Recall

Polign Recall

Recall 为 Agent 提供可跨对话和进程保留的记忆与状态。记忆是 Agent 知道的内容：用户陈述的事实，以及保留的每一次更正，因此 Agent 可以说明自己现在相信什么、以前相信什么，以及原因。状态是 Agent 所处的位置：它的进度、留给下一个实例的笔记，以及尚在执行中的工具调用，因此即使运行崩溃或迁移到其他机器，也能根据自身记录恢复。

Recall 是一个 Go 库、一个提供与 MCP 工具和 HTTP 相同操作的 recall 二进制文件，以及一个 Python 客户端。它将所有内容存储在你运行的数据库中：polign_db、PostgreSQL、MongoDB 或 Qdrant。Apache 2.0。

同一位用户，九个月，三处住所、三家雇主、三个工作邮箱、六个问题；Claude Opus 5.5 为这三个系统提取信息、回答问题并进行评判：Recall 18/18，mem0 18/18，Zep 12/18。保存一条消息所需的 Token 数：Recall 3.0k，mem0 12.7k，Zep 14.7k。

安装

pip install polign-recall          # the Python client, the recall binary, and the database it runs
brew install polign/tap/recall     # the same for Homebrew
go install github.com/Polign/recall/cmd/recall@latest   # the binary alone; it fetches the database on first use

然后将它提供给你使用的 Agent：

claude mcp add recall -- recall mcp -write      # Claude Code

添加到 Cursor · 添加到 VS Code · 其他 MCP 主机：命令 recall，参数 mcp -write（详情）。

未进行任何配置时，记忆存储在本地数据库 ~/.local/share/recall 中，该数据库会在首次使用时启动，并由这台机器上的所有 Agent 共享。启动时不需要模型或 API 密钥。若要将记忆存储在你已运行的数据库中，请参阅后端。

更正示例

每次更改都会保留。三个命令可读取记录：

$ recall history "which editor do I use"
user preferred editor
  believed now: user preferred editor: zed
  2026-09-01 10:00  stated, user_stated
      + user preferred editor: vim
  2026-09-20 10:00  replaced, user_stated
      - user preferred editor: vim
      + user preferred editor: emacs
  2026-10-05 10:00  replaced, user_stated
      - user preferred editor: emacs
      + user preferred editor: zed

$ recall ask -as-of 2026-09-25 "which editor do I use"
Believed as of 2026-09-25 00:00:
user preferred editor: emacs  (since 2026-09-20)
  replaced: vim  (since 2026-09-01)

$ recall diff -from 2026-09-15 -to 2026-10-31
Changed between 2026-09-15 00:00 and 2026-10-31 00:00:
- user home city: Lisbon
+ user home city: Porto
- user preferred editor: vim
+ user preferred editor: zed

为什么选择 Recall

• 更正会被记录，而非覆盖。 新值会按照可读的规则替换旧值，每个答案都会附带被替换的内容。
• 任何时刻都可查阅。 as_of、history 和 diff 会说明 Agent 当时相信什么，以及何时发生了变化。
• 每个答案都有来源。 recall explain 会显示事实来自哪条消息、由哪条规则决定，以及它的历史记录。
• Agent 可根据记录恢复。 崩溃或迁移的 Agent 能取回自己的工作状态、近期轮次和未完成的工具调用，而非一份快照。
• 你的存储，由你定规则。 记忆存储在你已运行的数据库中，要记住什么由你定义，或由你自由决定。

快速入门

Python 3.10 或更高版本。保存一项偏好，然后更正它：

pip install polign-recall
python - <<'PY'
from polign_recall import Client

with Client(local_dir="./recall-data") as memory:
    memory.remember("user", "prefers_editor", "vim")
    memory.remember("user", "prefers_editor", "neovim")
PY

第二个进程会读取当前值、历史记录以及更正前的认知：

python - <<'PY'
from polign_recall import Client

