Tools

Agentbrain

Name: Agentbrain
Rating: 3.5 (1 reviews)
Author: KLSGG

By KLSGG ⭐ 1 stars 👁 15 views ▲ 0 votes

🧠 Brain-inspired cognitive architecture plugin for AI agents — persistent memory, evolving personality, neurochemistry-driven mood, learning from mistakes. Fully local on OpenClaw.

Homepage GitHub

Install

npm install

#

Configuration Example

{
  "plugins": {
    "entries": {
      "agentbrain": {
        "enabled": true,
        "config": {
          "brainDir": "~/.openclaw/data/agentbrain",
          "maxRecallResults": 10,
          "maxInjectionTokens": 250,
          "enableReflection": true,
          "enableEmotions": true,
          "enableSkillTracking": true
        }
      }
    }
  }
}

README

<p align="center">
  <img src="docs/assets/banner.png" alt="AgentBrain — brain-inspired cognitive architecture for AI agents" width="100%">
</p>

# 🧠 AgentBrain

> **Give your AI agent a brain.** Persistent memory, a personality that evolves, neurochemistry-driven moods, and the ability to learn from its mistakes — all running locally, with zero extra token cost.

[![Version](https://img.shields.io/badge/version-0.5.0-blue)]()
[![Storage](https://img.shields.io/badge/storage-SQLite-orange)]()
[![TypeScript](https://img.shields.io/badge/TypeScript-5.5+-blue)]()
[![License](https://img.shields.io/badge/license-MIT-green)]()

---

## Why AgentBrain?

Most AI agents are amnesiacs. Every conversation starts from zero — they forget who you are, repeat mistakes you already corrected, and respond with the same flat tone whether you just shipped a release or lost a week of work.

AgentBrain fixes that. It sits between the incoming message and your agent, quietly doing what a brain does: recalling what matters, reading the emotional context, learning from corrections, and shaping how the agent responds — then injecting a compact (~200 token) cognitive briefing into the prompt.

```text
Without AgentBrain          With AgentBrain
──────────────────          ──────────────────
"Who are you again?"    →    "Welcome back — last time we were
                              debugging the deploy script."
repeats corrected bug   →    "Skipping that approach, you told me
                              it breaks the build."
flat, stateless tone    →    mood + trust adapt to how the
                              relationship has actually gone
```

---

## Overview

AgentBrain is a plugin for [OpenClaw](https://openclaw.ai) that gives any agent real cognitive continuity:

- **Persistent memory** — episodic, semantic, and procedural recall via semantic vector search
- **Evolving personality** — traits like warmth and directness shift based on how interactions go
- **Emotional awareness** — tracks mood, trust, and relationship depth over time
- **Neurochemistry** — dopamine / serotonin / cortisol / oxytocin give mood real momentum instead of resetting every turn
- **Learning from corrections** — remembers "don't do X" permanently, so mistakes aren't repeated
- **Proactive behavior** — surfaces suggestions based on patterns it has observed
- **Structured knowledge** — extracts facts, entities, and relationships into a queryable graph

Everything runs locally on SQLite. No external API calls, no added token cost beyond the small in-prompt briefing.

---

## Quick Start

### Installation

```bash
openclaw plugins install agentbrain
```

### Configuration

Add to your `openclaw.json`:

```json
{
  "plugins": {
    "entries": {
      "agentbrain": {
        "enabled": true,
        "config": {
          "brainDir": "~/.openclaw/data/agentbrain",
          "maxRecallResults": 10,
          "maxInjectionTokens": 250,
          "enableReflection": true,
          "enableEmotions": true,
          "enableSkillTracking": true
        }
      }
    }
  }
}
```

That's it. AgentBrain hooks into OpenClaw's plugin lifecycle automatically.

---

## How It Works

AgentBrain registers three hooks in OpenClaw:

| Hook | What it does |
|------|-------------|
| `before_prompt_build` | Recalls relevant memories, generates style directives, injects ~200 tokens of brain context |
| `message_received` | Classifies message, processes emotion, detects skills |
| `message_sent` | Consolidates memory, extracts knowledge, detects corrections, tracks rewards |

### On every incoming message:

1. **Classify** — intent, urgency, topic, tone
2. **Recall** — find relevant memories via embedding similarity (3-tier: local model → cache → TF-IDF)
3. **Emotion** — update mood, detect sentiment, track relationship
4. **Lessons** — check if past corrections apply to this context
5. **Style** — generate personality-driven directives (e.g., "be direct", "warn about risks")
6. **Inject** — append brain context to the agent's prompt (~200 tokens)

### After every response:

1. **Consolidate** — store new memories (deduplicated by content hash)
2. **Extract** — structured facts and entities from the conversation
3. **Learn** — detect if user corrected the agent, store as lesson
4. **Reflect** — evaluate task outcome, adjust personality traits
5. **Persist** — write all state to SQLite

---

## Architecture

AgentBrain is organized into modules inspired by neuroscience:

```mermaid
flowchart TB
    IN([Incoming message]) --> THAL[Thalamus<br/>classify]
    THAL --> HIP[Hippocampus<br/>recall memory]
    THAL --> AMY[Amygdala<br/>emotion + threat]
    AMY <--> NEU[Neurochemistry<br/>DA / 5HT / COR / OXT]
    HIP --> PFC[Prefrontal<br/>planning]
    AMY --> STYLE[PersonalityInfluence<br/>style directives]
    PFC --> STYLE
    STYLE --> INJ[[Inject ~200 tokens<br/>into agent prompt]]
    INJ --> OUT([Agent responds])
    OUT --> CONS[Hippocampus<br/>consolidate]
    OUT --> KNOW[KnowledgeExtractor<br/>facts + entities]
    OUT --> LESS[LessonLearner<br/>corrections]
    OUT --> REFL[Cingulate<br/>reflect + evolve traits]
    CONS & KNOW & LESS & REFL --> DB[(SQLite brain.db)]
```

<details>
<summary>Module map (ASCII)</summary>

┌─────────────────────────────────────────────────────────┐
│                      AgentBrain                           │
├─────────────────────────────────────────────────────────┤
│                                                          │
│  Core Cognition                                          │
│  ┌───────────┐ ┌───────────┐ ┌───────────┐             │
│  │Hippocampus│ │Prefrontal │ │ Amygdala  │             │
│  │  Memory   │ │ Planning  │ │ Emotions  │             │
│  └───────────┘ └───────────┘ └───────────┘             │
│  ┌───────────┐ ┌───────────┐ ┌───────────┐             │
│  │Cerebellum │ │  Basal    │ │ Cingulate │             │
│  │  Skills   │ │ Ganglia   │ │Reflection │             │
│  └───────────┘ └───────────┘ └───────────┘             │
│                                                          │
│  Smart Modules (v0.3+)                                   │
│  ┌───────────┐ ┌───────────┐ ┌───────────┐             │
│  │  Vector   │ │ Knowledge │ │  Lesson   │             │
│  │  Memory   │ │ Extractor │ │  Learner  │             │
│  └───────────┘ └───────────┘ └───────────┘             │
│  ┌───────────┐ ┌───────────┐ ┌───────────┐             │
│  │Personality│ │ Proactive │ │ Embedding │             │
│  │ Influence │ │  Engine   │ │  Engine   │             │
│  └───────────┘ └───────────┘ └───────────┘             │
│                                                          │
│  Storage: SQLite (brain.db)                              │
│  ┌─────────────────────────────────────────────┐        │
│  │ memories │ facts │ entities │ lessons │ ...  │        │
│  └─────────────────────────────────────────────┘        │
│                                                          │
└─────────────────────────────────────────────────────────┘
```

</details>


### Module Reference

| Module | Purpose |
|--------|---------|
| **Thalamus** | Message classification (intent, urgency, topic) |
| **Hippocampus** | Memory formation, deduplication, vector recall |
| **Amygdala** | Emotion processing, threat detection, relationship tracking |
| **Prefrontal Cortex** | Planning, working memory, goal management |
| **Cerebellum** | Skill proficiency tracking, habit detection |
| **Basal Ganglia** | Reward processing, motivation ranking |
| **Anterior Cingulate** | Self-reflection, personality trait evolution |
| **Temporal Lobe** | Language comprehension, semantic extraction |
| **Parietal Lobe** | Attention allocation, sensory integration |
| **Insula** | User state modeling (frustration, satisfaction) |
| **Neurochemistry** | Dopamine/serotonin/cortisol/oxytocin modulate mood with momentum + amygdala hijack on threats |
| **VectorMemory** | Embedding-based semantic recall with 3-tier fallback |
| **EmbeddingEngine** | Local embeddings via Transformers.js (all-MiniLM-L6-v2) |
| **KnowledgeExtractor** | Structured fact/entity extraction with supersession |
| **LessonLearner** | Correction detection, lesson storage, reinforcement |
| **PersonalityInfluence** | Trait-to-directive translation, context-aware styling |
| **ProactiveEngine** | Pattern-based action suggestions |

---

## Storage

All state lives in a single SQLite file (`brain.db`):

| Table | Purpose |
|-------|---------|
| `memories` | Episodic, semantic, procedural memories (UNIQUE on content hash) |
| `facts` | Structured knowledge (subject → relation → object) |
| `entities` | Extracted entities (people, tools, addresses) |
| `lessons` | Learned corrections with confidence scores |
| `patterns` | Behavioral patterns for proactive suggestions |
| `relationships` | Per-user trust, depth, interaction history |
| `personality` | Evolving trait values |
| `reflections` | Task outcomes and self-assessments |
| `skills` | Proficiency tracking per skill category |

### Why SQLite?

- **No duplicates** — UNIQUE constraints at the database level
- **Fast queries** — indexed columns, no regex parsing
- **Atomic writes** — no corrupted half-written files
- **Single file** — easy backup, easy migration
- **Zero config** — no external database server needed

---

## Memory Recall

AgentBrain uses a 3-tier fallback for memory retrieval:

1. **Transformers.js** — local `all-MiniLM-L6-v2` model (384 dims, ~22MB, downloads on first use)
2. **OpenClaw embedding cache** — reuses host's cached embeddings if available
3. **TF-IDF** — lightweight keyword-based fallback when embeddings unavailable

Recall is boosted by:
- Recency (recently accessed memories score higher)
- Confidence (high-confidence memories prioritized)
- Topic match (memories tagged with current topic get a boost)

---

## Personality System

Traits are defined on a 0-100 scale and evolve based on interactions:

| Trait | Effect on outp

... (truncated)

tools