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

## 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.*