agentmemory × pi 集成指南为 pi 编码智能体接入持久化跨会话记忆【免费下载链接】agentmemory#1 Persistent memory for AI coding agents based on real-world benchmarks项目地址: https://gitcode.com/GitHub_Trending/age/agentmemorypi 是面向终端场景的编码智能体每个会话结束后上下文随即丢失导致重复解释项目背景与历史决策。agentmemory 为 pi 提供了一套基于原生扩展 API 的集成方案integrations/pi/index.ts在before_agent_start时注入相关记忆、在agent_end与每次工具调用后回写观察并暴露memory_health、memory_search、memory_save三个记忆工具与/agentmemory-status命令。读完本文你将掌握从零安装 pi 扩展、理解其生命周期钩子与 REST 调用链、以及通过环境变量安全加固连接的完整实操方案。集成原理为什么选择 pi 扩展 API 而非 MCPagentmemory 对其他编码智能体如 Claude Code、Hermes、OpenClaw提供了 MCP 服务器接入方式而 pi 集成刻意不使用 MCP。正如文档 Notes 一节所述This extension uses pis extension API, not MCP, so it can hook directly into the agent lifecycle.这是因为 pi 的扩展 API 允许直接挂接代理生命周期事件从而在智能体开始工作前注入记忆、在会话结束时回写观察实现 MCP 工具调用难以覆盖的「自动召回 自动捕获」闭环。从 integrations/pi/package.json 可以看到该包声明了pi: { extensions: [./index.ts] }清单并以earendil-works/pi-coding-agent与typebox作为 peer 依赖测试 test/connect-pi.test.ts 明确断言了这一包名与清单结构。底层通信方式则是直连 agentmemory 的 REST API扩展通过callAgentMemory统一封装GET/POST请求路径统一映射到{baseUrl}/agentmemory/{path}见 integrations/pi/index.ts。因此集成需要的是一个正在运行的 agentmemory 服务端而非 MCP 配置。快速安装三条命令完成部署第一步启动 agentmemory 服务端在独立终端中启动共享记忆服务默认监听localhost:3111npx agentmemory/agentmemoryagentmemory 是跨智能体共享的单一后端——同一个本地服务可同时服务 pi、pi2、Hermes、OpenClaw、Claude Code、Codex CLI、Gemini CLI文档 Notes 明确列出这也是「持久化跨会话记忆」的前提。第二步拷贝扩展到 pi 的全局扩展目录pi 会自动发现~/.pi/agent/extensions/*/index.ts因此将本仓库的扩展文件复制过去即可无需手工修改配置mkdir -p ~/.pi/agent/extensions/agentmemory cp integrations/pi/index.ts ~/.pi/agent/extensions/agentmemory/index.ts注意完整的扩展还依赖同目录下的 integrations/pi/security.tsindex.ts中以./security.js相对导入。手动拷贝时建议两个文件一并复制例如cp integrations/pi/index.ts integrations/pi/security.ts ~/.pi/agent/extensions/agentmemory/避免运行时找不到模块。第三步显式启用可选与热重载如果希望显式加载可在~/.pi/agent/settings.json中声明{ extensions: [~/.pi/agent/extensions/agentmemory] }由于扩展放在~/.pi/agent/extensions/agentmemory/下pi 会自动发现它若 pi 正在运行执行/reload即可热重载扩展无需重启。替代方案使用agentmemory connect pi一键安装仓库自带的 CLI 提供了更省心的安装路径。连接适配器实现在 src/cli/connect/pi.ts它会检测~/.pi/目录是否存在detect()从安装包内置的integrations/pi目录读取index.ts与security.ts并原子写入扩展目录覆盖写入前自动备份旧文件备份存放于~/.agentmemory/backups/内容一致时幂等跳过返回already-wired--force可强制重装dry-run模式不产生任何写入。对应测试 test/connect-pi.test.ts 验证了扩展目录缺失时检测失败、安装后文件与仓库源文件逐字节一致、重复安装幂等、过期副本会被刷新、修改过的文件会被备份、dry-run 零副作用。安装完成后提示语建议用/agentmemory-status验证正在运行的 pi 可通过/reload立即加载。功能清单pi 智能体获得的能力安装扩展后pi 获得以下能力对应文档 What it adds 一节能力类型作用memory_healthTool确认共享记忆服务可达且健康memory_searchTool检索历史决策、bug、工作流与用户偏好memory_saveTool将持久事实写回长期记忆/agentmemory-statusCommand在 pi 内部检查记忆服务健康状态before_agent_startrecallHook在提示词中注入相关记忆agent_endcaptureHook将完成的对话轮次回写 agentmemory下面逐一深入源码实现。三个记忆工具与一个状态命令memory_health健康探测memory_health工具内部调用GET {baseUrl}/agentmemory/health将响应中的status/health.status与version拼装为文本返回服务不可达时返回agentmemory is unreachable at http://localhost:3111并附带details: { ok: false }integrations/pi/index.ts。pi 智能体可据此判断是否值得调用记忆工具。memory_search跨会话智能检索memory_search接收query必填与limit可选1~10默认5请求POST /agentmemory/smart-search并把当前项目名作为project字段一并发送integrations/pi/index.ts。结果经formatSearchResults格式化最多展示前 5 条每条输出标题 (类型) [scorexxx]及叙事摘要无结果时返回No relevant memories found.见 integrations/pi/index.ts。底层 smart-search 是 agentmemory 的混合检索BM25 向量 知识图谱因此能召回「先前决策、偏好、bug 修复、工作流」等结构化记忆而非简单的全文匹配。memory_save写入持久事实memory_save接收content要记住的内容与可选的type记忆类型默认fact请求POST /agentmemory/remember同样携带project字段成功后返回Saved memory (fact): ...integrations/pi/index.ts。/agentmemory-status命令行健康检查注册为 pi 命令agentmemory-statusintegrations/pi/index.ts执行时探测 health 接口成功则notify(agentmemory healthy vX.Y.Z, info)失败则notify(agentmemory is unreachable at http://localhost:3111, warning)。这既是安装后的冒烟测试入口也是日常排障工具。生命周期钩子自动召回与自动捕获扩展通过pi.on(...)挂接五个生命周期事件形成「会话开始 → 智能体启动 → 工具执行 → 智能体结束 → 会话关闭」的完整记忆闭环。session_start建立会话并上报会话开始时扩展从ctx.sessionManager.getSessionFile()推导会话 ID取文件名去扩展名否则生成ephemeral-uuid前缀的临时 ID解析当前工作目录与项目名并先刷新健康状态——只有服务健康lastHealthOk才会调用POST /agentmemory/session/start上报{ sessionId, project, cwd }integrations/pi/index.ts。before_agent_start提示词注入记忆这是「不再重复解释」的核心钩子integrations/pi/index.ts每次智能体启动前执行以用户提示词作为查询调用smart-searchlimit: 5限定当前项目将命中的记忆拼装成Relevant long-term memory from agentmemory:块连同固定的工具引导语TOOL_GUIDANCE提示智能体用memory_search回忆、用memory_save保存持久事实一起追加到系统提示词末尾通过return { systemPrompt: [...] }生效。同时若健康且提示词非重复还会异步调用POST /agentmemory/observehookType: prompt_submit记录用户输入。这里存在一个 5 分钟窗口的 SHA-256 去重机制DEDUP_WINDOW_MS见 integrations/pi/index.ts当自动重试重复提交相同提示词时跳过重复观察避免污染记忆库。tool_result记录每次工具调用每次 pi 工具执行后触发tool_result事件默认开启AGENTMEMORY_TOOL_OBSERVE ! 0将工具名、输入、输出各自截断到 8000 字符以及错误标记isError异步上报到observehookType: post_tool_useintegrations/pi/index.ts。这使记忆库能捕获解决某 bug 时执行了哪些命令这类高价值过程信息。agent_end保存完整对话轮次智能体结束时扩展从event.messages中提取最后一段助手文本getLastAssistantText从后向前找role assistant的文本内容见 integrations/pi/index.ts与本次提示词一起以tool_name: conversation的形式上报observeintegrations/pi/index.ts。这样「问题 → 结论」的完整轮次会被持久化供后续会话检索。session_shutdown结束会话并触发整合session_shutdown事件只在reason quit时真正结束会话/new、/resume、/fork与重载也会触发该事件但会被过滤随后调用POST /agentmemory/session/end5 秒超时并异步触发POST /agentmemory/consolidate启动后台整合integrations/pi/index.ts。注释明确指出会话摘要在服务端由session/end统一扇出完成。项目作用域多智能体共享同一记忆桶扩展在解析项目名时遵循与其他 hooks 一致的顺序AGENTMEMORY_PROJECT_NAME环境变量优先 → git 仓库顶层目录名 → 当前工作目录名见 integrations/pi/index.ts并通过projectCache缓存避免重复执行git rev-parse --show-toplevel。这样 pi 会话与 Claude Code、Codex CLI 等其他智能体落在同一个项目桶内实现真正的跨智能体记忆共享而不是按原始路径各自为政。环境变量配置与安全防护变量默认值说明AGENTMEMORY_URLhttp://localhost:3111agentmemory 服务地址AGENTMEMORY_SECRET无受保护实例的 Bearer TokenAGENTMEMORY_REQUIRE_HTTPS关闭设为1时拒绝向非回环地址的明文 HTTP 发送 Bearer Token仅在AGENTMEMORY_URL为https://...或指向localhost/127.0.0.1/::1时发送。关闭时插件仅警告一次但仍发送AGENTMEMORY_PROJECT_NAME无显式覆盖项目名优先于 git 推导AGENTMEMORY_TOOL_OBSERVE开启设为0可关闭tool_result工具调用观察其中AGENTMEMORY_SECRET与AGENTMEMORY_REQUIRE_HTTPS的安全语义由 integrations/pi/security.ts 实现usesPlaintextBearerAuth判定「配置了 secret 且目标为http:协议且非回环主机」一旦命中REQUIRE_HTTPS1时直接抛出异常拒绝发送否则仅通过console.warn警告一次提示 Bearer Token 与记忆负载可能被网络嗅探建议改用 HTTPS 或 SSH 隧道。该守卫在每次 REST 调用前callAgentMemory内以及扩展初始化时REQUIRE_HTTPS1时都会被触发。冒烟测试与验证安装完成后在 pi 中直接执行/agentmemory-status预期输出agentmemory healthy且界面底部状态栏出现 agentmemory徽标refreshStatus通过ctx.ui.setStatus(agentmemory, ...)写入见 integrations/pi/index.ts。也可以让 pi 直接调用memory_health工具验证。若状态为 agentmemory off或提示不可达通常意味着 agentmemory 服务未启动或AGENTMEMORY_URL指向错误——回到第一步确认npx agentmemory/agentmemory正在运行。与其他智能体集成的对比与取舍同样位于integrations/目录下的其他智能体采用了不同接入形态可作为理解 pi 方案定位的参照Hermesintegrations/hermes/README.md提供 MCP 服务器零代码54 个记忆工具与内存提供者插件更深集成含prefetch、sync_turn、on_session_end、on_pre_compress、on_memory_write、system_prompt_block六个生命周期钩子两条路径OpenClawintegrations/openclaw/README.mdMCP43 个工具 内存插件before_agent_start召回、agent_end捕获需在openclaw.json中授权对话读取钩子。pi 集成则只走原生扩展 API用更少的依赖仅 peer 依赖 pi 核心与 typebox实现同等的召回 捕获 工具闭环且与三者共享同一个 agentmemory 服务端记忆完全互通。参考与延伸阅读集成核心实现integrations/pi/index.ts、安全守卫 integrations/pi/security.ts、包清单 integrations/pi/package.jsonCLI 一键安装适配器src/cli/connect/pi.ts安装与行为验证测试test/connect-pi.test.tsagentmemory 主文档README.md其他智能体集成integrations/hermes/README.md、integrations/openclaw/README.md【免费下载链接】agentmemory#1 Persistent memory for AI coding agents based on real-world benchmarks项目地址: https://gitcode.com/GitHub_Trending/age/agentmemory创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 agentmemory × pi 集成指南：为 pi 编码智能体接入持久化跨会话记忆
agentmemory × pi 集成指南为 pi 编码智能体接入持久化跨会话记忆【免费下载链接】agentmemory#1 Persistent memory for AI coding agents based on real-world benchmarks项目地址: https://gitcode.com/GitHub_Trending/age/agentmemorypi 是面向终端场景的编码智能体每个会话结束后上下文随即丢失导致重复解释项目背景与历史决策。agentmemory 为 pi 提供了一套基于原生扩展 API 的集成方案integrations/pi/index.ts在before_agent_start时注入相关记忆、在agent_end与每次工具调用后回写观察并暴露memory_health、memory_search、memory_save三个记忆工具与/agentmemory-status命令。读完本文你将掌握从零安装 pi 扩展、理解其生命周期钩子与 REST 调用链、以及通过环境变量安全加固连接的完整实操方案。集成原理为什么选择 pi 扩展 API 而非 MCPagentmemory 对其他编码智能体如 Claude Code、Hermes、OpenClaw提供了 MCP 服务器接入方式而 pi 集成刻意不使用 MCP。正如文档 Notes 一节所述This extension uses pis extension API, not MCP, so it can hook directly into the agent lifecycle.这是因为 pi 的扩展 API 允许直接挂接代理生命周期事件从而在智能体开始工作前注入记忆、在会话结束时回写观察实现 MCP 工具调用难以覆盖的「自动召回 自动捕获」闭环。从 integrations/pi/package.json 可以看到该包声明了pi: { extensions: [./index.ts] }清单并以earendil-works/pi-coding-agent与typebox作为 peer 依赖测试 test/connect-pi.test.ts 明确断言了这一包名与清单结构。底层通信方式则是直连 agentmemory 的 REST API扩展通过callAgentMemory统一封装GET/POST请求路径统一映射到{baseUrl}/agentmemory/{path}见 integrations/pi/index.ts。因此集成需要的是一个正在运行的 agentmemory 服务端而非 MCP 配置。快速安装三条命令完成部署第一步启动 agentmemory 服务端在独立终端中启动共享记忆服务默认监听localhost:3111npx agentmemory/agentmemoryagentmemory 是跨智能体共享的单一后端——同一个本地服务可同时服务 pi、pi2、Hermes、OpenClaw、Claude Code、Codex CLI、Gemini CLI文档 Notes 明确列出这也是「持久化跨会话记忆」的前提。第二步拷贝扩展到 pi 的全局扩展目录pi 会自动发现~/.pi/agent/extensions/*/index.ts因此将本仓库的扩展文件复制过去即可无需手工修改配置mkdir -p ~/.pi/agent/extensions/agentmemory cp integrations/pi/index.ts ~/.pi/agent/extensions/agentmemory/index.ts注意完整的扩展还依赖同目录下的 integrations/pi/security.tsindex.ts中以./security.js相对导入。手动拷贝时建议两个文件一并复制例如cp integrations/pi/index.ts integrations/pi/security.ts ~/.pi/agent/extensions/agentmemory/避免运行时找不到模块。第三步显式启用可选与热重载如果希望显式加载可在~/.pi/agent/settings.json中声明{ extensions: [~/.pi/agent/extensions/agentmemory] }由于扩展放在~/.pi/agent/extensions/agentmemory/下pi 会自动发现它若 pi 正在运行执行/reload即可热重载扩展无需重启。替代方案使用agentmemory connect pi一键安装仓库自带的 CLI 提供了更省心的安装路径。连接适配器实现在 src/cli/connect/pi.ts它会检测~/.pi/目录是否存在detect()从安装包内置的integrations/pi目录读取index.ts与security.ts并原子写入扩展目录覆盖写入前自动备份旧文件备份存放于~/.agentmemory/backups/内容一致时幂等跳过返回already-wired--force可强制重装dry-run模式不产生任何写入。对应测试 test/connect-pi.test.ts 验证了扩展目录缺失时检测失败、安装后文件与仓库源文件逐字节一致、重复安装幂等、过期副本会被刷新、修改过的文件会被备份、dry-run 零副作用。安装完成后提示语建议用/agentmemory-status验证正在运行的 pi 可通过/reload立即加载。功能清单pi 智能体获得的能力安装扩展后pi 获得以下能力对应文档 What it adds 一节能力类型作用memory_healthTool确认共享记忆服务可达且健康memory_searchTool检索历史决策、bug、工作流与用户偏好memory_saveTool将持久事实写回长期记忆/agentmemory-statusCommand在 pi 内部检查记忆服务健康状态before_agent_startrecallHook在提示词中注入相关记忆agent_endcaptureHook将完成的对话轮次回写 agentmemory下面逐一深入源码实现。三个记忆工具与一个状态命令memory_health健康探测memory_health工具内部调用GET {baseUrl}/agentmemory/health将响应中的status/health.status与version拼装为文本返回服务不可达时返回agentmemory is unreachable at http://localhost:3111并附带details: { ok: false }integrations/pi/index.ts。pi 智能体可据此判断是否值得调用记忆工具。memory_search跨会话智能检索memory_search接收query必填与limit可选1~10默认5请求POST /agentmemory/smart-search并把当前项目名作为project字段一并发送integrations/pi/index.ts。结果经formatSearchResults格式化最多展示前 5 条每条输出标题 (类型) [scorexxx]及叙事摘要无结果时返回No relevant memories found.见 integrations/pi/index.ts。底层 smart-search 是 agentmemory 的混合检索BM25 向量 知识图谱因此能召回「先前决策、偏好、bug 修复、工作流」等结构化记忆而非简单的全文匹配。memory_save写入持久事实memory_save接收content要记住的内容与可选的type记忆类型默认fact请求POST /agentmemory/remember同样携带project字段成功后返回Saved memory (fact): ...integrations/pi/index.ts。/agentmemory-status命令行健康检查注册为 pi 命令agentmemory-statusintegrations/pi/index.ts执行时探测 health 接口成功则notify(agentmemory healthy vX.Y.Z, info)失败则notify(agentmemory is unreachable at http://localhost:3111, warning)。这既是安装后的冒烟测试入口也是日常排障工具。生命周期钩子自动召回与自动捕获扩展通过pi.on(...)挂接五个生命周期事件形成「会话开始 → 智能体启动 → 工具执行 → 智能体结束 → 会话关闭」的完整记忆闭环。session_start建立会话并上报会话开始时扩展从ctx.sessionManager.getSessionFile()推导会话 ID取文件名去扩展名否则生成ephemeral-uuid前缀的临时 ID解析当前工作目录与项目名并先刷新健康状态——只有服务健康lastHealthOk才会调用POST /agentmemory/session/start上报{ sessionId, project, cwd }integrations/pi/index.ts。before_agent_start提示词注入记忆这是「不再重复解释」的核心钩子integrations/pi/index.ts每次智能体启动前执行以用户提示词作为查询调用smart-searchlimit: 5限定当前项目将命中的记忆拼装成Relevant long-term memory from agentmemory:块连同固定的工具引导语TOOL_GUIDANCE提示智能体用memory_search回忆、用memory_save保存持久事实一起追加到系统提示词末尾通过return { systemPrompt: [...] }生效。同时若健康且提示词非重复还会异步调用POST /agentmemory/observehookType: prompt_submit记录用户输入。这里存在一个 5 分钟窗口的 SHA-256 去重机制DEDUP_WINDOW_MS见 integrations/pi/index.ts当自动重试重复提交相同提示词时跳过重复观察避免污染记忆库。tool_result记录每次工具调用每次 pi 工具执行后触发tool_result事件默认开启AGENTMEMORY_TOOL_OBSERVE ! 0将工具名、输入、输出各自截断到 8000 字符以及错误标记isError异步上报到observehookType: post_tool_useintegrations/pi/index.ts。这使记忆库能捕获解决某 bug 时执行了哪些命令这类高价值过程信息。agent_end保存完整对话轮次智能体结束时扩展从event.messages中提取最后一段助手文本getLastAssistantText从后向前找role assistant的文本内容见 integrations/pi/index.ts与本次提示词一起以tool_name: conversation的形式上报observeintegrations/pi/index.ts。这样「问题 → 结论」的完整轮次会被持久化供后续会话检索。session_shutdown结束会话并触发整合session_shutdown事件只在reason quit时真正结束会话/new、/resume、/fork与重载也会触发该事件但会被过滤随后调用POST /agentmemory/session/end5 秒超时并异步触发POST /agentmemory/consolidate启动后台整合integrations/pi/index.ts。注释明确指出会话摘要在服务端由session/end统一扇出完成。项目作用域多智能体共享同一记忆桶扩展在解析项目名时遵循与其他 hooks 一致的顺序AGENTMEMORY_PROJECT_NAME环境变量优先 → git 仓库顶层目录名 → 当前工作目录名见 integrations/pi/index.ts并通过projectCache缓存避免重复执行git rev-parse --show-toplevel。这样 pi 会话与 Claude Code、Codex CLI 等其他智能体落在同一个项目桶内实现真正的跨智能体记忆共享而不是按原始路径各自为政。环境变量配置与安全防护变量默认值说明AGENTMEMORY_URLhttp://localhost:3111agentmemory 服务地址AGENTMEMORY_SECRET无受保护实例的 Bearer TokenAGENTMEMORY_REQUIRE_HTTPS关闭设为1时拒绝向非回环地址的明文 HTTP 发送 Bearer Token仅在AGENTMEMORY_URL为https://...或指向localhost/127.0.0.1/::1时发送。关闭时插件仅警告一次但仍发送AGENTMEMORY_PROJECT_NAME无显式覆盖项目名优先于 git 推导AGENTMEMORY_TOOL_OBSERVE开启设为0可关闭tool_result工具调用观察其中AGENTMEMORY_SECRET与AGENTMEMORY_REQUIRE_HTTPS的安全语义由 integrations/pi/security.ts 实现usesPlaintextBearerAuth判定「配置了 secret 且目标为http:协议且非回环主机」一旦命中REQUIRE_HTTPS1时直接抛出异常拒绝发送否则仅通过console.warn警告一次提示 Bearer Token 与记忆负载可能被网络嗅探建议改用 HTTPS 或 SSH 隧道。该守卫在每次 REST 调用前callAgentMemory内以及扩展初始化时REQUIRE_HTTPS1时都会被触发。冒烟测试与验证安装完成后在 pi 中直接执行/agentmemory-status预期输出agentmemory healthy且界面底部状态栏出现 agentmemory徽标refreshStatus通过ctx.ui.setStatus(agentmemory, ...)写入见 integrations/pi/index.ts。也可以让 pi 直接调用memory_health工具验证。若状态为 agentmemory off或提示不可达通常意味着 agentmemory 服务未启动或AGENTMEMORY_URL指向错误——回到第一步确认npx agentmemory/agentmemory正在运行。与其他智能体集成的对比与取舍同样位于integrations/目录下的其他智能体采用了不同接入形态可作为理解 pi 方案定位的参照Hermesintegrations/hermes/README.md提供 MCP 服务器零代码54 个记忆工具与内存提供者插件更深集成含prefetch、sync_turn、on_session_end、on_pre_compress、on_memory_write、system_prompt_block六个生命周期钩子两条路径OpenClawintegrations/openclaw/README.mdMCP43 个工具 内存插件before_agent_start召回、agent_end捕获需在openclaw.json中授权对话读取钩子。pi 集成则只走原生扩展 API用更少的依赖仅 peer 依赖 pi 核心与 typebox实现同等的召回 捕获 工具闭环且与三者共享同一个 agentmemory 服务端记忆完全互通。参考与延伸阅读集成核心实现integrations/pi/index.ts、安全守卫 integrations/pi/security.ts、包清单 integrations/pi/package.jsonCLI 一键安装适配器src/cli/connect/pi.ts安装与行为验证测试test/connect-pi.test.tsagentmemory 主文档README.md其他智能体集成integrations/hermes/README.md、integrations/openclaw/README.md【免费下载链接】agentmemory#1 Persistent memory for AI coding agents based on real-world benchmarks项目地址: https://gitcode.com/GitHub_Trending/age/agentmemory创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考