dev-memory-cli 0.23.1 → 0.25.0

package/README.md

@@ -1,6 +1,6 @@
 # Dev Memory Skill Suite
 
-Dev Memory Skill Suite 为 Codex、Claude 等 coding agent 提供跨会话开发记忆能力。
+Dev Memory Skill Suite 为 Codex、Claude Code、Trae / Trae CN 等 coding agent 提供跨会话开发记忆能力。
 
 开发知识存储在用户目录，并按 **仓库身份 + Git 分支** 隔离。分支层保存当前工作的目标、约束和上下文，repo 层保存跨分支长期有效的规则与资料入口。Git 负责提交与代码历史，dev-memory 负责对后续开发仍有价值的语义信息。
 
@@ -9,7 +9,7 @@ Dev Memory Skill Suite 为 Codex、Claude 等 coding agent 提供跨会话开发
 ## 核心能力
 
 - **会话恢复**：`SessionStart` 自动注入当前 repo + branch 的浓缩记忆和权威文件路径。
-- **语义化写入**：按 decision、risk、glossary、source、overview 等 kind 写入对应文件。
+- **后台语义沉淀**：定期读取完整会话，对照已有记忆后执行 append、rewrite、delete 或明确 skip。
 - **纠错优先**：修正旧记忆时定位并改写原 entry，避免同时保留互相冲突的新旧结论。
 - **分支隔离**：同一仓库的不同分支拥有独立工作记忆，可 fork、rename、reset 或归档。
 - **跨分支共享**：稳定规则进入 repo 层；候选知识可在分支完成时提炼上提。
@@ -17,17 +17,13 @@ Dev Memory Skill Suite 为 Codex、Claude 等 coding agent 提供跨会话开发
 - **多仓库工作区**：一个 workspace 下可同时加载多个 repo，并为主仓库保留更完整的上下文。
 - **本地管理面板**：浏览、编辑已存储记忆，预览 SessionStart 注入文本，并查看会话扫描与 token 用量。
 
-## 五个 Skill
+## 一个常驻 Skill
 
 | Skill | 职责 | 适用场景 |
 | --- | --- | --- |
 | `dev-memory-read` | 定位并搜索当前 repo/branch 的权威记忆，只读不写 | 主动恢复既有记忆、查询历史 TODO |
-| `dev-memory-capture` | 写入、改写或删除记忆；同步 Git 派生索引 | 稳定结论沉淀、纠错、阶段 checkpoint |
-| `dev-memory-setup` | 把 `unsorted.md` 中的内容分类合并到结构化文件 | 未分类内容整理、记忆结构初始化 |
-| `dev-memory-tidy` | 批量审查陈旧、重复、错误或模板残留条目，备份后应用 | 结构化记忆校准与清理 |
-| `dev-memory-graduate` | 提炼跨分支知识并归档已完成分支 | 分支收尾与归档 |
 
-Skill 定义触发语义与协作流程，文件操作统一由 `dev-memory-cli` 执行。
+普通开发会话不再常驻 capture/setup/tidy/graduate Skill。会话写入由 session-scan 后台处理；整理和归档由 CLI 临时启动专用维护 Agent，并只把对应维护 prompt 放进那个独立会话。
 
 ## 安装
 
@@ -44,13 +40,13 @@ npx skills add xluos/dev-memory-skill-suite --list
 安装到 Codex 全局：
 
 ```bash
-npx skills add xluos/dev-memory-skill-suite --skill '*' -a codex -g -y
+npx skills add xluos/dev-memory-skill-suite --skill dev-memory-read -a codex -g -y
 ```
 
 安装到检测到的所有 agent：
 
 ```bash
-npx skills add xluos/dev-memory-skill-suite --all -g -y
+npx skills add xluos/dev-memory-skill-suite --skill dev-memory-read --all -g -y
 ```
 
 ### 安装 CLI 与 Hook
@@ -61,8 +57,10 @@ npm install -g dev-memory-cli
 # 在当前仓库安装生命周期 hook
 dev-memory-cli install-hooks codex
 dev-memory-cli install-hooks claude
+dev-memory-cli install-hooks trae
+dev-memory-cli install-hooks trae-cn
 
-# 或一次安装两套
+# 或一次安装全部支持的客户端
 dev-memory-cli install-hooks --all
 ```
 
@@ -74,6 +72,8 @@ dev-memory-cli install-hooks --all --global
 
 CLI 也可通过 `npx -y dev-memory-cli ...` 按需执行。Skill 与 hook 相互独立，安装 skill 不会修改本地 hook 配置。
 
+Trae 的 Hook 配置按客户端隔离：国际版写入 `.trae/hooks.json`，国内版写入 `.trae-cn/hooks.json`；加 `--global` 时分别写入用户目录下的同名路径。已有 Hook 会保留，重复安装只更新 dev-memory 自己的条目。
+
 Codex Desktop 没有本仓库依赖的项目生命周期 hook。安装每日扫描任务可覆盖 Codex CLI 和 Desktop 共同写入的本机会话文件：
 
 ```bash
@@ -85,27 +85,23 @@ dev-memory-cli session-scan status
 
 ## 基本使用
 
