This MCP server provides correction-first agent memory. It tracks precision using a Precision KPI that measures whether agents heed warnings, based on a learning loop that records corrections, manages session lifecycle, and performs honest measurement. It is described as “5 layers” and “local-only,” with support via MCP · SDK · CLI · Skill.
🛠️ Key Features
Correction-first agent memory
Corrections ledger
Session lifecycle handling
Precision KPI for warnings
5 layers
Local-only operation
🚀 Use Cases
Measuring whether an agent stops repeating a mistake
2. First message of every new session, run the loop:
code
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:
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.
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.
The canonical cognitive-psychology taxonomy mapped to your agent's filesystem:
Layer
Type
What it holds
Path
1
Episodic
What happened in each session, chronologically. Auto-written during work.
journal/
2
Semantic
Topic-clustered facts with [[wikilinks]]: Architecture, Goals, Blockers.
palace/rooms/
3
Procedural
IF-THEN production rules — reusable how-tos.
palace/skills/
4
Narrative
Project phases: Goal → What was hard → How solved → Synthesis.
palace/pipeline/
5
Correction
Behavioral calibration: rules the agent must follow, with severity and outcome tracking.
corrections/
+
Awareness
Cross-project insights promoted from N-confirmed corrections — the compounding layer.
palace/awareness
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
Command
When
What it does
/arstart
First — every session
OPEN. No args = status board across ALL projects (pending work, blockers) → pick by number → load that project's deep context (palace rooms, corrections, task recall). /arstart <slug> loads directly; /arstart bootstrap scans your machine and imports existing projects.
/arsave
Last — every session
SAVE. Write journal + palace consolidation + awareness compounding. /arsave all batch-saves every parallel session of the day (scan, merge, deduplicate).
/arrecall
Mid-session, on demand
SEARCH. Surface past knowledge for the current task — documented fixes, prior decisions, patterns.
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.
What it does
Result
Mine patterns across all projects
Repeated corrections promote to palace/awareness
Ebbinghaus salience decay
Low-signal rooms fade; your palace stays sharp
Journal rollups
Entries >30 days compress into summary rooms
Awareness graduation
Corrections confirmed N× times go cross-project
Telegram report
Nightly summary: learned · decayed · crystallized
Requires a live Claude Code login. If the session expires, dream skips with a Telegram alert.
bash
# 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.
bash
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
Property
Guarantee
Default
OFF — flag off is byte-identical to keyword-only recall
Inference
Local ONNX (transformers.js), CPU, ~5-10ms per query warm
Network
Only ar embeddings setup ever downloads (one-time, cached, never re-fetched). Recall and rebuild run with remote fetch hard-disabled — offline you get a clean actionable error, never a hang
Packaging
Neither runtime nor model ships in the npm package — installed self-contained under ~/.agent-recall/embeddings/ on opt-in
Degradation
Missing/corrupt index or model → keyword results, unchanged, with the reason in semantic_leg metadata — never an error
Security
Semantic candidates pass the same trust/scope/fence stages as keyword ones; the index stores content-hash→vector only (no text), so a stale or tampered index cannot inject content
Measured
Golden retrieval eval 2026-09-12: 75% → 90% top-5 hit-rate, zero regressions (default paraphrase-multilingual-MiniLM-L12-v2, ~145MB; the e5 family is registry-available via AGENT_RECALL_EMBEDDINGS_MODEL — measured tradeoffs in the fix7 report)
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:
Piece
What it does
ar-scoreboard.py (SessionStart hook)
Health digest every session: correction flow, insight promotion rate, loop health, phantom counts, reflection cadence
ar-recurrence-check.py (+ your ~/.agent-recall/taxonomy.json, schema in TAXONOMY-SCHEMA.md)
Error-class taxonomy over your corrections; mechanical phantom detection (violation dated after its rule)
/arstart · /arsave · /arrecall · /arreflect
The four memory verbs (open · save · search · consolidate) as slash commands
Warn-only guard for an explicit-model dispatch policy — an example of mechanizing a rule that text alone failed to enforce
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.
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.
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.
