dev-memory-cli 0.18.2 → 0.18.3

package/README.md

@@ -53,10 +53,11 @@ append 类 kind 写入前会对目标 section 做相似度查重，阻止 append
 - **行为**：命中拦下不写，`exit 2`，stdout 返 `dedup_hint` 含 `matches[]` + `recommendation`（`update_existing` / `review_and_decide`）
 - **agent 处理**：按 recommendation 分流：
   - 修订旧条目 → `dev-memory-cli capture rewrite-entry --id <match_id> --content <text>`（新 subcommand）
+  - 删除旧条目 → `dev-memory-cli capture delete-entry --id <match_id>`
   - 确实是独立新事实 → `dev-memory-cli capture record --force ...`（绕过查重）
   - 误判同义 / 暂不写 → 不调任何命令
 - **绕过**：`--force` flag；upsert 类 kind（progress / next / overview / scope / stage / constraint）天然跳过 dedup
-- **批量**：`--summary-json` 每条独立 check，blocked 项进 stdout `dedup_blocked[]`，未 blocked 部分照常写
+- **批量**：`record --summary-json` 每条独立 check，blocked 项进 stdout `dedup_blocked[]`，未 blocked 部分照常写；SessionEnd 自动总结优先走 `capture apply-summary-output --json`，支持 upsert / append / rewrite / delete 的结构化 patch
 - **调试 / 实验**：可用 `--dedup-threshold <float>`（隐藏参数，范围 (0.0, 1.0]）临时覆盖默认 0.7 阈值，生产场景不建议改
 
 ### Setup vs Tidy vs Graduate（三个整理动作的边界）
@@ -75,6 +76,8 @@ append 类 kind 写入前会对目标 section 做相似度查重，阻止 append
 - 新 action `delete-block`：把 top bullet + 缩进子树 + 紧跟的 `**Why:**` / `**How to apply:**` bold paragraph 聚成一个语义单元整体删，自动吸附 orphan paragraph
 - action 优先级 `reset-file > delete-section > delete-block > delete-entries / edit-entries`，apply 时高优先级覆盖低优先级
 - `delete-block` 的 block_id 在 apply 时**重新解析**当前文件结构定位（不依赖 prepare 时的快照），文件中途被改不误删邻块
+- `prepare` 默认跑两个轻量启发式 pass 给 entry 贴 hint，让 review 从"全表扫一遍"变成"先看高亮"：**STALE**（文件在 `log.md` 最近一次出现 ≥ `--stale-after-days`（默认 30）天前 → 该文件下所有 entry 标 STALE）、**ORPHAN**（glossary entry 的 key phrase——冒号前 ≥ 4 字符——在其他 `.md` 零引用 → 标 ORPHAN，同 entry 上 ORPHAN 优先 STALE）。用户传 `--hints-json` / `--hints-file` 时用户优先；`--no-auto-hints` 关闭；冷启动 `log.md` 为空时不标，避免一次性给所有文件贴 STALE（HUB GAP 不实现，中文 NLP false positive 太干扰）
+- `apply` 落盘后写一行 `log.md`（accepted / rewritten / backup 等详情）
 
 ### 分支记忆生命周期（0.14 起新增 CLI）
 
@@ -113,10 +116,22 @@ dev-memory-cli branch inherit-worktree-base [--source NAME] [--backup | --force]
 - 环境变量 `DEV_MEMORY_DISABLE_WORKTREE_INHERIT=1` 全局关闭
 - 已经开过会话的 worktree 想后补 → 显式跑 `dev-memory-cli branch inherit-worktree-base`（支持 `--source` 覆盖 reflog 探测）
 
