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