0e9b260518
Nine tool modules in crates/vestige-mcp/src/tools/ had zero callers after
the v2.0.x unification work shipped *_unified + maintenance::* replacements.
They'd been #[allow(dead_code)]-papered over and forgotten. Verified each
module independently: grep for tools::<name>::, string dispatch in server.rs,
cross-crate usage — all nine returned zero external callers.
Removed modules (all superseded):
checkpoint (364 LOC) — no callers anywhere
codebase (298) — superseded by codebase_unified
consolidate (36) — superseded by maintenance::execute_consolidate
ingest (456) — superseded by smart_ingest
intentions (1,093) — superseded by intention_unified
knowledge (106) — no callers anywhere
recall (403) — superseded by search_unified
search (184) — superseded by search_unified
stats (132) — superseded by maintenance::execute_system_status
Also removed:
- EmotionCategory::base_arousal (10 LOC, zero callers)
Kept (still string-dispatched from server.rs):
- context, feedback, memory_states, review, tagging
Doc fixes (ghost env vars that were documented but zero Rust source reads):
- docs/CONFIGURATION.md — dropped VESTIGE_DATA_DIR, VESTIGE_LOG_LEVEL rows
(neither is read anywhere; --data-dir CLI flag + RUST_LOG are the real
mechanisms). Added the full real env-var table.
- packages/vestige-mcp-npm/README.md — same two ghost rows dropped
- docs/VESTIGE_STATE_AND_PLAN.md:399 — dropped VESTIGE_DATA_DIR row
- docs/VESTIGE_STATE_AND_PLAN.md:709 — typo VESTIGE_API_KEY
-> VESTIGE_AUTH_TOKEN (matches shipping convention), "open if unset"
-> "auto-generated if unset" to match actual behavior
Verified post-cleanup:
- cargo check --workspace clean
- cargo clippy --workspace -D warnings clean
- cargo test --workspace 1,223 passing / 0 failed
- cargo build --release -p vestige-mcp clean
Net: -3,091 LOC (14 files), zero behavior change, zero regressions.
3.6 KiB
vestige-mcp-server
Vestige MCP Server - A synthetic hippocampus for AI assistants.
Built on 130 years of cognitive science research, Vestige provides biologically-inspired memory that decays, strengthens, and consolidates like the human mind.
Installation
npm install -g vestige-mcp-server
This automatically downloads the correct binary for your platform (macOS, Linux, Windows) from GitHub releases.
What gets installed
| Command | Description |
|---|---|
vestige-mcp |
MCP server for Claude integration |
vestige |
CLI for stats, health checks, and maintenance |
Verify installation
vestige health
Usage with Claude Code
claude mcp add vestige vestige-mcp -s user
Then restart Claude.
Usage with Claude Desktop
Add to your Claude Desktop configuration:
macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json
{
"mcpServers": {
"vestige": {
"command": "vestige-mcp"
}
}
}
CLI Commands
vestige stats # Memory statistics
vestige stats --states # Cognitive state distribution
vestige health # System health check
vestige consolidate # Run memory maintenance cycle
Features
- FSRS-6 Algorithm: State-of-the-art spaced repetition for optimal memory retention
- Dual-Strength Memory: Bjork & Bjork (1992) - Storage + Retrieval strength model
- Synaptic Tagging: Memories become important retroactively (Frey & Morris 1997)
- Semantic Search: Local embeddings via nomic-embed-text-v1.5 (768 dimensions)
- Local-First: All data stays on your machine - no cloud, no API costs
Storage & Memory
Vestige uses SQLite for storage. Your memories are stored on disk, not in RAM.
- Database limit: 216TB (SQLite theoretical max)
- RAM usage: ~64MB cache (configurable)
- Typical usage: 1 million memories ≈ 1-2GB on disk
You'll never run out of space. A heavy user creating 100 memories/day would use ~1.5GB after 10 years.
Embeddings
On first use, Vestige downloads the nomic-embed-text-v1.5 model (~130MB). This is a one-time download and all subsequent operations are fully offline.
The model is stored in .fastembed_cache/ in your working directory, or you can set a global location:
export FASTEMBED_CACHE_PATH="$HOME/.fastembed_cache"
Environment Variables
| Variable | Description | Default |
|---|---|---|
RUST_LOG |
Log verbosity + per-module filter | info |
FASTEMBED_CACHE_PATH |
Embeddings model cache | ./.fastembed_cache |
VESTIGE_DASHBOARD_PORT |
Dashboard port | 3927 |
VESTIGE_AUTH_TOKEN |
Bearer auth for dashboard + HTTP MCP | auto-generated |
Storage location is the --data-dir <path> CLI flag (defaults to your OS's per-user data directory).
Troubleshooting
"Could not attach to MCP server vestige"
- Verify binary exists:
which vestige-mcp - Test directly:
vestige-mcp(should wait for stdio input) - Check Claude logs:
~/Library/Logs/Claude/(macOS)
"vestige: command not found"
Reinstall the package:
npm install -g vestige-mcp-server
Embeddings not downloading
The model downloads on first ingest or search operation. If Claude can't connect to the MCP server, no memory operations happen and no model downloads.
Fix the MCP connection first, then the model will download automatically.
Supported Platforms
| Platform | Architecture |
|---|---|
| macOS | ARM64 (Apple Silicon), x86_64 (Intel) |
| Linux | x86_64 |
| Windows | x86_64 |
License
AGPL-3.0-only