# ShipItAndPray/mcp-memory [Health: Active]

**Category:** 🧠 Knowledge & Memory  
**Repository:** https://github.com/ShipItAndPray/mcp-memory  
**GitHub Stars:** 2  
**Views:** 2  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/shipitandpray-mcp-memory

## Description
Smart memory with exponential decay. Memories strengthen on access and fade when unused — solving the Karpathy problem of unbounded context growth. 7 tools, SQLite-based, zero dependencies.

## Tools
Capabilities this server exposes over MCP:

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

## Claude Desktop Quick Installation
Install path detected from listing signals. Uses `npx` (confidence: high):

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

## Documentation & README

# mcp-memory

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

**Solves [the Karpathy problem](https://x.com/karpathy/status/2036836816654147718): "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

```json
"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