Every session, your AI assistant starts from zero. It asks the same questions, forgets your preferences, re-learns your stack. There is no memory between conversations.

YourMemory fixes that. It gives AI agents a persistent memory layer that works the way human memory does β€” important things stick, forgotten things fade, outdated facts get replaced automatically. Two commands to install, zero infrastructure required.

Tested on LoCoMo-10 β€” 1,534 QA pairs across 10 multi-session conversations.

| System | Recall@5 | 95% CI |
| --- | --- | --- |
| YourMemory (BM25 + vector + graph + decay) | 59% | 56–61% |
| Zep Cloud | 28% | 26–30% |

2Γ— better recall than Zep Cloud on the same benchmark.

Full methodology and per-sample breakdown in BENCHMARKS.md. Writeup: I built memory decay for AI agents using the Ebbinghaus forgetting curve.

Supports Python 3.11, 3.12, 3.13, and 3.14. No Docker, no database setup, no external services.

Step 2 β€” Run setup (once)

Downloads the spaCy language model and initialises the local database at ~/.yourmemory/memories.duckdb.

Step 3 β€” Get your config path

Prints your full executable path and a ready-to-paste config block. Copy it.

Step 4 β€” Wire into your AI client

Claude Code

Add to ~/.claude/settings.json:

{ "mcpServers": { "yourmemory": { "command": "yourmemory" } } }

Reload (Cmd+Shift+P β†’ Developer: Reload Window).

Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{ "mcpServers": { "yourmemory": { "command": "yourmemory" } } }

Restart Claude Desktop.

Cline (VS Code)

VS Code doesn't inherit your shell PATH. Run yourmemory-path first to get the full executable path.

In Cline β†’ MCP Servers β†’ Edit MCP Settings:

{ "mcpServers": { "yourmemory": { "command": "/full/path/to/yourmemory", "args": [], "env": { "YOURMEMORY_USER": "your_name" } } } }

Restart Cline after saving.

Cursor

Add to ~/.cursor/mcp.json:

{ "mcpServers": { "yourmemory": { "command": "/full/path/to/yourmemory", "args": [], "env": { "YOURMEMORY_USER": "your_name" } } } }

OpenCode

Add to ~/.config/opencode/config.json:

{ "mcp": { "yourmemory": { "type": "local", "command": ["yourmemory"], "environment": { "YOURMEMORY_USER": "your_name" } } } }

Then copy the memory workflow instructions:

cp sample_CLAUDE.md ~/.config/opencode/instructions.md

Restart OpenCode.

Any MCP-compatible client: YourMemory is a standard stdio MCP server. Works with Windsurf, Continue, Zed, and any client that supports MCP. Use the full path from yourmemory-path if the client doesn't inherit shell PATH.

Step 5 β€” Add memory instructions to your project

cp sample_CLAUDE.md CLAUDE.md

Edit CLAUDE.md β€” replace YOUR_NAME and YOUR_USER_ID. Claude now follows the recall β†’ store β†’ update workflow automatically on every task.

Three tools. Called by Claude automatically once CLAUDE.md is in place.

| Tool | When | What it does |
| --- | --- | --- |
| recall_memory(query) | Start of every task | Surfaces relevant memories ranked by similarity Γ— strength |
| store_memory(content, importance) | After learning something new | Embeds and stores with biological decay |
| update_memory(id, new_content) | When a memory is outdated | Re-embeds and replaces |

```

Example session

store_memory("Sachit prefers tabs over spaces in Python", importance=0.9, category="fact")

Next session β€” without being told again:

recall_memory("Python formatting")

β†’ {"content": "Sachit prefers tabs over spaces in Python", "strength": 0.87}

```

Categories control how fast memories fade

| Category | Survives without recall | Use case |
| --- | --- | --- |
| strategy | \~38 days | Successful patterns |
| fact | \~24 days | Preferences, identity |
| assumption | \~19 days | Inferred context |
| failure | \~11 days | Errors, environment-specific issues |

Ebbinghaus Forgetting Curve

Memory strength decays exponentially β€” but importance and recall frequency slow that decay:

effective_Ξ» = base_Ξ» Γ— (1 - importance Γ— 0.8) strength = importance Γ— e^(βˆ’effective_Ξ» Γ— days) Γ— (1 + recall_count Γ— 0.2) score = cosine_similarity Γ— strength