-写入操作具备 lazy initialization。存储骨架缺失时自动创建，setup 不作为写入前置条件。
+记忆是显式 opt-in。首次使用先初始化，然后由生命周期 hook 恢复、由定期 session-scan 沉淀新会话语义。
 
 ```bash
+# 为当前 repo + branch 初始化记忆骨架
+dev-memory-cli init
+
 # 查看当前仓库和分支对应的记忆路径
 dev-memory-cli read show
 
 # 只在当前 repo 的记忆范围内搜索
 dev-memory-cli read search --query "发布流程" --query "回滚"
 
-# 写入一条分支决策
-dev-memory-cli capture record \
-  --kind decision \
-  --content "发布前必须先跑完整打包检查"
-
-# 写入一条跨分支规则
-dev-memory-cli capture record \
-  --kind shared-decision \
-  --content "Python 测试优先使用项目虚拟环境"
+# 启动独立整理 Agent（不会把整理 prompt 放进普通开发会话）
+dev-memory-cli maintain tidy
 
-# 刷新 Git working tree 派生的文件索引
-dev-memory-cli capture sync-working-tree
+# 启动独立归档 Agent
+dev-memory-cli maintain archive --branch feature/example
 ```
 
 `read search` 默认搜索当前 branch + repo 共享层。跨分支和归档范围通过 `--scope` 显式指定：
@@ -115,11 +111,11 @@ dev-memory-cli read search --scope all-branches --query "关键词"
 dev-memory-cli read search --scope archived --query "关键词"
 ```
 
-### 写入路由
+### 底层写入路由
 
 ![Capture 写入路由](docs/diagrams/capture.png)
 
-`capture record` 支持三种输入方式：
+`capture` 是 session-scan 和维护 Agent 使用的底层写入引擎，同时保留为高级管理 CLI；它不再对应常驻 Skill。`capture record` 支持三种输入方式：
 
 - **显式 kind**：调用方明确指定内容语义，直接写目标 section。
 - **自动分类**：`--auto` 根据文本信号判断 decision、risk、glossary；无法明确分类时进入 `unsorted.md`。
@@ -150,19 +146,18 @@ dev-memory-cli capture rewrite-entry --id <entry-id> --content "修正后的完
 dev-memory-cli capture delete-entry --id <entry-id>
 ```
 
-符合跨分支复用判定的内容会同时进入 `pending-promotion.md`，由 graduate 在分支收尾阶段审核；候选内容不会直接写入 repo 共享层。
+符合跨分支复用判定的内容会同时进入 `pending-promotion.md`，由归档维护 Agent 在分支收尾阶段审核；候选内容不会直接写入 repo 共享层。
 
 ### 整理与归档
 
-三个维护动作边界不同：
+普通入口只有两个，都会启动独立交互式 Agent：
 
-| 动作 | 处理对象 | 结果 |
+| 命令 | 处理对象 | 结果 |
 | --- | --- | --- |
-| `setup` | `unsorted.md` 中尚未分类的内容 | 合并到 decisions、risks、glossary 或 repo 共享层 |
-| `tidy` | 已结构化但陈旧、重复或错误的内容 | proposal 审核，备份后 edit/delete/reset |
-| `graduate` | 已完成分支的有效记忆 | 上提跨分支知识，并把分支目录移入 `_archived` |
+| `dev-memory-cli maintain tidy` | `unsorted.md` 与已结构化但漂移的内容 | 分类、proposal HTML 审核、备份后 edit/delete/reset |
+| `dev-memory-cli maintain archive` | 已完成分支的有效记忆 | dry-run、上提跨分支知识、确认后移入 `_archived` |
 
-`tidy apply` 和 `graduate apply` 会改变或移动已有记忆，仅在显式调用后执行。
+维护 Agent 内部使用 `setup`、`tidy`、`graduate` 等低层子命令。`tidy apply` 和 `graduate apply` 会改变或移动已有记忆，仍然受人工审核和显式确认门禁保护。用 `--print-prompt` 可以只查看将传给独立 Agent 的完整维护指令。
 
 ### 分支记忆操作
 
@@ -187,18 +182,18 @@ git config --local dev-memory.worktreeWriteback true
 
 ## 生命周期 Hook
 
-| 事件 | Codex CLI | Claude Code CLI | 行为 |
-| --- | :-: | :-: | --- |
-| `SessionStart` | ✓ | ✓ | 刷新 Git 派生索引，注入浓缩记忆和完整文件路径；同一 session 幂等 |
-| `Stop` | ✓ | ✓ | 记录轻量 HEAD marker；Codex 同时登记待扫描会话，不启动模型 |
-| `PreCompact` |  | ✓ | 兼容占位，当前不执行额外刷新 |
-| `SessionEnd` |  | ✓ | 记录最终 HEAD，并把 transcript 总结任务放入后台队列 |
+| 事件 | Codex CLI | Claude Code CLI | Trae | Trae CN | 行为 |
+| --- | :-: | :-: | :-: | :-: | --- |
+| `SessionStart` | ✓ | ✓ | ✓ | ✓ | 刷新 Git 派生索引，注入浓缩记忆和完整文件路径；同一 session 幂等 |
+| `Stop` | ✓ | ✓ | ✓ | ✓ | 记录轻量 HEAD marker；有可识别会话信息时登记扫描候选，不启动模型 |
+| `PreCompact` |  | ✓ |  |  | 兼容占位，当前不执行额外刷新 |
+| `SessionEnd` |  | ✓ |  |  | 记录最终 HEAD，并把 transcript 总结任务放入后台队列 |
 
 ### 会话总结
 
-Claude Code CLI 通过 `SessionEnd` 创建后台总结任务。Codex CLI 没有 `SessionEnd`，其 `Stop` hook 只登记候选；Codex Desktop 不依赖 hook。Codex 两种入口统一由每日扫描器读取 `~/.codex/sessions` 和 `~/.codex/archived_sessions`。
+Claude Code CLI 通过 `SessionEnd` 创建后台总结任务。Codex、Trae 和 Trae CN 当前没有该事件：它们的 `Stop` hook 只做轻量记录，并在 payload 带有可识别会话信息时登记扫描候选，不会在每轮回复后启动总结模型。现有定时扫描器只解析 Codex CLI / Desktop 写入的 `~/.codex/sessions` 和 `~/.codex/archived_sessions`；Trae Hook 支持当前覆盖 SessionStart 恢复与轻量 HEAD 刷新，不宣称扫描其私有会话存储。
 
