AgentRecall

Your agent doesn't just remember. It learns how you think.

你的 agent 不只是记得。它在学你怎么想。

Every correction saved is a mistake never repeated. Every insight compounded is tokens never wasted rebuilding context.
每一次纠正都是不会重复的错误。每一次复合都是不会重建的上下文。

Persistent, compounding memory + automatic correction capture. MCP server + SDK + CLI.

EN:  Why · Memory · Install · Tools · Compounding · Phase 6 · SDK · CLI · Arch   |   中文:  什么 · 记忆模型 · 安装 · 工具 · 复合 · 新增

---

---

What & Why · 什么和为什么

🇬🇧 English	🇨🇳 中文
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）。

---

5 Memory Layers · 五层记忆模型

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

Layer · 层	Type · 类型	EN — What it holds	中文 — 存什么	Path
1	Episodic 情景	What happened in each session, chronologically. Auto-written by the agent during work.	每次会话发生了什么，按时间顺序。Agent 工作时自动写入。	journal/
2	Semantic 语义	Topic-clustered facts with [[wikilinks]]: Architecture, Goals, Blockers, etc.	按主题聚类的事实，带 [[wikilinks]]：架构、目标、阻塞等。	palace/rooms/
3	Procedural 程序 NEW	IF-THEN production rules: "When setting up Cloudflare DNS, do these 4 steps." Reusable how-tos.	IF-THEN 产生式规则："设置 Cloudflare DNS 时，按这 4 步走"。可复用的操作流程。	palace/skills/
4	Narrative 叙事	Project phase milestones: Goal → What was hard → How solved → Synthesis (1-sentence reusable lesson).	项目阶段里程碑：目标 → 难点 → 怎么解决的 → 提炼（一句话可复用的经验）。	palace/pipeline/
5	Correction 纠正	Behavioral calibration: rules the agent must follow, with precision KPIs tracking effectiveness.	行为校准：agent 必须遵守的规则，配合 precision KPI 追踪有效性。	corrections/
+	Awareness 感知	Cross-project insights promoted from N-confirmed corrections. The compounding layer.	跨项目的 insight，由确认 N 次以上的纠正晋升而来。复合层。	palace/awareness

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 · 会话循环

Command	When · 什么时候	EN — What it does	中文 — 做什么
🔴 /arstatus	First — every session 每个会话最先	Status board across ALL projects. Pending work, blockers, relevance scores. Pick by number.	所有项目的状态看板。待办、阻塞、相关性分数。按编号选。
/arstart	After picking a project 选完项目后	Load deep context: palace rooms, corrections, task-specific recall.	加载深度上下文：palace 房间、纠正记录、任务相关召回。
🔴 /arsave	Last — every session 每个会话最后	Write journal + palace consolidation + awareness compounding + semantic prefetch.	写 journal + palace 合并 + awareness 复合 + 语义预取。
/arsaveall	End of day (multi-session) 一天结束（多会话）	Batch save all parallel sessions — scan, merge, deduplicate, done.	批量保存所有并行会话——扫描、合并、去重、完成。
/arbootstrap	First install / migrating 首次安装 / 迁移	Scan your machine for existing projects and import them.	扫描你的机器，把已有项目导入进来。

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

---

18 MCP Tools · 18 个 MCP 工具

Category · 类别	Tool	EN — What it does	中文 — 做什么
Core session 核心会话	session_start	Load context at session start (full or mode:"lite" ≤500 tokens).	会话开始时加载上下文（完整或 mode:"lite" ≤500 tokens）。
	session_end	Save journal + insights; optionally close/open a pipeline phase in same call.	保存 journal + insights；可在同一次调用中关闭/开启 pipeline 阶段。
	session_end_reflect	Park-2023 reflection bundle — distills last N journals into reusable insights.	Park-2023 反思包——把最近 N 篇 journal 蒸馏成可复用的 insight。
	remember	Write a memory, auto-routes to the right palace room.	写入一条记忆，自动路由到合适的 palace 房间。
	recall	Search all memory (BM25 + vector with RRF fusion + Hopfield rerank).	搜索所有记忆（BM25 + 向量 + RRF 融合 + Hopfield 重排）。
	memory_query	Pull-on-demand recall mid-task. Supports file-scoped queries.	任务中按需召回。支持按文件范围查询。
Calibration 校准	check	Record agent understanding; system returns predictive warnings from past corrections.	记录 agent 的理解；系统返回从过去纠正得出的预测性警告。
	dashboard_export	Generate agent-readable dashboard.json with all-project memory snapshot + naming index.	生成 agent 可读的 dashboard.json，包含所有项目记忆快照 + 命名索引。
