mirror of
https://github.com/samvallad33/vestige.git
synced 2026-05-09 15:52:37 +02:00
f9c60eb5a7
FSRS-6 spaced repetition, spreading activation, synaptic tagging, hippocampal indexing, and 130 years of memory research. Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
186 lines
5.4 KiB
Markdown
186 lines
5.4 KiB
Markdown
# Vestige
|
|
|
|
[](https://www.npmjs.com/package/vestige-mcp)
|
|
[](https://modelcontextprotocol.io)
|
|
[](https://opensource.org/licenses/MIT)
|
|
|
|
**Git Blame for AI Thoughts** - Memory that decays, strengthens, and discovers connections like the human mind.
|
|
|
|
|
|
|
|
## Why Vestige?
|
|
|
|
| Feature | Vestige | Mem0 | Zep | Letta |
|
|
|---------|--------|------|-----|-------|
|
|
| FSRS-5 spaced repetition | Yes | No | No | No |
|
|
| Dual-strength memory | Yes | No | No | No |
|
|
| Sentiment-weighted retention | Yes | No | Yes | No |
|
|
| Local-first (no cloud) | Yes | No | No | No |
|
|
| Git context capture | Yes | No | No | No |
|
|
| Semantic connections | Yes | Limited | Yes | Yes |
|
|
| Free & open source | Yes | Freemium | Freemium | Yes |
|
|
|
|
## Quickstart
|
|
|
|
```bash
|
|
# Install
|
|
npx vestige-mcp init
|
|
|
|
# Add to Claude Desktop config
|
|
# ~/.config/claude/claude_desktop_config.json (Mac/Linux)
|
|
# %APPDATA%\Claude\claude_desktop_config.json (Windows)
|
|
{
|
|
"mcpServers": {
|
|
"vestige": {
|
|
"command": "npx",
|
|
"args": ["vestige-mcp"]
|
|
}
|
|
}
|
|
}
|
|
|
|
# Restart Claude Desktop - done!
|
|
```
|
|
|
|
## Key Concepts
|
|
|
|
### Cognitive Science Foundation
|
|
|
|
Vestige implements proven memory science:
|
|
|
|
- **FSRS-5**: State-of-the-art spaced repetition algorithm (powers Anki's 100M+ users)
|
|
- **Dual-Strength Memory**: Separate storage and retrieval strength (Bjork & Bjork, 1992)
|
|
- **Ebbinghaus Decay**: Memories fade naturally without reinforcement using `R = e^(-t/S)`
|
|
- **Sentiment Weighting**: Emotional memories decay slower via AFINN-165 lexicon analysis
|
|
|
|
### Developer Features
|
|
|
|
- **Git-Blame for Thoughts**: Every memory captures git branch, commit hash, and changed files
|
|
- **REM Cycle**: Background connection discovery between unrelated memories
|
|
- **Shadow Self**: Queue unsolved problems for future inspiration when new knowledge arrives
|
|
|
|
## MCP Tools
|
|
|
|
| Tool | Description |
|
|
|------|-------------|
|
|
| `ingest` | Store knowledge with metadata (source, people, tags, git context) |
|
|
| `recall` | Search memories by query with relevance ranking |
|
|
| `get_knowledge` | Retrieve specific memory by ID |
|
|
| `get_related` | Find connected nodes via graph traversal |
|
|
| `mark_reviewed` | Reinforce a memory (triggers spaced repetition) |
|
|
| `remember_person` | Add/update person in your network |
|
|
| `get_person` | Retrieve person details and relationship health |
|
|
| `daily_brief` | Get summary of memory state and review queue |
|
|
| `health_check` | Check database health with recommendations |
|
|
| `backup` | Create timestamped database backup |
|
|
|
|
## MCP Resources
|
|
|
|
| Resource | URI | Description |
|
|
|----------|-----|-------------|
|
|
| Recent memories | `memory://knowledge/recent` | Last 20 stored memories |
|
|
| Decaying memories | `memory://knowledge/decaying` | Memories below 50% retention |
|
|
| People network | `memory://people/network` | Your relationship graph |
|
|
| System context | `memory://context` | Active window, git branch, clipboard |
|
|
|
|
## CLI Commands
|
|
|
|
```bash
|
|
# Memory
|
|
vestige stats # Quick overview
|
|
vestige recall "query" # Search memories
|
|
vestige review # Show due for review
|
|
|
|
# Ingestion
|
|
vestige eat <url|path> # Ingest documentation
|
|
|
|
# REM Cycle
|
|
vestige dream # Discover connections
|
|
vestige dream --dry-run # Preview only
|
|
|
|
# Shadow Self
|
|
vestige problem "desc" # Log unsolved problem
|
|
vestige problems # List open problems
|
|
vestige solve <id> "fix" # Mark solved
|
|
|
|
# Context
|
|
vestige context # Show current context
|
|
vestige watch # Start context daemon
|
|
|
|
# Maintenance
|
|
vestige backup # Create backup
|
|
vestige optimize # Vacuum and reindex
|
|
vestige decay # Apply memory decay
|
|
```
|
|
|
|
## Configuration
|
|
|
|
Create `~/.vestige/config.json`:
|
|
|
|
```json
|
|
{
|
|
"fsrs": {
|
|
"desiredRetention": 0.9,
|
|
"maxStability": 365
|
|
},
|
|
"rem": {
|
|
"enabled": true,
|
|
"maxAnalyze": 50,
|
|
"minStrength": 0.3
|
|
},
|
|
"decay": {
|
|
"sentimentBoost": 2.0
|
|
}
|
|
}
|
|
```
|
|
|
|
### Database Locations
|
|
|
|
| File | Path |
|
|
|------|------|
|
|
| Main database | `~/.vestige/vestige.db` |
|
|
| Shadow Self | `~/.vestige/shadow.db` |
|
|
| Backups | `~/.vestige/backups/` |
|
|
| Context | `~/.vestige/context.json` |
|
|
|
|
## How It Works
|
|
|
|
### Memory Decay
|
|
|
|
```
|
|
Retention = e^(-days/stability)
|
|
|
|
New memory: S=1.0 -> 37% after 1 day
|
|
Reviewed once: S=2.5 -> 67% after 1 day
|
|
Reviewed 3x: S=15.6 -> 94% after 1 day
|
|
Emotional: S x 1.85 boost
|
|
```
|
|
|
|
### REM Cycle Connections
|
|
|
|
The REM cycle discovers hidden relationships:
|
|
|
|
| Connection Type | Trigger | Strength |
|
|
|----------------|---------|----------|
|
|
| `entity_shared` | Same people mentioned | 0.5 + (count * 0.2) |
|
|
| `concept_overlap` | 2+ shared concepts | 0.4 + (count * 0.15) |
|
|
| `keyword_similarity` | Jaccard > 15% | similarity * 2 |
|
|
| `temporal_proximity` | Same day + overlap | 0.3 |
|
|
|
|
## Documentation
|
|
|
|
- [API Reference](./docs/api.md) - Full TypeScript API documentation
|
|
- [Configuration](./docs/configuration.md) - All config options
|
|
- [Architecture](./docs/architecture.md) - System design and data flow
|
|
- [Cognitive Science](./docs/cognitive-science.md) - The research behind Vestige
|
|
|
|
## Contributing
|
|
|
|
See [CONTRIBUTING.md](./CONTRIBUTING.md) for guidelines.
|
|
|
|
## License
|
|
|
|
MIT - see [LICENSE](./LICENSE)
|
|
|
|
---
|
|
|
|
**Vestige**: The only AI memory system built on 130 years of cognitive science research.
|