-任务触发端与总结执行端相互独立。Claude 的即时 worker 和 Codex 定时扫描器都可以使用 `coco`、`codex` 或 `claude` CLI。扫描器在 `~/.dev-memory/config.json` 的 `session_scan` 中内置三个可配置 preset，默认按 `coco → codex → claude` 选择第一个可用命令；每个 preset 可指定模型、profile、额外参数和环境变量。
+任务触发端与总结执行端相互独立。Claude 的即时 worker 和 Codex 定时扫描器都可以使用 `coco`、`codex` 或 `claude` CLI。扫描器在 `~/.dev-memory/config.json` 的 `session_scan` 中内置三个可配置 preset，默认按 `claude → codex` 选择第一个可用命令；`coco` preset 继续保留，可显式启用或加入顺序。每个 preset 可指定模型、profile、额外参数和环境变量。
 
 总结输入包含全部尚未处理的 user/assistant 语义消息和现有 dev-memory，不按“最近几条”截尾，也不截断单条消息。长会话按顺序分块并最终归并；工具调用流水账、system 消息和 reasoning 不参与语义总结。输出限定为结构化 JSON，用于新增或修正 decisions、risks、glossary、file map 和 repo 共享记忆；时效性的“当前进展”“下一步”“当前阶段”不会写入。
 
@@ -251,7 +246,7 @@ dev-memory-cli workspace show
 dev-memory-cli workspace primary <repo-basename>
 ```
 
-`DEV_MEMORY_PRIMARY_REPO` 可作为临时 override。Skill 在 workspace 中写入时应使用 `--repo <repo-path-or-basename>` 明确目标仓库。
+`DEV_MEMORY_PRIMARY_REPO` 可作为临时 override。维护命令在 workspace 中应使用 `--repo <repo-path-or-basename>` 明确目标仓库。
 
 ## 存储结构
 
@@ -327,6 +322,9 @@ dev-memory-cli context injection-preview \
 
 ```text
 dev-memory-cli read <show|search>
+dev-memory-cli init [--repo PATH] [--branch NAME]
+dev-memory-cli maintain <tidy|archive> [--repo PATH] [--branch NAME] [--executor auto|codex|coco]
+# low-level mutation/admin commands:
 dev-memory-cli capture <show|suggest-kind|classify|record|list-entries|find-candidates|rewrite-entry|delete-entry|apply-summary-output|sync-working-tree|record-head>
 dev-memory-cli setup <init|merge-unsorted|mark-completed>
 dev-memory-cli tidy <prepare|apply>
@@ -338,7 +336,7 @@ dev-memory-cli summary <extract-core>
 dev-memory-cli session-scan <run|replay|install|status|stats|history|show|uninstall|config>
 dev-memory-cli hook <session-start|pre-compact|stop|session-end>
 dev-memory-cli ui
-dev-memory-cli install-hooks <codex|claude|--all>
+dev-memory-cli install-hooks <codex|claude|trae|trae-cn|--all>
 ```
 
 具体参数以各子命令的 `--help` 为准。
@@ -360,11 +358,12 @@ dev-memory 的能力边界不包括：
 ```text
 bin/dev-memory.js              # CLI 入口与 Node 侧命令
 lib/dev_memory_*.py            # 记忆、分支、会话扫描、整理与归档实现
+lib/maintenance/               # 按需注入独立维护 Agent 的 prompt
 lib/ui-server.js               # 本地管理面板服务
 lib/ui-app.html                # 管理面板前端
 scripts/hooks/                 # 生命周期 hook 实现
