docs: 拆分 AGENTS.md，根文件只保留全局规则

根 AGENTS.md 从约 78KB 压缩到约 10KB，避免作为常驻规则加载时被截断：
只保留仓库定位、扩展清单、跨扩展硬规则与通用验证命令。各扩展的维护
约定与验证命令移入对应目录的 AGENTS.md（新增 extensions/AGENTS.md 承载
系统提示词与根目录 TS/LSP 约定），上游来源记录统一放进各目录的中文
UPSTREAM.md，并补齐 pi-permission-system 与 pi-rtk-optimizer 的来源记录。

Generated with [Devin](https://devin.ai)

Co-Authored-By: Devin <158243242+devin-ai-integration[bot]@users.noreply.github.com>

pi-hermes-memory/AGENTS.md

@@ -1,3 +1,21 @@
+# 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