pmem-ai 0.5.0 → 0.6.0

package/dist/index.js

@@ -14,11 +14,13 @@ const migrate_1 = require("./commands/migrate");
 const distill_1 = require("./commands/distill");
 const session_1 = require("./commands/session");
 const status_1 = require("./commands/status");
+const install_1 = require("./commands/install");
+const doctor_1 = require("./commands/doctor");
 const program = new commander_1.Command();
 program
     .name('pmem')
     .description('Project Memory for AI Agents — graph-based project memory runtime')
-    .version('0.5.0');
+    .version('0.6.0');
 program
     .command('status')
     .description('Detect changed files and affected memory cards')
@@ -31,9 +33,20 @@ program
     .command('init [project-name]')
     .description('Initialize pmem in the current project')
     .option('--guided', 'Interactive guided initialization (recommended)')
+    .option('--description <text>', 'Project description (non-interactive mode)')
+    .option('--stage <text>', 'Current project stage (non-interactive mode)')
+    .option('--next <text>', 'Most important next step (non-interactive mode)')
+    .option('--answers <path>', 'Path to JSON answers file for non-interactive init')
     .action((projectName, options) => {
     const opts = options || {};
-    (0, init_1.initCommand)({ projectName, guided: opts.guided });
+    (0, init_1.initCommand)({
+        projectName,
+        guided: opts.guided,
+        description: opts.description,
+        stage: opts.stage,
+        next: opts.next,
+        answers: opts.answers,
+    });
 });
 program
     .command('recall')
@@ -106,6 +119,13 @@ program
     .action((options) => {
     (0, verify_1.verifyCommand)({ fix: options.fix });
 });
+program
+    .command('doctor')
+    .description('Run diagnostic checks on project memory setup')
+    .option('-f, --format <format>', 'Output format (compact, json)', 'compact')
+    .action((options) => {
+    (0, doctor_1.doctorCommand)(options.format);
+});
 program
     .command('migrate')
     .description('Migrate project memory to a newer schema version')
@@ -163,5 +183,22 @@ integration
     .action(() => {
     (0, integration_1.integrationCommand)('verify');
 });
+program
+    .command('install')
+    .description('Install pmem skills to agent global directories')
+    .option('--skills', 'Install skill files')
+    .option('--claude', 'Target Claude Code')
+    .option('--codex', 'Target Codex')
+    .option('--gemini', 'Target Gemini CLI')
+    .option('--all', 'Target all detected agents')
+    .action((options) => {
+    (0, install_1.installCommand)({
+        skills: options.skills,
+        claude: options.claude,
+        codex: options.codex,
+        gemini: options.gemini,
+        all: options.all,
+    });
+});
 program.parse();
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/docs/project-roadmap.md

@@ -19,7 +19,8 @@ CLI：`pmem`
 | v0.2 | 文件模式可信 | 防损坏——冷启动不空、并发不丢、卡片不乱、版本可迁 |
 | v0.3 | SQLite 运行时 | 强一致——查询/索引/状态迁入 SQLite，Markdown 仍为主数据 |
 | v0.4 | Agent 集成 & 自动化 | 多框架适配、session 追踪、distill 工作流优化 |
-| v0.5 | 可上线 Beta | 安装体验、文档、稳定 CLI、SQLite 默认开启、demo 项目 |
+| v0.5 | Productization Beta | README、npm package、E2E、错误 UX、发布清单，上线 npm Beta |
+| v0.6 | Agent-native Workflow Polish | 非交互 init、友好错误、空结果引导、Claude Code slash commands |
 
 ---
 
@@ -194,21 +195,44 @@ v0.3:  文件系统 → SQLite indexes → SQL 查询 → CLI
 
 ---
 
-## v0.5 — 可上线 Beta
+## v0.5 — Productization Beta ✅ 已完成
 
