Python
fix(memhub): repair SDK authority migration
alvinfei790d6d3d5e87
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex 6683843..5a9117a 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -4,6 +4,12 @@ Hy Memory and MemHub are versioned and released independently.## Unreleased+- Fixed legacy-to-SDK startup migration to adopt native Coding Experience and+ Working Fact IDs instead of importing them as Chat layers. Raw migration now+ rebuilds bounded user/assistant turns from the latest three days, excludes+ tools, and enforces the same rolling retention after cutover.+- Paused host capture writes with a live Desktop migration fence; Cursor+ History catch-up resumes from its existing checkpoint after cutover.- Removed MemHub's private `hy_memory_bridge` implementation. MemHub now callspublic `HyMemoryClient` methods at runtime; prompt/reconcile/responsemonkey-patches and private VDB/Coding runtime access were deleted. Kuzu Graphdiff --git a/memhub/MEMORY.md b/memhub/MEMORY.mdindex f0075d5..5b53b31 100644--- a/memhub/MEMORY.md+++ b/memhub/MEMORY.md@@ -13,6 +13,8 @@接口先补 SDK。Runtime writers 停止后的 App 启动迁移可直接操作底层存储,但不得把迁移专用方法加入公共 Client。3. MemHub **不存 memory 实体**;**可以存 `memory_id`** 做组织/回执。原文进入 **SDK raw**。+4. SDK raw 只保留滚动三天;一条 raw 对应一个完整 turn,只含真人 user 与+ assistant,tool 不持久化。提取后的高层 memory 不受该窗口影响。生产入口通过共享 Runtime 租约取得公开 `HyMemoryClient`;MemHub 只在调用前执行模型配置、密钥和 harness/model 门禁,不维护第二套 memory 正文权威。diff --git a/memhub/apps/core/src/one_memory/api.py b/memhub/apps/core/src/one_memory/api.pyindex 0a442aa..80fa413 100644--- a/memhub/apps/core/src/one_memory/api.py+++ b/memhub/apps/core/src/one_memory/api.py@@ -1151,6 +1151,8 @@ 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 claimdiff --git a/memhub/apps/core/src/one_memory/cli.py b/memhub/apps/core/src/one_memory/cli.pyindex 00f4b39..ed9b6d6 100644--- a/memhub/apps/core/src/one_memory/cli.py+++ b/memhub/apps/core/src/one_memory/cli.py@@ -744,11 +744,30 @@ def sdk_migration_status(options: Sequence[str], stream: TextIO) -> int:else 0),}+ active_migration = (+ database.execute(+ "SELECT migration_id,backup_bundle_id "+ "FROM sdk_data_plane_migrations "+ "WHERE state IN ('running','blocked','ready') "+ "ORDER BY created_at DESC LIMIT 1"+ ).fetchone()+ if "sdk_data_plane_migrations" in tables+ else None+ )document = {"schema_version": 1,"authority": "legacy","state": "required" if any(counts.values()) else "empty",- "migration_id": None,+ "migration_id": (+ str(active_migration["migration_id"])+ if active_migration is not None+ else None+ ),+ "bundle_id": (+ str(active_migration["backup_bundle_id"])+ if active_migration is not None+ else None+ ),"counts": counts,"generation": generation,}diff --git a/memhub/apps/core/src/one_memory/hy_sdk_migration.py b/memhub/apps/core/src/one_memory/hy_sdk_migration.pyindex b398f45..0d7fabe 100644--- a/memhub/apps/core/src/one_memory/hy_sdk_migration.py+++ b/memhub/apps/core/src/one_memory/hy_sdk_migration.py@@ -58,6 +58,16 @@ class MigrationClient(Protocol):def get_write_outcome(self, request_id: str) -> Mapping[str, object] | None: ...+ def get(+ self,+ memory_id: str,+ *,+ kind: str | None = None,+ variant: str | None = None,+ ) -> Mapping[str, object] | None: ...++ async def _coding_store_for_exact_get(self, variant: str) -> Any: ...+class HySdkMigration:"""Typed offline adapter over one initialized SDK data plane."""@@ -91,6 +101,89 @@ class HySdkMigration:)return _memory_page(raw, limit=limit, offset=offset)+ async def read_productivity_memory(+ self,+ memory_id: str,+ *,+ kind: str,+ variant: str | None,+ ) -> tuple[HySdkMemoryRecord, str] | None:+ raw = await _sdk_call(+ "hy_sdk_productivity_get_failed",+ self.client.get,+ memory_id,+ kind=kind,+ variant=variant,+ )+ if raw is None:+ return None+ if not isinstance(raw, Mapping) or raw.get("variant") not in {+ "working",+ "coding",+ }:+ raise HySdkMigrationError("hy_sdk_productivity_variant_invalid")+ return HySdkMemoryRecord.from_sdk(raw), str(raw["variant"])++ async def delete_productivity_memory(+ self,+ memory_id: str,+ *,+ kind: str,+ variant: str | None,+ user_id: str,+ ) -> dict[str, object]:+ raw = await _sdk_call(+ "hy_sdk_productivity_delete_failed",+ self._loop_thread.run,+ self._delete_productivity_memory(+ memory_id,+ kind=kind,+ variant=variant,+ user_id=user_id,+ ),+ )+ return _successful_result(raw, "hy_sdk_productivity_delete_failed")++ async def _delete_productivity_memory(+ self,+ memory_id: str,+ *,+ kind: str,+ variant: str | None,+ user_id: str,+ ) -> dict[str, object]:+ if kind not in {"experience", "fact"}:+ raise ValueError("productivity kind must be experience or fact")+ matches: list[tuple[Any, str]] = []+ for candidate in ((variant,) if variant is not None else ("working", "coding")):+ store = await self.client._coding_store_for_exact_get(candidate)+ if store is None:+ continue+ existing = (+ await store.get_by_id(memory_id, user_id=user_id)+ if kind == "experience"+ else await store.get_fact(memory_id, user_id=user_id)+ )+ if existing is not None:+ matches.append((store, candidate))+ if len(matches) > 1:+ raise ValueError("productivity memory id is ambiguous across variants")+ if not matches:+ return {"success": True, "deleted_count": 0}+ store, _actual_variant = matches[0]+ if kind == "experience":+ deleted = await store.delete(memory_id, user_id=user_id)+ elif kind == "fact":+ await store._fact_vec.delete(memory_id)+ with store._lock:+ store._conn.execute(+ "DELETE FROM working_fact WHERE fact_id=? AND user_id=?",+ (memory_id, user_id),+ )+ store._conn.commit()+ deleted = True+ return {"success": True, "deleted_count": int(deleted)}+async def write_legacy_memory(self,*,@@ -267,7 +360,7 @@ class HySdkMigration:nodes = await self._vector_store.list_by_user(user_id=user_id,agent_id=agent_id,- status_filter=[MemoryStatus.ACTIVE],+ status_filter=list(MemoryStatus),layers=[MemoryLayer.L1_RAW],include_sources=[source] if source else None,limit=100_000,@@ -318,6 +411,21 @@ class HySdkMigration:)return _successful_result(raw, "hy_sdk_raw_import_failed")+ async def delete_raw(self, raw_id: str) -> dict[str, object]:+ raw = await _sdk_call(+ "hy_sdk_raw_delete_failed",+ self._loop_thread.run,+ self._delete_raw(raw_id),+ )+ return _successful_result(raw, "hy_sdk_raw_delete_failed")++ async def _delete_raw(self, raw_id: str) -> dict[str, object]:+ existing = await self._vector_store.get_by_id(raw_id)+ if existing is None or existing.layer is not MemoryLayer.L1_RAW:+ return {"success": True, "deleted_count": 0}+ deleted = await self._vector_store.delete(raw_id)+ return {"success": True, "deleted_count": int(bool(deleted))}+async def _write_legacy_raw(self,*,diff --git a/memhub/apps/core/src/one_memory/live_capture.py b/memhub/apps/core/src/one_memory/live_capture.pyindex 3f6ca1e..e816b98 100644--- a/memhub/apps/core/src/one_memory/live_capture.py+++ b/memhub/apps/core/src/one_memory/live_capture.py@@ -1,6 +1,7 @@"""Write visible hook text into Evidence. Tool output stays out."""import json+import osimport timefrom datetime import UTC, datetimefrom enum import StrEnum@@ -74,6 +75,7 @@ _FILE_FALLBACK = {}_FALLBACK_EVENTS = frozenset({"Stop", "stop", "SubagentStop", "StopFailure"})_TEXT_BLOCKS = frozenset({"text"})+SDK_MIGRATION_CAPTURE_FENCE = ".sdk-migration-capture-fence.json"def database_path() -> Path:@@ -88,17 +90,42 @@ def capture_stdio(source_id: str, stdin: TextIO, output: TextIO) -> int:del outputif source_id not in CAPTURE_SOURCES:return 2+ database = database_path()+ if sdk_migration_capture_fenced(database.parent):+ return 0try:payload = json.loads(stdin.read() or "")except json.JSONDecodeError:return 0try:- capture_hook(source_id, payload, database_path())+ capture_hook(source_id, payload, database)except Exception:return 0return 0+def sdk_migration_capture_fenced(data_dir: Path) -> bool:+ """Ignore stale fences; only a live Desktop migration pauses hook writes."""+ marker = data_dir / SDK_MIGRATION_CAPTURE_FENCE+ try:+ document = json.loads(marker.read_text(encoding="utf-8"))+ pid = int(document["pid"])+ if pid < 1:+ raise ValueError("invalid migration fence pid")+ os.kill(pid, 0)+ return True+ except FileNotFoundError:+ return False+ except ProcessLookupError:+ marker.unlink(missing_ok=True)+ return False+ except PermissionError:+ return True+ except (KeyError, TypeError, ValueError, json.JSONDecodeError, OSError):+ marker.unlink(missing_ok=True)+ return False++def capture_hook(source_id: str, payload: object, database: Path) -> bool:if source_id not in CAPTURE_SOURCES or not isinstance(payload, dict):return Falsediff --git a/memhub/apps/core/src/one_memory/sdk_memory_runtime.py b/memhub/apps/core/src/one_memory/sdk_memory_runtime.pyindex 4534e3d..98338eb 100644--- a/memhub/apps/core/src/one_memory/sdk_memory_runtime.py+++ b/memhub/apps/core/src/one_memory/sdk_memory_runtime.py@@ -3,6 +3,8 @@from __future__ import annotationsimport asyncio+import logging+from contextlib import suppressfrom datetime import UTC, datetime, timedeltafrom pathlib import Pathfrom typing import Any@@ -25,6 +27,18 @@ from one_memory.memory_server.durable_queue import COMPLETED, DurableWriteQueuefrom one_memory.sdk_write_processor import SdkWriteCoordinatorfrom one_memory.semantic_deadline import SemanticMemoryHit+logger = logging.getLogger(__name__)+RAW_RETENTION_DAYS = 3+RAW_RETENTION_CHECK_SECONDS = 6 * 60 * 60+_RAW_STATUSES = (+ "active",+ "superseded",+ "shadow",+ "negated",+ "conflicted",+ "archived",+)+class SdkMemoryRuntime:"""Product services that remain after legacy task/governance writes retire."""@@ -43,6 +57,68 @@ class SdkMemoryRuntime:self.write_queue = write_queueself.extraction_settings = extraction_settingsself.data_dir = data_dir+ self._raw_retention_task: asyncio.Task[None] | None = None++ def start_raw_retention(self) -> None:+ if self._raw_retention_task is None or self._raw_retention_task.done():+ self._raw_retention_task = asyncio.create_task(+ self._raw_retention_loop(),+ name="one-memory-sdk-raw-retention",+ )++ async def prune_expired_raw(self, *, now: datetime | None = None) -> int:+ cutoff = (now or datetime.now(UTC)) - timedelta(days=RAW_RETENTION_DAYS)+ cutoff_timestamp = int(cutoff.timestamp())+ client = await self.read_handle.client()+ deleted = 0+ while True:+ page = await asyncio.to_thread(+ client.list_memories,+ user_id="local",+ layers=["l1_raw"],+ statuses=list(_RAW_STATUSES),+ order="asc",+ limit=500,+ offset=0,+ )+ bucket = page.get("vdb") if isinstance(page, dict) else None+ rows = bucket.get("memories") if isinstance(bucket, dict) else None+ if not isinstance(rows, list) or not rows:+ return deleted+ expired = [+ row+ for row in rows+ if isinstance(row, dict)+ and isinstance(row.get("memory_id"), str)+ and int(row.get("memory_at") or row.get("gmt_created") or 0)+ < cutoff_timestamp+ ]+ if not expired:+ return deleted+ removed_page = 0+ for row in expired:+ result = await asyncio.to_thread(client.delete, row["memory_id"])+ if isinstance(result, dict) and result.get("success") is True:+ count = int(result.get("deleted_count") or 0)+ deleted += count+ removed_page += count+ if removed_page == 0:+ return deleted++ async def _raw_retention_loop(self) -> None:+ while True:+ await asyncio.sleep(RAW_RETENTION_CHECK_SECONDS)+ try:+ removed = await self.prune_expired_raw()+ if removed:+ logger.info("sdk_raw_retention_deleted count=%d", removed)+ except asyncio.CancelledError:+ raise+ except Exception as error:+ logger.warning(+ "sdk_raw_retention_failed error_type=%s",+ type(error).__name__,+ )async def semantic_recall(self,@@ -279,7 +355,12 @@ class SdkMemoryRuntime:return Noneasync def shutdown(self) -> None:- return None+ if self._raw_retention_task is None:+ return+ self._raw_retention_task.cancel()+ with suppress(asyncio.CancelledError):+ await self._raw_retention_task+ self._raw_retention_task = Nonedef _agent_ids(raw: object) -> tuple[str, ...]:diff --git a/memhub/apps/core/src/one_memory/sdk_migration_inventory.py b/memhub/apps/core/src/one_memory/sdk_migration_inventory.pyindex ee3a9ce..3d891c1 100644--- a/memhub/apps/core/src/one_memory/sdk_migration_inventory.py+++ b/memhub/apps/core/src/one_memory/sdk_migration_inventory.py@@ -7,12 +7,13 @@ import jsonimport sqlite3from collections.abc import Awaitable, Mappingfrom dataclasses import dataclass-from datetime import datetime+from datetime import UTC, datetimefrom pathlib import Pathfrom typing import Protocolfrom one_memory.database_access import main_database-from one_memory.hy_sdk_types import HySdkMemoryPage, HySdkRawPage+from one_memory.hy_sdk_types import HySdkMemoryPage, HySdkMemoryRecord, HySdkRawPage+from one_memory.input_sanitization import sanitize_model_inputfrom one_memory.sdk_data_plane_migration import SdkDataPlaneMigrationStore@@ -35,6 +36,8 @@ class LegacyMemoryInventory:tags: tuple[str, ...]supersedes: tuple[str, ...]superseded_by: tuple[str, ...]+ productivity_kind: str | None = None+ productivity_variant: str | None = None@dataclass(frozen=True)@@ -44,6 +47,8 @@ class SdkMemoryInventory:agent_id: strcontent_hash: strstatus: str+ productivity_kind: str | None = None+ productivity_variant: str | None = None@dataclass(frozen=True)@@ -92,6 +97,17 @@ _KIND_LAYER = {"schema": "l6_schema","intention": "l7_intention",}+_PRODUCTIVITY_LAYER = {+ "coding_experience": ("experience", "coding"),+ "working_experience": ("experience", "working"),+ "coding_fact": ("fact", "coding"),+ # Historical receipts called every productivity fact "working_fact",+ # including facts stored beside a coding-variant experience. Resolve the+ # actual variant from the SDK exact lookup instead of trusting this label.+ "working_fact": ("fact", None),+}+_RAW_TURN_MAX_CHARACTERS = 60_000+_RAW_USER_MAX_CHARACTERS = 30_000SDK_LIFECYCLE_STATUSES = ("active",@@ -161,6 +177,25 @@ class SdkMigrationClient(Protocol):def delete(self, memory_id: str) -> Awaitable[dict[str, object]]: ...+ def read_productivity_memory(+ self,+ memory_id: str,+ *,+ kind: str,+ variant: str | None,+ ) -> Awaitable[tuple[HySdkMemoryRecord, str] | None]: ...++ def delete_productivity_memory(+ self,+ memory_id: str,+ *,+ kind: str,+ variant: str | None,+ user_id: str,+ ) -> Awaitable[dict[str, object]]: ...++ def delete_raw(self, raw_id: str) -> Awaitable[dict[str, object]]: ...+def read_legacy_memory_inventory(database_path: Path) -> tuple[LegacyMemoryInventory, ...]:"""Read legacy memory intent without constructing a Governance writer."""@@ -204,6 +239,7 @@ def read_legacy_memory_inventory(database_path: Path) -> tuple[LegacyMemoryInventags = tuple(value for value in tags_value if isinstance(value, str))kind = str(row["kind"])status = str(row["status"])+ productivity = _PRODUCTIVITY_LAYER.get(mapped_layer or "")records.append(LegacyMemoryInventory(legacy_memory_id=legacy_id,@@ -225,6 +261,8 @@ def read_legacy_memory_inventory(database_path: Path) -> tuple[LegacyMemoryInventags=tags,supersedes=tuple(supersedes.get(legacy_id, ())),superseded_by=tuple(superseded_by.get(legacy_id, ())),+ productivity_kind=productivity[0] if productivity else None,+ productivity_variant=productivity[1] if productivity else None,))return tuple(records)@@ -239,43 +277,110 @@ def _parse_datetime(value: object) -> datetime | None:return None-def read_legacy_raw_inventory(database_path: Path) -> tuple[LegacyRawInventory, ...]:+def read_legacy_raw_inventory(+ database_path: Path,+ *,+ cutoff: datetime,+) -> tuple[LegacyRawInventory, ...]:+ """Rebuild recent legacy messages into one user/assistant raw per turn."""+ if cutoff.tzinfo is None:+ cutoff = cutoff.replace(tzinfo=UTC)with main_database(database_path).read(row_factory=sqlite3.Row) as connection:rows = connection.execute("""SELECT evidence_id,user_id,source_id,workspace,project,conversation_id,message_id,source_ordinal,content_kind,role,written_by,created_at,imported_at,verbatim,content_hash,revision- FROM evidence ORDER BY COALESCE(ingest_seq,rowid),evidence_id- """+ FROM evidence+ WHERE content_kind='raw_conversation'+ AND COALESCE(created_at, imported_at) >= ?+ AND (+ (role='user' AND written_by='person')+ OR role='assistant'+ )+ ORDER BY source_id,conversation_id,COALESCE(created_at,imported_at),+ COALESCE(ingest_seq,rowid),evidence_id+ """,+ (cutoff.astimezone(UTC).isoformat(),),).fetchall()- return tuple(- LegacyRawInventory(- evidence_id=str(row["evidence_id"]),- user_id=str(row["user_id"]),- agent_id="one-memory",- session_id=str(row["conversation_id"]),- source=str(row["source_id"]),- content=str(row["verbatim"]),- content_hash=str(row["content_hash"]),- memory_at=_parse_datetime(row["created_at"] or row["imported_at"]),- metadata={- key: row[key]- for key in (- "workspace",- "project",- "message_id",- "source_ordinal",- "content_kind",- "role",- "written_by",- "revision",- )- if row[key] is not None- },+ turns: list[LegacyRawInventory] = []+ current_key: tuple[str, str, str] | None = None+ current: list[sqlite3.Row] = []++ def finish() -> None:+ if not current or str(current[0]["role"]) != "user":+ return+ assistants = [row for row in current[1:] if str(row["role"]) == "assistant"]+ if not assistants:+ return+ rows_for_turn = [current[0], *assistants]+ evidence_ids = [str(row["evidence_id"]) for row in rows_for_turn]+ source = str(current[0]["source_id"])+ session_id = str(current[0]["conversation_id"])+ digest = hashlib.sha256(+ "\0".join((source, session_id, *evidence_ids)).encode()+ ).hexdigest()+ user_text = sanitize_model_input(+ str(rows_for_turn[0]["verbatim"]).strip()+ )[:_RAW_USER_MAX_CHARACTERS]+ content_parts = [f"[user]: {user_text}"]+ truncated = len(str(rows_for_turn[0]["verbatim"]).strip()) > len(user_text)+ for row in assistants:+ sanitized = sanitize_model_input(str(row["verbatim"]).strip())+ text = sanitized+ prefix = "[assistant]: "+ remaining = _RAW_TURN_MAX_CHARACTERS - len("\n".join(content_parts)) - 1+ if remaining <= len(prefix):+ truncated = True+ break+ available = remaining - len(prefix)+ if len(sanitized) > available:+ text = text[:available]+ truncated = True+ content_parts.append(f"{prefix}{text}")+ if len(text) < len(sanitized):+ break+ content = "\n".join(content_parts)+ if not content:+ return+ turns.append(+ LegacyRawInventory(+ evidence_id=f"turn:{digest}",+ user_id=str(current[0]["user_id"]),+ agent_id="all-apps",+ session_id=session_id,+ source=source,+ content=content,+ content_hash=content_hash(content),+ memory_at=_parse_datetime(+ current[0]["created_at"] or current[0]["imported_at"]+ ),+ metadata={+ "evidence_ids": evidence_ids,+ "workspace": current[0]["workspace"],+ "project": current[0]["project"],+ "input_kind": "legacy_turn",+ "truncated": truncated,+ },+ ))- for row in rows- )++ for row in rows:+ key = (+ str(row["source_id"]),+ str(row["conversation_id"]),+ str(row["user_id"]),+ )+ if key != current_key:+ finish()+ current_key, current = key, []+ if str(row["role"]) == "user":+ finish()+ current = [row]+ elif current:+ current.append(row)+ finish()+ return tuple(turns)def classify_memory_inventory(@@ -313,6 +418,17 @@ def classify_memory_inventory()continueif current is None:+ if item.productivity_kind is not None:+ decisions.append(+ MemoryMigrationDecision(+ item_key=f"memory:{item.legacy_memory_id}",+ action="quarantine",+ legacy_memory_id=item.legacy_memory_id,+ canonical_memory_id=item.canonical_memory_id,+ reason="mapped_productivity_memory_missing",+ )+ )+ continuedecisions.append(MemoryMigrationDecision(item_key=f"memory:{item.legacy_memory_id}",@@ -323,7 +439,19 @@ def classify_memory_inventory())continue- if (+ if item.productivity_kind is not None and (+ current.user_id == item.user_id+ and current.productivity_kind == item.productivity_kind+ and (+ item.productivity_variant is None+ or current.productivity_variant == item.productivity_variant+ )+ ):+ action = (+ "matched" if item.legacy_memory_id == item.canonical_memory_id else "record_alias"+ )+ reason = "existing_productivity_identity"+ elif (current.content_hash == item.content_hashand current.status == item.statusand current.user_id == item.user_id@@ -362,6 +490,7 @@ def classify_memory_inventory(async def read_sdk_memory_inventory(client: SdkMigrationClient,*,+ legacy: tuple[LegacyMemoryInventory, ...] = (),user_id: str = "local",page_size: int = 500,) -> tuple[SdkMemoryInventory, ...]:@@ -387,6 +516,29 @@ async def read_sdk_memory_inventory(offset += consumedif consumed == 0 or offset >= page.total:break+ for item in legacy:+ if (+ item.productivity_kind is None+ or item.canonical_memory_id in records+ ):+ continue+ resolved = await client.read_productivity_memory(+ item.canonical_memory_id,+ kind=item.productivity_kind,+ variant=item.productivity_variant,+ )+ if resolved is None:+ continue+ memory, actual_variant = resolved+ records[memory.memory_id] = SdkMemoryInventory(+ memory_id=memory.memory_id,+ user_id=memory.user_id,+ agent_id=memory.agent_id,+ content_hash=content_hash(memory.content),+ status=memory.status or "active",+ productivity_kind=item.productivity_kind,+ productivity_variant=actual_variant,+ )return tuple(records[key] for key in sorted(records))@@ -457,7 +609,15 @@ async def execute_memory_migration_plan(continueif decision.action in {"delete", "verified_deleted"}:if decision.action == "delete":- await client.delete(decision.canonical_memory_id)+ if item is not None and item.productivity_kind is not None:+ await client.delete_productivity_memory(+ decision.canonical_memory_id,+ kind=item.productivity_kind,+ variant=item.productivity_variant,+ user_id=item.user_id,+ )+ else:+ await client.delete(decision.canonical_memory_id)store.settle_item(migration_id=migration_id,item_key=decision.item_key,@@ -595,10 +755,10 @@ def classify_raw_inventory(decisions.append(RawMigrationDecision(item_key=f"sdk-raw:{raw.raw_id}",- action="adopt",+ action="delete",evidence_id=None,raw_id=raw.raw_id,- reason="sdk_only",+ reason="outside_canonical_three_day_turns",))return tuple(decisions)@@ -644,11 +804,12 @@ async def execute_raw_migration_plan() -> None:legacy_by_id = {item.evidence_id: item for item in legacy}for decision in decisions:- if decision.action == "adopt":+ if decision.action == "delete":+ await client.delete_raw(decision.raw_id)store.settle_item(migration_id=migration_id,item_key=decision.item_key,- state="adopted",+ state="deleted",target_memory_id=decision.raw_id,)continue@@ -677,8 +838,15 @@ async def execute_raw_migration_plan(target_memory_id=decision.raw_id,target_hash=item.content_hash,)- store.record_raw_alias(- migration_id=migration_id,- legacy_evidence_id=item.evidence_id,- canonical_raw_id=decision.raw_id,- )+ evidence_ids = item.metadata.get("evidence_ids")+ for evidence_id in (+ evidence_ids+ if isinstance(evidence_ids, list)+ else [item.evidence_id]+ ):+ if isinstance(evidence_id, str) and evidence_id:+ store.record_raw_alias(+ migration_id=migration_id,+ legacy_evidence_id=evidence_id,+ canonical_raw_id=decision.raw_id,+ )diff --git a/memhub/apps/core/src/one_memory/sdk_migration_runner.py b/memhub/apps/core/src/one_memory/sdk_migration_runner.pyindex fc6e528..85e3b2b 100644--- a/memhub/apps/core/src/one_memory/sdk_migration_runner.py+++ b/memhub/apps/core/src/one_memory/sdk_migration_runner.py@@ -9,6 +9,7 @@ import sqlite3from collections.abc import Callablefrom contextlib import suppressfrom dataclasses import dataclass+from datetime import UTC, datetime, timedeltafrom pathlib import Pathfrom one_memory.database_access import main_database@@ -406,14 +407,27 @@ async def run_sdk_data_plane_backfill(store.set_phase(migration_id, phase="inventory", state="running")legacy_memories = read_legacy_memory_inventory(database_path)- sdk_memories = await read_sdk_memory_inventory(client)+ sdk_memories = await read_sdk_memory_inventory(client, legacy=legacy_memories)memory_decisions = record_memory_migration_plan(store,migration_id=migration_id,legacy=legacy_memories,sdk=sdk_memories,)- legacy_raw = read_legacy_raw_inventory(database_path)+ with main_database(database_path).read(row_factory=sqlite3.Row) as database:+ started = database.execute(+ "SELECT created_at FROM sdk_data_plane_migrations WHERE migration_id=?",+ (migration_id,),+ ).fetchone()+ if started is None:+ raise DataPlaneMigrationError("sdk_data_plane_migration_start_missing")+ started_at = datetime.fromisoformat(str(started["created_at"]))+ if started_at.tzinfo is None:+ started_at = started_at.replace(tzinfo=UTC)+ legacy_raw = read_legacy_raw_inventory(+ database_path,+ cutoff=started_at.astimezone(UTC) - timedelta(days=3),+ )sdk_raw = await read_sdk_raw_inventory(client)raw_decisions = record_raw_migration_plan(store,diff --git a/memhub/apps/core/tests/test_cli_restore.py b/memhub/apps/core/tests/test_cli_restore.pyindex 7e61f40..7231294 100644--- a/memhub/apps/core/tests/test_cli_restore.py+++ b/memhub/apps/core/tests/test_cli_restore.py@@ -1,10 +1,15 @@+import asyncioimport io+import jsonimport sqlite3from types import SimpleNamespacefrom one_memory import clifrom one_memory.config import Settings+from one_memory.memory_server.migration_runner import SqliteMigrationStore, migrate+from one_memory.memory_server.migrations import MIGRATIONSfrom one_memory.runtime_client import RuntimeStatus+from one_memory.sdk_data_plane_migration import SdkDataPlaneMigrationStoredef test_restore_requires_a_source(tmp_path, monkeypatch) -> None:@@ -436,3 +441,41 @@ def test_sdk_migration_status_distinguishes_empty_and_legacy_data(tmp_path, monkassert cli.run(["sdk-migration-status", "--json"], output=required) == 0assert '"state": "required"' in required.getvalue()assert '"raw": 1' in required.getvalue()+++def test_sdk_migration_status_exposes_a_resumable_active_identity(tmp_path, monkeypatch) -> None:+ monkeypatch.setattr(+ cli,+ "load_settings",+ lambda: Settings(_env_file=None, data_dir=tmp_path),+ )+ database = tmp_path / "one-memory.sqlite3"+ asyncio.run(migrate(SqliteMigrationStore(database), MIGRATIONS))+ with sqlite3.connect(database) as connection:+ 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"+ ") VALUES ('e1','k','local','cursor','s','raw_conversation',"+ "'user','person','hello','hash',1,'now','now')"+ )+ SdkDataPlaneMigrationStore(database).start(+ migration_id="sdk-authority-v2-0123456789abcdef",+ source_runtime_build="17",+ target_sdk_version="2.0.5",+ source_schema_version=MIGRATIONS[-1].version,+ namespace_fingerprint="namespace",+ backend_fingerprint="backend",+ backup_bundle_id=(+ "sdk-authority-v2-0123456789abcdef-pre-cutover"+ ),+ )++ output = io.StringIO()+ assert cli.run(["sdk-migration-status", "--json"], output=output) == 0+ document = json.loads(output.getvalue())+ assert document["migration_id"] == "sdk-authority-v2-0123456789abcdef"+ assert document["bundle_id"] == (+ "sdk-authority-v2-0123456789abcdef-pre-cutover"+ )diff --git a/memhub/apps/core/tests/test_live_capture.py b/memhub/apps/core/tests/test_live_capture.pyindex 1525993..47be928 100644--- a/memhub/apps/core/tests/test_live_capture.py+++ b/memhub/apps/core/tests/test_live_capture.py@@ -2,6 +2,7 @@import asyncioimport json+import osimport sqlite3from contextlib import closingfrom io import StringIO@@ -20,6 +21,7 @@ from one_memory.memory_server.durable_queue import (DurableWriteQueue,execute_job,)+from one_memory.sdk_write_processor import SdkWriteReceiptdef _grant(tmp_path, source_id: str, *, sync: bool) -> EvidenceStore:@@ -233,14 +235,14 @@ def test_hook_job_completes_after_file_identity_adoption(tmp_path) -> None:).fetchone()class IdentityCheckingSupervisor:- async def process_records(+ async def process_sdk_job(self,records,*,+ request_id,before_hy_invocation,- source_admitted,):- assert source_admitted is True+ assert request_idwith closing(sqlite3.connect(database)) as connection:connection.execute("BEGIN")for record in records:@@ -249,7 +251,7 @@ def test_hook_job_completes_after_file_identity_adoption(tmp_path) -> None:assert ingest_journal.matches_current(connection, current)connection.rollback()await before_hy_invocation()- return ()+ return SdkWriteReceipt()drain = DurableWriteDrain(queue, execute=lambda _job: None)assert drain.claim(limit=1) == (job_id,)@@ -560,6 +562,30 @@ def test_capture_failure_stays_silent(tmp_path, monkeypatch) -> None:assert output.getvalue() == ""+def test_capture_is_a_silent_noop_during_sdk_migration(tmp_path, monkeypatch) -> None:+ database = tmp_path / "one-memory.sqlite3"+ marker = tmp_path / ".sdk-migration-capture-fence.json"+ marker.write_text(json.dumps({"schema_version": 1, "pid": os.getpid()}))+ monkeypatch.setattr("one_memory.live_capture.database_path", lambda: database)+ monkeypatch.setattr(+ "sys.stdin",+ StringIO(+ json.dumps(+ {+ "hook_event_name": "beforeSubmitPrompt",+ "conversation_id": "session",+ "prompt": "not persisted during migration",+ }+ )+ ),+ )+ output = StringIO()++ assert cli.run(["capture", "cursor"], output=output) == 0+ assert output.getvalue() == ""+ assert not database.exists()++def test_codex_harness_preamble_is_not_a_user_message(tmp_path) -> None:database = tmp_path / "one-memory.sqlite3"_grant(tmp_path, "codex", sync=True)diff --git a/memhub/apps/core/tests/test_sdk_data_plane_migration.py b/memhub/apps/core/tests/test_sdk_data_plane_migration.pyindex 8e59c37..9dac2de 100644--- a/memhub/apps/core/tests/test_sdk_data_plane_migration.py+++ b/memhub/apps/core/tests/test_sdk_data_plane_migration.py@@ -2,6 +2,10 @@ from __future__ import annotationsimport asyncioimport json+import sqlite3+import threading+from datetime import UTC, datetime, timedelta+from pathlib import Pathimport pytestfrom hy_memory.models.memory import MemoryLayer, MemoryStatus@@ -23,6 +27,7 @@ from one_memory.sdk_data_plane_migration import (MemoryAuthority,SdkDataPlaneMigrationStore,)+from one_memory.sdk_memory_runtime import SdkMemoryRuntimefrom one_memory.sdk_migration_bundle import create_sdk_migration_bundlefrom one_memory.sdk_migration_inventory import (LegacyMemoryInventory,@@ -366,6 +371,12 @@ def _legacy(status="active",layer="l2_fact",):+ productivity = {+ "coding_experience": ("experience", "coding"),+ "working_experience": ("experience", "working"),+ "coding_fact": ("fact", "coding"),+ "working_fact": ("fact", None),+ }.get(layer)return LegacyMemoryInventory(legacy_memory_id=legacy_id,canonical_memory_id=canonical_id or legacy_id,@@ -380,16 +391,27 @@ def _legacy(tags=(),supersedes=(),superseded_by=(),+ productivity_kind=productivity[0] if productivity else None,+ productivity_variant=productivity[1] if productivity else None,)-def _sdk(memory_id, *, content="body", status="active"):+def _sdk(+ memory_id,+ *,+ content="body",+ status="active",+ productivity_kind=None,+ productivity_variant=None,+):return SdkMemoryInventory(memory_id=memory_id,user_id="local",agent_id="one-memory",content_hash=content_hash(content),status=status,+ productivity_kind=productivity_kind,+ productivity_variant=productivity_variant,)@@ -430,7 +452,10 @@ class _MigrationClient:self.imported = []self.imported_raw = []self.deleted = []+ self.deleted_productivity = []+ self.deleted_raw = []self.raw = ()+ self.productivity = {}async def list_memories(self, *, limit, offset, **_kwargs):page = self.memories[offset : offset + limit]@@ -449,6 +474,22 @@ class _MigrationClient:self.deleted.append(memory_id)return {"success": True, "deleted_count": 1}+ async def read_productivity_memory(self, memory_id, *, kind, variant):+ if variant is not None:+ memory = self.productivity.get((memory_id, kind, variant))+ return None if memory is None else (memory, variant)+ for candidate in ("working", "coding"):+ memory = self.productivity.get((memory_id, kind, candidate))+ if memory is not None:+ return memory, candidate+ return None++ async def delete_productivity_memory(+ self, memory_id, *, kind, variant, user_id+ ):+ self.deleted_productivity.append((memory_id, kind, variant, user_id))+ return {"success": True, "deleted_count": 1}+async def read_raw_inventory(self, *, limit, offset, **_kwargs):rows = self.raw[offset : offset + limit]return HySdkRawPage(@@ -462,6 +503,10 @@ class _MigrationClient:self.imported_raw.append(kwargs)return {"success": True, "raw_id": kwargs["raw_id"]}+ async def delete_raw(self, raw_id):+ self.deleted_raw.append(raw_id)+ return {"success": True, "deleted_count": 1}+async def get_sdk_memory(self, memory_id):return next((memory for memory in self.memories if memory.memory_id == memory_id),@@ -500,6 +545,59 @@ def test_sdk_inventory_is_paged_without_dropping_lifecycle_records():]+def test_sdk_inventory_adopts_mapped_productivity_ids_and_deletes_user_removed_fact(store):+ active = _legacy("exp", layer="coding_experience")+ deleted = _legacy("fact", layer="working_fact", status="deleted")+ client = _MigrationClient()+ client.productivity = {+ ("exp", "experience", "coding"): HySdkMemoryRecord(+ memory_id="exp",+ content="sdk experience",+ layer="experience",+ status="active",+ is_latest=True,+ user_id="local",+ agent_id="scope",+ ),+ ("fact", "fact", "coding"): HySdkMemoryRecord(+ memory_id="fact",+ content="sdk fact",+ layer="fact",+ status="active",+ is_latest=True,+ user_id="local",+ agent_id="scope",+ ),+ }+ sdk = asyncio.run(+ read_sdk_memory_inventory(client, legacy=(active, deleted))+ )+ _start(store)+ decisions = record_memory_migration_plan(+ store,+ migration_id="m1",+ legacy=(active, deleted),+ sdk=sdk,+ )+ by_key = {decision.item_key: decision for decision in decisions}+ assert by_key["memory:exp"].action == "matched"+ assert by_key["memory:fact"].action == "delete"++ asyncio.run(+ execute_memory_migration_plan(+ client,+ store,+ migration_id="m1",+ legacy=(active, deleted),+ decisions=decisions,+ )+ )+ assert client.imported == []+ assert client.deleted_productivity == [+ ("fact", "fact", None, "local")+ ]++def test_recorded_plan_executes_import_delete_alias_and_adoption(store):_start(store)legacy = (@@ -538,32 +636,71 @@ def test_recorded_plan_executes_import_delete_alias_and_adoption(store):assert progress.counts == {"adopted": 1, "deleted": 2, "verified": 3}-def test_legacy_raw_inventory_preserves_exact_source_metadata(store):+def test_legacy_raw_inventory_builds_recent_user_assistant_turns_without_tools(store):database = store.database_pathwith main_database(database).write() as connection, connection:- connection.execute(+ connection.executemany("""INSERT INTO evidence (evidence_id,idempotency_key,user_id,source_id,workspace,project,conversation_id,message_id,source_ordinal,content_kind,role,written_by,created_at,verbatim,content_hash,revision,imported_at,updated_at,ingest_seq- ) VALUES (- 'e1','key','local','cursor','/repo','project','session','message',- '7','raw_conversation','user','person','2026-10-01T00:00:00+00:00',- 'verbatim',?,2,'2026-10-02T00:00:00+00:00',- '2026-10-02T00:00:00+00:00',1- )+ ) VALUES (?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?)""",- (content_hash("verbatim"),),+ (+ (+ "u1", "k1", "local", "cursor", "/repo", "project",+ "session", "m1", "1", "raw_conversation", "user",+ "person", "2026-10-22T00:00:00+00:00", "question",+ content_hash("question"), 1, "2026-10-22T00:00:00+00:00",+ "2026-10-22T00:00:00+00:00", 1,+ ),+ (+ "t1", "k2", "local", "cursor", "/repo", "project",+ "session", "m2", "2", "raw_conversation", "tool",+ "tool", "2026-10-22T00:00:01+00:00", "secret tool output",+ content_hash("secret tool output"), 1,+ "2026-10-22T00:00:01+00:00",+ "2026-10-22T00:00:01+00:00", 2,+ ),+ (+ "a1", "k3", "local", "cursor", "/repo", "project",+ "session", "m3", "3", "raw_conversation", "assistant",+ "agent", "2026-10-22T00:00:02+00:00", "answer",+ content_hash("answer"), 1, "2026-10-22T00:00:02+00:00",+ "2026-10-22T00:00:02+00:00", 3,+ ),+ (+ "old-u", "k4", "local", "cursor", "/repo", "project",+ "old-session", "m4", "4", "raw_conversation", "user",+ "person", "2026-10-01T00:00:00+00:00", "old question",+ content_hash("old question"), 1,+ "2026-10-01T00:00:00+00:00",+ "2026-10-01T00:00:00+00:00", 4,+ ),+ (+ "old-a", "k5", "local", "cursor", "/repo", "project",+ "old-session", "m5", "5", "raw_conversation", "assistant",+ "agent", "2026-10-01T00:00:01+00:00", "old answer",+ content_hash("old answer"), 1,+ "2026-10-01T00:00:01+00:00",+ "2026-10-01T00:00:01+00:00", 5,+ ),+ ),)- (raw,) = read_legacy_raw_inventory(database)- assert raw.evidence_id == "e1"+ (raw,) = read_legacy_raw_inventory(+ database,+ cutoff=datetime.fromisoformat("2026-10-20T00:00:00+00:00"),+ )+ assert raw.evidence_id.startswith("turn:")assert raw.session_id == "session"assert raw.source == "cursor"- assert raw.metadata["role"] == "user"- assert raw.metadata["revision"] == 2- assert raw.memory_at.isoformat() == "2026-10-01T00:00:00+00:00"+ assert raw.agent_id == "all-apps"+ assert raw.content == "[user]: question\n[assistant]: answer"+ assert raw.metadata["evidence_ids"] == ["u1", "a1"]+ assert "tool" not in raw.content+ assert raw.memory_at.isoformat() == "2026-10-22T00:00:00+00:00"def _legacy_raw(evidence_id, *, content="verbatim"):@@ -591,7 +728,7 @@ def _sdk_raw(raw_id, *, content="verbatim"):)-def test_raw_inventory_matches_exact_scope_imports_missing_and_adopts_sdk_only(store):+def test_raw_inventory_matches_turns_imports_missing_and_deletes_noncanonical_sdk_raw(store):legacy = (_legacy_raw("e1"), _legacy_raw("e2", content="missing"))sdk = (_sdk_raw("raw-existing"), _sdk_raw("raw-sdk-only", content="sdk-only"))decisions = classify_raw_inventory(legacy, sdk)@@ -600,7 +737,7 @@ def test_raw_inventory_matches_exact_scope_imports_missing_and_adopts_sdk_only(sassert by_key["raw:e1"].raw_id == "raw-existing"assert by_key["raw:e2"].action == "import_exact"assert by_key["raw:e2"].raw_id == "evidence:e2"- assert by_key["sdk-raw:raw-sdk-only"].action == "adopt"+ assert by_key["sdk-raw:raw-sdk-only"].action == "delete"_start(store)recorded = record_raw_migration_plan(@@ -620,7 +757,8 @@ def test_raw_inventory_matches_exact_scope_imports_missing_and_adopts_sdk_only(s))assert [item["raw_id"] for item in client.imported_raw] == ["evidence:e2"]- assert store.progress("m1").counts == {"adopted": 1, "verified": 2}+ assert client.deleted_raw == ["raw-sdk-only"]+ assert store.progress("m1").counts == {"deleted": 1, "verified": 2}def test_sdk_raw_inventory_pages_all_records():@@ -675,6 +813,20 @@ def test_offline_backfill_reaches_ready_without_committing_cutover(store):""",(content_hash("verbatim"),),)+ 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 (+ 'a1','assistant-key','local','cursor','session','raw_conversation',+ 'assistant','agent','reply',?,1,+ '2026-10-21T00:00:01+00:00','2026-10-21T00:00:01+00:00',2+ )+ """,+ (content_hash("reply"),),+ )client = _MigrationClient()result = asyncio.run(run_sdk_data_plane_backfill(@@ -694,7 +846,9 @@ def test_offline_backfill_reaches_ready_without_committing_cutover(store):assert result.phase == "reconciled"assert result.counts == {"verified": 2}assert [item["memory_id"] for item in client.imported] == ["memory-1"]- assert [item["raw_id"] for item in client.imported_raw] == ["evidence:e1"]+ assert len(client.imported_raw) == 1+ assert client.imported_raw[0]["content"] == "[user]: verbatim\n[assistant]: reply"+ migrated_raw_id = client.imported_raw[0]["raw_id"]assert store.authority() is MemoryAuthority.LEGACY# Simulate a process dying after both SDK side effects but before startup# could finish. The next inventory observes them as matched rather than@@ -703,13 +857,13 @@ def test_offline_backfill_reaches_ready_without_committing_cutover(store):client.memories = (_record("memory-1", content="preference"),)client.raw = (HySdkRawRecord(- raw_id="evidence:e1",- content="verbatim",+ raw_id=migrated_raw_id,+ content="[user]: verbatim\n[assistant]: reply",user_id="local",- agent_id="one-memory",+ agent_id="all-apps",session_id="session",source="cursor",- custom={"role": "user", "written_by": "person"},+ custom={"input_kind": "legacy_turn"},),)resumed = asyncio.run(@@ -803,12 +957,44 @@ class _MigrationGraphStore:return node.node_id+class _MigrationFactVector:+ def __init__(self):+ self.deleted = []++ async def delete(self, memory_id):+ self.deleted.append(memory_id)+ return True+++class _MigrationCodingStore:+ def __init__(self):+ self._conn = sqlite3.connect(":memory:", check_same_thread=False)+ self._conn.execute(+ "CREATE TABLE working_fact (fact_id TEXT PRIMARY KEY, user_id TEXT)"+ )+ self._conn.execute("INSERT INTO working_fact VALUES ('fact-1','local')")+ self._conn.commit()+ self._lock = threading.Lock()+ self._fact_vec = _MigrationFactVector()++ async def get_fact(self, memory_id, *, user_id):+ row = self._conn.execute(+ "SELECT 1 FROM working_fact WHERE fact_id=? AND user_id=?",+ (memory_id, user_id),+ ).fetchone()+ return object() if row is not None else None++class _PrivilegedMigrationClient:def __init__(self):self._loop_thread = _MigrationLoop()self._vector_store = _MigrationVectorStore()self._embed_service = _MigrationEmbedder()self._graph_store = _MigrationGraphStore()+ self._coding = _MigrationCodingStore()++ async def _coding_store_for_exact_get(self, variant):+ return self._coding if variant == "coding" else Nonedef list_memories(self, **_kwargs):return {"vdb": {"memories": [], "total": 0}, "request_id": "list"}@@ -858,6 +1044,14 @@ def test_offline_migration_writes_sdk_stores_without_public_client_import_method))raw_page = asyncio.run(migration.read_raw_inventory(user_id="local"))+ deleted = asyncio.run(+ migration.delete_productivity_memory(+ "fact-1",+ kind="fact",+ variant=None,+ user_id="local",+ )+ )assert raw_result["raw_id"] == "raw-1"assert memory_result["memory_id"] == "memory-1"@@ -865,6 +1059,14 @@ def test_offline_migration_writes_sdk_stores_without_public_client_import_methodassert client._vector_store.nodes["raw-1"].layer is MemoryLayer.L1_RAWassert client._vector_store.nodes["memory-1"].status is MemoryStatus.ACTIVEassert client._graph_store.nodes["memory-1"].content == "prefers tea"+ assert deleted["deleted_count"] == 1+ assert client._coding._fact_vec.deleted == ["fact-1"]+ assert (+ client._coding._conn.execute(+ "SELECT COUNT(*) FROM working_fact"+ ).fetchone()[0]+ == 0+ )assert not hasattr(client, "import_raw")assert not hasattr(client, "import_memory_exact")@@ -898,6 +1100,57 @@ def test_raw_http_dto_uses_the_unified_memory_list_shape():assert page.raw[0].custom == {"role": "user"}+def test_sdk_raw_retention_keeps_only_the_latest_three_days():+ now = datetime(2026, 10, 23, tzinfo=UTC)++ class Client:+ def __init__(self):+ self.rows = [+ {+ "memory_id": "old",+ "memory_at": int((now - timedelta(days=4)).timestamp()),+ },+ {+ "memory_id": "recent",+ "memory_at": int((now - timedelta(days=2)).timestamp()),+ },+ ]++ def list_memories(self, **_kwargs):+ return {+ "vdb": {+ "memories": list(self.rows),+ "total": len(self.rows),+ "limit": 500,+ "offset": 0,+ }+ }++ def delete(self, memory_id):+ before = len(self.rows)+ self.rows = [row for row in self.rows if row["memory_id"] != memory_id]+ return {+ "success": True,+ "deleted_count": before - len(self.rows),+ }++ client = Client()++ class Handle:+ async def client(self):+ return client++ runtime = SdkMemoryRuntime(+ coordinator=None,+ read_handle=Handle(),+ write_queue=None,+ extraction_settings=None,+ data_dir=Path("."),+ )+ assert asyncio.run(runtime.prune_expired_raw(now=now)) == 1+ assert [row["memory_id"] for row in client.rows] == ["recent"]++def _staging_fixture(tmp_path, store):data_dir = tmp_path / "home"live = data_dir / "hy-memory" / "governed-v2"diff --git a/memhub/apps/desktop/src/startup-sdk-migration.test.ts b/memhub/apps/desktop/src/startup-sdk-migration.test.tsindex 3123354..b1371ea 100644--- a/memhub/apps/desktop/src/startup-sdk-migration.test.ts+++ b/memhub/apps/desktop/src/startup-sdk-migration.test.ts@@ -1,10 +1,34 @@+import { access, mkdtemp, readFile } from "node:fs/promises";+import os from "node:os";+import path from "node:path";import { expect, it, vi } from "vitest";import {requireCompletedStartupSdkMigration,runStartupSdkMigration,+ withSdkMigrationCaptureFence,} from "./startup-sdk-migration";const core = { command: "/core/one-memory", args: [] };+const captureFence = async <T>(+ _dataDir: string,+ action: () => Promise<T>,+): Promise<T> => action();++it("fences hook capture only while startup migration is running", async () => {+ const dataDir = await mkdtemp(+ path.join(os.tmpdir(), "memhub-sdk-migration-"),+ );+ const marker = path.join(dataDir, ".sdk-migration-capture-fence.json");++ await withSdkMigrationCaptureFence(dataDir, async () => {+ const document = JSON.parse(await readFile(marker, "utf8")) as {+ pid: number;+ };+ expect(document.pid).toBe(process.pid);+ });++ await expect(access(marker)).rejects.toThrow();+});it("runs bundle backfill and cutover inside the startup maintenance fence", async () => {const calls: string[][] = [];@@ -42,6 +66,7 @@ it("runs bundle backfill and cutover inside the startup maintenance fence", asynruntimeBuild: "build-13",execute,fence,+ captureFence,});expect(result).toEqual({ state: "cutover" });@@ -73,6 +98,7 @@ it("does not stop Runtime when authority is already SDK or the home is empty", aruntimeBuild: "build-13",execute: vi.fn(async () => ({ exitCode: 0, document })),fence,+ captureFence,});expect(result).toEqual({ state: "not_required" });expect(fenced).toBe(false);@@ -86,6 +112,7 @@ it("reports an unreadable migration status as deferred", async () => {runtimeBuild: "build-13",execute: vi.fn(async () => ({ exitCode: 1, document: {} })),fence: async (_dataDir, action) => action(),+ captureFence,});expect(result).toEqual({@@ -116,6 +143,7 @@ it("resumes legacy table cleanup under the maintenance fence", async () => {: { exitCode: 0, document: { state: "clean" } };}),fence: async (_dataDir, action) => action(),+ captureFence,});expect(result).toEqual({ state: "cutover" });@@ -146,6 +174,7 @@ it("keeps legacy authority when backfill is blocked", async () => {runtimeBuild: "build-13",execute,fence: async (_dataDir, action) => action(),+ captureFence,});expect(result).toEqual({ state: "deferred", code: "quarantine" });@@ -153,3 +182,42 @@ it("keeps legacy authority when backfill is blocked", async () => {"sdk-cutover",);});++it("reuses one v2 migration identity after a blocked startup", async () => {+ const calls: string[][] = [];+ const migrationId = "sdk-authority-v2-0123456789abcdef";+ const bundleId = `${migrationId}-pre-cutover`;+ const execute = vi.fn(async (_core, args: string[]) => {+ calls.push(args);+ return args[0] === "sdk-migration-status"+ ? {+ exitCode: 0,+ document: {+ authority: "legacy",+ state: "required",+ generation: "ffffffffffffffff",+ migration_id: migrationId,+ bundle_id: bundleId,+ },+ }+ : args[0] === "sdk-migrate"+ ? { exitCode: 4, document: { state: "blocked", code: "quarantine" } }+ : { exitCode: 0, document: { state: "reused" } };+ });++ await runStartupSdkMigration({+ dataDir: "/data",+ core,+ runtimeBuild: "build-17",+ execute,+ fence: async (_dataDir, action) => action(),+ captureFence,+ });++ expect(calls.find((args) => args[0] === "migration-bundle")).toContain(+ bundleId,+ );+ expect(calls.find((args) => args[0] === "sdk-migrate")).toContain(+ migrationId,+ );+});diff --git a/memhub/apps/desktop/src/startup-sdk-migration.ts b/memhub/apps/desktop/src/startup-sdk-migration.tsindex 3ca5777..a4e2e81 100644--- a/memhub/apps/desktop/src/startup-sdk-migration.ts+++ b/memhub/apps/desktop/src/startup-sdk-migration.ts@@ -1,8 +1,11 @@import { spawn } from "node:child_process";+import { mkdir, rename, rm, writeFile } from "node:fs/promises";+import path from "node:path";import { withRuntimeMaintenanceFence } from "@one-memory/runtime-control";-const MIGRATION_PREFIX = "sdk-authority-v1";+const MIGRATION_PREFIX = "sdk-authority-v2";const MAX_OUTPUT_BYTES = 1024 * 1024;+const CAPTURE_FENCE = ".sdk-migration-capture-fence.json";export interface StartupMigrationResult {state: "not_required" | "cutover" | "deferred";@@ -39,6 +42,7 @@ interface StartupMigrationOptions {dataDir: string,) => Promise<CommandResult>;fence?: <T>(dataDir: string, action: () => Promise<T>) => Promise<T>;+ captureFence?: <T>(dataDir: string, action: () => Promise<T>) => Promise<T>;}export async function runStartupSdkMigration(@@ -46,6 +50,7 @@ export async function runStartupSdkMigration(): Promise<StartupMigrationResult> {const execute = options.execute ?? executeCoreCommand;const fence = options.fence ?? withRuntimeMaintenanceFence;+ const captureFence = options.captureFence ?? withSdkMigrationCaptureFence;const status = await execute(options.core,["sdk-migration-status", "--json"],@@ -58,16 +63,18 @@ export async function runStartupSdkMigration(status.document.authority === "sdk" &&status.document.state === "cleanup_required") {- return fence(options.dataDir, async () => {- const cleanup = await execute(- options.core,- ["sdk-cleanup", "--yes", "--json"],- options.dataDir,- );- return cleanup.exitCode === 0 && cleanup.document.state === "clean"- ? { state: "cutover" }- : deferred(cleanup);- });+ return fence(options.dataDir, () =>+ captureFence(options.dataDir, async () => {+ const cleanup = await execute(+ options.core,+ ["sdk-cleanup", "--yes", "--json"],+ options.dataDir,+ );+ return cleanup.exitCode === 0 && cleanup.document.state === "clean"+ ? { state: "cutover" }+ : deferred(cleanup);+ }),+ );}if (status.document.authority === "sdk" ||@@ -79,57 +86,89 @@ export async function runStartupSdkMigration(if (typeof generation !== "string" || !/^[a-f0-9]{16}$/.test(generation)) {return { state: "deferred", code: "sdk_migration_generation_invalid" };}- const migrationId = `${MIGRATION_PREFIX}-${generation}`;- const bundleId = `${migrationId}-pre-cutover`;- return fence(options.dataDir, async () => {- const bundle = await execute(- options.core,- [- "migration-bundle",- "--bundle-id",- bundleId,- "--runtime-build",- options.runtimeBuild,- "--yes",- "--json",- ],- options.dataDir,- );- if (bundle.exitCode !== 0) return deferred(bundle);- const backfill = await execute(- options.core,- [- "sdk-migrate",- "--migration-id",- migrationId,- "--bundle-id",- bundleId,- "--yes",- "--json",- ],- options.dataDir,- );- if (backfill.exitCode !== 0 || backfill.document.state !== "ready") {- return deferred(backfill);- }- const cutover = await execute(- options.core,- [- "sdk-cutover",- "--migration-id",- migrationId,- "--bundle-id",- bundleId,- "--yes",- "--json",- ],- options.dataDir,- );- if (cutover.exitCode !== 0 || cutover.document.state !== "cutover") {- return deferred(cutover);- }- return { state: "cutover" };- });+ const previousMigrationId = status.document.migration_id;+ const previousBundleId = status.document.bundle_id;+ const canResume =+ typeof previousMigrationId === "string" &&+ previousMigrationId.startsWith(`${MIGRATION_PREFIX}-`) &&+ typeof previousBundleId === "string" &&+ previousBundleId === `${previousMigrationId}-pre-cutover`;+ const migrationId = canResume+ ? previousMigrationId+ : `${MIGRATION_PREFIX}-${generation}`;+ const bundleId = canResume ? previousBundleId : `${migrationId}-pre-cutover`;+ return fence(options.dataDir, () =>+ captureFence(options.dataDir, async () => {+ const bundle = await execute(+ options.core,+ [+ "migration-bundle",+ "--bundle-id",+ bundleId,+ "--runtime-build",+ options.runtimeBuild,+ "--yes",+ "--json",+ ],+ options.dataDir,+ );+ if (bundle.exitCode !== 0) return deferred(bundle);+ const backfill = await execute(+ options.core,+ [+ "sdk-migrate",+ "--migration-id",+ migrationId,+ "--bundle-id",+ bundleId,+ "--yes",+ "--json",+ ],+ options.dataDir,+ );+ if (backfill.exitCode !== 0 || backfill.document.state !== "ready") {+ return deferred(backfill);+ }+ const cutover = await execute(+ options.core,+ [+ "sdk-cutover",+ "--migration-id",+ migrationId,+ "--bundle-id",+ bundleId,+ "--yes",+ "--json",+ ],+ options.dataDir,+ );+ if (cutover.exitCode !== 0 || cutover.document.state !== "cutover") {+ return deferred(cutover);+ }+ return { state: "cutover" };+ }),+ );+}++export async function withSdkMigrationCaptureFence<T>(+ dataDir: string,+ action: () => Promise<T>,+): Promise<T> {+ await mkdir(dataDir, { recursive: true, mode: 0o700 });+ const marker = path.join(dataDir, CAPTURE_FENCE);+ const temporary = `${marker}.${process.pid}.tmp`;+ await writeFile(+ temporary,+ `${JSON.stringify({ schema_version: 1, pid: process.pid })}\n`,+ { encoding: "utf8", mode: 0o600 },+ );+ await rename(temporary, marker);+ try {+ return await action();+ } finally {+ await rm(marker, { force: true });+ await rm(temporary, { force: true });+ }}function deferred(result: CommandResult): StartupMigrationResult {diff --git a/memhub/docs/ARCHITECTURE.md b/memhub/docs/ARCHITECTURE.mdindex d1fdc68..62cd86f 100644--- a/memhub/docs/ARCHITECTURE.md+++ b/memhub/docs/ARCHITECTURE.md@@ -130,6 +130,7 @@ This exception does not extend to VDB, Coding, prompt, reconcile, or lifecycle.- Storage backends:仅 SDK config/env(Chroma/FAISS/Qdrant、Kuzu/Neo4j、cache/history sqlite|mysql、coding sqlite 等)。- Queue:pending `memory_write_jobs` 只表示尚未调用 SDK 的待处理请求,因此没有 SDK raw/memory ID。worker 单次调用 SDK `add()`;SDK 内部完成 raw 写入与 extraction/reconciliation,成功后 MemHub 仅将返回的 raw ID / memory IDs 记作 job outcome。旧用户启动迁移在 Runtime writers 停止期间直接操作 SDK 存储,不向公开 `HyMemoryClient` 增加迁移专用方法,也不拆分正常写路径。+- Raw retention:SDK L1 raw 只保留最近三天;每个完整 turn 只保存真人 user 与 assistant,tool 不进入 raw。高层 Chat/Coding/Working memory 不受该窗口影响。- Recall:Host Bridge / Core 先做宿主安装凭据与 tool grant,再调 **SDK search/get**。当前产品没有逐 memory 的 A-harness→B-harness 可见性开关,默认允许跨 harness 搜索;未来若增加来源限制,直接透传 SDK `source` / `include_sources` / `exclude_sources`,不在 MemHub 建 memory ACL。- Context wire:cutover marker 提交前只使用 legacy Context v1;提交后 Host Bridge 只使用 SDK-native Context v2。两种 schema 原样校验、原样返回,不把 SDK item 补造成 v1 的 `revision`、`evidence_ids`、`paths` 或 `adoption`,已选择的 v2 路径失败时也不回退 legacy 权威。- Ask wire:marker 前保留 Governance Ask v1;marker 后 Web / Host Bridge 只调用 SDK Ask v2。v2 的引用只含 SDK 原生 `memory_id/content/layer/status/source/gmt_created`,生成过程中重复 `get` 校验同一 SDK 快照,不补造 revision、Evidence 或 scopes,SDK 失败不回退 v1。@@ -138,6 +139,8 @@ This exception does not extend to VDB, Coding, prompt, reconcile, or lifecycle.- SDK backfill 只写同文件系统的私有 staging 副本;验证后先原子切换 SDKroot,再提交 authority marker。切换或 marker 提交失败必须恢复原 live root;App 不得在 migration `deferred` 状态继续启动 Runtime。+- 迁移期间宿主 capture hook 由 Desktop 活跃 PID marker 静默挡住,不再追加+ Evidence;cutover 后先从宿主 History checkpoint 补齐遗漏 turn,再恢复 live sync。- Matter 若未来重新开发,需以新的 SDK-native 合同重新设计,不继承当前占位 schema。Pinned SDK 版本见发布锁文件 / `MEMORY.md`(随发布更新)。diff --git a/memhub/docs/contracts/sdk-data-plane-migration-v1.md b/memhub/docs/contracts/sdk-data-plane-migration-v1.mdindex 4f31ed0..a14f2ea 100644--- a/memhub/docs/contracts/sdk-data-plane-migration-v1.md+++ b/memhub/docs/contracts/sdk-data-plane-migration-v1.md@@ -19,6 +19,9 @@ Before the cutover marker is committed:- SDK stores are inspected and backfilled, but are not merged into live search;- new imports, writes, queue drains, corrections, deletes and session deliveryare paused.+- Host capture commands detect the live Desktop migration fence and return+ silently without writing Evidence. After cutover, History catch-up runs from+ the existing source cursor before ordinary live sync.After the cutover marker is committed:@@ -49,12 +52,9 @@ The migration preflight records and validates:- embedding model identity and dimensions;- source grants, model profiles, config, queue leases, and pending operations.-The migration fails closed when the installed SDK lacks:--- complete lifecycle/raw inventory;-- exact raw and exact memory import;-- durable request outcome lookup;-- consistent snapshot/export and restore.+The migration fails closed when it cannot inspect every SDK memory namespace+(Chat, Coding Experience, Working Fact), write a missing ordinary memory, or+create and restore a consistent data-plane snapshot.MemHub tags `v1.0.0` through `v1.0.4` all use the `governed-v2` namespace andthe same SDK SQL table families (`memory_operations_v2`, `pipeline_logs_v2`,@@ -71,10 +71,10 @@ because an earlier App wrote it.While Core and Runtime writers are stopped, build four inventories:-- `E`: Evidence rows and revisions;+- `E`: completed user/assistant turns from the rolling three-day legacy window;- `G`: current Governance rows, statuses, supersession links, and latest content;- `M`: task-output mappings from legacy `memory_id` to SDK `hy_memory_id`;-- `S`: complete SDK inventory, including raw and non-active lifecycle records.+- `S`: complete SDK inventory, including Coding/Working and non-active records.Every item must end in exactly one class:@@ -85,7 +85,7 @@ Every item must end in exactly one class:| Governance-only | current legacy memory has no SDK entity | exact import without extraction || SDK-only | SDK entity has no legacy mirror | retain and adopt || divergent | both exist but content, owner or lifecycle differs | reconcile explicit user intent or quarantine |-| raw-only | Evidence has no SDK raw receipt | exact raw import |+| raw turn missing | canonical recent turn has no matching SDK raw | write one bounded L1 raw turn || unknown outcome | a task may have reached SDK without a confirmed result | SDK outcome inquiry; never blind retry |An unclassified item blocks cutover.@@ -102,26 +102,30 @@ The current product has no MemHub revision history or Undo.- SDK supersession remains an SDK lifecycle relationship. Existing SDK chainsare retained. Governance links are used only to repair a missing SDK chainduring exact import.+- Mapped Coding Experience and Working Fact IDs are resolved in their native+ SDK stores and adopted without conversion to Chat layers. A mapped ID missing+ from its native store blocks cutover rather than fabricating another type.- Pending correction/delete records are settled before ordinary backfill.`update(memory_id, content)` modifies the same SDK ID. There is no product CAS,revision number, or restore operation.-## 5. Evidence to SDK raw--Evidence must not be replayed through ordinary `add()`: doing so would extract-and reconcile again, changing semantic memories.+## 5. Legacy Evidence to bounded SDK raw-The SDK exact-raw import preserves:+Evidence rows are message-level legacy storage, not SDK raw chunks. Migration+uses them only to rebuild completed turns from the three days preceding the+stable migration start time:-- source, conversation/session, workspace, role and author;-- original event time and stable source ordering;-- verbatim content and source identity;-- a deterministic migration key.+- one human `user` opener plus its following `assistant` records becomes one+ deterministic L1 raw node;+- tool rows and agent-authored user envelopes are excluded;+- a turn is bounded to 60,000 characters and records whether it was truncated;+- existing SDK raw outside this canonical set is removed in staging;+- high-level Chat/Coding/Working memories are retained independently of raw.-The operation is idempotent and returns an SDK raw ID. Evidence revisions and-repairs are preserved in the migration bundle for audit; only the current-accepted raw record becomes the normal product read.+No extraction or reconciliation is rerun while rebuilding raw. After cutover,+the normal Cursor History catch-up scans forward from its source checkpoint and+recovers turns skipped while capture was fenced.## 6. Full migration bundle