pmem-ai 0.5.0

package/docs/handover-v0.4.md

@@ -0,0 +1,367 @@
+# pmem v0.4 交接文档
+
+## 一、项目概况
+
+**pmem**（Project Memory for Agents）是一个面向 AI coding agent 的图结构项目记忆 CLI 运行时。它让 Agent 以极少 token 恢复项目上下文、查找相关记忆、溯源决策，并通过感知代码变更自动建议记忆更新。
+
+- **仓库：** [github.com/KkSss999/pmem](https://github.com/KkSss999/pmem)（Private）
+- **当前版本：** v0.4.0（main 分支）
+- **技术栈：** TypeScript (strict, CommonJS, ES2022) + Commander + js-yaml + better-sqlite3
+- **运行时：** Node.js ≥18
+- **测试框架：** Node.js 原生 `node:test`（88 测试，~760ms）
+- **测试隔离区：** `temp/`（gitignored）
+
+### 一句话状态
+
+> v0.1 + v0.2 + v0.3 + v0.4 全部完成。15 个命令、零 TypeScript 错误、88 测试全通过。Agent workflow 闭环已打通：代码变更感知 → dirty 标记 → 建议生成 → 确认写入 → 蒸馏 → 验证。
+
+---
+
+## 二、版本演进概览
+
+| 版本 | 主题 | 关键交付 |
+|------|------|---------|
+| v0.1 | 核心闭环 | 10 命令，Markdown 主数据 + JSON indexes |
+| v0.2 | 工程底座 | +migrate, +distill, atomicWrite, file lock, card_policy |
+| v0.3 | SQLite Runtime | 7 P0 表, content-hash 增量 rebuild, FTS5, 四格式输出 |
+| v0.4 | **Agent Workflow Automation** | status, mark-dirty --auto, update --suggest, 退出码协议, integration templates |
+
+---
+
+## 三、v0.4 完成清单
+
+### P0 — 8/8
+
+| # | 功能 | 文件 | 说明 |
+|---|------|------|------|
+| 1 | `pmem status` | [src/commands/status.ts](src/commands/status.ts) **新建** | git status + paths 表反查，三级匹配（exact/directory/graph_neighbor），`--format compact/json`，退出码 0/1/2 |
+| 2 | `mark-dirty --auto` | [src/commands/update.ts](src/commands/update.ts) | git status → paths 反查 → 自动 insertDirtyFlag |
+| 3 | `update --suggest` | [src/commands/update.ts](src/commands/update.ts) | dirty_flags + state 时效 → 结构化建议，`--format json` 输出 |
+| 4 | `update --apply-suggestion` | [src/commands/update.ts](src/commands/update.ts) | 自动执行建议（update_card/create_trace/update_state） |
+| 5 | `distill --suggest` | [src/commands/distill.ts](src/commands/distill.ts) | SQLite edges 推断分组，退出码 0/1 |
+| 6 | `distill --apply-suggestion` | [src/commands/distill.ts](src/commands/distill.ts) | 非交互式应用蒸馏到指定 card |
+| 7 | session start/end | [src/commands/session.ts](src/commands/session.ts) | 已在 v0.3 P1 完成，v0.4 增强 update_log 汇总 |
+| 8 | CLI hooks-friendly output | update/distill/verify/status | 统一退出码（0=正常, 1=建议/警告, 2=错误），所有 suggest 命令 `--format json` |
+| 9 | Integration templates | `.pmem/integrations/` + [src/commands/init.ts](src/commands/init.ts) | Claude Code / Cursor / Codex 模板，嵌入 v0.4 workflow 指令 |
+| 10 | verify stale memory | [src/commands/verify.ts](src/commands/verify.ts) | paths 表 source_files 的 mtime 对比 card updated_at |
+
+### P1 — 3/3
+
+| # | 功能 | 文件 |
+|---|------|------|
+| 1 | status 三级匹配 | [src/commands/status.ts](src/commands/status.ts) — exact → directory → graph_neighbor |
+| 2 | session update_log 汇总 | [src/commands/session.ts](src/commands/session.ts) — end 时聚合 actions + affected_cards + unresolved dirty_flags |
+| 3 | AGENTS.md 模板优化 | [src/commands/init.ts](src/commands/init.ts) — 内联模板已更新，写入 v0.4 完整内容 |
+
+### v0.4 排除项（明确不做）
+
+| 排除 | 原因 |
+|------|------|
+| embedding 真接入 | 仅保留 Provider Interface + manifest 配置 |
+| pmem serve (MCP/REST) | 完全搁置 |
+| Graph UI | v0.5+ |
+| 多用户远程服务 | v0.5+ |
+
+---
+
+## 四、代码库地图
+
+```
+pmem/
+├── CLAUDE.md                              # Agent 入口指令
+├── package.json                           # v0.4.0，依赖：commander, js-yaml, better-sqlite3
+├── tsconfig.json                          # strict, ES2022, CommonJS
+├── .gitignore                             # node_modules, dist, temp, .pmem, .DS_Store, .claude
+├── temp/                                  # gitignored 测试隔离区
+│
+├── docs/                                  # 设计文档（按顺序读）
+│   ├── Voorlopige projekidee.md           # 长期架构总纲
+│   ├── prd.md                             # 产品需求文档
+│   ├── project-roadmap.md                 # v0.1 → v0.5 路线图
+│   ├── v0.2 pre-design.md                 # v0.2 前置设计
+│   ├── v0.2 pre-roadmap.md                # v0.2 路线图
+│   ├── v0.3 pre-design.md                 # ⭐ v0.3 圣经 — 14 章技术决策
+│   ├── v0.4 pre-design.md                 # ⭐ v0.4 圣经 — Agent Workflow Automation
+│   ├── handover-v0.3.md                   # v0.3 交接文档
+│   └── handover-v0.4.md                   # 本文档
+│
+├── src/
+│   ├── index.ts                           # CLI 入口（Commander），15 命令，版本 0.4.0
+│   ├── types.ts                           # 全部 TS 类型，Manifest = ManifestV02 | ManifestV03
+│   │
+│   ├── core/                              # 共享基础设施
+│   │   ├── fs.ts                          # 文件工具：atomicWrite, acquireLock, readFile, listFiles...
+│   │   ├── manifest.ts                    # Manifest 加载/保存(js-yaml)，getDefaultManifest()→ManifestV03
+│   │   ├── db.ts                          # ⭐ SQLite 核心：schema 创建(10 表)、CRUD、dirty/session/update_log
+│   │   ├── hash.ts                        # SHA-256 内容 hash（file/frontmatter/body）
+│   │   ├── yaml.ts                        # 共享 YAML frontmatter 解析器
+│   │   ├── format.ts                      # CLI 输出格式化（compact/json/paths/pack）
+│   │   ├── *.test.ts                      # 4 个测试文件（88 用例）
+│   │
+│   └── commands/                          # 15 个命令文件
+│       ├── init.ts                        # pmem init [--guided] — 已更新 v0.4 integration 模板
+│       ├── rebuild.ts                     # pmem rebuild --changed/--full/--card — SQLite 写入
+│       ├── recall.ts                      # pmem recall --budget N --format compact/json/paths/pack
+│       ├── ask.ts                         # pmem ask <query> — 6 步召回（exact→alias→tag→graph→FTS→rerank）
+│       ├── graph.ts                       # pmem related --depth N --type X / pmem trace
+│       ├── verify.ts                      # pmem verify --fix — hash 对比 + orphan + stale + exit codes
+│       ├── update.ts                      # ⭐ pmem update --suggest/--apply-suggestion/--confirm
+│       │                                  #    pmem mark-dirty --auto
+│       ├── migrate.ts                     # pmem migrate --to 0.3 --dry-run
+│       ├── distill.ts                     # ⭐ pmem distill --suggest/--apply-suggestion/--confirm
+│       ├── session.ts                     # pmem session start/end（+ update_log 汇总）
+│       ├── status.ts                      # ⭐ pmem status — git status + paths 三级匹配
+│       └── integration.ts                 # pmem integration list/install/verify
+└── dist/                                  # tsc 编译输出（gitignored）
+```
+
+---
+
+## 五、关键技术决策
+
+### 1. 架构原则
+
+```
+Markdown cards (.pmem/**/*.md)  ← 唯一主数据
+SQLite (.pmem/pmem.db)          ← 索引、缓存、运行时状态
+JSON indexes (.pmem/indexes/)   ← legacy 保留
+```
+
+- **永远不**在 SQLite 中创建"数据库独有"的卡片
+- **永远不**删除旧 JSON indexes
+- **永远不**直接修改 SQLite（修改必须通过 Markdown → rebuild）
+
+### 2. Content Hash 增量
+
+三 hash 体系：
+- `file_hash` — 整个 .md 文件（变化 = 重解析全部）
+- `frontmatter_hash` — YAML 部分（变化 = 更新元数据+关系）
+- `body_hash` — 正文部分（变化 = 更新 FTS/summary/token_count）
+
+`--changed` 模式下对比 hash，全部匹配则跳过。
+
+### 3. 退出码协议
+
+| 命令 | 0 | 1 | 2 |
+|------|---|---|---|
+| `pmem status` | 有变更 | 无变更 | 错误 |
+| `pmem update --suggest` | 无建议 | 有建议 | 错误 |
+| `pmem distill --suggest` | 无需蒸馏 | 建议蒸馏 | 错误 |
+| `pmem verify` | 通过 | 有 warning | 有 error |
+
+### 4. Status 三级匹配
+
+```
+Pass 1: exact — changed file path LIKE paths.path
+Pass 2: directory — changed file directory LIKE paths.path
+Pass 3: graph_neighbor — edges 表 1-hop 扩展
+```
+
+优先级：exact > directory > graph_neighbor（高优先级覆盖低优先级）。
+
+### 5. update --suggest 建议引擎
+
+基于三个数据源生成建议：
+1. `getUnresolvedDirtyFlags(db)` — 未解决的脏标记
+2. `state.md` mtime — 超过 24h = stale
+3. `next.md` 内容长度 — < 50 chars = minimal
+
+建议类型：`update_card`, `create_trace`, `update_state`, `update_next`。
+
+### 6. Manifest 类型系统
+
+```typescript
+type ManifestSchemaVersion = '0.2' | '0.3';
+type Manifest = ManifestV02 | ManifestV03;  // discriminated union on pmem.schema_version
+
+interface ManifestBase { /* 共享字段 */ }
+interface ManifestV02 extends ManifestBase { pmem: { schema_version: '0.2' }; indexes: ManifestIndexes; }
+interface ManifestV03 extends ManifestBase { pmem: { schema_version: '0.3' }; runtime; rebuild; cli; embedding; serve; }
+```
+
+严禁 `as any` 绕过类型检查。迁移函数返回 `ManifestV03`。
+
+---
+
+## 六、命令行完整参考（15 命令）
+
+```bash
+# 初始化
+pmem init [project-name] [--guided]
+
+# 内存查询
+pmem recall [--budget N] [--format compact|json|paths|pack]
+pmem ask <query> [--format compact|json|paths|pack]
+pmem related <id> [--depth N] [--type depends_on|related_to|...]
+pmem trace <id>
+
+# 变更感知（v0.4 新增）
+pmem status [--since <timestamp>] [--format compact|json]
+
+# 工作流（v0.4 增强）
+pmem mark-dirty [-r <reason>] [--auto]
+pmem update [--auto|--suggest|--apply-suggestion <id>|--confirm|--force] [-s <summary>] [-n <next>] [--format compact|json]
+
+# 蒸馏（v0.4 增强）
+pmem distill [--suggest|--apply-suggestion <id>|--confirm|--suggest-splits]
+
+# 维护
+pmem rebuild [--changed|--full|--card <id>]
+pmem verify [--fix]
+pmem migrate --to 0.3 [--dry-run] [--backup]
+
+# 会话（v0.3 P1 完成，v0.4 增强汇总）
+pmem session start [-a <agent-name>]
+pmem session end [-s <summary>]
+
+# 框架集成
+pmem integration list|install <framework>|verify
+```
+
+---
+
+## 七、测试基础设施
+
+```
+npm test  # node --require ts-node/register --test src/core/*.test.ts
+```
+
+| 文件 | 用例数 | 覆盖 |
+|------|--------|------|
+| [src/core/yaml.test.ts](src/core/yaml.test.ts) | 21 | parseYamlValue/parseSimpleYaml/parseFrontmatter |
+| [src/core/manifest.test.ts](src/core/manifest.test.ts) | 21 | getDefaultManifest/getDefaultManifestV03 全字段 |
+| [src/core/db.test.ts](src/core/db.test.ts) | 22 | 10 表 schema + CRUD + dirty/session/update_log |
+| [src/core/hash.test.ts](src/core/hash.test.ts) | 16 | computeHash/computeCardHashes/tokenCount/sectionCount |
+| **合计** | **88** | **0 失败** |
+
+### E2E 测试流程
+
+```bash
+cd temp && rm -rf v04-test && mkdir v04-test && cd v04-test
+
+# 初始化 + 创建卡片
+npx ts-node ../../src/index.ts init v04-test
+mkdir -p .pmem/modules .pmem/decisions .pmem/traces
+# ... 写入测试卡片（含 YAML frontmatter）...
+
+# 核心链路
+npx ts-node ../../src/index.ts rebuild
+npx ts-node ../../src/index.ts recall --format compact --budget 2000
+npx ts-node ../../src/index.ts ask "关键词" --format json
+npx ts-node ../../src/index.ts related <card_id> --depth 2
+npx ts-node ../../src/index.ts trace <card_id>
+
+# Workflow 闭环
+npx ts-node ../../src/index.ts session start -a "test"
+npx ts-node ../../src/index.ts status --format json
+npx ts-node ../../src/index.ts mark-dirty -r "test" --auto
+npx ts-node ../../src/index.ts update --suggest --format json
+npx ts-node ../../src/index.ts update --confirm -s "summary" -n "next"
+npx ts-node ../../src/index.ts distill --suggest
+npx ts-node ../../src/index.ts session end -s "test complete"
+npx ts-node ../../src/index.ts verify
+```
+
+---
+
+## 八、v0.5 路线图（接班人方向）
+
+### v0.5 目标：上线可用 Beta
+
+v0.4 完成了 Agent workflow 闭环。v0.5 应聚焦"真实可用性"：
+
+**建议优先级：**
+
+| 优先级 | 方向 | 说明 |
+|--------|------|------|
+| P0 | 实战打磨 | 在真实项目中使用 pmem，收集 ask/recall 不准、status 误报、建议噪音等案例 |
+| P0 | 性能优化 | 大项目（100+ cards）的 rebuild 和 ask 性能 |
+| P0 | 错误处理 | 完善 corner case 处理（DB 损坏、并发的 pmem 实例、空项目） |
+| P1 | embedding ? | 基于收集的召回不准案例判断是否接入 embedding，以及 provider 选型 |
+| P1 | `pmem serve` ? | 如果 Agent 不能运行 shell 的需求明确，再考虑 |
+| P2 | npm 发布 | `npm publish` 为可全局安装的 CLI |
+
+### v0.4 明确推迟到 v0.5+ 的
+
+- embedding 真接入（API 或 local）
+- pmem serve（MCP/REST/daemon）
+- Graph UI
+- 多用户远程服务
+- npm 包发布
+
+### 开工建议
+
+1. 先读 `docs/v0.4 pre-design.md` — 了解 v0.4 设计意图
+2. 在真实项目中使用 pmem — 积累 1-2 周的使用反馈
+3. 基于反馈写 `docs/v0.5 pre-design.md`
+4. 不急于堆功能，先打磨可用性
+
+---
+
+## 九、常见陷阱
+
+### 1. Markdown 是唯一主数据
+SQLite 中 `is_deleted` / `is_candidate` 只是标记。所有卡片必须对应 .md 文件。不要创建"数据库独有"的卡片。
+
+### 2. 不要修改 SQLite 直接
+修改记忆流程：编辑 .md 文件 → `pmem rebuild --changed`。不要写代码直接 UPDATE SQLite。
+
+### 3. Hash 不是 timestamp
+增量 rebuild 用 content hash（SHA-256），不用 mtime。git checkout 会改变 mtime 但不改变内容。
+
+### 4. FTS5 可能不可用
+`hasFTS5(db)` 检查后降级到 `LIKE` 查询。不要假设 FTS5 一定存在。
+
+### 5. Manifest 是 discriminated union
+`Manifest = ManifestV02 | ManifestV03`。访问版本特有字段前必须 narrow：`if (manifest.pmem.schema_version === '0.3')`。
+
+### 6. 退出码不要吞掉
+`pmem update --suggest` 和 `pmem distill --suggest` 的退出码是 Agent 决策依据。`process.exit(1)` = 有建议待处理，不是错误。
+
+### 7. status 依赖 git
+`pmem status` 优先用 `git status --porcelain`。非 git 项目自动降级到 mtime。测试时注意：temp/ 子目录不是 git repo，会 fallback 到 mtime。
+
+### 8. DB 不存在时 graceful fallback
+所有需要 SQLite 的命令必须检查 `.pmem/pmem.db` 是否存在。不存在时打印提示（不要 crash），降级到文件操作。
+
+### 9. 事务边界
+先 atomicWrite Markdown → 再 SQLite transaction。不要反过来。Markdown 写入无法回滚，SQLite 可以。
+
+### 10. 不要引入 as any
+manifest 类型系统已建立 discriminated union。新增 manifest 版本时扩展 union，不要绕过。
+
+---
+
+## 十、依赖清单
+
+```json
+{
+  "dependencies": {
+    "better-sqlite3": "^12.10.0",
+    "commander": "^14.0.3",
+    "js-yaml": "^4.1.1"
+  },
+  "devDependencies": {
+    "@types/better-sqlite3": "^7.6.13",
+    "@types/js-yaml": "^4.0.9",
+    "@types/node": "^25.9.1",
+    "ts-node": "^10.9.2",
+    "typescript": "^6.0.3"
+  }
+}
+```
+
+---
+
+## 十一、接班人阅读顺序
+
+1. **CLAUDE.md** — 5 分钟了解项目
+2. **docs/v0.3 pre-design.md** — v0.3 SQLite 架构决策（14 章）
+3. **docs/v0.4 pre-design.md** — v0.4 workflow 决策（12 章）
+4. **docs/handover-v0.4.md** — 本文档
+5. **src/types.ts** — 类型系统（特别注意 Manifest discriminated union）
+6. **src/core/db.ts** — SQLite schema 和 CRUD 辅助函数
+7. **src/commands/update.ts** — v0.4 最复杂的命令（suggest 引擎）
+8. **src/commands/status.ts** — v0.4 新增命令（三级匹配）
+
+然后在 `temp/` 中跑一次完整 E2E 测试，建立肌肉记忆。

package/docs/prd.md

@@ -0,0 +1,318 @@
+# pmem — Product Requirements Document
+
+## 一、产品概述
+
+### 1.1 产品名称
+
+**pmem**（Project Memory for Agents）
+
+备选：GraphMemo / PGM / Agent Project Memory
+
+### 1.2 一句话描述
+
+面向 AI 编码 Agent 的低 token、可溯源、图结构项目记忆协议与 CLI 运行时。
+
+### 1.3 产品定位
+
+pmem 不是知识库，不是文档系统，不是代码扫描器。它是一个**项目记忆运行时**：
+
+```
+传统：Agent → 读代码/文档 → 自己总结 → 高 token、不稳定
+pmem：Agent → 读 .pmem/index.md → 按需查图谱 → 回写记忆 → 低 token、可溯源
+```
+
+### 1.4 核心价值主张
+
+让任何 AI coding agent 进入项目时，以最少 token 获得三件事：
+1. **我在哪个项目里？**（项目名、阶段、当前关注点）
+2. **当前项目状态是什么？**（模块状态、活跃任务、最近决策）
+3. **下一步最应该做什么？为什么？证据在哪？**（next step + 溯源链）
+
+---
+
+## 二、目标用户
+
+### 2.1 主要用户
+
+| 用户 | 场景 | 核心需求 |
+|------|------|---------|
+| AI Coding Agent（Claude Code、Cursor、Codex 等） | 进入项目开始工作 | 快速恢复上下文，找到相关记忆，知道下一步做什么 |
+| 个人开发者 | 自己用 AI 辅助开发 | 让 Agent 记住项目演进过程，避免反复解释 |
+| 小型开发团队 | 多人 + 多 Agent 协作 | 共享项目记忆，决策可溯源 |
+
+### 2.2 用户痛点
+
+| 痛点 | pmem 解法 |
+|------|----------|
+| Agent 每次都要重新理解项目 → token 浪费 | `pmem recall --budget 2000` |
+| Agent 容易推翻之前决策 | `decisions/` + `pmem trace` |
+| Agent 不知道下一步做什么 | `pmem next` |
+| 项目长期演进后记忆丢失 | `.pmem/traces/` + `pmem distill` |
+| 不同 Agent 框架接入方式不统一 | `integrations/` + `AGENTS.md` |
+| 记忆过时无人发现 | `pmem verify` + freshness detection |
+
+---
+
+## 三、核心协议
+
+### 3.1 记忆存储层级
+
+```
+Hot Memory（每次必读）：
+  .pmem/index.md + state.md + next.md
+  ～1000–2000 tokens
+
+Warm Memory（按需读取）：
+  .pmem/modules/ + decisions/ + tasks/
+  按任务类型召回
+
+Cold Memory（溯源用）：
+  .pmem/traces/ + summaries/
+  不默认读取
+```
+
+### 3.2 数据模型
+
+**节点类型：** project | module | feature | task | decision | risk | assumption | constraint | trace
+
+**边类型：** depends_on | blocks | implements | constrains | decided_by | derived_from | related_to | supersedes | conflicts_with | next_step_of
+
+**核心原则：** Markdown 记忆卡片是单一真相来源，JSON/SQLite 索引是派生缓存。
+
+### 3.3 记忆卡片格式
+
+每张卡片 = YAML frontmatter（机器可读 metadata）+ Markdown 正文（人类和 Agent 可读）
+
+```md
+---
+id: module.backtest_sandbox
+type: module
+schema_version: "0.2"
+status: designing
+tags: [backtest, agent]
+aliases: [回测沙盒]
+depends_on: [module.market_data]
+related: [decision.agent_tool_boundary]
+updated: 2026-05-20
+---
+
+# Backtest Sandbox
+
+## One-liner
+...
+```
+
+---
+
+## 四、功能需求
+
+### 4.1 v0.1 — 核心闭环 ✅
+
+| 需求 | 优先级 | 状态 |
+|------|--------|------|
+| 项目初始化（`pmem init`） | P0 | ✅ |
+| 图索引构建（`pmem rebuild`） | P0 | ✅ |
+| 项目回忆（`pmem recall --budget N`） | P0 | ✅ |
+| 图引导召回（`pmem ask`） | P0 | ✅ |
+| 图谱查询（`pmem related`） | P0 | ✅ |
+| 溯源追踪（`pmem trace`） | P0 | ✅ |
+| 一致性检查（`pmem verify`） | P0 | ✅ |
+| 记忆更新（`pmem update` 四级） | P0 | ✅ |
+| 脏标记（`pmem mark-dirty`） | P0 | ✅ |
+| 框架适配（`pmem integration`） | P1 | ✅ |
+
+### 4.2 v0.2 — 文件模式可信
+
+| 需求 | 优先级 | 说明 |
+|------|--------|------|
+| 交互式冷启动（`pmem init --guided`） | P0 | 问 3 个必填字段，生成可用初始记忆 |
+| 保守项目扫描 + candidates | P0 | 扫描不自动确认，候选进入 `candidates/` |
+| `memory_incomplete` 降级模式 | P0 | 空 pmem 时明确告知 Agent 记忆不完整 |
+| schema 版本管理 | P0 | manifest + 每张卡片带 `schema_version` |
+| 迁移命令（`pmem migrate`） | P0 | dry-run + 执行 + 自动备份 |
+| 版本兼容检查（`pmem verify` 增强） | P0 | CLI vs 项目 schema 版本对比 |
+| atomic write | P0 | .tmp → fsync → rename，防止半写损坏 |
+| 简单 file lock | P0 | `.pmem/.lock`，超时 3s，默认 abort |
+| `memory_status` 追踪 | P1 | completeness + initialized_mode 字段 |
+| card_policy 校验 | P1 | ID 命名规范 + 大小阈值 + verify 警告 |
+| trace → card 蒸馏（`pmem distill` 初版） | P1 | 建议模式，需确认，不自动写 |
+| 卡片拆分建议（`pmem distill --suggest-splits`） | P1 | 检测过大卡片，建议拆分 |
+| 声明式初始化（`pmem init --from`） | P2 | 可延后 |
+| section-level merge（`pmem update --merge`） | P2 | 可延后 |
+| 完整乐观锁 + card_hashes.json | 不做 | 留给 v0.3 SQLite |
+
+### 4.3 v0.3 — SQLite 运行时
+
+| 需求 | 优先级 | 说明 |
+|------|--------|------|
+| SQLite 数据库（`.pmem/pmem.db`） | P0 | 存 cards、edges、aliases、tags、tasks、traces、sessions、dirty_flags、update_log |
+| SQL-backed recall / ask / related | P0 | 替代 JSON 遍历 |
+| transaction-based update | P0 | 原子写入卡片 + 索引 |
+| 乐观锁（SQLite 层） | P0 | 替代 card_hashes.json |
+| incremental rebuild | P1 | 只重建变更部分 |
+| `pmem serve` 原型 | P1 | HTTP API |
+| semantic search / embeddings | P2 | 可选 |
+
+### 4.4 v0.4 — Agent 集成 & 自动化
+
+| 需求 | 优先级 | 说明 |
+|------|--------|------|
+| Claude Code hooks 模板 | P0 | PostToolUse / Stop hooks |
+| Cursor rules 完整版 | P0 | `.cursor/rules/pmem.mdc` |
+| Codex / OpenClaw 适配 | P1 | AGENTS.md / skill 模板 |
+| `pmem update --auto --mode=suggest` 增强 | P0 | 智能变更检测 |
+| session tracking | P1 | Agent 会话起止 + 操作摘要 |
+| distill 工作流优化 | P1 | 定期自动建议蒸馏 |
+| stale memory detection | P1 | 基于 source_files 变更 |
+
+### 4.5 v0.5 — 可上线 Beta
+
+| 需求 | 优先级 | 说明 |
+|------|--------|------|
+| `npm install -g pmem` 一键安装 | P0 | |
+| SQLite 默认开启 | P0 | 新项目默认 SQLite，文件模式兼容 |
+| 完整体验的 `pmem init --guided` | P0 | 引导 → 首个项目跑通 |
+| 完整使用文档 | P0 | 使用指南 + CLI 参考 + 集成教程 |
+| demo 项目 | P0 | 开箱即用示例 |
+| `pmem backup` / `pmem restore` | P1 | |
+| 可选遥测 | P2 | opt-in |
+
+---
+
+## 五、技术架构
+
+### 5.1 技术栈
+
+| 层次 | v0.1–v0.2 | v0.3+ |
+|------|-----------|-------|
+| 语言 | TypeScript (strict) | TypeScript (strict) |
+| CLI 框架 | Commander | Commander |
+| 主数据存储 | Markdown + YAML frontmatter（文件系统） | 同左 |
+| 索引存储 | JSON files | SQLite |
+| 运行环境 | Node.js ≥18 | Node.js ≥18 |
+
+### 5.2 项目记忆目录结构
+
+```
+.pmem/
+  manifest.yml                 # 配置中心
+  index.md / state.md / next.md  # Hot Memory
+  modules/ / features/ / decisions/ / tasks/ / traces/ / risks/  # 记忆卡片
+  candidates/                  # 冷启动扫描候选（v0.2+）
+  indexes/                     # 派生索引（v0.2 JSON → v0.3 SQLite）
+  skills/                      # Agent 操作手册
+  integrations/                # 框架适配模板
+  backups/ / migrations/       # 迁移基础设施（v0.2+）
+  pmem.db                      # SQLite 数据库（v0.3+）
+```
+
+### 5.3 CLI 命令全集
+
+```
+pmem init [--guided] [--from <file>]
+pmem recall [--budget <tokens>]
+pmem next
+pmem ask <query>
+pmem related <id>
+pmem trace <id>
+pmem update [--auto|--confirm|--force]
+pmem mark-dirty [--reason <reason>]
+pmem rebuild
+pmem verify [--fix] [--report]
+pmem distill [--suggest-splits]
+pmem migrate [--dry-run] [--to <version>] [--backup]
+pmem integration [list|install|verify] [<framework>]
+pmem lock status
+pmem backup
+pmem restore
+pmem serve                 # v0.3+
+```
+
+---
+
+## 六、关键设计原则
+
+1. **Markdown 是主数据，索引是缓存。** 索引随时可重建。
+2. **召回必须可解释。** `pmem ask` 输出必须标注匹配路径（exact / alias / graph / fallback）。
+3. **更新分级，不无脑写。** mark-dirty → auto → confirm → force。
+4. **版本可迁移。** schema_version 从 v0.2 开始强制执行。
+5. **文件不写坏。** atomic write 从 v0.2 开始强制执行。
+6. **AGENTS.md 是入口，skills/ 是流程，integrations/ 是适配器。**
+7. **模块粒度以概念/责任边界为主，代码目录为辅。**
+
+---
+
+## 七、成功指标
+
+### v0.2 完成标准
+
+- [ ] `pmem init --guided` 能在 3 个问答内让 Agent 获得可用的初始上下文
+- [ ] v0.1 项目能通过 `pmem migrate --to 0.2` 完成迁移
+- [ ] `pmem verify` 能检测 schema_version 不匹配和 card_policy 违规
+- [ ] 并发写入时不会损坏文件（lock abort + atomic write）
+- [ ] distill 能正确建议将 trace 蒸馏到已有 card
+
+### v0.5 完成标准
+
+- [ ] 新用户能在 2 分钟内完成 `npm install -g pmem` + `pmem init --guided`
+- [ ] 已有 v0.1/v0.2 项目能平滑迁移至 v0.5
+- [ ] Claude Code / Cursor 用户能通过 integration 模板一键接入
+- [ ] Agent 首次进入项目时 token 消耗 ≤ 2000（recall --budget 2000）
+- [ ] `pmem ask` 召回命中率 ≥ 70%（在 50+ 张卡片的项目中）
+
+---
+
+## 八、竞争与差异化
+
+| 方案 | 问题 |
+|------|------|
+| 让 Agent 读 README / docs | token 大、不稳定 |
+| 让 Agent 读代码 | 无上下文，容易误解 |
+| 通用知识库 | 不是为 Agent 设计的，token 不可控 |
+| Cursor Rules / CLAUDE.md | 只有静态指令，无图记忆、无溯源、不更新 |
+| **pmem** | **图记忆 + token 预算 + 溯源 + 可更新 + 跨 Agent** |
+
+核心差异：pmem 不是"更好的文档"，而是"Agent 的项目记忆运行时"。
+
+---
+
+## 九、风险与缓解
+
+| 风险 | 影响 | 缓解措施 |
+|------|------|---------|
+| 记忆过时 | Agent 基于旧事实做错决策 | freshness TTL + source_files 变更检测 + verify |
+| 记忆噪音 | traces 过多，淹没信号 | trace 写入门槛 + distill 压缩 |
+| 维护成本高 | 用户不更新记忆卡 | guided init + distill 建议 + mark-dirty 提醒 |
+| Agent 不主动用 pmem | 工具被闲置 | AGENTS.md + hooks + integration 模板降低接入成本 |
+| 跨版本迁移出错 | 用户项目记忆损坏 | dry-run + 自动备份 + 官方迁移规则内置 |
+| SQLite 锁定用户 | 无法再编辑 .md 文件 | Markdown 永久保留为 canonical 主数据 |
+
+---
+
+## 十、未决事项
+
+以下问题待后续版本讨论和决策：
+
+### 技术
+
+- [ ] v0.3 SQLite schema 详细设计（表结构、索引策略、迁移脚本）
+- [ ] `pmem serve` 选择 MCP Server 还是 REST API，还是两者都做？
+- [ ] embeddings 选型（本地模型 vs API？哪种最适合代码项目语义？）
+- [ ] graph 分片策略——按模块？按类型？混合？
+- [ ] incremental rebuild 的实现策略
+
+### 产品
+
+- [ ] 多项目 / monorepo / workspace 支持方案
+- [ ] 记忆共享与多人协作机制
+- [ ] 记忆权限模型（谁能读/写哪些卡片）
+- [ ] npm 包发布策略（何时第一次 publish？scope？）
+- [ ] 是否需要 VS Code / JetBrains 插件？
+- [ ] telemetry 的范围、隐私策略、opt-in 机制
+
+### 业务
+
+- [ ] 开源协议（MIT？Apache 2.0？）
+- [ ] 社区治理模型
+- [ ] 文档站点与教程
+- [ ] 是否需要一个"pmem registry"让团队共享记忆模板？