+如果希望 worktree 分支写入时把新增知识也写回源分支，可以显式开启 write-back：
+
+```bash
+git config --local dev-memory.worktreeWriteback true
+# 或仅当前进程启用
+DEV_MEMORY_WORKTREE_WRITEBACK=1 dev-memory-cli capture record ...
+```
+
+write-back 只镜像 append 型分支知识：`decision` / `risk` / `glossary` / `source`。`progress` / `next` / `overview` / `scope` / `stage` / `constraint` 这类快照字段不会回源，因为它们表达当前 worktree 分支状态，双写会覆盖源分支自己的工作态。源分支重复内容会走同一套 dedup 检查；被拦截时当前分支写入仍然保留，只在输出的 `worktree_writeback.skipped` 里报告。
+
 ### Graduate 为什么必须显式
 
 `dev-memory-graduate` 会做 destructive move（把 `branches/<key>/` 搬到 `branches/_archived/<key>__<date>/`），同时把 branch 记忆里跨分支可复用的知识（剥离业务命名后）上提到 repo 共享层。**只接受用户显式触发**，不做 implicit 调用。在 no-git 模式下直接拒绝（没有分支概念）。Tidy 同样要求显式触发（用户主动说"整理"），不做 implicit。
 
+apply 写入受 **repo 级队列锁**保护：多个会话可连续发起归档，但 harvest / schema / branch 等 pre-flight 校验先于锁执行（失败立即返回），只有写 repo 共享层和移动归档目录的阶段按 repo memory 目录串行等待；等待者拿到锁后会重新确认 `branch_dir` 仍存在，避免并发写共享记忆或重复 move。
+
 ## 运行模式
 
 套件会根据当前工作目录自动切换运行模式，存储布局 key 始终是 `(仓库身份, 分支)`：
@@ -141,14 +156,16 @@ dev-memory-cli branch inherit-worktree-base [--source NAME] [--backup | --force]
     overview.md                   # 长期目标 + 约束
     decisions.md                  # 跨分支通用决策
     glossary.md                   # 共享入口 + 长期背景
+    log.md                        # 仓库事件日志（graduate / shared-* capture 镜像）
     manifest.json
   branches/
-    <branch>/                     # 当前分支层（v2 八件套）
+    <branch>/                     # 当前分支层
       overview.md                 # 冷启动摘要（snapshot 型）
       progress.md                 # 当前进展 + 下一步 + 自动同步区（snapshot 型）
       decisions.md                # 稳定决策 + Why + 影响（accumulation 型）
       risks.md                    # 阻塞 + 注意点（accumulation 型）
       glossary.md                 # 术语 + 源资料入口（accumulation 型）
+      log.md                      # append-only 事件时间线（capture / graduate 落盘后追加）
       unsorted.md                 # heuristic 兜底（setup 时分类）
       pending-promotion.md        # 跨分支候选 staging（graduate 预筛源）
       manifest.json               # 含 setup_completed
@@ -165,6 +182,7 @@ dev-memory-cli branch inherit-worktree-base [--source NAME] [--backup | --force]
 
 **其他关键点：**
 
+- `log.md`：append-only 事件时间线，capture record / rewrite-entry、graduate apply、tidy apply 落盘后各追加一行 `## [ISO] action · kind | summary`，`grep '^## \[' log.md | tail -20` 看最近事件。SessionStart 只列文件路径不抽正文（lazy loading）；`sync-working-tree` / `record-head` 故意不写以免机器噪音冲洗日志；`shared-*` kind 写入会镜像到 repo log，分支-only 写入不污染 repo log
 - `repo-key`：优先按仓库 remote 身份派生，不只看目录名；支持多 clone / worktree 共享同一套记忆
 - `DEV_ASSETS_ROOT`：覆盖默认 `~/.dev-memory/repos`；CLI、所有 hook 脚本、所有 skill 脚本都尊重此环境变量
 - v1 → v2 迁移在第一次 capture/context 时自动触发，老的 `development.md` / `context.md` / `sources.md` 按 section 切分进 v2 对应文件后删除（单用户离线清理，不保留 .legacy）
