vestige/CLAUDE.md

# Vestige v1.5.0 — Cognitive Memory System

Vestige is your long-term memory. It implements real neuroscience: FSRS-6 spaced repetition, synaptic tagging, prediction error gating, hippocampal indexing, spreading activation, and 28 stateful cognitive modules. **Use it automatically.**

---

## Session Start Protocol

Every conversation, before responding to the user:

```
1. search("user preferences instructions")     → recall who the user is
2. search("[current project] context")          → recall project patterns/decisions
3. intention → check (with current context)     → check for triggered reminders
4. codebase → get_context (if coding)           → load patterns and decisions
```

Say "Remembering..." then retrieve context before answering.

---

## The 23 Tools

### Core Memory (2 tools)
| Tool | When to Use |
|------|-------------|
| `ingest` | Store facts, concepts, events. Raw insertion, no dedup. |
| `smart_ingest` | **Default for all saves.** Uses Prediction Error Gating to auto-decide: create, update, reinforce, or supersede. Runs cognitive pipeline (4-channel importance scoring, intent detection, synaptic tagging, hippocampal indexing). |

### Unified Tools (4 tools)
| Tool | Actions | When to Use |
|------|---------|-------------|
| `search` | query + filters | **Every time you need to recall anything.** Hybrid search (BM25 + semantic + RRF fusion). 7-stage pipeline: overfetch → rerank → temporal boost → accessibility filter → context match → competition → spreading activation. Searching strengthens memory (Testing Effect). |
| `memory` | get, delete, state | Retrieve a full memory by ID, delete a memory, or check its cognitive state (Active/Dormant/Silent/Unavailable). |
| `codebase` | remember_pattern, remember_decision, get_context | Store and recall code patterns, architectural decisions, and project context. The killer differentiator. |
| `intention` | set, check, update, list | Prospective memory — "remember to do X when Y happens". Supports time, context, and event triggers. |

### Feedback (2 tools)
| Tool | When to Use |
|------|-------------|
| `promote_memory` | User confirms a memory was helpful or correct. Increases retrieval strength + triggers reward signal + reconsolidation. |
| `demote_memory` | User says a memory was wrong or unhelpful. Decreases retrieval strength + updates competition model. Does NOT delete. |

### Temporal (2 tools)
| Tool | When to Use |
|------|-------------|
| `memory_timeline` | Browse memories chronologically. Grouped by day. Filter by type, tags, date range. Detail levels: brief/summary/full. |
| `memory_changelog` | Audit trail. Per-memory: state transitions. System-wide: consolidations + recent changes. |

### Cognitive (3 tools) — v1.5.0
| Tool | When to Use |
|------|-------------|
| `dream` | Trigger memory consolidation — replays recent memories to discover hidden connections and synthesize insights. Like sleep for AI. |
| `explore_connections` | Graph exploration. Actions: `chain` (reasoning path A→B), `associations` (spreading activation from a node), `bridges` (connecting memories between two nodes). |
| `predict` | Proactive retrieval — predicts what memories you'll need next based on context, activity patterns, and learned behavior. |

### Auto-Save & Dedup (3 tools)
| Tool | When to Use |
|------|-------------|
| `importance_score` | Score content importance before deciding whether to save. 4-channel model: novelty, arousal, reward, attention. Composite > 0.6 = worth saving. |
| `session_checkpoint` | **Batch save up to 20 items in one call.** Each routes through Prediction Error Gating. Use at session end or before context compaction. |
| `find_duplicates` | Find near-duplicate memory clusters via cosine similarity. Returns merge/review suggestions. Run when memory count > 700 or on user request. |

### Maintenance (6 tools)
| Tool | When to Use |
|------|-------------|
| `health_check` | System status: healthy/degraded/critical/empty. Actionable recommendations. |
| `consolidate` | Run FSRS-6 consolidation cycle. Applies decay, generates embeddings, maintenance. Use when memories seem stale. |
| `stats` | Full statistics: total count, retention distribution, embedding coverage, cognitive state breakdown. |
| `backup` | Create SQLite database backup. Returns file path. |
| `export` | Export memories as JSON/JSONL with tag and date filters. |
| `gc` | Garbage collect low-retention memories. Defaults to dry_run=true for safety. |

### Restore (1 tool)
| Tool | When to Use |
|------|-------------|
| `restore` | Restore memories from a JSON backup file. Supports MCP wrapper, RecallResult, and direct array formats. |

---

## Mandatory Save Gates

**RULE: You MUST NOT proceed past a save gate without executing the save.**