-hooks/                         # Codex / Claude hook 模板
-skills/                        # 五个 skill 的声明与工作流
+hooks/                         # Codex / Claude Code / Trae hook 模板
+skills/dev-memory-read/        # 唯一常驻 Skill
 tests/                         # Python 测试
 docs/diagrams/                 # README 图表及源文件
 ```

package/bin/dev-memory.js

@@ -9,6 +9,7 @@ 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");
 const WORKSPACE_CONFIG_NAME = ".dev-memory-workspace.json";
+const SUPPORTED_HOOK_AGENTS = ["codex", "claude", "trae", "trae-cn"];
 
 function fail(message) {
   process.stderr.write(`ERROR: ${message}\n`);
@@ -191,32 +192,54 @@ function ensureSessionSummaryConfig() {
 function templatePathForAgent(agent) {
   if (agent === "codex") return packageScript("hooks", "codex-hooks.json");
   if (agent === "claude") return packageScript("hooks", "hooks.json");
+  if (agent === "trae" || agent === "trae-cn") return packageScript("hooks", "trae-hooks.json");
   fail(`unsupported agent: ${agent}`);
 }
 
 function targetPathForAgent(agent, repoRoot) {
   if (agent === "codex") return path.join(repoRoot, ".codex", "hooks.json");
   if (agent === "claude") return path.join(repoRoot, ".claude", "settings.local.json");
+  if (agent === "trae") return path.join(repoRoot, ".trae", "hooks.json");
+  if (agent === "trae-cn") return path.join(repoRoot, ".trae-cn", "hooks.json");
   fail(`unsupported agent: ${agent}`);
 }
 
 function globalTargetPathForAgent(agent) {
   if (agent === "codex") return path.join(os.homedir(), ".codex", "hooks.json");
   if (agent === "claude") return path.join(os.homedir(), ".claude", "settings.json");
+  if (agent === "trae") return path.join(os.homedir(), ".trae", "hooks.json");
+  if (agent === "trae-cn") return path.join(os.homedir(), ".trae-cn", "hooks.json");
   fail(`unsupported agent: ${agent}`);
 }
 
+function hookListIdentity(item) {
+  if (!item || typeof item !== "object") return null;
+  if (typeof item.id === "string" && item.id) {
+    return `id:${item.id}\u0000${item.matcher || ""}`;
+  }
+  const nestedHooks = Array.isArray(item.hooks) ? item.hooks : [];
+  for (const hook of nestedHooks) {
+    const command = hook && typeof hook.command === "string" ? hook.command.trim() : "";
+    const match = command.match(/(?:^|\s)dev-memory-cli\s+hook\s+(session-start|pre-compact|stop|session-end)(?:\s|$)/);
+    if (match) return `dev-memory-command:${match[1]}`;
+  }
+  return null;
+}
+
 function mergeHookLists(existingItems, incomingItems) {
   const merged = existingItems.map((item) => ({ ...item }));
   const index = new Map();
-  merged.forEach((item, i) => index.set(`${item.id || ""}\u0000${item.matcher || ""}`, i));
+  merged.forEach((item, i) => {
+    const key = hookListIdentity(item);
+    if (key) index.set(key, i);
+  });
   for (const item of incomingItems) {
     const copied = { ...item };
-    const key = `${copied.id || ""}\u0000${copied.matcher || ""}`;
-    if (index.has(key)) {
+    const key = hookListIdentity(copied);
+    if (key && index.has(key)) {
       merged[index.get(key)] = copied;
     } else {
-      index.set(key, merged.length);
+      if (key) index.set(key, merged.length);
       merged.push(copied);
     }
   }
@@ -224,7 +247,7 @@ function mergeHookLists(existingItems, incomingItems) {
 }
 
 function mergeConfig(existingConfig, templateConfig) {
-  const result = { ...existingConfig };
+  const result = { ...templateConfig, ...existingConfig };
   const existingHooks = existingConfig.hooks || {};
   const templateHooks = templateConfig.hooks || {};
   const mergedHooks = {};
@@ -272,7 +295,7 @@ function installHooksForAgent(agent, options) {
 
 function commandInstallHooks(positional, options) {
   const isAll = Boolean(options.all);
-  const agents = isAll ? ["codex", "claude"] : [positional[0] || options.agent || "codex"];
+  const agents = isAll ? SUPPORTED_HOOK_AGENTS : [positional[0] || options.agent || "codex"];
   const reports = agents.map((agent) => installHooksForAgent(agent, options));
   process.stdout.write(`${JSON.stringify(isAll ? reports : reports[0], null, 2)}\n`);
 }
@@ -376,6 +399,112 @@ function commandPySubcommand(name, rawArgs) {
   runPython(scriptPath, rawArgs);
 }
 
+const MAINTENANCE_MODES = new Set(["tidy", "archive"]);
+const MAINTENANCE_MARKER = "DEV_MEMORY_INTERNAL_MAINTENANCE_AGENT_V1";
+
+function maintenanceHelp() {
+  process.stdout.write(`Usage:
+  dev-memory-cli maintain tidy [--repo PATH] [--branch NAME] [--scope branch|branch+repo]
+                                  [--executor auto|codex|coco] [--model MODEL]
+  dev-memory-cli maintain archive [--repo PATH] [--branch NAME]
+                                     [--executor auto|codex|coco] [--model MODEL]
+  dev-memory-cli maintain <tidy|archive> --print-prompt [other options]
+
+The command starts a dedicated interactive maintenance-agent session. Tidy
+must not apply destructive changes before HTML review; archive must not apply
+before dry-run review and explicit confirmation.
+`);
+}
+
+function resolveMaintenanceExecutor(requested) {
+  const name = requested || process.env.DEV_MEMORY_MAINTENANCE_EXECUTOR || "auto";
+  if (!new Set(["auto", "codex", "coco"]).has(name)) {
+    fail(`unsupported maintenance executor: ${name}`);
+  }
+  if (name !== "auto") return name;
+  for (const candidate of ["codex", "coco"]) {
+    if (commandExists(candidate)) return candidate;
+  }
+  fail("no maintenance executor found; install codex/coco or use --print-prompt");
+}
+
+function buildMaintenancePrompt(mode, options, repoRoot) {
+  const promptPath = packageScript("lib", "maintenance", `${mode}.md`);
+  if (!fs.existsSync(promptPath)) fail(`missing maintenance prompt: ${promptPath}`);
+  const workflow = fs.readFileSync(promptPath, "utf8").trim();
+  const cliPath = path.resolve(process.argv[1]);
+  const branch = options.branch || "<current-git-branch>";
+  const scope = mode === "tidy" ? (options.scope || "branch") : "branch";
+  return `${MAINTENANCE_MARKER}
+
+你是 dev-memory 的专用维护 Agent。本会话只处理下面指定仓库的记忆维护，不承担普通开发任务。
+
+目标仓库：${repoRoot}
+目标分支：${branch}
+维护模式：${mode}
+整理范围：${scope}
+本次必须使用的 CLI：node ${JSON.stringify(cliPath)}
+
+不要依赖全局 dev-memory capture/setup/tidy/graduate Skill；完整维护流程已经随本提示提供。
+涉及删除、改写或归档时，必须遵守下面流程中的人工审核和确认门禁。
+
+${workflow}
+`;
+}
+
+function commandMaintain(rawArgs) {
+  const mode = rawArgs[0];
+  if (!mode || mode === "--help" || mode === "-h") {
+    maintenanceHelp();
+    return;
+  }
+  if (!MAINTENANCE_MODES.has(mode)) {
+    fail(`unknown maintenance mode: ${mode}`);
+  }
+  const { positional, options } = parseArgs(rawArgs.slice(1));
+  if (positional.length) fail(`unexpected maintenance argument: ${positional[0]}`);
+  const repoRoot = path.resolve(options.repo || process.cwd());
+  if (!fs.existsSync(repoRoot) || !fs.statSync(repoRoot).isDirectory()) {
+    fail(`maintenance repo does not exist: ${repoRoot}`);
+  }
+  if (mode === "tidy" && options.scope && !new Set(["branch", "branch+repo"]).has(options.scope)) {
+    fail(`unsupported tidy scope: ${options.scope}`);
+  }
+  const prompt = buildMaintenancePrompt(mode, options, repoRoot);
+  if (options["print-prompt"] || options["dry-run"]) {
+    process.stdout.write(prompt);
+    return;
+  }
+
+  const executor = resolveMaintenanceExecutor(options.executor);
+  let args;
+  if (executor === "codex") {
+    const modelArgs = options.model ? ["--model", String(options.model)] : [];
+    args = [
+      "-C", repoRoot,
+      "--sandbox", "danger-full-access",
+      "--ask-for-approval", "on-request",
+      "--dangerously-bypass-hook-trust",
+      ...modelArgs,
+      prompt,
+    ];
+  } else {
+    const modelArgs = options.model ? ["--config", `model=${String(options.model)}`] : [];
+    args = ["--permission-mode", "default", ...modelArgs, prompt];
+  }
+  const result = spawnSync(executor, args, {
+    cwd: repoRoot,
+    env: {
+      ...process.env,
+      DEV_MEMORY_MAINTENANCE_AGENT: "1",
+      DEV_MEMORY_MAINTENANCE_MODE: mode,
+    },
+    stdio: "inherit",
+  });
+  if (result.error) fail(`unable to start ${executor}: ${result.error.message}`);
+  if (result.status !== 0) process.exit(result.status || 1);
+}
+
 function branchScript() {
   return packageScript("lib", "dev_memory_branch.py");
 }
@@ -688,12 +817,15 @@ function commandBranch(rawArgs) {
 function printHelp() {
   process.stdout.write(`Usage:
   dev-memory-cli hook <session-start|pre-compact|stop|session-end> [--repo PATH]
