keepm 3.1.0__tar.gz → 3.2.0__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: keepm
-Version: 3.1.0
+Version: 3.2.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.1.0-6f42c1.svg)](https://pypi.org/project/keepm/)
+[![Version](https://img.shields.io/badge/version-3.2.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)
@@ -108,8 +108,31 @@ uvx keepm setup
 uvx keepm setup --yes --root /path/to/notes --agent codex --project-dir /path/to/project
 ```
 
+可选的运维参数包括 `--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 挂载路径即可。
 
+## 极简维护命令
+
+健康报告复用 `memory_doctor` 的确定性诊断结果，只导出状态和 finding 元数据，不包含记忆正文、Proposal 内容或任何 repair/update token：
+
+```bash
+uvx keepm doctor --format json
+uvx keepm doctor --format markdown --output keepm-health.md
+```
+
+Safe GC 只处理 `Memory/.trash/` 中具有可信软删除时间、且超过指定期限的普通文件。默认命令只生成预览和短时一次性计划；repair 备份、符号链接、无可信删除时间的文件以及正常的 active/archived/superseded 记忆均不会被删除：
+
+```bash
+# 仅预览，不删除
+uvx keepm gc --older-than-days 30
+
+# 使用预览返回的 token 执行完全相同且未变化的计划
+uvx keepm gc --confirm --token <gc-token>
+```
+
+确认后的 GC 是不可恢复删除；trash 内容、checksum、候选集合或 token 时效发生变化时会拒绝执行并要求重新预览。
+
 ## Agent 工作流与低噪对话式审核
 
 ```text
@@ -133,16 +156,16 @@ KeepM 使用受控对话完成 Inbox 审核，不依赖 GUI 或 Obsidian 插件
 >
 > 顺便提醒：检测到 2 条待审核候选记忆：
 >
-> 1. **［项目偏好］** 优先使用 pnpm 而非 npm（建议：**批准**）
-> 2. **［架构决策］** 放弃 Redis，改用 SQLite（建议：**批准**）
+> - **Proposal P1［项目偏好］** 优先使用 pnpm 而非 npm（建议：**批准**）
+> - **Proposal P2［架构决策］** 放弃 Redis，改用 SQLite（建议：**批准**）
 >
-> 可以回复“全部批准”“批准 1、拒绝 2”或“稍后”。
+> 可以回复“批准 Proposal P1、拒绝 Proposal P2”或“稍后”。
 
-主任务永远优先。用户回复“稍后”或忽略提醒后，本次会话不再重复打扰；沉默不会批准、拒绝、修改或删除任何内容。
+主任务永远优先，Proposal 使用独立于 `Step 1` 等主任务步骤的编号。“行”“好的”“按你说的办”“按建议处理”等泛化赞同只授权主任务，绝不授权 Inbox 变更；多条候选时用户必须明确引用 `Proposal P1` 等标签。只有最近明确呈报了一条 Proposal 时，“批准记忆提案”才可授权该唯一候选。用户回复“稍后”或忽略提醒后，本次会话不再重复打扰；沉默不会批准、拒绝、修改或删除任何内容。
 
 正式记忆使用“槽位命名”：`project-package-manager` 表示稳定主题，`pnpm` 只是该槽位当前的结论。`memory_context` / `memory_search` 在发现 active 名称、别名硬碰撞或同 kind 主题重叠时会返回有界的 `conflict_hints`；Agent 必须完整读取相关候选并核对项目真源，不能只信第一条。
 
-确认冲突并得到用户明确授权后，Agent 先预览 `memory_resolve_conflict(dry_run=true)`，再用绑定同一方案的短时 token 执行。`supersede` 保留历史关系，`archive` 归档失去独立价值的节点，`delete` 只把错误节点移入可恢复回收站。KeepM 会同时校验两份 checksum/token、拒绝 `supersedes` 环，并通过文件事务日志与单次 SQLite 事务避免可见的半完成状态。
+确认冲突并得到用户明确授权后，Agent 先预览 `memory_resolve_conflict(dry_run=true)`，再用绑定同一方案的短时 token 执行。`supersede` 保留历史关系，`archive` 归档失去独立价值的节点，`delete` 只把错误节点移入可恢复回收站。KeepM 会同时校验两份 checksum/token、拒绝 `supersedes` 环，并通过可恢复的文件事务日志与单次 SQLite 事务保证崩溃一致；若进程在多文件替换中断，下次启动会继续提交或安全回滚。
 
 ## MCP 工具一览
 
@@ -150,13 +173,22 @@ KeepM 使用受控对话完成 Inbox 审核，不依赖 GUI 或 Obsidian 插件
 | --- | --- | --- |
 | 上下文 | `memory_status`、`memory_context` | 运行状态、有长度边界的任务上下文和仅计数的 Inbox 信号 |
 | 检索 | `memory_search`、`memory_read`、`memory_links` | active 记忆加权检索、权威读取、WikiLink 与反向链接 |
-| 正式记忆 | `memory_create`、`memory_update`、`memory_delete`、`memory_resolve_conflict` | 创建已确认记忆；保护更新、删除及两条 active 记忆的预览式原子冲销 |
+| 正式记忆 | `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` | 保存、恢复、更新和归档未完成任务状态 |
 | 运维 | `memory_doctor`、`memory_repair`、`memory_sync` | 诊断损坏、预览授权的确定性修复、对账或重建索引 |
 
 修改或删除已有对象前必须完整读取当前内容，并提供一次性版本凭证；如果 Markdown 在读写之间发生变化，KeepM 会拒绝过期操作，不会盲目覆盖。
 
+## 对账、文件系统与长期健康
+
+- **分层对账：** 高频快速路径使用 `mtime_ns + size`；服务启动、默认每 30 分钟一次的周期深扫，以及 `memory_doctor` 都会重新计算内容 SHA-256。`memory_status` 返回 `last_checksum_scan` 和 `deep_scan_due`。
+- **落盘边界：** 单文件写入会先 `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` 默认免检，系统绝不因此自动归档或改写记忆。
+- **结构化报告：** `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 明确授权协议始终保留，不会把能力缺失当成批准。
+
 ## 设计哲学与非目标
 
 - **本地优先且透明：** 不依赖云服务、HTTP 守护进程或私有存储格式。

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

@@ -4,7 +4,7 @@
 
 > 带准入控制、本地优先、无模型依赖的 AI 编码 Agent 长期记忆引擎。
 
-[![Version](https://img.shields.io/badge/version-3.1.0-6f42c1.svg)](https://pypi.org/project/keepm/)
+[![Version](https://img.shields.io/badge/version-3.2.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)
@@ -88,8 +88,31 @@ uvx keepm setup
 uvx keepm setup --yes --root /path/to/notes --agent codex --project-dir /path/to/project
 ```
 
+可选的运维参数包括 `--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 挂载路径即可。
 
+## 极简维护命令
+
+健康报告复用 `memory_doctor` 的确定性诊断结果，只导出状态和 finding 元数据，不包含记忆正文、Proposal 内容或任何 repair/update token：
+
+```bash
+uvx keepm doctor --format json
+uvx keepm doctor --format markdown --output keepm-health.md
+```
+
+Safe GC 只处理 `Memory/.trash/` 中具有可信软删除时间、且超过指定期限的普通文件。默认命令只生成预览和短时一次性计划；repair 备份、符号链接、无可信删除时间的文件以及正常的 active/archived/superseded 记忆均不会被删除：
+
+```bash
+# 仅预览，不删除
+uvx keepm gc --older-than-days 30
+
+# 使用预览返回的 token 执行完全相同且未变化的计划
+uvx keepm gc --confirm --token <gc-token>
+```
+
+确认后的 GC 是不可恢复删除；trash 内容、checksum、候选集合或 token 时效发生变化时会拒绝执行并要求重新预览。
+
 ## Agent 工作流与低噪对话式审核
 
 ```text
@@ -113,16 +136,16 @@ KeepM 使用受控对话完成 Inbox 审核，不依赖 GUI 或 Obsidian 插件
 >
 > 顺便提醒：检测到 2 条待审核候选记忆：
 >
-> 1. **［项目偏好］** 优先使用 pnpm 而非 npm（建议：**批准**）
-> 2. **［架构决策］** 放弃 Redis，改用 SQLite（建议：**批准**）
+> - **Proposal P1［项目偏好］** 优先使用 pnpm 而非 npm（建议：**批准**）
+> - **Proposal P2［架构决策］** 放弃 Redis，改用 SQLite（建议：**批准**）
 >
-> 可以回复“全部批准”“批准 1、拒绝 2”或“稍后”。
+> 可以回复“批准 Proposal P1、拒绝 Proposal P2”或“稍后”。
 
-主任务永远优先。用户回复“稍后”或忽略提醒后，本次会话不再重复打扰；沉默不会批准、拒绝、修改或删除任何内容。
+主任务永远优先，Proposal 使用独立于 `Step 1` 等主任务步骤的编号。“行”“好的”“按你说的办”“按建议处理”等泛化赞同只授权主任务，绝不授权 Inbox 变更；多条候选时用户必须明确引用 `Proposal P1` 等标签。只有最近明确呈报了一条 Proposal 时，“批准记忆提案”才可授权该唯一候选。用户回复“稍后”或忽略提醒后，本次会话不再重复打扰；沉默不会批准、拒绝、修改或删除任何内容。
 
 正式记忆使用“槽位命名”：`project-package-manager` 表示稳定主题，`pnpm` 只是该槽位当前的结论。`memory_context` / `memory_search` 在发现 active 名称、别名硬碰撞或同 kind 主题重叠时会返回有界的 `conflict_hints`；Agent 必须完整读取相关候选并核对项目真源，不能只信第一条。
 
-确认冲突并得到用户明确授权后，Agent 先预览 `memory_resolve_conflict(dry_run=true)`，再用绑定同一方案的短时 token 执行。`supersede` 保留历史关系，`archive` 归档失去独立价值的节点，`delete` 只把错误节点移入可恢复回收站。KeepM 会同时校验两份 checksum/token、拒绝 `supersedes` 环，并通过文件事务日志与单次 SQLite 事务避免可见的半完成状态。
+确认冲突并得到用户明确授权后，Agent 先预览 `memory_resolve_conflict(dry_run=true)`，再用绑定同一方案的短时 token 执行。`supersede` 保留历史关系，`archive` 归档失去独立价值的节点，`delete` 只把错误节点移入可恢复回收站。KeepM 会同时校验两份 checksum/token、拒绝 `supersedes` 环，并通过可恢复的文件事务日志与单次 SQLite 事务保证崩溃一致；若进程在多文件替换中断，下次启动会继续提交或安全回滚。
 
 ## MCP 工具一览
 
@@ -130,13 +153,22 @@ KeepM 使用受控对话完成 Inbox 审核，不依赖 GUI 或 Obsidian 插件
 | --- | --- | --- |
 | 上下文 | `memory_status`、`memory_context` | 运行状态、有长度边界的任务上下文和仅计数的 Inbox 信号 |
 | 检索 | `memory_search`、`memory_read`、`memory_links` | active 记忆加权检索、权威读取、WikiLink 与反向链接 |
-| 正式记忆 | `memory_create`、`memory_update`、`memory_delete`、`memory_resolve_conflict` | 创建已确认记忆；保护更新、删除及两条 active 记忆的预览式原子冲销 |
+| 正式记忆 | `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` | 保存、恢复、更新和归档未完成任务状态 |
 | 运维 | `memory_doctor`、`memory_repair`、`memory_sync` | 诊断损坏、预览授权的确定性修复、对账或重建索引 |
 
 修改或删除已有对象前必须完整读取当前内容，并提供一次性版本凭证；如果 Markdown 在读写之间发生变化，KeepM 会拒绝过期操作，不会盲目覆盖。
 
+## 对账、文件系统与长期健康
+
+- **分层对账：** 高频快速路径使用 `mtime_ns + size`；服务启动、默认每 30 分钟一次的周期深扫，以及 `memory_doctor` 都会重新计算内容 SHA-256。`memory_status` 返回 `last_checksum_scan` 和 `deep_scan_due`。
+- **落盘边界：** 单文件写入会先 `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` 默认免检，系统绝不因此自动归档或改写记忆。
+- **结构化报告：** `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 明确授权协议始终保留，不会把能力缺失当成批准。
+
 ## 设计哲学与非目标
 
 - **本地优先且透明：** 不依赖云服务、HTTP 守护进程或私有存储格式。

{keepm-3.1.0 → keepm-3.2.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.1.0-6f42c1.svg)](https://pypi.org/project/keepm/)
+[![Version](https://img.shields.io/badge/version-3.2.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)
@@ -88,8 +88,31 @@ For automation:
 uvx keepm setup --yes --root /path/to/notes --agent codex --project-dir /path/to/project
 ```
 
+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.
 
+## Minimal maintenance commands
+
+Health export reuses the deterministic `memory_doctor` findings and emits status/finding metadata only. It never includes memory bodies, Proposal content, or repair/update tokens:
+
+```bash
+uvx keepm doctor --format json
+uvx keepm doctor --format markdown --output keepm-health.md
+```
+
+Safe GC considers only ordinary files in `Memory/.trash/` with a trustworthy tombstone timestamp older than the selected retention period. The default command creates a preview and a short-lived, one-time plan. Repair backups, symlinks, unknown-age files, and normal active/archived/superseded memories are excluded:
+
+```bash
+# Preview only; deletes nothing
+uvx keepm gc --older-than-days 30
+
+# Execute the exact unchanged plan returned by the preview
+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.
+
 ## Agent workflow and low-noise review
 
 ```text
@@ -113,16 +136,16 @@ KeepM reviews Inbox candidates through controlled conversation, with no GUI or O
 >
 > Two memory candidates are waiting for review:
 >
-> 1. **[Project preference]** Prefer pnpm over npm — suggested: **approve**
-> 2. **[Architecture decision]** Use SQLite instead of Redis — suggested: **approve**
+> - **Proposal P1 [Project preference]** Prefer pnpm over npm — suggested: **approve**
+> - **Proposal P2 [Architecture decision]** Use SQLite instead of Redis — suggested: **approve**
 >
-> Reply with “approve all”, “approve 1, reject 2”, or “later”.
+> Reply with “approve Proposal P1, reject Proposal P2” or “later”.
 
-The main task always comes first. After “later” or an ignored offer, the Agent does not repeat the reminder in the same session. Silence never approves, rejects, edits, or deletes anything.
+The main task always comes first, and Proposal labels are independent from primary-task labels such as `Step 1`. Generic assent such as “yes”, “okay”, “do it”, or “apply your suggestions” authorizes only the primary task, never an Inbox mutation; with multiple candidates the user must explicitly reference a label such as `Proposal P1`. Only when the most recent review presented exactly one Proposal may “approve the memory Proposal” authorize that sole candidate. After “later” or an ignored offer, the Agent does not repeat the reminder in the same session. Silence never approves, rejects, edits, or deletes anything.
 
 Formal memory uses slot-based naming: `project-package-manager` is the stable topic, while `pnpm` is only its current value. When active names or aliases collide, or same-kind results appear to cover one topic, `memory_context` and `memory_search` return bounded `conflict_hints`. The Agent must fully read the relevant candidates and check the project source of truth instead of trusting the first hit.
 
-After the conflict is confirmed and the user explicitly authorizes the change, the Agent previews `memory_resolve_conflict(dry_run=true)` and then executes the token-bound unchanged plan. `supersede` preserves valid history, `archive` retires a note that lost independent value, and `delete` moves only an erroneous note to recoverable trash. KeepM validates both checksum/token pairs, rejects `supersedes` cycles, and combines a recoverable file journal with one SQLite transaction to prevent a visible half-resolved state.
+After the conflict is confirmed and the user explicitly authorizes the change, the Agent previews `memory_resolve_conflict(dry_run=true)` and then executes the token-bound unchanged plan. `supersede` preserves valid history, `archive` retires a note that lost independent value, and `delete` moves only an erroneous note to recoverable trash. KeepM validates both checksum/token pairs, rejects `supersedes` cycles, and combines a recoverable file journal with one SQLite transaction for crash consistency; if the process stops during the multi-file replacement, the next startup completes or safely rolls back the journal.
 
 ## MCP tools
 
@@ -130,13 +153,22 @@ After the conflict is confirmed and the user explicitly authorizes the change, t
 | --- | --- | --- |
 | 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 |
-| Formal memory | `memory_create`, `memory_update`, `memory_delete`, `memory_resolve_conflict` | Create confirmed memory; protect updates, deletes, and previewed atomic resolution of two active notes |
+| 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 |
 | Operations | `memory_doctor`, `memory_repair`, `memory_sync` | Diagnose damage, preview authorized deterministic repair, and reconcile/rebuild the index |
 
 Mutating an existing object requires a complete current read plus one-time version credentials. If Markdown changes between read and write, KeepM rejects the stale operation instead of overwriting it.
 
+## Reconciliation, filesystems, and long-term health
+
+- **Tiered reconciliation:** the frequent fast path uses `mtime_ns + size`; server startup, the periodic deep scan (every 30 minutes by default), and `memory_doctor` recompute content SHA-256. `memory_status` returns `last_checksum_scan` and `deep_scan_due`.
+- **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.
+- **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.
+
 ## Design principles and non-goals
 
 - **Local-first and transparent:** no cloud service, HTTP daemon, or proprietary storage format.

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

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

keepm-3.2.0/src/keepm/__init__.py

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

{keepm-3.1.0 → keepm-3.2.0}/src/keepm/cli.py

@@ -22,6 +22,16 @@ def main(argv: Sequence[str] | None = None) -> None:
 
         hook_main(arguments[1:])
         return
+    if arguments[:1] == ["doctor"]:
+        from keepm.maintenance import doctor_main
+
+        doctor_main(arguments[1:])
+        return
+    if arguments[:1] == ["gc"]:
+        from keepm.maintenance import gc_main
+
+        gc_main(arguments[1:])
+        return
 
     from keepm.server import main as server_main
 

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

@@ -11,6 +11,7 @@ from typing import Literal, cast
 
 MemoryLanguage = Literal["zh", "en"]
 MemoryFeedback = Literal["off", "compact", "debug"]
+SQLiteJournalMode = Literal["wal", "delete"]
 
 
 def default_config_path() -> Path:
@@ -38,6 +39,9 @@ class KeepMConfig:
     audit_enabled: bool = False
     inbox_review_after_days: int = 30
     memory_feedback: MemoryFeedback = "off"
+    deep_reconcile_interval_seconds: int = 1_800
+    verification_review_after_days: int = 180
+    sqlite_journal_mode: SQLiteJournalMode = "wal"
 
     def __post_init__(self) -> None:
         memory_path = Path(self.memory_dir)
@@ -59,6 +63,12 @@ class KeepMConfig:
             raise ValueError("inbox_review_after_days must be positive")
         if self.memory_feedback not in ("off", "compact", "debug"):
             raise ValueError("memory_feedback must be off, compact, or debug")
+        if self.deep_reconcile_interval_seconds < 0:
+            raise ValueError("deep_reconcile_interval_seconds must be non-negative")
+        if self.verification_review_after_days < 1:
+            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")
         object.__setattr__(self, "vault_path", self.vault_path.expanduser().resolve())
 
     @property
@@ -146,6 +156,15 @@ class ConfigStore:
             memory_feedback=cast(
                 MemoryFeedback, str(data.get("memory_feedback", "off"))
             ),
+            deep_reconcile_interval_seconds=int(
+                data.get("deep_reconcile_interval_seconds", 1_800)
+            ),
+            verification_review_after_days=int(
+                data.get("verification_review_after_days", 180)
+            ),
+            sqlite_journal_mode=cast(
+                SQLiteJournalMode, str(data.get("sqlite_journal_mode", "wal"))
+            ),
         )
 
     def load_optional(self) -> KeepMConfig | None:
@@ -175,6 +194,9 @@ class ConfigStore:
             f"audit_enabled = {str(config.audit_enabled).lower()}\n"
             f"inbox_review_after_days = {config.inbox_review_after_days}\n"
             f"memory_feedback = {json.dumps(config.memory_feedback)}\n"
+            f"deep_reconcile_interval_seconds = {config.deep_reconcile_interval_seconds}\n"
+            f"verification_review_after_days = {config.verification_review_after_days}\n"
+            f"sqlite_journal_mode = {json.dumps(config.sqlite_journal_mode)}\n"
         )
         temporary = self.path.with_suffix(".tmp")
         temporary.write_text(content, encoding="utf-8", newline="\n")

{keepm-3.1.0 → keepm-3.2.0}/src/keepm/database.py

@@ -9,9 +9,9 @@ import threading
 from contextlib import contextmanager
 from dataclasses import dataclass
 from pathlib import Path
-from typing import Iterator
+from typing import Callable, Iterator, Literal
 
-from keepm.identifiers import normalize_identifier
+from keepm.identifiers import normalize_identifier, portable_path_key
 from keepm.markdown import slug_filename
 from keepm.models import (
     MemoryDocument,
@@ -99,7 +99,11 @@ class IndexedProposal:
 
 
 class MemoryDatabase:
-    def __init__(self, path: Path) -> None:
+    def __init__(
+        self, path: Path, *, journal_mode: Literal["wal", "delete"] = "wal"
+    ) -> None:
+        if journal_mode not in {"wal", "delete"}:
+            raise ValueError("journal_mode must be wal or delete")
         self.path = path.expanduser().resolve()
         self.path.parent.mkdir(parents=True, exist_ok=True)
         self._lock = threading.RLock()
@@ -110,7 +114,10 @@ class MemoryDatabase:
             check_same_thread=False,
         )
         self.connection.row_factory = sqlite3.Row
-        self.connection.execute("PRAGMA journal_mode=WAL")
+        row = self.connection.execute(
+            f"PRAGMA journal_mode={journal_mode.upper()}"
+        ).fetchone()
+        self.journal_mode = str(row[0]).casefold() if row is not None else journal_mode
         self.connection.execute("PRAGMA busy_timeout=5000")
         self.connection.execute("PRAGMA foreign_keys=ON")
         try:
@@ -752,64 +759,113 @@ class MemoryDatabase:
             """SELECT id, path, name_key, aliases_json, scope, project_id, status
             FROM memories"""
         ).fetchall()
+
+        id_index: dict[str, list[sqlite3.Row]] = {}
+        path_index: dict[str, list[sqlite3.Row]] = {}
+        stem_index: dict[str, list[sqlite3.Row]] = {}
+        name_index: dict[str, list[sqlite3.Row]] = {}
+        alias_index: dict[str, list[sqlite3.Row]] = {}
+
+        def add(
+            index: dict[str, list[sqlite3.Row]], key: str, row: sqlite3.Row
+        ) -> None:
+            index.setdefault(key, []).append(row)
+
+        def link_path_key(value: str | Path) -> str:
+            return portable_path_key(str(value).replace("\\", "/")).strip(
+                "/"
+            ).removesuffix(".md")
+
+        for memory in memories:
+            add(id_index, str(memory["id"]).casefold(), memory)
+            path = Path(str(memory["path"]))
+            normalized_path = link_path_key(path)
+            parts = tuple(part for part in normalized_path.split("/") if part)
+            for start in range(len(parts)):
+                add(path_index, "/".join(parts[start:]), memory)
+            try:
+                add(stem_index, normalize_identifier(path.stem), memory)
+            except ValueError:
+                pass
+            add(name_index, str(memory["name_key"]), memory)
+            for alias in json.loads(str(memory["aliases_json"])):
+                try:
+                    add(alias_index, normalize_identifier(str(alias)), memory)
+                except ValueError:
+                    continue
+
         for link in rows:
             names = self._target_names(str(link["target_text"]))
             target_text = str(link["target_text"]).strip()
             target_key = target_text.casefold().replace("\\", "/")
-            target_path_key = target_key.removesuffix(".md")
+            target_path_key = link_path_key(target_text)
             source_scope = str(link["scope"])
             source_project = str(link["project_id"])
-            eligible: list[tuple[tuple[int, ...], sqlite3.Row]] = []
-            for target in memories:
-                if source_scope == "global":
-                    if target["scope"] != "global":
+            eligible: dict[str, tuple[tuple[int, ...], sqlite3.Row]] = {}
+
+            def consider(
+                candidates: list[sqlite3.Row],
+                priority_for: tuple[int, ...]
+                | Callable[[sqlite3.Row], tuple[int, ...]],
+            ) -> None:
+                for target in candidates:
+                    if callable(priority_for):
+                        match_priority = priority_for(target)
+                    else:
+                        match_priority = priority_for
+                    if source_scope == "global":
+                        if target["scope"] != "global":
+                            continue
+                    elif not (
+                        target["scope"] == "global"
+                        or (
+                            target["scope"] == "project"
+                            and target["project_id"] == source_project
+                        )
+                    ):
                         continue
-                elif not (
-                    target["scope"] == "global"
-                    or (
-                        target["scope"] == "project"
+                    scope_priority = (
+                        0
+                        if target["scope"] == "project"
                         and target["project_id"] == source_project
+                        else 1
                     )
-                ):
-                    continue
-                path = Path(str(target["path"]))
-                path_key = path.as_posix().casefold().removesuffix(".md")
-                try:
-                    path_stem_key = normalize_identifier(path.stem)
-                except ValueError:
-                    path_stem_key = path.stem.casefold()
-                alias_keys: set[str] = set()
-                for alias in json.loads(str(target["aliases_json"])):
-                    try:
-                        alias_keys.add(normalize_identifier(str(alias)))
-                    except ValueError:
-                        pass
-                if target_key == str(target["id"]).casefold():
-                    priority = (0, 0)
-                elif "/" in target_path_key and path_key.endswith(
-                    "/" + target_path_key.lstrip("/")
-                ):
-                    priority = (0, 1)
-                elif path_stem_key in names:
-                    priority = (0, 2)
-                elif str(target["name_key"]) in names:
-                    priority = (1, 0 if target["status"] == "active" else 1, 0)
-                elif alias_keys.intersection(names):
-                    priority = (1, 0 if target["status"] == "active" else 1, 1)
-                else:
-                    continue
-                scope_priority = (
-                    0
-                    if target["scope"] == "project"
-                    and target["project_id"] == source_project
-                    else 1
+                    priority = (*match_priority, scope_priority)
+                    memory_id = str(target["id"])
+                    previous = eligible.get(memory_id)
+                    if previous is None or priority < previous[0]:
+                        eligible[memory_id] = (priority, target)
+
+            consider(id_index.get(target_key, []), (0, 0))
+            if "/" in target_path_key:
+                consider(path_index.get(target_path_key.strip("/"), []), (0, 1))
+            for name in names:
+                consider(stem_index.get(name, []), (0, 2))
+                consider(
+                    name_index.get(name, []),
+                    lambda target: (
+                        1,
+                        0 if target["status"] == "active" else 1,
+                        0,
+                    ),
+                )
+                consider(
+                    alias_index.get(name, []),
+                    lambda target: (
+                        1,
+                        0 if target["status"] == "active" else 1,
+                        1,
+                    ),
                 )
-                eligible.append(((*priority, scope_priority), target))
+
             if not eligible:
                 continue
-            eligible.sort(key=lambda item: (*item[0], str(item[1]["id"])))
-            best_priority = eligible[0][0]
-            best = [item for item in eligible if item[0] == best_priority]
+            ranked = sorted(
+                eligible.values(),
+                key=lambda item: (*item[0], str(item[1]["id"])),
+            )
+            best_priority = ranked[0][0]
+            best = [item for item in ranked if item[0] == best_priority]
             if len(best) != 1:
                 continue
             target = best[0][1]

{keepm-3.1.0 → keepm-3.2.0}/src/keepm/doctor.py

@@ -1,5 +1,6 @@
 from __future__ import annotations
 
+import datetime as dt
 from dataclasses import dataclass
 from pathlib import Path
 
@@ -18,6 +19,9 @@ from keepm.sync import sha256_file
 from keepm.validation import MemoryValidationError
 
 
+VERIFICATION_SENSITIVE_KINDS = frozenset({"constraint", "fix", "workflow"})
+
+
 @dataclass(frozen=True, slots=True)
 class DoctorFinding:
     code: str
@@ -179,6 +183,37 @@ def run_doctor(
                         ),
                         [],
                     ).append(path)
+
+    today = dt.datetime.now(dt.timezone.utc).date()
+    review_after_days = storage.config.verification_review_after_days
+    for path, document in parsed_by_path.items():
+        if (
+            document.status != "active"
+            or document.kind not in VERIFICATION_SENSITIVE_KINDS
+        ):
+            continue
+        if document.verified_at is None:
+            findings.append(
+                DoctorFinding(
+                    "verification_missing",
+                    path,
+                    "active change-sensitive memory has never been verified against its source of truth",
+                    "info",
+                )
+            )
+            continue
+        age_days = max(
+            0, (today - dt.date.fromisoformat(document.verified_at)).days
+        )
+        if age_days >= review_after_days:
+            findings.append(
+                DoctorFinding(
+                    "verification_overdue",
+                    path,
+                    f"active change-sensitive memory was last verified {age_days} days ago",
+                    "info",
+                )
+            )
     for memory_id, duplicate_paths in ids.items():
         if len(duplicate_paths) > 1:
             for path in duplicate_paths: