dev-memory-cli 0.23.1 → 0.24.0

package/README.md

@@ -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
@@ -85,27 +81,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 +107,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 +142,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 的完整维护指令。
 
 ### 分支记忆操作
 
@@ -251,7 +242,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 +318,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>
@@ -360,11 +354,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 的声明与工作流
+skills/dev-memory-read/        # 唯一常驻 Skill
 tests/                         # Python 测试
 docs/diagrams/                 # README 图表及源文件
 ```

package/bin/dev-memory.js

@@ -376,6 +376,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");
 }
@@ -692,8 +798,11 @@ function printHelp() {
   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 +828,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/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",
@@ -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.24.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",