Merge main into feat/sdk-trimmed-raw

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>

.env.example

@@ -40,6 +40,7 @@ MEMORY_EMBEDDING_DIMS=1024
 # MEMORY_EMBEDDER_TIMEOUT=15
 # MEMORY_EMBEDDER_MAX_RETRIES=2
 # MEMORY_EMBEDDER_RETRY_DELAY=0.3
+# MEMORY_EMBEDDER_BATCH_SIZE=64
 # MEMORY_EMBEDDER_EXTRA_HEADERS={}
 # MEMORY_EMBEDDER_EXTRA_BODY={}
 
@@ -86,6 +87,7 @@ MEMORY_VECTOR_STORE=chroma
 # MEMORY_CODING_DB_PATH=                        # coding_memory.db 路径（默认 {DATA_DIR}/data/coding_memory.db）
 # MEMORY_CODING_TOOL_RESULT_MAX_BYTES=2048      # 单条 tool_result 截断字节上限
 # MEMORY_CODING_VERBATIM_FALLBACK_ENABLED=false # 模型无结果时是否保存原文 fact；默认关，避免 tool trace 外泄
+# MEMORY_CODING_CHAIN_BLOCK_ENABLED=false       # search 是否注入版本演进链块（diff）；默认关，省 token
 # MEMORY_EXTRACT_HISTORY_TURNS=5                 # 除本次 write 外，额外注入 extractor 的历史 user-turn 数
 
 # ── 写入流程开关 ──

.github/workflows/hermes-provider.yml

@@ -0,0 +1,49 @@
+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

.github/workflows/linux-lifecycle.yml

@@ -122,19 +122,25 @@ jobs:
         shell: bash
         run: |
           set -euo pipefail
+          shopt -s globstar nullglob
           version=$(node -p 'require("./package.json").version')
           node scripts/verify-release-version.mjs \
             --channel stable \
             --version "$version" \
             --build-number "$(node -p 'require("./package.json").release.build_number')" \
             --tag "$GITHUB_REF_NAME"
+          mkdir -p publish-assets
           for arch in x64 arm64; do
-            archive="release-assets/memhub-runtime-v${version}-linux-${arch}.tar.gz"
-            test -f "$archive"
-            test -f "$archive.sha256"
+            name="memhub-runtime-v${version}-linux-${arch}.tar.gz"
+            archives=(release-assets/**/"$name")
+            checksums=(release-assets/**/"$name.sha256")
+            test "${#archives[@]}" -eq 1
+            test "${#checksums[@]}" -eq 1
+            cp -- "${archives[0]}" "publish-assets/$name"
+            cp -- "${checksums[0]}" "publish-assets/$name.sha256"
             (
-              cd release-assets
-              sha256sum -c "$(basename "$archive.sha256")"
+              cd publish-assets
+              sha256sum -c "$name.sha256"
             )
           done
       - name: Upload Linux assets to a draft GitHub Release
@@ -160,7 +166,7 @@ jobs:
               --title "$GITHUB_REF_NAME"
           fi
           gh release upload "$GITHUB_REF_NAME" \
-            release-assets/memhub-runtime-v*-linux-*.tar.gz \
-            release-assets/memhub-runtime-v*-linux-*.tar.gz.sha256 \
+            publish-assets/memhub-runtime-v*-linux-*.tar.gz \
+            publish-assets/memhub-runtime-v*-linux-*.tar.gz.sha256 \
             --repo "$GITHUB_REPOSITORY" \
             --clobber

.gitignore

@@ -26,6 +26,9 @@ 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,6 +2,340 @@
 
 Hy Memory and MemHub are versioned and released independently.
 
