feat: vendor official hippo memory extension

AGENTS.md

@@ -31,14 +31,17 @@
 - 初始导入快照：`ddfb23646fd3957b791214de278e23aa393c9b13`（`v0.3.6`）。
 - 该目录不是 submodule，不保留嵌套 `.git`、上游 `.pi` 状态、`node_modules` 或构建产物。
 - `pi-lsp@0.1.7`：提供声明式 LSP 接入；组合包内置 `typescript-language-server@5.3.0` + `typescript@6.0.3`，并配置机器级 `kotlin-lsp --stdio` 与 `jdtls`。
-- `pi-hermes-memory@0.9.6`：提供持久记忆、会话搜索、后台学习和 secret scanning，默认使用 policy-only 模式。
+- `hippo-memory-pi/`：从官方 `hippo-memory` 仓库的 `extensions/pi-extension/` 导入并由本仓库直接维护；提供 session start 项目记忆注入、工具错误过滤捕获、session shutdown sleep 和 5 个 `hippo_*` 工具。
+- 上游来源：<https://github.com/kitfunso/hippo-memory>
+- 初始导入快照：`e928179a3b35e8fe5837878aed071d6025ced45c`（`v1.33.0`）。
+- 官方 npm tarball 不包含 Pi Extension；仓库保留官方 README、LICENSE 和来源说明，匹配 CLI 版本由 `config/hippo-memory-version` 声明。
 - `@ogulcancelik/pi-codex-compaction@0.1.3`：为 `openai-codex` 提供原生远程 compaction，默认阈值为 90%。
 - `@ogulcancelik/pi-minimal-footer@0.1.10`：用紧凑的上下文仪表和订阅用量条替换默认 footer。
 - `pi-condense@2.9.1`：总结已完成的工具调用批次，以短 stub 替换历史原始输出，并通过 `context_tree_query` 按需恢复；组合包在用户尚未配置 `contextPrune.enabled` 时默认开启。
 - 根包还固定安装 `@tavily/pi-extension@0.1.2`、`@keenable/pi-search@0.1.2`、`pi-hashline-edit@0.8.3`、`typescript-language-server@5.3.0`、`typescript@6.0.3`、`pi-context-view` 和 `@firstpick/pi-extension-codex-fast-mode`；`@gotgenes/pi-permission-system` 与 `pi-tool-search` 分别指向仓库内对应目录的本地 `file:` 依赖。
-- `install.sh`：先安装根组合包，再交互检查 Kitty/Solarized Dark、Oh My Zsh/Powerlevel10k/Zsh 插件、CodeGraph、Kotlin LSP、Java 21+ 和 JDT LS；缺失项目只在用户明确选择 `Y` 后安装或配置。Powerlevel10k 默认配置来自仓库内置的 `config/p10k.zsh`（当前 Rainbow/ASCII 单行紧凑主题）。
+- `install.sh`：先安装根组合包，再交互检查 Hippo Memory CLI、Kitty/Solarized Dark、Oh My Zsh/Powerlevel10k/Zsh 插件、CodeGraph、Kotlin LSP、Java 21+ 和 JDT LS；缺失项目只在用户明确选择 `Y` 后安装或配置。Hippo 项目目录与 `hippo init` 始终由用户自行决定。Powerlevel10k 默认配置来自仓库内置的 `config/p10k.zsh`（当前 Rainbow/ASCII 单行紧凑主题）。
 - `update.sh`：先通过 `pi update` 升级根组合包，再只升级当前已安装的终端环境和机器级依赖；未安装项直接跳过。升级前先查询并比较本地与远端版本，只有版本不同时才下载或替换；Powerlevel10k 配置优先从 `pi update` 后的已安装组合包读取，并与 `.zshrc` 受管块一起按内容比较后增量同步。
-- `uninstall.sh`：只移除根组合包，不卸载或还原可能被其他项目共享的终端环境、CodeGraph、Kotlin LSP、JDT LS 或 Java。
+- `uninstall.sh`：先移除根组合包；若检测到 Hippo Memory CLI，再明确询问是否卸载确认属于 npm 全局安装的 `hippo-memory`，默认保留且始终不删除 `.hippo/` 或用户记忆数据。其他共享终端环境和机器工具不卸载。
 
 ## 当前职责与默认行为
 
