hippocampus

Hippocampus Skill

"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 reinforcement.

Quick Start

# Install
./install.sh --with-cron

# Load core memories
./scripts/load-core.sh

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

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

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

CAPTURE → SCORE → STORE → DECAY/REINFORCE → RETRIEVE
   ↑                                            │
   └────────────────────────────────────────────┘

Memory Structure

$WORKSPACE/
├── memory/
│   ├── index.json           # Central weighted index
│   ├── 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
decay.sh	Apply 0.99^days decay to all memories
reinforce.sh	Boost importance when memory is used
recall.sh	Search with importance weighting
load-core.sh	Output high-importance memories
sync-core.sh	Generate HIPPOCAMPUS_CORE.md
preprocess.sh	Extract signals from transcripts

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

Reinforcement Formula

When a memory is accessed and useful:

new_importance = old + (1 - old) × 0.15

Each use adds ~15% of remaining headroom toward 1.0.

Thresholds

Score	Status
0.7+	Core — high priority
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",
  "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

Set up via OpenClaw cron:

# Daily decay at 3 AM
openclaw cron add --name hippocampus-decay \
  --cron "0 3 * * *" \
  --session main \
  --system-event "🧠 Run: WORKSPACE=\$WORKSPACE decay.sh"

# Weekly consolidation
openclaw cron add --name hippocampus-consolidate \
  --cron "0 21 * * 6" \
  --session main \
  --system-event "🧠 Weekly consolidation time"

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" --reinforce
\`\`\`

Capture Guidelines

What to Capture

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

Trigger Phrases

Auto-capture when you hear:

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

References

• Stanford Generative Agents Paper
• GitHub: joonspk-research/generative_agents

---

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