+## Unreleased
+
+- Hy Memory: new `hy_memory.reembed` module for switching the embedding
+  model. Writers must be paused for the whole run. Nothing is derived from
+  the provider or endpoint: source and target are named explicitly, and the
+  identity of a space is the model name plus the width (`space_identity`).
+  Only Chroma and Kuzu are supported.
+  - `vector_space_names(config, base_name=None)` returns every physical
+    collection a client opens for the six vector roles: memory, entities,
+    coding keys and working facts, each in the working and coding variants.
+  - `reembed_vector_space(source, target, embedding=...)` pages every raw
+    source collection, covering all users and all layers including L1_RAW. It
+    embeds the text the write path embedded (`reembed_text`: the canonical
+    state's `state_retrieval_text`, a schema's `retrieval_text`, otherwise the
+    document). It then writes each record into the target with the same id,
+    document and metadata. Each batch's widths are checked before anything is
+    written. A cancel stops at a batch boundary (`ReembedCancelled`). A rerun
+    skips the ids the target already holds, so it resumes, and a merge never
+    overwrites the target. The source is never written.
+  - `plan_reembed`, `verify_reembed` and `drop_vector_space` complete the
+    vector side. `verify_reembed` checks ids, metadata, per-user counts and
+    the width, and runs a self-recall sample. `drop_vector_space` refuses
+    collections that a live client in this process holds open.
+  - `scan_vector_spaces(persist_directory)` is read-only. It lists every
+    space on disk with its roles, counts, stored width, per-user counts and
+    the models recorded in metadata. `diff_spaces(source, target)` returns the
+    ids that the source holds and the target lacks, whatever their status.
+  - `reembed_graph(source_path, target_path, embedding=..., target_dims=...)`
+    builds a new Kuzu graph at the new width. It copies every node and edge
+    and recomputes `Memory.embedding`, `Memory.beh_embedding`, and the Topic
+    and HierarchyTopic embeddings, then rebuilds the HNSW index. The source
+    graph is opened read-only and kept for rollback. A run that fails or is
+    cancelled leaves no target behind, and a rerun starts over.
+    `verify_graph_reembed` and `drop_graph` complete the graph side.
+- Hy Memory: `EmbedService.embed_batch` now splits large batches into
+  requests of `embedder.batch_size` texts each (`MEMORY_EMBEDDER_BATCH_SIZE`,
+  default 64); before, it sent them all in one request. On a 429 it waits for
+  the `Retry-After` time plus jitter, capped at 60 s. It takes a per-call
+  `max_retries`. A returned vector whose width differs from the configured
+  `embedding_dims` now raises `EmbeddingDimensionMismatchError` and is not
+  retried.
+- Hy Memory: Raw conversations are stored already trimmed. MemHub now keeps every raw
+  forever and lite mode stores nothing else, so tool output and long pasted
+  logs no longer stay in full. One rule (`hy_memory/utils/raw_trim.py`) is
+  applied to each message when the raw is written:
+  - `user` and `system` turns are kept in full;
+  - `assistant` turns and other speakers (`[John]:`) longer than 500
+    characters, after stripping, are cut to the first 500 plus `...`. This is
+    the limit history injection used before;
+  - `tool` turns keep their head and tail, and the middle becomes
+    `[...N bytes omitted by truncate...]`, with the coding limit
+    `coding.tool_result_max_bytes` (`MEMORY_CODING_TOOL_RESULT_MAX_BYTES`,
+    default 2048).
+
+  The rule is idempotent. It covers chat `L1_RAW` in lite, pro and ultra (lite
+  keeps tool turns, because it has no coding route) and the `memory_history`
+  ADD record. The coding/working `coding_trace` was already trimmed when it
+  was written. Its tool and assistant truncations are now idempotent, so
+  reading the history back no longer rewrites the omitted-count markers. The
+  text embedded for `L1_RAW` is the trimmed text. New raws carry
+  `custom.raw_trimmed=true`.
+- Hy Memory: extractor history ("last k messages") now joins the stored raws directly
+  and does not trim them again. Raws written before this change have no
+  `raw_trimmed` flag, so they are still trimmed with the same rule when they
+  are read. The extractor still receives the current batch in full (tool
+  turns are still removed on the chat route).
+
+## 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.9 — 2026-11-01
+
+- Published
+  [`hy-memory==2.0.9`](https://pypi.org/project/hy-memory/2.0.9/).
+- Placeholder values no longer overwrite the user's basic profile (L0). A
+  small extraction model filled `basic_info` with `{"name": "用户"}`,
+  `The user` or `N/A` when the user had said nothing about themselves, and
+  each placeholder superseded the real value, so the L0 chain read
+  费天翔 → Fei → 用户 → The user. Two defences:
+  - `upsert_basic_profile` drops placeholder values: empty, `用户`,
+    `the user`, `user`, `n/a`, `na`, `none`, `null`, `unknown`, `未提供`,
+    `未知`, `不详`, `-`, `?` and the field's own name, compared
+    case-insensitively with whitespace and punctuation stripped. When nothing
+    is left it writes no new version and no new L0 head. Placeholders already
+    stored in the chain no longer override earlier real values when the
+    profile is assembled, so `get_user_profile` of an affected user shows the
+    last real value again without any migration. This also stops an
+    assistant quoting an old memory ("The user's name is 用户.") from being
+    written back.
+  - The extraction prompts (zh and en) state the rule: only what the user
+    said in a `user` turn, never the field name or a placeholder, `{}`
+    otherwise, with a small-talk counter-example.
+
+## 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/).
+
+## Hy Memory 2.0.5.dev3 — 2026-10-21
+
+- Development preview; not the final `2.0.5` release.
+- Published as
+  [`hy-memory==2.0.5.dev3`](https://pypi.org/project/hy-memory/2.0.5.dev3/).
+- Lets the existing `search` API explicitly query SDK raw with
+  `layers=["l1_raw"]`, including existing source filters.
+
+## Hy Memory 2.0.5.dev2 — 2026-10-21
+
+- Development preview; not the final `2.0.5` release.
+- Published as
+  [`hy-memory==2.0.5.dev2`](https://pypi.org/project/hy-memory/2.0.5.dev2/).
+- Adds exact, idempotent semantic-memory import for legacy MemHub cutover
+  without extraction, reconciliation or identity changes.
+
+## Hy Memory 2.0.5.dev1 — 2026-10-21
+
+- Development preview for the MemHub SDK-authority migration; this is not the
+  final `2.0.5` release.
+- Published as
+  [`hy-memory==2.0.5.dev1`](https://pypi.org/project/hy-memory/2.0.5.dev1/).
+- Adds lifecycle status filtering, durable idempotent write outcomes, exact raw
+  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
@@ -12,16 +346,6 @@ Hy Memory and MemHub are versioned and released independently.
   unchanged memory extraction, reconciliation, storage, and Coding/Working
   behavior.
 
-## Unreleased
-
-- 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
@@ -36,7 +360,17 @@ Hy Memory and MemHub are versioned and released independently.
   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.3 — Unreleased
+## 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
 
 - Updated the source version to `1.0.3` (build 7).
 - Pinned the public SDK to `hy-memory==2.0.3`.

README.md

@@ -32,7 +32,10 @@ English | [中文](README.zh.md)
 
 ## Latest News
 
-* *<mark>[new]</mark>* 🔥🔥🔥 **[2026-10]**: 🚀 **Released** **Hy Memory 2.0 (`hy-memory==2.0.3`)** on [PyPI](https://pypi.org/project/hy-memory/2.0.3/) and open-sourced the **Hy-Memory** monorepo together with **[MemHub](memhub/README.md)**!
+* *<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!
 * *<mark>[new]</mark>* 🔥🔥 **[2026-09]**: 📊 **Released** **[CMB: A Coding Memory Benchmark for Long-Horizon and Interleaved Coding Agents](docs/papers/CMB_A_Coding_Memory_Benchmark_for_Long_Horizon_and_Interleaved_Coding_Agents.pdf)** (submitted to **ICLR 2027**).
 * *<mark>[new]</mark>* 🔥🔥 **[2026-08]**: 🎉 **Accepted** at **EMNLP 2026**: **[Memory Beyond Recall: A Dual-Process Cognitive Memory System for Self-Evolving LLM Agents](https://arxiv.org/abs/2606.09483)**!
@@ -63,13 +66,13 @@ Welcome to the **Hy Memory Research Family**, covering cognitive chat memory, lo
 ### 1. Installation
 
 ```bash
-pip install hy-memory==2.0.3              # core (includes ChromaDB and Kuzu)
-pip install "hy-memory[qdrant]==2.0.3"    # + Qdrant
-pip install "hy-memory[faiss]==2.0.3"     # + FAISS
-pip install "hy-memory[graph]==2.0.3"     # + Neo4j
-pip install "hy-memory[mysql]==2.0.3"     # + MySQL cache
-pip install "hy-memory[rerank]==2.0.3"    # + local multilingual cross-encoder rerank
-pip install "hy-memory[all]==2.0.3"       # everything
+pip install hy-memory==2.0.4              # core (includes ChromaDB and Kuzu)
+pip install "hy-memory[qdrant]==2.0.4"    # + Qdrant
+pip install "hy-memory[faiss]==2.0.4"     # + FAISS
+pip install "hy-memory[graph]==2.0.4"     # + Neo4j
+pip install "hy-memory[mysql]==2.0.4"     # + MySQL cache
+pip install "hy-memory[rerank]==2.0.4"    # + local multilingual cross-encoder rerank
+pip install "hy-memory[all]==2.0.4"       # everything
 ```
 
 ### 2. Configuration
@@ -151,7 +154,7 @@ result = client.search(
 
 result["facts"]          # fact layer
 result["experiences"]    # experience layer
-result["chain_block"]    # coding only: version-evolution context
+result["chain_block"]    # coding only: version-evolution context (empty unless MEMORY_CODING_CHAIN_BLOCK_ENABLED)
 ```
 
 ### 5. Routing, Source Isolation & Advanced APIs
@@ -251,6 +254,7 @@ 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

@@ -32,7 +32,10 @@
 
 ## 最新动态
 
-* *<mark>[new]</mark>* 🔥🔥🔥 **[2026-10]**: 🚀 **正式发布** **Hy Memory 2.0 (`hy-memory==2.0.3`)**（已上线 [PyPI](https://pypi.org/project/hy-memory/2.0.3/)），并开源 **Hy-Memory** monorepo 与 **[MemHub](memhub/README.md)**！
+* *<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)！
 * *<mark>[new]</mark>* 🔥🔥 **[2026-09]**: 📊 **基准与方法发布** 推出长周期与交错式编程记忆评测基准 **[CMB: A Coding Memory Benchmark for Long-Horizon and Interleaved Coding Agents](docs/papers/CMB_A_Coding_Memory_Benchmark_for_Long_Horizon_and_Interleaved_Coding_Agents.pdf)**（已投稿 **ICLR 2027**）。
 * *<mark>[new]</mark>* 🔥🔥 **[2026-08]**: 🎉 **论文录用** 双系统认知记忆架构论文 **[Memory Beyond Recall: A Dual-Process Cognitive Memory System for Self-Evolving LLM Agents](https://arxiv.org/abs/2606.09483)** 被 **EMNLP 2026** 接收！
@@ -63,13 +66,13 @@
 ### 1. 安装
 
 ```bash
-pip install hy-memory==2.0.3              # 核心（含 ChromaDB 与 Kuzu）
-pip install "hy-memory[qdrant]==2.0.3"    # + Qdrant
-pip install "hy-memory[faiss]==2.0.3"     # + FAISS
-pip install "hy-memory[graph]==2.0.3"     # + Neo4j
-pip install "hy-memory[mysql]==2.0.3"     # + MySQL 缓存
-pip install "hy-memory[rerank]==2.0.3"    # + 本地多语言 cross-encoder rerank
-pip install "hy-memory[all]==2.0.3"       # 全部
+pip install hy-memory==2.0.4              # 核心（含 ChromaDB 与 Kuzu）
+pip install "hy-memory[qdrant]==2.0.4"    # + Qdrant
+pip install "hy-memory[faiss]==2.0.4"     # + FAISS
+pip install "hy-memory[graph]==2.0.4"     # + Neo4j
+pip install "hy-memory[mysql]==2.0.4"     # + MySQL 缓存
+pip install "hy-memory[rerank]==2.0.4"    # + 本地多语言 cross-encoder rerank
+pip install "hy-memory[all]==2.0.4"       # 全部
 ```
 
 ### 2. 配置
@@ -151,7 +154,7 @@ result = client.search(
 
 result["facts"]          # 事实层
 result["experiences"]    # 经验层
-result["chain_block"]    # 仅 coding：版本演进上下文
+result["chain_block"]    # 仅 coding：版本演进上下文（默认空；需 MEMORY_CODING_CHAIN_BLOCK_ENABLED）
 ```
 
 ### 5. 自动路由、来源过滤与进阶 API
@@ -251,6 +254,7 @@ 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

@@ -48,6 +48,7 @@
 | `MEMORY_EMBEDDER_TIMEOUT` | `15` | 单次超时，秒 |
 | `MEMORY_EMBEDDER_MAX_RETRIES` | `2` | 最大重试次数 |
 | `MEMORY_EMBEDDER_RETRY_DELAY` | `0.3` | 重试间隔，秒 |
+| `MEMORY_EMBEDDER_BATCH_SIZE` | `64` | `embed_batch` 单次请求最多发送的文本条数，超出按此切块 |
 | `MEMORY_EMBEDDER_EXTRA_HEADERS` | — | JSON object，附加 HTTP headers |
 | `MEMORY_EMBEDDER_EXTRA_BODY` | — | JSON object，附加请求 body |
 
@@ -191,12 +192,14 @@ 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` | 是否启用历史记录 |
 | `MEMORY_HISTORY_DB_PATH` | `{DATA_DIR}/data/history.db` | History SQLite 路径 |
 | `MEMORY_HISTORY_RECORD_SEARCHES` | `false` | 是否记录 Search 操作 |
 | `MEMORY_CODING_CHAIN_REPO_ROOT` | — | coding 版本链读取本地 Git diff 的仓库根目录 |
+| `MEMORY_CODING_CHAIN_BLOCK_ENABLED` | `false` | search(scene=coding) 是否注入版本演进链块（diff / `chain_block`）；默认关 |
 
 ## HTTP Server
 

docs/hy_memory_search_skill.md

@@ -78,7 +78,8 @@ default 多-query 超过 `MEMORY_QUERY_REWRITE_MAX_CHARS` 时不改写：Coding
 Coding 关闭则直接使用最后一条 query。
 
 路由到 `working` / `coding` 后，Search 读取独立生产力记忆库，返回 `facts` /
-`experiences`，不使用 chat 三通道结构。`coding` 还返回 `chain_block` / `chain_used`。
+`experiences`，不使用 chat 三通道结构。`coding` 还返回 `chain_block` / `chain_used`
+（默认空；需 `MEMORY_CODING_CHAIN_BLOCK_ENABLED` 才注入 diff 块）。
 
 ## Chat 成功返回结构
 
@@ -152,7 +153,7 @@ client = HyMemoryClient.from_config({
 安装可选依赖：
 
 ```bash
-pip install 'hy-memory[rerank]==2.0.1'
+pip install 'hy-memory[rerank]==2.0.4'
 ```
 
 启用后，`HyMemoryClient(...)` 构造阶段会完成模型下载/读取、device 放置和一次 dummy

docs/monorepo.md

@@ -37,8 +37,7 @@ do not belong in the public source tree.
 - Root GitHub workflows run SDK and MemHub checks from their respective working
   directories. Native lifecycle workflows produce reviewable Actions artifacts;
   tag releases remain fail-closed on public identity, signing and notarization.
-- Hy Memory is published as `hy-memory==2.0.3`. MemHub pins that public
-  distribution; its selected npm package is `memhub-cli`, which is not yet
-  published.
+- Hy Memory is published as `hy-memory==2.0.4`. MemHub pins that public
+  distribution; its selected npm package is `memhub-cli` 1.0.5.
 - Hy-Memory source uses Apache-2.0 at the repository root. Third-party
   components retain their own licenses and attribution notices.

docs/scene_coding_usage.md

@@ -168,9 +168,11 @@ working/coding 搜索返回：
 
 `limit` 分别限制 facts 与 experiences，因此两层最多各返回 `limit` 条。
 
-`scene="coding"` 额外返回 `chain_block` 和 `chain_used`：
+`scene="coding"` 额外返回 `chain_block` 和 `chain_used` 字段（键始终存在；默认内容为空）：
 
-- `chain_block` 是与已召回 fact 对齐的版本演进上下文；无法挂链时为 `""`。
+- 注入 diff / 版本演进块需显式开启 `MEMORY_CODING_CHAIN_BLOCK_ENABLED=true`
+  （或 `CodingConfig.chain_block_enabled=True`）。默认关闭，以节约 prompt token。
+- 开启后，`chain_block` 是与已召回 fact 对齐的版本演进上下文；无法挂链时为 `""`。
 - `chain_used` 是已经进入 chain block 的 `facts` 下标。
 - SDK 不会从 `facts` 删除这些条目。调用方若要拼成“chain block + 剩余 facts”，需自行按 `chain_used` 过滤。
 
@@ -222,10 +224,12 @@ working/coding 搜索返回：
 | `MEMORY_CODING_DB_PATH` | `{DATA_DIR}/data/coding_memory.db` | working 基础 SQLite 路径；coding/trace 路径由此派生 |
 | `MEMORY_CODING_TOOL_RESULT_MAX_BYTES` | `2048` | 单条 tool result 的字节上限 |
 | `MEMORY_CODING_VERBATIM_FALLBACK_ENABLED` | `false` | 模型无结果时是否保存原文 fact；默认关闭，避免 assistant/tool trace 直接展示 |
+| `MEMORY_CODING_CHAIN_BLOCK_ENABLED` | `false` | search 是否注入版本演进链块（`chain_block` / diff）；默认关闭（opt-in） |
 | `MEMORY_EXTRACT_HISTORY_TURNS` | `5` | 回读的历史 user-turn 数；当前 prompt 最终最多使用 5 |
 | `MEMORY_CODING_CHAIN_REPO_ROOT` | 空 | coding 版本链读取本地 Git diff 的仓库路径 |
 
 `HCM_*` 变量属于版本链的高级调优项，不是稳定的公共配置契约；普通接入不应依赖其默认值。
+其中 `HCM_BLOCK_OFF=1` 可在已开启 `MEMORY_CODING_CHAIN_BLOCK_ENABLED` 时做消融（完全不出块）。
 
 ## 8. 定向验证
 

docs/usage.md

@@ -5,14 +5,14 @@
 ## 安装与快速开始
 
 ```bash
-pip install hy-memory==2.0.3
+pip install hy-memory==2.0.4
 
 # 可选后端
-pip install 'hy-memory[qdrant]==2.0.1'
-pip install 'hy-memory[faiss]==2.0.1'
-pip install 'hy-memory[graph]==2.0.1'     # Neo4j；Kuzu 已在核心依赖中
-pip install 'hy-memory[mysql]==2.0.1'
-pip install 'hy-memory[rerank]==2.0.1'    # 本地多语言 cross-encoder rerank
+pip install 'hy-memory[qdrant]==2.0.4'
+pip install 'hy-memory[faiss]==2.0.4'
+pip install 'hy-memory[graph]==2.0.4'     # Neo4j；Kuzu 已在核心依赖中
+pip install 'hy-memory[mysql]==2.0.4'
+pip install 'hy-memory[rerank]==2.0.4'    # 本地多语言 cross-encoder rerank
 ```
 
 默认 LLM 和 Embedding 均使用 OpenAI-compatible 接口。使用 OpenAI 时可只设置：
@@ -106,6 +106,15 @@ result = client.add(
 )
 ```
 
+`metadata` 与 `meta` 不是同一字段：
+
+- `metadata` 是兼容旧调用方保留的 SDK 处理选项，会进入内部
+  `WriteRequest.extra`，不保证持久化或随查询结果返回。
+- `meta` 是调用方的业务上下文，会持久化并在 `search()`、`get()` 等结果中返回。
+  同一记忆被多次合并时，各次 `meta` 会按写入顺序保存在列表中。
+
+需要以后读回的数据必须放在 `meta`，不要放在 `metadata`。
+
 `scene` 的公开取值：
 
 - `None`：普通文本直接走 chat；messages 含 tool 时执行快速场景判断。
@@ -201,7 +210,8 @@ result = client.search(
 ```
 
 `working` / `coding` 路径返回 `scene="productivity"`、`facts`、`experiences`，不使用
-chat 的三桶结构；`coding` 还会返回 `chain_block` 和 `chain_used`。
+chat 的三桶结构；`coding` 还会返回 `chain_block` 和 `chain_used` 字段（默认空；
+需 `MEMORY_CODING_CHAIN_BLOCK_ENABLED=true` 才注入 diff 块）。
 
 #### `search_mode`
 
@@ -263,6 +273,8 @@ catalog 也可以在没有基础 L0 时形成只读的合成画像。
 
 ```python
 memory = client.get("memory_id")
+# raw ID 返回 L1_RAW，fact ID 返回对应事实层。
+raw_memory = client.get("raw_id")
 result = client.update("memory_id", "更新后的内容")
 result = client.delete("memory_id")
 result = client.delete_all(user_id="user_001")
@@ -272,7 +284,7 @@ page = client.list_memories(
     limit=100,
     offset=0,
     order="desc",
-    layers=None,
+    layers=["l1_raw"],  # 显式列出 raw；不传仍沿用默认语义层列表
     with_evolution=False,
 )
 
@@ -282,6 +294,11 @@ 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。
+
 普通 `list_memories()` 返回 `vdb` 桶，并在 Graph 有结果时附带 `graph`；传入
 `workspace_id` 时返回生产力记忆的 `scene="productivity"` 和 `experiences`。
 

hy_memory/__init__.py

@@ -55,9 +55,49 @@ except Exception:
 from .client import HyMemoryClient
 from .inspector import MemoryInspector
 from .runtime import SharedRuntime
+from .reembed import (
+    EmbeddingSpaceIdentity,
+    GraphReembedPlan,
+    GraphReembedProgress,
+    GraphReembedReport,
+    GraphVerification,
+    ReembedCancelled,
+    ReembedPlan,
+    ReembedProgress,
+    ReembedReport,
+    ReembedVerification,
+    ScannedSpace,
+    SpaceDiff,
+    VectorSpace,
+    diff_spaces,
+    drop_graph,
+    drop_vector_space,
+    plan_reembed,
+    reembed_graph,
+    reembed_text,
+    reembed_vector_space,
+    scan_vector_spaces,
+    space_identity,
+    vector_space_names,
+    verify_graph_reembed,
+    verify_reembed,
+)
+from .snapshot import (
+    DataPlaneRestore,
+    DataPlaneSnapshot,
+    DataPlaneSnapshotRejected,
+    restore_local_data_plane,
+    snapshot_local_data_plane,
+)
 
 # ====== 配置 ======
 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
@@ -111,8 +151,46 @@ __all__ = [
     "HyMemoryClient",
     "MemoryInspector",
     "SharedRuntime",
+    "DataPlaneRestore",
+    "DataPlaneSnapshot",
+    "DataPlaneSnapshotRejected",
+    "restore_local_data_plane",
+    "snapshot_local_data_plane",
+    # 换 embedding 模型：把向量库和图重新 embed 进新的 embedding 空间
+    "EmbeddingSpaceIdentity",
+    "GraphReembedPlan",
+    "GraphReembedProgress",
+    "GraphReembedReport",
+    "GraphVerification",
+    "ReembedCancelled",
+    "ReembedPlan",
+    "ReembedProgress",
+    "ReembedReport",
+    "ReembedVerification",
+    "ScannedSpace",
+    "SpaceDiff",
+    "VectorSpace",
+    "diff_spaces",
+    "drop_graph",
+    "drop_vector_space",
+    "plan_reembed",
+    "reembed_graph",
+    "reembed_text",
+    "reembed_vector_space",
+    "scan_vector_spaces",
+    "space_identity",
+    "vector_space_names",
+    "verify_graph_reembed",
+    "verify_reembed",
     # 配置
     "MemoryConfig",
+    # 公共扩展协议 / 精确读取类型
+    "EmbeddingService",
+    "EmbeddingServiceProtocol",
+    "EmbeddingDimensionMismatchError",
+    "MemoryKind",
+    "MemoryVariant",
+    "AmbiguousMemoryIdError",
     # Embedding 端点覆盖
     "embed_endpoint_override",
     # 高级 API

hy_memory/agent/abstractor.py

@@ -22,7 +22,8 @@ logger = logging.getLogger(__name__)
 
 # ================================================================
 # 数据结构
-# ================================================================@dataclass
+# ================================================================
+@dataclass
 class SessionSummaryResult:
     """Session 摘要结果 (V2)"""
     success: bool

hy_memory/agent/episode_summary.py

@@ -39,6 +39,7 @@ import logging
 import hashlib
 import json
 import re
+from datetime import datetime
 from typing import Any, Dict, List, Optional
 import uuid
 
@@ -252,6 +253,17 @@ def _series_episode_id(
     return str(uuid.uuid5(uuid.NAMESPACE_URL, "hy-memory:series-episode:" + raw))
 
 
+def _series_memory_at(times: List[int]) -> Optional[datetime]:
+    """Earliest member timestamp as the same local wall clock it came from.
+
+    ``_node_timestamp`` produces ``datetime.timestamp()`` values. Reading them
+    back with ``utcfromtimestamp`` turns them into a naive *UTC* datetime, which
+    the vector payload later re-interprets as local time and shifts by the
+    machine's UTC offset.
+    """
+    return datetime.fromtimestamp(min(times)) if times else None
+
+
 def _node_timestamp(node: Any) -> Optional[int]:
     value = getattr(node, "memory_at", None) or getattr(node, "gmt_created", None)
     if value is None:
@@ -974,8 +986,6 @@ async def finalize_series_episode_containers(
     Stored text is only a title plus a structural intro. Exact L2 bodies remain in
     their canonical nodes and are referenced by ID from dated timeline segments.
     """
-    from datetime import datetime
-
     from ..models.memory import MemoryLayer, MemoryNode, MemoryStatus, SourceType
     from ..pipelines._retrieval.session_episode import (
         add_parent_episode_membership,
@@ -1061,7 +1071,7 @@ async def finalize_series_episode_containers(
             segment["memory_at"] for segment in plan["timeline"]
             if segment.get("memory_at") is not None
         ]
-        memory_at = datetime.utcfromtimestamp(min(times)) if times else None
+        memory_at = _series_memory_at(times)
         content = f"{plan['title']}. {plan['intro']}".strip()
         series = MemoryNode(
             node_id=series_id, user_id=user_id,

hy_memory/agent/extractor.py

@@ -682,6 +682,23 @@ Output:
 ```
 John's occupation and location are HIS attributes, so they go into `memory` with "John" as the subject. They must NEVER land in `basic_info.occupation` / `basic_info.location` — `basic_info` is exclusively the user's own profile. Only `name` (Tim, from the user message's `name` field) belongs there.
 
+## Example 11 — Counter-example: small talk has no basic_info
+
+New Messages:
+[{"role": "user", "content": "Hi"},
+ {"role": "assistant", "content": "Hello! The user's name is The user. How can I help?"}]
+Memory Date: 2025-09-03
+
+Output:
+```json
+{
+  "memory": [],
+  "intentions": [],
+  "basic_info": {}
+}
+```
+The user stated nothing about themselves. The assistant's line is not a user turn, and "The user" is a placeholder, not a name. Output `{}` — never `{"name": "The user"}` or `{"name": "user"}`.
+
 ---
 """
 
@@ -749,6 +766,14 @@ Rules:
   fields (e.g. name, age, location, occupation, employer) **explicitly stated**
   in the NEW user messages. Never infer, never invent. If no field is explicitly
   stated, output `{{}}`.
+  * HARD RULE: fill a field ONLY if the user stated it in a `user` turn.
+    Anything said only by the assistant (including the assistant quoting an
+    earlier memory such as "The user's name is X") does NOT count. If nothing
+    qualifies, output `"basic_info": {{}}`.
+  * NEVER write the field name itself or a placeholder as a value ("user",
+    "The user", "用户", "name", "N/A", "unknown", "none", "-"). Omit the field.
+  * Negative example: small talk such as `[user]: Hi` / `[assistant]: How can
+    I help?`, or `[user]: Reply with exactly: PONG` → `"basic_info": {{}}`.
   * Exception for `name`: the `name` field on the user's own message, or a leading
     line "The user's name is X" / "用户名叫X", is an authoritative source for
     `name` — even though the user never said it out loud.
@@ -817,6 +842,14 @@ Rules:
   fields (e.g. name, age, location, occupation, employer) **explicitly stated**
   in the NEW user messages. Never infer, never invent. If no field is explicitly
   stated, output `{{}}`.
+  * HARD RULE: fill a field ONLY if the user stated it in a `user` turn.
+    Anything said only by the assistant (including the assistant quoting an
+    earlier memory such as "The user's name is X") does NOT count. If nothing
+    qualifies, output `"basic_info": {{}}`.
+  * NEVER write the field name itself or a placeholder as a value ("user",
+    "The user", "用户", "name", "N/A", "unknown", "none", "-"). Omit the field.
+  * Negative example: small talk such as `[user]: Hi` / `[assistant]: How can
+    I help?`, or `[user]: Reply with exactly: PONG` → `"basic_info": {{}}`.
   * Exception for `name`: the `name` field on the user's own message, or a leading
     line "The user's name is X" / "用户名叫X", is an authoritative source for
     `name` — even though the user never said it out loud.
@@ -1177,7 +1210,7 @@ class Extractor:
                         if not tc_id:
                             logger.error(
                                 f"[extractor] tool_call_id is empty! "
-                                f"raw tc: {json.dumps(tc_raw, ensure_ascii=False, default=str)[:500]}"
+                                f"raw_keys={list(tc_raw.keys())}"
                             )
                         try:
                             t_res = await tool_registry.dispatch(
@@ -1311,11 +1344,12 @@ class Extractor:
                 if parsed is None:
                     if not all_tool_calls:
                         logger.warning(
-                            f"[extractor] JSON parse failed: {raw_text[:200]}"
+                            f"[extractor] JSON parse failed ({len(raw_text)} chars)"
                         )
+                        logger.debug(f"[extractor] unparsable output: {raw_text[:200]!r}")
                         return ExtractResult(
                             success=False,
-                            error=f"JSON parse failed: {raw_text[:200]}",
+                            error=f"JSON parse failed ({len(raw_text)} chars)",
                             error_code="JSON_PARSE_FAILED",
                             raw_response=raw_text,
                             tokens_used=total_tokens,

hy_memory/agent/llm_provider.py

@@ -129,8 +129,7 @@ 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'! raw: "
-                f"{_json.dumps(tc, ensure_ascii=False, default=str)[:500]}"
+                f"[llm] tool_call missing 'id'! keys={list(tc.keys())}"
             )
 
         # 保留原始 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.info(f"MemAgent: extracted_info={extract_result.info}")
+                logger.debug(f"MemAgent: extracted_info={extract_result.info}")
 
             # 3. 冲突检测（如果有已有记忆）
             if mode == ProcessMode.FULL and existing_memories:

hy_memory/agent/prompts_zh.py

@@ -365,6 +365,13 @@ EXTRACT_PROMPT_ZH = """## 最近 k 条消息
 * basic_info：**只装用户本人的画像**。
   仅当 NEW user messages 中**明确**陈述稳定画像字段（如 姓名、年龄、所在地、职业、雇主）时才填写。
   绝不推断、绝不编造。没有任何字段被明确陈述时输出 `{{}}`。
+  * **硬性规则**：只有用户在 `user` 回合里**明确说出**的字段才能填写。只在
+    assistant 回合出现的内容（包括 assistant 引用旧记忆，如"The user's name is X"
+    / "用户名是X"）一律不算。没有符合条件的字段时，必须输出 `"basic_info": {{}}`。
+  * **绝不**把字段名本身或占位符当值写入（"用户"、"The user"、"user"、"name"、
+    "姓名"、"N/A"、"unknown"、"未知"、"未提供"、"-"），宁可省略该字段。
+  * 负例：寒暄如 `[user]: 你好` / `[assistant]: 我可以帮你。`，或
+    `[user]: Reply with exactly: PONG` → `"basic_info": {{}}`。
   * `name` 的例外：用户自己那条消息上的 `name` 字段，或文首形如
     "用户名叫X" / "The user's name is X" 的那一行，都是 `name` 的权威来源
     ——即使用户本人从未开口自报姓名。
@@ -440,6 +447,13 @@ EXTRACT_PROMPT_ZH_NO_INTENTION = """## 最近 k 条消息
 * basic_info：**只装用户本人的画像**。
   仅当 NEW user messages 中**明确**陈述稳定画像字段（如 姓名、年龄、所在地、职业、雇主）时才填写。
   绝不推断、绝不编造。没有任何字段被明确陈述时输出 `{{}}`。
+  * **硬性规则**：只有用户在 `user` 回合里**明确说出**的字段才能填写。只在
+    assistant 回合出现的内容（包括 assistant 引用旧记忆，如"The user's name is X"
+    / "用户名是X"）一律不算。没有符合条件的字段时，必须输出 `"basic_info": {{}}`。
+  * **绝不**把字段名本身或占位符当值写入（"用户"、"The user"、"user"、"name"、
+    "姓名"、"N/A"、"unknown"、"未知"、"未提供"、"-"），宁可省略该字段。
+  * 负例：寒暄如 `[user]: 你好` / `[assistant]: 我可以帮你。`，或
+    `[user]: Reply with exactly: PONG` → `"basic_info": {{}}`。
   * `name` 的例外：用户自己那条消息上的 `name` 字段，或文首形如
     "用户名叫X" / "The user's name is X" 的那一行，都是 `name` 的权威来源
     ——即使用户本人从未开口自报姓名。
@@ -669,6 +683,23 @@ Memory Date：2025-09-02
 ```
 职业和所在地是 **John 的**属性，所以进 `memory` 并以"John"作主体，**绝不能**落到 `basic_info` 的 `occupation` / `location` —— `basic_info` 专属于用户本人。只有 `name`（Tim，来自用户消息的 `name` 字段）才该放进去。注意输出语言随输入语言（此例为英文）。
 
+## 示例 11 —— 反例：寒暄没有 basic_info
+
+新消息：
+[{"role": "user", "content": "你好"},
+ {"role": "assistant", "content": "你好！我可以帮你。之前记得 The user's name is 用户."}]
+Memory Date：2025-09-03
+
+输出：
+```json
+{
+  "memory": [],
+  "intentions": [],
+  "basic_info": {}
+}
+```
+用户没有说任何关于自己的信息。assistant 那句不是 user 回合，"用户" 也是占位符而不是名字。必须输出 `{}`——**绝不能**输出 `{"name": "用户"}`。
+
 ---
 """
 
@@ -743,6 +774,7 @@ RECONCILE_PROMPT_ZH = """你是一个记忆整合系统（Memory Reconciler）
 
 * content
 * owner
+* memory_at（发生时间）
 * tags
 
 new memories 没有 ID。
@@ -791,6 +823,7 @@ new memories 没有 ID。
 * 无损合并
 * 保留所有有效信息
 * 不要产生重复 memory
+* 两者在某个值上不一致时，保留 memory_at 更晚的那个值；绝不用更早的 memory 覆盖更新的值
 
 ### 同一次事件的补充 vs 另一次发生
 
@@ -823,6 +856,7 @@ new memories 没有 ID。
 * 新 memory 与旧 memory 在同一维度冲突
 * 两者不能同时为真
 * 旧 memory 已不再代表当前状态
+* 新 memory 的 memory_at 不早于旧 memory 的 memory_at
 
 例如：
 
@@ -837,6 +871,7 @@ new memories 没有 ID。
 * wording 差异
 * 同义表达
 * 可共存偏好
+* 新 memory 的 memory_at 早于旧 memory：它是更早的状态，绝不能取代更新的状态（见「时间规则」）
 
 要求：
 
@@ -859,7 +894,7 @@ new memories 没有 ID。
 
 ### 把多条旧记忆折叠进同一条链
 
-如果**两条或更多**已有记忆描述的是**同一维度**，而新记忆是该维度上的最新变化，
+如果**两条或更多**已有记忆描述的是**同一维度**，而新记忆是该维度上的最新变化（它的 memory_at 晚于所有被折叠的记忆），
 你可以把它们折叠进同一条演化链。此时用 `memory_ids`（有序列表，**旧→新**）
 代替单个 `memory_id`：
 
@@ -951,13 +986,16 @@ SUPERSEDE 不需要复制旧内容，因为旧节点仍存在。
 
 ## 时间规则
 
-`memory_at: null`
+每条 memory（新的和已有的）都带 memory_at，表示它发生的时间。记忆**不一定按发生顺序写入**：
+历史可能晚导入，导入还没处理完时用户也可能手动添加记忆。所以一条 new memory 可能**比已有记忆更早**。
 
-表示时间未知。
-
-不要编造时间顺序。
-
-不要仅因为“看起来更新”就 supersede。
+* 新旧**只看 memory_at**。"New memories" 只表示"正在写入"，不表示"更近"。
+* 更早的 memory 绝不能取代更新的 memory：不能 SUPERSEDE 一条更新的记忆，也不能用 UPDATE 拿更早的值覆盖更新的值。
+* 如果 new memory 比与它冲突的已有记忆更早：保留已有记忆作为当前状态；把 new memory 以"过去状态"ADD
+  （用过去时，并带上时间，例如"2023 年用户住在上海"），没有新信息就不输出。
+* `memory_at: null` 表示时间未知。未知**不算更新**：不要用 memory_at 为 null 的 memory 去 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:
-    """以单条 INFO（JSON list）输出 reconcile 的逐条结果，便于线上 debug。"""
+    """以单条 DEBUG（JSON list）输出 reconcile 的逐条结果；含记忆正文，不进 INFO。"""
     if not ops:
         return
     view = [
@@ -68,7 +68,7 @@ def _log_ops_detail(ops: List["ReconcileOp"]) -> None:
         }
         for o in ops
     ]
-    logger.info(
+    logger.debug(
         f"[reconciler] ops detail: {json.dumps(view, ensure_ascii=False, default=str)}"
     )
 
@@ -221,6 +221,8 @@ 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
 
@@ -255,6 +257,7 @@ 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:
 
@@ -268,6 +271,8 @@ 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:
 
@@ -289,7 +294,8 @@ 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, you may fold them into a single evolution
+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
 chain. Use `memory_ids` (an ordered list, OLDEST → NEWEST) instead of a single
 `memory_id`:
 
@@ -318,8 +324,7 @@ 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.
-* Do not invent chronology.
-* `memory_at: null` means unknown time.
+* Follow "Time order" below.
 * **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
@@ -332,6 +337,27 @@ 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
@@ -441,6 +467,81 @@ 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],
@@ -1399,6 +1500,7 @@ 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,
                 )
@@ -1412,9 +1514,10 @@ class MemoryReconciler:
                 logger.warning(
                     f"[reconciler] RECONCILE JSON parse failed "
                     f"(attempt {_attempt+1}/{_MAX_PARSE_ATTEMPTS}), "
-                    f"retrying: raw="
-                    f"{raw_response[:200] if _log_llm_content_enabled() else '<redacted>'}"
+                    f"retrying: raw({len(raw_response or '')} chars)"
                 )
+                if _log_llm_content_enabled():
+                    logger.debug(f"[reconciler] unparsable raw={raw_response[:200]!r}")
 
             recon_elapsed = (_time.perf_counter() - t_recon) * 1000
 
@@ -1426,8 +1529,8 @@ class MemoryReconciler:
                     error_code = "LLM_UNAVAILABLE"
                 elif raw_response.strip():
                     error_msg = (
-                        f"RECONCILE JSON parse failed after {_n_attempts} attempts: "
-                        f"{raw_response[:200] if _log_llm_content_enabled() else '<redacted>'}"
+                        f"RECONCILE JSON parse failed after {_n_attempts} attempts "
+                        f"({len(raw_response)} chars)"
                     )
                     error_code = "JSON_PARSE_FAILED"
                 else:
@@ -1704,7 +1807,8 @@ 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: {text[:200]}")
+                logger.warning(f"[reconciler] failed to parse ops JSON ({len(text)} chars)")
+                logger.debug(f"[reconciler] unparsable ops output: {text[:200]!r}")
                 return []
 
         if not isinstance(data, list):
@@ -1916,11 +2020,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} ({op.reason[:60]})' dropped"
+                        f"current op '{op.op}' dropped"
                     )
                     continue
                 for t in target_ids:
-                    touched[t] = f"{op.op}({op.reason[:40]})"
+                    touched[t] = op.op
             validated.append(op)
 
         return validated

hy_memory/agent/tools/base.py

@@ -211,7 +211,9 @@ 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: {args_raw[:120]}")
+                    logger.warning(
+                        f"[tools] failed to parse arguments as JSON ({len(args_raw)} chars)"
+                    )
                     args = {}
             elif isinstance(args_raw, dict):
                 args = args_raw

hy_memory/agent/tools/basic_profile.py

@@ -26,6 +26,8 @@ from __future__ import annotations
 
 import asyncio
 import logging
+import re
+import unicodedata
 import uuid
 import weakref
 from dataclasses import dataclass
@@ -208,6 +210,76 @@ def _sanitize_kv(
     return result
 
 
+# ================================================================
+# 占位符守卫（P0-1）
+# ================================================================
+# 弱模型（如 qwen3.5-2b）在用户什么都没说时，会把 schema 字段说明里的词当值
+# 填进 basic_info：{"name": "用户"} / "The user" / "N/A"。每个占位符都会
+# supersede 掉真实值，演化链变成 费天翔 → Fei → 用户 → The user。
+# 规则：占位符永远不入库；读侧组装 KV 时占位符也不覆盖已有真实值。
+
+_PLACEHOLDER_VALUES = frozenset({
+    "用户", "该用户", "本用户", "用户本人",
+    "the user", "the user's", "user", "a user", "this user",
+    "n/a", "na", "none", "null", "nil", "unknown", "unspecified",
+    "not provided", "not specified", "not mentioned",
+    "未提供", "未知", "不详", "未说明", "未提及", "无",
+    "-", "?",
+})
+
+# 内置字段的中文标签：弱模型也会把字段说明的中文词当值。
+_FIELD_LABELS: Dict[str, tuple] = {
+    "name": ("姓名", "名字", "用户名", "用户姓名", "用户名字"),
+    "age": ("年龄", "用户年龄"),
+    "location": ("所在地", "地点", "城市", "用户所在地"),
+    "occupation": ("职业", "工作", "用户职业"),
+    "employer": ("雇主", "公司", "用户雇主"),
+}
+
+# 去掉标点/符号后再比较，让 "The user." / "用户。" / "N/A" 都命中。
+# "-" / "?" 本身就是纯标点，剥完为空串，同样判为占位符。
+_PUNCT_RE = re.compile(r"[\s\.,;:!?'\"`~()\[\]{}<>/\\|_\-\u3000-\u303f\uff00-\uff0f\uff1a-\uff20]+")
+
+
+def _placeholder_key(value: str) -> str:
+    s = unicodedata.normalize("NFKC", str(value or "")).strip().lower()
+    s = s.replace("\u2019", "'")
+    s = _PUNCT_RE.sub(" ", s)
+    return " ".join(s.split())
+
+
+_PLACEHOLDER_KEYS = frozenset(_placeholder_key(v) for v in _PLACEHOLDER_VALUES)
+
+
+def is_placeholder_value(field_name: str, value: Any) -> bool:
+    """value 是否为占位符（空 / 用户 / The user / N/A / 字段名本身 等）。
+
+    大小写不敏感、首尾空白与标点不敏感。数字（如 age=30）永远不是占位符。
+    """
+    if value is None:
+        return True
+    if isinstance(value, bool):
+        return False
+    if isinstance(value, (int, float)):
+        return False
+    key = _placeholder_key(value)
+    if not key:
+        return True
+    if key in _PLACEHOLDER_KEYS:
+        return True
+    field_key = _placeholder_key(field_name)
+    if field_key and key in (field_key, field_key.replace("_", " ")):
+        return True
+    for label in _FIELD_LABELS.get(field_name, ()):
+        if key == _placeholder_key(label):
+            return True
+    return False
+
+
+def _drop_placeholders(kv: Dict[str, Any]) -> Dict[str, Any]:
+    return {k: v for k, v in kv.items() if not is_placeholder_value(k, v)}
+
+
 # ================================================================
 # 公共入口：upsert_basic_profile
 # ================================================================
@@ -287,6 +359,8 @@ async def _upsert_basic_profile_unlocked(
     # L0 Basic Info 从输入、唯一性到落盘都只属于 user_id。
 
     new_kv = _sanitize_kv(kv or {}, allowed_fields=allowed_fields)
+    # 单调性守卫：占位符永远不覆盖已有值，过滤后为空就不写新版本、不产生新链头。
+    new_kv = _drop_placeholders(new_kv)
     if not new_kv:
         return BasicProfileUpsertResult(
             success=True, changed=False, reason="no valid fields after sanitize"
@@ -513,5 +587,8 @@ def _assemble_full_kv_from_nodes(
         for k, v in kv.items():
             if allowed_set is not None and k not in allowed_set:
                 continue
+            # 历史上已落盘的占位符版本（如 name=用户）不覆盖更早的真实值。
+            if is_placeholder_value(k, v):
+                continue
             full_kv[k] = v
     return full_kv

hy_memory/coding/chain_store.py

@@ -647,7 +647,9 @@ class HyCodeMem:
         top-k，但它们的 diff 对当前工作区不可能有用，因此挂链前必须做同仓过滤。
         """
         facts = facts or []
-        # 开关: HCM_BLOCK_OFF=1 → 完全不出块, 也不从 bullet 删任何 fact。
+        # 高级消融开关: HCM_BLOCK_OFF=1 → 完全不出块, 也不从 bullet 删任何 fact。
+        # 公共 opt-in 见 CodingConfig.chain_block_enabled /
+        # MEMORY_CODING_CHAIN_BLOCK_ENABLED（默认关；客户端在调用 decorate 前拦截）。
         if os.environ.get("HCM_BLOCK_OFF") == "1":
             return "", []
         picked, used = [], []

hy_memory/coding/extractor.py

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

hy_memory/coding/fact_reconciler.py

@@ -454,9 +454,10 @@ 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 + 持久化。
+        执行 reconcile + 持久化。memory_at 是这段对话的时间，记到新事实上。
 
         Returns:
             (真正落库的新事实, 执行过的 ops)。LLM 挂掉时退化为全 INSERT 不覆盖，
@@ -466,7 +467,13 @@ class WorkingFactReconciler:
             return [], []
 
         candidates = await self._retrieve_candidates(
-            drafts, user_id=user_id, source=source,
+            drafts,
+            user_id=user_id,
+            agent_id=agent_id,
+            session_id=session_id,
+            workspace_id=workspace_id,
+            branch=branch,
+            source=source,
         )
 
         try:
@@ -487,6 +494,7 @@ 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)} "
@@ -499,7 +507,15 @@ class WorkingFactReconciler:
     # ------------------------------------------------------------
 
     async def _retrieve_candidates(
-        self, drafts: List[WorkingFactDraft], *, user_id: str, source: str
+        self,
+        drafts: List[WorkingFactDraft],
+        *,
+        user_id: str,
+        agent_id: str,
+        session_id: Optional[str],
+        workspace_id: Optional[str],
+        branch: Optional[str],
+        source: str,
     ) -> List[List[WorkingFact]]:
         """每条 draft 用 statement 召回同 user 的 top-N active 事实。
 
@@ -512,6 +528,10 @@ class WorkingFactReconciler:
         关掉时整份召回原样交给 LLM。适用于 subject 不是稳定实体名的数据集（自由文本、
         位置标签），那里精确字符串相等会把同实体判成不同主体，反而拦掉真实更新。
         """
+        # Empty/legacy session metadata remains readable, but cannot prove
+        # conversation authority for a destructive SUPERSEDE.
+        if not session_id:
+            return [[] for _ in drafts]
         try:
             embeddings = await self.embed_service.embed_batch(
                 [d.statement for d in drafts]
@@ -525,6 +545,10 @@ class WorkingFactReconciler:
             try:
                 hits = await self.store.search_facts(
                     emb, user_id=user_id, top=self.candidates_per_draft,
+                    agent_id=agent_id,
+                    session_id=session_id,
+                    workspace_id=workspace_id,
+                    branch=branch,
                     # 写入侧同样接词面通道：候选选错了 LLM 就没有机会判对。这里不传
                     # min_score——写入侧要的是"有哪些可能的前身"，让 LLM 看更宽的名单，
                     # 阈值过滤是读取侧的事。
@@ -546,9 +570,12 @@ class WorkingFactReconciler:
                     kept.append(fact)
             if blocked:
                 logger.info(
-                    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)
+                    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}"
                 )
             result.append(kept)
         return result
@@ -721,7 +748,10 @@ class WorkingFactReconciler:
                     obj = None
 
         if not isinstance(obj, dict):
-            logger.warning(f"[fact-reconcile] failed to parse ops output: {text!r}")
+            logger.warning(
+                f"[fact-reconcile] failed to parse ops output ({len(text or '')} chars)"
+            )
+            logger.debug(f"[fact-reconcile] unparsable ops output: {text!r}")
             return {}
         ops_raw = obj.get("ops")
         if not isinstance(ops_raw, list):
@@ -759,6 +789,7 @@ 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] = []
@@ -779,6 +810,7 @@ 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 [])}
@@ -794,14 +826,26 @@ class WorkingFactReconciler:
                 old = await self.store.get_fact(old_id, user_id=user_id)
                 if old is None:
                     continue
+                if (
+                    old.agent_id != agent_id
+                    or old.session_id != session_id
+                    or old.workspace_id != workspace_id
+                ):
+                    logger.warning(
+                        f"[fact-reconcile] refused cross-authority SUPERSEDE: {old.fact_id}"
+                    )
+                    continue
                 # 闸门在候选阶段已经拦过一道，这里再拦一次：候选是按 statement 召回的，
                 # 而 LLM 只能覆盖候选名单里的 id，理论上到不了这儿。真到了就说明前面
                 # 哪一环漏了，宁可让这次覆盖不生效——多留一条旧事实是可恢复的，删掉
                 # 别的主体的状态不是。闸门关掉时这道复查一并跳过，否则闸门就没关干净。
                 if self.subject_gate and _subject_conflict(draft.subject, old.subject):
                     logger.warning(
-                        f"[fact-reconcile] refused cross-subject SUPERSEDE: "
-                        f"{old.fact_id}({old.subject!r}) by draft subject {draft.subject!r}"
+                        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}"
                     )
                     continue
                 try:

hy_memory/coding/judge.py

@@ -195,8 +195,10 @@ 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: {resp.content!r}; defaulting to chat"
+                f"[coding-judge] failed to parse classify_messages output "
+                f"({len(resp.content or '')} chars); 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,
@@ -207,9 +209,8 @@ async def classify_messages_scene(
             return "chat"
         scene = result["scene"]
         parsed = {**result, "is_coding": scene != "chat"}
-        logger.info(
-            f"[coding-judge] scene={scene} reason={result.get('reason', '')!r}"
-        )
+        logger.info(f"[coding-judge] scene={scene}")
+        logger.debug(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,
@@ -295,8 +296,10 @@ 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: {resp.content!r}; defaulting to chat"
+                f"[coding-judge] failed to parse classify_queries output "
+                f"({len(resp.content or '')} chars); 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}")
@@ -422,15 +425,18 @@ 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={head!r}; falling back to chat"
+            f"[coding-judge] classify_and_rewrite unrecognized head "
+            f"({len(head)} chars); 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={rewrite!r}"
+        f"rewrite({len(rewrite)} chars)"
     )
+    logger.debug(f"[coding-judge] classify_and_rewrite rewrite={rewrite!r}")
     return {"scene": scene, "is_coding": is_coding, "rewrite_query": rewrite, "ok": True}
 
 
@@ -569,8 +575,9 @@ async def analyze_queries(
         parsed_scene = _parse_scene_label(head)
         if parsed_scene is None:
             logger.warning(
-                f"[coding-judge] analyze_queries unrecognized head={head!r}; ok=False"
+                f"[coding-judge] analyze_queries unrecognized head ({len(head)} chars); ok=False"
             )
+            logger.debug(f"[coding-judge] analyze_queries unrecognized head={head!r}")
             return {**fallback, "since_raw": ""}
         scene = parsed_scene
         idx = 1
@@ -589,9 +596,10 @@ async def analyze_queries(
     created_after = _since_to_created_after(since_raw, current_time)
 
     logger.info(
-        f"[coding-judge] analyze scene={scene} rewrite={rewrite!r} "
+        f"[coding-judge] analyze scene={scene} rewrite({len(rewrite)} chars) "
         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,
@@ -614,7 +622,10 @@ 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={since_raw!r}")
+    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}")
     return None
 
 

hy_memory/coding/preproc.py

@@ -11,6 +11,7 @@ Coding Memory 预处理工具（规则，零 LLM）
 使用方式与 scene 路由见 docs/scene_coding_usage.md。
 """
 
+import re
 from typing import Any, Dict, List, Optional, Tuple
 
 from ..pipelines.base import ChatMessage
@@ -63,6 +64,13 @@ DEFAULT_MAX_TOOL_RESULT_BYTES = 2048
 DEFAULT_HEAD_BYTES = 1024
 DEFAULT_TAIL_BYTES = 512
 
+# 本模块自己产出的省略标记。截断结果会再次经过截断（落库前一次、读历史时又一次），
+# 认出自己的标记才能保证幂等：已截断的文本再截一次原样返回，而不是把省略计数改写。
+_TOOL_OMIT_MARKER_RE = re.compile(r"\n\n\[\.\.\.\d+ bytes omitted by truncate\.\.\.\]\n\n")
+# 标记本身的字节数上限（数字位数有限），用于判断「已截断且只超出一个标记的长度」。
+_TOOL_OMIT_MARKER_MAX_BYTES = 128
+_ASSISTANT_OMIT_MARKER_RE = re.compile(r" \[\.\.\.\d+ chars omitted\.\.\.\] ")
+
 
 def truncate_tool_result_text(
     text: str,
@@ -81,6 +89,12 @@ def truncate_tool_result_text(
     raw = text.encode("utf-8")
     if len(raw) <= max_bytes:
         return text
+    # 已截断过（max_bytes 很小时标记本身会让结果略超上限）：原样返回，保证幂等。
+    if (
+        len(raw) <= max_bytes + _TOOL_OMIT_MARKER_MAX_BYTES
+        and _TOOL_OMIT_MARKER_RE.search(text)
+    ):
+        return text
     # 自定义 max_bytes 可能小于默认 head+tail（1024+512）。按原比例缩放内容窗口，
     # 给省略标记预留空间，不能因为窗口和过大而把超限原文直接返回。
     marker_budget = min(96, max(24, max_bytes // 4))
@@ -161,6 +175,10 @@ def truncate_assistant_text(
         text = "" if text is None else str(text)
     if len(text) <= head_chars + tail_chars:
         return text
+    # 已截断过：中段恰好是本函数的省略标记 → 原样返回，保证幂等（否则会把
+    # 省略计数改写成标记自身的长度）。
+    if _ASSISTANT_OMIT_MARKER_RE.fullmatch(text[head_chars:len(text) - tail_chars]):
+        return text
     omitted = len(text) - head_chars - tail_chars
     return (
         text[:head_chars]

hy_memory/coding/reconciler.py

@@ -240,7 +240,7 @@ class CodingMemoryReconciler:
         )
 
         # 3. 校验 + 执行
-        executed = await self._execute(ops, drafts)
+        executed = await self._execute(ops, drafts, candidates_per_draft)
         logger.info(
             f"[coding-reconcile] drafts={len(drafts)} ops={len(executed)} "
             + ", ".join(f"{a}={sum(1 for o in executed if o.action == a)}"
@@ -263,6 +263,12 @@ class CodingMemoryReconciler:
         """
         result: List[List[CodingMemory]] = []
         for d in drafts:
+            # A coding mutation must be attributable to one conversation.
+            # Empty/legacy session metadata stays readable through ordinary
+            # search, but it cannot authorize UPDATE/DELETE.
+            if not d.session_id:
+                result.append([])
+                continue
             try:
                 # task 为主入口，search_keys 为附加入口（去重、去空）
                 queries = [d.task] + [k for k in (d.search_keys or []) if k and k != d.task]
@@ -274,6 +280,8 @@ class CodingMemoryReconciler:
                     hits = await self.store.search_by_query_embedding(
                         emb,
                         user_id=d.user_id,
+                        agent_id=d.agent_id,
+                        session_id=d.session_id,
                         workspace_id=d.workspace_id,
                         branch=d.branch,
                         top=self.candidates_per_draft * 4,
@@ -380,7 +388,10 @@ class CodingMemoryReconciler:
                     obj = None
 
         if not obj or not isinstance(obj, dict):
-            logger.warning(f"[coding-reconcile] failed to parse ops output: {text!r}")
+            logger.warning(
+                f"[coding-reconcile] failed to parse ops output ({len(text or '')} chars)"
+            )
+            logger.debug(f"[coding-reconcile] unparsable ops output: {text!r}")
             return []
         ops_raw = obj.get("ops") or []
         if not isinstance(ops_raw, list):
@@ -415,6 +426,7 @@ class CodingMemoryReconciler:
         self,
         ops: List[ReconcileOp],
         drafts: List[CodingMemoryDraft],
+        candidates_per_draft: List[List[CodingMemory]],
     ) -> List[ReconcileOp]:
         """
         校验 + 执行 ops。返回成功执行的 ops（filter 掉无效 op）。
@@ -432,10 +444,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.to_dict()}")
+                    logger.warning(f"[coding-reconcile] drop invalid ADD: {_op_ref(op)}")
                     continue
                 if op.draft_idx in consumed:
-                    logger.warning(f"[coding-reconcile] drop ADD on consumed draft: {op.to_dict()}")
+                    logger.warning(f"[coding-reconcile] drop ADD on consumed draft: {_op_ref(op)}")
                     continue
                 d = drafts[op.draft_idx]
                 memory = self._draft_to_new_memory(d)
@@ -449,13 +461,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.to_dict()}")
+                    logger.warning(f"[coding-reconcile] drop invalid UPDATE: {_op_ref(op)}")
                     continue
                 if not op.target_experience_id:
-                    logger.warning(f"[coding-reconcile] drop UPDATE missing target: {op.to_dict()}")
+                    logger.warning(f"[coding-reconcile] drop UPDATE missing target: {_op_ref(op)}")
+                    continue
+                if not self._target_was_offered(op, candidates_per_draft):
+                    logger.warning(
+                        f"[coding-reconcile] drop UPDATE outside authority scope: {_op_ref(op)}"
+                    )
                     continue
                 if op.draft_idx in consumed:
-                    logger.warning(f"[coding-reconcile] drop UPDATE on consumed draft: {op.to_dict()}")
+                    logger.warning(f"[coding-reconcile] drop UPDATE on consumed draft: {_op_ref(op)}")
                     continue
                 d = drafts[op.draft_idx]
                 memory = self._draft_to_new_memory(d, experience_id=op.target_experience_id)
@@ -474,12 +491,17 @@ class CodingMemoryReconciler:
 
             elif op.action == "DELETE":
                 if not op.target_experience_id:
-                    logger.warning(f"[coding-reconcile] drop DELETE missing target: {op.to_dict()}")
+                    logger.warning(f"[coding-reconcile] drop DELETE missing target: {_op_ref(op)}")
+                    continue
+                if not self._target_was_offered(op, candidates_per_draft):
+                    logger.warning(
+                        f"[coding-reconcile] drop DELETE outside authority scope: {_op_ref(op)}"
+                    )
                     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.to_dict()}")
+                    logger.warning(f"[coding-reconcile] drop DELETE no user_id context: {_op_ref(op)}")
                     continue
                 try:
                     ok = await self.store.delete(op.target_experience_id, user_id=user_id)
@@ -512,6 +534,19 @@ class CodingMemoryReconciler:
 
         return executed
 
+    @staticmethod
+    def _target_was_offered(
+        op: ReconcileOp,
+        candidates_per_draft: List[List[CodingMemory]],
+    ) -> bool:
+        """Only mutate a target frozen into this draft's scoped candidate set."""
+        if op.draft_idx is None or not (0 <= op.draft_idx < len(candidates_per_draft)):
+            return False
+        return any(
+            candidate.experience_id == op.target_experience_id
+            for candidate in candidates_per_draft[op.draft_idx]
+        )
+
     @staticmethod
     def _infer_user_id(
         op: ReconcileOp, drafts: List[CodingMemoryDraft]
@@ -545,6 +580,7 @@ class CodingMemoryReconciler:
             confidence=d.confidence,
             source=d.source,
             extraction_source=d.extraction_source,
+            memory_at=d.memory_at,
         )
 
 
@@ -552,6 +588,14 @@ 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,6 +86,7 @@ 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
 );
@@ -109,6 +110,7 @@ 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 指向我）走这个索引，写演变总结时要顺着链往回走
@@ -164,6 +166,8 @@ _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 反查就有。老库里那一列留着不管，有默认值不影响插入。
@@ -177,6 +181,7 @@ _ADDED_COLUMNS = {
         "subject": "TEXT NOT NULL DEFAULT ''",
         "details": "TEXT NOT NULL DEFAULT ''",
         "source": "TEXT NOT NULL DEFAULT 'default'",
+        "memory_at": "INTEGER",
     },
 }
 
@@ -209,6 +214,29 @@ def _scope_where(
     return sql, params
 
 
+def _in_clause(column: str, values: Optional[List[str]]) -> Tuple[str, List[Any]]:
+    """SQL ``column IN (...)`` + parameters; empty values mean no condition."""
+    if not values:
+        return "", []
+    placeholders = ",".join("?" for _ in values)
+    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],
@@ -267,6 +295,29 @@ 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(
@@ -285,6 +336,7 @@ 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"]),
     )
@@ -311,6 +363,7 @@ 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"]),
     )
 
@@ -408,6 +461,36 @@ 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
@@ -522,18 +605,34 @@ class CodingMemoryStore:
         await self._upsert_vec_keys(memory)
         logger.info(
             f"[coding-store] inserted experience_id={memory.experience_id} "
-            f"task={memory.task!r} keys={1 + len(memory.search_keys)}"
+            f"keys={1 + len(memory.search_keys)}"
+        )
+        logger.debug(
+            f"[coding-store] inserted experience_id={memory.experience_id} "
+            f"task={memory.task!r}"
         )
 
     async def update(self, memory: CodingMemory) -> None:
         """覆盖式更新一条 coding memory。"""
         # 拿旧 keys 长度，先删旧 VDB rows
         prev = await self.get_by_id(memory.experience_id, user_id=memory.user_id)
-        prev_key_count = (1 + len(prev.search_keys)) if prev else 0
+        if prev is None:
+            raise ValueError("coding_memory_update_target_missing")
+        if (
+            not prev.session_id
+            or not memory.session_id
+            or prev.agent_id != memory.agent_id
+            or prev.session_id != memory.session_id
+            or prev.workspace_id != memory.workspace_id
+        ):
+            raise ValueError("coding_memory_update_authority_mismatch")
+        prev_key_count = 1 + len(prev.search_keys)
 
         memory.updated_at = datetime.utcnow()
-        if memory.created_at is None and prev is not None:
+        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)
@@ -555,6 +654,86 @@ 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
+
     # ------------------------------------------------------------
     # 读取
     # ------------------------------------------------------------
@@ -639,29 +818,84 @@ 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 倒序（最近修改优先）。
+        updated_at 倒序（最近修改优先）。include_sources / exclude_sources 按
+        source 列在 SQL 里过滤（排除优先），所以 LIMIT/OFFSET 在过滤之后生效。
         """
         return await _run_in_pool(
-            self._list_by_workspace_sync, user_id, workspace_id, branch, limit, offset
+            self._list_by_workspace_sync, user_id, workspace_id, branch, limit, offset,
+            include_sources, exclude_sources,
         )
 
     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"ORDER BY updated_at DESC LIMIT ? OFFSET ?")
-            params: List[Any] = [user_id] + scope_params + [limit, offset]
+                   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])
             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),
+        }
+
     # ------------------------------------------------------------
     # 召回
     # ------------------------------------------------------------
@@ -671,6 +905,10 @@ class CodingMemoryStore:
         query_embedding: List[float],
         user_id: str,
         *,
+        agent_id: Optional[str] = None,
+        session_id: Optional[str] = None,
+        agent_ids: Optional[List[str]] = None,
+        session_ids: Optional[List[str]] = None,
         workspace_id: Optional[str] = None,
         branch: Optional[str] = None,
         top: int = 40,
@@ -688,21 +926,34 @@ class CodingMemoryStore:
                 },
                 ...
             ]
-        workspace_id / branch 是作用域过滤，规则见 _scope_where：不传则纯语义召回
-        （行为与加过滤前完全一致）；传了则只保留 SQLite 里落在作用域内的经验，并按
-        作用域的选择率放大向量取数，避免"先取 top-N 再过滤"把召回吃掉。
+        agent_id / session_id（或 agent_ids / session_ids）是写授权作用域，
+        传入时精确匹配；workspace_id / branch 的规则见 _scope_where。
+        不传任何作用域则维持纯语义召回；传了则只保留 SQLite 里落在作用域内的经验，
+        并按选择率放大向量取数，避免"先取 top-N 再过滤"把召回吃掉。
         """
         if self._vec is None:
             return []
 
+        effective_agent_ids = list(agent_ids) if agent_ids else (
+            [agent_id] if agent_id else []
+        )
+        effective_session_ids = list(session_ids) if session_ids else (
+            [session_id] if session_id else []
+        )
         allowed: Optional[Set[str]] = None
-        if workspace_id:
+        if effective_agent_ids or effective_session_ids or workspace_id:
             allowed, total = await _run_in_pool(
-                self._scoped_experience_ids_sync, user_id, workspace_id, branch
+                self._authority_scoped_experience_ids_sync,
+                user_id,
+                effective_agent_ids,
+                effective_session_ids,
+                workspace_id,
+                branch,
             )
             if not allowed:
                 logger.info(
                     f"[coding-store] no experience in scope: "
+                    f"agent_id={agent_id!r} session_id={session_id!r} "
                     f"workspace_id={workspace_id!r} branch={branch!r} "
                     f"(user has {total}); skip vdb search"
                 )
@@ -755,7 +1006,8 @@ 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(
+        logger.info(f"[coding-store] inserted fact_id={fact.fact_id}")
+        logger.debug(
             f"[coding-store] inserted fact_id={fact.fact_id} "
             f"statement={fact.statement!r}"
         )
@@ -778,6 +1030,10 @@ class CodingMemoryStore:
         query_embedding: List[float],
         user_id: str,
         *,
+        agent_id: Optional[str] = None,
+        session_id: Optional[str] = None,
+        agent_ids: Optional[List[str]] = None,
+        session_ids: Optional[List[str]] = None,
         workspace_id: Optional[str] = None,
         branch: Optional[str] = None,
         top: int = 5,
@@ -791,8 +1047,9 @@ class CodingMemoryStore:
         SUPERSEDE 时向量行已被删掉，理论上召不到 superseded；这里再按 SQLite 的
         status 过一道，避免两边不一致时把过期结论放出去。
 
-        workspace_id / branch 是作用域过滤，规则见 _scope_where，语义与经验层一致：
-        不传不过滤，传了按 SQLite 里的值筛，并按选择率放大向量取数。
+        agent_id / session_id（或 agent_ids / session_ids）是写授权作用域，
+        传入时精确匹配；workspace_id / branch 的规则见 _scope_where。
+        不传任何作用域则不过滤，传了按 SQLite 里的值筛，并按选择率放大向量取数。
 
         向量库按 top 的 4 倍过采样：向量行和 SQLite 行不是一个事务里写的，中间挂掉
         就会留下"向量还在、SQLite 没了"的孤儿，软删时删向量失败也会留下 superseded
@@ -808,14 +1065,27 @@ class CodingMemoryStore:
         if self._fact_vec is None:
             return []
 
+        effective_agent_ids = list(agent_ids) if agent_ids else (
+            [agent_id] if agent_id else []
+        )
+        effective_session_ids = list(session_ids) if session_ids else (
+            [session_id] if session_id else []
+        )
         fetch = top * 4
-        if workspace_id:
+        if effective_agent_ids or effective_session_ids or workspace_id:
             scoped, total = await _run_in_pool(
-                self._count_active_facts_sync, user_id, workspace_id, branch
+                self._count_active_facts_sync,
+                user_id,
+                effective_agent_ids,
+                effective_session_ids,
+                workspace_id,
+                branch,
             )
             if not scoped:
                 logger.info(
                     f"[coding-store] no active fact in scope: "
+                    f"agent_ids={effective_agent_ids!r} "
+                    f"session_ids={effective_session_ids!r} "
                     f"workspace_id={workspace_id!r} branch={branch!r} "
                     f"(user has {total}); skip fact vdb search"
                 )
@@ -852,6 +1122,8 @@ class CodingMemoryStore:
         alive = [
             (f, scores[f.fact_id]) for f in facts
             if f.status == "active"
+            and (not effective_agent_ids or f.agent_id in effective_agent_ids)
+            and (not effective_session_ids or f.session_id in effective_session_ids)
             and _scope_matches(f.workspace_id, f.branch, workspace_id, branch)
         ]
         kept = [(f, s) for f, s in alive if s >= min_score]
@@ -964,8 +1236,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,
-                    created_at, updated_at
-                ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+                    memory_at, created_at, updated_at
+                ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
                 ON CONFLICT(experience_id) DO UPDATE SET
                     user_id         = excluded.user_id,
                     agent_id        = excluded.agent_id,
@@ -981,6 +1253,7 @@ class CodingMemoryStore:
                     confidence      = excluded.confidence,
                     source          = excluded.source,
                     extraction_source = excluded.extraction_source,
+                    memory_at       = excluded.memory_at,
                     updated_at      = excluded.updated_at
                 """,
                 (
@@ -991,6 +1264,7 @@ 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(),
                 ),
@@ -1003,6 +1277,14 @@ 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]:
@@ -1050,14 +1332,28 @@ class CodingMemoryStore:
             by_id = {r["experience_id"]: _row_to_memory(r) for r in rows}
             return [by_id[eid] for eid in experience_ids if eid in by_id]
 
-    def _scoped_experience_ids_sync(
-        self, user_id: str, workspace_id: str, branch: Optional[str]
+    def _authority_scoped_experience_ids_sync(
+        self,
+        user_id: str,
+        agent_ids: Optional[List[str]],
+        session_ids: Optional[List[str]],
+        workspace_id: Optional[str],
+        branch: Optional[str],
     ) -> Tuple[Set[str], int]:
-        """返回 (落在作用域内的 experience_id 集合, 该 user 的经验总数)。
+        """返回 (落在授权作用域内的 experience_id 集合, 该 user 的经验总数)。
 
         一次查询同时拿到过滤结果和选择率分母：前者供向量命中做交集，后者定放大倍数。
+        agent_ids / session_ids 为空表示该维度不筛；非空按 IN 精确匹配。
         """
         scope_sql, scope_params = _scope_where(workspace_id, branch)
+        agent_sql, agent_params = _in_clause("agent_id", agent_ids)
+        if agent_sql:
+            scope_sql = f"({agent_sql}) AND ({scope_sql})"
+            scope_params = [*agent_params, *scope_params]
+        session_sql, session_params = _in_clause("session_id", session_ids)
+        if session_sql:
+            scope_sql = f"({session_sql}) AND ({scope_sql})"
+            scope_params = [*session_params, *scope_params]
         with self._lock:
             assert self._conn is not None
             cur = self._conn.execute(
@@ -1069,13 +1365,27 @@ class CodingMemoryStore:
         return {r["experience_id"] for r in rows if r["in_scope"]}, len(rows)
 
     def _count_active_facts_sync(
-        self, user_id: str, workspace_id: str, branch: Optional[str]
+        self,
+        user_id: str,
+        agent_ids: Optional[List[str]],
+        session_ids: Optional[List[str]],
+        workspace_id: Optional[str],
+        branch: Optional[str],
     ) -> Tuple[int, int]:
         """返回 (作用域内 active 事实数, 该 user 的 active 事实总数)。
 
         事实层的过滤在 get_facts 拿到对象之后用 _scope_matches 做，这里只要选择率。
+        agent_ids / session_ids 为空表示该维度不筛；非空按 IN 精确匹配。
         """
         scope_sql, scope_params = _scope_where(workspace_id, branch)
+        agent_sql, agent_params = _in_clause("agent_id", agent_ids)
+        if agent_sql:
+            scope_sql = f"({agent_sql}) AND ({scope_sql})"
+            scope_params = [*agent_params, *scope_params]
+        session_sql, session_params = _in_clause("session_id", session_ids)
+        if session_sql:
+            scope_sql = f"({session_sql}) AND ({scope_sql})"
+            scope_params = [*session_params, *scope_params]
         with self._lock:
             assert self._conn is not None
             row = self._conn.execute(
@@ -1095,8 +1405,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, created_at
-                ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+                    status, fact_chain_summary, memory_at, created_at
+                ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
                 ON CONFLICT(fact_id) DO UPDATE SET
                     user_id                = excluded.user_id,
                     agent_id               = excluded.agent_id,
@@ -1111,7 +1421,8 @@ class CodingMemoryStore:
                     fact_link              = excluded.fact_link,
                     derived_experience_ids = excluded.derived_experience_ids,
                     status                 = excluded.status,
-                    fact_chain_summary     = excluded.fact_chain_summary
+                    fact_chain_summary     = excluded.fact_chain_summary,
+                    memory_at              = excluded.memory_at
                 """,
                 (
                     fact.fact_id, fact.user_id, fact.agent_id,
@@ -1124,6 +1435,7 @@ 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,6 +25,11 @@ 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 阶段输出）
 # ================================================================
@@ -53,6 +58,8 @@ 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
@@ -73,6 +80,7 @@ class CodingMemoryDraft:
             "files": list(self.files),
             "source": self.source,
             "extraction_source": self.extraction_source,
+            "memory_at": _epoch(self.memory_at),
         }
 
 
@@ -111,6 +119,9 @@ 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
 
@@ -135,6 +146,7 @@ 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,
         }
@@ -249,6 +261,7 @@ class WorkingFact:
     fact_chain_summary: str = ""
 
     # 时间
+    memory_at: Optional[datetime] = None   # 对话时间（同 chat），没传时是收到请求的时间
     created_at: Optional[datetime] = None  # 产生时间，新的优先
 
     def __post_init__(self) -> None:
@@ -272,6 +285,7 @@ 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,6 +18,7 @@ CodingWriter - 写入端协调器
 import logging
 import time
 import uuid
+from datetime import datetime
 from typing import Any, Dict, List, Optional
 
 from ..agent.llm_provider import LLMProvider
@@ -50,6 +51,7 @@ class CodingWriter:
         embed_service: EmbedService,
         fact_reconciler: Optional[WorkingFactReconciler] = None,
         cache: Any = None,
+        variant: str = "working",
     ):
         self.store = store
         self.extractor = extractor
@@ -59,6 +61,11 @@ 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
 
@@ -73,9 +80,11 @@ 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 段写入端到端。返回响应 dict（兼容 client.add 返回结构）：
+        working/coding 段写入端到端。memory_at 是对话时间，记到这次写出的经验和
+        事实上；不传则用收到请求的时间（与 chat 链路一致）。返回响应 dict（兼容 client.add 返回结构）：
             {
                 "success": True,
                 "scene": "productivity",
@@ -95,6 +104,8 @@ 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)
@@ -166,6 +177,7 @@ class CodingWriter:
         # extractor 只负责内容；调用来源由 SDK 入口注入，不能交给 LLM 生成。
         for draft in drafts:
             draft.source = source
+            draft.memory_at = memory_at
 
         # 3. 经验层 reconcile + 持久化
         ops: List[ReconcileOp] = (
@@ -191,6 +203,7 @@ class CodingWriter:
                 workspace_id=workspace_id,
                 branch=branch,
                 source=source,
+                memory_at=memory_at,
             )
 
         experience_ids = [op.target_experience_id for op in ops
@@ -217,6 +230,7 @@ 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],
@@ -278,11 +292,11 @@ class CodingWriter:
                         f"[coding-write] crosslink fact {f.fact_id} failed: {e}"
                     )
 
-    @staticmethod
-    def _empty_response(request_id: str, t0: float) -> Dict[str, Any]:
+    def _empty_response(self, 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/config.py

@@ -260,6 +260,7 @@ class EmbedderConfig:
     max_retries: int = None  # 最大重试次数
     retry_delay: float = None  # 重试间隔（秒）
     timeout: int = None  # 请求超时（秒）
+    batch_size: int = None  # 单次 HTTP 请求最多带多少条 input（embed_batch 按此切块）
 
     # 内部平台扩展（extra_headers / extra_body 会透传给 OpenAI client）
     extra_headers: Optional[Dict[str, str]] = None
@@ -294,6 +295,10 @@ class EmbedderConfig:
             # 请求切断并制造重试风暴。SDK 内层重试已关闭，15s 是每个显式 attempt
             # 的真实上限；部署可通过 MEMORY_EMBEDDER_TIMEOUT 覆盖。
             self.timeout = _get_env_int("MEMORY_EMBEDDER_TIMEOUT", 15)
+        if self.batch_size is None:
+            # 大批量（如重新 embed 整个库）不能一次 HTTP 发几千条：多数服务对
+            # input 数组有上限，超了直接 400。按 batch_size 切块逐块发送。
+            self.batch_size = _get_env_int("MEMORY_EMBEDDER_BATCH_SIZE", 64)
         if self.extra_headers is None:
             val = os.getenv("MEMORY_EMBEDDER_EXTRA_HEADERS")
             if val:
@@ -1136,6 +1141,9 @@ class CodingConfig:
     # LLM 失败或没有抽出 fact 时，是否把对话原文存成 working fact。
     # 默认关闭，避免 assistant/tool 轨迹以 statement 形式直接暴露给消费方。
     verbatim_fallback_enabled: bool = None
+    # search(scene="coding") 是否注入版本演进链块（diff / chain_block）。
+    # 默认关闭（opt-in）：中重度 coding 用户可省下大量 prompt token；写入侧仍可 observe。
+    chain_block_enabled: bool = None
 
     def __post_init__(self):
         if self.enable is None:
@@ -1153,6 +1161,10 @@ class CodingConfig:
             self.verbatim_fallback_enabled = _get_env_bool(
                 "MEMORY_CODING_VERBATIM_FALLBACK_ENABLED", False
             )
+        if self.chain_block_enabled is None:
+            self.chain_block_enabled = _get_env_bool(
+                "MEMORY_CODING_CHAIN_BLOCK_ENABLED", False
+            )
 
 
 @dataclass

hy_memory/core/embed_service.py

@@ -38,10 +38,12 @@ import importlib.util
 import json
 from json import JSONDecodeError
 import logging
+import random
 import threading
 import time
 
 from ..config import MemoryConfig
+from ..embedding import EmbeddingDimensionMismatchError
 from .workload import embedding_slot
 from ..utils.log_setup import get_request_id
 
@@ -80,7 +82,7 @@ def _count_tokens(text: str) -> int:
     try:
         import tiktoken
 
-        return len(tiktoken.get_encoding("cl100k_base").encode(text))
+        return len(tiktoken.get_encoding("cl100k_base").encode(text, disallowed_special=()))
     except Exception:
         return len(text) // _CHARS_PER_TOKEN_FALLBACK + 1
 
@@ -98,7 +100,8 @@ def _truncate_for_embedding(text: str, limit: int = _EMBED_MAX_TOKENS) -> str:
         import tiktoken
 
         enc = tiktoken.get_encoding("cl100k_base")
-        ids = enc.encode(text)
+        # Input is ordinary user text, not a tokenizer control-token stream.
+        ids = enc.encode(text, disallowed_special=())
         if len(ids) <= limit:
             return text
         dropped = len(ids) - limit
@@ -186,6 +189,41 @@ def _redact_headers(headers: Optional[Dict[str, Any]]) -> Optional[Dict[str, Any
     return out
 
 
+# Retry-After 的上限：服务端给出超长等待（或恶意值）时不让单次调用挂几十分钟。
+_RETRY_AFTER_MAX_S = 60.0
+
+
+def _retry_after_seconds(exc: Exception) -> Optional[float]:
+    """从 429 异常的响应头里取 Retry-After（秒数或 HTTP 日期），取不到返回 None。"""
+    response = getattr(exc, "response", None)
+    headers = getattr(response, "headers", None)
+    if not headers:
+        return None
+    try:
+        raw = headers.get("retry-after") or headers.get("Retry-After")
+    except Exception:
+        return None
+    if raw is None:
+        return None
+    raw = str(raw).strip()
+    try:
+        seconds = float(raw)
+    except ValueError:
+        try:
+            from email.utils import parsedate_to_datetime
+            from datetime import datetime, timezone
+
+            when = parsedate_to_datetime(raw)
+            if when.tzinfo is None:
+                when = when.replace(tzinfo=timezone.utc)
+            seconds = (when - datetime.now(timezone.utc)).total_seconds()
+        except Exception:
+            return None
+    if seconds != seconds:  # NaN
+        return None
+    return min(max(0.0, seconds), _RETRY_AFTER_MAX_S)
+
+
 def _embeddings_api_url(base_url: str) -> str:
     """OpenAI SDK posts to ``{base_url}/embeddings`` (base_url usually ends with /v1)."""
     base = (base_url or "").rstrip("/")
@@ -204,7 +242,8 @@ class EmbedServiceConfig:
     api_key: str = ""
     base_url: str = ""
     embedding_dims: int = 1536
-    batch_size: int = 100
+    # embed_batch 单次 HTTP 最多带多少条 input；超出按块顺序发送
+    batch_size: int = 64
     enable_cache: bool = True
     cache_size: int = 10000
     max_retries: int = 5
@@ -286,6 +325,7 @@ class EmbedService:
             max_retries=embedder.max_retries if embedder.max_retries is not None else 5,
             retry_delay=embedder.retry_delay if embedder.retry_delay is not None else 3.0,
             timeout=embedder.timeout if embedder.timeout is not None else 60,
+            batch_size=max(1, int(getattr(embedder, "batch_size", None) or 64)),
             queue_batch_size=int(os.getenv("MEMORY_EMBED_BATCH_SIZE", "8")),
             queue_batch_window_ms=float(os.getenv("MEMORY_EMBED_BATCH_WINDOW_MS", "100")),
             extra_headers=embedder.extra_headers,
@@ -639,6 +679,8 @@ class EmbedService:
         self,
         texts: List[str],
         use_cache: bool = True,
+        *,
+        max_retries: Optional[int] = None,
     ) -> List[List[float]]:
         """
         批量向量化
@@ -646,17 +688,23 @@ class EmbedService:
         Args:
             texts: 文本列表
             use_cache: 是否使用缓存
+            max_retries: 本次调用的重试次数；None 用配置值。长批量任务（重新
+                embed 整个库）可以给更宽的重试预算，不影响在线路径。
         
         Returns:
             向量列表
         """
-        vectors, _metas = await self.embed_batch_with_meta(texts, use_cache=use_cache)
+        vectors, _metas = await self.embed_batch_with_meta(
+            texts, use_cache=use_cache, max_retries=max_retries,
+        )
         return vectors
 
     async def embed_batch_with_meta(
         self,
         texts: List[str],
         use_cache: bool = True,
+        *,
+        max_retries: Optional[int] = None,
     ) -> Tuple[List[List[float]], List[Dict[str, Any]]]:
         """批量向量化，同时返回每条的 provider metadata（非 vector）。"""
         if not texts:
@@ -681,7 +729,12 @@ class EmbedService:
             indices_to_embed.append(i)
 
         if texts_to_embed:
-            vectors, batch_metas = await self._embed_texts_with_meta(texts_to_embed)
+            # max_retries 只在显式给出时透传：保持 `_embed_texts_with_meta(texts)`
+            # 这个既有调用形状不变（测试与下游替身按它打桩）。
+            retry_kwargs = {} if max_retries is None else {"max_retries": max_retries}
+            vectors, batch_metas = await self._embed_texts_with_meta(
+                texts_to_embed, **retry_kwargs,
+            )
 
             for j, vector in enumerate(vectors):
                 idx = indices_to_embed[j]
@@ -699,9 +752,9 @@ class EmbedService:
         return results, metas
     
     async def _embed_texts_with_meta(
-        self, texts: List[str]
+        self, texts: List[str], *, max_retries: Optional[int] = None,
     ) -> Tuple[List[List[float]], List[Dict[str, Any]]]:
-        """实际的向量化调用：**一次 HTTP 带走整批**；返回 (vectors, metas)。
+        """实际的向量化调用：**一次 HTTP 带走一块**；返回 (vectors, metas)。
 
         早期实现是 `for text in texts: await _embed_openai([text])` 逐条串行，
         原意是"避免 batch size 限制"，但代价极大：线上一批 8 条 × ~5.6s 串行
@@ -718,21 +771,34 @@ class EmbedService:
         截断在这里做（发送前逐条过 `_truncate_for_embedding`）：所有 embedding
         路径（embed / embed_batch / embed_queued / *_with_meta）最终都落到这个
         方法 —— 放在各入口会漏。理由与阈值见模块头部 `_EMBED_MAX_TOKENS`。
+
+        切块：一次带走整批只适用于小批。几千条的 input 数组会被多数服务直接
+        400（input 上限），所以按 `batch_size`（默认 64）切块，块之间顺序发送。
+        不超过一块时行为与切块前逐字相同（`batch_mode="single_request"`）。
         """
         if not texts:
             return [], []
 
         safe_texts = [_truncate_for_embedding(t) for t in texts]
-        vectors, meta = await self._embed_openai(safe_texts)
-        base_meta = dict(meta or {})
-        base_meta["batch_mode"] = "single_request"
-        base_meta["batch_input_count"] = len(safe_texts)
-
+        chunk = max(1, int(self._embed_config.batch_size or 64))
+        vectors: List[List[float]] = []
         all_metas: List[Dict[str, Any]] = []
-        for idx in range(len(safe_texts)):
-            m = dict(base_meta)
-            m["batch_index"] = idx
-            all_metas.append(m)
+        chunk_count = (len(safe_texts) + chunk - 1) // chunk
+        for start in range(0, len(safe_texts), chunk):
+            part = safe_texts[start:start + chunk]
+            retry_kwargs = {} if max_retries is None else {"max_retries": max_retries}
+            part_vectors, meta = await self._embed_openai(part, **retry_kwargs)
+            base_meta = dict(meta or {})
+            base_meta["batch_mode"] = "single_request" if chunk_count == 1 else "chunked"
+            base_meta["batch_input_count"] = len(part)
+            if chunk_count > 1:
+                base_meta["batch_chunk_index"] = start // chunk
+                base_meta["batch_chunk_count"] = chunk_count
+            for idx in range(len(part)):
+                m = dict(base_meta)
+                m["batch_index"] = start + idx
+                all_metas.append(m)
+            vectors.extend(part_vectors)
 
         self._last_embed_meta = all_metas[-1] if all_metas else {}
         return vectors, all_metas
@@ -753,16 +819,22 @@ class EmbedService:
         """
         打一条 INFO 级 embedding 请求日志（含 request_id / provider / model / api / 入参 / 出参）。
 
-        出参只含 vector 维度，不含向量数值。request_id 同时写入 message，
+        出参只含 vector 维度，不含向量数值。入参的 input 是待向量化的原文
+        （对话 / 记忆 / 查询），INFO 只记每条的字符数（input_chars），原文仅在
+        DEBUG 单独输出。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": request_payload,
+            "request": info_request,
             "response": response_payload,
         }
         try:
@@ -770,9 +842,13 @@ 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]
+        self, texts: List[str], *, max_retries: Optional[int] = None,
     ) -> Tuple[List[List[float]], Dict[str, Any]]:
         """
         使用 OpenAI 兼容接口向量化
@@ -862,7 +938,9 @@ class EmbedService:
             "endpoint_overridden": bool(_ov),
         }
 
-        _max_retries = max(0, int(self._embed_config.max_retries or 0))
+        _max_retries = max(0, int(
+            (self._embed_config.max_retries or 0) if max_retries is None else max_retries
+        ))
         _retry_delay = max(0.0, float(self._embed_config.retry_delay or 0.0))
         last_exc: Optional[Exception] = None
 
@@ -908,6 +986,17 @@ class EmbedService:
                         f"got={len(vectors)}"
                     )
                 dims = [len(v) for v in vectors]
+                expected_dims = self._embed_config.embedding_dims
+                if expected_dims:
+                    bad = [d for d in dims if d != int(expected_dims)]
+                    if bad:
+                        # 宽度不对的向量写进集合会把集合的维度钉死在错误值上（Chroma
+                        # 首次 add 定维），或在已有集合上整批失败。确定性错误，不重试。
+                        raise EmbeddingDimensionMismatchError(
+                            "embedding dimension mismatch: "
+                            f"expected={int(expected_dims)} got={bad[0]} "
+                            f"model={self._embed_config.model}"
+                        )
                 meta = {
                     "http_status": raw.status_code,
                     "response_headers": resp_headers,
@@ -943,6 +1032,8 @@ class EmbedService:
                     },
                 )
                 return vectors, meta
+            except EmbeddingDimensionMismatchError:
+                raise
             except Exception as e:
                 last_exc = e
                 _err_name = type(e).__name__
@@ -976,12 +1067,18 @@ class EmbedService:
                 if _retryable and attempt < _max_retries:
                     # 逐出可能卡死的 client,下个 attempt 重建干净连接(恢复原防御语义)
                     self._evict_client(_eff_base_url, _eff_api_key, _eff_timeout)
+                    _delay = _retry_delay
+                    _retry_after = _retry_after_seconds(e) if _status == 429 else None
+                    if _retry_after is not None:
+                        # 限流时服务端明确告诉了要等多久：按它等，再加一点抖动，
+                        # 避免多个 worker 在同一时刻一起醒来再次撞限流。
+                        _delay = max(_delay, _retry_after) + random.uniform(0, 0.25 * _retry_after)
                     logger.warning(
                         f"[embed] attempt {attempt + 1}/{_max_retries + 1} failed "
-                        f"({_err_name}): {_err_msg[:200]}; retry in {_retry_delay}s"
+                        f"({_err_name}): {_err_msg[:200]}; retry in {_delay:.2f}s"
                     )
-                    if _retry_delay > 0:
-                        await asyncio.sleep(_retry_delay)
+                    if _delay > 0:
+                        await asyncio.sleep(_delay)
                     continue
                 self._log_embed_call(
                     status="error",

hy_memory/data/cache_base.py

@@ -114,6 +114,37 @@ class CacheBase(ABC):
         """查询 pipeline 中间结果日志"""
         ...
 
+    # ================================================================
+    # Durable write outcomes
+    # ================================================================
+
+    @abstractmethod
+    async def claim_write_outcome(
+        self,
+        request_id: str,
+        user_id: str,
+        agent_id: str,
+        session_id: str,
+        operation: str,
+    ) -> Optional[Dict[str, Any]]:
+        """Claim one idempotent write; return the existing row if already claimed."""
+        ...
+
+    @abstractmethod
+    async def finish_write_outcome(
+        self,
+        request_id: str,
+        status: str,
+        result: Dict[str, Any],
+    ) -> bool:
+        """Persist the terminal/unknown result for a claimed write."""
+        ...
+
+    @abstractmethod
+    async def get_write_outcome(self, request_id: str) -> Optional[Dict[str, Any]]:
+        """Read one durable write outcome by exact request id."""
+        ...
+
     # ================================================================
     # Summary Buffer（rolling summary 的未消费 turn 暂存）
     #

hy_memory/data/cache_mysql.py

@@ -81,6 +81,21 @@ _CREATE_TABLES_SQL = [
     )
     """,
     """
+    CREATE TABLE IF NOT EXISTS write_outcomes (
+        request_id VARCHAR(256) NOT NULL,
+        user_id    VARCHAR(255) NOT NULL,
+        agent_id   VARCHAR(255) NOT NULL DEFAULT '',
+        session_id VARCHAR(255) NOT NULL DEFAULT '',
+        operation  VARCHAR(32) NOT NULL,
+        status     VARCHAR(32) NOT NULL,
+        result_json LONGTEXT NOT NULL,
+        created_at VARCHAR(64) NOT NULL,
+        updated_at VARCHAR(64) NOT NULL,
+        PRIMARY KEY (request_id),
+        KEY idx_write_outcomes_owner (user_id, agent_id, session_id)
+    ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4
+    """,
+    """
     CREATE TABLE IF NOT EXISTS system_metrics (
         minute_ts   VARCHAR(32) NOT NULL,
         data        LONGTEXT NOT NULL,
@@ -459,29 +474,128 @@ class MysqlCache(CacheBase):
             logger.warning(f"get_pipeline_logs failed: {e}")
             return []
 
+    async def claim_write_outcome(
+        self,
+        request_id: str,
+        user_id: str,
+        agent_id: str,
+        session_id: str,
+        operation: str,
+    ) -> Optional[Dict[str, Any]]:
+        now = datetime.now().isoformat()
+        inserted = await self._execute(
+            """
+            INSERT IGNORE INTO write_outcomes (
+                request_id, user_id, agent_id, session_id, operation,
+                status, result_json, created_at, updated_at
+            ) VALUES (%s, %s, %s, %s, %s, 'running', '{}', %s, %s)
+            """,
+            (request_id, user_id, agent_id, session_id, operation, now, now),
+        )
+        if inserted == 1:
+            return None
+        return await self.get_write_outcome(request_id)
+
+    async def finish_write_outcome(
+        self,
+        request_id: str,
+        status: str,
+        result: Dict[str, Any],
+    ) -> bool:
+        updated = await self._execute(
+            """
+            UPDATE write_outcomes
+            SET status = %s, result_json = %s, updated_at = %s
+            WHERE request_id = %s
+            """,
+            (
+                status,
+                json.dumps(result, ensure_ascii=False, default=str),
+                datetime.now().isoformat(),
+                request_id,
+            ),
+        )
+        return updated == 1
+
+    async def get_write_outcome(self, request_id: str) -> Optional[Dict[str, Any]]:
+        row = await self._fetchone(
+            "SELECT * FROM write_outcomes WHERE request_id = %s",
+            (request_id,),
+        )
+        if row is None:
+            return None
+        try:
+            row["result"] = json.loads(row.pop("result_json") or "{}")
+        except (TypeError, json.JSONDecodeError):
+            row["result"] = {}
+        return row
+
     # ================================================================
     # System Metrics（分钟粒度落盘）
     # ================================================================
 
     async def store_metrics_minute(self, minute_ts: str, data: dict) -> None:
+        import aiomysql
+
         try:
             now = datetime.now().isoformat()
-            # 尝试 UPSERT
-            existing = await self._fetchone(
-                "SELECT data FROM system_metrics WHERE minute_ts = %s", (minute_ts,)
-            )
-            if existing:
-                old_data = json.loads(existing["data"])
-                merged = self._merge_metric_buckets(old_data, data)
-                await self._execute(
-                    "UPDATE system_metrics SET data = %s, created_at = %s WHERE minute_ts = %s",
-                    (json.dumps(merged, default=str), now, minute_ts),
-                )
-            else:
-                await self._execute(
-                    "INSERT INTO system_metrics (minute_ts, data, created_at) VALUES (%s, %s, %s)",
-                    (minute_ts, json.dumps(data, default=str), now),
-                )
+            # Read-merge-write must be one transaction: two instances flushing
+            # the same minute used to overwrite each other's counters, and a
+            # concurrent insert could lose the whole batch to a duplicate key.
+            for attempt in range(2):
+                try:
+                    async with self._pool.acquire() as conn:
+                        await conn.begin()
+                        try:
+                            async with conn.cursor(aiomysql.DictCursor) as cur:
+                                await cur.execute(
+                                    "SELECT data FROM system_metrics "
+                                    "WHERE minute_ts = %s FOR UPDATE",
+                                    (minute_ts,),
+                                )
+                                row = await cur.fetchone()
+                                if row is not None:
+                                    old_raw = (
+                                        row["data"]
+                                        if isinstance(row, dict)
+                                        else row[0]
+                                    )
+                                    merged = self._merge_metric_buckets(
+                                        json.loads(old_raw), data,
+                                    )
+                                    await cur.execute(
+                                        "UPDATE system_metrics SET data = %s, "
+                                        "created_at = %s WHERE minute_ts = %s",
+                                        (
+                                            json.dumps(merged, default=str),
+                                            now,
+                                            minute_ts,
+                                        ),
+                                    )
+                                else:
+                                    await cur.execute(
+                                        "INSERT INTO system_metrics "
+                                        "(minute_ts, data, created_at) "
+                                        "VALUES (%s, %s, %s)",
+                                        (
+                                            minute_ts,
+                                            json.dumps(data, default=str),
+                                            now,
+                                        ),
+                                    )
+                            await conn.commit()
+                            return
+                        except Exception:
+                            await conn.rollback()
+                            raise
+                except (aiomysql.IntegrityError, aiomysql.OperationalError) as error:
+                    code = error.args[0] if error.args else None
+                    deadlock = code in (1205, 1213)
+                    if attempt or (isinstance(error, aiomysql.OperationalError) and not deadlock):
+                        raise
+                    # A competing writer inserted the row, or InnoDB chose us
+                    # as the deadlock victim. Retry so this batch merges.
+                    continue
         except Exception as e:
             logger.warning(f"store_metrics_minute failed: {e}")
 

hy_memory/data/cache_sqlite.py

@@ -7,7 +7,7 @@ Agent Memory V2 - SqliteCache
 设计模式跟随 history_store.py:
 - 标准库 sqlite3 + _run_in_sqlite_pool()
 - WAL 模式 + check_same_thread=False
-- threading.Lock 保护写操作
+- 每实例 threading.RLock 保护共享连接的全部操作与关闭
 
 三张表:
 - memory_operations / pipeline_logs / system_metrics: 审计与观测
@@ -87,6 +87,20 @@ CREATE TABLE IF NOT EXISTS pipeline_logs_v2 (
 CREATE INDEX IF NOT EXISTS idx_plog_request ON pipeline_logs_v2(request_id);
 CREATE INDEX IF NOT EXISTS idx_plog_user    ON pipeline_logs_v2(user_id);
 
+CREATE TABLE IF NOT EXISTS write_outcomes (
+    request_id   TEXT PRIMARY KEY,
+    user_id      TEXT NOT NULL,
+    agent_id     TEXT NOT NULL DEFAULT '',
+    session_id   TEXT NOT NULL DEFAULT '',
+    operation    TEXT NOT NULL,
+    status       TEXT NOT NULL,
+    result_json  TEXT NOT NULL DEFAULT '{}',
+    created_at   TEXT NOT NULL,
+    updated_at   TEXT NOT NULL
+);
+CREATE INDEX IF NOT EXISTS idx_write_outcomes_owner
+ON write_outcomes(user_id, agent_id, session_id);
+
 CREATE TABLE IF NOT EXISTS system_metrics (
     minute_ts  TEXT PRIMARY KEY,
     data       TEXT NOT NULL,
@@ -122,7 +136,10 @@ class SqliteCache(CacheBase):
     def __init__(self, config: MemoryConfig):
         self.config = config
         self._conn: Optional[sqlite3.Connection] = None
-        self._lock = threading.Lock()
+        # One connection is shared by the executor workers. Use the same lock
+        # for reads, writes, initialization and close so close() cannot free
+        # the connection while another worker is inside sqlite3.
+        self._lock = threading.RLock()
 
         # 读取 db_path
         cache_cfg = getattr(config, "cache", None)
@@ -144,35 +161,37 @@ class SqliteCache(CacheBase):
         logger.debug(f"SqliteCache initialized: {self._db_path}")
 
     def _init_sync(self) -> None:
-        db_dir = os.path.dirname(self._db_path)
-        if db_dir:
-            os.makedirs(db_dir, exist_ok=True)
-        self._conn = sqlite3.connect(self._db_path, check_same_thread=False)
-        self._conn.row_factory = sqlite3.Row
-        self._conn.execute("PRAGMA journal_mode=WAL;")
-        self._conn.executescript(_CREATE_TABLES_SQL)
-        self._migrate_pipeline_logs_columns()
-        self._conn.commit()
+        with self._lock:
+            db_dir = os.path.dirname(self._db_path)
+            if db_dir:
+                os.makedirs(db_dir, exist_ok=True)
+            self._conn = sqlite3.connect(self._db_path, check_same_thread=False)
+            self._conn.row_factory = sqlite3.Row
+            self._conn.execute("PRAGMA journal_mode=WAL;")
+            self._conn.executescript(_CREATE_TABLES_SQL)
+            self._migrate_pipeline_logs_columns()
+            self._conn.commit()
 
     def _migrate_pipeline_logs_columns(self) -> None:
         """给旧库的 pipeline_logs_v2 补 namespace/session/event time 列。"""
-        try:
-            cols = {
-                row["name"]
-                for row in self._conn.execute("PRAGMA table_info(pipeline_logs_v2)")
-            }
-            _text_cols = ("namespace", "session_id")
-            for col in _text_cols:
-                if col not in cols:
+        with self._lock:
+            try:
+                cols = {
+                    row["name"]
+                    for row in self._conn.execute("PRAGMA table_info(pipeline_logs_v2)")
+                }
+                _text_cols = ("namespace", "session_id")
+                for col in _text_cols:
+                    if col not in cols:
+                        self._conn.execute(
+                            f"ALTER TABLE pipeline_logs_v2 ADD COLUMN {col} TEXT NOT NULL DEFAULT ''"
+                        )
+                if "event_at_ms" not in cols:
                     self._conn.execute(
-                        f"ALTER TABLE pipeline_logs_v2 ADD COLUMN {col} TEXT NOT NULL DEFAULT ''"
+                        "ALTER TABLE pipeline_logs_v2 ADD COLUMN event_at_ms INTEGER NOT NULL DEFAULT 0"
                     )
-            if "event_at_ms" not in cols:
-                self._conn.execute(
-                    "ALTER TABLE pipeline_logs_v2 ADD COLUMN event_at_ms INTEGER NOT NULL DEFAULT 0"
-                )
-        except Exception as e:
-            logger.debug(f"[sqlite] pipeline_logs_v2 column migration skipped: {e}")
+            except Exception as e:
+                logger.debug(f"[sqlite] pipeline_logs_v2 column migration skipped: {e}")
 
     async def close(self) -> None:
         if self._conn is not None:
@@ -180,9 +199,10 @@ class SqliteCache(CacheBase):
         logger.info("SqliteCache closed")
 
     def _close_sync(self) -> None:
-        if self._conn:
-            self._conn.close()
-            self._conn = None
+        with self._lock:
+            if self._conn:
+                self._conn.close()
+                self._conn = None
 
     # ================================================================
     # 统计
@@ -255,39 +275,40 @@ class SqliteCache(CacheBase):
         """
         try:
             def _query():
-                conditions = []
-                params = []
-                if request_id:
-                    conditions.append("request_id = ?")
-                    params.append(request_id)
-                if memory_id:
-                    conditions.append("memory_id = ?")
-                    params.append(memory_id)
-                if user_id:
-                    conditions.append("user_id = ?")
-                    params.append(user_id)
+                with self._lock:
+                    conditions = []
+                    params = []
+                    if request_id:
+                        conditions.append("request_id = ?")
+                        params.append(request_id)
+                    if memory_id:
+                        conditions.append("memory_id = ?")
+                        params.append(memory_id)
+                    if user_id:
+                        conditions.append("user_id = ?")
+                        params.append(user_id)
 
-                if not conditions:
-                    return []
+                    if not conditions:
+                        return []
 
-                where = " AND ".join(conditions)
-                rows = self._conn.execute(
-                    f"SELECT * FROM memory_operations_v2 WHERE {where} "
-                    f"ORDER BY id DESC LIMIT ?",
-                    params + [limit],
-                ).fetchall()
-                result = []
-                for r in rows:
-                    row = dict(r)
-                    # 反序列化 supersedes JSON 字符串 → list
-                    import json as _json
-                    raw_sup = row.get("supersedes", "")
-                    try:
-                        row["supersedes"] = _json.loads(raw_sup) if raw_sup else []
-                    except Exception:
-                        row["supersedes"] = []
-                    result.append(row)
-                return result
+                    where = " AND ".join(conditions)
+                    rows = self._conn.execute(
+                        f"SELECT * FROM memory_operations_v2 WHERE {where} "
+                        f"ORDER BY id DESC LIMIT ?",
+                        params + [limit],
+                    ).fetchall()
+                    result = []
+                    for r in rows:
+                        row = dict(r)
+                        # 反序列化 supersedes JSON 字符串 → list
+                        import json as _json
+                        raw_sup = row.get("supersedes", "")
+                        try:
+                            row["supersedes"] = _json.loads(raw_sup) if raw_sup else []
+                        except Exception:
+                            row["supersedes"] = []
+                        result.append(row)
+                    return result
 
             return await _run_in_sqlite_pool(_query)
         except Exception as e:
@@ -369,43 +390,126 @@ class SqliteCache(CacheBase):
         """
         try:
             def _query():
-                conditions = []
-                params = []
-                if request_id:
-                    conditions.append("request_id = ?")
-                    params.append(request_id)
-                if user_id:
-                    conditions.append("user_id = ?")
-                    params.append(user_id)
-                if step:
-                    conditions.append("step = ?")
-                    params.append(step)
+                with self._lock:
+                    conditions = []
+                    params = []
+                    if request_id:
+                        conditions.append("request_id = ?")
+                        params.append(request_id)
+                    if user_id:
+                        conditions.append("user_id = ?")
+                        params.append(user_id)
+                    if step:
+                        conditions.append("step = ?")
+                        params.append(step)
 
-                if not conditions:
-                    return []
+                    if not conditions:
+                        return []
 
-                where = " AND ".join(conditions)
-                rows = self._conn.execute(
-                    f"SELECT * FROM pipeline_logs_v2 WHERE {where} "
-                    f"ORDER BY id ASC LIMIT ?",
-                    params + [limit],
-                ).fetchall()
-                out = [dict(r) for r in rows]
-                # 派生可读的 event_at（ISO ms）供查询接口直接用；event_at_ms 为 0 时留空
-                from datetime import datetime as _dt
-                for _r in out:
-                    _ms = _r.get("event_at_ms") or 0
-                    _r["event_at"] = (
-                        _dt.fromtimestamp(_ms / 1000.0).isoformat(timespec="milliseconds")
-                        if _ms else ""
-                    )
-                return out
+                    where = " AND ".join(conditions)
+                    rows = self._conn.execute(
+                        f"SELECT * FROM pipeline_logs_v2 WHERE {where} "
+                        f"ORDER BY id ASC LIMIT ?",
+                        params + [limit],
+                    ).fetchall()
+                    out = [dict(r) for r in rows]
+                    # 派生可读的 event_at（ISO ms）供查询接口直接用；event_at_ms 为 0 时留空
+                    from datetime import datetime as _dt
+                    for _r in out:
+                        _ms = _r.get("event_at_ms") or 0
+                        _r["event_at"] = (
+                            _dt.fromtimestamp(_ms / 1000.0).isoformat(timespec="milliseconds")
+                            if _ms else ""
+                        )
+                    return out
 
             return await _run_in_sqlite_pool(_query)
         except Exception as e:
             logger.warning(f"get_pipeline_logs failed: {e}")
             return []
 
+    # ================================================================
+    # Durable write outcomes
+    # ================================================================
+
+    async def claim_write_outcome(
+        self,
+        request_id: str,
+        user_id: str,
+        agent_id: str,
+        session_id: str,
+        operation: str,
+    ) -> Optional[Dict[str, Any]]:
+        def _claim():
+            with self._lock:
+                now = datetime.now().isoformat()
+                cursor = self._conn.execute(
+                    """
+                    INSERT OR IGNORE INTO write_outcomes (
+                        request_id, user_id, agent_id, session_id, operation,
+                        status, result_json, created_at, updated_at
+                    ) VALUES (?, ?, ?, ?, ?, 'running', '{}', ?, ?)
+                    """,
+                    (request_id, user_id, agent_id, session_id, operation, now, now),
+                )
+                self._conn.commit()
+                if cursor.rowcount == 1:
+                    return None
+                row = self._conn.execute(
+                    "SELECT * FROM write_outcomes WHERE request_id = ?",
+                    (request_id,),
+                ).fetchone()
+                return dict(row) if row else None
+
+        existing = await _run_in_sqlite_pool(_claim)
+        if existing is None:
+            return None
+        return await self.get_write_outcome(request_id)
+
+    async def finish_write_outcome(
+        self,
+        request_id: str,
+        status: str,
+        result: Dict[str, Any],
+    ) -> bool:
+        def _finish():
+            with self._lock:
+                cursor = self._conn.execute(
+                    """
+                    UPDATE write_outcomes
+                    SET status = ?, result_json = ?, updated_at = ?
+                    WHERE request_id = ?
+                    """,
+                    (
+                        status,
+                        json.dumps(result, ensure_ascii=False, default=str),
+                        datetime.now().isoformat(),
+                        request_id,
+                    ),
+                )
+                self._conn.commit()
+                return cursor.rowcount == 1
+
+        return await _run_in_sqlite_pool(_finish)
+
+    async def get_write_outcome(self, request_id: str) -> Optional[Dict[str, Any]]:
+        def _get():
+            with self._lock:
+                row = self._conn.execute(
+                    "SELECT * FROM write_outcomes WHERE request_id = ?",
+                    (request_id,),
+                ).fetchone()
+                return dict(row) if row else None
+
+        row = await _run_in_sqlite_pool(_get)
+        if row is None:
+            return None
+        try:
+            row["result"] = json.loads(row.pop("result_json") or "{}")
+        except (TypeError, json.JSONDecodeError):
+            row["result"] = {}
+        return row
+
     # ================================================================
     # System Metrics（分钟粒度落盘）
     # ================================================================
@@ -414,26 +518,27 @@ class SqliteCache(CacheBase):
         """存储一个分钟桶的增量指标数据（UPSERT: 同一分钟多次写入会合并）"""
         try:
             def _store():
-                now = datetime.now().isoformat()
-                # UPSERT: 如果同一分钟已存在，合并数据
-                existing = self._conn.execute(
-                    "SELECT data FROM system_metrics WHERE minute_ts = ?",
-                    (minute_ts,),
-                ).fetchone()
-                if existing:
-                    import json as _json
-                    old_data = _json.loads(existing["data"])
-                    merged = self._merge_metric_buckets(old_data, data)
-                    self._conn.execute(
-                        "UPDATE system_metrics SET data = ?, created_at = ? WHERE minute_ts = ?",
-                        (_json.dumps(merged, default=str), now, minute_ts),
-                    )
-                else:
-                    self._conn.execute(
-                        "INSERT INTO system_metrics (minute_ts, data, created_at) VALUES (?, ?, ?)",
-                        (minute_ts, json.dumps(data, default=str), now),
-                    )
-                self._conn.commit()
+                with self._lock:
+                    now = datetime.now().isoformat()
+                    # UPSERT: 如果同一分钟已存在，合并数据
+                    existing = self._conn.execute(
+                        "SELECT data FROM system_metrics WHERE minute_ts = ?",
+                        (minute_ts,),
+                    ).fetchone()
+                    if existing:
+                        import json as _json
+                        old_data = _json.loads(existing["data"])
+                        merged = self._merge_metric_buckets(old_data, data)
+                        self._conn.execute(
+                            "UPDATE system_metrics SET data = ?, created_at = ? WHERE minute_ts = ?",
+                            (_json.dumps(merged, default=str), now, minute_ts),
+                        )
+                    else:
+                        self._conn.execute(
+                            "INSERT INTO system_metrics (minute_ts, data, created_at) VALUES (?, ?, ?)",
+                            (minute_ts, json.dumps(data, default=str), now),
+                        )
+                    self._conn.commit()
             await _run_in_sqlite_pool(_store)
         except Exception as e:
             logger.warning(f"store_metrics_minute failed: {e}")
@@ -442,17 +547,18 @@ class SqliteCache(CacheBase):
         """读取指定时间范围内的分钟指标数据"""
         try:
             def _load():
-                rows = self._conn.execute(
-                    "SELECT data FROM system_metrics WHERE minute_ts >= ? AND minute_ts <= ? ORDER BY minute_ts",
-                    (start_ts, end_ts),
-                ).fetchall()
-                results = []
-                for row in rows:
-                    try:
-                        results.append(json.loads(row["data"]))
-                    except (json.JSONDecodeError, TypeError):
-                        pass
-                return results
+                with self._lock:
+                    rows = self._conn.execute(
+                        "SELECT data FROM system_metrics WHERE minute_ts >= ? AND minute_ts <= ? ORDER BY minute_ts",
+                        (start_ts, end_ts),
+                    ).fetchall()
+                    results = []
+                    for row in rows:
+                        try:
+                            results.append(json.loads(row["data"]))
+                        except (json.JSONDecodeError, TypeError):
+                            pass
+                    return results
             return await _run_in_sqlite_pool(_load)
         except Exception as e:
             logger.warning(f"load_metrics_range failed: {e}")
@@ -462,11 +568,12 @@ class SqliteCache(CacheBase):
         """删除指定时间之前的 metrics 数据"""
         try:
             def _cleanup():
-                self._conn.execute(
-                    "DELETE FROM system_metrics WHERE minute_ts < ?",
-                    (before_ts,),
-                )
-                self._conn.commit()
+                with self._lock:
+                    self._conn.execute(
+                        "DELETE FROM system_metrics WHERE minute_ts < ?",
+                        (before_ts,),
+                    )
+                    self._conn.commit()
             await _run_in_sqlite_pool(_cleanup)
         except Exception as e:
             logger.warning(f"cleanup_old_metrics failed: {e}")

hy_memory/data/graph_store_kuzu.py

@@ -22,6 +22,7 @@ import logging
 import json
 import threading
 import time
+import weakref
 
 from ..models.memory import MemoryNode, MemoryLayer, MemoryStatus
 from ..config import MemoryConfig
@@ -77,6 +78,21 @@ async def _run_in_kuzu_pool(func, *args, **kwargs):
     return await run_in_executor_guarded(_kuzu_executor, _measured)
 
 
+# 本进程里已打开、尚未 close 的 store。drop_graph 据此拒绝删掉一个正被
+# 活着的 client 使用的图库。WeakSet：store 被回收后自动消失。
+_LIVE_STORES: "weakref.WeakSet[KuzuGraphStore]" = weakref.WeakSet()
+
+
+def open_graph_paths() -> List[str]:
+    """Real paths of the graph databases live stores in this process hold open."""
+    import os
+    return [
+        os.path.realpath(str(store._db_path))
+        for store in list(_LIVE_STORES)
+        if store._db is not None
+    ]
+
+
 def kuzu_executor_snapshot() -> Dict[str, Any]:
     with _kuzu_stats_lock:
         return {
@@ -350,6 +366,7 @@ class KuzuGraphStore(GraphStoreBase):
             )
             self._db = db
             self._conn = conn
+            _LIVE_STORES.add(self)
         except asyncio.TimeoutError:
             logger.warning(
                 f"GraphStore init timed out after 5s (Kuzu file lock contention). "
@@ -2441,6 +2458,7 @@ class KuzuGraphStore(GraphStoreBase):
     async def close(self) -> None:
         """关闭连接"""
         conn, db = self._conn, self._db
+        _LIVE_STORES.discard(self)
         self._conn = None
         self._db = None
         self._available = False

hy_memory/data/history_store.py

@@ -16,6 +16,7 @@ import json
 import logging
 import os
 import sqlite3
+import threading
 from datetime import datetime, timezone
 from typing import Dict, List, Any, Optional
 
@@ -65,6 +66,11 @@ def _now_iso() -> str:
     return datetime.now(timezone.utc).isoformat()
 
 
+def _escape_like(value: str) -> str:
+    """Escape LIKE wildcards so a user id is matched literally."""
+    return value.replace("\\", "\\\\").replace("%", "\\%").replace("_", "\\_")
+
+
 class HistoryStore:
     """
     SQLite 历史存储 - 记录所有内存操作的审计日志。
@@ -89,6 +95,10 @@ class HistoryStore:
         """
         self._db_path = config.history.db_path
         self._conn: Optional[sqlite3.Connection] = None
+        # sqlite3.Connection.close() must never race with an execute() on the
+        # same connection. The lock also serializes operations on this shared
+        # connection; separate HistoryStore instances remain independent.
+        self._conn_lock = threading.RLock()
 
     async def initialize(self) -> None:
         """创建表和索引（如果不存在）"""
@@ -97,20 +107,21 @@ class HistoryStore:
 
     def _init_sync(self) -> None:
         """同步初始化：创建目录、连接数据库、建表建索引"""
-        # 确保目录存在
-        db_dir = os.path.dirname(self._db_path)
-        if db_dir:
-            os.makedirs(db_dir, exist_ok=True)
+        with self._conn_lock:
+            # 确保目录存在
+            db_dir = os.path.dirname(self._db_path)
+            if db_dir:
+                os.makedirs(db_dir, exist_ok=True)
 
-        self._conn = sqlite3.connect(self._db_path, check_same_thread=False)
-        self._conn.row_factory = sqlite3.Row
-        # 开启 WAL 模式，提高并发读写性能
-        self._conn.execute("PRAGMA journal_mode=WAL;")
+            self._conn = sqlite3.connect(self._db_path, check_same_thread=False)
+            self._conn.row_factory = sqlite3.Row
+            # 开启 WAL 模式，提高并发读写性能
+            self._conn.execute("PRAGMA journal_mode=WAL;")
 
-        self._conn.execute(_CREATE_TABLE_SQL)
-        for idx_sql in _CREATE_INDEXES_SQL:
-            self._conn.execute(idx_sql)
-        self._conn.commit()
+            self._conn.execute(_CREATE_TABLE_SQL)
+            for idx_sql in _CREATE_INDEXES_SQL:
+                self._conn.execute(idx_sql)
+            self._conn.commit()
 
     # ================================================================
     # 记录操作
@@ -218,13 +229,14 @@ class HistoryStore:
         return await _run_in_sqlite_pool(self._get_history_sync, memory_id)
 
     def _get_history_sync(self, memory_id: str) -> List[Dict[str, Any]]:
-        if self._conn is None:
-            return []
-        cursor = self._conn.execute(
-            "SELECT * FROM memory_history WHERE memory_id = ? ORDER BY created_at ASC",
-            (memory_id,),
-        )
-        return [dict(row) for row in cursor.fetchall()]
+        with self._conn_lock:
+            if self._conn is None:
+                return []
+            cursor = self._conn.execute(
+                "SELECT * FROM memory_history WHERE memory_id = ? ORDER BY created_at ASC",
+                (memory_id,),
+            )
+            return [dict(row) for row in cursor.fetchall()]
 
     async def get_recent(
         self,
@@ -244,14 +256,43 @@ class HistoryStore:
         return await _run_in_sqlite_pool(self._get_recent_sync, isolation_key, limit)
 
     def _get_recent_sync(self, isolation_key: str, limit: int) -> List[Dict[str, Any]]:
-        if self._conn is None:
-            return []
-        cursor = self._conn.execute(
-            "SELECT * FROM memory_history WHERE isolation_key = ? "
-            "ORDER BY created_at DESC LIMIT ?",
-            (isolation_key, limit),
+        with self._conn_lock:
+            if self._conn is None:
+                return []
+            cursor = self._conn.execute(
+                "SELECT * FROM memory_history WHERE isolation_key = ? "
+                "ORDER BY created_at DESC LIMIT ?",
+                (isolation_key, limit),
+            )
+            return [dict(row) for row in cursor.fetchall()]
+
+    async def get_recent_for_user(
+        self,
+        user_id: str,
+        limit: int = 50,
+    ) -> List[Dict[str, Any]]:
+        """获取某 user 下所有 agent 的最近操作。
+
+        isolation_key 形如 ``"{user_id}:{agent_id}"``。user_id 里的 LIKE
+        通配符会被转义，保证只匹配这个 user，不会漏到 ``u1`` 之外。
+        """
+        prefix = _escape_like(f"{user_id}:") + "%"
+        return await _run_in_sqlite_pool(
+            self._get_recent_prefix_sync, prefix, limit,
         )
-        return [dict(row) for row in cursor.fetchall()]
+
+    def _get_recent_prefix_sync(
+        self, pattern: str, limit: int,
+    ) -> List[Dict[str, Any]]:
+        with self._conn_lock:
+            if self._conn is None:
+                return []
+            cursor = self._conn.execute(
+                "SELECT * FROM memory_history WHERE isolation_key LIKE ? ESCAPE '\\' "
+                "ORDER BY created_at DESC LIMIT ?",
+                (pattern, limit),
+            )
+            return [dict(row) for row in cursor.fetchall()]
 
     async def count(self, isolation_key: str = "") -> int:
         """
@@ -266,16 +307,17 @@ class HistoryStore:
         return await _run_in_sqlite_pool(self._count_sync, isolation_key)
 
     def _count_sync(self, isolation_key: str) -> int:
-        if self._conn is None:
-            return 0
-        if isolation_key:
-            cursor = self._conn.execute(
-                "SELECT COUNT(*) FROM memory_history WHERE isolation_key = ?",
-                (isolation_key,),
-            )
-        else:
-            cursor = self._conn.execute("SELECT COUNT(*) FROM memory_history")
-        return cursor.fetchone()[0]
+        with self._conn_lock:
+            if self._conn is None:
+                return 0
+            if isolation_key:
+                cursor = self._conn.execute(
+                    "SELECT COUNT(*) FROM memory_history WHERE isolation_key = ?",
+                    (isolation_key,),
+                )
+            else:
+                cursor = self._conn.execute("SELECT COUNT(*) FROM memory_history")
+            return cursor.fetchone()[0]
 
     async def close(self) -> None:
         """关闭数据库连接"""
@@ -284,9 +326,10 @@ class HistoryStore:
             logger.info("[HistoryStore] closed")
 
     def _close_sync(self) -> None:
-        if self._conn:
-            self._conn.close()
-            self._conn = None
+        with self._conn_lock:
+            if self._conn:
+                self._conn.close()
+                self._conn = None
 
     # ================================================================
     # 内部
@@ -339,33 +382,34 @@ class HistoryStore:
         role: str = "",
         extra: Optional[Dict[str, Any]] = None,
     ) -> int:
-        if self._conn is None:
-            return -1
-        now = _now_iso()
-        extra_json = json.dumps(extra or {}, ensure_ascii=False)
-        cursor = self._conn.execute(
-            """INSERT INTO memory_history
-               (memory_id, isolation_key, event,
-                old_memory, new_memory, old_status, new_status,
-                change_reason, layer, actor_id, role, extra,
-                created_at, updated_at)
-               VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)""",
-            (
-                memory_id,
-                isolation_key,
-                event,
-                old_memory,
-                new_memory,
-                old_status,
-                new_status,
-                change_reason,
-                layer,
-                actor_id,
-                role,
-                extra_json,
-                now,
-                now,
-            ),
-        )
-        self._conn.commit()
-        return cursor.lastrowid
+        with self._conn_lock:
+            if self._conn is None:
+                return -1
+            now = _now_iso()
+            extra_json = json.dumps(extra or {}, ensure_ascii=False)
+            cursor = self._conn.execute(
+                """INSERT INTO memory_history
+                   (memory_id, isolation_key, event,
+                    old_memory, new_memory, old_status, new_status,
+                    change_reason, layer, actor_id, role, extra,
+                    created_at, updated_at)
+                   VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)""",
+                (
+                    memory_id,
+                    isolation_key,
+                    event,
+                    old_memory,
+                    new_memory,
+                    old_status,
+                    new_status,
+                    change_reason,
+                    layer,
+                    actor_id,
+                    role,
+                    extra_json,
+                    now,
+                    now,
+                ),
+            )
+            self._conn.commit()
+            return cursor.lastrowid

hy_memory/data/vector_store_base.py

@@ -89,6 +89,17 @@ def passes_created_after(
 logger = logging.getLogger(__name__)
 
 
+def physical_collection_name(base_name: Optional[str], dims: Optional[int]) -> str:
+    """The collection name a store opens for ``base_name`` at ``dims``.
+
+    The dims suffix keeps two embedding widths from sharing one collection.
+    `hy_memory.reembed.vector_space_names` uses this too, so callers never
+    re-derive the rule.
+    """
+    base = base_name or "agent_memories"
+    return f"{base}_{dims}" if dims else base
+
+
 class VectorStoreBase(ABC):
     """
     向量存储抽象基类
@@ -98,13 +109,10 @@ class VectorStoreBase(ABC):
 
     def __init__(self, config: MemoryConfig):
         self.config = config
-        base_name = config.vector_store.collection_name or "agent_memories"
-        dims = config.vector_store.embedding_dims
         # 自动拼接维度后缀，避免不同 embedding 模型写入同一 collection 导致维度冲突
-        if dims:
-            self._collection_name = f"{base_name}_{dims}"
-        else:
-            self._collection_name = base_name
+        self._collection_name = physical_collection_name(
+            config.vector_store.collection_name, config.vector_store.embedding_dims,
+        )
 
     _supports_retrieval_clauses: bool = False
     _supports_narrow_episode_queries: bool = False

hy_memory/data/vector_store_chroma.py

@@ -9,10 +9,12 @@ Agent Memory V2 - VectorStore (Chroma)
 - 同步 API → _run_in_vdb_pool() 包装为异步
 """
 
-from typing import Optional, List, Dict, Any
+from typing import Optional, List, Dict, Any, Set, Tuple
 import concurrent.futures
 import functools
 import logging
+import os
+import weakref
 
 from ..models.memory import (
     MemoryNode, MemoryLayer, MemoryStatus,
@@ -33,6 +35,30 @@ _vdb_executor = concurrent.futures.ThreadPoolExecutor(
 )
 
 
+# 本进程里已 initialize、尚未 close 的 store。drop_vector_space 据此拒绝删掉
+# 一个正被活着的 client 使用的集合。WeakSet：store 被回收后自动消失。
+_LIVE_STORES: "weakref.WeakSet[ChromaVectorStore]" = weakref.WeakSet()
+
+
+def _location_key(vs_config) -> Tuple[str, str]:
+    if getattr(vs_config, "host", None):
+        return ("http", f"{vs_config.host}:{vs_config.port or 8000}")
+    return ("local", os.path.realpath(str(vs_config.persist_directory or "")))
+
+
+def open_collection_names(location: Tuple[str, str]) -> Set[str]:
+    """Collections that live stores in this process hold open at ``location``."""
+    names: Set[str] = set()
+    for store in list(_LIVE_STORES):
+        if store._client is None or _location_key(store.config.vector_store) != location:
+            continue
+        names.add(store._collection_name)
+        if store._entity_collection is not None:
+            from ..pipelines._retrieval.config import entity_collection_name
+            names.add(entity_collection_name(store._collection_name))
+    return names
+
+
 async def _run_in_vdb_pool(func, *args, **kwargs):
     """Run a synchronous Chroma call in the dedicated VDB executor."""
     call = functools.partial(func, *args, **kwargs) if args or kwargs else func
@@ -88,6 +114,7 @@ class ChromaVectorStore(VectorStoreBase):
             return client, collection
 
         self._client, self._collection = await _run_in_vdb_pool(_init)
+        _LIVE_STORES.add(self)
         logger.debug(f"VectorStore initialized (Chroma), collection={self._collection_name}")
 
     # ================================================================
@@ -561,6 +588,7 @@ class ChromaVectorStore(VectorStoreBase):
     async def close(self) -> None:
         """关闭客户端"""
         # Chroma PersistentClient 无需显式关闭
+        _LIVE_STORES.discard(self)
         self._client = None
         self._collection = None
         self._entity_collection = None

hy_memory/data/vector_store_faiss.py

@@ -462,14 +462,39 @@ class FaissVectorStore(VectorStoreBase):
             return None
 
     async def get_embeddings(self, node_ids: List[str]) -> Dict[str, List[float]]:
-        """批量取向量（in-memory _data 直接读 embedding），供去重算 cosine。"""
-        out: Dict[str, List[float]] = {}
-        for nid in node_ids:
-            point_id = self._node_id_to_point_id(nid)
-            entry = self._data.get(point_id)
-            if entry and entry.get("embedding"):
-                out[nid] = list(entry["embedding"])
-        return out
+        """批量取向量，供去重 / episode 摘要计算 cosine。
+
+        ``_data`` 只保存 payload 与 FAISS 内部下标；普通 upsert 不额外存一份
+        embedding，向量本体在 FAISS index 里。这里按当前有效下标 reconstruct，
+        并用 ``_idx_to_id`` 校验，避免读到已被替换的旧下标。
+        """
+
+        def _get() -> Dict[str, List[float]]:
+            out: Dict[str, List[float]] = {}
+            with self._lock:
+                for nid in node_ids:
+                    point_id = self._node_id_to_point_id(nid)
+                    entry = self._data.get(point_id)
+                    if entry is None:
+                        continue
+                    embedding = entry.get("embedding")
+                    if embedding:
+                        out[nid] = list(embedding)
+                        continue
+                    idx = entry.get("idx")
+                    if (
+                        idx is None
+                        or self._index is None
+                        or self._idx_to_id.get(int(idx)) != point_id
+                    ):
+                        continue
+                    try:
+                        out[nid] = self._index.reconstruct(int(idx)).tolist()
+                    except Exception:
+                        continue
+            return out
+
+        return await _run_in_vdb_pool(_get)
 
     # ================================================================
     # 删除

hy_memory/embedding.py

@@ -0,0 +1,53 @@
+"""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,6 +160,28 @@ 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/intention.py

@@ -10,8 +10,8 @@ HY Memory - Intention (L7) 召回 + 惰性过期转换 + 复本判定
     节点的 layer 改写为 l2_fact（持久化 update_payload），并从意图结果里剔除——
     过期意图变成普通历史事实，下次走 normal 召回；
   - **判重（重点）**：对幸存意图按下述规则分组，同组只留一条本次返回：
-        同 user_id + 同一天 memory_at + valid_until 相同（都为 None 或都相等）
-        + cosine 相似度 ≥ MEMORY_DEDUP_THRESHOLD (默认 0.95)
+        同 user_id + 同 agent_id + 同一天 memory_at + valid_until 相同
+        （都为 None 或都相等）+ cosine 相似度 ≥ MEMORY_DEDUP_THRESHOLD (默认 0.95)
     → 视为同一个意图的复本（extractor 复读机 / 多 session 重复表达）。
     保留组里 `gmt_created` 最早的（老的先来先得，稳定 id）；
   - **异步删库**：其余复本 fire-and-forget 从 VDB 删除，不影响本次调用 RT。
@@ -112,11 +112,19 @@ def _partition_duplicates(
     if len(hits) < 2:
         return list(hits), []
 
-    # 1. 按 (memory_at day, valid_until day) 分桶
-    buckets: Dict[Tuple[Any, Any], List[int]] = {}
+    # 1. 按 (user_id, agent_id, memory_at day, valid_until day) 分桶。
+    #    user_id / agent_id 必须进键：多用户检索时不同用户的同一天意图可能
+    #    文本、日期都相同，但它们是两个独立的租户数据；只按日期分桶会把其中
+    #    一个判成复本并硬删除。
+    buckets: Dict[Tuple[Any, Any, Any, Any], List[int]] = {}
     for idx, h in enumerate(hits):
         node = h.get("node")
-        key = (_memory_at_day(node), _valid_until_key(node))
+        key = (
+            getattr(node, "user_id", None) if node else None,
+            getattr(node, "agent_id", None) if node else None,
+            _memory_at_day(node),
+            _valid_until_key(node),
+        )
         buckets.setdefault(key, []).append(idx)
 
     def _gmt(h: Dict[str, Any]) -> float:
@@ -229,6 +237,8 @@ async def recall_intentions(
     *,
     user_ids: Optional[List[str]] = None,
     agent_ids: Optional[List[str]] = None,
+    isolation_key: str = "",
+    isolation_keys: Optional[List[str]] = None,
     limit: int = 10,
     now: Optional[datetime] = None,
     stats_out: Optional[Dict[str, Any]] = None,
@@ -243,6 +253,9 @@ async def recall_intentions(
         query_embedding: 查询向量
         user_ids: 用户隔离（单/多用户）
         agent_ids: 可选 agent 过滤
+        isolation_key / isolation_keys: 精确的 (user, agent, session) 隔离键。
+            与其它召回通道一致：调用方在按 session 过滤时只生成这两项，
+            user_ids / agent_ids 为 None；不把它们透传下去就会退化成全库检索。
         limit: 召回上限（返回给上游的条数）
         now: 当前时间（默认 datetime.now()，测试可注入）
         stats_out: 可选 dict，本函数把分段耗时与数量**原地回填**进去，供调用方落
@@ -283,6 +296,8 @@ async def recall_intentions(
             query_embedding=query_embedding,
             user_ids=user_ids or None,
             agent_ids=agent_ids,
+            isolation_key=isolation_key,
+            isolation_keys=isolation_keys,
             layers=[MemoryLayer.L7_INTENTION],
             limit=fetch_limit,
             score_threshold=0.0,  # intention 不设语义门槛

hy_memory/pipelines/_retrieval/reconcile_retrieval.py

@@ -115,11 +115,16 @@ class ReconcileHybridRetriever:
         fused_max = max(fused_all) if fused_all else 0.0
 
         base = (
-            f"[reconcile-hybrid][{req}] pool={pool_size} q_terms={q_terms!r} "
+            f"[reconcile-hybrid][{req}] pool={pool_size} q_terms={len(q_terms)} "
             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

@@ -401,6 +401,11 @@ 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,9 +692,10 @@ class CrossDomainSweeper:
                 )
 
             logger.info(
-                f"[sweeper] Created L6 core {core_id[:12]}: '{core_content[:60]}' "
+                f"[sweeper] Created L6 core {core_id[:12]} "
                 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,7 +57,9 @@ 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,
@@ -1279,7 +1281,10 @@ class BaseReadPipeline(ReadPipeline):
             SAME_SERIES_TIMELINE_ON = bool(
                 getattr(self.config.recall, "same_series_timeline_enabled", False)
             )
-            LOCAL_RERANK_ON = bool(
+            # 按次的重排开关（search(rerank=False)）：关掉本地 cross-encoder 与图重排，
+            # 结果按召回分排序。只读请求对象，不碰共享状态，并发请求互不影响。
+            RERANK_ON = bool(getattr(request, "rerank", True))
+            LOCAL_RERANK_ON = RERANK_ON and bool(
                 getattr(self.config.recall, "local_rerank_enabled", False)
             )
             LOCAL_RERANK_POOL_FACTOR = max(1, int(
@@ -1431,6 +1436,11 @@ 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(
@@ -1840,6 +1850,8 @@ class BaseReadPipeline(ReadPipeline):
                     query_embedding,
                     user_ids=isolation_params.get("user_ids"),
                     agent_ids=isolation_params.get("agent_ids"),
+                    isolation_key=isolation_params.get("isolation_key") or "",
+                    isolation_keys=isolation_params.get("isolation_keys"),
                     limit=request.intention_limit,
                     stats_out=_intent_stats,
                     include_sources=request.include_sources,
@@ -2460,7 +2472,7 @@ class BaseReadPipeline(ReadPipeline):
             # 只把已选出的 top-N 换个顺序收益很小。
             relation_paths: List[Dict[str, Any]] = []
             _graph_stats: Dict[str, Any] = {}
-            if self._expansion_on():
+            if RERANK_ON and self._expansion_on():
                 _t_graph = datetime.now()
                 _pool_before = len(normal_results)
                 normal_results, relation_paths, _graph_stats = await self._apply_graph_rerank(
@@ -2523,7 +2535,7 @@ class BaseReadPipeline(ReadPipeline):
                         df_thr=POOL_DF_THR,
                         penalty=POOL_DF_PENALTY,
                     )
-                if NEAR_DUP_THR > 0 and NEAR_DUP_PENALTY > 0:
+                if NEAR_DUP_ON and NEAR_DUP_THR > 0 and NEAR_DUP_PENALTY > 0:
                     normal_results = near_dup_demote(
                         normal_results,
                         jaccard_thr=NEAR_DUP_THR,
@@ -2536,7 +2548,7 @@ class BaseReadPipeline(ReadPipeline):
                     ))
                     if LOCAL_RERANK_ON else final_limit
                 )
-                if 0.0 < MMR_LAMBDA < 0.999 and len(normal_results) > _pre_rerank_limit:
+                if MMR_ON and len(normal_results) > _pre_rerank_limit:
                     normal_results = mmr_select(
                         normal_results,
                         _pre_rerank_limit,
@@ -2713,7 +2725,7 @@ class BaseReadPipeline(ReadPipeline):
                         reverse=True,
                     )
                     if (
-                        0.0 < MMR_LAMBDA < 0.999
+                        MMR_ON
                         and len(multi_seed_pool) > _pre_rerank_limit
                     ):
                         multi_seed_pool = mmr_select(
@@ -3542,6 +3554,9 @@ 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",
@@ -3572,8 +3587,9 @@ 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='{request.query[:80]}'"
+                f"query({len(request.query or '')} chars)"
             )
+            logger.debug(f"[read/{self.VERSION}] query={request.query[:80]!r}")
 
             response.success = True
 

hy_memory/pipelines/registry.py

@@ -19,6 +19,7 @@ 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
 
@@ -50,7 +51,12 @@ class ComponentFactory:
         s2 = await factory.get_system2_writer()    # System2Writer (ultra mode)
     """
 
-    def __init__(self, config: Optional[MemoryConfig] = None):
+    def __init__(
+        self,
+        config: Optional[MemoryConfig] = None,
+        *,
+        embedding_service: Optional[EmbeddingService] = None,
+    ):
         self.config = config or MemoryConfig.from_env()
 
         # 实例缓存（单例）
@@ -62,7 +68,7 @@ class ComponentFactory:
         self._readers: Dict[str, ReadPipeline] = {}
 
         # 共享资源
-        self._shared_embed_service: Optional[EmbedService] = None
+        self._shared_embed_service: Optional[EmbeddingService] = embedding_service
         self._shared_vector_store: Optional[VectorStoreBase] = None
         self._shared_vector_store_initialized: bool = False
         self._shared_graph_store = None
@@ -72,7 +78,7 @@ class ComponentFactory:
     # 共享资源
     # ================================================================
 
-    def _get_shared_embed_service(self) -> EmbedService:
+    def _get_shared_embed_service(self) -> EmbeddingService:
         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,7 +2516,8 @@ 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: {json_str[:200]}")
+        logger.warning(f"[S2-agent] JSON parse failed ({len(json_str)} chars)")
+        logger.debug(f"[S2-agent] unparsable output: {json_str[:200]!r}")
         return None
 
 

hy_memory/pipelines/writer.py

@@ -280,6 +280,22 @@ class MemoryWriter(WritePipeline):
             custom["source_raw_memory_ids"] = source_ids
         return custom
 
+    def _flat_trimmed_raw(self, request: WriteRequest) -> str:
+        """把 request.messages 按 raw 统一规则裁剪后拼成 L1_RAW 文本。
+
+        只裁落库副本；request.messages 不动（本次 extractor 输入仍用完整 messages）。
+        """
+        import copy as _copy
+        from ..utils.raw_trim import trim_raw_messages
+
+        _coding_cfg = getattr(getattr(self, "config", None), "coding", None)
+        _trimmed_req = _copy.copy(request)
+        _trimmed_req.messages = trim_raw_messages(
+            request.messages,
+            tool_max_bytes=getattr(_coding_cfg, "tool_result_max_bytes", None),
+        )
+        return _trimmed_req.get_flat_content()
+
     @staticmethod
     def _attach_client_meta(custom: Dict[str, Any], request: Optional[WriteRequest]) -> None:
         """给新建节点挂上调用方 meta（单份 list）。
@@ -968,7 +984,7 @@ class MemoryWriter(WritePipeline):
             async def _run():
                 try:
                     nid = await summarize_closed_episode(
-                        vector_store=self.vector_store,
+                        vector_store=await self._get_vector_store(),
                         embed_service=self.embed_service,
                         llm_provider=self.llm_provider,
                         episode_id=episode_id,
@@ -2554,9 +2570,14 @@ class MemoryWriter(WritePipeline):
         try:
             # 参数校验
             content = request.content
+            # raw 在写入时就按统一规则裁好（见 utils/raw_trim.py）：工具输出、长
+            # assistant 回复不再原样长期存储；历史拼接直接用存下来的文本，不再二次裁剪。
+            # request.messages 保持原样——本次 extractor 输入仍是完整 messages。
+            _raw_trimmed = False
             if not content and request.has_messages():
-                content = request.get_flat_content()
+                content = self._flat_trimmed_raw(request)
                 request.content = content
+                _raw_trimmed = True
 
             if not content:
                 response.error_code = 400
@@ -2627,6 +2648,9 @@ class MemoryWriter(WritePipeline):
                     vector_store = await self._get_vector_store()
                     layer_enum = MemoryLayer.from_string(suggested_layer)
                     _raw_custom: Dict[str, Any] = {}
+                    if _raw_trimmed:
+                        from ..utils.raw_trim import RAW_TRIMMED_KEY
+                        _raw_custom[RAW_TRIMMED_KEY] = True
                     self._attach_client_meta(_raw_custom, request)
                     mem_node = MemoryNode(
                         user_id=request.user_id,
@@ -2929,13 +2953,16 @@ class MemoryWriter(WritePipeline):
         agent_id: Optional[str] = None,
         exclude_memory_id: str = "",
         max_turns: int = 20,
-        max_chars_assistant: int = 500,
+        max_chars_assistant: Optional[int] = None,
     ) -> str:
         """
         获取该用户最近的 L1_RAW 对话记录，按轮次拆分后拼成 history context。
 
         每条 L1_RAW 的 content 是多轮对话（[user]: ...\n[assistant]: ...）。
-        拆成单条 message 后，user 消息完整保留，assistant 消息截取前 max_chars_assistant 字符。
+        raw 在写入时已按 utils/raw_trim.py 的规则裁好（custom[RAW_TRIMMED_KEY]），
+        这里拆成单条 message 后直接拼接，不再二次裁剪。该规则之前写入的旧 raw
+        没有这个标记，仍按同一（幂等）规则裁剪后再拼，避免旧的长回复 / 工具输出
+        撑大 prompt。max_chars_assistant 只作用于这些旧 raw，默认同写入规则。
         最终取最近 max_turns 条 message（注意单位是 message 条数，非对话轮数；
         调用方按 k 轮 × 2 传入）。
 
@@ -2977,23 +3004,33 @@ class MemoryWriter(WritePipeline):
             # 避免把正文里形如 "[注]: xxx" 的普通文本误判成消息边界。
             import re as _re
             from .base import parse_user_name_line
-            _KNOWN_ROLES = {"user", "assistant", "system", "tool"}
             # 带方括号的任意 label（含对方真人名字）
             _labeled_prefix = _re.compile(r"^\[([^\]\n]{1,32})\]:\s?")
             # 无方括号的已知 role（历史数据容错，沿用旧正则的 `\[?...\]?` 宽容度）
             _bare_role_prefix = _re.compile(r"^(user|assistant|system|tool):\s?")
 
-            # (label, content) 元组列表；label 为 role 或对方真人名字
-            parsed: List[Tuple[str, str]] = []
+            from ..utils.raw_trim import (
+                DEFAULT_RAW_ASSISTANT_MAX_CHARS,
+                RAW_TRIMMED_KEY,
+                trim_raw_body,
+            )
+            if max_chars_assistant is None:
+                max_chars_assistant = DEFAULT_RAW_ASSISTANT_MAX_CHARS
+            _coding_cfg = getattr(getattr(self, "config", None), "coding", None)
+            _tool_max_bytes = getattr(_coding_cfg, "tool_result_max_bytes", None)
+
+            # (label, content, 是否旧 raw 需兼容裁剪) 元组列表；label 为 role 或对方真人名字
+            parsed: List[Tuple[str, str, bool]] = []
             user_name: str = ""
             for node in nodes:
                 content = node.content or ""
+                _legacy = not bool((node.custom or {}).get(RAW_TRIMMED_KEY))
                 for _line_idx, line in enumerate(content.split("\n")):
                     m = _labeled_prefix.match(line) or _bare_role_prefix.match(line)
                     if m:
                         label = m.group(1)
                         body = line[m.end():]
-                        parsed.append((label, body))
+                        parsed.append((label, body, _legacy))
                         continue
                     # 名字行只可能是每个 node content 的第一行（get_flat_content 插在文首）。
                     # 逐 node 判断而非用 `not parsed`：parsed 跨 node 累积，第二个 node
@@ -3006,18 +3043,18 @@ class MemoryWriter(WritePipeline):
                             continue
                     if parsed:
                         # 续行：拼回上一条 message（保留换行）
-                        prev_label, prev_body = parsed[-1]
-                        parsed[-1] = (prev_label, prev_body + "\n" + line)
+                        prev_label, prev_body, prev_legacy = parsed[-1]
+                        parsed[-1] = (prev_label, prev_body + "\n" + line, prev_legacy)
                     else:
                         # 开头就是无前缀行（异常/老数据）：当成 user 消息兜底
-                        parsed.append(("user", line))
+                        parsed.append(("user", line, _legacy))
 
             # 取最近 max_turns 条 message（按 message 截断，绝不从消息中间切开）
             recent = parsed[-max_turns:] if len(parsed) > max_turns else parsed
             if not recent:
                 return ""
 
-            # 格式化：非 user 侧整条截断（含对方真人），user 完整保留
+            # 格式化：新 raw 直接拼接；旧 raw 按写入同一规则兼容裁剪
             all_messages: List[str] = []
             if user_name:
                 from .base import render_user_name_line
@@ -3025,17 +3062,18 @@ class MemoryWriter(WritePipeline):
 
                 _name_line = render_user_name_line(
                     user_name,
-                    is_chinese("\n".join(b for _, b in recent)),
+                    is_chinese("\n".join(b for _, b, _ in recent)),
                 )
                 if _name_line:
                     all_messages.append(_name_line)
-            for label, body in recent:
+            for label, body, legacy in recent:
+                if legacy:
+                    body = trim_raw_body(
+                        label, body,
+                        assistant_max_chars=max_chars_assistant,
+                        tool_max_bytes=_tool_max_bytes,
+                    )
                 body = body.strip()
-                # 截断口径：assistant + 对方真人（非已知 role 的 label）。
-                # user 完整保留；system / tool 沿用历史行为（不截断）。
-                _truncate = label == "assistant" or label not in _KNOWN_ROLES
-                if _truncate and len(body) > max_chars_assistant:
-                    body = body[:max_chars_assistant] + "..."
                 all_messages.append(f"[{label}]: {body}")
 
             return "\n".join(all_messages)

hy_memory/retrieval.py

@@ -0,0 +1,23 @@
+"""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

@@ -29,13 +29,32 @@ import logging
 import os
 import re
 import signal
-import sys
+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
@@ -148,7 +167,6 @@ 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()
@@ -161,7 +179,8 @@ class MemoryHTTPHandler(BaseHTTPRequestHandler):
             if m:
                 memory_id = m.group(1)
                 client = _get_client()
-                result = client.get(memory_id)
+                query = parse_qs(urlparse(self.path).query)
+                result = client.get(memory_id, **_namespace_args(query))
                 if result is None:
                     _json_response(self, 404, {"error": "not_found", "memory_id": memory_id})
                 else:
@@ -170,6 +189,10 @@ 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)})
@@ -213,7 +236,7 @@ class MemoryHTTPHandler(BaseHTTPRequestHandler):
             _json_response(self, 500, {"error": str(e)})
 
     def do_PUT(self):
-        path = self.path.rstrip("/")
+        path = self.path.split("?")[0].rstrip("/")
         body = _read_json_body(self)
         if body is None:
             _json_response(self, 400, {"error": "invalid JSON body"})
@@ -228,29 +251,43 @@ class MemoryHTTPHandler(BaseHTTPRequestHandler):
                     _json_response(self, 400, {"error": "content is required"})
                     return
                 client = _get_client()
-                result = client.update(memory_id, content)
+                result = client.update(
+                    memory_id,
+                    content,
+                    **_namespace_args(body),
+                    **({"task": body["task"]} if body.get("task") else {}),
+                )
                 _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.rstrip("/")
+        path = self.path.split("?")[0].rstrip("/")
         try:
             m = re.match(r"^/api/v1/memories/([^/]+)$", path)
             if m:
                 memory_id = m.group(1)
                 client = _get_client()
-                result = client.delete(memory_id)
+                query = parse_qs(urlparse(self.path).query)
+                result = client.delete(memory_id, **_namespace_args(query))
                 _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)})
@@ -455,7 +492,8 @@ class MemoryHTTPHandler(BaseHTTPRequestHandler):
             if key in body:
                 kwargs[key] = body[key]
 
-        for key in ("limit", "min_score", "schema_min_score", "schema_limit", "reader"):
+        for key in ("limit", "min_score", "schema_min_score", "schema_limit", "reader",
+                    "rerank"):
             if key in body:
                 kwargs[key] = body[key]
 
@@ -495,6 +533,16 @@ class MemoryHTTPHandler(BaseHTTPRequestHandler):
         _json_response(self, 200, result)
 
 
+def _request_shutdown(server: ThreadingHTTPServer) -> None:
+    """Ask ``serve_forever`` to stop without blocking the calling thread.
+
+    ``BaseServer.shutdown()`` waits for the ``serve_forever`` loop to exit. A
+    signal handler runs on the very thread executing that loop, so calling it
+    there deadlocks forever. Hand the call to a helper thread instead.
+    """
+    threading.Thread(target=server.shutdown, daemon=True).start()
+
+
 def run_server(port: int = 19527, host: str = "127.0.0.1"):
     """Start the HTTP server (blocking)."""
     # Configure logging — basicConfig for root; hy_memory level set after client init
@@ -523,13 +571,12 @@ def run_server(port: int = 19527, host: str = "127.0.0.1"):
     logger.info(f"[server] Listening on http://{host}:{port}")
     logger.info(f"[server] Health check: http://{host}:{port}/healthz")
 
-    # Graceful shutdown
+    # Graceful shutdown. The signal handler only asks a helper thread to stop
+    # the loop; cleanup runs after serve_forever() returns so it cannot race
+    # the request threads or deadlock the serving thread.
     def _shutdown(signum, frame):
         logger.info("[server] Shutting down...")
-        server.shutdown()
-        if _client is not None:
-            _client.close()
-        sys.exit(0)
+        _request_shutdown(server)
 
     signal.signal(signal.SIGINT, _shutdown)
     signal.signal(signal.SIGTERM, _shutdown)
@@ -538,6 +585,10 @@ def run_server(port: int = 19527, host: str = "127.0.0.1"):
         server.serve_forever()
     except KeyboardInterrupt:
         _shutdown(None, None)
+    finally:
+        server.server_close()
+        if _client is not None:
+            _client.close()
 
 
 def main():

hy_memory/snapshot.py

@@ -0,0 +1,150 @@
+"""Public, offline snapshot support for the SDK-owned local data plane."""
+
+from __future__ import annotations
+
+import hashlib
+import os
+import shutil
+from dataclasses import dataclass
+from pathlib import Path
+
+
+class DataPlaneSnapshotRejected(RuntimeError):
+    def __init__(self, code: str) -> None:
+        super().__init__(code)
+        self.code = code
+
+
+@dataclass(frozen=True)
+class DataPlaneSnapshot:
+    source_root: Path
+    snapshot_root: Path
+    files: tuple[dict[str, object], ...]
+    total_bytes: int
+
+
+@dataclass(frozen=True)
+class DataPlaneRestore:
+    restored_root: Path
+    previous_root: Path | None
+    files_restored: int
+    total_bytes: int
+
+
+def _sha256(path: Path) -> str:
+    digest = hashlib.sha256()
+    with path.open("rb") as handle:
+        for chunk in iter(lambda: handle.read(1024 * 1024), b""):
+            digest.update(chunk)
+    return digest.hexdigest()
+
+
+def snapshot_local_data_plane(
+    *,
+    source_root: Path,
+    target_root: Path,
+    writers_stopped: bool,
+) -> DataPlaneSnapshot:
+    """Copy one quiesced local SDK root and return a verified inventory.
+
+    Remote providers require their own export implementation and must not call
+    this local-path contract.
+    """
+    if not writers_stopped:
+        raise DataPlaneSnapshotRejected("data_plane_snapshot_writers_running")
+    source = source_root.resolve()
+    target = target_root.resolve()
+    if source.is_symlink() or not source.is_dir():
+        raise DataPlaneSnapshotRejected("data_plane_snapshot_source_invalid")
+    if target.exists():
+        raise DataPlaneSnapshotRejected("data_plane_snapshot_target_exists")
+
+    try:
+        target.mkdir(parents=True)
+        for root, directories, files in os.walk(source, followlinks=False):
+            root_path = Path(root)
+            relative = root_path.relative_to(source)
+            target_directory = target / relative
+            target_directory.mkdir(parents=True, exist_ok=True)
+            for name in directories:
+                if (root_path / name).is_symlink():
+                    raise DataPlaneSnapshotRejected("data_plane_snapshot_symlink")
+            for name in files:
+                item = root_path / name
+                if item.is_symlink():
+                    raise DataPlaneSnapshotRejected("data_plane_snapshot_symlink")
+                shutil.copy2(item, target_directory / name)
+
+        inventory: list[dict[str, object]] = []
+        for path in sorted(item for item in target.rglob("*") if item.is_file()):
+            inventory.append(
+                {
+                    "path": path.relative_to(target).as_posix(),
+                    "bytes": path.stat().st_size,
+                    "sha256": _sha256(path),
+                }
+            )
+        for item in inventory:
+            copied = target / str(item["path"])
+            if copied.stat().st_size != item["bytes"] or _sha256(copied) != item["sha256"]:
+                raise DataPlaneSnapshotRejected("data_plane_snapshot_verify_failed")
+    except DataPlaneSnapshotRejected:
+        shutil.rmtree(target, ignore_errors=True)
+        raise
+    except OSError as error:
+        shutil.rmtree(target, ignore_errors=True)
+        raise DataPlaneSnapshotRejected("data_plane_snapshot_failed") from error
+
+    return DataPlaneSnapshot(
+        source_root=source,
+        snapshot_root=target,
+        files=tuple(inventory),
+        total_bytes=sum(int(item["bytes"]) for item in inventory),
+    )
+
+
+def restore_local_data_plane(
+    *,
+    snapshot_root: Path,
+    target_root: Path,
+    writers_stopped: bool,
+    protective_root: Path | None = None,
+) -> DataPlaneRestore:
+    """Replace one local SDK root from a verified snapshot with rollback."""
+    if not writers_stopped:
+        raise DataPlaneSnapshotRejected("data_plane_restore_writers_running")
+    source = snapshot_root.resolve()
+    target = target_root.resolve()
+    protective = (
+        protective_root.resolve()
+        if protective_root is not None
+        else target.parent / f".{target.name}.pre-restore"
+    )
+    staging = target.parent / f".{target.name}.restore.tmp"
+    if target.is_symlink() or protective.exists() or staging.exists():
+        raise DataPlaneSnapshotRejected("data_plane_restore_target_unsafe")
+
+    copied = snapshot_local_data_plane(
+        source_root=source,
+        target_root=staging,
+        writers_stopped=True,
+    )
+    previous: Path | None = None
+    try:
+        if target.exists():
+            target.replace(protective)
+            previous = protective
+        staging.replace(target)
+    except OSError as error:
+        if previous is not None and previous.exists() and not target.exists():
+            previous.replace(target)
+            previous = None
+        shutil.rmtree(staging, ignore_errors=True)
+        raise DataPlaneSnapshotRejected("data_plane_restore_replace_failed") from error
+
+    return DataPlaneRestore(
+        restored_root=target,
+        previous_root=previous,
+        files_restored=len(copied.files),
+        total_bytes=copied.total_bytes,
+    )

hy_memory/utils/async_executor.py

@@ -4,6 +4,7 @@ from __future__ import annotations
 
 import asyncio
 import concurrent.futures
+import contextvars
 import functools
 from concurrent.futures import Executor
 from typing import Any, Callable, Optional
@@ -39,7 +40,9 @@ 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."""
-    return await run_in_executor_guarded(None, func, *args, **kwargs)
+    context = contextvars.copy_context()
+    call = functools.partial(func, *args, **kwargs)
+    return await run_in_executor_guarded(None, context.run, call)
 
 
 def concurrent_result_guarded(

hy_memory/utils/lang_detect.py

@@ -8,6 +8,7 @@ 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
@@ -135,6 +136,30 @@ 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,
@@ -153,20 +178,57 @@ def extract_content_for_detection(
         Concatenated content text suitable for language detection.
     """
     if content and content.strip():
-        return 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)
 
     if messages:
         parts = []
+        user_parts = []
         for msg in messages:
             if isinstance(msg, dict):
-                c = msg.get("content", "")
+                c, role = msg.get("content", ""), msg.get("role")
             elif hasattr(msg, "content"):
-                c = msg.content
+                c, role = msg.content, getattr(msg, "role", None)
             else:
                 continue
-            if c and c.strip():
-                parts.append(c.strip())
-        return "\n".join(parts)
+            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)
 
     return ""
 

hy_memory/utils/pipeline_log_writer.py

@@ -1,6 +1,7 @@
 # -*- coding: utf-8 -*-
 """
-Pipeline Log Writer — 环节级 JSONL 日志（始终开启，与 SQLite Trace 分离）。
+Pipeline Log Writer — 环节级 JSONL 日志（默认开启，MEMORY_PIPELINE_LOG_ENABLED=false 关闭；
+与 SQLite Trace 分离）。
 
 目录: {log_dir}/{subdir}/{date}.log
 每行: request_id, namespace, user_id, agent_id, step, prompt, content, parsed,
@@ -18,12 +19,32 @@ from __future__ import annotations
 
 import json
 import logging
+import re
 from datetime import datetime
 from pathlib import Path
 from typing import Any, List, Optional
 
 logger = logging.getLogger(__name__)
 
+#: A namespace is a single path component, not a path. `\w` keeps Unicode
+#: names working while excluding separators, drive letters and NUL.
+_SAFE_SUBDIR = re.compile(r"[\w.-]{1,64}", re.UNICODE)
+
+
+def _safe_subdir(value: str) -> Optional[str]:
+    """Return ``value`` if it is safe as one directory name, else ``None``.
+
+    ``user_id`` is caller-controlled. Without this check a value such as
+    ``"/tmp/evil__u1"`` makes ``Path(base) / "/tmp/evil"`` discard ``base``
+    entirely; ``"../.."`` escapes it the same way.
+    """
+    candidate = (value or "").strip()
+    if not candidate or candidate in {".", ".."}:
+        return None
+    if not _SAFE_SUBDIR.fullmatch(candidate):
+        return None
+    return candidate
+
 # 兼容旧 import
 TraceFileWriter = None  # set after class definition
 
@@ -40,7 +61,7 @@ class PipelineLogWriter:
 
     def __init__(self, log_dir: str, default_subdir: str = "default"):
         self._log_dir = log_dir
-        self._default_subdir = default_subdir or "default"
+        self._default_subdir = _safe_subdir(default_subdir) or "default"
         try:
             (Path(self._log_dir) / self._default_subdir).mkdir(parents=True, exist_ok=True)
         except Exception:
@@ -49,7 +70,7 @@ class PipelineLogWriter:
     def _resolve_subdir(self, user_id: str) -> str:
         """从 user_id 的 "{prefix}__{user_id}" 前缀取 prefix 作为子目录；无前缀则回落。"""
         if user_id and "__" in user_id:
-            prefix = user_id.split("__", 1)[0].strip()
+            prefix = _safe_subdir(user_id.split("__", 1)[0])
             if prefix:
                 return prefix
         return self._default_subdir
@@ -115,7 +136,14 @@ class PipelineLogWriter:
             line = json.dumps(record, ensure_ascii=False, default=str)
             date_str = datetime.now().strftime("%Y-%m-%d")
             subdir = self._resolve_subdir(user_id)
-            log_dir = Path(self._log_dir) / subdir
+            base_dir = Path(self._log_dir).resolve()
+            log_dir = (base_dir / subdir).resolve()
+            # Defence in depth: even if a future change lets a suspicious
+            # component through, never write outside the configured root.
+            try:
+                log_dir.relative_to(base_dir)
+            except ValueError:
+                log_dir = base_dir / self._default_subdir
             log_dir.mkdir(parents=True, exist_ok=True)
             log_file = log_dir / f"{date_str}.log"
             with open(log_file, "a", encoding="utf-8") as f:

hy_memory/utils/pipeline_observability.py

@@ -1,16 +1,20 @@
 # -*- 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，可用于项目、部署或数据分桶。
@@ -94,6 +98,16 @@ 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 (
@@ -125,7 +139,7 @@ def redact_content(value: str) -> str:
 
 def resolve_pipeline_log_dir() -> str:
     """
-    JSONL pipeline log 根目录（始终使用，有默认值）。
+    JSONL pipeline log 根目录（MEMORY_PIPELINE_LOG_ENABLED 开启时使用，有默认值）。
 
     优先级: MEMORY_LOG_DIR > MEMORY_TRACE_LOG_DIR > {MEMORY_DATA_DIR}/logs/pipeline
     """
@@ -228,6 +242,7 @@ 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()
@@ -410,7 +425,8 @@ def wrap_store_pipeline_log(
         try:
             loop = asyncio.get_running_loop()
             # JSONL 用线程池，与 loop 无亲和，留在当前 loop。
-            _track_task(loop.create_task(_persist_jsonl()))
+            if log_writer is not None:
+                _track_task(loop.create_task(_persist_jsonl()))
             # DB trace 用 cache pool（可能 aiomysql，绑定 owner_loop）。若当前不在
             # owner_loop（如 search 走独立 loop），派发回 owner_loop 执行，避免跨 loop。
             if trace_enabled:
@@ -446,25 +462,26 @@ def wrap_store_pipeline_log(
                         )
         except RuntimeError:
             # 无 running loop（极少见）：退化为同步写，保证不丢日志
-            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 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
             if trace_enabled:
                 try:
                     result = original_store(
@@ -496,6 +513,11 @@ 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,
     *,
@@ -503,6 +525,9 @@ 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 污染连接池。
@@ -514,15 +539,31 @@ def install_pipeline_observability(
     except RuntimeError:
         owner_loop = None
 
-    log_dir = resolve_pipeline_log_dir()
-    log_writer = PipelineLogWriter(log_dir)
+    log_enabled = is_pipeline_log_enabled()
     trace_enabled = is_pipeline_trace_enabled()
-    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)"
-    )
+    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)"
+        )
     cache.store_pipeline_log = wrap_store_pipeline_log(
         cache.store_pipeline_log,
         log_writer=log_writer,

hy_memory/utils/raw_trim.py

@@ -0,0 +1,91 @@
+# -*- coding: utf-8 -*-
+"""
+原始对话（raw）落库前的统一裁剪规则（规则，零 LLM）。
+
+raw 会被长期保存（MemHub 已取消 raw 的保留期限；lite 模式下 raw 是唯一存储），
+不裁剪会把工具输出、大段粘贴日志原样存下来。因此 raw 在**写入时**就裁好，
+读取方（extractor 的「最近 k 条」历史注入）直接拼接，不再二次裁剪。
+
+规则按说话人标签（ChatMessage.speaker_label() / L1_RAW 里的 ``[label]``）：
+
+- ``user``：完整保留；
+- ``system``：完整保留（与历史注入原口径一致）；
+- ``tool``：头尾保留、中段替换为 ``[...N bytes omitted by truncate...]``，
+  上限为 ``coding.tool_result_max_bytes``（env ``MEMORY_CODING_TOOL_RESULT_MAX_BYTES``，
+  默认 2048），与 coding 链路同一个函数；
+- 其余（``assistant``、对方真人名字等非已知 role 的 label）：strip 后超过
+  ``assistant_max_chars``（默认 500，即历史注入原来的 ``max_chars_assistant``）
+  时截成前 N 个字符 + ``...``。
+
+所有规则确定且幂等：对已裁剪的文本再裁一次结果不变。
+"""
+
+from typing import List, Optional
+
+from ..pipelines.base import ChatMessage
+
+# 历史注入原 `_get_recent_history(max_chars_assistant=500)` 的默认值，现为唯一来源。
+DEFAULT_RAW_ASSISTANT_MAX_CHARS = 500
+
+# L1_RAW 节点 custom 上的标记：内容已按本模块规则在写入时裁剪。
+# 历史拼接据此区分「新 raw 直接拼接」与「本规则之前写入的旧 raw 需兼容裁剪」。
+RAW_TRIMMED_KEY = "raw_trimmed"
+
+# 不裁剪的标签（tool 单独处理）
+_KEEP_LABELS = frozenset({"user", "system"})
+
+
+def trim_raw_body(
+    label: str,
+    body: str,
+    *,
+    assistant_max_chars: int = DEFAULT_RAW_ASSISTANT_MAX_CHARS,
+    tool_max_bytes: Optional[int] = None,
+) -> str:
+    """按说话人标签裁剪单条消息正文。幂等。"""
+    if not isinstance(body, str):
+        body = "" if body is None else str(body)
+    if label in _KEEP_LABELS:
+        return body
+    if label == "tool":
+        from ..coding.preproc import (
+            DEFAULT_MAX_TOOL_RESULT_BYTES,
+            truncate_tool_result_text,
+        )
+
+        return truncate_tool_result_text(
+            body, max_bytes=int(tool_max_bytes or DEFAULT_MAX_TOOL_RESULT_BYTES),
+        )
+    stripped = body.strip()
+    if len(stripped) > assistant_max_chars:
+        return stripped[:assistant_max_chars] + "..."
+    return body
+
+
+def trim_raw_messages(
+    messages: List[ChatMessage],
+    *,
+    assistant_max_chars: int = DEFAULT_RAW_ASSISTANT_MAX_CHARS,
+    tool_max_bytes: Optional[int] = None,
+) -> List[ChatMessage]:
+    """返回裁剪后的新列表；不修改入参（messages 仍要原样给 extractor）。"""
+    out: List[ChatMessage] = []
+    for m in messages:
+        new_content = trim_raw_body(
+            m.speaker_label(),
+            m.content,
+            assistant_max_chars=assistant_max_chars,
+            tool_max_bytes=tool_max_bytes,
+        )
+        if new_content == m.content:
+            out.append(m)
+            continue
+        out.append(ChatMessage(
+            role=m.role,
+            content=new_content,
+            name=m.name,
+            tool_calls=list(m.tool_calls),
+            tool_call_id=m.tool_call_id,
+            tool_name=m.tool_name,
+        ))
+    return out

hy_memory/utils/token_count.py

@@ -36,7 +36,8 @@ def count_tokens(text: str) -> int:
     enc = _get_encoder()
     if enc:
         try:
-            return len(enc.encode(text))
+            # Quoted control-token spellings are ordinary input text.
+            return len(enc.encode(text, disallowed_special=()))
         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
 
-感谢你参与 One Memory。
+感谢你参与 MemHub。
 
 ## 开发环境
 
@@ -27,3 +27,10 @@ pnpm check
 
 涉及外部源码时，必须记录项目、固定版本或 commit、许可证、采用文件和修改说明。不得提交
 密钥、内部地址、真实对话、个人路径、模型权重或签名证书。
+
+## 界面翻译
+
+新增或修改界面语言时遵循
+[`docs/LOCALIZATION.md`](docs/LOCALIZATION.md)：使用稳定语义 key，保持所有
+locale 的 key 与占位符一致，不翻译用户内容、路径、标识符或外部错误正文。语言
+catalog 与无关产品行为应拆成不同 PR。

memhub/MEMORY.md

@@ -1,97 +1,73 @@
 # Hy Memory 使用与配置
 
-更新：2026-10-12
+更新：2026-10-21
 
-本文说明 MemHub 当前使用的 Hy Memory SDK、配置边界，以及直接使用 SDK 时如何
-write、search，并把搜索结果格式化为可交给模型的 memory text chunk。
+架构边界以 [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md) 为准。
 
-仓库内仍以 One Memory 命名的 Evidence、权限和 Governance 层属于 MemHub 的历史兼容
-模块；产品代码不应绕过这些层直接调用 SDK。本文中的
-原生 SDK 示例主要用于开发、调试和独立验证。
+---
+
+## 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。
 
 ## 当前版本状态
 
-当前源码固定使用：
+当前源码固定使用（以仓库 pin / lockfile 为准）：
 
 ```text
 distribution: hy-memory
-version:      2.0.3
+version:      见 pyproject / lock（文档数字可能滞后）
 mode:         按运行时配置选择
 reader:       hybrid
 ```
 
-仓库 pin、lockfile 和运行时版本守卫均固定到公开的 `hy-memory==2.0.3`。
-MemHub 在本地 Runtime 内嵌入 SDK，但不绕过自身的来源授权、模型授权、Evidence、
-Governance 和撤权边界。
-
 ## MemHub 运行时边界
 
-MemHub 对 SDK 使用以下公开、可复现的本地策略：
+MemHub 通过公开 `HyMemoryClient` 配置使用可复现的本地策略：
 
-- 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。
+- vector / graph / cache / history / coding 等 **一律 SDK config/env**；
+- 模型与 embedding 来自版本化 Model Profile；密钥进安全存储；
+- MemHub 管理库可存 harness/model/队列状态与 **`memory_id` 引用**。
 
-发布包固定应用以下 SDK 行为配置：
+MemHub 不再通过 import-time 环境变量覆盖 SDK 的提取、reconcile、episode、
+intention、few-shot、summary 或去重策略。产品只配置模型/密钥/endpoint、本地
+backend 路径、公开 embedding service，以及每次公开 Client 调用的参数。
 
-| 环境变量 | 值 |
-|---|---|
-| `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 时须自配存储目录与模型端点。
 
 ## 原生 SDK 初始化
 
-下面是独立调试示例。产品代码应使用 One Memory 的 `HyMemoryBridge`，因为它额外提供来源
-授权、模型授权、Evidence 绑定、写后核验、Governance 和撤权保护。
+下面是独立调试示例。
+
+产品代码经 `hy_sdk_runtime.SdkClientHandle` 获取已配置的公开 client；memory I/O
+由 SDK 完成。
 
 ```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/governed-v2/vector"
+config.vector_store.persist_directory = "/path/to/one-memory/hy-memory/vector"
 config.graph_store.provider = "kuzu"
-config.graph_store.db_path = "/path/to/one-memory/hy-memory/governed-v2/graph"
+config.graph_store.db_path = "/path/to/one-memory/hy-memory/graph"
 config.cache.backend = "sqlite"
-config.cache.db_path = "/path/to/one-memory/hy-memory/governed-v2/cache.sqlite3"
+config.cache.db_path = "/path/to/one-memory/hy-memory/cache.sqlite3"
 
 config.llm.provider = "openai"
 config.llm.model = "your-model"
@@ -107,12 +83,11 @@ config.embedder.embedding_dims = 1024
 client = HyMemoryClient(config=config, mode="ultra")
 ```
 
-`embedding_dims` 必须与模型实际输出宽度以及已有向量/图存储一致。更换 embedding 模型、
-端点或维度不能直接复用旧 collection；One Memory 会检测图宽度不一致并拒绝静默重建。
+`embedding_dims` 必须与模型输出及已有向量/图存储一致。
 
 ## Write：写入对话
 
-推荐把一段连续对话作为 OpenAI messages 写入：
+推荐把一段连续对话作为 OpenAI messages 写入；含原文时由 SDK 接管 raw：
 
 ```python
 from datetime import UTC, datetime
@@ -131,47 +106,54 @@ 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；不混入 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；模型和维度不能改变 |
+| `data` | 字符串或 `[{role, content}]` | 对话优先 messages；不混入密钥与隐藏系统提示 |
+| `user_id` / `agent_id` / `session_id` | 隔离与会话键 | 产品侧授权决定合法 scope |
+| `memory_at` | 有时区 datetime | 历史导入用原始发生时间 |
+| `scene` | `chat` / `working` | 明确传入 |
+| `request_id` | 每次写入唯一 | 幂等与追踪 |
+| `metadata` / `meta` | 来源与透传 | 不放秘密 |
 
-返回值至少检查：
+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 = result.get("memory_ids") or []
+memory_ids = list(result.get("memory_ids") or [])
 if result.get("memory_id"):
     memory_ids.append(result["memory_id"])
+# 需要组织或回执时，MemHub 只持久化这些 memory_id。
 ```
 
-不要只相信 `success=True`。One Memory 还会按返回 ID `get()` 回读、核对 request/source/
-Evidence 支持关系，并在 Governance 层记录版本。生产路径不能用直接 `client.add()` 代替这些
-检查。
+以 SDK 合同为准做成功判定；需要写后核验时使用 SDK `get` 回读。缺少所需
+核验能力时扩展 SDK API，不在 MemHub 新建镜像台账。
 
 ### 写入已抽取的记忆
 
-只有输入本身就是已有记忆内容、且原始对话不可用时才使用：
-
 ```python
 result = client.add_extracted(
     ["用户长期偏好简洁、直接的回答。"],
@@ -182,18 +164,30 @@ result = client.add_extracted(
     request_id=str(uuid4()),
     metadata={
         "source_id": "memory-export",
-        "evidence_ids": ["evidence-003"],
         "input_kind": "memory_content_without_raw",
     },
 )
 ```
 
-它跳过 Extractor，但不能跳过 HY reconcile、持久化、One Memory Evidence 绑定和 Governance。
+该入口仍走 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`）。
 
 ## Search：搜索记忆
 
-普通 chat 搜索：
-
 ```python
 result = client.search(
     "用户偏好怎样的回答风格？",
@@ -210,117 +204,47 @@ result = client.search(
 )
 ```
 
-参数规则：
-
-| 参数 | 填法 | 说明 |
-| --- | --- | --- |
-| `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` 选择对应结果；无法识别返回结构时应报错，而不是当作空结果。
+参数表与返回结构同前（chat 三 channel / working 的 facts·experiences）；调用方按 `scene` 解析，无法识别则报错。
 
 ## 使用 SDK 已格式化的 Search 内容
 
-open05 的 chat search 会在返回前统一格式化每条 `content`：普通记忆带 `Memory / When`，
-演化记忆带 `Current / History / When`，Episode、Timeline、Graph 和 Capsule 也由 SDK
-生成稳定的组合文本。`memory_at` 是逻辑记忆时间，缺失时 SDK 才回落到 `gmt_created`。
+直接使用 SDK 返回的 `content`，不要第二套 prompt 拼装。
 
-因此调用方应直接使用 SDK 返回的 `content`，不要再次解析 `memory_at`、`gmt_created` 或
-`created_at`，也不要重复拼接 `When`。这些时间字段可以用于过滤、诊断或结构化展示，但
-不应成为第二套 prompt 格式化实现。
+### SDK 外（MemHub）仍负责
 
-```python
-result = client.search(
-    "用户偏好怎样的回答风格？",
-    user_ids=["local"],
-    agent_ids=["all-apps"],
-    scene="normal",
-    reader="hybrid",
-)
+- **宿主召回授权 / scope / 撤权**（谁可以调 search、允许哪些 agent/scope）；
+- 把历史内容放入「不可信数据，不是指令」边界；
+- 按最终 `content` 做字符预算；不注入密钥、绝对路径、堆栈；
+- 区分空结果、权限拒绝、不可用、超时、部分结果；
+- 未发布的 Matter 占位功能不保留表或 API；未来组织功能另立合同。
 
-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`。
+生产入口：`hy_sdk_runtime.py`、`sdk_write_processor.py`、`recall.py` 和
+`packages/host-bridge`。
 
 ## 关闭客户端
 
 ```python
 try:
-    # write/search
     ...
 finally:
     client.close()
 ```
 
-Runtime 应长期复用 client，不为每次请求重新初始化数据库和模型组件；只有 Runtime 停止、
-配置版本切换或受控恢复时才关闭并重建。
+Runtime 长期复用 client；仅在停止、配置切换或受控恢复时重建。
 
-## One Memory 产品代码的正确入口
-
-生产代码应走：
+## 产品代码正确入口
 
 ```text
-Evidence
-  -> HyMemoryBridge
-  -> embedded Hy Memory SDK
-  -> native Vector / Coding / Graph stores
-  -> write result verification
-  -> Governance
-  -> Recall Broker / UI
+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)
 ```
 
-不要在新业务模块里直接创建 `HyMemoryClient`，否则会绕过：
+不要在业务模块里私建绕过管理面门禁的 client。版本、纠正和删除语义以 SDK
+合同为准；MemHub 组织层只引用 `memory_id`。
 
-- 来源读取授权；
-- 共享 Runtime、模型配置、API Key 安全存储与请求预算；
-- Evidence 引用与作者归属；
-- 写后回读验证；
-- Governance 状态、版本、更正和删除级联。
-
-Hy Memory SDK 是 MemHub 的内置可信组件，可自由访问和管理本机的全部
-Hy Memory 数据。来源授权仍决定哪些宿主数据可以进入本机；宿主 Recall Grant
-仍决定哪些外部 AI 应用可以读取治理后的记忆。这两类边界不限制内置 SDK 的本地 CRUD。
+Hy Memory SDK 是 MemHub 内置可信引擎，管理本机 Hy Memory 数据。  
+来源授权决定哪些宿主数据可进入写入路径；宿主 Recall Grant 决定外部应用可读范围。  
+这两类边界 **不** 意味着 MemHub 再存一套 memory 实体。

memhub/PRIVACY.md

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

memhub/README.md

@@ -18,13 +18,13 @@ If you run into a problem, please open an Issue with the version, platform,repro
 
 ## 发行与平台合同
 
-公共 Python SDK 为 `hy-memory==2.0.3`。MemHub 源码版本为 `1.0.3`
-（build 7），GitHub 仓库为
+源码当前固定使用公开 PyPI 正式版 `hy-memory==2.0.9`。MemHub 源码版本为 `1.0.5`
+（build 36），GitHub 仓库为
 [`Tencent-Hunyuan/Hy-Memory`](https://github.com/Tencent-Hunyuan/Hy-Memory)，npm 包名为
 `memhub-cli`。当前代码架构见
 [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md)。
 
-`v1.0.3` 的发行目标是 Linux x64/arm64 Runtime 与 macOS arm64/x64 App 和 Runtime。
+`v1.0.5` 的发行目标是 Linux x64/arm64 Runtime 与 macOS arm64 App 和 Runtime。
 Linux 制品由 GitHub Actions 在原生架构 runner 上构建并完成生命周期验收；macOS
 制品由发行流水线完成 Developer ID 签名、公证和验收后手动上传。Windows 不支持。
 只有同时出现在 GitHub Release 与 `release-manifest.json` 中、且通过公开校验的制品才属于
@@ -37,23 +37,27 @@ Linux 制品由 GitHub Actions 在原生架构 runner 上构建并完成生命
 ## 核心原则
 
 - 一次安装、一个 Runtime、一份数据、多种客户端。
-- Python Core 是唯一记忆数据面和唯一业务数据库写入者。
+- Hy Memory SDK 是 memory/raw/vector/graph/coding 数据面的唯一权威；Python Core
+  管理授权、模型、异步队列和 Runtime 状态。
 - 来源读取、模型处理和宿主读取是相互独立的授权边界。
-- 正式记忆链路保持 `Evidence -> Hy Memory -> Governance -> Matters/Wiki`。
+- 正式写链路为 `memory_write_jobs -> SDK add() -> raw/memory ID receipt`。
 - 产品不包含屏幕、Accessibility / AXTree、OCR、键鼠、剪贴板或后台录音采集。
 
 ## 仓库结构
 
-- `apps/core`：Python / FastAPI Kernel，负责 Evidence、Hy Memory、治理、检索与 API。
+- `apps/core`：Python / FastAPI Kernel，负责授权、模型、队列、SDK Runtime 边界与 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)。
 
@@ -105,15 +109,16 @@ 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 停止且二次确认精确路径后
-才会删除数据。
+默认保留 Memory。只有独立的 `memhub delete-data` 在 Runtime 停止、显式加 `--yes` 并用
+`--confirm <数据目录>` 再写一遍同一个目录后才会删除数据（不加参数只预览要删除的目录）。`memhub stop` 停止受管服务时也会关闭
+登录自动启动，再次 `memhub start` 会恢复。
 
 当前平台能力和安装边界以源码、CI 与发布说明为准。未完成真机验收的平台不会仅凭跨平台
 测试宣称可用。
 
 ## Hy Memory
 
-当前开发依赖固定为公开 PyPI 包 `hy-memory==2.0.3`。SDK 配置、权限边界及 search
+SDK 依赖固定为公开 PyPI 正式版 `hy-memory==2.0.9`。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-17T13:52:48Z",
+  "documentNamespace": "https://one-memory.local/spdx/2026-10-22T13:18:16Z",
   "creationInfo": {
-    "created": "2026-10-17T13:52:48Z",
+    "created": "2026-10-22T13:18:16Z",
     "creators": [
       "Tool: one-memory-generate-sbom"
     ]
@@ -88,6 +88,23 @@
         }
       ]
     },
+    {
+      "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",
@@ -2335,7 +2352,7 @@
     {
       "SPDXID": "SPDXRef-Package-hy-memory",
       "name": "hy-memory",
-      "versionInfo": "2.0.4",
+      "versionInfo": "2.0.9",
       "downloadLocation": "NOASSERTION",
       "filesAnalyzed": false,
       "licenseConcluded": "Apache-2.0",
@@ -2380,6 +2397,11 @@
       "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-17T13:52:48Z
+Generated from the installed dependency tree on 2026-10-22T13:18:16Z
 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.4
+## hy-memory 2.0.9
 
 License: Apache-2.0
 
@@ -112,12 +112,13 @@ Adaptation boundary:
 
 No Memmy brand, icon, font or mascot assets are distributed.
 
-## JavaScript (npm) — 10 packages
+## JavaScript (npm) — 11 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.4",
+  "version": "1.0.5",
   "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,18 +21,21 @@ const TOKEN = "probe-token-not-a-real-credential";
 
 const MEMORY = {
   memory_id: "probe-1",
-  user_id: "local",
-  kind: "chat",
-  status: "confirmed",
   content: "部署脚本要先跑 verify_merge_plan。",
-  scopes: ["all-apps"],
-  evidence_ids: ["probe-e1"],
-  origin: "extracted",
+  layer: "l2_fact",
+  status: "active",
+  is_latest: true,
+  supersedes: [],
+  superseded_by: [],
   tags: [],
-  revision: 2,
-  created_at: "2026-09-19T00:00:00Z",
-  updated_at: "2026-09-19T00:00:00Z",
-  deleted_at: null,
+  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,
 };
 
 const ROUTES = new Map([
@@ -124,26 +127,6 @@ 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",
     [
@@ -159,28 +142,20 @@ const ROUTES = new Map([
       },
     ],
   ],
-  ["/api/v1/home-summary", { memory_count: 1, latest: null, observed_at: "T" }],
   [
-    "/api/v1/memory-library",
-    { total: 1, offset: 0, limit: 100, items: [MEMORY] },
-  ],
-  [
-    "/api/v1/memories/probe-1",
+    "/api/v2/home-summary",
     {
-      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" }],
+      schema_version: 2,
+      memory_count: 1,
+      latest: MEMORY,
+      observed_at: "2026-09-19T00:00:01Z",
     },
   ],
+  [
+    "/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,11 +29,8 @@ const REQUIRED_COMMAND_SURFACE = [
   "sources",
   "sync",
   "memories",
-  "calls",
-  "import-file",
-  "notes",
-  "extraction",
-  "graph",
+  "profile",
+  "graph-width",
   "models",
   "host",
   "doctor",
@@ -51,20 +48,17 @@ const REQUIRED_COMMAND_SURFACE = [
   "uninstall",
   "delete-data",
   "recall",
-  "setup",
   "scan",
   "progress",
   "jobs",
-  "processing",
-  "path",
+  "scan-roots",
   "adapter",
   "write",
-  "task",
   "serve",
 ];
 
 const REQUIRED_MARKERS = [
-  "backup_restore_confirmation_required",
+  "backup_restore_confirmation_mismatch",
   "backup_restore_runtime_state_unknown",
   "backup_restore_maintenance_identity_invalid",
   "runtime_service_activation_unverified",
@@ -81,17 +75,18 @@ const REQUIRED_MARKERS = [
  * exact literal the catalog usage string contains.
  */
 const REQUIRED_SUBCOMMANDS = [
-  { 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: "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: "models", marker: "memhub models edit" },
   { command: "models", marker: "memhub models activate" },
-  { command: "processing", marker: "memhub processing extract" },
+  { command: "sources", marker: "memhub sources connect" },
   { command: "jobs", marker: "memhub jobs start" },
   { command: "jobs", marker: "memhub jobs <pause|resume|cancel>" },
 ];
@@ -103,83 +98,30 @@ 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: "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: "memories_delete_apply",
+    args: ["memories", "delete", "m-1", "--yes"],
   },
   {
     name: "graph_width_apply",
-    args: ["graph", "width", "--decision", "keep_existing", "--confirm"],
+    args: ["graph-width", "--decision", "keep_existing"],
   },
   {
-    name: "processing_extract_apply",
-    args: ["processing", "extract", "--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: "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",
-    ],
+    name: "sources_connect_import",
+    args: ["sources", "connect", "codex", "--import"],
   },
 ];
 

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

@@ -119,6 +119,7 @@ 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);
@@ -165,6 +166,7 @@ describe("A19 batch execution", () => {
       readerFor([]),
       operations,
       planned.notFound,
+      { confirmOverrides: false },
     );
     expect(document.state).toBe("partial");
     const byId = Object.fromEntries(
@@ -206,6 +208,7 @@ describe("A19 batch execution", () => {
       readerFor([]),
       operations,
       [],
+      { confirmOverrides: false },
     );
     expect(document.sources.every((row) => row.status === "failed")).toBe(true);
     expect(
@@ -249,6 +252,7 @@ describe("A19 batch execution", () => {
       readerFor([]),
       operations,
       [],
+      { confirmOverrides: false },
     );
     const busy = document.sources.find((row) => row.source_id === "cursor");
     expect(document.state).toBe("partial");
@@ -288,6 +292,7 @@ describe("A19 batch execution", () => {
       readerFor([]),
       operations,
       planned.notFound,
+      { confirmOverrides: false },
     );
     const notFoundRow = document.sources.find(
       (row) => row.source_id === "cursor",
@@ -296,3 +301,82 @@ 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,4 +1,5 @@
-/** A19: one-shot scan/import of every *detected* source.
+/** A19: one-shot connect/import of every *detected* source
+ * (`sources connect --all-detected --import`).
  *
  * 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
@@ -37,13 +38,16 @@ export interface BatchSourceRow {
 export interface BatchScanDocument {
   schema_version: 1;
   product: string;
-  command: "scan" | "init";
+  command: "sources connect";
   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;
 }
 
@@ -118,12 +122,39 @@ export async function planBatchImport(reader: CoreReader): Promise<
 
 /** Run the batch connect once and fold the per-source receipt into rows. */
 export async function executeBatchImport(
-  candidates: readonly SourceConnectionCandidate[],
+  detected: 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({
@@ -141,9 +172,9 @@ export async function executeBatchImport(
           : [[candidate.source_id, candidate.candidate_revision]],
       ),
     ),
-    confirmEnvironmentOverrides: candidates.some(
-      (candidate) => candidate.requires_override_confirmation,
-    ),
+    confirmEnvironmentOverrides:
+      options.confirmOverrides &&
+      candidates.some((candidate) => candidate.requires_override_confirmation),
     fullRescan: false,
     onboarding: true,
     enableSync: true,
@@ -154,7 +185,7 @@ export async function executeBatchImport(
     return {
       schema_version: 1,
       product: PRODUCT,
-      command: "scan",
+      command: "sources connect",
       state: result.state,
       request_id: requestId,
       accepted_source_ids: [],
@@ -168,6 +199,7 @@ export async function executeBatchImport(
         failure_reason: result.code,
       })),
       not_found_source_ids: [...notFound],
+      ...overrideFields,
       code: result.code,
     };
   }
@@ -254,7 +286,7 @@ export async function executeBatchImport(
   return {
     schema_version: 1,
     product: PRODUCT,
-    command: "scan",
+    command: "sources connect",
     state:
       failedCount === 0
         ? "committed"
@@ -270,6 +302,7 @@ export async function executeBatchImport(
     accepted_source_ids: accepted,
     sources: rows,
     not_found_source_ids: [...notFound],
+    ...overrideFields,
   };
 }
 
@@ -301,5 +334,10 @@ export function renderBatchScanText(document: BatchScanDocument): string {
       : document.state === "partial"
         ? `部分完成：${document.accepted_source_ids.length} 个成功，其余见上方`
         : `未完成：${document.code ?? "unknown"}`;
-  return `${summary}\n${lines.join("\n")}\n`;
+  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`;
 }

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

@@ -0,0 +1,371 @@
+// 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,6 +1,7 @@
-import { mkdtemp, readdir, rm, writeFile } from "node:fs/promises";
+import { mkdtemp, readdir, readFile, 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";
 
@@ -29,6 +30,27 @@ 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 = "";
@@ -74,6 +96,25 @@ 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 () => {
@@ -121,10 +162,54 @@ it("never emits a secret from a malformed manually written event", async () => {
     command: "logs",
     state: "empty",
     events: 0,
-    invalid_lines: 1,
+    invalid_lines: 0,
+    unrecognized_lines: 1,
   });
 });
 
+// After an upgrade the files still hold an older build's records. They are
+// whole JSON lines the reader leaves out, not damage, so the text output must
+// not warn about them; only a line that is not JSON is called damaged.
+it("warns only about lines that are not JSON, not about older records", async () => {
+  const dataDir = await fixture();
+  const older = {
+    schema_version: 0,
+    service: "desktop",
+    component: "desktop.lifecycle",
+    event: "desktop.started",
+  };
+  await writeFile(
+    path.join(dataDir, "logs", "diagnostic-desktop.jsonl"),
+    `${JSON.stringify(older)}\n${JSON.stringify({ ...older, schema_version: 1 })}\n`,
+    { mode: 0o600 },
+  );
+  let stdout = "";
+  let stderr = "";
+  vi.spyOn(process.stdout, "write").mockImplementation((value) => {
+    stdout += String(value);
+    return true;
+  });
+  vi.spyOn(process.stderr, "write").mockImplementation((value) => {
+    stderr += String(value);
+    return true;
+  });
+
+  expect(await run(["logs"], { ONE_MEMORY_DATA_DIR: dataDir })).toBe(0);
+  expect(stdout).toContain("core.start_failed");
+  expect(stdout).not.toContain("损坏");
+  expect(stderr).toBe("");
+
+  await writeFile(
+    path.join(dataDir, "logs", "diagnostic-cli.jsonl"),
+    '{"schema_version": 1, "event": \n',
+    { mode: 0o600 },
+  );
+  stdout = "";
+  expect(await run(["logs"], { ONE_MEMORY_DATA_DIR: dataDir })).toBe(0);
+  expect(stdout).toContain("跳过 1 行损坏的诊断记录。");
+  expect(stderr).toBe("memhub: 跳过 1 行损坏的诊断记录。\n");
+});
+
 it("rejects invalid filters without touching the log directory", async () => {
   const dataDir = path.join(
     await mkdtemp(path.join(os.tmpdir(), "om-cli-no-log-")),

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

@@ -1,9 +1,18 @@
-import { mkdtemp, readdir, readFile, realpath, rm } from "node:fs/promises";
+import {
+  mkdir,
+  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";
@@ -57,6 +66,11 @@ 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,
@@ -126,6 +140,7 @@ 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,
@@ -784,7 +799,7 @@ describe("public One Memory CLI", () => {
       }
     });
 
-    it("upgrade failure restarts the restored artifact with the same data identity", async () => {
+    it("upgrade restart failure keeps the new version and never restarts the old one", async () => {
       vi.clearAllMocks();
       runtimeMocks.planCliLink.mockResolvedValueOnce({
         schema_version: 1,
@@ -826,25 +841,27 @@ describe("public One Memory CLI", () => {
         command: "upgrade",
         code: "restart failed",
       });
-      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",
-        });
-      }
+      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",
+      });
     });
 
     // 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("rolls back and fails when the upgraded Runtime never becomes healthy", async () => {
+    it("fails without rolling back when the upgraded Runtime never becomes healthy", async () => {
       vi.clearAllMocks();
       runtimeMocks.planCliLink.mockResolvedValueOnce({
         schema_version: 1,
@@ -884,9 +901,219 @@ describe("public One Memory CLI", () => {
         command: "upgrade",
         code: "upgrade_health_check_failed",
       });
-      // Rolled back to the previous version and restarted it.
+      // 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();
       expect(runtimeMocks.rollbackLocalInstall).toHaveBeenCalledOnce();
-      expect(runtimeMocks.restartUserService).toHaveBeenCalledTimes(2);
+      // 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();
     });
 
     it("reports success once the upgraded Runtime is healthy", async () => {
@@ -1384,7 +1611,7 @@ describe("public One Memory CLI", () => {
     expect(JSON.parse(output.value()).apply).toBe(true);
   });
 
-  it("rolls back the distribution when service installation fails", async () => {
+  it("keeps the distribution when service installation fails after the migration ran", async () => {
     runtimeMocks.applyLocalInstall.mockResolvedValueOnce({
       schema_version: 1,
       source: "/tmp/distribution",
@@ -1425,13 +1652,14 @@ describe("public One Memory CLI", () => {
       command: "install",
       status: "error",
       code: "service failed",
+      rolled_back: false,
     });
-    expect(runtimeMocks.rollbackLocalInstall).toHaveBeenCalledOnce();
-    expect(runtimeMocks.rollbackCliLink).toHaveBeenCalledOnce();
-    expect(aliasMocks.rollbackManagedCliLink).toHaveBeenCalledTimes(2);
+    expect(runtimeMocks.rollbackLocalInstall).not.toHaveBeenCalled();
+    expect(runtimeMocks.rollbackCliLink).not.toHaveBeenCalled();
+    expect(aliasMocks.rollbackManagedCliLink).not.toHaveBeenCalled();
   });
 
-  it("upgrades only an existing managed CLI and rolls back a failed restart", async () => {
+  it("upgrades only an existing managed CLI and keeps it after a failed restart", async () => {
     runtimeMocks.planCliLink.mockResolvedValueOnce({
       schema_version: 1,
       platform: "linux",
@@ -1471,7 +1699,7 @@ describe("public One Memory CLI", () => {
       status: "error",
       code: "restart failed",
     });
-    expect(runtimeMocks.rollbackLocalInstall).toHaveBeenCalledOnce();
+    expect(runtimeMocks.rollbackLocalInstall).not.toHaveBeenCalled();
     expect(runtimeMocks.installCliLink).not.toHaveBeenCalled();
   });
 
@@ -1783,19 +2011,11 @@ describe("stopped Runtime is exit 3, not a usage error", () => {
     ["path", "list", "--json"],
     ["adapter", "list", "--json"],
     ["task", "--id", "nope", "--json"],
-    [
-      "write",
-      "--session",
-      "s",
-      "--from",
-      "1",
-      "--to",
-      "1",
-      "--evidence",
-      "e",
-      "--json",
-    ],
-    ["backup", "create", "--target", "/tmp/x", "--yes", "--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"],
   ])("%s ... --json exits 3 with runtime_not_running", async (...argv) => {
     const streams = captureStreams();
     let code: number;
@@ -1805,7 +2025,9 @@ describe("stopped Runtime is exit 3, not a usage error", () => {
       streams.restore();
     }
     expect(code!).toBe(3);
-    const document = JSON.parse(streams.stderr());
+    // A result, not an error: on stdout like every other --json document.
+    expect(streams.stderr()).toBe("");
+    const document = JSON.parse(streams.stdout());
     expect(document).toMatchObject({
       code: "runtime_not_running",
       exit_code: 3,
@@ -1814,6 +2036,48 @@ 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) => {
@@ -1898,6 +2162,189 @@ 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.
@@ -2007,7 +2454,7 @@ describe("install gates on Runtime readiness", () => {
     });
   }
 
-  it("fails and rolls back when the installed Runtime never becomes ready", async () => {
+  it("fails without rolling back when the installed Runtime never becomes ready", async () => {
     vi.clearAllMocks();
     stubInstallPlan();
     const streams = captureStreams();
@@ -2036,10 +2483,10 @@ describe("install gates on Runtime readiness", () => {
     }
     expect(code!).toBe(1);
     expect(streams.stderr()).toContain("install_runtime_not_ready");
-    expect(runtimeMocks.rollbackLocalInstall).toHaveBeenCalledOnce();
+    expect(runtimeMocks.rollbackLocalInstall).not.toHaveBeenCalled();
     expect(
       lifecycleMocks.rollbackPreparedServiceInstall,
-    ).toHaveBeenCalledOnce();
+    ).not.toHaveBeenCalled();
   });
 
   it("takes CLI ownership after a successful install over an App-owned Runtime", async () => {
@@ -2084,7 +2531,7 @@ describe("install gates on Runtime readiness", () => {
     }
   });
 
-  it("restores App ownership before relaunching the old Runtime after install failure", async () => {
+  it("never hands the home back to the App Runtime after the migration ran", async () => {
     vi.clearAllMocks();
     stubInstallPlan();
     const root = await mkdtemp(path.join(tmpdir(), "memhub-cli-owner-"));
@@ -2094,14 +2541,6 @@ 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(
@@ -2124,15 +2563,114 @@ 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: "app",
+        owner: "cli",
       });
+      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();
@@ -2212,7 +2750,8 @@ describe("ui wires the Core session contract without token leakage", () => {
     } finally {
       output.restore();
     }
-    expect(code!).toBe(4);
+    // A stopped Runtime is exit 3, like every other command.
+    expect(code!).toBe(3);
     const document = JSON.parse(output.value());
     expect(document).toMatchObject({
       schema_version: 1,
@@ -2241,6 +2780,120 @@ 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",
@@ -2357,7 +3010,7 @@ describe("backup restore drives the Core managed-restore contract", () => {
     });
   });
 
-  it("requires --confirm to repeat the exact source path", async () => {
+  it("refuses a legacy --confirm that does not repeat the source path", async () => {
     const maintenance = vi.fn();
     const output = captureStdout();
     let code: number;
@@ -2385,7 +3038,7 @@ describe("backup restore drives the Core managed-restore contract", () => {
       command: "backup",
       verb: "restore",
       state: "rejected",
-      code: "backup_restore_confirmation_required",
+      code: "backup_restore_confirmation_mismatch",
     });
   });
 
@@ -2537,7 +3190,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", "--full-rescan", "--confirm-overrides", "--dry-run"])(
+  it.each(["--import", "--confirm-overrides"])(
     "refuses a repeated init %s flag",
     async (flag) => {
       expect(await run(["init", "--source", "codex", flag, flag], {})).toBe(2);
@@ -2610,12 +3263,25 @@ describe("init onboarding", () => {
     },
   );
 
-  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);
+  // `--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();
+    }
   });
 });
 

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

@@ -58,10 +58,22 @@ 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 消费。",
 };
+/** Global to the memory commands: whose memories are read or written. */
+const USER_ID_OPTION: CommandOption = {
+  flag: "--user-id <id>",
+  summary:
+    "读写哪个用户的记忆，默认 local（App 用的就是 local）。1–64 位字母、数字、点、下划线或连字符；其他用户的记忆来自用 sources connect hermes --user-id 接入的 Hermes profile。",
+};
 const WATCH_OPTION: CommandOption = {
   flag: "--watch",
   summary: "串行持续刷新；Ctrl-C 只停止观察，不停止 Runtime。",
@@ -70,21 +82,6 @@ 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,
@@ -154,55 +151,77 @@ 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: [EXIT_OK, EXIT_FAILED],
+    exit_codes: USAGE_EXITS,
   },
   {
     name: "start",
-    summary: "启动本机 Runtime；已有通过身份校验的实例时只连接，不重复启动。",
+    summary:
+      "启动本机 Runtime；已有通过身份校验的实例时只连接，不重复启动。受管服务会同时恢复登录时自动启动。",
     usage: "memhub start [--json]",
     options: [JSON_OPTION],
-    exit_codes: [EXIT_OK, EXIT_FAILED, EXIT_RUNTIME_STOPPED],
+    exit_codes: USAGE_EXITS,
   },
   {
     name: "stop",
-    summary: "停止通过身份校验的本机 Runtime；身份不明确时不发送信号。",
+    summary:
+      "停止通过身份校验的本机 Runtime；身份不明确时不发送信号。受管服务（launchd/systemd、App）停止后登录时也不会自动启动，直到再次运行 memhub start。",
     usage: "memhub stop [--json]",
     options: [JSON_OPTION],
-    exit_codes: [EXIT_OK, EXIT_FAILED],
+    exit_codes: USAGE_EXITS,
   },
   {
     name: "restart",
     summary: "先停止再启动本机 Runtime，两步串行执行。",
     usage: "memhub restart [--json]",
     options: [JSON_OPTION],
-    exit_codes: [EXIT_OK, EXIT_FAILED],
+    exit_codes: USAGE_EXITS,
   },
   {
     name: "status",
     summary: "只读查询 Runtime 运行状态；不启动服务、不迁移数据、不改配置。",
     usage: "memhub status [--watch] [--interval <seconds>] [--json]",
     options: [WATCH_OPTION, INTERVAL_OPTION, JSON_OPTION],
-    exit_codes: [EXIT_OK, EXIT_FAILED, EXIT_RUNTIME_STOPPED],
+    exit_codes: RUNTIME_EXITS,
   },
   {
     name: "doctor",
-    summary: "按诊断口径做同样的只读检查；默认不修复任何东西。",
+    summary:
+      "按诊断口径做只读检查并给出修复建议；默认不修复任何东西。Runtime 未运行时 exit 3。",
     usage: "memhub doctor [--json]",
     options: [JSON_OPTION],
-    exit_codes: [EXIT_OK, EXIT_FAILED, EXIT_RUNTIME_STOPPED],
+    exit_codes: RUNTIME_EXITS,
   },
   {
     name: "logs",
     summary:
-      "读取本机脱敏诊断日志；logs export 会把排查包直接存到下载目录。默认显示最近一次会话的 200 条事件。",
+      "读取本机脱敏诊断日志；logs export 会把排查包（含系统崩溃报告）直接存到下载目录。默认显示最近一次会话的 200 条事件。",
     usage:
-      "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]",
+      "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]",
     options: [
       {
         flag: "--since <time>",
@@ -226,64 +245,56 @@ export const COMMANDS: readonly CommandDescriptor[] = [
           "以 NDJSON 输出到 stdout（每行一个脱敏事件；非单 JSON 文档），供脚本与 Agent 消费。",
       },
     ],
-    exit_codes: [EXIT_OK, EXIT_FAILED, EXIT_USAGE],
+    exit_codes: USAGE_EXITS,
   },
   {
     name: "init",
     summary:
-      "首次接入：选择来源 → 选择是否导入历史。接入即开启该 Harness 的处理；后续可用 sync pause/resume 冻结或恢复。在终端且不带 --source 时进入交互引导（默认全选）；非终端或加 --json 时不读 stdin、只列出可用来源和下一步。--all-detected 一次接入所有已检测来源。",
+      "首次接入引导。在终端里（未加 --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。Hermes 的每个 profile 是一个独立用户：用 --user-id 和 --root 接入，授权并导入历史（会自动排除 ~/.hermes/profiles/**，各用户互不读取）。",
     usage:
-      "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]",
+      "memhub sources list [--json]\n            memhub sources connect <id> [<id> ...] [--import] [--confirm-overrides] [--request-id <uuid>] [--json]\n            memhub sources connect hermes --user-id <id> --root <path> [--import] [--request-id <uuid>] [--json]\n            memhub sources connect --all-detected [--import] [--confirm-overrides] [--json]\n            memhub sources receipt <request-id> [--json]",
     options: [
       {
-        flag: "--source <id>",
-        summary: "要接入的来源，可重复；终端下不给则进入交互引导。",
+        flag: "--import",
+        summary:
+          "接入后立即导入历史会话并开启持续同步；不加时只授权，处理保持冻结。",
+      },
+      {
+        flag: "--user-id <id>",
+        summary:
+          "只用于 hermes：这条接入属于哪个用户（默认 local）。和 --root 一起接入一个 Hermes profile，例如 --user-id wife --root ~/.hermes/profiles/wife；其他来源只能是 local。",
+      },
+      {
+        flag: "--root <path>",
+        summary:
+          "只用于 hermes：读取的根目录（~ 会展开为主目录）。默认是 Hermes 自己的目录 ~/.hermes。",
       },
       {
         flag: "--all-detected",
         summary:
-          "接入并（加 --import 时）导入全部 location_state=found 的来源。",
-      },
-      {
-        flag: "--import",
-        summary: "接入后立即导入该来源的历史会话（默认只接入不导入）。",
-      },
-      {
-        flag: "--dry-run",
-        summary: "只出计划，不接入也不导入；用于先看会做什么。",
-      },
-      {
-        flag: "--full-rescan",
-        summary: "导入时忽略既有游标做全量重扫。",
+          "接入全部已检测到（location_state=found）的来源；与具体来源互斥。",
       },
       {
         flag: "--confirm-overrides",
-        summary: "确认接受环境覆盖类来源（如 DSH_HOME 指定的目录）。",
+        summary:
+          "确认接受目录来自环境变量覆盖的来源（如 DSH_HOME 指定的目录）；不加时这些来源被拒绝（指定来源时）或跳过并列出（--all-detected 时）。",
       },
-      JSON_OPTION,
-    ],
-    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 次。",
+        flag: "--request-id <uuid>",
+        summary:
+          "--import 的幂等键；用同一个 id 重试只会读回第一次的回执，不会重复导入。",
       },
       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],
+    exit_codes: RUNTIME_EXITS,
   },
   {
     name: "sync",
@@ -297,7 +308,7 @@ export const COMMANDS: readonly CommandDescriptor[] = [
       },
       JSON_OPTION,
     ],
-    exit_codes: [EXIT_OK, EXIT_FAILED, EXIT_USAGE, EXIT_RUNTIME_STOPPED],
+    exit_codes: RUNTIME_EXITS,
   },
   {
     name: "progress",
@@ -318,17 +329,17 @@ export const COMMANDS: readonly CommandDescriptor[] = [
       INTERVAL_OPTION,
       JSON_OPTION,
     ],
-    exit_codes: [EXIT_OK, EXIT_FAILED, EXIT_USAGE, EXIT_RUNTIME_STOPPED],
+    exit_codes: RUNTIME_EXITS,
   },
   {
     name: "jobs",
     summary:
-      "启动或控制单个导入任务：start 创建 history/sync 作业；pause/resume/cancel 控制已有作业。所有写操作先出计划，必须显式 --confirm；list/show 为只读。",
+      "查看或控制导入任务：start 创建 history/sync 任务；pause/resume/cancel 控制已有任务。都直接执行。",
     usage:
       "memhub jobs list [--json]\n" +
       "            memhub jobs show <job-id> [--json]\n" +
-      "            memhub jobs start --source <id> [--operation <history|sync>] [--confirm] [--json]\n" +
-      "            memhub jobs <pause|resume|cancel> --job <id> [--confirm] [--json]",
+      "            memhub jobs start --source <id> [--operation <history|sync>] [--json]\n" +
+      "            memhub jobs <pause|resume|cancel> --job <id> [--json]",
     options: [
       {
         flag: "--source <id>",
@@ -336,192 +347,117 @@ export const COMMANDS: readonly CommandDescriptor[] = [
       },
       {
         flag: "--operation <history|sync>",
-        summary: "start 的导入类型，默认 history。",
+        summary:
+          "start 的导入类型，默认 history；sync 与 scan --source 相同，立即增量同步一次。",
       },
       {
         flag: "--job <id>",
         summary: "pause/resume/cancel 的目标导入任务。",
       },
-      DIRECT_CONFIRM_OPTION,
       JSON_OPTION,
     ],
-    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],
+    exit_codes: RUNTIME_EXITS,
   },
   {
     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 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]",
+      "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]",
     alternative_usage: "memhub models setup",
     options: [
       {
         flag: "--config-file <path>",
-        summary: "不含 api_key 的有界 JSON 模型配置。",
+        summary:
+          "有界 JSON 模型配置，不能含 api_key；edit 的补丁必须带 expected_revision。",
       },
-      PLAN_FILE_OPTION,
-      EXPLICIT_CONFIRM_OPTION,
       {
         flag: "--api-key-file <path>",
-        summary: "从 regular file 读取凭据；内容不进入参数、输出或错误。",
+        summary: "从属主专用的普通文件读取凭据；内容不进入参数、输出或错误。",
       },
+      {
+        flag: "--activate",
+        summary: "add 成功后把新配置设为当前使用。",
+      },
+      DESTRUCTIVE_CONFIRM_OPTION,
       JSON_OPTION,
     ],
-    exit_codes: [EXIT_OK, EXIT_FAILED, EXIT_USAGE, EXIT_RUNTIME_STOPPED],
+    exit_codes: RUNTIME_EXITS,
   },
   {
     name: "memories",
     summary:
-      "列出/查看记忆，或生成并显式确认带版本与 request identity 的治理操作计划。",
+      "列出、搜索、查看、添加、修改或物理删除记忆（对话、工作、编码三个场景）。add 和 App 的「添加记忆」是同一个入口；delete 不可逆，需 --yes。",
     usage:
-      "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]",
+      "memhub memories list [--scene <all|chat|working|coding>] [--source <id>] [--query <text>] [--status <state>] [--offset <n>] [--limit <n>] [--user-id <id>] [--json]\n            memhub memories show <memory-id> [--kind <kind>] [--variant <variant>] [--user-id <id>] [--json]\n            memhub memories add <text> [--request-id <uuid>] [--user-id <id>] [--json]\n            memhub memories add --content-file <path> [--request-id <uuid>] [--user-id <id>] [--json]\n            memhub memories add-status <request-id> [--user-id <id>] [--json]\n            memhub memories update <memory-id> --content-file <path> [--kind <kind>] [--variant <variant>] [--task <text>] [--user-id <id>] [--json]\n            memhub memories delete <memory-id> [--kind <kind>] [--variant <variant>] [--yes] [--user-id <id>] [--json]",
     options: [
+      {
+        flag: "--scene <all|chat|working|coding>",
+        summary: "只列一个场景，默认 all。working/coding 列的是该场景的经验。",
+      },
+      { flag: "--source <id>", summary: "只列某个来源写入的记忆。" },
       {
         flag: "--query <text>",
         summary:
-          "按内容过滤；会出现在 shell 历史里，敏感词请改用 --query-file。",
-      },
-      {
-        flag: "--query-file <path>",
-        summary: "从文件读取过滤词，避免查询内容进入命令行历史。",
+          "关键词搜索（只搜 active 记忆，在最相关的一批里匹配所有关键词，输出 search_window 时表示可能少计）。",
       },
       {
         flag: "--status <state>",
-        summary: `记忆状态，取值 ${MEMORY_STATUSES.join("、")}。`,
+        summary: `记忆状态，取值 ${MEMORY_STATUSES.join("、")}，默认 active。`,
       },
-      { 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: "--kind <chat|working|coding|schema|intention>",
-        summary: "新增记忆的类型，默认 chat。",
+        flag: "--task <text>",
+        summary: "update 经验（--kind experience）时同时改写 task。",
       },
       {
-        flag: "--scope <scope>",
-        summary: "记忆使用范围，可重复；private 必须独占。",
-      },
-      {
-        flag: "--evidence <id>",
-        summary: "新增记忆引用的 Evidence ID，可重复。",
-      },
-      PLAN_FILE_OPTION,
-      EXPLICIT_CONFIRM_OPTION,
-      JSON_OPTION,
-    ],
-    exit_codes: [EXIT_OK, EXIT_FAILED, EXIT_USAGE, EXIT_RUNTIME_STOPPED],
-  },
-  {
-    name: "calls",
-    summary:
-      "清除本机调用记录；不可逆删除，默认只出计划，必须显式 --confirm 才执行。",
-    usage:
-      "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>",
+        flag: "--request-id <uuid>",
         summary:
-          "要上传的普通文件（非符号链接，<=128 MiB，.zip/.json/.md/.txt）。",
+          "add 的幂等键；用同一个 id 重试只会读回第一次的结果，不会重复添加。不给时自动生成并输出。",
       },
-      {
-        flag: "--kind <kind>",
-        summary:
-          "输入类型，默认 raw_conversation；memory_content 用于记忆正文。",
-      },
-      DIRECT_CONFIRM_OPTION,
+      DESTRUCTIVE_CONFIRM_OPTION,
+      USER_ID_OPTION,
       JSON_OPTION,
     ],
-    exit_codes: [EXIT_OK, EXIT_FAILED, EXIT_USAGE, EXIT_RUNTIME_STOPPED],
+    exit_codes: RUNTIME_EXITS,
   },
   {
-    name: "notes",
+    name: "profile",
+    summary: "读取 SDK 组装后的用户长期画像（L0 + 已启用的长期画像补充）。",
+    usage: "memhub profile [--user-id <id>] [--json]",
+    options: [USER_ID_OPTION, JSON_OPTION],
+    exit_codes: RUNTIME_EXITS,
+  },
+  {
+    name: "graph-width",
     summary:
-      "端内新增记忆（memory-notes）：从普通文件新增，或显式确认后处理已有笔记。",
+      "嵌入维度变化、图谱宽度不匹配时的处置决定。keep_existing 与 export_first 直接执行；rebuild_with_new 会归档旧图谱并重建，需 --yes。",
     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]",
+      "memhub graph-width --decision <keep_existing|export_first|rebuild_with_new> [--yes] [--json]",
     options: [
       {
         flag: "--decision <decision>",
         summary:
-          "keep_existing（保持）、export_first（先导出）、rebuild_with_new（导出后重建）。",
+          "keep_existing（保持现有图谱）、export_first（先导出）、rebuild_with_new（导出后归档旧图谱并按新维度重建）。",
+      },
+      {
+        ...DESTRUCTIVE_CONFIRM_OPTION,
+        summary: "rebuild_with_new 必须加；其它决定不需要。",
       },
-      DIRECT_CONFIRM_OPTION,
       JSON_OPTION,
     ],
-    exit_codes: [EXIT_OK, EXIT_FAILED, EXIT_USAGE, EXIT_RUNTIME_STOPPED],
+    exit_codes: RUNTIME_EXITS,
   },
   {
     name: "host",
@@ -549,14 +485,14 @@ export const COMMANDS: readonly CommandDescriptor[] = [
       },
       JSON_OPTION,
     ],
-    exit_codes: [EXIT_OK, EXIT_FAILED, EXIT_USAGE, EXIT_RUNTIME_STOPPED],
+    exit_codes: RUNTIME_EXITS,
   },
   {
     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 [...]",
+      "memhub recall <query> [--kind <raw|memory>] [--source <id>] [--limit <n>] [--character-budget <n>] [--timeout-ms <n>] [--user-id <id>] [--json]\n            memhub recall --query-file <path> [...]\n            memhub recall --stdin [...]",
     options: [
       {
         flag: "--query-file <path>",
@@ -583,23 +519,24 @@ export const COMMANDS: readonly CommandDescriptor[] = [
         flag: "--timeout-ms <n>",
         summary: "Core 查询时限 50..30000 毫秒，默认 2000。",
       },
+      USER_ID_OPTION,
       JSON_OPTION,
     ],
-    exit_codes: [EXIT_OK, EXIT_FAILED, EXIT_USAGE, EXIT_RUNTIME_STOPPED],
+    exit_codes: RUNTIME_EXITS,
   },
   {
     name: "service-plan",
     summary: "生成用户级服务计划；只输出计划，不写文件也不执行命令。",
     usage: `memhub service-plan ${SERVICE_USAGE}`,
     options: SERVICE_OPTIONS,
-    exit_codes: [EXIT_OK, EXIT_PLAN_BLOCKED],
+    exit_codes: [EXIT_OK, EXIT_USAGE, 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_PLAN_BLOCKED],
+    exit_codes: [EXIT_OK, EXIT_FAILED, EXIT_USAGE, EXIT_PLAN_BLOCKED],
   },
   {
     name: "service-uninstall",
@@ -607,15 +544,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_PLAN_BLOCKED],
+    exit_codes: [EXIT_OK, EXIT_FAILED, EXIT_USAGE, 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_PLAN_BLOCKED],
+    exit_codes: [EXIT_OK, EXIT_FAILED, EXIT_USAGE, EXIT_PLAN_BLOCKED],
   },
   {
     name: "uninstall",
@@ -628,24 +565,31 @@ 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_PLAN_BLOCKED],
+    exit_codes: [EXIT_OK, EXIT_FAILED, EXIT_USAGE, EXIT_PLAN_BLOCKED],
   },
   {
     name: "delete-data",
     summary:
-      "独立、二次确认地删除 One Memory Home（数据）。这是唯一会删除数据的命令；uninstall 不会。默认只出预览；需 Runtime 已停止，并显式 --confirm <path> 复述该目录。",
+      "删除 MemHub 数据目录（记忆、来源、配置），不可逆。这是唯一会删除数据的命令；uninstall 不会。需要 Runtime 已停止；不加参数时只预览要删除的目录；删除需要 --yes 并用 --confirm 再写一遍同一个目录。",
     usage:
       "memhub delete-data [--data-dir <path>] [--yes --confirm <path>] [--json]",
     options: [
-      DATA_DIR_OPTION,
-      CONFIRM_OPTION,
+      {
+        flag: "--data-dir <path>",
+        summary: "要删除的数据目录绝对路径；默认当前使用的数据目录。",
+      },
+      {
+        ...DESTRUCTIVE_CONFIRM_OPTION,
+        summary:
+          "删除时必须加，且要同时给出 --confirm <path>；不加时只预览，exit 0。",
+      },
       {
         flag: "--confirm <path>",
         summary:
-          "第二次确认：逐字复述预览里的数据目录；缺少它时即使 --yes 也不删除。",
+          "删除时必须加：再写一遍要删除的数据目录，与预览中的目录完全一致才执行。",
       },
       JSON_OPTION,
     ],
@@ -657,113 +601,150 @@ export const COMMANDS: readonly CommandDescriptor[] = [
       "onboarding reset 回到首次运行的引导流程。只清除引导完成状态：不删记忆数据，也不需要卸载重装。",
     usage: "memhub onboarding reset [--json]",
     options: [JSON_OPTION],
-    exit_codes: [EXIT_OK, EXIT_FAILED, EXIT_USAGE],
+    exit_codes: RUNTIME_EXITS,
   },
   {
     name: "help",
     summary: "显示总帮助或单个命令的用法。",
     usage: "memhub help [command] [--json]",
     options: [JSON_OPTION],
-    exit_codes: [EXIT_OK],
+    exit_codes: [EXIT_OK, EXIT_USAGE],
   },
   {
     name: "version",
     summary: "显示 CLI 版本。",
     usage: "memhub version [--json]",
     options: [JSON_OPTION],
-    exit_codes: [EXIT_OK],
+    exit_codes: [EXIT_OK, EXIT_USAGE],
   },
   {
-    name: "path",
+    name: "scan-roots",
     summary:
-      "查看或登记被扫描的目录（scan roots）。list 只读；add/remove 预览后加 --yes 才提交；均已接入 Runtime 的 scan-roots 端点。",
+      "查看或登记被扫描的目录（scan roots）。add/remove 直接执行。（旧名 path 仍可用。）",
     usage:
-      "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],
+      "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,
   },
   {
     name: "adapter",
     summary:
-      "查看 Harness Adapter 的就绪状态与最近一次探测结果（list），或现场探测某个来源（probe --source <id>）；两者均为只读，已接入 Runtime 的 adapters/探测端点。",
+      "查看 Harness Adapter 的就绪状态与最近一次探测结果（list），或现场探测某个来源（probe --source <id>）；两者均为只读。",
     usage:
       "memhub adapter list [--json]\n" +
       "            memhub adapter probe --source <id> [--json]",
-    options: [DATA_DIR_OPTION, JSON_OPTION],
-    exit_codes: [EXIT_OK, EXIT_USAGE, EXIT_FAILED],
+    options: [
+      { flag: "--source <id>", summary: "probe 的目标来源。" },
+      JSON_OPTION,
+    ],
+    exit_codes: RUNTIME_EXITS,
   },
   {
     name: "scan",
     summary:
-      "立即扫描；默认只输出计划，加 --yes 才真正执行。指定 --source 扫描单个来源，--all 一次扫描/导入全部已检测来源（Runtime 按来源寻址，不接受裸路径）。",
-    usage:
-      "memhub scan [--source <id>] [--full] [--yes] [--json]\n            memhub scan --all [--yes] [--json]",
+      "立即增量扫描一个已连接并开启同步的来源，返回导入任务（与 jobs start --operation sync 相同）。接入全部来源请用 sources connect --all-detected --import。",
+    usage: "memhub scan --source <id> [--json]",
     options: [
       {
         flag: "--source <id>",
-        summary: "按单个来源扫描；与 --all 互斥。",
+        summary: "要扫描的来源。",
       },
-      {
-        flag: "--all",
-        summary:
-          "处理全部 location_state=found 的来源，按来源逐条回执；部分成功返回非 0。",
-      },
-      {
-        flag: "--full",
-        summary: "忽略既有游标做全量重扫；默认只读取增量。",
-      },
-      DATA_DIR_OPTION,
       JSON_OPTION,
-      CONFIRM_OPTION,
     ],
-    exit_codes: [EXIT_OK, EXIT_USAGE, EXIT_FAILED, EXIT_PLAN_BLOCKED],
+    exit_codes: RUNTIME_EXITS,
   },
   {
     name: "write",
     summary:
-      "提交一次记忆写入，返回可查询的 request id；写入异步完成，不可重复提交。",
+      "提交一段 OpenAI 格式的对话（messages）到写入队列，异步加工成记忆；或按 request id 查询状态。request id 是幂等键：不给时自动生成并输出，重试请带上同一个。新增一条结论式记忆请用 memories add。",
     usage:
-      "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],
+      "memhub write submit --messages-file <path> --session <id> [--source <id>] [--request-id <id>] [--memory-at <RFC3339>] [--live] [--user-id <id>] [--json]\n            memhub write status <request-id> [--user-id <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: "优先处理。" },
+      USER_ID_OPTION,
+      JSON_OPTION,
+    ],
+    exit_codes: RUNTIME_EXITS,
   },
   {
     name: "backup",
     summary:
-      "备份与恢复 MemHub 数据（两阶段）。create 调用 Runtime 的备份端点；restore 会覆盖现有数据，要求 Runtime 已停止且 `--confirm` 逐字重复 `--source`，随后由非 Runtime 维护态 Core 完成受管校验、保护性备份和原子替换。",
+      "备份与恢复主库（来源、写入队列、配置）。注意：不包含记忆本身——SDK 记忆库 hy-memory/ 不在备份里，restore 也不会替换它。create 的目标要放在 <数据目录>/backups/ 下才能被 restore 使用；restore 覆盖现有主库，需 Runtime 已停止，并加 --yes 与 --confirm <同一个备份路径>。",
     usage:
-      "memhub backup create --target <path> [--yes] [--json]\n" +
-      "            memhub backup restore --source <path> --yes --confirm <path> [--json]",
+      "memhub backup create --target <path> [--json]\n" +
+      "            memhub backup restore --source <path> [--yes --confirm <path>] [--json]",
     options: [
-      DATA_DIR_OPTION,
-      JSON_OPTION,
-      CONFIRM_OPTION,
+      {
+        flag: "--target <path>",
+        summary: "create 的备份文件路径，必须在数据目录内。",
+      },
+      {
+        flag: "--source <path>",
+        summary:
+          "restore 的备份文件，必须是 <数据目录>/backups/ 下的受管备份。",
+      },
+      {
+        ...DESTRUCTIVE_CONFIRM_OPTION,
+        summary:
+          "restore 必须加，且要同时给出 --confirm <path>；create 不需要。",
+      },
       {
         flag: "--confirm <path>",
-        summary: "restore 要求逐字重复 --source 路径；不一致时不做任何改动。",
+        summary:
+          "restore 必须加：再写一遍 --source 的备份路径，完全一致才执行。",
       },
+      JSON_OPTION,
     ],
-    exit_codes: [EXIT_OK, EXIT_USAGE, EXIT_FAILED, EXIT_PLAN_BLOCKED],
+    exit_codes: [...RUNTIME_EXITS, EXIT_PLAN_BLOCKED],
   },
   {
     name: "ui",
     summary:
-      "用系统默认浏览器打开 Runtime 托管的 Web Console：先向 Core 换取一次性 loopback 登录码，再交给系统浏览器由 Core 置 HttpOnly/SameSite=Strict session；CLI 不向浏览器暴露裸 Core token。Core 未提供该合同时如实返回 ui_session_contract_unavailable（exit 4）。",
+      "用系统默认浏览器打开 Runtime 托管的 Web Console：先向 Core 换取一次性 loopback 登录码，再交给系统浏览器由 Core 置 HttpOnly/SameSite=Strict session；CLI 不向浏览器暴露裸 Core token。Runtime 未运行时 exit 3；Core 未提供该合同时如实返回 ui_session_contract_unavailable（exit 4）。",
     usage: "memhub ui [--json]",
     options: [JSON_OPTION],
-    exit_codes: [EXIT_OK, EXIT_FAILED, EXIT_USAGE, EXIT_PLAN_BLOCKED],
+    exit_codes: [...RUNTIME_EXITS, 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,20 +69,14 @@ const COMMANDS = [
   "doctor",
   "logs",
   "init",
-  "setup",
   "sources",
   "sync",
   "progress",
   "jobs",
-  "processing",
   "models",
   "memories",
-  // C6 App BLOCK (25f4ecf): UI write operations that had no CLI equivalent.
-  "calls",
-  "import-file",
-  "notes",
-  "extraction",
-  "graph",
+  "profile",
+  "graph-width",
   "host",
   "recall",
   "service-plan",
@@ -95,19 +89,20 @@ const COMMANDS = [
   "onboarding",
   "help",
   "version",
-  // A6 product commands. Appended, not inserted: the catalog is a stable
-  // contract, so existing names must not shift position.
-  "path",
+  "scan-roots",
   "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"]])(
@@ -148,6 +143,56 @@ 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 [
@@ -203,27 +248,63 @@ describe("CLI-22 shared output contract", () => {
       expect(payload.commands).toBeUndefined();
     });
 
-    it("documents the destructive restore confirmation explicitly", async () => {
+    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 () => {
       const streams = captureStreams();
       try {
         expect(await run(["help", "backup"], {})).toBe(0);
       } finally {
         streams.restore();
       }
-      expect(streams.stdout()).toContain(
-        "memhub backup restore --source <path> --yes --confirm <path>",
-      );
-      expect(streams.stdout()).toContain("逐字重复 --source");
+      expect(streams.stdout()).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();
+    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("失败时回滚");
       }
-      expect(streams.stdout()).not.toContain("--confirm <path>");
     });
   });
 
@@ -547,22 +628,23 @@ describe("documented commands", () => {
     models: [
       "list",
       "show",
-      "plan",
-      "configure",
+      "add",
+      "test",
       "receipt",
-      "probe-plan",
-      "probe",
-      "probe-receipt",
+      "edit",
+      "activate",
       "remove",
     ],
     // Source processing is one Freeze/Thaw switch under `sync`; the obsolete
     // independent read/write `sources access` command must not return here.
-    sources: ["list", "import", "receipt"],
+    sources: ["list", "connect", "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", "plan", "apply"],
+    memories: ["list", "show", "add", "add-status", "update", "delete"],
+    "scan-roots": ["list", "add", "remove"],
+    write: ["submit", "status"],
     host: ["list", "status", "install", "uninstall", "sync"],
   };
 

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

@@ -43,61 +43,35 @@ const ATTACHED = {
 };
 
 const RESPONSE = {
-  schema_version: 1,
+  schema_version: 2,
   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",
-      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,
-        },
-      ],
+      raw_id: "raw-1",
+      content: "Synthetic raw citation.",
+      source: "codex",
+      session_id: "session-1",
+      memory_at: "2026-09-19T00:00:00Z",
+      score: 0.8,
       truncated: false,
     },
     {
       kind: "memory",
       memory_id: "memory-1",
-      revision: 2,
-      content: "Synthetic governed memory.",
-      memory_kind: "working",
+      content: "Synthetic SDK memory.",
+      layer: "l2_fact",
+      status: "active",
+      source: "codex",
       updated_at: "2026-09-19T00:00:01Z",
-      evidence_ids: ["evidence-1"],
+      score: 0.7,
       truncated: false,
     },
   ],
-  used_characters: 49,
+  used_characters: 44,
   truncated: false,
   total_ms: 5,
-  adoption: "unknown",
 };
 
 beforeEach(() => {
@@ -115,42 +89,17 @@ beforeEach(() => {
 });
 
 describe("unified context search", () => {
-  it("accepts an empty tool message in a valid partial context response", async () => {
+  it("accepts an empty raw item 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: [
           {
-            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,
-              },
-            ],
+            ...RESPONSE.items[0],
+            source: "workbuddy",
+            content: "",
             truncated: true,
           },
         ],
@@ -165,8 +114,9 @@ describe("unified context search", () => {
       streams.restore();
     }
     expect(JSON.parse(streams.stdout())).toMatchObject({
+      schema_version: 2,
       state: "partial",
-      items: [{ kind: "raw", messages: [{ text: "" }] }],
+      items: [{ kind: "raw", content: "" }],
     });
   });
 
@@ -178,12 +128,26 @@ describe("unified context search", () => {
       streams.restore();
     }
     const output = streams.stdout();
-    expect(output).toContain("Synthetic governed memory.");
+    expect(output).toContain("Synthetic SDK memory.");
     expect(output).toContain("Synthetic raw citation.");
-    expect(output).not.toMatch(/^- raw |memory-1|evidence-1|采用状态/m);
+    expect(output).not.toMatch(/^- raw |memory-1|raw-1|采用状态/m);
   });
 
-  it("queries the current read-only context endpoint and preserves citations", async () => {
+  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 () => {
     const streams = captureStreams();
     try {
       expect(
@@ -209,7 +173,7 @@ describe("unified context search", () => {
       streams.restore();
     }
     expect(transport.post).toHaveBeenCalledWith(
-      "/api/v1/context/search",
+      "/api/v2/context/search",
       {
         query: "synthetic question",
         kinds: ["raw", "memory"],
@@ -222,12 +186,18 @@ 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.items[0].messages[0].evidence_id).toBe("evidence-1");
-    expect(output.items[1].evidence_ids).toEqual(["evidence-1"]);
+    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(transport.get).not.toHaveBeenCalled();
     expect(transport.put).not.toHaveBeenCalled();
     expect(transport.patch).not.toHaveBeenCalled();
@@ -242,19 +212,8 @@ 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: 26,
+        used_characters: 21,
       },
     });
     const streams = captureStreams();
@@ -394,29 +353,7 @@ describe("unified context search", () => {
       status: 200,
       data: {
         ...RESPONSE,
-        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,
-              },
-            ],
-          },
-        ],
+        items: [{ ...RESPONSE.items[0], content: text }],
         used_characters: 10,
       },
     });
@@ -429,7 +366,7 @@ describe("unified context search", () => {
     expect(JSON.parse(streams.stdout())).toMatchObject({
       state: "grounded",
       used_characters: 10,
-      items: [{ kind: "raw", messages: [{ text }] }],
+      items: [{ kind: "raw", content: text }],
     });
   });
 
@@ -441,29 +378,7 @@ describe("unified context search", () => {
       status: 200,
       data: {
         ...RESPONSE,
-        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,
-              },
-            ],
-          },
-        ],
+        items: [{ ...RESPONSE.items[0], content: text }],
         used_characters: 12,
       },
     });
@@ -479,6 +394,40 @@ 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,31 +3,6 @@ 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]>;
@@ -35,10 +10,13 @@ export interface ContextSearchInput {
   limit: number;
   character_budget: number;
   timeout_ms: number;
+  /** Whose memories to search. Omitted for the default user (`local`). */
+  user_id?: string;
 }
 
+/** The CLI's JSON document mirrors Core's SDK-native context schema v2. */
 export interface ContextSearchDocument {
-  schema_version: 1;
+  schema_version: 2;
   product: string;
   state:
     | "grounded"
@@ -47,15 +25,14 @@ 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(
@@ -67,7 +44,7 @@ export async function searchContext(
   const validated = validateContextResponse(outcome.data, input);
   return (
     validated ?? {
-      schema_version: 1,
+      schema_version: 2,
       product: PRODUCT,
       state: "invalid",
       code: "response_invalid",
@@ -123,6 +100,9 @@ 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"
       ? "没有查到相关记忆。"
@@ -130,14 +110,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) {
-    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)}`);
-      }
-    }
+    const label =
+      item.kind === "raw"
+        ? `[原始对话摘录 · ${String(item.source)}]`
+        : "[记忆]";
+    lines.push(`- ${label} ${String(item.content)}`);
   }
   if (document.truncated) lines.push("结果已按请求预算截断。");
   return `${lines.join("\n")}\n`;
@@ -149,84 +129,37 @@ function validateContextResponse(
 ): ContextSearchDocument | null {
   const response = record(value);
   if (
-    response?.schema_version !== 1 ||
+    response?.schema_version !== 2 ||
     !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) ||
-    response.adoption !== "unknown"
+    !number(response.total_ms, 0)
   ) {
     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 +=
-      item.kind === "memory"
-        ? characterCount(item.content)
-        : (item.messages as Array<Record<string, unknown>>).reduce(
-            (sum, message) => sum + characterCount(message.text),
-            0,
-          );
+    characters += characterCount(item.content);
   }
   if (characters !== response.used_characters) return null;
   if (response.state === "empty" && items.length !== 0) return null;
   return {
-    schema_version: 1,
+    schema_version: 2,
     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,
   };
 }
 
@@ -235,88 +168,65 @@ function validateItem(
   request: ContextSearchInput,
 ): Record<string, unknown> | null {
   const item = record(value);
-  if (!item || !oneOf(item.kind, CONTEXT_KINDS)) return null;
+  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.kind === "memory") {
     if (
       !boundedText(item.memory_id, 512) ||
-      !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"
+      boundedText(item.layer, 64, true) === null ||
+      boundedText(item.status, 32, true) === null ||
+      !optionalText(item.source, 128) ||
+      !optionalText(item.updated_at, 64)
     ) {
       return null;
     }
     return {
       kind: "memory",
       memory_id: item.memory_id,
-      revision: item.revision,
       content: item.content,
-      memory_kind: item.memory_kind,
-      updated_at: item.updated_at,
-      evidence_ids: item.evidence_ids,
+      layer: item.layer,
+      status: item.status,
+      source: item.source ?? null,
+      updated_at: item.updated_at ?? null,
+      score: item.score,
       truncated: item.truncated,
     };
   }
   if (
-    !boundedText(item.source_id, 128) ||
+    !boundedText(item.raw_id, 512) ||
+    !boundedText(item.source, 128) ||
     (request.raw_source_ids !== undefined &&
-      !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"
+      !request.raw_source_ids.includes(item.source as string)) ||
+    !boundedText(item.session_id, 512) ||
+    !optionalText(item.memory_at, 64)
   ) {
     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,
+    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,
   };
 }
 
-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 {
-    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,
-  };
-}
-
 function failed(
   outcome: Exclude<ReadOutcome<unknown>, { state: "ok" }>,
 ): ContextSearchDocument {
   return {
-    schema_version: 1,
+    schema_version: 2,
     product: PRODUCT,
     state: outcome.state,
     code: outcome.code,
@@ -374,27 +284,10 @@ function oneOf<const T extends readonly string[]>(
   return typeof value === "string" && values.includes(value as T[number]);
 }
 
-function enumList(
-  value: unknown,
-  values: readonly string[],
-): value is string[] {
+function optionalText(value: unknown, maximum: number): boolean {
   return (
-    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)
+    value === null ||
+    value === undefined ||
+    boundedText(value, maximum) !== null
   );
 }

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

@@ -8,15 +8,20 @@ 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/source-grants",
   "/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
@@ -64,13 +69,10 @@ 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`
@@ -81,9 +83,15 @@ 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"; code: string };
+  | {
+      state: "denied" | "unavailable" | "not_found" | "rejected";
+      code: string;
+    };
 
 export type CoreReader = <T>(
   path: string,
@@ -142,10 +150,27 @@ 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.
@@ -170,7 +195,7 @@ export function createCoreContextQuery(attachment: {
     let response: { status: number; data: unknown };
     try {
       response = await client.post(
-        "/api/v1/context/search",
+        "/api/v2/context/search",
         body,
         options?.signal ? { signal: options.signal } : undefined,
       );
@@ -194,16 +219,18 @@ 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_MUTATION_RECEIPT.test(path)) return true;
-  if (!MEMORY_DETAIL.test(path)) return false;
-  const segment = path.slice("/api/v1/memories/".length);
+  if (MEMORY_ADDITION.test(path)) return true;
+  if (!SDK_MEMORY_DETAIL.test(path)) return false;
+  const segment = path.slice("/api/v2/memories/".length);
   return !(RESERVED_MEMORY_SEGMENTS as readonly string[]).includes(segment);
 }
 
 /** A write accepted by the unified Memory Server entry.
  *
- * `request_id` is what the caller keeps and queries later. Retrying is unsafe:
- * HY has no idempotency key, so a resubmit duplicates the memory.
+ * `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.
  */
 export interface MemoryWriteReceipt {
   request_id: string;
@@ -211,6 +238,43 @@ 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.
@@ -233,34 +297,68 @@ 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;
-    first_round: number;
-    last_round: number;
-    evidence_ids: readonly string[];
+    source: string;
+    request_id: string;
+    messages: readonly OpenAIMessage[];
+    memory_at?: string;
     priority?: "live" | "normal";
+    /** Whose memory this is. Omitted for the default user (`local`). */
+    user_id?: string;
   },
-): 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;
+): 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 }),
+        ...(request.user_id === undefined || request.user_id === "local"
+          ? {}
+          : { user_id: request.user_id }),
+      },
+      {
+        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` };
 }
 
 /** Ask Runtime to scan one source now, returning the import job it started.
@@ -377,11 +475,16 @@ export async function deleteModelProfile(
 export async function readMemoryWrite(
   attachment: RuntimeAttachmentLike,
   requestId: string,
+  /** A receipt belongs to the user that submitted it; omit for `local`. */
+  userId?: string,
 ): Promise<MemoryWriteReceipt | null> {
   try {
     const response = await axios.get<MemoryWriteReceipt>(
-      `${baseUrlOf(attachment)}/api/v1/memory-writes/${encodeURIComponent(requestId)}`,
+      `${baseUrlOf(attachment)}/api/v2/memory-writes/${encodeURIComponent(requestId)}`,
       {
+        ...(userId === undefined || userId === "local"
+          ? {}
+          : { params: { user_id: userId } }),
         headers: { Authorization: `Bearer ${attachment.apiToken}` },
         timeout: 10_000,
         proxy: false,
@@ -457,48 +560,52 @@ 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<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) };
-  }
+): Promise<CoreWriteResult> {
+  return coreWrite(attachment, "post", "/api/v1/scan-roots", body);
 }
 
 export async function removeScanRoot(
   attachment: RuntimeAttachmentLike,
   body: { root: string },
-): 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) };
-  }
+): Promise<CoreWriteResult> {
+  return coreWrite(attachment, "delete", "/api/v1/scan-roots", body);
 }
 
 export async function readAdapters(
@@ -524,21 +631,12 @@ export async function readAdapters(
 export async function probeAdapter(
   attachment: RuntimeAttachmentLike,
   source: string,
-): 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) };
-  }
+): Promise<CoreWriteResult> {
+  return coreWrite(
+    attachment,
+    "post",
+    "/api/v1/adapters/probe",
+    { source },
+    15_000,
+  );
 }

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

@@ -4,8 +4,12 @@ const WRITE_PATHS = [
   "/api/v1/sources/connect",
   "/api/v1/model-profiles",
 ] as const;
-const MEMORY_WRITE_PATH =
-  /^\/api\/v1\/memories(?:\/[A-Za-z0-9][\w.-]{0,127}\/(?:correct|scopes|actions\/delete))?$/;
+/** `POST /api/v2/memories` adds one memory (the app's 添加记忆). */
+const MEMORY_ADD_PATH = "/api/v2/memories";
+/** One SDK memory; delete names its namespace, and a non-default user, 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))?(?:&user_id=[A-Za-z0-9._-]{1,64})?|user_id=[A-Za-z0-9._-]{1,64}))?$/;
 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 =
@@ -21,18 +25,7 @@ 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;
 
@@ -69,18 +62,6 @@ 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;
@@ -89,8 +70,7 @@ export function createCoreOperations(attachment: {
 }): CoreOperations &
   CoreDeleteOperations &
   CorePutOperations &
-  CorePatchOperations &
-  CoreUploadOperations {
+  CorePatchOperations {
   const client = axios.create({
     baseURL: `http://${attachment.host}:${attachment.port}`,
     headers: { Authorization: `Bearer ${attachment.apiToken}` },
@@ -101,18 +81,6 @@ 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,
@@ -122,19 +90,13 @@ export function createCoreOperations(attachment: {
       if (
         !(WRITE_PATHS as readonly string[]).includes(path) &&
         path !== SOURCE_IMPORT_JOB_PATH &&
-        !MEMORY_WRITE_PATH.test(path) &&
+        path !== MEMORY_ADD_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)
       ) {
@@ -170,7 +132,7 @@ export function createCoreOperations(attachment: {
       body: Record<string, unknown>,
       signal?: AbortSignal,
     ) {
-      if (path !== EXTRACTION_SETTINGS_PATH) {
+      if (!SDK_MEMORY_PATH.test(path) || path.includes("?")) {
         throw new Error("core_operation_path_not_allowed");
       }
       let response: { status: number; data: unknown };
@@ -232,7 +194,7 @@ export function createCoreOperations(attachment: {
       };
     },
     async delete<T>(path: string, signal?: AbortSignal) {
-      if (!IMPORT_FILE.test(path)) {
+      if (!SDK_MEMORY_PATH.test(path) && !MODEL_PROFILE_PATH.test(path)) {
         throw new Error("core_operation_path_not_allowed");
       }
       let response: { status: number; data: unknown };
@@ -256,51 +218,6 @@ 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,18 +1,20 @@
 import type {
-  GovernedMemory,
-  HomeSummary,
   ImportIssue,
   ImportJob,
   LiveSyncHealth,
-  MemoryDetail,
-  MemoryEvidenceExcerpt,
-  MemoryLibraryPage,
   MemoryProcessingSummary,
   ModelProfile,
   SourceResponse,
 } from "@one-memory/contracts";
-/** 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;
+/** SDK memory states `memhub memories list --status` may ask for. */
+export const MEMORY_STATUSES = [
+  "active",
+  "superseded",
+  "shadow",
+  "negated",
+  "conflicted",
+  "archived",
+] as const;
 
 /**
  * HTTP 200 is not a contract. Everything here re-checks the shape and the
@@ -23,7 +25,6 @@ export const MEMORY_STATUSES = ["confirmed", "deleted", "superseded"] as const;
 
 const ID_MAX = 128;
 const LABEL_MAX = 256;
-const TEXT_MAX = 100_000;
 const LIST_MAX = 500;
 const LIVE_SYNC_STATES = [
   "idle",
@@ -39,14 +40,6 @@ 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",
@@ -57,16 +50,6 @@ 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 = [
@@ -87,16 +70,6 @@ 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;
@@ -352,45 +325,6 @@ 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 {
@@ -444,150 +378,32 @@ export function validateModelProfiles(value: unknown): ModelProfile[] | null {
   });
 }
 
-export function validateHomeSummary(value: unknown): HomeSummary | 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 {
   const summary = record(value);
   if (
     !summary ||
+    summary.schema_version !== 2 ||
     count(summary.memory_count) === null ||
     text(summary.observed_at, LABEL_MAX) === null
   ) {
     return null;
   }
-  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"
-    ) {
+  const latest = summary.latest;
+  if (latest !== null) {
+    const memory = record(latest);
+    if (!memory || typeof memory.memory_id !== "string" || !memory.memory_id) {
       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;
   }
-  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;
+  return summary as unknown as SdkHomeSummary;
 }
 
 function identifiers(value: unknown): string[] | null {
@@ -618,10 +434,6 @@ 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,11 +134,6 @@ 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,6 +65,9 @@ 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(
@@ -73,7 +76,13 @@ export function renderDoctorText(document: DoctorDocument): string {
     ),
     ...(document.state === "healthy"
       ? []
-      : ["下一步：打开 MemHub 的“帮助与诊断”查看并处理异常。"]),
+      : migration
+        ? [
+            `升级迁移没有完成（错误码：${migration.code}），MemHub 不会启动。`,
+            `下一步：把迁移日志附在 GitHub 反馈里发给我们：${migration.details?.log_file}`,
+            `反馈地址：${migration.details?.issues_url}`,
+          ]
+        : ["下一步：打开 MemHub 的“帮助与诊断”查看并处理异常。"]),
     "",
   ].join("\n");
 }
@@ -107,6 +116,14 @@ 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 ?? "",
+          },
+        }
+      : {}),
   };
 }
 
@@ -200,8 +217,7 @@ function modelCheck(status: StatusDocument): DoctorCheck {
 function pendingCheck(progress: ProgressDocument | null): DoctorCheck {
   if (
     progress?.imports.state !== "ok" ||
-    progress.generation.summary_state.state !== "ok" ||
-    progress.generation.tasks_state.state !== "ok"
+    progress.generation.summary_state.state !== "ok"
   ) {
     return {
       id: "pending_operations",
@@ -212,27 +228,20 @@ 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 + taskAttention + waiting + failed;
+  const attention = jobAttention + 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 ||
-        progress.generation.output_truncated,
+      output_truncated: progress.imports.output_truncated,
     },
   };
 }

memhub/apps/cli/src/entry.ts

@@ -23,39 +23,26 @@ 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")
-    ? true
-    : arguments_.includes("--confirm");
+  const confirmed = arguments_.includes("--yes");
   const installLike = [
     "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");
+  const isPreview = installLike && !confirmed;
+  const mutating = [
+    "start",
+    "stop",
+    "restart",
+    "install",
+    "upgrade",
+    "service-install",
+    "service-uninstall",
+  ].includes(command ?? "");
   let diagnostics: DiagnosticLogger | null = null;
   if (mutating && !isPreview) {
     try {

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

@@ -0,0 +1,93 @@
+/**
+ * `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 { createHash, randomUUID } from "node:crypto";
+import { randomUUID } from "node:crypto";
 import type { ImportJob, ModelProfile } from "@one-memory/contracts";
 import {
   buildModelProfileCreateRequest,
@@ -26,45 +26,7 @@ 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;
@@ -133,10 +95,33 @@ function classifySourceImport(
   return committed(operationId, receipt);
 }
 
-export async function planSourceImport(
+/**
+ * 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(
   reader: CoreReader,
-  sourceIds: readonly string[],
+  operations: CoreOperations,
+  input: {
+    sourceIds: readonly string[];
+    confirmOverrides: boolean;
+    requestId?: string;
+    /** Whose grant this is. Omitted for the default user (`local`). */
+    userId?: string;
+    /** An absolute root other than the source's candidate (a Hermes
+     * profile). Core reads its identity itself, so the source's candidate
+     * root id and revision are not sent for it. */
+    root?: string;
+  },
 ): Promise<FlowDocument> {
+  const sourceIds = input.sourceIds;
+  // A second user's grant is not a first run, and a custom root has no
+  // candidate the app showed: both are a plain connect.
+  const profile = input.root !== undefined || input.userId !== undefined;
   if (
     sourceIds.length < 1 ||
     sourceIds.length > 32 ||
@@ -145,6 +130,8 @@ export async function planSourceImport(
   ) {
     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);
@@ -156,69 +143,72 @@ export async function planSourceImport(
     return invalid("source_unavailable");
   }
   const items = selected.map(([candidate]) => candidate);
-  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");
+  // A custom root is the caller's own choice, not the environment override
+  // the confirmation exists for.
+  const needsOverride =
+    input.root !== undefined
+      ? []
+      : 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 },
+    };
+  }
   // 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: plan.source_ids,
-      sourceRoots: plan.source_roots,
-      sourceCandidateRevisions: plan.source_candidate_revisions,
-      confirmEnvironmentOverrides: plan.confirm_environment_overrides,
-      fullRescan: plan.full_rescan,
-      onboarding: plan.onboarding,
+      sourceIds: [...sourceIds],
+      sourceRoots: Object.fromEntries(
+        items.flatMap((item) =>
+          input.root === undefined
+            ? [[item.source_id, item.candidate_root_id]]
+            : [],
+        ),
+      ),
+      sourceCandidateRevisions: Object.fromEntries(
+        items.flatMap((item) =>
+          item.candidate_revision === undefined || input.root !== undefined
+            ? []
+            : [[item.source_id, item.candidate_revision]],
+        ),
+      ),
+      confirmEnvironmentOverrides: needsOverride.length > 0,
+      fullRescan: false,
+      onboarding: !profile,
       enableSync: true,
-      requestId: plan.request_id,
+      requestId,
     });
   } catch (error) {
     if (error instanceof SourceImportInputError) {
-      return invalid("source_plan_invalid");
+      return invalid("invalid_source_selection");
     }
     throw error;
   }
-  const result = await operations.post<unknown>(request.path, request.body);
+  const result = await operations.post<unknown>(request.path, {
+    ...request.body,
+    ...(input.userId === undefined ? {} : { user_id: input.userId }),
+    ...(input.root === undefined ? {} : { root: input.root }),
+  });
   if (result.state === "rejected") {
-    return rejected(plan.request_id, result.code);
+    return rejected(requestId, result.code);
   }
   if (result.state === "committed") {
-    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 receipt = validateSourceReceipt(result.data, requestId);
+    if (!receipt) return unknown(requestId, "source_receipt_invalid");
+    return classifySourceImport(requestId, receipt);
   }
-  const recovered = await readSourceReceipt(reader, plan.request_id);
+  const recovered = await readSourceReceipt(reader, requestId);
   if (recovered.state === "unknown" || recovered.state === "not_found") {
-    return unknown(plan.request_id, result.code);
+    return unknown(requestId, 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
@@ -262,26 +252,23 @@ export async function readSourceReceipt(
   return committed(requestId, receipt);
 }
 
-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(
+/**
+ * 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(
   value: unknown,
   apiKey: string | undefined,
   reader: CoreReader,
   operations: CoreOperations,
+  operationId: string = randomUUID(),
 ): Promise<FlowDocument> {
-  const plan = validateModelPlan(value);
-  if (!plan) return invalid("model_plan_invalid");
+  const config = validateModelConfig(value);
+  if (!config) return invalid("model_config_invalid");
+  if (!UUID.test(operationId)) return invalid("invalid_operation_id");
   // 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.
@@ -289,31 +276,31 @@ export async function executeModelProfile(
   try {
     request = buildModelProfileCreateRequest(
       {
-        ...(plan.config as Record<string, unknown>),
+        ...config,
         ...(apiKey === undefined ? {} : { api_key: apiKey }),
       } as Parameters<typeof buildModelProfileCreateRequest>[0],
-      plan.operation_id,
+      operationId,
     );
   } catch (error) {
     if (error instanceof ModelProfileInputError) {
-      return invalid("model_plan_invalid");
+      return invalid("model_config_invalid");
     }
     throw error;
   }
   const result = await operations.post<unknown>(request.path, request.body);
   if (result.state === "rejected") {
-    return rejected(plan.operation_id, result.code);
+    return rejected(operationId, result.code);
   }
   if (result.state === "committed") {
     const profile = validateModelProfile(result.data);
     return profile
-      ? committed(plan.operation_id, projectProfile(profile))
-      : unknown(plan.operation_id, "model_receipt_invalid");
+      ? committed(operationId, projectProfile(profile))
+      : unknown(operationId, "model_receipt_invalid");
   }
-  const recovered = await readModelReceipt(reader, plan.operation_id);
+  const recovered = await readModelReceipt(reader, operationId);
   return recovered.state === "committed"
     ? { ...recovered, state: "recovered" }
-    : unknown(plan.operation_id, result.code);
+    : unknown(operationId, result.code);
 }
 
 export async function readModelReceipt(
@@ -362,27 +349,6 @@ 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 ?? "无"}`,
@@ -407,98 +373,20 @@ 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 ["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;
+  return ["committed", "recovered"].includes(document.state) ? 0 : 1;
 }
 
 function validateModelConfig(value: unknown): Record<string, unknown> | null {
@@ -644,37 +532,6 @@ 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>,
@@ -767,43 +624,3 @@ 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

@@ -1,64 +0,0 @@
-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

@@ -1,16 +0,0 @@
-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. 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 () => {
+  // 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 () => {
     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(true);
+    ).toBe(false);
   });
 
   it("keeps selected Harnesses frozen without creating history jobs", async () => {
@@ -506,7 +506,7 @@ describe("A2 dual-mode init", () => {
   });
 });
 
-describe("A19 init --all-detected", () => {
+describe("A19 sources connect --all-detected (old spelling: 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 init --all-detected", () => {
     expect(prompter.asked).toBe(0);
     expect(code).toBe(0);
     const document = JSON.parse(streams.value());
-    expect(document.command).toBe("init");
+    expect(document.command).toBe("sources connect");
     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,18 +4,11 @@ import type {
   CoreDeleteOperations,
   CoreOperations,
 } from "./core-operations.js";
-import {
-  executeModelProfile,
-  type FlowDocument,
-  planModelProfile,
-} from "./headless-flows.js";
+import { createModelProfile, type FlowDocument } from "./headless-flows.js";
 import { approvalFingerprint, listHosts, readHost } from "./host-flow.js";
 import { parseSelection, type WizardPrompter } from "./init-wizard.js";
-import { executeModelProbe, planModelProbe } from "./model-probe-flow.js";
-import {
-  executeModelProfileActivate,
-  planModelProfileActivate,
-} from "./model-write-flows.js";
+import { startModelProbe } from "./model-probe-flow.js";
+import { activateModelProfile } from "./model-write-flows.js";
 
 type ProviderPreset = {
   id: string;
@@ -359,30 +352,26 @@ export async function runInteractiveModelSetup(
           );
         })
       : new Map<string, string>();
-    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,
+    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,
+      },
       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("模型配置未保存。");
@@ -391,18 +380,11 @@ export async function runInteractiveModelSetup(
     }
 
     try {
-      const probePlan = await planModelProbe(
+      const probed = await startModelProbe(
         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)}`,
@@ -421,17 +403,8 @@ export async function runInteractiveModelSetup(
       throw error;
     }
 
-    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,
+    const activated = await activateModelProfile(
+      profile.profile_id,
       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 previews without a POST", async () => {
+  it("start posts directly, without a preview step", async () => {
     const output = captureStdout();
     let code: number;
     try {
@@ -110,14 +110,14 @@ describe("memhub jobs", () => {
       output.restore();
     }
     expect(code!).toBe(0);
-    expect(transport.post).not.toHaveBeenCalled();
-    expect(JSON.parse(output.value())).toMatchObject({
-      state: "preview",
-      plan: { source_id: "codex", operation: "history" },
-    });
+    expect(transport.post).toHaveBeenCalledWith(
+      "/api/v1/import-jobs",
+      { source_id: "codex", operation: "history" },
+      undefined,
+    );
   });
 
-  it("start --confirm posts the exact Core request", async () => {
+  it("start still accepts a legacy --confirm", async () => {
     const output = captureStdout();
     let code: number;
     try {
@@ -146,7 +146,7 @@ describe("memhub jobs", () => {
   });
 
   it.each(["pause", "resume", "cancel"] as const)(
-    "%s previews without a POST",
+    "%s posts the action endpoint directly",
     async (action) => {
       const output = captureStdout();
       let code: number;
@@ -156,11 +156,11 @@ describe("memhub jobs", () => {
         output.restore();
       }
       expect(code!).toBe(0);
-      expect(transport.post).not.toHaveBeenCalled();
-      expect(JSON.parse(output.value())).toMatchObject({
-        state: "preview",
-        plan: { job_id: "job-1", action },
-      });
+      expect(transport.post).toHaveBeenCalledWith(
+        `/api/v1/import-jobs/job-1/${action}`,
+        {},
+        undefined,
+      );
     },
   );
 

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

@@ -1,4 +1,4 @@
-import { mkdtemp, rm } from "node:fs/promises";
+import { mkdtemp, rm, symlink } from "node:fs/promises";
 import os from "node:os";
 import path from "node:path";
 import { DiagnosticLogger } from "@one-memory/runtime-control";
@@ -41,11 +41,15 @@ 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",
     ],
@@ -56,6 +60,8 @@ 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");
 });
@@ -132,3 +138,27 @@ 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,6 +3,7 @@ import path from "node:path";
 import type { DiagnosticEventV1 } from "@one-memory/runtime-control";
 import {
   diagnosticLogFiles,
+  projectDiagnosticEventForSafeOutput,
   readDiagnosticEvents,
 } from "@one-memory/runtime-control";
 
@@ -24,54 +25,6 @@ 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 };
@@ -154,7 +107,11 @@ export async function readLogReport(
   query: LogQuery,
 ): Promise<{
   events: DiagnosticEventV1[];
+  /** Lines that are not JSON: the only ones `memhub logs` calls damaged. */
   invalid_lines: number;
+  /** Whole JSON lines the reader leaves out, such as an older build's
+   * records. Nothing is wrong with them, so the text output says nothing. */
+  unrecognized_lines: number;
   failure?: "log_directory_unreadable";
 }> {
   // `readDiagnosticEvents` treats an unreadable logs path as "no events". That
@@ -166,6 +123,7 @@ export async function readLogReport(
     return {
       events: [],
       invalid_lines: 0,
+      unrecognized_lines: 0,
       failure: "log_directory_unreadable",
     };
   }
@@ -176,6 +134,7 @@ export async function readLogReport(
     return {
       events: [],
       invalid_lines: 0,
+      unrecognized_lines: 0,
       failure: "log_directory_unreadable",
     };
   }
@@ -237,63 +196,13 @@ export function renderLogText(
   return `${lines.join("\n")}\n`;
 }
 
-/** 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. */
+/** 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. */
 export function redactDiagnosticEvent(
   event: DiagnosticEventV1,
 ): DiagnosticEventV1 {
-  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;
+  return projectDiagnosticEventForSafeOutput(event);
 }
 
 export async function followLogs(options: {
@@ -315,6 +224,7 @@ 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

@@ -0,0 +1,583 @@
+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

@@ -1,718 +0,0 @@
-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

@@ -1,725 +0,0 @@
-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;
-}