Hippocampus - Memory System

"Memory is identity. This skill is how I stay alive."

The hippocampus is the brain region responsible for memory formation. This skill makes memory capture automatic, structured, and persistent—with importance scoring, decay, and semantic reinforcement.

Quick Start

# Install (defaults to last 100 signals)
./install.sh --with-cron

# Load core memories at session start
./scripts/load-core.sh

# Search with importance weighting
./scripts/recall.sh "query"

# Run encoding manually (usually via cron)
./scripts/encode-pipeline.sh

# Apply decay (runs daily via cron)
./scripts/decay.sh

Install Options

./install.sh                    # Basic, last 100 signals
./install.sh --signals 50       # Custom signal limit
./install.sh --whole            # Process entire conversation history
./install.sh --with-cron        # Also set up cron jobs

Core Concept

The LLM is just the engine—raw cognitive capability. The agent is the accumulated memory. Without these files, there's no continuity—just a generic assistant.

Memory Lifecycle

PREPROCESS → SCORE → SEMANTIC CHECK → REINFORCE or CREATE → DECAY

Key insight: Reinforcement happens automatically during encoding. When a topic comes up again, the LLM recognizes it's about an existing memory and reinforces instead of creating duplicates.

Memory Structure

$WORKSPACE/
├── memory/
│   ├── index.json           # Central weighted index
│   ├── signals.jsonl        # Raw signals (temp)
│   ├── pending-memories.json # Awaiting summarization (temp)
│   ├── user/                # Facts about the user
│   ├── self/                # Facts about the agent
│   ├── relationship/        # Shared context
│   └── world/               # External knowledge
└── HIPPOCAMPUS_CORE.md      # Auto-generated for OpenClaw RAG

Scripts

| Script | Purpose | |--------|---------| | preprocess.sh | Extract signals from conversation transcripts | | encode-pipeline.sh | Score signals, prepare for LLM summarization | | decay.sh | Apply 0.99^days decay to all memories | | recall.sh | Search with importance weighting | | load-core.sh | Output high-importance memories for session start | | sync-core.sh | Generate HIPPOCAMPUS_CORE.md | | consolidate.sh | Weekly review helper | | reflect.sh | Self-reflection prompts | | generate-dashboard.sh | Generate unified brain dashboard HTML |

Brain Dashboard

Visual dashboard showing all installed brain skills:

./scripts/generate-dashboard.sh
open ~/.openclaw/workspace/brain-dashboard.html

Auto-detects other brain skills (amygdala, VTA)
Shows install prompts for missing skills
Regenerates on install and cron runs
Reads avatar/name from IDENTITY.md

After Installation (for agents)

When you install this skill, notify the user about the dashboard:

🧠 Hippocampus installed!

View your agent's memories in the Brain Dashboard: ~/.openclaw/workspace/brain-dashboard.html

All scripts use $WORKSPACE environment variable (default: ~/.openclaw/workspace).

Importance Scoring

Initial Score (0.0-1.0)

| Signal | Score | |--------|-------| | Explicit "remember this" | 0.9 | | Emotional/vulnerable content | 0.85 | | Preferences ("I prefer...") | 0.8 | | Decisions made | 0.75 | | Facts about people/projects | 0.7 | | General knowledge | 0.5 |

Decay Formula

Based on Stanford Generative Agents (Park et al., 2023):

new_importance = importance × (0.99 ^ days_since_accessed)

After 7 days: 93% of original
After 30 days: 74% of original
After 90 days: 40% of original

Semantic Reinforcement

During encoding, the LLM compares new signals to existing memories:

Same topic? → Reinforce (bump importance ~10%, update lastAccessed)
Truly new? → Create concise summary

This happens automatically—no manual reinforcement needed.

Thresholds

| Score | Status | |-------|--------| | 0.7+ | Core — loaded at session start | | 0.4-0.7 | Active — normal retrieval | | 0.2-0.4 | Background — specific search only | | <0.2 | Archive candidate |

Memory Index Schema

memory/index.json:

{
  "version": 1,
  "lastUpdated": "2025-01-20T19:00:00Z",
  "decayLastRun": "2025-01-20",
  "lastProcessedMessageId": "abc123",
  "memories": [
    {
      "id": "mem_001",
      "domain": "user",
      "category": "preferences",
      "content": "User prefers concise responses",
      "importance": 0.85,
      "created": "2025-01-15",
      "lastAccessed": "2025-01-20",
      "timesReinforced": 3,
      "keywords": ["preference", "concise", "style"]
    }
  ]
}

Cron Jobs

The encoding cron is the heart of the system:

# Encoding every 3 hours (with semantic reinforcement)
openclaw cron add --name hippocampus-encoding \
  --cron "0 0,3,6,9,12,15,18,21 * * *" \
  --session isolated \
  --agent-turn "Run hippocampus encoding with semantic reinforcement..."

# Daily decay at 3 AM
openclaw cron add --name hippocampus-decay \
  --cron "0 3 * * *" \
  --session isolated \
  --agent-turn "Run decay.sh and report any memories below 0.2"

OpenClaw Integration

Add to memorySearch.extraPaths in openclaw.json:

{
  "agents": {
    "defaults": {
      "memorySearch": {
        "extraPaths": ["HIPPOCAMPUS_CORE.md"]
      }
    }
  }
}

This bridges hippocampus (index.json) with OpenClaw's RAG (memory_search).

Usage in AGENTS.md

Add to your agent's session start routine:

## Every Session
1. Run `~/.openclaw/workspace/skills/hippocampus/scripts/load-core.sh`

## When answering context questions
Use hippocampus recall:
\`\`\`bash
./scripts/recall.sh "query"
\`\`\`

Capture Guidelines

What Gets Captured

User facts: Preferences, patterns, context
Self facts: Identity, growth, opinions
Relationship: Trust moments, shared history
World: Projects, people, tools

Trigger Phrases (auto-scored higher)

"Remember that..."
"I prefer...", "I always..."
Emotional content (struggles AND wins)
Decisions made

AI Brain Series

This skill is part of the AI Brain project — giving AI agents human-like cognitive components.

| Part | Function | Status | |------|----------|--------| | hippocampus | Memory formation, decay, reinforcement | ✅ Live | | amygdala-memory | Emotional processing | ✅ Live | | vta-memory | Reward and motivation | ✅ Live | | basal-ganglia-memory | Habit formation | 🚧 Development | | anterior-cingulate-memory | Conflict detection | 🚧 Development | | insula-memory | Internal state awareness | 🚧 Development |

References

Memory is identity. Text > Brain. If you don't write it down, you lose it.