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)