Skip to content
Python

fix(memhub): reattach stranded vectors and read memories back before cutover

alvinfeid8837b4fb22e
diff --git a/memhub/apps/cli/src/cli.ts b/memhub/apps/cli/src/cli.ts
index b451ad7..4cdb1d6 100644
--- a/memhub/apps/cli/src/cli.ts
+++ b/memhub/apps/cli/src/cli.ts
@@ -4131,6 +4131,15 @@ function notReadyAfterMigration(command: "install" | "upgrade") {
};
}
+const SDK_MIGRATION_FAILURES: Record<string, string> = {
+ sdk_migration_disk_space_insufficient:
+ "磁盘空间不足,记忆数据迁移没有完成,已回滚到上一版本。请腾出与记忆数据同等大小的空间后重试;原有记忆数据不会丢失。",
+ sdk_migration_memory_unreadable:
+ "核对发现新版本还读不到你的全部记忆,没有切换数据源,已回滚到上一版本。请把这个错误码反馈给我们;原有记忆数据不会丢失。",
+ sdk_migration_model_profile_required:
+ "迁移需要先有可用的模型配置,用来核对新版本能否读回记忆。已回滚到上一版本;请先用 memhub models setup 完成配置后再升级。",
+};
+
function sdkMigrationFailure(command: "install" | "upgrade", code: string) {
return {
schema_version: 1,
@@ -4139,9 +4148,8 @@ function sdkMigrationFailure(command: "install" | "upgrade", code: string) {
status: "error",
code,
message:
- code === "sdk_migration_disk_space_insufficient"
- ? "磁盘空间不足,记忆数据迁移没有完成,已回滚到上一版本。请腾出与记忆数据同等大小的空间后重试;原有记忆数据不会丢失。"
- : "记忆数据迁移没有完成,已回滚到上一版本。请重试;如果仍然失败,请把这个错误码反馈给我们。原有记忆数据不会丢失。",
+ SDK_MIGRATION_FAILURES[code] ??
+ "记忆数据迁移没有完成,已回滚到上一版本。请重试;如果仍然失败,请把这个错误码反馈给我们。原有记忆数据不会丢失。",
};
}
diff --git a/memhub/apps/core/src/one_memory/api.py b/memhub/apps/core/src/one_memory/api.py
index b42e0a1..19d462d 100644
--- a/memhub/apps/core/src/one_memory/api.py
+++ b/memhub/apps/core/src/one_memory/api.py
@@ -3130,11 +3130,8 @@ def create_app(
store = getattr(app.state, "sdk_data_plane_migrations", None)
if store is None:
store = SdkDataPlaneMigrationStore(_evidence_store(app).database_path)
- marker = store.cutover()
- return MemoryAuthorityResponse(
- authority="sdk" if marker is not None else "legacy",
- migration_id=marker.migration_id if marker is not None else None,
- )
+ authority, migration_id = store.authority_state()
+ return MemoryAuthorityResponse(authority=authority.value, migration_id=migration_id)
@app.get(
"/api/v2/memory-library",
diff --git a/memhub/apps/core/src/one_memory/cli.py b/memhub/apps/core/src/one_memory/cli.py
index c5676de..ee81e05 100644
--- a/memhub/apps/core/src/one_memory/cli.py
+++ b/memhub/apps/core/src/one_memory/cli.py
@@ -335,6 +335,8 @@ def sdk_migrate(options: Sequence[str], stream: TextIO) -> int:
"bundle": "正在备份记忆数据……",
"prepare": "正在整理待处理的写入任务……",
"cutover": "正在切换数据源……",
+ "vectors": "正在接回旧版本的向量数据……",
+ "verify": "正在用新版本核对记忆能否读回……",
"cleanup": "正在删除旧表……",
}
@@ -356,13 +358,17 @@ def sdk_migrate(options: Sequence[str], stream: TextIO) -> int:
progress=progress,
)
except Exception as error:
+ from one_memory.sdk_migration_verify import MemoryReadbackFailed
+
code = migration_failure_code(error)
- document = {"schema_version": 1, "state": "failed", "code": code}
- _write_restore(stream, as_json, document, f"迁移未完成:{code}")
+ failed: dict[str, object] = {"schema_version": 1, "state": "failed", "code": code}
+ if isinstance(error, MemoryReadbackFailed):
+ failed["readback"] = error.report.as_document()
+ _write_restore(stream, as_json, failed, f"迁移未完成:{code}")
return 1
messages = {
"not_required": "不需要迁移。",
- "complete": "迁移已完成,旧表已清理。",
+ "complete": "迁移已完成;遗留的旧表或向量已处理。",
"cutover": "迁移完成:记忆数据已以 SDK 为准。",
}
_write_restore(stream, as_json, result.as_document(), messages[result.state])
@@ -390,16 +396,23 @@ def sdk_migration_status(options: Sequence[str], stream: TextIO) -> int:
SdkDataPlaneMigrationStore,
)
from one_memory.sdk_migration_runner import abandoned_staging_present
+ from one_memory.sdk_migration_verify import read_active_profile
+ from one_memory.sdk_vector_reattach import legacy_vector_collections
from one_memory.target_schema import legacy_tables_present
authority = SdkDataPlaneMigrationStore(database_path).authority()
if authority is MemoryAuthority.SDK:
+ profile = read_active_profile(database_path)
leftovers = bool(
legacy_tables_present(database_path)
or abandoned_staging_present(
data_dir=settings.data_dir,
namespace=HY_MEMORY_NAMESPACE,
)
+ or (
+ profile is not None
+ and legacy_vector_collections(settings.data_dir, profile)
+ )
)
state = "required" if leftovers else "not_required"
else:
diff --git a/memhub/apps/core/src/one_memory/hy_sdk_runtime.py b/memhub/apps/core/src/one_memory/hy_sdk_runtime.py
index 5c461b6..a510dcc 100644
--- a/memhub/apps/core/src/one_memory/hy_sdk_runtime.py
+++ b/memhub/apps/core/src/one_memory/hy_sdk_runtime.py
@@ -237,15 +237,9 @@ def build_sdk_config(
root = data_dir.resolve() / "hy-memory" / "governed-v2"
root.mkdir(parents=True, exist_ok=True)
- collection_identity = "\0".join(
- (
- embedding_provider.value,
- embedding_endpoint or "local",
- embedding_model,
- str(dimensions or "auto"),
- )
+ collection = _collection_base(
+ embedding_provider, embedding_endpoint, embedding_model, dimensions
)
- collection = "memhub_" + hashlib.sha256(collection_identity.encode()).hexdigest()[:16]
return MemoryConfig.from_dict(
{
@@ -348,6 +342,49 @@ def _generation_access(
return endpoint, api_key
+def _collection_base(
+ provider: ProviderKind,
+ endpoint: str | None,
+ model: str,
+ dimensions: int | None,
+) -> str:
+ identity = "\0".join((provider.value, endpoint or "local", model, str(dimensions or "auto")))
+ return "memhub_" + hashlib.sha256(identity.encode()).hexdigest()[:16]
+
+
+def vector_collection_bases(profile: ModelProfileSnapshot) -> tuple[str, tuple[str, ...]]:
+ """The SDK vector collection base for this embedding space, and the older ones.
+
+ The SDK derives every vector collection (chat, Coding keys, Working facts,
+ each variant) by suffixing this base. Builds before #145 named the same
+ embedding space `one_memory_<12 hex>`, with or without a declared width;
+ the offline migration renames those so their vectors stay readable.
+ """
+ provider = profile.embedding_provider_kind or profile.provider_kind
+ local = provider is ProviderKind.LOCAL_ONNX
+ model = profile.embedding_model or (BUILTIN_EMBEDDING_MODEL if local else None)
+ if not model:
+ raise HySdkRuntimeError("hy_sdk_embedding_model_required")
+ endpoint: str | None
+ dimensions: int | None
+ if local:
+ endpoint, dimensions = None, profile.embedding_dimensions or BUILTIN_EMBEDDING_DIMENSIONS
+ legacy_endpoint = "local-onnx"
+ else:
+ endpoint = _openai_endpoint(provider, profile.embedding_base_url or profile.base_url)
+ dimensions = profile.embedding_dimensions
+ legacy_endpoint = endpoint
+ legacy_model = profile.embedding_model or "bge-small-zh-v1.5"
+ legacy = tuple(
+ "one_memory_"
+ + hashlib.sha256(
+ ":".join((provider.value, legacy_endpoint, legacy_model, *declared)).encode()
+ ).hexdigest()[:12]
+ for declared in ((), ("auto",), (str(profile.embedding_dimensions or "auto"),))
+ )
+ return _collection_base(provider, endpoint, model, dimensions), tuple(dict.fromkeys(legacy))
+
+
def _openai_endpoint(provider: ProviderKind, endpoint: str | None) -> str:
value = (endpoint or "").rstrip("/")
if not value:
diff --git a/memhub/apps/core/src/one_memory/sdk_data_plane_migration.py b/memhub/apps/core/src/one_memory/sdk_data_plane_migration.py
index ced4278..502f37b 100644
--- a/memhub/apps/core/src/one_memory/sdk_data_plane_migration.py
+++ b/memhub/apps/core/src/one_memory/sdk_data_plane_migration.py
@@ -50,18 +50,29 @@ class SdkDataPlaneMigrationStore:
return datetime.now(UTC).isoformat()
def authority(self) -> MemoryAuthority:
+ return self.authority_state()[0]
+
+ def authority_state(self) -> tuple[MemoryAuthority, str | None]:
+ """The surviving singleton: authority and the migration that set it.
+
+ This is the only source of authority. The detailed cutover receipt is
+ dropped after cleanup and never exists on a fresh home.
+ """
try:
with main_database(self.database_path).read() as connection:
row = connection.execute(
- "SELECT authority FROM memory_authority_state WHERE singleton=1"
+ "SELECT authority,migration_id FROM memory_authority_state WHERE singleton=1"
).fetchone()
except sqlite3.OperationalError as error:
if "no such table" not in str(error).lower():
raise
else:
if row is not None:
- return MemoryAuthority(str(row[0]))
- return MemoryAuthority.SDK if self.cutover() is not None else MemoryAuthority.LEGACY
+ return MemoryAuthority(str(row[0])), (str(row[1]) if row[1] else None)
+ marker = self.cutover()
+ if marker is not None:
+ return MemoryAuthority.SDK, marker.migration_id
+ return MemoryAuthority.LEGACY, None
def cutover(self) -> CutoverMarker | None:
try:
diff --git a/memhub/apps/core/src/one_memory/sdk_migration_runner.py b/memhub/apps/core/src/one_memory/sdk_migration_runner.py
index 670bb72..cc991c3 100644
--- a/memhub/apps/core/src/one_memory/sdk_migration_runner.py
+++ b/memhub/apps/core/src/one_memory/sdk_migration_runner.py
@@ -15,9 +15,10 @@ import os
import shutil
import sqlite3
from collections.abc import Callable, Iterator
-from contextlib import contextmanager
+from contextlib import AbstractContextManager, contextmanager
from dataclasses import dataclass
from pathlib import Path
+from typing import Any
from one_memory.database_access import main_database
from one_memory.imports.models import EvidenceRecord
@@ -35,6 +36,7 @@ from one_memory.memory_server.durable_queue import (
DurableWriteQueue,
)
from one_memory.memory_server.unified_entry import UnifiedWriteIntake
+from one_memory.model_profiles import ModelProfileSnapshot
from one_memory.sdk_data_plane_migration import (
CutoverMarker,
DataPlaneMigrationError,
@@ -42,6 +44,20 @@ from one_memory.sdk_data_plane_migration import (
SdkDataPlaneMigrationStore,
)
from one_memory.sdk_migration_bundle import inspect_sdk_migration_bundle
+from one_memory.sdk_migration_verify import (
+ MemoryReadbackFailed,
+ ReadbackReport,
+ legacy_memory_ids_from,
+ legacy_memory_ids_from_bundle,
+ read_active_profile,
+ runtime_sdk_client,
+ verify_readback,
+)
+from one_memory.sdk_vector_reattach import (
+ ReattachedCollection,
+ legacy_vector_collections,
+ reattach_legacy_vectors,
+)
from one_memory.target_schema import drop_legacy_tables, legacy_tables_present
PREPARED_PHASE = "prepared"
@@ -341,6 +357,8 @@ class StartupMigrationResult:
bundle_id: str | None = None
preparation: CutoverPreparation | None = None
dropped_tables: tuple[str, ...] = ()
+ reattached: tuple[ReattachedCollection, ...] = ()
+ readback: ReadbackReport | None = None
def as_document(self) -> dict[str, object]:
document: dict[str, object] = {"schema_version": 1, "state": self.state}
@@ -349,6 +367,18 @@ class StartupMigrationResult:
document["bundle_id"] = self.bundle_id
if self.preparation is not None:
document.update(self.preparation.as_document())
+ if self.reattached:
+ document["reattached_vectors"] = [
+ {
+ "collection": item.current,
+ "legacy_count": item.legacy_count,
+ "merged_count": item.merged_count,
+ "final_count": item.final_count,
+ }
+ for item in self.reattached
+ ]
+ if self.readback is not None:
+ document["readback"] = self.readback.as_document()
if self.dropped_tables:
document["dropped_tables"] = list(self.dropped_tables)
return document
@@ -415,6 +445,15 @@ def _ensure_bundle(*, data_dir: Path, bundle_id: str, runtime_build: str) -> dic
return inspect_sdk_migration_bundle(data_dir=data_dir, bundle_id=bundle_id)
+def _vacuum(database_path: Path) -> None:
+ """Return the dropped tables' pages to the disk; a full disk only skips it."""
+ try:
+ with main_database(database_path).write(autocommit=True) as database:
+ database.execute("VACUUM")
+ except sqlite3.OperationalError:
+ return
+
+
def run_startup_migration(
*,
data_dir: Path,
@@ -422,24 +461,59 @@ def run_startup_migration(
sdk_version: str,
namespace: str,
progress: Callable[[str], None] = lambda _step: None,
+ open_client: Callable[[ModelProfileSnapshot], AbstractContextManager[Any]] | 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.
"""
database_path = data_dir / "one-memory.sqlite3"
if not database_path.is_file():
return StartupMigrationResult(state="not_required")
+
+ def client_for(profile: ModelProfileSnapshot) -> AbstractContextManager[Any]:
+ if open_client is not None:
+ return open_client(profile)
+ return runtime_sdk_client(database_path, data_dir, profile)
+
store = SdkDataPlaneMigrationStore(database_path)
- if store.authority() is MemoryAuthority.SDK:
- if not legacy_tables_present(database_path) and not abandoned_staging_present(
+ authority, authority_migration = store.authority_state()
+ profile = read_active_profile(database_path)
+ if authority is MemoryAuthority.SDK:
+ vectors_waiting = profile is not None and bool(legacy_vector_collections(data_dir, profile))
+ leftovers = bool(legacy_tables_present(database_path)) or abandoned_staging_present(
data_dir=data_dir, namespace=namespace
- ):
+ )
+ if not vectors_waiting and not leftovers:
return StartupMigrationResult(state="not_required")
- progress("cleanup")
+ reattached: tuple[ReattachedCollection, ...] = ()
+ readback: ReadbackReport | None = None
+ if vectors_waiting:
+ assert profile is not None
+ progress("vectors")
+ reattached = reattach_legacy_vectors(data_dir, profile)
+ legacy = legacy_memory_ids_from_bundle(data_dir, authority_migration)
+ if legacy is not None and not legacy.empty:
+ # Authority already moved, so nothing is left to protect by
+ # refusing; record what the repaired home reads back.
+ progress("verify")
+ with client_for(profile) as client:
+ readback = verify_readback(client, legacy)
+ dropped: tuple[str, ...] = ()
+ if leftovers:
+ progress("cleanup")
+ dropped = resume_legacy_cleanup(data_dir=data_dir, database_path=database_path)
+ if dropped:
+ _vacuum(database_path)
return StartupMigrationResult(
state="complete",
- dropped_tables=resume_legacy_cleanup(data_dir=data_dir, database_path=database_path),
+ migration_id=authority_migration,
+ bundle_id=f"{authority_migration}-pre-cutover" if authority_migration else None,
+ dropped_tables=dropped,
+ reattached=reattached,
+ readback=readback,
)
from one_memory.database_access import close_main_databases
@@ -447,6 +521,11 @@ def run_startup_migration(
from one_memory.memory_server.migrations import MIGRATIONS
migration_id, bundle_id = _resumable_identity(database_path)
+ legacy = legacy_memory_ids_from(database_path)
+ if profile is None and not legacy.empty:
+ # Without the embedding profile the Runtime's collections cannot be
+ # named, so neither reattached nor read back. Legacy stays intact.
+ raise DataPlaneMigrationError("sdk_migration_model_profile_required")
with capture_fence(data_dir):
progress("bundle")
manifest = _ensure_bundle(
@@ -472,6 +551,19 @@ def run_startup_migration(
backup_bundle_id=bundle_id,
)
preparation = prepare_legacy_work_for_cutover(database_path)
+ reattached = ()
+ readback = None
+ if profile is not None:
+ progress("vectors")
+ reattached = reattach_legacy_vectors(data_dir, profile)
+ if not legacy.empty:
+ assert profile is not None
+ progress("verify")
+ with client_for(profile) as client:
+ readback = verify_readback(client, legacy)
+ if not readback.passed:
+ store.set_phase(migration_id, phase="readback_failed", state="blocked")
+ raise MemoryReadbackFailed(readback)
store.set_phase(migration_id, phase=PREPARED_PHASE, state="ready")
progress("cutover")
commit_sdk_cutover(
@@ -483,10 +575,14 @@ def run_startup_migration(
)
progress("cleanup")
dropped = resume_legacy_cleanup(data_dir=data_dir, database_path=database_path)
+ if dropped:
+ _vacuum(database_path)
return StartupMigrationResult(
state="cutover",
migration_id=migration_id,
bundle_id=bundle_id,
preparation=preparation,
dropped_tables=dropped,
+ reattached=reattached,
+ readback=readback,
)
diff --git a/memhub/apps/core/src/one_memory/sdk_migration_verify.py b/memhub/apps/core/src/one_memory/sdk_migration_verify.py
new file mode 100644
index 0000000..529e5e8
--- /dev/null
+++ b/memhub/apps/core/src/one_memory/sdk_migration_verify.py
@@ -0,0 +1,232 @@
+"""Read legacy memory IDs back through the SDK before (and after) the cutover.
+
+The cutover is only safe if the SDK, configured exactly as the new Runtime
+will configure it, returns the memories the legacy mirror lists. Checking that
+the backup bundle is complete says nothing about it: build 20 dropped the
+legacy tables while its Runtime read an empty vector collection.
+
+Reads go through the public `HyMemoryClient` (`list_memories`, `get`).
+"""
+
+from __future__ import annotations
+
+import json
+import sqlite3
+from collections.abc import Iterator
+from contextlib import closing, contextmanager
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+from one_memory.database_access import main_database
+from one_memory.model_profiles import ModelProfileSnapshot
+from one_memory.sdk_data_plane_migration import DataPlaneMigrationError
+
+_PRODUCTIVITY_KINDS = frozenset({"coding", "working"})
+_PRODUCTIVITY_LAYERS = frozenset(
+ {"coding_experience", "working_experience", "coding_fact", "working_fact"}
+)
+_SDK_STATUSES = ("active", "superseded", "shadow", "negated", "conflicted", "archived")
+_PAGE = 500
+
+
+@dataclass(frozen=True)
+class LegacyMemoryIds:
+ chat: tuple[str, ...]
+ productivity: tuple[str, ...]
+ users: tuple[str, ...]
+
+ @property
+ def empty(self) -> bool:
+ return not self.chat and not self.productivity
+
+
+@dataclass(frozen=True)
+class ReadbackReport:
+ chat_expected: int
+ chat_readable: int
+ productivity_expected: int
+ productivity_readable: int
+
+ @property
+ def passed(self) -> bool:
+ # Every chat memory is an SDK node by construction, so all must read
+ # back. The SDK's Coding reconciler deletes experiences it retires, so
+ # a partial productivity count is normal; none at all is not.
+ return self.chat_readable == self.chat_expected and (
+ self.productivity_expected == 0 or self.productivity_readable > 0
+ )
+
+ def as_document(self) -> dict[str, object]:
+ return {
+ "chat_expected": self.chat_expected,
+ "chat_readable": self.chat_readable,
+ "productivity_expected": self.productivity_expected,
+ "productivity_readable": self.productivity_readable,
+ "passed": self.passed,
+ }
+
+
+class MemoryReadbackFailed(DataPlaneMigrationError):
+ def __init__(self, report: ReadbackReport) -> None:
+ super().__init__("sdk_migration_memory_unreadable")
+ self.report = report
+
+
+def _tables(connection: sqlite3.Connection) -> set[str]:
+ return {
+ str(row[0])
+ for row in connection.execute("SELECT name FROM sqlite_master WHERE type='table'")
+ }
+
+
+def read_legacy_memory_ids(connection: sqlite3.Connection) -> LegacyMemoryIds:
+ """Confirmed legacy memories, by the SDK id the old bridge recorded."""
+ tables = _tables(connection)
+ if "governed_memories" not in tables:
+ return LegacyMemoryIds(chat=(), productivity=(), users=())
+ mapped: dict[str, tuple[str, str | None]] = {}
+ if "memory_task_outputs" in tables:
+ for (body,) in connection.execute("SELECT body FROM memory_task_outputs"):
+ try:
+ document = json.loads(body)
+ except (TypeError, ValueError):
+ continue
+ legacy_id, sdk_id = document.get("memory_id"), document.get("hy_memory_id")
+ if isinstance(legacy_id, str) and isinstance(sdk_id, str):
+ layer = document.get("layer")
+ mapped[legacy_id] = (sdk_id, layer if isinstance(layer, str) else None)
+ chat: set[str] = set()
+ productivity: set[str] = set()
+ users: set[str] = set()
+ for memory_id, user_id, kind in connection.execute(
+ "SELECT memory_id,user_id,kind FROM governed_memories WHERE status='confirmed'"
+ ):
+ sdk_id, layer = mapped.get(str(memory_id), (str(memory_id), None))
+ users.add(str(user_id))
+ if str(kind) in _PRODUCTIVITY_KINDS or layer in _PRODUCTIVITY_LAYERS:
+ productivity.add(sdk_id)
+ else:
+ chat.add(sdk_id)
+ return LegacyMemoryIds(
+ chat=tuple(sorted(chat)),
+ productivity=tuple(sorted(productivity)),
+ users=tuple(sorted(users)),
+ )
+
+
+def legacy_memory_ids_from(database_path: Path) -> LegacyMemoryIds:
+ with main_database(database_path).read() as connection:
+ return read_legacy_memory_ids(connection)
+
+
+def legacy_memory_ids_from_bundle(
+ data_dir: Path, migration_id: str | None
+) -> LegacyMemoryIds | None:
+ """The same list from the pre-cutover bundle, for a home already migrated."""
+ if not migration_id:
+ return None
+ database = (
+ data_dir
+ / "backups"
+ / f"{migration_id}-pre-cutover.sdk-bundle"
+ / "management"
+ / "one-memory.sqlite3"
+ )
+ if not database.is_file():
+ return None
+ with closing(sqlite3.connect(f"file:{database}?mode=ro", uri=True)) as connection:
+ return read_legacy_memory_ids(connection)
+
+
+def read_active_profile(database_path: Path) -> ModelProfileSnapshot | None:
+ """The active model profile, read only; the status probe runs beside Core."""
+ with main_database(database_path).read(row_factory=sqlite3.Row) as connection:
+ if not {"model_profiles", "model_profile_versions"} <= _tables(connection):
+ return None
+ row = connection.execute(
+ "SELECT version.* FROM model_profiles profile "
+ "JOIN model_profile_versions version "
+ "ON version.profile_id=profile.profile_id AND version.revision=profile.revision "
+ "WHERE profile.is_active=1"
+ ).fetchone()
+ if row is None:
+ return None
+ return ModelProfileSnapshot(
+ profile_id=row["profile_id"],
+ revision=row["revision"],
+ provider_kind=row["provider_kind"],
+ base_url=row["base_url"],
+ model=row["model"],
+ embedding_model=row["embedding_model"],
+ embedding_provider_kind=row["embedding_provider_kind"],
+ embedding_base_url=row["embedding_base_url"],
+ embedding_dimensions=row["embedding_dimensions"],
+ timeout_seconds=row["timeout_seconds"],
+ max_concurrency=row["max_concurrency"],
+ context_window=row["context_window"],
+ has_api_key=row["secret_ref"] is not None,
+ disable_thinking=bool(row["disable_thinking"]),
+ )
+
+
+@contextmanager
+def runtime_sdk_client(
+ database_path: Path, data_dir: Path, profile: ModelProfileSnapshot
+) -> Iterator[Any]:
+ """A public SDK client configured exactly as the Runtime configures it."""
+ from one_memory.hy_sdk_runtime import acquire_client
+ from one_memory.model_profiles import ModelProfileStore
+ from one_memory.secrets import KeyringSecretStore, SecretStoreUnavailableError
+
+ try:
+ secret = ModelProfileStore(database_path).resolve_snapshot_secret(
+ profile.profile_id, profile.revision, KeyringSecretStore()
+ )
+ except SecretStoreUnavailableError:
+ raise DataPlaneMigrationError("sdk_migration_secure_storage_unavailable") from None
+ if profile.has_api_key and secret is None:
+ raise DataPlaneMigrationError("sdk_migration_model_secret_unavailable")
+ lease = acquire_client(profile, api_key=secret, data_dir=data_dir)
+ try:
+ yield lease.client
+ finally:
+ lease.close()
+
+
+def verify_readback(client: Any, legacy: LegacyMemoryIds) -> ReadbackReport:
+ listed: set[str] = set()
+ for user_id in legacy.users or ("local",):
+ offset = 0
+ while True:
+ raw = client.list_memories(
+ user_id=user_id,
+ statuses=list(_SDK_STATUSES),
+ limit=_PAGE,
+ offset=offset,
+ order="asc",
+ )
+ bucket = raw.get("vdb") if isinstance(raw, dict) else None
+ rows = bucket.get("memories") if isinstance(bucket, dict) else None
+ total = bucket.get("total") if isinstance(bucket, dict) else None
+ if not isinstance(rows, list) or not isinstance(total, int):
+ raise DataPlaneMigrationError("sdk_migration_memory_list_shape_unknown")
+ listed.update(
+ str(row["memory_id"])
+ for row in rows
+ if isinstance(row, dict) and row.get("memory_id")
+ )
+ offset += len(rows)
+ if not rows or offset >= total:
+ break
+
+ def readable(memory_id: str) -> bool:
+ return memory_id in listed or client.get(memory_id) is not None
+
+ return ReadbackReport(
+ chat_expected=len(legacy.chat),
+ chat_readable=sum(1 for memory_id in legacy.chat if readable(memory_id)),
+ productivity_expected=len(legacy.productivity),
+ productivity_readable=sum(1 for memory_id in legacy.productivity if readable(memory_id)),
+ )
+
diff --git a/memhub/apps/core/src/one_memory/sdk_vector_reattach.py b/memhub/apps/core/src/one_memory/sdk_vector_reattach.py
new file mode 100644
index 0000000..4136cb4
--- /dev/null
+++ b/memhub/apps/core/src/one_memory/sdk_vector_reattach.py
@@ -0,0 +1,149 @@
+"""Offline reattachment of SDK vector collections named by builds before #145.
+
+Those builds named a profile's embedding space `one_memory_<12 hex>`; #145
+renamed it `memhub_<16 hex>` and dropped the step that carried the old
+collections over, so every later Runtime opened an empty space beside the old
+one. Runtime code only reaches vectors through the SDK. This module runs from
+`sdk-migrate` while the Runtime is stopped, through Chroma's public client.
+"""
+
+from __future__ import annotations
+
+import sqlite3
+from collections.abc import Iterator
+from contextlib import closing
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+from one_memory.hy_sdk_runtime import vector_collection_bases
+from one_memory.model_profiles import ModelProfileSnapshot
+from one_memory.sdk_data_plane_migration import DataPlaneMigrationError
+
+_BATCH = 500
+
+
+@dataclass(frozen=True)
+class ReattachedCollection:
+ legacy: str
+ current: str
+ legacy_count: int
+ merged_count: int
+ final_count: int
+
+
+def _vector_directory(data_dir: Path) -> Path:
+ return data_dir / "hy-memory" / "governed-v2" / "vector"
+
+
+def _stored_names(data_dir: Path) -> tuple[str, ...]:
+ database = _vector_directory(data_dir) / "chroma.sqlite3"
+ if not database.is_file():
+ return ()
+ with closing(sqlite3.connect(f"file:{database}?mode=ro", uri=True)) as connection:
+ try:
+ rows = connection.execute("SELECT name FROM collections").fetchall()
+ except sqlite3.Error:
+ return ()
+ return tuple(sorted(str(row[0]) for row in rows))
+
+
+def legacy_vector_collections(
+ data_dir: Path, profile: ModelProfileSnapshot
+) -> tuple[tuple[str, str], ...]:
+ """(legacy name, current name) pairs still waiting to be reattached.
+
+ Read-only, so `sdk-migration-status` can ask it.
+ """
+ current, legacy_bases = vector_collection_bases(profile)
+ pairs: list[tuple[str, str]] = []
+ for name in _stored_names(data_dir):
+ for base in legacy_bases:
+ if name == base or name.startswith(f"{base}_"):
+ pairs.append((name, current + name[len(base) :]))
+ break
+ return tuple(pairs)
+
+
+def _records(collection: Any) -> Iterator[dict[str, Any]]:
+ offset = 0
+ while True:
+ page = collection.get(
+ include=["embeddings", "documents", "metadatas"],
+ limit=_BATCH,
+ offset=offset,
+ )
+ ids = list(page["ids"])
+ if not ids:
+ return
+ yield {
+ "ids": ids,
+ "embeddings": page["embeddings"],
+ "documents": page["documents"],
+ "metadatas": page["metadatas"],
+ }
+ offset += len(ids)
+
+
+def reattach_legacy_vectors(
+ data_dir: Path, profile: ModelProfileSnapshot
+) -> tuple[ReattachedCollection, ...]:
+ """Rename legacy collections to the current names, keeping newer writes.
+
+ A current collection that already exists (written after the rename broke)
+ is merged into the legacy one first; on an id present in both, the newer
+ current record wins. Callers must have stopped every SDK writer.
+ """
+ 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,
+ )
+ )
+ return tuple(done)
+
+
+def _ids(collection: Any) -> Iterator[str]:
+ offset = 0
+ while True:
+ ids = list(collection.get(include=[], limit=_BATCH, offset=offset)["ids"])
+ if not ids:
+ return
+ yield from ids
+ offset += len(ids)
diff --git a/memhub/apps/core/tests/test_main_database_entry.py b/memhub/apps/core/tests/test_main_database_entry.py
index 1b778b8..49b2b5d 100644
--- a/memhub/apps/core/tests/test_main_database_entry.py
+++ b/memhub/apps/core/tests/test_main_database_entry.py
@@ -91,6 +91,16 @@ ALLOWED = {
"Chroma's own chroma.sqlite3, read-only, checked before Chroma opens it",
opened_with='"?mode=ro"',
),
+ ("sdk_migration_verify.py", "legacy_memory_ids_from_bundle"): Allowed(
+ "the pre-cutover bundle's copy of the legacy database, read-only, to list "
+ "the memory ids a migrated home must still read back",
+ opened_with="?mode=ro",
+ ),
+ ("sdk_vector_reattach.py", "_stored_names"): Allowed(
+ "Chroma's own chroma.sqlite3, read-only, to list collection names before "
+ "the offline migration opens Chroma",
+ opened_with="?mode=ro",
+ ),
("imports/sqlite_access.py", "open_sqlite_readonly"): Allowed(
"a host app's own SQLite (Cursor state.vscdb / store.db): one direct "
"read-only open when there is no WAL, and one read-only open of the "
diff --git a/memhub/apps/core/tests/test_sdk_data_plane_migration.py b/memhub/apps/core/tests/test_sdk_data_plane_migration.py
index 31e0196..e0c7cad 100644
--- a/memhub/apps/core/tests/test_sdk_data_plane_migration.py
+++ b/memhub/apps/core/tests/test_sdk_data_plane_migration.py
@@ -8,11 +8,15 @@ from datetime import UTC, datetime, timedelta
from pathlib import Path
import pytest
+from httpx import ASGITransport, AsyncClient
+from pydantic import SecretStr
from one_memory import cli
+from one_memory.api import create_app
from one_memory.config import Settings
from one_memory.database_access import close_main_databases, main_database
from one_memory.hy_sdk_types import HySdkRawPage
+from one_memory.imports.storage import EvidenceStore
from one_memory.memory_server.contracts import BatchIdentity, WriteRequest
from one_memory.memory_server.durable_queue import DurableWriteQueue
from one_memory.memory_server.migration_runner import SqliteMigrationStore, migrate
@@ -35,6 +39,7 @@ from one_memory.sdk_migration_runner import (
resume_legacy_cleanup,
run_startup_migration,
)
+from one_memory.secrets import InMemorySecretStore
from one_memory.target_schema import legacy_tables_present
@@ -283,6 +288,235 @@ def test_finished_jobs_without_input_do_not_stop_the_migration(store):
prepare_legacy_write_queue_for_cutover(store.database_path)
+def _chroma(home: Path):
+ import chromadb
+ from chromadb.config import Settings as ChromaSettings
+
+ return chromadb.PersistentClient(
+ path=str(home / "hy-memory" / "governed-v2" / "vector"),
+ settings=ChromaSettings(anonymized_telemetry=False),
+ )
+
+
+def _fill(client, name: str, ids: list[str], *, text: str = "old") -> None:
+ 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"{text} {identifier}" for identifier in ids],
+ metadatas=[{"layer": "l2_fact"} for _ in ids],
+ )
+
+
+def test_legacy_vectors_are_renamed_and_newer_writes_are_kept(tmp_path) -> None:
+ """Build 20: 3317 memories in `one_memory_*`, the Runtime reading an empty `memhub_*`."""
+ from one_memory.hy_sdk_runtime import builtin_retrieval_snapshot, vector_collection_bases
+ from one_memory.sdk_vector_reattach import (
+ legacy_vector_collections,
+ reattach_legacy_vectors,
+ )
+
+ profile = builtin_retrieval_snapshot()
+ current, legacy = vector_collection_bases(profile)
+ client = _chroma(tmp_path)
+ _fill(client, f"{legacy[0]}_4", ["a", "b", "both"])
+ _fill(client, f"{legacy[0]}_coding_keys_cv_4", ["k1"])
+ _fill(client, f"{current}_4", ["new", "both"], text="newer")
+ del client
+
+ assert len(legacy_vector_collections(tmp_path, profile)) == 2
+ done = reattach_legacy_vectors(tmp_path, profile)
+
+ assert {(item.current, item.final_count) for item in done} == {
+ (f"{current}_4", 4),
+ (f"{current}_coding_keys_cv_4", 1),
+ }
+ assert legacy_vector_collections(tmp_path, profile) == ()
+ client = _chroma(tmp_path)
+ assert sorted(collection.name for collection in client.list_collections()) == [
+ f"{current}_4",
+ f"{current}_coding_keys_cv_4",
+ ]
+ chat = client.get_collection(f"{current}_4").get(ids=["both"], include=["documents"])
+ assert chat["documents"] == ["newer both"]
+ assert reattach_legacy_vectors(tmp_path, profile) == ()
+
+
+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:
+ database.execute(
+ "INSERT INTO governed_memories (memory_id,user_id,kind,status,content,"
+ "scopes_json,revision,created_at,updated_at) "
+ "VALUES (?,'local',?,'confirmed','x','[]',1,'now','now')",
+ (memory_id, kind),
+ )
+
+
+class _ReadingClient:
+ """Public-API shaped SDK client that holds only `readable` ids."""
+
+ def __init__(self, readable: set[str]) -> None:
+ self.readable = readable
+
+ def list_memories(self, *, user_id, statuses, limit, offset, order):
+ del user_id, statuses, order
+ ids = sorted(self.readable)
+ rows = [{"memory_id": memory_id} for memory_id 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 self.readable else None
+
+
+def _reading(readable: set[str]):
+ from contextlib import contextmanager
+
+ @contextmanager
+ def open_client(_profile):
+ yield _ReadingClient(readable)
+
+ return open_client
+
+
+def active_profile(monkeypatch):
+ from one_memory.hy_sdk_runtime import builtin_retrieval_snapshot
+
+ profile = builtin_retrieval_snapshot()
+ monkeypatch.setattr("one_memory.sdk_migration_runner.read_active_profile", lambda _db: profile)
+ monkeypatch.setattr("one_memory.sdk_migration_verify.read_active_profile", lambda _db: profile)
+ return profile
+
+
+def test_cutover_waits_until_the_new_runtime_reads_every_chat_memory(store, active_profile):
+ """Build 20 reported success on 37 of 3317. Now the legacy tables stay."""
+ from one_memory.sdk_migration_verify import MemoryReadbackFailed
+
+ _confirmed(store, "m1", "m2", "m3")
+ home = store.database_path.parent
+
+ with pytest.raises(MemoryReadbackFailed) as caught:
+ run_startup_migration(
+ data_dir=home,
+ runtime_build="21",
+ sdk_version="2.0.5",
+ namespace="governed-v2",
+ open_client=_reading({"m1"}),
+ )
+
+ assert caught.value.code == "sdk_migration_memory_unreadable"
+ assert caught.value.report.as_document() == {
+ "chat_expected": 3,
+ "chat_readable": 1,
+ "productivity_expected": 0,
+ "productivity_readable": 0,
+ "passed": False,
+ }
+ assert store.authority() is MemoryAuthority.LEGACY
+ assert "governed_memories" in legacy_tables_present(store.database_path)
+
+ result = run_startup_migration(
+ data_dir=home,
+ runtime_build="21",
+ sdk_version="2.0.5",
+ namespace="governed-v2",
+ open_client=_reading({"m1", "m2", "m3"}),
+ )
+
+ assert result.state == "cutover"
+ assert result.readback is not None and result.readback.passed
+ assert store.authority() is MemoryAuthority.SDK
+
+
+def test_retired_coding_experiences_do_not_block_but_an_empty_store_does(store, active_profile):
+ _confirmed(store, "chat-1")
+ _confirmed(store, "exp-kept", "exp-retired", kind="coding")
+ home = store.database_path.parent
+ from one_memory.sdk_migration_verify import MemoryReadbackFailed
+
+ with pytest.raises(MemoryReadbackFailed):
+ run_startup_migration(
+ data_dir=home,
+ runtime_build="21",
+ sdk_version="2.0.5",
+ namespace="governed-v2",
+ open_client=_reading({"chat-1"}),
+ )
+ result = run_startup_migration(
+ data_dir=home,
+ runtime_build="21",
+ sdk_version="2.0.5",
+ namespace="governed-v2",
+ open_client=_reading({"chat-1", "exp-kept"}),
+ )
+ assert result.readback is not None
+ assert (result.readback.productivity_expected, result.readback.productivity_readable) == (2, 1)
+
+
+def test_memories_without_a_model_profile_keep_legacy_authority(store, monkeypatch):
+ monkeypatch.setattr("one_memory.sdk_migration_runner.read_active_profile", lambda _db: None)
+ _confirmed(store, "m1")
+
+ with pytest.raises(DataPlaneMigrationError, match="sdk_migration_model_profile_required"):
+ run_startup_migration(
+ data_dir=store.database_path.parent,
+ runtime_build="21",
+ sdk_version="2.0.5",
+ namespace="governed-v2",
+ )
+ assert store.authority() is MemoryAuthority.LEGACY
+
+
+def test_a_build_20_home_gets_its_vectors_back_and_is_checked_against_its_backup(
+ store, active_profile, monkeypatch
+):
+ from one_memory.hy_sdk_runtime import vector_collection_bases
+
+ home = store.database_path.parent
+ current, legacy_bases = vector_collection_bases(active_profile)
+ client = _chroma(home)
+ _fill(client, f"{legacy_bases[0]}_512", ["m1", "m2"])
+ _fill(client, f"{current}_512", ["after-upgrade"], text="newer")
+ del client
+ _confirmed(store, "m1", "m2")
+ first = run_startup_migration(
+ data_dir=home,
+ runtime_build="20",
+ sdk_version="2.0.5",
+ namespace="governed-v2",
+ open_client=_reading({"m1", "m2"}),
+ )
+ assert first.state == "cutover"
+ # Reproduce build 20: cut over while the legacy collection stayed stranded.
+ client = _chroma(home)
+ client.get_collection(f"{current}_512").modify(name=f"{legacy_bases[0]}_512")
+ _fill(client, f"{current}_512", ["after-upgrade"], text="newer")
+ del client
+ 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"
+
+ repaired = run_startup_migration(
+ data_dir=home,
+ runtime_build="21",
+ sdk_version="2.0.5",
+ namespace="governed-v2",
+ open_client=_reading({"m1", "m2", "after-upgrade"}),
+ )
+
+ assert repaired.state == "complete"
+ assert [(item.current, item.final_count) for item in repaired.reattached] == [
+ (f"{current}_512", 3)
+ ]
+ assert repaired.readback is not None and repaired.readback.passed
+ assert repaired.readback.chat_expected == 2
+ status = io.StringIO()
+ assert cli.run(["sdk-migration-status", "--json"], output=status) == 0
+ assert json.loads(status.getvalue())["state"] == "not_required"
+
+
def test_pending_dispatch_becomes_one_write_job_per_conversation(store):
_insert_evidence(store, "a1", conversation="a", seq=1)
_insert_evidence(store, "a2", conversation="a", role="assistant", seq=2)
@@ -560,3 +794,75 @@ def test_sdk_raw_retention_keeps_only_the_latest_three_days():
)
assert asyncio.run(runtime.prune_expired_raw(now=now)) == 1
assert [row["memory_id"] for row in client.rows] == ["recent"]
+
+
+# The UI asks which memory data plane is authoritative and must get the
+# answer the API gates use.
+
+
+def _app_settings(tmp_path) -> Settings:
+ return Settings(
+ _env_file=None,
+ data_dir=tmp_path / "data",
+ source_home=tmp_path,
+ api_token=SecretStr("authority-test"),
+ imports_enabled=False,
+ automatic_memory_processing=False,
+ live_sync_enabled=False,
+ )
+
+
+async def _authority(tmp_path) -> tuple[dict[str, object], str]:
+ app = create_app(_app_settings(tmp_path), secret_store=InMemorySecretStore())
+ async with (
+ app.router.lifespan_context(app),
+ AsyncClient(
+ transport=ASGITransport(app=app),
+ base_url="http://test",
+ headers={"Authorization": "Bearer authority-test"},
+ ) as client,
+ ):
+ response = await client.get("/api/v2/memory-authority")
+ assert response.status_code == 200
+ return response.json(), app.state.memory_authority.value
+
+
+def test_a_fresh_home_reports_sdk_authority(tmp_path) -> None:
+ document, gate = asyncio.run(_authority(tmp_path))
+
+ assert document == {"authority": "sdk", "migration_id": None}
+ assert gate == "sdk"
+
+
+def test_a_migrated_home_still_reports_sdk_after_its_receipt_is_dropped(
+ tmp_path, monkeypatch
+) -> None:
+ """Build 20: the cleanup dropped the cutover receipt, the UI fell back to legacy."""
+ data_dir = tmp_path / "data"
+ EvidenceStore(data_dir / "one-memory.sqlite3")
+ monkeypatch.setattr(cli, "load_settings", lambda: _app_settings(tmp_path))
+ monkeypatch.setattr(
+ cli,
+ "inspect_runtime",
+ lambda _data_dir: RuntimeStatus("stopped", "runtime_receipt_missing"),
+ )
+ output = io.StringIO()
+ assert cli.run(["sdk-migrate", "--runtime-build", "21", "--yes", "--json"], output=output) == 0
+ migration_id = json.loads(output.getvalue().splitlines()[-1])["migration_id"]
+ assert legacy_tables_present(data_dir / "one-memory.sqlite3") == ()
+
+ document, gate = asyncio.run(_authority(tmp_path))
+
+ assert document == {"authority": "sdk", "migration_id": migration_id}
+ assert gate == "sdk"
+
+
+def test_a_legacy_home_reports_legacy_authority(tmp_path) -> None:
+ document, gate = asyncio.run(_authority(tmp_path))
+
+ assert document == {"authority": "legacy", "migration_id": None}
+ assert gate == "legacy"
diff --git a/memhub/apps/desktop/src/stable-runtime.test.ts b/memhub/apps/desktop/src/stable-runtime.test.ts
index 79f8dd0..ad6fbc6 100644
--- a/memhub/apps/desktop/src/stable-runtime.test.ts
+++ b/memhub/apps/desktop/src/stable-runtime.test.ts
@@ -285,6 +285,12 @@ describe("startup install errors", () => {
expect(noSpace).toContain("重新启动");
expect(noSpace).toContain("不会丢失");
expect(noSpace).not.toContain("sdk_migration_disk_space_insufficient");
+
+ const unreadable = stableRuntimeUserMessage(
+ new Error("sdk_migration_memory_unreadable"),
+ );
+ expect(unreadable).toContain("没有切换数据源");
+ expect(unreadable).toContain("不会丢失");
});
});
diff --git a/memhub/apps/desktop/src/stable-runtime.ts b/memhub/apps/desktop/src/stable-runtime.ts
index af919f7..7794f97 100644
--- a/memhub/apps/desktop/src/stable-runtime.ts
+++ b/memhub/apps/desktop/src/stable-runtime.ts
@@ -130,6 +130,10 @@ const SAFE_STABLE_RUNTIME_ERROR_CODES = new Set([
// a first launch can be given. They stay codes here and become sentences in
// STABLE_RUNTIME_USER_MESSAGES: a person reading the dialog never sees them.
"sdk_migration_preflight_failed",
+ "sdk_migration_memory_unreadable",
+ "sdk_migration_model_profile_required",
+ "sdk_migration_model_secret_unavailable",
+ "sdk_migration_secure_storage_unavailable",
"sdk_migration_disk_space_insufficient",
"sdk_migration_cutover_failed",
"sdk_migration_bundle_copy_failed",
@@ -201,6 +205,14 @@ export const STABLE_RUNTIME_USER_MESSAGES: Record<string, string> = {
"已安装的运行环境比这个安装包更新,无法用旧安装包启动。请安装最新版本的 MemHub;你的记忆数据不会受到影响。",
install_current_unmanaged:
"运行环境的安装目录被改动过,无法安全接管。请重新安装 MemHub,你的记忆数据不会受到影响。",
+ sdk_migration_memory_unreadable:
+ "升级前核对发现,新版本还读不到你的全部记忆,所以没有切换数据源,旧数据保持原样可用。请把这个提示反馈给我们;原有记忆数据不会丢失。",
+ sdk_migration_model_profile_required:
+ "升级记忆数据格式需要先有可用的模型配置,用来核对新版本能否读回你的记忆。请在旧版本中完成模型配置后重启;你的记忆数据不会受到影响。",
+ sdk_migration_model_secret_unavailable:
+ "模型密钥读不到(可能被系统钥匙串拒绝),无法核对新版本能否读回你的记忆。请允许 MemHub 访问钥匙串后重新启动;你的记忆数据不会受到影响。",
+ sdk_migration_secure_storage_unavailable:
+ "系统钥匙串暂时不可用,无法核对新版本能否读回你的记忆。请解锁钥匙串后重新启动;你的记忆数据不会受到影响。",
sdk_migration_disk_space_insufficient:
"磁盘空间不足,升级记忆数据格式时中断了。请至少腾出与记忆数据同等大小的可用空间(可在「关于本机 → 储存空间」查看),然后重新启动 MemHub;升级会自动继续,原有记忆数据不会丢失。",
sdk_migration_bundle_copy_failed:
diff --git a/memhub/docs/ARCHITECTURE.md b/memhub/docs/ARCHITECTURE.md
index a8d03e8..9b6637a 100644
--- a/memhub/docs/ARCHITECTURE.md
+++ b/memhub/docs/ARCHITECTURE.md
@@ -135,7 +135,7 @@ This exception does not extend to VDB, Coding, prompt, reconcile, or lifecycle.
- 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。
- Matter:未形成已发布产品合同,不迁移占位数据;所有 `matter*` 表在升级清理时物理删除,fresh install 不创建,Runtime 不注册 Matter API。
-- 旧用户迁移:由 App 在可见的启动 loading 阶段统一执行;此时 Core 尚未对外提供产品读写。所有已发布版本都先经 SDK 写入,Governance/Evidence 只是镜像,所以迁移**不复制、不比对任何 memory 或 raw**:只创建并校验完整 bundle、让写入队列脱离旧表、提交 marker、删除旧表。由一个 Core 命令 `sdk-migrate` 完成;Desktop 启动与 CLI `memhub install`/`upgrade`(macOS、Linux)在启动新 Runtime 前调用它,普通用户不需要另跑命令。App 不得在 migration `deferred` 状态继续启动 Runtime。
+- 旧用户迁移:由 App 在可见的启动 loading 阶段统一执行;此时 Core 尚未对外提供产品读写。所有已发布版本都先经 SDK 写入,Governance/Evidence 只是镜像,所以迁移**不复制任何 memory 或 raw**:创建并校验完整 bundle、让写入队列脱离旧表、把旧版命名的 SDK 向量集合接回当前名字、用 Runtime 同样配置的公开 SDK client 按 ID 回读核对,通过后才提交 marker、删除旧表。由一个 Core 命令 `sdk-migrate` 完成;Desktop 启动与 CLI `memhub install`/`upgrade`(macOS、Linux)在启动新 Runtime 前调用它,普通用户不需要另跑命令。App 不得在 migration `deferred` 状态继续启动 Runtime。
- 迁移期间宿主 capture hook 由 Desktop 活跃 PID marker 静默挡住,不再追加
Evidence;cutover 后先从宿主 History checkpoint 补齐遗漏 turn,再恢复 live sync。
- Matter 若未来重新开发,需以新的 SDK-native 合同重新设计,不继承当前占位 schema。
diff --git a/memhub/docs/contracts/sdk-data-plane-migration-v1.md b/memhub/docs/contracts/sdk-data-plane-migration-v1.md
index 445345f..03e7ac9 100644
--- a/memhub/docs/contracts/sdk-data-plane-migration-v1.md
+++ b/memhub/docs/contracts/sdk-data-plane-migration-v1.md
@@ -1,6 +1,6 @@
# SDK Data Plane Migration v1
-Updated: 2026-10-24.
+Updated: 2026-10-24 (vector reattach, readback).
This contract moves released MemHub installations from the historical
Evidence/Governance authority to the Hy Memory SDK data plane defined by
@@ -29,6 +29,14 @@ and no raw turn, and does not compare the mirror with the SDK:
- SDK L1 raw is retained for three days by the Runtime's own
`prune_expired_raw`, not by the migration.
+"Already complete" holds only if the new Runtime opens the same stores. Builds
+before #145 named a profile's vector collections `one_memory_<12 hex>…`; #145
+renamed them `memhub_<16 hex>…` without carrying the old ones over, so later
+Runtimes read an empty collection (build 20 cut over showing 37 of 3317
+memories). The migration therefore reattaches those collections (§3, step 3)
+and proves the new Runtime reads the memories back before it cuts over
+(step 4).
+
## 2. Authority before and after cutover
Before the cutover marker is committed, legacy tables remain the product read
@@ -68,9 +76,32 @@ then:
restore; an existing verified bundle of the same run is reused;
2. **prepare**: applies the management schema migrations, discards SDK staging
left by builds through 19 (§5) and makes legacy queue work self-contained
- (§4); it needs no model profile and no SDK client;
-3. **cutover**: re-verifies the bundle, repeats §4, commits SDK authority;
-4. **cleanup**: drops the legacy tables (including the `evidence_search` index).
+ (§4);
+3. **vectors**: for the active embedding profile, renames every
+ `one_memory_<old hash>…` collection to the current `memhub_<hash>…` name
+ through Chroma's public client. A current collection that already holds
+ writes is merged in first (newer record wins on a shared id); counts are
+ checked after each step;
+4. **verify**: opens the public SDK client exactly as the Runtime will and reads
+ the legacy confirmed memory ids back (`list_memories`, then `get`). Every
+ chat memory must read back. Coding/Working may be fewer, because the SDK's
+ Coding reconciler deletes experiences it retires, but not zero when the
+ legacy mirror has some. Otherwise the run stops with
+ `sdk_migration_memory_unreadable` and the counts, before anything
+ irreversible; legacy authority and tables stay intact;
+5. **cutover**: re-verifies the bundle, repeats §4, commits SDK authority;
+6. **cleanup**: drops the legacy tables (including the `evidence_search`
+ index) and runs `VACUUM` (skipped if the disk is too full).
+
+A home with legacy memories but no active model profile is not migrated
+(`sdk_migration_model_profile_required`): its collections can be neither named
+nor read back.
+
+A home already on SDK authority still reports `required` while legacy-named
+vector collections exist for its profile (build 20 homes). `sdk-migrate` then
+reattaches them and reads back against the memory ids in the pre-cutover
+bundle; that report is recorded but does not block, as nothing irreversible is
+left. Runtime code never renames or reads Chroma directly.
With `--json` each step prints `{"state":"running","step":…}` and the last line
is the result: `cutover`, `complete` (only cleanup was left), `not_required`, or
@@ -148,6 +179,12 @@ The release gate covers:
- CLI upgrade migrating before restart, rolling back on a failed migration,
and keeping the new version when a migrated home is slow to come up;
- host capture fenced for the whole command;
+- legacy-named vector collections reattached (with merge) before verifying,
+ and on a home that already cut over;
+- readback refusing a cutover the new Runtime cannot read, and tolerating
+ retired Coding experiences;
+- `/api/v2/memory-authority` agreeing with the API gates on fresh, migrated
+ and legacy homes;
- pending job freezing, legacy task and pending dispatch conversion;
- invoked/unknown legacy tasks and pending deletions not blocking cutover;
- interrupted directory swap recovery before and after authority;