-  dev-memory-cli install-hooks <codex|claude> [--repo PATH] [--global]
+  dev-memory-cli install-hooks <codex|claude|trae|trae-cn> [--repo PATH] [--global]
   dev-memory-cli install-hooks --all [--repo PATH] [--global]
   dev-memory-cli ui [--port N] [--host HOST] [--no-open] [--read-only]
   dev-memory-cli workspace <show|primary> [...]
+  dev-memory-cli init [--repo PATH] [--branch NAME]
   dev-memory-cli read <show|search> [...]
+  dev-memory-cli maintain <tidy|archive> [...]   # starts a dedicated interactive agent
   dev-memory-cli context <show|...> [...]
+  # Low-level mutation/admin commands used by session-scan and maintenance agents:
   dev-memory-cli capture <record|show|sync-working-tree|record-head|suggest-kind|classify> [...]
   dev-memory-cli setup <init|merge-unsorted|mark-completed> [...]
   dev-memory-cli graduate <dry-run|apply|index> [...]
@@ -719,6 +851,14 @@ function main() {
     commandPySubcommand(command, argv.slice(1));
     return;
   }
+  if (command === "init") {
+    commandPySubcommand("setup", ["init", ...argv.slice(1)]);
+    return;
+  }
+  if (command === "maintain") {
+    commandMaintain(argv.slice(1));
+    return;
+  }
   if (command === "branch") {
     commandBranch(argv.slice(1));
     return;

package/hooks/README.md

@@ -1,16 +1,24 @@
 # Lifecycle Hooks
 
-本项目使用 agent 生命周期 hook，不使用 Git hook。Claude Code 与 Codex 的可用事件不同，模板分别维护。
+本项目使用 agent 生命周期 hook，不使用 Git hook。Claude Code、Codex、Trae 与 Trae CN 的可用事件和配置目录不同，模板分别维护。
 
 ## 当前仓库里的接入方式
 
 - repo-local 配置位置：
   - Claude: `.claude/settings.local.json`
   - Codex: `.codex/hooks.json`
+  - Trae: `.trae/hooks.json`
+  - Trae CN: `.trae-cn/hooks.json`
+- user-level 配置位置：
+  - Claude: `~/.claude/settings.json`
+  - Codex: `~/.codex/hooks.json`
+  - Trae: `~/.trae/hooks.json`
+  - Trae CN: `~/.trae-cn/hooks.json`
 - 可复用模板：
   - Claude: [hooks/hooks.json](hooks.json)
   - Codex: [hooks/codex-hooks.json](codex-hooks.json)
-- `dev-memory-cli` 是这两套配置共用的稳定执行入口
+  - Trae / Trae CN: [hooks/trae-hooks.json](trae-hooks.json)
+- `dev-memory-cli` 是所有配置共用的稳定执行入口
 - hook 仅在模板内容合并到对应 agent 配置后生效
 
 ### Codex 快速安装
@@ -34,18 +42,21 @@ sh -c "$(curl -fsSL https://raw.githubusercontent.com/xluos/dev-memory-skill-sui
 ```bash
 dev-memory-cli install-hooks codex
 dev-memory-cli install-hooks claude
+dev-memory-cli install-hooks trae
+dev-memory-cli install-hooks trae-cn
+dev-memory-cli install-hooks --all
 ```
 
 已有旧配置如果还写着 `dev-memory hook ...` 或 `npx dev-memory hook ...`，重新执行安装命令会按 hook id 覆盖为 `dev-memory-cli hook ...`。
 
 ## Hook 行为
 
-| 事件 | Codex CLI | Claude Code CLI | 行为 |
-| --- | :-: | :-: | --- |
-| `SessionStart` | ✓ | ✓ | 读取当前 repo+branch 记忆并注入会话；同一 session 的重复触发幂等跳过 |
-| `Stop` | ✓ | ✓ | 每次回复后记录轻量 HEAD marker；Codex 同时登记定时扫描候选 |
-| `PreCompact` |  | ✓ | 兼容占位；当前不执行额外刷新 |
-| `SessionEnd` |  | ✓ | 记录最终 HEAD，创建 transcript 总结任务并启动后台 worker |
+| 事件 | Codex CLI | Claude Code CLI | Trae | Trae CN | 行为 |
+| --- | :-: | :-: | :-: | :-: | --- |
+| `SessionStart` | ✓ | ✓ | ✓ | ✓ | 读取当前 repo+branch 记忆并注入会话；同一 session 的重复触发幂等跳过 |
+| `Stop` | ✓ | ✓ | ✓ | ✓ | 每次回复后记录轻量 HEAD marker；payload 有会话信息时登记扫描候选 |
+| `PreCompact` |  | ✓ |  |  | 兼容占位；当前不执行额外刷新 |
+| `SessionEnd` |  | ✓ |  |  | 记录最终 HEAD，创建 transcript 总结任务并启动后台 worker |
 
 `SessionStart` 的幂等记录位于 `<repo-memory>/jobs/session-start/injected/*.json`。重复触发只记录 skip 日志，不重复注入上下文。
 
@@ -53,7 +64,7 @@ dev-memory-cli install-hooks claude
 
 ### 生效范围
 
-`SessionEnd` 自动总结仅由 **Claude Code CLI** 的生命周期事件触发。Codex CLI hook 模板没有 `SessionEnd`；它的 `Stop` 只登记候选，不在每轮回答后启动模型。Codex Desktop 不使用这组项目 hook。
+`SessionEnd` 自动总结仅由 **Claude Code CLI** 的生命周期事件触发。Codex、Trae 和 Trae CN 模板都不注册 `SessionEnd`；它们的 `Stop` 只做轻量记录，不在每轮回答后启动模型。Codex Desktop 不使用这组项目 hook。
 
 总结任务的触发端与执行端是两个独立概念：
 
@@ -138,13 +149,13 @@ dev-memory-cli session-scan status
 
 ### 执行器配置
 
-`~/.dev-memory/config.json` 中的 `session_scan` 独立配置扫描执行器。默认提供 `coco`、`codex`、`claude` 三个 preset，并按顺序选择第一个已安装且启用的命令：
+`~/.dev-memory/config.json` 中的 `session_scan` 独立配置扫描执行器。默认提供 `coco`、`codex`、`claude` 三个 preset，并按 `claude → codex` 选择第一个已安装且启用的命令；`coco` preset 为兼容保留，可显式加入 `order`：
 
 ```json
 {
   "session_scan": {
     "executor": "auto",
-    "order": ["coco", "codex", "claude"],
+    "order": ["claude", "codex"],
     "schedule_times": ["03:00", "13:00"],
     "skip_when_computer_active": true,
     "active_within_minutes": 10,
@@ -214,6 +225,8 @@ dev-memory-cli session-scan uninstall
 
 - Claude 把 [hooks/hooks.json](hooks.json) 合并到 `.claude/settings.local.json`。
 - Codex CLI 把 [hooks/codex-hooks.json](codex-hooks.json) 合并到 `.codex/hooks.json`。
+- Trae 把 [hooks/trae-hooks.json](trae-hooks.json) 合并到 `.trae/hooks.json`。
+- Trae CN 把同一模板合并到 `.trae-cn/hooks.json`；模板声明 Trae 要求的 `version: 1`。
 - Codex Desktop 通过本地 rollout 定时扫描覆盖，不依赖项目 hook。
 - 其他仓库需要先安装 CLI，再安装对应 hook；hook 运行时统一调用 `dev-memory-cli hook ...`。
 

package/hooks/trae-hooks.json

@@ -0,0 +1,29 @@
+{
+  "version": 1,
+  "hooks": {
+    "SessionStart": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "dev-memory-cli hook session-start",
+            "timeout": 20,
+            "statusMessage": "Loading dev-memory context"
+          }
+        ]
+      }
+    ],
+    "Stop": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "dev-memory-cli hook stop",
+            "timeout": 15,
+            "statusMessage": "Updating dev-memory session marker"
+          }
+        ]
+      }
+    ]
+  }
+}

package/lib/dev_memory_session_scan.py

@@ -29,6 +29,8 @@ PLIST_PATH = Path(os.environ.get(
     "~/Library/LaunchAgents/com.dev-memory.session-scan.plist",
 )).expanduser()
 INTERNAL_MARKER = "DEV_MEMORY_INTERNAL_SESSION_SUMMARY_V1"
+MAINTENANCE_MARKER = "DEV_MEMORY_INTERNAL_MAINTENANCE_AGENT_V1"
+INTERNAL_MARKERS = (INTERNAL_MARKER, MAINTENANCE_MARKER)
 SUMMARY_MUTATION_FIELDS = (
     "file_map",
     "decisions",
@@ -124,7 +126,7 @@ def _deep_merge(base, override):
 def default_scan_config():
     return {
         "executor": "auto",
-        "order": ["coco", "codex", "claude"],
+        "order": ["claude", "codex"],
         "executors": json.loads(json.dumps(DEFAULT_EXECUTORS)),
         "schedule_times": ["03:00", "13:00"],
         "skip_when_computer_active": True,
@@ -360,7 +362,7 @@ def parse_codex_session(path, since_offset=0):
                 if usage:
                     total_usage = usage
             message = _semantic_message(obj)
-            if message and INTERNAL_MARKER in message["text"]:
+            if message and any(marker in message["text"] for marker in INTERNAL_MARKERS):
                 internal_marker = True
             if message and end > since_offset:
                 message.update({"start_offset": start, "end_offset": end})

package/lib/maintenance/archive.md

@@ -0,0 +1,83 @@
+# 分支记忆归档维护流程
+
+目标是把已完成分支中真正跨分支复用的知识提炼到 repo 共享层，然后归档该分支的记忆目录。归档是破坏性显式动作，必须由用户确认。
+
+## 硬规则
+
+- 始终只处理提示中指定的 repo + branch。
+- 所有命令都使用提示中给出的 CLI 路径，并显式传 `--repo`、必要时传 `--branch`。
+- 禁止跳过 dry-run 直接 apply。
+- 当前分支存在未提交改动、领先默认基线且尚未 merge，或仍在开发时，不得擅自归档；先向用户说明并确认。
+- pending-promotion 只是候选，不是必选。业务专用事实不得上提到 repo 共享层。
+- 上提决策必须保留 Why 与影响范围，并改写成脱离当前分支名称仍可理解的最终事实。
+
+## 第一阶段：pre-flight
+
+运行：
+
+```bash
+<CLI> graduate dry-run --repo <REPO> [--branch <BRANCH>]
+```
+
+检查并向用户报告：
+
+- `git_status.ahead`
+- `git_status.uncommitted`
+- 默认基线与当前分支
+- `archive_destination`
+- 主审核面 `primary_sources.pending-promotion.md`
+- 主审核面 `primary_sources.decisions.md`
+- 其他 `cross_check_sources` 中可能遗漏的跨分支经验
+
+若 pre-flight 暴露未 merge 或未提交状态，停止在确认点，不要继续生成 apply。
+
+## 第二阶段：生成 harvest 草案
+
+只提炼真正跨分支稳定成立的内容，生成：
+
+```json
+{
+  "repo_overview": [
+    {"section": "长期目标与边界", "body": "...", "mode": "append"}
+  ],
+  "repo_decisions": [
+    {"section": "跨分支通用决策", "body": "...", "mode": "append"}
+  ],
+  "repo_glossary": [
+    {"section": "长期有效背景", "body": "...", "mode": "append"},
+    {"section": "共享入口", "body": "...", "mode": "append"}
+  ],
+  "notes": "从目标分支提炼",
+  "archive": true
+}
+```
+
+提炼时：
+
+- 去掉当前需求名、临时人员分工、一次性状态和提交流水。
+- 保留通用约束、反直觉风险、长期资料入口和可复用流程。
+- 对照现有 repo 共享记忆去重；旧共享结论失效时应改成最终口径，不能制造两条冲突规则。
+- 默认 `mode=append`，除非已经确认需要更新已有 section。
+
+把 harvest 草案完整展示给用户，包括“会上提什么”和“只归档、不做上提什么”。获得明确确认之前禁止 apply。
+
+## 第三阶段：apply
+
+用户确认草案与归档目标后运行：
+
+```bash
+<CLI> graduate apply --repo <REPO> [--branch <BRANCH>] --harvest-file <HARVEST>
+```
+
+apply 会串行写入 repo 共享层，生成 `archive_summary.md`，并把分支目录移动到 `branches/_archived/<branch>__<date>/`，同时更新 `_archived/INDEX.md`。
+
+## 第四阶段：复核
+
+完成后必须：
+
+1. 读取 `archive_summary.md`。
+2. 运行 `<CLI> graduate index --repo <REPO>` 确认归档索引存在。
+3. 检查原 branch_dir 已移动、archive destination 存在。
+4. 汇总实际上提条目、归档路径和任何跳过项。
+
+如果 apply 报 branch 不存在、schema 漂移或并发归档冲突，停止并报告真实错误；不得强行移动目录或手写 INDEX 绕过 CLI。

package/lib/maintenance/tidy.md

@@ -0,0 +1,102 @@
+# 记忆整理维护流程
+
+目标是把未分类内容归位，并校准已经结构化但陈旧、重复、错误或残留模板的记忆。整理是显式维护任务，不在普通开发会话中自动触发。
+
+## 硬规则
+
+- 始终只处理提示中指定的单个 repo + branch。
+- 所有命令都使用提示中给出的 CLI 路径，并显式传 `--repo`、必要时传 `--branch`。
+- 未分类内容可以在用户确认分类后 merge；结构化内容的删除和改写必须先生成 HTML review，由用户审核并导出 plan，禁止直接 apply。
+- 不复制 PRD、聊天流水或 Git 历史；只保留下次开发仍有价值的决策、风险、术语、约束、入口与文件导航。
+- `progress.md` 的 `AUTO-GENERATED` 块不得删除或改写。
+
+## 第一阶段：处理 unsorted
+
+先运行：
+
+```bash
+<CLI> setup init --repo <REPO> [--branch <BRANCH>]
+```
+
+如果 `unsorted_entries` 非空：
+
+1. 把相关条目聚合后给出高置信度分类建议。
+2. 可选 kind：`decision`、`risk`、`glossary`、`source`、`shared-decision`、`shared-context`、`shared-source`、`skip`。
+3. 让用户确认或修正分类；未确认前不要 merge。
+4. 生成 `classifications` plan，并运行 `setup merge-unsorted --plan-file ...`。
+
+如果 unsorted 为空，不需要为了修改 `setup_completed` 制造额外步骤；继续结构化整理即可。
+
+## 第二阶段：扫描结构化记忆
+
+运行：
+
+```bash
+<CLI> tidy prepare --repo <REPO> [--branch <BRANCH>] --scope <SCOPE>
+```
+
+`SCOPE` 使用启动提示中的 `branch` 或 `branch+repo`。第一次 prepare 后优先读取输出中的 `annotated_md`，不要只看 stdout 的扁平 entries。它保留了：
+
+- entry id
+- block 边界
+- section 结构
+- Why/How 等 orphan paragraph
+- STALE / ORPHAN hints
+
+## 第三阶段：生成事项级 proposals
+
+把相关条目聚合成约 3～8 个 proposal，每个 proposal 必须包含 `id`、`priority`、`title`、`reason`、`actions`。优先使用粗粒度动作：
+
+1. `reset-file`
+2. `delete-section`
+3. `delete-block`
+4. `delete-entries`
+5. `edit-entries`
+
+不要把每个 entry 单独做成 proposal。同一原因、同一结果的动作应合并。删除 block 时尽量附带 prepare 输出的 `expected_content_hash`，防止用户中途修改文件后误删。
+
+priority 口径：
+
+- `P0`：继续保留会误导下一次开发
+- `P1`：强烈建议清理
+- `P2`：建议清理
+- `P3`：可选
+- `P4`：可有可无
+
+把 proposals 写入临时 JSON，再次运行：
+
+```bash
+<CLI> tidy prepare --repo <REPO> [--branch <BRANCH>] --scope <SCOPE> --proposals-file <FILE>
+```
+
+## 第四阶段：人工审核门禁
+
+把 `review_html` / `open_url` 告诉用户，引导用户逐个选择：
+
+- accept：按原方案执行
+- reject：保持不动
+- custom：给出新的处理意见
+
+用户审核后从 HTML 导出 plan.json，并把路径交回本会话。没有用户导出的 plan 文件，禁止调用 `tidy apply`。
+
+## 第五阶段：apply 与复核
+
+用户明确提供已审核 plan 后运行：
+
+```bash
+<CLI> tidy apply --repo <REPO> [--branch <BRANCH>] --plan-file <PLAN>
+```
+
+apply 会先备份，再按 reset → section → block → entry 的顺序执行。完成后必须读取生成的 `summary_*.md`，核对 accepted/rejected/custom、实际 rewritten/deleted 和 invalid actions。
+
+custom proposal 不会自动 apply。根据反馈决定是直接精确改写、解释后再确认、保持不动，还是重新生成 proposals；不要机械重复整轮 prepare。
+
+## 完成输出
+
+最终向用户说明：
+
+- unsorted 分类合并了多少条
+- HTML 审核了多少个 proposal
+- 实际改写、删除、重置的数量
+- 备份和 summary 路径
+- 因漂移校验而跳过的动作

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dev-memory-cli",
-  "version": "0.23.1",
+  "version": "0.25.0",
   "description": "CLI for dev-memory hooks and repo-local setup (formerly @xluos/dev-assets-cli)",
   "license": "MIT",
   "repository": {
@@ -28,6 +28,7 @@
     "hooks/*.json",
     "hooks/README.md",
     "lib/*.py",
+    "lib/maintenance/*.md",
     "lib/ui-server.js",
     "lib/ui-app.html",
     "lib/assets/*",

package/scripts/hooks/_common.py

@@ -490,13 +490,12 @@ def _extract_sections(paths, keys, *, repo_newest_first=False):
 
 def _build_context_from_assets(assets, *, full=True, heading=None, brief_profile="standard"):
     if not assets["branch_dir"].exists():
-        # v2: capture lazy-inits on first write, so branch_dir typically
-        # exists after any real interaction. Missing here just means no
-        # write has happened yet — no need to push setup.
+        # Memory is opt-in. A missing branch directory stays silent in
+        # workspace briefs; the primary repo gets a concise init hint.
         if heading is None:
             return (
                 "当前仓库+分支还没有 dev-memory 记忆。"
-                "下一次 `dev-memory-capture` 写入时会自动 lazy init；现有结论若值得记一笔，直接走 capture。"
+                "需要启用时运行 `dev-memory-cli init`；之后由定期 session-scan 沉淀会话语义。"
             )
         return None
 
@@ -617,7 +616,7 @@ def _build_context_from_assets(assets, *, full=True, heading=None, brief_profile
                 "",
                 f"归档分支查询：`grep -r 'KEYWORD' {archive_dir}/` （体量大时派 Task 子 agent）",
             ])
-        footer_lines.extend(["", "新决策 / 进展 / 阻塞 → `dev-memory-capture` 写入。"])
+        footer_lines.extend(["", "新增会话语义由定期 session-scan 沉淀；主动查旧记忆使用 `dev-memory-read`。"])
         parts.append("\n".join(footer_lines))
 
     return "\n\n".join(parts)

package/suite-manifest.json

@@ -1,13 +1,13 @@
 {
   "suite_name": "dev-memory-skill-suite",
   "skills": [
-    "dev-memory-read",
+    "dev-memory-read"
+  ],
+  "legacy_skills": [
     "dev-memory-setup",
     "dev-memory-capture",
     "dev-memory-graduate",
-    "dev-memory-tidy"
-  ],
-  "legacy_skills": [
+    "dev-memory-tidy",
     "branch-context",
     "branch-context-setup",
     "dev-asset-setup",