-**主题：** 面向真实用户（开发者 + AI Agent）稳定可用。
+**主题：** 把 v0.4 已经跑通的 Agent Workflow Runtime 包装成一个真实项目可以安装、理解、运行、验证、反馈的 Beta CLI 产品。
 
 | 功能 | 说明 |
 |------|------|
-| 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` |
+| README / quick start | 外部用户可独立理解 pmem 并跑通 5 分钟流程 |
+| npm package readiness | package metadata、bin、files、build、pack smoke |
+| install smoke E2E | 验证 tarball 安装后的 `pmem` 二进制可用 |
+| real workflow E2E | 覆盖 init → rebuild → recall/ask → status → mark-dirty → update → verify |
+| Agent docs sync | `AGENTS.md`、`CLAUDE.md`、integration templates 统一到 v0.5 产品口径 |
+| Error UX / exit code docs | 明确 workflow signal exit code，不把 exit 1 都视为失败 |
+| CHANGELOG / release checklist | 支持可重复 Beta 发布 |
+
+详细设计：`docs/v0.5 pre-design.md`
+
+---
+
+## v0.6 — Agent-native Workflow Polish
+
+**主题：** 让 v0.5 已经成立的 Beta CLI 更适合 AI Agent 程序化调用、跨会话恢复、无人工兜底使用。
+
+v0.6 不扩大能力边界，不做 embedding、MCP/REST、Graph UI、遥测或远程服务。它专注处理 v0.5 真实使用反馈中暴露出的 Agent 摩擦点。
+
+| 功能 | 说明 |
+|------|------|
+| 非交互 init | `init --guided` 提供参数 / answers 文件路径，避免 Agent 卡在 TTY |
+| git 前置检查 | `status` / `mark-dirty --auto` 在非 git 或 git 不可用时给友好提示 |
+| 空结果引导 | `update --suggest` / `ask` 不静默返回空数组，解释下一步 |
+| session 容错 UX | `session end` 未 start 时给出可操作建议，评估显式容错 option |
+| Claude Code slash commands | `integration install claude-code` 生成 `.claude/commands/pmem-*.md` |
+| integration verify 增强 | 检查 root files、settings、slash commands、rules 是否真实存在 |
+| 全局 skills 安装 | `pmem install --skills --claude/--codex/--gemini` 一键安装到 agent skills 目录 |
+| pmem doctor | 8 项诊断检查（pmem_dir/manifest/database/cards/dirty_flags/session/git/integrations） |
+| Agent-native E2E | 覆盖非交互 init、integration install、空结果、非 git UX、skills install |
+| 文档口径同步 | README / AGENTS / CLAUDE 解释 pmem 的跨会话价值 |
+
+详细设计：`docs/v0.6 pre-design.md`
 
 ---
 
@@ -233,10 +257,12 @@ v0.3 → v0.4:
        manifest integrations 扩展
 
 v0.4 → v0.5:
-  pmem migrate --to 0.5
-  变更：SQLite 成为默认
-       文件模式标记为 legacy
-       遥测配置项
+  无强制 memory schema migration
+  变更：README / package / E2E / agent docs / release checklist 产品化
+
+v0.5 → v0.6:
+  无强制 memory schema migration
+  变更：非交互 init、Agent integration 文件、错误 UX、空结果引导
 ```
 
 每次迁移自动备份到 `.pmem/backups/YYYY-MM-DD-before-vX.Y/`。
@@ -246,10 +272,10 @@ v0.4 → v0.5:
 ## 总览
 
 ```
-v0.1 ───→ v0.2 ───→ v0.3 ───→ v0.4 ───→ v0.5
-能用      防损坏    强一致    自动化    可上线
-10 cmd    14 cmd    16 cmd    18 cmd    20+ cmd
-文件模式   文件模式   +SQLite   +集成     +体验
+v0.1 ───→ v0.2 ───→ v0.3 ───→ v0.4 ───→ v0.5 ───→ v0.6
+能用      防损坏    强一致    自动化    Beta上线  Agent原生
+10 cmd    14 cmd    16 cmd    18 cmd    产品化    低摩擦
+文件模式   文件模式   +SQLite   +集成     +体验     +程序化调用
 ```
 
 ---