with Client(local_dir="./recall-data") as memory:
    print(memory.recall("user", "prefers_editor")[0].value)   # neovim

    events = memory.history("user", "prefers_editor")
    print([e.value for e in events])                           # ['vim', 'neovim']

    before = memory.recall("user", "prefers_editor", as_of=events[0].observed_at)
    print(before[0].value)                                      # vim
PY

首个打开 ./recall-data 的客户端会为其启动本地数据库，之后的客户端会共享该数据库；程序退出后，记忆仍会保留在那里。直接使用 Client() 时，默认使用 ~/.local/share/recall，即这台机器上所有 Agent 共享的记忆。Python 客户端指南介绍了其他内容：使用模型的纯文本记忆、遗忘、历史记录以及恢复 Agent。

记忆的工作方式

一条记忆由 主体、谓词 和 带类型的值 组成：user、 prefers_editor、neovim。谓词存放在一个注册表中，其中定义了值的类型、 谓词是单值还是多值，以及它与哪些谓词相互矛盾：dislikes 与 likes 互斥， gave_away 与 owns 互斥。单值谓词会在出现新陈述时替换原值；多值谓词则会 累积值。遗忘会记录一条撤回记录，不会删除任何内容。Recall 提供用于编码、 个人助手、支持、销售和语音 Agent 的入门注册表， 你也可以稍后更改注册表，而无需修改 已经记住的内容。

你不必定义谓词。使用开放词汇时，谓词首次 使用时会自动定义；配置好模型后，MCP 工具会接收纯文本，任何地方都不会出现谓词：

recall setup -extract-model anthropic:claude-haiku-4-5-20251001

remember("I switched from helix to zed last week")
recall("which editor do I use?")  ->  "user prefers editor: zed" (before: helix)
forget("my editor")

模型会决定如何归档每条陈述。归档后，替换会遵循谓词的规则，每次归档都会被 记录，而错误的归档则通过一条事件更正，之后的每个回答都会遵循这条事件。模型 不会自行协调记忆：Recall 会应用注册表的规则，指出可能存在冲突的内容，并让 Agent 确认其余内容，因此每次更正都能追溯到触发更正的规则或陈述。recall mcp -typed 会改为提供带类型的工具（remember(subject, predicate, value)）。开发者参考 详细介绍了相关信息，Memory API 则定义了约定。

状态

Recall 的另一半，有自己的约定：docs/state-api-v1.md。Agent 在工作时会记录当前进展，新进程会根据这些记录恢复工作，而不是从快照恢复：

• 工作状态：目标、计划、进度、关注点、决策、待解决问题。
• 轮次：逐字记录；大型工具输出则按引用存储。
• 指针：指向工作所在位置，例如分支、对象键或进程。
• 操作：每次会影响外部环境的工具调用都会在执行前记录，并在完成后写入结果， 因此两者之间发生的崩溃会被显现出来；下次恢复时，该调用会被列为未确认，而不是重复执行。

Resume 会获取 Agent ID 的租约，确保同一时间只有一个进程代表该 Agent 行事； 它会在令牌预算内重建上下文，并将其呈现为一份供模型使用的简报：

agent, err := client.Resume(ctx, recall.ResumeRequest{AgentID: "coder-1", TokenBudget: 8000})
if err != nil {
    return err
}
defer agent.Release(context.Background())

briefing := agent.Resumed().Briefing // hand this to the model

相同的操作也可通过 MCP 工具（agent_resume、update_working_state、 record_turn、begin_action……）使用；执行 recall serve 时，还可通过 HTTP 路由 POST /v1/agent/<verb> 使用。通过 HTTP 调用时，服务端会在请求之间 持有租约：resume 会返回一个 epoch，每次写入都必须携带该值，因此过时的进程 无法覆盖后继进程的内容。State API 处于 Beta 阶段；它写入的记录是稳定的 （STABILITY.md）。恢复示例会在任务执行过程中 终止一个 Agent，并在新进程中继续执行。

为多个 Agent 提供服务

recall mcp 是一个 Agent、一个进程。recall serve 通过 HTTP 为多个 Agent 提供相同的记忆和状态，每个 Agent 都位于其密钥所命名的命名空间内。服务端持有数据库凭据；Agent 持有 Recall 密钥。

