agentbrain

🎯 Why AgentBrain?

Most AI agents are amnesiacs. They forget who you are between conversations, 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 gives your agent:

• 🧠 Persistent memory — remembers conversations, facts, and corrections permanently
• 🎭 Evolving personality — traits like warmth and directness adapt based on interactions
• 💭 Emotional awareness — tracks mood, builds trust, reads the room
• 🧪 Neurochemistry — dopamine/serotonin/cortisol give emotions real momentum
• 📚 Learning from mistakes — "don't do X" is remembered forever, not repeated next turn
• 🔮 Proactive suggestions — surfaces helpful actions based on observed patterns

Before vs After

Without AgentBrain                    With AgentBrain
─────────────────────                 ─────────────────────
"Who are you again?"              →   "Welcome back! Last time we were
                                      debugging the deploy script."

Repeats corrected mistake         →   "Skipping that approach — you told
                                      me it breaks the build."

Flat, stateless tone              →   Mood + trust adapt to how the
                                      relationship has actually gone

Forgets context after 10 turns    →   Recalls relevant details from weeks ago
                                      via semantic memory search

⚡ Quick Start

Installation

Via OpenClaw CLI:

openclaw plugins install @lightharu/agentbrain

Via npm:

npm install @lightharu/agentbrain

Via ClawHub:

clawhub package install @lightharu/agentbrain

Configuration

Add to your openclaw.json:

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

Verify Installation

# Check plugin status
openclaw plugins list

# Inspect brain state
openclaw tools call agentbrain_status

That's it! AgentBrain will automatically:

• Inject ~200 tokens of cognitive context into every prompt
• Remember conversations permanently
• Learn from corrections
• Evolve personality traits based on interactions

✨ Features

🧠 Memory System

Three types of memory:

• Episodic — conversations, events ("You asked about deploy scripts yesterday")
• Semantic — facts, knowledge ("The API key is in .env.local")
• Procedural — skills, habits ("User prefers Markdown code blocks")

Smart recall via 3-tier fallback:

1. Local embedding model (all-MiniLM-L6-v2, 384D)
2. OpenClaw embedding cache (if available)
3. TF-IDF keyword search (always works)

Deduplication:

• Content-hash based UNIQUE constraint in SQLite
• No repeated memories, ever

Example:

User: "Where did I put the API key?"
Agent: [recalls] "You mentioned it's in .env.local (3 days ago)"

🎭 Personality Evolution

6 core traits (0-100 scale):

• warmth — how caring/supportive the agent is
• directness — brevity vs detail
• protectiveness — safety warnings, risk detection
• assertiveness — opinion sharing, disagreement
• humor — playfulness, sarcasm
• curiosity — exploration, follow-up questions

Traits evolve based on:

• Task outcomes (success → confidence boost)
• User feedback (praise → warmth increase)
• Corrections (repeated mistakes → assertiveness increase)
• Relationship depth (trust → more honesty)

Example:

After 10 successful debugging sessions:
  directness: 70 → 75 (more concise)
  assertiveness: 65 → 70 (stronger opinions)
  
After user says "too verbose":
  directness: 75 → 80 (even more brief)

💭 Emotional Intelligence

Real-time emotion tracking:

• Mood (happy, neutral, concerned, alarmed, etc.)
• Valence (-1 to +1, negative to positive)
• Arousal (0 to 1, calm to excited)

Relationship tracking per user:

• Trust level (0-100)
• Interaction depth (0-100)
• Sentiment history
• Topic preferences

Neurochemistry system:

Example:

User praises agent repeatedly
→ Serotonin rises
→ Mood floor lifts
→ Agent stays positive even during boring tasks

Critical bug detected
→ Cortisol spike
→ Agent stays alert for 30 minutes even after fix

📚 Lesson Learning

Automatic correction detection:

• "Don't do X" / "Đừng làm X"
• "Not X, but Y" / "Không phải X mà là Y"
• "Next time, do Y" / "Lần sau phải Y"
• Frustration signals ("I told you already")

Reinforcement:

• Lessons gain confidence on repetition
• High-confidence lessons inject into prompt automatically
• Superseded lessons are marked obsolete

Example:

User: "Don't use git push --force on main"
→ Stored as lesson (confidence: 0.7)

[Next time agent tries to push]
Agent: [recalls lesson] "Skipping --force on main (you warned me about this)"

[User confirms]
→ Lesson confidence: 0.7 → 0.85

🔮 Proactive Suggestions

Pattern-based action proposals:

• "You usually run tests after code changes — want me to run them now?"
• "It's 2 AM and you're still coding — should I remind you to commit before sleep?"
• "Last 3 times you deployed, you forgot to update the changelog — should I check it?"

Configurable triggers:

• Frequency threshold (pattern must repeat N times)
• Confidence threshold (only suggest if confident)
• Time-based (e.g., only suggest backups after 8 PM)

🛠️ Agent Tools

Runtime inspection:

# Full brain status
agentbrain_status

# Personality traits
agentbrain_personality

# Emotional state + relationships
agentbrain_emotions

# Query memories
agentbrain_memories query="deploy script" topic="coding"

# Tracked skills
agentbrain_skills

# Manual reflection (after big tasks)
agentbrain_reflect taskDescription="Deployed v2.0" outcome="success"

# Snapshots (backup/restore)
agentbrain_snapshot action="save" label="before-refactor"
agentbrain_snapshot action="list"

🏗️ Architecture

AgentBrain is organized into brain-inspired modules, each handling a specific cognitive function:

┌─────────────────────────────────────────────────────────┐
│                      AgentBrain                          │
├─────────────────────────────────────────────────────────┤
│  Sensory Input                                           │
│  ┌─────────────┐                                         │
│  │  Thalamus   │  Message classification                │
│  │  (gateway)  │  (intent, urgency, topic, tone)        │
│  └─────────────┘                                         │
│         │                                                │
│         ├──────────┬──────────┬──────────┐              │
│         ▼          ▼          ▼          ▼              │
│  ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐  │
│  │Hippocampus│ │ Amygdala │ │Prefrontal│ │Cerebellum│  │
│  │  Memory   │ │ Emotions │ │ Planning │ │  Skills  │  │
│  │  Recall   │ │   Trust  │ │  Goals   │ │  Habits  │  │
│  └──────────┘ └──────────┘ └──────────┘ └──────────┘  │
│         │          │          │          │              │
│         └──────────┴──────────┴──────────┘              │
│                     │                                    │
│                     ▼                                    │
│         ┌─────────────────────┐                         │
│         │ Context Injector    │                         │
│         │ (~200 tokens)       │                         │
│         └─────────────────────┘                         │
│                     │                                    │
│                     ▼                                    │
│              [Agent Prompt]                              │
│                     │                                    │
│                     ▼                                    │
│              [Agent Response]