chandra447/pi-hermes-memory

Pi Hermes Memory – 为 Pi 代理提供持久、可搜索的记忆

简介 – 一个官方 Pi 扩展，为 Pi 助手提供持久的知识库。它跨会话存储事实、用户偏好、失败日志和可复用的程序（称为技能），让代理能够搜索过去的对话，并保护机密不被持久化。

主要功能

功能	说明
会话搜索	通过 SQLite FTS5 对所有之前的 Pi 对话进行全文搜索（/session_search）。
持久记忆	事实、偏好和修正以 Markdown 格式（MEMORY.md、USER.md）保存，并在重启后仍然存在。
后台学习	每 10 轮（或 15 次工具调用）扩展会审查对话，提取失败、修正、见解，并写入记忆。
程序性技能	代理可以通过 skill_manage 工具创建、查看、修补、更新或删除可复用的 SKILL.md 文件（全局或项目范围）。
机密扫描	API 密钥、令牌、SSH 密钥等在被写入之前会自动被拒绝。
两层架构	全局记忆位于 ~/.pi/agent/pi-hermes-memory/；项目记忆位于 ~/.pi/agent/projects-memory/<项目>/。两者都可搜索。
自动整合	当 Markdown 记忆文件达到大小限制时，扩展会运行整合过程，合并或删除过期条目。
常驻指令	一个小型、用户控制的块（STANDING.md），注入到每个会话中，用于硬编码指令。
记忆老化与策略	条目带有时间戳；可配置的 <memory-policy> 告诉代理何时调用 memory_search。

工作原理

• 扩展创建三个主要存储：MEMORY.md（事实）、USER.md（个人资料）和一个镜像 Markdown 条目以实现无限搜索的 SQLite sessions.db。
• 所有写入都通过内容扫描器，该扫描器会剥离机密并阻止恶意负载。
• 代理可以调用专门工具（memory_add、memory_replace、memory_remove）直接操作记忆，并使用 skill_manage 处理程序性技能。
• 后台审查过程定期运行，提取有用的知识，并写入适当的存储。

安装

# 从 Pi 包管理器
pi install npm:pi-hermes-memory
# 或直接从 GitHub
pi install git:github.com/chandra447/pi-hermes-memory

您也可以不安装就在本地测试：

pi -e /path/to/pi-hermes-memory/src/index.ts

快速开始

# 索引现有会话（一次性）
/memory-index-sessions
# 将旧的 Markdown 记忆同步到 SQLite（可选）
/memory-sync-markdown
# 学习命令
/learn-memory-tool

典型工作流程：

1. 添加事实 – memory_add → "my project codename is ZEPHYR‑7741"。
2. 稍后回忆 – memory_search("ZEPHYR") 或直接询问代理。
3. 更新 – 使用 memory_replace 更改过时条目。
4. 删除 – 如果事实不再相关，使用 memory_remove。
5. 创建技能 – 使用结构化字段（when_to_use、procedure_steps 等）调用 skill_manage.create。

配置

• memoryPolicyStyle：full、compact、custom 或 none，控制注入的策略文本量。
• memoryMode：legacy-inject（将 Markdown 注入系统提示）或 policy-only（仅使用 SQLite 查询）。
• standingInstructionsEnabled：切换永久的 <standing-instructions> 块。

开发说明

• 发布的 npm 包省略了测试和 TypeScript 源代码；克隆仓库以运行 npm run check 和 npm test。
• 如果您的 Node ABI 不同，原生插件 better-sqlite3 可能需要重新构建（在 Homebrew 安装中很常见）。

重要性 如果没有此扩展，Pi 会在会话结束时忘记一切，迫使您重复偏好、项目约定或过去的失败。Pi Hermes Memory 为助手提供了一个可靠的、可搜索的“大脑”，随着时间的推移不断增长，同时保护机密安全，使长期运行或多项目的工作流程更加高效。