my-pi/pi-hermes-memory/AGENTS.md

my-pi 维护约定（优先于下文上游约定）

• 扩展入口是 pi-hermes-memory/src/index.ts，来源记录是 UPSTREAM.md；只从官方 chandra447/pi-hermes-memory 的明确 tag/commit 移植并保留官方 README、LICENSE 和版权。
• 根包必须通过 file:./pi-hermes-memory 提供依赖并直接加载仓库源码；不得同时安装或加载 npm 预编译入口，也不得保留第二个记忆扩展（hippo-memory-pi 已移除）。
• package.json 的 pi.extensions 必须把 ./pi-hermes-memory/src/index.ts 排在 ./pi-compaction/index.ts 之前：ExtensionRunner.emit() 在第一个返回 { cancel: true } 的 session_before_compact handler 处立即停止，而 pi-compaction 在判定无需压缩时正是这样返回，注册在其后的 handler 会被跳过从而静默禁用 flushOnCompact；根 tests/extension-load.test.ts 必须断言该顺序。
• 记忆默认 policy-only 模式：只注入 <memory-policy> 指令而不注入记忆正文，不改变 system prompt 前缀、对 DeepSeek 前缀缓存友好；模型需要历史上下文时主动调用 memory_search / session_search，写入用 memory_add / memory_replace / memory_remove，过程记忆用 skill_manage。
• 六个记忆工具与 context_tree_query 必须在 pi-tool-search/extensions/config.ts 的 BUNDLE_TOOL_SEARCH_DEFAULTS.alwaysEnabled 中常驻（不放入动态组——注入的 policy 指示模型在普通工作中调用记忆工具，恢复被投影的工具证据也不能依赖 tool_search 激活，常驻同时保持请求前缀稳定），并由 pi-tool-search/extensions/bundle-groups.ts 的 memory-recall / memory-management 分组提供目录元数据（context_tree_query 留在 memory-recall）。新增、删除或重命名这些工具时必须同步 bundle-groups.ts、BUNDLE_TOOL_SEARCH_DEFAULTS、config/tool-search.json（二者必须完全一致）、Tool Search 测试、权限策略与 pi-tool-search 的 README / CHANGELOG。它们只写扩展自己的 agent 目录数据或只读本地索引，不触碰工作区，因此在权限策略中默认 allow，避免每轮 AutoReview 往返。
• 依赖必须保持 better-sqlite3@^13.0.3：13.x 运行时使用包内 N-API 预编译二进制 prebuilds/<platform>.node，不依赖 node-gyp 编译产物，必须能由 npm 嵌套安装并与根 better-sqlite3@12.11.1 并存。不得把它降级回 12.x（Node 24 下会在进程退出时 SIGABRT），也不得让根包提升为单一版本；npm 因 binding.gyp 推断出的 node-gyp rebuild 不得批准，根 allowScripts 不新增条目。
• devDependencies 中的 @earendil-works/* 必须与根包当前版本精确一致。若写成 ^0.80.2 这类与根不兼容的范围，npm 会在本目录嵌套安装第二套 Pi runtime，违反"不得在组合包内再安装一套 Pi runtime"的纪律；typebox、tsx、typescript、@types/better-sqlite3 同理，必须钉到根已有版本。
• 全局记忆、项目记忆与 skill 位于 ~/.pi/agent/pi-hermes-memory/ 与 ~/.pi/agent/projects-memory/，属于用户数据，安装、升级与卸载脚本不得创建、迁移或删除；扩展配置位于已安装组合包的 config/pi-hermes-memory.json（其中路径类默认值由代码运行时计算），旧 ~/.pi/agent/hermes-memory-config.json 被忽略。
• 子会话（pi-subagents child）只读：src/subagent-mode.ts 用与 pi-subagents 相同的 <active_agent name="..."/> 契约检测——权威判定在 before_agent_start 的 systemPromptOptions.customPrompt（绝不检测渲染后提示词，主会话文档里也可能含该字面量），session_start 仅以"渲染提示词以该 tag 开头"作提前预判以跳过 session_start 写入；按 sessionManager 逐会话标记（同一进程内父子会话并发，不能用全局开关）。子会话中 memory_add/memory_replace/memory_remove/skill_manage 返回固定错误且零写入，后台 review、correction detection、compact/shutdown flush、live/shutdown session 索引与初始化迁移/同步全部跳过；memory_search/session_search 保持只读可用。
• skill_manage 是本扩展提供的能力，不是 Pi 宿主能力：Pi 只发现并加载 skill 目录（~/.pi/agent/skills/ 加扩展通过 resources_discover 注册的目录），没有创建 skill 的工具。该扩展同时承担 skill 写入与目录注册；不加载它，projects-memory/<项目>/skills/ 下的既有 skill 也不会被 Pi 发现。
• 修改工具注册、before_agent_start 注入策略、resources_discover 目录注册、SQLite 迁移或 consolidation 后，必须同步包内 README/CHANGELOG/docs，并运行根扩展联合加载与 Tool Search 测试。

验证

• 在本目录内运行包内测试与类型检查。记忆扩展变化必须额外验证：在隔离临时 Pi agent 目录中可加载且注册 6 个工具、pi.extensions 中排在 pi-compaction 之前、Tool Search 目录把六个工具归入 memory-recall / memory-management 且全部常驻、权限策略默认 allow、better-sqlite3@13 嵌套安装与根 12.11.1 并存。不得在测试中连接真实数据库或修改真实 ~/.pi/agent/ 记忆数据。

Pi Hermes Memory Extension

Project Overview

This is a Pi coding agent extension that brings Hermes-style persistent memory and a learning loop to any Pi user. After pi install, users get persistent memory across sessions, a background learning loop, and session-end flush.

v0.1 is complete (119 tests, v0.1.0 tagged). Current work is v0.2: Skills + Smart Curation — see docs/0.2/TASKS.md.

Architecture

• Language: TypeScript (loaded via jiti, no compilation needed at runtime)
• Runtime: Pi extension API (@earendil-works/pi-coding-agent)
• Storage: Two markdown files (MEMORY.md, USER.md) in ~/.pi/agent/memory/
• Entry point: src/index.ts — registers tools, event handlers, and commands

Key Files

File	Purpose
src/index.ts	Extension entry point — wires all components together
src/types.ts	Shared TypeScript interfaces + getMessageText() helper
src/constants.ts	Prompts, defaults, delimiter
src/store/memory-store.ts	Core MemoryStore class — CRUD, persistence, frozen snapshot
src/store/content-scanner.ts	scanContent() — injection/exfiltration detection
src/tools/memory-tool.ts	registerMemoryTool() — LLM tool definition
src/handlers/background-review.ts	setupBackgroundReview() — learning loop via pi.exec
src/handlers/session-flush.ts	setupSessionFlush() — pre-compaction/shutdown flush
src/handlers/insights.ts	registerInsightsCommand() — /memory-insights command
PLAN.md	Full v0.1 implementation plan with Hermes source file reference map
docs/ROADMAP.md	Full roadmap with Hermes competitive analysis + gap analysis
docs/0.2/TASKS.md	v0.2 task breakdown — Skills + Smart Curation

Design Decisions

1. Frozen snapshot — Memory is injected into system prompt once at session start, never mutated mid-session (preserves Pi's prompt caching)
2. Atomic writes — Temp file + fs.rename() for crash safety
3. pi.exec() for background review — Stays within Pi's intended extension API
4. § delimiter — Same as Hermes for consistency
5. No SQLite — Pi has its own SessionManager, we read from it directly

Hermes Source Reference

The implementation is ported from the Hermes agent harness. See PLAN.md → "Hermes Source File Reference Map" for exact files and line ranges to read.

Roadmap & Task Tracking

• Roadmap: docs/ROADMAP.md — full roadmap with Hermes competitive analysis, gap analysis, and phased plan (v0.1 → v0.5 → v1.0)
• v0.1 tasks (complete): docs/0.1/TASKS.md
• v0.2 tasks (current): docs/0.2/TASKS.md — Skills, auto-consolidation, correction detection, tool-call-aware nudge

Workflow:

1. Pick a task from docs/0.2/TASKS.md
2. Mark it [~] (in progress)
3. Implement it
4. Mark it [x] (done) with the commit hash
5. Move to the next task

Before starting any work, read docs/0.2/TASKS.md to see what's next.

Development

# Type check
npm run check

# Test locally
pi -e ./src/index.ts

Installation (for users)

pi install npm:pi-hermes-memory

# or from git
pi install git:github.com/chandra447/pi-hermes-memory