English · 中文

AgentRecall

Claude Code memory that learns from corrections. The only learning loop that measures whether your agent actually stops repeating a mistake.

Corrections ledger + session lifecycle + honest measurement. MCP · SDK · CLI · Skill.

claude mcp add --scope user agent-recall -- npx -y agent-recall-mcp

{ "mcpServers": { "agent-recall": { "command": "npx", "args": ["-y", "agent-recall-mcp"] } } }

At the start of a session, call session_start to load context.
When the human corrects you, call remember with type "correction".
At the end of a session, call session_end to compound what you learned.

What it does

AgentRecall is two things:

1. A governed corrections ledger — every time you correct your agent ("no, not that version", "put this section first", "ask me before you assume"), that correction is stored as a structured record with severity, evidence, and outcome tracking. It persists across sessions, projects, and agent restarts.

2. A measurement instrument — the only open-source system that tracks whether a correction actually changed what the agent does in a later session. Every correction accumulates retrieved_count, and every time the agent encounters the same situation, the outcome is recorded (heeded or recurred).

No other agent memory tool measures that second step. Every benchmark in the field tests retrieval; none tests behavioral change across sessions. We built the measurement harness first — and we publish what we found, including the unflattering numbers.

Measured, not promised

Most agent memory tools claim "never repeats the same mistake." None of them publish a number for it.

Here is what our own instrument found on our own live corpus (2026-07-03):

The heed instrument defaulted to "heeded" absent evidence before 2026-07-03; the reset default is "unknown" — the honest 0/3 is the correct starting point, not a regression. Transfer recall cannot support a point-estimate claim below 39 classes (claim-gate ledger, benchmark spec §2.6).

Verify it yourself: every number above regenerates from the committed artifacts — see docs/eval/REPRODUCE.md.

What this means: we captured 35% of real corrections in our own live use. The heed instrument was biased and we reset it. The offline transfer benchmark scores 0 on our own corpus — which is a density problem (32 active corrections across 19 projects is too sparse to front-run mistakes), not a retrieval architecture problem (confirmed 5× by internal experiments).

The learning loop framing is correct — the system is designed to track whether corrections change behavior — but the data we have so far is insufficient to quantify the uplift. We are publishing the measurement harness and running the experiment.

Why this is different from every other memory tool

In mid-2026, the agent-memory field is crowded (Mem0 ~60K stars, Graphiti/Zep ~28K, Supermemory ~28K, Letta ~24K). Most published benchmark numbers in this space are self-reported on the same 2–3 retrieval benchmarks and are hard to reproduce independently.

The confirmed gap (from our research report docs/research/agent-memory-landscape-2026-07.md §2): no public benchmark measures whether a captured correction changes what a fresh agent does in a new session. LongMemEval, LoCoMo, MemoryAgentBench, Letta Leaderboard — all test retrieval or within-session updates.

AgentRecall owns two pieces of the unclaimed ground:

• The corrections ledger — a governed data model (corrections-export/v1, scrubbed egress, retraction, severity, proof-confidence) that any engine can integrate against.
• The measurement harness — predict-loo (leave-one-out, anti-self-confirming, dual denominators) and the correction-transfer benchmark spec (HeedBench v1 — provisional name), which implements the missing pipeline: capture → persist → fresh session → measure recurrence.

Benchmark numbers in agent memory are typically self-reported and hard to reproduce. Ours regenerate from a fixed, hash-locked corpus with one command (npm run bench) — including the scores that make us look bad.

Quick Start

Visual setup guide — all 13 clients, copy-paste prompts: open warroom/install.html from the repo (or after unzipping the War Room release) in any browser. No server needed.

MCP Server — for AI agents

# Claude Code
claude mcp add --scope user agent-recall -- npx -y agent-recall-mcp

# Cursor — .cursor/mcp.json
{ "mcpServers": { "agent-recall": { "command": "npx", "args": ["-y", "agent-recall-mcp"] } } }

# VS Code — .vscode/mcp.json
{ "servers": { "agent-recall": { "command": "npx", "args": ["-y", "agent-recall-mcp"] } } }

# Windsurf — ~/.codeium/windsurf/mcp_config.json
{ "mcpServers": { "agent-recall": { "command": "npx", "args": ["-y", "agent-recall-mcp"] } } }

# Codex
codex mcp add agent-recall -- npx -y agent-recall-mcp

Skill (Claude Code only):

mkdir -p ~/.claude/skills/agent-recall
curl -o ~/.claude/skills/agent-recall/SKILL.md \
  https://raw.githubusercontent.com/Goldentrii/AgentRecall-X/main/SKILL.md

SDK & CLI

npm install agent-recall-sdk        # JS/TS apps
npx agent-recall-cli recall "topic" # terminal & CI

import { AgentRecall } from "agent-recall-sdk";
const memory = new AgentRecall({ project: "my-app" });
await memory.capture("What stack?", "Next.js + Postgres");
const ctx = await memory.recall("rate limiting");

5 Memory Layers

The canonical cognitive-psychology taxonomy mapped to your agent's filesystem:

All layers share one canonical naming grammar so any agent can compose retrieval paths from intent. Existing files keep working via a legacy_path view — no migration needed.

