feat: Hippocampus Memory System — Phases 1, 2, 3

[yhyu13]

feat: Hippocampus Memory System — Phases 1, 2, 3

Summary

Implements a complete neuroscience-inspired episodic/spatial memory system for OpenWolf, tracking file operations across sessions with valence detection, fast recall, and long-term consolidation.

7 commits | 12,221 lines added | 178 deleted

---

What Is This?

The hippocampus memory system addresses a fundamental gap in OpenWolf's intelligence:

Current OpenWolf (Before Hippocampus)
OpenWolf tracks what exists and what you told it:

anatomy.md — what files contain (static map)
cerebrum.md — what you corrected it to remember (explicit)
buglog.json — bugs you explicitly logged (manual)
memory.md — chronological log (flat, unindexed)
But it has no memory of what happened across sessions in a structured, queryable way.

Why Hippocampus Matters

1. Implicit Learning Without Explicit Corrections
   Cerebrum requires you to explicitly correct Claude. Hippocampus watches silently and learns from actions — file edited 8 times? That's trauma, worth remembering. No explicit correction needed.

2. Spatial Memory — "Where" vs "What"
   A log says "file X was edited." Hippocampus says "file X was edited 8 times by you across 3 sessions, always in src/auth/, the errors were TypeErrors about undefined properties." That's context-aware memory.

3. Automatic Problem Detection
   Files with high trauma scores are signals: "this code is problematic." Claude can use this to prioritize testing, be more careful with edits, or proactively suggest fixes.

4. Recall with Scoring
   Instead of grepping a flat memory.md, openwolf recall /src/ returns ranked results weighted by recency, intensity, and valence. Most relevant events surface first.

5. Token Savings
   When Claude knows "I already fixed this exact bug in this file 3 weeks ago" before starting work, it doesn't re-do the investigation. The cue-index makes this O(1) lookup instead of scanning.

6. Long-term Memory That Decays Like Real Memory
   5%/week decay for low-value events, trauma never decays. Important stuff persists, noise fades. This is how biological memory actually works.

The Analogy
Human Memory Hippocampus
Episodic memory hippocampus.json (who what when where)
Fast indexing (where did I put my keys?) cue-index.json (fast path lookup)
Consolidation during sleep neocortex.json (long-term storage)
Emotional intensity = better recall trauma valence = high intensity = important
Forgetting low-importance details 5%/week decay for neutral events
Bottom line: Without hippocampus, OpenWolf is a reactive tool that learns only when explicitly told. With it, OpenWolf becomes a proactive memory system that watches, indexes, recalls, and consolidates — like a real second brain.

---

What This Adds

Phase 1 — Hippocampus Core (✅ 98 tests)

• src/hippocampus/types.ts — WolfEvent, Valence, ConsolidationStage types
• src/hippocampus/index.ts — Hippocampus class with addEvent(), recall(), getTraumas()
• src/hippocampus/event-store.ts — hippocampus.json CRUD operations
• src/templates/hippocampus.json — Template for openwolf init
• Hook wiring: post-write (capture events), pre-read (trauma warnings)

Phase 2 — Recall System (✅ 109 tests)

• src/hippocampus/cue-index.ts — Fast lookup index (location_index, tag_index, trauma_index)
• src/hippocampus/cue-recall.ts — Scoring algorithm (location 55%, recency 20%, valence 15%, intensity 10%)
• src/cli/recall.ts — openwolf recall <path> CLI command
• Match modes: exact, prefix, glob, parent, sibling
• src/templates/cue-index.json — Template for cue-index

Phase 3 — Consolidation (✅ 37 tests)

• src/hippocampus/consolidation.ts — Neocortex transfer, decay logic, consolidation scoring
• src/templates/neocortex.json — Long-term memory template
• Decay: 5%/week for neutral/reward/penalty, trauma never decays
• Daemon wiring: hippocampus-consolidation cron task (daily 3 AM)

---

New Files

src/hippocampus/
├── index.ts              # Hippocampus class
├── types.ts              # Type definitions
├── event-store.ts        # hippocampus.json CRUD
├── cue-index.ts          # Cue index builder
├── cue-recall.ts         # Recall algorithm
└── consolidation.ts       # Neocortex + decay logic

src/cli/
└── recall.ts             # openwolf recall CLI

src/templates/
├── hippocampus.json      # Short-term store template
├── cue-index.json        # Cue index template
└── neocortex.json       # Long-term store template

docs2/
├── 00-hippocampus-memory-system.md
├── 01-event-model.md
├── 02-cue-system.md
├── 03-consolidation.md
├── 04-implementation-spec.md
├── 05-hook-integration.md
├── PLAN.md
├── phase1/test/ (T1-T8, 98 tests)
├── phase2/test/ (T9-T12, 109 tests)
├── phase3/test/ (T13-T16, 37 tests)
└── critic/ (critique docs)

---

New CLI Commands

# Recall events by file path
openwolf recall /path/to/file.ts

# Prefix match (all files under directory)
openwolf recall --match-mode prefix /path/to/src/

# JSON output
openwolf recall --json /path/to/file.ts

# State cue (error matching)
openwolf recall --type state --error "TypeError" /path/to/src/

---

Test Results

Suite	Tests	Status
T1-T8 Phase 1	98	✅ Pass
T9-T12 Phase 2	109	✅ Pass
T13-T16 Phase 3	37	✅ Pass
Total	244	✅ All pass

---

Known Defects (Documented)

• D3: Index batch-persist — cue-index.json persists every 10 events, not on every add
• D4: Parent match mode — exact key lookup instead of prefix matching

---

Breaking Changes

• None. Pure additive feature.

Backward Compatibility

• openwolf init creates new files alongside existing .wolf/ files
• Existing hooks remain functional

---

Test Plan

pnpm build
node docs2/phase1/test/T1_T2_build-init.sh
node docs2/phase1/test/T3_event-store.test.ts
node docs2/phase1/test/T4_hippocampus.test.ts
bash docs2/phase1/test/T5_T8_runtime.sh

node docs2/phase2/test/T9_cue-index.test.ts
node docs2/phase2/test/T10_recall.test.ts
bash docs2/phase2/test/T11_recall-cli.test.sh
bash docs2/phase2/test/T12_integration.test.sh

node docs2/phase3/test/T13_consolidation.test.ts
node docs2/phase3/test/T14_decay.test.ts
node docs2/phase3/test/T15_neocortex.test.ts
bash docs2/phase3/test/T16_integration.test.sh

---

Generated by Claude Code