YourMemory

YourMemory

Your 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](https://sachitrafa.github.io/YourMemory/marketing/interactive.html) · [Website](https://yourmemoryai.xyz) · [Benchmarks](BENCHMARKS.md)

---

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 AI something"] --> B["Extract durable facts"] B --> C["Dedup + embed

• graph-link"] C --> D[("Memory

store")] D -->|"related facts pile up"| E["✨ Consolidate N → 1 summary"] D -->|"stale + unused"| F["📉 Decay

• prune"] D -->|"new session"| G["♻️ Recall

hybrid + graph"] E --> D G --> H["🤖 Your agent picks up where 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

One command to install. DuckDB by default (zero setup), Postgres + pgvector for teams.

---

Table of Contents

• 🏆 Benchmarks
• 🚀 Quick Start
• 🧠 How Memory Works
• Consolidation
• Decay
• Hybrid Retrieval
• 🔒 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.

HotpotQA — 200 multi-hop questions

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 yourmemory-setup

Get your token: visit [yourmemoryai.xyz](https://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-setup pulls the model (qwen2.5:7b, ~4.7 GB) automatically. Prefer the cloud? Set YOURMEMORY_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:

# macOS / Linux — download, extract, run

tar -xzf yourmemory-macos-arm64.tar.gz ./yourmemory-macos-arm64 register ./yourmemory-macos-arm64 setup ./yourmemory-macos-arm64 # start the server

One executable handles every command: register, setup, ask " ", 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 the Postgres URL"] A4["Deploys on Railway with Postgres"] end before --> C{"cluster + LLM summarize"} C --> S["✨ Summary Deploys on Railway (Pro, Nixpacks) with Postgres 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:

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 hybrid search"] R1 --> R2["Graph expansion (what you forgot to ask)"] R2 --> S["rank by 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 = sha256(prev + data)"] end E1 --> E2 subgraph E2 [Event 2] H2["row_hash = sha256(#1.hash + data)"] end E2 --> E3 subgraph E3 [Event 3] H3["row_hash = sha256(#2.hash + data)"] end E3 -