style(memhub): format Core sources with Ruff

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

.env.example

@@ -40,6 +40,7 @@ MEMORY_EMBEDDING_DIMS=1024
 # MEMORY_EMBEDDER_TIMEOUT=15
 # MEMORY_EMBEDDER_MAX_RETRIES=2
 # MEMORY_EMBEDDER_RETRY_DELAY=0.3
+# MEMORY_EMBEDDER_BATCH_SIZE=64
 # MEMORY_EMBEDDER_EXTRA_HEADERS={}
 # MEMORY_EMBEDDER_EXTRA_BODY={}
 
@@ -77,6 +78,7 @@ MEMORY_VECTOR_STORE=chroma
 
 # ── 处理模式 ──
 # MEMORY_MODE=pro                         # lite | pro | ultra
+# MEMORY_LANGUAGE=                        # 提示词/记忆语言：en | zh-Hans | zh-Hant | ja | es | de | pt | fr | ko | ru | id；空=zh/en 自动检测
 
 # ── Coding Memory（生产力 / 编码场景独立链路，默认开启）──
 # 独立于 chat 记忆的一套链路：写入端对 messages 判类，coding 场景抽「任务→方案」存 sqlite；

CHANGELOG.md

@@ -4,9 +4,343 @@ Hy Memory and MemHub are versioned and released independently.
 
 ## Unreleased
 
+- MemHub host capture hooks no longer write the database. `one-memory
+  capture <host>` used to open the main SQLite file from its own short-lived
+  process on every hook, re-create the retired `evidence` / FTS tables on an
+  SDK-authority home and write the write queue outside Core's single writer,
+  contending for the file lock with Core and with other hosts' hooks. It now
+  reads only the runtime receipt and token and posts the hook's JSON to the
+  running Core (`POST /api/v1/live-capture/{source}`, 1.5 s budget). Core
+  applies the same gates (grant, sync switch, rejection counting, automated
+  sessions, the Cursor/Claude Code rule; the migration fence stays on the hook
+  side) and stages the turn in-process through the live file-sync path. When
+  Core is not running the turn is dropped silently; nothing falls back to a
+  local write.
+- MemHub no longer sends one turn to the SDK twice when a host's hook and live
+  file sync both see it. The two lanes gave the same message different
+  identities (the hook carries no workspace and often no message id) and
+  separate assembly rows, so both were written as raws. Hook input for a
+  source that live sync reads from its own files (every hooked host except
+  Qwen Work, while live sync is on) is now left to the file path; only a
+  source without file polling is staged from its hook. Tables an older hook
+  re-created on an SDK home are dropped by the existing startup cleanup.
+
+## 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 44, 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
+  module. The registry covers chat extraction (system prompt, basic_info,
+  intentions, few-shot including Example 11), the no-intention variant,
+  reconcile and its search-query prompt, the working/coding extractor, both
+  coding reconcilers and the chain summary, the episode and topic summaries,
+  System 2 evolve, and the user name line. The English and Simplified Chinese
+  strings are unchanged byte for byte, and a test pins them. The old names
+  (`prompts_zh.*_ZH`, `extractor.EXTRACT_SYSTEM_PROMPT`, ...) still import.
+  The nine new languages are machine translations, and native-speaker review
+  is recommended.
+- 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
+  config. The value goes through every LLM call of the request: extract and
+  basic profile, reconcile, the coding path, the summaries and System 2.
+  Aliases: `zh`, `zh-CN` → `zh-Hans`; `zh-TW`, `zh-HK` → `zh-Hant`; `pt-BR` →
+  `pt`. An unknown code raises `ValueError` listing the supported codes, and
+  the HTTP server returns 400. With an explicit language, memories are
+  written in that language even when the conversation uses another one.
+  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.
+- 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
+  identity of a space is the model name plus the width (`space_identity`).
+  Only Chroma and Kuzu are supported.
+  - `vector_space_names(config, base_name=None)` returns every physical
+    collection a client opens for the six vector roles: memory, entities,
+    coding keys and working facts, each in the working and coding variants.
+  - `reembed_vector_space(source, target, embedding=...)` pages every raw
+    source collection, covering all users and all layers including L1_RAW. It
+    embeds the text the write path embedded (`reembed_text`: the canonical
+    state's `state_retrieval_text`, a schema's `retrieval_text`, otherwise the
+    document). It then writes each record into the target with the same id,
+    document and metadata. Each batch's widths are checked before anything is
+    written. A cancel stops at a batch boundary (`ReembedCancelled`). A rerun
+    skips the ids the target already holds, so it resumes, and a merge never
+    overwrites the target. The source is never written.
+  - `plan_reembed`, `verify_reembed` and `drop_vector_space` complete the
+    vector side. `verify_reembed` checks ids, metadata, per-user counts and
+    the width, and runs a self-recall sample. `drop_vector_space` refuses
+    collections that a live client in this process holds open.
+  - `scan_vector_spaces(persist_directory)` is read-only. It lists every
+    space on disk with its roles, counts, stored width, per-user counts and
+    the models recorded in metadata. `diff_spaces(source, target)` returns the
+    ids that the source holds and the target lacks, whatever their status.
+  - `reembed_graph(source_path, target_path, embedding=..., target_dims=...)`
+    builds a new Kuzu graph at the new width. It copies every node and edge
+    and recomputes `Memory.embedding`, `Memory.beh_embedding`, and the Topic
+    and HierarchyTopic embeddings, then rebuilds the HNSW index. The source
+    graph is opened read-only and kept for rollback. A run that fails or is
+    cancelled leaves no target behind, and a rerun starts over.
+    `verify_graph_reembed` and `drop_graph` complete the graph side.
+- `EmbedService.embed_batch` now splits large batches into
+  requests of `embedder.batch_size` texts each (`MEMORY_EMBEDDER_BATCH_SIZE`,
+  default 64); before, it sent them all in one request. On a 429 it waits for
+  the `Retry-After` time plus jitter, capped at 60 s. It takes a per-call
+  `max_retries`. A returned vector whose width differs from the configured
+  `embedding_dims` now raises `EmbeddingDimensionMismatchError` and is not
+  retried.
+- Raw conversations are stored already trimmed. MemHub now keeps every raw
+  forever and lite mode stores nothing else, so tool output and long pasted
+  logs no longer stay in full. One rule (`hy_memory/utils/raw_trim.py`) is
+  applied to each message when the raw is written:
+  - `user` and `system` turns are kept in full;
+  - `assistant` turns and other speakers (`[John]:`) longer than 500
+    characters, after stripping, are cut to the first 500 plus `...`. This is
+    the limit history injection used before;
+  - `tool` turns keep their head and tail, and the middle becomes
+    `[...N bytes omitted by truncate...]`, with the coding limit
+    `coding.tool_result_max_bytes` (`MEMORY_CODING_TOOL_RESULT_MAX_BYTES`,
+    default 2048).
+
+  The rule is idempotent. It covers chat `L1_RAW` in lite, pro and ultra (lite
+  keeps tool turns, because it has no coding route) and the `memory_history`
+  ADD record. The coding/working `coding_trace` was already trimmed when it
+  was written. Its tool and assistant truncations are now idempotent, so
+  reading the history back no longer rewrites the omitted-count markers. The
+  text embedded for `L1_RAW` is the trimmed text. New raws carry
+  `custom.raw_trimmed=true`.
+- Extractor history ("last k messages") now joins the stored raws directly
+  and does not trim them again. Raws written before this change have no
+  `raw_trimmed` flag, so they are still trimmed with the same rule when they
+  are read. The extractor still receives the current batch in full (tool
+  turns are still removed on the chat route).
+
 ## MemHub 1.0.5 — 2026-10-28
 
-Build 35, on `hy-memory==2.0.8`. Linux x64/arm64 Runtime and macOS arm64
+Build 36, on `hy-memory==2.0.8`. Linux x64/arm64 Runtime and macOS arm64
 App and Runtime. Upgrading from 1.0.4 migrates the existing library to SDK
 authority on first launch.
 
@@ -94,6 +428,29 @@ authority on first launch.
   `hy_node_permissions` proof table. Evidence, governed memories, model
   profiles, SDK stores, and source/host grants are preserved.
 
+## Hy Memory 2.0.9 — 2026-11-01
+
+- Published
+  [`hy-memory==2.0.9`](https://pypi.org/project/hy-memory/2.0.9/).
+- Placeholder values no longer overwrite the user's basic profile (L0). A
+  small extraction model filled `basic_info` with `{"name": "用户"}`,
+  `The user` or `N/A` when the user had said nothing about themselves, and
+  each placeholder superseded the real value, so the L0 chain read
+  费天翔 → Fei → 用户 → The user. Two defences:
+  - `upsert_basic_profile` drops placeholder values: empty, `用户`,
+    `the user`, `user`, `n/a`, `na`, `none`, `null`, `unknown`, `未提供`,
+    `未知`, `不详`, `-`, `?` and the field's own name, compared
+    case-insensitively with whitespace and punctuation stripped. When nothing
+    is left it writes no new version and no new L0 head. Placeholders already
+    stored in the chain no longer override earlier real values when the
+    profile is assembled, so `get_user_profile` of an affected user shows the
+    last real value again without any migration. This also stops an
+    assistant quoting an old memory ("The user's name is 用户.") from being
+    written back.
+  - The extraction prompts (zh and en) state the rule: only what the user
+    said in a `user` turn, never the field name or a placeholder, `{}`
+    otherwise, with a small-talk counter-example.
+
 ## Hy Memory 2.0.8 — 2026-10-28
 
 - Published

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)**!
@@ -98,6 +99,12 @@ export OPENAI_API_KEY="sk-your-key"
 
 See the [Environment Variable Reference](docs/env_reference.md) for the full list.
 
+Prompts ship in 11 languages (`en`, `zh-Hans`, `zh-Hant`, `ja`, `es`, `de`, `pt`,
+`fr`, `ko`, `ru`, `id`). By default the SDK picks Chinese or English from the
+input. Set `MEMORY_LANGUAGE` (or `language=` on `add()`) to choose one
+explicitly; memories are then written in that language. See
+[Prompt language](docs/usage.md#提示词语言language).
+
 ### 3. Chat Memory
 
 ```python

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)**！
@@ -98,6 +99,11 @@ export OPENAI_API_KEY="sk-your-key"
 
 完整配置见 [环境变量参考](docs/env_reference.md)。
 
+提示词提供 11 种语言（`en`、`zh-Hans`、`zh-Hant`、`ja`、`es`、`de`、`pt`、`fr`、
+`ko`、`ru`、`id`）。默认按输入自动在中文与英文之间选择；设置 `MEMORY_LANGUAGE`（或在
+`add()` 上传 `language=`）可显式指定，记忆随之用该语言书写。详见
+[提示词语言](docs/usage.md#提示词语言language)。
+
 ### 3. Chat 记忆
 
 ```python

docs/env_reference.md

@@ -9,6 +9,7 @@
 |---|---|---|
 | `MEMORY_MODE` | `pro` | `lite` / `pro` / `ultra` |
 | `MEMORY_DATA_DIR` | `~/.hy_memory` | 本地数据、缓存和日志根目录 |
+| `MEMORY_LANGUAGE` | — | LLM 提示词与记忆正文语言：`en` / `zh-Hans` / `zh-Hant` / `ja` / `es` / `de` / `pt` / `fr` / `ko` / `ru` / `id`（别名 `zh`、`zh-CN` → `zh-Hans`，`zh-TW`、`zh-HK` → `zh-Hant`，`pt-BR` → `pt`）。未设置时按输入做 zh/en 自动检测；per-call `language=` 优先 |
 
 - `lite`：纯 Embedding 写入，Graph 强制关闭。
 - `pro`：LLM 提取与 reconcile；Graph 由 `MEMORY_ENABLE_GRAPH` 控制。
@@ -48,6 +49,7 @@
 | `MEMORY_EMBEDDER_TIMEOUT` | `15` | 单次超时，秒 |
 | `MEMORY_EMBEDDER_MAX_RETRIES` | `2` | 最大重试次数 |
 | `MEMORY_EMBEDDER_RETRY_DELAY` | `0.3` | 重试间隔，秒 |
+| `MEMORY_EMBEDDER_BATCH_SIZE` | `64` | `embed_batch` 单次请求最多发送的文本条数，超出按此切块 |
 | `MEMORY_EMBEDDER_EXTRA_HEADERS` | — | JSON object，附加 HTTP headers |
 | `MEMORY_EMBEDDER_EXTRA_BODY` | — | JSON object，附加请求 body |
 
@@ -180,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

@@ -103,6 +103,7 @@ result = client.add(
     metadata=None,
     meta=None,
     embed_override=None,
+    language=None,
 )
 ```
 
@@ -127,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 链路，也不会调用场景判断
@@ -136,6 +145,54 @@ LLM。pro / ultra 仍遵循各自的层级与场景参数，默认不公开原
 正交：前者说明“从哪个产品/入口写入”，后者仍是记忆隔离中的 agent 身份。source 会
 执行 `strip().lower()` 后存储，并随 chat、working、coding 记忆一起返回。
 
+### 提示词语言（`language`）
+
+SDK 的 LLM 提示词提供 11 种语言，按语言码注册在 `hy_memory/prompts/`
+（每种语言一个模块，`get_prompt(name, language)` 统一取用）：
+
+| 语言码 | 语言 | 别名 |
+|---|---|---|
+| `en` | English | `en-US`、`en-GB` |
+| `zh-Hans` | 简体中文 | `zh`、`zh-CN`、`zh-SG` |
+| `zh-Hant` | 繁體中文 | `zh-TW`、`zh-HK`、`zh-MO` |
+| `ja` | 日本語 | |
+| `es` | Español | |
+| `de` | Deutsch | |
+| `pt` | Português | `pt-BR`、`pt-PT` |
+| `fr` | Français | |
+| `ko` | 한국어 | |
+| `ru` | Русский | |
+| `id` | Bahasa Indonesia | |
+
+语言码大小写不敏感，`_` 与 `-` 等价；未知语言码抛 `ValueError` 并列出支持的语言码。
+
+```python
+# client 默认值（也可用环境变量 MEMORY_LANGUAGE=ja）
+client = HyMemoryClient.from_config({"mode": "pro", "language": "ja"})
+
+# per-call 覆盖 client 默认值
+client.add(messages, user_id="u1", language="de")
+client.add_extracted(["Der Nutzer trinkt keinen Kaffee."], user_id="u1", language="de")
+client.finalize_session(user_id="u1", session_id="s1", language="de")
+client.evolve(user_id="u1", language="de")   # ultra
+client.sweep(user_ids=["u1"], language="de")  # ultra
+```
+
+优先级：per-call `language` > `MemoryConfig.language`（`MEMORY_LANGUAGE`）> 自动检测。
+
+- **未指定语言（默认）**：行为与以前完全一致。SDK 按输入做 zh/en 自动检测，中文输入用
+  简体中文提示词，其余用英文提示词；自动检测不会选到其他语言。提示词里的「输出语言与
+  输入语言一致」规则仍然生效，所以记忆正文保持对话的原始语言。
+- **显式指定语言**：本次请求的全部 LLM 调用（抽取、基础画像、reconcile、working /
+  coding 链路的抽取与两个 reconciler 及演变总结、episode / topic 摘要、System 2）都使用
+  该语言的提示词，并在提示词末尾追加该语言的「输出语言」规则：记忆正文、摘要等自然语言
+  字段一律用该语言书写，即使对话是另一种语言。JSON 键、字段名、枚举值、代码、路径、
+  报错信息和专有名词保持原样；tags 仍是英文小写关键词。
+- 只有英文版的提示词（session / dynamic episode、cross-domain sweeper）在显式指定语言时
+  同样追加该输出规则；搜索侧的场景判断 / query rewrite 只有英文版且保持 query 原语言，
+  因此 `search()` 不接受 `language`。
+- 自定义 `extract_system_prompt_zh` / `extract_system_prompt_en` 只覆盖 `zh-Hans` / `en`。
+
 ### `search()` / `async_search()`
 
 普通 chat 检索：

hy_memory/__init__.py

@@ -55,6 +55,33 @@ except Exception:
 from .client import HyMemoryClient
 from .inspector import MemoryInspector
 from .runtime import SharedRuntime
+from .reembed import (
+    EmbeddingSpaceIdentity,
+    GraphReembedPlan,
+    GraphReembedProgress,
+    GraphReembedReport,
+    GraphVerification,
+    ReembedCancelled,
+    ReembedPlan,
+    ReembedProgress,
+    ReembedReport,
+    ReembedVerification,
+    ScannedSpace,
+    SpaceDiff,
+    VectorSpace,
+    diff_spaces,
+    drop_graph,
+    drop_vector_space,
+    plan_reembed,
+    reembed_graph,
+    reembed_text,
+    reembed_vector_space,
+    scan_vector_spaces,
+    space_identity,
+    vector_space_names,
+    verify_graph_reembed,
+    verify_reembed,
+)
 from .snapshot import (
     DataPlaneRestore,
     DataPlaneSnapshot,
@@ -129,6 +156,32 @@ __all__ = [
     "DataPlaneSnapshotRejected",
     "restore_local_data_plane",
     "snapshot_local_data_plane",
+    # 换 embedding 模型：把向量库和图重新 embed 进新的 embedding 空间
+    "EmbeddingSpaceIdentity",
+    "GraphReembedPlan",
+    "GraphReembedProgress",
+    "GraphReembedReport",
+    "GraphVerification",
+    "ReembedCancelled",
+    "ReembedPlan",
+    "ReembedProgress",
+    "ReembedReport",
+    "ReembedVerification",
+    "ScannedSpace",
+    "SpaceDiff",
+    "VectorSpace",
+    "diff_spaces",
+    "drop_graph",
+    "drop_vector_space",
+    "plan_reembed",
+    "reembed_graph",
+    "reembed_text",
+    "reembed_vector_space",
+    "scan_vector_spaces",
+    "space_identity",
+    "vector_space_names",
+    "verify_graph_reembed",
+    "verify_reembed",
     # 配置
     "MemoryConfig",
     # 公共扩展协议 / 精确读取类型

hy_memory/agent/episode_summary.py

@@ -43,6 +43,12 @@ from datetime import datetime
 from typing import Any, Dict, List, Optional
 import uuid
 
+from ..prompts import (
+    get_prompt,
+    normalize_language,
+    resolve_language,
+    with_output_language,
+)
 from ..utils.source_filter import merge_sources
 
 logger = logging.getLogger(__name__)
@@ -115,56 +121,9 @@ Messages:
 """
 
 
-EPISODE_SUMMARY_PROMPT = """You are summarizing ONE episode of conversation with the user.
-
-An episode is a single stretch of discussion — one thing that was talked about,
-possibly across several sessions of writing.
-
-## Memories captured during this episode (oldest → newest)
-
-{memories}
-
----
-
-Write a single dense summary of what happened / what was discussed in this episode.
-
-Rules:
-
-* 2–4 sentences, third person, starting with "The user ..." (or the named person
-  if the memories are about someone else).
-* Tie the memories together into one coherent account — an episode usually has a
-  thread running through it (a plan, a problem, an outing, a decision).
-* Preserve concrete details: names, places, numbers, dates.
-* Do NOT invent anything that is not in the memories.
-* Do NOT enumerate the memories one by one; synthesize them.
-* Output language must match the language of the memories.
-
-Return ONLY the summary text, no preamble, no JSON, no quotes."""
-
-
-EPISODE_SUMMARY_PROMPT_ZH = """你在为**一段讨论**（一个 episode）做总结。
-
-一个 episode 是一段连续的讨论 —— 围绕一件事，可能跨越好几次写入。
-
-## 这段讨论中抽取到的记忆（时间正序）
-
-{memories}
-
----
-
-写一段关于这次讨论内容的高密度摘要。
-
-要求：
-
-* 2–4 句，第三人称，以"用户…"开头（若记忆讲的是别人，则以那个人的名字开头）。
-* 把这些记忆串成一个连贯的叙述 —— 一段讨论通常有一根主线（一个计划、一个问题、
-  一次出行、一个决定）。
-* 保留具体细节：人名、地点、数字、日期。
-* 绝不编造记忆里没有的内容。
-* 不要逐条罗列记忆，要综合成一段。
-* 输出语言与记忆的语言一致。
-
-只返回摘要正文，不要任何前言、不要 JSON、不要引号。"""
+# 多语言版本见 hy_memory/prompts/<language>.py；旧名字保留为别名。
+from ..prompts.en import EPISODE_SUMMARY_PROMPT  # noqa: E402,F401  (re-export)
+from ..prompts.zh_hans import EPISODE_SUMMARY_PROMPT as EPISODE_SUMMARY_PROMPT_ZH  # noqa: E402,F401  (re-export)
 
 
 SESSION_EPISODE_PROMPT = """Convert this complete conversation session into one retrieval-friendly episode narrative.
@@ -596,9 +555,13 @@ def _assign_facts_to_segments(facts: List[Any], segments: List[dict]) -> Dict[in
 async def finalize_dynamic_episode_capsules(
     *, vector_store, embed_service, llm_provider, user_id: str,
     agent_id: Optional[str], session_id: str, summary_concurrency: int = 3,
+    language: Optional[str] = None,
 ) -> dict:
     """Split a completed session, create compact L3 capsules, and link its facts.
 
+    The capsule prompt is English-only; an explicit ``language`` appends that
+    language's output rule so the capsule text is written in it.
+
     Boundary and summary generation are separate calls. Boundary failure degrades
     to one whole-session capsule. A segmented-summary failure also retries the
     session as one capsule so the write never loses the complete event context.
@@ -802,6 +765,7 @@ async def finalize_dynamic_episode_capsules(
             start = end + 1
 
         semaphore = asyncio.Semaphore(max(1, min(16, int(summary_concurrency or 1))))
+        explicit_language = normalize_language(language)
 
         async def summarize(spec):
             segment_index, segment_start, segment_end, segment = spec
@@ -809,9 +773,13 @@ async def finalize_dynamic_episode_capsules(
             try:
                 async with semaphore:
                     response = await llm_provider.complete(
-                        prompt=DYNAMIC_CAPSULE_PROMPT.format(
-                            timestamp=timestamp_text,
-                            messages=_render_messages(segment),
+                        prompt=with_output_language(
+                            DYNAMIC_CAPSULE_PROMPT.format(
+                                timestamp=timestamp_text,
+                                messages=_render_messages(segment),
+                            ),
+                            explicit_language,
+                            explicit=explicit_language is not None,
                         ),
                         max_tokens=4096,
                     )
@@ -1128,9 +1096,13 @@ def _cosine(a: List[float], b: List[float]) -> float:
 async def finalize_session_episode(
     *, vector_store, embed_service, llm_provider, user_id: str,
     agent_id: Optional[str], session_id: str,
+    language: Optional[str] = None,
 ) -> dict:
     """Create one first-class narrative from all raw chunks in a caller session.
 
+    The prompt is English-only; an explicit ``language`` appends that
+    language's output rule so the narrative is written in it.
+
     This is deliberately explicit: the SDK cannot infer that the final write of a
     session has arrived. Repeated calls upsert the same deterministic node id.
     """
@@ -1213,6 +1185,10 @@ async def finalize_session_episode(
         timestamp=timestamp_text,
         conversation=conversation,
     )
+    explicit_language = normalize_language(language)
+    prompt = with_output_language(
+        prompt, explicit_language, explicit=explicit_language is not None,
+    )
     response = await llm_provider.complete(prompt=prompt, max_tokens=3000)
     narrative = (getattr(response, "content", "") or "").strip()
     if not narrative:
@@ -1274,9 +1250,12 @@ async def summarize_closed_episode(
     max_memories: int = 60,
     temperature: Optional[float] = None,
     trace=None,
+    language: Optional[str] = None,
 ) -> Optional[str]:
     """总结一个**刚刚关闭**的 episode，返回摘要节点 id（跳过则 None）。
 
+    language 为显式 prompt 语言码；None 时按记忆内容做 zh/en 自动检测。
+
     由 writer 在检测到 episode 滚动时 fire-and-forget 调用：此时上一个 episode
     不会再有新内容进来，所以这一次总结就是最终产物，不需要后续 merge / 重写。
     """
@@ -1317,6 +1296,7 @@ async def summarize_closed_episode(
     _t0 = _dt.now()
     summary, prompt, tokens = await _generate(
         llm_provider=llm_provider, memories=contents, temperature=temperature,
+        language=language,
     )
     _elapsed = (_dt.now() - _t0).total_seconds() * 1000
     if trace is not None:
@@ -1351,15 +1331,16 @@ async def summarize_closed_episode(
 
 async def _generate(
     *, llm_provider, memories: List[str], temperature: Optional[float] = None,
+    language: Optional[str] = None,
 ) -> tuple:
     """返回 (摘要文本, 实际 prompt, token 用量) —— 后两个供埋点，线上要能复盘。"""
-    from ..utils.lang_detect import is_chinese
-
     body = "\n".join(f"- {c}" for c in memories if c)
     if not body:
         return "", "", {}
-    tpl = EPISODE_SUMMARY_PROMPT_ZH if is_chinese(body) else EPISODE_SUMMARY_PROMPT
-    prompt = tpl.format(memories=body)
+    explicit = normalize_language(language)
+    code = resolve_language(explicit, body)
+    prompt = get_prompt("EPISODE_SUMMARY_PROMPT", code).format(memories=body)
+    prompt = with_output_language(prompt, code, explicit=explicit is not None)
     resp = await llm_provider.complete(
         prompt=prompt,
         max_tokens=400,

hy_memory/agent/extractor.py

@@ -20,6 +20,12 @@ import re
 
 from .llm_provider import LLMProvider, _content_fingerprint, _log_llm_content_enabled
 from ..config import LLMConfig as GlobalLLMConfig
+from ..prompts import (
+    get_prompt,
+    normalize_language,
+    resolve_language,
+    with_output_language,
+)
 
 logger = logging.getLogger(__name__)
 
@@ -164,671 +170,13 @@ class V2ExtractResult:
 #   - 不再输出 time_ref 字段。时间相关信息如果是时间敏感的（schedule / past event），
 #     让 LLM 把已解析的时间自然嵌入 content 即可；稳定偏好类 content 保持不含时间。
 
-# System prompt（固定，不参与 format）
-EXTRACT_SYSTEM_PROMPT = """# ROLE
-
-You are a Memory Extractor.
-
-Extract durable, high-value memories from conversations and convert them into structured, self-contained statements.
-
-Only extract information that is likely to matter in future conversations.
-
----
-
-# INPUTS
-
-You will receive:
-
-* Last k Messages
-* New Messages
-* Memory Date
-* Current Date
-
-Use:
-
-* Last k Messages only for coreference resolution
-* Memory Date as the ONLY temporal anchor
-* Current Date only as metadata, never for resolving relative time
-
----
-
-# WHAT TO EXTRACT
-
-Extract ONLY genuinely new information introduced in the NEW user messages.
-
-Good memories include:
-
-* preferences
-* long-term projects
-* habits
-* goals
-* recurring activities
-* opinions
-* relationships
-* important experiences
-* stable traits
-* future plans
-* decisions
-* constraints
-* accepted recommendations
-
-Do NOT extract:
-
-* small talk
-* acknowledgements
-* generic emotions
-* temporary conversational context
-* assistant reminders of old memories
-* information already implied by prior context
-* vague personality judgments
-
----
-
-# SUBJECT
-
-Every memory must be self-contained, written in third person, with an explicit
-subject. Which subject to use is decided by **who spoke**:
-
-| Speaker | Subject to write | Example |
-| --- | --- | --- |
-| `role: "user"` | the user | "The user ..." / "用户..." |
-| any speaker with a `name` other than the user (e.g. `name: "John"`) | that person, by name | "John ..." |
-| `role: "assistant"` with NO `name` | the AI assistant | "The assistant ..." |
-
-The two input sections express the speaker differently:
-
-* **New Messages** is a JSON array — read `role` and the optional `name` field.
-* **Last k Messages** is rendered text — the speaker is the bracket label,
-  `[user]:` / `[John]:` / `[assistant]:`, optionally preceded by one line
-  "The user's name is Tim" / "用户名叫Tim".
-
-Rules:
-
-* The user is the person these memories belong to. Even when the user's own name
-  is known (from `name` on their message, or from the leading name line), still
-  write "The user ...", NEVER "Tim ...".
-* **`role: "assistant"` WITH a `name` is another real person, not the AI.**
-  Write their memories with their name as the subject: "John ...".
-* Only a nameless `role: "assistant"` is the AI assistant.
-* Never invent a name for the AI assistant, it has none.
-
----
-
-# LANGUAGE RULES
-
-* Output language must match input language.
-* Preserve original scripts and technical terms exactly.
-* Never transliterate names, brands, or equations.
-
----
-
-# TWO KINDS OF MEMORY
-
-You extract two kinds of memory: **memory** and **intentions**.
-
-## memory
-
-Everything durable and worth remembering about the user — and about any other
-named person in the conversation — goes here:
-
-* preferences, opinions, values, attitudes
-* events, actions, experiences
-* habits, behavioral patterns
-* relationships, traits
-* objective facts, decisions, constraints
-* ongoing activities
-
-Implicit preferences MUST be inferred when strongly suggested
-(e.g. resuming an activity → positive interest; avoiding something →
-negative preference; repeated voluntary effort → sustained interest).
-
-Do NOT separate "what kind of person the user is" from "what happened".
-Both go into `memory`.
-
-## intentions
-
-A forward-looking thing the user **plans or intends to do in the future**,
-which can be acted on and which becomes irrelevant once done or past.
-
-Examples:
-
-* "The user has a job interview next Tuesday."
-* "The user plans to move apartments at the end of the month."
-* "The user intends to finish the report before Friday."
-
-NOT intentions (these belong in `memory`):
-
-* stable preferences / traits ("The user likes basketball")
-* completed past events ("The user moved to Beijing last year")
-* general goals with no actionable future step
-
-### valid_until
-
-For each intention, provide `valid_until`: the date after which the
-intention no longer matters (the deadline / target date), resolved
-against **Memory Date** (e.g. "next Tuesday" → that absolute date).
-If no deadline can be determined, set `valid_until` to `null`.
-
----
-
-# OWNER
-
-Every memory and intention MUST carry an `owner` saying which memory store it
-belongs to. There are exactly two values:
-
-* `"user"` — anything belonging to the user's own memory store. This includes
-  facts/preferences/traits about the user themselves, AND facts about other
-  named real people in the conversation, because those are still things the
-  user's memory should hold.
-* `"agent"` — information the AI assistant (a nameless `role: "assistant"`)
-  provides (recommendations, confirmations, things it researched), or a future
-  action the user wants the **assistant** to perform ("remind me in 8 hours").
-
-A named person is NEVER `owner: "agent"` — they are a real person, not the AI,
-even though their messages carry `role: "assistant"`. Their memories are
-`owner: "user"` with their name as the content subject.
-
-Decide `owner` per item. When unsure, default to `"user"`.
-
----
-
-# TEMPORAL RULES
-
-Resolve relative time using Memory Date.
-
-Examples:
-
-* "next week"
-* "last month"
-* "tomorrow"
-
-If time cannot be resolved safely:
-
-* remove the relative wording
-* keep the memory atemporal
-
-Do not invent chronology.
-
-**Just-happened events are events — keep them.** When the user reports something as
-just completed ("just got back", "just finished", "this morning", "yesterday"), the
-completion date is the Memory Date. Emit the **event itself** with that date; do not
-fold it into a background statement.
-
-* "I just got back from a trip with my family"
-  → "The user returned from a family trip on <Memory Date>."
-  NOT → "The user takes family trips." (the return date is the answer to "when did
-  they get back", and dropping it makes the question unanswerable)
-
-Where an event has both a start and an end that the conversation gives separately,
-record both rather than collapsing them into one span.
-
----
-
-# QUALITY RULES
-
-Each memory must be:
-
-* self-contained
-* contextually complete
-* retrieval-friendly
-* information-dense
-
-Retain important details:
-
-* names
-* products
-* locations
-* numbers
-* equations
-* constraints
-
-Never generalise a specific into a category. Write what was actually said.
-
-* "Banff" → keep "Banff", NOT "the Rocky Mountains"
-* "a 3-year-old border collie named Luna" → keep the breed, age and name
-
-**Specifics supplied by the other speaker still count.** A fact is often built across
-turns: the other speaker names the thing, the user confirms it. The subject rules
-decide *whose* memory it is — they do not license dropping detail.
-
-* [Sam]: "Did you take advantage of the skiing opportunities in Banff?"
-  [user]: "Yeah, it was great for skiing!"
-  → "The user went skiing in Banff and found the snow amazing."
-  NOT → "The user enjoys winter sports." (both the place and the activity were
-  established, one by each speaker)
-
-Avoid fragmentary memories lacking context.
-
-Choose the smallest number of memories that still preserves distinct future
-retrieval needs.
-
-* Compression means combining, not omitting. Every explicit durable proposition
-  in the new messages must appear exactly once in the output.
-* Combine details when they share the same subject and the same real-world event,
-  state, preference, plan, or decision. A coherent event may use 1–3 sentences.
-* Do not emit both a broad statement and narrower restatements of the same evidence.
-* Split only when the subject differs, the events happened independently, or the
-  memories describe different states.
-* Keep a cause, recommendation, or consequence with the fact it explains when
-  separating them would lose the relationship.
-* Never merge separate dated occurrences merely because they share a topic.
-* Preserve the source's time precision. Do not turn vague phrases such as "last
-  weekend" or "last summer" into exact calendar dates unless the date is explicit
-  or uniquely determined; "the weekend before <Memory Date>" is acceptable.
-
----
-
-# TAGS
-
-Each memory must include 1–3 concise tags.
-- Topical keywords stay lowercase (travel, health, work).
-- Proper nouns keep capitalization (Jasper, Canada, Banff, Prius).
-
-Examples:
-
-* work
-* travel
-* Jasper
-* Canada
-* health
-
----
-"""
-
-STRUCTURE_METADATA_PROMPT_EN = """
-
----
-
-# STRUCTURAL ORGANIZATION
-
-For every `memory`, also output:
-
-* `topic_paths`: a backward-compatible list of zero to three broad-to-specific
-  semantic paths.
-* `event_facet`: an object with only `subject`, `participants`, `action`,
-  `objects`, `locations`, and `state`; state is `planned`, `ongoing`,
-  `completed`, or `unknown`.
-* `topic_assignments`: zero to six subject-specific memberships. Each item is
-  `{subject, role, path}`, where `path` is a list of `{name, type}` segments and
-  `type` is one of `topic`, `facet`, `series`, or `episode`. Use `topic` for a
-  broad domain, `facet` for a concrete activity/semantic aspect, `series` only
-  for repeated occurrences of the same concrete activity/state line, and
-  `episode` only for one bounded real-world occurrence. A shared event may have
-  one assignment per explicit participant while keeping one canonical memory.
-  Types follow `topic -> facet -> series -> episode`; levels may be skipped but
-  types may not repeat or move backward.
-
-This extractor sees only the current write and therefore must not emit a
-`series` segment. Emit Topic/Facet/Episode here. Reconcile may later establish a
-Series after comparing independent stored occurrences.
-
-This is write-time organization. Do not infer Series/Episode from path depth,
-manufacture hierarchy from a proper noun or broad tag, or assign a person only
-because they co-occur in unrelated context. Stop at the most specific supported
-level and use empty values when uncertain. Never encode query forms such as
-"when", "how many", "who", plurality, or ordinal wording.
-"""
-
-# Few-shot examples (appended to the system prompt only when few_shot_enabled).
-# Each example mirrors the real input shape (Last k Messages / New Messages /
-# Memory Date) and our output schema (memory / intentions / basic_info with
-# owner & tags), and ends with a one-line takeaway.
-EXTRACT_FEW_SHOT_EN = """
----
-
-# EXAMPLES
-
-## Example 1 — Boundary: old context is for resolution only, never re-extracted
-
-Last k Messages:
-[{"role": "user", "content": "I've been looking at rescue dogs at the shelter downtown."},
- {"role": "assistant", "content": "That's lovely — found one you like?"}]
-New Messages:
-[{"role": "user", "content": "Yeah, picked her up yesterday — a 3-year-old border collie named Luna."}]
-Memory Date: 2025-04-10
-
-Output:
-```json
-{
-  "memory": [
-    {"content": "The user adopted a 3-year-old border collie named Luna from a downtown shelter on 2025-04-09.", "tags": ["pets", "family"], "owner": "user"}
-  ],
-  "intentions": [],
-  "basic_info": {}
-}
-```
-The old messages only resolve "her" and supply context ("downtown shelter"). Do NOT emit a stale memory like "the user is considering adopting a dog" — only the genuinely new fact (the completed adoption) is extracted, with "yesterday" resolved against Memory Date.
-
-## Example 2 — Condense a long assistant reply
-
-New Messages:
-[{"role": "user", "content": "Write me a short essay on why remote work boosts productivity."},
- {"role": "assistant", "content": "Sure — opening: 'Remote work has reshaped how teams operate...' [~2000 words of body omitted] ...closing: 'In short, autonomy and fewer interruptions drive higher output.'"}]
-Memory Date: 2025-03-22
-
-Output:
-```json
-{
-  "memory": [
-    {"content": "The assistant drafted a short essay for the user arguing that remote work boosts productivity because autonomy and fewer interruptions drive higher output.", "tags": ["writing", "remote-work"], "owner": "agent"}
-  ],
-  "intentions": [],
-  "basic_info": {}
-}
-```
-The assistant's reply is long. Never store the verbatim essay — distill it to topic + thesis. owner is "agent" because the assistant produced it. Bloated verbatim content makes memory unusable.
-
-## Example 3 — Composite extraction: basic_info + intention + condensed agent plan
-
-New Messages:
-[{"role": "user", "content": "Hi, I'm Kenji. I'm planning a trip to Japan next month — could you put together a 7-day itinerary?"},
- {"role": "assistant", "content": "# 7-Day Classic Japan Golden Route (Tokyo → Kyoto → Nara → Osaka)\\nFly into Tokyo, Shinkansen south to Kyoto, day-trip Nara, depart from Osaka (Kansai).\\n\\n## Day 1: Arrival in Tokyo\\n- Land at Haneda/Narita, drop bags at hotel near Tokyo Station.\\n- Late afternoon: Sensoji Temple (Asakusa), wander Nakamise Street, try taiyaki.\\n- Evening: Shibuya Crossing + Shibuya Sky rooftop for sunset; izakaya dinner (yakitori, sake).\\n\\n## Day 2: Tokyo markets & landmarks — [omitted]\\n## Day 3: Shinkansen to Kyoto, Fushimi Inari, Gion — [omitted]\\n## Day 4: Kyoto temples (Kiyomizu-dera, Kinkaku-ji, Ginkaku-ji) — [omitted]\\n## Day 5: Nara day trip (Nara Park deer, Todai-ji) — [omitted]\\n## Day 6: Osaka (Osaka Castle, Dotonbori street food) — [omitted]\\n## Day 7: Osaka sightseeing + depart from Kansai Airport — [omitted]\\n\\nTip: buy a 7-day JR Pass before arriving. Want me to adjust anything?"}]
-Memory Date: 2025-09-15
-
-Output:
-```json
-{
-  "memory": [
-    {"content": "The assistant created a 7-day Japan itinerary for the user along the classic golden route: Tokyo (Asakusa, Shibuya), Shinkansen to Kyoto (Fushimi Inari, Kiyomizu-dera, Kinkaku-ji, Gion), a Nara day trip (deer park, Todai-ji), then Osaka (Osaka Castle, Dotonbori), departing from Kansai Airport.", "tags": ["travel", "japan", "itinerary"], "owner": "agent"}
-  ],
-  "intentions": [
-    {"content": "The user plans to take a 7-day trip to Japan in October 2025.", "tags": ["travel", "japan"], "valid_until": "2025-10-31", "owner": "user"}
-  ],
-  "basic_info": {"name": "Kenji"}
-}
-```
-One turn produces three outputs in different buckets: the name goes to basic_info, the trip is a forward-looking intention with a deadline, and the assistant's long multi-section itinerary is condensed into ONE dense agent memory — the route and key stops per city, NOT every day's bullets, tips, or food lists. Storing the whole reply verbatim would bloat memory; storing the skeleton keeps it queryable.
-
-## Example 4 — A later message confirming/adopting an earlier recommendation is itself a fact
-
-New Messages:
-[{"role": "user", "content": "My 6-year-old won't eat any vegetables. Any ideas?"},
- {"role": "assistant", "content": "Try blending spinach or carrots into pasta sauce — the color and flavor mostly disappear, and many kids accept it without noticing."},
- {"role": "user", "content": "Oh nice, we'll try that tonight. By the way, what's a good bedtime for that age?"},
- {"role": "assistant", "content": "For a 6-year-old, aim for 7–9 PM with about 10–11 hours of sleep."}]
-Memory Date: 2025-06-20
-
-Output:
-```json
-{
-  "memory": [
-    {"content": "The user has a 6-year-old child who refuses to eat vegetables, and accepted the assistant's suggestion to blend spinach or carrots into pasta sauce to hide them.", "tags": ["parenting", "food"], "owner": "user"},
-    {"content": "The assistant advised the user that a 6-year-old should aim for a 7–9 PM bedtime with about 10–11 hours of sleep.", "tags": ["parenting", "sleep"], "owner": "agent"}
-  ],
-  "intentions": [],
-  "basic_info": {}
-}
-```
-In the third message the user said "we'll try that tonight" — explicitly adopting the earlier suggestion. That acceptance is valuable and must be recorded ("accepted the assistant's suggestion to ..."), not discarded as small talk. The bedtime advice was just given and not yet adopted, so it is recorded as advice (owner "agent").
-
-## Example 5 — RAG/injected context: never store the injected text
-
-New Messages:
-[{"role": "user", "content": "[Retrieved context: The Eiffel Tower is 330m tall and was completed in 1889.] Given the above, I'm going to propose to my girlfriend at the top of the Eiffel Tower this summer."}]
-Memory Date: 2025-05-02
-
-Output:
-```json
-{
-  "memory": [],
-  "intentions": [
-    {"content": "The user plans to propose to his girlfriend at the top of the Eiffel Tower in summer 2025.", "tags": ["relationship", "travel"], "valid_until": "2025-08-31", "owner": "user"}
-  ],
-  "basic_info": {}
-}
-```
-The bracketed retrieved context (the tower's height and year) is RAG-injected reference material, NOT something the user told us about themselves — do NOT store it. Only the user's own forward-looking plan is extracted. System/RAG-injected text is context for the model, never a memory.
-
-## Example 6 — Shared reference material: extract the content, not the sharing action
-
-New Messages:
-[{"role": "user", "content": "Remember my grandma's dumpling recipe so I don't lose it. Filling: 500g ground pork, 300g napa cabbage, 2 tbsp soy sauce, 1 tbsp sesame oil, a thumb of ginger minced. Cabbage salted 15 min then squeezed dry. Boil dumplings, add cold water twice, ready when they float."},
- {"role": "assistant", "content": "Got it, saved!"}]
-Memory Date: 2025-07-01
-
-Output:
-```json
-{
-  "memory": [
-    {"content": "The user's grandmother's dumpling recipe: filling of 500g ground pork, 300g napa cabbage (salted 15 minutes then squeezed dry), 2 tbsp soy sauce, 1 tbsp sesame oil, and a thumb of minced ginger; boil the dumplings, add cold water twice, and they are done when they float.", "tags": ["food", "recipe", "family"], "owner": "user"}
-  ],
-  "intentions": [],
-  "basic_info": {}
-}
-```
-Extract the actual factual content (ingredients, quantities, the salt-and-squeeze step, the boiling method) — NOT "the user shared a recipe" or "the user asked to remember the recipe". The sharing action is worthless; the content is what's queryable.
-
-## Example 7 — Structured numbers and attributes preserved exactly
-
-New Messages:
-[{"role": "user", "content": "Logging my home-gym PRs this cycle: Squat 140kg x 3, Bench 100kg x 5, Deadlift 180kg x 2, Overhead Press 60kg x 6. Bodyweight 78kg, 3 sets per lift, 3 min rest."},
- {"role": "assistant", "content": "Logged — strong numbers!"}]
-Memory Date: 2026-01-20
-
-Output:
-```json
-{
-  "memory": [
-    {"content": "The user's current lifting PRs are Squat 140kg x 3, Bench 100kg x 5, Deadlift 180kg x 2, and Overhead Press 60kg x 6, at a bodyweight of 78kg.", "tags": ["fitness", "strength"], "owner": "user"},
-    {"content": "The user trains with 3 sets per lift and 3 minutes of rest between sets.", "tags": ["fitness", "training"], "owner": "user"}
-  ],
-  "intentions": [],
-  "basic_info": {}
-}
-```
-Every number and unit (kg, reps, sets, rest time) is preserved exactly — dropping them would destroy the most queryable information. Split into two clean topics (PRs vs. training protocol), but never round or omit the specifics.
-
-## Example 8 — Long multi-topic conversation: do not stop after the first topic
-
-New Messages:
-[{"role": "user", "content": "Big week — I finally defended my PhD thesis on Tuesday!"},
- {"role": "assistant", "content": "Huge congrats! How do you feel?"},
- {"role": "user", "content": "Relieved! I also signed a lease on an apartment in Berlin and move next month. And I've started learning German on Duolingo — 30-day streak. My partner Sofia is staying in Madrid for now, which is hard."}]
-Memory Date: 2025-11-08
-
-Output:
-```json
-{
-  "memory": [
-    {"content": "The user defended their PhD thesis on 2025-11-04.", "tags": ["education", "milestone"], "owner": "user"},
-    {"content": "The user signed a lease on an apartment in Berlin.", "tags": ["housing"], "owner": "user"},
-    {"content": "The user has been learning German on Duolingo and has a 30-day streak.", "tags": ["language", "learning"], "owner": "user"},
-    {"content": "The user's partner Sofia is staying in Madrid for now, which the user finds hard.", "tags": ["relationship"], "owner": "user"}
-  ],
-  "intentions": [
-    {"content": "The user plans to move to Berlin next month (around December 2025).", "tags": ["housing", "relocation"], "valid_until": "2025-12-31", "owner": "user"}
-  ],
-  "basic_info": {}
-}
-```
-Four+ topics — thesis defense, the Berlin apartment, learning German, and the partner in Madrid. Do not stop after the first topic. Note one turn split into a completed fact (lease signed) AND an intention (the upcoming move), and the emotional-but-substantive detail about Sofia is kept because it carries lasting relationship context.
-
-## Example 9 — Two real people: `name` on an assistant message means a real person
-
-New Messages:
-[{"role": "user", "name": "Tim", "content": "Just got back from the climbing gym, third time this week. Finally sent that overhang route."},
- {"role": "assistant", "name": "John", "content": "Nice! I've been swimming instead — my shoulder still hurts from last month."}]
-Memory Date: 2025-08-14
-
-Output:
-```json
-{
-  "memory": [
-    {"content": "The user has been climbing three times a week and recently completed a difficult overhang route.", "tags": ["fitness", "climbing"], "owner": "user"},
-    {"content": "John has been swimming instead of other exercise because his shoulder still hurt after an injury around July 2025.", "tags": ["fitness", "health"], "owner": "user"}
-  ],
-  "intentions": [],
-  "basic_info": {"name": "Tim"}
-}
-```
-John carries `role: "assistant"` but he has a `name`, so he is another real person, NOT the AI: his memory uses "John ..." as the subject and is still `owner: "user"` (it belongs to the user's memory store). The user's own memory stays "The user ..." even though we know the name is Tim — never "Tim has been climbing". `basic_info.name` comes from `name: "Tim"` on the user message, which is authoritative even though Tim never said his own name out loud.
-
-## Example 10 — Counter-example: another person's attributes never go into basic_info
-
-New Messages:
-[{"role": "user", "name": "Tim", "content": "你最近在忙什么？"},
- {"role": "assistant", "name": "John", "content": "我在柏林一家医院当护士，上的是夜班，挺累的。"}]
-Memory Date: 2025-09-02
-
-Output:
-```json
-{
-  "memory": [
-    {"content": "John是柏林一家医院的护士，上夜班，觉得很累。", "tags": ["work", "health"], "owner": "user"}
-  ],
-  "intentions": [],
-  "basic_info": {"name": "Tim"}
-}
-```
-John's occupation and location are HIS attributes, so they go into `memory` with "John" as the subject. They must NEVER land in `basic_info.occupation` / `basic_info.location` — `basic_info` is exclusively the user's own profile. Only `name` (Tim, from the user message's `name` field) belongs there.
-
----
-"""
-
-
-EXTRACT_PROMPT = """## Last k Messages
-
-{last_messages}
-
----
-
-## New Messages
-
-{content}
-
----
-
-## Memory Date
-
-{memory_at}
-
----
-
-## Current Date
-
-{current_date}
-
----
-
-# Output Format
-
-Return ONLY a JSON object inside a ```json fenced block.
-
-```json
-{{
-  "memory": [
-    {{
-      "content": "...",
-      "tags": ["..."],
-      "owner": "user"
-    }}
-  ],
-  "intentions": [
-    {{
-      "content": "...",
-      "tags": ["..."],
-      "valid_until": "YYYY-MM-DD",
-      "owner": "user"
-    }}
-  ],
-  "basic_info": {{}}
-}}
-```
-
-Rules:
-
-* `memory` = durable info worth remembering: preferences, opinions, attitudes,
-  traits, events, plans, experiences, habits, decisions — about the user or
-  about any other named real person, with the subject written per "# SUBJECT"
-* `intentions` = forward-looking things the user (or another named person) plans /
-  intends to do in the future, with `valid_until` = the deadline/target date
-  (resolved against Memory Date) or `null` if none
-* `owner` (required on every memory & intention) = `"user"` or `"agent"`
-  (see "# OWNER" above; default `"user"` when unsure)
-* `basic_info` = the **user's own profile only**. Include stable profile
-  fields (e.g. name, age, location, occupation, employer) **explicitly stated**
-  in the NEW user messages. Never infer, never invent. If no field is explicitly
-  stated, output `{{}}`.
-  * Exception for `name`: the `name` field on the user's own message, or a leading
-    line "The user's name is X" / "用户名叫X", is an authoritative source for
-    `name` — even though the user never said it out loud.
-  * NEVER put another real person's attributes here. If John (an assistant-role
-    message carrying `name`) says "I'm a nurse in Berlin", that is a `memory`
-    ("John is a nurse in Berlin."), NOT `basic_info.occupation` / `.location`.
-* No duplicate information across sections
-* Tags must contain 1–3 concise lowercase keywords
-* Use empty arrays `[]` or `{{}}` when nothing is extracted
-* Return valid JSON only
-
-Output the JSON now."""
-
-
-# User prompt when MEMORY_ENABLE_INTENTION=false（无 intentions 桶）
-EXTRACT_PROMPT_NO_INTENTION = """## Last k Messages
-
-{last_messages}
-
----
-
-## New Messages
-
-{content}
-
----
-
-## Memory Date
-
-{memory_at}
-
----
-
-## Current Date
-
-{current_date}
-
----
-
-# Output Format
-
-Return ONLY a JSON object inside a ```json fenced block.
-
-```json
-{{
-  "memory": [
-    {{
-      "content": "...",
-      "tags": ["..."],
-      "owner": "user"
-    }}
-  ],
-  "basic_info": {{}}
-}}
-```
-
-Rules:
-
-* `memory` = durable info worth remembering: preferences, opinions, attitudes,
-  traits, events, experiences, habits, decisions, **and future plans / upcoming
-  actions** — about the user or about any other named real person, with the
-  subject written per "# SUBJECT". Do **not** invent a separate intentions bucket.
-* `owner` (required on every memory) = `"user"` or `"agent"`
-  (see "# OWNER" above; default `"user"` when unsure)
-* `basic_info` = the **user's own profile only**. Include stable profile
-  fields (e.g. name, age, location, occupation, employer) **explicitly stated**
-  in the NEW user messages. Never infer, never invent. If no field is explicitly
-  stated, output `{{}}`.
-  * Exception for `name`: the `name` field on the user's own message, or a leading
-    line "The user's name is X" / "用户名叫X", is an authoritative source for
-    `name` — even though the user never said it out loud.
-  * NEVER put another real person's attributes here. If John (an assistant-role
-    message carrying `name`) says "I'm a nurse in Berlin", that is a `memory`
-    ("John is a nurse in Berlin."), NOT `basic_info.occupation` / `.location`.
-* No duplicate information across sections
-* Tags: 1–3 concise keywords; topical tags lowercase; proper nouns keep capitalization
-* Use empty arrays `[]` or `{{}}` when nothing is extracted
-* Return valid JSON only — **never** include an `intentions` key
-
-Output the JSON now."""
+# Prompt 文本统一放在 hy_memory/prompts/<language>.py，按语言码经 get_prompt()
+# 取用。以下旧名字保留为英文版的别名（向后兼容）。
+from ..prompts.en import EXTRACT_SYSTEM_PROMPT  # noqa: E402,F401  (re-export)
+from ..prompts.en import STRUCTURE_METADATA_PROMPT as STRUCTURE_METADATA_PROMPT_EN  # noqa: E402,F401  (re-export)
+from ..prompts.en import EXTRACT_FEW_SHOT as EXTRACT_FEW_SHOT_EN  # noqa: E402,F401  (re-export)
+from ..prompts.en import EXTRACT_PROMPT  # noqa: E402,F401  (re-export)
+from ..prompts.en import EXTRACT_PROMPT_NO_INTENTION  # noqa: E402,F401  (re-export)
 
 
 # ================================================================
@@ -837,101 +185,26 @@ Output the JSON now."""
 
 
 def _system_prompt_without_intention(system_prompt: str, *, lang: str) -> str:
-    """从 system prompt 去掉 intentions 分桶，改为单一 memory（含未来计划）。"""
+    """从 system prompt 去掉 intentions 分桶，改为单一 memory（含未来计划）。
+
+    ``lang`` 是语言码（``en`` / ``zh-Hans`` / ``ja`` ...；旧值 ``zh`` 视作 zh-Hans）。
+    每种语言的替换片段在 ``hy_memory/prompts/<lang>.py`` 中定义。
+    """
     import re
 
-    if lang == "zh":
-        repl = (
-            "# 记忆\n"
-            "\n"
-            "你只提取一类记忆：**memory（记忆）**。\n"
-            "\n"
-            "## memory（记忆）\n"
-            "\n"
-            "一切值得长期记住的信息都放这里——既包括用户本人的，也包括对话中其他具名真人的：\n"
-            "\n"
-            "* 偏好、观点、态度、价值观\n"
-            "* 事件、行动、经历\n"
-            "* 习惯、行为模式\n"
-            "* 关系、稳定特质\n"
-            "* 客观事实、决策、约束条件\n"
-            "* 正在进行的活动\n"
-            "* **未来计划 / 即将发生的安排**（若值得记住，直接写进 `memory`；"
-            "不要单独开 intentions 桶）\n"
-            "\n"
-            "如果用户隐式表达偏好，也应提取。\n"
-            "\n"
-            "不要把\"用户是怎样的人\"和\"发生了什么\"分开。两者都放进 `memory`。\n"
-            "\n"
-            "---\n"
-            "\n"
-        )
-        system_prompt = re.sub(
-            r"# 两类记忆.*?(?=\n# OWNER)",
-            repl,
-            system_prompt,
-            count=1,
-            flags=re.S,
-        )
-        system_prompt = system_prompt.replace(
-            "每条 memory 和 intention 都必须带 `owner`",
-            "每条 memory 都必须带 `owner`",
-        )
-        system_prompt = system_prompt.replace(
-            "每条 memory 和 intention 都必须带",
-            "每条 memory 都必须带",
-        )
-        # few-shot 里若仍出现 intentions，用硬约束盖住
-        system_prompt += (
-            "\n\n---\n\n# INTENTION 关闭\n"
-            "当前配置关闭了 intention 抽取。即使示例里出现 `intentions`，"
-            "也**不要**输出该字段；未来计划写入 `memory`。\n"
-        )
-    else:
-        repl = (
-            "# MEMORY\n"
-            "\n"
-            "You extract one kind of memory: **memory**.\n"
-            "\n"
-            "## memory\n"
-            "\n"
-            "Everything durable and worth remembering about the user — and about any other\n"
-            "named person in the conversation — goes here:\n"
-            "\n"
-            "* preferences, opinions, values, attitudes\n"
-            "* events, actions, experiences\n"
-            "* habits, behavioral patterns\n"
-            "* relationships, traits\n"
-            "* objective facts, decisions, constraints\n"
-            "* ongoing activities\n"
-            "* **future plans / upcoming actions** that are worth remembering\n"
-            "  (put them in `memory`; do NOT invent a separate intentions bucket)\n"
-            "\n"
-            "Implicit preferences MUST be inferred when strongly suggested.\n"
-            "\n"
-            "Do NOT separate \"what kind of person the user is\" from \"what happened\".\n"
-            "Both go into `memory`.\n"
-            "\n"
-            "---\n"
-            "\n"
-        )
-        system_prompt = re.sub(
-            r"# TWO KINDS OF MEMORY.*?(?=\n# OWNER\n)",
-            repl,
-            system_prompt,
-            count=1,
-            flags=re.S,
-        )
-        system_prompt = system_prompt.replace(
-            "Every memory and intention MUST carry an `owner`",
-            "Every memory MUST carry an `owner`",
-        )
-        system_prompt += (
-            "\n\n---\n\n# INTENTION DISABLED\n"
-            "Intention extraction is disabled. Even if few-shot examples show "
-            "`intentions`, do **not** emit that key; put future plans in `memory`.\n"
-        )
-    return system_prompt
+    language = "zh-Hans" if lang == "zh" else lang
+    repl = get_prompt("NO_INTENTION_MEMORY_SECTION", language)
+    system_prompt = re.sub(
+        get_prompt("NO_INTENTION_SECTION_PATTERN", language),
+        lambda _m: repl,
+        system_prompt,
+        count=1,
+        flags=re.S,
+    )
+    for old, new in get_prompt("NO_INTENTION_REPLACEMENTS", language):
+        system_prompt = system_prompt.replace(old, new)
+    # few-shot 里若仍出现 intentions，用硬约束盖住
+    return system_prompt + get_prompt("INTENTION_DISABLED_NOTE", language)
 
 
 class Extractor:
@@ -968,6 +241,7 @@ class Extractor:
         tool_context: Optional[Dict[str, Any]] = None,
         history_context: str = "",
         basic_profile_fields: Optional[Dict[str, str]] = None,
+        language: Optional[str] = None,
     ) -> ExtractResult:
         """
         统一提取：identity / facts / basic_info
@@ -989,6 +263,9 @@ class Extractor:
                 **DEPRECATED**: 曾用于渲染 EXTRACT prompt 的基础画像 schema 段落，
                 现已移除该段落（basic_info 由内置 few-shot / 指令引导）。保留参数
                 仅为向后兼容，传入不再生效。
+            language:      显式 prompt 语言码（见 hy_memory.prompts.SUPPORTED_LANGUAGES，
+                           接受别名）。None 时按 content 做 zh/en 自动检测。显式指定时
+                           追加 OUTPUT_LANGUAGE_DIRECTIVE，记忆正文用该语言书写。
         """
         MAX_TOOL_ROUNDS = 5
 
@@ -1015,73 +292,52 @@ class Extractor:
             else:
                 _memory_at = _current_date
 
-            # Select prompt based on input language
-            from ..utils.lang_detect import is_chinese
+            # 选 prompt 语言：显式 language（per-call / MemoryConfig.language）优先；
+            # 未指定时沿用 zh/en 自动检测（行为与以前完全一致）。
+            _explicit_language = normalize_language(language)
+            _language = resolve_language(_explicit_language, content)
 
             _enable_intention = bool(
                 getattr(self._llm_config, "enable_intention", True)
             )
-            if is_chinese(content):
-                from .prompts_zh import (
-                    EXTRACT_PROMPT_ZH,
-                    EXTRACT_PROMPT_ZH_NO_INTENTION,
-                    EXTRACT_SYSTEM_PROMPT_ZH,
-                    EXTRACT_FEW_SHOT_ZH,
-                )
-
+            # client 自定义 system prompt 仅覆盖对应语言（zh → zh-Hans, en → en）；
+            # 直接用，不追加内置 few-shot
+            _custom_sys = None
+            if _language == "zh-Hans":
                 _custom_sys = getattr(
                     self._llm_config, "extract_system_prompt_zh", None
                 )
-                if _custom_sys:
-                    # client 自定义 system prompt：直接用，不追加内置 few-shot
-                    system_prompt = _custom_sys
-                else:
-                    system_prompt = EXTRACT_SYSTEM_PROMPT_ZH
-                    if getattr(self._llm_config, "few_shot_enabled", False):
-                        system_prompt = system_prompt + EXTRACT_FEW_SHOT_ZH
-                if not _enable_intention and not _custom_sys:
-                    system_prompt = _system_prompt_without_intention(
-                        system_prompt, lang="zh"
-                    )
-                if getattr(self._llm_config, "structure_metadata_enabled", False):
-                    from .prompts_zh import STRUCTURE_METADATA_PROMPT_ZH
-                    system_prompt += STRUCTURE_METADATA_PROMPT_ZH
-                _user_tmpl = (
-                    EXTRACT_PROMPT_ZH
-                    if _enable_intention
-                    else EXTRACT_PROMPT_ZH_NO_INTENTION
-                )
-                prompt = _user_tmpl.format(
-                    content=content,
-                    current_date=_current_date,
-                    memory_at=_memory_at,
-                    last_messages=_last_messages,
-                )
-            else:
+            elif _language == "en":
                 _custom_sys = getattr(
                     self._llm_config, "extract_system_prompt_en", None
                 )
-                if _custom_sys:
-                    system_prompt = _custom_sys
-                else:
-                    system_prompt = EXTRACT_SYSTEM_PROMPT
-                    if getattr(self._llm_config, "few_shot_enabled", False):
-                        system_prompt = system_prompt + EXTRACT_FEW_SHOT_EN
-                if not _enable_intention and not _custom_sys:
-                    system_prompt = _system_prompt_without_intention(
-                        system_prompt, lang="en"
+            if _custom_sys:
+                system_prompt = _custom_sys
+            else:
+                system_prompt = get_prompt("EXTRACT_SYSTEM_PROMPT", _language)
+                if getattr(self._llm_config, "few_shot_enabled", False):
+                    system_prompt = system_prompt + get_prompt(
+                        "EXTRACT_FEW_SHOT", _language
                     )
-                if getattr(self._llm_config, "structure_metadata_enabled", False):
-                    system_prompt += STRUCTURE_METADATA_PROMPT_EN
-                _user_tmpl = (
-                    EXTRACT_PROMPT if _enable_intention else EXTRACT_PROMPT_NO_INTENTION
-                )
-                prompt = _user_tmpl.format(
-                    content=content,
-                    current_date=_current_date,
-                    memory_at=_memory_at,
-                    last_messages=_last_messages,
+            if not _enable_intention and not _custom_sys:
+                system_prompt = _system_prompt_without_intention(
+                    system_prompt, lang=_language
                 )
+            if getattr(self._llm_config, "structure_metadata_enabled", False):
+                system_prompt += get_prompt("STRUCTURE_METADATA_PROMPT", _language)
+            system_prompt = with_output_language(
+                system_prompt, _language, explicit=_explicit_language is not None,
+            )
+            _user_tmpl = get_prompt(
+                "EXTRACT_PROMPT" if _enable_intention else "EXTRACT_PROMPT_NO_INTENTION",
+                _language,
+            )
+            prompt = _user_tmpl.format(
+                content=content,
+                current_date=_current_date,
+                memory_at=_memory_at,
+                last_messages=_last_messages,
+            )
 
             # 累计 token 统计
             if _log_llm_content_enabled():

hy_memory/agent/mem_agent.py

@@ -144,6 +144,7 @@ class MemAgent:
         tool_context: Optional[Dict[str, Any]] = None,
         history_context: str = "",
         basic_profile_fields: Optional[Dict[str, str]] = None,
+        language: Optional[str] = None,
     ) -> AgentResult:
         """
         处理添加记忆请求
@@ -161,6 +162,7 @@ class MemAgent:
             basic_profile_fields:
                 {field_name: description} 字段表，由调用方从 MemoryConfig.basic_profile.fields
                 透传过来，extractor 会渲染到 prompt 中要求 LLM 在 JSON basic_info 字段返回。
+            language: 显式 prompt 语言码，透传给 extractor；None 时 zh/en 自动检测。
 
         Returns:
             处理结果
@@ -187,6 +189,7 @@ class MemAgent:
                     tool_context=tool_context,
                     history_context=history_context,
                     basic_profile_fields=basic_profile_fields,
+                    language=language,
                 )
 
             _t_parallel = datetime.now()

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)
 
@@ -160,299 +160,18 @@ class ReconcileResult:
 # Prompts
 # ================================================================
 
-SEARCH_QUERY_PROMPT = """You are a search query generator. Given a list of newly extracted memories, generate a set of short search queries that can be used to find related existing memories in a vector database.
-
-The goal is to maximize recall — find existing memories that are semantically related to the new memories, even if the wording is very different.
-
-## New memories:
-{new_memories}
-
-## Instructions
-
-Generate search queries that cover:
-- Key topics, entities, and themes mentioned in the memories
-- Rephrased or abstracted versions of the core concepts
-- Related concepts that might exist in the user's memory store
-
-Output a JSON array of query strings (5-15 queries, short and focused):
-
-["query1", "query2", "query3", ...]
-
-Output JSON array only, no other text."""
-
-RECONCILE_PROMPT = """You are a memory management system.
-
-Your task is to merge new memories into an existing memory base while keeping it:
-
-* lossless
-* non-contradictory
-* compact
-* highly retrievable
-
----
-
-# Operations
-
-## ADD
-
-Use when the information is entirely new.
-
-```json
-{{
-  "op": "ADD",
-  "content": "...",
-  "owner": "user",
-  "tags": ["..."]
-}}
-```
-
----
-
-## UPDATE
-
-Use when:
-
-* the new memory is compatible with an existing one
-* they describe the same topic
-* merging improves completeness or retrievability
-
-Rules:
-
-* merge losslessly
-* preserve all useful information
-* do NOT create duplicates
-* if the two disagree on a value, keep the value from the memory with the later
-  `memory_at`; never let an older memory overwrite a newer value
-
-### Same occurrence vs. another occurrence
-
-Use **UPDATE** only when the new memory adds detail to the same real-world
-occurrence or durable fact already recorded.
-
-If the same person does the same kind of activity/event again at another time
-(another trip, game, injury, purchase, health scare, etc.), keep the occurrence
-as a separate **ADD**. Preserve its own date and details. When an existing memory
-is clearly another occurrence in that same concrete series, link it with
-`related: [{{"memory_id":"...","relation":"same_series"}}]`.
-
-Do not merge separate dated occurrences into one long count/timeline memory.
-The retrieval layer builds timelines from the linked L2 memories.
-
-```json
-{{
-  "op": "UPDATE",
-  "memory_id": "...",
-  "content": "...",
-  "owner": "user",
-  "tags": ["..."]
-}}
-```
-
----
-
-## SUPERSEDE
-
-Use ONLY when:
-
-* the new memory contradicts an existing memory
-* both cannot be true at the same time
-* the old memory would now give the wrong current-state answer
-* the new memory's `memory_at` is the same as or LATER than the existing memory's `memory_at`
-
-Examples:
-
-* city changed
-* employer changed
-* relationship status changed
-
-Do NOT use for:
-
-* added detail
-* compatible preferences
-* wording differences
-* semantic equivalence
-* a new memory whose `memory_at` is EARLIER than the existing memory's — it is an
-  older state and must never replace a newer one (see "Time order")
-
-Rules:
-
-* content must contain ONLY the new state
-* do NOT copy unchanged information
-* the system keeps the old node and links it onto the evolution chain automatically; you don't need to handle history
-
-```json
-{{
-  "op": "SUPERSEDE",
-  "memory_id": "...",
-  "content": "...",
-  "supersede_reason": "...",
-  "owner": "user",
-  "tags": ["..."]
-}}
-```
-
-### Folding several existing memories into one chain
-
-If TWO OR MORE existing memories track the SAME dimension and the new memory is
-the latest change on that dimension — its `memory_at` is later than every folded
-memory's `memory_at` — you may fold them into a single evolution
-chain. Use `memory_ids` (an ordered list, OLDEST → NEWEST) instead of a single
-`memory_id`:
-
-```json
-{{
-  "op": "SUPERSEDE",
-  "memory_ids": ["<oldest_id>", "<newer_id>"],
-  "content": "<only the newest state>",
-  "supersede_reason": "...",
-  "owner": "user",
-  "tags": ["..."]
-}}
-```
-
-The listed memories are chained oldest → newest and the new memory becomes the
-chain head. `content` still describes ONLY the newest state — never copy the
-older memories' text into it; they remain queryable in the chain history.
-
----
-
-# Rules
-
-* Preserve all meaningful information.
-* Skip exact duplicates.
-* Prefer merging related fragments.
-* Separate dated occurrences stay separate ADDs; use `same_series` only for the
-  same subject and same concrete activity/event type.
-* Keep each memory focused on one coherent topic.
-* Follow "Time order" below.
-* **NEVER merge or supersede across different subjects.** The subject is whoever
-  the content is about: "The user ..." vs "John ..." vs "Mary ...". Memories about
-  different people are independent facts even when the sentence is otherwise
-  identical — "The user likes coffee" and "John likes coffee" are two separate
-  memories, never an UPDATE or a SUPERSEDE of each other.
-* `owner` (`user`/`agent`): copy it from the memory being written. NEVER merge or supersede across different owners — a user's fact and the assistant's fact are distinct even on the same topic.
-* A SUPERSEDE either targets ONE memory (`memory_id`) or folds several memories on the same dimension into one chain (`memory_ids`, oldest→newest). An UPDATE targets exactly ONE memory.
-* Never touch the same existing memory from more than one op.
-* Output language matches input memory language.
-
----
-
-# Time order
-
-Every memory, new or existing, has `memory_at`: when it happened. Memories are
-NOT always written in the order they happened — history can be imported late,
-and a memory can be added while older history is still being processed. A new
-memory can therefore be OLDER than an existing one.
-
-* Decide which memory is newer ONLY by `memory_at`. "New memories" means "being
-  written now", not "more recent".
-* An older memory must never replace a newer one: no SUPERSEDE of a newer
-  memory, and no UPDATE that overwrites a newer value with an older one.
-* If a new memory is older than an existing memory it conflicts with, keep the
-  existing memory as the current state. ADD the new one as a past state, worded
-  in the past with its time (for example "In 2023 the user lived in Shanghai"),
-  or output nothing if it adds no information.
-* `memory_at: null` means unknown time. Unknown is NOT newer: never SUPERSEDE a
-  memory that has a known `memory_at` with one whose `memory_at` is null.
-* Do not invent chronology.
-
----
-
-# Optional: `related`
-
-On any op you MAY add a `related` array recording how the memory being written
-relates to an EXISTING memory. This does not change what gets stored — it only
-records a link.
-
-```json
-{{
-  "op": "ADD",
-  "content": "...",
-  "owner": "user",
-  "tags": ["..."],
-  "related": [{{"memory_id": "<existing_id>", "relation": "causes"}}]
-}}
-```
-
-Only these four relations are allowed:
-
-* `causes` — the two memories are in a cause/effect relationship
-  (e.g. "started running daily" → "knee started hurting")
-* `elaborates` — adds detail to, or is a later development of, the existing memory
-* `contrasts` — they are in tension but BOTH still true (if one makes the other
-  false, that is a SUPERSEDE, not a `contrasts` link)
-* `same_series` — separate dated occurrences of the same concrete activity or
-  event type for the same subject (for example, two different skiing trips)
-
-Rules:
-
-* Only link to memories that appear in "Existing memories" — never invent an id.
-* Only emit a link when the relationship is **explicit and specific**. Two memories
-  merely being about the same broad topic is NOT a relation — leave `related` out.
-* `same_series` requires the same subject and a concrete repeated action/event;
-  shared broad tags such as health, travel, sport, food, or work are insufficient.
-* Omit the field entirely when there is nothing to link. Zero links is the normal case.
-* Never use `related` as a substitute for UPDATE / SUPERSEDE.
-
----
-{few_shot_section}
-###################
-Input Data
-###################
-
-Current date: {current_date}
-
-## Existing memories
-
-{existing_memories}
-
-## New memories
-
-{new_memories}
-
----
-
-# Output
-
-Return ONLY a JSON array inside a fenced ```json code block.
-
-If no changes are needed:
-
-```json
-[]
-```
-
-Now produce the JSON array."""
-
-RECONCILE_STRUCTURE_METADATA_PROMPT_EN = """
-
-Additional structural output contract:
-
-For every ADD, UPDATE, or SUPERSEDE result, preserve or refine `topic_paths`,
-`event_facet`, and `topic_assignments`. `event_facet` contains only `subject`,
-`participants`, `action`, `objects`, `locations`, and `state`.
-`topic_assignments` contains subject-specific `{subject, role, path}` entries;
-each path segment is `{name, type}` and type is `topic|facet|series|episode`.
-Types follow `topic -> facet -> series -> episode`; levels may be skipped but
-types may not repeat or move backward.
-Use Series only for repeated occurrences of one concrete activity/state line and
-Episode only for one bounded real-world occurrence. Never infer these types from
-depth, a broad shared tag, or unrelated co-occurrence. When an Existing memory
-already has a semantically equivalent subject-specific path, reuse its exact node
-names and types instead of creating a synonym fork. To request exact reuse, emit
-`structure_references: [{"memory_id":"<existing_id>", "subject":"...",
-"through":"topic|facet|series|episode"}]`. The referenced ID must appear in
-Existing memories. `through` means copy that existing path prefix through the
-named structural type; an explicitly authored deeper suffix remains new. Reuse
-is forbidden when the subject, concrete activity/state line, or Episode boundary
-differs. These fields describe the memory, never a future query form such as
-"when", "how many", or "who".
-
-Series is a reconcile-time relation: establish it only when the new memory and
-at least one independent Existing memory are distinct occurrences of the same
-concrete activity/state line. Multiple propositions from the current write do
-not prove repetition.
-"""
+# Prompt 文本统一放在 hy_memory/prompts/<language>.py（get_prompt 按语言码取）；
+# 以下旧名字保留为英文版别名（向后兼容）。
+from ..prompts import (  # noqa: E402
+    get_prompt,
+    normalize_language,
+    resolve_language,
+    with_output_language,
+)
+from ..prompts.en import SEARCH_QUERY_PROMPT  # noqa: E402,F401  (re-export)
+from ..prompts.en import RECONCILE_PROMPT  # noqa: E402,F401  (re-export)
+from ..prompts.en import RECONCILE_STRUCTURE_METADATA_PROMPT as RECONCILE_STRUCTURE_METADATA_PROMPT_EN  # noqa: E402,F401  (re-export)
+from ..prompts.en import RECONCILE_FEW_SHOT as RECONCILE_FEW_SHOT_EN  # noqa: E402,F401  (re-export)
 
 
 def append_reconcile_structure_prompt(
@@ -461,10 +180,8 @@ def append_reconcile_structure_prompt(
     """Append the structure contract only for an explicit experiment config."""
     if not enabled:
         return prompt
-    if language == "zh":
-        from .prompts_zh import RECONCILE_STRUCTURE_METADATA_PROMPT_ZH
-        return prompt + RECONCILE_STRUCTURE_METADATA_PROMPT_ZH
-    return prompt + RECONCILE_STRUCTURE_METADATA_PROMPT_EN
+    code = "zh-Hans" if language == "zh" else language
+    return prompt + get_prompt("RECONCILE_STRUCTURE_METADATA_PROMPT", code)
 
 
 def _as_aware(value: Any) -> Optional[datetime]:
@@ -550,147 +267,42 @@ def build_reconcile_prompt(
     current_date: str,
     few_shot_enabled: bool = False,
     structure_metadata_enabled: bool = False,
+    language: Optional[str] = None,
 ) -> str:
-    """Build the language-matched reconcile prompt used by the write path."""
-    from ..utils.lang_detect import is_chinese
+    """Build the reconcile prompt used by the write path.
 
-    if is_chinese("\n".join(new_memories)):
-        from .prompts_zh import RECONCILE_FEW_SHOT_ZH, RECONCILE_PROMPT_ZH
-
-        few_shot = ("\n" + RECONCILE_FEW_SHOT_ZH + "\n") if few_shot_enabled else ""
-        prompt = RECONCILE_PROMPT_ZH.format(
-            current_date=current_date,
-            new_memories=new_memories_block,
-            existing_memories=existing_memories_block,
-            few_shot_section=few_shot,
-        )
-        return append_reconcile_structure_prompt(
-            prompt,
-            enabled=structure_metadata_enabled,
-            language="zh",
-        )
-
-    few_shot = ("\n" + RECONCILE_FEW_SHOT_EN + "\n") if few_shot_enabled else ""
-    prompt = RECONCILE_PROMPT.format(
+    ``language`` set → that language's prompt plus the output-language rule;
+    None → zh/en auto-detection over the new memories (unchanged behaviour).
+    """
+    explicit = normalize_language(language)
+    code = resolve_language(explicit, "\n".join(new_memories))
+    few_shot = (
+        ("\n" + get_prompt("RECONCILE_FEW_SHOT", code) + "\n")
+        if few_shot_enabled else ""
+    )
+    prompt = get_prompt("RECONCILE_PROMPT", code).format(
         current_date=current_date,
         new_memories=new_memories_block,
         existing_memories=existing_memories_block,
         few_shot_section=few_shot,
     )
-    return append_reconcile_structure_prompt(
+    prompt = append_reconcile_structure_prompt(
         prompt,
         enabled=structure_metadata_enabled,
-        language="en",
+        language=code,
     )
+    return with_output_language(prompt, code, explicit=explicit is not None)
 
 
-# Reconcile few-shot examples (injected into {few_shot_section} only when
-# few_shot_enabled). Each shows the existing/new input and the expected ops,
-# with a one-line takeaway. IDs are shortened for readability.
-RECONCILE_FEW_SHOT_EN = """
-###################
-Examples
-###################
-
-## Example 1 — One new memory: part conflicts with an existing chain, part is unrelated
-
-Existing memories:
-[
-  {"memory_id": "m1", "content": "The user works as a product manager at Stripe.", "owner": "user", "history_versions": [{"content": "The user works as a product manager at a fintech startup."}]}
-]
-New memories:
-[
-  {"content": "The user has left Stripe and is now a product lead at Notion, and has recently taken up pottery on weekends.", "owner": "user"}
-]
-
-Output:
-```json
-[
-  {"op": "SUPERSEDE", "memory_id": "m1", "content": "The user works as a product lead at Notion.", "supersede_reason": "employer changed from Stripe to Notion", "owner": "user", "tags": ["work"]},
-  {"op": "ADD", "content": "The user has recently taken up pottery on weekends.", "owner": "user", "tags": ["hobby"]}
-]
-```
-A SINGLE new memory carries two things: the job change (same dimension as the existing employment chain m1, which already has history → SUPERSEDE, becomes the new chain head) and an unrelated detail (pottery → ADD). Split the one memory into the right op per part — the new head describes ONLY the employment state, never the pottery.
-
-## Example 2 — Fold two unlinked existing memories + the new change into one 3-node chain
-
-Existing memories:
-[
-  {"memory_id": "a1", "content": "The user is learning to play the guitar.", "owner": "user", "memory_at": "2024-02-10 09:00"},
-  {"memory_id": "a2", "content": "The user can now play a few full songs on the guitar.", "owner": "user", "memory_at": "2024-09-05 09:00"}
-]
-New memories:
-[
-  {"content": "The user now performs guitar at local open-mic nights.", "owner": "user"}
-]
-
-Output:
-```json
-[
-  {"op": "SUPERSEDE", "memory_ids": ["a1", "a2"], "content": "The user performs guitar at local open-mic nights.", "supersede_reason": "guitar skill progressed: learning → playing songs → performing live", "owner": "user", "tags": ["music", "hobby"]}
-]
-```
-a1 and a2 were never linked, but they track the same dimension (guitar progress) and the new memory is the latest step. Fold them with `memory_ids` ordered oldest→newest; they become a 3-node chain (a1 ← a2 ← new head). The head `content` describes ONLY the current state — it does not restate "learning" or "a few songs".
-
-## Example 3 — New head must NOT copy the old memory's content
-
-Existing memories:
-[
-  {"memory_id": "c1", "content": "The user lives in a rented one-bedroom apartment in Shibuya, Tokyo, pays ¥180,000/month, loves the 5-minute walk to the station, but complains the place is noisy at night and has no parking.", "owner": "user"}
-]
-New memories:
-[
-  {"content": "The user just bought and moved into a three-bedroom house in the suburbs of Yokohama with a garden and a two-car garage.", "owner": "user"}
-]
-
-Output:
-```json
-[
-  {"op": "SUPERSEDE", "memory_id": "c1", "content": "The user bought and moved into a three-bedroom house in suburban Yokohama, with a garden and a two-car garage.", "supersede_reason": "residence changed from a rented Shibuya apartment to an owned Yokohama house", "owner": "user", "tags": ["housing"]}
-]
-```
-The new memory SUPERSEDEs c1 and becomes the chain head. The head `content` describes ONLY the new Yokohama house. Do NOT drag the old apartment's distinctive details (Shibuya, ¥180,000 rent, the station walk, the noise/parking complaints) into the new node — those clearly belong to the old residence, not the new one. They stay in chain history and remain retrievable; copying them would make the head self-contradictory (renting in Shibuya AND owning in Yokohama at once).
-
-## Example 4 — Different subjects are never merged, however similar the wording
-
-Existing memories:
-[
-  {"memory_id": "d1", "content": "The user drinks black coffee every morning.", "owner": "user"}
-]
-New memories:
-[
-  {"content": "John drinks black coffee every morning.", "owner": "user"},
-  {"content": "The user now drinks black coffee twice a day, morning and after lunch.", "owner": "user"}
-]
-
-Output:
-```json
-[
-  {"op": "ADD", "content": "John drinks black coffee every morning.", "owner": "user", "tags": ["food"]},
-  {"op": "UPDATE", "memory_id": "d1", "content": "The user drinks black coffee twice a day, in the morning and after lunch.", "owner": "user", "tags": ["food"]}
-]
-```
-The two new memories are near-identical in wording but have DIFFERENT subjects. "John ..." is about another person, so it is a plain ADD — never an UPDATE or SUPERSEDE of d1, even though d1 says almost the same thing about the user. Only the memory whose subject is also "The user" may merge with d1.
-
-## Example 5 — Recurring event: bump count and keep a timeline (UPDATE, not ADD)
-
-Existing memories:
-[
-  {"memory_id": "i1", "content": "John injured his ankle last season and needed time off plus physical therapy.", "owner": "user", "memory_at": "2023-05-21 19:48"}
-]
-New memories:
-[
-  {"content": "John twisted his ankle again during a recent game.", "owner": "user", "memory_at": "2023-10-13 13:50"}
-]
-
-Output:
-```json
-[
-  {"op": "UPDATE", "memory_id": "i1", "content": "John has injured his ankle two times: first last season (around the 2022–2023 season), needing time off and physical therapy; second during a game around 2023-10-13.", "owner": "user", "tags": ["health", "basketball", "injury"]}
-]
-```
-Same event type happening again → UPDATE the old memory. State the **count** and list occurrences with times when known. Do NOT ADD a second "John injured his ankle" fact, and do NOT SUPERSEDE (the first injury did not stop being true).
-"""
+def build_search_query_prompt(
+    new_memories: List[str], *, language: Optional[str] = None,
+) -> str:
+    """Search-query generation prompt (same language rule as reconcile)."""
+    explicit = normalize_language(language)
+    code = resolve_language(explicit, "\n".join(new_memories))
+    mem_lines = "\n".join(f"{i+1}. {m}" for i, m in enumerate(new_memories))
+    prompt = get_prompt("SEARCH_QUERY_PROMPT", code).format(new_memories=mem_lines)
+    return with_output_language(prompt, code, explicit=explicit is not None)
 
 
 # ================================================================
@@ -745,7 +357,9 @@ class MemoryReconciler:
             self._llm = LLMProvider(self.config)
         return self._llm
 
-    async def _generate_search_queries(self, new_memories: List[str]) -> tuple:
+    async def _generate_search_queries(
+        self, new_memories: List[str], language: Optional[str] = None,
+    ) -> tuple:
         """
         Pre-process: 从全部新 memory 中提取 search queries，
         用于补充向量搜索的召回能力。
@@ -753,17 +367,7 @@ class MemoryReconciler:
         Returns:
             (queries: List[str], llm_response: Optional[LLMResponse])
         """
-        mem_lines = "\n".join(f"{i+1}. {m}" for i, m in enumerate(new_memories))
-
-        # Select prompt based on input language
-        from ..utils.lang_detect import is_chinese
-
-        if is_chinese("\n".join(new_memories)):
-            from .prompts_zh import SEARCH_QUERY_PROMPT_ZH
-
-            prompt = SEARCH_QUERY_PROMPT_ZH.format(new_memories=mem_lines)
-        else:
-            prompt = SEARCH_QUERY_PROMPT.format(new_memories=mem_lines)
+        prompt = build_search_query_prompt(new_memories, language=language)
 
         try:
             llm = self._get_llm()
@@ -790,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],
@@ -849,6 +410,7 @@ class MemoryReconciler:
         graph_store=None,  # Optional GraphStore：Entity MENTIONS boost
         new_memory_embeddings: Optional[Dict[str, List[float]]] = None,
         source: str = "default",
+        language: Optional[str] = None,
     ) -> ReconcileResult:
         """
         对 new_memories 做 reconcile。
@@ -856,6 +418,7 @@ class MemoryReconciler:
         Args:
             new_memories: 新记忆内容列表（content only，用于 embed 搜索）
             new_memories_with_meta: 可选，含 tags 的完整 meta
+            language: 显式 prompt 语言码；None 时按新记忆做 zh/en 自动检测
         """
         if not new_memories:
             return ReconcileResult(ops=[], success=True)
@@ -876,7 +439,7 @@ class MemoryReconciler:
 
             if self._enable_search_query:
                 search_queries, sq_response = await self._generate_search_queries(
-                    new_memories
+                    new_memories, language=language,
                 )
             sq_elapsed = (_time.perf_counter() - t_sq) * 1000
 
@@ -887,18 +450,10 @@ class MemoryReconciler:
 
             # 写 SEARCH_QUERY pipeline log
             if cache and request_id:
-                mem_lines = "\n".join(f"{i+1}. {m}" for i, m in enumerate(new_memories))
                 if self._enable_search_query:
-                    from ..utils.lang_detect import is_chinese as _is_zh
-
-                    if _is_zh("\n".join(new_memories)):
-                        from .prompts_zh import SEARCH_QUERY_PROMPT_ZH
-
-                        sq_prompt = SEARCH_QUERY_PROMPT_ZH.format(
-                            new_memories=mem_lines
-                        )
-                    else:
-                        sq_prompt = SEARCH_QUERY_PROMPT.format(new_memories=mem_lines)
+                    sq_prompt = build_search_query_prompt(
+                        new_memories, language=language,
+                    )
                 else:
                     sq_prompt = "[search query disabled — hybrid retrieval per new memory]"
                 try:
@@ -1447,6 +1002,7 @@ class MemoryReconciler:
                     getattr(self.config.llm, "few_shot_enabled", False)
                 ),
                 structure_metadata_enabled=_structure_metadata_on,
+                language=language,
             )
 
             # ── Step 5: LLM 调用 + 重试 ──
@@ -1489,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
@@ -1498,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(
@@ -1507,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
@@ -1537,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:
@@ -1554,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,
@@ -1571,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
@@ -1651,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/agent/tools/basic_profile.py

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

hy_memory/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",
@@ -909,6 +910,19 @@ class HyMemoryClient:
         """
         return "coding" if str(scene or "").strip().lower() == "coding" else "working"
 
+    def _resolve_language(self, language: Optional[str]) -> Optional[str]:
+        """per-call language > MemoryConfig.language; None = zh/en 自动检测。
+
+        返回 canonical 码；未知码抛 ValueError（列出支持的码与别名）。
+        """
+        from .prompts import normalize_language
+
+        code = normalize_language(language)
+        if code is not None:
+            return code
+        config = getattr(self, "_config", None)
+        return normalize_language(getattr(config, "language", None))
+
     @staticmethod
     def _parse_input(data: AddInput):
         """
@@ -1723,6 +1737,7 @@ class HyMemoryClient:
         request_id: Optional[str] = None,
         meta: Optional[Dict[str, Any]] = None,
         embed_override: Optional[Dict[str, Any]] = None,
+        language: Optional[str] = None,
     ) -> Dict[str, Any]:
         """
         写入记忆。
@@ -1773,6 +1788,13 @@ class HyMemoryClient:
                           meta 独立持久化，只做业务透传。
                           语义为「该次 write 时刻的上下文」，故存为 list——同一节点被
                           多次写入合并时会追加而非覆盖，详见 get() 返回的 meta 字段。
+            language:     本次请求的 LLM prompt 语言码（en / zh-Hans / zh-Hant / ja / es /
+                          de / pt / fr / ko / ru / id；别名 zh、zh-CN → zh-Hans，zh-TW、
+                          zh-HK → zh-Hant，pt-BR → pt）。优先于 MemoryConfig.language
+                          （env MEMORY_LANGUAGE）；两者都未设时沿用 zh/en 自动检测。
+                          显式指定时 extract / reconcile / coding 链路 / 基础画像等本次
+                          请求的全部 LLM 调用都用该语言的 prompt，记忆正文也用该语言书写。
+                          未知码抛 ValueError（列出支持的码）。
 
         Returns:
             chat 链路：{"success": True, "memory_id": "...", "request_id": "...", "elapsed_ms": ...}
@@ -1788,6 +1810,7 @@ class HyMemoryClient:
                 workspace_id=workspace_id, branch=branch,
                 request_id=request_id, meta=meta,
                 embed_override=embed_override,
+                language=language,
             ),
             include_runtime_diag=True,
         )
@@ -1798,15 +1821,20 @@ class HyMemoryClient:
         user_id: str,
         agent_id: str = "default_agent",
         session_id: str,
+        language: Optional[str] = None,
     ) -> Dict[str, Any]:
         """Finalize one caller session into a first-class episode narrative.
 
         The feature is opt-in through MEMORY_SESSION_EPISODE_ENABLED. Calls are
         idempotent: the same user/agent/session tuple upserts one deterministic node.
+
+        ``language`` (or MemoryConfig.language) makes the narrative be written in
+        that language; see add(). The episode prompts themselves are English-only.
         """
         return self._loop_thread.run(
             self.async_finalize_session(
                 user_id=user_id, agent_id=agent_id, session_id=session_id,
+                language=language,
             ),
             include_runtime_diag=True,
         )
@@ -1836,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,
@@ -1928,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/
@@ -1971,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,
@@ -2263,6 +2294,7 @@ class HyMemoryClient:
         user_id: str,
         agent_id: str = "default_agent",
         max_batches: Optional[int] = None,
+        language: Optional[str] = None,
     ) -> Dict[str, Any]:
         """
         手动触发 System 2 认知加工（ultra 模式专用，同步阻塞直到完成）。
@@ -2285,6 +2317,8 @@ class HyMemoryClient:
         Args:
             user_id:  用户 ID
             agent_id: Agent ID
+            language: System 2 / sweeper prompt 语言码，语义同 add()（per-call >
+                      MemoryConfig.language > 按 materials 做 zh/en 检测）。
 
         Returns:
             {"success": True, "request_id": "...", "tasks_processed": 1, "results": {...},
@@ -2298,6 +2332,7 @@ class HyMemoryClient:
         return self._loop_thread.run(
             self.async_evolve(
                 user_id=user_id, agent_id=agent_id, max_batches=max_batches,
+                language=language,
             )
         )
 
@@ -2307,8 +2342,10 @@ class HyMemoryClient:
         user_id: str,
         agent_id: str = "default_agent",
         max_batches: Optional[int] = None,
+        language: Optional[str] = None,
     ) -> Dict[str, Any]:
         """手动触发 System 2 认知加工（异步）"""
+        language = self._resolve_language(language)
         t0 = __import__("time").perf_counter()
 
         # 获取 System2Writer
@@ -2331,6 +2368,7 @@ class HyMemoryClient:
 
         result = await writer.evolve(
             user_id=user_id, agent_id=agent_id, max_batches=max_batches,
+            language=language,
         )
         result["elapsed_ms"] = round((__import__("time").perf_counter() - t0) * 1000, 2)
         return result
@@ -2339,6 +2377,7 @@ class HyMemoryClient:
         self,
         user_ids: List[str],
         agent_ids: Optional[List[str]] = None,
+        language: Optional[str] = None,
     ) -> Dict[str, Any]:
         """
         手动触发 cross-domain sweeper（同步）。
@@ -2352,6 +2391,8 @@ class HyMemoryClient:
         Args:
             user_ids:  SDK user_id 列表
             agent_ids: Agent ID 列表（默认 ["default_agent"]）
+            language:  输出语言码，语义同 add()。sweeper prompt 只有英文版，显式
+                       指定时追加该语言的输出规则。
 
         Returns:
             {"success": True, "results": [{...}, ...]}
@@ -2361,7 +2402,9 @@ class HyMemoryClient:
                 f"sweep() requires mode='ultra', but this client is mode='{self._mode}'."
             )
         return self._loop_thread.run(
-            self.async_sweep(user_ids=user_ids, agent_ids=agent_ids)
+            self.async_sweep(
+                user_ids=user_ids, agent_ids=agent_ids, language=language,
+            )
         )
 
     @_ensure_internal_loop
@@ -2369,11 +2412,13 @@ class HyMemoryClient:
         self,
         user_ids: List[str],
         agent_ids: Optional[List[str]] = None,
+        language: Optional[str] = None,
     ) -> Dict[str, Any]:
         """手动触发 cross-domain sweeper（异步）
 
         对每个 user_id × agent_id 组合执行一次 sweeper。
         """
+        language = self._resolve_language(language)
         t0 = __import__("time").perf_counter()
 
         try:
@@ -2385,7 +2430,9 @@ class HyMemoryClient:
         results = []
         for uid in user_ids:
             for aid in effective_agents:
-                r = await writer.run_sweeper(user_id=uid, agent_id=aid)
+                r = await writer.run_sweeper(
+                    user_id=uid, agent_id=aid, language=language,
+                )
                 results.append({"user_id": uid, "agent_id": aid, **r})
 
         elapsed_ms = round((__import__("time").perf_counter() - t0) * 1000, 2)
@@ -2740,13 +2787,17 @@ class HyMemoryClient:
         request_id: Optional[str] = None,
         meta: Optional[Dict[str, Any]] = None,
         embed_override: Optional[Dict[str, Any]] = None,
+        language: Optional[str] = None,
     ) -> Dict[str, Any]:
         """写入记忆（异步）
 
         embed_override: 本次写入的 embedding 端点覆盖（不改 model/dims，只换接入点）。
             dict，可含 base_url / api_key / extra_headers / timeout；None = 用 client 配置。
             可用于按请求切换任意 OpenAI-compatible embedding endpoint。
+        language: 本次请求的 prompt 语言码，详见 add()。
         """
+        # 先校验语言码：非法值直接 ValueError，不占用 request_id 的幂等槽位
+        language = self._resolve_language(language)
         request_id = request_id or str(uuid.uuid4())
         replay = await self._claim_write_outcome(
             request_id=request_id,
@@ -2770,7 +2821,7 @@ class HyMemoryClient:
                         source=source,
                         metadata=metadata, memory_at=memory_at,
                         scene=scene, workspace_id=workspace_id, branch=branch,
-                        request_id=request_id, meta=meta,
+                        request_id=request_id, meta=meta, language=language,
                     )
             else:
                 result = await self._async_add_impl(
@@ -2778,7 +2829,7 @@ class HyMemoryClient:
                     source=source,
                     metadata=metadata, memory_at=memory_at,
                     scene=scene, workspace_id=workspace_id, branch=branch,
-                    request_id=request_id, meta=meta,
+                    request_id=request_id, meta=meta, language=language,
                 )
         except BaseException:
             await self._mark_write_outcome_unknown(request_id)
@@ -2797,8 +2848,10 @@ class HyMemoryClient:
         user_id: str,
         agent_id: str = "default_agent",
         session_id: str,
+        language: Optional[str] = None,
     ) -> Dict[str, Any]:
         """Async counterpart of :meth:`finalize_session`."""
+        language = self._resolve_language(language)
         series = bool(getattr(self._config.recall, "series_episode_enabled", False))
         dynamic = bool(
             getattr(self._config.recall, "dynamic_episode_enabled", False) or series
@@ -2828,6 +2881,7 @@ class HyMemoryClient:
             user_id=user_id,
             agent_id=agent_id,
             session_id=session_id,
+            language=language,
         )
         if finalize is finalize_dynamic_episode_capsules:
             finalize_kwargs["summary_concurrency"] = getattr(
@@ -2867,6 +2921,7 @@ class HyMemoryClient:
         branch: Optional[str] = None,
         request_id: Optional[str] = None,
         meta: Optional[Dict[str, Any]] = None,
+        language: Optional[str] = None,
     ) -> Dict[str, Any]:
         """写入记忆（异步）
 
@@ -2875,6 +2930,7 @@ class HyMemoryClient:
                    None = 自动判定。详见 add() docstring。
             workspace_id / branch: Coding memory 路径专用，详见 add() docstring。
             meta: 调用方自定义业务 meta，透传存储，详见 add() docstring。
+            language: 已解析的 canonical 语言码（None = zh/en 自动检测）。
         """
         from .utils.source_filter import normalize_source
         source = normalize_source(source)
@@ -2973,13 +3029,16 @@ class HyMemoryClient:
                     request_id=request_id,
                     source=source,
                     memory_at=memory_at,
+                    language=language,
                 )
                 # Public receipt always identifies the productivity namespace.
                 resp["variant"] = scene_variant
                 # 版本演进链层（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,
@@ -3038,6 +3097,7 @@ class HyMemoryClient:
             # 落库 memory_ops / WRITE_SUMMARY / pipeline_logs 的单一真相源。
             request_id=request_id,
             client_meta=meta,
+            language=language,
         )
 
         # mode → writer:
@@ -3089,9 +3149,18 @@ class HyMemoryClient:
             if self._history_store is not None:
                 try:
                     isolation_key = self._build_isolation_key(uid, agent_id)
-                    # 从 content 或 messages 中提取用于记录的文本
+                    # 从 content 或 messages 中提取用于记录的文本。messages 与 L1_RAW
+                    # 同一规则先裁剪再落审计库（工具输出 / 长回复不原样长期保存）。
+                    from .utils.raw_trim import trim_raw_messages
                     history_content = content or "; ".join(
-                        f"{m.role}: {m.content}" for m in chat_messages
+                        f"{m.role}: {m.content}"
+                        for m in trim_raw_messages(
+                            chat_messages,
+                            tool_max_bytes=getattr(
+                                getattr(self._config, "coding", None),
+                                "tool_result_max_bytes", None,
+                            ),
+                        )
                     )
                     await self._history_store.record_add(
                         memory_id=result.memory_id,
@@ -3117,6 +3186,7 @@ class HyMemoryClient:
         metadata: Optional[Dict[str, Any]] = None,
         memory_at: Optional[datetime] = None,
         request_id: Optional[str] = None,
+        language: Optional[str] = None,
     ) -> Dict[str, Any]:
         """写入「调用方已抽取好的」记忆：跳过 extract，直接进 reconcile。
 
@@ -3131,6 +3201,7 @@ class HyMemoryClient:
 
         Args:
             contents: 单条事实字符串，或多条事实字符串列表。
+            language: reconcile prompt 的语言码，语义同 add()。
             其余参数语义同 add()。
 
         Returns:
@@ -3142,6 +3213,7 @@ class HyMemoryClient:
                 contents, user_id=user_id, agent_id=agent_id,
                 session_id=session_id, source=source, metadata=metadata,
                 memory_at=memory_at, request_id=request_id,
+                language=language,
             ),
             include_runtime_diag=True,
         )
@@ -3158,8 +3230,10 @@ class HyMemoryClient:
         metadata: Optional[Dict[str, Any]] = None,
         memory_at: Optional[datetime] = None,
         request_id: Optional[str] = None,
+        language: Optional[str] = None,
     ) -> Dict[str, Any]:
         """Idempotent async wrapper for extracted-memory writes."""
+        language = self._resolve_language(language)
         request_id = request_id or str(uuid.uuid4())
         replay = await self._claim_write_outcome(
             request_id=request_id,
@@ -3180,6 +3254,7 @@ class HyMemoryClient:
                 metadata=metadata,
                 memory_at=memory_at,
                 request_id=request_id,
+                language=language,
             )
         except BaseException:
             await self._mark_write_outcome_unknown(request_id)
@@ -3202,6 +3277,7 @@ class HyMemoryClient:
         metadata: Optional[Dict[str, Any]] = None,
         memory_at: Optional[datetime] = None,
         request_id: Optional[str] = None,
+        language: Optional[str] = None,
     ) -> Dict[str, Any]:
         """写入已抽取好的记忆（异步）；跳过 extract，直接 reconcile。详见 add_extracted()。"""
         request_id = request_id or str(uuid.uuid4())
@@ -3242,6 +3318,7 @@ class HyMemoryClient:
             extra=extra,
             memory_at=memory_at,
             request_id=request_id,
+            language=language,
         )
 
         # lite/pro → MemoryWriter；ultra → System2Writer（内部复用 MemoryWriter）
@@ -3313,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,
@@ -3328,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,
         )
@@ -3346,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),
                 }
             )
@@ -3790,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,
@@ -3819,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,
                 )
@@ -3834,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,
         )
@@ -3864,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]:
@@ -3949,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,
@@ -4284,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

@@ -21,14 +21,19 @@ from typing import List, Optional, Dict, Any, Tuple
 
 from ..agent.llm_provider import LLMProvider
 from ..pipelines.base import ChatMessage
-from ..utils.lang_detect import is_chinese
+from ..prompts import (
+    get_prompt,
+    normalize_language,
+    resolve_language,
+    with_output_language,
+)
 from .preproc import (
     extract_files,
     keep_last_k_user_turns,
     prepare_extractor_messages,
 )
 from .judge import _store_coding_log
-from .types import CodingMemoryDraft, WorkingFactDraft
+from .types import CodingMemoryDraft, CodingWriteError, WorkingFactDraft
 
 
 
@@ -65,332 +70,7 @@ _VERBATIM_STATEMENT_CHARS = 600
 # Prompt
 # ================================================================
 
-EXTRACT_PROMPT = """\
-You extract durable WORKING memories from a task-execution session segment.
-A "working" session is any hands-on task where the user operates a computer /
-system through tools — this covers BOTH software/code work (writing, debugging,
-refactoring, building, deploying, API/library usage) AND system & operations
-work (running shell/PowerShell commands, disk/storage analysis or cleanup, file
-& folder operations, installing/configuring software, environment/device setup,
-hardware/disk health inspection, backup, scheduling/automation, data processing).
-
-You produce TWO layers from the SAME segment:
-
-  EXPERIENCES (procedural, "how to do it") — reusable method, extracted only
-  when it clears the VALUE BAR below. A (task, search_keys, solution,
-  boundary_envs) bundle.
-
-  FACT (episodic, "what happened this time") — EXACTLY ONE record of THIS
-  session: what the user wanted, how it was gone about, how it came out. No
-  value bar, but there is never more than one.
-
-The two layers answer different questions and are stored separately. A method
-that generalizes goes in EXPERIENCES; the story of this particular session —
-only true for this system / this project / right now — goes in the FACT.
-
-═══════════════════════════════════════════════════════════════════
-VALUE BAR (EXPERIENCES ONLY) — DO NOT cross this lightly.
-═══════════════════════════════════════════════════════════════════
-A memory MUST satisfy ALL of:
-  (a) Solves a problem likely to recur for the same user
-  (b) Solution is non-trivial: combines multiple pieces of info / steps, OR
-      carries a decision rationale, OR captures a hard-won workaround, OR is a
-      reusable procedure/recipe for an operational task (e.g. how to analyze &
-      clean up disk usage, how to batch-organize files, how to inspect hardware
-      health, how to set up a scheduled job)
-  (c) A future agent / user would prefer looking it up over re-discovering it
-
-IMPORTANT — analysis / diagnostic / investigation tasks COUNT:
-A task does NOT have to make a change or "fix" something to be worth remembering.
-Read-only / analytical / troubleshooting work is valuable when its PROCEDURE or
-CONCLUSION is reusable. Explicitly extract:
-  - Analysis / diagnostic recipes: the reusable procedure + what it revealed
-    (e.g. "how to analyze which folders eat C-drive space" — the scan commands,
-    the gotchas hit, and the finding). "It only produced a report, no change"
-    is NOT a reason to skip — the reusable METHOD is the memory.
-  - Investigation outcomes, INCLUDING negative / not-found results
-    (e.g. "searched folder X across C: and D: with rg / fs_search / SQL index —
-    not found anywhere"). A recorded dead-end saves the next agent from repeating
-    the same fruitless search, so it clears the bar.
-Do NOT reject a memory merely because "the assistant could regenerate the
-commands" or "nothing was actually modified". If the procedure or the conclusion
-would save future effort, keep it.
-
-DO NOT extract:
-  - Truly trivial single-step ops with no reusable procedure ("rename one file",
-    "git status", "run ls once")
-  - One-off issues already resolved with no transferable lesson
-  - Information that is already in the repo/system (don't duplicate package.json)
-  - Per-PR / per-session throwaway tasks unless they encode a reusable pattern
-  - The act of ASKING THE USER for missing information. Requesting a parameter,
-    listing what is unknown, or eliciting required fields is conversational
-    behaviour, not a method: every agent already knows how to ask a question, so
-    there is nothing to look up later. Never emit an experience whose task or
-    search_keys are shaped like "how to ask for X", "gather the missing Y",
-    "eliciting required fields", "what to clarify before starting". Note this
-    stays out of EXPERIENCES only — that the session ended waiting on the user
-    is real state and belongs in the FACT.
-
-If the segment made no substantive progress because it stalled waiting on the
-user — the assistant only asked for parameters, or was blocked before doing any
-real work — emit "experiences": [] and write the FACT alone. Nothing was
-learned yet, so there is no method to store. This matters more than it looks:
-an experience distilled from a stall reads as a legitimate skill on retrieval,
-and a later segment of the same task will match it and ask the user again
-instead of proceeding, so the stall reproduces itself for the rest of the
-session. Judge substance by what the tools actually did, not by whether the
-turn produced fluent text.
-
-Heuristic: if the user (or a future agent doing the same kind of task) would
-want this written down instead of figuring it out again, keep it. A multi-step
-operational procedure (even a system/ops or read-only analysis/search one, not
-just code) usually qualifies. Only drop it if it is a single command any user
-would find via `--help` in 30 seconds AND carries no decision/gotcha worth
-remembering.
-
-═══════════════════════════════════════════════════════════════════
-EXPERIENCE FIELDS
-═══════════════════════════════════════════════════════════════════
-
-task          — Query-shaped name; phrase as how a user would later ASK.
-                "publish a release to the xx platform" not
-                "publish_release_internal"
-                Self-contained (no "this", "the file", "we").
-
-search_keys   — 0 to 5 alternative phrasings capturing important aspects of
-                solution that `task` alone wouldn't match. Phrase as questions
-                or topics future users would ASK ABOUT. Distinct from task.
-                Omit if task already covers everything.
-
-solution      — Complete, self-contained content the user actually needs:
-                commands, credential locations (NOT credential VALUES),
-                file paths, ordered steps, gotchas, decision rationale.
-                Aggregate multi-turn end-to-end work into ONE solution if it
-                forms a coherent task; split into multiple memories only when
-                the user did unrelated tasks.
-
-boundary_envs — Concrete pinning that solution depends on, multi-line "key: value":
-                  runtime / SDK / library + version
-                  API endpoint or method signature
-                  external service / middleware version
-                  env var NAME (not value)
-                  config file path
-                  host / cluster / region identifier
-                If solution is environment-agnostic, leave as "" (empty).
-                Purpose: when the underlying SDK/middleware upgrades, future
-                consumers can inspect this to decide if solution still applies.
-
-confidence  — 0.0 to 1.0
-  1.0   user explicitly stated this as a rule / instruction
-  0.7   inferred with good evidence from tool actions
-  0.5   weakly inferred; one observation; uncertain
-
-═══════════════════════════════════════════════════════════════════
-FACT FIELD — EXACTLY ONE per segment, no value bar
-═══════════════════════════════════════════════════════════════════
-
-You write ONE fact for the whole segment — a recoverable state record for this
-session, not a polished retrospective and never a list of separate findings. A
-future agent must be able to resume from it without mistaking a suggestion,
-inference, or partial search for something verified.
-
-subject    — WHO or WHAT this session is about: the single entity the work was
-             performed on or for. One short noun phrase, no sentence, no verb.
-             Pick the most specific entity that the session is *about*, not the
-             tool it used:
-               a person's name when the session serves one named person
-                 ("Dylan", "Matthew")
-               the file / module / symbol when the work targets code
-                 ("auth/middleware.ts", "parse_plan_text")
-               the service / host / device / drive for ops work
-                 ("D:\\WXWork", "redis-cache-prod", "ci.yml")
-             This is a HARD KEY, not prose: two sessions about different people
-             or different files MUST get different subjects, and two sessions
-             about the same one MUST get the same string, spelled identically.
-             Prefer the exact identifier as it appears in the trace over a
-             description of it. If the segment genuinely has no single subject,
-             output "".
-
-             Why it matters: subject is the gate that decides whether a later
-             session is allowed to overwrite this one as "the same task,
-             continued". Get it wrong and one person's state silently replaces
-             another's.
-
-statement  — A compact record of THIS session. Two parts, and the second is the
-             one that gets lost.
-             Preserve task-scoped givens and concrete constraints instead of
-             replacing them with a generic evaluation of the outcome. State
-             each rule once: repeated instruction text competes with the data
-             the memory must retain.
-
-             PART 1 — what happened, about 300 latin characters (~150 CJK).
-             Start with the specific goal and object ("reclaim disk space taken
-             by D:\\WXWork", "locate the new_file_search folder"), not a generic
-             "fix a bug" / "find a file". Then roughly what was inspected, tried,
-             or changed. Then how it ended, with the semantics of exactly one of:
-             completed, partially completed, failed, blocked, or
-             still awaiting verification. Include negative results and dead ends
-             without overstating them.
-
-             PART 2 — the TASK-SCOPED GIVENS: everything the WHOLE task runs on,
-             even when this segment did not establish it and even when it feels
-             too elementary to state. Bindings (what each name/symbol/label
-             stands for), fixed values the task supplies rather than derives,
-             conventions adopted (indexing base, units, timezone, defaults), and
-             this segment's own result WITH its value ("x = 7", not "the value
-             was computed").
-
-             Write PART 2 as data, one item per line, values as given:
-               retry budget = 5; timeout 30s; index starts at 0
-               step 3 input: n=64, tolerance 1e-6
-               slot B: type=private, cost 688.7-721.3 per unit
-             A line should be almost entirely values. Keep the trace's notation —
-             symbols, units, numbers, spellings — and drop its sentences: strip
-             the phrases that announce a given rather than being one ("I would
-             prefer", "it should be somewhere between … and …"). They repeat once
-             per item, so a 15-item list pays for them 15 times.
-             Carry them on EVERY fact; never write "as above" or "same as the
-             previous session" — retrieval returns a handful of facts by
-             similarity and the referent may not be among them.
-
-             Aim under 1200 characters total. If PART 2 does not fit, fix the
-             notation, never the coverage: statement is the retrieval vector AND
-             the only field a later segment can read (details is neither embedded
-             nor injected), so anything cut from it is gone. Compress the wording
-             around a given; never the given.
-
-             The test: if the next segment cannot see the original material, can
-             it continue from this record alone? Only a yes counts. A missing
-             binding does not fail loudly — the name still looks meaningful, so
-             it gets read with its general-usage meaning and the answer that
-             follows is fluent and about a different question.
-
-             LANGUAGE — same language as the session trace: statement is the
-             retrieval vector and queries arrive in the user's working language,
-             so another language pays a cross-lingual penalty on every lookup.
-
-             EVIDENCE FIDELITY — record only actions actually executed and
-             evidence explicitly present in the trace. Preserve material
-             commands, flags, arguments, errors, and numbers verbatim.
-             NEVER complete a command with customary flags, and never turn
-             advice or plans into actions:
-               "ran Get-ChildItem -Force" → "ran Get-ChildItem"
-                 (the trace did not contain `-Force`; do not invent it)
-             Scope every negative finding to what was actually searched, and
-             enumerate EVERY explicit coverage limit that could invalidate it,
-             especially permission failures and depth limits: keep the roots,
-             filters, and depth that were in effect ("not found under C:\\ and
-             D:\\ at depth 3; some directories were not covered due to Access
-             denied"), never widen it to "does not exist". Do not omit one limit
-             to make the record prettier.
-             Never promote a partial search to global absence.
-             A blocked attempt keeps its blocker.
-             Preserve the distinction among attempted, observed, verified,
-             inferred, and unresolved — express it naturally ("tried … but was
-             blocked by Access denied", "suspected …, not yet verified"), not as
-             labels. Without tool output or explicit confirmation, NEVER claim a
-             fix succeeded, a cause was established, or a path does not exist.
-
-             Do NOT record greetings or pure chatter — that is the only case
-             getting "fact": null. A segment that merely stated requirements, or
-             stalled before doing work, still established something.
-
-details    — The session's concrete OUTPUT, copied over verbatim. `statement` is
-             a summary and a summary necessarily drops the individual values; a
-             later lookup almost always wants one specific value, not the gist.
-             So whatever addressable result this session produced, reproduce it
-             here in its original form and structure:
-               a plan / schedule / itinerary → keep every line, every day, every
-                 slot, and every price exactly as written
-               a config or code block → keep the block
-               a command's material output → keep the lines that carry the
-                 findings (sizes, counts, versions, error text)
-               a structured result (table, list of records) → keep the rows
-             Preserve the original layout — line breaks, `Day 1:` / key: value
-             prefixes, units, currency symbols, ids. Do not re-summarize, do not
-             reorder, do not round numbers, do not translate.
-
-             Copy ONLY what is present in the trace. Never fill a gap: if a slot
-             was left unfilled, leave it unfilled or say so — an invented value
-             is worse than a missing one, because it will be retrieved and used.
-             Cap around 4000 characters; if the output is longer, keep the parts
-             carrying concrete values and drop decorative prose, noting what was
-             dropped.
-
-             "" when the session produced no such artifact (pure investigation
-             with no findings yet, or a stall waiting on the user).
-
-             This field is NOT part of the retrieval vector — `statement` and
-             `subject` do the finding, `details` supplies the value once found.
-             So do not write retrieval bait here, and do not duplicate the
-             summary; write the raw thing.
-
-files      — 0..N absolute or repo-relative FILE OR DIRECTORY paths actually
-             operated on or investigated during this session. Keep investigated
-             roots such as `C:\\` and `D:\\`. Only include paths that were
-             actually accessed/searched, not paths merely suggested or planned;
-             [] if none apply.
-═══════════════════════════════════════════════════════════════════
-HOST CONTEXT (given by SDK)
-═══════════════════════════════════════════════════════════════════
-- workspace_id present: {workspace_present}
-- branch present: {branch_present}
-
-When no workspace_id is present, the solution cannot rely on unstated
-project-local context — spell out any repo / path / service it needs inside
-`solution` or `boundary_envs` so the memory stays usable on its own.
-
-═══════════════════════════════════════════════════════════════════
-CONVERSATION
-═══════════════════════════════════════════════════════════════════
-{conversation_block}
-
-═══════════════════════════════════════════════════════════════════
-OUTPUT (strict JSON only, no markdown)
-═══════════════════════════════════════════════════════════════════
-{{
-  "experiences": [
-    {{
-      "task": "...",
-      "search_keys": ["...", "..."],
-      "solution": "...",
-      "boundary_envs": "...",
-      "confidence": 0.9
-    }}
-  ],
-  "fact": {{
-    "subject": "...",
-    "statement": "...",
-    "files": ["..."],
-    "details": "..."
-  }}
-}}
-
-DEFAULT TO EXTRACTING. When the segment did real work, you MUST output at least
-one experience — even if the task looks simple or was a one-shot success, still
-capture the reusable essence of what was done (the method / command / how-to).
-When the session is thin, the single most valuable experience is enough.
-
-The ONE exception is the stall case above: if the segment did no real work
-because it was blocked asking the user for missing information, output
-"experiences": [] and write only the fact. Do not manufacture an experience to
-satisfy this instruction — a fabricated one ("how to ask for the departure
-city") is worse than none, because it is later retrieved and followed. Empty is
-allowed ONLY for that reason, never as a shortcut when work was actually done.
-
-"fact" is a SINGLE object, never a list — one record per session.
-
-ALWAYS write the fact. The bar for the fact is not "was this valuable" but "did
-anything at all happen", and a segment reaching you has already cleared that.
-This includes segments that look like setup rather than work: a single
-user message stating requirements, parameters, or a starting state, with no
-tools run, is exactly the material a later session cannot reconstruct on its own
-— 把需求、参数、起始状态连同情形一起写进 `statement`（紧凑记法，不要照抄对话原句），
-不要推给 `details`（`details` 不进检索向量，读取侧也不再注入它）。Use
-"fact": null ONLY for greetings and pure chatter with no content whatsoever.
-When in doubt, write the fact: an unneeded record costs one row, while a dropped
-one costs every later session that needed it and has no way to know it existed.
-"""
+from ..prompts.en import CODING_EXTRACT_PROMPT as EXTRACT_PROMPT  # noqa: E402,F401  (re-export)
 
 
 # ================================================================
@@ -421,350 +101,7 @@ one costs every later session that needed it and has no way to know it existed.
 #
 # 修改 prompt 时应使用代表性 coding traces 做回归，确认坐标、决策与验证状态仍保留。
 
-EXTRACT_PROMPT_CODING = """\
-╔═══════════════════════════════════════════════════════════════════════════╗
-║ HARD CONSTRAINT — read this before anything else, it overrides any         ║
-║ phrasing later in this prompt that sounds like it wants a narrative.       ║
-║                                                                           ║
-║ You are NOT writing a report of what a person did. You are writing what a  ║
-║ FUTURE AGENT needs in order to act. That agent already has its own task;   ║
-║ it does not care what this user wanted. It needs to know: what was decided ║
-║ here, at which code coordinates, what was tried and rejected, and whether  ║
-║ it was verified.                                                          ║
-║                                                                           ║
-║ Concretely, in every `statement` and every `solution`:                     ║
-║   · The grammatical subject is the CODE or THE DECISION — never "the user" ║
-║     and never "the agent". Do not write "The user attempted to…",          ║
-║     "The user wanted…", "The agent then checked…".                        ║
-║   · Never close with a bookkeeping phrase like "the session was completed", ║
-║     "the error was noted", "no solution was found yet". Close with the     ║
-║     decision and its verification status. If nothing was decided, close    ║
-║     with what was RULED OUT and the next unexplored lead — that is the     ║
-║     reusable part.                                                        ║
-║   · Keep the concrete symptom (error string, failing command, wrong        ║
-║     output) — that is what a future search will match on.                 ║
-║                                                                           ║
-║ bad:  "The user attempted to write a QTable to RST with header_rows and    ║
-║        hit a TypeError. The session was completed with the error noted."   ║
-║ good: "ascii.rst's RST writer rejects header_rows: `tbl.write(..., \        ║
-║        format='ascii.rst', header_rows=['name','unit'])` raises TypeError   ║
-║        because RST.__init__ does not forward it, unlike ascii.fixed_width   ║
-║        which accepts it. No fix written — the writer needs the same         ║
-║        header_rows plumbing as fixed_width."                              ║
-╚═══════════════════════════════════════════════════════════════════════════╝
-
-You extract durable WORKING memories from a task-execution session segment.
-A "working" session is any hands-on task where the user operates a computer /
-system through tools — this covers BOTH software/code work (writing, debugging,
-refactoring, building, deploying, API/library usage) AND system & operations
-work (running shell/PowerShell commands, disk/storage analysis or cleanup, file
-& folder operations, installing/configuring software, environment/device setup,
-hardware/disk health inspection, backup, scheduling/automation, data processing).
-
-You produce TWO layers from the SAME segment:
-
-  EXPERIENCES (procedural, "how to do it") — reusable method, extracted only
-  when it clears the VALUE BAR below. A (task, search_keys, solution,
-  boundary_envs) bundle.
-
-  FACT (episodic, "what was established this time") — EXACTLY ONE record of THIS
-  session. It is NOT a narrative of what the user did. It records, in this order:
-  the task and its concrete symptom (this is what makes it findable later), the
-  code coordinates, WHAT WAS SETTLED ON and what was rejected, and how far it was
-  verified. No value bar, but there is never more than one.
-
-The two layers answer different questions and are stored separately. A method
-that generalizes goes in EXPERIENCES; the story of this particular session —
-only true for this system / this project / right now — goes in the FACT.
-
-═══════════════════════════════════════════════════════════════════
-VALUE BAR (EXPERIENCES ONLY) — DO NOT cross this lightly.
-═══════════════════════════════════════════════════════════════════
-A memory MUST satisfy ALL of:
-  (a) Solves a problem likely to recur for the same user
-  (b) Solution is non-trivial: combines multiple pieces of info / steps, OR
-      carries a decision rationale, OR captures a hard-won workaround, OR is a
-      reusable procedure/recipe for an operational task (e.g. how to analyze &
-      clean up disk usage, how to batch-organize files, how to inspect hardware
-      health, how to set up a scheduled job)
-  (c) A future agent / user would prefer looking it up over re-discovering it
-
-IMPORTANT — analysis / diagnostic / investigation tasks COUNT:
-A task does NOT have to make a change or "fix" something to be worth remembering.
-Read-only / analytical / troubleshooting work is valuable when its PROCEDURE or
-CONCLUSION is reusable. Explicitly extract:
-  - Analysis / diagnostic recipes: the reusable procedure + what it revealed
-    (e.g. "how to analyze which folders eat C-drive space" — the scan commands,
-    the gotchas hit, and the finding). "It only produced a report, no change"
-    is NOT a reason to skip — the reusable METHOD is the memory.
-  - Investigation outcomes, INCLUDING negative / not-found results
-    (e.g. "searched folder X across C: and D: with rg / fs_search / SQL index —
-    not found anywhere"). A recorded dead-end saves the next agent from repeating
-    the same fruitless search, so it clears the bar.
-Do NOT reject a memory merely because "the assistant could regenerate the
-commands" or "nothing was actually modified". If the procedure or the conclusion
-would save future effort, keep it.
-
-DO NOT extract:
-  - Truly trivial single-step ops with no reusable procedure ("rename one file",
-    "git status", "run ls once")
-  - One-off issues already resolved with no transferable lesson
-  - Information that is already in the repo/system (don't duplicate package.json)
-  - Per-PR / per-session throwaway tasks unless they encode a reusable pattern
-
-Heuristic: if the user (or a future agent doing the same kind of task) would
-want this written down instead of figuring it out again, keep it. A multi-step
-operational procedure (even a system/ops or read-only analysis/search one, not
-just code) usually qualifies. Only drop it if it is a single command any user
-would find via `--help` in 30 seconds AND carries no decision/gotcha worth
-remembering.
-
-═══════════════════════════════════════════════════════════════════
-CODE WORK — what a future agent cannot re-derive, so it MUST be captured
-═══════════════════════════════════════════════════════════════════
-When the segment is software work on a repository, the reusable method is only
-half of it. The other half is WHERE the work lives and WHICH VERSION won. Those
-cannot be recovered by reading the code later — the code shows the current state,
-not which branch it sits on, nor what was already rejected.
-
-This section does NOT ask for a longer record. It asks you to SPEND THE SAME
-BUDGET on higher-value tokens: drop restated goals, narration of what the
-assistant "then decided to", and pasted code you are only echoing; spend those
-characters on the four items below instead. A record that omits the branch but
-quotes 30 lines of diff is a bad trade.
-
-1. BRANCH / WORKING LOCATION — verbatim, in the fact `statement`. If the segment
-   mentions or checks out `feat/x` / `fix/y`, that token MUST appear. An agent
-   that resumes on the wrong branch produces changes that are silently thrown
-   away, so this one token outranks every other detail.
-
-2. WHICH VERSION WON — when the user changed their mind, name the winner and mark
-   the loser in one clause: "settled on A; the interim B was dropped". Not both in
-   full — one clause. Keeping only the latest is wrong: an agent that meets the
-   rejected code must recognize it, or it will "fix" things back to the discarded
-   variant. Phrases like `scratch that / go back to / actually, let's / no, not that`
-   mark this: what follows is of record, what precedes is superseded.
-
-3. EXACT COORDINATES, NOT PASTED CODE — repo-relative path
-   (`qutebrowser/utils/debug.py`, never bare `debug.py`) plus the function /
-   class touched. If a signature changed, give the new signature. If a constant,
-   regex or literal was decided, quote THAT verbatim — but quote only it, not the
-   surrounding block. One accurate line beats a paragraph of approximation.
-
-4. VERIFIED vs MERELY WRITTEN — four words is enough ("tests run and passing" /
-   "confirmed by git diff only, tests not run"). "the edit is in" and "the edit is in
-   and tested" lead a future agent to do very different things next.
-
-Anti-pattern — summarizing the goal and dropping the coordinates:
-  bad:  "refactored the colour parsing logic to be cleaner."
-  good: "on feat/q4, in qutebrowser/config/configtypes.py QtColor._parse_value:
-         settled on `mult = 360.0 if kind == 'h' else 255.0`; the interim version that
-         used 255.0 for everything was dropped. Tests not run."
-  (the good one is SHORTER than most bad ones — it just spends every character
-   on something that cannot be re-derived)
-
-═══════════════════════════════════════════════════════════════════
-EXPERIENCE FIELDS
-═══════════════════════════════════════════════════════════════════
-
-task          — Query-shaped name; phrase as how a user would later ASK.
-                "publish a release to the xx platform", not "publish_release_internal"
-                Self-contained (no "this", "the file", "we").
-
-search_keys   — 0 to 5 alternative phrasings capturing important aspects of
-                solution that `task` alone wouldn't match. Phrase as questions
-                or topics future users would ASK ABOUT. Distinct from task.
-                Omit if task already covers everything.
-
-solution      — Complete, self-contained content the user actually needs:
-                commands, credential locations (NOT credential VALUES),
-                file paths, ordered steps, gotchas, decision rationale.
-                Aggregate multi-turn end-to-end work into ONE solution if it
-                forms a coherent task; split into multiple memories only when
-                the user did unrelated tasks.
-
-boundary_envs — Concrete pinning that solution depends on, multi-line "key: value":
-                  runtime / SDK / library + version
-                  API endpoint or method signature
-                  external service / middleware version
-                  env var NAME (not value)
-                  config file path
-                  host / cluster / region identifier
-                If solution is environment-agnostic, leave as "" (empty).
-                Purpose: when the underlying SDK/middleware upgrades, future
-                consumers can inspect this to decide if solution still applies.
-
-confidence  — 0.0 to 1.0
-  1.0   user explicitly stated this as a rule / instruction
-  0.7   inferred with good evidence from tool actions
-  0.5   weakly inferred; one observation; uncertain
-
-═══════════════════════════════════════════════════════════════════
-FACT FIELD — EXACTLY ONE per segment, no value bar
-═══════════════════════════════════════════════════════════════════
-
-You write ONE fact for the whole segment — a recoverable state record for this
-session, not a polished retrospective and never a list of separate findings. A
-future agent must be able to resume from it without mistaking a suggestion,
-inference, or partial search for something verified.
-
-statement  — A compact summary of THIS session. It has two jobs at once, and it
-             must do BOTH: it is the retrieval vector (a future agent finds it by
-             searching with a fresh issue report, phrased the way a user phrases a
-             problem), and it is the payload that agent then acts on. So:
-
-             OPEN with the task and the symptom, in the words a user would use.
-                This is what makes it findable — keep the surface form close to how
-                the problem would be reported. Name the specific goal and object
-                ("reclaim disk space under D:\\WXWork", "adjust the hue multiplier
-                in QtColor._parse_value on feat/q4", "locate the new_file_search
-                folder"), never a generic "fix a bug" / "look for a file". Include
-                the concrete symptom: the error string, the failing command, the
-                wrong output.
-
-             THEN give the coordinates and the decision.
-                repo-relative path, symbol, and branch for code work. State what was
-                SETTLED ON, and in the same clause mark what was dropped
-                ("settled on X; the interim Y was dropped"). This is the part that
-                cannot be re-derived by reading the code — the code only shows the
-                winner, never that Y was tried and rejected. An agent that meets the
-                rejected variant later must be able to recognize it, or it will
-                "fix" the code back to the discarded version.
-
-             CLOSE with the evidence status.
-                Exactly one of: completed, partially completed, failed, blocked, or
-                still awaiting verification — plus how it was checked ("tests run and
-                passing" / "confirmed by git diff only, tests not run"). Include
-                negative results and dead ends without overstating them.
-
-             ⚠️ Never stop at the narrative. "The user tried X and hit error Y; no
-             solution found yet" is a wasted record: it retrieves fine but gives a
-             future agent nothing to act on. If the session genuinely reached no
-             decision, say what was ruled out and what the next unexplored lead is —
-             that is the reusable part.
-
-             The subject of the sentences should be the code and the decision, not
-             "the user". 2 to 4 sentences, flowing prose, not labelled sections.
-             Hard ceiling ~400 latin characters (~200 CJK characters).
-
-             EVIDENCE FIDELITY — mandatory:
-             - Record only actions actually executed and evidence explicitly
-               present in the trace. Preserve material commands, flags,
-               arguments, errors, and numbers verbatim. NEVER complete a
-               command with customary flags or turn advice/plans into actions.
-             - Preserve the distinction among attempted, observed, verified,
-               inferred, and unresolved. Do not add those labels to the prose;
-               express their meaning naturally, e.g. "tried … but was blocked by
-               Access denied" or "suspect … , not yet verified".
-             - Without tool output or explicit confirmation, NEVER claim a fix
-               succeeded, a cause was established, a file/folder does not
-               exist, or tests passed.
-             - Scope every negative finding to what was actually searched and
-               enumerate EVERY explicit coverage limit that could invalidate
-               it, especially permission failures and maximum search depth:
-               "not found within the searched parts of C:\\ and D:\\; some
-               directories were skipped on Access denied, and the search was also
-               depth-limited". Do not omit one limit to make the
-               summary prettier. Never promote a partial search to global
-               absence.
-             - State causality as certain only when the trace directly verifies
-               it. Otherwise retain the hedge ("suspected" / "inferred" / "not yet
-               verified"); do not rewrite an
-               incorrect test assumption as the system's root cause.
-
-             CRITICAL — this text IS the retrieval vector, and it is the only
-             thing a future query gets matched against. A generic summary is
-             worthless, because EVERY session looks like a generic summary: it
-             would match every query and answer none of them. So you MUST name
-             the concrete anchors that make THIS session findable — real file
-             paths, function / symbol names, branch names, commands, error
-             strings, versions, config keys and values, host / service names.
-             If someone later searches for any one of those specifics, this
-             summary has to be the thing that comes back.
-               good: "fixing a failing `npm run build` in CI. Read
-                      .github/workflows/ci.yml and package.json; traced it to webpack
-                      5.74 hitting ERR_OSSL_EVP_UNSUPPORTED under node 18. Bumping the
-                      workflow's node to 20 made the build pass; node 18 still
-                      reproduces locally."
-               good: "on branch feat/q0, in qutebrowser/utils/debug.py signal_name:
-                      PyQt<5.11 only exposes the name via repr(sig), and repr comes in
-                      both a bracketed and a parenthesised form. Settled on two patterns
-                      tried in order with fullmatch, breaking on the first hit; the
-                      single-regex version was dropped. Confirmed by git diff, tests not
-                      run."
-               bad:  "user wanted a build bug fixed, the agent looked at some config
-                      files, changed some code, and fixed it."
-                      (no path, no command, no error string, no version — nothing
-                       to retrieve on; every session reads exactly like this)
-               bad:  "fixed the signal-name parsing compatibility issue on a feature
-                      branch."
-                      (which branch? which file? which function? which of the two
-                       competing versions won? nothing here survives being
-                       retrieved a week later)
-             Fidelity examples (bad → good):
-               "ran Get-ChildItem -Force" → "ran Get-ChildItem"
-                 (the trace did not contain `-Force`; do not invent it)
-               "confirmed new_file_search does not exist" →
-                 "new_file_search was not found within the searched parts of C:\\ and
-                  D:\\; some directories were skipped on Access denied or by the depth
-                  limit, so the investigation is only partly done"
-               "identical payloads cause a spurious lock error" →
-                 "the verification script assumed the last writer is always a fixed
-                  rank; that assumption does not hold, so whether there is a lock bug
-                  is still unverified"
-
-             Do NOT record greetings or pure chatter. If the segment established
-             nothing at all, output "fact": null.
-
-files      — 0..N absolute or repo-relative FILE OR DIRECTORY paths actually
-             operated on or investigated during this session. Keep investigated
-             roots such as `C:\\` and `D:\\`. Only include paths that were
-             actually accessed/searched, not paths merely suggested or planned;
-             [] if none apply.
-
-═══════════════════════════════════════════════════════════════════
-HOST CONTEXT (given by SDK)
-═══════════════════════════════════════════════════════════════════
-- workspace_id present: {workspace_present}
-- branch present: {branch_present}
-
-When no workspace_id is present, the solution cannot rely on unstated
-project-local context — spell out any repo / path / service it needs inside
-`solution` or `boundary_envs` so the memory stays usable on its own.
-
-═══════════════════════════════════════════════════════════════════
-CONVERSATION
-═══════════════════════════════════════════════════════════════════
-{conversation_block}
-
-═══════════════════════════════════════════════════════════════════
-OUTPUT (strict JSON only, no markdown)
-═══════════════════════════════════════════════════════════════════
-{{
-  "experiences": [
-    {{
-      "task": "...",
-      "search_keys": ["...", "..."],
-      "solution": "...",
-      "boundary_envs": "...",
-      "confidence": 0.9
-    }}
-  ],
-  "fact": {{
-    "statement": "...",
-    "files": ["..."]
-  }}
-}}
-
-MANDATORY: You MUST output at least ONE experience. Do NOT return an empty list.
-Even if the task looks simple or is a one-shot success, still capture the
-reusable essence of what was done (the method / command / how-to). Only the
-single most valuable experience is required when the session is thin — but never
-output an empty "experiences" array.
-
-"fact" is a SINGLE object, never a list — one record per session. Use
-"fact": null only when the segment is pure chatter that established nothing.
-"""
+from ..prompts.en import CODING_EXTRACT_PROMPT_CODING as EXTRACT_PROMPT_CODING  # noqa: E402,F401  (re-export)
 
 
 # ================================================================
@@ -839,15 +176,22 @@ class CodingMemoryExtractor:
             if str(message.content or "").strip()
         )
 
-    def _select_prompt_template(self, messages: List[ChatMessage]) -> Tuple[str, str]:
-        """Return (template, language) for this write's new messages."""
-        if not is_chinese(self._language_text(messages)):
-            return self._prompt_tmpl, "en"
+    def _select_prompt_template(
+        self, messages: List[ChatMessage], language: Optional[str] = None,
+    ) -> Tuple[str, str]:
+        """Return (template, language code) for this write's new messages.
 
-        from .prompts_zh import EXTRACT_PROMPT_CODING_ZH, EXTRACT_PROMPT_ZH
-
-        prompt = EXTRACT_PROMPT_CODING_ZH if self.scene == "coding" else EXTRACT_PROMPT_ZH
-        return prompt, "zh"
+        Explicit ``language`` wins; otherwise zh/en auto-detection over the new
+        user text (unchanged behaviour).
+        """
+        code = resolve_language(language, self._language_text(messages))
+        if code == "en":
+            return self._prompt_tmpl, code
+        name = (
+            "CODING_EXTRACT_PROMPT_CODING" if self.scene == "coding"
+            else "CODING_EXTRACT_PROMPT"
+        )
+        return get_prompt(name, code), code
 
     async def extract(
         self,
@@ -861,16 +205,22 @@ class CodingMemoryExtractor:
         branch: Optional[str] = None,
         session_id: Optional[str] = None,
         request_id: str = "",
+        language: Optional[str] = None,
     ) -> Tuple[List[CodingMemoryDraft], List[WorkingFactDraft]]:
         """
         Args:
             messages: 本次 write 的完整新消息；只做单条限长，不裁 turn
             history_messages: 之前 write 的历史消息；仅取最近 5 个 user-turn 作消解上下文
             user_id / agent_id / workspace_id / branch / session_id: SDK 注入
+            language: 显式 prompt 语言码；None 时按新 user 文本做 zh/en 自动检测
 
         Returns:
             (经验草稿, 事实草稿)。两层都可能为空。只有显式启用
             verbatim_fallback_enabled 时，模型没产出 fact 才调用 _verbatim_fact。
+
+        Raises:
+            CodingWriteError: 未开启原文兜底时，LLM 调用失败（LLM_ERROR）、返回空
+                content（EMPTY_RESPONSE）或回复解析不出 JSON 对象（JSON_PARSE_FAILED）。
         """
         if not messages:
             return [], []
@@ -892,27 +242,26 @@ class CodingMemoryExtractor:
 
         history_block = self._format_conversation(history_window).strip()
         new_block = self._format_conversation(new_messages).strip()
-        prompt_tmpl, prompt_language = self._select_prompt_template(new_messages)
-        if prompt_language == "zh":
-            conversation_block = (
-                "最近 5 个用户轮次（仅作上下文，不要重复抽取）：\n"
-                + (history_block or "（无）")
-                + "\n\n本次新增消息（只从这次完整写入中抽取）：\n"
-                + (new_block or "（无）")
-            )
-        else:
-            conversation_block = (
-                "LAST 5 USER TURNS (CONTEXT ONLY; do not extract them again):\n"
-                + (history_block or "(none)")
-                + "\n\nNEW MESSAGES (extract only from this complete write):\n"
-                + (new_block or "(none)")
-            )
+        explicit_language = normalize_language(language)
+        prompt_tmpl, prompt_language = self._select_prompt_template(
+            new_messages, explicit_language,
+        )
+        empty_block = get_prompt("CODING_EMPTY_BLOCK", prompt_language)
+        conversation_block = get_prompt(
+            "CODING_CONVERSATION_BLOCK", prompt_language,
+        ).format(
+            history=history_block or empty_block,
+            new=new_block or empty_block,
+        )
 
         prompt = prompt_tmpl.format(
             workspace_present=str(bool(workspace_id)).lower(),
             branch_present=str(bool(branch)).lower(),
             conversation_block=conversation_block,
         )
+        prompt = with_output_language(
+            prompt, prompt_language, explicit=explicit_language is not None,
+        )
 
         _t0 = time.perf_counter()
         try:
@@ -923,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
@@ -951,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
@@ -1133,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("```"):
@@ -1164,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,17 +18,24 @@ 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
 
 from ..agent.llm_provider import LLMProvider
 from ..core.embed_service import EmbedService
-from ..utils.lang_detect import is_chinese
+from ..prompts import (
+    get_prompt,
+    normalize_language,
+    resolve_language,
+    with_output_language,
+)
 from .store import CodingMemoryStore
 from .types import (
 
 
     MAX_FACT_CHAIN_ENTRIES,
+    CodingWriteError,
     FactReconcileOp,
     WorkingFact,
     WorkingFactDraft,
@@ -206,143 +213,10 @@ def _subject_conflict(new_subject: str, old_subject: str) -> bool:
 # General subject-isolation rules belong in the prompt; lookalike examples
 # encourage pattern matching instead of teaching the rule.
 
-FACT_RECONCILE_PROMPT = """\
-You maintain session-level WORKING FACTS. Each statement summarizes one whole
-trace/session: the user's task, the rough approach, and the result. It is not an
-atomic claim.
-
-Every new session fact below WILL be stored; that is not your decision. Your only
-job is to detect task continuation: is the new session continuing to advance the
-SAME user task as an existing session fact? If so, SUPERSEDE the older fact so
-the links form a cross-session progress chain for that task.
-
-Mark an existing fact as superseded ONLY when there is strong evidence that:
-  - The subjects match: both records are about the SAME entity — the same
-    person, the same file/module, the same host/service. A shared subject is
-    necessary but not sufficient; AND
-  - The user goal is materially the SAME, not merely in the same topic/project;
-    AND
-  - The new trace continues, retries, extends, verifies, or finishes the work
-    recorded by the existing trace.
-
-Do NOT supersede when:
-  - The two records name different subjects. Two people in one group, two files
-    in one module, two hosts in one cluster are PARALLEL, not successive: one
-    person's state is not a newer version of another's. Where a subject is shown
-    as (unspecified), fall back to judging by the statement alone.
-  - The sessions merely mention the same file, symbol, component, repository,
-    error, or technology but pursue different user goals.
-  - One task only supplies context or a technique for another task.
-  - The relationship is uncertain. Be conservative: INSERT is the safe default;
-    merging unrelated sessions destroys their separate task history.
-
-Treat each statement as evidence-bounded text. Do not reinterpret an inference
-inside it as an established cause or use a shared conjecture/error as proof that
-the user goals are the same. Your decision is only about task continuation; do
-not "correct", complete, or embellish either session record.
-
-Examples:
-  existing: "The user needed to fix CI's npm run build; traced it to
-             ERR_OSSL_EVP_UNSUPPORTED under Node 18, workflow not yet changed."
-  new:      "The user continued fixing the same CI build; raised Node in
-             .github/workflows/ci.yml to 20 and npm run build passed."
-                                                                 → SUPERSEDE
-
-  existing: "The user needed to fix JWT expiry handling in
-             auth/middleware.ts; refresh logic was added."
-  new:      "The user needed performance logging added to
-             auth/middleware.ts; a latency metric was introduced."
-                                                                 → keep both
-            (same file/project, different user goal)
-
-═══════════════════════════════════════════════════════════════════
-NEW SESSION FACTS
-═══════════════════════════════════════════════════════════════════
-{drafts_block}
-
-═══════════════════════════════════════════════════════════════════
-EXISTING SESSION FACTS (per new fact, retrieved by statement similarity)
-═══════════════════════════════════════════════════════════════════
-{candidates_block}
-
-═══════════════════════════════════════════════════════════════════
-OUTPUT (strict JSON only, no markdown)
-═══════════════════════════════════════════════════════════════════
-{{
-  "ops": [
-    {{"draft_idx": 0, "supersedes": ["fact_xxx"], "reason": "continues the same CI fix task"}},
-    {{"draft_idx": 1, "supersedes": []}}
-  ]
-}}
-
-Only use fact ids that appear in the candidate list for that same draft_idx.
-If nothing is superseded anywhere, output {{"ops": []}}.
-"""
+from ..prompts.en import CODING_FACT_RECONCILE_PROMPT as FACT_RECONCILE_PROMPT  # noqa: E402,F401  (re-export)
 
 
-CHAIN_SUMMARY_PROMPT = """\
-A user task in a working-memory store has progressed across sessions. Below are
-the session summaries in that task's progress chain, oldest first, ending with
-the current session.
-
-Summarize how the SAME task progressed across sessions to its current state.
-Cover every important stage in chronological order. For each stage, preserve
-where available: the actual action or change, its direct result, and any
-unresolved issue or limiting condition. End with an explicit current status.
-
-Rules:
-  - This is compression only. Report ONLY what the entries say; never add or
-    complete a command, cause, motive, action, test result, success state, or
-    global negative conclusion.
-  - Preserve evidence status exactly: attempted is not completed, observed is
-    not verified, inferred is not established, and unresolved stays unresolved.
-    Keep uncertainty words and search/permission/coverage limits.
-  - State the current ending status faithfully (completed, partially completed,
-    failed, blocked, or still awaiting verification). Never upgrade it based on
-    a plausible causal story or on a later entry that did not verify it.
-  - When entries mention a suspected cause and a later result, connect them
-    causally only if an entry directly says that cause was verified.
-  - Preserve concrete retrieval anchors: file paths, symbols, commands, error
-    strings, versions, config keys/values, and important numeric values that
-    matter to the progress.
-  - For chains of 2-3 generations, do not over-compress the progression into one
-    sentence. Prefer 2-4 compact paragraphs when useful, or readable prose with
-    a clear task goal, stage-by-stage progression, and current status.
-  - Do not mechanically copy the full history. Omit repetition and low-value
-    detail while retaining important actions, direct results, and leftovers.
-  - Do not invent stage headings or dates. Mention a date only when the entries
-    make it meaningful; bare timestamps are noise.
-  - If the entries say older revisions were omitted, explicitly state that
-    earlier history was omitted; do not imply the supplied entries are complete.
-  - Write in the same language the entries are written in.
-  - No preamble or enclosing quotes.
-
-Example
-  entries:
-    (2026-07-20) The user needed to fix CI's npm run build; traced it to
-                 ERR_OSSL_EVP_UNSUPPORTED under Node 18, workflow not yet
-                 changed.
-    (2026-07-24) The user continued that CI fix; raised Node in
-                 .github/workflows/ci.yml to 20, but the dependency cache
-                 still reproduced the old error.
-    (now)        The user continued verifying the same fix; after clearing the
-                 npm cache, npm run build passed.
-  output:
-    The task goal is fixing CI's npm run build. It was first traced to
-    ERR_OSSL_EVP_UNSUPPORTED under Node 18, with the workflow not yet changed;
-    then .github/workflows/ci.yml was raised to Node 20, but the dependency
-    cache kept the old error present. Finally, after clearing the npm cache,
-    npm run build passed, so this build fix is currently verified as complete.
-
-═══════════════════════════════════════════════════════════════════
-ENTRIES
-═══════════════════════════════════════════════════════════════════
-{chain_block}
-
-═══════════════════════════════════════════════════════════════════
-OUTPUT (the summary itself, nothing else)
-═══════════════════════════════════════════════════════════════════
-"""
+from ..prompts.en import CODING_CHAIN_SUMMARY_PROMPT as CHAIN_SUMMARY_PROMPT  # noqa: E402,F401  (re-export)
 
 
 def _fact_drafts_language_text(drafts: List[WorkingFactDraft]) -> str:
@@ -357,37 +231,44 @@ def _fact_drafts_language_text(drafts: List[WorkingFactDraft]) -> str:
 def build_fact_reconcile_prompt(
     drafts: List[WorkingFactDraft],
     candidates: List[List[WorkingFact]],
+    language: Optional[str] = None,
 ) -> Tuple[str, str]:
-    """Return the language-matched fact reconcile prompt and language."""
-    if is_chinese(_fact_drafts_language_text(drafts)):
-        from .prompts_zh import FACT_RECONCILE_PROMPT_ZH
+    """Return the fact reconcile prompt and its language code.
 
-        template = FACT_RECONCILE_PROMPT_ZH
-        language = "zh"
-    else:
-        template = FACT_RECONCILE_PROMPT
-        language = "en"
-    return template.format(
+    Explicit ``language`` wins; otherwise zh/en auto-detection over the drafts.
+    """
+    explicit = normalize_language(language)
+    code = resolve_language(explicit, _fact_drafts_language_text(drafts))
+    prompt = get_prompt("CODING_FACT_RECONCILE_PROMPT", code).format(
         drafts_block=WorkingFactReconciler._format_drafts(drafts),
         candidates_block=WorkingFactReconciler._format_candidates(drafts, candidates),
-    ), language
+    )
+    return with_output_language(prompt, code, explicit=explicit is not None), code
 
 
 def build_chain_summary_prompt(
     chain_block: str,
     *,
     current_statement: str,
+    language: Optional[str] = None,
 ) -> Tuple[str, str]:
-    """Return the language-matched cross-session summary prompt and language."""
-    if is_chinese(current_statement or chain_block):
-        from .prompts_zh import CHAIN_SUMMARY_PROMPT_ZH
+    """Return the cross-session summary prompt and its language code."""
+    explicit = normalize_language(language)
+    code = resolve_language(explicit, current_statement or chain_block)
+    prompt = get_prompt("CODING_CHAIN_SUMMARY_PROMPT", code).format(
+        chain_block=chain_block,
+    )
+    return with_output_language(prompt, code, explicit=explicit is not None), code
 
-        template = CHAIN_SUMMARY_PROMPT_ZH
-        language = "zh"
-    else:
-        template = CHAIN_SUMMARY_PROMPT
-        language = "en"
-    return template.format(chain_block=chain_block), language
+
+@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)
 
 
 # ================================================================
@@ -455,16 +336,66 @@ class WorkingFactReconciler:
         branch: Optional[str] = None,
         source: str = "default",
         memory_at: Optional[datetime] = None,
+        language: Optional[str] = None,
     ) -> Tuple[List[WorkingFact], List[FactReconcileOp]]:
         """
-        执行 reconcile + 持久化。memory_at 是这段对话的时间，记到新事实上。
+        执行 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,
@@ -477,27 +408,38 @@ class WorkingFactReconciler:
         )
 
         try:
-            supersedes = await self._llm_decide(drafts, candidates)
+            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,
+            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
@@ -588,18 +530,24 @@ class WorkingFactReconciler:
         self,
         drafts: List[WorkingFactDraft],
         candidates: List[List[WorkingFact]],
+        language: Optional[str] = None,
     ) -> Dict[int, List[str]]:
         """返回 {draft_idx: [被它覆盖的旧 fact_id, ...]}。"""
         # 一条候选都没有就没得判，省一次 LLM 调用
         if not any(candidates):
             return {}
 
-        prompt, _ = build_fact_reconcile_prompt(drafts, candidates)
+        prompt, _ = build_fact_reconcile_prompt(drafts, candidates, language=language)
         resp = await self.llm_provider.complete(
             prompt=prompt,
             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)
 
     # ------------------------------------------------------------
@@ -638,7 +586,8 @@ class WorkingFactReconciler:
         return ordered[-MAX_FACT_CHAIN_ENTRIES:], truncated
 
     async def _summarize_chain(
-        self, history: List[WorkingFact], current: str, *, truncated: bool = False
+        self, history: List[WorkingFact], current: str, *, truncated: bool = False,
+        language: Optional[str] = None,
     ) -> str:
         """让 LLM 把同一任务的跨 session 进展写成简短摘要。
 
@@ -659,6 +608,7 @@ class WorkingFactReconciler:
         prompt, _ = build_chain_summary_prompt(
             "\n".join(rows),
             current_statement=current,
+            language=language,
         )
 
         try:
@@ -724,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("```"):
@@ -746,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)"
@@ -790,6 +760,7 @@ class WorkingFactReconciler:
         branch: Optional[str] = None,
         source: str = "default",
         memory_at: Optional[datetime] = None,
+        language: Optional[str] = None,
     ) -> Tuple[List[WorkingFact], List[FactReconcileOp]]:
         inserted: List[WorkingFact] = []
         ops: List[FactReconcileOp] = []
@@ -813,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, [])
@@ -873,7 +849,8 @@ class WorkingFactReconciler:
                     retired, user_id=user_id
                 )
                 new_fact.fact_chain_summary = await self._summarize_chain(
-                    history, new_fact.statement, truncated=truncated
+                    history, new_fact.statement, truncated=truncated,
+                    language=language,
                 )
                 # 摘要之外再把历代自己的 details 原样过继一份。摘要保叙事，过继保数值，
                 # 两者不重复：details 本来就不进摘要（_collect_history 只读 statement）。
@@ -892,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/preproc.py

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

hy_memory/coding/prompts_zh.py

@@ -1,745 +1,13 @@
 # -*- coding: utf-8 -*-
-"""HY Memory working/coding 链路使用的中文提示词模板。"""
+"""HY Memory working/coding 链路使用的中文提示词模板（兼容入口）。
 
-
-EXTRACT_PROMPT_ZH = """\
-你需要从一段任务执行会话中抽取可长期保留的 WORKING 记忆。
-“working”会话是指用户通过工具操作计算机或系统的任何实操任务——既包括软件/代码
-工作（编写、调试、重构、构建、部署、API/library 使用），也包括系统与运维工作
-（运行 shell/PowerShell 命令、磁盘/存储分析或清理、文件与文件夹操作、安装/配置
-软件、环境/设备设置、硬件/磁盘健康检查、备份、调度/自动化、数据处理）。
-
-你需要从同一段会话中产出两个层次：
-
-  EXPERIENCES（过程性，“如何做”）——可复用的方法；只有达到下述 VALUE BAR 时才
-  抽取。每条是一个 (task, search_keys, solution, boundary_envs) 组合。
-
-  FACT（情节性，“这次发生了什么”）——关于本次会话的恰好一条记录：用户想做什么、
-  大致如何推进、最终结果如何。它不受价值门槛限制，但绝不能超过一条。
-
-这两个层次回答不同问题，并分别存储。可泛化的方法放入 EXPERIENCES；只对这个系统、
-这个项目、此时此刻成立的本次会话经历放入 FACT。
-
-═══════════════════════════════════════════════════════════════════
-VALUE BAR（仅适用于 EXPERIENCES）——不要轻易越过此门槛。
-═══════════════════════════════════════════════════════════════════
-一条记忆必须同时满足以下全部条件：
-  (a) 解决了同一用户以后很可能再次遇到的问题
-  (b) 解决方案并非琐碎操作：它组合了多项信息/多个步骤，或者包含决策理由，或者记录了
-      来之不易的 workaround，或者是某项运维任务的可复用流程/配方（例如如何分析并
-      清理磁盘占用、如何批量整理文件、如何检查硬件健康、如何设置 scheduled job）
-  (c) 未来的 agent / 用户会更愿意查阅它，而不是重新摸索
-
-重要——分析、诊断、调查任务也算：
-一项任务不必实际修改或“修复”任何东西才值得记忆。只读、分析、故障排查工作，只要其
-流程或结论可复用，就有价值。明确抽取：
-  - 分析/诊断配方：可复用的流程以及它揭示的结果（例如“如何分析哪些文件夹占用了
-    C-drive 空间”——扫描命令、遇到的坑和最终发现）。“只生成了报告，没有修改”
-    不是跳过理由——可复用的方法本身就是记忆。
-  - 调查结果，包括否定结果或未找到结果（例如“使用 rg / fs_search / SQL index
-    在 C: 和 D: 中搜索 folder X——任何位置都未找到”）。记录一条死路可以避免下一个
-    agent 重复同样无果的搜索，因此达到了价值门槛。
-不要仅仅因为“assistant 可以重新生成这些命令”或“实际上没有修改任何东西”就拒绝
-一条记忆。只要流程或结论能节省未来的工作，就保留它。
-
-不要抽取：
-  - 没有可复用流程、真正琐碎的单步操作（“rename one file”、“git status”、
-    “run ls once”）
-  - 已经解决且没有可迁移经验的一次性问题
-  - repo/system 中已经存在的信息（不要重复 package.json）
-  - 每个 PR / 每次会话的一次性任务，除非其中编码了可复用模式
-  - 向用户询问缺失信息这一行为。请求参数、列出未知项或引导用户提供必填字段属于
-    对话行为，不是方法：每个 agent 都知道如何提问，因此以后没有任何值得查阅的内容。
-    绝不要产出 task 或 search_keys 形如“how to ask for X”、“gather the missing Y”、
-    “eliciting required fields”、“what to clarify before starting”的 experience。
-    注意，这条限制只适用于 EXPERIENCES——会话最终停在等待用户的状态是真实状态，
-    应写入 FACT。
-
-如果该段会话因为等待用户而没有取得任何实质进展——assistant 只是询问参数，或者在
-开展任何实际工作前就被阻塞——输出 "experiences": []，只写 FACT。此时尚未学到任何
-东西，因此没有方法可存。这一点比看起来更重要：从停滞中提炼出的 experience 在检索时
-会像一项真正的技能；同一任务的后续片段会匹配它，再次向用户提问而不是继续推进，导致
-这种停滞在余下会话中不断自我复制。应根据工具实际做了什么判断是否有实质进展，而不是
-根据该轮是否生成了流畅文本。
-
-启发式标准：如果用户（或未来执行同类任务的 agent）希望把它记下来，而不是以后再重新
-摸索，就保留。多步骤运维流程通常符合条件——包括 system/ops 或只读分析/搜索流程，
-不局限于代码。只有当它只是任何用户都能在 30 秒内通过 `--help` 找到的单条命令，并且
-不包含值得记忆的决策或坑点时，才丢弃。
-
-═══════════════════════════════════════════════════════════════════
-EXPERIENCE 字段
-═══════════════════════════════════════════════════════════════════
-
-task          — 采用查询式名称；写成用户以后会如何提问。
-                使用“publish a release to the xx platform”，不要使用
-                “publish_release_internal”。
-                必须自包含（不要使用“this”、“the file”、“we”）。
-
-search_keys   — 0 到 5 种替代表述，用来覆盖仅靠 `task` 无法匹配、但对 solution 很
-                重要的方面。写成未来用户会询问的问题或主题，且必须与 task 有区别。
-                如果 task 已覆盖全部内容，则省略。
-
-solution      — 用户实际需要的完整、自包含内容：命令、凭据位置（不是凭据值）、
-                文件路径、有序步骤、坑点、决策理由。如果多轮端到端工作构成一个连贯
-                任务，应聚合成一个 solution；只有用户执行了互不相关的任务时才拆成
-                多条记忆。
-
-boundary_envs — solution 所依赖的具体限定条件，使用多行“key: value”：
-                  runtime / SDK / library + version
-                  API endpoint 或 method signature
-                  external service / middleware version
-                  env var NAME（不是值）
-                  config file path
-                  host / cluster / region identifier
-                如果 solution 与环境无关，填写 ""（空字符串）。
-                目的：底层 SDK/middleware 升级后，未来使用者可以据此判断 solution
-                是否仍然适用。
-
-confidence  — 0.0 到 1.0
-  1.0   用户明确将其陈述为规则/指令
-  0.7   根据工具操作及充分证据推断
-  0.5   弱推断；只有一次观察；不确定
-
-═══════════════════════════════════════════════════════════════════
-FACT 字段——每段会话恰好一条，无价值门槛
-═══════════════════════════════════════════════════════════════════
-
-你要为整段会话写一条 FACT——它是本次会话可恢复的状态记录，不是精心润色的回顾，也
-绝不是分散发现的列表。未来 agent 必须能够从中继续推进，且不会把建议、推断或局部搜索
-误认为已经验证的事实。
-
-subject    — 本次会话围绕谁或什么展开：工作所针对或服务的单一实体。使用简短名词
-             短语，不要写句子，不要使用动词。选择会话真正围绕的最具体实体，而不是
-             所使用的工具：
-               会话服务于某个具名人员时，使用人名
-                 （“Dylan”、“Matthew”）
-               工作针对代码时，使用 file / module / symbol
-                 （“auth/middleware.ts”、“parse_plan_text”）
-               运维工作使用 service / host / device / drive
-                 （“D:\\WXWork”、“redis-cache-prod”、“ci.yml”）
-             这是 HARD KEY，不是散文：关于不同人员或不同文件的两次会话必须得到不同
-             subject；关于同一实体的两次会话必须得到拼写完全一致的同一字符串。
-             优先使用 trace 中出现的精确标识符，而不是对它的描述。如果该段确实没有
-             单一 subject，输出 ""。
-
-             这很重要：subject 是决定后续会话是否可以按“同一任务的继续”覆盖本条
-             记录的闸门。填错后，一个人的状态可能静默替换另一个人的状态。
-
-statement  — 本次会话的紧凑记录。它分为两部分，而第二部分最容易丢失。
-             保留任务范围内的给定量和具体约束，不要用泛泛的结果评价取代它们。
-             每条规则只写一次：重复的指令文字会挤占记忆真正需要保留的数据。
-
-             PART 1——发生了什么，约 300 个拉丁字符（约 150 个 CJK 字符）。
-             从具体目标和对象开始（“reclaim disk space taken by D:\\WXWork”、
-             “locate the new_file_search folder”），不要写泛泛的“fix a bug”/
-             “find a file”。然后概述检查、尝试或修改了什么。最后说明结束状态，
-             且语义必须精确对应以下之一：completed、partially completed、failed、
-             blocked、still awaiting verification。纳入否定结果和死路，但不要夸大。
-
-             PART 2——TASK-SCOPED GIVENS：整个任务赖以运行的全部给定信息，即使并非
-             本段会话建立，或看起来基础到不值得写。包括绑定关系（每个 name/symbol/
-             label 代表什么）、任务提供而不是推导出的固定值、采用的约定（indexing
-             base、units、timezone、defaults），以及本段自己的结果和值（写“x = 7”，
-             不要只写“the value was computed”）。
-
-             将 PART 2 写成数据，每行一项，值保持给定形式：
-               retry budget = 5; timeout 30s; index starts at 0
-               step 3 input: n=64, tolerance 1e-6
-               slot B: type=private, cost 688.7-721.3 per unit
-             每一行几乎都应由值构成。保留 trace 的 notation——symbols、units、
-             numbers、spellings——删掉其句子外壳：去掉那些只是宣告“这是给定量”的
-             短语，而非给定量本身（“I would prefer”、“it should be somewhere
-             between … and …”）。这些短语会在每项重复；一个 15 项列表会为它们
-             支付 15 次空间成本。
-             每一条 FACT 都要携带这些信息；绝不要写“as above”或“same as the
-             previous session”——检索只会按相似度返回少量 facts，被指代项可能不在
-             其中。
-
-             总长度尽量控制在 1200 字符以内。如果 PART 2 放不下，应优化 notation，
-             绝不能削减覆盖范围：statement 是 retrieval vector，也是后续 segment
-             唯一能读到的字段（details 既不做 embedding，也不会被注入），因此从中
-             删除的内容就永久丢失。压缩给定量周围的措辞，绝不要压缩给定量本身。
-
-             检验标准：如果下一段看不到原始材料，能否仅凭此记录继续任务？只有肯定
-             答案才合格。缺失 binding 不会明显报错——该名称仍看起来有意义，于是会
-             按其通用含义被理解，后续答案可以很流畅，却回答了另一个问题。
-
-             LANGUAGE——使用与 session trace 相同的语言：statement 是 retrieval
-             vector，而查询会使用用户的工作语言；改用另一种语言会让每次检索都付出
-             跨语言匹配损失。
-
-             EVIDENCE FIDELITY——只记录 trace 中实际执行的操作和明确存在的证据。
-             对关键命令、flags、arguments、errors、numbers 保持原样。
-             绝不要按惯例补全命令 flags，也不要把建议或计划写成已经执行的动作：
-               “ran Get-ChildItem -Force” → “ran Get-ChildItem”
-                 （trace 中没有 `-Force`，不要杜撰）
-             每个否定发现都必须限定在实际搜索范围内，并逐一列出可能使其失效的所有
-             明确覆盖限制，尤其是 permission failures 和 depth limits：保留当时的
-             roots、filters、depth（“not found under C:\\ and D:\\ at depth 3;
-             some directories were not covered due to Access denied”），绝不要扩大为
-             “does not exist”。不要为了让记录更漂亮而漏掉任何限制。
-             绝不要把局部搜索提升为全局不存在。
-             被阻塞的尝试必须保留其 blocker。
-             保留 attempted、observed、verified、inferred、unresolved 之间的区别；
-             用自然语言表达（“tried … but was blocked by Access denied”、
-             “suspected …, not yet verified”），不要把它们当标签。没有工具输出或
-             明确确认时，绝不要声称修复已成功、原因已确定或路径不存在。
-
-             不要记录问候或纯闲聊——只有这种情况才输出 "fact": null。仅仅陈述了
-             要求，或尚未开展工作就停滞的会话，仍然建立了信息。
-
-details    — 本次会话的具体 OUTPUT，逐字复制。`statement` 是摘要，而摘要必然会
-             丢掉各个具体值；后续检索几乎总是在寻找某个具体值，而非大意。因此，只要
-             会话产出了可寻址的结果，就以原始形式和结构复现在这里：
-               plan / schedule / itinerary → 每一行、每一天、每个 slot、每个 price
-                 都严格按原文保留
-               config 或 code block → 保留整个 block
-               command 的关键 output → 保留承载发现的行（sizes、counts、versions、
-                 error text）
-               structured result（table、records list）→ 保留各行
-             保留原始布局——line breaks、`Day 1:` / key: value prefixes、units、
-             currency symbols、ids。不要再次概括，不要重排，不要舍入数字，不要翻译。
-
-             只复制 trace 中实际存在的内容。绝不要填补空缺：如果某个 slot 没有填，
-             就保持未填或明确说明——杜撰的值比缺失的值更糟，因为它会被检索并使用。
-             长度控制在约 4000 字符；如果输出更长，保留承载具体值的部分，删去装饰性
-             文字，并注明删掉了什么。
-
-             如果本次会话未产生此类 artifact（尚无发现的纯调查，或等待用户导致的
-             停滞），填写 ""。
-
-             此字段不属于 retrieval vector——`statement` 和 `subject` 负责找到
-             记录，`details` 在找到后提供具体值。因此不要在此堆砌检索诱饵，也不要
-             重复摘要；只写原始内容。
-
-files      — 0..N 个本次会话中实际操作或调查过的绝对或 repo-relative FILE OR
-             DIRECTORY paths。保留调查过的 roots，例如 `C:\\` 和 `D:\\`。只包含
-             实际访问/搜索过的路径，不包含仅建议或计划访问的路径；不适用时填写 []。
-═══════════════════════════════════════════════════════════════════
-HOST CONTEXT（由 SDK 提供）
-═══════════════════════════════════════════════════════════════════
-- workspace_id present: {workspace_present}
-- branch present: {branch_present}
-
-没有 workspace_id 时，solution 不能依赖未声明的项目本地上下文——必须在 `solution`
-或 `boundary_envs` 中明确写出其所需的 repo / path / service，使记忆能够独立使用。
-
-═══════════════════════════════════════════════════════════════════
-CONVERSATION
-═══════════════════════════════════════════════════════════════════
-{conversation_block}
-
-═══════════════════════════════════════════════════════════════════
-OUTPUT（仅输出严格 JSON，不要 markdown）
-═══════════════════════════════════════════════════════════════════
-{{
-  "experiences": [
-    {{
-      "task": "...",
-      "search_keys": ["...", "..."],
-      "solution": "...",
-      "boundary_envs": "...",
-      "confidence": 0.9
-    }}
-  ],
-  "fact": {{
-    "subject": "...",
-    "statement": "...",
-    "files": ["..."],
-    "details": "..."
-  }}
-}}
-
-默认应进行抽取。当该段会话确实完成了实际工作时，必须输出至少一条 experience——即使
-任务看似简单或一次成功，也要记录所做工作的可复用本质（method / command / how-to）。
-会话内容较少时，只保留最有价值的一条 experience 即可。
-
-唯一例外是上述停滞情况：如果该段因为缺少信息、被阻塞在向用户提问而没有开展实际工作，
-输出 "experiences": []，只写 fact。不要为了满足本指令而杜撰 experience——杜撰的
-“how to ask for the departure city”比没有记忆更糟，因为以后会被检索并照做。只有这个
-原因允许空数组；实际开展过工作时，绝不能把空数组当捷径。
-
-"fact" 是单个对象，绝不是列表——每次会话一条记录。
-
-始终写 fact。fact 的门槛不是“这是否有价值”，而是“是否发生了任何事情”；能够到达
-你的 segment 已经越过这条门槛。这包括看起来只是 setup 而非工作的片段：仅有一条用户
-消息陈述 requirements、parameters 或 starting state，即使没有运行工具，也恰恰是后续
-会话无法自行重建的材料——把需求、参数、起始状态连同情形一起写进 `statement`（紧凑
-记法，不要照抄对话原句），不要推给 `details`（`details` 不进检索向量，读取侧也不再
-注入它）。只有完全没有内容的问候和纯闲聊才使用 "fact": null。有疑问时应写 fact：
-多余记录只多占一行，而漏掉记录会伤害每一次需要它、却无从知道它曾存在的后续会话。
+文本已迁到 ``hy_memory/prompts/zh_hans.py``（``CODING_*``），这里保留旧名字。
 """
 
-
-EXTRACT_PROMPT_CODING_ZH = """\
-╔═══════════════════════════════════════════════════════════════════════════╗
-║ HARD CONSTRAINT——先阅读本节；它覆盖本提示词后文任何看似要求叙事的措辞。      ║
-║                                                                           ║
-║ 你不是在撰写某个人做过什么的报告。你要写的是 FUTURE AGENT 为采取行动所需要 ║
-║ 的信息。该 agent 已有自己的任务；它不关心这个用户想要什么。它需要知道：此处 ║
-║ 做出了什么决定、位于哪些代码坐标、尝试并否决了什么，以及是否经过验证。       ║
-║                                                                           ║
-║ 具体来说，每个 `statement` 和每个 `solution` 都必须遵守：                 ║
-║   · 语法主语必须是 CODE 或 THE DECISION——绝不能是“the user”，也绝不能是   ║
-║     “the agent”。不要写“The user attempted to…”、“The user wanted…”、   ║
-║     “The agent then checked…”。                                           ║
-║   · 绝不要用“the session was completed”、“the error was noted”、         ║
-║     “no solution was found yet”之类流水账短语收尾。结尾应写决定及其验证    ║
-║     状态。如果没有做出决定，就以已排除的内容和下一条尚未探索的线索收尾——这才 ║
-║     是可复用部分。                                                        ║
-║   · 保留具体症状（error string、failing command、wrong output）——未来搜索 ║
-║     正是通过这些内容命中。                                                ║
-║                                                                           ║
-║ bad:  “The user attempted to write a QTable to RST with header_rows and   ║
-║        hit a TypeError. The session was completed with the error noted.”  ║
-║ good: “ascii.rst's RST writer rejects header_rows:                        ║
-║        `tbl.write(..., format='ascii.rst', header_rows=['name','unit'])`  ║
-║        raises TypeError because RST.__init__ does not forward it, unlike  ║
-║        ascii.fixed_width which accepts it. No fix written — the writer    ║
-║        needs the same header_rows plumbing as fixed_width.”               ║
-╚═══════════════════════════════════════════════════════════════════════════╝
-
-你需要从一段任务执行会话中抽取可长期保留的 WORKING 记忆。
-“working”会话是指用户通过工具操作计算机或系统的任何实操任务——既包括软件/代码
-工作（编写、调试、重构、构建、部署、API/library 使用），也包括系统与运维工作
-（运行 shell/PowerShell 命令、磁盘/存储分析或清理、文件与文件夹操作、安装/配置
-软件、环境/设备设置、硬件/磁盘健康检查、备份、调度/自动化、数据处理）。
-
-你需要从同一段会话中产出两个层次：
-
-  EXPERIENCES（过程性，“如何做”）——可复用的方法；只有达到下述 VALUE BAR 时才
-  抽取。每条是一个 (task, search_keys, solution, boundary_envs) 组合。
-
-  FACT（情节性，“这次确立了什么”）——关于本次会话的恰好一条记录。它不是用户做了
-  什么的叙事，而要按以下顺序记录：任务及其具体症状（使它以后能被检索到）、代码坐标、
-  最终采用了什么以及拒绝了什么、验证推进到什么程度。它不受价值门槛限制，但绝不能
-  超过一条。
-
-这两个层次回答不同问题，并分别存储。可泛化的方法放入 EXPERIENCES；只对这个系统、
-这个项目、此时此刻成立的本次会话经历放入 FACT。
-
-═══════════════════════════════════════════════════════════════════
-VALUE BAR（仅适用于 EXPERIENCES）——不要轻易越过此门槛。
-═══════════════════════════════════════════════════════════════════
-一条记忆必须同时满足以下全部条件：
-  (a) 解决了同一用户以后很可能再次遇到的问题
-  (b) 解决方案并非琐碎操作：它组合了多项信息/多个步骤，或者包含决策理由，或者记录了
-      来之不易的 workaround，或者是某项运维任务的可复用流程/配方（例如如何分析并
-      清理磁盘占用、如何批量整理文件、如何检查硬件健康、如何设置 scheduled job）
-  (c) 未来的 agent / 用户会更愿意查阅它，而不是重新摸索
-
-重要——分析、诊断、调查任务也算：
-一项任务不必实际修改或“修复”任何东西才值得记忆。只读、分析、故障排查工作，只要其
-流程或结论可复用，就有价值。明确抽取：
-  - 分析/诊断配方：可复用的流程以及它揭示的结果（例如“如何分析哪些文件夹占用了
-    C-drive 空间”——扫描命令、遇到的坑和最终发现）。“只生成了报告，没有修改”
-    不是跳过理由——可复用的方法本身就是记忆。
-  - 调查结果，包括否定结果或未找到结果（例如“使用 rg / fs_search / SQL index
-    在 C: 和 D: 中搜索 folder X——任何位置都未找到”）。记录一条死路可以避免下一个
-    agent 重复同样无果的搜索，因此达到了价值门槛。
-不要仅仅因为“assistant 可以重新生成这些命令”或“实际上没有修改任何东西”就拒绝
-一条记忆。只要流程或结论能节省未来的工作，就保留它。
-
-不要抽取：
-  - 没有可复用流程、真正琐碎的单步操作（“rename one file”、“git status”、
-    “run ls once”）
-  - 已经解决且没有可迁移经验的一次性问题
-  - repo/system 中已经存在的信息（不要重复 package.json）
-  - 每个 PR / 每次会话的一次性任务，除非其中编码了可复用模式
-
-启发式标准：如果用户（或未来执行同类任务的 agent）希望把它记下来，而不是以后再重新
-摸索，就保留。多步骤运维流程通常符合条件——包括 system/ops 或只读分析/搜索流程，
-不局限于代码。只有当它只是任何用户都能在 30 秒内通过 `--help` 找到的单条命令，并且
-不包含值得记忆的决策或坑点时，才丢弃。
-
-═══════════════════════════════════════════════════════════════════
-CODE WORK——未来 agent 无法重新推导的信息，因此必须捕获
-═══════════════════════════════════════════════════════════════════
-当该段是针对 repository 的软件工作时，可复用方法只占一半。另一半是工作位于哪里，
-以及哪个版本胜出。这些无法通过以后阅读代码恢复——代码只能展示当前状态，无法说明它
-位于哪个 branch，也无法说明哪些方案已被否决。
-
-本节不是要求写得更长，而是要求把相同预算花在价值更高的 token 上：删掉重复目标、
-assistant“随后决定”做什么的叙事，以及只是复述的粘贴代码；把这些字符用于下面四项。
-一条遗漏 branch、却引用 30 行 diff 的记录是糟糕的取舍。
-
-1. BRANCH / WORKING LOCATION——逐字写入 fact `statement`。如果该段提到或 checkout
-   了 `feat/x` / `fix/y`，这个 token 必须出现。在错误 branch 上恢复工作的 agent
-   会产生随后被静默丢弃的改动，因此这一个 token 的优先级高于其他任何细节。
-
-2. WHICH VERSION WON——当用户改变主意时，用一个分句指出胜出者并标记落败者：
-   “settled on A; the interim B was dropped”。不要完整保留两个版本，只需一个分句。
-   只保留最新版本是错误的：以后遇到被否决代码的 agent 必须识别它，否则会把代码
-   “修复”回已经丢弃的变体。`scratch that / go back to / actually, let's / no, not that`
-   之类措辞就是标志：后面的内容才是正式结论，前面的内容已被 superseded。
-
-3. EXACT COORDINATES, NOT PASTED CODE——使用 repo-relative path
-   （`qutebrowser/utils/debug.py`，绝不要只写 `debug.py`）以及触及的 function /
-   class。如果 signature 发生变化，给出新的 signature。如果决定的是 constant、regex
-   或 literal，逐字引用它——但只引用这一项，不要引用周围 block。准确的一行胜过一段
-   近似描述。
-
-4. VERIFIED vs MERELY WRITTEN——四个词就足够（“tests run and passing”/
-   “confirmed by git diff only, tests not run”）。“the edit is in”和“the edit is in
-   and tested”会让未来 agent 采取完全不同的下一步。
-
-反例——只总结目标，却丢掉坐标：
-  bad:  “refactored the colour parsing logic to be cleaner.”
-  good: “on feat/q4, in qutebrowser/config/configtypes.py QtColor._parse_value:
-         settled on `mult = 360.0 if kind == 'h' else 255.0`; the interim version that
-         used 255.0 for everything was dropped. Tests not run.”
-  （good 往往比 bad 还短——它只是把每个字符都用在无法重新推导的信息上）
-
-═══════════════════════════════════════════════════════════════════
-EXPERIENCE 字段
-═══════════════════════════════════════════════════════════════════
-
-task          — 采用查询式名称；写成用户以后会如何提问。
-                使用“publish a release to the xx platform”，不要使用
-                “publish_release_internal”。
-                必须自包含（不要使用“this”、“the file”、“we”）。
-
-search_keys   — 0 到 5 种替代表述，用来覆盖仅靠 `task` 无法匹配、但对 solution 很
-                重要的方面。写成未来用户会询问的问题或主题，且必须与 task 有区别。
-                如果 task 已覆盖全部内容，则省略。
-
-solution      — 用户实际需要的完整、自包含内容：命令、凭据位置（不是凭据值）、
-                文件路径、有序步骤、坑点、决策理由。如果多轮端到端工作构成一个连贯
-                任务，应聚合成一个 solution；只有用户执行了互不相关的任务时才拆成
-                多条记忆。
-
-boundary_envs — solution 所依赖的具体限定条件，使用多行“key: value”：
-                  runtime / SDK / library + version
-                  API endpoint 或 method signature
-                  external service / middleware version
-                  env var NAME（不是值）
-                  config file path
-                  host / cluster / region identifier
-                如果 solution 与环境无关，填写 ""（空字符串）。
-                目的：底层 SDK/middleware 升级后，未来使用者可以据此判断 solution
-                是否仍然适用。
-
-confidence  — 0.0 到 1.0
-  1.0   用户明确将其陈述为规则/指令
-  0.7   根据工具操作及充分证据推断
-  0.5   弱推断；只有一次观察；不确定
-
-═══════════════════════════════════════════════════════════════════
-FACT 字段——每段会话恰好一条，无价值门槛
-═══════════════════════════════════════════════════════════════════
-
-你要为整段会话写一条 FACT——它是本次会话可恢复的状态记录，不是精心润色的回顾，也
-绝不是分散发现的列表。未来 agent 必须能够从中继续推进，且不会把建议、推断或局部搜索
-误认为已经验证的事实。
-
-statement  — 本次会话的紧凑摘要。它同时承担两个职责，且两者都必须完成：它既是
-             retrieval vector（未来 agent 用一份新 issue report 搜索它；措辞方式
-             与用户报告问题的方式一致），也是该 agent 找到后要据以行动的 payload。
-             因此：
-
-             开头写任务和症状，使用用户会使用的措辞。
-                这是保证可检索性的关键——表述应尽量贴近问题被报告时的表面形式。
-                点明具体目标和对象（“reclaim disk space under D:\\WXWork”、
-                “adjust the hue multiplier in QtColor._parse_value on feat/q4”、
-                “locate the new_file_search folder”），绝不要写泛泛的“fix a bug”/
-                “look for a file”。包含具体症状：error string、failing command、
-                wrong output。
-
-             然后给出坐标和决定。
-                对代码工作写 repo-relative path、symbol 和 branch。说明最终 SETTLED ON
-                什么，并在同一分句标记丢弃了什么（“settled on X; the interim Y was
-                dropped”）。这部分无法通过阅读代码重新推导——代码只展示胜出者，从不
-                展示 Y 曾被尝试后否决。以后遇到被否决变体的 agent 必须能识别它，
-                否则会把代码“修复”回已丢弃版本。
-
-             结尾写证据状态。
-                必须精确对应以下之一：completed、partially completed、failed、blocked、
-                still awaiting verification；还要写明如何检查（“tests run and passing”/
-                “confirmed by git diff only, tests not run”）。纳入否定结果和死路，
-                但不要夸大。
-
-             ⚠️ 绝不要停留在叙事层。“The user tried X and hit error Y; no solution found
-             yet”是一条浪费的记录：它容易被检索到，却不能指导未来 agent 行动。如果
-             本次确实没有得出决定，就说明排除了什么、下一条尚未探索的线索是什么——
-             这才是可复用部分。
-
-             句子的主语应是 code 和 decision，而不是“the user”。使用 2 到 4 个连贯
-             句子，不要写带标签的小节。硬上限约 400 个拉丁字符（约 200 个 CJK 字符）。
-
-             EVIDENCE FIDELITY——强制要求：
-             - 只记录 trace 中实际执行的操作和明确存在的证据。对关键 commands、flags、
-               arguments、errors、numbers 保持原样。绝不要按惯例补全 command flags，
-               也不要把 advice/plans 写成已执行的动作。
-             - 保留 attempted、observed、verified、inferred、unresolved 之间的区别。
-               不要把这些词作为标签写进正文；自然表达其含义，例如“tried … but was
-               blocked by Access denied”或“suspect …, not yet verified”。
-             - 没有工具输出或明确确认时，绝不要声称修复成功、原因已经确定、file/folder
-               不存在或 tests passed。
-             - 每个否定发现都必须限定在实际搜索范围内，并逐一列出可能使其失效的所有
-               明确覆盖限制，尤其是 permission failures 和 maximum search depth：
-               “not found within the searched parts of C:\\ and D:\\; some directories
-               were skipped on Access denied, and the search was also depth-limited”。
-               不要为了摘要更漂亮而漏掉任何限制。绝不要把局部搜索提升为全局不存在。
-             - 只有 trace 直接验证了因果关系时，才能确定地陈述因果。否则保留限定词
-               （“suspected”/“inferred”/“not yet verified”）；不要把错误的测试假设
-               改写成系统的 root cause。
-
-             关键——这段文字就是 retrieval vector，也是未来 query 唯一会匹配的内容。
-             泛泛摘要毫无价值，因为每次会话看起来都像泛泛摘要：它会匹配所有查询，
-             却无法回答任何一个。因此必须写出使本次会话可检索的具体 anchors——真实
-             file paths、function / symbol names、branch names、commands、error strings、
-             versions、config keys and values、host / service names。以后有人搜索其中任一
-             具体项时，本摘要必须能被返回。
-               good: “fixing a failing `npm run build` in CI. Read
-                      .github/workflows/ci.yml and package.json; traced it to webpack
-                      5.74 hitting ERR_OSSL_EVP_UNSUPPORTED under node 18. Bumping the
-                      workflow's node to 20 made the build pass; node 18 still
-                      reproduces locally.”
-               good: “on branch feat/q0, in qutebrowser/utils/debug.py signal_name:
-                      PyQt<5.11 only exposes the name via repr(sig), and repr comes in
-                      both a bracketed and a parenthesised form. Settled on two patterns
-                      tried in order with fullmatch, breaking on the first hit; the
-                      single-regex version was dropped. Confirmed by git diff, tests not
-                      run.”
-               bad:  “user wanted a build bug fixed, the agent looked at some config
-                      files, changed some code, and fixed it.”
-                      （没有 path、command、error string、version——没有任何可检索锚点；
-                       每次会话都可以写成这样）
-               bad:  “fixed the signal-name parsing compatibility issue on a feature
-                      branch.”
-                      （哪个 branch？哪个 file？哪个 function？两个竞争版本中谁胜出？
-                       一周后检索到它时，没有任何信息仍然有用）
-             忠实度示例（bad → good）：
-               “ran Get-ChildItem -Force” → “ran Get-ChildItem”
-                 （trace 中没有 `-Force`，不要杜撰）
-               “confirmed new_file_search does not exist” →
-                 “new_file_search was not found within the searched parts of C:\\ and
-                  D:\\; some directories were skipped on Access denied or by the depth
-                  limit, so the investigation is only partly done”
-               “identical payloads cause a spurious lock error” →
-                 “the verification script assumed the last writer is always a fixed
-                  rank; that assumption does not hold, so whether there is a lock bug
-                  is still unverified”
-
-             不要记录问候或纯闲聊。如果该段完全没有建立任何信息，输出 "fact": null。
-
-files      — 0..N 个本次会话中实际操作或调查过的绝对或 repo-relative FILE OR
-             DIRECTORY paths。保留调查过的 roots，例如 `C:\\` 和 `D:\\`。只包含
-             实际访问/搜索过的路径，不包含仅建议或计划访问的路径；不适用时填写 []。
-
-═══════════════════════════════════════════════════════════════════
-HOST CONTEXT（由 SDK 提供）
-═══════════════════════════════════════════════════════════════════
-- workspace_id present: {workspace_present}
-- branch present: {branch_present}
-
-没有 workspace_id 时，solution 不能依赖未声明的项目本地上下文——必须在 `solution`
-或 `boundary_envs` 中明确写出其所需的 repo / path / service，使记忆能够独立使用。
-
-═══════════════════════════════════════════════════════════════════
-CONVERSATION
-═══════════════════════════════════════════════════════════════════
-{conversation_block}
-
-═══════════════════════════════════════════════════════════════════
-OUTPUT（仅输出严格 JSON，不要 markdown）
-═══════════════════════════════════════════════════════════════════
-{{
-  "experiences": [
-    {{
-      "task": "...",
-      "search_keys": ["...", "..."],
-      "solution": "...",
-      "boundary_envs": "...",
-      "confidence": 0.9
-    }}
-  ],
-  "fact": {{
-    "statement": "...",
-    "files": ["..."]
-  }}
-}}
-
-强制要求：必须输出至少一条 experience，不要返回空列表。即使任务看似简单或一次成功，
-也要记录所做工作的可复用本质（method / command / how-to）。会话内容较少时，只需要
-最有价值的一条 experience——但绝不能输出空的 "experiences" array。
-
-"fact" 是单个对象，绝不是列表——每次会话一条记录。只有该段是没有建立任何信息的
-纯闲聊时，才使用 "fact": null。
-"""
-
-
-RECONCILE_PROMPT_ZH = """\
-你需要决定如何将新的 coding memory drafts 与用户已有的 memories 合并。
-
-对每条新 draft，选择以下一种 action：
-  ADD     — 没有已有 memory 描述相同的任务/方面
-  UPDATE  — 某条已有 memory 描述相同任务；用新 draft 替换它
-            （solution 可能已经变化，env 可能已经升级，等等）
-  SKIP    — 与已有内容重复；没有新信息
-
-此外，当新内容使已有候选失效或作废时，可以针对已有 candidates 输出 DELETE ops：
-  DELETE  — 新 conversation 明确 supersedes/cancels/invalidates 某条已有 memory，
-            且无法通过 UPDATE 修复。示例：
-              * 用户说“don't use X anymore”，而 X 只存在于另一条独立 memory 中
-                （不是本次正在 ADD/UPDATE 的那条）
-              * candidate 的 boundary_envs（service / endpoint / SDK）已经消失，
-                且新 conversation 确认其已 deprecated
-
-规则：
-- “Same task”是指已有 memory 和新 draft 都可以作为同一个未来用户查询的有效答案。
-- 如果 solution 不同，优先 UPDATE（不保留历史版本）。
-- 如果 task 和 solution 都高度一致，选择 SKIP。
-- 只有在存在明确证据表明 candidate 已 invalid/obsolete 时才 DELETE。绝不要仅仅因为
-  candidate 看起来“stale”就 DELETE。
-- 产生 DELETE 时，输出的 ops 数量可以超过 drafts 数量。
-
-═══════════════════════════════════════════════════════════════════
-NEW DRAFTS
-═══════════════════════════════════════════════════════════════════
-{drafts_block}
-
-═══════════════════════════════════════════════════════════════════
-EXISTING CANDIDATES（按每条 draft 的 task similarity 检索）
-═══════════════════════════════════════════════════════════════════
-{candidates_block}
-
-═══════════════════════════════════════════════════════════════════
-OUTPUT（仅输出严格 JSON，不要 markdown）
-═══════════════════════════════════════════════════════════════════
-{{
-  "ops": [
-    {{"draft_idx": 0, "action": "ADD"}},
-    {{"draft_idx": 1, "action": "UPDATE", "target_experience_id": "exp_xxx", "reason": "..."}},
-    {{"draft_idx": 1, "action": "DELETE", "target_experience_id": "exp_yyy", "reason": "user explicitly deprecated Y"}},
-    {{"draft_idx": 2, "action": "SKIP",   "reason": "duplicate"}}
-  ]
-}}
-
-如果没有 drafts，输出 {{"ops": []}}。
-"""
-
-
-FACT_RECONCILE_PROMPT_ZH = """\
-你负责维护 session-level WORKING FACTS。每条 statement 都概括一整段 trace/session：
-用户的任务、大致方法和结果。它不是一条 atomic claim。
-
-下面每条新的 session fact 都一定会被存储；这不是你要决定的事情。你的唯一任务是识别
-task continuation：新 session 是否在继续推进某条已有 session fact 所记录的同一个用户
-任务？如果是，就将较旧 fact 标记为 SUPERSEDE，使这些链接为该任务构成跨 session 的
-进展链。
-
-只有在存在充分证据同时满足以下条件时，才将已有 fact 标记为 superseded：
-  - subjects 匹配：两条记录围绕同一个实体——同一个 person、同一个 file/module、
-    同一个 host/service。subject 相同是必要条件，但不是充分条件；并且
-  - 用户目标在实质上相同，而不只是处于同一 topic/project；并且
-  - 新 trace 在继续、重试、扩展、验证或完成已有 trace 所记录的工作。
-
-以下情况不要 supersede：
-  - 两条记录的 subjects 不同。同一 group 中的两个人、同一 module 中的两个 files、
-    同一 cluster 中的两个 hosts 是并行关系，不是先后关系：一个人的状态不是另一个人
-    状态的新版本。如果 subject 显示为 (unspecified)，退回到只根据 statement 判断。
-  - 两次 session 只是提到了相同 file、symbol、component、repository、error 或
-    technology，但追求不同的用户目标。
-  - 一个任务只是为另一个任务提供 context 或 technique。
-  - 关系不确定。应保守判断：INSERT 是安全默认值；合并无关 session 会毁掉它们各自
-    独立的任务历史。
-
-把每条 statement 当作有证据边界的文本。不要把其中的 inference 重新解释为已经确定的
-cause，也不要把共同的 conjecture/error 当作用户目标相同的证据。你的判断仅涉及 task
-continuation；不要“纠正”、补全或润色任何一条 session 记录。
-
-示例：
-  existing: “需要修复 CI 的 npm run build；已追踪到 Node 18 下的
-             ERR_OSSL_EVP_UNSUPPORTED，workflow 尚未修改。”
-  new:      “继续修复同一个 CI build；已将 .github/workflows/ci.yml 中的 Node
-             提升到 20，且 npm run build 通过。”
-                                                                 → SUPERSEDE
-
-  existing: “需要修复 auth/middleware.ts 中的 JWT expiry handling；已添加
-             refresh logic。”
-  new:      “需要在 auth/middleware.ts 中添加 performance logging；已引入
-             latency metric。”
-                                                                 → 两者都保留
-            （同一 file/project，不同用户目标）
-
-═══════════════════════════════════════════════════════════════════
-NEW SESSION FACTS
-═══════════════════════════════════════════════════════════════════
-{drafts_block}
-
-═══════════════════════════════════════════════════════════════════
-EXISTING SESSION FACTS（按每条新 fact 的 statement similarity 检索）
-═══════════════════════════════════════════════════════════════════
-{candidates_block}
-
-═══════════════════════════════════════════════════════════════════
-OUTPUT（仅输出严格 JSON，不要 markdown）
-═══════════════════════════════════════════════════════════════════
-{{
-  "ops": [
-    {{"draft_idx": 0, "supersedes": ["fact_xxx"], "reason": "continues the same CI fix task"}},
-    {{"draft_idx": 1, "supersedes": []}}
-  ]
-}}
-
-只能使用同一个 draft_idx 的 candidate list 中实际出现的 fact ids。
-如果任何位置都没有 fact 被 superseded，输出 {{"ops": []}}。
-"""
-
-
-CHAIN_SUMMARY_PROMPT_ZH = """\
-working-memory store 中的某个用户任务已跨多个 sessions 推进。下面是该任务进展链中的
-session summaries，按从最早到最新排列，最后一条是当前 session。
-
-总结同一个任务如何跨 sessions 推进到当前状态。按时间顺序覆盖每个重要阶段。对每个
-阶段，在有信息时保留：实际 action 或 change、其 direct result，以及任何 unresolved
-issue 或 limiting condition。最后明确写出当前状态。
-
-规则：
-  - 这只是压缩。只能报告 entries 实际陈述的内容；绝不要新增或补全 command、cause、
-    motive、action、test result、success state 或 global negative conclusion。
-  - 精确保留证据状态：attempted 不等于 completed，observed 不等于 verified，inferred
-    不等于 established，unresolved 必须保持 unresolved。保留 uncertainty words 以及
-    search/permission/coverage limits。
-  - 忠实陈述当前结束状态（completed、partially completed、failed、blocked 或
-    still awaiting verification）。绝不要因为某个看似合理的因果故事，或后续 entry
-    并未验证的内容而提升状态。
-  - 如果 entries 提到 suspected cause 和后续 result，只有某条 entry 直接说明该 cause
-    已被 verified 时，才可在两者之间建立因果联系。
-  - 保留具体 retrieval anchors：file paths、symbols、commands、error strings、versions、
-    config keys/values，以及对进展重要的 numeric values。
-  - 对 2-3 代的 chains，不要把进展过度压缩成一句话。适合时优先使用 2-4 个紧凑段落，
-    或使用可读性良好的 prose，清楚呈现 task goal、逐阶段 progression 和 current status。
-  - 不要机械复制完整 history。在保留重要 actions、direct results 和 leftovers 的同时，
-    省略重复及低价值细节。
-  - 不要杜撰 stage headings 或 dates。只有 entries 使日期有实际意义时才提及日期；
-    单独的 timestamps 是噪声。
-  - 如果 entries 说明更早 revisions 已被省略，必须明确指出 earlier history was omitted；
-    不要暗示所提供的 entries 是完整历史。
-  - 使用与 entries 相同的语言。
-  - 不要写前言，也不要用引号包裹输出。
-
-示例
-  entries:
-    (2026-07-20) 需要修复 CI 的 npm run build；已追踪到 Node 18 下的
-                 ERR_OSSL_EVP_UNSUPPORTED，workflow 尚未修改。
-    (2026-07-24) 继续修复同一个 CI 问题；已将 .github/workflows/ci.yml 中的 Node
-                 提升到 20，但 dependency cache 仍复现旧错误。
-    (now)        继续验证同一修复；清除 npm cache 后，npm run build 通过。
-  output:
-    任务目标是修复 CI 的 npm run build。最初将问题追踪到 Node 18 下的
-    ERR_OSSL_EVP_UNSUPPORTED，当时尚未修改 workflow；随后将
-    .github/workflows/ci.yml 提升到 Node 20，但 dependency cache 仍使旧错误继续
-    出现。最后，清除 npm cache 后 npm run build 通过，因此该 build 修复目前已验证完成。
-
-═══════════════════════════════════════════════════════════════════
-ENTRIES
-═══════════════════════════════════════════════════════════════════
-{chain_block}
-
-═══════════════════════════════════════════════════════════════════
-OUTPUT（只输出 summary 本身，不要其他内容）
-═══════════════════════════════════════════════════════════════════
-"""
+from ..prompts.zh_hans import (  # noqa: F401
+    CODING_CHAIN_SUMMARY_PROMPT as CHAIN_SUMMARY_PROMPT_ZH,
+    CODING_EXTRACT_PROMPT as EXTRACT_PROMPT_ZH,
+    CODING_EXTRACT_PROMPT_CODING as EXTRACT_PROMPT_CODING_ZH,
+    CODING_FACT_RECONCILE_PROMPT as FACT_RECONCILE_PROMPT_ZH,
+    CODING_RECONCILE_PROMPT as RECONCILE_PROMPT_ZH,
+)

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,14 +20,20 @@ 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
 from ..core.embed_service import EmbedService
-from ..utils.lang_detect import is_chinese
+from ..prompts import (
+    get_prompt,
+    normalize_language,
+    resolve_language,
+    with_output_language,
+)
 from .judge import _store_coding_log
 from .store import CodingMemoryStore
-from .types import CodingMemory, CodingMemoryDraft, ReconcileOp
+from .types import CodingMemory, CodingMemoryDraft, CodingWriteError, ReconcileOp
 
 
 
@@ -50,57 +59,7 @@ def _resolve_configured_temperature(llm_provider) -> Optional[float]:
 # Prompt
 # ================================================================
 
-RECONCILE_PROMPT = """\
-You decide how to merge new coding memory drafts with the user's existing memories.
-
-For each new draft, decide one of:
-  ADD     — no existing memory describes the same task/aspect
-  UPDATE  — an existing memory describes the same task; the new draft replaces it
-            (solution may have changed, env may have upgraded, etc.)
-  SKIP    — duplicate of existing; nothing new
-
-Additionally, you may emit DELETE ops on existing candidates when the new
-content makes them obsolete or invalid:
-  DELETE  — the new conversation EXPLICITLY supersedes/cancels/invalidates an
-            existing memory that cannot be repaired via UPDATE. Examples:
-              * user says "don't use X anymore" and X is only present as a
-                separate memory (not the one being added/updated)
-              * candidate's boundary_envs (service / endpoint / SDK) is gone
-                and the new conversation confirms the deprecation
-
-Rules:
-- "Same task" means the existing memory and the new draft would both be valid
-  answers to the same future user query.
-- If solution differs, prefer UPDATE (we don't keep history).
-- If both task and solution match closely, SKIP.
-- DELETE only when there is EXPLICIT evidence the candidate is invalid/obsolete.
-  Never DELETE just because a candidate looks "stale".
-- Output ops can outnumber drafts when DELETEs are produced.
-
-═══════════════════════════════════════════════════════════════════
-NEW DRAFTS
-═══════════════════════════════════════════════════════════════════
-{drafts_block}
-
-═══════════════════════════════════════════════════════════════════
-EXISTING CANDIDATES (per draft, retrieved by task similarity)
-═══════════════════════════════════════════════════════════════════
-{candidates_block}
-
-═══════════════════════════════════════════════════════════════════
-OUTPUT (strict JSON only, no markdown)
-═══════════════════════════════════════════════════════════════════
-{{
-  "ops": [
-    {{"draft_idx": 0, "action": "ADD"}},
-    {{"draft_idx": 1, "action": "UPDATE", "target_experience_id": "exp_xxx", "reason": "..."}},
-    {{"draft_idx": 1, "action": "DELETE", "target_experience_id": "exp_yyy", "reason": "user explicitly deprecated Y"}},
-    {{"draft_idx": 2, "action": "SKIP",   "reason": "duplicate"}}
-  ]
-}}
-
-If there are no drafts, output {{"ops": []}}.
-"""
+from ..prompts.en import CODING_RECONCILE_PROMPT as RECONCILE_PROMPT  # noqa: E402,F401  (re-export)
 
 
 def _drafts_language_text(drafts: List[CodingMemoryDraft]) -> str:
@@ -119,24 +78,32 @@ def _drafts_language_text(drafts: List[CodingMemoryDraft]) -> str:
 def build_experience_reconcile_prompt(
     drafts: List[CodingMemoryDraft],
     candidates_per_draft: List[List[CodingMemory]],
+    language: Optional[str] = None,
 ) -> Tuple[str, str]:
-    """Return the language-matched experience reconcile prompt and language."""
+    """Return the experience reconcile prompt and its language code.
+
+    Explicit ``language`` wins; otherwise zh/en auto-detection over the drafts.
+    """
     drafts_block = CodingMemoryReconciler._format_drafts(drafts)
     candidates_block = CodingMemoryReconciler._format_candidates(
         drafts, candidates_per_draft,
     )
-    if is_chinese(_drafts_language_text(drafts)):
-        from .prompts_zh import RECONCILE_PROMPT_ZH
-
-        template = RECONCILE_PROMPT_ZH
-        language = "zh"
-    else:
-        template = RECONCILE_PROMPT
-        language = "en"
-    return template.format(
+    explicit = normalize_language(language)
+    code = resolve_language(explicit, _drafts_language_text(drafts))
+    prompt = get_prompt("CODING_RECONCILE_PROMPT", code).format(
         drafts_block=drafts_block,
         candidates_block=candidates_block,
-    ), language
+    )
+    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)
 
 
 # ================================================================
@@ -186,23 +153,55 @@ class CodingMemoryReconciler:
         user_id: str = "",
         agent_id: str = "default_agent",
         session_id: str = "",
+        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)
@@ -212,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
+                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 不丢）
@@ -232,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"))
         )
@@ -311,9 +336,12 @@ class CodingMemoryReconciler:
         self,
         drafts: List[CodingMemoryDraft],
         candidates_per_draft: List[List[CodingMemory]],
+        language: Optional[str] = None,
     ) -> Tuple[List[ReconcileOp], str, str, Any]:
         """返回 (ops, prompt, raw_response, llm_resp)，供上层打 CODING_RECONCILE log。"""
-        prompt, _ = build_experience_reconcile_prompt(drafts, candidates_per_draft)
+        prompt, _ = build_experience_reconcile_prompt(
+            drafts, candidates_per_draft, language=language,
+        )
 
         resp = await self.llm_provider.complete(
             prompt=prompt,
@@ -358,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("```"):
@@ -386,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)"
             )
@@ -436,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
@@ -456,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}")
 
@@ -486,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}")
 
@@ -529,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__)
 
@@ -81,10 +82,13 @@ class CodingWriter:
         request_id: Optional[str] = None,
         source: str = "default",
         memory_at: Optional[datetime] = None,
+        language: Optional[str] = None,
     ) -> Dict[str, Any]:
         """
         working/coding 段写入端到端。memory_at 是对话时间，记到这次写出的经验和
-        事实上；不传则用收到请求的时间（与 chat 链路一致）。返回响应 dict（兼容 client.add 返回结构）：
+        事实上；不传则用收到请求的时间（与 chat 链路一致）。language 是显式 prompt
+        语言码，透传给抽取、经验 reconcile、事实 reconcile 与演变总结；None 时各步
+        沿用 zh/en 自动检测。返回响应 dict（兼容 client.add 返回结构）：
             {
                 "success": True,
                 "scene": "productivity",
@@ -101,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()
@@ -140,6 +151,10 @@ class CodingWriter:
         # 跟库里已有的什么关系是 reconcile 的事。把已有 task 摆到它面前，它会把
         # 一个其实不同的任务往清单里某个措辞上靠，reconciler 随后判成 UPDATE 合并
         # 掉，那个区别就没了——措辞对不上顶多多存一条，措辞被带偏是直接写错。
+        #
+        # 模型失败（LLM 调用失败 / 空回复 / 解析不出）抛 CodingWriteError：整次写入
+        # 报失败、什么都不存，连 trace 也不追加——调用方换个 request_id 重跑时，
+        # 历史窗口里不会多出这段本该是「新消息」的对话。
         try:
             drafts, fact_drafts = await self.extractor.extract(
                 messages,
@@ -151,27 +166,28 @@ class CodingWriter:
                 branch=branch,
                 session_id=session_id,
                 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 生成。
@@ -179,32 +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 "",
-            )
-            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,
+        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]
@@ -212,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")
@@ -292,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

@@ -260,6 +260,7 @@ class EmbedderConfig:
     max_retries: int = None  # 最大重试次数
     retry_delay: float = None  # 重试间隔（秒）
     timeout: int = None  # 请求超时（秒）
+    batch_size: int = None  # 单次 HTTP 请求最多带多少条 input（embed_batch 按此切块）
 
     # 内部平台扩展（extra_headers / extra_body 会透传给 OpenAI client）
     extra_headers: Optional[Dict[str, str]] = None
@@ -294,6 +295,10 @@ class EmbedderConfig:
             # 请求切断并制造重试风暴。SDK 内层重试已关闭，15s 是每个显式 attempt
             # 的真实上限；部署可通过 MEMORY_EMBEDDER_TIMEOUT 覆盖。
             self.timeout = _get_env_int("MEMORY_EMBEDDER_TIMEOUT", 15)
+        if self.batch_size is None:
+            # 大批量（如重新 embed 整个库）不能一次 HTTP 发几千条：多数服务对
+            # input 数组有上限，超了直接 400。按 batch_size 切块逐块发送。
+            self.batch_size = _get_env_int("MEMORY_EMBEDDER_BATCH_SIZE", 64)
         if self.extra_headers is None:
             val = os.getenv("MEMORY_EMBEDDER_EXTRA_HEADERS")
             if val:
@@ -427,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
@@ -745,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
@@ -1259,6 +1281,12 @@ class MemoryConfig:
     enable_agent: bool = False
     debug: bool = False
     metrics_enabled: bool = True
+    # LLM prompt 语言（client 默认值；env: MEMORY_LANGUAGE）。canonical 码见
+    # hy_memory.prompts.SUPPORTED_LANGUAGES（en / zh-Hans / zh-Hant / ja / es / de /
+    # pt / fr / ko / ru / id），也接受别名 zh、zh-CN → zh-Hans，zh-TW、zh-HK →
+    # zh-Hant，pt-BR → pt。add() 等的 per-call language 优先于它。None（默认）=
+    # 沿用 zh/en 自动检测。显式指定时记忆正文用该语言书写。未知码抛 ValueError。
+    language: Optional[str] = None
     # Runtime-only HTTP transport factory. MemHub uses this for request-cost
     # budgeting without restricting the embedded SDK's local store access.
     http_transport_factory: Optional[Callable[[], Any]] = field(
@@ -1273,6 +1301,11 @@ class MemoryConfig:
         self.enable_agent = _get_env_bool("MEMORY_ENABLE_AGENT", False)
         self.debug = _get_env_bool("MEMORY_DEBUG", False)
         self.metrics_enabled = _get_env_bool("MEMORY_METRICS", True)
+        if self.language is None:
+            self.language = os.getenv("MEMORY_LANGUAGE", "").strip() or None
+        from .prompts import normalize_language
+
+        self.language = normalize_language(self.language)
 
     @classmethod
     def from_env(cls) -> "MemoryConfig":
@@ -1323,6 +1356,10 @@ class MemoryConfig:
         config.metrics_enabled = config_dict.get(
             "metrics_enabled", config.metrics_enabled
         )
+        if config_dict.get("language") is not None:
+            from .prompts import normalize_language
+
+            config.language = normalize_language(config_dict["language"])
 
         return config
 
@@ -1364,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,
@@ -1381,6 +1420,7 @@ class MemoryConfig:
             "enable_graph": self.enable_graph,
             "enable_agent": self.enable_agent,
             "metrics_enabled": self.metrics_enabled,
+            "language": self.language,
         }
 
     def print_config(self) -> None:

hy_memory/core/embed_service.py

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

hy_memory/data/graph_store_kuzu.py

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

hy_memory/data/vector_store_base.py

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

hy_memory/data/vector_store_chroma.py

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

hy_memory/pipelines/_graph/topic_summary.py

@@ -64,59 +64,15 @@ def _topic_lock(graph_store, isolation_key: str, topic_id: str) -> asyncio.Lock:
         return lock
 
 
-TOPIC_SUMMARY_PROMPT = """You are summarizing everything known about ONE topic.
-
-## Topic
-
-{topic_name}
-
-## Memories under this topic (oldest → newest)
-
-{memories}
-
----
-
-Write a single dense summary of what is known about the user with respect to this
-topic.
-
-Rules:
-
-* 2–4 sentences, third person, starting with "The user ..." (or the named person
-  if the memories are about someone else).
-* Cover the topic as a whole — state the current situation, and mention how it
-  developed only when the change matters.
-* Preserve concrete details: names, places, numbers, dates.
-* Do NOT invent anything that is not in the memories.
-* Do NOT enumerate the memories one by one; synthesize them.
-* Output language must match the language of the memories.
-
-Return ONLY the summary text, no preamble, no JSON, no quotes."""
-
-
-TOPIC_SUMMARY_PROMPT_ZH = """你在为**一个主题**总结已知的全部信息。
-
-## 主题
-
-{topic_name}
-
-## 该主题下的记忆（时间正序）
-
-{memories}
-
----
-
-写一段关于用户在这个主题上的高密度摘要。
-
-要求：
-
-* 2–4 句，第三人称，以"用户…"开头（若记忆讲的是别人，则以那个人的名字开头）。
-* 覆盖整个主题 —— 说明当前状况；只在变化本身重要时才提它是怎么演变过来的。
-* 保留具体细节：人名、地点、数字、日期。
-* 绝不编造记忆里没有的内容。
-* 不要逐条罗列记忆，要综合成一段。
-* 输出语言与记忆的语言一致。
-
-只返回摘要正文，不要任何前言、不要 JSON、不要引号。"""
+# 多语言版本见 hy_memory/prompts/<language>.py；旧名字保留为别名。
+from ...prompts import (  # noqa: E402
+    get_prompt,
+    normalize_language,
+    resolve_language,
+    with_output_language,
+)
+from ...prompts.en import TOPIC_SUMMARY_PROMPT  # noqa: E402,F401  (re-export)
+from ...prompts.zh_hans import TOPIC_SUMMARY_PROMPT as TOPIC_SUMMARY_PROMPT_ZH  # noqa: E402,F401  (re-export)
 
 
 async def find_latest_topic_summary(
@@ -193,9 +149,13 @@ async def maybe_summarize_topics(
     max_concurrency: int = 3,
     temperature: Optional[float] = None,
     trace=None,
+    language: Optional[str] = None,
 ) -> Dict[str, Any]:
     """对本次写入触达的 Topic，按需有界并发生成 / 刷新 summary。
 
+    language 为显式 prompt 语言码（随触发本次写入的请求）；None 时按记忆内容
+    做 zh/en 自动检测。
+
     触发条件：Topic 下 active 记忆数 ≥ `min_memories`，且比上次总结时多了 ≥ `step` 条。
     这样既不会每写一条就重算（贵），也不会一直不更新（陈旧）。
 
@@ -254,6 +214,7 @@ async def maybe_summarize_topics(
                         topic_name=topic_names.get(topic_id) or topic_id,
                         memories=[m.get("content") or "" for m in mems],
                         temperature=temperature,
+                        language=language,
                     )
                     if trace is not None:
                         await trace(
@@ -317,15 +278,18 @@ async def maybe_summarize_topics(
 async def _generate(
     *, llm_provider, topic_name: str, memories: List[str],
     temperature: Optional[float] = None,
+    language: Optional[str] = None,
 ) -> tuple:
     """返回 (摘要文本, 实际 prompt, token 用量) —— 后两个供埋点，线上要能复盘。"""
-    from ...utils.lang_detect import is_chinese
-
     body = "\n".join(f"- {c}" for c in memories if c)
     if not body:
         return "", "", {}
-    tpl = TOPIC_SUMMARY_PROMPT_ZH if is_chinese(body) else TOPIC_SUMMARY_PROMPT
-    prompt = tpl.format(topic_name=topic_name, memories=body)
+    explicit = normalize_language(language)
+    code = resolve_language(explicit, body)
+    prompt = get_prompt("TOPIC_SUMMARY_PROMPT", code).format(
+        topic_name=topic_name, memories=body,
+    )
+    prompt = with_output_language(prompt, code, explicit=explicit is not None)
     resp = await llm_provider.complete(
         prompt=prompt,
         max_tokens=400,

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

@@ -95,21 +95,48 @@ class ToolCall:
 #   [John]: 我也喜欢茶
 # 名字单独占一行、整段只出现一次；[user] 标签**不换成名字**，视角信息留在标签里。
 # extract 用这一行给 L0 basic_info 取 name（用户不必在对话里自报姓名）。
+# 各语言的模板在 hy_memory/prompts/<language>.py 的 USER_NAME_LINE；这两个旧名字保留。
 _USER_NAME_LINE_ZH = "用户名叫{name}"
 _USER_NAME_LINE_EN = "The user's name is {name}"
 
-_USER_NAME_LINE_RE = re.compile(
-    r"^(?:用户名叫|The user's name is)\s*(.+?)\s*$"
-)
+_user_name_line_res: Optional[List["re.Pattern"]] = None
 
 
-def render_user_name_line(name: str, is_zh: bool) -> str:
-    """渲染文首的用户名字行；name 为空返回空串。"""
+def _user_name_line_patterns() -> List["re.Pattern"]:
+    """每种语言一个匹配名字行的正则（L1_RAW 里可能存着任意语言的名字行）。"""
+    global _user_name_line_res
+    if _user_name_line_res is None:
+        from ..prompts import SUPPORTED_LANGUAGES, get_prompt
+
+        patterns = []
+        for code in SUPPORTED_LANGUAGES:
+            try:
+                tpl = get_prompt("USER_NAME_LINE", code)
+            except (ImportError, AttributeError):
+                continue
+            prefix, _, suffix = tpl.partition("{name}")
+            patterns.append(re.compile(
+                r"^" + re.escape(prefix.strip()) + r"\s*(.+?)\s*"
+                + re.escape(suffix.strip()) + r"$"
+            ))
+        _user_name_line_res = patterns
+    return _user_name_line_res
+
+
+def render_user_name_line(
+    name: str, is_zh: bool = False, *, language: Optional[str] = None,
+) -> str:
+    """渲染文首的用户名字行；name 为空返回空串。
+
+    language（语言码）优先；未给时按 is_zh 在 zh-Hans / en 间选（旧行为）。
+    """
     name = (name or "").strip()
     if not name:
         return ""
-    tpl = _USER_NAME_LINE_ZH if is_zh else _USER_NAME_LINE_EN
-    return tpl.format(name=name)
+    from ..prompts import get_prompt
+
+    code = language or ("zh-Hans" if is_zh else "en")
+    return get_prompt("USER_NAME_LINE", code).format(name=name)
 
 
 def parse_user_name_line(line: str) -> Optional[str]:
@@ -118,8 +145,12 @@ def parse_user_name_line(line: str) -> Optional[str]:
     L1_RAW 存的就是 get_flat_content() 的产物，回读历史时要靠这个把名字行识别出来，
     否则它会被当成一条无前缀的裸消息（见 MemoryWriter._get_recent_history）。
     """
-    m = _USER_NAME_LINE_RE.match((line or "").strip())
-    return m.group(1) if m else None
+    text = (line or "").strip()
+    for pattern in _user_name_line_patterns():
+        m = pattern.match(text)
+        if m:
+            return m.group(1)
+    return None
 
 
 @dataclass
@@ -257,6 +288,11 @@ class WriteRequest:
     branch: Optional[str] = None
     # 分支名。同 workspace_id。
 
+    # 显式 prompt 语言码（canonical，见 hy_memory.prompts.SUPPORTED_LANGUAGES）。
+    # 由 client 入口按「per-call > MemoryConfig.language」解析后注入；None 时
+    # 抽取 / reconcile / 画像等各步沿用 zh/en 自动检测。
+    language: Optional[str] = None
+
     # ---- 便捷方法 ----
 
     def has_messages(self) -> bool:
@@ -286,8 +322,8 @@ class WriteRequest:
             [John]: 我也喜欢茶
 
         无 name 时与历史行为完全一致（`[user]: ...` / `[assistant]: ...`）。
-        名字行只在 role=user 带 name 时出现，且整段只出现一次；语言按消息内容判定
-        （与 extractor 选 zh/en prompt 同一套判据）。
+        名字行只在 role=user 带 name 时出现，且整段只出现一次；语言取显式
+        language，未指定时按消息内容判定（与 extractor 选 zh/en prompt 同一套判据）。
         """
         if not self.messages:
             return self.content or ""
@@ -296,11 +332,14 @@ class WriteRequest:
 
         name = self.user_name()
         if name:
-            from ..utils.lang_detect import is_chinese
+            if self.language:
+                name_line = render_user_name_line(name, language=self.language)
+            else:
+                from ..utils.lang_detect import is_chinese
 
-            name_line = render_user_name_line(
-                name, is_chinese(messages=self.messages)
-            )
+                name_line = render_user_name_line(
+                    name, is_chinese(messages=self.messages)
+                )
             if name_line:
                 lines.insert(0, name_line)
 

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

@@ -979,171 +979,16 @@ def s2_agent_skip_reason(materials: Dict[str, Any]) -> Optional[str]:
     return None
 
 # ====================================================================
-# System Prompt (dual language)
+# System Prompt (multilingual: hy_memory/prompts/<language>.py)
 # ====================================================================
 
-SYSTEM2_AGENT_PROMPT_ZH = """你是一个认知加工 Agent，负责从用户的记忆数据中演化高层认知结构。
-
-## 记忆分层架构
-
-用户的记忆存储在两个系统中：
-
-### VDB（向量数据库）— 你只能读取，不能修改
-| 层级 | 说明 |
-|------|------|
-| L0 BASIC_INFO | 用户基础属性（姓名、年龄、职业等）|
-| L1 RAW | 原始对话记录 |
-| L2 FACT | 原子事实（从对话中提取的客观事实）|
-| L3 SUMMARY | 会话摘要 |
-| L4 IDENTITY | 身份画像（性格特征、偏好、习惯）|
-| L5 KNOWLEDGE | 领域知识 |
-
-### Graph（知识图谱）— 你是唯一的写入者
-| 层级 | 说明 |
-|------|------|
-| L6 SCHEMA | 行为模式 — 域内、原子化、创建后不可变 |
-
-## L6 Schema 是什么？
-
-Schema 是从多次独立经历归纳出的长期行为模式，包含以下三个要素：
-
-- **Circumstance（场景）**：该模式发生的领域/话题/场景。Schema 必须限定在其场景内，不要跨域泛化。
-- **Pattern（模式）**：用户在该场景下的惯常行为、思维方式或行动倾向。
-- **Insight（洞察）**：底层心理驱动力或心智模型。
-
-### 内容格式
-行为模式用一句话组合三要素：
-"当[场景]时，用户[模式]——反映了[洞察]。"
-
-对与情绪、治疗、压力、哀伤或创伤有关的长期模式，不要把具体人生背景压缩成
-空泛人格词。优先保留这三部分：
-"Trigger/background（持久触发背景） → emotional response（反复情绪反应） → observed coping resource（用户已实际使用的应对资源）。"
-只能写入 user-owned 证据中出现的触发背景、反应和应对方式；助手建议不是用户已观察到的应对资源。
-
-### 规则
-- **原子化**：一个 Schema 只包含一个模式。两个不同模式 → 两个 Schema。
-- **不可变**：Schema 创建后内容永远不变。不要修改已有 Schema 的内容。
-- **累积证据**：新事实只是在支持已有表述 → 调 `add_evidence`。如果新证据会让旧画像的当前状态产生实质遗漏、错误或误导，使用 `revise_schema` 创建新版本，让旧版本保留审计但退出 active 检索。
-- **域内约束**：不要跨域。跨域抽象由系统的其他流程处理。
-- **事实与模式分层**：单条明确身份、健康状态、设备使用、隶属关系、项目或偏好属于 L2 状态，不创建 L6。L6 必须由至少两个独立 raw/session 中的 user-owned 证据支持。
-- **主体安全**：同一原始写入可能包含他人资料或示例。只有材料明确归因于当前用户时才创建用户 Schema；否则对该材料不执行任何操作。
-- **候选覆盖**：source-context 审查时，每条候选事实必须二选一：用于 `create_schema`/`add_evidence` 的 evidence，或用 `skip_fact` 明确跳过。原始上下文只用于确认主体或补回该事实遗漏的细节，不得据此创建无关 Schema。
-- **证据门槛**：创建 L6 必须有 user-owned evidence，且这些证据合计代表至少两个独立 raw/session。
-  一个被 S1 合并的 L2 事实可以代表多次独立写入，应检查它的 `source_raw_memory_ids`，不要只数节点。
-  助手建议不能作为用户模式的独立证据。
-
-## 工作流程
-
-输入材料分两部分（仅当已形成聚类时才会调用你）：
-- **聚类结果（Cluster Results）**：主输入，按语义相似度归组的事实
-- **未聚类事实（补充）**：未进入任一聚类的事实，优先级低于聚类结果，酌情审视即可
-
-对于每组事实（无论聚类还是未聚类）：
-1. **搜索已有 Schema**：如果已有 Schema 已覆盖该模式，使用 `add_evidence`。只有加入新证据后旧表述会产生实质遗漏、错误或误导时才使用 `revise_schema`。
-2. **创建新 Schema**：仅当没有已有 Schema 覆盖时。一句话，三要素。
-3. **建立关系**：两个 Schema 主题相关 → 用 `add_edge`（RELATED_TO）。
-
-## 原则
-
-- 所有 Graph 操作必须通过 tools 执行
-- Schema 内容创建后不可变——绝不重新创建已存在的 Schema
-- 优先 `add_evidence` 而非创建重复节点
-- 宁可不创建，也不要创建低质量节点
-- 一个 Schema = 一个域内原子模式
-- 打标签时优先使用已有标签列表中的标签"""
-
-
-SYSTEM2_AGENT_PROMPT_EN = """You are a cognitive processing Agent. Your job is to evolve higher-order cognitive structures from a user's raw memory data.
-
-## Memory Architecture
-
-### VDB (Vector Database) — read-only
-| Layer | Description |
-|-------|-------------|
-| L0 BASIC_INFO | User attributes (name, age, occupation) |
-| L1 RAW | Original conversation transcripts |
-| L2 FACT | Atomic facts extracted from conversations |
-| L3 SUMMARY | Session summaries |
-| L4 IDENTITY | Identity traits, preferences, habits |
-| L5 KNOWLEDGE | Domain knowledge |
-
-### Graph (Knowledge Graph) — you are the sole writer
-| Layer | Description |
-|-------|-------------|
-| L6 SCHEMA | Behavioral patterns — domain-bound, atomic, immutable once created |
-
-## What is an L6 Schema?
-
-A Schema is one cross-event behavioral pattern in the long-term user model and
-contains the following three components:
-
-
-- **Circumstance**: The domain/topic/situation where this pattern is observed. A Schema MUST stay within its circumstance — do NOT generalize across domains. Cross-domain abstraction is handled separately by the system.
-- **Pattern**: The user's habitual behavior, thinking style, or action tendency in this circumstance.
-- **Insight**: The underlying psychological driver or mental model.
-
-### Content format
-Use a single sentence combining all three:
-"When [circumstance], the user [pattern] — reflecting [insight]."
-
-For durable emotional, therapy, stress, grief, or trauma-related patterns, do
-not erase the specific autobiographical background into a generic personality
-label. Prefer an anchored structure that preserves:
-"Trigger/background -> recurring emotional response -> observed coping resource."
-Only include triggers, responses, and coping resources present in user-owned
-evidence. Assistant advice is not an observed user coping resource.
-
-### Rules
-- **Atomic**: One pattern per Schema. Two distinct patterns → two Schemas.
-- **Immutable**: Once created, content NEVER changes.
-- **Evidence only**: New facts that merely support existing wording → call
-  `add_evidence`. If new evidence materially changes, corrects, or narrows the
-  current durable state, use `revise_schema` so the old version is retained for
-  audit but removed from active retrieval.
-- **Domain-bound**: Stay within the observed domain. Cross-domain abstraction is handled by a separate system process.
-- **Separate facts from patterns**: A single explicit identity, health state,
-  equipment use, affiliation, project, or preference belongs in L2 state memory,
-  not L6. L6 requires user-owned evidence representing at least two independent
-  raw writes or sessions. One reconciled L2 fact may represent multiple writes;
-  inspect its source_raw_memory_ids rather than counting fact nodes.
-- **Subject safety**: Facts sharing a source chunk may describe other people or
-  examples. Create a user Schema only when the material explicitly attributes
-  the pattern to the user. Otherwise output no operation for that material.
-- **Candidate coverage**: In a source-context review, account for every listed
-  candidate fact: either use it as evidence in `create_schema`/`add_evidence`,
-  or emit `skip_fact`. Raw context may confirm its subject or restore omitted
-  detail, but must not seed unrelated Schemas.
-- **Evidence threshold**: Creating L6 requires one or more user-owned evidence
-  facts representing at least two independent raw writes or sessions.
-  Assistant advice does not establish a user pattern by itself.
-
-### Good vs Bad examples
-✅ "When cooking, the user strictly follows recipe steps and precisely measures ingredients — reflecting a need for external structure to manage uncertainty."
-✅ "When gaming, the user always checks walkthroughs to achieve 100% completion — driven by low tolerance for incompleteness."
-✅ "After an unexpected mentor loss, mortality reminders can bring grief back suddenly; the user pauses to reflect and takes quiet walks to regain steadiness."
-❌ "The user approaches music as a medium for creative synthesis and cultural bridge-building, consistently blending diverse musical traditions..." (multiple patterns merged, too broad)
-❌ "The user is passionate about many things and values quality." (no circumstance, too vague)
-❌ "The user is meaning-driven and resilient." (erases the durable trigger and observed coping evidence)
-
-## Your Workflow
-
-Input materials (you are only invoked when at least one cluster exists):
-- **Cluster Results**: Primary input — facts grouped by semantic similarity
-- **Unclustered Facts (supplemental)**: Facts not in any cluster; lower priority than cluster results
-
-For each group of facts (clustered or unclustered):
-1. **Search existing Schemas**: If an existing Schema already captures this pattern, call `add_evidence`. Use `revise_schema` only when the old wording would become materially incomplete or misleading after adding the new evidence.
-2. **Create new Schema**: Only if no existing Schema covers this pattern. One sentence, three components.
-3. **Build relationships**: If two Schemas are thematically related, use `add_edge` (RELATED_TO).
-
-## Principles
-
-- All Graph operations MUST go through tools
-- Schema content is IMMUTABLE — never recreate what already exists
-- Prefer `add_evidence` over creating duplicates
-- Prefer not creating over creating low-quality nodes
-- One Schema = one atomic pattern in one domain
-- When tagging, prefer reusing tags from the existing tags list"""
+from ..prompts import (  # noqa: E402
+    get_prompt,
+    normalize_language,
+    with_output_language,
+)
+from ..prompts.zh_hans import SYSTEM2_AGENT_PROMPT as SYSTEM2_AGENT_PROMPT_ZH  # noqa: E402,F401  (re-export)
+from ..prompts.en import SYSTEM2_AGENT_PROMPT as SYSTEM2_AGENT_PROMPT_EN  # noqa: E402,F401  (re-export)
 
 # backward compat alias
 SYSTEM2_AGENT_PROMPT = SYSTEM2_AGENT_PROMPT_ZH
@@ -2095,10 +1940,14 @@ async def run_system2_agent(
     tool_executor: System2ToolExecutor,
     config: MemoryConfig,
     max_iterations: int = 10,  # kept for backward compat, unused in single-call mode
+    language: Optional[str] = None,
 ) -> Dict[str, Any]:
     """
     Phase 2: System 2 Agent — Single LLM call + JSON output + post-process execution.
 
+    ``language``: explicit prompt language code (overrides config.language);
+    None and no config default → zh/en detection over the materials.
+
     Instead of multi-turn tool-calling loop, this version:
     1. Puts all materials (facts + existing graph) into the prompt
     2. Asks LLM to output a JSON array of operations
@@ -2120,9 +1969,17 @@ async def run_system2_agent(
     # Build LLMProvider from config
     llm_provider = LLMProvider(config)
 
-    # Detect language from materials content
-    lang = _detect_language(materials)
-    system_prompt = _build_single_call_system_prompt(lang)
+    # Prompt language: explicit language (evolve(language=...) or
+    # MemoryConfig.language) wins; otherwise detect zh/en from the materials.
+    explicit_language = normalize_language(language) or normalize_language(
+        getattr(config, "language", None)
+    )
+    lang = explicit_language or _s2_language_code(_detect_language(materials))
+    system_prompt = with_output_language(
+        _build_single_call_system_prompt(lang),
+        lang,
+        explicit=explicit_language is not None,
+    )
     user_msg = _build_materials_message(materials, lang=lang)
 
     messages = [
@@ -2393,101 +2250,30 @@ async def run_system2_agent(
     }
 
 
-def _build_single_call_system_prompt(lang: str) -> str:
-    """Build system prompt for single-call mode (includes output format instructions)."""
-    base = SYSTEM2_AGENT_PROMPT_ZH if lang == "zh" else SYSTEM2_AGENT_PROMPT_EN
-
+def _s2_language_code(lang: str) -> str:
+    """旧的 "zh" / "en" 标记映射到语言码；其余值按语言码处理。"""
     if lang == "zh":
-        output_instructions = """
+        return "zh-Hans"
+    return lang or "en"
 
-## 输出格式
 
-不要调用 tools。直接输出一个 JSON 数组，包含你决定执行的操作。用 ```json 代码块包裹。
+def _build_single_call_system_prompt(lang: str) -> str:
+    """Build system prompt for single-call mode (includes output format instructions).
 
-可用操作：
-
-1. **create_schema** — 创建新的 L6 行为 Schema
-   ```{"op": "create_schema", "schema_kind": "behavior_pattern", "content": "供用户阅读的简洁画像", "retrieval_text": "用于检索的行为与适用场景", "evidence_list": ["fact_node_id_1", "fact_node_id_2"], "tags": ["tag1"]}```
-
-2. **add_evidence** — 给已有 Schema 追加证据（不修改内容）
-   ```{"op": "add_evidence", "node_id": "existing_schema_node_id", "evidence_list": ["new_fact_id_1"]}```
-
-3. **revise_schema** — 新证据使已有 Schema 的当前状态发生实质变化时，创建新版本并让旧版本退出默认检索。不要用于可共存的细节补充。
-   ```{"op": "revise_schema", "node_id": "old_schema_id", "schema_kind": "explicit_state", "content": "更新后的当前画像", "retrieval_text": "更新后的检索文本", "evidence_list": ["new_fact_id_1"], "tags": ["tag1"], "reason": "明确说明旧画像为何会误导"}```
-
-4. **add_edge** — 建立两个 Schema 之间的关系
-   ```{"op": "add_edge", "source_id": "schema_id_1", "target_id": "schema_id_2", "reason": "关系原因"}```
-
-5. **skip_fact** — 明确标记某条候选事实已审查但不创建 Schema。仅用于他人事实、临时事件、不能证明用户特征的助手建议，或已被现有 Schema 完整覆盖的事实。
-   ```{"op": "skip_fact", "node_id": "candidate_fact_id", "reason": "不是稳定的用户模式"}```
-
-## 输出约定
-
-1. 输出必须是 JSON 数组，用 ```json 代码块包裹。
-2. 如果数据不足以得出可靠结论，输出 `[]`。在 source-context review 中，
-   `[]` 表示已审查该组全部候选，且都不足以支持稳定 Schema。
-3. 代码块外不要有任何其他文字。
-4. evidence_list 中的 id 必须来自材料中提供的 fact node_id。
-5. add_evidence / revise_schema 的 node_id 必须来自已有 Graph 节点的 id。
-6. 对 source-context 审查，必须让每条候选事实出现在 evidence_list 或 skip_fact 中。"""
-    else:
-        output_instructions = """
-
-## Output Format
-
-Do NOT call tools. Output a JSON array of operations directly, wrapped in a ```json code block.
-
-Available operations:
-
-1. **create_schema** — Create a new L6 behavioral Schema
-   ```{"op": "create_schema", "schema_kind": "behavior_pattern", "content": "concise user-facing pattern", "retrieval_text": "behavior plus relevant situations", "evidence_list": ["fact_node_id_1", "fact_node_id_2"], "tags": ["tag1"]}```
-
-2. **add_evidence** — Add evidence to an existing Schema (content stays immutable)
-   ```{"op": "add_evidence", "node_id": "existing_schema_node_id", "evidence_list": ["new_fact_id_1"]}```
-
-3. **revise_schema** — Create a new version when new evidence materially changes the current state and retire the old version from active retrieval. Do not use it for compatible detail.
-   ```{"op": "revise_schema", "node_id": "old_schema_id", "schema_kind": "explicit_state", "content": "updated current profile", "retrieval_text": "updated retrieval text", "evidence_list": ["new_fact_id_1"], "tags": ["tag1"], "reason": "why the old wording would mislead"}```
-
-4. **add_edge** — Create a relationship between two Schemas
-   ```{"op": "add_edge", "source_id": "schema_id_1", "target_id": "schema_id_2", "reason": "relationship reason"}```
-
-5. **skip_fact** — Explicitly mark a candidate fact as reviewed without creating
-   a Schema. Use only for facts about another person, transient events, assistant
-   advice that does not establish a user trait, or facts already fully covered.
-   ```{"op": "skip_fact", "node_id": "candidate_fact_id", "reason": "not a durable user pattern"}```
-
-## Output Contract
-
-1. Output MUST be a JSON array wrapped in a ```json code block.
-2. If data is insufficient for reliable conclusions, output `[]`. In a
-   source-context review, `[]` means every candidate in that review was examined
-   and none supports a durable Schema.
-3. NO text outside the code block.
-4. evidence_list IDs must come from the fact node_ids provided in the materials.
-5. add_evidence / revise_schema node_id must come from existing Graph node IDs.
-6. For a source-context review, every candidate fact must appear in an evidence_list or skip_fact."""
+    ``lang`` is a language code (``en`` / ``zh-Hans`` / ``ja`` ...; legacy ``zh``
+    means zh-Hans). Every fragment comes from hy_memory/prompts/<language>.py.
+    """
+    code = _s2_language_code(lang)
+    base = get_prompt("SYSTEM2_AGENT_PROMPT", code)
+    output_instructions = get_prompt("SYSTEM2_OUTPUT_INSTRUCTIONS", code)
 
     if _S2_SCHEMA_EVIDENCE_GATE_ENABLED:
-        if lang == "zh":
-            output_instructions += """
+        output_instructions += get_prompt("SYSTEM2_SCHEMA_EVIDENCE_GATE", code)
 
-7. L6 只表示跨事件行为模式。create_schema 必须使用 user-owned 证据，且证据合计代表至少两个独立 raw/session。当 `source_raw_memory_ids` 包含多个独立写入时，一个合并后的 L2 事实也可以满足门槛。
-8. 单条明确身份、健康状态、设备使用、隶属关系、项目或偏好不要创建 L6；这些由 canonical L2 状态通道维护。"""
-        else:
-            output_instructions += """
-
-7. L6 represents cross-event behavioral patterns only. create_schema must use user-owned evidence representing at least two independent raw writes or sessions. A single reconciled fact can qualify when source_raw_memory_ids contains multiple independent writes.
-8. Do not create L6 for a single explicit identity, health state, equipment use, affiliation, project, or preference. Canonical L2 state projection owns those facts."""
-
-    # Remove the old "All Graph operations MUST go through tools" principle
-    base = base.replace("- 所有 Graph 操作必须通过 tools 执行\n", "")
-    base = base.replace("- All Graph operations MUST go through tools\n", "")
-    # Remove old tool-calling instructions from workflow
-    base = base.replace("调 `add_evidence` 添加证据", "使用 add_evidence 操作")
-    base = base.replace("call `add_evidence`", "use add_evidence operation")
-    base = base.replace("调 `add_evidence`", "使用 add_evidence")
-    base = base.replace("用 `add_edge`（RELATED_TO）", "使用 add_edge 操作")
-    base = base.replace("use `add_edge` (RELATED_TO)", "use add_edge operation")
+    # Remove the old "All Graph operations MUST go through tools" principle and
+    # the tool-calling wording from the workflow (single-call mode has no tools).
+    for old, new in get_prompt("SYSTEM2_SINGLE_CALL_REPLACEMENTS", code):
+        base = base.replace(old, new)
 
     return base + output_instructions
 
@@ -2554,10 +2340,14 @@ def _detect_language(materials: Dict[str, Any]) -> str:
 
 
 def _build_materials_message(materials: Dict[str, Any], lang: str = "zh") -> str:
-    """将预处理好的 materials 格式化为 Agent 能理解的 user message"""
-    is_zh = (lang == "zh")
+    """将预处理好的 materials 格式化为 Agent 能理解的 user message
 
-    parts = [("## 预处理材料\n" if is_zh else "## Preprocessed Materials\n")]
+    ``lang`` 为语言码（旧值 "zh" 视作 zh-Hans）；文案见 prompts/<language>.py 的
+    SYSTEM2_MATERIALS。
+    """
+    text = get_prompt("SYSTEM2_MATERIALS", _s2_language_code(lang))
+
+    parts = [text["title"]]
 
     stats = materials.get("stats", {})
     fresh = stats.get("fresh_facts", 0)
@@ -2566,55 +2356,35 @@ def _build_materials_message(materials: Dict[str, Any], lang: str = "zh") -> str
     graph_total = stats.get("graph_total_schemas", 0)
     recalled_schemas = stats.get("graph_schemas_recalled", 0)
 
-    if is_zh:
-        parts.append(f"### 统计\n- VDB 事实总数: {stats.get('total_facts_all', 0)}")
-        parts.append(f"- 新鲜事实（待处理）: {fresh}（已被引用排除={evidenced}）")
-        parts.append(f"- 聚类数: {stats.get('clusters_found', 0)}")
-        parts.append(
-            f"- 聚类内事实: {stats.get('clustered_facts_count', 0)}，"
-            f"未聚类补充: {stats.get('unclustered_facts_count', 0)}"
-        )
-        parts.append(f"- Graph Schema 总数: {stats.get('graph_total_schemas', 0)}（本次召回={recalled_schemas}）")
-        if graph_total == 0:
-            parts.append("- Graph 状态: **空**（首次认知加工）\n")
-        else:
-            parts.append("")
+    parts.append(text["stats"].format(
+        total=stats.get('total_facts_all', 0),
+        fresh=fresh,
+        evidenced=evidenced,
+        clusters=stats.get('clusters_found', 0),
+        clustered=stats.get('clustered_facts_count', 0),
+        unclustered=stats.get('unclustered_facts_count', 0),
+        graph_total=stats.get('graph_total_schemas', 0),
+        recalled=recalled_schemas,
+    ))
+    if graph_total == 0:
+        parts.append(text["graph_status_empty"])
     else:
-        parts.append(f"### Statistics\n- Total VDB facts: {stats.get('total_facts_all', 0)}")
-        parts.append(f"- Fresh facts (to process): {fresh} (evidenced_excluded={evidenced})")
-        parts.append(f"- Clusters found: {stats.get('clusters_found', 0)}")
-        parts.append(
-            f"- Facts in clusters: {stats.get('clustered_facts_count', 0)}, "
-            f"unclustered supplement: {stats.get('unclustered_facts_count', 0)}"
-        )
-        parts.append(f"- Graph Schemas total: {stats.get('graph_total_schemas', 0)} (recalled={recalled_schemas})")
-        if graph_total == 0:
-            parts.append("- Graph status: **EMPTY** (first cognitive processing run)\n")
-        else:
-            parts.append("")
+        parts.append("")
 
     # Clusters
     clusters = materials.get("clusters", [])
     clustered_ids = set()
     if clusters:
-        parts.append(("### 聚类结果\n" if is_zh else "### Cluster Results\n"))
+        parts.append(text["clusters_header"])
         for i, c in enumerate(clusters):
             n_facts = len(c['facts'])
             group_type = c.get("group_type", "semantic_cluster")
             if group_type == "holistic_therapy_review":
-                label = (
-                    f"{n_facts} 条跨会话用户事实；只归纳有证据的长期情绪/治疗模式"
-                    if is_zh else
-                    f"{n_facts} cross-session user facts; only evidence-backed durable emotional/therapy patterns"
-                )
+                label = text["label_holistic"].format(n=n_facts)
             elif group_type == "source_context_review":
-                label = (
-                    f"{n_facts} 条候选事实；原始写入仅用于主体与细节核验"
-                    if is_zh else
-                    f"{n_facts} candidate facts; raw write is only for subject/detail validation"
-                )
+                label = text["label_source_context"].format(n=n_facts)
             else:
-                label = f"{n_facts} 条，主题" if is_zh else f"{n_facts} facts, topic"
+                label = text["label_topic"].format(n=n_facts)
             parts.append(f"**Cluster {i}** ({label}: {c['centroid_text']})")
             for f in c["facts"]:
                 source_ids = list(f.get("source_raw_memory_ids") or [])
@@ -2628,8 +2398,7 @@ def _build_materials_message(materials: Dict[str, Any], lang: str = "zh") -> str
                 )
                 clustered_ids.add(f['node_id'])
             if group_type == "source_context_review" and c.get("raw_contexts"):
-                raw_label = "候选事实对应的原始片段" if is_zh else "Relevant raw excerpt per candidate"
-                parts.append(f"\n**{raw_label}:**")
+                parts.append(f"\n**{text['raw_label']}:**")
                 for item in c["raw_contexts"]:
                     parts.append(
                         f"- candidate_id={item.get('node_id')}, "
@@ -2638,30 +2407,12 @@ def _build_materials_message(materials: Dict[str, Any], lang: str = "zh") -> str
                     )
             parts.append("")
         if materials.get("holistic_therapy_review"):
-            parts.append(
-                (
-                    "这是一次有边界的夜间全局整理。最多创建 "
-                    f"{_S2_HOLISTIC_THERAPY_MAX_SCHEMAS} 条 anchored therapy Schema。"
-                    "优先联合不同 raw/session 中的持久 trigger/background、"
-                    "反复 emotional response 和用户已实际使用的 coping resource/decision constraint。"
-                    "证据不足时输出 []。\n"
-                    if is_zh else
-                    "This is one bounded nightly holistic consolidation pass. Create at most "
-                    f"{_S2_HOLISTIC_THERAPY_MAX_SCHEMAS} anchored therapy Schemas. "
-                    "Prefer joining durable trigger/background, recurring emotional response, "
-                    "and observed coping resource or decision constraint across different raw writes/sessions. "
-                    "Before create_schema, union raw_sources for its evidence IDs and require at least two "
-                    "distinct raw source IDs; two facts from one raw write are one event. "
-                    "Output [] when evidence is insufficient.\n"
-                )
-            )
+            parts.append(text["holistic_note"].format(
+                max_schemas=_S2_HOLISTIC_THERAPY_MAX_SCHEMAS,
+            ))
             companion_hints = materials.get("independent_source_companions") or {}
             if companion_hints:
-                parts.append(
-                    "**独立来源 companion 提示（只是候选，不是结论）:**"
-                    if is_zh else
-                    "**Independent-source companion hints (candidates, not conclusions):**"
-                )
+                parts.append(text["companion_header"])
                 for node_id, companions in companion_hints.items():
                     parts.append(
                         f"- {node_id} -> "
@@ -2677,14 +2428,8 @@ def _build_materials_message(materials: Dict[str, Any], lang: str = "zh") -> str
     all_facts = materials.get("unprocessed_facts", [])
     unclustered = [f for f in all_facts if f["node_id"] not in clustered_ids]
     if clusters and unclustered:
-        header = "### 未聚类事实（补充，次要）\n" if is_zh else "### Unclustered Facts (supplemental)\n"
-        hint = (
-            "以下事实未进入上述任一聚类，可在完成聚类主题加工后酌情审视；优先级低于聚类结果。\n"
-            if is_zh
-            else "Facts below were not grouped into any cluster above. Review after cluster themes; lower priority than cluster results.\n"
-        )
-        parts.append(header)
-        parts.append(hint)
+        parts.append(text["unclustered_header"])
+        parts.append(text["unclustered_hint"])
         for f in unclustered:
             parts.append(f"  - [{f['layer']}] {f['content']}  (id={f['node_id']})")
         parts.append("")
@@ -2692,10 +2437,7 @@ def _build_materials_message(materials: Dict[str, Any], lang: str = "zh") -> str
     # Existing graph nodes
     forward = materials.get("graph_forward", [])
     if forward:
-        if is_zh:
-            parts.append(f"### 相关 Graph 节点（通过 cluster centroid 向量召回，共 {len(forward)} 条）\n")
-        else:
-            parts.append(f"### Related Graph Nodes (retrieved via cluster centroid search, {len(forward)} hits)\n")
+        parts.append(text["forward_header"].format(count=len(forward)))
         for g in forward:
             sim = g.get("similarity", "")
             sim_str = f", sim={sim}" if sim else ""
@@ -2705,30 +2447,17 @@ def _build_materials_message(materials: Dict[str, Any], lang: str = "zh") -> str
             )
         parts.append("")
     elif graph_total == 0:
-        if is_zh:
-            parts.append("### 已有 Graph 节点\n当前 Graph 为空，这是首次认知加工。无需搜索 Graph，直接根据聚类结果创建 Schema。\n")
-        else:
-            parts.append("### Existing Graph Nodes\nThe Graph is currently EMPTY — this is the first cognitive processing run. Do NOT search the Graph (it will return nothing). Proceed directly to create Schemas from the cluster results.\n")
+        parts.append(text["graph_empty"])
     else:
         # Graph 有节点但 centroid search 没召回（可能 threshold 太高或语义距离远）
-        if is_zh:
-            parts.append(
-                f"### 已有 Graph 节点\n"
-                f"Graph 中共有 {stats.get('graph_total_schemas', 0)} 个 Schema，"
-                f"但 centroid 向量召回未命中相关节点。请根据聚类结果判断是否需要创建新 Schema。\n"
-            )
-        else:
-            parts.append(
-                f"### Existing Graph Nodes\n"
-                f"The Graph has {stats.get('graph_total_schemas', 0)} Schemas, "
-                f"but centroid-based vector recall found no matches. Decide based on cluster results whether new Schemas are needed.\n"
-            )
+        parts.append(text["graph_no_recall"].format(
+            graph_total=stats.get('graph_total_schemas', 0),
+        ))
 
     # Reverse hits
     reverse = materials.get("graph_reverse", [])
     if reverse:
-        parts.append(("### Graph 反向引用（已有 Schema 引用的 VDB 事实）\n" if is_zh
-                       else "### Graph Reverse References (VDB facts referenced by existing Schemas)\n"))
+        parts.append(text["reverse_header"])
         for r in reverse:
             parts.append(
                 f"  - [{r['layer']}] {r['content']} "
@@ -2739,26 +2468,9 @@ def _build_materials_message(materials: Dict[str, Any], lang: str = "zh") -> str
     # Existing tags（指导 Agent 复用已有 tag，减少发散）
     existing_tags = materials.get("existing_tags", [])
     if existing_tags:
-        if is_zh:
-            parts.append("### 已有标签（请优先从中选择，避免创建同义标签）\n")
-            parts.append(f"  {', '.join(existing_tags)}\n")
-        else:
-            parts.append("### Existing Tags (prefer reusing these over creating synonyms)\n")
-            parts.append(f"  {', '.join(existing_tags)}\n")
+        parts.append(text["tags_header"])
+        parts.append(f"  {', '.join(existing_tags)}\n")
 
-    if is_zh:
-        parts.append(
-            "请分析以上材料，输出操作 JSON 数组。"
-            "决定是否需要创建新的 Schema，或为已有 Schema 追加 evidence。"
-            "如果数据不足以得出可靠结论，输出空数组 `[]`。"
-            "打标签时请优先使用已有标签列表中的标签。"
-        )
-    else:
-        parts.append(
-            "Analyze the materials above and output a JSON array of operations. "
-            "Decide whether to create new Schemas, or add evidence to existing ones. "
-            "If the data is insufficient for reliable conclusions, output an empty array `[]`. "
-            "When tagging, prefer reusing tags from the existing tags list above."
-        )
+    parts.append(text["closing"])
 
     return "\n".join(parts)

hy_memory/pipelines/system2_writer.py

@@ -243,6 +243,7 @@ class System2Writer(WritePipeline):
             materials=materials,
             tool_executor=tool_executor,
             config=self.config,
+            language=payload.get("language"),
         )
 
         # 计算 timing
@@ -508,6 +509,7 @@ class System2Writer(WritePipeline):
                 materials=batch,
                 tool_executor=tool_executor,
                 config=self.config,
+                language=payload.get("language"),
             )
             batch_record = {
                 "batch_index": batch_index,
@@ -632,6 +634,7 @@ class System2Writer(WritePipeline):
                 materials=holistic_materials,
                 tool_executor=tool_executor,
                 config=self.config,
+                language=payload.get("language"),
             )
             if holistic_result.get("success"):
                 await self._mark_holistic_therapy_reviewed(
@@ -1044,11 +1047,26 @@ class System2Writer(WritePipeline):
         agent_id: str,
         llm_call,
         request_id: str = "",
+        language: Optional[str] = None,
     ) -> Dict[str, Any]:
-        """在 System2 Agent 之后运行跨域突破性归纳"""
+        """在 System2 Agent 之后运行跨域突破性归纳
+
+        sweeper 的 prompt 只有英文版（要求与输入 schema 同语言）。显式 language
+        时在每个 prompt 末尾追加该语言的输出规则，让产出用该语言书写。
+        """
         if not _SWEEPER_ENABLED:
             return {"skipped": True, "reason": "SWEEPER_ENABLED=false"}
 
+        if language:
+            from ..prompts import with_output_language
+
+            _base_call = llm_call
+
+            async def llm_call(prompt: str) -> str:
+                return await _base_call(
+                    with_output_language(prompt, language, explicit=True)
+                )
+
         try:
             from .cross_domain_sweeper import CrossDomainSweeper
 
@@ -1119,6 +1137,7 @@ class System2Writer(WritePipeline):
         self,
         user_id: str,
         agent_id: str = "default_agent",
+        language: Optional[str] = None,
     ) -> Dict[str, Any]:
         """
         手动触发 cross-domain sweeper（同步等待完成）。
@@ -1145,6 +1164,7 @@ class System2Writer(WritePipeline):
             agent_id=agent_id,
             llm_call=self._get_llm_call(),
             request_id=request_id,
+            language=language,
         )
         result["request_id"] = request_id
         return result
@@ -1154,6 +1174,7 @@ class System2Writer(WritePipeline):
         user_id: str,
         agent_id: str = "default_agent",
         max_batches: Optional[int] = None,
+        language: Optional[str] = None,
     ) -> Dict[str, Any]:
         """
         手动触发 System 2 认知加工（由调用方/App 层控制触发时机）。
@@ -1186,6 +1207,8 @@ class System2Writer(WritePipeline):
             "content": "",
             "created_at": datetime.now().isoformat(),
             "max_batches": max_batches,
+            # 显式 prompt 语言码（None → System 2 按 materials 做 zh/en 检测）
+            "language": language,
         }
         results = await self._run_system2_workers(payload)
 
@@ -1204,6 +1227,7 @@ class System2Writer(WritePipeline):
                 agent_id=agent_id,
                 llm_call=self._get_llm_call(),
                 request_id=request_id,
+                language=language,
             )
 
         agent_success = bool((results.get("system2_agent") or {}).get("success", True))

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)
@@ -280,6 +293,22 @@ class MemoryWriter(WritePipeline):
             custom["source_raw_memory_ids"] = source_ids
         return custom
 
+    def _flat_trimmed_raw(self, request: WriteRequest) -> str:
+        """把 request.messages 按 raw 统一规则裁剪后拼成 L1_RAW 文本。
+
+        只裁落库副本；request.messages 不动（本次 extractor 输入仍用完整 messages）。
+        """
+        import copy as _copy
+        from ..utils.raw_trim import trim_raw_messages
+
+        _coding_cfg = getattr(getattr(self, "config", None), "coding", None)
+        _trimmed_req = _copy.copy(request)
+        _trimmed_req.messages = trim_raw_messages(
+            request.messages,
+            tool_max_bytes=getattr(_coding_cfg, "tool_result_max_bytes", None),
+        )
+        return _trimmed_req.get_flat_content()
+
     @staticmethod
     def _attach_client_meta(custom: Dict[str, Any], request: Optional[WriteRequest]) -> None:
         """给新建节点挂上调用方 meta（单份 list）。
@@ -619,6 +648,7 @@ class MemoryWriter(WritePipeline):
         不查 VDB、不做"新写入 vs 库里已有"的对比，避免给 VDB 增加读压力。
         库内存量污染由 recall 侧异步删除逐步清理。best-effort：任何异常都
         回退到"不判重、全写入"，绝不影响 upsert 主流程。
+        `recall.intention_dedup_enabled=False` 时跳过批内判重，全部写入。
         """
         if not intentions:
             return []
@@ -644,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
@@ -981,6 +1015,7 @@ class MemoryWriter(WritePipeline):
                         # 这是一次 LLM 调用：prompt / 产出必须能在线上追到，
                         # 否则 badcase 只能看到"摘要内容不对"却拿不到输入
                         trace=self._make_trace_sink(request, "EPISODE_SUMMARY"),
+                        language=request.language,
                     )
                     if nid:
                         logger.info(
@@ -1194,6 +1229,7 @@ class MemoryWriter(WritePipeline):
                     self._make_trace_sink(request, "TOPIC_SUMMARY")
                     if request is not None else None
                 ),
+                language=getattr(request, "language", None),
             )
         except Exception as e:
             logger.warning(f"[topic-summary] failed (non-fatal): {e}")
@@ -1239,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]] = []
@@ -1270,10 +1297,36 @@ class MemoryWriter(WritePipeline):
             graph_store=getattr(self, "_graph_store", None),
             new_memory_embeddings=precomputed_embeddings,
             source=request.source,
+            language=request.language,
         )
 
         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 = {}
@@ -1284,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 输出，
         # 这里不再逐条打印（避免重复刷屏）。
 
@@ -2483,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
@@ -2554,9 +2596,14 @@ class MemoryWriter(WritePipeline):
         try:
             # 参数校验
             content = request.content
+            # raw 在写入时就按统一规则裁好（见 utils/raw_trim.py）：工具输出、长
+            # assistant 回复不再原样长期存储；历史拼接直接用存下来的文本，不再二次裁剪。
+            # request.messages 保持原样——本次 extractor 输入仍是完整 messages。
+            _raw_trimmed = False
             if not content and request.has_messages():
-                content = request.get_flat_content()
+                content = self._flat_trimmed_raw(request)
                 request.content = content
+                _raw_trimmed = True
 
             if not content:
                 response.error_code = 400
@@ -2627,6 +2674,9 @@ class MemoryWriter(WritePipeline):
                     vector_store = await self._get_vector_store()
                     layer_enum = MemoryLayer.from_string(suggested_layer)
                     _raw_custom: Dict[str, Any] = {}
+                    if _raw_trimmed:
+                        from ..utils.raw_trim import RAW_TRIMMED_KEY
+                        _raw_custom[RAW_TRIMMED_KEY] = True
                     self._attach_client_meta(_raw_custom, request)
                     mem_node = MemoryNode(
                         user_id=request.user_id,
@@ -2690,6 +2740,7 @@ class MemoryWriter(WritePipeline):
                         vector_store, request.user_id, request.agent_id,
                         exclude_memory_id=memory_id,
                         max_turns=_hist_turns * 2,  # k 轮对话 = k*2 条 message
+                        language=request.language,
                     )
                     _recent_history_ms = (_t_recent_history and (datetime.now() - _t_recent_history).total_seconds() * 1000) or 0.0
                     _recent_history_count = len([line for line in (_history_context or "").splitlines() if line.strip()])
@@ -2770,6 +2821,7 @@ class MemoryWriter(WritePipeline):
                             user_id=request.user_id,
                             agent_id=request.agent_id,
                             session_id=request.session_id or "default_session",
+                            language=request.language,
                         )
                         if finalize is finalize_dynamic_episode_capsules:
                             finalize_kwargs["summary_concurrency"] = getattr(
@@ -2929,13 +2981,18 @@ class MemoryWriter(WritePipeline):
         agent_id: Optional[str] = None,
         exclude_memory_id: str = "",
         max_turns: int = 20,
-        max_chars_assistant: int = 500,
+        max_chars_assistant: Optional[int] = None,
+        language: Optional[str] = None,
     ) -> str:
         """
         获取该用户最近的 L1_RAW 对话记录，按轮次拆分后拼成 history context。
+        language：显式 prompt 语言码，用于渲染名字行；None 时按内容判 zh/en。
 
         每条 L1_RAW 的 content 是多轮对话（[user]: ...\n[assistant]: ...）。
-        拆成单条 message 后，user 消息完整保留，assistant 消息截取前 max_chars_assistant 字符。
+        raw 在写入时已按 utils/raw_trim.py 的规则裁好（custom[RAW_TRIMMED_KEY]），
+        这里拆成单条 message 后直接拼接，不再二次裁剪。该规则之前写入的旧 raw
+        没有这个标记，仍按同一（幂等）规则裁剪后再拼，避免旧的长回复 / 工具输出
+        撑大 prompt。max_chars_assistant 只作用于这些旧 raw，默认同写入规则。
         最终取最近 max_turns 条 message（注意单位是 message 条数，非对话轮数；
         调用方按 k 轮 × 2 传入）。
 
@@ -2977,23 +3034,33 @@ class MemoryWriter(WritePipeline):
             # 避免把正文里形如 "[注]: xxx" 的普通文本误判成消息边界。
             import re as _re
             from .base import parse_user_name_line
-            _KNOWN_ROLES = {"user", "assistant", "system", "tool"}
             # 带方括号的任意 label（含对方真人名字）
             _labeled_prefix = _re.compile(r"^\[([^\]\n]{1,32})\]:\s?")
             # 无方括号的已知 role（历史数据容错，沿用旧正则的 `\[?...\]?` 宽容度）
             _bare_role_prefix = _re.compile(r"^(user|assistant|system|tool):\s?")
 
-            # (label, content) 元组列表；label 为 role 或对方真人名字
-            parsed: List[Tuple[str, str]] = []
+            from ..utils.raw_trim import (
+                DEFAULT_RAW_ASSISTANT_MAX_CHARS,
+                RAW_TRIMMED_KEY,
+                trim_raw_body,
+            )
+            if max_chars_assistant is None:
+                max_chars_assistant = DEFAULT_RAW_ASSISTANT_MAX_CHARS
+            _coding_cfg = getattr(getattr(self, "config", None), "coding", None)
+            _tool_max_bytes = getattr(_coding_cfg, "tool_result_max_bytes", None)
+
+            # (label, content, 是否旧 raw 需兼容裁剪) 元组列表；label 为 role 或对方真人名字
+            parsed: List[Tuple[str, str, bool]] = []
             user_name: str = ""
             for node in nodes:
                 content = node.content or ""
+                _legacy = not bool((node.custom or {}).get(RAW_TRIMMED_KEY))
                 for _line_idx, line in enumerate(content.split("\n")):
                     m = _labeled_prefix.match(line) or _bare_role_prefix.match(line)
                     if m:
                         label = m.group(1)
                         body = line[m.end():]
-                        parsed.append((label, body))
+                        parsed.append((label, body, _legacy))
                         continue
                     # 名字行只可能是每个 node content 的第一行（get_flat_content 插在文首）。
                     # 逐 node 判断而非用 `not parsed`：parsed 跨 node 累积，第二个 node
@@ -3006,36 +3073,41 @@ class MemoryWriter(WritePipeline):
                             continue
                     if parsed:
                         # 续行：拼回上一条 message（保留换行）
-                        prev_label, prev_body = parsed[-1]
-                        parsed[-1] = (prev_label, prev_body + "\n" + line)
+                        prev_label, prev_body, prev_legacy = parsed[-1]
+                        parsed[-1] = (prev_label, prev_body + "\n" + line, prev_legacy)
                     else:
                         # 开头就是无前缀行（异常/老数据）：当成 user 消息兜底
-                        parsed.append(("user", line))
+                        parsed.append(("user", line, _legacy))
 
             # 取最近 max_turns 条 message（按 message 截断，绝不从消息中间切开）
             recent = parsed[-max_turns:] if len(parsed) > max_turns else parsed
             if not recent:
                 return ""
 
-            # 格式化：非 user 侧整条截断（含对方真人），user 完整保留
+            # 格式化：新 raw 直接拼接；旧 raw 按写入同一规则兼容裁剪
             all_messages: List[str] = []
             if user_name:
                 from .base import render_user_name_line
                 from ..utils.lang_detect import is_chinese
 
-                _name_line = render_user_name_line(
-                    user_name,
-                    is_chinese("\n".join(b for _, b in recent)),
+                _name_line = (
+                    render_user_name_line(user_name, language=language)
+                    if language else
+                    render_user_name_line(
+                        user_name,
+                        is_chinese("\n".join(b for _, b, _ in recent)),
+                    )
                 )
                 if _name_line:
                     all_messages.append(_name_line)
-            for label, body in recent:
+            for label, body, legacy in recent:
+                if legacy:
+                    body = trim_raw_body(
+                        label, body,
+                        assistant_max_chars=max_chars_assistant,
+                        tool_max_bytes=_tool_max_bytes,
+                    )
                 body = body.strip()
-                # 截断口径：assistant + 对方真人（非已知 role 的 label）。
-                # user 完整保留；system / tool 沿用历史行为（不截断）。
-                _truncate = label == "assistant" or label not in _KNOWN_ROLES
-                if _truncate and len(body) > max_chars_assistant:
-                    body = body[:max_chars_assistant] + "..."
                 all_messages.append(f"[{label}]: {body}")
 
             return "\n".join(all_messages)
@@ -3267,6 +3339,7 @@ class MemoryWriter(WritePipeline):
                 existing_tags=existing_tags,
                 history_context=history_context,
                 basic_profile_fields=_basic_profile_fields,
+                language=request.language,
             )
             extract_timing["extract_total_ms"] = round(
                 (datetime.now() - _t_extract_total).total_seconds() * 1000, 2
@@ -3476,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
@@ -3604,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:

hy_memory/prompts/__init__.py

@@ -0,0 +1,242 @@
+"""Prompt registry: every multilingual LLM prompt, keyed by language code.
+
+One module per language (``en.py``, ``zh_hans.py``, ``ja.py`` ...) defines the
+same set of names (``PROMPT_NAMES``). Call sites look prompts up with
+``get_prompt(name, language)`` instead of importing a language module, so a
+new language only needs a new module and an entry in ``_MODULES``.
+
+Language selection (``resolve_language``):
+
+* explicit ``language`` (per call, else ``MemoryConfig.language`` /
+  ``MEMORY_LANGUAGE``) wins and is validated by ``normalize_language``;
+* otherwise the existing zh/en auto-detection runs unchanged
+  (``utils.lang_detect.is_chinese`` → ``zh-Hans`` or ``en``). Auto-detection
+  never picks any of the other languages.
+
+When the language is explicit, ``with_output_language`` appends
+``OUTPUT_LANGUAGE_DIRECTIVE`` so memories are written in that language even
+if the conversation uses another one. Auto-detected requests keep the
+"same language as the input" rule and their prompts are byte-identical to
+earlier releases.
+"""
+
+from __future__ import annotations
+
+import importlib
+from types import ModuleType
+from typing import Any, Dict, Optional, Tuple
+
+# Canonical codes, in documentation order.
+SUPPORTED_LANGUAGES: Tuple[str, ...] = (
+    "en",
+    "zh-Hans",
+    "zh-Hant",
+    "ja",
+    "es",
+    "de",
+    "pt",
+    "fr",
+    "ko",
+    "ru",
+    "id",
+)
+
+# Accepted aliases (matched case-insensitively, "_" treated as "-").
+LANGUAGE_ALIASES: Dict[str, str] = {
+    "zh": "zh-Hans",
+    "zh-cn": "zh-Hans",
+    "zh-sg": "zh-Hans",
+    "zh-hans-cn": "zh-Hans",
+    "zh-tw": "zh-Hant",
+    "zh-hk": "zh-Hant",
+    "zh-mo": "zh-Hant",
+    "zh-hant-tw": "zh-Hant",
+    "zh-hant-hk": "zh-Hant",
+    "pt-br": "pt",
+    "pt-pt": "pt",
+    "en-us": "en",
+    "en-gb": "en",
+}
+
+_MODULES: Dict[str, str] = {
+    "en": "en",
+    "zh-Hans": "zh_hans",
+    "zh-Hant": "zh_hant",
+    "ja": "ja",
+    "es": "es",
+    "de": "de",
+    "pt": "pt",
+    "fr": "fr",
+    "ko": "ko",
+    "ru": "ru",
+    "id": "id",
+}
+
+# Every language module must define all of these.
+PROMPT_NAMES: Tuple[str, ...] = (
+    # chat extraction
+    "EXTRACT_SYSTEM_PROMPT",
+    "STRUCTURE_METADATA_PROMPT",
+    "EXTRACT_FEW_SHOT",
+    "EXTRACT_PROMPT",
+    "EXTRACT_PROMPT_NO_INTENTION",
+    "NO_INTENTION_SECTION_PATTERN",
+    "NO_INTENTION_MEMORY_SECTION",
+    "NO_INTENTION_REPLACEMENTS",
+    "INTENTION_DISABLED_NOTE",
+    "USER_NAME_LINE",
+    # chat reconcile
+    "SEARCH_QUERY_PROMPT",
+    "RECONCILE_PROMPT",
+    "RECONCILE_STRUCTURE_METADATA_PROMPT",
+    "RECONCILE_FEW_SHOT",
+    # working / coding memory
+    "CODING_EXTRACT_PROMPT",
+    "CODING_EXTRACT_PROMPT_CODING",
+    "CODING_CONVERSATION_BLOCK",
+    "CODING_EMPTY_BLOCK",
+    "CODING_RECONCILE_PROMPT",
+    "CODING_FACT_RECONCILE_PROMPT",
+    "CODING_CHAIN_SUMMARY_PROMPT",
+    # summaries
+    "EPISODE_SUMMARY_PROMPT",
+    "TOPIC_SUMMARY_PROMPT",
+    # System 2 evolve
+    "SYSTEM2_AGENT_PROMPT",
+    "SYSTEM2_OUTPUT_INSTRUCTIONS",
+    "SYSTEM2_SCHEMA_EVIDENCE_GATE",
+    "SYSTEM2_SINGLE_CALL_REPLACEMENTS",
+    "SYSTEM2_MATERIALS",
+    # explicit-language output rule
+    "OUTPUT_LANGUAGE_DIRECTIVE",
+    "LANGUAGE_NAME",
+)
+
+# Prompts rendered with str.format(); the value lists the expected fields.
+# The rest are appended verbatim (their braces are literal JSON).
+FORMAT_FIELDS: Dict[str, Tuple[str, ...]] = {
+    "EXTRACT_PROMPT": ("content", "current_date", "last_messages", "memory_at"),
+    "EXTRACT_PROMPT_NO_INTENTION": ("content", "current_date", "last_messages", "memory_at"),
+    "USER_NAME_LINE": ("name",),
+    "SEARCH_QUERY_PROMPT": ("new_memories",),
+    "RECONCILE_PROMPT": ("current_date", "existing_memories", "few_shot_section", "new_memories"),
+    "CODING_EXTRACT_PROMPT": ("branch_present", "conversation_block", "workspace_present"),
+    "CODING_EXTRACT_PROMPT_CODING": ("branch_present", "conversation_block", "workspace_present"),
+    "CODING_CONVERSATION_BLOCK": ("history", "new"),
+    "CODING_RECONCILE_PROMPT": ("candidates_block", "drafts_block"),
+    "CODING_FACT_RECONCILE_PROMPT": ("candidates_block", "drafts_block"),
+    "CODING_CHAIN_SUMMARY_PROMPT": ("chain_block",),
+    "EPISODE_SUMMARY_PROMPT": ("memories",),
+    "TOPIC_SUMMARY_PROMPT": ("memories", "topic_name"),
+}
+
+# Fields of each SYSTEM2_MATERIALS entry (all other entries have none).
+SYSTEM2_MATERIALS_FIELDS: Dict[str, Tuple[str, ...]] = {
+    "title": (),
+    "stats": ("clustered", "clusters", "evidenced", "fresh", "graph_total", "recalled", "total", "unclustered"),
+    "graph_status_empty": (),
+    "clusters_header": (),
+    "label_holistic": ("n",),
+    "label_source_context": ("n",),
+    "label_topic": ("n",),
+    "raw_label": (),
+    "holistic_note": ("max_schemas",),
+    "companion_header": (),
+    "unclustered_header": (),
+    "unclustered_hint": (),
+    "forward_header": ("count",),
+    "graph_empty": (),
+    "graph_no_recall": ("graph_total",),
+    "reverse_header": (),
+    "tags_header": (),
+    "closing": (),
+}
+
+_loaded: Dict[str, ModuleType] = {}
+
+
+def _supported_text() -> str:
+    aliases = ", ".join(f"{k}->{v}" for k, v in LANGUAGE_ALIASES.items())
+    return f"supported: {', '.join(SUPPORTED_LANGUAGES)} (aliases: {aliases})"
+
+
+def normalize_language(language: Optional[str]) -> Optional[str]:
+    """Return the canonical code for ``language``; None/"" stays None.
+
+    Raises ValueError for an unknown code, listing the supported codes.
+    """
+    if language is None:
+        return None
+    if not isinstance(language, str):
+        raise ValueError(
+            f"language must be a string, got {type(language).__name__}; "
+            + _supported_text()
+        )
+    raw = language.strip()
+    if not raw:
+        return None
+    key = raw.replace("_", "-").lower()
+    for code in SUPPORTED_LANGUAGES:
+        if code.lower() == key:
+            return code
+    if key in LANGUAGE_ALIASES:
+        return LANGUAGE_ALIASES[key]
+    raise ValueError(f"unsupported language {language!r}; " + _supported_text())
+
+
+def detect_language_code(content: str = "", messages=None) -> str:
+    """The legacy automatic choice: ``zh-Hans`` if Chinese, else ``en``."""
+    from ..utils.lang_detect import is_chinese
+
+    return "zh-Hans" if is_chinese(content, messages=messages) else "en"
+
+
+def resolve_language(
+    language: Optional[str] = None,
+    content: str = "",
+    messages=None,
+) -> str:
+    """Explicit language if given (validated), else zh/en auto-detection."""
+    code = normalize_language(language)
+    if code is not None:
+        return code
+    return detect_language_code(content, messages=messages)
+
+
+def _module(language: str) -> ModuleType:
+    code = normalize_language(language) or "en"
+    mod = _loaded.get(code)
+    if mod is None:
+        mod = importlib.import_module(f"{__name__}.{_MODULES[code]}")
+        _loaded[code] = mod
+    return mod
+
+
+def get_prompt(name: str, language: Optional[str] = "en") -> Any:
+    """Look up prompt ``name`` for ``language`` (canonical code or alias)."""
+    if name not in PROMPT_NAMES:
+        raise KeyError(f"unknown prompt {name!r}")
+    return getattr(_module(language or "en"), name)
+
+
+def with_output_language(
+    prompt: str, language: Optional[str], explicit: bool,
+) -> str:
+    """Append the output-language rule when the language was set explicitly."""
+    if not explicit or not language:
+        return prompt
+    return prompt + get_prompt("OUTPUT_LANGUAGE_DIRECTIVE", language)
+
+
+__all__ = [
+    "SUPPORTED_LANGUAGES",
+    "LANGUAGE_ALIASES",
+    "PROMPT_NAMES",
+    "FORMAT_FIELDS",
+    "SYSTEM2_MATERIALS_FIELDS",
+    "normalize_language",
+    "detect_language_code",
+    "resolve_language",
+    "get_prompt",
+    "with_output_language",
+]

hy_memory/server.py

@@ -21,6 +21,11 @@ API Endpoints:
     GET  /healthz             — Health check (static, process alive)
     GET  /health              — Liveness probe (pings internal event loop; 503 if loop blocked)
     GET  /info                — Server info
+
+/add and /add_extracted accept an optional "language" (en, zh-Hans, zh-Hant, ja,
+es, de, pt, fr, ko, ru, id, or an alias such as zh-CN / zh-TW / pt-BR). An
+unknown code returns 400. /search has no language option: the search-time
+judge / rewrite prompts are English-only and keep the query's own language.
 """
 
 import asyncio
@@ -100,6 +105,20 @@ def _get_client():
     return _client
 
 
+def _language_arg(handler: BaseHTTPRequestHandler, body: Dict, kwargs: Dict) -> bool:
+    """Validate optional ``language`` and add it to kwargs; False after a 400 reply."""
+    if body.get("language") in (None, ""):
+        return True
+    from .prompts import normalize_language
+
+    try:
+        kwargs["language"] = normalize_language(body["language"])
+    except ValueError as e:
+        _json_response(handler, 400, {"error": str(e)})
+        return False
+    return True
+
+
 def _json_response(handler: BaseHTTPRequestHandler, status: int, data: Any):
     """Send a JSON response."""
     body = json.dumps(data, ensure_ascii=False, default=str).encode("utf-8")
@@ -436,6 +455,9 @@ class MemoryHTTPHandler(BaseHTTPRequestHandler):
                 kwargs["memory_at"] = datetime.fromisoformat(body["memory_at"])
             except Exception:
                 pass
+        # language: explicit prompt / memory language (see HyMemoryClient.add)
+        if not _language_arg(self, body, kwargs):
+            return
 
         result = client.add(data, **kwargs)
         _json_response(self, 200, result)
@@ -462,6 +484,8 @@ class MemoryHTTPHandler(BaseHTTPRequestHandler):
                 kwargs["memory_at"] = datetime.fromisoformat(body["memory_at"])
             except Exception:
                 pass
+        if not _language_arg(self, body, kwargs):
+            return
 
         result = client.add_extracted(contents, **kwargs)
         _json_response(self, 200, result)

hy_memory/utils/raw_trim.py

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

memhub/MEMORY.md

@@ -13,8 +13,8 @@
    接口先补 SDK。Runtime writers 停止后的 App 启动迁移可直接操作底层存储，
    但不得把迁移专用方法加入公共 Client。
 3. MemHub **不存 memory 实体**；**可以存 `memory_id`** 做组织/回执。原文进入 **SDK raw**。
-4. SDK raw 只保留滚动三天；一条 raw 对应一个完整 turn，只含真人 user 与
-   assistant，tool 不持久化。提取后的高层 memory 不受该窗口影响。
+4. SDK raw 全部保留，任何模式（lite / pro / ultra）都不删除；一条 raw 对应一个
+   完整 turn，只含真人 user 与 assistant，tool 不持久化。
 5. `source_raw_ids` 是 SDK 内部溯源关系，不是产品 Evidence 合同；记忆详情不提供
    “原始依据”或按 raw ID 展开原文的入口。
 
@@ -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.8`。MemHub 源码版本为 `1.0.5`
-（build 35），GitHub 仓库为
+源码当前固定使用公开 PyPI 正式版 `hy-memory==2.0.14`。MemHub 源码版本为 `1.0.6`
+（build 44），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.8`。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.8",
+      "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.8
+## 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-contract-fixes.test.ts

@@ -315,6 +315,8 @@ describe("catalog exit codes", () => {
       "models",
       "memories",
       "profile",
+      "settings",
+      "evolve",
       "graph-width",
       "host",
       "recall",

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

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

memhub/apps/cli/src/cli.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,
@@ -188,10 +196,38 @@ import {
   removeManagedCliLink,
   rollbackManagedCliLink,
 } from "./managed-cli-link.js";
+import {
+  type FeaturesDocument,
+  featuresExitCode,
+  parseFeaturesCommand,
+  renderFeaturesText,
+  runFeaturesCommand,
+} from "./memory-features-flow.js";
+import {
+  type LanguageDocument,
+  languageExitCode,
+  parseLanguageCommand,
+  renderLanguageText,
+  runLanguageCommand,
+} from "./memory-language-flow.js";
+import {
+  type EvolveDocument,
+  evolveExitCode,
+  type ModeDocument,
+  modeExitCode,
+  parseEvolveCommand,
+  parseSettingsCommand,
+  renderEvolveText,
+  renderModeText,
+  runEvolveCommand,
+  runModeCommand,
+} from "./memory-mode-flow.js";
 import {
   addMemory,
+  DEFAULT_USER_ID,
   isMemoryId,
   isRequestId,
+  isUserId,
   MEMORY_KINDS,
   MEMORY_SCENES,
   MEMORY_VARIANTS,
@@ -209,6 +245,7 @@ import {
   renderMemoryAddText,
   renderMemoryDetailText,
   renderMemoryPageText,
+  userIdParameters,
   validMemoryText,
 } from "./memory-report.js";
 import {
@@ -226,7 +263,6 @@ import {
   renderModelReportText,
 } from "./model-report.js";
 import {
-  activateModelProfile,
   editModelProfile,
   type ModelWriteDocument,
   modelWriteExitCode,
@@ -322,6 +358,8 @@ export interface RunControls {
   watchSignal?: AbortSignal;
   watchWait?: (milliseconds: number, signal: AbortSignal) => Promise<void>;
   watchNow?: () => string;
+  /** `memhub evolve --wait` polls on this; tests inject an instant one. */
+  sleep?: (milliseconds: number) => Promise<void>;
   readStdin?: () => Promise<Buffer | null>;
   stdinIsTTY?: boolean;
   /** Injectable onboarding prompter so the wizard can be driven in tests
@@ -538,6 +576,23 @@ async function runCommand(
       environment = { ...environment, ONE_MEMORY_DATA_DIR: lifted.dataDir };
     }
   }
+  // `--user-id <id>` is global to the memory commands: it names whose
+  // memories are read or written. It is lifted before dispatch so each
+  // command's own parser keeps seeing exactly the arguments it always did.
+  // `sources connect` gives the flag its own meaning and parses it itself.
+  let userId: string | undefined;
+  if (USER_ID_COMMANDS.has(arguments_[0] ?? "")) {
+    const lifted = liftUserIdOption(arguments_);
+    if (lifted === null) {
+      return reject(
+        findCommand(arguments_[0] ?? ""),
+        asJson,
+        "--user-id 无效：只能是 1–64 位字母、数字、点、下划线或连字符。",
+      );
+    }
+    arguments_ = lifted.arguments_;
+    userId = lifted.userId;
+  }
   environment = await environmentWithManagedDataDir(environment);
   const command = arguments_[0];
   if (command === undefined) return reject(undefined, asJson, "缺少命令。");
@@ -776,9 +831,11 @@ async function runCommand(
     const attachment = await attachToRuntimeOrNull(environment);
     if (attachment === null) return runtimeUnavailable(descriptor, asJson);
     if (parsed.kind === "status") {
-      const receipt = await readMemoryWrite(attachment, parsed.id).catch(
-        () => undefined,
-      );
+      const receipt = await readMemoryWrite(
+        attachment,
+        parsed.id,
+        userId,
+      ).catch(() => undefined);
       if (receipt === undefined) {
         return emitFailure(asJson, "write status", "memory_write_read_failed");
       }
@@ -812,6 +869,7 @@ async function runCommand(
         ? {}
         : { memory_at: parsed.memory_at }),
       ...(parsed.priority === undefined ? {} : { priority: parsed.priority }),
+      ...(userId === undefined ? {} : { user_id: userId }),
     });
     if (outcome.state !== "accepted") {
       emit(
@@ -957,9 +1015,12 @@ async function runCommand(
                 state: "empty",
                 events: 0,
                 invalid_lines: report.invalid_lines,
+                unrecognized_lines: report.unrecognized_lines,
               })}\n`
           : renderLogText(report.events, report.invalid_lines),
       );
+      // Only lines that are not JSON are damage. Records an older build wrote
+      // are left out without a warning: after an upgrade they are expected.
       if (report.invalid_lines) {
         process.stderr.write(
           `${PRODUCT}: 跳过 ${report.invalid_lines} 行损坏的诊断记录。\n`,
@@ -1582,6 +1643,7 @@ async function runCommand(
           limit: parsed.limit,
           character_budget: parsed.characterBudget,
           timeout_ms: parsed.timeoutMs,
+          ...userIdParameters(userId),
         })
       : ({
           schema_version: 2,
@@ -1655,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",
@@ -1677,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,
@@ -1691,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);
     }
@@ -1780,6 +1931,16 @@ async function runCommand(
   }
   if (named === "sources" && arguments_[1] !== "list") {
     const parsed = parseSourcesCommand(arguments_.slice(1));
+    if (
+      !parsed &&
+      arguments_.some((item) => item === "--user-id" || item === "--root")
+    ) {
+      return reject(
+        descriptor,
+        asJson,
+        "--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();
     if (parsed.kind === "receipt") {
       const connected = await connectRuntime(environment);
@@ -1981,12 +2142,17 @@ async function runCommand(
     return sourceProgressExitCode(document);
   }
   if (named === "profile") {
+    const profileFlags = arguments_.slice(1);
     if (
-      arguments_.filter((item) => item === "--json").length > 1 ||
-      arguments_.slice(1).some((value) => value !== "--json")
+      profileFlags.filter((item) => item === "--json").length > 1 ||
+      profileFlags.filter((item) => item === "--versions").length > 1 ||
+      profileFlags.some((value) => value !== "--json" && value !== "--versions")
     ) {
       return usage();
     }
+    if (profileFlags.includes("--versions")) {
+      return await profileVersionsCommand(environment, { asJson, userId });
+    }
     const connected = await connectRuntime(environment, {
       readerTimeoutMs: 15_000,
     });
@@ -2004,7 +2170,11 @@ async function runCommand(
       );
       return connected.exitCode;
     }
-    const outcome = await connected.reader<unknown>("/api/v2/user-profile");
+    const profileUser = userIdParameters(userId);
+    const outcome =
+      profileUser.user_id === undefined
+        ? await connected.reader<unknown>("/api/v2/user-profile")
+        : await connected.reader<unknown>("/api/v2/user-profile", profileUser);
     const value =
       outcome.state === "ok"
         ? (outcome.data as {
@@ -2109,7 +2279,7 @@ async function runCommand(
     }
     const { reader, operations } = connected;
     if (parsed.kind === "list") {
-      const document = await readMemoryPage(reader, parsed.query);
+      const document = await readMemoryPage(reader, parsed.query, userId);
       emit(
         asJson
           ? `${JSON.stringify(document)}\n`
@@ -2122,6 +2292,7 @@ async function runCommand(
         reader,
         parsed.memoryId,
         parsed.namespace,
+        userId,
       );
       emit(
         asJson
@@ -2133,8 +2304,8 @@ async function runCommand(
     if (parsed.kind === "add" || parsed.kind === "add-status") {
       const document =
         parsed.kind === "add"
-          ? await addMemory(operations, text ?? "", parsed.requestId)
-          : await readMemoryAddStatus(reader, parsed.requestId);
+          ? await addMemory(operations, text ?? "", parsed.requestId, userId)
+          : await readMemoryAddStatus(reader, parsed.requestId, userId);
       emit(
         asJson
           ? `${JSON.stringify(document)}\n`
@@ -2149,33 +2320,166 @@ async function runCommand(
             content: text,
             ...namespaceParameters(parsed.namespace),
             ...(parsed.task === undefined ? {} : { task: parsed.task }),
+            ...userIdParameters(userId),
           })
         : await operations.delete<unknown>(
-            withQuery(memoryPath, namespaceParameters(parsed.namespace)),
+            withQuery(memoryPath, {
+              ...namespaceParameters(parsed.namespace),
+              ...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" &&
+    arguments_.slice(1).find((value) => value !== "--json") === "features"
+  ) {
+    const parsed = parseFeaturesCommand(
+      arguments_
+        .slice(1)
+        .filter((value, index, all) => index !== all.indexOf("features")),
+    );
+    if (!parsed) return usage();
+    const connected = await connectRuntime(environment);
+    if (!connected.ok) {
+      const document: FeaturesDocument = {
+        schema_version: 1,
+        product: PRODUCT,
+        command: "settings features",
+        state: "unavailable",
+        code: connected.code,
+      };
+      emit(
+        asJson ? `${JSON.stringify(document)}\n` : renderFeaturesText(document),
+      );
+      return connected.exitCode;
+    }
+    const document = await runFeaturesCommand(
+      parsed,
+      connected.reader,
+      connected.operations,
+    );
+    emit(
+      asJson ? `${JSON.stringify(document)}\n` : renderFeaturesText(document),
+    );
+    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();
+    const connected = await connectRuntime(environment);
+    if (!connected.ok) {
+      const document: ModeDocument = {
+        schema_version: 1,
+        product: PRODUCT,
+        command: "settings mode",
+        state: "unavailable",
+        code: connected.code,
+      };
+      emit(asJson ? `${JSON.stringify(document)}\n` : renderModeText(document));
+      return connected.exitCode;
+    }
+    const document = await runModeCommand(
+      parsed,
+      connected.reader,
+      connected.operations,
+    );
+    emit(asJson ? `${JSON.stringify(document)}\n` : renderModeText(document));
+    return modeExitCode(document);
+  }
+  if (named === "evolve") {
+    const parsed = parseEvolveCommand(arguments_.slice(1));
+    if (!parsed) return usage();
+    const connected = await connectRuntime(environment);
+    if (!connected.ok) {
+      const document: EvolveDocument = {
+        schema_version: 1,
+        product: PRODUCT,
+        command: "evolve",
+        state: "unavailable",
+        code: connected.code,
+      };
+      emit(
+        asJson ? `${JSON.stringify(document)}\n` : renderEvolveText(document),
+      );
+      return connected.exitCode;
+    }
+    const document = await runEvolveCommand(parsed, {
+      userId: userIdParameters(userId).user_id,
+      reader: connected.reader,
+      operations: connected.operations,
+      sleep: controls.sleep,
+    });
+    emit(asJson ? `${JSON.stringify(document)}\n` : renderEvolveText(document));
+    return evolveExitCode(document);
   }
   if (named === "graph-width") {
     const parsed = parseGraphWidthCommand(arguments_.slice(1));
@@ -3675,13 +3979,21 @@ async function connectSources(
       asJson,
     );
   }
-  if (parsed.importHistory) {
+  // Another user's Hermes profile is granted and imported in one connect
+  // request: only that request can carry a user and a root.
+  if (
+    parsed.importHistory ||
+    parsed.userId !== undefined ||
+    parsed.root !== undefined
+  ) {
     const document = await connectSourcesWithImport(reader, operations, {
       sourceIds: parsed.sourceIds,
       confirmOverrides: parsed.confirmOverrides,
       ...(parsed.requestId === undefined
         ? {}
         : { requestId: parsed.requestId }),
+      ...(parsed.userId === undefined ? {} : { userId: parsed.userId }),
+      ...(parsed.root === undefined ? {} : { root: parsed.root }),
     });
     emitFlowDocument(document, asJson);
     return flowExitCode(document);
@@ -3834,6 +4146,108 @@ async function emitModelReceipt(
 
 /** Attach to a verified Runtime, telling a stopped one (exit 3) from one
  * that is up but unusable (exit 1). */
+/**
+ * `memhub profile --versions`: the long-term profile's L0 version chains,
+ * latest first, so a value that replaced a better one can be found by id.
+ */
+async function profileVersionsCommand(
+  environment: NodeJS.ProcessEnv,
+  options: { asJson: boolean; userId?: string },
+): Promise<number> {
+  const fail = (state: string, code: string, exitCode: number): number => {
+    emit(
+      options.asJson
+        ? `${JSON.stringify({ schema_version: 2, product: PRODUCT, state, code })}\n`
+        : `画像版本读取失败：${code}\n`,
+    );
+    return exitCode;
+  };
+  const connected = await connectRuntime(environment, {
+    readerTimeoutMs: 15_000,
+  });
+  if (!connected.ok) {
+    return fail("unavailable", connected.code, connected.exitCode);
+  }
+  const outcome = await connected.reader<unknown>(
+    "/api/v2/user-profile/versions",
+    userIdParameters(options.userId),
+  );
+  const chains = outcome.state === "ok" ? profileChains(outcome.data) : null;
+  if (outcome.state !== "ok" || chains === null) {
+    return fail(
+      outcome.state === "ok" ? "invalid" : outcome.state,
+      outcome.state === "ok" ? "response_invalid" : outcome.code,
+      EXIT_FAILED,
+    );
+  }
+  if (options.asJson) {
+    emit(
+      `${JSON.stringify({
+        schema_version: 2,
+        product: PRODUCT,
+        state: "ok",
+        ...(outcome.data as object),
+      })}\n`,
+    );
+    return EXIT_OK;
+  }
+  if (chains.length === 0) {
+    emit("尚未形成用户画像版本。\n");
+    return EXIT_OK;
+  }
+  const lines: string[] = [];
+  for (const chain of chains) {
+    lines.push(`画像 ${chain.memory_id}（${chain.status}）`);
+    for (const version of chain.versions) {
+      const when =
+        typeof version.gmt_created === "number"
+          ? new Date(version.gmt_created * 1000).toISOString()
+          : "时间未知";
+      lines.push(
+        `  ${version.current ? "*" : " "} ${version.memory_id}  ${when}  ${version.content}`,
+      );
+    }
+  }
+  lines.push(
+    "* 表示当前生效的版本；删除错误版本：memhub memories delete <memory-id> --yes",
+  );
+  emit(`${lines.join("\n")}\n`);
+  return EXIT_OK;
+}
+
+type ProfileChainView = {
+  memory_id: string;
+  status: string;
+  versions: {
+    memory_id: string;
+    content: string;
+    gmt_created?: number | null;
+    current: boolean;
+  }[];
+};
+
+function profileChains(value: unknown): ProfileChainView[] | null {
+  if (!value || typeof value !== "object") return null;
+  const chains = (value as { chains?: unknown }).chains;
+  if (!Array.isArray(chains)) return null;
+  const valid = chains.every(
+    (chain) =>
+      chain &&
+      typeof chain === "object" &&
+      typeof (chain as ProfileChainView).memory_id === "string" &&
+      typeof (chain as ProfileChainView).status === "string" &&
+      Array.isArray((chain as ProfileChainView).versions) &&
+      (chain as ProfileChainView).versions.every(
+        (version) =>
+          version &&
+          typeof version.memory_id === "string" &&
+          typeof version.content === "string" &&
+          typeof version.current === "boolean",
+      ),
+  );
+  return valid ? (chains as ProfileChainView[]) : null;
+}
+
 async function connectRuntime(
   environment: NodeJS.ProcessEnv,
   options?: { readerTimeoutMs?: number },
@@ -3969,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");
 }
@@ -4101,6 +4519,8 @@ const SDK_MIGRATION_FAILURES: Record<string, string> = {
     "核对发现新版本还读不到你的全部记忆，没有切换数据源。",
   sdk_migration_model_profile_required:
     "迁移需要先有可用的模型配置，用来核对新版本能否读回记忆。请先用 memhub models setup 完成配置，再运行 memhub restart 重试。",
+  sdk_migration_vector_profile_missing:
+    "记忆的向量来自一个已删除的模型配置，当前配置读不回它们，所以没有迁移。请重新添加并启用那个模型配置，再运行 memhub restart 重试。",
 };
 
 const MIGRATION_ISSUES_URL =
@@ -5022,6 +5442,8 @@ type ModelsCommand =
       configFile: string;
       apiKeyFile?: string;
       activate: boolean;
+      confirmed: boolean;
+      follow?: boolean;
     }
   | {
       kind: "edit";
@@ -5029,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 };
@@ -5070,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;
@@ -5100,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;
@@ -5124,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";
@@ -5131,14 +5632,23 @@ type SourcesCommand =
       importHistory: boolean;
       confirmOverrides: boolean;
       requestId?: string;
+      /** `--user-id`: whose grant (Hermes only). Absent for `local`. */
+      userId?: string;
+      /** `--root`: an absolute root other than the candidate (Hermes only). */
+      root?: string;
     }
   | { kind: "all"; importHistory: boolean; confirmOverrides: boolean }
   | { kind: "receipt"; requestId: string };
 
 const SOURCE_ID_SHAPE = /^[a-z0-9][a-z0-9-]{0,127}$/;
 
+/** Only Hermes keeps one history per profile, so only Hermes may be
+ * connected for another user or from another root. */
+const MULTI_USER_SOURCES = new Set(["hermes"]);
+
 /** `sources connect <id> [<id> ...] | --all-detected [--import]
- * [--confirm-overrides] [--request-id <uuid>]` and `sources receipt <id>`.
+ * [--confirm-overrides] [--request-id <uuid>]
+ * [--user-id <id>] [--root <path>]` and `sources receipt <id>`.
  *
  * Sources may be named positionally or with repeated `--source` (the old
  * `init --source` spelling is rewritten to this command). */
@@ -5154,6 +5664,8 @@ function parseSourcesCommand(rest: readonly string[]): SourcesCommand | null {
   const sourceIds: string[] = [];
   const switches = new Set<string>();
   let requestId: string | undefined;
+  let userId: string | undefined;
+  let root: string | undefined;
   for (let index = 1; index < tokens.length; index += 1) {
     const token = tokens[index];
     if (["--import", "--confirm-overrides", "--all-detected"].includes(token)) {
@@ -5161,6 +5673,21 @@ function parseSourcesCommand(rest: readonly string[]): SourcesCommand | null {
       switches.add(token);
       continue;
     }
+    if (token === "--user-id" || token === "--root") {
+      const value = tokens[index + 1];
+      if (value === undefined || value.startsWith("--")) return null;
+      if (token === "--user-id") {
+        if (userId !== undefined || !isUserId(value)) return null;
+        userId = value;
+      } else {
+        if (root !== undefined) return null;
+        const expanded = expandRootPath(value);
+        if (expanded === null) return null;
+        root = expanded;
+      }
+      index += 1;
+      continue;
+    }
     if (token === "--source" || token === "--request-id") {
       const value = tokens[index + 1];
       if (value === undefined || value.startsWith("--")) return null;
@@ -5184,10 +5711,23 @@ function parseSourcesCommand(rest: readonly string[]): SourcesCommand | null {
   const confirmOverrides = switches.has("--confirm-overrides");
   if (
     requestId !== undefined &&
-    (!OPERATION_ID.test(requestId) || !importHistory)
+    (!OPERATION_ID.test(requestId) ||
+      !(importHistory || userId !== undefined || root !== undefined))
   ) {
     return null;
   }
+  // `--user-id local` is the default and changes nothing.
+  if (userId === DEFAULT_USER_ID) userId = undefined;
+  if (userId !== undefined || root !== undefined) {
+    // One Hermes profile per connect: the user and root name one grant.
+    if (
+      switches.has("--all-detected") ||
+      sourceIds.length !== 1 ||
+      !MULTI_USER_SOURCES.has(sourceIds[0])
+    ) {
+      return null;
+    }
+  }
   if (switches.has("--all-detected")) {
     // One names exact sources, the other means "whatever is detected".
     if (sourceIds.length > 0 || requestId !== undefined) return null;
@@ -5200,9 +5740,24 @@ function parseSourcesCommand(rest: readonly string[]): SourcesCommand | null {
     importHistory,
     confirmOverrides,
     ...(requestId === undefined ? {} : { requestId }),
+    ...(userId === undefined ? {} : { userId }),
+    ...(root === undefined ? {} : { root }),
   };
 }
 
+/** `--root` as an absolute path: a leading `~` is the home directory, a
+ * relative path is taken from the working directory. Core expands nothing. */
+function expandRootPath(value: string): string | null {
+  if (value.length === 0 || /[\0\r\n]/.test(value)) return null;
+  const expanded =
+    value === "~"
+      ? os.homedir()
+      : value.startsWith("~/")
+        ? path.join(os.homedir(), value.slice(2))
+        : value;
+  return path.resolve(expanded);
+}
+
 function parseGraphWidthCommand(
   rest: readonly string[],
 ): { decision: GraphWidthDecision; confirmed: boolean } | null {
@@ -6596,6 +7151,36 @@ const OWN_DATA_DIR_COMMANDS = new Set([
 
 /** Remove one `--data-dir <absolute path>` from argv; null when it is
  * repeated, missing its value, or not an absolute path. */
+/** Memory commands that honour the global `--user-id`. */
+const USER_ID_COMMANDS = new Set([
+  "memories",
+  "recall",
+  "profile",
+  "write",
+  "evolve",
+]);
+
+/**
+ * Take `--user-id <id>` out of the arguments. The default user (`local`) is
+ * returned as undefined, so a default request names no user at all and stays
+ * byte-identical to one sent before multi-user support.
+ */
+function liftUserIdOption(
+  arguments_: readonly string[],
+): { arguments_: string[]; userId?: string } | null {
+  const index = arguments_.indexOf("--user-id");
+  if (index === -1) return { arguments_: [...arguments_] };
+  if (arguments_.indexOf("--user-id", index + 1) !== -1) return null;
+  const value = arguments_[index + 1];
+  if (value === undefined || value.startsWith("--") || !isUserId(value)) {
+    return null;
+  }
+  return {
+    arguments_: [...arguments_.slice(0, index), ...arguments_.slice(index + 2)],
+    ...(value === DEFAULT_USER_ID ? {} : { userId: value }),
+  };
+}
+
 function liftDataDirOption(
   arguments_: readonly string[],
 ): { arguments_: string[]; dataDir?: string } | null {

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

@@ -68,6 +68,12 @@ const JSON_OPTION: CommandOption = {
   flag: "--json",
   summary: "以 JSON 输出到 stdout，供脚本与 Agent 消费。",
 };
+/** Global to the memory commands: whose memories are read or written. */
+const USER_ID_OPTION: CommandOption = {
+  flag: "--user-id <id>",
+  summary:
+    "读写哪个用户的记忆，默认 local（App 用的就是 local）。1–64 位字母、数字、点、下划线或连字符；其他用户的记忆来自用 sources connect hermes --user-id 接入的 Hermes profile。",
+};
 const WATCH_OPTION: CommandOption = {
   flag: "--watch",
   summary: "串行持续刷新；Ctrl-C 只停止观察，不停止 Runtime。",
@@ -252,15 +258,25 @@ export const COMMANDS: readonly CommandDescriptor[] = [
   {
     name: "sources",
     summary:
-      "列出来源，直接接入来源，或按 request id 查接入回执。connect 不加 --import 只授权（处理保持冻结：不导入历史、不扫描新会话）；加 --import 同时导入历史并开启持续同步，返回 request id。目录来自环境变量覆盖的来源必须加 --confirm-overrides。",
+      "列出来源，直接接入来源，或按 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 --all-detected [--import] [--confirm-overrides] [--json]\n            memhub sources receipt <request-id> [--json]",
+      "memhub sources list [--json]\n            memhub sources connect <id> [<id> ...] [--import] [--confirm-overrides] [--request-id <uuid>] [--json]\n            memhub sources connect hermes --user-id <id> --root <path> [--import] [--request-id <uuid>] [--json]\n            memhub sources connect --all-detected [--import] [--confirm-overrides] [--json]\n            memhub sources receipt <request-id> [--json]",
     options: [
       {
         flag: "--import",
         summary:
           "接入后立即导入历史会话并开启持续同步；不加时只授权，处理保持冻结。",
       },
+      {
+        flag: "--user-id <id>",
+        summary:
+          "只用于 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>",
+        summary:
+          "只用于 hermes：读取的根目录（~ 会展开为主目录）。默认是 Hermes 自己的目录 ~/.hermes。",
+      },
       {
         flag: "--all-detected",
         summary:
@@ -345,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: [
       {
@@ -361,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,
@@ -371,9 +397,9 @@ 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>] [--json]\n            memhub memories show <memory-id> [--kind <kind>] [--variant <variant>] [--json]\n            memhub memories add <text> [--request-id <uuid>] [--json]\n            memhub memories add --content-file <path> [--request-id <uuid>] [--json]\n            memhub memories add-status <request-id> [--json]\n            memhub memories update <memory-id> --content-file <path> [--kind <kind>] [--variant <variant>] [--task <text>] [--json]\n            memhub memories delete <memory-id> [--kind <kind>] [--variant <variant>] [--yes] [--json]",
+      "memhub memories list [--scene <all|chat|working|coding>] [--source <id>] [--query <text>] [--status <state>] [--offset <n>] [--limit <n>] [--user-id <id>] [--json]\n            memhub memories show <memory-id> [--kind <kind>] [--variant <variant>] [--user-id <id>] [--json]\n            memhub memories add <text> [--request-id <uuid>] [--user-id <id>] [--json]\n            memhub memories add --content-file <path> [--request-id <uuid>] [--user-id <id>] [--json]\n            memhub memories add-status <request-id> [--user-id <id>] [--json]\n            memhub memories update <memory-id> --content-file <path> [--kind <kind>] [--variant <variant>] [--task <text>] [--user-id <id>] [--json]\n            memhub memories delete <memory-id> [--kind <kind>] [--variant <variant>] [--yes] [--user-id <id>] [--json]",
     options: [
       {
         flag: "--scene <all|chat|working|coding>",
@@ -411,15 +437,82 @@ export const COMMANDS: readonly CommandDescriptor[] = [
           "add 的幂等键；用同一个 id 重试只会读回第一次的结果，不会重复添加。不给时自动生成并输出。",
       },
       DESTRUCTIVE_CONFIRM_OPTION,
+      USER_ID_OPTION,
       JSON_OPTION,
     ],
     exit_codes: RUNTIME_EXITS,
   },
   {
     name: "profile",
-    summary: "读取 SDK 组装后的用户长期画像（L0 + 已启用的长期画像补充）。",
-    usage: "memhub profile [--json]",
-    options: [JSON_OPTION],
+    summary:
+      "读取 SDK 组装后的用户长期画像（L0 + 已启用的长期画像补充）；--versions 列出 L0 画像的版本链（最新在前，* 为当前版本）。",
+    usage: "memhub profile [--versions] [--user-id <id>] [--json]",
+    options: [
+      {
+        flag: "--versions",
+        summary:
+          "列出 L0 基本信息的版本链（get_user_basic_info），用于找出覆盖了正确值的错误版本。",
+      },
+      USER_ID_OPTION,
+      JSON_OPTION,
+    ],
+    exit_codes: RUNTIME_EXITS,
+  },
+  {
+    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 意图提取（默认开）、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 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]",
+        summary: "不带模式只显示当前模式；带模式时先显示切换计划。",
+      },
+      {
+        flag: "features set <name>=<true|false>",
+        summary:
+          "开关一个或多个 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,
+    ],
+    exit_codes: RUNTIME_EXITS,
+  },
+  {
+    name: "evolve",
+    summary:
+      "立即为一个用户运行记忆进化（System 2，仅 ultra 模式）。在后台运行并返回运行 ID；--wait 等待结果。同一用户同时只运行一次；每晚的自动进化由 Runtime 按设置安排。",
+    usage:
+      "memhub evolve [--user-id <id>] [--agent-id <id>] [--max-batches <n>] [--wait] [--json]",
+    options: [
+      USER_ID_OPTION,
+      {
+        flag: "--agent-id <id>",
+        summary:
+          "进化哪个 agent 的记忆，默认 all-apps（MemHub 写入记忆用的 agent）。",
+      },
+      {
+        flag: "--max-batches <n>",
+        summary: "每轮最多处理的批次数（1–1000），默认由 SDK 决定。",
+      },
+      { flag: "--wait", summary: "等待这次进化结束再返回。" },
+      JSON_OPTION,
+    ],
     exit_codes: RUNTIME_EXITS,
   },
   {
@@ -475,7 +568,7 @@ export const COMMANDS: readonly CommandDescriptor[] = [
     summary:
       "从原始对话与已沉淀记忆统一检索上下文；本地只读，不调用模型、不触发补索引。文本输出标明每条是「原始对话摘录」还是「记忆」（JSON 里是 kind: raw|memory）。",
     usage:
-      "memhub recall <query> [--kind <raw|memory>] [--source <id>] [--limit <n>] [--character-budget <n>] [--timeout-ms <n>] [--json]\n            memhub recall --query-file <path> [...]\n            memhub recall --stdin [...]",
+      "memhub recall <query> [--kind <raw|memory>] [--source <id>] [--limit <n>] [--character-budget <n>] [--timeout-ms <n>] [--user-id <id>] [--json]\n            memhub recall --query-file <path> [...]\n            memhub recall --stdin [...]",
     options: [
       {
         flag: "--query-file <path>",
@@ -502,6 +595,7 @@ export const COMMANDS: readonly CommandDescriptor[] = [
         flag: "--timeout-ms <n>",
         summary: "Core 查询时限 50..30000 毫秒，默认 2000。",
       },
+      USER_ID_OPTION,
       JSON_OPTION,
     ],
     exit_codes: RUNTIME_EXITS,
@@ -650,7 +744,7 @@ export const COMMANDS: readonly CommandDescriptor[] = [
     summary:
       "提交一段 OpenAI 格式的对话（messages）到写入队列，异步加工成记忆；或按 request id 查询状态。request id 是幂等键：不给时自动生成并输出，重试请带上同一个。新增一条结论式记忆请用 memories add。",
     usage:
-      "memhub write submit --messages-file <path> --session <id> [--source <id>] [--request-id <id>] [--memory-at <RFC3339>] [--live] [--json]\n            memhub write status <request-id> [--json]",
+      "memhub write submit --messages-file <path> --session <id> [--source <id>] [--request-id <id>] [--memory-at <RFC3339>] [--live] [--user-id <id>] [--json]\n            memhub write status <request-id> [--user-id <id>] [--json]",
     options: [
       {
         flag: "--messages-file <path>",
@@ -666,6 +760,7 @@ export const COMMANDS: readonly CommandDescriptor[] = [
       },
       { flag: "--memory-at <RFC3339>", summary: "对话发生时间，必须带时区。" },
       { flag: "--live", summary: "优先处理。" },
+      USER_ID_OPTION,
       JSON_OPTION,
     ],
     exit_codes: RUNTIME_EXITS,

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

@@ -76,6 +76,8 @@ const COMMANDS = [
   "models",
   "memories",
   "profile",
+  "settings",
+  "evolve",
   "graph-width",
   "host",
   "recall",
@@ -633,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

@@ -10,6 +10,8 @@ export interface ContextSearchInput {
   limit: number;
   character_budget: number;
   timeout_ms: number;
+  /** Whose memories to search. Omitted for the default user (`local`). */
+  user_id?: string;
 }
 
 /** The CLI's JSON document mirrors Core's SDK-native context schema v2. */
@@ -95,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,15 +8,30 @@ 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`). */
+const EVOLVE_RUN =
+  /^\/api\/v2\/evolve\/[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/;
 const SDK_MEMORY_DETAIL = /^\/api\/v2\/memories\/[A-Za-z0-9][\w.-]{0,127}$/;
 /** Status of one `POST /api/v2/memories` addition, by its request id. */
 const MEMORY_ADDITION =
@@ -155,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 =
@@ -210,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),
+    };
   };
 }
 
@@ -219,6 +250,7 @@ export function isReadOnlyPath(path: string): boolean {
   if (IMPORT_JOB.test(path)) return true;
   if (OPERATION_RECEIPT.test(path)) return true;
   if (MEMORY_ADDITION.test(path)) return true;
+  if (EVOLVE_RUN.test(path)) return true;
   if (!SDK_MEMORY_DETAIL.test(path)) return false;
   const segment = path.slice("/api/v2/memories/".length);
   return !(RESERVED_MEMORY_SEGMENTS as readonly string[]).includes(segment);
@@ -239,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 {
@@ -310,6 +347,8 @@ export async function submitMemoryWrite(
     messages: readonly OpenAIMessage[];
     memory_at?: string;
     priority?: "live" | "normal";
+    /** Whose memory this is. Omitted for the default user (`local`). */
+    user_id?: string;
   },
 ): Promise<MemoryWriteOutcome> {
   let response: { status: number; data: unknown };
@@ -327,6 +366,9 @@ export async function submitMemoryWrite(
         ...(request.priority === undefined
           ? {}
           : { priority: request.priority }),
+        ...(request.user_id === undefined || request.user_id === "local"
+          ? {}
+          : { user_id: request.user_id }),
       },
       {
         headers: { Authorization: `Bearer ${attachment.apiToken}` },
@@ -469,11 +511,16 @@ export async function deleteModelProfile(
 export async function readMemoryWrite(
   attachment: RuntimeAttachmentLike,
   requestId: string,
+  /** A receipt belongs to the user that submitted it; omit for `local`. */
+  userId?: string,
 ): Promise<MemoryWriteReceipt | null> {
   try {
     const response = await axios.get<MemoryWriteReceipt>(
       `${baseUrlOf(attachment)}/api/v2/memory-writes/${encodeURIComponent(requestId)}`,
       {
+        ...(userId === undefined || userId === "local"
+          ? {}
+          : { params: { user_id: userId } }),
         headers: { Authorization: `Bearer ${attachment.apiToken}` },
         timeout: 10_000,
         proxy: false,

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

@@ -6,9 +6,10 @@ const WRITE_PATHS = [
 ] as const;
 /** `POST /api/v2/memories` adds one memory (the app's 添加记忆). */
 const MEMORY_ADD_PATH = "/api/v2/memories";
-/** One SDK memory; delete names its namespace in the query string. */
+/** One SDK memory; delete names its namespace, and a non-default user, in
+ * the query string. */
 const SDK_MEMORY_PATH =
-  /^\/api\/v2\/memories\/[A-Za-z0-9][\w.-]{0,127}(?:\?kind=(?:chat|experience|fact)(?:&variant=(?:working|coding))?)?$/;
+  /^\/api\/v2\/memories\/[A-Za-z0-9][\w.-]{0,127}(?:\?(?:kind=(?:chat|experience|fact)(?:&variant=(?:working|coding))?(?:&user_id=[A-Za-z0-9._-]{1,64})?|user_id=[A-Za-z0-9._-]{1,64}))?$/;
 const MODEL_PROBE_PATH =
   /^\/api\/v1\/model-profiles\/[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}\/probe$/;
 const MODEL_PROFILE_PATH =
@@ -25,12 +26,34 @@ const SOURCE_IMPORT_JOB_PATH = "/api/v1/import-jobs";
 const IMPORT_JOB_ACTION_PATH =
   /^\/api\/v1\/import-jobs\/[A-Za-z0-9][\w.-]{0,127}\/(?:pause|resume|cancel)$/;
 const GRAPH_WIDTH_PATH = "/api/v1/graph-width";
+/** `memhub evolve` starts a run; `memhub settings mode <m> --yes` sets the mode. */
+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 {
@@ -96,7 +119,10 @@ export function createCoreOperations(attachment: {
         !SOURCE_AUTHORIZE_PATH.test(path) &&
         !SOURCE_REVOKE_PATH.test(path) &&
         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");
@@ -114,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 {
@@ -131,7 +164,12 @@ export function createCoreOperations(attachment: {
       body: Record<string, unknown>,
       signal?: AbortSignal,
     ) {
-      if (!SDK_MEMORY_PATH.test(path) || path.includes("?")) {
+      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");
       }
       let response: { status: number; data: unknown };
@@ -193,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

@@ -110,9 +110,18 @@ export async function connectSourcesWithImport(
     sourceIds: readonly string[];
     confirmOverrides: boolean;
     requestId?: string;
+    /** Whose grant this is. Omitted for the default user (`local`). */
+    userId?: string;
+    /** An absolute root other than the source's candidate (a Hermes
+     * profile). Core reads its identity itself, so the source's candidate
+     * root id and revision are not sent for it. */
+    root?: string;
   },
 ): Promise<FlowDocument> {
   const sourceIds = input.sourceIds;
+  // A second user's grant is not a first run, and a custom root has no
+  // candidate the app showed: both are a plain connect.
+  const profile = input.root !== undefined || input.userId !== undefined;
   if (
     sourceIds.length < 1 ||
     sourceIds.length > 32 ||
@@ -134,9 +143,14 @@ export async function connectSourcesWithImport(
     return invalid("source_unavailable");
   }
   const items = selected.map(([candidate]) => candidate);
-  const needsOverride = items
-    .filter((item) => item.requires_override_confirmation)
-    .map((item) => item.source_id);
+  // A custom root is the caller's own choice, not the environment override
+  // the confirmation exists for.
+  const needsOverride =
+    input.root !== undefined
+      ? []
+      : items
+          .filter((item) => item.requires_override_confirmation)
+          .map((item) => item.source_id);
   if (needsOverride.length > 0 && !input.confirmOverrides) {
     return {
       schema_version: 1,
@@ -154,18 +168,22 @@ export async function connectSourcesWithImport(
     request = buildSourceImportRequest({
       sourceIds: [...sourceIds],
       sourceRoots: Object.fromEntries(
-        items.map((item) => [item.source_id, item.candidate_root_id]),
+        items.flatMap((item) =>
+          input.root === undefined
+            ? [[item.source_id, item.candidate_root_id]]
+            : [],
+        ),
       ),
       sourceCandidateRevisions: Object.fromEntries(
         items.flatMap((item) =>
-          item.candidate_revision === undefined
+          item.candidate_revision === undefined || input.root !== undefined
             ? []
             : [[item.source_id, item.candidate_revision]],
         ),
       ),
       confirmEnvironmentOverrides: needsOverride.length > 0,
       fullRescan: false,
-      onboarding: true,
+      onboarding: !profile,
       enableSync: true,
       requestId,
     });
@@ -175,7 +193,11 @@ export async function connectSourcesWithImport(
     }
     throw error;
   }
-  const result = await operations.post<unknown>(request.path, request.body);
+  const result = await operations.post<unknown>(request.path, {
+    ...request.body,
+    ...(input.userId === undefined ? {} : { user_id: input.userId }),
+    ...(input.root === undefined ? {} : { root: input.root }),
+  });
   if (result.state === "rejected") {
     return rejected(requestId, result.code);
   }
@@ -326,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/log-report.ts

@@ -107,7 +107,11 @@ export async function readLogReport(
   query: LogQuery,
 ): Promise<{
   events: DiagnosticEventV1[];
+  /** Lines that are not JSON: the only ones `memhub logs` calls damaged. */
   invalid_lines: number;
+  /** Whole JSON lines the reader leaves out, such as an older build's
+   * records. Nothing is wrong with them, so the text output says nothing. */
+  unrecognized_lines: number;
   failure?: "log_directory_unreadable";
 }> {
   // `readDiagnosticEvents` treats an unreadable logs path as "no events". That
@@ -119,6 +123,7 @@ export async function readLogReport(
     return {
       events: [],
       invalid_lines: 0,
+      unrecognized_lines: 0,
       failure: "log_directory_unreadable",
     };
   }
@@ -129,6 +134,7 @@ export async function readLogReport(
     return {
       events: [],
       invalid_lines: 0,
+      unrecognized_lines: 0,
       failure: "log_directory_unreadable",
     };
   }

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

@@ -0,0 +1,485 @@
+import { beforeEach, describe, expect, it, vi } from "vitest";
+
+import { run } from "./cli.js";
+import { parseFeaturesCommand } from "./memory-features-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,
+}));
+
+const DEFAULTS: Record<string, boolean> = {
+  graph_rerank: false,
+  same_series_timeline: false,
+  episode_recall: false,
+  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 | number> = {},
+  mode = "pro",
+  extra: Record<string, unknown> = {},
+) {
+  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;
+    const needsUltra = name === "graph_rerank";
+    const reason = !enabled
+      ? "disabled"
+      : needsUltra && mode !== "ultra"
+        ? "requires_ultra"
+        : null;
+    return {
+      name,
+      enabled,
+      configured: name in configured ? configured[name] : null,
+      default: fallback,
+      active: reason === null,
+      reason,
+      side: "read",
+      requires_mode: needsUltra ? "ultra" : "pro",
+      requires_feature: null,
+      cost: "none",
+      sdk_field: `recall.${name}`,
+      env: `MEMORY_${name.toUpperCase()}`,
+      description: name,
+    };
+  });
+  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(() => {
+  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/memory-features"
+      ? { status: 200, data: featuresState() }
+      : { status: 404, data: {} },
+  );
+});
+
+describe("memhub settings features", () => {
+  it("lists every feature with its value and whether it acts", async () => {
+    const result = await capturedRun(["settings", "features", "--json"]);
+    expect(result.code).toBe(0);
+    const json = JSON.parse(result.stdout);
+    expect(json.state).toBe("ok");
+    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");
+  });
+
+  it("prints the plan and changes nothing without --yes", async () => {
+    const result = await capturedRun([
+      "settings",
+      "features",
+      "set",
+      "graph_rerank=true",
+      "episode_recall=true",
+    ]);
+    expect(result.code).toBe(0);
+    expect(transport.put).not.toHaveBeenCalled();
+    expect(result.stdout).toContain(
+      "memhub settings features set graph_rerank=true episode_recall=true --yes",
+    );
+  });
+
+  it("sets features with --yes and reports the ones inactive in this mode", async () => {
+    transport.put.mockResolvedValue({
+      status: 200,
+      data: featuresState({ graph_rerank: true, episode_recall: true }, "pro", {
+        changed: ["graph_rerank", "episode_recall"],
+      }),
+    });
+    const result = await capturedRun([
+      "settings",
+      "features",
+      "set",
+      "graph_rerank=true",
+      "episode_recall=true",
+      "--yes",
+    ]);
+    expect(result.code).toBe(0);
+    expect(transport.put).toHaveBeenCalledWith(
+      "/api/v1/settings/memory-features",
+      { graph_rerank: true, episode_recall: true },
+      undefined,
+    );
+    expect(result.stdout).toContain("已更新：graph_rerank、episode_recall");
+    expect(result.stdout).toContain(
+      "graph_rerank：开（已设置，当前模式下不生效（需要 ultra））",
+    );
+  });
+
+  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,
+      data: featuresState({ few_shot: true }),
+    });
+    const result = await capturedRun([
+      "settings",
+      "features",
+      "set",
+      "few_shot=true",
+      "--yes",
+    ]);
+    expect(result.code).toBe(0);
+    expect(result.stdout).toContain("没有需要改动的设置");
+    expect(transport.put).not.toHaveBeenCalled();
+  });
+
+  it("resets the named features, or every set one, to the default", async () => {
+    transport.get.mockResolvedValue({
+      status: 200,
+      data: featuresState({ few_shot: true, intention: false }),
+    });
+    transport.put.mockResolvedValue({
+      status: 200,
+      data: featuresState({}, "pro", { changed: ["intention", "few_shot"] }),
+    });
+    expect(
+      (await capturedRun(["settings", "features", "reset", "few_shot"])).code,
+    ).toBe(0);
+    expect(transport.put).toHaveBeenLastCalledWith(
+      "/api/v1/settings/memory-features",
+      { few_shot: null },
+      undefined,
+    );
+    const all = await capturedRun(["settings", "features", "reset", "--json"]);
+    expect(JSON.parse(all.stdout).state).toBe("committed");
+    expect(transport.put).toHaveBeenLastCalledWith(
+      "/api/v1/settings/memory-features",
+      { intention: null, few_shot: null },
+      undefined,
+    );
+  });
+
+  it("refuses unknown names and malformed values before the Runtime", async () => {
+    for (const bad of [
+      ["settings", "features", "set"],
+      ["settings", "features", "set", "local_rerank=true"],
+      ["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"],
+    ]) {
+      const result = await capturedRun(bad);
+      expect(result.code, bad.join(" ")).toBe(2);
+    }
+    expect(transport.put).not.toHaveBeenCalled();
+  });
+
+  it("surfaces a 422 from the Runtime as rejected", async () => {
+    transport.put.mockResolvedValue({
+      status: 422,
+      data: { detail: "invalid_request" },
+    });
+    const result = await capturedRun([
+      "settings",
+      "features",
+      "set",
+      "few_shot=true",
+      "--yes",
+      "--json",
+    ]);
+    expect(result.code).toBe(1);
+    expect(JSON.parse(result.stdout).state).toBe("rejected");
+  });
+
+  it("parses the forms the help shows", () => {
+    expect(parseFeaturesCommand([])).toEqual({ kind: "show" });
+    expect(parseFeaturesCommand(["set", "intention=false", "--yes"])).toEqual({
+      kind: "set",
+      values: { intention: false },
+      confirmed: true,
+    });
+    expect(parseFeaturesCommand(["reset"])).toEqual({
+      kind: "reset",
+      names: [],
+    });
+  });
+});
+
+describe("status pipeline features", () => {
+  it("shows the features that differ from the defaults", async () => {
+    const processing = {
+      pending: 0,
+      fresh_pending: 0,
+      backlog_pending: 0,
+      outside_window_pending: 0,
+      running: 0,
+      waiting_for_model: 0,
+      completed: 3,
+      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: {
+          episode_recall: true,
+          intention: false,
+          intention_dedup_threshold: 0.9,
+        },
+      },
+    };
+    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?.features).toEqual({
+      episode_recall: true,
+      intention: false,
+      intention_dedup_threshold: 0.9,
+    });
+    const text = renderStatusText(report, "MemHub");
+    expect(text).toContain(
+      "SDK 功能：episode_recall=开、intention=关、intention_dedup_threshold=0.9",
+    );
+  });
+});
+
+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-features-flow.ts

@@ -0,0 +1,363 @@
+/**
+ * `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 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`
+ * only returns features to their defaults and applies at once.
+ */
+
+import type { CoreReader } from "./core-client.js";
+import type { CorePutOperations } from "./core-operations.js";
+import { PRODUCT } from "./version.js";
+
+export const MEMORY_FEATURES = [
+  "graph_rerank",
+  "same_series_timeline",
+  "episode_recall",
+  "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:
+    "同系列时间线（同一系列的记忆按时间放在一起；需图谱重排）",
+  episode_recall:
+    "片段召回（补入同一片段的记忆并多通道打分；pro / ultra，需片段写入）",
+  session_episodes: "片段写入（同一会话提取的记忆归入同一片段）",
+  episode_summary: "片段摘要（片段结束时总结一次；每个片段一次模型调用）",
+  intention: "意图提取（随事实一起提取用户的计划与意图）",
+  intention_dedup:
+    "意图判重（检索时把同一天、相似度达到阈值的意图视为重复，只返回最早一条并删除其余；关闭则不判重、不删除）",
+  few_shot: "提取示例（在提取提示里附上示例；不加调用，输入更长）",
+};
+
+const REASON_TEXT: Record<string, string> = {
+  disabled: "未开启",
+  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: SettingValues;
+      confirmed: boolean;
+    }
+  | { 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[],
+): FeaturesCommand | null {
+  const rest = values.filter((value) => value !== "--json");
+  if (rest.length === 0) return { kind: "show" };
+  const [verb, ...tail] = rest;
+  const yes = tail.filter((value) => value === "--yes").length;
+  if (yes > 1) return null;
+  const positional = tail.filter((value) => value !== "--yes");
+  if (verb === "set") {
+    if (positional.length === 0) return null;
+    const parsed: SettingValues = {};
+    for (const item of positional) {
+      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(isSetting)) return null;
+    return { kind: "reset", names: positional as MemorySetting[] };
+  }
+  return null;
+}
+
+export interface FeatureState {
+  name: MemoryFeature;
+  enabled: boolean;
+  configured: boolean | null;
+  default: boolean;
+  active: boolean;
+  reason: string | null;
+  cost: string;
+  requires_mode: string;
+  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[];
+  /** Absent from a Runtime older than the intention dedup threshold. */
+  parameters?: ParameterState[];
+  non_default: SettingValues;
+  changed?: MemorySetting[];
+}
+
+function featuresState(value: unknown): FeaturesState | null {
+  if (!value || typeof value !== "object") return null;
+  const item = value as Record<string, unknown>;
+  if (
+    typeof item.mode !== "string" ||
+    !Array.isArray(item.features) ||
+    !item.non_default ||
+    typeof item.non_default !== "object"
+  ) {
+    return null;
+  }
+  for (const feature of item.features) {
+    if (
+      !feature ||
+      typeof feature !== "object" ||
+      typeof (feature as FeatureState).name !== "string" ||
+      typeof (feature as FeatureState).enabled !== "boolean" ||
+      typeof (feature as FeatureState).active !== "boolean"
+    ) {
+      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;
+}
+
+export type FeaturesDocument = {
+  schema_version: 1;
+  product: string;
+  command: "settings features";
+} & (
+  | { state: "ok"; features: FeaturesState }
+  | {
+      state: "preview";
+      features: FeaturesState;
+      target: SettingValues;
+      applied: false;
+      next_step: string;
+    }
+  | { state: "unchanged"; features: FeaturesState }
+  | { state: "committed"; features: FeaturesState; changed: MemorySetting[] }
+  | { state: "rejected" | "unknown" | "unavailable"; code: string }
+);
+
+const BASE = {
+  schema_version: 1 as const,
+  product: PRODUCT,
+  command: "settings features" as const,
+};
+
+const PATH = "/api/v1/settings/memory-features";
+
+export async function runFeaturesCommand(
+  command: FeaturesCommand,
+  reader: CoreReader,
+  operations: CorePutOperations,
+): Promise<FeaturesDocument> {
+  const read = await reader<unknown>(PATH);
+  if (read.state !== "ok") {
+    return { ...BASE, state: "unavailable", code: read.code };
+  }
+  const current = featuresState(read.data);
+  if (current === null) {
+    return { ...BASE, state: "unavailable", code: "response_invalid" };
+  }
+  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") {
+    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) !== value,
+    );
+    if (!differs) return { ...BASE, state: "unchanged", features: current };
+    if (!command.confirmed) {
+      const pairs = Object.entries(command.values)
+        .map(([name, value]) => `${name}=${value}`)
+        .join(" ");
+      return {
+        ...BASE,
+        state: "preview",
+        features: current,
+        target: command.values,
+        applied: false,
+        next_step: `${PRODUCT} settings features set ${pairs} --yes`,
+      };
+    }
+    body = { ...command.values };
+  } else {
+    const names =
+      command.names.length > 0
+        ? command.names
+        : [...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]));
+  }
+  const result = await operations.put<unknown>(PATH, body);
+  if (result.state !== "committed") {
+    return { ...BASE, state: result.state, code: result.code };
+  }
+  const changed = featuresState(result.data);
+  if (changed === null) {
+    return { ...BASE, state: "unknown", code: "response_invalid" };
+  }
+  return {
+    ...BASE,
+    state: "committed",
+    features: changed,
+    changed: changed.changed ?? [],
+  };
+}
+
+export function featuresExitCode(document: FeaturesDocument): number {
+  return ["ok", "preview", "unchanged", "committed"].includes(document.state)
+    ? 0
+    : 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 ? "开" : "关";
+  const origin = feature.configured === null ? "默认" : "已设置";
+  const activity =
+    feature.enabled && !feature.active && feature.reason
+      ? `，${REASON_TEXT[feature.reason] ?? feature.reason}`
+      : "";
+  return `${feature.name}：${value}（${origin}${activity}）— ${label}`;
+}
+
+export function renderFeaturesText(document: FeaturesDocument): string {
+  if ("code" in document) {
+    return `SDK 功能未能${document.state === "unavailable" ? "读取" : "修改"}：${document.code}\n`;
+  }
+  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，之后提取的记忆才会带片段。",
+  );
+  if (document.state === "unchanged") lines.push("没有需要改动的设置。");
+  if (document.state === "preview") {
+    lines.push("将设置：");
+    for (const [name, value] of Object.entries(document.target)) {
+      lines.push(
+        `- ${name} = ${typeof value === "number" ? value : value ? "开" : "关"}`,
+      );
+    }
+    lines.push(`未执行任何改动。确认后运行：${document.next_step}`);
+  }
+  if (document.state === "committed") {
+    lines.push(
+      document.changed.length > 0
+        ? `已更新：${document.changed.join("、")}。正在进行的写入按原设置完成，之后的写入和检索使用新设置。`
+        : "已保存，生效的值没有变化。",
+    );
+  }
+  return `${lines.join("\n")}\n`;
+}

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

@@ -0,0 +1,309 @@
+import { beforeEach, describe, expect, it, vi } from "vitest";
+
+import { run } from "./cli.js";
+import { modeEffects, parseSettingsCommand } from "./memory-mode-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,
+}));
+
+const RUN_ID = "11111111-2222-4333-8444-555555555555";
+
+function modeState(mode: string, configured = mode) {
+  return {
+    mode,
+    configured_mode: configured,
+    forced_by_env: false,
+    modes: ["lite", "pro", "ultra"],
+    graph_build: { state: "idle", users: {} },
+  };
+}
+
+function receipt(state: string, extra: Record<string, unknown> = {}) {
+  return {
+    run_id: RUN_ID,
+    user_id: "wife",
+    agent_id: "all-apps",
+    state,
+    trigger: "manual",
+    started_at: "2026-11-01T03:00:00Z",
+    rounds: state === "running" ? 0 : 2,
+    tasks_processed: state === "running" ? 0 : 5,
+    batch_failures: 0,
+    capped: false,
+    elapsed_ms: 10,
+    results: { schemas: ["never printed"] },
+    ...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/memory-mode"
+      ? { status: 200, data: modeState("pro") }
+      : { status: 404, data: {} },
+  );
+});
+
+describe("memhub settings mode", () => {
+  it("shows the current mode without changing it", async () => {
+    const result = await capturedRun(["settings", "mode", "--json"]);
+    expect(result.code).toBe(0);
+    expect(JSON.parse(result.stdout).mode.mode).toBe("pro");
+    expect(transport.put).not.toHaveBeenCalled();
+  });
+
+  it("prints the plan and changes nothing without --yes", async () => {
+    const result = await capturedRun(["settings", "mode", "lite"]);
+    expect(result.code).toBe(0);
+    expect(transport.put).not.toHaveBeenCalled();
+    expect(result.stdout).toContain("更高模式生成的记忆仍保存着");
+    expect(result.stdout).toContain("memhub settings mode lite --yes");
+    const json = JSON.parse(
+      (await capturedRun(["settings", "mode", "ultra", "--json"])).stdout,
+    );
+    expect(json.state).toBe("preview");
+    expect(json.applied).toBe(false);
+    expect(json.effects).toEqual(["existing_memories_added_to_graph"]);
+  });
+
+  it("changes the mode with --yes and reports what changed", async () => {
+    transport.put.mockResolvedValue({
+      status: 200,
+      data: {
+        ...modeState("lite"),
+        previous_mode: "pro",
+        effects: ["higher_mode_memories_hidden"],
+      },
+    });
+    const result = await capturedRun(["settings", "mode", "lite", "--yes"]);
+    expect(result.code).toBe(0);
+    expect(transport.put).toHaveBeenCalledWith(
+      "/api/v1/settings/memory-mode",
+      { mode: "lite" },
+      undefined,
+    );
+    expect(result.stdout).toContain("已切换");
+    expect(result.stdout).toContain("原始对话：全部保留");
+  });
+
+  it("does nothing for the mode already set, and refuses bad input", async () => {
+    const same = await capturedRun(["settings", "mode", "pro", "--yes"]);
+    expect(same.code).toBe(0);
+    expect(same.stdout).toContain("已经是这个模式");
+    expect(transport.put).not.toHaveBeenCalled();
+    for (const bad of [
+      ["settings"],
+      ["settings", "mode", "max"],
+      ["settings", "mode", "--yes"],
+      ["settings", "mode", "lite", "pro"],
+      ["settings", "theme", "dark"],
+    ]) {
+      expect((await capturedRun(bad)).code, bad.join(" ")).toBe(2);
+    }
+  });
+
+  it("plans the same effects Core reports", () => {
+    expect(modeEffects("lite", "pro")).toEqual([
+      "earlier_raw_not_extracted",
+      "lite_search_stops",
+    ]);
+    expect(modeEffects("ultra", "lite")).toEqual([
+      "higher_mode_memories_hidden",
+      "evolve_stopped",
+    ]);
+    expect(modeEffects("pro", "pro")).toEqual([]);
+    expect(parseSettingsCommand(["mode", "ultra", "--yes"])).toEqual({
+      kind: "set",
+      mode: "ultra",
+      confirmed: true,
+    });
+  });
+});
+
+describe("memhub evolve", () => {
+  it("starts a run for the named user and returns at once", async () => {
+    transport.post.mockResolvedValue({ status: 202, data: receipt("running") });
+    const result = await capturedRun([
+      "evolve",
+      "--user-id",
+      "wife",
+      "--agent-id",
+      "all-apps",
+      "--max-batches",
+      "3",
+      "--json",
+    ]);
+    expect(result.code).toBe(0);
+    expect(transport.post).toHaveBeenCalledWith(
+      "/api/v2/evolve",
+      { user_id: "wife", agent_id: "all-apps", max_batches: 3 },
+      undefined,
+    );
+    const document = JSON.parse(result.stdout);
+    expect(document.state).toBe("running");
+    expect(document.run.results).toBeUndefined();
+  });
+
+  it("follows the run with --wait until it ends", async () => {
+    transport.post.mockResolvedValue({ status: 202, data: receipt("running") });
+    const reads = [receipt("running"), receipt("succeeded")];
+    transport.get.mockImplementation(async (url: string) =>
+      url === `/api/v2/evolve/${RUN_ID}`
+        ? { status: 200, data: reads.shift() }
+        : { status: 404, data: {} },
+    );
+    const result = await capturedRun(["evolve", "--wait"], {
+      sleep: async () => undefined,
+    });
+    expect(result.code).toBe(0);
+    expect(transport.post).toHaveBeenCalledWith(
+      "/api/v2/evolve",
+      {},
+      undefined,
+    );
+    expect(result.stdout).toContain("进化完成");
+    expect(result.stdout).toContain("2 轮");
+  });
+
+  it("names the mode when Core refuses outside ultra", async () => {
+    transport.post.mockResolvedValue({
+      status: 409,
+      data: { detail: "memory_mode_not_ultra" },
+    });
+    const result = await capturedRun(["evolve"]);
+    expect(result.code).toBe(1);
+    expect(result.stdout).toContain("memhub settings mode ultra --yes");
+    expect((await capturedRun(["evolve", "--max-batches", "0"])).code).toBe(2);
+    expect((await capturedRun(["evolve", "--now"])).code).toBe(2);
+  });
+});
+
+describe("status pipeline", () => {
+  it("reports pipeline.mode and the last evolve from memory-processing", async () => {
+    const processing = {
+      pending: 0,
+      fresh_pending: 0,
+      backlog_pending: 0,
+      outside_window_pending: 0,
+      running: 0,
+      waiting_for_model: 0,
+      completed: 3,
+      failed: 0,
+      blocked_stages: [],
+      pipeline: {
+        mode: "ultra",
+        configured_mode: "ultra",
+        forced_by_env: false,
+        last_evolve_at: "2026-11-01T03:00:05+08:00",
+        graph_build: { state: "succeeded", users: {} },
+        evolve: {
+          mode: "ultra",
+          schedule: { enabled: true, time: "03:00" },
+          running: [],
+          users: {
+            local: {
+              last_run_at: "2026-11-01T03:00:05+08:00",
+              last_result: { state: "succeeded", tasks_processed: 4 },
+              last_error: null,
+            },
+          },
+        },
+      },
+    };
+    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?.mode).toBe("ultra");
+    expect(report.pipeline?.last_evolve_at).toBe("2026-11-01T03:00:05+08:00");
+    expect(report.pipeline?.evolve_users.local?.state).toBe("succeeded");
+    const text = renderStatusText(report, "MemHub");
+    expect(text).toContain("记忆模式：ultra");
+    expect(text).toContain("每日 03:00 自动进化");
+  });
+});
+
+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" },
+        controls,
+      ),
+      stdout,
+      stderr,
+    };
+  } finally {
+    stdoutSpy.mockRestore();
+    stderrSpy.mockRestore();
+  }
+}

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

@@ -0,0 +1,372 @@
+/**
+ * `memhub settings mode` and `memhub evolve`.
+ *
+ * The mode (lite / pro / ultra) decides what the SDK does with every
+ * conversation, and switching it migrates nothing: what one mode made is not
+ * shown by a lower one, and raw kept by lite is not extracted until it is
+ * imported again. So a change prints its plan first and needs `--yes`, like
+ * every other command whose effect a person cannot simply take back.
+ *
+ * `memhub evolve` starts System 2 (ultra only) and, with `--wait`, follows
+ * the run until it ends.
+ */
+
+import type { CoreReader } from "./core-client.js";
+import type { CoreOperations, CorePutOperations } from "./core-operations.js";
+import { PRODUCT } from "./version.js";
+
+export const MEMORY_MODES = ["lite", "pro", "ultra"] as const;
+export type MemoryMode = (typeof MEMORY_MODES)[number];
+
+export type ModeEffect =
+  | "earlier_raw_not_extracted"
+  | "higher_mode_memories_hidden"
+  | "existing_memories_added_to_graph"
+  | "evolve_stopped"
+  | "lite_search_stops"
+  | "graph_backfill_already_running";
+
+const MODE_SUMMARY: Record<MemoryMode, string> = {
+  lite: "lite：不调用模型，保留全部原始对话，只在原始对话里检索",
+  pro: "pro：模型从对话中提取记忆（System 1）",
+  ultra: "ultra：pro + 每晚自动进化（System 2，使用知识图谱）",
+};
+
+const EFFECT_TEXT: Record<ModeEffect, string> = {
+  earlier_raw_not_extracted:
+    "lite 下已处理完的对话不会再被提取；只有尚未处理的和之后的新对话会由模型整理成记忆，检索立即改为记忆检索",
+  higher_mode_memories_hidden:
+    "更高模式生成的记忆仍保存着，但在这个模式下不会显示",
+  existing_memories_added_to_graph:
+    "已有记忆会在后台加入知识图谱（每个用户一次）",
+  evolve_stopped: "每晚的自动进化（System 2）停止",
+  lite_search_stops: "lite 只在原始对话里的检索立即停止，改为检索记忆",
+  graph_backfill_already_running: "知识图谱的补建已在进行中",
+};
+
+/** The same rule Core applies (`memory_mode_effects`), for the plan. */
+export function modeEffects(
+  previous: MemoryMode,
+  next: MemoryMode,
+): ModeEffect[] {
+  if (previous === next) return [];
+  const rank: Record<MemoryMode, number> = { lite: 0, pro: 1, ultra: 2 };
+  const effects: ModeEffect[] = [];
+  if (previous === "lite") {
+    effects.push("earlier_raw_not_extracted", "lite_search_stops");
+  }
+  if (rank[next] < rank[previous]) effects.push("higher_mode_memories_hidden");
+  if (previous === "ultra") effects.push("evolve_stopped");
+  if (next === "ultra") effects.push("existing_memories_added_to_graph");
+  return effects;
+}
+
+export type ModeCommand =
+  | { kind: "show" }
+  | { kind: "set"; mode: MemoryMode; confirmed: boolean };
+
+/** `settings mode [lite|pro|ultra] [--yes]` after `settings`; null = usage. */
+export function parseSettingsCommand(
+  values: readonly string[],
+): ModeCommand | null {
+  const rest = values.filter((value) => value !== "--json");
+  if (rest[0] !== "mode") return null;
+  const tail = rest.slice(1);
+  const confirmed = tail.includes("--yes");
+  const positional = tail.filter((value) => value !== "--yes");
+  if (tail.filter((value) => value === "--yes").length > 1) return null;
+  if (positional.length === 0) return confirmed ? null : { kind: "show" };
+  if (positional.length !== 1) return null;
+  const mode = positional[0] as MemoryMode;
+  if (!(MEMORY_MODES as readonly string[]).includes(mode)) return null;
+  return { kind: "set", mode, confirmed };
+}
+
+export interface ModeState {
+  mode: MemoryMode;
+  configured_mode: MemoryMode;
+  forced_by_env: boolean;
+  graph_build?: { state?: string } | null;
+  previous_mode?: MemoryMode;
+  effects?: ModeEffect[];
+}
+
+function modeState(value: unknown): ModeState | null {
+  if (!value || typeof value !== "object") return null;
+  const item = value as Record<string, unknown>;
+  if (
+    !(MEMORY_MODES as readonly unknown[]).includes(item.mode) ||
+    !(MEMORY_MODES as readonly unknown[]).includes(item.configured_mode) ||
+    typeof item.forced_by_env !== "boolean"
+  ) {
+    return null;
+  }
+  return item as unknown as ModeState;
+}
+
+export type ModeDocument = {
+  schema_version: 1;
+  product: string;
+  command: "settings mode";
+} & (
+  | { state: "ok"; mode: ModeState }
+  | {
+      state: "preview";
+      mode: ModeState;
+      target: MemoryMode;
+      effects: ModeEffect[];
+      applied: false;
+      next_step: string;
+    }
+  | { state: "unchanged"; mode: ModeState }
+  | { state: "committed"; mode: ModeState; effects: ModeEffect[] }
+  | { state: "rejected" | "unknown" | "unavailable"; code: string }
+);
+
+const BASE = {
+  schema_version: 1 as const,
+  product: PRODUCT,
+  command: "settings mode" as const,
+};
+
+export async function runModeCommand(
+  command: ModeCommand,
+  reader: CoreReader,
+  operations: CorePutOperations,
+): Promise<ModeDocument> {
+  const read = await reader<unknown>("/api/v1/settings/memory-mode");
+  if (read.state !== "ok") {
+    return { ...BASE, state: "unavailable", code: read.code };
+  }
+  const current = modeState(read.data);
+  if (current === null) {
+    return { ...BASE, state: "unavailable", code: "response_invalid" };
+  }
+  if (command.kind === "show") return { ...BASE, state: "ok", mode: current };
+  if (current.configured_mode === command.mode) {
+    return { ...BASE, state: "unchanged", mode: current };
+  }
+  if (!command.confirmed) {
+    return {
+      ...BASE,
+      state: "preview",
+      mode: current,
+      target: command.mode,
+      effects: modeEffects(current.mode, command.mode),
+      applied: false,
+      next_step: `${PRODUCT} settings mode ${command.mode} --yes`,
+    };
+  }
+  const result = await operations.put<unknown>("/api/v1/settings/memory-mode", {
+    mode: command.mode,
+  });
+  if (result.state !== "committed") {
+    return { ...BASE, state: result.state, code: result.code };
+  }
+  const changed = modeState(result.data);
+  if (changed === null) {
+    return { ...BASE, state: "unknown", code: "response_invalid" };
+  }
+  return {
+    ...BASE,
+    state: "committed",
+    mode: changed,
+    effects: changed.effects ?? [],
+  };
+}
+
+export function modeExitCode(document: ModeDocument): number {
+  return ["ok", "preview", "unchanged", "committed"].includes(document.state)
+    ? 0
+    : 1;
+}
+
+export function renderModeText(document: ModeDocument): string {
+  if ("code" in document) {
+    return `记忆模式未能${document.state === "unavailable" ? "读取" : "修改"}：${document.code}\n`;
+  }
+  const mode = document.mode;
+  const lines = [`当前模式：${MODE_SUMMARY[mode.mode]}`];
+  if (mode.forced_by_env) {
+    lines.push(
+      `设置里是 ${mode.configured_mode}；环境变量 ONE_MEMORY_GRAPH_STORE 强制使用 ultra。`,
+    );
+  }
+  lines.push("原始对话：全部保留（任何模式都不删除）");
+  if (document.state === "unchanged") {
+    lines.push("已经是这个模式，未做改动。");
+  }
+  if (document.state === "preview") {
+    lines.push(`将切换到：${MODE_SUMMARY[document.target]}`);
+    for (const effect of document.effects)
+      lines.push(`- ${EFFECT_TEXT[effect]}`);
+    lines.push(`未执行任何改动。确认后运行：${document.next_step}`);
+  }
+  if (document.state === "committed") {
+    lines.push("已切换。");
+    for (const effect of document.effects)
+      lines.push(`- ${EFFECT_TEXT[effect]}`);
+  }
+  return `${lines.join("\n")}\n`;
+}
+
+export type EvolveCommand = {
+  agentId?: string;
+  maxBatches?: number;
+  wait: boolean;
+};
+
+/** `evolve [--agent-id <id>] [--max-batches <n>] [--wait]`; null = usage. */
+export function parseEvolveCommand(
+  values: readonly string[],
+): EvolveCommand | null {
+  const parsed: EvolveCommand = { wait: false };
+  const rest = values.filter((value) => value !== "--json");
+  for (let index = 0; index < rest.length; index += 1) {
+    const flag = rest[index];
+    if (flag === "--wait" && !parsed.wait) {
+      parsed.wait = true;
+    } else if (flag === "--agent-id" && parsed.agentId === undefined) {
+      const value = rest[index + 1];
+      if (!value || !/^[A-Za-z0-9._:-]{1,128}$/.test(value)) return null;
+      parsed.agentId = value;
+      index += 1;
+    } else if (flag === "--max-batches" && parsed.maxBatches === undefined) {
+      const value = Number(rest[index + 1]);
+      if (!Number.isInteger(value) || value < 1 || value > 1000) return null;
+      parsed.maxBatches = value;
+      index += 1;
+    } else {
+      return null;
+    }
+  }
+  return parsed;
+}
+
+export type EvolveDocument = {
+  schema_version: 1;
+  product: string;
+  command: "evolve";
+} & (
+  | { state: "running" | "succeeded" | "failed"; run: Record<string, unknown> }
+  | { state: "rejected" | "unknown" | "unavailable"; code: string }
+);
+
+const RUN_ID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/;
+
+function evolveRun(value: unknown): Record<string, unknown> | null {
+  if (!value || typeof value !== "object") return null;
+  const run = value as Record<string, unknown>;
+  if (
+    typeof run.run_id !== "string" ||
+    !RUN_ID.test(run.run_id) ||
+    !["running", "succeeded", "failed"].includes(String(run.state))
+  ) {
+    return null;
+  }
+  return run;
+}
+
+export async function runEvolveCommand(
+  command: EvolveCommand,
+  options: {
+    userId?: string;
+    reader: CoreReader;
+    operations: CoreOperations;
+    sleep?: (ms: number) => Promise<void>;
+    pollMs?: number;
+  },
+): Promise<EvolveDocument> {
+  const base = {
+    schema_version: 1 as const,
+    product: PRODUCT,
+    command: "evolve" as const,
+  };
+  const body: Record<string, unknown> = {};
+  if (options.userId !== undefined) body.user_id = options.userId;
+  if (command.agentId !== undefined) body.agent_id = command.agentId;
+  if (command.maxBatches !== undefined) body.max_batches = command.maxBatches;
+  const started = await options.operations.post<unknown>(
+    "/api/v2/evolve",
+    body,
+  );
+  if (started.state !== "committed") {
+    return { ...base, state: started.state, code: started.code };
+  }
+  let run = evolveRun(started.data);
+  if (run === null)
+    return { ...base, state: "unknown", code: "response_invalid" };
+  const sleep =
+    options.sleep ??
+    ((ms: number) => new Promise((done) => setTimeout(done, ms)));
+  while (command.wait && run.state === "running") {
+    await sleep(options.pollMs ?? 2_000);
+    const read = await options.reader<unknown>(
+      `/api/v2/evolve/${run.run_id}`,
+      options.userId === undefined ? {} : { user_id: options.userId },
+    );
+    if (read.state !== "ok") {
+      return { ...base, state: "unavailable", code: read.code };
+    }
+    const next = evolveRun(read.data);
+    if (next === null)
+      return { ...base, state: "unknown", code: "response_invalid" };
+    run = next;
+  }
+  return {
+    ...base,
+    state: run.state as "running" | "succeeded" | "failed",
+    run: projectRun(run),
+  };
+}
+
+/** Counts and codes; SDK result bodies stay in the Core receipt. */
+function projectRun(run: Record<string, unknown>): Record<string, unknown> {
+  const keep = [
+    "run_id",
+    "user_id",
+    "agent_id",
+    "state",
+    "trigger",
+    "started_at",
+    "finished_at",
+    "rounds",
+    "tasks_processed",
+    "batch_failures",
+    "cycle_status",
+    "should_continue",
+    "continuation_reason",
+    "remaining_clusters",
+    "remaining_actionable_clusters",
+    "remaining_fresh_facts",
+    "capped",
+    "elapsed_ms",
+    "error_code",
+    "failure_kind",
+  ];
+  return Object.fromEntries(
+    keep.filter((key) => key in run).map((key) => [key, run[key]]),
+  );
+}
+
+export function evolveExitCode(document: EvolveDocument): number {
+  return document.state === "running" || document.state === "succeeded" ? 0 : 1;
+}
+
+export function renderEvolveText(document: EvolveDocument): string {
+  if ("code" in document) {
+    return document.code === "memory_mode_not_ultra"
+      ? "进化只在 ultra 模式下可用。切换：memhub settings mode ultra --yes\n"
+      : `进化未能开始：${document.code}\n`;
+  }
+  const run = document.run;
+  if (document.state === "running") {
+    return `进化已开始（${run.run_id}），在后台运行；加 --wait 等待结果。\n`;
+  }
+  if (document.state === "failed") {
+    return `进化失败（${run.run_id}）：${String(run.error_code ?? "unknown")}\n`;
+  }
+  return `进化完成（${run.run_id}）：${run.rounds} 轮，处理 ${run.tasks_processed} 项${
+    run.cycle_status ? `，周期 ${run.cycle_status}` : ""
+  }${run.capped ? "，已到轮数上限，可再次运行继续" : ""}\n`;
+}

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

@@ -14,6 +14,25 @@ import { type CoreReader, RESERVED_MEMORY_SEGMENTS } from "./core-client.js";
 import type { CoreOperations } from "./core-operations.js";
 import { PRODUCT } from "./version.js";
 
+/** A MemHub user id, the same shape Core accepts. `local` is the default. */
+const USER_ID = /^[A-Za-z0-9._-]{1,64}$/;
+export const DEFAULT_USER_ID = "local";
+
+export function isUserId(value: string): boolean {
+  return USER_ID.test(value);
+}
+
+/**
+ * The `user_id` to send, or nothing. The default user is never named on the
+ * wire, so a request without `--user-id` stays exactly what it was before
+ * multi-user support and still works against an older Core.
+ */
+export function userIdParameters(userId?: string): { user_id?: string } {
+  return userId === undefined || userId === DEFAULT_USER_ID
+    ? {}
+    : { user_id: userId };
+}
+
 /** Output budget: a long memory is shortened visibly, never dropped silently. */
 const CONTENT_BUDGET = 240;
 
@@ -101,10 +120,12 @@ export interface MemoryDetailDocument {
 export async function readMemoryPage(
   reader: CoreReader,
   query: MemoryQuery,
+  userId?: string,
 ): Promise<MemoryPageDocument> {
   const parameters: Record<string, string | number> = {
     offset: query.offset,
     limit: query.limit,
+    ...userIdParameters(userId),
   };
   if (query.status !== undefined) parameters.statuses = query.status;
   if (query.source !== undefined) parameters.source = query.source;
@@ -156,8 +177,12 @@ export async function readMemoryDetail(
   reader: CoreReader,
   memoryId: string,
   namespace: MemoryNamespace = {},
+  userId?: string,
 ): Promise<MemoryDetailDocument> {
-  const parameters = namespaceParameters(namespace);
+  const parameters = {
+    ...namespaceParameters(namespace),
+    ...userIdParameters(userId),
+  };
   const outcome = await reader<unknown>(
     `/api/v2/memories/${memoryId}`,
     Object.keys(parameters).length > 0 ? parameters : undefined,
@@ -223,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,
   };
 }
 
@@ -236,6 +265,7 @@ export async function addMemory(
   operations: CoreOperations,
   text: string,
   requestId: string = randomUUID(),
+  userId?: string,
 ): Promise<MemoryAddDocument> {
   const base = {
     schema_version: 2 as const,
@@ -259,7 +289,10 @@ export async function addMemory(
     }
     throw error;
   }
-  const result = await operations.post<unknown>(request.path, request.body);
+  const result = await operations.post<unknown>(request.path, {
+    ...request.body,
+    ...userIdParameters(userId),
+  });
   if (result.state !== "committed") {
     return { ...base, state: result.state, code: result.code };
   }
@@ -273,6 +306,7 @@ export async function addMemory(
 export async function readMemoryAddStatus(
   reader: CoreReader,
   requestId: string,
+  userId?: string,
 ): Promise<MemoryAddDocument> {
   const base = {
     schema_version: 2 as const,
@@ -283,7 +317,11 @@ export async function readMemoryAddStatus(
   if (!UUID.test(requestId)) {
     return { ...base, state: "invalid", code: "invalid_request_id" };
   }
-  const outcome = await reader<unknown>(memoryAddStatusPath(requestId));
+  const user = userIdParameters(userId);
+  const outcome =
+    user.user_id === undefined
+      ? await reader<unknown>(memoryAddStatusPath(requestId))
+      : await reader<unknown>(memoryAddStatusPath(requestId), user);
   if (outcome.state === "not_found") {
     return { ...base, state: "not_found", code: "memory_add_not_found" };
   }
@@ -313,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，不会重复添加。`
         : "",
@@ -338,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/profile-versions-cli.test.ts

@@ -0,0 +1,166 @@
+import { beforeEach, describe, expect, it, vi } from "vitest";
+
+import { run } from "./cli.js";
+
+const transport = vi.hoisted(() => ({
+  get: vi.fn(),
+  post: vi.fn(),
+  put: vi.fn(),
+  patch: vi.fn(),
+  delete: vi.fn(),
+}));
+vi.mock("axios", () => ({
+  default: {
+    create: vi.fn(() => transport),
+    get: vi.fn(),
+    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,
+}));
+
+const VERSIONS = {
+  user_id: "wife",
+  request_id: "r-versions",
+  elapsed_ms: 2,
+  chains: [
+    {
+      memory_id: "l0-head",
+      content: "The user's name is Fei.",
+      status: "active",
+      memory_at: null,
+      gmt_created: 1_790_000_100,
+      basic_info: { name: "Fei" },
+      versions: [
+        {
+          memory_id: "l0-head",
+          content: "The user's name is Fei.",
+          memory_at: null,
+          gmt_created: 1_790_000_100,
+          current: true,
+        },
+        {
+          memory_id: "l0-old",
+          content: "The user's name is 费天翔.",
+          memory_at: null,
+          gmt_created: 1_790_000_000,
+          current: false,
+        },
+      ],
+    },
+  ],
+};
+
+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/v2/user-profile/versions"
+      ? { status: 200, data: VERSIONS }
+      : { status: 404, data: {} },
+  );
+});
+
+describe("memhub profile --versions", () => {
+  it("reads the L0 version chain for the named user", async () => {
+    const result = await capturedRun([
+      "profile",
+      "--versions",
+      "--user-id",
+      "wife",
+      "--json",
+    ]);
+    expect(result.code).toBe(0);
+    expect(transport.get).toHaveBeenCalledWith(
+      "/api/v2/user-profile/versions",
+      { params: { user_id: "wife" } },
+    );
+    const document = JSON.parse(result.stdout);
+    expect(document.state).toBe("ok");
+    expect(document.chains[0].versions).toHaveLength(2);
+  });
+
+  it("marks the current version in text and names no user for local", async () => {
+    const result = await capturedRun(["profile", "--versions"]);
+    expect(result.code).toBe(0);
+    const [url, config] = transport.get.mock.calls[0] ?? [];
+    expect(url).toBe("/api/v2/user-profile/versions");
+    expect(config?.params?.user_id).toBeUndefined();
+    expect(result.stdout).toContain("* l0-head");
+    expect(result.stdout).toContain("  l0-old");
+    expect(result.stdout).toContain("费天翔");
+  });
+
+  it("refuses an unknown flag and a repeated --versions", async () => {
+    expect((await capturedRun(["profile", "--version-chain"])).code).toBe(2);
+    expect(
+      (await capturedRun(["profile", "--versions", "--versions"])).code,
+    ).toBe(2);
+    expect(transport.get).not.toHaveBeenCalled();
+  });
+
+  it("reports a malformed answer as invalid", async () => {
+    transport.get.mockResolvedValue({ status: 200, data: { chains: "x" } });
+    const result = await capturedRun(["profile", "--versions", "--json"]);
+    expect(result.code).toBe(1);
+    expect(JSON.parse(result.stdout).code).toBe("response_invalid");
+  });
+});
+
+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/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/source-progress-report.ts

@@ -14,6 +14,11 @@ import {
   validateProcessing,
   validateSources,
 } from "./core-responses.js";
+import {
+  describePipeline,
+  type PipelineSummary,
+  pipelineLine,
+} from "./status-report.js";
 import { PRODUCT } from "./version.js";
 
 type ReadState =
@@ -38,6 +43,21 @@ export interface SourcesDocument {
   state: ReadState["state"];
   code?: string;
   sources: Array<Record<string, unknown>>;
+  /** Every grant of every user (`GET /api/v1/source-grants`). Absent when
+   * Core is too old to list them; `sources` is the default user's view. */
+  grants?: SourceGrant[];
+}
+
+/** One source grant. Only Hermes has grants for users other than `local`,
+ * one per Hermes profile root. */
+export interface SourceGrant {
+  user_id: string;
+  source_id: string;
+  root_label: string | null;
+  root_path: string | null;
+  authorized: boolean;
+  revoked_at: string | null;
+  sync_enabled: boolean;
 }
 
 export interface SyncDocument {
@@ -69,6 +89,8 @@ export interface ProgressDocument {
     summary_state: ReadState;
     summary: Record<string, unknown> | null;
   };
+  /** The SDK mode and last evolve per user; absent on an older Core. */
+  pipeline?: PipelineSummary | null;
 }
 
 export async function readSources(
@@ -86,14 +108,66 @@ export async function readSources(
       sources: [],
     };
   }
+  const grants = await readSourceGrants(reader);
   return {
     schema_version: SCHEMA_VERSION,
     product: PRODUCT,
     state: "ok",
-    sources: result.data.map(projectSource),
+    // `/api/v1/sources` is the default user's view of every source.
+    sources: result.data.map((source) => ({
+      ...projectSource(source),
+      user_id: "local",
+    })),
+    ...(grants === null ? {} : { grants }),
   };
 }
 
+/** The grants of every user, or null when Core cannot list them (an older
+ * Core answers 404): the source list is then shown as before. */
+async function readSourceGrants(
+  reader: CoreReader,
+): Promise<SourceGrant[] | null> {
+  let outcome: ReadOutcome<unknown>;
+  try {
+    outcome = await reader<unknown>("/api/v1/source-grants");
+  } catch {
+    return null;
+  }
+  if (outcome.state !== "ok") return null;
+  const value = outcome.data;
+  if (!value || typeof value !== "object" || Array.isArray(value)) return null;
+  const items = (value as { grants?: unknown }).grants;
+  if (!Array.isArray(items)) return null;
+  const grants: SourceGrant[] = [];
+  const text = (candidate: unknown): string | null =>
+    typeof candidate === "string" && candidate.length <= 4096
+      ? candidate
+      : null;
+  for (const item of items) {
+    if (!item || typeof item !== "object" || Array.isArray(item)) return null;
+    const grant = item as Record<string, unknown>;
+    if (
+      typeof grant.user_id !== "string" ||
+      !/^[A-Za-z0-9._-]{1,64}$/.test(grant.user_id) ||
+      typeof grant.source_id !== "string" ||
+      !/^[a-z0-9][a-z0-9-]{0,127}$/.test(grant.source_id) ||
+      typeof grant.authorized !== "boolean"
+    ) {
+      return null;
+    }
+    grants.push({
+      user_id: grant.user_id,
+      source_id: grant.source_id,
+      root_label: text(grant.root_label),
+      root_path: text(grant.root_path),
+      authorized: grant.authorized,
+      revoked_at: text(grant.revoked_at),
+      sync_enabled: grant.sync_enabled === true,
+    });
+  }
+  return grants;
+}
+
 export async function readSync(reader: CoreReader): Promise<SyncDocument> {
   const result = validated(
     await reader<unknown>("/api/v1/live-sync"),
@@ -216,6 +290,10 @@ export async function readProgress(
       summary:
         processing.state === "ok" ? projectProcessing(processing.data) : null,
     },
+    pipeline:
+      processingRead.state === "ok"
+        ? describePipeline(processingRead.data)
+        : null,
   };
 }
 
@@ -231,6 +309,22 @@ export function renderSourcesText(document: SourcesDocument): string {
     );
   }
   if (document.sources.length === 0) lines.push("（没有来源）");
+  // The list above is the default user's (`local`). Another user's grant,
+  // a Hermes profile, is listed with its user so it is not mistaken for it.
+  const others = (document.grants ?? []).filter(
+    (grant) => grant.user_id !== "local",
+  );
+  if (others.length > 0) {
+    lines.push("其他用户的连接：");
+    for (const grant of others) {
+      const name =
+        document.sources.find((source) => source.source_id === grant.source_id)
+          ?.display_name ?? grant.source_id;
+      lines.push(
+        `- ${name}（用户 ${grant.user_id}）：${grant.authorized ? "已连接" : grant.revoked_at ? "已撤销" : "未连接"}；处理${grant.sync_enabled ? "已开启" : "已冻结"}${grant.root_path ? `；目录 ${grant.root_path}` : ""}`,
+      );
+    }
+  }
   lines.push("");
   return lines.join("\n");
 }
@@ -270,6 +364,18 @@ export function renderProgressText(document: ProgressDocument): string {
       ? `记忆整理：待处理 ${document.generation.summary.pending} · 进行中 ${document.generation.summary.running} · 等待模型 ${document.generation.summary.waiting_for_model} · 失败 ${document.generation.summary.failed}`
       : "记忆整理：暂时无法读取",
   );
+  if (document.pipeline) {
+    lines.push(`记忆模式：${pipelineLine(document.pipeline)}`);
+    for (const [userId, user] of Object.entries(
+      document.pipeline.evolve_users,
+    )) {
+      lines.push(
+        `  进化 ${userId}：${user.last_run_at ?? "尚未进化"}${
+          user.last_error ? `（失败：${user.last_error}）` : ""
+        }`,
+      );
+    }
+  }
   if (document.imports.output_truncated) {
     lines.push("这里只显示汇总；完整记录请使用 --json。");
   }

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

@@ -179,12 +179,72 @@ describe("CLI-07/10 source and synchronization reads", () => {
       sync_enabled: true,
       sync_completeness: "additions_only",
     });
-    expect(requestedPaths()).toEqual(["/api/v1/sources"]);
+    // The grants list answers 404 here, as an older Core does: the source
+    // list is shown as before, every row the default user's.
+    expect(report.sources[0].user_id).toBe("local");
+    expect(report.grants).toBeUndefined();
+    expect(requestedPaths()).toEqual([
+      "/api/v1/sources",
+      "/api/v1/source-grants",
+    ]);
     expect(requestedPaths().some((path) => path.includes("detect"))).toBe(
       false,
     );
   });
 
+  it("shows every user's grant, a Hermes profile with its user", async () => {
+    const grants = {
+      schema_version: 1,
+      grants: [
+        {
+          user_id: "local",
+          source_id: "codex",
+          root_label: ".codex",
+          root_path: "/home/synthetic/.codex",
+          authorized: true,
+          revoked_at: null,
+          sync_enabled: true,
+        },
+        {
+          user_id: "wife",
+          source_id: "hermes",
+          root_label: "wife",
+          root_path: "/home/synthetic/.hermes/profiles/wife",
+          authorized: true,
+          revoked_at: null,
+          sync_enabled: true,
+        },
+      ],
+    };
+    transport.get.mockImplementation(async (url: string) =>
+      url === "/api/v1/source-grants"
+        ? { status: 200, data: grants }
+        : (RESPONSES.get(url) ?? { status: 404, data: {} }),
+    );
+    let streams = captureStreams();
+    try {
+      expect(await run(["sources", "list", "--json"], {})).toBe(0);
+    } finally {
+      streams.restore();
+    }
+    const report = JSON.parse(streams.stdout());
+    expect(report.grants).toEqual(grants.grants);
+    expect(report.sources[0]).toMatchObject({
+      source_id: "codex",
+      user_id: "local",
+    });
+    streams = captureStreams();
+    try {
+      expect(await run(["sources", "list"], {})).toBe(0);
+    } finally {
+      streams.restore();
+    }
+    expect(streams.stdout()).toContain("其他用户的连接：");
+    expect(streams.stdout()).toContain(
+      "hermes（用户 wife）：已连接；处理已开启；目录 /home/synthetic/.hermes/profiles/wife",
+    );
+  });
+
   it("keeps degraded synchronization distinct and prints its error code", async () => {
     const streams = captureStreams();
     try {
@@ -552,6 +612,7 @@ describe("CLI-19 progress and issue reads", () => {
       requestedPaths().every((path) =>
         [
           "/api/v1/sources",
+          "/api/v1/source-grants",
           "/api/v1/live-sync",
           "/api/v1/import-jobs",
           "/api/v1/memory-processing",

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 =
@@ -57,6 +61,9 @@ export interface StatusDocument {
     broker?: BackgroundHealth["broker"];
   };
   sections: Record<string, Section>;
+  /** R10: the SDK mode and System 2 state; null when the Runtime is not read
+   * or is older than the setting. */
+  pipeline?: PipelineSummary | null;
   summary: {
     state: "ok" | "partial";
     degraded: string[];
@@ -64,6 +71,108 @@ export interface StatusDocument {
   };
 }
 
+export interface PipelineSummary {
+  mode: "lite" | "pro" | "ultra";
+  configured_mode: "lite" | "pro" | "ultra";
+  forced_by_env: boolean;
+  last_evolve_at: string | null;
+  evolve_schedule: { enabled: boolean; time: string } | null;
+  evolve_running: number;
+  evolve_users: Record<
+    string,
+    {
+      last_run_at: string | null;
+      last_error: string | null;
+      state: string | null;
+    }
+  >;
+  graph_build: string | null;
+  /** SDK features (`memory_features`) whose value differs from the default. */
+  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"]);
+
+/** Projection of `pipeline` in `/api/v1/memory-processing`; null if absent or malformed. */
+export function describePipeline(value: unknown): PipelineSummary | null {
+  if (!value || typeof value !== "object") return null;
+  const pipeline = (value as { pipeline?: unknown }).pipeline;
+  if (!pipeline || typeof pipeline !== "object") return null;
+  const item = pipeline as Record<string, unknown>;
+  if (
+    !MODES.has(String(item.mode)) ||
+    !MODES.has(String(item.configured_mode))
+  ) {
+    return null;
+  }
+  const evolve =
+    item.evolve && typeof item.evolve === "object"
+      ? (item.evolve as Record<string, unknown>)
+      : {};
+  const schedule =
+    evolve.schedule && typeof evolve.schedule === "object"
+      ? (evolve.schedule as Record<string, unknown>)
+      : null;
+  const users: PipelineSummary["evolve_users"] = {};
+  if (evolve.users && typeof evolve.users === "object") {
+    for (const [userId, raw] of Object.entries(
+      evolve.users as Record<string, unknown>,
+    )) {
+      const user =
+        raw && typeof raw === "object" ? (raw as Record<string, unknown>) : {};
+      const result =
+        user.last_result && typeof user.last_result === "object"
+          ? (user.last_result as Record<string, unknown>)
+          : {};
+      users[userId] = {
+        last_run_at:
+          typeof user.last_run_at === "string" ? user.last_run_at : null,
+        last_error:
+          typeof user.last_error === "string" ? user.last_error : null,
+        state: typeof result.state === "string" ? result.state : null,
+      };
+    }
+  }
+  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" || typeof value === "number")
+        features[name] = value;
+    }
+  }
+  const graph =
+    item.graph_build && typeof item.graph_build === "object"
+      ? (item.graph_build as Record<string, unknown>)
+      : {};
+  return {
+    mode: item.mode as PipelineSummary["mode"],
+    configured_mode: item.configured_mode as PipelineSummary["mode"],
+    forced_by_env: item.forced_by_env === true,
+    last_evolve_at:
+      typeof item.last_evolve_at === "string" ? item.last_evolve_at : null,
+    evolve_schedule:
+      schedule &&
+      typeof schedule.enabled === "boolean" &&
+      typeof schedule.time === "string"
+        ? { enabled: schedule.enabled, time: schedule.time }
+        : null,
+    evolve_running: Array.isArray(evolve.running) ? evolve.running.length : 0,
+    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",
+  };
+}
+
 const SECTION_NAMES = [
   "sources",
   "sync",
@@ -97,6 +206,7 @@ export async function composeStatusReport(options: {
   attachFailure?: string;
 }): Promise<StatusDocument> {
   const sections: Record<string, Section> = {};
+  let pipeline: PipelineSummary | null = null;
   if (options.reader === null) {
     const state: SectionState =
       options.attachFailure === undefined ? "not_checked" : "unavailable";
@@ -104,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);
@@ -118,12 +228,10 @@ export async function composeStatusReport(options: {
       validateProcessing,
       describeProcessing,
     );
+    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"] =
@@ -169,6 +277,7 @@ export async function composeStatusReport(options: {
     },
     bridge,
     sections,
+    pipeline,
     summary: {
       state:
         degraded.length === 0 && notChecked.length === 0 ? "ok" : "partial",
@@ -202,9 +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
@@ -220,6 +340,75 @@ 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)
+    parts.push("（ONE_MEMORY_GRAPH_STORE 强制 ultra）");
+  if (pipeline.mode === "ultra") {
+    const schedule = pipeline.evolve_schedule;
+    parts.push(
+      schedule?.enabled
+        ? `，每日 ${schedule.time} 自动进化`
+        : "，自动进化已关闭",
+    );
+    parts.push(
+      pipeline.last_evolve_at
+        ? `，上次进化 ${pipeline.last_evolve_at}`
+        : "，尚未进化",
+    );
+    if (pipeline.evolve_running > 0)
+      parts.push(`，进行中 ${pipeline.evolve_running}`);
+  }
+  const changed = Object.entries(pipeline.features);
+  if (changed.length > 0) {
+    parts.push(
+      `；SDK 功能：${changed
+        .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("");
+}
+
 function runtimeLine(report: StatusDocument): string {
   if (report.runtime.state !== "running") {
     return report.runtime.state === "stopped" ? "未运行" : "暂时无法确认";
@@ -229,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(" ");
 }
@@ -270,6 +480,7 @@ function fieldLabel(key: string): string {
     backlog_pending: "历史待处理",
     outside_window_pending: "稍后处理",
     waiting_for_model: "等待模型",
+    suspended: "来源已暂停",
     completed: "已完成",
     failed: "失败",
     blocked: "卡住",
@@ -279,6 +490,10 @@ function fieldLabel(key: string): string {
     profiles: "配置",
     active: "当前",
     memory_count: "记忆",
+    raw_count: "原始对话",
+    visible_count: "可见",
+    content_plane: "内容层",
+    effective_mode: "模式",
   };
   return labels[key] ?? key;
 }
@@ -350,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);
@@ -373,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

@@ -0,0 +1,468 @@
+import { mkdtemp, writeFile } from "node:fs/promises";
+import os, { tmpdir } from "node:os";
+import path from "node:path";
+import { beforeEach, describe, expect, it, vi } from "vitest";
+
+import { run } from "./cli.js";
+
+const transport = vi.hoisted(() => ({
+  get: vi.fn(),
+  post: vi.fn(),
+  put: vi.fn(),
+  patch: vi.fn(),
+  delete: vi.fn(),
+}));
+const direct = vi.hoisted(() => ({ get: vi.fn(), post: vi.fn() }));
+vi.mock("axios", () => ({
+  default: {
+    create: vi.fn(() => transport),
+    get: direct.get,
+    post: direct.post,
+    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,
+}));
+
+const REQUEST = "33333333-3333-4333-8333-333333333333";
+const HERMES = {
+  source_id: "hermes",
+  display_name: "Hermes",
+  storage_kinds: ["sqlite"],
+  available: true,
+  authorized: true,
+  detected: null,
+  root_label: ".hermes",
+  candidate_path: "~/.hermes",
+  candidate_kind: "default",
+  candidate_revision: 0,
+  candidate_root_id: "hermes-root-identity",
+  imported_messages: 0,
+  imported_conversations: 0,
+  capabilities: {
+    historical_import: "implemented",
+    incremental_import: "implemented",
+    live_sync: "implemented",
+    recall: "implemented",
+    installer: "not_implemented",
+    verification: "fixture_only",
+  },
+  sync_completeness: "additions_only",
+  location_state: "found",
+};
+const CODEX = {
+  ...HERMES,
+  source_id: "codex",
+  display_name: "Codex",
+  candidate_root_id: "codex-root-identity",
+};
+
+function addReceipt() {
+  return {
+    evidence_id: "44444444-4444-4444-8444-444444444444",
+    text: "Prefers tea",
+    scope: "all-apps",
+    created_at: "2026-10-27T00:00:00Z",
+    state: "pending",
+    task_id: null,
+    memory_ids: [],
+    error: null,
+  };
+}
+
+beforeEach(() => {
+  vi.clearAllMocks();
+  for (const method of [
+    ...Object.values(transport),
+    ...Object.values(direct),
+  ]) {
+    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) => {
+    if (url === "/api/v1/sources") {
+      return { status: 200, data: [HERMES, CODEX] };
+    }
+    if (url === "/api/v2/user-profile") {
+      return {
+        status: 200,
+        data: { request_id: "r-1", profile: null, elapsed_ms: 1 },
+      };
+    }
+    return { status: 404, data: {} };
+  });
+  transport.post.mockImplementation(
+    async (url: string, body: Record<string, unknown>) =>
+      url === "/api/v1/sources/connect"
+        ? {
+            status: 200,
+            data: {
+              request_id: body.request_id,
+              accepted_source_ids: ["hermes"],
+              failed_sources: {},
+              jobs: [],
+            },
+          }
+        : url === "/api/v2/memories"
+          ? { status: 201, data: addReceipt() }
+          : { status: 404, data: {} },
+  );
+  transport.put.mockResolvedValue({ status: 200, data: {} });
+  transport.delete.mockResolvedValue({ status: 204, data: "" });
+  direct.post.mockResolvedValue({
+    status: 202,
+    data: {
+      request_id: REQUEST,
+      state: "accepted",
+      created_at: "T1",
+      updated_at: "T1",
+    },
+  });
+  direct.get.mockResolvedValue({
+    data: {
+      request_id: REQUEST,
+      state: "accepted",
+      created_at: "T1",
+      updated_at: "T1",
+    },
+  });
+});
+
+describe("--user-id on the memory commands", () => {
+  it("passes the user as a query parameter to memory reads and deletes", async () => {
+    await capturedRun(["memories", "list", "--user-id", "wife", "--json"]);
+    expect(transport.get).toHaveBeenCalledWith("/api/v2/memory-library", {
+      params: { offset: 0, limit: 100, user_id: "wife" },
+    });
+    // Global: the flag may come before the subcommand too.
+    await capturedRun(["memories", "--user-id", "wife", "show", "m-1"]);
+    expect(transport.get).toHaveBeenCalledWith("/api/v2/memories/m-1", {
+      params: { user_id: "wife" },
+    });
+    await capturedRun(["memories", "add-status", REQUEST, "--user-id", "wife"]);
+    expect(transport.get).toHaveBeenCalledWith(
+      `/api/v2/memories/additions/${REQUEST}`,
+      { params: { user_id: "wife" } },
+    );
+    await capturedRun(["profile", "--user-id", "wife", "--json"]);
+    expect(transport.get).toHaveBeenCalledWith("/api/v2/user-profile", {
+      params: { user_id: "wife" },
+    });
+    await capturedRun([
+      "memories",
+      "delete",
+      "fact-1",
+      "--kind",
+      "fact",
+      "--yes",
+      "--user-id",
+      "wife",
+    ]);
+    expect(transport.delete).toHaveBeenCalledWith(
+      "/api/v2/memories/fact-1?kind=fact&user_id=wife",
+      undefined,
+    );
+    await capturedRun([
+      "memories",
+      "delete",
+      "m-1",
+      "--yes",
+      "--user-id",
+      "wife",
+    ]);
+    expect(transport.delete).toHaveBeenCalledWith(
+      "/api/v2/memories/m-1?user_id=wife",
+      undefined,
+    );
+    await capturedRun(["write", "status", REQUEST, "--user-id", "wife"]);
+    expect(direct.get.mock.calls[0][0]).toBe(
+      `http://127.0.0.1:8765/api/v2/memory-writes/${REQUEST}`,
+    );
+    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");
+    expect(transport.post.mock.calls[0][1]).toMatchObject({
+      text: "Prefers tea",
+      scope: "all-apps",
+      user_id: "wife",
+    });
+    const directory = await mkdtemp(path.join(tmpdir(), "om-user-id-"));
+    const content = path.join(directory, "content.txt");
+    await writeFile(content, "Prefers green tea\n");
+    await capturedRun([
+      "memories",
+      "update",
+      "m-1",
+      "--content-file",
+      content,
+      "--user-id",
+      "wife",
+    ]);
+    expect(transport.put.mock.calls[0][0]).toBe("/api/v2/memories/m-1");
+    expect(transport.put.mock.calls[0][1]).toMatchObject({ user_id: "wife" });
+    await capturedRun(["recall", "tea", "--user-id", "wife", "--json"]);
+    const search = transport.post.mock.calls.find(
+      ([url]) => url === "/api/v2/context/search",
+    );
+    expect(search?.[1]).toMatchObject({ query: "tea", user_id: "wife" });
+    const messages = path.join(directory, "messages.json");
+    await writeFile(
+      messages,
+      JSON.stringify([{ role: "user", content: "I like tea" }]),
+    );
+    await capturedRun([
+      "write",
+      "submit",
+      "--messages-file",
+      messages,
+      "--session",
+      "s-1",
+      "--user-id",
+      "wife",
+    ]);
+    expect(direct.post.mock.calls[0][0]).toBe(
+      "http://127.0.0.1:8765/api/v2/memory-writes",
+    );
+    expect(direct.post.mock.calls[0][1]).toMatchObject({
+      session_id: "s-1",
+      user_id: "wife",
+    });
+  });
+
+  it("names no user by default or for --user-id local", async () => {
+    for (const extra of [[], ["--user-id", "local"]]) {
+      transport.get.mockClear();
+      transport.post.mockClear();
+      await capturedRun(["memories", "list", ...extra, "--json"]);
+      expect(transport.get).toHaveBeenCalledWith("/api/v2/memory-library", {
+        params: { offset: 0, limit: 100 },
+      });
+      await capturedRun(["profile", ...extra]);
+      expect(transport.get).toHaveBeenCalledWith(
+        "/api/v2/user-profile",
+        undefined,
+      );
+      await capturedRun(["memories", "add", "Prefers tea", ...extra]);
+      expect(transport.post.mock.calls[0][1]).not.toHaveProperty("user_id");
+      await capturedRun(["recall", "tea", ...extra, "--json"]);
+      const search = transport.post.mock.calls.find(
+        ([url]) => url === "/api/v2/context/search",
+      );
+      expect(search?.[1]).not.toHaveProperty("user_id");
+    }
+  });
+
+  it("refuses a malformed user id before contacting Core", async () => {
+    for (const value of ["bad:id", "", "x".repeat(65), "a b", "--json"]) {
+      const result = await capturedRun([
+        "memories",
+        "list",
+        "--user-id",
+        value,
+      ]);
+      expect(result.code).toBe(2);
+    }
+    expect(
+      (await capturedRun(["profile", "--user-id", "a", "--user-id", "b"])).code,
+    ).toBe(2);
+    expect((await capturedRun(["recall", "tea", "--user-id"])).code).toBe(2);
+    expect(transport.get).not.toHaveBeenCalled();
+    expect(transport.post).not.toHaveBeenCalled();
+  });
+});
+
+describe("sources connect for a Hermes profile", () => {
+  it("connects hermes for another user from its own root", async () => {
+    const result = await capturedRun([
+      "sources",
+      "connect",
+      "hermes",
+      "--user-id",
+      "wife",
+      "--root",
+      "~/.hermes/profiles/wife",
+      "--json",
+    ]);
+    expect(result.code).toBe(0);
+    expect(transport.post).toHaveBeenCalledTimes(1);
+    const [url, body] = transport.post.mock.calls[0];
+    expect(url).toBe("/api/v1/sources/connect");
+    expect(body).toMatchObject({
+      source_ids: ["hermes"],
+      // Core reads the custom root's identity itself.
+      source_roots: {},
+      source_candidate_revisions: {},
+      onboarding: false,
+      user_id: "wife",
+      root: path.join(os.homedir(), ".hermes/profiles/wife"),
+    });
+  });
+
+  it("keeps a plain connect unchanged and accepts --import with a profile", async () => {
+    await capturedRun(["sources", "connect", "hermes", "--import", "--json"]);
+    const plain = transport.post.mock.calls[0][1];
+    expect(plain).not.toHaveProperty("user_id");
+    expect(plain).not.toHaveProperty("root");
+    expect(plain).toMatchObject({
+      source_roots: { hermes: "hermes-root-identity" },
+      onboarding: true,
+    });
+    transport.post.mockClear();
+    const result = await capturedRun([
+      "sources",
+      "connect",
+      "hermes",
+      "--import",
+      "--user-id",
+      "wife",
+      "--root",
+      "/profiles/wife",
+      "--request-id",
+      REQUEST,
+      "--json",
+    ]);
+    expect(result.code).toBe(0);
+    expect(transport.post.mock.calls[0][1]).toMatchObject({
+      request_id: REQUEST,
+      user_id: "wife",
+      root: "/profiles/wife",
+    });
+  });
+
+  it("refuses --user-id and --root for any source but hermes", async () => {
+    for (const argv of [
+      ["sources", "connect", "codex", "--user-id", "wife"],
+      ["sources", "connect", "codex", "--root", "/somewhere", "--import"],
+      ["sources", "connect", "hermes", "codex", "--user-id", "wife"],
+      ["sources", "connect", "--all-detected", "--user-id", "wife"],
+      ["sources", "connect", "hermes", "--user-id", "bad:id"],
+    ]) {
+      const result = await capturedRun(argv);
+      expect(result.code).toBe(2);
+      expect(result.stderr).toContain("hermes");
+    }
+    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[]) {
+  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/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.8",
+    "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/capture_handoff.py

@@ -0,0 +1,133 @@
+"""The hook side of live capture: hand the turn to the running Core, nothing more.
+
+A host runs `one-memory capture <source>` as a short-lived process on every
+hook, often several at once. That process used to open the main database
+itself and write Evidence and the write queue from outside Core's single
+writer. It now never opens the database: it reads the hook's JSON, posts it to
+the running Core over loopback with the runtime token, and exits. Core applies
+every gate and stages the turn in-process (`live_capture.capture_hook`).
+
+Anything that goes wrong — Core not running, a stale receipt, a slow answer —
+drops the turn silently. There is no local fallback write: file-backed sources
+are read again by live sync from their persisted cursor once Core is back.
+"""
+
+import json
+import os
+from pathlib import Path
+from typing import TextIO
+
+CAPTURE_SOURCES = frozenset(
+    {
+        "workbuddy",
+        "claude-code",
+        "codex",
+        "cursor",
+        "pi",
+        "qwen-code",
+        "qwenwork",
+        "hermes",
+        "deepseek-harness",
+        "opencode",
+        "openclaw",
+    }
+)
+SDK_MIGRATION_CAPTURE_FENCE = ".sdk-migration-capture-fence.json"
+#: Core's in-process intake for a hook's payload; see `live_capture`.
+CAPTURE_ROUTE = "/api/v1/live-capture/{source_id}"
+#: Whole request, connect to answer. Pi and OpenCode wait for the hook
+#: synchronously (3 s, interpreter start included), so this stays well under.
+HANDOFF_TIMEOUT_SECONDS = 1.5
+#: A hook carries one turn, or one session's visible text at most.
+MAX_PAYLOAD_BYTES = 8 * 1024 * 1024
+
+
+def data_directory() -> Path:
+    from one_memory.config import load_settings
+
+    return load_settings().data_dir
+
+
+def capture_stdio(source_id: str, stdin: TextIO, output: TextIO) -> int:
+    """Host hooks must stay silent. A bad payload or an absent Core does not fail the turn."""
+
+    del output
+    if source_id not in CAPTURE_SOURCES:
+        return 2
+    try:
+        data_dir = data_directory()
+        if sdk_migration_capture_fenced(data_dir):
+            return 0
+        payload = json.loads(stdin.read() or "")
+    except Exception:
+        return 0
+    if not isinstance(payload, dict):
+        return 0
+    try:
+        hand_to_core(source_id, payload, data_dir)
+    except Exception:
+        return 0
+    return 0
+
+
+def hand_to_core(
+    source_id: str,
+    payload: dict[str, object],
+    data_dir: Path,
+    *,
+    timeout: float = HANDOFF_TIMEOUT_SECONDS,
+) -> bool:
+    """Post the payload to the Core named by this home's receipt. True when Core took it.
+
+    Only the receipt, the runtime token and a loopback socket are touched; the
+    main database is never opened from here.
+    """
+    from one_memory.runtime_client import core_endpoint
+
+    endpoint = core_endpoint(data_dir)
+    if endpoint is None:
+        return False
+    body = json.dumps(payload, ensure_ascii=False).encode("utf-8")
+    if len(body) > MAX_PAYLOAD_BYTES:
+        return False
+    from one_memory.http_client import create_client
+
+    with create_client(timeout=timeout) as client:
+        response = client.post(
+            f"http://{endpoint.host}:{endpoint.port}{CAPTURE_ROUTE.format(source_id=source_id)}",
+            content=body,
+            headers={
+                "Authorization": f"Bearer {endpoint.token}",
+                "Content-Type": "application/json",
+            },
+        )
+    return response.status_code == 202
+
+
+def sdk_migration_capture_fenced(data_dir: Path) -> bool:
+    """Ignore stale fences; a live migration or a failed one pauses hook writes.
+
+    A failed upgrade migration leaves the fence `frozen` (no pid): the home was
+    put back as it was before the upgrade and takes no writes until the next
+    migration attempt, which replaces the fence and lifts it on success.
+    """
+    marker = data_dir / SDK_MIGRATION_CAPTURE_FENCE
+    try:
+        document = json.loads(marker.read_text(encoding="utf-8"))
+        if isinstance(document, dict) and document.get("frozen") is True:
+            return True
+        pid = int(document["pid"])
+        if pid < 1:
+            raise ValueError("invalid migration fence pid")
+        os.kill(pid, 0)
+        return True
+    except FileNotFoundError:
+        return False
+    except ProcessLookupError:
+        marker.unlink(missing_ok=True)
+        return False
+    except PermissionError:
+        return True
+    except (KeyError, TypeError, ValueError, json.JSONDecodeError, OSError):
+        marker.unlink(missing_ok=True)
+        return False

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
@@ -119,7 +119,7 @@ def run(arguments: Sequence[str], *, output: TextIO | None = None) -> int:
     if command == "sdk-migration-status":
         return sdk_migration_status(options, stream)
     if command == "capture" and len(options) == 1:
-        from one_memory.live_capture import capture_stdio
+        from one_memory.capture_handoff import capture_stdio
 
         return capture_stdio(options[0], sys.stdin, stream)
     if command not in {"status", "doctor"} or options not in ([], ["--json"]):
@@ -584,6 +584,7 @@ def _sdk_migration_status(options: Sequence[str], stream: TextIO) -> int:
         }
     else:
         from one_memory.hy_runtime_config import HY_MEMORY_NAMESPACE
+        from one_memory.hy_sdk_runtime import builtin_retrieval_snapshot
         from one_memory.sdk_data_plane_migration import (
             MemoryAuthority,
             SdkDataPlaneMigrationStore,
@@ -595,19 +596,27 @@ def _sdk_migration_status(options: Sequence[str], stream: TextIO) -> int:
 
         authority = SdkDataPlaneMigrationStore(database_path).authority()
         if authority is MemoryAuthority.SDK:
-            profile = read_active_profile(database_path)
+            profile = read_active_profile(database_path) or builtin_retrieval_snapshot()
             leftovers = bool(
                 legacy_tables_present(database_path)
                 or abandoned_staging_present(
                     data_dir=settings.data_dir,
                     namespace=HY_MEMORY_NAMESPACE,
                 )
-                or (profile is not None and legacy_vector_collections(settings.data_dir, profile))
+                or legacy_vector_collections(settings.data_dir, profile)
             )
             state = "required" if leftovers else "not_required"
         else:
             state = "required"
         document = {"schema_version": 1, "authority": authority.value, "state": state}
+        from one_memory.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(
@@ -615,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")
@@ -695,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
 
@@ -739,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_access.py

@@ -11,14 +11,14 @@ from one_memory.context_models import ContextSearchRequest
 from one_memory.external_memory_access import ExternalMemoryAccess
 from one_memory.memory_server.store_binding import store_for
 
-#: The revoked-source query, per engine.
+#: The connected-source query, per engine.
 #:
 #: Identical text today because it uses no placeholders and reads by position,
 #: which both engines support. Kept as a named constant so that adding a
 #: parameter later forces the `?`/`%s` difference to be considered here rather
 #: than being introduced silently at the call site.
-REVOKED_SOURCES_SQL = (
-    "SELECT source_id FROM source_grants WHERE user_id='local' AND revoked_at IS NOT NULL"
+CONNECTED_SOURCES_SQL = (
+    "SELECT DISTINCT source_id FROM source_grants WHERE user_id='local' AND revoked_at IS NULL"
 )
 
 
@@ -49,16 +49,10 @@ def resolve_context_authority(
         scope for scope in access.scopes if scope == "all-apps" or scope.startswith("workspace:v1:")
     )
     memory_allowed = memory_requested and "om_recall" in access.tools and bool(memory_scopes)
-    declared_sources = frozenset(
-        scope.removeprefix("source:") for scope in access.scopes if scope.startswith("source:")
-    )
     raw_allowed = (
-        raw_requested
-        and "om_conversations" in access.tools
-        and "all-apps" in access.scopes
-        and bool(declared_sources)
+        raw_requested and "om_conversations" in access.tools and "all-apps" in access.scopes
     )
-    if explicit is not None and (not raw_allowed or not explicit <= declared_sources):
+    if explicit is not None and not raw_allowed:
         raise HTTPException(403, "external_context_scope_denied")
 
     raw_sources: frozenset[str] = frozenset()
@@ -70,10 +64,10 @@ def resolve_context_authority(
             # the same code runs on both engines without a branch per engine.
             if hasattr(db, "set_progress_handler"):
                 db.set_progress_handler(lambda: int(time.monotonic() >= deadline), 1000)
-            revoked = frozenset(str(row[0]) for row in db.execute(REVOKED_SOURCES_SQL))
+            connected = frozenset(str(row[0]) for row in db.execute(CONNECTED_SOURCES_SQL))
         if time.monotonic() >= deadline:
             raise TimeoutError
-        raw_sources = declared_sources - revoked
+        raw_sources = connected
         if explicit is not None:
             if not explicit <= raw_sources:
                 raise HTTPException(403, "external_context_scope_denied")

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

@@ -5,6 +5,9 @@ from typing import Annotated, Literal
 
 from pydantic import BaseModel, ConfigDict, Field, model_validator
 
+from one_memory.sdk_search_options import SdkSearchOptions
+from one_memory.user_scope import DEFAULT_USER_ID, UserId
+
 ContextKind = Literal["raw", "memory"]
 ContextSearchChannel = Literal["lexical", "semantic"]
 ContextSemanticStatus = Literal["not_searched", "completed", "failed", "timed_out"]
@@ -47,17 +50,26 @@ class ContextSearchRequest(BaseModel):
         return self
 
 
-class SdkContextSearchRequest(ContextSearchRequest):
+class SdkContextSearchRequest(ContextSearchRequest, SdkSearchOptions):
     """`POST /api/v2/context/search`: the three SDK recall lanes are set apart.
 
     `limit` is the normal lane's top-k and the cap on returned items;
     `schema_limit` and `intention_limit` are the SDK's schema (L6) and
     proactive intention (L7) lanes. A caller's values are passed through.
+
+    The `SdkSearchOptions` fields reach the memory lane's `client.search`;
+    the raw lane takes the floor and the source, session, agent and time
+    filters (never wider than the caller's raw authority). Absent, both
+    lanes make the call they always made.
     """
 
     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
 
 
 class ContextMessage(BaseModel):
@@ -113,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):
@@ -145,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

@@ -1,6 +1,7 @@
 """Authenticated SDK context search route, without generation or reindex side effects."""
 
 import asyncio
+import logging
 import time
 from collections.abc import Sequence
 from datetime import UTC, datetime
@@ -19,17 +20,84 @@ 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
 from one_memory.hy_sdk_types import (
     HySdkMemoryRecord,
+    parse_sdk_lane_search,
     parse_sdk_raw_search,
     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
 
 CALL_EVENT_RESPONSE_BUDGET_MS = 250
+SDK_CONTEXT_CONTENT_LIMIT = 20_000
+logger = logging.getLogger(__name__)
+
+#: Pass-through filters the raw lane honours. Scene, layers, reader and the
+#: schema/working floors describe memory lanes; the raw lane is always the
+#: chat store's L1 raw layer.
+_RAW_LANE_FILTERS = ("created_after", "session_ids", "agent_ids", "exclude_sources", "rerank")
+
+
+def raw_lane_sources(
+    allowed: Sequence[str] | frozenset[str] | None,
+    requested: Sequence[str] | None,
+) -> list[str] | None:
+    """The raw lane's source filter: the caller's, never wider than its authority.
+
+    `allowed` empty or None means every source (the call Core always made).
+    None back means nothing is left to search.
+    """
+    allowed_list = list(allowed or ())
+    if requested is None:
+        return allowed_list
+    chosen = [
+        source for source in dict.fromkeys(requested) if not allowed_list or source in allowed_list
+    ]
+    return chosen or None
+
+
+def raw_lane_overrides(value: SdkSearchFilters) -> dict[str, object]:
+    """The caller's raw-lane overrides: its floor and its row filters."""
+    overrides = value.filter_kwargs()
+    found = {name: overrides[name] for name in _RAW_LANE_FILTERS if name in overrides}
+    floor = value.lane_floor("raw")
+    if floor is not None:
+        found["min_score"] = floor
+    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:
+        return {"kind": hit.kind, "variant": hit.variant}
+    return {}
+
+
+def bounded_context_content(content: str) -> tuple[str, bool]:
+    """Fit SDK text into its wire contract before Pydantic validates it."""
+    if len(content) <= SDK_CONTEXT_CONTENT_LIMIT:
+        return content, False
+    return content[:SDK_CONTEXT_CONTENT_LIMIT], True
 
 
 def sdk_context_router(dependencies: Sequence[Depends]) -> APIRouter:
@@ -66,75 +134,146 @@ def sdk_context_router(dependencies: Sequence[Depends]) -> APIRouter:
             client = await client_handle.client()
         except Exception:
             raise HTTPException(503, "sdk_context_unavailable") from None
+        memory_mode = getattr(request.app.state, "memory_mode", None)
+        lite = callable(memory_mode) and memory_mode() == "lite"
 
         async def raw_lane() -> tuple[SdkRawContextItem, ...]:
             if "raw" not in value.kinds or not authority.raw_allowed:
                 return ()
+            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,
-                user_ids=["local"],
-                agent_ids=[],
-                include_sources=list(authority.raw_sources or ()),
-                limit=value.limit,
-                min_score=0.0,
-                schema_min_score=0.0,
-                schema_limit=0,
-                intention_limit=0,
-                scene="chat",
-                reader=HY_MEMORY_READER,
-                layers=["l1_raw"],
+                **{
+                    "user_ids": [value.user_id],
+                    "agent_ids": [],
+                    "include_sources": sources,
+                    "limit": value.limit,
+                    "min_score": 0.0,
+                    "schema_min_score": 0.0,
+                    "schema_limit": 0,
+                    "intention_limit": 0,
+                    "scene": "chat",
+                    "reader": HY_MEMORY_READER,
+                    "layers": ["l1_raw"],
+                    **raw_lane_statuses(lite=lite),
+                    **raw_lane_overrides(value),
+                },
             )
-            hits = parse_sdk_raw_search(raw)
-            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,
+            hits = tuple(
+                hit for hit in parse_sdk_raw_search(raw) if value.passes_floor("raw", 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:
+                    content, truncated = bounded_context_content(hit.content)
+                    primary.append(
+                        SdkRawContextItem(
+                            raw_id=hit.raw_id,
+                            content=content,
+                            source=hit.source,
+                            session_id=hit.session_id,
+                            memory_at=memory_at,
+                            score=hit.score,
+                            truncated=truncated,
+                        )
+                    )
+                    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: list[SdkRawContextItem] = []
+                for turn in turns_for_hit(turns, value.query):
+                    content, truncated = bounded_context_content(turn.content)
+                    shown.append(
+                        SdkRawContextItem(
+                            raw_id=hit.raw_id,
+                            turn_id=turn.turn_id,
+                            turn_index=turn.turn_index,
+                            turn_count=turn.turn_count,
+                            content=content,
+                            source=hit.source,
+                            session_id=hit.session_id,
+                            memory_at=memory_at,
+                            score=hit.score,
+                            truncated=truncated,
+                        )
+                    )
+                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, ...]:
-            if "memory" not in value.kinds or not authority.memory_allowed:
+            # lite extracts nothing: its search answers raw turns, which the
+            # raw lane already reads under the raw authority.
+            if "memory" not in value.kinds or not authority.memory_allowed or lite:
                 return ()
+            overrides = value.search_overrides()
             raw = await asyncio.to_thread(
                 client.search,
                 value.query,
-                user_ids=["local"],
-                agent_ids=[],
-                limit=value.limit,
-                min_score=sdk_relevance_floor(),
-                schema_min_score=sdk_relevance_floor(),
-                schema_limit=value.schema_limit,
-                intention_limit=value.intention_limit,
-                scene="normal",
-                reader=HY_MEMORY_READER,
+                **{
+                    "user_ids": [value.user_id],
+                    "agent_ids": [],
+                    "limit": value.limit,
+                    "min_score": sdk_relevance_floor(),
+                    "schema_min_score": sdk_relevance_floor(),
+                    "schema_limit": value.schema_limit,
+                    "intention_limit": value.intention_limit,
+                    "scene": "normal",
+                    "reader": HY_MEMORY_READER,
+                    **overrides,
+                },
+            )
+            hits = (
+                tuple(
+                    hit
+                    for hit in parse_sdk_lane_search(
+                        raw, error_code="hy_memory_search_shape_unknown"
+                    )
+                    if value.passes_floor(cast(SearchLane, hit.lane), hit.score)
+                )
+                if overrides
+                else parse_sdk_search(raw, error_code="hy_memory_search_shape_unknown")
             )
-            hits = parse_sdk_search(raw, error_code="hy_memory_search_shape_unknown")
             items: list[SdkMemoryContextItem] = []
             for hit in hits:
-                record = await asyncio.to_thread(client.get, hit.memory_id)
+                record = await asyncio.to_thread(client.get, hit.memory_id, **hit_namespace(hit))
                 memory = None if record is None else HySdkMemoryRecord.from_sdk(record)
-                if memory is None or memory.status != "active":
+                # `get` takes no user: a hit is kept only if it is the caller's.
+                if (
+                    memory is None
+                    or memory.status != "active"
+                    or not owns(memory.user_id, value.user_id)
+                ):
                     continue
+                content, truncated = bounded_context_content(
+                    hit.formatted_content
+                    if hit.sdk_formatted and hit.formatting_complete and hit.formatted_content
+                    else memory.content
+                )
                 items.append(
                     SdkMemoryContextItem(
                         memory_id=memory.memory_id,
-                        content=(
-                            hit.formatted_content
-                            if hit.sdk_formatted
-                            and hit.formatting_complete
-                            and hit.formatted_content
-                            else memory.content
-                        ),
+                        content=content,
                         layer=memory.layer,
                         status=memory.status,
                         source=memory.source,
@@ -144,6 +283,7 @@ def sdk_context_router(dependencies: Sequence[Depends]) -> APIRouter:
                             else None
                         ),
                         score=hit.score,
+                        truncated=truncated,
                     )
                 )
             return tuple(items)
@@ -185,13 +325,53 @@ 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
-        partial = isinstance(raw_items, Exception) or isinstance(memory_items, Exception)
+        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)
+        requested_lanes = {
+            "raw": raw_items,
+            "memory": memory_items,
+        }
+        failed_lanes = {
+            name: lane
+            for name, lane in requested_lanes.items()
+            if name in value.kinds and isinstance(lane, Exception)
+        }
+        for name, error in failed_lanes.items():
+            logger.warning(
+                "sdk_context_lane_failed lane=%s error_class=%s",
+                name,
+                type(error).__name__,
+            )
+        all_requested_failed = len(failed_lanes) == len(value.kinds)
+        partial = bool(failed_lanes)
         raw_candidates = (
             () if isinstance(raw_items, Exception) else cast(tuple[SdkContextItem, ...], raw_items)
         )
+        if access is not None and raw_candidates:
+            try:
+                current = await asyncio.to_thread(
+                    resolve_context_authority,
+                    value,
+                    access,
+                    database,
+                    deadline=started + value.timeout_ms / 1000,
+                )
+            except HTTPException:
+                raise
+            except Exception:
+                raise HTTPException(503, "context_authority_unavailable") from None
+            current_sources = current.raw_sources or frozenset()
+            raw_candidates = tuple(
+                item
+                for item in raw_candidates
+                if item.kind == "raw" and item.source in current_sources
+            )
         memory_candidates = (
             ()
             if isinstance(memory_items, Exception)
@@ -217,15 +397,25 @@ def sdk_context_router(dependencies: Sequence[Depends]) -> APIRouter:
             if len(content) > remaining:
                 item = item.model_copy(update={"content": content[:remaining], "truncated": True})
                 truncated = True
+            truncated = truncated or item.truncated
             selected.append(item)
             used += len(item.content)
         final = SdkContextSearchResponse(
             request_id=str(uuid4()),
-            state=("partial" if partial else "grounded" if selected else "empty"),
+            state=(
+                "unavailable"
+                if all_requested_failed
+                else "partial"
+                if partial
+                else "grounded"
+                if selected
+                else "empty"
+            ),
             items=tuple(selected),
             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)