{
  "markdown": "**English** · [中文](README.zh-CN.md)\n\n<h1 align=\"center\">AgentRecall</h1>\n\n<p align=\"center\"><strong>Claude Code memory that learns from corrections. The only learning loop that measures whether your agent actually stops repeating a mistake.</strong></p>\n\n<p align=\"center\">Corrections ledger + session lifecycle + honest measurement. MCP · SDK · CLI · Skill.</p>\n\n<p align=\"center\">\n  <a href=\"https://t.me/+ywZwoHrg3AM0NDVi\"><img src=\"https://img.shields.io/badge/Telegram-Community-2CA5E0?style=flat-square&logo=telegram\" alt=\"Telegram Community\"></a>\n  <a href=\"https://www.npmjs.com/package/agent-recall-mcp\"><img src=\"https://img.shields.io/npm/v/agent-recall-mcp?style=flat-square&label=MCP&color=5D34F2\" alt=\"MCP npm\"></a>\n  <a href=\"https://www.npmjs.com/package/agent-recall-sdk\"><img src=\"https://img.shields.io/npm/v/agent-recall-sdk?style=flat-square&label=SDK&color=0EA5E9\" alt=\"SDK npm\"></a>\n  <a href=\"https://www.npmjs.com/package/agent-recall-cli\"><img src=\"https://img.shields.io/npm/v/agent-recall-cli?style=flat-square&label=CLI&color=10B981\" alt=\"CLI npm\"></a>\n  <a href=\"https://github.com/Goldentrii/AgentRecall-X/blob/main/LICENSE\"><img src=\"https://img.shields.io/badge/license-MIT-brightgreen?style=flat-square\" alt=\"License\"></a>\n  <img src=\"https://img.shields.io/badge/tools-5_default-orange?style=flat-square\" alt=\"Tools\">\n  <img src=\"https://img.shields.io/badge/memory_layers-5-7C3AED?style=flat-square\" alt=\"5 layers\">\n  <img src=\"https://img.shields.io/badge/cloud-zero_by_default-blue?style=flat-square\" alt=\"Zero cloud by default\">\n  <img src=\"https://img.shields.io/badge/retrieval-keyword_%2B_RRF-8B5CF6?style=flat-square\" alt=\"Keyword + RRF retrieval\">\n</p>\n\n<p align=\"center\">\n  <a href=\"#the-session-loop\"><img src=\"https://img.shields.io/badge/%2Farstart-OPEN·START_HERE-22C55E?style=for-the-badge\" alt=\"/arstart\"></a>\n  <a href=\"#the-session-loop\"><img src=\"https://img.shields.io/badge/%2Farsave-SAVE-FF6B6B?style=for-the-badge\" alt=\"/arsave\"></a>\n  <a href=\"#the-session-loop\"><img src=\"https://img.shields.io/badge/%2Farrecall-SEARCH-4ECDC4?style=for-the-badge\" alt=\"/arrecall\"></a>\n  <a href=\"#the-session-loop\"><img src=\"https://img.shields.io/badge/%2Farreflect-CONSOLIDATE-8B5CF6?style=for-the-badge\" alt=\"/arreflect\"></a>\n</p>\n\n<details>\n<summary><b>Agent found this repo?</b> Install AgentRecall for your human (click to expand)</summary>\n\n**1. Install the MCP server** (Claude Code):\n\n```bash\nclaude mcp add --scope user agent-recall -- npx -y agent-recall-mcp\n```\n\nGeneric MCP JSON for other clients:\n\n```json\n{ \"mcpServers\": { \"agent-recall\": { \"command\": \"npx\", \"args\": [\"-y\", \"agent-recall-mcp\"] } } }\n```\n\n**2. First message of every new session**, run the loop:\n\n```\nAt the start of a session, call session_start to load context.\nWhen the human corrects you, call remember with type \"correction\".\nAt the end of a session, call session_end to compound what you learned.\n```\n\n</details>\n\n---\n\n## What it does\n\nAgentRecall is two things:\n\n1. **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.\n\n2. **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`).\n\nNo 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.\n\n---\n\n## Measured, not promised\n\nMost agent memory tools claim \"never repeats the same mistake.\" None of them publish a number for it.\n\nHere is what our own instrument found on our own live corpus (2026-07-03):\n\n| Metric | Value | Artifact |\n|---|---|---|\n| Correction capture recall (dual-blind audit, n=59) | **35.3%** [17.3–58.7 CI] | `UPDATE-LOG.md` §M2 |\n| 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` |\n| Heed rate, evidence-grounded (post-reset) | **0/3** events | `scripts/eval/baselines/rmr-baseline-2026-07-03.json` |\n| Correction transfer recall (offline bench, achievable) | **0/4** [Wilson 0–49%] | `scripts/eval/baselines/correction-transfer-real-2026-07-03.json` |\n| Median session_start injection | **1,489 tokens** (was 2,010; Mem0 anchor ~7K) | `UPDATE-LOG.md` §C2 |\n| p95 session_start latency (warm) | **363 ms** (was 1,132) | `UPDATE-LOG.md` §C2 |\n\n*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](docs/proposals/2026-07-02-correction-transfer-benchmark-spec.md) §2.6).*\n\n**Verify it yourself:** every number above regenerates from the committed artifacts — see [docs/eval/REPRODUCE.md](docs/eval/REPRODUCE.md).\n\n**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).\n\nThe 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.\n\n---\n\n## Why this is different from every other memory tool\n\nIn 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.\n\nThe 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.\n\nAgentRecall owns two pieces of the unclaimed ground:\n\n- **The corrections ledger** — a governed data model (`corrections-export/v1`, scrubbed egress, retraction, severity, proof-confidence) that any engine can integrate against.\n- **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.\n\nBenchmark 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.\n\n---\n\n## Quick Start\n\n> **Visual setup guide — all 13 clients, copy-paste prompts:** open [`warroom/install.html`](warroom/install.html) from the repo (or after unzipping the War Room release) in any browser. No server needed.\n\n<p align=\"center\">\n  <img src=\"warroom/static/install-preview.png\" alt=\"AgentRecall Install Guide\" width=\"900\">\n</p>\n\n### MCP Server — for AI agents\n\n```bash\n# Claude Code\nclaude mcp add --scope user agent-recall -- npx -y agent-recall-mcp\n\n# Cursor — .cursor/mcp.json\n{ \"mcpServers\": { \"agent-recall\": { \"command\": \"npx\", \"args\": [\"-y\", \"agent-recall-mcp\"] } } }\n\n# VS Code — .vscode/mcp.json\n{ \"servers\": { \"agent-recall\": { \"command\": \"npx\", \"args\": [\"-y\", \"agent-recall-mcp\"] } } }\n\n# Windsurf — ~/.codeium/windsurf/mcp_config.json\n{ \"mcpServers\": { \"agent-recall\": { \"command\": \"npx\", \"args\": [\"-y\", \"agent-recall-mcp\"] } } }\n\n# Codex\ncodex mcp add agent-recall -- npx -y agent-recall-mcp\n```\n\n**Skill (Claude Code only):**\n\n```bash\nmkdir -p ~/.claude/skills/agent-recall\ncurl -o ~/.claude/skills/agent-recall/SKILL.md \\\n  https://raw.githubusercontent.com/Goldentrii/AgentRecall-X/main/SKILL.md\n```\n\n### SDK & CLI\n\n```bash\nnpm install agent-recall-sdk        # JS/TS apps\nnpx agent-recall-cli recall \"topic\" # terminal & CI\n```\n\n```typescript\nimport { AgentRecall } from \"agent-recall-sdk\";\nconst memory = new AgentRecall({ project: \"my-app\" });\nawait memory.capture(\"What stack?\", \"Next.js + Postgres\");\nconst ctx = await memory.recall(\"rate limiting\");\n```\n\n---\n\n## 5 Memory Layers\n\nThe canonical cognitive-psychology taxonomy mapped to your agent's filesystem:\n\n| Layer | Type | What it holds | Path |\n|---|---|---|---|\n| 1 | **Episodic** | What happened in each session, chronologically. Auto-written during work. | `journal/` |\n| 2 | **Semantic** | Topic-clustered facts with `[[wikilinks]]`: Architecture, Goals, Blockers. | `palace/rooms/` |\n| 3 | **Procedural** | IF-THEN production rules — reusable how-tos. | `palace/skills/` |\n| 4 | **Narrative** | Project phases: Goal → What was hard → How solved → Synthesis. | `palace/pipeline/` |\n| 5 | **Correction** | Behavioral calibration: rules the agent must follow, with severity and outcome tracking. | `corrections/` |\n| + | **Awareness** | Cross-project insights promoted from N-confirmed corrections — the compounding layer. | `palace/awareness` |\n\nAll 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.\n\n---\n\n## The Session Loop\n\n```mermaid\nflowchart LR\n    A([session start]) --> B[\"/arstart — open<br/>board → pick → load context\"]\n    B --> C{work}\n    C -->|need past knowledge| D[\"/arrecall — search\"]\n    D --> C\n    C --> E[\"/arsave — save<br/>journal + compound\"]\n    E --> F([session end])\n    F -. every K sessions .-> G[\"/arreflect — consolidate\"]\n    G -.-> A\n```\n\n| Command | When | What it does |\n|---|---|---|\n| `/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. |\n| `/arsave` | **Last — every session** | SAVE. Write journal + palace consolidation + awareness compounding. `/arsave all` batch-saves every parallel session of the day (scan, merge, deduplicate). |\n| `/arrecall` | Mid-session, on demand | SEARCH. Surface past knowledge for the current task — documented fixes, prior decisions, patterns. |\n| `/arreflect` | Every K sessions | CONSOLIDATE. Periodic triage: confirm recurrence/phantom matches, cluster new error classes, propose rule re-abstractions (rule edits stay owner-gated). |\n\n> **Without `/arstart`, a fresh agent has zero orientation. Without `/arsave`, nothing compounds. Those two are the spine; `/arrecall` and `/arreflect` compound it.**\n\n---\n\n## The Automaticity Principle\n\nMemory 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`.\n\n---\n\n## Dreaming — Nightly Consolidation (optional)\n\nAn autonomous overnight agent that runs while you sleep and compounds everything your sessions wrote during the day.\n\n| What it does | Result |\n|---|---|\n| Mine patterns across all projects | Repeated corrections promote to `palace/awareness` |\n| Ebbinghaus salience decay | Low-signal rooms fade; your palace stays sharp |\n| Journal rollups | Entries >30 days compress into summary rooms |\n| Awareness graduation | Corrections confirmed N× times go cross-project |\n| Telegram report | Nightly summary: learned · decayed · crystallized |\n\n**Requires a live Claude Code login.** If the session expires, dream skips with a Telegram alert.\n\n```bash\n# Fix expired login (run this when dreaming stops)\nclaude login\n```\n\nDream reports are saved locally to `~/.agent-recall/dreams/YYYY-MM-DD.md`.\n\n---\n\n## Experimental: Recurrence & Reflection Harness Kit\n\n**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.\n\nThe kit in [`experimental/harness-kit/`](experimental/harness-kit/) is a Claude Code harness layer that closes this loop on top of AgentRecall:\n\n| Piece | What it does |\n|---|---|\n| `ar-scoreboard.py` (SessionStart hook) | Health digest every session: correction flow, insight promotion rate, loop health, phantom counts, reflection cadence |\n| `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) |\n| `/arstart` · `/arsave` · `/arrecall` · `/arreflect` | The four memory verbs (open · save · search · consolidate) as slash commands |\n| `/arreflect` (every K sessions) | Periodic triage: confirm provisional matches, cluster new error classes, propose rule re-abstractions — **rule edits stay owner-gated** |\n| `ar-nudge.py` (UserPromptSubmit hook) | Surfaces overdue reflection mid-session — memory pushed to the moment of action, not left to be remembered |\n| `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 |\n\nNorth-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.\n\n**Status: experimental.** Validated on one harness; Python 3 stdlib only; install steps and caveats in the kit's [README](experimental/harness-kit/README.md). Since v3.4.37 the same phenomenon is also measured natively: `failure_class` + the cross-project recurrence join.\n\n---\n\n## War Room Dashboard — Download & Deploy\n\nA 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.\n\n<p align=\"center\">\n  <img src=\"warroom/static/preview.png\" alt=\"AgentRecall War Room — Overview\" width=\"900\">\n</p>\n\n1. Download **`ar-warroom-v3.4.32.zip`** from the [latest GitHub Release](https://github.com/Goldentrii/AgentRecall-X/releases/latest).\n2. Unzip it, then serve it locally:\n\n```bash\ncd warroom\npython3 -m http.server 8080\n```\n\n3. Open **http://localhost:8080/AgentRecall.html**\n\nThis is the recommended onboarding for Hermes / OpenClaw / OpenCode users too — one offline page to see everything your agent has learned.\n\n---\n\n## Architecture\n\nTypeScript 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.\n\nRetrieval: 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.\n\n## Platform Compatibility\n\n| Platform | Mechanism | Status |\n|---|---|---|\n| Claude Code | MCP server + skill + hooks | Primary |\n| Cursor · Windsurf · VS Code (Copilot) · Codex | MCP server | Supported |\n| Any JS/TS app | SDK (`agent-recall-sdk`) | Supported |\n| Terminal / CI | CLI (`ar`) | Supported |\n\n---\n\n## Links\n\n- **Full reference** → [README.full.md](README.full.md)\n- **Docs** → [docs/](docs/) — command reference, architecture deep-dives\n- **Changelog** → [UPDATE-LOG.md](UPDATE-LOG.md) — phase-by-phase evolution + design reasoning\n- **Benchmark spec** → [docs/proposals/2026-07-02-correction-transfer-benchmark-spec.md](docs/proposals/2026-07-02-correction-transfer-benchmark-spec.md)\n- **Landscape research** → [docs/research/agent-memory-landscape-2026-07.md](docs/research/agent-memory-landscape-2026-07.md)\n- **Skill** → [SKILL.md](SKILL.md) — Claude Code skill definition\n- **Community** → [Telegram](https://t.me/+ywZwoHrg3AM0NDVi) · [GitHub Issues](https://github.com/Goldentrii/AgentRecall-X/issues)\n\n## Contributing\n\nPRs welcome. Open an issue first for anything substantive — the design is opinionated and grounded in published research; we want changes grounded the same way.\n\n## License\n\nMIT — see [LICENSE](LICENSE).\n",
  "bytes": 17608,
  "sha": "79a4ea752a68e292b1c164c58045812916616aadc710672e2bfabc9385d94750",
  "repo_slug": "goldentrii/agentrecall-mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_goldentrii_agent_recall_5e92bb0d/readme"
}