Verleiht KI-Agenten ein persistentes lokales Gedächtnis mit Konsolidierung, einem Vergessenskurven-Zerfall und graphbasiertem Abruf über verschiedene Sessions hinweg.
Auch bekannt als sachitrafa/YourMemory
- Stars
- 273
- Tools
- —
- Downloads, 30 Tage
- 562
- Neueste Version
- 1.4.18
- Letzter Commit
- 19. Sept. 2026
- Lizenz
- —
Was ist YourMemory MCP?
Verleiht KI-Agenten ein persistentes lokales Gedächtnis mit Konsolidierung, einem Vergessenskurven-Zerfall und graphbasiertem Abruf über verschiedene Sessions hinweg.
Zusammenfassung generiert aus dem README des Projekts
Über YourMemory MCP server
YourMemory ermöglicht es Entwicklern, die MCP-Clients wie Claude Desktop, Cursor, Windsurf oder Cline nutzen, ihren KI-Agenten ein langfristiges Gedächtnis nach biologischem Vorbild zu geben. Anstatt einer einfachen Vektorspeicherung, die mit der Zeit nur Rauschen ansammelt, implementiert dieser Server eine Ebbinghaus-Vergessenskurve, um veraltete Fakten auszusortieren, sowie einen Konsolidierungsprozess, der zusammenhängende Informationen in sauberen Summaries komprimiert. Das stellt sicher, dass der Kontext deines Agenten präzise bleibt, anstatt mit der Zeit aufzublähen.
Nutzer können dies lokal mit einem Zero-Setup DuckDB-Backend ausführen oder es für Teams mit Postgres und der pgvector-Extension bereitstellen. Es fungiert als Local-first-System, bei dem keine Daten deine Maschine verlassen, obwohl du optional Ollama für die lokale Faktenextraktion oder Anthropic für die cloudbasierte Extraktion nutzen kannst. Das System pflegt einen Entity-Graph, um Personen, Orte und Konzepte zu verknüpfen, was der KI ermöglicht, verwandte Informationen abzurufen, die du vielleicht nicht explizit angefragt hast. Jede Interaktion wird in einem Hash-Chained-Audit-Log gespeichert, das manipulationssicher ist, um die Datenintegrität zu gewährleisten.
Was du damit machen kannst
- 1Langfristigen Kontext beibehaltenVersorge einen KI-Agenten mit persistentem Wissen, das Context-Window-Resets und neue Sessions überdauert.
- 2Gedächtnis-Rauschen reduzierenKomprimiere große Cluster zusammenhängender Fakten automatisch in einzelne Summaries, um Unordnung beim Abruf zu vermeiden.
- 3Wissensaustausch im Team ermöglichenErstelle gemeinsame Memory-Pools, damit mehrere Agenten innerhalb einer Organisation auf dasselbe institutionelle Wissen zugreifen können.
- 4Verwandte Konzepte entdeckenNutze einen Entity-Graph, um Informationen aufzuspüren, die kontextuell mit einer Anfrage verknüpft sind, selbst wenn die Wortwahl eine andere ist.
Geschrieben aus dem README des Projekts. Jeder Use Case wurde gegen ein Zitat daraus geprüft.
So installierst du YourMemory MCP
Formate geprüft am 10. Nov. 2026Zu Cursor hinzufügenZu Goose hinzufügenYourMemory MCP in Claude Code installieren
$ claude mcp add yourmemory -- uvx yourmemoryYourMemory MCP in Cursor installieren
~/.cursor/mcp.json
{
"mcpServers": {
"yourmemory": {
"command": "uvx",
"args": [
"yourmemory"
]
}
}
}YourMemory MCP in VS Code installieren
.vscode/mcp.json
{
"servers": {
"yourmemory": {
"type": "stdio",
"command": "uvx",
"args": [
"yourmemory"
]
}
}
}YourMemory MCP in VS Code CLI installieren
$ code --add-mcp '{"name":"yourmemory","type":"stdio","command":"uvx","args":["yourmemory"]}'YourMemory MCP in Claude Desktop installieren
claude_desktop_config.json
{
"mcpServers": {
"yourmemory": {
"command": "uvx",
"args": [
"yourmemory"
]
}
}
}YourMemory MCP in Codex installieren
$ codex mcp add yourmemory -- uvx yourmemoryYourMemory MCP in Codex config.toml installieren
~/.codex/config.toml
[mcp_servers.yourmemory] command = "uvx" args = ["yourmemory"]
YourMemory MCP in Gemini CLI installieren
$ gemini mcp add -s user yourmemory uvx -- yourmemoryYourMemory MCP in Gemini settings.json installieren
~/.gemini/settings.json
{
"mcpServers": {
"yourmemory": {
"command": "uvx",
"args": [
"yourmemory"
]
}
}
}Konfiguration
PYTHONIOENCODINGSet to utf-8 to ensure correct text encoding on all platforms.
| Name | Beschreibung | Typ |
|---|---|---|
| PYTHONIOENCODING | Set to utf-8 to ensure correct text encoding on all platforms. |
Automatisierte Checks
Geluften am 14. Nov. 2026Vollständiger Bericht →Unsere automatisierten Checks bestanden. Das ist kein Security-Audit: Lies den Code und gib dem Server nur den minimal notwendigen Zugriff. Wie die Checks funktionieren · Was du für mehr Punkte verbessern kannst
- Source Repository verknüpft und erreichbarsachitrafa/yourmemory is public and reachablegithub.com/sachitrafa/yourmemory ↗Bestanden
- Paket nennt dieses Repository als Quelleyourmemory names sachitrafa/yourmemory as sourcepypi.org/project/yourmemory/ ↗Bestanden
- Build-Provenienz (Sigstore-Attestierung)No build attestation published for this releaseNicht geprüft
- Open Source Lizenz (OSI)No licenseBefund
- Commit oder Release im letzten JahrLast commit or release 2026-09-19github.com/sachitrafa/yourmemory ↗Bestanden
- OpenSSF ScorecardNicht geprüft
- Package-Name ähnelt keinem populären PackageNo popular package one edit away from yourmemoryBestanden
- Keine kritischen Advisories im Paket oder seinen Abhängigkeiten92 resolved dependencies checked; no critical advisoryosv.dev ↗Bestanden
- Keine versteckten Anweisungen an das Modell0 tool descriptions and the README read; no override phrases, credential paths or hidden charactersBestanden
- Destruktive Tools sind markiertNicht geprüft
- Remote-Endpoint beantwortet den MCP-HandshakeNicht geprüft
README
Auf GitHub ansehenYour AI has the memory of a goldfish. Not anymore.
Persistent, self-improving memory for AI agents — built on the science of how humans remember.
▶ Try the live interactive demo · Website · Benchmarks
The problem
Every morning your AI agent treats you like a stranger. Same context re-explained. Same preferences forgotten. Every session starts from zero.
Most "memory" tools bolt a vector database onto an agent and call it done — but that's just storage. It hoards every near-duplicate until retrieval drowns in noise. A goldfish with a bigger bowl.
YourMemory is different: memory that works like a brain, not a database.
flowchart LR
A["🧠 You tell your<br/>AI something"] --> B["Extract durable<br/>facts"]
B --> C["Dedup + embed<br/>+ graph-link"]
C --> D[("Memory<br/>store")]
D -->|"related facts pile up"| E["✨ Consolidate<br/>N → 1 summary"]
D -->|"stale + unused"| F["📉 Decay<br/>+ prune"]
D -->|"new session"| G["♻️ Recall<br/>hybrid + graph"]
E --> D
G --> H["🤖 Your agent<br/>picks up where<br/>it left off"]
style D fill:#0a2540,stroke:#19cdff,color:#fff
style E fill:#0c2b3a,stroke:#5eead4,color:#fff
style H fill:#0c2b3a,stroke:#19cdff,color:#fff
✨ What makes it different
| Feature | What it does | |
|---|---|---|
| 🧠 | Consolidation | When enough related facts accumulate, they're compressed into one clean summary and the originals are archived. Memory gets sharper over time, not bloated. |
| 📉 | Biological decay | Every memory ages on an Ebbinghaus forgetting curve. Stale, unused facts fade; important and frequently-recalled ones persist. |
| 🔗 | Entity graph | Memories link by shared people, places, and concepts — so recall surfaces what you forgot to ask for. |
| ♻️ | Survives context resets | When the context window compacts, YourMemory hands the working context back — no re-reading files to figure out where you were. |
| 🔒 | Tamper-evident audit trail | Every read / write / delete is logged in a hash-chained ledger. Alter one record and the chain breaks. |
| 👥 | Team memory pools | Role-based shared memory, so a whole team's agents draw on the same institutional knowledge — with private memories kept private. |
| 🛡️ | Data rights built in | One-command export (right to access) and right-to-forget (purge), plus SOC 2-aligned controls. |
| 🔌 | MCP-native & local-first | Works with Claude, Cursor, Cline, Windsurf, or any MCP client. Runs entirely on your machine — no API key, nothing leaves your system. |
One command to install. DuckDB by default (zero setup), Postgres + pgvector for teams.
Table of Contents
- 🏆 Benchmarks
- 🚀 Quick Start
- 🧠 How Memory Works
- 🔒 Trust & Audit Trail
- 👥 Team Memory Pools
- 🛡️ Data Rights & Compliance
- 🎛️ Dashboards
- 🔧 MCP Tools
- ⚡ Ask Without an LLM Call
- 🔀 API Proxy — Guaranteed Memory
- 🏗️ Architecture & Stack
- 🩺 Troubleshooting
- 🤝 Contributing
🏆 Benchmarks
Three external datasets. Every number independently reproducible — benchmark code lives in the repo. Full methodology in BENCHMARKS.md.
LoCoMo-10 — multi-session conversational memory
xychart-beta
title "Recall@5 · LoCoMo-10 (higher is better)"
x-axis ["Mem0", "Zep Cloud", "Supermemory", "YourMemory"]
y-axis "Recall@5 percent" 0 --> 70
bar [18, 28, 31, 59]
2× better recall than Zep Cloud across all 10 samples. *Supermemory and Mem0 exhausted free-tier quotas mid-benchmark; scores computed over the full 1,534 pairs.
LongMemEval-S — 500 questions, ~53 distractor sessions each
The hardest standard benchmark for long-term memory. Each question is buried in ~53 sessions.
| Metric | Score |
|---|---|
| Recall@5 (any gold session in top-5) | 89.4% |
| Recall-all@5 (all gold sessions in top-5) | 84.8% |
| nDCG@5 (ranking quality) | 87.4% |
HotpotQA — 200 multi-hop questions
| System | BOTH_FOUND@5 |
|---|---|
| YourMemory (vector + BM25 + entity graph) | 71.5% |
| YourMemory (no entity edges) | 59.5% |
Entity graph edges add +12 pp — they traverse from Fact 1 to Fact 2 even when Fact 2 has low embedding similarity to the query.
Writeup: I built memory decay for AI agents using the Ebbinghaus forgetting curve
🚀 Quick Start
Python 3.11–3.14. No Docker, no database setup. All memory stored locally in ~/.yourmemory/.
pip install yourmemory
yourmemory-register <your-token>
yourmemory-setup
Get your token: visit yourmemoryai.xyz → enter your email → verify with a 6-digit code → copy your token.
yourmemory-setup auto-detects and wires up Claude Code, Claude Desktop, Cursor, Windsurf, and Cline, then asks which backend to use:
- DuckDB — zero setup, single local file (default)
- Postgres — shared / production; you provide a
DATABASE_URL(needs the pgvector extension)
Optional — smarter local extraction: YourMemory works out of the box with built-in heuristics. For higher-quality, fully-local fact extraction, install Ollama and
yourmemory-setuppulls the model (qwen2.5:7b, ~4.7 GB) automatically. Prefer the cloud? SetYOURMEMORY_EXTRACT_BACKEND=anthropic.
Or install from a binary — no Python required
Prefer not to touch pip? Grab the standalone binary for your platform from the latest release:
| Platform | Asset |
|---|---|
| macOS (Apple Silicon) | yourmemory-macos-arm64.tar.gz |
| macOS (Intel) | yourmemory-macos-x86_64.tar.gz |
| Linux (x86-64) | yourmemory-linux-x86_64.tar.gz |
| Windows (x86-64) | yourmemory-windows-x86_64.exe.zip |
# macOS / Linux — download, extract, run
tar -xzf yourmemory-macos-arm64.tar.gz
./yourmemory-macos-arm64 register <your-token>
./yourmemory-macos-arm64 setup
./yourmemory-macos-arm64 # start the server
One executable handles every command: register, setup, ask "<question>", path, and (with no args) starts the server.
Fully self-contained & offline — the binary bundles Python, every dependency, and both ML models (the embedding model + spaCy). Nothing is downloaded on first run. The trade-off is size (~2 GB). Build your own with a single command — ./build-binary.sh — and multi-platform release binaries are produced automatically by the build workflow.
🧠 How Memory Works
YourMemory treats memory as a living system — it grows, consolidates, forgets, and connects, the way a brain does.
Consolidation — N → 1
Most memory tools just keep growing. YourMemory watches for clusters of related facts and, once enough accumulate, compresses them into a single clean summary — archiving the originals (never deleting, so nothing is lost).
flowchart LR
subgraph before [Related facts pile up]
A1["Railway uses Nixpacks"]
A2["Railway on Pro plan"]
A3["Railway env vars hold<br/>the Postgres URL"]
A4["Deploys on Railway<br/>with Postgres"]
end
before --> C{"cluster +<br/>LLM summarize"}
C --> S["✨ Summary<br/>Deploys on Railway (Pro,<br/>Nixpacks) with Postgres<br/>via env vars"]
C -.->|"archived, recoverable"| ARC[("archive")]
style S fill:#0a2540,stroke:#5eead4,color:#fff
style C fill:#0c2b3a,stroke:#19cdff,color:#fff
Real example from one production store: 444 memories → 16 summaries — same knowledge, a fraction of the noise. Consolidation is event-driven (triggered when related memories pile up), not a blind nightly job.
Decay — the forgetting curve
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)
active_days counts only days you were active — vacations don't cause memory loss. Memories below strength 0.05 are pruned automatically. Each category ages at its own rate:
| Category | Half-life | Best for |
|---|---|---|
strategy |
~38 days | Patterns that worked, architectural decisions |
fact |
~24 days | Preferences, identity, stable knowledge |
assumption |
~19 days | Inferred context, uncertain beliefs |
failure |
~11 days | Errors, wrong approaches, environment-specific issues |
Chain-aware pruning: a decayed memory is kept alive if any graph neighbour is still strong — load-bearing context survives even when rarely queried directly.
Hybrid Retrieval — Vector + BM25 + Graph
Recall runs in two rounds so it surfaces both what you asked for and what you forgot to ask for:
flowchart LR
Q["query"] --> R1["Vector + BM25<br/>hybrid search"]
R1 --> R2["Graph expansion<br/>(what you forgot to ask)"]
R2 --> S["rank by<br/>similarity × strength"]
S --> OUT["🎯 Ranked memories"]
style OUT fill:#0a2540,stroke:#19cdff,color:#fff
Subject-aware deduplication runs before every store — it embeds the subject of each sentence so "Sachit uses DuckDB" and "YourMemory uses DuckDB" stay separate (different entities), while "YourMemory uses DuckDB" and "YourMemory stores data in DuckDB" merge (same entity). No hardcoded word lists; generalises to any language.
🔒 Trust & Audit Trail
Enterprises won't let an opaque black box store their data. So every operation — read, write, update, delete, consolidation — is appended to a hash-chained, tamper-evident audit log.
flowchart LR
E0["GENESIS"] --> E1
subgraph E1 [Event 1]
H1["row_hash =<br/>sha256(prev + data)"]
end
E1 --> E2
subgraph E2 [Event 2]
H2["row_hash =<br/>sha256(#1.hash + data)"]
end
E2 --> E3
subgraph E3 [Event 3]
H3["row_hash =<br/>sha256(#2.hash + data)"]
end
E3 --> V{"GET /audit/verify"}
V -->|chain intact| OK["✅ verified"]
V -->|any row altered| BAD["❌ chain breaks<br/>at that row"]
style OK fill:#0a2540,stroke:#5eead4,color:#fff
style BAD fill:#3a0c14,stroke:#fb7185,color:#fff
Each row records the timestamp, actor user + agent, action, operation, target memory, source (http vs mcp), and the previous row's hash. Change any historical record and verify_chain() pinpoints exactly where the chain broke.
GET /audit # browse the trail (filter by user / action / operation)
GET /audit/verify # cryptographically verify the chain is untampered
POST /audit/prune # retention-based cleanup (90-day minimum, never lower)
Audit logging is fail-open — it never blocks a memory operation — and read/list events from the dashboard's own render loop are excluded, so the trail stays signal, not noise.
👥 Team Memory Pools
Give a whole team's agents one shared brain — without leaking anyone's private context. Memories are either shared (visible to the pool) or private (visible only to their owner).
flowchart TB
P(("🧠 Team Pool<br/>shared memory"))
A["Alice's agent"] <-->|shared| P
B["Bob's agent"] <-->|shared| P
C["Carol's agent"] <-->|shared| P
A -. private .-> AP["🔒 Alice-only"]
B -. private .-> BP["🔒 Bob-only"]
style P fill:#0a2540,stroke:#19cdff,color:#fff
style AP fill:#0c1424,stroke:#5a6b80,color:#8294a8
style BP fill:#0c1424,stroke:#5a6b80,color:#8294a8
Role-based access is enforced per agent — what one engineer's agent learns, the whole team benefits from instantly; sensitive context stays scoped to its owner.
POST /pools # create a pool
POST /pools/{id}/members # add a member (with role)
POST /pools/{id}/memories # contribute a shared memory
POST /pools/{id}/retrieve # recall across the pool
🛡️ Data Rights & Compliance
Because memory that stores real data needs the controls to be trusted with it:
| Right | Endpoint | What it does |
|---|---|---|
| Access (DSAR export) | GET /users/{id}/export |
Full export of everything stored for a user |
| Erasure (right to forget) | DELETE /users/{id}/memories |
One-command purge of a user's memories |
| Portability | POST /users/{id}/import |
Re-import a previous export |
| Recoverability | GET /users/{id}/archive |
Retrieve consolidated-away originals |
Combined with the hash-chained audit trail and 90-day retention floor, these map directly onto the controls documented in SECURITY.md (SOC 2-aligned).
🎛️ Dashboards
Two built-in browser UIs — no extra setup, they start automatically with the server.
Memory Dashboard — http://localhost:3033/ui
A full read/write view with Memories · Audit · Pools tabs: stats bar (Strong / Fading / Near-prune), per-agent tabs, memory cards with live strength bars, category filters, the audit trail, and pool management.
Graph Visualiser — http://localhost:3033/graph
An interactive force-directed map of how memories connect — root memory as a bright node, neighbours color-coded by category, edge thickness = connection strength. Drag, zoom, and click any node for full content.
http://localhost:3033/graph?memoryId=42&userId=alex&depth=2
🔧 MCP Tools
Three tools, called by your AI automatically.
| Tool | When your AI calls it | What it does |
|---|---|---|
recall_memory(query, current_path?) |
Start of every task | Surfaces memories ranked by similarity × decay strength; spatial boost for path-matched memories |
store_memory(content, importance, category?, context_paths?) |
After learning something new | Embeds, deduplicates, stores with decay; tags optional file/dir paths |
update_memory(id, new_content, importance) |
When a stored fact is outdated | Re-embeds and replaces; logs the change to the audit trail |
# Store with spatial context
store_memory(
"Alex prefers tabs over spaces in Python",
importance=0.9, category="fact",
context_paths=["/projects/backend"],
)
# Next session — spatial boost fires when working in that directory
recall_memory("Python formatting", current_path="/projects/backend")
# → {"content": "Alex prefers tabs over spaces in Python", "strength": 0.87}
⚡ Ask Without an LLM Call
The only memory system that can answer questions without making any LLM API call:
yourmemory ask "what database does this project use"
# → YourMemory uses DuckDB locally and Postgres in production.
yourmemory ask "how do I fix a kubernetes deployment"
# → Not enough memory context to answer without an LLM.
When memory is strong enough it answers instantly — zero tokens, zero cloud cost, zero latency. When it isn't, it declines cleanly rather than hallucinating. Your query never leaves your machine.
🔀 API Proxy — Guaranteed Memory
MCP tools are called at the AI's discretion. The API proxy removes that uncertainty — it intercepts every LLM call, injects relevant memories automatically, and handles store_memory / update_memory with no model configuration.
Start the server (yourmemory), then point your client at localhost:3033:
from anthropic import Anthropic
client = Anthropic(
api_key="sk-ant-...",
base_url="http://localhost:3033/proxy/anthropic",
default_headers={"X-YourMemory-User": "alex"}, # per-user memory
)
# Memory is injected automatically — no other changes needed
response = client.messages.create(
model="claude-opus-4-8",
max_tokens=1024,
messages=[{"role": "user", "content": "What database do I use?"}],
)
OpenAI works identically via base_url="http://localhost:3033/proxy/openai".
🏗️ Architecture & Stack
flowchart LR
C["Your AI client<br/>Claude · Cursor · any MCP"] <--> Y["🧠 YourMemory"]
Y --> M[("Memory<br/>store")]
Y --> A[("Audit<br/>ledger")]
style Y fill:#0a2540,stroke:#19cdff,color:#fff
style M fill:#0c1a2c,stroke:#5eead4,color:#fff
style A fill:#0c1a2c,stroke:#5eead4,color:#fff
| Component | Role |
|---|---|
| DuckDB | Default vector store — zero setup, native cosine similarity |
| PostgreSQL + pgvector | Optional — for teams or large datasets |
| NetworkX | Default graph backend (~/.yourmemory/graph.pkl) |
| Neo4j | Optional graph backend |
| sentence-transformers | Local embeddings (multi-qa-mpnet-base-dot-v1, 768 dims) |
| spaCy | Local NLP for deduplication and entity extraction |
| APScheduler | Automatic decay + pruning |
🩺 Troubleshooting
Writes hang / time out (DuckDB single-writer lock). If both the MCP server and the HTTP server run at once, they compete for the DuckDB write lock. Fix:
pkill -f yourmemory 2>/dev/null || true
rm -f ~/.yourmemory/memories.duckdb.wal ~/.yourmemory/memories.duckdb.lock 2>/dev/null || true
# restart your client
Running Claude Desktop (MCP) and Claude Code (hooks) simultaneously? Use SQLite instead — it handles concurrent readers/writers cleanly:
DATABASE_URL=sqlite:///~/.yourmemory/memories.db
🤝 Contributing
PRs welcome — see CONTRIBUTORS.md.
📚 Dataset References
- LoCoMo — Maharana et al. (2024)
- LongMemEval — Wu et al. (2024)
- HotpotQA — Yang et al. (2018)
📄 License
Copyright 2026 Sachit Misra — Licensed under CC-BY-NC-4.0.
Free for personal use, education, academic research, and open-source projects. Commercial use requires a separate written agreement → mishrasachit1@gmail.com
YourMemory MCP Fragen
Wie füge ich YourMemory MCP zu Claude Code hinzu?
Führe claude mcp add yourmemory -- uvx yourmemory in deinem Terminal aus. Füge --scope user hinzu, damit der Server in jedem Projekt verfügbar ist.
Wie füge ich YourMemory MCP zu Cursor hinzu?
Öffne ~/.cursor/mcp.json und füge den Server unter mcpServers hinzu, mit der Cursor-Config aus dem Installationsabschnitt oben.
Speichert YourMemory Daten lokal?
Ja, es läuft vollständig auf deiner Maschine und nutzt standardmäßig DuckDB mit einer einzelnen lokalen Datei, sodass keine Daten dein System verlassen.
Welche MCP-Clients funktionieren mit YourMemory?
Es funktioniert mit Claude, Cursor, Cline, Windsurf oder jedem anderen MCP-Client; das Setup erkennt gängige Clients automatisch.
Wie funktioniert der Gedächtnis-Zerfall in YourMemory?
Jede Erinnerung altert nach einer Ebbinghaus-Vergessenskurve; veraltete, ungenutzte Fakten verblassen, während wichtige oder häufig abgerufene Informationen bestehen bleiben. Erinnerungen mit einer Stärke unter 0.05 werden gelöscht.
Welche Abrufmethoden nutzt YourMemory?
Der Recall kombiniert Vektorsuche, BM25 und Entity-Graph-Expansion und rankt die Ergebnisse nach Ähnlichkeit multipliziert mit der Stärke.
Wie installiere ich YourMemory?
Installiere es über PyPI, registriere einen Token und führe das Setup aus; eine standalone Binary ist zudem für macOS, Linux und Windows verfügbar.