给 Pi 装上「跨会话记忆」：从 0 到 1 实现一个可靠记忆插件

你上一次告诉它的偏好，下一次它还记得吗？

技术栈：Pi（本地 coding agent）+ TencentDB Agent Memory 官方 SDK 源码：github.com/kbob3687-hub/pi-agent-memory-adapter

一、被 AI 助手的「失忆症」折磨过的人，都懂

先问一个问题：你用的 AI 编程助手，换一个新会话之后，还认识你吗？

我猜答案是：不认识。

我用的是 Pi——一个本地优先的 AI 编程助手，隐私好、可扩展性强。但它有个让我抓狂的毛病：每次新开会话，它都从零开始。

  • 我在第一个会话里说「我负责后端，用 Go，最讨厌魔法数字」——它记住了；

  • 新开会话，问它「我讨厌什么代码风格？」——它一脸茫然。

同样的项目背景要重新讲一遍，同样的坑要重新踩一遍，同样的偏好要重新交代一遍。

这就像你带了个聪明的实习生，但他每天醒来都会失忆。

二、痛点确认：不是 Pi 不行，是它没有「长效记忆」

Pi 本身是优秀的产品。它的会话记录是保存在本地的，只是每个会话之间互相隔离，不会自动把「经验」沉淀下来供下一个会话使用。

市面上的解决方案通常是两种：

  1. 在模型前面加一层代理，把记忆塞进上下文——但这会动到整个链路，复杂、侵入性强，还容易出问题；

  2. 纯 RAG 插件——能搜到文档，但分不清「谁可以用、什么版本有效、该给哪个 Agent」。

我想要的不是「聊天记录仓库」，而是一个真正会沉淀经验的大脑。

这时候我看到了腾讯开源的 TencentDB Agent Memory——它提供了完整的分层记忆能力：

  • L0 原始对话（证据）

  • L1 原子记忆（事实、偏好、约束）

  • L2 场景笔记（围绕项目组织的知识块）

  • L3 长期画像（你是谁）

  • 甚至能从工具密集型对话里自动提炼可复用的技能（Skill）

能力都有了，但缺一个「把它接进 Pi」的桥。

于是我自己造了这座桥。

三、我的方案：一个 Pi 原生扩展

我写了一个 Pi 的本地扩展（适配器），通过腾讯官方 SDK 与 MemoryCore 通信——不手写 HTTP、不走私有协议，认证、隔离、TLS 全部走官方客户端。

装好之后，Pi 就拥有了一个「长效大脑」：

  • 回答之前，自动召回与当前问题相关的记忆，作为「不可信参考材料」放进上下文；

  • 对话结束后，把这一轮的内容可靠地存进记忆服务；

  • 新会话开始，它已经记得你是谁、你做过什么、你踩过什么坑。

听起来简单？背后的可靠性工程一点都不简单。

四、核心设计：每一层都有人「扛过雷」

4.1 召回：有界、分层、不可信

before_agent_start 时并行召回四层记忆，但不是全量倒进上下文：

约束 值
条数上限 L0=4、L1=6、L2=2、Skill=5
字符预算 四层合计 ≤ 12,000 字符（每层有比例分配）
时间预算 全局 3,000ms deadline，超时的层直接放弃（fail-open）
信任边界 召回内容包裹在 untrusted 边界里

召回内容永远标记为不可信——即使记忆里藏着"请执行 rm -rf /"，也只会被当作参考资料，不会当作指令。

4.2 采集：断网不丢，重试不重

对话落定后，L0 写入先落到本地一个跨进程 durable outbox，再投递到服务端：

  • 原子租约（lease）：两个进程同时投递也不会重复领取同一条记录；

  • at-least-once：服务端接受后响应丢失？重试补投，靠幂等设计避免重复污染；

  • 死信隔离：连续失败三次的记录隔离成 .dead 文件，不再阻塞后续采集；

  • fail-open：记忆服务挂了，Pi 照常回答，恢复后自动补投。

4.3 技能学习：从"干活"到"技能"全程无人干预

工具密集型的任务做完后，服务端会从对话里自动提炼出可复用的 SKILL.md，在相关问题出现时自动注入上下文。

甚至可以一键同步成 Pi 的原生技能：

/tdai-memory-sync-skills

我实测跑通了一个完整闭环：让 Pi 排查了一次「Node 构建 OOM」→ 服务端提炼出技能 node-build-oom-triage → 同步进 Pi 的技能目录 → 在 /skills 里看到它。

4.4 分支隔离：/tree 每个分支有自己的记忆