The Session Loop

flowchart LR
    A([session start]) --> B["/arstart — open<br/>board → pick → load context"]
    B --> C{work}
    C -->|need past knowledge| D["/arrecall — search"]
    D --> C
    C --> E["/arsave — save<br/>journal + compound"]
    E --> F([session end])
    F -. every K sessions .-> G["/arreflect — consolidate"]
    G -.-> A

Without /arstart, a fresh agent has zero orientation. Without /arsave, nothing compounds. Those two are the spine; /arrecall and /arreflect compound it.

The Automaticity Principle

Memory only compounds if it fires automatically, not on demand. Every pull-channel tool (recall, memory_query) saw zero organic calls across 44 projects over weeks of real use — including from the agent that built them. That is why only 5 tools ship by default; the two-verb model (session_start / session_end) carries all the compounding value, and everything else is opt-in via --full.

Dreaming — Nightly Consolidation (optional)

An autonomous overnight agent that runs while you sleep and compounds everything your sessions wrote during the day.

Requires a live Claude Code login. If the session expires, dream skips with a Telegram alert.

# Fix expired login (run this when dreaming stops)
claude login

Dream reports are saved locally to ~/.agent-recall/dreams/YYYY-MM-DD.md.

Semantic Recall — opt-in, 100% local embeddings

Keyword recall cannot reach a memory phrased differently from your question ("semver increment" never matches a rule written as "one version bump per release"). The optional semantic leg closes that gap with a local ONNX embedding model — zero cloud, zero telemetry, and the recall path never touches the network.

ar embeddings setup     # one-time: installs the local runtime (~380MB) + downloads the model (~145MB, cached forever)
ar embeddings rebuild   # builds the vector index from your store (incremental — only new/changed content embeds)
export AGENT_RECALL_EMBEDDINGS=1   # or add "embeddings_enabled": true to ~/.agent-recall/config.json
ar embeddings status    # flag / model / index diagnostics

Chinese/English cross-lingual queries work (the model is multilingual — a zh question finds an en rule and vice versa). Re-run ar embeddings rebuild occasionally (or after writing a lot); content-hash keying makes it cheap, and un-indexed new content simply stays keyword-searchable until then.

Experimental: Recurrence & Reflection Harness Kit

The question this answers: does a correction actually change behavior, or does the same mistake come back? A logged correction whose error class recurs after the rule was encoded is a phantom gradient step — the write cost was paid, the behavior never changed.

The kit in experimental/harness-kit/ is a Claude Code harness layer that closes this loop on top of AgentRecall:

North-star metric: post-re-abstraction phantom rate → 0 for treated classes. First validation run (2026-07-14, one power-user harness): 8 error classes and 18 confirmed phantom gradient steps found in 109 corrections; 6 rules re-abstracted the same day.

Status: experimental. Validated on one harness; Python 3 stdlib only; install steps and caveats in the kit's README. Since v3.4.37 the same phenomenon is also measured natively: failure_class + the cross-project recurrence join.

War Room Dashboard — Download & Deploy

A local-first visual dashboard for your memory: an activity calendar, per-project status, corrections, and insights — all rendered from your local ~/.agent-recall/ data. Fully offline (vendored assets), no Node and no build step.

1. Download ar-warroom-v3.4.32.zip from the latest GitHub Release.
2. Unzip it, then serve it locally:

cd warroom
python3 -m http.server 8080

3. Open http://localhost:8080/AgentRecall.html

This is the recommended onboarding for Hermes / OpenClaw / OpenCode users too — one offline page to see everything your agent has learned.

Architecture

TypeScript monorepo, 4 published packages: core (storage + tool logic), mcp-server (thin MCP wrappers), sdk (programmatic API), cli (the ar command). All memory is local markdown under ~/.agent-recall/projects/<slug>/ — journal/, corrections/, and palace/ (rooms, skills, pipeline, awareness). An optional Supabase mirror adds pgvector semantic recall; all-local stays the default.

Retrieval: keyword + RRF (Cormack 2009). FSRS-lite decay (Ebbinghaus → SuperMemo → FSRS-6). A Modern Hopfield re-rank primitive (Ramsauer 2020) is in the codebase but not wired into the default path — what runs today is local keyword/substring matching (stemming + synonym expansion + lightweight IDF, per-source ranking) merged via RRF, plus optional vector search when OPENAI_API_KEY is set. No inverted index or BM25 k1/b tuning — a real BM25 index is a possible future upgrade, not what's running now.

Platform Compatibility

Links

• Full reference → README.full.md
• Docs → docs/ — command reference, architecture deep-dives
• Changelog → UPDATE-LOG.md — phase-by-phase evolution + design reasoning
• Benchmark spec → docs/proposals/2026-07-02-correction-transfer-benchmark-spec.md
• Landscape research → docs/research/agent-memory-landscape-2026-07.md
• Skill → SKILL.md — Claude Code skill definition
• Community → Telegram · GitHub Issues

Contributing

PRs welcome. Open an issue first for anything substantive — the design is opinionated and grounded in published research; we want changes grounded the same way.

License

MIT — see LICENSE.