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-pathif 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