Recall — persistent, self-correcting memory for coding agents

Built for the Cognee "Hangover Part AI: Where's My Context?" hackathon (WeMakeDevs, Jun 29–Jul 5 2026). Track: Best Use of Open Source (self-hosted Cognee).

Your coding agent wakes up every session with amnesia. Recall gives it a memory that not only remembers your project's decisions and conventions — it self-corrects: when you fix the agent, it forgets the old pattern and reinforces the new one, so it stops making the same mistake next session.

The one-liner: Recall is a memory layer that knows when it's wrong.

The problem

Coding agents (Claude Code, Cursor) re-learn your project from scratch every session. You tell it "we use httpx, not requests" on Monday; on Tuesday it reaches for requests again. Plain RAG-over-your-repo doesn't fix this, because it never un-learns stale facts — it only appends. So the correction and the original mistake coexist in the store, retrieval returns both, and the model flips a coin. You didn't fix the mistake; you gave it a contradiction.

Why not just use Cognee's plugin?

Cognee already ships an official Claude Code plugin that gives an agent cross-session memory, auto-capture, and context injection. If Recall were just "give the agent memory," we'd be re-shipping the sponsor's own product.

Recall's edge is the one thing that plugin does not do: contradiction resolution. When you correct the agent, Recall doesn't merely store the new rule — it surgically deletes the old one so it can never resurface, then reinforces the replacement. Memory that only adds is a hoarder; Recall is memory that un-learns. That deletion is the whole product.

The idea

Recall is an MCP server sitting between your agent and a Cognee knowledge graph of your project. It uses the full memory lifecycle — not just retrieval:

Cognee verb	In Recall
remember (add + cognify)	Ingest repo, architectural decisions, past bug fixes, conventions
recall (search)	Before acting, the agent queries relevant decisions/conventions/gotchas
memify / improve	A user correction is captured and reinforced
forget (delete)	The deprecated decision is surgically removed so it stops resurfacing

Conventions are stored one dataset per topic, which is what makes forget() surgical: superseding a rule drops that topic's dataset and re-adds the new rule as active, rather than pruning the whole graph.

MCP tools the agent calls

Tool	What it does
recall_context(query)	Retrieve conventions/decisions relevant to the task (call this first).
remember_convention(topic, rule)	Store a new convention as a typed graph node.
correct_convention(topic, new_rule, supersedes)	The self-correction verb: forget the old rule, remember + reinforce the new one.
remember_repo(path)	Ingest a repository into project memory.
forget_convention(topic)	Surgically remove a deprecated convention.

Memory is organized with a typed ontology (Convention, Decision, Bug) so retrieval returns first-class rules — not raw text chunks.

The demo (the one moment everything serves)

1. Session 1: agent writes code with the wrong convention (requests). You correct it. → correction stored, old convention forgotten.
2. Session 2 (fresh context — "woke up in Vegas with no memory"): similar task, and the agent uses httpx unprompted. It remembered last night.
3. Show the knowledge graph: decisions, conventions, a contradiction resolved.

Layout

src/recall/
  memory.py     # Cognee wrapper: remember / recall / supersede / forget / visualize
  ontology.py   # Convention / Decision / Bug typed DataPoints
  server.py     # MCP server (FastMCP/stdio) exposing 6 tools to the agent
  config.py     # env + settings (loads .env by absolute path)
sample_repo/    # target project we ingest; uses `requests` on purpose. Has CLAUDE.md.
scripts/
  smoke_test.py       # reset -> remember -> recall -> supersede -> recall (proves the loop)
  reset.py            # wipe all memory (clean slate before a take)
  ingest.py           # seed the "before" state (requests) + ingest the repo
  demo_agent.py       # Session-2 "fresh agent": recalls, then writes httpx unprompted
  dump_conventions.py # text proof + pre-record verification gate
  render_graph.py     # render the knowledge graph to scratch/graph_<tag>.html
  demo_runner.py      # orchestrate a full take (--scripted for the deterministic backup)
docs/           # demo script, blog draft, plan

Quickstart

uv venv --python 3.12 && source .venv/bin/activate
uv pip install -e .
cp .env.example .env          # add your LLM_API_KEY (OpenAI); flags are preset
python scripts/smoke_test.py  # proves the self-correction loop end to end

Use it with your coding agent (MCP)

Register the server (user scope — no trust prompt):

claude mcp add recall -- "$(pwd)/.venv/bin/recall-server"
claude mcp list               # recall ✓ connected

Or rely on the project-scoped .mcp.json at the repo root (Claude Code prompts to approve it on first launch in this directory). Inside a session, /mcp lists the tools: recall_context, remember_convention, remember_decision, remember_bug, correct_convention, remember_repo, forget_convention, show_graph.

Reproduce the demo

See docs/DEMO_SETUP.md for the full recording runbook. The deterministic backup take is one command:

python scripts/demo_runner.py --scripted

What's verified

Reproducible checks (require LLM_API_KEY):

• python scripts/test_recall.py — automated assertions: a correction makes recall authoritatively return the new rule and drop the old one; multiple conventions + a Decision + a Bug all surface; forgetting one topic leaves the others intact (surgical independence). Exits non-zero on regression.
• python scripts/demo_runner.py --scripted — the full loop end to end with the repo ingested; ends on READY TO RECORD.
• bash scripts/agent_e2e.sh — the autonomous proof: a real headless Claude Code agent records the correction via correct_convention, then a fresh agent process consults recall_context and writes httpx unprompted.

Design notes & honest limitations

This is a focused prototype. What it does well, and where the edges are:

• Conventions are read as facts, not searched. recall returns active Convention/Decision/Bug nodes read directly from the typed graph, not via semantic completion. This is deliberate: we measured that GRAPH_COMPLETION — even scoped to the convention datasets and filtered to node_type=Convention — still returns the stale rule when the old code remains in the shared graph. A current rule is a fact to read, not a similarity match. Open-ended queries (no matching convention) still fall back to Cognee semantic search.
• One dataset per topic (conv::<name>) makes forget surgical and zero-cost, at the cost of graph fragmentation (weaker cross-topic reasoning).
• Local / single-user only. Runs on Cognee's embedded stores (SQLite + LanceDB + Kuzu) with access control and caching disabled. The graph DB is single-process-locked, so tooling can't open a second Cognee process while the MCP server is running (see docs/DEMO_SETUP.md).
• recall scans the graph to collect typed nodes — fine for typical projects; for very large ingested codebases a typed/indexed lookup would be the next optimization.
• Scope: validated on a small sample repo with a handful of conventions. Not hardened for production scale or multi-tenant use.