AgentRecall

What & Why · 什么和为什么

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.

AgentRecall 不是记忆工具，是学习闭环。

记忆是机制，理解才是目标。每一次纠正——"不是那个版本"、"先放这一段"、"假设之前先问我"——都会被存储、加权、并在下次召回。

跑 10 次会话之后，agent 不只是记得项目，它理解你的思考方式：优先级、沟通风格、不可妥协的底线。

Five things that make it different:

• Correction-first. When you say "no, that's wrong", we log a CorrectionRecord with severity, holder, and evidence. After N confirmations across sessions, it auto-promotes to a cross-project insight.

• Measurable learning loop. Every correction tracks retrieved_count, heeded_count, recurrence_count, precision. The KPI that matters: did the same bug recur after we warned about it?

• Five memory types. Episodic, semantic, procedural, narrative, correction — mapped to canonical cognitive-psychology taxonomy (Squire 2004, Tulving 1972).

• Local markdown only. Everything lives in ~/.agent-recall/. Open it in Obsidian. Grep it in the terminal. Version it in git. No cloud, no API keys, no lock-in.

• Backed by published math. FSRS-lite decay (Ebbinghaus → SuperMemo → FSRS-6), Modern Hopfield retrieval (Ramsauer 2020), RRF fusion (Cormack 2009).

让它不同的五件事：

• 以纠正为先。 你说"不对"时，我们记下 CorrectionRecord（严重度、归属、证据）。跨会话被确认 N 次后，自动晋升为跨项目的 insight。

• 可量化的学习闭环。 每条纠正都跟踪 retrieved_count（被召回多少次）、heeded_count（被遵守多少次）、recurrence_count（同样的 bug 是否复发）、precision。唯一重要的 KPI：警告之后同样的 bug 还复发吗？

• 五种记忆类型。 Episodic、semantic、procedural、narrative、correction —— 对应认知心理学经典分类（Squire 2004、Tulving 1972）。

• 只用本地 markdown。 一切都在 ~/.agent-recall/。用 Obsidian 打开、用终端 grep、用 git 版本管理。零云、零 API key、零锁定。

• 基于已发表数学。 FSRS-lite 衰减（Ebbinghaus → SuperMemo → FSRS-6）、Modern Hopfield 检索（Ramsauer 2020）、RRF 融合（Cormack 2009）。

Related MCP server: my-memory-mcp

5 Memory Layers · 五层记忆模型

The canonical cognitive-psychology taxonomy mapped to your agent's filesystem · 把认知心理学的经典记忆分类映射到你的文件系统：

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 虚拟键视图继续可用。无需迁移。

The Session Loop · 会话循环

Without /arstatus, a fresh agent has zero orientation. Without /arsave, nothing compounds. These two are the entire loop. 没有 /arstatus，新 agent 完全失去方向。没有 /arsave，什么都不会复合。这两个就是整个闭环。

Already Using Another Memory System? · 已经用过别的？

/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

Quick Start · 快速开始

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) · 仅 Claude Code：

mkdir -p ~/.claude/skills/agent-recall
curl -o ~/.claude/skills/agent-recall/SKILL.md \
  https://raw.githubusercontent.com/Goldentrii/AgentRecall/main/SKILL.md

SDK — for JS/TS applications

npm install agent-recall-sdk

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");

CLI — for terminal & CI

npx agent-recall-cli capture "What stack?" "Next.js + Postgres"
npx agent-recall-cli recall "rate limiting"
npx agent-recall-cli palace walk --depth active

MCP Tools

Why 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 按需开启。

How Memory Compounds · 记忆如何复合

What's New in Phase 6 · Phase 6 新增

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 视角研究审查 → 实现 → 独立代码审查 → 修复。

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。

SDK API

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" });

CLI

# 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 summaries

Run ar --help for the full surface · 完整命令运行 ar --help.

Architecture · 架构

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 Compatibility · 平台兼容

Docs · 文档

• UPDATE-LOG.md — phase-by-phase evolution + design reasoning

• REPORT-2026-05-30.html — Phase 6 visual report

• docs/ — command reference, architecture deep-dives

• SKILL.md — Claude Code skill definition

Community · 社区

• 💬 Telegram — questions, feedback, requests

• 🐛 GitHub Issues — bugs and feature requests

• 📦 npm: agent-recall-mcp

• 📦 npm: agent-recall-sdk

• 📦 npm: agent-recall-cli

Contributing · 贡献

PRs 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——这个设计有自己的主张，且基于已发表的研究；我们希望改动也能用同样的方式落地。

License

MIT — see LICENSE.