{
  "markdown": "<!-- mcp-name: io.github.sachitrafa/yourmemory -->\n<div align=\"center\">\n<img src=\"logo.svg.png\" alt=\"YourMemory\" width=\"110\" /><br>\n<h1>YourMemory</h1>\n\n### Your AI has the memory of a goldfish. Not anymore.\n\n**Persistent, self-improving memory for AI agents — built on the science of how humans remember.**\n\n[![PyPI](https://img.shields.io/pypi/v/yourmemory?color=blue&logo=pypi&logoColor=white)](https://pypi.org/project/yourmemory/)\n[![PyPI Downloads](https://img.shields.io/pypi/dm/yourmemory?color=brightgreen)](https://pypi.org/project/yourmemory/)\n[![Python](https://img.shields.io/pypi/pyversions/yourmemory)](https://pypi.org/project/yourmemory/)\n[![License: CC BY-NC 4.0](https://img.shields.io/badge/license-CC%20BY--NC%204.0-lightgrey)](https://creativecommons.org/licenses/by-nc/4.0/)\n[![GitHub Stars](https://img.shields.io/github/stars/sachitrafa/YourMemory?style=social)](https://github.com/sachitrafa/YourMemory)\n\n[![LoCoMo Recall@5](https://img.shields.io/badge/LoCoMo%20Recall%405-59%25-brightgreen)](BENCHMARKS.md)\n[![LongMemEval Recall@5](https://img.shields.io/badge/LongMemEval%20Recall%405-89.4%25-brightgreen)](BENCHMARKS.md)\n[![HotpotQA BOTH@5](https://img.shields.io/badge/HotpotQA%20BOTH%405-71.5%25-brightgreen)](BENCHMARKS.md)\n[![MCP Native](https://img.shields.io/badge/MCP-native-19cdff)](https://modelcontextprotocol.io)\n\n<br>\n\n**[▶ Try the live interactive demo](https://sachitrafa.github.io/YourMemory/marketing/interactive.html)** · **[Website](https://yourmemoryai.xyz)** · **[Benchmarks](BENCHMARKS.md)**\n\n</div>\n\n---\n\n## The problem\n\nEvery morning your AI agent treats you like a stranger. Same context re-explained. Same preferences forgotten. Every session starts from zero.\n\nMost \"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.\n\n**YourMemory is different: memory that works like a brain, not a database.**\n\n```mermaid\nflowchart LR\n    A[\"🧠 You tell your<br/>AI something\"] --> B[\"Extract durable<br/>facts\"]\n    B --> C[\"Dedup + embed<br/>+ graph-link\"]\n    C --> D[(\"Memory<br/>store\")]\n    D -->|\"related facts pile up\"| E[\"✨ Consolidate<br/>N → 1 summary\"]\n    D -->|\"stale + unused\"| F[\"📉 Decay<br/>+ prune\"]\n    D -->|\"new session\"| G[\"♻️ Recall<br/>hybrid + graph\"]\n    E --> D\n    G --> H[\"🤖 Your agent<br/>picks up where<br/>it left off\"]\n    style D fill:#0a2540,stroke:#19cdff,color:#fff\n    style E fill:#0c2b3a,stroke:#5eead4,color:#fff\n    style H fill:#0c2b3a,stroke:#19cdff,color:#fff\n```\n\n---\n\n## ✨ What makes it different\n\n| | Feature | What it does |\n|---|---|---|\n| 🧠 | **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**. |\n| 📉 | **Biological decay** | Every memory ages on an **Ebbinghaus forgetting curve**. Stale, unused facts fade; important and frequently-recalled ones persist. |\n| 🔗 | **Entity graph** | Memories link by shared people, places, and concepts — so recall surfaces what you *forgot to ask for*. |\n| ♻️ | **Survives context resets** | When the context window compacts, YourMemory hands the working context back — no re-reading files to figure out where you were. |\n| 🔒 | **Tamper-evident audit trail** | Every read / write / delete is logged in a **hash-chained** ledger. Alter one record and the chain breaks. |\n| 👥 | **Team memory pools** | Role-based shared memory, so a whole team's agents draw on the same institutional knowledge — with private memories kept private. |\n| 🛡️ | **Data rights built in** | One-command **export** (right to access) and **right-to-forget** (purge), plus SOC 2-aligned controls. |\n| 🔌 | **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. |\n\n> One command to install. DuckDB by default (zero setup), Postgres + pgvector for teams.\n\n---\n\n## Table of Contents\n\n- [🏆 Benchmarks](#-benchmarks)\n- [🚀 Quick Start](#-quick-start)\n- [🧠 How Memory Works](#-how-memory-works)\n  - [Consolidation](#consolidation--n--1)\n  - [Decay](#decay--the-forgetting-curve)\n  - [Hybrid Retrieval](#hybrid-retrieval--vector--bm25--graph)\n- [🔒 Trust & Audit Trail](#-trust--audit-trail)\n- [👥 Team Memory Pools](#-team-memory-pools)\n- [🛡️ Data Rights & Compliance](#️-data-rights--compliance)\n- [🎛️ Dashboards](#️-dashboards)\n- [🔧 MCP Tools](#-mcp-tools)\n- [⚡ Ask Without an LLM Call](#-ask-without-an-llm-call)\n- [🔀 API Proxy — Guaranteed Memory](#-api-proxy--guaranteed-memory)\n- [🏗️ Architecture & Stack](#️-architecture--stack)\n- [🩺 Troubleshooting](#-troubleshooting)\n- [🤝 Contributing](#-contributing)\n\n---\n\n## 🏆 Benchmarks\n\nThree external datasets. Every number independently reproducible — [benchmark code lives in the repo](benchmarks/). Full methodology in [BENCHMARKS.md](BENCHMARKS.md).\n\n### LoCoMo-10 — multi-session conversational memory\n\n```mermaid\nxychart-beta\n    title \"Recall@5 · LoCoMo-10 (higher is better)\"\n    x-axis [\"Mem0\", \"Zep Cloud\", \"Supermemory\", \"YourMemory\"]\n    y-axis \"Recall@5 percent\" 0 --> 70\n    bar [18, 28, 31, 59]\n```\n\n> **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.\n\n### LongMemEval-S — 500 questions, ~53 distractor sessions each\n\nThe hardest standard benchmark for long-term memory. Each question is buried in ~53 sessions.\n\n| Metric | Score |\n|--------|:-----:|\n| **Recall@5** (any gold session in top-5) | **89.4%** |\n| Recall-all@5 (all gold sessions in top-5) | 84.8% |\n| nDCG@5 (ranking quality) | 87.4% |\n\n### HotpotQA — 200 multi-hop questions\n\n| System | BOTH_FOUND@5 |\n|--------|:------------:|\n| **YourMemory** (vector + BM25 + entity graph) | **71.5%** |\n| YourMemory (no entity edges) | 59.5% |\n\nEntity graph edges add **+12 pp** — they traverse from Fact 1 to Fact 2 even when Fact 2 has low embedding similarity to the query.\n\n*Writeup: [I built memory decay for AI agents using the Ebbinghaus forgetting curve](https://dev.to/sachit_mishra_686a94d1bb5/i-built-memory-decay-for-ai-agents-using-the-ebbinghaus-forgetting-curve-1b0e)*\n\n---\n\n## 🚀 Quick Start\n\n**Python 3.11–3.14. No Docker, no database setup. All memory stored locally in `~/.yourmemory/`.**\n\n```bash\npip install yourmemory\nyourmemory-register <your-token>\nyourmemory-setup\n```\n\n**Get your token:** visit **[yourmemoryai.xyz](https://yourmemoryai.xyz/)** → enter your email → verify with a 6-digit code → copy your token.\n\n`yourmemory-setup` auto-detects and wires up **Claude Code, Claude Desktop, Cursor, Windsurf, and Cline**, then asks which backend to use:\n\n- **DuckDB** — zero setup, single local file *(default)*\n- **Postgres** — shared / production; you provide a `DATABASE_URL` (needs the pgvector extension)\n\n> **Optional — smarter local extraction:** YourMemory works out of the box with built-in heuristics. For higher-quality, fully-local fact extraction, install [Ollama](https://ollama.com) and `yourmemory-setup` pulls the model (`qwen2.5:7b`, ~4.7 GB) automatically. Prefer the cloud? Set `YOURMEMORY_EXTRACT_BACKEND=anthropic`.\n\n### Or install from a binary — no Python required\n\nPrefer not to touch pip? Grab the standalone binary for your platform from the [latest release](https://github.com/sachitrafa/YourMemory/releases/latest):\n\n| Platform | Asset |\n|----------|-------|\n| macOS (Apple Silicon) | `yourmemory-macos-arm64.tar.gz` |\n| macOS (Intel) | `yourmemory-macos-x86_64.tar.gz` |\n| Linux (x86-64) | `yourmemory-linux-x86_64.tar.gz` |\n| Windows (x86-64) | `yourmemory-windows-x86_64.exe.zip` |\n\n```bash\n# macOS / Linux — download, extract, run\ntar -xzf yourmemory-macos-arm64.tar.gz\n./yourmemory-macos-arm64 register <your-token>\n./yourmemory-macos-arm64 setup\n./yourmemory-macos-arm64            # start the server\n```\n\nOne executable handles every command: `register`, `setup`, `ask \"<question>\"`, `path`, and (with no args) starts the server.\n\n**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](.github/workflows/build-binary.yml).\n\n---\n\n## 🧠 How Memory Works\n\nYourMemory treats memory as a living system — it **grows, consolidates, forgets, and connects**, the way a brain does.\n\n### Consolidation — *N → 1*\n\nMost 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).\n\n```mermaid\nflowchart LR\n    subgraph before [Related facts pile up]\n        A1[\"Railway uses Nixpacks\"]\n        A2[\"Railway on Pro plan\"]\n        A3[\"Railway env vars hold<br/>the Postgres URL\"]\n        A4[\"Deploys on Railway<br/>with Postgres\"]\n    end\n    before --> C{\"cluster +<br/>LLM summarize\"}\n    C --> S[\"✨ Summary<br/>Deploys on Railway (Pro,<br/>Nixpacks) with Postgres<br/>via env vars\"]\n    C -.->|\"archived, recoverable\"| ARC[(\"archive\")]\n    style S fill:#0a2540,stroke:#5eead4,color:#fff\n    style C fill:#0c2b3a,stroke:#19cdff,color:#fff\n```\n\n> 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.\n\n### Decay — the forgetting curve\n\nMemory strength decays exponentially. Importance and recall frequency slow that decay:\n\n```\neffective_λ  = base_λ × (1 − importance × 0.8)\nstrength     = clamp(importance × e^(−effective_λ × active_days) × (1 + recall_count × 0.2), 0, 1)\n```\n\n`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:\n\n| Category | Half-life | Best for |\n|----------|:---------:|----------|\n| `strategy` | ~38 days | Patterns that worked, architectural decisions |\n| `fact` | ~24 days | Preferences, identity, stable knowledge |\n| `assumption` | ~19 days | Inferred context, uncertain beliefs |\n| `failure` | ~11 days | Errors, wrong approaches, environment-specific issues |\n\n**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.\n\n### Hybrid Retrieval — Vector + BM25 + Graph\n\nRecall runs in two rounds so it surfaces both what you asked for *and* what you forgot to ask for:\n\n```mermaid\nflowchart LR\n    Q[\"query\"] --> R1[\"Vector + BM25<br/>hybrid search\"]\n    R1 --> R2[\"Graph expansion<br/>(what you forgot to ask)\"]\n    R2 --> S[\"rank by<br/>similarity × strength\"]\n    S --> OUT[\"🎯 Ranked memories\"]\n    style OUT fill:#0a2540,stroke:#19cdff,color:#fff\n```\n\n**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.\n\n---\n\n## 🔒 Trust & Audit Trail\n\nEnterprises 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**.\n\n```mermaid\nflowchart LR\n    E0[\"GENESIS\"] --> E1\n    subgraph E1 [Event 1]\n        H1[\"row_hash =<br/>sha256(prev + data)\"]\n    end\n    E1 --> E2\n    subgraph E2 [Event 2]\n        H2[\"row_hash =<br/>sha256(#1.hash + data)\"]\n    end\n    E2 --> E3\n    subgraph E3 [Event 3]\n        H3[\"row_hash =<br/>sha256(#2.hash + data)\"]\n    end\n    E3 --> V{\"GET /audit/verify\"}\n    V -->|chain intact| OK[\"✅ verified\"]\n    V -->|any row altered| BAD[\"❌ chain breaks<br/>at that row\"]\n    style OK fill:#0a2540,stroke:#5eead4,color:#fff\n    style BAD fill:#3a0c14,stroke:#fb7185,color:#fff\n```\n\nEach 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.\n\n```bash\nGET  /audit            # browse the trail (filter by user / action / operation)\nGET  /audit/verify     # cryptographically verify the chain is untampered\nPOST /audit/prune      # retention-based cleanup (90-day minimum, never lower)\n```\n\n> 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.\n\n---\n\n## 👥 Team Memory Pools\n\nGive 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).\n\n```mermaid\nflowchart TB\n    P((\"🧠 Team Pool<br/>shared memory\"))\n    A[\"Alice's agent\"] <-->|shared| P\n    B[\"Bob's agent\"] <-->|shared| P\n    C[\"Carol's agent\"] <-->|shared| P\n    A -. private .-> AP[\"🔒 Alice-only\"]\n    B -. private .-> BP[\"🔒 Bob-only\"]\n    style P fill:#0a2540,stroke:#19cdff,color:#fff\n    style AP fill:#0c1424,stroke:#5a6b80,color:#8294a8\n    style BP fill:#0c1424,stroke:#5a6b80,color:#8294a8\n```\n\nRole-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.\n\n```bash\nPOST   /pools                          # create a pool\nPOST   /pools/{id}/members             # add a member (with role)\nPOST   /pools/{id}/memories            # contribute a shared memory\nPOST   /pools/{id}/retrieve            # recall across the pool\n```\n\n---\n\n## 🛡️ Data Rights & Compliance\n\nBecause memory that stores real data needs the controls to be trusted with it:\n\n| Right | Endpoint | What it does |\n|-------|----------|--------------|\n| **Access** (DSAR export) | `GET /users/{id}/export` | Full export of everything stored for a user |\n| **Erasure** (right to forget) | `DELETE /users/{id}/memories` | One-command purge of a user's memories |\n| **Portability** | `POST /users/{id}/import` | Re-import a previous export |\n| **Recoverability** | `GET /users/{id}/archive` | Retrieve consolidated-away originals |\n\nCombined with the hash-chained audit trail and 90-day retention floor, these map directly onto the controls documented in [SECURITY.md](SECURITY.md) (SOC 2-aligned).\n\n---\n\n## 🎛️ Dashboards\n\nTwo built-in browser UIs — no extra setup, they start automatically with the server.\n\n### Memory Dashboard — `http://localhost:3033/ui`\n\nA 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.\n\n### Graph Visualiser — `http://localhost:3033/graph`\n\nAn 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.\n\n```\nhttp://localhost:3033/graph?memoryId=42&userId=alex&depth=2\n```\n\n---\n\n## 🔧 MCP Tools\n\nThree tools, called by your AI automatically.\n\n| Tool | When your AI calls it | What it does |\n|------|-----------------------|--------------|\n| `recall_memory(query, current_path?)` | Start of every task | Surfaces memories ranked by similarity × decay strength; spatial boost for path-matched memories |\n| `store_memory(content, importance, category?, context_paths?)` | After learning something new | Embeds, deduplicates, stores with decay; tags optional file/dir paths |\n| `update_memory(id, new_content, importance)` | When a stored fact is outdated | Re-embeds and replaces; logs the change to the audit trail |\n\n```python\n# Store with spatial context\nstore_memory(\n    \"Alex prefers tabs over spaces in Python\",\n    importance=0.9, category=\"fact\",\n    context_paths=[\"/projects/backend\"],\n)\n\n# Next session — spatial boost fires when working in that directory\nrecall_memory(\"Python formatting\", current_path=\"/projects/backend\")\n# → {\"content\": \"Alex prefers tabs over spaces in Python\", \"strength\": 0.87}\n```\n\n---\n\n## ⚡ Ask Without an LLM Call\n\nThe only memory system that can answer questions **without making any LLM API call**:\n\n```bash\nyourmemory ask \"what database does this project use\"\n# → YourMemory uses DuckDB locally and Postgres in production.\n\nyourmemory ask \"how do I fix a kubernetes deployment\"\n# → Not enough memory context to answer without an LLM.\n```\n\nWhen 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.\n\n---\n\n## 🔀 API Proxy — Guaranteed Memory\n\nMCP 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.\n\nStart the server (`yourmemory`), then point your client at `localhost:3033`:\n\n```python\nfrom anthropic import Anthropic\n\nclient = Anthropic(\n    api_key=\"sk-ant-...\",\n    base_url=\"http://localhost:3033/proxy/anthropic\",\n    default_headers={\"X-YourMemory-User\": \"alex\"},  # per-user memory\n)\n\n# Memory is injected automatically — no other changes needed\nresponse = client.messages.create(\n    model=\"claude-opus-4-8\",\n    max_tokens=1024,\n    messages=[{\"role\": \"user\", \"content\": \"What database do I use?\"}],\n)\n```\n\nOpenAI works identically via `base_url=\"http://localhost:3033/proxy/openai\"`.\n\n---\n\n## 🏗️ Architecture & Stack\n\n```mermaid\nflowchart LR\n    C[\"Your AI client<br/>Claude · Cursor · any MCP\"] <--> Y[\"🧠 YourMemory\"]\n    Y --> M[(\"Memory<br/>store\")]\n    Y --> A[(\"Audit<br/>ledger\")]\n    style Y fill:#0a2540,stroke:#19cdff,color:#fff\n    style M fill:#0c1a2c,stroke:#5eead4,color:#fff\n    style A fill:#0c1a2c,stroke:#5eead4,color:#fff\n```\n\n| Component | Role |\n|-----------|------|\n| **DuckDB** | Default vector store — zero setup, native cosine similarity |\n| **PostgreSQL + pgvector** | Optional — for teams or large datasets |\n| **NetworkX** | Default graph backend (`~/.yourmemory/graph.pkl`) |\n| **Neo4j** | Optional graph backend |\n| **sentence-transformers** | Local embeddings (`multi-qa-mpnet-base-dot-v1`, 768 dims) |\n| **spaCy** | Local NLP for deduplication and entity extraction |\n| **APScheduler** | Automatic decay + pruning |\n\n---\n\n## 🩺 Troubleshooting\n\n**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:\n\n```bash\npkill -f yourmemory 2>/dev/null || true\nrm -f ~/.yourmemory/memories.duckdb.wal ~/.yourmemory/memories.duckdb.lock 2>/dev/null || true\n# restart your client\n```\n\nRunning Claude Desktop (MCP) and Claude Code (hooks) simultaneously? Use SQLite instead — it handles concurrent readers/writers cleanly:\n`DATABASE_URL=sqlite:///~/.yourmemory/memories.db`\n\n---\n\n## 🤝 Contributing\n\nPRs welcome — see [CONTRIBUTORS.md](CONTRIBUTORS.md).\n\n## 📚 Dataset References\n\n- [LoCoMo](https://github.com/snap-research/locomo) — Maharana et al. (2024)\n- [LongMemEval](https://github.com/xiaowu0162/LongMemEval) — Wu et al. (2024)\n- [HotpotQA](https://hotpotqa.github.io/) — Yang et al. (2018)\n\n## 📄 License\n\nCopyright 2026 **Sachit Misra** — Licensed under [CC-BY-NC-4.0](LICENSE).\n\n**Free for** personal use, education, academic research, and open-source projects.\n**Commercial use** requires a separate written agreement → mishrasachit1@gmail.com\n\n<div align=\"center\"><br><b>Give your AI a memory worth keeping.</b><br><code>pip install yourmemory</code></div>\n",
  "bytes": 20000,
  "sha": "c000ce932459a51f1dff75dde3d764447254888d03dcfa83180fedaa6fa51487",
  "repo_slug": "sachitrafa/yourmemory",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_sachitrafa_yourmemory_e9c8a729/readme"
}