ShipItAndPray/mcp-memory

Smart memory for AI agents. Memories decay, topics are frequency-weighted, one-time questions don't become obsessions.

Solves the Karpathy problem: "A single question from 2 months ago keeps coming up as a deep interest with undue mentions in perpetuity."

What's New in v0.2.0

• Auto-categorization — no need to specify category, inferred from content
• Semantic dedup — bigram similarity prevents duplicate memories
• Preference supersede — "prefers dark mode" then "prefers light mode" updates, not duplicates
• Recall auto-reinforces — searching for a topic counts as a mention
• Recall auto-prunes — dead memories cleaned up on every read
• System prompt injection — active memories provided via MCP prompts capability
• Fuzzy forget — "VS Code" matches "User prefers VS Code for all editing"
• 7 tools → 4 tools — simpler API, higher adoption (backwards compatible)

In Action

Day 1: User asks 5 questions (Rust, dark mode, Python, job title, Haskell)

  #1 [ACTIVE] rel=1.000 cat=preference "User prefers dark mode in all editors"
  #2 [ACTIVE] rel=0.900 cat=fact       "User works as a senior software engineer"
  #3 [FADING] rel=0.500 cat=question   "User is building a Python web scraper"
  #4 [FADING] rel=0.300 cat=one-time   "User asked about Rust programming"
  #5 [FADING] rel=0.300 cat=one-time   "User asked what Haskell monads are"

Day 2-5: User mentions Python 4 more times → auto-upgraded to "interest"

  #1 [ACTIVE] rel=2.658 mentions=5 cat=interest    "Python web scraper"
  #2 [ACTIVE] rel=1.000 mentions=1 cat=preference  "dark mode"
  #3 [ACTIVE] rel=0.900 mentions=1 cat=fact         "senior software engineer"
  #4 [FADING] rel=0.300 mentions=1 cat=one-time     "Rust" ← FADING, won't obsess
  #5 [FADING] rel=0.300 mentions=1 cat=one-time     "Haskell" ← FADING, won't obsess

After 60 days:
  Rust:   0.3 × 0.5^(60/7) = 0.0008 → DEAD (gone, as it should be)
  Python: 0.8 × 0.5^(60/60) × 3.32 = 1.329 → STILL ACTIVE (real interest)

How It Fixes This

Current LLM Memory	mcp-memory
Ask about Rust once → mentioned forever	Ask once → fades in 7 days
All memories equal weight	Categories: one-time (7d), question (14d), interest (60d), preference (180d)
No decay	Exponential decay — old memories naturally fade
No frequency tracking	Mentioned 5+ times → auto-upgrades from "question" to "interest"
Keyword matching	Bigram similarity + relevance scoring
Agent must decide to remember	Auto-categorizes from content patterns
Contradicting preferences coexist	New preference supersedes old one
Manual cleanup required	Auto-prunes dead memories on recall

Install

"mcpServers": {
  "memory": {
    "command": "npx",
    "args": ["-y", "mcp-memory"]
  }
}

Tools

Tool	What it does
remember	Store a memory. Auto-categorizes from content. Auto-deduplicates via bigram similarity. Supersedes conflicting preferences.
recall	Retrieve memories ranked by relevance. Auto-reinforces top match. Auto-prunes dead memories.
forget	Delete a memory by ID or fuzzy content match.
inspect	Debug view: all memories with decay status, relevance scores, category breakdown, health.

Auto-Categorization

No need to specify category — it's inferred from content:

Content Pattern	Auto-Category	Decay
"prefers X", "likes X", "always uses X"	preference	180 days
"works as X", "is a X", "lives in X"	fact	365 days
"actually X", "meant X", "wrong"	correction	365 days
"currently building", "working on"	context	30 days
"what is X", "how to X"	one-time	7 days
anything else	question	14 days

You can still override: remember(content: "...", category: "preference")

Examples

Auto-categorized preference:

remember(content: "User prefers TypeScript over JavaScript")
→ Auto-detected as "preference". Persists 180 days.

Semantic dedup:

remember(content: "Works as data scientist at Google")
remember(content: "Works as senior data scientist at Google")
→ Second call reinforces first (80% similar). Keeps longer version.

Preference supersede:

remember(content: "User prefers dark mode")
remember(content: "User prefers light mode")
→ Superseded: "dark mode" → "light mode". One memory, not two.

Recall auto-reinforces:

recall(query: "MCP servers")
→ Returns matching memories AND counts this as a mention.
  mention_count goes from 1 → 2 automatically.

Fuzzy forget:

forget(content: "VS Code")
→ Matches and removes "User prefers VS Code for all editing"

The Math

relevance = base_weight × decay × frequency_boost

where:
  base_weight  = category-specific (0.3 for one-time, 1.0 for preference)
  decay        = 0.5 ^ (age_days / halflife_days)
  freq_boost   = 1 + log2(mention_count)

A one-time question from 2 months ago: 0.3 × 0.5^(60/7) × 1.0 = 0.0003 → effectively zero. Won't surface.

A preference mentioned 8 times, last week: 1.0 × 0.5^(7/180) × 4.0 = 3.89 → top of every recall.

Backwards Compatibility

v0.2.0 still accepts the old v0.1.0 tool names (reinforce, prune, stats). They map to the new tools internally. No breaking changes.

License

MIT