vestige/CLAUDE.md

Vestige v2.0.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 29 stateful cognitive modules. Use it automatically.

---

Session Start Protocol

Every conversation, before responding to the user:

1. session_context({                            → ONE CALL replaces steps 1-5
     queries: ["user preferences", "[project] context"],
     context: { codebase: "[project]", topics: ["[current topics]"] },
     token_budget: 1000
   })
2. Check automationTriggers from response:
   - needsDream == true  → call dream
   - needsBackup == true → call backup
   - needsGc == true     → call gc(dry_run: true)
   - totalMemories > 700 → call find_duplicates

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

Fallback: If session_context is unavailable, use the 5-call sequence: search × 2 → intention check → system_status → predict.

---

The 21 Tools

Context Packets (1 tool)

Tool

When to Use

session_context

One-call session initialization. Replaces 5 separate calls (search × 2, intention check, system_status, predict) with a single token-budgeted response. Returns markdown context + automationTriggers (needsDream/needsBackup/needsGc) + expandable IDs for on-demand full retrieval. Params: queries (string[]), token_budget (100-10000, default 1000), context ({codebase, topics, file}), include_status/include_intentions/include_predictions (bool).

Core Memory (1 tool)

Tool	When to Use
smart_ingest	Default for all saves. Single mode: provide content for auto-decide CREATE/UPDATE/SUPERSEDE via Prediction Error Gating. Batch mode: provide items array (max 20) for session-end saves — each item runs full cognitive pipeline (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 + convex combination fusion). 7-stage pipeline: overfetch → rerank → temporal boost → accessibility filter → context match → competition → spreading activation. Searching strengthens memory (Testing Effect). v1.8.0: optional token_budget param (100-10000) limits response size; results exceeding budget moved to expandable array.
memory	get, delete, state, promote, demote	Retrieve a full memory by ID, delete a memory, check its cognitive state (Active/Dormant/Silent/Unavailable), promote (thumbs up — increases retrieval strength), or demote (thumbs down — decreases retrieval strength, does NOT delete).
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.

Temporal (2 tools)

Tool	When to Use
memory_timeline	Browse memories chronologically. Grouped by day. Filter by type, tags, date range. When user references a time period ("last week", "yesterday").
memory_changelog	Audit trail. Per-memory: state transitions. System-wide: consolidations + recent changes. When debugging memory issues.

Cognitive (3 tools)

Tool	When to Use
dream	Trigger memory consolidation — replays recent memories to discover hidden connections and synthesize insights. At session start if >24h since last dream, after every 50 saves.
explore_connections	Graph exploration. Actions: chain (reasoning path A→B), associations (spreading activation from a node), bridges (connecting memories between two nodes). When search returns 3+ related results.
predict	Proactive retrieval — predicts what memories you'll need next based on context, activity patterns, and learned behavior. At session start, when switching projects.

Auto-Save & Dedup (2 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.
find_duplicates	Find near-duplicate memory clusters via cosine similarity. Returns merge/review suggestions. Run when memory count > 700 or on user request.

Autonomic (2 tools)

Tool	When to Use
memory_health	Retention dashboard — avg retention, distribution buckets, trend (improving/declining/stable), recommendation. Lightweight alternative to system_status focused on memory quality.
memory_graph	Subgraph export for visualization. Input: center_id or query, depth (1-3), max_nodes. Returns nodes with force-directed layout positions and edges with weights.

Maintenance (5 tools)

Tool	When to Use
system_status	Combined health + stats. Returns status (healthy/degraded/critical/empty), full statistics, FSRS preview, cognitive module health, state distribution, warnings, and recommendations. At session start (or use session_context which includes this).
consolidate	Run FSRS-6 consolidation cycle. Applies decay, generates embeddings, maintenance. At session end, when retention drops.
backup	Create SQLite database backup. Before major upgrades, weekly.
export	Export memories as JSON/JSONL with tag and date filters.
gc	Garbage collect low-retention memories. When system_status shows degraded + high count. Defaults to dry_run=true.

Restore (1 tool)

Tool	When to Use
restore	Restore memories from a JSON backup file. Supports MCP wrapper, RecallResult, and direct array formats.

Deprecated (still work via redirects)

Old Tool	Redirects To
ingest	smart_ingest
session_checkpoint	smart_ingest (batch mode)
promote_memory	memory(action="promote")
demote_memory	memory(action="demote")
health_check	system_status
stats	system_status

---

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

smart_ingest({
  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 + memory(action="promote")
"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 (cross-encoder)
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 (via memory promote/demote)

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 — 29 Modules

All modules persist across tool calls as stateful instances:

Neuroscience (16): ActivationNetwork, SynapticTaggingSystem, HippocampalIndex, ContextMatcher, AccessibilityCalculator, CompetitionManager, StateUpdateService, ImportanceSignals, NoveltySignal, ArousalSignal, RewardSignal, AttentionSignal, EmotionalMemory, 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 → memory(action="promote")
• Solution worked correctly
• Information was accurate

Demote when:

• User corrects a mistake → memory(action="demote")
• 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 v2.0.1, Rust 2024 edition, MSRV 1.91
• Tests: 1,238 tests, zero warnings
• Build: cargo build --release -p vestige-mcp
• Features: embeddings + vector-search (default on)
• Architecture: McpServer holds Arc<Storage> + Arc<Mutex<CognitiveEngine>>
• Storage: Interior mutability — Storage uses Mutex<Connection> for reader/writer split, all methods take &self. WAL mode for concurrent reads + writes.
• Entry: src/main.rs → stdio JSON-RPC server
• Tools: src/tools/ — one file per tool, each exports schema() + execute()
• Cognitive: src/cognitive.rs — 29-field struct, initialized once at startup