recall serve -backend polign -url http://polign:23000 -bootstrap-key-file admin.key
recall key create -backend polign -url http://polign:23000 -namespace acme:agent-7 -expires 168h

每个命名空间都有自己的集合，因此调用方发送的任何内容都无法触及其他命名空间的记录。POST /mcp 是基于可流式传输 HTTP 的 MCP；POST /v1/<tool> 将记忆工具的参数作为请求正文，POST /v1/agent/<verb> 则将状态工具的参数作为请求正文。任何 stdio MCP 客户端都可以通过设置 RECALL_URL 和 RECALL_API_KEY，使用 recall connect 连接到服务端。

在 Kubernetes 上，Pod 完全不需要密钥。使用 recall serve -kubernetes 时，Pod 会提交其投射的服务账户令牌，并获得一个固定绑定到自身 Agent ID 的短期密钥；recall connect 和 Python 客户端会自动获取并续期该密钥。Helm 图表位于 Polign/polign 的 charts/recall；agent-sandbox 演示 在 kind 上运行它。

后端

	本地（默认）	polign_db	PostgreSQL + pgvector	MongoDB	Qdrant
RECALL_BACKEND	local	polign	pgvector	mongodb	qdrant
RECALL_BACKEND_URL	一个目录	http://host:23000	postgres://user:pw@host/db	mongodb://user:pw@host/db	http://host:6333
记忆、历史记录、按时点查询	是	是	是	是	是
关键词搜索	是	是	是	是	否
缓存读取	是	是	是	是	否
状态 API（租约）	是	是	是	是	否

export RECALL_BACKEND=pgvector RECALL_BACKEND_URL=postgres://user:password@localhost:5432/mydb
recall mcp -write

三个设置项为每条命令指定数据库：-backend、-url 和 -key，或使用上面的变量。其余所有内容，包括各后端的需求以及如何添加后端，都见 docs/backends.md。

基准测试

LongMemEval 用户事实子集，包含 267 个关于用户自身事实、偏好、更新和日期的问题，由 Claude Sonnet 5.5 作为阅读器和评判者，并使用上游提示词：

提供给阅读器的内容	得分
无	6.0
完整聊天历史	88.0
对会话使用 BM25，取排名前 10 条	89.9
Recall，内置词语搜索	88.8
使用模型嵌入器的 Recall（OpenAI text-embedding-3-small，512 维）	92.9
仅包含答案的会话	96.6

使用词语搜索时，Recall 的总体表现与 BM25 持平，但在偏好问题上落后（70.0，对比 83.3）；使用模型嵌入器后，Recall 的表现则更好。Recall 为阅读器每个问题提供约 28k 个 token，而 BM25 提供 44k 个，完整历史记录提供 168k 个。测试框架位于 eval/longmemeval。

集成

Python	执行 pip install polign-recall，然后查看客户端指南。
Go	执行 go get github.com/Polign/recall，然后查看 Go 库指南。
MCP	将任意 Agent 连接起来，以便记住、回忆和遗忘。
Claude Code	Recall 插件：在编码会话之间保留记忆。
LangGraph	执行 pip install recall-langgraph，以恢复 LangGraph Agent。
LiveKit、Vapi	recall-livekit 和 recall-vapi，用于语音 Agent 的来电者记忆。
Pydantic AI	执行 pip install recall-pydantic-ai，为 Pydantic AI Agent 提供记忆工具。
Vercel AI SDK	Next.js 聊天示例，一键部署。
OpenClaw	npm 上的 @polign/openclaw-recall，OpenClaw 插件。

文档

开发者参考 · 记忆 API 契约 · 状态 API 契约 · 后端 · 通过 MCP 连接 · 缓存记忆读取 · 导出和重放历史记录 · 哪些内容稳定，哪些内容处于 Beta 阶段 · 开发指南

支持本项目

如果 Recall 曾让你的 Agent 避免依据过时事实采取行动，请为此仓库点个星，帮助其他人发现它。Bug、问题和想法请提交到 issues。

许可证

Apache 2.0。