vestige/README.md

██╗   ██╗███████╗███████╗████████╗██╗ ██████╗ ███████╗
██║   ██║██╔════╝██╔════╝╚══██╔══╝██║██╔════╝ ██╔════╝
██║   ██║█████╗  ███████╗   ██║   ██║██║  ███╗█████╗
╚██╗ ██╔╝██╔══╝  ╚════██║   ██║   ██║██║   ██║██╔══╝
 ╚████╔╝ ███████╗███████║   ██║   ██║╚██████╔╝███████╗
  ╚═══╝  ╚══════╝╚══════╝   ╚═╝   ╚═╝ ╚═════╝ ╚══════╝

Vestige

Memory traces that fade like yours do

The only AI memory system built on real cognitive science.
FSRS-6 spaced repetition. Prediction Error Gating. Context-dependent recall.
29 MCP tools. 100% local. 100% free.

Quick Start | All 26 Tools | The Science | Comparison

---

Quick Start (2 minutes)

Step 1: Build & Install

git clone https://github.com/samvallad33/vestige
cd vestige
cargo build --release
sudo cp target/release/vestige-mcp /usr/local/bin/

That's it. Vestige is now globally available.

Step 2: Add to Claude Code

Add to your ~/.claude/settings.json:

{
  "mcpServers": {
    "vestige": {
      "command": "vestige-mcp"
    }
  }
}

Step 3: Add to Claude Desktop (Optional)

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "vestige": {
      "command": "vestige-mcp",
      "args": [],
      "env": {
        "VESTIGE_DATA_DIR": "~/.vestige"
      }
    }
  }
}

Step 4: Restart & Verify

Restart Claude Code/Desktop. You should see 29 Vestige tools available.

---

Why Vestige?

Feature	What It Does	Who Else Has It
Prediction Error Gating	Auto-decides create/update/supersede based on similarity	Nobody
FSRS-6 Spaced Repetition	Full 21-parameter algorithm trained on millions of reviews	Nobody in AI memory
Retroactive Importance	Mark something important, past 9 hours of memories strengthen	Nobody
Context-Dependent Recall	Retrieval matches encoding context (Tulving 1973)	Nobody
Memory States	Active/Dormant/Silent/Unavailable accessibility model	Nobody
100% Local	No API keys, no cloud, no data leaves your machine	Rare

Other tools store memories. Vestige understands how memory actually works.

---

All 29 Tools

Core Memory (8 tools)

Tool	Description
ingest	Store a new memory
smart_ingest	Prediction Error Gating - auto-decides CREATE/UPDATE/SUPERSEDE based on semantic similarity to existing memories
recall	Semantic search with keyword matching
semantic_search	Pure embedding-based similarity search
hybrid_search	BM25 + semantic + RRF fusion (best retrieval quality)
get_knowledge	Retrieve a specific memory by ID
delete_knowledge	Remove a memory
mark_reviewed	FSRS review with 1-4 rating (strengthens memory)

Feedback System (3 tools)

Tool	Description
promote_memory	Thumbs up - memory led to good outcome, increase retrieval strength
demote_memory	Thumbs down - memory was wrong/unhelpful, decrease retrieval strength
request_feedback	Ask user if a memory was helpful after using it

Stats & Maintenance (3 tools)

Tool	Description
get_stats	Memory system statistics (total nodes, retention, embeddings)
health_check	System health status
run_consolidation	Trigger memory consolidation cycle (decay, promote, embed)

Codebase Memory (3 tools)

Tool	Description
remember_pattern	Store a code pattern or convention
remember_decision	Store an architectural decision with rationale
get_codebase_context	Retrieve patterns and decisions for current project

Prospective Memory (5 tools)

Tool	Description
set_intention	Remember to do something in the future (time/context/event triggers)
check_intentions	Check if any intentions should trigger based on current context
complete_intention	Mark an intention as fulfilled
snooze_intention	Delay an intention
list_intentions	List all active intentions

Neuroscience (7 tools)

