fix(memhub): satisfy full lint gate

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

CHANGELOG.md

@@ -4,6 +4,13 @@ Hy Memory and MemHub are versioned and released independently.
 
 ## Unreleased
 
+- The SDK migration no longer fails its first run on a home with legacy
+  vectors: reattaching them left a Chroma instance open with its own settings,
+  and the readback that followed could not open the same store
+  ("An instance of Chroma already exists ... with different settings").
+- MemHub "添加记忆" (add a memory) no longer waits behind unprocessed history.
+  Notes are claimed ahead of the event-time window that keeps history strictly
+  old to new; they still run one at a time and in order within their session.
 - The SDK memory page now reads its list, count, source and time labels and
   graph from one page response for one source filter, so rows, totals and the
   map no longer disagree. Memories with no recorded source are shown and
@@ -61,6 +68,60 @@ Hy Memory and MemHub are versioned and released independently.
   `hy_node_permissions` proof table. Evidence, governed memories, model
   profiles, SDK stores, and source/host grants are preserved.
 
+## Hy Memory 2.0.6 — 2026-10-27
+
+- Published
+  [`hy-memory==2.0.6`](https://pypi.org/project/hy-memory/2.0.6/).
+- `search(..., rerank=False)` skips every reranking stage for that one
+  call (the local cross-encoder, the memory-graph rerank, and the BM25 rerank of
+  working/coding facts), so results come back in retrieval-score order. The
+  flag travels on the read request, so concurrent searches do not affect each
+  other. The default (`True`) keeps current behavior; `/api/v1/search` accepts
+  it too.
+- MMR diversity selection now runs only when the requested `limit` is
+  below 20 (`MMR_MAX_TOP_K`) and is skipped for larger limits, where its
+  quadratic token-overlap pass is slow and gains little. Previously it ran for
+  every limit. `MEMORY_HYBRID_V2_MMR_LAMBDA` still sets the weight.
+  Near-duplicate demotion follows the same gate: it compares each candidate
+  with every earlier non-duplicate, which is quadratic in a pool that grows
+  with `limit`, and large result pages should show similar items anyway.
+- `search(scene="all")` searches chat, working and coding at the same time
+  and merges them with Reciprocal Rank Fusion (k=60) over each scene's own
+  ranking, so no scene is crowded out by the other scenes' score scales. Each
+  result says which scene and kind it came from. A scene that fails or is turned
+  off is reported in `errors` and does not fail the search. Source filters apply
+  to all three.
+- `list_memories(scene="all")` lists chat, working and coding memories
+  together, newest update first, with `limit`/`offset` paging over the merged
+  order and `total` summing all three. `scene="coding"` and `"working"` now
+  honor `include_sources` / `exclude_sources`, and `total` counts only the
+  filtered memories.
+- `update()` and `delete()` now work on working/coding experiences and
+  facts, not just chat memories. They take the same optional `kind` / `variant`
+  as `get()`, and an ID found in more than one place raises
+  `AmbiguousMemoryIdError` instead of guessing. Updating an experience replaces
+  its solution and keeps its task, unless a new `task=` is also passed; updating
+  a fact replaces its statement. Deleting removes the stored row and its vectors.
+- `list_memories(scene="chat" | "coding" | "working")` lists one kind of
+  memory. `coding` and `working` list that scene's whole store, newest update
+  first (`workspace_id` still narrows it), and `total` is now the real count
+  rather than the page size. The new `memory_stats()` returns the count and the
+  latest created/updated time for each scene and their total, without reading
+  any memory text. Previously coding and working memories could not be listed
+  or counted without a workspace, so a library of 45 memories listed 22.
+- Reconcile keeps time order. Both reconcile prompts now state that only
+  `memory_at` decides which memory is newer, that an older memory must never
+  supersede or overwrite a newer one, and that an unknown time is not newer;
+  the Chinese prompt now lists `memory_at` among the new-memory fields. The
+  reconciler also enforces this in code: a SUPERSEDE or UPDATE aimed at a memory
+  with a later `memory_at` becomes an ADD, so the newer memory stays current.
+- The HTTP server returns 409 `ambiguous_memory_id` and 400 for a bad
+  `kind`/`variant` instead of 500, passes `kind`/`variant` (and `task` on PUT)
+  to get/update/delete, and no longer reads a PUT/DELETE query string as part
+  of the memory id.
+- `memory_stats()` reads working/coding times, which are stored as naive UTC,
+  as UTC rather than local time.
+
 ## Hy Memory 2.0.5 — 2026-10-22
 
 - Published

hy_memory/agent/prompts_zh.py

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

hy_memory/agent/reconciler.py

@@ -221,6 +221,8 @@ Rules:
 * merge losslessly
 * preserve all useful information
 * do NOT create duplicates
+* if the two disagree on a value, keep the value from the memory with the later
+  `memory_at`; never let an older memory overwrite a newer value
 
 ### Same occurrence vs. another occurrence
 
@@ -255,6 +257,7 @@ Use ONLY when:
 * the new memory contradicts an existing memory
 * both cannot be true at the same time
 * the old memory would now give the wrong current-state answer
+* the new memory's `memory_at` is the same as or LATER than the existing memory's `memory_at`
 
 Examples:
 
@@ -268,6 +271,8 @@ Do NOT use for:
 * compatible preferences
 * wording differences
 * semantic equivalence
+* a new memory whose `memory_at` is EARLIER than the existing memory's — it is an
+  older state and must never replace a newer one (see "Time order")
 
 Rules:
 
@@ -289,7 +294,8 @@ Rules:
 ### Folding several existing memories into one chain
 
 If TWO OR MORE existing memories track the SAME dimension and the new memory is
-the latest change on that dimension, you may fold them into a single evolution
+the latest change on that dimension — its `memory_at` is later than every folded
+memory's `memory_at` — you may fold them into a single evolution
 chain. Use `memory_ids` (an ordered list, OLDEST → NEWEST) instead of a single
 `memory_id`:
 
@@ -318,8 +324,7 @@ older memories' text into it; they remain queryable in the chain history.
 * Separate dated occurrences stay separate ADDs; use `same_series` only for the
   same subject and same concrete activity/event type.
 * Keep each memory focused on one coherent topic.
-* Do not invent chronology.
-* `memory_at: null` means unknown time.
+* Follow "Time order" below.
 * **NEVER merge or supersede across different subjects.** The subject is whoever
   the content is about: "The user ..." vs "John ..." vs "Mary ...". Memories about
   different people are independent facts even when the sentence is otherwise
@@ -332,6 +337,27 @@ older memories' text into it; they remain queryable in the chain history.
 
 ---
 
+# Time order
+
+Every memory, new or existing, has `memory_at`: when it happened. Memories are
+NOT always written in the order they happened — history can be imported late,
+and a memory can be added while older history is still being processed. A new
+memory can therefore be OLDER than an existing one.
+
+* Decide which memory is newer ONLY by `memory_at`. "New memories" means "being
+  written now", not "more recent".
+* An older memory must never replace a newer one: no SUPERSEDE of a newer
+  memory, and no UPDATE that overwrites a newer value with an older one.
+* If a new memory is older than an existing memory it conflicts with, keep the
+  existing memory as the current state. ADD the new one as a past state, worded
+  in the past with its time (for example "In 2023 the user lived in Shanghai"),
+  or output nothing if it adds no information.
+* `memory_at: null` means unknown time. Unknown is NOT newer: never SUPERSEDE a
+  memory that has a known `memory_at` with one whose `memory_at` is null.
+* Do not invent chronology.
+
+---
+
 # Optional: `related`
 
 On any op you MAY add a `related` array recording how the memory being written
@@ -441,6 +467,81 @@ def append_reconcile_structure_prompt(
     return prompt + RECONCILE_STRUCTURE_METADATA_PROMPT_EN
 
 
+def _as_aware(value: Any) -> Optional[datetime]:
+    """memory_at as a comparable aware datetime; None when unknown or unreadable."""
+    if isinstance(value, str) and value:
+        try:
+            value = datetime.fromisoformat(value)
+        except (TypeError, ValueError):
+            return None
+    if not isinstance(value, datetime):
+        return None
+    # Stored nodes rebuild memory_at from epoch seconds as naive local time
+    # (MemoryNode.from_dict), so a naive value is local, not UTC.
+    return value if value.tzinfo is not None else value.astimezone()
+
+
+def enforce_time_order(
+    ops: List["ReconcileOp"],
+    new_memory_at: Any,
+    existing: Dict[str, Any],
+) -> List["ReconcileOp"]:
+    """An older memory must never replace a newer one, whatever the model says.
+
+    Memories are not always written in the order they happened: history is
+    imported late, and a person can add a memory while older history is still
+    being processed. The prompt tells the model to compare `memory_at`; this
+    makes it hold. A SUPERSEDE or UPDATE aimed at an existing memory whose
+    `memory_at` is later than the memory being written is turned into an ADD,
+    so the newer memory stays the current state. Unknown times are not
+    compared. A content-less UPDATE (the legacy DELETE mapping) is dropped.
+    """
+    written_at = _as_aware(new_memory_at)
+    if written_at is None:
+        return ops
+    kept: List[ReconcileOp] = []
+    for op in ops:
+        if op.op not in ("SUPERSEDE", "UPDATE"):
+            kept.append(op)
+            continue
+        targets = list(op.memory_ids) if op.memory_ids else [op.memory_id]
+        newer = [
+            target for target in targets
+            if target and (node := existing.get(target)) is not None
+            and (target_at := _as_aware(getattr(node, "memory_at", None))) is not None
+            and target_at > written_at
+        ]
+        if not newer:
+            kept.append(op)
+            continue
+        logger.warning(
+            "[reconciler] %s blocked: memory_at %s is older than existing %s; "
+            "kept the newer memory",
+            op.op, written_at.isoformat(), ",".join(newer),
+        )
+        if not op.content:
+            continue
+        kept.append(ReconcileOp(
+            op="ADD",
+            content=op.content,
+            layer=op.layer,
+            owner=op.owner,
+            tags=list(op.tags),
+            tag_ners=list(op.tag_ners),
+            topic_paths=list(op.topic_paths),
+            event_facet=dict(op.event_facet),
+            topic_assignments=list(op.topic_assignments),
+            structure_references=list(op.structure_references),
+            topic_paths_provided=op.topic_paths_provided,
+            event_facet_provided=op.event_facet_provided,
+            topic_assignments_provided=op.topic_assignments_provided,
+            speculate=op.speculate,
+            related=list(op.related),
+            reason=f"time_order: older than {','.join(newer)}; {op.reason}"[:500],
+        ))
+    return kept
+
+
 def build_reconcile_prompt(
     *,
     new_memories: List[str],
@@ -1399,6 +1500,7 @@ class MemoryReconciler:
                 _tok_total += response.tokens_used
                 raw_response = response.content
                 ops = self._parse_ops(raw_response)
+                ops = enforce_time_order(ops, current_time, candidate_map)
                 ops = self._inherit_exact_input_structure(
                     ops, new_memories_with_meta,
                 )

hy_memory/coding/store.py

@@ -217,6 +217,21 @@ def _in_clause(column: str, values: Optional[List[str]]) -> Tuple[str, List[Any]
     return f"{column} IN ({placeholders})", list(values)
 
 
+def _source_where(
+    include_sources: Optional[List[str]], exclude_sources: Optional[List[str]],
+) -> Tuple[str, List[Any]]:
+    """Caller-source filter as SQL (``1`` when unfiltered); exclusion wins."""
+    clauses: List[str] = []
+    params: List[Any] = []
+    if include_sources:
+        clauses.append(f"source IN ({','.join('?' for _ in include_sources)})")
+        params.extend(include_sources)
+    if exclude_sources:
+        clauses.append(f"source NOT IN ({','.join('?' for _ in exclude_sources)})")
+        params.extend(exclude_sources)
+    return (" AND ".join(clauses) or "1"), params
+
+
 def _scope_matches(
     row_workspace_id: Optional[str],
     row_branch: Optional[str],
@@ -603,6 +618,86 @@ class CodingMemoryStore:
         logger.info(f"[coding-store] deleted experience_id={experience_id}")
         return True
 
+    async def edit_experience(
+        self,
+        experience_id: str,
+        *,
+        user_id: Optional[str] = None,
+        task: Optional[str] = None,
+        solution: Optional[str] = None,
+        search_keys: Optional[List[str]] = None,
+    ) -> Optional[CodingMemory]:
+        """调用方手动改一条经验（client.update 用）。返回改后的经验；不存在返回 None。
+
+        与 update() 的区别：update 是写入链路的覆盖式重写，带写授权校验（同
+        agent/session/workspace 才能改）；这里是用户对已有条目的直接编辑，只动
+        给定的字段，其余原样保留，因此不做授权校验。
+
+        向量行只嵌 task + search_keys（solution 不进向量），所以只改 solution 时
+        不重嵌、不碰向量库；改了 task / search_keys 才删旧 key 行重写。
+        updated_at 总是刷新。
+        """
+        prev = await self.get_by_id(experience_id, user_id=user_id)
+        if prev is None:
+            return None
+        updated = deepcopy(prev)
+        if task is not None:
+            updated.task = task
+        if solution is not None:
+            updated.solution = solution
+        if search_keys is not None:
+            updated.search_keys = list(search_keys)
+        updated.updated_at = datetime.utcnow()
+        await _run_in_pool(self._upsert_sql_sync, updated)
+        if updated.task != prev.task or updated.search_keys != prev.search_keys:
+            await self._delete_vec_keys_by_count(experience_id, 1 + len(prev.search_keys))
+            await self._upsert_vec_keys(updated)
+        logger.info(f"[coding-store] edited experience_id={experience_id}")
+        return updated
+
+    async def edit_fact(
+        self,
+        fact_id: str,
+        *,
+        statement: str,
+        user_id: Optional[str] = None,
+    ) -> Optional[WorkingFact]:
+        """调用方手动改一条事实的 statement。返回改后的事实；不存在返回 None。
+
+        statement 是事实层的检索文本，所以 active 事实会重嵌并覆盖它那一行向量
+        （node_id 就是 fact_id，upsert 即覆盖）。superseded 事实的向量行早已撤掉，
+        这里不把它加回去，否则会让过期结论重新占召回名额。
+        """
+        prev = await self.get_fact(fact_id, user_id=user_id)
+        if prev is None:
+            return None
+        updated = deepcopy(prev)
+        updated.statement = statement
+        await _run_in_pool(self._upsert_fact_sql_sync, updated)
+        if updated.status == "active":
+            await self._upsert_fact_vec(updated)
+        logger.info(f"[coding-store] edited fact_id={fact_id}")
+        return updated
+
+    async def delete_fact(self, fact_id: str, user_id: Optional[str] = None) -> bool:
+        """物理删除一条事实（SQLite 行 + 事实向量行），返回是否真有删到。
+
+        别处留下的引用（经验的 source_fact_ids、后继事实的 fact_link）不清：
+        召回侧本来就按存在性过滤死链（get_many / get_facts 查不到自然掉队）。
+        """
+        prev = await self.get_fact(fact_id, user_id=user_id)
+        if prev is None:
+            logger.info(f"[coding-store] delete fact skipped (not found): {fact_id}")
+            return False
+        if self._fact_vec is not None:
+            try:
+                await self._fact_vec.delete(fact_id)
+            except Exception as e:
+                logger.debug(f"[coding-store] delete fact vec {fact_id} ignored: {e}")
+        await _run_in_pool(self._delete_fact_sql_sync, fact_id, prev.user_id)
+        logger.info(f"[coding-store] deleted fact_id={fact_id}")
+        return True
+
     # ------------------------------------------------------------
     # 读取
     # ------------------------------------------------------------
@@ -687,29 +782,84 @@ class CodingMemoryStore:
         branch: Optional[str] = None,
         limit: int = 100,
         offset: int = 0,
+        include_sources: Optional[List[str]] = None,
+        exclude_sources: Optional[List[str]] = None,
     ) -> List["CodingMemory"]:
         """按 workspace_id（+可选 branch）纯过滤列出该 user 的完整 coding memory。
 
         作用域规则见 _scope_where（与 search 路径共用同一套）。无语义排序，按
-        updated_at 倒序（最近修改优先）。
+        updated_at 倒序（最近修改优先）。include_sources / exclude_sources 按
+        source 列在 SQL 里过滤（排除优先），所以 LIMIT/OFFSET 在过滤之后生效。
         """
         return await _run_in_pool(
-            self._list_by_workspace_sync, user_id, workspace_id, branch, limit, offset
+            self._list_by_workspace_sync, user_id, workspace_id, branch, limit, offset,
+            include_sources, exclude_sources,
         )
 
     def _list_by_workspace_sync(
         self, user_id: str, workspace_id: str, branch: Optional[str],
         limit: int, offset: int,
+        include_sources: Optional[List[str]] = None,
+        exclude_sources: Optional[List[str]] = None,
     ) -> List["CodingMemory"]:
         scope_sql, scope_params = _scope_where(workspace_id, branch)
+        source_sql, source_params = _source_where(include_sources, exclude_sources)
         with self._lock:
             assert self._conn is not None
             sql = (f"SELECT * FROM coding_memory_meta WHERE user_id = ? AND {scope_sql} "
-                   f"ORDER BY updated_at DESC LIMIT ? OFFSET ?")
-            params: List[Any] = [user_id] + scope_params + [limit, offset]
+                   f"AND {source_sql} "
+                   f"ORDER BY updated_at DESC, experience_id ASC LIMIT ? OFFSET ?")
+            params: List[Any] = ([user_id] + scope_params + source_params
+                                 + [limit, offset])
             cur = self._conn.execute(sql, params)
             return [_row_to_memory(r) for r in cur.fetchall()]
 
+    async def stats(
+        self,
+        user_id: str,
+        workspace_id: Optional[str] = None,
+        branch: Optional[str] = None,
+        include_sources: Optional[List[str]] = None,
+        exclude_sources: Optional[List[str]] = None,
+    ) -> Dict[str, Any]:
+        """经验数、最新创建/修改时间、active 事实数。纯聚合，不读正文。
+
+        作用域与 list_by_workspace 相同：workspace_id 为空表示该 user 全部；
+        来源过滤同样与 list_by_workspace 一致，count 因此恒等于分页可翻到的总数。
+        """
+        return await _run_in_pool(
+            self._stats_sync, user_id, workspace_id, branch,
+            include_sources, exclude_sources,
+        )
+
+    def _stats_sync(
+        self, user_id: str, workspace_id: Optional[str], branch: Optional[str],
+        include_sources: Optional[List[str]] = None,
+        exclude_sources: Optional[List[str]] = None,
+    ) -> Dict[str, Any]:
+        scope_sql, scope_params = _scope_where(workspace_id, branch)
+        source_sql, source_params = _source_where(include_sources, exclude_sources)
+        with self._lock:
+            assert self._conn is not None
+            row = self._conn.execute(
+                f"SELECT COUNT(*) AS n, MAX(created_at) AS created, "
+                f"MAX(updated_at) AS updated FROM coding_memory_meta "
+                f"WHERE user_id = ? AND {scope_sql} AND {source_sql}",
+                [user_id] + scope_params + source_params,
+            ).fetchone()
+            facts = self._conn.execute(
+                f"SELECT COUNT(*) AS n FROM working_fact "
+                f"WHERE user_id = ? AND status = 'active' AND {scope_sql} "
+                f"AND {source_sql}",
+                [user_id] + scope_params + source_params,
+            ).fetchone()
+        return {
+            "count": int(row["n"] or 0),
+            "latest_created_at": _parse_dt(row["created"]) if row["created"] else None,
+            "latest_updated_at": _parse_dt(row["updated"]) if row["updated"] else None,
+            "facts": int(facts["n"] or 0),
+        }
+
     # ------------------------------------------------------------
     # 召回
     # ------------------------------------------------------------
@@ -1088,6 +1238,14 @@ class CodingMemoryStore:
                 (experience_id, user_id),
             )
 
+    def _delete_fact_sql_sync(self, fact_id: str, user_id: str) -> None:
+        with self._lock:
+            assert self._conn is not None
+            self._conn.execute(
+                "DELETE FROM working_fact WHERE fact_id = ? AND user_id = ?",
+                (fact_id, user_id),
+            )
+
     def _get_by_id_sync(
         self, experience_id: str, user_id: Optional[str]
     ) -> Optional[CodingMemory]:

hy_memory/pipelines/_retrieval/diversity.py

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

hy_memory/pipelines/base.py

@@ -401,6 +401,11 @@ class ReadRequest:
     intention_limit: int = 0           # Intention 路的 topk，默认 0 关闭
 
 
+    # 重排开关（按次生效）。False 时跳过全部重排阶段：本地 cross-encoder
+    # (recall.local_rerank_enabled) 与记忆关系图重排 (_apply_graph_rerank)，
+    # 结果按召回分排序。走请求对象而非环境变量，并发请求互不影响。
+    rerank: bool = True
+
     # 时间过滤
     created_after: Optional[float] = None  # Unix timestamp (float)，只返回 gmt_created >= 此值的记忆
 

hy_memory/pipelines/reader_base.py

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

hy_memory/server.py

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

memhub/MEMORY.md

@@ -172,6 +172,20 @@ result = client.add_extracted(
 该入口仍走 SDK reconcile/持久化；MemHub 只做管理面门禁与可选
 `memory_id` 记录。
 
+应用的「添加记忆」、MCP `MemHub_write`（经 broker `POST /memories` 以本机可信身份转发）
+共用同一个本机 HTTP 合同，直接新增一条记忆：
+
+```text
+POST /api/v2/memories                         {request_id, text, scope: "all-apps"}
+GET  /api/v2/memories/additions/{request_id}  # 该次新增的状态
+```
+
+两者返回同一回执（`evidence_id`、`text`、`scope`、`created_at`、`state`、`task_id`、
+`memory_ids`、`error`）。同一 `request_id` 重放返回原回执；内容不同返回 409
+`memory_add_conflict`，未知 `request_id` 返回 404 `memory_add_not_found`。新增走持久
+写入队列的优先通道，最终调用 `add_extracted` + reconcile。带外部读取信封的请求
+一律拒绝（403 `external_endpoint_denied`）。
+
 ## Search：搜索记忆
 
 ```python

memhub/README.md

@@ -18,7 +18,7 @@ If you run into a problem, please open an Issue with the version, platform,repro
 
 ## 发行与平台合同
 
-源码当前固定使用公开 PyPI 正式版 `hy-memory==2.0.5`。MemHub 源码版本为 `1.0.5`
+源码当前固定使用公开 PyPI 正式版 `hy-memory==2.0.6`。MemHub 源码版本为 `1.0.5`
 （build 14），GitHub 仓库为
 [`Tencent-Hunyuan/Hy-Memory`](https://github.com/Tencent-Hunyuan/Hy-Memory)，npm 包名为
 `memhub-cli`。当前代码架构见
@@ -109,15 +109,16 @@ Node、Host Bridge 或模型。用户显式执行 `memhub install` 后，CLI 才
 Python Core 和运行所需的 Python 依赖位于 MemHub 受管 Runtime，不写入系统 Python。
 MemHub 的 SQLite 数据默认位于 `~/.one-memory`，不在 npm 包或 Runtime 版本目录中。
 `npm uninstall` 只移除 npm CLI；`memhub uninstall` 移除服务、受管 Runtime 和 CLI 链接，
-默认保留 Memory。只有独立的 `memhub delete-data` 在 Runtime 停止且二次确认精确路径后
-才会删除数据。
+默认保留 Memory。只有独立的 `memhub delete-data` 在 Runtime 停止、显式加 `--yes` 并用
+`--confirm <数据目录>` 再写一遍同一个目录后才会删除数据（不加参数只预览要删除的目录）。`memhub stop` 停止受管服务时也会关闭
+登录自动启动，再次 `memhub start` 会恢复。
 
 当前平台能力和安装边界以源码、CI 与发布说明为准。未完成真机验收的平台不会仅凭跨平台
 测试宣称可用。
 
 ## Hy Memory
 
-SDK 依赖固定为公开 PyPI 正式版 `hy-memory==2.0.5`。SDK 配置、权限边界及 search
+SDK 依赖固定为公开 PyPI 正式版 `hy-memory==2.0.6`。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.5",
+      "versionInfo": "2.0.6",
       "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.5
+## hy-memory 2.0.6
 
 License: Apache-2.0
 

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

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

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

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

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

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

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

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

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

@@ -1,8 +1,16 @@
-import { mkdtemp, readdir, readFile, realpath, rm } from "node:fs/promises";
+import {
+  mkdir,
+  mkdtemp,
+  readdir,
+  readFile,
+  realpath,
+  rm,
+} from "node:fs/promises";
 import { tmpdir } from "node:os";
 import path from "node:path";
 import {
   claimRuntimeServiceForApp,
+  clearSdkMigrationBlock,
   readRuntimeServiceOwner,
   recordSdkMigrationBlock,
   resolveRuntimeCliConfig,
@@ -922,6 +930,38 @@ describe("public One Memory CLI", () => {
       target_path: "/tmp/install/current/bin/one-memory",
     };
 
+    it("says the data was restored when a failed migration put it back", async () => {
+      vi.clearAllMocks();
+      runtimeMocks.planCliLink.mockResolvedValueOnce(presentCliLink);
+      runtimeMocks.runSdkMigration.mockResolvedValueOnce({
+        state: "deferred",
+        code: "sdk_migration_memory_unreadable",
+        dataRestored: true,
+      } as never);
+      const streams = captureStreams();
+      let code: number;
+      try {
+        code = await run(
+          upgradeArguments,
+          {},
+          { waitForRuntimeReady: async () => true },
+        );
+      } finally {
+        streams.restore();
+      }
+      expect(code!).toBe(1);
+      const failure = JSON.parse(streams.stderr());
+      expect(failure).toMatchObject({
+        code: "sdk_migration_memory_unreadable",
+        data_restored: true,
+        log_file: "/tmp/custom data/logs/sdk-migration.log",
+      });
+      expect(failure.message).toContain("记忆数据已恢复到升级前的状态。");
+      expect(failure.message).toContain(
+        "/tmp/custom data/logs/sdk-migration.log",
+      );
+    });
+
     it("migrates the home with the new Core before restarting the Runtime", async () => {
       vi.clearAllMocks();
       runtimeMocks.planCliLink.mockResolvedValueOnce(presentCliLink);
@@ -1971,16 +2011,11 @@ describe("stopped Runtime is exit 3, not a usage error", () => {
     ["path", "list", "--json"],
     ["adapter", "list", "--json"],
     ["task", "--id", "nope", "--json"],
-    [
-      "write",
-      "submit",
-      "--session",
-      "s",
-      "--messages-file",
-      "/tmp/messages.json",
-      "--json",
-    ],
-    ["backup", "create", "--target", "/tmp/x", "--yes", "--json"],
+    ["write", "status", "nope", "--json"],
+    ["backup", "create", "--target", "/tmp/x", "--json"],
+    ["scan-roots", "add", "--root", "/tmp/x", "--json"],
+    ["scan", "--source", "codex", "--json"],
+    ["onboarding", "reset", "--json"],
   ])("%s ... --json exits 3 with runtime_not_running", async (...argv) => {
     const streams = captureStreams();
     let code: number;
@@ -1990,7 +2025,9 @@ describe("stopped Runtime is exit 3, not a usage error", () => {
       streams.restore();
     }
     expect(code!).toBe(3);
-    const document = JSON.parse(streams.stderr());
+    // A result, not an error: on stdout like every other --json document.
+    expect(streams.stderr()).toBe("");
+    const document = JSON.parse(streams.stdout());
     expect(document).toMatchObject({
       code: "runtime_not_running",
       exit_code: 3,
@@ -1999,6 +2036,48 @@ describe("stopped Runtime is exit 3, not a usage error", () => {
     expect(document.status).not.toBe("usage_error");
   });
 
+  it("write submit validates its messages file before attaching, then exits 3", async () => {
+    const directory = await mkdtemp(path.join(tmpdir(), "memhub-write-"));
+    const file = path.join(directory, "messages.json");
+    await import("node:fs/promises").then(({ writeFile }) =>
+      writeFile(file, JSON.stringify([{ role: "user", content: "hi" }])),
+    );
+    const streams = captureStreams();
+    let missing: number;
+    let code: number;
+    try {
+      missing = await run(
+        [
+          "write",
+          "submit",
+          "--session",
+          "s",
+          "--messages-file",
+          path.join(directory, "absent.json"),
+          "--json",
+        ],
+        {},
+      );
+      code = await run(
+        [
+          "write",
+          "submit",
+          "--session",
+          "s",
+          "--messages-file",
+          file,
+          "--json",
+        ],
+        {},
+      );
+    } finally {
+      streams.restore();
+      await rm(directory, { recursive: true, force: true });
+    }
+    expect(missing!).toBe(2);
+    expect(code!).toBe(3);
+  });
+
   it.each(["pause", "resume"] as const)(
     "parses sync %s as the direct sync-set command",
     async (action) => {
@@ -2134,6 +2213,94 @@ describe("lifecycle commands report a migration block", () => {
     expect(output.value()).not.toContain("runtime_not_ready_within_budget");
   });
 
+  it("restart on a frozen home retries the migration in the foreground first", async () => {
+    const dataDir = await mkdtemp(path.join(tmpdir(), "memhub-frozen-"));
+    await recordSdkMigrationBlock(
+      dataDir,
+      "sdk_migration_memory_unreadable",
+      "desktop",
+      { frozen: { service_was_enabled: true }, data_restored: true },
+    );
+    const controls = {
+      ...blockedControls(),
+      migrateSdkData: vi.fn(async () => ({
+        state: "deferred" as const,
+        code: "sdk_migration_memory_unreadable",
+        dataRestored: true,
+      })),
+    };
+    const output = captureStdout();
+    let code: number;
+    try {
+      code = await run(
+        ["restart", "--json"],
+        { ONE_MEMORY_DATA_DIR: dataDir },
+        controls,
+      );
+    } finally {
+      output.restore();
+      await rm(dataDir, { recursive: true, force: true });
+    }
+    expect(code!).toBe(1);
+    expect(controls.migrateSdkData).toHaveBeenCalledWith(
+      expect.objectContaining({ dataDir, caller: "cli-restart" }),
+    );
+    // Still frozen: the service is not started to retry on its own.
+    expect(controls.restartManagedRuntime).not.toHaveBeenCalled();
+    expect(controls.ensureRuntime).not.toHaveBeenCalled();
+    expect(JSON.parse(output.value())).toMatchObject({
+      command: "restart",
+      state: "blocked",
+      code: "sdk_migration_memory_unreadable",
+      data_restored: true,
+    });
+  });
+
+  it("restart on a frozen home restarts the Runtime once the retry succeeds", async () => {
+    const dataDir = await mkdtemp(path.join(tmpdir(), "memhub-frozen-"));
+    await recordSdkMigrationBlock(
+      dataDir,
+      "sdk_migration_memory_unreadable",
+      "desktop",
+      { frozen: { service_was_enabled: false } },
+    );
+    const order: string[] = [];
+    const migrateSdkData = vi.fn(async () => {
+      order.push("migrate");
+      await clearSdkMigrationBlock(dataDir);
+      return { state: "cutover" as const };
+    });
+    const output = captureStreams();
+    let code: number;
+    try {
+      code = await run(
+        ["restart", "--json"],
+        { ONE_MEMORY_DATA_DIR: dataDir },
+        {
+          migrateSdkData,
+          waitForRuntimeReady: vi.fn(async () => true),
+          restartManagedRuntime: vi.fn(async () => {
+            order.push("restart");
+            return "restarted" as const;
+          }),
+          stopRuntime: vi.fn(async () => "stopped" as const),
+          ensureRuntime: vi.fn(async () => {
+            order.push("restart");
+            return { pid: 1 } as never;
+          }),
+        },
+      );
+    } finally {
+      output.restore();
+      await rm(dataDir, { recursive: true, force: true });
+    }
+    expect(code!).toBe(0);
+    expect(migrateSdkData).toHaveBeenCalledWith(
+      expect.objectContaining({ caller: "cli-restart" }),
+    );
+    expect(order).toEqual(["migrate", "restart"]);
+  });
+
   it("restart in text mode names the log file and GitHub issues", async () => {
     const dataDir = await blockedHome();
     const output = captureStdout();
@@ -2583,7 +2750,8 @@ describe("ui wires the Core session contract without token leakage", () => {
     } finally {
       output.restore();
     }
-    expect(code!).toBe(4);
+    // A stopped Runtime is exit 3, like every other command.
+    expect(code!).toBe(3);
     const document = JSON.parse(output.value());
     expect(document).toMatchObject({
       schema_version: 1,
@@ -2612,6 +2780,120 @@ describe("ui wires the Core session contract without token leakage", () => {
 // refuse while the Runtime owns the data dir, stop+call Core from a
 // maintenance process, and never report success from a malformed response.
 describe("backup restore drives the Core managed-restore contract", () => {
+  it("previews without --yes, exits 0 and starts nothing", async () => {
+    const maintenance = vi.fn();
+    const output = captureStdout();
+    let code: number;
+    try {
+      code = await run(
+        ["backup", "restore", "--source", "/tmp/x", "--json"],
+        {},
+        { runMaintenanceRestore: maintenance },
+      );
+    } finally {
+      output.restore();
+    }
+    expect(code!).toBe(0);
+    expect(maintenance).not.toHaveBeenCalled();
+    expect(JSON.parse(output.value())).toMatchObject({
+      command: "backup restore",
+      state: "preview",
+      target: "/tmp/x",
+      applied: false,
+      next_step: "memhub backup restore --source /tmp/x --yes --confirm /tmp/x",
+    });
+  });
+
+  it("deletes data only when --confirm repeats the data directory", async () => {
+    const home = await mkdtemp(path.join(tmpdir(), "memhub-delete-home-"));
+    const dataDir = path.join(home, ".one-memory");
+    await mkdir(path.join(dataDir, "logs"), { recursive: true });
+    const deleteData = async (...extra: string[]) => {
+      const output = captureStdout();
+      try {
+        const code = await run(
+          ["delete-data", "--data-dir", dataDir, ...extra, "--json"],
+          { HOME: home },
+        );
+        return { code, document: JSON.parse(output.value()) };
+      } finally {
+        output.restore();
+      }
+    };
+    try {
+      const refused = await deleteData("--yes");
+      expect(refused.code).toBe(4);
+      expect(refused.document).toMatchObject({
+        state: "blocked",
+        code: "data_deletion_confirmation_required",
+      });
+      expect(await readdir(dataDir)).toEqual(["logs"]);
+
+      const deleted = await deleteData("--yes", "--confirm", dataDir);
+      expect(deleted.code).toBe(0);
+      expect(await readdir(dataDir).catch(() => [])).toEqual([]);
+    } finally {
+      await rm(home, { recursive: true, force: true });
+    }
+  });
+
+  it("refuses --yes without repeating the backup path", async () => {
+    const maintenance = vi.fn();
+    const output = captureStdout();
+    let code: number;
+    try {
+      code = await run(
+        ["backup", "restore", "--source", "/tmp/x", "--yes", "--json"],
+        {},
+        { runMaintenanceRestore: maintenance },
+      );
+    } finally {
+      output.restore();
+    }
+    expect(code!).toBe(4);
+    expect(maintenance).not.toHaveBeenCalled();
+    expect(JSON.parse(output.value())).toMatchObject({
+      state: "rejected",
+      code: "backup_restore_confirmation_required",
+      next_step:
+        "恢复需要再写一遍备份路径：memhub backup restore --source /tmp/x --yes --confirm /tmp/x",
+    });
+  });
+
+  it("restores with --yes and the repeated backup path", async () => {
+    const maintenance = vi.fn(async () => ({
+      state: "restored" as const,
+      result: {
+        state: "restored" as const,
+        restoredBytes: 1,
+        previousBackupPath: "/tmp/pre.sqlite3",
+        sourceSchemaVersion: 34,
+      },
+    }));
+    const output = captureStdout();
+    let code: number;
+    try {
+      code = await run(
+        [
+          "backup",
+          "restore",
+          "--source",
+          "/tmp/x",
+          "--yes",
+          "--confirm",
+          "/tmp/x",
+          "--json",
+        ],
+        {},
+        { runMaintenanceRestore: maintenance },
+      );
+    } finally {
+      output.restore();
+    }
+    expect(code!).toBe(0);
+    expect(maintenance).toHaveBeenCalledTimes(1);
+  });
+
   it("rejects while the Runtime is running, with a distinct exit code", async () => {
     runtimeMocks.inspectRuntimeStatus.mockResolvedValueOnce({
       state: "running",
@@ -2728,7 +3010,7 @@ describe("backup restore drives the Core managed-restore contract", () => {
     });
   });
 
-  it("requires --confirm to repeat the exact source path", async () => {
+  it("refuses a legacy --confirm that does not repeat the source path", async () => {
     const maintenance = vi.fn();
     const output = captureStdout();
     let code: number;
@@ -2756,7 +3038,7 @@ describe("backup restore drives the Core managed-restore contract", () => {
       command: "backup",
       verb: "restore",
       state: "rejected",
-      code: "backup_restore_confirmation_required",
+      code: "backup_restore_confirmation_mismatch",
     });
   });
 
@@ -2908,7 +3190,7 @@ describe("init onboarding", () => {
 
   // Boolean flags were idempotent, but accepting them twice hid a duplicated
   // argv fragment that could also have duplicated a value-bearing flag.
-  it.each(["--import", "--full-rescan", "--confirm-overrides", "--dry-run"])(
+  it.each(["--import", "--confirm-overrides"])(
     "refuses a repeated init %s flag",
     async (flag) => {
       expect(await run(["init", "--source", "codex", flag, flag], {})).toBe(2);
@@ -2981,12 +3263,25 @@ describe("init onboarding", () => {
     },
   );
 
-  it("accepts --dry-run together with --import", async () => {
-    // Parsing must accept the pair; it stops at the Runtime check, which is
-    // not a usage failure.
-    expect(
-      await run(["init", "--source", "codex", "--import", "--dry-run"], {}),
-    ).not.toBe(2);
+  // `--dry-run` and `--full-rescan` never did anything (P0-2/P0-3): they are
+  // gone rather than accepted as no-ops.
+  it.each(["--dry-run", "--full-rescan"])(
+    "refuses the removed no-op %s flag",
+    async (flag) => {
+      expect(
+        await run(["init", "--source", "codex", "--import", flag], {}),
+      ).toBe(2);
+    },
+  );
+
+  it("still parses the old `init --source --import` spelling", async () => {
+    // It stops at the Runtime check (exit 3), which is not a usage failure.
+    const streams = captureStreams();
+    try {
+      expect(await run(["init", "--source", "codex", "--import"], {})).toBe(3);
+    } finally {
+      streams.restore();
+    }
   });
 });
 

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

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

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

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

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

@@ -133,6 +133,20 @@ describe("unified context search", () => {
     expect(output).not.toMatch(/^- raw |memory-1|raw-1|采用状态/m);
   });
 
+  it("labels raw hits as original-conversation excerpts, not memories", async () => {
+    const streams = captureStreams();
+    try {
+      expect(await run(["recall", "synthetic question"])).toBe(0);
+    } finally {
+      streams.restore();
+    }
+    const output = streams.stdout();
+    expect(output).toContain(
+      "- [原始对话摘录 · codex] Synthetic raw citation.",
+    );
+    expect(output).toContain("- [记忆] Synthetic SDK memory.");
+  });
+
   it("queries the SDK context endpoint directly and preserves item ids", async () => {
     const streams = captureStreams();
     try {

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

@@ -23,6 +23,7 @@ export interface ContextSearchDocument {
     | "unavailable"
     | "denied"
     | "not_found"
+    | "rejected"
     | "invalid";
   code?: string;
   request_id?: string;
@@ -97,6 +98,9 @@ export function renderContextText(document: ContextSearchDocument): string {
   if (document.state === "unavailable") return "暂时无法查记忆，请稍后重试。\n";
   if (document.state === "denied") return "当前应用没有查记忆权限。\n";
   if (document.state === "invalid") return "查记忆返回了无法识别的结果。\n";
+  if (document.state === "rejected") {
+    return `查记忆被拒绝（${document.code}），请检查参数。\n`;
+  }
   const lines = [
     document.state === "empty"
       ? "没有查到相关记忆。"
@@ -104,8 +108,14 @@ export function renderContextText(document: ContextSearchDocument): string {
         ? "查到以下内容，部分内容还在整理中："
         : "查到以下相关内容：",
   ];
+  // A raw hit is an excerpt of an original conversation, not a distilled
+  // memory; say which one each line is so it is not read as a conclusion.
   for (const item of document.items) {
-    lines.push(`- ${String(item.content)}`);
+    const label =
+      item.kind === "raw"
+        ? `[原始对话摘录 · ${String(item.source)}]`
+        : "[记忆]";
+    lines.push(`- ${label} ${String(item.content)}`);
   }
   if (document.truncated) lines.push("结果已按请求预算截断。");
   return `${lines.join("\n")}\n`;

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

@@ -18,6 +18,9 @@ const READ_ONLY_PATHS = [
   "/api/v2/user-profile",
 ] as const;
 const SDK_MEMORY_DETAIL = /^\/api\/v2\/memories\/[A-Za-z0-9][\w.-]{0,127}$/;
+/** Status of one `POST /api/v2/memories` addition, by its request id. */
+const MEMORY_ADDITION =
+  /^\/api\/v2\/memories\/additions\/[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/;
 
 /** Contract (C0, H25): the one-time loopback code exchange for `memhub ui`.
  * It is a POST because it mints a short-lived code; the CLI sends the bearer
@@ -79,9 +82,15 @@ export const RESERVED_MEMORY_SEGMENTS = ["ask", "graph"] as const;
 /** A response larger than this is refused before it is buffered. */
 const MAX_RESPONSE_BYTES = 4 * 1024 * 1024;
 
+/** `rejected` is Core refusing the request itself (400/409/422: a bad filter,
+ * an ambiguous id). It is not "Core is busy" — only a transport failure or a
+ * 5xx is `unavailable`. */
 export type ReadOutcome<T> =
   | { state: "ok"; data: T }
-  | { state: "denied" | "unavailable" | "not_found"; code: string };
+  | {
+      state: "denied" | "unavailable" | "not_found" | "rejected";
+      code: string;
+    };
 
 export type CoreReader = <T>(
   path: string,
@@ -140,10 +149,27 @@ export function createCoreReader(attachment: {
     if (response.status === 404) {
       return { state: "not_found" as const, code: "http_404" };
     }
+    if ([400, 409, 422].includes(response.status)) {
+      return {
+        state: "rejected" as const,
+        code: detailCode(response.data, response.status),
+      };
+    }
     return { state: "unavailable" as const, code: `http_${response.status}` };
   };
 }
 
+/** Core's stable `detail` code when it sent one, else the bare status. */
+function detailCode(value: unknown, status: number): string {
+  const detail =
+    value && typeof value === "object" && !Array.isArray(value)
+      ? (value as { detail?: unknown }).detail
+      : undefined;
+  return typeof detail === "string" && /^[a-z0-9_.:-]{1,128}$/.test(detail)
+    ? detail
+    : `http_${status}`;
+}
+
 /**
  * Context search is semantically read-only but intentionally uses POST so the
  * private query and filters are carried in a bounded body, never in a URL.
@@ -192,6 +218,7 @@ export function isReadOnlyPath(path: string): boolean {
   if ((READ_ONLY_PATHS as readonly string[]).includes(path)) return true;
   if (IMPORT_JOB.test(path)) return true;
   if (OPERATION_RECEIPT.test(path)) return true;
+  if (MEMORY_ADDITION.test(path)) return true;
   if (!SDK_MEMORY_DETAIL.test(path)) return false;
   const segment = path.slice("/api/v2/memories/".length);
   return !(RESERVED_MEMORY_SEGMENTS as readonly string[]).includes(segment);
@@ -199,8 +226,10 @@ export function isReadOnlyPath(path: string): boolean {
 
 /** A write accepted by the unified Memory Server entry.
  *
- * `request_id` is what the caller keeps and queries later. Retrying is unsafe:
- * HY has no idempotency key, so a resubmit duplicates the memory.
+ * `request_id` is the idempotency key: Core keys the write on it, so a retry
+ * with the same id and the same messages is answered from the first write, and
+ * the same id with different messages is refused (409). A retry without the
+ * original id is a new write.
  */
 export interface MemoryWriteReceipt {
   request_id: string;
@@ -267,6 +296,11 @@ function baseUrlOf(attachment: RuntimeAttachmentLike): string {
   return `http://${attachment.host}:${attachment.port}`;
 }
 
+export type MemoryWriteOutcome =
+  | { state: "accepted"; receipt: MemoryWriteReceipt }
+  | { state: "rejected"; code: string; http_status: number }
+  | { state: "unknown"; code: string };
+
 export async function submitMemoryWrite(
   attachment: RuntimeAttachmentLike,
   request: {
@@ -277,28 +311,48 @@ export async function submitMemoryWrite(
     memory_at?: string;
     priority?: "live" | "normal";
   },
-): Promise<MemoryWriteReceipt> {
-  const response = await axios.post<MemoryWriteReceipt>(
-    `${baseUrlOf(attachment)}/api/v2/memory-writes`,
-    {
-      request_id: request.request_id,
-      session_id: request.session,
-      source_id: request.source,
-      messages: [...request.messages],
-      ...(request.memory_at === undefined
-        ? {}
-        : { memory_at: request.memory_at }),
-      ...(request.priority === undefined ? {} : { priority: request.priority }),
-    },
-    {
-      headers: { Authorization: `Bearer ${attachment.apiToken}` },
-      timeout: 15_000,
-      proxy: false,
-      maxRedirects: 0,
-      maxContentLength: MAX_RESPONSE_BYTES,
-    },
-  );
-  return response.data;
+): Promise<MemoryWriteOutcome> {
+  let response: { status: number; data: unknown };
+  try {
+    response = await axios.post<MemoryWriteReceipt>(
+      `${baseUrlOf(attachment)}/api/v2/memory-writes`,
+      {
+        request_id: request.request_id,
+        session_id: request.session,
+        source_id: request.source,
+        messages: [...request.messages],
+        ...(request.memory_at === undefined
+          ? {}
+          : { memory_at: request.memory_at }),
+        ...(request.priority === undefined
+          ? {}
+          : { priority: request.priority }),
+      },
+      {
+        headers: { Authorization: `Bearer ${attachment.apiToken}` },
+        timeout: 15_000,
+        proxy: false,
+        maxRedirects: 0,
+        maxContentLength: MAX_RESPONSE_BYTES,
+        validateStatus: () => true,
+      },
+    );
+  } catch {
+    // The request may or may not have reached Core; the same request id makes
+    // a retry safe.
+    return { state: "unknown", code: "transport_result_unknown" };
+  }
+  if (response.status >= 200 && response.status < 300) {
+    return { state: "accepted", receipt: response.data as MemoryWriteReceipt };
+  }
+  if (response.status >= 400 && response.status < 500) {
+    return {
+      state: "rejected",
+      code: detailCode(response.data, response.status),
+      http_status: response.status,
+    };
+  }
+  return { state: "unknown", code: `http_${response.status}_result_unknown` };
 }
 
 /** Ask Runtime to scan one source now, returning the import job it started.
@@ -495,48 +549,52 @@ export async function readScanRoots(
   }
 }
 
+/** A direct Core write whose refusal carries Core's stable code. */
+export type CoreWriteResult =
+  | { ok: true; data: unknown }
+  | { ok: false; code: string };
+
+async function coreWrite(
+  attachment: RuntimeAttachmentLike,
+  method: "post" | "delete",
+  pathname: string,
+  body: Record<string, unknown>,
+  timeout = 10_000,
+): Promise<CoreWriteResult> {
+  let response: { status: number; data: unknown };
+  try {
+    response = await axios.request({
+      method,
+      url: `${baseUrlOf(attachment)}${pathname}`,
+      data: body,
+      headers: { Authorization: `Bearer ${attachment.apiToken}` },
+      timeout,
+      proxy: false,
+      maxRedirects: 0,
+      maxContentLength: MAX_RESPONSE_BYTES,
+      validateStatus: () => true,
+    });
+  } catch {
+    return { ok: false, code: "transport_failed" };
+  }
+  if (response.status >= 200 && response.status < 300) {
+    return { ok: true, data: response.data };
+  }
+  return { ok: false, code: detailCode(response.data, response.status) };
+}
+
 export async function addScanRoot(
   attachment: RuntimeAttachmentLike,
   body: { root: string; source?: string; recursive?: boolean },
-): Promise<unknown | null> {
-  try {
-    const response = await axios.post<unknown>(
-      `${baseUrlOf(attachment)}/api/v1/scan-roots`,
-      body,
-      {
-        headers: { Authorization: `Bearer ${attachment.apiToken}` },
-        timeout: 10_000,
-        proxy: false,
-        maxRedirects: 0,
-        maxContentLength: MAX_RESPONSE_BYTES,
-      },
-    );
-    return response.data;
-  } catch (error) {
-    return { _error: error instanceof Error ? error.message : String(error) };
-  }
+): Promise<CoreWriteResult> {
+  return coreWrite(attachment, "post", "/api/v1/scan-roots", body);
 }
 
 export async function removeScanRoot(
   attachment: RuntimeAttachmentLike,
   body: { root: string },
-): Promise<unknown | null> {
-  try {
-    const response = await axios.delete<unknown>(
-      `${baseUrlOf(attachment)}/api/v1/scan-roots`,
-      {
-        headers: { Authorization: `Bearer ${attachment.apiToken}` },
-        data: body,
-        timeout: 10_000,
-        proxy: false,
-        maxRedirects: 0,
-        maxContentLength: MAX_RESPONSE_BYTES,
-      },
-    );
-    return response.data;
-  } catch (error) {
-    return { _error: error instanceof Error ? error.message : String(error) };
-  }
+): Promise<CoreWriteResult> {
+  return coreWrite(attachment, "delete", "/api/v1/scan-roots", body);
 }
 
 export async function readAdapters(
@@ -562,21 +620,12 @@ export async function readAdapters(
 export async function probeAdapter(
   attachment: RuntimeAttachmentLike,
   source: string,
-): Promise<unknown | null> {
-  try {
-    const response = await axios.post<unknown>(
-      `${baseUrlOf(attachment)}/api/v1/adapters/probe`,
-      { source },
-      {
-        headers: { Authorization: `Bearer ${attachment.apiToken}` },
-        timeout: 15_000,
-        proxy: false,
-        maxRedirects: 0,
-        maxContentLength: MAX_RESPONSE_BYTES,
-      },
-    );
-    return response.data;
-  } catch (error) {
-    return { _error: error instanceof Error ? error.message : String(error) };
-  }
+): Promise<CoreWriteResult> {
+  return coreWrite(
+    attachment,
+    "post",
+    "/api/v1/adapters/probe",
+    { source },
+    15_000,
+  );
 }

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

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

memhub/apps/cli/src/entry.ts

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

@@ -104,7 +104,7 @@ describe("package matrix harness", () => {
     });
   });
 
-  it("fails closed on every destructive UI-write command without a Runtime", {
+  it("fails closed on every write command without a Runtime", {
     timeout: 120_000,
   }, async () => {
     const runtimeDist = await mkdtemp(
@@ -140,7 +140,7 @@ describe("package matrix harness", () => {
     expect(document.state).toBe("verified");
     const results = document.commands.stopped_destructive.results;
     // Every destructive command fails closed while Runtime is stopped.
-    expect(Object.keys(results)).toHaveLength(7);
+    expect(Object.keys(results)).toHaveLength(8);
     for (const [name, result] of Object.entries(results)) {
       expect(result, `${name} did not fail closed`).toEqual({
         exit: 3,
@@ -164,7 +164,7 @@ describe("package matrix harness", () => {
     const shim = [
       "#!/usr/bin/env node",
       "const a=process.argv.slice(2);",
-      "if(['calls','notes','graph','models','memories'].includes(a[0])){",
+      "if(['graph-width','models','memories','sources'].includes(a[0])){",
       '  process.stdout.write(\'{"schema_version":1,"product":"memhub","state":"committed","operation_id":"x","receipt":{}}\\n\');',
       "  process.exit(0);",
       "}",
@@ -190,7 +190,7 @@ describe("package matrix harness", () => {
     expect(failure?.state).toBe("failed");
     expect(
       failure?.failures.filter((item) => item.includes("did not fail closed")),
-    ).toHaveLength(7);
+    ).toHaveLength(8);
   });
 
   it("can require an expected bundle SHA and reports bundle metadata", {
@@ -291,9 +291,7 @@ describe("package matrix harness", () => {
       "sync",
       "memories",
       "profile",
-      "calls",
-      "notes",
-      "graph",
+      "graph-width",
       "models",
       "host",
       "doctor",
@@ -311,14 +309,12 @@ describe("package matrix harness", () => {
       "uninstall",
       "delete-data",
       "recall",
-      "setup",
       "scan",
       "progress",
       "jobs",
-      "path",
+      "scan-roots",
       "adapter",
       "write",
-      "task",
       "serve",
     ];
     const catalog = {

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

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

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

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

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

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

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

@@ -697,6 +697,66 @@ describe("CLI-21 memory reads", () => {
     expect(report.memories[1].content.length).toBeLessThan(400);
   });
 
+  it("lists working and coding memories with their scene and kind", async () => {
+    transport.get.mockResolvedValue({
+      status: 200,
+      data: {
+        total: 2,
+        offset: 0,
+        limit: 20,
+        totals: { chat: 1, working: 1, coding: 0 },
+        window_id: null,
+        window_reset: false,
+        memories: [
+          memory("m1", "对话记忆"),
+          {
+            ...memory("e1", "修复测试\n固定随机种子"),
+            layer: "experience",
+            agent_id: "",
+            owner: null,
+            source_raw_ids: [],
+            scene: "working",
+            kind: "experience",
+            variant: "working",
+            task: "修复测试",
+            solution: "固定随机种子",
+            created_at: 1_790_000_000,
+            updated_at: 1_790_000_100,
+          },
+        ],
+      },
+    });
+    const streams = captureStreams();
+    try {
+      expect(await run(["memories", "list", "--json"], {})).toBe(0);
+    } finally {
+      streams.restore();
+    }
+    const report = JSON.parse(streams.stdout());
+    expect(report.page).toMatchObject({ state: "ok", total: 2, returned: 2 });
+    expect(report.memories[0]).toMatchObject({
+      memory_id: "m1",
+      scene: "chat",
+      kind: "chat",
+      variant: null,
+    });
+    expect(report.memories[1]).toMatchObject({
+      memory_id: "e1",
+      scene: "working",
+      kind: "experience",
+      variant: "working",
+      layer: "experience",
+    });
+
+    const text = captureStreams();
+    try {
+      expect(await run(["memories", "list"], {})).toBe(0);
+    } finally {
+      text.restore();
+    }
+    expect(text.stdout()).toContain("- e1  [working] active/experience");
+  });
+
   it("passes the requested filters through as query parameters", async () => {
     await run(
       [
@@ -818,8 +878,11 @@ describe("CLI-21 memory reads", () => {
       layer: "L2_FACT",
       status: "active",
     });
-    expect(report.evidence).toEqual([]);
-    expect(report.history).toEqual([]);
+    // Schema 2, like add/update/delete; the v1-era always-empty
+    // `evidence`/`history` fields are gone.
+    expect(report.schema_version).toBe(2);
+    expect(report).not.toHaveProperty("evidence");
+    expect(report).not.toHaveProperty("history");
   });
 
   // Core registers /api/v2/memories/graph before /{memory_id}, and that static
@@ -1077,14 +1140,16 @@ describe("backup create target refusal is rejected, not usage_error", () => {
     let code: number;
     try {
       code = await run(
-        ["backup", "create", "--target", "/tmp/outside.db", "--yes", "--json"],
+        ["backup", "create", "--target", "/tmp/outside.db", "--json"],
         {},
       );
     } finally {
       streams.restore();
     }
     expect(code!).toBe(1);
-    const document = JSON.parse(streams.stderr());
+    // A result, on stdout like every --json document.
+    expect(streams.stderr()).toBe("");
+    const document = JSON.parse(streams.stdout());
     expect(document.status).not.toBe("usage_error");
     expect(document).toMatchObject({
       command: "backup",

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

@@ -341,7 +341,11 @@ function validated<T>(
 ):
   | { state: "ok"; data: T }
   | { state: Exclude<ReadState["state"], "ok">; code: string } {
-  if (outcome.state !== "ok") return outcome;
+  if (outcome.state !== "ok") {
+    // A Core refusal of the request itself reads as an invalid answer here.
+    const state = outcome.state === "rejected" ? "invalid" : outcome.state;
+    return { state, code: outcome.code };
+  }
   const data = validate(outcome.data);
   return data === null
     ? { state: "invalid", code: "response_invalid" }

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

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

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

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

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

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

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

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

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

@@ -1,555 +0,0 @@
-/**
- * The Web Console's remaining mutating operations, exposed to the CLI without
- * duplicating Core semantics. Each operation is planned first; callers apply
- * the exact plan they reviewed.
- */
-
-import { createHash } from "node:crypto";
-import { constants } from "node:fs";
-import { type FileHandle, open } from "node:fs/promises";
-import type {
-  CoreDeleteOperations,
-  CoreOperations,
-  CoreUploadOperations,
-} from "./core-operations.js";
-import { PRODUCT } from "./version.js";
-
-const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/;
-const INPUT_KINDS = ["raw_conversation", "memory_content"] as const;
-const MAX_UPLOAD_BYTES = 128 * 1024 * 1024;
-
-export type UiWritePlan =
-  | {
-      schema_version: 1;
-      kind: "call_events_clear";
-      event_ids: string[];
-      digest: string;
-    }
-  | {
-      schema_version: 1;
-      kind: "call_events_clear_all";
-      digest: string;
-    }
-  | {
-      schema_version: 1;
-      kind: "import_file_commit";
-      upload_id: string;
-      digest: string;
-    }
-  | {
-      schema_version: 1;
-      kind: "import_file_discard";
-      upload_id: string;
-      digest: string;
-    }
-  | {
-      schema_version: 1;
-      kind: "import_file_upload";
-      operation_id: string;
-      path: string;
-      filename: string;
-      input_kind: (typeof INPUT_KINDS)[number];
-      bytes: number;
-      sha256: string;
-      digest: string;
-    };
-
-export type UiWriteOutcome =
-  | {
-      schema_version: 1;
-      product: string;
-      state: "preview";
-      plan: UiWritePlan;
-    }
-  | {
-      schema_version: 1;
-      product: string;
-      state: "committed" | "recovered";
-      operation_id: string;
-      receipt: Record<string, unknown>;
-    }
-  | {
-      schema_version: 1;
-      product: string;
-      state: "rejected" | "unknown" | "invalid";
-      operation_id?: string;
-      code: string;
-      receipt?: Record<string, unknown>;
-    };
-
-function digestOf(value: unknown): string {
-  return createHash("sha256").update(canonical(value)).digest("hex");
-}
-
-function canonical(value: unknown): string {
-  if (Array.isArray(value)) return `[${value.map(canonical).join(",")}]`;
-  if (value !== null && typeof value === "object") {
-    return `{${Object.entries(value as Record<string, unknown>)
-      .sort(([left], [right]) => left.localeCompare(right))
-      .map(([key, item]) => `${JSON.stringify(key)}:${canonical(item)}`)
-      .join(",")}}`;
-  }
-  if (value === undefined) return "null";
-  return JSON.stringify(value);
-}
-
-export type UiWritePlanDraft =
-  | Omit<Extract<UiWritePlan, { kind: "call_events_clear" }>, "digest">
-  | Omit<Extract<UiWritePlan, { kind: "call_events_clear_all" }>, "digest">
-  | Omit<Extract<UiWritePlan, { kind: "import_file_commit" }>, "digest">
-  | Omit<Extract<UiWritePlan, { kind: "import_file_discard" }>, "digest">
-  | Omit<Extract<UiWritePlan, { kind: "import_file_upload" }>, "digest">;
-
-function preview(plan: UiWritePlanDraft): UiWriteOutcome {
-  return {
-    schema_version: 1,
-    product: PRODUCT,
-    state: "preview",
-    plan: { ...plan, digest: digestOf(plan) } as UiWritePlan,
-  };
-}
-
-function invalid(code: string): UiWriteOutcome {
-  return { schema_version: 1, product: PRODUCT, state: "invalid", code };
-}
-
-function committed(
-  operationId: string,
-  receipt: Record<string, unknown>,
-  state: "committed" | "recovered" = "committed",
-): UiWriteOutcome {
-  return {
-    schema_version: 1,
-    product: PRODUCT,
-    state,
-    operation_id: operationId,
-    receipt,
-  };
-}
-
-export function planCallEventsClear(
-  eventIds: readonly string[],
-): UiWriteOutcome {
-  if (
-    eventIds.length < 1 ||
-    eventIds.length > 100 ||
-    new Set(eventIds).size !== eventIds.length ||
-    eventIds.some((id) => !UUID.test(id))
-  ) {
-    return invalid("call_event_ids_invalid");
-  }
-  return preview({
-    schema_version: 1,
-    kind: "call_events_clear",
-    event_ids: [...eventIds],
-  });
-}
-
-export function planCallEventsClearAll(): UiWriteOutcome {
-  return preview({ schema_version: 1, kind: "call_events_clear_all" });
-}
-
-export function planImportFileCommit(uploadId: string): UiWriteOutcome {
-  return UUID.test(uploadId)
-    ? preview({
-        schema_version: 1,
-        kind: "import_file_commit",
-        upload_id: uploadId,
-      })
-    : invalid("import_file_id_invalid");
-}
-
-export function planImportFileDiscard(uploadId: string): UiWriteOutcome {
-  return UUID.test(uploadId)
-    ? preview({
-        schema_version: 1,
-        kind: "import_file_discard",
-        upload_id: uploadId,
-      })
-    : invalid("import_file_id_invalid");
-}
-
-export function planImportFileUpload(input: {
-  path: string;
-  bytes: number;
-  sha256: string;
-  inputKind: "raw_conversation" | "memory_content";
-}): UiWriteOutcome {
-  const filename = input.path.split(/[/\\]/).pop() ?? "";
-  if (
-    input.path.length === 0 ||
-    !Number.isSafeInteger(input.bytes) ||
-    input.bytes < 0 ||
-    input.bytes > MAX_UPLOAD_BYTES ||
-    !/^[0-9a-f]{64}$/.test(input.sha256) ||
-    !INPUT_KINDS.includes(input.inputKind) ||
-    filename.length === 0 ||
-    [...filename].length > 200 ||
-    !/\.(?:zip|json|md|txt)$/i.test(filename)
-  ) {
-    return invalid("import_file_upload_invalid");
-  }
-  return preview({
-    schema_version: 1,
-    kind: "import_file_upload",
-    operation_id: fileUploadOperationId(
-      filename,
-      input.inputKind,
-      input.sha256,
-    ),
-    path: input.path,
-    filename,
-    input_kind: input.inputKind,
-    bytes: input.bytes,
-    sha256: input.sha256,
-  });
-}
-
-/**
- * Read one regular, non-symlinked export without buffering past the 128 MiB
- * limit. Returns the bytes plus the checksum the plan records, so apply can
- * prove the file it uploads is the one the caller reviewed.
- */
-export async function readImportFileUpload(
-  filePath: string,
-  inputKind: "raw_conversation" | "memory_content",
-): Promise<{ plan: UiWritePlan; bytes: Buffer } | null> {
-  let handle: FileHandle;
-  try {
-    handle = await open(
-      filePath,
-      constants.O_RDONLY |
-        (constants.O_NONBLOCK ?? 0) |
-        (constants.O_NOFOLLOW ?? 0),
-    );
-  } catch {
-    return null;
-  }
-  try {
-    const stats = await handle.stat();
-    if (!stats.isFile() || stats.nlink !== 1 || stats.size > MAX_UPLOAD_BYTES) {
-      return null;
-    }
-    const buffer = Buffer.alloc(Number(stats.size));
-    let offset = 0;
-    while (offset < buffer.length) {
-      const chunk = await handle.read(
-        buffer,
-        offset,
-        buffer.length - offset,
-        offset,
-      );
-      if (chunk.bytesRead === 0) break;
-      offset += chunk.bytesRead;
-    }
-    if (offset !== buffer.length) return null;
-    const checksum = createHash("sha256").update(buffer).digest("hex");
-    const result = planImportFileUpload({
-      path: filePath,
-      bytes: buffer.byteLength,
-      sha256: checksum,
-      inputKind,
-    });
-    if (result.state !== "preview") return null;
-    return { plan: result.plan, bytes: buffer };
-  } catch {
-    return null;
-  } finally {
-    await handle.close().catch(() => undefined);
-  }
-}
-
-/**
- * Core keys upload idempotency by `operation_id` and rejects a replay whose
- * fingerprint differs. Deriving it from the file's own identity means a retry
- * after a dropped response resumes the same staging operation instead of
- * creating a second upload; a genuinely different payload maps to a different
- * operation and cannot overwrite the first.
- */
-function fileUploadOperationId(
-  filename: string,
-  inputKind: (typeof INPUT_KINDS)[number],
-  checksum: string,
-): string {
-  const hex = createHash("sha256")
-    .update(JSON.stringify([filename, inputKind, checksum]))
-    .digest("hex");
-  return [
-    hex.slice(0, 8),
-    hex.slice(8, 12),
-    `4${hex.slice(13, 16)}`,
-    `${(8 + (parseInt(hex[16]!, 16) % 4)).toString(16)}${hex.slice(17, 20)}`,
-    hex.slice(20, 32),
-  ].join("-");
-}
-
-export function validateUiWritePlan(value: unknown): UiWritePlan | null {
-  if (value === null || typeof value !== "object" || Array.isArray(value)) {
-    return null;
-  }
-  const candidate = value as Record<string, unknown>;
-  if (candidate.schema_version !== 1 || typeof candidate.kind !== "string") {
-    return null;
-  }
-  const { digest, ...withoutDigest } = candidate;
-  if (typeof digest !== "string" || digest !== digestOf(withoutDigest)) {
-    return null;
-  }
-  switch (candidate.kind) {
-    case "call_events_clear":
-      return Array.isArray(candidate.event_ids) &&
-        candidate.event_ids.length >= 1 &&
-        candidate.event_ids.length <= 100 &&
-        new Set(candidate.event_ids).size === candidate.event_ids.length &&
-        candidate.event_ids.every(
-          (id) => typeof id === "string" && UUID.test(id),
-        )
-        ? (candidate as unknown as UiWritePlan)
-        : null;
-    case "call_events_clear_all":
-      return Object.keys(candidate).length === 3
-        ? (candidate as unknown as UiWritePlan)
-        : null;
-    case "import_file_commit":
-    case "import_file_discard":
-      return typeof candidate.upload_id === "string" &&
-        UUID.test(candidate.upload_id) &&
-        Object.keys(candidate).length === 4
-        ? (candidate as unknown as UiWritePlan)
-        : null;
-    case "import_file_upload":
-      return typeof candidate.operation_id === "string" &&
-        UUID.test(candidate.operation_id) &&
-        typeof candidate.path === "string" &&
-        typeof candidate.filename === "string" &&
-        candidate.filename === candidate.path.split(/[/\\]/).pop() &&
-        /^[0-9a-f]{64}$/.test(String(candidate.sha256)) &&
-        INPUT_KINDS.includes(
-          candidate.input_kind as (typeof INPUT_KINDS)[number],
-        ) &&
-        Number.isSafeInteger(candidate.bytes) &&
-        (candidate.bytes as number) >= 0 &&
-        (candidate.bytes as number) <= 128 * 1024 * 1024
-        ? (candidate as unknown as UiWritePlan)
-        : null;
-    default:
-      return null;
-  }
-}
-
-export function uiWriteExitCode(document: UiWriteOutcome): number {
-  return ["preview", "committed", "recovered"].includes(document.state) ? 0 : 1;
-}
-
-export function renderUiWriteText(document: UiWriteOutcome): string {
-  if (document.state === "preview") {
-    return `以下操作尚未执行；加 --confirm 后才会写入：\n${document.plan.kind}\nplan_digest：${document.plan.digest}\n`;
-  }
-  if (document.state === "committed" || document.state === "recovered") {
-    return `已提交：${document.operation_id}\n${JSON.stringify(document.receipt)}\n`;
-  }
-  const code = "code" in document ? document.code : "ui_write_state_invalid";
-  return `操作未完成：${document.state}（${code}）\n`;
-}
-
-export async function executeCallEventsClear(
-  plan: Extract<UiWritePlan, { kind: "call_events_clear" }>,
-  operations: CoreOperations,
-): Promise<UiWriteOutcome> {
-  const result = await operations.post<unknown>("/api/v1/call-events/clear", {
-    event_ids: plan.event_ids,
-    user_confirmed: true,
-  });
-  return outcome(result, plan.event_ids.join(","), ["removed"]);
-}
-
-export async function executeCallEventsClearAll(
-  plan: Extract<UiWritePlan, { kind: "call_events_clear_all" }>,
-  operations: CoreOperations,
-): Promise<UiWriteOutcome> {
-  const result = await operations.post<unknown>(
-    "/api/v1/call-events/clear-all",
-    { user_confirmed: true },
-  );
-  return outcome(result, "all", ["removed"]);
-}
-
-export async function executeImportFileCommit(
-  plan: Extract<UiWritePlan, { kind: "import_file_commit" }>,
-  operations: CoreOperations,
-): Promise<UiWriteOutcome> {
-  const result = await operations.post<unknown>(
-    `/api/v1/import-files/${plan.upload_id}/commit`,
-    { confirmed: true },
-  );
-  return outcome(result, plan.upload_id, [
-    "upload_id",
-    "filename",
-    "vendor",
-    "source_id",
-    "messages",
-    "conversations",
-    "human_messages",
-    "agent_messages",
-    "skipped_records",
-    "ignored_files",
-    "checksum",
-    "created_at",
-    "committed",
-  ]);
-}
-
-export async function executeImportFileDiscard(
-  plan: Extract<UiWritePlan, { kind: "import_file_discard" }>,
-  operations: CoreDeleteOperations,
-): Promise<UiWriteOutcome> {
-  const result = await operations.delete<unknown>(
-    `/api/v1/import-files/${plan.upload_id}`,
-  );
-  // Core answers 204 with no body. A successful delete is a committed
-  // operation even though there is no receipt to validate; requiring a body
-  // here would report every real discard as `ui_write_receipt_invalid`.
-  return outcome(result, plan.upload_id, null);
-}
-
-/** Upload one local file through the same recoverable Core staging flow the
- * Web console uses. The operation id is part of the plan, so a retry after a
- * dropped response resumes the same staging record instead of duplicating it.
- */
-export async function executeImportFileUpload(
-  plan: Extract<UiWritePlan, { kind: "import_file_upload" }>,
-  operations: CoreUploadOperations,
-): Promise<UiWriteOutcome> {
-  // Re-read the file at apply time and re-derive its identity. A plan that
-  // names a path whose content changed after review is refused rather than
-  // uploading something the caller never saw.
-  const reread = await readImportFileUpload(plan.path, plan.input_kind);
-  if (reread === null) {
-    return invalid("import_file_upload_unreadable");
-  }
-  const bytes = reread.bytes;
-  const checksum = createHash("sha256").update(bytes).digest("hex");
-  if (
-    bytes.byteLength !== plan.bytes ||
-    checksum !== plan.sha256 ||
-    reread.plan.digest !== plan.digest
-  ) {
-    return invalid("import_file_upload_content_mismatch");
-  }
-  const result = await operations.uploadImportFile<unknown>({
-    bytes,
-    filename: plan.filename,
-    inputKind: plan.input_kind,
-    operationId: plan.operation_id,
-  });
-  if (result.state === "rejected") {
-    return {
-      schema_version: 1,
-      product: PRODUCT,
-      state: "rejected",
-      operation_id: plan.operation_id,
-      code: result.code,
-    };
-  }
-  if (result.state === "unknown") {
-    return {
-      schema_version: 1,
-      product: PRODUCT,
-      state: "unknown",
-      operation_id: plan.operation_id,
-      code: result.code,
-    };
-  }
-  const receipt =
-    result.data !== null &&
-    typeof result.data === "object" &&
-    !Array.isArray(result.data)
-      ? (result.data as Record<string, unknown>)
-      : null;
-  if (
-    receipt === null ||
-    receipt.operation_id !== plan.operation_id ||
-    typeof receipt.state !== "string"
-  ) {
-    return {
-      schema_version: 1,
-      product: PRODUCT,
-      state: "unknown",
-      operation_id: plan.operation_id,
-      code: "ui_write_receipt_invalid",
-    };
-  }
-  // Core reports the staged upload as `completed`; `pending`/`not_found` here
-  // means the operation record did not settle, so the result is not known.
-  if (receipt.state !== "completed") {
-    return {
-      schema_version: 1,
-      product: PRODUCT,
-      state: "unknown",
-      operation_id: plan.operation_id,
-      code: `import_upload_${receipt.state}`,
-    };
-  }
-  const uploadId =
-    typeof receipt.upload_id === "string" ? receipt.upload_id : undefined;
-  if (uploadId === undefined || !UUID.test(uploadId)) {
-    return {
-      schema_version: 1,
-      product: PRODUCT,
-      state: "unknown",
-      operation_id: plan.operation_id,
-      code: "ui_write_receipt_invalid",
-    };
-  }
-  return committed(plan.operation_id, {
-    operation_id: plan.operation_id,
-    upload_id: uploadId,
-    upload_state: receipt.upload_state ?? null,
-  });
-}
-
-function outcome(
-  result:
-    | Awaited<ReturnType<CoreOperations["post"]>>
-    | Awaited<ReturnType<CoreDeleteOperations["delete"]>>,
-  operationId: string,
-  required: readonly string[] | null,
-): UiWriteOutcome {
-  if (result.state === "rejected") {
-    return {
-      schema_version: 1,
-      product: PRODUCT,
-      state: "rejected",
-      operation_id: operationId,
-      code: result.code,
-    };
-  }
-  if (result.state === "unknown") {
-    return {
-      schema_version: 1,
-      product: PRODUCT,
-      state: "unknown",
-      operation_id: operationId,
-      code: result.code,
-    };
-  }
-  if (required === null) {
-    return committed(operationId, {});
-  }
-  const data =
-    result.data !== null &&
-    typeof result.data === "object" &&
-    !Array.isArray(result.data)
-      ? (result.data as Record<string, unknown>)
-      : null;
-  if (data === null || required.some((key) => !Object.hasOwn(data, key))) {
-    return {
-      schema_version: 1,
-      product: PRODUCT,
-      state: "unknown",
-      operation_id: operationId,
-      code: "ui_write_receipt_invalid",
-    };
-  }
-  return committed(operationId, data);
-}

memhub/apps/cli/src/usage.ts

@@ -13,7 +13,16 @@ const GLOBAL_OPTIONS: readonly CommandOption[] = [
     summary: "显示帮助；可与 --json 组合输出机器可读目录。",
   },
   { flag: "--version, -V", summary: "显示 CLI 版本。" },
-  { flag: "--json", summary: "以 JSON 输出到 stdout，供脚本与 Agent 消费。" },
+  {
+    flag: "--json",
+    summary:
+      "以 JSON 输出到 stdout，供脚本与 Agent 消费；结果与失败都在 stdout，只有参数错误写 stderr。",
+  },
+  {
+    flag: "--data-dir <path>",
+    summary:
+      "本次使用的 MemHub 数据目录（绝对路径）；默认 ONE_MEMORY_DATA_DIR > 安装回执 > ~/.one-memory。",
+  },
 ];
 
 export function renderGeneralHelp(): string {
@@ -33,6 +42,9 @@ export function renderGeneralHelp(): string {
       (exit) => `  ${exit.code}  ${pad(exit.name, 17)}${exit.summary}`,
     ),
     "",
+    "确认约定：只有不可逆操作（memories delete、models remove、delete-data、backup restore、graph-width --decision rebuild_with_new）需要 --yes；不加时只说明将要做什么，不做任何改动，exit 0。delete-data 与 backup restore 还要用 --confirm <path> 再写一遍目标路径。install/upgrade/uninstall/service-install/service-uninstall 不加 --yes 时只出计划。其它写命令直接执行。",
+    "异步操作返回 ID，用对应命令查进度：sources receipt、models receipt、memories add-status、write status。",
+    "目前仅支持 macOS 与 Linux 连接本机 Runtime。",
     "stdout 只输出数据，进度与诊断写入 stderr。",
     `运行 ${PRODUCT} help <command> 查看单个命令的参数。`,
     "",
@@ -55,6 +67,8 @@ export function renderCommandHelp(command: CommandDescriptor): string {
     );
   }
   lines.push(
+    "Global options: --json、--data-dir <path>（见 memhub help）。",
+    "",
     "Exit codes:",
     ...EXIT_CODES.filter((exit) => command.exit_codes.includes(exit.code)).map(
       (exit) => `  ${exit.code}  ${pad(exit.name, 17)}${exit.summary}`,

memhub/apps/core/pyproject.toml

@@ -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.5",
+    "hy-memory==2.0.6",
     # 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/api.py

@@ -74,7 +74,11 @@ from one_memory.exception_reporting import (
     report_exception,
     watched_task,
 )
-from one_memory.external_memory_access import external_access, require_external_endpoint
+from one_memory.external_memory_access import (
+    ExternalMemoryAccess,
+    external_access,
+    require_external_endpoint,
+)
 from one_memory.extraction_settings import ExtractionSettings, ExtractionSettingsStore
 from one_memory.file_imports import FileImportStore, file_import_router
 from one_memory.hy_graph_admin import GraphWidthDecision, GraphWidthMismatch
@@ -87,6 +91,7 @@ from one_memory.hy_runtime_config import (
     set_diagnostic_log_level,
 )
 from one_memory.hy_sdk_runtime import (
+    AmbiguousMemoryIdError,
     SdkClientHandle,
     builtin_retrieval_snapshot,
     close_all_shared_runtimes,
@@ -96,11 +101,14 @@ from one_memory.hy_sdk_types import (
     HySdkError,
     HySdkMemoryPage,
     HySdkMemoryRecord,
+    HySdkRawHit,
     HySdkRawPage,
     HySdkRawRecord,
     HySdkReadError,
     HySdkUserProfile,
+    LibraryHit,
     library_keyword_hits,
+    parse_sdk_raw_search,
     parse_sdk_search,
 )
 from one_memory.imports.access import (
@@ -152,16 +160,17 @@ from one_memory.imports.sources.registry import (
 )
 from one_memory.imports.storage import EvidenceStore
 from one_memory.imports.supervisor import ImportSupervisor
+from one_memory.library_search_window import LibrarySearchWindows, window_key
 from one_memory.library_upgrade import LibraryUpgradeError, prepare_library
 from one_memory.loop_watchdog import LoopWatchdog
+from one_memory.memory_additions import (
+    LegacyMemoryAdditionReader,
+    MemoryAdditionStore,
+    memory_add_router,
+)
 from one_memory.memory_governance import (
     MemoryGovernanceStore,
 )
-from one_memory.memory_notes import (
-    LegacyMemoryNoteReader,
-    MemoryNoteStore,
-    memory_note_router,
-)
 from one_memory.memory_qa import MemoryAnswerError
 from one_memory.memory_queue import (
     ExtractionWindowPreset,
@@ -253,6 +262,11 @@ class HealthResponse(BaseModel):
     # is answering. Reads fall back to exact LIKE while this is not ready.
     content_candidate_backfill: Literal["idle", "running", "ready", "failed"] = "idle"
     content_candidate_backfill_failure: str | None = None
+    # Picking up work an earlier run left unfinished starts after readiness.
+    # "running" is not degraded: Core is ready and answers throughout; the
+    # failed steps are named so a stuck recovery is visible without a log.
+    recovery: Literal["pending", "running", "done", "failed"] = "done"
+    recovery_failed_steps: tuple[str, ...] = ()
 
 
 class BackupRequest(BaseModel):
@@ -391,10 +405,20 @@ class ConnectSourcesResponse(BaseModel):
     request_id: str | None = None
 
 
+SdkMemoryKind = Literal["chat", "experience", "fact"]
+SdkMemoryVariant = Literal["working", "coding"]
+
+
 class SdkMemoryUpdateRequest(BaseModel):
     model_config = ConfigDict(extra="forbid")
 
+    # Chat: the memory text. Experience: the solution. Fact: the statement.
     content: str = Field(min_length=1, max_length=200_000)
+    # Optional namespace, as listed on the memory (`kind`, `variant`).
+    kind: SdkMemoryKind | None = None
+    variant: SdkMemoryVariant | None = None
+    # Experiences only: also replace the task.
+    task: str | None = Field(default=None, min_length=1, max_length=200_000)
 
 
 class SdkUserProfileResponse(BaseModel):
@@ -685,28 +709,8 @@ def create_app(
                 # Only the maintenance Core (restore) may open such a home.
                 raise SdkMigrationRequired()
             if app.state.memory_authority is MemoryAuthority.SDK:
-                from one_memory.hy_sdk_migration import (
-                    repair_sdk_metadata_from_bundle,
-                )
-
-                try:
-                    repair = await asyncio.to_thread(
-                        repair_sdk_metadata_from_bundle,
-                        data_dir=runtime_settings.data_dir,
-                        database_path=database_path,
-                    )
-                    if repair.vector_rows or repair.coding_rows:
-                        logger.info(
-                            "sdk_metadata_repair_completed mapped=%d vector=%d coding=%d",
-                            repair.mapped,
-                            repair.vector_rows,
-                            repair.coding_rows,
-                        )
-                except Exception as error:
-                    logger.warning(
-                        "sdk_metadata_repair_failed error_type=%s",
-                        type(error).__name__,
-                    )
+                # The metadata repair after a cutover reads every bundle: it is
+                # recovery work, so it runs after readiness (`recover_after_ready`).
                 app.state.memory_governance_store = RetiredGovernanceStore(database_path)
                 app.state.evidence_store = RetiredEvidenceStore(database_path)
             else:
@@ -921,8 +925,6 @@ def create_app(
                 extraction_settings=app.state.extraction_settings_store,
                 data_dir=runtime_settings.data_dir,
             )
-            if app.state.memory_authority is MemoryAuthority.SDK:
-                app.state.sdk_memory_runtime.start_raw_retention()
             # C2 owns the single production budget (handle 5s + reserve 250ms,
             # total 5.25s, lease 10s, renew 1s, claim 250ms). The composition
             # root only consumes it: no local formula, and the 250ms claim
@@ -1012,11 +1014,9 @@ def create_app(
                 source_claim_enabled=lambda source_id: _sedimentation_claim_enabled(app, source_id),
             )
             app.state.memory_write_drain = memory_write_drain
-            app.state.memory_write_drain_task = watched_task(
-                asyncio.get_running_loop(),
-                lambda: memory_write_drain.run_forever(),
-                name="one-memory-durable-write-drain",
-            )
+            # Started by `recover_after_ready`: a running drain claims jobs and
+            # holds the single writer, which the rest of startup still needs.
+            app.state.memory_write_drain_task = None
             # D52: every entry that already holds committed Evidence goes
             # through the one durable queue. The intake turns one record into
             # one complete-turn request; the drain stays the only consumer, so
@@ -1050,10 +1050,10 @@ def create_app(
                         priority=priority,
                     )
 
-            app.state.memory_note_store = MemoryNoteStore(
+            app.state.memory_addition_store = MemoryAdditionStore(
                 app.state.evidence_store,
                 (
-                    LegacyMemoryNoteReader(
+                    LegacyMemoryAdditionReader(
                         app.state.memory_task_store,
                         app.state.memory_governance_store,
                     )
@@ -1089,60 +1089,6 @@ def create_app(
                 sdk_authority=lambda: app.state.memory_authority is MemoryAuthority.SDK,
             )
             app.state.import_job_store.replace_never_published_snapshot_failures()
-            # A file's Evidence and its pending-dispatch row commit atomically,
-            # but the callback that turns them into a task runs after the
-            # transaction. A crash in that window leaves durable Evidence with
-            # no in-memory timer left to notice it; drain those rows once on
-            # startup through the same permission/debounce path as live work.
-            if (
-                runtime_settings.automatic_memory_processing
-                and app.state.memory_authority is MemoryAuthority.LEGACY
-            ):
-                # Two-phase, like the live runner: enumerate the file
-                # identities, read each without consuming its pending marker,
-                # await the durable submit, and only then consume. A crash or
-                # a failed/cancelled submit leaves the marker for the next
-                # startup instead of dropping the committed Evidence. The
-                # legacy `take_all_stable_records()` consumes while reading and
-                # is deliberately no longer the startup path.
-                for user_id, source_id, file_key in await asyncio.to_thread(
-                    app.state.evidence_store.list_pending_dispatch_files
-                ):
-                    try:
-                        for dispatch in await asyncio.to_thread(
-                            app.state.evidence_store.take_stable_file_dispatches,
-                            user_id=user_id,
-                            source_id=source_id,
-                            file_key=file_key,
-                        ):
-                            # Same intake as the live callback, so the crash
-                            # window between Evidence commit and durable submit
-                            # is closed by the same idempotent path rather than
-                            # a second one.
-                            token = live_sync_arrival.set(dispatch.priority == "live")
-                            try:
-                                await enqueue_stable_evidence(dispatch.record)
-                            finally:
-                                live_sync_arrival.reset(token)
-                    except Exception:
-                        # The submit did not succeed, so the pending marker is
-                        # deliberately left in place: the next startup will
-                        # replay this file. Startup continues for the other
-                        # files instead of failing the whole composition root.
-                        logger.warning(
-                            "stable_evidence_startup_replay_deferred source=%s file=%s",
-                            source_id,
-                            file_key,
-                            exc_info=True,
-                        )
-                        continue
-                    await asyncio.to_thread(
-                        app.state.evidence_store.consume_stable_file_records,
-                        user_id=user_id,
-                        source_id=source_id,
-                        file_key=file_key,
-                    )
-            app.state.import_supervisor.resume_interrupted()
             app.state.source_connection_store = SourceConnectionStore(
                 app.state.source_grant_store,
                 app.state.import_job_store,
@@ -1185,11 +1131,6 @@ def create_app(
             app.state.live_sync_supervisor.set_watched_sources(
                 watch_roots if watching and runtime_settings.live_sync_enabled else ()
             )
-            if runtime_settings.live_sync_enabled:
-                app.state.live_sync_supervisor.start()
-                if app.state.live_sync_watch is not None:
-                    app.state.live_sync_watch.start(prime=True)
-            await _reconcile_source_sync_from_config()
             # Taking up the memory work again — the tasks left unfinished, then
             # the conversations with no memory yet — reads every conversation
             # ever imported: 13.5 seconds on this machine's real database, and
@@ -1203,9 +1144,6 @@ def create_app(
             warm_bulk_pool()
             app.state.memory_backfill = None
             app.state.memory_visibility_task = None
-            if app.state.memory_authority is MemoryAuthority.LEGACY:
-                _start_backfill(app)
-                _start_visibility_recompute(app)
             # Both times the loop was blocked here it was found from outside,
             # by hand, days later. This says so at the time, and says what was
             # holding it.
@@ -1224,15 +1162,182 @@ def create_app(
             app.state.resource_diagnostics = watched_task(
                 asyncio.get_running_loop(), _emit_resource_snapshots
             )
+            # Readiness is "Core answers": the stores above are open and
+            # /health, recall and the library work. Everything below picks up
+            # work an earlier run left unfinished -- the post-cutover metadata
+            # repair, the durable write queue, interrupted imports, live sync,
+            # source reconcile. On a library with pending work that took longer
+            # than the Runtime's readiness budget, so the Runtime killed a
+            # healthy Core and the next one began the same recovery again. It
+            # now runs only after readiness, one step at a time, and a failed
+            # step is reported without taking readiness or the other steps
+            # with it.
+            app.state.recovery = "pending"
+            app.state.recovery_failed_steps = ()
+
+            async def recover_after_ready() -> None:
+                app.state.recovery = "running"
+                recovery_started = time.monotonic()
+                failed: list[str] = []
+
+                async def step(name: str, action: Callable[[], Awaitable[None]]) -> None:
+                    step_started = time.monotonic()
+                    try:
+                        await action()
+                    except asyncio.CancelledError:
+                        raise
+                    except Exception as error:
+                        failed.append(name)
+                        app.state.recovery_failed_steps = tuple(failed)
+                        logger.warning(
+                            "core_recovery_step_failed step=%s error_type=%s",
+                            name,
+                            type(error).__name__,
+                        )
+                        diagnostic_event(
+                            level="warn",
+                            component="core.recovery",
+                            event="core.recovery_step_failed",
+                            outcome="failed",
+                            error_type=type(error).__name__,
+                            duration_ms=elapsed_ms(step_started),
+                            details={"phase": name},
+                        )
+
+                async def repair_sdk_metadata() -> None:
+                    from one_memory.hy_sdk_migration import (
+                        repair_sdk_metadata_from_bundle,
+                    )
+
+                    repair = await asyncio.to_thread(
+                        repair_sdk_metadata_from_bundle,
+                        data_dir=runtime_settings.data_dir,
+                        database_path=database_path,
+                    )
+                    if repair.vector_rows or repair.coding_rows:
+                        logger.info(
+                            "sdk_metadata_repair_completed mapped=%d vector=%d coding=%d",
+                            repair.mapped,
+                            repair.vector_rows,
+                            repair.coding_rows,
+                        )
+
+                async def start_write_drain() -> None:
+                    app.state.memory_write_drain_task = watched_task(
+                        asyncio.get_running_loop(),
+                        lambda: memory_write_drain.run_forever(),
+                        name="one-memory-durable-write-drain",
+                    )
+
+                async def start_raw_retention() -> None:
+                    app.state.sdk_memory_runtime.start_raw_retention()
+
+                async def replay_pending_dispatch() -> None:
+                    # A file's Evidence and its pending-dispatch row commit atomically,
+                    # but the callback that turns them into a task runs after the
+                    # transaction. A crash in that window leaves durable Evidence with
+                    # no in-memory timer left to notice it; drain those rows once on
+                    # startup through the same permission/debounce path as live work.
+                    if (
+                        runtime_settings.automatic_memory_processing
+                        and app.state.memory_authority is MemoryAuthority.LEGACY
+                    ):
+                        # Two-phase, like the live runner: enumerate the file
+                        # identities, read each without consuming its pending marker,
+                        # await the durable submit, and only then consume. A crash or
+                        # a failed/cancelled submit leaves the marker for the next
+                        # startup instead of dropping the committed Evidence. The
+                        # legacy `take_all_stable_records()` consumes while reading and
+                        # is deliberately no longer the startup path.
+                        for user_id, source_id, file_key in await asyncio.to_thread(
+                            app.state.evidence_store.list_pending_dispatch_files
+                        ):
+                            try:
+                                for dispatch in await asyncio.to_thread(
+                                    app.state.evidence_store.take_stable_file_dispatches,
+                                    user_id=user_id,
+                                    source_id=source_id,
+                                    file_key=file_key,
+                                ):
+                                    # Same intake as the live callback, so the crash
+                                    # window between Evidence commit and durable submit
+                                    # is closed by the same idempotent path rather than
+                                    # a second one.
+                                    token = live_sync_arrival.set(dispatch.priority == "live")
+                                    try:
+                                        await enqueue_stable_evidence(dispatch.record)
+                                    finally:
+                                        live_sync_arrival.reset(token)
+                            except Exception:
+                                # The submit did not succeed, so the pending marker is
+                                # deliberately left in place: the next startup will
+                                # replay this file. Startup continues for the other
+                                # files instead of failing the whole composition root.
+                                logger.warning(
+                                    "stable_evidence_startup_replay_deferred source=%s file=%s",
+                                    source_id,
+                                    file_key,
+                                    exc_info=True,
+                                )
+                                continue
+                            await asyncio.to_thread(
+                                app.state.evidence_store.consume_stable_file_records,
+                                user_id=user_id,
+                                source_id=source_id,
+                                file_key=file_key,
+                            )
+
+                async def resume_imports() -> None:
+                    app.state.import_supervisor.resume_interrupted()
+
+                async def start_live_sync() -> None:
+                    if runtime_settings.live_sync_enabled:
+                        app.state.live_sync_supervisor.start()
+                        if app.state.live_sync_watch is not None:
+                            app.state.live_sync_watch.start(prime=True)
+
+                async def start_legacy_catch_up() -> None:
+                    _start_backfill(app)
+                    _start_visibility_recompute(app)
+
+                # Yield once first so the HTTP server finishes binding before
+                # any of this asks the loop for time.
+                await asyncio.sleep(0)
+                try:
+                    sdk = app.state.memory_authority is MemoryAuthority.SDK
+                    if sdk:
+                        # Before the drain: the repair restores metadata the
+                        # queued writes are read back against.
+                        await step("sdk_metadata_repair", repair_sdk_metadata)
+                    await step("write_drain", start_write_drain)
+                    if sdk:
+                        await step("raw_retention", start_raw_retention)
+                    else:
+                        await step("pending_dispatch_replay", replay_pending_dispatch)
+                    await step("import_resume", resume_imports)
+                    await step("live_sync", start_live_sync)
+                    await step("source_reconcile", _reconcile_source_sync_from_config)
+                    if not sdk:
+                        await step("legacy_catch_up", start_legacy_catch_up)
+                finally:
+                    # Startup writes are done. Only now let the derived-content
+                    # rebuild take the single write checkout: it is a long
+                    # background job, and on a large library it would otherwise
+                    # hold the writer while the recovery above still needs it
+                    # (ISSUE-CONTENT-BACKFILL-BLOCKS-STARTUP).
+                    app.state.memory_governance_store.release_content_backfill_startup_gate()
+                app.state.recovery = "failed" if failed else "done"
+                diagnostic_event(
+                    level="warn" if failed else "info",
+                    component="core.recovery",
+                    event="core.recovery_finished",
+                    outcome="failed" if failed else "succeeded",
+                    duration_ms=elapsed_ms(recovery_started),
+                    details={"count": len(failed)},
+                )
+
+            app.state.recovery_task = None
             try:
-                # Startup writes are done. Only now let the derived-content
-                # rebuild take the single write checkout: it is a long
-                # background job, and on a large library it would otherwise
-                # hold the writer while the store initializations above still
-                # need it, so startup would wait out the write budget and fail
-                # with `database is locked`
-                # (ISSUE-CONTENT-BACKFILL-BLOCKS-STARTUP).
-                app.state.memory_governance_store.release_content_backfill_startup_gate()
                 diagnostic_event(
                     level="info",
                     component="core.lifecycle",
@@ -1241,6 +1346,11 @@ def create_app(
                     instance_id=runtime_settings.instance_id,
                     duration_ms=elapsed_ms(lifecycle_started),
                 )
+                app.state.recovery_task = watched_task(
+                    asyncio.get_running_loop(),
+                    recover_after_ready,
+                    name="one-memory-post-ready-recovery",
+                )
                 yield
             finally:
                 shutdown_started = time.monotonic()
@@ -1251,6 +1361,14 @@ def create_app(
                     outcome="started",
                     instance_id=runtime_settings.instance_id,
                 )
+                # First: recovery may be about to start what is stopped below.
+                if app.state.recovery_task is not None:
+                    app.state.recovery_task.cancel()
+                    with suppress(asyncio.CancelledError):
+                        await app.state.recovery_task
+                # Cancelled before it got that far, recovery never let the
+                # rebuild go; a held rebuild would hold shutdown below too.
+                app.state.memory_governance_store.release_content_backfill_startup_gate()
                 app.state.main_database_report.cancel()
                 app.state.loop_heartbeat.cancel()
                 with suppress(asyncio.CancelledError):
@@ -1278,8 +1396,9 @@ def create_app(
                 await app.state.live_sync_supervisor.shutdown()
                 await app.state.import_supervisor.shutdown()
                 app.state.memory_write_drain.stop()
-                with suppress(asyncio.CancelledError):
-                    await app.state.memory_write_drain_task
+                if app.state.memory_write_drain_task is not None:
+                    with suppress(asyncio.CancelledError):
+                        await app.state.memory_write_drain_task
                 await app.state.sdk_memory_runtime.shutdown()
                 await app.state.sdk_write_coordinator.close()
                 if app.state.sdk_client_handle is not None:
@@ -1341,7 +1460,7 @@ def create_app(
         Depends(local_api_guard(runtime_settings, valid_ui_session=ui_session_valid)),
         Depends(require_external_endpoint),
     ]
-    app.include_router(memory_note_router(protected))
+    app.include_router(memory_add_router(protected))
     app.include_router(file_import_router(protected))
     app.include_router(sdk_context_router(protected))
 
@@ -1497,6 +1616,8 @@ def create_app(
             content_candidate_backfill_failure=(
                 governance.content_candidate_backfill_failure() if governance is not None else None
             ),
+            recovery=getattr(app.state, "recovery", "pending"),
+            recovery_failed_steps=getattr(app.state, "recovery_failed_steps", ()),
         )
 
     @app.get("/health", response_model=HealthResponse, include_in_schema=False)
@@ -2733,8 +2854,24 @@ def create_app(
         source: str | None = Query(default=None, min_length=1),
         query: str | None = Query(default=None, max_length=512),
         offset: int = Query(default=0, ge=0),
-        limit: int = Query(default=100, ge=1, le=500),
+        limit: int = Query(default=LIBRARY_PAGE_SIZE, ge=1, le=500),
+        window_id: str | None = Query(default=None, min_length=1, max_length=64),
+        scene: Literal["all", "chat", "working", "coding"] = Query(default="all"),
     ) -> HySdkMemoryPage:
+        """One page of memories across chat, working and coding.
+
+        Without `query`: `list_memories(scene="all")`, newest update first;
+        `total` is the SDK's count across the three scenes. `scene` narrows
+        the page to one scene: chat lists the chat store, working/coding list
+        that scene's experiences (the SDK lists experiences only, all active).
+
+        With `query`: keyword search over one SDK relevance window (see
+        `_library_search_page`). The first request (no `window_id`) searches
+        and returns a `window_id`; later pages pass it back with their offset
+        and are cut from the same matches, so pages never overlap or skip. A
+        `window_id` that expired or was searched with other filters searches
+        again and answers page 1 with `window_reset: true`.
+        """
         try:
             client = await _sdk_client_handle(app).client()
             search_query = (query or "").strip()
@@ -2744,59 +2881,26 @@ def create_app(
                         status_code=422,
                         detail="sdk_search_supports_active_status_only",
                     )
-                # SDK search has no count-only contract and, on the local store,
-                # no keyword channel. Ask for one bounded relevance window with
-                # no score floor, then keep the rows that contain the words, so
-                # a word in the library is found and a word in none of it finds
-                # nothing. The whole library is never listed in Core.
-                # A larger window made one search take long enough to freeze
-                # the page; 20 is the bounded window the library searches.
-                fetch = 20
-                search_raw = await asyncio.to_thread(
-                    client.search,
-                    search_query,
-                    user_ids=["local"],
-                    agent_ids=[],
-                    include_sources=[source] if source else None,
-                    limit=fetch,
-                    min_score=0.0,
-                    schema_min_score=0.0,
-                    schema_limit=fetch,
-                    # The library lists stored memories; proactive intentions
-                    # are a recall-time lane the list never shows.
-                    intention_limit=0,
-                    scene="normal",
-                    reader=HY_MEMORY_READER,
-                )
-                hit_ids, window = library_keyword_hits(search_raw, search_query)
-                rows = await _get_sdk_rows(client, list(hit_ids[offset : offset + limit]))
-                memories: list[HySdkMemoryRecord] = []
-                skipped = 0
-                for row in rows:
-                    if row is None:
-                        continue
-                    try:
-                        record = HySdkMemoryRecord.from_sdk(row)
-                    except HySdkReadError:
-                        skipped += 1
-                        continue
-                    if record.status == "active":
-                        memories.append(record)
-                _log_skipped_sdk_memories(skipped)
-                return HySdkMemoryPage(
-                    memories=tuple(memories),
-                    total=len(hit_ids),
-                    limit=limit,
+                return await _library_search_page(
+                    app,
+                    client,
+                    query=search_query,
+                    source=source,
+                    statuses=list(statuses),
                     offset=offset,
-                    search_window=fetch if window >= fetch else None,
+                    limit=limit,
+                    window_id=window_id,
+                    scene=scene,
                 )
             raw = await asyncio.to_thread(
                 client.list_memories,
                 user_id="local",
+                scene=scene,
                 statuses=list(statuses),
                 include_sources=[source] if source else None,
                 offset=offset,
                 limit=limit,
+                order="desc",
             )
             page, skipped = HySdkMemoryPage.from_sdk_skipping_invalid(
                 raw, limit=limit, offset=offset
@@ -2964,9 +3068,18 @@ def create_app(
         response_model=HySdkMemoryRecord,
         dependencies=protected,
     )
-    async def get_sdk_memory(memory_id: str) -> HySdkMemoryRecord:
+    async def get_sdk_memory(
+        memory_id: str,
+        kind: SdkMemoryKind | None = None,
+        variant: SdkMemoryVariant | None = None,
+    ) -> HySdkMemoryRecord:
+        _check_memory_namespace(kind, variant)
         try:
-            memory = await _get_sdk_memory(_sdk_client_handle(app), memory_id)
+            memory = await _get_sdk_memory(
+                _sdk_client_handle(app), memory_id, kind=kind, variant=variant
+            )
+        except AmbiguousMemoryIdError:
+            raise HTTPException(status_code=409, detail="memory_id_ambiguous") from None
         except Exception as error:
             raise _sdk_http_error(error, "hy_memory_get_failed") from None
         if memory is None:
@@ -2982,13 +3095,40 @@ def create_app(
         memory_id: str,
         request: SdkMemoryUpdateRequest,
     ) -> HySdkMemoryRecord:
+        _check_memory_namespace(request.kind, request.variant)
+        if request.task is not None and request.kind in {"chat", "fact"}:
+            raise HTTPException(status_code=422, detail="memory_task_requires_experience")
+        namespace = _namespace_kwargs(request.kind, request.variant)
         try:
             client = await app.state.sdk_write_coordinator.client()
-            result = await asyncio.to_thread(client.update, memory_id, request.content)
-            if not isinstance(result, dict) or result.get("success") is not True:
+            update_kwargs: dict[str, object] = dict(namespace)
+            if request.task is not None:
+                update_kwargs["task"] = request.task
+            result = await asyncio.to_thread(
+                client.update, memory_id, request.content, **update_kwargs
+            )
+            if not isinstance(result, dict):
                 raise HySdkError("hy_memory_update_rejected")
-            raw = await asyncio.to_thread(client.get, memory_id)
+            if result.get("success") is not True:
+                if "not found" in str(result.get("error_message") or ""):
+                    raise HTTPException(status_code=404, detail="memory_not_found")
+                raise HySdkError("hy_memory_update_rejected")
+            # The SDK names the namespace it wrote; read that one back.
+            if result.get("kind") in {"experience", "fact"}:
+                namespace = {"kind": result["kind"]}
+                if result.get("variant") in {"working", "coding"}:
+                    namespace["variant"] = result["variant"]
+            raw = await asyncio.to_thread(client.get, memory_id, **namespace)
             memory = None if raw is None else HySdkMemoryRecord.from_sdk(raw)
+        except HTTPException:
+            raise
+        except AmbiguousMemoryIdError:
+            raise HTTPException(status_code=409, detail="memory_id_ambiguous") from None
+        except ValueError as error:
+            if request.task is None:
+                raise _sdk_http_error(error, "hy_memory_update_failed") from None
+            # The SDK refuses `task` for anything but an experience.
+            raise HTTPException(status_code=422, detail="memory_task_requires_experience") from None
         except Exception as error:
             raise _sdk_http_error(error, "hy_memory_update_failed") from None
         if memory is None:
@@ -3000,10 +3140,17 @@ def create_app(
         status_code=204,
         dependencies=protected,
     )
-    async def delete_sdk_memory(memory_id: str) -> Response:
+    async def delete_sdk_memory(
+        memory_id: str,
+        kind: SdkMemoryKind | None = None,
+        variant: SdkMemoryVariant | None = None,
+    ) -> Response:
+        _check_memory_namespace(kind, variant)
         try:
             client = await app.state.sdk_write_coordinator.client()
-            result = await asyncio.to_thread(client.delete, memory_id)
+            result = await asyncio.to_thread(
+                client.delete, memory_id, **_namespace_kwargs(kind, variant)
+            )
             if not isinstance(result, dict):
                 raise HySdkError("hy_memory_delete_rejected")
             error_code = result.get("error_code")
@@ -3011,6 +3158,8 @@ def create_app(
                 raise HySdkError(str(error_code or "hy_memory_delete_incomplete"))
             if result.get("success") is not True and result.get("deleted_count") != 0:
                 raise HySdkError("hy_memory_delete_rejected")
+        except AmbiguousMemoryIdError:
+            raise HTTPException(status_code=409, detail="memory_id_ambiguous") from None
         except Exception as error:
             raise _sdk_http_error(error, "hy_memory_delete_failed") from None
         return Response(status_code=204)
@@ -3137,6 +3286,7 @@ def create_app(
         http_request: Request,
     ) -> RecallReceipt:
         from one_memory.call_event_recorder import record_legacy_result
+        from one_memory.recall_fallback import recall_with_fallback
 
         started = time.monotonic()
         await _require_external_recall_scope(
@@ -3144,7 +3294,16 @@ def create_app(
         )
         target = _recall_target(app)
         access = external_access(http_request.headers)
-        receipt = await target.recall_async(request)
+        receipt = await recall_with_fallback(
+            request,
+            model_ready=lambda: _recall_model_ready(app),
+            recall_memories=target.recall_async,
+            has_memories=lambda: _library_has_memories(app),
+            raw_sources=lambda: _recall_raw_sources(app, request, access, started),
+            search_raw=lambda query, limit, sources: _search_sdk_raw(
+                app, query, limit=limit, sources=sources
+            ),
+        )
         event_store = getattr(app.state, "call_event_store", None)
         if event_store is not None and request.query != "__om_probe__":
             try:
@@ -4204,6 +4363,100 @@ def _sdk_memory_runtime(app: FastAPI) -> SdkMemoryRuntime:
     )
 
 
+async def _recall_model_ready(app: FastAPI) -> bool:
+    """A generation model is configured and usable, so memories can exist."""
+    try:
+        profile = await asyncio.to_thread(_model_profile_store(app).active, _secret_store(app))
+    except Exception:
+        return False
+    return profile is not None and bool(profile.capabilities.model_available)
+
+
+async def _library_has_memories(app: FastAPI) -> bool:
+    """Any active memory at all. Asked only after an empty memory search."""
+    try:
+        client = await _sdk_client_handle(app).client()
+        raw = await asyncio.to_thread(
+            client.list_memories,
+            user_id="local",
+            statuses=["active"],
+            limit=1,
+            offset=0,
+            order="desc",
+        )
+        page, _ = HySdkMemoryPage.from_sdk_skipping_invalid(raw, limit=1, offset=0)
+    except Exception:
+        # Unknown is not "empty": keep the memory answer rather than guess.
+        return True
+    return page.total > 0
+
+
+async def _recall_raw_sources(
+    app: FastAPI,
+    request: RecallRequest,
+    access: ExternalMemoryAccess | None,
+    started: float,
+) -> frozenset[str] | None:
+    """The raw sources this caller may read: the `/context` raw-lane rule.
+
+    Recall's own grant does not cover original conversations. A host reads
+    them only with `om_conversations` and its granted, unrevoked sources; a
+    trusted local caller reads every source.
+    """
+    if access is None:
+        return None
+    from one_memory.context_access import resolve_context_authority
+    from one_memory.context_models import ContextSearchRequest
+
+    query = ContextSearchRequest(
+        query=request.query,
+        kinds=("raw",),
+        limit=request.limit,
+        character_budget=request.character_budget,
+        timeout_ms=request.timeout_ms,
+    )
+    try:
+        authority = await asyncio.to_thread(
+            resolve_context_authority,
+            query,
+            access,
+            _evidence_store(app).database_path,
+            deadline=started + request.timeout_ms / 1_000,
+        )
+    except (HTTPException, TimeoutError):
+        return frozenset()
+    if not authority.raw_allowed:
+        return frozenset()
+    return frozenset(authority.raw_sources or ())
+
+
+async def _search_sdk_raw(
+    app: FastAPI,
+    query: str,
+    *,
+    limit: int,
+    sources: frozenset[str] | None,
+) -> tuple[HySdkRawHit, ...]:
+    """The imported conversations nearest the query: the SDK raw layer."""
+    client = await _sdk_client_handle(app).client()
+    raw = await asyncio.to_thread(
+        client.search,
+        query,
+        user_ids=["local"],
+        agent_ids=[],
+        include_sources=sorted(sources) if sources else None,
+        limit=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"],
+    )
+    return parse_sdk_raw_search(raw)
+
+
 def _sdk_client_handle(app: FastAPI) -> SdkClientHandle:
     handle = cast(SdkClientHandle | None, app.state.sdk_client_handle)
     if handle is None:
@@ -4226,25 +4479,143 @@ def _log_skipped_sdk_memories(count: int) -> None:
 _SDK_GET_CONCURRENCY = 8
 
 
-async def _get_sdk_rows(client: Any, memory_ids: list[str]) -> list[object]:
+async def _get_sdk_rows(client: Any, hits: list[LibraryHit]) -> list[object]:
     gate = asyncio.Semaphore(_SDK_GET_CONCURRENCY)
 
-    async def one(memory_id: str) -> object:
+    async def one(hit: LibraryHit) -> object:
         async with gate:
-            return await asyncio.to_thread(client.get, memory_id)
+            # Name the namespace the search found the row in, so an id that
+            # also exists elsewhere cannot make the read ambiguous.
+            return await asyncio.to_thread(
+                client.get, hit.memory_id, **_namespace_kwargs(hit.kind, hit.variant)
+            )
 
-    return list(await asyncio.gather(*(one(memory_id) for memory_id in memory_ids)))
+    return list(await asyncio.gather(*(one(hit) for hit in hits)))
 
 
 async def _get_sdk_memory(
     handle: SdkClientHandle,
     memory_id: str,
+    *,
+    kind: str | None = None,
+    variant: str | None = None,
 ) -> HySdkMemoryRecord | None:
     client = await handle.client()
-    raw = await asyncio.to_thread(client.get, memory_id)
+    raw = await asyncio.to_thread(client.get, memory_id, **_namespace_kwargs(kind, variant))
     return None if raw is None else HySdkMemoryRecord.from_sdk(raw)
 
 
+def _namespace_kwargs(kind: str | None, variant: str | None) -> dict[str, str]:
+    """The SDK's kind/variant arguments, only the ones the caller gave."""
+    namespace: dict[str, str] = {}
+    if kind is not None:
+        namespace["kind"] = kind
+    if variant is not None:
+        namespace["variant"] = variant
+    return namespace
+
+
+def _check_memory_namespace(kind: str | None, variant: str | None) -> None:
+    if kind == "chat" and variant is not None:
+        raise HTTPException(status_code=422, detail="memory_variant_requires_productivity_kind")
+
+
+# Keyword search reads one SDK relevance window this large, once per window.
+LIBRARY_SEARCH_WINDOW = 200
+# The memory panel's page size; the API still accepts 1..500 for the CLI.
+LIBRARY_PAGE_SIZE = 20
+
+
+def _library_search_windows(app: FastAPI) -> LibrarySearchWindows:
+    windows = getattr(app.state, "library_search_windows", None)
+    if windows is None:
+        windows = LibrarySearchWindows()
+        app.state.library_search_windows = windows
+    return cast(LibrarySearchWindows, windows)
+
+
+async def _library_search_page(
+    app: FastAPI,
+    client: Any,
+    *,
+    query: str,
+    source: str | None,
+    statuses: list[str],
+    offset: int,
+    limit: int,
+    window_id: str | None,
+    scene: str = "all",
+) -> HySdkMemoryPage:
+    """One page of a keyword search, cut from a cached result window.
+
+    SDK search has no count-only contract and, on the local store, no keyword
+    channel. The search asks once for a bounded relevance window across chat,
+    working and coding (no reranking, no score floor), keeps the rows that
+    contain every word, and caches those matches under a `window_id`. Every
+    page of that search is a slice of the same matches, read fresh from the
+    SDK so edits and deletes show. The whole library is never listed in Core.
+    """
+    windows = _library_search_windows(app)
+    key = window_key(query, source, statuses, scene)
+    window = windows.get(window_id, key) if window_id else None
+    window_reset = window_id is not None and window is None
+    if window is None:
+        fetch = LIBRARY_SEARCH_WINDOW
+        search_raw = await asyncio.to_thread(
+            client.search,
+            query,
+            scene="all",
+            rerank=False,
+            user_ids=["local"],
+            agent_ids=[],
+            include_sources=[source] if source else None,
+            limit=fetch,
+            min_score=0.0,
+            working_fact_min_score=0.0,
+            working_experience_min_score=0.0,
+            schema_min_score=0.0,
+            schema_limit=fetch,
+            # The library lists stored memories; proactive intentions are a
+            # recall-time lane the list never shows.
+            intention_limit=0,
+            reader=HY_MEMORY_READER,
+        )
+        hits, held = library_keyword_hits(search_raw, query)
+        if scene != "all":
+            # One scene: keep that scene's matches from the same fused window.
+            hits = tuple(
+                hit
+                for hit in hits
+                if (hit.kind == "chat" if scene == "chat" else hit.variant == scene)
+            )
+        window = windows.put(key, hits, fetch if held >= fetch else None)
+        if window_reset:
+            offset = 0
+    rows = await _get_sdk_rows(client, list(window.hits[offset : offset + limit]))
+    memories: list[HySdkMemoryRecord] = []
+    skipped = 0
+    for row in rows:
+        if row is None:
+            continue
+        try:
+            record = HySdkMemoryRecord.from_sdk(row)
+        except HySdkReadError:
+            skipped += 1
+            continue
+        if record.status == "active":
+            memories.append(record)
+    _log_skipped_sdk_memories(skipped)
+    return HySdkMemoryPage(
+        memories=tuple(memories),
+        total=len(window.hits),
+        limit=limit,
+        offset=offset,
+        search_window=window.search_window,
+        window_id=window.window_id,
+        window_reset=window_reset,
+    )
+
+
 async def _search_sdk_memories(
     handle: SdkClientHandle,
     query: str,

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

@@ -187,8 +187,9 @@ def record_legacy_result(
             host_session_id=None,
             injection_elapsed_ms=None,
             elapsed_ms=elapsed_ms,
-            raw_count=0,
-            memory_count=len(receipt.hits),
+            # A raw-fallback recall returned conversation excerpts, not memories.
+            raw_count=len(receipt.hits) if receipt.mode == "raw" else 0,
+            memory_count=0 if receipt.mode == "raw" else len(receipt.hits),
             references=(),
         )
     )

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

@@ -314,6 +314,10 @@ def sdk_migrate(options: Sequence[str], stream: TextIO) -> int:
         details={
             "runtime_build": runtime_build,
             "confirmed": confirmed,
+            # The Runtime the upgrade replaced, as the orchestrator read it
+            # from that Runtime's install manifest; never guessed.
+            "source_version": _migration_source("ONE_MEMORY_MIGRATION_SOURCE_VERSION"),
+            "source_build": _migration_source("ONE_MEMORY_MIGRATION_SOURCE_BUILD"),
             **authority_snapshot(database_path),
         },
     )
@@ -340,7 +344,13 @@ def sdk_migrate(options: Sequence[str], stream: TextIO) -> int:
         _write_restore(stream, as_json, document, "预览通过；加 --yes 后执行迁移。")
         return 4
 
-    from one_memory.hy_runtime_config import HY_MEMORY_NAMESPACE, HY_MEMORY_VERSION
+    from one_memory.hy_runtime_config import (
+        HY_MEMORY_NAMESPACE,
+        HY_MEMORY_VERSION,
+        configure_hy_runtime_environment,
+    )
+
+    configure_hy_runtime_environment(settings.data_dir)
     from one_memory.sdk_migration_runner import run_startup_migration
 
     step_names = {
@@ -380,6 +390,7 @@ def sdk_migrate(options: Sequence[str], stream: TextIO) -> int:
             stream.write(f"{step_names.get(step, step)}\n")
         stream.flush()
 
+    restore: dict[str, object] = {}
     try:
         with _migration_lock(settings.data_dir):
             result = run_startup_migration(
@@ -388,6 +399,7 @@ def sdk_migrate(options: Sequence[str], stream: TextIO) -> int:
                 sdk_version=HY_MEMORY_VERSION,
                 namespace=HY_MEMORY_NAMESPACE,
                 progress=progress,
+                restore_report=restore,
             )
     except Exception as error:
         from one_memory.sdk_migration_verify import MemoryReadbackFailed
@@ -396,6 +408,10 @@ def sdk_migrate(options: Sequence[str], stream: TextIO) -> int:
         failed: dict[str, object] = {"schema_version": 1, "state": "failed", "code": code}
         if isinstance(error, MemoryReadbackFailed):
             failed["readback"] = error.report.as_document()
+        # The migration's own code stays the result; the restore is secondary.
+        failed["data_restored"] = restore.get("state") == "restored"
+        if restore.get("state") == "failed":
+            failed["restore_code"] = restore.get("code")
         write_migration_log(
             settings.data_dir,
             writer="core-sdk-migrate",
@@ -411,10 +427,13 @@ def sdk_migrate(options: Sequence[str], stream: TextIO) -> int:
                 "code_is_fallback": code == "sdk_migration_preflight_failed"
                 and not _names_code(error, code),
                 **({"readback": failed["readback"]} if "readback" in failed else {}),
+                "restore": restore.get("state", "not_attempted"),
+                **({"restore_code": restore["code"]} if "code" in restore else {}),
                 **authority_snapshot(database_path),
             },
         )
-        _write_restore(stream, as_json, failed, f"迁移未完成：{code}")
+        restored_text = "；数据已恢复到升级前的状态" if failed["data_restored"] else ""
+        _write_restore(stream, as_json, failed, f"迁移未完成：{code}{restored_text}")
         return 1
     document = result.as_document()
     write_migration_log(
@@ -440,6 +459,14 @@ def sdk_migrate(options: Sequence[str], stream: TextIO) -> int:
     return 0
 
 
+_SAFE_SOURCE = re.compile(r"^[0-9A-Za-z][0-9A-Za-z.+\-]{0,63}$")
+
+
+def _migration_source(name: str) -> str:
+    value = os.environ.get(name, "").strip()
+    return value if _SAFE_SOURCE.fullmatch(value) else "unknown"
+
+
 @contextlib.contextmanager
 def _migration_lock(data_dir: Path) -> Iterator[None]:
     """One `sdk-migrate` per home at a time.
@@ -539,8 +566,18 @@ def _sdk_migration_status(options: Sequence[str], stream: TextIO) -> int:
     as_json = "--json" in options
     settings = load_settings()
     database_path = settings.data_dir / "one-memory.sqlite3"
-    if not database_path.is_file():
+    from one_memory.sdk_migration_restore import restore_pending
+
+    if restore_pending(settings.data_dir):
+        # A restore was killed between its renames; the database may be
+        # elsewhere. Only `sdk-migrate` may finish it.
         document: dict[str, object] = {
+            "schema_version": 1,
+            "authority": "legacy",
+            "state": "required",
+        }
+    elif not database_path.is_file():
+        document = {
             "schema_version": 1,
             "authority": "sdk",
             "state": "not_required",
@@ -613,8 +650,22 @@ def _refuse_unmigrated_home(data_dir: Path) -> None:
     """
     from one_memory.sdk_data_plane_migration import MemoryAuthority, SdkDataPlaneMigrationStore
     from one_memory.sdk_migration_log import authority_snapshot, write_migration_log
+    from one_memory.sdk_migration_restore import restore_pending
 
     database_path = data_dir / "one-memory.sqlite3"
+    if restore_pending(data_dir):
+        # A killed restore may have moved the database aside: serving now
+        # would create an empty home over the user's data.
+        write_migration_log(
+            data_dir,
+            writer="core-startup",
+            event="core.refused_legacy",
+            outcome="refused",
+            code="sdk_migration_required",
+            details={"stage": "serve_entry", "restore_pending": True},
+        )
+        print("sdk_migration_required", file=sys.stderr, flush=True)
+        raise SystemExit(SDK_MIGRATION_REQUIRED_EXIT)
     if not database_path.is_file():
         return
     try:
@@ -650,6 +701,7 @@ def serve(*, maintenance: bool = False) -> None:
     from one_memory.diagnostic_log import configure_diagnostics, diagnostic_event
     from one_memory.hy_runtime_config import (
         apply_diagnostic_log_level,
+        configure_hy_runtime_environment,
         diagnostic_log_level,
     )
     from one_memory.log_file import start_logging_to_file
@@ -657,10 +709,15 @@ def serve(*, maintenance: bool = False) -> None:
     from one_memory.runtime import CoreRuntime, parent_pid
 
     settings = load_settings()
-    from one_memory.api import create_app
-
     if not maintenance:
         _refuse_unmigrated_home(settings.data_dir)
+    # HY resolves some trace paths at import time and its pipeline path when
+    # SharedRuntime starts. Bind both to the MemHub root before importing the
+    # application graph; otherwise HY falls back to ~/.hy_memory while the
+    # desktop Debug panel watches the managed data directory.
+    configure_hy_runtime_environment(settings.data_dir)
+    from one_memory.api import create_app
+
     start_logging_to_file(settings.data_dir)
     apply_diagnostic_log_level(diagnostic_log_level(settings.data_dir))
     configure_diagnostics(

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

@@ -227,7 +227,7 @@ def _trailing_user_turn_is_open(turn: list[EvidenceRecord]) -> bool:
     return (
         _opens_turn(opener)
         and opener.content_kind is EvidenceContentKind.RAW_CONVERSATION
-        and not _is_memory_note(opener)
+        and not _is_hand_added_memory(opener)
     )
 
 
@@ -254,7 +254,7 @@ def _is_hy_input_turn(record: EvidenceRecord) -> bool:
     return _HOST_ENVELOPE.search(source[:2_000]) is None
 
 
-def _is_memory_note(record: EvidenceRecord) -> bool:
+def _is_hand_added_memory(record: EvidenceRecord) -> bool:
     meta = record.origin_meta.get(EvidenceOrigin.MANUAL_IMPORT)
     return (
         record.source_id == "one-memory-manual"

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

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

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

@@ -326,13 +326,9 @@ def _repair_vector(
     directory = data_dir / "hy-memory" / HY_MEMORY_NAMESPACE / "vector"
     if not (directory / "chroma.sqlite3").is_file():
         return 0
-    import chromadb
-    from chromadb.config import Settings
+    from one_memory.sdk_vector_reattach import open_offline_chroma
 
-    client = chromadb.PersistentClient(
-        path=str(directory),
-        settings=Settings(anonymized_telemetry=False),
-    )
+    client = open_offline_chroma(directory)
     # The SDK client is not open yet (startup has not created its handle), so
     # this is the only writer; release the store before the SDK takes it.
     try:

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

@@ -17,6 +17,9 @@ from pathlib import Path
 from typing import Any, ClassVar
 
 from hy_memory import (  # type: ignore[import-untyped]
+    AmbiguousMemoryIdError as AmbiguousMemoryIdError,  # re-export for api.py
+)
+from hy_memory import (
     HyMemoryClient,
     MemoryConfig,
     SharedRuntime,

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

@@ -3,6 +3,8 @@
 from __future__ import annotations
 
 from collections.abc import Mapping
+from datetime import UTC, datetime
+from typing import Literal, NamedTuple, cast
 
 from pydantic import BaseModel, ConfigDict, Field
 
@@ -29,7 +31,21 @@ class HySdkReadError(HySdkError):
     """A public SDK read operation failed or returned an invalid shape."""
 
 
+MemoryScene = Literal["chat", "working", "coding"]
+MemoryKindName = Literal["chat", "experience", "fact"]
+MemoryVariantName = Literal["working", "coding"]
+
+
 class HySdkMemoryRecord(BaseModel):
+    """One memory of any scene, in the unified shape the library lists.
+
+    Chat memories keep every field they always had. Working/coding memories
+    (experiences and facts) carry ``scene``/``kind``/``variant`` so a client
+    can open, edit and delete them again without guessing the namespace; an
+    experience also keeps ``task`` and ``solution`` apart, and ``content`` is
+    the readable ``task\nsolution`` text the SDK lists.
+    """
+
     model_config = ConfigDict(frozen=True, extra="forbid")
 
     memory_id: str
@@ -48,17 +64,36 @@ class HySdkMemoryRecord(BaseModel):
     source: str | None = None
     memory_at: int | None = None
     gmt_created: int | None = None
+    scene: MemoryScene = "chat"
+    kind: MemoryKindName = "chat"
+    # The productivity namespace ("working" | "coding"); None for chat. Pass it
+    # back with `kind` on get/update/delete.
+    variant: MemoryVariantName | None = None
+    task: str | None = None
+    solution: str | None = None
+    # Epoch seconds. `updated_at` falls back to `created_at`.
+    created_at: int | None = None
+    updated_at: int | None = None
 
     @classmethod
     def from_sdk(cls, raw: object) -> HySdkMemoryRecord:
         if not isinstance(raw, Mapping):
             raise HySdkReadError("hy_memory_record_shape_unknown")
+        if raw.get("kind") in {"experience", "fact"}:
+            return cls._from_productivity(raw)
         if any(
             not isinstance(raw.get(key), str) or not str(raw[key]).strip()
             for key in ("memory_id", "content")
         ):
             raise HySdkReadError("hy_memory_record_shape_unknown")
         try:
+            gmt_created = (
+                raw.get("gmt_created") if isinstance(raw.get("gmt_created"), int) else None
+            )
+            created_at = _epoch(raw.get("created_at"))
+            if created_at is None:
+                created_at = gmt_created
+            updated_at = _epoch(raw.get("updated_at"))
             return cls(
                 memory_id=str(raw["memory_id"]),
                 content=str(raw["content"]),
@@ -77,9 +112,69 @@ class HySdkMemoryRecord(BaseModel):
                 ),
                 source=str(raw["source"]) if isinstance(raw.get("source"), str) else None,
                 memory_at=raw.get("memory_at") if isinstance(raw.get("memory_at"), int) else None,
-                gmt_created=(
-                    raw.get("gmt_created") if isinstance(raw.get("gmt_created"), int) else None
+                gmt_created=gmt_created,
+                created_at=created_at,
+                updated_at=updated_at if updated_at is not None else created_at,
+            )
+        except (KeyError, TypeError, ValueError) as error:
+            raise HySdkReadError("hy_memory_record_shape_unknown") from error
+
+    @classmethod
+    def _from_productivity(cls, raw: Mapping[str, object]) -> HySdkMemoryRecord:
+        """An experience or fact from list/search(scene="all") or get().
+
+        get() names the namespace in ``variant`` (its ``scene`` is the legacy
+        "productivity"); list/search name it in ``scene``.
+        """
+        kind = str(raw["kind"])
+        variant = next(
+            (
+                value
+                for value in (raw.get("variant"), raw.get("scene"))
+                if value in {"working", "coding"}
+            ),
+            None,
+        )
+        id_key = "experience_id" if kind == "experience" else "fact_id"
+        memory_id = raw.get("memory_id") or raw.get(id_key)
+        if variant is None or not isinstance(memory_id, str) or not memory_id.strip():
+            raise HySdkReadError("hy_memory_record_shape_unknown")
+        task: str | None = None
+        solution: str | None = None
+        if kind == "experience":
+            task = str(raw.get("task") or "").strip()
+            solution = str(raw.get("solution") or "").strip()
+            content = "\n".join(part for part in (task, solution) if part)
+        else:
+            statement = raw.get("statement")
+            content = str(statement if isinstance(statement, str) else raw.get("content") or "")
+        if not content.strip():
+            raise HySdkReadError("hy_memory_record_shape_unknown")
+        status = str(raw.get("status") or "active")
+        created_at = _epoch(raw.get("created_at"))
+        updated_at = _epoch(raw.get("updated_at"))
+        try:
+            return cls(
+                memory_id=memory_id,
+                content=content,
+                layer=kind,
+                status=status,
+                is_latest=status == "active",
+                tags=_string_tuple(raw.get("tags")),
+                user_id=str(raw.get("user_id") or ""),
+                agent_id=str(raw.get("agent_id") or ""),
+                session_id=(
+                    str(raw["session_id"]) if isinstance(raw.get("session_id"), str) else None
                 ),
+                source=str(raw["source"]) if isinstance(raw.get("source"), str) else None,
+                gmt_created=created_at,
+                scene=cast(MemoryScene, variant),
+                kind=cast(MemoryKindName, kind),
+                variant=cast(MemoryVariantName, variant),
+                task=task,
+                solution=solution,
+                created_at=created_at,
+                updated_at=updated_at if updated_at is not None else created_at,
             )
         except (KeyError, TypeError, ValueError) as error:
             raise HySdkReadError("hy_memory_record_shape_unknown") from error
@@ -95,6 +190,15 @@ class HySdkMemoryPage(BaseModel):
     # Set on a search whose relevance window was full: matches were looked for
     # only among this many most relevant memories, so `total` may undercount.
     search_window: int | None = None
+    # Keyword search only: the server-side result window this page was cut
+    # from. Pass it back with the next offset to page the same results.
+    window_id: str | None = None
+    # True when the window_id the client sent had expired or did not match the
+    # query: the search ran again and this is page 1 of the new window.
+    window_reset: bool = False
+    # Empty-query listing only: how many memories each scene holds under the
+    # same filters (`total` is their sum).
+    totals: dict[str, int] | None = None
 
     @classmethod
     def from_sdk(cls, raw: object, *, limit: int, offset: int) -> HySdkMemoryPage:
@@ -123,6 +227,12 @@ class HySdkMemoryPage(BaseModel):
     ) -> tuple[HySdkMemoryPage, int]:
         if not isinstance(raw, Mapping):
             raise HySdkReadError("hy_memory_list_shape_unknown")
+        if raw.get("scene") == "all":
+            return cls._parse_all_scenes(raw, limit=limit, offset=offset, skip_invalid=skip_invalid)
+        if raw.get("scene") == "productivity":
+            return cls._parse_experiences(
+                raw, limit=limit, offset=offset, skip_invalid=skip_invalid
+            )
         rows: list[object] = []
         total = 0
         for bucket_name, rows_name in (("vdb", "memories"), ("graph", "nodes")):
@@ -163,6 +273,107 @@ class HySdkMemoryPage(BaseModel):
         )
         return page, skipped
 
+    @classmethod
+    def _parse_all_scenes(
+        cls,
+        raw: Mapping[str, object],
+        *,
+        limit: int,
+        offset: int,
+        skip_invalid: bool,
+    ) -> tuple[HySdkMemoryPage, int]:
+        """``list_memories(scene="all")``: chat, working and coding, newest first."""
+        rows = raw.get("memories")
+        total = raw.get("total")
+        if (
+            not isinstance(rows, list)
+            or not isinstance(total, int)
+            or isinstance(total, bool)
+            or total < 0
+        ):
+            raise HySdkReadError("hy_memory_list_shape_unknown")
+        totals_raw = raw.get("totals")
+        totals = (
+            {
+                str(scene): count
+                for scene, count in totals_raw.items()
+                if isinstance(count, int) and not isinstance(count, bool) and count >= 0
+            }
+            if isinstance(totals_raw, Mapping)
+            else None
+        )
+        memories: list[HySdkMemoryRecord] = []
+        seen: set[tuple[str, str, str | None]] = set()
+        skipped = 0
+        for row in rows:
+            try:
+                record = HySdkMemoryRecord.from_sdk(row)
+            except HySdkReadError:
+                if not skip_invalid:
+                    raise
+                skipped += 1
+                continue
+            key = (record.memory_id, record.kind, record.variant)
+            if key in seen:
+                continue
+            seen.add(key)
+            memories.append(record)
+        return (
+            cls(
+                memories=tuple(memories),
+                total=total,
+                limit=limit,
+                offset=offset,
+                totals=totals,
+            ),
+            skipped,
+        )
+
+    @classmethod
+    def _parse_experiences(
+        cls,
+        raw: Mapping[str, object],
+        *,
+        limit: int,
+        offset: int,
+        skip_invalid: bool,
+    ) -> tuple[HySdkMemoryPage, int]:
+        """``list_memories(scene="working"|"coding")``: that scene's experiences.
+
+        The SDK names the scene once, in ``variant``; each row is a bare
+        experience, so the kind and variant are added before parsing.
+        """
+        rows = raw.get("experiences")
+        total = raw.get("total")
+        variant = raw.get("variant")
+        if (
+            not isinstance(rows, list)
+            or not isinstance(total, int)
+            or isinstance(total, bool)
+            or total < 0
+            or variant not in {"working", "coding"}
+        ):
+            raise HySdkReadError("hy_memory_list_shape_unknown")
+        memories: list[HySdkMemoryRecord] = []
+        skipped = 0
+        for row in rows:
+            try:
+                if not isinstance(row, Mapping):
+                    raise HySdkReadError("hy_memory_record_shape_unknown")
+                record = HySdkMemoryRecord.from_sdk(
+                    {**row, "kind": "experience", "variant": variant}
+                )
+            except HySdkReadError:
+                if not skip_invalid:
+                    raise
+                skipped += 1
+                continue
+            memories.append(record)
+        return (
+            cls(memories=tuple(memories), total=total, limit=limit, offset=offset),
+            skipped,
+        )
+
 
 class HySdkRawRecord(BaseModel):
     model_config = ConfigDict(frozen=True, extra="forbid")
@@ -327,38 +538,79 @@ def parse_sdk_search(raw: object, *, error_code: str) -> tuple[SemanticMemoryHit
     return tuple(found)
 
 
-def library_keyword_hits(raw: object, query: str) -> tuple[tuple[str, ...], int]:
-    """Ids in an SDK search window whose text contains every query term.
+class LibraryHit(NamedTuple):
+    """One keyword match in a library search window, with its namespace."""
+
+    memory_id: str
+    kind: MemoryKindName
+    variant: MemoryVariantName | None
+
+
+def library_keyword_hits(raw: object, query: str) -> tuple[tuple[LibraryHit, ...], int]:
+    """Memories in an SDK search window whose text contains every query term.
 
     The local SDK store has no keyword channel (Chroma's keyword search is
     empty), so search is pure vector similarity: a word in the library can
     score below the floor, and a word in none of it still scores above. The
     library search asks the SDK for its most relevant window and keeps only the
-    rows that actually contain the words, most relevant first. Returns those ids
-    and how many distinct rows the window held.
+    rows that actually contain the words, most relevant first. Returns those
+    hits and how many distinct rows the window held.
+
+    A ``search(scene="all")`` window mixes chat memories with working/coding
+    experiences and facts; their text is the unified ``content`` (an
+    experience's task and solution, a fact's statement). The fused order is
+    kept as the SDK ranked it.
     """
-    rows = _reply_rows(raw, "hy_memory_search_shape_unknown")
     terms = query.casefold().split()
-    seen: set[str] = set()
-    matched: list[str] = []
-    for item in sorted(rows, key=_score, reverse=True):
-        memory_id = item.get("memory_id") or item.get("id")
-        if not isinstance(memory_id, str) or not memory_id or memory_id in seen:
+    if isinstance(raw, Mapping) and raw.get("scene") == "all":
+        rows = raw.get("memories")
+        if not isinstance(rows, list) or any(not isinstance(row, Mapping) for row in rows):
+            raise HySdkReadError("hy_memory_search_shape_unknown")
+        ordered: list[Mapping[str, object]] = list(rows)
+    else:
+        ordered = sorted(
+            _reply_rows(raw, "hy_memory_search_shape_unknown"), key=_score, reverse=True
+        )
+    seen: set[LibraryHit] = set()
+    matched: list[LibraryHit] = []
+    for item in ordered:
+        hit = _library_hit(item)
+        if hit is None or hit in seen:
             continue
-        seen.add(memory_id)
-        content = item.get("content")
+        seen.add(hit)
         tags = item.get("tags")
-        text = " ".join(
-            [
-                content if isinstance(content, str) else "",
-                *(tag for tag in (tags if isinstance(tags, list) else ()) if isinstance(tag, str)),
-            ]
-        ).casefold()
+        parts = [item.get(key) for key in ("content", "task", "solution", "statement")] + list(
+            tags if isinstance(tags, list) else ()
+        )
+        text = " ".join(part for part in parts if isinstance(part, str)).casefold()
         if all(term in text for term in terms):
-            matched.append(memory_id)
+            matched.append(hit)
     return tuple(matched), len(seen)
 
 
+def _library_hit(item: Mapping[str, object]) -> LibraryHit | None:
+    kind = item.get("kind")
+    if kind in {"experience", "fact"}:
+        variant = item.get("variant") if item.get("variant") in {"working", "coding"} else None
+        variant = variant or (
+            item.get("scene") if item.get("scene") in {"working", "coding"} else None
+        )
+        memory_id = item.get("memory_id") or item.get(
+            "experience_id" if kind == "experience" else "fact_id"
+        )
+        if variant is None or not isinstance(memory_id, str) or not memory_id:
+            return None
+        return LibraryHit(
+            memory_id,
+            "experience" if kind == "experience" else "fact",
+            "coding" if variant == "coding" else "working",
+        )
+    memory_id = item.get("memory_id") or item.get("id")
+    if not isinstance(memory_id, str) or not memory_id:
+        return None
+    return LibraryHit(memory_id, "chat", None)
+
+
 def parse_sdk_raw_search(raw: object) -> tuple[HySdkRawHit, ...]:
     return tuple(
         HySdkRawHit.from_sdk_search(row)
@@ -366,6 +618,25 @@ def parse_sdk_raw_search(raw: object) -> tuple[HySdkRawHit, ...]:
     )
 
 
+def _epoch(value: object) -> int | None:
+    """Epoch seconds from an int or an ISO-8601 string (naive means UTC)."""
+    if isinstance(value, bool):
+        return None
+    if isinstance(value, int):
+        return value
+    if isinstance(value, float):
+        return int(value)
+    if isinstance(value, str) and value.strip():
+        try:
+            parsed = datetime.fromisoformat(value.strip())
+        except ValueError:
+            return None
+        if parsed.tzinfo is None:
+            parsed = parsed.replace(tzinfo=UTC)
+        return int(parsed.timestamp())
+    return None
+
+
 def _string_tuple(value: object) -> tuple[str, ...]:
     if not isinstance(value, list):
         return ()

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

@@ -0,0 +1,113 @@
+"""Short-lived result windows for the memory library's keyword search.
+
+A library search asks the SDK once for a bounded relevance window and keeps
+the keyword matches. Paging must cut every page from that same list: running
+the search again per page can rank differently and duplicate or skip memories
+between pages. The matches are kept here under an opaque ``window_id`` that
+the client passes back with the next offset.
+
+A window is bound to the filters it was searched with (query, source,
+statuses, scene). It expires after ``ttl_seconds`` without being read, and the
+store keeps at most ``max_windows`` windows, dropping the least recently read
+first.
+Only memory identities are kept, never content: each page is read fresh from
+the SDK, so an edit or a delete shows on the next page read.
+"""
+
+from __future__ import annotations
+
+import secrets
+import threading
+import time
+from collections import OrderedDict
+from collections.abc import Callable
+from dataclasses import dataclass, field
+
+from one_memory.hy_sdk_types import LibraryHit
+
+DEFAULT_WINDOW_TTL_SECONDS = 300.0
+DEFAULT_MAX_WINDOWS = 32
+
+WindowKey = tuple[str, str | None, tuple[str, ...], str]
+
+
+def window_key(
+    query: str, source: str | None, statuses: list[str], scene: str = "all"
+) -> WindowKey:
+    return (query, source, tuple(sorted(set(statuses))), scene)
+
+
+@dataclass(frozen=True)
+class SearchWindow:
+    window_id: str
+    key: WindowKey
+    hits: tuple[LibraryHit, ...]
+    # Set when the SDK window was full, so matches outside it were not looked
+    # for and `total` may undercount.
+    search_window: int | None
+
+
+@dataclass
+class _Entry:
+    window: SearchWindow
+    last_read: float = field(default=0.0)
+
+
+class LibrarySearchWindows:
+    def __init__(
+        self,
+        *,
+        ttl_seconds: float = DEFAULT_WINDOW_TTL_SECONDS,
+        max_windows: int = DEFAULT_MAX_WINDOWS,
+        clock: Callable[[], float] = time.monotonic,
+    ) -> None:
+        self._ttl = ttl_seconds
+        self._max = max(1, max_windows)
+        self._clock = clock
+        self._entries: OrderedDict[str, _Entry] = OrderedDict()
+        self._lock = threading.Lock()
+
+    def get(self, window_id: str, key: WindowKey) -> SearchWindow | None:
+        """The window, if it is still live and was searched with `key`."""
+        with self._lock:
+            now = self._clock()
+            self._expire(now)
+            entry = self._entries.get(window_id)
+            if entry is None or entry.window.key != key:
+                return None
+            entry.last_read = now
+            self._entries.move_to_end(window_id)
+            return entry.window
+
+    def put(
+        self,
+        key: WindowKey,
+        hits: tuple[LibraryHit, ...],
+        search_window: int | None,
+    ) -> SearchWindow:
+        window = SearchWindow(
+            window_id=secrets.token_urlsafe(12),
+            key=key,
+            hits=hits,
+            search_window=search_window,
+        )
+        with self._lock:
+            now = self._clock()
+            self._expire(now)
+            self._entries[window.window_id] = _Entry(window=window, last_read=now)
+            while len(self._entries) > self._max:
+                self._entries.popitem(last=False)
+        return window
+
+    def __len__(self) -> int:
+        with self._lock:
+            return len(self._entries)
+
+    def _expire(self, now: float) -> None:
+        stale = [
+            window_id
+            for window_id, entry in self._entries.items()
+            if now - entry.last_read >= self._ttl
+        ]
+        for window_id in stale:
+            del self._entries[window_id]

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

@@ -105,10 +105,17 @@ def capture_stdio(source_id: str, stdin: TextIO, output: TextIO) -> int:
 
 
 def sdk_migration_capture_fenced(data_dir: Path) -> bool:
-    """Ignore stale fences; only a live Desktop migration pauses hook writes."""
+    """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")

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

@@ -1,5 +1,13 @@
+"""Add one memory directly: `POST /api/v2/memories` and its status read.
+
+The public API has no "notes": a hand-added memory is filed as manual Evidence
+and turned into memories by the durable write queue. Storage keeps its
+pre-rename identifiers (`memory_note_requests`, source `one-memory-manual`,
+`input_mode=direct_memory_note`, conversation `note:<request_id>`) because they
+are persisted and feed evidence ids; renaming them would change stored data.
+"""
+
 import asyncio
-import json
 import sqlite3
 from collections.abc import Sequence
 from datetime import UTC, datetime
@@ -28,7 +36,7 @@ from one_memory.memory_tasks import MemoryTaskStatus, MemoryTaskStore
 from one_memory.secrets import SecretStoreUnavailableError
 
 SOURCE_ID = "one-memory-manual"
-MemoryNoteState = Literal[
+MemoryAddState = Literal[
     "waiting_for_model",
     "waiting_for_permission",
     "pending",
@@ -39,7 +47,7 @@ MemoryNoteState = Literal[
 ]
 
 
-class MemoryNoteInput(BaseModel):
+class MemoryAddInput(BaseModel):
     model_config = ConfigDict(extra="forbid")
 
     request_id: UUID
@@ -50,25 +58,25 @@ class MemoryNoteInput(BaseModel):
     @classmethod
     def meaningful_text(cls, value: str) -> str:
         if not value.strip():
-            raise ValueError("memory_note_empty")
+            raise ValueError("memory_add_empty")
         return value
 
 
-class MemoryNoteReceipt(BaseModel):
+class MemoryAddReceipt(BaseModel):
     model_config = ConfigDict(extra="forbid")
 
     evidence_id: str
     text: str
     scope: Literal["all-apps"] = "all-apps"
     created_at: datetime
-    state: MemoryNoteState
+    state: MemoryAddState
     task_id: str | None = None
     memory_ids: list[str] = Field(default_factory=list)
     error: str | None = None
 
 
-class LegacyMemoryNoteReader:
-    """Read pre-cutover note receipts without retaining any write runtime."""
+class LegacyMemoryAdditionReader:
+    """Read pre-cutover addition receipts without retaining any write runtime."""
 
     def __init__(
         self,
@@ -79,7 +87,7 @@ class LegacyMemoryNoteReader:
         self.governance = governance
 
 
-class MemoryNoteStore:
+class MemoryAdditionStore:
     def __init__(
         self,
         evidence: EvidenceStore,
@@ -92,34 +100,34 @@ class MemoryNoteStore:
         self.evidence = evidence
         self.processor = processor
         # D52: the production composition root passes a UnifiedWriteIntake so a
-        # manual note reaches the durable queue like every other entry. It stays
+        # manual addition reaches the durable queue like every other entry. It stays
         # optional so isolated tests can keep constructing the store directly.
         self.intake = intake
         self.sdk_authority = sdk_authority
         self.write_queue = write_queue
 
-    def save(self, note: MemoryNoteInput) -> EvidenceRecord:
+    def save(self, addition: MemoryAddInput) -> EvidenceRecord:
         now = datetime.now(UTC)
         value = EvidenceInput(
             source_id=SOURCE_ID,
-            conversation_id=f"note:{note.request_id}",
-            message_id=str(note.request_id),
+            conversation_id=f"note:{addition.request_id}",
+            message_id=str(addition.request_id),
             role="user",
             written_by=WrittenBy.PERSON,
             created_at=now,
-            verbatim=note.text,
+            verbatim=addition.text,
             origin_meta={
                 EvidenceOrigin.MANUAL_IMPORT: OriginMetadata(
                     raw_meta={
                         "input_mode": "direct_memory_note",
-                        "recall_scope": note.scope,
+                        "recall_scope": addition.scope,
                     }
                 )
             },
         )
         if self.sdk_authority:
             if self.intake is None or self.write_queue is None:
-                raise RuntimeError("sdk_memory_note_intake_unavailable")
+                raise RuntimeError("sdk_memory_add_intake_unavailable")
             record = materialize_write_input(value, observed_at=now)
             with main_database(self.write_queue.database_path).read() as database:
                 existing = database.execute(
@@ -129,7 +137,7 @@ class MemoryNoteStore:
             if existing is not None:
                 current = self.require(record.evidence_id)
                 if current.verbatim != record.verbatim:
-                    raise ValueError("memory_note_request_conflict")
+                    raise ValueError("memory_add_conflict")
                 return current
             receipt = self.intake.submit_records(
                 (record,),
@@ -159,13 +167,13 @@ class MemoryNoteStore:
                 (SOURCE_ID,),
             ).fetchone()
             if grant and grant[0] is not None:
-                raise ValueError("memory_note_source_revoked")
+                raise ValueError("memory_add_source_revoked")
             existing = db.execute(
                 "SELECT verbatim FROM evidence WHERE evidence_id=?", (value.evidence_id,)
             ).fetchone()
             if existing:
-                if existing[0] != note.text:
-                    raise ValueError("memory_note_request_conflict")
+                if existing[0] != addition.text:
+                    raise ValueError("memory_add_conflict")
             else:
                 self.evidence.put(value, connection=db)
                 db.execute(
@@ -218,10 +226,10 @@ class MemoryNoteStore:
                 (SOURCE_ID,),
             ).fetchone()
         if grant is None or grant[0] is not None:
-            raise ValueError("memory_note_source_revoked")
+            raise ValueError("memory_add_source_revoked")
         return record
 
-    def receipt(self, evidence_id: str) -> MemoryNoteReceipt:
+    def receipt(self, evidence_id: str) -> MemoryAddReceipt:
         record = self.require(evidence_id)
         if self.sdk_authority:
             assert self.write_queue is not None
@@ -232,7 +240,7 @@ class MemoryNoteStore:
                 ).fetchone()[0]
             durable = self.write_queue.get(str(request_id))
             durable_state = durable.state if durable is not None else "failed"
-            mapped: MemoryNoteState = {
+            mapped: MemoryAddState = {
                 "pending": "pending",
                 "running": "running",
                 "waiting_for_model": "waiting_for_model",
@@ -241,7 +249,7 @@ class MemoryNoteStore:
                     "ready" if durable is not None and durable.sdk_memory_ids else "no_memories"
                 ),
             }.get(durable_state, "failed")
-            return MemoryNoteReceipt(
+            return MemoryAddReceipt(
                 evidence_id=evidence_id,
                 text=sanitize_model_input(record.verbatim),
                 created_at=record.created_at or record.imported_at,
@@ -250,7 +258,7 @@ class MemoryNoteStore:
                 error=durable.detail if durable is not None else "write_missing",
             )
         if self.processor is None:
-            raise RuntimeError("legacy_memory_note_processor_unavailable")
+            raise RuntimeError("legacy_memory_add_processor_unavailable")
         task = self.processor.tasks.task_for_evidence(evidence_id)
         memory_ids = []
         if task:
@@ -258,7 +266,7 @@ class MemoryNoteStore:
                 memory = self.processor.governance.get(output.memory_id, user_id="local")
                 if memory and memory.status is MemoryStatus.CONFIRMED:
                     memory_ids.append(memory.memory_id)
-        state: MemoryNoteState
+        state: MemoryAddState
         if task is None or task.status == MemoryTaskStatus.WAITING_FOR_MODEL:
             state = "waiting_for_model"
         elif task.status == MemoryTaskStatus.WAITING_FOR_PERMISSION:
@@ -274,7 +282,7 @@ class MemoryNoteStore:
         else:
             state = "failed"
         error = task.last_error_code if task else None
-        return MemoryNoteReceipt(
+        return MemoryAddReceipt(
             evidence_id=record.evidence_id,
             text=sanitize_model_input(record.verbatim),
             created_at=record.created_at or record.imported_at,
@@ -284,33 +292,7 @@ class MemoryNoteStore:
             error=error,
         )
 
-    def list(self) -> list[MemoryNoteReceipt]:
-        if self.sdk_authority:
-            assert self.write_queue is not None
-            with main_database(self.write_queue.database_path).read() as database:
-                ids = [
-                    str(row[0])
-                    for row in database.execute(
-                        "SELECT note_id FROM memory_note_requests ORDER BY created_at DESC LIMIT 50"
-                    )
-                ]
-            return [self.receipt(key) for key in ids]
-        with main_database(self.evidence.database_path).read() as db:
-            ids = [
-                row[0]
-                for row in db.execute(
-                    "SELECT e.evidence_id,o.raw_meta_json FROM evidence e "
-                    "JOIN source_grants g USING(user_id,source_id) "
-                    "JOIN evidence_origins o USING(evidence_id) WHERE e.user_id='local' "
-                    "AND e.source_id=? AND g.revoked_at IS NULL AND o.origin='manual_import' "
-                    "ORDER BY e.imported_at DESC,e.evidence_id LIMIT 50",
-                    (SOURCE_ID,),
-                )
-                if json.loads(row[1]).get("input_mode") == "direct_memory_note"
-            ]
-        return [self.receipt(key) for key in ids]
-
-    def receipt_for_request(self, request_id: UUID) -> MemoryNoteReceipt:
+    def receipt_for_request(self, request_id: UUID) -> MemoryAddReceipt:
         identity = str(request_id)
         if self.sdk_authority:
             probe = EvidenceInput(
@@ -338,107 +320,65 @@ class MemoryNoteStore:
         return self.receipt(str(row[0]))
 
 
-def memory_note_router(dependencies: Sequence[Depends]) -> APIRouter:
-    router = APIRouter(
-        prefix="/api/v1/memory-notes", tags=["memory-notes"], dependencies=dependencies
-    )
+def memory_add_router(dependencies: Sequence[Depends]) -> APIRouter:
+    """`POST /api/v2/memories` and `GET /api/v2/memories/additions/{request_id}`.
 
-    def store(request: Request) -> MemoryNoteStore:
-        return cast(MemoryNoteStore, request.app.state.memory_note_store)
+    Both paths are outside the single-segment `/api/v2/memories/{memory_id}`
+    routes; external (enveloped) callers are refused by
+    `require_external_endpoint` because neither is a broker read route.
+    """
+    router = APIRouter(prefix="/api/v2/memories", tags=["memories"], dependencies=dependencies)
 
-    async def schedule(
-        notes: MemoryNoteStore,
-        record: EvidenceRecord,
-        *,
-        readmit: bool = False,
-    ) -> MemoryNoteReceipt:
+    def store(request: Request) -> MemoryAdditionStore:
+        return cast(MemoryAdditionStore, request.app.state.memory_addition_store)
+
+    async def schedule(additions: MemoryAdditionStore, record: EvidenceRecord) -> None:
         try:
-            if notes.sdk_authority:
-                return await asyncio.to_thread(notes.receipt, record.evidence_id)
-            if notes.processor is None:
-                raise RuntimeError("legacy_memory_note_processor_unavailable")
-            if notes.intake is None:
+            if additions.sdk_authority:
+                return
+            if additions.processor is None:
+                raise RuntimeError("legacy_memory_add_processor_unavailable")
+            if additions.intake is None:
                 # Isolated tests construct the store without a queue.
-                await notes.processor.enqueue_conversation_off_thread(record)
+                await additions.processor.enqueue_conversation_off_thread(record)
             else:
-                # Production: submit to the durable queue first. The drain runs
-                # the same supervisor path, so create/process semantics are
-                # unchanged; replaying the same request returns the original
-                # `entry:<evidence_id>` job instead of a second HY call.
-                if readmit:
-                    # `/{evidence_id}/process` is the explicit retry signal.
-                    # It also revives pre-upgrade permission waiters.
-                    await asyncio.to_thread(notes.intake.queue.readmit_parked)
-                submitted = await asyncio.to_thread(
-                    notes.intake.submit_evidence,
+                # Production: submit to the durable queue. Replaying the same
+                # request returns the original `entry:<evidence_id>` job
+                # instead of a second HY call.
+                await asyncio.to_thread(
+                    additions.intake.submit_evidence,
                     record,
                     first_round=1,
                     last_round=1,
                     priority="live",
                 )
-                if readmit:
-                    await asyncio.to_thread(
-                        notes.intake.readmit_cancelled_evidence,
-                        record,
-                        job_id=submitted.record.job_id,
-                        first_round=1,
-                        last_round=1,
-                        priority="live",
-                    )
         except SecretStoreUnavailableError:
-            saved = await asyncio.to_thread(notes.receipt, record.evidence_id)
-            return saved.model_copy(
-                update={"state": "waiting_for_model", "error": "secure_storage_unavailable"}
-            )
-        return await asyncio.to_thread(notes.receipt, record.evidence_id)
+            # The receipt already reports the saved text; the queue retries
+            # once secure storage is back.
+            return
 
-    @router.post("", response_model=MemoryNoteReceipt, status_code=201)
-    async def create(
-        note: MemoryNoteInput,
+    @router.post("", response_model=MemoryAddReceipt, status_code=201)
+    async def add_memory(
+        addition: MemoryAddInput,
         request: Request,
         background: BackgroundTasks,
-    ) -> MemoryNoteReceipt:
-        notes = store(request)
+    ) -> MemoryAddReceipt:
+        additions = store(request)
         try:
-            record = await asyncio.to_thread(notes.save, note)
+            record = await asyncio.to_thread(additions.save, addition)
         except ValueError as error:
             raise HTTPException(409, str(error)) from error
-        saved = await asyncio.to_thread(notes.receipt, record.evidence_id)
-        background.add_task(schedule, notes, record)
+        saved = await asyncio.to_thread(additions.receipt, record.evidence_id)
+        background.add_task(schedule, additions, record)
         return saved
 
-    @router.get("", response_model=list[MemoryNoteReceipt])
-    def listing(request: Request) -> list[MemoryNoteReceipt]:
-        return store(request).list()
-
-    @router.get("/operations/{request_id}", response_model=MemoryNoteReceipt)
-    def operation(request_id: UUID, request: Request) -> MemoryNoteReceipt:
+    @router.get("/additions/{request_id}", response_model=MemoryAddReceipt)
+    def memory_add_status(request_id: UUID, request: Request) -> MemoryAddReceipt:
         try:
             return store(request).receipt_for_request(request_id)
         except KeyError as error:
-            raise HTTPException(404, "memory_note_operation_not_found") from error
-
-    @router.get("/{evidence_id}", response_model=MemoryNoteReceipt)
-    def get(evidence_id: str, request: Request) -> MemoryNoteReceipt:
-        try:
-            return store(request).receipt(evidence_id)
-        except KeyError as error:
-            raise HTTPException(404, "memory_note_not_found") from error
+            raise HTTPException(404, "memory_add_not_found") from error
         except ValueError as error:
             raise HTTPException(409, str(error)) from error
 
-    @router.post("/{evidence_id}/process", response_model=MemoryNoteReceipt)
-    async def process(evidence_id: str, request: Request) -> MemoryNoteReceipt:
-        notes = store(request)
-        try:
-            record = await asyncio.to_thread(notes.require, evidence_id)
-        except KeyError as error:
-            raise HTTPException(404, "memory_note_not_found") from error
-        except ValueError as error:
-            raise HTTPException(409, str(error)) from error
-        # This route is the explicit "the condition that parked it may have
-        # changed" signal (the person just granted consent or fixed the model),
-        # which is when `readmit_parked` is meant to run.
-        return await schedule(notes, record, readmit=True)
-
     return router

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

@@ -316,6 +316,12 @@ LEGACY_MEMORY_WRITE_JOB_COLUMNS = (
 
 _FIFO_BLOCKING_STATES = (PENDING, RUNNING, WAITING_FOR_PERMISSION, WAITING_FOR_MODEL)
 EVENT_TIME_WINDOW = timedelta(minutes=10)
+#: Sources whose jobs are a person adding a memory by hand ("添加记忆"), not
+#: history. History is digested strictly old to new through the event-time
+#: window; a note is stamped "now", so inside that window it waited behind the
+#: whole unprocessed history. These jobs are claimed ahead of the window,
+#: still one at a time per source and in order within their session.
+DIRECT_WRITE_SOURCES = frozenset({"one-memory-manual"})
 
 
 @dataclass(frozen=True)
@@ -2601,6 +2607,39 @@ class DurableWriteDrain:
                 placeholders = ",".join("?" for _ in enabled_sources)
                 source_clause = f"AND candidate.source_key IN ({placeholders}) "
                 source_params = tuple(sorted(enabled_sources))
+            direct_sources = ",".join("?" for _ in DIRECT_WRITE_SOURCES)
+            # Same eligibility as the window claim below (free lease, no
+            # running job of its source, nothing earlier in its session), but
+            # not bound to the window: a note must not wait for history.
+            direct_rows = connection.execute(
+                "SELECT candidate.job_id,candidate.source_key "
+                "FROM memory_write_jobs AS candidate "
+                "WHERE candidate.state=? "
+                "AND (candidate.lease_expires_at IS NULL OR candidate.lease_expires_at < ?) "
+                + source_clause
+                + f"AND candidate.source_key IN ({direct_sources}) "
+                "AND NOT EXISTS ("
+                "SELECT 1 FROM memory_write_jobs AS held "
+                "WHERE held.source_key=candidate.source_key AND held.state=? "
+                "AND held.lease_owner IS NOT NULL AND held.lease_expires_at>=?) "
+                "AND NOT EXISTS ("
+                "SELECT 1 FROM memory_write_jobs AS earlier "
+                "WHERE earlier.session_key=candidate.session_key "
+                f"AND earlier.state IN ({blocking}) "
+                "AND (earlier.event_at<candidate.event_at OR "
+                "(earlier.event_at=candidate.event_at "
+                "AND earlier.queue_seq<candidate.queue_seq))) "
+                "ORDER BY candidate.queue_seq",
+                (
+                    PENDING,
+                    now.isoformat(),
+                    *source_params,
+                    *sorted(DIRECT_WRITE_SOURCES),
+                    RUNNING,
+                    now.isoformat(),
+                    *_FIFO_BLOCKING_STATES,
+                ),
+            ).fetchall()
             window = connection.execute(
                 "SELECT window_anchor,window_end FROM memory_write_schedule_state WHERE singleton=1"
             ).fetchone()
@@ -2654,6 +2693,7 @@ class DurableWriteDrain:
                 if active is None:
                     connection.execute("DELETE FROM memory_write_schedule_state WHERE singleton=1")
                     window = None
+            anchor: Any = None
             if window is None:
                 anchor = connection.execute(
                     "SELECT candidate.event_at "
@@ -2682,8 +2722,10 @@ class DurableWriteDrain:
                         *_FIFO_BLOCKING_STATES,
                     ),
                 ).fetchone()
-                if anchor is None:
+                if anchor is None and not direct_rows:
                     return ()
+            has_window = window is not None or anchor is not None
+            if window is None and anchor is not None:
                 anchor_at = datetime.fromisoformat(str(anchor[0]))
                 if anchor_at.tzinfo is None:
                     anchor_at = anchor_at.replace(tzinfo=UTC)
@@ -2695,39 +2737,41 @@ class DurableWriteDrain:
                     "VALUES (1,?,?,?)",
                     (anchor_text, end_text, now.isoformat()),
                 )
-            rows = connection.execute(
-                "SELECT candidate.job_id,candidate.source_key "
-                "FROM memory_write_jobs AS candidate "
-                "WHERE candidate.state=? "
-                "AND (candidate.lease_expires_at IS NULL OR candidate.lease_expires_at < ?) "
-                + source_clause
-                + "AND candidate.event_at>=? AND candidate.event_at<? "
-                "AND NOT EXISTS ("
-                "SELECT 1 FROM memory_write_jobs AS held "
-                "WHERE held.source_key=candidate.source_key AND held.state=? "
-                "AND held.lease_owner IS NOT NULL AND held.lease_expires_at>=?) "
-                "AND NOT EXISTS ("
-                "SELECT 1 FROM memory_write_jobs AS earlier "
-                "WHERE earlier.session_key=candidate.session_key "
-                f"AND earlier.state IN ({blocking}) "
-                "AND (earlier.event_at<candidate.event_at OR "
-                "(earlier.event_at=candidate.event_at "
-                "AND earlier.queue_seq<candidate.queue_seq))) "
-                "ORDER BY candidate.event_at,candidate.queue_seq",
-                (
-                    PENDING,
-                    now.isoformat(),
-                    *source_params,
-                    anchor_text,
-                    end_text,
-                    RUNNING,
-                    now.isoformat(),
-                    *_FIFO_BLOCKING_STATES,
-                ),
-            ).fetchall()
+            rows: list[Any] = []
+            if has_window:
+                rows = connection.execute(
+                    "SELECT candidate.job_id,candidate.source_key "
+                    "FROM memory_write_jobs AS candidate "
+                    "WHERE candidate.state=? "
+                    "AND (candidate.lease_expires_at IS NULL OR candidate.lease_expires_at < ?) "
+                    + source_clause
+                    + "AND candidate.event_at>=? AND candidate.event_at<? "
+                    "AND NOT EXISTS ("
+                    "SELECT 1 FROM memory_write_jobs AS held "
+                    "WHERE held.source_key=candidate.source_key AND held.state=? "
+                    "AND held.lease_owner IS NOT NULL AND held.lease_expires_at>=?) "
+                    "AND NOT EXISTS ("
+                    "SELECT 1 FROM memory_write_jobs AS earlier "
+                    "WHERE earlier.session_key=candidate.session_key "
+                    f"AND earlier.state IN ({blocking}) "
+                    "AND (earlier.event_at<candidate.event_at OR "
+                    "(earlier.event_at=candidate.event_at "
+                    "AND earlier.queue_seq<candidate.queue_seq))) "
+                    "ORDER BY candidate.event_at,candidate.queue_seq",
+                    (
+                        PENDING,
+                        now.isoformat(),
+                        *source_params,
+                        anchor_text,
+                        end_text,
+                        RUNNING,
+                        now.isoformat(),
+                        *_FIFO_BLOCKING_STATES,
+                    ),
+                ).fetchall()
             selected: list[str] = []
             selected_sources: set[str] = set()
-            for row in rows:
+            for row in (*direct_rows, *rows):
                 source_key = str(row["source_key"])
                 if source_key in selected_sources:
                     continue

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

@@ -98,23 +98,6 @@ class UnifiedWriteIntake:
             enqueued=durable.enqueued,
         )
 
-    def readmit_cancelled_evidence(
-        self,
-        record: EvidenceRecord,
-        *,
-        job_id: str,
-        first_round: int,
-        last_round: int,
-        priority: WritePriority = "normal",
-    ) -> int:
-        request = self._evidence_request(
-            record,
-            first_round=first_round,
-            last_round=last_round,
-            priority=priority,
-        )
-        return self.queue.readmit_cancelled_permission_confirmed(job_id, request)
-
     @staticmethod
     def _evidence_request(
         record: EvidenceRecord,

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

@@ -81,7 +81,11 @@ class RecallHit(BaseModel):
     score: float = Field(ge=0, le=1)
     #: HY already rendered memory time/evolution/capsule context into content.
     #: Hosts must not append their own governance timestamp in this case.
-    content_format: Literal["plain", "hy-sdk"] = "plain"
+    #: "raw" is an excerpt of an imported conversation, not a memory.
+    content_format: Literal["plain", "hy-sdk", "raw"] = "plain"
+    #: Raw excerpts only: the app and conversation the excerpt came from.
+    source: str | None = None
+    session_id: str | None = None
 
 
 class RecallReceipt(BaseModel):
@@ -103,6 +107,11 @@ class RecallReceipt(BaseModel):
     #: whether the answer is that nothing was found or that reading was not
     #: allowed.
     excluded_sources: tuple[str, ...] = ()
+    #: "raw" when recall searched the imported conversations instead of
+    #: memories, because no generation model is configured or no memory
+    #: exists yet (`fallback_reason`). Raw hits are excerpts, not memories.
+    mode: Literal["memory", "raw"] = "memory"
+    fallback_reason: Literal["model_unavailable", "no_memories"] | None = None
 
 
 class RecallTarget(Protocol):

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

@@ -0,0 +1,149 @@
+"""Recall that degrades to the original conversations instead of answering empty.
+
+MemHub_recall searches the memories the SDK distilled from conversations. That
+needs a configured generation model to have produced any, and a library that
+holds some. Without either, the memory search can only come back empty, so
+recall searches the SDK's raw layer (the imported conversations themselves)
+instead: plain retrieval over what was imported, the same lane
+`/api/v2/context/search` reads, under the same raw-source authority.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import time
+from collections.abc import Awaitable, Callable
+from datetime import UTC, datetime
+from typing import Literal
+
+from one_memory.hy_sdk_types import HySdkRawHit
+from one_memory.recall import (
+    PROBE_QUERY,
+    RecallHit,
+    RecallReceipt,
+    RecallRequest,
+    RecallState,
+    TruncationBudget,
+)
+
+FallbackReason = Literal["model_unavailable", "no_memories"]
+
+#: Raw sources this caller may read, or None for every source (a trusted local
+#: caller). An empty set means the caller may read no raw conversation.
+RawSources = frozenset[str] | None
+
+
+async def recall_with_fallback(
+    request: RecallRequest,
+    *,
+    model_ready: Callable[[], Awaitable[bool]],
+    recall_memories: Callable[[RecallRequest], Awaitable[RecallReceipt]],
+    has_memories: Callable[[], Awaitable[bool]],
+    raw_sources: Callable[[], Awaitable[RawSources]],
+    search_raw: Callable[[str, int, RawSources], Awaitable[tuple[HySdkRawHit, ...]]],
+) -> RecallReceipt:
+    """Memory recall when a model and memories exist, otherwise the raw layer.
+
+    The library check runs only after an empty memory search: with memories
+    present and nothing relevant, the answer stays an honest empty memory
+    result rather than a different kind of hit.
+    """
+    if request.query == PROBE_QUERY:
+        return await recall_memories(request)
+    started = time.monotonic()
+    if await model_ready():
+        receipt = await recall_memories(request)
+        if receipt.hits or await has_memories():
+            return receipt
+        reason: FallbackReason = "no_memories"
+    else:
+        reason = "model_unavailable"
+    remaining = request.timeout_ms / 1_000 - (time.monotonic() - started)
+    return await _raw_recall(
+        request,
+        reason=reason,
+        remaining_seconds=remaining,
+        raw_sources=raw_sources,
+        search_raw=search_raw,
+    )
+
+
+async def _raw_recall(
+    request: RecallRequest,
+    *,
+    reason: FallbackReason,
+    remaining_seconds: float,
+    raw_sources: Callable[[], Awaitable[RawSources]],
+    search_raw: Callable[[str, int, RawSources], Awaitable[tuple[HySdkRawHit, ...]]],
+) -> RecallReceipt:
+    def receipt(
+        hits: tuple[RecallHit, ...] = (),
+        *,
+        used: int = 0,
+        truncated_by: TruncationBudget | None = None,
+        unexamined: int = 0,
+    ) -> RecallReceipt:
+        return RecallReceipt(
+            state=RecallState.GROUNDED if hits else RecallState.EMPTY,
+            query=request.query,
+            scope=request.scope,
+            hits=hits,
+            used_characters=used,
+            truncated=truncated_by is not None,
+            truncated_by=truncated_by,
+            unexamined_count=unexamined,
+            mode="raw",
+            fallback_reason=reason,
+        )
+
+    sources = await raw_sources()
+    if sources is not None and not sources:
+        # The caller may read no original conversation: an empty answer, not
+        # a wider grant than recall had.
+        return receipt()
+    if remaining_seconds <= 0:
+        return receipt(truncated_by=TruncationBudget.TIMEOUT)
+    try:
+        found = await asyncio.wait_for(
+            search_raw(request.query, request.limit, sources),
+            timeout=remaining_seconds,
+        )
+    except TimeoutError:
+        return receipt(truncated_by=TruncationBudget.TIMEOUT)
+    hits: list[RecallHit] = []
+    used = 0
+    truncated_by: TruncationBudget | None = None
+    for index, hit in enumerate(found):
+        if sources is not None and hit.source not in sources:
+            continue
+        if len(hits) >= request.limit:
+            truncated_by = TruncationBudget.COUNT
+            return receipt(
+                tuple(hits),
+                used=used,
+                truncated_by=truncated_by,
+                unexamined=len(found) - index,
+            )
+        if used + len(hit.content) > request.character_budget:
+            truncated_by = TruncationBudget.CHARACTER
+            continue
+        hits.append(
+            RecallHit(
+                memory_id=hit.raw_id,
+                content=hit.content,
+                kind="raw",
+                scopes=(),
+                evidence_ids=(),
+                updated_at=(
+                    datetime.fromtimestamp(hit.memory_at, tz=UTC)
+                    if hit.memory_at is not None
+                    else datetime(1970, 1, 1, tzinfo=UTC)
+                ),
+                score=hit.score,
+                content_format="raw",
+                source=hit.source,
+                session_id=hit.session_id,
+            )
+        )
+        used += len(hit.content)
+    return receipt(tuple(hits), used=used, truncated_by=truncated_by)

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

@@ -0,0 +1,504 @@
+"""Put a home back exactly as it was when a failed `sdk-migrate` started.
+
+A migration that fails before SDK authority is committed has already changed
+the home: schema migrations on `one-memory.sqlite3`, legacy work moved into the
+durable queue, renamed Chroma collections under `hy-memory/governed-v2`, ledger
+rows. The fixed release that follows must start from the original data, not
+from that half-way state, so the runner restores the verified full-home bundle
+it took before the first change (`restore point`).
+
+The restore is staged and then swapped in with renames:
+
+1. the bundle is verified (every file hashed against its manifest);
+2. its database, config and SDK root are copied next to their live places and
+   verified again;
+3. a journal lists every rename, then the live items (database with its
+   `-wal`/`-shm`, `config.json`, `hy-memory/governed-v2`) are renamed into
+   `backups/sdk-migration-failed/` and the staged copies are renamed in.
+
+A rename either happened or did not, and each step is idempotent, so a process
+killed during step 3 is finished by the next run (`finish_interrupted_restore`)
+before anything else reads the home. Core refuses to serve and the status
+probe reports `required` while a journal exists.
+
+After SDK authority is committed nothing is restored: the home already belongs
+to the SDK and the legacy tables may be gone.
+"""
+
+from __future__ import annotations
+
+import errno
+import hashlib
+import json
+import os
+import shutil
+import sys
+import time
+from dataclasses import dataclass
+from datetime import UTC, datetime
+from pathlib import Path
+
+from one_memory.database_access import close_main_databases
+from one_memory.hy_runtime_config import HY_MEMORY_NAMESPACE
+from one_memory.sdk_data_plane_migration import DataPlaneMigrationError
+
+RESTORE_POINT = ".sdk-migration-restore-point.json"
+RESTORE_STAGING = ".sdk-migration-restore"
+JOURNAL = "journal.json"
+FAILED_STATE = "sdk-migration-failed"
+RESTORED_MARK = "restored.json"
+DATABASE = "one-memory.sqlite3"
+CONFIG = "config.json"
+_DATABASE_SIDECARS = ("-wal", "-shm", "-journal")
+_WRITER = "core-sdk-migrate"
+
+
+class MigrationRestoreFailed(DataPlaneMigrationError):
+    """The pre-migration data could not be put back; the home stays blocked."""
+
+
+@dataclass(frozen=True)
+class RestoreResult:
+    bundle_id: str
+    files: int
+    bytes: int
+    duration_ms: float
+
+    def as_document(self) -> dict[str, object]:
+        return {
+            "bundle_id": self.bundle_id,
+            "files": self.files,
+            "bytes": self.bytes,
+            "duration_ms": self.duration_ms,
+        }
+
+
+def _home(data_dir: Path) -> Path:
+    return data_dir.resolve()
+
+
+def _staging(home: Path) -> Path:
+    return home / RESTORE_STAGING
+
+
+def _journal(home: Path) -> Path:
+    return _staging(home) / JOURNAL
+
+
+def _sdk_staging(home: Path) -> Path:
+    return home / "hy-memory" / f".{HY_MEMORY_NAMESPACE}.restore-staging"
+
+
+def failed_state_path(data_dir: Path) -> Path:
+    return _home(data_dir) / "backups" / FAILED_STATE
+
+
+def _write_json(path: Path, document: dict[str, object]) -> None:
+    temporary = path.with_name(f"{path.name}.{os.getpid()}.tmp")
+    temporary.write_text(json.dumps(document, sort_keys=True) + "\n", encoding="utf-8")
+    os.chmod(temporary, 0o600)
+    _fsync(temporary)
+    temporary.replace(path)
+    _fsync_directory(path.parent)
+
+
+def _fsync(path: Path) -> None:
+    descriptor = os.open(path, os.O_RDONLY)
+    try:
+        os.fsync(descriptor)
+    finally:
+        os.close(descriptor)
+
+
+def _fsync_directory(path: Path) -> None:
+    # Windows cannot open a directory; its renames are durable on return.
+    try:
+        _fsync(path)
+    except OSError:
+        return
+
+
+def _log(
+    data_dir: Path,
+    event: str,
+    outcome: str,
+    *,
+    migration_id: str | None,
+    code: str | None = None,
+    error: BaseException | None = None,
+    details: dict[str, object] | None = None,
+) -> None:
+    from one_memory.sdk_migration_log import write_migration_log
+
+    write_migration_log(
+        data_dir,
+        writer=_WRITER,
+        event=event,
+        outcome=outcome,
+        migration_id=migration_id,
+        code=code,
+        error=error,
+        details=details,
+    )
+
+
+# --- restore point -----------------------------------------------------------
+
+
+def record_restore_point(data_dir: Path, *, migration_id: str, bundle_id: str) -> None:
+    """Name the verified bundle that holds this home as the migration found it.
+
+    Written before the first change, so a run killed part-way is rolled back
+    by the next one instead of resumed.
+    """
+    _write_json(
+        _home(data_dir) / RESTORE_POINT,
+        {
+            "schema_version": 1,
+            "migration_id": migration_id,
+            "bundle_id": bundle_id,
+            "created_at": datetime.now(UTC).isoformat(),
+        },
+    )
+
+
+def read_restore_point(data_dir: Path) -> dict[str, str] | None:
+    try:
+        document = json.loads((_home(data_dir) / RESTORE_POINT).read_text(encoding="utf-8"))
+    except FileNotFoundError:
+        return None
+    except (OSError, ValueError) as error:
+        raise MigrationRestoreFailed("sdk_migration_restore_point_invalid") from error
+    if (
+        not isinstance(document, dict)
+        or document.get("schema_version") != 1
+        or not isinstance(document.get("migration_id"), str)
+        or not isinstance(document.get("bundle_id"), str)
+    ):
+        raise MigrationRestoreFailed("sdk_migration_restore_point_invalid")
+    return {"migration_id": document["migration_id"], "bundle_id": document["bundle_id"]}
+
+
+def clear_restore_point(data_dir: Path) -> None:
+    (_home(data_dir) / RESTORE_POINT).unlink(missing_ok=True)
+
+
+def restore_pending(data_dir: Path) -> bool:
+    """A restore was interrupted between its renames; nothing may read the home."""
+    return _journal(_home(data_dir)).is_file()
+
+
+# --- restore -----------------------------------------------------------------
+
+
+def _sha256(path: Path) -> str:
+    digest = hashlib.sha256()
+    with path.open("rb") as handle:
+        for chunk in iter(lambda: handle.read(1024 * 1024), b""):
+            digest.update(chunk)
+    return digest.hexdigest()
+
+
+def _release_handles() -> None:
+    """Close what this process holds on the home; Windows cannot rename open files."""
+    close_main_databases()
+    chromadb = sys.modules.get("chromadb")
+    if chromadb is None:
+        return
+    try:
+        from chromadb.api.shared_system_client import SharedSystemClient
+
+        SharedSystemClient.clear_system_cache()
+    except Exception:  # noqa: BLE001 - best effort; a held file fails the rename instead
+        return
+
+
+def _verify_copy(copy: Path, expected: list[dict[str, object]], prefix: str) -> None:
+    """The staged tree holds exactly the bundle's files under `prefix`."""
+    wanted = {
+        str(item["path"])[len(prefix) :]: item
+        for item in expected
+        if str(item["path"]).startswith(prefix)
+    }
+    present = (
+        {path.relative_to(copy).as_posix() for path in copy.rglob("*") if path.is_file()}
+        if copy.is_dir()
+        else set()
+    )
+    if present != set(wanted):
+        raise MigrationRestoreFailed("sdk_migration_restore_verify_failed")
+    for relative, item in wanted.items():
+        path = copy / relative
+        if path.stat().st_size != int(str(item["bytes"])) or _sha256(path) != item["sha256"]:
+            raise MigrationRestoreFailed("sdk_migration_restore_verify_failed")
+
+
+def _plan(home: Path, *, config_staged: bool) -> list[tuple[str, str]]:
+    """Every rename of the swap, as paths relative to the home, in order."""
+    failed = Path("backups") / FAILED_STATE
+    staging = Path(RESTORE_STAGING)
+    sdk_live = Path("hy-memory") / HY_MEMORY_NAMESPACE
+    steps: list[tuple[Path, Path]] = [
+        (Path(f"{DATABASE}{suffix}"), failed / "management" / f"{DATABASE}{suffix}")
+        for suffix in _DATABASE_SIDECARS
+    ]
+    steps += [
+        (Path(DATABASE), failed / "management" / DATABASE),
+        (Path(CONFIG), failed / "management" / CONFIG),
+        (sdk_live, failed / "sdk" / HY_MEMORY_NAMESPACE),
+        (staging / "management" / DATABASE, Path(DATABASE)),
+        (_sdk_staging(home).relative_to(home), sdk_live),
+    ]
+    if config_staged:
+        steps.append((staging / "management" / CONFIG, Path(CONFIG)))
+    return [(source.as_posix(), target.as_posix()) for source, target in steps]
+
+
+def _apply(
+    home: Path,
+    steps: list[list[str]] | list[tuple[str, str]],
+    done: list[tuple[Path, Path]],
+) -> None:
+    """Run each rename once; a step whose source is already gone is skipped.
+
+    `done` collects the renames this call made, so a caller can undo them.
+    """
+    for source_name, target_name in steps:
+        source, target = home / source_name, home / target_name
+        source_exists = source.exists() or source.is_symlink()
+        target_exists = target.exists() or target.is_symlink()
+        if not source_exists:
+            continue
+        if target_exists:
+            raise MigrationRestoreFailed("sdk_migration_restore_conflict")
+        target.parent.mkdir(parents=True, exist_ok=True, mode=0o700)
+        source.replace(target)
+        done.append((source, target))
+    for directory in (home, home / "hy-memory"):
+        _fsync_directory(directory)
+
+
+def _finish(home: Path, bundle_id: str) -> None:
+    # The restore point goes first: a kill after it leaves only the journal,
+    # whose steps are all done, and the next run just tidies up.
+    clear_restore_point(home)
+    shutil.rmtree(_sdk_staging(home), ignore_errors=True)
+    _journal(home).unlink(missing_ok=True)
+    shutil.rmtree(_staging(home), ignore_errors=True)
+    bundle = home / "backups" / f"{bundle_id}.sdk-bundle"
+    try:
+        # A later verified bundle supersedes this one (`prune_restored_bundles`).
+        _write_json(
+            bundle / RESTORED_MARK,
+            {"schema_version": 1, "restored_at": datetime.now(UTC).isoformat()},
+        )
+    except OSError:
+        return
+
+
+def restore_pre_migration_state(
+    data_dir: Path,
+    *,
+    bundle_id: str,
+    migration_id: str | None,
+    reason: str,
+) -> RestoreResult:
+    """Put the restore-point bundle back in place of the half-migrated home.
+
+    The caller holds the migration lock with Runtime stopped and host capture
+    fenced. Raises `MigrationRestoreFailed`; before the swap the home is left as
+    the failure left it, and the restore point stays for the next run.
+    """
+    home = _home(data_dir)
+    started = time.monotonic()
+    _log(
+        home,
+        "restore.started",
+        "started",
+        migration_id=migration_id,
+        details={"bundle_id": bundle_id, "reason": reason},
+    )
+    try:
+        result = _restore(home, bundle_id=bundle_id, started=started)
+    except BaseException as error:
+        code = getattr(error, "code", None)
+        if not (isinstance(code, str) and code.startswith("sdk_migration_restore")):
+            code = (
+                "sdk_migration_restore_disk_space_insufficient"
+                if isinstance(error, OSError) and error.errno in {errno.ENOSPC, errno.EDQUOT}
+                else "sdk_migration_restore_failed"
+            )
+        _log(
+            home,
+            "restore.failed",
+            "failed",
+            migration_id=migration_id,
+            code=code,
+            error=error,
+            details={
+                "bundle_id": bundle_id,
+                "reason": reason,
+                "duration_ms": (time.monotonic() - started) * 1000,
+                "swap_pending": restore_pending(home),
+            },
+        )
+        if not isinstance(error, Exception) or (
+            isinstance(error, MigrationRestoreFailed) and error.code == code
+        ):
+            raise
+        raise MigrationRestoreFailed(code) from error
+    _log(
+        home,
+        "restore.finished",
+        "succeeded",
+        migration_id=migration_id,
+        details={**result.as_document(), "reason": reason},
+    )
+    return result
+
+
+def _restore(home: Path, *, bundle_id: str, started: float) -> RestoreResult:
+    from one_memory.sdk_migration_bundle import inspect_sdk_migration_bundle
+
+    if restore_pending(home):
+        raise MigrationRestoreFailed("sdk_migration_restore_pending")
+    manifest = inspect_sdk_migration_bundle(data_dir=home, bundle_id=bundle_id)
+    bundle = home / "backups" / f"{bundle_id}.sdk-bundle"
+    listed = manifest.get("files")
+    files = [item for item in listed if isinstance(item, dict)] if isinstance(listed, list) else []
+    total = sum(int(str(item["bytes"])) for item in files)
+    if shutil.disk_usage(home).free < total:
+        raise MigrationRestoreFailed("sdk_migration_restore_disk_space_insufficient")
+    _release_handles()
+
+    staging = _staging(home)
+    sdk_staging = _sdk_staging(home)
+    shutil.rmtree(staging, ignore_errors=True)
+    shutil.rmtree(sdk_staging, ignore_errors=True)
+    (staging / "management").mkdir(parents=True, mode=0o700)
+    try:
+        shutil.copy2(bundle / "management" / DATABASE, staging / "management" / DATABASE)
+        config_staged = manifest.get("config") is not None
+        if config_staged:
+            shutil.copy2(bundle / "management" / CONFIG, staging / "management" / CONFIG)
+        _verify_copy(staging / "management", files, "management/")
+        sdk_source = bundle / "sdk" / HY_MEMORY_NAMESPACE
+        if not sdk_source.is_dir() or sdk_source.is_symlink():
+            raise MigrationRestoreFailed("sdk_migration_restore_bundle_incomplete")
+        sdk_staging.parent.mkdir(parents=True, exist_ok=True)
+        shutil.copytree(sdk_source, sdk_staging, symlinks=True)
+        _verify_copy(sdk_staging, files, f"sdk/{HY_MEMORY_NAMESPACE}/")
+        for path in (staging / "management").iterdir():
+            _fsync(path)
+    except BaseException:
+        shutil.rmtree(staging, ignore_errors=True)
+        shutil.rmtree(sdk_staging, ignore_errors=True)
+        raise
+
+    failed = failed_state_path(home)
+    # One failed state is kept for diagnosis; the newest replaces the last.
+    shutil.rmtree(failed, ignore_errors=True)
+    if failed.exists():
+        raise MigrationRestoreFailed("sdk_migration_restore_failed_state_busy")
+    steps = _plan(home, config_staged=config_staged)
+    _write_json(
+        _journal(home),
+        {"schema_version": 1, "bundle_id": bundle_id, "steps": [list(step) for step in steps]},
+    )
+    done: list[tuple[Path, Path]] = []
+    try:
+        _apply(home, steps, done)
+    except BaseException as error:
+        if not isinstance(error, Exception):
+            # Interrupted (a signal tearing the process down): leave the
+            # journal; the next run finishes the swap forward.
+            raise
+        try:
+            for source, target in reversed(done):
+                target.replace(source)
+        except OSError:
+            # The journal stays: the next run finishes the swap forward.
+            raise MigrationRestoreFailed("sdk_migration_restore_swap_interrupted") from error
+        _journal(home).unlink(missing_ok=True)
+        shutil.rmtree(staging, ignore_errors=True)
+        shutil.rmtree(sdk_staging, ignore_errors=True)
+        raise
+    _finish(home, bundle_id)
+    return RestoreResult(
+        bundle_id=bundle_id,
+        files=len(files),
+        bytes=total,
+        duration_ms=(time.monotonic() - started) * 1000,
+    )
+
+
+def finish_interrupted_restore(data_dir: Path, *, migration_id: str | None = None) -> bool:
+    """Complete a swap a killed process left between its renames. True if it did."""
+    home = _home(data_dir)
+    journal = _journal(home)
+    if not journal.is_file():
+        return False
+    started = time.monotonic()
+    try:
+        document = json.loads(journal.read_text(encoding="utf-8"))
+        steps = document["steps"]
+        bundle_id = str(document["bundle_id"])
+        if not isinstance(steps, list) or not all(
+            isinstance(step, list) and len(step) == 2 for step in steps
+        ):
+            raise ValueError("journal steps invalid")
+        _release_handles()
+        _apply(home, steps, [])
+        _finish(home, bundle_id)
+    except Exception as error:
+        code = (
+            error.code
+            if isinstance(error, MigrationRestoreFailed)
+            else "sdk_migration_restore_resume_failed"
+        )
+        _log(
+            home,
+            "restore.failed",
+            "failed",
+            migration_id=migration_id,
+            code=code,
+            error=error,
+            details={"reason": "interrupted_swap", "swap_pending": True},
+        )
+        if isinstance(error, MigrationRestoreFailed):
+            raise
+        raise MigrationRestoreFailed(code) from error
+    _log(
+        home,
+        "restore.finished",
+        "succeeded",
+        migration_id=migration_id,
+        details={
+            "bundle_id": bundle_id,
+            "reason": "interrupted_swap",
+            "duration_ms": (time.monotonic() - started) * 1000,
+        },
+    )
+    return True
+
+
+def prune_restored_bundles(data_dir: Path, *, keep: set[str]) -> int:
+    """Drop bundles already restored, once a newer verified bundle exists.
+
+    Each holds the same pre-migration home a newer bundle now holds (capture
+    stayed fenced since), so it is only a second copy of it.
+    """
+    backups = _home(data_dir) / "backups"
+    removed = 0
+    for mark in backups.glob(f"*.sdk-bundle/{RESTORED_MARK}"):
+        bundle = mark.parent
+        if bundle.name.removesuffix(".sdk-bundle") in keep:
+            continue
+        shutil.rmtree(bundle, ignore_errors=True)
+        removed += 0 if bundle.exists() else 1
+    return removed
+
+
+def discard_failed_state(data_dir: Path) -> None:
+    """The failed half-migrated copy is only useful until a migration succeeds."""
+    shutil.rmtree(failed_state_path(data_dir), ignore_errors=True)

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

@@ -18,6 +18,7 @@ import time
 from collections.abc import Callable, Iterator
 from contextlib import AbstractContextManager, contextmanager
 from dataclasses import dataclass
+from datetime import UTC, datetime
 from pathlib import Path
 from typing import Any
 
@@ -483,30 +484,50 @@ def _resumable_identity(database_path: Path) -> tuple[str, str]:
     return migration_id, f"{migration_id}-pre-cutover"
 
 
-@contextmanager
-def capture_fence(data_dir: Path) -> Iterator[None]:
-    """Host capture hooks return silently while this process is alive."""
+def _write_capture_fence(data_dir: Path, document: dict[str, object]) -> None:
     marker = data_dir / CAPTURE_FENCE
     temporary = marker.with_name(f"{marker.name}.{os.getpid()}.tmp")
-    temporary.write_text(
-        json.dumps({"schema_version": 1, "pid": os.getpid()}) + "\n",
-        encoding="utf-8",
-    )
+    temporary.write_text(json.dumps(document) + "\n", encoding="utf-8")
     os.chmod(temporary, 0o600)
     temporary.replace(marker)
+
+
+@contextmanager
+def capture_fence(data_dir: Path) -> Iterator[None]:
+    """Host capture hooks return silently while this process is alive.
+
+    A failed run leaves the fence frozen instead of lifting it: the home was
+    put back (or is half-migrated) and must not take new writes until the next
+    migration attempt replaces the fence with its own and succeeds.
+    """
+    marker = data_dir / CAPTURE_FENCE
+    _write_capture_fence(data_dir, {"schema_version": 1, "pid": os.getpid()})
     try:
         yield
-    finally:
+    except BaseException:
+        try:
+            _write_capture_fence(
+                data_dir, {"schema_version": 1, "frozen": True, "reason": "sdk_migration_failed"}
+            )
+        except OSError:
+            marker.unlink(missing_ok=True)
+        raise
+    else:
         marker.unlink(missing_ok=True)
-        temporary.unlink(missing_ok=True)
+    finally:
+        marker.with_name(f"{marker.name}.{os.getpid()}.tmp").unlink(missing_ok=True)
 
 
-def _ensure_bundle(*, data_dir: Path, bundle_id: str, runtime_build: str) -> dict[str, object]:
+def _ensure_bundle(
+    *, data_dir: Path, bundle_id: str, runtime_build: str
+) -> tuple[dict[str, object], bool]:
+    """The verified bundle, and whether this call created it."""
     from one_memory.sdk_migration_bundle import (
         MigrationBundleRejected,
         create_sdk_migration_bundle,
     )
 
+    created = True
     try:
         create_sdk_migration_bundle(
             data_dir=data_dir,
@@ -517,7 +538,67 @@ def _ensure_bundle(*, data_dir: Path, bundle_id: str, runtime_build: str) -> dic
     except MigrationBundleRejected as error:
         if error.code != "sdk_migration_bundle_exists":
             raise
-    return inspect_sdk_migration_bundle(data_dir=data_dir, bundle_id=bundle_id)
+        created = False
+    return inspect_sdk_migration_bundle(data_dir=data_dir, bundle_id=bundle_id), created
+
+
+def _restore_point_bundle(
+    *, data_dir: Path, migration_id: str, bundle_id: str, created: bool, runtime_build: str
+) -> str:
+    """The bundle that holds this home exactly as this run found it.
+
+    The cutover bundle qualifies when this run created it. One left by an
+    earlier run (an older build's blocked ledger row) may predate later writes,
+    so restoring it could drop them; a fresh restore-point bundle is taken.
+    """
+    if created:
+        return bundle_id
+    from one_memory.sdk_migration_bundle import create_sdk_migration_bundle
+
+    stamp = datetime.now(UTC).strftime("%Y%m%dT%H%M%S%fZ")
+    restore_id = f"{migration_id}-restore-point-{stamp}"
+    create_sdk_migration_bundle(
+        data_dir=data_dir,
+        bundle_id=restore_id,
+        runtime_build=runtime_build,
+        runtime_stopped=True,
+    )
+    inspect_sdk_migration_bundle(data_dir=data_dir, bundle_id=restore_id)
+    return restore_id
+
+
+def _recover_interrupted_attempt(data_dir: Path, database_path: Path, log: _StepLog) -> None:
+    """Roll back what a killed earlier run left, before anything reads the home."""
+    from one_memory.sdk_migration_restore import (
+        MigrationRestoreFailed,
+        clear_restore_point,
+        finish_interrupted_restore,
+        read_restore_point,
+        restore_pre_migration_state,
+    )
+
+    finish_interrupted_restore(data_dir)
+    point = read_restore_point(data_dir)
+    if point is None:
+        return
+    with log.step("preflight.interrupted_attempt") as step:
+        try:
+            authority = SdkDataPlaneMigrationStore(database_path).authority()
+        except Exception as error:
+            # Never restore over a home that may already be on SDK authority.
+            raise MigrationRestoreFailed("sdk_migration_restore_authority_unknown") from error
+        step["authority"] = authority.value
+        if authority is MemoryAuthority.SDK:
+            clear_restore_point(data_dir)
+            step["restored"] = False
+            return
+        restore_pre_migration_state(
+            data_dir,
+            bundle_id=point["bundle_id"],
+            migration_id=point["migration_id"],
+            reason="interrupted_attempt",
+        )
+        step["restored"] = True
 
 
 def _vacuum(database_path: Path) -> None:
@@ -537,14 +618,28 @@ def run_startup_migration(
     namespace: str,
     progress: Callable[[str], None] = lambda _step: None,
     open_client: Callable[[ModelProfileSnapshot], AbstractContextManager[Any]] | None = None,
+    restore_report: dict[str, object] | None = None,
 ) -> StartupMigrationResult:
     """Bring one stopped home to SDK authority. Safe to repeat after any failure.
 
     The caller must stop Runtime and keep its service from restarting.
     `open_client` yields a public SDK client configured as the Runtime will be;
     tests replace it.
+
+    A failure before SDK authority is committed puts the home back exactly as
+    this run found it (`sdk_migration_restore`), so the next run, possibly of a
+    fixed release, starts from the original data. The original exception is
+    re-raised either way; `restore_report` learns what the restore did
+    (`state`: `restored`, `failed` with its own `code`, or `skipped`).
     """
+    from one_memory.sdk_migration_restore import read_restore_point, restore_pending
+
     database_path = data_dir / "one-memory.sqlite3"
+    log = _StepLog(data_dir)
+    # Before anything reads the home: a run killed part-way is rolled back.
+    if restore_pending(data_dir) or read_restore_point(data_dir) is not None:
+        with capture_fence(data_dir):
+            _recover_interrupted_attempt(data_dir, database_path, log)
     if not database_path.is_file():
         return StartupMigrationResult(state="not_required")
 
@@ -553,7 +648,6 @@ def run_startup_migration(
             return open_client(profile)
         return runtime_sdk_client(database_path, data_dir, profile)
 
-    log = _StepLog(data_dir)
     store = SdkDataPlaneMigrationStore(database_path)
     with log.step("preflight.authority_read") as step:
         authority, authority_migration = store.authority_state()
@@ -613,6 +707,12 @@ def run_startup_migration(
     from one_memory.database_access import close_main_databases
     from one_memory.memory_server.migration_runner import SqliteMigrationStore, migrate
     from one_memory.memory_server.migrations import MIGRATIONS
+    from one_memory.sdk_migration_restore import (
+        clear_restore_point,
+        discard_failed_state,
+        prune_restored_bundles,
+        record_restore_point,
+    )
 
     with log.step("preflight.resumable_identity") as step:
         migration_id, bundle_id = _resumable_identity(database_path)
@@ -630,66 +730,105 @@ def run_startup_migration(
         raise DataPlaneMigrationError("sdk_migration_model_profile_required")
     log.check("preflight.model_profile_check", None)
     with capture_fence(data_dir):
-        progress("bundle")
-        with log.step("bundle.ensure") as step:
-            manifest = _ensure_bundle(
-                data_dir=data_dir,
-                bundle_id=bundle_id,
-                runtime_build=runtime_build,
-            )
-            step["bundle_id"] = bundle_id
-        progress("prepare")
-        with log.step("prepare.schema_migrate") as step:
-            asyncio.run(migrate(SqliteMigrationStore(database_path), MIGRATIONS))
-            close_main_databases()
-            step["schema_version"] = MIGRATIONS[-1].version
+        # Builds through 19 left a staged SDK copy beside the original store.
+        # Settling it before the bundle means the bundle holds the original
+        # store, and a restore never brings the staged copy back.
         with log.step("prepare.recover_abandoned_staging"):
             recover_abandoned_staging(
                 data_dir=data_dir,
                 database_path=database_path,
                 namespace=namespace,
             )
-        with log.step("prepare.ledger_start"):
-            store.start(
-                migration_id=migration_id,
-                source_runtime_build=str(manifest.get("runtime_build") or ""),
-                target_sdk_version=sdk_version,
-                source_schema_version=MIGRATIONS[-1].version,
-                namespace_fingerprint=hashlib.sha256(namespace.encode()).hexdigest(),
-                backend_fingerprint=hashlib.sha256(b"chroma:kuzu:sqlite").hexdigest(),
-                backup_bundle_id=bundle_id,
+        progress("bundle")
+        with log.step("bundle.ensure") as step:
+            manifest, created = _ensure_bundle(
+                data_dir=data_dir,
+                bundle_id=bundle_id,
+                runtime_build=runtime_build,
             )
-        with log.step("prepare.legacy_work") as step:
-            preparation = prepare_legacy_work_for_cutover(database_path, step)
-            step.update(preparation.as_document())
-        reattached = ()
-        readback = None
-        if profile is not None:
-            progress("vectors")
-            with log.step("vectors.reattach") as step:
-                reattached = reattach_legacy_vectors(data_dir, profile)
-                step["collections"] = len(reattached)
-        if not legacy.empty:
-            assert profile is not None
-            progress("verify")
-            with log.step("verify.readback") as step:
-                with client_for(profile) as client:
-                    readback = verify_readback(client, legacy)
-                step.update(readback.as_document())
-                if not readback.passed:
-                    store.set_phase(migration_id, phase="readback_failed", state="blocked")
-                    raise MemoryReadbackFailed(readback)
-        with log.step("prepare.mark_prepared"):
-            store.set_phase(migration_id, phase=PREPARED_PHASE, state="ready")
-        progress("cutover")
-        with log.step("cutover.commit"):
-            commit_sdk_cutover(
+            step["bundle_id"] = bundle_id
+            step["created"] = created
+        with log.step("bundle.restore_point") as step:
+            restore_bundle = _restore_point_bundle(
+                data_dir=data_dir,
+                migration_id=migration_id,
+                bundle_id=bundle_id,
+                created=created,
+                runtime_build=runtime_build,
+            )
+            record_restore_point(data_dir, migration_id=migration_id, bundle_id=restore_bundle)
+            step["bundle_id"] = restore_bundle
+            step["pruned"] = prune_restored_bundles(data_dir, keep={bundle_id, restore_bundle})
+        # From here until SDK authority is committed, a failure puts the
+        # restore point back. Only `cutover.commit` can fail after its own
+        # commit; the database decides then.
+        cutover_started = False
+        try:
+            progress("prepare")
+            with log.step("prepare.schema_migrate") as step:
+                asyncio.run(migrate(SqliteMigrationStore(database_path), MIGRATIONS))
+                close_main_databases()
+                step["schema_version"] = MIGRATIONS[-1].version
+            with log.step("prepare.ledger_start"):
+                store.start(
+                    migration_id=migration_id,
+                    source_runtime_build=str(manifest.get("runtime_build") or ""),
+                    target_sdk_version=sdk_version,
+                    source_schema_version=MIGRATIONS[-1].version,
+                    namespace_fingerprint=hashlib.sha256(namespace.encode()).hexdigest(),
+                    backend_fingerprint=hashlib.sha256(b"chroma:kuzu:sqlite").hexdigest(),
+                    backup_bundle_id=bundle_id,
+                )
+            with log.step("prepare.legacy_work") as step:
+                preparation = prepare_legacy_work_for_cutover(database_path, step)
+                step.update(preparation.as_document())
+            reattached = ()
+            readback = None
+            if profile is not None:
+                progress("vectors")
+                with log.step("vectors.reattach") as step:
+                    reattached = reattach_legacy_vectors(data_dir, profile)
+                    step["collections"] = len(reattached)
+            if not legacy.empty:
+                assert profile is not None
+                progress("verify")
+                with log.step("verify.readback") as step:
+                    with client_for(profile) as client:
+                        readback = verify_readback(client, legacy)
+                    step.update(readback.as_document())
+                    if not readback.passed:
+                        store.set_phase(migration_id, phase="readback_failed", state="blocked")
+                        raise MemoryReadbackFailed(readback)
+            with log.step("prepare.mark_prepared"):
+                store.set_phase(migration_id, phase=PREPARED_PHASE, state="ready")
+            progress("cutover")
+            cutover_started = True
+            with log.step("cutover.commit"):
+                commit_sdk_cutover(
+                    data_dir=data_dir,
+                    database_path=database_path,
+                    migration_id=migration_id,
+                    bundle_id=bundle_id,
+                    sdk_version=sdk_version,
+                )
+        except Exception:
+            _restore_after_failure(
                 data_dir=data_dir,
                 database_path=database_path,
                 migration_id=migration_id,
-                bundle_id=bundle_id,
-                sdk_version=sdk_version,
+                bundle_id=restore_bundle,
+                cutover_started=cutover_started,
+                report=restore_report,
             )
+            raise
+        # SDK authority is committed: from here on the home is never restored.
+        clear_restore_point(data_dir)
+        if restore_bundle != bundle_id:
+            shutil.rmtree(
+                data_dir.resolve() / "backups" / f"{restore_bundle}.sdk-bundle",
+                ignore_errors=True,
+            )
+        discard_failed_state(data_dir)
         progress("cleanup")
         with log.step("cleanup.drop_legacy_tables") as step:
             dropped = resume_legacy_cleanup(data_dir=data_dir, database_path=database_path)
@@ -706,3 +845,52 @@ def run_startup_migration(
         reattached=reattached,
         readback=readback,
     )
+
+
+def _restore_after_failure(
+    *,
+    data_dir: Path,
+    database_path: Path,
+    migration_id: str,
+    bundle_id: str,
+    cutover_started: bool,
+    report: dict[str, object] | None,
+) -> None:
+    """Put the restore point back after a pre-cutover failure. Never raises.
+
+    The caller re-raises the migration's own error: the restore is secondary,
+    so its outcome only goes to the log and to `report`.
+    """
+    from one_memory.sdk_migration_log import write_migration_log
+    from one_memory.sdk_migration_restore import restore_pre_migration_state
+
+    report = {} if report is None else report
+    if cutover_started:
+        try:
+            committed = SdkDataPlaneMigrationStore(database_path).authority() is MemoryAuthority.SDK
+        except Exception:  # noqa: BLE001 - never restore over an unknown authority
+            committed = True
+        if committed:
+            write_migration_log(
+                data_dir,
+                writer="core-sdk-migrate",
+                event="restore.skipped",
+                outcome="succeeded",
+                migration_id=migration_id,
+                details={"reason": "authority_committed_or_unknown"},
+            )
+            report["state"] = "skipped"
+            return
+    try:
+        restore_pre_migration_state(
+            data_dir,
+            bundle_id=bundle_id,
+            migration_id=migration_id,
+            reason="migration_failed",
+        )
+    except Exception as error:  # noqa: BLE001 - the migration's own failure is raised
+        code = getattr(error, "code", None)
+        report["state"] = "failed"
+        report["code"] = code if isinstance(code, str) else "sdk_migration_restore_failed"
+        return
+    report["state"] = "restored"

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

@@ -23,6 +23,21 @@ from one_memory.sdk_data_plane_migration import DataPlaneMigrationError
 _BATCH = 500
 
 
+def open_offline_chroma(directory: Path) -> Any:
+    """A Chroma client on the SDK's vector store, configured as the SDK opens it.
+
+    Chroma refuses a second client on a directory whose shared instance was
+    created with different settings, so offline code must not pass its own.
+    Telemetry is turned off the way the Runtime turns it off, by environment.
+    """
+    import os
+
+    import chromadb
+
+    os.environ["ANONYMIZED_TELEMETRY"] = "False"
+    return chromadb.PersistentClient(path=str(directory))
+
+
 @dataclass(frozen=True)
 class ReattachedCollection:
     legacy: str
@@ -97,45 +112,46 @@ def reattach_legacy_vectors(
     pairs = legacy_vector_collections(data_dir, profile)
     if not pairs:
         return ()
-    import chromadb
-    from chromadb.config import Settings
-
-    client = chromadb.PersistentClient(
-        path=str(_vector_directory(data_dir)),
-        settings=Settings(anonymized_telemetry=False),
-    )
-    existing = set(_stored_names(data_dir))
-    done: list[ReattachedCollection] = []
-    for legacy_name, current_name in pairs:
-        legacy = client.get_collection(legacy_name)
-        legacy_count = legacy.count()
-        merged = 0
-        if current_name in existing:
-            current = client.get_collection(current_name)
-            legacy_ids = set(_ids(legacy))
-            current_ids: set[str] = set()
-            for batch in _records(current):
-                legacy.upsert(**batch)
-                current_ids.update(batch["ids"])
-            merged = len(current_ids)
-            if legacy.count() != len(legacy_ids | current_ids):
-                raise DataPlaneMigrationError("sdk_migration_vector_merge_incomplete")
-            client.delete_collection(current_name)
-        legacy.modify(name=current_name)
-        final = client.get_collection(current_name).count()
-        if final < legacy_count:
-            raise DataPlaneMigrationError("sdk_migration_vector_reattach_incomplete")
-        existing.discard(legacy_name)
-        existing.add(current_name)
-        done.append(
-            ReattachedCollection(
-                legacy=legacy_name,
-                current=current_name,
-                legacy_count=legacy_count,
-                merged_count=merged,
-                final_count=final,
+    client = open_offline_chroma(_vector_directory(data_dir))
+    # Closed, not left to the process: Chroma keeps one shared instance per
+    # directory, and the readback that follows opens the same directory
+    # through the SDK. A leaked instance failed that open on every 1.0.4 home
+    # with legacy vectors, so the first launch after upgrade always failed.
+    try:
+        existing = set(_stored_names(data_dir))
+        done: list[ReattachedCollection] = []
+        for legacy_name, current_name in pairs:
+            legacy = client.get_collection(legacy_name)
+            legacy_count = legacy.count()
+            merged = 0
+            if current_name in existing:
+                current = client.get_collection(current_name)
+                legacy_ids = set(_ids(legacy))
+                current_ids: set[str] = set()
+                for batch in _records(current):
+                    legacy.upsert(**batch)
+                    current_ids.update(batch["ids"])
+                merged = len(current_ids)
+                if legacy.count() != len(legacy_ids | current_ids):
+                    raise DataPlaneMigrationError("sdk_migration_vector_merge_incomplete")
+                client.delete_collection(current_name)
+            legacy.modify(name=current_name)
+            final = client.get_collection(current_name).count()
+            if final < legacy_count:
+                raise DataPlaneMigrationError("sdk_migration_vector_reattach_incomplete")
+            existing.discard(legacy_name)
+            existing.add(current_name)
+            done.append(
+                ReattachedCollection(
+                    legacy=legacy_name,
+                    current=current_name,
+                    legacy_count=legacy_count,
+                    merged_count=merged,
+                    final_count=final,
+                )
             )
-        )
+    finally:
+        client.close()
     return tuple(done)
 
 

memhub/apps/core/tests/TEST_INDEX.md

@@ -68,6 +68,7 @@
 | `test_conversation_search.py` | `integration` | Searching imported conversations before any generation model is configured. |
 | `test_conversation_seed_ids.py` | `contract` | 覆盖 seed ids read metadata only without hydrating、seed eligibility keeps person and memory content only、latest activity includes nonseed turns and import time fallback 等 13 个场景。 |
 | `test_conversation_turn_grouping.py` | `contract` | A proposal and the turn that adopts it must reach HY as one turn. |
+| `test_core_ready_before_recovery.py` | `integration` | Readiness never waits for picking up work an earlier run left unfinished. |
 | `test_core_test_reporting.py` | `contract` | 覆盖 report writes sanitized machine readable views、file and marker aggregates are stable、classification suggestions never guess unit contract or integration 等 6 个场景。 |
 | `test_credential_responsiveness.py` | `integration` | 覆盖 credentials do not block the event loop、disabled automatic processing does not digest onboarding、answering reads credentials off loop 等 5 个场景。 |
 | `test_cursor_default_root_windows.py` | `contract` | R-29 剩余：Cursor 默认根路径不能写死成 macOS。 |
@@ -128,6 +129,7 @@
 | `test_intake_dedupe.py` | `contract` | A4-07: hook and scan share one identity, so order cannot duplicate. |
 | `test_internal_preset.py` | `contract` | The optional model preset a configured build carries. |
 | `test_jsonl_snapshot_tail.py` | `contract` | Bounded EOF handling on synthetic files only, never original host history. |
+| `test_library_search_window.py` | `unit` | The library search window store and the unified record/keyword parsing. |
 | `test_live_capture.py` | `integration` | Visible hook text lands in Evidence before the transcript file is flushed. |
 | `test_live_sync.py` | `contract` | 覆盖 live sync preempts a reader batch before it emits work、live sync cuts in front of a running history import、live sync does not resume a history import the user paused 等 24 个场景。 |
 | `test_live_sync_file_incremental.py` | `contract` | 覆盖 unchanged file metadata avoids a job and content read、changed file content is read once by the import job、workbuddy first live poll baselines history then imports only append 等 6 个场景。 |
@@ -150,12 +152,13 @@
 | `test_measure_c1_import_scale.py` | `contract` | The import measurement must not report fabricated or conflated counters. |
 | `test_measure_c1_loop_blocking_contract.py` | `integration` | Contract guards for the C1 event-loop blocking measurement. |
 | `test_memhub_display_identity.py` | `contract` | Display name MemHub must not fork the technical identity. |
+| `test_memory_additions.py` | `integration` | Add one memory directly: `POST /api/v2/memories` and `GET /api/v2/memories/additions/{id}`. |
 | `test_memory_batch_extraction.py` | `contract` | 覆盖 batch extractor keeps only unique known evidence ids、batch extractor maps provider failure to machine error 场景。 |
 | `test_memory_citation_query_plan.py` | `contract` | Correlated citation checks must look links up by memory, not scan by 'active'. |
 | `test_memory_content_import.py` | `integration` | 覆盖 existing memory preview keeps unknown author and exact original、invalid existing memory records never leave a partial upload、memory content requires explicit mode and rejects vendor guessing 等 5 个场景。 |
 | `test_memory_evidence_freshness.py` | `contract` | 新鲜度拆除后：读路径恒为 current；证据修订 / 畸形 proof / segment ref 不再藏记忆或 503。 |
 | `test_memory_freshness_integration_review.py` | `integration` | Independent synthetic read-path review; no lifespan, model or user database. |
-| `test_memory_notes.py` | `integration` | 覆盖 empty library can save a note without a matter or configured model、note requires authentication explicit scope and nonempty content、saved note evidence returns raw and consent reference from same record 等 6 个场景。 |
+| `test_memory_library_all_scenes.py` | `integration` | The v2 memory library across chat, working and coding memories. |
 | `test_memory_qa.py` | `contract` | 覆盖 search terms keep meaningful single chinese character、streamed answer emits recall then incremental grounded text、governance change during generation stops the old answer 等 14 个场景。 |
 | `test_memory_qa_api.py` | `integration` | 覆盖 ask stream endpoint emits recall deltas and final、ask stream endpoint requires the local token 场景。 |
 | `test_memory_qa_permissions.py` | `contract` | 覆盖 initial refusal precedes all secret access and network、invalid authorization result fails before secret access、authorization receives exact question and only outbound grounding 等 16 个场景。 |
@@ -216,6 +219,7 @@
 | `test_recall_library_scale.py` | `contract` | 覆盖 recall reaches a memory that is not among the newest 500、semantic recall reaches a memory outside the newest 500、recall still works just below the boundary 等 5 个场景。 |
 | `test_recall_log_probe_exclusion.py` | `contract` | A-21：R-10 一旦引入召回日志，「探针不污染」必须自动变红而不是静默失效。 |
 | `test_recall_probe.py` | `contract` | The self-check query, and what it must not touch on its way through. |
+| `test_recall_raw_fallback.py` | `integration` | MemHub_recall degrades to the imported conversations instead of answering empty. |
 | `test_recall_revoked_candidate_crowding.py` | `contract` | Revoked-source rows must not crowd a readable recall hit out of the page. |
 | `test_recall_scope_candidate_budget.py` | `contract` | 覆盖 other scopes cannot consume the recall candidate budget、internal wildcard still reports real candidate truncation、workspace resolution does not remove shared results 等 9 个场景。 |
 | `test_recall_scope_control.py` | `integration` | 覆盖 external scope cannot override shared or host workspace boundary、scope only mutation is versioned without changing status or reindexing 场景。 |
@@ -245,6 +249,7 @@
 | `test_sdk_memory_qa.py` | `contract` | 覆盖 sdk ask propagates sdk search failure without legacy fallback、sdk ask revalidates memory before returning extract、sdk ask uses native sdk memory without governance fields 场景。 |
 | `test_sdk_migration_bundle.py` | `contract` | SDK-authority cutover requires a verified management + SDK data-plane bundle. |
 | `test_sdk_migration_log.py` | `integration` | `sdk-migration.log` explains an unfinished upgrade, and a legacy home is never served. |
+| `test_sdk_migration_restore.py` | `contract` | A failed upgrade migration puts the home back exactly as it found it. |
 | `test_sdk_verbatim_fallback.py` | `contract` | D98: the SDK's verbatim fallback must stay off. |
 | `test_search_without_profile.py` | `contract` | What 'semantic_search' should do once the profile that filled the store is gone. |
 | `test_secondary_source_adapters.py` | `contract` | 覆盖 pi and qwenwork keep tool and sidechain content out of the persons words、qwen code reads only the transcript beside its bookkeeping、qwen native parts preserve visible text not reasoning or tools 等 22 个场景。 |
@@ -302,4 +307,4 @@
 | `test_workspace_recall.py` | `contract` | Workspace memories were unreachable from every host; these pin the way in. |
 | `test_write_queue_lease_renewal.py` | `contract` | Rule 8: a lease must outlive the work it covers, and be renewed while it runs. |
 
-共 297 个测试文件。
+共 302 个测试文件。

memhub/apps/core/tests/core_test_classification.py

@@ -14,8 +14,8 @@ from pathlib import Path
 import pytest
 
 PRIMARY_MARKERS = ("unit", "contract", "integration", "performance", "live")
-EXPECTED_TEST_FILE_COUNT = 297
-EXPECTED_TEST_FILES_SHA256 = "50fc934916818220efdd6259dafb8831c2e568a19fc63e2ea6a9b865d1a75c90"
+EXPECTED_TEST_FILE_COUNT = 302
+EXPECTED_TEST_FILES_SHA256 = "07707528025ac134e46c93ebef12335e852df1ed0f52f8beb62abb3b4d1b0e97"
 
 # Pure transformations, validation models, parity checks and state machines.
 # This list is intentionally small: uncertain files default to contract.
@@ -31,6 +31,7 @@ UNIT_FILES = frozenset(
         "test_graph_width_guard.py",
         "test_host_capabilities.py",
         "test_input_sanitization.py",
+        "test_library_search_window.py",
         "test_memory_server_config_state.py",
         "test_memory_server_contracts.py",
         "test_memory_server_job_state.py",
@@ -51,6 +52,8 @@ INTEGRATION_FILES = frozenset(
     {
         "test_auth.py",
         "test_backup_endpoint.py",
+        "test_recall_raw_fallback.py",
+        "test_core_ready_before_recovery.py",
         "test_backup_restore_api.py",
         "test_c1_import_via_api_path.py",
         "test_capture_deadline.py",
@@ -75,7 +78,8 @@ INTEGRATION_FILES = frozenset(
         "test_measure_c1_loop_blocking_contract.py",
         "test_memory_content_import.py",
         "test_memory_freshness_integration_review.py",
-        "test_memory_notes.py",
+        "test_memory_additions.py",
+        "test_memory_library_all_scenes.py",
         "test_memory_qa_api.py",
         "test_memory_server_durable_queue.py",
         "test_memory_supersede.py",

memhub/apps/core/tests/hourly_c1_import_peak_replay.py

@@ -34,6 +34,7 @@ import subprocess
 import sys
 import tempfile
 import time
+import uuid
 from pathlib import Path
 
 
@@ -201,10 +202,10 @@ def main() -> int:
             receipt["reason"] = "runtime_not_ready"
             return 2
 
-        _run(cli, ["init", "--source", "workbuddy", "--json"], env)
-        plan = _json(_run(cli, ["setup", "plan", "--source", "workbuddy", "--json"], env).stdout)
-        plan_file = work / "plan-inner.json"
-        plan_file.write_text(json.dumps(plan.get("plan", {})), encoding="utf-8")
+        _run(cli, ["sources", "connect", "workbuddy", "--json"], env)
+        # No plan files: the connect request id is the idempotency key, minted
+        # here so the receipt can be read while the import runs.
+        plan = {"plan": {"request_id": str(uuid.uuid4())}}
 
         idle_latencies = []
         idle_errors: list[int] = []
@@ -217,7 +218,15 @@ def main() -> int:
         started = time.perf_counter()
         imported = _run(
             cli,
-            ["sources", "import", "--plan-file", str(plan_file), "--confirm"],
+            [
+                "sources",
+                "connect",
+                "workbuddy",
+                "--import",
+                "--request-id",
+                plan["plan"]["request_id"],
+                "--json",
+            ],
             env,
         )
         during_latencies = []

memhub/apps/core/tests/hourly_c1_package_acceptance.py

@@ -36,6 +36,7 @@ import sqlite3
 import subprocess
 import tempfile
 import time
+import uuid
 from pathlib import Path
 from subprocess import Popen
 
@@ -266,14 +267,22 @@ def _receipt(
 
 
 def _import_plan(cli: Path, env: dict[str, str], work: Path, *sources: str) -> dict:
-    args = ["init"]
-    for source in sources:
-        args.extend(["--source", source])
-    args.append("--json")
-    plan = _body(_run(cli, args, env).stdout)
+    # Grant only (processing stays frozen); the imports below connect again
+    # with --import.
+    plan = _body(_run(cli, ["sources", "connect", *sources, "--json"], env).stdout)
     return plan
 
 
+def _connect_plan(source: str) -> dict:
+    """The request a `sources connect --import` will carry.
+
+    There are no plan files any more: the CLI connects directly and the
+    request id is the idempotency key, so the probe mints it up front to read
+    the receipt afterwards.
+    """
+    return {"plan": {"request_id": str(uuid.uuid4()), "source_ids": [source]}}
+
+
 def _submit_plan(
     cli: Path,
     env: dict[str, str],
@@ -282,9 +291,20 @@ def _submit_plan(
     name: str,
     wait_timeout: float = CONVERGENCE_TIMEOUT_SECONDS,
 ) -> dict:
-    path = work / f"{name}-inner.json"
-    path.write_text(json.dumps(plan.get("plan", {})), encoding="utf-8")
-    result = _run(cli, ["sources", "import", "--plan-file", str(path), "--confirm"], env)
+    body = plan.get("plan", {})
+    result = _run(
+        cli,
+        [
+            "sources",
+            "connect",
+            *body.get("source_ids", []),
+            "--import",
+            "--request-id",
+            str(body.get("request_id")),
+            "--json",
+        ],
+        env,
+    )
     return {
         "exit": result.returncode,
         "receipt": _receipt(cli, env, plan, wait_timeout=wait_timeout),
@@ -394,10 +414,21 @@ def _preserve_run_state(dest: Path, data: Path, receipt: dict, args) -> dict:
 
 def _busy_negative_arm(cli: Path, env: dict[str, str], work: Path, source: str) -> dict:
     """Prove a concurrent history request is refused without a second job."""
-    plan = _body(_run(cli, ["setup", "plan", "--source", source, "--json"], env).stdout)
-    path = work / "busy-inner.json"
-    path.write_text(json.dumps(plan.get("plan", {})), encoding="utf-8")
-    result = _run(cli, ["sources", "import", "--plan-file", str(path), "--confirm"], env)
+    plan = _connect_plan(source)
+    body = plan["plan"]
+    result = _run(
+        cli,
+        [
+            "sources",
+            "connect",
+            source,
+            "--import",
+            "--request-id",
+            body["request_id"],
+            "--json",
+        ],
+        env,
+    )
     return {
         "exit": result.returncode,
         "receipt": _receipt(cli, env, plan, wait_terminal=False),
@@ -408,7 +439,7 @@ def _run_busy_negative(
     cli: Path, env: dict[str, str], work: Path, source: str, timeout: float
 ) -> int:
     """A separate arm: make a real long-running job, then require busy/no-job."""
-    first_plan = _body(_run(cli, ["setup", "plan", "--source", source, "--json"], env).stdout)
+    first_plan = _connect_plan(source)
     first = _submit_plan(cli, env, work, first_plan, "busy-first", timeout)
     first_job = _nested(first, "receipt").get("jobs", [])
     if not first_job or first_job[0].get("status") not in {"running", "pending"}:
@@ -583,22 +614,16 @@ def main() -> int:
         if args.busy_negative:
             return _run_busy_negative(cli, env, work, args.source, args.wait_timeout)
 
-        # Authorize first, then use the same headless plan shape for every
-        # import. `init --json` is a discovery/authorization receipt and its
-        # nested shape differs from `setup plan`.
+        # Authorize first, then connect with --import for every import.
         _import_plan(cli, env, work, args.source)
-        first_plan = _body(
-            _run(cli, ["setup", "plan", "--source", args.source, "--json"], env).stdout
-        )
+        first_plan = _connect_plan(args.source)
         receipt["first"] = _submit_plan(cli, env, work, first_plan, "first", args.wait_timeout)
         if _nested(receipt, "first", "receipt").get("_probe_timeout"):
             receipt["state"] = "failed"
             receipt["reason"] = "convergence_timeout"
             return 1
 
-        second_plan = _body(
-            _run(cli, ["setup", "plan", "--source", args.source, "--json"], env).stdout
-        )
+        second_plan = _connect_plan(args.source)
         receipt["second"] = _submit_plan(cli, env, work, second_plan, "second", args.wait_timeout)
         if _nested(receipt, "second", "receipt").get("_probe_timeout"):
             receipt["state"] = "failed"
@@ -607,9 +632,7 @@ def main() -> int:
 
         with copied[0].open("a", encoding="utf-8") as stream:
             stream.write(json.dumps(_append_record(args.source)) + "\n")
-        append_plan = _body(
-            _run(cli, ["setup", "plan", "--source", args.source, "--json"], env).stdout
-        )
+        append_plan = _connect_plan(args.source)
         receipt["append"] = _submit_plan(cli, env, work, append_plan, "append", args.wait_timeout)
         if _nested(receipt, "append", "receipt").get("_probe_timeout"):
             receipt["state"] = "failed"
@@ -631,9 +654,7 @@ def main() -> int:
             text=True,
         )
         receipt["restart"] = _wait_ready(cli, env, process)
-        restart_plan = _body(
-            _run(cli, ["setup", "plan", "--source", args.source, "--json"], env).stdout
-        )
+        restart_plan = _connect_plan(args.source)
         receipt["restart_import"] = _submit_plan(
             cli, env, work, restart_plan, "restart", args.wait_timeout
         )
@@ -642,18 +663,10 @@ def main() -> int:
             receipt["reason"] = "convergence_timeout"
             return 1
 
-        freeze_plan = _body(
-            _run(
-                cli,
-                ["sync", "pause", "--source", args.source, "--json"],
-                env,
-            ).stdout
-        )
-        freeze_file = work / "freeze-inner.json"
-        freeze_file.write_text(json.dumps(freeze_plan.get("plan", {})), encoding="utf-8")
+        # `sync pause` applies directly (there is no plan/apply pair).
         applied = _run(
             cli,
-            ["sync", "apply", "--plan-file", str(freeze_file), "--confirm"],
+            ["sync", "pause", "--source", args.source, "--json"],
             env,
         )
         listed = _body(_run(cli, ["sources", "list", "--json"], env).stdout)

memhub/apps/core/tests/test_cli_restore.py

@@ -200,6 +200,7 @@ def test_sdk_migrate_failure_is_one_named_code(tmp_path, monkeypatch) -> None:
         "schema_version": 1,
         "state": "failed",
         "code": "sdk_migration_disk_space_insufficient",
+        "data_restored": False,
     }
 
 

memhub/apps/core/tests/test_core_ready_before_recovery.py

@@ -0,0 +1,144 @@
+"""Readiness never waits for picking up work an earlier run left unfinished.
+
+A 1.0.4 home with pending imports and write jobs used to resume all of it
+before the lifespan yielded, so /health did not answer within the Runtime's
+60s budget and the Runtime killed a healthy Core, which then began the same
+recovery again. Recovery now runs after readiness.
+"""
+
+import asyncio
+import threading
+import time
+
+import pytest
+from httpx import ASGITransport, AsyncClient
+from pydantic import SecretStr
+
+from one_memory import hy_sdk_migration
+from one_memory.api import create_app
+from one_memory.config import Settings
+from one_memory.hy_sdk_migration import MetadataRepairResult
+from one_memory.secrets import InMemorySecretStore
+
+pytestmark = pytest.mark.fresh_sdk
+
+
+def application(tmp_path):
+    return create_app(
+        Settings(
+            data_dir=tmp_path / "data",
+            source_home=tmp_path,
+            api_token=SecretStr("ready-test"),
+            imports_enabled=False,
+            automatic_memory_processing=False,
+            live_sync_enabled=False,
+        ),
+        secret_store=InMemorySecretStore(),
+    )
+
+
+def client_for(app):
+    return AsyncClient(
+        transport=ASGITransport(app=app),
+        base_url="http://test",
+        headers={"Authorization": "Bearer ready-test"},
+    )
+
+
+async def health(client):
+    response = await client.get("/api/v1/health")
+    assert response.status_code == 200
+    return response.json()
+
+
+async def wait_for_recovery(client, *, seconds=10.0):
+    deadline = time.monotonic() + seconds
+    while time.monotonic() < deadline:
+        body = await health(client)
+        if body["recovery"] in {"done", "failed"}:
+            return body
+        await asyncio.sleep(0.01)
+    raise AssertionError("recovery did not finish")
+
+
+def test_core_is_ready_while_recovery_is_still_running(tmp_path, monkeypatch):
+    release = threading.Event()
+    entered = threading.Event()
+
+    def slow_repair(**_):
+        entered.set()
+        release.wait(10)
+        return MetadataRepairResult(None, 0, 0, 0)
+
+    monkeypatch.setattr(hy_sdk_migration, "repair_sdk_metadata_from_bundle", slow_repair)
+
+    async def scenario():
+        app = application(tmp_path)
+        try:
+            started = time.monotonic()
+            async with app.router.lifespan_context(app), client_for(app) as client:
+                # Startup finished although the first recovery step cannot.
+                assert time.monotonic() - started < 5
+                assert await asyncio.to_thread(entered.wait, 5)
+                body = await health(client)
+                assert body["status"] == "ok"
+                assert body["recovery"] == "running"
+                # Nothing after the blocked step has been started yet: the
+                # write drain in particular would hold the single writer.
+                assert app.state.memory_write_drain_task is None
+                # Reads answer during recovery.
+                assert (await client.get("/api/v1/sources")).status_code == 200
+                release.set()
+                body = await wait_for_recovery(client)
+                assert body["recovery"] == "done"
+                assert body["recovery_failed_steps"] == []
+                assert app.state.memory_write_drain_task is not None
+        finally:
+            release.set()
+
+    asyncio.run(scenario())
+
+
+def test_a_failed_recovery_step_does_not_stop_readiness_or_later_steps(tmp_path, monkeypatch):
+    def broken_repair(**_):
+        raise OSError("bundle unreadable")
+
+    monkeypatch.setattr(hy_sdk_migration, "repair_sdk_metadata_from_bundle", broken_repair)
+
+    async def scenario():
+        app = application(tmp_path)
+        async with app.router.lifespan_context(app), client_for(app) as client:
+            body = await wait_for_recovery(client)
+            assert body["status"] == "ok"
+            assert body["recovery"] == "failed"
+            assert body["recovery_failed_steps"] == ["sdk_metadata_repair"]
+            # The steps after the failed one still ran.
+            assert app.state.memory_write_drain_task is not None
+
+    asyncio.run(scenario())
+
+
+def test_shutdown_during_recovery_stops_it_without_starting_more(tmp_path, monkeypatch):
+    release = threading.Event()
+    entered = threading.Event()
+
+    def slow_repair(**_):
+        entered.set()
+        release.wait(10)
+        return MetadataRepairResult(None, 0, 0, 0)
+
+    monkeypatch.setattr(hy_sdk_migration, "repair_sdk_metadata_from_bundle", slow_repair)
+
+    async def scenario():
+        app = application(tmp_path)
+        try:
+            async with app.router.lifespan_context(app):
+                assert await asyncio.to_thread(entered.wait, 5)
+                recovery = app.state.recovery_task
+            # Shutdown cancelled recovery before it could start the drain.
+            assert recovery.done()
+            assert app.state.memory_write_drain_task is None
+        finally:
+            release.set()
+
+    asyncio.run(scenario())

memhub/apps/core/tests/test_detailed_logging.py

@@ -110,11 +110,24 @@ def test_log_level_document_migrates_the_old_boolean_shape(tmp_path: Path) -> No
     assert json.loads(target.read_text()) == {"schema_version": 2, "level": "error"}
 
 
-def test_configure_environment_passes_debug_content_settings_to_sdk(tmp_path: Path) -> None:
+def test_configure_environment_passes_debug_content_settings_to_sdk(
+    tmp_path: Path, monkeypatch
+) -> None:
+    for name in (
+        "MEMORY_DATA_DIR",
+        "MEMORY_LOG_DIR",
+        "MEMORY_LOG_LEVEL",
+        "MEMORY_PIPELINE_TRACE_ENABLED",
+        "MEMORY_LOG_LLM_CONTENT",
+    ):
+        monkeypatch.delenv(name, raising=False)
     set_diagnostic_log_level(tmp_path, "debug")
     configure_hy_runtime_environment(tmp_path)
 
     environment = __import__("os").environ
+    memory_root = tmp_path / "hy-memory" / "governed-v2"
+    assert environment["MEMORY_DATA_DIR"] == str(memory_root)
+    assert environment["MEMORY_LOG_DIR"] == str(memory_root / "logs")
     assert environment["MEMORY_LOG_LEVEL"] == "DEBUG"
     assert environment["MEMORY_PIPELINE_TRACE_ENABLED"] == "true"
     assert environment["MEMORY_LOG_LLM_CONTENT"] == "true"

memhub/apps/core/tests/test_health.py

@@ -45,6 +45,9 @@ def test_health_reports_the_single_core() -> None:
         "memory_backfill_error": None,
         "content_candidate_backfill": "idle",
         "content_candidate_backfill_failure": None,
+        # No lifespan ran, so recovery has not begun.
+        "recovery": "pending",
+        "recovery_failed_steps": [],
     }
 
 
@@ -210,6 +213,8 @@ def test_lifespan_drains_committed_pending_dispatch_through_enqueue(tmp_path, mo
 
     async def scenario() -> None:
         async with app.router.lifespan_context(app):
+            # Replayed by the recovery that runs after readiness.
+            await app.state.recovery_task
             assert record.evidence_id in seen
             assert evidence.take_all_stable_records() == ()
 
@@ -434,6 +439,7 @@ def test_a_backfill_that_fails_says_so_rather_than_disappearing(tmp_path, monkey
             app.router.lifespan_context(app),
             AsyncClient(transport=ASGITransport(app=app), base_url="http://test") as client,
         ):
+            await app.state.recovery_task
             await app.state.memory_backfill
 
             response = await client.get("/api/v1/health")
@@ -497,6 +503,7 @@ def test_a_failed_catch_up_leaves_a_traceback_behind(tmp_path, monkeypatch, capl
             app.router.lifespan_context(app),
             AsyncClient(transport=ASGITransport(app=app), base_url="http://test") as client,
         ):
+            await app.state.recovery_task
             with suppress(BaseException):
                 await app.state.memory_backfill
             return (await client.get("/api/v1/health")).json()

memhub/apps/core/tests/test_library_search_window.py

@@ -0,0 +1,118 @@
+"""The library search window store and the unified record/keyword parsing."""
+
+from one_memory.hy_sdk_types import HySdkMemoryPage, HySdkMemoryRecord, library_keyword_hits
+from one_memory.library_search_window import LibrarySearchWindows, window_key
+
+
+def test_window_is_bound_to_its_filters_and_expires_when_idle():
+    now = [0.0]
+    windows = LibrarySearchWindows(ttl_seconds=10, clock=lambda: now[0])
+    key = window_key("deploy", None, ["active"])
+    window = windows.put(key, (), None)
+
+    assert windows.get(window.window_id, key) is window
+    assert windows.get(window.window_id, window_key("deploy", "cursor", ["active"])) is None
+    now[0] = 9.0
+    assert windows.get(window.window_id, key) is window  # reading keeps it alive
+    now[0] = 18.0
+    assert windows.get(window.window_id, key) is window
+    now[0] = 28.5
+    assert windows.get(window.window_id, key) is None
+    assert len(windows) == 0
+
+
+def test_window_store_is_bounded_least_recently_read_first():
+    windows = LibrarySearchWindows(max_windows=2)
+    key = window_key("q", None, ["active"])
+    first = windows.put(key, (), None)
+    second = windows.put(key, (), None)
+    assert windows.get(first.window_id, key) is first
+    third = windows.put(key, (), None)
+    assert len(windows) == 2
+    assert windows.get(second.window_id, key) is None
+    assert windows.get(first.window_id, key) is first
+    assert windows.get(third.window_id, key) is third
+
+
+def test_keyword_hits_read_unified_items_in_fused_order():
+    raw = {
+        "scene": "all",
+        "memories": [
+            {"memory_id": "c1", "scene": "chat", "kind": "chat", "content": "Deploy on Fridays"},
+            {
+                "memory_id": "e1",
+                "experience_id": "e1",
+                "scene": "working",
+                "kind": "experience",
+                "content": "Deploy service\nUse blue/green",
+            },
+            {
+                "memory_id": "f1",
+                "fact_id": "f1",
+                "scene": "coding",
+                "kind": "fact",
+                "content": "Nothing relevant",
+                "statement": "Nothing relevant",
+            },
+            {"memory_id": "c1", "scene": "chat", "kind": "chat", "content": "Deploy on Fridays"},
+        ],
+    }
+    hits, held = library_keyword_hits(raw, "deploy")
+    assert held == 3
+    assert [(hit.memory_id, hit.kind, hit.variant) for hit in hits] == [
+        ("c1", "chat", None),
+        ("e1", "experience", "working"),
+    ]
+
+
+def test_productivity_get_becomes_a_unified_record():
+    record = HySdkMemoryRecord.from_sdk(
+        {
+            "memory_id": "e1",
+            "kind": "experience",
+            "variant": "coding",
+            "scene": "productivity",
+            "content": "solution only",
+            "task": "the task",
+            "solution": "solution only",
+            "user_id": "local",
+            "agent_id": "codebuddy",
+            "source": "codebuddy",
+            "created_at": "2026-10-01T00:00:00",
+            "updated_at": None,
+        }
+    )
+    assert (record.scene, record.kind, record.variant) == ("coding", "experience", "coding")
+    assert record.content == "the task\nsolution only"
+    assert record.status == "active"
+    assert record.created_at == record.updated_at == 1_790_812_800
+
+
+def test_all_scene_list_page_keeps_totals_and_skips_invalid_rows():
+    page, skipped = HySdkMemoryPage.from_sdk_skipping_invalid(
+        {
+            "scene": "all",
+            "memories": [
+                {"memory_id": "c1", "content": "chat", "scene": "chat", "kind": "chat"},
+                {"memory_id": "bad", "content": "", "scene": "chat", "kind": "chat"},
+                {
+                    "memory_id": "f1",
+                    "kind": "fact",
+                    "scene": "working",
+                    "content": "fact",
+                    "status": "active",
+                },
+            ],
+            "total": 3,
+            "totals": {"chat": 2, "working": 1, "coding": 0},
+        },
+        limit=20,
+        offset=0,
+    )
+    assert skipped == 1
+    assert page.total == 3
+    assert page.totals == {"chat": 2, "working": 1, "coding": 0}
+    assert [(m.memory_id, m.scene, m.kind) for m in page.memories] == [
+        ("c1", "chat", "chat"),
+        ("f1", "working", "fact"),
+    ]

memhub/apps/core/tests/test_memory_additions.py

@@ -1,3 +1,5 @@
+"""Add one memory directly: `POST /api/v2/memories` and `GET /api/v2/memories/additions/{id}`."""
+
 import asyncio
 import json
 import sqlite3
@@ -20,7 +22,7 @@ def application(tmp_path):
         Settings(
             data_dir=tmp_path / "data",
             source_home=tmp_path,
-            api_token=SecretStr("note-test"),
+            api_token=SecretStr("memory-add-test"),
             imports_enabled=False,
             automatic_memory_processing=False,
             live_sync_enabled=False,
@@ -39,56 +41,59 @@ def client_for(app):
     return AsyncClient(
         transport=ASGITransport(app=app),
         base_url="http://test",
-        headers={"Authorization": "Bearer note-test"},
+        headers={"Authorization": "Bearer memory-add-test"},
     )
 
 
 @pytest.mark.fresh_sdk
-def test_empty_library_can_save_a_note_without_a_matter_or_configured_model(tmp_path):
+def test_empty_library_can_add_a_memory_without_a_matter_or_configured_model(tmp_path):
     async def scenario():
         app = application(tmp_path)
         async with app.router.lifespan_context(app), client_for(app) as client:
             assert legacy_tables_present(app.state.settings.data_dir / "one-memory.sqlite3") == ()
-            note = {
+            addition = {
                 "request_id": str(uuid4()),
                 "text": "请记住：项目周会不排在周五。",
                 "scope": "all-apps",
             }
-            response = await client.post("/api/v1/memory-notes", json=note)
+            response = await client.post("/api/v2/memories", json=addition)
             assert response.status_code == 201
             saved = response.json()
             assert saved["state"] == "pending"
             assert saved["memory_ids"] == []
-            record = app.state.memory_note_store.require(saved["evidence_id"])
+            record = app.state.memory_addition_store.require(saved["evidence_id"])
             assert record.source_id == "one-memory-manual"
             assert record.role == "user" and record.written_by == WrittenBy.PERSON
-            assert record.verbatim == note["text"] and record.created_at is not None
-            again = await client.post("/api/v1/memory-notes", json=note)
+            assert record.verbatim == addition["text"] and record.created_at is not None
+            again = await client.post("/api/v2/memories", json=addition)
             assert again.json()["evidence_id"] == saved["evidence_id"]
-            operation = await client.get(f"/api/v1/memory-notes/operations/{note['request_id']}")
-            assert operation.status_code == 200
-            assert operation.json()["evidence_id"] == saved["evidence_id"]
-            assert (
-                await client.get(f"/api/v1/memory-notes/operations/{uuid4()}")
-            ).status_code == 404
+            status = await client.get(f"/api/v2/memories/additions/{addition['request_id']}")
+            assert status.status_code == 200
+            assert status.json()["evidence_id"] == saved["evidence_id"]
+            missing = await client.get(f"/api/v2/memories/additions/{uuid4()}")
+            assert missing.status_code == 404
+            assert missing.json()["detail"] == "memory_add_not_found"
             conflict = await client.post(
-                "/api/v1/memory-notes", json={**note, "text": "Changed content"}
+                "/api/v2/memories", json={**addition, "text": "Changed content"}
             )
             assert conflict.status_code == 409
+            assert conflict.json()["detail"] == "memory_add_conflict"
             assert (
-                app.state.memory_note_store.require(saved["evidence_id"]).verbatim == note["text"]
+                app.state.memory_addition_store.require(saved["evidence_id"]).verbatim
+                == addition["text"]
             )
             assert legacy_tables_present(app.state.settings.data_dir / "one-memory.sqlite3") == ()
         restarted = application(tmp_path)
         async with restarted.router.lifespan_context(restarted), client_for(restarted) as client:
-            notes = (await client.get("/api/v1/memory-notes")).json()
-            assert len(notes) == 1 and notes[0]["evidence_id"] == saved["evidence_id"]
+            status = await client.get(f"/api/v2/memories/additions/{addition['request_id']}")
+            assert status.status_code == 200
+            assert status.json()["evidence_id"] == saved["evidence_id"]
 
     asyncio.run(scenario())
 
 
 @pytest.mark.fresh_sdk
-def test_note_requires_authentication_explicit_scope_and_nonempty_content(tmp_path):
+def test_memory_add_requires_authentication_explicit_scope_and_nonempty_content(tmp_path):
     async def scenario():
         app = application(tmp_path)
         async with app.router.lifespan_context(app), client_for(app) as client:
@@ -100,23 +105,26 @@ def test_note_requires_authentication_explicit_scope_and_nonempty_content(tmp_pa
                 {"user_id": "other"},
             ):
                 assert (
-                    await client.post("/api/v1/memory-notes", json={**base, **change})
+                    await client.post("/api/v2/memories", json={**base, **change})
                 ).status_code == 422
             assert (
                 await client.post(
-                    "/api/v1/memory-notes",
+                    "/api/v2/memories",
                     json={"request_id": base["request_id"], "text": "No scope"},
                 )
             ).status_code == 422
             client.headers.pop("Authorization")
-            assert (await client.post("/api/v1/memory-notes", json=base)).status_code == 401
-            assert app.state.memory_note_store.list() == []
+            assert (await client.post("/api/v2/memories", json=base)).status_code == 401
+            status_path = f"/api/v2/memories/additions/{base['request_id']}"
+            assert (await client.get(status_path)).status_code == 401
+            client.headers["Authorization"] = "Bearer memory-add-test"
+            assert (await client.get(status_path)).status_code == 404
 
     asyncio.run(scenario())
 
 
-def test_note_and_source_grant_are_atomic(tmp_path):
-    from one_memory.memory_notes import MemoryNoteInput
+def test_memory_add_and_source_grant_are_atomic(tmp_path):
+    from one_memory.memory_additions import MemoryAddInput
 
     async def scenario():
         app = legacy_application(tmp_path)
@@ -127,8 +135,8 @@ def test_note_and_source_grant_are_atomic(tmp_path):
                     "BEGIN SELECT RAISE(ABORT, 'grant failed'); END"
                 )
             with pytest.raises(sqlite3.IntegrityError, match="grant failed"):
-                app.state.memory_note_store.save(
-                    MemoryNoteInput(
+                app.state.memory_addition_store.save(
+                    MemoryAddInput(
                         request_id=uuid4(), text="Do not leave half a save.", scope="all-apps"
                     )
                 )
@@ -137,22 +145,23 @@ def test_note_and_source_grant_are_atomic(tmp_path):
     asyncio.run(scenario())
 
 
-def test_revoked_note_source_is_not_silently_reauthorized(tmp_path):
+def test_revoked_manual_source_is_not_silently_reauthorized(tmp_path):
     async def scenario():
         app = legacy_application(tmp_path)
         async with app.router.lifespan_context(app), client_for(app) as client:
-            note = {"request_id": str(uuid4()), "text": "Remember this.", "scope": "all-apps"}
-            saved = (await client.post("/api/v1/memory-notes", json=note)).json()
+            addition = {"request_id": str(uuid4()), "text": "Remember this.", "scope": "all-apps"}
+            assert (await client.post("/api/v2/memories", json=addition)).status_code == 201
             with sqlite3.connect(app.state.evidence_store.database_path) as db:
                 db.execute(
                     "UPDATE source_grants SET revoked_at='2026-09-12' "
                     "WHERE source_id='one-memory-manual'"
                 )
-            assert (await client.post("/api/v1/memory-notes", json=note)).status_code == 409
-            assert (
-                await client.post(f"/api/v1/memory-notes/{saved['evidence_id']}/process", json={})
-            ).status_code == 409
-            assert (await client.get("/api/v1/memory-notes")).json() == []
+            again = await client.post("/api/v2/memories", json=addition)
+            assert again.status_code == 409
+            assert again.json()["detail"] == "memory_add_source_revoked"
+            status = await client.get(f"/api/v2/memories/additions/{addition['request_id']}")
+            assert status.status_code == 409
+            assert status.json()["detail"] == "memory_add_source_revoked"
 
     asyncio.run(scenario())
 
@@ -313,6 +322,16 @@ def test_sdk_memory_library_uses_sdk_search_and_skips_empty_rows_without_mutatio
                 include_sources = kwargs.get("include_sources") or []
                 if include_sources:
                     rows = [row for row in rows if row["source"] in include_sources]
+                if kwargs.get("scene") == "all":
+                    return {
+                        "scene": "all",
+                        "memories": [{**row, "scene": "chat", "kind": "chat"} for row in rows],
+                        "total": len(rows),
+                        "totals": {"chat": len(rows), "working": 0, "coding": 0},
+                        "errors": {},
+                        "limit": kwargs["limit"],
+                        "offset": kwargs["offset"],
+                    }
                 return {
                     "vdb": {
                         "memories": rows,
@@ -325,25 +344,28 @@ def test_sdk_memory_library_uses_sdk_search_and_skips_empty_rows_without_mutatio
             def search(self, query, **kwargs):
                 search_calls.append((query, kwargs))
                 return {
-                    "memories": {
-                        "schema": [],
-                        "proactive": [],
-                        "normal": [
-                            {
-                                "memory_id": "release",
-                                "content": "Release plan",
-                                "score": 0.9,
-                            },
-                            {
-                                "memory_id": "retired",
-                                "content": "Release plan, first draft",
-                                "score": 0.8,
-                            },
-                        ],
-                    }
+                    "scene": "all",
+                    "memories": [
+                        {
+                            "memory_id": "release",
+                            "content": "Release plan",
+                            "score": 0.9,
+                            "scene": "chat",
+                            "kind": "chat",
+                        },
+                        {
+                            "memory_id": "retired",
+                            "content": "Release plan, first draft",
+                            "score": 0.8,
+                            "scene": "chat",
+                            "kind": "chat",
+                        },
+                    ],
+                    "lanes": {"chat": 2, "working": 0, "coding": 0},
+                    "errors": {},
                 }
 
-            def get(self, memory_id):
+            def get(self, memory_id, **_namespace):
                 return records.get(memory_id)
 
             def delete(self, memory_id):
@@ -375,7 +397,9 @@ def test_sdk_memory_library_uses_sdk_search_and_skips_empty_rows_without_mutatio
                 assert [item["memory_id"] for item in body["memories"]] == ["release"]
                 assert search_calls[0][0] == "release"
                 assert search_calls[0][1]["include_sources"] == ["cursor"]
-                assert search_calls[0][1]["limit"] == 20
+                assert search_calls[0][1]["limit"] == 200
+                assert search_calls[0][1]["scene"] == "all"
+                assert search_calls[0][1]["rerank"] is False
                 assert search_calls[0][1]["intention_limit"] == 0
                 assert search_calls[0][1]["min_score"] == 0.0
                 assert list_calls == []
@@ -397,6 +421,7 @@ def test_sdk_memory_library_uses_sdk_search_and_skips_empty_rows_without_mutatio
                 assert listed.json()["total"] == 1
                 assert deleted == []
                 assert list_calls[0]["limit"] == 100
+                assert list_calls[0]["scene"] == "all"
                 assert "sdk_memory_invalid_rows_skipped count=1" in caplog.messages
 
                 graph = await client.get("/api/v2/memories/graph")
@@ -457,3 +482,157 @@ def test_sdk_context_search_sets_each_recall_lane_apart(tmp_path):
         ] == [(10, 3, 1), (5, 0, 2)]
 
     asyncio.run(scenario())
+
+
+def _envelope(tools=("om_recall", "om_ask")) -> dict[str, str]:
+    return {
+        "x-one-memory-read-context": "external",
+        "x-one-memory-installation-id": "00000000-0000-0000-0000-000000000001",
+        "x-one-memory-installation-revision": "1",
+        "x-one-memory-allowed-scopes": json.dumps(["all-apps"]),
+        "x-one-memory-allowed-tools": json.dumps(list(tools)),
+    }
+
+
+def _bare_request(method: str, path: str, headers: dict[str, str]):
+    from starlette.requests import Request
+
+    return Request(
+        {
+            "type": "http",
+            "method": method,
+            "path": path,
+            "headers": [(k.encode(), v.encode()) for k, v in headers.items()],
+        }
+    )
+
+
+@pytest.mark.parametrize(
+    ("method", "path"),
+    [
+        ("POST", "/api/v2/memories"),
+        ("GET", f"/api/v2/memories/additions/{uuid4()}"),
+    ],
+)
+def test_memory_add_routes_are_denied_to_enveloped_requests(method, path):
+    """The broker writes as a trusted local caller; an external envelope never
+    reaches the add or status route, whatever tools it carries."""
+    from fastapi import HTTPException
+
+    from one_memory.external_memory_access import TOOLS, require_external_endpoint
+
+    with pytest.raises(HTTPException) as error:
+        require_external_endpoint(_bare_request(method, path, _envelope(sorted(TOOLS))))
+    assert (error.value.status_code, error.value.detail) == (403, "external_endpoint_denied")
+    # A trusted local caller (no envelope) is not refused by this gate.
+    require_external_endpoint(_bare_request(method, path, {}))
+
+
+def test_existing_memories_broker_routes_keep_their_access_rules():
+    """Adding `POST /api/v2/memories` neither opens nor closes the ask routes."""
+    from fastapi import HTTPException
+
+    from one_memory.external_memory_access import require_external_endpoint
+
+    for path in ("/api/v2/memories/ask", "/api/v2/memories/ask/stream"):
+        require_external_endpoint(_bare_request("POST", path, _envelope(("om_ask",))))
+        with pytest.raises(HTTPException) as denied:
+            require_external_endpoint(_bare_request("POST", path, _envelope(("om_recall",))))
+        assert denied.value.detail == "external_recall_scope_denied"
+    for method, path in (
+        ("GET", "/api/v2/memories/some-memory"),
+        ("GET", "/api/v2/memories/graph"),
+        ("PUT", "/api/v2/memories/some-memory"),
+        ("DELETE", "/api/v2/memories/some-memory"),
+    ):
+        with pytest.raises(HTTPException) as denied:
+            require_external_endpoint(_bare_request(method, path, _envelope(("om_ask",))))
+        assert denied.value.detail == "external_endpoint_denied"
+
+
+@pytest.mark.fresh_sdk
+def test_enveloped_memory_add_saves_nothing(tmp_path):
+    async def scenario():
+        app = application(tmp_path)
+        async with app.router.lifespan_context(app), client_for(app) as client:
+            addition = {"request_id": str(uuid4()), "text": "Remember this.", "scope": "all-apps"}
+            refused = await client.post("/api/v2/memories", json=addition, headers=_envelope())
+            assert refused.status_code == 403
+            assert refused.json()["detail"] == "external_endpoint_denied"
+            status = f"/api/v2/memories/additions/{addition['request_id']}"
+            assert (await client.get(status, headers=_envelope())).status_code == 403
+            assert (await client.get(status)).status_code == 404
+
+    asyncio.run(scenario())
+
+
+@pytest.mark.fresh_sdk
+def test_memory_add_routes_do_not_collide_with_single_memory_routes(tmp_path):
+    """`/additions/{request_id}` is two segments and the add is a POST on the
+    collection: neither may be served by `/api/v2/memories/{memory_id}`."""
+    sdk_calls: list[tuple[str, object]] = []
+
+    class Client:
+        def __getattr__(self, name):
+            def record(*args, **kwargs):
+                sdk_calls.append((name, args))
+                return None
+
+            return record
+
+    class Handle:
+        async def client(self):
+            return Client()
+
+        async def close(self):
+            return None
+
+    async def scenario():
+        app = application(tmp_path)
+        request_id = str(uuid4())
+        async with app.router.lifespan_context(app), client_for(app) as client:
+            app.state.sdk_client_handle = Handle()
+            missing = await client.get(f"/api/v2/memories/additions/{request_id}")
+            assert missing.status_code == 404
+            assert missing.json()["detail"] == "memory_add_not_found"
+            created = await client.post(
+                "/api/v2/memories",
+                json={"request_id": request_id, "text": "Remember this.", "scope": "all-apps"},
+            )
+            assert created.status_code == 201
+            assert set(created.json()) == {
+                "evidence_id",
+                "text",
+                "scope",
+                "created_at",
+                "state",
+                "task_id",
+                "memory_ids",
+                "error",
+            }
+            status = await client.get(f"/api/v2/memories/additions/{request_id}")
+            assert status.json()["evidence_id"] == created.json()["evidence_id"]
+            # Neither route reached the single-memory SDK reads ...
+            assert not [call for call in sdk_calls if call[0] == "get"]
+            # ... while a single segment still does, even one named `additions`.
+            await client.get("/api/v2/memories/additions")
+            await client.get("/api/v2/memories/some-memory")
+            assert [call[1][0] for call in sdk_calls if call[0] == "get"] == [
+                "additions",
+                "some-memory",
+            ]
+            # The old note surface is gone.
+            assert (await client.get("/api/v1/memory-notes")).status_code == 404
+            assert (
+                await client.post(
+                    "/api/v1/memory-notes",
+                    json={"request_id": str(uuid4()), "text": "x", "scope": "all-apps"},
+                )
+            ).status_code == 404
+            schema = (await client.get("/openapi.json")).json()
+            assert "MemoryAddReceipt" in schema["components"]["schemas"]
+            assert "MemoryAddInput" in schema["components"]["schemas"]
+            assert not [name for name in schema["components"]["schemas"] if "Note" in name]
+            assert not [path for path in schema["paths"] if "note" in path]
+
+    asyncio.run(scenario())

memhub/apps/core/tests/test_memory_library_all_scenes.py

@@ -0,0 +1,649 @@
+"""The v2 memory library across chat, working and coding memories.
+
+Keyword search pages are cut from one cached SDK result window (window_id),
+the empty-query list mixes the three scenes newest first, and detail, edit
+and delete pass the memory's kind/variant through to the SDK.
+"""
+
+import asyncio
+
+import pytest
+from httpx import ASGITransport, AsyncClient
+from hy_memory import AmbiguousMemoryIdError
+from pydantic import SecretStr
+
+from one_memory.api import create_app
+from one_memory.config import Settings
+from one_memory.library_search_window import LibrarySearchWindows
+from one_memory.secrets import InMemorySecretStore
+
+
+def application(tmp_path):
+    return create_app(
+        Settings(
+            data_dir=tmp_path / "data",
+            source_home=tmp_path,
+            api_token=SecretStr("library-test"),
+            imports_enabled=False,
+            automatic_memory_processing=False,
+            live_sync_enabled=False,
+        ),
+        secret_store=InMemorySecretStore(),
+    )
+
+
+def client_for(app):
+    return AsyncClient(
+        transport=ASGITransport(app=app),
+        base_url="http://test",
+        headers={"Authorization": "Bearer library-test"},
+    )
+
+
+def chat_row(memory_id, content, *, source="cursor"):
+    return {
+        "memory_id": memory_id,
+        "content": content,
+        "layer": "l2_fact",
+        "status": "active",
+        "user_id": "local",
+        "agent_id": "all-apps",
+        "session_id": "s1",
+        "source": source,
+        "tags": [],
+        "gmt_created": 1_790_000_000,
+    }
+
+
+def experience_row(memory_id, task, solution, *, variant="working", source="codebuddy"):
+    return {
+        "experience_id": memory_id,
+        "user_id": "local",
+        "agent_id": "codebuddy",
+        "task": task,
+        "solution": solution,
+        "source": source,
+        "created_at": "2026-10-01T08:00:00",
+        "updated_at": "2026-10-02T08:00:00",
+        "_variant": variant,
+    }
+
+
+def fact_row(memory_id, statement, *, variant="coding", source="codebuddy"):
+    return {
+        "fact_id": memory_id,
+        "user_id": "local",
+        "agent_id": "codebuddy",
+        "statement": statement,
+        "status": "active",
+        "source": source,
+        "created_at": "2026-10-03T08:00:00",
+        "_variant": variant,
+    }
+
+
+class FakeSdk:
+    """Public-API shaped client holding chat, experience and fact memories."""
+
+    def __init__(self):
+        self.chat = {}
+        self.productivity = {}
+        self.search_calls = []
+        self.list_calls = []
+        self.get_calls = []
+        self.update_calls = []
+        self.delete_calls = []
+        self.reverse_next_search = False
+
+    def add_chat(self, row):
+        self.chat[row["memory_id"]] = row
+
+    def add_productivity(self, kind, row):
+        memory_id = row["experience_id"] if kind == "experience" else row["fact_id"]
+        self.productivity[(kind, row["_variant"], memory_id)] = row
+
+    def _unified(self, kind, variant, row):
+        if kind == "experience":
+            content = f"{row['task']}\n{row['solution']}"
+            memory_id = row["experience_id"]
+        else:
+            content = row["statement"]
+            memory_id = row["fact_id"]
+        return {
+            **{key: value for key, value in row.items() if not key.startswith("_")},
+            "scene": variant,
+            "kind": kind,
+            "memory_id": memory_id,
+            "content": content,
+            "created_at": 1_790_000_000,
+            "updated_at": 1_790_000_100,
+        }
+
+    def _matches(self, memory_id, kind, variant):
+        found = []
+        if kind in (None, "chat") and variant is None and memory_id in self.chat:
+            found.append(("chat", None, self.chat[memory_id]))
+        for (row_kind, row_variant, row_id), row in self.productivity.items():
+            if row_id != memory_id:
+                continue
+            if kind not in (None, row_kind) or variant not in (None, row_variant):
+                continue
+            found.append((row_kind, row_variant, row))
+        if len(found) > 1:
+            raise AmbiguousMemoryIdError(
+                memory_id,
+                [f"{v}:{k}" if v else k for k, v, _ in found],
+            )
+        return found[0] if found else None
+
+    def search(self, query, **kwargs):
+        self.search_calls.append((query, kwargs))
+        include = kwargs.get("include_sources") or []
+        items = [
+            {**row, "scene": "chat", "kind": "chat"}
+            for row in self.chat.values()
+            if not include or row["source"] in include
+        ]
+        items += [
+            self._unified(kind, variant, row)
+            for (kind, variant, _id), row in self.productivity.items()
+            if not include or row["source"] in include
+        ]
+        if self.reverse_next_search:
+            items.reverse()
+        items = items[: kwargs["limit"]]
+        for rank, item in enumerate(items, start=1):
+            item["score"] = round(1 / (60 + rank), 6)
+        return {
+            "request_id": "search",
+            "scene": "all",
+            "memories": items,
+            "lanes": {"chat": 0, "working": 0, "coding": 0},
+            "errors": {},
+            "elapsed_ms": 1.0,
+        }
+
+    def list_memories(self, **kwargs):
+        self.list_calls.append(kwargs)
+        include = kwargs.get("include_sources") or []
+        scene = kwargs["scene"]
+        start, stop = kwargs["offset"], kwargs["offset"] + kwargs["limit"]
+        if scene == "chat":
+            rows = [row for row in self.chat.values() if not include or row["source"] in include]
+            return {
+                "vdb": {
+                    "memories": rows[start:stop],
+                    "total": len(rows),
+                    "limit": kwargs["limit"],
+                    "offset": kwargs["offset"],
+                },
+                "elapsed_ms": 1.0,
+            }
+        if scene in ("working", "coding"):
+            rows = [
+                {key: value for key, value in row.items() if not key.startswith("_")}
+                | {"status": "active"}
+                for (kind, variant, _id), row in self.productivity.items()
+                if kind == "experience"
+                and variant == scene
+                and (not include or row["source"] in include)
+            ]
+            return {
+                "request_id": "list",
+                "scene": "productivity",
+                "variant": scene,
+                "experiences": rows[start:stop],
+                "total": len(rows),
+                "limit": kwargs["limit"],
+                "offset": kwargs["offset"],
+                "elapsed_ms": 1.0,
+            }
+        assert scene == "all"
+        chat = [
+            {**row, "scene": "chat", "kind": "chat", "created_at": 10, "updated_at": 10}
+            for row in self.chat.values()
+            if not include or row["source"] in include
+        ]
+        productivity = [
+            {**self._unified(kind, variant, row), "status": "active"}
+            for (kind, variant, _id), row in self.productivity.items()
+            if kind == "experience" and (not include or row["source"] in include)
+        ]
+        rows = productivity + chat
+        page = rows[kwargs["offset"] : kwargs["offset"] + kwargs["limit"]]
+        return {
+            "scene": "all",
+            "memories": page,
+            "total": len(rows),
+            "totals": {
+                "chat": len(chat),
+                "working": sum(1 for row in productivity if row["scene"] == "working"),
+                "coding": sum(1 for row in productivity if row["scene"] == "coding"),
+            },
+            "errors": {},
+            "limit": kwargs["limit"],
+            "offset": kwargs["offset"],
+            "request_id": "list",
+            "elapsed_ms": 1.0,
+        }
+
+    def get(self, memory_id, kind=None, variant=None):
+        self.get_calls.append((memory_id, kind, variant))
+        match = self._matches(memory_id, kind, variant)
+        if match is None:
+            return None
+        row_kind, row_variant, row = match
+        if row_kind == "chat":
+            return {**row, "kind": "chat", "variant": None}
+        payload = {key: value for key, value in row.items() if not key.startswith("_")}
+        return {
+            "memory_id": memory_id,
+            "kind": row_kind,
+            "variant": row_variant,
+            "scene": "productivity",
+            "content": row["solution"] if row_kind == "experience" else row["statement"],
+            "layer": row_kind,
+            **payload,
+        }
+
+    def update(self, memory_id, content, kind=None, variant=None, task=None):
+        self.update_calls.append((memory_id, content, kind, variant, task))
+        match = self._matches(memory_id, kind, variant)
+        if match is None:
+            return {"success": False, "error_message": f"memory_id '{memory_id}' not found"}
+        row_kind, row_variant, row = match
+        if row_kind == "chat":
+            row["content"] = content
+            return {"success": True, "memory_id": memory_id}
+        if row_kind == "experience":
+            row["solution"] = content
+            if task is not None:
+                row["task"] = task
+        else:
+            row["statement"] = content
+        return {"success": True, "memory_id": memory_id, "kind": row_kind, "variant": row_variant}
+
+    def delete(self, memory_id, kind=None, variant=None):
+        self.delete_calls.append((memory_id, kind, variant))
+        match = self._matches(memory_id, kind, variant)
+        if match is None:
+            return {"success": False, "deleted_count": 0}
+        row_kind, row_variant, row = match
+        if row_kind == "chat":
+            del self.chat[memory_id]
+        else:
+            del self.productivity[(row_kind, row_variant, memory_id)]
+        return {"success": True, "deleted_count": 1}
+
+
+def run_with_sdk(tmp_path, monkeypatch, scenario):
+    async def main():
+        app = application(tmp_path)
+        sdk = FakeSdk()
+
+        class Handle:
+            async def client(self):
+                return sdk
+
+            async def close(self):
+                return None
+
+        async def write_client():
+            return sdk
+
+        async with app.router.lifespan_context(app):
+            app.state.sdk_client_handle = Handle()
+            monkeypatch.setattr(app.state.sdk_write_coordinator, "client", write_client)
+            async with client_for(app) as client:
+                await scenario(app, sdk, client)
+
+    asyncio.run(main())
+
+
+@pytest.mark.fresh_sdk
+def test_search_pages_come_from_one_cached_window_without_duplicates(tmp_path, monkeypatch):
+    async def scenario(app, sdk, client):
+        for index in range(30):
+            sdk.add_chat(chat_row(f"chat-{index:02d}", f"deploy note {index}"))
+        for index in range(15):
+            sdk.add_productivity(
+                "experience",
+                experience_row(f"exp-{index:02d}", f"deploy task {index}", "run make"),
+            )
+        sdk.add_chat(chat_row("other", "unrelated words"))
+
+        first = await client.get("/api/v2/memory-library", params={"query": "deploy"})
+        assert first.status_code == 200
+        body = first.json()
+        assert body["total"] == 45
+        assert body["limit"] == 20
+        assert body["offset"] == 0
+        assert body["window_reset"] is False
+        assert body["search_window"] is None
+        window_id = body["window_id"]
+        assert window_id
+        assert len(sdk.search_calls) == 1
+        query, options = sdk.search_calls[0]
+        assert query == "deploy"
+        assert options["scene"] == "all"
+        assert options["rerank"] is False
+        assert options["limit"] == 200
+        assert options["min_score"] == 0.0
+
+        # A second search would now rank differently; pages must not care.
+        sdk.reverse_next_search = True
+        seen = [item["memory_id"] for item in body["memories"]]
+        for offset in (20, 40):
+            page = await client.get(
+                "/api/v2/memory-library",
+                params={"query": "deploy", "offset": offset, "window_id": window_id},
+            )
+            assert page.status_code == 200
+            data = page.json()
+            assert data["window_id"] == window_id
+            assert data["window_reset"] is False
+            assert data["offset"] == offset
+            assert data["total"] == 45
+            seen += [item["memory_id"] for item in data["memories"]]
+        assert len(sdk.search_calls) == 1
+        assert len(seen) == 45
+        assert len(set(seen)) == 45
+        scenes = {item["memory_id"]: item for item in body["memories"]}
+        assert {item["scene"] for item in scenes.values()} <= {"chat", "working"}
+
+        # Each productivity row is read back in the namespace it was found in.
+        productivity_gets = [call for call in sdk.get_calls if call[0].startswith("exp-")]
+        assert productivity_gets
+        assert all(call[1:] == ("experience", "working") for call in productivity_gets)
+        chat_gets = [call for call in sdk.get_calls if call[0].startswith("chat-")]
+        assert all(call[1:] == ("chat", None) for call in chat_gets)
+
+    run_with_sdk(tmp_path, monkeypatch, scenario)
+
+
+@pytest.mark.fresh_sdk
+def test_expired_or_mismatched_window_searches_again_and_restarts(tmp_path, monkeypatch):
+    async def scenario(app, sdk, client):
+        now = [1000.0]
+        app.state.library_search_windows = LibrarySearchWindows(
+            ttl_seconds=60, clock=lambda: now[0]
+        )
+        for index in range(25):
+            sdk.add_chat(chat_row(f"chat-{index:02d}", f"deploy note {index}"))
+
+        first = (await client.get("/api/v2/memory-library", params={"query": "deploy"})).json()
+        window_id = first["window_id"]
+
+        now[0] += 61
+        expired = await client.get(
+            "/api/v2/memory-library",
+            params={"query": "deploy", "offset": 20, "window_id": window_id},
+        )
+        data = expired.json()
+        assert data["window_reset"] is True
+        assert data["offset"] == 0
+        assert data["window_id"] != window_id
+        assert len(data["memories"]) == 20
+        assert len(sdk.search_calls) == 2
+
+        # A window searched for other words is not reused for this query.
+        mismatched = await client.get(
+            "/api/v2/memory-library",
+            params={"query": "note", "offset": 20, "window_id": data["window_id"]},
+        )
+        assert mismatched.json()["window_reset"] is True
+        assert mismatched.json()["offset"] == 0
+
+        unknown = await client.get(
+            "/api/v2/memory-library",
+            params={"query": "deploy", "window_id": "never-issued"},
+        )
+        assert unknown.json()["window_reset"] is True
+
+    run_with_sdk(tmp_path, monkeypatch, scenario)
+
+
+@pytest.mark.fresh_sdk
+def test_keyword_filter_reads_experience_and_fact_text(tmp_path, monkeypatch):
+    async def scenario(app, sdk, client):
+        sdk.add_chat(chat_row("chat-1", "lunch preferences"))
+        sdk.add_productivity(
+            "experience",
+            experience_row("exp-1", "Fix flaky tests", "Pin the pytest seed"),
+        )
+        sdk.add_productivity("fact", fact_row("fact-1", "The pytest suite runs in CI"))
+
+        response = await client.get(
+            "/api/v2/memory-library", params={"query": "PYTEST", "source": "codebuddy"}
+        )
+        body = response.json()
+        assert body["total"] == 2
+        assert sdk.search_calls[0][1]["include_sources"] == ["codebuddy"]
+        by_id = {item["memory_id"]: item for item in body["memories"]}
+        experience = by_id["exp-1"]
+        assert experience["scene"] == "working"
+        assert experience["kind"] == "experience"
+        assert experience["variant"] == "working"
+        assert experience["task"] == "Fix flaky tests"
+        assert experience["solution"] == "Pin the pytest seed"
+        assert experience["content"] == "Fix flaky tests\nPin the pytest seed"
+        assert experience["status"] == "active"
+        assert experience["updated_at"] > experience["created_at"]
+        fact = by_id["fact-1"]
+        assert (fact["scene"], fact["kind"], fact["variant"]) == ("coding", "fact", "coding")
+        assert fact["content"] == "The pytest suite runs in CI"
+
+    run_with_sdk(tmp_path, monkeypatch, scenario)
+
+
+@pytest.mark.fresh_sdk
+def test_full_search_window_is_reported(tmp_path, monkeypatch):
+    async def scenario(app, sdk, client):
+        for index in range(205):
+            sdk.add_chat(chat_row(f"chat-{index:03d}", f"note {index}"))
+        body = (await client.get("/api/v2/memory-library", params={"query": "note"})).json()
+        assert body["search_window"] == 200
+        assert body["total"] == 200
+
+    run_with_sdk(tmp_path, monkeypatch, scenario)
+
+
+@pytest.mark.fresh_sdk
+def test_empty_query_lists_all_scenes_with_source_filter_and_totals(tmp_path, monkeypatch):
+    async def scenario(app, sdk, client):
+        sdk.add_chat(chat_row("chat-1", "cursor chat", source="cursor"))
+        sdk.add_chat(chat_row("chat-2", "codebuddy chat", source="codebuddy"))
+        sdk.add_productivity("experience", experience_row("exp-w", "task w", "solution w"))
+        sdk.add_productivity(
+            "experience", experience_row("exp-c", "task c", "solution c", variant="coding")
+        )
+
+        response = await client.get("/api/v2/memory-library")
+        body = response.json()
+        assert response.status_code == 200
+        assert body["limit"] == 20
+        assert body["total"] == 4
+        assert body["totals"] == {"chat": 2, "working": 1, "coding": 1}
+        assert body["window_id"] is None
+        assert [item["scene"] for item in body["memories"]] == [
+            "working",
+            "coding",
+            "chat",
+            "chat",
+        ]
+        call = sdk.list_calls[0]
+        assert call["scene"] == "all"
+        assert call["include_sources"] is None
+        assert call["statuses"] == ["active"]
+        assert (call["offset"], call["limit"]) == (0, 20)
+
+        filtered = await client.get(
+            "/api/v2/memory-library", params={"source": "codebuddy", "offset": 1}
+        )
+        data = filtered.json()
+        assert sdk.list_calls[1]["include_sources"] == ["codebuddy"]
+        assert sdk.list_calls[1]["offset"] == 1
+        assert data["total"] == 3
+        assert data["offset"] == 1
+        assert [item["memory_id"] for item in data["memories"]] == ["exp-c", "chat-2"]
+
+    run_with_sdk(tmp_path, monkeypatch, scenario)
+
+
+@pytest.mark.fresh_sdk
+def test_detail_edit_delete_pass_kind_and_variant(tmp_path, monkeypatch):
+    async def scenario(app, sdk, client):
+        sdk.add_chat(chat_row("chat-1", "hello"))
+        sdk.add_productivity("experience", experience_row("exp-1", "Old task", "Old solution"))
+        sdk.add_productivity("fact", fact_row("fact-1", "Old statement"))
+
+        detail = await client.get(
+            "/api/v2/memories/exp-1", params={"kind": "experience", "variant": "working"}
+        )
+        assert detail.status_code == 200
+        record = detail.json()
+        assert (record["scene"], record["kind"], record["variant"]) == (
+            "working",
+            "experience",
+            "working",
+        )
+        assert record["task"] == "Old task"
+        assert record["solution"] == "Old solution"
+        assert record["content"] == "Old task\nOld solution"
+        assert sdk.get_calls[-1] == ("exp-1", "experience", "working")
+
+        # Chat detail with no namespace keeps the plain SDK call.
+        chat = await client.get("/api/v2/memories/chat-1")
+        assert chat.json()["kind"] == "chat"
+        assert chat.json()["scene"] == "chat"
+        assert sdk.get_calls[-1] == ("chat-1", None, None)
+
+        edited = await client.put(
+            "/api/v2/memories/exp-1",
+            json={
+                "content": "New solution",
+                "task": "New task",
+                "kind": "experience",
+                "variant": "working",
+            },
+        )
+        assert edited.status_code == 200
+        assert sdk.update_calls[-1] == (
+            "exp-1",
+            "New solution",
+            "experience",
+            "working",
+            "New task",
+        )
+        assert edited.json()["solution"] == "New solution"
+        assert edited.json()["task"] == "New task"
+
+        fact = await client.put(
+            "/api/v2/memories/fact-1",
+            json={"content": "New statement", "kind": "fact", "variant": "coding"},
+        )
+        assert fact.status_code == 200
+        assert fact.json()["content"] == "New statement"
+        refused = await client.put(
+            "/api/v2/memories/fact-1",
+            json={"content": "x", "task": "y", "kind": "fact"},
+        )
+        assert refused.status_code == 422
+
+        deleted = await client.delete(
+            "/api/v2/memories/fact-1", params={"kind": "fact", "variant": "coding"}
+        )
+        assert deleted.status_code == 204
+        assert sdk.delete_calls[-1] == ("fact-1", "fact", "coding")
+
+        bad = await client.get("/api/v2/memories/exp-1", params={"kind": "nope"})
+        assert bad.status_code == 422
+
+    run_with_sdk(tmp_path, monkeypatch, scenario)
+
+
+@pytest.mark.fresh_sdk
+def test_ambiguous_memory_id_is_a_conflict(tmp_path, monkeypatch):
+    async def scenario(app, sdk, client):
+        sdk.add_chat(chat_row("dup", "chat text"))
+        sdk.add_productivity("experience", experience_row("dup", "task", "solution"))
+
+        for method in ("get", "delete"):
+            response = await getattr(client, method)("/api/v2/memories/dup")
+            assert response.status_code == 409
+            assert response.json()["detail"] == "memory_id_ambiguous"
+        update = await client.put("/api/v2/memories/dup", json={"content": "x"})
+        assert update.status_code == 409
+        assert update.json()["detail"] == "memory_id_ambiguous"
+
+        resolved = await client.get("/api/v2/memories/dup", params={"kind": "chat"})
+        assert resolved.status_code == 200
+        assert resolved.json()["content"] == "chat text"
+
+    run_with_sdk(tmp_path, monkeypatch, scenario)
+
+
+@pytest.mark.fresh_sdk
+def test_scene_filter_lists_one_scene(tmp_path, monkeypatch):
+    async def scenario(app, sdk, client):
+        sdk.add_chat(chat_row("chat-1", "chat text"))
+        sdk.add_productivity("experience", experience_row("work-1", "w task", "w fix"))
+        sdk.add_productivity(
+            "experience", experience_row("code-1", "c task", "c fix", variant="coding")
+        )
+
+        working = await client.get("/api/v2/memory-library", params={"scene": "working"})
+        assert working.status_code == 200
+        body = working.json()
+        assert body["total"] == 1
+        assert [item["memory_id"] for item in body["memories"]] == ["work-1"]
+        assert body["memories"][0]["kind"] == "experience"
+        assert body["memories"][0]["variant"] == "working"
+        assert body["memories"][0]["scene"] == "working"
+        assert sdk.list_calls[-1]["scene"] == "working"
+
+        chat = await client.get("/api/v2/memory-library", params={"scene": "chat"})
+        assert chat.status_code == 200
+        assert [item["memory_id"] for item in chat.json()["memories"]] == ["chat-1"]
+        assert sdk.list_calls[-1]["scene"] == "chat"
+
+        default = await client.get("/api/v2/memory-library")
+        assert default.status_code == 200
+        assert sdk.list_calls[-1]["scene"] == "all"
+
+        bad = await client.get("/api/v2/memory-library", params={"scene": "normal"})
+        assert bad.status_code == 422
+
+    run_with_sdk(tmp_path, monkeypatch, scenario)
+
+
+@pytest.mark.fresh_sdk
+def test_scene_filter_narrows_search_and_binds_the_window(tmp_path, monkeypatch):
+    async def scenario(app, sdk, client):
+        sdk.add_chat(chat_row("chat-1", "deploy chat"))
+        sdk.add_productivity("experience", experience_row("work-1", "deploy task", "run make"))
+        sdk.add_productivity(
+            "experience",
+            experience_row("code-1", "deploy code", "run tests", variant="coding"),
+        )
+
+        coding = await client.get(
+            "/api/v2/memory-library", params={"query": "deploy", "scene": "coding"}
+        )
+        assert coding.status_code == 200
+        body = coding.json()
+        assert body["total"] == 1
+        assert [item["memory_id"] for item in body["memories"]] == ["code-1"]
+        assert sdk.search_calls[-1][1]["scene"] == "all"
+
+        # The same window under another scene is a different search.
+        other = await client.get(
+            "/api/v2/memory-library",
+            params={"query": "deploy", "scene": "chat", "window_id": body["window_id"]},
+        )
+        assert other.status_code == 200
+        assert other.json()["window_reset"] is True
+        assert [item["memory_id"] for item in other.json()["memories"]] == ["chat-1"]
+        assert len(sdk.search_calls) == 2
+
+    run_with_sdk(tmp_path, monkeypatch, scenario)

memhub/apps/core/tests/test_memory_server_durable_queue.py

@@ -963,7 +963,7 @@ class _SdkPublicClient:
     def add_extracted(self, contents, **kwargs):
         self.events.append("add_extracted")
         self.calls.append(("add_extracted", contents, kwargs))
-        return {"success": True, "memory_ids": ["memory-note"]}
+        return {"success": True, "memory_ids": ["memory-added"]}
 
     def get_write_outcome(self, request_id):
         self.calls.append(("get_write_outcome", request_id, {}))
@@ -988,7 +988,7 @@ def _sdk_evidence(
     text: str = "hello",
     memory_content: bool = False,
     source: str = "cursor",
-    manual_note: bool = False,
+    manual_addition: bool = False,
     created_at: datetime | None = None,
 ):
     from one_memory.imports.models import (
@@ -1002,7 +1002,7 @@ def _sdk_evidence(
 
     origin = (
         OriginMetadata(raw_meta={"input_mode": "direct_memory_note"})
-        if manual_note
+        if manual_addition
         else OriginMetadata()
     )
     return materialize_write_input(
@@ -1089,14 +1089,14 @@ def test_sdk_write_processor_calls_add_once_with_public_scope_and_receipt() -> N
     (
         _sdk_evidence("memory", text="remember this", memory_content=True),
         _sdk_evidence(
-            "note",
-            text="save this note",
+            "addition",
+            text="save this memory",
             source="one-memory-manual",
-            manual_note=True,
+            manual_addition=True,
         ),
     ),
 )
-def test_sdk_write_processor_uses_add_extracted_for_memory_content_and_notes(record) -> None:
+def test_sdk_write_processor_uses_add_extracted_for_memory_content_and_additions(record) -> None:
     from one_memory.sdk_write_processor import SdkWriteProcessor, SdkWriteReceipt
 
     client = _SdkPublicClient()
@@ -1112,7 +1112,7 @@ def test_sdk_write_processor_uses_add_extracted_for_memory_content_and_notes(rec
             before_hy_invocation=before,
         )
 
-    assert asyncio.run(run()) == SdkWriteReceipt(memory_ids=("memory-note",))
+    assert asyncio.run(run()) == SdkWriteReceipt(memory_ids=("memory-added",))
     assert client.events == ["before", "add_extracted"]
     assert client.calls[0][1] == [record.verbatim]
     assert len(client.calls) == 1
@@ -5330,3 +5330,70 @@ def test_equal_event_time_uses_queue_sequence_inside_one_session(tmp_path) -> No
         owner="equal-owner",
     )
     assert drain.claim(limit=10) == (second.job_id,)
+
+
+def test_a_hand_added_memory_is_claimed_ahead_of_unprocessed_history(tmp_path) -> None:
+    """A hand-added memory ("添加记忆") waited behind every unprocessed history job.
+
+    History is claimed through a ten-minute event-time window, oldest first. A
+    note is stamped "now", so with a backlog it sat at the far end of the
+    timeline and ran only after the whole history was digested.
+    """
+    queue = DurableWriteQueue(tmp_path / "one-memory.sqlite3")
+    old = datetime(2025, 1, 1, tzinfo=UTC)
+    history = [
+        queue.submit(
+            _request(
+                key=f"history-{index}",
+                evidence=(f"h{index}",),
+                source="cursor",
+                session=f"cursor-{index}",
+                event_at=old + timedelta(hours=index),
+            )
+        )
+        for index in range(3)
+    ]
+    note = queue.submit(
+        _request(
+            key="note",
+            evidence=("n1",),
+            source="one-memory-manual",
+            session="note:1",
+            event_at=datetime.now(UTC),
+        )
+    )
+    drain = DurableWriteDrain(queue, execute=_never_execute)
+
+    assert drain.claim(limit=1) == (note.job_id,)
+    # History keeps its own order through the window.
+    assert drain.claim(limit=1) == (history[0].job_id,)
+
+
+def test_hand_added_memories_still_run_one_at_a_time_in_order(tmp_path) -> None:
+    queue = DurableWriteQueue(tmp_path / "one-memory.sqlite3")
+    now = datetime.now(UTC)
+    first = queue.submit(
+        _request(
+            key="note-1",
+            evidence=("n1",),
+            source="one-memory-manual",
+            session="note:1",
+            event_at=now,
+        )
+    )
+    second = queue.submit(
+        _request(
+            key="note-2",
+            evidence=("n2",),
+            source="one-memory-manual",
+            session="note:2",
+            event_at=now + timedelta(seconds=1),
+        )
+    )
+    drain = DurableWriteDrain(queue, execute=_never_execute)
+
+    assert drain.claim(limit=5) == (first.job_id,)
+    # Its source is busy: the next note waits for the running one, not for history.
+    assert drain.claim(limit=5) == ()
+    assert queue.get("note-2").state == PENDING
+    assert second.job_id

memhub/apps/core/tests/test_policy_production_entry.py

@@ -1,18 +1,24 @@
 import inspect
 from types import SimpleNamespace
 
-from one_memory import api, cli, log_file, runtime
+from one_memory import api, cli, hy_runtime_config, log_file, runtime
 
 
 def test_production_serve_passes_only_supported_app_options(monkeypatch, tmp_path):
     import uvicorn
 
+    serve_source = inspect.getsource(cli.serve)
+    assert serve_source.index("configure_hy_runtime_environment(settings.data_dir)") < (
+        serve_source.index("from one_memory.api import create_app")
+    )
     settings = SimpleNamespace(data_dir=tmp_path, host="127.0.0.1", port=12345)
     captured = {}
+    startup_order = []
     marker = object()
     create_app_signature = inspect.signature(api.create_app)
 
     def factory(*args, **kwargs):
+        startup_order.append("create_app")
         create_app_signature.bind(*args, **kwargs)
         captured.update(kwargs)
         return marker
@@ -27,12 +33,18 @@ def test_production_serve_passes_only_supported_app_options(monkeypatch, tmp_pat
         }
 
     monkeypatch.setattr(cli, "load_settings", lambda: settings)
+    monkeypatch.setattr(
+        hy_runtime_config,
+        "configure_hy_runtime_environment",
+        lambda data_dir: startup_order.append(f"configure_hy:{data_dir}"),
+    )
     monkeypatch.setattr(log_file, "start_logging_to_file", lambda _: None)
     monkeypatch.setattr(runtime, "parent_pid", lambda: None)
     monkeypatch.setattr(api, "create_app", factory)
     monkeypatch.setattr(uvicorn, "run", run)
     cli.serve()
     assert captured == {"manage_runtime": True}
+    assert startup_order == [f"configure_hy:{tmp_path}", "create_app"]
 
 
 def test_maintenance_serve_does_not_own_the_runtime(monkeypatch, tmp_path):
@@ -59,6 +71,11 @@ def test_maintenance_serve_does_not_own_the_runtime(monkeypatch, tmp_path):
         }
 
     monkeypatch.setattr(cli, "load_settings", lambda: settings)
+    monkeypatch.setattr(
+        hy_runtime_config,
+        "configure_hy_runtime_environment",
+        lambda _data_dir: None,
+    )
     monkeypatch.setattr(log_file, "start_logging_to_file", lambda _: None)
     monkeypatch.setattr(runtime, "parent_pid", lambda: None)
     monkeypatch.setattr(api, "create_app", factory)

memhub/apps/core/tests/test_recall_raw_fallback.py

@@ -0,0 +1,261 @@
+"""MemHub_recall degrades to the imported conversations instead of answering empty.
+
+Without a usable generation model no memory can be distilled, and with no
+memory in the library a memory search can only come back empty. In both cases
+recall searches the SDK raw layer and says so with `mode: "raw"`. Original
+conversations stay under their own grant: recall's grant does not widen it.
+"""
+
+import asyncio
+import json
+from datetime import UTC, datetime
+
+import pytest
+from httpx import ASGITransport, AsyncClient
+from pydantic import SecretStr
+
+from one_memory import api
+from one_memory.api import create_app
+from one_memory.config import Settings
+from one_memory.hy_sdk_types import HySdkRawHit
+from one_memory.recall import RecallHit, RecallReceipt, RecallRequest, RecallState
+from one_memory.recall_fallback import recall_with_fallback
+from one_memory.secrets import InMemorySecretStore
+
+AT = int(datetime(2026, 9, 1, tzinfo=UTC).timestamp())
+
+
+def _raw(raw_id, content, *, source="cursor", score=0.8):
+    return HySdkRawHit(
+        raw_id=raw_id,
+        content=content,
+        user_id="local",
+        agent_id="a",
+        session_id=f"s-{raw_id}",
+        source=source,
+        memory_at=AT,
+        score=score,
+    )
+
+
+def _memory_receipt(request, *hits):
+    return RecallReceipt(
+        state=RecallState.GROUNDED if hits else RecallState.EMPTY,
+        query=request.query,
+        scope=request.scope,
+        hits=hits,
+        used_characters=sum(len(hit.content) for hit in hits),
+        truncated=False,
+    )
+
+
+def _memory_hit():
+    return RecallHit(
+        memory_id="m1",
+        content="The user prefers tea.",
+        kind="l2_fact",
+        scopes=(),
+        evidence_ids=(),
+        updated_at=datetime(2026, 9, 1, tzinfo=UTC),
+        score=0.9,
+        content_format="hy-sdk",
+    )
+
+
+def _fakes(*, ready, memories, has_memories, raw, sources=None):
+    calls = {"memory": 0, "raw": 0, "library": 0, "sources": None}
+
+    async def model_ready():
+        return ready
+
+    async def recall_memories(request):
+        calls["memory"] += 1
+        return _memory_receipt(request, *memories)
+
+    async def library():
+        calls["library"] += 1
+        return has_memories
+
+    async def raw_sources():
+        return sources
+
+    async def search_raw(query, limit, allowed):
+        calls["raw"] += 1
+        calls["sources"] = allowed
+        return tuple(raw)
+
+    return calls, {
+        "model_ready": model_ready,
+        "recall_memories": recall_memories,
+        "has_memories": library,
+        "raw_sources": raw_sources,
+        "search_raw": search_raw,
+    }
+
+
+def run(request, fakes):
+    return asyncio.run(recall_with_fallback(request, **fakes))
+
+
+def test_with_a_model_and_memories_recall_searches_memories_only():
+    calls, fakes = _fakes(ready=True, memories=[_memory_hit()], has_memories=True, raw=[])
+
+    receipt = run(RecallRequest(query="tea"), fakes)
+
+    assert receipt.mode == "memory" and receipt.fallback_reason is None
+    assert [hit.memory_id for hit in receipt.hits] == ["m1"]
+    assert calls["raw"] == 0 and calls["library"] == 0
+
+
+def test_without_a_model_recall_searches_the_raw_layer():
+    calls, fakes = _fakes(
+        ready=False, memories=[], has_memories=True, raw=[_raw("r1", "我喜欢喝茶")]
+    )
+
+    receipt = run(RecallRequest(query="tea"), fakes)
+
+    assert calls["memory"] == 0
+    assert receipt.mode == "raw" and receipt.fallback_reason == "model_unavailable"
+    assert receipt.state == RecallState.GROUNDED
+    hit = receipt.hits[0]
+    assert (hit.memory_id, hit.kind, hit.content_format) == ("r1", "raw", "raw")
+    assert (hit.source, hit.session_id) == ("cursor", "s-r1")
+    assert hit.updated_at == datetime(2026, 9, 1, tzinfo=UTC)
+
+
+def test_with_no_memories_yet_recall_searches_the_raw_layer():
+    calls, fakes = _fakes(ready=True, memories=[], has_memories=False, raw=[_raw("r1", "x")])
+
+    receipt = run(RecallRequest(query="tea"), fakes)
+
+    assert calls["memory"] == 1 and calls["library"] == 1
+    assert receipt.mode == "raw" and receipt.fallback_reason == "no_memories"
+
+
+def test_with_memories_but_none_relevant_the_answer_stays_an_empty_memory_result():
+    calls, fakes = _fakes(ready=True, memories=[], has_memories=True, raw=[_raw("r1", "x")])
+
+    receipt = run(RecallRequest(query="tea"), fakes)
+
+    assert receipt.mode == "memory" and receipt.hits == ()
+    assert calls["raw"] == 0
+
+
+def test_raw_fallback_respects_the_callers_raw_sources():
+    calls, fakes = _fakes(
+        ready=False,
+        memories=[],
+        has_memories=False,
+        raw=[_raw("r1", "a", source="cursor"), _raw("r2", "b", source="codex")],
+        sources=frozenset({"cursor"}),
+    )
+
+    receipt = run(RecallRequest(query="q"), fakes)
+
+    assert calls["sources"] == frozenset({"cursor"})
+    assert [hit.memory_id for hit in receipt.hits] == ["r1"]
+
+
+def test_a_caller_with_no_raw_grant_gets_nothing_rather_than_a_wider_read():
+    calls, fakes = _fakes(
+        ready=False,
+        memories=[],
+        has_memories=False,
+        raw=[_raw("r1", "a")],
+        sources=frozenset(),
+    )
+
+    receipt = run(RecallRequest(query="q"), fakes)
+
+    assert calls["raw"] == 0
+    assert receipt.mode == "raw" and receipt.hits == () and receipt.state == RecallState.EMPTY
+
+
+def test_raw_fallback_keeps_the_count_and_character_budgets():
+    _, fakes = _fakes(
+        ready=False,
+        memories=[],
+        has_memories=False,
+        raw=[_raw(f"r{index}", "x" * 150) for index in range(5)],
+    )
+
+    by_count = run(RecallRequest(query="q", limit=2), fakes)
+    by_chars = run(RecallRequest(query="q", limit=10, character_budget=300), fakes)
+
+    assert len(by_count.hits) == 2 and by_count.truncated_by.value == "count_budget"
+    assert len(by_chars.hits) == 2 and by_chars.truncated_by.value == "character_budget"
+    assert by_chars.used_characters == 300
+
+
+def test_the_probe_never_falls_back():
+    calls, fakes = _fakes(ready=False, memories=[], has_memories=False, raw=[_raw("r1", "x")])
+
+    receipt = run(RecallRequest(query="__om_probe__"), fakes)
+
+    assert calls["memory"] == 1 and calls["raw"] == 0
+    assert receipt.mode == "memory"
+
+
+EXTERNAL = {
+    "X-One-Memory-Read-Context": "external",
+    "X-One-Memory-Installation-Id": "24361b44-5a15-4f87-ad09-05571dc281c3",
+    "X-One-Memory-Installation-Revision": "1",
+}
+
+
+@pytest.mark.fresh_sdk
+def test_recall_route_falls_back_and_keeps_the_raw_grant(tmp_path, monkeypatch):
+    searched: list[object] = []
+
+    async def no_model(_app):
+        return False
+
+    async def raw(_app, query, *, limit, sources):
+        searched.append(sources)
+        return (_raw("r1", "上周决定用 Postgres", source="cursor"),)
+
+    monkeypatch.setattr(api, "_recall_model_ready", no_model)
+    monkeypatch.setattr(api, "_search_sdk_raw", raw)
+
+    async def scenario():
+        app = create_app(
+            Settings(
+                data_dir=tmp_path / "data",
+                source_home=tmp_path,
+                api_token=SecretStr("recall-test"),
+                imports_enabled=False,
+                automatic_memory_processing=False,
+                live_sync_enabled=False,
+            ),
+            secret_store=InMemorySecretStore(),
+        )
+        async with (
+            app.router.lifespan_context(app),
+            AsyncClient(
+                transport=ASGITransport(app=app),
+                base_url="http://test",
+                headers={"Authorization": "Bearer recall-test"},
+            ) as client,
+        ):
+            local = await client.post("/api/v1/recall", json={"query": "数据库"})
+            recall_only = await client.post(
+                "/api/v1/recall",
+                json={"query": "数据库"},
+                headers={
+                    **EXTERNAL,
+                    "X-One-Memory-Allowed-Tools": json.dumps(["om_recall"]),
+                    "X-One-Memory-Allowed-Scopes": json.dumps(["all-apps"]),
+                },
+            )
+            return local.json(), recall_only.json()
+
+    local, recall_only = asyncio.run(scenario())
+
+    assert local["mode"] == "raw" and local["fallback_reason"] == "model_unavailable"
+    assert local["hits"][0]["content_format"] == "raw"
+    assert local["hits"][0]["source"] == "cursor"
+    # A trusted local caller reads every source.
+    assert searched[0] is None
+    # A host granted recall alone may not read original conversations.
+    assert recall_only["mode"] == "raw" and recall_only["hits"] == []
+    assert len(searched) == 1

memhub/apps/core/tests/test_recall_scope_control.py

@@ -11,7 +11,13 @@ from one_memory.imports.access import opaque_workspace_id
 from one_memory.secrets import InMemorySecretStore
 
 
-def test_external_scope_cannot_override_shared_or_host_workspace_boundary(tmp_path):
+def test_external_scope_cannot_override_shared_or_host_workspace_boundary(tmp_path, monkeypatch):
+    # Memory recall, not the raw fallback a home without a model would take.
+    async def model_ready(_app):
+        return True
+
+    monkeypatch.setattr("one_memory.api._recall_model_ready", model_ready)
+
     async def scenario():
         app = create_app(
             Settings(

memhub/apps/core/tests/test_sdk_data_plane_migration.py

@@ -119,14 +119,10 @@ def test_post_cutover_metadata_repair_restores_source_and_original_times(store):
             ),
         )
 
-    import chromadb
-    from chromadb.config import Settings as ChromaSettings
+    from one_memory.sdk_vector_reattach import open_offline_chroma
 
     vector = data_dir / "hy-memory" / "governed-v2" / "vector"
-    collection = chromadb.PersistentClient(
-        path=str(vector),
-        settings=ChromaSettings(anonymized_telemetry=False),
-    ).get_or_create_collection("memory")
+    collection = open_offline_chroma(vector).get_or_create_collection("memory")
     collection.add(
         ids=["sdk-1"],
         documents=["remember"],
@@ -230,13 +226,10 @@ def test_metadata_repair_reaches_memories_the_cutover_backfilled_under_legacy_id
                 "INSERT INTO evidence VALUES ('e7','workbuddy','2026-09-01T00:00:00+00:00',NULL)"
             )
 
-    import chromadb
-    from chromadb.config import Settings as ChromaSettings
+    from one_memory.sdk_vector_reattach import open_offline_chroma
 
     vector = data_dir / "hy-memory" / "governed-v2" / "vector"
-    client = chromadb.PersistentClient(
-        path=str(vector), settings=ChromaSettings(anonymized_telemetry=False)
-    )
+    client = open_offline_chroma(vector)
     collection = client.get_or_create_collection("memory")
     imported = int(datetime(2026, 10, 20, tzinfo=UTC).timestamp())
     collection.add(
@@ -256,9 +249,7 @@ def test_metadata_repair_reaches_memories_the_cutover_backfilled_under_legacy_id
         now=datetime(2026, 10, 25, tzinfo=UTC),
     )
 
-    client = chromadb.PersistentClient(
-        path=str(vector), settings=ChromaSettings(anonymized_telemetry=False)
-    )
+    client = open_offline_chroma(vector)
     rows = client.get_collection("memory").get(ids=["legacy-7", "unlinked"], include=["metadatas"])
     client.close()
     metadata = dict(zip(rows["ids"], rows["metadatas"], strict=True))
@@ -546,13 +537,9 @@ def test_finished_jobs_without_input_do_not_stop_the_migration(store):
 
 
 def _chroma(home: Path):
-    import chromadb
-    from chromadb.config import Settings as ChromaSettings
+    from one_memory.sdk_vector_reattach import open_offline_chroma
 
-    return chromadb.PersistentClient(
-        path=str(home / "hy-memory" / "governed-v2" / "vector"),
-        settings=ChromaSettings(anonymized_telemetry=False),
-    )
+    return open_offline_chroma(home / "hy-memory" / "governed-v2" / "vector")
 
 
 def _fill(client, name: str, ids: list[str], *, text: str = "old") -> None:
@@ -599,6 +586,38 @@ def test_legacy_vectors_are_renamed_and_newer_writes_are_kept(tmp_path) -> None:
     assert reattach_legacy_vectors(tmp_path, profile) == ()
 
 
+def test_the_readback_can_open_the_store_right_after_reattach(tmp_path, monkeypatch) -> None:
+    """The 1.0.4 upgrade failed its first launch at `verify.readback`.
+
+    Reattach opened Chroma with `anonymized_telemetry=False` and never closed
+    it. The SDK then opened the same directory in the same process with
+    default settings, and Chroma refused: "An instance of Chroma already
+    exists ... with different settings". The second launch only passed because
+    nothing was left to reattach.
+    """
+    import chromadb
+
+    from one_memory.hy_sdk_runtime import builtin_retrieval_snapshot, vector_collection_bases
+    from one_memory.sdk_vector_reattach import reattach_legacy_vectors
+
+    profile = builtin_retrieval_snapshot()
+    current, legacy = vector_collection_bases(profile)
+    seeded = _chroma(tmp_path)
+    _fill(seeded, f"{legacy[0]}_4", ["a", "b"])
+    seeded.close()
+    # The migration process has not configured the SDK environment yet.
+    monkeypatch.delenv("ANONYMIZED_TELEMETRY", raising=False)
+
+    assert len(reattach_legacy_vectors(tmp_path, profile)) == 1
+
+    # What the SDK does next, in the same process: no settings of its own.
+    sdk = chromadb.PersistentClient(path=str(tmp_path / "hy-memory" / "governed-v2" / "vector"))
+    try:
+        assert sdk.get_collection(f"{current}_4").count() == 2
+    finally:
+        sdk.close()
+
+
 def _confirmed(store, *memory_ids: str, kind: str = "chat") -> None:
     with main_database(store.database_path).write() as database, database:
         for memory_id in memory_ids:

memhub/apps/core/tests/test_sdk_migration_bundle.py

@@ -91,7 +91,7 @@ def test_bundle_contains_management_sdk_config_and_verified_manifest(tmp_path):
     assert manifest["bundle_id"] == "migration-1"
     assert manifest["sdk_namespace"] == "governed-v2"
     assert manifest["runtime_build"] == "build-13"
-    assert manifest["snapshot_sdk_version"] == "2.0.5"
+    assert manifest["snapshot_sdk_version"] == "2.0.6"
     paths = {item["path"]: item for item in manifest["files"]}
     assert {
         "management/one-memory.sqlite3",

memhub/apps/core/tests/test_sdk_migration_log.py

@@ -143,14 +143,24 @@ def test_a_finished_migration_records_the_result(home, monkeypatch):
     legacy_home(home)
     from one_memory.sdk_migration_runner import StartupMigrationResult
 
+    startup_order = []
+
     def run_startup_migration(**options):
+        startup_order.append("run_migration")
         options["progress"]("cutover")
         return StartupMigrationResult(state="cutover", migration_id="sdk-authority-v2-abc")
 
+    import one_memory.hy_runtime_config as hy_runtime_config
     import one_memory.sdk_migration_runner as runner
 
+    monkeypatch.setattr(
+        hy_runtime_config,
+        "configure_hy_runtime_environment",
+        lambda data_dir: startup_order.append(f"configure_hy:{data_dir}"),
+    )
     monkeypatch.setattr(runner, "run_startup_migration", run_startup_migration)
     assert cli.run(MIGRATE, output=StringIO()) == 0
+    assert startup_order == [f"configure_hy:{home}", "run_migration"]
     finished = lines(home)[-1]
     assert finished["event"] == "migrate.finished"
     assert finished["migration_id"] == "sdk-authority-v2-abc"
@@ -291,16 +301,20 @@ def test_the_runner_names_the_step_and_sub_step_that_failed(tmp_path, monkeypatc
         for line in written
         if "step" in line.get("details", {})
     ]
-    assert steps[:6] == [
+    assert steps[:8] == [
         ("step.finished", "preflight.authority_read"),
         ("step.finished", "preflight.profile_read"),
         ("step.finished", "preflight.resumable_identity"),
         ("step.finished", "preflight.legacy_ids_scan"),
         ("step.finished", "preflight.model_profile_check"),
+        ("step.finished", "prepare.recover_abandoned_staging"),
         ("step.finished", "bundle.ensure"),
+        ("step.finished", "bundle.restore_point"),
     ]
     assert steps[-1] == ("step.failed", "prepare.legacy_work")
-    failed = written[-1]
+    # The failure put the home back; the restore says so after the failed step.
+    assert [line["event"] for line in written[-2:]] == ["restore.started", "restore.finished"]
+    failed = next(line for line in reversed(written) if line["event"] == "step.failed")
     assert failed["migration_id"].startswith("sdk-authority-v2-")
     assert failed["details"]["sub_step"] == "write_queue"
     assert failed["error"]["chain"][0]["type"] == "ValueError"

memhub/apps/core/tests/test_sdk_migration_restore.py

@@ -0,0 +1,483 @@
+"""A failed upgrade migration puts the home back exactly as it found it.
+
+The fixed release that follows must migrate from the original 1.0.4 data, not
+from a half-migrated home: every pre-cutover failure restores the database,
+the SDK store and `config.json`, and a later run succeeds from there.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import hashlib
+import io
+import json
+import sqlite3
+from contextlib import closing, contextmanager
+from pathlib import Path
+
+import pytest
+
+from one_memory import cli
+from one_memory.config import Settings
+from one_memory.database_access import close_main_databases, main_database
+from one_memory.imports.storage import EvidenceStore
+from one_memory.live_capture import sdk_migration_capture_fenced
+from one_memory.memory_server.migration_runner import SqliteMigrationStore, migrate
+from one_memory.memory_server.migrations import MIGRATIONS
+from one_memory.runtime_client import RuntimeStatus
+from one_memory.sdk_data_plane_migration import (
+    DataPlaneMigrationError,
+    MemoryAuthority,
+    SdkDataPlaneMigrationStore,
+)
+from one_memory.sdk_migration_log import log_path
+from one_memory.sdk_migration_restore import (
+    RESTORE_POINT,
+    MigrationRestoreFailed,
+    failed_state_path,
+    finish_interrupted_restore,
+    restore_pending,
+)
+from one_memory.sdk_migration_runner import run_startup_migration
+from one_memory.sdk_migration_verify import MemoryReadbackFailed
+from one_memory.target_schema import legacy_tables_present
+
+NAMESPACE = "governed-v2"
+CONFIG = {"schema_version": 1, "sources": {"cursor": {"sync_enabled": True}}}
+
+
+@pytest.fixture
+def profile(monkeypatch):
+    from one_memory.hy_sdk_runtime import builtin_retrieval_snapshot
+
+    snapshot = builtin_retrieval_snapshot()
+    monkeypatch.setattr("one_memory.sdk_migration_runner.read_active_profile", lambda _db: snapshot)
+    monkeypatch.setattr("one_memory.sdk_migration_verify.read_active_profile", lambda _db: snapshot)
+    return snapshot
+
+
+def _chroma(home: Path):
+    from one_memory.sdk_vector_reattach import open_offline_chroma
+
+    return open_offline_chroma(home / "hy-memory" / NAMESPACE / "vector")
+
+
+@pytest.fixture
+def home(tmp_path, profile) -> Path:
+    """A 1.0.4-shaped home: legacy memories, queued legacy work, legacy vectors."""
+    from one_memory.hy_sdk_runtime import vector_collection_bases
+
+    database = tmp_path / "one-memory.sqlite3"
+    asyncio.run(migrate(SqliteMigrationStore(database), MIGRATIONS))
+    with main_database(database).write() as connection, connection:
+        for memory_id in ("m1", "m2"):
+            connection.execute(
+                "INSERT INTO governed_memories (memory_id,user_id,kind,status,content,"
+                "scopes_json,revision,created_at,updated_at) "
+                "VALUES (?,'local','chat','confirmed','x','[]',1,'now','now')",
+                (memory_id,),
+            )
+        verbatim = "text of e1"
+        connection.execute(
+            "INSERT INTO evidence (evidence_id,idempotency_key,user_id,source_id,"
+            "conversation_id,content_kind,role,written_by,verbatim,content_hash,"
+            "revision,imported_at,updated_at,ingest_seq) "
+            "VALUES ('e1','e1','local','cursor','session-1','raw_conversation','user',"
+            "'person',?,?,1,'2026-10-22T00:00:00+00:00','2026-10-22T00:00:00+00:00',1)",
+            (verbatim, hashlib.sha256(verbatim.encode()).hexdigest()),
+        )
+        connection.execute(
+            "INSERT INTO memory_tasks "
+            "(task_id,request_id,user_id,kind,input_ref,status,profile_id,"
+            "profile_revision,profile_snapshot_json,runner_token,attempts,"
+            "last_error_code,created_at,updated_at,duration_seconds,hy_invocation_count) "
+            "VALUES ('t1','request-t1','local','extract','e1','pending','profile',1,'{}',"
+            "NULL,0,NULL,'now','now',NULL,0)"
+        )
+    close_main_databases()
+    assert EvidenceStore(database).get("e1") is not None
+    close_main_databases()
+    current, legacy = vector_collection_bases(profile)
+    client = _chroma(tmp_path)
+    for name, ids in ((f"{legacy[0]}_4", ["m1", "m2"]), (f"{current}_4", ["after"])):
+        collection = client.get_or_create_collection(name, metadata={"hnsw:space": "cosine"})
+        collection.upsert(
+            ids=ids,
+            embeddings=[[float(index + 1)] * 4 for index, _ in enumerate(ids)],
+            documents=[f"doc {identifier}" for identifier in ids],
+        )
+    client.close()
+    (tmp_path / "config.json").write_text(json.dumps(CONFIG), encoding="utf-8")
+    return tmp_path
+
+
+def _collections(home: Path) -> dict[str, int]:
+    client = _chroma(home)
+    try:
+        return {item.name: item.count() for item in client.list_collections()}
+    finally:
+        client.close()
+
+
+def _state(home: Path) -> dict[str, object]:
+    """Everything a migration may change, compared byte for byte or row for row."""
+    close_main_databases()
+    with closing(sqlite3.connect(home / "one-memory.sqlite3")) as connection:
+        dump = list(connection.iterdump())
+    sdk = home / "hy-memory" / NAMESPACE
+    files = {
+        path.relative_to(sdk).as_posix(): hashlib.sha256(path.read_bytes()).hexdigest()
+        for path in sorted(sdk.rglob("*"))
+        if path.is_file()
+    }
+    from one_memory.sdk_vector_reattach import _stored_names
+
+    return {
+        "database": dump,
+        "sdk_files": files,
+        "collection_names": _stored_names(home),
+        "config": (home / "config.json").read_bytes(),
+    }
+
+
+def _reading(readable: set[str]):
+    class Client:
+        def list_memories(self, *, user_id, statuses, limit, offset, order):
+            del user_id, statuses, order
+            ids = sorted(readable)
+            rows = [{"memory_id": item} for item in ids[offset : offset + limit]]
+            return {"vdb": {"memories": rows, "total": len(ids)}}
+
+        def get(self, memory_id):
+            return {"memory_id": memory_id} if memory_id in readable else None
+
+    @contextmanager
+    def open_client(_profile):
+        yield Client()
+
+    return open_client
+
+
+def _run(home: Path, *, readable=frozenset({"m1", "m2"}), report=None):
+    return run_startup_migration(
+        data_dir=home,
+        runtime_build="22",
+        sdk_version="2.0.5",
+        namespace=NAMESPACE,
+        open_client=_reading(set(readable)),
+        restore_report=report,
+    )
+
+
+def _events(home: Path) -> list[dict[str, object]]:
+    return [json.loads(line) for line in log_path(home).read_text().splitlines()]
+
+
+def _fail_schema_migrate(monkeypatch, home):
+    import one_memory.memory_server.migration_runner as runner_module
+
+    async def half_migrated(store, migrations):
+        del store, migrations
+        with main_database(home / "one-memory.sqlite3").write() as connection, connection:
+            connection.execute("CREATE TABLE half_applied_migration (x INTEGER)")
+        raise DataPlaneMigrationError("sdk_migration_schema_failed")
+
+    monkeypatch.setattr(runner_module, "migrate", half_migrated)
+
+
+def _fail_legacy_work(monkeypatch, home):
+    import one_memory.sdk_migration_runner as runner
+
+    def broken(_database_path):
+        raise DataPlaneMigrationError("sdk_data_plane_dispatch_failed")
+
+    monkeypatch.setattr(runner, "move_pending_dispatches", broken)
+
+
+def _fail_vectors(monkeypatch, home):
+    import one_memory.sdk_migration_runner as runner
+
+    real = runner.reattach_legacy_vectors
+
+    def renamed_then_failed(data_dir, profile):
+        real(data_dir, profile)
+        raise DataPlaneMigrationError("sdk_migration_vector_reattach_incomplete")
+
+    monkeypatch.setattr(runner, "reattach_legacy_vectors", renamed_then_failed)
+
+
+FAILURES = {
+    "prepare.schema_migrate": (_fail_schema_migrate, "sdk_migration_schema_failed"),
+    "prepare.legacy_work": (_fail_legacy_work, "sdk_data_plane_dispatch_failed"),
+    "vectors.reattach": (_fail_vectors, "sdk_migration_vector_reattach_incomplete"),
+}
+
+
+@pytest.mark.parametrize("step", sorted(FAILURES))
+def test_a_failure_before_cutover_restores_the_home_exactly(home, monkeypatch, step):
+    counts = _collections(home)
+    before = _state(home)
+    inject, code = FAILURES[step]
+    inject(monkeypatch, home)
+    report: dict[str, object] = {}
+
+    with pytest.raises(DataPlaneMigrationError) as caught:
+        _run(home, report=report)
+
+    # The migration's own failure is what the caller sees.
+    assert caught.value.code == code
+    assert report == {"state": "restored"}
+    assert _state(home) == before
+    assert _collections(home) == counts
+    store = SdkDataPlaneMigrationStore(home / "one-memory.sqlite3")
+    assert store.authority() is MemoryAuthority.LEGACY
+    # Nothing left to resume: the next run starts from the original data.
+    assert not (home / RESTORE_POINT).exists()
+    assert not restore_pending(home)
+    # The failed state is kept aside for diagnosis; capture stays frozen.
+    assert (failed_state_path(home) / "management" / "one-memory.sqlite3").is_file()
+    assert sdk_migration_capture_fenced(home)
+    events = _events(home)
+    failed_at = next(
+        index
+        for index, line in enumerate(events)
+        if line["event"] == "step.failed" and line["details"]["step"] == step
+    )
+    finished = next(line for line in events if line["event"] == "restore.finished")
+    assert events.index(finished) > failed_at
+    assert finished["details"]["files"] > 0 and finished["details"]["bytes"] > 0
+    assert finished["details"]["reason"] == "migration_failed"
+    assert "duration_ms" in finished["details"]
+
+    monkeypatch.undo()
+    _retry_succeeds(home, monkeypatch)
+
+
+def test_a_readback_failure_restores_and_a_fixed_build_succeeds(home, monkeypatch):
+    before = _state(home)
+    report: dict[str, object] = {}
+
+    with pytest.raises(MemoryReadbackFailed):
+        _run(home, readable={"m1"}, report=report)
+
+    assert report == {"state": "restored"}
+    assert _state(home) == before
+    # The ledger row the failure wrote went with the rest.
+    with closing(sqlite3.connect(home / "one-memory.sqlite3")) as connection:
+        assert not connection.execute(
+            "SELECT 1 FROM sdk_data_plane_migrations WHERE state='blocked'"
+        ).fetchall()
+    _retry_succeeds(home, monkeypatch)
+
+
+def _retry_succeeds(home: Path, monkeypatch) -> None:
+    from one_memory.hy_sdk_runtime import builtin_retrieval_snapshot, vector_collection_bases
+
+    snapshot = builtin_retrieval_snapshot()
+    monkeypatch.setattr("one_memory.sdk_migration_runner.read_active_profile", lambda _db: snapshot)
+    restored_bundles = sorted((home / "backups").glob("*.sdk-bundle/restored.json"))
+    assert restored_bundles
+
+    result = _run(home)
+
+    assert result.state == "cutover"
+    store = SdkDataPlaneMigrationStore(home / "one-memory.sqlite3")
+    assert store.authority() is MemoryAuthority.SDK
+    current, _legacy = vector_collection_bases(snapshot)
+    assert _collections(home) == {f"{current}_4": 3}
+    assert not sdk_migration_capture_fenced(home)
+    assert not (home / RESTORE_POINT).exists()
+    assert not failed_state_path(home).exists()
+    # The restored bundle was superseded by this run's verified one.
+    assert not any(path.exists() for path in restored_bundles)
+    assert len(list((home / "backups").glob("*-pre-cutover.sdk-bundle"))) == 1
+
+
+def test_a_failure_after_the_cutover_commit_is_not_restored(home, monkeypatch):
+    import one_memory.sdk_migration_runner as runner
+
+    def broken_cleanup(**_options):
+        raise DataPlaneMigrationError("sdk_data_plane_cleanup_failed")
+
+    monkeypatch.setattr(runner, "resume_legacy_cleanup", broken_cleanup)
+    report: dict[str, object] = {}
+
+    with pytest.raises(DataPlaneMigrationError):
+        _run(home, report=report)
+
+    assert report == {}
+    store = SdkDataPlaneMigrationStore(home / "one-memory.sqlite3")
+    assert store.authority() is MemoryAuthority.SDK
+    assert legacy_tables_present(home / "one-memory.sqlite3")
+    assert not (home / RESTORE_POINT).exists()
+    assert not any(line["event"].startswith("restore.") for line in _events(home))
+
+    monkeypatch.undo()
+    from one_memory.hy_sdk_runtime import builtin_retrieval_snapshot
+
+    snapshot = builtin_retrieval_snapshot()
+    monkeypatch.setattr("one_memory.sdk_migration_runner.read_active_profile", lambda _db: snapshot)
+    assert _run(home).state == "complete"
+
+
+def test_a_commit_that_landed_before_its_step_failed_is_not_restored(home, monkeypatch):
+    import one_memory.sdk_migration_runner as runner
+
+    real = runner.commit_sdk_cutover
+
+    def committed_then_failed(**options):
+        real(**options)
+        raise DataPlaneMigrationError("sdk_data_plane_cutover_missing")
+
+    monkeypatch.setattr(runner, "commit_sdk_cutover", committed_then_failed)
+    report: dict[str, object] = {}
+
+    with pytest.raises(DataPlaneMigrationError):
+        _run(home, report=report)
+
+    assert report == {"state": "skipped"}
+    assert (
+        SdkDataPlaneMigrationStore(home / "one-memory.sqlite3").authority() is MemoryAuthority.SDK
+    )
+    skipped = [line for line in _events(home) if line["event"] == "restore.skipped"]
+    assert len(skipped) == 1
+
+
+def test_a_failed_restore_is_logged_and_the_original_code_is_kept(home, monkeypatch):
+    import one_memory.sdk_migration_runner as runner
+
+    def corrupt_bundle_then_fail(_database_path):
+        bundle = next((home / "backups").glob("*-pre-cutover.sdk-bundle"))
+        (bundle / "management" / "one-memory.sqlite3").write_bytes(b"not the backup")
+        raise DataPlaneMigrationError("sdk_data_plane_dispatch_failed")
+
+    monkeypatch.setattr(runner, "move_pending_dispatches", corrupt_bundle_then_fail)
+    monkeypatch.setattr(cli, "load_settings", lambda: Settings(_env_file=None, data_dir=home))
+    monkeypatch.setattr(
+        cli,
+        "inspect_runtime",
+        lambda _data_dir: RuntimeStatus("stopped", "runtime_receipt_missing"),
+    )
+    output = io.StringIO()
+
+    code = cli.run(["sdk-migrate", "--runtime-build", "22", "--yes", "--json"], output=output)
+
+    document = json.loads(output.getvalue().splitlines()[-1])
+    assert code == 1
+    assert document["code"] == "sdk_data_plane_dispatch_failed"
+    assert document["data_restored"] is False
+    assert document["restore_code"] == "sdk_migration_restore_failed"
+    events = _events(home)
+    restore_failed = next(line for line in events if line["event"] == "restore.failed")
+    assert restore_failed["code"] == "sdk_migration_restore_failed"
+    assert restore_failed["error"]["chain"]
+    migrate_failed = next(line for line in events if line["event"] == "migrate.failed")
+    assert migrate_failed["code"] == "sdk_data_plane_dispatch_failed"
+    assert migrate_failed["details"]["restore"] == "failed"
+    # Nothing was swapped; the restore point stays and the next run refuses
+    # to migrate over the half-migrated home until a restore succeeds.
+    assert (home / RESTORE_POINT).exists()
+    assert not restore_pending(home)
+    monkeypatch.undo()
+    with pytest.raises(MigrationRestoreFailed):
+        _run(home)
+
+
+def test_a_restore_killed_between_renames_is_finished_before_anything_reads(home, monkeypatch):
+    import one_memory.sdk_migration_restore as restore_module
+
+    before = _state(home)
+    real_apply = restore_module._apply
+
+    def killed_part_way(target, steps, done):
+        real_apply(target, steps[:5], done)
+        raise KeyboardInterrupt
+
+    _fail_vectors(monkeypatch, home)
+    monkeypatch.setattr(restore_module, "_apply", killed_part_way)
+
+    with pytest.raises(KeyboardInterrupt):
+        _run(home)
+
+    assert restore_pending(home)
+    # The database was renamed aside: Core must not serve, and the probe
+    # must not call this a fresh home.
+    assert not (home / "one-memory.sqlite3").exists()
+    monkeypatch.setattr(cli, "load_settings", lambda: Settings(_env_file=None, data_dir=home))
+    status = io.StringIO()
+    assert cli.run(["sdk-migration-status", "--json"], output=status) == 0
+    assert json.loads(status.getvalue())["state"] == "required"
+    with pytest.raises(SystemExit) as refused:
+        cli._refuse_unmigrated_home(home)
+    assert refused.value.code == cli.SDK_MIGRATION_REQUIRED_EXIT
+
+    monkeypatch.undo()
+    from one_memory.hy_sdk_runtime import builtin_retrieval_snapshot
+
+    snapshot = builtin_retrieval_snapshot()
+    monkeypatch.setattr("one_memory.sdk_migration_runner.read_active_profile", lambda _db: snapshot)
+
+    assert finish_interrupted_restore(home)
+
+    assert not restore_pending(home)
+    assert _state(home) == before
+
+
+def test_a_run_killed_after_its_restore_point_is_rolled_back_on_the_next_start(home, monkeypatch):
+    import one_memory.sdk_migration_runner as runner
+
+    before = _state(home)
+    real = runner.reattach_legacy_vectors
+
+    def renamed_then_killed(data_dir, profile):
+        real(data_dir, profile)
+        raise KeyboardInterrupt
+
+    monkeypatch.setattr(runner, "reattach_legacy_vectors", renamed_then_killed)
+    with pytest.raises(KeyboardInterrupt):
+        _run(home)
+    assert (home / RESTORE_POINT).exists()
+    monkeypatch.undo()
+    from one_memory.hy_sdk_runtime import builtin_retrieval_snapshot
+
+    snapshot = builtin_retrieval_snapshot()
+    monkeypatch.setattr("one_memory.sdk_migration_runner.read_active_profile", lambda _db: snapshot)
+
+    # The next start first puts the home back, then migrates it from there.
+    def failing_readback(_profile):
+        raise DataPlaneMigrationError("sdk_migration_secure_storage_unavailable")
+
+    with pytest.raises(DataPlaneMigrationError):
+        run_startup_migration(
+            data_dir=home,
+            runtime_build="22",
+            sdk_version="2.0.5",
+            namespace=NAMESPACE,
+            open_client=failing_readback,
+        )
+    reasons = [
+        line["details"]["reason"] for line in _events(home) if line["event"] == "restore.finished"
+    ]
+    assert reasons == ["interrupted_attempt", "migration_failed"]
+    assert _state(home) == before
+
+
+def test_a_preflight_failure_changes_nothing_and_needs_no_restore(home, monkeypatch):
+    monkeypatch.setattr("one_memory.sdk_migration_runner.read_active_profile", lambda _db: None)
+    before = _state(home)
+    report: dict[str, object] = {}
+
+    with pytest.raises(DataPlaneMigrationError, match="sdk_migration_model_profile_required"):
+        _run(home, report=report)
+
+    assert report == {}
+    assert _state(home) == before
+    assert not (home / "backups").exists() or not list((home / "backups").iterdir())
+
+
+def test_a_frozen_capture_fence_holds_until_a_migration_lifts_it(tmp_path):
+    marker = tmp_path / ".sdk-migration-capture-fence.json"
+    marker.write_text(json.dumps({"schema_version": 1, "frozen": True}), encoding="utf-8")
+
+    assert sdk_migration_capture_fenced(tmp_path)
+    assert marker.exists()

memhub/apps/core/tests/test_source_permission_races.py

@@ -295,6 +295,8 @@ def test_startup_reconciles_enabled_source_from_config(tmp_path, monkeypatch):
             secret_store=InMemorySecretStore(),
         )
         async with restored.router.lifespan_context(restored):
+            # The reconcile runs after readiness, in recovery.
+            await restored.state.recovery_task
             history = [
                 job
                 for job in restored.state.import_job_store.list_jobs()

memhub/apps/core/tests/test_source_status_latency.py

@@ -111,6 +111,7 @@ def test_large_import_status_does_not_scan_source_trees(tmp_path, monkeypatch):
         app, catalog = build_app(tmp_path, monkeypatch)
         seed_layouts(catalog)
         async with app.router.lifespan_context(app), client_for(app) as client:
+            await app.state.recovery_task
             await app.state.memory_backfill
             await asyncio.to_thread(seed_evidence, app)
             probes = []

memhub/apps/core/tests/test_unified_write_entry_wiring.py

@@ -2,12 +2,12 @@
 
 Companion to `test_memory_server_unified_entry.py` (C2's adapter). That file
 proves the adapter works in isolation; this one pins the *wiring* in `api.py` /
-`memory_notes.py`, which is the C0-owned half:
+`memory_additions.py`, which is the C0-owned half:
 
   red state  - before the wiring, `on_stable_evidence` was the supervisor's
                `enqueue_evidence` and a committed record had no
                `memory_write_jobs` row;
-  positive   - after it, both the import callback and a manual note submit to
+  positive   - after it, both the import callback and a hand-added memory submit to
                the durable queue under `entry:<evidence_id>`;
   idempotent - replaying the same evidence returns the original job.
 """
@@ -173,8 +173,8 @@ def test_import_callback_goes_through_the_durable_intake(tmp_path) -> None:
             assert callback.__module__ == "one_memory.api"
             # The shared intake exists and is what the callback closes over.
             assert app.state.memory_write_intake.queue is not None
-            # Same object for the note path, so both entries share one queue.
-            assert app.state.memory_note_store.intake is app.state.memory_write_intake
+            # Same object for the memory-add path, so both entries share one queue.
+            assert app.state.memory_addition_store.intake is app.state.memory_write_intake
 
     asyncio.run(scenario())
 
@@ -225,7 +225,7 @@ def test_live_import_callback_submits_realtime_priority(tmp_path) -> None:
     asyncio.run(scenario())
 
 
-def test_manual_note_creates_one_durable_row_and_replays_idempotently(
+def test_memory_add_creates_one_durable_row_and_replays_idempotently(
     tmp_path,
 ) -> None:
     async def scenario():
@@ -237,10 +237,8 @@ def test_manual_note_creates_one_durable_row_and_replays_idempotently(
                 headers={"Authorization": "Bearer wire-test"},
             )
             request_id = str(uuid4())
-            created = await client.post(
-                "/api/v1/memory-notes",
-                json={"request_id": request_id, "text": "记住这条", "scope": "all-apps"},
-            )
+            body = {"request_id": request_id, "text": "记住这条", "scope": "all-apps"}
+            created = await client.post("/api/v2/memories", json=body)
             assert created.status_code == 201
             evidence_id = created.json()["evidence_id"]
             key = f"entry:{evidence_id}"
@@ -257,10 +255,12 @@ def test_manual_note_creates_one_durable_row_and_replays_idempotently(
                     break
             assert rows == [(key,)]
 
-            # Idempotent replay: a second /process must not add a second row.
-            assert (
-                await client.post(f"/api/v1/memory-notes/{evidence_id}/process")
-            ).status_code == 200
+            # Idempotent replay: the same request submitted again must not add
+            # a second row.
+            replay = await client.post("/api/v2/memories", json=body)
+            assert replay.status_code == 201
+            assert replay.json()["evidence_id"] == evidence_id
+            await asyncio.sleep(0.2)
             with sqlite3.connect(app.state.evidence_store.database_path) as db:
                 count = db.execute(
                     "SELECT COUNT(*) FROM memory_write_jobs WHERE idempotency_key=?",

memhub/apps/core/tests/test_visibility_background.py

@@ -62,6 +62,8 @@ def test_the_switch_on_starts_it(library, monkeypatch):
     async def scenario() -> None:
         app = _app(library)
         async with app.router.lifespan_context(app):
+            # Started by the recovery that runs after readiness.
+            await app.state.recovery_task
             assert app.state.memory_visibility_task is not None
 
     asyncio.run(scenario())

memhub/apps/core/uv.lock

@@ -991,7 +991,7 @@ wheels = [
 
 [[package]]
 name = "hy-memory"
-version = "2.0.5"
+version = "2.0.6"
 source = { registry = "https://pypi.org/simple" }
 dependencies = [
     { name = "chromadb" },
@@ -1008,9 +1008,9 @@ dependencies = [
     { name = "scikit-learn" },
     { name = "tiktoken" },
 ]
-sdist = { url = "https://files.pythonhosted.org/packages/94/56/7a279122bb56b067c390b748b8a83b6a90bb2a8f237c1d3989b6317681cd/hy_memory-2.0.5.tar.gz", hash = "sha256:bfb1e9e9815377477702327fa318331d555b8256a67b5bad8d70d6a682bd9a4f", size = 839060, upload-time = "2026-10-22T12:59:30.502Z" }
+sdist = { url = "https://files.pythonhosted.org/packages/18/98/312ac8bcbe41e63200a93d296300b2e6748e1a532dad01f009dad57ba408/hy_memory-2.0.6.tar.gz", hash = "sha256:d0f54d54867ee7e722a8dd1a88a00c0576904435f15ae7899fe640840bff74bc", size = 855200, upload-time = "2026-10-27T07:53:10.022Z" }
 wheels = [
-    { url = "https://files.pythonhosted.org/packages/c5/97/090ca18b6a13d0216d2df607cb67732ff7a8eba2d0359b9ad95283b2cbdc/hy_memory-2.0.5-py3-none-any.whl", hash = "sha256:c24649d188eaa03d3b4e4e4ec20e818da884170b5f775f3cf23ecfa6b60523d6", size = 902923, upload-time = "2026-10-22T12:59:28.018Z" },
+    { url = "https://files.pythonhosted.org/packages/27/f1/d4866cffe426d77b857168cc694b15df866f3d9f45152c17c148e1595db4/hy_memory-2.0.6-py3-none-any.whl", hash = "sha256:b0e666f8e89d1763bb31c0e67502df74434134a638ff6fd1912de9e936be2483", size = 918955, upload-time = "2026-10-27T07:53:07.686Z" },
 ]
 
 [[package]]
@@ -1837,7 +1837,7 @@ requires-dist = [
     { name = "fastapi", specifier = ">=0.141.1" },
     { name = "filelock", specifier = ">=3.32.4" },
     { name = "httpx", specifier = ">=0.28.1" },
-    { name = "hy-memory", specifier = "==2.0.5" },
+    { name = "hy-memory", specifier = "==2.0.6" },
     { name = "keyring", specifier = ">=25.7.0" },
     { name = "numpy", specifier = "==2.5.2" },
     { name = "onnxruntime", specifier = "==1.23.2" },

memhub/apps/desktop/src/core-supervisor.test.ts

@@ -234,9 +234,14 @@ describe("Core ownership", () => {
   it("attaches when a standalone Core wins the race with the first spawn", async () => {
     const dataDir = await mkdtemp(path.join(tmpdir(), "core-attach-race-"));
     let probes = 0;
+    // The winner has finished publishing its receipt and token by the time
+    // our child loses the lock. Writing them from inside the spawn raced the
+    // readiness loop: on a slow runner the token was not there yet, the
+    // re-read rejected the receipt, and the test saw a false conflict.
+    let winner: Promise<void> = Promise.resolve();
     const spawnProcess = vi.fn(() => {
       const child = fakeChild();
-      void writeRuntime(dataDir, {
+      winner = writeRuntime(dataDir, {
         schema_version: 1,
         service: "one-memory-core",
         instance_id: "cli-race-winner",
@@ -245,7 +250,9 @@ describe("Core ownership", () => {
         host: "127.0.0.1",
         port: 9236,
         started_at: "2026-09-19T01:00:00Z",
-      }).then(() => child.emit("exit", 1, null));
+      }).then(() => {
+        child.emit("exit", 1, null);
+      });
       return child;
     });
     const supervisor = new CoreSupervisor({
@@ -256,6 +263,10 @@ describe("Core ownership", () => {
       spawnProcess,
       probeHealth: async (port, token) => {
         probes += 1;
+        // Our own child never answers: it lost the race. Waiting here for the
+        // winner's files keeps the readiness loop from concluding before the
+        // winner exists, which is the order this test is about.
+        await winner;
         if (port !== 9236 || token !== "attached-secret")
           throw new Error("not attached yet");
         return {

memhub/apps/desktop/src/diagnostics-ipc.test.ts

@@ -246,21 +246,23 @@ it("shows HY pipeline metrics without exposing model content", async () => {
   const target = path.join(pipelineDir, "2026-10-14.log");
   await writeFile(target, "");
   const cursor = await captureDebugLogCursor(dataDir);
-  await appendFile(
-    target,
-    `${JSON.stringify({
-      request_id: "request-safe-1",
-      user_id: "private-user",
-      agent_id: "private-agent",
-      session_id: "private-session",
-      step: "EXTRACT",
-      prompt: "private prompt",
-      content: "private response",
-      parsed: "private parsed output",
-      tokens: 42,
-      elapsed_ms: 123.5,
-      timestamp: "2026-10-14T10:01:00.000",
-    })}\n`,
+  const pipelineEntry = {
+    request_id: "request-safe-1",
+    user_id: "private-user",
+    agent_id: "private-agent",
+    session_id: "private-session",
+    step: "EXTRACT",
+    prompt: "private prompt",
+    content: "private response",
+    parsed: "private parsed output",
+    tokens: 42,
+    elapsed_ms: 123.5,
+    timestamp: "2026-10-14T10:01:00.000",
+  };
+  await appendFile(target, `${JSON.stringify(pipelineEntry)}\n`);
+  await writeFile(
+    path.join(dataDir, "hy-memory", "governed-v2", "logs", "hy_memory.log"),
+    `${JSON.stringify({ ...pipelineEntry, request_id: "must-not-appear" })}\n`,
   );
 
   const snapshot = await readDebugLogSnapshot(

memhub/apps/desktop/src/diagnostics-ipc.ts

@@ -18,6 +18,7 @@ const UI_TRACE = "one-memory:log-ui-trace";
 const DEBUG_LOGS = "one-memory:get-debug-logs";
 const DEBUG_LOG_NAME =
   /^diagnostic-(runtime|core|host-bridge|desktop|cli)\.jsonl(?:\.\d+)?$/;
+const PIPELINE_LOG_NAME = /^\d{4}-\d{2}-\d{2}\.log$/;
 const SERVICE_LOG_NAMES = [
   "service.log",
   "service-error.log",
@@ -554,7 +555,11 @@ async function pipelineLogFiles(root: string): Promise<PipelineLogCursor[]> {
         await visit(target);
         continue;
       }
-      if (!entry.isFile() || !entry.name.endsWith(".log")) continue;
+      // The same root also contains HY's human-readable hy_memory.log.
+      // Pipeline files are date-named JSONL; accepting every .log file makes
+      // the Debug poller repeatedly parse unrelated text and still display no
+      // HY entries.
+      if (!entry.isFile() || !PIPELINE_LOG_NAME.test(entry.name)) continue;
       const info = await safeRegularFile(target);
       if (!info) continue;
       files.push({