keepm 3.2.0__tar.gz → 3.4.0__tar.gz

{keepm-3.2.0/src/keepm.egg-info → keepm-3.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: keepm
-Version: 3.2.0
+Version: 3.4.0
 Summary: Admission-controlled local Markdown memory MCP for AI coding agents
 Project-URL: Homepage, https://github.com/LeoKon3/KeepM
 Project-URL: Repository, https://github.com/LeoKon3/KeepM
@@ -24,7 +24,7 @@ Dynamic: license-file
 
 > 带准入控制、本地优先、无模型依赖的 AI 编码 Agent 长期记忆引擎。
 
-[![Version](https://img.shields.io/badge/version-3.2.0-6f42c1.svg)](https://pypi.org/project/keepm/)
+[![Version](https://img.shields.io/badge/version-3.4.0-6f42c1.svg)](https://pypi.org/project/keepm/)
 [![Python](https://img.shields.io/badge/python-3.11%2B-3776ab.svg)](https://www.python.org/)
 [![MCP](https://img.shields.io/badge/MCP-supported-2ea44f.svg)](https://modelcontextprotocol.io/)
 [![License](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/LeoKon3/KeepM/blob/main/LICENSE)
@@ -98,16 +98,36 @@ uvx keepm setup
 `uvx` 会在隔离环境中运行 KeepM，无需永久安装。交互向导会完成最少且完整的接入：
 
 - 指定共用的 Markdown 存储根目录与默认记忆语言（`zh` / `en`）；
-- 选择 Codex 或 Claude Code；
+- 选择 Codex、Claude Code 或 pi；
 - 指定要接入的项目目录，默认使用当前工作目录；
 - 仅在该项目中注册 `keepm` stdio MCP Server、安装受管理的 Agent 记忆策略，并默认配置 `SessionStart` / `Stop` Hook。
 
+三个宓主的接入位置：
+
+| 宓主 | MCP 注册 | Agent 入口 | 生命周期 Hook |
+| --- | --- | --- | --- |
+| Codex | `.codex/config.toml` | `AGENTS.md` | `.codex/hooks.json` |
+| Claude Code | `.mcp.json` | `CLAUDE.md` | `.claude/settings.json` |
+| pi | `.mcp.json` | `AGENTS.md` | 无宓主 Hook 文件，报 `not-applicable` |
+
+pi 与 Claude Code 共用同一份项目 `.mcp.json`，且两边都把 `command` 条目视为 stdio，因此一次注册对两个宓主同时生效，不会互相覆盖。写入采用 JSON 合并：其他 MCP Server 和未知顶层字段全部保留；文件格式非法、是符号链接或不是普通文件时直接报错，绝不整体重写。pi 没有 Claude 那种宓主 Hook 配置文件，setup 会在文本和 JSON 中把 `lifecycle_hooks` 明确报为 `not-applicable`，而不伪造成功；相同的会话与 checkpoint 指引由受管理的 `AGENTS.md` 策略承担。
+
 自动化配置：
 
 ```bash
 uvx keepm setup --yes --root /path/to/notes --agent codex --project-dir /path/to/project
 ```
 
+`--agent` 可选 `codex`、`claude` 或 `pi`。
+
+CI、安装脚本或 Agent 还可以请求机器可读的验收摘要：
+
+```bash
+uvx keepm setup --yes --format json --root /path/to/notes --agent codex --project-dir /path/to/project
+```
+
+文本和 JSON 输出都会分别汇总 Vault 可访问性、MCP 注册、受管理策略、Hook 与 Audit 配置。SQLite 健康和宿主 Elicitation 能力只有在首次 MCP 会话建立后才能验证，因此 setup 会明确标为 deferred，而不会伪造成功。
+
 可选的运维参数包括 `--deep-reconcile-seconds`（默认 1800，`0` 禁用周期深扫）、`--verification-review-days`（默认 180）和 `--sqlite-journal-mode wal|delete`（默认 `wal`；网络文件系统可显式选择 `delete`，但这不会提供跨机器锁）。
 
 重复执行 setup 是幂等的，只会更新目标项目中 KeepM 管理的配置块。`~/.config/keepm/config.toml` 只保存 KeepM 自身的本机 Vault 配置，不会在所有项目中全局启用 Agent。KeepM 不要求安装或运行 Obsidian；在 WSL 中直接使用 `/mnt/c/...` 形式的 Windows 挂载路径即可。
@@ -133,6 +153,38 @@ uvx keepm gc --confirm --token <gc-token>
 
 确认后的 GC 是不可恢复删除；trash 内容、checksum、候选集合或 token 时效发生变化时会拒绝执行并要求重新预览。
 
+## JIT 两阶段读取与可复现卡片契约
+
+上下文压缩丢细节的真正原因往往不是“没存”，而是“存得太粗”与“召回靠语义联想”。KeepM 把两个问题分开解决。
+
+**写入侧：确定性契约。** `decision`、`constraint`、`fix` 必须包含固定英文段落 `## Decision and constraints` 与 `## Reproducible parameters`（无论正文是中文还是英文），`fix` 还必须在 frontmatter 携带至少一个仓库相对 `sources` 指针：
+
+```yaml
+sources:
+  - deploy/docker-compose.yml#service:db
+  - src/config/database.py#symbol:get_engine
+```
+
+指针路径是机器真源，`#` 后的锚点只是给人看的提示，KeepM 绝不做 AST 解析，避免重构造成误报。契约只在写入时生效（create / propose / inbox_update / promote，以及改变正文或 kind 的 update）；契约之前保存的卡片仍然可解析、可检索，只刷新 `verified_at` 或 `tags` 也不会被拦。写入层另外会拦住带密码的连接串与显式密码赋值，但会放行 `***`、`${PGPASSWORD}`、`<password>` 这类脉敏写法。
+
+**读取侧：两阶段 JIT。**
+
+```text
+阶段 1：骶架探测
+  memory_context(query)          ─► 相关记忆、handoff、Inbox 计数
+  memory_catalog()               ─► 有界槽位句柄（name / kind / scope / 30 字用途 / is_stale）
+
+阶段 2：目标点读
+  memory_catalog(source_path="deploy/docker-compose.yml")
+                                 ─► 路径反查到 postgres-wsl2-io-config
+  memory_read(identifier="postgres-wsl2-io-config")
+                                 ─► 完整参数、真源指针、版本凭证
+```
+
+目录只返回句柄，不返回事实：排序固定为 `pinned → kind 优先级 → verified_at → name_key`，默认 `limit=20`、用途行截断到 30 字符，并带 `notice` 明确禁止从槽位名推测参数。同名的 global 槽位被 project 槽位遮蔽后不会重复出现，`is_stale` 直接复用 doctor 的验证判据（只对 active 的 `constraint` / `fix` / `workflow` 生效）。
+
+路径反查把“该读哪张卡”从语义联想变成确定性路由：准备修改 `deploy/docker-compose.yml` 时，相关 `fix` 卡片会直接被命中，而不依赖 Agent 猜到名字。目录支持文件与目录前缀，并对 `./`、反斜杠和大小写做可移植归一化。
+
 ## Agent 工作流与低噪对话式审核
 
 ```text
@@ -150,7 +202,7 @@ uvx keepm gc --confirm --token <gc-token>
 
 写操作会立即刷新对应索引，不需要在任务开始或结束时常规调用 `memory_sync`。Hook 只负责提醒当前 Agent 做有边界的恢复或检查点整理；KeepM 不读取原始对话，也不会调用模型。
 
-KeepM 使用受控对话完成 Inbox 审核，不依赖 GUI 或 Obsidian 插件。Agent 只有在用户主动要求、当前对话刚产生新 Proposal，或 Inbox 出现过期/数量阈值信号时，才会在主任务回答末尾提醒；每次最多呈报 3 条。
+KeepM 使用受控对话完成 Inbox 审核，不强制依赖 GUI 或 Obsidian 插件。Agent 只有在用户主动要求、当前对话刚产生新 Proposal，或 Inbox 出现过期/数量阈值信号时，才会在主任务回答末尾提醒；每次最多呈报 3 条。宿主支持 MCP Elicitation 时，实际提升前还会显示一次与 Proposal checksum 和目标方案绑定的原生最终确认。
 
 > **Agent 对话式审核示例**
 >
@@ -172,7 +224,7 @@ KeepM 使用受控对话完成 Inbox 审核，不依赖 GUI 或 Obsidian 插件
 | 分组 | 工具 | 用途 |
 | --- | --- | --- |
 | 上下文 | `memory_status`、`memory_context` | 运行状态、有长度边界的任务上下文和仅计数的 Inbox 信号 |
-| 检索 | `memory_search`、`memory_read`、`memory_links` | active 记忆加权检索、权威读取、WikiLink 与反向链接 |
+| 检索 | `memory_catalog`、`memory_search`、`memory_read`、`memory_links` | 有界槽位目录与文件路径反查、active 记忆加权检索、权威读取、WikiLink 与反向链接 |
 | 正式记忆 | `memory_create`、`memory_update`、`memory_delete`、`memory_resolve_conflict` | 创建已确认记忆；保护更新、删除及两条 active 记忆的预览式冲突解决 |
 | Inbox | `memory_propose`、`memory_inbox_list`、`memory_inbox_read`、`memory_inbox_update`、`memory_inbox_promote`、`memory_inbox_reject`、`memory_inbox_prune` | 隔离、查看、修正、批准、拒绝、合并或安全清理候选 |
 | Handoff | `memory_handoff_create`、`memory_handoff_read`、`memory_handoff_update`、`memory_handoff_complete` | 保存、恢复、更新和归档未完成任务状态 |
@@ -186,8 +238,10 @@ KeepM 使用受控对话完成 Inbox 审核，不依赖 GUI 或 Obsidian 插件
 - **落盘边界：** 单文件写入会先 `fsync` 临时文件，`os.replace` 后再 `fsync` 父目录；Markdown 仍是唯一真源，Doctor 只报告损坏，不猜测性重写。
 - **单活 Writer：** 一个 Vault 同一时间只能由一台机器写入。`memory_status` 会尽力识别 NFS/SMB 等网络文件系统并给出提示；SQLite journal mode 可显式配置为 `wal` 或 `delete`，但两者都不能替代跨主机协调。
 - **核验提示：** `memory_doctor` 只对 active 的 `constraint`、`fix`、`workflow` 给出 `verification_missing` / `verification_overdue` info；`decision` 和 `preference` 默认免检，系统绝不因此自动归档或改写记忆。
+- **指针校验：** 只有本机配置记录了 `[projects.<id>].root`，且该目录仍然解析回相同 project id 时，doctor 才会检查 `sources` 指针是否存在；否则返回 `source_pointer_check_skipped`。缺失只会产生 info 级 `source_pointer_missing`，绝不把报告标为 failed——因为同一个 Vault 会被多台机器共用。项目根目录只保存在本机 `~/.config/keepm/config.toml`，绝不写入 Vault。
 - **结构化报告：** `memory_doctor(report_format=json|markdown)` 和 `keepm doctor` 复用同一份无正文健康报告；CLI 可安全写入本地 JSON/Markdown，不引入 HTML 渲染。
-- **Host 确认适配：** `memory_status.host_confirmation` 根据 MCP 客户端能力报告 `elicitation` 或 `proposal-protocol`。不支持、取消或调用错误都 fail closed；当前 Proposal P1/P2 明确授权协议始终保留，不会把能力缺失当成批准。
+- **Host 确认适配：** `memory_status.host_confirmation` 根据 MCP 客户端能力报告 `elicitation` 或 `proposal-protocol`。不支持 Elicitation 时沿用已经明确完成的 Proposal P1/P2 授权；宿主声明支持后，只有原生确认明确接受才会继续，拒绝、取消或调用错误都会保持 Proposal pending，不写入正式记忆。
+- **无正文审计溯源：** Proposal 提升审计记录来源 Proposal、MCP 客户端、来源引用、目标记忆、KeepM 策略版本与确认模式，但不会记录 Proposal 正文、描述或 Prompt。
 
 ## 设计哲学与非目标
 
@@ -197,7 +251,7 @@ KeepM 使用受控对话完成 Inbox 审核，不依赖 GUI 或 Obsidian 插件
 - **人类可编辑真源：** 手工修改的 Markdown 会增量对账；无效文件会被诊断和隔离，不会被猜测性改写。
 - **不内置 LLM、Embedding 或向量数据库：** 语义提炼由当前 Agent 完成，KeepM 只执行确定性规则。
 - **不使用伪置信度、静默衰减或自动提升：** 用明确生命周期状态和 `verified_at` 管理记忆，审核阈值绝不构成写入授权。
-- **不要求 Obsidian 插件或审核 UI：** Obsidian 只是可选编辑器，受控 Agent 对话才是标准审核入口。
+- **不强制 Obsidian 插件或审核 UI：** 受控 Agent 对话是通用审核入口；支持 MCP Elicitation 的宿主可额外提供原生最终确认。
 - **不归档原始对话：** 临时进度进入有边界的 handoff，长期记忆只保留提炼后的可复用结论。
 
 ## License

{keepm-3.2.0 → keepm-3.4.0}/README.md

@@ -4,7 +4,7 @@
 
 > 带准入控制、本地优先、无模型依赖的 AI 编码 Agent 长期记忆引擎。
 
-[![Version](https://img.shields.io/badge/version-3.2.0-6f42c1.svg)](https://pypi.org/project/keepm/)
+[![Version](https://img.shields.io/badge/version-3.4.0-6f42c1.svg)](https://pypi.org/project/keepm/)
 [![Python](https://img.shields.io/badge/python-3.11%2B-3776ab.svg)](https://www.python.org/)
 [![MCP](https://img.shields.io/badge/MCP-supported-2ea44f.svg)](https://modelcontextprotocol.io/)
 [![License](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/LeoKon3/KeepM/blob/main/LICENSE)
@@ -78,16 +78,36 @@ uvx keepm setup
 `uvx` 会在隔离环境中运行 KeepM，无需永久安装。交互向导会完成最少且完整的接入：
 
 - 指定共用的 Markdown 存储根目录与默认记忆语言（`zh` / `en`）；
-- 选择 Codex 或 Claude Code；
+- 选择 Codex、Claude Code 或 pi；
 - 指定要接入的项目目录，默认使用当前工作目录；
 - 仅在该项目中注册 `keepm` stdio MCP Server、安装受管理的 Agent 记忆策略，并默认配置 `SessionStart` / `Stop` Hook。
 
+三个宓主的接入位置：
+
+| 宓主 | MCP 注册 | Agent 入口 | 生命周期 Hook |
+| --- | --- | --- | --- |
+| Codex | `.codex/config.toml` | `AGENTS.md` | `.codex/hooks.json` |
+| Claude Code | `.mcp.json` | `CLAUDE.md` | `.claude/settings.json` |
+| pi | `.mcp.json` | `AGENTS.md` | 无宓主 Hook 文件，报 `not-applicable` |
+
+pi 与 Claude Code 共用同一份项目 `.mcp.json`，且两边都把 `command` 条目视为 stdio，因此一次注册对两个宓主同时生效，不会互相覆盖。写入采用 JSON 合并：其他 MCP Server 和未知顶层字段全部保留；文件格式非法、是符号链接或不是普通文件时直接报错，绝不整体重写。pi 没有 Claude 那种宓主 Hook 配置文件，setup 会在文本和 JSON 中把 `lifecycle_hooks` 明确报为 `not-applicable`，而不伪造成功；相同的会话与 checkpoint 指引由受管理的 `AGENTS.md` 策略承担。
+
 自动化配置：
 
 ```bash
 uvx keepm setup --yes --root /path/to/notes --agent codex --project-dir /path/to/project
 ```
 
+`--agent` 可选 `codex`、`claude` 或 `pi`。
+
+CI、安装脚本或 Agent 还可以请求机器可读的验收摘要：
+
+```bash
+uvx keepm setup --yes --format json --root /path/to/notes --agent codex --project-dir /path/to/project
+```
+
+文本和 JSON 输出都会分别汇总 Vault 可访问性、MCP 注册、受管理策略、Hook 与 Audit 配置。SQLite 健康和宿主 Elicitation 能力只有在首次 MCP 会话建立后才能验证，因此 setup 会明确标为 deferred，而不会伪造成功。
+
 可选的运维参数包括 `--deep-reconcile-seconds`（默认 1800，`0` 禁用周期深扫）、`--verification-review-days`（默认 180）和 `--sqlite-journal-mode wal|delete`（默认 `wal`；网络文件系统可显式选择 `delete`，但这不会提供跨机器锁）。
 
 重复执行 setup 是幂等的，只会更新目标项目中 KeepM 管理的配置块。`~/.config/keepm/config.toml` 只保存 KeepM 自身的本机 Vault 配置，不会在所有项目中全局启用 Agent。KeepM 不要求安装或运行 Obsidian；在 WSL 中直接使用 `/mnt/c/...` 形式的 Windows 挂载路径即可。
@@ -113,6 +133,38 @@ uvx keepm gc --confirm --token <gc-token>
 
 确认后的 GC 是不可恢复删除；trash 内容、checksum、候选集合或 token 时效发生变化时会拒绝执行并要求重新预览。
 
+## JIT 两阶段读取与可复现卡片契约
+
+上下文压缩丢细节的真正原因往往不是“没存”，而是“存得太粗”与“召回靠语义联想”。KeepM 把两个问题分开解决。
+
+**写入侧：确定性契约。** `decision`、`constraint`、`fix` 必须包含固定英文段落 `## Decision and constraints` 与 `## Reproducible parameters`（无论正文是中文还是英文），`fix` 还必须在 frontmatter 携带至少一个仓库相对 `sources` 指针：
+
+```yaml
+sources:
+  - deploy/docker-compose.yml#service:db
+  - src/config/database.py#symbol:get_engine
+```
+
+指针路径是机器真源，`#` 后的锚点只是给人看的提示，KeepM 绝不做 AST 解析，避免重构造成误报。契约只在写入时生效（create / propose / inbox_update / promote，以及改变正文或 kind 的 update）；契约之前保存的卡片仍然可解析、可检索，只刷新 `verified_at` 或 `tags` 也不会被拦。写入层另外会拦住带密码的连接串与显式密码赋值，但会放行 `***`、`${PGPASSWORD}`、`<password>` 这类脉敏写法。
+
+**读取侧：两阶段 JIT。**
+
+```text
+阶段 1：骶架探测
+  memory_context(query)          ─► 相关记忆、handoff、Inbox 计数
+  memory_catalog()               ─► 有界槽位句柄（name / kind / scope / 30 字用途 / is_stale）
+
+阶段 2：目标点读
+  memory_catalog(source_path="deploy/docker-compose.yml")
+                                 ─► 路径反查到 postgres-wsl2-io-config
+  memory_read(identifier="postgres-wsl2-io-config")
+                                 ─► 完整参数、真源指针、版本凭证
+```
+
+目录只返回句柄，不返回事实：排序固定为 `pinned → kind 优先级 → verified_at → name_key`，默认 `limit=20`、用途行截断到 30 字符，并带 `notice` 明确禁止从槽位名推测参数。同名的 global 槽位被 project 槽位遮蔽后不会重复出现，`is_stale` 直接复用 doctor 的验证判据（只对 active 的 `constraint` / `fix` / `workflow` 生效）。
+
+路径反查把“该读哪张卡”从语义联想变成确定性路由：准备修改 `deploy/docker-compose.yml` 时，相关 `fix` 卡片会直接被命中，而不依赖 Agent 猜到名字。目录支持文件与目录前缀，并对 `./`、反斜杠和大小写做可移植归一化。
+
 ## Agent 工作流与低噪对话式审核
 
 ```text
@@ -130,7 +182,7 @@ uvx keepm gc --confirm --token <gc-token>
 
 写操作会立即刷新对应索引，不需要在任务开始或结束时常规调用 `memory_sync`。Hook 只负责提醒当前 Agent 做有边界的恢复或检查点整理；KeepM 不读取原始对话，也不会调用模型。
 
-KeepM 使用受控对话完成 Inbox 审核，不依赖 GUI 或 Obsidian 插件。Agent 只有在用户主动要求、当前对话刚产生新 Proposal，或 Inbox 出现过期/数量阈值信号时，才会在主任务回答末尾提醒；每次最多呈报 3 条。
+KeepM 使用受控对话完成 Inbox 审核，不强制依赖 GUI 或 Obsidian 插件。Agent 只有在用户主动要求、当前对话刚产生新 Proposal，或 Inbox 出现过期/数量阈值信号时，才会在主任务回答末尾提醒；每次最多呈报 3 条。宿主支持 MCP Elicitation 时，实际提升前还会显示一次与 Proposal checksum 和目标方案绑定的原生最终确认。
 
 > **Agent 对话式审核示例**
 >
@@ -152,7 +204,7 @@ KeepM 使用受控对话完成 Inbox 审核，不依赖 GUI 或 Obsidian 插件
 | 分组 | 工具 | 用途 |
 | --- | --- | --- |
 | 上下文 | `memory_status`、`memory_context` | 运行状态、有长度边界的任务上下文和仅计数的 Inbox 信号 |
-| 检索 | `memory_search`、`memory_read`、`memory_links` | active 记忆加权检索、权威读取、WikiLink 与反向链接 |
+| 检索 | `memory_catalog`、`memory_search`、`memory_read`、`memory_links` | 有界槽位目录与文件路径反查、active 记忆加权检索、权威读取、WikiLink 与反向链接 |
 | 正式记忆 | `memory_create`、`memory_update`、`memory_delete`、`memory_resolve_conflict` | 创建已确认记忆；保护更新、删除及两条 active 记忆的预览式冲突解决 |
 | Inbox | `memory_propose`、`memory_inbox_list`、`memory_inbox_read`、`memory_inbox_update`、`memory_inbox_promote`、`memory_inbox_reject`、`memory_inbox_prune` | 隔离、查看、修正、批准、拒绝、合并或安全清理候选 |
 | Handoff | `memory_handoff_create`、`memory_handoff_read`、`memory_handoff_update`、`memory_handoff_complete` | 保存、恢复、更新和归档未完成任务状态 |
@@ -166,8 +218,10 @@ KeepM 使用受控对话完成 Inbox 审核，不依赖 GUI 或 Obsidian 插件
 - **落盘边界：** 单文件写入会先 `fsync` 临时文件，`os.replace` 后再 `fsync` 父目录；Markdown 仍是唯一真源，Doctor 只报告损坏，不猜测性重写。
 - **单活 Writer：** 一个 Vault 同一时间只能由一台机器写入。`memory_status` 会尽力识别 NFS/SMB 等网络文件系统并给出提示；SQLite journal mode 可显式配置为 `wal` 或 `delete`，但两者都不能替代跨主机协调。
 - **核验提示：** `memory_doctor` 只对 active 的 `constraint`、`fix`、`workflow` 给出 `verification_missing` / `verification_overdue` info；`decision` 和 `preference` 默认免检，系统绝不因此自动归档或改写记忆。
+- **指针校验：** 只有本机配置记录了 `[projects.<id>].root`，且该目录仍然解析回相同 project id 时，doctor 才会检查 `sources` 指针是否存在；否则返回 `source_pointer_check_skipped`。缺失只会产生 info 级 `source_pointer_missing`，绝不把报告标为 failed——因为同一个 Vault 会被多台机器共用。项目根目录只保存在本机 `~/.config/keepm/config.toml`，绝不写入 Vault。
 - **结构化报告：** `memory_doctor(report_format=json|markdown)` 和 `keepm doctor` 复用同一份无正文健康报告；CLI 可安全写入本地 JSON/Markdown，不引入 HTML 渲染。
-- **Host 确认适配：** `memory_status.host_confirmation` 根据 MCP 客户端能力报告 `elicitation` 或 `proposal-protocol`。不支持、取消或调用错误都 fail closed；当前 Proposal P1/P2 明确授权协议始终保留，不会把能力缺失当成批准。
+- **Host 确认适配：** `memory_status.host_confirmation` 根据 MCP 客户端能力报告 `elicitation` 或 `proposal-protocol`。不支持 Elicitation 时沿用已经明确完成的 Proposal P1/P2 授权；宿主声明支持后，只有原生确认明确接受才会继续，拒绝、取消或调用错误都会保持 Proposal pending，不写入正式记忆。
+- **无正文审计溯源：** Proposal 提升审计记录来源 Proposal、MCP 客户端、来源引用、目标记忆、KeepM 策略版本与确认模式，但不会记录 Proposal 正文、描述或 Prompt。
 
 ## 设计哲学与非目标
 
@@ -177,7 +231,7 @@ KeepM 使用受控对话完成 Inbox 审核，不依赖 GUI 或 Obsidian 插件
 - **人类可编辑真源：** 手工修改的 Markdown 会增量对账；无效文件会被诊断和隔离，不会被猜测性改写。
 - **不内置 LLM、Embedding 或向量数据库：** 语义提炼由当前 Agent 完成，KeepM 只执行确定性规则。
 - **不使用伪置信度、静默衰减或自动提升：** 用明确生命周期状态和 `verified_at` 管理记忆，审核阈值绝不构成写入授权。
-- **不要求 Obsidian 插件或审核 UI：** Obsidian 只是可选编辑器，受控 Agent 对话才是标准审核入口。
+- **不强制 Obsidian 插件或审核 UI：** 受控 Agent 对话是通用审核入口；支持 MCP Elicitation 的宿主可额外提供原生最终确认。
 - **不归档原始对话：** 临时进度进入有边界的 handoff，长期记忆只保留提炼后的可复用结论。
 
 ## License

{keepm-3.2.0 → keepm-3.4.0}/README_EN.md

@@ -4,7 +4,7 @@
 
 > An admission-controlled, local-first, model-free durable memory engine for AI coding agents.
 
-[![Version](https://img.shields.io/badge/version-3.2.0-6f42c1.svg)](https://pypi.org/project/keepm/)
+[![Version](https://img.shields.io/badge/version-3.4.0-6f42c1.svg)](https://pypi.org/project/keepm/)
 [![Python](https://img.shields.io/badge/python-3.11%2B-3776ab.svg)](https://www.python.org/)
 [![MCP](https://img.shields.io/badge/MCP-supported-2ea44f.svg)](https://modelcontextprotocol.io/)
 [![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
@@ -78,16 +78,36 @@ uvx keepm setup
 `uvx` runs KeepM in an isolated environment, so no permanent installation is required. The wizard completes the smallest full integration:
 
 - choose the shared Markdown root and default memory language (`zh` / `en`);
-- choose Codex or Claude Code;
+- choose Codex, Claude Code, or pi;
 - select the project directory to integrate, defaulting to the current working directory;
 - register the `keepm` stdio MCP Server, managed Agent memory policy, and default `SessionStart` / `Stop` Hooks only in that project.
 
+Where each host is integrated:
+
+| Host | MCP registration | Agent entry | Lifecycle Hooks |
+| --- | --- | --- | --- |
+| Codex | `.codex/config.toml` | `AGENTS.md` | `.codex/hooks.json` |
+| Claude Code | `.mcp.json` | `CLAUDE.md` | `.claude/settings.json` |
+| pi | `.mcp.json` | `AGENTS.md` | no host Hook file; reported `not-applicable` |
+
+pi and Claude Code share the same project `.mcp.json`, and both treat a `command` entry as stdio, so one registration satisfies both hosts instead of overwriting each other. The write is a JSON merge: every other MCP server and unknown top-level key is preserved, and an invalid, symlinked, or non-regular file raises an error instead of being replaced wholesale. pi has no Claude-style host Hook file, so setup reports `lifecycle_hooks` as `not-applicable` in both text and JSON rather than faking success; the managed `AGENTS.md` policy carries the same session and checkpoint guidance.
+
 For automation:
 
 ```bash
 uvx keepm setup --yes --root /path/to/notes --agent codex --project-dir /path/to/project
 ```
 
+`--agent` accepts `codex`, `claude`, or `pi`.
+
+CI, installer scripts, and Agents can request a machine-readable acceptance summary:
+
+```bash
+uvx keepm setup --yes --format json --root /path/to/notes --agent codex --project-dir /path/to/project
+```
+
+Both text and JSON output summarize Vault accessibility, MCP registration, managed policy, Hooks, and Audit configuration independently. SQLite health and host Elicitation capability can only be verified after the first MCP session starts, so setup reports them as deferred instead of claiming success.
+
 Optional operations settings include `--deep-reconcile-seconds` (default 1800; `0` disables periodic deep scans), `--verification-review-days` (default 180), and `--sqlite-journal-mode wal|delete` (default `wal`; network filesystems may explicitly select `delete`, but it does not provide cross-machine locking).
 
 Setup is idempotent and updates only KeepM-managed configuration blocks in the target project. `~/.config/keepm/config.toml` stores KeepM's local Vault configuration only; it does not enable the Agent globally in every project. Obsidian does not need to be installed or running. From WSL, use a mounted Windows path such as `/mnt/c/...` directly.
@@ -113,6 +133,38 @@ uvx keepm gc --confirm --token <gc-token>
 
 Confirmed GC is irreversible. Any trash-content, checksum, candidate-set, or token-expiry change rejects execution and requires a new preview.
 
+## Just-in-time reads and the reproducible card contract
+
+Detail usually disappears from a long session for two reasons: cards were written too coarsely, and recall depended on the model associating a topic with a slot name. KeepM addresses them separately.
+
+**Write side: a deterministic contract.** `decision`, `constraint`, and `fix` must contain the fixed English sections `## Decision and constraints` and `## Reproducible parameters` regardless of body language, and a `fix` must also carry at least one repository-relative `sources` pointer in frontmatter:
+
+```yaml
+sources:
+  - deploy/docker-compose.yml#service:db
+  - src/config/database.py#symbol:get_engine
+```
+
+The pointer path is the machine-readable truth, while the anchor after `#` is a human hint that KeepM never parses into an AST, so refactors cannot create false diagnostics. The contract applies only to writes (create, propose, inbox_update, promote, and an update that changes the body or kind). Cards stored before the contract keep parsing and stay retrievable, and refreshing only `verified_at` or `tags` is never blocked. The write layer additionally rejects credential-bearing connection strings and explicit password assignments while allowing masked forms such as `***`, `${PGPASSWORD}`, or `<password>`.
+
+**Read side: two-phase JIT.**
+
+```text
+phase 1: skeleton
+  memory_context(query)          ─► relevant memories, handoff, Inbox counts
+  memory_catalog()               ─► bounded slot handles (name / kind / scope / 30-char purpose / is_stale)
+
+phase 2: targeted read
+  memory_catalog(source_path="deploy/docker-compose.yml")
+                                 ─► routes the path to postgres-wsl2-io-config
+  memory_read(identifier="postgres-wsl2-io-config")
+                                 ─► exact parameters, pointers, version credentials
+```
+
+The catalog returns handles, never facts: ordering is fixed at `pinned → kind priority → verified_at → name_key`, the default `limit` is 20, the purpose line truncates at 30 characters, and a `notice` states that parameters must never be inferred from a slot name. A global slot shadowed by a same-named project slot never appears twice, and `is_stale` reuses the doctor verification predicate, so only active `constraint`, `fix`, and `workflow` slots can be marked.
+
+The reverse lookup turns “which card should I read” from semantic association into deterministic routing: editing `deploy/docker-compose.yml` surfaces the `fix` card that documents it without guessing its name. Queries accept a file or a directory prefix and normalize `./`, backslashes, and case portably.
+
 ## Agent workflow and low-noise review
 
 ```text
@@ -130,7 +182,7 @@ new retained information
 
 Writes immediately refresh the affected index rows, so normal task starts and finishes do not call `memory_sync`. Hooks only remind the current Agent to perform a bounded recovery or checkpoint pass; KeepM never reads raw transcripts and never invokes a model.
 
-KeepM reviews Inbox candidates through controlled conversation, with no GUI or Obsidian plugin dependency. The Agent may mention review only when the user asks, the current conversation has just created a Proposal, or Inbox age/count thresholds signal a backlog. It appears after the main answer and presents at most three candidates.
+KeepM reviews Inbox candidates through controlled conversation, with no mandatory GUI or Obsidian plugin dependency. The Agent may mention review only when the user asks, the current conversation has just created a Proposal, or Inbox age/count thresholds signal a backlog. It appears after the main answer and presents at most three candidates. When the host supports MCP Elicitation, promotion also shows a native final confirmation bound to the Proposal checksum and exact destination plan.
 
 > **Conversational review example**
 >
@@ -152,7 +204,7 @@ After the conflict is confirmed and the user explicitly authorizes the change, t
 | Group | Tools | Purpose |
 | --- | --- | --- |
 | Context | `memory_status`, `memory_context` | Runtime state and bounded task context with count-only Inbox signals |
-| Retrieval | `memory_search`, `memory_read`, `memory_links` | Weighted active-memory search, authoritative reads, WikiLinks, and backlinks |
+| Retrieval | `memory_catalog`, `memory_search`, `memory_read`, `memory_links` | Bounded slot catalog and repository-path reverse lookup, weighted active-memory search, authoritative reads, WikiLinks, and backlinks |
 | Formal memory | `memory_create`, `memory_update`, `memory_delete`, `memory_resolve_conflict` | Create confirmed memory; protect updates, deletes, and previewed conflict resolution of two active notes |
 | Inbox | `memory_propose`, `memory_inbox_list`, `memory_inbox_read`, `memory_inbox_update`, `memory_inbox_promote`, `memory_inbox_reject`, `memory_inbox_prune` | Isolate, inspect, edit, approve, reject, merge, or safely prune candidates |
 | Handoff | `memory_handoff_create`, `memory_handoff_read`, `memory_handoff_update`, `memory_handoff_complete` | Save, resume, update, and archive unfinished task state |
@@ -166,8 +218,10 @@ Mutating an existing object requires a complete current read plus one-time versi
 - **Durability boundary:** a single-file write fsyncs the temporary file, performs `os.replace`, and then fsyncs the parent directory. Markdown remains the only source of truth; Doctor reports damage without guessing a rewrite.
 - **Single-active Writer:** only one machine may write a Vault at a time. `memory_status` makes a best-effort check for network filesystems such as NFS/SMB. SQLite journal mode can be configured as `wal` or `delete`, but neither substitutes for cross-host coordination.
 - **Verification reminders:** `memory_doctor` emits `verification_missing` / `verification_overdue` info only for active `constraint`, `fix`, and `workflow` memories. `decision` and `preference` are exempt by default, and KeepM never archives or rewrites a memory because of age.
+- **Pointer verification:** doctor checks `sources` pointers only when the local config records `[projects.<id>].root` and that checkout still resolves to the same project id; otherwise it reports `source_pointer_check_skipped`. A missing file produces the info-level `source_pointer_missing` and never marks a report failed, because one Vault is shared across machines. Project roots live only in the local `~/.config/keepm/config.toml` and are never written into the Vault.
 - **Structured reports:** `memory_doctor(report_format=json|markdown)` and `keepm doctor` share one body-free report model. The CLI can write local JSON/Markdown without adding HTML rendering.
-- **Host confirmation adapter:** `memory_status.host_confirmation` reports `elicitation` or `proposal-protocol` from MCP client capabilities. Unsupported, cancelled, or failed elicitation remains fail-closed; the explicit Proposal P1/P2 protocol always remains available and missing capability is never approval.
+- **Host confirmation adapter:** `memory_status.host_confirmation` reports `elicitation` or `proposal-protocol` from MCP client capabilities. Unsupported hosts keep using the already-completed explicit Proposal P1/P2 authorization. Once a host advertises Elicitation, only explicit native acceptance continues; decline, cancel, or an invocation error leaves the Proposal pending and writes no formal memory.
+- **Body-free audit provenance:** Proposal promotion records the source Proposal, MCP client, source reference, target memory, KeepM policy version, and confirmation mode, but never the Proposal body, description, or Prompt.
 
 ## Design principles and non-goals
 
@@ -177,7 +231,7 @@ Mutating an existing object requires a complete current read plus one-time versi
 - **Human-editable truth:** manual Markdown edits are reconciled incrementally; invalid files are diagnosed and isolated instead of being guessed into shape.
 - **No embedded LLM, embeddings, or vector database:** the current Agent performs semantic distillation; KeepM executes deterministic rules only.
 - **No fake confidence, silent decay, or automatic promotion:** explicit lifecycle states and `verified_at` govern memory; review thresholds never authorize a write.
-- **No required Obsidian plugin or review UI:** Obsidian is an optional editor; controlled Agent conversation is the standard review surface.
+- **No mandatory Obsidian plugin or review UI:** controlled Agent conversation is the universal review surface; hosts with MCP Elicitation may add native final confirmation.
 - **No raw transcript archive:** temporary progress belongs in a bounded handoff; durable memory contains distilled, reusable conclusions only.
 
 ## License

{keepm-3.2.0 → keepm-3.4.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "keepm"
-version = "3.2.0"
+version = "3.4.0"
 description = "Admission-controlled local Markdown memory MCP for AI coding agents"
 readme = "README.md"
 requires-python = ">=3.11"

keepm-3.4.0/src/keepm/__init__.py

@@ -0,0 +1 @@
+__version__ = "3.4.0"

{keepm-3.2.0 → keepm-3.4.0}/src/keepm/audit.py

@@ -25,6 +25,13 @@ SAFE_FIELDS = frozenset(
         "before_checksum",
         "after_checksum",
         "code",
+        "origin",
+        "source_id",
+        "source_client",
+        "source_ref",
+        "target_id",
+        "policy_version",
+        "confirmation_mode",
     }
 )
 
@@ -48,6 +55,13 @@ class AuditLogger:
         before_checksum: str | None,
         after_checksum: str | None,
         code: str | None,
+        origin: str | None = None,
+        source_id: str | None = None,
+        source_client: str | None = None,
+        source_ref: str | None = None,
+        target_id: str | None = None,
+        policy_version: str | None = None,
+        confirmation_mode: str | None = None,
     ) -> None:
         if not self.enabled:
             return
@@ -62,6 +76,13 @@ class AuditLogger:
             "before_checksum": before_checksum,
             "after_checksum": after_checksum,
             "code": code,
+            "origin": origin,
+            "source_id": source_id,
+            "source_client": source_client,
+            "source_ref": source_ref,
+            "target_id": target_id,
+            "policy_version": policy_version,
+            "confirmation_mode": confirmation_mode,
         }
         try:
             payload = (json.dumps(event, ensure_ascii=False, separators=(",", ":")) + "\n").encode(

{keepm-3.2.0 → keepm-3.4.0}/src/keepm/config.py

@@ -4,9 +4,9 @@ import json
 import os
 import hashlib
 import tomllib
-from dataclasses import dataclass
+from dataclasses import dataclass, field
 from pathlib import Path
-from typing import Literal, cast
+from typing import Literal, Mapping, cast
 
 
 MemoryLanguage = Literal["zh", "en"]
@@ -30,6 +30,26 @@ def vault_id(config: "KeepMConfig") -> str:
     return hashlib.sha256(identity.encode("utf-8")).hexdigest()[:24]
 
 
+def _parse_project_roots(value: object) -> dict[str, Path]:
+    """Parse the optional machine-local ``[projects.<id>]`` mapping."""
+
+    if value is None:
+        return {}
+    if not isinstance(value, Mapping):
+        raise ValueError("projects must be a table of project ids")
+    roots: dict[str, Path] = {}
+    for project_id, entry in value.items():
+        if not isinstance(entry, Mapping):
+            raise ValueError(f"projects.{project_id} must be a table")
+        root = entry.get("root")
+        if root is None:
+            continue
+        if not isinstance(root, str) or not root.strip():
+            raise ValueError(f"projects.{project_id}.root must be a path string")
+        roots[str(project_id)] = Path(root)
+    return roots
+
+
 @dataclass(frozen=True, slots=True)
 class KeepMConfig:
     vault_path: Path
@@ -42,6 +62,7 @@ class KeepMConfig:
     deep_reconcile_interval_seconds: int = 1_800
     verification_review_after_days: int = 180
     sqlite_journal_mode: SQLiteJournalMode = "wal"
+    project_roots: Mapping[str, Path] = field(default_factory=dict)
 
     def __post_init__(self) -> None:
         memory_path = Path(self.memory_dir)
@@ -69,6 +90,17 @@ class KeepMConfig:
             raise ValueError("verification_review_after_days must be positive")
         if self.sqlite_journal_mode not in ("wal", "delete"):
             raise ValueError("sqlite_journal_mode must be wal or delete")
+        if not isinstance(self.project_roots, Mapping):
+            raise ValueError("project_roots must be a mapping of project id to path")
+        normalized_roots: dict[str, Path] = {}
+        for project_id, root in self.project_roots.items():
+            if not isinstance(project_id, str) or not project_id.strip():
+                raise ValueError("project_roots keys must be non-empty project ids")
+            candidate = Path(root).expanduser()
+            if not candidate.is_absolute():
+                raise ValueError("project_roots values must be absolute local paths")
+            normalized_roots[project_id.strip()] = candidate.resolve()
+        object.__setattr__(self, "project_roots", normalized_roots)
         object.__setattr__(self, "vault_path", self.vault_path.expanduser().resolve())
 
     @property
@@ -165,6 +197,7 @@ class ConfigStore:
             sqlite_journal_mode=cast(
                 SQLiteJournalMode, str(data.get("sqlite_journal_mode", "wal"))
             ),
+            project_roots=_parse_project_roots(data.get("projects")),
         )
 
     def load_optional(self) -> KeepMConfig | None:
@@ -198,6 +231,14 @@ class ConfigStore:
             f"verification_review_after_days = {config.verification_review_after_days}\n"
             f"sqlite_journal_mode = {json.dumps(config.sqlite_journal_mode)}\n"
         )
+        # Project roots stay machine-local: they map a project id to this host's
+        # checkout so `keepm doctor` can verify source pointers without ever
+        # writing host paths into the shared Vault.
+        for project_id in sorted(config.project_roots):
+            content += (
+                f"\n[projects.{json.dumps(project_id)}]\n"
+                f"root = {json.dumps(str(config.project_roots[project_id]))}\n"
+            )
         temporary = self.path.with_suffix(".tmp")
         temporary.write_text(content, encoding="utf-8", newline="\n")
         os.replace(temporary, self.path)