mirror of
https://github.com/samvallad33/vestige.git
synced 2026-04-25 00:36:22 +02:00
0e9b260518
Some checks are pending
CI / Test (macos-latest) (push) Waiting to run
CI / Test (ubuntu-latest) (push) Waiting to run
CI / Release Build (aarch64-apple-darwin) (push) Blocked by required conditions
CI / Release Build (x86_64-unknown-linux-gnu) (push) Blocked by required conditions
CI / Release Build (x86_64-apple-darwin) (push) Blocked by required conditions
Test Suite / Unit Tests (push) Waiting to run
Test Suite / MCP E2E Tests (push) Waiting to run
Test Suite / User Journey Tests (push) Blocked by required conditions
Test Suite / Dashboard Build (push) Waiting to run
Test Suite / Code Coverage (push) Waiting to run
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.
132 lines
3.6 KiB
Markdown
132 lines
3.6 KiB
Markdown
# 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
|
|
|
|
```bash
|
|
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
|
|
|
|
```bash
|
|
vestige health
|
|
```
|
|
|
|
## Usage with Claude Code
|
|
|
|
```bash
|
|
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`
|
|
|
|
```json
|
|
{
|
|
"mcpServers": {
|
|
"vestige": {
|
|
"command": "vestige-mcp"
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
## CLI Commands
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
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"
|
|
|
|
1. Verify binary exists: `which vestige-mcp`
|
|
2. Test directly: `vestige-mcp` (should wait for stdio input)
|
|
3. Check Claude logs: `~/Library/Logs/Claude/` (macOS)
|
|
|
|
### "vestige: command not found"
|
|
|
|
Reinstall the package:
|
|
```bash
|
|
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
|