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. One command to install, zero infrastructure required. Memory starts working the moment you add it to your AI client.
| 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.
The 59% result used all-mpnet-base-v2. The current default model (multi-qa-mpnet-base-dot-v1) scores 55% on LoCoMo session-summary retrieval — see BENCHMARKS.md for details.
| System | Recall-all@5 | nDCG@5 |
|---|---|---|
YourMemory (full stack · multi-qa-mpnet-base-dot-v1) |
85% | 87% |
Full methodology in BENCHMARKS.md. Writeup: I built memory decay for AI agents using the Ebbinghaus forgetting curve.
Supports Python 3.11–3.14. No Docker, no database setup, no external services.
pip install yourmemoryyourmemory-pathPrints your full executable path and a ready-to-paste config block. Copy it.
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" }
}
}
}Windsurf / OpenCode / any MCP client
YourMemory is a standard stdio MCP server. Use the full path from yourmemory-path if the client doesn't inherit shell PATH.
{
"mcpServers": {
"yourmemory": {
"command": "/full/path/to/yourmemory",
"env": { "YOURMEMORY_USER": "your_name" }
}
}
}First start is automatic. On the first run, YourMemory initialises your database, downloads the language model, and injects memory workflow instructions into your AI client config — no manual setup needed.
That's it. On the first MCP start, YourMemory automatically:
- Initialises your local database at
~/.yourmemory/memories.duckdb - Downloads the spaCy language model in the background
- Injects the memory workflow rules into your AI client
Your AI now recalls what it learned in previous sessions, without you telling it to.
Every YourMemory instance ships with a built-in browser UI. When the MCP server is running, open:
http://localhost:3033/ui
Browse your memories by agent, filter by category, sort by strength, and see which memories are fading.
What you'll see
- Strength bars — how close each memory is to being pruned
- Agent tabs — switch between All / User / per-agent views
- Category badges — fact · strategy · assumption · failure
- Stats — total, strong (≥ 50%), fading (5–50%), near prune (< 10%)
Three tools, called by your AI automatically.
| Tool | When | What it does |
|---|---|---|
recall_memory(query, current_path?) |
Start of every task | Surfaces relevant memories ranked by similarity × strength; boosts spatially matched memories |
store_memory(content, importance, context_paths?) |
After learning something new | Embeds and stores with biological decay; tags optional file/dir paths for spatial recall |
update_memory(id, new_content) |
When a memory is outdated | Re-embeds and replaces; logs old content to audit trail |
# Store with spatial context
store_memory("Sachit prefers tabs over spaces in Python", importance=0.9, category="fact",
context_paths=["/projects/backend"])
# Next session — spatial boost applied when working in that path:
recall_memory("Python formatting", current_path="/projects/backend")
# → {"content": "Sachit prefers tabs over spaces in Python", "strength": 0.87, "score": 0.81}| 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 |
Memory strength decays exponentially — importance and recall frequency slow that decay:
effective_λ = base_λ × (1 - importance × 0.8)
strength = clamp(importance × e^(−effective_λ × active_days) × (1 + recall_count × 0.2), 0, 1)
hybrid_score = 0.4 × bm25_norm + 0.6 × cosine_similarity
active_days counts only days the user was active — vacations don't cause memory loss. Decay is used for pruning only, not ranking. Memories below strength 0.05 are pruned automatically every 24 hours.
Session wrap-up scoring: recalled memory IDs are tracked per session and get a recall_count boost when the session goes idle (30 min default). Set YOURMEMORY_SESSION_IDLE to change the window.
Recall throttling: identical (user, query) pairs are cached to avoid redundant retrieval within a configurable window. Set YOURMEMORY_RECALL_COOLDOWN (seconds, default 0 = off).
Retrieval runs in two rounds to surface related context that vocabulary-based search misses:
Round 1 — Hybrid search: cosine similarity + BM25 keyword scoring, 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 onlyPass 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 (multi-qa-mpnet-base-dot-v1, 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/yourmemorymacOS
brew install postgresql@16 pgvector && brew services start postgresql@16
createdb yourmemoryUbuntu / Debian
sudo apt install postgresql postgresql-contrib postgresql-16-pgvector
createdb yourmemoryClaude / Cline / Cursor / Any MCP client
│
├── recall_memory(query, current_path?, api_key?)
│ └── throttle check (YOURMEMORY_RECALL_COOLDOWN)
│ embed → vector similarity (Round 1)
│ → graph BFS expansion (Round 2)
│ → score = sim × strength → top-k
│ → spatial boost (+0.08) if current_path matches context_paths
│ → session tracking → recall_count bump on session end
│
├── store_memory(content, importance, category?, context_paths?, visibility?, api_key?)
│ └── question? → reject
│ contradiction check → update if conflict
│ embed() → INSERT → index_memory() → graph node + edges
│ record_activity(user_id) → active days log
│
└── update_memory(id, new_content, importance)
└── log old content → memory_history (audit trail)
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
├── context_paths JSON Neo4j (opt-in)
├── visibility VARCHAR └── bolt://localhost:7687
├── agent_id VARCHAR
user_activity (active days log)
memory_history (supersession audit)
PRs are welcome. See CONTRIBUTORS.md for the people who have already improved YourMemory.
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