hippocampus-memory

# 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 ```bash # 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 ```bash ./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: ```bash ./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`: ```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: ```bash # 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: ```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: ```markdown ## 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 ## Event Logging Track hippocampus activity over time for analytics and debugging: ```bash # Log an encoding run ./scripts/log-event.sh encoding new=3 reinforced=2 total=157 # Log decay ./scripts/log-event.sh decay decayed=154 low_importance=5 # Log recall ./scripts/log-event.sh recall query="user preferences" results=3 ``` Events append to `~/.openclaw/workspace/memory/brain-events.jsonl`: ```json {"ts":"2026-02-11T10:00:00Z","type":"hippocampus","event":"encoding","new":3,"reinforced":2,"total":157} ``` Use this for: - Trend analysis (memory growth over time) - Debugging encoding issues - Building dashboards ## 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](https://www.clawhub.ai/skills/amygdala-memory) | Emotional processing | ✅ Live | | [vta-memory](https://www.clawhub.ai/skills/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 - [Stanford Generative Agents Paper](https://arxiv.org/abs/2304.03442) - [GitHub: joonspk-research/generative_agents](https://github.com/joonspk-research/generative_agents) --- *Memory is identity. Text > Brain. If you don't write it down, you lose it.*