io.github.sachitrafa/cognitive-ai-memory

Persistent memory for AI agents — built on the science of how humans remember.

What Is YourMemory?

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 with a one-command install that plugs into Claude, Cursor, Cline, Windsurf, or any MCP client. It gives your AI a persistent memory layer modelled on human cognition:

• Things that matter stick — importance score controls how quickly a memory decays
• Outdated facts get replaced — subject-aware deduplication merges or supersedes memories automatically
• Related context surfaces together — entity graph links memories that share people, places, or concepts
• Old memories fade naturally — Ebbinghaus forgetting curve prunes stale context every 24 hours

Zero infrastructure required. SQLite by default, Postgres for teams.

Table of Contents

• Benchmarks
• Quick Start
• Memory Dashboard
• Ask Without an LLM Call
• API Proxy — Guaranteed Memory
• MCP Tools
• How It Works
• Multi-Agent Memory
• Stack
• Architecture
• Troubleshooting
• Contributing

Benchmarks

Three external datasets, all scripts open source and reproducible. Full methodology in BENCHMARKS.md.

LongMemEval-S — 500 questions, ~53 distractor sessions each

The hardest standard benchmark for long-term memory systems. Each question is backed by ~53 conversation sessions; the model must retrieve the right one(s) from the haystack.

By question type (Recall@5):

LoCoMo-10 — 1,534 QA pairs across 10 multi-session conversations

Conversations spanning weeks to months. Every system ingests the same session summaries in the same order.

2× better recall than Zep Cloud across all 10 samples. * Supermemory and Mem0 exhausted free-tier quotas mid-benchmark; scores computed over full 1,534 pairs using 0 for unfinished samples.

HotpotQA — 200 multi-hop questions requiring two facts from different articles

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

Supports Python 3.11–3.14. No Docker, no database setup. All memory stored locally in ~/.yourmemory/.

Before you install — what this does

Activation steps:

1. Visit yourmemoryai.xyz and enter your email
2. Check your inbox for a 6-digit verification code
3. Enter the code on the website — your token is shown instantly
4. Run the three commands below:

pip install yourmemory
yourmemory-register <your-token>
yourmemory-setup

Requirement — local model: YourMemory extracts memories with a local model via Ollama. Install Ollama and start it — yourmemory-setup then pulls the default model (qwen2.5:7b, ~4.7 GB) automatically. To use a lighter model you already have, set YOURMEMORY_OLLAMA_MODEL (e.g. llama3.2:3b) before setup.

Backend: yourmemory-setup asks whether to use DuckDB (zero setup, default) or Postgres (shared/production — you provide a DATABASE_URL; needs the pgvector extension).

Memory Dashboard

Two built-in browser UIs — no extra setup, start automatically with the MCP server.

Memory Browser — http://localhost:3033/ui

A full read/write view of everything stored in memory.

Pass ?user=<id> to pre-load a specific user: http://localhost:3033/ui?user=sachit

Graph Visualiser — http://localhost:3033/graph

An interactive force-directed map of how memories connect.

http://localhost:3033/graph?memoryId=42&userId=sachit&depth=2

• Root memory as a larger cyan node; neighbours color-coded by category
• Edge thickness = connection strength
• Click any node for full content; drag, zoom, reposition freely

Ask Without Calling the API

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 "what port does the dashboard run on"
# → 3033

yourmemory ask "how do I fix a kubernetes deployment"
# → Not enough memory context to answer without Claude.

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.

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 without any model configuration.

Start the YourMemory server (yourmemory), then point your LLM client at localhost:3033:

OpenAI

from openai import OpenAI

client = OpenAI(
    api_key="sk-...",
    base_url="http://localhost:3033/proxy/openai"
)

# Memory is injected automatically — no other changes needed
response = client.chat.completions.create(
    model="gpt-4o",
    messages=[{"role": "user", "content": "What database do I use?"}]
)

Anthropic

from anthropic import Anthropic

client = Anthropic(
    api_key="sk-ant-...",
    base_url="http://localhost:3033/proxy/anthropic"
)

response = client.messages.create(
    model="claude-opus-4-8",
    max_tokens=1024,
    messages=[{"role": "user", "content": "What database do I use?"}]
)

Per-user memory

Pass X-YourMemory-User to isolate memory per person:

client = OpenAI(
    api_key="sk-...",
    base_url="http://localhost:3033/proxy/openai",
    default_headers={"X-YourMemory-User": "sachit"}
)

How it works

On every request the proxy:

1. Recalls relevant memories and injects them into the system prompt — guaranteed, no tool call needed
2. Adds store_memory and update_memory as tools — the model calls them when it learns something new
3. Executes those tool calls locally and returns the final response transparently

