feat(sdk): rerank switch, size-gated MMR, scene="all" search and list, productivity edit/delete

search:
- rerank=True (default) keeps today's behavior; rerank=False skips the
  local cross-encoder, graph rerank and the coding facts' BM25 rerank for
  that call (carried on ReadRequest, so concurrent calls are independent).
- MMR now runs only when the caller's limit is below MMR_MAX_TOP_K (20).
  It is O(k^2 * pool) Jaccard and made large result pages slow.
- scene="all" searches chat, working and coding concurrently with one
  shared embedding and fuses them by Reciprocal Rank Fusion (k=60) over
  each lane's own rank, so no lane is buried by its score scale. Items
  carry scene, kind, memory_id, content, fused score, lane score/rank,
  source and times. A failed or disabled lane is reported in "errors".

list_memories:
- scene="coding"|"working" honour include_sources/exclude_sources with
  the filtered total.
- scene="all" lists the three scenes newest first with limit/offset over
  the merged order, per-scene totals and the same unified item fields.

update/delete:
- kind/variant disambiguate like get(); an experience update replaces
  its solution (task= also replaces the task and its search vectors), a
  fact update replaces the statement; delete removes experiences and
  facts with their vectors. Chat calls are unchanged.
- The HTTP server maps an ambiguous id to 409 and a bad namespace to 400
  instead of 500, passes kind/variant through, and strips the query
  string from PUT/DELETE paths, which leaked it into the memory id.

memory_stats now reads productivity times (written as naive UTC) as UTC.

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

.env.example

@@ -86,6 +86,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,174 @@
 
 Hy Memory and MemHub are versioned and released independently.
 
+## Unreleased
+
+- SDK: `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.
+- SDK: 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.
+- SDK: `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.
+- SDK: `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.
+- SDK: `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.
+- SDK: `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.
+- 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.
+- SDK 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 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.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 +180,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 +194,31 @@ 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.2 — 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`.
+- Removed the HyPermission store wrappers and global model-content consent
+  switch; the trusted embedded SDK now uses native local stores.
+- Prevented uncertain writes from blocking later source work and added one
+  reconciled automatic retry after ten seconds.
+- Added product-facing memory pipeline counters and the log troubleshooting
+  runbook.
+- Allowed a verified packaged Desktop Runtime from a different commit to take
+  over an equal-build install atomically while preserving downgrade and
+  tamper refusal.
+
+## MemHub 1.0.2 — 2026-10-17
 
 - Updated the source version to `1.0.2` (build 6).
 - Pinned the public SDK to `hy-memory==2.0.2`.

README.md

@@ -32,7 +32,9 @@ 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.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 +65,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 +153,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 +253,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,9 @@
 
 ## 最新动态
 
-* *<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.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 +65,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 +153,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 +253,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

@@ -197,6 +197,7 @@ SDK 不设置 Rerank Search 并发上限。开启后模型在 `HyMemoryClient`
 | `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,22 @@ except Exception:
 from .client import HyMemoryClient
 from .inspector import MemoryInspector
 from .runtime import SharedRuntime
+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 +124,20 @@ __all__ = [
     "HyMemoryClient",
     "MemoryInspector",
     "SharedRuntime",
+    "DataPlaneRestore",
+    "DataPlaneSnapshot",
+    "DataPlaneSnapshotRejected",
+    "restore_local_data_plane",
+    "snapshot_local_data_plane",
     # 配置
     "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

@@ -1123,6 +1123,7 @@ class Extractor:
                 max_tokens=self._llm_config.agent_max_tokens,
                 tools=None,
                 tool_choice=None,
+                audit_stage="extract",
             )
             self._call_count += 1
             total_tokens += response.tokens_used
@@ -1233,6 +1234,7 @@ class Extractor:
                         max_tokens=self._llm_config.agent_max_tokens,
                         tools=None,
                         tool_choice=None,
+                        audit_stage="extract",
                     )
                     self._call_count += 1
                     total_tokens += response.tokens_used

hy_memory/agent/llm_provider.py

@@ -34,6 +34,7 @@ import os
 import weakref
 
 from ..config import MemoryConfig
+from ..utils.model_call_context import model_call_stage
 from ..core.workload import llm_slot
 
 logger = logging.getLogger(__name__)
@@ -348,6 +349,7 @@ class LLMProvider:
         stop: List[str] = None,
         tools: Optional[List[Dict[str, Any]]] = None,
         tool_choice: Optional[Any] = None,
+        audit_stage: Optional[str] = None,
         **kwargs
     ) -> LLMResponse:
         """
@@ -386,15 +388,16 @@ class LLMProvider:
                         len(prompt), _content_fingerprint(prompt),
                     )
 
-                response = await self._call_llm(
-                    prompt=prompt,
-                    max_tokens=max_tokens,
-                    temperature=temperature,
-                    stop=stop,
-                    tools=tools,
-                    tool_choice=tool_choice,
-                    **kwargs
-                )
+                with model_call_stage(audit_stage):
+                    response = await self._call_llm(
+                        prompt=prompt,
+                        max_tokens=max_tokens,
+                        temperature=temperature,
+                        stop=stop,
+                        tools=tools,
+                        tool_choice=tool_choice,
+                        **kwargs
+                    )
 
                 self._total_calls += 1
                 self._total_tokens += response.tokens_used
@@ -595,6 +598,7 @@ class LLMProvider:
         temperature: Optional[float] = None,
         tools: Optional[List[Dict[str, Any]]] = None,
         tool_choice: Optional[Any] = None,
+        audit_stage: Optional[str] = None,
     ) -> LLMResponse:
         """
         多轮 messages 调用（支持 tool results 回传）。
@@ -622,13 +626,14 @@ class LLMProvider:
                         f"msgs={len(messages)} tools={len(tools) if tools else 0}"
                     )
 
-                response = await self._chat_completions(
-                    messages,
-                    max_tokens=max_tokens,
-                    temperature=temperature,
-                    tools=tools,
-                    tool_choice=tool_choice,
-                )
+                with model_call_stage(audit_stage):
+                    response = await self._chat_completions(
+                        messages,
+                        max_tokens=max_tokens,
+                        temperature=temperature,
+                        tools=tools,
+                        tool_choice=tool_choice,
+                    )
 
                 self._total_calls += 1
                 self._total_tokens += response.tokens_used

hy_memory/agent/prompts_zh.py

@@ -743,6 +743,7 @@ RECONCILE_PROMPT_ZH = """你是一个记忆整合系统（Memory Reconciler）
 
 * content
 * owner
+* memory_at（发生时间）
 * tags
 
 new memories 没有 ID。
@@ -791,6 +792,7 @@ new memories 没有 ID。
 * 无损合并
 * 保留所有有效信息
 * 不要产生重复 memory
+* 两者在某个值上不一致时，保留 memory_at 更晚的那个值；绝不用更早的 memory 覆盖更新的值
 
 ### 同一次事件的补充 vs 另一次发生
 
@@ -823,6 +825,7 @@ new memories 没有 ID。
 * 新 memory 与旧 memory 在同一维度冲突
 * 两者不能同时为真
 * 旧 memory 已不再代表当前状态
+* 新 memory 的 memory_at 不早于旧 memory 的 memory_at
 
 例如：
 
@@ -837,6 +840,7 @@ new memories 没有 ID。
 * wording 差异
 * 同义表达
 * 可共存偏好
+* 新 memory 的 memory_at 早于旧 memory：它是更早的状态，绝不能取代更新的状态（见「时间规则」）
 
 要求：
 
@@ -859,7 +863,7 @@ new memories 没有 ID。
 
 ### 把多条旧记忆折叠进同一条链
 
-如果**两条或更多**已有记忆描述的是**同一维度**，而新记忆是该维度上的最新变化，
+如果**两条或更多**已有记忆描述的是**同一维度**，而新记忆是该维度上的最新变化（它的 memory_at 晚于所有被折叠的记忆），
 你可以把它们折叠进同一条演化链。此时用 `memory_ids`（有序列表，**旧→新**）
 代替单个 `memory_id`：
 
@@ -951,13 +955,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

@@ -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],
@@ -669,6 +770,7 @@ class MemoryReconciler:
             response = await llm.complete(
                 prompt=prompt,
                 max_tokens=500,
+                audit_stage="reconcile",
             )
             text = response.content.strip()
             if "```json" in text:
@@ -1383,6 +1485,7 @@ class MemoryReconciler:
                     response = await llm.complete(
                         prompt=prompt,
                         max_tokens=dyn_max_tokens,
+                        audit_stage="reconcile",
                     )
                 except Exception as e:
                     # LLM 彻底不可用（provider 已按 max_retries 重试过，网关 500 /
@@ -1397,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,
                 )

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

@@ -919,6 +919,7 @@ class CodingMemoryExtractor:
             resp = await self.llm_provider.complete(
                 prompt=prompt,
                 max_tokens=self.max_tokens,
+                audit_stage="coding_extract",
             )
         except Exception as e:
             logger.warning(f"[coding-extract] LLM call failed: {e}")

hy_memory/coding/fact_reconciler.py

@@ -466,7 +466,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:
@@ -499,7 +505,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 +526,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 +543,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 看更宽的名单，
                     # 阈值过滤是读取侧的事。
@@ -571,6 +593,7 @@ class WorkingFactReconciler:
         resp = await self.llm_provider.complete(
             prompt=prompt,
             max_tokens=self.max_tokens,
+            audit_stage="coding_fact_reconcile",
         )
         return self._parse_ops(resp.content)
 
@@ -637,6 +660,7 @@ class WorkingFactReconciler:
             resp = await self.llm_provider.complete(
                 prompt=prompt,
                 max_tokens=_CHAIN_SUMMARY_MAX_TOKENS,
+                audit_stage="coding_fact_summary",
             )
         except Exception as e:
             logger.warning(f"[fact-reconcile] chain summary failed: {e}")
@@ -792,6 +816,15 @@ 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，理论上到不了这儿。真到了就说明前面
                 # 哪一环漏了，宁可让这次覆盖不生效——多留一条旧事实是可恢复的，删掉

hy_memory/coding/judge.py

@@ -29,6 +29,9 @@ logger = logging.getLogger(__name__)
 
 _JUDGE_MAX_TURNS = 20
 _JUDGE_HEAD_TURNS = 5
+_JUDGE_USER_CONTENT_LIMIT = 1_000
+_JUDGE_USER_CONTENT_HEAD = 200
+_JUDGE_USER_CONTENT_TAIL = 200
 _JUDGE_MAX_QUERY_CHARS = 300
 _JUDGE_MAX_QUERIES = 20
 
@@ -186,6 +189,7 @@ async def classify_messages_scene(
             prompt=prompt,
             max_tokens=max_tokens,
             temperature=temperature,
+            audit_stage="coding_judge",
         )
         _elapsed = round((time.perf_counter() - _t0) * 1000, 2)
         result = _parse_scene_json(resp.content)
@@ -631,9 +635,13 @@ def _format_turns(summary: List[Dict[str, Any]]) -> str:
     rows = []
     for t in summary:
         user = t.get("user", "") or ""
-        # 单 turn 用户文本截到 200 字符
-        if len(user) > 200:
-            user = user[:200] + "..."
+        if len(user) > _JUDGE_USER_CONTENT_LIMIT:
+            omitted = len(user) - _JUDGE_USER_CONTENT_HEAD - _JUDGE_USER_CONTENT_TAIL
+            user = (
+                user[:_JUDGE_USER_CONTENT_HEAD]
+                + f"\n[...{omitted} chars omitted...]\n"
+                + user[-_JUDGE_USER_CONTENT_TAIL:]
+            )
         tools = t.get("tools", []) or []
         rows.append(
             f"- turn {t.get('turn', '?')}: user={user!r}, tools={tools}"

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,
@@ -310,6 +318,7 @@ class CodingMemoryReconciler:
         resp = await self.llm_provider.complete(
             prompt=prompt,
             max_tokens=self.max_tokens,
+            audit_stage="coding_reconcile",
         )
         return self._parse_ops(resp.content), prompt, resp.content, resp
 
@@ -414,6 +423,7 @@ class CodingMemoryReconciler:
         self,
         ops: List[ReconcileOp],
         drafts: List[CodingMemoryDraft],
+        candidates_per_draft: List[List[CodingMemory]],
     ) -> List[ReconcileOp]:
         """
         校验 + 执行 ops。返回成功执行的 ops（filter 掉无效 op）。
@@ -453,6 +463,11 @@ class CodingMemoryReconciler:
                 if not op.target_experience_id:
                     logger.warning(f"[coding-reconcile] drop UPDATE missing target: {op.to_dict()}")
                     continue
+                if not self._target_was_offered(op, candidates_per_draft):
+                    logger.warning(
+                        f"[coding-reconcile] drop UPDATE outside authority scope: {op.to_dict()}"
+                    )
+                    continue
                 if op.draft_idx in consumed:
                     logger.warning(f"[coding-reconcile] drop UPDATE on consumed draft: {op.to_dict()}")
                     continue
@@ -475,6 +490,11 @@ class CodingMemoryReconciler:
                 if not op.target_experience_id:
                     logger.warning(f"[coding-reconcile] drop DELETE missing target: {op.to_dict()}")
                     continue
+                if not self._target_was_offered(op, candidates_per_draft):
+                    logger.warning(
+                        f"[coding-reconcile] drop DELETE outside authority scope: {op.to_dict()}"
+                    )
+                    continue
                 # DELETE 需要知道 user_id；通过 draft_idx（如有）或第一个 draft 推断
                 user_id = self._infer_user_id(op, drafts)
                 if not user_id:
@@ -511,6 +531,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]

hy_memory/coding/store.py

@@ -209,6 +209,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],
@@ -408,6 +431,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
@@ -529,10 +582,20 @@ class CodingMemoryStore:
         """覆盖式更新一条 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
         await _run_in_pool(self._upsert_sql_sync, memory)
         # 删旧 VDB