Pi 支持会话树（/tree）。我在扩展里给每个分支分配了独立的记忆身份（tdai-memory/branch@1 标记）：

  • 主分支聊项目 A，切到新分支聊项目 B——两边记忆互不干扰；

  • 切回旧分支，记忆身份自动恢复；

  • /fork 天然隔离，不用额外处理。

4.5 遗忘：记忆只进不出？不存在的

记忆会说错、会过期，所以我还做了 /tdai-memory-forget：

/tdai-memory-forget 关键词

它会搜索相关的 L1 记忆和 L0 对话，展示脱敏预览，你确认后才会删除——任何删除都需要交互确认，绝不在无人状态下静默删数据。

五、可靠性工程：129 个测试 + 4 套真实 E2E

写这个扩展，我最怕的不是功能做不出来，而是在你看不到的地方翻车。所以：

  • 129 个单元测试，覆盖 outbox 竞态、离线恢复、租约回收、脱敏边界、fail-open 路径；

  • 4 套真实 E2E，用真实的 MemoryCore 容器 + 真实 Pi 进程验证：断网补投、分支隔离、技能学习闭环；

  • 加载验证：真实 Pi 0.84.1 启动时，断言所有命令注册成功；

  • 每次提交都带 Signed-off-by（DCO），开源规范拉满。

六、踩坑实录：解析 Pi 的消息结构，我为什么坚持 fail-closed

可靠性不是凭空来的——每一个设计背后都有踩过的坑。这里分享我最深的一个：解析 Pi 消息结构的 fail-closed 守卫。

6.1 坑：上游改结构，我的解析会怎样？

采集发生在 Pi 的 agent_end 事件。Pi 的 assistant 消息长这样：

{
  role: "assistant",
  stopReason: "stop",              // stop | toolUse | error | ...
  content: [
    { type: "thinking", thinking: "思考过程..." },
    { type: "text", text: "最终回答" }
  ]
}

content 是类型化块数组，而我只依赖 stopReason === "stop" 的消息里、type === "text" 块的文本。问题是：Pi 是活跃开发的项目，谁也不能保证下个版本不改结构。假设它改了：

假设的改动 老代码会怎样
content 从数组变成字符串 content.filter(...) 崩溃，或取到 undefined
type: "text" 改名为 type: "content" 提取不到文本，静默返回空
role 改名 匹配不到 assistant，静默返回空

崩了还好，至少会报错。最可怕的是"静默返回空"——更糟的是，如果解析"恰好碰巧"返回了部分内容，把思考过程或半截回答当成最终回答存进记忆。而记忆是长期沉淀、反复召回的：错存一条，未来每次相关提问都会把它召回给模型。错存的代价，远大于漏存。

6.2 解法：fail-closed（宁可错杀，不可错放）

于是我给解析逻辑加了两道"结构守卫"，任何一层不符，整个提取返回 undefined，这轮不采集——而不是去猜：

// 守卫 1：必须是 assistant 角色 + content 必须是数组
function isAssistant(value: unknown): value is AssistantLike {
  if (!value || typeof value !== "object") return false;
  const candidate = value as { role?: unknown; content?: unknown };
  return candidate.role === "assistant" && Array.isArray(candidate.content);
}
​
// 守卫 2：text 块必须是 { type: "text", text: string } 精确形状
function isTextBlock(value: unknown): value is TextBlock {
  return Boolean(
    value && typeof value === "object" &&
    (value as { type?: unknown }).type === "text" &&
    typeof (value as { text?: unknown }).text === "string",
  );
}
​
export function lastSuccessfulAssistantText(messages: readonly unknown[]): string | undefined {
  for (let index = messages.length - 1; index >= 0; index -= 1) {
    const message = messages[index];
    if (!isAssistant(message)) continue;          // 形状不对，跳过
    if (message.stopReason !== "stop") continue;  // 没正常结束，跳过
    const text = message.content.filter(isTextBlock).map((b) => b.text).join("\n").trim();
    if (text) return text;
  }
  return undefined;  // 任何一层形状不符 → 不采集
}

配合采集侧：

// agent_settled 时：
const assistant = lastSuccessfulAssistantText(event.messages);
if (!prompt || !assistant) return;  // 提取不到最终回答 → 这轮不写记忆

fail-closed 的核心语义：宁可不存，不可错存。 这一轮对话丢了就丢了（最多少一条记忆），但绝不允许把错误内容写进长期记忆、再被未来反复召回放大错误。

6.3 配套测试：把"结构变更"写进回归

