Initial commit: Vestige v1.0.0 - Cognitive memory MCP server

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>
2026-05-10 08:12:37 +02:00 · 2026-01-25 01:31:03 -06:00 · 2026-01-25 01:31:03 -06:00 · f9c60eb5a7
commit f9c60eb5a7
169 changed files with 97206 additions and 0 deletions
--- a/packages/core/README.md
+++ b/packages/core/README.md
@ -0,0 +1,186 @@
+# Vestige
+
+[![npm version](https://img.shields.io/npm/v/vestige-mcp.svg)](https://www.npmjs.com/package/vestige-mcp)
+[![MCP Compatible](https://img.shields.io/badge/MCP-Compatible-blue.svg)](https://modelcontextprotocol.io)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+**Git Blame for AI Thoughts** - Memory that decays, strengthens, and discovers connections like the human mind.
+
+![Vestige Demo](./docs/assets/hero-demo.gif)
+
+## 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.