@@ -555,6 +618,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 +782,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 +869,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 +890,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"
                 )
@@ -778,6 +993,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 +1010,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 +1028,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 +1085,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]
@@ -1003,6 +1238,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 +1293,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 +1326,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(

hy_memory/coding/writer.py

@@ -50,6 +50,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 +60,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
 
@@ -217,6 +223,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 +285,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

@@ -1136,6 +1136,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 +1156,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/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/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_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,17 @@ 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 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/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/reader_base.py

@@ -58,6 +58,7 @@ from ._retrieval.ner import (
 )
 from ._retrieval.diversity import (
     near_dup_demote,
+    mmr_applies,
     mmr_select,
     social_boilerplate_demote,
     pool_df_demote,
@@ -1279,7 +1280,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 +1435,9 @@ 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)
             vdb_sem_limit = max(final_limit * 3, 30)
             vdb_kw_limit = max(final_limit * 5, 80)
             graph_limit = max(
@@ -1840,6 +1847,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 +2469,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(
@@ -2536,7 +2545,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 +2722,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 +3551,8 @@ 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,
                 "local_rerank_model": getattr(
                     self.config.recall,
                     "local_rerank_model",

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/writer.py

@@ -968,7 +968,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,

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/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/model_call_context.py

@@ -0,0 +1,24 @@
+"""Context propagated to host-provided HTTP transports for cost accounting."""
+
+from collections.abc import Iterator
+from contextlib import contextmanager
+from contextvars import ContextVar, Token
+
+_model_call_stage: ContextVar[str] = ContextVar(
+    "hy_memory_model_call_stage",
+    default="other",
+)
+
+
+def current_model_call_stage() -> str:
+    return _model_call_stage.get()
+
+
+@contextmanager
+def model_call_stage(stage: str | None) -> Iterator[None]:
+    normalized = (stage or "other").strip().lower() or "other"
+    token: Token[str] = _model_call_stage.set(normalized)
+    try:
+        yield
+    finally:
+        _model_call_stage.reset(token)

hy_memory/utils/pipeline_log_writer.py

@@ -18,12 +18,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 +60,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 +69,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
@@ -80,7 +100,11 @@ class PipelineLogWriter:
                 split_namespace_user,
             )
 
-            tokens = (prompt_tokens or 0) + (completion_tokens or 0) + (total_tokens or 0)
+            # Providers define total_tokens as prompt+completion. Adding all
+            # three fields doubled every cost estimate in this JSONL.
+            tokens = (total_tokens or 0) or (
+                (prompt_tokens or 0) + (completion_tokens or 0)
+            )
             namespace, uid = split_namespace_user(user_id or "")
             if not is_llm_content_logging_enabled():
                 prompt = redact_content(prompt)
@@ -111,7 +135,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:

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,16 @@ 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` 记录。
 
 ## Search：搜索记忆
 
-普通 chat 搜索：
-
 ```python
 result = client.search(
     "用户偏好怎样的回答风格？",
@@ -210,117 +190,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/README.md

@@ -1,18 +1,30 @@
-# MemHub / One Memory
+# MemHub
 
-MemHub 是一个本地优先的共享记忆产品：把用户授权的多个 AI 产品中的历史对话和新增内容
-汇总到同一份记忆，并让这些 AI 在独立授权后复用它。Hy Memory 是 MemHub 使用的 Python
-SDK 和记忆引擎。One Memory / `one-memory` 是历史模块、数据目录、服务和兼容命令名称。
+MemHub是一个本地优先的共享记忆产品。它把用户明确授权的AI对话和编码记录汇总到一份本地记忆中，再由用户分别授权给支持的AI工具调用。你可以继续使用熟悉的客户端，同时保留跨工具延续的上下文。Hy Memory是MemHub使用的Python SDK和记忆引擎。
+
+# 💡❤️ MemHub 刚刚开源，欢迎一起优化共建！ ❤️💡 
+
+**# 💭 MemHub处于preview阶段，当前公开版本可以下载和体验，部分平台制品、安装路径与宿主体验仍在持续优化验证。安装前请先查看Release里的实际制品和版本说明。**
+
+> 🙋 如果你遇到问题/有建议：欢迎提交Issue，并附上MemHub版本、操作系统与芯片架构、复现步骤、预期结果、实际结果和经过脱敏的日志。请不要上传APIKey、真实对话、个人路径或其他敏感信息。
+
+> 我们会公开跟进可复现的问题，持续发布修复，并根据真实反馈完善安装、同步和召回体验。
+
+**# 感谢每一条反馈，期待你和我们一起打磨MemHub的体验 ：）**
+
+> 💗 MemHub has just been open-sourced and is under active development. The current public release is available for download andevaluation. Some platform packages, installation paths, and host integrations are still being completed and verified. Check the assets
+and release notes before installing.
+If you run into a problem, please open an Issue with the version, platform,reproduction steps, and sanitized logs, We wilreviewreports, publish fixes, and keep the support matrix up to date.
 
 ## 发行与平台合同
 
-公共 Python SDK 为 `hy-memory==2.0.3`。MemHub 源码版本为 `1.0.2`
-（build 6），GitHub 仓库为
+源码当前固定使用公开 PyPI 正式版 `hy-memory==2.0.5`。MemHub 源码版本为 `1.0.5`
+（build 14），GitHub 仓库为
 [`Tencent-Hunyuan/Hy-Memory`](https://github.com/Tencent-Hunyuan/Hy-Memory)，npm 包名为
 `memhub-cli`。当前代码架构见
 [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md)。
 
-`v1.0.2` 的发行目标是 Linux x64/arm64 Runtime 与 macOS arm64/x64 App 和 Runtime。
+`v1.0.5` 的发行目标是 Linux x64/arm64 Runtime 与 macOS arm64/x64 App 和 Runtime。
 Linux 制品由 GitHub Actions 在原生架构 runner 上构建并完成生命周期验收；macOS
 制品由发行流水线完成 Developer ID 签名、公证和验收后手动上传。Windows 不支持。
 只有同时出现在 GitHub Release 与 `release-manifest.json` 中、且通过公开校验的制品才属于
@@ -25,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)。
 
@@ -101,7 +117,7 @@ MemHub 的 SQLite 数据默认位于 `~/.one-memory`，不在 npm 包或 Runtime
 
 ## Hy Memory
 
-当前开发依赖固定为公开 PyPI 包 `hy-memory==2.0.3`。SDK 配置、权限边界及 search
+SDK 依赖固定为公开 PyPI 正式版 `hy-memory==2.0.5`。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-17T11:07:57Z",
+  "documentNamespace": "https://one-memory.local/spdx/2026-10-22T13:18:16Z",
   "creationInfo": {
-    "created": "2026-10-17T11:07:57Z",
+    "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.3",
+      "versionInfo": "2.0.5",
       "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-17T11:07:57Z
+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.3
+## hy-memory 2.0.5
 
 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.2",
+  "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/prepare-publish-manifest.mjs

@@ -12,7 +12,6 @@
  * It is generated rather than hand-written so the two cannot drift: this reads
  * the real package.json and only strips what is provably not needed at runtime.
  */
-import { execFileSync } from "node:child_process";
 import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { createRequire } from "node:module";
 import { dirname, resolve } from "node:path";
@@ -20,12 +19,14 @@ import { fileURLToPath } from "node:url";
 
 const here = dirname(fileURLToPath(import.meta.url));
 const root = resolve(here, "..");
-const repositoryRoot = resolve(root, "../..");
 const require = createRequire(import.meta.url);
-const { resolveBuildVersion } = require("../../../scripts/release-version.cjs");
-const releaseVersion = resolveBuildVersion(process.env, repositoryRoot);
+const { assertSemver } = require("../../../scripts/release-version.cjs");
 const pkgPath = resolve(root, "package.json");
 const pkg = JSON.parse(readFileSync(pkgPath, "utf8"));
+const publishVersion = assertSemver(
+  process.env.MEMHUB_NPM_VERSION?.trim() || pkg.version,
+  "MEMHUB_NPM_VERSION",
+);
 const publishName = process.env.MEMHUB_NPM_PACKAGE?.trim();
 if (!publishName || !/^(?:@[a-z0-9._-]+\/)?[a-z0-9._-]+$/.test(publishName)) {
   throw new Error(
@@ -53,7 +54,7 @@ mkdirSync(outDir, { recursive: true });
 
 const published = { ...pkg };
 published.name = publishName;
-published.version = releaseVersion;
+published.version = publishVersion;
 for (const section of ["dependencies", "devDependencies", "peerDependencies"]) {
   if (!published[section]) continue;
   published[section] = Object.fromEntries(

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,10 +29,9 @@ const REQUIRED_COMMAND_SURFACE = [
   "sources",
   "sync",
   "memories",
+  "profile",
   "calls",
-  "import-file",
   "notes",
-  "extraction",
   "graph",
   "models",
   "host",
@@ -55,7 +54,6 @@ const REQUIRED_COMMAND_SURFACE = [
   "scan",
   "progress",
   "jobs",
-  "processing",
   "path",
   "adapter",
   "write",
@@ -82,16 +80,15 @@ const REQUIRED_MARKERS = [
  */
 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: "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", marker: "memhub graph width" },
   { command: "models", marker: "memhub models edit" },
   { command: "models", marker: "memhub models activate" },
-  { command: "processing", marker: "memhub processing extract" },
   { command: "jobs", marker: "memhub jobs start" },
   { command: "jobs", marker: "memhub jobs <pause|resume|cancel>" },
 ];
@@ -122,24 +119,6 @@ const STOPPED_DESTRUCTIVE_PROBES = [
     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: [
@@ -149,18 +128,10 @@ const STOPPED_DESTRUCTIVE_PROBES = [
       "--confirm",
     ],
   },
-  {
-    name: "extraction_set_apply",
-    args: ["extraction", "set", "--window", "6m", "--confirm"],
-  },
   {
     name: "graph_width_apply",
     args: ["graph", "width", "--decision", "keep_existing", "--confirm"],
   },
-  {
-    name: "processing_extract_apply",
-    args: ["processing", "extract", "--confirm"],
-  },
   {
     name: "models_activate_apply",
     args: [

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 () => {

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

@@ -4,6 +4,7 @@ import path from "node:path";
 import {
   claimRuntimeServiceForApp,
   readRuntimeServiceOwner,
+  recordSdkMigrationBlock,
   resolveRuntimeCliConfig,
 } from "@one-memory/runtime-control";
 import { describe, expect, it, vi } from "vitest";
@@ -57,6 +58,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 +132,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 +791,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 +833,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 +893,187 @@ 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("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 +1571,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 +1612,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 +1659,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();
   });
 
@@ -1785,14 +1973,11 @@ describe("stopped Runtime is exit 3, not a usage error", () => {
     ["task", "--id", "nope", "--json"],
     [
       "write",
+      "submit",
       "--session",
       "s",
-      "--from",
-      "1",
-      "--to",
-      "1",
-      "--evidence",
-      "e",
+      "--messages-file",
+      "/tmp/messages.json",
       "--json",
     ],
     ["backup", "create", "--target", "/tmp/x", "--yes", "--json"],
@@ -1898,6 +2083,101 @@ 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 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 +2287,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 +2316,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 +2364,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 +2374,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 +2396,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();

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

@@ -347,22 +347,6 @@ export const COMMANDS: readonly CommandDescriptor[] = [
     ],
     exit_codes: [EXIT_OK, EXIT_FAILED, EXIT_USAGE, EXIT_RUNTIME_STOPPED],
   },
-  {
-    name: "processing",
-    summary: "手动推进待处理证据；默认只预览，确认后执行。",
-    usage:
-      "memhub processing extract [--evidence <id> ...] [--confirm] [--json]",
-    options: [
-      {
-        flag: "--evidence <id>",
-        summary:
-          "processing extract 要提前处理的证据 ID，可重复；不给则推进下一批。",
-      },
-      DIRECT_CONFIRM_OPTION,
-      JSON_OPTION,
-    ],
-    exit_codes: [EXIT_OK, EXIT_FAILED, EXIT_USAGE, EXIT_RUNTIME_STOPPED],
-  },
   {
     name: "models",
     summary:
@@ -387,25 +371,14 @@ export const COMMANDS: readonly CommandDescriptor[] = [
   },
   {
     name: "memories",
-    summary:
-      "列出/查看记忆，或生成并显式确认带版本与 request identity 的治理操作计划。",
+    summary: "通过 SDK 数据面列出、查看、修改或物理删除记忆。",
     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 [--status <state>] [--offset <n>] [--limit <n>] [--json]\n            memhub memories show <memory-id> [--json]\n            memhub memories update <memory-id> --content-file <path> [--confirm] [--json]\n            memhub memories delete <memory-id> [--confirm] [--json]",
     options: [
-      {
-        flag: "--query <text>",
-        summary:
-          "按内容过滤；会出现在 shell 历史里，敏感词请改用 --query-file。",
-      },
-      {
-        flag: "--query-file <path>",
-        summary: "从文件读取过滤词，避免查询内容进入命令行历史。",
-      },
       {
         flag: "--status <state>",
         summary: `记忆状态，取值 ${MEMORY_STATUSES.join("、")}。`,
       },
-      { flag: "--source <id>", summary: "只看某个来源产生的记忆。" },
       { flag: "--offset <n>", summary: "跳过前 n 条，默认 0。" },
       {
         flag: "--limit <n>",
@@ -414,26 +387,20 @@ export const COMMANDS: readonly CommandDescriptor[] = [
       {
         flag: "--content-file <path>",
         summary:
-          "从有界普通文件读取新增/纠正正文；计划只保存摘要，执行时再次校验。",
+          "从有界普通文件读取 update 的新正文；预览只显示摘要，--confirm 时才写入。",
       },
-      {
-        flag: "--kind <chat|working|coding|schema|intention>",
-        summary: "新增记忆的类型，默认 chat。",
-      },
-      {
-        flag: "--scope <scope>",
-        summary: "记忆使用范围，可重复；private 必须独占。",
-      },
-      {
-        flag: "--evidence <id>",
-        summary: "新增记忆引用的 Evidence ID，可重复。",
-      },
-      PLAN_FILE_OPTION,
-      EXPLICIT_CONFIRM_OPTION,
+      DIRECT_CONFIRM_OPTION,
       JSON_OPTION,
     ],
     exit_codes: [EXIT_OK, EXIT_FAILED, EXIT_USAGE, EXIT_RUNTIME_STOPPED],
   },
+  {
+    name: "profile",
+    summary: "读取 SDK 组装后的用户长期画像（L0 + 已启用的长期画像补充）。",
+    usage: "memhub profile [--json]",
+    options: [DATA_DIR_OPTION, JSON_OPTION],
+    exit_codes: [EXIT_OK, EXIT_FAILED, EXIT_USAGE, EXIT_RUNTIME_STOPPED],
+  },
   {
     name: "calls",
     summary:
@@ -454,28 +421,6 @@ export const COMMANDS: readonly CommandDescriptor[] = [
     ],
     exit_codes: [EXIT_OK, EXIT_FAILED, EXIT_USAGE, EXIT_RUNTIME_STOPPED],
   },
-  {
-    name: "import-file",
-    summary:
-      "上传、提交或丢弃一份历史导入文件；提交与丢弃默认只出计划，需 --confirm。",
-    usage:
-      "memhub import-file upload --file <path> [--kind raw_conversation|memory_content] [--confirm] [--json]\n            memhub import-file commit <upload-id> [--confirm] [--json]\n            memhub import-file discard <upload-id> [--confirm] [--json]",
-    options: [
-      {
-        flag: "--file <path>",
-        summary:
-          "要上传的普通文件（非符号链接，<=128 MiB，.zip/.json/.md/.txt）。",
-      },
-      {
-        flag: "--kind <kind>",
-        summary:
-          "输入类型，默认 raw_conversation；memory_content 用于记忆正文。",
-      },
-      DIRECT_CONFIRM_OPTION,
-      JSON_OPTION,
-    ],
-    exit_codes: [EXIT_OK, EXIT_FAILED, EXIT_USAGE, EXIT_RUNTIME_STOPPED],
-  },
   {
     name: "notes",
     summary:
@@ -493,20 +438,6 @@ export const COMMANDS: readonly CommandDescriptor[] = [
     ],
     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 后才执行。",
@@ -554,7 +485,7 @@ export const COMMANDS: readonly CommandDescriptor[] = [
   {
     name: "recall",
     summary:
-      "从当前授权的原文与治理记忆统一检索上下文；本地只读，不调用模型、不触发补索引。",
+      "从当前授权的原文与已沉淀记忆统一检索上下文；本地只读，不调用模型、不触发补索引。",
     usage:
       "memhub recall <query> [--kind <raw|memory>] [--source <id>] [--limit <n>] [--character-budget <n>] [--timeout-ms <n>] [--json]\n            memhub recall --query-file <path> [...]\n            memhub recall --stdin [...]",
     options: [
@@ -722,16 +653,16 @@ export const COMMANDS: readonly CommandDescriptor[] = [
   },
   {
     name: "write",
-    summary:
-      "提交一次记忆写入，返回可查询的 request id；写入异步完成，不可重复提交。",
+    summary: "提交 OpenAI messages 到 SDK 写入队列，或按 request id 查询状态。",
     usage:
-      "memhub write --session <id> --from <round> --to <round> --evidence <id> [--evidence <id>...] [--live] [--json]",
+      "memhub write submit --messages-file <path> --session <id> [--source <id>] [--request-id <id>] [--memory-at <RFC3339>] [--live] [--json]\n            memhub write status --id <request-id> [--json]",
     options: [DATA_DIR_OPTION, JSON_OPTION],
     exit_codes: [EXIT_OK, EXIT_USAGE, EXIT_FAILED],
   },
   {
     name: "task",
-    summary: "查询写入任务状态；unknown 表示结果待定，不可据此重发。",
+    summary:
+      "兼容别名：按 request id 查询写入状态；新脚本请使用 write status。",
     usage: "memhub task --id <request-id> [--json]",
     options: [DATA_DIR_OPTION, JSON_OPTION],
     exit_codes: [EXIT_OK, EXIT_USAGE, EXIT_FAILED],

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

@@ -74,14 +74,12 @@ const COMMANDS = [
   "sync",
   "progress",
   "jobs",
-  "processing",
   "models",
   "memories",
+  "profile",
   // C6 App BLOCK (25f4ecf): UI write operations that had no CLI equivalent.
   "calls",
-  "import-file",
   "notes",
-  "extraction",
   "graph",
   "host",
   "recall",
@@ -562,7 +560,7 @@ describe("documented commands", () => {
     // `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", "update", "delete"],
     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,12 @@ 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("queries the SDK context endpoint directly and preserves item ids", async () => {
     const streams = captureStreams();
     try {
       expect(
@@ -209,7 +159,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 +172,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 +198,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();
@@ -384,6 +329,91 @@ describe("unified context search", () => {
     expect(streams.stdout()).not.toContain("must-not-print");
   });
 
+  it("counts characters as code points so an emoji hit stays grounded", async () => {
+    // Core reports used_characters with Python's len(), which counts code
+    // points: this text is 10 characters there and 12 UTF-16 units here.
+    const text = "消费保 📍 扩展 📡";
+    expect(text.length).toBe(12);
+    expect(Array.from(text).length).toBe(10);
+    transport.post.mockResolvedValue({
+      status: 200,
+      data: {
+        ...RESPONSE,
+        items: [{ ...RESPONSE.items[0], content: text }],
+        used_characters: 10,
+      },
+    });
+    const streams = captureStreams();
+    try {
+      expect(await run(["recall", "test", "--json"])).toBe(0);
+    } finally {
+      streams.restore();
+    }
+    expect(JSON.parse(streams.stdout())).toMatchObject({
+      state: "grounded",
+      used_characters: 10,
+      items: [{ kind: "raw", content: text }],
+    });
+  });
+
+  it("still rejects a response whose character total does not match", async () => {
+    // The same text counted as UTF-16 units is exactly what Core does not mean,
+    // so the cross-check must keep failing instead of accepting both totals.
+    const text = "消费保 📍 扩展 📡";
+    transport.post.mockResolvedValue({
+      status: 200,
+      data: {
+        ...RESPONSE,
+        items: [{ ...RESPONSE.items[0], content: text }],
+        used_characters: 12,
+      },
+    });
+    const streams = captureStreams();
+    try {
+      expect(await run(["recall", "test", "--json"])).toBe(1);
+    } finally {
+      streams.restore();
+    }
+    expect(JSON.parse(streams.stdout())).toMatchObject({
+      state: "invalid",
+      code: "response_invalid",
+    });
+  });
+
+  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]>;
@@ -37,8 +12,9 @@ export interface ContextSearchInput {
   timeout_ms: number;
 }
 
+/** 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"
@@ -50,12 +26,10 @@ export interface ContextSearchDocument {
     | "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 +41,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",
@@ -131,13 +105,7 @@ export function renderContextText(document: ContextSearchDocument): string {
         : "查到以下相关内容：",
   ];
   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)}`);
-      }
-    }
+    lines.push(`- ${String(item.content)}`);
   }
   if (document.truncated) lines.push("结果已按请求预算截断。");
   return `${lines.join("\n")}\n`;
@@ -149,84 +117,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"
-        ? String(item.content).length
-        : (item.messages as Array<Record<string, unknown>>).reduce(
-            (sum, message) => sum + String(message.text).length,
-            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 +156,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,
@@ -330,6 +228,17 @@ function record(value: unknown): Record<string, unknown> | null {
     : null;
 }
 
+/**
+ * Count characters the way Core does. Python's len() counts Unicode code
+ * points; String.prototype.length counts UTF-16 code units, so an emoji outside
+ * the BMP is one character to Core and two here. Comparing the two totals made
+ * every response containing an emoji fail the used_characters cross-check and
+ * surface as response_invalid.
+ */
+function characterCount(value: unknown): number {
+  return Array.from(String(value)).length;
+}
+
 function boundedText(
   value: unknown,
   maximum: number,
@@ -363,27 +272,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,16 @@ import axios from "axios";
  */
 const READ_ONLY_PATHS = [
   "/api/v1/call-events",
-  "/api/v1/home-summary",
   "/api/v1/import-jobs",
   "/api/v1/live-sync",
-  "/api/v1/memory-library",
   "/api/v1/memory-processing",
-  "/api/v1/memory-tasks",
   "/api/v1/model-profiles",
   "/api/v1/sources",
+  "/api/v2/home-summary",
+  "/api/v2/memory-library",
+  "/api/v2/user-profile",
 ] as const;
+const SDK_MEMORY_DETAIL = /^\/api\/v2\/memories\/[A-Za-z0-9][\w.-]{0,127}$/;
 
 /** 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 +65,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`
@@ -170,7 +168,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,9 +192,8 @@ 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 (!SDK_MEMORY_DETAIL.test(path)) return false;
+  const segment = path.slice("/api/v2/memories/".length);
   return !(RESERVED_MEMORY_SEGMENTS as readonly string[]).includes(segment);
 }
 
@@ -211,6 +208,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.
@@ -237,19 +271,23 @@ 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";
   },
 ): Promise<MemoryWriteReceipt> {
   const response = await axios.post<MemoryWriteReceipt>(
-    `${baseUrlOf(attachment)}/api/v1/memory-writes`,
+    `${baseUrlOf(attachment)}/api/v2/memory-writes`,
     {
-      internal_session_id: request.session,
-      first_round: request.first_round,
-      last_round: request.last_round,
-      evidence_ids: [...request.evidence_ids],
+      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 }),
     },
     {
@@ -380,7 +418,7 @@ export async function readMemoryWrite(
 ): 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)}`,
       {
         headers: { Authorization: `Bearer ${attachment.apiToken}` },
         timeout: 10_000,

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

@@ -6,6 +6,7 @@ const WRITE_PATHS = [
 ] as const;
 const MEMORY_WRITE_PATH =
   /^\/api\/v1\/memories(?:\/[A-Za-z0-9][\w.-]{0,127}\/(?:correct|scopes|actions\/delete))?$/;
+const SDK_MEMORY_PATH = /^\/api\/v2\/memories\/[A-Za-z0-9][\w.-]{0,127}$/;
 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 =
@@ -170,7 +171,7 @@ export function createCoreOperations(attachment: {
       body: Record<string, unknown>,
       signal?: AbortSignal,
     ) {
-      if (path !== EXTRACTION_SETTINGS_PATH) {
+      if (path !== EXTRACTION_SETTINGS_PATH && !SDK_MEMORY_PATH.test(path)) {
         throw new Error("core_operation_path_not_allowed");
       }
       let response: { status: number; data: unknown };
@@ -232,7 +233,7 @@ export function createCoreOperations(attachment: {
       };
     },
     async delete<T>(path: string, signal?: AbortSignal) {
-      if (!IMPORT_FILE.test(path)) {
+      if (!IMPORT_FILE.test(path) && !SDK_MEMORY_PATH.test(path)) {
         throw new Error("core_operation_path_not_allowed");
       }
       let response: { status: number; data: 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/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 };
@@ -237,63 +190,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 +218,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/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;
-}

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

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

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

@@ -1,6 +1,5 @@
-import type { GovernedMemory } from "@one-memory/contracts";
+import type { SdkMemoryPage, SdkMemoryRecord } from "@one-memory/contracts";
 import { type CoreReader, RESERVED_MEMORY_SEGMENTS } from "./core-client.js";
-import { validateMemoryDetail, validateMemoryPage } from "./core-responses.js";
 import { PRODUCT } from "./version.js";
 
 /** Output budget: a long memory is shortened visibly, never dropped silently. */
@@ -16,6 +15,29 @@ export function isMemoryId(value: string): boolean {
   );
 }
 
+const CONTENT_MAX_CHARACTERS = 100_000;
+
+/** A memory body read from `--content-file`: UTF-8, non-blank, bounded, and
+ * free of control characters other than tab and newline. */
+export function parseMemoryContent(bytes: Buffer): string | null {
+  if (bytes.byteLength > CONTENT_MAX_CHARACTERS * 4 + 2) return null;
+  let decoded: string;
+  try {
+    decoded = new TextDecoder("utf-8", { fatal: true }).decode(bytes);
+  } catch {
+    return null;
+  }
+  const content = decoded.replace(/\r?\n$/, "");
+  return content.trim().length > 0 &&
+    [...content].length <= CONTENT_MAX_CHARACTERS &&
+    ![...content].some((character) => {
+      const code = character.charCodeAt(0);
+      return code <= 8 || (code >= 11 && code <= 31) || code === 127;
+    })
+    ? content
+    : null;
+}
+
 export interface MemoryQuery {
   query?: string;
   status?: string;
@@ -47,10 +69,8 @@ export async function readMemoryPage(
     offset: query.offset,
     limit: query.limit,
   };
-  if (query.query !== undefined) parameters.query = query.query;
-  if (query.status !== undefined) parameters.status = query.status;
-  if (query.source !== undefined) parameters.source = query.source;
-  const outcome = await reader<unknown>("/api/v1/memory-library", parameters);
+  if (query.status !== undefined) parameters.statuses = query.status;
+  const outcome = await reader<unknown>("/api/v2/memory-library", parameters);
   if (outcome.state !== "ok") {
     return {
       schema_version: 1,
@@ -59,7 +79,7 @@ export async function readMemoryPage(
       memories: [],
     };
   }
-  const page = validateMemoryPage(outcome.data, query);
+  const page = sdkMemoryPage(outcome.data);
   if (page === null) {
     return {
       schema_version: 1,
@@ -68,7 +88,7 @@ export async function readMemoryPage(
       memories: [],
     };
   }
-  const items = page.items;
+  const items = page.memories;
   return {
     schema_version: 1,
     product: PRODUCT,
@@ -88,7 +108,7 @@ export async function readMemoryDetail(
   reader: CoreReader,
   memoryId: string,
 ): Promise<MemoryDetailDocument> {
-  const outcome = await reader<unknown>(`/api/v1/memories/${memoryId}`);
+  const outcome = await reader<unknown>(`/api/v2/memories/${memoryId}`);
   if (outcome.state !== "ok") {
     return {
       schema_version: 1,
@@ -98,8 +118,8 @@ export async function readMemoryDetail(
       history: [],
     };
   }
-  const detail = validateMemoryDetail(outcome.data, memoryId);
-  if (detail === null) {
+  const memory = sdkMemory(outcome.data);
+  if (memory === null || memory.memory_id !== memoryId) {
     return {
       schema_version: 1,
       product: PRODUCT,
@@ -111,33 +131,9 @@ export async function readMemoryDetail(
   return {
     schema_version: 1,
     product: PRODUCT,
-    memory: { state: "ok", ...describeMemory(detail.memory) },
-    evidence: (detail.evidence ?? []).map((item) => {
-      const budgeted = budget(item.verbatim ?? "");
-      return {
-        evidence_id: item.evidence_id,
-        available: item.available,
-        source_id: item.source_id,
-        written_by: item.written_by,
-        created_at: item.created_at,
-        excerpt: budgeted.text,
-        excerpt_truncated: budgeted.truncated,
-        excerpt_characters: budgeted.characters,
-      };
-    }),
-    history: (detail.history ?? []).map((item) => {
-      const content = budget(item.content);
-      return {
-        revision: item.revision,
-        action: item.action,
-        status: item.status,
-        scopes: item.scopes,
-        created_at: item.created_at,
-        content: content.text,
-        content_truncated: content.truncated,
-        content_characters: content.characters,
-      };
-    }),
+    memory: { state: "ok", ...describeMemory(memory) },
+    evidence: [],
+    history: [],
   };
 }
 
@@ -156,9 +152,7 @@ export function renderMemoryPageText(document: MemoryPageDocument): string {
   ];
   for (const memory of document.memories) {
     lines.push(
-      `- ${memory.memory_id}  ${memory.status}/${memory.kind}  rev ${memory.revision}  scopes=${
-        (memory.scopes as string[]).join(",") || "无"
-      }`,
+      `- ${memory.memory_id}  ${memory.status}/${memory.layer}  source=${memory.source ?? "未知"}`,
       `  ${memory.content}${memory.content_truncated ? ` …（共 ${memory.content_characters} 字）` : ""}`,
     );
   }
@@ -177,54 +171,91 @@ export function renderMemoryDetailText(document: MemoryDetailDocument): string {
   }
   const lines = [
     `记忆 ${memory.memory_id}`,
-    `状态：${memory.status}  类型：${memory.kind}  来源方式：${memory.origin}  版本：${memory.revision}`,
-    `授权范围：${(memory.scopes as string[]).join(",") || "无"}`,
-    `证据：${(memory.evidence_ids as string[]).join(",") || "无"}`,
-    `更新时间：${memory.updated_at}`,
+    `状态：${memory.status}  层：${memory.layer}  来源：${memory.source ?? "未知"}`,
+    `owner：${memory.owner ?? "未知"}  latest：${memory.is_latest}`,
+    `raw IDs：${(memory.source_raw_ids as string[]).join(",") || "无"}`,
     "",
     String(memory.content),
     memory.content_truncated ? `…（共 ${memory.content_characters} 字）` : "",
     "",
-    "原文摘录：",
+    "SDK memory 数据不在 MemHub 中保留 Evidence/版本副本。",
   ];
-  for (const item of document.evidence) {
-    lines.push(
-      `- ${item.evidence_id}  来源=${item.source_id ?? "未知"}  作者=${item.written_by ?? "未知"}  可读=${item.available}`,
-      `  ${item.excerpt}${item.excerpt_truncated ? ` …（共 ${item.excerpt_characters} 字）` : ""}`,
-    );
-  }
-  if (document.evidence.length === 0) lines.push("（无可读原文）");
-  lines.push("", "版本历史：");
-  for (const item of document.history) {
-    lines.push(
-      `- rev ${item.revision}  ${item.action}  ${item.status}  scopes=${(item.scopes as string[]).join(",")}`,
-      `  ${item.content}${item.content_truncated ? ` …（共 ${item.content_characters} 字）` : ""}`,
-    );
-  }
-  if (document.history.length === 0) lines.push("（无）");
   lines.push("");
   return lines.join("\n");
 }
 
-function describeMemory(memory: GovernedMemory): Record<string, unknown> {
+function describeMemory(memory: SdkMemoryRecord): Record<string, unknown> {
   const budgeted = budget(memory.content ?? "");
   return {
     memory_id: memory.memory_id,
     status: memory.status,
-    kind: memory.kind,
-    origin: memory.origin,
-    revision: memory.revision,
-    scopes: memory.scopes ?? [],
-    evidence_ids: memory.evidence_ids ?? [],
+    layer: memory.layer,
+    is_latest: memory.is_latest,
+    owner: memory.owner,
+    source: memory.source,
+    source_raw_ids: memory.source_raw_ids,
+    supersedes: memory.supersedes,
+    superseded_by: memory.superseded_by,
     tags: memory.tags ?? [],
-    created_at: memory.created_at,
-    updated_at: memory.updated_at,
+    memory_at: memory.memory_at,
+    gmt_created: memory.gmt_created,
     content: budgeted.text,
     content_truncated: budgeted.truncated,
     content_characters: budgeted.characters,
   };
 }
 
+function sdkMemoryPage(value: unknown): SdkMemoryPage | null {
+  if (!record(value) || !Array.isArray(value.memories)) return null;
+  const memories = value.memories.map(sdkMemory);
+  if (memories.some((item) => item === null)) return null;
+  if (!integer(value.total) || !integer(value.limit) || !integer(value.offset))
+    return null;
+  return {
+    memories: memories as SdkMemoryRecord[],
+    total: value.total,
+    limit: value.limit,
+    offset: value.offset,
+  };
+}
+
+function sdkMemory(value: unknown): SdkMemoryRecord | null {
+  if (
+    !record(value) ||
+    !text(value.memory_id) ||
+    typeof value.content !== "string" ||
+    !text(value.layer) ||
+    !text(value.status) ||
+    typeof value.is_latest !== "boolean" ||
+    !strings(value.supersedes) ||
+    !strings(value.superseded_by) ||
+    !strings(value.tags) ||
+    !strings(value.source_raw_ids) ||
+    !text(value.user_id) ||
+    !text(value.agent_id)
+  )
+    return null;
+  return value as unknown as SdkMemoryRecord;
+}
+
+function record(value: unknown): value is Record<string, unknown> {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+
+function text(value: unknown): value is string {
+  return typeof value === "string" && value.length > 0;
+}
+
+function strings(value: unknown): value is string[] {
+  return (
+    Array.isArray(value) && value.every((item) => typeof item === "string")
+  );
+}
+
+function integer(value: unknown): value is number {
+  return Number.isInteger(value) && Number(value) >= 0;
+}
+
 function budget(value: string): {
   text: string;
   truncated: boolean;

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

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

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

@@ -146,17 +146,16 @@ describe("memhub short-command contract", () => {
     ).join("\n");
     for (const shortForm of [
       "memhub calls clear",
-      "memhub import-file upload",
-      "memhub import-file commit",
-      "memhub import-file discard",
       "memhub notes add",
       "memhub notes process",
       "memhub models setup",
       "memhub models activate",
       "memhub models edit",
-      "memhub extraction set",
       "memhub graph width",
-      "memhub processing extract",
+      "memhub write submit",
+      "memhub write status",
+      "memhub memories update",
+      "memhub memories delete",
     ]) {
       expect(flattened).toContain(shortForm);
     }

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

@@ -6,6 +6,7 @@
 
 import { describe, expect, it } from "vitest";
 
+import { parseOpenAIMessages } from "./core-client.js";
 import {
   asPlanDocument,
   describe as describePlan,
@@ -259,93 +260,92 @@ describe("unknown flags are rejected", () => {
 
 describe("write", () => {
   const base = [
+    "submit",
     "--session",
     "s1",
-    "--from",
-    "1",
-    "--to",
-    "5",
-    "--evidence",
-    "e1",
+    "--messages-file",
+    "/tmp/messages.json",
   ];
 
   it("accepts a well-formed write", () => {
     const parsed = parseWriteCommand(base);
     expect(parsed).toEqual({
+      kind: "submit",
       session: "s1",
-      first_round: 1,
-      last_round: 5,
-      evidence_ids: ["e1"],
+      source: "memhub-cli",
+      messages_file: "/tmp/messages.json",
     });
   });
 
-  it("rejects a write with no evidence", () => {
-    expect(
-      parseWriteCommand(["--session", "s1", "--from", "1", "--to", "5"]),
-    ).toBeNull();
+  it("rejects a write with no messages file", () => {
+    expect(parseWriteCommand(["submit", "--session", "s1"])).toBeNull();
   });
 
-  it("rejects a descending round range", () => {
+  it("accepts source, request identity, and RFC3339 time", () => {
     expect(
       parseWriteCommand([
-        "--session",
-        "s1",
-        "--from",
-        "5",
-        "--to",
-        "1",
-        "--evidence",
-        "e1",
+        ...base,
+        "--source",
+        "cursor",
+        "--request-id",
+        "request-1",
+        "--memory-at",
+        "2026-10-22T00:00:00+08:00",
       ]),
-    ).toBeNull();
+    ).toMatchObject({
+      source: "cursor",
+      request_id: "request-1",
+      memory_at: "2026-10-22T00:00:00+08:00",
+    });
   });
 
-  it("rejects a round starting below one", () => {
+  it("rejects a timestamp without timezone", () => {
     expect(
-      parseWriteCommand([
-        "--session",
-        "s1",
-        "--from",
-        "0",
-        "--to",
-        "5",
-        "--evidence",
-        "e1",
-      ]),
+      parseWriteCommand([...base, "--memory-at", "2026-10-22T00:00:00"]),
     ).toBeNull();
   });
 
-  it("rejects a non-integer round", () => {
-    expect(
-      parseWriteCommand([
-        "--session",
-        "s1",
-        "--from",
-        "x",
-        "--to",
-        "5",
-        "--evidence",
-        "e1",
-      ]),
-    ).toBeNull();
-  });
-
-  it("accepts several evidence ids", () => {
-    const parsed = parseWriteCommand([...base, "--evidence", "e2"]);
-    expect(parsed?.evidence_ids).toEqual(["e1", "e2"]);
+  it("parses status under write", () => {
+    expect(parseWriteCommand(["status", "--id", "request-1"])).toEqual({
+      kind: "status",
+      id: "request-1",
+    });
   });
 
   it("marks --live as priority live", () => {
-    expect(parseWriteCommand([...base, "--live"])?.priority).toBe("live");
+    expect(parseWriteCommand([...base, "--live"])).toMatchObject({
+      kind: "submit",
+      priority: "live",
+    });
   });
 
   it("leaves priority unset by default", () => {
-    expect(parseWriteCommand(base)?.priority).toBeUndefined();
+    expect(parseWriteCommand(base)).not.toHaveProperty("priority");
   });
 
   it("rejects a repeated --json", () => {
     expect(parseWriteCommand([...base, "--json", "--json"])).toBeNull();
   });
+
+  it("validates OpenAI text messages and requires a user turn", () => {
+    expect(
+      parseOpenAIMessages({
+        messages: [
+          { role: "user", content: "Remember Tuesday." },
+          { role: "assistant", content: "Understood.", ignored: true },
+        ],
+      }),
+    ).toEqual([
+      { role: "user", content: "Remember Tuesday." },
+      { role: "assistant", content: "Understood." },
+    ]);
+    expect(
+      parseOpenAIMessages([{ role: "assistant", content: "No user turn." }]),
+    ).toBeNull();
+    expect(
+      parseOpenAIMessages([{ role: "system", content: "Hidden prompt." }]),
+    ).toBeNull();
+  });
 });
 
 describe("task", () => {

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

@@ -255,52 +255,73 @@ export function restoreConfirmationMatches(
   return confirmPath === source;
 }
 
-export interface WriteCommand {
+export interface WriteSubmitCommand {
+  readonly kind: "submit";
   readonly session: string;
-  readonly first_round: number;
-  readonly last_round: number;
-  readonly evidence_ids: readonly string[];
+  readonly source: string;
+  readonly messages_file: string;
+  readonly request_id?: string;
+  readonly memory_at?: string;
   readonly priority?: "live" | "normal";
 }
 
-/** Parse `write`. Evidence is required: no write without something to cite. */
+export interface WriteStatusCommand {
+  readonly kind: "status";
+  readonly id: string;
+}
+
+export type WriteCommand = WriteSubmitCommand | WriteStatusCommand;
+
+/** Parse SDK-native `write submit|status`. */
 export function parseWriteCommand(
   args: readonly string[],
 ): WriteCommand | null {
   if (args.filter((item) => item === "--json").length > 1) return null;
+  const meaningful = args.filter((item) => item !== "--json");
+  if (meaningful[0] === "status") {
+    const status = parseTaskCommand(meaningful.slice(1));
+    return status === null ? null : { kind: "status", id: status.id };
+  }
+  const input = meaningful[0] === "submit" ? meaningful.slice(1) : meaningful;
   let session: string | undefined;
-  let first: number | undefined;
-  let last: number | undefined;
+  let source = "memhub-cli";
+  let messagesFile: string | undefined;
+  let requestId: string | undefined;
+  let memoryAt: string | undefined;
   let priority: "live" | "normal" | undefined;
-  const evidence: string[] = [];
 
-  for (let index = 0; index < args.length; index += 1) {
-    const arg = args[index];
-    if (arg === "--json") continue;
+  for (let index = 0; index < input.length; index += 1) {
+    const arg = input[index];
     if (arg === "--live") {
       priority = "live";
       continue;
     }
-    const value = args[index + 1];
+    const value = input[index + 1];
     if (value === undefined || value.startsWith("--")) return null;
     index += 1;
     if (arg === "--session") session = value;
-    else if (arg === "--from") first = Number(value);
-    else if (arg === "--to") last = Number(value);
-    else if (arg === "--evidence") evidence.push(value);
+    else if (arg === "--source") source = value;
+    else if (arg === "--messages-file") messagesFile = value;
+    else if (arg === "--request-id") requestId = value;
+    else if (arg === "--memory-at") memoryAt = value;
     else return null;
   }
 
-  if (session === undefined || first === undefined || last === undefined)
+  if (session === undefined || messagesFile === undefined || !source)
     return null;
-  if (!Number.isInteger(first) || first < 1) return null;
-  if (!Number.isInteger(last) || last < first) return null;
-  if (evidence.length === 0) return null;
-  const command: WriteCommand = {
+  if (
+    memoryAt !== undefined &&
+    (!Number.isFinite(Date.parse(memoryAt)) ||
+      !/(?:Z|[+-]\d\d:\d\d)$/.test(memoryAt))
+  )
+    return null;
+  const command: WriteSubmitCommand = {
+    kind: "submit",
     session,
-    first_round: first,
-    last_round: last,
-    evidence_ids: evidence,
+    source,
+    messages_file: messagesFile,
+    ...(requestId === undefined ? {} : { request_id: requestId }),
+    ...(memoryAt === undefined ? {} : { memory_at: memoryAt }),
   };
   return priority === undefined ? command : { ...command, priority };
 }

memhub/apps/cli/src/publish-manifest.test.ts

@@ -48,7 +48,11 @@ describe("publish manifest is production-safe", () => {
     execFileSync("node", ["scripts/prepare-publish-manifest.mjs"], {
       cwd: root,
       stdio: "pipe",
-      env: { ...process.env, MEMHUB_NPM_PACKAGE: "@example/memhub-cli" },
+      env: {
+        ...process.env,
+        MEMHUB_NPM_PACKAGE: "@example/memhub-cli",
+        MEMHUB_NPM_VERSION: "1.0.5",
+      },
     });
     const published = JSON.parse(
       readFileSync(path.join(root, "dist-publish", "package.json"), "utf8"),
@@ -56,6 +60,7 @@ describe("publish manifest is production-safe", () => {
     expect(published.dependencies).toBeUndefined();
     expect(published.private).toBe(false);
     expect(published.name).toBe("@example/memhub-cli");
+    expect(published.version).toBe("1.0.5");
     expect(published.bin).toMatchObject({
       memhub: "dist/one-memory.cjs",
       "memhub-cli": "dist/one-memory.cjs",

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

@@ -160,7 +160,7 @@ describe("calls clear", () => {
   });
 });
 
-describe("import-file", () => {
+describe.skip("retired import-file", () => {
   it("never uploads without --confirm", async () => {
     const directory = await mkdtemp(path.join(tmpdir(), "om-import-"));
     const file = path.join(directory, "export.json");
@@ -356,7 +356,7 @@ describe("notes / extraction / graph / manual extract", () => {
     expect(JSON.parse(applied.stdout).state).toBe("committed");
   });
 
-  it("plans then applies the extraction window", async () => {
+  it.skip("plans then applies the extraction window", async () => {
     const preview = await capturedRun([
       "extraction",
       "set",
@@ -417,7 +417,7 @@ describe("notes / extraction / graph / manual extract", () => {
     );
   });
 
-  it("plans manual extraction and applies it only on confirm", async () => {
+  it.skip("plans manual extraction and applies it only on confirm", async () => {
     const preview = await capturedRun([
       "processing",
       "extract",

memhub/apps/cli/src/version.ts

@@ -1,5 +1,9 @@
 declare const __ONE_MEMORY_VERSION__: string;
 declare const __ONE_MEMORY_BUILD_NUMBER__: string;
+declare const __MEMHUB_DEFAULT_RUNTIME_VERSION__: string;
+
+const SEMVER =
+  /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*)?(?:\+[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*)?$/;
 
 const embeddedVersion =
   typeof __ONE_MEMORY_VERSION__ === "string"
@@ -9,13 +13,18 @@ const embeddedBuildNumber =
   typeof __ONE_MEMORY_BUILD_NUMBER__ === "string"
     ? __ONE_MEMORY_BUILD_NUMBER__.trim()
     : "";
+const embeddedRuntimeVersion =
+  typeof __MEMHUB_DEFAULT_RUNTIME_VERSION__ === "string"
+    ? __MEMHUB_DEFAULT_RUNTIME_VERSION__.trim()
+    : "";
 
-export const CLI_VERSION =
-  /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*)?(?:\+[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*)?$/.test(
-    embeddedVersion,
-  )
-    ? embeddedVersion
-    : "development";
+export const CLI_VERSION = SEMVER.test(embeddedVersion)
+  ? embeddedVersion
+  : "development";
+
+export const RUNTIME_RELEASE_VERSION = SEMVER.test(embeddedRuntimeVersion)
+  ? embeddedRuntimeVersion
+  : CLI_VERSION;
 
 export const CLI_BUILD_NUMBER = /^\d+$/.test(embeddedBuildNumber)
   ? Number(embeddedBuildNumber)

memhub/apps/cli/tsup.config.ts

@@ -2,11 +2,22 @@ import { createRequire } from "node:module";
 import { defineConfig } from "tsup";
 
 const require = createRequire(import.meta.url);
-const { resolveBuildVersion } =
+const { assertSemver, resolveBuildVersion } =
   require("../../scripts/release-version.cjs") as {
+    assertSemver(value: string, label?: string): string;
     resolveBuildVersion(environment?: NodeJS.ProcessEnv, root?: string): string;
   };
 const releaseVersion = resolveBuildVersion(process.env);
+const packageVersion = (require("./package.json") as { version: string })
+  .version;
+const cliVersion = assertSemver(
+  process.env.MEMHUB_NPM_VERSION?.trim() || packageVersion,
+  "MEMHUB_NPM_VERSION",
+);
+const runtimeReleaseVersion = assertSemver(
+  process.env.MEMHUB_DEFAULT_RUNTIME_VERSION?.trim() || releaseVersion,
+  "MEMHUB_DEFAULT_RUNTIME_VERSION",
+);
 
 export default defineConfig({
   entry: { "one-memory": "src/entry.ts" },
@@ -15,7 +26,7 @@ export default defineConfig({
   outDir: "dist",
   clean: true,
   define: {
-    __ONE_MEMORY_VERSION__: JSON.stringify(releaseVersion),
+    __ONE_MEMORY_VERSION__: JSON.stringify(cliVersion),
     __ONE_MEMORY_BUILD_NUMBER__: JSON.stringify(
       process.env.ONE_MEMORY_BUILD_NUMBER ?? "unknown",
     ),
@@ -25,11 +36,15 @@ export default defineConfig({
     __MEMHUB_DEFAULT_RELEASE_MANIFEST_URL_TEMPLATE__: JSON.stringify(
       process.env.MEMHUB_DEFAULT_RELEASE_MANIFEST_URL_TEMPLATE ?? "",
     ),
+    __MEMHUB_DEFAULT_RUNTIME_VERSION__: JSON.stringify(runtimeReleaseVersion),
   },
   // The shared operations package ships TypeScript sources, so it must be
   // inlined into the CJS bundle the same way runtime-control is; otherwise the
   // emitted bundle tries to `require` a `.js` file that only exists as `.ts`.
+  // `@one-memory/contracts` is the same kind of package and is imported for a
+  // value (the host-id grammar), so it has to be inlined too.
   noExternal: [
+    "@one-memory/contracts",
     "@one-memory/operations",
     "@one-memory/runtime-control",
     "axios",

memhub/apps/cli/vitest.config.ts

@@ -11,6 +11,7 @@ export default defineConfig({
     __ONE_MEMORY_BUILD_NUMBER__: JSON.stringify("unknown"),
     __ONE_MEMORY_COMMIT__: JSON.stringify("unknown"),
     __MEMHUB_DEFAULT_RELEASE_MANIFEST_URL_TEMPLATE__: JSON.stringify(""),
+    __MEMHUB_DEFAULT_RUNTIME_VERSION__: JSON.stringify(version),
   },
   test: {
     testTimeout: 120_000,

memhub/apps/core/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "uv_build"
 
 [project]
 name = "one-memory"
-version = "1.0.2"
+version = "1.0.5"
 description = "MemHub local-first memory core"
 readme = "README.md"
 requires-python = ">=3.12"
@@ -12,8 +12,9 @@ dependencies = [
     "fastapi>=0.141.1",
     "filelock>=3.32.4",
     # Public SDK version validated against MemHub's permission and recall contracts.
-    "hy-memory==2.0.3",
-    # Retrieval's derived vector index directly consumes these locked versions.
+    "hy-memory==2.0.5",
+    # chromadb arrives through the HY SDK; locked here so an unrelated upgrade
+    # cannot move the SDK's store. Built-in embedding consumes numpy directly.
     "chromadb==1.5.9",
     "numpy==2.5.2",
     "httpx>=0.28.1",

memhub/apps/core/scripts/verify_c2_slice.py

@@ -42,12 +42,10 @@ TARGETED = (
     "tests/test_database_contention.py",
     "tests/test_main_database_fairness.py",
     "tests/test_soak_probe_effectiveness.py",
-    "tests/test_evidence_reconcile_primitive.py",
     "tests/test_sqlite_semantics_gate.py",
     "tests/test_store_binding.py",
     "tests/test_store_binding_ratchet.py",
     "tests/test_main_database_entry.py",
-    "tests/test_memory_processing.py",
     "tests/test_extraction_window.py",
     "tests/test_extraction_defer.py",
     "tests/test_active_memory_window.py",

memhub/apps/core/src/one_memory/__init__.py

@@ -2,11 +2,5 @@
 
 import os
 
-from one_memory.hy_runtime_config import configure_hy_behavior_environment
-
-# HY has a few reader switches evaluated at module import time.  Fix the
-# product-owned, non-secret behavior before any one_memory module imports HY.
-configure_hy_behavior_environment()
-
 _version = os.environ.get("ONE_MEMORY_VERSION", "").strip()
 __version__ = _version if _version else "development"

memhub/apps/core/src/one_memory/auth.py

@@ -1,4 +1,5 @@
 import hmac
+import ipaddress
 from collections.abc import Callable
 from urllib.parse import urlsplit
 
@@ -35,7 +36,15 @@ def is_loopback_origin(origin: str) -> bool:
     host = parsed.hostname
     if not host:
         return False
-    return host in LOOPBACK_HOSTNAMES or host.startswith("127.")
+    if host in LOOPBACK_HOSTNAMES:
+        return True
+    # A prefix check is not enough: "127.attacker.example" is a perfectly valid
+    # DNS name that resolves wherever its owner wants (including 127.0.0.1 via
+    # DNS rebinding). Parse the address and ask the standard library.
+    try:
+        return ipaddress.ip_address(host).is_loopback
+    except ValueError:
+        return False
 
 
 def local_api_guard(

memhub/apps/core/src/one_memory/background_work.py

@@ -175,6 +175,22 @@ async def in_interactive_read[T](
     return await in_read_pool(interactive_read_pool(), work, *args, **kwargs)
 
 
+def _retrieve[T](future: "asyncio.Future[T]") -> None:
+    """Mark a shielded read's outcome as seen.
+
+    `in_read_pool` shields the wrapped worker, so a caller that gives up and
+    cancels leaves the read running to completion. When that read then fails,
+    nothing awaits the future any more: asyncio reports the orphan at GC as
+    "Future exception was never retrieved", the loop handler turns it into a
+    `core.loop.task_exception` error diagnostic, and a lane that degraded on
+    its own budget -- correctly, and already reported -- looks like a crashed
+    task on top of it. Retrieving here keeps the diagnostics honest. Awaiting
+    still raises for callers that are still there, so no failure is hidden.
+    """
+    if not future.cancelled():
+        future.exception()
+
+
 async def in_read_pool[T](
     pool: ThreadPoolExecutor,
     work: Callable[..., T],
@@ -193,7 +209,9 @@ async def in_read_pool[T](
             _interactive_reads -= 1
 
     worker.add_done_callback(released)
-    return await asyncio.shield(asyncio.wrap_future(worker))
+    pending = asyncio.wrap_future(worker)
+    pending.add_done_callback(_retrieve)
+    return await asyncio.shield(pending)
 
 
 async def wait_for_interactive_reads() -> None:

memhub/apps/core/src/one_memory/call_event_recorder.py

@@ -15,7 +15,7 @@ from one_memory.call_event_store import (
     CallTool,
     HostId,
 )
-from one_memory.context_models import ContextSearchResponse, MemoryContextItem, RawContextItem
+from one_memory.context_models import SdkContextSearchResponse
 from one_memory.external_memory_access import ExternalMemoryAccess
 from one_memory.recall import RecallReceipt
 
@@ -41,75 +41,27 @@ def _host_id(access: ExternalMemoryAccess | None) -> HostId | None:
     return cast(HostId, host) if host in HOSTS else None
 
 
-def context_call_event(
-    result: ContextSearchResponse,
+def sdk_context_call_event(
+    result: SdkContextSearchResponse,
     access: ExternalMemoryAccess | None,
+    *,
+    memory_searched: bool,
+    timed_out: bool,
 ) -> CallEvent:
-    references: list[CallReference] = []
-    seen: set[tuple[str, str, int]] = set()
-    for item in result.items:
-        if isinstance(item, RawContextItem):
-            candidates = [
-                CallReference(
-                    kind="raw",
-                    id=message.evidence_id,
-                    revision=message.revision,
-                    source_id=item.source_id,
-                )
-                for message in item.messages
-            ]
-        elif isinstance(item, MemoryContextItem):
-            candidates = [
-                CallReference(
-                    kind="memory", id=item.memory_id, revision=item.revision, source_id=None
-                )
-            ]
-        else:
-            continue
-        for reference in candidates:
-            identity = (reference.kind, reference.id, reference.revision)
-            if identity not in seen:
-                seen.add(identity)
-                references.append(reference)
-    timed_out = any(
-        path.reason == "timeout_budget" for path in (result.paths.raw, result.paths.memory)
+    # SDK items carry no Evidence/Governance revision, and the reference
+    # resolver reads the legacy store, so the event records counts only.
+    raw_count = sum(item.kind == "raw" for item in result.items)
+    memory_count = sum(item.kind == "memory" for item in result.items)
+    state: CallState = "timed_out" if timed_out else result.state
+    return _metadata_event(
+        tool="om_recall" if memory_searched else "om_conversations",
+        state=state,
+        elapsed_ms=result.total_ms,
+        access=access,
+        raw_count=raw_count,
+        memory_count=memory_count,
+        event_id=UUID(result.request_id),
     )
-    state: CallState = (
-        "partial" if timed_out and references else "timed_out" if timed_out else result.state
-    )
-    return CallEvent.model_validate(
-        {
-            "event_id": UUID(result.request_id),
-            "occurred_at": datetime.now(UTC),
-            "host_id": _host_id(access),
-            "installation_id": UUID(access.installation_id) if access else None,
-            "tool": _context_tool(result),
-            "state": state,
-            "stage": "core_result",
-            "delivery": "unknown",
-            "adoption": "unknown",
-            "host_session_id": None,
-            "injection_elapsed_ms": None,
-            "elapsed_ms": result.total_ms,
-            "raw_count": sum(isinstance(item, RawContextItem) for item in result.items),
-            "memory_count": sum(isinstance(item, MemoryContextItem) for item in result.items),
-            "references": tuple(references),
-        }
-    )
-
-
-def record_context_result(
-    store: CallEventStore,
-    result: ContextSearchResponse,
-    access: ExternalMemoryAccess | None,
-) -> None:
-    store.record(context_call_event(result, access))
-
-
-def _context_tool(result: ContextSearchResponse) -> CallTool:
-    if result.paths.memory.status not in {"not_requested", "not_authorized"}:
-        return "om_recall"
-    return "om_conversations"
 
 
 def _metadata_event(
@@ -142,26 +94,6 @@ def _metadata_event(
     )
 
 
-def conversation_call_event(
-    result: object,
-    access: ExternalMemoryAccess | None,
-    elapsed_ms: float,
-) -> CallEvent:
-    hits = tuple(getattr(result, "hits", ()) or ())
-    conversations = {
-        conversation_id
-        for hit in hits
-        if (conversation_id := getattr(hit, "conversation_id", None))
-    }
-    return _metadata_event(
-        tool="om_conversations",
-        state="grounded" if hits else "empty",
-        elapsed_ms=elapsed_ms,
-        access=access,
-        raw_count=min(len(conversations), 20),
-    )
-
-
 def ask_call_event(
     result: object,
     access: ExternalMemoryAccess | None,
@@ -255,8 +187,9 @@ def record_legacy_result(
             host_session_id=None,
             injection_elapsed_ms=None,
             elapsed_ms=elapsed_ms,
-            raw_count=0,
-            memory_count=len(receipt.hits),
+            # A raw-fallback recall returned conversation excerpts, not memories.
+            raw_count=len(receipt.hits) if receipt.mode == "raw" else 0,
+            memory_count=0 if receipt.mode == "raw" else len(receipt.hits),
             references=(),
         )
     )

memhub/apps/core/src/one_memory/call_event_references.py

@@ -76,8 +76,7 @@ def _memory(db: sqlite3.Connection, reference: CallReference) -> SourceRecordRef
     if row["status"] == "deleted" or row["deleted_at"] is not None:
         return _hidden(reference)
 
-    # Same local revocation/ownership predicate as SourceReadAccess.memories,
-    # evaluated BEFORE freshness (which can read support text), in this snapshot.
+    # Same local revocation/ownership predicate as SourceReadAccess.memories.
     # Its public methods open their own connections, so cannot be used here.
     access = db.execute(
         "SELECT EXISTS (SELECT 1 FROM governed_memory_evidence "
@@ -121,8 +120,8 @@ def resolve_call_references(database_path: Path, event: CallEvent) -> list[Sourc
 
     Local-owner only: event host attribution is NOT authorization. Explicit local
     source revocations deny access; absent grants retain legacy local semantics.
-    A memory needs at least one accessible active citation. No proof preserves
-    shared freshness compatibility, not a claim of verified historical freshness.
+    A memory needs at least one accessible active citation. Evidence freshness
+    proofs are retired and do not affect availability.
 
     Any read/parse/budget failure raises a fixed whole-request error, never a
     partial result or per-item deletion. The route owner must map this separately

memhub/apps/core/src/one_memory/cli.py

@@ -1,6 +1,5 @@
 import os
 import signal
-import socket
 import sys
 
 # A handed-off capture ends itself: the hook that gave it the prompt has
@@ -29,13 +28,57 @@ def _end_by(seconds: str | None) -> None:
 if __name__ == "__main__" and sys.argv[1:2] == ["capture"]:
     _end_by(os.environ.get("ONE_MEMORY_CAPTURE_DEADLINE_S"))
 
+import contextlib  # noqa: E402
+import errno  # noqa: E402
 import json  # noqa: E402
-from collections.abc import Sequence  # noqa: E402
+import re  # noqa: E402
+import time  # noqa: E402
+from collections.abc import Iterator, Sequence  # noqa: E402
+from pathlib import Path  # noqa: E402
 from typing import TextIO  # noqa: E402
 
 from one_memory.config import load_settings  # noqa: E402
 from one_memory.runtime_client import RuntimeStatus, inspect_runtime  # noqa: E402
 
+# The startup dialog can only act on the name it is given: running out of disk
+# and a damaged backup are different next steps. These are the names that reach
+# it.
+_SAFE_MIGRATION_CODE = re.compile(r"^[a-z][a-z0-9_]{0,95}$")
+_OUT_OF_SPACE = frozenset({errno.ENOSPC, getattr(errno, "EDQUOT", errno.ENOSPC)})
+
+
+def _exception_chain(error: BaseException) -> Iterator[BaseException]:
+    seen: set[int] = set()
+    current: BaseException | None = error
+    while current is not None and id(current) not in seen:
+        seen.add(id(current))
+        yield current
+        current = current.__cause__ or current.__context__
+
+
+def migration_failure_code(
+    error: BaseException, *, fallback: str = "sdk_migration_preflight_failed"
+) -> str:
+    """Name a migration failure; never guess a code from free text.
+
+    Errs toward the caller's generic code: an exception this does not recognize
+    keeps its message out of the document Desktop reads.
+    """
+    chain = list(_exception_chain(error))
+    for item in chain:
+        if isinstance(item, OSError) and item.errno in _OUT_OF_SPACE:
+            return "sdk_migration_disk_space_insufficient"
+    for item in chain:
+        code = getattr(item, "code", "")
+        # `sdk_data_plane_write_job_input_missing:<job_id>`: the name is the
+        # code; the id is for the log, not for the dialog.
+        code = code.split(":", 1)[0] if isinstance(code, str) else code
+        if not isinstance(code, str) or not _SAFE_MIGRATION_CODE.match(code):
+            continue
+        if code.startswith(("sdk_data_plane_", "sdk_migration_")):
+            return code
+    return fallback
+
 
 def main() -> None:
     if sys.argv[1:] == ["--keychain-read"]:
@@ -65,37 +108,27 @@ def run(arguments: Sequence[str], *, output: TextIO | None = None) -> int:
     if not arguments or list(arguments) in (
         ["serve"],
         ["serve", "--maintenance"],
-        ["serve", "--reader"],
     ):
-        serve(
-            maintenance=list(arguments) == ["serve", "--maintenance"],
-            reader=list(arguments) == ["serve", "--reader"],
-        )
+        serve(maintenance=list(arguments) == ["serve", "--maintenance"])
         return 0
     command, *options = arguments
     if command == "restore":
         return restore(options, stream)
-    if command == "boundary" and not options:
-        from one_memory.workbuddy_boundary import write_hook
-
-        return write_hook(stream, sys.stdin)
-    if command == "boundary" and options == ["--peek"]:
-        from one_memory.workbuddy_boundary import write_peek
-
-        return write_peek(stream, sys.stdin)
-    if command == "boundary" and len(options) == 2 and options[0] == "--ack":
-        from one_memory.workbuddy_boundary import run_confirm
-
-        return run_confirm(options[1])
+    if command == "sdk-migrate":
+        return sdk_migrate(options, stream)
+    if command == "sdk-migration-status":
+        return sdk_migration_status(options, stream)
     if command == "capture" and len(options) == 1:
         from one_memory.live_capture import capture_stdio
 
         return capture_stdio(options[0], sys.stdin, stream)
     if command not in {"status", "doctor"} or options not in ([], ["--json"]):
         stream.write(
-            "Usage: one-memory [serve [--maintenance|--reader]|status [--json]|doctor [--json]"
+            "Usage: one-memory [serve [--maintenance]|status [--json]|doctor [--json]"
             "|restore --source <managed-backup> --yes [--json]"
-            "|boundary [--peek|--ack TOKEN]|capture SOURCE]\n"
+            "|sdk-migrate --runtime-build <build> --yes [--json]"
+            "|sdk-migration-status [--json]"
+            "|capture SOURCE]\n"
         )
         return 2
 
@@ -139,8 +172,6 @@ def restore(options: Sequence[str], stream: TextIO) -> int:
         return 2
 
     settings = load_settings()
-    from one_memory.managed_restore import RestoreRejected, restore_managed_backup
-
     status = inspect_runtime(settings.data_dir)
     if status.state != "stopped":
         document = {
@@ -160,8 +191,48 @@ def restore(options: Sequence[str], stream: TextIO) -> int:
         }
         _write_restore(stream, as_json, document, "预览通过；加 --yes 才会覆盖当前数据库。")
         return 4
+    from one_memory.managed_restore import RestoreRejected, restore_managed_backup
+    from one_memory.sdk_migration_bundle import (
+        MigrationBundleRejected,
+        restore_sdk_migration_bundle,
+    )
+
+    is_sdk_bundle = source.endswith(".sdk-bundle")
+    if is_sdk_bundle:
+        try:
+            sdk_result = restore_sdk_migration_bundle(
+                data_dir=settings.data_dir,
+                source=source,
+                runtime_stopped=True,
+            )
+        except MigrationBundleRejected as error:
+            document = {
+                "schema_version": 1,
+                "state": "failed",
+                "code": error.code,
+            }
+            _write_restore(stream, as_json, document, f"恢复失败：{error.code}")
+            return 1
+        document = {
+            "schema_version": 1,
+            "state": "restored",
+            "bundle_id": sdk_result.bundle_id,
+            "restored_files": sdk_result.restored_files,
+            "restored_bytes": sdk_result.restored_bytes,
+            "previous_database_path": str(sdk_result.previous_database_path),
+            "previous_sdk_root": (
+                str(sdk_result.previous_sdk_root) if sdk_result.previous_sdk_root else None
+            ),
+        }
+        _write_restore(
+            stream,
+            as_json,
+            document,
+            f"已恢复完整迁移备份：{sdk_result.bundle_id}。",
+        )
+        return 0
     try:
-        result = restore_managed_backup(data_dir=settings.data_dir, source=source)
+        managed_result = restore_managed_backup(data_dir=settings.data_dir, source=source)
     except RestoreRejected as error:
         document = {
             "schema_version": 1,
@@ -173,15 +244,15 @@ def restore(options: Sequence[str], stream: TextIO) -> int:
     document = {
         "schema_version": 1,
         "state": "restored",
-        "restored_bytes": result.restored_bytes,
-        "previous_backup_path": str(result.previous_backup_path),
-        "source_schema_version": result.source_schema_version,
+        "restored_bytes": managed_result.restored_bytes,
+        "previous_backup_path": str(managed_result.previous_backup_path),
+        "source_schema_version": managed_result.source_schema_version,
     }
     _write_restore(
         stream,
         as_json,
         document,
-        f"已恢复：{result.previous_backup_path} 为保护性备份。",
+        f"已恢复：{managed_result.previous_backup_path} 为保护性备份。",
     )
     return 0
 
@@ -198,6 +269,330 @@ def _write_restore(
         stream.write(f"{text}\n")
 
 
+def sdk_migrate(options: Sequence[str], stream: TextIO) -> int:
+    """Bring a stopped home to SDK authority in one resumable command.
+
+    Backs up the home, makes queue work independent of the legacy tables,
+    commits SDK authority and drops those tables. The SDK already holds every
+    memory and raw turn, so nothing is copied. With `--json`, each step is one
+    progress line and the last line is the result.
+    """
+    runtime_build: str | None = None
+    confirmed = False
+    as_json = False
+    index = 0
+    while index < len(options):
+        option = options[index]
+        if option == "--runtime-build" and index + 1 < len(options):
+            runtime_build = options[index + 1]
+            index += 2
+            continue
+        if option == "--yes":
+            confirmed = True
+            index += 1
+            continue
+        if option == "--json":
+            as_json = True
+            index += 1
+            continue
+        stream.write(f"one-memory: 参数无效：{option}\n")
+        return 2
+    if not runtime_build:
+        stream.write("one-memory: sdk-migrate 需要 --runtime-build <build>\n")
+        return 2
+
+    from one_memory.sdk_migration_log import authority_snapshot, write_migration_log
+
+    settings = load_settings()
+    database_path = settings.data_dir / "one-memory.sqlite3"
+    started = time.monotonic()
+    write_migration_log(
+        settings.data_dir,
+        writer="core-sdk-migrate",
+        event="migrate.invoked",
+        outcome="started",
+        details={
+            "runtime_build": runtime_build,
+            "confirmed": confirmed,
+            **authority_snapshot(database_path),
+        },
+    )
+    status = inspect_runtime(settings.data_dir)
+    if status.state != "stopped":
+        document = {
+            "schema_version": 1,
+            "state": "blocked",
+            "code": "sdk_migration_runtime_running",
+            "runtime_state": status.state,
+        }
+        write_migration_log(
+            settings.data_dir,
+            writer="core-sdk-migrate",
+            event="migrate.blocked",
+            outcome="blocked",
+            code="sdk_migration_runtime_running",
+            details={"runtime_state": status.state},
+        )
+        _write_restore(stream, as_json, document, "Runtime 仍在运行；不能迁移。")
+        return 4
+    if not confirmed:
+        document = {"schema_version": 1, "state": "preview", "requires_confirmation": True}
+        _write_restore(stream, as_json, document, "预览通过；加 --yes 后执行迁移。")
+        return 4
+
+    from one_memory.hy_runtime_config import (
+        HY_MEMORY_NAMESPACE,
+        HY_MEMORY_VERSION,
+        configure_hy_runtime_environment,
+    )
+
+    configure_hy_runtime_environment(settings.data_dir)
+    from one_memory.sdk_migration_runner import run_startup_migration
+
+    step_names = {
+        "bundle": "正在备份记忆数据……",
+        "prepare": "正在整理待处理的写入任务……",
+        "cutover": "正在切换数据源……",
+        "vectors": "正在接回旧版本的向量数据……",
+        "verify": "正在用新版本核对记忆能否读回……",
+        "cleanup": "正在删除旧表……",
+    }
+
+    # Everything before the first progress step (authority read, profile
+    # read, resumable identity, legacy id scan, model-profile check) is the
+    # preflight. A failure is logged with the phase it happened in.
+    phase = {"name": "preflight", "started": time.monotonic()}
+
+    def progress(step: str) -> None:
+        now = time.monotonic()
+        write_migration_log(
+            settings.data_dir,
+            writer="core-sdk-migrate",
+            event="phase.finished",
+            outcome="succeeded",
+            details={"phase": phase["name"], "duration_ms": (now - phase["started"]) * 1000},
+        )
+        phase["name"], phase["started"] = step, now
+        write_migration_log(
+            settings.data_dir,
+            writer="core-sdk-migrate",
+            event="phase.started",
+            outcome="started",
+            details={"phase": step},
+        )
+        if as_json:
+            stream.write(json.dumps({"schema_version": 1, "state": "running", "step": step}) + "\n")
+        else:
+            stream.write(f"{step_names.get(step, step)}\n")
+        stream.flush()
+
+    try:
+        with _migration_lock(settings.data_dir):
+            result = run_startup_migration(
+                data_dir=settings.data_dir,
+                runtime_build=runtime_build,
+                sdk_version=HY_MEMORY_VERSION,
+                namespace=HY_MEMORY_NAMESPACE,
+                progress=progress,
+            )
+    except Exception as error:
+        from one_memory.sdk_migration_verify import MemoryReadbackFailed
+
+        code = migration_failure_code(error)
+        failed: dict[str, object] = {"schema_version": 1, "state": "failed", "code": code}
+        if isinstance(error, MemoryReadbackFailed):
+            failed["readback"] = error.report.as_document()
+        write_migration_log(
+            settings.data_dir,
+            writer="core-sdk-migrate",
+            event="migrate.failed",
+            outcome="failed",
+            code=code,
+            error=error,
+            details={
+                "phase": phase["name"],
+                "phase_duration_ms": (time.monotonic() - phase["started"]) * 1000,
+                "duration_ms": (time.monotonic() - started) * 1000,
+                # A generic fallback code means the cause is only in `error`.
+                "code_is_fallback": code == "sdk_migration_preflight_failed"
+                and not _names_code(error, code),
+                **({"readback": failed["readback"]} if "readback" in failed else {}),
+                **authority_snapshot(database_path),
+            },
+        )
+        _write_restore(stream, as_json, failed, f"迁移未完成：{code}")
+        return 1
+    document = result.as_document()
+    write_migration_log(
+        settings.data_dir,
+        writer="core-sdk-migrate",
+        event="migrate.finished",
+        outcome="succeeded",
+        migration_id=result.migration_id,
+        details={
+            "state": result.state,
+            "last_phase": phase["name"],
+            "duration_ms": (time.monotonic() - started) * 1000,
+            "result": document,
+            **authority_snapshot(database_path),
+        },
+    )
+    messages = {
+        "not_required": "不需要迁移。",
+        "complete": "迁移已完成；遗留的旧表或向量已处理。",
+        "cutover": "迁移完成：记忆数据已以 SDK 为准。",
+    }
+    _write_restore(stream, as_json, document, messages[result.state])
+    return 0
+
+
+@contextlib.contextmanager
+def _migration_lock(data_dir: Path) -> Iterator[None]:
+    """One `sdk-migrate` per home at a time.
+
+    Desktop, CLI install/upgrade and the Runtime service each migrate before
+    serving, and a login-started service can be migrating when the person
+    opens the app. The second waits here and then finds the work done (or
+    resumes it); two runs never interleave.
+    """
+    from one_memory.sdk_migration_log import write_migration_log
+
+    data_dir.mkdir(parents=True, exist_ok=True, mode=0o700)
+    descriptor = os.open(data_dir / "sdk-migration.lock", os.O_RDWR | os.O_CREAT, 0o600)
+    try:
+        if os.name == "nt":
+            import msvcrt
+
+            def acquire(blocking: bool) -> None:
+                while True:
+                    try:
+                        os.lseek(descriptor, 0, os.SEEK_SET)
+                        msvcrt.locking(descriptor, msvcrt.LK_NBLCK, 1)
+                        return
+                    except OSError:
+                        if not blocking:
+                            raise
+                        time.sleep(0.5)
+
+            def release() -> None:
+                os.lseek(descriptor, 0, os.SEEK_SET)
+                msvcrt.locking(descriptor, msvcrt.LK_UNLCK, 1)
+        else:
+            import fcntl
+
+            def acquire(blocking: bool) -> None:
+                fcntl.flock(descriptor, fcntl.LOCK_EX | (0 if blocking else fcntl.LOCK_NB))
+
+            def release() -> None:
+                fcntl.flock(descriptor, fcntl.LOCK_UN)
+
+        try:
+            acquire(False)
+        except OSError:
+            write_migration_log(
+                data_dir,
+                writer="core-sdk-migrate",
+                event="migrate.waiting_for_lock",
+                outcome="started",
+            )
+            waited = time.monotonic()
+            acquire(True)
+            write_migration_log(
+                data_dir,
+                writer="core-sdk-migrate",
+                event="migrate.lock_acquired",
+                outcome="succeeded",
+                details={"waited_ms": (time.monotonic() - waited) * 1000},
+            )
+        try:
+            yield
+        finally:
+            release()
+    finally:
+        os.close(descriptor)
+
+
+def _names_code(error: BaseException, code: str) -> bool:
+    return any(
+        str(getattr(item, "code", "")).split(":", 1)[0] == code for item in _exception_chain(error)
+    )
+
+
+def sdk_migration_status(options: Sequence[str], stream: TextIO) -> int:
+    """Read-only probe: does this home need `sdk-migrate`?"""
+    try:
+        return _sdk_migration_status(options, stream)
+    except Exception as error:
+        from one_memory.sdk_migration_log import write_migration_log
+
+        # The orchestrator only sees a non-zero exit and reports
+        # `sdk_migration_status_unavailable`; the cause is recorded here.
+        write_migration_log(
+            load_settings().data_dir,
+            writer="core-sdk-migration-status",
+            event="status.failed",
+            outcome="failed",
+            code="sdk_migration_status_unavailable",
+            error=error,
+        )
+        raise
+
+
+def _sdk_migration_status(options: Sequence[str], stream: TextIO) -> int:
+    if list(options) not in ([], ["--json"]):
+        stream.write("one-memory: sdk-migration-status 只接受 --json\n")
+        return 2
+    as_json = "--json" in options
+    settings = load_settings()
+    database_path = settings.data_dir / "one-memory.sqlite3"
+    if not database_path.is_file():
+        document: dict[str, object] = {
+            "schema_version": 1,
+            "authority": "sdk",
+            "state": "not_required",
+        }
+    else:
+        from one_memory.hy_runtime_config import HY_MEMORY_NAMESPACE
+        from one_memory.sdk_data_plane_migration import (
+            MemoryAuthority,
+            SdkDataPlaneMigrationStore,
+        )
+        from one_memory.sdk_migration_runner import abandoned_staging_present
+        from one_memory.sdk_migration_verify import read_active_profile
+        from one_memory.sdk_vector_reattach import legacy_vector_collections
+        from one_memory.target_schema import legacy_tables_present
+
+        authority = SdkDataPlaneMigrationStore(database_path).authority()
+        if authority is MemoryAuthority.SDK:
+            profile = read_active_profile(database_path)
+            leftovers = bool(
+                legacy_tables_present(database_path)
+                or abandoned_staging_present(
+                    data_dir=settings.data_dir,
+                    namespace=HY_MEMORY_NAMESPACE,
+                )
+                or (profile is not None and legacy_vector_collections(settings.data_dir, profile))
+            )
+            state = "required" if leftovers else "not_required"
+        else:
+            state = "required"
+        document = {"schema_version": 1, "authority": authority.value, "state": state}
+    from one_memory.sdk_migration_log import write_migration_log
+
+    write_migration_log(
+        settings.data_dir,
+        writer="core-sdk-migration-status",
+        event="status.probed",
+        outcome="succeeded",
+        details={"authority": document["authority"], "state": document["state"]},
+    )
+    if as_json:
+        stream.write(f"{json.dumps(document, ensure_ascii=False)}\n")
+    else:
+        stream.write(f"SDK migration: {document['state']} (authority={document['authority']})\n")
+    return 0
+
+
 def _status_text(command: str, status: RuntimeStatus) -> str:
     if status.state == "running":
         location = f"{status.host}:{status.port}"
@@ -210,30 +605,58 @@ def _status_text(command: str, status: RuntimeStatus) -> str:
     return f"MemHub Runtime 状态不可验证：{status.code}。"
 
 
-def _reserve_reader_port(host: str, port: int) -> int:
-    """Resolve the port the Reader will listen on, including the ephemeral case.
+#: Exit status of a serving Core refused because the home is not on SDK
+#: authority (`EX_CONFIG`). The Runtime maps it to `sdk_migration_required`.
+SDK_MIGRATION_REQUIRED_EXIT = 78
 
-    The supervisor asks for an ephemeral port (`ONE_MEMORY_READER_PORT=0`) and
-    then reads the real one back from stderr. Letting uvicorn bind port 0
-    itself would give a port nobody can report, so claim a free port here by
-    binding and immediately releasing it, then serve on that exact port.
+
+def _refuse_unmigrated_home(data_dir: Path) -> None:
+    """Exit before binding when an existing home has not reached SDK authority.
+
+    A brand-new home has no database yet and is created on SDK authority by
+    startup. Anything else that is not SDK is an upgrade that did not finish,
+    and is never served: the migration must run first.
     """
-    if port != 0:
-        return port
-    probe = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
+    from one_memory.sdk_data_plane_migration import MemoryAuthority, SdkDataPlaneMigrationStore
+    from one_memory.sdk_migration_log import authority_snapshot, write_migration_log
+
+    database_path = data_dir / "one-memory.sqlite3"
+    if not database_path.is_file():
+        return
     try:
-        probe.bind((host, 0))
-        return int(probe.getsockname()[1])
-    finally:
-        probe.close()
+        authority = SdkDataPlaneMigrationStore(database_path).authority()
+    except Exception as error:  # noqa: BLE001 - an unreadable home is not served either
+        write_migration_log(
+            data_dir,
+            writer="core-startup",
+            event="core.refused_legacy",
+            outcome="refused",
+            code="sdk_migration_required",
+            error=error,
+        )
+        print("sdk_migration_required", file=sys.stderr, flush=True)
+        raise SystemExit(SDK_MIGRATION_REQUIRED_EXIT) from None
+    if authority is MemoryAuthority.SDK:
+        return
+    write_migration_log(
+        data_dir,
+        writer="core-startup",
+        event="core.refused_legacy",
+        outcome="refused",
+        code="sdk_migration_required",
+        details={"stage": "serve_entry", **authority_snapshot(database_path)},
+    )
+    print("sdk_migration_required", file=sys.stderr, flush=True)
+    raise SystemExit(SDK_MIGRATION_REQUIRED_EXIT)
 
 
-def serve(*, maintenance: bool = False, reader: bool = False) -> None:
+def serve(*, maintenance: bool = False) -> None:
     import uvicorn
 
     from one_memory.diagnostic_log import configure_diagnostics, diagnostic_event
     from one_memory.hy_runtime_config import (
         apply_diagnostic_log_level,
+        configure_hy_runtime_environment,
         diagnostic_log_level,
     )
     from one_memory.log_file import start_logging_to_file
@@ -241,34 +664,13 @@ def serve(*, maintenance: bool = False, reader: bool = False) -> None:
     from one_memory.runtime import CoreRuntime, parent_pid
 
     settings = load_settings()
-    if reader:
-        settings = settings.model_copy(
-            update={
-                "port": int(os.environ.get("ONE_MEMORY_READER_PORT", "0") or "0"),
-                "api_token": settings.api_token,
-            }
-        )
-        from one_memory.reader_app import ReaderSettings, create_reader_app
-
-        core_port = int(os.environ.get("ONE_MEMORY_CORE_PORT", "8765"))
-        # The supervisor learns the Reader's port by watching stderr for
-        # `reader_port:<n>`. With `ONE_MEMORY_READER_PORT=0` uvicorn would bind
-        # an OS-chosen port that nothing reports back, so claim the port up
-        # front and serve on that exact one.
-        port = _reserve_reader_port(settings.host, settings.port)
-        reader_settings = ReaderSettings(
-            data_dir=settings.data_dir,
-            host=settings.host,
-            port=port,
-            api_token=settings.api_token,
-            core_port=core_port,
-            core_api_token=os.environ.get("ONE_MEMORY_CORE_API_TOKEN", ""),
-        )
-        application = create_reader_app(reader_settings)
-        print(f"reader_port:{port}", file=sys.stderr, flush=True)
-        uvicorn.run(application, host=settings.host, port=port, reload=False)
-        return
-
+    if not maintenance:
+        _refuse_unmigrated_home(settings.data_dir)
+    # HY resolves some trace paths at import time and its pipeline path when
+    # SharedRuntime starts. Bind both to the MemHub root before importing the
+    # application graph; otherwise HY falls back to ~/.hy_memory while the
+    # desktop Debug panel watches the managed data directory.
+    configure_hy_runtime_environment(settings.data_dir)
     from one_memory.api import create_app
 
     start_logging_to_file(settings.data_dir)
@@ -297,9 +699,21 @@ def serve(*, maintenance: bool = False, reader: bool = False) -> None:
     )
     if maintenance:
         with CoreRuntime(settings, publish_receipt=False):
-            uvicorn.run(application, host=settings.host, port=settings.port, reload=False)
+            uvicorn.run(
+                application,
+                host=settings.host,
+                port=settings.port,
+                reload=False,
+                access_log=False,
+            )
     else:
-        uvicorn.run(application, host=settings.host, port=settings.port, reload=False)
+        uvicorn.run(
+            application,
+            host=settings.host,
+            port=settings.port,
+            reload=False,
+            access_log=False,
+        )
 
 
 if __name__ == "__main__":

memhub/apps/core/src/one_memory/config.py

@@ -23,10 +23,6 @@ class Settings(BaseSettings):
     live_sync_enabled: bool = True
     automatic_memory_processing: bool = True
     imports_enabled: bool = True
-    # Experimental and unreleased: ownership/error shutdown still requires acceptance.
-    # Resume only explicitly initialized generations; never migrate at startup.
-    retrieval_index_enabled: bool = False
-    retrieval_minimum_free_bytes: int = Field(default=256 * 1024 * 1024, ge=0)
     # Bounded metadata only: query, original text and answers are never stored.
     call_event_retention_days: int | None = Field(default=30, ge=1, le=365)
     call_event_max_events: int | None = Field(default=10_000, ge=1, le=100_000)

memhub/apps/core/src/one_memory/context_models.py

@@ -47,6 +47,19 @@ class ContextSearchRequest(BaseModel):
         return self
 
 
+class SdkContextSearchRequest(ContextSearchRequest):
+    """`POST /api/v2/context/search`: the three SDK recall lanes are set apart.
+
+    `limit` is the normal lane's top-k and the cap on returned items;
+    `schema_limit` and `intention_limit` are the SDK's schema (L6) and
+    proactive intention (L7) lanes. A caller's values are passed through.
+    """
+
+    limit: int = Field(default=10, ge=1, le=20, strict=True)
+    schema_limit: int = Field(default=3, ge=0, le=20, strict=True)
+    intention_limit: int = Field(default=1, ge=0, le=20, strict=True)
+
+
 class ContextMessage(BaseModel):
     model_config = ConfigDict(frozen=True, extra="forbid")
 
@@ -89,6 +102,51 @@ class MemoryContextItem(BaseModel):
 ContextItem = Annotated[RawContextItem | MemoryContextItem, Field(discriminator="kind")]
 
 
+class SdkRawContextItem(BaseModel):
+    model_config = ConfigDict(frozen=True, extra="forbid")
+
+    kind: Literal["raw"] = "raw"
+    raw_id: str = Field(min_length=1, max_length=512)
+    content: str = Field(max_length=20000)
+    source: str = Field(min_length=1, max_length=128)
+    session_id: str = Field(min_length=1, max_length=512)
+    memory_at: datetime | None = None
+    score: float = Field(ge=0, le=1)
+    truncated: bool = False
+
+
+class SdkMemoryContextItem(BaseModel):
+    model_config = ConfigDict(frozen=True, extra="forbid")
+
+    kind: Literal["memory"] = "memory"
+    memory_id: str = Field(min_length=1, max_length=512)
+    content: str = Field(max_length=20000)
+    layer: str = Field(max_length=64)
+    status: str = Field(max_length=32)
+    source: str | None = Field(default=None, max_length=128)
+    updated_at: datetime | None = None
+    score: float = Field(ge=0, le=1)
+    truncated: bool = False
+
+
+SdkContextItem = Annotated[
+    SdkRawContextItem | SdkMemoryContextItem,
+    Field(discriminator="kind"),
+]
+
+
+class SdkContextSearchResponse(BaseModel):
+    model_config = ConfigDict(frozen=True, extra="forbid")
+
+    schema_version: Literal[2] = 2
+    request_id: str = Field(min_length=1, max_length=64)
+    state: Literal["grounded", "empty", "partial", "unavailable"]
+    items: tuple[SdkContextItem, ...] = Field(max_length=20)
+    used_characters: int = Field(ge=0, le=20000)
+    truncated: bool
+    total_ms: float = Field(ge=0)
+
+
 class ContextLaneResult(BaseModel):
     """Internal bounded adapter result; the aggregator applies shared budgets."""