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."

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	Relevance scoring: decay × frequency × match quality

Install

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

Tools

Tool	What it does
remember	Store a memory with category. Auto-detects duplicates and reinforces.
recall	Retrieve memories ranked by smart relevance, not just keyword match.
forget	Explicitly delete a memory.
reinforce	User mentioned topic again — boost relevance, reset decay clock.
inspect	Debug view: all memories with decay status and scores.
prune	Auto-remove memories below relevance threshold.
stats	Health overview: active, fading, dead memories.

Memory Categories

Category	Decay Half-life	Use For
one-time	7 days	Casual question, unlikely to matter again
question	14 days	Regular question, might come back
interest	60 days	Recurring topic (auto-promoted after 5 mentions)
context	30 days	Situational context, project-specific
preference	180 days	User stated preference ("I prefer X")
correction	365 days	User corrected the agent ("No, I meant X")
fact	365 days	Factual info about the user (role, location)

Examples

User asks about Rust once:

remember(content: "User asked about Rust programming", category: "one-time")
→ Stored. Decays to 50% in 7 days. Gone in a month.

User keeps mentioning Python (5th time):

remember(content: "User asked about Python")
→ Reinforced (mention #5). Auto-upgraded from "question" to "interest". Now persists 60 days.

Recall with smart ranking:

recall(query: "programming")
→ Python (relevance: 0.92, 5 mentions, ACTIVE)
→ Rust (relevance: 0.08, 1 mention, FADING)

Python ranks first because it's been mentioned 5x. Rust ranks last because it was asked once and is fading. This is what Karpathy wants.

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.

License

MIT