pmem-ai 0.5.0

package/docs/project-roadmap.md

@@ -0,0 +1,279 @@
+# pmem Project Roadmap
+
+## 产品定位
+
+> **面向 AI Agent 的图结构项目记忆运行时。**
+>
+> 一个 CLI 工具 + 文件协议 + 图索引系统，让任意 AI coding agent 以极少 token 恢复项目上下文、查找相关记忆、溯源决策依据、规划下一步、回写记忆。
+
+简称：`pmem`（Project Memory for Agents）
+CLI：`pmem`
+
+---
+
+## 各版本主题
+
+| 版本 | 主题 | 一句话 |
+|------|------|--------|
+| v0.1 | 能用 | 10 个命令跑通核心闭环（init → recall → ask → update → verify） |
+| v0.2 | 文件模式可信 | 防损坏——冷启动不空、并发不丢、卡片不乱、版本可迁 |
+| v0.3 | SQLite 运行时 | 强一致——查询/索引/状态迁入 SQLite，Markdown 仍为主数据 |
+| v0.4 | Agent 集成 & 自动化 | 多框架适配、session 追踪、distill 工作流优化 |
+| v0.5 | 可上线 Beta | 安装体验、文档、稳定 CLI、SQLite 默认开启、demo 项目 |
+
+---
+
+## v0.1 — 能用 ✅ 已完成
+
+**目标：** 跑通核心闭环，证明"文件模式 + 图索引 + CLI"可行。
+
+**已实现：**
+
+| 命令 | 功能 |
+|------|------|
+| `pmem init` | 生成 .pmem/ 骨架 + manifest.yml + AGENTS.md |
+| `pmem rebuild` | .md frontmatter → indexes/graph.json |
+| `pmem recall --budget N` | 三层 token 预算输出 |
+| `pmem ask <query>` | 精确匹配 → 图邻居 → BM25 兜底 |
+| `pmem related <id>` | 图邻居查询 |
+| `pmem trace <id>` | 溯源 + 卡片内容 |
+| `pmem verify --fix` | index 一致性检查 |
+| `pmem update` | 四级更新（mark-dirty / auto / confirm / force） |
+| `pmem mark-dirty` | 脏状态标记 |
+| `pmem integration` | list / install / verify |
+
+**技术栈：** TypeScript + Commander + 文件系统 + frontmatter + JSON graph
+
+**已知限制：**
+- 无并发保护
+- init 只生成空骨架
+- 无卡片粒度约束
+- 无版本迁移能力
+- YAML 解析器为最小实现
+
+---
+
+## v0.2 — 文件模式可信（防损坏）
+
+**主题：** 让 pmem 在纯文件模式下变得**可初始化、可维护、可迁移**，为 v0.3 SQLite 做铺垫。
+
+**不做：** 复杂乐观锁、hash-based merge、card_hashes.json、锁队列。这些留给 v0.3 SQLite。
+
+### P0 — 必须完成
+
+| 功能 | 说明 |
+|------|------|
+| `pmem init --guided` | 交互式冷启动，问 3 个必填（项目描述、阶段、下一步） |
+| `pmem init` 增强 | 保守扫描 → `candidates/` → 标记 `memory_incomplete` |
+| `pmem migrate --dry-run` | 预览迁移变更 |
+| `pmem migrate --to 0.2` | 执行迁移（带自动备份到 `backups/`） |
+| `pmem rebuild` 增强 | 支持 v0.2 manifest 新字段 |
+| `pmem verify` 增强 | 检查 schema_version、card_policy 违规 |
+| `pmem mark-dirty` 增强 | 更新 `memory_status.dirty` |
+| atomic write | 所有写入：.tmp → fsync → rename |
+| 简单 file lock | `.pmem/.lock`，超时 3s，默认 abort |
+| manifest schema_version | `pmem.schema_version: "0.2"`，每张卡片也带 |
+
+### P1 — 强烈建议
+
+| 功能 | 说明 |
+|------|------|
+| `pmem distill` 初版 | trace → card 蒸馏建议（需确认，不自动写） |
+| `pmem distill --suggest-splits` | 建议拆分过大卡片 |
+| card_policy 校验 | ID 命名规范 + 大小阈值 + verify 警告 |
+| memory_status | `completeness` 和 `initialized_mode` 追踪 |
+| integration 模板更新 | Claude Code / Cursor / Codex 适配 |
+
+### P2 — 可延后到 v0.3
+
+| 功能 | 说明 |
+|------|------|
+| 完整乐观锁 / card_hashes.json | 由 SQLite transaction 替代 |
+| `update --merge` | section-level merge |
+| `pmem init --from <file>` | 声明式初始化 |
+| graph 分片存储 | JSON → 多文件索引 |
+| `pmem split --interactive` | 交互式拆分卡片 |
+
+### v0.2 并发策略
+
+```yml
+concurrency:
+  mode: file-basic
+  atomic_write: true
+  lock:
+    enabled: true
+    path: ".pmem/.lock"
+    timeout: "3s"
+    stale_after: "60s"
+    on_timeout: "abort"
+  optimistic_lock:
+    enabled: false
+    note: "Deferred to SQLite runtime in v0.3"
+```
+
+v0.2 并发目标：**文件不写坏、索引可重建、冲突时 abort 不覆盖。**
+
+### v0.2 新增目录
+
+```
+.pmem/
++  candidates/          # 冷启动扫描候选项
++  risks/               # 风险卡片
++  backups/             # 迁移前自动备份
++  migrations/          # 项目自定义迁移（预留）
++  indexes/card_hashes.json  # P2（留给 v0.3）
++  skills/distill.md    # 蒸馏操作手册
+```
+
+---
+
+## v0.3 — SQLite 运行时（强一致）
+
+**主题：** 将查询、索引、状态管理迁入 SQLite。Markdown cards 继续作为 canonical 主数据。
+
+### 核心切换
+
+```
+v0.2:  文件系统 → JSON indexes → CLI 查询
+v0.3:  文件系统 → SQLite indexes → SQL 查询 → CLI
+                    ↑
+              Markdown cards 仍是主数据
+```
+
+### SQLite 存储内容
+
+```txt
+.pmem/pmem.db:
+  cards           # 卡片元数据（id, type, title, status, file_path, hash）
+  edges           # 图边
+  aliases         # 别名索引
+  tags            # 标签索引
+  tasks           # 任务状态
+  traces          # trace 元数据
+  sessions        # agent session 记录
+  dirty_flags     # 脏状态
+  update_log      # 更新日志
+  migrations_log  # 迁移历史
+```
+
+### v0.3 关键能力
+
+| 功能 | 说明 |
+|------|------|
+| SQLite-backed recall | 替代 JSON 遍历 |
+| SQLite-backed ask | JOIN 查询替代内存匹配 |
+| SQLite-backed related | 图邻居 SQL 查询 |
+| transaction-based update | 原子写入卡片 + 索引 |
+| 乐观锁 | 在 SQLite 层实现 version check |
+| incremental rebuild | 只重建变更部分 |
+| card_hashes.json → db | 完整并发语义 |
+| `pmem serve` | HTTP API / MCP Server 原型 |
+
+### v0.3 不做的
+
+- 不把 Markdown 全文存入数据库（保持 Git 友好）
+- 不做 AI embedding / semantic search
+- 不做自动 memory quality scoring
+
+---
+
+## v0.4 — Agent 集成 & 自动化
+
+**主题：** 让不同 Agent 框架真正能稳定接入 pmem，自动化记忆维护流程。
+
+| 功能 | 说明 |
+|------|------|
+| Claude Code hooks | PostToolUse / Stop hooks 模板 |
+| Cursor rules | `.cursor/rules/pmem.mdc` 完整版 |
+| Codex / OpenClaw | AGENTS.md / skill 模板 |
+| `pmem update --auto --mode=suggest` | 智能检测 → 生成更新建议 |
+| session tracking | 记录 Agent 会话起止、操作摘要 |
+| distill 工作流优化 | 定期自动建议蒸馏 |
+| stale memory detection | 基于 `source_files` 变更的过时检测 |
+| integration verify 增强 | 检查各框架 hooks 是否正确安装 |
+
+---
+
+## v0.5 — 可上线 Beta
+
+**主题：** 面向真实用户（开发者 + AI Agent）稳定可用。
+
+| 功能 | 说明 |
+|------|------|
+| CLI 安装体验 | `npm install -g pmem` 一键安装 |
+| `pmem init --guided` 完整体验 | 引导式初始化 → 首个 project 跑通 |
+| SQLite 默认开启 | v0.5 起新项目默认 SQLite |
+| 文件模式兼容 | 已有 v0.1/v0.2 项目仍可用文件模式 |
+| 完整文档 | 使用指南、CLI 参考、集成教程 |
+| demo 项目 | 开箱即用的示例项目 |
+| 回滚 / 备份 | `pmem backup` / `pmem restore` |
+| 基础遥测（可选） | `pmem telemetry` opt-in |
+| 记忆健康仪表板 | `pmem verify --report` |
+
+---
+
+## 版本间迁移路径
+
+```
+v0.1 → v0.2:
+  pmem migrate --to 0.2
+  变更：manifest 加 schema_version + memory_status + card_policy
+       卡片 frontmatter 加 schema_version
+
+v0.2 → v0.3:
+  pmem migrate --to 0.3
+  变更：JSON indexes → SQLite db
+       manifest indexes.mode: sqlite
+       保留 .md 卡片不变
+
+v0.3 → v0.4:
+  pmem migrate --to 0.4
+  变更：新增 sessions table
+       新增 update_log table
+       manifest integrations 扩展
+
+v0.4 → v0.5:
+  pmem migrate --to 0.5
+  变更：SQLite 成为默认
+       文件模式标记为 legacy
+       遥测配置项
+```
+
+每次迁移自动备份到 `.pmem/backups/YYYY-MM-DD-before-vX.Y/`。
+
+---
+
+## 总览
+
+```
+v0.1 ───→ v0.2 ───→ v0.3 ───→ v0.4 ───→ v0.5
+能用      防损坏    强一致    自动化    可上线
+10 cmd    14 cmd    16 cmd    18 cmd    20+ cmd
+文件模式   文件模式   +SQLite   +集成     +体验
+```
+
+---
+
+## 当前状态
+
+- **v0.1:** ✅ 完成（10 个命令实现并测试）
+- **v0.2:** 🔜 设计完成，待开工
+  - 设计决策：`docs/v0.2 pre-design.md`
+  - 架构规划：`docs/v0.2 pre-roadmap.md`
+- **v0.3–v0.5:** 📋 方向确定，详细设计待 v0.2 完成后细化
+
+---
+
+## 未决事项
+
+以下问题留待后续版本讨论：
+
+- v0.3 SQLite schema 详细设计
+- MCP Server vs HTTP API 的选择
+- 多项目 / workspace 支持
+- 记忆共享与协作机制
+- 记忆权限模型
+- 多语言 CLI 支持
+- telemetry 的范围和隐私策略
+- npm 包发布与版本策略
+- 是否支持嵌入到 VS Code / JetBrains 插件

