# 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

```bash
# Type check
npm run check

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

## Installation (for users)

```bash
pi install npm:pi-hermes-memory

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