@@ -257,10 +283,19 @@ v0.1 ───→ v0.2 ───→ v0.3 ───→ v0.4 ───→ v0.5
 ## 当前状态
 
 - **v0.1:** ✅ 完成（10 个命令实现并测试）
-- **v0.2:** 🔜 设计完成，待开工
+- **v0.2:** ✅ 完成（文件模式可信）
   - 设计决策：`docs/v0.2 pre-design.md`
   - 架构规划：`docs/v0.2 pre-roadmap.md`
-- **v0.3–v0.5:** 📋 方向确定，详细设计待 v0.2 完成后细化
+- **v0.3:** ✅ 完成（SQLite runtime）
+  - 设计决策：`docs/v0.3 pre-design.md`
+- **v0.4:** ✅ 完成（Agent workflow runtime）
+  - 设计决策：`docs/v0.4 pre-design.md`
+  - handover：`docs/handover-v0.4.md`
+- **v0.5:** ✅ 完成并上线 npm（Productization Beta）
+  - 设计决策：`docs/v0.5 pre-design.md`
+  - 发布清单：`docs/release-checklist-v0.5.md`
+- **v0.6:** 📋 设计完成，待开工（Agent-native Workflow Polish）
+  - 设计决策：`docs/v0.6 pre-design.md`
 
 ---
 
@@ -268,12 +303,10 @@ v0.1 ───→ v0.2 ───→ v0.3 ───→ v0.4 ───→ v0.5
 
 以下问题留待后续版本讨论：
 
-- v0.3 SQLite schema 详细设计
 - MCP Server vs HTTP API 的选择
 - 多项目 / workspace 支持
 - 记忆共享与协作机制
 - 记忆权限模型
 - 多语言 CLI 支持
-- telemetry 的范围和隐私策略
-- npm 包发布与版本策略
+- telemetry 的范围和隐私策略（v0.6 继续不做）
 - 是否支持嵌入到 VS Code / JetBrains 插件

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

@@ -0,0 +1,72 @@
+# pmem v0.6 Release Checklist
+
+Use this checklist before tagging or publishing v0.6.0.
+
+## Scope Check
+
+- [ ] v0.6 remains Agent-native Workflow Polish only.
+- [ ] No embedding, MCP/REST, Graph UI, telemetry, or remote service was added.
+- [ ] Non-interactive init, error UX, empty result guidance, Claude Code slash commands, pmem doctor, and global skills installation are complete.
+
+## Version Check
+
+- [ ] `package.json` version is `0.6.0`.
+- [ ] `package-lock.json` root version is `0.6.0`.
+- [ ] `src/index.ts` Commander version is `0.6.0`.
+- [ ] `CHANGELOG.md` has a `0.6.0` section.
+
+## Test Check
+
+Run:
+
+```bash
+npm test
+npm run build
+npm run test:e2e:install
+npm run test:e2e:workflow
+npm run test:e2e:non-git
+npm run test:e2e:v06-init
+npm run test:e2e:v06-answers
+npm run test:e2e:v06-claude
+npm run test:e2e:v06-empty
+npm run test:e2e:v06-nongit
+npm run test:e2e:v06-skills
+```
+
+Expected:
+
+- [ ] Unit tests pass (90+).
+- [ ] TypeScript build passes.
+- [ ] All E2E scripts pass.
+
+## Package Check
+
+Run:
+
+```bash
+npm pack --dry-run
+```
+
+Expected:
+
+- [ ] Package name is `pmem-ai`.
+- [ ] Package version is `0.6.0`.
+- [ ] Tarball includes `dist/`.
+- [ ] Tarball includes `skills/pmem/SKILL.md` and `skills/pmem/references/`.
+- [ ] Tarball includes `README.md`, `LICENSE`, `CHANGELOG.md`.
+- [ ] Tarball includes `docs/*.md` including `docs/usage.md`.
+- [ ] Tarball excludes `src/`, `temp/`, `.pmem/`, `node_modules/`.
+- [ ] Tarball excludes compiled test files.
+
+## Publish Decision
+
+- [ ] Confirm whether v0.6.0 is ready to publish.
+- [ ] Confirm npm account and publish permission.
+- [ ] Confirm CI/CD publish job will run on push to main.
+
+## Final Commands
+
+```bash
+npm publish --access public
+# or push to main for CI/CD auto-publish
+```

