vestige/packages/core

Vestige

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

# 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

# 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:

{
  "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 - Full TypeScript API documentation
• Configuration - All config options
• Architecture - System design and data flow
• Cognitive Science - The research behind Vestige

Contributing

See CONTRIBUTING.md for guidelines.

License

MIT - see LICENSE

---

Vestige: The only AI memory system built on 130 years of cognitive science research.