Pipeline 叙事	pipeline_open	Open a new project phase (Goal/Hard/Solved/Synthesis).	开启新的项目阶段（目标/难点/解决/提炼）。
	pipeline_close	Close active phase with reflection fields. Status: closed / abandoned / pivoted.	关闭当前阶段并填反思字段。状态：closed / abandoned / pivoted。
	pipeline_list	List all phases as JSON summaries.	列出所有阶段（JSON 摘要）。
	pipeline_current	Return full content of the currently active phase.	返回当前 active 阶段的完整内容。
	pipeline_show	Render a project's narrative spine — human-readable view of all phases.	渲染项目的叙事主干——所有阶段的人类可读视图。
Skills 程序记忆	skill_write	Save an IF-THEN production rule (trigger / preconditions / steps / postconditions / pitfalls).	保存一条 IF-THEN 产生式规则（触发条件/前提/步骤/后置条件/陷阱）。
	skill_recall	Find skills matching an intent (deterministic trigger-keyword ranking).	按意图找到匹配的 skill（基于触发关键词的确定性排序）。
	skill_list	Browse all skills in a project.	浏览项目中所有 skill。
Setup 初始化	bootstrap_scan + bootstrap_import	Discover existing projects on this machine and import in bulk.	发现本机已有项目并批量导入。

---

How Memory Compounds · 记忆如何复合

Mechanism · 机制	EN	中文
Auto-naming	Files name themselves from content via canonical grammar — agents compose paths from intent, no guessing.	文件根据内容用规范语法自命名——agent 按意图组合路径，不用猜。
FSRS-lite decay	R = exp(-days_since_lastConfirmed / S). Each recall hit reinforces stability. Cold facts get tagged archive_candidate instead of silently growing forever.	R = exp(-距上次确认天数 / S)。每次召回命中会强化稳定性。冷的事实会被标 archive_candidate，而不是静默无限增长。
RRF + Hopfield retrieval	BM25 + vector merged via RRF (Cormack 2009), then optionally re-ranked by Modern Hopfield (Ramsauer 2020) for associative blend.	BM25 + 向量通过 RRF 融合（Cormack 2009），再可选地用 Modern Hopfield 重排（Ramsauer 2020）做关联融合。
Correction precision KPI	Every correction tracks precision = heeded / retrieved. <0.3 → archive candidate (noise). ≥0.8 → promote faster.	每条纠正跟踪 precision = 被遵守 / 被召回。<0.3 → archive 候选（噪声）。≥0.8 → 加速晋升。
Cross-project insights	Lessons learned in one project surface when you're working on a similar problem in another. Match by keyword + topic.	一个项目学到的经验，在另一个相似问题上会自动浮现。按关键词 + 主题匹配。
Awareness cap	Capped at 200 lines. New insights merge with existing (strengthening) or replace the weakest. After 100 sessions: still 200 lines, but cross-validated.	上限 200 行。新 insight 与已有合并（加强）或替换最弱的。100 次会话之后：仍然 200 行，但都是经过交叉验证的。

---

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

Change · 改动	Research grounding · 研究依据
Pipeline layer — project narrative spine with 5 MCP tools 叙事层 — 项目叙事主干 + 5 个 MCP 工具	Park et al. 2023 (Generative Agents) reflection pattern
Canonical naming system — virtual key + legacy_path, no migration needed 规范命名系统 — 虚拟键 + legacy_path，无需迁移	Squire 2004 taxonomy + CoALA architecture
Procedural memory (5th layer) — palace/skills/ + 3 MCP tools 程序记忆（第 5 层） — palace/skills/ + 3 个 MCP 工具	Squire 2004 declarative/non-declarative split, ACT-R production rules
Correction outcome KPIs — precision / heeded / recurrence tracking 纠正结果 KPI — precision / heeded / recurrence 追踪	Reflexion (Shinn 2023), RLAIF — making the learning loop measurable
FSRS-lite decay scorer — reinforce on recall, decay on staleness FSRS-lite 衰减打分 — 召回时强化，过期时衰减	Ebbinghaus 1885 → SuperMemo → FSRS-6 (Anki ≥23.10)
Modern Hopfield re-ranker — ξ_new = X·softmax(β·X^⊤·ξ) Modern Hopfield 重排 — ξ_new = X·softmax(β·X^⊤·ξ)	Ramsauer et al. 2020, exp(d/2) capacity vs classical 0.14·d
session_start lite mode — ≤500 tokens, pull-on-demand session_start lite 模式 — ≤500 tokens，按需召回	Anthropic 2026 context engineering — "smallest high-signal set"
Agent-readable dashboard.json — schema_version=1, one-call self-inspection Agent 可读的 dashboard.json — schema_version=1，一次调用自查	Agent-first principle — humans aren't the only readers
Reflection bundle — Park-style aggregation prompt (LLM call happens in the agent's turn, not core) 反思包 — Park 风格的聚合 prompt（LLM 调用在 agent 自己的 turn 里，不在 core）	Park 2023 §4.3
Security hardening — path traversal blocked, frontmatter YAML escaped, atomic writes, line-walk section parser 安全加固 — 路径穿越封堵、frontmatter YAML 转义、原子写入、按行解析章节	8-agent red-team P0 findings (2026-05-30)

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

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

---

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.