package/docs/usage.md

@@ -0,0 +1,374 @@
+# pmem Usage Guide
+
+A step-by-step guide to using pmem with AI coding agents. Uses Claude Code as the primary example; the same patterns work for Codex, Cursor, and other agent frameworks.
+
+## Prerequisites
+
+- Node.js >= 18
+- A Git repository (pmem uses `git status --porcelain` for change detection; non-Git projects fall back to mtime scanning)
+
+## 1. Install
+
+```bash
+npm install -g pmem-ai
+pmem --version   # should print 0.5.0
+```
+
+The binary is `pmem`. The package name `pmem-ai` is only for npm.
+
+## 2. One-Time Setup (per project)
+
+Run these once in your project root:
+
+```bash
+cd your-project
+pmem init your-project
+pmem rebuild
+```
+
+This creates a `.pmem/` directory with:
+
+```
+.pmem/
+  manifest.yml         # project configuration
+  index.md             # project overview (edit this)
+  state.md             # current state (edit this)
+  next.md              # recommended next step (edit this)
+  modules/             # module memory cards
+  decisions/           # decision records
+  tasks/               # task tracking
+  traces/              # work traces
+  integrations/        # agent framework templates
+  pmem.db              # SQLite runtime index (auto-generated)
+```
+
+`pmem init --guided` lets you answer 3 questions interactively to populate the project info.
+
+## 3. Create Your First Memory Card
+
+A memory card is a Markdown file with YAML frontmatter. The most important type is `module` — it connects source files to memory:
+
+```bash
+mkdir -p .pmem/modules
+
+cat > .pmem/modules/core.md <<'EOF'
+---
+id: module.core
+type: module
+status: active
+tags: [core]
+aliases: [main, entry]
+source_files: [src/index.ts]
+depends_on: []
+---
+# Core Module
+
+## Purpose
+Main application entry point.
+
+## Key Behavior
+- Initializes the app
+- Loads configuration
+- Boots subsystems
+EOF
+```
+
+Then rebuild the index:
+
+```bash
+pmem rebuild
+```
+
+Now pmem knows that `src/index.ts` belongs to the `module.core` card.
+
+## 4. Claude Code Integration
+
+### 4a. Install the Integration Template
+
+`pmem init` already created `.pmem/integrations/claude-code/CLAUDE.md`. Copy it to your project root so Claude Code can see it:
+
+```bash
+cp .pmem/integrations/claude-code/CLAUDE.md ./CLAUDE.md
+```
+
+If your project already has a `CLAUDE.md`, merge the pmem workflow section into it instead.
+
+### 4b. What the Integration Does
+
+The integration template teaches Claude Code the pmem workflow. Here is what happens in a typical session:
+
+**Session Start**
+
+Claude Code runs these when beginning work:
+
+```bash
+pmem session start -a "Claude"
+pmem recall --format compact --budget 2000
+```
+
+`pmem recall` outputs the project context: name, stage, current focus, state summary, recommended next step, and a list of files to read. All within the token budget.
+
+**Before Focused Work**
+
+```bash
+pmem ask "<task or module>" --format compact
+```
+
+`pmem ask` finds relevant memory cards by exact ID match, alias, tag, graph neighbor expansion, and keyword fallback (FTS5 or LIKE).
+
+**After Editing Code**
+
+```bash
+pmem status --format json
+pmem mark-dirty --auto
+pmem update --suggest --format json
+```
+
+- `pmem status` detects changed files and maps them to affected memory cards
+- `pmem mark-dirty --auto` marks those cards as potentially stale
+- `pmem update --suggest` generates memory update suggestions
+
+Important: `pmem update --suggest` exits with code `1` when it has suggestions. This is a workflow signal ("action suggested"), not a failure.
+
+**Session End**
+
+```bash
+pmem update --confirm -s "<what changed>" -n "<next step>"
+pmem session end -s "<task summary>"
+pmem verify
+```
+
+- `pmem update --confirm` writes the confirmed changes
+- `pmem session end` closes the session with a summary
+- `pmem verify` checks consistency
+
+### 4c. Complete Session Example
+
+Here is a complete Claude Code session transcript showing pmem integration:
+
+```bash
+# === Session start ===
+$ pmem session start -a "Claude"
+Session started: session_2026-05-20T09-00-00
+
+$ pmem recall --format compact --budget 2000
+PROJECT: pmem
+STAGE: v0.5 Productization Beta
+
+FOCUS: Making the CLI product installable and reliable as a Beta.
+
+NEXT:
+Complete the Error UX pass for common failure scenarios.
+
+STATE:
+  - README and quick start: done
+  - npm package readiness: done
+  - E2E scripts: done
+  - Agent docs sync: done
+  - Error UX pass: in progress
+
+READ_IF_NEEDED:
+  .pmem/state.md
+  .pmem/next.md
+  .pmem/modules/core.md
+
+# === Before editing src/commands/verify.ts ===
+$ pmem ask "verify" --format compact
+Query: verify
+
+Matched:
+  - module.verify by keyword_fallback: "verify.ts"
+
+# === After editing the file ===
+$ pmem status --format json
+{
+  "source": "git",
+  "changes": [
+    {
+      "path": "src/commands/verify.ts",
+      "status": "M",
+      "related_cards": [{"card_id": "module.verify", "match_type": "exact"}]
+    }
+  ]
+}
+
+$ pmem mark-dirty --auto
+Auto-marked 1 card(s) as dirty.
+
+$ pmem update --suggest --format json
+# exit code 1 (suggestions exist)
+{
+  "suggestions": [
+    {
+      "card_id": "module.verify",
+      "action": "update",
+      "reason": "Source file changed: src/commands/verify.ts"
+    }
+  ]
+}
+
+# === Confirm the update ===
+$ pmem update --confirm -s "Added corrupt DB error handling to verify" -n "Test the error UX changes"
+Memory updated.
+
+# === Session end ===
+$ pmem session end -s "Completed Error UX pass for verify command"
+Session ended. 1 update recorded.
+
+$ pmem verify
+✓ Memory verification passed.
+  Score: 100/100
+```
+
+## 5. What the Agent Sees
+
+When Claude Code (or another agent) starts a session with pmem, it gets the critical project context immediately:
+
+- **recall** gives it orientation: project name, stage, focus, state, and next steps
+- **ask** finds the specific cards relevant to the current task
+- **status** tells it which memory cards are affected by code changes
+- **update --suggest** tells it what needs updating in the memory
+
+The agent never needs to read the entire `.pmem/` tree. It only reads what pmem tells it to.
+
+## 6. Adding More Memory Cards
+
+### Decision Record
+
+```bash
+cat > .pmem/decisions/sqlite-runtime.md <<'EOF'
+---
+id: decision.sqlite_runtime
+type: decision
+status: accepted
+tags: [architecture, data]
+---
+# Use SQLite as Runtime Index
+
+## Context
+v0.3 needed faster recall and richer query support.
+
+## Decision
+Use better-sqlite3 with WAL mode as the primary runtime store.
+
+## Consequences
+- Markdown cards remain source of truth
+- SQLite is fully rebuildable from cards
+- FTS5 enables keyword search; LIKE fallback for builds without FTS5
+EOF
+
+pmem rebuild
+```
+
+### Task Card
+
+```bash
+cat > .pmem/tasks/error-ux-pass.md <<'EOF'
+---
+id: task.error_ux_pass
+type: task
+status: in_progress
+priority: high
+tags: [v0.5, ux]
+depends_on: [module.verify, module.ask]
+---
+# Error UX Pass
+
+## Goal
+Every common failure scenario should produce a message that says what happened, why, and what to do next.
+
+## Sub-tasks
+- [x] Corrupt DB: catch SQLITE_NOTADB in openDatabase
+- [x] Missing .pmem: prompt pmem init
+- [ ] Non-git status: show mtime source in compact output
+EOF
+
+pmem rebuild
+```
+
+## 7. Working with Codex
+
+For Codex, the integration template is at `.pmem/integrations/codex/AGENTS.md`. Copy or merge it into your project's `AGENTS.md`:
+
+```bash
+cat .pmem/integrations/codex/AGENTS.md >> AGENTS.md
+```
+
+The workflow is identical — replace `Claude` with `Codex` in `pmem session start -a`.
+
+## 8. Working with Cursor
+
+Cursor uses `.cursor/rules/` for instructions. The pmem integration is at `.pmem/integrations/cursor/rules.example.md`:
+
+```bash
+mkdir -p .cursor/rules
+cp .pmem/integrations/cursor/rules.example.md .cursor/rules/pmem.md
+```
+
+In Cursor's AI chat, prefix pmem commands with backticks:
+
+```
+`pmem session start -a "Cursor" && pmem recall --format compact --budget 2000`
+```
+
+## 9. Exit Codes
+
+Agents must treat some exit codes as workflow signals:
+
+| Command | 0 | 1 | 2 |
+|---------|---|---|---|
+| `pmem status` | changes found | no changes | error |
+| `pmem update --suggest` | no suggestions | **suggestions found** | error |
+| `pmem distill --suggest` | no distillation needed | **distillation suggested** | error |
+| `pmem verify` | passed | warnings | errors |
+
+When `pmem update --suggest` returns 1, it means "action suggested" — not "command failed". Parse the JSON output for suggestions.
+
+## 10. Tips for Agent Framework Authors
+
+If you are an agent framework developer integrating pmem:
+
+1. **Run session start + recall at session begin.** This gives the agent immediate project orientation.
+2. **Run status after file writes.** Detect changes before the agent forgets what it edited.
+3. **Parse exit code 1 correctly.** For `update --suggest` and `distill --suggest`, code 1 is success.
+4. **Use `--format json` for machine consumption.** Compact format is for humans.
+5. **Don't edit `pmem.db` directly.** All writes go through Markdown cards or pmem CLI commands.
+6. **Run verify at session end.** Catch stale indexes, orphan edges, or dirty flags before they accumulate.
+
+## 11. Troubleshooting First-Run Issues
+
+### `pmem: command not found`
+
+npm global bin directory is not in your `PATH`. Add it:
+
+```bash
+npm config get prefix   # shows where global packages are installed
+export PATH="$(npm config get prefix)/bin:$PATH"
+```
+
+### `No .pmem directory found`
+
+You are not in a project that has been initialized. Run `pmem init <name>` from the project root.
+
+### `pmem rebuild` says no manifest
+
+The project was not properly initialized. Run `pmem init <name>` again.
+
+### `pmem recall` shows empty project
+
+No memory cards exist yet. Create at least one module card (see Section 3), then run `pmem rebuild`.
+
+### `pmem.db` is corrupted
+
+This can happen if the SQLite file was interrupted during a write:
+
+```bash
+mv .pmem/pmem.db .pmem/pmem.db.bak
+pmem rebuild --full
+```
+
+## Next Steps
+
+- Read the [README](../README.md) for the full CLI reference
+- Read the [v0.5 pre-design](v0.5%20pre-design.md) for the product vision
+- Check `.pmem/integrations/` for your agent framework's template