agentrecall-x

English · 中文

1. Install the MCP server (Claude Code):

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

Generic MCP JSON for other clients:

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

2. First message of every new session, run the loop:

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):

Metric	Value	Artifact
Correction capture recall (dual-blind audit, n=59)	35.3% [17.3–58.7 CI]	UPDATE-LOG.md §M2
Heed rate, pre-2026-07-03 (instrument-biased upper bound — do not cite)	92.5% [Wilson 60.1–100]	scripts/eval/baselines/rmr-baseline-2026-07-03.json
Heed rate, evidence-grounded (post-reset)	0/3 events	scripts/eval/baselines/rmr-baseline-2026-07-03.json
Correction transfer recall (offline bench, achievable)	0/4 [Wilson 0–49%]	scripts/eval/baselines/correction-transfer-real-2026-07-03.json
Median session_start injection	1,489 tokens (was 2,010; Mem0 anchor ~7K)	UPDATE-LOG.md §C2
p95 session_start latency (warm)	363 ms (was 1,132)	UPDATE-LOG.md §C2

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:

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.
/arreflect	Every K sessions	CONSOLIDATE. Periodic triage: confirm recurrence/phantom matches, cluster new error classes, propose rule re-abstractions (rule edits stay owner-gated).

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.

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

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

---

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
/arreflect (every K sessions)	Periodic triage: confirm provisional matches, cluster new error classes, propose rule re-abstractions — rule edits stay owner-gated
ar-nudge.py (UserPromptSubmit hook)	Surfaces overdue reflection mid-session — memory pushed to the moment of action, not left to be remembered
dispatch-model-guard.py (PreToolUse hook, optional)	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.

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

Platform	Mechanism	Status
Claude Code	MCP server + skill + hooks	Primary
Cursor · Windsurf · VS Code (Copilot) · Codex	MCP server	Supported
Any JS/TS app	SDK (agent-recall-sdk)	Supported
Terminal / CI	CLI (ar)	Supported

---

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.