release: publish Hy Memory 2.0.5.dev4

Co-authored-by: Cursor <cursoragent@cursor.com>

.github/workflows/hermes-provider.yml

@@ -1,49 +0,0 @@
-name: Hermes provider
-
-on:
-  pull_request:
-    paths:
-      - "plugins/hermes/**"
-      - ".github/workflows/hermes-provider.yml"
-  push:
-    branches: [main]
-    paths:
-      - "plugins/hermes/**"
-      - ".github/workflows/hermes-provider.yml"
-
-permissions:
-  contents: read
-
-jobs:
-  provider:
-    runs-on: ubuntu-24.04
-    timeout-minutes: 3
-    steps:
-      - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262
-        with:
-          persist-credentials: false
-      - uses: astral-sh/setup-uv@d0d8abe699bfb85fec6de9f7adb5ae17292296ff
-        with:
-          python-version: "3.12"
-          enable-cache: false
-      - name: Download and verify native Hermes contract
-        run: |
-          uv run --no-project --python 3.12 python - <<'PY'
-          import hashlib
-          import os
-          from pathlib import Path
-          import urllib.request
-
-          url = "https://raw.githubusercontent.com/NousResearch/hermes-agent/818c13be1dc4fd28987e1e881a9408224afd4535/agent/memory_provider.py"
-          with urllib.request.urlopen(url, timeout=30) as response:
-              data = response.read()
-          expected = "a4e44a293013fff831ac136ab77c556541cd18817f53bd662e97090cd80bd5a6"
-          if hashlib.sha256(data).hexdigest() != expected:
-              raise SystemExit("Hermes contract SHA-256 mismatch")
-          snapshot = Path(os.environ["RUNNER_TEMP"]) / "hermes-memory-provider.py"
-          snapshot.write_bytes(data)
-          with open(os.environ["GITHUB_ENV"], "a") as env:
-              env.write(f"HERMES_MEMORY_PROVIDER_SNAPSHOT={snapshot}\n")
-          PY
-      - name: Test provider with native contract
-        run: uv run --no-project --python 3.12 --with pytest python -m pytest plugins/hermes/tests -o addopts= -o log_cli=false -q

.gitignore

@@ -26,9 +26,6 @@ package-lock.json
 ui_walkthrough_*/
 
 # Internal release/open-source coordination must never enter the public tree.
-HANDSOFF.md
-新鲜度_todo.md
-memhub/docs/LOCAL_PRODUCT_APP_MIGRATION_TEST.md
 OPEN_SOURCE_TODO.md
 release_todo.md
 

CHANGELOG.md

@@ -2,219 +2,13 @@
 
 Hy Memory and MemHub are versioned and released independently.
 
-## Unreleased
-
-## MemHub 1.0.5 — 2026-10-28
-
-Build 36, on `hy-memory==2.0.8`. Linux x64/arm64 Runtime and macOS arm64
-App and Runtime. Upgrading from 1.0.4 migrates the existing library to SDK
-authority on first launch.
-
-- MemHub turns off the HY pipeline log and trace at every diagnostic level
-  (hy-memory 2.0.8 `MEMORY_PIPELINE_LOG_ENABLED=false`,
-  `MEMORY_PIPELINE_TRACE_ENABLED=false`), so the per-step JSONL files under
-  `hy-memory/governed-v2/logs/` and the `pipeline_logs` rows stop growing.
-  The Debug panel no longer shows the HY pipeline section. Existing files are
-  left in place.
-- HY SDK text logs are written once, to `hy_memory.log`. They are no longer
-  copied to `service.log` and `service-error.log` through the SDK's
-  stdout/stderr streams. SDK warnings and errors also go to `core.log`, so the
-  Debug panel still shows them. A live switch of the diagnostic level now also
-  changes the level of `hy_memory.log`.
-
-- MemHub shows when working and coding experiences were talked about. After
-  the SDK upgrade every one of them read "时间未知" (time unknown) because the
-  SDK never stored their conversation time; hy-memory 2.0.7 stores it and
-  Core now passes it through the memory list, detail, search and home
-  summary. An experience stored before 2.0.7 shows its write time, labelled
-  "写入于" / "写入时间", instead of "时间未知". Metadata repair also writes
-  the conversation time it recovers from the migration bundle into the SDK's
-  coding/working stores when they already have the column.
-- The SDK migration no longer fails its first run on a home with legacy
-  vectors: reattaching them left a Chroma instance open with its own settings,
-  and the readback that followed could not open the same store
-  ("An instance of Chroma already exists ... with different settings").
-- MemHub "添加记忆" (add a memory) no longer waits behind unprocessed history.
-  Notes are claimed ahead of the event-time window that keeps history strictly
-  old to new; they still run one at a time and in order within their session.
-- The SDK memory page now reads its list, count, source and time labels and
-  graph from one page response for one source filter, so rows, totals and the
-  map no longer disagree. Memories with no recorded source are shown and
-  filterable as "unidentified source"; library search keeps only memories
-  that contain the words within the SDK's relevance window.
-- Metadata repair v2 follows `governed_memory_evidence` across every
-  pre-cutover bundle, which restores the source of memories the cutover
-  backfilled without one, and moves impossible future conversation times back
-  to the write time.
-- Reused the existing three-column memory map for SDK-authority list/detail
-  views and removed the retired "original evidence" surface. SDK-native status,
-  source, conversation time and creation time now render without fabricated
-  revisions; source and text filters are applied by the paged Core endpoint.
-- SDK memory search now calls the SDK search contract instead of listing the
-  entire library in Core. Corrupt empty records are skipped and diagnosed
-  without mutating data or failing a page, and post-cutover metadata repair
-  restores source and original times from the verified migration bundle.
-- Kept Cursor's WAL change token separate from the file mtime so a hash can no
-  longer appear as a conversation date centuries in the future.
-- A trusted packaged Runtime now repairs a dirty same-build installation by
-  staging a clean replacement, and `runtime_service_not_ready` is rendered as
-  user-facing startup guidance instead of an internal code.
-- Fixed legacy-to-SDK startup migration to adopt native Coding Experience and
-  Working Fact IDs instead of importing them as Chat layers. Raw migration now
-  rebuilds bounded user/assistant turns from the latest three days, excludes
-  tools, and enforces the same rolling retention after cutover.
-- Paused host capture writes with a live Desktop migration fence; Cursor
-  History catch-up resumes from its existing checkpoint after cutover.
-- Removed MemHub's private `hy_memory_bridge` implementation. MemHub now calls
-  public `HyMemoryClient` methods at runtime; prompt/reconcile/response
-  monkey-patches and private VDB/Coding runtime access were deleted. Kuzu Graph
-  projection/admin and stopped-writer App migration are the documented product
-  exceptions.
-- Added a MemHub-managed native Hermes MemoryProvider with automatic prefetch,
-  persistent per-session memory-ID deduplication, authorized Broker reads, and
-  recall-context stripping to prevent memory recursion.
-- Added an extensible MemHub interface-localization layer with Simplified
-  Chinese, English, and Spanish catalogs shared by Web and Electron-native
-  surfaces. Interface language remains independent from memory content and
-  model processing language.
-- Fixed governed-memory revisions and repeated evidence links failing when the
-  visibility dirty-marker trigger encounters the same memory twice. Startup
-  now replaces the affected legacy trigger without changing schema versions
-  or governed and visibility data.
-- Kept post-write authority verification failures available for read-only
-  reconciliation while preventing automatic or generic confirmed retries from
-  invoking the model again. Automatic reconciliation skips those sticky rows
-  before applying its batch limit, and linked durable jobs exclusively own
-  retry scheduling for their memory tasks.
-- Removed MemHub's task-scoped HyPermission store wrappers and global
-  model-content consent switch. The trusted embedded Hy Memory SDK now uses
-  its native local stores directly.
-- Existing installations ignore the retired config flag, readmit previously
-  parked pre-invocation work, and drop only the obsolete
-  `hy_node_permissions` proof table. Evidence, governed memories, model
-  profiles, SDK stores, and source/host grants are preserved.
-
-## Hy Memory 2.0.8 — 2026-10-28
-
-- Published
-  [`hy-memory==2.0.8`](https://pypi.org/project/hy-memory/2.0.8/).
-- New `MEMORY_PIPELINE_LOG_ENABLED` (default `true`) turns the pipeline JSONL
-  log (`{MEMORY_LOG_DIR}/<subdir>/<date>.log`) off. With `false` no JSONL
-  file or directory is written. When `MEMORY_PIPELINE_TRACE_ENABLED` is also
-  `false`, `store_pipeline_log` becomes a no-op that returns `True` at once:
-  no timing, redaction, background task or database write. The init log line
-  now states whether the JSONL log is on or off.
-- Conversation and memory text no longer appears in INFO or WARNING logs. The
-  `[add]` input, search queries and rewrites, coding experience tasks, fact
-  statements and subjects, reconcile op details, extracted info, embedding
-  inputs and unparsable model output moved to DEBUG. INFO lines keep ids,
-  counts and character lengths; parse-failure warnings remain but report only
-  the length of the output, e.g. `failed to parse output (812 chars)`. The
-  `[embed]` INFO line now carries `request.input_chars` instead of
-  `request.input`. The `JSON_PARSE_FAILED` error message from extraction no
-  longer embeds the model output either.
-
-## Hy Memory 2.0.7 — 2026-10-28
-
-- Published
-  [`hy-memory==2.0.7`](https://pypi.org/project/hy-memory/2.0.7/).
-- Coding and working experiences and facts now keep their conversation time.
-  `add(..., memory_at=...)` reached only the chat path before; the
-  productivity path dropped it, so every experience had only its write time
-  and MemHub showed them as "时间未知" (time unknown). `coding_memory_meta`
-  and `working_fact` gain a nullable `memory_at` column (epoch seconds) in
-  both the working and coding stores; existing databases get it on open, and
-  their old rows stay `None`. Without `memory_at` a write uses the time the
-  request arrived, as chat does. When an experience is updated by a later
-  conversation it keeps the later of the two times.
-- `list_memories` (`scene="coding"`, `"working"` and `"all"`), `get` and
-  `search` return `memory_at` for experiences and facts in the same field and
-  format as chat (epoch seconds, `None` when unknown). Experience search
-  results now also carry `created_at`.
-
-## Hy Memory 2.0.6 — 2026-10-27
-
-- Published
-  [`hy-memory==2.0.6`](https://pypi.org/project/hy-memory/2.0.6/).
-- `search(..., rerank=False)` skips every reranking stage for that one
-  call (the local cross-encoder, the memory-graph rerank, and the BM25 rerank of
-  working/coding facts), so results come back in retrieval-score order. The
-  flag travels on the read request, so concurrent searches do not affect each
-  other. The default (`True`) keeps current behavior; `/api/v1/search` accepts
-  it too.
-- MMR diversity selection now runs only when the requested `limit` is
-  below 20 (`MMR_MAX_TOP_K`) and is skipped for larger limits, where its
-  quadratic token-overlap pass is slow and gains little. Previously it ran for
-  every limit. `MEMORY_HYBRID_V2_MMR_LAMBDA` still sets the weight.
-  Near-duplicate demotion follows the same gate: it compares each candidate
-  with every earlier non-duplicate, which is quadratic in a pool that grows
-  with `limit`, and large result pages should show similar items anyway.
-- `search(scene="all")` searches chat, working and coding at the same time
-  and merges them with Reciprocal Rank Fusion (k=60) over each scene's own
-  ranking, so no scene is crowded out by the other scenes' score scales. Each
-  result says which scene and kind it came from. A scene that fails or is turned
-  off is reported in `errors` and does not fail the search. Source filters apply
-  to all three.
-- `list_memories(scene="all")` lists chat, working and coding memories
-  together, newest update first, with `limit`/`offset` paging over the merged
-  order and `total` summing all three. `scene="coding"` and `"working"` now
-  honor `include_sources` / `exclude_sources`, and `total` counts only the
-  filtered memories.
-- `update()` and `delete()` now work on working/coding experiences and
-  facts, not just chat memories. They take the same optional `kind` / `variant`
-  as `get()`, and an ID found in more than one place raises
-  `AmbiguousMemoryIdError` instead of guessing. Updating an experience replaces
-  its solution and keeps its task, unless a new `task=` is also passed; updating
-  a fact replaces its statement. Deleting removes the stored row and its vectors.
-- `list_memories(scene="chat" | "coding" | "working")` lists one kind of
-  memory. `coding` and `working` list that scene's whole store, newest update
-  first (`workspace_id` still narrows it), and `total` is now the real count
-  rather than the page size. The new `memory_stats()` returns the count and the
-  latest created/updated time for each scene and their total, without reading
-  any memory text. Previously coding and working memories could not be listed
-  or counted without a workspace, so a library of 45 memories listed 22.
-- Reconcile keeps time order. Both reconcile prompts now state that only
-  `memory_at` decides which memory is newer, that an older memory must never
-  supersede or overwrite a newer one, and that an unknown time is not newer;
-  the Chinese prompt now lists `memory_at` among the new-memory fields. The
-  reconciler also enforces this in code: a SUPERSEDE or UPDATE aimed at a memory
-  with a later `memory_at` becomes an ADD, so the newer memory stays current.
-- The HTTP server returns 409 `ambiguous_memory_id` and 400 for a bad
-  `kind`/`variant` instead of 500, passes `kind`/`variant` (and `task` on PUT)
-  to get/update/delete, and no longer reads a PUT/DELETE query string as part
-  of the memory id.
-- `memory_stats()` reads working/coding times, which are stored as naive UTC,
-  as UTC rather than local time.
-
-## Hy Memory 2.0.5 — 2026-10-22
-
-- Published
-  [`hy-memory==2.0.5`](https://pypi.org/project/hy-memory/2.0.5/).
-- Extended `get()` across Chat, Coding Experience, Working Fact, and raw IDs;
-  the returned `layer`, `kind`, and `variant` identify the actual record.
-- Added explicit raw retrieval through the existing `search()` and
-  `list_memories()` contracts, including user, agent, session, and source
-  filters.
-- Added public embedding-service injection and corrected extraction language
-  detection for structured OpenAI-style messages.
-- Added lifecycle status filters, durable idempotent write outcomes, and
-  quiesced local data-plane snapshot/restore.
-- Kept legacy migration mechanics out of the public Client API; separate
-  migration-only raw/import methods from development previews were removed.
-- Physical delete now reports partial VDB/Graph cleanup as failure.
-- Coding search no longer injects the version-evolution diff block by default;
-  opt in with `MEMORY_CODING_CHAIN_BLOCK_ENABLED=true`.
-- Serialized SDK SQLite cache/history connection lifecycle and tightened
-  Coding reconciliation to its agent/session/workspace authority.
-- Clarified persistent caller context through `meta`, while `metadata` remains
-  legacy processing configuration.
-
 ## Hy Memory 2.0.5.dev4 — 2026-10-21
 
-- Development preview used for SDK-authority migration validation; not the
-  final `2.0.5` release.
-- Published as
-  [`hy-memory==2.0.5.dev4`](https://pypi.org/project/hy-memory/2.0.5.dev4/).
+- Development preview; not the final `2.0.5` release.
+- Adds idempotent `process_raw` / `async_process_raw` APIs that extract and
+  reconcile ordered existing L1 raw IDs without embedding or inserting raw
+  again.
+- Returns durable raw/memory ID receipts for MemHub queue recovery.
 
 ## Hy Memory 2.0.5.dev3 — 2026-10-21
 
@@ -242,12 +36,6 @@ authority on first launch.
   APIs, offline local data-plane snapshot/restore, and fail-closed physical
   delete receipts.
 
-## Hy Memory 2.0.4 — 2026-10-17
-
-- Published
-  [`hy-memory==2.0.4`](https://pypi.org/project/hy-memory/2.0.4/) as a
-  maintenance release.
-
 ## Hy Memory 2.0.3 — 2026-10-17
 
 - Added an optional runtime HTTP transport factory so embedded products can
@@ -258,6 +46,51 @@ authority on first launch.
   unchanged memory extraction, reconciliation, storage, and Coding/Working
   behavior.
 
+## Unreleased
+
+- `search(..., layers=["l1_raw"])` now explicitly searches SDK raw records in
+  pro/ultra mode and keeps existing user/agent/session/source filters; default
+  search continues to hide raw.
+- Added `import_memory_exact` for idempotent migration of an existing semantic
+  memory with its canonical ID, lifecycle and supersession links, without
+  extraction or reconciliation.
+- Added SDK-authoritative lifecycle listing with explicit status filters,
+  idempotent durable write outcomes, exact raw import/get/list APIs, and
+  quiesced local data-plane snapshot/restore contracts for the MemHub
+  authority migration.
+- Physical delete now reports incomplete VDB/Graph cleanup as a partial failure
+  instead of claiming success after only one store was changed.
+- Coding search no longer injects the version-evolution diff block
+  (`chain_block`) by default. Enable with
+  `MEMORY_CODING_CHAIN_BLOCK_ENABLED=true` or
+  `CodingConfig.chain_block_enabled=True` (write-side observe unchanged).
+- Fixed governed-memory revisions and repeated evidence links failing when the
+  visibility dirty-marker trigger encounters the same memory twice. Startup
+  now replaces the affected legacy trigger without changing schema versions
+  or governed and visibility data.
+- Serialized each SDK SQLite store's shared connection lifecycle so concurrent
+  history/cache operations cannot race with `close()` and crash the process.
+- Scoped Coding reconciliation targets to the current HY authority,
+  conversation, and workspace, preventing near-duplicate sessions from
+  mutating an experience or working fact owned by another evidence context.
+- Kept post-write authority verification failures available for read-only
+  reconciliation while preventing automatic or generic confirmed retries from
+  invoking the model again. Automatic reconciliation skips those sticky rows
+  before applying its batch limit, and linked durable jobs exclusively own
+  retry scheduling for their memory tasks.
+- Clarified that `add(metadata=...)` carries legacy SDK processing options,
+  while persistent caller business context belongs in `meta`.
+- Added an opt-in `get(..., include_raw=True)` path for reading `L1_RAW`
+  memories, including memories written in lite mode. The default remains
+  hidden for backward compatibility.
+- Removed MemHub's task-scoped HyPermission store wrappers and global
+  model-content consent switch. The trusted embedded Hy Memory SDK now uses
+  its native local stores directly.
+- Existing installations ignore the retired config flag, readmit previously
+  parked pre-invocation work, and drop only the obsolete
+  `hy_node_permissions` proof table. Evidence, governed memories, model
+  profiles, SDK stores, and source/host grants are preserved.
+
 ## Hy Memory 2.0.2 — 2026-10-17
 
 - Published
@@ -272,17 +105,7 @@ authority on first launch.
   Because PyPI release metadata is immutable, the next SDK patch release must
   carry the updated license metadata; `2.0.1` retains its published metadata.
 
-## MemHub 1.0.5 — Unreleased
-
-- Updated the source version to `1.0.5` (build 14).
-- Pinned the public SDK to the stable `hy-memory==2.0.5` release.
-
-## MemHub 1.0.4 — 2026-10-18
-
-- Updated the source version to `1.0.4` (build 13).
-- Published the `v1.0.4` source and release metadata.
-
-## MemHub 1.0.3 — 2026-10-17
+## MemHub 1.0.3 — Unreleased
 
 - Updated the source version to `1.0.3` (build 7).
 - Pinned the public SDK to `hy-memory==2.0.3`.

README.md

@@ -33,7 +33,6 @@ English | [中文](README.zh.md)
 ## Latest News
 
 * *<mark>[new]</mark>* 🔥🔥🔥 **[2026-10]**: 🚀 **Open-sourced** quantized **FP8** (**[Hy-Memory-30B-A3B-FP8](https://huggingface.co/tencent/Hy-Memory-30B-A3B-FP8)**) and **GGUF** (**[Hy-Memory-30B-A3B-GGUF](https://huggingface.co/tencent/Hy-Memory-30B-A3B-GGUF)**) versions of **Hy-Memory-30B-A3B** on Hugging Face!
-* *<mark>[new]</mark>* 🔥🔥🔥 **[2026-10]**: 📦 **Released [MemHub v1.0.5](https://github.com/Tencent-Hunyuan/Hy-Memory/releases/tag/v1.0.5)** with Chinese, English and Spanish interfaces, one-time pairing codes for more custom Harnesses, and smoother browsing, search, startup and recovery, on **`hy-memory==2.0.8`**. See the release notes for details.
 * *<mark>[new]</mark>* 🔥🔥🔥 **[2026-10]**: 📦 **Released [MemHub v1.0.4](https://github.com/Tencent-Hunyuan/Hy-Memory/releases/tag/v1.0.4)** and **[memhub-cli 1.0.5](https://www.npmjs.com/package/memhub-cli/v/1.0.5)**, with a signed macOS desktop app and verified macOS/Linux Runtimes!
 * *<mark>[new]</mark>* 🔥🔥🔥 **[2026-10]**: 🚀 **Released** **Hy Memory 2.0 (`hy-memory==2.0.4`)** on [PyPI](https://pypi.org/project/hy-memory/2.0.4/) and open-sourced the **Hy-Memory** monorepo together with **[MemHub](memhub/README.md)**!
 * *<mark>[new]</mark>* 🔥🔥🔥 **[2026-10]**: 🚀 **Open-sourced** **[Hy-Memory-30B-A3B](https://huggingface.co/tencent/Hy-Memory-30B-A3B)** on Hugging Face along with its [technical report](https://arxiv.org/abs/2610.22196) on attributed reinforcement learning for long-term memory writing!
@@ -254,7 +253,6 @@ That version is usually not in the working tree or at HEAD either, so it cannot
 - [Graph memory design](docs/pro_graph_design.md) — graph projection, rerank, relation paths, and deployment limits
 - [Environment template](.env.example) — a copy-ready configuration template
 - [MemHub README](memhub/README.md) — local-first desktop & CLI product overview, runtime commands, and privacy boundaries
-- [Hermes native memory provider](plugins/hermes/README.md) — explicit owner/agent scope; separate HTTP service; automatic capture and recall opt-in.
 - [OpenClaw plugin](plugins/openclaw/README.md) — agent integrations live under `plugins/` (overview: [plugins/README.md](plugins/README.md))
 
 ### License

README.zh.md

@@ -33,7 +33,6 @@
 ## 最新动态
 
 * *<mark>[new]</mark>* 🔥🔥🔥 **[2026-10]**: 🚀 **模型开源** 在 Hugging Face 发布 **Hy-Memory-30B-A3B** 的 **FP8**（**[Hy-Memory-30B-A3B-FP8](https://huggingface.co/tencent/Hy-Memory-30B-A3B-FP8)**）与 **GGUF**（**[Hy-Memory-30B-A3B-GGUF](https://huggingface.co/tencent/Hy-Memory-30B-A3B-GGUF)**）量化版本模型！
-* *<mark>[new]</mark>* 🔥🔥🔥 **[2026-10]**: 📦 **正式发布 [MemHub v1.0.5](https://github.com/Tencent-Hunyuan/Hy-Memory/releases/tag/v1.0.5)**：支持中文、英文和西班牙语界面，可通过一次性配对码连接更多自定义 Harness，并优化了记忆浏览、搜索、启动和异常恢复；底层使用 **`hy-memory==2.0.8`**。详见发布说明。
 * *<mark>[new]</mark>* 🔥🔥🔥 **[2026-10]**: 📦 **正式发布 [MemHub v1.0.4](https://github.com/Tencent-Hunyuan/Hy-Memory/releases/tag/v1.0.4)** 与 **[memhub-cli 1.0.5](https://www.npmjs.com/package/memhub-cli/v/1.0.5)**，提供已签名的 macOS 桌面应用及经过验证的 macOS/Linux Runtime！
 * *<mark>[new]</mark>* 🔥🔥🔥 **[2026-10]**: 🚀 **正式发布** **Hy Memory 2.0 (`hy-memory==2.0.4`)**（已上线 [PyPI](https://pypi.org/project/hy-memory/2.0.4/)），并开源 **Hy-Memory** monorepo 与 **[MemHub](memhub/README.md)**！
 * *<mark>[new]</mark>* 🔥🔥🔥 **[2026-10]**: 🚀 **模型开源** 在 Hugging Face 发布 **[Hy-Memory-30B-A3B](https://huggingface.co/tencent/Hy-Memory-30B-A3B)** 长期记忆写入模型及[技术报告](https://arxiv.org/abs/2610.22196)！
@@ -254,7 +253,6 @@ Coding 与 Working **复用同一套双层 pipeline 和数据 schema**，区别
 - [Graph 记忆设计](docs/pro_graph_design.md) — 图投影、重排、关系路径与部署限制
 - [环境变量模板](.env.example) — 可直接复制的配置模板
 - [MemHub 说明文档](memhub/README.md) — 本地优先桌面端与 CLI 产品总览、Runtime 命令与隐私边界
-- [Hermes 原生记忆 Provider](plugins/hermes/README.md) — 显式用户与 Agent 隔离，独立 HTTP 服务，自动记录与召回默认关闭。
 - [OpenClaw 插件](plugins/openclaw/README.md) — Agent 集成见 `plugins/`（总览：[plugins/README.md](plugins/README.md)）
 
 ### License

docs/env_reference.md

@@ -191,7 +191,6 @@ SDK 不设置 Rerank Search 并发上限。开启后模型在 `HyMemoryClient`
 | `MEMORY_LOG_FORMAT` | `text` | `text` / `json` |
 | `MEMORY_LOG_DIR` | — | 统一日志根目录 |
 | `MEMORY_TRACE_LOG_DIR` | — | JSONL 日志目录的兼容旧名；优先使用 `MEMORY_LOG_DIR` |
-| `MEMORY_PIPELINE_LOG_ENABLED` | `true` | 是否写 pipeline JSONL 日志（`{MEMORY_LOG_DIR}/<subdir>/<date>.log`）；`false` 完全不写 |
 | `MEMORY_PIPELINE_TRACE_ENABLED` | `true` | 是否写入 cache 的 pipeline trace 表 |
 | `MEMORY_MEMORY_OPERATIONS_ENABLED` | `false` | 是否写入 memory operation 审计记录 |
 | `MEMORY_HISTORY_ENABLE` | `true` | 是否启用历史记录 |

docs/usage.md

@@ -273,8 +273,8 @@ catalog 也可以在没有基础 L0 时形成只读的合成画像。
 
 ```python
 memory = client.get("memory_id")
-# raw ID 返回 L1_RAW，fact ID 返回对应事实层。
-raw_memory = client.get("raw_id")
+# lite 模式写入的是 L1_RAW；按 ID 读取时必须显式选择返回原文。
+raw_memory = client.get("memory_id", include_raw=True)
 result = client.update("memory_id", "更新后的内容")
 result = client.delete("memory_id")
 result = client.delete_all(user_id="user_001")
@@ -284,7 +284,7 @@ page = client.list_memories(
     limit=100,
     offset=0,
     order="desc",
-    layers=["l1_raw"],  # 显式列出 raw；不传仍沿用默认语义层列表
+    layers=None,
     with_evolution=False,
 )
 
@@ -294,10 +294,9 @@ result = client.clone_user("user_001", "user_002", agent_id=None)
 对应异步方法为 `async_get()`、`async_update()`、`async_delete()`、
 `async_delete_all()`、`async_list_memories()`、`async_clone_user()`。
 
-`get()` / `async_get()` 是统一的 ID 精确读取：返回结果的 `layer`、`kind` 和
-`variant` 表明实际类型。授权由调用 SDK 前的产品边界完成，不由 SDK 根据 layer
-猜测。`list_memories()` 默认仍不包含 `L1_RAW`；显式传
-`layers=["l1_raw"]` 时按同一列表合同返回 raw。
+`get()` / `async_get()` 默认继续隐藏 `L1_RAW`，因此不会改变现有调用方的原文访问
+边界。只有显式传入 `include_raw=True` 才返回该层；这也是 lite 模式按 ID 读取
+写入内容及其 `meta` 的方式。MemHub 的 HTTP 读取接口不开放此参数。
 
 普通 `list_memories()` 返回 `vdb` 桶，并在 Graph 有结果时附带 `graph`；传入
 `workspace_id` 时返回生产力记忆的 `scene="productivity"` 和 `experiences`。

hy_memory/__init__.py

@@ -65,12 +65,6 @@ from .snapshot import (
 
 # ====== 配置 ======
 from .config import MemoryConfig
-from .embedding import (
-    EmbeddingDimensionMismatchError,
-    EmbeddingService,
-    EmbeddingServiceProtocol,
-)
-from .retrieval import AmbiguousMemoryIdError, MemoryKind, MemoryVariant
 
 # ====== Embedding 端点覆盖（per-call，不改 model/dims，只换接入端点）======
 from .core.embed_service import embed_endpoint_override
@@ -131,13 +125,6 @@ __all__ = [
     "snapshot_local_data_plane",
     # 配置
     "MemoryConfig",
-    # 公共扩展协议 / 精确读取类型
-    "EmbeddingService",
-    "EmbeddingServiceProtocol",
-    "EmbeddingDimensionMismatchError",
-    "MemoryKind",
-    "MemoryVariant",
-    "AmbiguousMemoryIdError",
     # Embedding 端点覆盖
     "embed_endpoint_override",
     # 高级 API

hy_memory/agent/extractor.py

@@ -1177,7 +1177,7 @@ class Extractor:
                         if not tc_id:
                             logger.error(
                                 f"[extractor] tool_call_id is empty! "
-                                f"raw_keys={list(tc_raw.keys())}"
+                                f"raw tc: {json.dumps(tc_raw, ensure_ascii=False, default=str)[:500]}"
                             )
                         try:
                             t_res = await tool_registry.dispatch(
@@ -1311,12 +1311,11 @@ class Extractor:
                 if parsed is None:
                     if not all_tool_calls:
                         logger.warning(
-                            f"[extractor] JSON parse failed ({len(raw_text)} chars)"
+                            f"[extractor] JSON parse failed: {raw_text[:200]}"
                         )
-                        logger.debug(f"[extractor] unparsable output: {raw_text[:200]!r}")
                         return ExtractResult(
                             success=False,
-                            error=f"JSON parse failed ({len(raw_text)} chars)",
+                            error=f"JSON parse failed: {raw_text[:200]}",
                             error_code="JSON_PARSE_FAILED",
                             raw_response=raw_text,
                             tokens_used=total_tokens,

hy_memory/agent/llm_provider.py

@@ -129,7 +129,8 @@ def _parse_tool_calls_list(raw_calls: list, _json) -> List[Dict[str, Any]]:
         tc_id = tc.get("id") or ""
         if not tc_id:
             logger.error(
-                f"[llm] tool_call missing 'id'! keys={list(tc.keys())}"
+                f"[llm] tool_call missing 'id'! raw: "
+                f"{_json.dumps(tc, ensure_ascii=False, default=str)[:500]}"
             )
 
         # 保留原始 tc 完整结构，只规范化 arguments

hy_memory/agent/mem_agent.py

@@ -234,7 +234,7 @@ class MemAgent:
                     f"identity={len(identity)} facts={len(facts)} "
                     f"basic_info={basic_field_count}fields"
                 )
-                logger.debug(f"MemAgent: extracted_info={extract_result.info}")
+                logger.info(f"MemAgent: extracted_info={extract_result.info}")
 
             # 3. 冲突检测（如果有已有记忆）
             if mode == ProcessMode.FULL and existing_memories:

hy_memory/agent/prompts_zh.py

@@ -743,7 +743,6 @@ RECONCILE_PROMPT_ZH = """你是一个记忆整合系统（Memory Reconciler）
 
 * content
 * owner
-* memory_at（发生时间）
 * tags
 
 new memories 没有 ID。
@@ -792,7 +791,6 @@ new memories 没有 ID。
 * 无损合并
 * 保留所有有效信息
 * 不要产生重复 memory
-* 两者在某个值上不一致时，保留 memory_at 更晚的那个值；绝不用更早的 memory 覆盖更新的值
 
 ### 同一次事件的补充 vs 另一次发生
 
@@ -825,7 +823,6 @@ new memories 没有 ID。
 * 新 memory 与旧 memory 在同一维度冲突
 * 两者不能同时为真
 * 旧 memory 已不再代表当前状态
-* 新 memory 的 memory_at 不早于旧 memory 的 memory_at
 
 例如：
 
@@ -840,7 +837,6 @@ new memories 没有 ID。
 * wording 差异
 * 同义表达
 * 可共存偏好
-* 新 memory 的 memory_at 早于旧 memory：它是更早的状态，绝不能取代更新的状态（见「时间规则」）
 
 要求：
 
@@ -863,7 +859,7 @@ new memories 没有 ID。
 
 ### 把多条旧记忆折叠进同一条链
 
-如果**两条或更多**已有记忆描述的是**同一维度**，而新记忆是该维度上的最新变化（它的 memory_at 晚于所有被折叠的记忆），
+如果**两条或更多**已有记忆描述的是**同一维度**，而新记忆是该维度上的最新变化，
 你可以把它们折叠进同一条演化链。此时用 `memory_ids`（有序列表，**旧→新**）
 代替单个 `memory_id`：
 
@@ -955,16 +951,13 @@ SUPERSEDE 不需要复制旧内容，因为旧节点仍存在。
 
 ## 时间规则
 
-每条 memory（新的和已有的）都带 memory_at，表示它发生的时间。记忆**不一定按发生顺序写入**：
-历史可能晚导入，导入还没处理完时用户也可能手动添加记忆。所以一条 new memory 可能**比已有记忆更早**。
+`memory_at: null`
 
-* 新旧**只看 memory_at**。"New memories" 只表示"正在写入"，不表示"更近"。
-* 更早的 memory 绝不能取代更新的 memory：不能 SUPERSEDE 一条更新的记忆，也不能用 UPDATE 拿更早的值覆盖更新的值。
-* 如果 new memory 比与它冲突的已有记忆更早：保留已有记忆作为当前状态；把 new memory 以"过去状态"ADD
-  （用过去时，并带上时间，例如"2023 年用户住在上海"），没有新信息就不输出。
-* `memory_at: null` 表示时间未知。未知**不算更新**：不要用 memory_at 为 null 的 memory 去 SUPERSEDE 一条有时间的记忆。
-* 不要编造时间顺序。
-* 不要仅因为“看起来更新”就 supersede。
+表示时间未知。
+
+不要编造时间顺序。
+
+不要仅因为“看起来更新”就 supersede。
 
 ---
 

hy_memory/agent/reconciler.py

@@ -50,7 +50,7 @@ def is_canonical_state_node(node: Any) -> bool:
 
 
 def _log_ops_detail(ops: List["ReconcileOp"]) -> None:
-    """以单条 DEBUG（JSON list）输出 reconcile 的逐条结果；含记忆正文，不进 INFO。"""
+    """以单条 INFO（JSON list）输出 reconcile 的逐条结果，便于线上 debug。"""
     if not ops:
         return
     view = [
@@ -68,7 +68,7 @@ def _log_ops_detail(ops: List["ReconcileOp"]) -> None:
         }
         for o in ops
     ]
-    logger.debug(
+    logger.info(
         f"[reconciler] ops detail: {json.dumps(view, ensure_ascii=False, default=str)}"
     )
 
@@ -221,8 +221,6 @@ Rules:
 * merge losslessly
 * preserve all useful information
 * do NOT create duplicates
-* if the two disagree on a value, keep the value from the memory with the later
-  `memory_at`; never let an older memory overwrite a newer value
 
 ### Same occurrence vs. another occurrence
 
@@ -257,7 +255,6 @@ Use ONLY when:
 * the new memory contradicts an existing memory
 * both cannot be true at the same time
 * the old memory would now give the wrong current-state answer
-* the new memory's `memory_at` is the same as or LATER than the existing memory's `memory_at`
 
 Examples:
 
@@ -271,8 +268,6 @@ Do NOT use for:
 * compatible preferences
 * wording differences
 * semantic equivalence
-* a new memory whose `memory_at` is EARLIER than the existing memory's — it is an
-  older state and must never replace a newer one (see "Time order")
 
 Rules:
 
@@ -294,8 +289,7 @@ Rules:
 ### Folding several existing memories into one chain
 
 If TWO OR MORE existing memories track the SAME dimension and the new memory is
-the latest change on that dimension — its `memory_at` is later than every folded
-memory's `memory_at` — you may fold them into a single evolution
+the latest change on that dimension, you may fold them into a single evolution
 chain. Use `memory_ids` (an ordered list, OLDEST → NEWEST) instead of a single
 `memory_id`:
 
@@ -324,7 +318,8 @@ older memories' text into it; they remain queryable in the chain history.
 * Separate dated occurrences stay separate ADDs; use `same_series` only for the
   same subject and same concrete activity/event type.
 * Keep each memory focused on one coherent topic.
-* Follow "Time order" below.
+* Do not invent chronology.
+* `memory_at: null` means unknown time.
 * **NEVER merge or supersede across different subjects.** The subject is whoever
   the content is about: "The user ..." vs "John ..." vs "Mary ...". Memories about
   different people are independent facts even when the sentence is otherwise
@@ -337,27 +332,6 @@ older memories' text into it; they remain queryable in the chain history.
 
 ---
 
-# Time order
-
-Every memory, new or existing, has `memory_at`: when it happened. Memories are
-NOT always written in the order they happened — history can be imported late,
-and a memory can be added while older history is still being processed. A new
-memory can therefore be OLDER than an existing one.
-
-* Decide which memory is newer ONLY by `memory_at`. "New memories" means "being
-  written now", not "more recent".
-* An older memory must never replace a newer one: no SUPERSEDE of a newer
-  memory, and no UPDATE that overwrites a newer value with an older one.
-* If a new memory is older than an existing memory it conflicts with, keep the
-  existing memory as the current state. ADD the new one as a past state, worded
-  in the past with its time (for example "In 2023 the user lived in Shanghai"),
-  or output nothing if it adds no information.
-* `memory_at: null` means unknown time. Unknown is NOT newer: never SUPERSEDE a
-  memory that has a known `memory_at` with one whose `memory_at` is null.
-* Do not invent chronology.
-
----
-
 # Optional: `related`
 
 On any op you MAY add a `related` array recording how the memory being written
@@ -467,81 +441,6 @@ def append_reconcile_structure_prompt(
     return prompt + RECONCILE_STRUCTURE_METADATA_PROMPT_EN
 
 
-def _as_aware(value: Any) -> Optional[datetime]:
-    """memory_at as a comparable aware datetime; None when unknown or unreadable."""
-    if isinstance(value, str) and value:
-        try:
-            value = datetime.fromisoformat(value)
-        except (TypeError, ValueError):
-            return None
-    if not isinstance(value, datetime):
-        return None
-    # Stored nodes rebuild memory_at from epoch seconds as naive local time
-    # (MemoryNode.from_dict), so a naive value is local, not UTC.
-    return value if value.tzinfo is not None else value.astimezone()
-
-
-def enforce_time_order(
-    ops: List["ReconcileOp"],
-    new_memory_at: Any,
-    existing: Dict[str, Any],
-) -> List["ReconcileOp"]:
-    """An older memory must never replace a newer one, whatever the model says.
-
-    Memories are not always written in the order they happened: history is
-    imported late, and a person can add a memory while older history is still
-    being processed. The prompt tells the model to compare `memory_at`; this
-    makes it hold. A SUPERSEDE or UPDATE aimed at an existing memory whose
-    `memory_at` is later than the memory being written is turned into an ADD,
-    so the newer memory stays the current state. Unknown times are not
-    compared. A content-less UPDATE (the legacy DELETE mapping) is dropped.
-    """
-    written_at = _as_aware(new_memory_at)
-    if written_at is None:
-        return ops
-    kept: List[ReconcileOp] = []
-    for op in ops:
-        if op.op not in ("SUPERSEDE", "UPDATE"):
-            kept.append(op)
-            continue
-        targets = list(op.memory_ids) if op.memory_ids else [op.memory_id]
-        newer = [
-            target for target in targets
-            if target and (node := existing.get(target)) is not None
-            and (target_at := _as_aware(getattr(node, "memory_at", None))) is not None
-            and target_at > written_at
-        ]
-        if not newer:
-            kept.append(op)
-            continue
-        logger.warning(
-            "[reconciler] %s blocked: memory_at %s is older than existing %s; "
-            "kept the newer memory",
-            op.op, written_at.isoformat(), ",".join(newer),
-        )
-        if not op.content:
-            continue
-        kept.append(ReconcileOp(
-            op="ADD",
-            content=op.content,
-            layer=op.layer,
-            owner=op.owner,
-            tags=list(op.tags),
-            tag_ners=list(op.tag_ners),
-            topic_paths=list(op.topic_paths),
-            event_facet=dict(op.event_facet),
-            topic_assignments=list(op.topic_assignments),
-            structure_references=list(op.structure_references),
-            topic_paths_provided=op.topic_paths_provided,
-            event_facet_provided=op.event_facet_provided,
-            topic_assignments_provided=op.topic_assignments_provided,
-            speculate=op.speculate,
-            related=list(op.related),
-            reason=f"time_order: older than {','.join(newer)}; {op.reason}"[:500],
-        ))
-    return kept
-
-
 def build_reconcile_prompt(
     *,
     new_memories: List[str],
@@ -1500,7 +1399,6 @@ class MemoryReconciler:
                 _tok_total += response.tokens_used
                 raw_response = response.content
                 ops = self._parse_ops(raw_response)
-                ops = enforce_time_order(ops, current_time, candidate_map)
                 ops = self._inherit_exact_input_structure(
                     ops, new_memories_with_meta,
                 )
@@ -1514,10 +1412,9 @@ class MemoryReconciler:
                 logger.warning(
                     f"[reconciler] RECONCILE JSON parse failed "
                     f"(attempt {_attempt+1}/{_MAX_PARSE_ATTEMPTS}), "
-                    f"retrying: raw({len(raw_response or '')} chars)"
+                    f"retrying: raw="
+                    f"{raw_response[:200] if _log_llm_content_enabled() else '<redacted>'}"
                 )
-                if _log_llm_content_enabled():
-                    logger.debug(f"[reconciler] unparsable raw={raw_response[:200]!r}")
 
             recon_elapsed = (_time.perf_counter() - t_recon) * 1000
 
@@ -1529,8 +1426,8 @@ class MemoryReconciler:
                     error_code = "LLM_UNAVAILABLE"
                 elif raw_response.strip():
                     error_msg = (
-                        f"RECONCILE JSON parse failed after {_n_attempts} attempts "
-                        f"({len(raw_response)} chars)"
+                        f"RECONCILE JSON parse failed after {_n_attempts} attempts: "
+                        f"{raw_response[:200] if _log_llm_content_enabled() else '<redacted>'}"
                     )
                     error_code = "JSON_PARSE_FAILED"
                 else:
@@ -1807,8 +1704,7 @@ class MemoryReconciler:
                 except Exception as _re:
                     logger.debug(f"[reconciler] json_repair failed: {_re}")
             if data is None:
-                logger.warning(f"[reconciler] failed to parse ops JSON ({len(text)} chars)")
-                logger.debug(f"[reconciler] unparsable ops output: {text[:200]!r}")
+                logger.warning(f"[reconciler] failed to parse ops JSON: {text[:200]}")
                 return []
 
         if not isinstance(data, list):
@@ -2020,11 +1916,11 @@ class MemoryReconciler:
                 if clash is not None:
                     logger.warning(
                         f"[reconciler] memory_id {clash} already touched by '{touched[clash]}', "
-                        f"current op '{op.op}' dropped"
+                        f"current op '{op.op} ({op.reason[:60]})' dropped"
                     )
                     continue
                 for t in target_ids:
-                    touched[t] = op.op
+                    touched[t] = f"{op.op}({op.reason[:40]})"
             validated.append(op)
 
         return validated

hy_memory/agent/tools/base.py

@@ -211,9 +211,7 @@ def parse_tool_calls_from_json(raw: Any) -> List[ToolCall]:
                 try:
                     args = json.loads(args_raw) if args_raw.strip() else {}
                 except json.JSONDecodeError:
-                    logger.warning(
-                        f"[tools] failed to parse arguments as JSON ({len(args_raw)} chars)"
-                    )
+                    logger.warning(f"[tools] failed to parse arguments as JSON: {args_raw[:120]}")
                     args = {}
             elif isinstance(args_raw, dict):
                 args = args_raw

hy_memory/coding/extractor.py

@@ -1166,10 +1166,7 @@ class CodingMemoryExtractor:
                     obj = None
 
         if not isinstance(obj, dict):
-            logger.warning(
-                f"[coding-extract] failed to parse output ({len(text or '')} chars)"
-            )
-            logger.debug(f"[coding-extract] unparsable output: {text!r}")
+            logger.warning(f"[coding-extract] failed to parse output: {text!r}")
             return [], []
 
         # "memories" 是双层化之前的 key，老 prompt 缓存 / 旧模型可能还这么回

hy_memory/coding/fact_reconciler.py

@@ -454,10 +454,9 @@ class WorkingFactReconciler:
         workspace_id: Optional[str] = None,
         branch: Optional[str] = None,
         source: str = "default",
-        memory_at: Optional[datetime] = None,
     ) -> Tuple[List[WorkingFact], List[FactReconcileOp]]:
         """
-        执行 reconcile + 持久化。memory_at 是这段对话的时间，记到新事实上。
+        执行 reconcile + 持久化。
 
         Returns:
             (真正落库的新事实, 执行过的 ops)。LLM 挂掉时退化为全 INSERT 不覆盖，
@@ -494,7 +493,6 @@ class WorkingFactReconciler:
             workspace_id=workspace_id,
             branch=branch,
             source=source,
-            memory_at=memory_at,
         )
         logger.info(
             f"[fact-reconcile] drafts={len(drafts)} inserted={len(facts)} "
@@ -570,12 +568,9 @@ class WorkingFactReconciler:
                     kept.append(fact)
             if blocked:
                 logger.info(
-                    f"[fact-reconcile] subject gate blocked {len(blocked)} candidate(s): "
-                    + ", ".join(f.fact_id for f in blocked)
-                )
-                logger.debug(
-                    f"[fact-reconcile] subject gate: draft subject={draft.subject!r} "
-                    f"blocked subjects={[f.subject for f in blocked]!r}"
+                    f"[fact-reconcile] subject gate blocked {len(blocked)} candidate(s) "
+                    f"for subject={draft.subject!r}: "
+                    + ", ".join(f"{f.fact_id}({f.subject!r})" for f in blocked)
                 )
             result.append(kept)
         return result
@@ -748,10 +743,7 @@ class WorkingFactReconciler:
                     obj = None
 
         if not isinstance(obj, dict):
-            logger.warning(
-                f"[fact-reconcile] failed to parse ops output ({len(text or '')} chars)"
-            )
-            logger.debug(f"[fact-reconcile] unparsable ops output: {text!r}")
+            logger.warning(f"[fact-reconcile] failed to parse ops output: {text!r}")
             return {}
         ops_raw = obj.get("ops")
         if not isinstance(ops_raw, list):
@@ -789,7 +781,6 @@ class WorkingFactReconciler:
         workspace_id: Optional[str],
         branch: Optional[str] = None,
         source: str = "default",
-        memory_at: Optional[datetime] = None,
     ) -> Tuple[List[WorkingFact], List[FactReconcileOp]]:
         inserted: List[WorkingFact] = []
         ops: List[FactReconcileOp] = []
@@ -810,7 +801,6 @@ class WorkingFactReconciler:
                 subject=draft.subject,
                 details=draft.details,
                 status="active",
-                memory_at=memory_at,
             )
 
             allowed = {c.fact_id for c in (candidates[idx] if idx < len(candidates) else [])}
@@ -841,11 +831,8 @@ class WorkingFactReconciler:
                 # 别的主体的状态不是。闸门关掉时这道复查一并跳过，否则闸门就没关干净。
                 if self.subject_gate and _subject_conflict(draft.subject, old.subject):
                     logger.warning(
-                        f"[fact-reconcile] refused cross-subject SUPERSEDE: {old.fact_id}"
-                    )
-                    logger.debug(
-                        f"[fact-reconcile] cross-subject: old subject={old.subject!r} "
-                        f"draft subject={draft.subject!r}"
+                        f"[fact-reconcile] refused cross-subject SUPERSEDE: "
+                        f"{old.fact_id}({old.subject!r}) by draft subject {draft.subject!r}"
                     )
                     continue
                 try:

hy_memory/coding/judge.py

@@ -195,10 +195,8 @@ async def classify_messages_scene(
         result = _parse_scene_json(resp.content)
         if result is None:
             logger.warning(
-                f"[coding-judge] failed to parse classify_messages output "
-                f"({len(resp.content or '')} chars); defaulting to chat"
+                f"[coding-judge] failed to parse classify_messages output: {resp.content!r}; defaulting to chat"
             )
-            logger.debug(f"[coding-judge] unparsable classify_messages output: {resp.content!r}")
             await _store_coding_log(
                 cache, request_id=request_id, user_id=user_id, agent_id=agent_id,
                 session_id=session_id, step="CODING_JUDGE", prompt=prompt,
@@ -209,8 +207,9 @@ async def classify_messages_scene(
             return "chat"
         scene = result["scene"]
         parsed = {**result, "is_coding": scene != "chat"}
-        logger.info(f"[coding-judge] scene={scene}")
-        logger.debug(f"[coding-judge] scene={scene} reason={result.get('reason', '')!r}")
+        logger.info(
+            f"[coding-judge] scene={scene} reason={result.get('reason', '')!r}"
+        )
         await _store_coding_log(
             cache, request_id=request_id, user_id=user_id, agent_id=agent_id,
             session_id=session_id, step="CODING_JUDGE", prompt=prompt,
@@ -296,10 +295,8 @@ async def classify_queries_scene(
         result = _parse_scene_json(resp.content)
         if result is None:
             logger.warning(
-                f"[coding-judge] failed to parse classify_queries output "
-                f"({len(resp.content or '')} chars); defaulting to chat"
+                f"[coding-judge] failed to parse classify_queries output: {resp.content!r}; defaulting to chat"
             )
-            logger.debug(f"[coding-judge] unparsable classify_queries output: {resp.content!r}")
             return "chat"
         scene = result["scene"]
         logger.info(f"[coding-judge] queries scene={scene}")
@@ -425,18 +422,15 @@ async def classify_and_rewrite_queries(
     scene = _parse_scene_label(head)
     if scene is None:
         logger.warning(
-            f"[coding-judge] classify_and_rewrite unrecognized head "
-            f"({len(head)} chars); falling back to chat"
+            f"[coding-judge] classify_and_rewrite unrecognized head={head!r}; falling back to chat"
         )
-        logger.debug(f"[coding-judge] classify_and_rewrite unrecognized head={head!r}")
         return {"scene": "chat", "is_coding": False, "rewrite_query": rewrite, "ok": False}
     is_coding = scene != "chat"
 
     logger.info(
         f"[coding-judge] classify_and_rewrite scene={scene} "
-        f"rewrite({len(rewrite)} chars)"
+        f"rewrite={rewrite!r}"
     )
-    logger.debug(f"[coding-judge] classify_and_rewrite rewrite={rewrite!r}")
     return {"scene": scene, "is_coding": is_coding, "rewrite_query": rewrite, "ok": True}
 
 
@@ -575,9 +569,8 @@ async def analyze_queries(
         parsed_scene = _parse_scene_label(head)
         if parsed_scene is None:
             logger.warning(
-                f"[coding-judge] analyze_queries unrecognized head ({len(head)} chars); ok=False"
+                f"[coding-judge] analyze_queries unrecognized head={head!r}; ok=False"
             )
-            logger.debug(f"[coding-judge] analyze_queries unrecognized head={head!r}")
             return {**fallback, "since_raw": ""}
         scene = parsed_scene
         idx = 1
@@ -596,10 +589,9 @@ async def analyze_queries(
     created_after = _since_to_created_after(since_raw, current_time)
 
     logger.info(
-        f"[coding-judge] analyze scene={scene} rewrite({len(rewrite)} chars) "
+        f"[coding-judge] analyze scene={scene} rewrite={rewrite!r} "
         f"since={since_raw!r} created_after={created_after}"
     )
-    logger.debug(f"[coding-judge] analyze rewrite={rewrite!r}")
     return {
         "scene": scene, "is_coding": scene != "chat", "rewrite_query": rewrite,
         "created_after": created_after, "since_raw": since_raw, "ok": True,
@@ -622,10 +614,7 @@ def _since_to_created_after(since_raw: str, current_time: str) -> Optional[float
             return dt.timestamp()
         except (ValueError, TypeError):
             continue
-    logger.warning(
-        f"[coding-judge] analyze_queries unparsable SINCE ({len(since_raw)} chars)"
-    )
-    logger.debug(f"[coding-judge] analyze_queries unparsable SINCE={since_raw!r}")
+    logger.warning(f"[coding-judge] analyze_queries unparsable SINCE={since_raw!r}")
     return None
 
 

hy_memory/coding/reconciler.py

@@ -388,10 +388,7 @@ class CodingMemoryReconciler:
                     obj = None
 
         if not obj or not isinstance(obj, dict):
-            logger.warning(
-                f"[coding-reconcile] failed to parse ops output ({len(text or '')} chars)"
-            )
-            logger.debug(f"[coding-reconcile] unparsable ops output: {text!r}")
+            logger.warning(f"[coding-reconcile] failed to parse ops output: {text!r}")
             return []
         ops_raw = obj.get("ops") or []
         if not isinstance(ops_raw, list):
@@ -444,10 +441,10 @@ class CodingMemoryReconciler:
         for op in ops:
             if op.action == "ADD":
                 if op.draft_idx is None or not (0 <= op.draft_idx < len(drafts)):
-                    logger.warning(f"[coding-reconcile] drop invalid ADD: {_op_ref(op)}")
+                    logger.warning(f"[coding-reconcile] drop invalid ADD: {op.to_dict()}")
                     continue
                 if op.draft_idx in consumed:
-                    logger.warning(f"[coding-reconcile] drop ADD on consumed draft: {_op_ref(op)}")
+                    logger.warning(f"[coding-reconcile] drop ADD on consumed draft: {op.to_dict()}")
                     continue
                 d = drafts[op.draft_idx]
                 memory = self._draft_to_new_memory(d)
@@ -461,18 +458,18 @@ class CodingMemoryReconciler:
 
             elif op.action == "UPDATE":
                 if op.draft_idx is None or not (0 <= op.draft_idx < len(drafts)):
-                    logger.warning(f"[coding-reconcile] drop invalid UPDATE: {_op_ref(op)}")
+                    logger.warning(f"[coding-reconcile] drop invalid UPDATE: {op.to_dict()}")
                     continue
                 if not op.target_experience_id:
-                    logger.warning(f"[coding-reconcile] drop UPDATE missing target: {_op_ref(op)}")
+                    logger.warning(f"[coding-reconcile] drop UPDATE missing target: {op.to_dict()}")
                     continue
                 if not self._target_was_offered(op, candidates_per_draft):
                     logger.warning(
-                        f"[coding-reconcile] drop UPDATE outside authority scope: {_op_ref(op)}"
+                        f"[coding-reconcile] drop UPDATE outside authority scope: {op.to_dict()}"
                     )
                     continue
                 if op.draft_idx in consumed:
-                    logger.warning(f"[coding-reconcile] drop UPDATE on consumed draft: {_op_ref(op)}")
+                    logger.warning(f"[coding-reconcile] drop UPDATE on consumed draft: {op.to_dict()}")
                     continue
                 d = drafts[op.draft_idx]
                 memory = self._draft_to_new_memory(d, experience_id=op.target_experience_id)
@@ -491,17 +488,17 @@ class CodingMemoryReconciler:
 
             elif op.action == "DELETE":
                 if not op.target_experience_id:
-                    logger.warning(f"[coding-reconcile] drop DELETE missing target: {_op_ref(op)}")
+                    logger.warning(f"[coding-reconcile] drop DELETE missing target: {op.to_dict()}")
                     continue
                 if not self._target_was_offered(op, candidates_per_draft):
                     logger.warning(
-                        f"[coding-reconcile] drop DELETE outside authority scope: {_op_ref(op)}"
+                        f"[coding-reconcile] drop DELETE outside authority scope: {op.to_dict()}"
                     )
                     continue
                 # DELETE 需要知道 user_id；通过 draft_idx（如有）或第一个 draft 推断
                 user_id = self._infer_user_id(op, drafts)
                 if not user_id:
-                    logger.warning(f"[coding-reconcile] drop DELETE no user_id context: {_op_ref(op)}")
+                    logger.warning(f"[coding-reconcile] drop DELETE no user_id context: {op.to_dict()}")
                     continue
                 try:
                     ok = await self.store.delete(op.target_experience_id, user_id=user_id)
@@ -580,7 +577,6 @@ class CodingMemoryReconciler:
             confidence=d.confidence,
             source=d.source,
             extraction_source=d.extraction_source,
-            memory_at=d.memory_at,
         )
 
 
@@ -588,14 +584,6 @@ class CodingMemoryReconciler:
 # Helpers
 # ================================================================
 
-def _op_ref(op: ReconcileOp) -> str:
-    """op 的日志引用：只带动作与编号，不带 LLM 写的 reason。"""
-    return (
-        f"action={op.action} draft_idx={op.draft_idx} "
-        f"target={op.target_experience_id}"
-    )
-
-
 def _truncate(s: str, n: int) -> str:
     if not s:
         return ""

hy_memory/coding/store.py

@@ -86,7 +86,6 @@ CREATE TABLE IF NOT EXISTS coding_memory_meta (
     confidence       REAL NOT NULL DEFAULT 0.7,
     source           TEXT NOT NULL DEFAULT 'default',
     extraction_source TEXT NOT NULL DEFAULT 'auto_extract',
-    memory_at        INTEGER,
     created_at       TEXT NOT NULL,
     updated_at       TEXT NOT NULL
 );
@@ -110,7 +109,6 @@ CREATE TABLE IF NOT EXISTS working_fact (
     derived_experience_ids TEXT NOT NULL DEFAULT '[]',
     status                 TEXT NOT NULL DEFAULT 'active',
     fact_chain_summary     TEXT NOT NULL DEFAULT '',
-    memory_at              INTEGER,
     created_at             TEXT NOT NULL
 );
 -- 反查前驱（谁的 fact_link 指向我）走这个索引，写演变总结时要顺着链往回走
@@ -166,8 +164,6 @@ _ADDED_COLUMNS = {
     "coding_memory_meta": {
         "source_fact_ids": "TEXT NOT NULL DEFAULT '[]'",
         "extraction_source": "TEXT NOT NULL DEFAULT 'auto_extract'",
-        # 对话时间，秒级 epoch（同 chat）。老库里的行是 NULL：那时没存过。
-        "memory_at": "INTEGER",
     },
     # 早期版本存过一列 fact_chain（机械累积的历代说法），已废弃：同样的信息顺着
     # fact_link 反查就有。老库里那一列留着不管，有默认值不影响插入。
@@ -181,7 +177,6 @@ _ADDED_COLUMNS = {
         "subject": "TEXT NOT NULL DEFAULT ''",
         "details": "TEXT NOT NULL DEFAULT ''",
         "source": "TEXT NOT NULL DEFAULT 'default'",
-        "memory_at": "INTEGER",
     },
 }
 
@@ -222,21 +217,6 @@ def _in_clause(column: str, values: Optional[List[str]]) -> Tuple[str, List[Any]
     return f"{column} IN ({placeholders})", list(values)
 
 
-def _source_where(
-    include_sources: Optional[List[str]], exclude_sources: Optional[List[str]],
-) -> Tuple[str, List[Any]]:
-    """Caller-source filter as SQL (``1`` when unfiltered); exclusion wins."""
-    clauses: List[str] = []
-    params: List[Any] = []
-    if include_sources:
-        clauses.append(f"source IN ({','.join('?' for _ in include_sources)})")
-        params.extend(include_sources)
-    if exclude_sources:
-        clauses.append(f"source NOT IN ({','.join('?' for _ in exclude_sources)})")
-        params.extend(exclude_sources)
-    return (" AND ".join(clauses) or "1"), params
-
-
 def _scope_matches(
     row_workspace_id: Optional[str],
     row_branch: Optional[str],
@@ -295,29 +275,6 @@ def _parse_dt(s: Optional[str]) -> Optional[datetime]:
         return None
 
 
-def _from_epoch(value: Any) -> Optional[datetime]:
-    """memory_at 列（秒级 epoch）→ datetime；NULL 或坏值返回 None。"""
-    if value is None:
-        return None
-    try:
-        return datetime.fromtimestamp(int(value))
-    except Exception:
-        return None
-
-
-def _to_epoch(value: Optional[datetime]) -> Optional[int]:
-    return int(value.timestamp()) if isinstance(value, datetime) else None
-
-
-def _later(a: Optional[datetime], b: Optional[datetime]) -> Optional[datetime]:
-    """两个对话时间取较晚的；一边缺就取另一边。"""
-    if a is None:
-        return b
-    if b is None:
-        return a
-    return a if _to_epoch(a) >= _to_epoch(b) else b
-
-
 def _row_to_memory(row: sqlite3.Row) -> CodingMemory:
     """SQLite row → CodingMemory"""
     return CodingMemory(
@@ -336,7 +293,6 @@ def _row_to_memory(row: sqlite3.Row) -> CodingMemory:
         confidence=row["confidence"],
         source=row["source"],
         extraction_source=row["extraction_source"],
-        memory_at=_from_epoch(row["memory_at"]),
         created_at=_parse_dt(row["created_at"]),
         updated_at=_parse_dt(row["updated_at"]),
     )
@@ -363,7 +319,6 @@ def _row_to_fact(row: sqlite3.Row) -> WorkingFact:
         # 老库刚 ADD COLUMN 时可能取不到这一列，用 keys() 兜一下
         fact_chain_summary=(row["fact_chain_summary"] or ""
                             if "fact_chain_summary" in row.keys() else ""),
-        memory_at=_from_epoch(row["memory_at"]),
         created_at=_parse_dt(row["created_at"]),
     )
 
@@ -461,36 +416,6 @@ class CodingMemoryStore:
 
         self._initialized = False
 
-    @staticmethod
-    def database_path(
-        config: MemoryConfig,
-        db_path: Optional[str] = None,
-        variant: str = "working",
-    ) -> str:
-        """Return the authoritative SQLite path without creating anything."""
-        if db_path is None:
-            data_dir = (
-                os.path.dirname(config.history.db_path)
-                if config.history.db_path else "./data"
-            )
-            db_path = os.path.join(data_dir, "coding_memory.db")
-        normalized = (
-            "coding"
-            if str(variant or "").strip().lower() == "coding"
-            else "working"
-        )
-        return _variant_db_path(db_path, "_cv" if normalized == "coding" else "")
-
-    @classmethod
-    def database_exists(
-        cls,
-        config: MemoryConfig,
-        db_path: Optional[str] = None,
-        variant: str = "working",
-    ) -> bool:
-        """Whether a coding namespace has an existing SQLite database."""
-        return os.path.isfile(cls.database_path(config, db_path, variant))
-
     async def initialize(self) -> None:
         if self._initialized:
             return
@@ -605,11 +530,7 @@ class CodingMemoryStore:
         await self._upsert_vec_keys(memory)
         logger.info(
             f"[coding-store] inserted experience_id={memory.experience_id} "
-            f"keys={1 + len(memory.search_keys)}"
-        )
-        logger.debug(
-            f"[coding-store] inserted experience_id={memory.experience_id} "
-            f"task={memory.task!r}"
+            f"task={memory.task!r} keys={1 + len(memory.search_keys)}"
         )
 
     async def update(self, memory: CodingMemory) -> None:
@@ -631,8 +552,6 @@ class CodingMemoryStore:
         memory.updated_at = datetime.utcnow()
         if memory.created_at is None:
             memory.created_at = prev.created_at
-        # 合并后的经验讲的是两段对话，对话时间取较晚的那段
-        memory.memory_at = _later(prev.memory_at, memory.memory_at)
         await _run_in_pool(self._upsert_sql_sync, memory)
         # 删旧 VDB
         await self._delete_vec_keys_by_count(memory.experience_id, prev_key_count)
@@ -654,86 +573,6 @@ class CodingMemoryStore:
         logger.info(f"[coding-store] deleted experience_id={experience_id}")
         return True
 
-    async def edit_experience(
-        self,
-        experience_id: str,
-        *,
-        user_id: Optional[str] = None,
-        task: Optional[str] = None,
-        solution: Optional[str] = None,
-        search_keys: Optional[List[str]] = None,
-    ) -> Optional[CodingMemory]:
-        """调用方手动改一条经验（client.update 用）。返回改后的经验；不存在返回 None。
-
-        与 update() 的区别：update 是写入链路的覆盖式重写，带写授权校验（同
-        agent/session/workspace 才能改）；这里是用户对已有条目的直接编辑，只动
-        给定的字段，其余原样保留，因此不做授权校验。
-
-        向量行只嵌 task + search_keys（solution 不进向量），所以只改 solution 时
-        不重嵌、不碰向量库；改了 task / search_keys 才删旧 key 行重写。
-        updated_at 总是刷新。
-        """
-        prev = await self.get_by_id(experience_id, user_id=user_id)
-        if prev is None:
-            return None
-        updated = deepcopy(prev)
-        if task is not None:
-            updated.task = task
-        if solution is not None:
-            updated.solution = solution
-        if search_keys is not None:
-            updated.search_keys = list(search_keys)
-        updated.updated_at = datetime.utcnow()
-        await _run_in_pool(self._upsert_sql_sync, updated)
-        if updated.task != prev.task or updated.search_keys != prev.search_keys:
-            await self._delete_vec_keys_by_count(experience_id, 1 + len(prev.search_keys))
-            await self._upsert_vec_keys(updated)
-        logger.info(f"[coding-store] edited experience_id={experience_id}")
-        return updated
-
-    async def edit_fact(
-        self,
-        fact_id: str,
-        *,
-        statement: str,
-        user_id: Optional[str] = None,
-    ) -> Optional[WorkingFact]:
-        """调用方手动改一条事实的 statement。返回改后的事实；不存在返回 None。
-
-        statement 是事实层的检索文本，所以 active 事实会重嵌并覆盖它那一行向量
-        （node_id 就是 fact_id，upsert 即覆盖）。superseded 事实的向量行早已撤掉，
-        这里不把它加回去，否则会让过期结论重新占召回名额。
-        """
-        prev = await self.get_fact(fact_id, user_id=user_id)
-        if prev is None:
-            return None
-        updated = deepcopy(prev)
-        updated.statement = statement
-        await _run_in_pool(self._upsert_fact_sql_sync, updated)
-        if updated.status == "active":
-            await self._upsert_fact_vec(updated)
-        logger.info(f"[coding-store] edited fact_id={fact_id}")
-        return updated
-
-    async def delete_fact(self, fact_id: str, user_id: Optional[str] = None) -> bool:
-        """物理删除一条事实（SQLite 行 + 事实向量行），返回是否真有删到。
-
-        别处留下的引用（经验的 source_fact_ids、后继事实的 fact_link）不清：
-        召回侧本来就按存在性过滤死链（get_many / get_facts 查不到自然掉队）。
-        """
-        prev = await self.get_fact(fact_id, user_id=user_id)
-        if prev is None:
-            logger.info(f"[coding-store] delete fact skipped (not found): {fact_id}")
-            return False
-        if self._fact_vec is not None:
-            try:
-                await self._fact_vec.delete(fact_id)
-            except Exception as e:
-                logger.debug(f"[coding-store] delete fact vec {fact_id} ignored: {e}")
-        await _run_in_pool(self._delete_fact_sql_sync, fact_id, prev.user_id)
-        logger.info(f"[coding-store] deleted fact_id={fact_id}")
-        return True
-
     # ------------------------------------------------------------
     # 读取
     # ------------------------------------------------------------
@@ -818,84 +657,29 @@ class CodingMemoryStore:
         branch: Optional[str] = None,
         limit: int = 100,
         offset: int = 0,
-        include_sources: Optional[List[str]] = None,
-        exclude_sources: Optional[List[str]] = None,
     ) -> List["CodingMemory"]:
         """按 workspace_id（+可选 branch）纯过滤列出该 user 的完整 coding memory。
 
         作用域规则见 _scope_where（与 search 路径共用同一套）。无语义排序，按
-        updated_at 倒序（最近修改优先）。include_sources / exclude_sources 按
-        source 列在 SQL 里过滤（排除优先），所以 LIMIT/OFFSET 在过滤之后生效。
+        updated_at 倒序（最近修改优先）。
         """
         return await _run_in_pool(
-            self._list_by_workspace_sync, user_id, workspace_id, branch, limit, offset,
-            include_sources, exclude_sources,
+            self._list_by_workspace_sync, user_id, workspace_id, branch, limit, offset
         )
 
     def _list_by_workspace_sync(
         self, user_id: str, workspace_id: str, branch: Optional[str],
         limit: int, offset: int,
-        include_sources: Optional[List[str]] = None,
-        exclude_sources: Optional[List[str]] = None,
     ) -> List["CodingMemory"]:
         scope_sql, scope_params = _scope_where(workspace_id, branch)
-        source_sql, source_params = _source_where(include_sources, exclude_sources)
         with self._lock:
             assert self._conn is not None
             sql = (f"SELECT * FROM coding_memory_meta WHERE user_id = ? AND {scope_sql} "
-                   f"AND {source_sql} "
-                   f"ORDER BY updated_at DESC, experience_id ASC LIMIT ? OFFSET ?")
-            params: List[Any] = ([user_id] + scope_params + source_params
-                                 + [limit, offset])
+                   f"ORDER BY updated_at DESC LIMIT ? OFFSET ?")
+            params: List[Any] = [user_id] + scope_params + [limit, offset]
             cur = self._conn.execute(sql, params)
             return [_row_to_memory(r) for r in cur.fetchall()]
 
-    async def stats(
-        self,
-        user_id: str,
-        workspace_id: Optional[str] = None,
-        branch: Optional[str] = None,
-        include_sources: Optional[List[str]] = None,
-        exclude_sources: Optional[List[str]] = None,
-    ) -> Dict[str, Any]:
-        """经验数、最新创建/修改时间、active 事实数。纯聚合，不读正文。
-
-        作用域与 list_by_workspace 相同：workspace_id 为空表示该 user 全部；
-        来源过滤同样与 list_by_workspace 一致，count 因此恒等于分页可翻到的总数。
-        """
-        return await _run_in_pool(
-            self._stats_sync, user_id, workspace_id, branch,
-            include_sources, exclude_sources,
-        )
-
-    def _stats_sync(
-        self, user_id: str, workspace_id: Optional[str], branch: Optional[str],
-        include_sources: Optional[List[str]] = None,
-        exclude_sources: Optional[List[str]] = None,
-    ) -> Dict[str, Any]:
-        scope_sql, scope_params = _scope_where(workspace_id, branch)
-        source_sql, source_params = _source_where(include_sources, exclude_sources)
-        with self._lock:
-            assert self._conn is not None
-            row = self._conn.execute(
-                f"SELECT COUNT(*) AS n, MAX(created_at) AS created, "
-                f"MAX(updated_at) AS updated FROM coding_memory_meta "
-                f"WHERE user_id = ? AND {scope_sql} AND {source_sql}",
-                [user_id] + scope_params + source_params,
-            ).fetchone()
-            facts = self._conn.execute(
-                f"SELECT COUNT(*) AS n FROM working_fact "
-                f"WHERE user_id = ? AND status = 'active' AND {scope_sql} "
-                f"AND {source_sql}",
-                [user_id] + scope_params + source_params,
-            ).fetchone()
-        return {
-            "count": int(row["n"] or 0),
-            "latest_created_at": _parse_dt(row["created"]) if row["created"] else None,
-            "latest_updated_at": _parse_dt(row["updated"]) if row["updated"] else None,
-            "facts": int(facts["n"] or 0),
-        }
-
     # ------------------------------------------------------------
     # 召回
     # ------------------------------------------------------------
@@ -1006,8 +790,7 @@ class CodingMemoryStore:
             fact.created_at = datetime.utcnow()
         await _run_in_pool(self._upsert_fact_sql_sync, fact)
         await self._upsert_fact_vec(fact)
-        logger.info(f"[coding-store] inserted fact_id={fact.fact_id}")
-        logger.debug(
+        logger.info(
             f"[coding-store] inserted fact_id={fact.fact_id} "
             f"statement={fact.statement!r}"
         )
@@ -1236,8 +1019,8 @@ class CodingMemoryStore:
                     experience_id, user_id, agent_id, task, search_keys, solution,
                     boundary_envs, workspace_id, branch, session_id,
                     files, source_fact_ids, confidence, source, extraction_source,
-                    memory_at, created_at, updated_at
-                ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+                    created_at, updated_at
+                ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
                 ON CONFLICT(experience_id) DO UPDATE SET
                     user_id         = excluded.user_id,
                     agent_id        = excluded.agent_id,
@@ -1253,7 +1036,6 @@ class CodingMemoryStore:
                     confidence      = excluded.confidence,
                     source          = excluded.source,
                     extraction_source = excluded.extraction_source,
-                    memory_at       = excluded.memory_at,
                     updated_at      = excluded.updated_at
                 """,
                 (
@@ -1264,7 +1046,6 @@ class CodingMemoryStore:
                     json.dumps(memory.files, ensure_ascii=False),
                     json.dumps(memory.source_fact_ids, ensure_ascii=False),
                     memory.confidence, memory.source, memory.extraction_source,
-                    _to_epoch(memory.memory_at),
                     (memory.created_at or datetime.utcnow()).isoformat(),
                     (memory.updated_at or datetime.utcnow()).isoformat(),
                 ),
@@ -1277,14 +1058,6 @@ class CodingMemoryStore:
                 (experience_id, user_id),
             )
 
-    def _delete_fact_sql_sync(self, fact_id: str, user_id: str) -> None:
-        with self._lock:
-            assert self._conn is not None
-            self._conn.execute(
-                "DELETE FROM working_fact WHERE fact_id = ? AND user_id = ?",
-                (fact_id, user_id),
-            )
-
     def _get_by_id_sync(
         self, experience_id: str, user_id: Optional[str]
     ) -> Optional[CodingMemory]:
@@ -1405,8 +1178,8 @@ class CodingMemoryStore:
                     fact_id, user_id, agent_id, session_id, workspace_id, branch,
                     source, statement, files, subject, details,
                     fact_link, derived_experience_ids,
-                    status, fact_chain_summary, memory_at, created_at
-                ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+                    status, fact_chain_summary, created_at
+                ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
                 ON CONFLICT(fact_id) DO UPDATE SET
                     user_id                = excluded.user_id,
                     agent_id               = excluded.agent_id,
@@ -1421,8 +1194,7 @@ class CodingMemoryStore:
                     fact_link              = excluded.fact_link,
                     derived_experience_ids = excluded.derived_experience_ids,
                     status                 = excluded.status,
-                    fact_chain_summary     = excluded.fact_chain_summary,
-                    memory_at              = excluded.memory_at
+                    fact_chain_summary     = excluded.fact_chain_summary
                 """,
                 (
                     fact.fact_id, fact.user_id, fact.agent_id,
@@ -1435,7 +1207,6 @@ class CodingMemoryStore:
                     json.dumps(fact.derived_experience_ids, ensure_ascii=False),
                     fact.status,
                     fact.fact_chain_summary or "",
-                    _to_epoch(fact.memory_at),
                     (fact.created_at or datetime.utcnow()).isoformat(),
                 ),
             )

hy_memory/coding/types.py

@@ -25,11 +25,6 @@ FactStatus = Literal["active", "superseded"]
 MAX_FACT_CHAIN_ENTRIES = 8
 
 
-def _epoch(value: Optional[datetime]) -> Optional[int]:
-    """memory_at 对外是秒级 epoch，与 chat 一致。"""
-    return int(value.timestamp()) if isinstance(value, datetime) else None
-
-
 # ================================================================
 # 草稿（LLM extract 阶段输出）
 # ================================================================
@@ -58,8 +53,6 @@ class CodingMemoryDraft:
     files: List[str] = field(default_factory=list)
     source: str = "default"
     extraction_source: str = "auto_extract"
-    # 对话时间（SDK 注入，同 chat 的 memory_at）
-    memory_at: Optional[datetime] = None
 
     def __post_init__(self) -> None:
         from ..utils.source_filter import normalize_source
@@ -80,7 +73,6 @@ class CodingMemoryDraft:
             "files": list(self.files),
             "source": self.source,
             "extraction_source": self.extraction_source,
-            "memory_at": _epoch(self.memory_at),
         }
 
 
@@ -119,9 +111,6 @@ class CodingMemory:
     extraction_source: str = "auto_extract"
 
     # 时间
-    # memory_at 是对话时间（同 chat），created_at / updated_at 是写库时间。
-    # UPDATE 合并时取两者中较晚的那个对话时间，见 store.update。
-    memory_at: Optional[datetime] = None
     created_at: Optional[datetime] = None
     updated_at: Optional[datetime] = None
 
@@ -146,7 +135,6 @@ class CodingMemory:
             "confidence": self.confidence,
             "source": self.source,
             "extraction_source": self.extraction_source,
-            "memory_at": _epoch(self.memory_at),
             "created_at": self.created_at.isoformat() if self.created_at else None,
             "updated_at": self.updated_at.isoformat() if self.updated_at else None,
         }
@@ -261,7 +249,6 @@ class WorkingFact:
     fact_chain_summary: str = ""
 
     # 时间
-    memory_at: Optional[datetime] = None   # 对话时间（同 chat），没传时是收到请求的时间
     created_at: Optional[datetime] = None  # 产生时间，新的优先
 
     def __post_init__(self) -> None:
@@ -285,7 +272,6 @@ class WorkingFact:
             "derived_experience_ids": list(self.derived_experience_ids),
             "status": self.status,
             "fact_chain_summary": self.fact_chain_summary,
-            "memory_at": _epoch(self.memory_at),
             "created_at": self.created_at.isoformat() if self.created_at else None,
         }
 

hy_memory/coding/writer.py

@@ -18,7 +18,6 @@ CodingWriter - 写入端协调器
 import logging
 import time
 import uuid
-from datetime import datetime
 from typing import Any, Dict, List, Optional
 
 from ..agent.llm_provider import LLMProvider
@@ -51,7 +50,6 @@ class CodingWriter:
         embed_service: EmbedService,
         fact_reconciler: Optional[WorkingFactReconciler] = None,
         cache: Any = None,
-        variant: str = "working",
     ):
         self.store = store
         self.extractor = extractor
@@ -61,11 +59,6 @@ class CodingWriter:
         self.fact_reconciler = fact_reconciler or WorkingFactReconciler(
             store, embed_service, llm_provider
         )
-        self.variant = (
-            "coding"
-            if str(variant or "").strip().lower() == "coding"
-            else "working"
-        )
         # cache 仅用于把 request_id 串给各阶段（各阶段自己打点）；writer 不集中打点。
         self.cache = cache
 
@@ -80,11 +73,9 @@ class CodingWriter:
         session_id: Optional[str] = None,
         request_id: Optional[str] = None,
         source: str = "default",
-        memory_at: Optional[datetime] = None,
     ) -> Dict[str, Any]:
         """
-        working/coding 段写入端到端。memory_at 是对话时间，记到这次写出的经验和
-        事实上；不传则用收到请求的时间（与 chat 链路一致）。返回响应 dict（兼容 client.add 返回结构）：
+        working/coding 段写入端到端。返回响应 dict（兼容 client.add 返回结构）：
             {
                 "success": True,
                 "scene": "productivity",
@@ -104,8 +95,6 @@ class CodingWriter:
         """
         request_id = request_id or str(uuid.uuid4())
         t0 = time.perf_counter()
-        if memory_at is None:
-            memory_at = datetime.now()
 
         if not messages:
             return self._empty_response(request_id, t0)
@@ -177,7 +166,6 @@ class CodingWriter:
         # extractor 只负责内容；调用来源由 SDK 入口注入，不能交给 LLM 生成。
         for draft in drafts:
             draft.source = source
-            draft.memory_at = memory_at
 
         # 3. 经验层 reconcile + 持久化
         ops: List[ReconcileOp] = (
@@ -203,7 +191,6 @@ class CodingWriter:
                 workspace_id=workspace_id,
                 branch=branch,
                 source=source,
-                memory_at=memory_at,
             )
 
         experience_ids = [op.target_experience_id for op in ops
@@ -230,7 +217,6 @@ class CodingWriter:
         return {
             "success": True,
             "scene": "productivity",
-            "variant": self.variant,
             "request_id": request_id,
             "elapsed_ms": round((time.perf_counter() - t0) * 1000, 2),
             "ops": [op.to_dict() for op in ops],
@@ -292,11 +278,11 @@ class CodingWriter:
                         f"[coding-write] crosslink fact {f.fact_id} failed: {e}"
                     )
 
-    def _empty_response(self, request_id: str, t0: float) -> Dict[str, Any]:
+    @staticmethod
+    def _empty_response(request_id: str, t0: float) -> Dict[str, Any]:
         return {
             "success": True,
             "scene": "productivity",
-            "variant": self.variant,
             "request_id": request_id,
             "elapsed_ms": round((time.perf_counter() - t0) * 1000, 2),
             "ops": [],

hy_memory/core/embed_service.py

@@ -80,7 +80,7 @@ def _count_tokens(text: str) -> int:
     try:
         import tiktoken
 
-        return len(tiktoken.get_encoding("cl100k_base").encode(text, disallowed_special=()))
+        return len(tiktoken.get_encoding("cl100k_base").encode(text))
     except Exception:
         return len(text) // _CHARS_PER_TOKEN_FALLBACK + 1
 
@@ -98,8 +98,7 @@ def _truncate_for_embedding(text: str, limit: int = _EMBED_MAX_TOKENS) -> str:
         import tiktoken
 
         enc = tiktoken.get_encoding("cl100k_base")
-        # Input is ordinary user text, not a tokenizer control-token stream.
-        ids = enc.encode(text, disallowed_special=())
+        ids = enc.encode(text)
         if len(ids) <= limit:
             return text
         dropped = len(ids) - limit
@@ -754,22 +753,16 @@ class EmbedService:
         """
         打一条 INFO 级 embedding 请求日志（含 request_id / provider / model / api / 入参 / 出参）。
 
-        出参只含 vector 维度，不含向量数值。入参的 input 是待向量化的原文
-        （对话 / 记忆 / 查询），INFO 只记每条的字符数（input_chars），原文仅在
-        DEBUG 单独输出。request_id 同时写入 message，
+        出参只含 vector 维度，不含向量数值。request_id 同时写入 message，
         并依赖 log formatter 的 %(request_id)s（setup_logging 后生效）。
         """
-        texts = request_payload.get("input")
-        info_request = {k: v for k, v in request_payload.items() if k != "input"}
-        if isinstance(texts, list):
-            info_request["input_chars"] = [len(str(t)) for t in texts]
         payload = {
             "request_id": get_request_id(),
             "status": status,
             "provider": self._embed_config.provider,
             "model": self._embed_config.model,
             "api": api_url,
-            "request": info_request,
+            "request": request_payload,
             "response": response_payload,
         }
         try:
@@ -777,10 +770,6 @@ class EmbedService:
         except Exception:
             body = str(payload)
         logger.info(f"[embed] {body}")
-        if texts is not None and logger.isEnabledFor(logging.DEBUG):
-            logger.debug(
-                f"[embed] input: {json.dumps(texts, ensure_ascii=False, default=str)}"
-            )
 
     async def _embed_openai(
         self, texts: List[str]

hy_memory/embedding.py

@@ -1,53 +0,0 @@
-"""Public structural contract for injected embedding services."""
-
-from typing import Any, Dict, List, Protocol, Tuple, runtime_checkable
-
-
-@runtime_checkable
-class EmbeddingService(Protocol):
-    """Embedding service accepted by :class:`HyMemoryClient`.
-
-    Implementations are borrowed by the client: their lifecycle remains owned
-    by the caller and ``HyMemoryClient.close()`` will not close them.
-    """
-
-    async def embed(self, text: str, use_cache: bool = True) -> List[float]:
-        ...
-
-    async def embed_with_meta(
-        self, text: str, use_cache: bool = True
-    ) -> Tuple[List[float], Dict[str, Any]]:
-        ...
-
-    async def embed_batch(
-        self, texts: List[str], use_cache: bool = True
-    ) -> List[List[float]]:
-        ...
-
-    async def embed_queued(
-        self, text: str, use_cache: bool = True
-    ) -> List[float]:
-        ...
-
-    async def embed_queued_with_meta(
-        self, text: str, use_cache: bool = True
-    ) -> Tuple[List[float], Dict[str, Any]]:
-        ...
-
-    def get_embedding_dims(self) -> int:
-        ...
-
-
-# Explicit alias for callers that prefer the conventional Protocol suffix.
-EmbeddingServiceProtocol = EmbeddingService
-
-
-class EmbeddingDimensionMismatchError(ValueError):
-    """Raised before initialization when service and store dimensions differ."""
-
-
-__all__ = [
-    "EmbeddingService",
-    "EmbeddingServiceProtocol",
-    "EmbeddingDimensionMismatchError",
-]

hy_memory/pipelines/_retrieval/diversity.py

@@ -160,28 +160,6 @@ def near_dup_demote(
     return out
 
 
-# MMR 只在调用方请求的 top-k（search 的 limit）小于这个值时自动启用。
-# mmr_select 的贪心是 O(k^2 * pool) 次 Jaccard，k 大时代价陡增，而大 k 本身已
-# 足够容纳多样性，收益很小。权重仍由 MEMORY_HYBRID_V2_MMR_LAMBDA 控制。
-MMR_MAX_TOP_K = 20
-
-
-def mmr_applies(top_k: int, lambda_: float) -> bool:
-    """本次检索是否走 MMR：λ 在有效区间内，且 top_k < MMR_MAX_TOP_K。"""
-    return 0.0 < float(lambda_) < 0.999 and int(top_k) < MMR_MAX_TOP_K
-
-
-def near_dup_applies(top_k: int) -> bool:
-    """本次检索是否走近重复降权：与 MMR 同一个 top-k 门槛。
-
-    near_dup_demote 让每个候选和此前所有"非重复"候选两两算 Jaccard，候选
-    互不相似时是 O(pool^2)；池子随 limit 放大（约 max(3*limit, 30) + 关键词
-    命中），limit 达到 MMR_MAX_TOP_K 时代价同样陡增。大 k 的调用方（如记忆
-    面板翻页）要的是全部相关项，相似项也应照常出现，降权没有收益。
-    """
-    return int(top_k) < MMR_MAX_TOP_K
-
-
 def mmr_select(
     hits: Sequence[Dict[str, Any]],
     limit: int,

hy_memory/pipelines/_retrieval/reconcile_retrieval.py

@@ -115,16 +115,11 @@ class ReconcileHybridRetriever:
         fused_max = max(fused_all) if fused_all else 0.0
 
         base = (
-            f"[reconcile-hybrid][{req}] pool={pool_size} q_terms={len(q_terms)} "
+            f"[reconcile-hybrid][{req}] pool={pool_size} q_terms={q_terms!r} "
             f"raw_bm25 max={raw_max:.4f} nonzero={raw_nonzero}/{len(raw_bm25)} "
             f"bm25_norm max={norm_max:.4f} nonzero={norm_nonzero}/{len(bm25_norms)} "
             f"sem_max={sem_max:.4f} fused_max={fused_max:.4f} "
             f"kept={kept}/{len(fused_all)} min_score={self._cfg.min_score} "
-            f"query({len(query_text or '')} chars)"
-        )
-        # query 是待对账的新记忆原文，词项与预览只进 DEBUG
-        logger.debug(
-            f"[reconcile-hybrid][{req}] q_terms={q_terms!r} "
             f"query={q_preview!r} lemmatized={lem_preview!r}"
         )
 

hy_memory/pipelines/base.py

@@ -231,6 +231,10 @@ class WriteRequest:
     # 已有记忆 (V1 合并检测用)
     existing_memories: Optional[List[Dict[str, Any]]] = None
 
+    # Public client process_raw() only: reuse these exact L1 nodes as input.
+    # Ordinary add() never populates this field.
+    existing_raw_ids: List[str] = field(default_factory=list)
+
     # 记忆时间戳（不传则用当前时间 datetime.now()）
     memory_at: Optional[datetime] = None
 
@@ -401,11 +405,6 @@ class ReadRequest:
     intention_limit: int = 0           # Intention 路的 topk，默认 0 关闭
 
 
-    # 重排开关（按次生效）。False 时跳过全部重排阶段：本地 cross-encoder
-    # (recall.local_rerank_enabled) 与记忆关系图重排 (_apply_graph_rerank)，
-    # 结果按召回分排序。走请求对象而非环境变量，并发请求互不影响。
-    rerank: bool = True
-
     # 时间过滤
     created_after: Optional[float] = None  # Unix timestamp (float)，只返回 gmt_created >= 此值的记忆
 

hy_memory/pipelines/cross_domain_sweeper.py

@@ -692,10 +692,9 @@ class CrossDomainSweeper:
                 )
 
             logger.info(
-                f"[sweeper] Created L6 core {core_id[:12]} "
+                f"[sweeper] Created L6 core {core_id[:12]}: '{core_content[:60]}' "
                 f"from {len(cluster_ids)} basics, evidence_inherited={len(inherited_evidence_ids)}"
             )
-            logger.debug(f"[sweeper] L6 core {core_id[:12]} content={core_content[:60]!r}")
             return 1, 0, [core_id]
 
         except Exception as e:

hy_memory/pipelines/reader_base.py

@@ -57,9 +57,7 @@ from ._retrieval.ner import (
     memory_matches_time_hints,
 )
 from ._retrieval.diversity import (
-    near_dup_applies,
     near_dup_demote,
-    mmr_applies,
     mmr_select,
     social_boilerplate_demote,
     pool_df_demote,
@@ -1281,10 +1279,7 @@ class BaseReadPipeline(ReadPipeline):
             SAME_SERIES_TIMELINE_ON = bool(
                 getattr(self.config.recall, "same_series_timeline_enabled", False)
             )
-            # 按次的重排开关（search(rerank=False)）：关掉本地 cross-encoder 与图重排，
-            # 结果按召回分排序。只读请求对象，不碰共享状态，并发请求互不影响。
-            RERANK_ON = bool(getattr(request, "rerank", True))
-            LOCAL_RERANK_ON = RERANK_ON and bool(
+            LOCAL_RERANK_ON = bool(
                 getattr(self.config.recall, "local_rerank_enabled", False)
             )
             LOCAL_RERANK_POOL_FACTOR = max(1, int(
@@ -1436,11 +1431,6 @@ class BaseReadPipeline(ReadPipeline):
             MIN_SCORE = _resolve_normal_min_score(request.min_score)
 
             final_limit = request.limit if request.limit > 0 else 10
-            # MMR 只在调用方的 top-k（final_limit，即 search 的 limit）< MMR_MAX_TOP_K
-            # 时启用；池子（LOCAL_RERANK 下是 final_limit 的若干倍）不参与判定。
-            MMR_ON = mmr_applies(final_limit, MMR_LAMBDA)
-            # 近重复降权同样是候选两两比较，用同一个 top-k 门槛。
-            NEAR_DUP_ON = near_dup_applies(final_limit)
             vdb_sem_limit = max(final_limit * 3, 30)
             vdb_kw_limit = max(final_limit * 5, 80)
             graph_limit = max(
@@ -2472,7 +2462,7 @@ class BaseReadPipeline(ReadPipeline):
             # 只把已选出的 top-N 换个顺序收益很小。
             relation_paths: List[Dict[str, Any]] = []
             _graph_stats: Dict[str, Any] = {}
-            if RERANK_ON and self._expansion_on():
+            if self._expansion_on():
                 _t_graph = datetime.now()
                 _pool_before = len(normal_results)
                 normal_results, relation_paths, _graph_stats = await self._apply_graph_rerank(
@@ -2535,7 +2525,7 @@ class BaseReadPipeline(ReadPipeline):
                         df_thr=POOL_DF_THR,
                         penalty=POOL_DF_PENALTY,
                     )
-                if NEAR_DUP_ON and NEAR_DUP_THR > 0 and NEAR_DUP_PENALTY > 0:
+                if NEAR_DUP_THR > 0 and NEAR_DUP_PENALTY > 0:
                     normal_results = near_dup_demote(
                         normal_results,
                         jaccard_thr=NEAR_DUP_THR,
@@ -2548,7 +2538,7 @@ class BaseReadPipeline(ReadPipeline):
                     ))
                     if LOCAL_RERANK_ON else final_limit
                 )
-                if MMR_ON and len(normal_results) > _pre_rerank_limit:
+                if 0.0 < MMR_LAMBDA < 0.999 and len(normal_results) > _pre_rerank_limit:
                     normal_results = mmr_select(
                         normal_results,
                         _pre_rerank_limit,
@@ -2725,7 +2715,7 @@ class BaseReadPipeline(ReadPipeline):
                         reverse=True,
                     )
                     if (
-                        MMR_ON
+                        0.0 < MMR_LAMBDA < 0.999
                         and len(multi_seed_pool) > _pre_rerank_limit
                     ):
                         multi_seed_pool = mmr_select(
@@ -3554,9 +3544,6 @@ class BaseReadPipeline(ReadPipeline):
                 "episode_capsule_render_mode": EPISODE_CAPSULE_RENDER_MODE,
                 "same_series_timeline_enabled": SAME_SERIES_TIMELINE_ON,
                 "local_rerank_enabled": LOCAL_RERANK_ON,
-                "rerank": RERANK_ON,
-                "mmr_applied": MMR_ON,
-                "near_dup_applied": NEAR_DUP_ON,
                 "local_rerank_model": getattr(
                     self.config.recall,
                     "local_rerank_model",
@@ -3587,9 +3574,8 @@ class BaseReadPipeline(ReadPipeline):
                 f"hidden_l0={len(hidden_l0_hits)} fwd_l6={len(forward_l6)} rev_l6={len(reverse_l6)} "
                 f"fused_l6={len(fused_l6)} graph_intent={len(graph_intention_hits)} "
                 f"returned={len(final_results)} "
-                f"query({len(request.query or '')} chars)"
+                f"query='{request.query[:80]}'"
             )
-            logger.debug(f"[read/{self.VERSION}] query={request.query[:80]!r}")
 
             response.success = True
 

hy_memory/pipelines/registry.py

@@ -19,7 +19,6 @@ import logging
 from .base import WritePipeline, ReadPipeline
 from ..config import MemoryConfig
 from ..core.embed_service import EmbedService
-from ..embedding import EmbeddingService
 from ..data.vector_store import create_vector_store
 from ..data.vector_store_base import VectorStoreBase
 
@@ -51,12 +50,7 @@ class ComponentFactory:
         s2 = await factory.get_system2_writer()    # System2Writer (ultra mode)
     """
 
-    def __init__(
-        self,
-        config: Optional[MemoryConfig] = None,
-        *,
-        embedding_service: Optional[EmbeddingService] = None,
-    ):
+    def __init__(self, config: Optional[MemoryConfig] = None):
         self.config = config or MemoryConfig.from_env()
 
         # 实例缓存（单例）
@@ -68,7 +62,7 @@ class ComponentFactory:
         self._readers: Dict[str, ReadPipeline] = {}
 
         # 共享资源
-        self._shared_embed_service: Optional[EmbeddingService] = embedding_service
+        self._shared_embed_service: Optional[EmbedService] = None
         self._shared_vector_store: Optional[VectorStoreBase] = None
         self._shared_vector_store_initialized: bool = False
         self._shared_graph_store = None
@@ -78,7 +72,7 @@ class ComponentFactory:
     # 共享资源
     # ================================================================
 
-    def _get_shared_embed_service(self) -> EmbeddingService:
+    def _get_shared_embed_service(self) -> EmbedService:
         if self._shared_embed_service is None:
             self._shared_embed_service = EmbedService(self.config)
         return self._shared_embed_service

hy_memory/pipelines/system2_agent.py

@@ -2516,8 +2516,7 @@ def _parse_operations_json(text: str) -> Optional[List[Dict[str, Any]]]:
             return result
         return None
     except json.JSONDecodeError:
-        logger.warning(f"[S2-agent] JSON parse failed ({len(json_str)} chars)")
-        logger.debug(f"[S2-agent] unparsable output: {json_str[:200]!r}")
+        logger.warning(f"[S2-agent] JSON parse failed: {json_str[:200]}")
         return None
 
 

hy_memory/pipelines/writer.py

@@ -280,6 +280,27 @@ class MemoryWriter(WritePipeline):
             custom["source_raw_memory_ids"] = source_ids
         return custom
 
+    async def _attach_existing_raw_ids(
+        self,
+        vector_store,
+        memory_ids: List[str],
+        raw_ids: List[str],
+    ) -> None:
+        """Attach every reused raw record to canonical outputs."""
+        for memory_id in memory_ids:
+            node = await vector_store.get_by_id(memory_id)
+            if node is None:
+                continue
+            custom = dict(node.custom or {})
+            source_ids = list(custom.get("source_raw_memory_ids") or [])
+            legacy_source = str(getattr(node, "source_raw_memory_id", "") or "")
+            for raw_id in (legacy_source, *raw_ids):
+                if raw_id and raw_id not in source_ids:
+                    source_ids.append(raw_id)
+            if source_ids:
+                custom["source_raw_memory_ids"] = source_ids
+                await vector_store.update_payload(memory_id, {"custom": custom})
+
     @staticmethod
     def _attach_client_meta(custom: Dict[str, Any], request: Optional[WriteRequest]) -> None:
         """给新建节点挂上调用方 meta（单份 list）。
@@ -2596,13 +2617,23 @@ class MemoryWriter(WritePipeline):
             from ..metrics import MetricsCollector
             MetricsCollector.get().sys1_start()
 
-            # 2. 向量化 + 持久化（L1_RAW）
+            existing_raw_ids = request.existing_raw_ids
+            if (
+                not isinstance(existing_raw_ids, list)
+                or any(not isinstance(raw_id, str) or not raw_id for raw_id in existing_raw_ids)
+            ):
+                raise ValueError("_existing_raw_ids must be a list of non-empty ids")
+
+            # 2. 向量化（处理已有 raw 时复用已存节点，不再次 embed）
             _t_embed = datetime.now()
-            with tracer.span("embed") as s:
-                embedding, embed_meta = await self.embed_service.embed_queued_with_meta(
-                    request.content
-                )
-                s.set_output({"dims": len(embedding), "content_len": len(request.content)})
+            if existing_raw_ids:
+                embedding, embed_meta = [], {"reused_raw": True}
+            else:
+                with tracer.span("embed") as s:
+                    embedding, embed_meta = await self.embed_service.embed_queued_with_meta(
+                        request.content
+                    )
+                    s.set_output({"dims": len(embedding), "content_len": len(request.content)})
             _embed_ms = (datetime.now() - _t_embed).total_seconds() * 1000
             response.extra["embedding"] = embedding
             await self._emit_pipeline_step(
@@ -2625,27 +2656,43 @@ class MemoryWriter(WritePipeline):
             with tracer.span("qdrant_upsert") as s:
                 try:
                     vector_store = await self._get_vector_store()
-                    layer_enum = MemoryLayer.from_string(suggested_layer)
-                    _raw_custom: Dict[str, Any] = {}
-                    self._attach_client_meta(_raw_custom, request)
-                    mem_node = MemoryNode(
-                        user_id=request.user_id,
-                        agent_id=request.agent_id or "default_agent",
-                        session_id=request.session_id or "default_session",
-                        source=request.source,
-                        layer=layer_enum,
-                        content=request.content,
-                        source_type=SourceType.EXPLICIT,
-                        status=MemoryStatus.ACTIVE,
-                        is_latest=True,
-                        embedding=embedding,
-                        memory_at=request.memory_at,
-                        custom=_raw_custom,
-                    )
-                    memory_id = await vector_store.upsert(mem_node)
+                    if existing_raw_ids:
+                        memory_id = existing_raw_ids[-1]
+                        mem_node = await vector_store.get_by_id(memory_id)
+                        if (
+                            mem_node is None
+                            or mem_node.layer != MemoryLayer.L1_RAW
+                            or mem_node.user_id != request.user_id
+                            or mem_node.agent_id != (request.agent_id or "default_agent")
+                            or mem_node.session_id != (request.session_id or "default_session")
+                            or mem_node.source != request.source
+                        ):
+                            raise ValueError("existing raw record is outside the write scope")
+                    else:
+                        layer_enum = MemoryLayer.from_string(suggested_layer)
+                        _raw_custom: Dict[str, Any] = {}
+                        self._attach_client_meta(_raw_custom, request)
+                        mem_node = MemoryNode(
+                            user_id=request.user_id,
+                            agent_id=request.agent_id or "default_agent",
+                            session_id=request.session_id or "default_session",
+                            source=request.source,
+                            layer=layer_enum,
+                            content=request.content,
+                            source_type=SourceType.EXPLICIT,
+                            status=MemoryStatus.ACTIVE,
+                            is_latest=True,
+                            embedding=embedding,
+                            memory_at=request.memory_at,
+                            custom=_raw_custom,
+                        )
+                        memory_id = await vector_store.upsert(mem_node)
                     response.memory_id = memory_id
                     s.set_output({"memory_id": memory_id, "layer": suggested_layer})
-                    logger.debug(f"[write] persisted: id={memory_id} layer={suggested_layer}")
+                    logger.debug(
+                        f"[write] {'reused' if existing_raw_ids else 'persisted'}: "
+                        f"id={memory_id} layer={suggested_layer}"
+                    )
                 except Exception as persist_err:
                     _l1_error = str(persist_err)
                     s.set_error(_l1_error)
@@ -2709,6 +2756,12 @@ class MemoryWriter(WritePipeline):
                         recent_history_count=_recent_history_count,
                     )
                     total_tokens += response.extra.get("_agent_tokens", 0)
+                if existing_raw_ids and response.extra.get("agent_stored_ids"):
+                    await self._attach_existing_raw_ids(
+                        vector_store,
+                        list(response.extra["agent_stored_ids"]),
+                        existing_raw_ids,
+                    )
                 if response.extra.get("agent_status") == "failed":
                     await self._emit_pipeline_step(
                         request,
@@ -2718,12 +2771,13 @@ class MemoryWriter(WritePipeline):
                             "error": response.extra.get("agent_error", ""),
                         },
                     )
-                    await self._rollback_failed_l1(
-                        request=request,
-                        response=response,
-                        vector_store=vector_store,
-                        memory_id=memory_id,
-                    )
+                    if not existing_raw_ids:
+                        await self._rollback_failed_l1(
+                            request=request,
+                            response=response,
+                            vector_store=vector_store,
+                            memory_id=memory_id,
+                        )
                     response.tokens_used = total_tokens
                     _failed_workflow_ms = (
                         datetime.now() - _t_workflow

hy_memory/retrieval.py

@@ -1,23 +0,0 @@
-"""Public types and errors for exact memory-ID lookup."""
-
-from typing import Literal, Sequence
-
-
-MemoryKind = Literal["chat", "experience", "fact"]
-MemoryVariant = Literal["working", "coding"]
-
-
-class AmbiguousMemoryIdError(LookupError):
-    """An ID exists in more than one public memory namespace."""
-
-    def __init__(self, memory_id: str, namespaces: Sequence[str]):
-        self.memory_id = memory_id
-        self.namespaces = tuple(namespaces)
-        joined = ", ".join(self.namespaces)
-        super().__init__(
-            f"memory ID {memory_id!r} is ambiguous across namespaces: {joined}; "
-            "pass kind and/or variant to disambiguate"
-        )
-
-
-__all__ = ["MemoryKind", "MemoryVariant", "AmbiguousMemoryIdError"]

hy_memory/server.py

@@ -33,28 +33,9 @@ import threading
 from datetime import datetime
 from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
 from typing import Any, Dict, Optional
-from urllib.parse import parse_qs, urlparse
-
-from .retrieval import AmbiguousMemoryIdError
 
 logger = logging.getLogger("hy_memory.server")
 
-
-def _namespace_args(values: Dict[str, Any]) -> Dict[str, Any]:
-    """kind / variant from a query string (lists) or a JSON body (scalars).
-
-    They disambiguate an id that exists in more than one namespace (chat,
-    experience, fact; working or coding). Absent means "resolve it".
-    """
-    args: Dict[str, Any] = {}
-    for key in ("kind", "variant"):
-        value = values.get(key)
-        if isinstance(value, list):
-            value = value[0] if value else None
-        if value:
-            args[key] = str(value)
-    return args
-
 # Lazy-init global client
 _client = None
 _client_lock = None
@@ -167,6 +148,7 @@ class MemoryHTTPHandler(BaseHTTPRequestHandler):
             if path == "/api/v1/metrics":
                 minutes = 5
                 if "?" in self.path:
+                    from urllib.parse import parse_qs, urlparse
                     qs = parse_qs(urlparse(self.path).query)
                     minutes = int(qs.get("minutes", ["5"])[0])
                 client = _get_client()
@@ -179,8 +161,7 @@ class MemoryHTTPHandler(BaseHTTPRequestHandler):
             if m:
                 memory_id = m.group(1)
                 client = _get_client()
-                query = parse_qs(urlparse(self.path).query)
-                result = client.get(memory_id, **_namespace_args(query))
+                result = client.get(memory_id)
                 if result is None:
                     _json_response(self, 404, {"error": "not_found", "memory_id": memory_id})
                 else:
@@ -189,10 +170,6 @@ class MemoryHTTPHandler(BaseHTTPRequestHandler):
 
             _json_response(self, 404, {"error": "not_found", "path": path})
 
-        except AmbiguousMemoryIdError as e:
-            _json_response(self, 409, {"error": "ambiguous_memory_id", "detail": str(e)})
-        except ValueError as e:
-            _json_response(self, 400, {"error": str(e)})
         except Exception as e:
             logger.error(f"[server] GET {path} error: {e}", exc_info=True)
             _json_response(self, 500, {"error": str(e)})
@@ -236,7 +213,7 @@ class MemoryHTTPHandler(BaseHTTPRequestHandler):
             _json_response(self, 500, {"error": str(e)})
 
     def do_PUT(self):
-        path = self.path.split("?")[0].rstrip("/")
+        path = self.path.rstrip("/")
         body = _read_json_body(self)
         if body is None:
             _json_response(self, 400, {"error": "invalid JSON body"})
@@ -251,43 +228,29 @@ class MemoryHTTPHandler(BaseHTTPRequestHandler):
                     _json_response(self, 400, {"error": "content is required"})
                     return
                 client = _get_client()
-                result = client.update(
-                    memory_id,
-                    content,
-                    **_namespace_args(body),
-                    **({"task": body["task"]} if body.get("task") else {}),
-                )
+                result = client.update(memory_id, content)
                 _json_response(self, 200, result)
                 return
 
             _json_response(self, 404, {"error": "not_found", "path": path})
 
-        except AmbiguousMemoryIdError as e:
-            _json_response(self, 409, {"error": "ambiguous_memory_id", "detail": str(e)})
-        except ValueError as e:
-            _json_response(self, 400, {"error": str(e)})
         except Exception as e:
             logger.error(f"[server] PUT {path} error: {e}", exc_info=True)
             _json_response(self, 500, {"error": str(e)})
 
     def do_DELETE(self):
-        path = self.path.split("?")[0].rstrip("/")
+        path = self.path.rstrip("/")
         try:
             m = re.match(r"^/api/v1/memories/([^/]+)$", path)
             if m:
                 memory_id = m.group(1)
                 client = _get_client()
-                query = parse_qs(urlparse(self.path).query)
-                result = client.delete(memory_id, **_namespace_args(query))
+                result = client.delete(memory_id)
                 _json_response(self, 200, result)
                 return
 
             _json_response(self, 404, {"error": "not_found", "path": path})
 
-        except AmbiguousMemoryIdError as e:
-            _json_response(self, 409, {"error": "ambiguous_memory_id", "detail": str(e)})
-        except ValueError as e:
-            _json_response(self, 400, {"error": str(e)})
         except Exception as e:
             logger.error(f"[server] DELETE {path} error: {e}", exc_info=True)
             _json_response(self, 500, {"error": str(e)})
@@ -492,8 +455,7 @@ class MemoryHTTPHandler(BaseHTTPRequestHandler):
             if key in body:
                 kwargs[key] = body[key]
 
-        for key in ("limit", "min_score", "schema_min_score", "schema_limit", "reader",
-                    "rerank"):
+        for key in ("limit", "min_score", "schema_min_score", "schema_limit", "reader"):
             if key in body:
                 kwargs[key] = body[key]
 

hy_memory/utils/async_executor.py

@@ -4,7 +4,6 @@ from __future__ import annotations
 
 import asyncio
 import concurrent.futures
-import contextvars
 import functools
 from concurrent.futures import Executor
 from typing import Any, Callable, Optional
@@ -40,9 +39,7 @@ async def run_in_executor_guarded(
 
 async def to_thread_guarded(func: Callable[..., Any], *args: Any, **kwargs: Any) -> Any:
     """Guarded equivalent of ``asyncio.to_thread`` using the default pool."""
-    context = contextvars.copy_context()
-    call = functools.partial(func, *args, **kwargs)
-    return await run_in_executor_guarded(None, context.run, call)
+    return await run_in_executor_guarded(None, func, *args, **kwargs)
 
 
 def concurrent_result_guarded(

hy_memory/utils/lang_detect.py

@@ -8,7 +8,6 @@ Uses a two-tier strategy:
 This avoids langdetect's known weakness with short Chinese text.
 """
 
-import json
 import logging
 import re
 from typing import List, Optional
@@ -136,30 +135,6 @@ def detect_language(text: str) -> str:
     return "zh" if ratio > 0.1 else "en"
 
 
-def _spoken_text(value: str) -> str:
-    """Ignore text-block metadata when a message content is structured JSON."""
-    text = value.strip()
-    if text.startswith("["):
-        try:
-            blocks = json.loads(text)
-        except (ValueError, TypeError):
-            pass
-        else:
-            if (
-                isinstance(blocks, list)
-                and blocks
-                and all(
-                    isinstance(block, dict)
-                    and isinstance(block.get("type"), str)
-                    and block["type"] in {"text", "input_text", "output_text"}
-                    and isinstance(block.get("text"), str)
-                    for block in blocks
-                )
-            ):
-                return "\n".join(block["text"] for block in blocks)
-    return text
-
-
 def extract_content_for_detection(
     content: str = "",
     messages: Optional[List] = None,
@@ -178,57 +153,20 @@ def extract_content_for_detection(
         Concatenated content text suitable for language detection.
     """
     if content and content.strip():
-        value = content.strip()
-        # Writer serializes message batches to JSON before calling Extractor.
-        # Detect the spoken text, not the leading ASCII keys (role/content),
-        # without changing the raw evidence sent to the model.
-        if value.startswith("["):
-            try:
-                decoded = json.loads(value)
-            except (ValueError, TypeError):
-                pass
-            else:
-                if (
-                    isinstance(decoded, list)
-                    and decoded
-                    and all(
-                        isinstance(item, dict)
-                        and isinstance(item.get("role"), str)
-                        and isinstance(item.get("content"), str)
-                        for item in decoded
-                    )
-                ):
-                    # In a mixed batch, the latest user turn is the clearest
-                    # instruction for the language; assistant/tool metadata
-                    # must not decide it first.
-                    user_text = [
-                        _spoken_text(item["content"])
-                        for item in decoded
-                        if item["role"] == "user" and item["content"].strip()
-                    ]
-                    if user_text:
-                        return user_text[-1]
-                    spoken = "\n".join(_spoken_text(item["content"]) for item in decoded)
-                    if spoken.strip():
-                        return spoken
-        return _spoken_text(value)
+        return content.strip()
 
     if messages:
         parts = []
-        user_parts = []
         for msg in messages:
             if isinstance(msg, dict):
-                c, role = msg.get("content", ""), msg.get("role")
+                c = msg.get("content", "")
             elif hasattr(msg, "content"):
-                c, role = msg.content, getattr(msg, "role", None)
+                c = msg.content
             else:
                 continue
-            if isinstance(c, str) and c.strip():
-                text = _spoken_text(c)
-                parts.append(text)
-                if role == "user":
-                    user_parts.append(text)
-        return user_parts[-1] if user_parts else "\n".join(parts)
+            if c and c.strip():
+                parts.append(c.strip())
+        return "\n".join(parts)
 
     return ""
 

hy_memory/utils/pipeline_log_writer.py

@@ -1,7 +1,6 @@
 # -*- coding: utf-8 -*-
 """
-Pipeline Log Writer — 环节级 JSONL 日志（默认开启，MEMORY_PIPELINE_LOG_ENABLED=false 关闭；
-与 SQLite Trace 分离）。
+Pipeline Log Writer — 环节级 JSONL 日志（始终开启，与 SQLite Trace 分离）。
 
 目录: {log_dir}/{subdir}/{date}.log
 每行: request_id, namespace, user_id, agent_id, step, prompt, content, parsed,

hy_memory/utils/pipeline_observability.py

@@ -1,20 +1,16 @@
 # -*- coding: utf-8 -*-
 """
-Pipeline 可观测性：Log（文件 JSONL，默认开启，可关闭）与 Trace（SQLite pipeline_logs，可关闭）。
+Pipeline 可观测性：Log（文件 JSONL，始终开启）与 Trace（SQLite pipeline_logs，可关闭）。
 
 - Log：运维 tail/grep，每个环节即时一行，不依赖后续步骤成功与否。
 - Trace：Inspector / 调试，落库 pipeline_logs（需 MEMORY_CACHE_BACKEND=sqlite 等持久化后端）。
 
 环境变量：
-  MEMORY_PIPELINE_LOG_ENABLED    — Log 写 JSONL 文件，默认 true；false 时完全不写
   MEMORY_PIPELINE_TRACE_ENABLED  — Trace 落库，默认 true；OpenClaw C 端可设 false
   MEMORY_MEMORY_OPERATIONS_ENABLED — memory_operations 审计表落库，默认 false
   MEMORY_LOG_DIR                 — Log 目录（优先）
   MEMORY_TRACE_LOG_DIR           — Log 目录（兼容旧名）
 
-Log 与 Trace 都关闭时不包装 store_pipeline_log，而是换成立即返回 True 的
-空操作：热路径不做任何计时、脱敏或后台任务，也不写库。
-
 子目录（{log_dir}/{subdir}/{date}.log）由 PipelineLogWriter 从每条记录的
 user_id 前缀（第一个 "__" 左侧）切分；无前缀回落 "default"。该前缀是
 通用 namespace，可用于项目、部署或数据分桶。
@@ -98,16 +94,6 @@ def is_pipeline_trace_enabled() -> bool:
     )
 
 
-def is_pipeline_log_enabled() -> bool:
-    """是否把 pipeline step 写成 JSONL 文件（{log_dir}/<subdir>/<date>.log）。默认开启。"""
-    return os.getenv("MEMORY_PIPELINE_LOG_ENABLED", "true").strip().lower() in (
-        "true",
-        "1",
-        "yes",
-        "on",
-    )
-
-
 def is_memory_operations_enabled() -> bool:
     """是否将知识库变动写入 memory_operations 审计表。默认关闭（false）。"""
     return os.getenv("MEMORY_MEMORY_OPERATIONS_ENABLED", "false").lower() in (
@@ -139,7 +125,7 @@ def redact_content(value: str) -> str:
 
 def resolve_pipeline_log_dir() -> str:
     """
-    JSONL pipeline log 根目录（MEMORY_PIPELINE_LOG_ENABLED 开启时使用，有默认值）。
+    JSONL pipeline log 根目录（始终使用，有默认值）。
 
     优先级: MEMORY_LOG_DIR > MEMORY_TRACE_LOG_DIR > {MEMORY_DATA_DIR}/logs/pipeline
     """
@@ -242,7 +228,6 @@ def wrap_store_pipeline_log(
 ) -> Callable[..., Any]:
     """包装 cache.store_pipeline_log：计时同步、JSONL/DB 异步落盘，不堵主请求。
 
-    - log_writer 为 None 时不写 JSONL（MEMORY_PIPELINE_LOG_ENABLED=false）
     - step-to-step elapsed_ms / event_at_ms 在调用瞬间打点（与业务墙钟对齐）
     - event_at_ms：调用方传入非 0 值则直接复用（App 已在自己被调用的那一刻
       同步打点，比这里更接近真实事件时刻）；传 0 / 不传才用本地 time.time()
@@ -425,8 +410,7 @@ def wrap_store_pipeline_log(
         try:
             loop = asyncio.get_running_loop()
             # JSONL 用线程池，与 loop 无亲和，留在当前 loop。
-            if log_writer is not None:
-                _track_task(loop.create_task(_persist_jsonl()))
+            _track_task(loop.create_task(_persist_jsonl()))
             # DB trace 用 cache pool（可能 aiomysql，绑定 owner_loop）。若当前不在
             # owner_loop（如 search 走独立 loop），派发回 owner_loop 执行，避免跨 loop。
             if trace_enabled:
@@ -462,26 +446,25 @@ def wrap_store_pipeline_log(
                         )
         except RuntimeError:
             # 无 running loop（极少见）：退化为同步写，保证不丢日志
-            if log_writer is not None:
-                try:
-                    log_writer.write_step(
-                        request_id=request_id,
-                        user_id=user_id,
-                        agent_id=agent_id,
-                        session_id=session_id,
-                        step=step,
-                        prompt=prompt,
-                        response=response,
-                        parsed=parsed,
-                        memory_ids=mem_ids,
-                        elapsed_ms=step_elapsed_ms,
-                        prompt_tokens=prompt_tokens,
-                        completion_tokens=completion_tokens,
-                        total_tokens=total_tokens,
-                        event_at_ms=event_at_ms,
-                    )
-                except Exception:
-                    pass
+            try:
+                log_writer.write_step(
+                    request_id=request_id,
+                    user_id=user_id,
+                    agent_id=agent_id,
+                    session_id=session_id,
+                    step=step,
+                    prompt=prompt,
+                    response=response,
+                    parsed=parsed,
+                    memory_ids=mem_ids,
+                    elapsed_ms=step_elapsed_ms,
+                    prompt_tokens=prompt_tokens,
+                    completion_tokens=completion_tokens,
+                    total_tokens=total_tokens,
+                    event_at_ms=event_at_ms,
+                )
+            except Exception:
+                pass
             if trace_enabled:
                 try:
                     result = original_store(
@@ -513,11 +496,6 @@ def wrap_store_pipeline_log(
     return _store_pipeline_observability
 
 
-async def _noop_store_pipeline_log(*args: Any, **kwargs: Any) -> bool:
-    """Log 与 Trace 都关闭时的 store_pipeline_log：不计时、不写文件、不写库。"""
-    return True
-
-
 def install_pipeline_observability(
     cache: Any,
     *,
@@ -525,9 +503,6 @@ def install_pipeline_observability(
 ) -> None:
     """给 cache 安装 JSONL + Trace 包装（fire-and-forget）。
 
-    MEMORY_PIPELINE_LOG_ENABLED=false 时不写 JSONL；若 Trace 也关闭，
-    store_pipeline_log 被换成空操作（不包装、不写库）。
-
     在 cache 所属 loop（write loop / _LoopThread）上调用，本函数会捕获该 loop
     作为 owner_loop 传给包装器：search 走独立 loop 后，从 search loop 触发的 DB
     落库会被派发回这个 owner_loop，避免跨 loop 用 aiomysql 污染连接池。
@@ -539,31 +514,15 @@ def install_pipeline_observability(
     except RuntimeError:
         owner_loop = None
 
-    log_enabled = is_pipeline_log_enabled()
+    log_dir = resolve_pipeline_log_dir()
+    log_writer = PipelineLogWriter(log_dir)
     trace_enabled = is_pipeline_trace_enabled()
-    if not log_enabled and not trace_enabled:
-        logger.info(
-            f"[{log_label}] Pipeline log (JSONL) disabled ; pipeline trace (DB)=off ; "
-            f"store_pipeline_log=no-op"
-        )
-        cache.store_pipeline_log = _noop_store_pipeline_log
-        return
-
-    log_writer = None
-    if log_enabled:
-        log_dir = resolve_pipeline_log_dir()
-        log_writer = PipelineLogWriter(log_dir)
-        logger.info(
-            f"[{log_label}] Pipeline log (JSONL) enabled: {log_dir}/<subdir>/<date>.log "
-            f"(subdir from user_id prefix before '__', else default) ; "
-            f"pipeline trace (DB)={'on' if trace_enabled else 'off'} ; "
-            f"persist=async(fire-and-forget)"
-        )
-    else:
-        logger.info(
-            f"[{log_label}] Pipeline log (JSONL) disabled ; "
-            f"pipeline trace (DB)=on ; persist=async(fire-and-forget)"
-        )
+    logger.info(
+        f"[{log_label}] Pipeline log (JSONL) enabled: {log_dir}/<subdir>/<date>.log "
+        f"(subdir from user_id prefix before '__', else default) ; "
+        f"pipeline trace (DB)={'on' if trace_enabled else 'off'} ; "
+        f"persist=async(fire-and-forget)"
+    )
     cache.store_pipeline_log = wrap_store_pipeline_log(
         cache.store_pipeline_log,
         log_writer=log_writer,

hy_memory/utils/token_count.py

@@ -36,8 +36,7 @@ def count_tokens(text: str) -> int:
     enc = _get_encoder()
     if enc:
         try:
-            # Quoted control-token spellings are ordinary input text.
-            return len(enc.encode(text, disallowed_special=()))
+            return len(enc.encode(text))
         except Exception as e:
             logger.debug(f"[token_count] encode failed, char fallback: {e}")
     return max(1, len(text) // 4)

memhub/CONTRIBUTING.md

@@ -1,6 +1,6 @@
 # Contributing
 
-感谢你参与 MemHub。
+感谢你参与 One Memory。
 
 ## 开发环境
 
@@ -27,10 +27,3 @@ pnpm check
 
 涉及外部源码时，必须记录项目、固定版本或 commit、许可证、采用文件和修改说明。不得提交
 密钥、内部地址、真实对话、个人路径、模型权重或签名证书。
-
-## 界面翻译
-
-新增或修改界面语言时遵循
-[`docs/LOCALIZATION.md`](docs/LOCALIZATION.md)：使用稳定语义 key，保持所有
-locale 的 key 与占位符一致，不翻译用户内容、路径、标识符或外部错误正文。语言
-catalog 与无关产品行为应拆成不同 PR。

memhub/MEMORY.md

@@ -1,73 +1,97 @@
 # Hy Memory 使用与配置
 
-更新：2026-10-21
+更新：2026-10-12
 
-架构边界以 [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md) 为准。
+本文说明 MemHub 当前使用的 Hy Memory SDK、配置边界，以及直接使用 SDK 时如何
+write、search，并把搜索结果格式化为可交给模型的 memory text chunk。
 
----
-
-## Architecture Principles
-
-1. Memory 读写与存储 backend **只经 SDK**（config / env）。
-2. MemHub 运行时对 memory 的原子操作 **只经 SDK 公共 Client**；缺正常业务
-   接口先补 SDK。Runtime writers 停止后的 App 启动迁移可直接操作底层存储，
-   但不得把迁移专用方法加入公共 Client。
-3. MemHub **不存 memory 实体**；**可以存 `memory_id`** 做组织/回执。原文进入 **SDK raw**。
-4. SDK raw 只保留滚动三天；一条 raw 对应一个完整 turn，只含真人 user 与
-   assistant，tool 不持久化。提取后的高层 memory 不受该窗口影响。
-5. `source_raw_ids` 是 SDK 内部溯源关系，不是产品 Evidence 合同；记忆详情不提供
-   “原始依据”或按 raw ID 展开原文的入口。
-
-生产入口通过共享 Runtime 租约取得公开 `HyMemoryClient`；MemHub 只在调用前执行
-模型配置、密钥和 harness/model 门禁，不维护第二套 memory 正文权威。
-
-来源授权、模型授权和宿主召回授权仍是 MemHub 管理面门禁；memory
-数据平面的权威在 SDK。
+仓库内仍以 One Memory 命名的 Evidence、权限和 Governance 层属于 MemHub 的历史兼容
+模块；产品代码不应绕过这些层直接调用 SDK。本文中的
+原生 SDK 示例主要用于开发、调试和独立验证。
 
 ## 当前版本状态
 
-当前源码固定使用（以仓库 pin / lockfile 为准）：
+当前源码固定使用：
 
 ```text
 distribution: hy-memory
-version:      见 pyproject / lock（文档数字可能滞后）
+version:      2.0.3
 mode:         按运行时配置选择
 reader:       hybrid
 ```
 
+仓库 pin、lockfile 和运行时版本守卫均固定到公开的 `hy-memory==2.0.3`。
+MemHub 在本地 Runtime 内嵌入 SDK，但不绕过自身的来源授权、模型授权、Evidence、
+Governance 和撤权边界。
+
 ## MemHub 运行时边界
 
-MemHub 通过公开 `HyMemoryClient` 配置使用可复现的本地策略：
+MemHub 对 SDK 使用以下公开、可复现的本地策略：
 
-- vector / graph / cache / history / coding 等 **一律 SDK config/env**；
-- 模型与 embedding 来自版本化 Model Profile；密钥进安全存储；
-- MemHub 管理库可存 harness/model/队列状态与 **`memory_id` 引用**。
+- vector store 使用受管数据目录中的 Chroma；
+- graph store 使用受管数据目录中的 Kuzu；
+- cache 与 history 使用 SQLite；
+- reader 使用 `hybrid`；
+- reranker 默认关闭，不引入 Torch、Transformers 或额外模型；
+- 模型与远程 embedding 参数来自版本化 Model Profile；
+- API Key 进入系统安全存储，不写入仓库、安装包、日志或 HY metadata；
+- 服务端数据库、租户队列及宿主 shell 中的 ambient 凭据不会进入 SDK config。
 
-MemHub 不再通过 import-time 环境变量覆盖 SDK 的提取、reconcile、episode、
-intention、few-shot、summary 或去重策略。产品只配置模型/密钥/endpoint、本地
-backend 路径、公开 embedding service，以及每次公开 Client 调用的参数。
+发布包固定应用以下 SDK 行为配置：
 
-独立脚本直连 SDK 时须自配存储目录与模型端点。
+| 环境变量 | 值 |
+|---|---|
+| `MEMORY_MODE` | `ultra` |
+| `MEMORY_ENABLE_GRAPH` | `true` |
+| `MEMORY_GRAPH_RERANK_ENABLED` | `false` |
+| `MEMORY_GRAPH_TEMPORAL_SPINE` | `true` |
+| `MEMORY_TOPIC_SUMMARY_ENABLED` | `false` |
+| `MEMORY_EPISODE_SUMMARY_ENABLED` | `false` |
+| `MEMORY_EPISODE_RECALL_ENABLED` | `true` |
+| `MEMORY_DYNAMIC_EPISODE_ENABLED` | `true` |
+| `MEMORY_SESSION_EPISODE_ENABLED` | `false` |
+| `MEMORY_SESSION_EPISODE_CONTEXT_ENABLED` | `false` |
+| `MEMORY_EPISODE_CAPSULE_CONTEXT_ENABLED` | `true` |
+| `MEMORY_EPISODE_CAPSULE_QUERY_MIN` | `0.65` |
+| `MEMORY_EPISODE_CAPSULE_ASSIGNMENT_MIN` | `0.60` |
+| `MEMORY_EPISODE_CAPSULE_FIRST_RANK_MAX` | `3` |
+| `MEMORY_EPISODE_CAPSULE_MEMBER_LIMIT` | `3` |
+| `MEMORY_ENABLE_INTENTION` | `false` |
+| `MEMORY_ENABLE_QUERY_REWRITE` | `false` |
+| `MEMORY_FEW_SHOT_ENABLED` | `true` |
+| `MEMORY_HYBRID_V2_QUERY_EXPAND` | `1` |
+| `MEMORY_HYBRID_V2_GEO_INTENT_PRIOR` | `0.6` |
+| `MEMORY_HYBRID_V2_DIVERSITY` | `1` |
+| `MEMORY_HYBRID_V2_TEMPORAL_ADMIT_PRIOR` | `0.55` |
+| `MEMORY_HYBRID_V2_TEMPORAL_BOOST` | `0.18` |
+| `MEMORY_CROSS_DOMAIN_CON_THRESHOLD` | `0.5` |
+| `MEMORY_READER_ENABLE_SUMMARY` | `false` |
+| `MEMORY_SUMMARY_ENABLED_IN_SYS2` | `false` |
+| `MEMORY_LOCAL_RERANK_ENABLED` | `false` |
+| `RECONCILE_ENABLED` | `true` |
+| `HY_MEMORY_READER` | `hybrid` |
+
+这些默认值集中在
+`apps/core/src/one_memory/hy_runtime_config.py`，并由发布测试和 lockfile 共同约束。
+独立脚本若绕过 MemHub 直接导入 SDK，应自行显式配置存储目录和模型端点。
 
 ## 原生 SDK 初始化
 
-下面是独立调试示例。
-
-产品代码经 `hy_sdk_runtime.SdkClientHandle` 获取已配置的公开 client；memory I/O
-由 SDK 完成。
+下面是独立调试示例。产品代码应使用 One Memory 的 `HyMemoryBridge`，因为它额外提供来源
+授权、模型授权、Evidence 绑定、写后核验、Governance 和撤权保护。
 
 ```python
 from hy_memory import HyMemoryClient, MemoryConfig
 
 config = MemoryConfig.from_env()
 
-# 本地优先示例；实际目录应由调用方传入。
+# 本地优先示例；实际目录应由调用方传入，不能依赖 ~/.hy_memory 默认值。
 config.vector_store.provider = "chroma"
-config.vector_store.persist_directory = "/path/to/one-memory/hy-memory/vector"
+config.vector_store.persist_directory = "/path/to/one-memory/hy-memory/governed-v2/vector"
 config.graph_store.provider = "kuzu"
-config.graph_store.db_path = "/path/to/one-memory/hy-memory/graph"
+config.graph_store.db_path = "/path/to/one-memory/hy-memory/governed-v2/graph"
 config.cache.backend = "sqlite"
-config.cache.db_path = "/path/to/one-memory/hy-memory/cache.sqlite3"
+config.cache.db_path = "/path/to/one-memory/hy-memory/governed-v2/cache.sqlite3"
 
 config.llm.provider = "openai"
 config.llm.model = "your-model"
@@ -83,11 +107,12 @@ config.embedder.embedding_dims = 1024
 client = HyMemoryClient(config=config, mode="ultra")
 ```
 
-`embedding_dims` 必须与模型输出及已有向量/图存储一致。
+`embedding_dims` 必须与模型实际输出宽度以及已有向量/图存储一致。更换 embedding 模型、
+端点或维度不能直接复用旧 collection；One Memory 会检测图宽度不一致并拒绝静默重建。
 
 ## Write：写入对话
 
-推荐把一段连续对话作为 OpenAI messages 写入；含原文时由 SDK 接管 raw：
+推荐把一段连续对话作为 OpenAI messages 写入：
 
 ```python
 from datetime import UTC, datetime
@@ -106,54 +131,47 @@ result = client.add(
     request_id=str(uuid4()),
     metadata={
         "source_id": "cursor",
+        "evidence_ids": ["evidence-001", "evidence-002"],
         "workspace_ids": ["workspace-abc"],
         "input_kind": "raw_conversation",
     },
 )
 ```
 
+参数规则：
+
 | 参数 | 填法 | 约束 |
 | --- | --- | --- |
-| `data` | 字符串或 `[{role, content}]` | 对话优先 messages；不混入密钥与隐藏系统提示 |
-| `user_id` / `agent_id` / `session_id` | 隔离与会话键 | 产品侧授权决定合法 scope |
-| `memory_at` | 有时区 datetime | 历史导入用原始发生时间 |
-| `scene` | `chat` / `working` | 明确传入 |
-| `request_id` | 每次写入唯一 | 幂等与追踪 |
-| `metadata` / `meta` | 来源与透传 | 不放秘密 |
+| `data` | 字符串或 `[{role, content}]` | 对话优先用 messages；不混入 tool 参数、reasoning、密钥和隐藏系统提示 |
+| `user_id` | 稳定用户 ID | 一级隔离键；不能为空 |
+| `agent_id` | 记忆 scope | One Memory 中不是宿主 App 名的简单替代；跨 App scope 由授权和路由决定 |
+| `session_id` | 稳定会话 ID | 同一会话增量写入时保持一致 |
+| `memory_at` | 有时区的 `datetime` | 历史导入必须传原始发生时间，不能用导入时间替代 |
+| `scene` | `"chat"` 或 `"working"` | 普通对话明确传 `chat`；代码/tool 会话才用 `working` |
+| `request_id` | 每次写入唯一 ID | 用于幂等、追踪和写后核验 |
+| `metadata` | 来源和 Evidence 引用 | 不放秘密；One Memory 至少保存 source/evidence/workspace/input kind |
+| `meta` | 业务透传数据 | 不参与 embedding 和过滤；只放可安全返回的数据 |
+| `embed_override` | 临时 embedding 端点 | 只能换 endpoint/key/header/timeout；模型和维度不能改变 |
 
-MemHub Runtime 对应用和 CLI 暴露等价的本机 HTTP 合同：
-
-```text
-POST /api/v2/memory-writes
-GET  /api/v2/user-profile
-
-memhub write submit --messages-file messages.json --session <id>
-memhub profile
-```
-
-`messages.json` 是 OpenAI 文本 messages 数组，当前接受 `user`、
-`assistant`、`tool`；系统/开发者隐藏提示不得作为记忆输入。Core 将输入冻结进
-`memory_write_jobs`，worker 对 SDK 执行一次 `add()`，成功后清除队列正文。
-`user-profile` / `memhub profile` 调用 SDK `get_user_profile()`，返回组装后的
-用户长期画像，不通过普通 Search 拼装。
-
-返回值：
+返回值至少检查：
 
 ```python
 if result.get("success") is not True:
     raise RuntimeError("HY write failed")
 
-memory_ids = list(result.get("memory_ids") or [])
+memory_ids = result.get("memory_ids") or []
 if result.get("memory_id"):
     memory_ids.append(result["memory_id"])
-# 需要组织或回执时，MemHub 只持久化这些 memory_id。
 ```
 
-以 SDK 合同为准做成功判定；需要写后核验时使用 SDK `get` 回读。缺少所需
-核验能力时扩展 SDK API，不在 MemHub 新建镜像台账。
+不要只相信 `success=True`。One Memory 还会按返回 ID `get()` 回读、核对 request/source/
+Evidence 支持关系，并在 Governance 层记录版本。生产路径不能用直接 `client.add()` 代替这些
+检查。
 
 ### 写入已抽取的记忆
 
+只有输入本身就是已有记忆内容、且原始对话不可用时才使用：
+
 ```python
 result = client.add_extracted(
     ["用户长期偏好简洁、直接的回答。"],
@@ -164,30 +182,18 @@ result = client.add_extracted(
     request_id=str(uuid4()),
     metadata={
         "source_id": "memory-export",
+        "evidence_ids": ["evidence-003"],
         "input_kind": "memory_content_without_raw",
     },
 )
 ```
 
-该入口仍走 SDK reconcile/持久化；MemHub 只做管理面门禁与可选
-`memory_id` 记录。
-
-应用的「添加记忆」、MCP `MemHub_write`（经 broker `POST /memories` 以本机可信身份转发）
-共用同一个本机 HTTP 合同，直接新增一条记忆：
-
-```text
-POST /api/v2/memories                         {request_id, text, scope: "all-apps"}
-GET  /api/v2/memories/additions/{request_id}  # 该次新增的状态
-```
-
-两者返回同一回执（`evidence_id`、`text`、`scope`、`created_at`、`state`、`task_id`、
-`memory_ids`、`error`）。同一 `request_id` 重放返回原回执；内容不同返回 409
-`memory_add_conflict`，未知 `request_id` 返回 404 `memory_add_not_found`。新增走持久
-写入队列的优先通道，最终调用 `add_extracted` + reconcile。带外部读取信封的请求
-一律拒绝（403 `external_endpoint_denied`）。
+它跳过 Extractor，但不能跳过 HY reconcile、持久化、One Memory Evidence 绑定和 Governance。
 
 ## Search：搜索记忆
 
+普通 chat 搜索：
+
 ```python
 result = client.search(
     "用户偏好怎样的回答风格？",
@@ -204,47 +210,117 @@ result = client.search(
 )
 ```
 
-参数表与返回结构同前（chat 三 channel / working 的 facts·experiences）；调用方按 `scene` 解析，无法识别则报错。
+参数规则：
+
+| 参数 | 填法 | 说明 |
+| --- | --- | --- |
+| `query` | 当前问题 | 与 `queries` 二选一 |
+| `queries` | 多轮查询文本 | 最后一条是目标；只有需要 SDK 判断上下文时使用 |
+| `user_ids` | 获授权用户列表 | 必填且不能空；不要用空列表扩大范围 |
+| `agent_ids` | 获授权 scope 列表 | 空列表在 SDK 中表示所有 agent，产品代码必须先完成授权判断 |
+| `session_ids` | 可选会话范围 | 多 agent 与多 session 不能同时使用 |
+| `limit` | normal top-k | 默认 10；注入模型前还要受字符预算限制 |
+| `min_score` | normal 阈值 | One Memory 当前内部语义检索使用 0.25 |
+| `profile_min_score` | profile 阈值 | One Memory 当前使用 0.25 |
+| `profile_limit` | profile 数量 | 通常与 limit 一致 |
+| `intention_limit` | intention 数量 | 当前配置关闭 intention，传 0 |
+| `created_after` | Unix 秒 | 可选时间下界 |
+| `scene` | `chat` / `working` | 明确传入可避免额外场景判断模型调用 |
+| `reader` | `hybrid` | One Memory 固定使用该 reader |
+| `workspace_id` / `branch` | working scope | 仅 coding/working 路径使用 |
+| `layers` | 指定层级列表 | 在召回阶段过滤，避免无关层占用 limit |
+
+chat 返回结构：
+
+```python
+{
+    "request_id": "...",
+    "memories": {
+        "profile": [...],
+        "proactive": [...],
+        "normal": [...],
+    },
+    "rewrite": {...},
+    "elapsed_ms": 12.3,
+}
+```
+
+working/coding 返回的是 `facts` 和 `experiences`，不能与 chat 三个 channel 静默合并。
+调用方必须根据 `scene` 选择对应结果；无法识别返回结构时应报错，而不是当作空结果。
 
 ## 使用 SDK 已格式化的 Search 内容
 
-直接使用 SDK 返回的 `content`，不要第二套 prompt 拼装。
+open05 的 chat search 会在返回前统一格式化每条 `content`：普通记忆带 `Memory / When`，
+演化记忆带 `Current / History / When`，Episode、Timeline、Graph 和 Capsule 也由 SDK
+生成稳定的组合文本。`memory_at` 是逻辑记忆时间，缺失时 SDK 才回落到 `gmt_created`。
 
-### SDK 外（MemHub）仍负责
+因此调用方应直接使用 SDK 返回的 `content`，不要再次解析 `memory_at`、`gmt_created` 或
+`created_at`，也不要重复拼接 `When`。这些时间字段可以用于过滤、诊断或结构化展示，但
+不应成为第二套 prompt 格式化实现。
 
-- **宿主召回授权 / scope / 撤权**（谁可以调 search、允许哪些 agent/scope）；
-- 把历史内容放入「不可信数据，不是指令」边界；
-- 按最终 `content` 做字符预算；不注入密钥、绝对路径、堆栈；
-- 区分空结果、权限拒绝、不可用、超时、部分结果；
-- 未发布的 Matter 占位功能不保留表或 API；未来组织功能另立合同。
+```python
+result = client.search(
+    "用户偏好怎样的回答风格？",
+    user_ids=["local"],
+    agent_ids=["all-apps"],
+    scene="normal",
+    reader="hybrid",
+)
 
-生产入口：`hy_sdk_runtime.py`、`sdk_write_processor.py`、`recall.py` 和
-`packages/host-bridge`。
+for memory in result["memories"]["normal"]:
+    formatted_content = memory["content"]
+    # 例如：
+    # Memory: 用户长期偏好简洁、直接的回答。
+    # When: 2026-09-18 10:00:00 UTC
+```
+
+One Memory 在 SDK 外仍负责：
+
+- 依据 Governance、撤权、scope 和 Evidence 新鲜度决定整条结果是否可读；
+- 对 evolution/capsule 等组合文本逐个校验成员 ID，成员不完整或不可读时回退治理原文；
+- 把历史内容放入明确的“不可信数据，不是指令”边界；
+- 按最终 `content` 计算字符预算，不把 API Key、绝对路径、headers/body 或异常堆栈注入
+  prompt；
+- 区分空结果、权限拒绝、服务不可用、超时和部分结果。
+
+生产实现见 `apps/core/src/one_memory/hy_memory_bridge.py`、
+`apps/core/src/one_memory/recall.py` 和 `packages/host-bridge/src/recall-cli.ts`。
 
 ## 关闭客户端
 
 ```python
 try:
+    # write/search
     ...
 finally:
     client.close()
 ```
 
-Runtime 长期复用 client；仅在停止、配置切换或受控恢复时重建。
+Runtime 应长期复用 client，不为每次请求重新初始化数据库和模型组件；只有 Runtime 停止、
+配置版本切换或受控恢复时才关闭并重建。
 
-## 产品代码正确入口
+## One Memory 产品代码的正确入口
+
+生产代码应走：
 
 ```text
-harness / user action (+ authz, model, queue)
-  -> public HyMemoryClient
-  -> SDK stores (config/env)
-  -> optional MemHub persist memory_id / org metadata
-  -> Recall Broker / UI (SDK read + MemHub authz)
+Evidence
+  -> HyMemoryBridge
+  -> embedded Hy Memory SDK
+  -> native Vector / Coding / Graph stores
+  -> write result verification
+  -> Governance
+  -> Recall Broker / UI
 ```
 
-不要在业务模块里私建绕过管理面门禁的 client。版本、纠正和删除语义以 SDK
-合同为准；MemHub 组织层只引用 `memory_id`。
+不要在新业务模块里直接创建 `HyMemoryClient`，否则会绕过：
 
-Hy Memory SDK 是 MemHub 内置可信引擎，管理本机 Hy Memory 数据。  
-来源授权决定哪些宿主数据可进入写入路径；宿主 Recall Grant 决定外部应用可读范围。  
-这两类边界 **不** 意味着 MemHub 再存一套 memory 实体。
+- 来源读取授权；
+- 共享 Runtime、模型配置、API Key 安全存储与请求预算；
+- Evidence 引用与作者归属；
+- 写后回读验证；
+- Governance 状态、版本、更正和删除级联。
+
+Hy Memory SDK 是 MemHub 的内置可信组件，可自由访问和管理本机的全部
+Hy Memory 数据。来源授权仍决定哪些宿主数据可以进入本机；宿主 Recall Grant
+仍决定哪些外部 AI 应用可以读取治理后的记忆。这两类边界不限制内置 SDK 的本地 CRUD。

memhub/PRIVACY.md

@@ -29,12 +29,10 @@ prompt/response、密钥、访问令牌或完整本地路径。结构化日志
 文件。详细合同见
 [`docs/contracts/diagnostic-logging.md`](docs/contracts/diagnostic-logging.md)。
 
-HY pipeline 日志与 trace 在任何级别下都关闭。HY SDK 的文本日志只写入
-`hy-memory/governed-v2/logs/hy_memory.log`，其中的 WARNING 及以上同时写入 `core.log`；
-SDK 不在 INFO 及以上级别记录对话或记忆正文。用户显式把诊断级别切换为 `debug` 时，Core 将
-`MEMORY_LOG_LLM_CONTENT` 设为 `true`。该模式会把完整模型 prompt/response 写入
-`hy_memory.log` 的 DEBUG 行，其中可能包含获授权的对话正文和模型输出；它只应用于有意识的
-故障排查，不应长期开启，也不应在未经检查和脱敏时分享相关日志。切回 `info` 会停止后续正文记录，但不会
+用户显式把诊断级别切换为 `debug` 时，Core 会启用 HY pipeline trace，并将
+`MEMORY_LOG_LLM_CONTENT` 设为 `true`。该模式会把完整模型 prompt/response 写入本地调试
+日志，其中可能包含获授权的对话正文和模型输出；它只应用于有意识的故障排查，不应长期
+开启，也不应在未经检查和脱敏时分享相关日志。切回 `info` 会停止后续正文记录，但不会
 自动删除此前已写入的调试文件。
 
 具体行为以当前源码、网络请求实现和发布说明为准。发现实现与本说明不一致时，请按

memhub/README.md

@@ -18,13 +18,13 @@ If you run into a problem, please open an Issue with the version, platform,repro
 
 ## 发行与平台合同
 
-源码当前固定使用公开 PyPI 正式版 `hy-memory==2.0.8`。MemHub 源码版本为 `1.0.5`
-（build 36），GitHub 仓库为
+公共 Python SDK 为 `hy-memory==2.0.4`。MemHub 源码版本为 `1.0.4`
+（build 13），GitHub 仓库为
 [`Tencent-Hunyuan/Hy-Memory`](https://github.com/Tencent-Hunyuan/Hy-Memory)，npm 包名为
 `memhub-cli`。当前代码架构见
 [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md)。
 
-`v1.0.5` 的发行目标是 Linux x64/arm64 Runtime 与 macOS arm64 App 和 Runtime。
+`v1.0.4` 的发行目标是 Linux x64/arm64 Runtime 与 macOS arm64/x64 App 和 Runtime。
 Linux 制品由 GitHub Actions 在原生架构 runner 上构建并完成生命周期验收；macOS
 制品由发行流水线完成 Developer ID 签名、公证和验收后手动上传。Windows 不支持。
 只有同时出现在 GitHub Release 与 `release-manifest.json` 中、且通过公开校验的制品才属于
@@ -37,27 +37,23 @@ Linux 制品由 GitHub Actions 在原生架构 runner 上构建并完成生命
 ## 核心原则
 
 - 一次安装、一个 Runtime、一份数据、多种客户端。
-- Hy Memory SDK 是 memory/raw/vector/graph/coding 数据面的唯一权威；Python Core
-  管理授权、模型、异步队列和 Runtime 状态。
+- Python Core 是唯一记忆数据面和唯一业务数据库写入者。
 - 来源读取、模型处理和宿主读取是相互独立的授权边界。
-- 正式写链路为 `memory_write_jobs -> SDK add() -> raw/memory ID receipt`。
+- 正式记忆链路保持 `Evidence -> Hy Memory -> Governance -> Matters/Wiki`。
 - 产品不包含屏幕、Accessibility / AXTree、OCR、键鼠、剪贴板或后台录音采集。
 
 ## 仓库结构
 
-- `apps/core`：Python / FastAPI Kernel，负责授权、模型、队列、SDK Runtime 边界与 API。
+- `apps/core`：Python / FastAPI Kernel，负责 Evidence、Hy Memory、治理、检索与 API。
 - `apps/cli`：安装、控制和诊断共享 Runtime 的 `one-memory` CLI。
 - `apps/web`：React / TypeScript 管理界面。
 - `apps/desktop`：Electron 桌面壳与图形安装入口。
 - `packages/contracts`：公共 API 类型。
-- `packages/i18n`：Web 与 Electron 共用的界面语言合同和 catalog。
 - `packages/host-bridge`：AI App 的 Skill、Hook、插件和 MCP 接入。
 - `packages/runtime-control`：Core、Host Gateway 和 Runtime 生命周期控制。
 
 架构详情见 [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md) 和
 [`docs/contracts/runtime-unification.md`](docs/contracts/runtime-unification.md)。
-界面语言架构与社区翻译规则见
-[`docs/LOCALIZATION.md`](docs/LOCALIZATION.md)。
 产品、测试和一线支持排查导入与记忆沉淀时，使用
 [`docs/PRODUCT_LOG_TROUBLESHOOTING.md`](docs/PRODUCT_LOG_TROUBLESHOOTING.md)。
 
@@ -109,16 +105,15 @@ Node、Host Bridge 或模型。用户显式执行 `memhub install` 后，CLI 才
 Python Core 和运行所需的 Python 依赖位于 MemHub 受管 Runtime，不写入系统 Python。
 MemHub 的 SQLite 数据默认位于 `~/.one-memory`，不在 npm 包或 Runtime 版本目录中。
 `npm uninstall` 只移除 npm CLI；`memhub uninstall` 移除服务、受管 Runtime 和 CLI 链接，
-默认保留 Memory。只有独立的 `memhub delete-data` 在 Runtime 停止、显式加 `--yes` 并用
-`--confirm <数据目录>` 再写一遍同一个目录后才会删除数据（不加参数只预览要删除的目录）。`memhub stop` 停止受管服务时也会关闭
-登录自动启动，再次 `memhub start` 会恢复。
+默认保留 Memory。只有独立的 `memhub delete-data` 在 Runtime 停止且二次确认精确路径后
+才会删除数据。
 
 当前平台能力和安装边界以源码、CI 与发布说明为准。未完成真机验收的平台不会仅凭跨平台
 测试宣称可用。
 
 ## Hy Memory
 
-SDK 依赖固定为公开 PyPI 正式版 `hy-memory==2.0.8`。SDK 配置、权限边界及 search
+当前开发依赖固定为公开 PyPI 包 `hy-memory==2.0.4`。SDK 配置、权限边界及 search
 返回格式见 [`MEMORY.md`](MEMORY.md)。HY search 返回的 `content` 已包含 SDK 统一生成的
 逻辑时间和演化上下文；调用方不应再次转换时间戳或重复拼接 `When`。
 

memhub/SBOM.spdx.json

@@ -3,9 +3,9 @@
   "dataLicense": "CC0-1.0",
   "SPDXID": "SPDXRef-DOCUMENT",
   "name": "one-memory",
-  "documentNamespace": "https://one-memory.local/spdx/2026-10-22T13:18:16Z",
+  "documentNamespace": "https://one-memory.local/spdx/2026-10-17T13:52:48Z",
   "creationInfo": {
-    "created": "2026-10-22T13:18:16Z",
+    "created": "2026-10-17T13:52:48Z",
     "creators": [
       "Tool: one-memory-generate-sbom"
     ]
@@ -88,23 +88,6 @@
         }
       ]
     },
-    {
-      "SPDXID": "SPDXRef-Package-npm-i18next",
-      "name": "i18next",
-      "versionInfo": "25.10.10",
-      "downloadLocation": "NOASSERTION",
-      "filesAnalyzed": false,
-      "licenseConcluded": "NOASSERTION",
-      "licenseDeclared": "NOASSERTION",
-      "copyrightText": "NOASSERTION",
-      "externalRefs": [
-        {
-          "referenceCategory": "PACKAGE-MANAGER",
-          "referenceType": "purl",
-          "referenceLocator": "pkg:npm/i18next@25.10.10"
-        }
-      ]
-    },
     {
       "SPDXID": "SPDXRef-Package-npm-lucide-react",
       "name": "lucide-react",
@@ -2352,7 +2335,7 @@
     {
       "SPDXID": "SPDXRef-Package-hy-memory",
       "name": "hy-memory",
-      "versionInfo": "2.0.8",
+      "versionInfo": "2.0.4",
       "downloadLocation": "NOASSERTION",
       "filesAnalyzed": false,
       "licenseConcluded": "Apache-2.0",
@@ -2397,11 +2380,6 @@
       "relationshipType": "DEPENDS_ON",
       "relatedSpdxElement": "SPDXRef-Package-npm-https-proxy-agent"
     },
-    {
-      "spdxElementId": "SPDXRef-Package-one-memory",
-      "relationshipType": "DEPENDS_ON",
-      "relatedSpdxElement": "SPDXRef-Package-npm-i18next"
-    },
     {
       "spdxElementId": "SPDXRef-Package-one-memory",
       "relationshipType": "DEPENDS_ON",

memhub/THIRD_PARTY_NOTICES.md

@@ -2,14 +2,14 @@
 
 MemHub itself is licensed under Apache-2.0 (see `LICENSE`).
 It bundles the runtime dependencies listed below.
-Generated from the installed dependency tree on 2026-10-22T13:18:16Z
+Generated from the installed dependency tree on 2026-10-17T13:52:48Z
 by `python3 scripts/generate_sbom.py`. Do not edit by hand.
 
 Per-package license texts are not reproduced here yet; the license
 column is filled in as part of release review, and the SBOM records
 `NOASSERTION` until then rather than guessing.
 
-## hy-memory 2.0.8
+## hy-memory 2.0.4
 
 License: Apache-2.0
 
@@ -112,13 +112,12 @@ Adaptation boundary:
 
 No Memmy brand, icon, font or mascot assets are distributed.
 
-## JavaScript (npm) — 11 packages
+## JavaScript (npm) — 10 packages
 
 - @tanstack/react-query 5.103.2
 - axios 1.20.0
 - fflate 0.8.3
 - https-proxy-agent 7.0.0
-- i18next 25.10.10
 - lucide-react 1.43.0
 - proxy-from-env 2.1.0
 - react 19.2.8

memhub/apps/cli/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@one-memory/cli",
-  "version": "1.0.5",
+  "version": "1.0.4",
   "description": "MemHub bootstrap CLI for installing and managing the local-first shared memory runtime",
   "license": "Apache-2.0",
   "repository": {

memhub/apps/cli/scripts/real-read-probe.mjs

@@ -21,21 +21,18 @@ const TOKEN = "probe-token-not-a-real-credential";
 
 const MEMORY = {
   memory_id: "probe-1",
-  content: "部署脚本要先跑 verify_merge_plan。",
-  layer: "l2_fact",
-  status: "active",
-  is_latest: true,
-  supersedes: [],
-  superseded_by: [],
-  tags: [],
-  owner: null,
-  source_raw_ids: ["probe-raw-1"],
   user_id: "local",
-  agent_id: "codex",
-  session_id: "probe-session",
-  source: "codex",
-  memory_at: 1758240000,
-  gmt_created: 1758240000,
+  kind: "chat",
+  status: "confirmed",
+  content: "部署脚本要先跑 verify_merge_plan。",
+  scopes: ["all-apps"],
+  evidence_ids: ["probe-e1"],
+  origin: "extracted",
+  tags: [],
+  revision: 2,
+  created_at: "2026-09-19T00:00:00Z",
+  updated_at: "2026-09-19T00:00:00Z",
+  deleted_at: null,
 };
 
 const ROUTES = new Map([
@@ -127,6 +124,26 @@ const ROUTES = new Map([
       },
     ],
   ],
+  [
+    "/api/v1/memory-tasks",
+    [
+      {
+        task_id: "probe-task",
+        request_id: "probe-request",
+        user_id: "local",
+        kind: "extract",
+        input_ref: "probe",
+        status: "waiting_for_model",
+        profile_id: "probe-profile",
+        profile_revision: 1,
+        profile_snapshot: {},
+        attempts: 0,
+        last_error_code: "model_missing",
+        created_at: "2026-09-19T00:00:00Z",
+        updated_at: "2026-09-19T00:00:01Z",
+      },
+    ],
+  ],
   [
     "/api/v1/model-profiles",
     [
@@ -142,20 +159,28 @@ const ROUTES = new Map([
       },
     ],
   ],
+  ["/api/v1/home-summary", { memory_count: 1, latest: null, observed_at: "T" }],
   [
-    "/api/v2/home-summary",
+    "/api/v1/memory-library",
+    { total: 1, offset: 0, limit: 100, items: [MEMORY] },
+  ],
+  [
+    "/api/v1/memories/probe-1",
     {
-      schema_version: 2,
-      memory_count: 1,
-      latest: MEMORY,
-      observed_at: "2026-09-19T00:00:01Z",
+      memory: MEMORY,
+      evidence: [
+        {
+          evidence_id: "probe-e1",
+          available: true,
+          source_id: "codex",
+          written_by: "user",
+          created_at: "2026-09-19T00:00:00Z",
+          verbatim: "部署前先跑 verify_merge_plan，别靠读 diff 猜冲突。",
+        },
+      ],
+      history: [{ memory_id: "probe-1", revision: 2, action: "confirm" }],
     },
   ],
-  [
-    "/api/v2/memory-library",
-    { memories: [MEMORY], total: 1, offset: 0, limit: 100 },
-  ],
-  ["/api/v2/memories/probe-1", MEMORY],
 ]);
 
 const seen = [];

memhub/apps/cli/scripts/verify-package-matrix.mjs

@@ -29,8 +29,11 @@ const REQUIRED_COMMAND_SURFACE = [
   "sources",
   "sync",
   "memories",
-  "profile",
-  "graph-width",
+  "calls",
+  "import-file",
+  "notes",
+  "extraction",
+  "graph",
   "models",
   "host",
   "doctor",
@@ -48,17 +51,20 @@ const REQUIRED_COMMAND_SURFACE = [
   "uninstall",
   "delete-data",
   "recall",
+  "setup",
   "scan",
   "progress",
   "jobs",
-  "scan-roots",
+  "processing",
+  "path",
   "adapter",
   "write",
+  "task",
   "serve",
 ];
 
 const REQUIRED_MARKERS = [
-  "backup_restore_confirmation_mismatch",
+  "backup_restore_confirmation_required",
   "backup_restore_runtime_state_unknown",
   "backup_restore_maintenance_identity_invalid",
   "runtime_service_activation_unverified",
@@ -75,18 +81,17 @@ const REQUIRED_MARKERS = [
  * exact literal the catalog usage string contains.
  */
 const REQUIRED_SUBCOMMANDS = [
-  { command: "memories", marker: "memhub memories add" },
-  { command: "memories", marker: "memhub memories add-status" },
-  { command: "memories", marker: "memhub memories update" },
-  { command: "memories", marker: "memhub memories delete" },
-  { command: "write", marker: "memhub write submit" },
-  { command: "write", marker: "memhub write status" },
-  { command: "graph-width", marker: "memhub graph-width --decision" },
-  { command: "models", marker: "memhub models add" },
-  { command: "models", marker: "memhub models test" },
+  { command: "calls", marker: "memhub calls clear" },
+  { command: "import-file", marker: "memhub import-file upload" },
+  { command: "import-file", marker: "memhub import-file commit" },
+  { command: "import-file", marker: "memhub import-file discard" },
+  { command: "notes", marker: "memhub notes add" },
+  { command: "notes", marker: "memhub notes process" },
+  { command: "extraction", marker: "memhub extraction set" },
+  { command: "graph", marker: "memhub graph width" },
   { command: "models", marker: "memhub models edit" },
   { command: "models", marker: "memhub models activate" },
-  { command: "sources", marker: "memhub sources connect" },
+  { command: "processing", marker: "memhub processing extract" },
   { command: "jobs", marker: "memhub jobs start" },
   { command: "jobs", marker: "memhub jobs <pause|resume|cancel>" },
 ];
@@ -98,30 +103,83 @@ const REQUIRED_SUBCOMMANDS = [
  * counterexamples on the packaged Runtime") had no machine-checkable probe.
  * These run without `--lifecycle`, so they are safe against any package.
  */
-const PROFILE_ID = "44444444-4444-4444-8444-444444444444";
 const STOPPED_DESTRUCTIVE_PROBES = [
-  { name: "memories_add", args: ["memories", "add", "synthetic memory"] },
   {
-    name: "memories_delete_apply",
-    args: ["memories", "delete", "m-1", "--yes"],
+    name: "calls_clear_preview",
+    args: ["calls", "clear", "--event", "11111111-1111-4111-8111-111111111111"],
+  },
+  {
+    name: "calls_clear_apply",
+    args: [
+      "calls",
+      "clear",
+      "--event",
+      "11111111-1111-4111-8111-111111111111",
+      "--confirm",
+    ],
+  },
+  {
+    name: "calls_clear_all_apply",
+    args: ["calls", "clear", "--all", "--confirm"],
+  },
+  {
+    name: "import_file_commit_apply",
+    args: [
+      "import-file",
+      "commit",
+      "22222222-2222-4222-8222-222222222222",
+      "--confirm",
+    ],
+  },
+  {
+    name: "import_file_discard_apply",
+    args: [
+      "import-file",
+      "discard",
+      "22222222-2222-4222-8222-222222222222",
+      "--confirm",
+    ],
+  },
+  {
+    name: "notes_process_apply",
+    args: [
+      "notes",
+      "process",
+      "33333333-3333-4333-8333-333333333333",
+      "--confirm",
+    ],
+  },
+  {
+    name: "extraction_set_apply",
+    args: ["extraction", "set", "--window", "6m", "--confirm"],
   },
   {
     name: "graph_width_apply",
-    args: ["graph-width", "--decision", "keep_existing"],
+    args: ["graph", "width", "--decision", "keep_existing", "--confirm"],
   },
   {
-    name: "graph_width_rebuild_apply",
-    args: ["graph-width", "--decision", "rebuild_with_new", "--yes"],
-  },
-  { name: "models_activate_apply", args: ["models", "activate", PROFILE_ID] },
-  { name: "models_test", args: ["models", "test", PROFILE_ID] },
-  {
-    name: "models_remove_apply",
-    args: ["models", "remove", PROFILE_ID, "--yes"],
+    name: "processing_extract_apply",
+    args: ["processing", "extract", "--confirm"],
   },
   {
-    name: "sources_connect_import",
-    args: ["sources", "connect", "codex", "--import"],
+    name: "models_activate_apply",
+    args: [
+      "models",
+      "activate",
+      "44444444-4444-4444-8444-444444444444",
+      "--confirm",
+    ],
+  },
+  {
+    name: "models_edit_apply",
+    args: [
+      "models",
+      "edit",
+      "44444444-4444-4444-8444-444444444444",
+      "--config-file",
+      "/nonexistent/patch.json",
+      "--confirm",
+    ],
   },
 ];
 

memhub/apps/cli/src/batch-import-flow.test.ts

@@ -119,7 +119,6 @@ describe("A19 batch execution", () => {
       readerFor([]),
       operations,
       planned.notFound,
-      { confirmOverrides: false },
     );
     // Exactly one request for two sources — the batch endpoint, per contract.
     expect(post).toHaveBeenCalledTimes(1);
@@ -166,7 +165,6 @@ describe("A19 batch execution", () => {
       readerFor([]),
       operations,
       planned.notFound,
-      { confirmOverrides: false },
     );
     expect(document.state).toBe("partial");
     const byId = Object.fromEntries(
@@ -208,7 +206,6 @@ describe("A19 batch execution", () => {
       readerFor([]),
       operations,
       [],
-      { confirmOverrides: false },
     );
     expect(document.sources.every((row) => row.status === "failed")).toBe(true);
     expect(
@@ -252,7 +249,6 @@ describe("A19 batch execution", () => {
       readerFor([]),
       operations,
       [],
-      { confirmOverrides: false },
     );
     const busy = document.sources.find((row) => row.source_id === "cursor");
     expect(document.state).toBe("partial");
@@ -292,7 +288,6 @@ describe("A19 batch execution", () => {
       readerFor([]),
       operations,
       planned.notFound,
-      { confirmOverrides: false },
     );
     const notFoundRow = document.sources.find(
       (row) => row.source_id === "cursor",
@@ -301,82 +296,3 @@ describe("A19 batch execution", () => {
     expect(document.not_found_source_ids).toContain("cursor");
   });
 });
-
-describe("environment-override sources need --confirm-overrides", () => {
-  it("leaves them out and names them unless confirmed", async () => {
-    const planned = await planBatchImport(
-      readerFor([
-        found("codex"),
-        found("dsh", {
-          candidate_kind: "environment_override",
-          requires_override_confirmation: true,
-        }),
-      ]),
-    );
-    if (planned.state !== "preview") throw new Error("expected preview");
-    const post = vi.fn(
-      async (_path: string, body: Record<string, unknown>) => ({
-        state: "committed" as const,
-        data: {
-          request_id: body.request_id,
-          accepted_source_ids: body.source_ids,
-          failed_sources: {},
-          jobs: [],
-        },
-      }),
-    );
-    const operations = { post } as unknown as CoreOperations;
-    const skipped = await executeBatchImport(
-      planned.candidates,
-      readerFor([]),
-      operations,
-      planned.notFound,
-      { confirmOverrides: false },
-    );
-    expect(post.mock.calls[0]![1]).toMatchObject({
-      source_ids: ["codex"],
-      confirm_environment_overrides: false,
-    });
-    expect(skipped.override_required_source_ids).toEqual(["dsh"]);
-    expect(renderBatchScanText(skipped)).toContain("--confirm-overrides");
-
-    const confirmed = await executeBatchImport(
-      planned.candidates,
-      readerFor([]),
-      operations,
-      planned.notFound,
-      { confirmOverrides: true },
-    );
-    expect(post.mock.calls[1]![1]).toMatchObject({
-      source_ids: ["codex", "dsh"],
-      confirm_environment_overrides: true,
-    });
-    expect(confirmed.override_required_source_ids).toBeUndefined();
-  });
-
-  it("refuses without a request when every detected source needs confirmation", async () => {
-    const planned = await planBatchImport(
-      readerFor([
-        found("dsh", {
-          candidate_kind: "environment_override",
-          requires_override_confirmation: true,
-        }),
-      ]),
-    );
-    if (planned.state !== "preview") throw new Error("expected preview");
-    const post = vi.fn();
-    const document = await executeBatchImport(
-      planned.candidates,
-      readerFor([]),
-      { post } as unknown as CoreOperations,
-      planned.notFound,
-      { confirmOverrides: false },
-    );
-    expect(post).not.toHaveBeenCalled();
-    expect(document).toMatchObject({
-      state: "rejected",
-      code: "environment_override_confirmation_required",
-    });
-    expect(batchScanExitCode(document)).toBe(1);
-  });
-});

memhub/apps/cli/src/batch-import-flow.ts

@@ -1,5 +1,4 @@
-/** A19: one-shot connect/import of every *detected* source
- * (`sources connect --all-detected --import`).
+/** A19: one-shot scan/import of every *detected* source.
  *
  * The engine already takes many sources in a single `POST /api/v1/sources/connect`
  * (`source_ids` is a 1..32 tuple) and answers per source. The CLI used to reject
@@ -38,16 +37,13 @@ export interface BatchSourceRow {
 export interface BatchScanDocument {
   schema_version: 1;
   product: string;
-  command: "sources connect";
+  command: "scan" | "init";
   state: "committed" | "partial" | "rejected" | "unknown" | "no_sources";
   request_id: string | null;
   accepted_source_ids: string[];
   sources: BatchSourceRow[];
   /** `location_state != found` rows are listed so the user can see what was skipped. */
   not_found_source_ids: string[];
-  /** Detected sources whose location comes from an environment override and
-   * that were left out because `--confirm-overrides` was not given. */
-  override_required_source_ids?: string[];
   code?: string;
 }
 
@@ -122,39 +118,12 @@ export async function planBatchImport(reader: CoreReader): Promise<
 
 /** Run the batch connect once and fold the per-source receipt into rows. */
 export async function executeBatchImport(
-  detected: readonly SourceConnectionCandidate[],
+  candidates: readonly SourceConnectionCandidate[],
   reader: CoreReader,
   operations: CoreOperations,
   notFound: readonly string[],
-  options: { confirmOverrides: boolean },
 ): Promise<BatchScanDocument> {
   const requestId = randomUUID();
-  // An environment-override location is a choice the user has to confirm:
-  // without `--confirm-overrides` those sources are left out and named.
-  const skipped = options.confirmOverrides
-    ? []
-    : detected
-        .filter((candidate) => candidate.requires_override_confirmation)
-        .map((candidate) => candidate.source_id);
-  const overrideFields =
-    skipped.length > 0 ? { override_required_source_ids: skipped } : {};
-  const candidates = detected.filter(
-    (candidate) => !skipped.includes(candidate.source_id),
-  );
-  if (candidates.length === 0) {
-    return {
-      schema_version: 1,
-      product: PRODUCT,
-      command: "sources connect",
-      state: "rejected",
-      request_id: null,
-      accepted_source_ids: [],
-      sources: [],
-      not_found_source_ids: [...notFound],
-      ...overrideFields,
-      code: "environment_override_confirmation_required",
-    };
-  }
   // Same shared builder as the single-source import and the Web console, so a
   // batch connect cannot drift from either.
   const request = buildSourceImportRequest({
@@ -172,9 +141,9 @@ export async function executeBatchImport(
           : [[candidate.source_id, candidate.candidate_revision]],
       ),
     ),
-    confirmEnvironmentOverrides:
-      options.confirmOverrides &&
-      candidates.some((candidate) => candidate.requires_override_confirmation),
+    confirmEnvironmentOverrides: candidates.some(
+      (candidate) => candidate.requires_override_confirmation,
+    ),
     fullRescan: false,
     onboarding: true,
     enableSync: true,
@@ -185,7 +154,7 @@ export async function executeBatchImport(
     return {
       schema_version: 1,
       product: PRODUCT,
-      command: "sources connect",
+      command: "scan",
       state: result.state,
       request_id: requestId,
       accepted_source_ids: [],
@@ -199,7 +168,6 @@ export async function executeBatchImport(
         failure_reason: result.code,
       })),
       not_found_source_ids: [...notFound],
-      ...overrideFields,
       code: result.code,
     };
   }
@@ -286,7 +254,7 @@ export async function executeBatchImport(
   return {
     schema_version: 1,
     product: PRODUCT,
-    command: "sources connect",
+    command: "scan",
     state:
       failedCount === 0
         ? "committed"
@@ -302,7 +270,6 @@ export async function executeBatchImport(
     accepted_source_ids: accepted,
     sources: rows,
     not_found_source_ids: [...notFound],
-    ...overrideFields,
   };
 }
 
@@ -334,10 +301,5 @@ export function renderBatchScanText(document: BatchScanDocument): string {
       : document.state === "partial"
         ? `部分完成：${document.accepted_source_ids.length} 个成功，其余见上方`
         : `未完成：${document.code ?? "unknown"}`;
-  const overrides = document.override_required_source_ids ?? [];
-  const hint =
-    overrides.length > 0
-      ? `\n未接入（目录来自环境变量覆盖，需确认）：${overrides.join("、")}\n确认目录无误后加 --confirm-overrides 重新运行。`
-      : "";
-  return `${summary}\n${lines.join("\n")}${hint}\n`;
+  return `${summary}\n${lines.join("\n")}\n`;
 }

memhub/apps/cli/src/cli-contract-fixes.test.ts

@@ -1,371 +0,0 @@
-// Contract fixes from the CLI review: exit codes, where JSON goes, the global
-// `--data-dir`, and the write idempotency key.
-import { mkdtemp, writeFile } from "node:fs/promises";
-import { tmpdir } from "node:os";
-import path from "node:path";
-import { beforeEach, describe, expect, it, vi } from "vitest";
-
-import { run } from "./cli.js";
-import { COMMANDS } from "./command-catalog.js";
-
-const transport = vi.hoisted(() => ({
-  get: vi.fn(),
-  post: vi.fn(),
-  put: vi.fn(),
-  patch: vi.fn(),
-  delete: vi.fn(),
-  request: vi.fn(),
-}));
-vi.mock("axios", () => ({
-  default: {
-    create: vi.fn(() => transport),
-    get: transport.get,
-    post: transport.post,
-    request: transport.request,
-    isAxiosError: () => false,
-  },
-}));
-
-const runtime = vi.hoisted(() => ({
-  inspectRuntimeStatus: vi.fn(),
-  discoverRuntimeAttachment: vi.fn(),
-  inspectBackgroundHealth: vi.fn(),
-}));
-vi.mock("@one-memory/runtime-control", async (importOriginal) => ({
-  ...(await importOriginal<typeof import("@one-memory/runtime-control")>()),
-  ...runtime,
-}));
-
-const ATTACHED = {
-  instanceId: "instance-1",
-  apiToken: "synthetic-runtime-token",
-  host: "127.0.0.1",
-  port: 8765,
-  servicePid: 4242,
-  health: {
-    status: "ok",
-    service: "one-memory-core",
-    version: "1.2.3",
-    instance_id: "instance-1",
-  },
-};
-
-beforeEach(() => {
-  vi.clearAllMocks();
-  for (const method of Object.values(transport)) method.mockReset();
-  runtime.inspectRuntimeStatus.mockResolvedValue({
-    state: "running",
-    code: "runtime_verified",
-    instanceId: "instance-1",
-    host: "127.0.0.1",
-    port: 8765,
-    version: "1.2.3",
-  });
-  runtime.discoverRuntimeAttachment.mockResolvedValue(ATTACHED);
-  runtime.inspectBackgroundHealth.mockResolvedValue(null);
-});
-
-describe("--data-dir is a global option", () => {
-  it("points a Runtime-attached command at that data directory", async () => {
-    transport.get.mockResolvedValue({
-      status: 200,
-      data: { request_id: "r", profile: null, elapsed_ms: 1 },
-    });
-    const result = await capturedRun(
-      ["profile", "--data-dir", "/synthetic/other", "--json"],
-      { ONE_MEMORY_DATA_DIR: "/synthetic/default" },
-    );
-    expect(result.code).toBe(0);
-    expect(runtime.inspectRuntimeStatus).toHaveBeenCalledWith(
-      expect.objectContaining({ dataDir: "/synthetic/other" }),
-    );
-  });
-
-  it("is accepted by every command the catalog used to advertise it on", async () => {
-    runtime.inspectRuntimeStatus.mockResolvedValue({
-      state: "stopped",
-      code: "runtime_not_running",
-    });
-    runtime.discoverRuntimeAttachment.mockResolvedValue(null);
-    for (const argv of [
-      ["profile"],
-      ["scan-roots", "list"],
-      ["adapter", "list"],
-      ["scan", "--source", "codex"],
-      ["write", "status", "r-1"],
-      ["backup", "create", "--target", "/synthetic/data/backups/a"],
-      ["memories", "list"],
-    ]) {
-      const result = await capturedRun([
-        ...argv,
-        "--data-dir",
-        "/synthetic/other",
-        "--json",
-      ]);
-      expect(result.code, argv.join(" ")).toBe(3);
-    }
-  });
-
-  it("refuses a relative or repeated --data-dir", async () => {
-    for (const argv of [
-      ["profile", "--data-dir", "relative"],
-      ["profile", "--data-dir", "/a", "--data-dir", "/b"],
-      ["profile", "--data-dir"],
-    ]) {
-      expect((await capturedRun(argv)).code).toBe(2);
-    }
-    expect(runtime.inspectRuntimeStatus).not.toHaveBeenCalled();
-  });
-});
-
-describe("Core failures are exit 1, not usage errors", () => {
-  it("adapter probe reports a Core refusal with its code on stdout", async () => {
-    transport.request.mockResolvedValue({
-      status: 409,
-      data: { detail: "source_not_authorized" },
-    });
-    const result = await capturedRun([
-      "adapter",
-      "probe",
-      "--source",
-      "codex",
-      "--json",
-    ]);
-    expect(result.code).toBe(1);
-    expect(result.stderr).toBe("");
-    expect(JSON.parse(result.stdout)).toMatchObject({
-      command: "adapter probe",
-      state: "failed",
-      code: "source_not_authorized",
-      exit_code: 1,
-    });
-  });
-
-  it("adapter probe prints readable text without --json", async () => {
-    transport.request.mockResolvedValue({
-      status: 200,
-      data: { source: "codex", available: true },
-    });
-    const result = await capturedRun(["adapter", "probe", "--source", "codex"]);
-    expect(result.code).toBe(0);
-    expect(result.stdout).toContain("来源 codex 的探测结果");
-    expect(result.stdout).toContain("available: true");
-  });
-
-  it("scan-roots add posts directly and reports a refusal as exit 1", async () => {
-    transport.request.mockResolvedValue({
-      status: 409,
-      data: { detail: "scan_root_conflict" },
-    });
-    const result = await capturedRun([
-      "scan-roots",
-      "add",
-      "--root",
-      "/synthetic/root",
-      "--source",
-      "codex",
-      "--json",
-    ]);
-    expect(result.code).toBe(1);
-    expect(transport.request).toHaveBeenCalledWith(
-      expect.objectContaining({
-        method: "post",
-        url: "http://127.0.0.1:8765/api/v1/scan-roots",
-        data: { root: "/synthetic/root", source: "codex", recursive: true },
-      }),
-    );
-    expect(JSON.parse(result.stdout).code).toBe("scan_root_conflict");
-  });
-
-  it("the old `path add` spelling still works", async () => {
-    transport.request.mockResolvedValue({ status: 200, data: { ok: true } });
-    const result = await capturedRun([
-      "path",
-      "remove",
-      "--root",
-      "/synthetic/root",
-      "--yes",
-    ]);
-    expect(result.code).toBe(0);
-    expect(transport.request.mock.calls[0][0]).toMatchObject({
-      method: "delete",
-      data: { root: "/synthetic/root" },
-    });
-  });
-
-  it("scan --source runs directly", async () => {
-    transport.post.mockResolvedValue({
-      status: 200,
-      data: { job_id: "j1", source_id: "codex", status: "pending" },
-    });
-    const result = await capturedRun(["scan", "--source", "codex", "--json"]);
-    expect(result.code).toBe(0);
-    expect(JSON.parse(result.stdout)).toMatchObject({
-      command: "scan",
-      state: "committed",
-      scan: { job_id: "j1" },
-    });
-    // A scan without a source is a usage error, not a preview.
-    expect((await capturedRun(["scan"])).code).toBe(2);
-  });
-});
-
-describe("write submit keeps its idempotency key", () => {
-  async function messagesFile(): Promise<string> {
-    const directory = await mkdtemp(path.join(tmpdir(), "memhub-write-"));
-    const file = path.join(directory, "messages.json");
-    await writeFile(file, JSON.stringify([{ role: "user", content: "hi" }]));
-    return file;
-  }
-
-  it("generates a request id, sends it and prints it with a retry hint", async () => {
-    transport.post.mockImplementation(
-      async (_url: string, body: { request_id: string }) => ({
-        status: 200,
-        data: {
-          request_id: body.request_id,
-          state: "accepted",
-          created_at: "T",
-          updated_at: "T",
-        },
-      }),
-    );
-    const result = await capturedRun([
-      "write",
-      "submit",
-      "--session",
-      "s1",
-      "--messages-file",
-      await messagesFile(),
-    ]);
-    expect(result.code).toBe(0);
-    const sent = transport.post.mock.calls[0][1].request_id as string;
-    expect(sent).toMatch(/^[0-9a-f-]{36}$/);
-    expect(result.stdout).toContain(`request_id: ${sent}`);
-    expect(result.stdout).toContain(`--request-id ${sent}`);
-  });
-
-  it("reports a 409 conflict as JSON on stdout with the request id", async () => {
-    transport.post.mockResolvedValue({
-      status: 409,
-      data: { detail: "memory_write_conflict" },
-    });
-    const result = await capturedRun([
-      "write",
-      "submit",
-      "--session",
-      "s1",
-      "--messages-file",
-      await messagesFile(),
-      "--request-id",
-      "req-1",
-      "--json",
-    ]);
-    expect(result.code).toBe(1);
-    expect(result.stderr).toBe("");
-    expect(JSON.parse(result.stdout)).toMatchObject({
-      command: "write submit",
-      state: "rejected",
-      request_id: "req-1",
-      code: "memory_write_conflict",
-    });
-  });
-
-  it("write status of an unknown id is exit 1 with state not_found", async () => {
-    transport.get.mockResolvedValue({ status: 404, data: {} });
-    const error = Object.assign(new Error("404"), {
-      response: { status: 404 },
-    });
-    transport.get.mockRejectedValue(error);
-    const result = await capturedRun(["task", "--id", "nope", "--json"]);
-    // `axios.isAxiosError` is mocked false, so the read error surfaces as a
-    // failed read; either way it is exit 1, never a silent exit 0.
-    expect(result.code).toBe(1);
-  });
-});
-
-describe("doctor and ui use exit 3 for a stopped Runtime", () => {
-  it("doctor exits 3 when the Runtime is stopped", async () => {
-    runtime.inspectRuntimeStatus.mockResolvedValue({
-      state: "stopped",
-      code: "runtime_not_running",
-    });
-    const result = await capturedRun(["doctor", "--json"]);
-    expect(result.code).toBe(3);
-    expect(JSON.parse(result.stdout).schema_version).toBe(1);
-  });
-});
-
-describe("catalog exit codes", () => {
-  it("lists exit 2 for every command, since every parser can reject", () => {
-    for (const command of COMMANDS) {
-      expect(command.exit_codes, command.name).toContain(2);
-    }
-  });
-
-  it("lists exit 3 for every command that attaches to the Runtime", () => {
-    for (const name of [
-      "status",
-      "doctor",
-      "init",
-      "sources",
-      "sync",
-      "progress",
-      "jobs",
-      "models",
-      "memories",
-      "profile",
-      "graph-width",
-      "host",
-      "recall",
-      "scan-roots",
-      "adapter",
-      "scan",
-      "write",
-      "backup",
-      "ui",
-      "onboarding",
-    ]) {
-      const command = COMMANDS.find((entry) => entry.name === name);
-      expect(command?.exit_codes, name).toContain(3);
-    }
-  });
-
-  it("does not claim exit 3 or 4 for lifecycle commands that never return them", () => {
-    for (const name of ["start", "stop", "restart"]) {
-      const command = COMMANDS.find((entry) => entry.name === name);
-      expect(command?.exit_codes).toEqual([0, 1, 2]);
-    }
-  });
-
-  it("says stop turns login auto-start off for a managed service", () => {
-    const stop = COMMANDS.find((entry) => entry.name === "stop");
-    expect(stop?.summary).toContain("登录时也不会自动启动");
-  });
-});
-
-async function capturedRun(
-  arguments_: string[],
-  environment: NodeJS.ProcessEnv = { ONE_MEMORY_DATA_DIR: "/synthetic/data" },
-) {
-  let stdout = "";
-  let stderr = "";
-  const stdoutSpy = vi
-    .spyOn(process.stdout, "write")
-    .mockImplementation((chunk) => {
-      stdout += String(chunk);
-      return true;
-    });
-  const stderrSpy = vi
-    .spyOn(process.stderr, "write")
-    .mockImplementation((chunk) => {
-      stderr += String(chunk);
-      return true;
-    });
-  try {
-    return { code: await run(arguments_, environment), stdout, stderr };
-  } finally {
-    stdoutSpy.mockRestore();
-    stderrSpy.mockRestore();
-  }
-}

memhub/apps/cli/src/cli-logs.test.ts

@@ -1,7 +1,6 @@
-import { mkdtemp, readdir, readFile, rm, writeFile } from "node:fs/promises";
+import { mkdtemp, readdir, rm, writeFile } from "node:fs/promises";
 import os from "node:os";
 import path from "node:path";
-import { inflateRawSync } from "node:zlib";
 import { DiagnosticLogger } from "@one-memory/runtime-control";
 import { afterEach, expect, it, vi } from "vitest";
 
@@ -30,27 +29,6 @@ async function fixture() {
   return dataDir;
 }
 
-function readZipEntry(archive: Buffer, expected: string): string {
-  let offset = 0;
-  while (archive.readUInt32LE(offset) === 0x04034b50) {
-    const method = archive.readUInt16LE(offset + 8);
-    const compressedSize = archive.readUInt32LE(offset + 18);
-    const nameLength = archive.readUInt16LE(offset + 26);
-    const extraLength = archive.readUInt16LE(offset + 28);
-    const nameStart = offset + 30;
-    const dataStart = nameStart + nameLength + extraLength;
-    const name = archive.subarray(nameStart, nameStart + nameLength).toString();
-    const compressed = archive.subarray(dataStart, dataStart + compressedSize);
-    if (name === expected) {
-      if (method === 0) return compressed.toString();
-      if (method === 8) return inflateRawSync(compressed).toString();
-      throw new Error("unsupported zip compression");
-    }
-    offset = dataStart + compressedSize;
-  }
-  throw new Error(`missing ${expected}`);
-}
-
 it("prints matching diagnostic events as NDJSON without starting Runtime", async () => {
   const dataDir = await fixture();
   let stdout = "";
@@ -96,25 +74,6 @@ it("exports one support zip to the requested downloads directory", async () => {
   });
   expect(receipt.path).toMatch(/MemHub-日志-3800-\d{8}-\d{4}\.zip$/);
   expect(await readdir(downloads)).toEqual([path.basename(receipt.path)]);
-  const archive = await readFile(receipt.path);
-  expect(JSON.parse(readZipEntry(archive, "summary.json")).commit).toBeNull();
-});
-
-it("fails closed for an explicitly supplied invalid commit", async () => {
-  const dataDir = await fixture();
-  const downloads = await mkdtemp(path.join(os.tmpdir(), "om-cli-downloads-"));
-  roots.push(downloads);
-  vi.spyOn(process.stdout, "write").mockImplementation(() => true);
-
-  await expect(
-    run(["logs", "export", "--json"], {
-      ONE_MEMORY_DATA_DIR: dataDir,
-      ONE_MEMORY_EXPORT_DIR: downloads,
-      ONE_MEMORY_BUILD_NUMBER: "3800",
-      ONE_MEMORY_COMMIT: "unknown",
-    }),
-  ).rejects.toThrow("diagnostic_commit_invalid");
-  expect(await readdir(downloads)).toEqual([]);
 });
 
 it("never emits a secret from a malformed manually written event", async () => {

memhub/apps/cli/src/cli.test.ts

@@ -1,18 +1,9 @@
-import {
-  mkdir,
-  mkdtemp,
-  readdir,
-  readFile,
-  realpath,
-  rm,
-} from "node:fs/promises";
+import { mkdtemp, readdir, readFile, realpath, rm } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import path from "node:path";
 import {
   claimRuntimeServiceForApp,
-  clearSdkMigrationBlock,
   readRuntimeServiceOwner,
-  recordSdkMigrationBlock,
   resolveRuntimeCliConfig,
 } from "@one-memory/runtime-control";
 import { describe, expect, it, vi } from "vitest";
@@ -66,11 +57,6 @@ const runtimeMocks = vi.hoisted(() => ({
   })),
   uninstallUserService: vi.fn(async (..._args: unknown[]) => "removed"),
   restartUserService: vi.fn(async () => undefined),
-  runSdkMigration: vi.fn(
-    async (): Promise<{ state: string; code?: string }> => ({
-      state: "not_required",
-    }),
-  ),
   rollbackLocalInstall: vi.fn(async () => undefined),
   planCliLink: vi.fn(async ({ home, installRoot }) => ({
     schema_version: 1,
@@ -140,7 +126,6 @@ vi.mock("@one-memory/runtime-control", async (importOriginal) => {
     installUserService: runtimeMocks.installUserService,
     uninstallUserService: runtimeMocks.uninstallUserService,
     restartUserService: runtimeMocks.restartUserService,
-    runSdkMigration: runtimeMocks.runSdkMigration,
     rollbackLocalInstall: runtimeMocks.rollbackLocalInstall,
     planCliLink: runtimeMocks.planCliLink,
     installCliLink: runtimeMocks.installCliLink,
@@ -799,7 +784,7 @@ describe("public One Memory CLI", () => {
       }
     });
 
-    it("upgrade restart failure keeps the new version and never restarts the old one", async () => {
+    it("upgrade failure restarts the restored artifact with the same data identity", async () => {
       vi.clearAllMocks();
       runtimeMocks.planCliLink.mockResolvedValueOnce({
         schema_version: 1,
@@ -841,27 +826,25 @@ describe("public One Memory CLI", () => {
         command: "upgrade",
         code: "restart failed",
       });
-      expect(JSON.parse(streams.stderr())).toMatchObject({
-        rolled_back: false,
-      });
-      // Product rule: the previous Runtime may predate the SDK migration gate,
-      // so it is never restored after the migration was handed the home.
-      expect(runtimeMocks.rollbackLocalInstall).not.toHaveBeenCalled();
-      expect(aliasMocks.rollbackManagedCliLink).not.toHaveBeenCalled();
-      expect(runtimeMocks.restartUserService).toHaveBeenCalledOnce();
-      expect(
-        (runtimeMocks.restartUserService.mock.calls as unknown[][])[0]?.[0],
-      ).toMatchObject({
-        dataDir: "/tmp/custom data",
-        installRoot: "/tmp/install/current",
-      });
+      expect(runtimeMocks.rollbackLocalInstall).toHaveBeenCalledOnce();
+      // The CLI manages the objective aliases the package does not own
+      // (`memhub` + `memhub-cli`); both are rolled back.
+      expect(aliasMocks.rollbackManagedCliLink).toHaveBeenCalledTimes(2);
+      expect(runtimeMocks.restartUserService).toHaveBeenCalledTimes(2);
+      for (const call of runtimeMocks.restartUserService.mock
+        .calls as unknown[][]) {
+        expect(call[0]).toMatchObject({
+          dataDir: "/tmp/custom data",
+          installRoot: "/tmp/install/current",
+        });
+      }
     });
 
     // O-22 (2026-09-29 C8 H17): `upgrade --yes` on a manifest-valid but
     // crash-looping version reported exit 0 and left `current` on the bad
     // version. A restart that merely returns is not proof the new Runtime came
     // up, so the CLI now verifies health and rolls back if it never does.
-    it("fails without rolling back when the upgraded Runtime never becomes healthy", async () => {
+    it("rolls back and fails when the upgraded Runtime never becomes healthy", async () => {
       vi.clearAllMocks();
       runtimeMocks.planCliLink.mockResolvedValueOnce({
         schema_version: 1,
@@ -901,219 +884,9 @@ describe("public One Memory CLI", () => {
         command: "upgrade",
         code: "upgrade_health_check_failed",
       });
-      // Kept on the new version; the old Runtime is not restarted.
-      expect(runtimeMocks.rollbackLocalInstall).not.toHaveBeenCalled();
-      expect(runtimeMocks.restartUserService).toHaveBeenCalledOnce();
-    });
-
-    const upgradeArguments = [
-      "upgrade",
-      "--source",
-      "/tmp/dist",
-      "--home",
-      "/tmp/home",
-      "--install-root",
-      "/tmp/install",
-      "--data-dir",
-      "/tmp/custom data",
-      "--yes",
-    ];
-    const presentCliLink = {
-      schema_version: 1 as const,
-      platform: "linux" as const,
-      home: "/tmp/home",
-      install_root: "/tmp/install",
-      bin_directory: "/tmp/bin",
-      status: "present" as const,
-      blocked_reason: null,
-      link_path: "/tmp/bin/one-memory",
-      target_path: "/tmp/install/current/bin/one-memory",
-    };
-
-    it("says the data was restored when a failed migration put it back", async () => {
-      vi.clearAllMocks();
-      runtimeMocks.planCliLink.mockResolvedValueOnce(presentCliLink);
-      runtimeMocks.runSdkMigration.mockResolvedValueOnce({
-        state: "deferred",
-        code: "sdk_migration_memory_unreadable",
-        dataRestored: true,
-      } as never);
-      const streams = captureStreams();
-      let code: number;
-      try {
-        code = await run(
-          upgradeArguments,
-          {},
-          { waitForRuntimeReady: async () => true },
-        );
-      } finally {
-        streams.restore();
-      }
-      expect(code!).toBe(1);
-      const failure = JSON.parse(streams.stderr());
-      expect(failure).toMatchObject({
-        code: "sdk_migration_memory_unreadable",
-        data_restored: true,
-        log_file: "/tmp/custom data/logs/sdk-migration.log",
-      });
-      expect(failure.message).toContain("记忆数据已恢复到升级前的状态。");
-      expect(failure.message).toContain(
-        "/tmp/custom data/logs/sdk-migration.log",
-      );
-    });
-
-    it("migrates the home with the new Core before restarting the Runtime", async () => {
-      vi.clearAllMocks();
-      runtimeMocks.planCliLink.mockResolvedValueOnce(presentCliLink);
-      const order: string[] = [];
-      runtimeMocks.runSdkMigration.mockImplementationOnce(async () => {
-        order.push("migrate");
-        return { state: "cutover" };
-      });
-      runtimeMocks.restartUserService.mockImplementationOnce(async () => {
-        order.push("restart");
-      });
-      const output = captureStdout();
-      let code: number;
-      try {
-        code = await run(
-          upgradeArguments,
-          {},
-          { waitForRuntimeReady: async () => true },
-        );
-      } finally {
-        output.restore();
-      }
-      expect(code!).toBe(0);
-      expect(order).toEqual(["migrate", "restart"]);
-      expect(runtimeMocks.runSdkMigration).toHaveBeenCalledWith(
-        expect.objectContaining({ dataDir: "/tmp/custom data" }),
-      );
-    });
-
-    it("stays on the new version, not serving, when the migration does not finish", async () => {
-      vi.clearAllMocks();
-      runtimeMocks.planCliLink.mockResolvedValueOnce(presentCliLink);
-      runtimeMocks.runSdkMigration.mockResolvedValueOnce({
-        state: "deferred",
-        code: "sdk_migration_disk_space_insufficient",
-      });
-      const streams = captureStreams();
-      let code: number;
-      try {
-        code = await run(
-          upgradeArguments,
-          {},
-          { waitForRuntimeReady: async () => true },
-        );
-      } finally {
-        streams.restore();
-      }
-      expect(code!).toBe(1);
-      const failure = JSON.parse(streams.stderr());
-      expect(failure).toMatchObject({
-        command: "upgrade",
-        code: "sdk_migration_disk_space_insufficient",
-        // The one file support needs, and where to send it.
-        log_file: "/tmp/custom data/logs/sdk-migration.log",
-        issues_url: "https://github.com/Tencent-Hunyuan/Hy-Memory/issues/new",
-      });
-      expect(failure.message).toContain(
-        "/tmp/custom data/logs/sdk-migration.log",
-      );
-      expect(failure.message).toContain("GitHub");
-      expect(failure.message).not.toContain("回滚到上一版本");
-      expect(runtimeMocks.runSdkMigration).toHaveBeenCalledWith(
-        expect.objectContaining({ caller: "cli-upgrade" }),
-      );
-      // No rollback: the old Runtime has no migration gate. The new service is
-      // (re)started so its gate, not the old Runtime, holds the data dir.
-      expect(runtimeMocks.rollbackLocalInstall).not.toHaveBeenCalled();
-      expect(aliasMocks.rollbackManagedCliLink).not.toHaveBeenCalled();
-      expect(runtimeMocks.restartUserService).toHaveBeenCalledOnce();
-      expect(
-        (runtimeMocks.restartUserService.mock.calls as unknown[][])[0]?.[0],
-      ).toMatchObject({
-        installRoot: "/tmp/install/current",
-      });
-    });
-
-    it("stays on the new version when the migration itself throws", async () => {
-      vi.clearAllMocks();
-      runtimeMocks.planCliLink.mockResolvedValueOnce(presentCliLink);
-      runtimeMocks.runSdkMigration.mockRejectedValueOnce(
-        new Error("sdk_migration_fence_failed"),
-      );
-      const streams = captureStreams();
-      let code: number;
-      try {
-        code = await run(
-          upgradeArguments,
-          {},
-          { waitForRuntimeReady: async () => true },
-        );
-      } finally {
-        streams.restore();
-      }
-      expect(code!).toBe(1);
-      expect(JSON.parse(streams.stderr())).toMatchObject({
-        command: "upgrade",
-        code: "sdk_migration_fence_failed",
-        log_file: "/tmp/custom data/logs/sdk-migration.log",
-        issues_url: "https://github.com/Tencent-Hunyuan/Hy-Memory/issues/new",
-      });
-      expect(runtimeMocks.rollbackLocalInstall).not.toHaveBeenCalled();
-    });
-
-    it("still rolls back a failure before the migration touched the home", async () => {
-      vi.clearAllMocks();
-      runtimeMocks.planCliLink.mockResolvedValueOnce(presentCliLink);
-      aliasMocks.installManagedCliLink.mockRejectedValueOnce(
-        new Error("cli_link_failed"),
-      );
-      const streams = captureStreams();
-      let code: number;
-      try {
-        code = await run(
-          upgradeArguments,
-          {},
-          { waitForRuntimeReady: async () => true },
-        );
-      } finally {
-        streams.restore();
-      }
-      expect(code!).toBe(1);
-      expect(JSON.parse(streams.stderr())).toMatchObject({
-        command: "upgrade",
-        code: "cli_link_failed",
-      });
-      expect(runtimeMocks.runSdkMigration).not.toHaveBeenCalled();
+      // Rolled back to the previous version and restarted it.
       expect(runtimeMocks.rollbackLocalInstall).toHaveBeenCalledOnce();
-      // The previous Runtime was never stopped; nothing is (re)started.
-      expect(runtimeMocks.restartUserService).not.toHaveBeenCalled();
-    });
-
-    it("keeps the new version when a migrated home is slow to come up", async () => {
-      vi.clearAllMocks();
-      runtimeMocks.planCliLink.mockResolvedValueOnce(presentCliLink);
-      runtimeMocks.runSdkMigration.mockResolvedValueOnce({ state: "cutover" });
-      const streams = captureStreams();
-      let code: number;
-      try {
-        code = await run(
-          upgradeArguments,
-          {},
-          { waitForRuntimeReady: async () => false },
-        );
-      } finally {
-        streams.restore();
-      }
-      expect(code!).toBe(1);
-      expect(JSON.parse(streams.stderr())).toMatchObject({
-        command: "upgrade",
-        code: "runtime_not_ready_after_sdk_migration",
-      });
-      expect(runtimeMocks.rollbackLocalInstall).not.toHaveBeenCalled();
+      expect(runtimeMocks.restartUserService).toHaveBeenCalledTimes(2);
     });
 
     it("reports success once the upgraded Runtime is healthy", async () => {
@@ -1611,7 +1384,7 @@ describe("public One Memory CLI", () => {
     expect(JSON.parse(output.value()).apply).toBe(true);
   });
 
-  it("keeps the distribution when service installation fails after the migration ran", async () => {
+  it("rolls back the distribution when service installation fails", async () => {
     runtimeMocks.applyLocalInstall.mockResolvedValueOnce({
       schema_version: 1,
       source: "/tmp/distribution",
@@ -1652,14 +1425,13 @@ describe("public One Memory CLI", () => {
       command: "install",
       status: "error",
       code: "service failed",
-      rolled_back: false,
     });
-    expect(runtimeMocks.rollbackLocalInstall).not.toHaveBeenCalled();
-    expect(runtimeMocks.rollbackCliLink).not.toHaveBeenCalled();
-    expect(aliasMocks.rollbackManagedCliLink).not.toHaveBeenCalled();
+    expect(runtimeMocks.rollbackLocalInstall).toHaveBeenCalledOnce();
+    expect(runtimeMocks.rollbackCliLink).toHaveBeenCalledOnce();
+    expect(aliasMocks.rollbackManagedCliLink).toHaveBeenCalledTimes(2);
   });
 
-  it("upgrades only an existing managed CLI and keeps it after a failed restart", async () => {
+  it("upgrades only an existing managed CLI and rolls back a failed restart", async () => {
     runtimeMocks.planCliLink.mockResolvedValueOnce({
       schema_version: 1,
       platform: "linux",
@@ -1699,7 +1471,7 @@ describe("public One Memory CLI", () => {
       status: "error",
       code: "restart failed",
     });
-    expect(runtimeMocks.rollbackLocalInstall).not.toHaveBeenCalled();
+    expect(runtimeMocks.rollbackLocalInstall).toHaveBeenCalledOnce();
     expect(runtimeMocks.installCliLink).not.toHaveBeenCalled();
   });
 
@@ -2011,11 +1783,19 @@ describe("stopped Runtime is exit 3, not a usage error", () => {
     ["path", "list", "--json"],
     ["adapter", "list", "--json"],
     ["task", "--id", "nope", "--json"],
-    ["write", "status", "nope", "--json"],
-    ["backup", "create", "--target", "/tmp/x", "--json"],
-    ["scan-roots", "add", "--root", "/tmp/x", "--json"],
-    ["scan", "--source", "codex", "--json"],
-    ["onboarding", "reset", "--json"],
+    [
+      "write",
+      "--session",
+      "s",
+      "--from",
+      "1",
+      "--to",
+      "1",
+      "--evidence",
+      "e",
+      "--json",
+    ],
+    ["backup", "create", "--target", "/tmp/x", "--yes", "--json"],
   ])("%s ... --json exits 3 with runtime_not_running", async (...argv) => {
     const streams = captureStreams();
     let code: number;
@@ -2025,9 +1805,7 @@ describe("stopped Runtime is exit 3, not a usage error", () => {
       streams.restore();
     }
     expect(code!).toBe(3);
-    // A result, not an error: on stdout like every other --json document.
-    expect(streams.stderr()).toBe("");
-    const document = JSON.parse(streams.stdout());
+    const document = JSON.parse(streams.stderr());
     expect(document).toMatchObject({
       code: "runtime_not_running",
       exit_code: 3,
@@ -2036,48 +1814,6 @@ describe("stopped Runtime is exit 3, not a usage error", () => {
     expect(document.status).not.toBe("usage_error");
   });
 
-  it("write submit validates its messages file before attaching, then exits 3", async () => {
-    const directory = await mkdtemp(path.join(tmpdir(), "memhub-write-"));
-    const file = path.join(directory, "messages.json");
-    await import("node:fs/promises").then(({ writeFile }) =>
-      writeFile(file, JSON.stringify([{ role: "user", content: "hi" }])),
-    );
-    const streams = captureStreams();
-    let missing: number;
-    let code: number;
-    try {
-      missing = await run(
-        [
-          "write",
-          "submit",
-          "--session",
-          "s",
-          "--messages-file",
-          path.join(directory, "absent.json"),
-          "--json",
-        ],
-        {},
-      );
-      code = await run(
-        [
-          "write",
-          "submit",
-          "--session",
-          "s",
-          "--messages-file",
-          file,
-          "--json",
-        ],
-        {},
-      );
-    } finally {
-      streams.restore();
-      await rm(directory, { recursive: true, force: true });
-    }
-    expect(missing!).toBe(2);
-    expect(code!).toBe(3);
-  });
-
   it.each(["pause", "resume"] as const)(
     "parses sync %s as the direct sync-set command",
     async (action) => {
@@ -2162,189 +1898,6 @@ describe("lifecycle commands accept --json", () => {
   });
 });
 
-// A Runtime service that refuses to serve an unmigrated home must be reported
-// as that, with the migration log and where to send it, not as a generic
-// "not ready within budget".
-describe("lifecycle commands report a migration block", () => {
-  async function blockedHome() {
-    const dataDir = await mkdtemp(path.join(tmpdir(), "memhub-blocked-"));
-    await recordSdkMigrationBlock(
-      dataDir,
-      "sdk_migration_disk_space_insufficient",
-      "runtime-service",
-    );
-    return dataDir;
-  }
-  // darwin: kickstart "restarts" but never becomes ready. Elsewhere: no
-  // service, so the direct spawn fails. Both must surface the block.
-  const blockedControls = () => ({
-    restartManagedRuntime: vi.fn(async () => "restarted" as const),
-    waitForRuntimeReady: vi.fn(async () => false),
-    stopRuntime: vi.fn(async () => "stopped" as const),
-    ensureRuntime: vi.fn(async () => {
-      throw new Error("Timed out waiting for MemHub Runtime");
-    }),
-  });
-
-  it("restart --json prints the block code, log file and issues URL", async () => {
-    const dataDir = await blockedHome();
-    const output = captureStdout();
-    let code: number;
-    try {
-      code = await run(
-        ["restart", "--json"],
-        { ONE_MEMORY_DATA_DIR: dataDir },
-        blockedControls(),
-      );
-    } finally {
-      output.restore();
-      await rm(dataDir, { recursive: true, force: true });
-    }
-    expect(code!).toBe(1);
-    const lines = output.value().trim().split("\n");
-    const document = JSON.parse(lines[lines.length - 1]!);
-    expect(document).toMatchObject({
-      command: "restart",
-      state: "blocked",
-      code: "sdk_migration_disk_space_insufficient",
-      log_file: path.join(dataDir, "logs", "sdk-migration.log"),
-      issues_url: "https://github.com/Tencent-Hunyuan/Hy-Memory/issues/new",
-    });
-    expect(output.value()).not.toContain("runtime_not_ready_within_budget");
-  });
-
-  it("restart on a frozen home retries the migration in the foreground first", async () => {
-    const dataDir = await mkdtemp(path.join(tmpdir(), "memhub-frozen-"));
-    await recordSdkMigrationBlock(
-      dataDir,
-      "sdk_migration_memory_unreadable",
-      "desktop",
-      { frozen: { service_was_enabled: true }, data_restored: true },
-    );
-    const controls = {
-      ...blockedControls(),
-      migrateSdkData: vi.fn(async () => ({
-        state: "deferred" as const,
-        code: "sdk_migration_memory_unreadable",
-        dataRestored: true,
-      })),
-    };
-    const output = captureStdout();
-    let code: number;
-    try {
-      code = await run(
-        ["restart", "--json"],
-        { ONE_MEMORY_DATA_DIR: dataDir },
-        controls,
-      );
-    } finally {
-      output.restore();
-      await rm(dataDir, { recursive: true, force: true });
-    }
-    expect(code!).toBe(1);
-    expect(controls.migrateSdkData).toHaveBeenCalledWith(
-      expect.objectContaining({ dataDir, caller: "cli-restart" }),
-    );
-    // Still frozen: the service is not started to retry on its own.
-    expect(controls.restartManagedRuntime).not.toHaveBeenCalled();
-    expect(controls.ensureRuntime).not.toHaveBeenCalled();
-    expect(JSON.parse(output.value())).toMatchObject({
-      command: "restart",
-      state: "blocked",
-      code: "sdk_migration_memory_unreadable",
-      data_restored: true,
-    });
-  });
-
-  it("restart on a frozen home restarts the Runtime once the retry succeeds", async () => {
-    const dataDir = await mkdtemp(path.join(tmpdir(), "memhub-frozen-"));
-    await recordSdkMigrationBlock(
-      dataDir,
-      "sdk_migration_memory_unreadable",
-      "desktop",
-      { frozen: { service_was_enabled: false } },
-    );
-    const order: string[] = [];
-    const migrateSdkData = vi.fn(async () => {
-      order.push("migrate");
-      await clearSdkMigrationBlock(dataDir);
-      return { state: "cutover" as const };
-    });
-    const output = captureStreams();
-    let code: number;
-    try {
-      code = await run(
-        ["restart", "--json"],
-        { ONE_MEMORY_DATA_DIR: dataDir },
-        {
-          migrateSdkData,
-          waitForRuntimeReady: vi.fn(async () => true),
-          restartManagedRuntime: vi.fn(async () => {
-            order.push("restart");
-            return "restarted" as const;
-          }),
-          stopRuntime: vi.fn(async () => "stopped" as const),
-          ensureRuntime: vi.fn(async () => {
-            order.push("restart");
-            return { pid: 1 } as never;
-          }),
-        },
-      );
-    } finally {
-      output.restore();
-      await rm(dataDir, { recursive: true, force: true });
-    }
-    expect(code!).toBe(0);
-    expect(migrateSdkData).toHaveBeenCalledWith(
-      expect.objectContaining({ caller: "cli-restart" }),
-    );
-    expect(order).toEqual(["migrate", "restart"]);
-  });
-
-  it("restart in text mode names the log file and GitHub issues", async () => {
-    const dataDir = await blockedHome();
-    const output = captureStdout();
-    try {
-      expect(
-        await run(
-          ["restart"],
-          { ONE_MEMORY_DATA_DIR: dataDir },
-          blockedControls(),
-        ),
-      ).toBe(1);
-    } finally {
-      output.restore();
-      await rm(dataDir, { recursive: true, force: true });
-    }
-    expect(output.value()).toContain("sdk_migration_disk_space_insufficient");
-    expect(output.value()).toContain(
-      path.join(dataDir, "logs", "sdk-migration.log"),
-    );
-    expect(output.value()).toContain(
-      "https://github.com/Tencent-Hunyuan/Hy-Memory/issues/new",
-    );
-  });
-
-  it("ui --json reports the block instead of runtime_not_running", async () => {
-    const dataDir = await blockedHome();
-    const output = captureStdout();
-    let code: number;
-    try {
-      code = await run(["ui", "--json"], { ONE_MEMORY_DATA_DIR: dataDir });
-    } finally {
-      output.restore();
-      await rm(dataDir, { recursive: true, force: true });
-    }
-    expect(code!).not.toBe(0);
-    expect(JSON.parse(output.value())).toMatchObject({
-      command: "ui",
-      state: "blocked",
-      code: "sdk_migration_disk_space_insufficient",
-      log_file: path.join(dataDir, "logs", "sdk-migration.log"),
-    });
-  });
-});
-
 // The objective names `memhub host install <host>` (host as a positional). Both
 // that and the `--host <id>` flag form must reach the same command; naming both
 // at once is ambiguous and refused rather than guessed.
@@ -2454,7 +2007,7 @@ describe("install gates on Runtime readiness", () => {
     });
   }
 
-  it("fails without rolling back when the installed Runtime never becomes ready", async () => {
+  it("fails and rolls back when the installed Runtime never becomes ready", async () => {
     vi.clearAllMocks();
     stubInstallPlan();
     const streams = captureStreams();
@@ -2483,10 +2036,10 @@ describe("install gates on Runtime readiness", () => {
     }
     expect(code!).toBe(1);
     expect(streams.stderr()).toContain("install_runtime_not_ready");
-    expect(runtimeMocks.rollbackLocalInstall).not.toHaveBeenCalled();
+    expect(runtimeMocks.rollbackLocalInstall).toHaveBeenCalledOnce();
     expect(
       lifecycleMocks.rollbackPreparedServiceInstall,
-    ).not.toHaveBeenCalled();
+    ).toHaveBeenCalledOnce();
   });
 
   it("takes CLI ownership after a successful install over an App-owned Runtime", async () => {
@@ -2531,7 +2084,7 @@ describe("install gates on Runtime readiness", () => {
     }
   });
 
-  it("never hands the home back to the App Runtime after the migration ran", async () => {
+  it("restores App ownership before relaunching the old Runtime after install failure", async () => {
     vi.clearAllMocks();
     stubInstallPlan();
     const root = await mkdtemp(path.join(tmpdir(), "memhub-cli-owner-"));
@@ -2541,6 +2094,14 @@ describe("install gates on Runtime readiness", () => {
       appBundle: "/Applications/MemHub.app",
       appExecutable: "/Applications/MemHub.app/Contents/MacOS/MemHub",
     });
+    lifecycleMocks.rollbackPreparedServiceInstall.mockImplementationOnce(
+      async (_prepared: unknown, rollback: () => Promise<void>) => {
+        await rollback();
+        await expect(readRuntimeServiceOwner(dataDir)).resolves.toMatchObject({
+          owner: "app",
+        });
+      },
+    );
     const streams = captureStreams();
     try {
       expect(
@@ -2563,114 +2124,15 @@ describe("install gates on Runtime readiness", () => {
           { waitForRuntimeReady: async () => false },
         ),
       ).toBe(1);
-      // The App Runtime may predate the SDK migration gate: CLI keeps it.
       await expect(readRuntimeServiceOwner(dataDir)).resolves.toMatchObject({
-        owner: "cli",
+        owner: "app",
       });
-      expect(
-        lifecycleMocks.rollbackPreparedServiceInstall,
-      ).not.toHaveBeenCalled();
     } finally {
       streams.restore();
       await rm(root, { recursive: true, force: true });
     }
   });
 
-  it("keeps the install, not serving, when its migration is deferred", async () => {
-    vi.clearAllMocks();
-    stubInstallPlan();
-    runtimeMocks.runSdkMigration.mockResolvedValueOnce({
-      state: "deferred",
-      code: "sdk_migration_memory_unreadable",
-    });
-    const waitForRuntimeReady = vi.fn(async () => true);
-    const streams = captureStreams();
-    let code: number;
-    try {
-      code = await run(
-        [
-          "install",
-          "--source",
-          "/tmp/dist",
-          "--home",
-          "/tmp/home",
-          "--install-root",
-          "/tmp/install",
-          "--bin-dir",
-          "/tmp/bin",
-          "--data-dir",
-          "/tmp/data",
-          "--yes",
-        ],
-        {},
-        { waitForRuntimeReady },
-      );
-    } finally {
-      streams.restore();
-    }
-    expect(code!).toBe(1);
-    const failure = JSON.parse(streams.stderr());
-    expect(failure).toMatchObject({
-      command: "install",
-      code: "sdk_migration_memory_unreadable",
-      log_file: "/tmp/data/logs/sdk-migration.log",
-      issues_url: "https://github.com/Tencent-Hunyuan/Hy-Memory/issues/new",
-    });
-    expect(failure.message).toContain("/tmp/data/logs/sdk-migration.log");
-    expect(runtimeMocks.runSdkMigration).toHaveBeenCalledWith(
-      expect.objectContaining({ caller: "cli-install" }),
-    );
-    // The new (gated) service owns the data dir; the previous registration is
-    // never re-bootstrapped and nothing is rolled back.
-    expect(lifecycleMocks.applyPreparedServiceInstall).toHaveBeenCalledWith(
-      expect.objectContaining({ restorePreviousOnFailure: false }),
-    );
-    expect(runtimeMocks.rollbackLocalInstall).not.toHaveBeenCalled();
-    expect(
-      lifecycleMocks.rollbackPreparedServiceInstall,
-    ).not.toHaveBeenCalled();
-    expect(waitForRuntimeReady).not.toHaveBeenCalled();
-  });
-
-  it("still rolls back an install that failed before its migration ran", async () => {
-    vi.clearAllMocks();
-    stubInstallPlan();
-    runtimeMocks.installCliLink.mockRejectedValueOnce(
-      new Error("cli_link_failed"),
-    );
-    const streams = captureStreams();
-    let code: number;
-    try {
-      code = await run(
-        [
-          "install",
-          "--source",
-          "/tmp/dist",
-          "--home",
-          "/tmp/home",
-          "--install-root",
-          "/tmp/install",
-          "--bin-dir",
-          "/tmp/bin",
-          "--data-dir",
-          "/tmp/data",
-          "--yes",
-        ],
-        {},
-        { waitForRuntimeReady: async () => true },
-      );
-    } finally {
-      streams.restore();
-    }
-    expect(code!).toBe(1);
-    expect(JSON.parse(streams.stderr())).toMatchObject({
-      command: "install",
-      code: "cli_link_failed",
-    });
-    expect(runtimeMocks.runSdkMigration).not.toHaveBeenCalled();
-    expect(runtimeMocks.rollbackLocalInstall).toHaveBeenCalledOnce();
-  });
-
   it("succeeds when the installed Runtime becomes ready", async () => {
     vi.clearAllMocks();
     stubInstallPlan();
@@ -2750,8 +2212,7 @@ describe("ui wires the Core session contract without token leakage", () => {
     } finally {
       output.restore();
     }
-    // A stopped Runtime is exit 3, like every other command.
-    expect(code!).toBe(3);
+    expect(code!).toBe(4);
     const document = JSON.parse(output.value());
     expect(document).toMatchObject({
       schema_version: 1,
@@ -2780,120 +2241,6 @@ describe("ui wires the Core session contract without token leakage", () => {
 // refuse while the Runtime owns the data dir, stop+call Core from a
 // maintenance process, and never report success from a malformed response.
 describe("backup restore drives the Core managed-restore contract", () => {
-  it("previews without --yes, exits 0 and starts nothing", async () => {
-    const maintenance = vi.fn();
-    const output = captureStdout();
-    let code: number;
-    try {
-      code = await run(
-        ["backup", "restore", "--source", "/tmp/x", "--json"],
-        {},
-        { runMaintenanceRestore: maintenance },
-      );
-    } finally {
-      output.restore();
-    }
-    expect(code!).toBe(0);
-    expect(maintenance).not.toHaveBeenCalled();
-    expect(JSON.parse(output.value())).toMatchObject({
-      command: "backup restore",
-      state: "preview",
-      target: "/tmp/x",
-      applied: false,
-      next_step: "memhub backup restore --source /tmp/x --yes --confirm /tmp/x",
-    });
-  });
-
-  it("deletes data only when --confirm repeats the data directory", async () => {
-    const home = await mkdtemp(path.join(tmpdir(), "memhub-delete-home-"));
-    const dataDir = path.join(home, ".one-memory");
-    await mkdir(path.join(dataDir, "logs"), { recursive: true });
-    const deleteData = async (...extra: string[]) => {
-      const output = captureStdout();
-      try {
-        const code = await run(
-          ["delete-data", "--data-dir", dataDir, ...extra, "--json"],
-          { HOME: home },
-        );
-        return { code, document: JSON.parse(output.value()) };
-      } finally {
-        output.restore();
-      }
-    };
-    try {
-      const refused = await deleteData("--yes");
-      expect(refused.code).toBe(4);
-      expect(refused.document).toMatchObject({
-        state: "blocked",
-        code: "data_deletion_confirmation_required",
-      });
-      expect(await readdir(dataDir)).toEqual(["logs"]);
-
-      const deleted = await deleteData("--yes", "--confirm", dataDir);
-      expect(deleted.code).toBe(0);
-      expect(await readdir(dataDir).catch(() => [])).toEqual([]);
-    } finally {
-      await rm(home, { recursive: true, force: true });
-    }
-  });
-
-  it("refuses --yes without repeating the backup path", async () => {
-    const maintenance = vi.fn();
-    const output = captureStdout();
-    let code: number;
-    try {
-      code = await run(
-        ["backup", "restore", "--source", "/tmp/x", "--yes", "--json"],
-        {},
-        { runMaintenanceRestore: maintenance },
-      );
-    } finally {
-      output.restore();
-    }
-    expect(code!).toBe(4);
-    expect(maintenance).not.toHaveBeenCalled();
-    expect(JSON.parse(output.value())).toMatchObject({
-      state: "rejected",
-      code: "backup_restore_confirmation_required",
-      next_step:
-        "恢复需要再写一遍备份路径：memhub backup restore --source /tmp/x --yes --confirm /tmp/x",
-    });
-  });
-
-  it("restores with --yes and the repeated backup path", async () => {
-    const maintenance = vi.fn(async () => ({
-      state: "restored" as const,
-      result: {
-        state: "restored" as const,
-        restoredBytes: 1,
-        previousBackupPath: "/tmp/pre.sqlite3",
-        sourceSchemaVersion: 34,
-      },
-    }));
-    const output = captureStdout();
-    let code: number;
-    try {
-      code = await run(
-        [
-          "backup",
-          "restore",
-          "--source",
-          "/tmp/x",
-          "--yes",
-          "--confirm",
-          "/tmp/x",
-          "--json",
-        ],
-        {},
-        { runMaintenanceRestore: maintenance },
-      );
-    } finally {
-      output.restore();
-    }
-    expect(code!).toBe(0);
-    expect(maintenance).toHaveBeenCalledTimes(1);
-  });
-
   it("rejects while the Runtime is running, with a distinct exit code", async () => {
     runtimeMocks.inspectRuntimeStatus.mockResolvedValueOnce({
       state: "running",
@@ -3010,7 +2357,7 @@ describe("backup restore drives the Core managed-restore contract", () => {
     });
   });
 
-  it("refuses a legacy --confirm that does not repeat the source path", async () => {
+  it("requires --confirm to repeat the exact source path", async () => {
     const maintenance = vi.fn();
     const output = captureStdout();
     let code: number;
@@ -3038,7 +2385,7 @@ describe("backup restore drives the Core managed-restore contract", () => {
       command: "backup",
       verb: "restore",
       state: "rejected",
-      code: "backup_restore_confirmation_mismatch",
+      code: "backup_restore_confirmation_required",
     });
   });
 
@@ -3190,7 +2537,7 @@ describe("init onboarding", () => {
 
   // Boolean flags were idempotent, but accepting them twice hid a duplicated
   // argv fragment that could also have duplicated a value-bearing flag.
-  it.each(["--import", "--confirm-overrides"])(
+  it.each(["--import", "--full-rescan", "--confirm-overrides", "--dry-run"])(
     "refuses a repeated init %s flag",
     async (flag) => {
       expect(await run(["init", "--source", "codex", flag, flag], {})).toBe(2);
@@ -3263,25 +2610,12 @@ describe("init onboarding", () => {
     },
   );
 
-  // `--dry-run` and `--full-rescan` never did anything (P0-2/P0-3): they are
-  // gone rather than accepted as no-ops.
-  it.each(["--dry-run", "--full-rescan"])(
-    "refuses the removed no-op %s flag",
-    async (flag) => {
-      expect(
-        await run(["init", "--source", "codex", "--import", flag], {}),
-      ).toBe(2);
-    },
-  );
-
-  it("still parses the old `init --source --import` spelling", async () => {
-    // It stops at the Runtime check (exit 3), which is not a usage failure.
-    const streams = captureStreams();
-    try {
-      expect(await run(["init", "--source", "codex", "--import"], {})).toBe(3);
-    } finally {
-      streams.restore();
-    }
+  it("accepts --dry-run together with --import", async () => {
+    // Parsing must accept the pair; it stops at the Runtime check, which is
+    // not a usage failure.
+    expect(
+      await run(["init", "--source", "codex", "--import", "--dry-run"], {}),
+    ).not.toBe(2);
   });
 });
 

memhub/apps/cli/src/command-catalog.ts

@@ -58,12 +58,6 @@ const CONFIRM_OPTION: CommandOption = {
   flag: "--yes",
   summary: "确认执行；不加该参数时只输出计划，不做任何改动。",
 };
-/** The one confirmation convention, for irreversible operations only. */
-const DESTRUCTIVE_CONFIRM_OPTION: CommandOption = {
-  flag: "--yes",
-  summary:
-    "确认这次不可逆操作；不加时只说明将要做什么，不做任何改动，exit 0。（旧的 --confirm 仍作为别名接受。）",
-};
 const JSON_OPTION: CommandOption = {
   flag: "--json",
   summary: "以 JSON 输出到 stdout，供脚本与 Agent 消费。",
@@ -76,6 +70,21 @@ const INTERVAL_OPTION: CommandOption = {
   flag: "--interval <seconds>",
   summary: "刷新间隔，默认 5 秒，范围 1..300；必须与 --watch 一起使用。",
 };
+const PLAN_FILE_OPTION: CommandOption = {
+  flag: "--plan-file <path>",
+  summary: "读取先前 --json 保存的有界计划文件。",
+};
+const EXPLICIT_CONFIRM_OPTION: CommandOption = {
+  flag: "--confirm",
+  summary: "确认执行计划文件逐字描述的操作；缺少时绝不写入。",
+};
+// Same flag, but for commands that name their target directly instead of
+// going through a saved plan file; the plan-file wording would be wrong here.
+const DIRECT_CONFIRM_OPTION: CommandOption = {
+  flag: "--confirm",
+  summary: "确认执行上面预览的这次操作；缺少时绝不写入。",
+};
+
 const SERVICE_OPTIONS: readonly CommandOption[] = [
   PLATFORM_OPTION,
   HOME_OPTION,
@@ -145,77 +154,55 @@ const INSTALL_OPTIONS: readonly CommandOption[] = [
 const INSTALL_USAGE =
   "[--source <path> | --release-manifest-url <https-url>] [--channel <stable|prerelease>] [--install-root <path>] [--home <path>] [--bin-dir <path>] [--data-dir <path>] [--uid <id>] [--xdg-config-home <path>] [--no-shell-path] [--shell-profile <path>] [--preserve-data-dir] [--allow-downgrade] [--yes]";
 
-const USAGE_EXITS = [EXIT_OK, EXIT_FAILED, EXIT_USAGE] as const;
-const RUNTIME_EXITS = [
-  EXIT_OK,
-  EXIT_FAILED,
-  EXIT_USAGE,
-  EXIT_RUNTIME_STOPPED,
-] as const;
-
-const KIND_OPTION: CommandOption = {
-  flag: "--kind <chat|experience|fact>",
-  summary:
-    "记忆所在的命名空间；工作/编码场景的经验和事实需要同时给 --variant。list 输出里每条都带 kind/variant。",
-};
-const VARIANT_OPTION: CommandOption = {
-  flag: "--variant <working|coding>",
-  summary:
-    "经验或事实属于工作还是编码场景；必须和 --kind experience|fact 一起用。",
-};
-
 export const COMMANDS: readonly CommandDescriptor[] = [
   {
     name: "serve",
     summary: "在前台启动完整 Runtime（Core 与 Host Gateway），不注册系统服务。",
     usage: "memhub serve",
     options: [],
-    exit_codes: USAGE_EXITS,
+    exit_codes: [EXIT_OK, EXIT_FAILED],
   },
   {
     name: "start",
-    summary:
-      "启动本机 Runtime；已有通过身份校验的实例时只连接，不重复启动。受管服务会同时恢复登录时自动启动。",
+    summary: "启动本机 Runtime；已有通过身份校验的实例时只连接，不重复启动。",
     usage: "memhub start [--json]",
     options: [JSON_OPTION],
-    exit_codes: USAGE_EXITS,
+    exit_codes: [EXIT_OK, EXIT_FAILED, EXIT_RUNTIME_STOPPED],
   },
   {
     name: "stop",
-    summary:
-      "停止通过身份校验的本机 Runtime；身份不明确时不发送信号。受管服务（launchd/systemd、App）停止后登录时也不会自动启动，直到再次运行 memhub start。",
+    summary: "停止通过身份校验的本机 Runtime；身份不明确时不发送信号。",
     usage: "memhub stop [--json]",
     options: [JSON_OPTION],
-    exit_codes: USAGE_EXITS,
+    exit_codes: [EXIT_OK, EXIT_FAILED],
   },
   {
     name: "restart",
     summary: "先停止再启动本机 Runtime，两步串行执行。",
     usage: "memhub restart [--json]",
     options: [JSON_OPTION],
-    exit_codes: USAGE_EXITS,
+    exit_codes: [EXIT_OK, EXIT_FAILED],
   },
   {
     name: "status",
     summary: "只读查询 Runtime 运行状态；不启动服务、不迁移数据、不改配置。",
     usage: "memhub status [--watch] [--interval <seconds>] [--json]",
     options: [WATCH_OPTION, INTERVAL_OPTION, JSON_OPTION],
-    exit_codes: RUNTIME_EXITS,
+    exit_codes: [EXIT_OK, EXIT_FAILED, EXIT_RUNTIME_STOPPED],
   },
   {
     name: "doctor",
-    summary:
-      "按诊断口径做只读检查并给出修复建议；默认不修复任何东西。Runtime 未运行时 exit 3。",
+    summary: "按诊断口径做同样的只读检查；默认不修复任何东西。",
     usage: "memhub doctor [--json]",
     options: [JSON_OPTION],
-    exit_codes: RUNTIME_EXITS,
+    exit_codes: [EXIT_OK, EXIT_FAILED, EXIT_RUNTIME_STOPPED],
   },
   {
     name: "logs",
     summary:
-      "读取本机脱敏诊断日志；logs export 会把排查包（含系统崩溃报告）直接存到下载目录。默认显示最近一次会话的 200 条事件。",
+      "读取本机脱敏诊断日志；logs export 会把排查包直接存到下载目录。默认显示最近一次会话的 200 条事件。",
     usage:
-      "memhub logs export [--json]\n            memhub logs [--since <15m|2h|7d|RFC3339>] [--session <id>] [--trace <id>] [--incident <id>] [--operation <id>] [--request <id>] [--job <id>] [--task <id>] [--component <name>] [--event <name>] [--errors-only] [--tail <1..5000>] [--follow] [--json]",
+      "memhub logs export [--json]\nmemhub logs [--since <15m|2h|7d|RFC3339>] [--session <id>] [--trace <id>] [--incident <id>] [--operation <id>] [--request <id>] [--job <id>] [--task <id>] [--component <name>] [--event <name>] [--errors-only] [--tail <1..5000>] [--follow] [--json]",
     options: [
       {
         flag: "--since <time>",
@@ -239,46 +226,64 @@ export const COMMANDS: readonly CommandDescriptor[] = [
           "以 NDJSON 输出到 stdout（每行一个脱敏事件；非单 JSON 文档），供脚本与 Agent 消费。",
       },
     ],
-    exit_codes: USAGE_EXITS,
+    exit_codes: [EXIT_OK, EXIT_FAILED, EXIT_USAGE],
   },
   {
     name: "init",
     summary:
-      "首次接入引导。在终端里（未加 --json）进入交互向导：选择来源 → 是否开启处理 → 配置模型。非终端或加 --json 时不读 stdin，只列出可接入的来源和下一步命令。脚本接入请用 sources connect。",
-    usage: "memhub init [--json]",
-    options: [JSON_OPTION],
-    exit_codes: RUNTIME_EXITS,
-  },
-  {
-    name: "sources",
-    summary:
-      "列出来源，直接接入来源，或按 request id 查接入回执。connect 不加 --import 只授权（处理保持冻结：不导入历史、不扫描新会话）；加 --import 同时导入历史并开启持续同步，返回 request id。目录来自环境变量覆盖的来源必须加 --confirm-overrides。",
+      "首次接入：选择来源 → 选择是否导入历史。接入即开启该 Harness 的处理；后续可用 sync pause/resume 冻结或恢复。在终端且不带 --source 时进入交互引导（默认全选）；非终端或加 --json 时不读 stdin、只列出可用来源和下一步。--all-detected 一次接入所有已检测来源。",
     usage:
-      "memhub sources list [--json]\n            memhub sources connect <id> [<id> ...] [--import] [--confirm-overrides] [--request-id <uuid>] [--json]\n            memhub sources connect --all-detected [--import] [--confirm-overrides] [--json]\n            memhub sources receipt <request-id> [--json]",
+      "memhub init [--json]\n            memhub init --source <id> [--source <id> ...] [--import] [--dry-run] [--full-rescan] [--confirm-overrides] [--json]\n            memhub init --all-detected [--import] [--dry-run] [--json]",
     options: [
       {
-        flag: "--import",
-        summary:
-          "接入后立即导入历史会话并开启持续同步；不加时只授权，处理保持冻结。",
+        flag: "--source <id>",
+        summary: "要接入的来源，可重复；终端下不给则进入交互引导。",
       },
       {
         flag: "--all-detected",
         summary:
-          "接入全部已检测到（location_state=found）的来源；与具体来源互斥。",
+          "接入并（加 --import 时）导入全部 location_state=found 的来源。",
+      },
+      {
+        flag: "--import",
+        summary: "接入后立即导入该来源的历史会话（默认只接入不导入）。",
+      },
+      {
+        flag: "--dry-run",
+        summary: "只出计划，不接入也不导入；用于先看会做什么。",
+      },
+      {
+        flag: "--full-rescan",
+        summary: "导入时忽略既有游标做全量重扫。",
       },
       {
         flag: "--confirm-overrides",
-        summary:
-          "确认接受目录来自环境变量覆盖的来源（如 DSH_HOME 指定的目录）；不加时这些来源被拒绝（指定来源时）或跳过并列出（--all-detected 时）。",
-      },
-      {
-        flag: "--request-id <uuid>",
-        summary:
-          "--import 的幂等键；用同一个 id 重试只会读回第一次的回执，不会重复导入。",
+        summary: "确认接受环境覆盖类来源（如 DSH_HOME 指定的目录）。",
       },
       JSON_OPTION,
     ],
-    exit_codes: RUNTIME_EXITS,
+    exit_codes: [EXIT_OK, EXIT_FAILED, EXIT_USAGE, EXIT_RUNTIME_STOPPED],
+  },
+  {
+    name: "setup",
+    summary: "生成无头首次导入计划；只读取已有来源，不探测目录、不写授权。",
+    usage: "memhub setup plan --source <id> [--source <id> ...] [--json]",
+    options: [
+      {
+        flag: "--source <id>",
+        summary: "计划导入的来源，可重复 1..32 次。",
+      },
+      JSON_OPTION,
+    ],
+    exit_codes: [EXIT_OK, EXIT_FAILED, EXIT_USAGE, EXIT_RUNTIME_STOPPED],
+  },
+  {
+    name: "sources",
+    summary: "列出来源、执行已确认的导入计划。",
+    usage:
+      "memhub sources list [--json]\n            memhub sources import --plan-file <path> --confirm [--json]\n            memhub sources receipt <request-id> [--json]",
+    options: [PLAN_FILE_OPTION, EXPLICIT_CONFIRM_OPTION, JSON_OPTION],
+    exit_codes: [EXIT_OK, EXIT_FAILED, EXIT_USAGE, EXIT_RUNTIME_STOPPED],
   },
   {
     name: "sync",
@@ -292,7 +297,7 @@ export const COMMANDS: readonly CommandDescriptor[] = [
       },
       JSON_OPTION,
     ],
-    exit_codes: RUNTIME_EXITS,
+    exit_codes: [EXIT_OK, EXIT_FAILED, EXIT_USAGE, EXIT_RUNTIME_STOPPED],
   },
   {
     name: "progress",
@@ -313,17 +318,17 @@ export const COMMANDS: readonly CommandDescriptor[] = [
       INTERVAL_OPTION,
       JSON_OPTION,
     ],
-    exit_codes: RUNTIME_EXITS,
+    exit_codes: [EXIT_OK, EXIT_FAILED, EXIT_USAGE, EXIT_RUNTIME_STOPPED],
   },
   {
     name: "jobs",
     summary:
-      "查看或控制导入任务：start 创建 history/sync 任务；pause/resume/cancel 控制已有任务。都直接执行。",
+      "启动或控制单个导入任务：start 创建 history/sync 作业；pause/resume/cancel 控制已有作业。所有写操作先出计划，必须显式 --confirm；list/show 为只读。",
     usage:
       "memhub jobs list [--json]\n" +
       "            memhub jobs show <job-id> [--json]\n" +
-      "            memhub jobs start --source <id> [--operation <history|sync>] [--json]\n" +
-      "            memhub jobs <pause|resume|cancel> --job <id> [--json]",
+      "            memhub jobs start --source <id> [--operation <history|sync>] [--confirm] [--json]\n" +
+      "            memhub jobs <pause|resume|cancel> --job <id> [--confirm] [--json]",
     options: [
       {
         flag: "--source <id>",
@@ -331,116 +336,192 @@ export const COMMANDS: readonly CommandDescriptor[] = [
       },
       {
         flag: "--operation <history|sync>",
-        summary:
-          "start 的导入类型，默认 history；sync 与 scan --source 相同，立即增量同步一次。",
+        summary: "start 的导入类型，默认 history。",
       },
       {
         flag: "--job <id>",
         summary: "pause/resume/cancel 的目标导入任务。",
       },
+      DIRECT_CONFIRM_OPTION,
       JSON_OPTION,
     ],
-    exit_codes: RUNTIME_EXITS,
+    exit_codes: [EXIT_OK, EXIT_FAILED, EXIT_USAGE, EXIT_RUNTIME_STOPPED],
+  },
+  {
+    name: "processing",
+    summary: "手动推进待处理证据；默认只预览，确认后执行。",
+    usage:
+      "memhub processing extract [--evidence <id> ...] [--confirm] [--json]",
+    options: [
+      {
+        flag: "--evidence <id>",
+        summary:
+          "processing extract 要提前处理的证据 ID，可重复；不给则推进下一批。",
+      },
+      DIRECT_CONFIRM_OPTION,
+      JSON_OPTION,
+    ],
+    exit_codes: [EXIT_OK, EXIT_FAILED, EXIT_USAGE, EXIT_RUNTIME_STOPPED],
   },
   {
     name: "models",
     summary:
-      "管理生成模型配置。add/test 直接提交并返回操作 ID（异步，用 receipt 查结果）；edit/activate 直接执行；remove 不可逆，需 --yes。<profile-id>/<operation-id> 都是 UUID；脚本模式的凭据只从受控文件读取。",
+      "交互配置模型，或生成配置/探测计划、执行已确认操作与查询回执；脚本模式的凭据只从受控文件读取。",
     usage:
-      "memhub models list [--json]\n            memhub models show <profile-id> [--json]\n            memhub models add --config-file <path> [--api-key-file <path>] [--activate] [--json]\n            memhub models test <profile-id> [--json]\n            memhub models receipt <operation-id> [--json]\n            memhub models edit <profile-id> --config-file <path> [--api-key-file <path>] [--json]\n            memhub models activate <profile-id> [--json]\n            memhub models remove <profile-id> [--yes] [--json]",
+      "memhub models list [--json]\n            memhub models show <profile-id> [--json]\n            memhub models plan --config-file <path> [--json]\n            memhub models configure --plan-file <path> --confirm [--api-key-file <path>] [--json]\n            memhub models receipt <operation-id> [--json]\n            memhub models edit <profile-id> --config-file <path> [--confirm] [--api-key-file <path>] [--json]\n            memhub models activate <profile-id> [--confirm] [--json]\n            memhub models probe-plan <profile-id> [--json]\n            memhub models probe --plan-file <path> --confirm [--json]\n            memhub models probe-receipt <operation-id> [--json]\n            memhub models remove <profile-id> [--confirm] [--json]",
     alternative_usage: "memhub models setup",
     options: [
       {
         flag: "--config-file <path>",
-        summary:
-          "有界 JSON 模型配置，不能含 api_key；edit 的补丁必须带 expected_revision。",
+        summary: "不含 api_key 的有界 JSON 模型配置。",
       },
+      PLAN_FILE_OPTION,
+      EXPLICIT_CONFIRM_OPTION,
       {
         flag: "--api-key-file <path>",
-        summary: "从属主专用的普通文件读取凭据；内容不进入参数、输出或错误。",
+        summary: "从 regular file 读取凭据；内容不进入参数、输出或错误。",
       },
-      {
-        flag: "--activate",
-        summary: "add 成功后把新配置设为当前使用。",
-      },
-      DESTRUCTIVE_CONFIRM_OPTION,
       JSON_OPTION,
     ],
-    exit_codes: RUNTIME_EXITS,
+    exit_codes: [EXIT_OK, EXIT_FAILED, EXIT_USAGE, EXIT_RUNTIME_STOPPED],
   },
   {
     name: "memories",
     summary:
-      "列出、搜索、查看、添加、修改或物理删除记忆（对话、工作、编码三个场景）。add 和 App 的「添加记忆」是同一个入口；delete 不可逆，需 --yes。",
+      "列出/查看记忆，或生成并显式确认带版本与 request identity 的治理操作计划。",
     usage:
-      "memhub memories list [--scene <all|chat|working|coding>] [--source <id>] [--query <text>] [--status <state>] [--offset <n>] [--limit <n>] [--json]\n            memhub memories show <memory-id> [--kind <kind>] [--variant <variant>] [--json]\n            memhub memories add <text> [--request-id <uuid>] [--json]\n            memhub memories add --content-file <path> [--request-id <uuid>] [--json]\n            memhub memories add-status <request-id> [--json]\n            memhub memories update <memory-id> --content-file <path> [--kind <kind>] [--variant <variant>] [--task <text>] [--json]\n            memhub memories delete <memory-id> [--kind <kind>] [--variant <variant>] [--yes] [--json]",
+      "memhub memories list [--query <text>] [--query-file <path>] [--status <state>] [--source <id>] [--offset <n>] [--limit <n>] [--json]\n            memhub memories show <memory-id> [--json]\n            memhub memories plan add --content-file <path> --scope <scope> --evidence <id> [--kind <kind>] [--json]\n            memhub memories plan <correct|delete|scope> <memory-id> [--content-file <path>] [--scope <scope>] [--json]\n            memhub memories apply --plan-file <path> --confirm [--content-file <path>] [--json]",
     options: [
-      {
-        flag: "--scene <all|chat|working|coding>",
-        summary: "只列一个场景，默认 all。working/coding 列的是该场景的经验。",
-      },
-      { flag: "--source <id>", summary: "只列某个来源写入的记忆。" },
       {
         flag: "--query <text>",
         summary:
-          "关键词搜索（只搜 active 记忆，在最相关的一批里匹配所有关键词，输出 search_window 时表示可能少计）。",
+          "按内容过滤；会出现在 shell 历史里，敏感词请改用 --query-file。",
+      },
+      {
+        flag: "--query-file <path>",
+        summary: "从文件读取过滤词，避免查询内容进入命令行历史。",
       },
       {
         flag: "--status <state>",
-        summary: `记忆状态，取值 ${MEMORY_STATUSES.join("、")}，默认 active。`,
+        summary: `记忆状态，取值 ${MEMORY_STATUSES.join("、")}。`,
       },
+      { flag: "--source <id>", summary: "只看某个来源产生的记忆。" },
       { flag: "--offset <n>", summary: "跳过前 n 条，默认 0。" },
       {
         flag: "--limit <n>",
         summary: "本页最多返回多少条，默认 100，上限 500。",
       },
-      KIND_OPTION,
-      VARIANT_OPTION,
       {
         flag: "--content-file <path>",
         summary:
-          "从有界普通文件读取正文：add 的新记忆（≤12000 字），或 update 的新内容（经验为 solution）。",
+          "从有界普通文件读取新增/纠正正文；计划只保存摘要，执行时再次校验。",
       },
       {
-        flag: "--task <text>",
-        summary: "update 经验（--kind experience）时同时改写 task。",
+        flag: "--kind <chat|working|coding|schema|intention>",
+        summary: "新增记忆的类型，默认 chat。",
       },
       {
-        flag: "--request-id <uuid>",
-        summary:
-          "add 的幂等键；用同一个 id 重试只会读回第一次的结果，不会重复添加。不给时自动生成并输出。",
+        flag: "--scope <scope>",
+        summary: "记忆使用范围，可重复；private 必须独占。",
       },
-      DESTRUCTIVE_CONFIRM_OPTION,
+      {
+        flag: "--evidence <id>",
+        summary: "新增记忆引用的 Evidence ID，可重复。",
+      },
+      PLAN_FILE_OPTION,
+      EXPLICIT_CONFIRM_OPTION,
       JSON_OPTION,
     ],
-    exit_codes: RUNTIME_EXITS,
+    exit_codes: [EXIT_OK, EXIT_FAILED, EXIT_USAGE, EXIT_RUNTIME_STOPPED],
   },
   {
-    name: "profile",
-    summary: "读取 SDK 组装后的用户长期画像（L0 + 已启用的长期画像补充）。",
-    usage: "memhub profile [--json]",
-    options: [JSON_OPTION],
-    exit_codes: RUNTIME_EXITS,
-  },
-  {
-    name: "graph-width",
+    name: "calls",
     summary:
-      "嵌入维度变化、图谱宽度不匹配时的处置决定。keep_existing 与 export_first 直接执行；rebuild_with_new 会归档旧图谱并重建，需 --yes。",
+      "清除本机调用记录；不可逆删除，默认只出计划，必须显式 --confirm 才执行。",
     usage:
-      "memhub graph-width --decision <keep_existing|export_first|rebuild_with_new> [--yes] [--json]",
+      "memhub calls clear --event <id> [--event <id> ...] [--confirm] [--json]\n            memhub calls clear --all [--confirm] [--json]",
+    options: [
+      {
+        flag: "--event <id>",
+        summary: "要清除的调用记录事件 ID，可重复，最多 100 条。",
+      },
+      {
+        flag: "--all",
+        summary: "清除全部调用记录；与 --event 互斥。",
+      },
+      DIRECT_CONFIRM_OPTION,
+      JSON_OPTION,
+    ],
+    exit_codes: [EXIT_OK, EXIT_FAILED, EXIT_USAGE, EXIT_RUNTIME_STOPPED],
+  },
+  {
+    name: "import-file",
+    summary:
+      "上传、提交或丢弃一份历史导入文件；提交与丢弃默认只出计划，需 --confirm。",
+    usage:
+      "memhub import-file upload --file <path> [--kind raw_conversation|memory_content] [--confirm] [--json]\n            memhub import-file commit <upload-id> [--confirm] [--json]\n            memhub import-file discard <upload-id> [--confirm] [--json]",
+    options: [
+      {
+        flag: "--file <path>",
+        summary:
+          "要上传的普通文件（非符号链接，<=128 MiB，.zip/.json/.md/.txt）。",
+      },
+      {
+        flag: "--kind <kind>",
+        summary:
+          "输入类型，默认 raw_conversation；memory_content 用于记忆正文。",
+      },
+      DIRECT_CONFIRM_OPTION,
+      JSON_OPTION,
+    ],
+    exit_codes: [EXIT_OK, EXIT_FAILED, EXIT_USAGE, EXIT_RUNTIME_STOPPED],
+  },
+  {
+    name: "notes",
+    summary:
+      "端内新增记忆（memory-notes）：从普通文件新增，或显式确认后处理已有笔记。",
+    usage:
+      "memhub notes add --content-file <path> [--json]\n            memhub notes apply --plan-file <path> --content-file <path> --confirm [--json]\n            memhub notes process <note-id> [--confirm] [--json]",
+    options: [
+      {
+        flag: "--content-file <path>",
+        summary: "从有界普通文件读取新增正文；计划只保存摘要，执行时重新校验。",
+      },
+      PLAN_FILE_OPTION,
+      DIRECT_CONFIRM_OPTION,
+      JSON_OPTION,
+    ],
+    exit_codes: [EXIT_OK, EXIT_FAILED, EXIT_USAGE, EXIT_RUNTIME_STOPPED],
+  },
+  {
+    name: "extraction",
+    summary: "设置提取窗口；默认只出计划，--confirm 后才写入。",
+    usage: "memhub extraction set --window <3m|6m|1y|all> [--confirm] [--json]",
+    options: [
+      {
+        flag: "--window <preset>",
+        summary: "提取窗口预设：3m、6m、1y 或 all。",
+      },
+      DIRECT_CONFIRM_OPTION,
+      JSON_OPTION,
+    ],
+    exit_codes: [EXIT_OK, EXIT_FAILED, EXIT_USAGE, EXIT_RUNTIME_STOPPED],
+  },
+  {
+    name: "graph",
+    summary: "图谱宽度不匹配时的用户决定；默认只出计划，--confirm 后才执行。",
+    usage:
+      "memhub graph width --decision <keep_existing|rebuild_with_new|export_first> [--confirm] [--json]",
     options: [
       {
         flag: "--decision <decision>",
         summary:
-          "keep_existing（保持现有图谱）、export_first（先导出）、rebuild_with_new（导出后归档旧图谱并按新维度重建）。",
-      },
-      {
-        ...DESTRUCTIVE_CONFIRM_OPTION,
-        summary: "rebuild_with_new 必须加；其它决定不需要。",
+          "keep_existing（保持）、export_first（先导出）、rebuild_with_new（导出后重建）。",
       },
+      DIRECT_CONFIRM_OPTION,
       JSON_OPTION,
     ],
-    exit_codes: RUNTIME_EXITS,
+    exit_codes: [EXIT_OK, EXIT_FAILED, EXIT_USAGE, EXIT_RUNTIME_STOPPED],
   },
   {
     name: "host",
@@ -468,12 +549,12 @@ export const COMMANDS: readonly CommandDescriptor[] = [
       },
       JSON_OPTION,
     ],
-    exit_codes: RUNTIME_EXITS,
+    exit_codes: [EXIT_OK, EXIT_FAILED, EXIT_USAGE, EXIT_RUNTIME_STOPPED],
   },
   {
     name: "recall",
     summary:
-      "从原始对话与已沉淀记忆统一检索上下文；本地只读，不调用模型、不触发补索引。文本输出标明每条是「原始对话摘录」还是「记忆」（JSON 里是 kind: raw|memory）。",
+      "从当前授权的原文与治理记忆统一检索上下文；本地只读，不调用模型、不触发补索引。",
     usage:
       "memhub recall <query> [--kind <raw|memory>] [--source <id>] [--limit <n>] [--character-budget <n>] [--timeout-ms <n>] [--json]\n            memhub recall --query-file <path> [...]\n            memhub recall --stdin [...]",
     options: [
@@ -504,21 +585,21 @@ export const COMMANDS: readonly CommandDescriptor[] = [
       },
       JSON_OPTION,
     ],
-    exit_codes: RUNTIME_EXITS,
+    exit_codes: [EXIT_OK, EXIT_FAILED, EXIT_USAGE, EXIT_RUNTIME_STOPPED],
   },
   {
     name: "service-plan",
     summary: "生成用户级服务计划；只输出计划，不写文件也不执行命令。",
     usage: `memhub service-plan ${SERVICE_USAGE}`,
     options: SERVICE_OPTIONS,
-    exit_codes: [EXIT_OK, EXIT_USAGE, EXIT_PLAN_BLOCKED],
+    exit_codes: [EXIT_OK, EXIT_PLAN_BLOCKED],
   },
   {
     name: "service-install",
     summary: "预览用户级服务安装；只有 --yes 才写入服务文件并注册。",
     usage: `memhub service-install ${SERVICE_USAGE} [--yes]`,
     options: [...SERVICE_OPTIONS, CONFIRM_OPTION],
-    exit_codes: [EXIT_OK, EXIT_FAILED, EXIT_USAGE, EXIT_PLAN_BLOCKED],
+    exit_codes: [EXIT_OK, EXIT_FAILED, EXIT_PLAN_BLOCKED],
   },
   {
     name: "service-uninstall",
@@ -526,15 +607,15 @@ export const COMMANDS: readonly CommandDescriptor[] = [
       "预览用户级服务卸载；只有 --yes 才注销并删除逐字匹配的受管服务文件，不删数据。",
     usage: `memhub service-uninstall ${SERVICE_USAGE} [--yes]`,
     options: [...SERVICE_OPTIONS, CONFIRM_OPTION],
-    exit_codes: [EXIT_OK, EXIT_FAILED, EXIT_USAGE, EXIT_PLAN_BLOCKED],
+    exit_codes: [EXIT_OK, EXIT_FAILED, EXIT_PLAN_BLOCKED],
   },
   {
     name: "install",
     summary:
-      "预览发行目录安装、memhub/memhub-cli/one-memory 短链接、PATH 条目与用户服务计划；只有 --yes 才执行。记忆数据迁移开始前失败会回滚；迁移开始后失败保留新版本、拒绝启动，并输出迁移日志与反馈地址。",
+      "预览发行目录安装、memhub/memhub-cli/one-memory 短链接、PATH 条目与用户服务计划；只有 --yes 才执行并在失败时回滚。",
     usage: `memhub install ${INSTALL_USAGE}`,
     options: INSTALL_OPTIONS,
-    exit_codes: [EXIT_OK, EXIT_FAILED, EXIT_USAGE, EXIT_PLAN_BLOCKED],
+    exit_codes: [EXIT_OK, EXIT_FAILED, EXIT_PLAN_BLOCKED],
   },
   {
     name: "uninstall",
@@ -547,31 +628,24 @@ export const COMMANDS: readonly CommandDescriptor[] = [
   {
     name: "upgrade",
     summary:
-      "预览升级；只有 --yes 才切换受管版本并重启服务，不删数据。记忆数据迁移开始前失败会恢复旧版本；迁移开始后失败保留新版本、拒绝启动，并输出迁移日志与反馈地址（不会回滚到旧版本）。",
+      "预览升级；只有 --yes 才切换受管版本并重启服务，失败时恢复旧版本，不删数据。",
     usage: `memhub upgrade ${INSTALL_USAGE}`,
     options: INSTALL_OPTIONS,
-    exit_codes: [EXIT_OK, EXIT_FAILED, EXIT_USAGE, EXIT_PLAN_BLOCKED],
+    exit_codes: [EXIT_OK, EXIT_FAILED, EXIT_PLAN_BLOCKED],
   },
   {
     name: "delete-data",
     summary:
-      "删除 MemHub 数据目录（记忆、来源、配置），不可逆。这是唯一会删除数据的命令；uninstall 不会。需要 Runtime 已停止；不加参数时只预览要删除的目录；删除需要 --yes 并用 --confirm 再写一遍同一个目录。",
+      "独立、二次确认地删除 One Memory Home（数据）。这是唯一会删除数据的命令；uninstall 不会。默认只出预览；需 Runtime 已停止，并显式 --confirm <path> 复述该目录。",
     usage:
       "memhub delete-data [--data-dir <path>] [--yes --confirm <path>] [--json]",
     options: [
-      {
-        flag: "--data-dir <path>",
-        summary: "要删除的数据目录绝对路径；默认当前使用的数据目录。",
-      },
-      {
-        ...DESTRUCTIVE_CONFIRM_OPTION,
-        summary:
-          "删除时必须加，且要同时给出 --confirm <path>；不加时只预览，exit 0。",
-      },
+      DATA_DIR_OPTION,
+      CONFIRM_OPTION,
       {
         flag: "--confirm <path>",
         summary:
-          "删除时必须加：再写一遍要删除的数据目录，与预览中的目录完全一致才执行。",
+          "第二次确认：逐字复述预览里的数据目录；缺少它时即使 --yes 也不删除。",
       },
       JSON_OPTION,
     ],
@@ -583,149 +657,113 @@ export const COMMANDS: readonly CommandDescriptor[] = [
       "onboarding reset 回到首次运行的引导流程。只清除引导完成状态：不删记忆数据，也不需要卸载重装。",
     usage: "memhub onboarding reset [--json]",
     options: [JSON_OPTION],
-    exit_codes: RUNTIME_EXITS,
+    exit_codes: [EXIT_OK, EXIT_FAILED, EXIT_USAGE],
   },
   {
     name: "help",
     summary: "显示总帮助或单个命令的用法。",
     usage: "memhub help [command] [--json]",
     options: [JSON_OPTION],
-    exit_codes: [EXIT_OK, EXIT_USAGE],
+    exit_codes: [EXIT_OK],
   },
   {
     name: "version",
     summary: "显示 CLI 版本。",
     usage: "memhub version [--json]",
     options: [JSON_OPTION],
-    exit_codes: [EXIT_OK, EXIT_USAGE],
+    exit_codes: [EXIT_OK],
   },
   {
-    name: "scan-roots",
+    name: "path",
     summary:
-      "查看或登记被扫描的目录（scan roots）。add/remove 直接执行。（旧名 path 仍可用。）",
+      "查看或登记被扫描的目录（scan roots）。list 只读；add/remove 预览后加 --yes 才提交；均已接入 Runtime 的 scan-roots 端点。",
     usage:
-      "memhub scan-roots list [--json]\n" +
-      "            memhub scan-roots add --root <path> [--source <id>] [--no-recursive] [--json]\n" +
-      "            memhub scan-roots remove --root <path> [--json]",
-    options: [
-      { flag: "--root <path>", summary: "要登记或移除的目录。" },
-      {
-        flag: "--source <id>",
-        summary: "把目录绑定到某个来源；不给时由 Runtime 自动识别。",
-      },
-      { flag: "--no-recursive", summary: "只扫描该目录本身，不进入子目录。" },
-      JSON_OPTION,
-    ],
-    exit_codes: RUNTIME_EXITS,
+      "memhub path list [--json]\n" +
+      "            memhub path add --root <path> [--source <id>] [--no-recursive] [--yes]\n" +
+      "            memhub path remove --root <path> [--yes]",
+    options: [DATA_DIR_OPTION, JSON_OPTION, CONFIRM_OPTION],
+    exit_codes: [EXIT_OK, EXIT_USAGE, EXIT_FAILED, EXIT_PLAN_BLOCKED],
   },
   {
     name: "adapter",
     summary:
-      "查看 Harness Adapter 的就绪状态与最近一次探测结果（list），或现场探测某个来源（probe --source <id>）；两者均为只读。",
+      "查看 Harness Adapter 的就绪状态与最近一次探测结果（list），或现场探测某个来源（probe --source <id>）；两者均为只读，已接入 Runtime 的 adapters/探测端点。",
     usage:
       "memhub adapter list [--json]\n" +
       "            memhub adapter probe --source <id> [--json]",
-    options: [
-      { flag: "--source <id>", summary: "probe 的目标来源。" },
-      JSON_OPTION,
-    ],
-    exit_codes: RUNTIME_EXITS,
+    options: [DATA_DIR_OPTION, JSON_OPTION],
+    exit_codes: [EXIT_OK, EXIT_USAGE, EXIT_FAILED],
   },
   {
     name: "scan",
     summary:
-      "立即增量扫描一个已连接并开启同步的来源，返回导入任务（与 jobs start --operation sync 相同）。接入全部来源请用 sources connect --all-detected --import。",
-    usage: "memhub scan --source <id> [--json]",
+      "立即扫描；默认只输出计划，加 --yes 才真正执行。指定 --source 扫描单个来源，--all 一次扫描/导入全部已检测来源（Runtime 按来源寻址，不接受裸路径）。",
+    usage:
+      "memhub scan [--source <id>] [--full] [--yes] [--json]\n            memhub scan --all [--yes] [--json]",
     options: [
       {
         flag: "--source <id>",
-        summary: "要扫描的来源。",
+        summary: "按单个来源扫描；与 --all 互斥。",
       },
+      {
+        flag: "--all",
+        summary:
+          "处理全部 location_state=found 的来源，按来源逐条回执；部分成功返回非 0。",
+      },
+      {
+        flag: "--full",
+        summary: "忽略既有游标做全量重扫；默认只读取增量。",
+      },
+      DATA_DIR_OPTION,
       JSON_OPTION,
+      CONFIRM_OPTION,
     ],
-    exit_codes: RUNTIME_EXITS,
+    exit_codes: [EXIT_OK, EXIT_USAGE, EXIT_FAILED, EXIT_PLAN_BLOCKED],
   },
   {
     name: "write",
     summary:
-      "提交一段 OpenAI 格式的对话（messages）到写入队列，异步加工成记忆；或按 request id 查询状态。request id 是幂等键：不给时自动生成并输出，重试请带上同一个。新增一条结论式记忆请用 memories add。",
+      "提交一次记忆写入，返回可查询的 request id；写入异步完成，不可重复提交。",
     usage:
-      "memhub write submit --messages-file <path> --session <id> [--source <id>] [--request-id <id>] [--memory-at <RFC3339>] [--live] [--json]\n            memhub write status <request-id> [--json]",
-    options: [
-      {
-        flag: "--messages-file <path>",
-        summary:
-          "OpenAI messages 数组（或 {messages:[…]}），1..200 条，role 为 user/assistant/tool，至少一条 user。",
-      },
-      { flag: "--session <id>", summary: "会话 ID。" },
-      { flag: "--source <id>", summary: "来源应用，默认 memhub-cli。" },
-      {
-        flag: "--request-id <id>",
-        summary:
-          "幂等键：同 id 同内容不会重复入队，同 id 不同内容被拒绝（409）。",
-      },
-      { flag: "--memory-at <RFC3339>", summary: "对话发生时间，必须带时区。" },
-      { flag: "--live", summary: "优先处理。" },
-      JSON_OPTION,
-    ],
-    exit_codes: RUNTIME_EXITS,
+      "memhub write --session <id> --from <round> --to <round> --evidence <id> [--evidence <id>...] [--live] [--json]",
+    options: [DATA_DIR_OPTION, JSON_OPTION],
+    exit_codes: [EXIT_OK, EXIT_USAGE, EXIT_FAILED],
+  },
+  {
+    name: "task",
+    summary: "查询写入任务状态；unknown 表示结果待定，不可据此重发。",
+    usage: "memhub task --id <request-id> [--json]",
+    options: [DATA_DIR_OPTION, JSON_OPTION],
+    exit_codes: [EXIT_OK, EXIT_USAGE, EXIT_FAILED],
   },
   {
     name: "backup",
     summary:
-      "备份与恢复主库（来源、写入队列、配置）。注意：不包含记忆本身——SDK 记忆库 hy-memory/ 不在备份里，restore 也不会替换它。create 的目标要放在 <数据目录>/backups/ 下才能被 restore 使用；restore 覆盖现有主库，需 Runtime 已停止，并加 --yes 与 --confirm <同一个备份路径>。",
+      "备份与恢复 MemHub 数据（两阶段）。create 调用 Runtime 的备份端点；restore 会覆盖现有数据，要求 Runtime 已停止且 `--confirm` 逐字重复 `--source`，随后由非 Runtime 维护态 Core 完成受管校验、保护性备份和原子替换。",
     usage:
-      "memhub backup create --target <path> [--json]\n" +
-      "            memhub backup restore --source <path> [--yes --confirm <path>] [--json]",
+      "memhub backup create --target <path> [--yes] [--json]\n" +
+      "            memhub backup restore --source <path> --yes --confirm <path> [--json]",
     options: [
-      {
-        flag: "--target <path>",
-        summary: "create 的备份文件路径，必须在数据目录内。",
-      },
-      {
-        flag: "--source <path>",
-        summary:
-          "restore 的备份文件，必须是 <数据目录>/backups/ 下的受管备份。",
-      },
-      {
-        ...DESTRUCTIVE_CONFIRM_OPTION,
-        summary:
-          "restore 必须加，且要同时给出 --confirm <path>；create 不需要。",
-      },
+      DATA_DIR_OPTION,
+      JSON_OPTION,
+      CONFIRM_OPTION,
       {
         flag: "--confirm <path>",
-        summary:
-          "restore 必须加：再写一遍 --source 的备份路径，完全一致才执行。",
+        summary: "restore 要求逐字重复 --source 路径；不一致时不做任何改动。",
       },
-      JSON_OPTION,
     ],
-    exit_codes: [...RUNTIME_EXITS, EXIT_PLAN_BLOCKED],
+    exit_codes: [EXIT_OK, EXIT_USAGE, EXIT_FAILED, EXIT_PLAN_BLOCKED],
   },
   {
     name: "ui",
     summary:
-      "用系统默认浏览器打开 Runtime 托管的 Web Console：先向 Core 换取一次性 loopback 登录码，再交给系统浏览器由 Core 置 HttpOnly/SameSite=Strict session；CLI 不向浏览器暴露裸 Core token。Runtime 未运行时 exit 3；Core 未提供该合同时如实返回 ui_session_contract_unavailable（exit 4）。",
+      "用系统默认浏览器打开 Runtime 托管的 Web Console：先向 Core 换取一次性 loopback 登录码，再交给系统浏览器由 Core 置 HttpOnly/SameSite=Strict session；CLI 不向浏览器暴露裸 Core token。Core 未提供该合同时如实返回 ui_session_contract_unavailable（exit 4）。",
     usage: "memhub ui [--json]",
     options: [JSON_OPTION],
-    exit_codes: [...RUNTIME_EXITS, EXIT_PLAN_BLOCKED],
+    exit_codes: [EXIT_OK, EXIT_FAILED, EXIT_USAGE, EXIT_PLAN_BLOCKED],
   },
 ];
 
-/** Old names that still run but are not listed: `path` → `scan-roots`,
- * `task` → `write status`, `graph width` → `graph-width`. */
-export const HIDDEN_COMMAND_ALIASES: Readonly<Record<string, string>> = {
-  path: "scan-roots",
-  task: "write",
-  graph: "graph-width",
-};
-
 export function findCommand(name: string): CommandDescriptor | undefined {
   return COMMANDS.find((command) => command.name === name);
 }
-
-/** A listed command, or the command a hidden alias now runs as. */
-export function findCommandOrAlias(
-  name: string,
-): CommandDescriptor | undefined {
-  return findCommand(HIDDEN_COMMAND_ALIASES[name] ?? name);
-}

memhub/apps/cli/src/command-contract.test.ts

@@ -69,14 +69,20 @@ const COMMANDS = [
   "doctor",
   "logs",
   "init",
+  "setup",
   "sources",
   "sync",
   "progress",
   "jobs",
+  "processing",
   "models",
   "memories",
-  "profile",
-  "graph-width",
+  // C6 App BLOCK (25f4ecf): UI write operations that had no CLI equivalent.
+  "calls",
+  "import-file",
+  "notes",
+  "extraction",
+  "graph",
   "host",
   "recall",
   "service-plan",
@@ -89,20 +95,19 @@ const COMMANDS = [
   "onboarding",
   "help",
   "version",
-  "scan-roots",
+  // A6 product commands. Appended, not inserted: the catalog is a stable
+  // contract, so existing names must not shift position.
+  "path",
   "adapter",
   "scan",
   "write",
+  "task",
   "backup",
+  // `ui` is declared but blocked on a Core session contract; it is listed so
+  // `help` documents it and the blocked shape is machine-readable.
   "ui",
 ] as const;
 
-/** Old names that still run and still answer `--help`, but are not listed. */
-const HIDDEN_ALIASES = [
-  ["path", "scan-roots"],
-  ["task", "write"],
-] as const;
-
 describe("CLI-22 shared output contract", () => {
   describe("help", () => {
     it.each([["help"], ["--help"], ["-h"]])(
@@ -143,56 +148,6 @@ describe("CLI-22 shared output contract", () => {
       },
     );
 
-    it.each(HIDDEN_ALIASES)(
-      "documents the hidden alias %s as %s and keeps it out of the listing",
-      async (alias, target) => {
-        const streams = captureStreams();
-        try {
-          expect(await run(["help", alias], {})).toBe(0);
-          expect(await run([alias, "--help"], {})).toBe(0);
-        } finally {
-          streams.restore();
-        }
-        expect(streams.stdout()).toContain(`${PRODUCT} ${target}`);
-        const listing = captureStreams();
-        try {
-          expect(await run(["help", "--json"], {})).toBe(0);
-        } finally {
-          listing.restore();
-        }
-        const names = JSON.parse(listing.stdout()).commands.map(
-          (entry: { name: string }) => entry.name,
-        );
-        expect(names).not.toContain(alias);
-      },
-    );
-
-    it("lists no removed command", async () => {
-      const streams = captureStreams();
-      try {
-        expect(await run(["help", "--json"], {})).toBe(0);
-      } finally {
-        streams.restore();
-      }
-      const catalog = streams.stdout();
-      for (const removed of [
-        '"name":"setup"',
-        '"name":"notes"',
-        '"name":"calls"',
-        '"name":"graph"',
-        "--plan-file",
-        "probe-plan",
-        "probe-receipt",
-        "models configure",
-        "sources import",
-        "--full-rescan",
-        "--dry-run",
-        "--full]",
-      ]) {
-        expect(catalog).not.toContain(removed);
-      }
-    });
-
     it("never executes the documented command", async () => {
       for (const command of COMMANDS) {
         for (const argv of [
@@ -248,63 +203,27 @@ describe("CLI-22 shared output contract", () => {
       expect(payload.commands).toBeUndefined();
     });
 
-    it("documents the one --yes convention for destructive commands", async () => {
-      const general = captureStreams();
-      try {
-        expect(await run(["help"], {})).toBe(0);
-      } finally {
-        general.restore();
-      }
-      expect(general.stdout()).toContain("确认约定");
-      for (const [command, usage] of [
-        [
-          "backup",
-          "memhub backup restore --source <path> [--yes --confirm <path>]",
-        ],
-        ["memories", "memhub memories delete <memory-id>"],
-        ["models", "memhub models remove <profile-id> [--yes]"],
-        [
-          "delete-data",
-          "memhub delete-data [--data-dir <path>] [--yes --confirm <path>]",
-        ],
-        ["graph-width", "[--yes]"],
-      ] as const) {
-        const streams = captureStreams();
-        try {
-          expect(await run(["help", command], {})).toBe(0);
-        } finally {
-          streams.restore();
-        }
-        expect(streams.stdout()).toContain(usage);
-        // Only the two commands with no way back repeat the target path.
-        if (command !== "backup" && command !== "delete-data") {
-          expect(streams.stdout()).not.toContain("--confirm <path>");
-        }
-      }
-    });
-
-    it("says backup does not include the memories themselves", async () => {
+    it("documents the destructive restore confirmation explicitly", async () => {
       const streams = captureStreams();
       try {
         expect(await run(["help", "backup"], {})).toBe(0);
       } finally {
         streams.restore();
       }
-      expect(streams.stdout()).toContain("不包含记忆本身");
+      expect(streams.stdout()).toContain(
+        "memhub backup restore --source <path> --yes --confirm <path>",
+      );
+      expect(streams.stdout()).toContain("逐字重复 --source");
     });
 
-    it("does not promise a rollback after the migration started", async () => {
-      for (const command of ["install", "upgrade"]) {
-        const streams = captureStreams();
-        try {
-          expect(await run(["help", command], {})).toBe(0);
-        } finally {
-          streams.restore();
-        }
-        expect(streams.stdout()).toContain("迁移开始后失败保留新版本");
-        expect(streams.stdout()).not.toContain("失败时恢复旧版本");
-        expect(streams.stdout()).not.toContain("失败时回滚");
+    it("does not attach restore's confirmation flag to path", async () => {
+      const streams = captureStreams();
+      try {
+        expect(await run(["help", "path"], {})).toBe(0);
+      } finally {
+        streams.restore();
       }
+      expect(streams.stdout()).not.toContain("--confirm <path>");
     });
   });
 
@@ -628,23 +547,22 @@ describe("documented commands", () => {
     models: [
       "list",
       "show",
-      "add",
-      "test",
+      "plan",
+      "configure",
       "receipt",
-      "edit",
-      "activate",
+      "probe-plan",
+      "probe",
+      "probe-receipt",
       "remove",
     ],
     // Source processing is one Freeze/Thaw switch under `sync`; the obsolete
     // independent read/write `sources access` command must not return here.
-    sources: ["list", "connect", "receipt"],
+    sources: ["list", "import", "receipt"],
     jobs: ["list", "show", "start", "<pause|resume|cancel>"],
     // `sync <pause|resume>` is documented as one alternation, so it is
     // checked as an entry rather than as two literal subcommands.
     sync: ["status", "<pause|resume>"],
-    memories: ["list", "show", "add", "add-status", "update", "delete"],
-    "scan-roots": ["list", "add", "remove"],
-    write: ["submit", "status"],
+    memories: ["list", "show", "plan", "apply"],
     host: ["list", "status", "install", "uninstall", "sync"],
   };
 

memhub/apps/cli/src/context-search.test.ts

@@ -43,35 +43,61 @@ const ATTACHED = {
 };
 
 const RESPONSE = {
-  schema_version: 2,
+  schema_version: 1,
   request_id: "context-request-1",
   state: "grounded",
+  paths: {
+    raw: {
+      status: "ok",
+      reason: null,
+      elapsed_ms: 2,
+      returned_count: 1,
+      truncated: false,
+      truncated_by: [],
+    },
+    memory: {
+      status: "ok",
+      reason: null,
+      elapsed_ms: 3,
+      returned_count: 1,
+      truncated: false,
+      truncated_by: [],
+    },
+  },
   items: [
     {
       kind: "raw",
-      raw_id: "raw-1",
-      content: "Synthetic raw citation.",
-      source: "codex",
-      session_id: "session-1",
-      memory_at: "2026-09-19T00:00:00Z",
-      score: 0.8,
+      source_id: "codex",
+      conversation_id: "conversation-1",
+      anchor_evidence_id: "evidence-1",
+      messages: [
+        {
+          evidence_id: "evidence-1",
+          revision: 1,
+          role: "user",
+          written_by: "user",
+          created_at: "2026-09-19T00:00:00Z",
+          text: "Synthetic raw citation.",
+          truncated: false,
+        },
+      ],
       truncated: false,
     },
     {
       kind: "memory",
       memory_id: "memory-1",
-      content: "Synthetic SDK memory.",
-      layer: "l2_fact",
-      status: "active",
-      source: "codex",
+      revision: 2,
+      content: "Synthetic governed memory.",
+      memory_kind: "working",
       updated_at: "2026-09-19T00:00:01Z",
-      score: 0.7,
+      evidence_ids: ["evidence-1"],
       truncated: false,
     },
   ],
-  used_characters: 44,
+  used_characters: 49,
   truncated: false,
   total_ms: 5,
+  adoption: "unknown",
 };
 
 beforeEach(() => {
@@ -89,17 +115,42 @@ beforeEach(() => {
 });
 
 describe("unified context search", () => {
-  it("accepts an empty raw item in a valid partial context response", async () => {
+  it("accepts an empty tool message in a valid partial context response", async () => {
     transport.post.mockResolvedValue({
       status: 200,
       data: {
         ...RESPONSE,
         state: "partial",
+        paths: {
+          raw: {
+            ...RESPONSE.paths.raw,
+            status: "degraded",
+            reason: "lexical_only",
+            returned_count: 1,
+          },
+          memory: {
+            ...RESPONSE.paths.memory,
+            status: "empty",
+            returned_count: 0,
+          },
+        },
         items: [
           {
-            ...RESPONSE.items[0],
-            source: "workbuddy",
-            content: "",
+            kind: "raw",
+            source_id: "workbuddy",
+            conversation_id: "conversation-1",
+            anchor_evidence_id: "evidence-1",
+            messages: [
+              {
+                evidence_id: "evidence-1",
+                revision: 1,
+                role: "tool",
+                written_by: "tool",
+                created_at: "2026-10-05T20:48:12Z",
+                text: "",
+                truncated: true,
+              },
+            ],
             truncated: true,
           },
         ],
@@ -114,9 +165,8 @@ describe("unified context search", () => {
       streams.restore();
     }
     expect(JSON.parse(streams.stdout())).toMatchObject({
-      schema_version: 2,
       state: "partial",
-      items: [{ kind: "raw", content: "" }],
+      items: [{ kind: "raw", messages: [{ text: "" }] }],
     });
   });
 
@@ -128,26 +178,12 @@ describe("unified context search", () => {
       streams.restore();
     }
     const output = streams.stdout();
-    expect(output).toContain("Synthetic SDK memory.");
+    expect(output).toContain("Synthetic governed memory.");
     expect(output).toContain("Synthetic raw citation.");
-    expect(output).not.toMatch(/^- raw |memory-1|raw-1|采用状态/m);
+    expect(output).not.toMatch(/^- raw |memory-1|evidence-1|采用状态/m);
   });
 
-  it("labels raw hits as original-conversation excerpts, not memories", async () => {
-    const streams = captureStreams();
-    try {
-      expect(await run(["recall", "synthetic question"])).toBe(0);
-    } finally {
-      streams.restore();
-    }
-    const output = streams.stdout();
-    expect(output).toContain(
-      "- [原始对话摘录 · codex] Synthetic raw citation.",
-    );
-    expect(output).toContain("- [记忆] Synthetic SDK memory.");
-  });
-
-  it("queries the SDK context endpoint directly and preserves item ids", async () => {
+  it("queries the current read-only context endpoint and preserves citations", async () => {
     const streams = captureStreams();
     try {
       expect(
@@ -173,7 +209,7 @@ describe("unified context search", () => {
       streams.restore();
     }
     expect(transport.post).toHaveBeenCalledWith(
-      "/api/v2/context/search",
+      "/api/v1/context/search",
       {
         query: "synthetic question",
         kinds: ["raw", "memory"],
@@ -186,18 +222,12 @@ describe("unified context search", () => {
     );
     const output = JSON.parse(streams.stdout());
     expect(output).toMatchObject({
-      schema_version: 2,
       state: "grounded",
       request_id: "context-request-1",
+      adoption: "unknown",
     });
-    expect(output).not.toHaveProperty("paths");
-    expect(output.items[0]).toMatchObject({ kind: "raw", raw_id: "raw-1" });
-    expect(output.items[1]).toMatchObject({
-      kind: "memory",
-      memory_id: "memory-1",
-      layer: "l2_fact",
-    });
-    // No authority pre-query: released Core always serves the SDK data plane.
+    expect(output.items[0].messages[0].evidence_id).toBe("evidence-1");
+    expect(output.items[1].evidence_ids).toEqual(["evidence-1"]);
     expect(transport.get).not.toHaveBeenCalled();
     expect(transport.put).not.toHaveBeenCalled();
     expect(transport.patch).not.toHaveBeenCalled();
@@ -212,8 +242,19 @@ describe("unified context search", () => {
       status: 200,
       data: {
         ...RESPONSE,
+        paths: {
+          ...RESPONSE.paths,
+          raw: {
+            status: "not_requested",
+            reason: "not_requested",
+            elapsed_ms: 0,
+            returned_count: 0,
+            truncated: false,
+            truncated_by: [],
+          },
+        },
         items: [RESPONSE.items[1]],
-        used_characters: 21,
+        used_characters: 26,
       },
     });
     const streams = captureStreams();
@@ -353,7 +394,29 @@ describe("unified context search", () => {
       status: 200,
       data: {
         ...RESPONSE,
-        items: [{ ...RESPONSE.items[0], content: text }],
+        paths: {
+          ...RESPONSE.paths,
+          memory: {
+            ...RESPONSE.paths.memory,
+            status: "empty",
+            returned_count: 0,
+          },
+        },
+        items: [
+          {
+            ...(RESPONSE.items[0] as Record<string, unknown>),
+            messages: [
+              {
+                ...(
+                  RESPONSE.items[0] as {
+                    messages: Array<Record<string, unknown>>;
+                  }
+                ).messages[0],
+                text,
+              },
+            ],
+          },
+        ],
         used_characters: 10,
       },
     });
@@ -366,7 +429,7 @@ describe("unified context search", () => {
     expect(JSON.parse(streams.stdout())).toMatchObject({
       state: "grounded",
       used_characters: 10,
-      items: [{ kind: "raw", content: text }],
+      items: [{ kind: "raw", messages: [{ text }] }],
     });
   });
 
@@ -378,7 +441,29 @@ describe("unified context search", () => {
       status: 200,
       data: {
         ...RESPONSE,
-        items: [{ ...RESPONSE.items[0], content: text }],
+        paths: {
+          ...RESPONSE.paths,
+          memory: {
+            ...RESPONSE.paths.memory,
+            status: "empty",
+            returned_count: 0,
+          },
+        },
+        items: [
+          {
+            ...(RESPONSE.items[0] as Record<string, unknown>),
+            messages: [
+              {
+                ...(
+                  RESPONSE.items[0] as {
+                    messages: Array<Record<string, unknown>>;
+                  }
+                ).messages[0],
+                text,
+              },
+            ],
+          },
+        ],
         used_characters: 12,
       },
     });
@@ -394,40 +479,6 @@ describe("unified context search", () => {
     });
   });
 
-  it.each([
-    [
-      "a raw item from a source that was not asked for",
-      ["--source", "codex"],
-      { ...RESPONSE.items[0], source: "cursor" },
-    ],
-    [
-      "a raw item when only memory was asked for",
-      ["--kind", "memory"],
-      RESPONSE.items[0],
-    ],
-    ["a score outside 0..1", [], { ...RESPONSE.items[1], score: 1.5 }],
-  ])("rejects %s as an invalid response", async (_label, flags, item) => {
-    transport.post.mockResolvedValue({
-      status: 200,
-      data: {
-        ...RESPONSE,
-        items: [item],
-        used_characters: Array.from(String(item.content)).length,
-      },
-    });
-    const streams = captureStreams();
-    try {
-      expect(await run(["recall", "query", ...flags, "--json"])).toBe(1);
-    } finally {
-      streams.restore();
-    }
-    expect(JSON.parse(streams.stdout())).toMatchObject({
-      schema_version: 2,
-      state: "invalid",
-      code: "response_invalid",
-    });
-  });
-
   it("reports endpoint denial without exposing the response body", async () => {
     transport.post.mockResolvedValue({
       status: 403,

memhub/apps/cli/src/context-search.ts

@@ -3,6 +3,31 @@ import { PRODUCT } from "./version.js";
 
 export const CONTEXT_QUERY_MAX_CHARACTERS = 2_000;
 const CONTEXT_KINDS = ["raw", "memory"] as const;
+const PATH_STATES = [
+  "ok",
+  "empty",
+  "not_requested",
+  "not_authorized",
+  "unavailable",
+  "degraded",
+] as const;
+const PATH_REASONS = [
+  "not_requested",
+  "permission_required",
+  "source_revoked",
+  "read_unavailable",
+  "timeout_budget",
+  "evidence_changed",
+  "memory_changed",
+  "lexical_only",
+] as const;
+const LIMIT_REASONS = [
+  "count_budget",
+  "character_budget",
+  "timeout_budget",
+  "metadata_budget",
+] as const;
+
 export interface ContextSearchInput {
   query: string;
   kinds: Array<(typeof CONTEXT_KINDS)[number]>;
@@ -12,9 +37,8 @@ export interface ContextSearchInput {
   timeout_ms: number;
 }
 
-/** The CLI's JSON document mirrors Core's SDK-native context schema v2. */
 export interface ContextSearchDocument {
-  schema_version: 2;
+  schema_version: 1;
   product: string;
   state:
     | "grounded"
@@ -23,14 +47,15 @@ export interface ContextSearchDocument {
     | "unavailable"
     | "denied"
     | "not_found"
-    | "rejected"
     | "invalid";
   code?: string;
   request_id?: string;
+  paths?: Record<string, unknown>;
   items: Array<Record<string, unknown>>;
   used_characters?: number;
   truncated?: boolean;
   total_ms?: number;
+  adoption?: "unknown";
 }
 
 export async function searchContext(
@@ -42,7 +67,7 @@ export async function searchContext(
   const validated = validateContextResponse(outcome.data, input);
   return (
     validated ?? {
-      schema_version: 2,
+      schema_version: 1,
       product: PRODUCT,
       state: "invalid",
       code: "response_invalid",
@@ -98,9 +123,6 @@ export function renderContextText(document: ContextSearchDocument): string {
   if (document.state === "unavailable") return "暂时无法查记忆，请稍后重试。\n";
   if (document.state === "denied") return "当前应用没有查记忆权限。\n";
   if (document.state === "invalid") return "查记忆返回了无法识别的结果。\n";
-  if (document.state === "rejected") {
-    return `查记忆被拒绝（${document.code}），请检查参数。\n`;
-  }
   const lines = [
     document.state === "empty"
       ? "没有查到相关记忆。"
@@ -108,14 +130,14 @@ export function renderContextText(document: ContextSearchDocument): string {
         ? "查到以下内容，部分内容还在整理中："
         : "查到以下相关内容：",
   ];
-  // A raw hit is an excerpt of an original conversation, not a distilled
-  // memory; say which one each line is so it is not read as a conclusion.
   for (const item of document.items) {
-    const label =
-      item.kind === "raw"
-        ? `[原始对话摘录 · ${String(item.source)}]`
-        : "[记忆]";
-    lines.push(`- ${label} ${String(item.content)}`);
+    if (item.kind === "memory") {
+      lines.push(`- ${String(item.content)}`);
+    } else {
+      for (const message of item.messages as Array<Record<string, unknown>>) {
+        lines.push(`- ${String(message.text)}`);
+      }
+    }
   }
   if (document.truncated) lines.push("结果已按请求预算截断。");
   return `${lines.join("\n")}\n`;
@@ -127,37 +149,84 @@ function validateContextResponse(
 ): ContextSearchDocument | null {
   const response = record(value);
   if (
-    response?.schema_version !== 2 ||
+    response?.schema_version !== 1 ||
     !oneOf(response.state, ["grounded", "empty", "partial", "unavailable"]) ||
     !boundedText(response.request_id, 64) ||
+    !record(response.paths) ||
     !Array.isArray(response.items) ||
     response.items.length > request.limit ||
     !integer(response.used_characters, 0, request.character_budget) ||
     typeof response.truncated !== "boolean" ||
-    !number(response.total_ms, 0)
+    !number(response.total_ms, 0) ||
+    response.adoption !== "unknown"
   ) {
     return null;
   }
+  const paths = response.paths as Record<string, unknown>;
+  const rawPath = validatePath(paths.raw);
+  const memoryPath = validatePath(paths.memory);
+  if (!rawPath || !memoryPath) return null;
   const requested = new Set(request.kinds);
+  if (
+    (!requested.has("raw") && rawPath.status !== "not_requested") ||
+    (!requested.has("memory") && memoryPath.status !== "not_requested")
+  ) {
+    return null;
+  }
   const items: Array<Record<string, unknown>> = [];
   let characters = 0;
   for (const itemValue of response.items) {
     const item = validateItem(itemValue, request);
     if (!item || !requested.has(item.kind as "raw" | "memory")) return null;
     items.push(item);
-    characters += characterCount(item.content);
+    characters +=
+      item.kind === "memory"
+        ? characterCount(item.content)
+        : (item.messages as Array<Record<string, unknown>>).reduce(
+            (sum, message) => sum + characterCount(message.text),
+            0,
+          );
   }
   if (characters !== response.used_characters) return null;
   if (response.state === "empty" && items.length !== 0) return null;
   return {
-    schema_version: 2,
+    schema_version: 1,
     product: PRODUCT,
     state: response.state,
     request_id: response.request_id as string,
+    paths: { raw: rawPath, memory: memoryPath },
     items,
     used_characters: response.used_characters as number,
     truncated: response.truncated,
     total_ms: response.total_ms as number,
+    adoption: "unknown",
+  };
+}
+
+function validatePath(value: unknown): Record<string, unknown> | null {
+  const path = record(value);
+  if (
+    !path ||
+    !oneOf(path.status, PATH_STATES) ||
+    !number(path.elapsed_ms, 0) ||
+    !integer(path.returned_count, 0, 20) ||
+    typeof path.truncated !== "boolean" ||
+    !enumList(path.truncated_by, LIMIT_REASONS) ||
+    !(
+      path.reason === null ||
+      path.reason === undefined ||
+      oneOf(path.reason, PATH_REASONS)
+    )
+  ) {
+    return null;
+  }
+  return {
+    status: path.status,
+    reason: path.reason ?? null,
+    elapsed_ms: path.elapsed_ms,
+    returned_count: path.returned_count,
+    truncated: path.truncated,
+    truncated_by: path.truncated_by,
   };
 }
 
@@ -166,57 +235,80 @@ function validateItem(
   request: ContextSearchInput,
 ): Record<string, unknown> | null {
   const item = record(value);
-  if (
-    !item ||
-    !oneOf(item.kind, CONTEXT_KINDS) ||
-    boundedText(item.content, 20_000, true) === null ||
-    !number(item.score, 0) ||
-    (item.score as number) > 1 ||
-    typeof item.truncated !== "boolean"
-  ) {
-    return null;
-  }
+  if (!item || !oneOf(item.kind, CONTEXT_KINDS)) return null;
   if (item.kind === "memory") {
     if (
       !boundedText(item.memory_id, 512) ||
-      boundedText(item.layer, 64, true) === null ||
-      boundedText(item.status, 32, true) === null ||
-      !optionalText(item.source, 128) ||
-      !optionalText(item.updated_at, 64)
+      !integer(item.revision, 1) ||
+      boundedText(item.content, 20_000, true) === null ||
+      boundedText(item.memory_kind, 64, true) === null ||
+      !boundedText(item.updated_at, 64) ||
+      !textList(item.evidence_ids, 128, 512) ||
+      typeof item.truncated !== "boolean"
     ) {
       return null;
     }
     return {
       kind: "memory",
       memory_id: item.memory_id,
+      revision: item.revision,
       content: item.content,
-      layer: item.layer,
-      status: item.status,
-      source: item.source ?? null,
-      updated_at: item.updated_at ?? null,
-      score: item.score,
+      memory_kind: item.memory_kind,
+      updated_at: item.updated_at,
+      evidence_ids: item.evidence_ids,
       truncated: item.truncated,
     };
   }
   if (
-    !boundedText(item.raw_id, 512) ||
-    !boundedText(item.source, 128) ||
+    !boundedText(item.source_id, 128) ||
     (request.raw_source_ids !== undefined &&
-      !request.raw_source_ids.includes(item.source as string)) ||
-    !boundedText(item.session_id, 512) ||
-    !optionalText(item.memory_at, 64)
+      !request.raw_source_ids.includes(item.source_id as string)) ||
+    !boundedText(item.conversation_id, 512) ||
+    !boundedText(item.anchor_evidence_id, 512) ||
+    !Array.isArray(item.messages) ||
+    item.messages.length < 1 ||
+    item.messages.length > 3 ||
+    typeof item.truncated !== "boolean"
+  ) {
+    return null;
+  }
+  const messages = item.messages.map(validateMessage);
+  if (messages.some((message) => message === null)) return null;
+  return {
+    kind: "raw",
+    source_id: item.source_id,
+    conversation_id: item.conversation_id,
+    anchor_evidence_id: item.anchor_evidence_id,
+    messages,
+    truncated: item.truncated,
+  };
+}
+
+function validateMessage(value: unknown): Record<string, unknown> | null {
+  const message = record(value);
+  if (
+    !message ||
+    !boundedText(message.evidence_id, 512) ||
+    !integer(message.revision, 1) ||
+    boundedText(message.role, 32, true) === null ||
+    boundedText(message.written_by, 32, true) === null ||
+    !(
+      message.created_at === null ||
+      boundedText(message.created_at, 64) !== null
+    ) ||
+    boundedText(message.text, 20_000, true) === null ||
+    typeof message.truncated !== "boolean"
   ) {
     return null;
   }
   return {
-    kind: "raw",
-    raw_id: item.raw_id,
-    content: item.content,
-    source: item.source,
-    session_id: item.session_id,
-    memory_at: item.memory_at ?? null,
-    score: item.score,
-    truncated: item.truncated,
+    evidence_id: message.evidence_id,
+    revision: message.revision,
+    role: message.role,
+    written_by: message.written_by,
+    created_at: message.created_at,
+    text: message.text,
+    truncated: message.truncated,
   };
 }
 
@@ -224,7 +316,7 @@ function failed(
   outcome: Exclude<ReadOutcome<unknown>, { state: "ok" }>,
 ): ContextSearchDocument {
   return {
-    schema_version: 2,
+    schema_version: 1,
     product: PRODUCT,
     state: outcome.state,
     code: outcome.code,
@@ -282,10 +374,27 @@ function oneOf<const T extends readonly string[]>(
   return typeof value === "string" && values.includes(value as T[number]);
 }
 
-function optionalText(value: unknown, maximum: number): boolean {
+function enumList(
+  value: unknown,
+  values: readonly string[],
+): value is string[] {
   return (
-    value === null ||
-    value === undefined ||
-    boundedText(value, maximum) !== null
+    Array.isArray(value) &&
+    value.length <= 4 &&
+    new Set(value).size === value.length &&
+    value.every((item) => oneOf(item, values))
+  );
+}
+
+function textList(
+  value: unknown,
+  maximumItems: number,
+  maximumText: number,
+): value is string[] {
+  return (
+    Array.isArray(value) &&
+    value.length <= maximumItems &&
+    new Set(value).size === value.length &&
+    value.every((item) => boundedText(item, maximumText) !== null)
   );
 }

memhub/apps/cli/src/core-client.ts

@@ -8,19 +8,15 @@ import axios from "axios";
  */
 const READ_ONLY_PATHS = [
   "/api/v1/call-events",
+  "/api/v1/home-summary",
   "/api/v1/import-jobs",
   "/api/v1/live-sync",
+  "/api/v1/memory-library",
   "/api/v1/memory-processing",
+  "/api/v1/memory-tasks",
   "/api/v1/model-profiles",
   "/api/v1/sources",
-  "/api/v2/home-summary",
-  "/api/v2/memory-library",
-  "/api/v2/user-profile",
 ] as const;
-const SDK_MEMORY_DETAIL = /^\/api\/v2\/memories\/[A-Za-z0-9][\w.-]{0,127}$/;
-/** Status of one `POST /api/v2/memories` addition, by its request id. */
-const MEMORY_ADDITION =
-  /^\/api\/v2\/memories\/additions\/[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/;
 
 /** Contract (C0, H25): the one-time loopback code exchange for `memhub ui`.
  * It is a POST because it mints a short-lived code; the CLI sends the bearer
@@ -68,10 +64,13 @@ export function createUiSessionRequest(attachment: {
   };
 }
 
+const MEMORY_DETAIL = /^\/api\/v1\/memories\/[A-Za-z0-9][\w.-]{0,127}$/;
 const IMPORT_JOB =
   /^\/api\/v1\/import-jobs\/[A-Za-z0-9][\w.-]{0,127}(?:\/issues)?$/;
 const OPERATION_RECEIPT =
   /^\/api\/v1\/(?:source-connections|model-profile-creations|model-probe-operations)\/[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/;
+const MEMORY_MUTATION_RECEIPT =
+  /^\/api\/v1\/memory-mutations\/[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/;
 /**
  * Core registers these static routes before `/{memory_id}`, so a memory whose
  * id happens to be one of them would reach a different handler: `graph`
@@ -82,15 +81,9 @@ export const RESERVED_MEMORY_SEGMENTS = ["ask", "graph"] as const;
 /** A response larger than this is refused before it is buffered. */
 const MAX_RESPONSE_BYTES = 4 * 1024 * 1024;
 
-/** `rejected` is Core refusing the request itself (400/409/422: a bad filter,
- * an ambiguous id). It is not "Core is busy" — only a transport failure or a
- * 5xx is `unavailable`. */
 export type ReadOutcome<T> =
   | { state: "ok"; data: T }
-  | {
-      state: "denied" | "unavailable" | "not_found" | "rejected";
-      code: string;
-    };
+  | { state: "denied" | "unavailable" | "not_found"; code: string };
 
 export type CoreReader = <T>(
   path: string,
@@ -149,27 +142,10 @@ export function createCoreReader(attachment: {
     if (response.status === 404) {
       return { state: "not_found" as const, code: "http_404" };
     }
-    if ([400, 409, 422].includes(response.status)) {
-      return {
-        state: "rejected" as const,
-        code: detailCode(response.data, response.status),
-      };
-    }
     return { state: "unavailable" as const, code: `http_${response.status}` };
   };
 }
 
-/** Core's stable `detail` code when it sent one, else the bare status. */
-function detailCode(value: unknown, status: number): string {
-  const detail =
-    value && typeof value === "object" && !Array.isArray(value)
-      ? (value as { detail?: unknown }).detail
-      : undefined;
-  return typeof detail === "string" && /^[a-z0-9_.:-]{1,128}$/.test(detail)
-    ? detail
-    : `http_${status}`;
-}
-
 /**
  * Context search is semantically read-only but intentionally uses POST so the
  * private query and filters are carried in a bounded body, never in a URL.
@@ -194,7 +170,7 @@ export function createCoreContextQuery(attachment: {
     let response: { status: number; data: unknown };
     try {
       response = await client.post(
-        "/api/v2/context/search",
+        "/api/v1/context/search",
         body,
         options?.signal ? { signal: options.signal } : undefined,
       );
@@ -218,18 +194,16 @@ export function isReadOnlyPath(path: string): boolean {
   if ((READ_ONLY_PATHS as readonly string[]).includes(path)) return true;
   if (IMPORT_JOB.test(path)) return true;
   if (OPERATION_RECEIPT.test(path)) return true;
-  if (MEMORY_ADDITION.test(path)) return true;
-  if (!SDK_MEMORY_DETAIL.test(path)) return false;
-  const segment = path.slice("/api/v2/memories/".length);
+  if (MEMORY_MUTATION_RECEIPT.test(path)) return true;
+  if (!MEMORY_DETAIL.test(path)) return false;
+  const segment = path.slice("/api/v1/memories/".length);
   return !(RESERVED_MEMORY_SEGMENTS as readonly string[]).includes(segment);
 }
 
 /** A write accepted by the unified Memory Server entry.
  *
- * `request_id` is the idempotency key: Core keys the write on it, so a retry
- * with the same id and the same messages is answered from the first write, and
- * the same id with different messages is refused (409). A retry without the
- * original id is a new write.
+ * `request_id` is what the caller keeps and queries later. Retrying is unsafe:
+ * HY has no idempotency key, so a resubmit duplicates the memory.
  */
 export interface MemoryWriteReceipt {
   request_id: string;
@@ -237,43 +211,6 @@ export interface MemoryWriteReceipt {
   created_at: string;
   updated_at: string;
   detail?: string;
-  raw_ids?: string[];
-  memory_ids?: string[];
-}
-
-export interface OpenAIMessage {
-  role: "user" | "assistant" | "tool";
-  content: string;
-}
-
-function isRecord(value: unknown): value is Record<string, unknown> {
-  return value !== null && typeof value === "object" && !Array.isArray(value);
-}
-
-export function parseOpenAIMessages(value: unknown): OpenAIMessage[] | null {
-  const candidate = Array.isArray(value)
-    ? value
-    : isRecord(value) && Array.isArray(value.messages)
-      ? value.messages
-      : null;
-  if (candidate === null || candidate.length < 1 || candidate.length > 200)
-    return null;
-  const messages: OpenAIMessage[] = [];
-  for (const item of candidate) {
-    if (!isRecord(item)) return null;
-    if (!["user", "assistant", "tool"].includes(String(item.role))) return null;
-    if (
-      typeof item.content !== "string" ||
-      item.content.length < 1 ||
-      item.content.length > 12_000
-    )
-      return null;
-    messages.push({
-      role: item.role as OpenAIMessage["role"],
-      content: item.content,
-    });
-  }
-  return messages.some((message) => message.role === "user") ? messages : null;
 }
 
 /** A6: submit a write through the durable entry every entry shares.
@@ -296,63 +233,34 @@ function baseUrlOf(attachment: RuntimeAttachmentLike): string {
   return `http://${attachment.host}:${attachment.port}`;
 }
 
-export type MemoryWriteOutcome =
-  | { state: "accepted"; receipt: MemoryWriteReceipt }
-  | { state: "rejected"; code: string; http_status: number }
-  | { state: "unknown"; code: string };
-
 export async function submitMemoryWrite(
   attachment: RuntimeAttachmentLike,
   request: {
     session: string;
-    source: string;
-    request_id: string;
-    messages: readonly OpenAIMessage[];
-    memory_at?: string;
+    first_round: number;
+    last_round: number;
+    evidence_ids: readonly string[];
     priority?: "live" | "normal";
   },
-): Promise<MemoryWriteOutcome> {
-  let response: { status: number; data: unknown };
-  try {
-    response = await axios.post<MemoryWriteReceipt>(
-      `${baseUrlOf(attachment)}/api/v2/memory-writes`,
-      {
-        request_id: request.request_id,
-        session_id: request.session,
-        source_id: request.source,
-        messages: [...request.messages],
-        ...(request.memory_at === undefined
-          ? {}
-          : { memory_at: request.memory_at }),
-        ...(request.priority === undefined
-          ? {}
-          : { priority: request.priority }),
-      },
-      {
-        headers: { Authorization: `Bearer ${attachment.apiToken}` },
-        timeout: 15_000,
-        proxy: false,
-        maxRedirects: 0,
-        maxContentLength: MAX_RESPONSE_BYTES,
-        validateStatus: () => true,
-      },
-    );
-  } catch {
-    // The request may or may not have reached Core; the same request id makes
-    // a retry safe.
-    return { state: "unknown", code: "transport_result_unknown" };
-  }
-  if (response.status >= 200 && response.status < 300) {
-    return { state: "accepted", receipt: response.data as MemoryWriteReceipt };
-  }
-  if (response.status >= 400 && response.status < 500) {
-    return {
-      state: "rejected",
-      code: detailCode(response.data, response.status),
-      http_status: response.status,
-    };
-  }
-  return { state: "unknown", code: `http_${response.status}_result_unknown` };
+): Promise<MemoryWriteReceipt> {
+  const response = await axios.post<MemoryWriteReceipt>(
+    `${baseUrlOf(attachment)}/api/v1/memory-writes`,
+    {
+      internal_session_id: request.session,
+      first_round: request.first_round,
+      last_round: request.last_round,
+      evidence_ids: [...request.evidence_ids],
+      ...(request.priority === undefined ? {} : { priority: request.priority }),
+    },
+    {
+      headers: { Authorization: `Bearer ${attachment.apiToken}` },
+      timeout: 15_000,
+      proxy: false,
+      maxRedirects: 0,
+      maxContentLength: MAX_RESPONSE_BYTES,
+    },
+  );
+  return response.data;
 }
 
 /** Ask Runtime to scan one source now, returning the import job it started.
@@ -472,7 +380,7 @@ export async function readMemoryWrite(
 ): Promise<MemoryWriteReceipt | null> {
   try {
     const response = await axios.get<MemoryWriteReceipt>(
-      `${baseUrlOf(attachment)}/api/v2/memory-writes/${encodeURIComponent(requestId)}`,
+      `${baseUrlOf(attachment)}/api/v1/memory-writes/${encodeURIComponent(requestId)}`,
       {
         headers: { Authorization: `Bearer ${attachment.apiToken}` },
         timeout: 10_000,
@@ -549,52 +457,48 @@ export async function readScanRoots(
   }
 }
 
-/** A direct Core write whose refusal carries Core's stable code. */
-export type CoreWriteResult =
-  | { ok: true; data: unknown }
-  | { ok: false; code: string };
-
-async function coreWrite(
-  attachment: RuntimeAttachmentLike,
-  method: "post" | "delete",
-  pathname: string,
-  body: Record<string, unknown>,
-  timeout = 10_000,
-): Promise<CoreWriteResult> {
-  let response: { status: number; data: unknown };
-  try {
-    response = await axios.request({
-      method,
-      url: `${baseUrlOf(attachment)}${pathname}`,
-      data: body,
-      headers: { Authorization: `Bearer ${attachment.apiToken}` },
-      timeout,
-      proxy: false,
-      maxRedirects: 0,
-      maxContentLength: MAX_RESPONSE_BYTES,
-      validateStatus: () => true,
-    });
-  } catch {
-    return { ok: false, code: "transport_failed" };
-  }
-  if (response.status >= 200 && response.status < 300) {
-    return { ok: true, data: response.data };
-  }
-  return { ok: false, code: detailCode(response.data, response.status) };
-}
-
 export async function addScanRoot(
   attachment: RuntimeAttachmentLike,
   body: { root: string; source?: string; recursive?: boolean },
-): Promise<CoreWriteResult> {
-  return coreWrite(attachment, "post", "/api/v1/scan-roots", body);
+): Promise<unknown | null> {
+  try {
+    const response = await axios.post<unknown>(
+      `${baseUrlOf(attachment)}/api/v1/scan-roots`,
+      body,
+      {
+        headers: { Authorization: `Bearer ${attachment.apiToken}` },
+        timeout: 10_000,
+        proxy: false,
+        maxRedirects: 0,
+        maxContentLength: MAX_RESPONSE_BYTES,
+      },
+    );
+    return response.data;
+  } catch (error) {
+    return { _error: error instanceof Error ? error.message : String(error) };
+  }
 }
 
 export async function removeScanRoot(
   attachment: RuntimeAttachmentLike,
   body: { root: string },
-): Promise<CoreWriteResult> {
-  return coreWrite(attachment, "delete", "/api/v1/scan-roots", body);
+): Promise<unknown | null> {
+  try {
+    const response = await axios.delete<unknown>(
+      `${baseUrlOf(attachment)}/api/v1/scan-roots`,
+      {
+        headers: { Authorization: `Bearer ${attachment.apiToken}` },
+        data: body,
+        timeout: 10_000,
+        proxy: false,
+        maxRedirects: 0,
+        maxContentLength: MAX_RESPONSE_BYTES,
+      },
+    );
+    return response.data;
+  } catch (error) {
+    return { _error: error instanceof Error ? error.message : String(error) };
+  }
 }
 
 export async function readAdapters(
@@ -620,12 +524,21 @@ export async function readAdapters(
 export async function probeAdapter(
   attachment: RuntimeAttachmentLike,
   source: string,
-): Promise<CoreWriteResult> {
-  return coreWrite(
-    attachment,
-    "post",
-    "/api/v1/adapters/probe",
-    { source },
-    15_000,
-  );
+): Promise<unknown | null> {
+  try {
+    const response = await axios.post<unknown>(
+      `${baseUrlOf(attachment)}/api/v1/adapters/probe`,
+      { source },
+      {
+        headers: { Authorization: `Bearer ${attachment.apiToken}` },
+        timeout: 15_000,
+        proxy: false,
+        maxRedirects: 0,
+        maxContentLength: MAX_RESPONSE_BYTES,
+      },
+    );
+    return response.data;
+  } catch (error) {
+    return { _error: error instanceof Error ? error.message : String(error) };
+  }
 }

memhub/apps/cli/src/core-operations.ts

@@ -4,11 +4,8 @@ const WRITE_PATHS = [
   "/api/v1/sources/connect",
   "/api/v1/model-profiles",
 ] as const;
-/** `POST /api/v2/memories` adds one memory (the app's 添加记忆). */
-const MEMORY_ADD_PATH = "/api/v2/memories";
-/** One SDK memory; delete names its namespace in the query string. */
-const SDK_MEMORY_PATH =
-  /^\/api\/v2\/memories\/[A-Za-z0-9][\w.-]{0,127}(?:\?kind=(?:chat|experience|fact)(?:&variant=(?:working|coding))?)?$/;
+const MEMORY_WRITE_PATH =
+  /^\/api\/v1\/memories(?:\/[A-Za-z0-9][\w.-]{0,127}\/(?:correct|scopes|actions\/delete))?$/;
 const MODEL_PROBE_PATH =
   /^\/api\/v1\/model-profiles\/[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}\/probe$/;
 const MODEL_PROFILE_PATH =
@@ -24,7 +21,18 @@ const SOURCE_REVOKE_PATH =
 const SOURCE_IMPORT_JOB_PATH = "/api/v1/import-jobs";
 const IMPORT_JOB_ACTION_PATH =
   /^\/api\/v1\/import-jobs\/[A-Za-z0-9][\w.-]{0,127}\/(?:pause|resume|cancel)$/;
+const CALL_EVENTS_CLEAR_PATH = "/api/v1/call-events/clear";
+const CALL_EVENTS_CLEAR_ALL_PATH = "/api/v1/call-events/clear-all";
+const IMPORT_FILE_COMMIT =
+  /^\/api\/v1\/import-files\/[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}\/commit$/;
+const IMPORT_FILE =
+  /^\/api\/v1\/import-files\/[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/;
+const MEMORY_NOTES_PATH = "/api/v1/memory-notes";
+const MEMORY_NOTE_PROCESS =
+  /^\/api\/v1\/memory-notes\/[A-Za-z0-9][\w.:-]{0,127}\/process$/;
+const EXTRACTION_SETTINGS_PATH = "/api/v1/extraction-settings";
 const GRAPH_WIDTH_PATH = "/api/v1/graph-width";
+const MANUAL_EXTRACT_PATH = "/api/v1/memory-processing/manual-extract";
 const ONBOARDING_COMPLETE_PATH = "/api/v1/onboarding/complete";
 const MAX_BYTES = 4 * 1024 * 1024;
 
@@ -61,6 +69,18 @@ export interface CorePatchOperations {
   ): Promise<OperationOutcome<T>>;
 }
 
+export interface CoreUploadOperations {
+  uploadImportFile<T>(
+    input: {
+      bytes: Uint8Array;
+      filename: string;
+      inputKind: "raw_conversation" | "memory_content";
+      operationId: string;
+    },
+    signal?: AbortSignal,
+  ): Promise<OperationOutcome<T>>;
+}
+
 export function createCoreOperations(attachment: {
   host: string;
   port: number;
@@ -69,7 +89,8 @@ export function createCoreOperations(attachment: {
 }): CoreOperations &
   CoreDeleteOperations &
   CorePutOperations &
-  CorePatchOperations {
+  CorePatchOperations &
+  CoreUploadOperations {
   const client = axios.create({
     baseURL: `http://${attachment.host}:${attachment.port}`,
     headers: { Authorization: `Bearer ${attachment.apiToken}` },
@@ -80,6 +101,18 @@ export function createCoreOperations(attachment: {
     maxBodyLength: 128 * 1024,
     validateStatus: () => true,
   });
+  // Uploads carry up to 128 MiB of raw octet-stream, so they need a separate
+  // body limit and a deadline that leaves room for parsing on the Core side.
+  const uploadClient = axios.create({
+    baseURL: `http://${attachment.host}:${attachment.port}`,
+    headers: { Authorization: `Bearer ${attachment.apiToken}` },
+    timeout: 120_000,
+    proxy: false,
+    maxRedirects: 0,
+    maxContentLength: MAX_BYTES,
+    maxBodyLength: 128 * 1024 * 1024,
+    validateStatus: () => true,
+  });
   return {
     async post<T>(
       path: string,
@@ -89,13 +122,19 @@ export function createCoreOperations(attachment: {
       if (
         !(WRITE_PATHS as readonly string[]).includes(path) &&
         path !== SOURCE_IMPORT_JOB_PATH &&
-        path !== MEMORY_ADD_PATH &&
+        !MEMORY_WRITE_PATH.test(path) &&
         !MODEL_PROBE_PATH.test(path) &&
         !SOURCE_SYNC_PATH.test(path) &&
         !IMPORT_JOB_ACTION_PATH.test(path) &&
         !SOURCE_AUTHORIZE_PATH.test(path) &&
         !SOURCE_REVOKE_PATH.test(path) &&
+        path !== CALL_EVENTS_CLEAR_PATH &&
+        path !== CALL_EVENTS_CLEAR_ALL_PATH &&
+        !IMPORT_FILE_COMMIT.test(path) &&
+        path !== MEMORY_NOTES_PATH &&
+        !MEMORY_NOTE_PROCESS.test(path) &&
         path !== GRAPH_WIDTH_PATH &&
+        path !== MANUAL_EXTRACT_PATH &&
         path !== ONBOARDING_COMPLETE_PATH &&
         !MODEL_PROFILE_ACTIVATE.test(path)
       ) {
@@ -131,7 +170,7 @@ export function createCoreOperations(attachment: {
       body: Record<string, unknown>,
       signal?: AbortSignal,
     ) {
-      if (!SDK_MEMORY_PATH.test(path) || path.includes("?")) {
+      if (path !== EXTRACTION_SETTINGS_PATH) {
         throw new Error("core_operation_path_not_allowed");
       }
       let response: { status: number; data: unknown };
@@ -193,7 +232,7 @@ export function createCoreOperations(attachment: {
       };
     },
     async delete<T>(path: string, signal?: AbortSignal) {
-      if (!SDK_MEMORY_PATH.test(path) && !MODEL_PROFILE_PATH.test(path)) {
+      if (!IMPORT_FILE.test(path)) {
         throw new Error("core_operation_path_not_allowed");
       }
       let response: { status: number; data: unknown };
@@ -217,6 +256,51 @@ export function createCoreOperations(attachment: {
         code: `http_${response.status}_result_unknown`,
       };
     },
+    async uploadImportFile<T>(
+      input: {
+        bytes: Uint8Array;
+        filename: string;
+        inputKind: "raw_conversation" | "memory_content";
+        operationId: string;
+      },
+      signal?: AbortSignal,
+    ) {
+      const query = new URLSearchParams({
+        filename: input.filename,
+        input_kind: input.inputKind,
+        operation_id: input.operationId,
+      });
+      let response: { status: number; data: unknown };
+      try {
+        response = await uploadClient.post(
+          `/api/v1/import-files?${query.toString()}`,
+          input.bytes,
+          {
+            headers: {
+              "Content-Type": "application/octet-stream",
+              "Content-Length": String(input.bytes.byteLength),
+            },
+            ...(signal ? { signal } : {}),
+          },
+        );
+      } catch {
+        return { state: "unknown", code: "transport_result_unknown" };
+      }
+      if (response.status >= 200 && response.status < 300) {
+        return { state: "committed", data: response.data as T };
+      }
+      if (response.status >= 400 && response.status < 500) {
+        return {
+          state: "rejected",
+          code: safeErrorCode(response.data, response.status),
+          http_status: response.status,
+        };
+      }
+      return {
+        state: "unknown",
+        code: `http_${response.status}_result_unknown`,
+      };
+    },
   };
 }
 

memhub/apps/cli/src/core-responses.ts

@@ -1,20 +1,18 @@
 import type {
+  GovernedMemory,
+  HomeSummary,
   ImportIssue,
   ImportJob,
   LiveSyncHealth,
+  MemoryDetail,
+  MemoryEvidenceExcerpt,
+  MemoryLibraryPage,
   MemoryProcessingSummary,
   ModelProfile,
   SourceResponse,
 } from "@one-memory/contracts";
-/** SDK memory states `memhub memories list --status` may ask for. */
-export const MEMORY_STATUSES = [
-  "active",
-  "superseded",
-  "shadow",
-  "negated",
-  "conflicted",
-  "archived",
-] as const;
+/** The only memory states a response may carry, and the only ones a filter may ask for. */
+export const MEMORY_STATUSES = ["confirmed", "deleted", "superseded"] as const;
 
 /**
  * HTTP 200 is not a contract. Everything here re-checks the shape and the
@@ -25,6 +23,7 @@ export const MEMORY_STATUSES = [
 
 const ID_MAX = 128;
 const LABEL_MAX = 256;
+const TEXT_MAX = 100_000;
 const LIST_MAX = 500;
 const LIVE_SYNC_STATES = [
   "idle",
@@ -40,6 +39,14 @@ const PROVIDER_KINDS = [
   "local_onnx",
 ] as const;
 const CREDENTIAL_STATES = ["available", "missing", "unavailable"] as const;
+const MEMORY_KINDS = [
+  "chat",
+  "working",
+  "coding",
+  "schema",
+  "intention",
+] as const;
+const MEMORY_ORIGINS = ["extracted", "answered", "agent", "manual"] as const;
 const IMPORT_STATUSES = [
   "pending",
   "running",
@@ -50,6 +57,16 @@ const IMPORT_STATUSES = [
   "cancelled",
 ] as const;
 const SCAN_PHASES = ["discover", "read", "emit", "done"] as const;
+const MEMORY_TASK_KINDS = ["extract", "system2", "ultra", "sweeper"] as const;
+const MEMORY_TASK_STATUSES = [
+  "pending",
+  "running",
+  "waiting_for_model",
+  "completed",
+  "failed",
+  "cancelled",
+  "deferred_outside_window",
+] as const;
 const CAPABILITY_STATES = ["not_implemented", "implemented"] as const;
 const VERIFICATION_STATES = ["fixture_only", "real_replayed"] as const;
 const SYNC_COMPLETENESS = [
@@ -70,6 +87,16 @@ const LOCATION_STATES = [
 ] as const;
 const LIVE_SYNC_MODES = ["polling", "watch_and_polling"] as const;
 
+export interface ValidatedMemoryTask {
+  task_id: string;
+  kind: (typeof MEMORY_TASK_KINDS)[number];
+  status: (typeof MEMORY_TASK_STATUSES)[number];
+  attempts: number;
+  last_error_code: string | null;
+  created_at: string;
+  updated_at: string;
+}
+
 export interface SourceConnectionCandidate {
   source_id: string;
   display_name: string;
@@ -325,6 +352,45 @@ export function validateImportIssues(
   });
 }
 
+export function validateMemoryTasks(
+  value: unknown,
+): ValidatedMemoryTask[] | null {
+  return list(value, (item) => {
+    const task = record(item);
+    if (!task) return null;
+    const taskId = text(task.task_id, ID_MAX);
+    if (
+      task.last_error_code !== null &&
+      text(task.last_error_code, LABEL_MAX) === null
+    ) {
+      return null;
+    }
+    const error = task.last_error_code as string | null;
+    const createdAt = text(task.created_at, LABEL_MAX);
+    const updatedAt = text(task.updated_at, LABEL_MAX);
+    const attempts = count(task.attempts);
+    if (
+      taskId === null ||
+      createdAt === null ||
+      updatedAt === null ||
+      attempts === null ||
+      !oneOf(task.kind, MEMORY_TASK_KINDS) ||
+      !oneOf(task.status, MEMORY_TASK_STATUSES)
+    ) {
+      return null;
+    }
+    return {
+      task_id: taskId,
+      kind: task.kind,
+      status: task.status,
+      attempts,
+      last_error_code: error,
+      created_at: createdAt,
+      updated_at: updatedAt,
+    };
+  });
+}
+
 export function validateProcessing(
   value: unknown,
 ): MemoryProcessingSummary | null {
@@ -378,32 +444,150 @@ export function validateModelProfiles(value: unknown): ModelProfile[] | null {
   });
 }
 
-/** `GET /api/v2/home-summary`: the SDK-authority home card. */
-export interface SdkHomeSummary {
-  schema_version: 2;
-  memory_count: number;
-  latest: { memory_id: string } | null;
-  observed_at: string;
-}
-
-export function validateHomeSummary(value: unknown): SdkHomeSummary | null {
+export function validateHomeSummary(value: unknown): HomeSummary | null {
   const summary = record(value);
   if (
     !summary ||
-    summary.schema_version !== 2 ||
     count(summary.memory_count) === null ||
     text(summary.observed_at, LABEL_MAX) === null
   ) {
     return null;
   }
-  const latest = summary.latest;
-  if (latest !== null) {
-    const memory = record(latest);
-    if (!memory || typeof memory.memory_id !== "string" || !memory.memory_id) {
+  return summary as unknown as HomeSummary;
+}
+
+/** The page must be the page that was asked for, not merely a page. */
+export function validateMemoryPage(
+  value: unknown,
+  request: { offset: number; limit: number },
+): MemoryLibraryPage | null {
+  const page = record(value);
+  if (!page) return null;
+  const total = count(page.total);
+  if (
+    total === null ||
+    page.offset !== request.offset ||
+    page.limit !== request.limit
+  ) {
+    return null;
+  }
+  const items = list(page.items, validateGovernedMemory);
+  if (items === null || items.length > request.limit) return null;
+  if (items.length > 0 && total < request.offset + items.length) return null;
+  return { items, total, offset: page.offset, limit: page.limit };
+}
+
+export function validateMemoryDetail(
+  value: unknown,
+  memoryId: string,
+): MemoryDetail | null {
+  const detail = record(value);
+  if (!detail) return null;
+  const memory = validateGovernedMemory(detail.memory);
+  if (memory === null || memory.memory_id !== memoryId) return null;
+  const cited = new Set(memory.evidence_ids);
+  const returned = new Set<string>();
+  const evidence = list(detail.evidence ?? [], (item) => {
+    const excerpt = record(item);
+    if (!excerpt) return null;
+    const evidenceId = text(excerpt.evidence_id, ID_MAX);
+    // Core builds this list from the memory's own citations; anything else is
+    // another record's excerpt and must not be shown under this memory.
+    if (
+      evidenceId === null ||
+      !cited.has(evidenceId) ||
+      returned.has(evidenceId) ||
+      typeof excerpt.available !== "boolean"
+    ) {
       return null;
     }
+    returned.add(evidenceId);
+    const available = excerpt.available === true;
+    const verbatim = available ? text(excerpt.verbatim ?? "", TEXT_MAX) : "";
+    if (verbatim === null) return null;
+    return {
+      evidence_id: evidenceId,
+      available,
+      source_id: optional(excerpt.source_id, ID_MAX),
+      written_by: optional(excerpt.written_by, LABEL_MAX),
+      created_at: optional(excerpt.created_at, LABEL_MAX),
+      // An excerpt the user cannot read has no text, whatever the server sent.
+      verbatim,
+    } as unknown as MemoryEvidenceExcerpt;
+  });
+  if (evidence === null || evidence.length !== memory.evidence_ids.length) {
+    return null;
   }
-  return summary as unknown as SdkHomeSummary;
+  const history = list(detail.history ?? [], (item) => {
+    const version = record(item);
+    if (
+      !version ||
+      typeof version.revision !== "number" ||
+      !Number.isSafeInteger(version.revision) ||
+      version.revision < 1 ||
+      text(version.action, LABEL_MAX) === null ||
+      !oneOf(version.status, MEMORY_STATUSES) ||
+      text(version.content, TEXT_MAX) === null ||
+      identifiers(version.scopes) === null ||
+      text(version.created_at, LABEL_MAX) === null
+    ) {
+      return null;
+    }
+    return {
+      revision: version.revision,
+      action: version.action,
+      status: version.status,
+      content: version.content,
+      scopes: identifiers(version.scopes) as string[],
+      created_at: version.created_at,
+    };
+  });
+  if (history === null) return null;
+  return {
+    memory,
+    evidence,
+    history,
+    index_sync: null,
+  } as unknown as MemoryDetail;
+}
+
+export function validateGovernedMemory(value: unknown): GovernedMemory | null {
+  const memory = record(value);
+  if (
+    !memory ||
+    !text(memory.memory_id, ID_MAX) ||
+    !text(memory.user_id, LABEL_MAX) ||
+    !text(memory.content, TEXT_MAX) ||
+    !oneOf(memory.kind, MEMORY_KINDS) ||
+    !oneOf(memory.origin, MEMORY_ORIGINS) ||
+    typeof memory.revision !== "number" ||
+    !Number.isSafeInteger(memory.revision) ||
+    memory.revision < 1 ||
+    !oneOf(memory.status, MEMORY_STATUSES) ||
+    !text(memory.created_at, LABEL_MAX) ||
+    !text(memory.updated_at, LABEL_MAX)
+  ) {
+    return null;
+  }
+  const scopes = identifiers(memory.scopes);
+  const evidenceIds = identifiers(memory.evidence_ids);
+  const tags = identifiers(memory.tags ?? []);
+  if (
+    scopes === null ||
+    scopes.length < 1 ||
+    evidenceIds === null ||
+    evidenceIds.length < 1 ||
+    tags === null ||
+    tags.length > 32
+  ) {
+    return null;
+  }
+  return {
+    ...memory,
+    scopes,
+    evidence_ids: evidenceIds,
+    tags,
+  } as unknown as GovernedMemory;
 }
 
 function identifiers(value: unknown): string[] | null {
@@ -434,6 +618,10 @@ function text(value: unknown, max: number): string | null {
   return typeof value === "string" && value.length <= max ? value : null;
 }
 
+function optional(value: unknown, max: number): string | undefined {
+  return typeof value === "string" && value.length <= max ? value : undefined;
+}
+
 function count(value: unknown): number | null {
   return typeof value === "number" && Number.isSafeInteger(value) && value >= 0
     ? value

memhub/apps/cli/src/doctor-report.test.ts

@@ -134,6 +134,11 @@ function progress(): ProgressDocument {
     generation: {
       summary_state: { state: "ok" },
       summary: { waiting_for_model: 1, failed: 0 },
+      tasks_state: { state: "ok" },
+      tasks: [{ task_id: "t1", status: "waiting_for_model" }],
+      returned: 1,
+      validated: 1,
+      output_truncated: false,
     },
   };
 }

memhub/apps/cli/src/doctor-report.ts

@@ -65,9 +65,6 @@ export function renderDoctorText(document: DoctorDocument): string {
     model: "模型",
     pending_operations: "待处理操作",
   };
-  const migration = document.checks.find(
-    (check) => check.id === "core" && check.details?.log_file,
-  );
   return [
     `MemHub 检查：${doctorState(document.state)}`,
     ...document.checks.map(
@@ -76,13 +73,7 @@ export function renderDoctorText(document: DoctorDocument): string {
     ),
     ...(document.state === "healthy"
       ? []
-      : migration
-        ? [
-            `升级迁移没有完成（错误码：${migration.code}），MemHub 不会启动。`,
-            `下一步：把迁移日志附在 GitHub 反馈里发给我们：${migration.details?.log_file}`,
-            `反馈地址：${migration.details?.issues_url}`,
-          ]
-        : ["下一步：打开 MemHub 的“帮助与诊断”查看并处理异常。"]),
+      : ["下一步：打开 MemHub 的“帮助与诊断”查看并处理异常。"]),
     "",
   ].join("\n");
 }
@@ -116,14 +107,6 @@ function coreCheck(status: StatusDocument): DoctorCheck {
     id: "core",
     state: status.runtime.state === "stopped" ? "warn" : "fail",
     code: status.runtime.code,
-    ...(status.runtime.log_file
-      ? {
-          details: {
-            log_file: status.runtime.log_file,
-            issues_url: status.runtime.issues_url ?? "",
-          },
-        }
-      : {}),
   };
 }
 
@@ -217,7 +200,8 @@ function modelCheck(status: StatusDocument): DoctorCheck {
 function pendingCheck(progress: ProgressDocument | null): DoctorCheck {
   if (
     progress?.imports.state !== "ok" ||
-    progress.generation.summary_state.state !== "ok"
+    progress.generation.summary_state.state !== "ok" ||
+    progress.generation.tasks_state.state !== "ok"
   ) {
     return {
       id: "pending_operations",
@@ -228,20 +212,27 @@ function pendingCheck(progress: ProgressDocument | null): DoctorCheck {
   const jobAttention = progress.imports.jobs.filter((item) =>
     ["paused", "interrupted", "failed"].includes(text(item.status) ?? ""),
   ).length;
+  const taskAttention = progress.generation.tasks.filter((item) =>
+    ["waiting_for_model", "failed"].includes(text(item.status) ?? ""),
+  ).length;
   const summary = progress.generation.summary;
   const waiting = summary ? number(summary.waiting_for_model) : 0;
   const failed = summary ? number(summary.failed) : 0;
-  const attention = jobAttention + waiting + failed;
+  const attention = jobAttention + taskAttention + waiting + failed;
   return {
     id: "pending_operations",
     state: attention > 0 ? "warn" : "pass",
     code: attention > 0 ? "operations_need_attention" : "pending_operations_ok",
     details: {
       import_jobs_validated: progress.imports.validated,
+      generation_tasks_validated: progress.generation.validated,
       jobs_need_attention: jobAttention,
+      tasks_need_attention: taskAttention,
       waiting_for_model: waiting,
       failed,
-      output_truncated: progress.imports.output_truncated,
+      output_truncated:
+        progress.imports.output_truncated ||
+        progress.generation.output_truncated,
     },
   };
 }

memhub/apps/cli/src/entry.ts

@@ -23,26 +23,39 @@ function accountHomeDirectory(): string | undefined {
 async function main(): Promise<number> {
   const arguments_ = process.argv.slice(2);
   const command = arguments_[0];
+  const action = arguments_[1];
   // A preview (`--yes` absent) must not create or write any diagnostic file:
   // the contract is that it only emits a plan. Diagnostics for these commands
   // are initialized only once the caller has confirmed the mutation.
-  const confirmed = arguments_.includes("--yes");
+  const confirmed = arguments_.includes("--yes")
+    ? true
+    : arguments_.includes("--confirm");
   const installLike = [
     "install",
     "upgrade",
     "service-install",
     "service-uninstall",
   ].includes(command ?? "");
-  const isPreview = installLike && !confirmed;
-  const mutating = [
-    "start",
-    "stop",
-    "restart",
-    "install",
-    "upgrade",
-    "service-install",
-    "service-uninstall",
-  ].includes(command ?? "");
+  const planFileApply =
+    (command === "sources" && action === "import") ||
+    (command === "models" && (action === "configure" || action === "probe")) ||
+    (command === "processing" && action === "apply") ||
+    (command === "memories" && action === "apply");
+  const isPreview = (installLike || planFileApply) && !confirmed;
+  const mutating =
+    [
+      "start",
+      "stop",
+      "restart",
+      "install",
+      "upgrade",
+      "service-install",
+      "service-uninstall",
+    ].includes(command ?? "") ||
+    (command === "sources" && action === "import") ||
+    (command === "models" && ["configure", "probe"].includes(action ?? "")) ||
+    (command === "processing" && action === "apply") ||
+    (command === "memories" && action === "apply");
   let diagnostics: DiagnosticLogger | null = null;
   if (mutating && !isPreview) {
     try {

memhub/apps/cli/src/graph-width-flow.ts

@@ -1,93 +0,0 @@
-/**
- * `memhub graph-width`: the user's decision when the embedding width changed
- * and the memory graph no longer matches it (`POST /api/v1/graph-width`).
- *
- * `keep_existing` and `export_first` change nothing irreversible and run
- * directly. `rebuild_with_new` archives the current graph and rebuilds it, so
- * the CLI asks for `--yes` before sending it.
- */
-
-import { parseGraphWidthDecisionReceipt } from "@one-memory/operations";
-import type { CoreOperations } from "./core-operations.js";
-import { PRODUCT } from "./version.js";
-
-export const GRAPH_WIDTH_DECISIONS = [
-  "keep_existing",
-  "rebuild_with_new",
-  "export_first",
-] as const;
-export type GraphWidthDecision = (typeof GRAPH_WIDTH_DECISIONS)[number];
-
-/** The one decision that cannot be taken back. */
-export function graphWidthDecisionIsDestructive(
-  decision: GraphWidthDecision,
-): boolean {
-  return decision === "rebuild_with_new";
-}
-
-export type GraphWidthDocument =
-  | {
-      schema_version: 1;
-      product: string;
-      command: "graph-width";
-      state: "committed";
-      decision: GraphWidthDecision;
-      receipt: Record<string, unknown>;
-    }
-  | {
-      schema_version: 1;
-      product: string;
-      command: "graph-width";
-      state: "rejected" | "unknown";
-      decision: GraphWidthDecision;
-      code: string;
-    };
-
-export async function decideGraphWidth(
-  decision: GraphWidthDecision,
-  operations: CoreOperations,
-): Promise<GraphWidthDocument> {
-  const base = {
-    schema_version: 1 as const,
-    product: PRODUCT,
-    command: "graph-width" as const,
-    decision,
-  };
-  const result = await operations.post<unknown>("/api/v1/graph-width", {
-    decision,
-  });
-  if (result.state !== "committed") {
-    return { ...base, state: result.state, code: result.code };
-  }
-  const receipt = parseGraphWidthDecisionReceipt(result.data);
-  if (receipt === null) {
-    return { ...base, state: "unknown", code: "graph_width_receipt_invalid" };
-  }
-  return {
-    ...base,
-    state: "committed",
-    receipt: {
-      archived_path: receipt.archived_path ?? null,
-      exported_path: receipt.exported_path ?? null,
-      mismatch: receipt.mismatch ?? null,
-    },
-  };
-}
-
-export function graphWidthExitCode(document: GraphWidthDocument): number {
-  return document.state === "committed" ? 0 : 1;
-}
-
-export function renderGraphWidthText(document: GraphWidthDocument): string {
-  if (document.state === "committed") {
-    const lines = [`已执行图谱宽度决定：${document.decision}`];
-    if (document.receipt.exported_path) {
-      lines.push(`导出：${document.receipt.exported_path}`);
-    }
-    if (document.receipt.archived_path) {
-      lines.push(`旧图谱已归档：${document.receipt.archived_path}`);
-    }
-    return `${lines.join("\n")}\n`;
-  }
-  return `图谱宽度决定未完成：${document.state}（${document.code}）\n`;
-}

memhub/apps/cli/src/headless-flows.ts

@@ -1,4 +1,4 @@
-import { randomUUID } from "node:crypto";
+import { createHash, randomUUID } from "node:crypto";
 import type { ImportJob, ModelProfile } from "@one-memory/contracts";
 import {
   buildModelProfileCreateRequest,
@@ -26,7 +26,45 @@ const PROVIDERS = [
   "local_onnx",
 ] as const;
 
+interface SourceImportPlanBody {
+  schema_version: 1;
+  kind: "source_import";
+  request_id: string;
+  source_ids: string[];
+  source_roots: Record<string, string>;
+  source_candidate_revisions: Record<string, number>;
+  confirm_environment_overrides: boolean;
+  full_rescan: false;
+  onboarding: true;
+}
+
+export type SourceImportPlan = SourceImportPlanBody & { digest: string };
+
+interface ModelCreatePlanBody {
+  schema_version: 1;
+  kind: "model_profile_create";
+  operation_id: string;
+  config: Record<string, unknown>;
+}
+
+export type ModelCreatePlan = ModelCreatePlanBody & { digest: string };
+
+/** A removal only needs an id: there is no config to review, and inventing one
+ * to fit the create shape would misrepresent what the command does.
+ */
+export interface ModelRemovePlan {
+  schema_version: 1;
+  kind: "model_profile_remove";
+  target: string;
+}
+
 export type FlowDocument =
+  | {
+      schema_version: 1;
+      product: string;
+      state: "preview";
+      plan: SourceImportPlan | ModelCreatePlan | ModelRemovePlan;
+    }
   | {
       schema_version: 1;
       product: string;
@@ -95,24 +133,10 @@ function classifySourceImport(
   return committed(operationId, receipt);
 }
 
-/**
- * Connect sources and import their history in one direct request.
- *
- * Reads the current candidates, refuses a source whose location comes from an
- * environment override unless the caller confirmed overrides, and posts one
- * `/sources/connect` (grant + history import + live sync). `requestId` is the
- * idempotency key: re-running with the same id reads the first receipt.
- */
-export async function connectSourcesWithImport(
+export async function planSourceImport(
   reader: CoreReader,
-  operations: CoreOperations,
-  input: {
-    sourceIds: readonly string[];
-    confirmOverrides: boolean;
-    requestId?: string;
-  },
+  sourceIds: readonly string[],
 ): Promise<FlowDocument> {
-  const sourceIds = input.sourceIds;
   if (
     sourceIds.length < 1 ||
     sourceIds.length > 32 ||
@@ -121,8 +145,6 @@ export async function connectSourcesWithImport(
   ) {
     return invalid("invalid_source_selection");
   }
-  const requestId = input.requestId ?? randomUUID();
-  if (!UUID.test(requestId)) return invalid("invalid_request_id");
   const outcome = await reader<unknown>("/api/v1/sources");
   if (outcome.state !== "ok") return fromReadFailure(outcome);
   const candidates = validateSourceConnectionCandidates(outcome.data);
@@ -134,59 +156,69 @@ export async function connectSourcesWithImport(
     return invalid("source_unavailable");
   }
   const items = selected.map(([candidate]) => candidate);
-  const needsOverride = items
-    .filter((item) => item.requires_override_confirmation)
-    .map((item) => item.source_id);
-  if (needsOverride.length > 0 && !input.confirmOverrides) {
-    return {
-      schema_version: 1,
-      product: PRODUCT,
-      state: "rejected",
-      operation_id: requestId,
-      code: "environment_override_confirmation_required",
-      receipt: { override_required_source_ids: needsOverride },
-    };
-  }
+  const body: SourceImportPlanBody = {
+    schema_version: 1,
+    kind: "source_import",
+    request_id: randomUUID(),
+    source_ids: [...sourceIds],
+    source_roots: Object.fromEntries(
+      items.map((item) => [item.source_id, item.candidate_root_id]),
+    ),
+    source_candidate_revisions: Object.fromEntries(
+      items.flatMap((item) =>
+        item.candidate_revision === undefined
+          ? []
+          : [[item.source_id, item.candidate_revision]],
+      ),
+    ),
+    confirm_environment_overrides: items.some(
+      (item) => item.requires_override_confirmation,
+    ),
+    full_rescan: false,
+    onboarding: true,
+  };
+  return preview(withDigest(body));
+}
+
+export async function executeSourceImport(
+  value: unknown,
+  reader: CoreReader,
+  operations: CoreOperations,
+): Promise<FlowDocument> {
+  const plan = validateSourcePlan(value);
+  if (!plan) return invalid("source_plan_invalid");
   // The shared builder owns the connect body's field set and coalescing, so
   // the CLI and the Web console send the same request by construction.
   let request: ReturnType<typeof buildSourceImportRequest>;
   try {
     request = buildSourceImportRequest({
-      sourceIds: [...sourceIds],
-      sourceRoots: Object.fromEntries(
-        items.map((item) => [item.source_id, item.candidate_root_id]),
-      ),
-      sourceCandidateRevisions: Object.fromEntries(
-        items.flatMap((item) =>
-          item.candidate_revision === undefined
-            ? []
-            : [[item.source_id, item.candidate_revision]],
-        ),
-      ),
-      confirmEnvironmentOverrides: needsOverride.length > 0,
-      fullRescan: false,
-      onboarding: true,
+      sourceIds: plan.source_ids,
+      sourceRoots: plan.source_roots,
+      sourceCandidateRevisions: plan.source_candidate_revisions,
+      confirmEnvironmentOverrides: plan.confirm_environment_overrides,
+      fullRescan: plan.full_rescan,
+      onboarding: plan.onboarding,
       enableSync: true,
-      requestId,
+      requestId: plan.request_id,
     });
   } catch (error) {
     if (error instanceof SourceImportInputError) {
-      return invalid("invalid_source_selection");
+      return invalid("source_plan_invalid");
     }
     throw error;
   }
   const result = await operations.post<unknown>(request.path, request.body);
   if (result.state === "rejected") {
-    return rejected(requestId, result.code);
+    return rejected(plan.request_id, result.code);
   }
   if (result.state === "committed") {
-    const receipt = validateSourceReceipt(result.data, requestId);
-    if (!receipt) return unknown(requestId, "source_receipt_invalid");
-    return classifySourceImport(requestId, receipt);
+    const receipt = validateSourceReceipt(result.data, plan.request_id);
+    if (!receipt) return unknown(plan.request_id, "source_receipt_invalid");
+    return classifySourceImport(plan.request_id, receipt);
   }
-  const recovered = await readSourceReceipt(reader, requestId);
+  const recovered = await readSourceReceipt(reader, plan.request_id);
   if (recovered.state === "unknown" || recovered.state === "not_found") {
-    return unknown(requestId, result.code);
+    return unknown(plan.request_id, result.code);
   }
   // A recovered receipt must be classified the same way as a fresh one: an
   // all-rejected or all-busy replay is still not success. Only a terminal
@@ -230,23 +262,26 @@ export async function readSourceReceipt(
   return committed(requestId, receipt);
 }
 
-/**
- * Create a model profile directly from a bounded config (never containing the
- * key) plus an optional key read from a controlled file.
- *
- * `operationId` is Core's creation idempotency key; the receipt can be read
- * later with `readModelReceipt`.
- */
-export async function createModelProfile(
+export function planModelProfile(value: unknown): FlowDocument {
+  const config = validateModelConfig(value);
+  if (!config) return invalid("model_config_invalid");
+  const body: ModelCreatePlanBody = {
+    schema_version: 1,
+    kind: "model_profile_create",
+    operation_id: randomUUID(),
+    config,
+  };
+  return preview(withDigest(body));
+}
+
+export async function executeModelProfile(
   value: unknown,
   apiKey: string | undefined,
   reader: CoreReader,
   operations: CoreOperations,
-  operationId: string = randomUUID(),
 ): Promise<FlowDocument> {
-  const config = validateModelConfig(value);
-  if (!config) return invalid("model_config_invalid");
-  if (!UUID.test(operationId)) return invalid("invalid_operation_id");
+  const plan = validateModelPlan(value);
+  if (!plan) return invalid("model_plan_invalid");
   // The shared create builder owns the body's allow-list, bounds and the
   // creation_operation_id/api_key handling, so the CLI and the Web console
   // send the same create request.
@@ -254,31 +289,31 @@ export async function createModelProfile(
   try {
     request = buildModelProfileCreateRequest(
       {
-        ...config,
+        ...(plan.config as Record<string, unknown>),
         ...(apiKey === undefined ? {} : { api_key: apiKey }),
       } as Parameters<typeof buildModelProfileCreateRequest>[0],
-      operationId,
+      plan.operation_id,
     );
   } catch (error) {
     if (error instanceof ModelProfileInputError) {
-      return invalid("model_config_invalid");
+      return invalid("model_plan_invalid");
     }
     throw error;
   }
   const result = await operations.post<unknown>(request.path, request.body);
   if (result.state === "rejected") {
-    return rejected(operationId, result.code);
+    return rejected(plan.operation_id, result.code);
   }
   if (result.state === "committed") {
     const profile = validateModelProfile(result.data);
     return profile
-      ? committed(operationId, projectProfile(profile))
-      : unknown(operationId, "model_receipt_invalid");
+      ? committed(plan.operation_id, projectProfile(profile))
+      : unknown(plan.operation_id, "model_receipt_invalid");
   }
-  const recovered = await readModelReceipt(reader, operationId);
+  const recovered = await readModelReceipt(reader, plan.operation_id);
   return recovered.state === "committed"
     ? { ...recovered, state: "recovered" }
-    : unknown(operationId, result.code);
+    : unknown(plan.operation_id, result.code);
 }
 
 export async function readModelReceipt(
@@ -327,6 +362,27 @@ export function parseApiKey(bytes: Buffer | null): string | undefined {
 }
 
 export function renderFlowText(document: FlowDocument): string {
+  if (document.state === "preview") {
+    const plan = document.plan;
+    // A removal has no config digest or operation id to confirm: the target id
+    // *is* the thing being reviewed. Rendering fields it does not have would
+    // print "undefined".
+    if (plan.kind === "model_profile_remove") {
+      return [
+        `预览：${plan.kind}`,
+        `目标配置：${plan.target}`,
+        "未执行任何写操作。加 --confirm 才会真正删除。",
+        "",
+      ].join("\n");
+    }
+    return [
+      `预览：${plan.kind}`,
+      `操作 ID：${"request_id" in plan ? plan.request_id : plan.operation_id}`,
+      `确认摘要：${plan.digest}`,
+      "未执行任何写操作。请把 --json 输出保存为 plan 文件，再用对应命令加 --confirm。",
+      "",
+    ].join("\n");
+  }
   const lines = [
     `操作状态：${document.state}`,
     `操作 ID：${document.operation_id ?? "无"}`,
@@ -351,20 +407,98 @@ export function renderFlowText(document: FlowDocument): string {
     if (document.state === "partial" && Array.isArray(accepted)) {
       lines.push(`  已接入：${accepted.join("、")}`);
     }
-    const overrides = document.receipt.override_required_source_ids;
-    if (Array.isArray(overrides)) {
-      lines.push(
-        `  这些来源的目录来自环境变量覆盖，需要确认：${overrides.join("、")}`,
-        "  确认目录无误后加 --confirm-overrides 重新运行。",
-      );
-    }
   }
   lines.push("");
   return lines.join("\n");
 }
 
 export function flowExitCode(document: FlowDocument): number {
-  return ["committed", "recovered"].includes(document.state) ? 0 : 1;
+  return ["preview", "committed", "recovered"].includes(document.state) ? 0 : 1;
+}
+
+export function inspectExecutionPlan(value: unknown): {
+  kind: "source_import" | "model_profile_create";
+  operationId: string;
+  digest: string;
+} | null {
+  const source = validateSourcePlan(value);
+  if (source) {
+    return {
+      kind: source.kind,
+      operationId: source.request_id,
+      digest: source.digest,
+    };
+  }
+  const model = validateModelPlan(value);
+  return model
+    ? {
+        kind: model.kind,
+        operationId: model.operation_id,
+        digest: model.digest,
+      }
+    : null;
+}
+
+function validateSourcePlan(value: unknown): SourceImportPlan | null {
+  const plan = record(value);
+  const requestId = asString(plan?.request_id);
+  if (
+    plan?.schema_version !== 1 ||
+    plan.kind !== "source_import" ||
+    !UUID.test(requestId) ||
+    !Array.isArray(plan.source_ids) ||
+    plan.source_ids.length < 1 ||
+    plan.source_ids.length > 32 ||
+    plan.source_ids.some(
+      (id) => typeof id !== "string" || !SOURCE_ID.test(id),
+    ) ||
+    new Set(plan.source_ids).size !== plan.source_ids.length ||
+    plan.full_rescan !== false ||
+    plan.onboarding !== true ||
+    typeof plan.confirm_environment_overrides !== "boolean" ||
+    typeof plan.digest !== "string"
+  ) {
+    return null;
+  }
+  const sourceIds = plan.source_ids as string[];
+  const roots = stringMap(plan.source_roots, sourceIds);
+  const revisions = numberMap(plan.source_candidate_revisions, sourceIds);
+  if (!roots || !revisions) return null;
+  const body: SourceImportPlanBody = {
+    schema_version: 1,
+    kind: "source_import",
+    request_id: requestId,
+    source_ids: [...sourceIds],
+    source_roots: roots,
+    source_candidate_revisions: revisions,
+    confirm_environment_overrides: plan.confirm_environment_overrides,
+    full_rescan: false,
+    onboarding: true,
+  };
+  const expected = withDigest(body);
+  return timingSafeText(expected.digest, plan.digest) ? expected : null;
+}
+
+function validateModelPlan(value: unknown): ModelCreatePlan | null {
+  const plan = record(value);
+  const operationId = asString(plan?.operation_id);
+  if (
+    plan?.schema_version !== 1 ||
+    plan.kind !== "model_profile_create" ||
+    !UUID.test(operationId) ||
+    typeof plan.digest !== "string"
+  ) {
+    return null;
+  }
+  const config = validateModelConfig(plan.config);
+  if (!config) return null;
+  const expected = withDigest<ModelCreatePlanBody>({
+    schema_version: 1,
+    kind: "model_profile_create",
+    operation_id: operationId,
+    config,
+  });
+  return timingSafeText(expected.digest, plan.digest) ? expected : null;
 }
 
 function validateModelConfig(value: unknown): Record<string, unknown> | null {
@@ -510,6 +644,37 @@ function projectJob(job: ImportJob): Record<string, unknown> {
   };
 }
 
+function withDigest<T extends object>(body: T): T & { digest: string } {
+  return { ...body, digest: digest(body) };
+}
+
+function digest(value: unknown): string {
+  return createHash("sha256").update(canonical(value)).digest("hex");
+}
+
+function canonical(value: unknown): string {
+  if (Array.isArray(value)) return `[${value.map(canonical).join(",")}]`;
+  if (value && typeof value === "object") {
+    return `{${Object.keys(value)
+      .sort()
+      .map(
+        (key) =>
+          `${JSON.stringify(key)}:${canonical((value as Record<string, unknown>)[key])}`,
+      )
+      .join(",")}}`;
+  }
+  return JSON.stringify(value);
+}
+
+function preview(plan: SourceImportPlan | ModelCreatePlan): FlowDocument {
+  return {
+    schema_version: 1,
+    product: PRODUCT,
+    state: "preview",
+    plan,
+  };
+}
+
 function committed(
   operationId: string,
   receipt: Record<string, unknown>,
@@ -602,3 +767,43 @@ function optionalInteger(
       (value as number) <= maximum)
   );
 }
+
+function stringMap(
+  value: unknown,
+  keys: readonly string[],
+): Record<string, string> | null {
+  const map = record(value);
+  if (
+    !map ||
+    Object.keys(map).length !== keys.length ||
+    keys.some((key) => !boundedText(map[key], 256))
+  ) {
+    return null;
+  }
+  return Object.fromEntries(keys.map((key) => [key, map[key] as string]));
+}
+
+function numberMap(
+  value: unknown,
+  allowedKeys: readonly string[],
+): Record<string, number> | null {
+  const map = record(value);
+  if (
+    !map ||
+    Object.entries(map).some(
+      ([key, revision]) =>
+        !allowedKeys.includes(key) ||
+        !Number.isSafeInteger(revision) ||
+        (revision as number) < 0,
+    )
+  ) {
+    return null;
+  }
+  return Object.fromEntries(
+    Object.entries(map).map(([key, revision]) => [key, revision as number]),
+  );
+}
+
+function timingSafeText(expected: string, actual: unknown): boolean {
+  return typeof actual === "string" && expected === actual;
+}

memhub/apps/cli/src/init-attempt-fence.test.ts

@@ -0,0 +1,64 @@
+import path from "node:path";
+import { describe, expect, it } from "vitest";
+
+import { initPlanAttemptPath } from "./cli.js";
+import { interactiveInitAttemptPath } from "./init-attempt.js";
+
+// Regression: `init --source <id> --import` used to pass the literal string
+// `"init"` to `claimPlanAttempt`, which resolved to `<cwd>/init.one-memory-attempt`.
+// Two consequences: the fence was shared across unrelated runs in the same
+// directory, and any unrelated file named `init` could make a valid import
+// report a misleading usage error (exit 2) instead of reading its receipt.
+describe("init import attempt fence", () => {
+  it("lives under the data dir, not the current working directory", () => {
+    const fence = initPlanAttemptPath(
+      "/tmp/example data",
+      "11111111-2222-4333-8444-555555555555",
+    );
+    expect(fence).toBe(
+      path.join(
+        "/tmp/example data",
+        ".cli-init-attempt-11111111-2222-4333-8444-555555555555",
+      ),
+    );
+    expect(path.isAbsolute(fence)).toBe(true);
+    expect(fence).not.toBe("init");
+    // Directly under the data dir: no nested directory that could fail to be
+    // created and turn a valid import into a usage error.
+    expect(path.dirname(fence)).toBe("/tmp/example data");
+  });
+
+  it("is per data dir and per operation, so installs/runs cannot collide", () => {
+    const a = initPlanAttemptPath("/tmp/data-a", "op-1");
+    const b = initPlanAttemptPath("/tmp/data-b", "op-1");
+    const c = initPlanAttemptPath("/tmp/data-a", "op-2");
+    expect(new Set([a, b, c]).size).toBe(3);
+  });
+});
+
+// QA-CLI R3 F1: the interactive wizard passed a CWD-relative singleton
+// (`init` or `<journalDir>/init`) to `claimPlanAttempt`. A stale
+// `init.one-memory-attempt` in the working directory then made every later
+// `memhub init` fail with "交互计划无效 / exit 2".
+describe("interactive init attempt fence", () => {
+  it("lives under the data dir and is unique per operation", () => {
+    const fence = interactiveInitAttemptPath(
+      "/tmp/data",
+      "11111111-2222-4333-8444-555555555555",
+    );
+    expect(fence).toBe(
+      path.join(
+        "/tmp/data",
+        ".cli-init-attempt-11111111-2222-4333-8444-555555555555",
+      ),
+    );
+    expect(path.isAbsolute(fence)).toBe(true);
+    expect(fence).not.toBe("init");
+  });
+
+  it("does not reuse one fence for two distinct plans", () => {
+    const first = interactiveInitAttemptPath("/tmp/data", "op-1");
+    const second = interactiveInitAttemptPath("/tmp/data", "op-2");
+    expect(first).not.toBe(second);
+  });
+});

memhub/apps/cli/src/init-attempt.ts

@@ -0,0 +1,16 @@
+import path from "node:path";
+
+/** Where the interactive `init` wizard keeps its durable attempt fence.
+ *
+ * The wizard originally passed a CWD-relative singleton (`init`) to
+ * `claimPlanAttempt`. That shared one fence across unrelated runs and let a
+ * stale `init.one-memory-attempt` in the working directory turn every later
+ * wizard run into "交互计划无效 / exit 2". Keep the fence under the Runtime's
+ * data dir, keyed by the operation id, exactly like `init --source --import`.
+ */
+export function interactiveInitAttemptPath(
+  dataDir: string,
+  operationId: string,
+): string {
+  return path.join(dataDir, `.cli-init-attempt-${operationId}`);
+}

memhub/apps/cli/src/init-interactive.test.ts

@@ -418,9 +418,9 @@ describe("A2 dual-mode init", () => {
   });
 
   // QA-CLI R3 F1: a stale CWD `init.one-memory-attempt` used to poison every
-  // later wizard run. There are no plan files or attempt fences any more: the
-  // connect request id is the idempotency key Core keeps.
-  it("ignores a stale CWD init fence and writes no fence files", async () => {
+  // later wizard run. The fence now lives under the isolated data dir and is
+  // keyed by the operation id.
+  it("ignores a stale CWD init fence and keeps its fence under the data dir", async () => {
     transport.get.mockImplementation(async (url: string) =>
       url === "/api/v1/sources"
         ? { status: 200, data: [candidate("codex", "Codex")] }
@@ -471,7 +471,7 @@ describe("A2 dual-mode init", () => {
     const dataEntries = await readdir(dataDir);
     expect(
       dataEntries.some((entry) => entry.startsWith(".cli-init-attempt-")),
-    ).toBe(false);
+    ).toBe(true);
   });
 
   it("keeps selected Harnesses frozen without creating history jobs", async () => {
@@ -506,7 +506,7 @@ describe("A2 dual-mode init", () => {
   });
 });
 
-describe("A19 sources connect --all-detected (old spelling: init --all-detected)", () => {
+describe("A19 init --all-detected", () => {
   it("connects every found source in one batch call without prompting", async () => {
     transport.get.mockImplementation(async (url: string) =>
       url === "/api/v1/sources"
@@ -556,7 +556,7 @@ describe("A19 sources connect --all-detected (old spelling: init --all-detected)
     expect(prompter.asked).toBe(0);
     expect(code).toBe(0);
     const document = JSON.parse(streams.value());
-    expect(document.command).toBe("sources connect");
+    expect(document.command).toBe("init");
     expect(document.state).toBe("committed");
     expect(
       document.sources.map((row: { source_id: string }) => row.source_id),

memhub/apps/cli/src/interactive-model-setup.ts

@@ -4,11 +4,18 @@ import type {
   CoreDeleteOperations,
   CoreOperations,
 } from "./core-operations.js";
-import { createModelProfile, type FlowDocument } from "./headless-flows.js";
+import {
+  executeModelProfile,
+  type FlowDocument,
+  planModelProfile,
+} from "./headless-flows.js";
 import { approvalFingerprint, listHosts, readHost } from "./host-flow.js";
 import { parseSelection, type WizardPrompter } from "./init-wizard.js";
-import { startModelProbe } from "./model-probe-flow.js";
-import { activateModelProfile } from "./model-write-flows.js";
+import { executeModelProbe, planModelProbe } from "./model-probe-flow.js";
+import {
+  executeModelProfileActivate,
+  planModelProfileActivate,
+} from "./model-write-flows.js";
 
 type ProviderPreset = {
   id: string;
@@ -352,26 +359,30 @@ export async function runInteractiveModelSetup(
           );
         })
       : new Map<string, string>();
-    const created = await createModelProfile(
-      {
-        name: preset.label,
-        provider_kind: preset.provider_kind,
-        base_url: baseUrl,
-        model,
-        embedding_provider_kind: "local_onnx",
-        embedding_model: "bge-small-zh-v1.5",
-        embedding_dimensions: 512,
-        timeout_seconds: 90,
-        max_concurrency: 4,
-        disable_thinking: true,
-      },
+    const planned = planModelProfile({
+      name: preset.label,
+      provider_kind: preset.provider_kind,
+      base_url: baseUrl,
+      model,
+      embedding_provider_kind: "local_onnx",
+      embedding_model: "bge-small-zh-v1.5",
+      embedding_dimensions: 512,
+      timeout_seconds: 90,
+      max_concurrency: 4,
+      disable_thinking: true,
+    });
+    if (
+      planned.state !== "preview" ||
+      planned.plan.kind !== "model_profile_create"
+    ) {
+      return { state: "failed", code: "model_config_invalid" };
+    }
+    const created = await executeModelProfile(
+      planned.plan,
       apiKey,
       clients.reader,
       clients.operations,
     );
-    if (created.state === "invalid") {
-      return { state: "failed", code: "model_config_invalid" };
-    }
     const profile = receiptProfile(created);
     if (profile === null) {
       prompter.write("模型配置未保存。");
@@ -380,11 +391,18 @@ export async function runInteractiveModelSetup(
     }
 
     try {
-      const probed = await startModelProbe(
+      const probePlan = await planModelProbe(
         clients.reader,
-        clients.operations,
         profile.profile_id,
       );
+      const probed =
+        probePlan.state === "preview"
+          ? await executeModelProbe(
+              probePlan.plan,
+              clients.reader,
+              clients.operations,
+            )
+          : probePlan;
       if (!probePassed(probed)) {
         await clients.operations.delete(
           `/api/v1/model-profiles/${encodeURIComponent(profile.profile_id)}`,
@@ -403,8 +421,17 @@ export async function runInteractiveModelSetup(
       throw error;
     }
 
-    const activated = await activateModelProfile(
-      profile.profile_id,
+    const activation = planModelProfileActivate({
+      profileId: profile.profile_id,
+    });
+    if (
+      activation.state !== "preview" ||
+      activation.plan.kind !== "model_profile_activate"
+    ) {
+      return { state: "failed", code: "model_activate_plan_invalid" };
+    }
+    const activated = await executeModelProfileActivate(
+      activation.plan,
       clients.operations,
     );
     if (activated.state !== "committed") {

memhub/apps/cli/src/jobs-command.test.ts

@@ -101,7 +101,7 @@ describe("memhub jobs", () => {
     expect(transport.post).not.toHaveBeenCalled();
   });
 
-  it("start posts directly, without a preview step", async () => {
+  it("start previews without a POST", async () => {
     const output = captureStdout();
     let code: number;
     try {
@@ -110,14 +110,14 @@ describe("memhub jobs", () => {
       output.restore();
     }
     expect(code!).toBe(0);
-    expect(transport.post).toHaveBeenCalledWith(
-      "/api/v1/import-jobs",
-      { source_id: "codex", operation: "history" },
-      undefined,
-    );
+    expect(transport.post).not.toHaveBeenCalled();
+    expect(JSON.parse(output.value())).toMatchObject({
+      state: "preview",
+      plan: { source_id: "codex", operation: "history" },
+    });
   });
 
-  it("start still accepts a legacy --confirm", async () => {
+  it("start --confirm posts the exact Core request", async () => {
     const output = captureStdout();
     let code: number;
     try {
@@ -146,7 +146,7 @@ describe("memhub jobs", () => {
   });
 
   it.each(["pause", "resume", "cancel"] as const)(
-    "%s posts the action endpoint directly",
+    "%s previews without a POST",
     async (action) => {
       const output = captureStdout();
       let code: number;
@@ -156,11 +156,11 @@ describe("memhub jobs", () => {
         output.restore();
       }
       expect(code!).toBe(0);
-      expect(transport.post).toHaveBeenCalledWith(
-        `/api/v1/import-jobs/job-1/${action}`,
-        {},
-        undefined,
-      );
+      expect(transport.post).not.toHaveBeenCalled();
+      expect(JSON.parse(output.value())).toMatchObject({
+        state: "preview",
+        plan: { job_id: "job-1", action },
+      });
     },
   );
 

memhub/apps/cli/src/log-report.test.ts

@@ -1,4 +1,4 @@
-import { mkdtemp, rm, symlink } from "node:fs/promises";
+import { mkdtemp, rm } from "node:fs/promises";
 import os from "node:os";
 import path from "node:path";
 import { DiagnosticLogger } from "@one-memory/runtime-control";
@@ -41,15 +41,11 @@ it("redacts unsafe details and absolute stack frames from the read surface", ()
     session_id: "11111111-1111-4111-8111-111111111111",
     details: {
       count: 1,
-      reason: "/Users/me/private-query.txt",
-      status: "sk-live-secret-token",
-      source_id: "credential.private",
       prompt: "secret-token-123",
       authorization: "Bearer secret-token-123",
     } as unknown as Record<string, string | number | boolean | null>,
     safe_stack: [
       "packages/runtime-control/src/example.ts:42:7",
-      "packages/runtime/sk-live-secret-token.ts:1:1",
       "/Users/me/private.py:1",
       "C:\\Users\\me\\private.py:1",
     ],
@@ -60,8 +56,6 @@ it("redacts unsafe details and absolute stack frames from the read surface", ()
     "packages/runtime-control/src/example.ts:42:7",
   ]);
   expect(JSON.stringify(redacted)).not.toContain("secret-token-123");
-  expect(JSON.stringify(redacted)).not.toContain("sk-live-secret-token");
-  expect(JSON.stringify(redacted)).not.toContain("credential.private");
   expect(JSON.stringify(redacted)).not.toContain("/Users/me");
   expect(JSON.stringify(redacted)).not.toContain("C:\\\\Users");
 });
@@ -138,27 +132,3 @@ it("follows a newly appended event without stopping Runtime", async () => {
   });
   expect(seen).toEqual(["service.ready", "core.failed"]);
 });
-
-it("fails follow mode when the diagnostic directory is unsafe", async () => {
-  const dataDir = await mkdtemp(
-    path.join(os.tmpdir(), "om-cli-follow-unsafe-"),
-  );
-  const external = await mkdtemp(
-    path.join(os.tmpdir(), "om-cli-follow-external-"),
-  );
-  roots.push(dataDir, external);
-  await symlink(external, path.join(dataDir, "logs"));
-  const query = parseLogQuery(["--follow"]);
-  expect(query).not.toBeNull();
-  if (!query) throw new Error("query_missing");
-  await expect(
-    followLogs({
-      dataDir,
-      query,
-      signal: new AbortController().signal,
-      maxEvents: 1,
-      emit: () => undefined,
-      wait: async () => undefined,
-    }),
-  ).rejects.toThrow("log_directory_unreadable");
-});

memhub/apps/cli/src/log-report.ts

@@ -3,7 +3,6 @@ import path from "node:path";
 import type { DiagnosticEventV1 } from "@one-memory/runtime-control";
 import {
   diagnosticLogFiles,
-  projectDiagnosticEventForSafeOutput,
   readDiagnosticEvents,
 } from "@one-memory/runtime-control";
 
@@ -25,6 +24,54 @@ export interface LogQuery {
 
 const ID = /^[A-Za-z0-9][A-Za-z0-9._:-]{0,255}$/;
 const NAME = /^[a-z][a-z0-9]*(?:[._-][a-z0-9]+){0,15}$/;
+const SAFE_DETAIL_KEYS = new Set([
+  "action",
+  "attempt",
+  "count",
+  "method",
+  "mode",
+  "phase",
+  "platform",
+  "reason",
+  "result_count",
+  "source_id",
+  "spawned",
+  "status",
+  "version",
+  "parent_session_id",
+  "invalid_lines",
+  "truncated",
+  "runtime_state",
+  "core_state",
+  "broker_state",
+  "instance_id",
+  "open_file_count",
+  "memory_bytes",
+  "thread_count",
+  "database_error_count",
+  "file_count",
+  "sqlite_file_count",
+  "byte_file_count",
+  "total_bytes",
+  "copied_bytes",
+  "bytes_per_second",
+  "stored_count",
+  "revised_count",
+  "skipped_count",
+  "error_count",
+  "pending_count",
+  "prepared_count",
+  "queue_depth",
+  "in_flight_count",
+  "call_count",
+  "created_count",
+  "updated_count",
+  "superseded_count",
+  "deleted_count",
+  "operation_kind",
+  "file_kind",
+]);
+
 export function parseLogQuery(arguments_: readonly string[]): LogQuery | null {
   if (arguments_.filter((item) => item === "--json").length > 1) return null;
   const values: Partial<LogQuery> = { errorsOnly: false, follow: false };
@@ -190,13 +237,63 @@ export function renderLogText(
   return `${lines.join("\n")}\n`;
 }
 
-/** Defence in depth for the CLI read surface. Local writers accept arbitrary
- * bounded scalar keys, so every outward read surface must reuse the same
- * field-and-value projection as the support-bundle exporter. */
+/** Defence in depth for the CLI read surface. `DiagnosticLogger` already
+ * allow-lists keys, but a future writer, a manually edited log, or a malformed
+ * line must not turn `memhub logs` into an exfiltration path. */
 export function redactDiagnosticEvent(
   event: DiagnosticEventV1,
 ): DiagnosticEventV1 {
-  return projectDiagnosticEventForSafeOutput(event);
+  const redacted: DiagnosticEventV1 = {
+    schema_version: 1,
+    timestamp: event.timestamp,
+    level: event.level,
+    service: event.service,
+    component: event.component,
+    event: event.event,
+    outcome: event.outcome,
+    session_id: event.session_id,
+    ...(event.trace_id === undefined ? {} : { trace_id: event.trace_id }),
+    ...(event.incident_id === undefined
+      ? {}
+      : { incident_id: event.incident_id }),
+    ...(event.instance_id === undefined
+      ? {}
+      : { instance_id: event.instance_id }),
+    ...(event.operation_id === undefined
+      ? {}
+      : { operation_id: event.operation_id }),
+    ...(event.request_id === undefined ? {} : { request_id: event.request_id }),
+    ...(event.job_id === undefined ? {} : { job_id: event.job_id }),
+    ...(event.task_id === undefined ? {} : { task_id: event.task_id }),
+    ...(event.duration_ms === undefined
+      ? {}
+      : { duration_ms: event.duration_ms }),
+    ...(event.state_before === undefined
+      ? {}
+      : { state_before: event.state_before }),
+    ...(event.state_after === undefined
+      ? {}
+      : { state_after: event.state_after }),
+    ...(event.error_code === undefined ? {} : { error_code: event.error_code }),
+    ...(event.error_type === undefined ? {} : { error_type: event.error_type }),
+    ...(event.safe_stack === undefined
+      ? {}
+      : {
+          safe_stack: event.safe_stack.filter(
+            (frame) =>
+              !frame.startsWith("/") &&
+              !/^[A-Za-z]:\\/.test(frame) &&
+              !frame.includes(".."),
+          ),
+        }),
+  };
+  const details = Object.fromEntries(
+    Object.entries(event.details ?? {}).filter(([key]) =>
+      SAFE_DETAIL_KEYS.has(key),
+    ),
+  );
+  if (Object.keys(details).length > 0) redacted.details = details;
+  return redacted;
 }
 
 export async function followLogs(options: {
@@ -218,7 +315,6 @@ export async function followLogs(options: {
       ...options.query,
       tail: 5_000,
     });
-    if (report.failure) throw new Error(report.failure);
     for (const event of report.events) {
       const identity = JSON.stringify(event);
       if (seen.has(identity)) continue;

memhub/apps/cli/src/memories-cli.test.ts

@@ -1,583 +0,0 @@
-import { mkdtemp, writeFile } from "node:fs/promises";
-import { tmpdir } from "node:os";
-import path from "node:path";
-import { beforeEach, describe, expect, it, vi } from "vitest";
-
-import { run } from "./cli.js";
-
-const transport = vi.hoisted(() => ({
-  get: vi.fn(),
-  post: vi.fn(),
-  put: vi.fn(),
-  patch: vi.fn(),
-  delete: vi.fn(),
-}));
-vi.mock("axios", () => ({
-  default: { create: vi.fn(() => transport), get: vi.fn() },
-}));
-
-const runtime = vi.hoisted(() => ({
-  inspectRuntimeStatus: vi.fn(),
-  discoverRuntimeAttachment: vi.fn(),
-}));
-vi.mock("@one-memory/runtime-control", async (importOriginal) => ({
-  ...(await importOriginal<typeof import("@one-memory/runtime-control")>()),
-  ...runtime,
-}));
-
-const REQUEST = "33333333-3333-4333-8333-333333333333";
-const EVIDENCE = "44444444-4444-4444-8444-444444444444";
-
-function addReceipt(state = "pending", memoryIds: string[] = []) {
-  return {
-    evidence_id: EVIDENCE,
-    text: "Prefers tea",
-    scope: "all-apps",
-    created_at: "2026-10-27T00:00:00Z",
-    state,
-    task_id: null,
-    memory_ids: memoryIds,
-    error: null,
-  };
-}
-
-function memoryRecord(overrides: Record<string, unknown> = {}) {
-  return {
-    memory_id: "exp-1",
-    content: "deploy\nrun make",
-    layer: "experience",
-    status: "active",
-    is_latest: true,
-    supersedes: [],
-    superseded_by: [],
-    tags: [],
-    owner: null,
-    source_raw_ids: [],
-    user_id: "local",
-    agent_id: "",
-    session_id: null,
-    source: "codebuddy",
-    memory_at: null,
-    gmt_created: 1_790_000_000,
-    scene: "working",
-    kind: "experience",
-    variant: "working",
-    task: "deploy",
-    solution: "run make",
-    ...overrides,
-  };
-}
-
-beforeEach(() => {
-  vi.clearAllMocks();
-  transport.get.mockReset();
-  transport.post.mockReset();
-  transport.put.mockReset();
-  transport.patch.mockReset();
-  transport.delete.mockReset();
-  runtime.inspectRuntimeStatus.mockResolvedValue({
-    state: "running",
-    code: "runtime_verified",
-    instanceId: "instance-1",
-    host: "127.0.0.1",
-    port: 8765,
-    version: "1.2.3",
-  });
-  runtime.discoverRuntimeAttachment.mockResolvedValue({
-    instanceId: "instance-1",
-    apiToken: "synthetic-runtime-token",
-    host: "127.0.0.1",
-    port: 8765,
-    servicePid: 4242,
-    health: {
-      status: "ok",
-      service: "one-memory-core",
-      version: "1.2.3",
-      instance_id: "instance-1",
-    },
-  });
-});
-
-describe("memories add", () => {
-  it("adds one memory directly and prints the receipt with its request id", async () => {
-    transport.post.mockResolvedValue({ status: 201, data: addReceipt() });
-    const result = await capturedRun([
-      "memories",
-      "add",
-      "Prefers tea",
-      "--json",
-    ]);
-    expect(result.code).toBe(0);
-    const [url, body] = transport.post.mock.calls[0];
-    expect(url).toBe("/api/v2/memories");
-    expect(body).toMatchObject({ text: "Prefers tea", scope: "all-apps" });
-    expect(body.request_id).toMatch(/^[0-9a-f-]{36}$/);
-    expect(JSON.parse(result.stdout)).toMatchObject({
-      schema_version: 2,
-      command: "memories add",
-      state: "accepted",
-      request_id: body.request_id,
-      receipt: { evidence_id: EVIDENCE, state: "pending" },
-    });
-  });
-
-  it("reuses --request-id so a retry is idempotent, and says so in text", async () => {
-    transport.post.mockResolvedValue({ status: 201, data: addReceipt() });
-    const result = await capturedRun([
-      "memories",
-      "add",
-      "Prefers tea",
-      "--request-id",
-      REQUEST,
-    ]);
-    expect(result.code).toBe(0);
-    expect(transport.post.mock.calls[0][1].request_id).toBe(REQUEST);
-    expect(result.stdout).toContain(`request_id: ${REQUEST}`);
-    expect(result.stdout).toContain(`memhub memories add-status ${REQUEST}`);
-  });
-
-  it("reads the text from a bounded file", async () => {
-    const directory = await mkdtemp(path.join(tmpdir(), "om-memory-add-"));
-    const file = path.join(directory, "memory.txt");
-    await writeFile(file, "Prefers tea\n", { mode: 0o600 });
-    transport.post.mockResolvedValue({ status: 201, data: addReceipt() });
-    const result = await capturedRun([
-      "memories",
-      "add",
-      "--content-file",
-      file,
-      "--json",
-    ]);
-    expect(result.code).toBe(0);
-    expect(transport.post.mock.calls[0][1].text).toBe("Prefers tea");
-  });
-
-  it("refuses bad input before contacting Core", async () => {
-    for (const argv of [
-      ["memories", "add"],
-      ["memories", "add", "a", "--content-file", "/tmp/x"],
-      ["memories", "add", "a", "--request-id", "not-a-uuid"],
-      ["memories", "add", "   "],
-      ["memories", "add", "x".repeat(12_001)],
-    ]) {
-      expect((await capturedRun(argv)).code).toBe(2);
-    }
-    expect(transport.post).not.toHaveBeenCalled();
-    expect(runtime.inspectRuntimeStatus).not.toHaveBeenCalled();
-  });
-
-  it("reports a Core conflict as rejected, on stdout, exit 1", async () => {
-    transport.post.mockResolvedValue({
-      status: 409,
-      data: { detail: "memory_add_conflict" },
-    });
-    const result = await capturedRun([
-      "memories",
-      "add",
-      "Other text",
-      "--request-id",
-      REQUEST,
-      "--json",
-    ]);
-    expect(result.code).toBe(1);
-    expect(JSON.parse(result.stdout)).toMatchObject({
-      state: "rejected",
-      code: "memory_add_conflict",
-      request_id: REQUEST,
-    });
-  });
-
-  it("never reports a malformed success body as accepted", async () => {
-    transport.post.mockResolvedValue({
-      status: 201,
-      data: { evidence_id: "x" },
-    });
-    const result = await capturedRun(["memories", "add", "tea", "--json"]);
-    expect(result.code).toBe(1);
-    expect(JSON.parse(result.stdout).state).toBe("unknown");
-  });
-
-  it("answers a stopped Runtime with exit 3 and writes nothing", async () => {
-    runtime.inspectRuntimeStatus.mockResolvedValue({
-      state: "stopped",
-      code: "runtime_not_running",
-    });
-    const result = await capturedRun(["memories", "add", "tea", "--json"]);
-    expect(result.code).toBe(3);
-    expect(JSON.parse(result.stdout).code).toBe("runtime_not_running");
-    expect(transport.post).not.toHaveBeenCalled();
-  });
-});
-
-describe("memories add-status", () => {
-  it("reads the addition by request id", async () => {
-    transport.get.mockResolvedValue({
-      status: 200,
-      data: addReceipt("ready", ["m-1"]),
-    });
-    const result = await capturedRun([
-      "memories",
-      "add-status",
-      REQUEST,
-      "--json",
-    ]);
-    expect(result.code).toBe(0);
-    expect(transport.get).toHaveBeenCalledWith(
-      `/api/v2/memories/additions/${REQUEST}`,
-      undefined,
-    );
-    expect(JSON.parse(result.stdout)).toMatchObject({
-      command: "memories add-status",
-      state: "accepted",
-      receipt: { state: "ready", memory_ids: ["m-1"] },
-    });
-  });
-
-  it("reports an unknown request id as not_found, exit 1", async () => {
-    transport.get.mockResolvedValue({
-      status: 404,
-      data: { detail: "memory_add_not_found" },
-    });
-    const result = await capturedRun(["memories", "status", REQUEST]);
-    expect(result.code).toBe(1);
-    expect(result.stdout).toContain("未找到该 request id");
-  });
-
-  it("refuses a non-UUID request id", async () => {
-    expect((await capturedRun(["memories", "add-status", "abc"])).code).toBe(2);
-    expect(transport.get).not.toHaveBeenCalled();
-  });
-});
-
-describe("memories update / delete pass the namespace", () => {
-  it("updates an experience with kind, variant and task, directly", async () => {
-    const directory = await mkdtemp(path.join(tmpdir(), "om-memory-update-"));
-    const file = path.join(directory, "solution.txt");
-    await writeFile(file, "run make deploy\n", { mode: 0o600 });
-    transport.put.mockResolvedValue({ status: 200, data: memoryRecord() });
-    const result = await capturedRun([
-      "memories",
-      "update",
-      "exp-1",
-      "--content-file",
-      file,
-      "--kind",
-      "experience",
-      "--variant",
-      "working",
-      "--task",
-      "deploy",
-      "--json",
-    ]);
-    expect(result.code).toBe(0);
-    expect(transport.put).toHaveBeenCalledWith(
-      "/api/v2/memories/exp-1",
-      {
-        content: "run make deploy",
-        kind: "experience",
-        variant: "working",
-        task: "deploy",
-      },
-      undefined,
-    );
-    expect(JSON.parse(result.stdout)).toMatchObject({
-      schema_version: 2,
-      state: "committed",
-      operation: "update",
-    });
-  });
-
-  it("refuses --task on anything but an experience, and a lone --variant", async () => {
-    for (const argv of [
-      ["memories", "update", "m-1", "--content-file", "/tmp/x", "--task", "t"],
-      [
-        "memories",
-        "update",
-        "m-1",
-        "--content-file",
-        "/tmp/x",
-        "--kind",
-        "fact",
-        "--variant",
-        "coding",
-        "--task",
-        "t",
-      ],
-      ["memories", "delete", "m-1", "--variant", "coding"],
-      ["memories", "delete", "m-1", "--kind", "chat", "--variant", "coding"],
-      ["memories", "show", "m-1", "--kind", "nope"],
-    ]) {
-      expect((await capturedRun(argv)).code).toBe(2);
-    }
-    expect(transport.put).not.toHaveBeenCalled();
-    expect(transport.delete).not.toHaveBeenCalled();
-  });
-
-  it("previews a delete without --yes and changes nothing", async () => {
-    const result = await capturedRun([
-      "memories",
-      "delete",
-      "fact-1",
-      "--kind",
-      "fact",
-      "--variant",
-      "coding",
-      "--json",
-    ]);
-    expect(result.code).toBe(0);
-    expect(JSON.parse(result.stdout)).toMatchObject({
-      schema_version: 2,
-      command: "memories delete",
-      state: "preview",
-      target: "fact-1",
-      applied: false,
-    });
-    expect(JSON.parse(result.stdout).next_step).toContain(
-      "--kind fact --variant coding --yes",
-    );
-    expect(transport.delete).not.toHaveBeenCalled();
-    expect(runtime.inspectRuntimeStatus).not.toHaveBeenCalled();
-  });
-
-  it("deletes with --yes (or the legacy --confirm) and names the namespace", async () => {
-    transport.delete.mockResolvedValue({ status: 204, data: "" });
-    for (const flag of ["--yes", "--confirm"]) {
-      const result = await capturedRun([
-        "memories",
-        "delete",
-        "fact-1",
-        "--kind",
-        "fact",
-        "--variant",
-        "coding",
-        flag,
-        "--json",
-      ]);
-      expect(result.code).toBe(0);
-      expect(JSON.parse(result.stdout)).toMatchObject({
-        schema_version: 2,
-        state: "committed",
-        operation: "delete",
-      });
-    }
-    expect(transport.delete).toHaveBeenCalledWith(
-      "/api/v2/memories/fact-1?kind=fact&variant=coding",
-      undefined,
-    );
-  });
-
-  it("explains an ambiguous id instead of a bare code", async () => {
-    transport.delete.mockResolvedValue({
-      status: 409,
-      data: { detail: "memory_id_ambiguous" },
-    });
-    const result = await capturedRun(["memories", "delete", "dup", "--yes"]);
-    expect(result.code).toBe(1);
-    expect(result.stdout).toContain("--kind");
-  });
-
-  it("shows a memory in its namespace", async () => {
-    transport.get.mockResolvedValue({ status: 200, data: memoryRecord() });
-    const result = await capturedRun([
-      "memories",
-      "show",
-      "exp-1",
-      "--kind",
-      "experience",
-      "--variant",
-      "working",
-      "--json",
-    ]);
-    expect(result.code).toBe(0);
-    expect(transport.get).toHaveBeenCalledWith("/api/v2/memories/exp-1", {
-      params: { kind: "experience", variant: "working" },
-    });
-    const document = JSON.parse(result.stdout);
-    expect(document.schema_version).toBe(2);
-    expect(document).not.toHaveProperty("evidence");
-    expect(document).not.toHaveProperty("history");
-    expect(document.memory).toMatchObject({
-      kind: "experience",
-      variant: "working",
-      task: "deploy",
-    });
-  });
-});
-
-describe("memories list filters", () => {
-  const page = {
-    memories: [memoryRecord()],
-    total: 1,
-    limit: 100,
-    offset: 0,
-    search_window: 200,
-    window_id: "w1",
-    window_reset: false,
-  };
-
-  it("sends --scene, --source and --query to the library", async () => {
-    transport.get.mockResolvedValue({ status: 200, data: page });
-    const result = await capturedRun([
-      "memories",
-      "list",
-      "--scene",
-      "working",
-      "--source",
-      "codebuddy",
-      "--query",
-      "deploy",
-      "--json",
-    ]);
-    expect(result.code).toBe(0);
-    expect(transport.get).toHaveBeenCalledWith("/api/v2/memory-library", {
-      params: {
-        offset: 0,
-        limit: 100,
-        scene: "working",
-        source: "codebuddy",
-        query: "deploy",
-      },
-    });
-    const document = JSON.parse(result.stdout);
-    expect(document.schema_version).toBe(2);
-    expect(document.page).toMatchObject({
-      state: "ok",
-      scene: "working",
-      query: "deploy",
-      search_window: 200,
-    });
-    expect(document.memories[0]).toMatchObject({
-      kind: "experience",
-      variant: "working",
-    });
-  });
-
-  it("omits scene for the default all", async () => {
-    transport.get.mockResolvedValue({ status: 200, data: page });
-    await capturedRun(["memories", "list", "--scene", "all", "--json"]);
-    expect(transport.get.mock.calls[0][1].params).not.toHaveProperty("scene");
-  });
-
-  it("validates --status, --scene and --query locally instead of reporting a busy backend", async () => {
-    for (const argv of [
-      ["memories", "list", "--status", "bogus"],
-      ["memories", "list", "--scene", "normal"],
-      ["memories", "list", "--query", "x", "--status", "archived"],
-      ["memories", "list", "--source", "Bad Source"],
-    ]) {
-      expect((await capturedRun(argv)).code).toBe(2);
-    }
-    expect(transport.get).not.toHaveBeenCalled();
-  });
-
-  it("reports a Core 422 as rejected, not as 后台正忙", async () => {
-    transport.get.mockResolvedValue({
-      status: 422,
-      data: { detail: "sdk_search_supports_active_status_only" },
-    });
-    const result = await capturedRun(["memories", "list"]);
-    expect(result.code).toBe(1);
-    expect(result.stdout).not.toContain("后台正忙");
-    expect(result.stdout).toContain("sdk_search_supports_active_status_only");
-  });
-});
-
-describe("graph-width", () => {
-  it("runs a non-destructive decision directly", async () => {
-    transport.post.mockResolvedValue({
-      status: 200,
-      data: { archived_path: null, exported_path: "/tmp/x", mismatch: null },
-    });
-    const result = await capturedRun([
-      "graph-width",
-      "--decision",
-      "export_first",
-      "--json",
-    ]);
-    expect(result.code).toBe(0);
-    expect(transport.post).toHaveBeenCalledWith(
-      "/api/v1/graph-width",
-      { decision: "export_first" },
-      undefined,
-    );
-    expect(JSON.parse(result.stdout).state).toBe("committed");
-  });
-
-  it("previews rebuild_with_new without --yes and applies it with --yes", async () => {
-    const preview = await capturedRun([
-      "graph-width",
-      "--decision",
-      "rebuild_with_new",
-      "--json",
-    ]);
-    expect(preview.code).toBe(0);
-    expect(JSON.parse(preview.stdout)).toMatchObject({
-      state: "preview",
-      applied: false,
-    });
-    expect(transport.post).not.toHaveBeenCalled();
-    transport.post.mockResolvedValue({
-      status: 200,
-      data: { archived_path: "/tmp/old", exported_path: null, mismatch: null },
-    });
-    const applied = await capturedRun([
-      "graph",
-      "width",
-      "--decision",
-      "rebuild_with_new",
-      "--yes",
-      "--json",
-    ]);
-    expect(applied.code).toBe(0);
-    expect(transport.post).toHaveBeenCalledWith(
-      "/api/v1/graph-width",
-      { decision: "rebuild_with_new" },
-      undefined,
-    );
-  });
-});
-
-describe("removed commands", () => {
-  it.each([
-    ["notes", "add", "--content-file", "/tmp/x"],
-    ["notes", "process", REQUEST, "--confirm"],
-    ["calls", "clear", "--all", "--confirm"],
-    ["processing", "extract", "--evidence", REQUEST, "--confirm"],
-    ["extraction", "set", "--window", "6m", "--confirm"],
-    ["import-file", "upload", "--file", "/tmp/x", "--confirm"],
-  ])("%s is an unknown command that writes nothing", async (...argv) => {
-    const result = await capturedRun(argv as string[]);
-    expect(result.code).toBe(2);
-    expect(result.stderr).toContain("未知命令");
-    expect(transport.post).not.toHaveBeenCalled();
-  });
-});
-
-async function capturedRun(arguments_: string[]) {
-  let stdout = "";
-  let stderr = "";
-  const stdoutSpy = vi
-    .spyOn(process.stdout, "write")
-    .mockImplementation((chunk) => {
-      stdout += String(chunk);
-      return true;
-    });
-  const stderrSpy = vi
-    .spyOn(process.stderr, "write")
-    .mockImplementation((chunk) => {
-      stderr += String(chunk);
-      return true;
-    });
-  try {
-    return {
-      code: await run(arguments_, {
-        ONE_MEMORY_DATA_DIR: "/synthetic/data",
-      }),
-      stdout,
-      stderr,
-    };
-  } finally {
-    stdoutSpy.mockRestore();
-    stderrSpy.mockRestore();
-  }
-}

memhub/apps/cli/src/memory-flows.test.ts

@@ -0,0 +1,718 @@
+import { mkdtemp, rm, writeFile } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import { run } from "./cli.js";
+import type { CoreReader } from "./core-client.js";
+import type { CoreOperations } from "./core-operations.js";
+import {
+  executeMemoryMutation,
+  inspectMemoryPlan,
+  memoryPlanAcceptsContent,
+  planExistingMemoryMutation,
+  planMemoryAdd,
+  readMemoryMutationReceipt,
+} from "./memory-flows.js";
+import { readMemoryDetail } from "./memory-report.js";
+
+const transport = vi.hoisted(() => ({
+  get: vi.fn(),
+  post: vi.fn(),
+  put: vi.fn(),
+  patch: vi.fn(),
+  delete: vi.fn(),
+}));
+
+vi.mock("axios", () => ({
+  default: { create: vi.fn(() => transport), get: vi.fn() },
+}));
+
+const runtime = vi.hoisted(() => ({
+  inspectRuntimeStatus: vi.fn(),
+  discoverRuntimeAttachment: vi.fn(),
+  stopRuntimeProcess: vi.fn(),
+}));
+
+vi.mock("@one-memory/runtime-control", async (importOriginal) => ({
+  ...(await importOriginal<typeof import("@one-memory/runtime-control")>()),
+  ...runtime,
+}));
+
+const MEMORY = {
+  memory_id: "memory-1",
+  user_id: "local",
+  kind: "working",
+  status: "confirmed",
+  content: "Existing synthetic memory.",
+  scopes: ["all-apps"],
+  evidence_ids: ["evidence-1"],
+  origin: "extracted",
+  tags: ["synthetic"],
+  revision: 3,
+  created_at: "2026-09-19T00:00:00Z",
+  updated_at: "2026-09-19T00:00:01Z",
+  deleted_at: null,
+};
+
+const DETAIL = {
+  memory: MEMORY,
+  evidence: [
+    {
+      evidence_id: "evidence-1",
+      available: true,
+      source_id: "codex",
+      written_by: "person",
+      created_at: "2026-09-19T00:00:00Z",
+      verbatim: "Synthetic source text.",
+    },
+  ],
+  history: [
+    {
+      revision: 3,
+      action: "create",
+      status: "confirmed",
+      content: "Existing synthetic memory.",
+      scopes: ["all-apps"],
+      created_at: "2026-09-19T00:00:01Z",
+    },
+  ],
+  index_sync: null,
+};
+
+const ATTACHED = {
+  instanceId: "instance-1",
+  apiToken: "synthetic-runtime-token",
+  host: "127.0.0.1" as const,
+  port: 8765,
+  servicePid: 4242,
+  health: {
+    status: "ok",
+    service: "one-memory-core",
+    version: "1.2.3",
+    instance_id: "instance-1",
+  },
+};
+
+beforeEach(() => {
+  vi.clearAllMocks();
+  runtime.inspectRuntimeStatus.mockResolvedValue({
+    state: "running",
+    code: "runtime_verified",
+    instanceId: "instance-1",
+    host: "127.0.0.1",
+    port: 8765,
+    version: "1.2.3",
+  });
+  runtime.discoverRuntimeAttachment.mockResolvedValue(ATTACHED);
+  transport.get.mockImplementation(async (url: string) =>
+    url === "/api/v1/memories/memory-1"
+      ? { status: 200, data: DETAIL }
+      : { status: 404, data: {} },
+  );
+});
+
+describe("memory governance plans", () => {
+  it("plans a manual memory without putting private content in the plan", () => {
+    const result = planMemoryAdd({
+      content: "Private synthetic addition.",
+      memoryKind: "working",
+      scopes: ["all-apps"],
+      evidenceIds: ["evidence-1"],
+    });
+    expect(result.state).toBe("preview");
+    expect(JSON.stringify(result)).not.toContain("Private synthetic addition.");
+    if (result.state !== "preview") throw new Error("preview expected");
+    expect(result.plan).toMatchObject({
+      operation: "add",
+      memory_kind: "working",
+      scopes: ["all-apps"],
+      evidence_ids: ["evidence-1"],
+      content_characters: 27,
+    });
+    expect(inspectMemoryPlan(result.plan)).toMatchObject({
+      operationId: result.plan.request_id,
+      needsContent: true,
+    });
+    expect(
+      memoryPlanAcceptsContent(result.plan, "Private synthetic addition."),
+    ).toBe(true);
+    expect(memoryPlanAcceptsContent(result.plan, "Different content.")).toBe(
+      false,
+    );
+  });
+
+  it("binds correction to the current version, source, author and scopes", async () => {
+    const result = await planExistingMemoryMutation(detailReader(), {
+      operation: "correct",
+      memoryId: "memory-1",
+      content: "Corrected synthetic memory.",
+      scopes: ["codex"],
+    });
+    expect(result.state).toBe("preview");
+    if (result.state !== "preview") throw new Error("preview expected");
+    expect(result.plan).toMatchObject({
+      memory_id: "memory-1",
+      expected_revision: 3,
+      expected_status: "confirmed",
+      expected_origin: "extracted",
+      scopes: ["codex"],
+      current: {
+        revision: 3,
+        evidence: [
+          {
+            evidence_id: "evidence-1",
+            source_id: "codex",
+            written_by: "person",
+          },
+        ],
+      },
+    });
+    expect(JSON.stringify(result)).not.toContain("Corrected synthetic memory.");
+  });
+
+  it("posts a confirmed plan once and validates the bound receipt", async () => {
+    const preview = planMemoryAdd({
+      content: "Private synthetic addition.",
+      memoryKind: "working",
+      scopes: ["all-apps"],
+      evidenceIds: ["evidence-1"],
+    });
+    if (preview.state !== "preview") throw new Error("preview expected");
+    const post = vi.fn().mockResolvedValue({
+      state: "committed",
+      data: {
+        ...MEMORY,
+        memory_id: "created-1",
+        content: "Private synthetic addition.",
+        status: "confirmed",
+        origin: "manual",
+        revision: 1,
+      },
+    });
+    const result = await executeMemoryMutation(
+      preview.plan,
+      "Private synthetic addition.",
+      { post } as CoreOperations,
+    );
+    expect(result.state).toBe("committed");
+    expect(post).toHaveBeenCalledWith(
+      "/api/v1/memories",
+      expect.objectContaining({
+        request_id: preview.plan.request_id,
+        draft: expect.objectContaining({
+          origin: "manual",
+          content: "Private synthetic addition.",
+        }),
+      }),
+    );
+    expect(JSON.stringify(result)).not.toContain("Private synthetic addition.");
+  });
+
+  it("does not take a created memory that is not in effect as the add", async () => {
+    const preview = planMemoryAdd({
+      content: "Private synthetic addition.",
+      memoryKind: "working",
+      scopes: ["all-apps"],
+      evidenceIds: ["evidence-1"],
+    });
+    if (preview.state !== "preview") throw new Error("preview expected");
+    const result = await executeMemoryMutation(
+      preview.plan,
+      "Private synthetic addition.",
+      {
+        post: vi.fn().mockResolvedValue({
+          state: "committed",
+          data: {
+            ...MEMORY,
+            memory_id: "created-1",
+            content: "Private synthetic addition.",
+            status: "deleted",
+            origin: "manual",
+            revision: 1,
+          },
+        }),
+      } as CoreOperations,
+    );
+    expect(result).toMatchObject({
+      state: "unknown",
+      code: "memory_receipt_invalid",
+    });
+  });
+
+  it.each([["delete", "/actions/delete", "deleted"]] as const)(
+    "executes %s against the revision-bound action route",
+    async (operation, suffix, status) => {
+      const preview = await planExistingMemoryMutation(detailReader(), {
+        operation,
+        memoryId: "memory-1",
+      });
+      if (preview.state !== "preview") throw new Error("preview expected");
+      const post = vi.fn().mockResolvedValue({
+        state: "committed",
+        data: { ...MEMORY, status, revision: 4 },
+      });
+      const result = await executeMemoryMutation(preview.plan, undefined, {
+        post,
+      } as CoreOperations);
+      expect(result.state).toBe("committed");
+      expect(post).toHaveBeenCalledWith(`/api/v1/memories/memory-1${suffix}`, {
+        request_id: preview.plan.request_id,
+        expected_revision: 3,
+      });
+    },
+  );
+
+  it("executes correction and scope changes without changing origin", async () => {
+    for (const operation of ["correct", "scope"] as const) {
+      const content =
+        operation === "correct" ? "Corrected synthetic memory." : undefined;
+      const preview = await planExistingMemoryMutation(detailReader(), {
+        operation,
+        memoryId: "memory-1",
+        ...(content ? { content } : {}),
+        scopes: ["codex"],
+      });
+      if (preview.state !== "preview") throw new Error("preview expected");
+      const post = vi.fn().mockResolvedValue({
+        state: "committed",
+        data: {
+          ...MEMORY,
+          content: content ?? MEMORY.content,
+          scopes: ["codex"],
+          revision: 4,
+        },
+      });
+      const result = await executeMemoryMutation(preview.plan, content, {
+        post,
+      } as CoreOperations);
+      expect(result.state).toBe("committed");
+      expect(post.mock.calls[0][0]).toBe(
+        `/api/v1/memories/memory-1/${operation === "scope" ? "scopes" : "correct"}`,
+      );
+      expect(post.mock.calls[0][1]).toMatchObject({
+        request_id: preview.plan.request_id,
+        expected_revision: 3,
+        scopes: ["codex"],
+      });
+    }
+  });
+
+  it("treats a misbound HTTP 200 receipt as unknown", async () => {
+    const preview = await planExistingMemoryMutation(detailReader(), {
+      operation: "delete",
+      memoryId: "memory-1",
+    });
+    if (preview.state !== "preview") throw new Error("preview expected");
+    const result = await executeMemoryMutation(preview.plan, undefined, {
+      post: vi.fn().mockResolvedValue({
+        state: "committed",
+        data: {
+          ...MEMORY,
+          memory_id: "another-memory",
+          status: "deleted",
+          revision: 4,
+        },
+      }),
+    });
+    expect(result).toMatchObject({
+      state: "unknown",
+      code: "memory_receipt_invalid",
+      operation_id: preview.plan.request_id,
+    });
+  });
+
+  it("recovers only an exactly bound governance transaction receipt", async () => {
+    const preview = await planExistingMemoryMutation(detailReader(), {
+      operation: "delete",
+      memoryId: "memory-1",
+    });
+    if (preview.state !== "preview") throw new Error("preview expected");
+    const result = await readMemoryMutationReceipt(
+      receiptReader({
+        schema_version: 2,
+        request_id: preview.plan.request_id,
+        state: "committed",
+        operation: "delete",
+        memory_id: "memory-1",
+        result_revision: 4,
+        result_status: "deleted",
+        memory_state: "deleted",
+        migrated_from: null,
+      }),
+      preview.plan,
+    );
+    expect(result).toMatchObject({
+      state: "recovered",
+      operation_id: preview.plan.request_id,
+      receipt: {
+        operation: "delete",
+        memory_id: "memory-1",
+        result_revision: 4,
+        result_status: "deleted",
+      },
+    });
+    expect(JSON.stringify(result)).not.toContain("content_sha256");
+  });
+
+  it.each([
+    ["operation", "correct"],
+    ["memory_id", "memory-2"],
+    ["result_revision", 5],
+    ["result_status", "confirmed"],
+    ["migrated_from", "reject"],
+  ] as const)("refuses a receipt with wrong %s", async (field, wrong) => {
+    const preview = await planExistingMemoryMutation(detailReader(), {
+      operation: "delete",
+      memoryId: "memory-1",
+    });
+    if (preview.state !== "preview") throw new Error("preview expected");
+    const result = await readMemoryMutationReceipt(
+      receiptReader({
+        schema_version: 2,
+        request_id: preview.plan.request_id,
+        state: "committed",
+        operation: "delete",
+        memory_id: "memory-1",
+        result_revision: 4,
+        result_status: "deleted",
+        memory_state: "deleted",
+        migrated_from: null,
+        [field]: wrong,
+      }),
+      preview.plan,
+    );
+    expect(result).toMatchObject({
+      state: "unknown",
+      code: "memory_mutation_receipt_invalid",
+    });
+  });
+
+  it("keeps not-found, denied and unavailable lookups unresolved", async () => {
+    const preview = await planExistingMemoryMutation(detailReader(), {
+      operation: "delete",
+      memoryId: "memory-1",
+    });
+    if (preview.state !== "preview") throw new Error("preview expected");
+    const notFound = await readMemoryMutationReceipt(
+      receiptReader({
+        schema_version: 2,
+        request_id: preview.plan.request_id,
+        state: "not_found",
+        operation: null,
+        memory_id: null,
+        result_revision: null,
+        result_status: null,
+        memory_state: null,
+        migrated_from: null,
+      }),
+      preview.plan,
+    );
+    expect(notFound).toMatchObject({
+      state: "unknown",
+      code: "memory_mutation_receipt_not_found_after_attempt",
+    });
+    for (const state of ["denied", "unavailable"] as const) {
+      const result = await readMemoryMutationReceipt(
+        async () => ({ state, code: `synthetic_${state}` }),
+        preview.plan,
+      );
+      expect(result).toMatchObject({
+        state: "unknown",
+        code: `memory_mutation_receipt_synthetic_${state}`,
+      });
+    }
+  });
+
+  it("maps an add plan only to the Core create receipt", async () => {
+    const preview = planMemoryAdd({
+      content: "Private synthetic addition.",
+      memoryKind: "working",
+      scopes: ["all-apps"],
+      evidenceIds: ["evidence-1"],
+    });
+    if (preview.state !== "preview") throw new Error("preview expected");
+    const result = await readMemoryMutationReceipt(
+      receiptReader({
+        schema_version: 2,
+        request_id: preview.plan.request_id,
+        state: "committed",
+        operation: "create",
+        memory_id: "created-1",
+        result_revision: 1,
+        result_status: "confirmed",
+        memory_state: "present",
+        migrated_from: null,
+      }),
+      preview.plan,
+    );
+    expect(result).toMatchObject({
+      state: "recovered",
+      receipt: {
+        operation: "create",
+        memory_id: "created-1",
+        result_revision: 1,
+        result_status: "confirmed",
+      },
+    });
+  });
+
+  it("shows bounded history fields including scopes and status", async () => {
+    const result = await readMemoryDetail(detailReader(), "memory-1");
+    expect(result.history[0]).toMatchObject({
+      revision: 3,
+      action: "create",
+      status: "confirmed",
+      scopes: ["all-apps"],
+      content: "Existing synthetic memory.",
+    });
+  });
+});
+
+describe("memory pending fence", () => {
+  it("rejects missing confirmation and invalid plans before any write", async () => {
+    for (const argv of [
+      ["memories", "apply", "--plan-file", "/synthetic/plan", "--json"],
+      ["memories", "plan", "delete", "graph", "--json"],
+      ["memories", "plan", "delete", "memory-1", "--scope", "codex", "--json"],
+      ["memories", "plan", "confirm", "memory-1", "--json"],
+      ["memories", "plan", "reject", "memory-1", "--json"],
+      [
+        "memories",
+        "plan",
+        "add",
+        "--content-file",
+        "/synthetic/content",
+        "--scope",
+        "all-apps",
+        "--json",
+      ],
+    ]) {
+      const streams = captureStreams();
+      try {
+        expect(await run(argv)).toBe(2);
+      } finally {
+        streams.restore();
+      }
+    }
+    expect(transport.post).not.toHaveBeenCalled();
+  });
+
+  it("generates a bounded correction preview without writing", async () => {
+    const directory = await mkdtemp(
+      path.join(os.tmpdir(), "om-memory-preview-"),
+    );
+    const contentFile = path.join(directory, "content.txt");
+    await writeFile(contentFile, "Corrected synthetic memory.");
+    const streams = captureStreams();
+    try {
+      expect(
+        await run([
+          "memories",
+          "plan",
+          "correct",
+          "memory-1",
+          "--content-file",
+          contentFile,
+          "--scope",
+          "codex",
+          "--json",
+        ]),
+      ).toBe(0);
+    } finally {
+      streams.restore();
+      await rm(directory, { recursive: true, force: true });
+    }
+    const output = JSON.parse(streams.stdout());
+    expect(output).toMatchObject({
+      state: "preview",
+      plan: {
+        operation: "correct",
+        memory_id: "memory-1",
+        expected_revision: 3,
+        scopes: ["codex"],
+      },
+    });
+    expect(streams.stdout()).not.toContain("Corrected synthetic memory.");
+    expect(transport.post).not.toHaveBeenCalled();
+  });
+
+  it("checks content identity before claiming the durable fence", async () => {
+    const preview = planMemoryAdd({
+      content: "Private synthetic addition.",
+      memoryKind: "working",
+      scopes: ["all-apps"],
+      evidenceIds: ["evidence-1"],
+    });
+    if (preview.state !== "preview") throw new Error("preview expected");
+    const directory = await mkdtemp(
+      path.join(os.tmpdir(), "om-memory-content-"),
+    );
+    const planFile = path.join(directory, "plan.json");
+    const wrongFile = path.join(directory, "wrong.txt");
+    const correctFile = path.join(directory, "correct.txt");
+    await writeFile(planFile, JSON.stringify(preview));
+    await writeFile(wrongFile, "Different content.");
+    await writeFile(correctFile, "Private synthetic addition.");
+    const wrong = captureStreams();
+    try {
+      expect(
+        await run([
+          "memories",
+          "apply",
+          "--plan-file",
+          planFile,
+          "--content-file",
+          wrongFile,
+          "--confirm",
+          "--json",
+        ]),
+      ).toBe(2);
+    } finally {
+      wrong.restore();
+    }
+    transport.post.mockResolvedValue({
+      status: 200,
+      data: {
+        ...MEMORY,
+        memory_id: "created-1",
+        content: "Private synthetic addition.",
+        status: "confirmed",
+        origin: "manual",
+        revision: 1,
+      },
+    });
+    const correct = captureStreams();
+    try {
+      expect(
+        await run([
+          "memories",
+          "apply",
+          "--plan-file",
+          planFile,
+          "--content-file",
+          correctFile,
+          "--confirm",
+          "--json",
+        ]),
+      ).toBe(0);
+    } finally {
+      correct.restore();
+      await rm(directory, { recursive: true, force: true });
+    }
+    expect(transport.post).toHaveBeenCalledTimes(1);
+  });
+
+  it("recovers an unknown mutation after restart without reposting", async () => {
+    const preview = await planExistingMemoryMutation(detailReader(), {
+      operation: "delete",
+      memoryId: "memory-1",
+    });
+    if (preview.state !== "preview") throw new Error("preview expected");
+    const directory = await mkdtemp(path.join(os.tmpdir(), "om-memory-plan-"));
+    const planFile = path.join(directory, "plan.json");
+    await writeFile(planFile, JSON.stringify(preview));
+    transport.post.mockRejectedValue(new Error("synthetic disconnect"));
+    let receiptLookups = 0;
+    transport.get.mockImplementation(async (url: string) => {
+      if (url === "/api/v1/memories/memory-1") {
+        return { status: 200, data: DETAIL };
+      }
+      if (url === `/api/v1/memory-mutations/${preview.plan.request_id}`) {
+        receiptLookups += 1;
+        if (receiptLookups === 1) throw new Error("synthetic lookup outage");
+        return {
+          status: 200,
+          data: {
+            schema_version: 2,
+            request_id: preview.plan.request_id,
+            state: "committed",
+            operation: "delete",
+            memory_id: "memory-1",
+            result_revision: 4,
+            result_status: "deleted",
+            memory_state: "deleted",
+            migrated_from: null,
+          },
+        };
+      }
+      return { status: 404, data: {} };
+    });
+    const first = captureStreams();
+    try {
+      expect(
+        await run([
+          "memories",
+          "apply",
+          "--plan-file",
+          planFile,
+          "--confirm",
+          "--json",
+        ]),
+      ).toBe(1);
+    } finally {
+      first.restore();
+    }
+    expect(JSON.parse(first.stdout())).toMatchObject({
+      state: "unknown",
+      code: "memory_mutation_receipt_transport_failed",
+    });
+    const second = captureStreams();
+    try {
+      expect(
+        await run([
+          "memories",
+          "apply",
+          "--plan-file",
+          planFile,
+          "--confirm",
+          "--json",
+        ]),
+      ).toBe(0);
+    } finally {
+      second.restore();
+      await rm(directory, { recursive: true, force: true });
+    }
+    expect(JSON.parse(second.stdout())).toMatchObject({
+      state: "recovered",
+      receipt: {
+        operation: "delete",
+        memory_id: "memory-1",
+        result_revision: 4,
+        result_status: "deleted",
+      },
+    });
+    expect(transport.post).toHaveBeenCalledTimes(1);
+    expect(receiptLookups).toBe(2);
+  });
+});
+
+function captureStreams() {
+  let stdout = "";
+  let stderr = "";
+  const out = vi.spyOn(process.stdout, "write").mockImplementation((chunk) => {
+    stdout += String(chunk);
+    return true;
+  });
+  const error = vi
+    .spyOn(process.stderr, "write")
+    .mockImplementation((chunk) => {
+      stderr += String(chunk);
+      return true;
+    });
+  return {
+    stdout: () => stdout,
+    stderr: () => stderr,
+    restore: () => {
+      out.mockRestore();
+      error.mockRestore();
+    },
+  };
+}
+
+function detailReader(): CoreReader {
+  return async <T>() => ({ state: "ok", data: DETAIL as T });
+}
+
+function receiptReader(receipt: unknown): CoreReader {
+  return async <T>() => ({ state: "ok", data: receipt as T });
+}

memhub/apps/cli/src/memory-flows.ts

@@ -0,0 +1,725 @@
+import { createHash, randomUUID, timingSafeEqual } from "node:crypto";
+import type { GovernedMemory } from "@one-memory/contracts";
+import {
+  buildMemoryActionRequest,
+  buildMemoryCorrectRequest,
+  buildMemoryCreateRequest,
+  buildMemoryScopesRequest,
+  parseMemoryReceipt,
+} from "@one-memory/operations";
+import type { CoreReader } from "./core-client.js";
+import type { CoreOperations } from "./core-operations.js";
+import {
+  validateGovernedMemory,
+  validateMemoryDetail,
+} from "./core-responses.js";
+import { isMemoryId } from "./memory-report.js";
+import { PRODUCT } from "./version.js";
+
+const MEMORY_KINDS = [
+  "chat",
+  "working",
+  "coding",
+  "schema",
+  "intention",
+] as const;
+const OPERATIONS = ["add", "correct", "delete", "scope"] as const;
+const MEMORY_ORIGINS = ["extracted", "answered", "agent", "manual"] as const;
+const MUTATION_RECEIPT_KEYS = new Set([
+  "schema_version",
+  "request_id",
+  "state",
+  "operation",
+  "memory_id",
+  "result_revision",
+  "result_status",
+  "memory_state",
+  "migrated_from",
+]);
+const CONTENT_MAX_CHARACTERS = 100_000;
+const ID = /^[A-Za-z0-9][\w.-]{0,127}$/;
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/;
+
+interface PlanBody {
+  schema_version: 1;
+  kind: "memory_mutation";
+  operation: (typeof OPERATIONS)[number];
+  request_id: string;
+  memory_id?: string;
+  expected_revision?: number;
+  expected_status?: string;
+  expected_origin?: string;
+  memory_kind?: (typeof MEMORY_KINDS)[number];
+  scopes?: string[];
+  evidence_ids?: string[];
+  content_sha256?: string;
+  content_characters?: number;
+  current?: {
+    status: string;
+    origin: string;
+    revision: number;
+    scopes: string[];
+    evidence: Array<{
+      evidence_id: string;
+      available: boolean;
+      source_id?: string;
+      written_by?: string;
+    }>;
+  };
+}
+
+export type MemoryMutationPlan = PlanBody & { digest: string };
+
+export type MemoryFlowDocument =
+  | {
+      schema_version: 1;
+      product: string;
+      state: "preview";
+      plan: MemoryMutationPlan;
+    }
+  | {
+      schema_version: 1;
+      product: string;
+      state: "committed" | "recovered";
+      operation_id: string;
+      receipt: Record<string, unknown>;
+    }
+  | {
+      schema_version: 1;
+      product: string;
+      state: "rejected" | "unknown" | "invalid";
+      operation_id?: string;
+      code: string;
+    };
+
+export function parseMemoryContent(bytes: Buffer): string | null {
+  if (bytes.byteLength > CONTENT_MAX_CHARACTERS * 4 + 2) return null;
+  let decoded: string;
+  try {
+    decoded = new TextDecoder("utf-8", { fatal: true }).decode(bytes);
+  } catch {
+    return null;
+  }
+  const content = decoded.replace(/\r?\n$/, "");
+  return content.trim().length > 0 &&
+    [...content].length <= CONTENT_MAX_CHARACTERS &&
+    ![...content].some((character) => {
+      const code = character.charCodeAt(0);
+      return code <= 8 || (code >= 11 && code <= 31) || code === 127;
+    })
+    ? content
+    : null;
+}
+
+export function planMemoryAdd(input: {
+  content: string;
+  memoryKind: string;
+  scopes: string[];
+  evidenceIds: string[];
+}): MemoryFlowDocument {
+  if (
+    !validContent(input.content) ||
+    !oneOf(input.memoryKind, MEMORY_KINDS) ||
+    !validScopes(input.scopes) ||
+    !validIds(input.evidenceIds, 500)
+  ) {
+    return invalid("memory_add_input_invalid");
+  }
+  return preview(
+    withDigest({
+      schema_version: 1,
+      kind: "memory_mutation",
+      operation: "add",
+      request_id: randomUUID(),
+      memory_kind: input.memoryKind,
+      scopes: input.scopes,
+      evidence_ids: input.evidenceIds,
+      ...contentIdentity(input.content),
+    }),
+  );
+}
+
+export async function planExistingMemoryMutation(
+  reader: CoreReader,
+  input: {
+    operation: Exclude<(typeof OPERATIONS)[number], "add">;
+    memoryId: string;
+    content?: string;
+    scopes?: string[];
+  },
+): Promise<MemoryFlowDocument> {
+  if (
+    !isMemoryId(input.memoryId) ||
+    (input.operation === "correct" && input.content === undefined) ||
+    (input.content !== undefined && !validContent(input.content)) ||
+    ((input.operation === "scope" || input.scopes !== undefined) &&
+      !validScopes(input.scopes ?? []))
+  ) {
+    return invalid("memory_plan_input_invalid");
+  }
+  const outcome = await reader<unknown>(`/api/v1/memories/${input.memoryId}`);
+  if (outcome.state !== "ok") {
+    return invalid(`memory_${outcome.state}:${outcome.code}`);
+  }
+  const detail = validateMemoryDetail(outcome.data, input.memoryId);
+  if (!detail) return invalid("memory_response_invalid");
+  const memory = detail.memory;
+  if (memory.status !== "confirmed") {
+    return invalid("memory_operation_not_allowed");
+  }
+  const body: PlanBody = {
+    schema_version: 1,
+    kind: "memory_mutation",
+    operation: input.operation,
+    request_id: randomUUID(),
+    memory_id: memory.memory_id,
+    expected_revision: memory.revision,
+    expected_status: memory.status,
+    expected_origin: memory.origin,
+    ...(input.scopes ? { scopes: input.scopes } : {}),
+    ...(input.content ? contentIdentity(input.content) : {}),
+    current: {
+      status: memory.status,
+      origin: memory.origin,
+      revision: memory.revision,
+      scopes: [...memory.scopes],
+      evidence: detail.evidence.map((item) => ({
+        evidence_id: item.evidence_id,
+        available: item.available,
+        ...(item.source_id ? { source_id: item.source_id } : {}),
+        ...(item.written_by ? { written_by: item.written_by } : {}),
+      })),
+    },
+  };
+  return preview(withDigest(body));
+}
+
+export function inspectMemoryPlan(
+  value: unknown,
+): { operationId: string; digest: string; needsContent: boolean } | null {
+  const plan = validatePlan(value);
+  return plan
+    ? {
+        operationId: plan.request_id,
+        digest: plan.digest,
+        needsContent: plan.operation === "add" || plan.operation === "correct",
+      }
+    : null;
+}
+
+export function memoryPlanAcceptsContent(
+  value: unknown,
+  content: string | undefined,
+): boolean {
+  const plan = validatePlan(value);
+  if (!plan) return false;
+  if (plan.operation !== "add" && plan.operation !== "correct") {
+    return content === undefined;
+  }
+  if (content === undefined) return false;
+  const identity = contentIdentity(content);
+  return (
+    identity.content_sha256 === plan.content_sha256 &&
+    identity.content_characters === plan.content_characters
+  );
+}
+
+export async function executeMemoryMutation(
+  value: unknown,
+  content: string | undefined,
+  operations: CoreOperations,
+  reader?: CoreReader,
+): Promise<MemoryFlowDocument> {
+  const plan = validatePlan(value);
+  if (!plan) return invalid("memory_plan_invalid");
+  if (!memoryPlanAcceptsContent(plan, content)) {
+    return invalid("memory_content_mismatch");
+  }
+  const { path, body } = operationRequest(plan, content);
+  const outcome = await operations.post<unknown>(path, body);
+  if (outcome.state === "rejected") {
+    return {
+      schema_version: 1,
+      product: PRODUCT,
+      state: "rejected",
+      operation_id: plan.request_id,
+      code: outcome.code,
+    };
+  }
+  if (outcome.state === "unknown") {
+    return reader
+      ? readMemoryMutationReceipt(reader, plan)
+      : pending(plan.request_id, outcome.code);
+  }
+  const memory = validateWriteResponse(outcome.data, plan);
+  if (!memory || !matchesReceipt(memory, plan, content)) {
+    return reader
+      ? readMemoryMutationReceipt(reader, plan)
+      : pending(plan.request_id, "memory_receipt_invalid");
+  }
+  return {
+    schema_version: 1,
+    product: PRODUCT,
+    state: "committed",
+    operation_id: plan.request_id,
+    receipt: {
+      memory_id: memory.memory_id,
+      status: memory.status,
+      origin: memory.origin,
+      revision: memory.revision,
+      scopes: memory.scopes,
+      evidence_ids: memory.evidence_ids,
+      content_sha256: contentIdentity(memory.content).content_sha256,
+      content_characters: [...memory.content].length,
+      created_at: memory.created_at,
+      updated_at: memory.updated_at,
+    },
+  };
+}
+
+/**
+ * Validate the write response through the shared `parseMemoryReceipt`, which
+ * owns the GovernedMemory shape and the revision/status binding Core must
+ * satisfy. The CLI keeps only its own plan binding (`matchesReceipt`, which
+ * also checks `origin`, `kind` and the echoed content), so the two surfaces
+ * judge a write response identically and no shape rule is duplicated here.
+ *
+ * `add` creates the first revision and expects `confirmed`; the shared parser
+ * derives that from `expectedRevision: 0`. Every other operation advances the
+ * revision the caller acted against and expects `confirmed` (correct/scope)
+ * or `deleted` (delete).
+ */
+function validateWriteResponse(
+  value: unknown,
+  plan: MemoryMutationPlan,
+): GovernedMemory | null {
+  const expectedStatus = plan.operation === "delete" ? "deleted" : "confirmed";
+  // For `add` there is no id or prior revision to bind yet, so the parser's
+  // own receipt is the only source for both; the plan binding that follows is
+  // what proves the response belongs to this request.
+  const memoryId =
+    plan.operation === "add"
+      ? String((value as { memory_id?: unknown } | null)?.memory_id ?? "")
+      : (plan.memory_id as string);
+  if (memoryId === "") return null;
+  return parseMemoryReceipt(value, {
+    memoryId,
+    expectedRevision:
+      plan.operation === "add" ? 0 : (plan.expected_revision as number),
+    expectedStatus,
+  });
+}
+
+export async function readMemoryMutationReceipt(
+  reader: CoreReader,
+  value: unknown,
+): Promise<MemoryFlowDocument> {
+  const plan = validatePlan(value);
+  if (!plan) return invalid("memory_plan_invalid");
+  const outcome = await reader<unknown>(
+    `/api/v1/memory-mutations/${encodeURIComponent(plan.request_id)}`,
+  );
+  if (outcome.state !== "ok") {
+    return pending(plan.request_id, `memory_mutation_receipt_${outcome.code}`);
+  }
+  const receipt = validateMutationReceipt(outcome.data, plan);
+  if (receipt === "not_found") {
+    return pending(
+      plan.request_id,
+      "memory_mutation_receipt_not_found_after_attempt",
+    );
+  }
+  if (!receipt) {
+    return pending(plan.request_id, "memory_mutation_receipt_invalid");
+  }
+  return {
+    schema_version: 1,
+    product: PRODUCT,
+    state: "recovered",
+    operation_id: plan.request_id,
+    receipt,
+  };
+}
+
+export function memoryFlowExitCode(document: MemoryFlowDocument): number {
+  return ["preview", "committed", "recovered"].includes(document.state) ? 0 : 1;
+}
+
+export function renderMemoryFlowText(document: MemoryFlowDocument): string {
+  if (document.state === "preview") {
+    const plan = document.plan;
+    const lines = [
+      `记忆操作预览：${plan.operation}`,
+      `request_id：${plan.request_id}`,
+    ];
+    if (plan.memory_id) lines.push(`memory_id：${plan.memory_id}`);
+    if (plan.expected_revision) {
+      lines.push(
+        `当前版本：${plan.expected_revision}  状态：${plan.expected_status}  来源方式：${plan.expected_origin}`,
+      );
+    }
+    if (plan.scopes) lines.push(`使用范围：${plan.scopes.join(",")}`);
+    if (plan.current) {
+      for (const evidence of plan.current.evidence) {
+        lines.push(
+          `证据 ${evidence.evidence_id}：source=${evidence.source_id ?? "unknown"} author=${evidence.written_by ?? "unknown"} available=${evidence.available}`,
+        );
+      }
+    }
+    if (plan.content_characters !== undefined) {
+      lines.push(
+        `正文：${plan.content_characters} 字符，sha256=${plan.content_sha256}`,
+      );
+    }
+    lines.push("尚未写入；保存 JSON 计划后用 memories apply --confirm 执行。");
+    return `${lines.join("\n")}\n`;
+  }
+  if (document.state === "committed" || document.state === "recovered") {
+    return `记忆操作${document.state === "recovered" ? "已从治理回执恢复" : "已提交"}：${document.operation_id}\n${JSON.stringify(document.receipt)}\n`;
+  }
+  return `记忆操作未完成：${document.state}（${"code" in document ? document.code : "memory_operation_state_invalid"}）${document.operation_id ? ` request_id=${document.operation_id}` : ""}\n`;
+}
+
+function operationRequest(
+  plan: MemoryMutationPlan,
+  content: string | undefined,
+): { path: string; body: Record<string, unknown> } {
+  if (plan.operation === "add") {
+    // The shared create builder is the Web console's manual-add body, which
+    // always creates `chat` (the Web has no kind picker). The CLI exposes
+    // `--kind`, so it builds through the same builder and then sets the kind,
+    // keeping every other field (user_id/scope/evidence/origin) shared.
+    const request = buildMemoryCreateRequest(
+      {
+        content: content as string,
+        scopes: plan.scopes ?? [],
+        evidence_ids: plan.evidence_ids ?? [],
+        origin: "manual",
+      },
+      plan.request_id,
+    );
+    const draft = request.body.draft as Record<string, unknown>;
+    draft.kind = plan.memory_kind;
+    return { path: request.path, body: request.body };
+  }
+  if (plan.operation === "correct") {
+    return buildMemoryCorrectRequest(
+      plan.memory_id as string,
+      plan.expected_revision as number,
+      content as string,
+      plan.scopes,
+      plan.request_id,
+    );
+  }
+  if (plan.operation === "scope") {
+    return buildMemoryScopesRequest(
+      plan.memory_id as string,
+      plan.expected_revision as number,
+      plan.scopes ?? [],
+      plan.request_id,
+    );
+  }
+  return buildMemoryActionRequest(
+    plan.memory_id as string,
+    plan.operation,
+    plan.expected_revision as number,
+    plan.request_id,
+  );
+}
+
+function matchesReceipt(
+  memory: GovernedMemory,
+  plan: MemoryMutationPlan,
+  content: string | undefined,
+): boolean {
+  if (plan.operation === "add") {
+    return (
+      memory.status === "confirmed" &&
+      memory.origin === "manual" &&
+      memory.revision === 1 &&
+      memory.kind === plan.memory_kind &&
+      same(memory.scopes, plan.scopes ?? []) &&
+      same(memory.evidence_ids, plan.evidence_ids ?? []) &&
+      memory.content === content
+    );
+  }
+  if (
+    memory.memory_id !== plan.memory_id ||
+    memory.revision !== (plan.expected_revision as number) + 1 ||
+    memory.origin !== plan.expected_origin
+  ) {
+    return false;
+  }
+  if (plan.operation === "delete" && memory.status !== "deleted") return false;
+  if (
+    (plan.operation === "correct" || plan.operation === "scope") &&
+    memory.status !== plan.expected_status
+  ) {
+    return false;
+  }
+  if (plan.operation === "correct" && memory.content !== content) return false;
+  const expectedScopes =
+    plan.scopes ?? (plan.current?.scopes as string[] | undefined);
+  return expectedScopes ? same(memory.scopes, expectedScopes) : true;
+}
+
+function validateMutationReceipt(
+  value: unknown,
+  plan: MemoryMutationPlan,
+): Record<string, unknown> | "not_found" | null {
+  const receipt = record(value);
+  if (
+    !receipt ||
+    Object.keys(receipt).length !== MUTATION_RECEIPT_KEYS.size ||
+    Object.keys(receipt).some((key) => !MUTATION_RECEIPT_KEYS.has(key)) ||
+    receipt.schema_version !== 2 ||
+    receipt.request_id !== plan.request_id
+  ) {
+    return null;
+  }
+  if (receipt.state === "not_found") {
+    return [
+      receipt.operation,
+      receipt.memory_id,
+      receipt.result_revision,
+      receipt.result_status,
+      receipt.memory_state,
+      receipt.migrated_from,
+    ].every((item) => item === null)
+      ? "not_found"
+      : null;
+  }
+  const expectedOperation =
+    plan.operation === "add"
+      ? "create"
+      : plan.operation === "scope"
+        ? "set_scopes"
+        : plan.operation;
+  const expectedRevision =
+    plan.operation === "add" ? 1 : (plan.expected_revision as number) + 1;
+  const expectedStatus = plan.operation === "delete" ? "deleted" : "confirmed";
+  // A migrated receipt records an operation from before v2; no plan made
+  // today can have produced it.
+  if (
+    receipt.state !== "committed" ||
+    receipt.migrated_from !== null ||
+    receipt.operation !== expectedOperation ||
+    typeof receipt.memory_id !== "string" ||
+    !isMemoryId(receipt.memory_id) ||
+    (plan.memory_id !== undefined && receipt.memory_id !== plan.memory_id) ||
+    receipt.result_revision !== expectedRevision ||
+    receipt.result_status !== expectedStatus ||
+    !["present", "deleted"].includes(String(receipt.memory_state))
+  ) {
+    return null;
+  }
+  return {
+    schema_version: 2,
+    request_id: plan.request_id,
+    state: "committed",
+    operation: expectedOperation,
+    memory_id: receipt.memory_id,
+    result_revision: expectedRevision,
+    result_status: expectedStatus,
+    memory_state: receipt.memory_state,
+    proof_scope: "governance_transaction_only",
+    downstream_sync_verified: false,
+    payload_fingerprint_verified: false,
+  };
+}
+
+function validatePlan(value: unknown): MemoryMutationPlan | null {
+  const plan = record(value);
+  if (
+    plan?.schema_version !== 1 ||
+    plan.kind !== "memory_mutation" ||
+    !oneOf(plan.operation, OPERATIONS) ||
+    typeof plan.request_id !== "string" ||
+    !UUID.test(plan.request_id) ||
+    typeof plan.digest !== "string"
+  ) {
+    return null;
+  }
+  const body = { ...plan };
+  delete body.digest;
+  const expected = withDigest(body as unknown as PlanBody);
+  if (!safeEqual(expected.digest, plan.digest)) return null;
+  if (plan.operation === "add") {
+    if (
+      !oneOf(plan.memory_kind, MEMORY_KINDS) ||
+      !validScopes(plan.scopes) ||
+      !validIds(plan.evidence_ids, 500) ||
+      !contentFields(plan)
+    ) {
+      return null;
+    }
+  } else if (
+    typeof plan.memory_id !== "string" ||
+    !isMemoryId(plan.memory_id) ||
+    !Number.isSafeInteger(plan.expected_revision) ||
+    (plan.expected_revision as number) < 1 ||
+    plan.expected_status !== "confirmed" ||
+    !oneOf(plan.expected_origin, MEMORY_ORIGINS) ||
+    !validCurrent(plan) ||
+    (plan.operation === "correct" && !contentFields(plan)) ||
+    ((plan.operation === "scope" || plan.scopes !== undefined) &&
+      !validScopes(plan.scopes))
+  ) {
+    return null;
+  }
+  return plan as unknown as MemoryMutationPlan;
+}
+
+function contentFields(plan: Record<string, unknown>): boolean {
+  return (
+    typeof plan.content_sha256 === "string" &&
+    /^[0-9a-f]{64}$/.test(plan.content_sha256) &&
+    Number.isSafeInteger(plan.content_characters) &&
+    (plan.content_characters as number) >= 1 &&
+    (plan.content_characters as number) <= CONTENT_MAX_CHARACTERS
+  );
+}
+
+function validCurrent(plan: Record<string, unknown>): boolean {
+  const current = record(plan.current);
+  if (
+    !current ||
+    current.status !== plan.expected_status ||
+    current.origin !== plan.expected_origin ||
+    current.revision !== plan.expected_revision ||
+    !validScopes(current.scopes) ||
+    !Array.isArray(current.evidence) ||
+    current.evidence.length < 1 ||
+    current.evidence.length > 500
+  ) {
+    return false;
+  }
+  return current.evidence.every((value) => {
+    const evidence = record(value);
+    return (
+      evidence !== null &&
+      typeof evidence.evidence_id === "string" &&
+      ID.test(evidence.evidence_id) &&
+      typeof evidence.available === "boolean" &&
+      (evidence.source_id === undefined ||
+        (typeof evidence.source_id === "string" &&
+          evidence.source_id.length <= 128)) &&
+      (evidence.written_by === undefined ||
+        (typeof evidence.written_by === "string" &&
+          evidence.written_by.length <= 256))
+    );
+  });
+}
+
+function contentIdentity(content: string): {
+  content_sha256: string;
+  content_characters: number;
+} {
+  return {
+    content_sha256: createHash("sha256").update(content, "utf8").digest("hex"),
+    content_characters: [...content].length,
+  };
+}
+
+function validContent(content: string): boolean {
+  return (
+    content.trim().length > 0 &&
+    [...content].length <= CONTENT_MAX_CHARACTERS &&
+    ![...content].some((character) => {
+      const code = character.charCodeAt(0);
+      return code <= 8 || (code >= 11 && code <= 31) || code === 127;
+    })
+  );
+}
+
+function validScopes(value: unknown): value is string[] {
+  if (
+    !Array.isArray(value) ||
+    value.length < 1 ||
+    value.length > 128 ||
+    new Set(value).size !== value.length ||
+    value.some(
+      (scope) =>
+        typeof scope !== "string" ||
+        scope.trim() !== scope ||
+        scope.length < 1 ||
+        scope.length > 512 ||
+        scope === "*",
+    )
+  ) {
+    return false;
+  }
+  return !value.includes("private") || value.length === 1;
+}
+
+function validIds(value: unknown, maximum: number): value is string[] {
+  return (
+    Array.isArray(value) &&
+    value.length >= 1 &&
+    value.length <= maximum &&
+    new Set(value).size === value.length &&
+    value.every((item) => typeof item === "string" && ID.test(item))
+  );
+}
+
+function withDigest(body: PlanBody): MemoryMutationPlan {
+  return {
+    ...body,
+    digest: createHash("sha256")
+      .update(JSON.stringify(body), "utf8")
+      .digest("hex"),
+  };
+}
+
+function preview(plan: MemoryMutationPlan): MemoryFlowDocument {
+  return {
+    schema_version: 1,
+    product: PRODUCT,
+    state: "preview",
+    plan,
+  };
+}
+
+function invalid(code: string): MemoryFlowDocument {
+  return {
+    schema_version: 1,
+    product: PRODUCT,
+    state: "invalid",
+    code,
+  };
+}
+
+function pending(operationId: string, code: string): MemoryFlowDocument {
+  return {
+    schema_version: 1,
+    product: PRODUCT,
+    state: "unknown",
+    operation_id: operationId,
+    code,
+  };
+}
+
+function same(left: readonly string[], right: readonly string[]): boolean {
+  return (
+    left.length === right.length &&
+    left.every((value, index) => value === right[index])
+  );
+}
+
+function safeEqual(left: string, right: string): boolean {
+  if (left.length !== right.length) return false;
+  return timingSafeEqual(Buffer.from(left), Buffer.from(right));
+}
+
+function oneOf<const T extends readonly string[]>(
+  value: unknown,
+  values: T,
+): value is T[number] {
+  return typeof value === "string" && values.includes(value as T[number]);
+}
+
+function record(value: unknown): Record<string, unknown> | null {
+  return value !== null && typeof value === "object" && !Array.isArray(value)
+    ? (value as Record<string, unknown>)
+    : null;
+}

memhub/apps/cli/src/memory-receipt-contract.test.ts

@@ -0,0 +1,214 @@
+import { readFileSync } from "node:fs";
+import { describe, expect, it } from "vitest";
+import type { CoreReader } from "./core-client.js";
+import {
+  planExistingMemoryMutation,
+  planMemoryAdd,
+  readMemoryMutationReceipt,
+} from "./memory-flows.js";
+
+// Written by a real Core and checked against it on the Core side, so these are
+// the receipts the CLI meets in use rather than ones shaped to fit the parser.
+const FIXTURE = JSON.parse(
+  readFileSync(
+    new URL(
+      "../../../packages/contracts/fixtures/memory-mutation-receipts.v2.json",
+      import.meta.url,
+    ),
+    "utf8",
+  ),
+) as { receipts: Record<"add" | "correct" | "scope" | "delete", Receipt> };
+
+interface Receipt {
+  schema_version: number;
+  request_id: string;
+  memory_id: string;
+  result_revision: number;
+  result_status: string;
+  operation: string;
+}
+
+function reader(data: unknown): CoreReader {
+  return async <T>() => ({ state: "ok", data: data as T });
+}
+
+function detail(sample: Receipt) {
+  const revision = sample.result_revision - 1;
+  return {
+    memory: {
+      memory_id: sample.memory_id,
+      user_id: "local",
+      kind: "chat",
+      status: "confirmed",
+      content: "Synthetic memory.",
+      scopes: ["all-apps"],
+      evidence_ids: ["evidence-1"],
+      origin: "manual",
+      tags: [],
+      revision,
+      created_at: "2026-09-19T00:00:00Z",
+      updated_at: "2026-09-19T00:00:01Z",
+      deleted_at: null,
+    },
+    evidence: [
+      {
+        evidence_id: "evidence-1",
+        available: true,
+        source_id: "fixture",
+        written_by: "person",
+        created_at: "2026-09-19T00:00:00Z",
+        verbatim: "Synthetic source text.",
+      },
+    ],
+    history: [
+      {
+        revision,
+        action: "create",
+        status: "confirmed",
+        content: "Synthetic memory.",
+        scopes: ["all-apps"],
+        created_at: "2026-09-19T00:00:01Z",
+      },
+    ],
+    index_sync: null,
+  };
+}
+
+describe("memory mutation receipt v2 from Core", () => {
+  it("recovers an add from the receipt Core returns for a create", async () => {
+    const sample = FIXTURE.receipts.add;
+    expect(sample.schema_version).toBe(2);
+    const preview = planMemoryAdd({
+      content: "Synthetic memory.",
+      memoryKind: "chat",
+      scopes: ["all-apps"],
+      evidenceIds: ["evidence-1"],
+    });
+    if (preview.state !== "preview") throw new Error("preview expected");
+    // The request id is the one binding a receipt to its plan; the plan picks it.
+    const result = await readMemoryMutationReceipt(
+      reader({ ...sample, request_id: preview.plan.request_id }),
+      preview.plan,
+    );
+    expect(result).toMatchObject({
+      state: "recovered",
+      receipt: {
+        schema_version: 2,
+        operation: "create",
+        memory_id: sample.memory_id,
+        result_revision: 1,
+        result_status: "confirmed",
+        memory_state: "present",
+      },
+    });
+  });
+
+  it.each<
+    ["correct" | "scope" | "delete", { content?: string; scopes?: string[] }]
+  >([
+    ["correct", { content: "Corrected synthetic memory." }],
+    ["scope", { scopes: ["codex"] }],
+    ["delete", {}],
+  ])(
+    "recovers %s from the receipt Core returns for it",
+    async (operation, extra) => {
+      const sample = FIXTURE.receipts[operation];
+      const preview = await planExistingMemoryMutation(reader(detail(sample)), {
+        operation,
+        memoryId: sample.memory_id,
+        ...extra,
+      });
+      if (preview.state !== "preview") {
+        throw new Error(`preview expected: ${JSON.stringify(preview)}`);
+      }
+      const result = await readMemoryMutationReceipt(
+        reader({ ...sample, request_id: preview.plan.request_id }),
+        preview.plan,
+      );
+      expect(result).toMatchObject({
+        state: "recovered",
+        receipt: {
+          schema_version: 2,
+          operation: sample.operation,
+          memory_id: sample.memory_id,
+          result_revision: sample.result_revision,
+          result_status: sample.result_status,
+        },
+      });
+    },
+  );
+
+  it("does not take a v1 receipt for a v2 one", async () => {
+    const sample = FIXTURE.receipts.delete;
+    const preview = await planExistingMemoryMutation(reader(detail(sample)), {
+      operation: "delete",
+      memoryId: sample.memory_id,
+    });
+    if (preview.state !== "preview") throw new Error("preview expected");
+    const { migrated_from: _dropped, ...v1 } = sample as Receipt & {
+      migrated_from: null;
+    };
+    // As v1 was, and with v2's fields but v1's number: either alone is refused.
+    for (const receipt of [
+      { ...v1, schema_version: 1 },
+      { ...sample, schema_version: 1 },
+    ]) {
+      const result = await readMemoryMutationReceipt(
+        reader({ ...receipt, request_id: preview.plan.request_id }),
+        preview.plan,
+      );
+      expect(result).toMatchObject({
+        state: "unknown",
+        code: "memory_mutation_receipt_invalid",
+      });
+    }
+  });
+
+  it("does not take a not-found receipt that names a migrated operation", async () => {
+    const sample = FIXTURE.receipts.delete;
+    const preview = await planExistingMemoryMutation(reader(detail(sample)), {
+      operation: "delete",
+      memoryId: sample.memory_id,
+    });
+    if (preview.state !== "preview") throw new Error("preview expected");
+    const notFound = {
+      schema_version: 2,
+      request_id: preview.plan.request_id,
+      state: "not_found",
+      operation: null,
+      memory_id: null,
+      result_revision: null,
+      result_status: null,
+      memory_state: null,
+    };
+    expect(
+      await readMemoryMutationReceipt(
+        reader({ ...notFound, migrated_from: null }),
+        preview.plan,
+      ),
+    ).toMatchObject({
+      code: "memory_mutation_receipt_not_found_after_attempt",
+    });
+    expect(
+      await readMemoryMutationReceipt(
+        reader({ ...notFound, migrated_from: "reject" }),
+        preview.plan,
+      ),
+    ).toMatchObject({ code: "memory_mutation_receipt_invalid" });
+  });
+
+  it("plans nothing on a memory that is not in effect", async () => {
+    const sample = FIXTURE.receipts.delete;
+    const superseded = detail(sample);
+    superseded.memory.status = "superseded";
+    superseded.history[0].status = "superseded";
+    const result = await planExistingMemoryMutation(reader(superseded), {
+      operation: "delete",
+      memoryId: sample.memory_id,
+    });
+    expect(result).toMatchObject({
+      state: "invalid",
+      code: "memory_operation_not_allowed",
+    });
+  });
+});

memhub/apps/cli/src/memory-report.ts

@@ -1,17 +1,6 @@
-import { randomUUID } from "node:crypto";
-import type {
-  MemoryAddReceipt,
-  SdkMemoryPage,
-  SdkMemoryRecord,
-} from "@one-memory/contracts";
-import {
-  buildMemoryAddRequest,
-  MemoryAddInputError,
-  memoryAddStatusPath,
-  parseMemoryAddReceipt,
-} from "@one-memory/operations";
+import type { GovernedMemory } from "@one-memory/contracts";
 import { type CoreReader, RESERVED_MEMORY_SEGMENTS } from "./core-client.js";
-import type { CoreOperations } from "./core-operations.js";
+import { validateMemoryDetail, validateMemoryPage } from "./core-responses.js";
 import { PRODUCT } from "./version.js";
 
 /** Output budget: a long memory is shortened visibly, never dropped silently. */
@@ -27,75 +16,27 @@ export function isMemoryId(value: string): boolean {
   );
 }
 
-const CONTENT_MAX_CHARACTERS = 100_000;
-
-/** A memory body read from `--content-file`: UTF-8, non-blank, bounded, and
- * free of control characters other than tab and newline. */
-export function parseMemoryContent(bytes: Buffer): string | null {
-  if (bytes.byteLength > CONTENT_MAX_CHARACTERS * 4 + 2) return null;
-  let decoded: string;
-  try {
-    decoded = new TextDecoder("utf-8", { fatal: true }).decode(bytes);
-  } catch {
-    return null;
-  }
-  const content = decoded.replace(/\r?\n$/, "");
-  return content.trim().length > 0 &&
-    [...content].length <= CONTENT_MAX_CHARACTERS &&
-    ![...content].some((character) => {
-      const code = character.charCodeAt(0);
-      return code <= 8 || (code >= 11 && code <= 31) || code === 127;
-    })
-    ? content
-    : null;
-}
-
-export const MEMORY_SCENES = ["all", "chat", "working", "coding"] as const;
-export type MemoryScene = (typeof MEMORY_SCENES)[number];
-export const MEMORY_KINDS = ["chat", "experience", "fact"] as const;
-export type MemoryKind = (typeof MEMORY_KINDS)[number];
-export const MEMORY_VARIANTS = ["working", "coding"] as const;
-export type MemoryVariant = (typeof MEMORY_VARIANTS)[number];
-
-/** Which SDK namespace a memory lives in. A chat memory needs neither; a
- * working/coding experience or fact needs both so Core does not have to guess
- * (an id present in two namespaces is refused as ambiguous). */
-export interface MemoryNamespace {
-  kind?: MemoryKind;
-  variant?: MemoryVariant;
-}
-
-export function namespaceParameters(
-  namespace: MemoryNamespace,
-): Record<string, string> {
-  return {
-    ...(namespace.kind === undefined ? {} : { kind: namespace.kind }),
-    ...(namespace.variant === undefined ? {} : { variant: namespace.variant }),
-  };
-}
-
 export interface MemoryQuery {
   query?: string;
   status?: string;
   source?: string;
-  scene?: MemoryScene;
   offset: number;
   limit: number;
 }
 
-/** Every `memories` document is schema 2: list/show share it with
- * add/update/delete, and the v1-era `evidence`/`history` fields are gone. */
 export interface MemoryPageDocument {
-  schema_version: 2;
+  schema_version: 1;
   product: string;
   page: Record<string, unknown>;
   memories: Record<string, unknown>[];
 }
 
 export interface MemoryDetailDocument {
-  schema_version: 2;
+  schema_version: 1;
   product: string;
   memory: Record<string, unknown>;
+  evidence: Record<string, unknown>[];
+  history: Record<string, unknown>[];
 }
 
 export async function readMemoryPage(
@@ -106,47 +47,38 @@ export async function readMemoryPage(
     offset: query.offset,
     limit: query.limit,
   };
-  if (query.status !== undefined) parameters.statuses = query.status;
-  if (query.source !== undefined) parameters.source = query.source;
   if (query.query !== undefined) parameters.query = query.query;
-  if (query.scene !== undefined && query.scene !== "all") {
-    parameters.scene = query.scene;
-  }
-  const outcome = await reader<unknown>("/api/v2/memory-library", parameters);
+  if (query.status !== undefined) parameters.status = query.status;
+  if (query.source !== undefined) parameters.source = query.source;
+  const outcome = await reader<unknown>("/api/v1/memory-library", parameters);
   if (outcome.state !== "ok") {
     return {
-      schema_version: 2,
+      schema_version: 1,
       product: PRODUCT,
       page: { state: outcome.state, code: outcome.code },
       memories: [],
     };
   }
-  const page = sdkMemoryPage(outcome.data);
+  const page = validateMemoryPage(outcome.data, query);
   if (page === null) {
     return {
-      schema_version: 2,
+      schema_version: 1,
       product: PRODUCT,
       page: { state: "invalid", code: "response_invalid" },
       memories: [],
     };
   }
-  const items = page.memories;
+  const items = page.items;
   return {
-    schema_version: 2,
+    schema_version: 1,
     product: PRODUCT,
     page: {
       state: "ok",
-      scene: query.scene ?? "all",
-      ...(query.query === undefined ? {} : { query: query.query }),
       total: page.total,
       offset: page.offset,
       limit: page.limit,
       returned: items.length,
       has_more: page.offset + items.length < page.total,
-      // A keyword search only looks among this many most relevant memories.
-      ...(typeof page.search_window === "number"
-        ? { search_window: page.search_window }
-        : {}),
     },
     memories: items.map((item) => describeMemory(item)),
   };
@@ -155,195 +87,66 @@ export async function readMemoryPage(
 export async function readMemoryDetail(
   reader: CoreReader,
   memoryId: string,
-  namespace: MemoryNamespace = {},
 ): Promise<MemoryDetailDocument> {
-  const parameters = namespaceParameters(namespace);
-  const outcome = await reader<unknown>(
-    `/api/v2/memories/${memoryId}`,
-    Object.keys(parameters).length > 0 ? parameters : undefined,
-  );
+  const outcome = await reader<unknown>(`/api/v1/memories/${memoryId}`);
   if (outcome.state !== "ok") {
     return {
-      schema_version: 2,
+      schema_version: 1,
       product: PRODUCT,
       memory: { state: outcome.state, code: outcome.code },
+      evidence: [],
+      history: [],
     };
   }
-  const memory = sdkMemory(outcome.data);
-  if (memory === null || memory.memory_id !== memoryId) {
+  const detail = validateMemoryDetail(outcome.data, memoryId);
+  if (detail === null) {
     return {
-      schema_version: 2,
+      schema_version: 1,
       product: PRODUCT,
       memory: { state: "invalid", code: "response_invalid" },
+      evidence: [],
+      history: [],
     };
   }
   return {
-    schema_version: 2,
+    schema_version: 1,
     product: PRODUCT,
-    memory: { state: "ok", ...describeMemory(memory) },
+    memory: { state: "ok", ...describeMemory(detail.memory) },
+    evidence: (detail.evidence ?? []).map((item) => {
+      const budgeted = budget(item.verbatim ?? "");
+      return {
+        evidence_id: item.evidence_id,
+        available: item.available,
+        source_id: item.source_id,
+        written_by: item.written_by,
+        created_at: item.created_at,
+        excerpt: budgeted.text,
+        excerpt_truncated: budgeted.truncated,
+        excerpt_characters: budgeted.characters,
+      };
+    }),
+    history: (detail.history ?? []).map((item) => {
+      const content = budget(item.content);
+      return {
+        revision: item.revision,
+        action: item.action,
+        status: item.status,
+        scopes: item.scopes,
+        created_at: item.created_at,
+        content: content.text,
+        content_truncated: content.truncated,
+        content_characters: content.characters,
+      };
+    }),
   };
 }
 
-const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/;
-/** The same bound the app's 添加记忆 box applies. */
-export const MEMORY_ADD_MAX_CHARACTERS = 12_000;
-
-export interface MemoryAddDocument {
-  schema_version: 2;
-  product: string;
-  command: "memories add" | "memories add-status";
-  state: "accepted" | "rejected" | "unknown" | "not_found" | "invalid";
-  request_id: string;
-  code?: string;
-  receipt?: Record<string, unknown>;
-}
-
-export function isRequestId(value: string): boolean {
-  return UUID.test(value);
-}
-
-/** A memory text: non-blank, bounded, no control characters except tab and
- * newline. */
-export function validMemoryText(text: string): boolean {
-  return (
-    text.trim().length > 0 &&
-    [...text].length <= MEMORY_ADD_MAX_CHARACTERS &&
-    ![...text].some((character) => {
-      const code = character.charCodeAt(0);
-      return code <= 8 || (code >= 11 && code <= 31) || code === 127;
-    })
-  );
-}
-
-function addReceipt(receipt: MemoryAddReceipt): Record<string, unknown> {
-  return {
-    evidence_id: receipt.evidence_id,
-    state: receipt.state,
-    created_at: receipt.created_at,
-    task_id: receipt.task_id,
-    memory_ids: receipt.memory_ids,
-    error: receipt.error,
-  };
-}
-
-/**
- * Add one memory directly, the same request as the app's 添加记忆.
- *
- * `requestId` is Core's idempotency key: retrying with the same id and text
- * returns the first receipt; the same id with other text is refused.
- */
-export async function addMemory(
-  operations: CoreOperations,
-  text: string,
-  requestId: string = randomUUID(),
-): Promise<MemoryAddDocument> {
-  const base = {
-    schema_version: 2 as const,
-    product: PRODUCT,
-    command: "memories add" as const,
-    request_id: requestId,
-  };
-  if (!validMemoryText(text) || !UUID.test(requestId)) {
-    return { ...base, state: "invalid", code: "memory_add_invalid" };
-  }
-  let request: ReturnType<typeof buildMemoryAddRequest>;
-  try {
-    request = buildMemoryAddRequest({
-      request_id: requestId,
-      text,
-      scope: "all-apps",
-    });
-  } catch (error) {
-    if (error instanceof MemoryAddInputError) {
-      return { ...base, state: "invalid", code: "memory_add_invalid" };
-    }
-    throw error;
-  }
-  const result = await operations.post<unknown>(request.path, request.body);
-  if (result.state !== "committed") {
-    return { ...base, state: result.state, code: result.code };
-  }
-  const receipt = parseMemoryAddReceipt(result.data);
-  return receipt === null
-    ? { ...base, state: "unknown", code: "memory_add_receipt_invalid" }
-    : { ...base, state: "accepted", receipt: addReceipt(receipt) };
-}
-
-/** Read how one addition is doing, by the request id it was submitted with. */
-export async function readMemoryAddStatus(
-  reader: CoreReader,
-  requestId: string,
-): Promise<MemoryAddDocument> {
-  const base = {
-    schema_version: 2 as const,
-    product: PRODUCT,
-    command: "memories add-status" as const,
-    request_id: requestId,
-  };
-  if (!UUID.test(requestId)) {
-    return { ...base, state: "invalid", code: "invalid_request_id" };
-  }
-  const outcome = await reader<unknown>(memoryAddStatusPath(requestId));
-  if (outcome.state === "not_found") {
-    return { ...base, state: "not_found", code: "memory_add_not_found" };
-  }
-  if (outcome.state !== "ok") {
-    return {
-      ...base,
-      state: outcome.state === "rejected" ? "rejected" : "unknown",
-      code: outcome.code,
-    };
-  }
-  const receipt = parseMemoryAddReceipt(outcome.data);
-  return receipt === null
-    ? { ...base, state: "unknown", code: "memory_add_receipt_invalid" }
-    : { ...base, state: "accepted", receipt: addReceipt(receipt) };
-}
-
-export function memoryAddExitCode(document: MemoryAddDocument): number {
-  return document.state === "accepted" ? 0 : 1;
-}
-
-export function renderMemoryAddText(document: MemoryAddDocument): string {
-  if (document.state === "accepted" && document.receipt) {
-    return [
-      `request_id: ${document.request_id}`,
-      `evidence_id: ${document.receipt.evidence_id}`,
-      `state: ${document.receipt.state}`,
-      ...((document.receipt.memory_ids as string[]).length > 0
-        ? [`memory_ids: ${(document.receipt.memory_ids as string[]).join(",")}`]
-        : []),
-      document.command === "memories add"
-        ? `查询进度：memhub memories add-status ${document.request_id}；重试请带上同一个 --request-id，不会重复添加。`
-        : "",
-      "",
-    ]
-      .filter((line, index, all) => line !== "" || index === all.length - 1)
-      .join("\n");
-  }
-  if (document.state === "not_found") {
-    return `未找到该 request id：${document.request_id}\n`;
-  }
-  return [
-    `添加记忆未完成：${document.state}（${document.code}）`,
-    document.state === "unknown"
-      ? `结果未知；可以用同一个 --request-id ${document.request_id} 安全重试。`
-      : "",
-    "",
-  ]
-    .filter((line, index, all) => line !== "" || index === all.length - 1)
-    .join("\n");
-}
-
 export function renderMemoryPageText(document: MemoryPageDocument): string {
   const page = document.page;
   if (page.state !== "ok") {
     if (page.state === "unavailable") {
       return "后台正忙，记忆列表这次没查完，不代表没有记忆，请稍后再试\n";
     }
-    if (page.state === "rejected") {
-      return `记忆查询被拒绝（${page.code}），请检查参数。\n`;
-    }
     return `记忆查询未完成：${page.state}（${page.code}）\n`;
   }
   const lines = [
@@ -351,16 +154,11 @@ export function renderMemoryPageText(document: MemoryPageDocument): string {
       page.has_more ? "，还有更多，请用 --offset 继续" : ""
     }`,
   ];
-  if (typeof page.search_window === "number") {
-    lines.push(`（搜索只在最相关的 ${page.search_window} 条里匹配关键词）`);
-  }
   for (const memory of document.memories) {
-    const namespace =
-      memory.kind === "chat"
-        ? ""
-        : ` kind=${memory.kind} variant=${memory.variant}`;
     lines.push(
-      `- ${memory.memory_id}  [${memory.scene}] ${memory.status}/${memory.layer}  source=${memory.source ?? "未知"}${namespace}`,
+      `- ${memory.memory_id}  ${memory.status}/${memory.kind}  rev ${memory.revision}  scopes=${
+        (memory.scopes as string[]).join(",") || "无"
+      }`,
       `  ${memory.content}${memory.content_truncated ? ` …（共 ${memory.content_characters} 字）` : ""}`,
     );
   }
@@ -375,110 +173,58 @@ export function renderMemoryDetailText(document: MemoryDetailDocument): string {
     if (memory.state === "unavailable") {
       return "后台正忙，记忆详情这次没查完，不代表没有这条记忆，请稍后再试\n";
     }
-    if (memory.code === "memory_id_ambiguous") {
-      return "这个 ID 同时存在于多个场景；请加 --kind（以及 --variant）指明是哪一条。\n";
-    }
     return `记忆读取未完成：${memory.state}（${memory.code}）\n`;
   }
   const lines = [
     `记忆 ${memory.memory_id}`,
-    `场景：${memory.scene}  类型：${memory.kind}${memory.variant ? `（${memory.variant}）` : ""}`,
-    `状态：${memory.status}  层：${memory.layer}  来源：${memory.source ?? "未知"}`,
-    `owner：${memory.owner ?? "未知"}  latest：${memory.is_latest}`,
-    `raw IDs：${(memory.source_raw_ids as string[]).join(",") || "无"}`,
+    `状态：${memory.status}  类型：${memory.kind}  来源方式：${memory.origin}  版本：${memory.revision}`,
+    `授权范围：${(memory.scopes as string[]).join(",") || "无"}`,
+    `证据：${(memory.evidence_ids as string[]).join(",") || "无"}`,
+    `更新时间：${memory.updated_at}`,
     "",
     String(memory.content),
     memory.content_truncated ? `…（共 ${memory.content_characters} 字）` : "",
     "",
-    "SDK memory 数据不在 MemHub 中保留 Evidence/版本副本。",
+    "原文摘录：",
   ];
+  for (const item of document.evidence) {
+    lines.push(
+      `- ${item.evidence_id}  来源=${item.source_id ?? "未知"}  作者=${item.written_by ?? "未知"}  可读=${item.available}`,
+      `  ${item.excerpt}${item.excerpt_truncated ? ` …（共 ${item.excerpt_characters} 字）` : ""}`,
+    );
+  }
+  if (document.evidence.length === 0) lines.push("（无可读原文）");
+  lines.push("", "版本历史：");
+  for (const item of document.history) {
+    lines.push(
+      `- rev ${item.revision}  ${item.action}  ${item.status}  scopes=${(item.scopes as string[]).join(",")}`,
+      `  ${item.content}${item.content_truncated ? ` …（共 ${item.content_characters} 字）` : ""}`,
+    );
+  }
+  if (document.history.length === 0) lines.push("（无）");
   lines.push("");
   return lines.join("\n");
 }
 
-function describeMemory(memory: SdkMemoryRecord): Record<string, unknown> {
+function describeMemory(memory: GovernedMemory): Record<string, unknown> {
   const budgeted = budget(memory.content ?? "");
   return {
     memory_id: memory.memory_id,
-    // Pre-2.0.6 Core listed chat memories only and named no scene.
-    scene: memory.scene ?? "chat",
-    kind: memory.kind ?? "chat",
-    variant: memory.variant ?? null,
     status: memory.status,
-    layer: memory.layer,
-    is_latest: memory.is_latest,
-    owner: memory.owner,
-    source: memory.source,
-    source_raw_ids: memory.source_raw_ids,
-    supersedes: memory.supersedes,
-    superseded_by: memory.superseded_by,
+    kind: memory.kind,
+    origin: memory.origin,
+    revision: memory.revision,
+    scopes: memory.scopes ?? [],
+    evidence_ids: memory.evidence_ids ?? [],
     tags: memory.tags ?? [],
-    memory_at: memory.memory_at,
-    gmt_created: memory.gmt_created,
-    ...(memory.task === undefined || memory.task === null
-      ? {}
-      : { task: memory.task }),
+    created_at: memory.created_at,
+    updated_at: memory.updated_at,
     content: budgeted.text,
     content_truncated: budgeted.truncated,
     content_characters: budgeted.characters,
   };
 }
 
-function sdkMemoryPage(value: unknown): SdkMemoryPage | null {
-  if (!record(value) || !Array.isArray(value.memories)) return null;
-  const memories = value.memories.map(sdkMemory);
-  if (memories.some((item) => item === null)) return null;
-  if (!integer(value.total) || !integer(value.limit) || !integer(value.offset))
-    return null;
-  return {
-    memories: memories as SdkMemoryRecord[],
-    total: value.total,
-    limit: value.limit,
-    offset: value.offset,
-    ...(integer(value.search_window)
-      ? { search_window: value.search_window }
-      : {}),
-  };
-}
-
-function sdkMemory(value: unknown): SdkMemoryRecord | null {
-  if (
-    !record(value) ||
-    !text(value.memory_id) ||
-    typeof value.content !== "string" ||
-    !text(value.layer) ||
-    !text(value.status) ||
-    typeof value.is_latest !== "boolean" ||
-    !strings(value.supersedes) ||
-    !strings(value.superseded_by) ||
-    !strings(value.tags) ||
-    !strings(value.source_raw_ids) ||
-    // Working/coding memories may carry an empty user or agent id.
-    typeof value.user_id !== "string" ||
-    typeof value.agent_id !== "string"
-  )
-    return null;
-  return value as unknown as SdkMemoryRecord;
-}
-
-function record(value: unknown): value is Record<string, unknown> {
-  return value !== null && typeof value === "object" && !Array.isArray(value);
-}
-
-function text(value: unknown): value is string {
-  return typeof value === "string" && value.length > 0;
-}
-
-function strings(value: unknown): value is string[] {
-  return (
-    Array.isArray(value) && value.every((item) => typeof item === "string")
-  );
-}
-
-function integer(value: unknown): value is number {
-  return Number.isInteger(value) && Number(value) >= 0;
-}
-
 function budget(value: string): {
   text: string;
   truncated: boolean;

memhub/apps/cli/src/model-probe-flow.test.ts

@@ -3,9 +3,9 @@ import { describe, expect, it, vi } from "vitest";
 import type { CoreReader } from "./core-client.js";
 import type { CoreOperations } from "./core-operations.js";
 import {
-  modelProbeExitCode,
+  executeModelProbe,
+  planModelProbe,
   readModelProbeReceipt,
-  startModelProbe,
 } from "./model-probe-flow.js";
 
 const PROFILE_ID = "22222222-2222-4222-8222-222222222222";
@@ -83,101 +83,67 @@ function completed(operationId: string) {
   };
 }
 
-const OPERATION_ID = "33333333-3333-4333-8333-333333333333";
-
-/** Reader that answers the profile list, then the queued operation reads. */
-function readerWith(...operationReads: unknown[]) {
-  const reader = vi.fn(async (path: string) => {
-    if (path === "/api/v1/model-profiles") {
-      return { state: "ok", data: [PROFILE] };
-    }
-    return operationReads.shift() ?? { state: "not_found", code: "http_404" };
-  });
-  return reader;
-}
-
 describe("model probe operation flow", () => {
-  it("probes the exact current profile revision once support is proven", async () => {
-    const reader = readerWith({ state: "ok", data: notFound(OPERATION_ID) });
+  it("plans against the exact current profile revision", async () => {
+    const reader = vi.fn().mockResolvedValue({ state: "ok", data: [PROFILE] });
+    const document = await planModelProbe(reader as CoreReader, PROFILE_ID);
+    expect(document.state).toBe("preview");
+    if (document.state !== "preview") throw new Error("expected preview");
+    expect(document.plan).toMatchObject({
+      kind: "model_profile_probe",
+      profile_id: PROFILE_ID,
+      expected_profile_revision: 3,
+    });
+    expect(document.plan.operation_id).toMatch(
+      /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/,
+    );
+    expect(document.plan.digest).toMatch(/^[0-9a-f]{64}$/);
+  });
+
+  it("proves operation support with schema-1 not_found before posting", async () => {
+    const planned = await planModelProbe(
+      vi.fn().mockResolvedValue({ state: "ok", data: [PROFILE] }) as CoreReader,
+      PROFILE_ID,
+    );
+    if (planned.state !== "preview") throw new Error("expected preview");
+    const operationId = planned.plan.operation_id;
+    const reader = vi
+      .fn()
+      .mockResolvedValueOnce({ state: "ok", data: notFound(operationId) });
     const post = vi
       .fn()
-      .mockResolvedValue({ state: "committed", data: completed(OPERATION_ID) });
+      .mockResolvedValue({ state: "committed", data: completed(operationId) });
 
-    const result = await startModelProbe(
-      reader as unknown as CoreReader,
+    const result = await executeModelProbe(
+      planned.plan,
+      reader as CoreReader,
       { post } as CoreOperations,
-      PROFILE_ID,
-      OPERATION_ID,
     );
 
     expect(result.state).toBe("completed");
     expect(reader).toHaveBeenCalledWith(
-      `/api/v1/model-probe-operations/${OPERATION_ID}`,
+      `/api/v1/model-probe-operations/${operationId}`,
     );
     expect(post).toHaveBeenCalledWith(
       `/api/v1/model-profiles/${PROFILE_ID}/probe`,
-      { operation_id: OPERATION_ID, expected_profile_revision: 3 },
+      { operation_id: operationId, expected_profile_revision: 3 },
     );
   });
 
-  it("generates its own operation id and treats a pending probe as submitted", async () => {
-    const post = vi.fn(
-      async (_path: string, body: Record<string, unknown>) => ({
-        state: "committed",
-        data: {
-          ...notFound(String(body.operation_id)),
-          profile_id: PROFILE_ID,
-          expected_profile_revision: 3,
-          state: "pending",
-          stale: false,
-        },
-      }),
-    );
-    const reader = vi.fn(async (path: string) =>
-      path === "/api/v1/model-profiles"
-        ? { state: "ok", data: [PROFILE] }
-        : {
-            state: "ok",
-            data: notFound(path.split("/").at(-1) ?? ""),
-          },
-    );
-    const result = await startModelProbe(
-      reader as unknown as CoreReader,
-      { post } as unknown as CoreOperations,
-      PROFILE_ID,
-    );
-    expect(result.state).toBe("pending");
-    expect(result.operation_id).toMatch(
-      /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/,
-    );
-    expect(modelProbeExitCode(result)).toBe(0);
-  });
-
-  it("refuses an unknown profile without posting", async () => {
-    const post = vi.fn();
-    const result = await startModelProbe(
-      readerWith() as unknown as CoreReader,
-      { post } as CoreOperations,
-      "44444444-4444-4444-8444-444444444444",
-      OPERATION_ID,
-    );
-    expect(result).toMatchObject({
-      state: "not_found",
-      code: "model_profile_not_found",
-    });
-    expect(post).not.toHaveBeenCalled();
-  });
-
   it("does not post when the Core lacks the exact operation contract", async () => {
+    const planned = await planModelProbe(
+      vi.fn().mockResolvedValue({ state: "ok", data: [PROFILE] }) as CoreReader,
+      PROFILE_ID,
+    );
+    if (planned.state !== "preview") throw new Error("expected preview");
     const post = vi.fn();
-    const result = await startModelProbe(
-      readerWith({
+    const result = await executeModelProbe(
+      planned.plan,
+      vi.fn().mockResolvedValue({
         state: "not_found",
         code: "http_404",
-      }) as unknown as CoreReader,
+      }) as CoreReader,
       { post } as CoreOperations,
-      PROFILE_ID,
-      OPERATION_ID,
     );
     expect(result).toMatchObject({
       state: "disabled",
@@ -187,15 +153,19 @@ describe("model probe operation flow", () => {
   });
 
   it("does not post when a legacy Core returns a non-operation body", async () => {
+    const planned = await planModelProbe(
+      vi.fn().mockResolvedValue({ state: "ok", data: [PROFILE] }) as CoreReader,
+      PROFILE_ID,
+    );
+    if (planned.state !== "preview") throw new Error("expected preview");
     const post = vi.fn();
-    const result = await startModelProbe(
-      readerWith({
+    const result = await executeModelProbe(
+      planned.plan,
+      vi.fn().mockResolvedValue({
         state: "ok",
         data: { detail: "legacy_route_shape" },
-      }) as unknown as CoreReader,
+      }) as CoreReader,
       { post } as CoreOperations,
-      PROFILE_ID,
-      OPERATION_ID,
     );
     expect(result).toMatchObject({
       state: "disabled",
@@ -205,19 +175,24 @@ describe("model probe operation flow", () => {
   });
 
   it("reconciles an unknown POST by GET and never treats not_found as replay permission", async () => {
-    const reader = readerWith(
-      { state: "ok", data: notFound(OPERATION_ID) },
-      { state: "ok", data: notFound(OPERATION_ID) },
+    const planned = await planModelProbe(
+      vi.fn().mockResolvedValue({ state: "ok", data: [PROFILE] }) as CoreReader,
+      PROFILE_ID,
     );
+    if (planned.state !== "preview") throw new Error("expected preview");
+    const operationId = planned.plan.operation_id;
+    const reader = vi
+      .fn()
+      .mockResolvedValueOnce({ state: "ok", data: notFound(operationId) })
+      .mockResolvedValueOnce({ state: "ok", data: notFound(operationId) });
     const post = vi.fn().mockResolvedValue({
       state: "unknown",
       code: "transport_result_unknown",
     });
-    const result = await startModelProbe(
-      reader as unknown as CoreReader,
+    const result = await executeModelProbe(
+      planned.plan,
+      reader as CoreReader,
       { post } as CoreOperations,
-      PROFILE_ID,
-      OPERATION_ID,
     );
     expect(result).toMatchObject({
       state: "unknown",

memhub/apps/cli/src/model-probe-flow.ts

@@ -1,10 +1,11 @@
-import { randomUUID } from "node:crypto";
+import { createHash, randomUUID } from "node:crypto";
 import type { CoreReader, ReadOutcome } from "./core-client.js";
 import type { CoreOperations } from "./core-operations.js";
 import { validateModelProfiles } from "./core-responses.js";
 import { PRODUCT } from "./version.js";
 
 const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/;
+const DIGEST = /^[0-9a-f]{64}$/;
 const RECEIPT_KEYS = new Set([
   "schema_version",
   "operation_id",
@@ -58,7 +59,23 @@ const CODES = new Set([
   "embedding_unavailable",
 ]);
 
+interface ModelProbePlanBody {
+  schema_version: 1;
+  kind: "model_profile_probe";
+  operation_id: string;
+  profile_id: string;
+  expected_profile_revision: number;
+}
+
+export type ModelProbePlan = ModelProbePlanBody & { digest: string };
+
 export type ModelProbeFlowDocument =
+  | {
+      schema_version: 1;
+      product: string;
+      state: "preview";
+      plan: ModelProbePlan;
+    }
   | {
       schema_version: 1;
       product: string;
@@ -74,25 +91,11 @@ export type ModelProbeFlowDocument =
       code: string;
     };
 
-/**
- * Start one capability probe of a model profile (one real model request).
- *
- * Reads the profile's current revision so Core can refuse a probe of a
- * profile that changed meanwhile, checks that this Core tracks probe
- * operations (an old Core would start an untracked request), then submits it.
- * The probe runs asynchronously: the answer is usually `pending`, and
- * `models receipt <operation-id>` reads the result.
- */
-export async function startModelProbe(
+export async function planModelProbe(
   reader: CoreReader,
-  operations: CoreOperations,
   profileId: string,
-  operationId: string = randomUUID(),
 ): Promise<ModelProbeFlowDocument> {
   if (!UUID.test(profileId)) return failure("invalid", "invalid_profile_id");
-  if (!UUID.test(operationId)) {
-    return failure("invalid", "invalid_probe_operation_id");
-  }
   const outcome = await reader<unknown>("/api/v1/model-profiles");
   if (outcome.state !== "ok") return fromReadFailure(outcome);
   const profiles = validateModelProfiles(outcome.data);
@@ -102,46 +105,71 @@ export async function startModelProbe(
   );
   if (matches.length !== 1)
     return failure("not_found", "model_profile_not_found");
-  const revision = matches[0].revision;
-  if (!Number.isSafeInteger(revision) || revision < 1) {
+  const profile = matches[0];
+  if (!Number.isSafeInteger(profile.revision) || profile.revision < 1) {
     return failure("invalid", "model_profile_revision_invalid");
   }
+  const plan = withDigest({
+    schema_version: 1 as const,
+    kind: "model_profile_probe" as const,
+    operation_id: randomUUID(),
+    profile_id: profileId,
+    expected_profile_revision: profile.revision,
+  });
+  return { schema_version: 1, product: PRODUCT, state: "preview", plan };
+}
+
+export async function executeModelProbe(
+  value: unknown,
+  reader: CoreReader,
+  operations: CoreOperations,
+): Promise<ModelProbeFlowDocument> {
+  const plan = validatePlan(value);
+  if (!plan) return failure("invalid", "model_probe_plan_invalid");
 
   // A 404 or a legacy/malformed body is not support. Some old Core versions
   // ignore the operation body and start an untracked external model request.
-  const support = await reader<unknown>(operationPath(operationId));
+  const support = await reader<unknown>(operationPath(plan.operation_id));
   if (support.state !== "ok") {
     return failure(
       "disabled",
       "model_probe_operations_unsupported",
-      operationId,
+      plan.operation_id,
     );
   }
-  const supportReceipt = validateReceipt(support.data, operationId);
+  const supportReceipt = validateReceipt(support.data, plan.operation_id);
   if (supportReceipt?.state !== "not_found") {
     return failure(
       "disabled",
       "model_probe_operations_unsupported",
-      operationId,
+      plan.operation_id,
     );
   }
 
-  const posted = await operations.post<unknown>(
-    `/api/v1/model-profiles/${profileId}/probe`,
-    { operation_id: operationId, expected_profile_revision: revision },
+  const outcome = await operations.post<unknown>(
+    `/api/v1/model-profiles/${plan.profile_id}/probe`,
+    {
+      operation_id: plan.operation_id,
+      expected_profile_revision: plan.expected_profile_revision,
+    },
   );
-  if (posted.state === "rejected") {
-    return failure("rejected", posted.code, operationId);
+  if (outcome.state === "rejected") {
+    return failure("rejected", outcome.code, plan.operation_id);
   }
-  if (posted.state === "committed") {
-    return receiptDocument(posted.data, operationId, profileId, revision);
+  if (outcome.state === "committed") {
+    return receiptDocument(
+      outcome.data,
+      plan.operation_id,
+      plan.profile_id,
+      plan.expected_profile_revision,
+    );
   }
-  const reconciled = await readModelProbeReceipt(reader, operationId);
+  const reconciled = await readModelProbeReceipt(reader, plan.operation_id);
   return reconciled.state === "not_found"
     ? failure(
         "unknown",
         "model_probe_receipt_not_found_after_attempt",
-        operationId,
+        plan.operation_id,
       )
     : reconciled;
 }
@@ -162,24 +190,32 @@ export async function readModelProbeReceipt(
   return receiptDocument(outcome.data, operationId);
 }
 
+export function inspectModelProbePlan(value: unknown): ModelProbePlan | null {
+  return validatePlan(value);
+}
+
 export function modelProbeExitCode(document: ModelProbeFlowDocument): number {
-  // `pending` is a submitted probe still running: the submit succeeded.
-  return ["completed", "pending"].includes(document.state) ? 0 : 1;
+  return ["preview", "completed"].includes(document.state) ? 0 : 1;
 }
 
 export function renderModelProbeText(document: ModelProbeFlowDocument): string {
-  const lines = [
+  if (document.state === "preview") {
+    return [
+      "预览：模型能力探测",
+      `模型配置：${document.plan.profile_id}`,
+      `预期版本：${document.plan.expected_profile_revision}`,
+      `操作 ID：${document.plan.operation_id}`,
+      `确认摘要：${document.plan.digest}`,
+      "未发起模型请求。请保存 --json 输出，再用 models probe --plan-file <path> --confirm。",
+      "",
+    ].join("\n");
+  }
+  return [
     `探测状态：${document.state}`,
     `操作 ID：${document.operation_id ?? "无"}`,
     "code" in document ? `代码：${document.code}` : "已返回有界操作回执。",
-  ];
-  if (document.state === "pending" && document.operation_id) {
-    lines.push(
-      `探测在后台进行；用 memhub models receipt ${document.operation_id} 查看结果。`,
-    );
-  }
-  lines.push("");
-  return lines.join("\n");
+    "",
+  ].join("\n");
 }
 
 function receiptDocument(
@@ -213,6 +249,31 @@ function receiptDocument(
   };
 }
 
+function validatePlan(value: unknown): ModelProbePlan | null {
+  const plan = record(value);
+  if (
+    plan?.schema_version !== 1 ||
+    plan.kind !== "model_profile_probe" ||
+    typeof plan.operation_id !== "string" ||
+    !UUID.test(plan.operation_id) ||
+    typeof plan.profile_id !== "string" ||
+    !UUID.test(plan.profile_id) ||
+    !positiveInteger(plan.expected_profile_revision) ||
+    typeof plan.digest !== "string" ||
+    !DIGEST.test(plan.digest)
+  ) {
+    return null;
+  }
+  const expected = withDigest({
+    schema_version: 1 as const,
+    kind: "model_profile_probe" as const,
+    operation_id: plan.operation_id,
+    profile_id: plan.profile_id,
+    expected_profile_revision: plan.expected_profile_revision,
+  });
+  return expected.digest === plan.digest ? expected : null;
+}
+
 function validateReceipt(
   value: unknown,
   operationId: string,
@@ -348,6 +409,27 @@ function failure(
   };
 }
 
+function withDigest<T extends object>(body: T): T & { digest: string } {
+  return {
+    ...body,
+    digest: createHash("sha256").update(canonical(body)).digest("hex"),
+  };
+}
+
+function canonical(value: unknown): string {
+  if (Array.isArray(value)) return `[${value.map(canonical).join(",")}]`;
+  if (value && typeof value === "object") {
+    return `{${Object.keys(value)
+      .sort()
+      .map(
+        (key) =>
+          `${JSON.stringify(key)}:${canonical((value as Record<string, unknown>)[key])}`,
+      )
+      .join(",")}}`;
+  }
+  return JSON.stringify(value);
+}
+
 function record(value: unknown): Record<string, unknown> | null {
   return value !== null && typeof value === "object" && !Array.isArray(value)
     ? (value as Record<string, unknown>)

memhub/apps/cli/src/model-report.ts

@@ -41,7 +41,7 @@ export type ModelReportDocument =
   | {
       schema_version: 1;
       product: string;
-      state: "denied" | "unavailable" | "not_found" | "invalid" | "rejected";
+      state: "denied" | "unavailable" | "not_found" | "invalid";
       code: string;
     };
 
@@ -136,7 +136,7 @@ function project(profile: ModelProfile): SafeModelProfile {
 }
 
 function failure(
-  state: "denied" | "unavailable" | "not_found" | "invalid" | "rejected",
+  state: "denied" | "unavailable" | "not_found" | "invalid",
   code: string,
 ): ModelReportDocument {
   return { schema_version: 1, product: PRODUCT, state, code };

memhub/apps/cli/src/model-write-cli.test.ts

@@ -126,12 +126,29 @@ describe("models activate", () => {
     expect(runtime.inspectRuntimeStatus).not.toHaveBeenCalled();
   });
 
-  it("posts the activate endpoint directly and reports the profile", async () => {
+  it("previews without contacting Core", async () => {
+    const result = await capturedRun(["models", "activate", PROFILE, "--json"]);
+    expect(result.code).toBe(0);
+    const document = JSON.parse(result.stdout);
+    expect(document.state).toBe("preview");
+    expect(document.plan.kind).toBe("model_profile_activate");
+    // Activation has no CAS body, so the plan must not pretend to carry one.
+    expect(document.plan).not.toHaveProperty("expected_revision");
+    expect(transport.post).not.toHaveBeenCalled();
+  });
+
+  it("posts the activate endpoint with --confirm and reports the profile", async () => {
     transport.post.mockResolvedValue({
       status: 200,
       data: profileResponse(),
     });
-    const result = await capturedRun(["models", "activate", PROFILE, "--json"]);
+    const result = await capturedRun([
+      "models",
+      "activate",
+      PROFILE,
+      "--confirm",
+      "--json",
+    ]);
     expect(result.code).toBe(0);
     expect(transport.post).toHaveBeenCalledWith(
       `/api/v1/model-profiles/${PROFILE}/activate`,
@@ -179,22 +196,31 @@ describe("models activate", () => {
   });
 });
 
-describe("models remove", () => {
-  it("previews without --yes and changes nothing", async () => {
-    const result = await capturedRun(["models", "remove", PROFILE, "--json"]);
-    expect(result.code).toBe(0);
-    expect(JSON.parse(result.stdout)).toMatchObject({
-      command: "models remove",
-      state: "preview",
-      target: PROFILE,
-      applied: false,
-    });
-    expect(runtime.inspectRuntimeStatus).not.toHaveBeenCalled();
-  });
-});
-
 describe("models edit", () => {
-  it("sends the exact patch body with the CAS revision directly", async () => {
+  it("previews a patch from a config file without writing", async () => {
+    const directory = await mkdtemp(path.join(tmpdir(), "om-model-edit-"));
+    const config = path.join(directory, "patch.json");
+    await writeFile(
+      config,
+      JSON.stringify({ expected_revision: 4, name: "Renamed" }),
+      { mode: 0o600 },
+    );
+    const result = await capturedRun([
+      "models",
+      "edit",
+      PROFILE,
+      "--config-file",
+      config,
+      "--json",
+    ]);
+    expect(result.code).toBe(0);
+    const document = JSON.parse(result.stdout);
+    expect(document.state).toBe("preview");
+    expect(document.plan.patch).toEqual({ name: "Renamed" });
+    expect(transport.patch).not.toHaveBeenCalled();
+  });
+
+  it("sends the exact patch body with the CAS revision on confirm", async () => {
     const directory = await mkdtemp(path.join(tmpdir(), "om-model-edit-"));
     const config = path.join(directory, "patch.json");
     await writeFile(
@@ -216,6 +242,7 @@ describe("models edit", () => {
       PROFILE,
       "--config-file",
       config,
+      "--confirm",
       "--json",
     ]);
     expect(result.code).toBe(0);

memhub/apps/cli/src/model-write-flows.ts

@@ -3,12 +3,14 @@
  * activate (`POST /model-profiles/{id}/activate`) and edit
  * (`PATCH /model-profiles/{id}`).
  *
- * Core owns the semantics. Both run directly: activation is reversible (activate
- * another profile) and an edit is guarded by `expected_revision`, the
- * compare-and-swap Core requires, mirroring the Web console's
- * `ModelProfilePatch`.
+ * Core owns the semantics. These flows reuse the same two-phase convention as
+ * `models configure`: plan without `--confirm` (or produce a plan file), then
+ * apply exactly that plan. The edit body mirrors the Web console's
+ * `ModelProfilePatch`, including `expected_revision` as the compare-and-swap
+ * guard Core requires.
  */
 
+import { createHash, randomUUID } from "node:crypto";
 import type { ModelProfile } from "@one-memory/contracts";
 import {
   buildModelProfileUpdateRequest,
@@ -20,7 +22,29 @@ import { PRODUCT } from "./version.js";
 
 const PROFILE_ID = /^[A-Za-z0-9][\w.-]{0,127}$/;
 
+export type ModelWritePlan =
+  | {
+      schema_version: 1;
+      kind: "model_profile_activate";
+      profile_id: string;
+      digest: string;
+    }
+  | {
+      schema_version: 1;
+      kind: "model_profile_edit";
+      profile_id: string;
+      expected_revision: number;
+      patch: Record<string, unknown>;
+      digest: string;
+    };
+
 export type ModelWriteDocument =
+  | {
+      schema_version: 1;
+      product: string;
+      state: "preview";
+      plan: ModelWritePlan;
+    }
   | {
       schema_version: 1;
       product: string;
@@ -36,6 +60,38 @@ export type ModelWriteDocument =
       code: string;
     };
 
+function canonical(value: unknown): string {
+  if (Array.isArray(value)) return `[${value.map(canonical).join(",")}]`;
+  if (value !== null && typeof value === "object") {
+    return `{${Object.entries(value as Record<string, unknown>)
+      .sort(([left], [right]) => left.localeCompare(right))
+      .map(([key, item]) => `${JSON.stringify(key)}:${canonical(item)}`)
+      .join(",")}}`;
+  }
+  if (value === undefined) return "null";
+  return JSON.stringify(value);
+}
+
+function digestOf(value: unknown): string {
+  return createHash("sha256").update(canonical(value)).digest("hex");
+}
+
+function preview(
+  plan:
+    | Omit<
+        Extract<ModelWritePlan, { kind: "model_profile_activate" }>,
+        "digest"
+      >
+    | Omit<Extract<ModelWritePlan, { kind: "model_profile_edit" }>, "digest">,
+): ModelWriteDocument {
+  return {
+    schema_version: 1,
+    product: PRODUCT,
+    state: "preview",
+    plan: { ...plan, digest: digestOf(plan) } as ModelWritePlan,
+  };
+}
+
 function invalid(code: string): ModelWriteDocument {
   return { schema_version: 1, product: PRODUCT, state: "invalid", code };
 }
@@ -66,45 +122,87 @@ function projectProfile(profile: ModelProfile): Record<string, unknown> {
   };
 }
 
-/** Make `profileId` the active profile. Activation has no request body, so
- * there is no revision for Core to check. */
-export async function activateModelProfile(
-  profileId: string,
-  operations: CoreOperations,
-): Promise<ModelWriteDocument> {
-  if (!PROFILE_ID.test(profileId)) {
-    return invalid("model_profile_activate_input_invalid");
-  }
-  const result = await operations.post<unknown>(
-    `/api/v1/model-profiles/${encodeURIComponent(profileId)}/activate`,
-    {},
-  );
-  return modelProfileResult(profileId, result);
+// --- activate -------------------------------------------------------------
+
+/**
+ * Activation has no request body, so the plan carries only the target. There
+ * is deliberately no `expected_revision`: Core would never read one, and
+ * recording a check it does not perform would be a fake guard.
+ */
+export function planModelProfileActivate(input: {
+  profileId: string;
+}): ModelWriteDocument {
+  return PROFILE_ID.test(input.profileId)
+    ? preview({
+        schema_version: 1,
+        kind: "model_profile_activate",
+        profile_id: input.profileId,
+      })
+    : invalid("model_profile_activate_input_invalid");
 }
 
-/** Apply a bounded patch (carrying `expected_revision`) to one profile; the
- * key, when given, comes from a controlled file and never from the patch. */
-export async function editModelProfile(
-  profileId: string,
-  patch: unknown,
-  apiKey: string | undefined,
-  operations: CorePatchOperations,
+export async function executeModelProfileActivate(
+  plan: Extract<ModelWritePlan, { kind: "model_profile_activate" }>,
+  operations: CoreOperations,
 ): Promise<ModelWriteDocument> {
-  if (
-    !PROFILE_ID.test(profileId) ||
-    patch === null ||
-    typeof patch !== "object" ||
-    Array.isArray(patch) ||
-    "api_key" in patch
-  ) {
-    return invalid("model_profile_edit_input_invalid");
-  }
-  // The shared builder owns patch validation (allow-list, expected_revision
-  // CAS, field bounds, api_key/clear_api_key exclusivity).
+  const result = await operations.post<unknown>(
+    `/api/v1/model-profiles/${encodeURIComponent(plan.profile_id)}/activate`,
+    {},
+  );
+  return modelProfileResult(plan.profile_id, result);
+}
+
+// --- edit -----------------------------------------------------------------
+
+export function planModelProfileEdit(input: {
+  profileId: string;
+  patch: unknown;
+}): ModelWriteDocument {
+  // The shared builder owns patch validation (14-key allow-list,
+  // expected_revision CAS, field bounds, api_key/clear_api_key exclusivity).
+  // A rejected patch is `invalid`, never a plan the caller could confirm.
   let request: ReturnType<typeof buildModelProfileUpdateRequest>;
   try {
-    request = buildModelProfileUpdateRequest(profileId, {
-      ...(patch as Record<string, unknown>),
+    request = buildModelProfileUpdateRequest(input.profileId, input.patch);
+  } catch (error) {
+    if (error instanceof ModelProfileInputError) {
+      return invalid("model_profile_edit_input_invalid");
+    }
+    throw error;
+  }
+  const patch = request.body as Record<string, unknown>;
+  if (!PROFILE_ID.test(input.profileId)) {
+    return invalid("model_profile_edit_input_invalid");
+  }
+  return preview({
+    schema_version: 1,
+    kind: "model_profile_edit",
+    profile_id: input.profileId,
+    expected_revision: patch.expected_revision as number,
+    // `api_key` is read from a controlled file at apply time, exactly like
+    // `models configure`; the plan never carries the credential. The revision
+    // is a top-level field, so it is stripped from the nested patch rather
+    // than being duplicated in both places.
+    patch: Object.fromEntries(
+      Object.entries(patch).filter(
+        ([key]) => key !== "api_key" && key !== "expected_revision",
+      ),
+    ),
+  });
+}
+
+export async function executeModelProfileEdit(
+  plan: Extract<ModelWritePlan, { kind: "model_profile_edit" }>,
+  operations: CorePatchOperations,
+  apiKey: string | undefined,
+): Promise<ModelWriteDocument> {
+  // Re-validate through the shared builder at apply time too, so a hand-edited
+  // plan cannot smuggle an out-of-bounds patch past the write.
+  let request: ReturnType<typeof buildModelProfileUpdateRequest>;
+  try {
+    request = buildModelProfileUpdateRequest(plan.profile_id, {
+      ...plan.patch,
+      expected_revision: plan.expected_revision,
       ...(apiKey === undefined ? {} : { api_key: apiKey }),
     });
   } catch (error) {
@@ -114,7 +212,7 @@ export async function editModelProfile(
     throw error;
   }
   const result = await operations.patch<unknown>(request.path, request.body);
-  return modelProfileResult(profileId, result);
+  return modelProfileResult(plan.profile_id, result);
 }
 
 function modelProfileResult(
@@ -156,11 +254,69 @@ function modelProfileResult(
   return committed(operationId, profile);
 }
 
+export function validateModelWritePlan(value: unknown): ModelWritePlan | null {
+  if (value === null || typeof value !== "object" || Array.isArray(value)) {
+    return null;
+  }
+  const candidate = value as Record<string, unknown>;
+  if (candidate.schema_version !== 1 || typeof candidate.kind !== "string") {
+    return null;
+  }
+  const { digest, ...withoutDigest } = candidate;
+  if (typeof digest !== "string" || digest !== digestOf(withoutDigest)) {
+    return null;
+  }
+  switch (candidate.kind) {
+    case "model_profile_activate":
+      return typeof candidate.profile_id === "string" &&
+        PROFILE_ID.test(candidate.profile_id) &&
+        Object.keys(candidate).length === 3
+        ? (candidate as unknown as ModelWritePlan)
+        : null;
+    case "model_profile_edit": {
+      if (
+        typeof candidate.profile_id !== "string" ||
+        !PROFILE_ID.test(candidate.profile_id) ||
+        !Number.isSafeInteger(candidate.expected_revision)
+      ) {
+        return null;
+      }
+      // The shared builder is the single judge of a patch body; the plan must
+      // not carry `api_key` (that is read from a controlled file at apply).
+      let built: ReturnType<typeof buildModelProfileUpdateRequest>;
+      try {
+        built = buildModelProfileUpdateRequest(candidate.profile_id, {
+          ...(candidate.patch as Record<string, unknown>),
+          expected_revision: candidate.expected_revision,
+        });
+      } catch {
+        return null;
+      }
+      if ("api_key" in built.body) return null;
+      return Object.keys(candidate).length === 6
+        ? (candidate as unknown as ModelWritePlan)
+        : null;
+    }
+    default:
+      return null;
+  }
+}
+
 export function modelWriteExitCode(document: ModelWriteDocument): number {
-  return document.state === "committed" ? 0 : 1;
+  return ["preview", "committed"].includes(document.state) ? 0 : 1;
 }
 
 export function renderModelWriteText(document: ModelWriteDocument): string {
+  if (document.state === "preview") {
+    const plan = document.plan;
+    return [
+      `预览：${plan.kind}`,
+      `目标配置：${plan.profile_id}`,
+      `确认摘要：${plan.digest}`,
+      "未执行任何写操作。请把 --json 输出保存为 plan 文件，再用对应命令加 --confirm。",
+      "",
+    ].join("\n");
+  }
   if (document.state === "committed") {
     return `已保存模型配置：${document.receipt.profile_id}\nrevision=${document.receipt.revision}\n`;
   }

memhub/apps/cli/src/operation-journal.ts

@@ -0,0 +1,57 @@
+import { constants } from "node:fs";
+import { type FileHandle, open } from "node:fs/promises";
+import { readBoundedJson } from "./bounded-file.js";
+
+export type PlanAttempt = {
+  schema_version: 1;
+  operation_id: string;
+  plan_digest: string;
+};
+
+/**
+ * Durable client fence written before a mutating request. Once present, the
+ * same plan may only query its operation receipt; it is never blindly posted
+ * again after an unknown result.
+ */
+export async function claimPlanAttempt(
+  planFile: string,
+  attempt: PlanAttempt,
+): Promise<"first" | "prior" | "invalid"> {
+  const journal = `${planFile}.one-memory-attempt`;
+  let handle: FileHandle;
+  try {
+    handle = await open(
+      journal,
+      constants.O_WRONLY |
+        constants.O_CREAT |
+        constants.O_EXCL |
+        (constants.O_NOFOLLOW ?? 0),
+      0o600,
+    );
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code !== "EEXIST") return "invalid";
+    const current = await readBoundedJson(journal, 1024);
+    return sameAttempt(current, attempt) ? "prior" : "invalid";
+  }
+  try {
+    await handle.writeFile(`${JSON.stringify(attempt)}\n`, "utf8");
+    await handle.sync();
+    return "first";
+  } catch {
+    return "invalid";
+  } finally {
+    await handle.close().catch(() => undefined);
+  }
+}
+
+function sameAttempt(value: unknown, expected: PlanAttempt): boolean {
+  return (
+    value !== null &&
+    typeof value === "object" &&
+    !Array.isArray(value) &&
+    (value as Record<string, unknown>).schema_version === 1 &&
+    (value as Record<string, unknown>).operation_id === expected.operation_id &&
+    (value as Record<string, unknown>).plan_digest === expected.plan_digest &&
+    Object.keys(value).length === 3
+  );
+}

memhub/apps/cli/src/package-matrix.test.ts

@@ -104,7 +104,7 @@ describe("package matrix harness", () => {
     });
   });
 
-  it("fails closed on every write command without a Runtime", {
+  it("fails closed on every destructive UI-write command without a Runtime", {
     timeout: 120_000,
   }, async () => {
     const runtimeDist = await mkdtemp(
@@ -122,9 +122,7 @@ describe("package matrix harness", () => {
       process.execPath,
       [script, runtimeDist, "--stopped-commands", "--json"],
       { env: isolatedEnv },
-    ).catch((error: { stdout?: string; stderr?: string }) => {
-      throw new Error(`${error.stdout ?? ""}\n${error.stderr ?? ""}`);
-    });
+    );
     const document = JSON.parse(positive.stdout) as {
       state: string;
       commands: {
@@ -139,8 +137,8 @@ describe("package matrix harness", () => {
     };
     expect(document.state).toBe("verified");
     const results = document.commands.stopped_destructive.results;
-    // Every destructive command fails closed while Runtime is stopped.
-    expect(Object.keys(results)).toHaveLength(8);
+    // 11 destructive commands, each unknown/runtime_not_running with exit 3.
+    expect(Object.keys(results)).toHaveLength(11);
     for (const [name, result] of Object.entries(results)) {
       expect(result, `${name} did not fail closed`).toEqual({
         exit: 3,
@@ -164,7 +162,7 @@ describe("package matrix harness", () => {
     const shim = [
       "#!/usr/bin/env node",
       "const a=process.argv.slice(2);",
-      "if(['graph-width','models','memories','sources'].includes(a[0])){",
+      "if(['calls','import-file','notes','extraction','graph','models'].includes(a[0])||(a[0]==='processing'&&a[1]==='extract')){",
       '  process.stdout.write(\'{"schema_version":1,"product":"memhub","state":"committed","operation_id":"x","receipt":{}}\\n\');',
       "  process.exit(0);",
       "}",
@@ -190,7 +188,7 @@ describe("package matrix harness", () => {
     expect(failure?.state).toBe("failed");
     expect(
       failure?.failures.filter((item) => item.includes("did not fail closed")),
-    ).toHaveLength(8);
+    ).toHaveLength(11);
   });
 
   it("can require an expected bundle SHA and reports bundle metadata", {
@@ -290,8 +288,11 @@ describe("package matrix harness", () => {
       "sources",
       "sync",
       "memories",
-      "profile",
-      "graph-width",
+      "calls",
+      "import-file",
+      "notes",
+      "extraction",
+      "graph",
       "models",
       "host",
       "doctor",
@@ -309,12 +310,15 @@ describe("package matrix harness", () => {
       "uninstall",
       "delete-data",
       "recall",
+      "setup",
       "scan",
       "progress",
       "jobs",
-      "scan-roots",
+      "processing",
+      "path",
       "adapter",
       "write",
+      "task",
       "serve",
     ];
     const catalog = {
@@ -340,7 +344,7 @@ describe("package matrix harness", () => {
       'command "models" is missing usage "memhub models activate"',
     );
     expect(failures).toContain(
-      'command "memories" is missing usage "memhub memories update"',
+      'command "import-file" is missing usage "memhub import-file discard"',
     );
     expect(failures).toContain(
       'command "jobs" is missing usage "memhub jobs start"',

memhub/apps/cli/src/product-command-contract.test.ts

@@ -145,26 +145,21 @@ describe("memhub short-command contract", () => {
       [command.usage, command.alternative_usage ?? ""].join("\n"),
     ).join("\n");
     for (const shortForm of [
-      "memhub memories add",
-      "memhub memories add-status",
+      "memhub calls clear",
+      "memhub import-file upload",
+      "memhub import-file commit",
+      "memhub import-file discard",
+      "memhub notes add",
+      "memhub notes process",
       "memhub models setup",
-      "memhub models add",
-      "memhub models test",
       "memhub models activate",
       "memhub models edit",
-      "memhub graph-width",
-      "memhub sources connect",
-      "memhub write submit",
-      "memhub write status",
-      "memhub memories update",
-      "memhub memories delete",
+      "memhub extraction set",
+      "memhub graph width",
+      "memhub processing extract",
     ]) {
       expect(flattened).toContain(shortForm);
     }
-    // No "note" concept and no plan files on the CLI surface.
-    for (const removed of ["memhub notes", "memhub calls", "--plan-file"]) {
-      expect(flattened).not.toContain(removed);
-    }
     expect(COMMANDS.some((command) => command.name === "permission")).toBe(
       false,
     );
@@ -217,7 +212,7 @@ describe("memhub short-command contract", () => {
   // but an earlier catalog text still claimed they were "尚不可用". A user
   // reading `help path` would not try a command that works.
   it("does not call the wired path/adapter commands unavailable", () => {
-    for (const name of ["scan-roots", "adapter"]) {
+    for (const name of ["path", "adapter"]) {
       const command = COMMANDS.find((entry) => entry.name === name);
       expect(command).toBeDefined();
       const text = [
@@ -283,7 +278,7 @@ describe("memhub short-command contract", () => {
     }
   });
 
-  it("keeps destructive previews free of diagnostic side effects", {
+  it("keeps plan-file apply previews free of diagnostic side effects", {
     timeout: 20_000,
   }, async () => {
     expect(
@@ -297,10 +292,9 @@ describe("memhub short-command contract", () => {
     );
     try {
       for (const [index, argv] of [
-        ["memories", "delete", "m-1"],
-        ["models", "remove", "44444444-4444-4444-8444-444444444444"],
-        ["backup", "restore", "--source", path.join(root, "backup.sqlite3")],
-        ["graph-width", "--decision", "rebuild_with_new"],
+        ["sources", "import", "--plan-file", path.join(root, "plan.json")],
+        ["models", "configure", "--plan-file", path.join(root, "plan.json")],
+        ["memories", "apply", "--plan-file", path.join(root, "plan.json")],
       ].entries()) {
         const dataDir = path.join(root, `data-${index}`);
         await import("node:fs/promises").then(({ mkdir }) =>
@@ -312,8 +306,8 @@ describe("memhub short-command contract", () => {
             stdio: "pipe",
           });
         } catch {
-          // A failure path is acceptable; the guard is that no preview adds
-          // a diagnostic file.
+          // The missing plan or stopped Runtime is expected; the guard is
+          // that even the failure path did not add a diagnostic file.
         }
         expect(await readdir(dataDir)).toEqual([]);
       }

memhub/apps/cli/src/product-flows.test.ts

@@ -1,56 +1,121 @@
-// The rules behind the commands that attach to the Runtime directly.
+// A6: the rules behind the six product commands.
 //
-// The parsers are where the contract actually lives — "only irreversible
-// operations ask for --yes" and "unknown flags are rejected" are decisions,
-// not formatting — so they are tested directly rather than only through the
-// CLI.
+// The parsers are where the contract actually lives — "needs --yes to change
+// anything" and "no write without evidence" are decisions, not formatting — so
+// they are tested directly rather than only through the CLI.
 
 import { describe, expect, it } from "vitest";
 
-import { parseOpenAIMessages } from "./core-client.js";
 import {
-  parseBackupCommand,
-  parseScanCommand,
-  parseScanRootsCommand,
+  asPlanDocument,
+  describe as describePlan,
+  parseProductCommand,
   parseTaskCommand,
   parseWriteCommand,
   restoreConfirmationMatches,
 } from "./product-flows.js";
 
-describe("scan-roots", () => {
-  it("reads the root, source and recursive flag off add", () => {
-    expect(
-      parseScanRootsCommand([
-        "add",
-        "--root",
-        "/tmp/x",
-        "--source",
-        "codex",
-        "--no-recursive",
-      ]),
-    ).toEqual({
-      kind: "add",
-      root: "/tmp/x",
-      source: "codex",
-      recursive: false,
-    });
-    expect(parseScanRootsCommand(["add", "--root", "/tmp/x"])).toEqual({
-      kind: "add",
-      root: "/tmp/x",
-      recursive: true,
-    });
+describe("mutating commands are two-phase", () => {
+  it("plans without --yes", () => {
+    const parsed = parseProductCommand("scan", ["--root", "/tmp/a"]);
+    expect(parsed?.confirmed).toBe(false);
   });
 
-  it("distinguishes remove from add and refuses add-only flags on remove", () => {
-    expect(parseScanRootsCommand(["remove", "--root", "/tmp/x"])).toEqual({
-      kind: "remove",
-      root: "/tmp/x",
-    });
+  it("confirms with --yes", () => {
+    const parsed = parseProductCommand("scan", ["--root", "/tmp/a", "--yes"]);
+    expect(parsed?.confirmed).toBe(true);
+  });
+
+  it("says what it would do", () => {
+    const parsed = parseProductCommand("scan", ["--root", "/tmp/a"]);
+    // `?.plan!` would let a null parse pass silently; assert the parse first.
+    if (parsed === null) {
+      throw new Error("scan with a root must parse");
+    }
+    expect(describePlan(parsed.plan)).toContain("scan: /tmp/a");
+  });
+
+  it("marks a plan as not applied", () => {
+    // Assert the parse itself: `?.` let a null result satisfy this test for as
+    // long as `backup create` was unparseable.
+    const parsed = parseProductCommand("backup", [
+      "create",
+      "--target",
+      "/tmp/b",
+    ]);
+    if (parsed === null) {
+      throw new Error("backup create must parse");
+    }
+    expect(parsed.plan.verb).toBe("create");
+    expect(asPlanDocument(parsed.plan).applied).toBe(false);
+  });
+
+  it("parses the verb for every command that takes one", () => {
+    // `path add` / `path remove` / `backup create` were rejected outright
+    // before the verb was skipped in parsing.
     expect(
-      parseScanRootsCommand(["remove", "--root", "/tmp/x", "--no-recursive"]),
+      parseProductCommand("path", ["add", "--root", "/tmp/x"])?.plan.action,
+    ).toBe("add scan root");
+    expect(
+      parseProductCommand("path", ["remove", "--root", "/tmp/x"])?.plan.action,
+    ).toBe("remove scan root");
+    expect(
+      parseProductCommand("backup", ["restore", "--source", "/tmp/b"])?.plan
+        .action,
+    ).toBe("restore backup");
+  });
+
+  it("defaults a scan to all registered roots", () => {
+    const parsed = parseProductCommand("scan", []);
+    expect(parsed?.plan.target).toBe("all registered roots");
+  });
+});
+
+describe("unknown flags are rejected", () => {
+  it("rejects a typo'd flag rather than ignoring it", () => {
+    // A silently ignored --yes would turn a real apply into a plan, and the
+    // user would believe the change had been made.
+    expect(parseProductCommand("scan", ["--yesx"])).toBeNull();
+    expect(parseProductCommand("scan", ["--root"])).toBeNull();
+    expect(parseProductCommand("scan", ["--root", "--yes"])).toBeNull();
+  });
+
+  it("rejects an unknown verb for backup", () => {
+    expect(
+      parseProductCommand("backup", ["make", "--target", "/tmp/b"]),
     ).toBeNull();
+  });
+
+  // `path` and `scan` share one parser. Before this guard, an unknown verb was
+  // silently treated as `path add` or a default `scan`, so `--yes` executed a
+  // different operation than the one the caller named.
+  it("rejects an unknown verb for path without turning it into add", () => {
     expect(
-      parseScanRootsCommand([
+      parseProductCommand("path", ["frobnicate", "--root", "/tmp/x", "--yes"]),
+    ).toBeNull();
+  });
+
+  it("rejects an unknown verb for scan without turning it into all", () => {
+    expect(
+      parseProductCommand("scan", ["frobnicate", "--all", "--yes"]),
+    ).toBeNull();
+    expect(parseProductCommand("scan", ["frobnicate", "--yes"])).toBeNull();
+  });
+
+  it("still accepts the documented verbless scan", () => {
+    expect(parseProductCommand("scan", ["--all", "--yes"])?.plan.all).toBe(
+      true,
+    );
+    expect(
+      parseProductCommand("scan", ["--source", "codex"])?.plan.sourceId,
+    ).toBe("codex");
+  });
+
+  it("rejects flags that the named verb does not consume", () => {
+    // These were accepted and then silently dropped. An operator who typed
+    // `path remove --source codex` would believe the source filter applied.
+    expect(
+      parseProductCommand("path", [
         "remove",
         "--root",
         "/tmp/x",
@@ -58,202 +123,229 @@ describe("scan-roots", () => {
         "codex",
       ]),
     ).toBeNull();
-  });
-
-  it("is direct, but keeps accepting a legacy --yes", () => {
-    expect(parseScanRootsCommand(["add", "--root", "/tmp/x", "--yes"])).toEqual(
-      { kind: "add", root: "/tmp/x", recursive: true },
-    );
-  });
-
-  it("rejects unknown verbs, typos and repeated flags", () => {
-    expect(parseScanRootsCommand(["create", "--root", "/tmp/x"])).toBeNull();
-    expect(parseScanRootsCommand(["add", "--rot", "/tmp/x"])).toBeNull();
-    expect(parseScanRootsCommand(["add"])).toBeNull();
     expect(
-      parseScanRootsCommand(["add", "--root", "/a", "--root", "/b"]),
+      parseProductCommand("path", [
+        "remove",
+        "--root",
+        "/tmp/x",
+        "--no-recursive",
+      ]),
     ).toBeNull();
     expect(
-      parseScanRootsCommand(["add", "--root", "/a", "--yes", "--yes"]),
-    ).toBeNull();
-  });
-});
-
-describe("scan", () => {
-  it("needs a source: there is no endpoint that scans a bare path", () => {
-    expect(parseScanCommand(["--source", "codex"])).toEqual({
-      kind: "source",
-      sourceId: "codex",
-    });
-    expect(parseScanCommand([])).toBeNull();
-    expect(parseScanCommand(["--root", "/tmp/a"])).toBeNull();
-  });
-
-  it("no longer accepts --full, which was never sent to Core", () => {
-    expect(parseScanCommand(["--source", "codex", "--full"])).toBeNull();
-  });
-
-  it("keeps --all as a hidden alias and a legacy --yes", () => {
-    expect(parseScanCommand(["--all", "--yes"])).toEqual({ kind: "all" });
-    expect(parseScanCommand(["--all", "--source", "codex"])).toBeNull();
-    expect(parseScanCommand(["--source", "codex", "--yes"])).toEqual({
-      kind: "source",
-      sourceId: "codex",
-    });
-  });
-
-  it("rejects a verb, a bad source id and repeated flags", () => {
-    expect(parseScanCommand(["all"])).toBeNull();
-    expect(parseScanCommand(["--source", "Bad Id"])).toBeNull();
-    expect(
-      parseScanCommand(["--source", "codex", "--source", "cursor"]),
+      parseProductCommand("path", ["add", "--root", "/tmp/x", "--full"]),
     ).toBeNull();
     expect(
-      parseScanCommand(["--source", "codex", "--json", "--json"]),
+      parseProductCommand("backup", [
+        "create",
+        "--target",
+        "/tmp/b",
+        "--source",
+        "/tmp/s",
+      ]),
     ).toBeNull();
-  });
-});
-
-describe("backup", () => {
-  it("creates directly and requires a target", () => {
-    expect(parseBackupCommand(["create", "--target", "/tmp/b"])).toEqual({
-      verb: "create",
-      target: "/tmp/b",
-    });
-    expect(parseBackupCommand(["create"])).toBeNull();
     expect(
-      parseBackupCommand(["create", "--target", "/tmp/b", "--source", "/x"]),
+      parseProductCommand("backup", [
+        "restore",
+        "--source",
+        "/tmp/s",
+        "--target",
+        "/tmp/t",
+      ]),
     ).toBeNull();
   });
 
-  it("restores only with --yes and requires a source", () => {
-    expect(parseBackupCommand(["restore", "--source", "/tmp/b"])).toEqual({
-      verb: "restore",
-      source: "/tmp/b",
-      confirmed: false,
-    });
+  // A later value silently won before this guard. For `scan --source` that
+  // means one extra shell/make variable can change which source is scanned
+  // while the operator believes both were applied.
+  it("rejects repeated value-bearing flags instead of letting the last one win", () => {
     expect(
-      parseBackupCommand(["restore", "--source", "/tmp/b", "--yes"]),
-    ).toMatchObject({ confirmed: true });
-    expect(parseBackupCommand(["restore", "--yes"])).toBeNull();
+      parseProductCommand("scan", ["--source", "codex", "--source", "cursor"]),
+    ).toBeNull();
+    expect(
+      parseProductCommand("path", [
+        "add",
+        "--root",
+        "/tmp/a",
+        "--root",
+        "/tmp/b",
+      ]),
+    ).toBeNull();
+    expect(
+      parseProductCommand("backup", [
+        "create",
+        "--target",
+        "/tmp/a",
+        "--target",
+        "/tmp/b",
+      ]),
+    ).toBeNull();
   });
 
-  it("accepts the legacy --confirm <path> and checks it lexically", () => {
-    const parsed = parseBackupCommand([
+  it("rejects repeated boolean flags instead of treating them as idempotent", () => {
+    expect(parseProductCommand("scan", ["--all", "--all", "--yes"])).toBeNull();
+    expect(
+      parseProductCommand("scan", ["--full", "--full", "--yes"]),
+    ).toBeNull();
+    expect(
+      parseProductCommand("path", [
+        "add",
+        "--root",
+        "/tmp/a",
+        "--no-recursive",
+        "--no-recursive",
+      ]),
+    ).toBeNull();
+    expect(
+      parseProductCommand("backup", [
+        "create",
+        "--target",
+        "/tmp/a",
+        "--yes",
+        "--yes",
+      ]),
+    ).toBeNull();
+  });
+
+  it("rejects a repeated global --json spelling", () => {
+    expect(
+      parseProductCommand("scan", ["--root", "/tmp/a", "--json", "--json"]),
+    ).toBeNull();
+    expect(
+      parseProductCommand("backup", [
+        "create",
+        "--target",
+        "/tmp/a",
+        "--json",
+        "--json",
+      ]),
+    ).toBeNull();
+  });
+
+  it("requires a source when restoring", () => {
+    expect(
+      parseProductCommand("backup", ["restore", "--target", "/tmp/b"]),
+    ).toBeNull();
+  });
+
+  it("parses the explicit restore confirmation path", () => {
+    const parsed = parseProductCommand("backup", [
       "restore",
       "--source",
-      "/tmp/b",
+      "/tmp/backups/a.sqlite3",
       "--yes",
       "--confirm",
-      "/tmp/b",
+      "/tmp/backups/a.sqlite3",
     ]);
-    expect(parsed).toMatchObject({ confirmPath: "/tmp/b" });
-    expect(restoreConfirmationMatches("/tmp/b", "/tmp/b")).toBe(true);
-    expect(restoreConfirmationMatches("/tmp/b", undefined)).toBe(true);
-    expect(restoreConfirmationMatches("/tmp/b", "/tmp/./b")).toBe(false);
+    expect(parsed).not.toBeNull();
+    expect(parsed?.confirmPath).toBe("/tmp/backups/a.sqlite3");
+    expect(
+      restoreConfirmationMatches("/tmp/backups/a.sqlite3", parsed?.confirmPath),
+    ).toBe(true);
+    expect(
+      restoreConfirmationMatches("/tmp/backups/a.sqlite3", undefined),
+    ).toBe(false);
+    expect(
+      restoreConfirmationMatches(
+        "/tmp/backups/a.sqlite3",
+        "/tmp/backups/../backups/a.sqlite3",
+      ),
+    ).toBe(false);
   });
 
-  it("rejects an unknown verb", () => {
-    expect(parseBackupCommand(["delete", "--target", "/tmp/b"])).toBeNull();
+  it("requires a target when creating a backup", () => {
+    expect(parseProductCommand("backup", ["create"])).toBeNull();
   });
 });
 
 describe("write", () => {
   const base = [
-    "submit",
     "--session",
     "s1",
-    "--messages-file",
-    "/tmp/messages.json",
+    "--from",
+    "1",
+    "--to",
+    "5",
+    "--evidence",
+    "e1",
   ];
 
   it("accepts a well-formed write", () => {
     const parsed = parseWriteCommand(base);
     expect(parsed).toEqual({
-      kind: "submit",
       session: "s1",
-      source: "memhub-cli",
-      messages_file: "/tmp/messages.json",
+      first_round: 1,
+      last_round: 5,
+      evidence_ids: ["e1"],
     });
   });
 
-  it("rejects a write with no messages file", () => {
-    expect(parseWriteCommand(["submit", "--session", "s1"])).toBeNull();
-  });
-
-  it("accepts source, request identity, and RFC3339 time", () => {
+  it("rejects a write with no evidence", () => {
     expect(
-      parseWriteCommand([
-        ...base,
-        "--source",
-        "cursor",
-        "--request-id",
-        "request-1",
-        "--memory-at",
-        "2026-10-22T00:00:00+08:00",
-      ]),
-    ).toMatchObject({
-      source: "cursor",
-      request_id: "request-1",
-      memory_at: "2026-10-22T00:00:00+08:00",
-    });
-  });
-
-  it("rejects a timestamp without timezone", () => {
-    expect(
-      parseWriteCommand([...base, "--memory-at", "2026-10-22T00:00:00"]),
+      parseWriteCommand(["--session", "s1", "--from", "1", "--to", "5"]),
     ).toBeNull();
   });
 
-  it("parses status under write, positional or --id", () => {
-    expect(parseWriteCommand(["status", "--id", "request-1"])).toEqual({
-      kind: "status",
-      id: "request-1",
-    });
-    expect(parseWriteCommand(["status", "request-1"])).toEqual({
-      kind: "status",
-      id: "request-1",
-    });
+  it("rejects a descending round range", () => {
+    expect(
+      parseWriteCommand([
+        "--session",
+        "s1",
+        "--from",
+        "5",
+        "--to",
+        "1",
+        "--evidence",
+        "e1",
+      ]),
+    ).toBeNull();
   });
 
-  it("rejects a repeated --session instead of letting the last one win", () => {
-    expect(parseWriteCommand([...base, "--session", "s2"])).toBeNull();
+  it("rejects a round starting below one", () => {
+    expect(
+      parseWriteCommand([
+        "--session",
+        "s1",
+        "--from",
+        "0",
+        "--to",
+        "5",
+        "--evidence",
+        "e1",
+      ]),
+    ).toBeNull();
+  });
+
+  it("rejects a non-integer round", () => {
+    expect(
+      parseWriteCommand([
+        "--session",
+        "s1",
+        "--from",
+        "x",
+        "--to",
+        "5",
+        "--evidence",
+        "e1",
+      ]),
+    ).toBeNull();
+  });
+
+  it("accepts several evidence ids", () => {
+    const parsed = parseWriteCommand([...base, "--evidence", "e2"]);
+    expect(parsed?.evidence_ids).toEqual(["e1", "e2"]);
   });
 
   it("marks --live as priority live", () => {
-    expect(parseWriteCommand([...base, "--live"])).toMatchObject({
-      kind: "submit",
-      priority: "live",
-    });
+    expect(parseWriteCommand([...base, "--live"])?.priority).toBe("live");
   });
 
   it("leaves priority unset by default", () => {
-    expect(parseWriteCommand(base)).not.toHaveProperty("priority");
+    expect(parseWriteCommand(base)?.priority).toBeUndefined();
   });
 
   it("rejects a repeated --json", () => {
     expect(parseWriteCommand([...base, "--json", "--json"])).toBeNull();
   });
-
-  it("validates OpenAI text messages and requires a user turn", () => {
-    expect(
-      parseOpenAIMessages({
-        messages: [
-          { role: "user", content: "Remember Tuesday." },
-          { role: "assistant", content: "Understood.", ignored: true },
-        ],
-      }),
-    ).toEqual([
-      { role: "user", content: "Remember Tuesday." },
-      { role: "assistant", content: "Understood." },
-    ]);
-    expect(
-      parseOpenAIMessages([{ role: "assistant", content: "No user turn." }]),
-    ).toBeNull();
-    expect(
-      parseOpenAIMessages([{ role: "system", content: "Hidden prompt." }]),
-    ).toBeNull();
-  });
 });
 
 describe("task", () => {
@@ -274,3 +366,53 @@ describe("task", () => {
     expect(parseTaskCommand(["--id", "req-1", "--json", "--json"])).toBeNull();
   });
 });
+
+describe("path add and remove carry what the endpoint needs", () => {
+  it("reads the source and recursive flag off the path add", () => {
+    const parsed = parseProductCommand("path", [
+      "add",
+      "--root",
+      "/tmp/scanme",
+      "--source",
+      "codex",
+      "--no-recursive",
+    ]);
+    // `?.plan!` let a null parse pass silently, so assert the parse itself.
+    if (parsed === null) {
+      throw new Error("path add must parse");
+    }
+    expect(parsed.plan.action).toBe("add scan root");
+    expect(parsed.plan.target).toBe("/tmp/scanme");
+    expect(parsed.plan.detail).toContain("source=codex");
+    expect(parsed.plan.detail).toContain("recursive=false");
+  });
+
+  it("distinguishes remove from add", () => {
+    const parsed = parseProductCommand("path", [
+      "remove",
+      "--root",
+      "/tmp/scanme",
+    ]);
+    if (parsed === null) {
+      throw new Error("path remove must parse");
+    }
+    // The action is the discriminator at apply time: add and remove share a
+    // `--root`, so a mis-set action would register the directory it meant to delete.
+    expect(parsed.plan.action).toBe("remove scan root");
+  });
+
+  it("does not silently drop --yes", () => {
+    const parsed = parseProductCommand("path", [
+      "add",
+      "--root",
+      "/tmp/a",
+      "--yes",
+    ]);
+    expect(parsed?.confirmed).toBe(true);
+    // Without this, a typo'd `--yes` would fall through to a plan and the user
+    // would believe the change had been made.
+
+    const without = parseProductCommand("path", ["add", "--root", "/tmp/a"]);
+    expect(without?.confirmed).toBe(false);
+  });
+});

memhub/apps/cli/src/product-flows.ts

@@ -1,242 +1,340 @@
-// Parsers for the commands that attach to the Runtime directly:
-// `scan-roots` (alias `path`), `scan`, `backup`, `write`.
+// A6: the product commands Runtime exposes on the CLI.
 //
-// Rules shared by all of them:
+// These are the six commands the objective names: path, adapter, scan, write,
+// task, backup. Two rules run through all of them:
 //
-// - **Only irreversible operations ask for `--yes`.** `backup restore`
-//   overwrites the database, so without `--yes` it previews and changes
-//   nothing. Registering a scan root, scanning a source, creating a backup and
-//   submitting a write are direct. A legacy `--yes` on a direct command is
-//   accepted and ignored so older scripts keep working.
-// - **Unknown or repeated flags are rejected**, never ignored: a dropped typo
-//   would silently change what the command does.
-// - **Output is machine-readable.** `--json` emits one document on stdout.
+// - **Mutating commands are two-phase.** Without `--yes` they print a plan and
+//   change nothing. This is the convention the existing install/service
+//   commands already follow, and it is why `scan` and `backup` default to a
+//   plan rather than quietly doing work.
+// - **Output is machine-readable.** `--json` emits one document on stdout so an
+//   agent can consume it; the human form is text. Never both, so a caller that
+//   parses stdout is not surprised by prose.
 //
 // The commands talk to the Runtime's HTTP API, not to the database and not to
-// the SDK: CLI and desktop are clients of the same Runtime.
+// HY. That is the A6 rule: CLI and Electron are clients of the same Runtime.
 
-export type ScanRootsCommand =
-  | {
-      readonly kind: "add";
-      readonly root: string;
-      readonly source?: string;
-      readonly recursive: boolean;
-    }
-  | { readonly kind: "remove"; readonly root: string };
-
-export type ScanCommand =
-  | { readonly kind: "source"; readonly sourceId: string }
-  /** Hidden alias of `sources connect --all-detected --import`. */
-  | { readonly kind: "all" };
-
-export type BackupCommand =
-  | { readonly verb: "create"; readonly target: string }
-  | {
-      readonly verb: "restore";
-      readonly source: string;
-      readonly confirmed: boolean;
-      /** Legacy `--confirm <path>`: accepted, and must repeat `--source`. */
-      readonly confirmPath?: string;
-    };
-
-interface ParsedFlags {
-  readonly values: Map<string, string>;
-  readonly switches: Set<string>;
+/** What a mutating command would do, before it is allowed to do it. */
+export interface Plan {
+  readonly action: string;
+  readonly target: string;
+  readonly detail?: string;
+  /** Which form of the command this plan is for, when one name has several.
+   *
+   * `backup` has `create` and `restore`, and applying the wrong one is not a
+   * harmless mistake — so the verb travels with the plan the user confirmed.
+   */
+  readonly verb?: string;
+  /** The source the Runtime endpoint addresses, when the plan names one.
+   *
+   * Carried on the plan rather than re-parsed at apply time so the plan the
+   * user confirmed and the request actually sent cannot disagree.
+   */
+  readonly sourceId?: string;
+  /** `scan --all`: every source Runtime actually found, not a named one. */
+  readonly all?: boolean;
 }
 
-/** Read `--flag value` pairs and bare switches; null on anything unknown,
- * repeated or missing its value. */
-function parseFlags(
+export function planAddRoot(
+  root: string,
+  source: string | undefined,
+  recursive: boolean,
+): Plan {
+  return {
+    action: "add scan root",
+    target: root,
+    detail: `source=${source ?? "auto"} recursive=${recursive}`,
+  };
+}
+
+export function planRemoveRoot(root: string): Plan {
+  return { action: "remove scan root", target: root };
+}
+
+export function planScan(root: string | undefined, full: boolean): Plan {
+  return {
+    action: "scan",
+    target: root ?? "all registered roots",
+    detail: `full=${full}`,
+  };
+}
+
+export function planScanSource(sourceId: string, full: boolean): Plan {
+  return {
+    action: "scan",
+    target: `source ${sourceId}`,
+    detail: `full=${full}`,
+    sourceId,
+  };
+}
+
+export function planScanAll(full: boolean): Plan {
+  return {
+    action: "scan",
+    target: "all detected sources",
+    detail: `full=${full}`,
+    all: true,
+  };
+}
+
+export function planBackup(target: string): Plan {
+  return { action: "create backup", target, verb: "create" };
+}
+
+export function planRestore(source: string): Plan {
+  return { action: "restore backup", target: source, verb: "restore" };
+}
+
+export interface ProductCommand {
+  readonly plan: Plan;
+  readonly confirmed: boolean;
+  /** For destructive verbs with a named artifact, the exact value repeated by
+   * the user. `backup restore` requires this to match `--source`. */
+  readonly confirmPath?: string;
+}
+
+/** Parse a mutating product command.
+ *
+ * Unknown flags are rejected rather than ignored: a typo'd `--yes` that is
+ * silently dropped would turn a real apply into a plan, and the user would
+ * believe the change had been made.
+ */
+export function parseProductCommand(
+  name: string,
   args: readonly string[],
-  valueFlags: readonly string[],
-  switchFlags: readonly string[],
-): ParsedFlags | null {
-  const values = new Map<string, string>();
-  const switches = new Set<string>();
-  for (let index = 0; index < args.length; index += 1) {
+): ProductCommand | null {
+  let root: string | undefined;
+  let source: string | undefined;
+  let target: string | undefined;
+  let recursive = true;
+  let full = false;
+  let all = false;
+  let confirmed = false;
+  let confirmPath: string | undefined;
+  const seen = new Set<string>();
+  const seenValues = new Set<string>();
+
+  const flags = new Set([
+    "--root",
+    "--source",
+    "--target",
+    "--confirm",
+    "--no-recursive",
+    "--full",
+    "--all",
+    "--yes",
+    "--json",
+  ]);
+
+  // The first token is the verb for commands that have one (`path add`,
+  // `backup create`). It used to fall into the flag loop and be rejected as an
+  // unknown flag, which made every one of these commands permanently
+  // unparseable — `path add --root X` printed "参数无效" even though `help`
+  // documented it. The tests missed this because they asserted
+  // `parsed?.plan!` and null satisfies `?.` + `!`.
+  const verb = args[0];
+  const start = verb !== undefined && !verb.startsWith("--") ? 1 : 0;
+
+  for (let index = start; index < args.length; index += 1) {
     const arg = args[index];
-    if (switchFlags.includes(arg)) {
-      if (switches.has(arg)) return null;
-      switches.add(arg);
+    if (!flags.has(arg)) return null;
+    // A repeated flag is a malformed argv, not an idempotent spelling. The
+    // other command parsers already apply this rule to --json as well.
+    if (seen.has(arg)) return null;
+    seen.add(arg);
+    if (arg === "--yes") {
+      confirmed = true;
+      continue;
+    }
+    if (arg === "--confirm") {
+      const value = args[index + 1];
+      if (value === undefined || value.startsWith("--")) return null;
+      if (confirmPath !== undefined) return null;
+      confirmPath = value;
+      index += 1;
+      continue;
+    }
+    if (arg === "--json") continue;
+    if (arg === "--no-recursive") {
+      recursive = false;
+      continue;
+    }
+    if (arg === "--full") {
+      full = true;
+      continue;
+    }
+    if (arg === "--all") {
+      all = true;
       continue;
     }
-    if (!valueFlags.includes(arg) || values.has(arg)) return null;
     const value = args[index + 1];
     if (value === undefined || value.startsWith("--")) return null;
-    values.set(arg, value);
+    if (seenValues.has(arg)) return null;
+    seenValues.add(arg);
     index += 1;
+    if (arg === "--root") root = value;
+    else if (arg === "--source") source = value;
+    else target = value;
   }
-  return { values, switches };
-}
 
-const SOURCE_ID = /^[a-z0-9][a-z0-9-]{0,127}$/;
-
-/** `scan-roots add --root <path> [--source <id>] [--no-recursive]` and
- * `scan-roots remove --root <path>` (`list` is answered separately). */
-export function parseScanRootsCommand(
-  args: readonly string[],
-): ScanRootsCommand | null {
-  const verb = args[0];
-  if (verb === "add") {
-    const flags = parseFlags(
-      args.slice(1),
-      ["--root", "--source"],
-      ["--no-recursive", "--yes", "--json"],
-    );
-    const root = flags?.values.get("--root");
-    if (!flags || root === undefined) return null;
-    const source = flags.values.get("--source");
-    if (source !== undefined && !SOURCE_ID.test(source)) return null;
+  if (name === "path") {
+    if (confirmPath !== undefined) return null;
+    if (target !== undefined) return null;
+    if (root === undefined) return null;
+    if (source === undefined && args.includes("--source")) return null;
+    if (seen.has("--full") || seen.has("--all")) return null;
+    if (args[0] !== "add" && args[0] !== "remove") return null;
+    if (
+      args[0] === "remove" &&
+      (seen.has("--source") || seen.has("--no-recursive"))
+    ) {
+      return null;
+    }
     return {
-      kind: "add",
-      root,
-      ...(source === undefined ? {} : { source }),
-      recursive: !flags.switches.has("--no-recursive"),
+      plan:
+        args[0] === "add"
+          ? planAddRoot(root, source, recursive)
+          : planRemoveRoot(root),
+      confirmed,
     };
   }
-  if (verb === "remove") {
-    const flags = parseFlags(args.slice(1), ["--root"], ["--yes", "--json"]);
-    const root = flags?.values.get("--root");
-    return flags && root !== undefined ? { kind: "remove", root } : null;
+  if (name === "scan") {
+    if (confirmPath !== undefined) return null;
+    if (target !== undefined) return null;
+    if (seen.has("--no-recursive")) return null;
+    if (args[0] !== undefined && !args[0].startsWith("--")) return null;
+    // `--all` means "every source Runtime actually found", so naming one too
+    // would make the command mean two different things.
+    if (all && source !== undefined) return null;
+    if (all) return { plan: planScanAll(full), confirmed };
+    // A source is the thing the Runtime scan endpoint addresses. A bare root is
+    // still accepted for planning (it means "all registered roots") but cannot
+    // be applied, because there is no endpoint that scans a raw path — the CLI
+    // must not pretend it can.
+    if (source === undefined) return { plan: planScan(root, full), confirmed };
+    return { plan: planScanSource(source, full), confirmed };
   }
-  return null;
-}
-
-/** `scan --source <id>`. A scan names a source: the Runtime has no endpoint
- * that scans a bare path, so a missing `--source` is a usage error rather
- * than a preview of something that can never run. */
-export function parseScanCommand(args: readonly string[]): ScanCommand | null {
-  const flags = parseFlags(args, ["--source"], ["--all", "--yes", "--json"]);
-  if (!flags) return null;
-  const source = flags.values.get("--source");
-  if (flags.switches.has("--all")) {
-    return source === undefined ? { kind: "all" } : null;
-  }
-  return source !== undefined && SOURCE_ID.test(source)
-    ? { kind: "source", sourceId: source }
-    : null;
-}
-
-/** `backup create --target <path>` and
- * `backup restore --source <path> [--yes]`. */
-export function parseBackupCommand(
-  args: readonly string[],
-): BackupCommand | null {
-  const verb = args[0];
-  if (verb === "create") {
-    const flags = parseFlags(args.slice(1), ["--target"], ["--yes", "--json"]);
-    const target = flags?.values.get("--target");
-    return flags && target !== undefined ? { verb: "create", target } : null;
-  }
-  if (verb === "restore") {
-    const flags = parseFlags(
-      args.slice(1),
-      ["--source", "--confirm"],
-      ["--yes", "--json"],
-    );
-    const source = flags?.values.get("--source");
-    if (!flags || source === undefined) return null;
-    const confirmPath = flags.values.get("--confirm");
+  if (name === "backup") {
+    const verb = args[0];
+    if (verb !== "create" && verb !== "restore") return null;
+    if (seen.has("--full") || seen.has("--all") || seen.has("--no-recursive")) {
+      return null;
+    }
+    if (verb === "restore") {
+      if (source === undefined) return null;
+      if (target !== undefined) return null;
+      return {
+        plan: planRestore(source),
+        confirmed,
+        ...(confirmPath === undefined ? {} : { confirmPath }),
+      };
+    }
+    if (confirmPath !== undefined) return null;
+    if (source !== undefined) return null;
+    if (target === undefined) return null;
     return {
-      verb: "restore",
-      source,
-      confirmed: flags.switches.has("--yes"),
+      plan: planBackup(target),
+      confirmed,
       ...(confirmPath === undefined ? {} : { confirmPath }),
     };
   }
   return null;
 }
 
-/** Whether a legacy `--confirm <path>` names the same restore source.
+/** Whether `--confirm <path>` names the same restore source.
  *
  * The comparison is lexical on purpose: the CLI must not resolve symlinks or
  * touch the filesystem before Core has validated the managed source. A
- * different string is a different confirmation.
+ * different string is a different confirmation, so a typo or a path escape
+ * can never be applied as a side effect of `--yes`.
  */
 export function restoreConfirmationMatches(
   source: string,
   confirmPath: string | undefined,
 ): boolean {
-  return confirmPath === undefined || confirmPath === source;
+  return confirmPath === source;
 }
 
-export interface WriteSubmitCommand {
-  readonly kind: "submit";
+export interface WriteCommand {
   readonly session: string;
-  readonly source: string;
-  readonly messages_file: string;
-  readonly request_id?: string;
-  readonly memory_at?: string;
+  readonly first_round: number;
+  readonly last_round: number;
+  readonly evidence_ids: readonly string[];
   readonly priority?: "live" | "normal";
 }
 
-export interface WriteStatusCommand {
-  readonly kind: "status";
-  readonly id: string;
-}
-
-export type WriteCommand = WriteSubmitCommand | WriteStatusCommand;
-
-/** Parse `write submit ...` and `write status <request-id>` (or `--id`). */
+/** Parse `write`. Evidence is required: no write without something to cite. */
 export function parseWriteCommand(
   args: readonly string[],
 ): WriteCommand | null {
   if (args.filter((item) => item === "--json").length > 1) return null;
-  const meaningful = args.filter((item) => item !== "--json");
-  if (meaningful[0] === "status") {
-    const rest = meaningful.slice(1);
-    if (rest.length === 1 && !rest[0].startsWith("--")) {
-      return { kind: "status", id: rest[0] };
+  let session: string | undefined;
+  let first: number | undefined;
+  let last: number | undefined;
+  let priority: "live" | "normal" | undefined;
+  const evidence: string[] = [];
+
+  for (let index = 0; index < args.length; index += 1) {
+    const arg = args[index];
+    if (arg === "--json") continue;
+    if (arg === "--live") {
+      priority = "live";
+      continue;
     }
-    const status = parseTaskCommand(rest);
-    return status === null ? null : { kind: "status", id: status.id };
+    const value = args[index + 1];
+    if (value === undefined || value.startsWith("--")) return null;
+    index += 1;
+    if (arg === "--session") session = value;
+    else if (arg === "--from") first = Number(value);
+    else if (arg === "--to") last = Number(value);
+    else if (arg === "--evidence") evidence.push(value);
+    else return null;
   }
-  // `write --session ...` without `submit` stays accepted for older scripts.
-  const input = meaningful[0] === "submit" ? meaningful.slice(1) : meaningful;
-  const flags = parseFlags(
-    input,
-    ["--session", "--source", "--messages-file", "--request-id", "--memory-at"],
-    ["--live"],
-  );
-  if (!flags) return null;
-  const session = flags.values.get("--session");
-  const source = flags.values.get("--source") ?? "memhub-cli";
-  const messagesFile = flags.values.get("--messages-file");
-  const requestId = flags.values.get("--request-id");
-  const memoryAt = flags.values.get("--memory-at");
-  if (session === undefined || messagesFile === undefined || !source)
+
+  if (session === undefined || first === undefined || last === undefined)
     return null;
-  if (
-    memoryAt !== undefined &&
-    (!Number.isFinite(Date.parse(memoryAt)) ||
-      !/(?:Z|[+-]\d\d:\d\d)$/.test(memoryAt))
-  )
-    return null;
-  const command: WriteSubmitCommand = {
-    kind: "submit",
+  if (!Number.isInteger(first) || first < 1) return null;
+  if (!Number.isInteger(last) || last < first) return null;
+  if (evidence.length === 0) return null;
+  const command: WriteCommand = {
     session,
-    source,
-    messages_file: messagesFile,
-    ...(requestId === undefined ? {} : { request_id: requestId }),
-    ...(memoryAt === undefined ? {} : { memory_at: memoryAt }),
+    first_round: first,
+    last_round: last,
+    evidence_ids: evidence,
   };
-  return flags.switches.has("--live")
-    ? { ...command, priority: "live" }
-    : command;
+  return priority === undefined ? command : { ...command, priority };
 }
 
 export interface TaskCommand {
   readonly id: string;
 }
 
-/** `--id <request-id>`: the legacy `task` spelling of `write status`. */
 export function parseTaskCommand(args: readonly string[]): TaskCommand | null {
   if (args.filter((item) => item === "--json").length > 1) return null;
-  const flags = parseFlags(
-    args.filter((item) => item !== "--json"),
-    ["--id"],
-    [],
-  );
-  const id = flags?.values.get("--id");
+  let id: string | undefined;
+  for (let index = 0; index < args.length; index += 1) {
+    const arg = args[index];
+    if (arg === "--json") continue;
+    if (arg !== "--id") return null;
+    const value = args[index + 1];
+    if (value === undefined || value.startsWith("--")) return null;
+    index += 1;
+    id = value;
+  }
   return id === undefined ? null : { id };
 }
+
+/** The human form. Kept separate from the JSON form on purpose. */
+export function describe(plan: Plan): string {
+  const line = `${plan.action}: ${plan.target}`;
+  return plan.detail ? `${line} (${plan.detail})` : line;
+}
+
+/** The machine form: one document, nothing else on stdout. */
+export function asPlanDocument(plan: Plan): {
+  schema_version: 1;
+  plan: Plan;
+  applied: boolean;
+} {
+  return { schema_version: 1, plan, applied: false };
+}

memhub/apps/cli/src/read-only-queries.test.ts

@@ -184,16 +184,8 @@ const CORE = new Map<string, { status: number; data: unknown }>([
     },
   ],
   [
-    "/api/v2/home-summary",
-    {
-      status: 200,
-      data: {
-        schema_version: 2,
-        memory_count: 42,
-        latest: null,
-        observed_at: "T",
-      },
-    },
+    "/api/v1/home-summary",
+    { status: 200, data: { memory_count: 42, latest: null, observed_at: "T" } },
   ],
 ]);
 
@@ -202,10 +194,9 @@ const READ_ONLY_PATHS = [
   "/api/v1/live-sync",
   "/api/v1/memory-processing",
   "/api/v1/model-profiles",
-  "/api/v2/home-summary",
-  "/api/v2/memory-library",
-  "/api/v2/memories/",
-  "/api/v2/user-profile",
+  "/api/v1/home-summary",
+  "/api/v1/memory-library",
+  "/api/v1/memories/",
 ];
 
 const BACKGROUND_HEALTHY = {
@@ -571,43 +562,6 @@ describe("CLI-20 status summary", () => {
   });
 });
 
-describe("SDK user profile", () => {
-  it("prints the assembled long-term profile from the v2 endpoint", async () => {
-    transport.get.mockImplementation(async (url: string) =>
-      url === "/api/v2/user-profile"
-        ? {
-            status: 200,
-            data: {
-              request_id: "profile-request",
-              profile: {
-                memory_id: "l0-head",
-                content: "name is Alice",
-                layer: "L0_BASIC_INFO",
-                basic_info: { name: "Alice" },
-              },
-              elapsed_ms: 1.2,
-            },
-          }
-        : { status: 404, data: {} },
-    );
-    const streams = captureStreams();
-    try {
-      expect(await run(["profile", "--json"], {})).toBe(0);
-    } finally {
-      streams.restore();
-    }
-    expect(transport.get).toHaveBeenCalledWith(
-      "/api/v2/user-profile",
-      undefined,
-    );
-    expect(JSON.parse(streams.stdout())).toMatchObject({
-      schema_version: 2,
-      state: "ok",
-      profile: { memory_id: "l0-head", content: "name is Alice" },
-    });
-  });
-});
-
 describe("CLI-21 memory reads", () => {
   it("keeps memory reads open long enough for a busy Core and explains failure", async () => {
     const axios = (await import("axios")).default as unknown as {
@@ -656,14 +610,14 @@ describe("CLI-21 memory reads", () => {
 
   it("lists a page and states truthfully that more remains", async () => {
     transport.get.mockImplementation(async (url: string) => {
-      if (url !== "/api/v2/memory-library") return { status: 404, data: {} };
+      if (url !== "/api/v1/memory-library") return { status: 404, data: {} };
       return {
         status: 200,
         data: {
           total: 12,
           offset: 0,
           limit: 2,
-          memories: [memory("m1", "第一条记忆"), memory("m2", "x".repeat(400))],
+          items: [memory("m1", "第一条记忆"), memory("m2", "x".repeat(400))],
         },
       };
     });
@@ -686,8 +640,10 @@ describe("CLI-21 memory reads", () => {
     });
     expect(report.memories[0]).toMatchObject({
       memory_id: "m1",
-      status: "active",
-      layer: "L2_FACT",
+      status: "confirmed",
+      revision: 3,
+      scopes: ["all-apps"],
+      evidence_ids: ["e1"],
       content_truncated: false,
     });
     expect(report.memories[1]).toMatchObject({
@@ -697,73 +653,17 @@ describe("CLI-21 memory reads", () => {
     expect(report.memories[1].content.length).toBeLessThan(400);
   });
 
-  it("lists working and coding memories with their scene and kind", async () => {
-    transport.get.mockResolvedValue({
-      status: 200,
-      data: {
-        total: 2,
-        offset: 0,
-        limit: 20,
-        totals: { chat: 1, working: 1, coding: 0 },
-        window_id: null,
-        window_reset: false,
-        memories: [
-          memory("m1", "对话记忆"),
-          {
-            ...memory("e1", "修复测试\n固定随机种子"),
-            layer: "experience",
-            agent_id: "",
-            owner: null,
-            source_raw_ids: [],
-            scene: "working",
-            kind: "experience",
-            variant: "working",
-            task: "修复测试",
-            solution: "固定随机种子",
-            created_at: 1_790_000_000,
-            updated_at: 1_790_000_100,
-          },
-        ],
-      },
-    });
-    const streams = captureStreams();
-    try {
-      expect(await run(["memories", "list", "--json"], {})).toBe(0);
-    } finally {
-      streams.restore();
-    }
-    const report = JSON.parse(streams.stdout());
-    expect(report.page).toMatchObject({ state: "ok", total: 2, returned: 2 });
-    expect(report.memories[0]).toMatchObject({
-      memory_id: "m1",
-      scene: "chat",
-      kind: "chat",
-      variant: null,
-    });
-    expect(report.memories[1]).toMatchObject({
-      memory_id: "e1",
-      scene: "working",
-      kind: "experience",
-      variant: "working",
-      layer: "experience",
-    });
-
-    const text = captureStreams();
-    try {
-      expect(await run(["memories", "list"], {})).toBe(0);
-    } finally {
-      text.restore();
-    }
-    expect(text.stdout()).toContain("- e1  [working] active/experience");
-  });
-
   it("passes the requested filters through as query parameters", async () => {
     await run(
       [
         "memories",
         "list",
+        "--query",
+        "部署",
         "--status",
-        "active",
+        "confirmed",
+        "--source",
+        "codex",
         "--offset",
         "10",
         "--limit",
@@ -772,23 +672,30 @@ describe("CLI-21 memory reads", () => {
       ],
       {},
     ).catch(() => undefined);
-    expect(transport.get).toHaveBeenCalledWith("/api/v2/memory-library", {
+    expect(transport.get).toHaveBeenCalledWith("/api/v1/memory-library", {
       params: {
-        statuses: "active",
+        query: "部署",
+        status: "confirmed",
+        source: "codex",
         offset: 10,
         limit: 5,
       },
     });
   });
 
-  it("rejects retired memory query flags before calling Core", async () => {
+  it("reads a sensitive query from a file so it stays out of shell history", async () => {
     const directory = await mkdtemp(path.join(tmpdir(), "om-cli-query-"));
     const file = path.join(directory, "query.txt");
     await writeFile(file, "机密查询\n", { mode: 0o600 });
-    expect(
-      await run(["memories", "list", "--query-file", file, "--json"], {}),
-    ).toBe(2);
-    expect(transport.get).not.toHaveBeenCalled();
+    await run(["memories", "list", "--query-file", file, "--json"], {}).catch(
+      () => undefined,
+    );
+    expect(transport.get).toHaveBeenCalledWith(
+      "/api/v1/memory-library",
+      expect.objectContaining({
+        params: expect.objectContaining({ query: "机密查询" }),
+      }),
+    );
   });
 
   it("rejects contradictory or unreadable query input before calling Core", async () => {
@@ -798,7 +705,7 @@ describe("CLI-21 memory reads", () => {
       ["memories", "list", "--limit", "0"],
       ["memories", "list", "--limit", "501"],
       ["memories", "list", "--offset", "-1"],
-      ["memories", "list", "--status", ""],
+      ["memories", "list", "--status", "unknown-status"],
       ["memories", "show"],
       ["memories"],
     ]) {
@@ -816,7 +723,7 @@ describe("CLI-21 memory reads", () => {
   it("distinguishes an empty page from a denied or missing one", async () => {
     transport.get.mockResolvedValue({
       status: 200,
-      data: { total: 0, offset: 0, limit: 100, memories: [] },
+      data: { total: 0, offset: 0, limit: 100, items: [] },
     });
     const empty = captureStreams();
     try {
@@ -856,10 +763,33 @@ describe("CLI-21 memory reads", () => {
     });
   });
 
-  it("shows one SDK memory without fabricated Evidence or versions", async () => {
+  it("shows one memory with its source, version and evidence", async () => {
     transport.get.mockResolvedValue({
       status: 200,
-      data: memory("m1", "记忆正文"),
+      data: {
+        memory: memory("m1", "记忆正文"),
+        evidence: [
+          {
+            evidence_id: "e1",
+            available: true,
+            source_id: "codex",
+            written_by: "user",
+            created_at: "T",
+            verbatim: "y".repeat(500),
+          },
+        ],
+        history: [
+          {
+            memory_id: "m1",
+            revision: 3,
+            action: "correct",
+            status: "confirmed",
+            content: "记忆正文",
+            scopes: ["all-apps"],
+            created_at: "T",
+          },
+        ],
+      },
     });
     const streams = captureStreams();
     try {
@@ -869,23 +799,31 @@ describe("CLI-21 memory reads", () => {
     }
     const report = JSON.parse(streams.stdout());
     expect(transport.get).toHaveBeenCalledWith(
-      "/api/v2/memories/m1",
+      "/api/v1/memories/m1",
       undefined,
     );
     expect(report.memory).toMatchObject({
       state: "ok",
       memory_id: "m1",
-      layer: "L2_FACT",
-      status: "active",
+      revision: 3,
+      scopes: ["all-apps"],
+    });
+    expect(report.evidence[0]).toMatchObject({
+      evidence_id: "e1",
+      source_id: "codex",
+      excerpt_truncated: true,
+      excerpt_characters: 500,
+    });
+    expect(report.history[0]).toMatchObject({
+      revision: 3,
+      action: "correct",
+      status: "confirmed",
+      scopes: ["all-apps"],
+      content: "记忆正文",
     });
-    // Schema 2, like add/update/delete; the v1-era always-empty
-    // `evidence`/`history` fields are gone.
-    expect(report.schema_version).toBe(2);
-    expect(report).not.toHaveProperty("evidence");
-    expect(report).not.toHaveProperty("history");
   });
 
-  // Core registers /api/v2/memories/graph before /{memory_id}, and that static
+  // Core registers /api/v1/memories/graph before /{memory_id}, and that static
   // handler initializes the HY bridge. A memory id that collides with a
   // reserved segment must never become a request.
   it("refuses a memory id that collides with a static Core route", async () => {
@@ -899,15 +837,16 @@ describe("CLI-21 memory reads", () => {
       expect(streams.stdout()).toBe("");
     }
     expect(transport.get).not.toHaveBeenCalled();
-    expect(isReadOnlyPath("/api/v2/memories/graph")).toBe(false);
-    expect(isReadOnlyPath("/api/v2/memories/ask")).toBe(false);
-    expect(isReadOnlyPath("/api/v2/memories/m1")).toBe(true);
-    expect(isReadOnlyPath("/api/v2/memory-library")).toBe(true);
-    expect(isReadOnlyPath("/api/v2/home-summary")).toBe(true);
-    // The retired v1 data plane is no longer a CLI read.
-    expect(isReadOnlyPath("/api/v1/memories/m1")).toBe(false);
-    expect(isReadOnlyPath("/api/v1/home-summary")).toBe(false);
+    expect(isReadOnlyPath("/api/v1/memories/graph")).toBe(false);
+    expect(isReadOnlyPath("/api/v1/memories/ask")).toBe(false);
+    expect(isReadOnlyPath("/api/v1/memories/m1")).toBe(true);
     expect(isReadOnlyPath("/api/v1/model-content-permission")).toBe(false);
+    expect(
+      isReadOnlyPath(
+        "/api/v1/memory-mutations/123e4567-e89b-12d3-a456-426614174000",
+      ),
+    ).toBe(true);
+    expect(isReadOnlyPath("/api/v1/memory-mutations/../sources")).toBe(false);
   });
 
   it("refuses a memory id that would escape the memories path", async () => {
@@ -927,26 +866,6 @@ describe("CLI-21 memory reads", () => {
 // was cast to the expected type, so a wrong record, an unavailable excerpt, an
 // oversized page and a non-string model field all reached stdout as success.
 describe("malformed success responses", () => {
-  it("treats a v1-shaped home summary as invalid, not as a memory count", async () => {
-    transport.get.mockImplementation(async (url: string) =>
-      url === "/api/v2/home-summary"
-        ? {
-            status: 200,
-            data: { memory_count: 7, latest: null, observed_at: "T" },
-          }
-        : (CORE.get(url) ?? { status: 404, data: { detail: "not_found" } }),
-    );
-    const streams = captureStreams();
-    try {
-      await run(["status", "--json"], {});
-    } finally {
-      streams.restore();
-    }
-    expect(JSON.parse(streams.stdout()).sections.memories).toMatchObject({
-      state: "invalid",
-    });
-  });
-
   it("refuses a detail that is not the memory that was asked for", async () => {
     transport.get.mockResolvedValue({
       status: 200,
@@ -1140,16 +1059,14 @@ describe("backup create target refusal is rejected, not usage_error", () => {
     let code: number;
     try {
       code = await run(
-        ["backup", "create", "--target", "/tmp/outside.db", "--json"],
+        ["backup", "create", "--target", "/tmp/outside.db", "--yes", "--json"],
         {},
       );
     } finally {
       streams.restore();
     }
     expect(code!).toBe(1);
-    // A result, on stdout like every --json document.
-    expect(streams.stderr()).toBe("");
-    const document = JSON.parse(streams.stdout());
+    const document = JSON.parse(streams.stderr());
     expect(document.status).not.toBe("usage_error");
     expect(document).toMatchObject({
       command: "backup",
@@ -1220,20 +1137,17 @@ function memory(id: string, content: string) {
   return {
     memory_id: id,
     user_id: "local",
-    agent_id: "one-memory",
-    layer: "L2_FACT",
-    status: "active",
-    is_latest: true,
-    supersedes: [],
-    superseded_by: [],
+    kind: "chat",
+    status: "confirmed",
     content,
+    scopes: ["all-apps"],
+    evidence_ids: ["e1"],
+    origin: "extracted",
     tags: [],
-    owner: "user",
-    source_raw_ids: ["raw-1"],
-    session_id: "s1",
-    source: "codex",
-    memory_at: null,
-    gmt_created: null,
+    revision: 3,
+    created_at: "T",
+    updated_at: "T",
+    deleted_at: null,
   };
 }
 

memhub/apps/cli/src/service-lifecycle.test.ts

@@ -315,40 +315,6 @@ describe("macOS service lifecycle", () => {
     expect(deps.verifyRegistrationSnapshot).toHaveBeenCalledTimes(2);
   });
 
-  it("does not re-bootstrap a previous registration that may serve a legacy home", async () => {
-    const f = fixture();
-    const oldPath = "/Users/example/Library/LaunchAgents/old-runtime.plist";
-    const runCommand = vi
-      .fn()
-      .mockResolvedValueOnce(undefined)
-      .mockRejectedValueOnce(new Error("bootstrap failed"));
-    const deps = dependencies({
-      inspectRegistration: vi.fn(async () => ({
-        kind: "managed" as const,
-        plistPath: oldPath,
-        content: "old managed plist",
-      })),
-      runCommand,
-    });
-
-    const prepared = await prepareServiceInstall(f.layout, f.options, deps);
-    await expect(
-      applyPreparedServiceInstall(
-        { ...prepared, restorePreviousOnFailure: false },
-        deps,
-      ),
-    ).rejects.toThrow("runtime_service_replacement_failed");
-
-    // bootout + the failed bootstrap only; the old plist is not bootstrapped.
-    expect(runCommand).toHaveBeenCalledTimes(2);
-    expect(runCommand).not.toHaveBeenCalledWith([
-      "launchctl",
-      "bootstrap",
-      "gui/501",
-      oldPath,
-    ]);
-  });
-
   it("removes the replacement plist and restores the previous registration", async () => {
     const f = fixture();
     const oldPath = "/Users/example/Library/LaunchAgents/old-runtime.plist";

memhub/apps/cli/src/service-lifecycle.ts

@@ -72,13 +72,6 @@ export type PreparedServiceInstall = {
   mode: "direct" | "bootstrap-existing" | "restart" | "replace";
   previous?: ManagedSnapshot;
   previouslyEnabled: boolean;
-  /**
-   * Re-bootstrap the previous (possibly older) LaunchAgent when the new one
-   * fails to bootstrap. `install` turns this off once the home has been handed
-   * to this version's SDK migration: an older Runtime has no migration gate and
-   * would serve a home that is not on SDK authority.
-   */
-  restorePreviousOnFailure?: boolean;
 };
 
 const defaultDependencies: ServiceLifecycleDependencies = {
@@ -198,8 +191,7 @@ export async function applyPreparedServiceInstall(
     if (!previous) throw new Error("runtime_service_upgrade_state_invalid");
     await verifyPreparedRegistration(prepared, dependencies);
     const domain = launchdDomain(options.uid);
-    let replacementFailure: "upgrade" | "rollback" | "not-restored" | null =
-      null;
+    let replacementFailure: "upgrade" | "rollback" | null = null;
     const replaceCommand: ServiceCommandRunner = async (command) => {
       if (command[0] !== "launchctl" || command[1] !== "bootstrap") {
         await dependencies.runCommand(command);
@@ -216,10 +208,6 @@ export async function applyPreparedServiceInstall(
         await dependencies.runCommand(command);
       } catch {
         replacementFailure = "upgrade";
-        if (prepared.restorePreviousOnFailure === false) {
-          replacementFailure = "not-restored";
-          throw new Error("runtime_service_replacement_failed");
-        }
         try {
           await dependencies.verifyRegistrationSnapshot(previous);
           await dependencies.runCommand([
@@ -246,9 +234,6 @@ export async function applyPreparedServiceInstall(
       if (replacementFailure === "upgrade") {
         throw new Error("runtime_service_managed_upgrade_failed");
       }
-      if (replacementFailure === "not-restored") {
-        throw new Error("runtime_service_replacement_failed");
-      }
       throw error;
     }
   } catch (error) {

memhub/apps/cli/src/source-progress-report.ts

@@ -7,10 +7,12 @@ import type {
 } from "@one-memory/contracts";
 import type { CoreReader, ReadOutcome } from "./core-client.js";
 import {
+  type ValidatedMemoryTask,
   validateImportIssues,
   validateImportJob,
   validateImportJobs,
   validateLiveSync,
+  validateMemoryTasks,
   validateProcessing,
   validateSources,
 } from "./core-responses.js";
@@ -68,6 +70,11 @@ export interface ProgressDocument {
   generation: {
     summary_state: ReadState;
     summary: Record<string, unknown> | null;
+    tasks_state: ReadState;
+    tasks: Array<Record<string, unknown>>;
+    returned: number;
+    validated: number;
+    output_truncated: boolean;
   };
 }
 
@@ -127,13 +134,12 @@ export async function readProgress(
   const importsPath = options.jobId
     ? `/api/v1/import-jobs/${options.jobId}`
     : "/api/v1/import-jobs";
-  // Generation progress comes from `memory-processing` alone: under SDK
-  // authority the per-task list (`/api/v1/memory-tasks`) is retired and empty.
-  const [importsRead, sourcesRead, processingRead, issuesRead] =
+  const [importsRead, sourcesRead, processingRead, tasksRead, issuesRead] =
     await Promise.all([
       reader<unknown>(importsPath),
       reader<unknown>("/api/v1/sources"),
       reader<unknown>("/api/v1/memory-processing"),
+      reader<unknown>("/api/v1/memory-tasks"),
       options.jobId && options.issues
         ? reader<unknown>(`/api/v1/import-jobs/${options.jobId}/issues`)
         : Promise.resolve(null),
@@ -147,6 +153,7 @@ export async function readProgress(
     : validated(importsRead, validateImportJobs);
   const processing = validated(processingRead, validateProcessing);
   const sources = validated(sourcesRead, validateSources);
+  const tasks = validated(tasksRead, validateMemoryTasks);
   const issues =
     options.jobId && options.issues && issuesRead
       ? validated(issuesRead, (value) =>
@@ -155,19 +162,25 @@ export async function readProgress(
       : null;
 
   const jobs = imports.state === "ok" ? imports.data : [];
+  const taskItems = tasks.state === "ok" ? tasks.data : [];
   const issueItems = issues?.state === "ok" ? issues.data : [];
   const importState = stateOnly(imports);
   const summaryState = stateOnly(processing);
+  const tasksState = stateOnly(tasks);
 
   const hasReadFailure =
     importState.state !== "ok" ||
     sources.state !== "ok" ||
     summaryState.state !== "ok" ||
+    tasksState.state !== "ok" ||
     (issues !== null && issues.state !== "ok");
   const hasProblem =
     jobs.some((job) =>
       ["paused", "interrupted", "failed"].includes(job.status),
     ) ||
+    taskItems.some((task) =>
+      ["waiting_for_model", "failed"].includes(task.status),
+    ) ||
     (processing.state === "ok" &&
       (processing.data.failed > 0 ||
         processing.data.waiting_for_model > 0 ||
@@ -175,6 +188,7 @@ export async function readProgress(
     issueItems.length > 0;
   const hasActive =
     jobs.some((job) => ["pending", "running"].includes(job.status)) ||
+    taskItems.some((task) => ["pending", "running"].includes(task.status)) ||
     (processing.state === "ok" &&
       (processing.data.pending > 0 || processing.data.running > 0));
 
@@ -215,6 +229,11 @@ export async function readProgress(
       summary_state: summaryState,
       summary:
         processing.state === "ok" ? projectProcessing(processing.data) : null,
+      tasks_state: tasksState,
+      tasks: taskItems.slice(0, options.limit).map(projectTask),
+      returned: Math.min(taskItems.length, options.limit),
+      validated: taskItems.length,
+      output_truncated: taskItems.length > options.limit,
     },
   };
 }
@@ -270,7 +289,10 @@ export function renderProgressText(document: ProgressDocument): string {
       ? `记忆整理：待处理 ${document.generation.summary.pending} · 进行中 ${document.generation.summary.running} · 等待模型 ${document.generation.summary.waiting_for_model} · 失败 ${document.generation.summary.failed}`
       : "记忆整理：暂时无法读取",
   );
-  if (document.imports.output_truncated) {
+  if (
+    document.imports.output_truncated ||
+    document.generation.output_truncated
+  ) {
     lines.push("这里只显示汇总；完整记录请使用 --json。");
   }
   lines.push("");
@@ -331,6 +353,11 @@ export function unreadProgress(
     generation: {
       summary_state: failed,
       summary: null,
+      tasks_state: failed,
+      tasks: [],
+      returned: 0,
+      validated: 0,
+      output_truncated: false,
     },
   };
 }
@@ -341,11 +368,7 @@ function validated<T>(
 ):
   | { state: "ok"; data: T }
   | { state: Exclude<ReadState["state"], "ok">; code: string } {
-  if (outcome.state !== "ok") {
-    // A Core refusal of the request itself reads as an invalid answer here.
-    const state = outcome.state === "rejected" ? "invalid" : outcome.state;
-    return { state, code: outcome.code };
-  }
+  if (outcome.state !== "ok") return outcome;
   const data = validate(outcome.data);
   return data === null
     ? { state: "invalid", code: "response_invalid" }
@@ -442,3 +465,7 @@ function projectProcessing(
     })),
   };
 }
+
+function projectTask(task: ValidatedMemoryTask): Record<string, unknown> {
+  return { ...task };
+}

memhub/apps/cli/src/source-progress.test.ts

@@ -129,6 +129,18 @@ const RESPONSES = new Map<string, { status: number; data: unknown }>([
       },
     },
   ],
+  [
+    "/api/v1/memory-tasks",
+    {
+      status: 200,
+      data: [
+        memoryTask("task-pending", "pending"),
+        memoryTask("task-running", "running"),
+        memoryTask("task-model", "waiting_for_model", "model_missing"),
+        memoryTask("task-failed", "failed", "provider_unavailable"),
+      ],
+    },
+  ],
   [
     "/api/v1/import-jobs/job-running",
     { status: 200, data: importJob("job-running", "running") },
@@ -270,9 +282,9 @@ describe("CLI-19 progress and issue reads", () => {
       imported_messages: 20,
       totals_state: { state: "ok" },
     });
-    // The retired per-task list is no longer read or reported.
-    expect(report.generation).not.toHaveProperty("tasks");
-    expect(requestedPaths()).not.toContain("/api/v1/memory-tasks");
+    expect(
+      report.generation.tasks.map((task: { status: string }) => task.status),
+    ).toEqual(["pending", "running", "waiting_for_model", "failed"]);
     expect(streams.stdout()).not.toMatch(/percent|percentage|%/i);
   });
 
@@ -362,7 +374,7 @@ describe("CLI-19 progress and issue reads", () => {
     expect(streams.stdout()).not.toContain("SYNTHETIC_FOREIGN_ISSUE");
   });
 
-  it("bounds the import job list and emits an explicit truncation receipt", async () => {
+  it("bounds each task list and emits an explicit truncation receipt", async () => {
     const streams = captureStreams();
     try {
       expect(await run(["progress", "--limit", "1", "--json"], {})).toBe(1);
@@ -376,6 +388,12 @@ describe("CLI-19 progress and issue reads", () => {
       validated: 3,
       output_truncated: true,
     });
+    expect(report.generation.tasks).toHaveLength(1);
+    expect(report.generation).toMatchObject({
+      returned: 1,
+      validated: 4,
+      output_truncated: true,
+    });
   });
 
   it("streams bounded progress snapshots as serial NDJSON", async () => {
@@ -410,6 +428,7 @@ describe("CLI-19 progress and issue reads", () => {
       "/api/v1/import-jobs",
       "/api/v1/sources",
       "/api/v1/memory-processing",
+      "/api/v1/memory-tasks",
     ]) {
       expect(requestedPaths().filter((item) => item === path)).toHaveLength(2);
     }
@@ -481,7 +500,7 @@ describe("CLI-19 progress and issue reads", () => {
   it("preserves denied, unavailable and malformed sections in one partial report", async () => {
     transport.get.mockImplementation(async (url: string) => {
       if (url === "/api/v1/import-jobs") return { status: 503, data: {} };
-      if (url === "/api/v1/sources") return { status: 403, data: {} };
+      if (url === "/api/v1/memory-tasks") return { status: 403, data: {} };
       if (url === "/api/v1/memory-processing") {
         return { status: 200, data: { pending: { secret: "nested" } } };
       }
@@ -502,7 +521,7 @@ describe("CLI-19 progress and issue reads", () => {
       state: "invalid",
       code: "response_invalid",
     });
-    expect(report.imports.totals_state).toEqual({
+    expect(report.generation.tasks_state).toEqual({
       state: "denied",
       code: "http_403",
     });
@@ -555,6 +574,7 @@ describe("CLI-19 progress and issue reads", () => {
           "/api/v1/live-sync",
           "/api/v1/import-jobs",
           "/api/v1/memory-processing",
+          "/api/v1/memory-tasks",
         ].some((allowed) => path === allowed || path.startsWith(`${allowed}/`)),
       ),
     ).toBe(true);
@@ -614,6 +634,28 @@ function importJob(
   };
 }
 
+function memoryTask(
+  taskId: string,
+  status: string,
+  error: string | null = null,
+) {
+  return {
+    task_id: taskId,
+    request_id: `request-${taskId}`,
+    user_id: "local",
+    kind: "extract",
+    input_ref: "synthetic",
+    status,
+    profile_id: "profile-1",
+    profile_revision: 1,
+    profile_snapshot: {},
+    attempts: status === "failed" ? 2 : 0,
+    last_error_code: error,
+    created_at: "T1",
+    updated_at: "T2",
+  };
+}
+
 function requestedPaths(): string[] {
   return (transport.get.mock.calls as [string][]).map(([path]) => path);
 }

memhub/apps/cli/src/status-report.test.ts

@@ -1,11 +1,6 @@
 import { describe, expect, it } from "vitest";
 
-import { composeDoctorReport, renderDoctorText } from "./doctor-report.js";
-import {
-  composeStatusReport,
-  renderStatusText,
-  type StatusDocument,
-} from "./status-report.js";
+import { renderStatusText, type StatusDocument } from "./status-report.js";
 
 describe("status default output", () => {
   it("formats blocked task objects recursively instead of printing object coercions", () => {
@@ -40,40 +35,3 @@ describe("status default output", () => {
     );
   });
 });
-
-describe("status and doctor on an unfinished upgrade migration", () => {
-  it("names the migration log and the issues page", async () => {
-    const report = await composeStatusReport({
-      dataDir: "/tmp/isolated/.one-memory",
-      runtime: { state: "stopped", code: "sdk_migration_required" },
-      background: null,
-      reader: null,
-    });
-
-    expect(report.runtime.log_file).toBe(
-      "/tmp/isolated/.one-memory/logs/sdk-migration.log",
-    );
-    expect(report.runtime.issues_url).toBe(
-      "https://github.com/Tencent-Hunyuan/Hy-Memory/issues/new",
-    );
-    const text = renderStatusText(report, "MemHub");
-    expect(text).toContain("sdk_migration_required");
-    expect(text).toContain("/tmp/isolated/.one-memory/logs/sdk-migration.log");
-
-    const doctor = renderDoctorText(composeDoctorReport(report, null));
-    expect(doctor).toContain(
-      "/tmp/isolated/.one-memory/logs/sdk-migration.log",
-    );
-    expect(doctor).not.toContain("帮助与诊断");
-  });
-
-  it("adds no log path for an ordinary stopped runtime", async () => {
-    const report = await composeStatusReport({
-      dataDir: "/tmp/isolated/.one-memory",
-      runtime: { state: "stopped", code: "runtime_not_running" },
-      background: null,
-      reader: null,
-    });
-    expect(report.runtime.log_file).toBeUndefined();
-  });
-});

memhub/apps/cli/src/status-report.ts

@@ -1,4 +1,5 @@
 import type {
+  HomeSummary,
   LiveSyncHealth,
   MemoryProcessingSummary,
   ModelProfile,
@@ -8,10 +9,8 @@ import type {
   BackgroundHealth,
   RuntimeStatus,
 } from "@one-memory/runtime-control";
-import { sdkMigrationLogPath } from "@one-memory/runtime-control";
 import type { CoreReader, ReadOutcome } from "./core-client.js";
 import {
-  type SdkHomeSummary,
   validateHomeSummary,
   validateLiveSync,
   validateModelProfiles,
@@ -20,9 +19,6 @@ import {
 } from "./core-responses.js";
 import { PRODUCT } from "./version.js";
 
-const MIGRATION_ISSUES_URL =
-  "https://github.com/Tencent-Hunyuan/Hy-Memory/issues/new";
-
 export type SectionState =
   | "ok"
   | "denied"
@@ -46,9 +42,6 @@ export interface StatusDocument {
     host?: string;
     port?: number;
     version?: string;
-    /** Set only when an unfinished upgrade migration is why nothing serves. */
-    log_file?: string;
-    issues_url?: string;
   };
   bridge: {
     state: BackgroundHealth["state"] | "not_checked";
@@ -109,7 +102,7 @@ export async function composeStatusReport(options: {
       reader<unknown>("/api/v1/live-sync"),
       reader<unknown>("/api/v1/memory-processing"),
       reader<unknown>("/api/v1/model-profiles"),
-      reader<unknown>("/api/v2/home-summary"),
+      reader<unknown>("/api/v1/home-summary"),
     ]);
     sections.sources = section(sources, validateSources, describeSources);
     sections.sync = section(sync, validateLiveSync, describeSync);
@@ -160,12 +153,6 @@ export async function composeStatusReport(options: {
       host: options.runtime.host,
       port: options.runtime.port,
       version: options.runtime.version,
-      ...(options.runtime.code.startsWith("sdk_migration_")
-        ? {
-            log_file: sdkMigrationLogPath(options.dataDir),
-            issues_url: MIGRATION_ISSUES_URL,
-          }
-        : {}),
     },
     bridge,
     sections,
@@ -190,13 +177,6 @@ export function renderStatusText(
 ): string {
   const lines = [
     `${heading}：${runtimeLine(report)}`,
-    ...(report.runtime.log_file
-      ? [
-          `升级迁移没有完成（错误码：${report.runtime.code}），MemHub 不会启动。`,
-          `请把迁移日志附在 GitHub 反馈里发给我们：${report.runtime.log_file}`,
-          `反馈地址：${report.runtime.issues_url}`,
-        ]
-      : []),
     `资料空间：${report.data_dir}`,
     `应用连接：${BRIDGE_LABELS[report.bridge.state]}`,
   ];
@@ -367,7 +347,7 @@ function describeModel(profiles: ModelProfile[]): Record<string, unknown> {
   };
 }
 
-function describeMemories(summary: SdkHomeSummary): Record<string, unknown> {
+function describeMemories(summary: HomeSummary): Record<string, unknown> {
   return {
     memory_count: summary.memory_count,
   };

memhub/apps/cli/src/ui-session.ts

@@ -102,10 +102,6 @@ export function uiSessionFailure(code: string): { code: string } {
 
 export function uiExitCode(result: UiResult): number {
   if (result.state === "opened") return 0;
-  // A stopped Runtime is the same exit 3 every other command reports.
-  if (result.state === "blocked" && result.code === "runtime_not_running") {
-    return 3;
-  }
   if (result.state === "blocked") return 4;
   return 1;
 }

memhub/apps/cli/src/ui-write-cli.test.ts

@@ -0,0 +1,479 @@
+import { mkdtemp, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import path from "node:path";
+import { beforeEach, describe, expect, it, vi } from "vitest";
+
+import { run } from "./cli.js";
+
+const transport = vi.hoisted(() => ({
+  get: vi.fn(),
+  post: vi.fn(),
+  put: vi.fn(),
+  patch: vi.fn(),
+  delete: vi.fn(),
+}));
+vi.mock("axios", () => ({
+  default: { create: vi.fn(() => transport), get: vi.fn() },
+}));
+
+const runtime = vi.hoisted(() => ({
+  inspectRuntimeStatus: vi.fn(),
+  discoverRuntimeAttachment: vi.fn(),
+}));
+vi.mock("@one-memory/runtime-control", async (importOriginal) => ({
+  ...(await importOriginal<typeof import("@one-memory/runtime-control")>()),
+  ...runtime,
+}));
+
+const EVENT = "11111111-1111-4111-8111-111111111111";
+const UPLOAD = "22222222-2222-4222-8222-222222222222";
+const NOTE = "33333333-3333-4333-8333-333333333333";
+
+beforeEach(() => {
+  vi.clearAllMocks();
+  // clearAllMocks keeps prior mock implementations, so a mockResolvedValue
+  // from an earlier test would leak into the next one and fake its response.
+  transport.get.mockReset();
+  transport.post.mockReset();
+  transport.put.mockReset();
+  transport.patch.mockReset();
+  transport.delete.mockReset();
+  runtime.inspectRuntimeStatus.mockResolvedValue({
+    state: "running",
+    code: "runtime_verified",
+    instanceId: "instance-1",
+    host: "127.0.0.1",
+    port: 8765,
+    version: "1.2.3",
+  });
+  runtime.discoverRuntimeAttachment.mockResolvedValue({
+    instanceId: "instance-1",
+    apiToken: "synthetic-runtime-token",
+    host: "127.0.0.1",
+    port: 8765,
+    servicePid: 4242,
+    health: {
+      status: "ok",
+      service: "one-memory-core",
+      version: "1.2.3",
+      instance_id: "instance-1",
+    },
+  });
+});
+
+describe("calls clear", () => {
+  it("reports runtime_stopped (exit 3) without attempting a write", async () => {
+    runtime.inspectRuntimeStatus.mockResolvedValue({
+      state: "stopped",
+      code: "runtime_not_running",
+    });
+    const result = await capturedRun([
+      "calls",
+      "clear",
+      "--all",
+      "--confirm",
+      "--json",
+    ]);
+    expect(result.code).toBe(3);
+    expect(JSON.parse(result.stdout).code).toBe("runtime_not_running");
+    expect(transport.post).not.toHaveBeenCalled();
+  });
+
+  it("previews without contacting Core", async () => {
+    const result = await capturedRun([
+      "calls",
+      "clear",
+      "--event",
+      EVENT,
+      "--json",
+    ]);
+    expect(result.code).toBe(0);
+    const document = JSON.parse(result.stdout);
+    expect(document.state).toBe("preview");
+    expect(document.plan.kind).toBe("call_events_clear");
+    expect(transport.post).not.toHaveBeenCalled();
+    expect(transport.delete).not.toHaveBeenCalled();
+  });
+
+  it("sends the exact Core body with --confirm", async () => {
+    transport.post.mockResolvedValue({ status: 200, data: { removed: 1 } });
+    const result = await capturedRun([
+      "calls",
+      "clear",
+      "--event",
+      EVENT,
+      "--confirm",
+      "--json",
+    ]);
+    expect(result.code).toBe(0);
+    expect(transport.post).toHaveBeenCalledWith(
+      "/api/v1/call-events/clear",
+      { event_ids: [EVENT], user_confirmed: true },
+      undefined,
+    );
+    expect(JSON.parse(result.stdout).state).toBe("committed");
+  });
+
+  it("clears all without naming events", async () => {
+    transport.post.mockResolvedValue({ status: 200, data: { removed: 4 } });
+    const result = await capturedRun([
+      "calls",
+      "clear",
+      "--all",
+      "--confirm",
+      "--json",
+    ]);
+    expect(result.code).toBe(0);
+    expect(transport.post).toHaveBeenCalledWith(
+      "/api/v1/call-events/clear-all",
+      { user_confirmed: true },
+      undefined,
+    );
+  });
+
+  it("rejects a malformed event id without contacting Core", async () => {
+    const result = await capturedRun([
+      "calls",
+      "clear",
+      "--event",
+      "not-a-uuid",
+      "--json",
+    ]);
+    expect(result.code).toBe(2);
+    expect(transport.post).not.toHaveBeenCalled();
+  });
+
+  it("never reports committed for a malformed success body", async () => {
+    transport.post.mockResolvedValue({ status: 200, data: { wrong: true } });
+    const result = await capturedRun([
+      "calls",
+      "clear",
+      "--event",
+      EVENT,
+      "--confirm",
+      "--json",
+    ]);
+    expect(result.code).toBe(1);
+    const document = JSON.parse(result.stdout);
+    expect(document.state).toBe("unknown");
+    expect(document.code).toBe("ui_write_receipt_invalid");
+  });
+});
+
+describe("import-file", () => {
+  it("never uploads without --confirm", async () => {
+    const directory = await mkdtemp(path.join(tmpdir(), "om-import-"));
+    const file = path.join(directory, "export.json");
+    await writeFile(file, '{"conversations":[]}', { mode: 0o600 });
+    const result = await capturedRun([
+      "import-file",
+      "upload",
+      "--file",
+      file,
+      "--json",
+    ]);
+    expect(result.code).toBe(0);
+    const document = JSON.parse(result.stdout);
+    expect(document.state).toBe("preview");
+    expect(document.plan.operation_id).toBeDefined();
+    expect(transport.post).not.toHaveBeenCalled();
+  });
+
+  it("uploads the file with a deterministic operation id on confirm", async () => {
+    const directory = await mkdtemp(path.join(tmpdir(), "om-import-"));
+    const file = path.join(directory, "export.json");
+    await writeFile(file, '{"conversations":[]}', { mode: 0o600 });
+    transport.post.mockResolvedValue({
+      status: 201,
+      data: {
+        schema_version: 1,
+        operation_id: "ignored-here",
+        state: "completed",
+        upload_id: UPLOAD,
+        upload_state: "staged",
+      },
+    });
+    const preview = await capturedRun([
+      "import-file",
+      "upload",
+      "--file",
+      file,
+      "--json",
+    ]);
+    const plan = JSON.parse(preview.stdout).plan;
+    transport.post.mockResolvedValue({
+      status: 201,
+      data: {
+        schema_version: 1,
+        operation_id: plan.operation_id,
+        state: "completed",
+        upload_id: UPLOAD,
+        upload_state: "staged",
+      },
+    });
+    const result = await capturedRun([
+      "import-file",
+      "upload",
+      "--file",
+      file,
+      "--confirm",
+      "--json",
+    ]);
+    expect(result.code).toBe(0);
+    const url = transport.post.mock.calls.at(-1)?.[0] as string;
+    expect(url).toContain("/api/v1/import-files?");
+    expect(url).toContain(`operation_id=${plan.operation_id}`);
+    expect(url).toContain("filename=export.json");
+    expect(JSON.parse(result.stdout).state).toBe("committed");
+  });
+
+  it("commits and discards only with explicit confirmation", async () => {
+    const preview = await capturedRun([
+      "import-file",
+      "commit",
+      UPLOAD,
+      "--json",
+    ]);
+    expect(preview.code).toBe(0);
+    expect(JSON.parse(preview.stdout).state).toBe("preview");
+    expect(transport.post).not.toHaveBeenCalled();
+
+    transport.post.mockResolvedValue({
+      status: 200,
+      data: {
+        upload_id: UPLOAD,
+        filename: "x.json",
+        vendor: "generic",
+        source_id: "generic-export",
+        messages: 0,
+        conversations: 0,
+        human_messages: 0,
+        agent_messages: 0,
+        skipped_records: 0,
+        ignored_files: 0,
+        checksum: "a".repeat(64),
+        created_at: "T",
+        committed: true,
+      },
+    });
+    const committed = await capturedRun([
+      "import-file",
+      "commit",
+      UPLOAD,
+      "--confirm",
+      "--json",
+    ]);
+    expect(committed.code).toBe(0);
+    expect(transport.post).toHaveBeenCalledWith(
+      `/api/v1/import-files/${UPLOAD}/commit`,
+      { confirmed: true },
+      undefined,
+    );
+
+    transport.delete.mockResolvedValue({ status: 204, data: "" });
+    const discarded = await capturedRun([
+      "import-file",
+      "discard",
+      UPLOAD,
+      "--confirm",
+      "--json",
+    ]);
+    expect(discarded.code).toBe(0);
+    expect(JSON.parse(discarded.stdout).state).toBe("committed");
+    expect(transport.delete).toHaveBeenCalledWith(
+      `/api/v1/import-files/${UPLOAD}`,
+      undefined,
+    );
+  });
+
+  it("maps a Core 404 to a stable rejected code, not a fake success", async () => {
+    transport.post.mockResolvedValue({
+      status: 404,
+      data: { detail: "import_file_not_found" },
+    });
+    const result = await capturedRun([
+      "import-file",
+      "commit",
+      UPLOAD,
+      "--confirm",
+      "--json",
+    ]);
+    expect(result.code).toBe(1);
+    const document = JSON.parse(result.stdout);
+    expect(document.state).toBe("rejected");
+    expect(document.code).toBe("import_file_not_found");
+  });
+});
+
+describe("notes / extraction / graph / manual extract", () => {
+  it("adds a note from a bounded file and re-verifies content on apply", async () => {
+    const directory = await mkdtemp(path.join(tmpdir(), "om-note-"));
+    const content = path.join(directory, "note.txt");
+    await writeFile(content, "记住这个决定", { mode: 0o600 });
+    const preview = await capturedRun([
+      "notes",
+      "add",
+      "--content-file",
+      content,
+      "--json",
+    ]);
+    expect(preview.code).toBe(0);
+    const planFile = path.join(directory, "plan.json");
+    await writeFile(planFile, preview.stdout, { mode: 0o600 });
+    transport.post.mockResolvedValue({
+      status: 201,
+      // A realistic Core `MemoryNoteReceipt`: the shared parser requires
+      // `scope` and `memory_ids` too, so a minimal `{evidence_id,state}` stub
+      // is a malformed body, not a success.
+      data: {
+        evidence_id: NOTE,
+        text: "记住这个决定",
+        scope: "all-apps",
+        created_at: "2026-09-19T00:00:00Z",
+        state: "pending",
+        task_id: null,
+        memory_ids: [],
+        error: null,
+      },
+    });
+    const applied = await capturedRun([
+      "notes",
+      "apply",
+      "--plan-file",
+      planFile,
+      "--content-file",
+      content,
+      "--confirm",
+      "--json",
+    ]);
+    expect(applied.code).toBe(0);
+    const body = transport.post.mock.calls.at(-1)?.[1] as Record<
+      string,
+      unknown
+    >;
+    expect(body.text).toBe("记住这个决定");
+    expect(body.scope).toBe("all-apps");
+    expect(JSON.parse(applied.stdout).state).toBe("committed");
+  });
+
+  it("plans then applies the extraction window", async () => {
+    const preview = await capturedRun([
+      "extraction",
+      "set",
+      "--window",
+      "6m",
+      "--json",
+    ]);
+    expect(preview.code).toBe(0);
+    expect(JSON.parse(preview.stdout).state).toBe("preview");
+    expect(transport.put).not.toHaveBeenCalled();
+    transport.put.mockResolvedValue({
+      status: 200,
+      data: { window_preset: "6m" },
+    });
+    const applied = await capturedRun([
+      "extraction",
+      "set",
+      "--window",
+      "6m",
+      "--confirm",
+      "--json",
+    ]);
+    expect(applied.code).toBe(0);
+    expect(transport.put).toHaveBeenCalledWith(
+      "/api/v1/extraction-settings",
+      { window_preset: "6m" },
+      undefined,
+    );
+  });
+
+  it("does not call graph width without --confirm", async () => {
+    const preview = await capturedRun([
+      "graph",
+      "width",
+      "--decision",
+      "rebuild_with_new",
+      "--json",
+    ]);
+    expect(preview.code).toBe(0);
+    expect(transport.post).not.toHaveBeenCalled();
+    transport.post.mockResolvedValue({
+      status: 200,
+      data: { archived_path: "/tmp/old", exported_path: null, mismatch: null },
+    });
+    const applied = await capturedRun([
+      "graph",
+      "width",
+      "--decision",
+      "rebuild_with_new",
+      "--confirm",
+      "--json",
+    ]);
+    expect(applied.code).toBe(0);
+    expect(transport.post).toHaveBeenCalledWith(
+      "/api/v1/graph-width",
+      { decision: "rebuild_with_new" },
+      undefined,
+    );
+  });
+
+  it("plans manual extraction and applies it only on confirm", async () => {
+    const preview = await capturedRun([
+      "processing",
+      "extract",
+      "--evidence",
+      NOTE,
+      "--json",
+    ]);
+    expect(preview.code).toBe(0);
+    expect(JSON.parse(preview.stdout).state).toBe("preview");
+    expect(transport.post).not.toHaveBeenCalled();
+    transport.post.mockResolvedValue({
+      status: 200,
+      data: { promoted: 1, batches_planned: 2, batches_current: 1 },
+    });
+    const applied = await capturedRun([
+      "processing",
+      "extract",
+      "--evidence",
+      NOTE,
+      "--confirm",
+      "--json",
+    ]);
+    expect(applied.code).toBe(0);
+    expect(transport.post).toHaveBeenCalledWith(
+      "/api/v1/memory-processing/manual-extract",
+      { evidence_ids: [NOTE] },
+      undefined,
+    );
+  });
+});
+
+async function capturedRun(arguments_: string[]) {
+  let stdout = "";
+  let stderr = "";
+  const stdoutSpy = vi
+    .spyOn(process.stdout, "write")
+    .mockImplementation((chunk) => {
+      stdout += String(chunk);
+      return true;
+    });
+  const stderrSpy = vi
+    .spyOn(process.stderr, "write")
+    .mockImplementation((chunk) => {
+      stderr += String(chunk);
+      return true;
+    });
+  try {
+    return {
+      code: await run(arguments_, {
+        ONE_MEMORY_DATA_DIR: "/synthetic/data",
+      }),
+      stdout,
+      stderr,
+    };
+  } finally {
+    stdoutSpy.mockRestore();
+    stderrSpy.mockRestore();
+  }
+}

memhub/apps/cli/src/ui-write-flows-extended.ts

@@ -0,0 +1,501 @@
+/**
+ * The remaining Web Console mutating operations the CLI did not expose:
+ * 端内新增记忆 (memory-notes), extraction window, graph width, and manual
+ * extraction.
+ *
+ * Core owns every rule; this module only validates the input it is about to
+ * send, performs one explicit two-phase write, and normalises the receipt so
+ * the CLI never reports a write as committed without evidence.
+ */
+
+import { createHash, randomUUID } from "node:crypto";
+import {
+  buildMemoryNoteSaveRequest,
+  MemoryNoteInputError,
+  parseExtractionSettingsReceipt,
+  parseGraphWidthDecisionReceipt,
+  parseManualExtractReceipt,
+  parseMemoryNoteReceipt,
+} from "@one-memory/operations";
+import type { CoreOperations, CorePutOperations } from "./core-operations.js";
+import { PRODUCT } from "./version.js";
+
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/;
+const DIGEST = /^[0-9a-f]{64}$/;
+const NOTE_MAX_CHARACTERS = 12_000;
+const EXTRACTION_PRESETS = ["3m", "6m", "1y", "all"] as const;
+const GRAPH_DECISIONS = [
+  "keep_existing",
+  "rebuild_with_new",
+  "export_first",
+] as const;
+const NOTE_STATES = [
+  "waiting_for_model",
+  "waiting_for_permission",
+  "pending",
+  "running",
+  "failed",
+  "ready",
+  "no_memories",
+] as const;
+
+export type NoteState = (typeof NOTE_STATES)[number];
+
+export type ExtendedWritePlan =
+  | {
+      schema_version: 1;
+      kind: "memory_note_add";
+      request_id: string;
+      content_sha256: string;
+      content_characters: number;
+      digest: string;
+    }
+  | {
+      schema_version: 1;
+      kind: "memory_note_process";
+      evidence_id: string;
+      digest: string;
+    }
+  | {
+      schema_version: 1;
+      kind: "extraction_window_set";
+      window_preset: (typeof EXTRACTION_PRESETS)[number];
+      digest: string;
+    }
+  | {
+      schema_version: 1;
+      kind: "graph_width_decide";
+      decision: (typeof GRAPH_DECISIONS)[number];
+      digest: string;
+    }
+  | {
+      schema_version: 1;
+      kind: "manual_extract";
+      evidence_ids: string[];
+      digest: string;
+    };
+
+export type ExtendedWriteOutcome =
+  | {
+      schema_version: 1;
+      product: string;
+      state: "preview";
+      plan: ExtendedWritePlan;
+    }
+  | {
+      schema_version: 1;
+      product: string;
+      state: "committed" | "recovered";
+      operation_id: string;
+      receipt: Record<string, unknown>;
+    }
+  | {
+      schema_version: 1;
+      product: string;
+      state: "rejected" | "unknown" | "invalid";
+      operation_id?: string;
+      code: string;
+    };
+
+function canonical(value: unknown): string {
+  if (Array.isArray(value)) return `[${value.map(canonical).join(",")}]`;
+  if (value !== null && typeof value === "object") {
+    return `{${Object.entries(value as Record<string, unknown>)
+      .sort(([left], [right]) => left.localeCompare(right))
+      .map(([key, item]) => `${JSON.stringify(key)}:${canonical(item)}`)
+      .join(",")}}`;
+  }
+  if (value === undefined) return "null";
+  return JSON.stringify(value);
+}
+
+function digestOf(value: unknown): string {
+  return createHash("sha256").update(canonical(value)).digest("hex");
+}
+
+type Draft =
+  | Omit<Extract<ExtendedWritePlan, { kind: "memory_note_add" }>, "digest">
+  | Omit<Extract<ExtendedWritePlan, { kind: "memory_note_process" }>, "digest">
+  | Omit<
+      Extract<ExtendedWritePlan, { kind: "extraction_window_set" }>,
+      "digest"
+    >
+  | Omit<Extract<ExtendedWritePlan, { kind: "graph_width_decide" }>, "digest">
+  | Omit<Extract<ExtendedWritePlan, { kind: "manual_extract" }>, "digest">;
+
+function preview(plan: Draft): ExtendedWriteOutcome {
+  return {
+    schema_version: 1,
+    product: PRODUCT,
+    state: "preview",
+    plan: { ...plan, digest: digestOf(plan) } as ExtendedWritePlan,
+  };
+}
+
+function invalid(code: string): ExtendedWriteOutcome {
+  return { schema_version: 1, product: PRODUCT, state: "invalid", code };
+}
+
+function committed(
+  operationId: string,
+  receipt: Record<string, unknown>,
+  state: "committed" | "recovered" = "committed",
+): ExtendedWriteOutcome {
+  return {
+    schema_version: 1,
+    product: PRODUCT,
+    state,
+    operation_id: operationId,
+    receipt,
+  };
+}
+
+function rejected(
+  operationId: string | undefined,
+  code: string,
+): ExtendedWriteOutcome {
+  return {
+    schema_version: 1,
+    product: PRODUCT,
+    state: "rejected",
+    ...(operationId === undefined ? {} : { operation_id: operationId }),
+    code,
+  };
+}
+
+function unknown(
+  operationId: string | undefined,
+  code: string,
+): ExtendedWriteOutcome {
+  return {
+    schema_version: 1,
+    product: PRODUCT,
+    state: "unknown",
+    ...(operationId === undefined ? {} : { operation_id: operationId }),
+    code,
+  };
+}
+
+// --- memory-notes ---------------------------------------------------------
+
+export function planMemoryNoteAdd(text: string): ExtendedWriteOutcome {
+  // The plan keeps only the note's identity, like `memories plan add`: the
+  //正文 lives in a bounded file and is re-read and re-hashed at apply time, so
+  // a plan file never carries the user's private text.
+  if (!validNoteText(text)) return invalid("memory_note_text_invalid");
+  const requestId = randomUUID();
+  return preview({
+    schema_version: 1,
+    kind: "memory_note_add",
+    request_id: requestId,
+    content_sha256: createHash("sha256").update(text, "utf8").digest("hex"),
+    content_characters: [...text].length,
+  });
+}
+
+export function validNoteText(text: string): boolean {
+  return (
+    text.length > 0 &&
+    [...text].length <= NOTE_MAX_CHARACTERS &&
+    text.trim().length > 0 &&
+    ![...text].some((character) => {
+      const code = character.charCodeAt(0);
+      return code <= 8 || (code >= 11 && code <= 31) || code === 127;
+    })
+  );
+}
+
+export function planMemoryNoteProcess(
+  evidenceId: string,
+): ExtendedWriteOutcome {
+  return UUID.test(evidenceId)
+    ? preview({
+        schema_version: 1,
+        kind: "memory_note_process",
+        evidence_id: evidenceId,
+      })
+    : invalid("memory_note_id_invalid");
+}
+
+function noteReceipt(
+  operationId: string,
+  data: { evidence_id: string; state: NoteState },
+): ExtendedWriteOutcome {
+  return committed(operationId, { ...data });
+}
+
+export async function executeMemoryNoteAdd(
+  plan: Extract<ExtendedWritePlan, { kind: "memory_note_add" }>,
+  operations: CoreOperations,
+  text: string,
+): Promise<ExtendedWriteOutcome> {
+  if (
+    !validNoteText(text) ||
+    createHash("sha256").update(text, "utf8").digest("hex") !==
+      plan.content_sha256 ||
+    [...text].length !== plan.content_characters
+  ) {
+    return invalid("memory_note_content_mismatch");
+  }
+  // The shared builder owns the save body (request_id/text/scope=all-apps), so
+  // the CLI and the Web console post the same three fields. Its own text check
+  // already ran above, so a throw here means an unusable plan.
+  let request: ReturnType<typeof buildMemoryNoteSaveRequest>;
+  try {
+    request = buildMemoryNoteSaveRequest({
+      request_id: plan.request_id,
+      text,
+      scope: "all-apps",
+    } as Parameters<typeof buildMemoryNoteSaveRequest>[0]);
+  } catch (error) {
+    if (error instanceof MemoryNoteInputError) {
+      return invalid("memory_note_content_mismatch");
+    }
+    throw error;
+  }
+  const result = await operations.post<unknown>(request.path, request.body);
+  if (result.state === "rejected") {
+    return rejected(plan.request_id, result.code);
+  }
+  if (result.state === "unknown") {
+    return unknown(plan.request_id, result.code);
+  }
+  const receipt = asNoteReceipt(result.data);
+  return receipt === null
+    ? unknown(plan.request_id, "ui_write_receipt_invalid")
+    : noteReceipt(plan.request_id, receipt);
+}
+
+export async function executeMemoryNoteProcess(
+  plan: Extract<ExtendedWritePlan, { kind: "memory_note_process" }>,
+  operations: CoreOperations,
+): Promise<ExtendedWriteOutcome> {
+  const result = await operations.post<unknown>(
+    `/api/v1/memory-notes/${plan.evidence_id}/process`,
+    {},
+  );
+  if (result.state === "rejected") {
+    return rejected(plan.evidence_id, result.code);
+  }
+  if (result.state === "unknown") {
+    return unknown(plan.evidence_id, result.code);
+  }
+  const receipt = asNoteReceipt(result.data);
+  return receipt === null
+    ? unknown(plan.evidence_id, "ui_write_receipt_invalid")
+    : noteReceipt(plan.evidence_id, receipt);
+}
+
+function asNoteReceipt(
+  value: unknown,
+): { evidence_id: string; state: NoteState } | null {
+  // The shared parser is the single judge of a note receipt; a malformed body
+  // returns null and the caller reports `unknown`, never a saved note.
+  const receipt = parseMemoryNoteReceipt(value);
+  return receipt === null
+    ? null
+    : { evidence_id: receipt.evidence_id, state: receipt.state as NoteState };
+}
+
+// --- extraction window / graph width / manual extract ---------------------
+
+export function planExtractionWindowSet(
+  windowPreset: string,
+): ExtendedWriteOutcome {
+  return (EXTRACTION_PRESETS as readonly string[]).includes(windowPreset)
+    ? preview({
+        schema_version: 1,
+        kind: "extraction_window_set",
+        window_preset: windowPreset as (typeof EXTRACTION_PRESETS)[number],
+      })
+    : invalid("extraction_window_preset_invalid");
+}
+
+export function planGraphWidthDecide(decision: string): ExtendedWriteOutcome {
+  return (GRAPH_DECISIONS as readonly string[]).includes(decision)
+    ? preview({
+        schema_version: 1,
+        kind: "graph_width_decide",
+        decision: decision as (typeof GRAPH_DECISIONS)[number],
+      })
+    : invalid("graph_width_decision_invalid");
+}
+
+export function planManualExtract(evidenceIds: string[]): ExtendedWriteOutcome {
+  const ids = [...new Set(evidenceIds)];
+  return ids.length === evidenceIds.length && ids.every((id) => UUID.test(id))
+    ? preview({
+        schema_version: 1,
+        kind: "manual_extract",
+        evidence_ids: ids,
+      })
+    : invalid("manual_extract_evidence_ids_invalid");
+}
+
+export async function executeExtractionWindowSet(
+  plan: Extract<ExtendedWritePlan, { kind: "extraction_window_set" }>,
+  operations: CorePutOperations,
+): Promise<ExtendedWriteOutcome> {
+  const result = await operations.put<unknown>("/api/v1/extraction-settings", {
+    window_preset: plan.window_preset,
+  });
+  if (result.state === "rejected") {
+    return rejected(plan.window_preset, result.code);
+  }
+  if (result.state === "unknown") {
+    return unknown(plan.window_preset, result.code);
+  }
+  // The shared parser also enforces that the receipt echoes the requested
+  // preset, so a response belonging to another write cannot pass.
+  const parsed = parseExtractionSettingsReceipt(
+    result.data,
+    plan.window_preset,
+  );
+  if (parsed === null) {
+    return unknown(plan.window_preset, "ui_write_receipt_invalid");
+  }
+  return committed(plan.window_preset, { window_preset: plan.window_preset });
+}
+
+export async function executeGraphWidthDecide(
+  plan: Extract<ExtendedWritePlan, { kind: "graph_width_decide" }>,
+  operations: CoreOperations,
+): Promise<ExtendedWriteOutcome> {
+  const result = await operations.post<unknown>("/api/v1/graph-width", {
+    decision: plan.decision,
+  });
+  if (result.state === "rejected") {
+    return rejected(plan.decision, result.code);
+  }
+  if (result.state === "unknown") {
+    return unknown(plan.decision, result.code);
+  }
+  const receipt = parseGraphWidthDecisionReceipt(result.data);
+  if (receipt === null) {
+    return unknown(plan.decision, "ui_write_receipt_invalid");
+  }
+  return committed(plan.decision, {
+    archived_path: receipt.archived_path ?? null,
+    exported_path: receipt.exported_path ?? null,
+    mismatch: receipt.mismatch ?? null,
+  });
+}
+
+export async function executeManualExtract(
+  plan: Extract<ExtendedWritePlan, { kind: "manual_extract" }>,
+  operations: CoreOperations,
+): Promise<ExtendedWriteOutcome> {
+  const result = await operations.post<unknown>(
+    "/api/v1/memory-processing/manual-extract",
+    { evidence_ids: plan.evidence_ids },
+  );
+  if (result.state === "rejected") {
+    return rejected("manual_extract", result.code);
+  }
+  if (result.state === "unknown") {
+    return unknown("manual_extract", result.code);
+  }
+  const receipt = parseManualExtractReceipt(result.data);
+  if (receipt === null) {
+    return unknown("manual_extract", "ui_write_receipt_invalid");
+  }
+  return committed("manual_extract", {
+    promoted: receipt.promoted,
+    batches_planned: receipt.batches_planned,
+    batches_current: receipt.batches_current,
+  });
+}
+
+export function validateExtendedWritePlan(
+  value: unknown,
+): ExtendedWritePlan | null {
+  if (value === null || typeof value !== "object" || Array.isArray(value)) {
+    return null;
+  }
+  const candidate = value as Record<string, unknown>;
+  if (candidate.schema_version !== 1 || typeof candidate.kind !== "string") {
+    return null;
+  }
+  const { digest, ...withoutDigest } = candidate;
+  if (typeof digest !== "string" || digest !== digestOf(withoutDigest)) {
+    return null;
+  }
+  switch (candidate.kind) {
+    case "memory_note_add":
+      return typeof candidate.request_id === "string" &&
+        UUID.test(candidate.request_id) &&
+        typeof candidate.content_sha256 === "string" &&
+        DIGEST.test(candidate.content_sha256) &&
+        Number.isSafeInteger(candidate.content_characters) &&
+        (candidate.content_characters as number) >= 1 &&
+        (candidate.content_characters as number) <= NOTE_MAX_CHARACTERS &&
+        Object.keys(candidate).length === 6
+        ? (candidate as unknown as ExtendedWritePlan)
+        : null;
+    case "memory_note_process":
+      return typeof candidate.evidence_id === "string" &&
+        UUID.test(candidate.evidence_id) &&
+        Object.keys(candidate).length === 4
+        ? (candidate as unknown as ExtendedWritePlan)
+        : null;
+    case "extraction_window_set":
+      return (EXTRACTION_PRESETS as readonly string[]).includes(
+        String(candidate.window_preset),
+      ) && Object.keys(candidate).length === 4
+        ? (candidate as unknown as ExtendedWritePlan)
+        : null;
+    case "graph_width_decide":
+      return (GRAPH_DECISIONS as readonly string[]).includes(
+        String(candidate.decision),
+      ) && Object.keys(candidate).length === 4
+        ? (candidate as unknown as ExtendedWritePlan)
+        : null;
+    case "manual_extract":
+      return Array.isArray(candidate.evidence_ids) &&
+        candidate.evidence_ids.every(
+          (id) => typeof id === "string" && UUID.test(id),
+        ) &&
+        Object.keys(candidate).length === 4
+        ? (candidate as unknown as ExtendedWritePlan)
+        : null;
+    default:
+      return null;
+  }
+}
+
+export function extendedWriteExitCode(document: ExtendedWriteOutcome): number {
+  return ["preview", "committed", "recovered"].includes(document.state) ? 0 : 1;
+}
+
+export function renderExtendedWriteText(
+  document: ExtendedWriteOutcome,
+): string {
+  if (document.state === "preview") {
+    const lines = ["以下操作尚未执行；加 --confirm 后才会写入："];
+    const plan = document.plan;
+    switch (plan.kind) {
+      case "memory_note_add":
+        lines.push(`新增端内记忆：${plan.content_characters} 字符`);
+        break;
+      case "memory_note_process":
+        lines.push(`处理端内记忆：${plan.evidence_id}`);
+        break;
+      case "extraction_window_set":
+        lines.push(`设置提取窗口：${plan.window_preset}`);
+        break;
+      case "graph_width_decide":
+        lines.push(`图谱宽度决定：${plan.decision}`);
+        break;
+      case "manual_extract":
+        lines.push(`手动提取：${plan.evidence_ids.length} 条证据`);
+        break;
+    }
+    lines.push(`plan_digest：${plan.digest}`);
+    return `${lines.join("\n")}\n`;
+  }
+  if (document.state === "committed" || document.state === "recovered") {
+    return `${document.state === "recovered" ? "已从回执恢复" : "已提交"}：${document.operation_id}\n${JSON.stringify(document.receipt)}\n`;
+  }
+  const code = "code" in document ? document.code : "ui_write_state_invalid";
+  return `操作未完成：${document.state}（${code}）\n`;
+}

memhub/apps/cli/src/ui-write-flows.test.ts

@@ -0,0 +1,144 @@
+import { describe, expect, it, vi } from "vitest";
+
+import type {
+  CoreDeleteOperations,
+  CoreOperations,
+} from "./core-operations.js";
+import {
+  executeCallEventsClear,
+  executeCallEventsClearAll,
+  executeImportFileCommit,
+  executeImportFileDiscard,
+  planCallEventsClear,
+  planCallEventsClearAll,
+  planImportFileCommit,
+  planImportFileDiscard,
+  planImportFileUpload,
+  validateUiWritePlan,
+} from "./ui-write-flows.js";
+
+const EVENT = "11111111-1111-4111-8111-111111111111";
+const UPLOAD = "22222222-2222-4222-8222-222222222222";
+
+function planOf(value: ReturnType<typeof planCallEventsClear>) {
+  if (value.state !== "preview") throw new Error("expected preview");
+  return value.plan;
+}
+
+describe("UI write plans", () => {
+  it("permits only valid call-event ids and rejects duplicates", () => {
+    expect(planCallEventsClear([EVENT]).state).toBe("preview");
+    expect(planCallEventsClear([]).state).toBe("invalid");
+    expect(planCallEventsClear([EVENT, EVENT]).state).toBe("invalid");
+  });
+
+  it("plans all remaining UI write operations", () => {
+    expect(planCallEventsClearAll().state).toBe("preview");
+    expect(planImportFileCommit(UPLOAD).state).toBe("preview");
+    expect(planImportFileDiscard(UPLOAD).state).toBe("preview");
+    expect(
+      planImportFileUpload({
+        path: "/tmp/export.json",
+        bytes: 42,
+        sha256: "a".repeat(64),
+        inputKind: "raw_conversation",
+      }).state,
+    ).toBe("preview");
+  });
+
+  it("rejects a tampered plan digest", async () => {
+    const plan = planOf(planCallEventsClear([EVENT]));
+    expect(validateUiWritePlan(plan)).toEqual(plan);
+    expect(validateUiWritePlan({ ...plan, event_ids: [UPLOAD] })).toBeNull();
+  });
+});
+
+describe("UI write execution", () => {
+  it("posts clear with Core's confirmation field", async () => {
+    const post = vi.fn(async () => ({
+      state: "committed" as const,
+      data: { removed: 1 },
+    }));
+    const plan = planOf(planCallEventsClear([EVENT]));
+    if (plan.kind !== "call_events_clear") throw new Error("kind");
+    const result = await executeCallEventsClear(plan, {
+      post,
+    } as unknown as CoreOperations);
+    expect(result.state).toBe("committed");
+    expect(post).toHaveBeenCalledWith("/api/v1/call-events/clear", {
+      event_ids: [EVENT],
+      user_confirmed: true,
+    });
+  });
+
+  it("posts clear-all with Core's confirmation field", async () => {
+    const post = vi.fn(async () => ({
+      state: "committed" as const,
+      data: { removed: 2 },
+    }));
+    const plan = planOf(planCallEventsClearAll());
+    if (plan.kind !== "call_events_clear_all") throw new Error("kind");
+    await executeCallEventsClearAll(plan, {
+      post,
+    } as unknown as CoreOperations);
+    expect(post).toHaveBeenCalledWith("/api/v1/call-events/clear-all", {
+      user_confirmed: true,
+    });
+  });
+
+  it("uses POST commit and DELETE discard endpoints", async () => {
+    const post = vi.fn(async () => ({
+      state: "committed" as const,
+      data: {
+        upload_id: UPLOAD,
+        filename: "x.json",
+        vendor: "generic",
+        source_id: "generic-export",
+        messages: 0,
+        conversations: 0,
+        human_messages: 0,
+        agent_messages: 0,
+        skipped_records: 0,
+        ignored_files: 0,
+        checksum: "a".repeat(64),
+        created_at: "T",
+        committed: true,
+      },
+    }));
+    const del = vi.fn(async <T>() => ({
+      state: "committed" as const,
+      data: {} as T,
+    }));
+    const operations = {
+      post,
+      delete: del,
+    } as unknown as CoreOperations & CoreDeleteOperations;
+    const commit = planOf(planImportFileCommit(UPLOAD));
+    if (commit.kind !== "import_file_commit") throw new Error("kind");
+    await executeImportFileCommit(commit, operations);
+    expect(post).toHaveBeenCalledWith(`/api/v1/import-files/${UPLOAD}/commit`, {
+      confirmed: true,
+    });
+    const discard = planOf(planImportFileDiscard(UPLOAD));
+    if (discard.kind !== "import_file_discard") throw new Error("kind");
+    expect((await executeImportFileDiscard(discard, operations)).state).toBe(
+      "committed",
+    );
+    expect(del).toHaveBeenCalledWith(`/api/v1/import-files/${UPLOAD}`);
+  });
+
+  it("treats a malformed success receipt as unknown", async () => {
+    const plan = planOf(planCallEventsClear([EVENT]));
+    if (plan.kind !== "call_events_clear") throw new Error("kind");
+    const result = await executeCallEventsClear(plan, {
+      post: vi.fn(async () => ({
+        state: "committed" as const,
+        data: { wrong: true },
+      })),
+    } as unknown as CoreOperations);
+    expect(result).toMatchObject({
+      state: "unknown",
+      code: "ui_write_receipt_invalid",
+    });
+  });
+});