Tool	Description
get_memory_state	Check cognitive state (Active/Dormant/Silent/Unavailable)
list_by_state	List memories filtered by cognitive state
state_stats	Distribution of memories across states
trigger_importance	Retroactively strengthen recent memories (Synaptic Tagging)
find_tagged	Find memories with high retention (tagged/strengthened)
tagging_stats	Synaptic tagging statistics
match_context	Context-dependent retrieval (Tulving's Encoding Specificity)

---

Prediction Error Gating

The smart_ingest tool implements neuroscience-inspired memory gating:

New memory: "The API uses JWT tokens"
                    ↓
         [Prediction Error Gate]
                    ↓
┌────────────────────────────────────────────┐
│ Found similar: "API uses OAuth"            │
│ Similarity: 0.82 | Prediction Error: 0.18  │
│                                            │
│ Decision: UPDATE existing memory           │
│ (Not creating duplicate)                   │
└────────────────────────────────────────────┘

Thresholds:

• >0.92 similarity → Reinforce (near-identical, just strengthen)
• >0.75 similarity → Update/Merge (related, combine information)
• <0.75 similarity → Create (sufficiently different, new memory)
• Demoted memory + similar new → Supersede (replace bad with good)

This solves the "bad vs good similar memory" problem automatically.

---

The Science

FSRS-6 Algorithm (2024)

Free Spaced Repetition Scheduler version 6. Trained on 700M+ reviews:

const FSRS_WEIGHTS: [f64; 21] = [
    0.40255, 1.18385, 3.173, 15.69105, 7.1949,
    0.5345, 1.4604, 0.0046, 1.54575, 0.1192,
    1.01925, 1.9395, 0.11, 0.29605, 2.2698,
    0.2315, 2.9898, 0.51655, 0.6621, 0.1, 0.5
];

20-30% better retention than SM-2 (what Anki uses).

Bjork & Bjork Dual-Strength Model (1992)

Memories have two independent strengths:

• Storage Strength: How well encoded (never decreases)
• Retrieval Strength: How accessible now (decays with time)

Key insight: difficult retrievals increase storage strength more than easy ones.

Synaptic Tagging & Capture (Frey & Morris 1997)

When something important happens, it retroactively strengthens memories from the past several hours. Vestige implements this with a 9-hour capture window.

Encoding Specificity Principle (Tulving 1973)

Memory retrieval is most effective when the retrieval context matches the encoding context. The match_context tool scores memories by context similarity.

Ebbinghaus Forgetting Curve (1885)

Memory retention decays exponentially: R = e^(-t/S)

Where R = retrievability, t = time, S = stability.

---

Comparison

Feature	Vestige	Mem0	Zep	Letta
Tools	29	~5	~8	~10
Prediction Error Gating	Yes	No	No	No
FSRS-6 spaced repetition	Yes	No	No	No
Dual-strength memory	Yes	No	No	No
Retroactive importance	Yes	No	No	No
Memory states	Yes	No	No	No
Context-dependent recall	Yes	No	No	No
Local embeddings	Yes	No	No	No
100% local	Yes	No	No	No
Free & open source	Yes	Freemium	Freemium	Yes

---

Configuration

Environment Variables

Variable	Description	Default
VESTIGE_DATA_DIR	Data storage directory	~/.vestige
VESTIGE_LOG_LEVEL	Log verbosity (error, warn, info, debug, trace)	info

Data Location

All data is stored in ~/.vestige/ by default:

• vestige.db - SQLite database with FTS5
• embeddings/ - Local embedding cache

---

Development

Prerequisites

• Rust 1.75+

Building

git clone https://github.com/samvallad33/vestige
cd vestige
cargo build --release

Testing

cargo test --workspace

Installing Locally

sudo cp target/release/vestige-mcp /usr/local/bin/

---

Updating

cd vestige
git pull
cargo build --release
sudo cp target/release/vestige-mcp /usr/local/bin/

Restart Claude Code/Desktop to pick up changes.

---

Troubleshooting

"vestige-mcp: command not found"

Make sure you copied the binary:

sudo cp target/release/vestige-mcp /usr/local/bin/

"No tools showing in Claude"

1. Check your config file syntax (valid JSON)
2. Restart Claude Code/Desktop completely
3. Check logs: VESTIGE_LOG_LEVEL=debug vestige-mcp

"Embeddings not generating"

First run downloads the embedding model (~100MB). Check your internet connection and wait for download to complete.

---

Contributing

Contributions welcome! Please open an issue or submit a pull request.

---

License

MIT OR Apache-2.0

---

_{Built with cognitive science and Rust.}