{"skill":{"slug":"hippocampus-memory","displayName":"Hippocampus","summary":"Persistent memory system for AI agents. Automatic encoding, decay, and semantic reinforcement — just like the hippocampus in your brain. Based on Stanford Generative Agents (Park et al., 2023).","description":"---\nname: hippocampus-memory\ntitle: \"Hippocampus - Memory System\"\ndescription: \"Persistent memory system for AI agents. Automatic encoding, decay, and semantic reinforcement — just like the hippocampus in your brain. Based on Stanford Generative Agents (Park et al., 2023).\"\nmetadata:\n  openclaw:\n    emoji: \"🧠\"\n    version: \"3.8.6\"\n    author: \"Community\"\n    repo: \"https://github.com/ImpKind/hippocampus-skill\"\n    requires:\n      bins: [\"python3\", \"jq\"]\n    install:\n      - id: \"manual\"\n        kind: \"manual\"\n        label: \"Run install.sh\"\n        instructions: \"./install.sh --with-cron\"\n---\n\n# Hippocampus - Memory System\n\n> \"Memory is identity. This skill is how I stay alive.\"\n\nThe 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.\n\n## Quick Start\n\n```bash\n# Install (defaults to last 100 signals)\n./install.sh --with-cron\n\n# Load core memories at session start\n./scripts/load-core.sh\n\n# Search with importance weighting\n./scripts/recall.sh \"query\"\n\n# Run encoding manually (usually via cron)\n./scripts/encode-pipeline.sh\n\n# Apply decay (runs daily via cron)\n./scripts/decay.sh\n```\n\n## Install Options\n\n```bash\n./install.sh                    # Basic, last 100 signals\n./install.sh --signals 50       # Custom signal limit\n./install.sh --whole            # Process entire conversation history\n./install.sh --with-cron        # Also set up cron jobs\n```\n\n## Core Concept\n\nThe 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.\n\n### Memory Lifecycle\n\n```\nPREPROCESS → SCORE → SEMANTIC CHECK → REINFORCE or CREATE → DECAY\n```\n\n**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.\n\n## Memory Structure\n\n```\n$WORKSPACE/\n├── memory/\n│   ├── index.json           # Central weighted index\n│   ├── signals.jsonl        # Raw signals (temp)\n│   ├── pending-memories.json # Awaiting summarization (temp)\n│   ├── user/                # Facts about the user\n│   ├── self/                # Facts about the agent\n│   ├── relationship/        # Shared context\n│   └── world/               # External knowledge\n└── HIPPOCAMPUS_CORE.md      # Auto-generated for OpenClaw RAG\n```\n\n## Scripts\n\n| Script | Purpose |\n|--------|---------|\n| `preprocess.sh` | Extract signals from conversation transcripts |\n| `encode-pipeline.sh` | Score signals, prepare for LLM summarization |\n| `decay.sh` | Apply 0.99^days decay to all memories |\n| `recall.sh` | Search with importance weighting |\n| `load-core.sh` | Output high-importance memories for session start |\n| `sync-core.sh` | Generate HIPPOCAMPUS_CORE.md |\n| `consolidate.sh` | Weekly review helper |\n| `reflect.sh` | Self-reflection prompts |\n| `generate-dashboard.sh` | Generate unified brain dashboard HTML |\n\n## Brain Dashboard\n\nVisual dashboard showing all installed brain skills:\n\n```bash\n./scripts/generate-dashboard.sh\nopen ~/.openclaw/workspace/brain-dashboard.html\n```\n\n- **Auto-detects** other brain skills (amygdala, VTA)\n- Shows install prompts for missing skills\n- Regenerates on install and cron runs\n- Reads avatar/name from `IDENTITY.md`\n\n### After Installation (for agents)\n\nWhen you install this skill, **notify the user** about the dashboard:\n\n> 🧠 **Hippocampus installed!** \n> \n> View your agent's memories in the Brain Dashboard:\n> `~/.openclaw/workspace/brain-dashboard.html`\n\nAll scripts use `$WORKSPACE` environment variable (default: `~/.openclaw/workspace`).\n\n## Importance Scoring\n\n### Initial Score (0.0-1.0)\n\n| Signal | Score |\n|--------|-------|\n| Explicit \"remember this\" | 0.9 |\n| Emotional/vulnerable content | 0.85 |\n| Preferences (\"I prefer...\") | 0.8 |\n| Decisions made | 0.75 |\n| Facts about people/projects | 0.7 |\n| General knowledge | 0.5 |\n\n### Decay Formula\n\nBased on Stanford Generative Agents (Park et al., 2023):\n\n```\nnew_importance = importance × (0.99 ^ days_since_accessed)\n```\n\n- After 7 days: 93% of original\n- After 30 days: 74% of original\n- After 90 days: 40% of original\n\n### Semantic Reinforcement\n\nDuring encoding, the LLM compares new signals to existing memories:\n- **Same topic?** → Reinforce (bump importance ~10%, update lastAccessed)\n- **Truly new?** → Create concise summary\n\nThis happens automatically—no manual reinforcement needed.\n\n### Thresholds\n\n| Score | Status |\n|-------|--------|\n| 0.7+ | **Core** — loaded at session start |\n| 0.4-0.7 | **Active** — normal retrieval |\n| 0.2-0.4 | **Background** — specific search only |\n| <0.2 | **Archive candidate** |\n\n## Memory Index Schema\n\n`memory/index.json`:\n\n```json\n{\n  \"version\": 1,\n  \"lastUpdated\": \"2025-01-20T19:00:00Z\",\n  \"decayLastRun\": \"2025-01-20\",\n  \"lastProcessedMessageId\": \"abc123\",\n  \"memories\": [\n    {\n      \"id\": \"mem_001\",\n      \"domain\": \"user\",\n      \"category\": \"preferences\",\n      \"content\": \"User prefers concise responses\",\n      \"importance\": 0.85,\n      \"created\": \"2025-01-15\",\n      \"lastAccessed\": \"2025-01-20\",\n      \"timesReinforced\": 3,\n      \"keywords\": [\"preference\", \"concise\", \"style\"]\n    }\n  ]\n}\n```\n\n## Cron Jobs\n\nThe encoding cron is the heart of the system:\n\n```bash\n# Encoding every 3 hours (with semantic reinforcement)\nopenclaw cron add --name hippocampus-encoding \\\n  --cron \"0 0,3,6,9,12,15,18,21 * * *\" \\\n  --session isolated \\\n  --agent-turn \"Run hippocampus encoding with semantic reinforcement...\"\n\n# Daily decay at 3 AM\nopenclaw cron add --name hippocampus-decay \\\n  --cron \"0 3 * * *\" \\\n  --session isolated \\\n  --agent-turn \"Run decay.sh and report any memories below 0.2\"\n```\n\n## OpenClaw Integration\n\nAdd to `memorySearch.extraPaths` in openclaw.json:\n\n```json\n{\n  \"agents\": {\n    \"defaults\": {\n      \"memorySearch\": {\n        \"extraPaths\": [\"HIPPOCAMPUS_CORE.md\"]\n      }\n    }\n  }\n}\n```\n\nThis bridges hippocampus (index.json) with OpenClaw's RAG (memory_search).\n\n## Usage in AGENTS.md\n\nAdd to your agent's session start routine:\n\n```markdown\n## Every Session\n1. Run `~/.openclaw/workspace/skills/hippocampus/scripts/load-core.sh`\n\n## When answering context questions\nUse hippocampus recall:\n\\`\\`\\`bash\n./scripts/recall.sh \"query\"\n\\`\\`\\`\n```\n\n## Capture Guidelines\n\n### What Gets Captured\n\n- **User facts**: Preferences, patterns, context\n- **Self facts**: Identity, growth, opinions\n- **Relationship**: Trust moments, shared history\n- **World**: Projects, people, tools\n\n### Trigger Phrases (auto-scored higher)\n\n- \"Remember that...\"\n- \"I prefer...\", \"I always...\"\n- Emotional content (struggles AND wins)\n- Decisions made\n\n## AI Brain Series\n\nThis skill is part of the **AI Brain** project — giving AI agents human-like cognitive components.\n\n| Part | Function | Status |\n|------|----------|--------|\n| **hippocampus** | Memory formation, decay, reinforcement | ✅ Live |\n| [amygdala-memory](https://www.clawhub.ai/skills/amygdala-memory) | Emotional processing | ✅ Live |\n| [vta-memory](https://www.clawhub.ai/skills/vta-memory) | Reward and motivation | ✅ Live |\n| basal-ganglia-memory | Habit formation | 🚧 Development |\n| anterior-cingulate-memory | Conflict detection | 🚧 Development |\n| insula-memory | Internal state awareness | 🚧 Development |\n\n## References\n\n- [Stanford Generative Agents Paper](https://arxiv.org/abs/2304.03442)\n- [GitHub: joonspk-research/generative_agents](https://github.com/joonspk-research/generative_agents)\n\n---\n\n*Memory is identity. Text > Brain. If you don't write it down, you lose it.*\n","tags":{"latest":"3.8.6"},"stats":{"comments":2,"downloads":6179,"installsAllTime":26,"installsCurrent":26,"stars":24,"versions":10},"createdAt":1769896469487,"updatedAt":1779076551570},"latestVersion":{"version":"3.8.6","createdAt":1770323640353,"changelog":"- Skill name updated to \"hippocampus-memory\" and title clarified.\n- Description rewritten for clarity and conciseness.\n- Metadata version bumped to 3.8.6.\n- Documentation restructured for easier reading; headings clarified and formatting improved.\n- No changes to scripts, features, or usage—documentation improvements only.","license":null},"metadata":{"setup":[],"os":null,"systems":null},"owner":{"handle":"impkind","userId":"s17a6jgq93ckexmb6qdvze637s84538n","displayName":"ImpKind","image":"https://avatars.githubusercontent.com/u/54905270?v=4"},"moderation":{"isSuspicious":false,"isMalwareBlocked":false,"verdict":"clean","reasonCodes":["review.llm_review"],"summary":"Review: review.llm_review","engineVersion":"v2.4.24","updatedAt":1779922109183}}