Skip to content
Python

fix(memhub): reads use the active profile's embedding space

alvinfei80d3b557231f
diff --git a/memhub/apps/core/src/one_memory/api.py b/memhub/apps/core/src/one_memory/api.py
index cb516f7..da2b7d9 100644
--- a/memhub/apps/core/src/one_memory/api.py
+++ b/memhub/apps/core/src/one_memory/api.py
@@ -94,7 +94,6 @@ from one_memory.hy_runtime_config import (
from one_memory.hy_sdk_runtime import (
AmbiguousMemoryIdError,
SdkClientHandle,
- builtin_retrieval_snapshot,
close_all_shared_runtimes,
hold_stores_offline,
release_stores,
@@ -229,6 +228,7 @@ from one_memory.sdk_memory_qa import (
)
from one_memory.sdk_memory_runtime import SdkMemoryRuntime
from one_memory.sdk_migration_log import error_chain_text, error_frames
+from one_memory.sdk_read_handle import ActiveProfileReadHandle
from one_memory.sdk_write_processor import SdkWriteCoordinator
from one_memory.secrets import (
KeyringSecretStore,
@@ -4880,9 +4880,11 @@ async def _search_sdk_raw(
def _sdk_client_handle(app: FastAPI) -> SdkClientHandle:
handle = cast(SdkClientHandle | None, app.state.sdk_client_handle)
if handle is None:
- handle = SdkClientHandle(
- profile=builtin_retrieval_snapshot(),
- api_key=None,
+ # Reads open the embedding space writes fill: the active profile's,
+ # the built-in one only when none is active (#242).
+ handle = ActiveProfileReadHandle(
+ profiles=_model_profile_store(app),
+ secrets=_secret_store(app),
data_dir=cast(Settings, app.state.settings).data_dir,
)
app.state.sdk_client_handle = handle
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 3b4f626..0acedcf 100644
--- a/memhub/apps/core/src/one_memory/hy_sdk_runtime.py
+++ b/memhub/apps/core/src/one_memory/hy_sdk_runtime.py
@@ -217,6 +217,33 @@ def builtin_retrieval_snapshot() -> ModelProfileSnapshot:
)
+def retrieval_view(profile: ModelProfileSnapshot) -> ModelProfileSnapshot:
+ """The read side of `profile`: its embedding space, and no generation.
+
+ Reads must open the collection writes fill (#242), and the collection is
+ named by the embedding only. Generation stays the built-in placeholder, so
+ a read never needs the generation model. A remote embedding still needs
+ the profile's API key, which `build_sdk_config` uses as the embedding key.
+ """
+ provider = profile.embedding_provider_kind or profile.provider_kind
+ endpoint: str | None = None
+ if provider is not ProviderKind.LOCAL_ONNX:
+ endpoint = profile.embedding_base_url or profile.base_url
+ if not endpoint:
+ raise HySdkRuntimeError("hy_sdk_model_endpoint_missing")
+ return builtin_retrieval_snapshot().model_copy(
+ update={
+ "profile_id": profile.profile_id,
+ "revision": profile.revision,
+ "embedding_provider_kind": provider,
+ "embedding_model": profile.embedding_model,
+ "embedding_base_url": endpoint,
+ "embedding_dimensions": profile.embedding_dimensions,
+ "has_api_key": profile.has_api_key,
+ }
+ )
+
+
def sdk_relevance_floor() -> float:
raw = os.environ.get("ONE_MEMORY_HY_RELEVANCE_FLOOR", "").strip()
if not raw:
diff --git a/memhub/apps/core/src/one_memory/sdk_memory_runtime.py b/memhub/apps/core/src/one_memory/sdk_memory_runtime.py
index 1fe42b9..8b5ee32 100644
--- a/memhub/apps/core/src/one_memory/sdk_memory_runtime.py
+++ b/memhub/apps/core/src/one_memory/sdk_memory_runtime.py
@@ -122,7 +122,9 @@ class SdkMemoryRuntime:
while True:
await asyncio.sleep(RAW_RETENTION_CHECK_SECONDS)
try:
- removed = await self.prune_expired_raw()
+ # Its own task, so this pass's use of the read client ends
+ # with it instead of with this loop (see `sdk_read_handle`).
+ removed = await asyncio.create_task(self.prune_expired_raw())
if removed:
logger.info("sdk_raw_retention_deleted count=%d", removed)
except asyncio.CancelledError:
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 55eda1e..3d069aa 100644
--- a/memhub/apps/core/src/one_memory/sdk_migration_runner.py
+++ b/memhub/apps/core/src/one_memory/sdk_migration_runner.py
@@ -777,9 +777,7 @@ def run_startup_migration(
step["chat"] = len(legacy.chat)
step["productivity"] = len(legacy.productivity)
step["users"] = len(legacy.users)
- if active is None and not legacy.empty and vectors_belong_to_another_space(
- data_dir, profile
- ):
+ if active is None and not legacy.empty and vectors_belong_to_another_space(data_dir, profile):
# The memories live in the space of a profile that is no longer active,
# so the built-in model cannot read them. Legacy stays intact.
log.check("preflight.vector_space_check", "sdk_migration_vector_profile_missing")
diff --git a/memhub/apps/core/src/one_memory/sdk_read_handle.py b/memhub/apps/core/src/one_memory/sdk_read_handle.py
new file mode 100644
index 0000000..29cade6
--- /dev/null
+++ b/memhub/apps/core/src/one_memory/sdk_read_handle.py
@@ -0,0 +1,114 @@
+"""The read client, kept in the embedding space the active profile writes to.
+
+Every read used to open the built-in 512-dim collection while writes followed
+the active profile, so a custom embedding read an empty space (#242). This
+handle opens the active profile's `retrieval_view` instead, and the built-in
+space only when no profile is active.
+
+A profile change builds a new client and retires the old one; a retired client
+is closed once no task still uses it, as `SdkWriteCoordinator` does for writes
+(#218). A use is the task that asked for the client: callers keep their
+`client = await handle.client()` shape, and the use ends with that task (one
+HTTP request, one retention pass).
+"""
+
+from __future__ import annotations
+
+import asyncio
+from pathlib import Path
+from typing import Any
+
+from one_memory.hy_sdk_runtime import (
+ BUILTIN_RETRIEVAL_PROFILE_ID,
+ SdkClientHandle,
+ builtin_retrieval_snapshot,
+ retrieval_view,
+)
+from one_memory.hy_sdk_types import HySdkRuntimeError
+from one_memory.model_profiles import ModelProfileStore, ProviderKind
+from one_memory.secrets import SecretStore, SecretStoreUnavailableError
+
+_BUILTIN = (BUILTIN_RETRIEVAL_PROFILE_ID, 0)
+
+
+class ActiveProfileReadHandle(SdkClientHandle):
+ """An `SdkClientHandle` whose profile follows the active one."""
+
+ def __init__(
+ self,
+ *,
+ profiles: ModelProfileStore,
+ secrets: SecretStore,
+ data_dir: Path,
+ ) -> None:
+ super().__init__(builtin_retrieval_snapshot(), api_key=None, data_dir=data_dir)
+ self.profiles = profiles
+ self.secrets = secrets
+ self.data_dir = data_dir
+ self._handles: dict[tuple[str, int], SdkClientHandle] = {}
+ #: Tasks in flight per handle; a retired handle closes at zero.
+ self._uses: dict[SdkClientHandle, int] = {}
+ self._retired: set[SdkClientHandle] = set()
+ self._closing: set[asyncio.Task[None]] = set()
+ self._handle_lock = asyncio.Lock()
+
+ async def client(self) -> Any:
+ identity = await asyncio.to_thread(self.profiles.active_identity) or _BUILTIN
+ async with self._handle_lock:
+ handle = self._handles.get(identity)
+ if handle is None:
+ # Only on a change of profile: resolving a key can reach the
+ # system keychain, so it is not done on every read.
+ handle = await asyncio.to_thread(self._build, identity)
+ self._handles[identity] = handle
+ self._retired.update(value for key, value in self._handles.items() if key != identity)
+ self._handles = {identity: handle}
+ unused = {value for value in self._retired if not self._uses.get(value)}
+ self._retired -= unused
+ self._hold(handle)
+ await asyncio.gather(*(value.close() for value in unused))
+ return await handle.client()
+
+ async def close(self) -> None:
+ async with self._handle_lock:
+ handles = (*self._handles.values(), *self._retired)
+ self._handles, self._retired, self._uses = {}, set(), {}
+ await asyncio.gather(*(handle.close() for handle in handles), *self._closing)
+
+ def _hold(self, handle: SdkClientHandle) -> None:
+ """Count a use of `handle` until the asking task finishes."""
+ task = asyncio.current_task()
+ if task is None: # pragma: no cover - always called from a coroutine
+ return
+ self._uses[handle] = self._uses.get(handle, 0) + 1
+ task.add_done_callback(lambda _task: self._release(handle))
+
+ def _release(self, handle: SdkClientHandle) -> None:
+ remaining = self._uses.get(handle, 0) - 1
+ if remaining > 0:
+ self._uses[handle] = remaining
+ return
+ self._uses.pop(handle, None)
+ if handle in self._retired:
+ self._retired.discard(handle)
+ closing = asyncio.get_running_loop().create_task(handle.close())
+ self._closing.add(closing)
+ closing.add_done_callback(self._closing.discard)
+
+ def _build(self, identity: tuple[str, int]) -> SdkClientHandle:
+ if identity == _BUILTIN:
+ return SdkClientHandle(
+ builtin_retrieval_snapshot(), api_key=None, data_dir=self.data_dir
+ )
+ profile = self.profiles.snapshot(*identity)
+ view = retrieval_view(profile)
+ secret: str | None = None
+ # Only a remote OpenAI-compatible embedding sends the shared key.
+ if view.embedding_provider_kind is ProviderKind.OPENAI_COMPATIBLE:
+ try:
+ secret = self.profiles.resolve_snapshot_secret(*identity, self.secrets)
+ except SecretStoreUnavailableError:
+ raise HySdkRuntimeError("secure_storage_unavailable") from None
+ if secret is None:
+ raise HySdkRuntimeError("model_secret_unavailable")
+ return SdkClientHandle(view, api_key=secret, data_dir=self.data_dir)
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 c722980..89de51e 100644
--- a/memhub/apps/core/tests/test_sdk_data_plane_migration.py
+++ b/memhub/apps/core/tests/test_sdk_data_plane_migration.py
@@ -888,9 +888,7 @@ def test_vectors_left_by_a_deleted_profile_stop_the_upgrade_by_name(store, monke
assert not (home / "backups").exists()
-def test_confirmed_chats_the_sdk_had_already_merged_do_not_fail_the_upgrade(
- store, active_profile
-):
+def test_confirmed_chats_the_sdk_had_already_merged_do_not_fail_the_upgrade(store, active_profile):
"""#229/#240: 658 confirmed chats, 657 in the store, and the upgrade failed.
A 1.0.4 library can hold confirmed rows whose SDK node had been merged or
diff --git a/memhub/apps/core/tests/test_search_without_profile.py b/memhub/apps/core/tests/test_search_without_profile.py
index a7f6f7a..864316a 100644
--- a/memhub/apps/core/tests/test_search_without_profile.py
+++ b/memhub/apps/core/tests/test_search_without_profile.py
@@ -1,5 +1,6 @@
"""Model-free SDK search remains available without an active write profile."""
+import asyncio
from pathlib import Path
from types import SimpleNamespace
@@ -95,3 +96,158 @@ async def test_search_without_profile_uses_public_sdk_search() -> None:
assert options["user_ids"] == ["local"]
assert options["agent_ids"] == []
assert options["scene"] == "normal"
+
+
+def _activate(profiles, secrets, *, dimensions: int, model: str = "chat"):
+ from pydantic import SecretStr
+
+ from one_memory.model_profiles import ModelCapabilities, ModelProfileInput
+
+ profile = profiles.create(
+ ModelProfileInput(
+ name=f"embedding-{dimensions}",
+ provider_kind=ProviderKind.OPENAI_COMPATIBLE,
+ base_url="https://models.example/v1",
+ model=model,
+ embedding_provider_kind=ProviderKind.OPENAI_COMPATIBLE,
+ embedding_base_url="https://models.example/v1",
+ embedding_model="qwen3-embedding-4b",
+ embedding_dimensions=dimensions,
+ api_key=SecretStr("sk-test"),
+ ),
+ secrets,
+ )
+ profiles.record_capabilities(
+ profile.profile_id,
+ expected_revision=profile.revision,
+ capabilities=ModelCapabilities(
+ endpoint_reachable=True,
+ model_available=True,
+ structured_output=True,
+ embedding_available=True,
+ ),
+ secrets=secrets,
+ )
+ profiles.activate(profile.profile_id, secrets)
+ return profiles.snapshot(profile.profile_id, profiles.active_identity()[1])
+
+
+class _Recorder:
+ """Stands in for `acquire_client`: records the collection each client opens."""
+
+ def __init__(self, data_dir: Path) -> None:
+ self.data_dir = data_dir
+ self.opened: list[tuple[str, int | None, str | None]] = []
+ self.closed: list[str] = []
+
+ def __call__(self, profile, *, api_key, data_dir, http_transport_factory=None):
+ from one_memory.hy_sdk_runtime import build_sdk_config
+
+ config = build_sdk_config(profile, api_key=api_key, data_dir=data_dir)
+ name = config.vector_store.collection_name
+ self.opened.append((name, config.vector_store.embedding_dims, api_key))
+ return SimpleNamespace(
+ client=SimpleNamespace(collection=name),
+ close=lambda: self.closed.append(name),
+ )
+
+
+async def test_reads_open_the_collection_the_active_profile_writes(
+ tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+ """#242: a 2560-dim profile wrote `memhub_<sha>_2560`, reads opened `_512`."""
+ from one_memory.hy_sdk_runtime import build_sdk_config
+ from one_memory.model_profiles import ModelProfileStore
+ from one_memory.sdk_read_handle import ActiveProfileReadHandle
+ from one_memory.secrets import InMemorySecretStore
+
+ recorder = _Recorder(tmp_path)
+ monkeypatch.setattr("one_memory.hy_sdk_runtime.acquire_client", recorder)
+ profiles = ModelProfileStore(tmp_path / "one-memory.sqlite3")
+ secrets = InMemorySecretStore()
+ handle = ActiveProfileReadHandle(profiles=profiles, secrets=secrets, data_dir=tmp_path)
+
+ builtin = build_sdk_config(builtin_retrieval_snapshot(), api_key=None, data_dir=tmp_path)
+ assert (await handle.client()).collection == builtin.vector_store.collection_name
+
+ written = _activate(profiles, secrets, dimensions=2560)
+ writes = build_sdk_config(written, api_key="sk-test", data_dir=tmp_path)
+
+ async def read() -> str:
+ return str((await handle.client()).collection)
+
+ assert await asyncio.create_task(read()) == writes.vector_store.collection_name
+ assert recorder.opened[-1] == (writes.vector_store.collection_name, 2560, "sk-test")
+ assert writes.vector_store.collection_name != builtin.vector_store.collection_name
+ await handle.close()
+
+
+async def test_a_profile_change_rebuilds_reads_without_closing_one_in_flight(
+ tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+ from one_memory.model_profiles import ModelProfileStore
+ from one_memory.sdk_read_handle import ActiveProfileReadHandle
+ from one_memory.secrets import InMemorySecretStore
+
+ recorder = _Recorder(tmp_path)
+ monkeypatch.setattr("one_memory.hy_sdk_runtime.acquire_client", recorder)
+ profiles = ModelProfileStore(tmp_path / "one-memory.sqlite3")
+ secrets = InMemorySecretStore()
+ handle = ActiveProfileReadHandle(profiles=profiles, secrets=secrets, data_dir=tmp_path)
+ _activate(profiles, secrets, dimensions=1024)
+
+ holding = asyncio.Event()
+ finish = asyncio.Event()
+
+ async def slow_read() -> str:
+ client = await handle.client()
+ holding.set()
+ await finish.wait()
+ return str(client.collection)
+
+ in_flight = asyncio.create_task(slow_read())
+ await holding.wait()
+ [(old, _, _)] = recorder.opened
+
+ _activate(profiles, secrets, dimensions=2560, model="chat-2")
+
+ async def read() -> str:
+ return str((await handle.client()).collection)
+
+ new = await asyncio.create_task(read())
+ assert new != old
+ # The read that started on the old space still has its client.
+ assert recorder.closed == []
+
+ finish.set()
+ assert await in_flight == old
+ for _ in range(5):
+ await asyncio.sleep(0)
+ assert recorder.closed == [old]
+ await handle.close()
+ assert recorder.closed == [old, new]
+
+
+def test_every_api_read_shares_the_active_profile_handle(tmp_path: Path) -> None:
+ """Library, search, recall, graph, profile, raw, ask and context all read
+ through `_sdk_client_handle`, so it must be the active-profile handle."""
+ from one_memory.api import _sdk_client_handle
+ from one_memory.config import Settings
+ from one_memory.model_profiles import ModelProfileStore
+ from one_memory.sdk_read_handle import ActiveProfileReadHandle
+ from one_memory.secrets import InMemorySecretStore
+
+ state = SimpleNamespace(
+ sdk_client_handle=None,
+ model_profile_store=ModelProfileStore(tmp_path / "one-memory.sqlite3"),
+ secret_store=InMemorySecretStore(),
+ settings=Settings(_env_file=None, data_dir=tmp_path),
+ )
+ app = SimpleNamespace(state=state)
+
+ handle = _sdk_client_handle(app) # type: ignore[arg-type]
+
+ assert isinstance(handle, ActiveProfileReadHandle)
+ assert _sdk_client_handle(app) is handle is state.sdk_client_handle # type: ignore[arg-type]