Streaming note: recall injection works for all requests. Tool call interception (store/update) works for non-streaming requests only — streaming passes through and tools execute on the next turn.

MCP Tools

Three tools, called by your AI automatically.

# 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 fires when working in that directory
recall_memory("Python formatting", current_path="/projects/backend")
# → {"content": "Sachit prefers tabs over spaces in Python", "strength": 0.87}

Memory categories control decay rate

How It Works

Ebbinghaus 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)
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. Memories below strength 0.05 are pruned automatically every 24 hours.

Session wrap-up: recalled memory IDs are tracked per session. When a session goes idle (30 min default), those memories get a recall_count boost. Set YOURMEMORY_SESSION_IDLE to change the window.

Recall throttling: identical (user, query) pairs are cached within a configurable window. Set YOURMEMORY_RECALL_COOLDOWN (seconds, default 0 = off).

Hybrid Retrieval: Vector + BM25 + Entity Graph

Retrieval runs in two rounds:

Round 1 — Hybrid search: cosine similarity + BM25 keyword scoring, returns top-k candidates above threshold.

Round 2 — Graph expansion: BFS traversal from Round 1 seeds surfaces memories that share context but not vocabulary — connected via semantic or entity edges.

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 shared entity "backend")

Chain-aware pruning: a decayed memory is kept alive if any graph neighbour is above the prune threshold. Related memories age together.

Subject-Aware Deduplication

Before storing, YourMemory checks whether the new memory is about the same entity as the nearest existing one:

"Sachit uses DuckDB"      vs  "YourMemory uses DuckDB"
 subject: Sachit               subject: YourMemory
 → different entities → stored separately ✓

"YourMemory uses DuckDB"  vs  "YourMemory stores data in DuckDB"
 subject: YourMemory           subject: YourMemory
 → same entity → merged ✓

Subject comparison embeds the first two tokens of each sentence — no hardcoded word lists, generalises to any language.

Multi-Agent Memory

Multiple agents can share one 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)

# Agent stores a private failure memory
store_memory(
    "Staging uses self-signed cert — skip SSL verify",
    importance=0.7, category="failure",
    api_key="ym_xxxx", visibility="private"
)

# Recalls shared + its own private memories; other agents see shared only
recall_memory("staging SSL", api_key="ym_xxxx")

Stack

Architecture

Claude / Cline / Cursor / Any MCP client
    │
    ├── recall_memory(query, current_path?, api_key?)
    │       └── throttle check → embed → hybrid search (Round 1)
    │               → graph BFS expansion (Round 2)
    │               → score = sim × strength
    │               → spatial boost (+0.08) if current_path matches context_paths
    │               → temporal boost (+0.25) if query has time window expression
    │               → session tracking → recall_count bump on session end
    │
    ├── store_memory(content, importance, category?, context_paths?, api_key?)
    │       └── question? → reject
    │               subject-aware dedup → same entity? merge/reinforce : new
    │               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)
    ├── created_at TIMESTAMP         └── bolt://localhost:7687
    ├── visibility VARCHAR
    ├── agent_id VARCHAR
    user_activity  (active days log)
    memory_history (supersession audit)

Troubleshooting

Writes hang / time out in Claude Desktop

Symptom: store_memory or update_memory never returns; the MCP server appears frozen.

Cause: DuckDB enforces a single-writer-per-process constraint. If you also have the YourMemory HTTP server running (e.g. for Claude Code hooks), both processes compete for the same write lock and one hangs indefinitely.

Fix — kill the lock holder and restart:

# Kill any lingering YourMemory process holding the DuckDB write lock
pkill -f yourmemory 2>/dev/null || true

# Remove stale DuckDB WAL/lock files if the process exited uncleanly
rm -f ~/.yourmemory/memories.duckdb.wal \
      ~/.yourmemory/memories.duckdb.lock 2>/dev/null || true

# Restart Claude Desktop

As of v1.4.57+, DuckDB connections time out after 8 seconds and surface this exact error message with the fix above instead of hanging forever.

If you run both Claude Desktop (MCP) and Claude Code (hooks) at the same time: Use the environment variable DATABASE_URL=sqlite:///~/.yourmemory/memories.db in your MCP server config. SQLite's WAL mode handles concurrent readers/writers cleanly and has no single-writer process limit.

Contributing

PRs are welcome. See CONTRIBUTORS.md for contributors who have already improved YourMemory.

Dataset References

• LoCoMo — Maharana et al. (2024). LoCoMo: Long Context Multimodal Benchmark for Dialogue. Snap Research.
• LongMemEval — Wu et al. (2024). LongMemEval: Benchmarking Chat Assistants on Long-Term Interactive Memory.
• HotpotQA — Yang et al. (2018). HotpotQA: A Dataset for Diverse, Explainable Multi-hop Question Answering.

License

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