mcp-memory

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