@@ -252,16 +270,20 @@ dev-memory-cli ui --read-only          # 禁用编辑回写
 
 | 事件 | Claude | Codex | 做什么 |
 | --- | :-: | :-: | --- |
-| `SessionStart` | ✅ | ✅ | 跑 `context sync` 刷 progress.md auto 区，抽 14 段摘要 + 列权威记忆文件路径，注入会话上下文 |
+| `SessionStart` | ✅ | ✅ | 跑 `context sync` 刷 progress.md auto 区，抽 14 段摘要 + 列权威记忆文件路径，注入会话上下文；同一 session resume 重触发时只写日志并返回空 payload |
 | `PreCompact` | ✅ | ✕ | **0.17 起 no-op**（SessionStart 已经刷过，重复跑无信号） |
 | `Stop` | ✅ | ✅ | 每次回复后落一个轻量 HEAD marker |
-| `SessionEnd` | ✅ | ✕ | 会话结束时再落一次最终 HEAD |
+| `SessionEnd` | ✅ | ✕ | 会话结束时再落一次最终 HEAD，并把 transcript 总结任务写入队列 |
 
 重要边界：
 
 - 本仓库只提供**模板 + CLI**，真正生效的是你本地 `.codex/hooks.json` / `.claude/settings.local.json` / `~/.codex/hooks.json` / `~/.claude/settings.json` 里有没有合并进来
 - hook 运行时统一走 `dev-memory-cli hook ...`，所以 CLI 必须在 PATH 上或可被 `npx` 解析
 - hook 只做**低摩擦恢复 + 轻量刷新**，不在 hook 里重写高语义正文
+- `SessionStart` 以 `<repo-memory>/jobs/session-start/injected/*.json` 做同 session 幂等；Codex resume 等场景再次触发生命周期事件时，只写 skip 日志并返回空 payload，不重复注入上下文
+- `SessionEnd` 只 enqueue 总结任务，不同步跑总结：任务写到 `<repo-memory>/jobs/session-summary/pending/*.json`，事件日志写到同目录 `events.jsonl`。同一 repo+branch+session 会更新同一个 job，避免短时间重复结束时冲突
+- enqueue 后是否启动后台 summarizer 由 `~/.dev-memory/config.json` 的 `session_summary.command` 决定；`install-hooks` 会扫描本地工具，按 `coco -> codex -> claude` 顺序写默认值。coco 默认用 `--session-id {summary_session_id}`，Claude 默认用 UUID 形态的 `{summary_session_uuid}`。hook 会启动后台 worker，worker 先确定性提取 transcript core messages + existing memory，写入 `<repo-memory>/jobs/session-summary/inputs/*.json`，再把这份 JSON 内联进 `{prompt}`；agent 只输出 summary-output JSON，不调用 CLI、不移动 job。worker 会校验 JSON，格式错误时用同一个 summary session 最多重试 3 次，然后由代码执行 `apply-summary-output` 并迁移 pending/done/skipped/failed；无 touched targets 的空总结进入 `skipped/`，不刷新 capture manifest，不算真实落盘
+- `DEV_MEMORY_SESSION_SUMMARY_CMD` 只作为临时调试 override；要禁用后台 summarizer，可清掉配置里的 `session_summary.command`，或设置 `DEV_MEMORY_DISABLE_SESSION_SUMMARY_AGENT=1`
 - 全局 skill 安装不会自动加载 hook —— 这是一个 skill suite，不是独立 agent 插件
 
 ## CLI 入口
@@ -279,7 +301,7 @@ CLI 暴露的子命令：
 | 安装助手 | `dev-memory-cli install-hooks <codex\|claude\|--all>` | 把 hook 模板合并到目标配置 |
 | 浏览器 UI | `dev-memory-cli ui [--port N] [--read-only]` | 启动本地浏览器界面看/编辑记忆 |
 | 分支生命周期 | `dev-memory-cli branch [list\|inspect\|rename\|fork\|delete\|init]` | 分支记忆迁移 / 副本 / 重置（无参数 = 交互式 type-ahead）|