### BUG_FIX — After any error is resolved
Your next tool call after confirming a fix MUST be `smart_ingest`:
```
smart_ingest({
  content: "BUG FIX: [exact error]\nRoot cause: [why]\nSolution: [what fixed it]\nFiles: [paths]",
  tags: ["bug-fix", "[project]"], node_type: "fact"
})
```

### DECISION — After any architectural or design choice
```
codebase({
  action: "remember_decision",
  decision: "[what]", rationale: "[why]",
  alternatives: ["[A]", "[B]"], files: ["[affected]"], codebase: "[project]"
})
```

### CODE_CHANGE — After writing significant code (>20 lines or new pattern)
```
codebase({
  action: "remember_pattern",
  name: "[pattern]", description: "[how/when to use]",
  files: ["[files]"], codebase: "[project]"
})
```

### SESSION_END — Before stopping or compaction
```
session_checkpoint({
  items: [
    { content: "SESSION: [work done]\nFixes: [list]\nDecisions: [list]", tags: ["session-end", "[project]"] },
    // ... any unsaved fixes, decisions, patterns
  ]
})
```

---

## Trigger Words — Auto-Save

| User Says | Action |
|-----------|--------|
| "Remember this" / "Don't forget" | `smart_ingest` immediately |
| "I always..." / "I never..." / "I prefer..." | Save as preference |
| "This is important" | `smart_ingest` + `promote_memory` |
| "Remind me..." / "Next time..." | `intention` → set |

---

## Under the Hood — Cognitive Pipelines

### Search Pipeline (7 stages)
1. **Overfetch** — Pull 3x results from hybrid search (BM25 + semantic)
2. **Reranker** — Re-score by relevance quality
3. **Temporal boost** — Recent memories get recency bonus
4. **Accessibility filter** — FSRS-6 retention threshold (Ebbinghaus curve)
5. **Context match** — Tulving 1973 encoding specificity (match current context to encoding context)
6. **Competition** — Anderson 1994 retrieval-induced forgetting (winners strengthen, competitors weaken)
7. **Spreading activation** — Side effects: activate related memories, update predictive model, record reconsolidation opportunity

### Ingest Pipeline (cognitive pre/post)
**Pre-ingest:** 4-channel importance scoring (novelty/arousal/reward/attention) + intent detection → auto-tag
**Storage:** Prediction Error Gating decides create/update/reinforce/supersede
**Post-ingest:** Synaptic tagging (Frey & Morris 1997) + novelty model update + hippocampal indexing + cross-project recording

### Feedback Pipeline
**Promote:** Reward signal + importance boost + reconsolidation (memory becomes modifiable for 24-48h) + activation spread
**Demote:** Competition suppression + retrieval strength decrease (does NOT delete — alternatives surface instead)

---

## CognitiveEngine — 28 Modules

All modules persist across tool calls as stateful instances:

**Neuroscience (15):** ActivationNetwork, SynapticTaggingSystem, HippocampalIndex, ContextMatcher, AccessibilityCalculator, CompetitionManager, StateUpdateService, ImportanceSignals, NoveltySignal, ArousalSignal, RewardSignal, AttentionSignal, PredictiveMemory, ProspectiveMemory, IntentionParser

**Advanced (11):** ImportanceTracker, ReconsolidationManager, IntentDetector, ActivityTracker, MemoryDreamer, MemoryChainBuilder, MemoryCompressor, CrossProjectLearner, AdaptiveEmbedder, SpeculativeRetriever, ConsolidationScheduler

**Search (2):** Reranker, TemporalSearcher

---

## Memory Hygiene

### Promote when:
- User confirms memory was helpful
- Solution worked correctly
- Information was accurate

### Demote when:
- User corrects a mistake
- Information was wrong
- Memory led to bad outcome

### Never save:
- Secrets, API keys, passwords
- Temporary debugging state
- Obvious/trivial information

---

## The One Rule

**When in doubt, save. The cost of a duplicate is near zero (Prediction Error Gating handles dedup). The cost of lost knowledge is permanent.**

Memory is retrieval. Searching strengthens memory. Search liberally, save aggressively.

---

## Development

- **Crate:** `vestige-mcp` v1.5.0, Rust 2024 edition
- **Tests:** 305 tests, zero warnings (`cargo test -p vestige-mcp`)
- **Build:** `cargo build --release -p vestige-mcp`
- **Features:** `embeddings` + `vector-search` (default on)
- **Architecture:** `McpServer` holds `Arc<Mutex<Storage>>` + `Arc<Mutex<CognitiveEngine>>`
- **Entry:** `src/main.rs` → stdio JSON-RPC server
- **Tools:** `src/tools/` — one file per tool, each exports `schema()` + `execute()`
- **Cognitive:** `src/cognitive.rs` — 28-field struct, initialized once at startup