pmem-ai 0.5.0

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

@@ -0,0 +1,686 @@
+# v0.3 前置设计决策
+
+本文档记录 pmem v0.3 开工前的最终技术决策。v0.3 的核心定位：
+
+> **SQLite-backed Agent CLI Runtime**
+>
+> 不是 SQLite 主数据化系统，不是 MCP-first Memory Server，不是 REST-first Memory Service。
+> 而是：Markdown 主数据 + SQLite 运行时索引 + Agent-first CLI + Skills 使用协议 + Content Hash 增量 rebuild + 可解释召回。
+
+---
+
+## 一、SQLite Schema 设计
+
+### 核心原则
+
+SQLite 的职责是：**索引层、查询层、运行时状态层、会话状态层、缓存层**。不是主数据层。
+
+### P0 表结构（必须实现）
+
+#### `cards` — 卡片索引
+
+```sql
+CREATE TABLE cards (
+  id TEXT PRIMARY KEY,
+  type TEXT NOT NULL,
+  title TEXT NOT NULL,
+  status TEXT,
+  priority TEXT,
+  file_path TEXT NOT NULL UNIQUE,
+
+  summary TEXT,
+  schema_version TEXT,
+  card_version INTEGER DEFAULT 1,
+
+  created_at TEXT,
+  updated_at TEXT,
+  last_verified_at TEXT,
+
+  file_hash TEXT NOT NULL,
+  frontmatter_hash TEXT NOT NULL,
+  body_hash TEXT NOT NULL,
+
+  token_count INTEGER DEFAULT 0,
+  section_count INTEGER DEFAULT 0,
+
+  is_deleted INTEGER DEFAULT 0,
+  is_candidate INTEGER DEFAULT 0
+);
+```
+
+#### `edges` — 图关系
+
+```sql
+CREATE TABLE edges (
+  id INTEGER PRIMARY KEY AUTOINCREMENT,
+  from_id TEXT NOT NULL,
+  to_id TEXT NOT NULL,
+  type TEXT NOT NULL,
+
+  source TEXT NOT NULL,    -- explicit | inferred | mention
+  confidence REAL DEFAULT 1.0,
+
+  created_at TEXT,
+  updated_at TEXT,
+
+  UNIQUE(from_id, to_id, type, source)
+);
+```
+
+v0.3 暂时不生成 `same_tag` 弱关系边。
+
+#### `aliases` — 别名
+
+```sql
+CREATE TABLE aliases (
+  id INTEGER PRIMARY KEY AUTOINCREMENT,
+  card_id TEXT NOT NULL,
+  alias TEXT NOT NULL,
+  normalized_alias TEXT NOT NULL,
+  language TEXT,
+  UNIQUE(card_id, normalized_alias)
+);
+```
+
+#### `tags` — 标签
+
+```sql
+CREATE TABLE tags (
+  id INTEGER PRIMARY KEY AUTOINCREMENT,
+  card_id TEXT NOT NULL,
+  tag TEXT NOT NULL,
+  normalized_tag TEXT NOT NULL,
+  UNIQUE(card_id, normalized_tag)
+);
+```
+
+#### `paths` — 代码/文档路径关联
+
+```sql
+CREATE TABLE paths (
+  id INTEGER PRIMARY KEY AUTOINCREMENT,
+  card_id TEXT NOT NULL,
+  path TEXT NOT NULL,
+  relation TEXT NOT NULL,  -- source_path | test_path | doc_path | config_path
+  UNIQUE(card_id, path, relation)
+);
+```
+
+对 stale detection 非常关键。
+
+#### `dirty_flags` — 脏状态
+
+```sql
+CREATE TABLE dirty_flags (
+  id INTEGER PRIMARY KEY AUTOINCREMENT,
+  scope TEXT NOT NULL,
+  target TEXT NOT NULL,
+  reason TEXT NOT NULL,
+  created_at TEXT NOT NULL,
+  resolved_at TEXT,
+  session_id TEXT
+);
+```
+
+#### `schema_meta` — 数据库元信息
+
+```sql
+CREATE TABLE schema_meta (
+  key TEXT PRIMARY KEY,
+  value TEXT NOT NULL
+);
+```
+
+### P1 表结构（强烈建议）
+
+#### `sessions`
+
+```sql
+CREATE TABLE sessions (
+  id TEXT PRIMARY KEY,
+  agent_name TEXT,
+  started_at TEXT NOT NULL,
+  ended_at TEXT,
+  task_summary TEXT,
+  base_index_hash TEXT,
+  status TEXT,
+  dirty INTEGER DEFAULT 0
+);
+```
+
+#### `update_log`
+
+```sql
+CREATE TABLE update_log (
+  id INTEGER PRIMARY KEY AUTOINCREMENT,
+  action TEXT NOT NULL,
+  summary TEXT,
+  session_id TEXT,
+  created_at TEXT NOT NULL,
+  affected_cards TEXT,
+  affected_paths TEXT,
+  success INTEGER NOT NULL,
+  error TEXT
+);
+```
+
+#### `card_fts` — FTS5 全文检索（如环境支持）
+
+```sql
+CREATE VIRTUAL TABLE card_fts USING fts5(
+  card_id UNINDEXED,
+  title,
+  summary,
+  body,
+  aliases,
+  tags
+);
+```
+
+FTS5 是 v0.3 `ask` 升级的重要基础。
+
+### P2 暂缓
+
+embeddings 真向量检索、SQLite-only memory card、复杂 section-level merge、图可视化、远程多用户服务。这些留给 v0.4。
+
+---
+
+## 二、Markdown 主数据策略
+
+### 最终决策
+
+> **Markdown cards 继续作为唯一主数据，SQLite 只是索引、缓存和运行时状态。**
+
+```
+.pmem/**/*.md      canonical source of truth
+.pmem/pmem.db      generated runtime index/cache/state
+```
+
+### 为什么不让 SQLite 存主数据？
+
+pmem 核心价值：人类可读、Git 友好、可 diff、可手动修复、可迁移、不被数据库锁死。
+
+### 正文缓存（可选）
+
+```sql
+CREATE TABLE card_content_cache (
+  card_id TEXT PRIMARY KEY,
+  file_path TEXT NOT NULL,
+  body TEXT,
+  body_hash TEXT NOT NULL,
+  extracted_summary TEXT,
+  updated_at TEXT
+);
+```
+
+用途：FTS 检索、快速 recall/ask、distill 分组、减少重复读 Markdown。但一致性规则：Markdown 改了 → cache 重建，永不手修 cache。
+
+### 数据一致性模型
+
+```
+写入路径：
+pmem update / distill / migrate
+→ 写 Markdown（atomicWrite）
+→ 更新 SQLite（transaction）
+
+读取路径：
+pmem recall / ask / related / trace
+→ 读 SQLite
+→ 如果 SQLite 过期，提示或自动 rebuild
+```
+
+核心原则：Markdown 是事实，SQLite 是索引，SQLite 可以丢，Markdown 不能乱。
+
+---
+
+## 三、`pmem serve` 架构方向
+
+### 最终决策
+
+> **v0.3 不做 MCP-first，也不做 REST-first。主线是 Agent-first CLI + Skills。**
+
+`pmem serve` 不进入 P0。CLI 对比 MCP/REST 的优势：低 token、简单可组合、无需 server 生命周期、适合任意 coding agent、容易集成到 AGENTS.md / CLAUDE.md。
+
+如需 serve，仅作 experimental：
+
+```bash
+pmem serve --mcp --experimental
+pmem serve --rest --experimental
+```
+
+### CLI 输出协议（P0）
+
+所有核心查询命令支持：
+
+```bash
+--format compact    # Agent 低 token 直接阅读
+--format json       # Agent 程序化处理
+--format paths      # 只返回文件路径，极低 token
+--format pack       # 受 token budget 控制的上下文包
+```
+
+`--format compact` 示例：
+
+```txt
+PROJECT: pmem
+STAGE: v0.3 planning
+FOCUS: SQLite-backed Agent CLI Runtime
+
+NEXT:
+- Implement SQLite schema
+- Migrate JSON indexes to SQLite
+
+READ_IF_NEEDED:
+- .pmem/modules/sqlite_runtime.md
+- .pmem/decisions/markdown-source-of-truth.md
+```
+
+`--format json` 示例：
+
+```json
+{
+  "query": "SQLite schema 怎么设计",
+  "matched": [
+    {"id": "module.sqlite_runtime", "match_type": "alias", "score": 1.0, "file": ".pmem/modules/sqlite_runtime.md"}
+  ],
+  "expanded": [
+    {"id": "decision.markdown_source_of_truth", "edge": "constrains", "file": ".pmem/decisions/markdown-source-of-truth.md"}
+  ],
+  "recommended_files": [
+    ".pmem/modules/sqlite_runtime.md",
+    ".pmem/decisions/markdown-source-of-truth.md"
+  ]
+}
+```
+
+`--format paths` 示例：
+
+```txt
+.pmem/modules/distill_runtime.md
+.pmem/skills/distill.md
+.pmem/decisions/trace-distillation-policy.md
+```
+
+---
+
+## 四、增量 Rebuild 策略
+
+### 最终决策
+
+> **以 content hash 为准，timestamp 只作为预筛。不用 timestamp 作为一致性依据。**
+
+原因：git checkout 影响 mtime、复制文件改变 mtime、编辑器保存但内容未变、系统时间不准。
+
+### Hash 设计
+
+每张 card 计算三个 hash：
+
+```
+file_hash          整个 Markdown 文件
+frontmatter_hash   frontmatter 部分
+body_hash          正文部分
+```
+
+用途：
+- `file_hash` 变化 → 文件整体变化
+- `frontmatter_hash` 变化 → 更新 cards / edges / aliases / tags / paths
+- `body_hash` 变化 → 更新 FTS / summary / token_count / section_count
+
+### Rebuild 命令
+
+```bash
+pmem rebuild               # 默认增量（--changed）
+pmem rebuild --changed     # hash 相同跳过，hash 不同重解析
+pmem rebuild --full        # 清空 SQLite 后全量重建
+pmem rebuild --card <id>   # 只重建单张 card
+```
+
+### verify 与 rebuild 关系
+
+`pmem verify` 检查 SQLite 是否与 Markdown 一致。不一致时：不手修 SQLite，运行 `pmem rebuild`。`pmem verify --fix` = `pmem rebuild --changed` + `pmem verify`。
+
+---
+
+## 五、Embeddings 选型
+
+### 最终决策
+
+> **v0.3 不强绑定 embedding，不默认启用。只设计 Embedding Provider Interface。**
+
+三种模式预留：`none | api | local`。默认 `none`。
+
+原因：v0.3 主线是 SQLite runtime + CLI output contract + hash rebuild + migrate。embedding 引入模型选择、API key、向量维度、成本、隐私等额外复杂度。
+
+### v0.3 的 ask 召回顺序
+
+```
+1. exact match：id / title / alias
+2. graph expansion：related / depends_on / constrains / next_step_of
+3. FTS keyword match（SQLite FTS5）
+4. optional embedding semantic match（默认关闭）
+5. rerank：match_type + graph_distance + priority + freshness
+```
+
+核心原则：pmem 是项目记忆系统，不是普通文档搜索系统。**图关系优先于语义猜测。**
+
+### 配置预留
+
+```yml
+embedding:
+  enabled: false
+  provider: none
+  model: null
+  dimension: null
+  store: sqlite
+  index: none
+```
+
+---
+
+## 六、File Lock + AtomicWrite 与 SQLite 事务共存
+
+### 最终决策
+
+> **两者保留，职责不同。File lock 保护 Markdown 文件写入，SQLite transaction 保护数据库索引和状态更新。**
+
+### v0.3 写入流程
+
+```
+1. acquire global pmem write lock
+2. prepare update
+3. write Markdown atomically
+4. update SQLite inside transaction
+5. write update_log
+6. release lock
+```
+
+### 为什么仍需要 file lock？
+
+SQLite transaction 只能保护数据库，不能保护 `.md` 文件。两个 Agent 同时写同一张 Markdown card，SQLite 无法自动阻止文件层面的覆盖。
+
+### 如果 Markdown 写成功但 SQLite 更新失败？
+
+不是灾难。主数据是 Markdown。处理方式：SQLite 标记 stale → 提示或自动 `pmem rebuild --changed`。原则：Markdown 成功写入后，SQLite 永远可重建。不需要为 SQLite 回滚 Markdown。
+
+### v0.3 并发模型
+
+```
+读操作 → 直接读 SQLite，不加锁
+写操作 → acquire .pmem/.lock → atomicWrite Markdown → SQLite transaction → release lock
+锁超时 → 默认 abort，不排队，不覆盖
+```
+
+v0.3 不追求多写并发，单写模型已足够支撑 v0.5 上线。
+
+---
+
+## 七、v0.2 → v0.3 迁移路径
+
+### 最终决策
+
+> **从 Markdown cards 重建 SQLite，而不是从 JSON indexes 迁移主数据。**
+
+v0.2 的 JSON indexes 本质是缓存，不是事实来源。
+
+### 迁移原则
+
+- Markdown cards 不搬家
+- JSON indexes 不作为主迁移来源
+- SQLite 从 Markdown rebuild
+- 旧 JSON indexes 仅用于校验或备份
+- manifest 增加 `runtime.mode = sqlite`
+
+### dry-run
+
+```bash
+pmem migrate --to 0.3 --dry-run
+```
+
+输出：将创建 .pmem/pmem.db、创建 schema、导入 cards/edges/aliases/tags/paths、构建 FTS、更新 manifest。不删除 Markdown cards，不删除 JSON indexes。
+
+### 正式迁移
+
+```bash
+pmem migrate --to 0.3
+```
+
+执行流程：备份 .pmem → 创建 pmem.db → 创建 schema → 扫描 Markdown → 解析 frontmatter → 写入 tables → 构建 FTS → 校验 hash → 更新 manifest → 标记 legacy JSON indexes → 运行 verify。
+
+### 备份策略
+
+迁移前自动备份到 `.pmem/backups/YYYY-MM-DD-before-v0.3-migration/`。不支持降级 migration，如需回退用备份恢复。
+
+### JSON indexes 处理
+
+迁移后不删除，默认保留。manifest 标记：
+
+```yml
+indexes:
+  primary: sqlite
+  legacy_json:
+    enabled: false
+    retained: true
+    path: ".pmem/indexes"
+```
+
+---
+
+## 八、v0.3 Manifest 最终形态
+
+```yml
+pmem:
+  schema_version: "0.3"
+  protocol_version: "0.3"
+  created_by: "0.2.0"
+  last_migrated_by: "0.3.0"
+
+project:
+  name: ""
+  language: "zh-CN"
+  status: "active"
+
+runtime:
+  mode: sqlite
+  db_path: ".pmem/pmem.db"
+  markdown_source: true
+
+source_of_truth:
+  type: markdown_cards
+  card_globs:
+    - ".pmem/modules/**/*.md"
+    - ".pmem/features/**/*.md"
+    - ".pmem/decisions/**/*.md"
+    - ".pmem/tasks/**/*.md"
+    - ".pmem/traces/**/*.md"
+    - ".pmem/risks/**/*.md"
+
+indexes:
+  primary: sqlite
+  legacy_json:
+    enabled: false
+    retained: true
+    path: ".pmem/indexes"
+
+rebuild:
+  strategy: content_hash
+  hash:
+    file_hash: true
+    frontmatter_hash: true
+    body_hash: true
+
+concurrency:
+  write_lock:
+    enabled: true
+    path: ".pmem/.lock"
+    timeout: "3s"
+    stale_after: "60s"
+    on_timeout: "abort"
+  sqlite_transaction: true
+  atomic_write: true
+
+cli:
+  default_format: compact
+  supported_formats:
+    - compact
+    - json
+    - paths
+    - pack
+  default_budget: 1600
+
+embedding:
+  enabled: false
+  provider: none
+  model: null
+  dimension: null
+  store: sqlite
+  index: none
+
+serve:
+  enabled: false
+  mode: none
+  experimental:
+    mcp: false
+    rest: false
+
+integrations:
+  active: []
+  compatibility: {}
+
+migrations:
+  applied: []
+```
+
+---
+
+## 九、v0.3 命令优先级
+
+### P0 — 必须完成
+
+| 命令 | 说明 |
+|------|------|
+| `pmem rebuild` | 切换到 SQLite-backed，支持 `--changed`/`--full`/`--card` |
+| `pmem recall` | SQLite 查询 + `--format compact/json/paths/pack` |
+| `pmem ask` | SQLite + aliases + FTS + graph expansion + 可解释召回 |
+| `pmem related` | SQL edges 查询 + `--depth` + `--type` |
+| `pmem verify` | SQLite ↔ Markdown 一致性检查 |
+| `pmem migrate --to 0.3 --dry-run` | 预览迁移 |
+| `pmem migrate --to 0.3` | 执行迁移（自动备份） |
+
+所有核心查询命令必须支持 `--format` 和 `--budget`。
+
+### P1 — 强烈建议
+
+| 命令 | 说明 |
+|------|------|
+| `pmem trace` | SQLite-backed 溯源 |
+| `pmem distill` | SQLite-backed 蒸馏分组 |
+| `pmem mark-dirty` | 写入 dirty_flags table |
+| `pmem session start/end` | 会话追踪 |
+| FTS5 全文检索 | card_fts 表 |
+| Integration 模板更新 | Claude Code / Cursor / Codex |
+
+### P2 — 推迟
+
+| 功能 | 目标版本 |
+|------|---------|
+| embedding 真接入 | v0.4 |
+| Graph UI | v0.4+ |
+| 多用户远程服务 | v0.5+ |
+| SQLite-only card | 不做 |
+| 复杂 merge | v0.4+ |
+
+---
+
+## 十、v0.3 的 ask / recall / related 工作方式
+
+### `pmem recall`
+
+目标：快速恢复项目状态。
+
+数据来源：SQLite cards + state/next cards + recent update_log + dirty_flags。
+
+输出：项目是什么、当前阶段、当前焦点、下一步、可能过期的记忆、建议读取的文件。
+
+### `pmem ask`
+
+目标：根据问题返回可解释召回包。
+
+```
+1. normalize query
+2. exact id/title/alias match（SQLite）
+3. graph expansion（edges table）
+4. FTS keyword match（card_fts）
+5. optional embedding（默认关闭）
+6. rerank：match_type + graph_distance + priority + freshness
+7. output context pack / paths / json / compact
+```
+
+输出必须包含 matched nodes、match_type、expanded nodes、recommended files、evidence paths。不要把 `pmem ask` 做成黑盒聊天机器人。它是**可解释召回器**。
+
+### `pmem related`
+
+目标：查询图邻居。数据来源：edges + cards + aliases + tags + paths。
+
+```bash
+pmem related module.agent_runtime
+pmem related module.agent_runtime --depth 2
+pmem related module.agent_runtime --type depends_on
+```
+
+---
+
+## 十一、v0.3 最终决策表
+
+| 问题 | 最终决策 |
+|------|---------|
+| SQLite schema | P0: cards / edges / aliases / tags / paths / dirty_flags / schema_meta；P1: sessions / update_log / card_fts |
+| Markdown 主数据 | Markdown 是唯一主数据；SQLite 是索引、缓存、运行时状态 |
+| `pmem serve` | 不做 MCP-first；v0.3 主线是 Agent-first CLI + Skills |
+| 增量 rebuild | 基于 content hash；timestamp 只做预筛 |
+| embeddings | v0.3 默认关闭，只设计 provider interface |
+| file lock + SQLite | file lock 保护 Markdown；SQLite transaction 保护 DB；多读单写 |
+| v0.2 → v0.3 migrate | 从 Markdown 重建 SQLite；JSON indexes 只作校验/备份 |
+
+---
+
+## 十二、v0.3 一句话定义
+
+> **pmem v0.3 是一个以 Markdown 为主数据、SQLite 为运行时索引、CLI 为 Agent 操作入口的项目图记忆系统。**
+
+更工程化：
+
+```
+pmem v0.3 =
+  Markdown canonical memory cards
++ SQLite-backed graph/index/runtime
++ content-hash incremental rebuild
++ Agent-first CLI output contract
++ skills-based usage protocol
+```
+
+## 十三、核心开发链路
+
+v0.3 不要扩散方向。优先跑通这条链路：
+
+```
+Markdown cards
+→ pmem migrate
+→ SQLite index
+→ pmem rebuild
+→ pmem recall
+→ pmem ask
+→ pmem related
+→ compact/json/paths/pack 输出
+→ Agent 根据输出按需读取
+```
+
+这条链路跑通，v0.3 就成功了。
+
+## 十四、v0.3 → v0.5 路线
+
+| 版本 | 主题 |
+|------|------|
+| v0.2 | 文件模式稳定（防损坏） |
+| v0.3 | SQLite-backed CLI Runtime（强一致） |
+| v0.4 | Agent workflow 自动化 + embedding |
+| v0.5 | 可上线 Beta |