@@ -69,10 +72,13 @@
 - `config/pi-permission-system.json` 必须显式配置 `authorizerChain: ["auto-review"]`，并把需要自动复核的 Git 非只读操作、包管理及其他类别声明为 `ask`；硬 `deny` 不得改成可由模型覆盖的 `ask`。
 - `pi-lsp` 的 TypeScript/JavaScript 后端由根包固定依赖提供，`extensions/lsp.ts` 使用当前 Node 可执行文件直接启动包内 `typescript-language-server` CLI，不得依赖或调用 VS Code GUI；Kotlin/JDT LS 仍使用组合包部署的 `kotlin-lsp --stdio` 与 `jdtls` 配置，根包不安装这两个系统可执行文件，便捷脚本可在用户逐项明确确认后通过 Homebrew 安装 Kotlin LSP、Java 21 和 JDT LS。
 - 终端环境配置只属于便捷脚本：Kitty 可选安装后可通过官方 kitten 启用 Solarized Dark；Oh My Zsh 使用不切换 shell 的 unattended 安装；Powerlevel10k 将仓库内置的 `config/p10k.zsh`（Rainbow/ASCII 单行紧凑主题）部署到 `~/.config/my-pi/p10k.zsh`（遵循 `XDG_CONFIG_HOME`），不得覆盖用户自己的 `~/.p10k.zsh`。`.zshrc` 中脚本拥有的内容必须使用 `# >>> my-pi:<id> >>>` / `# <<< my-pi:<id> <<<` 受管块，更新时只替换块内内容；标记不完整或重复时拒绝修改。实际修改前必须创建带时间戳的备份。`git`、`zsh-autosuggestions`、`zsh-syntax-highlighting` 在安装流程中逐项询问后才安装或启用。
-- Codex 远程压缩只对 `openai-codex` 生效，默认在 turn boundary 达到 90% 时触发；Hermes Memory 默认使用 policy-only 模式。
+- Codex 远程压缩只对 `openai-codex` 生效，默认在 turn boundary 达到 90% 时触发；官方 Hippo Extension 在已初始化项目的 session start 注入上下文、过滤捕获工具错误，并在 session shutdown 执行 `hippo sleep`。
+- Hippo Extension 直接使用 PATH 中的官方全局 `hippo` CLI；`install.sh` 只在 CLI 缺失且用户明确确认后安装 `config/hippo-memory-version` 指定的 npm 版本，不得扫描项目、选择初始化目录或执行 `hippo init`。用户必须在自己选择的项目目录中手动初始化。
+- `update.sh` 只升级已经安装且属于 npm 全局包的 Hippo CLI；必须从 `pi update` 后的组合包读取目标版本，先用 `npm view` 确认，再比较本地版本，版本相同不得重新安装，CLI 缺失或来源未知时保留现状。
+- `uninstall.sh` 只在根包移除成功后询问是否卸载 npm 全局 Hippo CLI，默认拒绝；不得删除项目 `.hippo/`、全局记忆或旧 Hermes 数据。
 - `install.sh` 默认从 `git:git@bitbucket.org:siakitem/my-pi.git` 安装，并允许用 `PI_PACKAGE_SOURCE` 覆盖来源；组合包安装失败时立即停止，机器级依赖安装失败时继续检查其余依赖并最终返回非零状态。
 - CodeGraph 的可选安装使用官方远程安装脚本；macOS Kitty 使用 Homebrew cask，其他系统使用 Kitty 官方安装器；Kotlin LSP、Java 21 和 JDT LS 使用 Homebrew；Oh My Zsh 使用官方安装器，Powerlevel10k 与两个第三方 Zsh 插件从各自官方 Git 仓库克隆。升级时 Git checkout、Homebrew 包、Kitty 官方安装和 CodeGraph 都必须先比较本地与远端版本，版本一致时不得重新下载安装；无法可靠比较时保留现状并报告。缺少 Homebrew、curl 或 git 时保留已经完成的组合包安装并报告失败。
-- `install.sh` 不检查默认不需要的 `rtk` CLI；`update.sh` 和 `uninstall.sh` 使用同一个 `PI_PACKAGE_SOURCE` 规则分别调用 `pi update` 和 `pi remove`。运行 `update.sh` 视为明确授权升级已安装组件及同步已有受管配置，但不得安装缺失组件或改写受管块之外的用户配置；卸载仍不改动共享机器级工具。
+- `install.sh` 不检查默认不需要的 `rtk` CLI；`update.sh` 和 `uninstall.sh` 使用同一个 `PI_PACKAGE_SOURCE` 规则分别调用 `pi update` 和 `pi remove`。运行 `update.sh` 视为明确授权升级已安装组件及同步已有受管配置，但不得安装缺失组件或改写受管块之外的用户配置；卸载仅可在用户当次明确确认后移除 npm 全局 Hippo CLI，其他共享机器级工具保持不变。
 
 ## 修改边界
 
@@ -80,7 +86,7 @@
 - 保留原项目的 `LICENSE`、版权信息和必要的来源说明。
 - 扩展运行目录中的 `config.json`、日志、构建产物、覆盖率目录和依赖目录属于本地状态，不应提交；`config/pi-permission-system.json`、`config/pi-hashline-edit.json` 与 `config/lsp.json` 分别是权限链、Hashline 默认行为和 LSP 后端的组合包权威源配置，必须提交并维护。
 - 外部 Pi 扩展依赖必须在根 `package.json` 中使用精确版本，并更新根 `package-lock.json`；不要用仓库级 `.pi/settings.json` 代替组合包依赖。