package/docs/release-checklist-v0.5.md

@@ -0,0 +1,109 @@
+# pmem v0.5 Release Checklist
+
+Use this checklist before tagging or publishing v0.5.0.
+
+## Scope Check
+
+- [ ] v0.5 remains Productization Beta only.
+- [ ] No embedding implementation was added.
+- [ ] No `pmem serve`, MCP, REST, Graph UI, telemetry, or remote service work was added.
+- [ ] README, package readiness, E2E, agent docs, and release artifacts are complete.
+
+## Version Check
+
+- [ ] `package.json` version is `0.5.0`.
+- [ ] `package-lock.json` root version is `0.5.0`.
+- [ ] `src/index.ts` Commander version is `0.5.0`.
+- [ ] `CHANGELOG.md` has a `0.5.0` section.
+
+## Documentation Check
+
+- [ ] `README.md` explains why pmem exists.
+- [ ] `README.md` has install instructions.
+- [ ] `README.md` has a 5-minute quick start.
+- [ ] `README.md` documents exit code semantics.
+- [ ] `README.md` documents troubleshooting for missing `.pmem`, missing DB, no ask matches, non-git projects, FTS5 fallback, and dirty flags.
+- [ ] `AGENTS.md` and `CLAUDE.md` match v0.5 scope.
+- [ ] `pmem init` generated integration templates match v0.5 workflow.
+
+## Test Check
+
+Run:
+
+```bash
+npm test
+npm run build
+npm run test:e2e:install
+npm run test:e2e:workflow
+```
+
+Expected:
+
+- [ ] Unit tests pass.
+- [ ] TypeScript build passes.
+- [ ] Install smoke E2E passes.
+- [ ] Real workflow E2E passes.
+
+## Package Check
+
+Run:
+
+```bash
+npm pack --dry-run
+```
+
+Expected:
+
+- [ ] Package name is `pmem`.
+- [ ] Package version is `0.5.0`.
+- [ ] Tarball includes `dist/`.
+- [ ] Tarball includes `README.md`.
+- [ ] Tarball includes `LICENSE`.
+- [ ] Tarball includes top-level `docs/*.md`.
+- [ ] Tarball excludes `src/`.
+- [ ] Tarball excludes `temp/`.
+- [ ] Tarball excludes `.pmem/`.
+- [ ] Tarball excludes `node_modules/`.
+- [ ] Tarball excludes compiled test files.
+
+## Install Smoke
+
+Run:
+
+```bash
+npm run build
+TARBALL="$(npm pack --silent)"
+TMP_PREFIX="$(mktemp -d)"
+npm install -g --prefix "$TMP_PREFIX" "./$TARBALL"
+"$TMP_PREFIX/bin/pmem" --version
+"$TMP_PREFIX/bin/pmem" --help
+rm -f "$TARBALL"
+rm -rf "$TMP_PREFIX"
+```
+
+Expected:
+
+- [ ] `pmem --version` prints `0.5.0`.
+- [ ] `pmem --help` lists the v0.5 public commands.
+
+## Publish Decision
+
+- [ ] Confirm whether v0.5.0 is Internal Beta only or Public Beta.
+- [ ] Confirm npm account and publish permission.
+- [ ] Confirm the `pmem` package name is available or accessible.
+- [ ] Confirm repository visibility and issue tracker policy.
+
+## Final Commands
+
+Only if publishing:
+
+```bash
+npm publish --dry-run
+npm publish
+```
+
+After publishing:
+
+- [ ] Create git tag `v0.5.0`.
+- [ ] Push branch and tag.
+- [ ] Create GitHub release notes from `CHANGELOG.md`.

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

