Persistent, correction-driven memory for AI agents. Cross-session, cross-platform (Claude Code, Codex, Gemini — any MCP client). Learns from mistakes, compresses context to save tokens, consolidates knowledge overnight. npm: agent-recall-mcp
AgentRecall is not a memory tool. It's a learning loop.
Memory is the mechanism. Understanding is the goal. Every time you correct your agent — "no, not that version", "put this section first", "ask me before you assume" — that correction is stored, weighted, and recalled next time.
After 10 sessions, your agent doesn't just remember your project. It understands how you think: your priorities, your communication style, your non-negotiables.
</td> <td>AgentRecall 不是记忆工具，是学习闭环。
记忆是机制，理解才是目标。每一次纠正——"不是那个版本"、"先放这一段"、"假设之前先问我"——都会被存储、加权、并在下次召回。
跑 10 次会话之后，agent 不只是记得项目，它理解你的思考方式：优先级、沟通风格、不可妥协的底线。
</td> </tr> <tr> <td>Five things that make it different:
CorrectionRecord with severity, holder, and evidence. After N confirmations across sessions, it auto-promotes to a cross-project insight.retrieved_count, heeded_count, recurrence_count, precision. The KPI that matters: did the same bug recur after we warned about it?~/.agent-recall/. Open it in Obsidian. Grep it in the terminal. Version it in git. No cloud, no API keys, no lock-in.让它不同的五件事：
CorrectionRecord（严重度、归属、证据）。跨会话被确认 N 次后，自动晋升为跨项目的 insight。retrieved_count（被召回多少次）、heeded_count（被遵守多少次）、recurrence_count（同样的 bug 是否复发）、precision。唯一重要的 KPI：警告之后同样的 bug 还复发吗？~/.agent-recall/。用 Obsidian 打开、用终端 grep、用 git 版本管理。零云、零 API key、零锁定。The canonical cognitive-psychology taxonomy mapped to your agent's filesystem · 把认知心理学的经典记忆分类映射到你的文件系统：
<table> <tr> <th>Layer · 层</th> <th>Type · 类型</th> <th>EN — What it holds</th> <th>中文 — 存什么</th> <th>Path</th> </tr> <tr> <td>1</td> <td><b>Episodic</b><br/>情景</td> <td>What happened in each session, chronologically. Auto-written by the agent during work.</td> <td>每次会话发生了什么，按时间顺序。Agent 工作时自动写入。</td> <td><code>journal/</code></td> </tr> <tr> <td>2</td> <td><b>Semantic</b><br/>语义</td> <td>Topic-clustered facts with <code>[[wikilinks]]</code>: Architecture, Goals, Blockers, etc.</td> <td>按主题聚类的事实，带 <code>[[wikilinks]]</code>：架构、目标、阻塞等。</td> <td><code>palace/rooms/</code></td> </tr> <tr> <td>3</td> <td><b>Procedural</b><br/>程序<br/><i>NEW</i></td> <td>IF-THEN production rules: <i>"When setting up Cloudflare DNS, do these 4 steps."</i> Reusable how-tos.</td> <td>IF-THEN 产生式规则："设置 Cloudflare DNS 时，按这 4 步走"。可复用的操作流程。</td> <td><code>palace/skills/</code></td> </tr> <tr> <td>4</td> <td><b>Narrative</b><br/>叙事</td> <td>Project phase milestones: Goal → What was hard → How solved → Synthesis (1-sentence reusable lesson).</td> <td>项目阶段里程碑：目标 → 难点 → 怎么解决的 → 提炼（一句话可复用的经验）。</td> <td><code>palace/pipeline/</code></td> </tr> <tr> <td>5</td> <td><b>Correction</b><br/>纠正</td> <td>Behavioral calibration: rules the agent must follow, with precision KPIs tracking effectiveness.</td> <td>行为校准：agent 必须遵守的规则，配合 precision KPI 追踪有效性。</td> <td><code>corrections/</code></td> </tr> <tr> <td>+</td> <td><b>Awareness</b><br/>感知</td> <td>Cross-project insights promoted from N-confirmed corrections. The compounding layer.</td> <td>跨项目的 insight，由确认 N 次以上的纠正晋升而来。复合层。</td> <td><code>palace/awareness</code></td> </tr> </table>All five layers share one canonical naming grammar (<scope>/<type>/[<topic>/]<temporal>--<slug>.md) so any agent — Claude, Codex, future LLM — can compose retrieval paths from intent instead of grepping five conventions. Existing files keep working via a legacy_path virtual-key view. No migration needed.
所有五层共享一个 规范命名语法（<scope>/<type>/[<topic>/]<temporal>--<slug>.md），任何 agent —— Claude、Codex、未来的 LLM —— 都能用意图组合检索路径，不用 grep 五套命名约定。旧文件通过 legacy_path 虚拟键视图继续可用。无需迁移。
Without
/arstatus, a fresh agent has zero orientation. Without/arsave, nothing compounds. These two are the entire loop.
没有/arstatus，新 agent 完全失去方向。没有/arsave，什么都不会复合。这两个就是整个闭环。
/arbootstrap scans your machine and imports everything: git repos, Claude AutoMemory (~/.claude/projects/), CLAUDE.md files. Read-only scan, secrets never touched.
/arbootstrap 扫描你的机器并导入所有：git 仓库、Claude AutoMemory（~/.claude/projects/）、CLAUDE.md 文件。只读扫描，secrets 永不触碰。
ar bootstrap # scan and show what was found
ar bootstrap --import # import all new projects# 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-mcpSkill (Claude Code only) · 仅 Claude Code：
mkdir -p ~/.claude/skills/agent-recall
curl -o ~/.claude/skills/agent-recall/SKILL.md \
https://raw.githubusercontent.com/Goldentrii/AgentRecall/main/SKILL.mdnpm install agent-recall-sdkimport { 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");npx agent-recall-cli capture "What stack?" "Next.js + Postgres"
npx agent-recall-cli recall "rate limiting"
npx agent-recall-cli palace walk --depth activeWhy only 5 by default? The Automaticity Law (measured on the live corpus, 2026-06-12): push channels —
session_start,session_end, correction hooks — show repeated behavior-changing usage. Pull channels (check_action,skill_recall,pipeline_*,memory_query) had zero organic calls in 44 projects over weeks of real use, including from the agent that built them. Every extra tool in the default surface burns tool-definition tokens every session for zero behavioral return. The two-verb model (inhale/exhale) carries all compounding value; everything else is opt-in via--full.为什么默认只有 5 个工具？ 自动化定律（基于真实语料库测量，2026-06-12）：推送通道（
session_start、session_end、纠正 hooks）有持续的行为改变使用记录；拉取通道（check_action、skill_recall、pipeline_*、memory_query）在 44 个项目、数周真实使用中有零次有机调用——包括构建它们的 agent 本身。默认工具面每多一个工具就会在每次会话燃烧 tool-definition tokens，但零行为回报。双动词模型（吸入/呼出）承载了所有复合价值；其余功能通过--full按需开启。
Phase 6 closes 11 structural gaps the field's research literature flagged. Three improvement loops in one pass — 10-vantage research review → implementation → independent code review → fix-up.
Phase 6 修复了研究文献指出的 11 个结构性缺口。一次完成三个改进循环——10 视角研究审查 → 实现 → 独立代码审查 → 修复。
<table> <tr> <th>Change · 改动</th> <th>Research grounding · 研究依据</th> </tr> <tr> <td><b>Pipeline layer</b> — project narrative spine with 5 MCP tools<br/><b>叙事层</b> — 项目叙事主干 + 5 个 MCP 工具</td> <td>Park et al. 2023 (Generative Agents) reflection pattern</td> </tr> <tr> <td><b>Canonical naming system</b> — virtual key + <code>legacy_path</code>, no migration needed<br/><b>规范命名系统</b> — 虚拟键 + <code>legacy_path</code>，无需迁移</td> <td>Squire 2004 taxonomy + CoALA architecture</td> </tr> <tr> <td><b>Procedural memory (5th layer)</b> — <code>palace/skills/</code> + 3 MCP tools<br/><b>程序记忆（第 5 层）</b> — <code>palace/skills/</code> + 3 个 MCP 工具</td> <td>Squire 2004 declarative/non-declarative split, ACT-R production rules</td> </tr> <tr> <td><b>Correction outcome KPIs</b> — precision / heeded / recurrence tracking<br/><b>纠正结果 KPI</b> — precision / heeded / recurrence 追踪</td> <td>Reflexion (Shinn 2023), RLAIF — making the learning loop measurable</td> </tr> <tr> <td><b>FSRS-lite decay scorer</b> — reinforce on recall, decay on staleness<br/><b>FSRS-lite 衰减打分</b> — 召回时强化，过期时衰减</td> <td>Ebbinghaus 1885 → SuperMemo → FSRS-6 (Anki ≥23.10)</td> </tr> <tr> <td><b>Modern Hopfield re-ranker</b> — <code>ξ_new = X·softmax(β·X^⊤·ξ)</code><br/><b>Modern Hopfield 重排</b> — <code>ξ_new = X·softmax(β·X^⊤·ξ)</code></td> <td>Ramsauer et al. 2020, exp(d/2) capacity vs classical 0.14·d</td> </tr> <tr> <td><b>session_start lite mode</b> — ≤500 tokens, pull-on-demand<br/><b>session_start lite 模式</b> — ≤500 tokens，按需召回</td> <td>Anthropic 2026 context engineering — "smallest high-signal set"</td> </tr> <tr> <td><b>Agent-readable dashboard.json</b> — schema_version=1, one-call self-inspection<br/><b>Agent 可读的 dashboard.json</b> — schema_version=1，一次调用自查</td> <td>Agent-first principle — humans aren't the only readers</td> </tr> <tr> <td><b>Reflection bundle</b> — Park-style aggregation prompt (LLM call happens in the agent's turn, not core)<br/><b>反思包</b> — Park 风格的聚合 prompt（LLM 调用在 agent 自己的 turn 里，不在 core）</td> <td>Park 2023 §4.3</td> </tr> <tr> <td><b>Security hardening</b> — path traversal blocked, frontmatter YAML escaped, atomic writes, line-walk section parser<br/><b>安全加固</b> — 路径穿越封堵、frontmatter YAML 转义、原子写入、按行解析章节</td> <td>8-agent red-team P0 findings (2026-05-30)</td> </tr> </table>Full details: see UPDATE-LOG.md Phase 6 section. Visual report: REPORT-2026-05-30.html.
完整细节见 UPDATE-LOG.md Phase 6 章节。可视化报告：REPORT-2026-05-30.html。
import { AgentRecall } from "agent-recall-sdk";
const memory = new AgentRecall({ project: "my-app" });
// Write — auto-routes to journal / palace / awareness based on content
await memory.capture("What stack?", "Next.js + Postgres + Drizzle ORM");
await memory.remember("Database: pgvector enabled, RRF fusion for hybrid recall");
// Read — full hybrid search
const results = await memory.recall("rate limiting");
const filescoped = await memory.recall("auth flow", { file_path: "src/auth.ts" });
// Reflect — bundle recent journals + corrections for LLM-side distillation
const bundle = await memory.reflect({ lookback_days: 7 });
// Pipeline — track project narrative
await memory.pipelineOpen({ phase_name: "Discovery", goal: "Map user pain points" });
await memory.pipelineClose({
what_was_hard: "Conflicting signals from interviews",
how_solved: "Triangulated against analytics data",
synthesis: "Behavior > stated preference when they diverge"
});
// Skills — save and recall procedural know-how
await memory.skillWrite({
name: "Cloudflare 4-step routing",
topic: "deploy",
triggers: ["cloudflare", "dns", "ssl"],
when: "Setting up a new domain with API gateway behind Cloudflare",
steps: ["Add DNS record", "Enable Proxy", "Add Origin Rule", "Set SSL mode = Full"]
});
const hits = await memory.skillRecall({ intent: "set up cloudflare for new domain" });# Capture & recall
ar capture "Question" "Answer"
ar recall "topic" # hybrid BM25 + vector + Hopfield re-rank
ar recall "topic" --since 7d # time-filtered
# Sessions
ar status # status board across all projects
ar save # full session_end (journal + palace + awareness)
ar saveall # batch save all parallel sessions
# Bootstrap
ar bootstrap # scan and show
ar bootstrap --import # import all new projects
# Palace navigation
ar palace walk --depth active # browse active rooms
ar palace read goals # read a room
# Pipeline
ar pipeline show <project> # narrative spine
ar pipeline list <project> # JSON summariesRun ar --help for the full surface · 完整命令运行 ar --help.
TypeScript monorepo, 4 published packages · TypeScript monorepo，4 个发布包：
packages/
├── core/ # storage + tool logic + helpers (agent-recall-core)
├── mcp-server/ # thin MCP wrappers (agent-recall-mcp)
├── sdk/ # programmatic API for JS/TS apps (agent-recall-sdk)
└── cli/ # `ar` shell command (agent-recall-cli)Storage layout · 存储布局:
~/.agent-recall/
├── projects/
│ └── <slug>/
│ ├── journal/ # episodic — per-session entries
│ ├── corrections/ # behavioral rules + outcome KPIs
│ └── palace/
│ ├── rooms/ # semantic — topic-clustered facts
│ ├── skills/ # procedural — IF-THEN rules (NEW)
│ ├── pipeline/ # narrative — project phases (NEW)
│ ├── identity.md
│ └── awareness # cross-project insights
├── dashboard.html # human-readable dashboard
└── dashboard.json # agent-readable snapshot (NEW)Optional Supabase mirror · 可选 Supabase 镜像 — pgvector for semantic recall, RRF fusion when configured. All-local stays the default.
| Platform | Mechanism | Status |
|---|---|---|
| Claude Code | MCP server + skill + hooks | ✅ Primary |
| Cursor | MCP server | ✅ |
| Windsurf | MCP server | ✅ |
| VS Code (Copilot) | MCP server | ✅ |
| Codex | MCP server | ✅ |
| Any JS/TS app | SDK (agent-recall-sdk) | ✅ |
| Terminal / CI | CLI (ar) | ✅ |
UPDATE-LOG.md — phase-by-phase evolution + design reasoningREPORT-2026-05-30.html — Phase 6 visual reportdocs/ — command reference, architecture deep-divesSKILL.md — Claude Code skill definitionPRs welcome. Open an issue first for anything substantive — the design is opinionated and based on published research; we want changes to be grounded the same way.
欢迎 PR。任何实质性改动请先开 issue——这个设计有自己的主张，且基于已发表的研究；我们希望改动也能用同样的方式落地。
MIT — see LICENSE.
Goldentrii/AgentRecall-MCP
March 24, 2026
June 14, 2026
TypeScript