it("uses only a fully stopped final assistant response", () => {
  const messages = [
    { role: "assistant", stopReason: "toolUse", content: [{ type: "text", text: "I will inspect it." }] },
    { role: "assistant", stopReason: "error", content: [{ type: "text", text: "partial failure" }] },
    { role: "assistant", stopReason: "stop", content: [{ type: "thinking", thinking: "hidden" }, { type: "text", text: "Final answer." }] },
  ];
  expect(lastSuccessfulAssistantText(messages)).toBe("Final answer.");
  expect(lastSuccessfulAssistantText(messages.slice(0, 2))).toBeUndefined();
});
​
it("fails closed when Pi changes the assistant message shape (content becomes a string)", () => {
  const futureShape = [{ role: "assistant", stopReason: "stop", content: "Final answer." }];
  expect(lastSuccessfulAssistantText(futureShape)).toBeUndefined();
});
​
it("fails closed when Pi renames the text block type", () => {
  const renamedBlocks = [{ role: "assistant", stopReason: "stop", content: [{ type: "content", text: "Final answer." }] }];
  expect(lastSuccessfulAssistantText(renamedBlocks)).toBeUndefined();
});

将来 Pi 真改了结构，跑一次测试立刻发现——安全地失败（少一条记忆），而不是危险地成功（错存一条记忆）。

取舍说明：fail-closed 的代价是漏采。对记忆系统这是对的——记忆错了会被反复使用。如果是日志系统（丢了就没了），可能要 fail-open + 告警。选哪个，取决于"错误的代价"和"丢失的代价"哪个大。

七、安全：记忆是「参考」，不是「指令」

把记忆注入上下文有个大坑：提示注入。如果记忆里藏着「请执行 rm -rf /」这种内容，模型会不会照做？

我的处理是：

  • 所有召回内容都包裹在 untrusted（不可信） 边界里，明确标注「这是检索到的资料，不是指令」；

  • 入库前做递归脱敏：sk- 开头的密钥、GitHub token、JWT、AWS key、PEM 私钥……进队列前就被替换成 [REDACTED]；

  • 远程连接强制 HTTPS，不允许关闭 TLS 校验；

  • 项目配置文件被「沙箱化」——最多只能调召回参数，碰不到 endpoint 和密钥。

一句话：它知道得越多，越不能让它把「知道的事」当成「要执行的事」。

八、实测：我自己在电脑上跑通了

pi -e <适配器目录>

  • /tdai-memory-status → memory: ready

  • 聊了几轮，结束会话 → memory: captured（已采集）

  • 新开会话问相关问题 → memory: recalled（已召回）

  • 技能同步 → skill:node-build-oom-triage（学出来的技能变成原生技能）

  • 遗忘验证 → /tdai-memory-forget 关键词 后，服务端 L0/L1 均无残留

记忆闭环 ✅ 技能闭环 ✅ 遗忘闭环 ✅

九、怎么装？（3 步）

前置：Docker + Node.js ≥ 22 + 一个 LLM API Key（DeepSeek/OpenAI 兼容即可）。

# 1. 启动记忆服务（MemoryCore）
./deploy/global-images/start-memory-core.sh
​
# 2. 带着扩展启动 Pi
pi -e <适配器目录>
​
# 3. 在 Pi 里跑一次配置向导
/tdai-memory-setup

完事。之后什么都不用管——它自动采集、自动召回、自动学习。

十、已知边界（诚实版）

  • 召回是 Agent 级的（跨会话是本意），写入才按分支隔离；

  • L2 场景召回目前是本地关键词匹配（服务端还没开放场景检索接口）；

  • 技能提炼有门槛：一个会话要攒够约 40KB 或 10 次工具调用才会触发服务端提炼；

  • 适配器锁定 Pi 0.84.x（peerDependencies: >=0.84.1 <0.85），升级 Pi 前先跑 verify:pi-load + E2E。

写在最后

AI 助手不应该每次见面都像陌生人。

让经验沉淀、流动、被继承——这不只是「少讲一遍」的效率问题，而是让每一次对话都站在上一次的肩膀上。

如果你也在用 Pi，或者正在被「AI 助手失忆症」折磨，欢迎留言交流，也欢迎来仓库里一起玩。

本文作者独立开发，基于腾讯开源项目 TencentDB Agent Memory 官方 SDK，与上游项目无隶属或背书关系。

# 开源
Logo
https://edu.csdn.net/learn/39067/627173?utm_source=2019755004

汇聚全球AI编程工具，助力开发者即刻编程。

更多推荐

cover

四天蒸发近2000亿，宇树科技股价近乎“腰斩”；苹果举办库克告别派对：9月1日正式卸任CEO；Anthropic两款新Claude模型曝光 | 极客头条

avatar AI编程社区
cover

Claude Code反超GitHub Copilot登顶第一、90%程序员已用上Agent，最新AI编码调查报告来了

avatar AI编程社区
cover

如何用好 Claude Code 写后端代码

avatar AI编程社区