Memories recalled frequently resist decay. Memories below strength 0.05 are pruned automatically every 24 hours.

Hybrid Retrieval: Vector + Graph

Retrieval runs in two rounds to surface related context that vocabulary-based search misses:

Round 1 β€” Vector search: cosine similarity against all memories, returns top-k above threshold.

Round 2 β€” Graph expansion: BFS traversal from Round 1 seeds surfaces memories that share context but not vocabulary β€” connected via semantic edges (cosine similarity β‰₯ 0.4).

recall("Python backend") Round 1 β†’ [1] Python/MongoDB (sim=0.61) [2] DuckDB/spaCy (sim=0.19) Round 2 β†’ [5] Docker/Kubernetes (sim=0.29 β€” below cut-off, surfaced via graph)

Chain-aware pruning: A decayed memory is kept alive if any graph neighbour is above the prune threshold. Related memories age together.

Multiple agents can share the same YourMemory instance β€” each with isolated private memories and controlled access to shared context.

```
from src.services.api_keys import register_agent

result = register_agent(
agent_id="coding-agent",
user_id="sachit",
can_read=["shared", "private"],
can_write=["shared", "private"],
)

β†’ result["api_key"] β€” ym_xxxx, shown once only

```

Pass api_key to any MCP call to authenticate as an agent:

```
store_memory(content="Staging uses self-signed cert β€” skip SSL verify",
importance=0.7, category="failure",
api_key="ym_xxxx", visibility="private")

recall_memory(query="staging SSL", api_key="ym_xxxx")

β†’ returns shared memories + this agent's private memories

β†’ other agents see shared only

```

| Component | Role |
| --- | --- |
| DuckDB | Default vector DB β€” zero setup, native cosine similarity |
| NetworkX | Default graph backend β€” persists at ~/.yourmemory/graph.pkl |
| sentence-transformers | Local embeddings (all-mpnet-base-v2, 768 dims) |
| spaCy | Local NLP for deduplication and SVO triple extraction |
| APScheduler | Automatic 24h decay job |
| PostgreSQL + pgvector | Optional β€” for teams or large datasets |
| Neo4j | Optional graph backend β€” pip install 'yourmemory[neo4j]' |

PostgreSQL setup (optional)

pip install yourmemory[postgres]

Create a .env file:

DATABASE_URL=postgresql://YOUR_USER@localhost:5432/yourmemory

macOS

brew install postgresql@16 pgvector && brew services start postgresql@16 createdb yourmemory

Ubuntu / Debian

sudo apt install postgresql postgresql-contrib postgresql-16-pgvector createdb yourmemory

```
Claude / Cline / Cursor / Any MCP client
β”‚
β”œβ”€β”€ recall_memory(query, api_key?)
β”‚ └── embed β†’ vector similarity (Round 1)
β”‚ β†’ graph BFS expansion (Round 2)
β”‚ β†’ score = sim Γ— strength β†’ top-k
β”‚ β†’ recall propagation β†’ boost neighbours
β”‚
β”œβ”€β”€ store_memory(content, importance, category?, visibility?, api_key?)
β”‚ └── question? β†’ reject
β”‚ contradiction check β†’ update if conflict
β”‚ embed() β†’ INSERT β†’ index_memory() β†’ graph node + edges
β”‚
└── update_memory(id, new_content, importance)
└── embed(new_content) β†’ UPDATE β†’ refresh graph node

Vector DB (Round 1) Graph DB (Round 2)
DuckDB (default) NetworkX (default)
memories.duckdb graph.pkl
β”œβ”€β”€ embedding FLOAT[768] β”œβ”€β”€ nodes: memory_id, strength
β”œβ”€β”€ importance FLOAT └── edges: sim Γ— verb_weight β‰₯ 0.4
β”œβ”€β”€ recall_count INTEGER
β”œβ”€β”€ visibility VARCHAR Neo4j (opt-in)
└── agent_id VARCHAR └── bolt://localhost:7687
```

Benchmarks use the LoCoMo dataset by Snap Research.

Maharana et al. (2024). LoCoMo: Long Context Multimodal Benchmark for Dialogue. Snap Research.

Copyright 2026 Sachit Misra β€” Licensed under CC-BY-NC-4.0.

Free for: personal use, education, academic research, open-source projects.
Not permitted: commercial use without a separate written agreement.

Commercial licensing: mishrasachit1@gmail.com