-| Skill 工作流（agent 在 SKILL.md 里调用，也能手动跑）| `dev-memory-cli capture <record\|rewrite-entry\|show\|suggest-kind\|...>` | 统一写入入口（含 0.18 起的 dedup 拦截 + rewrite-entry） |
+| Skill 工作流（agent 在 SKILL.md 里调用，也能手动跑）| `dev-memory-cli capture <record\|rewrite-entry\|delete-entry\|apply-summary-output\|show\|suggest-kind\|...>` | 统一写入入口（含 dedup、结构化 patch executor） |
 | | `dev-memory-cli setup <init\|merge-unsorted\|mark-completed>` | 整理 unsorted |
 | | `dev-memory-cli tidy <prepare\|apply>` | 浏览器化的批量 review + 落盘（0.18 起含 annotated md + delete-block）|
 | | `dev-memory-cli graduate <dry-run\|apply\|index>` | 分支归档 + 跨分支知识上提 |

package/bin/dev-memory.js

@@ -7,6 +7,7 @@ const os = require("node:os");
 
 const PACKAGE_ROOT = path.resolve(__dirname, "..");
 const DEFAULT_STORAGE_ROOT = path.join(os.homedir(), ".dev-memory", "repos");
+const DEFAULT_CONFIG_PATH = process.env.DEV_MEMORY_CONFIG_PATH || path.join(os.homedir(), ".dev-memory", "config.json");
 
 function fail(message) {
   process.stderr.write(`ERROR: ${message}\n`);
@@ -116,6 +117,72 @@ function writeJson(filePath, data) {
   fs.writeFileSync(filePath, `${JSON.stringify(data, null, 2)}\n`, "utf8");
 }
 
+function commandExists(command) {
+  const result = spawnSync("sh", ["-lc", `command -v ${command}`], {
+    encoding: "utf8",
+    stdio: ["ignore", "pipe", "ignore"],
+  });
+  return result.status === 0 && Boolean((result.stdout || "").trim());
+}
+
+function detectSessionSummaryCommand() {
+  if (commandExists("coco")) {
+    return {
+      provider: "coco",
+      command: "coco -p --yolo --session-id {summary_session_id} {prompt}",
+    };
+  }
+  if (commandExists("codex")) {
+    return {
+      provider: "codex",
+      command: "codex exec --ignore-user-config --ignore-rules --skip-git-repo-check --sandbox danger-full-access {prompt}",
+    };
+  }
+  if (commandExists("claude")) {
+    return {
+      provider: "claude",
+      command: "claude -p --permission-mode bypassPermissions --session-id {summary_session_uuid} {prompt}",
+    };
+  }
+  return null;
+}
+
+function ensureSessionSummaryConfig() {
+  const configPath = DEFAULT_CONFIG_PATH;
+  const existing = fs.existsSync(configPath) ? loadJson(configPath) : {};
+  const config = existing && typeof existing === "object" ? existing : {};
+  const sessionSummary = config.session_summary && typeof config.session_summary === "object"
+    ? { ...config.session_summary }
+    : {};
+  if (typeof sessionSummary.command === "string" && sessionSummary.command.trim()) {
+    return {
+      path: configPath,
+      changed: false,
+      provider: sessionSummary.provider || null,
+      command: sessionSummary.command,
+    };
+  }
+  const detected = detectSessionSummaryCommand();
+  if (!detected) {
+    return { path: configPath, changed: false, provider: null, command: null };
+  }
+  config.session_summary = {
+    ...sessionSummary,
+    provider: detected.provider,
+    command: detected.command,
+    max_attempts: sessionSummary.max_attempts || 3,
+    configured_at: new Date().toISOString(),
+    source: "install-hooks:auto-detect",
+  };
+  writeJson(configPath, config);
+  return {
+    path: configPath,
+    changed: true,
+    provider: detected.provider,
+    command: detected.command,
+  };
+}
+
 function templatePathForAgent(agent) {
   if (agent === "codex") return packageScript("hooks", "codex-hooks.json");
   if (agent === "claude") return packageScript("hooks", "hooks.json");
@@ -186,7 +253,14 @@ function installHooksForAgent(agent, options) {
   const existing = fs.existsSync(targetPath) ? loadJson(targetPath) : {};
   const merged = mergeConfig(existing, template);
   writeJson(targetPath, merged);
-  const report = { agent, scope, target: targetPath, events: Object.keys(template.hooks || {}) };
+  const summaryConfig = ensureSessionSummaryConfig();
+  const report = {
+    agent,
+    scope,
+    target: targetPath,
+    events: Object.keys(template.hooks || {}),
+    session_summary_config: summaryConfig,
+  };
   if (repoRoot) report.repo_root = repoRoot;
   return report;
 }
@@ -216,6 +290,7 @@ const PY_SUBCOMMAND_SCRIPTS = {
   setup: "dev_memory_setup.py",
   graduate: "dev_memory_graduate.py",
   tidy: "dev_memory_tidy.py",
+  summary: "dev_memory_summary.py",
 };
 
 function commandPySubcommand(name, rawArgs) {
@@ -546,6 +621,7 @@ function printHelp() {
   dev-memory-cli setup <init|merge-unsorted|mark-completed> [...]
   dev-memory-cli graduate <dry-run|apply|index> [...]
   dev-memory-cli tidy <prepare|apply> [...]
+  dev-memory-cli summary <extract-core> [...]
   dev-memory-cli branch [list|inspect|rename|fork|delete|init|inherit-worktree-base] [...]   # no subcommand = interactive
 
 Environment:

package/hooks/README.md

@@ -54,13 +54,19 @@ dev-memory-cli install-hooks claude
 语义分别是：
 
 - `SessionStart`
-  读取当前 repo+branch 的 dev-memory，并把可恢复上下文注入新会话
+  读取当前 repo+branch 的 dev-memory，并把可恢复上下文注入新会话；同一 session resume 重触发时通过
+  `<repo-memory>/jobs/session-start/injected/*.json` 幂等跳过重复注入，只写 skip 日志并返回空 payload
 - `PreCompact`
   在上下文压缩前刷新 working-tree 派生导航信息
 - `Stop`
   在每次回复后记录轻量 HEAD 标记
 - `SessionEnd`
-  在会话结束时再落一次最终 HEAD 标记
+  在会话结束时再落一次最终 HEAD 标记，并把 transcript 总结任务 enqueue 到
+  `<repo-memory>/jobs/session-summary/pending/`。`install-hooks` 会扫描本地工具并写入
+  `~/.dev-memory/config.json` 的 `session_summary.command`（优先 coco，其次 codex，再 claude）。hook 会启动后台 worker，先生成
+  `<repo-memory>/jobs/session-summary/inputs/*.json`，再把已提取的 core messages 和 existing memory
+  内联进 `{prompt}`。agent 只输出 summary-output JSON，不调用 CLI；worker 负责 JSON 校验、同 session 最多 3 次重试、落盘和 pending/done/skipped/failed 迁移；无 touched targets 的空总结进入 `skipped/`，不算真实落盘。hook 不等待总结完成。`DEV_MEMORY_SESSION_SUMMARY_CMD` 仅作临时 override，禁用用
+  `DEV_MEMORY_DISABLE_SESSION_SUMMARY_AGENT=1`
 
 ## 和 ECC 的差异
 

package/hooks/hooks.json

@@ -52,7 +52,7 @@
             "timeout": 15
           }
         ],
-        "description": "Persist final HEAD marker at session end",
+        "description": "Persist final HEAD marker and enqueue transcript summary work",
         "id": "dev-memory:session-end"
       }
     ]