@@ -0,0 +1,182 @@
+# v0.2 前置设计决策
+
+本文档记录 v0.2 开工前必须解决的 4 个设计问题及其最终决策。v0.2 的总原则：
+
+> **v0.2 不追求"更智能"，而是补齐"可冷启动、可并发、可治理、可迁移"的工程底座。**
+
+---
+
+## 1. 冷启动：`pmem init` 在已有项目上应该做什么？
+
+### 决策
+
+`pmem init` 不允许纯空初始化。提供三种模式：
+
+```bash
+pmem init                # 最小可用初始化，生成低置信度记忆，标记 memory_incomplete
+pmem init --guided       # 推荐模式，交互式引导（问 3 个必填字段）
+pmem init --from <file>  # 声明式，适合团队/模板/自动化
+```
+
+### 核心规则
+
+- **默认 init**：扫描项目 → 生成候选（`candidates/`，非稳定卡）→ 标记 `memory_incomplete` → Agent 看到后知道不要假装理解项目
+- **guided init**：问 3 个必填（项目描述、当前阶段、下一步），可选再问 2 个（关键模块、已确定决策）
+- **扫描算法**：保守扫描（package.json、目录结构），不激进、不自动确认为稳定记忆
+- **降级策略**：用户跳过引导时，`pmem recall` 明确提示 `memory incomplete`，不建议自动深扫描代码
+
+### 路径选择
+
+- 普通用户 → `pmem init --guided`（交互式，门槛低）
+- 高级用户/团队 → `pmem init --from pmem.init.yml`（声明式，可版本化）
+
+---
+
+## 2. 多 Agent / 多会话并发写入
+
+### 决策
+
+v0.2 必须引入五层并发保护。SQLite 留到 v0.3。
+
+### 必须实现（P0）
+
+| 机制 | 说明 |
+|------|------|
+| file lock | `.pmem/.lock`，超时 5s，默认 abort |
+| optimistic lock | 每张卡片 `version` + `content_hash`，写入时对比 |
+| atomic write | 写 `.tmp` → fsync → rename，防止半写损坏 |
+| conflict detection | `card_hashes.json` 记录写入前快照，检测读后写冲突 |
+| abort by default | 冲突时不自动 merge，生成冲突报告 |
+
+### 冲突行为
+
+- 锁超时 → abort（不排队，旧上下文延迟写入更危险）
+- 乐观锁冲突 → abort + 报告（"Card changed since session started"）
+- section-level merge → v0.2 可选，只对安全场景（不同 section 无冲突时）
+
+### 配置
+
+```yml
+concurrency:
+  lock: file
+  lock_path: ".pmem/.lock"
+  timeout: "5s"
+  stale_after: "60s"
+  on_timeout: "abort"
+  optimistic_lock: true
+  atomic_write: true
+```
+
+---
+
+## 3. 卡片粒度的判断标准
+
+### 决策
+
+v0.2 必须定义 `card_policy`，建立三套标准：类型标准、粒度标准、命名标准。
+
+### 类型判断树
+
+```txt
+变化改变了"为什么做"    → decision card
+变化描述稳定组成部分    → module card
+变化描述用户可见能力    → feature card
+变化是待办/进行/完成    → task card
+变化只是一次工作过程    → trace card
+变化是长期风险          → risk card
+同模块状态推进          → 更新已有 module card
+同任务进度推进          → 更新已有 task card
+```
+
+### 大小阈值
+
+| 卡片类型 | max_tokens | max_sections |
+|----------|-----------|-------------|
+| module   | 1200      | 8           |
+| feature  | 1000      | 8           |
+| decision | 800       | 6           |
+| task     | 600       | 6           |
+| trace    | 1000      | -           |
+
+`warn_when_related_count_gt: 12`，超过时 `pmem verify` 警告。
+
+### module 粒度原则
+
+> **以概念/责任边界为主，代码路径为辅。** 不等于代码目录一一对应。
+
+冷启动扫描生成的候选用 `status: candidate`，需用户确认后才成为稳定卡。
+
+### ID 命名强制规范
+
+```txt
+project.<name>
+module.<name>
+feature.<name>
+task.<name>
+decision.<yyyy-mm-dd>.<slug>
+trace.<yyyy-mm-dd>.<slug>
+risk.<name>
+```
+
+规则：小写、英文 slug、点号分层、中文放 `title` / `aliases`。
+
+### distill 与拆分
+
+- `pmem distill` 建议目标 card（"这条 trace 应蒸馏到 module.X"）
+- `pmem distill --suggest-splits` 建议拆分过大卡片
+- v0.2 只建议，不自动拆分
+
+---
+
+## 4. 记忆格式自身的版本迁移
+
+### 决策
+
+v0.2 必须引入三层版本标识和 migrate 机制。
+
+### 版本字段设计
+
+区分三个概念：
+
+```yml
+pmem:
+  cli_version_created: "0.1.0"    # 工具版本
+  cli_version_last_used: "0.2.0"
+  schema_version: "0.2"           # frontmatter/manifest/index 格式版本
+  protocol_version: "0.2"         # 语义协议版本
+```
+
+每张卡片也带 `schema_version: "0.2"`。
+
+### 迁移命令
+
+```bash
+pmem migrate --to 0.2 --dry-run   # 预览变更，不改任何文件
+pmem migrate --to 0.2             # 执行迁移
+pmem migrate --backup             # 迁移前自动备份
+```
+
+### 迁移规则
+
+- 官方迁移规则内置于 CLI（0.1→0.2、0.2→0.3 等）
+- 项目自定义迁移可放 `.pmem/migrations/`（v0.2 先不做）
+- manifest 记录 `migrations.applied` 历史
+- 不支持降级迁移（语义不可逆），改用自动备份回退
+
+### verify 中的版本检查
+
+- 项目 schema ≤ CLI 支持 → OK 或建议升级
+- 项目 schema > CLI 支持 → 报错，要求升级 CLI
+- init 时必须写入 `schema_version`
+
+---
+
+## v0.2 设计的核心主题
+
+v0.1 是"能用"。v0.2 是"可信地长期使用"：
+
+- 冷启动不空
+- 并发不丢
+- 卡片不乱
+- 版本可迁
+- 记忆可持续