-- 需要原生构建的依赖只按锁定版本加入根 `allowScripts`；当前仅允许 Hermes Memory 所需的 `better-sqlite3`，不得批量批准其他 install scripts。
+- 需要原生构建的依赖只按锁定版本加入根 `allowScripts`；当前 `better-sqlite3@12.11.1` 仍由 Context Mode 使用并保持精确放行。官方 Hippo CLI 是独立机器级 npm 包，不得因此向根包批量批准其他 install scripts。
 - Pi 核心包只作为宿主 peer dependencies，不得在组合包内再安装或打包一套 Pi runtime；保留根 `.npmrc` 的 peer 安装策略。
 - `pi-tool-search/` 的根依赖必须保持 `file:./pi-tool-search`，组合包直接加载 `pi-tool-search/extensions/index.ts`；同步上游时先核对本地增量动态工具改造，禁止用旧 npm 入口或上游旧宿主实现直接覆盖。
 - 上游仅作为参考来源。同步上游改动时先核对本仓库已有修改，再按明确范围移植；不要直接覆盖本地实现。
@@ -125,6 +131,14 @@
 - reviewer 只能处理 `pi-permission-system` 已判定为 `ask` 的请求；不得绕过硬 `deny`，不得另加并行 `tool_call` 审批层，也不得扩大 `pi-permission-system` 明确授予的 delegation envelope。
 - 修改 reviewer 策略、可信证据边界、配置结构、模型解析或 authorizer 注册时，必须同步更新 README、schema 和相应测试。
 
+## `hippo-memory-pi` 开发约定
+
+- 扩展入口是 `hippo-memory-pi/index.ts`，来源记录是 `hippo-memory-pi/UPSTREAM.md`；只从官方 `kitfunso/hippo-memory` 的明确 tag/commit 移植 `extensions/pi-extension/`，保留官方 README、LICENSE 和版权。
+- 官方 npm tarball 当前不包含 Pi Extension，因此根包直接打包并加载本地源码；不得同时加载第三方 `@the-forge-flow/hippo-memory-pi` 或第二个 Hippo Pi Extension。
+- CLI 版本权威源是 `config/hippo-memory-version`；修改它时必须同步上游源码快照、README、AGENTS、安装/升级 mock 测试和扩展加载验证。
+- 扩展依赖 PATH 中的全局 `hippo`。CLI 缺失时必须 fail-safe，不得阻止其他扩展加载；项目未执行 `hippo init` 时不得擅自创建 `.hippo/`。
+
+
 ## `pi-tool-search` 开发约定
 
 - 扩展入口是 `pi-tool-search/extensions/index.ts`，组合包权威分组位于 `pi-tool-search/extensions/bundle-groups.ts`，目录生成/校验/缓存位于 `pi-tool-search/extensions/catalog.ts`，配置部署位于 `pi-tool-search/extensions/config.ts`，测试保留在 `pi-tool-search/test/`。
@@ -140,10 +154,13 @@
 
 安装、升级、卸载或搜索配置脚本变化时，至少运行 `sh -n install.sh`、`sh -n update.sh`、`sh -n uninstall.sh`、`sh -n search_config.sh` 和 ShellCheck，并核对脚本仍具有可执行权限、仍包含在根 `package.json` 的 `files` 中、README 描述与实际流程一致。搜索配置测试只能使用虚拟 key 和隔离 HOME，不得把真实 key 写入测试输出。涉及真实 `pi install`、`pi update`、`pi remove`、Homebrew、远程安装器、Git 克隆或真实用户终端配置的端到端验证属于外部写操作，未经明确要求不得执行；可以使用隔离的临时 HOME 和 mock 命令验证分支行为。
 
+Hippo 脚本变化必须额外用隔离 HOME/PATH 和 mock `pi`、`npm`、`hippo` 验证：安装缺失 CLI 但不调用 `hippo init`、相同版本不升级、不同版本精确升级、未知来源 CLI 不替换、卸载默认保留、明确确认后只卸载 npm 全局包且保留数据。不得在测试中执行真实全局 npm 写入或修改真实 `.hippo/`。
+
 在 `pi-permission-system/` 内至少运行 `npm run typecheck`、`npm run test` 和 `npm run build`。在 `pi-permission-auto-review/` 内至少运行同样三项；涉及权限集成时还要使用仓库内 `pi-permission-system` 验证 authorizer 注册、`allow` / `deny` / `defer` 与 delegation envelope。
 
 在 `pi-tool-search/` 内至少运行 `npm run typecheck`、`npm run test` 和 `npm run build`；涉及加载入口或 active-tool 行为时还要运行根扩展联合加载测试和实际 packed tarball 的隔离安装验证。
 
+
 在 `pi-rtk-optimizer/` 内按改动范围选择最小充分验证：
 
 - `npm run build`：TypeScript 转译检查。