pmem-ai 0.5.0

package/docs/v0.4 pre-design.md

@@ -0,0 +1,417 @@
+# v0.4 前置设计决策
+
+本文档记录 pmem v0.4 开工前的最终技术决策。v0.4 的核心定位：
+
+> **Agent Workflow Automation**
+>
+> 不是语义搜索增强，不是 MCP Server，不是 REST 服务。
+> 而是：代码变更感知 → dirty 标记 → update suggest → distill suggest → Agent 确认写入 → rebuild → verify 的完整闭环。
+>
+> v0.4 要回答的唯一问题：**pmem 能否进入 Agent 真实开发工作流，低成本、低噪音、可控地运行？**
+
+---
+
+## 一、v0.4 不做的事情（范围排除）
+
+以下方向已明确排除，不做任何实现、不做 experimental、不做接口预留：
+
+| 排除项 | 原因 |
+|--------|------|
+| API embedding | 引入 API key + 网络依赖 + 成本 + 隐私顾虑 |
+| local embedding (transformers.js) | 包体积 + 跨平台 + 中文模型选择未验证 |
+| pmem serve (MCP/REST/daemon) | 分散主线，CLI 已是更优 Agent 入口 |
+| Graph UI | UI 层独立问题，不阻塞 workflow 验证 |
+| 多用户远程服务 | 远超 v0.4 范围 |
+
+v0.4 对 embedding 的处理：保留 Provider Interface + manifest 配置 + SQLite schema 预留，但不接入任何模型。
+v0.4 对 serve 的处理：完全搁置，代码中不做任何 serve 相关实现。
+
+---
+
+## 二、v0.4 目标闭环
+
+```
+Agent 开始任务
+  ↓
+pmem recall / ask 获取上下文
+  ↓
+Agent 修改代码
+  ↓
+pmem 感知 changed files
+  ↓
+pmem mark-dirty --auto
+  ↓
+pmem update --suggest 生成记忆更新建议
+  ↓
+Agent / 人确认后写入 Markdown cards
+  ↓
+pmem rebuild --changed 更新 SQLite
+  ↓
+pmem verify 检查一致性
+```
+
+这条链路是 v0.4 的"核心回路"。v0.4 做完，pmem 就从"查询工具"变成了"工作流运行时"。
+
+---
+
+## 三、优先级表
+
+### P0 — 必须完成
+
+| # | 功能 | 说明 |
+|---|------|------|
+| 1 | changed files detection | 感知项目文件的增删改（基于 git status + file mtime） |
+| 2 | dirty_flags workflow | mark-dirty --auto 自动标记 + 关联 cards |
+| 3 | pmem update --suggest | 基于 dirty flags + changed files 生成记忆更新建议 |
+| 4 | pmem distill --suggest | 基于未蒸馏 traces 数量 + 时效性建议蒸馏时机 |
+| 5 | pmem session start/end | 会话追踪（v0.3 P1 已完成，v0.4 加强 update_log 汇总） |
+| 6 | CLI hooks-friendly output | 所有 suggest 命令支持 `--format json` 供 Agent 程序化消费 |
+| 7 | Integration templates | Claude Code / Cursor / Codex 的 AGENTS.md / rules / CLAUDE.md 模板 |
+| 8 | verify stale memory 增强 | 基于 changed files 检测可能过期的 cards，提示更新 |
+
+### P1 — 应该完成
+
+| # | 功能 | 说明 |
+|---|------|------|
+| 1 | pmem update --apply-suggestion | 非交互式接受建议并写入 |
+| 2 | pmem distill --apply-suggestion | 非交互式接受蒸馏建议并执行 |
+| 3 | changed files → related cards 推断 | 通过 paths 表 + edges 表反查受影响的 cards |
+| 4 | session update_log 汇总 | session end 时汇总本次会话的所有 update_log |
+| 5 | AGENTS.md / CLAUDE.md 模板优化 | 嵌入 hooks 使用示例，降低 Agent 接入门槛 |
+
+### P2 — 推迟到 v0.5+
+
+| 功能 | 目标版本 |
+|------|---------|
+| embedding 真接入 (API/local) | v0.5+ |
+| pmem serve (MCP/REST) | v0.5+ |
+| Graph UI | v0.5+ |
+| 多用户远程服务 | v0.5+ |
+| 自动 commit message 生成 | v0.5+ |
+
+---
+
+## 四、Changed Files Detection 设计
+
+### 数据来源
+
+优先级：`git status --porcelain` > `file mtime comparison`
+
+```bash
+git status --porcelain 2>/dev/null || find . -newer .pmem/.last-check -type f
+```
+
+### 输出格式
+
+```json
+{
+  "checked_at": "2026-05-20T10:00:00Z",
+  "source": "git",
+  "changes": [
+    { "path": "src/core/db.ts", "status": "M", "related_cards": ["module.sqlite_runtime"] },
+    { "path": "src/commands/rebuild.ts", "status": "M", "related_cards": ["module.sqlite_runtime"] },
+    { "path": "tests/db.test.ts", "status": "A", "related_cards": [] }
+  ],
+  "affected_cards": ["module.sqlite_runtime"],
+  "suggested_actions": [
+    "mark-dirty --reason 'src/core/db.ts modified'",
+    "update --suggest"
+  ]
+}
+```
+
+### 关联推断规则
+
+1. 通过 `paths` 表精确匹配：`SELECT card_id FROM paths WHERE path LIKE '%<changed_file>%'`
+2. 通过目录前缀模糊匹配：`src/core/` 变更 → 查找所有 paths 中包含 `src/core/` 的 cards
+3. 通过 edges 表扩展：找到关联 cards 的直接邻居
+
+---
+
+## 五、`pmem update --suggest` 设计
+
+### 触发条件
+
+1. 存在 unresolved dirty_flags
+2. state.md / next.md 内容过时
+3. 检测到 changed files 关联到已有 cards
+4. 上次 update 距今超过 24 小时
+
+### 输出格式 (`--format compact`)
+
+```
+Memory Update Suggestions:
+
+Dirty Flags (2 unresolved):
+  [project] code_changed (2026-05-20T09:00:00Z)
+  [module.url_store] schema_changed (2026-05-20T09:30:00Z)
+
+Changed Files (3):
+  M src/store.ts → related: module.url_store
+  M src/shortcode.ts → related: module.shortcode_generator
+  A tests/store.test.ts → related: (none)
+
+Suggested Actions:
+  1. Update module.url_store — src/store.ts changed
+  2. Update module.shortcode_generator — src/shortcode.ts changed
+  3. Create trace for recent changes
+  4. Update state.md
+
+Run `pmem update --apply-suggestion <id>` to accept, or `pmem update --confirm` to write manually.
+```
+
+### 输出格式 (`--format json`)
+
+```json
+{
+  "dirty_flags": [
+    { "scope": "project", "target": ".pmem", "reason": "code_changed", "created_at": "..." }
+  ],
+  "changed_files": [
+    { "path": "src/store.ts", "status": "M", "related_cards": ["module.url_store"] }
+  ],
+  "suggestions": [
+    {
+      "id": "suggest-1",
+      "action": "update_card",
+      "target": "module.url_store",
+      "reason": "src/store.ts changed — this file is registered as a source_file of module.url_store",
+      "priority": "high",
+      "auto_applicable": false
+    },
+    {
+      "id": "suggest-2",
+      "action": "create_trace",
+      "target": null,
+      "reason": "3 files changed without a corresponding trace",
+      "priority": "medium",
+      "auto_applicable": true
+    }
+  ]
+}
+```
+
+### `--apply-suggestion <id>` 行为
+
+| suggestion.action | 自动行为 |
+|-------------------|---------|
+| `update_card` | 标记该 card 的 `last_verified_at` 为过期，提示 Agent 手动更新 |
+| `create_trace` | 自动创建 trace 文件（格式同 `pmem update --confirm`） |
+| `update_state` | 提示 Agent 手动编辑 state.md |
+| `mark_dirty_resolved` | 将该 dirty flag 的 `resolved_at` 设为当前时间 |
+
+---
+
+## 六、`pmem distill --suggest` 设计
+
+### 触发条件
+
+1. traces/ 目录中未蒸馏 traces 数量 ≥ `manifest.distill.max_undistilled_traces` (默认 20)
+2. 距上次蒸馏超过 `manifest.distill.cadence` (默认 weekly)
+
+### 输出格式
+
+```
+Distill Suggestions:
+
+Undistilled traces: 15 (threshold: 20)
+Last distilled: 2026-05-13 (7 days ago)
+Cadence: weekly
+
+Traces by target:
+  module.url_store: 5 traces → suggested merge
+  module.shortcode_generator: 3 traces → below threshold
+  decision.storage_backend: 2 traces → below threshold
+  (ungrouped): 5 traces → create new decision or trace card
+
+Suggested Actions:
+  1. Distill 5 traces into module.url_store
+  2. Review 5 ungrouped traces — may indicate a new module or decision
+
+Run `pmem distill --apply-suggestion <id>` to apply, or `pmem distill --confirm` to review interactively.
+```
+
+### 与 v0.3 的差异
+
+v0.3 的 distill 是纯文件扫描 + Markdown 追加。v0.4 的 distill 应该：
+1. 从 SQLite edges 表推断 traces → cards 的分组关系
+2. 按 target card 聚合，超过阈值的才建议蒸馏
+3. 未被分组的 traces 建议创建新 card
+
+---
+
+## 七、CLI Hooks-Friendly Output 设计
+
+### 设计原则
+
+所有 suggest/info 类命令输出必须满足：
+- 无交互式提示（不依赖 stdin）
+- `--format json` 输出可被 `jq` / `JSON.parse` 直接消费
+- `--format compact` 输出可被 Agent 直接阅读
+- 退出码明确：0 = 无建议, 1 = 有建议待处理, 2 = 错误
+
+### 退出码约定
+
+| 命令 | 退出码 0 | 退出码 1 | 退出码 2 |
+|------|---------|---------|---------|
+| `pmem update --suggest` | 无建议 | 有建议待处理 | 错误 |
+| `pmem distill --suggest` | 无需蒸馏 | 建议蒸馏 | 错误 |
+| `pmem verify` | 全部通过 | 有 warning | 有 error |
+
+这个退出码约定让 Agent 可以这样使用：
+
+```bash
+if pmem update --suggest --format json > /tmp/suggestions.json; then
+  echo "Memory is up to date."
+else
+  # Parse suggestions and decide which to apply
+  cat /tmp/suggestions.json | jq '.suggestions'
+fi
+```
+
+---
+
+## 八、Integration Templates 设计
+
+### 目标
+
+降低 Claude Code / Cursor / Codex 接入 pmem 的门槛。每个模板应包含：
+1. 启动指令（session start + recall）
+2. 工作循环（修改代码 → mark-dirty → update）
+3. 结束指令（update --confirm + session end + verify）
+
+### Claude Code 模板 (`.pmem/integrations/claude-code/CLAUDE.md`)
+
+```markdown
+# pmem integration for Claude Code
+
+## Session Start
+Run at the beginning of each coding session:
+```bash
+pmem session start -a "Claude"
+pmem recall --format compact --budget 2000
+```
+
+## During Work
+After modifying code:
+```bash
+pmem mark-dirty -r "Modified <file> — <brief reason>"
+```
+
+Before committing changes:
+```bash
+pmem update --suggest --format json
+```
+
+## Session End
+Before ending the session:
+```bash
+pmem update --confirm -s "<summary of changes>" -n "<next step>"
+pmem session end -s "<task summary>"
+pmem verify
+```
+
+## Hooks (optional)
+Add to `.claude/settings.json`:
+```json
+{
+  "hooks": {
+    "PostToolUse": [
+      {
+        "matcher": "Edit|Write",
+        "command": "pmem mark-dirty -r \"File modified by Claude\""
+      }
+    ]
+  }
+}
+```
+```
+
+### Cursor 模板 (`.pmem/integrations/cursor/rules.example.md`)
+
+类似结构，适配 Cursor 的 Rules 语法。
+
+### Codex 模板 (`.pmem/integrations/codex/AGENTS.md`)
+
+类似结构，适配 Codex 的 AGENTS.md 约定。
+
+---
+
+## 九、技术债清理（v0.4 功能开发前完成）
+
+### 债 1：重复内联 YAML 解析器
+
+**问题：** `rebuild.ts` 和 `migrate.ts` 各有一份 ~100 行的内联 YAML 解析器。
+
+**方案：** 抽取到 `src/core/yaml.ts`：
+
+```typescript
+export function parseSimpleYaml(yaml: string): Record<string, unknown>;
+export function parseYamlValue(val: string): string | boolean | number | string[];
+export function parseFrontmatter(content: string): { data: Record<string, unknown>; body: string } | null;
+export function stringifyFrontmatter(data: Record<string, unknown>, body: string): string;
+```
+
+`rebuild.ts`、`migrate.ts`、`distill.ts` 统一使用 `src/core/yaml.ts`。
+
+### 债 2：manifest `as any` 类型绕过
+
+**问题：** `migrate.ts` 中 `saveManifest(pmemPath, newManifest as any)` 绕过了类型检查。
+
+**方案：**
+1. 将 `Manifest` 改为 discriminated union：`type Manifest = ManifestV02 | ManifestV03`
+2. `saveManifest` 接受 `Manifest`（union type），运行时根据 `pmem.schema_version` 校验
+3. `migrate02to03` 返回 `ManifestV03`，不再需要 `as any`
+
+---
+
+## 十、开工顺序
+
+```
+Step 0: 冻结 v0.4 pre-design（本文档）
+  ↓
+Step 1a: 抽取 YAML 解析器到 src/core/yaml.ts
+  ↓
+Step 1b: 移除 manifest as any，typed migration
+  ↓
+Step 2: 补测试（yaml / manifest / rebuild-migrate 一致性）
+  ↓
+Step 3: P0 功能开发（按优先级表 1→8 顺序）
+  ↓
+Step 4: P1 功能开发
+  ↓
+Step 5: E2E 实战验证
+```
+
+---
+
+## 十一、v0.4 最终决策表
+
+| 问题 | 最终决策 |
+|------|---------|
+| v0.4 主线 | Agent workflow 自动化 |
+| embedding | v0.4 不入，仅保留 Provider Interface + manifest 配置 |
+| API embedding | 暂缓 |
+| local embedding | 暂缓 |
+| pmem serve (MCP/REST) | 完全搁置，不做 experimental |
+| YAML 解析器 | 抽取到 src/core/yaml.ts |
+| manifest as any | 移除，改 discriminated union |
+| 开工顺序 | 先清技术债，再做 workflow P0 |
+| v0.5 目标 | 上线可用 Beta |
+
+---
+
+## 十二、v0.4 一句话定义
+
+> **pmem v0.4 是一个能感知代码变更、自动建议记忆更新、通过退出码和 JSON 输出与 Agent 协作的项目记忆工作流运行时。**
+
+更工程化：
+
+```
+pmem v0.4 =
+  v0.3 SQLite runtime
++ changed files detection
++ dirty → suggest → apply 闭环
++ CLI hooks-friendly output contract
++ integration templates (Claude Code / Cursor / Codex)
+```