██╗ ██╗███████╗███████╗████████╗██╗ ██████╗ ███████╗
██║ ██║██╔════╝██╔════╝╚══██╔══╝██║██╔════╝ ██╔════╝
██║ ██║█████╗ ███████╗ ██║ ██║██║ ███╗█████╗
╚██╗ ██╔╝██╔══╝ ╚════██║ ██║ ██║██║ ██║██╔══╝
╚████╔╝ ███████╗███████║ ██║ ██║╚██████╔╝███████╗
╚═══╝ ╚══════╝╚══════╝ ╚═╝ ╚═╝ ╚═════╝ ╚══════╝
Vestige
Memory traces that fade like yours do
The only AI memory system built on real cognitive science.
FSRS-6 spaced repetition. Retroactive importance. Context-dependent recall.
All local. All free.
Installation |
Quick Start |
Features |
The Science
---
## Why Vestige?
**The only AI memory built on real cognitive science.**
| Feature | What It Does |
|---------|--------------|
| **FSRS-6 Spaced Repetition** | Full 21-parameter algorithm - nobody else in AI memory has this |
| **Retroactive Importance** | Mark something important, past 9 hours of memories strengthen too |
| **Context-Dependent Recall** | Retrieval matches encoding context (Tulving 1973) |
| **Memory States** | See if memories are Active, Dormant, Silent, or Unavailable |
| **100% Local** | No API keys, no cloud, your data stays yours |
> Other tools store memories. Vestige understands how memory actually works.
---
## Installation
### From Source (Recommended)
```bash
git clone https://github.com/samvallad33/vestige
cd vestige
cargo build --release --package vestige-mcp
```
The binary will be at `./target/release/vestige-mcp`
### Homebrew (macOS/Linux)
```bash
brew install samvallad33/tap/vestige
```
---
## Quick Start
### 1. Build Vestige
```bash
cargo build --release --package vestige-mcp
```
### 2. Configure Claude Desktop
Add Vestige 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": "/path/to/vestige-mcp",
"args": [],
"env": {
"VESTIGE_DATA_DIR": "~/.vestige"
}
}
}
}
```
### 3. Restart Claude Desktop
Claude will now have access to persistent, biologically-inspired memory.
---
## Features
### Core
| Feature | Description |
|---------|-------------|
| **FSRS-6 Algorithm** | Full 21-parameter spaced repetition (20-30% better than SM-2) |
| **Dual-Strength Memory** | Bjork & Bjork (1992) - Storage + Retrieval strength model |
| **Hybrid Search** | BM25 + Semantic + RRF fusion for best retrieval |
| **Local Embeddings** | 768-dim BGE embeddings, no API required |
| **SQLite + FTS5** | Fast full-text search with persistence |
### Neuroscience-Inspired
| Feature | Description |
|---------|-------------|
| **Synaptic Tagging** | Retroactive importance (Frey & Morris 1997) |
| **Memory States** | Active/Dormant/Silent/Unavailable continuum |
| **Context-Dependent Memory** | Encoding specificity principle (Tulving 1973) |
| **Prospective Memory** | Future intentions with time/context triggers |
| **Basic Consolidation** | Decay + prune cycles |
### MCP Tools (25 Total)
**Core Memory (7):**
- `ingest` - Store new memories
- `recall` - Semantic retrieval
- `semantic_search` - Pure embedding search
- `hybrid_search` - BM25 + semantic fusion
- `get_knowledge` - Get memory by ID
- `delete_knowledge` - Remove memory
- `mark_reviewed` - FSRS review (1-4 rating)
**Stats & Maintenance (3):**
- `get_stats` - Memory statistics
- `health_check` - System health
- `run_consolidation` - Trigger consolidation
**Codebase Memory (3):**
- `remember_pattern` - Store code patterns
- `remember_decision` - Store architectural decisions
- `get_codebase_context` - Retrieve project context
**Prospective Memory (5):**
- `set_intention` - Remember to do something
- `check_intentions` - Check triggered intentions
- `complete_intention` - Mark intention done
- `snooze_intention` - Delay intention
- `list_intentions` - List all intentions
**Neuroscience (7):**
- `get_memory_state` - Check cognitive state
- `list_by_state` - Filter by state
- `state_stats` - State distribution
- `trigger_importance` - Retroactive strengthening
- `find_tagged` - Find strengthened memories
- `tagging_stats` - Tagging system statistics
- `match_context` - Context-dependent retrieval
---
## The Science
### Ebbinghaus Forgetting Curve (1885)
Memory retention decays exponentially over time:
```
R = e^(-t/S)
```
Where:
- **R** = Retrievability (probability of recall)
- **t** = Time since last review
- **S** = Stability (strength of memory)
### 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.
### FSRS-6 Algorithm (2024)
Free Spaced Repetition Scheduler version 6. Trained on millions of reviews:
```rust
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
];
```
### Synaptic Tagging & Capture (Frey & Morris 1997)
When something important happens, it can retroactively strengthen 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. Vestige scores memories by context match.
---
## Comparison
| Feature | Vestige | Mem0 | Zep | Letta |
|---------|--------|------|-----|-------|
| 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 |
| Local embeddings | Yes | No | No | No |
| 100% local | Yes | No | No | No |
| Free & open source | Yes | Freemium | Freemium | Yes |
---
## Environment Variables
| Variable | Description | Default |
|----------|-------------|---------|
| `VESTIGE_DATA_DIR` | Data storage directory | `~/.vestige` |
| `VESTIGE_LOG_LEVEL` | Log verbosity | `info` |
---
## Development
### Prerequisites
- Rust 1.75+
### Building
```bash
git clone https://github.com/samvallad33/vestige
cd vestige
cargo build --release --package vestige-mcp
```
### Testing
```bash
cargo test --workspace
```
---
## Contributing
Contributions are welcome! Please open an issue or submit a pull request.
---
## License
MIT OR Apache-2.0
---
Built with cognitive science and Rust.