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`:

```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.