test: stabilize reembed merge fixture timestamps

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

CHANGELOG.md

@@ -4,7 +4,222 @@ Hy Memory and MemHub are versioned and released independently.
 
 ## Unreleased
 
-- Hy Memory: LLM prompts now ship in 11 languages: `en`, `zh-Hans`,
+## Hy Memory 2.0.14 — 2026-11-04
+
+- `search()` / `async_search()` take an optional `statuses` for explicit
+  L1_RAW search (`layers=["l1_raw"]`, or any search in lite mode), e.g.
+  `statuses=["active", "shadow"]`, so raw turns a pro extraction already
+  shadowed can still be searched. Default stays active-only. Raw hits now
+  report their real `status`. Passing `statuses` to a non-raw search or to
+  `scene="all"` raises `ValueError` instead of being ignored.
+
+## Hy Memory 2.0.13 — 2026-11-02
+
+- A model failure during a write now reports failure and stores
+  nothing. **Behaviour change for direct SDK users:** writes that used to
+  return `success: true` in a degraded state now return `success: false`;
+  retry them with a new `request_id` once the model is back.
+  - Reconcile (pro / ultra `add` and `add_extracted`): when the reconcile model
+    call fails, returns HTTP 200 with empty content, or returns a reply that
+    cannot be parsed, or reconcile raises before anything is stored, the write
+    used to fall back to adding every extracted memory as-is (no dedup or
+    evolution) and report success. That fallback is removed, with its
+    `degraded` / `degraded_reason` result fields. The write now returns
+    `success: false`, `error_code: 502`,
+    `agent_error_code: "RECONCILE_FAILED"`, and the cause in the new
+    `reconcile_error_code` (`LLM_UNAVAILABLE`, `EMPTY_RESPONSE`,
+    `JSON_PARSE_FAILED`, `RECONCILE_EXCEPTION`). None of the new memories are
+    stored, the episode counter does not advance, and `add` rolls back its
+    raw turn the same way as an extraction failure
+    (`l1_rollback.retry_safe: true`). An empty 200 reply was previously
+    counted as "no changes" and reported success with 0 memories; only a
+    literal `[]` reply still means that. `RECONCILE_ENABLED=false` is a
+    configuration choice and still writes directly.
+  - Working / coding path: an extraction model failure used to return
+    success with 0 operations. It now returns `success: false` with
+    `agent_error_code` `LLM_ERROR`, `EMPTY_RESPONSE` or `JSON_PARSE_FAILED`.
+    A model that answers with nothing worth remembering is still a success.
+    An embedding failure used to store the experience or fact without a
+    vector, where search never finds it, and report success; it now returns
+    `EMBEDDING_FAILED` and the node is not stored. A fact embedding is checked
+    before any older fact is superseded. A failed write no longer appends its
+    turns to the recent trace and records no `chain_rounds`.
+    With `MEMORY_CODING_VERBATIM_FALLBACK_ENABLED` turned on, extraction
+    failures keep the verbatim fallback.
+  - Working / coding reconcile: when the experience reconcile or the fact
+    reconcile model call fails, returns empty content, or returns a reply that
+    is not a JSON object with an `ops` list, the write returns
+    `success: false`, `agent_error_code: "RECONCILE_FAILED"` and the cause in
+    `reconcile_error_code` (`LLM_UNAVAILABLE`, `EMPTY_RESPONSE`,
+    `JSON_PARSE_FAILED`), the same as chat. Before, experience reconcile fell
+    back to adding every draft, and fact reconcile inserted the new fact
+    without superseding older ones. Both model decisions now run before
+    anything is stored, so a failure in either leaves no experience or fact
+    from the write and supersedes no older fact. An experience reply of
+    `{"ops": []}` is a valid "no changes" decision: the write succeeds and no
+    experience is stored. A non-empty `ops` list with no recognizable op is a
+    parse failure. A fact reply of `{"ops": []}` inserts the new fact without
+    superseding anything. Fact reconcile still makes no model call when there
+    are no candidates.
+
+## Hy Memory 2.0.12 — 2026-11-02
+
+- Intention dedup is now configurable per client
+  (`MemoryConfig.recall.intention_dedup_enabled`, default `true`;
+  `recall.intention_dedup_threshold`, default `MEMORY_DEDUP_THRESHOLD` or
+  `0.95`). Env defaults: `MEMORY_INTENTION_DEDUP_ENABLED`,
+  `MEMORY_INTENTION_DEDUP_THRESHOLD`. When on, behaviour is unchanged
+  (duplicates found at read time are still deleted); when off, no intention
+  dedup runs, at read time or within a write batch, and nothing is hidden,
+  dropped or deleted. The threshold applies to read-time dedup only. Refs #241.
+
+- MemHub pins `hy-memory==2.0.12` and exposes that intention dedup switch in
+  its memory-features setting (`GET`/`PUT /api/v1/settings/memory-features`,
+  `memhub settings features`): the feature `intention_dedup` (default on) and
+  the numeric `intention_dedup_threshold` (default 0.95, accepted 0.8–1.0,
+  anything else is 422 or a CLI usage error). Unset, both keep the SDK
+  default, so nothing changes for the App; a change rebuilds the SDK clients
+  like the other feature switches. The API answer gains `parameters`, and
+  `pipeline.features` can now carry the threshold as a number. Refs #241.
+
+## MemHub 1.0.6 — 2026-11-04
+
+Build 41, on `hy-memory==2.0.14`. Linux x64/arm64 Runtime and macOS arm64
+App and Runtime.
+
+- MemHub App now exposes the complete memory-mode lifecycle. New installs
+  explicitly choose lite or pro during onboarding; pro completes only after a
+  generation model is active, while ultra remains an advanced Settings choice.
+  Settings shows mode effects, graph backfill, the default 03:00 evolve
+  schedule and manual evolve. The memory page shows original conversations in
+  lite and advanced memories in pro/ultra. Existing installs remain pro unless
+  the user changes them, and embedding maintenance blocks mode/evolve changes.
+- MemHub pins `hy-memory==2.0.14`. Lite search is plain RAG over raw: the
+  App's lite search, CLI context search, `/api/v1/recall` and the Host Bridge
+  (`MemHub_recall`, context search) return every vector hit above the floor,
+  ranked by score, over active and shadow raws, so history pro already
+  processed is still found after switching to lite. The turn view no longer
+  drops a hit whose turns do not literally contain the query; it shows the
+  hit's closest turn instead. Pro and ultra raw search stays active-only.
+  Fixes every raw search failing in packaged builds since #316, which passed
+  `statuses` to an SDK (2.0.13) that did not accept it. The lite raw-turn
+  page also stops re-listing the whole raw layer on each poll when a live
+  session only adds new raws.
+- MemHub Core no longer stalls writes or freezes the App for tens of seconds
+  on a machine with a long live-sync history. Finished live-sync import jobs
+  are pruned to the newest 20 per source (at startup, in bounded batches, and
+  every 10 minutes); history imports and every unfinished job are kept. Job
+  lookups are filtered in SQL with new indexes (schema migration 63) instead
+  of reading the whole table. The durable write queue runs its claims,
+  settles and lease renewals on its own threads, so import work can no longer
+  starve a lease. Import abandon, resume and enqueue, and the file watcher's
+  path attribution, no longer touch the database or the disk on the event
+  loop, and the WAL cadence checkpoint runs on its own thread instead of on
+  the writer's. The write drain now restarts itself after an unexpected exit,
+  reports the failure with its stack, and shows `write_drain` /
+  `write_drain_error` in memory-processing and `memhub status`.
+- Model Center (#293, #295): Settings splits into 界面语言 / 记忆模式 /
+  模型配置 pages, with separate 记忆整理 (generation) and 记忆搜索
+  (embedding) lanes. Changing one lane sends only that lane's patch. An
+  embedding change shows the switch plan, confirmation, progress, cancel and
+  rollback, and the search model only changes after the rebuilt index is
+  verified. Model panels open inside the lane that launched them and close
+  only after Core confirms the profile is active (#310).
+- Lite keeps raw conversations (#297): lite raw writes are no longer stopped
+  by the "pause model sedimentation" switch, the memory page lists every
+  imported raw conversation by role (by turn since #316), and lite adds a
+  manual raw input (source `one-memory-manual`) that never calls a
+  generation model.
+- The home page follows the memory mode (#298): lite counts raw
+  conversations and previews the latest one; pro and ultra read memories.
+  Pro and ultra now require an active generation model, in both the mode
+  preview and the switch.
+- Onboarding (#304) asks for lite or pro and resumes after a restart (schema
+  migration 62); pro finishes only once a generation model is active.
+- Smaller App fixes: compact home status copy (#307), clearer mode-switch
+  effects (#312), Ultra topic nodes are hover-only (#315), and settings
+  controls use the content width (#317).
+- Interfaces in 11 languages: English, Simplified and Traditional Chinese,
+  Japanese, Spanish, German, Portuguese, French, Korean, Russian and
+  Indonesian. Every interface language, Simplified Chinese included, sets the
+  SDK prompt language (#270). **User-visible:** zh-Hans users now get Chinese
+  prompts and Chinese memory text for every conversation, English ones
+  included; the App sends the language it displays, also when it follows the
+  system. Only an unset language (CLI/API installs, `memhub settings language
+  system`) keeps the SDK's zh/en detection.
+- Memory modes: lite (no LLM, keeps raw conversations), pro (LLM extraction)
+  and ultra (pro plus the knowledge graph and a nightly evolve run). Set with
+  `GET`/`PUT /api/v1/settings/memory-mode` or `memhub settings mode`. Raw
+  conversations are now kept permanently. `POST /api/v2/evolve` and
+  `memhub evolve` run System 2 on demand.
+- Safe embedding-model switching: an embedding-space registry, a switch that
+  pauses writes, re-embeds every user's vectors and the graph, verifies and
+  commits atomically, and resumes after a crash or an App update. Every start
+  scans the vector store and merges data left in other spaces. When the
+  embedding service is unavailable, search returns `embedding_unavailable`.
+- Multi-user Runtime: memory APIs and the CLI take `user_id` (default
+  `local`); records are isolated per user; Hermes profiles can be connected as
+  separate users. The App keeps using `local`. Hardening (#280): read
+  responses echo `user_id`; deleting another user's memory, or one that does
+  not exist, is 404 `memory_not_found` (the App and `memhub memories delete`
+  treat it as already gone); Hermes never reads a `profiles/` directory, and
+  a root that is the `profiles` container or overlaps another user's grant is
+  refused (`hermes_root_is_profiles_container`,
+  `hermes_root_overlaps_other_user`).
+- Configurable SDK features through the CLI and API (`memhub settings
+  features`): graph rerank, episode recall, session episodes, episode
+  summaries, intention and few-shot, and the intention dedup switch with its
+  threshold (`intention_dedup`, `intention_dedup_threshold`, #277). Defaults
+  are unchanged.
+- Memory writes retry themselves (#278), each time under a new SDK request
+  id after checking whether the previous one landed; interrupted writes
+  re-run automatically. A model provider failure (401/403, 404, 408, 429,
+  5xx, timeout, unreachable) keeps the job pending in place without spending
+  a retry, and a per-profile circuit breaker paces the queue (5 s doubling to
+  180 s, one probe job at a time). Any other failure is retried after 30, 60
+  and 120 s, then `failed`. With `hy-memory==2.0.13` a model failure is no
+  longer a silent success, and a failed job's `error_code` names the SDK's
+  cause (`hy_sdk_reconcile_empty_response`, `hy_sdk_llm_error`, ...) rather
+  than `hy_sdk_write_failed`. **User-visible:** the manual 重新整理 button,
+  the "整理结果不确定" display and
+  `POST /api/v1/memory-processing/retry-unknown` are gone; a banner
+  ("模型配置有问题……记忆暂停处理，已有 N 条在排队") with a button to the model
+  settings shows while a model problem pauses processing, and clears on
+  recovery.
+- Queue, WAL and recall (#278): the WAL stays bounded (64 MiB journal limit,
+  idle `TRUNCATE` checkpoints); a disabled or revoked source's jobs are
+  `suspended` and resume when it is turned back on; SDK writes and recall
+  reads use separate thread pools, and recall has a total budget (504
+  `recall_timeout`, `broker_timeout` in clients) instead of starving behind
+  stuck writes.
+- One Runtime per data dir (#273). App quit asks the service manager at quit
+  time: an enabled background service is never stopped, a disabled one has
+  every Runtime of the data dir stopped (only after an authenticated identity
+  check), and an unknown state stops nothing. At start the App adopts a
+  Runtime of the same build, replaces an older one, and silently adopts a
+  newer one. The tray quit label follows the current state.
+- DeepSeek Harness: the app page's one switch installs and grants recall for
+  every detected profile, and keeps new profiles granted without a restart
+  (#230); versioned session files (`session.v3.jsonl.zstd`,
+  `session.v4.jsonl.zstd`) are imported, and v4 tool output goes through the
+  same clipping and scrubbing (#175).
+- The packaged Runtime accepts only a full 40-character commit, lowercased; a
+  malformed `ONE_MEMORY_COMMIT` fails the build (#235, #236).
+- Search and recall pass through the SDK's search parameters with server-side
+  score floors; the memory library filters by layer; `/api/v2/raw` returns
+  data again; v2 source and import routes; profile version history.
+- Upgrade fixes: migration no longer stops without a model profile (#234) or
+  on a pre-existing readback mismatch (#229, #240); source grants work after
+  the cutover (#233); reads use the active embedding (#242); the embedding
+  endpoint no longer follows the generation `base_url`.
+- Hermes import drops gateway notices and probes and unwraps relayed
+  messages; `memhub logs` no longer reports valid older records as damaged.
+
+## Hy Memory 2.0.11 — 2026-11-01
+
+- Published
+  [`hy-memory==2.0.11`](https://pypi.org/project/hy-memory/2.0.11/).
+- LLM prompts now ship in 11 languages: `en`, `zh-Hans`,
   `zh-Hant`, `ja`, `es`, `de`, `pt`, `fr`, `ko`, `ru` and `id`. They live in
   one registry, `hy_memory/prompts/`, with one module per language. Call
   sites use `get_prompt(name, language)`, so a new language only needs a new
@@ -17,7 +232,7 @@ Hy Memory and MemHub are versioned and released independently.
   (`prompts_zh.*_ZH`, `extractor.EXTRACT_SYSTEM_PROMPT`, ...) still import.
   The nine new languages are machine translations, and native-speaker review
   is recommended.
-- Hy Memory: new optional `language` to choose the prompt language
+- New optional `language` to choose the prompt language
   explicitly. Set it on `MemoryConfig.language` (env `MEMORY_LANGUAGE`) for
   a client default, or per call on `add` / `async_add`, `add_extracted`,
   `finalize_session`, `evolve` and `sweep`. A per-call value overrides the
@@ -30,11 +245,13 @@ Hy Memory and MemHub are versioned and released independently.
   Without a language, the existing zh/en auto-detection runs unchanged and
   memories keep the source language. `search` has no `language`: its judge
   and rewrite prompts are English-only and keep the query's language.
-- Hy Memory: the HTTP server accepts `language` on `/api/v1/add` and
+- The HTTP server accepts `language` on `/api/v1/add` and
   `/api/v1/add_extracted`.
 
 ## Hy Memory 2.0.10 — 2026-11-01
 
+- Published
+  [`hy-memory==2.0.10`](https://pypi.org/project/hy-memory/2.0.10/).
 - New `hy_memory.reembed` module for switching the embedding
   model. Writers must be paused for the whole run. Nothing is derived from
   the provider or endpoint: source and target are named explicitly, and the

README.md

@@ -33,6 +33,7 @@ English | [中文](README.zh.md)
 ## Latest News
 
 * *<mark>[new]</mark>* 🔥🔥🔥 **[2026-10]**: 🚀 **Open-sourced** quantized **FP8** (**[Hy-Memory-30B-A3B-FP8](https://huggingface.co/tencent/Hy-Memory-30B-A3B-FP8)**) and **GGUF** (**[Hy-Memory-30B-A3B-GGUF](https://huggingface.co/tencent/Hy-Memory-30B-A3B-GGUF)**) versions of **Hy-Memory-30B-A3B** on Hugging Face!
+* *<mark>[new]</mark>* 🔥🔥🔥 **[2026-11]**: 📦 **Released [MemHub v1.0.6](https://github.com/Tencent-Hunyuan/Hy-Memory/releases/tag/v1.0.6)** with interfaces in 11 languages, memory modes (lite / pro / ultra with nightly evolve), safe embedding-model switching, multi-user support for the CLI and API, memory writes that retry themselves and pause while the model provider is down, and more reliable upgrades, on **`hy-memory==2.0.14`**. See the release notes for details.
 * *<mark>[new]</mark>* 🔥🔥🔥 **[2026-10]**: 📦 **Released [MemHub v1.0.5](https://github.com/Tencent-Hunyuan/Hy-Memory/releases/tag/v1.0.5)** with Chinese, English and Spanish interfaces, one-time pairing codes for more custom Harnesses, and smoother browsing, search, startup and recovery, on **`hy-memory==2.0.8`**. See the release notes for details.
 * *<mark>[new]</mark>* 🔥🔥🔥 **[2026-10]**: 📦 **Released [MemHub v1.0.4](https://github.com/Tencent-Hunyuan/Hy-Memory/releases/tag/v1.0.4)** and **[memhub-cli 1.0.5](https://www.npmjs.com/package/memhub-cli/v/1.0.5)**, with a signed macOS desktop app and verified macOS/Linux Runtimes!
 * *<mark>[new]</mark>* 🔥🔥🔥 **[2026-10]**: 🚀 **Released** **Hy Memory 2.0 (`hy-memory==2.0.4`)** on [PyPI](https://pypi.org/project/hy-memory/2.0.4/) and open-sourced the **Hy-Memory** monorepo together with **[MemHub](memhub/README.md)**!

README.zh.md

@@ -33,6 +33,7 @@
 ## 最新动态
 
 * *<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-11]**: 📦 **正式发布 [MemHub v1.0.6](https://github.com/Tencent-Hunyuan/Hy-Memory/releases/tag/v1.0.6)**：界面支持 11 种语言，新增记忆模式（lite / pro / ultra，ultra 每晚自动整理），可安全切换嵌入模型，CLI 和 API 支持多用户，记忆写入自动重试、模型服务异常时暂停排队，升级更可靠；底层使用 **`hy-memory==2.0.14`**。详见发布说明。
 * *<mark>[new]</mark>* 🔥🔥🔥 **[2026-10]**: 📦 **正式发布 [MemHub v1.0.5](https://github.com/Tencent-Hunyuan/Hy-Memory/releases/tag/v1.0.5)**：支持中文、英文和西班牙语界面，可通过一次性配对码连接更多自定义 Harness，并优化了记忆浏览、搜索、启动和异常恢复；底层使用 **`hy-memory==2.0.8`**。详见发布说明。
 * *<mark>[new]</mark>* 🔥🔥🔥 **[2026-10]**: 📦 **正式发布 [MemHub v1.0.4](https://github.com/Tencent-Hunyuan/Hy-Memory/releases/tag/v1.0.4)** 与 **[memhub-cli 1.0.5](https://www.npmjs.com/package/memhub-cli/v/1.0.5)**，提供已签名的 macOS 桌面应用及经过验证的 macOS/Linux Runtime！
 * *<mark>[new]</mark>* 🔥🔥🔥 **[2026-10]**: 🚀 **正式发布** **Hy Memory 2.0 (`hy-memory==2.0.4`)**（已上线 [PyPI](https://pypi.org/project/hy-memory/2.0.4/)），并开源 **Hy-Memory** monorepo 与 **[MemHub](memhub/README.md)**！

docs/env_reference.md

@@ -182,9 +182,29 @@ SDK 不设置 Rerank Search 并发上限。开启后模型在 `HyMemoryClient`
 | `MEMORY_RECALL_STRENGTH_TAU` | `180` | 衰减时间常数，天 |
 | `MEMORY_RECALL_ACCESS_TRACKING` | `true` | Strength 开启时是否回写访问信息 |
 | `MEMORY_ENTITY_STORE_ENABLED` | `false` | 是否维护独立 entity collection；当前 Reader 不直接读取 |
+| `MEMORY_INTENTION_DEDUP_ENABLED` | `true` | 是否对 L7 Intention 判重（读侧和写入侧批内）；见下文 |
+| `MEMORY_INTENTION_DEDUP_THRESHOLD` | `MEMORY_DEDUP_THRESHOLD`，再缺省为 `0.95` | Intention 读侧判重的 cosine 阈值 |
 
 旧数据可调用当前公开方法 `client.build_entity_store(user_id)` 补建 Entity Store。
 
+Intention 判重：开启时（默认，与以往行为一致），Search 召回的 L7 Intention 中，
+同 `user_id` + 同 `agent_id` + `memory_at` 同一天 + `valid_until` 相同、且 cosine ≥ 阈值的
+条目视为复本，只返回最早写入的一条，其余在后台从向量库**删除**。判重不区分内容中的项目、
+对象等语义差异，内容高度相似但对象不同的意图可能被误删；写入时同一批抽取结果也会做一次
+批内判重。关闭后这两处都不判重，不隐藏、不丢弃、也不删除意图。两项对应
+`MemoryConfig.recall.intention_dedup_enabled` /
+`recall.intention_dedup_threshold`，按 client 生效，环境变量只提供默认值：
+
+```python
+client = HyMemoryClient.from_config({
+    "recall": {"intention_dedup_enabled": False},
+})
+```
+
+`MEMORY_DEDUP_THRESHOLD` 同时被写入侧批内意图判重和 dedup 内核使用；
+`MEMORY_INTENTION_DEDUP_THRESHOLD` 只影响读侧 Intention 判重，写入侧批内判重的阈值
+仍取 `MEMORY_DEDUP_THRESHOLD`。
+
 ## 日志、Trace 与历史
 
 | 变量 | 默认值 | 说明 |

docs/multi_speaker_design.md

@@ -107,5 +107,5 @@ L1_RAW 保存的内容使用上述渲染格式。历史回读时：
 ```bash
 python -m pytest -q \
   tests/test_multi_speaker_format.py \
-  tests/test_reconcile_fallback.py
+  tests/test_reconcile_failure.py
 ```

docs/scene_coding_usage.md

@@ -150,7 +150,23 @@ working/coding 写入返回双层结果：
 }
 ```
 
-`scene="coding"` 还会返回 `chain_rounds`。出于历史兼容，该字段当前统计本次识别并处理
+抽取 LLM 调用失败、返回空 content 或回复解析不出 JSON，以及经验 / 事实向量化失败时，
+写入返回 `success=False`、`error_code=502`，`agent_error_code` 依次为 `LLM_ERROR`、
+`EMPTY_RESPONSE`、`JSON_PARSE_FAILED`、`EMBEDDING_FAILED`，`error_message` 以
+`[CODE]` 开头；没有向量的经验 / 事实不会落库，失败的写入也不追加对话 trace，换一个
+`request_id` 重跑即可。模型正常作答但没有值得记的内容仍是 `success=True`、0 条。
+显式开启 `MEMORY_CODING_VERBATIM_FALLBACK_ENABLED` 时抽取失败沿用原文兜底。
+
+经验层 / 事实层 reconcile 的模型决策同样不再兜底：LLM 调用失败、返回空 content 或回复
+不是带 `ops` 列表的 JSON 对象时，写入返回 `success=False`、
+`agent_error_code="RECONCILE_FAILED"`，原因在 `reconcile_error_code`（`LLM_UNAVAILABLE` /
+`EMPTY_RESPONSE` / `JSON_PARSE_FAILED`，与 chat 链路一致）。两层的模型决策都在落库之前
+完成，任何一层失败时本次一条经验 / 事实都不存，旧事实也不会被覆盖。经验层回复
+`{"ops": []}` 表示「无需任何操作」，写入成功、经验层不存；`ops` 非空却没有一条可识别的
+op 视为解析失败。事实层回复 `{"ops": []}` 表示都不覆盖、照常插入新事实；没有候选时不
+调用 LLM。
+
+`scene="coding"` 还会返回 `chain_rounds`（写入失败时不记录演进链，也不返回该字段）。出于历史兼容，该字段当前统计本次识别并处理
 的 diff hunk 数，而不保证等于最终合并后的唯一演进 round 数。`0` 表示没有识别到可记录
 的代码修改，不代表双层 memory 写入失败。
 

docs/usage.md

@@ -128,6 +128,14 @@ result = client.add(
 双层 reconcile 操作、`experience_ids`、`fact_ids` 等字段，完整结构见
 [scene_coding_usage.md](scene_coding_usage.md#4-返回结构)。
 
+写入失败时 `success=False`，`error_code` 为 HTTP 风格的整数，`agent_error_code` 给出稳定
+失败码。pro / ultra 的 reconcile（新事实与已有记忆判重、合并）模型调用失败、返回空
+content 或回复解析不出时，`add` 与 `add_extracted` 都报 `agent_error_code="RECONCILE_FAILED"`，
+具体原因在 `reconcile_error_code`（`LLM_UNAVAILABLE` / `EMPTY_RESPONSE` /
+`JSON_PARSE_FAILED` / `RECONCILE_EXCEPTION`）。此时本次一条新记忆都不落库，`add` 已写入
+的原始对话按抽取失败同样回滚（`l1_rollback.retry_safe=True`）；模型恢复后换一个
+`request_id` 重跑即可。`RECONCILE_ENABLED=false` 时不调用 reconcile，直接写入。
+
 `mode="lite"` 不执行 LLM 抽取，写入内容直接以 `L1_RAW` 形式保存。lite 的 Search 是
 严格的 raw-only 向量检索：无论调用方传入什么 `layers`、`scene` 或 `search_mode`，都只
 召回 `L1_RAW`，不会进入 working/coding、Schema 或 Intention 链路，也不会调用场景判断

hy_memory/agent/reconciler.py

@@ -136,10 +136,10 @@ class ReconcileResult:
     ops: List[ReconcileOp] = field(default_factory=list)
     success: bool = True
     error: Optional[str] = None
-    # True = reconcile 失败后走了「全部 ADD」兜底（见 _fallback_add_ops）。
-    # 结果仍然可用（success=True），但没有做过去重/演化判定，可能引入重复。
-    degraded: bool = False
-    degraded_reason: Optional[str] = None
+    # success=False 时的稳定失败码：LLM_UNAVAILABLE / EMPTY_RESPONSE /
+    # JSON_PARSE_FAILED / RECONCILE_EXCEPTION。失败时 ops 恒为空：writer 什么都
+    # 不落库，整次写入报失败，调用方换个 request_id 重跑即可（reconcile 会判重）。
+    error_code: Optional[str] = None
     # reconcile 链路 LLM token 消耗（search-query + reconcile 两次 LLM 调用之和）
     prompt_tokens: int = 0
     completion_tokens: int = 0
@@ -151,7 +151,7 @@ class ReconcileResult:
     # 用 content 作 key 而不是 node_id：新记忆此刻还没入库、没有 id。
     candidate_scores: Dict[str, List[Tuple[str, float]]] = field(default_factory=dict)
     # reconcile 候选检索已经为每条新 memory 算过 embedding。把原始文本对应向量交回
-    # writer，ADD-all / degraded ADD 可直接落库，避免同一事实再次请求 embedding。
+    # writer，原文不变的 ADD 可直接落库，避免同一事实再次请求 embedding。
     # 仅按完全相同 content 复用；LLM 改写后的 UPDATE/SUPERSEDE 会重新计算，防止错配。
     new_memory_embeddings: Dict[str, List[float]] = field(default_factory=dict)
 
@@ -394,49 +394,6 @@ class MemoryReconciler:
 
         return [], None
 
-    @staticmethod
-    def _fallback_add_ops(
-        new_memories: List[str],
-        new_memories_with_meta: Optional[List[Dict]] = None,
-    ) -> List[ReconcileOp]:
-        """reconcile 彻底失败时的兜底：把抽取结果**原样全部 ADD**。
-
-        为什么必须有这个兜底：reconcile 只是决定「新事实和旧记忆怎么合」。它挂了（网关 500、
-        JSON 解析不出）不代表抽取结果没价值 —— 此前的行为是把一整批完好的事实**全部丢弃**，
-        线上实测因此丢掉过整块内容（含评测题的正确答案）。宁可留重复也不要丢内容：
-        重复还能被后续 dedup / reconcile 收拾，丢了就永远找不回来。
-        """
-        metas = new_memories_with_meta or []
-        by_content = {
-            (m.get("content") or ""): m for m in metas if isinstance(m, dict)
-        }
-        ops: List[ReconcileOp] = []
-        for text in new_memories:
-            if not text:
-                continue
-            meta = by_content.get(text) or {}
-            ops.append(ReconcileOp(
-                op="ADD",
-                content=text,
-                layer=meta.get("layer"),
-                tags=meta.get("tags") or [],
-                owner=meta.get("owner"),
-                topic_paths=meta.get("topic_paths") or [],
-                event_facet=meta.get("event_facet") or {},
-                topic_assignments=meta.get("topic_assignments") or [],
-                topic_paths_provided=bool(
-                    meta.get("topic_paths_provided", "topic_paths" in meta)
-                ),
-                event_facet_provided=bool(
-                    meta.get("event_facet_provided", "event_facet" in meta)
-                ),
-                topic_assignments_provided=bool(meta.get(
-                    "topic_assignments_provided", "topic_assignments" in meta,
-                )),
-                reason="reconcile unavailable → stored as-is (degraded)",
-            ))
-        return ops
-
     async def reconcile(
         self,
         new_memories: List[str],
@@ -1088,8 +1045,8 @@ class MemoryReconciler:
                     )
                 except Exception as e:
                     # LLM 彻底不可用（provider 已按 max_retries 重试过，网关 500 /
-                    # 连接错误等）。**不能让它冒泡** —— 冒泡会让整批抽取结果连带丢弃。
-                    # 交给下面的 ADD-all 兜底。
+                    # 连接错误等）。不冒泡：下面统一记 RECONCILE 失败日志，再返回
+                    # success=False —— writer 不落任何新记忆，整次写入报失败。
                     _llm_error = f"{type(e).__name__}: {e}"
                     logger.warning(f"[reconciler] RECONCILE LLM unavailable: {_llm_error}")
                     break
@@ -1097,7 +1054,7 @@ class MemoryReconciler:
                 _tok_pt += response.prompt_tokens
                 _tok_ct += response.completion_tokens
                 _tok_total += response.tokens_used
-                raw_response = response.content
+                raw_response = response.content or ""
                 ops = self._parse_ops(raw_response)
                 ops = enforce_time_order(ops, current_time, candidate_map)
                 ops = self._inherit_exact_input_structure(
@@ -1106,7 +1063,9 @@ class MemoryReconciler:
                 if _structure_metadata_on:
                     ops = self._resolve_structure_references(ops, candidate_map)
 
-                _is_empty_array = self._strip_code_fence(raw_response) in ("[]", "")
+                # 只有字面量 "[]" 才是「模型判定无需任何操作」。HTTP 200 但 content
+                # 为空不是决策，是失败：按 EMPTY_RESPONSE 处理，不能当成 0 条成功。
+                _is_empty_array = self._strip_code_fence(raw_response) == "[]"
                 if ops or _is_empty_array:
                     _parse_ok = True
                     break
@@ -1136,7 +1095,7 @@ class MemoryReconciler:
                     error_msg = (
                         f"RECONCILE LLM returned empty response after {_n_attempts} attempts"
                     )
-                    error_code = "EMPTY_RESPONSE" 
+                    error_code = "EMPTY_RESPONSE"
                 logger.warning(f"[reconciler] {error_msg}")
 
                 if cache and request_id:
@@ -1153,14 +1112,13 @@ class MemoryReconciler:
                                 {
                                     "error": error_code,
                                     "message": error_msg,
-                                    "fallback": "ADD_ALL",
-                                    "fallback_count": len(new_memories or []),
+                                    "stored": 0,
                                 },
                                 ensure_ascii=False,
                             ),
                             elapsed_ms=recon_elapsed,
-                            # LLM 彻底不可用时 response 是 None —— 这行本身会抛
-                            # AttributeError，而它正好在兜底路径上，会把兜底也一起废掉
+                            # LLM 彻底不可用时 response 是 None —— 直接取属性会抛
+                            # AttributeError，把失败日志本身也废掉
                             prompt_tokens=getattr(response, "prompt_tokens", 0) or 0,
                             completion_tokens=getattr(response, "completion_tokens", 0) or 0,
                             total_tokens=getattr(response, "tokens_used", 0) or 0,
@@ -1170,22 +1128,16 @@ class MemoryReconciler:
                             f"[reconciler] store failed RECONCILE log failed: {e}"
                         )
 
-                # 兜底：JSON 解析不出来不等于抽取结果没价值 —— 全部 ADD，别丢内容。
-                _fb = self._fallback_add_ops(new_memories, new_memories_with_meta)
-                logger.warning(
-                    f"[reconciler] falling back to ADD-all: {len(_fb)} memories "
-                    f"({error_code})"
-                )
+                # 不做 ADD-all 兜底：没经过判重 / 演化的整批 ADD 会在重跑时产生重复，
+                # 而且调用方看到 success 就不会重试。这里报失败、不落库，由调用方重跑。
                 return ReconcileResult(
-                    ops=_fb,
-                    success=bool(_fb),
-                    error=None if _fb else error_msg,
-                    degraded=bool(_fb),
-                    degraded_reason=error_code,
+                    ops=[],
+                    success=False,
+                    error=error_msg,
+                    error_code=error_code,
                     prompt_tokens=_tok_pt,
                     completion_tokens=_tok_ct,
                     total_tokens=_tok_total,
-                    new_memory_embeddings=new_memory_embeddings,
                 )
 
             # 写 RECONCILE pipeline log
@@ -1250,20 +1202,14 @@ class MemoryReconciler:
 
         except Exception as e:
             logger.error(f"[reconciler] failed: {e}", exc_info=True)
-            # 兜底同样适用于「reconcile 链路任意环节炸了」（候选检索、embed、
-            # prompt 组装…）。此前这里返回 ops=[] → writer 直接丢弃整批抽取结果。
-            _fb = self._fallback_add_ops(new_memories, new_memories_with_meta)
-            if _fb:
-                logger.warning(
-                    f"[reconciler] falling back to ADD-all after unexpected error: "
-                    f"{len(_fb)} memories"
-                )
-                return ReconcileResult(
-                    ops=_fb, success=True,
-                    degraded=True, degraded_reason=f"EXCEPTION:{type(e).__name__}",
-                    new_memory_embeddings=dict(new_memory_embeddings or {}),
-                )
-            return ReconcileResult(ops=[], success=False, error=str(e))
+            # reconcile 链路任意环节炸了（候选检索、embed、prompt 组装…）：此时还
+            # 没有任何新记忆落库，报失败让整次写入可以干净地重跑。
+            return ReconcileResult(
+                ops=[],
+                success=False,
+                error=f"{type(e).__name__}: {e}",
+                error_code="RECONCILE_EXCEPTION",
+            )
 
     @staticmethod
     def _inherit_exact_input_structure(

hy_memory/client.py

@@ -134,6 +134,7 @@ _WRITE_DIAGNOSTIC_KEYS = (
     "agent_status",
     "agent_error_code",
     "agent_error",
+    "reconcile_error_code",
     "l1_rollback",
     "l1_rollback_failed",
     "partial_agent_persist",
@@ -1863,6 +1864,7 @@ class HyMemoryClient:
         branch: Optional[str] = None,
         request_id: Optional[str] = None,
         layers: Optional[List[Any]] = None,
+        statuses: Optional[List[Any]] = None,
         embed_override: Optional[Dict[str, Any]] = None,
         query_embedding: Optional[List[float]] = None,
         rerank: bool = True,
@@ -1955,6 +1957,8 @@ class HyMemoryClient:
             layers:             可选。pro/ultra 下只召回指定层级（字符串或
                                 MemoryLayer），在召回阶段生效。lite 下忽略该参数并
                                 强制只召回 L1_RAW。
+            statuses:           仅用于 L1_RAW 定向搜索，可显式包含 active / shadow。
+                                非 raw 搜索或 scene="all" 传入时拒绝，避免静默忽略。
             rerank:             默认 True（原行为）。False 时本次调用跳过全部重排阶段：
                                 chat 路的本地 cross-encoder 重排（recall.local_rerank_enabled）
                                 与记忆关系图重排（graph_rerank / episode 扩展），working/
@@ -1998,7 +2002,7 @@ class HyMemoryClient:
             intention_limit=intention_limit, created_after=created_after,
             reader=reader,
             workspace_id=workspace_id, branch=branch,
-            request_id=request_id, layers=layers,
+            request_id=request_id, layers=layers, statuses=statuses,
             embed_override=embed_override,
             query_embedding=query_embedding,
             rerank=rerank,
@@ -3032,7 +3036,9 @@ class HyMemoryClient:
                 # 版本演进链层（scene="coding" 独有）。放在 writer.write 之后、返回
                 # 之前，因为它只依赖对话原文，与向量层写入结果无关。
                 # best-effort：这层挂不上不影响本次 add 的向量层产出。
-                if scene_variant == "coding":
+                # 向量层写入失败（success=False）时跳过：调用方会重跑整段，失败的
+                # 那次不该先把改动记进演进链。
+                if scene_variant == "coding" and resp.get("success"):
                     resp["chain_rounds"] = self._observe_chain(
                         chat_messages, user_id=uid,
                         workspace_id=workspace_id, branch=branch,
@@ -3384,12 +3390,14 @@ class HyMemoryClient:
         request_id: str,
         t0: float,
         query_embedding: Optional[List[float]],
+        statuses: Optional[List[Any]],
     ) -> Dict[str, Any]:
         """Implement `search(..., layers=['l1_raw'])` without a second API."""
         from .models.memory import MemoryLayer, MemoryStatus
 
         embedding = query_embedding or await self._embed_service.embed(query)
         fetch = min(max(limit * (10 if session_ids else 2), limit), 10_000)
+        status_filter = self._normalize_statuses(statuses) or [MemoryStatus.ACTIVE]
         hits = await self._vector_store.search(
             query_embedding=embedding,
             user_ids=user_ids,
@@ -3399,7 +3407,7 @@ class HyMemoryClient:
             layers=[MemoryLayer.L1_RAW],
             limit=fetch,
             score_threshold=min_score,
-            status_filter=[MemoryStatus.ACTIVE],
+            status_filter=status_filter,
             only_latest=False,
             created_after=created_after,
         )
@@ -3417,7 +3425,7 @@ class HyMemoryClient:
                     "memory_id": row.pop("raw_id"),
                     **row,
                     "layer": MemoryLayer.L1_RAW.value,
-                    "status": MemoryStatus.ACTIVE.value,
+                    "status": node.status.value,
                     "score": round(float(hit.get("score", 0.0)), 4),
                 }
             )
@@ -3861,6 +3869,7 @@ class HyMemoryClient:
         branch: Optional[str] = None,
         request_id: Optional[str] = None,
         layers: Optional[List[Any]] = None,
+        statuses: Optional[List[Any]] = None,
         embed_override: Optional[Dict[str, Any]] = None,
         query_embedding: Optional[List[float]] = None,
         rerank: bool = True,
@@ -3890,7 +3899,7 @@ class HyMemoryClient:
                     schema_min_score=schema_min_score, schema_limit=schema_limit,
                     intention_limit=intention_limit, created_after=created_after,
                     reader=reader, workspace_id=workspace_id, branch=branch,
-                    request_id=request_id, layers=layers,
+                    request_id=request_id, layers=layers, statuses=statuses,
                     query_embedding=query_embedding,
                     rerank=rerank,
                 )
@@ -3905,7 +3914,7 @@ class HyMemoryClient:
             schema_min_score=schema_min_score, schema_limit=schema_limit,
             intention_limit=intention_limit, created_after=created_after,
             reader=reader, workspace_id=workspace_id, branch=branch,
-            request_id=request_id, layers=layers,
+            request_id=request_id, layers=layers, statuses=statuses,
             query_embedding=query_embedding,
             rerank=rerank,
         )
@@ -3935,6 +3944,7 @@ class HyMemoryClient:
         branch: Optional[str] = None,
         request_id: Optional[str] = None,
         layers: Optional[List[Any]] = None,
+        statuses: Optional[List[Any]] = None,
         query_embedding: Optional[List[float]] = None,
         rerank: bool = True,
     ) -> Dict[str, Any]:
@@ -4020,6 +4030,17 @@ class HyMemoryClient:
                 "Use single agent_id with multiple session_ids, or multiple agent_ids without session_ids."
             )
 
+        if statuses is not None:
+            from .models.memory import MemoryLayer
+
+            requested_layers = self._normalize_layers(layers)
+            if scene_all or (
+                not lite_mode and requested_layers != [MemoryLayer.L1_RAW]
+            ):
+                raise ValueError(
+                    "statuses is supported only for explicit L1_RAW search"
+                )
+
         if scene_all:
             return await self._search_all_scenes(
                 query, queries=queries, search_mode=search_mode,
@@ -4355,6 +4376,7 @@ class HyMemoryClient:
                 request_id=request_id,
                 t0=t0,
                 query_embedding=query_embedding,
+                statuses=statuses,
             )
 
         read_req = ReadRequest(

hy_memory/coding/__init__.py

@@ -12,6 +12,7 @@ HY Memory - Coding Memory 模块
 
 from .types import (
     CodingMemory,
+    CodingWriteError,
     CodingMemoryDraft,
     ReconcileOp,
     WorkingFact,
@@ -26,6 +27,7 @@ from .types import (
 
 __all__ = [
     "CodingMemory",
+    "CodingWriteError",
     "CodingMemoryDraft",
     "ReconcileOp",
     "WorkingFact",

hy_memory/coding/extractor.py

@@ -33,7 +33,7 @@ from .preproc import (
     prepare_extractor_messages,
 )
 from .judge import _store_coding_log
-from .types import CodingMemoryDraft, WorkingFactDraft
+from .types import CodingMemoryDraft, CodingWriteError, WorkingFactDraft
 
 
 
@@ -217,6 +217,10 @@ class CodingMemoryExtractor:
         Returns:
             (经验草稿, 事实草稿)。两层都可能为空。只有显式启用
             verbatim_fallback_enabled 时，模型没产出 fact 才调用 _verbatim_fact。
+
+        Raises:
+            CodingWriteError: 未开启原文兜底时，LLM 调用失败（LLM_ERROR）、返回空
+                content（EMPTY_RESPONSE）或回复解析不出 JSON 对象（JSON_PARSE_FAILED）。
         """
         if not messages:
             return [], []
@@ -268,8 +272,9 @@ class CodingMemoryExtractor:
             )
         except Exception as e:
             logger.warning(f"[coding-extract] LLM call failed: {e}")
-            # 经验层不兜底。事实层原文兜底也默认关闭，避免 assistant/tool 轨迹被
-            # 当作 statement 直接展示；仅在配置显式开启时保留旧行为。
+            # 经验层不兜底。事实层原文兜底默认关闭，避免 assistant/tool 轨迹被
+            # 当作 statement 直接展示；关闭时 LLM 失败抛 CodingWriteError(LLM_ERROR)，
+            # 整次写入报失败，而不是「成功、0 条」。仅在配置显式开启时保留旧行为。
             verbatim = (
                 self._verbatim_fact(messages)
                 if self.verbatim_fallback_enabled else None
@@ -296,9 +301,33 @@ class CodingMemoryExtractor:
                 ),
                 elapsed_ms=round((time.perf_counter() - _t0) * 1000, 2),
             )
+            if not self.verbatim_fallback_enabled:
+                raise CodingWriteError(
+                    "LLM_ERROR",
+                    f"coding extract LLM call failed: {type(e).__name__}: {e}",
+                ) from e
             return [], ([verbatim] if verbatim else [])
         _elapsed = round((time.perf_counter() - _t0) * 1000, 2)
 
+        # 模型答了且没有可记的内容（如 {"experiences": [], "fact": null}）是正常的空
+        # 抽取；200 但 content 为空、或回复解析不出 JSON 对象，是模型失败，不能当成
+        # 「成功、0 条」。原文兜底显式开启时沿用旧行为（交给下面的 verbatim 兜底）。
+        failure = self._output_failure(resp.content)
+        if failure is not None and not self.verbatim_fallback_enabled:
+            code, message = failure
+            await _store_coding_log(
+                self.cache, request_id=request_id, user_id=user_id, agent_id=agent_id,
+                session_id=session_id or "", step="CODING_EXTRACT", prompt=prompt,
+                response=resp.content or "",
+                parsed=json.dumps(
+                    {"drafts": 0, "error": code, "message": message},
+                    ensure_ascii=False,
+                ),
+                elapsed_ms=_elapsed, prompt_tokens=resp.prompt_tokens,
+                completion_tokens=resp.completion_tokens, total_tokens=resp.tokens_used,
+            )
+            raise CodingWriteError(code, message)
+
         raw_experiences, raw_facts = self._parse_output(resp.content)
 
         # 经验层的 files 走规则抽取（整段轨迹碰过的文件）；事实层的 files 由 LLM
@@ -478,12 +507,22 @@ class CodingMemoryExtractor:
         return "\n".join(rows)
 
     @classmethod
-    def _parse_output(
-        cls, text: str
-    ) -> Tuple[List[Dict[str, Any]], List[Dict[str, Any]]]:
-        """宽松解析 LLM 输出 JSON，返回 (experiences, facts) 两个原始列表。"""
+    def _output_failure(cls, text: Optional[str]) -> Optional[Tuple[str, str]]:
+        """回复本身是失败时返回 (error_code, message)；正常（含空抽取）返回 None。"""
+        if not (text or "").strip():
+            return "EMPTY_RESPONSE", "coding extract LLM returned empty response"
+        if cls._load_output_object(text) is None:
+            return (
+                "JSON_PARSE_FAILED",
+                f"coding extract output is not a JSON object ({len(text)} chars)",
+            )
+        return None
+
+    @staticmethod
+    def _load_output_object(text: Optional[str]) -> Optional[Dict[str, Any]]:
+        """宽松解析 LLM 输出，返回顶层 JSON 对象；解析不出返回 None。"""
         if not text:
-            return [], []
+            return None
         s = text.strip()
         # 去 markdown fence
         if s.startswith("```"):
@@ -509,8 +548,17 @@ class CodingMemoryExtractor:
                     obj = json.loads(s[start: end + 1])
                 except Exception:
                     obj = None
+        return obj if isinstance(obj, dict) else None
 
-        if not isinstance(obj, dict):
+    @classmethod
+    def _parse_output(
+        cls, text: str
+    ) -> Tuple[List[Dict[str, Any]], List[Dict[str, Any]]]:
+        """宽松解析 LLM 输出 JSON，返回 (experiences, facts) 两个原始列表。"""
+        if not text:
+            return [], []
+        obj = cls._load_output_object(text)
+        if obj is None:
             logger.warning(
                 f"[coding-extract] failed to parse output ({len(text or '')} chars)"
             )

hy_memory/coding/fact_reconciler.py

@@ -18,6 +18,7 @@ import json
 import logging
 import os
 import uuid
+from dataclasses import dataclass, field
 from datetime import datetime
 from typing import Any, Dict, List, Optional, Tuple
 
@@ -34,6 +35,7 @@ from .types import (
 
 
     MAX_FACT_CHAIN_ENTRIES,
+    CodingWriteError,
     FactReconcileOp,
     WorkingFact,
     WorkingFactDraft,
@@ -259,6 +261,16 @@ def build_chain_summary_prompt(
     return with_output_language(prompt, code, explicit=explicit is not None), code
 
 
+@dataclass
+class FactReconcilePlan:
+    """plan() 的产物：覆盖判定已完成、尚未落库。apply() 才执行 store 操作。"""
+
+    drafts: List[WorkingFactDraft]
+    candidates: List[List[WorkingFact]] = field(default_factory=list)
+    supersedes: Dict[int, List[str]] = field(default_factory=dict)
+    context: Dict[str, Any] = field(default_factory=dict)
+
+
 # ================================================================
 # WorkingFactReconciler
 # ================================================================
@@ -327,15 +339,63 @@ class WorkingFactReconciler:
         language: Optional[str] = None,
     ) -> Tuple[List[WorkingFact], List[FactReconcileOp]]:
         """
-        执行 reconcile + 持久化。memory_at 是这段对话的时间，记到新事实上。
-        language 为显式 prompt 语言码（None → zh/en 自动检测），同时用于演变总结。
+        执行 reconcile + 持久化（plan() 后紧接 apply()）。memory_at 是这段对话的
+        时间，记到新事实上。language 为显式 prompt 语言码（None → zh/en 自动检测），
+        同时用于演变总结。
 
         Returns:
-            (真正落库的新事实, 执行过的 ops)。LLM 挂掉时退化为全 INSERT 不覆盖，
-            宁可多留一条过期事实，也不因为一次调用失败丢结论。
+            (真正落库的新事实, 执行过的 ops)。
+
+        Raises:
+            CodingWriteError(RECONCILE_FAILED)：覆盖判定的 LLM 失败 / 空回复 /
+                解析不出。此时既不插入新事实，也不覆盖任何旧事实。
         """
+        plan = await self.plan(
+            drafts,
+            user_id=user_id,
+            agent_id=agent_id,
+            session_id=session_id,
+            workspace_id=workspace_id,
+            branch=branch,
+            source=source,
+            memory_at=memory_at,
+            language=language,
+        )
+        return await self.apply(plan)
+
+    async def plan(
+        self,
+        drafts: List[WorkingFactDraft],
+        *,
+        user_id: str,
+        agent_id: str = "default_agent",
+        session_id: Optional[str] = None,
+        workspace_id: Optional[str] = None,
+        branch: Optional[str] = None,
+        source: str = "default",
+        memory_at: Optional[datetime] = None,
+        language: Optional[str] = None,
+    ) -> FactReconcilePlan:
+        """检索 candidates + 覆盖判定，不落库。
+
+        没有任何候选时不调 LLM（全部 INSERT 是确定的结论，不是兜底）。调了 LLM 时，
+        有效回复 = JSON 对象且 "ops" 是列表（空列表 = 都不覆盖、只插入）。LLM 调用
+        失败（LLM_UNAVAILABLE）、200 但 content 为空（EMPTY_RESPONSE）、回复不是
+        上述形状（JSON_PARSE_FAILED）时抛 CodingWriteError(RECONCILE_FAILED)。
+        此前 LLM 失败会退化为全 INSERT 不覆盖，留下本该被接续的旧事实。
+        """
+        context = dict(
+            user_id=user_id,
+            agent_id=agent_id,
+            session_id=session_id,
+            workspace_id=workspace_id,
+            branch=branch,
+            source=source,
+            memory_at=memory_at,
+            language=language,
+        )
         if not drafts:
-            return [], []
+            return FactReconcilePlan(drafts=[], context=context)
 
         candidates = await self._retrieve_candidates(
             drafts,
@@ -349,27 +409,37 @@ class WorkingFactReconciler:
 
         try:
             supersedes = await self._llm_decide(drafts, candidates, language=language)
+        except CodingWriteError:
+            raise
         except Exception as e:
-            logger.warning(
-                f"[fact-reconcile] LLM decide failed, insert without supersede: {e}"
-            )
-            supersedes = {}
+            logger.warning(f"[fact-reconcile] LLM decide failed: {e}")
+            raise CodingWriteError(
+                "RECONCILE_FAILED",
+                f"working fact reconcile LLM call failed: {type(e).__name__}: {e}",
+                cause="LLM_UNAVAILABLE",
+            ) from e
 
+        return FactReconcilePlan(
+            drafts=list(drafts),
+            candidates=candidates,
+            supersedes=supersedes,
+            context=context,
+        )
+
+    async def apply(
+        self, plan: FactReconcilePlan,
+    ) -> Tuple[List[WorkingFact], List[FactReconcileOp]]:
+        """执行 plan() 的决策（覆盖旧事实 + 插入新事实）。"""
+        if not plan.drafts:
+            return [], []
         facts, ops = await self._execute(
-            drafts,
-            candidates,
-            supersedes,
-            user_id=user_id,
-            agent_id=agent_id,
-            session_id=session_id,
-            workspace_id=workspace_id,
-            branch=branch,
-            source=source,
-            memory_at=memory_at,
-            language=language,
+            plan.drafts,
+            plan.candidates,
+            plan.supersedes,
+            **plan.context,
         )
         logger.info(
-            f"[fact-reconcile] drafts={len(drafts)} inserted={len(facts)} "
+            f"[fact-reconcile] drafts={len(plan.drafts)} inserted={len(facts)} "
             f"superseded={sum(1 for o in ops if o.action == 'SUPERSEDE')}"
         )
         return facts, ops
@@ -473,6 +543,11 @@ class WorkingFactReconciler:
             max_tokens=self.max_tokens,
             audit_stage="coding_fact_reconcile",
         )
+        failure = self._reply_failure(resp.content)
+        if failure is not None:
+            code, message = failure
+            logger.warning(f"[fact-reconcile] {code}: {message}")
+            raise CodingWriteError("RECONCILE_FAILED", message, cause=code)
         return self._parse_ops(resp.content)
 
     # ------------------------------------------------------------
@@ -599,11 +674,24 @@ class WorkingFactReconciler:
             rows.append(f"for draft[{i}]:\n" + "\n".join(cand_rows))
         return "\n\n".join(rows) if rows else "(none)"
 
+    @classmethod
+    def _reply_failure(cls, text: Optional[str]) -> Optional[Tuple[str, str]]:
+        """回复本身是失败时返回 (cause, message)；有效回复（含 {"ops": []}）返回 None。"""
+        if not (text or "").strip():
+            return "EMPTY_RESPONSE", "working fact reconcile LLM returned empty response"
+        obj = cls._load_object(text)
+        if not isinstance(obj, dict) or not isinstance(obj.get("ops"), list):
+            return (
+                "JSON_PARSE_FAILED",
+                f"working fact reconcile output has no ops list ({len(text)} chars)",
+            )
+        return None
+
     @staticmethod
-    def _parse_ops(text: str) -> Dict[int, List[str]]:
-        """宽松解析 ops，返回 {draft_idx: [fact_id...]}。"""
+    def _load_object(text: Optional[str]) -> Optional[Dict[str, Any]]:
+        """宽松解析出顶层 JSON 对象；解析不出返回 None。"""
         if not text:
-            return {}
+            return None
         s = text.strip()
         # 去 markdown fence
         if s.startswith("```"):
@@ -621,7 +709,14 @@ class WorkingFactReconciler:
                     obj = json.loads(s[start: end + 1])
                 except Exception:
                     obj = None
+        return obj if isinstance(obj, dict) else None
 
+    @classmethod
+    def _parse_ops(cls, text: str) -> Dict[int, List[str]]:
+        """宽松解析 ops，返回 {draft_idx: [fact_id...]}。"""
+        if not text:
+            return {}
+        obj = cls._load_object(text)
         if not isinstance(obj, dict):
             logger.warning(
                 f"[fact-reconcile] failed to parse ops output ({len(text or '')} chars)"
@@ -689,6 +784,11 @@ class WorkingFactReconciler:
                 memory_at=memory_at,
             )
 
+            # 先确认新事实能向量化，再去覆盖旧事实：否则 embedding 挂掉时旧事实
+            # 已被软删、新事实又落不了库，这条结论就凭空没了。失败抛
+            # CodingWriteError(EMBEDDING_FAILED)，整次写入报失败。
+            new_embedding = await self.store.embed_fact(new_fact)
+
             allowed = {c.fact_id for c in (candidates[idx] if idx < len(candidates) else [])}
             targets = [
                 fid for fid in supersedes.get(idx, [])
@@ -769,7 +869,9 @@ class WorkingFactReconciler:
                         )
 
             try:
-                await self.store.insert_fact(new_fact)
+                await self.store.insert_fact(new_fact, embedding=new_embedding)
+            except CodingWriteError:
+                raise
             except Exception as e:
                 logger.warning(f"[fact-reconcile] INSERT failed: {e}")
                 continue

hy_memory/coding/reconciler.py

@@ -7,6 +7,9 @@ Coding Memory Reconciler
         （DELETE 由 LLM 在 draft 与 candidate 关系中观察到"明确否定/作废"时附带产出）
 
 执行端：reconcile() 调用 store 完成实际 ADD / UPDATE / DELETE 持久化操作。
+CodingWriter 分两步用：先 plan()（检索 + LLM 决策，不落库），等经验层与事实层的
+模型决策都成功后再 apply()（落库）。LLM 失败 / 空回复 / 解析不出时 plan() 抛
+CodingWriteError(RECONCILE_FAILED)，本次写入什么都不存。
 
 复用 LLMConfig.model（与 chat reconciler 共用）。
 
@@ -17,6 +20,7 @@ import json
 import logging
 import time
 import uuid
+from dataclasses import dataclass, field
 from typing import Any, Dict, List, Optional, Tuple
 
 from ..agent.llm_provider import LLMProvider
@@ -29,7 +33,7 @@ from ..prompts import (
 )
 from .judge import _store_coding_log
 from .store import CodingMemoryStore
-from .types import CodingMemory, CodingMemoryDraft, ReconcileOp
+from .types import CodingMemory, CodingMemoryDraft, CodingWriteError, ReconcileOp
 
 
 
@@ -93,6 +97,15 @@ def build_experience_reconcile_prompt(
     return with_output_language(prompt, code, explicit=explicit is not None), code
 
 
+@dataclass
+class ExperienceReconcilePlan:
+    """plan() 的产物：模型已决策、尚未落库。apply() 才执行 store 操作。"""
+
+    drafts: List[CodingMemoryDraft]
+    candidates_per_draft: List[List[CodingMemory]] = field(default_factory=list)
+    ops: List[ReconcileOp] = field(default_factory=list)
+
+
 # ================================================================
 # CodingMemoryReconciler
 # ================================================================
@@ -143,21 +156,52 @@ class CodingMemoryReconciler:
         language: Optional[str] = None,
     ) -> List[ReconcileOp]:
         """
-        执行 reconcile + 持久化。返回执行的 ReconcileOp[]（含成功执行的 ADD/UPDATE/DELETE/SKIP）。
+        执行 reconcile + 持久化（plan() 后紧接 apply()）。返回执行的 ReconcileOp[]
+        （含成功执行的 ADD/UPDATE/DELETE/SKIP）。
 
-        执行错误（如 LLM 失败）会 fail-safe 回退到对每个 draft 直接 ADD。
+        LLM 失败、空回复或解析不出时抛 CodingWriteError(RECONCILE_FAILED)，什么都
+        不落库——不再回退成「全部 ADD」。
+        """
+        plan = await self.plan(
+            drafts,
+            request_id=request_id,
+            user_id=user_id,
+            agent_id=agent_id,
+            session_id=session_id,
+            language=language,
+        )
+        return await self.apply(plan)
 
-        cache 非空时落 CODING_RECONCILE pipeline log——在 LLM 决策后、执行入库前打点，
-        这样即使 store 入库崩溃，reconcile 决策仍已可见（crash 不丢）。
+    async def plan(
+        self,
+        drafts: List[CodingMemoryDraft],
+        *,
+        request_id: str = "",
+        user_id: str = "",
+        agent_id: str = "default_agent",
+        session_id: str = "",
+        language: Optional[str] = None,
+    ) -> ExperienceReconcilePlan:
+        """检索 candidates + LLM 决策，不落库。
+
+        有效回复 = 一个 JSON 对象，其 "ops" 是列表：
+          - {"ops": []}：模型判定「无需任何操作」（与 chat reconcile 的 [] 同义），
+            成功、本层什么都不存；
+          - 非空列表：至少要有一条可识别的 op（ADD/UPDATE/DELETE/SKIP），否则视为
+            解析失败。漏掉的 draft 仍按原规则补 ADD（那是对有效回复的校验兜底，
+            不是模型失败兜底）。
+        LLM 调用失败（LLM_UNAVAILABLE）、200 但 content 为空（EMPTY_RESPONSE）、
+        回复不是上述形状（JSON_PARSE_FAILED）时抛 CodingWriteError(RECONCILE_FAILED)。
+
+        cache 非空时落 CODING_RECONCILE pipeline log（成功、失败都落）。
         """
         if not drafts:
-            return []
+            return ExperienceReconcilePlan(drafts=[])
 
         # 从 draft 回填 trace 身份（writer 通常显式传，这里兜底）
-        if drafts:
-            user_id = user_id or drafts[0].user_id
-            agent_id = agent_id or drafts[0].agent_id
-            session_id = session_id or (drafts[0].session_id or "")
+        user_id = user_id or drafts[0].user_id
+        agent_id = agent_id or drafts[0].agent_id
+        session_id = session_id or (drafts[0].session_id or "")
 
         # 1. 检索 candidates
         candidates_per_draft: List[List[CodingMemory]] = await self._retrieve_candidates(drafts)
@@ -167,19 +211,20 @@ class CodingMemoryReconciler:
         _decide_prompt = ""
         _decide_raw = ""
         _decide_resp = None
+        failure: Optional[Tuple[str, str]] = None
+        ops: List[ReconcileOp] = []
         try:
             ops, _decide_prompt, _decide_raw, _decide_resp = await self._llm_decide(
                 drafts, candidates_per_draft, language=language,
             )
+            failure = self._reply_failure(_decide_raw)
         except Exception as e:
-            logger.warning(f"[coding-reconcile] LLM decide failed, fallback to ADD-all: {e}")
-            ops = [ReconcileOp(action="ADD", draft_idx=i) for i in range(len(drafts))]
+            logger.warning(f"[coding-reconcile] LLM decide failed: {e}")
             _decide_raw = f"[LLM error] {type(e).__name__}: {str(e)[:300]}"
-
-        if not ops:
-            # LLM 输出无 ops，但有 drafts → fallback ADD-all
-            logger.info("[coding-reconcile] LLM returned no ops, fallback to ADD-all")
-            ops = [ReconcileOp(action="ADD", draft_idx=i) for i in range(len(drafts))]
+            failure = (
+                "LLM_UNAVAILABLE",
+                f"coding reconcile LLM call failed: {type(e).__name__}: {e}",
+            )
 
         _decide_elapsed = round((time.perf_counter() - _t0) * 1000, 2)
         # CODING_RECONCILE：LLM 决策完成即打点（执行入库之前，crash 不丢）
@@ -187,17 +232,42 @@ class CodingMemoryReconciler:
             self.cache, request_id=request_id, user_id=user_id, agent_id=agent_id,
             session_id=session_id, step="CODING_RECONCILE",
             prompt=_decide_prompt, response=_decide_raw,
-            parsed=json.dumps({"ops": [o.to_dict() for o in ops]}, ensure_ascii=False, default=str),
+            parsed=json.dumps(
+                {"error": failure[0], "message": failure[1], "stored": 0}
+                if failure else {"ops": [o.to_dict() for o in ops]},
+                ensure_ascii=False, default=str,
+            ),
             elapsed_ms=_decide_elapsed,
             prompt_tokens=getattr(_decide_resp, "prompt_tokens", 0) if _decide_resp else 0,
             completion_tokens=getattr(_decide_resp, "completion_tokens", 0) if _decide_resp else 0,
             total_tokens=getattr(_decide_resp, "tokens_used", 0) if _decide_resp else 0,
         )
+        if failure is not None:
+            code, message = failure
+            logger.warning(f"[coding-reconcile] {code}: {message}")
+            raise CodingWriteError("RECONCILE_FAILED", message, cause=code)
 
-        # 3. 校验 + 执行
-        executed = await self._execute(ops, drafts, candidates_per_draft)
+        return ExperienceReconcilePlan(
+            drafts=list(drafts),
+            candidates_per_draft=candidates_per_draft,
+            ops=ops,
+        )
+
+    async def apply(self, plan: ExperienceReconcilePlan) -> List[ReconcileOp]:
+        """执行 plan() 的决策（store ADD / UPDATE / DELETE）。"""
+        if not plan.drafts:
+            return []
+        if not plan.ops:
+            # 有效的 {"ops": []}：模型判定无需任何操作，本层什么都不存。
+            logger.info(
+                f"[coding-reconcile] drafts={len(plan.drafts)} LLM decided no ops"
+            )
+            return []
+        executed = await self._execute(
+            plan.ops, plan.drafts, plan.candidates_per_draft,
+        )
         logger.info(
-            f"[coding-reconcile] drafts={len(drafts)} ops={len(executed)} "
+            f"[coding-reconcile] drafts={len(plan.drafts)} ops={len(executed)} "
             + ", ".join(f"{a}={sum(1 for o in executed if o.action == a)}"
                         for a in ("ADD", "UPDATE", "DELETE", "SKIP"))
         )
@@ -316,11 +386,30 @@ class CodingMemoryReconciler:
             rows.append(f"for draft[{i}]:\n" + "\n".join(cand_rows))
         return "\n\n".join(rows) if rows else "(none)"
 
+    @classmethod
+    def _reply_failure(cls, text: Optional[str]) -> Optional[Tuple[str, str]]:
+        """回复本身是失败时返回 (cause, message)；有效回复（含 {"ops": []}）返回 None。"""
+        if not (text or "").strip():
+            return "EMPTY_RESPONSE", "coding reconcile LLM returned empty response"
+        obj = cls._load_object(text)
+        ops_raw = obj.get("ops") if isinstance(obj, dict) else None
+        if not isinstance(ops_raw, list):
+            return (
+                "JSON_PARSE_FAILED",
+                f"coding reconcile output has no ops list ({len(text)} chars)",
+            )
+        if ops_raw and not cls._parse_ops(text):
+            return (
+                "JSON_PARSE_FAILED",
+                f"coding reconcile output has no recognizable op ({len(text)} chars)",
+            )
+        return None
+
     @staticmethod
-    def _parse_ops(text: str) -> List[ReconcileOp]:
-        """宽松解析 ops 列表。"""
+    def _load_object(text: Optional[str]) -> Optional[Dict[str, Any]]:
+        """宽松解析出顶层 JSON 对象；解析不出返回 None。"""
         if not text:
-            return []
+            return None
         s = text.strip()
         # 去 markdown fence
         if s.startswith("```"):
@@ -344,8 +433,15 @@ class CodingMemoryReconciler:
                     obj = json.loads(s[start: end + 1])
                 except Exception:
                     obj = None
+        return obj if isinstance(obj, dict) else None
 
-        if not obj or not isinstance(obj, dict):
+    @classmethod
+    def _parse_ops(cls, text: str) -> List[ReconcileOp]:
+        """宽松解析 ops 列表。"""
+        if not text:
+            return []
+        obj = cls._load_object(text)
+        if not obj:
             logger.warning(
                 f"[coding-reconcile] failed to parse ops output ({len(text or '')} chars)"
             )
@@ -394,6 +490,9 @@ class CodingMemoryReconciler:
         - UPDATE  需 draft_idx 合法 + target_experience_id 非空
         - DELETE  需 target_experience_id 非空
         - SKIP    不执行任何 store 操作
+
+        向量化失败（CodingWriteError(EMBEDDING_FAILED)）不吞成「少执行一条」，
+        原样抛给 CodingWriter，整次写入报失败。
         """
         executed: List[ReconcileOp] = []
         # 已被 UPDATE 占用的 draft_idx → 防止同 draft 被重复 ADD/UPDATE
@@ -414,6 +513,8 @@ class CodingMemoryReconciler:
                     op.target_experience_id = memory.experience_id  # 回写 id 供 caller 读
                     executed.append(op)
                     consumed.add(op.draft_idx)
+                except CodingWriteError:
+                    raise
                 except Exception as e:
                     logger.warning(f"[coding-reconcile] ADD failed: {e}")
 
@@ -444,6 +545,8 @@ class CodingMemoryReconciler:
                     await self.store.update(memory)
                     executed.append(op)
                     consumed.add(op.draft_idx)
+                except CodingWriteError:
+                    raise
                 except Exception as e:
                     logger.warning(f"[coding-reconcile] UPDATE failed: {e}")
 
@@ -487,6 +590,8 @@ class CodingMemoryReconciler:
                     target_experience_id=memory.experience_id,
                     reason="fallback ADD (no LLM op)",
                 ))
+            except CodingWriteError:
+                raise
             except Exception as e:
                 logger.warning(f"[coding-reconcile] fallback ADD failed: {e}")
 

hy_memory/coding/store.py

@@ -44,7 +44,7 @@ from ..data.vector_store import create_vector_store
 from ..data.vector_store_base import VectorStoreBase
 from ..models.memory import MemoryLayer, MemoryNode, MemoryStatus
 from ..utils.async_executor import run_in_executor_guarded
-from .types import CodingMemory, WorkingFact
+from .types import CodingMemory, CodingWriteError, WorkingFact
 
 logger = logging.getLogger(__name__)
 
@@ -599,10 +599,15 @@ class CodingMemoryStore:
     # ------------------------------------------------------------
 
     async def insert(self, memory: CodingMemory) -> None:
-        """新增一条 coding memory（SQLite + VDB 全套）"""
+        """新增一条 coding memory（SQLite + VDB 全套）。
+
+        先向量化再落 SQLite：向量化失败抛 CodingWriteError(EMBEDDING_FAILED)，
+        什么都不写，不留一条没有向量、永远检索不到的经验。
+        """
         self._fill_timestamps(memory)
+        embeddings = await self._embed_vec_keys(memory)
         await _run_in_pool(self._upsert_sql_sync, memory)
-        await self._upsert_vec_keys(memory)
+        await self._upsert_vec_keys(memory, embeddings=embeddings)
         logger.info(
             f"[coding-store] inserted experience_id={memory.experience_id} "
             f"keys={1 + len(memory.search_keys)}"
@@ -627,6 +632,8 @@ class CodingMemoryStore:
         ):
             raise ValueError("coding_memory_update_authority_mismatch")
         prev_key_count = 1 + len(prev.search_keys)
+        # 先向量化：失败时旧经验（SQLite 与向量行）原样保留，不改一个字。
+        embeddings = await self._embed_vec_keys(memory)
 
         memory.updated_at = datetime.utcnow()
         if memory.created_at is None:
@@ -637,7 +644,7 @@ class CodingMemoryStore:
         # 删旧 VDB
         await self._delete_vec_keys_by_count(memory.experience_id, prev_key_count)
         # 写新 VDB
-        await self._upsert_vec_keys(memory)
+        await self._upsert_vec_keys(memory, embeddings=embeddings)
         logger.info(
             f"[coding-store] updated experience_id={memory.experience_id} "
             f"old_keys={prev_key_count} new_keys={1 + len(memory.search_keys)}"
@@ -1000,12 +1007,22 @@ class CodingMemoryStore:
     # 事实层
     # ------------------------------------------------------------
 
-    async def insert_fact(self, fact: WorkingFact) -> None:
-        """新增一条事实（SQLite + 事实 collection 各一行）。"""
+    async def insert_fact(
+        self, fact: WorkingFact, embedding: Optional[List[float]] = None,
+    ) -> None:
+        """新增一条事实（SQLite + 事实 collection 各一行）。
+
+        embedding 可由调用方预先用 embed_fact() 算好（fact reconcile 要在覆盖旧
+        事实之前确认新事实能向量化）；不传时这里算。向量化失败抛
+        CodingWriteError(EMBEDDING_FAILED)，什么都不写。
+        """
         if fact.created_at is None:
             fact.created_at = datetime.utcnow()
+        # 先向量化再落 SQLite，理由同 insert()：不落没有向量的事实。
+        if embedding is None:
+            embedding = await self.embed_fact(fact)
         await _run_in_pool(self._upsert_fact_sql_sync, fact)
-        await self._upsert_fact_vec(fact)
+        await self._upsert_fact_vec(fact, embedding=embedding)
         logger.info(f"[coding-store] inserted fact_id={fact.fact_id}")
         logger.debug(
             f"[coding-store] inserted fact_id={fact.fact_id} "
@@ -1574,25 +1591,64 @@ class CodingMemoryStore:
     # VDB 实现
     # ------------------------------------------------------------
 
-    async def _upsert_vec_keys(self, memory: CodingMemory) -> None:
-        """把 task + search_keys 写入 VDB（每行一个 MemoryNode）。"""
-        if self._vec is None:
-            return
-
+    @staticmethod
+    def _vec_key_texts(memory: CodingMemory) -> List[Tuple[str, str]]:
         all_keys: List[Tuple[str, str]] = [("task", memory.task)]
         for k in memory.search_keys:
             if k:
                 all_keys.append(("aspect", k))
+        return all_keys
+
+    async def _embed_vec_keys(
+        self, memory: CodingMemory
+    ) -> Optional[List[List[float]]]:
+        """写入链路用：向量化 task + search_keys，失败抛 CodingWriteError。
+
+        无 VDB 时返回 None（不需要向量）。
+        """
+        if self._vec is None:
+            return None
+        texts = [t for _, t in self._vec_key_texts(memory)]
+        try:
+            embeddings = await self.embed_service.embed_batch(texts)
+        except Exception as e:
+            logger.warning(f"[coding-store] embed_batch failed: {e}")
+            raise CodingWriteError(
+                "EMBEDDING_FAILED",
+                f"coding experience embedding failed: {type(e).__name__}: {e}",
+            ) from e
+        if len(embeddings or []) != len(texts) or not all(embeddings):
+            raise CodingWriteError(
+                "EMBEDDING_FAILED",
+                "coding experience embedding returned no vector",
+            )
+        return embeddings
+
+    async def _upsert_vec_keys(
+        self,
+        memory: CodingMemory,
+        embeddings: Optional[List[List[float]]] = None,
+    ) -> None:
+        """把 task + search_keys 写入 VDB（每行一个 MemoryNode）。
+
+        embeddings 由写入链路预先算好（见 _embed_vec_keys）；不传时现算，
+        失败只记 warning（edit_experience 的手动编辑路径沿用这一行为）。
+        """
+        if self._vec is None:
+            return
+
+        all_keys = self._vec_key_texts(memory)
         if not all_keys:
             return
 
         # batch embed
         texts = [t for _, t in all_keys]
-        try:
-            embeddings = await self.embed_service.embed_batch(texts)
-        except Exception as e:
-            logger.warning(f"[coding-store] embed_batch failed: {e}")
-            return
+        if embeddings is None:
+            try:
+                embeddings = await self.embed_service.embed_batch(texts)
+            except Exception as e:
+                logger.warning(f"[coding-store] embed_batch failed: {e}")
+                return
 
         nodes: List[MemoryNode] = []
         for i, ((kind, text), emb) in enumerate(zip(all_keys, embeddings)):
@@ -1623,7 +1679,34 @@ class CodingMemoryStore:
         except Exception as e:
             logger.warning(f"[coding-store] vdb upsert_batch failed: {e}")
 
-    async def _upsert_fact_vec(self, fact: WorkingFact) -> None:
+    @staticmethod
+    def _fact_vector_text(fact: WorkingFact) -> str:
+        return f"{fact.subject}: {fact.statement}" if fact.subject else fact.statement
+
+    async def embed_fact(self, fact: WorkingFact) -> Optional[List[float]]:
+        """写入链路用：向量化事实检索文本，失败抛 CodingWriteError。
+
+        无事实 VDB 或 statement 为空时返回 None（不需要向量）。
+        """
+        if self._fact_vec is None or not fact.statement:
+            return None
+        try:
+            embedding = await self.embed_service.embed(self._fact_vector_text(fact))
+        except Exception as e:
+            logger.warning(f"[coding-store] fact embed failed: {e}")
+            raise CodingWriteError(
+                "EMBEDDING_FAILED",
+                f"working fact embedding failed: {type(e).__name__}: {e}",
+            ) from e
+        if not embedding:
+            raise CodingWriteError(
+                "EMBEDDING_FAILED", "working fact embedding returned no vector",
+            )
+        return embedding
+
+    async def _upsert_fact_vec(
+        self, fact: WorkingFact, embedding: Optional[List[float]] = None,
+    ) -> None:
         """事实入向量库。一条事实一行，node_id 就是 fact_id。
 
         检索文本是 statement，前面缀上 subject（有的话）。subject 通常已经在
@@ -1634,14 +1717,14 @@ class CodingMemoryStore:
         """
         if self._fact_vec is None or not fact.statement:
             return
-        vector_text = (
-            f"{fact.subject}: {fact.statement}" if fact.subject else fact.statement
-        )
-        try:
-            embedding = await self.embed_service.embed(vector_text)
-        except Exception as e:
-            logger.warning(f"[coding-store] fact embed failed: {e}")
-            return
+        vector_text = self._fact_vector_text(fact)
+        if embedding is None:
+            # edit_fact 的手动编辑路径：现算，失败只记 warning。
+            try:
+                embedding = await self.embed_service.embed(vector_text)
+            except Exception as e:
+                logger.warning(f"[coding-store] fact embed failed: {e}")
+                return
 
         node = MemoryNode(
             node_id=fact.fact_id,

hy_memory/coding/types.py

@@ -25,6 +25,25 @@ FactStatus = Literal["active", "superseded"]
 MAX_FACT_CHAIN_ENTRIES = 8
 
 
+class CodingWriteError(RuntimeError):
+    """working / coding 写入链路里让整次写入失败的模型错误。
+
+    error_code 是稳定失败码，CodingWriter 原样透传为 agent_error_code：
+    - LLM_ERROR          抽取 LLM 调用失败
+    - EMPTY_RESPONSE     抽取 LLM 返回 200 但 content 为空
+    - JSON_PARSE_FAILED  抽取 LLM 的回复解析不出 JSON 对象
+    - EMBEDDING_FAILED   经验 / 事实向量化失败（不落没有向量的节点）
+    - RECONCILE_FAILED   经验 / 事实 reconcile 的模型决策失败；具体原因在 cause
+                         （LLM_UNAVAILABLE / EMPTY_RESPONSE / JSON_PARSE_FAILED），
+                         透传为 reconcile_error_code，与 chat 链路一致
+    """
+
+    def __init__(self, error_code: str, message: str, cause: Optional[str] = None):
+        super().__init__(message)
+        self.error_code = error_code
+        self.cause = cause
+
+
 def _epoch(value: Optional[datetime]) -> Optional[int]:
     """memory_at 对外是秒级 epoch，与 chat 一致。"""
     return int(value.timestamp()) if isinstance(value, datetime) else None

hy_memory/coding/writer.py

@@ -10,8 +10,9 @@ CodingWriter - 写入端协调器
              ├── recent history: 最近 K 个 user-turn（只作上下文）
              ├── new messages: 本次全部 turn（只做单条限长）
              ├── extractor.extract(...)            ← 一次 LLM 产出双层草稿
-             ├── reconciler.reconcile(经验草稿)     ← ADD/UPDATE/DELETE/SKIP
-             ├── fact_reconciler.reconcile(事实草稿) ← INSERT/SUPERSEDE
+             ├── reconciler.plan(经验草稿)          ← ADD/UPDATE/DELETE/SKIP 决策
+             ├── fact_reconciler.plan(事实草稿)      ← INSERT/SUPERSEDE 决策
+             ├── reconciler.apply / fact_reconciler.apply ← 两层决策都成功后才落库
              └── _crosslink(...)                   ← 同批全互链回填
 """
 
@@ -30,7 +31,7 @@ from .judge import classify_messages_is_coding
 from .preproc import has_any_tool_message, prepare_extractor_messages
 from .reconciler import CodingMemoryReconciler
 from .store import CodingMemoryStore
-from .types import FactReconcileOp, ReconcileOp, WorkingFact
+from .types import CodingWriteError, FactReconcileOp, ReconcileOp, WorkingFact
 
 logger = logging.getLogger(__name__)
 
@@ -104,6 +105,13 @@ class CodingWriter:
                 ],
                 "fact_ids": ["..."],         # 这趟真正落库的 fact_id
             }
+
+        模型失败（抽取 LLM 调用失败 / 空回复 / 解析不出）或向量化失败时返回
+        success=False，agent_error_code 为 LLM_ERROR / EMPTY_RESPONSE /
+        JSON_PARSE_FAILED / EMBEDDING_FAILED，error_code=502。经验层 / 事实层
+        reconcile 的模型决策失败时 agent_error_code=RECONCILE_FAILED，原因在
+        reconcile_error_code（LLM_UNAVAILABLE / EMPTY_RESPONSE / JSON_PARSE_FAILED），
+        本次什么都不落库。模型答了但没有值得记的内容仍是 success=True、0 条。
         """
         request_id = request_id or str(uuid.uuid4())
         t0 = time.perf_counter()
@@ -143,6 +151,10 @@ class CodingWriter:
         # 跟库里已有的什么关系是 reconcile 的事。把已有 task 摆到它面前，它会把
         # 一个其实不同的任务往清单里某个措辞上靠，reconciler 随后判成 UPDATE 合并
         # 掉，那个区别就没了——措辞对不上顶多多存一条，措辞被带偏是直接写错。
+        #
+        # 模型失败（LLM 调用失败 / 空回复 / 解析不出）抛 CodingWriteError：整次写入
+        # 报失败、什么都不存，连 trace 也不追加——调用方换个 request_id 重跑时，
+        # 历史窗口里不会多出这段本该是「新消息」的对话。
         try:
             drafts, fact_drafts = await self.extractor.extract(
                 messages,
@@ -156,26 +168,26 @@ class CodingWriter:
                 request_id=request_id,
                 language=language,
             )
-        finally:
-            # 历史服务于下一次 write；即使本次没跨过价值门槛，也不能丢掉上下文。
-            try:
-                await self.store.append_trace(
-                    current_messages,
-                    request_id=request_id,
-                    user_id=user_id,
-                    agent_id=agent_id or "default_agent",
-                    session_id=session_id,
-                    workspace_id=workspace_id,
-                    branch=branch,
-                    source=source,
-                )
-            except Exception as e:
-                logger.warning(f"[coding-write] append trace failed: {e}")
+        except CodingWriteError as e:
+            return self._failure_response(request_id, t0, e)
+
+        trace_kwargs = dict(
+            request_id=request_id,
+            user_id=user_id,
+            agent_id=agent_id or "default_agent",
+            session_id=session_id,
+            workspace_id=workspace_id,
+            branch=branch,
+            source=source,
+        )
 
         if not drafts and not fact_drafts:
+            # 模型答了、只是没有值得记的：正常的空抽取，仍算成功。历史服务于下一次
+            # write；即使本次没跨过价值门槛，也不能丢掉上下文。
             logger.info(
                 f"[coding-write] no drafts produced (value bar); request_id={request_id}"
             )
+            await self._append_trace(current_messages, **trace_kwargs)
             return self._empty_response(request_id, t0)
 
         # extractor 只负责内容；调用来源由 SDK 入口注入，不能交给 LLM 生成。
@@ -183,34 +195,51 @@ class CodingWriter:
             draft.source = source
             draft.memory_at = memory_at
 
-        # 3. 经验层 reconcile + 持久化
-        ops: List[ReconcileOp] = (
-            await self.reconciler.reconcile(
-                drafts,
-                request_id=request_id,
-                user_id=user_id,
-                agent_id=agent_id,
-                session_id=session_id or "",
-                language=language,
-            )
-            if drafts else []
-        )
-
-        # 4. 事实层 reconcile + 持久化（独立链路，不受经验层结果影响）
+        # 3. 两层 reconcile 的模型决策（只检索 + 调 LLM，不落库）
+        # 4. 两层决策都成功后才落库：经验层 apply → 事实层 apply
+        #
+        # 先把所有模型决策做完再写库，任何一层的决策失败（LLM 失败 / 空回复 /
+        # 解析不出 → CodingWriteError(RECONCILE_FAILED)）都发生在落库之前，本次
+        # 写入一条经验 / 事实都没存、也没覆盖旧事实，换个 request_id 重跑即干净。
+        # 两层决策互不依赖（各自检索各自的候选），提前做不改变结果。
+        #
+        # 向量化失败抛 CodingWriteError(EMBEDDING_FAILED)：不落没有向量的节点，
+        # 整次写入报失败。
         facts: List[WorkingFact] = []
         fact_ops: List[FactReconcileOp] = []
-        if fact_drafts:
-            facts, fact_ops = await self.fact_reconciler.reconcile(
-                fact_drafts,
-                user_id=user_id,
-                agent_id=agent_id,
-                session_id=session_id,
-                workspace_id=workspace_id,
-                branch=branch,
-                source=source,
-                memory_at=memory_at,
-                language=language,
+        ops: List[ReconcileOp] = []
+        try:
+            experience_plan = (
+                await self.reconciler.plan(
+                    drafts,
+                    request_id=request_id,
+                    user_id=user_id,
+                    agent_id=agent_id,
+                    session_id=session_id or "",
+                    language=language,
+                )
+                if drafts else None
             )
+            fact_plan = (
+                await self.fact_reconciler.plan(
+                    fact_drafts,
+                    user_id=user_id,
+                    agent_id=agent_id,
+                    session_id=session_id,
+                    workspace_id=workspace_id,
+                    branch=branch,
+                    source=source,
+                    memory_at=memory_at,
+                    language=language,
+                )
+                if fact_drafts else None
+            )
+            if experience_plan is not None:
+                ops = await self.reconciler.apply(experience_plan)
+            if fact_plan is not None:
+                facts, fact_ops = await self.fact_reconciler.apply(fact_plan)
+        except CodingWriteError as e:
+            return self._failure_response(request_id, t0, e)
 
         experience_ids = [op.target_experience_id for op in ops
                           if op.action in ("ADD", "UPDATE") and op.target_experience_id]
@@ -218,6 +247,7 @@ class CodingWriter:
 
         # 5. 同批全互链
         await self._crosslink(experience_ids, facts, user_id=user_id)
+        await self._append_trace(current_messages, **trace_kwargs)
 
         add_cnt = sum(1 for op in ops if op.action == "ADD")
         update_cnt = sum(1 for op in ops if op.action == "UPDATE")
@@ -298,6 +328,41 @@ class CodingWriter:
                         f"[coding-write] crosslink fact {f.fact_id} failed: {e}"
                     )
 
+    async def _append_trace(self, current_messages: List[ChatMessage], **kwargs) -> None:
+        """把本次对话追加进 recent trace（下一次 write 的历史上下文），best-effort。"""
+        try:
+            await self.store.append_trace(current_messages, **kwargs)
+        except Exception as e:
+            logger.warning(f"[coding-write] append trace failed: {e}")
+
+    def _failure_response(
+        self, request_id: str, t0: float, error: CodingWriteError,
+    ) -> Dict[str, Any]:
+        """模型 / 向量化失败：success=False，稳定失败码在 agent_error_code。
+
+        形状与 chat 链路的失败回执一致（error_code=502，error_message 带
+        「[CODE] 」前缀），调用方据 success 判定并重跑。
+        """
+        code = error.error_code
+        cause = getattr(error, "cause", None)
+        message = f"{cause}: {error}" if cause else str(error)
+        logger.warning(
+            f"[coding-write] failed: code={code} request_id={request_id}: {message}"
+        )
+        resp = self._empty_response(request_id, t0)
+        resp.update({
+            "success": False,
+            "error_code": 502,
+            "error_message": f"[{code}] {message}",
+            "agent_status": "failed",
+            "agent_error_code": code,
+            "agent_error": message,
+        })
+        if cause:
+            # 与 chat 链路一致：reconcile 失败的具体原因
+            resp["reconcile_error_code"] = cause
+        return resp
+
     def _empty_response(self, request_id: str, t0: float) -> Dict[str, Any]:
         return {
             "success": True,

hy_memory/config.py

@@ -432,6 +432,14 @@ class RecallConfig:
     retrieval_clauses_require_keyword: bool = None  # env: MEMORY_RETRIEVAL_CLAUSES_REQUIRE_KEYWORD
     retrieval_clauses_min_keyword_score: float = None  # normalized BM25 floor
     supplemental_propositions_enabled: bool = None  # env: MEMORY_SUPPLEMENTAL_PROPOSITIONS_ENABLED
+    # ── Intention（L7）判重 ──
+    # 开启（默认）：召回时同 user+agent+同天 memory_at+同 valid_until 且
+    # cosine≥阈值 的意图视为复本，只返回最早一条，其余异步从 VDB 删除（历史行为）。
+    # 关闭：读侧与写入侧批内都不判重——不隐藏、不丢弃、不删除任何意图。
+    intention_dedup_enabled: bool = None       # env: MEMORY_INTENTION_DEDUP_ENABLED
+    # 读侧意图判重 cosine 阈值。env: MEMORY_INTENTION_DEDUP_THRESHOLD，
+    # 未设置时回退到共享的 MEMORY_DEDUP_THRESHOLD（兼容旧部署），默认 0.95。
+    intention_dedup_threshold: float = None
 
     # 最小分数阈值
     min_score_threshold: float = 0.0
@@ -750,6 +758,15 @@ class RecallConfig:
             self.supplemental_propositions_enabled = _get_env_bool(
                 "MEMORY_SUPPLEMENTAL_PROPOSITIONS_ENABLED", False
             )
+        if self.intention_dedup_enabled is None:
+            self.intention_dedup_enabled = _get_env_bool(
+                "MEMORY_INTENTION_DEDUP_ENABLED", True
+            )
+        if self.intention_dedup_threshold is None:
+            self.intention_dedup_threshold = _get_env_float(
+                "MEMORY_INTENTION_DEDUP_THRESHOLD",
+                _get_env_float("MEMORY_DEDUP_THRESHOLD", 0.95),
+            )
 
 
 @dataclass
@@ -1384,6 +1401,8 @@ class MemoryConfig:
                 "supplemental_propositions_enabled": (
                     self.recall.supplemental_propositions_enabled
                 ),
+                "intention_dedup_enabled": self.recall.intention_dedup_enabled,
+                "intention_dedup_threshold": self.recall.intention_dedup_threshold,
             },
             "pipeline": {
                 "default_version": self.pipeline.default_version,

hy_memory/pipelines/_retrieval/intention.py

@@ -15,6 +15,9 @@ HY Memory - Intention (L7) 召回 + 惰性过期转换 + 复本判定
     → 视为同一个意图的复本（extractor 复读机 / 多 session 重复表达）。
     保留组里 `gmt_created` 最早的（老的先来先得，稳定 id）；
   - **异步删库**：其余复本 fire-and-forget 从 VDB 删除，不影响本次调用 RT。
+  - **开关**：判重受 `MemoryConfig.recall.intention_dedup_enabled`（默认开）与
+    `recall.intention_dedup_threshold` 控制，由 reader 按 client 配置传入。
+    关闭时完全跳过判重：不隐藏、不删除任何意图（写入侧批内判重同样跳过）。
 
 Q: 为什么要看 memory_at 和 valid_until？
 A: 意图是 point-in-time 信号。同一句"我周五要开会"，如果一条 memory_at 在
@@ -38,8 +41,14 @@ from ...models.memory import MemoryLayer, MemoryStatus
 logger = logging.getLogger(__name__)
 
 
-def _get_dedup_threshold() -> float:
-    """去重 cosine 阈值：沿用 dedup 内核的 MEMORY_DEDUP_THRESHOLD，默认 0.95。"""
+def _get_dedup_threshold(configured: Optional[float] = None) -> float:
+    """去重 cosine 阈值：优先用 client 配置；否则（或配置非法）沿用 dedup 内核的
+    MEMORY_DEDUP_THRESHOLD，默认 0.95。"""
+    try:
+        if configured is not None:
+            return float(configured)
+    except (TypeError, ValueError):
+        logger.warning(f"[intention] invalid dedup threshold: {configured!r}")
     try:
         return float(os.environ.get("MEMORY_DEDUP_THRESHOLD", 0.95))
     except (TypeError, ValueError):
@@ -244,6 +253,8 @@ async def recall_intentions(
     stats_out: Optional[Dict[str, Any]] = None,
     include_sources: Optional[List[str]] = None,
     exclude_sources: Optional[List[str]] = None,
+    dedup_enabled: bool = True,
+    dedup_threshold: Optional[float] = None,
 ) -> List[Dict[str, Any]]:
     """
     召回未过期的 L7_INTENTION 节点（VDB），惰性过期转 L2_FACT，判重并异步删复本。
@@ -260,6 +271,11 @@ async def recall_intentions(
         now: 当前时间（默认 datetime.now()，测试可注入）
         stats_out: 可选 dict，本函数把分段耗时与数量**原地回填**进去，供调用方落
             READ_INTENTION pipeline log。传 None 则完全不统计（零开销）。
+        dedup_enabled: 是否执行读侧判重（及复本异步删库）。False 时跳过判重，
+            所有未过期意图原样返回，不删除任何节点。默认 True（历史行为）。
+        dedup_threshold: 判重 cosine 阈值。None 时回退到 env
+            MEMORY_DEDUP_THRESHOLD（默认 0.95），兼容直接调用本函数的旧代码；
+            reader 总是传入 `recall.intention_dedup_threshold`。
 
     Returns:
         [{"node_id", "score", "node", "layer": "l7_intention", "source": "vdb_intention"}, ...]
@@ -272,7 +288,7 @@ async def recall_intentions(
     埋点字段（回填进 stats_out）:
       耗时(ms): vdb_search_ms / expire_ms / backfill_embed_ms / dedup_ms / total_ms
       数量: fetched / expired / survivors / dedup_dropped / returned
-      配置: fetch_limit / out_limit / dedup_threshold
+      配置: fetch_limit / out_limit / dedup_enabled / dedup_threshold
       说明: expire_ms、backfill_embed_ms 只有真的发生了对应操作才非 0，
             借此可判断慢在 VDB 检索、逐条过期转换、补拉向量还是判重计算。
     """
@@ -358,7 +374,7 @@ async def recall_intentions(
     _t = time.perf_counter()
     _backfilled = 0
     _missing_cnt = 0
-    if survivors:
+    if survivors and dedup_enabled:  # 补拉只为判重；关闭时无需这次 VDB 读
         missing_ids = [
             h.get("node_id") for h in survivors
             if h.get("node_id") and not getattr(h.get("node"), "embedding", None)
@@ -391,18 +407,23 @@ async def recall_intentions(
     )
 
     # 2. 判重：同 user + 同天 memory_at + valid_until 同日 + cosine≥threshold
+    #    dedup_enabled=False → 完全跳过：不隐藏、不删除。
     _t = time.perf_counter()
-    threshold = _get_dedup_threshold()
-    try:
-        kept, delete_ids = _partition_duplicates(survivors, threshold)
-    except Exception as e:
-        # 任何 dedup 异常 → 降级为不去重（返回全部 survivors 截断 limit）
-        logger.warning(f"[intention] dedup partition failed, degrade to raw: {e}")
+    threshold = _get_dedup_threshold(dedup_threshold)
+    if dedup_enabled:
+        try:
+            kept, delete_ids = _partition_duplicates(survivors, threshold)
+        except Exception as e:
+            # 任何 dedup 异常 → 降级为不去重（返回全部 survivors 截断 limit）
+            logger.warning(f"[intention] dedup partition failed, degrade to raw: {e}")
+            kept, delete_ids = survivors, []
+    else:
         kept, delete_ids = survivors, []
     # 纯 CPU（cosine 两两比较）；survivors 多时可能显著
     _stat(
         dedup_ms=round((time.perf_counter() - _t) * 1000, 2),
         dedup_dropped=len(delete_ids),
+        dedup_enabled=bool(dedup_enabled),
         dedup_threshold=threshold,
     )
 

hy_memory/pipelines/reader_base.py

@@ -1856,6 +1856,12 @@ class BaseReadPipeline(ReadPipeline):
                     stats_out=_intent_stats,
                     include_sources=request.include_sources,
                     exclude_sources=request.exclude_sources,
+                    dedup_enabled=bool(getattr(
+                        self.config.recall, "intention_dedup_enabled", True
+                    )),
+                    dedup_threshold=getattr(
+                        self.config.recall, "intention_dedup_threshold", None
+                    ),
                 )
                 await trace_log.log_intention(
                     stats=_intent_stats,

hy_memory/pipelines/writer.py

@@ -73,6 +73,19 @@ def _write_apply_verify_enabled() -> bool:
 _RECONCILE_LOOP_USER_LOCKS = weakref.WeakKeyDictionary()
 
 
+class ReconcileFailure(str):
+    """reconcile 失败时 `_reconcile_and_store` 返回的 error：仍是错误信息字符串，
+    另带稳定的失败码 `code`（LLM_UNAVAILABLE / EMPTY_RESPONSE / JSON_PARSE_FAILED /
+    RECONCILE_EXCEPTION），供 writer 透传给调用方。"""
+
+    code: str = "RECONCILE_FAILED"
+
+    def __new__(cls, message: str, code: str = "RECONCILE_FAILED"):
+        obj = super().__new__(cls, message)
+        obj.code = code
+        return obj
+
+
 def _reconcile_user_lock(user_id: str) -> asyncio.Lock:
     loop = asyncio.get_running_loop()
     locks = _RECONCILE_LOOP_USER_LOCKS.get(loop)
@@ -635,6 +648,7 @@ class MemoryWriter(WritePipeline):
         不查 VDB、不做"新写入 vs 库里已有"的对比，避免给 VDB 增加读压力。
         库内存量污染由 recall 侧异步删除逐步清理。best-effort：任何异常都
         回退到"不判重、全写入"，绝不影响 upsert 主流程。
+        `recall.intention_dedup_enabled=False` 时跳过批内判重，全部写入。
         """
         if not intentions:
             return []
@@ -660,7 +674,11 @@ class MemoryWriter(WritePipeline):
         # ============ 批内 dedup（不查 VDB，只对本批 intentions 互斥判重） ============
         keep_mask: List[bool] = [True] * len(intentions)
         try:
-            dropped = self._intention_batch_dedup(intentions, embeddings)
+            dropped = (
+                self._intention_batch_dedup(intentions, embeddings)
+                if getattr(self.config.recall, "intention_dedup_enabled", True)
+                else []
+            )
             for i in dropped:
                 if 0 <= i < len(keep_mask):
                     keep_mask[i] = False
@@ -1257,15 +1275,6 @@ class MemoryWriter(WritePipeline):
             recon_tokens 含 prompt/completion/total（reconcile 链路 LLM 消耗）
         """
         stored_ids: List[str] = []
-        # Episode：本次写入归属的内部会话 id（跨 write 把"一件事"归到一起）。
-        # 只数 user 侧记忆（与 rolling summary 只数 pending_user_count 一致）——
-        # agent 侧记忆若参与计数会把 episode 提前撑到上限、切得过碎，白付摘要的 token。
-        episode_id = await self._resolve_episode_id(
-            request, _count_user_owned(new_memories_meta)
-        )
-        session_episode_id = self._session_episode_id(request)
-        if session_episode_id:
-            episode_id = session_episode_id
         # 关系图用：收集本次落库的 (node, op)，供 graph 投影建边。
         # 收 op 是为了拿 op.related（LLM 标注的 typed 关系）。
         graph_payload: List[Tuple[Any, Any]] = []
@@ -1292,7 +1301,32 @@ class MemoryWriter(WritePipeline):
         )
 
         if not recon_result.success:
-            return [], recon_result.error, {"add": 0, "supersede": 0, "update": 0, "total": 0}, {"prompt": 0, "completion": 0, "total": 0}
+            # reconcile 失败：本次一条新记忆都不落库（不做 ADD-all 兜底），由调用方重跑。
+            # episode 状态也还没推进，重跑不会把同一批记忆重复计数。
+            error = ReconcileFailure(
+                recon_result.error or "reconcile failed",
+                code=recon_result.error_code or "RECONCILE_FAILED",
+            )
+            logger.warning(
+                f"TRACE_PERF [{req_id}] S1_RECONCILE_FAILED "
+                f"code={error.code} candidates={len(new_memory_texts)} stored=0"
+            )
+            return [], error, {"add": 0, "supersede": 0, "update": 0, "total": 0}, {
+                "prompt": recon_result.prompt_tokens,
+                "completion": recon_result.completion_tokens,
+                "total": recon_result.total_tokens,
+            }
+
+        # Episode：本次写入归属的内部会话 id（跨 write 把"一件事"归到一起）。
+        # 只数 user 侧记忆（与 rolling summary 只数 pending_user_count 一致）——
+        # agent 侧记忆若参与计数会把 episode 提前撑到上限、切得过碎，白付摘要的 token。
+        # 放在 reconcile 成功之后：失败的写入不能推进 episode 计数。
+        episode_id = await self._resolve_episode_id(
+            request, _count_user_owned(new_memories_meta)
+        )
+        session_episode_id = self._session_episode_id(request)
+        if session_episode_id:
+            episode_id = session_episode_id
 
         # 分类统计
         _op_counts = {}
@@ -1303,16 +1337,7 @@ class MemoryWriter(WritePipeline):
         logger.info(
             f"TRACE_PERF [{req_id}] S1_RECONCILE_DONE "
             f"ops={len(recon_result.ops)} candidates={len(new_memory_texts)} | {_op_counts_str}"
-            + (f" | DEGRADED({recon_result.degraded_reason})"
-               if getattr(recon_result, "degraded", False) else "")
         )
-        if getattr(recon_result, "degraded", False):
-            # 走了 ADD-all 兜底：内容保住了，但没做去重/演化判定。必须可观测，
-            # 否则线上只会看到"记忆变多了"而不知道为什么。
-            logger.warning(
-                f"[write] reconcile degraded → ADD-all "
-                f"({recon_result.degraded_reason}), {len(recon_result.ops)} memories stored as-is"
-            )
         # 逐条 op 详情由 reconciler 的 "[reconciler] ops detail" 单条 JSON list 输出，
         # 这里不再逐条打印（避免重复刷屏）。
 
@@ -2502,12 +2527,10 @@ class MemoryWriter(WritePipeline):
             response.extra["extract_tokens"] = {"prompt": 0, "completion": 0, "total": 0}
 
             if recon_error is not None:
-                response.success = False
-                response.error_code = 502
-                response.error_message = f"[RECONCILE_FAILED] {recon_error}"
-                response.extra["agent_status"] = "failed"
-                response.extra["agent_error"] = recon_error
-                response.extra["agent_nodes"] = 0
+                # 与 write() 一致：reconcile 失败不落任何记忆，报失败供调用方重跑。
+                self._mark_reconcile_failure(response, recon_error)
+                response.extra["agent_mode"] = "extracted"
+                logger.warning(f"[write_extracted] reconcile failed: {recon_error}")
                 return response
 
             response.success = True
@@ -3526,12 +3549,11 @@ class MemoryWriter(WritePipeline):
                 response.extra["reconcile_ops"] = ops_counts
                 response.extra["reconcile_tokens"] = recon_tokens
                 if recon_error is not None:
+                    # stored_ids 为空：reconcile 失败时一条新记忆都不落库，write()
+                    # 随后回滚 L1_RAW（retry_safe=True），换个 request_id 重跑即可。
                     response.extra["agent_stored_ids"] = stored_ids
-                    self._mark_agent_failure(
-                        response,
-                        error_code="RECONCILE_FAILED",
-                        error_message=recon_error,
-                        agent_nodes=len(stored_ids),
+                    self._mark_reconcile_failure(
+                        response, recon_error, agent_nodes=len(stored_ids),
                     )
                     logger.warning(f"[write] reconcile failed: {recon_error}")
                     return
@@ -3654,6 +3676,29 @@ class MemoryWriter(WritePipeline):
         response.error_code = 502
         response.error_message = f"[{code}] {message}"
 
+    @classmethod
+    def _mark_reconcile_failure(
+        cls,
+        response: WriteResponse,
+        recon_error: str,
+        *,
+        agent_nodes: int = 0,
+    ) -> None:
+        """reconcile 失败：agent_error_code 恒为 RECONCILE_FAILED，具体原因
+        （LLM_UNAVAILABLE / EMPTY_RESPONSE / JSON_PARSE_FAILED / RECONCILE_EXCEPTION）
+        放在 reconcile_error_code。"""
+        reason = getattr(recon_error, "code", "") or "RECONCILE_FAILED"
+        response.extra["reconcile_error_code"] = reason
+        cls._mark_agent_failure(
+            response,
+            error_code="RECONCILE_FAILED",
+            error_message=(
+                f"{reason}: {recon_error}"
+                if reason != "RECONCILE_FAILED" else str(recon_error)
+            ),
+            agent_nodes=agent_nodes,
+        )
+
     async def _handle_agent_failure(self, request, response, agent_result, tracer_span, extract_timing: Optional[Dict[str, Any]] = None) -> None:
         """处理 agent extract 失败的情况。"""
         if agent_result is None:

memhub/MEMORY.md

@@ -137,6 +137,15 @@ memhub profile
 `user-profile` / `memhub profile` 调用 SDK `get_user_profile()`，返回组装后的
 用户长期画像，不通过普通 Search 拼装。
 
+读接口都回显 `user_id`（实际读的用户，未指定时为 `local`）：
+`GET /api/v2/memory-library`、`/memory-library/layers`、`/user-profile`、
+`/user-profile/versions`、`/home-summary`、`/memories/graph`、`/raw`，
+`POST /api/v2/context/search`、`/api/v1/recall`、`/api/v2/memories/ask`；
+`/memories/ask/stream` 写在第一个 `recall` 事件上。
+`DELETE /api/v2/memories/{id}` 只在删掉调用者自己的记忆时回 204；另一个用户的
+记忆和不存在的 ID 一律回 404 `memory_not_found`（不暴露是否存在），调用方按
+「已不存在」处理。
+
 返回值：
 
 ```python

memhub/README.md

@@ -18,13 +18,13 @@ If you run into a problem, please open an Issue with the version, platform,repro
 
 ## 发行与平台合同
 
-源码当前固定使用公开 PyPI 正式版 `hy-memory==2.0.9`。MemHub 源码版本为 `1.0.5`
-（build 36），GitHub 仓库为
+源码当前固定使用公开 PyPI 正式版 `hy-memory==2.0.14`。MemHub 源码版本为 `1.0.6`
+（build 41），GitHub 仓库为
 [`Tencent-Hunyuan/Hy-Memory`](https://github.com/Tencent-Hunyuan/Hy-Memory)，npm 包名为
 `memhub-cli`。当前代码架构见
 [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md)。
 
-`v1.0.5` 的发行目标是 Linux x64/arm64 Runtime 与 macOS arm64 App 和 Runtime。
+`v1.0.6` 的发行目标是 Linux x64/arm64 Runtime 与 macOS arm64 App 和 Runtime。
 Linux 制品由 GitHub Actions 在原生架构 runner 上构建并完成生命周期验收；macOS
 制品由发行流水线完成 Developer ID 签名、公证和验收后手动上传。Windows 不支持。
 只有同时出现在 GitHub Release 与 `release-manifest.json` 中、且通过公开校验的制品才属于
@@ -118,7 +118,7 @@ MemHub 的 SQLite 数据默认位于 `~/.one-memory`，不在 npm 包或 Runtime
 
 ## Hy Memory
 
-SDK 依赖固定为公开 PyPI 正式版 `hy-memory==2.0.9`。SDK 配置、权限边界及 search
+SDK 依赖固定为公开 PyPI 正式版 `hy-memory==2.0.14`。SDK 配置、权限边界及 search
 返回格式见 [`MEMORY.md`](MEMORY.md)。HY search 返回的 `content` 已包含 SDK 统一生成的
 逻辑时间和演化上下文；调用方不应再次转换时间戳或重复拼接 `When`。
 

memhub/SBOM.spdx.json

@@ -2352,7 +2352,7 @@
     {
       "SPDXID": "SPDXRef-Package-hy-memory",
       "name": "hy-memory",
-      "versionInfo": "2.0.9",
+      "versionInfo": "2.0.14",
       "downloadLocation": "NOASSERTION",
       "filesAnalyzed": false,
       "licenseConcluded": "Apache-2.0",

memhub/THIRD_PARTY_NOTICES.md

@@ -9,7 +9,7 @@ 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.9
+## hy-memory 2.0.14
 
 License: Apache-2.0
 

memhub/apps/cli/package.json

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

memhub/apps/cli/src/cli.ts

@@ -122,6 +122,14 @@ import {
   doctorExitCode,
   renderDoctorText,
 } from "./doctor-report.js";
+import {
+  activateWithEmbeddingSwitch,
+  cleanupSpace,
+  listSpaces,
+  type SwitchIo,
+  switchCancel,
+  switchStatus,
+} from "./embedding-switch-flow.js";
 import {
   EXIT_FAILED,
   EXIT_OK,
@@ -195,6 +203,13 @@ import {
   renderFeaturesText,
   runFeaturesCommand,
 } from "./memory-features-flow.js";
+import {
+  type LanguageDocument,
+  languageExitCode,
+  parseLanguageCommand,
+  renderLanguageText,
+  runLanguageCommand,
+} from "./memory-language-flow.js";
 import {
   type EvolveDocument,
   evolveExitCode,
@@ -248,7 +263,6 @@ import {
   renderModelReportText,
 } from "./model-report.js";
 import {
-  activateModelProfile,
   editModelProfile,
   type ModelWriteDocument,
   modelWriteExitCode,
@@ -1703,6 +1717,18 @@ async function runCommand(
       );
       if (apiKey === undefined) return usage();
     }
+    if (
+      parsed.kind === "spaces" &&
+      parsed.cleanup !== undefined &&
+      !parsed.confirmed
+    ) {
+      return emitConfirmPreview(asJson, {
+        command: "models spaces",
+        target: parsed.cleanup,
+        effect: `删除已停用的向量空间 ${parsed.cleanup}（不可恢复；正在使用的空间不能删除）`,
+        retry: `${PRODUCT} models spaces --cleanup ${parsed.cleanup} --yes`,
+      });
+    }
     if (parsed.kind === "remove" && !parsed.confirmed) {
       return emitConfirmPreview(asJson, {
         command: "models remove",
@@ -1725,6 +1751,50 @@ async function runCommand(
       return connected.exitCode;
     }
     const { reader, operations } = connected;
+    // Ctrl-C while following a switch stops watching, never the switch.
+    const interrupt = new AbortController();
+    const switchIo: SwitchIo = {
+      reader,
+      operations,
+      emit: (text) => {
+        emit(text);
+      },
+      asJson,
+      interactive:
+        !asJson && (controls.stdinIsTTY ?? process.stdin.isTTY) === true,
+      confirm: async (question) => {
+        const prompter =
+          controls.wizardPrompter ?? (await createTerminalPrompter());
+        try {
+          return /^(y|yes)$/i.test((await prompter.ask(question)).trim());
+        } finally {
+          if ("close" in prompter && typeof prompter.close === "function") {
+            prompter.close();
+          }
+        }
+      },
+      ...(controls.watchWait ? { wait: controls.watchWait } : {}),
+      signal: controls.watchSignal ?? interrupt.signal,
+    };
+    const withInterrupt = async (run: () => Promise<number>) => {
+      const onInterrupt = () => interrupt.abort();
+      process.once("SIGINT", onInterrupt);
+      try {
+        return await run();
+      } finally {
+        process.removeListener("SIGINT", onInterrupt);
+      }
+    };
+    if (parsed.kind === "switch") {
+      return parsed.action === "status"
+        ? await switchStatus(switchIo)
+        : await switchCancel(switchIo);
+    }
+    if (parsed.kind === "spaces") {
+      return parsed.cleanup === undefined
+        ? await listSpaces(switchIo)
+        : await cleanupSpace(parsed.cleanup, switchIo);
+    }
     if (parsed.kind === "add") {
       const created = await createModelProfile(
         config,
@@ -1739,33 +1809,66 @@ async function runCommand(
         emitFlowDocument(created, asJson);
         return flowExitCode(created);
       }
-      const activated = await activateModelProfile(
-        String(created.receipt.profile_id),
+      // Core activates only a probed profile: probe first, then the same
+      // path as `models activate`, so an embedding change shows its plan.
+      const profileId = String(created.receipt.profile_id);
+      const probe = await probeUntilSettled(
+        reader,
         operations,
+        profileId,
+        controls.watchWait,
       );
-      const document = {
-        ...created,
-        activation:
-          activated.state === "committed"
-            ? { state: "committed" }
-            : { state: activated.state, code: activated.code },
-      };
+      const probed =
+        probe.state === "completed" &&
+        Boolean(
+          (
+            (probe.receipt.result as Record<string, unknown> | undefined)
+              ?.capabilities as Record<string, unknown> | undefined
+          )?.embedding_available,
+        );
       emit(
         asJson
-          ? `${JSON.stringify(document)}\n`
+          ? `${JSON.stringify({
+              ...created,
+              probe: {
+                state: probe.state,
+                ...("operation_id" in probe && probe.operation_id
+                  ? { operation_id: probe.operation_id }
+                  : {}),
+                ...("code" in probe ? { code: probe.code } : {}),
+              },
+            })}\n`
           : `${renderFlowText(created)}${
-              activated.state === "committed"
-                ? "已设为当前使用的模型配置。\n"
-                : `设为当前使用未完成：${activated.state}（${activated.code}）\n`
+              probed
+                ? "探测通过。\n"
+                : `探测未通过（${"code" in probe ? probe.code : probe.state}），没有设为当前使用；用 ${PRODUCT} models test ${profileId} 查看原因。\n`
             }`,
       );
-      return activated.state === "committed" ? EXIT_OK : EXIT_FAILED;
+      if (!probed) return EXIT_FAILED;
+      return await withInterrupt(() =>
+        activateWithEmbeddingSwitch(
+          profileId,
+          { confirmed: parsed.confirmed, follow: parsed.follow },
+          switchIo,
+        ),
+      );
     }
-    if (parsed.kind === "edit" || parsed.kind === "activate") {
-      const document =
-        parsed.kind === "edit"
-          ? await editModelProfile(parsed.profileId, config, apiKey, operations)
-          : await activateModelProfile(parsed.profileId, operations);
+    if (parsed.kind === "activate") {
+      return await withInterrupt(() =>
+        activateWithEmbeddingSwitch(
+          parsed.profileId,
+          { confirmed: parsed.confirmed, follow: parsed.follow },
+          switchIo,
+        ),
+      );
+    }
+    if (parsed.kind === "edit") {
+      const document = await editModelProfile(
+        parsed.profileId,
+        config,
+        apiKey,
+        operations,
+      );
       emitModelWriteDocument(document, asJson);
       return modelWriteExitCode(document);
     }
@@ -1835,7 +1938,7 @@ async function runCommand(
       return reject(
         descriptor,
         asJson,
-        "--user-id 和 --root 只能用于接入单个 hermes 来源（Hermes profile），用户 ID 只能是 1–64 位字母、数字、点、下划线或连字符。",
+        "--user-id 和 --root 只能用于接入单个 hermes 来源（Hermes profile），用户 ID 只能是 1–64 位字母、数字、点、下划线或连字符。用户 ID 不必等于 Hermes profile 名，例如 --user-id wife-work --root ~/.hermes/profiles/wife:work。",
       );
     }
     if (!parsed) return usage();
@@ -2225,29 +2328,41 @@ async function runCommand(
               ...userIdParameters(userId),
             }),
           );
+    // A delete answered 404 `memory_not_found` is already gone (deleted
+    // before, or never this user's): what was asked for holds, so it exits 0
+    // as committed and says so, instead of failing a retry or a double run.
+    const alreadyGone =
+      parsed.kind === "delete" &&
+      outcome.state === "rejected" &&
+      outcome.code === "memory_not_found";
+    const state = alreadyGone ? "committed" : outcome.state;
     const document = {
       schema_version: 2,
       product: PRODUCT,
       command: `memories ${parsed.kind}`,
-      state: outcome.state,
+      state,
       operation: parsed.kind,
       memory_id: parsed.memoryId,
-      ...(outcome.state === "committed"
-        ? parsed.kind === "update"
-          ? { result: outcome.data }
-          : {}
-        : { code: outcome.code }),
+      ...(alreadyGone
+        ? { already_gone: true }
+        : outcome.state === "committed"
+          ? parsed.kind === "update"
+            ? { result: outcome.data }
+            : {}
+          : { code: outcome.code }),
     };
     emit(
       asJson
         ? `${JSON.stringify(document)}\n`
-        : outcome.state === "committed"
-          ? `已${parsed.kind === "update" ? "更新" : "删除"}记忆 ${parsed.memoryId}\n`
-          : outcome.code === "memory_id_ambiguous"
-            ? "这个 ID 同时存在于多个场景；请加 --kind（以及 --variant）指明是哪一条。\n"
-            : `操作失败：${outcome.code}\n`,
+        : alreadyGone
+          ? `未找到记忆 ${parsed.memoryId}（可能已删除），无需再删。\n`
+          : outcome.state === "committed"
+            ? `已${parsed.kind === "update" ? "更新" : "删除"}记忆 ${parsed.memoryId}\n`
+            : outcome.code === "memory_id_ambiguous"
+              ? "这个 ID 同时存在于多个场景；请加 --kind（以及 --variant）指明是哪一条。\n"
+              : `操作失败：${outcome.code}\n`,
     );
-    return outcome.state === "committed" ? EXIT_OK : EXIT_FAILED;
+    return state === "committed" ? EXIT_OK : EXIT_FAILED;
   }
   if (
     named === "settings" &&
@@ -2283,6 +2398,40 @@ async function runCommand(
     );
     return featuresExitCode(document);
   }
+  if (
+    named === "settings" &&
+    arguments_.slice(1).find((value) => value !== "--json") === "language"
+  ) {
+    const parsed = parseLanguageCommand(
+      arguments_
+        .slice(1)
+        .filter((value, index, all) => index !== all.indexOf("language")),
+    );
+    if (!parsed) return usage();
+    const connected = await connectRuntime(environment);
+    if (!connected.ok) {
+      const document: LanguageDocument = {
+        schema_version: 1,
+        product: PRODUCT,
+        command: "settings language",
+        state: "unavailable",
+        code: connected.code,
+      };
+      emit(
+        asJson ? `${JSON.stringify(document)}\n` : renderLanguageText(document),
+      );
+      return connected.exitCode;
+    }
+    const document = await runLanguageCommand(
+      parsed,
+      connected.reader,
+      connected.operations,
+    );
+    emit(
+      asJson ? `${JSON.stringify(document)}\n` : renderLanguageText(document),
+    );
+    return languageExitCode(document);
+  }
   if (named === "settings") {
     const parsed = parseSettingsCommand(arguments_.slice(1));
     if (!parsed) return usage();
@@ -4234,6 +4383,10 @@ function renderWriteReceiptText(receipt: MemoryWriteReceipt): string {
     ...(receipt.memory_ids && receipt.memory_ids.length > 0
       ? [`memory_ids: ${receipt.memory_ids.join(",")}`]
       : []),
+    ...(receipt.error_code ? [`error_code: ${receipt.error_code}`] : []),
+    ...(receipt.next_retry_at
+      ? [`next_retry_at: ${receipt.next_retry_at}`]
+      : []),
     "",
   ].join("\n");
 }
@@ -5289,6 +5442,8 @@ type ModelsCommand =
       configFile: string;
       apiKeyFile?: string;
       activate: boolean;
+      confirmed: boolean;
+      follow?: boolean;
     }
   | {
       kind: "edit";
@@ -5296,7 +5451,14 @@ type ModelsCommand =
       configFile: string;
       apiKeyFile?: string;
     }
-  | { kind: "activate"; profileId: string }
+  | {
+      kind: "activate";
+      profileId: string;
+      confirmed: boolean;
+      follow?: boolean;
+    }
+  | { kind: "switch"; action: "status" | "cancel" }
+  | { kind: "spaces"; cleanup?: string; confirmed: boolean }
   | { kind: "test"; profileId: string }
   | { kind: "receipt"; operationId: string }
   | { kind: "remove"; profileId: string; confirmed: boolean };
@@ -5337,16 +5499,46 @@ function parseModelsCommand(rest: readonly string[]): ModelsCommand | null {
     const flags = readFlags(
       tokens.slice(1),
       ["--config-file", "--api-key-file"],
-      ["--activate"],
+      ["--activate", "--yes", "--wait", "--no-wait"],
     );
     const configFile = flags?.values.get("--config-file");
     if (!flags || configFile === undefined) return null;
+    const follow = followFlag(flags.switches);
+    if (follow === null) return null;
+    const activate = flags.switches.has("--activate");
+    // The switch flags only mean something when the add also activates.
+    if (
+      !activate &&
+      ["--yes", "--wait", "--no-wait"].some((flag) => flags.switches.has(flag))
+    ) {
+      return null;
+    }
     const apiKeyFile = flags.values.get("--api-key-file");
     return {
       kind: "add",
       configFile,
       ...(apiKeyFile === undefined ? {} : { apiKeyFile }),
-      activate: flags.switches.has("--activate"),
+      activate,
+      confirmed: flags.switches.has("--yes"),
+      ...(follow === undefined ? {} : { follow }),
+    };
+  }
+  if (action === "switch") {
+    if (tokens.length !== 2 || (target !== "status" && target !== "cancel")) {
+      return null;
+    }
+    return { kind: "switch", action: target };
+  }
+  if (action === "spaces") {
+    const flags = readFlags(tokens.slice(1), ["--cleanup"], ["--yes"]);
+    if (!flags) return null;
+    const cleanup = flags.values.get("--cleanup");
+    if (cleanup === undefined && flags.switches.has("--yes")) return null;
+    if (cleanup !== undefined && !OPERATION_ID.test(cleanup)) return null;
+    return {
+      kind: "spaces",
+      ...(cleanup === undefined ? {} : { cleanup }),
+      confirmed: flags.switches.has("--yes"),
     };
   }
   if (target === undefined || !OPERATION_ID.test(target)) return null;
@@ -5367,8 +5559,21 @@ function parseModelsCommand(rest: readonly string[]): ModelsCommand | null {
     };
   }
   if (action === "activate") {
-    const flags = readFlags(tokens.slice(2), [], ["--confirm", "--yes"]);
-    return flags ? { kind: "activate", profileId: target } : null;
+    const flags = readFlags(
+      tokens.slice(2),
+      [],
+      ["--confirm", "--yes", "--wait", "--no-wait"],
+    );
+    if (!flags) return null;
+    const follow = followFlag(flags.switches);
+    if (follow === null) return null;
+    return {
+      kind: "activate",
+      profileId: target,
+      // `--confirm` stays the hidden alias of `--yes`.
+      confirmed: flags.switches.has("--yes") || flags.switches.has("--confirm"),
+      ...(follow === undefined ? {} : { follow }),
+    };
   }
   if (action === "test") {
     return tokens.length === 2 ? { kind: "test", profileId: target } : null;
@@ -5391,6 +5596,35 @@ function parseModelsCommand(rest: readonly string[]): ModelsCommand | null {
   return null;
 }
 
+/** `--wait` / `--no-wait`: undefined when neither, null when both. */
+function followFlag(switches: ReadonlySet<string>): boolean | undefined | null {
+  const wait = switches.has("--wait");
+  const noWait = switches.has("--no-wait");
+  if (wait && noWait) return null;
+  return wait ? true : noWait ? false : undefined;
+}
+
+/** Start a probe and read its receipt until it settles (about two minutes). */
+async function probeUntilSettled(
+  reader: CoreReader,
+  operations: CoreOperations,
+  profileId: string,
+  wait?: (milliseconds: number, signal: AbortSignal) => Promise<void>,
+): Promise<ModelProbeFlowDocument> {
+  let document = await startModelProbe(reader, operations, profileId);
+  const pause =
+    wait ??
+    ((milliseconds: number) =>
+      new Promise<void>((resolve) => setTimeout(resolve, milliseconds)));
+  const signal = new AbortController().signal;
+  for (let attempt = 0; attempt < 120; attempt += 1) {
+    if (document.state !== "pending" || !document.operation_id) break;
+    await pause(1_000, signal);
+    document = await readModelProbeReceipt(reader, document.operation_id);
+  }
+  return document;
+}
+
 type SourcesCommand =
   | {
       kind: "ids";

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

@@ -258,7 +258,7 @@ export const COMMANDS: readonly CommandDescriptor[] = [
   {
     name: "sources",
     summary:
-      "列出来源，直接接入来源，或按 request id 查接入回执。connect 不加 --import 只授权（处理保持冻结：不导入历史、不扫描新会话）；加 --import 同时导入历史并开启持续同步，返回 request id。目录来自环境变量覆盖的来源必须加 --confirm-overrides。Hermes 的每个 profile 是一个独立用户：用 --user-id 和 --root 接入，授权并导入历史（会自动排除 ~/.hermes/profiles/**，各用户互不读取）。",
+      "列出来源，直接接入来源，或按 request id 查接入回执。connect 不加 --import 只授权（处理保持冻结：不导入历史、不扫描新会话）；加 --import 同时导入历史并开启持续同步，返回 request id。目录来自环境变量覆盖的来源必须加 --confirm-overrides。Hermes 的每个 profile 是一个独立用户：用 --user-id 和 --root 接入，授权并导入历史（任何层级的 profiles/ 目录都会被排除，各用户互不读取）。--root 不能是 profiles 目录本身，也不能与另一个用户的 Hermes 目录相同或互相包含（~/.hermes 与 ~/.hermes/profiles/<name> 除外）。",
     usage:
       "memhub sources list [--json]\n            memhub sources connect <id> [<id> ...] [--import] [--confirm-overrides] [--request-id <uuid>] [--json]\n            memhub sources connect hermes --user-id <id> --root <path> [--import] [--request-id <uuid>] [--json]\n            memhub sources connect --all-detected [--import] [--confirm-overrides] [--json]\n            memhub sources receipt <request-id> [--json]",
     options: [
@@ -270,7 +270,7 @@ export const COMMANDS: readonly CommandDescriptor[] = [
       {
         flag: "--user-id <id>",
         summary:
-          "只用于 hermes：这条接入属于哪个用户（默认 local）。和 --root 一起接入一个 Hermes profile，例如 --user-id wife --root ~/.hermes/profiles/wife；其他来源只能是 local。",
+          "只用于 hermes：这条接入属于哪个用户（默认 local）。和 --root 一起接入一个 Hermes profile，例如 --user-id wife --root ~/.hermes/profiles/wife；用户 ID 不必等于 profile 名，例如 --user-id wife-work --root ~/.hermes/profiles/wife:work。其他来源只能是 local。",
       },
       {
         flag: "--root <path>",
@@ -361,9 +361,9 @@ export const COMMANDS: readonly CommandDescriptor[] = [
   {
     name: "models",
     summary:
-      "管理生成模型配置。add/test 直接提交并返回操作 ID（异步，用 receipt 查结果）；edit/activate 直接执行；remove 不可逆，需 --yes。<profile-id>/<operation-id> 都是 UUID；脚本模式的凭据只从受控文件读取。",
+      "管理生成模型配置。add/test 直接提交并返回操作 ID（异步，用 receipt 查结果）；edit 直接执行；activate 换了向量模型（模型或维度）时先显示切换计划，需 --yes 确认后重新生成全部向量，switch 查看或取消、spaces 查看或清理旧向量数据；remove 不可逆，需 --yes。<profile-id>/<operation-id> 都是 UUID；脚本模式的凭据只从受控文件读取。",
     usage:
-      "memhub models list [--json]\n            memhub models show <profile-id> [--json]\n            memhub models add --config-file <path> [--api-key-file <path>] [--activate] [--json]\n            memhub models test <profile-id> [--json]\n            memhub models receipt <operation-id> [--json]\n            memhub models edit <profile-id> --config-file <path> [--api-key-file <path>] [--json]\n            memhub models activate <profile-id> [--json]\n            memhub models remove <profile-id> [--yes] [--json]",
+      "memhub models list [--json]\n            memhub models show <profile-id> [--json]\n            memhub models add --config-file <path> [--api-key-file <path>] [--activate [--yes] [--wait|--no-wait]] [--json]\n            memhub models test <profile-id> [--json]\n            memhub models receipt <operation-id> [--json]\n            memhub models edit <profile-id> --config-file <path> [--api-key-file <path>] [--json]\n            memhub models activate <profile-id> [--yes] [--wait|--no-wait] [--json]\n            memhub models switch <status|cancel> [--json]\n            memhub models spaces [--cleanup <space-id> --yes] [--json]\n            memhub models remove <profile-id> [--yes] [--json]",
     alternative_usage: "memhub models setup",
     options: [
       {
@@ -377,7 +377,17 @@ export const COMMANDS: readonly CommandDescriptor[] = [
       },
       {
         flag: "--activate",
-        summary: "add 成功后把新配置设为当前使用。",
+        summary:
+          "add 成功后先探测，再按 activate 的规则设为当前使用（向量模型变化时同样要确认切换）。",
+      },
+      {
+        flag: "--wait | --no-wait",
+        summary:
+          "activate 开始向量模型切换后是否跟随进度；终端里默认跟随，Ctrl-C 只停止显示。",
+      },
+      {
+        flag: "--cleanup <space-id>",
+        summary: "spaces：立即删除一个已停用的向量空间（不可恢复，需 --yes）。",
       },
       DESTRUCTIVE_CONFIRM_OPTION,
       JSON_OPTION,
@@ -387,7 +397,7 @@ export const COMMANDS: readonly CommandDescriptor[] = [
   {
     name: "memories",
     summary:
-      "列出、搜索、查看、添加、修改或物理删除记忆（对话、工作、编码三个场景）。add 和 App 的「添加记忆」是同一个入口；delete 不可逆，需 --yes。",
+      "列出、搜索、查看、添加、修改或物理删除记忆（对话、工作、编码三个场景）。add 和 App 的「添加记忆」是同一个入口；delete 不可逆，需 --yes；要删的记忆已不存在（或不属于该用户）时提示未找到，按已删除处理并退出 0。",
     usage:
       "memhub memories list [--scene <all|chat|working|coding>] [--source <id>] [--query <text>] [--status <state>] [--offset <n>] [--limit <n>] [--user-id <id>] [--json]\n            memhub memories show <memory-id> [--kind <kind>] [--variant <variant>] [--user-id <id>] [--json]\n            memhub memories add <text> [--request-id <uuid>] [--user-id <id>] [--json]\n            memhub memories add --content-file <path> [--request-id <uuid>] [--user-id <id>] [--json]\n            memhub memories add-status <request-id> [--user-id <id>] [--json]\n            memhub memories update <memory-id> --content-file <path> [--kind <kind>] [--variant <variant>] [--task <text>] [--user-id <id>] [--json]\n            memhub memories delete <memory-id> [--kind <kind>] [--variant <variant>] [--yes] [--user-id <id>] [--json]",
     options: [
@@ -451,12 +461,14 @@ export const COMMANDS: readonly CommandDescriptor[] = [
   {
     name: "settings",
     summary:
-      "查看或切换记忆模式（lite / pro / ultra）。lite 不调用模型，只在原始对话里检索；pro 由模型提取记忆（System 1）；ultra 在 pro 之上每晚自动进化（System 2，使用知识图谱）。任何模式都保留全部原始对话。切换不迁移数据：已处理的不会重做，排队中的和新的按新模式处理；需 --yes，不加时只显示计划。环境变量 ONE_MEMORY_GRAPH_STORE 会强制 ultra。settings features 查看或开关 SDK 的可选检索与提取功能（全局设置，默认全部保持 SDK 默认值）：graph_rerank 图谱重排（仅 ultra）、same_series_timeline 同系列时间线（需 graph_rerank）、episode_recall 片段召回（pro / ultra，需先开 session_episodes 写入片段）、session_episodes 片段写入、episode_summary 片段摘要（每个片段一次模型调用）、intention 意图提取（默认开）、few_shot 提取示例；set 需 --yes，不加时只显示计划；reset 恢复默认值。",
+      "查看或切换记忆模式（lite / pro / ultra）。lite 不调用模型，只在原始对话里检索；pro 由模型提取记忆（System 1）；ultra 在 pro 之上每晚自动进化（System 2，使用知识图谱）。任何模式都保留全部原始对话。切换不迁移数据：已处理的不会重做，排队中的和新的按新模式处理；需 --yes，不加时只显示计划。环境变量 ONE_MEMORY_GRAPH_STORE 会强制 ultra。settings features 查看或开关 SDK 的可选检索与提取功能（全局设置，默认全部保持 SDK 默认值）：graph_rerank 图谱重排（仅 ultra）、same_series_timeline 同系列时间线（需 graph_rerank）、episode_recall 片段召回（pro / ultra，需先开 session_episodes 写入片段）、session_episodes 片段写入、episode_summary 片段摘要（每个片段一次模型调用）、intention 意图提取（默认开）、intention_dedup 意图判重（默认开；关闭则检索与写入都不判重、不删除意图）、few_shot 提取示例，以及数值 intention_dedup_threshold 意图判重阈值（默认 0.95，可设 0.8–1.0）；set 需 --yes，不加时只显示计划；reset 恢复默认值。settings language 查看或设置界面语言（App 切换语言时会自动设置）：简体中文（zh-Hans）和 system 不指定 SDK 语言，SDK 照旧自动识别中文或英文；其余语言（en、zh-Hant、ja、es、de、pt、fr、ko、ru、id）会让提取等 SDK 提示使用该语言，立即生效。",
     usage:
       "memhub settings mode [lite|pro|ultra] [--yes] [--json]\n" +
       "            memhub settings features [--json]\n" +
       "            memhub settings features set <name>=<true|false> [...] [--yes] [--json]\n" +
-      "            memhub settings features reset [<name> ...] [--json]",
+      "            memhub settings features set intention_dedup_threshold=<0.8-1.0> [--yes] [--json]\n" +
+      "            memhub settings features reset [<name> ...] [--json]\n" +
+      "            memhub settings language [<code>|system] [--json]",
     options: [
       {
         flag: "mode [lite|pro|ultra]",
@@ -465,12 +477,17 @@ export const COMMANDS: readonly CommandDescriptor[] = [
       {
         flag: "features set <name>=<true|false>",
         summary:
-          "开关一个或多个 SDK 功能；功能在当前模式下不生效时会注明原因（例如 graph_rerank 需要 ultra）。",
+          "开关一个或多个 SDK 功能；功能在当前模式下不生效时会注明原因（例如 graph_rerank 需要 ultra）。intention_dedup_threshold 取 0.8–1.0 的数值。",
       },
       {
         flag: "features reset [<name> ...]",
         summary: "把指定功能（不写则全部）恢复为 SDK 默认值。",
       },
+      {
+        flag: "language [<code>|system]",
+        summary:
+          "不带参数显示界面语言和 SDK 提示语言；带语言代码（en、zh-Hans、zh-Hant、ja、es、de、pt、fr、ko、ru、id）或 system 时设置。",
+      },
       CONFIRM_OPTION,
       JSON_OPTION,
     ],

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

@@ -635,6 +635,8 @@ describe("documented commands", () => {
       "receipt",
       "edit",
       "activate",
+      "switch",
+      "spaces",
       "remove",
     ],
     // Source processing is one Freeze/Thaw switch under `sync`; the obsolete

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

@@ -97,7 +97,12 @@ export function contextExitCode(document: ContextSearchDocument): number {
 }
 
 export function renderContextText(document: ContextSearchDocument): string {
-  if (document.state === "unavailable") return "暂时无法查记忆，请稍后重试。\n";
+  if (document.state === "unavailable") {
+    // No lexical fallback: without the embedding service nothing is searched.
+    return document.code === "embedding_unavailable"
+      ? "向量服务不可用，无法检索；请检查向量模型配置。\n"
+      : "暂时无法查记忆，请稍后重试。\n";
+  }
   if (document.state === "denied") return "当前应用没有查记忆权限。\n";
   if (document.state === "invalid") return "查记忆返回了无法识别的结果。\n";
   if (document.state === "rejected") {

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

@@ -8,18 +8,25 @@ import axios from "axios";
  */
 const READ_ONLY_PATHS = [
   "/api/v1/call-events",
+  // Read-only: the registry plus a scan of the vector store's collection names.
+  "/api/v1/embedding-spaces",
+  "/api/v1/embedding-switches/current",
   "/api/v1/import-jobs",
   "/api/v1/live-sync",
   "/api/v1/memory-processing",
   "/api/v1/model-profiles",
   "/api/v1/source-grants",
   "/api/v1/sources",
+  "/api/v2/home-projection",
   "/api/v2/home-summary",
+  "/api/v2/raw",
   "/api/v2/memory-library",
   "/api/v2/user-profile",
   "/api/v2/user-profile/versions",
   "/api/v1/settings/memory-mode",
+  "/api/v1/settings/memory-mode/plan",
   "/api/v1/settings/memory-features",
+  "/api/v1/settings/ui-language",
   "/api/v2/evolve",
 ] as const;
 /** One evolve run's receipt (`memhub evolve --wait`). */
@@ -163,10 +170,23 @@ export function createCoreReader(attachment: {
         code: detailCode(response.data, response.status),
       };
     }
-    return { state: "unavailable" as const, code: `http_${response.status}` };
+    return {
+      state: "unavailable" as const,
+      code: unavailableCode(response.data, response.status),
+    };
   };
 }
 
+/** A 503 that names `embedding_unavailable` keeps it: the search could not
+ * embed its query, which needs another fix than "try again later". */
+function unavailableCode(value: unknown, status: number): string {
+  return status === 503 && detailCode(value, status) === EMBEDDING_UNAVAILABLE
+    ? EMBEDDING_UNAVAILABLE
+    : `http_${status}`;
+}
+
+export const EMBEDDING_UNAVAILABLE = "embedding_unavailable";
+
 /** Core's stable `detail` code when it sent one, else the bare status. */
 function detailCode(value: unknown, status: number): string {
   const detail =
@@ -218,7 +238,10 @@ export function createCoreContextQuery(attachment: {
     if (response.status === 404) {
       return { state: "not_found" as const, code: "http_404" };
     }
-    return { state: "unavailable" as const, code: `http_${response.status}` };
+    return {
+      state: "unavailable" as const,
+      code: unavailableCode(response.data, response.status),
+    };
   };
 }
 
@@ -248,6 +271,11 @@ export interface MemoryWriteReceipt {
   detail?: string;
   raw_ids?: string[];
   memory_ids?: string[];
+  /** Stable code of the last failure while the write still waits; null when
+   * none. Optional so older Runtimes stay readable. */
+  error_code?: string | null;
+  /** When Core will try this write again (ISO); null when not scheduled. */
+  next_retry_at?: string | null;
 }
 
 export interface OpenAIMessage {

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

@@ -31,12 +31,29 @@ const EVOLVE_PATH = "/api/v2/evolve";
 const MEMORY_MODE_PATH = "/api/v1/settings/memory-mode";
 /** `memhub settings features set|reset` sets the SDK features. */
 const MEMORY_FEATURES_PATH = "/api/v1/settings/memory-features";
+/** `memhub settings language <code>` sets the display language Core uses. */
+const UI_LANGUAGE_PATH = "/api/v1/settings/ui-language";
 const ONBOARDING_COMPLETE_PATH = "/api/v1/onboarding/complete";
+const EMBEDDING_SWITCH_PATHS = [
+  "/api/v1/embedding-switches",
+  "/api/v1/embedding-switches/plan",
+] as const;
+const EMBEDDING_SWITCH_CANCEL =
+  /^\/api\/v1\/embedding-switches\/[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}\/cancel$/;
+const EMBEDDING_SPACE_PATH =
+  /^\/api\/v1\/embedding-spaces\/[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/;
 const MAX_BYTES = 4 * 1024 * 1024;
 
 export type OperationOutcome<T> =
   | { state: "committed"; data: T }
-  | { state: "rejected"; code: string; http_status: number }
+  | {
+      state: "rejected";
+      code: string;
+      http_status: number;
+      /** Core's refusal body, when it carries more than the code (a switch
+       * plan rides along with `embedding_switch_required`). */
+      body?: unknown;
+    }
   | { state: "unknown"; code: string };
 
 export interface CoreOperations {
@@ -104,6 +121,8 @@ export function createCoreOperations(attachment: {
         path !== GRAPH_WIDTH_PATH &&
         path !== EVOLVE_PATH &&
         path !== ONBOARDING_COMPLETE_PATH &&
+        !(EMBEDDING_SWITCH_PATHS as readonly string[]).includes(path) &&
+        !EMBEDDING_SWITCH_CANCEL.test(path) &&
         !MODEL_PROFILE_ACTIVATE.test(path)
       ) {
         throw new Error("core_operation_path_not_allowed");
@@ -121,11 +140,18 @@ export function createCoreOperations(attachment: {
       if (response.status >= 200 && response.status < 300) {
         return { state: "committed", data: response.data as T };
       }
-      if (response.status >= 400 && response.status < 500) {
+      if (
+        (response.status >= 400 && response.status < 500) ||
+        // Core answers a refusal it can name with 503 (`sdk_reembed_unavailable`)
+        // or 507 (`insufficient_disk_space`) on the switch routes.
+        ([503, 507].includes(response.status) &&
+          (EMBEDDING_SWITCH_PATHS as readonly string[]).includes(path))
+      ) {
         return {
           state: "rejected",
           code: safeErrorCode(response.data, response.status),
           http_status: response.status,
+          body: response.data,
         };
       }
       return {
@@ -141,6 +167,7 @@ export function createCoreOperations(attachment: {
       if (
         path !== MEMORY_MODE_PATH &&
         path !== MEMORY_FEATURES_PATH &&
+        path !== UI_LANGUAGE_PATH &&
         (!SDK_MEMORY_PATH.test(path) || path.includes("?"))
       ) {
         throw new Error("core_operation_path_not_allowed");
@@ -204,7 +231,11 @@ export function createCoreOperations(attachment: {
       };
     },
     async delete<T>(path: string, signal?: AbortSignal) {
-      if (!SDK_MEMORY_PATH.test(path) && !MODEL_PROFILE_PATH.test(path)) {
+      if (
+        !SDK_MEMORY_PATH.test(path) &&
+        !MODEL_PROFILE_PATH.test(path) &&
+        !EMBEDDING_SPACE_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,4 +1,5 @@
 import type {
+  HomeProjectionV1,
   ImportIssue,
   ImportJob,
   LiveSyncHealth,
@@ -26,6 +27,9 @@ export const MEMORY_STATUSES = [
 const ID_MAX = 128;
 const LABEL_MAX = 256;
 const LIST_MAX = 500;
+const USER_ID = /^[A-Za-z0-9._-]{1,64}$/;
+const ISO_TIME =
+  /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d+)?(?:Z|[+-]\d{2}:\d{2})$/;
 const LIVE_SYNC_STATES = [
   "idle",
   "running",
@@ -406,6 +410,153 @@ export function validateHomeSummary(value: unknown): SdkHomeSummary | null {
   return summary as unknown as SdkHomeSummary;
 }
 
+/** `GET /api/v2/home-projection`: the mode-aware home content plane. */
+export function validateHomeProjection(
+  value: unknown,
+): HomeProjectionV1 | null {
+  const projection = exactRecord(value, [
+    "projection_version",
+    "user_id",
+    "effective_mode",
+    "capabilities",
+    "visible_count",
+    "display_state",
+    "latest",
+    "observed_at",
+  ]);
+  if (!projection) return null;
+  const mode = projection.effective_mode;
+  const capabilities = exactRecord(projection.capabilities, [
+    "content_plane",
+    "generation_required",
+    "graph_enabled",
+    "evolve_available",
+  ]);
+  if (
+    projection.projection_version !== 1 ||
+    typeof projection.user_id !== "string" ||
+    !USER_ID.test(projection.user_id) ||
+    !oneOf(mode, ["lite", "pro", "ultra"] as const) ||
+    !capabilities ||
+    capabilities.content_plane !== (mode === "lite" ? "raw" : "memory") ||
+    capabilities.generation_required !== (mode !== "lite") ||
+    capabilities.graph_enabled !== (mode === "ultra") ||
+    capabilities.evolve_available !== (mode === "ultra") ||
+    count(projection.visible_count) === null ||
+    !oneOf(projection.display_state, [
+      "empty",
+      "excerpt",
+      "no_user_excerpt",
+      "no_displayable_memory",
+    ] as const) ||
+    !isoTime(projection.observed_at) ||
+    !validProjectionLatest(projection.latest, mode)
+  ) {
+    return null;
+  }
+  const visible = projection.visible_count as number;
+  const latest = projection.latest as Record<string, unknown> | null;
+  if (
+    (visible === 0 &&
+      (latest !== null || projection.display_state !== "empty")) ||
+    (visible > 0 && projection.display_state === "empty") ||
+    (latest === null &&
+      ["excerpt", "no_user_excerpt"].includes(
+        projection.display_state as string,
+      )) ||
+    (latest?.type === "raw" &&
+      projection.display_state !== latest.display_state) ||
+    (latest?.type === "memory" && projection.display_state !== "excerpt")
+  ) {
+    return null;
+  }
+  return projection as unknown as HomeProjectionV1;
+}
+
+function validProjectionLatest(
+  value: unknown,
+  mode: "lite" | "pro" | "ultra",
+): boolean {
+  if (value === null) return true;
+  const base = [
+    "type",
+    "time",
+    "time_basis",
+    "excerpt",
+    "truncated",
+    "source_id",
+  ];
+  const candidate = record(value);
+  if (!candidate) return false;
+  const keys =
+    candidate.type === "raw"
+      ? [...base, "raw_id", "session_id", "display_state"]
+      : [...base, "memory_id", "scene", "kind", "variant"];
+  const latest = exactRecord(value, keys);
+  if (
+    !latest ||
+    !(latest.time === null || isoTime(latest.time)) ||
+    ![null, "conversation", "import", "write", "update"].includes(
+      latest.time_basis as null | string,
+    ) ||
+    text(latest.excerpt, 200) === null ||
+    typeof latest.truncated !== "boolean" ||
+    text(latest.source_id, ID_MAX) === null
+  ) {
+    return false;
+  }
+  if (latest.type === "raw") {
+    return (
+      mode === "lite" &&
+      nonemptyText(latest.raw_id, ID_MAX) &&
+      nonemptyText(latest.session_id, LABEL_MAX) &&
+      oneOf(latest.display_state, ["excerpt", "no_user_excerpt"] as const) &&
+      (latest.display_state !== "no_user_excerpt" ||
+        (latest.excerpt === "" && latest.truncated === false))
+    );
+  }
+  return (
+    latest.type === "memory" &&
+    mode !== "lite" &&
+    nonemptyText(latest.memory_id, ID_MAX) &&
+    oneOf(latest.scene, ["chat", "working", "coding"] as const) &&
+    oneOf(latest.kind, ["chat", "experience"] as const) &&
+    [null, "working", "coding"].includes(latest.variant as null | string) &&
+    ((latest.kind === "chat" &&
+      latest.scene === "chat" &&
+      latest.variant === null) ||
+      (latest.kind === "experience" &&
+        latest.scene === latest.variant &&
+        oneOf(latest.scene, ["working", "coding"] as const)))
+  );
+}
+
+/** The bounded `/api/v2/raw?limit=1` envelope used only for its real total. */
+export function validateRawTotal(value: unknown): number | null {
+  const page = exactRecord(value, [
+    "user_id",
+    "items",
+    "total",
+    "offset",
+    "limit",
+    "time_filtered",
+  ]);
+  if (
+    !page ||
+    typeof page.user_id !== "string" ||
+    !USER_ID.test(page.user_id) ||
+    !Array.isArray(page.items) ||
+    page.items.length > 1 ||
+    count(page.total) === null ||
+    page.offset !== 0 ||
+    page.limit !== 1 ||
+    page.time_filtered !== false
+  ) {
+    return null;
+  }
+  return page.total as number;
+}
+
 function identifiers(value: unknown): string[] | null {
   return list(value ?? [], (item) => text(item, ID_MAX));
 }
@@ -430,6 +581,30 @@ function record(value: unknown): Record<string, unknown> | null {
     : null;
 }
 
+function exactRecord(
+  value: unknown,
+  keys: readonly string[],
+): Record<string, unknown> | null {
+  const item = record(value);
+  return item &&
+    Object.keys(item).length === keys.length &&
+    keys.every((key) => Object.hasOwn(item, key))
+    ? item
+    : null;
+}
+
+function isoTime(value: unknown): value is string {
+  return (
+    typeof value === "string" &&
+    ISO_TIME.test(value) &&
+    Number.isFinite(Date.parse(value))
+  );
+}
+
+function nonemptyText(value: unknown, max: number): value is string {
+  return typeof value === "string" && value.length > 0 && value.length <= max;
+}
+
 function text(value: unknown, max: number): string | null {
   return typeof value === "string" && value.length <= max ? value : null;
 }

memhub/apps/cli/src/embedding-switch-cli.test.ts

@@ -0,0 +1,502 @@
+import { beforeEach, describe, expect, it, vi } from "vitest";
+
+import { run } from "./cli.js";
+import { renderContextText } from "./context-search.js";
+import { describeEmbeddingSwitchSummary } from "./embedding-switch-flow.js";
+import { composeStatusReport, renderStatusText } from "./status-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(),
+}));
+vi.mock("@one-memory/runtime-control", async (importOriginal) => ({
+  ...(await importOriginal<typeof import("@one-memory/runtime-control")>()),
+  ...runtime,
+}));
+
+const PROFILE = "44444444-4444-4444-8444-444444444444";
+const JOB = "55555555-5555-4555-8555-555555555555";
+const SPACE = "66666666-6666-4666-8666-666666666666";
+
+function plan(overrides: Record<string, unknown> = {}) {
+  return {
+    needed: true,
+    reason: "embedding_identity_changed",
+    plan_token: "token-1",
+    source: {
+      space_id: "77777777-7777-4777-8777-777777777777",
+      model: "bge-small-zh-v1.5",
+      dims: 512,
+      collection_base: "memhub_aaaaaaaaaaaaaaaa",
+      vectors: 12480,
+    },
+    target: {
+      space_id: null,
+      model: "text-embedding-v3",
+      dims: 1024,
+      collection_base: "",
+    },
+    target_profile_id: PROFILE,
+    target_revision: 5,
+    target_provider_kind: "openai_compatible",
+    target_local: false,
+    sources: [],
+    total_vectors: 12480,
+    users: 2,
+    graph_vectors: null,
+    estimate_s: 120,
+    requests: 195,
+    disk_bytes_needed: 70 * 1024 * 1024,
+    disk_bytes_free: 10 * 1024 * 1024 * 1024,
+    retention_days: 14,
+    blockers: [],
+    ...overrides,
+  };
+}
+
+function job(
+  state: string,
+  percent: number,
+  extra: Record<string, unknown> = {},
+) {
+  return {
+    job_id: JOB,
+    kind: "switch",
+    state,
+    source: plan().source,
+    target: { ...plan().target, space_id: SPACE },
+    stray_space_ids: [],
+    target_profile_id: PROFILE,
+    target_revision: 5,
+    requested_by: "cli",
+    progress: {
+      phase: state === "reembedding" ? "vectors" : "prepare",
+      done: Math.round((12480 * percent) / 100),
+      total: 12480,
+      percent,
+      eta_s: 60,
+    },
+    cancel_requested: false,
+    error_code: null,
+    attempt: 1,
+    created_at: "T1",
+    updated_at: "T1",
+    finished_at: state === "done" ? "T2" : null,
+    ...extra,
+  };
+}
+
+beforeEach(() => {
+  vi.clearAllMocks();
+  for (const method of Object.values(transport)) method.mockReset();
+  runtime.inspectRuntimeStatus.mockResolvedValue({
+    state: "running",
+    code: "runtime_verified",
+    instanceId: "instance-1",
+    host: "127.0.0.1",
+    port: 8765,
+    version: "1.2.3",
+  });
+  runtime.discoverRuntimeAttachment.mockResolvedValue({
+    instanceId: "instance-1",
+    apiToken: "synthetic-runtime-token",
+    host: "127.0.0.1",
+    port: 8765,
+    servicePid: 4242,
+    health: {
+      status: "ok",
+      service: "one-memory-core",
+      version: "1.2.3",
+      instance_id: "instance-1",
+    },
+  });
+});
+
+describe("models activate with an embedding change", () => {
+  it("prints the plan and exits 2 without --yes on a non-terminal", async () => {
+    transport.post.mockImplementation(async (url: string) =>
+      url === "/api/v1/embedding-switches/plan"
+        ? { status: 200, data: plan() }
+        : { status: 404, data: {} },
+    );
+    const result = await capturedRun(["models", "activate", PROFILE]);
+    expect(result.code).toBe(2);
+    expect(result.stdout).toContain("将更换向量模型");
+    expect(result.stdout).toContain("bge-small-zh-v1.5（512 维）");
+    expect(result.stdout).toContain("text-embedding-v3（1024 维）");
+    expect(result.stdout).toContain("12,480");
+    expect(result.stdout).toContain("重新运行并加上 --yes 以确认");
+    expect(transport.post.mock.calls.map(([url]) => url)).toEqual([
+      "/api/v1/embedding-switches/plan",
+    ]);
+  });
+
+  it("starts the switch with --yes and emits JSON progress lines", async () => {
+    transport.post.mockImplementation(async (url: string) => {
+      if (url === "/api/v1/embedding-switches/plan") {
+        return { status: 200, data: plan() };
+      }
+      if (url === "/api/v1/embedding-switches") {
+        return { status: 202, data: job("preparing", 0) };
+      }
+      return { status: 404, data: {} };
+    });
+    const answers = [
+      {
+        phase: "running",
+        writes_paused: true,
+        job: job("reembedding", 50),
+        last_finished: null,
+      },
+      {
+        phase: "idle",
+        writes_paused: false,
+        job: null,
+        last_finished: job("done", 100),
+      },
+    ];
+    transport.get.mockImplementation(async (url: string) =>
+      url === "/api/v1/embedding-switches/current"
+        ? { status: 200, data: { schema_version: 1, ...answers.shift() } }
+        : { status: 404, data: {} },
+    );
+    const result = await capturedRun(
+      ["models", "activate", PROFILE, "--yes", "--wait", "--json"],
+      { watchWait: async () => undefined },
+    );
+    expect(result.code).toBe(0);
+    const lines = result.stdout
+      .trim()
+      .split("\n")
+      .map((line) => JSON.parse(line));
+    expect(lines.map((line) => line.state)).toEqual([
+      "preparing",
+      "reembedding",
+      "done",
+      "done",
+    ]);
+    expect(lines[1]).toMatchObject({ percent: 50, job_id: JOB });
+    expect(lines.at(-1)).toMatchObject({ result: "switched" });
+    expect(transport.post).toHaveBeenCalledWith(
+      "/api/v1/embedding-switches",
+      {
+        profile_id: PROFILE,
+        expected_revision: 5,
+        plan_token: "token-1",
+        requested_by: "cli",
+      },
+      undefined,
+    );
+  });
+
+  it("refuses a plan with blockers and starts nothing", async () => {
+    transport.post.mockResolvedValue({
+      status: 200,
+      data: plan({ blockers: ["sdk_reembed_unavailable"] }),
+    });
+    const result = await capturedRun([
+      "models",
+      "activate",
+      PROFILE,
+      "--yes",
+      "--json",
+    ]);
+    expect(result.code).toBe(1);
+    expect(JSON.parse(result.stdout)).toMatchObject({
+      state: "blocked",
+      code: "sdk_reembed_unavailable",
+    });
+    expect(transport.post).toHaveBeenCalledTimes(1);
+  });
+
+  it("says nothing is re-embedded when only generation changed", async () => {
+    transport.post.mockImplementation(async (url: string) =>
+      url === "/api/v1/embedding-switches/plan"
+        ? {
+            status: 200,
+            data: plan({ needed: false, reason: "same_embedding" }),
+          }
+        : { status: 200, data: profileResponse() },
+    );
+    const result = await capturedRun(["models", "activate", PROFILE]);
+    expect(result.code).toBe(0);
+    expect(result.stdout).toContain("向量模型未变化，无需重新生成向量。");
+  });
+
+  it("reads the plan carried by a 409 embedding_switch_required", async () => {
+    transport.post.mockImplementation(async (url: string) =>
+      url.endsWith("/activate")
+        ? {
+            status: 409,
+            data: { detail: "embedding_switch_required", plan: plan() },
+          }
+        : { status: 404, data: { detail: "Not Found" } },
+    );
+    const result = await capturedRun(["models", "activate", PROFILE, "--json"]);
+    expect(result.code).toBe(2);
+    expect(JSON.parse(result.stdout)).toMatchObject({
+      state: "confirmation_required",
+      code: "embedding_switch_required",
+    });
+  });
+
+  it("does not treat a domain 404 as an old-Core route miss", async () => {
+    transport.post.mockResolvedValue({
+      status: 404,
+      data: { detail: "embedding_switch_not_found" },
+    });
+    const result = await capturedRun(["models", "activate", PROFILE, "--json"]);
+    expect(result.code).toBe(1);
+    expect(
+      transport.post.mock.calls.some(([url]) =>
+        String(url).endsWith("/activate"),
+      ),
+    ).toBe(false);
+  });
+});
+
+describe("models switch and spaces", () => {
+  it("reports no switch, then cancels the running one", async () => {
+    transport.get.mockResolvedValueOnce({
+      status: 200,
+      data: {
+        schema_version: 1,
+        phase: "idle",
+        writes_paused: false,
+        job: null,
+        last_finished: null,
+      },
+    });
+    const idle = await capturedRun(["models", "switch", "status"]);
+    expect(idle.code).toBe(0);
+    expect(idle.stdout).toContain("没有进行中的向量模型切换");
+
+    transport.get.mockResolvedValueOnce({
+      status: 200,
+      data: {
+        schema_version: 1,
+        phase: "running",
+        writes_paused: true,
+        job: job("reembedding", 20),
+        last_finished: null,
+      },
+    });
+    transport.post.mockResolvedValue({
+      status: 200,
+      data: job("reembedding", 20, { cancel_requested: true }),
+    });
+    const cancelled = await capturedRun([
+      "models",
+      "switch",
+      "cancel",
+      "--json",
+    ]);
+    expect(cancelled.code).toBe(0);
+    expect(transport.post).toHaveBeenCalledWith(
+      `/api/v1/embedding-switches/${JOB}/cancel`,
+      {},
+      undefined,
+    );
+    expect(JSON.parse(cancelled.stdout)).toMatchObject({
+      cancel_requested: true,
+    });
+  });
+
+  it("lists spaces and needs --yes before cleaning one up", async () => {
+    transport.get.mockResolvedValue({
+      status: 200,
+      data: {
+        schema_version: 1,
+        live_space_id: "x",
+        spaces: [
+          {
+            space_id: SPACE,
+            state: "retired",
+            model: "bge-small-zh-v1.5",
+            dims: 512,
+            vectors: 10,
+            keep_until: "2026-11-15T00:00:00+00:00",
+          },
+          {
+            space_id: "88888888-8888-4888-8888-888888888888",
+            state: "dropped",
+            model: "m",
+            dims: 8,
+          },
+        ],
+        scanned: [],
+        scan_error: null,
+      },
+    });
+    const listed = await capturedRun(["models", "spaces"]);
+    expect(listed.code).toBe(0);
+    expect(listed.stdout).toContain("已停用");
+    expect(listed.stdout).toContain("保留到 2026-11-15");
+    expect(listed.stdout).not.toContain("88888888");
+
+    const preview = await capturedRun(["models", "spaces", "--cleanup", SPACE]);
+    expect(preview.code).toBe(0);
+    expect(preview.stdout).toContain("--yes");
+    expect(transport.delete).not.toHaveBeenCalled();
+
+    transport.delete.mockResolvedValue({
+      status: 200,
+      data: { schema_version: 1 },
+    });
+    const dropped = await capturedRun([
+      "models",
+      "spaces",
+      "--cleanup",
+      SPACE,
+      "--yes",
+    ]);
+    expect(dropped.code).toBe(0);
+    expect(transport.delete).toHaveBeenCalledWith(
+      `/api/v1/embedding-spaces/${SPACE}`,
+      undefined,
+    );
+  });
+});
+
+describe("status and search wording", () => {
+  it("shows the switch line in memhub status", async () => {
+    const reader = async (path: string) =>
+      path === "/api/v1/memory-processing"
+        ? {
+            state: "ok" as const,
+            data: {
+              pending: 3,
+              fresh_pending: 1,
+              backlog_pending: 2,
+              outside_window_pending: 0,
+              running: 0,
+              waiting_for_model: 0,
+              completed: 9,
+              failed: 0,
+              embedding_switch: {
+                job_id: JOB,
+                kind: "switch",
+                state: "reembedding",
+                percent: 50,
+                eta_s: 60,
+              },
+            },
+          }
+        : { state: "unavailable" as const, code: "http_503" };
+    const report = await composeStatusReport({
+      dataDir: "/synthetic/data",
+      runtime: {
+        state: "running",
+        code: "runtime_verified",
+        instanceId: "instance-1",
+        host: "127.0.0.1",
+        port: 8765,
+      } as never,
+      background: null,
+      reader: reader as never,
+    });
+    const text = renderStatusText(report, "MemHub");
+    expect(text).toContain("向量模型：切换中 50%，记忆整理已暂停");
+    expect(
+      describeEmbeddingSwitchSummary({
+        kind: "merge",
+        state: "reembedding",
+        percent: 30,
+      }),
+    ).toBe("正在合并旧向量数据 30%，记忆整理已暂停");
+    expect(
+      describeEmbeddingSwitchSummary({
+        kind: "merge",
+        state: "scanning",
+        percent: 0,
+      }),
+    ).toBe("正在检查向量数据…");
+  });
+
+  it("names an unavailable embedding service instead of 'try later'", () => {
+    expect(
+      renderContextText({
+        schema_version: 2,
+        product: "memhub",
+        state: "unavailable",
+        code: "embedding_unavailable",
+        items: [],
+      }),
+    ).toContain("向量服务不可用");
+  });
+});
+
+function profileResponse() {
+  return {
+    profile_id: PROFILE,
+    name: "Synthetic",
+    provider_kind: "openai_compatible",
+    base_url: "https://example.invalid/v1",
+    model: "synthetic-model-2",
+    embedding_model: "text-embedding-v3",
+    embedding_provider_kind: "openai_compatible",
+    embedding_base_url: "https://example.invalid/v1",
+    embedding_dimensions: 1024,
+    has_api_key: true,
+    credential_state: "available",
+    timeout_seconds: 30,
+    max_concurrency: 1,
+    context_window: null,
+    disable_thinking: true,
+    capabilities: {
+      endpoint_reachable: true,
+      model_available: true,
+      structured_output: true,
+      embedding_available: true,
+    },
+    revision: 5,
+    is_active: true,
+    created_at: "2026-09-19T00:00:00Z",
+    updated_at: "2026-09-19T00:00:00Z",
+  };
+}
+
+async function capturedRun(
+  arguments_: string[],
+  controls: Parameters<typeof run>[2] = {},
+) {
+  let stdout = "";
+  let stderr = "";
+  const stdoutSpy = vi
+    .spyOn(process.stdout, "write")
+    .mockImplementation((chunk) => {
+      stdout += String(chunk);
+      return true;
+    });
+  const stderrSpy = vi
+    .spyOn(process.stderr, "write")
+    .mockImplementation((chunk) => {
+      stderr += String(chunk);
+      return true;
+    });
+  try {
+    return {
+      code: await run(
+        arguments_,
+        { ONE_MEMORY_DATA_DIR: "/synthetic/data" },
+        { stdinIsTTY: false, ...controls },
+      ),
+      stdout,
+      stderr,
+    };
+  } finally {
+    stdoutSpy.mockRestore();
+    stderrSpy.mockRestore();
+  }
+}

memhub/apps/cli/src/embedding-switch-flow.ts

@@ -0,0 +1,852 @@
+/**
+ * Switching the embedding model from the CLI: `models activate` when the
+ * embedding changes, `models switch status|cancel`, `models spaces`.
+ *
+ * Core owns every decision (`/api/v1/embedding-switches*`, contract
+ * `docs/contracts/embedding-switch-v1.md`). A change of embedding model or
+ * width is never applied by activation alone: Core plans a switch, the user
+ * confirms it, Core re-embeds every memory into a new space and only then
+ * makes it live. The CLI shows the plan, asks, starts the job and follows it.
+ */
+
+import { isBareNotFound } from "@one-memory/operations";
+import type { CoreReader } from "./core-client.js";
+import type {
+  CoreDeleteOperations,
+  CoreOperations,
+  OperationOutcome,
+} from "./core-operations.js";
+import { EXIT_FAILED, EXIT_OK, EXIT_USAGE } from "./exit-codes.js";
+import {
+  activateModelProfile,
+  type ModelWriteDocument,
+  modelProfileResult,
+  renderModelWriteText,
+} from "./model-write-flows.js";
+import { PRODUCT } from "./version.js";
+
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/;
+const CODE = /^[a-z0-9_.:-]{1,128}$/;
+const TERMINAL = new Set(["done", "rolled_back"]);
+const POLL_MS = 1_000;
+
+export interface SpaceSummary {
+  space_id: string | null;
+  model: string | null;
+  dims: number | null;
+  collection_base: string;
+  vectors?: number | null;
+}
+
+export interface EmbeddingSwitchPlan {
+  needed: boolean;
+  reason: string;
+  plan_token: string;
+  source: SpaceSummary;
+  target: SpaceSummary;
+  target_profile_id: string;
+  target_revision: number;
+  target_provider_kind: string;
+  target_local: boolean;
+  total_vectors: number;
+  users: number | null;
+  graph_vectors: number | null;
+  estimate_s: number | null;
+  requests: number | null;
+  disk_bytes_needed: number;
+  disk_bytes_free: number | null;
+  retention_days: number;
+  blockers: string[];
+}
+
+export interface SwitchProgress {
+  phase: string;
+  done: number;
+  total: number;
+  percent: number;
+  eta_s: number | null;
+}
+
+export interface EmbeddingSwitchJob {
+  job_id: string;
+  kind: "switch" | "merge";
+  state: string;
+  source: SpaceSummary;
+  target: SpaceSummary;
+  progress: SwitchProgress;
+  cancel_requested: boolean;
+  error_code: string | null;
+  finished_at: string | null;
+}
+
+export interface SwitchCurrent {
+  phase: "idle" | "scanning" | "running";
+  writes_paused: boolean;
+  job: EmbeddingSwitchJob | null;
+  last_finished: EmbeddingSwitchJob | null;
+}
+
+export interface SwitchIo {
+  reader: CoreReader;
+  operations: CoreOperations & CoreDeleteOperations;
+  emit: (text: string) => void;
+  asJson: boolean;
+  /** A terminal is attached: may prompt, and follows progress by default. */
+  interactive: boolean;
+  confirm?: (question: string) => Promise<boolean>;
+  wait?: (milliseconds: number, signal: AbortSignal) => Promise<void>;
+  signal?: AbortSignal;
+}
+
+export interface ActivateOptions {
+  confirmed: boolean;
+  /** `--wait` / `--no-wait`; undefined follows on a terminal only. */
+  follow?: boolean;
+}
+
+// ---------------------------------------------------------------------------
+// Parsing: bounded projections of Core's answers, never passthrough.
+// ---------------------------------------------------------------------------
+
+function record(value: unknown): Record<string, unknown> | null {
+  return value && typeof value === "object" && !Array.isArray(value)
+    ? (value as Record<string, unknown>)
+    : null;
+}
+
+function int(value: unknown): number | null {
+  return typeof value === "number" && Number.isSafeInteger(value) && value >= 0
+    ? value
+    : null;
+}
+
+function str(value: unknown, max = 256): string | null {
+  return typeof value === "string" && value.length <= max ? value : null;
+}
+
+function space(value: unknown): SpaceSummary | null {
+  const item = record(value);
+  if (!item) return null;
+  return {
+    space_id: str(item.space_id, 64),
+    model: str(item.model),
+    dims: int(item.dims),
+    collection_base: str(item.collection_base) ?? "",
+    vectors: int(item.vectors),
+  };
+}
+
+export function parsePlan(value: unknown): EmbeddingSwitchPlan | null {
+  const plan = record(value);
+  if (!plan || typeof plan.needed !== "boolean") return null;
+  const source = space(plan.source);
+  const target = space(plan.target);
+  const token = str(plan.plan_token, 128);
+  const profile = str(plan.target_profile_id, 128);
+  const revision = int(plan.target_revision);
+  if (!source || !target || !token || !profile || revision === null) {
+    return null;
+  }
+  const blockers = Array.isArray(plan.blockers)
+    ? plan.blockers.filter(
+        (item): item is string => typeof item === "string" && CODE.test(item),
+      )
+    : [];
+  return {
+    needed: plan.needed,
+    reason: str(plan.reason, 64) ?? "",
+    plan_token: token,
+    source,
+    target,
+    target_profile_id: profile,
+    target_revision: revision,
+    target_provider_kind: str(plan.target_provider_kind, 64) ?? "",
+    target_local: plan.target_local === true,
+    total_vectors: int(plan.total_vectors) ?? 0,
+    users: int(plan.users),
+    graph_vectors: int(plan.graph_vectors),
+    estimate_s: int(plan.estimate_s),
+    requests: int(plan.requests),
+    disk_bytes_needed: int(plan.disk_bytes_needed) ?? 0,
+    disk_bytes_free: int(plan.disk_bytes_free),
+    retention_days: int(plan.retention_days) ?? 14,
+    blockers,
+  };
+}
+
+export function parseJob(value: unknown): EmbeddingSwitchJob | null {
+  const job = record(value);
+  if (!job) return null;
+  const jobId = str(job.job_id, 64);
+  const state = str(job.state, 32);
+  const source = space(job.source);
+  const target = space(job.target);
+  const progress = record(job.progress) ?? {};
+  if (!jobId || !state || !source || !target) return null;
+  if (job.kind !== "switch" && job.kind !== "merge") return null;
+  const percent =
+    typeof progress.percent === "number" && Number.isFinite(progress.percent)
+      ? Math.min(100, Math.max(0, progress.percent))
+      : 0;
+  return {
+    job_id: jobId,
+    kind: job.kind,
+    state,
+    source,
+    target,
+    progress: {
+      phase: str(progress.phase, 32) ?? "prepare",
+      done: int(progress.done) ?? 0,
+      total: int(progress.total) ?? 0,
+      percent,
+      eta_s: int(progress.eta_s),
+    },
+    cancel_requested: job.cancel_requested === true,
+    error_code:
+      typeof job.error_code === "string" && CODE.test(job.error_code)
+        ? job.error_code
+        : null,
+    finished_at: str(job.finished_at, 64),
+  };
+}
+
+export function parseCurrent(value: unknown): SwitchCurrent | null {
+  const current = record(value);
+  if (!current) return null;
+  const phase = current.phase;
+  if (phase !== "idle" && phase !== "scanning" && phase !== "running") {
+    return null;
+  }
+  return {
+    phase,
+    writes_paused: current.writes_paused === true,
+    job: current.job == null ? null : parseJob(current.job),
+    last_finished:
+      current.last_finished == null ? null : parseJob(current.last_finished),
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Wording
+// ---------------------------------------------------------------------------
+
+const BLOCKER_TEXT: Record<string, string> = {
+  embedding_switch_running: "上一次向量模型切换还在进行，请等待完成或先取消。",
+  embedding_probe_required: "新配置还没有通过探测；先运行 memhub models test。",
+  sdk_reembed_unavailable:
+    "当前运行时的 SDK 不支持重新生成向量，请先升级 MemHub。",
+  embedding_switch_requires_migration:
+    "还有旧版本的向量数据没有迁移完，请先完成升级迁移。",
+  embedding_dimensions_unknown:
+    "新配置的向量维度未知；先探测或在配置里写明 embedding_dimensions。",
+  insufficient_disk_space: "磁盘空间不足，无法容纳新旧两份向量数据。",
+};
+
+const FAILURE_TEXT: Record<string, string> = {
+  writes_did_not_drain: "等待正在进行的记忆整理结束超时",
+  embedding_service_failed: "向量服务连续请求失败",
+  embedding_dimensions_mismatch: "向量服务返回的维度与探测到的不一致",
+  embedding_verification_failed: "新向量没有通过校验",
+  target_profile_changed: "切换期间目标配置被修改",
+  embedding_switch_cancelled: "已取消",
+  model_secret_unavailable: "读不到向量服务的 API Key",
+  secure_storage_unavailable: "系统钥匙串不可用",
+  embedding_switch_clients_busy: "记忆图谱一直被占用，无法重新生成",
+};
+
+const STATE_TEXT: Record<string, string> = {
+  preparing: "准备中（等待记忆整理暂停）",
+  reembedding: "重新生成向量",
+  verifying: "校验新向量",
+  committing: "正式切换",
+  failed: "正在回滚",
+  done: "已完成",
+  rolled_back: "已回滚",
+};
+
+export function blockerText(code: string): string {
+  return BLOCKER_TEXT[code] ?? code;
+}
+
+function spaceLabel(item: SpaceSummary, local?: boolean): string {
+  const dims = item.dims === null ? "维度未知" : `${item.dims} 维`;
+  return `${item.model ?? "未知模型"}（${dims}${local ? "，本地" : ""}）`;
+}
+
+function duration(seconds: number | null): string {
+  if (seconds === null) return "未知";
+  if (seconds < 60) return `${Math.max(1, seconds)} 秒`;
+  return `${Math.round(seconds / 60)} 分钟`;
+}
+
+function megabytes(bytes: number | null): string {
+  return bytes === null ? "未知" : `${Math.ceil(bytes / (1024 * 1024))} MB`;
+}
+
+export function renderPlanText(plan: EmbeddingSwitchPlan): string {
+  const lines = [
+    `将更换向量模型：${spaceLabel(plan.source)} → ${spaceLabel(plan.target, plan.target_local)}`,
+    `需要用新模型重新生成 ${plan.total_vectors.toLocaleString("en-US")} 条向量` +
+      `${plan.users === null ? "" : `（${plan.users} 个用户）`}` +
+      `，预计约 ${duration(plan.estimate_s)}` +
+      `${plan.requests === null ? "，在本机计算，不产生费用" : `，约 ${plan.requests} 次请求`}` +
+      `，额外磁盘约 ${megabytes(plan.disk_bytes_needed)}。`,
+  ];
+  if (plan.graph_vectors) {
+    lines.push(`记忆图谱另有 ${plan.graph_vectors} 条向量一并重新生成。`);
+  }
+  if (
+    plan.source.dims !== null &&
+    plan.source.dims === plan.target.dims &&
+    plan.source.model !== plan.target.model
+  ) {
+    lines.push("新旧模型维度相同，但向量不能通用，仍需重新生成。");
+  }
+  lines.push(
+    "切换期间记忆整理暂停，检索继续使用旧模型；完成并校验通过后才会生效。",
+    `旧的向量数据保留 ${plan.retention_days} 天，可用 memhub models spaces 清理。`,
+  );
+  for (const blocker of plan.blockers) {
+    lines.push(`无法开始：${blockerText(blocker)}`);
+  }
+  return `${lines.join("\n")}\n`;
+}
+
+export function renderProgressLine(job: EmbeddingSwitchJob): string {
+  const what = job.kind === "merge" ? "正在合并旧向量数据" : "正在切换向量模型";
+  const state = STATE_TEXT[job.state] ?? job.state;
+  if (job.state === "reembedding" && job.progress.total > 0) {
+    const eta =
+      job.progress.eta_s === null
+        ? ""
+        : `  预计还需 ${duration(job.progress.eta_s)}`;
+    return `${what}：${state}  ${job.progress.done.toLocaleString("en-US")}/${job.progress.total.toLocaleString("en-US")}  ${Math.floor(job.progress.percent)}%${eta}`;
+  }
+  return `${what}：${state}`;
+}
+
+export function renderOutcomeText(job: EmbeddingSwitchJob): string {
+  if (job.state === "done") {
+    return job.kind === "merge"
+      ? "旧向量数据已合并，记忆整理已恢复。\n"
+      : `已切换到 ${job.target.model ?? "新模型"}。\n`;
+  }
+  const code = job.error_code ?? "embedding_switch_failed";
+  if (code === "embedding_switch_cancelled") {
+    return `已取消切换，继续使用 ${job.source.model ?? "旧模型"}。\n`;
+  }
+  return `切换未完成，已恢复使用 ${job.source.model ?? "旧模型"}，数据未受影响。原因：${FAILURE_TEXT[code] ?? code}（${code}）\n`;
+}
+
+/** One line for `memhub status`, from `memory-processing.embedding_switch`. */
+export function describeEmbeddingSwitchSummary(value: unknown): string | null {
+  const summary = record(value);
+  if (!summary) return null;
+  const percent =
+    typeof summary.percent === "number" && Number.isFinite(summary.percent)
+      ? Math.floor(summary.percent)
+      : 0;
+  if (summary.state === "scanning") return "正在检查向量数据…";
+  if (summary.kind === "merge") {
+    return `正在合并旧向量数据 ${percent}%，记忆整理已暂停`;
+  }
+  if (summary.state === "failed") return "切换未完成，正在恢复旧向量模型";
+  return `切换中 ${percent}%，记忆整理已暂停`;
+}
+
+// ---------------------------------------------------------------------------
+// Flows
+// ---------------------------------------------------------------------------
+
+function document(
+  command: string,
+  fields: Record<string, unknown>,
+): Record<string, unknown> {
+  return { schema_version: 1, product: PRODUCT, command, ...fields };
+}
+
+function emitDocument(io: SwitchIo, value: Record<string, unknown>): void {
+  io.emit(`${JSON.stringify(value)}\n`);
+}
+
+async function requestPlan(
+  profileId: string,
+  io: SwitchIo,
+): Promise<
+  | { state: "plan"; plan: EmbeddingSwitchPlan }
+  | { state: "unsupported" }
+  | { state: "failed"; code: string }
+> {
+  const outcome = await io.operations.post<unknown>(
+    "/api/v1/embedding-switches/plan",
+    { profile_id: profileId },
+  );
+  if (outcome.state === "committed") {
+    const plan = parsePlan(outcome.data);
+    // Not a plan: activation itself still refuses an embedding change.
+    return plan ? { state: "plan", plan } : { state: "unsupported" };
+  }
+  if (outcome.state === "rejected") {
+    // A Core before the registry has no plan route: activation as before.
+    if (
+      outcome.http_status === 404 &&
+      outcome.code === "http_404" &&
+      isBareNotFound(outcome.body)
+    ) {
+      return { state: "unsupported" };
+    }
+    const plan = parsePlan(record(outcome.body)?.plan);
+    if (plan) return { state: "plan", plan };
+    return { state: "failed", code: outcome.code };
+  }
+  return { state: "failed", code: outcome.code };
+}
+
+function emitActivation(io: SwitchIo, result: ModelWriteDocument): number {
+  io.emit(
+    io.asJson ? `${JSON.stringify(result)}\n` : renderModelWriteText(result),
+  );
+  return result.state === "committed" ? EXIT_OK : EXIT_FAILED;
+}
+
+/**
+ * `memhub models activate <id> [--yes] [--wait|--no-wait] [--json]`.
+ *
+ * Asks Core for the plan first. No embedding change: activate as before.
+ * An embedding change: show the plan, confirm (`--yes`, or a prompt on a
+ * terminal; exit 2 otherwise), start the switch and follow it.
+ */
+export async function activateWithEmbeddingSwitch(
+  profileId: string,
+  options: ActivateOptions,
+  io: SwitchIo,
+): Promise<number> {
+  if (!UUID.test(profileId)) {
+    return emitActivation(
+      io,
+      await activateModelProfile(profileId, io.operations),
+    );
+  }
+  const planned = await requestPlan(profileId, io);
+  if (planned.state === "unsupported") {
+    const activated = await activateOrPlan(profileId, io);
+    return activated.state === "plan"
+      ? confirmAndSwitch(activated.plan, options, io)
+      : emitActivation(io, activated.result);
+  }
+  if (planned.state === "failed") {
+    return reject(io, "models activate", planned.code);
+  }
+  const plan = planned.plan;
+  if (!plan.needed) {
+    if (!io.asJson && plan.reason === "same_embedding") {
+      io.emit("向量模型未变化，无需重新生成向量。\n");
+    }
+    const activated = await activateOrPlan(profileId, io);
+    if (activated.state === "plan") {
+      return confirmAndSwitch(activated.plan, options, io);
+    }
+    return emitActivation(io, activated.result);
+  }
+  return confirmAndSwitch(plan, options, io);
+}
+
+async function activateOrPlan(
+  profileId: string,
+  io: SwitchIo,
+): Promise<
+  | { state: "plan"; plan: EmbeddingSwitchPlan }
+  | { state: "activated"; result: ModelWriteDocument }
+> {
+  const result: OperationOutcome<unknown> = await io.operations.post<unknown>(
+    `/api/v1/model-profiles/${encodeURIComponent(profileId)}/activate`,
+    {},
+  );
+  if (
+    result.state === "rejected" &&
+    result.code === "embedding_switch_required"
+  ) {
+    const plan = parsePlan(record(result.body)?.plan);
+    if (plan) return { state: "plan", plan };
+  }
+  return { state: "activated", result: modelProfileResult(profileId, result) };
+}
+
+function reject(io: SwitchIo, command: string, code: string): number {
+  if (io.asJson) {
+    emitDocument(io, document(command, { state: "rejected", code }));
+  } else {
+    io.emit(`${command} 未完成：${blockerText(code)}（${code}）\n`);
+  }
+  return EXIT_FAILED;
+}
+
+async function confirmAndSwitch(
+  plan: EmbeddingSwitchPlan,
+  options: ActivateOptions,
+  io: SwitchIo,
+): Promise<number> {
+  if (plan.blockers.length > 0) {
+    if (io.asJson) {
+      emitDocument(
+        io,
+        document("models activate", {
+          state: "blocked",
+          code: plan.blockers[0],
+          plan,
+        }),
+      );
+    } else {
+      io.emit(renderPlanText(plan));
+    }
+    return EXIT_FAILED;
+  }
+  if (!options.confirmed) {
+    const ask = io.interactive && !io.asJson ? io.confirm : undefined;
+    if (ask === undefined) {
+      if (io.asJson) {
+        emitDocument(
+          io,
+          document("models activate", {
+            state: "confirmation_required",
+            code: "embedding_switch_required",
+            plan,
+            next_step: `${PRODUCT} models activate ${plan.target_profile_id} --yes`,
+          }),
+        );
+      } else {
+        io.emit(`${renderPlanText(plan)}重新运行并加上 --yes 以确认\n`);
+      }
+      return EXIT_USAGE;
+    }
+    io.emit(renderPlanText(plan));
+    if (!(await ask("继续？[y/N] "))) {
+      io.emit("未开始切换，仍在使用原来的向量模型。\n");
+      return EXIT_OK;
+    }
+  }
+  const started = await io.operations.post<unknown>(
+    "/api/v1/embedding-switches",
+    {
+      profile_id: plan.target_profile_id,
+      expected_revision: plan.target_revision,
+      plan_token: plan.plan_token,
+      requested_by: "cli",
+    },
+  );
+  if (started.state !== "committed") {
+    return reject(io, "models activate", started.code);
+  }
+  const job = parseJob(started.data);
+  if (!job) return reject(io, "models activate", "embedding_switch_invalid");
+  const follow = options.follow ?? io.interactive;
+  if (!follow) {
+    if (io.asJson) {
+      emitDocument(io, document("models activate", progressFields(job)));
+    } else {
+      io.emit(
+        `已开始切换向量模型（${job.job_id}）。用 memhub models switch status 查看进度。\n`,
+      );
+    }
+    return EXIT_OK;
+  }
+  return followJob(job, io, "models activate");
+}
+
+function progressFields(job: EmbeddingSwitchJob): Record<string, unknown> {
+  return {
+    state: job.state,
+    job_id: job.job_id,
+    kind: job.kind,
+    phase: job.progress.phase,
+    percent: job.progress.percent,
+    done: job.progress.done,
+    total: job.progress.total,
+    eta_s: job.progress.eta_s,
+    ...(job.error_code ? { code: job.error_code } : {}),
+  };
+}
+
+async function readCurrent(io: SwitchIo): Promise<SwitchCurrent | null> {
+  const outcome = await io.reader<unknown>(
+    "/api/v1/embedding-switches/current",
+  );
+  return outcome.state === "ok" ? parseCurrent(outcome.data) : null;
+}
+
+/** Poll `current` until the job ends or the user stops watching. */
+async function followJob(
+  started: EmbeddingSwitchJob,
+  io: SwitchIo,
+  command: string,
+): Promise<number> {
+  const wait = io.wait ?? defaultWait;
+  const signal = io.signal ?? new AbortController().signal;
+  let last = "";
+  let job = started;
+  const show = (value: EmbeddingSwitchJob) => {
+    const line = io.asJson
+      ? JSON.stringify(document(command, progressFields(value)))
+      : renderProgressLine(value);
+    if (line !== last) {
+      io.emit(`${line}\n`);
+      last = line;
+    }
+  };
+  show(job);
+  if (!io.asJson) {
+    io.emit(
+      "（Ctrl-C 只停止显示；用 `memhub models switch cancel` 取消切换）\n",
+    );
+  }
+  while (!TERMINAL.has(job.state)) {
+    try {
+      await wait(POLL_MS, signal);
+    } catch {
+      // Aborted below.
+    }
+    if (signal.aborted) {
+      if (!io.asJson) {
+        io.emit(
+          "已停止显示进度；切换仍在后台进行。用 `memhub models switch cancel` 取消。\n",
+        );
+      }
+      return EXIT_OK;
+    }
+    const current = await readCurrent(io);
+    if (current === null) continue;
+    const next =
+      current.job?.job_id === job.job_id
+        ? current.job
+        : current.last_finished?.job_id === job.job_id
+          ? current.last_finished
+          : null;
+    if (next === null) continue;
+    job = next;
+    show(job);
+  }
+  if (io.asJson) {
+    emitDocument(
+      io,
+      document(command, {
+        ...progressFields(job),
+        result: job.state === "done" ? "switched" : "rolled_back",
+      }),
+    );
+  } else {
+    io.emit(renderOutcomeText(job));
+  }
+  return job.state === "done" ? EXIT_OK : EXIT_FAILED;
+}
+
+function defaultWait(milliseconds: number, signal: AbortSignal): Promise<void> {
+  return new Promise((resolve, reject) => {
+    if (signal.aborted) {
+      reject(new Error("aborted"));
+      return;
+    }
+    const timer = setTimeout(() => {
+      signal.removeEventListener("abort", onAbort);
+      resolve();
+    }, milliseconds);
+    const onAbort = () => {
+      clearTimeout(timer);
+      reject(new Error("aborted"));
+    };
+    signal.addEventListener("abort", onAbort, { once: true });
+  });
+}
+
+/** `memhub models switch status [--json]`. */
+export async function switchStatus(io: SwitchIo): Promise<number> {
+  const outcome = await io.reader<unknown>(
+    "/api/v1/embedding-switches/current",
+  );
+  if (outcome.state !== "ok")
+    return reject(io, "models switch status", outcome.code);
+  const current = parseCurrent(outcome.data);
+  if (!current) {
+    return reject(io, "models switch status", "embedding_switch_invalid");
+  }
+  if (io.asJson) {
+    emitDocument(
+      io,
+      document("models switch status", {
+        state: current.phase,
+        writes_paused: current.writes_paused,
+        job: current.job ? progressFields(current.job) : null,
+        last_finished: current.last_finished
+          ? progressFields(current.last_finished)
+          : null,
+      }),
+    );
+    return EXIT_OK;
+  }
+  if (current.job) {
+    io.emit(
+      `${renderProgressLine(current.job)}\n记忆整理已暂停，检索不受影响。\n`,
+    );
+  } else if (current.phase === "scanning") {
+    io.emit("正在检查向量数据…\n");
+  } else if (current.last_finished) {
+    io.emit(
+      `没有进行中的向量模型切换。上一次：${renderOutcomeText(current.last_finished)}`,
+    );
+  } else {
+    io.emit("没有进行中的向量模型切换。\n");
+  }
+  return EXIT_OK;
+}
+
+/** `memhub models switch cancel [--json]`: cancel the running job, if any. */
+export async function switchCancel(io: SwitchIo): Promise<number> {
+  const current = await readCurrent(io);
+  if (current === null) {
+    return reject(io, "models switch cancel", "embedding_switch_unavailable");
+  }
+  if (!current.job) {
+    return reject(io, "models switch cancel", "embedding_switch_not_found");
+  }
+  const outcome = await io.operations.post<unknown>(
+    `/api/v1/embedding-switches/${current.job.job_id}/cancel`,
+    {},
+  );
+  if (outcome.state !== "committed") {
+    return reject(io, "models switch cancel", outcome.code);
+  }
+  const job = parseJob(outcome.data) ?? current.job;
+  if (io.asJson) {
+    emitDocument(
+      io,
+      document("models switch cancel", {
+        ...progressFields(job),
+        cancel_requested: true,
+      }),
+    );
+  } else {
+    io.emit("已请求取消；当前批次完成后回滚，继续使用原来的向量模型。\n");
+  }
+  return EXIT_OK;
+}
+
+interface SpaceRow {
+  space_id: string;
+  state: string;
+  model: string | null;
+  dims: number | null;
+  vectors: number | null;
+  keep_until: string | null;
+}
+
+function spaceRows(value: unknown): SpaceRow[] | null {
+  const body = record(value);
+  if (!body || !Array.isArray(body.spaces)) return null;
+  const rows: SpaceRow[] = [];
+  for (const item of body.spaces) {
+    const row = record(item);
+    const spaceId = str(row?.space_id, 64);
+    const state = str(row?.state, 16);
+    if (!row || !spaceId || !state) return null;
+    if (state === "dropped") continue;
+    rows.push({
+      space_id: spaceId,
+      state,
+      model: str(row.model),
+      dims: int(row.dims) ?? int(row.name_dims),
+      vectors: int(row.vectors),
+      keep_until: str(row.keep_until, 64),
+    });
+  }
+  return rows;
+}
+
+const SPACE_STATE: Record<string, string> = {
+  live: "使用中",
+  building: "正在生成",
+  stray: "待合并",
+  retired: "已停用",
+};
+
+/** `memhub models spaces [--json]`. */
+export async function listSpaces(io: SwitchIo): Promise<number> {
+  const outcome = await io.reader<unknown>("/api/v1/embedding-spaces");
+  if (outcome.state !== "ok") return reject(io, "models spaces", outcome.code);
+  const rows = spaceRows(outcome.data);
+  if (!rows) return reject(io, "models spaces", "embedding_spaces_invalid");
+  const body = record(outcome.data) ?? {};
+  const unregistered = Array.isArray(body.scanned)
+    ? body.scanned
+        .map(record)
+        .filter(
+          (item): item is Record<string, unknown> =>
+            item !== null && item.state === "unregistered",
+        )
+        .map((item) => ({
+          collection_base: str(item.collection_base) ?? "",
+          vectors: int(item.vectors) ?? 0,
+        }))
+    : [];
+  if (io.asJson) {
+    emitDocument(
+      io,
+      document("models spaces", {
+        state: "ok",
+        spaces: rows,
+        unregistered,
+        scan_error:
+          typeof body.scan_error === "string" && CODE.test(body.scan_error)
+            ? body.scan_error
+            : null,
+      }),
+    );
+    return EXIT_OK;
+  }
+  const lines = ["向量空间："];
+  for (const row of rows) {
+    const dims = row.dims === null ? "维度未知" : `${row.dims} 维`;
+    const keep =
+      row.state === "retired" && row.keep_until
+        ? `，保留到 ${row.keep_until.slice(0, 10)}`
+        : "";
+    lines.push(
+      `  ${row.space_id}  ${SPACE_STATE[row.state] ?? row.state}  ${row.model ?? "未知模型"}（${dims}）  ${row.vectors ?? "?"} 条${keep}`,
+    );
+  }
+  for (const item of unregistered) {
+    lines.push(
+      `  （未登记）${item.collection_base}  ${item.vectors} 条，下次启动时合并`,
+    );
+  }
+  if (rows.some((row) => row.state === "retired")) {
+    lines.push(
+      "清理已停用的空间：memhub models spaces --cleanup <space-id> --yes",
+    );
+  }
+  io.emit(`${lines.join("\n")}\n`);
+  return EXIT_OK;
+}
+
+/** `memhub models spaces --cleanup <space-id> --yes`: drop a retired space now. */
+export async function cleanupSpace(
+  spaceId: string,
+  io: SwitchIo,
+): Promise<number> {
+  if (!UUID.test(spaceId)) {
+    return reject(io, "models spaces", "embedding_space_not_found");
+  }
+  const outcome = await io.operations.delete<unknown>(
+    `/api/v1/embedding-spaces/${spaceId}`,
+  );
+  if (outcome.state !== "committed") {
+    return reject(io, "models spaces", outcome.code);
+  }
+  if (io.asJson) {
+    emitDocument(
+      io,
+      document("models spaces", { state: "dropped", space_id: spaceId }),
+    );
+  } else {
+    io.emit(`已清理旧向量数据：${spaceId}\n`);
+  }
+  return EXIT_OK;
+}

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

@@ -510,15 +510,98 @@ describe("models add", () => {
     expect(result.stdout + result.stderr).not.toContain("SYNTHETIC_LOOSE_KEY");
   });
 
-  it("activates the new profile with --activate", async () => {
+  it("probes the new profile before activating it with --activate", async () => {
     const configFile = await modelConfigFile();
-    transport.post.mockImplementation(async (url: string) =>
-      url === "/api/v1/model-profiles"
-        ? { status: 200, data: PROFILE }
-        : url === "/api/v1/model-profiles/profile-1/activate"
-          ? { status: 200, data: { ...PROFILE, is_active: true } }
-          : { status: 404, data: {} },
+    let probeId: string | undefined;
+    transport.get.mockImplementation(async (url: string) => {
+      if (url === "/api/v1/model-profiles") {
+        return { status: 200, data: [PROBE_PROFILE] };
+      }
+      const match = /^\/api\/v1\/model-probe-operations\/(.+)$/.exec(url);
+      if (match) {
+        return {
+          status: 200,
+          data:
+            probeId === undefined
+              ? probeNotFound(match[1])
+              : probeReceiptPassing(match[1]),
+        };
+      }
+      return { status: 404, data: {} };
+    });
+    transport.post.mockImplementation(async (url: string, body: unknown) => {
+      if (url === "/api/v1/model-profiles") {
+        return { status: 200, data: PROBE_PROFILE };
+      }
+      if (url === `/api/v1/model-profiles/${PROBE_PROFILE.profile_id}/probe`) {
+        probeId = (body as { operation_id: string }).operation_id;
+        return { status: 200, data: probePending(probeId) };
+      }
+      if (url === "/api/v1/embedding-switches/plan") {
+        return { status: 200, data: samePlan() };
+      }
+      if (
+        url === `/api/v1/model-profiles/${PROBE_PROFILE.profile_id}/activate`
+      ) {
+        return {
+          status: 200,
+          data: {
+            ...PROBE_PROFILE,
+            is_active: true,
+            embedding_model: "synthetic-embedding",
+          },
+        };
+      }
+      return { status: 404, data: {} };
+    });
+    const result = await capturedRun(
+      ["models", "add", "--config-file", configFile, "--activate", "--json"],
+      { watchWait: async () => undefined },
     );
+    expect(result.code).toBe(0);
+    const lines = result.stdout
+      .trim()
+      .split("\n")
+      .map((line) => JSON.parse(line));
+    expect(lines[0].probe).toMatchObject({ state: "completed" });
+    expect(lines.at(-1)).toMatchObject({ state: "committed" });
+    expect(transport.post.mock.calls.map(([url]) => url)).toEqual([
+      "/api/v1/model-profiles",
+      `/api/v1/model-profiles/${PROBE_PROFILE.profile_id}/probe`,
+      "/api/v1/embedding-switches/plan",
+      `/api/v1/model-profiles/${PROBE_PROFILE.profile_id}/activate`,
+    ]);
+  });
+
+  it("does not activate a profile whose probe fails", async () => {
+    const configFile = await modelConfigFile();
+    let probeId: string | undefined;
+    transport.get.mockImplementation(async (url: string) => {
+      if (url === "/api/v1/model-profiles") {
+        return { status: 200, data: [PROBE_PROFILE] };
+      }
+      const match = /^\/api\/v1\/model-probe-operations\/(.+)$/.exec(url);
+      if (match) {
+        return {
+          status: 200,
+          data:
+            probeId === undefined
+              ? probeNotFound(match[1])
+              : probeReceipt(match[1]),
+        };
+      }
+      return { status: 404, data: {} };
+    });
+    transport.post.mockImplementation(async (url: string, body: unknown) => {
+      if (url === "/api/v1/model-profiles") {
+        return { status: 200, data: PROBE_PROFILE };
+      }
+      if (url.endsWith("/probe")) {
+        probeId = (body as { operation_id: string }).operation_id;
+        return { status: 200, data: probeReceipt(probeId) };
+      }
+      return { status: 404, data: {} };
+    });
     const result = await capturedRun([
       "models",
       "add",
@@ -527,14 +610,12 @@ describe("models add", () => {
       "--activate",
       "--json",
     ]);
-    expect(result.code).toBe(0);
-    expect(JSON.parse(result.stdout).activation).toEqual({
-      state: "committed",
-    });
-    expect(transport.post.mock.calls.map(([url]) => url)).toEqual([
-      "/api/v1/model-profiles",
-      "/api/v1/model-profiles/profile-1/activate",
-    ]);
+    expect(result.code).toBe(1);
+    expect(
+      transport.post.mock.calls.some(([url]) =>
+        String(url).endsWith("/activate"),
+      ),
+    ).toBe(false);
   });
 
   it("recovers an unknown create through its operation receipt", async () => {
@@ -752,6 +833,54 @@ function probePending(operationId: string) {
   };
 }
 
+function samePlan() {
+  const space = {
+    space_id: null,
+    model: "synthetic-embedding",
+    dims: 8,
+    collection_base: "",
+  };
+  return {
+    needed: false,
+    reason: "same_embedding",
+    plan_token: "token-1",
+    source: space,
+    target: space,
+    target_profile_id: PROBE_PROFILE.profile_id,
+    target_revision: 3,
+    target_provider_kind: "openai_compatible",
+    target_local: false,
+    blockers: [],
+  };
+}
+
+function probeReceiptPassing(operationId: string) {
+  const receipt = probeReceipt(operationId);
+  return {
+    ...receipt,
+    result: {
+      ...receipt.result,
+      stages: [
+        {
+          stage: "embedding",
+          ok: true,
+          code: "ok",
+          latency_ms: 1,
+          embedding_dimensions: 8,
+        },
+      ],
+      capabilities: {
+        endpoint_reachable: true,
+        model_available: true,
+        structured_output: true,
+        embedding_available: true,
+      },
+      embedding_width: 8,
+      embedding_switch_required: false,
+    },
+  };
+}
+
 function probeNotFound(operationId: string) {
   return {
     schema_version: 1,
@@ -819,7 +948,10 @@ function importJob() {
   };
 }
 
-async function capturedRun(argv: string[]) {
+async function capturedRun(
+  argv: string[],
+  controls: Parameters<typeof run>[2] = {},
+) {
   let stdout = "";
   let stderr = "";
   const originalOut = process.stdout.write;
@@ -833,7 +965,7 @@ async function capturedRun(argv: string[]) {
     return true;
   }) as typeof process.stderr.write;
   try {
-    const code = await run(argv, {});
+    const code = await run(argv, {}, controls);
     return { code, stdout, stderr };
   } finally {
     process.stdout.write = originalOut;

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

@@ -348,12 +348,25 @@ export function parseApiKey(bytes: Buffer | null): string | undefined {
   return value;
 }
 
+/** What to do about a refusal whose code alone does not say. */
+const FLOW_CODE_HINTS: Record<string, string> = {
+  hermes_root_is_profiles_container:
+    "--root 指向的是 profiles 目录本身；请指向其中一个 profile，例如 ~/.hermes/profiles/wife。",
+  hermes_root_overlaps_other_user:
+    "--root 与另一个用户已接入的 Hermes 目录相同或互相包含，会读到对方的记录；请换一个目录，或先撤销对方的接入。~/.hermes 与 ~/.hermes/profiles/<name> 可以分属两个用户。",
+};
+
 export function renderFlowText(document: FlowDocument): string {
   const lines = [
     `操作状态：${document.state}`,
     `操作 ID：${document.operation_id ?? "无"}`,
     "code" in document ? `代码：${document.code}` : "已返回有界回执。",
   ];
+  const hint =
+    "code" in document && typeof document.code === "string"
+      ? FLOW_CODE_HINTS[document.code]
+      : undefined;
+  if (hint) lines.push(hint);
   // A partial success or an all-rejected batch must name each source that was
   // not accepted; a bare "partial" leaves the user with nothing to act on.
   if (

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

@@ -233,6 +233,31 @@ describe("memories add-status", () => {
     });
   });
 
+  it("passes the retry code and time of an addition still waiting", async () => {
+    transport.get.mockResolvedValue({
+      status: 200,
+      data: {
+        ...addReceipt("pending"),
+        error_code: "model_auth_failed",
+        next_retry_at: "2026-11-02T10:00:00+00:00",
+      },
+    });
+    const json = await capturedRun([
+      "memories",
+      "add-status",
+      REQUEST,
+      "--json",
+    ]);
+    expect(JSON.parse(json.stdout).receipt).toMatchObject({
+      state: "pending",
+      error_code: "model_auth_failed",
+      next_retry_at: "2026-11-02T10:00:00+00:00",
+    });
+    const text = await capturedRun(["memories", "add-status", REQUEST]);
+    expect(text.stdout).toContain("error_code: model_auth_failed");
+    expect(text.stdout).toContain("next_retry_at: 2026-11-02T10:00:00+00:00");
+  });
+
   it("reports an unknown request id as not_found, exit 1", async () => {
     transport.get.mockResolvedValue({
       status: 404,
@@ -366,6 +391,33 @@ describe("memories update / delete pass the namespace", () => {
     );
   });
 
+  it("reports a delete answered 404 as already gone and exits 0", async () => {
+    transport.delete.mockResolvedValue({
+      status: 404,
+      data: { detail: "memory_not_found" },
+    });
+    const json = await capturedRun([
+      "memories",
+      "delete",
+      "gone-1",
+      "--yes",
+      "--json",
+    ]);
+    expect(json.code).toBe(0);
+    expect(JSON.parse(json.stdout)).toEqual({
+      schema_version: 2,
+      product: expect.any(String),
+      command: "memories delete",
+      state: "committed",
+      operation: "delete",
+      memory_id: "gone-1",
+      already_gone: true,
+    });
+    const text = await capturedRun(["memories", "delete", "gone-1", "--yes"]);
+    expect(text.code).toBe(0);
+    expect(text.stdout).toContain("未找到记忆 gone-1");
+  });
+
   it("explains an ambiguous id instead of a bare code", async () => {
     transport.delete.mockResolvedValue({
       status: 409,

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

@@ -36,15 +36,17 @@ const DEFAULTS: Record<string, boolean> = {
   session_episodes: false,
   episode_summary: false,
   intention: true,
+  intention_dedup: true,
   few_shot: false,
 };
+const THRESHOLD_DEFAULT = 0.95;
 
 function featuresState(
-  configured: Record<string, boolean> = {},
+  configured: Record<string, boolean | number> = {},
   mode = "pro",
   extra: Record<string, unknown> = {},
 ) {
-  const nonDefault: Record<string, boolean> = {};
+  const nonDefault: Record<string, boolean | number> = {};
   const features = Object.entries(DEFAULTS).map(([name, fallback]) => {
     const enabled = configured[name] ?? fallback;
     if (enabled !== fallback) nonDefault[name] = enabled;
@@ -70,7 +72,34 @@ function featuresState(
       description: name,
     };
   });
-  return { mode, features, non_default: nonDefault, ...extra };
+  const threshold =
+    (configured.intention_dedup_threshold as number | undefined) ??
+    THRESHOLD_DEFAULT;
+  if (threshold !== THRESHOLD_DEFAULT)
+    nonDefault.intention_dedup_threshold = threshold;
+  const dedupOn =
+    (configured.intention_dedup as boolean | undefined) ??
+    DEFAULTS.intention_dedup;
+  const parameters = [
+    {
+      name: "intention_dedup_threshold",
+      value: threshold,
+      configured:
+        "intention_dedup_threshold" in configured
+          ? configured.intention_dedup_threshold
+          : null,
+      default: THRESHOLD_DEFAULT,
+      minimum: 0.8,
+      maximum: 1,
+      active: dedupOn,
+      reason: dedupOn ? null : "requires_intention_dedup",
+      requires_feature: "intention_dedup",
+      sdk_field: "recall.intention_dedup_threshold",
+      env: "MEMORY_INTENTION_DEDUP_THRESHOLD",
+      description: "threshold",
+    },
+  ];
+  return { mode, features, parameters, non_default: nonDefault, ...extra };
 }
 
 beforeEach(() => {
@@ -110,11 +139,16 @@ describe("memhub settings features", () => {
     expect(result.code).toBe(0);
     const json = JSON.parse(result.stdout);
     expect(json.state).toBe("ok");
-    expect(json.features.features).toHaveLength(7);
+    expect(json.features.features).toHaveLength(8);
+    expect(json.features.parameters[0].name).toBe("intention_dedup_threshold");
     expect(transport.put).not.toHaveBeenCalled();
     const text = (await capturedRun(["settings", "features"])).stdout;
     expect(text).toContain("graph_rerank：关（默认）");
     expect(text).toContain("intention：开（默认）");
+    expect(text).toContain("intention_dedup：开（默认）");
+    expect(text).toContain(
+      "intention_dedup_threshold：0.95（默认，可设 0.8–1）",
+    );
     expect(text).toContain("先开启 session_episodes");
   });
 
@@ -160,6 +194,130 @@ describe("memhub settings features", () => {
     );
   });
 
+  it("turns intention dedup off and sets its threshold, round trip", async () => {
+    transport.put.mockResolvedValueOnce({
+      status: 200,
+      data: featuresState({ intention_dedup: false }, "pro", {
+        changed: ["intention_dedup"],
+      }),
+    });
+    const off = await capturedRun([
+      "settings",
+      "features",
+      "set",
+      "intention_dedup=false",
+      "--yes",
+      "--json",
+    ]);
+    expect(off.code).toBe(0);
+    expect(transport.put).toHaveBeenLastCalledWith(
+      "/api/v1/settings/memory-features",
+      { intention_dedup: false },
+      undefined,
+    );
+    const offJson = JSON.parse(off.stdout);
+    expect(offJson.state).toBe("committed");
+    expect(offJson.changed).toEqual(["intention_dedup"]);
+    expect(offJson.features.parameters[0].reason).toBe(
+      "requires_intention_dedup",
+    );
+
+    transport.get.mockResolvedValue({
+      status: 200,
+      data: featuresState({ intention_dedup: false }),
+    });
+    transport.put.mockResolvedValueOnce({
+      status: 200,
+      data: featuresState(
+        { intention_dedup: true, intention_dedup_threshold: 0.9 },
+        "pro",
+        { changed: ["intention_dedup", "intention_dedup_threshold"] },
+      ),
+    });
+    const on = await capturedRun([
+      "settings",
+      "features",
+      "set",
+      "intention_dedup=true",
+      "intention_dedup_threshold=0.9",
+      "--yes",
+    ]);
+    expect(on.code).toBe(0);
+    expect(transport.put).toHaveBeenLastCalledWith(
+      "/api/v1/settings/memory-features",
+      { intention_dedup: true, intention_dedup_threshold: 0.9 },
+      undefined,
+    );
+    expect(on.stdout).toContain(
+      "已更新：intention_dedup、intention_dedup_threshold",
+    );
+    expect(on.stdout).toContain("intention_dedup_threshold：0.9（已设置");
+
+    transport.get.mockResolvedValue({
+      status: 200,
+      data: featuresState({ intention_dedup_threshold: 0.9 }),
+    });
+    transport.put.mockResolvedValueOnce({
+      status: 200,
+      data: featuresState({}, "pro", {
+        changed: ["intention_dedup_threshold"],
+      }),
+    });
+    const reset = await capturedRun([
+      "settings",
+      "features",
+      "reset",
+      "intention_dedup_threshold",
+    ]);
+    expect(reset.code).toBe(0);
+    expect(transport.put).toHaveBeenLastCalledWith(
+      "/api/v1/settings/memory-features",
+      { intention_dedup_threshold: null },
+      undefined,
+    );
+  });
+
+  it("previews a threshold without --yes and refuses one out of range", async () => {
+    const preview = await capturedRun([
+      "settings",
+      "features",
+      "set",
+      "intention_dedup_threshold=0.85",
+    ]);
+    expect(preview.code).toBe(0);
+    expect(preview.stdout).toContain("- intention_dedup_threshold = 0.85");
+    for (const value of ["0.5", "0.79", "1.01", "2", "-0.9", "abc", "1e0"]) {
+      const result = await capturedRun([
+        "settings",
+        "features",
+        "set",
+        `intention_dedup_threshold=${value}`,
+        "--yes",
+      ]);
+      expect(result.code, value).toBe(2);
+    }
+    expect(transport.put).not.toHaveBeenCalled();
+  });
+
+  it("does not send a threshold to a Runtime that does not list it", async () => {
+    const { parameters: _unused, ...older } = featuresState();
+    transport.get.mockResolvedValue({ status: 200, data: older });
+    const result = await capturedRun([
+      "settings",
+      "features",
+      "set",
+      "intention_dedup_threshold=0.9",
+      "--yes",
+      "--json",
+    ]);
+    expect(result.code).toBe(1);
+    expect(JSON.parse(result.stdout)).toMatchObject({
+      state: "rejected",
+      code: "memory_feature_unsupported",
+    });
+    expect(transport.put).not.toHaveBeenCalled();
+  });
+
   it("does nothing when the values are already set", async () => {
     transport.get.mockResolvedValue({
       status: 200,
@@ -210,6 +368,8 @@ describe("memhub settings features", () => {
       ["settings", "features", "set", "graph_rerank=yes"],
       ["settings", "features", "set", "graph_rerank"],
       ["settings", "features", "set", "few_shot=true", "few_shot=false"],
+      ["settings", "features", "set", "intention_dedup=0.9"],
+      ["settings", "features", "set", "intention_dedup_threshold=true"],
       ["settings", "features", "reset", "nope"],
       ["settings", "features", "toggle"],
     ]) {
@@ -269,7 +429,11 @@ describe("status pipeline features", () => {
         last_evolve_at: null,
         graph_build: { state: "idle", users: {} },
         evolve: { mode: "pro", schedule: null, running: [], users: {} },
-        features: { episode_recall: true, intention: false },
+        features: {
+          episode_recall: true,
+          intention: false,
+          intention_dedup_threshold: 0.9,
+        },
       },
     };
     const report = await composeStatusReport({
@@ -284,9 +448,12 @@ describe("status pipeline features", () => {
     expect(report.pipeline?.features).toEqual({
       episode_recall: true,
       intention: false,
+      intention_dedup_threshold: 0.9,
     });
     const text = renderStatusText(report, "MemHub");
-    expect(text).toContain("SDK 功能：episode_recall=开、intention=关");
+    expect(text).toContain(
+      "SDK 功能：episode_recall=开、intention=关、intention_dedup_threshold=0.9",
+    );
   });
 });
 

memhub/apps/cli/src/memory-features-flow.ts

@@ -2,7 +2,8 @@
  * `memhub settings features [set <name>=<true|false> ... | reset [<name> ...]]`.
  *
  * The SDK's optional retrieval and extraction features (graph rerank, episode
- * recall, the episode write side, intention, few-shot). One global setting in
+ * recall, the episode write side, intention and its dedup, few-shot), plus the
+ * intention dedup threshold, the one numeric setting. One global setting in
  * the Runtime; an unset feature keeps the SDK default, so an install nobody
  * touched behaves as before. `set` prints its plan first and needs `--yes`,
  * like `settings mode`, because some features spend model calls; `reset`
@@ -20,10 +21,19 @@ export const MEMORY_FEATURES = [
   "session_episodes",
   "episode_summary",
   "intention",
+  "intention_dedup",
   "few_shot",
 ] as const;
 export type MemoryFeature = (typeof MEMORY_FEATURES)[number];
 
+/** Numeric settings, with the range the Runtime accepts (inclusive). */
+export const MEMORY_PARAMETERS = {
+  intention_dedup_threshold: { minimum: 0.8, maximum: 1 },
+} as const;
+export type MemoryParameter = keyof typeof MEMORY_PARAMETERS;
+export type MemorySetting = MemoryFeature | MemoryParameter;
+type SettingValues = Partial<Record<MemorySetting, boolean | number>>;
+
 const FEATURE_LABEL: Record<MemoryFeature, string> = {
   graph_rerank: "图谱重排（沿知识图谱的边传播支持度；仅 ultra）",
   same_series_timeline:
@@ -33,6 +43,8 @@ const FEATURE_LABEL: Record<MemoryFeature, string> = {
   session_episodes: "片段写入（同一会话提取的记忆归入同一片段）",
   episode_summary: "片段摘要（片段结束时总结一次；每个片段一次模型调用）",
   intention: "意图提取（随事实一起提取用户的计划与意图）",
+  intention_dedup:
+    "意图判重（检索时把同一天、相似度达到阈值的意图视为重复，只返回最早一条并删除其余；关闭则不判重、不删除）",
   few_shot: "提取示例（在提取提示里附上示例；不加调用，输入更长）",
 };
 
@@ -41,21 +53,42 @@ const REASON_TEXT: Record<string, string> = {
   requires_pro: "lite 模式下不生效（需要 pro 或 ultra）",
   requires_ultra: "当前模式下不生效（需要 ultra）",
   requires_graph_rerank: "需要先开启并生效 graph_rerank",
+  requires_intention_dedup: "intention_dedup 已关闭，阈值不起作用",
+};
+
+const PARAMETER_LABEL: Record<MemoryParameter, string> = {
+  intention_dedup_threshold: "意图判重阈值（余弦相似度，越高保留越多）",
 };
 
 export type FeaturesCommand =
   | { kind: "show" }
   | {
       kind: "set";
-      values: Partial<Record<MemoryFeature, boolean>>;
+      values: SettingValues;
       confirmed: boolean;
     }
-  | { kind: "reset"; names: MemoryFeature[] };
+  | { kind: "reset"; names: MemorySetting[] };
 
 function isFeature(value: string): value is MemoryFeature {
   return (MEMORY_FEATURES as readonly string[]).includes(value);
 }
 
+function isParameter(value: string): value is MemoryParameter {
+  return Object.hasOwn(MEMORY_PARAMETERS, value);
+}
+
+function isSetting(value: string): value is MemorySetting {
+  return isFeature(value) || isParameter(value);
+}
+
+/** A parameter's value: a plain decimal in its range; null = usage. */
+function parameterValue(name: MemoryParameter, raw: string): number | null {
+  if (!/^\d+(\.\d+)?$/.test(raw)) return null;
+  const value = Number(raw);
+  const { minimum, maximum } = MEMORY_PARAMETERS[name];
+  return value >= minimum && value <= maximum ? value : null;
+}
+
 /** Arguments after `settings features`; null = usage. */
 export function parseFeaturesCommand(
   values: readonly string[],
@@ -68,18 +101,28 @@ export function parseFeaturesCommand(
   const positional = tail.filter((value) => value !== "--yes");
   if (verb === "set") {
     if (positional.length === 0) return null;
-    const parsed: Partial<Record<MemoryFeature, boolean>> = {};
+    const parsed: SettingValues = {};
     for (const item of positional) {
-      const match = /^([a-z_]+)=(true|false)$/.exec(item);
-      if (!match || !isFeature(match[1]) || match[1] in parsed) return null;
-      parsed[match[1]] = match[2] === "true";
+      const match = /^([a-z_]+)=(.+)$/.exec(item);
+      if (!match || match[1] in parsed) return null;
+      const [, name, raw] = match;
+      if (isFeature(name)) {
+        if (raw !== "true" && raw !== "false") return null;
+        parsed[name] = raw === "true";
+      } else if (isParameter(name)) {
+        const value = parameterValue(name, raw);
+        if (value === null) return null;
+        parsed[name] = value;
+      } else {
+        return null;
+      }
     }
     return { kind: "set", values: parsed, confirmed: yes === 1 };
   }
   if (verb === "reset") {
     if (new Set(positional).size !== positional.length) return null;
-    if (!positional.every(isFeature)) return null;
-    return { kind: "reset", names: positional as MemoryFeature[] };
+    if (!positional.every(isSetting)) return null;
+    return { kind: "reset", names: positional as MemorySetting[] };
   }
   return null;
 }
@@ -96,11 +139,26 @@ export interface FeatureState {
   description: string;
 }
 
+export interface ParameterState {
+  name: MemoryParameter;
+  value: number;
+  configured: number | null;
+  default: number;
+  minimum: number;
+  maximum: number;
+  active: boolean;
+  reason: string | null;
+  requires_feature: string;
+  description: string;
+}
+
 export interface FeaturesState {
   mode: string;
   features: FeatureState[];
-  non_default: Partial<Record<MemoryFeature, boolean>>;
-  changed?: MemoryFeature[];
+  /** Absent from a Runtime older than the intention dedup threshold. */
+  parameters?: ParameterState[];
+  non_default: SettingValues;
+  changed?: MemorySetting[];
 }
 
 function featuresState(value: unknown): FeaturesState | null {
@@ -125,6 +183,20 @@ function featuresState(value: unknown): FeaturesState | null {
       return null;
     }
   }
+  if (item.parameters !== undefined) {
+    if (!Array.isArray(item.parameters)) return null;
+    for (const parameter of item.parameters) {
+      if (
+        !parameter ||
+        typeof parameter !== "object" ||
+        typeof (parameter as ParameterState).name !== "string" ||
+        typeof (parameter as ParameterState).value !== "number" ||
+        typeof (parameter as ParameterState).active !== "boolean"
+      ) {
+        return null;
+      }
+    }
+  }
   return item as unknown as FeaturesState;
 }
 
@@ -137,12 +209,12 @@ export type FeaturesDocument = {
   | {
       state: "preview";
       features: FeaturesState;
-      target: Partial<Record<MemoryFeature, boolean>>;
+      target: SettingValues;
       applied: false;
       next_step: string;
     }
   | { state: "unchanged"; features: FeaturesState }
-  | { state: "committed"; features: FeaturesState; changed: MemoryFeature[] }
+  | { state: "committed"; features: FeaturesState; changed: MemorySetting[] }
   | { state: "rejected" | "unknown" | "unavailable"; code: string }
 );
 
@@ -170,13 +242,23 @@ export async function runFeaturesCommand(
   if (command.kind === "show") {
     return { ...BASE, state: "ok", features: current };
   }
+  // What a person set, per name this Runtime lists; null = the default.
+  const configured = new Map<string, boolean | number | null>([
+    ...current.features.map(
+      (feature) => [feature.name, feature.configured] as const,
+    ),
+    ...(current.parameters ?? []).map(
+      (parameter) => [parameter.name, parameter.configured] as const,
+    ),
+  ]);
   let body: Record<string, unknown>;
   if (command.kind === "set") {
-    const configured = new Map(
-      current.features.map((feature) => [feature.name, feature.configured]),
-    );
+    if (Object.keys(command.values).some((name) => !configured.has(name))) {
+      // An older Runtime does not know the name; it would answer 422.
+      return { ...BASE, state: "rejected", code: "memory_feature_unsupported" };
+    }
     const differs = Object.entries(command.values).some(
-      ([name, value]) => configured.get(name as MemoryFeature) !== value,
+      ([name, value]) => configured.get(name) !== value,
     );
     if (!differs) return { ...BASE, state: "unchanged", features: current };
     if (!command.confirmed) {
@@ -197,16 +279,10 @@ export async function runFeaturesCommand(
     const names =
       command.names.length > 0
         ? command.names
-        : current.features
-            .filter((feature) => feature.configured !== null)
-            .map((feature) => feature.name);
-    if (
-      names.every(
-        (name) =>
-          current.features.find((feature) => feature.name === name)
-            ?.configured === null,
-      )
-    ) {
+        : [...configured]
+            .filter(([, value]) => value !== null)
+            .map(([name]) => name as MemorySetting);
+    if (names.every((name) => (configured.get(name) ?? null) === null)) {
       return { ...BASE, state: "unchanged", features: current };
     }
     body = Object.fromEntries(names.map((name) => [name, null]));
@@ -233,6 +309,16 @@ export function featuresExitCode(document: FeaturesDocument): number {
     : 1;
 }
 
+function parameterLine(parameter: ParameterState): string {
+  const label = PARAMETER_LABEL[parameter.name] ?? parameter.name;
+  const origin = parameter.configured === null ? "默认" : "已设置";
+  const activity =
+    !parameter.active && parameter.reason
+      ? `，${REASON_TEXT[parameter.reason] ?? parameter.reason}`
+      : "";
+  return `${parameter.name}：${parameter.value}（${origin}${activity}，可设 ${parameter.minimum}–${parameter.maximum}）— ${label}`;
+}
+
 function featureLine(feature: FeatureState): string {
   const label = FEATURE_LABEL[feature.name] ?? feature.name;
   const value = feature.enabled ? "开" : "关";
@@ -251,6 +337,8 @@ export function renderFeaturesText(document: FeaturesDocument): string {
   const state = document.features;
   const lines = [`当前模式：${state.mode}`];
   for (const feature of state.features) lines.push(featureLine(feature));
+  for (const parameter of state.parameters ?? [])
+    lines.push(parameterLine(parameter));
   lines.push(
     "片段召回（episode_recall）只对带片段的记忆有用：先开启 session_episodes，之后提取的记忆才会带片段。",
   );
@@ -258,7 +346,9 @@ export function renderFeaturesText(document: FeaturesDocument): string {
   if (document.state === "preview") {
     lines.push("将设置：");
     for (const [name, value] of Object.entries(document.target)) {
-      lines.push(`- ${name} = ${value ? "开" : "关"}`);
+      lines.push(
+        `- ${name} = ${typeof value === "number" ? value : value ? "开" : "关"}`,
+      );
     }
     lines.push(`未执行任何改动。确认后运行：${document.next_step}`);
   }

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

@@ -0,0 +1,273 @@
+import { beforeEach, describe, expect, it, vi } from "vitest";
+
+import { run } from "./cli.js";
+import { parseLanguageCommand } from "./memory-language-flow.js";
+import { composeStatusReport, renderStatusText } from "./status-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(),
+    post: vi.fn(),
+    isAxiosError: () => false,
+  },
+}));
+
+const runtime = vi.hoisted(() => ({
+  inspectRuntimeStatus: vi.fn(),
+  discoverRuntimeAttachment: vi.fn(),
+}));
+vi.mock("@one-memory/runtime-control", async (importOriginal) => ({
+  ...(await importOriginal<typeof import("@one-memory/runtime-control")>()),
+  ...runtime,
+}));
+
+function languageState(uiLanguage: string | null, extra = {}) {
+  const sdk = uiLanguage === null ? "auto" : uiLanguage;
+  return {
+    ui_language: uiLanguage,
+    sdk_language: sdk,
+    languages: [
+      "en",
+      "zh-Hans",
+      "zh-Hant",
+      "ja",
+      "es",
+      "de",
+      "pt",
+      "fr",
+      "ko",
+      "ru",
+      "id",
+    ],
+    ...extra,
+  };
+}
+
+beforeEach(() => {
+  vi.clearAllMocks();
+  for (const method of Object.values(transport)) method.mockReset();
+  runtime.inspectRuntimeStatus.mockResolvedValue({
+    state: "running",
+    code: "runtime_verified",
+    instanceId: "instance-1",
+    host: "127.0.0.1",
+    port: 8765,
+    version: "1.2.3",
+  });
+  runtime.discoverRuntimeAttachment.mockResolvedValue({
+    instanceId: "instance-1",
+    apiToken: "synthetic-runtime-token",
+    host: "127.0.0.1",
+    port: 8765,
+    servicePid: 4242,
+    health: {
+      status: "ok",
+      service: "one-memory-core",
+      version: "1.2.3",
+      instance_id: "instance-1",
+    },
+  });
+  transport.get.mockImplementation(async (url: string) =>
+    url === "/api/v1/settings/ui-language"
+      ? { status: 200, data: languageState(null) }
+      : { status: 404, data: {} },
+  );
+});
+
+describe("memhub settings language", () => {
+  it("shows the display language and the SDK prompt language", async () => {
+    const result = await capturedRun(["settings", "language", "--json"]);
+    expect(result.code).toBe(0);
+    const json = JSON.parse(result.stdout);
+    expect(json).toMatchObject({
+      command: "settings language",
+      state: "ok",
+      language: { ui_language: null, sdk_language: "auto" },
+    });
+    expect(transport.put).not.toHaveBeenCalled();
+    const text = (await capturedRun(["settings", "language"])).stdout;
+    expect(text).toContain("界面语言：未设置（SDK 自动识别）");
+    expect(text).toContain("SDK 提示语言：auto");
+  });
+
+  it("sets a language at once and reports the SDK language", async () => {
+    transport.put.mockResolvedValue({
+      status: 200,
+      data: languageState("ja", { rebuilt: true }),
+    });
+    const result = await capturedRun(["settings", "language", "ja", "--json"]);
+    expect(result.code).toBe(0);
+    expect(transport.put).toHaveBeenCalledWith(
+      "/api/v1/settings/ui-language",
+      { ui_language: "ja" },
+      undefined,
+    );
+    expect(JSON.parse(result.stdout)).toMatchObject({
+      state: "committed",
+      rebuilt: true,
+      language: { ui_language: "ja", sdk_language: "ja" },
+    });
+    const text = (await capturedRun(["settings", "language", "ja"])).stdout;
+    expect(text).toContain("界面语言：ja（日本語）");
+  });
+
+  it("sends null for system and maps the legacy zh-CN code", async () => {
+    transport.put.mockResolvedValue({
+      status: 200,
+      data: languageState("zh-Hans", { rebuilt: false }),
+    });
+    await capturedRun(["settings", "language", "zh-CN"]);
+    expect(transport.put).toHaveBeenLastCalledWith(
+      "/api/v1/settings/ui-language",
+      { ui_language: "zh-Hans" },
+      undefined,
+    );
+    transport.get.mockResolvedValue({
+      status: 200,
+      data: languageState("en"),
+    });
+    transport.put.mockResolvedValue({
+      status: 200,
+      data: languageState(null, { rebuilt: true }),
+    });
+    await capturedRun(["settings", "language", "system"]);
+    expect(transport.put).toHaveBeenLastCalledWith(
+      "/api/v1/settings/ui-language",
+      { ui_language: null },
+      undefined,
+    );
+  });
+
+  it("does not write a language Core already has", async () => {
+    const result = await capturedRun(["settings", "language", "system"]);
+    expect(result.code).toBe(0);
+    expect(
+      JSON.parse(
+        (await capturedRun(["settings", "language", "system", "--json"]))
+          .stdout,
+      ).state,
+    ).toBe("unchanged");
+    expect(transport.put).not.toHaveBeenCalled();
+  });
+
+  it("refuses unknown codes before the Runtime", async () => {
+    for (const bad of [
+      ["settings", "language", "it"],
+      ["settings", "language", "EN"],
+      ["settings", "language", "ja", "ko"],
+    ]) {
+      expect((await capturedRun(bad)).code, bad.join(" ")).toBe(2);
+    }
+    expect(transport.put).not.toHaveBeenCalled();
+  });
+
+  it("parses the forms the help shows", () => {
+    expect(parseLanguageCommand([])).toEqual({ kind: "show" });
+    expect(parseLanguageCommand(["system"])).toEqual({
+      kind: "set",
+      language: null,
+    });
+    expect(parseLanguageCommand(["zh-Hant", "--json"])).toEqual({
+      kind: "set",
+      language: "zh-Hant",
+    });
+  });
+});
+
+describe("status language", () => {
+  it.each([
+    [null, "auto", "跟随系统", "auto（自动识别中/英）"],
+    ["ja", "ja", "ja", "SDK 提示语言 ja"],
+  ])(
+    "shows the UI language %s and the SDK language %s",
+    async (uiLanguage, sdkLanguage, uiText, sdkText) => {
+      const processing = {
+        pending: 0,
+        completed: 0,
+        failed: 0,
+        blocked_stages: [],
+        pipeline: {
+          mode: "pro",
+          configured_mode: "pro",
+          forced_by_env: false,
+          last_evolve_at: null,
+          graph_build: { state: "idle", users: {} },
+          evolve: { mode: "pro", schedule: null, running: [], users: {} },
+          features: {},
+          ui_language: uiLanguage,
+          sdk_language: sdkLanguage,
+        },
+      };
+      const report = await composeStatusReport({
+        dataDir: "/tmp/isolated",
+        runtime: { state: "running", code: "ok", host: "127.0.0.1", port: 1 },
+        background: null,
+        reader: (async (path: string) =>
+          path === "/api/v1/memory-processing"
+            ? { state: "ok", data: processing }
+            : { state: "unavailable", code: "x" }) as never,
+      });
+      expect(report.pipeline?.ui_language).toBe(uiLanguage);
+      expect(report.pipeline?.sdk_language).toBe(sdkLanguage);
+      const text = renderStatusText(report, "MemHub");
+      expect(text).toContain(uiText);
+      expect(text).toContain(sdkText);
+    },
+  );
+
+  it("reads an older Runtime without the setting as auto", async () => {
+    const report = await composeStatusReport({
+      dataDir: "/tmp/isolated",
+      runtime: { state: "running", code: "ok", host: "127.0.0.1", port: 1 },
+      background: null,
+      reader: (async () => ({
+        state: "ok",
+        data: {
+          pipeline: {
+            mode: "pro",
+            configured_mode: "pro",
+            evolve: {},
+            graph_build: {},
+          },
+        },
+      })) as never,
+    });
+    expect(report.pipeline?.sdk_language).toBe("auto");
+    expect(report.pipeline?.ui_language).toBeNull();
+  });
+});
+
+async function capturedRun(arguments_: string[]) {
+  let stdout = "";
+  let stderr = "";
+  const stdoutSpy = vi
+    .spyOn(process.stdout, "write")
+    .mockImplementation((chunk) => {
+      stdout += String(chunk);
+      return true;
+    });
+  const stderrSpy = vi
+    .spyOn(process.stderr, "write")
+    .mockImplementation((chunk) => {
+      stderr += String(chunk);
+      return true;
+    });
+  try {
+    return {
+      code: await run(arguments_, { ONE_MEMORY_DATA_DIR: "/synthetic/data" }),
+      stdout,
+      stderr,
+    };
+  } finally {
+    stdoutSpy.mockRestore();
+    stderrSpy.mockRestore();
+  }
+}

memhub/apps/cli/src/memory-language-flow.ts

@@ -0,0 +1,185 @@
+/**
+ * `memhub settings language [<code>|system]`.
+ *
+ * The display language the App reports to the Runtime (`ui_language`), and
+ * the SDK prompt language it implies. Every code, zh-Hans and en included,
+ * makes extraction and the other SDK prompts use that language; "system"
+ * (no language set) passes none, so the SDK keeps detecting Chinese or
+ * English as before. The App sends the language it shows, so it is only
+ * unset on an install without the App. A change applies at once: a write in flight
+ * finishes in the old language, the next ones use the new one. The App sends
+ * its own choice again whenever it changes there.
+ */
+
+import type { CoreReader } from "./core-client.js";
+import type { CorePutOperations } from "./core-operations.js";
+import { PRODUCT } from "./version.js";
+
+export const UI_LANGUAGES = [
+  "en",
+  "zh-Hans",
+  "zh-Hant",
+  "ja",
+  "es",
+  "de",
+  "pt",
+  "fr",
+  "ko",
+  "ru",
+  "id",
+] as const;
+export type UiLanguage = (typeof UI_LANGUAGES)[number];
+
+/** Codes earlier builds used, and the code each one is now. */
+const LEGACY: Record<string, UiLanguage> = { "zh-CN": "zh-Hans" };
+
+const NAMES: Record<UiLanguage, string> = {
+  en: "English",
+  "zh-Hans": "简体中文",
+  "zh-Hant": "繁體中文",
+  ja: "日本語",
+  es: "Español",
+  de: "Deutsch",
+  pt: "Português",
+  fr: "Français",
+  ko: "한국어",
+  ru: "Русский",
+  id: "Bahasa Indonesia",
+};
+
+export type LanguageCommand =
+  | { kind: "show" }
+  | { kind: "set"; language: UiLanguage | null };
+
+function isUiLanguage(value: string): value is UiLanguage {
+  return (UI_LANGUAGES as readonly string[]).includes(value);
+}
+
+/** Arguments after `settings language`; null = usage. */
+export function parseLanguageCommand(
+  values: readonly string[],
+): LanguageCommand | null {
+  const rest = values.filter((value) => value !== "--json");
+  if (rest.length === 0) return { kind: "show" };
+  if (rest.length !== 1) return null;
+  const raw = rest[0] ?? "";
+  const value: string = Object.hasOwn(LEGACY, raw) ? LEGACY[raw] : raw;
+  if (value === "system") return { kind: "set", language: null };
+  return isUiLanguage(value) ? { kind: "set", language: value } : null;
+}
+
+export interface LanguageState {
+  ui_language: UiLanguage | null;
+  sdk_language: string;
+  rebuilt?: boolean;
+}
+
+function languageState(value: unknown): LanguageState | null {
+  if (!value || typeof value !== "object") return null;
+  const item = value as Record<string, unknown>;
+  if (
+    !(item.ui_language === null || isUiLanguage(String(item.ui_language))) ||
+    typeof item.sdk_language !== "string"
+  ) {
+    return null;
+  }
+  return {
+    ui_language: item.ui_language as UiLanguage | null,
+    sdk_language: item.sdk_language,
+    ...(typeof item.rebuilt === "boolean" ? { rebuilt: item.rebuilt } : {}),
+  };
+}
+
+export type LanguageDocument = {
+  schema_version: 1;
+  product: string;
+  command: "settings language";
+} & (
+  | { state: "ok" | "unchanged"; language: LanguageState }
+  | { state: "committed"; language: LanguageState; rebuilt: boolean }
+  | { state: "rejected" | "unknown" | "unavailable"; code: string }
+);
+
+const BASE = {
+  schema_version: 1 as const,
+  product: PRODUCT,
+  command: "settings language" as const,
+};
+
+const PATH = "/api/v1/settings/ui-language";
+
+export async function runLanguageCommand(
+  command: LanguageCommand,
+  reader: CoreReader,
+  operations: CorePutOperations,
+): Promise<LanguageDocument> {
+  const read = await reader<unknown>(PATH);
+  if (read.state !== "ok") {
+    return { ...BASE, state: "unavailable", code: read.code };
+  }
+  const current = languageState(read.data);
+  if (current === null) {
+    return { ...BASE, state: "unavailable", code: "response_invalid" };
+  }
+  if (command.kind === "show") {
+    return { ...BASE, state: "ok", language: current };
+  }
+  if (current.ui_language === command.language) {
+    return { ...BASE, state: "unchanged", language: current };
+  }
+  const result = await operations.put<unknown>(PATH, {
+    ui_language: command.language,
+  });
+  if (result.state !== "committed") {
+    return { ...BASE, state: result.state, code: result.code };
+  }
+  const changed = languageState(result.data);
+  if (changed === null) {
+    return { ...BASE, state: "unknown", code: "response_invalid" };
+  }
+  return {
+    ...BASE,
+    state: "committed",
+    language: changed,
+    rebuilt: changed.rebuilt === true,
+  };
+}
+
+export function languageExitCode(document: LanguageDocument): number {
+  return ["ok", "unchanged", "committed"].includes(document.state) ? 0 : 1;
+}
+
+function sdkText(sdkLanguage: string): string {
+  return sdkLanguage === "auto"
+    ? "auto（SDK 自动识别中文或英文）"
+    : `${sdkLanguage}（提取等 SDK 提示使用该语言）`;
+}
+
+export function renderLanguageText(document: LanguageDocument): string {
+  if ("code" in document) {
+    return `界面语言未能${document.state === "unavailable" ? "读取" : "修改"}：${document.code}\n`;
+  }
+  const state = document.language;
+  const lines = [
+    `界面语言：${
+      state.ui_language === null
+        ? "未设置（SDK 自动识别）"
+        : `${state.ui_language}（${NAMES[state.ui_language]}）`
+    }`,
+    `SDK 提示语言：${sdkText(state.sdk_language)}`,
+  ];
+  if (document.state === "ok") {
+    lines.push(
+      `可选：${UI_LANGUAGES.join("、")}、system。任一语言（包括 zh-Hans、en）都会让 SDK 使用该语言；system 不指定语言，SDK 自动识别中文或英文。`,
+    );
+  }
+  if (document.state === "unchanged") lines.push("没有需要改动的设置。");
+  if (document.state === "committed") {
+    lines.push(
+      document.rebuilt
+        ? "已更新。正在进行的写入按原语言完成，之后的写入和检索使用新语言。"
+        : "已保存，SDK 提示语言没有变化。",
+    );
+  }
+  return `${lines.join("\n")}\n`;
+}

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

@@ -142,7 +142,7 @@ describe("memhub settings mode", () => {
       ["settings", "mode", "max"],
       ["settings", "mode", "--yes"],
       ["settings", "mode", "lite", "pro"],
-      ["settings", "language", "en"],
+      ["settings", "theme", "dark"],
     ]) {
       expect((await capturedRun(bad)).code, bad.join(" ")).toBe(2);
     }

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

@@ -248,6 +248,10 @@ function addReceipt(receipt: MemoryAddReceipt): Record<string, unknown> {
     task_id: receipt.task_id,
     memory_ids: receipt.memory_ids,
     error: receipt.error,
+    error_code:
+      typeof receipt.error_code === "string" ? receipt.error_code : null,
+    next_retry_at:
+      typeof receipt.next_retry_at === "string" ? receipt.next_retry_at : null,
   };
 }
 
@@ -347,6 +351,12 @@ export function renderMemoryAddText(document: MemoryAddDocument): string {
       ...((document.receipt.memory_ids as string[]).length > 0
         ? [`memory_ids: ${(document.receipt.memory_ids as string[]).join(",")}`]
         : []),
+      ...(document.receipt.error_code
+        ? [`error_code: ${document.receipt.error_code}`]
+        : []),
+      ...(document.receipt.next_retry_at
+        ? [`next_retry_at: ${document.receipt.next_retry_at}`]
+        : []),
       document.command === "memories add"
         ? `查询进度：memhub memories add-status ${document.request_id}；重试请带上同一个 --request-id，不会重复添加。`
         : "",
@@ -372,6 +382,9 @@ export function renderMemoryAddText(document: MemoryAddDocument): string {
 export function renderMemoryPageText(document: MemoryPageDocument): string {
   const page = document.page;
   if (page.state !== "ok") {
+    if (page.state === "unavailable" && page.code === "embedding_unavailable") {
+      return "向量服务不可用，无法检索；请检查向量模型配置。\n";
+    }
     if (page.state === "unavailable") {
       return "后台正忙，记忆列表这次没查完，不代表没有记忆，请稍后再试\n";
     }

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

@@ -22,6 +22,10 @@ const RESULT_KEYS = new Set([
   "stages",
   "capabilities",
 ]);
+const OPTIONAL_RESULT_KEYS = [
+  "embedding_width",
+  "embedding_switch_required",
+] as const;
 const STAGE_KEYS = new Set([
   "stage",
   "ok",
@@ -272,9 +276,34 @@ function validateResult(
   inputRevision: number,
 ): Record<string, unknown> | null {
   const result = record(value);
+  // A Core with the embedding registry adds what the embedding stage measured
+  // and whether using it needs an embedding switch; older Cores send neither.
+  const optional = Object.fromEntries(
+    OPTIONAL_RESULT_KEYS.filter((key) => key in (result ?? {})).map((key) => [
+      key,
+      result?.[key],
+    ]),
+  );
+  const required = result
+    ? Object.fromEntries(
+        Object.entries(result).filter(
+          ([key]) => !(OPTIONAL_RESULT_KEYS as readonly string[]).includes(key),
+        ),
+      )
+    : null;
   if (
     !result ||
-    !exactKeys(result, RESULT_KEYS) ||
+    !required ||
+    !exactKeys(required, RESULT_KEYS) ||
+    !(
+      optional.embedding_width === undefined ||
+      optional.embedding_width === null ||
+      positiveInteger(optional.embedding_width)
+    ) ||
+    !(
+      optional.embedding_switch_required === undefined ||
+      typeof optional.embedding_switch_required === "boolean"
+    ) ||
     result.profile_id !== profileId ||
     result.input_profile_revision !== inputRevision ||
     !positiveInteger(result.profile_revision) ||

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

@@ -117,7 +117,7 @@ export async function editModelProfile(
   return modelProfileResult(profileId, result);
 }
 
-function modelProfileResult(
+export function modelProfileResult(
   operationId: string,
   result:
     | Awaited<ReturnType<CoreOperations["post"]>>

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

@@ -161,6 +161,7 @@ const CORE = new Map<string, { status: number; data: unknown }>([
         blocked_stages: [
           { kind: "extract", reason: "model_missing", count: 2 },
         ],
+        pipeline: { mode: "pro", configured_mode: "pro" },
       },
     },
   ],
@@ -202,7 +203,9 @@ const READ_ONLY_PATHS = [
   "/api/v1/live-sync",
   "/api/v1/memory-processing",
   "/api/v1/model-profiles",
+  "/api/v2/home-projection",
   "/api/v2/home-summary",
+  "/api/v2/raw",
   "/api/v2/memory-library",
   "/api/v2/memories/",
   "/api/v2/user-profile",
@@ -257,6 +260,9 @@ describe("CLI-20 status summary", () => {
     expect(report.sections.model).toMatchObject({ state: "ok", profiles: 1 });
     expect(report.sections.memories).toMatchObject({
       state: "ok",
+      content_plane: "memory",
+      visible_count: 42,
+      effective_mode: "pro",
       memory_count: 42,
     });
     expect(report.summary.state).toBe("ok");
@@ -903,7 +909,10 @@ describe("CLI-21 memory reads", () => {
     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-projection")).toBe(true);
     expect(isReadOnlyPath("/api/v2/home-summary")).toBe(true);
+    expect(isReadOnlyPath("/api/v2/raw")).toBe(true);
+    expect(isReadOnlyPath("/api/v1/settings/memory-mode/plan")).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);
@@ -1085,7 +1094,8 @@ describe("malformed success responses", () => {
 
   it("refuses a model profile whose string fields are not strings", async () => {
     transport.get.mockImplementation(async (url: string) => {
-      if (url !== "/api/v1/model-profiles") return CORE.get(url);
+      if (url !== "/api/v1/model-profiles")
+        return CORE.get(url) ?? { status: 404, data: { detail: "not_found" } };
       return {
         status: 200,
         data: [

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

@@ -1,5 +1,6 @@
 import { describe, expect, it } from "vitest";
 
+import type { CoreReader, ReadOutcome } from "./core-client.js";
 import { composeDoctorReport, renderDoctorText } from "./doctor-report.js";
 import {
   composeStatusReport,
@@ -41,6 +42,108 @@ describe("status default output", () => {
   });
 });
 
+describe("status on a paused model", () => {
+  const processing = (backoff: {
+    llm_backoff_until: string | null;
+    llm_backoff_error: string | null;
+  }) => ({
+    pending: 4,
+    fresh_pending: 4,
+    backlog_pending: 0,
+    outside_window_pending: 0,
+    running: 0,
+    waiting_for_model: 0,
+    completed: 1,
+    failed: 0,
+    blocked_stages: [],
+    suspended: 2,
+    ...backoff,
+  });
+  const reader =
+    (summary: unknown): CoreReader =>
+    async <T>(path: string) =>
+      (path === "/api/v1/memory-processing"
+        ? { state: "ok", data: summary }
+        : { state: "unavailable", code: "x" }) as ReadOutcome<T>;
+  const compose = (summary: unknown) =>
+    composeStatusReport({
+      dataDir: "/tmp/isolated/.one-memory",
+      runtime: {
+        state: "running",
+        code: "runtime_verified",
+        host: "127.0.0.1",
+        port: 30001,
+      },
+      background: null,
+      reader: reader(summary),
+    });
+
+  it("names the code and the retry time while the breaker pauses", async () => {
+    const report = await compose(
+      processing({
+        llm_backoff_until: "2026-11-02T10:00:00+00:00",
+        llm_backoff_error: "model_auth_failed",
+      }),
+    );
+    expect(report.sections.processing).toMatchObject({
+      state: "ok",
+      pending: 4,
+      suspended: 2,
+      llm_backoff_until: "2026-11-02T10:00:00+00:00",
+      llm_backoff_error: "model_auth_failed",
+    });
+    const text = renderStatusText(report, "MemHub");
+    expect(text).toContain(
+      "模型暂停：model_auth_failed，将于 2026-11-02T10:00:00+00:00 自动重试",
+    );
+    expect(text).not.toContain("llm_backoff");
+  });
+
+  it("prints no pause line and null fields when nothing is paused", async () => {
+    const report = await compose(
+      processing({ llm_backoff_until: null, llm_backoff_error: null }),
+    );
+    expect(report.sections.processing).toMatchObject({
+      llm_backoff_until: null,
+      llm_backoff_error: null,
+    });
+    expect(renderStatusText(report, "MemHub")).not.toContain("模型暂停");
+  });
+
+  it("reports a restarting write drain and its exit code", async () => {
+    const report = await compose({
+      ...processing({ llm_backoff_until: null, llm_backoff_error: null }),
+      write_drain: "restarting",
+      write_drain_error: "operational_error",
+    });
+    expect(report.sections.processing).toMatchObject({
+      write_drain: "restarting",
+      write_drain_error: "operational_error",
+    });
+    const text = renderStatusText(report, "MemHub");
+    expect(text).toContain(
+      "写入队列：异常退出（operational_error），正在自动重启",
+    );
+    expect(text).not.toContain("write_drain");
+  });
+
+  it("says nothing about a running drain and nulls what an older Core omits", async () => {
+    const running = await compose({
+      ...processing({ llm_backoff_until: null, llm_backoff_error: null }),
+      write_drain: "running",
+      write_drain_error: null,
+    });
+    expect(renderStatusText(running, "MemHub")).not.toContain("写入队列");
+    const older = await compose(
+      processing({ llm_backoff_until: null, llm_backoff_error: null }),
+    );
+    expect(older.sections.processing).toMatchObject({
+      write_drain: null,
+      write_drain_error: null,
+    });
+  });
+});
+
 describe("status and doctor on an unfinished upgrade migration", () => {
   it("names the migration log and the issues page", async () => {
     const report = await composeStatusReport({
@@ -77,3 +180,140 @@ describe("status and doctor on an unfinished upgrade migration", () => {
     expect(report.runtime.log_file).toBeUndefined();
   });
 });
+
+describe("mode-aware status content projection", () => {
+  const runtime = {
+    state: "running" as const,
+    code: "runtime_verified",
+    host: "127.0.0.1",
+    port: 30001,
+  };
+  const processing = (mode: "lite" | "pro" | "ultra") => ({
+    pending: 0,
+    fresh_pending: 0,
+    backlog_pending: 0,
+    outside_window_pending: 0,
+    running: 0,
+    waiting_for_model: 0,
+    completed: 0,
+    failed: 0,
+    pipeline: { mode, configured_mode: mode },
+  });
+  const projection = {
+    projection_version: 1,
+    user_id: "local",
+    effective_mode: "lite",
+    capabilities: {
+      content_plane: "raw",
+      generation_required: false,
+      graph_enabled: false,
+      evolve_available: false,
+    },
+    visible_count: 7,
+    display_state: "excerpt",
+    latest: {
+      type: "raw",
+      raw_id: "raw-1",
+      session_id: "session-1",
+      display_state: "excerpt",
+      time: null,
+      time_basis: null,
+      excerpt: "hello",
+      truncated: false,
+      source_id: "cursor",
+    },
+    observed_at: "2026-11-04T00:00:00Z",
+  };
+
+  it("uses the projection without reading either legacy count endpoint", async () => {
+    const calls: string[] = [];
+    const reader: CoreReader = async <T>(path: string) => {
+      calls.push(path);
+      const data =
+        path === "/api/v2/home-projection"
+          ? projection
+          : path === "/api/v1/memory-processing"
+            ? processing("lite")
+            : null;
+      return { state: "ok", data } as ReadOutcome<T>;
+    };
+    const report = await composeStatusReport({
+      dataDir: "/tmp/isolated",
+      runtime,
+      background: null,
+      reader,
+    });
+    expect(report.sections.memories).toEqual({
+      state: "ok",
+      content_plane: "raw",
+      visible_count: 7,
+      effective_mode: "lite",
+      raw_count: 7,
+    });
+    expect(calls).not.toContain("/api/v2/raw");
+    expect(calls).not.toContain("/api/v2/home-summary");
+    expect(renderStatusText(report, "MemHub")).toContain(
+      "原始对话：原始对话 7",
+    );
+  });
+
+  it("falls back to the real raw total only for an old Lite Core", async () => {
+    const reader: CoreReader = async <T>(path: string) => {
+      if (path === "/api/v2/home-projection")
+        return { state: "not_found", code: "http_404" } as ReadOutcome<T>;
+      if (path === "/api/v1/memory-processing")
+        return {
+          state: "ok",
+          data: processing("lite"),
+        } as ReadOutcome<T>;
+      if (path === "/api/v2/raw")
+        return {
+          state: "ok",
+          data: {
+            user_id: "local",
+            items: [],
+            total: 9,
+            offset: 0,
+            limit: 1,
+            time_filtered: false,
+          },
+        } as ReadOutcome<T>;
+      return { state: "unavailable", code: "x" } as ReadOutcome<T>;
+    };
+    const report = await composeStatusReport({
+      dataDir: "/tmp/isolated",
+      runtime,
+      background: null,
+      reader,
+    });
+    expect(report.sections.memories).toMatchObject({
+      state: "ok",
+      content_plane: "raw",
+      visible_count: 9,
+      raw_count: 9,
+    });
+    expect(report.sections.memories).not.toHaveProperty("memory_count");
+  });
+
+  it("rejects extra projection fields instead of falling back or leaking them", async () => {
+    const reader: CoreReader = async <T>(path: string) =>
+      ({
+        state: "ok",
+        data:
+          path === "/api/v2/home-projection"
+            ? { ...projection, secret: "must-not-leak" }
+            : processing("lite"),
+      }) as ReadOutcome<T>;
+    const report = await composeStatusReport({
+      dataDir: "/tmp/isolated",
+      runtime,
+      background: null,
+      reader,
+    });
+    expect(report.sections.memories).toEqual({
+      state: "invalid",
+      code: "response_invalid",
+    });
+    expect(JSON.stringify(report)).not.toContain("must-not-leak");
+  });
+});

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

@@ -1,4 +1,5 @@
 import type {
+  HomeProjectionV1,
   LiveSyncHealth,
   MemoryProcessingSummary,
   ModelProfile,
@@ -12,12 +13,15 @@ import { sdkMigrationLogPath } from "@one-memory/runtime-control";
 import type { CoreReader, ReadOutcome } from "./core-client.js";
 import {
   type SdkHomeSummary,
+  validateHomeProjection,
   validateHomeSummary,
   validateLiveSync,
   validateModelProfiles,
   validateProcessing,
+  validateRawTotal,
   validateSources,
 } from "./core-responses.js";
+import { describeEmbeddingSwitchSummary } from "./embedding-switch-flow.js";
 import { PRODUCT } from "./version.js";
 
 const MIGRATION_ISSUES_URL =
@@ -84,7 +88,11 @@ export interface PipelineSummary {
   >;
   graph_build: string | null;
   /** SDK features (`memory_features`) whose value differs from the default. */
-  features: Record<string, boolean>;
+  features: Record<string, boolean | number>;
+  /** The App's display language; null = never chosen or "follow the system". */
+  ui_language: string | null;
+  /** The SDK prompt language: `auto` (zh/en detection) or the code passed. */
+  sdk_language: string;
 }
 
 const MODES = new Set(["lite", "pro", "ultra"]);
@@ -129,12 +137,13 @@ export function describePipeline(value: unknown): PipelineSummary | null {
       };
     }
   }
-  const features: Record<string, boolean> = {};
+  const features: Record<string, boolean | number> = {};
   if (item.features && typeof item.features === "object") {
     for (const [name, value] of Object.entries(
       item.features as Record<string, unknown>,
     )) {
-      if (typeof value === "boolean") features[name] = value;
+      if (typeof value === "boolean" || typeof value === "number")
+        features[name] = value;
     }
   }
   const graph =
@@ -157,6 +166,10 @@ export function describePipeline(value: unknown): PipelineSummary | null {
     evolve_users: users,
     graph_build: typeof graph.state === "string" ? graph.state : null,
     features,
+    ui_language: typeof item.ui_language === "string" ? item.ui_language : null,
+    // An older Runtime has no setting: it always left the SDK on auto.
+    sdk_language:
+      typeof item.sdk_language === "string" ? item.sdk_language : "auto",
   };
 }
 
@@ -201,12 +214,12 @@ export async function composeStatusReport(options: {
     for (const name of SECTION_NAMES) sections[name] = { state, code };
   } else {
     const reader = options.reader;
-    const [sources, sync, processing, model, memories] = await Promise.all([
+    const [sources, sync, processing, model, projection] = await Promise.all([
       reader<unknown>("/api/v1/sources"),
       reader<unknown>("/api/v1/live-sync"),
       reader<unknown>("/api/v1/memory-processing"),
       reader<unknown>("/api/v1/model-profiles"),
-      reader<unknown>("/api/v2/home-summary"),
+      reader<unknown>("/api/v2/home-projection"),
     ]);
     sections.sources = section(sources, validateSources, describeSources);
     sections.sync = section(sync, validateLiveSync, describeSync);
@@ -218,11 +231,7 @@ export async function composeStatusReport(options: {
     pipeline =
       processing.state === "ok" ? describePipeline(processing.data) : null;
     sections.model = section(model, validateModelProfiles, describeModel);
-    sections.memories = section(
-      memories,
-      validateHomeSummary,
-      describeMemories,
-    );
+    sections.memories = await memorySection(reader, projection, pipeline);
   }
   // A bridge we could not inspect is unknown, not broken and not fine.
   const bridge: StatusDocument["bridge"] =
@@ -302,10 +311,20 @@ export function renderStatusText(
   ];
   for (const name of SECTION_NAMES) {
     lines.push(
-      `${SECTION_LABELS[name]}：${sectionLine(report.sections[name])}`,
+      `${sectionLabel(name, report.sections[name])}：${sectionLine(
+        report.sections[name],
+      )}`,
     );
   }
   if (report.pipeline) lines.push(`记忆模式：${pipelineLine(report.pipeline)}`);
+  const embeddingSwitch = describeEmbeddingSwitchSummary(
+    report.sections.processing?.embedding_switch,
+  );
+  if (embeddingSwitch !== null) lines.push(`向量模型：${embeddingSwitch}`);
+  const backoff = modelBackoffLine(report.sections.processing);
+  if (backoff !== null) lines.push(backoff);
+  const drain = writeDrainLine(report.sections.processing);
+  if (drain !== null) lines.push(drain);
   if (report.summary.state === "partial") {
     const notes = [
       report.summary.degraded.length > 0
@@ -321,6 +340,35 @@ export function renderStatusText(
   return lines.join("\n");
 }
 
+/** "Model paused" while Core's circuit breaker holds model work back; null
+ * otherwise. Nothing to do here: the queue resumes by itself once the model
+ * answers again (or after the model is fixed). */
+function modelBackoffLine(section: Section | undefined): string | null {
+  if (section?.state !== "ok") return null;
+  const error = section.llm_backoff_error;
+  if (typeof error !== "string" || error.length === 0) return null;
+  const until = section.llm_backoff_until;
+  return `模型暂停：${error}，${
+    typeof until === "string" && until.length > 0
+      ? `将于 ${until} 自动重试`
+      : "稍后自动重试"
+  }`;
+}
+
+/** The durable write drain, when it is not simply running: it exited on an
+ * error and is coming back (`restarting`), or it is not running at all. */
+function writeDrainLine(section: Section | undefined): string | null {
+  if (section?.state !== "ok") return null;
+  const state = section.write_drain;
+  if (state !== "restarting" && state !== "stopped") return null;
+  const error = section.write_drain_error;
+  const reason =
+    typeof error === "string" && error.length > 0 ? `（${error}）` : "";
+  return state === "restarting"
+    ? `写入队列：异常退出${reason}，正在自动重启`
+    : `写入队列：已停止${reason}`;
+}
+
 export function pipelineLine(pipeline: PipelineSummary): string {
   const parts: string[] = [pipeline.mode];
   if (pipeline.forced_by_env)
@@ -344,10 +392,20 @@ export function pipelineLine(pipeline: PipelineSummary): string {
   if (changed.length > 0) {
     parts.push(
       `；SDK 功能：${changed
-        .map(([name, value]) => `${name}=${value ? "开" : "关"}`)
+        .map(
+          ([name, value]) =>
+            `${name}=${typeof value === "number" ? value : value ? "开" : "关"}`,
+        )
         .join("、")}`,
     );
   }
+  parts.push(
+    `；界面语言 ${pipeline.ui_language ?? "跟随系统"}，SDK 提示语言 ${
+      pipeline.sdk_language === "auto"
+        ? "auto（自动识别中/英）"
+        : pipeline.sdk_language
+    }`,
+  );
   return parts.join("");
 }
 
@@ -360,12 +418,33 @@ function runtimeLine(report: StatusDocument): string {
   }）`;
 }
 
+/** Fields that have their own line (or none) instead of a place in the
+ * section's one-line summary. */
+const SECTION_LINE_OMITTED = new Set([
+  "state",
+  "code",
+  "embedding_switch",
+  "llm_backoff_until",
+  "llm_backoff_error",
+  "write_drain",
+  "write_drain_error",
+  "content_plane",
+  "visible_count",
+  "effective_mode",
+]);
+
+function sectionLabel(name: string, section: Section | undefined): string {
+  return name === "memories" && section?.content_plane === "raw"
+    ? "原始对话"
+    : SECTION_LABELS[name];
+}
+
 function sectionLine(section: Section | undefined): string {
   if (!section) return "未检查";
   if (section.state === "not_checked") return "未检查";
   if (section.state !== "ok") return "暂时不可用，请稍后重试";
   return Object.entries(section)
-    .filter(([key]) => key !== "state" && key !== "code")
+    .filter(([key]) => !SECTION_LINE_OMITTED.has(key))
     .map(([key, value]) => `${fieldLabel(key)} ${formatValue(value)}`)
     .join(" ");
 }
@@ -401,6 +480,7 @@ function fieldLabel(key: string): string {
     backlog_pending: "历史待处理",
     outside_window_pending: "稍后处理",
     waiting_for_model: "等待模型",
+    suspended: "来源已暂停",
     completed: "已完成",
     failed: "失败",
     blocked: "卡住",
@@ -410,6 +490,10 @@ function fieldLabel(key: string): string {
     profiles: "配置",
     active: "当前",
     memory_count: "记忆",
+    raw_count: "原始对话",
+    visible_count: "可见",
+    content_plane: "内容层",
+    effective_mode: "模式",
   };
   return labels[key] ?? key;
 }
@@ -481,9 +565,67 @@ function describeProcessing(
       reason: block.reason,
       count: block.count,
     })),
+    suspended: typeof summary.suspended === "number" ? summary.suspended : 0,
+    ...llmBackoffFields(summary),
+    ...writeDrainFields(summary),
+    ...embeddingSwitchField(summary),
   };
 }
 
+/** The model circuit breaker: set only while Core pauses model work because
+ * the provider keeps failing. Both null when nothing is paused. */
+function llmBackoffFields(summary: MemoryProcessingSummary): {
+  llm_backoff_until: string | null;
+  llm_backoff_error: string | null;
+} {
+  const until = summary.llm_backoff_until;
+  const error = summary.llm_backoff_error;
+  return {
+    llm_backoff_until:
+      typeof until === "string" && until.length <= 64 ? until : null,
+    llm_backoff_error:
+      typeof error === "string" && /^[a-z_]{1,64}$/.test(error) ? error : null,
+  };
+}
+
+/** Durable write drain liveness. Null when Core does not report it (older
+ * Core, or recovery has not started the drain yet). */
+function writeDrainFields(summary: MemoryProcessingSummary): {
+  write_drain: "running" | "restarting" | "stopped" | null;
+  write_drain_error: string | null;
+} {
+  const state = summary.write_drain;
+  const error = summary.write_drain_error;
+  return {
+    write_drain:
+      state === "running" || state === "restarting" || state === "stopped"
+        ? state
+        : null,
+    write_drain_error:
+      typeof error === "string" && /^[a-z_]{1,64}$/.test(error) ? error : null,
+  };
+}
+
+/** The running switch or merge, projected; absent when none runs. */
+function embeddingSwitchField(
+  summary: MemoryProcessingSummary,
+): Record<string, unknown> {
+  const value = (summary as unknown as Record<string, unknown>)
+    .embedding_switch;
+  if (!value || typeof value !== "object" || Array.isArray(value)) return {};
+  const item = value as Record<string, unknown>;
+  const kind = item.kind === "merge" ? "merge" : "switch";
+  const state =
+    typeof item.state === "string" && /^[a-z_]{1,32}$/.test(item.state)
+      ? item.state
+      : "unknown";
+  const percent =
+    typeof item.percent === "number" && Number.isFinite(item.percent)
+      ? Math.min(100, Math.max(0, item.percent))
+      : 0;
+  return { embedding_switch: { kind, state, percent } };
+}
+
 /** Projection, not passthrough: a Core that leaks a key must not make us leak. */
 function describeModel(profiles: ModelProfile[]): Record<string, unknown> {
   const active = profiles.find((profile) => profile.is_active);
@@ -504,6 +646,70 @@ function describeMemories(summary: SdkHomeSummary): Record<string, unknown> {
   };
 }
 
+async function memorySection(
+  reader: CoreReader,
+  projection: ReadOutcome<unknown>,
+  pipeline: PipelineSummary | null,
+): Promise<Section> {
+  if (projection.state === "ok") {
+    const parsed = validateHomeProjection(projection.data);
+    return parsed === null
+      ? { state: "invalid", code: "response_invalid" }
+      : { state: "ok", ...describeProjection(parsed) };
+  }
+  if (projection.state !== "not_found") {
+    return {
+      state: projection.state === "denied" ? "denied" : "unavailable",
+      code: projection.code,
+    };
+  }
+  if (pipeline === null) {
+    return { state: "unavailable", code: "effective_mode_unavailable" };
+  }
+  if (pipeline.mode === "lite") {
+    const raw = await reader<unknown>("/api/v2/raw", {
+      limit: 1,
+      offset: 0,
+    });
+    if (raw.state !== "ok") {
+      return {
+        state: raw.state === "denied" ? "denied" : "unavailable",
+        code: raw.code,
+      };
+    }
+    const total = validateRawTotal(raw.data);
+    return total === null
+      ? { state: "invalid", code: "response_invalid" }
+      : {
+          state: "ok",
+          content_plane: "raw",
+          visible_count: total,
+          effective_mode: "lite",
+          raw_count: total,
+        };
+  }
+  const legacy = await reader<unknown>("/api/v2/home-summary");
+  return section(legacy, validateHomeSummary, (summary) => ({
+    content_plane: "memory",
+    visible_count: summary.memory_count,
+    effective_mode: pipeline.mode,
+    ...describeMemories(summary),
+  }));
+}
+
+function describeProjection(
+  projection: HomeProjectionV1,
+): Record<string, unknown> {
+  return {
+    content_plane: projection.capabilities.content_plane,
+    visible_count: projection.visible_count,
+    effective_mode: projection.effective_mode,
+    ...(projection.capabilities.content_plane === "raw"
+      ? { raw_count: projection.visible_count }
+      : { memory_count: projection.visible_count }),
+  };
+}
+
 function sum(
   sources: SourceResponse[],
   key: "imported_conversations" | "imported_messages",

memhub/apps/cli/src/user-id-cli.test.ts

@@ -208,6 +208,27 @@ describe("--user-id on the memory commands", () => {
     expect(direct.get.mock.calls[0][1].params).toEqual({ user_id: "wife" });
   });
 
+  it("prints the retry code and time of a write still waiting", async () => {
+    direct.get.mockResolvedValue({
+      data: {
+        request_id: REQUEST,
+        state: "accepted",
+        created_at: "T1",
+        updated_at: "T2",
+        error_code: "model_timeout",
+        next_retry_at: "2026-11-02T10:00:00+00:00",
+      },
+    });
+    const text = await capturedRun(["write", "status", REQUEST]);
+    expect(text.stdout).toContain("error_code: model_timeout");
+    expect(text.stdout).toContain("next_retry_at: 2026-11-02T10:00:00+00:00");
+    const json = await capturedRun(["write", "status", REQUEST, "--json"]);
+    expect(JSON.parse(json.stdout).write).toMatchObject({
+      error_code: "model_timeout",
+      next_retry_at: "2026-11-02T10:00:00+00:00",
+    });
+  });
+
   it("passes the user in the body of memory writes and searches", async () => {
     await capturedRun(["memories", "add", "Prefers tea", "--user-id", "wife"]);
     expect(transport.post.mock.calls[0][0]).toBe("/api/v2/memories");
@@ -373,6 +394,48 @@ describe("sources connect for a Hermes profile", () => {
     }
     expect(transport.post).not.toHaveBeenCalled();
   });
+
+  it("says the user id need not equal the Hermes profile name", async () => {
+    const result = await capturedRun([
+      "sources",
+      "connect",
+      "hermes",
+      "--user-id",
+      "wife:work",
+      "--root",
+      "~/.hermes/profiles/wife:work",
+    ]);
+    expect(result.code).toBe(2);
+    expect(result.stderr).toContain("用户 ID 不必等于 Hermes profile 名");
+    expect(result.stderr).toContain(
+      "--user-id wife-work --root ~/.hermes/profiles/wife:work",
+    );
+    expect(transport.post).not.toHaveBeenCalled();
+  });
+
+  it("explains a refused overlapping or profiles-container root", async () => {
+    for (const code of [
+      "hermes_root_is_profiles_container",
+      "hermes_root_overlaps_other_user",
+    ]) {
+      transport.post.mockResolvedValueOnce({
+        status: code.endsWith("container") ? 422 : 409,
+        data: { detail: code },
+      });
+      const result = await capturedRun([
+        "sources",
+        "connect",
+        "hermes",
+        "--user-id",
+        "kid",
+        "--root",
+        "/profiles",
+      ]);
+      expect(result.code).toBe(1);
+      expect(result.stdout).toContain(code);
+      expect(result.stdout).toContain("--root");
+    }
+  });
 });
 
 async function capturedRun(arguments_: string[]) {

memhub/apps/core/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "uv_build"
 
 [project]
 name = "one-memory"
-version = "1.0.5"
+version = "1.0.6"
 description = "MemHub local-first memory core"
 readme = "README.md"
 requires-python = ">=3.12"
@@ -12,7 +12,7 @@ dependencies = [
     "fastapi>=0.141.1",
     "filelock>=3.32.4",
     # Public SDK version validated against MemHub's permission and recall contracts.
-    "hy-memory==2.0.9",
+    "hy-memory==2.0.14",
     # 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",

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

@@ -15,6 +15,20 @@ BULK_WORKERS = 3
 SNAPSHOT_WORKERS = 8
 INTERACTIVE_READ_WORKERS = 4
 SOURCE_READER_WORKERS = 4
+# One per source the drain runs side by side (`max_concurrent_sources`), and
+# two over for the outcome inquiries that follow them.
+SDK_WRITE_WORKERS = 12
+# Recall's SDK reads: one search and the `get`s behind it (`_SDK_GET_CONCURRENCY`).
+SDK_READ_WORKERS = 8
+# The durable write queue's own bookkeeping: claim, settle, the per-job reads
+# around an SDK write, and the drain's maintenance passes. Each is one short
+# statement on the single writer or a reader; the drain runs at most
+# `max_concurrent_sources` jobs, and they wait for the writer, not for CPU.
+DURABLE_QUEUE_WORKERS = 4
+# Lease renewal alone. Renewal is the drain's ownership fence: a lease that
+# lapses while its SDK write is still running hands the job to recovery, so it
+# must never wait for a thread behind any other work, its own queue's included.
+LEASE_RENEWAL_WORKERS = 2
 
 _pool: ThreadPoolExecutor | None = None
 _snapshot_pool: ThreadPoolExecutor | None = None
@@ -22,6 +36,9 @@ _interactive_pool: ThreadPoolExecutor | None = None
 _raw_read_pool: ThreadPoolExecutor | None = None
 _memory_read_pool: ThreadPoolExecutor | None = None
 _source_reader_pool: ThreadPoolExecutor | None = None
+_sdk_write_pool: ThreadPoolExecutor | None = None
+_durable_queue_pool: ThreadPoolExecutor | None = None
+_lease_renewal_pool: ThreadPoolExecutor | None = None
 _warmed_readers: weakref.WeakSet[ThreadPoolExecutor] = weakref.WeakSet()
 _reader_warm_lock = threading.Lock()
 _interactive_reads = 0
@@ -71,15 +88,67 @@ def raw_read_pool() -> ThreadPoolExecutor:
 
 
 def memory_read_pool() -> ThreadPoolExecutor:
+    """Recall's own threads: SDK searches, gets, and what decides between them.
+
+    Recall used to hand these to the default pool, which SDK writes share. A
+    write that times out keeps its thread until the SDK returns (#231), so a
+    few stuck writes left recall waiting for a thread while `/health`, which
+    needs none, still answered.
+    """
     global _memory_read_pool
     if _memory_read_pool is None:
         _memory_read_pool = ThreadPoolExecutor(
-            max_workers=INTERACTIVE_READ_WORKERS,
+            max_workers=SDK_READ_WORKERS,
             thread_name_prefix="one-memory-memory-read",
         )
     return _memory_read_pool
 
 
+def sdk_write_pool() -> ThreadPoolExecutor:
+    """SDK writes, bounded and apart from everything else.
+
+    Each thread here only waits for the SDK's own loop thread to answer
+    (`_LoopThread.run`), so any thread outside that loop may make the call; a
+    stuck write therefore costs a thread of this pool and nobody else's.
+    """
+    global _sdk_write_pool
+    if _sdk_write_pool is None:
+        _sdk_write_pool = ThreadPoolExecutor(
+            max_workers=SDK_WRITE_WORKERS,
+            thread_name_prefix="one-memory-sdk-write",
+        )
+    return _sdk_write_pool
+
+
+def durable_queue_pool() -> ThreadPoolExecutor:
+    """The durable write queue's database work, apart from bulk work.
+
+    The queue used to hand its claims, settles and maintenance to the bulk
+    pool, whose three threads also carry import heartbeats and job listings.
+    Under an import peak all three sat in those for tens of seconds, and the
+    queue's next statement waited for a thread before it could even join the
+    writer's line, and leases lapsed while their SDK writes were still running.
+    """
+    global _durable_queue_pool
+    if _durable_queue_pool is None:
+        _durable_queue_pool = ThreadPoolExecutor(
+            max_workers=DURABLE_QUEUE_WORKERS,
+            thread_name_prefix="one-memory-write-queue",
+        )
+    return _durable_queue_pool
+
+
+def lease_renewal_pool() -> ThreadPoolExecutor:
+    """Threads that only renew durable write leases (`DurableWriteDrain.renew`)."""
+    global _lease_renewal_pool
+    if _lease_renewal_pool is None:
+        _lease_renewal_pool = ThreadPoolExecutor(
+            max_workers=LEASE_RENEWAL_WORKERS,
+            thread_name_prefix="one-memory-lease-renewal",
+        )
+    return _lease_renewal_pool
+
+
 def source_reader_pool() -> ThreadPoolExecutor:
     """Bounded process-wide pool for source iteration and parsing."""
     global _source_reader_pool
@@ -99,9 +168,21 @@ def warm_bulk_pool() -> None:
     Starting a thread is nothing on an idle machine and 2.5 seconds on a busy
     one, which is precisely when bulk work is being handed over. So it is
     done here instead, at startup, before there is anything to be late for.
+
+    The durable write queue's pools are warmed here too, for the same reason:
+    their first renewal must not pay for starting a thread.
     """
-    pool = bulk_pool()
-    started = tuple(threading.Event() for _ in range(BULK_WORKERS))
+    _start_every_worker(bulk_pool(), BULK_WORKERS, "bulk_pool_warmup_timeout")
+    _start_every_worker(
+        durable_queue_pool(), DURABLE_QUEUE_WORKERS, "durable_queue_pool_warmup_timeout"
+    )
+    _start_every_worker(
+        lease_renewal_pool(), LEASE_RENEWAL_WORKERS, "lease_renewal_pool_warmup_timeout"
+    )
+
+
+def _start_every_worker(pool: ThreadPoolExecutor, workers: int, timeout_code: str) -> None:
+    started = tuple(threading.Event() for _ in range(workers))
     release = threading.Event()
 
     def occupy(marker: threading.Event) -> None:
@@ -117,7 +198,7 @@ def warm_bulk_pool() -> None:
     try:
         for marker in started:
             if not marker.wait(10):
-                raise RuntimeError("bulk_pool_warmup_timeout")
+                raise RuntimeError(timeout_code)
     finally:
         release.set()
     for future in futures:
@@ -175,6 +256,62 @@ async def in_interactive_read[T](
     return await in_read_pool(interactive_read_pool(), work, *args, **kwargs)
 
 
+async def in_sdk_read[T](
+    work: Callable[..., T],
+    /,
+    *args: object,
+    **kwargs: object,
+) -> T:
+    """A recall-path read, in recall's own pool (`memory_read_pool`)."""
+    return await in_read_pool(memory_read_pool(), work, *args, **kwargs)
+
+
+async def in_sdk_write[T](
+    work: Callable[..., T],
+    /,
+    *args: object,
+    **kwargs: object,
+) -> T:
+    """One SDK write call, in the write pool (`sdk_write_pool`)."""
+    return await asyncio.get_running_loop().run_in_executor(
+        sdk_write_pool(),
+        copy_context().run,
+        partial(work, *args, **kwargs),
+    )
+
+
+async def in_the_write_queue[T](
+    work: Callable[..., T],
+    /,
+    *args: object,
+    **kwargs: object,
+) -> T:
+    """One durable write queue statement, in the queue's pool (`durable_queue_pool`).
+
+    It still goes through the one writer and its line, like every write; what
+    it no longer does is wait for a bulk thread first.
+    """
+    return await asyncio.get_running_loop().run_in_executor(
+        durable_queue_pool(),
+        copy_context().run,
+        partial(work, *args, **kwargs),
+    )
+
+
+async def in_lease_renewal[T](
+    work: Callable[..., T],
+    /,
+    *args: object,
+    **kwargs: object,
+) -> T:
+    """One lease renewal, in the threads kept for nothing else (`lease_renewal_pool`)."""
+    return await asyncio.get_running_loop().run_in_executor(
+        lease_renewal_pool(),
+        copy_context().run,
+        partial(work, *args, **kwargs),
+    )
+
+
 def _retrieve[T](future: "asyncio.Future[T]") -> None:
     """Mark a shielded read's outcome as seen.
 
@@ -261,7 +398,16 @@ def _warm_reader_pool(reader: ThreadPoolExecutor) -> None:
 
 def shutdown_bulk_pool() -> None:
     global _pool, _snapshot_pool, _interactive_pool, _raw_read_pool, _memory_read_pool
-    global _source_reader_pool
+    global _source_reader_pool, _sdk_write_pool, _durable_queue_pool, _lease_renewal_pool
+    if _durable_queue_pool is not None:
+        _durable_queue_pool.shutdown(wait=False, cancel_futures=True)
+        _durable_queue_pool = None
+    if _lease_renewal_pool is not None:
+        _lease_renewal_pool.shutdown(wait=False, cancel_futures=True)
+        _lease_renewal_pool = None
+    if _sdk_write_pool is not None:
+        _sdk_write_pool.shutdown(wait=False, cancel_futures=True)
+        _sdk_write_pool = None
     if _pool is not None:
         _pool.shutdown(wait=False, cancel_futures=True)
         _pool = None

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

@@ -35,7 +35,7 @@ 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 typing import Any, TextIO  # noqa: E402
 
 from one_memory.config import load_settings  # noqa: E402
 from one_memory.runtime_client import RuntimeStatus, inspect_runtime  # noqa: E402
@@ -609,6 +609,14 @@ def _sdk_migration_status(options: Sequence[str], stream: TextIO) -> int:
         else:
             state = "required"
         document = {"schema_version": 1, "authority": authority.value, "state": state}
+        from one_memory.embedding_switch import read_open_job
+
+        # Informational. An unfinished embedding switch never makes a
+        # migration required or blocks it: the upgrade installs, `sdk-migrate`
+        # leaves the switch's tables alone, and the new Core resumes the job.
+        switch = read_open_job(database_path)
+        if switch is not None:
+            document["embedding_switch"] = switch
     from one_memory.sdk_migration_log import write_migration_log
 
     write_migration_log(
@@ -616,7 +624,15 @@ def _sdk_migration_status(options: Sequence[str], stream: TextIO) -> int:
         writer="core-sdk-migration-status",
         event="status.probed",
         outcome="succeeded",
-        details={"authority": document["authority"], "state": document["state"]},
+        details={
+            "authority": document["authority"],
+            "state": document["state"],
+            **(
+                {"embedding_switch": document["embedding_switch"]}
+                if "embedding_switch" in document
+                else {}
+            ),
+        },
     )
     if as_json:
         stream.write(f"{json.dumps(document, ensure_ascii=False)}\n")
@@ -696,6 +712,12 @@ def _refuse_unmigrated_home(data_dir: Path) -> None:
     raise SystemExit(SDK_MIGRATION_REQUIRED_EXIT)
 
 
+def _without_embedding_switch(settings: Any) -> Any:
+    """The maintenance Core's settings: it never resumes or runs a switch."""
+    copy = getattr(settings, "model_copy", None)
+    return copy(update={"embedding_switch_worker": False}) if callable(copy) else settings
+
+
 def serve(*, maintenance: bool = False) -> None:
     import uvicorn
 
@@ -740,7 +762,8 @@ def serve(*, maintenance: bool = False) -> None:
     if launcher is not None:
         ParentWatchdog(launcher).start()
     application = create_app(
-        settings,
+        # Only the serving Core runs or resumes an embedding switch.
+        _without_embedding_switch(settings) if maintenance else settings,
         manage_runtime=not maintenance,
     )
     if maintenance:

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

@@ -45,6 +45,11 @@ class Settings(BaseSettings):
     model_request_limit: int | None = Field(default=None, ge=1, le=100_000)
     model_request_body_byte_limit: int = Field(default=24_576, ge=1)
     model_request_output_token_limit: int = Field(default=16_384, ge=1)
+    # The embedding switch worker (and the startup merge). The maintenance
+    # Core turns it off: only the serving Core may resume or run a switch.
+    embedding_switch_worker: bool = True
+    # How long a switch waits for model writes already past their claim.
+    embedding_switch_drain_timeout_seconds: float = Field(default=600, gt=0)
 
     @field_validator("development_origin")
     @classmethod

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

@@ -66,6 +66,8 @@ class SdkContextSearchRequest(ContextSearchRequest, SdkSearchOptions):
     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)
+    #: Product callers can request one item per turn instead of SDK raw batches.
+    raw_unit: Literal["raw", "turn"] = "raw"
     #: Whose memories to search. The App never sends it and reads `local`.
     user_id: UserId = DEFAULT_USER_ID
 
@@ -123,6 +125,9 @@ class SdkRawContextItem(BaseModel):
     memory_at: datetime | None = None
     score: float = Field(ge=0, le=1)
     truncated: bool = False
+    turn_id: str | None = Field(default=None, min_length=1, max_length=96)
+    turn_index: int | None = Field(default=None, ge=0)
+    turn_count: int | None = Field(default=None, ge=1)
 
 
 class SdkMemoryContextItem(BaseModel):
@@ -155,6 +160,8 @@ class SdkContextSearchResponse(BaseModel):
     used_characters: int = Field(ge=0, le=20000)
     truncated: bool
     total_ms: float = Field(ge=0)
+    #: Whose memories were searched: the request's `user_id`, else `local`.
+    user_id: str = Field(min_length=1, max_length=64)
 
 
 class ContextLaneResult(BaseModel):

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

@@ -19,6 +19,7 @@ from one_memory.context_models import (
     SdkMemoryContextItem,
     SdkRawContextItem,
 )
+from one_memory.embedding_health import EMBEDDING_UNAVAILABLE, EmbeddingUnavailableError
 from one_memory.external_memory_access import external_access
 from one_memory.hy_runtime_config import HY_MEMORY_READER
 from one_memory.hy_sdk_runtime import sdk_relevance_floor
@@ -29,6 +30,7 @@ from one_memory.hy_sdk_types import (
     parse_sdk_search,
 )
 from one_memory.imports.storage import EvidenceStore
+from one_memory.raw_turns import raw_display_turns, turns_for_hit
 from one_memory.sdk_search_options import SdkSearchFilters, SearchLane
 from one_memory.semantic_deadline import SemanticMemoryHit
 from one_memory.user_scope import owns
@@ -69,6 +71,18 @@ def raw_lane_overrides(value: SdkSearchFilters) -> dict[str, object]:
     return found
 
 
+def raw_lane_statuses(*, lite: bool) -> dict[str, list[str]]:
+    """Which raw statuses the raw lane searches.
+
+    Lite extracts nothing, so its search is plain RAG over every raw,
+    including the shadow raws pro already processed before the switch to
+    lite. Pro and ultra keep the SDK default (active only): a shadow raw is
+    already represented by the memories extracted from it, and returning it
+    again would repeat that content in the caller's context budget.
+    """
+    return {"statuses": ["active", "shadow"]} if lite else {}
+
+
 def hit_namespace(hit: SemanticMemoryHit) -> dict[str, str]:
     """The `get` namespace of a hit: nothing for chat, kind and variant otherwise."""
     if hit.kind in {"experience", "fact"} and hit.variant is not None:
@@ -119,6 +133,9 @@ def sdk_context_router(dependencies: Sequence[Depends]) -> APIRouter:
             sources = raw_lane_sources(authority.raw_sources, value.include_sources)
             if sources is None:
                 return ()
+            # Plain RAG: every vector hit over the floor is an answer, ranked
+            # by its score. Each hit yields at least one item, so the SDK
+            # needs to return no more hits than the caller's limit.
             raw = await asyncio.to_thread(
                 client.search,
                 value.query,
@@ -134,27 +151,60 @@ def sdk_context_router(dependencies: Sequence[Depends]) -> APIRouter:
                     "scene": "chat",
                     "reader": HY_MEMORY_READER,
                     "layers": ["l1_raw"],
+                    **raw_lane_statuses(lite=lite),
                     **raw_lane_overrides(value),
                 },
             )
             hits = tuple(
                 hit for hit in parse_sdk_raw_search(raw) if value.passes_floor("raw", hit.score)
             )
-            return tuple(
-                SdkRawContextItem(
-                    raw_id=hit.raw_id,
-                    content=hit.content,
-                    source=hit.source,
-                    session_id=hit.session_id,
-                    memory_at=(
-                        datetime.fromtimestamp(hit.memory_at, tz=UTC)
-                        if hit.memory_at is not None
-                        else None
-                    ),
-                    score=hit.score,
+            # One item per hit first, so a hit is never crowded out by another
+            # hit's sibling turns; the siblings fill whatever room is left.
+            primary: list[SdkRawContextItem] = []
+            siblings: list[SdkRawContextItem] = []
+            for hit in hits:
+                memory_at = (
+                    datetime.fromtimestamp(hit.memory_at, tz=UTC)
+                    if hit.memory_at is not None
+                    else None
                 )
-                for hit in hits
-            )
+                turns = raw_display_turns(hit) if value.raw_unit == "turn" else ()
+                if not turns:
+                    primary.append(
+                        SdkRawContextItem(
+                            raw_id=hit.raw_id,
+                            content=hit.content,
+                            source=hit.source,
+                            session_id=hit.session_id,
+                            memory_at=memory_at,
+                            score=hit.score,
+                        )
+                    )
+                    continue
+                # The embedding is the batch's: the hit is shown by the turns
+                # that contain the query, or else by its closest turn, each
+                # with the hit's score.
+                shown = [
+                    SdkRawContextItem(
+                        raw_id=hit.raw_id,
+                        turn_id=turn.turn_id,
+                        turn_index=turn.turn_index,
+                        turn_count=turn.turn_count,
+                        content=turn.content,
+                        source=hit.source,
+                        session_id=hit.session_id,
+                        memory_at=memory_at,
+                        score=hit.score,
+                    )
+                    for turn in turns_for_hit(turns, value.query)
+                ]
+                primary.append(shown[0])
+                siblings.extend(shown[1:])
+            chosen = primary[: value.limit]
+            chosen.extend(siblings[: value.limit - len(chosen)])
+            # Stable: a hit's turns stay together, in hit-score order.
+            chosen.sort(key=lambda item: item.score, reverse=True)
+            return tuple(chosen)
 
         async def memory_lane() -> tuple[SdkMemoryContextItem, ...]:
             # lite extracts nothing: its search answers raw turns, which the
@@ -260,9 +310,14 @@ def sdk_context_router(dependencies: Sequence[Depends]) -> APIRouter:
                 used_characters=0,
                 truncated=True,
                 total_ms=(time.monotonic() - started) * 1000,
+                user_id=value.user_id,
             )
             await record(final, timed_out=True)
             return final
+        for lane in (raw_items, memory_items):
+            if isinstance(lane, EmbeddingUnavailableError):
+                # No lexical fallback: the query could not be embedded.
+                raise HTTPException(503, EMBEDDING_UNAVAILABLE)
         partial = isinstance(raw_items, Exception) or isinstance(memory_items, Exception)
         raw_candidates = (
             () if isinstance(raw_items, Exception) else cast(tuple[SdkContextItem, ...], raw_items)
@@ -301,6 +356,7 @@ def sdk_context_router(dependencies: Sequence[Depends]) -> APIRouter:
             used_characters=used,
             truncated=truncated,
             total_ms=(time.monotonic() - started) * 1000,
+            user_id=value.user_id,
         )
         await record(final, timed_out=False)
         return final

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

@@ -111,10 +111,26 @@ MAIN_DATABASE_CHECKPOINT_WRITE_INTERVAL = 64
 MAIN_DATABASE_CHECKPOINT_SECONDS = 30.0
 
 # Advisory only: PASSIVE cannot force a frame past a long reader. Crossing this
-# threshold is a signal that the WAL is not converging and that read snapshots
-# or write volume need investigation.
+# threshold with frames still waiting to be copied back is a signal that the
+# WAL is not converging and that read snapshots or write volume need
+# investigation. A large file whose frames are all checkpointed is not: the
+# idle TRUNCATE below gives that space back.
 MAIN_DATABASE_WAL_WARN_BYTES = 512 * 1024 * 1024
 
+# What a WAL file is cut back to once a checkpoint has copied every frame and
+# the writer starts it over. Without a limit SQLite reuses the file in place
+# and never shrinks it, so one import peak left a 639 MB WAL behind for good
+# (#245). 64 MiB is about sixteen times what the default autocheckpoint (1000
+# pages) lets build up between checkpoints, so ordinary write bursts reuse the
+# file without growing and shrinking it each time, and it is still a tenth of
+# what that user's disk was left holding.
+MAIN_DATABASE_JOURNAL_SIZE_LIMIT_BYTES = 64 * 1024 * 1024
+
+# How long an idle TRUNCATE may wait for the writer or for a reader to leave.
+# It runs only when nothing holds the database; anyone arriving in the
+# meantime wins, and the checkpoint is tried again on the next pass.
+MAIN_DATABASE_IDLE_CHECKPOINT_WAIT_MS = 50
+
 
 def checkpoint_write_interval() -> int:
     raw = os.environ.get(
@@ -226,6 +242,75 @@ class _InTurn:
             self._line.remove(place)
 
 
+class _Checkpointer:
+    """The one thread that runs cadence checkpoints, for every main database.
+
+    A database asks for at most one checkpoint at a time: a request made
+    while one is already waiting is the same request. The checkpoint goes
+    through the database's own writer, in its line, like any other write.
+    A waiting request holds the database weakly: it must not keep alive a
+    database nobody else holds any more.
+    """
+
+    def __init__(self) -> None:
+        self._state = threading.Condition()
+        self._due: OrderedDict[int, weakref.ref[MainDatabase]] = OrderedDict()
+        self._running = 0
+        self._thread: threading.Thread | None = None
+
+    def request(self, database: "MainDatabase") -> None:
+        with self._state:
+            self._due.setdefault(id(database), weakref.ref(database))
+            if self._thread is None or not self._thread.is_alive():
+                self._thread = threading.Thread(
+                    target=self._run,
+                    name="one-memory-checkpoint",
+                    daemon=True,
+                )
+                self._thread.start()
+            self._state.notify_all()
+
+    def forget(self, database: "MainDatabase") -> None:
+        with self._state:
+            self._due.pop(id(database), None)
+            self._state.notify_all()
+
+    def wait_idle(self, timeout: float) -> bool:
+        """Whether every requested checkpoint has run within `timeout` seconds."""
+        with self._state:
+            return self._state.wait_for(lambda: not self._due and not self._running, timeout)
+
+    def _run(self) -> None:
+        while True:
+            with self._state:
+                self._state.wait_for(lambda: bool(self._due))
+                _key, reference = self._due.popitem(last=False)
+                database = reference()
+                if database is None:
+                    self._state.notify_all()
+                    continue
+                self._running += 1
+            try:
+                database._cadence_checkpoint()
+            except Exception:  # noqa: BLE001 - maintenance must not end the thread
+                logger.warning(
+                    "main_database_checkpoint_failed file=%s", database.path.name, exc_info=True
+                )
+            finally:
+                del database
+                with self._state:
+                    self._running -= 1
+                    self._state.notify_all()
+
+
+_checkpointer = _Checkpointer()
+
+
+def wait_for_cadence_checkpoints(timeout: float = 5.0) -> bool:
+    """Wait for the cadence checkpoints already requested; for tests and shutdown."""
+    return _checkpointer.wait_idle(timeout)
+
+
 def _locked() -> sqlite3.OperationalError:
     # Callers tell a busy database from a broken one by these, as they would
     # for SQLite's own refusal.
@@ -276,6 +361,8 @@ class MainDatabase:
         self._writes_since_checkpoint = 0
         self._last_checkpoint_at = time.monotonic()
         self._wal_warned_at = 0.0
+        #: Learned from the first checkpoint; turns WAL frames into bytes.
+        self._page_size = 4096
         self._reader_started_at: dict[int, float] = {}
 
     @contextmanager
@@ -542,24 +629,77 @@ class MainDatabase:
     def _checkpoint_from_maintenance(self, mode: str) -> tuple[int, int, int]:
         return self._checkpoint(mode, maintenance=True)
 
-    def _checkpoint(self, mode: str, *, maintenance: bool) -> tuple[int, int, int]:
+    def _checkpoint(
+        self,
+        mode: str,
+        *,
+        maintenance: bool,
+        busy_timeout_ms: int = WRITE_LOCK_WAIT_MS,
+    ) -> tuple[int, int, int]:
         normalized = mode.strip().upper()
         if normalized not in {"PASSIVE", "FULL", "RESTART", "TRUNCATE"}:
             raise ValueError("unsupported WAL checkpoint mode")
-        with self.write(autocommit=True, maintenance=maintenance) as connection:
+        with self.write(
+            autocommit=True, maintenance=maintenance, busy_timeout_ms=busy_timeout_ms
+        ) as connection:
             row = connection.execute(f"PRAGMA wal_checkpoint({normalized})").fetchone()
+            page_size = connection.execute("PRAGMA page_size").fetchone()
         if row is None or len(row) != 3:
             raise sqlite3.DatabaseError("SQLite returned an invalid checkpoint result")
+        if page_size is not None:
+            self._page_size = int(page_size[0])
         return int(row[0]), int(row[1]), int(row[2])
 
+    def idle(self) -> bool:
+        """Nobody holds or waits for a connection to this database right now."""
+        with self._state:
+            return (
+                self._writer_owner is None
+                and not self._reader_holders
+                and not len(self._write_line)
+                and not len(self._read_line)
+            )
+
+    def checkpoint_if_idle(self) -> tuple[int, int, int] | None:
+        """Give the WAL file back to the disk while nothing is using the database.
+
+        PASSIVE copies frames back but leaves the file its size; only TRUNCATE
+        empties it, and TRUNCATE has to wait for every reader to finish, so it
+        is attempted only when this process holds no checkout at all, and with
+        a wait of a few milliseconds. A busy result, or someone arriving in
+        between, is not a failure: the next idle pass tries again. Returns the
+        checkpoint result, or None when it was not attempted or not admitted.
+        """
+        if not self.idle() or self._wal_bytes() == 0:
+            return None
+        try:
+            return self._checkpoint(
+                "TRUNCATE",
+                maintenance=True,
+                busy_timeout_ms=MAIN_DATABASE_IDLE_CHECKPOINT_WAIT_MS,
+            )
+        except sqlite3.Error:
+            logger.debug("main_database_idle_checkpoint_skipped file=%s", self.path.name)
+            return None
+
     def _maybe_checkpoint_after_write(self) -> None:
-        """Checkpoint on a write cadence without opening another connection.
+        """Count a write, and hand a due cadence checkpoint to the checkpointer.
 
         SQLite's default autocheckpoint only runs when the writer itself
         crosses the page threshold. Production hit a state where the WAL grew
         to 13GB, so the main database needs its own bounded, observable
-        maintenance path. This runs after the caller's checkout has been reset
-        and only re-enters the same serialized writer queue.
+        maintenance path: every `checkpoint_write_interval()` writes or
+        `MAIN_DATABASE_CHECKPOINT_SECONDS`, whichever comes first.
+
+        The checkpoint itself used to run right here, on the thread that had
+        just written, as one more turn in the writer's line. That thread was
+        an import heartbeat or a durable lease renewal as often as not, and
+        it then waited behind the whole line a second time before it could
+        return. The idle TRUNCATE (#278) cannot replace the cadence: under a
+        sustained import the database is never idle, and that is exactly when
+        the WAL grows. So the cadence stays, and one checkpointer thread runs
+        it (`_Checkpointer`); the writer stays the only connection that
+        writes, and no caller waits for maintenance it did not ask for.
         """
         now = time.monotonic()
         with self._state:
@@ -571,25 +711,35 @@ class MainDatabase:
             if due:
                 self._writes_since_checkpoint = 0
                 self._last_checkpoint_at = now
-        if not due:
-            return
+        if due:
+            _checkpointer.request(self)
+
+    def _cadence_checkpoint(self) -> None:
+        """One PASSIVE checkpoint through the writer, and the WAL alert after it."""
+        now = time.monotonic()
         try:
             busy, log_frames, checkpointed = self._checkpoint_from_maintenance("PASSIVE")
         except sqlite3.Error:
             logger.warning("main_database_checkpoint_failed file=%s", self.path.name, exc_info=True)
             return
         wal_bytes = self._wal_bytes()
-        if wal_bytes >= MAIN_DATABASE_WAL_WARN_BYTES:
+        # Frames the checkpoint could not copy back yet: what a reader is
+        # holding up. The file size alone also counts space already
+        # checkpointed and only waiting to be reused or truncated, which is
+        # not the WAL failing to converge.
+        pending_bytes = max(0, log_frames - checkpointed) * self._page_size
+        if pending_bytes >= MAIN_DATABASE_WAL_WARN_BYTES:
             with self._state:
                 should_warn = now - self._wal_warned_at >= MAIN_DATABASE_REPORT_SECONDS
                 if should_warn:
                     self._wal_warned_at = now
             if should_warn:
                 logger.warning(
-                    "main_database_wal_high file=%s wal_bytes=%d busy=%d "
+                    "main_database_wal_high file=%s wal_bytes=%d pending_bytes=%d busy=%d "
                     "log_frames=%d checkpointed=%d readers_in_use=%d",
                     self.path.name,
                     wal_bytes,
+                    pending_bytes,
                     busy,
                     log_frames,
                     checkpointed,
@@ -640,6 +790,8 @@ class MainDatabase:
 
     def close(self) -> None:
         """Close every idle connection now; ones in use close when handed back."""
+        # A checkpoint still waiting would open the writer again after this.
+        _checkpointer.forget(self)
         with self._state:
             self._generation += 1
             self._identity = None
@@ -784,6 +936,10 @@ class MainDatabase:
         try:
             if wal:
                 enable_write_ahead_log(connection, wait_ms=busy_timeout_ms)
+            # Only the writer restarts the WAL, so only the writer needs the cap.
+            connection.execute(
+                f"PRAGMA journal_size_limit = {int(MAIN_DATABASE_JOURNAL_SIZE_LIMIT_BYTES)}"
+            )
             _seal(connection)
             if busy_timeout_ms != WRITE_LOCK_WAIT_MS:
                 # Opened at the caller's wait; every checkout starts at the default.
@@ -1027,6 +1183,18 @@ def main_database_transaction(
         yield connection
 
 
+def checkpoint_idle_main_databases() -> int:
+    """TRUNCATE the WAL of every database nobody is using; how many were emptied."""
+    with _databases_lock:
+        databases = list(_alive.values())
+    emptied = 0
+    for database in databases:
+        result = database.checkpoint_if_idle()
+        if result is not None and result[0] == 0:
+            emptied += 1
+    return emptied
+
+
 def close_main_databases() -> None:
     """Close every connection this process holds; used when the Core stops."""
     with _databases_lock:
@@ -1050,6 +1218,9 @@ async def report_main_database(seconds: float) -> None:
     while True:
         await asyncio.sleep(seconds)
         log_main_database_stats("periodic")
+        # The idle signal is this process's own checkouts: none held, none
+        # waiting. Off the loop, since a checkpoint is disk work however short.
+        await asyncio.to_thread(checkpoint_idle_main_databases)
 
 
 def main_database_stats() -> dict[str, float | int]:

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

@@ -0,0 +1,180 @@
+"""What the embedding switch needs from the SDK's re-embed module, in Core terms.
+
+The switch worker, the startup merge and the retention sweep only talk to a
+`ReembedBackend`. The production one (`hy_sdk_migration.SdkReembedBackend`)
+is the single place that calls `hy_memory`'s re-embed functions; tests use
+an in-memory one. Every space is named explicitly -- collection names and
+graph paths -- and nothing here derives a name from a provider or endpoint.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable, Mapping
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Protocol
+
+from one_memory.embedding_spaces import EmbeddingSpace, space_collection_names
+from one_memory.model_profiles import ModelProfileSnapshot
+
+
+class ReembedUnavailableError(RuntimeError):
+    """The installed SDK has no re-embed module (before hy-memory 2.0.10)."""
+
+    def __init__(self, code: str = "sdk_reembed_unavailable") -> None:
+        super().__init__(code)
+        self.code = code
+
+
+class ReembedCancelledError(RuntimeError):
+    """A cancel was seen at a batch boundary; every finished batch is written."""
+
+
+class EmbeddingWidthError(RuntimeError):
+    """The embedding service returned vectors of another width than the target's."""
+
+
+@dataclass(frozen=True)
+class PhysicalSpace:
+    """One space's collections, named explicitly."""
+
+    collection_base: str
+    name_dims: int | None
+    #: The width of the vectors in it, or to be written to it.
+    dims: int | None
+    model: str | None = None
+    #: Explicit role -> collection name; None derives them from the base.
+    collections: Mapping[str, str] | None = None
+
+    def names(self) -> dict[str, str]:
+        if self.collections is not None:
+            return dict(self.collections)
+        return space_collection_names(self.collection_base, self.name_dims)
+
+    @classmethod
+    def of(cls, space: EmbeddingSpace) -> PhysicalSpace:
+        return cls(
+            collection_base=space.collection_base,
+            name_dims=space.name_dims,
+            dims=space.dims if space.dims is not None else space.name_dims,
+            model=space.model,
+        )
+
+
+@dataclass(frozen=True)
+class ScannedSpace:
+    """A space found in the vector store, grouped from its collection names."""
+
+    collection_base: str
+    name_dims: int | None
+    #: The stored width when every non-empty role agrees.
+    width: int | None
+    counts: Mapping[str, int]
+    collections: Mapping[str, str]
+    per_user: Mapping[str, int] = field(default_factory=dict)
+
+    @property
+    def vectors(self) -> int:
+        return sum(self.counts.values())
+
+    @property
+    def key(self) -> tuple[str, int]:
+        return (self.collection_base, self.name_dims or 0)
+
+    def physical(self) -> PhysicalSpace:
+        return PhysicalSpace(
+            collection_base=self.collection_base,
+            name_dims=self.name_dims,
+            dims=self.width if self.width is not None else self.name_dims,
+            collections=dict(self.collections),
+        )
+
+
+@dataclass(frozen=True)
+class ReembedStep:
+    """Progress of one role (vectors) or table (graph)."""
+
+    phase: str
+    role: str
+    done: int
+    total: int
+    embedded: int = 0
+    reused: int = 0
+    kept: int = 0
+
+
+@dataclass(frozen=True)
+class VectorCheck:
+    per_role: Mapping[str, Mapping[str, int]]
+    #: Target records per metadata `user_id`.
+    per_user: Mapping[str, int]
+    problems: tuple[str, ...]
+    warnings: tuple[str, ...] = ()
+    self_recall_hits: int = 0
+    self_recall_samples: int = 0
+
+
+@dataclass(frozen=True)
+class GraphCheck:
+    ok: bool
+    problems: tuple[str, ...] = ()
+
+
+@dataclass(frozen=True)
+class EmbeddingTarget:
+    """The embedding that fills a space: the profile to reach it, and its key."""
+
+    profile: ModelProfileSnapshot
+    space: EmbeddingSpace
+    api_key: str | None
+
+
+Cancel = Callable[[], bool]
+OnStep = Callable[[ReembedStep], None]
+
+
+class ReembedBackend(Protocol):
+    def unavailable_reason(self) -> str | None:
+        """None when re-embedding works; otherwise the code that says why not."""
+
+    async def scan(self, *, per_user: bool = False) -> tuple[ScannedSpace, ...]:
+        """Every space with collections in the home's vector store. Read-only."""
+
+    async def diff(self, source: PhysicalSpace, target: PhysicalSpace) -> dict[str, int]:
+        """Per role, how many ids the source holds that the target does not."""
+
+    async def reembed(
+        self,
+        source: PhysicalSpace,
+        target: PhysicalSpace,
+        *,
+        embedding: EmbeddingTarget,
+        cancel: Cancel,
+        on_step: OnStep,
+        batch_size: int = 64,
+    ) -> None:
+        """Embed every source record the target lacks into the target. Target wins."""
+
+    async def verify(
+        self, source: PhysicalSpace, target: PhysicalSpace, *, embedding: EmbeddingTarget
+    ) -> VectorCheck: ...
+
+    async def graph_vectors(self, path: Path) -> int | None:
+        """Embeddings a graph holds, or None when there is no graph there."""
+
+    async def reembed_graph(
+        self,
+        source: Path,
+        target: Path,
+        *,
+        embedding: EmbeddingTarget,
+        target_dims: int,
+        cancel: Cancel,
+        on_step: OnStep,
+    ) -> None: ...
+
+    async def verify_graph(self, source: Path, target: Path, *, target_dims: int) -> GraphCheck: ...
+
+    async def drop(self, space: PhysicalSpace) -> None: ...
+
+    async def drop_graph(self, path: Path) -> None: ...

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

@@ -0,0 +1,147 @@
+"""`embedding_unavailable`: a search that could not embed its query says so.
+
+With a remote embedding model, every search embeds the query through that
+service. When the service is down, the SDK swallows the failure and answers
+with no hits, which reads as "you have no such memory". There is no lexical
+fallback (owner decision): the search fails with the explicit code
+`embedding_unavailable`, the API answers 503 with that code, and the App
+shows a toast.
+
+The check is only made when a search came back empty or raised, so a working
+service costs nothing on searches that find something. It sends one tiny
+embedding request to the same endpoint, model and width the read client
+uses; the answer is remembered briefly so a burst of searches sends one.
+"""
+
+from __future__ import annotations
+
+import threading
+import time
+from collections.abc import Callable, Mapping
+from typing import Any
+
+import httpx
+
+from one_memory.http_client import create_client
+from one_memory.hy_sdk_types import HySdkError
+from one_memory.model_profiles import ModelProfileSnapshot, ProviderKind
+
+EMBEDDING_UNAVAILABLE = "embedding_unavailable"
+_OK_TTL_S = 30.0
+_FAILED_TTL_S = 10.0
+_TIMEOUT_S = 8.0
+
+
+def _no_transport() -> httpx.BaseTransport | None:
+    return None
+
+
+#: Tests replace this to answer the check without a network.
+transport_factory: Callable[[], httpx.BaseTransport | None] = _no_transport
+
+
+class EmbeddingUnavailableError(HySdkError):
+    """The live space's embedding service did not answer; search cannot run."""
+
+    def __init__(self) -> None:
+        super().__init__(EMBEDDING_UNAVAILABLE)
+
+
+class EmbeddingHealth:
+    """Whether a remote embedding answers, remembered for a few seconds."""
+
+    def __init__(self) -> None:
+        self._lock = threading.Lock()
+        self._known: dict[tuple[str, str, int | None], tuple[bool, float]] = {}
+
+    def available(
+        self,
+        profile: ModelProfileSnapshot,
+        *,
+        endpoint: str | None,
+        name_dims: int | None,
+        api_key: str | None,
+    ) -> bool:
+        provider = profile.embedding_provider_kind or profile.provider_kind
+        if provider is ProviderKind.LOCAL_ONNX or endpoint is None:
+            return True
+        model = profile.embedding_model or ""
+        key = (endpoint, model, name_dims)
+        now = time.monotonic()
+        with self._lock:
+            known = self._known.get(key)
+            if known is not None and known[1] > now:
+                return known[0]
+        ok = _answers(
+            endpoint,
+            model=model,
+            name_dims=name_dims,
+            api_key="ollama" if provider is ProviderKind.OLLAMA else api_key,
+        )
+        with self._lock:
+            self._known[key] = (ok, now + (_OK_TTL_S if ok else _FAILED_TTL_S))
+        return ok
+
+    def forget(self) -> None:
+        with self._lock:
+            self._known.clear()
+
+
+def _answers(endpoint: str, *, model: str, name_dims: int | None, api_key: str | None) -> bool:
+    body: dict[str, Any] = {"model": model, "input": ["ping"]}
+    if name_dims:
+        body["dimensions"] = name_dims
+    headers = {"Authorization": f"Bearer {api_key}"} if api_key else {}
+    transport = transport_factory()
+    try:
+        with create_client(
+            timeout=_TIMEOUT_S,
+            **({"transport": transport} if transport is not None else {}),
+        ) as client:
+            response = client.post(f"{endpoint.rstrip('/')}/embeddings", json=body, headers=headers)
+        if response.status_code != 200:
+            return False
+        data = response.json().get("data")
+        return bool(isinstance(data, list) and data and data[0].get("embedding"))
+    except (httpx.HTTPError, ValueError, AttributeError):
+        return False
+
+
+def has_hits(result: object) -> bool:
+    """Whether an SDK search result holds any hit, whatever its scene's shape."""
+    if not isinstance(result, Mapping):
+        return bool(result)
+    for key in ("memories", "facts", "experiences"):
+        value = result.get(key)
+        if isinstance(value, list) and value:
+            return True
+        if isinstance(value, Mapping) and any(
+            isinstance(item, list) and item for item in value.values()
+        ):
+            return True
+    return False
+
+
+class EmbeddingGuardedClient:
+    """An SDK client whose `search` reports a dead embedding instead of nothing.
+
+    Everything else is the client's own attribute, unchanged.
+    """
+
+    def __init__(self, client: Any, available: Callable[[], bool]) -> None:
+        self._client = client
+        self._available = available
+
+    def search(self, *args: Any, **kwargs: Any) -> Any:
+        try:
+            result = self._client.search(*args, **kwargs)
+        except Exception:
+            if not self._available():
+                raise EmbeddingUnavailableError() from None
+            raise
+        if not has_hits(result) and not self._available():
+            raise EmbeddingUnavailableError()
+        return result
+
+    def __getattr__(self, name: str) -> Any:
+        return getattr(self._client, name)

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

@@ -0,0 +1,554 @@
+"""Which embedding space the home reads and writes: an explicit registry.
+
+The SDK names its vector collections after `vector_store.collection_name`
+and the configured width, so the space used to follow whatever the active
+profile hashed to (`_collection_base`). Any change to that identity -- a
+probe recording the measured width, a new endpoint -- silently opened new,
+empty collections beside the old ones, and nothing carried the memories over.
+
+The live space is pinned here instead, in the main Core database beside the
+model profiles, so a switch commits the new space and the profile that fills
+it in one transaction. The identity of a space is its embedding model and
+width only: a new endpoint or provider serving the same model at the same
+width keeps the space.
+
+Existing homes keep their collections byte-for-byte. The first start registers
+the space the active profile (or the built-in model) already opened under its
+existing four-attribute name; only spaces created by a switch use the
+model-and-width name. A space whose width was never declared ("auto") keeps
+its unsuffixed name and only records the width it was measured at.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import sqlite3
+from collections.abc import Iterator, Mapping
+from contextlib import contextmanager
+from datetime import UTC, datetime, timedelta
+from pathlib import Path
+from typing import Literal
+from uuid import uuid4
+
+from pydantic import BaseModel, ConfigDict
+
+from one_memory.database import take_the_write_lock_first
+from one_memory.database_access import main_database
+from one_memory.embedding_assets import BUILTIN_EMBEDDING_DIMENSIONS, BUILTIN_EMBEDDING_MODEL
+from one_memory.memory_server.migrations import embedding_spaces_ddl
+from one_memory.model_profiles import ModelProfileSnapshot, ProviderKind
+
+#: How long a space replaced by a switch or folded in by a merge is kept.
+RETIRED_SPACE_RETENTION = timedelta(days=14)
+
+SpaceState = Literal["live", "building", "stray", "retired", "dropped"]
+SpaceNaming = Literal["legacy", "v2", "discovered"]
+
+#: Every vector collection one space consists of, as the SDK names them.
+VECTOR_ROLES = (
+    "memory",
+    "entities",
+    "coding_keys",
+    "coding_keys_cv",
+    "working_facts",
+    "working_facts_cv",
+)
+
+#: The graph directory of the first space; later spaces get their own.
+DEFAULT_GRAPH_DIR = "graph"
+
+EMBEDDING_SPACES_SCHEMA = embedding_spaces_ddl()
+
+
+#: Bumped by every registry write in this process, so cached live rows are
+#: reread after a change made through any connection (a probe's, a commit's).
+_CHANGES = [0]
+
+
+def _changed() -> None:
+    _CHANGES[0] += 1
+
+
+class EmbeddingSpaceError(RuntimeError):
+    """A registry refusal with a stable, product-facing code."""
+
+    def __init__(self, code: str) -> None:
+        super().__init__(code)
+        self.code = code
+
+
+class EmbeddingIdentity(BaseModel):
+    """What makes two vectors comparable: the model and the width.
+
+    `dims=None` is a width nobody declared or measured yet; it matches any
+    width, because the collection it names was opened without one.
+    """
+
+    model_config = ConfigDict(frozen=True, extra="forbid")
+
+    model: str
+    dims: int | None = None
+
+    def matches(self, other: EmbeddingIdentity) -> bool:
+        if self.model != other.model:
+            return False
+        return self.dims is None or other.dims is None or self.dims == other.dims
+
+
+class EmbeddingSpace(BaseModel):
+    """One embedding space: the physical collections and graph one model fills."""
+
+    model_config = ConfigDict(frozen=True, extra="forbid")
+
+    space_id: str
+    state: SpaceState
+    #: None only for a space found on disk that no registry row named.
+    model: str | None = None
+    #: The vector width stored in this space, once known.
+    dims: int | None = None
+    #: The width the collection names and embedding requests carry. None is
+    #: an "auto" space: unsuffixed names and no `dimensions` request field.
+    name_dims: int | None = None
+    collection_base: str
+    naming: SpaceNaming = "legacy"
+    graph_dir: str | None = DEFAULT_GRAPH_DIR
+    provider_kind: str | None = None
+    #: The profile version whose embedding fills this space; None = built-in.
+    profile_id: str | None = None
+    profile_revision: int | None = None
+    #: Vectors counted the last time the space was scanned.
+    vectors: int | None = None
+    created_at: str
+    live_since: str | None = None
+    retired_at: str | None = None
+    keep_until: str | None = None
+    dropped_at: str | None = None
+
+    @property
+    def identity(self) -> EmbeddingIdentity | None:
+        if self.model is None:
+            return None
+        return EmbeddingIdentity(model=self.model, dims=self.dims)
+
+    @property
+    def builtin(self) -> bool:
+        return self.provider_kind == ProviderKind.LOCAL_ONNX.value and self.profile_id is None
+
+    def collection_names(self) -> dict[str, str]:
+        return space_collection_names(self.collection_base, self.name_dims)
+
+
+def space_collection_names(base: str, name_dims: int | None) -> dict[str, str]:
+    """The SDK's physical collection name per role for one space.
+
+    Mirrors `VectorStoreBase` (the `_<dims>` suffix), the entity store and the
+    coding stores. The SDK's own `vector_space_names` is checked against this
+    in the migration adapter when the installed SDK provides it.
+    """
+    suffix = f"_{name_dims}" if name_dims else ""
+    return {
+        "memory": f"{base}{suffix}",
+        "entities": f"{base}{suffix}_entities",
+        "coding_keys": f"{base}_coding_keys{suffix}",
+        "coding_keys_cv": f"{base}_coding_keys_cv{suffix}",
+        "working_facts": f"{base}_working_facts{suffix}",
+        "working_facts_cv": f"{base}_working_facts_cv{suffix}",
+    }
+
+
+def embedding_identity(profile: ModelProfileSnapshot) -> EmbeddingIdentity:
+    """The embedding identity a profile asks for: model name and width only."""
+    provider = profile.embedding_provider_kind or profile.provider_kind
+    local = provider is ProviderKind.LOCAL_ONNX
+    model = profile.embedding_model or (BUILTIN_EMBEDDING_MODEL if local else None)
+    if not model:
+        raise EmbeddingSpaceError("hy_sdk_embedding_model_required")
+    dims = profile.embedding_dimensions
+    if local and dims is None:
+        dims = BUILTIN_EMBEDDING_DIMENSIONS
+    return EmbeddingIdentity(model=model, dims=dims)
+
+
+def v2_collection_base(identity: EmbeddingIdentity, generation: int = 0) -> str:
+    """The base name a switch gives a new space: model and width, nothing else."""
+    digest = hashlib.sha256(f"{identity.model}\0{identity.dims or 'auto'}".encode()).hexdigest()
+    base = f"memhub_e_{digest[:16]}"
+    return f"{base}_g{generation}" if generation else base
+
+
+def graph_dir_for(space_id: str) -> str:
+    return f"graph-{space_id[:8]}"
+
+
+def derived_space(profile: ModelProfileSnapshot) -> EmbeddingSpace:
+    """The space `profile` opened before the registry existed, under its old name.
+
+    Never stored as is: bootstrap stores it, and offline tools that run beside
+    a home with no registry yet read through it.
+    """
+    from one_memory.hy_sdk_runtime import legacy_collection_base
+
+    provider = profile.embedding_provider_kind or profile.provider_kind
+    identity = embedding_identity(profile)
+    builtin = profile.profile_id == _BUILTIN_PROFILE_ID
+    return EmbeddingSpace(
+        space_id="derived",
+        state="live",
+        model=identity.model,
+        dims=identity.dims,
+        name_dims=identity.dims,
+        collection_base=legacy_collection_base(profile),
+        naming="legacy",
+        graph_dir=DEFAULT_GRAPH_DIR,
+        provider_kind=provider.value,
+        profile_id=None if builtin else profile.profile_id,
+        profile_revision=None if builtin else profile.revision,
+        created_at=_now(),
+    )
+
+
+_BUILTIN_PROFILE_ID = "builtin-retrieval"
+
+
+def _now() -> str:
+    return datetime.now(UTC).isoformat()
+
+
+def _row(row: sqlite3.Row | Mapping[str, object]) -> EmbeddingSpace:
+    return EmbeddingSpace.model_validate(dict(row))
+
+
+def ensure_schema(connection: sqlite3.Connection) -> None:
+    connection.executescript(EMBEDDING_SPACES_SCHEMA)
+
+
+def registry_present(connection: sqlite3.Connection) -> bool:
+    return (
+        connection.execute(
+            "SELECT 1 FROM sqlite_master WHERE type='table' AND name='embedding_spaces'"
+        ).fetchone()
+        is not None
+    )
+
+
+def live_space_in(connection: sqlite3.Connection) -> EmbeddingSpace | None:
+    if not registry_present(connection):
+        return None
+    previous = connection.row_factory
+    connection.row_factory = sqlite3.Row
+    try:
+        row = connection.execute("SELECT * FROM embedding_spaces WHERE state='live'").fetchone()
+    finally:
+        connection.row_factory = previous
+    return _row(row) if row is not None else None
+
+
+def read_live_space(database_path: Path) -> EmbeddingSpace | None:
+    """The live space, read only, or None for a home with no registry yet."""
+    if not database_path.is_file():
+        return None
+    with main_database(database_path).read(row_factory=sqlite3.Row) as connection:
+        return live_space_in(connection)
+
+
+class EmbeddingSpaceStore:
+    """The `embedding_spaces` table of the main Core database."""
+
+    def __init__(self, database_path: Path) -> None:
+        self.database_path = database_path
+        #: The live row, read once per change: every read and write asks for
+        #: it. Only this process writes the registry while Core serves.
+        self._live_cache: tuple[int, EmbeddingSpace] | None = None
+        with self._connect(writing=True) as connection:
+            ensure_schema(connection)
+
+    def invalidate(self) -> None:
+        _changed()
+
+    @contextmanager
+    def _connect(
+        self, *, writing: bool = False, lock_first: bool = True
+    ) -> Iterator[sqlite3.Connection]:
+        database = main_database(self.database_path)
+        checkout = (
+            database.write(row_factory=sqlite3.Row)
+            if writing
+            else database.read(row_factory=sqlite3.Row)
+        )
+        with checkout as connection, connection:
+            if writing and lock_first:
+                take_the_write_lock_first(connection)
+            yield connection
+
+    @contextmanager
+    def transaction(self) -> Iterator[sqlite3.Connection]:
+        """One `BEGIN IMMEDIATE` on the main database, committed on success."""
+        _changed()
+        try:
+            with self._connect(writing=True, lock_first=False) as connection:
+                connection.execute("BEGIN IMMEDIATE")
+                yield connection
+        finally:
+            _changed()
+
+    def live(self) -> EmbeddingSpace | None:
+        generation = _CHANGES[0]
+        cached = self._live_cache
+        if cached is not None and cached[0] == generation:
+            return cached[1]
+        with self._connect() as connection:
+            space = live_space_in(connection)
+        self._live_cache = (generation, space) if space is not None else None
+        return space
+
+    def require_live(self) -> EmbeddingSpace:
+        space = self.live()
+        if space is None:
+            raise EmbeddingSpaceError("embedding_space_not_bootstrapped")
+        return space
+
+    def get(self, space_id: str) -> EmbeddingSpace | None:
+        with self._connect() as connection:
+            row = connection.execute(
+                "SELECT * FROM embedding_spaces WHERE space_id=?", (space_id,)
+            ).fetchone()
+        return _row(row) if row is not None else None
+
+    def list_spaces(self, *, include_dropped: bool = False) -> list[EmbeddingSpace]:
+        with self._connect() as connection:
+            rows = connection.execute(
+                "SELECT * FROM embedding_spaces "
+                + ("" if include_dropped else "WHERE state != 'dropped' ")
+                + "ORDER BY created_at, space_id"
+            ).fetchall()
+        return [_row(row) for row in rows]
+
+    def bootstrap(self, active: ModelProfileSnapshot | None) -> EmbeddingSpace:
+        """Register the space this home already uses, once, under its existing name.
+
+        `active` is the active profile, or None for the built-in model. The
+        collection name is derived exactly as before the registry, so nothing
+        on disk moves.
+        """
+        from one_memory.hy_sdk_runtime import builtin_retrieval_snapshot
+
+        with self.transaction() as connection:
+            existing = live_space_in(connection)
+            if existing is not None:
+                return existing
+            derived = derived_space(active or builtin_retrieval_snapshot())
+            space = derived.model_copy(
+                update={"space_id": str(uuid4()), "live_since": derived.created_at}
+            )
+            _insert(connection, space)
+            return space
+
+    def record_width(self, space_id: str, dims: int) -> EmbeddingSpace:
+        """A relabel: the space's stored width is now known. Names never change."""
+        with self.transaction() as connection:
+            record_width_in(connection, space_id, dims)
+        space = self.get(space_id)
+        if space is None:  # pragma: no cover - the row was just updated
+            raise EmbeddingSpaceError("embedding_space_not_found")
+        return space
+
+    def record_vectors(self, counts: Mapping[str, int]) -> None:
+        """Cache the vector count per space id from the last scan (display only)."""
+        if not counts:
+            return
+        _changed()
+        with self._connect(writing=True) as connection:
+            connection.executemany(
+                "UPDATE embedding_spaces SET vectors=? WHERE space_id=?",
+                [(count, space_id) for space_id, count in counts.items()],
+            )
+
+    def register_stray(
+        self,
+        *,
+        collection_base: str,
+        name_dims: int | None,
+        dims: int | None,
+        vectors: int,
+    ) -> EmbeddingSpace:
+        """Name a non-empty space the scan found that no row described."""
+        with self.transaction() as connection:
+            row = connection.execute(
+                "SELECT * FROM embedding_spaces WHERE collection_base=? "
+                "AND COALESCE(name_dims,0)=? AND state != 'dropped'",
+                (collection_base, name_dims or 0),
+            ).fetchone()
+            if row is not None:
+                return _row(row)
+            space = EmbeddingSpace(
+                space_id=str(uuid4()),
+                state="stray",
+                dims=dims,
+                name_dims=name_dims,
+                collection_base=collection_base,
+                naming="discovered",
+                graph_dir=None,
+                vectors=vectors,
+                created_at=_now(),
+            )
+            _insert(connection, space)
+            return space
+
+    def mark_dropped(self, space_id: str) -> None:
+        _changed()
+        with self._connect(writing=True) as connection:
+            connection.execute(
+                "UPDATE embedding_spaces SET state='dropped', dropped_at=? "
+                "WHERE space_id=? AND state IN ('retired','building')",
+                (_now(), space_id),
+            )
+
+    def expired(self, *, now: datetime | None = None) -> list[EmbeddingSpace]:
+        moment = (now or datetime.now(UTC)).isoformat()
+        with self._connect() as connection:
+            rows = connection.execute(
+                "SELECT * FROM embedding_spaces WHERE state='retired' "
+                "AND keep_until IS NOT NULL AND keep_until <= ?",
+                (moment,),
+            ).fetchall()
+        return [_row(row) for row in rows]
+
+
+def registry_for(profiles: object) -> EmbeddingSpaceStore | None:
+    """The registry beside a profile store, or None for a store with no database."""
+    path = getattr(profiles, "database_path", None)
+    return EmbeddingSpaceStore(path) if isinstance(path, Path) else None
+
+
+def _insert(connection: sqlite3.Connection, space: EmbeddingSpace) -> None:
+    values = space.model_dump()
+    columns = ", ".join(values)
+    marks = ", ".join("?" for _ in values)
+    connection.execute(
+        f"INSERT INTO embedding_spaces ({columns}) VALUES ({marks})",
+        tuple(values.values()),
+    )
+
+
+def insert_space_in(connection: sqlite3.Connection, space: EmbeddingSpace) -> None:
+    _changed()
+    _insert(connection, space)
+
+
+def record_width_in(connection: sqlite3.Connection, space_id: str, dims: int) -> None:
+    _changed()
+    changed = connection.execute(
+        "UPDATE embedding_spaces SET dims=? WHERE space_id=? AND (dims IS NULL OR dims=?)",
+        (dims, space_id, dims),
+    )
+    if changed.rowcount != 1:
+        raise EmbeddingSpaceError("embedding_space_width_conflict")
+
+
+def space_in(connection: sqlite3.Connection, space_id: str) -> EmbeddingSpace | None:
+    previous = connection.row_factory
+    connection.row_factory = sqlite3.Row
+    try:
+        row = connection.execute(
+            "SELECT * FROM embedding_spaces WHERE space_id=?", (space_id,)
+        ).fetchone()
+    finally:
+        connection.row_factory = previous
+    return _row(row) if row is not None else None
+
+
+def spaces_in(connection: sqlite3.Connection) -> list[EmbeddingSpace]:
+    previous = connection.row_factory
+    connection.row_factory = sqlite3.Row
+    try:
+        rows = connection.execute("SELECT * FROM embedding_spaces").fetchall()
+    finally:
+        connection.row_factory = previous
+    return [_row(row) for row in rows]
+
+
+def set_state_in(
+    connection: sqlite3.Connection,
+    space_id: str,
+    *,
+    state: SpaceState,
+    expected: tuple[SpaceState, ...],
+    now: datetime | None = None,
+) -> None:
+    """Move one space between states, refusing any it was not expected in."""
+    _changed()
+    moment = now or datetime.now(UTC)
+    updates: dict[str, object] = {"state": state}
+    if state == "live":
+        updates["live_since"] = moment.isoformat()
+    elif state == "retired":
+        updates["retired_at"] = moment.isoformat()
+        updates["keep_until"] = (moment + RETIRED_SPACE_RETENTION).isoformat()
+    elif state == "dropped":
+        updates["dropped_at"] = moment.isoformat()
+    assignments = ", ".join(f"{column}=?" for column in updates)
+    marks = ",".join("?" for _ in expected)
+    changed = connection.execute(
+        f"UPDATE embedding_spaces SET {assignments} WHERE space_id=? AND state IN ({marks})",
+        (*updates.values(), space_id, *expected),
+    )
+    if changed.rowcount != 1:
+        raise EmbeddingSpaceError("embedding_space_state_changed")
+
+
+def next_v2_base(
+    connection: sqlite3.Connection,
+    identity: EmbeddingIdentity,
+    *,
+    stored_names: frozenset[str],
+) -> str:
+    """A base for a new space no registry row and no stored collection uses.
+
+    Switching back to a model whose retired space is still kept gets a fresh
+    `_g<n>` base, so stale retired vectors are never mixed with fresh ones.
+    """
+    used = {space.collection_base for space in spaces_in(connection)}
+    generation = 0
+    while True:
+        base = v2_collection_base(identity, generation)
+        names = space_collection_names(base, identity.dims).values()
+        if base not in used and not any(name in stored_names for name in names):
+            return base
+        generation += 1
+
+
+def probe_width_allowed(
+    connection: sqlite3.Connection,
+    profile_id: str,
+    width: int,
+    *,
+    data_dir: Path,
+) -> bool:
+    """Whether a probe may record `width` on a profile without moving the space.
+
+    A profile that fills the live space (the active one, or the one the space
+    was built with) may record its measured width only when it is the
+    space's: equal to the width already known, or -- for an "auto" space
+    whose width was never recorded -- equal to the width Chroma stored, or
+    any width when nothing is stored yet. That is a relabel; the names never
+    change. Any other width needs a switch (B2: it used to silently open a
+    new, empty collection). Every other profile records what it measured.
+    """
+    live = live_space_in(connection)
+    if live is None:
+        return True
+    active = connection.execute(
+        "SELECT profile_id FROM model_profiles WHERE is_active=1"
+    ).fetchone()
+    fills_live = live.profile_id == profile_id or (active is not None and active[0] == profile_id)
+    if not fills_live:
+        return True
+    if live.dims is not None:
+        return live.dims == width
+    from one_memory.sdk_vector_reattach import stored_collection_width
+
+    stored = stored_collection_width(data_dir, live.collection_names()["memory"])
+    if stored is not None and stored != width:
+        return False
+    record_width_in(connection, live.space_id, width)
+    return True

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

@@ -0,0 +1,169 @@
+"""HTTP surface of the embedding switch: spaces, plans, jobs, cleanup.
+
+The contract the App and the CLI build on is
+`memhub/docs/contracts/embedding-switch-v1.md`. Errors keep Core's shape,
+`{"detail": "<code>"}`; a refusal that computed a plan also carries it as
+`"plan"`, so a client can show the confirmation without asking again.
+"""
+
+from __future__ import annotations
+
+import asyncio
+from collections.abc import Sequence
+from typing import Any, cast
+
+from fastapi import APIRouter, Request, Response
+from fastapi.params import Depends
+from fastapi.responses import JSONResponse
+from pydantic import BaseModel, ConfigDict, Field
+
+from one_memory.embedding_backend import ReembedUnavailableError
+from one_memory.embedding_spaces import EmbeddingSpaceError
+from one_memory.embedding_switch import (
+    EmbeddingSwitchError,
+    EmbeddingSwitchPlan,
+    EmbeddingSwitchService,
+)
+
+#: HTTP status per refusal code; anything not listed is a 409.
+_STATUS = {
+    "model_profile_not_found": 404,
+    "embedding_switch_not_found": 404,
+    "embedding_space_not_found": 404,
+    "sdk_reembed_unavailable": 503,
+    "secure_storage_unavailable": 503,
+    "insufficient_disk_space": 507,
+}
+
+
+class EmbeddingSwitchPlanRequest(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+    profile_id: str = Field(min_length=1, max_length=128)
+    expected_revision: int | None = Field(default=None, ge=1)
+
+
+class EmbeddingSwitchStartRequest(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+    profile_id: str = Field(min_length=1, max_length=128)
+    expected_revision: int = Field(ge=1)
+    plan_token: str = Field(min_length=1, max_length=128)
+    requested_by: str = Field(default="app", pattern=r"^(app|cli)$")
+
+
+def refusal(code: str, *, plan: EmbeddingSwitchPlan | None = None) -> JSONResponse:
+    content: dict[str, Any] = {"detail": code}
+    if plan is not None:
+        content["plan"] = plan.model_dump(mode="json")
+    return JSONResponse(status_code=_STATUS.get(code, 409), content=content)
+
+
+def _service(request: Request) -> EmbeddingSwitchService:
+    return cast(EmbeddingSwitchService, request.app.state.embedding_switch)
+
+
+def embedding_switch_router(dependencies: Sequence[Depends]) -> APIRouter:
+    router = APIRouter(dependencies=dependencies)
+
+    @router.get("/api/v1/embedding-spaces")
+    async def list_embedding_spaces(request: Request) -> dict[str, object]:
+        """The registry and what the vector store holds, space by space."""
+        service = _service(request)
+        spaces = await asyncio.to_thread(service.spaces.list_spaces)
+        live = next((space for space in spaces if space.state == "live"), None)
+        scanned: list[dict[str, object]] | None = None
+        scan_error = service.backend.unavailable_reason()
+        if scan_error is None:
+            try:
+                found = await service.backend.scan()
+            except Exception as error:  # noqa: BLE001 - the registry still answers
+                scan_error = getattr(error, "code", None) or "embedding_space_scan_failed"
+            else:
+                known = {(space.collection_base, space.name_dims or 0): space for space in spaces}
+                scanned = [
+                    {
+                        "collection_base": item.collection_base,
+                        "name_dims": item.name_dims,
+                        "width": item.width,
+                        "vectors": item.vectors,
+                        "counts": dict(item.counts),
+                        "space_id": known[item.key].space_id if item.key in known else None,
+                        "state": known[item.key].state if item.key in known else "unregistered",
+                    }
+                    for item in found
+                ]
+        return {
+            "schema_version": 1,
+            "live_space_id": live.space_id if live is not None else None,
+            "spaces": [space.model_dump(mode="json") for space in spaces],
+            "scanned": scanned,
+            "scan_error": scan_error,
+        }
+
+    @router.delete("/api/v1/embedding-spaces/{space_id}", response_model=None)
+    async def delete_embedding_space(space_id: str, request: Request) -> Any:
+        """Clean up a retired space now instead of after its 14 days."""
+        try:
+            space = await _service(request).drop_space(space_id)
+        except (EmbeddingSwitchError, EmbeddingSpaceError, ReembedUnavailableError) as error:
+            return refusal(error.code)
+        except RuntimeError as error:
+            if "held open" in str(error):
+                return refusal("embedding_space_in_use")
+            raise
+        return {"schema_version": 1, "space": space.model_dump(mode="json")}
+
+    @router.post("/api/v1/embedding-switches/plan", response_model=None)
+    async def plan_embedding_switch(value: EmbeddingSwitchPlanRequest, request: Request) -> Any:
+        try:
+            plan = await _service(request).plan(
+                value.profile_id, expected_revision=value.expected_revision
+            )
+        except EmbeddingSwitchError as error:
+            return refusal(error.code, plan=error.plan)
+        return plan.model_dump(mode="json")
+
+    @router.post("/api/v1/embedding-switches", status_code=202, response_model=None)
+    async def start_embedding_switch(value: EmbeddingSwitchStartRequest, request: Request) -> Any:
+        # One lifecycle lock orders mode/evolve/backfill and embedding
+        # maintenance. Without it each endpoint could pass its own preflight
+        # and then begin concurrently.
+        async with request.app.state.memory_mode_lock:
+            evolve = request.app.state.evolve_service
+            backfill = request.app.state.memory_graph_backfill
+            if evolve.running() or backfill.running:
+                return refusal("memory_lifecycle_busy")
+            try:
+                job = await _service(request).start_switch(
+                    value.profile_id,
+                    expected_revision=value.expected_revision,
+                    plan_token=value.plan_token,
+                    requested_by=value.requested_by,
+                )
+            except EmbeddingSwitchError as error:
+                return refusal(error.code, plan=error.plan)
+        return job.model_dump(mode="json")
+
+    @router.get("/api/v1/embedding-switches/current")
+    async def current_embedding_switch(request: Request, response: Response) -> dict[str, object]:
+        """Polled by the loading screen, the banner and `memhub models switch status`."""
+        response.headers["Cache-Control"] = "no-store"
+        return await asyncio.to_thread(_service(request).current)
+
+    @router.get("/api/v1/embedding-switches/{job_id}", response_model=None)
+    async def get_embedding_switch(job_id: str, request: Request) -> Any:
+        job = await asyncio.to_thread(_service(request).get_job, job_id)
+        if job is None:
+            return refusal("embedding_switch_not_found")
+        return job.model_dump(mode="json")
+
+    @router.post("/api/v1/embedding-switches/{job_id}/cancel", response_model=None)
+    async def cancel_embedding_switch(job_id: str, request: Request) -> Any:
+        try:
+            job = await asyncio.to_thread(_service(request).cancel, job_id)
+        except EmbeddingSwitchError as error:
+            return refusal(error.code)
+        return job.model_dump(mode="json")
+
+    return router

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

@@ -94,11 +94,15 @@ def inspect_profile_graph_width(
     api_key: str | None,
     data_dir: Path,
     mode: str | None = None,
+    graph_dir: str = "graph",
 ) -> GraphWidthMismatch | None:
-    """Inspect the graph path and width selected by the active profile."""
+    """Inspect the graph path and width selected by the active profile.
+
+    `graph_dir` is the live embedding space's graph (`embedding_spaces`).
+    """
     del api_key
     return _inspect_graph_width(
-        _profile_graph_path(data_dir, mode),
+        _profile_graph_path(data_dir, mode, graph_dir),
         _profile_embedding_width(profile),
     )
 
@@ -110,11 +114,12 @@ def decide_profile_graph_width(
     data_dir: Path,
     decision: GraphWidthDecision,
     mode: str | None = None,
+    graph_dir: str = "graph",
 ) -> GraphWidthOutcome:
     """Apply the user's decision to the active profile's graph."""
     del api_key
     config = _GraphAdminConfig(
-        graph_store=_GraphStoreConfig(str(_profile_graph_path(data_dir, mode))),
+        graph_store=_GraphStoreConfig(str(_profile_graph_path(data_dir, mode, graph_dir))),
         embedder=_EmbeddingWidthConfig(_profile_embedding_width(profile)),
     )
     return apply_graph_width_decision(
@@ -204,6 +209,12 @@ _GRAPH_WIDTH_CACHE: dict[str, int | None] = {}
 _GRAPH_WIDTH_LOCK = threading.Lock()
 
 
+def forget_graph_widths() -> None:
+    """Drop every remembered width: an embedding switch moved the graph."""
+    with _GRAPH_WIDTH_LOCK:
+        _GRAPH_WIDTH_CACHE.clear()
+
+
 def _graph_embedding_width(db_path: Path) -> int | None:
     """Read the Memory embedding width directly from Kuzu's schema."""
     try:
@@ -252,9 +263,9 @@ def _inspect_graph_width(
     )
 
 
-def _profile_graph_path(data_dir: Path, mode: str | None = None) -> Path:
+def _profile_graph_path(data_dir: Path, mode: str | None = None, graph_dir: str = "graph") -> Path:
     ultra = mode == "ultra" if mode is not None else graph_store_enabled()
-    name = "graph" if ultra else "graph-disabled"
+    name = graph_dir if ultra else "graph-disabled"
     return data_dir / "hy-memory" / HY_MEMORY_NAMESPACE / name
 
 

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

@@ -14,7 +14,7 @@ from pathlib import Path
 from typing import Literal, cast
 
 HY_MEMORY_DISTRIBUTION = "hy-memory"
-HY_MEMORY_VERSION = "2.0.9"
+HY_MEMORY_VERSION = "2.0.14"
 HY_MEMORY_NAMESPACE = "governed-v2"
 DiagnosticLogLevel = Literal["error", "warning", "info", "debug"]
 

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

@@ -3,20 +3,26 @@
 Runtime product code must use public ``HyMemoryClient`` methods.  The startup
 migration boundary is the isolated exception: all writers are stopped, so it
 may copy, restore and repair SDK-owned local stores.
+
+The embedding switch is the second such boundary: model writes are paused
+while it re-embeds one space into another (`SdkReembedBackend`), so it may
+read and fill SDK collections through the SDK's re-embed module.
 """
 
 from __future__ import annotations
 
+import asyncio
 import json
 import sqlite3
 from collections.abc import Iterator
-from contextlib import closing
+from contextlib import closing, contextmanager
 from dataclasses import dataclass, field
 from datetime import UTC, datetime, timedelta
 from pathlib import Path
 from typing import Any
 
-from hy_memory import (  # type: ignore[import-untyped]
+import hy_memory  # type: ignore[import-untyped]
+from hy_memory import (
     DataPlaneRestore,
     DataPlaneSnapshot,
     restore_local_data_plane,
@@ -497,7 +503,7 @@ def _ensure_coding_schema(path: Path) -> None:
         CodingMemoryStore,
     )
 
-    # Relies on the pinned SDK's internals (hy-memory==2.0.9 is pinned exactly).
+    # Relies on the pinned SDK's internals (hy-memory==2.0.14 is pinned exactly).
     store = CodingMemoryStore.__new__(CodingMemoryStore)
     store._db_path = str(path)
     store._conn = None
@@ -511,3 +517,256 @@ def _ensure_coding_schema(path: Path) -> None:
 def _batches[T](values: list[T] | tuple[T, ...]) -> Iterator[tuple[T, ...]]:
     for start in range(0, len(values), _BATCH):
         yield tuple(values[start : start + _BATCH])
+
+
+# The SDK functions the embedding switch needs. They arrived in hy-memory
+# 2.0.10; an older SDK reports `sdk_reembed_unavailable` instead of failing.
+_REEMBED_API = (
+    "VectorSpace",
+    "scan_vector_spaces",
+    "diff_spaces",
+    "reembed_vector_space",
+    "verify_reembed",
+    "drop_vector_space",
+    "reembed_graph",
+    "verify_graph_reembed",
+    "drop_graph",
+    "ReembedCancelled",
+)
+
+
+class SdkReembedBackend:
+    """`ReembedBackend` over `hy_memory`'s re-embed module, for one home.
+
+    Runs beside live SDK clients: the vector functions open Chroma with the
+    SDK's own settings, so they share its client system. The graph functions
+    refuse a graph a live client holds open; the switch closes them first.
+    """
+
+    def __init__(self, data_dir: Path) -> None:
+        self.data_dir = data_dir
+        self.root = data_dir.resolve() / "hy-memory" / HY_MEMORY_NAMESPACE
+        self.persist_directory = self.root / "vector"
+        self._chroma_opened = False
+
+    def unavailable_reason(self) -> str | None:
+        missing = [name for name in _REEMBED_API if not hasattr(hy_memory, name)]
+        return "sdk_reembed_unavailable" if missing else None
+
+    def _sdk(self) -> Any:
+        from one_memory.embedding_backend import ReembedUnavailableError
+
+        reason = self.unavailable_reason()
+        if reason is not None:
+            raise ReembedUnavailableError(reason)
+        return hy_memory
+
+    def _open_chroma_once(self) -> None:
+        """Open Chroma once under the client-construction lock.
+
+        Every later open beside the Runtime finds that system. Two first
+        opens race over Chroma's unlocked cache, and a client under
+        construction lost its stores that way (see `hy_sdk_runtime`).
+        """
+        if self._chroma_opened or not self.persist_directory.is_dir():
+            return
+        import chromadb
+
+        from one_memory.hy_sdk_runtime import first_store_open
+
+        with first_store_open(self.data_dir):
+            chromadb.PersistentClient(path=str(self.persist_directory))
+        self._chroma_opened = True
+
+    def _vector_space(self, space: Any) -> Any:
+        return self._sdk().VectorSpace(
+            base_name=space.collection_base,
+            dims=space.dims,
+            persist_directory=str(self.persist_directory),
+            model=space.model,
+            collections=space.names(),
+        )
+
+    async def scan(self, *, per_user: bool = False) -> tuple[Any, ...]:
+        from one_memory.embedding_backend import ScannedSpace
+
+        if not self.persist_directory.is_dir():
+            return ()
+        await asyncio.to_thread(self._open_chroma_once)
+        found = await self._sdk().scan_vector_spaces(str(self.persist_directory), per_user=per_user)
+        return tuple(
+            ScannedSpace(
+                collection_base=str(item.base_name),
+                name_dims=item.dims,
+                width=item.width,
+                counts={role: int(entry.count) for role, entry in item.roles.items()},
+                collections={role: str(entry.name) for role, entry in item.roles.items()},
+                per_user=dict(item.per_user) if per_user else {},
+            )
+            for item in found
+        )
+
+    async def diff(self, source: Any, target: Any) -> dict[str, int]:
+        await asyncio.to_thread(self._open_chroma_once)
+        result = await self._sdk().diff_spaces(
+            self._vector_space(source), self._vector_space(target)
+        )
+        return {role: len(ids) for role, ids in result.missing.items()}
+
+    async def reembed(
+        self,
+        source: Any,
+        target: Any,
+        *,
+        embedding: Any,
+        cancel: Any,
+        on_step: Any,
+        batch_size: int = 64,
+    ) -> None:
+        from one_memory.embedding_backend import ReembedStep
+
+        await asyncio.to_thread(self._open_chroma_once)
+        sdk = self._sdk()
+
+        def progress(item: Any) -> None:
+            on_step(
+                ReembedStep(
+                    phase="vectors",
+                    role=str(item.role),
+                    done=int(item.done),
+                    total=int(item.total),
+                    embedded=int(item.embedded),
+                    reused=int(item.reused),
+                    kept=int(getattr(item, "kept", 0)),
+                )
+            )
+
+        with self._translated():
+            await sdk.reembed_vector_space(
+                self._vector_space(source),
+                self._vector_space(target),
+                embedding=self._embedding_service(embedding),
+                batch_size=batch_size,
+                cancel=cancel,
+                on_progress=progress,
+                # The target wins: an id it already holds is never touched, so
+                # a resumed run continues and a merge never overwrites live data.
+                skip_existing=True,
+            )
+
+    async def verify(self, source: Any, target: Any, *, embedding: Any) -> Any:
+        from one_memory.embedding_backend import VectorCheck
+
+        await asyncio.to_thread(self._open_chroma_once)
+        with self._translated():
+            result = await self._sdk().verify_reembed(
+                self._vector_space(source),
+                self._vector_space(target),
+                embedding=self._embedding_service(embedding),
+            )
+        return VectorCheck(
+            per_role={role: dict(values) for role, values in result.per_role.items()},
+            per_user=dict(result.per_user),
+            problems=tuple(result.problems),
+            warnings=tuple(result.warnings),
+            self_recall_hits=int(result.self_recall_hits),
+            self_recall_samples=int(result.self_recall_samples),
+        )
+
+    async def graph_vectors(self, path: Path) -> int | None:
+        if not path.exists():
+            return None
+        # Not re-exported at the package root; the module is the SDK's own.
+        plan = await self._sdk().reembed.plan_graph_reembed(path)
+        return int(plan.vectors)
+
+    async def reembed_graph(
+        self,
+        source: Path,
+        target: Path,
+        *,
+        embedding: Any,
+        target_dims: int,
+        cancel: Any,
+        on_step: Any,
+    ) -> None:
+        from one_memory.embedding_backend import ReembedStep
+
+        def progress(item: Any) -> None:
+            on_step(
+                ReembedStep(
+                    phase="graph",
+                    role=str(item.table),
+                    done=int(item.done),
+                    total=int(item.total),
+                    embedded=int(item.embedded),
+                )
+            )
+
+        with self._translated():
+            await self._sdk().reembed_graph(
+                source,
+                target,
+                embedding=self._embedding_service(embedding),
+                target_dims=target_dims,
+                cancel=cancel,
+                on_progress=progress,
+                # A resumed switch rebuilds the copy from the untouched source.
+                overwrite=True,
+            )
+
+    async def verify_graph(self, source: Path, target: Path, *, target_dims: int) -> Any:
+        from one_memory.embedding_backend import GraphCheck
+
+        result = await self._sdk().verify_graph_reembed(source, target, target_dims=target_dims)
+        return GraphCheck(ok=bool(result.ok), problems=tuple(result.problems))
+
+    async def drop(self, space: Any) -> None:
+        await asyncio.to_thread(self._open_chroma_once)
+        await self._sdk().drop_vector_space(self._vector_space(space))
+
+    async def drop_graph(self, path: Path) -> None:
+        await self._sdk().drop_graph(path)
+
+    def _embedding_service(self, embedding: Any) -> Any:
+        """The service that computes a target space's vectors.
+
+        The built-in model is MemHub's ONNX service, exactly what the Runtime
+        client embeds with. A remote model gets the SDK's own service, built
+        from the same configuration the Runtime client would use.
+        """
+        from one_memory.hy_sdk_runtime import (
+            LocalOnnxEmbeddingService,
+            build_sdk_config,
+            retrieval_view,
+        )
+        from one_memory.model_profiles import ProviderKind
+
+        profile = embedding.profile
+        provider = profile.embedding_provider_kind or profile.provider_kind
+        if provider is ProviderKind.LOCAL_ONNX:
+            return LocalOnnxEmbeddingService()
+        from hy_memory.core.embed_service import EmbedService  # type: ignore[import-untyped]
+
+        return EmbedService(
+            # The retrieval view: re-embedding never needs the generation model.
+            build_sdk_config(
+                retrieval_view(profile),
+                embedding.space,
+                api_key=embedding.api_key,
+                data_dir=self.data_dir,
+            )
+        )
+
+    @contextmanager
+    def _translated(self) -> Iterator[None]:
+        """SDK refusals as the Core errors the switch classifies."""
+        from one_memory.embedding_backend import EmbeddingWidthError, ReembedCancelledError
+
+        sdk = self._sdk()
+        try:
+            yield
+        except sdk.ReembedCancelled:
+            raise ReembedCancelledError("embedding_switch_cancelled") from None
+        except hy_memory.EmbeddingDimensionMismatchError as error:
+            raise EmbeddingWidthError("embedding_dimensions_mismatch") from error

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

@@ -11,10 +11,11 @@ import asyncio
 import hashlib
 import os
 import threading
-from collections.abc import Callable, Coroutine, Iterable, Mapping
+from collections.abc import Callable, Coroutine, Iterable, Iterator, Mapping
+from contextlib import contextmanager
 from dataclasses import dataclass
 from pathlib import Path
-from typing import Any, ClassVar
+from typing import Any, ClassVar, Literal, TypedDict, cast
 
 from hy_memory import (  # type: ignore[import-untyped]
     AmbiguousMemoryIdError as AmbiguousMemoryIdError,  # re-export for api.py
@@ -29,6 +30,13 @@ from one_memory.embedding_assets import (
     BUILTIN_EMBEDDING_DIMENSIONS,
     BUILTIN_EMBEDDING_MODEL,
 )
+from one_memory.embedding_spaces import (
+    DEFAULT_GRAPH_DIR,
+    EmbeddingSpace,
+    EmbeddingSpaceError,
+    derived_space,
+    embedding_identity,
+)
 from one_memory.hy_graph_admin import (
     GraphWidthMismatchError,
     effective_memory_mode,
@@ -39,8 +47,10 @@ from one_memory.local_embedding import LocalEmbedder
 from one_memory.log_file import confine_hy_sdk_logging
 from one_memory.memory_features import (
     FEATURES,
-    FEATURES_BY_NAME,
+    PARAMETERS,
+    SETTINGS_BY_NAME,
     FeatureOverrides,
+    SettingValue,
     feature_overrides,
 )
 from one_memory.model_profiles import (
@@ -54,6 +64,10 @@ BUILTIN_RETRIEVAL_PROFILE_ID = "builtin-retrieval"
 _LOCAL_ONNX_PLACEHOLDER_URL = "http://127.0.0.1/local-onnx"
 DEFAULT_RELEVANCE_FLOOR = 0.35
 
+#: The SDK's memory modes. A mode never changes a collection name: the space
+#: names the collections, the mode only which stores the client opens.
+MemoryMode = Literal["lite", "pro", "ultra"]
+
 
 @dataclass
 class _RuntimeEntry:
@@ -176,37 +190,77 @@ class SdkClientHandle:
         api_key: str | None,
         data_dir: Path,
         http_transport_factory: Callable[[], Any] | None = None,
+        space: EmbeddingSpace | None = None,
         mode: str | None = None,
         features: FeatureOverrides = (),
+        language: str | None = None,
     ) -> None:
         self._profile = profile
         self._api_key = api_key
         self._data_dir = data_dir
         self._http_transport_factory = http_transport_factory
+        self._space = space
         #: The SDK mode this handle's client is built with, fixed for its life.
         self.mode = mode or effective_memory_mode()
         #: The SDK features set on its config (`memory_features`), fixed likewise.
         self.features = features
+        #: The SDK prompt language (`ui_language`); None = SDK auto-detect.
+        self.language = language
         self._lease: ClientLease | None = None
+        self._constructing: asyncio.Future[ClientLease] | None = None
         self._lock = asyncio.Lock()
 
+    @property
+    def profile(self) -> ModelProfileSnapshot:
+        return self._profile
+
+    @property
+    def space(self) -> EmbeddingSpace | None:
+        return self._space
+
+    @property
+    def api_key(self) -> str | None:
+        return self._api_key
+
     async def client(self) -> HyMemoryClient:
         if self._lease is not None:
             return self._lease.client
         async with self._lock:
             if self._lease is None:
-                self._lease = await asyncio.to_thread(
-                    acquire_client,
-                    self._profile,
-                    api_key=self._api_key,
-                    data_dir=self._data_dir,
-                    http_transport_factory=self._http_transport_factory,
-                    mode=self.mode,
-                    features=self.features,
+                constructing = asyncio.ensure_future(
+                    asyncio.to_thread(
+                        _acquire_for_handle,
+                        self._profile,
+                        self._space,
+                        api_key=self._api_key,
+                        data_dir=self._data_dir,
+                        http_transport_factory=self._http_transport_factory,
+                        mode=self.mode,
+                        features=self.features,
+                        **language_kwargs(self.language),
+                    )
                 )
+                self._constructing = constructing
+                try:
+                    self._lease = await asyncio.shield(constructing)
+                except asyncio.CancelledError:
+                    # The construction thread runs on. Keep what it builds, so
+                    # `close` releases it instead of leaving its runtime open.
+                    constructing.add_done_callback(self._keep)
+                    raise
             return self._lease.client
 
+    def _keep(self, constructing: asyncio.Future[ClientLease]) -> None:
+        if constructing.cancelled() or constructing.exception() is not None:
+            return
+        if self._lease is None:
+            self._lease = constructing.result()
+
     async def close(self) -> None:
+        constructing = self._constructing
+        if constructing is not None and not constructing.done():
+            # A construction a cancelled caller left behind: wait for its lease.
+            await asyncio.gather(constructing, return_exceptions=True)
         async with self._lock:
             lease, self._lease = self._lease, None
         if lease is not None:
@@ -269,21 +323,27 @@ def sdk_relevance_floor() -> float:
     return min(1.0, max(0.0, value))
 
 
-def sdk_feature_defaults() -> dict[str, bool]:
-    """Each `memory_features` feature's SDK default, as a fresh config has it.
+def sdk_feature_defaults() -> dict[str, SettingValue]:
+    """Each `memory_features` setting's SDK default, as a fresh config has it.
 
     That is the SDK's code default unless the process environment sets the
     SDK's own variable (`FeatureSpec.env`), exactly what an unset feature
     leaves on a client.
     """
     config = MemoryConfig()
-    return {
+    defaults: dict[str, SettingValue] = {
         spec.name: bool(getattr(getattr(config, spec.section), spec.field)) for spec in FEATURES
     }
+    for parameter in PARAMETERS:
+        defaults[parameter.name] = float(
+            getattr(getattr(config, parameter.section), parameter.field)
+        )
+    return defaults
 
 
 def apply_sdk_features(
-    config: MemoryConfig, features: Mapping[str, bool] | Iterable[tuple[str, bool]]
+    config: MemoryConfig,
+    features: Mapping[str, SettingValue] | Iterable[tuple[str, SettingValue]],
 ) -> MemoryConfig:
     """Set each feature a person chose on its `MemoryConfig` field.
 
@@ -294,38 +354,72 @@ def apply_sdk_features(
     """
     values = dict(features.items() if isinstance(features, Mapping) else features)
     for name, value in feature_overrides(values):
-        spec = FEATURES_BY_NAME[name]
+        spec = SETTINGS_BY_NAME[name]
         setattr(getattr(config, spec.section), spec.field, value)
     return config
 
 
+class LanguageKwargs(TypedDict, total=False):
+    language: str
+
+
+def language_kwargs(language: str | None) -> LanguageKwargs:
+    """`language=` for a client constructor, only when there is one.
+
+    Without a language every call is the one it was before the setting
+    existed, so stand-ins written for that call keep working.
+    """
+    return {"language": language} if language is not None else {}
+
+
+def apply_sdk_language(config: MemoryConfig, language: str | None) -> MemoryConfig:
+    """Set the SDK prompt language (`MemoryConfig.language`), when there is one.
+
+    None (no language set) sets nothing: the SDK detects zh/en as it always
+    did. Every display language, zh-Hans included, is set explicitly. Like a feature, the language never touches `vector_store`, so
+    the collection identity never depends on it.
+    """
+    if language is not None:
+        config.language = language
+    return config
+
+
 def build_sdk_config(
     profile: ModelProfileSnapshot,
+    space: EmbeddingSpace | None = None,
+    mode: MemoryMode | None = None,
     *,
     api_key: str | None,
     data_dir: Path,
-    features: Mapping[str, bool] | Iterable[tuple[str, bool]] = (),
+    features: Mapping[str, SettingValue] | Iterable[tuple[str, SettingValue]] = (),
+    language: str | None = None,
 ) -> MemoryConfig:
-    """Map a model snapshot to SDK models, endpoints, backends, and local paths.
+    """Map a model snapshot and its embedding space to an SDK configuration.
 
-    `features` (`memory_features`) are set on top; with none the config is
-    exactly what it was before the setting existed.
+    `space` names the collections and the graph; the profile only says how to
+    reach the models. A profile whose embedding identity (model and width) is
+    not the space's raises `embedding_space_mismatch` instead of opening new,
+    empty collections. Without `space`, the space the profile opened before
+    the registry existed is used: offline tools on a home with no registry.
+    `mode` never changes a name, and neither do `features`
+    (`memory_features`), which are set on top; with none the config is
+    exactly what it was before the setting existed. So is `language`
+    (`apply_sdk_language`); None leaves the SDK's own zh/en detection.
     """
+    if mode is not None and mode not in {"lite", "pro", "ultra"}:
+        raise HySdkRuntimeError("hy_sdk_memory_mode_invalid")
     generation_endpoint, generation_key = _generation_access(profile, api_key)
     embedding_provider = profile.embedding_provider_kind or profile.provider_kind
     embedding_service_is_local = embedding_provider is ProviderKind.LOCAL_ONNX
-    embedding_model = profile.embedding_model or (
-        BUILTIN_EMBEDDING_MODEL if embedding_service_is_local else None
-    )
-    if not embedding_model:
-        raise HySdkRuntimeError("hy_sdk_embedding_model_required")
-    dimensions: int | None
+    try:
+        identity = embedding_identity(profile)
+    except EmbeddingSpaceError as error:
+        raise HySdkRuntimeError(error.code) from None
     if embedding_service_is_local:
         embedding_endpoint = None
         embedding_key = None
-        dimensions = profile.embedding_dimensions or BUILTIN_EMBEDDING_DIMENSIONS
     else:
-        # Never the generation endpoint: the collection name hashes this one.
+        # Never the generation endpoint: a remote embedding has its own.
         embedding_endpoint = _openai_endpoint(embedding_provider, profile.embedding_base_url)
         embedding_key = "ollama" if embedding_provider is ProviderKind.OLLAMA else api_key
         if embedding_provider is ProviderKind.OPENAI_COMPATIBLE and not embedding_key:
@@ -335,13 +429,18 @@ def build_sdk_config(
             ProviderKind.OLLAMA,
         }:
             raise HySdkRuntimeError("hy_sdk_embedding_provider_unsupported")
-        dimensions = profile.embedding_dimensions
+    if space is None:
+        space = derived_space(profile)
+    elif space.identity is None or not identity.matches(space.identity):
+        raise HySdkRuntimeError("embedding_space_mismatch")
+    # The width the space was opened with: its names carry it, and a remote
+    # request sends it as `dimensions`. An "auto" space sends none, as before.
+    dimensions = space.name_dims
+    embedding_model = identity.model
 
     root = data_dir.resolve() / "hy-memory" / "governed-v2"
     root.mkdir(parents=True, exist_ok=True)
-    collection = _collection_base(
-        embedding_provider, embedding_endpoint, embedding_model, dimensions
-    )
+    collection = space.collection_base
 
     llm: dict[str, Any] = {
         "provider": "openai",
@@ -379,7 +478,7 @@ def build_sdk_config(
             },
             "graph_store": {
                 "provider": "kuzu",
-                "db_path": str(root / "graph"),
+                "db_path": str(root / (space.graph_dir or DEFAULT_GRAPH_DIR)),
                 "url": None,
                 "username": None,
                 "password": None,
@@ -393,25 +492,54 @@ def build_sdk_config(
             "coding": {"db_path": str(root / "coding.sqlite3")},
         }
     )
-    return apply_sdk_features(config, features)
+    return apply_sdk_language(apply_sdk_features(config, features), language)
+
+
+def _acquire_for_handle(
+    profile: ModelProfileSnapshot,
+    space: EmbeddingSpace | None,
+    *,
+    api_key: str | None,
+    data_dir: Path,
+    http_transport_factory: Callable[[], Any] | None,
+    mode: str | None,
+    features: FeatureOverrides = (),
+    language: str | None = None,
+) -> ClientLease:
+    # `acquire_client` is looked up at call time, so a stand-in replaces every
+    # construction. A handle without a space keeps the call it always made.
+    named: dict[str, Any] = {"space": space} if space is not None else {}
+    return acquire_client(
+        profile,
+        api_key=api_key,
+        data_dir=data_dir,
+        http_transport_factory=http_transport_factory,
+        mode=mode,
+        features=features,
+        **named,
+        **language_kwargs(language),
+    )
 
 
 def acquire_client(
     profile: ModelProfileSnapshot,
+    space: EmbeddingSpace | None = None,
     *,
     api_key: str | None,
     data_dir: Path,
     http_transport_factory: Callable[[], Any] | None = None,
     mode: str | None = None,
     features: FeatureOverrides = (),
+    language: str | None = None,
 ) -> ClientLease:
     """Construct a public SDK client and return its explicit runtime lease.
 
-    `mode` is the SDK pipeline mode (lite / pro / ultra); None keeps the
-    pre-setting default (ultra when `ONE_MEMORY_GRAPH_STORE` is set, else pro).
-    `features` are the `memory_features` set on its config; none keeps every
-    SDK default.
-    Waits while `hold_stores_offline` holds this home's stores.
+    `space` names the collections (`build_sdk_config`). `mode` is the SDK
+    pipeline mode (lite / pro / ultra) and never changes a name; None keeps
+    the pre-setting default (ultra when `ONE_MEMORY_GRAPH_STORE` is set, else
+    pro). `features` are the `memory_features` set on its config; none keeps
+    every SDK default. `language` is the SDK prompt language; None
+    auto-detects. Waits while `hold_stores_offline` holds this home's stores.
     """
     key = data_dir.resolve()
     with _STORE_GATE:
@@ -419,6 +547,7 @@ def acquire_client(
             _STORE_GATE.wait()
         _OPENING[key] = _OPENING.get(key, 0) + 1
     try:
+        named: dict[str, Any] = {"space": space} if space is not None else {}
         return _acquire_client(
             profile,
             api_key=api_key,
@@ -426,6 +555,8 @@ def acquire_client(
             http_transport_factory=http_transport_factory,
             mode=mode or effective_memory_mode(),
             features=features,
+            **named,
+            **language_kwargs(language),
         )
     finally:
         with _STORE_GATE:
@@ -435,6 +566,20 @@ def acquire_client(
             _STORE_GATE.notify_all()
 
 
+@contextmanager
+def first_store_open(data_dir: Path) -> Iterator[None]:
+    """One opening of this home's stores at a time: Chroma's first open is unlocked.
+
+    The same lock client construction takes, for anything else that opens
+    Chroma beside the Runtime (the re-embed functions).
+    """
+    key = data_dir.resolve()
+    with _STORE_GATE:
+        constructing = _CONSTRUCTING.setdefault(key, threading.Lock())
+    with constructing:
+        yield
+
+
 def hold_stores_offline(data_dir: Path) -> bool:
     """Hold this home's SDK stores for offline maintenance; False if a client is open.
 
@@ -460,14 +605,24 @@ def release_stores(data_dir: Path) -> None:
 
 def _acquire_client(
     profile: ModelProfileSnapshot,
+    space: EmbeddingSpace | None = None,
     *,
     api_key: str | None,
     data_dir: Path,
     http_transport_factory: Callable[[], Any] | None,
     mode: str = "pro",
     features: FeatureOverrides = (),
+    language: str | None = None,
 ) -> ClientLease:
-    config = build_sdk_config(profile, api_key=api_key, data_dir=data_dir, features=features)
+    config = build_sdk_config(
+        profile,
+        space,
+        cast(MemoryMode, mode),
+        api_key=api_key,
+        data_dir=data_dir,
+        features=features,
+        language=language,
+    )
     config.http_transport_factory = http_transport_factory
     mismatch = inspect_graph_width_mismatch(config)
     if mismatch is not None:
@@ -523,6 +678,33 @@ def _generation_access(
     return endpoint, api_key
 
 
+def embedding_endpoint(profile: ModelProfileSnapshot) -> str | None:
+    """The OpenAI-compatible base URL the SDK embeds through; None when local."""
+    provider = profile.embedding_provider_kind or profile.provider_kind
+    if provider is ProviderKind.LOCAL_ONNX:
+        return None
+    return _openai_endpoint(provider, profile.embedding_base_url)
+
+
+def legacy_collection_base(profile: ModelProfileSnapshot) -> str:
+    """The four-attribute name a profile's space had before the registry.
+
+    Existing homes are registered under exactly this name, so it must never
+    change: provider, embedding endpoint, model and declared width.
+    """
+    provider = profile.embedding_provider_kind or profile.provider_kind
+    local = provider is ProviderKind.LOCAL_ONNX
+    model = profile.embedding_model or (BUILTIN_EMBEDDING_MODEL if local else None)
+    if not model:
+        raise HySdkRuntimeError("hy_sdk_embedding_model_required")
+    if local:
+        return _collection_base(
+            provider, None, model, profile.embedding_dimensions or BUILTIN_EMBEDDING_DIMENSIONS
+        )
+    endpoint = _openai_endpoint(provider, profile.embedding_base_url)
+    return _collection_base(provider, endpoint, model, profile.embedding_dimensions)
+
+
 def _collection_base(
     provider: ProviderKind,
     endpoint: str | None,

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

@@ -75,6 +75,9 @@ class HySdkMemoryRecord(BaseModel):
     # Epoch seconds. `updated_at` falls back to `created_at`.
     created_at: int | None = None
     updated_at: int | None = None
+    # Actual scene=all ordering timestamp before the public fallback above.
+    # Internal-only: callers keep the existing SdkMemoryRecord wire shape.
+    sort_updated_at: int | None = Field(default=None, exclude=True, repr=False)
 
     @classmethod
     def from_sdk(cls, raw: object) -> HySdkMemoryRecord:
@@ -95,6 +98,10 @@ class HySdkMemoryRecord(BaseModel):
             if created_at is None:
                 created_at = gmt_created
             updated_at = _epoch(raw.get("updated_at"))
+            modified_at = _epoch(raw.get("gmt_modified"))
+            sort_updated_at = (
+                modified_at if modified_at is not None else updated_at
+            )
             return cls(
                 memory_id=str(raw["memory_id"]),
                 content=str(raw["content"]),
@@ -116,6 +123,7 @@ class HySdkMemoryRecord(BaseModel):
                 gmt_created=gmt_created,
                 created_at=created_at,
                 updated_at=updated_at if updated_at is not None else created_at,
+                sort_updated_at=sort_updated_at,
             )
         except (KeyError, TypeError, ValueError) as error:
             raise HySdkReadError("hy_memory_record_shape_unknown") from error
@@ -180,6 +188,7 @@ class HySdkMemoryRecord(BaseModel):
                 solution=solution,
                 created_at=created_at,
                 updated_at=updated_at if updated_at is not None else created_at,
+                sort_updated_at=updated_at,
             )
         except (KeyError, TypeError, ValueError) as error:
             raise HySdkReadError("hy_memory_record_shape_unknown") from error

memhub/apps/core/src/one_memory/imports/access.py

@@ -436,6 +436,11 @@ def root_identity_matches(root: Path, expected: str) -> bool:
     return _root_identity_matches_details(resolved, details, expected)
 
 
+def resolved_source_root(root: Path) -> Path:
+    """The real directory a root names (symlinks followed), as a grant records it."""
+    return _root_details(root)[0]
+
+
 def _check_root_identity(root: Path, expected: str | None) -> None:
     if expected is not None and not root_identity_matches(root, expected):
         raise SourceAccessError(SourceAccessErrorCode.SOURCE_IDENTITY_CHANGED)

memhub/apps/core/src/one_memory/imports/discovery.py

@@ -27,7 +27,7 @@ def discovered_off_loop(
     *,
     suffixes: frozenset[str],
     max_targets: int,
-    excluded_top_directories: frozenset[str] = frozenset(),
+    excluded_directory_names: frozenset[str] = frozenset(),
 ) -> AsyncIterator[SourceFileDiscoveryEvent]:
     """The same walk, for callers that have an event loop to keep free.
 
@@ -42,7 +42,7 @@ def discovered_off_loop(
             grant,
             suffixes=suffixes,
             max_targets=max_targets,
-            excluded_top_directories=excluded_top_directories,
+            excluded_directory_names=excluded_directory_names,
         ),
         scope_key=grant.source_id,
     )
@@ -53,15 +53,17 @@ def discover_source_files(
     *,
     suffixes: frozenset[str],
     max_targets: int,
-    excluded_top_directories: frozenset[str] = frozenset(),
+    excluded_directory_names: frozenset[str] = frozenset(),
 ) -> Iterator[SourceFileDiscoveryEvent]:
     """Metadata only: one lstat per candidate, no open and no per-file grant lookup.
 
     The grant and root identity are checked once before the walk. Each listed
     file keeps the grant's check, which runs again when that file is opened;
     the open itself refuses symlinks and any inode other than the one listed.
-    `excluded_top_directories` are directories directly under the root that
-    are never entered, such as another user's Hermes profiles.
+    `excluded_directory_names` are directory names never entered, at any
+    depth under the root, such as the `profiles` container that holds other
+    users' Hermes profiles. Any depth, because the granted root may sit above
+    the Hermes home (`~/.hermes` inside it is then `.hermes/profiles`).
     """
     grant.check_root()
     inspected = 0
@@ -69,12 +71,10 @@ def discover_source_files(
         grant.root,
         followlinks=False,
     ):
-        at_root = Path(directory) == grant.root
         child_directories[:] = sorted(
             child
             for child in child_directories
-            if not (Path(directory) / child).is_symlink()
-            and not (at_root and child in excluded_top_directories)
+            if not (Path(directory) / child).is_symlink() and child not in excluded_directory_names
         )
         for filename in sorted(filenames):
             if Path(filename).suffix.lower() not in suffixes:

memhub/apps/core/src/one_memory/imports/jobs.py

@@ -1,6 +1,7 @@
 import logging
 import re
 import sqlite3
+from collections.abc import Iterable
 from contextlib import AbstractContextManager, nullcontext
 from datetime import UTC, datetime
 from enum import StrEnum
@@ -18,13 +19,27 @@ from one_memory.imports.adapters import ScanPhase, SourceCursor
 #: the drift would only surface on a fresh database.
 #:
 #: This runs on SQLite today, so the SQLite rendering is used.
-from one_memory.memory_server.migrations import import_jobs_ddl
+from one_memory.memory_server.migrations import (
+    import_job_lookup_indexes_ddl,
+    import_jobs_ddl,
+)
 
 logger = logging.getLogger("one_memory.imports.jobs")
 
 JOB_SCHEMA = import_jobs_ddl("sqlite")
+#: Migration 63, applied by the store as well so a running home gets it.
+JOB_LOOKUP_INDEXES = import_job_lookup_indexes_ddl("sqlite")
 MAX_LIVE_BACKLOG_BYTES = 256 * 1024
 
+#: Finished live syncs kept per (user, source). Live sync opens a job for every
+#: change it imports, and nothing removed them: hundreds a day on an active
+#: machine. The App shows the latest job per source and the active ones; twenty is
+#: that plus enough recent history to read a failure back.
+SYNC_JOBS_KEPT_PER_SOURCE = 20
+#: Rows one pruning transaction may delete, so it holds the single writer for
+#: a few milliseconds at most however large the table grew.
+PRUNE_BATCH_ROWS = 200
+
 
 class ImportStatus(StrEnum):
     PENDING = "pending"
@@ -36,6 +51,12 @@ class ImportStatus(StrEnum):
     CANCELLED = "cancelled"
 
 
+#: States no job ever leaves (`ImportJobStore._TRANSITIONS`). Failed and
+#: interrupted are not among them: both can be resumed, and both still hold the
+#: source's one active slot.
+FINISHED_STATUSES = (ImportStatus.COMPLETED, ImportStatus.CANCELLED)
+
+
 class ImportJob(BaseModel):
     model_config = ConfigDict(frozen=True, extra="forbid")
 
@@ -272,6 +293,9 @@ class ImportJobStore:
                 WHERE status IN ('pending', 'running', 'paused', 'interrupted', 'failed')
                 """
             )
+        for statement in JOB_LOOKUP_INDEXES.split(";"):
+            if statement.strip():
+                connection.execute(statement)
 
     def create(
         self,
@@ -334,8 +358,8 @@ class ImportJobStore:
         read again.
         """
         opened: list[ImportJob] = []
-        for job in self.list_jobs(status=ImportStatus.FAILED):
-            if job.operation != "history" or job.stored != 0:
+        for job in self.find_jobs(operation="history", statuses=(ImportStatus.FAILED,)):
+            if job.stored != 0:
                 continue
             reasons = {issue.reason for issue in self.list_issues(job.job_id)}
             if not reasons or not reasons <= self._UNPUBLISHED_SNAPSHOT_FAILURES:
@@ -799,16 +823,172 @@ class ImportJobStore:
         return self.require(job_id)
 
     def list_jobs(self, *, status: ImportStatus | None = None) -> list[ImportJob]:
+        """Every job, oldest first. Hot paths ask `find_jobs` a narrower question."""
+        return self.find_jobs(statuses=(status,) if status is not None else None)
+
+    def find_jobs(
+        self,
+        *,
+        user_id: str | None = None,
+        source_id: str | None = None,
+        operation: Literal["history", "sync"] | None = None,
+        statuses: Iterable[ImportStatus] | None = None,
+        newest_first: bool = False,
+        limit: int | None = None,
+    ) -> list[ImportJob]:
+        """The jobs matching every given filter, oldest first unless asked otherwise.
+
+        The filters are SQL, served by `import_jobs_lane` / `import_jobs_status`
+        (migration 63). Reading the whole table and filtering here was what
+        three bulk threads and three request threads were all inside, for tens
+        of seconds, while the loop waited on them.
+        """
+        clauses: list[str] = []
+        parameters: list[str | int] = []
+        if user_id is not None:
+            clauses.append("user_id = ?")
+            parameters.append(user_id)
+        if source_id is not None:
+            clauses.append("source_id = ?")
+            parameters.append(source_id)
+        if operation is not None:
+            clauses.append("operation = ?")
+            parameters.append(operation)
+        if statuses is not None:
+            wanted = tuple(dict.fromkeys(ImportStatus(status) for status in statuses))
+            if not wanted:
+                return []
+            clauses.append(f"status IN ({', '.join('?' for _ in wanted)})")
+            parameters.extend(wanted)
         query = "SELECT * FROM import_jobs"
-        parameters: tuple[str, ...] = ()
-        if status is not None:
-            query += " WHERE status = ?"
-            parameters = (status,)
-        query += " ORDER BY created_at, job_id"
+        if clauses:
+            query += " WHERE " + " AND ".join(clauses)
+        query += (
+            " ORDER BY created_at DESC, job_id DESC"
+            if newest_first
+            else " ORDER BY created_at, job_id"
+        )
+        if limit is not None:
+            if limit < 1:
+                raise ValueError("limit must be positive")
+            query += " LIMIT ?"
+            parameters.append(limit)
         with self._connect() as connection:
             rows = connection.execute(query, parameters).fetchall()
         return [self._to_job(row) for row in rows]
 
+    def latest_job(
+        self,
+        *,
+        user_id: str,
+        source_id: str,
+        operation: Literal["history", "sync"] | None = None,
+        statuses: Iterable[ImportStatus] | None = None,
+    ) -> ImportJob | None:
+        jobs = self.find_jobs(
+            user_id=user_id,
+            source_id=source_id,
+            operation=operation,
+            statuses=statuses,
+            newest_first=True,
+            limit=1,
+        )
+        return jobs[0] if jobs else None
+
+    def prune_finished_sync_jobs(
+        self,
+        *,
+        keep: int = SYNC_JOBS_KEPT_PER_SOURCE,
+        max_rows: int = PRUNE_BATCH_ROWS,
+    ) -> int:
+        """Delete finished live-sync jobs beyond the newest `keep` of each source.
+
+        One bounded transaction: at most `max_rows` jobs, with their issues and
+        skip counts. Returns how many jobs went; fewer than `max_rows` means
+        nothing is left to prune, so calling again until then finishes the job.
+
+        Only `sync` jobs in a state nothing leaves (completed, cancelled) are
+        ever deleted. Failed and interrupted jobs hold the source's active slot
+        and can be resumed; history jobs are named by connection receipts, by
+        the onboarding gate and by the first-import review, and there are a
+        handful per source, so they are all kept. Cursors live in their own
+        tables keyed by file, not by job, so a pruned job takes no position
+        with it. The newest job of every source is always among those kept,
+        which is the one the App and live sync health name.
+        """
+        if keep < 1:
+            raise ValueError("keep must be positive")
+        if max_rows < 1:
+            raise ValueError("max_rows must be positive")
+        finished = tuple(FINISHED_STATUSES)
+        placeholders = ", ".join("?" for _ in finished)
+        deleted = 0
+        with self._connect(writing=True) as connection:
+            lanes = connection.execute(
+                f"""
+                SELECT user_id, source_id, COUNT(*) AS finished
+                FROM import_jobs
+                WHERE operation = 'sync' AND status IN ({placeholders})
+                GROUP BY user_id, source_id
+                HAVING COUNT(*) > ?
+                """,
+                (*finished, keep),
+            ).fetchall()
+            for lane in lanes:
+                if deleted >= max_rows:
+                    break
+                # The oldest job still kept: everything strictly older goes.
+                boundary = connection.execute(
+                    f"""
+                    SELECT created_at, job_id FROM import_jobs
+                    WHERE user_id = ? AND source_id = ? AND operation = 'sync'
+                      AND status IN ({placeholders})
+                    ORDER BY created_at DESC, job_id DESC
+                    LIMIT 1 OFFSET ?
+                    """,
+                    (lane["user_id"], lane["source_id"], *finished, keep - 1),
+                ).fetchone()
+                if boundary is None:
+                    continue
+                victims = [
+                    str(row["job_id"])
+                    for row in connection.execute(
+                        f"""
+                        SELECT job_id FROM import_jobs
+                        WHERE user_id = ? AND source_id = ? AND operation = 'sync'
+                          AND status IN ({placeholders})
+                          AND (created_at < ? OR (created_at = ? AND job_id < ?))
+                        ORDER BY created_at, job_id
+                        LIMIT ?
+                        """,
+                        (
+                            lane["user_id"],
+                            lane["source_id"],
+                            *finished,
+                            boundary["created_at"],
+                            boundary["created_at"],
+                            boundary["job_id"],
+                            max_rows - deleted,
+                        ),
+                    )
+                ]
+                if not victims:
+                    continue
+                marks = ", ".join("?" for _ in victims)
+                # Foreign keys cascade these too; deleting them by name keeps
+                # the outcome the same on a connection that has them off.
+                connection.execute(f"DELETE FROM import_issues WHERE job_id IN ({marks})", victims)
+                connection.execute(
+                    f"DELETE FROM import_skip_reason_counts WHERE job_id IN ({marks})", victims
+                )
+                removed = connection.execute(
+                    f"DELETE FROM import_jobs WHERE job_id IN ({marks}) "
+                    f"AND operation = 'sync' AND status IN ({placeholders})",
+                    (*victims, *finished),
+                )
+                deleted += removed.rowcount
+        return deleted
+
     def get_source_cursors(
         self,
         *,

memhub/apps/core/src/one_memory/imports/live_sync.py

@@ -28,7 +28,7 @@ from one_memory.imports.adapters import (
 )
 from one_memory.imports.jobs import ImportJob, ImportJobStore, ImportStatus
 from one_memory.imports.supervisor import ImportSupervisor
-from one_memory.user_scope import DEFAULT_USER_ID, lane_key, split_lane
+from one_memory.user_scope import DEFAULT_USER_ID, split_lane
 
 #: How long an automatic retry will wait for a wedged worker to notice cancel.
 ABANDON_TIMEOUT_SECONDS = 5.0
@@ -249,13 +249,15 @@ class PollingLiveSyncSupervisor:
                     ),
                 )
                 return None
-            source_jobs = await in_the_background(self.job_store.list_jobs)
+            # This lane's unfinished jobs only: the newest unfinished sync, and
+            # whatever history shares its cursor. Asked in SQL; listing every
+            # job ever run and filtering here was the poll's biggest read.
+            source_jobs = await in_the_background(self._lane_jobs, source_id)
             active_sync = next(
                 (
                     job
                     for job in reversed(source_jobs)
-                    if lane_key(job.user_id, job.source_id) == source_id
-                    and job.operation == "sync"
+                    if job.operation == "sync"
                     and job.status
                     in {
                         ImportStatus.PENDING,
@@ -275,7 +277,9 @@ class PollingLiveSyncSupervisor:
                     active_sync.job_id
                 ):
                     attempted_at = datetime.now(UTC)
-                    self.import_supervisor.enqueue(active_sync.job_id)
+                    await self.import_supervisor.enqueue_off_loop(
+                        active_sync.job_id, job=active_sync
+                    )
                     if not wait_for_completion:
                         self._observe_sync(source_id, attempted_at, active_sync.job_id)
                         return active_sync
@@ -295,22 +299,20 @@ class PollingLiveSyncSupervisor:
                 # by a process restart between yield and claim.  Enqueue is
                 # the operation that actually creates the task.
                 attempted_at = datetime.now(UTC)
-                self.import_supervisor.resume(active_sync.job_id)
-                self.import_supervisor.enqueue(active_sync.job_id)
+                resumed = await self.import_supervisor.resume_off_loop(active_sync.job_id)
+                await self.import_supervisor.enqueue_off_loop(active_sync.job_id, job=resumed)
                 completed = await self.import_supervisor.wait(active_sync.job_id)
                 self._record_outcome(source_id, attempted_at, completed)
                 return completed
             competing = [
                 job
                 for job in source_jobs
-                if lane_key(job.user_id, job.source_id) == source_id
-                and job.operation != "sync"
+                if job.operation != "sync"
                 and job.status
                 in {ImportStatus.PENDING, ImportStatus.RUNNING, ImportStatus.INTERRUPTED}
             ]
             bounded_history_incomplete = any(
-                lane_key(job.user_id, job.source_id) == source_id
-                and job.operation == "history"
+                job.operation == "history"
                 and job.history_after is not None
                 and job.status is not ImportStatus.COMPLETED
                 for job in source_jobs
@@ -354,6 +356,38 @@ class PollingLiveSyncSupervisor:
             # automatically after the realtime slice completes.
             return await self._run_sync(source_id, wait_for_completion=wait_for_completion)
 
+    def _lane_jobs(self, source_id: str) -> list[ImportJob]:
+        """The lane's jobs `_sync` decides on, oldest first.
+
+        Everything not completed, of either operation: an unfinished sync to
+        pick up, a history that competes for the cursor, and a bounded history
+        that has not completed yet (which includes a cancelled one). Finished
+        syncs, the rows that grow without end, are never read.
+        """
+        user_id, bare_source_id = split_lane(source_id)
+        unfinished = tuple(
+            status for status in ImportStatus if status is not ImportStatus.COMPLETED
+        )
+        return [
+            *self.job_store.find_jobs(
+                user_id=user_id,
+                source_id=bare_source_id,
+                operation="history",
+                statuses=unfinished,
+            ),
+            *self.job_store.find_jobs(
+                user_id=user_id,
+                source_id=bare_source_id,
+                operation="sync",
+                statuses=(
+                    ImportStatus.PENDING,
+                    ImportStatus.RUNNING,
+                    ImportStatus.PAUSED,
+                    ImportStatus.INTERRUPTED,
+                ),
+            ),
+        ]
+
     async def _has_work(self, source_id: str) -> bool:
         """Ask the source whether a scan would write anything, before taking a job out.
 
@@ -452,7 +486,7 @@ class PollingLiveSyncSupervisor:
             ),
         )
         self._active_jobs[source_id] = job.job_id
-        self.import_supervisor.enqueue(job.job_id)
+        await self.import_supervisor.enqueue_off_loop(job.job_id, job=job)
         if not wait_for_completion:
             self._observe_sync(source_id, attempted_at, job.job_id)
             return job

memhub/apps/core/src/one_memory/imports/live_watch.py

@@ -23,6 +23,7 @@ from pathlib import Path
 
 from watchfiles import awatch
 
+from one_memory.background_work import in_the_background
 from one_memory.diagnostic_log import diagnostic_event
 from one_memory.imports.jobs import ImportStatus
 from one_memory.imports.live_sync import PollingLiveSyncSupervisor
@@ -90,7 +91,8 @@ class FileWatchLiveSync:
                 # turn that caused setup. The watcher cannot observe a change
                 # from before it existed, so immediately run the same bounded
                 # trigger once instead of waiting for the 60-second backstop.
-                self._queue_changes(set(self.roots.values()))
+                # The roots are this watcher's own sources: nothing to resolve.
+                self._queue_sources(tuple(self.roots), count=len(self.roots))
 
     async def shutdown(self) -> None:
         task = self._task
@@ -139,28 +141,54 @@ class FileWatchLiveSync:
         observed_at: datetime | None = None,
     ) -> tuple[str, ...]:
         """Queue affected sources and wait for their coalesced work to settle."""
-        workers = self._queue_changes(changed, observed_at=observed_at)
+        workers = await self._queue_changes(changed, observed_at=observed_at)
         await asyncio.gather(*(asyncio.shield(worker) for worker in workers.values()))
         return tuple(workers)
 
-    def _queue_changes(
+    def sources_for(self, changed: set[Path]) -> tuple[str, ...]:
+        """The sources owning `changed`, in path order. Resolves every path."""
+        return tuple(
+            dict.fromkeys(
+                source
+                for source in (self.source_for(path) for path in sorted(changed))
+                if source is not None
+            )
+        )
+
+    async def _queue_changes(
         self, changed: set[Path], *, observed_at: datetime | None = None
+    ) -> dict[str, asyncio.Task[None]]:
+        """Attribute a batch of changed paths to sources and queue them.
+
+        Attributing resolves each path, a `stat` per component, and a busy
+        host reports hundreds of paths at once. On the loop that was the main
+        thread inside `source_for` while nothing else was answered, so the
+        resolving happens off it and only the queueing here.
+        """
+        if self._stop.is_set():
+            return {}
+        observed = observed_at or datetime.now(UTC)
+        sources = await in_the_background(self.sources_for, changed)
+        return self._queue_sources(sources, count=len(changed), observed_at=observed)
+
+    def _queue_sources(
+        self,
+        sources: tuple[str, ...],
+        *,
+        count: int,
+        observed_at: datetime | None = None,
     ) -> dict[str, asyncio.Task[None]]:
         if self._stop.is_set():
             return {}
         observed = observed_at or datetime.now(UTC)
         workers: dict[str, asyncio.Task[None]] = {}
-        for source_id in dict.fromkeys(
-            source
-            for source in (self.source_for(path) for path in sorted(changed))
-            if source is not None
-        ):
+        for source_id in sources:
             diagnostic_event(
                 level="debug",
                 component="import.live_watch",
                 event="live_sync.hook_received",
                 outcome="queued",
-                details={"source_id": source_id, "count": len(changed)},
+                details={"source_id": source_id, "count": count},
             )
             self._pending[source_id] = max(self._pending.get(source_id, observed), observed)
             worker = self._workers.get(source_id)
@@ -239,7 +267,7 @@ class FileWatchLiveSync:
                 stop_event=self._stop,
                 ignore_permission_denied=True,
             ):
-                self._queue_changes({Path(path) for _change, path in changes})
+                await self._queue_changes({Path(path) for _change, path in changes})
         except asyncio.CancelledError:
             raise
         except Exception:

memhub/apps/core/src/one_memory/imports/sources/common.py

@@ -209,6 +209,7 @@ class JsonlSourceAdapter:
         file_predicate: Callable[[AuthorizedSourceFile], bool] | None = None,
         suffixes: frozenset[str] = frozenset({".jsonl"}),
         header_selector: Callable[[dict[str, JsonValue]], bool] | None = None,
+        header_gate: Callable[[dict[str, JsonValue] | None], bool] | None = None,
     ) -> None:
         if descriptor.source_id != grant.source_id:
             raise ValueError("Descriptor and authorized root source IDs must match")
@@ -219,6 +220,10 @@ class JsonlSourceAdapter:
         self.file_predicate = file_predicate or (lambda _: True)
         self.suffixes = suffixes
         self.header_selector = header_selector
+        # False refuses the whole file before any record is read. It reports
+        # and leaves no cursor, so a release that learns the format reads the
+        # file from the top instead of finding it already behind a checkpoint.
+        self.header_gate = header_gate
         self._header_cache: dict[str, tuple[str, dict[str, JsonValue] | None]] = {}
         self._history_listing_cache: SourceListing | None = None
 
@@ -371,6 +376,9 @@ class JsonlSourceAdapter:
                 source_file, checkpoint, header = await asyncio.to_thread(
                     self._prepare, listed, options
                 )
+                if self.header_gate is not None and not self.header_gate(header):
+                    yield ScanFailure(reason_code=ScanIssueCode.UNSUPPORTED_SCHEMA)
+                    continue
                 _log.debug(
                     "import_file_read source=%s file=%d/%d file_bytes=%d planned_bytes=%d",
                     self.descriptor.source_id,
@@ -574,6 +582,9 @@ class JsonlSourceAdapter:
             # resumed scan starts past the header, and the records after it need
             # it just as much as the first batch did.
             header = await _read_header(reader, source_file, self.header_selector)
+            if self.header_gate is not None and not self.header_gate(header):
+                yield ScanFailure(reason_code=ScanIssueCode.UNSUPPORTED_SCHEMA)
+                continue
             last: SourceCursor = _start_cursor(source_file, options, checkpoint)
             async for raw in iterate_in_worker(
                 partial(reader, source_file, checkpoint=checkpoint),

memhub/apps/core/src/one_memory/imports/sources/deepseek_harness.py

@@ -1,3 +1,4 @@
+import re
 from pathlib import PurePosixPath
 
 from pydantic import JsonValue
@@ -37,6 +38,19 @@ DEEPSEEK_HARNESS_DESCRIPTOR = SourceDescriptor(
     ),
 )
 
+#: One session is one file, and the name carries the format generation it was
+#: written in: `session.jsonl[.zstd]` for the first format, then
+#: `session.v3.jsonl.zstd` and `session.v4.jsonl.zstd`. The version segment is
+#: part of the published on-disk contract, so discovery must accept it — the
+#: earlier exact-name match imported none of the versioned files.
+SESSION_FILE = re.compile(r"^session(?:\.v[0-9]+)?\.jsonl(?:\.zstd)?$")
+
+#: Session generations this parser has been verified against: the first format
+#: (header `version: 0`), v3 and v4. Discovery is intentionally wider than
+#: parsing: a future generation is found by pattern and then skipped from its
+#: header, so it is reported as unsupported instead of silently vanishing.
+SUPPORTED_SESSION_VERSIONS = frozenset({0, 3, 4})
+
 
 def create_deepseek_harness_adapter(
     grant: AuthorizedSourceRoot,
@@ -49,25 +63,43 @@ def create_deepseek_harness_adapter(
         grant=grant,
         parser=parse_deepseek_harness_record,
         source_version=source_version,
-        file_predicate=lambda source_file: (
-            source_file.relative_path.name in {"session.jsonl", "session.jsonl.zstd"}
-        ),
+        file_predicate=lambda source_file: bool(SESSION_FILE.match(source_file.relative_path.name)),
         suffixes=frozenset({".jsonl", ".zstd"}),
         header_selector=_is_session_header,
+        header_gate=_supported_session,
     )
 
 
 def _is_session_header(record: dict[str, JsonValue]) -> bool:
     """Harness writes the session's `cwd` once, in the first line only.
 
-    Verified against a session this machine produced: the header is
-    `{"type":"session","version":0,"id":...,"cwd":"/private/tmp/dsh-verify"}`
-    and no later record repeats it. Read per-record, `cwd` is therefore always
-    absent and every turn imports with no workspace.
+    Verified against sessions this machine produced: the header is
+    `{"type":"session","version":0|4,"id":...,"cwd":...}` and no later record
+    repeats it. Read per-record, `cwd` is therefore always absent and every turn
+    imports with no workspace.
     """
     return record.get("type") == "session"
 
 
+def _supported_session(header: dict[str, JsonValue] | None) -> bool:
+    """Whether the session's declared format generation is one we can read.
+
+    A missing header, or a header without `version`, is the first format — the
+    earliest files this adapter already read. Any declared version outside
+    `SUPPORTED_SESSION_VERSIONS` is refused rather than interpreted with today's
+    field rules: a future format may change field semantics, and importing it
+    wrongly is harder to undo than not importing it yet.
+    """
+    if header is None:
+        return True
+    version = header.get("version")
+    if version is None:
+        return True
+    if not isinstance(version, int) or isinstance(version, bool):
+        return False
+    return version in SUPPORTED_SESSION_VERSIONS
+
+
 def parse_deepseek_harness_record(
     record: dict[str, JsonValue],
     context: SourceRecordContext,
@@ -80,6 +112,11 @@ def parse_deepseek_harness_record(
     )
     event_type = record.get("type")
     data = as_record(record.get("data"))
+    if not _supported_session(context.header):
+        return ParsedSkip(
+            reason_code=ScanIssueCode.UNSUPPORTED_SCHEMA,
+            conversation_id=conversation_id,
+        )
     if event_type == "session":
         return ParsedSkip(reason_code=ScanIssueCode.UNKNOWN_RECORD)
     if data is None:
@@ -148,11 +185,18 @@ def _tool_message(
     """`tool/call` carries name and arguments; `tool/result` a user-role message.
 
     The same call also appears as a `tool-call` block in `assistant/message`;
-    only the event is read, so it is stored once.
+    only the event is read, so it is stored once. The first format and v3 wrap
+    the result in `tool-result` blocks; v4 writes plain `text` blocks, so both
+    shapes are read through the same clipping and credential-scrubbing path.
     """
     message = as_record(data.get("message"))
     if record.get("type") == "tool/result" and message is not None:
         text = tool_blocks_evidence(message.get("content"), block_types=frozenset({"tool-result"}))
+        if text is None:
+            text = tool_blocks_evidence(
+                [{"type": "tool-result", "content": message.get("content")}],
+                block_types=frozenset({"tool-result"}),
+            )
         message_id = first_string(message.get("id"), data.get("callId"))
     else:
         text = tool_evidence_text(data)

memhub/apps/core/src/one_memory/imports/sources/hermes.py

@@ -1,9 +1,9 @@
 import json
 import re
 import sqlite3
-from collections.abc import AsyncIterator, Iterator
+from collections.abc import AsyncIterator, Iterable, Iterator
 from functools import partial
-from pathlib import PurePosixPath
+from pathlib import Path, PurePosixPath
 
 from pydantic import JsonValue
 
@@ -88,7 +88,7 @@ class HermesSourceAdapter:
             self.grant,
             suffixes=frozenset({".jsonl", ".db"}),
             max_targets=10_000,
-            excluded_top_directories=frozenset({HERMES_PROFILES_DIRECTORY}),
+            excluded_directory_names=frozenset({HERMES_PROFILES_DIRECTORY}),
         ):
             if isinstance(item, AuthorizedSourceFile) and _is_hermes_target(
                 item.relative_path.as_posix()
@@ -102,7 +102,7 @@ class HermesSourceAdapter:
             self.grant,
             suffixes=frozenset({".jsonl", ".db"}),
             max_targets=options.max_scan_targets or 100_000,
-            excluded_top_directories=frozenset({HERMES_PROFILES_DIRECTORY}),
+            excluded_directory_names=frozenset({HERMES_PROFILES_DIRECTORY}),
         ):
             yield ScanProgressEvent(
                 phase=ScanPhase.DISCOVER,
@@ -253,16 +253,62 @@ def parse_hermes_rollout_record(
 #: own `state.db` and sessions. A profile is another person's history: it is
 #: read only through its own grant (its own MemHub user), never as part of the
 #: root above it. Hermes' own export skips this directory for the same reason.
+#:
+#: Skipped at any depth, not only directly under the root: a root granted
+#: above the Hermes home holds `.hermes/profiles/`. Hermes keeps nothing of
+#: its own under a directory of that name (its history is `state.db` and
+#: `sessions/`), so nothing real is lost.
 HERMES_PROFILES_DIRECTORY = "profiles"
 
 
 def _is_hermes_target(relative_path: str) -> bool:
     path = PurePosixPath(relative_path)
-    if path.parts and path.parts[0] == HERMES_PROFILES_DIRECTORY:
+    if HERMES_PROFILES_DIRECTORY in path.parts[:-1]:
         return False
     return path.name == "state.db" or (path.suffix == ".jsonl" and "sessions" in path.parts)
 
 
+def hermes_root_is_profiles_container(root: Path) -> bool:
+    """`profiles` itself holds everyone's profiles; it is never one person's history."""
+    return root.name == HERMES_PROFILES_DIRECTORY
+
+
+def hermes_root_conflict(mine: Path, other_users_roots: Iterable[Path]) -> str | None:
+    """Why the resolved root `mine` may not be granted beside other users' Hermes roots.
+
+    Paths are compared resolved (symlinks followed; the other users' roots are
+    resolved here). Two roots that are equal or nest would read the same files
+    for two users, except when one is exactly the other's `profiles/<name>`:
+    the scan above never enters `profiles/`, so the two stay apart (`local` on
+    `~/.hermes`, a user on `~/.hermes/profiles/<name>`). None when it may.
+    """
+    if hermes_root_is_profiles_container(mine):
+        return HERMES_ROOT_IS_PROFILES_CONTAINER
+    for other in other_users_roots:
+        theirs = _real(other)
+        if mine == theirs:
+            return HERMES_ROOT_OVERLAPS_OTHER_USER
+        for parent, child in ((mine, theirs), (theirs, mine)):
+            if parent in child.parents:
+                relative = child.relative_to(parent).parts
+                if len(relative) != 2 or relative[0] != HERMES_PROFILES_DIRECTORY:
+                    return HERMES_ROOT_OVERLAPS_OTHER_USER
+    return None
+
+
+#: 422: the root is the `profiles` container, not a profile.
+HERMES_ROOT_IS_PROFILES_CONTAINER = "hermes_root_is_profiles_container"
+#: 409: the root is, holds or sits inside another user's Hermes root.
+HERMES_ROOT_OVERLAPS_OTHER_USER = "hermes_root_overlaps_other_user"
+
+
+def _real(path: Path) -> Path:
+    try:
+        return path.expanduser().resolve(strict=False)
+    except (OSError, RuntimeError):
+        return path.expanduser().absolute()
+
+
 def _read_rollout(
     source_file: AuthorizedSourceFile,
     options: ScanOptions,

memhub/apps/core/src/one_memory/imports/sources/parsing.py

@@ -10,7 +10,10 @@ from pydantic import JsonValue
 from one_memory.input_sanitization import sanitize_model_input
 
 _REMINDER_TAGS = r"additional_data|system[-_]reminder|working_memory_reminder"
-_CONTEXT_TAGS = r"user_info|rules|agent_transcripts|system[-_]notification|pipeline_log"
+_CONTEXT_TAGS = (
+    r"user_info|rules|agent_transcripts|attached_files|image_local_path|"
+    r"system[-_]notification|pipeline_log"
+)
 _TAG_ATTRIBUTES = r"""(?:\s+[\w:-]+\s*=\s*(?:"[^"<>]*"|'[^'<>]*'))*\s*"""
 _HOST_PREFIX = re.compile(rf"<(?P<tag>{_REMINDER_TAGS}|{_CONTEXT_TAGS}){_TAG_ATTRIBUTES}>")
 _REMINDER_START = re.compile(rf"<(?P<tag>{_REMINDER_TAGS}){_TAG_ATTRIBUTES}>")

memhub/apps/core/src/one_memory/imports/supervisor.py

@@ -1,6 +1,7 @@
 import asyncio
 from collections.abc import Awaitable, Callable, Mapping
 from contextlib import suppress
+from functools import partial
 from time import monotonic
 from typing import Literal
 
@@ -82,6 +83,10 @@ class ImportSupervisor:
         )
         self._tasks: dict[str, asyncio.Task[None]] = {}
         self._drains: dict[str, asyncio.Task[None]] = {}
+        #: Pause and cancel settle a stopped job with a read and a transition.
+        #: Made on the loop, two of them could not interleave; made off it,
+        #: they are serialized here so they still land in the order they woke.
+        self._settling = asyncio.Lock()
 
     def register_adapter(self, adapter: SourceAdapter, *, user_id: str = "local") -> None:
         """Adapters are keyed by lane: the source id for `local`, `source@user`
@@ -116,11 +121,44 @@ class ImportSupervisor:
             raise UnknownSourceError(lane)
         if self.source_enabled is not None and not self.source_enabled(lane):
             return job
-        existing = self._tasks.get(job_id)
+        self._start(job)
+        return job
+
+    async def enqueue_off_loop(self, job_id: str, *, job: ImportJob | None = None) -> ImportJob:
+        """`enqueue`, with its job read and its grant check made off the loop.
+
+        Both are database reads, and the grant check resolves the source root
+        on disk. Live sync enqueues from its poll, so on the loop they were
+        the main thread waiting for a reader behind an import peak. `job` is
+        the row the caller has just read, when it has one.
+        """
+        if job_id in self._drains:
+            raise InvalidJobTransitionError("import_cleanup_in_progress")
+
+        def admit() -> tuple[ImportJob, bool]:
+            current = job if job is not None and job.job_id == job_id else None
+            if current is None:
+                current = self.job_store.require(job_id)
+            lane = self.lane_of(current)
+            return current, self.source_enabled is None or self.source_enabled(lane)
+
+        current, enabled = await in_the_background(admit)
+        lane = self.lane_of(current)
+        if lane not in self.adapters:
+            raise UnknownSourceError(lane)
+        if job_id in self._drains:
+            raise InvalidJobTransitionError("import_cleanup_in_progress")
+        if enabled:
+            self._start(current)
+        return current
+
+    def _start(self, job: ImportJob) -> None:
+        lane = self.lane_of(job)
+        existing = self._tasks.get(job.job_id)
         if existing is None or existing.done():
-            self._tasks[job_id] = asyncio.create_task(
+            self._tasks[job.job_id] = asyncio.create_task(
                 self._execute(
-                    job_id,
+                    job.job_id,
                     source_id=lane,
                     operation=job.operation,
                 )
@@ -130,10 +168,24 @@ class ImportSupervisor:
                 component="import.supervisor",
                 event="import.queued",
                 outcome="queued",
-                job_id=job_id,
+                job_id=job.job_id,
                 details={"source_id": job.source_id, "mode": job.operation},
             )
-        return job
+
+    async def resume_interrupted_off_loop(self) -> None:
+        """`resume_interrupted` for the running Core: every read and write off the loop."""
+        for status in (ImportStatus.INTERRUPTED, ImportStatus.PENDING):
+            jobs = await in_the_background(partial(self.job_store.find_jobs, statuses=(status,)))
+            for job in jobs:
+                if self.lane_of(job) not in self.adapters:
+                    continue
+                if job.status is not ImportStatus.PENDING:
+                    if self.source_enabled is not None and not await in_the_background(
+                        self.source_enabled, self.lane_of(job)
+                    ):
+                        continue
+                    job = await in_the_background(self.job_store.queue_for_resume, job.job_id)
+                await self.enqueue_off_loop(job.job_id, job=job)
 
     def resume_interrupted(self) -> None:
         # A process restart must not place recoverable work behind every newly
@@ -166,40 +218,64 @@ class ImportSupervisor:
         self.enqueue(job_id)
         return queued
 
+    async def resume_off_loop(self, job_id: str) -> ImportJob:
+        """`resume`, with its reads and its write made off the event loop."""
+        if job_id in self._drains:
+            raise InvalidJobTransitionError("import_cleanup_in_progress")
+        queued = await in_the_background(self._queue_resumable, job_id)
+        if queued.status is not ImportStatus.PENDING:
+            return queued
+        return await self.enqueue_off_loop(job_id, job=queued)
+
+    def _queue_resumable(self, job_id: str) -> ImportJob:
+        job = self.job_store.require(job_id)
+        if job.status not in {
+            ImportStatus.PENDING,
+            ImportStatus.PAUSED,
+            ImportStatus.INTERRUPTED,
+            ImportStatus.FAILED,
+        }:
+            return job
+        return self.job_store.queue_for_resume(job_id)
+
     async def wait(self, job_id: str) -> ImportJob:
         task = self._tasks.get(job_id)
         if task is not None:
             await asyncio.shield(task)
-        return self.job_store.require(job_id)
+        return await in_the_background(self.job_store.require, job_id)
 
     async def pause(self, job_id: str) -> ImportJob:
-        job = self.job_store.require(job_id)
+        job = await in_the_background(self.job_store.require, job_id)
         if job.status in {ImportStatus.PAUSED, ImportStatus.INTERRUPTED}:
             return job
         await self._cancel_task(job_id)
-        current = self.job_store.require(job_id)
-        if current.status is ImportStatus.COMPLETED:
-            return current
-        return self.job_store.transition(job_id, ImportStatus.PAUSED)
+        async with self._settling:
+            return await in_the_background(self._settle_stopped, job_id, ImportStatus.PAUSED)
 
     async def cancel(self, job_id: str) -> ImportJob:
-        job = self.job_store.require(job_id)
+        job = await in_the_background(self.job_store.require, job_id)
         if job.status is ImportStatus.CANCELLED:
             return job
         await self._cancel_task(job_id)
+        async with self._settling:
+            return await in_the_background(self._settle_stopped, job_id, ImportStatus.CANCELLED)
+
+    def _settle_stopped(self, job_id: str, target: ImportStatus) -> ImportJob:
+        """A stopped runner's job moves to `target`, unless it completed first."""
         current = self.job_store.require(job_id)
         if current.status is ImportStatus.COMPLETED:
             return current
-        return self.job_store.transition(job_id, ImportStatus.CANCELLED)
+        return self.job_store.transition(job_id, target)
 
     async def shutdown(self) -> None:
-        running = [
-            job
-            for job in self.job_store.list_jobs(status=ImportStatus.RUNNING)
-            if job.job_id in self._tasks
-        ]
-        for job in running:
-            self.job_store.interrupt_running(job.job_id)
+        mine = frozenset(self._tasks)
+
+        def interrupt_mine() -> None:
+            for job in self.job_store.find_jobs(statuses=(ImportStatus.RUNNING,)):
+                if job.job_id in mine:
+                    self.job_store.interrupt_running(job.job_id)
+
+        await in_the_background(interrupt_mine)
         await asyncio.gather(
             *(self._cancel_task(job_id) for job_id in tuple(self._tasks)),
         )
@@ -355,9 +431,7 @@ class ImportSupervisor:
             try:
                 await asyncio.wait_for(asyncio.shield(task), timeout)
             except TimeoutError:
-                current = self.job_store.require(job_id)
-                if current.status is ImportStatus.RUNNING:
-                    self.job_store.interrupt_running(job_id)
+                await in_the_background(self._interrupt_if_running, job_id)
                 return False
             except asyncio.CancelledError:
                 # The worker noticed cancel and exited. A cancel of this
@@ -365,10 +439,16 @@ class ImportSupervisor:
                 caller = asyncio.current_task()
                 if caller is not None and caller.cancelling():
                     raise
+        # A read and a write on the single writer: off the loop. Live sync
+        # calls this from its poll, and on the loop it was the main thread
+        # waiting its turn for the writer behind an import peak.
+        await in_the_background(self._interrupt_if_running, job_id)
+        return True
+
+    def _interrupt_if_running(self, job_id: str) -> None:
         current = self.job_store.require(job_id)
         if current.status is ImportStatus.RUNNING:
             self.job_store.interrupt_running(job_id)
-        return True
 
     async def _cancel_task(self, job_id: str) -> None:
         drain = self._drains.get(job_id)

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

@@ -34,6 +34,7 @@ from one_memory.memory_governance import MemoryGovernanceStore, MemoryStatus
 from one_memory.memory_server.durable_queue import DurableWriteQueue
 from one_memory.memory_server.unified_entry import UnifiedWriteIntake
 from one_memory.memory_tasks import MemoryTaskStatus, MemoryTaskStore
+from one_memory.model_backoff import next_retry_at
 from one_memory.secrets import SecretStoreUnavailableError
 from one_memory.user_scope import DEFAULT_USER_ID, USER_ID_PATTERN, UserId
 
@@ -77,6 +78,12 @@ class MemoryAddReceipt(BaseModel):
     task_id: str | None = None
     memory_ids: list[str] = Field(default_factory=list)
     error: str | None = None
+    #: Why a note still being worked on last failed (`model_auth_failed`, ...),
+    #: or why a failed one failed. A provider failure keeps it `pending`.
+    error_code: str | None = None
+    #: When a pending note is next tried: its own retry wait, or the model
+    #: provider's pause while the provider is failing.
+    next_retry_at: str | None = None
 
 
 class LegacyMemoryAdditionReader:
@@ -258,6 +265,8 @@ class MemoryAdditionStore:
             durable_state = durable.state if durable is not None else "failed"
             mapped: MemoryAddState = {
                 "pending": "pending",
+                # Re-run automatically within seconds (`recover_unknown`).
+                "unknown": "pending",
                 "running": "running",
                 "waiting_for_model": "waiting_for_model",
                 "waiting_for_permission": "waiting_for_permission",
@@ -272,6 +281,12 @@ class MemoryAdditionStore:
                 state=mapped,
                 memory_ids=(list(durable.sdk_memory_ids) if durable is not None else []),
                 error=durable.detail if durable is not None else "write_missing",
+                error_code=(
+                    durable.error_code
+                    if durable is not None and durable.state != "completed"
+                    else None
+                ),
+                next_retry_at=durable.retry_at if durable is not None else None,
             )
         if self.processor is None:
             raise RuntimeError("legacy_memory_add_processor_unavailable")
@@ -402,10 +417,15 @@ def memory_add_router(dependencies: Sequence[Depends]) -> APIRouter:
         user_id: str = Query(default=DEFAULT_USER_ID, pattern=USER_ID_PATTERN),
     ) -> MemoryAddReceipt:
         try:
-            return store(request).receipt_for_request(request_id, user_id=user_id)
+            receipt = store(request).receipt_for_request(request_id, user_id=user_id)
         except KeyError as error:
             raise HTTPException(404, "memory_add_not_found") from error
         except ValueError as error:
             raise HTTPException(409, str(error)) from error
+        return receipt.model_copy(
+            update={
+                "next_retry_at": next_retry_at(request.app, receipt.state, receipt.next_retry_at)
+            }
+        )
 
     return router

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

@@ -465,12 +465,16 @@ class EvolveScheduler:
         service: EvolveService,
         schedule: Callable[[], EvolveSchedule],
         users_with_memories: Callable[[], Awaitable[Iterable[str]]],
+        lifecycle_lock: asyncio.Lock | None = None,
+        lifecycle_open: Callable[[], bool] = lambda: True,
         now: Callable[[], datetime] = lambda: datetime.now().astimezone(),
         check_seconds: float = SCHEDULE_CHECK_SECONDS,
     ) -> None:
         self.service = service
         self.schedule = schedule
         self.users_with_memories = users_with_memories
+        self.lifecycle_lock = lifecycle_lock
+        self.lifecycle_open = lifecycle_open
         self._now = now
         self.check_seconds = check_seconds
         self._task: asyncio.Task[None] | None = None
@@ -492,7 +496,15 @@ class EvolveScheduler:
             if not evolve_due(now, schedule, last, anchor):
                 continue
             try:
-                receipt = self.service.start(user_id, trigger="scheduled")
+                if self.lifecycle_lock is None:
+                    if not self.lifecycle_open():
+                        break
+                    receipt = self.service.start(user_id, trigger="scheduled")
+                else:
+                    async with self.lifecycle_lock:
+                        if not self.lifecycle_open():
+                            break
+                        receipt = self.service.start(user_id, trigger="scheduled")
             except EvolveModeError:
                 break
             await self.service.wait(receipt.run_id)
@@ -533,10 +545,12 @@ class MemoryGraphBackfill:
         *,
         coordinator: EvolveCoordinator,
         state: EvolveStateStore,
+        lifecycle_open: Callable[[], bool] = lambda: True,
         now: Callable[[], datetime] = lambda: datetime.now(UTC),
     ) -> None:
         self.coordinator = coordinator
         self.state = state
+        self.lifecycle_open = lifecycle_open
         self._now = now
         self._task: asyncio.Task[None] | None = None
 
@@ -557,6 +571,35 @@ class MemoryGraphBackfill:
         self._task = asyncio.create_task(self._run(users), name="one-memory-graph-backfill")
         return state
 
+    def recover(self, user_ids: Iterable[str]) -> GraphBuildState:
+        """Resume an interrupted backfill without repeating completed users."""
+        if self.running:
+            return self.state.graph_build()
+        saved = self.state.graph_build()
+        if saved.state != "running":
+            return saved
+        users = tuple(dict.fromkeys((*saved.users.keys(), *user_ids)))
+        pending = tuple(
+            user_id
+            for user_id in users
+            if saved.users.get(user_id, GraphBuildUser()).state != "succeeded"
+        )
+        resumed = saved.model_copy(deep=True)
+        for user_id in pending:
+            resumed.users[user_id] = GraphBuildUser()
+        if not pending:
+            resumed.state = "succeeded"
+            resumed.finished_at = self._now()
+            self.state.set_graph_build(resumed)
+            return resumed
+        resumed.state = "running"
+        resumed.finished_at = None
+        self.state.set_graph_build(resumed)
+        self._task = asyncio.create_task(
+            self._run(pending), name="one-memory-graph-backfill-recovery"
+        )
+        return resumed
+
     async def wait(self) -> None:
         if self._task is not None:
             await asyncio.shield(self._task)
@@ -564,6 +607,8 @@ class MemoryGraphBackfill:
     async def _run(self, users: tuple[str, ...]) -> None:
         state = self.state.graph_build()
         for user_id in users:
+            while not self.lifecycle_open():
+                await asyncio.sleep(0.2)
             state.users[user_id] = GraphBuildUser(state="running")
             await asyncio.to_thread(self.state.set_graph_build, state.model_copy(deep=True))
             try:

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

@@ -21,6 +21,11 @@ exercises (query rewrite needs `queries=[...]`, session narratives need
 cross-encoder download, access write-back); and everything MemHub already
 controls elsewhere (pipeline log, trace, memory operations, telemetry, mode).
 
+Beside the on/off features there is one numeric parameter,
+`intention_dedup_threshold` (`PARAMETERS`): the cosine similarity at which the
+read-time intention dedup treats two intentions as copies. It is set, stored,
+reset and keyed exactly like a feature.
+
 No SDK import here: only `hy_sdk_runtime` and `hy_sdk_migration` import it.
 `config_state` imports this module, so it imports nothing from there.
 """
@@ -31,7 +36,7 @@ from collections.abc import Mapping
 from dataclasses import dataclass
 from typing import Literal
 
-from pydantic import BaseModel, ConfigDict, StrictBool
+from pydantic import BaseModel, ConfigDict, Field, StrictBool
 
 MemoryFeatureName = Literal[
     "graph_rerank",
@@ -40,8 +45,13 @@ MemoryFeatureName = Literal[
     "session_episodes",
     "episode_summary",
     "intention",
+    "intention_dedup",
     "few_shot",
 ]
+#: Numeric settings beside the on/off features.
+MemoryParameterName = Literal["intention_dedup_threshold"]
+#: Every key of the setting: a feature or a parameter.
+MemorySettingName = MemoryFeatureName | MemoryParameterName
 #: Read features change search; write features change what extraction stores.
 FeatureSide = Literal["read", "write"]
 #: none: no extra call. extra_query: one more store query per search.
@@ -49,9 +59,25 @@ FeatureSide = Literal["read", "write"]
 #: a longer extraction prompt.
 FeatureCost = Literal["none", "extra_query", "llm_call", "prompt_tokens"]
 #: Why an enabled feature does nothing right now (`active: false`).
-FeatureReason = Literal["disabled", "requires_pro", "requires_ultra", "requires_graph_rerank"]
+FeatureReason = Literal[
+    "disabled",
+    "requires_pro",
+    "requires_ultra",
+    "requires_graph_rerank",
+    "requires_intention_dedup",
+]
+#: A feature is on or off; a parameter is a number.
+type SettingValue = bool | float
 #: A client's features as a hashable key: sorted (name, value) pairs, set ones only.
-type FeatureOverrides = tuple[tuple[str, bool], ...]
+type FeatureOverrides = tuple[tuple[str, SettingValue], ...]
+
+#: The range a person may set `intention_dedup_threshold` to. With dedup on,
+#: the SDK deletes every intention at or above it from the store at read time,
+#: which cannot be undone; below 0.8 the embedding models MemHub uses score
+#: different plans on one topic as that close, so a lower value would delete
+#: intentions that are not copies. 1.0 keeps only exact copies' dedup.
+INTENTION_DEDUP_THRESHOLD_MIN = 0.8
+INTENTION_DEDUP_THRESHOLD_MAX = 1.0
 
 _MODE_RANK: dict[str, int] = {"lite": 0, "pro": 1, "ultra": 2}
 
@@ -169,6 +195,23 @@ FEATURES: tuple[FeatureSpec, ...] = (
             "No extra call."
         ),
     ),
+    FeatureSpec(
+        name="intention_dedup",
+        section="recall",
+        field="intention_dedup_enabled",
+        env="MEMORY_INTENTION_DEDUP_ENABLED",
+        side="read",
+        requires_mode="pro",
+        requires_feature=None,
+        cost="none",
+        description=(
+            "Treat same-day intentions (L7) with the same expiry and a cosine "
+            "similarity at or above intention_dedup_threshold as copies: a "
+            "search returns the earliest and deletes the others from the store. "
+            "On by default; off hides, drops and deletes no intention, at read "
+            "time or in a write batch. No extra call."
+        ),
+    ),
     FeatureSpec(
         name="few_shot",
         section="llm",
@@ -189,12 +232,57 @@ FEATURE_NAMES: tuple[MemoryFeatureName, ...] = tuple(spec.name for spec in FEATU
 FEATURES_BY_NAME: dict[str, FeatureSpec] = {spec.name: spec for spec in FEATURES}
 
 
+@dataclass(frozen=True)
+class ParameterSpec:
+    """A numeric setting; it acts only while `requires_feature` acts."""
+
+    name: MemoryParameterName
+    section: Literal["recall"]
+    field: str
+    env: str
+    minimum: float
+    maximum: float
+    requires_feature: MemoryFeatureName
+    description: str
+
+    @property
+    def sdk_field(self) -> str:
+        return f"{self.section}.{self.field}"
+
+
+PARAMETERS: tuple[ParameterSpec, ...] = (
+    ParameterSpec(
+        name="intention_dedup_threshold",
+        section="recall",
+        field="intention_dedup_threshold",
+        env="MEMORY_INTENTION_DEDUP_THRESHOLD",
+        minimum=INTENTION_DEDUP_THRESHOLD_MIN,
+        maximum=INTENTION_DEDUP_THRESHOLD_MAX,
+        requires_feature="intention_dedup",
+        description=(
+            "Cosine similarity at or above which intention_dedup treats two "
+            "intentions as copies. Higher keeps more. The SDK default is 0.95 "
+            "(MEMORY_DEDUP_THRESHOLD also sets it when its own env var is unset)."
+        ),
+    ),
+)
+PARAMETER_NAMES: tuple[MemoryParameterName, ...] = tuple(spec.name for spec in PARAMETERS)
+PARAMETERS_BY_NAME: dict[str, ParameterSpec] = {spec.name: spec for spec in PARAMETERS}
+#: Every key of the setting, features first, each in its catalog order.
+SETTING_NAMES: tuple[MemorySettingName, ...] = (*FEATURE_NAMES, *PARAMETER_NAMES)
+SETTINGS_BY_NAME: dict[str, FeatureSpec | ParameterSpec] = {
+    **FEATURES_BY_NAME,
+    **PARAMETERS_BY_NAME,
+}
+
+
 class MemoryFeatures(BaseModel):
     """`config.json` `memory_features`, and the `PUT` body.
 
     Every key is optional; absent (or null) means the SDK default. In a `PUT`
-    an absent key is left as it is and null resets it. Unknown keys and
-    non-boolean values are refused (422).
+    an absent key is left as it is and null resets it. Unknown keys,
+    non-boolean feature values and a threshold that is not a number in its
+    range are refused (422).
     """
 
     model_config = ConfigDict(frozen=True, extra="forbid", strict=True)
@@ -205,7 +293,14 @@ class MemoryFeatures(BaseModel):
     session_episodes: StrictBool | None = None
     episode_summary: StrictBool | None = None
     intention: StrictBool | None = None
+    intention_dedup: StrictBool | None = None
     few_shot: StrictBool | None = None
+    intention_dedup_threshold: float | None = Field(
+        default=None,
+        ge=INTENTION_DEDUP_THRESHOLD_MIN,
+        le=INTENTION_DEDUP_THRESHOLD_MAX,
+        allow_inf_nan=False,
+    )
 
     def overrides(self) -> FeatureOverrides:
         """The features a person set, as the client key."""
@@ -221,24 +316,47 @@ class MemoryFeatures(BaseModel):
         return MemoryFeatures(**{key: value for key, value in values.items() if value is not None})
 
 
-def feature_overrides(values: Mapping[str, bool]) -> FeatureOverrides:
-    unknown = set(values) - set(FEATURES_BY_NAME)
+def feature_overrides(values: Mapping[str, SettingValue]) -> FeatureOverrides:
+    unknown = set(values) - set(SETTINGS_BY_NAME)
     if unknown:
         raise ValueError("unknown_memory_feature")
-    return tuple(sorted((name, bool(value)) for name, value in values.items()))
+    return tuple(sorted((name, _setting_value(name, value)) for name, value in values.items()))
+
+
+def _setting_value(name: str, value: SettingValue) -> SettingValue:
+    parameter = PARAMETERS_BY_NAME.get(name)
+    if parameter is None:
+        return bool(value)
+    if isinstance(value, bool) or not parameter.minimum <= float(value) <= parameter.maximum:
+        raise ValueError("invalid_memory_feature_value")
+    return float(value)
 
 
 def effective_features(
-    overrides: FeatureOverrides, defaults: Mapping[str, bool]
-) -> dict[str, bool]:
-    """Every feature's value: what a person set, else the SDK default."""
-    values: dict[str, bool] = {spec.name: bool(defaults.get(spec.name, False)) for spec in FEATURES}
+    overrides: FeatureOverrides, defaults: Mapping[str, SettingValue]
+) -> dict[str, SettingValue]:
+    """Every setting's value: what a person set, else the SDK default."""
+    values: dict[str, SettingValue] = {
+        spec.name: bool(defaults.get(spec.name, False)) for spec in FEATURES
+    }
+    for parameter in PARAMETERS:
+        if parameter.name in defaults:
+            values[parameter.name] = float(defaults[parameter.name])
     values.update(dict(overrides))
     return values
 
 
-def feature_activity(name: str, effective: Mapping[str, bool], mode: str) -> FeatureReason | None:
-    """None when the feature acts in this mode; else why it does not."""
+def feature_activity(
+    name: str, effective: Mapping[str, SettingValue], mode: str
+) -> FeatureReason | None:
+    """None when the feature acts in this mode; else why it does not.
+
+    A parameter acts exactly when the feature it tunes acts.
+    """
+    parameter = PARAMETERS_BY_NAME.get(name)
+    if parameter is not None:
+        reason = feature_activity(parameter.requires_feature, effective, mode)
+        return "requires_intention_dedup" if reason == "disabled" else reason
     spec = FEATURES_BY_NAME[name]
     if not effective.get(name, False):
         return "disabled"
@@ -252,11 +370,12 @@ def feature_activity(name: str, effective: Mapping[str, bool], mode: str) -> Fea
 
 
 def non_default_features(
-    overrides: FeatureOverrides, defaults: Mapping[str, bool]
-) -> dict[str, bool]:
-    """The features whose value differs from the SDK default, for status."""
+    overrides: FeatureOverrides, defaults: Mapping[str, SettingValue]
+) -> dict[str, SettingValue]:
+    """The settings whose value differs from the SDK default, for status."""
+    baseline = effective_features((), defaults)
     return {
         name: value
         for name, value in effective_features(overrides, defaults).items()
-        if value != bool(defaults.get(name, False))
+        if value != baseline.get(name)
     }

memhub/apps/core/src/one_memory/memory_server/config_state.py

@@ -19,6 +19,7 @@ from pydantic import BaseModel, ConfigDict, Field, StrictBool, field_validator
 
 from one_memory.memory_features import MemoryFeatures
 from one_memory.memory_queue import ExtractionWindowPreset
+from one_memory.ui_language import UI_LANGUAGES, UiLanguage
 
 _SOURCE_ID = re.compile(r"^[a-z0-9][a-z0-9-]{0,127}$")
 
@@ -73,6 +74,10 @@ class ConfigDocument(BaseModel):
     #: SDK retrieval and extraction features a person set; an unset one keeps
     #: the SDK default. See `one_memory.memory_features`.
     memory_features: MemoryFeatures = Field(default_factory=MemoryFeatures)
+    #: The display language the App shows (its choice, or the system language
+    #: it follows); None = none set. See `one_memory.ui_language` for what it
+    #: does to the SDK.
+    ui_language: UiLanguage | None = None
 
     @field_validator("sources")
     @classmethod
@@ -95,7 +100,7 @@ class ConfigFileError(RuntimeError):
     pass
 
 
-_WRITTEN_WHEN_SET = frozenset({"memory_mode", "evolve_schedule", "memory_features"})
+_WRITTEN_WHEN_SET = frozenset({"memory_mode", "evolve_schedule", "memory_features", "ui_language"})
 
 
 class ConfigStore:
@@ -148,6 +153,11 @@ class ConfigStore:
         with self._lock:
             return self._document.memory_mode
 
+    def memory_mode_explicitly_configured(self) -> bool:
+        """Whether a person chose the mode, including choosing the default."""
+        with self._lock:
+            return "memory_mode" in self._document.model_fields_set
+
     def set_memory_mode(self, mode: MemoryMode) -> ConfigDocument:
         if mode not in MEMORY_MODES:
             raise ValueError("invalid_memory_mode")
@@ -183,6 +193,19 @@ class ConfigStore:
             self._document = updated
             return updated
 
+    def ui_language(self) -> UiLanguage | None:
+        with self._lock:
+            return self._document.ui_language
+
+    def set_ui_language(self, language: UiLanguage | None) -> ConfigDocument:
+        if language is not None and language not in UI_LANGUAGES:
+            raise ValueError("invalid_ui_language")
+        with self._lock:
+            updated = self._document.model_copy(update={"ui_language": language})
+            self._write(updated)
+            self._document = updated
+            return updated
+
     def migrate_extraction_window_preset(self, preset: ExtractionWindowPreset) -> ConfigDocument:
         """Adopt the legacy SQL value only when config.json has no value."""
         if not isinstance(preset, ExtractionWindowPreset):

memhub/apps/core/src/one_memory/memory_server/migrations.py

@@ -1383,6 +1383,83 @@ async def _050_model_probe_operations_reserved_at(cursor: Any) -> None:
     )
 
 
+def embedding_spaces_ddl() -> str:
+    """The embedding space registry (`embedding_spaces.py`); the main Core SQLite only.
+
+    Unversioned on purpose, like the visibility tables: a migration raises
+    the build's schema version, and a library this build opened would then
+    refuse an older package. The table is additive and created idempotently;
+    an older build ignores it and opens the space its active profile names,
+    which is the registered space on every home that never switched. SQLite
+    only (partial unique indexes): it lives in the main Core database.
+    """
+    return """
+CREATE TABLE IF NOT EXISTS embedding_spaces (
+    space_id TEXT PRIMARY KEY NOT NULL,
+    state TEXT NOT NULL CHECK(state IN ('live','building','stray','retired','dropped')),
+    model TEXT,
+    dims INTEGER,
+    name_dims INTEGER,
+    collection_base TEXT NOT NULL,
+    naming TEXT NOT NULL CHECK(naming IN ('legacy','v2','discovered')),
+    graph_dir TEXT,
+    provider_kind TEXT,
+    profile_id TEXT,
+    profile_revision INTEGER,
+    vectors INTEGER,
+    created_at TEXT NOT NULL,
+    live_since TEXT,
+    retired_at TEXT,
+    keep_until TEXT,
+    dropped_at TEXT
+);
+CREATE UNIQUE INDEX IF NOT EXISTS embedding_spaces_one_live
+    ON embedding_spaces(state) WHERE state = 'live';
+CREATE UNIQUE INDEX IF NOT EXISTS embedding_spaces_one_physical
+    ON embedding_spaces(collection_base, COALESCE(name_dims, 0))
+    WHERE state != 'dropped';
+"""
+
+
+def embedding_switch_jobs_ddl() -> str:
+    """Embedding switch and merge jobs (`embedding_switch.py`); unversioned, as above.
+
+    At most one job is open at a time (the partial unique index), and it
+    lives beside the profiles and the registry so the commit is one
+    transaction over all three.
+    """
+    return """
+CREATE TABLE IF NOT EXISTS embedding_switch_jobs (
+    job_id TEXT PRIMARY KEY NOT NULL,
+    kind TEXT NOT NULL CHECK(kind IN ('switch','merge')),
+    state TEXT NOT NULL CHECK(state IN (
+        'preparing','reembedding','verifying','committing','done','failed','rolled_back'
+    )),
+    source_space_id TEXT NOT NULL,
+    target_space_id TEXT NOT NULL,
+    stray_space_ids TEXT NOT NULL DEFAULT '[]',
+    target_profile_id TEXT,
+    target_revision INTEGER,
+    prior_profile_id TEXT,
+    requested_by TEXT NOT NULL,
+    plan_json TEXT NOT NULL,
+    progress_json TEXT NOT NULL DEFAULT '{}',
+    verification_json TEXT,
+    error_code TEXT,
+    error_detail TEXT,
+    cancel_requested INTEGER NOT NULL DEFAULT 0,
+    owner_pid INTEGER,
+    heartbeat_at TEXT,
+    attempt INTEGER NOT NULL DEFAULT 1,
+    created_at TEXT NOT NULL,
+    updated_at TEXT NOT NULL,
+    finished_at TEXT
+);
+CREATE UNIQUE INDEX IF NOT EXISTS embedding_switch_one_open
+    ON embedding_switch_jobs((1)) WHERE state NOT IN ('done','rolled_back');
+"""
+
+
 def model_profile_seeds_ddl(dialect: str = "mysql") -> str:
     """Which presets have been seeded, so seeding happens once."""
     if dialect == "sqlite":
@@ -3086,6 +3163,137 @@ async def _060_memory_note_requests(cursor: Any) -> None:
         await cursor.execute(statement)
 
 
+def write_job_retries_ddl(dialect: str = "mysql") -> str:
+    """Per-job retry state: which SDK request id is next, and retries spent.
+
+    The SDK replays a request id's first outcome forever, so every re-run of
+    a job needs an id of its own (`sdk_attempt`). `retries` counts automatic
+    retries after failures of the job itself; provider failures spend none.
+    """
+    if dialect == "sqlite":
+        return """
+ALTER TABLE memory_write_jobs
+ADD COLUMN sdk_attempt INTEGER NOT NULL DEFAULT 0;
+ALTER TABLE memory_write_jobs
+ADD COLUMN retries INTEGER NOT NULL DEFAULT 0;
+"""
+    return """
+ALTER TABLE memory_write_jobs
+ADD COLUMN sdk_attempt INT NOT NULL DEFAULT 0;
+ALTER TABLE memory_write_jobs
+ADD COLUMN retries INT NOT NULL DEFAULT 0;
+"""
+
+
+async def _061_write_job_retries(cursor: Any) -> None:
+    for statement in _split_statements(write_job_retries_ddl(_dialect(cursor))):
+        await cursor.execute(statement)
+
+
+ONBOARDING_PROGRESS_MIGRATION_VERSION = 62
+
+
+def onboarding_progress_ddl(dialect: str = "mysql") -> str:
+    """Append resumable onboarding choices without rewriting migration 12."""
+    if dialect == "sqlite":
+        return """
+ALTER TABLE onboarding_state
+ADD COLUMN mode_intent TEXT NULL;
+ALTER TABLE onboarding_state
+ADD COLUMN setup_step TEXT NULL;
+ALTER TABLE onboarding_state
+ADD COLUMN model_profile_id TEXT NULL;
+"""
+    return """
+ALTER TABLE onboarding_state
+ADD COLUMN mode_intent VARCHAR(16) NULL AFTER updated_at;
+ALTER TABLE onboarding_state
+ADD COLUMN setup_step VARCHAR(16) NULL AFTER mode_intent;
+ALTER TABLE onboarding_state
+ADD COLUMN model_profile_id VARCHAR(36) NULL AFTER setup_step;
+"""
+
+
+async def _062_onboarding_progress(cursor: Any) -> None:
+    if _dialect(cursor) == "sqlite":
+        existing = await cursor.columns("onboarding_state")
+        statements = _split_statements(onboarding_progress_ddl("sqlite"))
+        for column, statement in zip(
+            ("mode_intent", "setup_step", "model_profile_id"),
+            statements,
+            strict=True,
+        ):
+            if column not in existing:
+                await cursor.execute(statement)
+        return
+    for statement in _split_statements(onboarding_progress_ddl("mysql")):
+        try:
+            await cursor.execute(statement)
+        except Exception as error:  # noqa: BLE001 - MySQL driver error type varies
+            if _is_duplicate_column(error):
+                continue
+            raise
+
+
+IMPORT_JOB_LOOKUP_INDEXES_MIGRATION_VERSION = 63
+
+
+def import_job_lookup_indexes_ddl(dialect: str = "mysql") -> str:
+    """Index the per-source and per-status import job lookups.
+
+    Migration 7 gave SQLite `import_jobs` no index beyond its primary key (the
+    one-active-job index is partial), so every "this source's jobs" or "the
+    jobs in this state" question read and sorted the whole table. Live sync
+    adds a row per change it imports and nothing removed them, so on a machine
+    a few weeks old that table was thousands of rows read several times a poll.
+
+    `import_jobs_lane` serves the lane lookups (one user, one source, one
+    operation, a status, newest first) and the pruning of finished syncs;
+    `import_jobs_status` serves restart recovery and the status filters.
+    MySQL's migration 7 already has a status index and no `operation` column,
+    so it only gains the ordered source index.
+    """
+    if dialect == "sqlite":
+        return """
+CREATE INDEX IF NOT EXISTS import_jobs_lane
+ON import_jobs(user_id, source_id, operation, status, created_at);
+CREATE INDEX IF NOT EXISTS import_jobs_status
+ON import_jobs(status, created_at);
+"""
+    return """
+CREATE INDEX idx_import_jobs_source_created
+ON import_jobs(user_id, source_id, created_at);
+"""
+
+
+def _is_duplicate_index(error: Exception) -> bool:
+    """MySQL's "index name already there" (1061): the index is in place."""
+    args: tuple[object, ...] = getattr(error, "args", ())
+    return bool(args) and args[0] == 1061
+
+
+async def _063_import_job_lookup_indexes(cursor: Any) -> None:
+    dialect = _dialect(cursor)
+    if dialect == "sqlite":
+        # `operation` was added by the job store, not by migration 7, so a
+        # database built from the catalog alone may not have it yet. Same
+        # declaration as the store's own addition.
+        if "operation" not in await cursor.columns("import_jobs"):
+            await cursor.execute(
+                "ALTER TABLE import_jobs ADD COLUMN operation TEXT NOT NULL DEFAULT 'history'"
+            )
+        for statement in _split_statements(import_job_lookup_indexes_ddl(dialect)):
+            await cursor.execute(statement)
+        return
+    for statement in _split_statements(import_job_lookup_indexes_ddl(dialect)):
+        try:
+            await cursor.execute(statement)
+        except Exception as error:  # noqa: BLE001 - MySQL driver error type varies
+            if _is_duplicate_index(error):
+                continue
+            raise
+
+
 def _split_statements(sql: str) -> list[str]:
     """Split a multi-statement script, dropping blanks, PRAGMA and comments.
 
@@ -3385,4 +3593,16 @@ MIGRATIONS: tuple[Migration, ...] = (
         _060_memory_note_requests,
         ("memory_note_requests",),
     ),
+    Migration(61, "write_job_retries", _061_write_job_retries),
+    Migration(
+        ONBOARDING_PROGRESS_MIGRATION_VERSION,
+        "onboarding_progress",
+        _062_onboarding_progress,
+        ("onboarding_state",),
+    ),
+    Migration(
+        IMPORT_JOB_LOOKUP_INDEXES_MIGRATION_VERSION,
+        "import_job_lookup_indexes",
+        _063_import_job_lookup_indexes,
+    ),
 )

memhub/apps/core/src/one_memory/memory_server/registry.py

@@ -57,6 +57,11 @@ class WriteRecord:
     detail: str = ""
     raw_ids: tuple[str, ...] = ()
     memory_ids: tuple[str, ...] = ()
+    #: The stable code of the last failure of a job still being worked on
+    #: (or of a failed one).
+    error_code: str | None = None
+    #: When a waiting job is next tried, if a retry wait holds it.
+    next_retry_at: str | None = None
 
 
 def _now() -> str:

memhub/apps/core/src/one_memory/memory_server/routes.py

@@ -44,6 +44,7 @@ from one_memory.memory_server.durable_queue import (
 )
 from one_memory.memory_server.registry import WriteRegistry, WriteState
 from one_memory.memory_server.submit import WriteConflictError
+from one_memory.model_backoff import next_retry_at
 from one_memory.user_scope import DEFAULT_USER_ID, USER_ID_PATTERN, UserId
 
 #: Durable keys of another user's writes start with this. A `local` request
@@ -72,6 +73,12 @@ class MemoryWriteReceipt(BaseModel):
     detail: str = ""
     raw_ids: tuple[str, ...] = ()
     memory_ids: tuple[str, ...] = ()
+    #: Why a job still being worked on last failed (`model_auth_failed`, ...),
+    #: or why a failed one failed. A provider failure keeps `state` queued.
+    error_code: str | None = None
+    #: When it is next tried: the job's own retry wait, or the model
+    #: provider's pause (`model_backoff`) while the provider is failing.
+    next_retry_at: str | None = None
 
 
 class OpenAIMessage(BaseModel):
@@ -235,6 +242,8 @@ def sdk_router(dependencies: list[Any] | None = None) -> APIRouter:
             detail=record.detail,
             raw_ids=record.raw_ids,
             memory_ids=record.memory_ids,
+            error_code=record.error_code,
+            next_retry_at=next_retry_at(request.app, record.state, record.next_retry_at),
         )
 
     return instance

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

@@ -0,0 +1,330 @@
+"""One pause for every model request while the provider keeps failing (#245).
+
+A broken model configuration (a revoked key, a wrong base URL, a model that
+does not exist, a provider that is down) used to fail each queued job on its
+own: the drain claimed the next job the moment the last one failed, so a
+backlog of hundreds of jobs turned into requests as fast as the provider could
+refuse them. The pause is global, not per job: a failure says something about
+the provider, not about the conversation that happened to hit it.
+
+After the first failure no further model work is claimed for 5 seconds; each
+failed probe after that doubles the pause, up to 3 minutes. A pause admits one
+probe job at a time. The first success, or any change the user makes to the
+model configuration, ends it at once. Jobs not yet sent stay `pending`.
+"""
+
+from __future__ import annotations
+
+import logging
+import threading
+import time
+from collections.abc import Callable, Iterator
+from contextlib import contextmanager
+from dataclasses import dataclass
+from datetime import UTC, datetime, timedelta
+from typing import Any
+
+import httpx
+
+logger = logging.getLogger(__name__)
+
+BACKOFF_FIRST_SECONDS = 5.0
+BACKOFF_CAP_SECONDS = 180.0
+#: How long one probe may hold the pause open before another is admitted. A
+#: probe job that never reaches the provider (nothing to remember, a refusal
+#: before the SDK) reports nothing, and the queue must not wait on it forever.
+PROBE_HOLD_SECONDS = 30.0
+#: Requests already in flight when the pause began are refused without going
+#: out once this many failures in a row confirm it is not a one-off.
+REFUSE_IN_FLIGHT_AFTER = 2
+
+#: Statuses that say the configuration or the provider is wrong, not the one
+#: request: authentication, a missing model or route, throttling, a timeout
+#: and the provider's own failures. A 400/413/422 is about the request's
+#: content and is left to that job.
+_PROVIDER_STATUSES = {401: "model_auth_failed", 403: "model_auth_failed", 404: "model_not_found"}
+
+#: Every code a provider failure is recorded under: a job that failed with one
+#: of these waits for the provider instead of spending a retry.
+MODEL_FAILURE_CODES = frozenset(
+    {
+        "model_auth_failed",
+        "model_not_found",
+        "model_timeout",
+        "model_rate_limited",
+        "model_server_error",
+        "model_unreachable",
+        "model_transport_failed",
+    }
+)
+
+
+def backoff_seconds(level: int) -> float:
+    """The pause after the `level`-th failed attempt in a row (1-based)."""
+    if level < 1:
+        return 0.0
+    return min(BACKOFF_FIRST_SECONDS * float(2 ** min(level - 1, 16)), BACKOFF_CAP_SECONDS)
+
+
+def failure_code(status: int) -> str | None:
+    """The stable code for a provider HTTP status, or None if it is no provider failure."""
+    if status in _PROVIDER_STATUSES:
+        return _PROVIDER_STATUSES[status]
+    if status in {408, 504}:
+        return "model_timeout"
+    if status == 429:
+        return "model_rate_limited"
+    if status >= 500:
+        return "model_server_error"
+    return None
+
+
+def transport_failure_code(error: BaseException) -> str:
+    if isinstance(error, httpx.TimeoutException):
+        return "model_timeout"
+    if isinstance(error, httpx.ConnectError | httpx.NetworkError):
+        return "model_unreachable"
+    return "model_transport_failed"
+
+
+def request_kind(request: httpx.Request) -> str:
+    """`embedding` for the embeddings route, `chat` for everything else."""
+    return "embedding" if request.url.path.rstrip("/").endswith("/embeddings") else "chat"
+
+
+@dataclass(frozen=True)
+class ModelBackoffState:
+    #: When the pause ends; None when no pause is in force.
+    until: datetime | None
+    #: Failed attempts in a row.
+    failures: int
+    #: The last failure's stable code (`model_auth_failed`, ...).
+    last_error: str | None
+    profile_id: str | None
+
+
+class ModelBackoffRefusal(httpx.TransportError):
+    """A request refused locally because the provider is being given a rest."""
+
+
+@dataclass(eq=False)
+class ModelAttempt:
+    """One job's write, as the provider saw it.
+
+    `failure` is the code of the first provider failure (or local refusal)
+    that happened while this write was in flight, None if there was none.
+    """
+
+    failure: str | None = None
+
+
+class ModelBackoff:
+    """Process-wide circuit breaker for the active model profile.
+
+    Thread-safe: the transport records from the SDK's own loop thread, the
+    drain asks from its claim thread, and status reads from the event loop.
+    """
+
+    def __init__(
+        self,
+        *,
+        clock: Callable[[], float] = time.monotonic,
+        wall_clock: Callable[[], datetime] = lambda: datetime.now(UTC),
+    ) -> None:
+        self._clock = clock
+        self._wall_clock = wall_clock
+        self._lock = threading.Lock()
+        #: Writes in flight (`attempt`); never cleared by a reset.
+        self._attempts: set[ModelAttempt] = set()
+        self._reset_locked()
+
+    def _reset_locked(self) -> None:
+        #: Which kinds of request are failing (`chat`, `embedding`): a working
+        #: embedding endpoint says nothing about a chat model that is gone.
+        self._failing: set[str] = set()
+        self._level = 0
+        self._failures = 0
+        self._until = 0.0
+        self._probe_until = 0.0
+        self._last_error: str | None = None
+        self._profile_id: str | None = None
+
+    def reset(self, reason: str = "model_configuration_changed") -> None:
+        """Forget every failure: the user changed what is being called."""
+        with self._lock:
+            was_paused = self._failures > 0
+            self._reset_locked()
+        if was_paused:
+            logger.info("model_backoff_reset reason=%s", reason)
+
+    def record_success(self, profile_id: str | None = None, kind: str = "model") -> None:
+        with self._lock:
+            if self._failures == 0:
+                return
+            if profile_id is not None and self._profile_id not in {None, profile_id}:
+                return
+            self._failing.discard(kind)
+            if self._failing:
+                return
+            self._reset_locked()
+        logger.info("model_backoff_cleared profile_id=%s", profile_id)
+
+    def record_failure(self, code: str, profile_id: str | None = None, kind: str = "model") -> None:
+        now = self._clock()
+        with self._lock:
+            if profile_id is not None and self._profile_id not in {None, profile_id}:
+                # Another profile's history says nothing about this one.
+                self._reset_locked()
+            self._profile_id = profile_id
+            self._failing.add(kind)
+            self._mark_attempts_locked(code)
+            self._failures += 1
+            self._last_error = code
+            self._probe_until = 0.0
+            # Requests that were already out when the pause began fail too;
+            # they are the same outage, not a reason to wait longer.
+            if now >= self._until:
+                self._level += 1
+                self._until = now + backoff_seconds(self._level)
+            level, pause = self._level, self._until - now
+        logger.warning(
+            "model_backoff_failure error_code=%s level=%d pause_s=%.0f profile_id=%s",
+            code,
+            level,
+            pause,
+            profile_id,
+        )
+
+    @contextmanager
+    def attempt(self) -> Iterator[ModelAttempt]:
+        """Hold one job's write open, and learn whether the provider failed it.
+
+        Every provider failure and every local refusal while the write is in
+        flight is charged to it. A request cannot be traced to the job that
+        made it: the SDK sends embeddings from one shared batching worker, so
+        neither the calling thread nor a context variable identifies the job.
+        Charging every write then in flight can name a write the provider did
+        not fail (another job's request failed beside it); that write waits
+        for the provider and is retried with the rest. It can never miss the
+        write the provider did fail, which would spend that job's retries on
+        an outage.
+        """
+        record = ModelAttempt()
+        with self._lock:
+            self._attempts.add(record)
+        try:
+            yield record
+        finally:
+            with self._lock:
+                self._attempts.discard(record)
+
+    def record_refusal(self) -> str:
+        """A request refused locally; charged to the writes in flight like a failure."""
+        with self._lock:
+            code = self._last_error or "model_transport_failed"
+            self._mark_attempts_locked(code)
+        return code
+
+    def _mark_attempts_locked(self, code: str) -> None:
+        for record in self._attempts:
+            if record.failure is None:
+                record.failure = code
+
+    def paused(self) -> bool:
+        with self._lock:
+            return self._failures > 0 and self._clock() < self._until
+
+    def refuses_requests(self, kind: str = "model") -> bool:
+        """Whether a request of this kind should not go out at all right now.
+
+        Only the failing kind is refused: a chat model that is gone must not
+        take recall's embedding calls down with it.
+        """
+        with self._lock:
+            return (
+                kind in self._failing
+                and self._failures >= REFUSE_IN_FLIGHT_AFTER
+                and self._clock() < self._until
+            )
+
+    def allowance(self, *, kind: str | None = None) -> int | None:
+        """How many matching provider jobs may be claimed now.
+
+        0 while paused; once the pause is over, one probe at a time until it
+        reports or `PROBE_HOLD_SECONDS` pass. ``kind`` keeps a failed chat
+        model from pausing raw-only work that needs embeddings, while an
+        embedding outage still paces that work.
+        """
+        now = self._clock()
+        with self._lock:
+            if self._failures == 0 or (kind is not None and kind not in self._failing):
+                return None
+            if now < self._until or now < self._probe_until:
+                return 0
+            self._probe_until = now + PROBE_HOLD_SECONDS
+            return 1
+
+    def state(self) -> ModelBackoffState:
+        now = self._clock()
+        with self._lock:
+            remaining = self._until - now if self._failures else 0.0
+            return ModelBackoffState(
+                until=(
+                    self._wall_clock() + timedelta(seconds=remaining) if remaining > 0 else None
+                ),
+                failures=self._failures,
+                last_error=self._last_error,
+                profile_id=self._profile_id,
+            )
+
+
+def next_retry_at(app: Any, state: str, own: str | None) -> str | None:
+    """When a queued job is tried next: its own retry wait, or the provider's pause.
+
+    While the breaker pauses, nothing is claimed at all, so the pause holds
+    every queued job, whatever it last failed with.
+    """
+    if state not in {"accepted", "pending"}:
+        return None
+    backoff = getattr(getattr(app, "state", None), "model_backoff", None)
+    until = backoff.state().until if isinstance(backoff, ModelBackoff) else None
+    paused = until.isoformat() if until is not None else None
+    candidates = [value for value in (own, paused) if value]
+    return max(candidates) if candidates else None
+
+
+class BackedOffModelTransport(httpx.AsyncBaseTransport):
+    """Report each provider exchange to the breaker; refuse while it confirms a pause."""
+
+    def __init__(
+        self,
+        backoff: ModelBackoff,
+        *,
+        profile_id: str,
+        inner: httpx.AsyncBaseTransport | None = None,
+    ) -> None:
+        self.backoff = backoff
+        self.profile_id = profile_id
+        self.inner = inner or httpx.AsyncHTTPTransport(retries=0, trust_env=False)
+
+    async def handle_async_request(self, request: httpx.Request) -> httpx.Response:
+        kind = request_kind(request)
+        if self.backoff.refuses_requests(kind):
+            self.backoff.record_refusal()
+            raise ModelBackoffRefusal("model_backoff_active", request=request)
+        try:
+            response = await self.inner.handle_async_request(request)
+        except ModelBackoffRefusal:
+            raise
+        except httpx.TransportError as error:
+            self.backoff.record_failure(transport_failure_code(error), self.profile_id, kind)
+            raise
+        code = failure_code(response.status_code)
+        if code is not None:
+            self.backoff.record_failure(code, self.profile_id, kind)
+        elif response.status_code < 400:
+            self.backoff.record_success(self.profile_id, kind)
+        return response
+
+    async def aclose(self) -> None:
+        await self.inner.aclose()

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

@@ -423,7 +423,7 @@ class ModelProber:
         ModelProbeOperations(self.store).assert_no_pending(profile.profile_id)
         # Measuring embedding width may create a new profile version of its own.
         input_revision = profile.revision
-        profile = self._record_embedding_width(profile, stages)
+        profile, _switch_required = self._record_embedding_width(profile, stages)
         self.store.record_capabilities(
             profile.profile_id,
             expected_revision=profile.revision,
@@ -442,32 +442,55 @@ class ModelProber:
         self,
         profile: ModelProfile,
         stages: tuple[ProbeStage, ...],
-    ) -> ModelProfile:
-        """Store the measured vector width on the profile.
+    ) -> tuple[ModelProfile, bool]:
+        """Store the measured vector width on the profile, unless it moves the space.
 
         The graph store fixes its embedding column width when it is first
         created, so guessing this leaves every relation write failing later.
+        On the profile that fills the live embedding space a different width
+        is not recorded: it would name other collections (B2). True when the
+        width was refused that way: using it takes an embedding switch, which
+        the switch plan reports (the probe result keeps its shape).
         """
-        width = next(
-            (
-                stage.embedding_dimensions
-                for stage in stages
-                if stage.stage == "embedding" and stage.embedding_dimensions
-            ),
-            None,
-        )
+        width = measured_width(stages)
         if width is None or width == profile.embedding_dimensions:
-            return profile
-        return self.store.update(
-            profile.profile_id,
-            ModelProfilePatch(
-                expected_revision=profile.revision,
-                embedding_dimensions=width,
+            return profile, False
+        from one_memory.embedding_spaces import EmbeddingSpaceStore, probe_width_allowed
+
+        spaces = EmbeddingSpaceStore(self.store.database_path)
+        with spaces.transaction() as connection:
+            allowed = probe_width_allowed(
+                connection,
+                profile.profile_id,
+                width,
+                data_dir=self.store.database_path.parent,
+            )
+        if not allowed:
+            return profile, True
+        return (
+            self.store.update(
+                profile.profile_id,
+                ModelProfilePatch(
+                    expected_revision=profile.revision,
+                    embedding_dimensions=width,
+                ),
+                self.secrets,
             ),
-            self.secrets,
+            False,
         )
 
 
+def measured_width(stages: tuple[ProbeStage, ...]) -> int | None:
+    return next(
+        (
+            stage.embedding_dimensions
+            for stage in stages
+            if stage.stage == "embedding" and stage.embedding_dimensions
+        ),
+        None,
+    )
+
+
 def _models_request(
     profile: ModelProfile,
     secret: str | None,

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

@@ -13,6 +13,7 @@ from pydantic import BaseModel, ConfigDict, Field, field_validator
 
 from one_memory.database import take_the_write_lock_first
 from one_memory.database_access import main_database
+from one_memory.embedding_spaces import probe_width_allowed
 from one_memory.memory_server.migrations import model_probe_operations_ddl
 from one_memory.model_probe import ModelProbeResult, ProbeStage
 from one_memory.model_profiles import ModelCapabilities, ModelProfileStore
@@ -349,7 +350,19 @@ class ModelProbeOperations:
             )
             revision = profile["revision"]
             now = datetime.now(UTC).isoformat()
-            if width is not None and width != profile["embedding_dimensions"]:
+            # The profile that fills the live embedding space records only the
+            # space's own width: another one would move writes to new, empty
+            # collections (B2). Using it takes an embedding switch.
+            if (
+                width is not None
+                and width != profile["embedding_dimensions"]
+                and probe_width_allowed(
+                    db,
+                    profile["profile_id"],
+                    width,
+                    data_dir=self.store.database_path.parent,
+                )
+            ):
                 revision += 1
                 db.execute(
                     "UPDATE model_profiles SET embedding_dimensions=?,revision=? "

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

@@ -703,10 +703,16 @@ class ModelProfileStore:
                     }
                 )
             # User changes to service/model/credentials need a new explicit activation.
-            # Probe-discovered embedding width alone retains its existing behavior.
+            # Probe-discovered embedding width alone retains its existing behavior;
+            # replacing one declared width with another is a new embedding
+            # identity, and activating it goes through an embedding switch.
             deactivate = (
                 patch.api_key is not None
                 or patch.clear_api_key
+                or (
+                    row["embedding_dimensions"] is not None
+                    and next_values["embedding_dimensions"] != row["embedding_dimensions"]
+                )
                 or any(
                     row[key] != next_values[key]
                     for key in (

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

@@ -4,9 +4,10 @@ from collections.abc import Iterator
 from contextlib import contextmanager
 from datetime import UTC, datetime
 from pathlib import Path
-from typing import Any
+from typing import Any, Literal
+from uuid import UUID
 
-from pydantic import BaseModel, ConfigDict
+from pydantic import BaseModel, ConfigDict, Field, field_validator
 
 from one_memory.database import (
     take_the_write_lock_first,
@@ -14,11 +15,25 @@ from one_memory.database import (
 from one_memory.database_access import main_database
 
 #: Schema owned by `memory_server.migrations` (migration 12). No local copy.
-from one_memory.memory_server.migrations import onboarding_state_ddl
-from one_memory.memory_server.sql_compat import execute, is_mysql
+from one_memory.memory_server.migrations import (
+    onboarding_progress_ddl,
+    onboarding_state_ddl,
+)
+from one_memory.memory_server.sql_compat import execute, is_mysql, row_to_dict
 from one_memory.memory_server.store_binding import store_for
 
 SCHEMA = onboarding_state_ddl("sqlite")
+ONBOARDING_COLUMNS = (
+    "singleton",
+    "status",
+    "selected_source_ids_json",
+    "started_at",
+    "completed_at",
+    "updated_at",
+    "mode_intent",
+    "setup_step",
+    "model_profile_id",
+)
 
 #: The start/complete upserts, per engine.
 #:
@@ -51,11 +66,13 @@ START_MYSQL = """
         updated_at = VALUES(updated_at)
 """
 COMPLETE_UPDATE_SQLITE = (
-    "UPDATE onboarding_state SET status = 'completed', completed_at = ?, updated_at = ? "
+    "UPDATE onboarding_state SET status = 'completed', completed_at = ?, updated_at = ?, "
+    "mode_intent = NULL, setup_step = NULL, model_profile_id = NULL "
     "WHERE singleton = 1"
 )
 COMPLETE_UPDATE_MYSQL = (
-    "UPDATE onboarding_state SET status = 'completed', completed_at = %s, updated_at = %s "
+    "UPDATE onboarding_state SET status = 'completed', completed_at = %s, updated_at = %s, "
+    "mode_intent = NULL, setup_step = NULL, model_profile_id = NULL "
     "WHERE singleton = 1"
 )
 COMPLETE_INSERT_SQLITE = (
@@ -71,13 +88,27 @@ COMPLETE_INSERT_MYSQL = (
 RESET_UPDATE_SQLITE = (
     "UPDATE onboarding_state SET status = 'not_started', "
     "selected_source_ids_json = '[]', started_at = NULL, completed_at = NULL, "
+    "mode_intent = NULL, setup_step = NULL, model_profile_id = NULL, "
     "updated_at = ? WHERE singleton = 1"
 )
 RESET_UPDATE_MYSQL = (
     "UPDATE onboarding_state SET status = 'not_started', "
     "selected_source_ids_json = '[]', started_at = NULL, completed_at = NULL, "
+    "mode_intent = NULL, setup_step = NULL, model_profile_id = NULL, "
     "updated_at = %s WHERE singleton = 1"
 )
+ENSURE_PROGRESS_SQLITE = (
+    "INSERT INTO onboarding_state ("
+    "singleton,status,selected_source_ids_json,started_at,completed_at,updated_at"
+    ") VALUES (1,'not_started','[]',NULL,NULL,?) "
+    "ON CONFLICT(singleton) DO NOTHING"
+)
+ENSURE_PROGRESS_MYSQL = (
+    "INSERT INTO onboarding_state ("
+    "singleton,status,selected_source_ids_json,started_at,completed_at,updated_at"
+    ") VALUES (1,'not_started','[]',NULL,NULL,%s) "
+    "ON DUPLICATE KEY UPDATE singleton=VALUES(singleton)"
+)
 
 
 class OnboardingState(BaseModel):
@@ -87,6 +118,35 @@ class OnboardingState(BaseModel):
     selected_source_ids: tuple[str, ...]
     started_at: datetime | None
     completed_at: datetime | None
+    mode_intent: Literal["lite", "pro"] | None
+    setup_step: Literal["review", "mode", "model"] | None
+    model_profile_id: str | None
+
+
+class OnboardingProgressUpdate(BaseModel):
+    """Only non-sensitive, resumable choices accepted from the onboarding UI."""
+
+    model_config = ConfigDict(frozen=True, extra="forbid")
+
+    mode_intent: Literal["lite", "pro"] | None = None
+    setup_step: Literal["review", "mode", "model"] | None = None
+    model_profile_id: str | None = Field(default=None, min_length=36, max_length=36)
+
+    @field_validator("model_profile_id")
+    @classmethod
+    def validate_model_profile_id(cls, value: str | None) -> str | None:
+        if value is None:
+            return None
+        try:
+            if str(UUID(value)) != value:
+                raise ValueError
+        except (ValueError, TypeError, AttributeError):
+            raise ValueError("invalid_model_profile_id") from None
+        return value
+
+
+class OnboardingCompletedError(RuntimeError):
+    pass
 
 
 class OnboardingStore:
@@ -103,12 +163,31 @@ class OnboardingStore:
         """
         with self._connect(initialize=True) as connection:
             execute(connection, is_mysql(self._store), SCHEMA)
+            if not is_mysql(self._store):
+                existing = {
+                    str(row[1]) for row in connection.execute("PRAGMA table_info(onboarding_state)")
+                }
+                statements = tuple(
+                    statement.strip()
+                    for statement in onboarding_progress_ddl("sqlite").split(";")
+                    if statement.strip()
+                )
+                for column, statement in zip(
+                    ("mode_intent", "setup_step", "model_profile_id"),
+                    statements,
+                    strict=True,
+                ):
+                    if column not in existing:
+                        connection.execute(statement)
 
     def get(self) -> OnboardingState:
         mysql = is_mysql(self._store)
         with self._connect() as connection:
             row = execute(
-                connection, mysql, "SELECT * FROM onboarding_state WHERE singleton = 1"
+                connection,
+                mysql,
+                "SELECT " + ", ".join(ONBOARDING_COLUMNS) + " "
+                "FROM onboarding_state WHERE singleton = 1",
             ).fetchone()
         if row is None:
             return OnboardingState(
@@ -116,8 +195,11 @@ class OnboardingStore:
                 selected_source_ids=(),
                 started_at=None,
                 completed_at=None,
+                mode_intent=None,
+                setup_step=None,
+                model_profile_id=None,
             )
-        return self._to_state(row)
+        return self._to_state(row, mysql=mysql)
 
     def start(self, source_ids: tuple[str, ...]) -> OnboardingState:
         now = datetime.now(UTC).isoformat()
@@ -150,6 +232,43 @@ class OnboardingStore:
                 )
         return self.get()
 
+    def update_progress(self, update: OnboardingProgressUpdate) -> OnboardingState:
+        fields = tuple(
+            field
+            for field in ("mode_intent", "setup_step", "model_profile_id")
+            if field in update.model_fields_set
+        )
+        if not fields:
+            state = self.get()
+            if state.status == "completed":
+                raise OnboardingCompletedError("onboarding_completed")
+            return state
+        mysql = is_mysql(self._store)
+        placeholder = "%s" if mysql else "?"
+        assignments = [f"{field} = {placeholder}" for field in fields]
+        assignments.append(f"updated_at = {placeholder}")
+        values = [getattr(update, field) for field in fields]
+        now = datetime.now(UTC).isoformat()
+        values.append(now)
+        with self._connect(writing=True) as connection:
+            execute(
+                connection,
+                mysql,
+                ENSURE_PROGRESS_MYSQL if mysql else ENSURE_PROGRESS_SQLITE,
+                (now,),
+            )
+            updated = execute(
+                connection,
+                mysql,
+                "UPDATE onboarding_state SET "
+                + ", ".join(assignments)
+                + " WHERE singleton = 1 AND status != 'completed'",
+                tuple(values),
+            )
+            if updated.rowcount != 1:
+                raise OnboardingCompletedError("onboarding_completed")
+        return self.get()
+
     def reset(self) -> OnboardingState:
         """Return onboarding to its first-run state, touching nothing else.
 
@@ -207,33 +326,53 @@ class OnboardingStore:
             yield connection
 
     @staticmethod
-    def _to_state(row: Any) -> OnboardingState:
-        """Read the row by position, so it works for `sqlite3.Row` and tuples.
-
-        `SELECT *` makes the column order part of the contract here, which is
-        why the query is `SELECT *` and the indices are named: relying on
-        `row["..."]` would only work on SQLite, and relying on position alone
-        without saying which column is which would be unreadable.
-
-        Timestamps are a further engine difference: SQLite hands back the stored
-        string, MySQL hands back a `datetime`. Accepting both is not padding —
-        parsing a `datetime` raises, and treating a string as one would be
-        silently wrong.
-        """
-        # singleton, status, selected_source_ids_json, started_at, completed_at, updated_at
-        raw_ids = json.loads(row[2])
+    def _to_state(row: Any, *, mysql: bool) -> OnboardingState:
+        """Map SQLite rows and MySQL tuples through the shared database adapter."""
+        if mysql:
+            if not isinstance(row, tuple):
+                raise ValueError("onboarding_row_shape_invalid")
+        elif not isinstance(row, sqlite3.Row):
+            raise ValueError("onboarding_row_shape_invalid")
+        if len(row) != len(ONBOARDING_COLUMNS):
+            raise ValueError("onboarding_row_shape_invalid")
+        if mysql:
+            values = dict(zip(ONBOARDING_COLUMNS, tuple(row), strict=True))
+        else:
+            values = row_to_dict(row, ONBOARDING_COLUMNS, mysql=False)
+            if set(values) != set(ONBOARDING_COLUMNS):
+                raise ValueError("onboarding_row_shape_invalid")
+        _as_datetime(values["updated_at"], mysql=mysql, nullable=False)
+        raw_ids = json.loads(values["selected_source_ids_json"])
         return OnboardingState(
-            status=row[1],
+            status=values["status"],
             selected_source_ids=tuple(value for value in raw_ids if isinstance(value, str)),
-            started_at=_as_datetime(row[3]),
-            completed_at=_as_datetime(row[4]),
+            started_at=_as_datetime(values["started_at"], mysql=mysql),
+            completed_at=_as_datetime(values["completed_at"], mysql=mysql),
+            mode_intent=values["mode_intent"],
+            setup_step=values["setup_step"],
+            model_profile_id=values["model_profile_id"],
         )
 
 
-def _as_datetime(value: object) -> datetime | None:
-    """SQLite stores these as text; MySQL returns `datetime` objects."""
-    if value is None or value == "":
+def _as_datetime(
+    value: object,
+    *,
+    mysql: bool,
+    nullable: bool = True,
+) -> datetime | None:
+    """Validate the engine's timestamp shape and normalize it to UTC."""
+    if value is None:
+        if not nullable:
+            raise ValueError("onboarding_datetime_invalid")
         return None
-    if isinstance(value, datetime):
-        return value
-    return datetime.fromisoformat(str(value))
+    if mysql:
+        if not isinstance(value, datetime):
+            raise ValueError("onboarding_datetime_invalid")
+        parsed = value
+    else:
+        if not isinstance(value, str) or value == "":
+            raise ValueError("onboarding_datetime_invalid")
+        parsed = datetime.fromisoformat(value)
+    if parsed.tzinfo is None:
+        return parsed.replace(tzinfo=UTC)
+    return parsed.astimezone(UTC)

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

@@ -0,0 +1,123 @@
+"""Turn-level read projection for SDK raw batches.
+
+HY keeps several complete conversation turns in one L1 raw node so model
+writes stay batched. Product readers must not expose that storage batch as
+one conversation item: this module gives every contained turn a stable
+identity while retaining the parent raw id for traceability.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import re
+from dataclasses import dataclass
+
+from one_memory.hy_sdk_types import HySdkRawRecord, raw_turn_messages
+
+
+@dataclass(frozen=True)
+class RawDisplayTurn:
+    turn_id: str
+    turn_index: int
+    turn_count: int
+    content: str
+    messages: tuple[tuple[str, str], ...]
+
+
+def raw_display_turns(record: HySdkRawRecord) -> tuple[RawDisplayTurn, ...]:
+    """Split one stored raw batch into user-opened turns.
+
+    A user message opens a new turn; assistant/tool/system messages stay with
+    that user message until the next user message. Legacy content with no user
+    marker remains one turn so it never disappears from the product.
+    """
+    messages = raw_turn_messages(record.content)
+    grouped: list[list[tuple[str, str]]] = []
+    for message in messages:
+        role, _ = message
+        has_user = bool(grouped) and any(item[0] == "user" for item in grouped[-1])
+        if not grouped or (role == "user" and has_user):
+            grouped.append([message])
+        else:
+            grouped[-1].append(message)
+    if not grouped:
+        grouped = [[("", record.content)]]
+
+    digest = hashlib.sha256(record.raw_id.encode("utf-8")).hexdigest()
+    count = len(grouped)
+    return tuple(
+        RawDisplayTurn(
+            turn_id=f"raw-turn:{digest}:{index}",
+            turn_index=index,
+            turn_count=count,
+            content=_turn_content(turn),
+            messages=tuple(turn),
+        )
+        for index, turn in enumerate(grouped)
+    )
+
+
+def _turn_content(messages: list[tuple[str, str]]) -> str:
+    return "\n".join(f"[{role}]: {content}" if role else content for role, content in messages)
+
+
+def raw_prefix_added(
+    cached: tuple[tuple[str, str | None], ...],
+    current: tuple[tuple[str, str | None], ...],
+    cached_total: int,
+    current_total: int,
+) -> int | None:
+    """How many raws were only put on top of a cached newest-first listing.
+
+    `cached` and `current` are the (raw id, status) of the first page of each
+    listing. The answer is a count when the current page is the cached one
+    with new raws before it and nothing else changed; None when anything else
+    happened (a delete, a status change, a raw dated into the middle), which
+    needs a full re-listing.
+    """
+    added = current_total - cached_total
+    if added <= 0 or added > len(current):
+        return None
+    kept = current[added:]
+    if not kept and cached_total:
+        return None
+    if kept != cached[: len(kept)]:
+        return None
+    return added
+
+
+_WORD = re.compile(r"\w+")
+
+
+def _query_terms(query: str) -> frozenset[str]:
+    """Words of the query, plus character bigrams of unspaced (CJK) words."""
+    terms: set[str] = set()
+    for word in _WORD.findall(query.casefold()):
+        terms.add(word)
+        if not word.isascii() and len(word) > 1:
+            terms.update(word[index : index + 2] for index in range(len(word) - 1))
+    return frozenset(terms)
+
+
+def turns_for_hit(turns: tuple[RawDisplayTurn, ...], query: str) -> tuple[RawDisplayTurn, ...]:
+    """The turns one semantic raw hit shows, never none while it has turns.
+
+    The SDK embeds a whole raw batch, so a vector hit cannot say which of its
+    turns matched. Every turn containing the query text is shown; when none
+    does, the turn sharing the most query terms (the earliest on a tie) stands
+    for the hit. A semantic hit is never dropped for lacking the literal query.
+    """
+    if not turns:
+        return ()
+    needle = query.casefold().strip()
+    if needle:
+        lexical = tuple(turn for turn in turns if needle in turn.content.casefold())
+        if lexical:
+            return lexical
+    terms = _query_terms(query)
+
+    def overlap(turn: RawDisplayTurn) -> tuple[int, int]:
+        content = turn.content.casefold()
+        return (sum(1 for term in terms if term in content), -turn.turn_index)
+
+    return (max(turns, key=overlap),)

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

@@ -135,6 +135,8 @@ class RecallReceipt(BaseModel):
     #: exists yet (`fallback_reason`). Raw hits are excerpts, not memories.
     mode: Literal["memory", "raw"] = "memory"
     fallback_reason: Literal["model_unavailable", "no_memories"] | None = None
+    #: Whose memories were searched: the request's `user_id`, else `local`.
+    user_id: str = DEFAULT_USER_ID
 
 
 class RecallTarget(Protocol):

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

@@ -32,6 +32,19 @@ FallbackReason = Literal["model_unavailable", "no_memories"]
 #: caller). An empty set means the caller may read no raw conversation.
 RawSources = frozenset[str] | None
 
+#: What the whole recall request may take beyond the caller's own
+#: `timeout_ms`: the search keeps to that budget, but the checks around it
+#: (is a model configured, is the library empty, which raw sources) and the
+#: raw fallback need a little room of their own. Well under the broker's 15 s
+#: wait on Core, so a slow Core answers 504 before the broker gives up.
+RECALL_TOTAL_GRACE_SECONDS = 3.0
+RECALL_TOTAL_CEILING_SECONDS = 12.0
+
+
+def recall_total_timeout_seconds(timeout_ms: int) -> float:
+    """The most one recall request may take from start to answer."""
+    return min(timeout_ms / 1_000 + RECALL_TOTAL_GRACE_SECONDS, RECALL_TOTAL_CEILING_SECONDS)
+
 
 async def recall_with_fallback(
     request: RecallRequest,

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

@@ -33,7 +33,7 @@ from one_memory.model_profiles import (
 )
 from one_memory.sdk_search_options import SdkSearchFilters, SearchLane
 from one_memory.secrets import SecretStore, SecretStoreUnavailableError
-from one_memory.user_scope import owns
+from one_memory.user_scope import DEFAULT_USER_ID, owns
 
 _NO_GROUNDING = "现有记忆不足以回答这个问题。"
 _GROUNDING_LIMIT = 6
@@ -62,6 +62,8 @@ class SdkMemoryAnswer(BaseModel):
     answer: str
     memories: tuple[SdkAskMemory, ...]
     mode: Literal["generated", "extractive", "empty"]
+    #: Whose memories answered: the request's `user_id`, else `local`.
+    user_id: str = DEFAULT_USER_ID
 
 
 class _PromptMemory:

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

@@ -25,7 +25,7 @@ from one_memory.hy_runtime_config import HY_MEMORY_READER
 from one_memory.hy_sdk_runtime import SdkClientHandle, sdk_relevance_floor
 from one_memory.hy_sdk_types import HySdkError, parse_sdk_search
 from one_memory.memory_queue import ExtractionWindowPreset, QueueDepths
-from one_memory.memory_server.durable_queue import COMPLETED, DurableWriteQueue
+from one_memory.memory_server.durable_queue import WAITING_FOR_MODEL, DurableWriteQueue
 from one_memory.sdk_write_processor import SdkWriteCoordinator
 from one_memory.semantic_deadline import SemanticMemoryHit
 
@@ -34,6 +34,10 @@ _STABLE_CODE = re.compile(r"[a-z][a-z0-9_]{0,95}")
 
 logger = logging.getLogger(__name__)
 
+#: Jobs not yet run that a suspended source holds back.
+_WAITING_STATES = frozenset({"pending", "waiting_for_model", "waiting_for_permission"})
+_WAITING_SQL = ",".join(f"'{state}'" for state in sorted(_WAITING_STATES))
+
 
 class SdkMemoryRuntime:
     """Product services that remain after legacy task/governance writes retire."""
@@ -47,10 +51,20 @@ class SdkMemoryRuntime:
         extraction_settings: ExtractionSettingsStore,
         data_dir: Path,
         memory_mode: Callable[[], str] = lambda: "pro",
+        writes_open: Callable[[], bool] = lambda: True,
+        source_active: Callable[[str], bool] = lambda _source_key: True,
     ) -> None:
         self.coordinator = coordinator
         #: The SDK mode, for the graph store's path (`hy_graph_admin`).
         self.memory_mode = memory_mode
+        #: False while an embedding switch pauses model writes.
+        self.writes_open = writes_open
+        #: Whether a queue lane's source may still become memories: the same
+        #: question the drain's claim asks of it. A lane that is off (the
+        #: user turned the source off, or its grant was revoked) has its
+        #: waiting jobs suspended: kept, never claimed, and not counted as
+        #: pending until the source is on again.
+        self.source_active = source_active
         self.read_handle = read_handle
         self.write_queue = write_queue
         self.extraction_settings = extraction_settings
@@ -111,6 +125,8 @@ class SdkMemoryRuntime:
             )
 
     async def digest(self) -> dict[str, object]:
+        if not self.writes_open():
+            raise HySdkError("embedding_switch_in_progress")
         async with self.coordinator.use_client() as client:
             try:
                 raw = await asyncio.to_thread(
@@ -151,12 +167,14 @@ class SdkMemoryRuntime:
             if str(error) == "model_profile_not_active":
                 return None
             raise
+        space = await self.coordinator.live_space()
         return await asyncio.to_thread(
             inspect_profile_graph_width,
             profile,
             api_key=secret,
             data_dir=self.data_dir,
             mode=self.memory_mode(),
+            graph_dir=space.graph_dir if space is not None and space.graph_dir else "graph",
         )
 
     async def decide_graph_width(
@@ -167,6 +185,7 @@ class SdkMemoryRuntime:
             profile, secret = await self.coordinator.active_profile_credentials()
         except RuntimeError as error:
             raise HySdkError(str(error)) from error
+        space = await self.coordinator.live_space()
         return await asyncio.to_thread(
             decide_profile_graph_width,
             profile,
@@ -174,6 +193,7 @@ class SdkMemoryRuntime:
             data_dir=self.data_dir,
             decision=decision,
             mode=self.memory_mode(),
+            graph_dir=space.graph_dir if space is not None and space.graph_dir else "graph",
         )
 
     @asynccontextmanager
@@ -183,6 +203,8 @@ class SdkMemoryRuntime:
         Callers record these against the edit or deletion instead of failing
         the request that already committed it.
         """
+        if not self.writes_open():
+            raise HySdkError("embedding_switch_in_progress")
         async with AsyncExitStack() as stack:
             try:
                 client = await stack.enter_async_context(self.coordinator.use_client())
@@ -230,22 +252,11 @@ class SdkMemoryRuntime:
         now = datetime.now(UTC)
         fresh_since = (now - timedelta(days=7)).isoformat()
         with main_database(self.write_queue.database_path).read() as database:
-            fresh = int(
-                database.execute(
-                    "SELECT COUNT(*) FROM memory_write_jobs "
-                    "WHERE state IN ('pending','waiting_for_model','waiting_for_permission') "
-                    "AND event_at>=?",
-                    (fresh_since,),
-                ).fetchone()[0]
-            )
-            backlog = int(
-                database.execute(
-                    "SELECT COUNT(*) FROM memory_write_jobs "
-                    "WHERE state IN ('pending','waiting_for_model','waiting_for_permission') "
-                    "AND event_at<?",
-                    (fresh_since,),
-                ).fetchone()[0]
-            )
+            rows = database.execute(
+                "SELECT source_key,event_at>=? AS fresh,COUNT(*) FROM memory_write_jobs "
+                f"WHERE state IN ({_WAITING_SQL}) GROUP BY source_key,fresh",
+                (fresh_since,),
+            ).fetchall()
             recent = tuple(
                 datetime.fromisoformat(str(row[0]))
                 for row in database.execute(
@@ -253,6 +264,9 @@ class SdkMemoryRuntime:
                     "ORDER BY updated_at DESC LIMIT 8"
                 )
             )
+        active = self._active_lanes({str(row[0]) for row in rows})
+        fresh = sum(int(row[2]) for row in rows if str(row[0]) in active and row[1])
+        backlog = sum(int(row[2]) for row in rows if str(row[0]) in active and not row[1])
         return QueueDepths(fresh=fresh, backlog=backlog, recent_completions=recent)
 
     def active_depths(self) -> tuple[int, int]:
@@ -265,13 +279,27 @@ class SdkMemoryRuntime:
         return running, running
 
     def status_counts(self) -> dict[str, int]:
+        """Jobs per state, with a suspended source's waiting jobs as `suspended`.
+
+        Those jobs keep their state in the table: suspension is the source's
+        switch, not the row's, so turning the source back on is all it takes
+        for the drain to claim them again, and nothing is moved or deleted.
+        """
         with main_database(self.write_queue.database_path).read() as database:
-            return {
-                str(row[0]): int(row[1])
-                for row in database.execute(
-                    "SELECT state,COUNT(*) FROM memory_write_jobs GROUP BY state"
-                )
-            }
+            rows = database.execute(
+                "SELECT source_key,state,COUNT(*) FROM memory_write_jobs GROUP BY source_key,state"
+            ).fetchall()
+        active = self._active_lanes({str(row[0]) for row in rows if str(row[1]) in _WAITING_STATES})
+        counts: dict[str, int] = {}
+        for source_key, state, count in rows:
+            name = str(state)
+            if name in _WAITING_STATES and str(source_key) not in active:
+                name = "suspended"
+            counts[name] = counts.get(name, 0) + int(count)
+        return counts
+
+    def _active_lanes(self, lanes: set[str]) -> set[str]:
+        return {lane for lane in lanes if self.source_active(lane)}
 
     def manual_batch_progress(self) -> tuple[int, int]:
         return 0, 0
@@ -280,33 +308,11 @@ class SdkMemoryRuntime:
         del task_ids
         return []
 
-    async def reconcile_unknown_outputs(
-        self,
-        *,
-        limit: int = 128,
-        exclude_error_codes: tuple[str, ...] = (),
-    ) -> int:
-        reconciled = 0
-        for job in await asyncio.to_thread(
-            self.write_queue.unknown_jobs,
-            limit=limit,
-            exclude_error_codes=exclude_error_codes,
-        ):
-            receipt = await self.coordinator.inquire_write_outcome(job.request_id)
-            if receipt is None:
-                continue
-            await asyncio.to_thread(
-                self.write_queue.settle,
-                job.job_id,
-                state=COMPLETED,
-                sdk_raw_ids=receipt.raw_ids,
-                sdk_memory_ids=receipt.memory_ids,
-            )
-            reconciled += 1
-        return reconciled
-
     async def resume_allowed(self) -> None:
-        await asyncio.to_thread(self.write_queue.readmit_parked)
+        await asyncio.to_thread(
+            self.write_queue.readmit_parked,
+            states=(WAITING_FOR_MODEL,),
+        )
 
     def accepted_backfill_status(self) -> None:
         return None

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

@@ -222,13 +222,34 @@ def runtime_sdk_client(
             raise DataPlaneMigrationError("sdk_migration_secure_storage_unavailable") from None
         if secret is None:
             raise DataPlaneMigrationError("sdk_migration_model_secret_unavailable")
-    lease = acquire_client(profile, api_key=secret, data_dir=data_dir)
+    # The registry's live space when this home has one and the profile fills
+    # it; otherwise the space the profile named before the registry existed.
+    # A switch in progress never changes it: the profile and the live space
+    # change together, at the switch's commit.
+    space = live_space_for(database_path, profile)
+    lease = (
+        acquire_client(profile, space, api_key=secret, data_dir=data_dir)
+        if space is not None
+        else acquire_client(profile, api_key=secret, data_dir=data_dir)
+    )
     try:
         yield lease.client
     finally:
         lease.close()
 
 
+def live_space_for(database_path: Path, profile: ModelProfileSnapshot) -> Any:
+    """The live embedding space `profile` reads, or None to derive it from the profile."""
+    from one_memory.embedding_spaces import embedding_identity, read_live_space
+
+    space = read_live_space(database_path)
+    if space is None or space.identity is None:
+        return None
+    if not embedding_identity(profile).matches(space.identity):
+        return None
+    return space
+
+
 def verify_readback(
     client: Any, legacy: LegacyMemoryIds, *, chat_missing_before_migration: int = 0
 ) -> ReadbackReport:

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

@@ -1,20 +1,25 @@
-"""The read client, kept in the embedding space the active profile writes to.
+"""The read client, kept in the live embedding space.
 
 Every read used to open the built-in 512-dim collection while writes followed
-the active profile, so a custom embedding read an empty space (#242). This
-handle opens the active profile's `retrieval_view` instead, and the built-in
-space only when no profile is active.
+the active profile, so a custom embedding read an empty space (#242). Reads
+now open the space the registry pins as live (`embedding_spaces`), which is
+the space writes fill. The embedding that reaches it is the active profile's
+when its model and width are the space's -- a new endpoint for the same model
+keeps the space -- and otherwise the profile version that filled the space
+(the built-in model for the built-in space). A switch that is still running
+never changes this: reads keep serving the old space until its commit.
 
-A profile change builds a new client and retires the old one; a retired client
-is closed once no task still uses it, as `SdkWriteCoordinator` does for writes
-(#218). A use is the task that asked for the client: callers keep their
-`client = await handle.client()` shape, and the use ends with that task (one
-HTTP request, one retention pass).
+A change of space or profile builds a new client and retires the old one; a
+retired client is closed once no task still uses it, as `SdkWriteCoordinator`
+does for writes (#218). A use is the task that asked for the client: callers
+keep their `client = await handle.client()` shape, and the use ends with that
+task (one HTTP request, one retention pass).
 
 The memory mode (lite / pro / ultra) is fixed per SDK client, so a mode change
 rebuilds and retires the same way, and so do the SDK features
-(`memory_features`): handles are keyed by (profile, mode, features). Neither
-mode nor features names a collection; both are separate client parameters.
+(`memory_features`) and the SDK prompt language (`ui_language`): handles are
+keyed by (space, profile, mode, features, language). None of mode, features
+or language names a collection; each is a separate client parameter.
 """
 
 from __future__ import annotations
@@ -24,23 +29,35 @@ from collections.abc import Callable
 from pathlib import Path
 from typing import Any
 
+from one_memory.background_work import in_sdk_read
+from one_memory.embedding_health import EmbeddingGuardedClient, EmbeddingHealth
+from one_memory.embedding_spaces import (
+    EmbeddingSpace,
+    EmbeddingSpaceStore,
+    embedding_identity,
+    registry_for,
+)
 from one_memory.hy_graph_admin import effective_memory_mode
 from one_memory.hy_sdk_runtime import (
     BUILTIN_RETRIEVAL_PROFILE_ID,
     SdkClientHandle,
     builtin_retrieval_snapshot,
+    embedding_endpoint,
+    language_kwargs,
     retrieval_view,
 )
 from one_memory.hy_sdk_types import HySdkRuntimeError
 from one_memory.memory_features import FeatureOverrides
-from one_memory.model_profiles import ModelProfileStore, ProviderKind
+from one_memory.model_profiles import ModelProfileSnapshot, ModelProfileStore, ProviderKind
 from one_memory.secrets import SecretStore, SecretStoreUnavailableError
 
 _BUILTIN = (BUILTIN_RETRIEVAL_PROFILE_ID, 0)
+#: (space id, profile id, revision, memory mode, features, SDK language)
+_HandleKey = tuple[str, str, int, str, FeatureOverrides, str | None]
 
 
 class ActiveProfileReadHandle(SdkClientHandle):
-    """An `SdkClientHandle` whose profile follows the active one."""
+    """An `SdkClientHandle` that follows the live space and its embedding."""
 
     def __init__(
         self,
@@ -50,6 +67,9 @@ class ActiveProfileReadHandle(SdkClientHandle):
         data_dir: Path,
         memory_mode: Callable[[], str] = effective_memory_mode,
         features: Callable[[], FeatureOverrides] = lambda: (),
+        spaces: EmbeddingSpaceStore | None = None,
+        health: EmbeddingHealth | None = None,
+        language: Callable[[], str | None] = lambda: None,
     ) -> None:
         super().__init__(builtin_retrieval_snapshot(), api_key=None, data_dir=data_dir)
         self.profiles = profiles
@@ -57,7 +77,13 @@ class ActiveProfileReadHandle(SdkClientHandle):
         self.data_dir = data_dir
         self.memory_mode = memory_mode
         self.current_features = features
-        self._handles: dict[tuple[str, int, str, FeatureOverrides], SdkClientHandle] = {}
+        self.current_language = language
+        #: None only for a profile store without a database (test doubles).
+        self.spaces = spaces if spaces is not None else registry_for(profiles)
+        self.health = health or EmbeddingHealth()
+        self._handles: dict[_HandleKey, SdkClientHandle] = {}
+        #: Whether an active profile version reads a space, per (profile, space).
+        self._matches: dict[tuple[str, int, str], bool] = {}
         #: Tasks in flight per handle; a retired handle closes at zero.
         self._uses: dict[SdkClientHandle, int] = {}
         self._retired: set[SdkClientHandle] = set()
@@ -65,22 +91,59 @@ class ActiveProfileReadHandle(SdkClientHandle):
         self._handle_lock = asyncio.Lock()
 
     async def client(self) -> Any:
-        profile = await asyncio.to_thread(self.profiles.active_identity) or _BUILTIN
-        identity = (*profile, self.memory_mode(), self.current_features())
+        handle = await self.current_handle()
+        return self._guarded(handle, await handle.client())
+
+    async def client_for_mode(self, mode: str) -> Any:
+        """Build/read with the caller's one mode snapshot, without rereading it."""
+        handle = await self.current_handle(mode=mode)
+        return self._guarded(handle, await handle.client())
+
+    def _guarded(self, handle: SdkClientHandle, client: Any) -> Any:
+        """A remote embedding's searches report `embedding_unavailable` (no fallback)."""
+        profile = getattr(handle, "profile", None)
+        if not isinstance(profile, ModelProfileSnapshot):
+            return client
+        endpoint = embedding_endpoint(profile)
+        if endpoint is None:
+            return client
+        space = handle.space
+        name_dims = space.name_dims if space is not None else profile.embedding_dimensions
+        return EmbeddingGuardedClient(
+            client,
+            lambda: self.health.available(
+                profile, endpoint=endpoint, name_dims=name_dims, api_key=handle.api_key
+            ),
+        )
+
+    async def current_handle(self, *, mode: str | None = None) -> SdkClientHandle:
+        """The handle of the live space, held for the asking task."""
+        space, identity = await in_sdk_read(self._resolve)
+        selected_mode, features = mode or self.memory_mode(), self.current_features()
+        language = self.current_language()
+        key = (
+            space.space_id if space is not None else "",
+            *identity,
+            selected_mode,
+            features,
+            language,
+        )
         async with self._handle_lock:
-            handle = self._handles.get(identity)
+            handle = self._handles.get(key)
             if handle is None:
-                # Only on a change of profile: resolving a key can reach the
-                # system keychain, so it is not done on every read.
-                handle = await asyncio.to_thread(self._build, identity)
-                self._handles[identity] = handle
-            self._retired.update(value for key, value in self._handles.items() if key != identity)
-            self._handles = {identity: handle}
+                # Only on a change of space or profile: resolving a key can
+                # reach the system keychain, so it is not done on every read.
+                handle = await in_sdk_read(
+                    self._build, space, identity, selected_mode, features, language
+                )
+                self._handles[key] = handle
+            self._retired.update(value for name, value in self._handles.items() if name != key)
+            self._handles = {key: handle}
             unused = {value for value in self._retired if not self._uses.get(value)}
             self._retired -= unused
             self._hold(handle)
         await asyncio.gather(*(value.close() for value in unused))
-        return await handle.client()
+        return handle
 
     async def close(self) -> None:
         async with self._handle_lock:
@@ -88,6 +151,51 @@ class ActiveProfileReadHandle(SdkClientHandle):
             self._handles, self._retired, self._uses = {}, set(), {}
         await asyncio.gather(*(handle.close() for handle in handles), *self._closing)
 
+    async def close_idle(self) -> None:
+        """Retire every client; the unused close now, the rest when their task ends."""
+        async with self._handle_lock:
+            self._retired.update(self._handles.values())
+            self._handles = {}
+            unused = {value for value in self._retired if not self._uses.get(value)}
+            self._retired -= unused
+        await asyncio.gather(*(value.close() for value in unused))
+
+    def _resolve(self) -> tuple[EmbeddingSpace | None, tuple[str, int]]:
+        active = self.profiles.active_identity()
+        if self.spaces is None:
+            return None, active or _BUILTIN
+        space = self.spaces.live()
+        if space is None:
+            # A home this process has not bootstrapped yet: register what it
+            # already uses, under the name it already has.
+            space = self.spaces.bootstrap(
+                self.profiles.snapshot(*active) if active is not None else None
+            )
+        if active is not None and self._reads(active, space):
+            return space, active
+        if space.profile_id is not None and space.profile_revision is not None:
+            identity = (space.profile_id, space.profile_revision)
+            try:
+                self.profiles.snapshot(*identity)
+            except KeyError:
+                # Its endpoint and key went with the profile; the built-in
+                # model cannot read these vectors. Say so, never read wrong.
+                raise HySdkRuntimeError("embedding_space_profile_missing") from None
+            return space, identity
+        return space, _BUILTIN
+
+    def _reads(self, identity: tuple[str, int], space: EmbeddingSpace) -> bool:
+        key = (*identity, space.space_id)
+        known = self._matches.get(key)
+        if known is None:
+            if space.identity is None:
+                known = False
+            else:
+                profile = self.profiles.snapshot(*identity)
+                known = embedding_identity(profile).matches(space.identity)
+            self._matches[key] = known
+        return known
+
     def _hold(self, handle: SdkClientHandle) -> None:
         """Count a use of `handle` until the asking task finishes."""
         task = asyncio.current_task()
@@ -108,9 +216,18 @@ class ActiveProfileReadHandle(SdkClientHandle):
             self._closing.add(closing)
             closing.add_done_callback(self._closing.discard)
 
-    def _build(self, key: tuple[str, int, str, FeatureOverrides]) -> SdkClientHandle:
-        profile_id, revision, mode, features = key
-        identity = (profile_id, revision)
+    def _build(
+        self,
+        space: EmbeddingSpace | None,
+        identity: tuple[str, int],
+        mode: str,
+        features: FeatureOverrides = (),
+        language: str | None = None,
+    ) -> SdkClientHandle:
+        # Without a registry (a profile store with no database) the handle
+        # opens the space its profile names, exactly as before.
+        named: dict[str, Any] = {"space": space} if space is not None else {}
+        named.update(language_kwargs(language))
         if identity == _BUILTIN:
             return SdkClientHandle(
                 builtin_retrieval_snapshot(),
@@ -118,8 +235,9 @@ class ActiveProfileReadHandle(SdkClientHandle):
                 data_dir=self.data_dir,
                 mode=mode,
                 features=features,
+                **named,
             )
-        profile = self.profiles.snapshot(*identity)
+        profile: ModelProfileSnapshot = self.profiles.snapshot(*identity)
         view = retrieval_view(profile)
         secret: str | None = None
         # Only a remote OpenAI-compatible embedding sends the shared key.
@@ -131,5 +249,5 @@ class ActiveProfileReadHandle(SdkClientHandle):
             if secret is None:
                 raise HySdkRuntimeError("model_secret_unavailable")
         return SdkClientHandle(
-            view, api_key=secret, data_dir=self.data_dir, mode=mode, features=features
+            view, api_key=secret, data_dir=self.data_dir, mode=mode, features=features, **named
         )

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

@@ -73,6 +73,30 @@ def _stored_names(data_dir: Path, *, filled: bool = False) -> tuple[str, ...]:
     return tuple(sorted(str(row[0]) for row in rows))
 
 
+def filled_collection_names(data_dir: Path) -> tuple[str, ...]:
+    """Every vector collection holding at least one record. Read-only.
+
+    Safe beside a serving Core: it reads Chroma's own SQLite file, never the
+    client system the SDK shares.
+    """
+    return _stored_names(data_dir, filled=True)
+
+
+def stored_collection_width(data_dir: Path, name: str) -> int | None:
+    """The vector width Chroma fixed for `name` on its first add; None if unset."""
+    database = _vector_directory(data_dir) / "chroma.sqlite3"
+    if not database.is_file():
+        return None
+    with closing(sqlite3.connect(f"file:{database}?mode=ro", uri=True)) as connection:
+        try:
+            row = connection.execute(
+                "SELECT dimension FROM collections WHERE name=?", (name,)
+            ).fetchone()
+        except sqlite3.Error:
+            return None
+    return int(row[0]) if row is not None and row[0] is not None else None
+
+
 def legacy_vector_collections(
     data_dir: Path, profile: ModelProfileSnapshot
 ) -> tuple[tuple[str, str], ...]:

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

@@ -3,21 +3,90 @@
 from __future__ import annotations
 
 import asyncio
+import re
+import threading
 from collections.abc import AsyncIterator, Awaitable, Callable, Mapping, Sequence
 from contextlib import asynccontextmanager
 from dataclasses import dataclass
 from datetime import datetime
 from typing import Any
 
+from one_memory.background_work import in_sdk_write
+from one_memory.embedding_spaces import (
+    EmbeddingSpace,
+    EmbeddingSpaceStore,
+    embedding_identity,
+    registry_for,
+)
 from one_memory.hy_graph_admin import effective_memory_mode
-from one_memory.hy_sdk_runtime import SdkClientHandle, builtin_retrieval_snapshot
+from one_memory.hy_sdk_runtime import (
+    SdkClientHandle,
+    builtin_retrieval_snapshot,
+    language_kwargs,
+    retrieval_view,
+)
 from one_memory.imports.models import EvidenceContentKind, EvidenceOrigin, EvidenceRecord
 from one_memory.input_sanitization import sanitize_model_input
 from one_memory.memory_features import FeatureOverrides
-from one_memory.model_profiles import ModelProfileSnapshot, ModelProfileStore
+from one_memory.model_profiles import ModelProfileSnapshot, ModelProfileStore, ProviderKind
 from one_memory.secrets import SecretStore, SecretStoreUnavailableError
 
 PRODUCT_AGENT_ID = "all-apps"
+
+#: SDK request ids whose write call is running on a thread right now. A write
+#: the drain gave up on (its work ceiling, a lost lease) keeps running on its
+#: thread; it must not be re-run beside itself (`recover_unknown`).
+_IN_FLIGHT: set[str] = set()
+_IN_FLIGHT_LOCK = threading.Lock()
+
+
+def sdk_write_in_flight(request_id: str) -> bool:
+    with _IN_FLIGHT_LOCK:
+        return request_id in _IN_FLIGHT
+
+
+class _Tracked:
+    """One SDK write call, held in `_IN_FLIGHT` from submission until it ends.
+
+    If the wait for it is cancelled before a thread picked it up, it is
+    abandoned: it will not start, and it leaves `_IN_FLIGHT` at once.
+    """
+
+    def __init__(self, request_id: str, work: Callable[..., Any]) -> None:
+        self.request_id = request_id
+        self.work = work
+        self.started = False
+        self.abandoned = False
+        with _IN_FLIGHT_LOCK:
+            _IN_FLIGHT.add(request_id)
+
+    def __call__(self, *args: Any, **kwargs: Any) -> Any:
+        with _IN_FLIGHT_LOCK:
+            if self.abandoned:
+                raise RuntimeError("hy_memory_write_abandoned")
+            self.started = True
+        try:
+            return self.work(*args, **kwargs)
+        finally:
+            with _IN_FLIGHT_LOCK:
+                _IN_FLIGHT.discard(self.request_id)
+
+    def abandon(self) -> None:
+        with _IN_FLIGHT_LOCK:
+            if not self.started:
+                self.abandoned = True
+                _IN_FLIGHT.discard(self.request_id)
+
+
+async def _write(tracked_id: str, work: Callable[..., Any], /, *args: Any, **kwargs: Any) -> Any:
+    call = _Tracked(tracked_id, work)
+    try:
+        return await in_sdk_write(call, *args, **kwargs)
+    except asyncio.CancelledError:
+        call.abandon()
+        raise
+
+
 _MESSAGE_ROLES = frozenset({"user", "assistant", "tool"})
 _CONVERSATION_ROLES = frozenset({"user", "assistant"})
 
@@ -44,7 +113,7 @@ class SdkWriteProcessor:
         records: tuple[EvidenceRecord, ...],
         *,
         request_id: str,
-        before_hy_invocation: Callable[[], Awaitable[None]],
+        before_hy_invocation: Callable[[bool], Awaitable[None]],
     ) -> SdkWriteReceipt:
         if not records:
             raise RuntimeError("hy_memory_task_without_inputs")
@@ -71,8 +140,9 @@ class SdkWriteProcessor:
 
         if extracted and not self._lite:
             contents = [sanitize_model_input(record.verbatim) for record in records]
-            await before_hy_invocation()
-            result = await asyncio.to_thread(
+            await before_hy_invocation(True)
+            result = await _write(
+                request_id,
                 client.add_extracted,
                 contents,
                 user_id=scope.user_id,
@@ -98,8 +168,9 @@ class SdkWriteProcessor:
             ]
             if not messages:
                 raise RuntimeError("hy_memory_task_without_inputs")
-            await before_hy_invocation()
-            result = await asyncio.to_thread(
+            await before_hy_invocation(not self._lite)
+            result = await _write(
+                request_id,
                 client.add,
                 messages,
                 user_id=scope.user_id,
@@ -120,7 +191,7 @@ class SdkWriteProcessor:
         if not request_id:
             raise ValueError("request_id is required")
         client = await self._client_handle.client()
-        outcome = await asyncio.to_thread(client.get_write_outcome, request_id)
+        outcome = await in_sdk_write(client.get_write_outcome, request_id)
         if outcome is None:
             return None
         if not isinstance(outcome, Mapping):
@@ -147,15 +218,22 @@ class SdkWriteCoordinator:
     the SharedRuntime closed mid-`add`, the job failed with AttributeError
     after HY was invoked, and it was left `unknown`.
 
-    Handles are keyed by profile, memory mode and the SDK features
-    (`memory_features`), so a mode or feature change retires handles the same
-    way. In lite no generation model is needed: without an
-    active profile the built-in local embedder writes raw turns.
+    Handles are keyed by profile, memory mode, the SDK features
+    (`memory_features`) and the SDK language (`ui_language`), so a mode,
+    feature or language change retires handles the same way. In lite no
+    generation model is needed: without an active profile the built-in
+    local embedder writes raw turns.
 
     `exclusive_for_evolve(user_id)` keeps evolve and that user's writes
     apart: it waits for the user's write in flight, and while it runs that
     user's jobs are refused before the SDK is called
     (`memory_evolve_in_progress`), so the drain puts them back.
+
+    Writes go to the live embedding space only. An active profile whose
+    embedding (model and width) is not the live space's is refused with
+    `embedding_space_mismatch`: it used to open a new, empty collection.
+    While an embedding switch runs, `writes_open` is false and no write
+    starts (`embedding_switch_in_progress`); the job waits in the queue.
     """
 
     def __init__(
@@ -168,6 +246,9 @@ class SdkWriteCoordinator:
         sedimentation_enabled: Callable[[], bool],
         memory_mode: Callable[[], str] = effective_memory_mode,
         memory_features: Callable[[], FeatureOverrides] = lambda: (),
+        spaces: EmbeddingSpaceStore | None = None,
+        writes_open: Callable[[], bool] = lambda: True,
+        sdk_language: Callable[[], str | None] = lambda: None,
     ) -> None:
         self.profiles = profiles
         self.secrets = secrets
@@ -176,7 +257,12 @@ class SdkWriteCoordinator:
         self.sedimentation_enabled = sedimentation_enabled
         self.memory_mode = memory_mode
         self.memory_features = memory_features
-        self._handles: dict[tuple[str, int, str, FeatureOverrides], SdkClientHandle] = {}
+        self.sdk_language = sdk_language
+        #: Keyed by (profile id, revision, space id, memory mode, features,
+        #: SDK language).
+        self._handles: dict[
+            tuple[str, int, str, str, FeatureOverrides, str | None], SdkClientHandle
+        ] = {}
         #: Users evolve (or the graph backfill) is running for, the writes in
         #: flight per user, and one exclusive run per user at a time. Writes
         #: of one user still run side by side; only evolve waits for them.
@@ -184,6 +270,10 @@ class SdkWriteCoordinator:
         self._writing: dict[str, int] = {}
         self._writes_idle = asyncio.Condition()
         self._exclusive: dict[str, asyncio.Lock] = {}
+        #: None only for a profile store without a database (test doubles):
+        #: then every client opens the space its profile names, as before.
+        self.spaces = spaces if spaces is not None else registry_for(profiles)
+        self.writes_open = writes_open
         #: Uses in flight per handle; a retired handle closes at zero.
         self._uses: dict[SdkClientHandle, int] = {}
         self._retired: set[SdkClientHandle] = set()
@@ -194,10 +284,11 @@ class SdkWriteCoordinator:
         records: tuple[EvidenceRecord, ...],
         *,
         request_id: str,
-        before_hy_invocation: Callable[[], Awaitable[None]],
+        before_hy_invocation: Callable[[bool], Awaitable[None]],
     ) -> SdkWriteReceipt:
-        if not self.sedimentation_enabled():
-            raise RuntimeError("model_sedimentation_disabled")
+        if not self.writes_open():
+            # An embedding switch paused writes: the drain puts the job back.
+            raise RuntimeError("embedding_switch_in_progress")
         user_id = records[0].user_id if records else "local"
         if user_id in self._evolving:
             # Before any SDK call: the drain returns the job to pending.
@@ -205,9 +296,8 @@ class SdkWriteCoordinator:
         self._writing[user_id] = self._writing.get(user_id, 0) + 1
         try:
             async with self._active_handle() as handle:
-                return await SdkWriteProcessor(
-                    handle, lite=getattr(handle, "mode", None) == "lite"
-                ).process_sdk_job(
+                lite = getattr(handle, "mode", None) == "lite"
+                return await SdkWriteProcessor(handle, lite=lite).process_sdk_job(
                     records,
                     request_id=request_id,
                     before_hy_invocation=before_hy_invocation,
@@ -222,15 +312,15 @@ class SdkWriteCoordinator:
                 self._writes_idle.notify_all()
 
     async def retire_stale_handles(self) -> None:
-        """After a mode or feature change: retire handles built otherwise.
+        """After a mode, feature or language change: retire handles built otherwise.
 
         The idle ones close now. A handle still writing is closed when its
         last use ends (#218), so a write that started in the old mode, or
         with the old features, finishes in it.
         """
-        build = (self.memory_mode(), self.memory_features())
+        build = (self.memory_mode(), self.memory_features(), self.sdk_language())
         async with self._lock:
-            stale = {key: handle for key, handle in self._handles.items() if key[2:] != build}
+            stale = {key: handle for key, handle in self._handles.items() if key[3:] != build}
             for key in stale:
                 del self._handles[key]
             self._retired.update(stale.values())
@@ -250,8 +340,11 @@ class SdkWriteCoordinator:
         """Hold one user's writes off while evolve runs for them.
 
         New writes of the user are refused from here on; the ones already in
-        flight are waited for before the body runs.
+        flight are waited for before the body runs. Evolve and the graph
+        backfill write too, so an embedding switch refuses them as well.
         """
+        if not self.writes_open():
+            raise RuntimeError("embedding_switch_in_progress")
         async with self._exclusive.setdefault(user_id, asyncio.Lock()):
             self._evolving.add(user_id)
             try:
@@ -271,6 +364,19 @@ class SdkWriteCoordinator:
             self._handles, self._retired, self._uses = {}, set(), {}
         await asyncio.gather(*(handle.close() for handle in handles))
 
+    def in_use(self) -> int:
+        """Writes and reads holding a client right now."""
+        return sum(self._uses.values())
+
+    async def close_idle(self) -> None:
+        """Retire every handle; the unused close now, the rest when released."""
+        async with self._lock:
+            self._retired.update(self._handles.values())
+            self._handles = {}
+            unused = {value for value in self._retired if not self._uses.get(value)}
+            self._retired -= unused
+        await asyncio.gather(*(value.close() for value in unused))
+
     @asynccontextmanager
     async def use_client(self) -> AsyncIterator[Any]:
         """The public SDK client of the active write profile, kept open while used."""
@@ -281,20 +387,32 @@ class SdkWriteCoordinator:
         self,
     ) -> tuple[ModelProfileSnapshot, str | None]:
         """Resolve one stable profile snapshot for graph administration."""
-        _identity, profile, secret = await asyncio.to_thread(self._read_active_credentials)
+        _identity, profile, secret, _space = await asyncio.to_thread(self._read_active_credentials)
         return profile, secret
 
+    async def live_space(self) -> EmbeddingSpace | None:
+        if self.spaces is None:
+            return None
+        return await asyncio.to_thread(self._live_space)
+
     @asynccontextmanager
     async def _active_handle(self) -> AsyncIterator[SdkClientHandle]:
         """Use the active profile's handle; retire the others, closing the unused."""
         mode = self.memory_mode()
         features = self.memory_features()
-        profile_identity, profile, secret = await asyncio.to_thread(
+        language = self.sdk_language()
+        profile_identity, profile, secret, space = await asyncio.to_thread(
             self._read_active_credentials, mode
         )
-        identity = (*profile_identity, mode, features)
+        key = (
+            *profile_identity,
+            space.space_id if space is not None else "",
+            mode,
+            features,
+            language,
+        )
         async with self._lock:
-            handle = self._handles.get(identity)
+            handle = self._handles.get(key)
             if handle is None:
                 handle = SdkClientHandle(
                     profile,
@@ -303,10 +421,12 @@ class SdkWriteCoordinator:
                     http_transport_factory=self.transport_factory(profile),
                     mode=mode,
                     features=features,
+                    space=space,
+                    **language_kwargs(language),
                 )
-                self._handles[identity] = handle
-            self._retired.update(value for key, value in self._handles.items() if key != identity)
-            self._handles = {identity: handle}
+                self._handles[key] = handle
+            self._retired.update(value for name, value in self._handles.items() if name != key)
+            self._handles = {key: handle}
             self._uses[handle] = self._uses.get(handle, 0) + 1
             unused = {value for value in self._retired if not self._uses.get(value)}
             self._retired -= unused
@@ -325,18 +445,54 @@ class SdkWriteCoordinator:
                 self._retired.discard(handle)
                 await handle.close()
 
+    def _live_space(self) -> EmbeddingSpace:
+        assert self.spaces is not None
+        space = self.spaces.live()
+        if space is None:
+            active = self.profiles.active_identity()
+            space = self.spaces.bootstrap(
+                self.profiles.snapshot(*active) if active is not None else None
+            )
+        return space
+
+    def _lite_credentials(
+        self,
+    ) -> tuple[tuple[str, int], ModelProfileSnapshot, str | None, EmbeddingSpace | None]:
+        space = self._live_space() if self.spaces is not None else None
+        if space is None or space.profile_id is None or space.profile_revision is None:
+            builtin = builtin_retrieval_snapshot()
+            return (builtin.profile_id, builtin.revision), builtin, None, space
+        identity = (space.profile_id, space.profile_revision)
+        profile = self.profiles.snapshot(*identity)
+        view = retrieval_view(profile)
+        secret: str | None = None
+        if view.embedding_provider_kind is ProviderKind.OPENAI_COMPATIBLE:
+            try:
+                secret = self.profiles.resolve_snapshot_secret(*identity, self.secrets)
+            except SecretStoreUnavailableError:
+                raise RuntimeError("secure_storage_unavailable") from None
+            if secret is None:
+                raise RuntimeError("model_secret_unavailable")
+        return identity, view, secret, space
+
     def _read_active_credentials(
         self,
         mode: str = "pro",
-    ) -> tuple[tuple[str, int], ModelProfileSnapshot, str | None]:
+    ) -> tuple[tuple[str, int], ModelProfileSnapshot, str | None, EmbeddingSpace | None]:
+        if mode == "lite":
+            # A lite write is an embedding-only view of the live space. Never
+            # resolve or inject the generation model endpoint or its secret.
+            return self._lite_credentials()
         identity = self.profiles.active_identity()
         if identity is None:
-            if mode == "lite":
-                # lite stores raw turns with one embedding and calls no model.
-                builtin = builtin_retrieval_snapshot()
-                return (builtin.profile_id, builtin.revision), builtin, None
             raise RuntimeError("model_profile_not_active")
         profile = self.profiles.snapshot(*identity)
+        space = self._live_space() if self.spaces is not None else None
+        if space is not None and (
+            space.identity is None or not embedding_identity(profile).matches(space.identity)
+        ):
+            # Never a new, empty collection: the switch moves the space.
+            raise RuntimeError("embedding_space_mismatch")
         try:
             secret = self.profiles.resolve_snapshot_secret(
                 *identity,
@@ -348,7 +504,7 @@ class SdkWriteCoordinator:
             raise RuntimeError("model_profile_changed")
         if profile.has_api_key and secret is None:
             raise RuntimeError("model_secret_unavailable")
-        return identity, profile, secret
+        return identity, profile, secret, space
 
 
 @dataclass(frozen=True)
@@ -414,11 +570,36 @@ def _is_extracted_content(record: EvidenceRecord) -> bool:
     )
 
 
+#: The SDK's stable failure codes are upper snake case (`RECONCILE_FAILED`).
+_SDK_FAILURE_CODE = re.compile(r"[A-Z][A-Z0-9_]{0,47}")
+
+
+def sdk_write_failure_code(value: Mapping[object, object]) -> str:
+    """The job's `error_code` for a failed SDK write: the SDK's own cause if it gave one.
+
+    hy-memory 2.0.13 names why a write failed: `agent_error_code`
+    (`LLM_ERROR`, `EMPTY_RESPONSE`, `JSON_PARSE_FAILED`, `EMBEDDING_FAILED`,
+    `RECONCILE_FAILED`) and, for a failed reconcile, `reconcile_error_code`
+    (`LLM_UNAVAILABLE`, `EMPTY_RESPONSE`, `JSON_PARSE_FAILED`,
+    `RECONCILE_EXCEPTION`). They become `hy_sdk_reconcile_empty_response`,
+    `hy_sdk_llm_error`, ... Without a recognisable code it stays
+    `hy_sdk_write_failed`. Only the code is kept, never the SDK's message.
+    """
+    reconcile = value.get("reconcile_error_code")
+    if isinstance(reconcile, str) and _SDK_FAILURE_CODE.fullmatch(reconcile):
+        cause = reconcile.removeprefix("RECONCILE_") or "FAILED"
+        return f"hy_sdk_reconcile_{cause.lower()}"
+    agent = value.get("agent_error_code")
+    if isinstance(agent, str) and _SDK_FAILURE_CODE.fullmatch(agent):
+        return f"hy_sdk_{agent.lower()}"
+    return "hy_sdk_write_failed"
+
+
 def _receipt_from_result(value: object) -> SdkWriteReceipt:
     if not isinstance(value, Mapping):
         raise RuntimeError("hy_sdk_write_receipt_shape_invalid")
     if value.get("success") is not True:
-        raise RuntimeError("hy_sdk_write_failed")
+        raise RuntimeError(sdk_write_failure_code(value))
 
     # Read only documented public receipt fields. ``variant`` identifies the
     # productivity namespace; IDs from both variants are canonical memory IDs.

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

@@ -145,6 +145,10 @@ async def search_within(
         return (), "failed"
     error = pending.exception()
     if error is not None:
+        if getattr(error, "code", None) == "embedding_unavailable":
+            # Not "HY found nothing": the query could not be embedded, and
+            # the caller must say so instead of answering empty.
+            raise error
         return (), "failed"
     found = pending.result()
     normalized = normalize_semantic_hits(found)