Skip to content
Python

refactor(memhub): remove private Hy Memory bridge (#145)

feitianxiangd92684417336
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 768542f..017f804 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -40,6 +40,14 @@ Hy Memory and MemHub are versioned and released independently.
## Unreleased
+- Removed MemHub's private `hy_memory_bridge` implementation. MemHub now calls
+ public `HyMemoryClient` methods through explicit runtime, write, migration,
+ and read modules; prompt/reconcile/response monkey-patches and private
+ VDB/Coding access were deleted. Kuzu Graph projection/admin remains the one
+ documented product exception.
+- Extended public SDK `get()` to resolve Chat, Coding Experience, and Working
+ Fact IDs, including owner/session fields and explicit ambiguity handling;
+ added constructor-time public embedding-service injection.
- Added a MemHub-managed native Hermes MemoryProvider with automatic prefetch,
persistent per-session memory-ID deduplication, authorized Broker reads, and
recall-context stripping to prevent memory recursion.
diff --git a/hy_memory/__init__.py b/hy_memory/__init__.py
index e8944a7..e0a1f3a 100644
--- a/hy_memory/__init__.py
+++ b/hy_memory/__init__.py
@@ -65,6 +65,12 @@ from .snapshot import (
# ====== 配置 ======
from .config import MemoryConfig
+from .embedding import (
+ EmbeddingDimensionMismatchError,
+ EmbeddingService,
+ EmbeddingServiceProtocol,
+)
+from .retrieval import AmbiguousMemoryIdError, MemoryKind, MemoryVariant
# ====== Embedding 端点覆盖(per-call,不改 model/dims,只换接入端点)======
from .core.embed_service import embed_endpoint_override
@@ -125,6 +131,13 @@ __all__ = [
"snapshot_local_data_plane",
# 配置
"MemoryConfig",
+ # 公共扩展协议 / 精确读取类型
+ "EmbeddingService",
+ "EmbeddingServiceProtocol",
+ "EmbeddingDimensionMismatchError",
+ "MemoryKind",
+ "MemoryVariant",
+ "AmbiguousMemoryIdError",
# Embedding 端点覆盖
"embed_endpoint_override",
# 高级 API
diff --git a/hy_memory/client.py b/hy_memory/client.py
index e2ca32d..d52966d 100644
--- a/hy_memory/client.py
+++ b/hy_memory/client.py
@@ -38,6 +38,8 @@ from typing import List, Dict, Any, Optional, Tuple, Union, TYPE_CHECKING
from .config import MemoryConfig
from .core.embed_service import EmbedService, embed_endpoint_override
+from .embedding import EmbeddingDimensionMismatchError, EmbeddingService
+from .retrieval import AmbiguousMemoryIdError, MemoryKind, MemoryVariant
from .data.vector_store import create_vector_store
from .data.history_store import HistoryStore
from .data.cache import create_cache
@@ -434,6 +436,8 @@ class HyMemoryClient:
Args:
config: 自定义 MemoryConfig(默认从环境变量加载)
mode: 处理模式 ("lite" / "pro" / "ultra"),默认从环境变量 MEMORY_MODE 读取
+ embedding_service: 可选的调用方自管 embedding service;须满足公开的
+ EmbeddingService Protocol,client 不接管其生命周期。
"""
# 合法的 mode 值
@@ -445,12 +449,15 @@ class HyMemoryClient:
mode: Optional[str] = None,
coding_writer: Optional[str] = None,
runtime: Optional["SharedRuntime"] = None,
+ embedding_service: Optional[EmbeddingService] = None,
):
# 确保日志系统已配置(幂等,多次调用安全)
setup_logging()
# 配置
self._config = config or MemoryConfig.from_env()
+ self._borrowed_embedding_service = embedding_service
+ self._validate_embedding_service(embedding_service)
# coding_writer 显式传入则覆盖 config / env(默认 None → 沿用 config.coding.writer)
# 取值: "legacy" | "agent"
@@ -537,8 +544,12 @@ class HyMemoryClient:
)
logger.info(f"[init] Default ThreadPoolExecutor max_workers={_max_workers}")
- # 1. EmbedService(纯配置,首次调用时真正连接 API)
- self._embed_service = EmbedService(self._config)
+ # 1. EmbedService(注入发生在 ComponentFactory / pipeline 预热之前)
+ self._embed_service = (
+ self._borrowed_embedding_service
+ if self._borrowed_embedding_service is not None
+ else EmbedService(self._config)
+ )
logger.debug(
f"[init] EmbedService created: model={self._config.embedder.model}"
)
@@ -568,8 +579,10 @@ class HyMemoryClient:
)
# 4. ComponentFactory(注入已初始化的共享组件)
- self._registry = ComponentFactory(config=self._config)
- self._registry._shared_embed_service = self._embed_service
+ self._registry = ComponentFactory(
+ config=self._config,
+ embedding_service=self._embed_service,
+ )
self._registry._shared_vector_store = self._vector_store
self._registry._shared_vector_store_initialized = True
if self._graph_store is not None:
@@ -703,6 +716,7 @@ class HyMemoryClient:
cls,
config_dict: Dict[str, Any],
mode: Optional[str] = None,
+ embedding_service: Optional[EmbeddingService] = None,
) -> "HyMemoryClient":
"""
从字典创建客户端(类似 mem0 风格)。
@@ -734,7 +748,49 @@ class HyMemoryClient:
"""
config = MemoryConfig.from_dict(config_dict)
resolved_mode = mode or config_dict.get("mode")
- return cls(config=config, mode=resolved_mode)
+ return cls(
+ config=config,
+ mode=resolved_mode,
+ embedding_service=embedding_service,
+ )
+
+ def _validate_embedding_service(
+ self, embedding_service: Optional[EmbeddingService]
+ ) -> None:
+ """Validate a borrowed service before any store or pipeline is created."""
+ if embedding_service is None:
+ return
+ required = (
+ "embed",
+ "embed_with_meta",
+ "embed_batch",
+ "embed_queued",
+ "embed_queued_with_meta",
+ "get_embedding_dims",
+ )
+ missing = [
+ name for name in required
+ if not callable(getattr(embedding_service, name, None))
+ ]
+ if missing:
+ raise TypeError(
+ "embedding_service does not implement EmbeddingService; "
+ f"missing: {', '.join(missing)}"
+ )
+ try:
+ actual_dims = int(embedding_service.get_embedding_dims())
+ except Exception as exc:
+ raise TypeError(
+ "embedding_service.get_embedding_dims() must return an integer"
+ ) from exc
+ expected_dims = getattr(self._config.vector_store, "embedding_dims", None)
+ if expected_dims is None:
+ expected_dims = getattr(self._config.embedder, "embedding_dims", None)
+ if expected_dims is not None and actual_dims != int(expected_dims):
+ raise EmbeddingDimensionMismatchError(
+ "embedding service dimension mismatch: "
+ f"service={actual_dims}, vector_store={int(expected_dims)}"
+ )
# ================================================================
# 属性
@@ -1060,6 +1116,7 @@ class HyMemoryClient:
llm_provider=self._coding_llm_provider,
embed_service=self._embed_service,
cache=self._cache,
+ variant=variant,
)
self._coding_stores[variant] = store
self._coding_writers[variant] = writer
@@ -1830,6 +1887,8 @@ class HyMemoryClient:
memory_id: str,
*,
include_raw: bool = False,
+ kind: Optional[MemoryKind] = None,
+ variant: Optional[MemoryVariant] = None,
) -> Optional[Dict[str, Any]]:
"""
获取单条记忆。
@@ -1838,12 +1897,19 @@ class HyMemoryClient:
memory_id: 记忆 ID
include_raw: 是否允许返回 L1_RAW 原始记忆。默认 False,保持原有隐藏行为;
lite 模式的记忆均为 L1_RAW,需显式设为 True 才能按 ID 读取。
+ kind: 可选 namespace("chat" / "experience" / "fact")。
+ variant: 可选生产力变体("working" / "coding")。
Returns:
- {"memory_id", "content", "layer", "request_id", "elapsed_ms"} 或 None(不存在时)
+ 带 kind/variant 的统一 memory dict,或 None(不存在时)。
"""
return self._loop_thread.run(
- self.async_get(memory_id, include_raw=include_raw)
+ self.async_get(
+ memory_id,
+ include_raw=include_raw,
+ kind=kind,
+ variant=variant,
+ )
)
def update(
@@ -2737,6 +2803,8 @@ class HyMemoryClient:
request_id=request_id,
source=source,
)
+ # Public receipt always identifies the productivity namespace.
+ resp["variant"] = scene_variant
# 版本演进链层(scene="coding" 独有)。放在 writer.write 之后、返回
# 之前,因为它只依赖对话原文,与向量层写入结果无关。
# best-effort:这层挂不上不影响本次 add 的向量层产出。
@@ -4374,35 +4442,104 @@ class HyMemoryClient:
# CRUD API(异步)— get / update / delete / delete_all
# ================================================================
+ async def _coding_store_for_exact_get(self, variant: str):
+ """Return an existing namespace store without creating an empty DB."""
+ stores = getattr(self, "_coding_stores", None) or {}
+ store = stores.get(variant)
+ if store is not None:
+ return store
+
+ from .coding.store import CodingMemoryStore
+
+ config = getattr(self, "_config", None)
+ coding_config = getattr(config, "coding", None)
+ if config is None or coding_config is None:
+ return None
+ if not CodingMemoryStore.database_exists(
+ config,
+ db_path=coding_config.db_path,
+ variant=variant,
+ ):
+ return None
+ await self._get_coding_writer(variant=variant)
+ return (getattr(self, "_coding_stores", None) or {}).get(variant)
+
+ @staticmethod
+ def _format_productivity_get(
+ item: Any,
+ *,
+ kind: str,
+ variant: str,
+ request_id: str,
+ elapsed_ms: float,
+ ) -> Dict[str, Any]:
+ payload = item.to_dict()
+ item_id = (
+ payload.get("experience_id")
+ if kind == "experience"
+ else payload.get("fact_id")
+ )
+ return {
+ "memory_id": item_id,
+ "kind": kind,
+ "variant": variant,
+ "scene": "productivity",
+ "content": (
+ payload.get("solution", "")
+ if kind == "experience"
+ else payload.get("statement", "")
+ ),
+ "layer": kind,
+ **payload,
+ "request_id": request_id,
+ "elapsed_ms": elapsed_ms,
+ }
+
@_ensure_internal_loop
async def async_get(
self,
memory_id: str,
*,
include_raw: bool = False,
+ kind: Optional[MemoryKind] = None,
+ variant: Optional[MemoryVariant] = None,
) -> Optional[Dict[str, Any]]:
"""
获取单条记忆(异步)。
- VDB + Graph 双路并行查询,哪个有结果返回哪个。
+ 默认查询 chat、working/coding experience 和 working/coding fact。
+ 若同一 ID 命中多个 namespace,则 fail closed;调用方必须用 kind/variant
+ 显式消歧。
Args:
memory_id: 记忆 ID
include_raw: 是否允许返回 L1_RAW 原始记忆,默认 False。
+ kind: 可选 namespace("chat" / "experience" / "fact")。
+ variant: 可选生产力变体("working" / "coding")。
Returns:
- {"memory_id", "content", "layer", "source", "request_id", "elapsed_ms"} 或 None
+ 统一 memory dict,或 None。
"""
- import asyncio as _asyncio_get
from .models.memory import MemoryLayer
+ if kind not in (None, "chat", "experience", "fact"):
+ raise ValueError(
+ "kind must be one of: chat, experience, fact"
+ )
+ if variant not in (None, "working", "coding"):
+ raise ValueError("variant must be one of: working, coding")
+ if kind == "chat" and variant is not None:
+ raise ValueError("variant is only valid for experience/fact lookups")
+
request_id = str(uuid.uuid4())
set_request_id(request_id)
t0 = time.perf_counter()
- logger.info(f"[get] memory_id={memory_id}")
+ logger.info(
+ "[get] memory_id=%s kind=%s variant=%s",
+ memory_id, kind, variant,
+ )
- # 双路并行
async def _get_vdb():
return await self._vector_store.get_by_id(memory_id)
@@ -4415,7 +4552,36 @@ class HyMemoryClient:
logger.debug(f"[get] graph_store query failed: {e}")
return None
- vdb_node, graph_node = await _asyncio_get.gather(_get_vdb(), _get_graph())
+ query_chat = kind in (None, "chat") and variant is None
+ coding_kinds = (
+ ("experience", "fact") if kind is None else (kind,)
+ )
+ coding_variants = (variant,) if variant is not None else ("working", "coding")
+
+ stores = {}
+ if kind != "chat":
+ for candidate_variant in coding_variants:
+ store = await self._coding_store_for_exact_get(candidate_variant)
+ if store is not None:
+ stores[candidate_variant] = store
+
+ tasks = []
+ task_names = []
+ if query_chat:
+ tasks.extend((_get_vdb(), _get_graph()))
+ task_names.extend(("chat:vdb", "chat:graph"))
+ for candidate_variant, store in stores.items():
+ if "experience" in coding_kinds:
+ tasks.append(store.get_by_id(memory_id))
+ task_names.append(f"{candidate_variant}:experience")
+ if "fact" in coding_kinds:
+ tasks.append(store.get_fact(memory_id))
+ task_names.append(f"{candidate_variant}:fact")
+
+ values = await asyncio.gather(*tasks) if tasks else []
+ by_name = dict(zip(task_names, values))
+ vdb_node = by_name.get("chat:vdb")
+ graph_node = by_name.get("chat:graph")
# L1_RAW 默认不对外可见:按 ID 直取走主键查询、绕过向量库的 layer
# filter,故在此统一挡掉。SDK 调用方可通过 include_raw=True 显式读取;
@@ -4437,17 +4603,32 @@ class HyMemoryClient:
):
graph_node = None
- elapsed = round((time.perf_counter() - t0) * 1000, 2)
+ matches = []
+ chat_node = vdb_node if vdb_node is not None else graph_node
+ if chat_node is not None:
+ matches.append(("chat", chat_node))
+ for name, value in by_name.items():
+ if not name.startswith("chat:") and value is not None:
+ matches.append((name, value))
+
+ if len(matches) > 1:
+ raise AmbiguousMemoryIdError(
+ memory_id, [namespace for namespace, _ in matches]
+ )
- # pipeline trace(best-effort,受 MEMORY_PIPELINE_TRACE_ENABLED 控制)
- _hit_node = vdb_node if vdb_node is not None else graph_node
- _source = "vdb" if vdb_node is not None else ("graph" if graph_node is not None else "")
+ elapsed = round((time.perf_counter() - t0) * 1000, 2)
+ _hit_namespace, _hit_node = matches[0] if matches else ("", None)
+ _source = (
+ "vdb" if vdb_node is not None
+ else ("graph" if graph_node is not None else _hit_namespace)
+ )
_ident = self._backend_identity()
_parsed = {
"memory_id": memory_id,
**_ident,
"hit": _hit_node is not None,
"source": _source,
+ "namespace": _hit_namespace,
}
if _hit_node is not None:
try:
@@ -4464,10 +4645,25 @@ class HyMemoryClient:
elapsed_ms=elapsed,
)
- # VDB 优先(如果两边都有,以 VDB 为准)
+ if not matches:
+ logger.info(f"[get] not found: memory_id={memory_id}")
+ return None
+
+ if _hit_namespace != "chat":
+ hit_variant, hit_kind = _hit_namespace.split(":", 1)
+ return self._format_productivity_get(
+ _hit_node,
+ kind=hit_kind,
+ variant=hit_variant,
+ request_id=request_id,
+ elapsed_ms=elapsed,
+ )
+
if vdb_node is not None:
return {
"memory_id": vdb_node.node_id,
+ "kind": "chat",
+ "variant": None,
"content": vdb_node.content,
"layer": vdb_node.layer.value,
"status": vdb_node.status.value if vdb_node.status else "active",
@@ -4481,6 +4677,8 @@ class HyMemoryClient:
# 不透出 source_raw_memory_id:见 async_search 同处说明。
"user_id": vdb_node.user_id,
"agent_id": vdb_node.agent_id,
+ "session_id": vdb_node.session_id,
+ "owner": vdb_node.owner,
"confidence": vdb_node.confidence,
"custom": vdb_node.custom or {},
"meta": list((vdb_node.custom or {}).get("meta") or []),
@@ -4492,6 +4690,8 @@ class HyMemoryClient:
if graph_node is not None:
return {
"memory_id": graph_node.node_id,
+ "kind": "chat",
+ "variant": None,
"content": graph_node.content,
"layer": graph_node.layer.value if graph_node.layer else "",
"status": graph_node.status.value if graph_node.status else "active",
@@ -4505,6 +4705,8 @@ class HyMemoryClient:
# 不透出 source_raw_memory_id:见 async_search 同处说明。
"user_id": graph_node.user_id,
"agent_id": graph_node.agent_id,
+ "session_id": getattr(graph_node, "session_id", "") or "",
+ "owner": getattr(graph_node, "owner", None),
"confidence": graph_node.confidence,
"custom": getattr(graph_node, "custom", {}) or {},
"source": "graph",
@@ -4512,7 +4714,6 @@ class HyMemoryClient:
"elapsed_ms": elapsed,
}
- logger.info(f"[get] not found: memory_id={memory_id}")
return None
@_ensure_internal_loop
diff --git a/hy_memory/coding/store.py b/hy_memory/coding/store.py
index 0b0d232..123a9f1 100644
--- a/hy_memory/coding/store.py
+++ b/hy_memory/coding/store.py
@@ -416,6 +416,36 @@ class CodingMemoryStore:
self._initialized = False
+ @staticmethod
+ def database_path(
+ config: MemoryConfig,
+ db_path: Optional[str] = None,
+ variant: str = "working",
+ ) -> str:
+ """Return the authoritative SQLite path without creating anything."""
+ if db_path is None:
+ data_dir = (
+ os.path.dirname(config.history.db_path)
+ if config.history.db_path else "./data"
+ )
+ db_path = os.path.join(data_dir, "coding_memory.db")
+ normalized = (
+ "coding"
+ if str(variant or "").strip().lower() == "coding"
+ else "working"
+ )
+ return _variant_db_path(db_path, "_cv" if normalized == "coding" else "")
+
+ @classmethod
+ def database_exists(
+ cls,
+ config: MemoryConfig,
+ db_path: Optional[str] = None,
+ variant: str = "working",
+ ) -> bool:
+ """Whether a coding namespace has an existing SQLite database."""
+ return os.path.isfile(cls.database_path(config, db_path, variant))
+
async def initialize(self) -> None:
if self._initialized:
return
diff --git a/hy_memory/coding/writer.py b/hy_memory/coding/writer.py
index 34d21d0..c6a8b1e 100644
--- a/hy_memory/coding/writer.py
+++ b/hy_memory/coding/writer.py
@@ -50,6 +50,7 @@ class CodingWriter:
embed_service: EmbedService,
fact_reconciler: Optional[WorkingFactReconciler] = None,
cache: Any = None,
+ variant: str = "working",
):
self.store = store
self.extractor = extractor
@@ -59,6 +60,11 @@ class CodingWriter:
self.fact_reconciler = fact_reconciler or WorkingFactReconciler(
store, embed_service, llm_provider
)
+ self.variant = (
+ "coding"
+ if str(variant or "").strip().lower() == "coding"
+ else "working"
+ )
# cache 仅用于把 request_id 串给各阶段(各阶段自己打点);writer 不集中打点。
self.cache = cache
@@ -217,6 +223,7 @@ class CodingWriter:
return {
"success": True,
"scene": "productivity",
+ "variant": self.variant,
"request_id": request_id,
"elapsed_ms": round((time.perf_counter() - t0) * 1000, 2),
"ops": [op.to_dict() for op in ops],
@@ -278,11 +285,11 @@ class CodingWriter:
f"[coding-write] crosslink fact {f.fact_id} failed: {e}"
)
- @staticmethod
- def _empty_response(request_id: str, t0: float) -> Dict[str, Any]:
+ def _empty_response(self, request_id: str, t0: float) -> Dict[str, Any]:
return {
"success": True,
"scene": "productivity",
+ "variant": self.variant,
"request_id": request_id,
"elapsed_ms": round((time.perf_counter() - t0) * 1000, 2),
"ops": [],
diff --git a/hy_memory/embedding.py b/hy_memory/embedding.py
new file mode 100644
index 0000000..17ffd8b
--- /dev/null
+++ b/hy_memory/embedding.py
@@ -0,0 +1,53 @@
+"""Public structural contract for injected embedding services."""
+
+from typing import Any, Dict, List, Protocol, Tuple, runtime_checkable
+
+
+@runtime_checkable
+class EmbeddingService(Protocol):
+ """Embedding service accepted by :class:`HyMemoryClient`.
+
+ Implementations are borrowed by the client: their lifecycle remains owned
+ by the caller and ``HyMemoryClient.close()`` will not close them.
+ """
+
+ async def embed(self, text: str, use_cache: bool = True) -> List[float]:
+ ...
+
+ async def embed_with_meta(
+ self, text: str, use_cache: bool = True
+ ) -> Tuple[List[float], Dict[str, Any]]:
+ ...
+
+ async def embed_batch(
+ self, texts: List[str], use_cache: bool = True
+ ) -> List[List[float]]:
+ ...
+
+ async def embed_queued(
+ self, text: str, use_cache: bool = True
+ ) -> List[float]:
+ ...
+
+ async def embed_queued_with_meta(
+ self, text: str, use_cache: bool = True
+ ) -> Tuple[List[float], Dict[str, Any]]:
+ ...
+
+ def get_embedding_dims(self) -> int:
+ ...
+
+
+# Explicit alias for callers that prefer the conventional Protocol suffix.
+EmbeddingServiceProtocol = EmbeddingService
+
+
+class EmbeddingDimensionMismatchError(ValueError):
+ """Raised before initialization when service and store dimensions differ."""
+
+
+__all__ = [
+ "EmbeddingService",
+ "EmbeddingServiceProtocol",
+ "EmbeddingDimensionMismatchError",
+]
diff --git a/hy_memory/pipelines/registry.py b/hy_memory/pipelines/registry.py
index caea7c9..221d399 100644
--- a/hy_memory/pipelines/registry.py
+++ b/hy_memory/pipelines/registry.py
@@ -19,6 +19,7 @@ import logging
from .base import WritePipeline, ReadPipeline
from ..config import MemoryConfig
from ..core.embed_service import EmbedService
+from ..embedding import EmbeddingService
from ..data.vector_store import create_vector_store
from ..data.vector_store_base import VectorStoreBase
@@ -50,7 +51,12 @@ class ComponentFactory:
s2 = await factory.get_system2_writer() # System2Writer (ultra mode)
"""
- def __init__(self, config: Optional[MemoryConfig] = None):
+ def __init__(
+ self,
+ config: Optional[MemoryConfig] = None,
+ *,
+ embedding_service: Optional[EmbeddingService] = None,
+ ):
self.config = config or MemoryConfig.from_env()
# 实例缓存(单例)
@@ -62,7 +68,7 @@ class ComponentFactory:
self._readers: Dict[str, ReadPipeline] = {}
# 共享资源
- self._shared_embed_service: Optional[EmbedService] = None
+ self._shared_embed_service: Optional[EmbeddingService] = embedding_service
self._shared_vector_store: Optional[VectorStoreBase] = None
self._shared_vector_store_initialized: bool = False
self._shared_graph_store = None
@@ -72,7 +78,7 @@ class ComponentFactory:
# 共享资源
# ================================================================
- def _get_shared_embed_service(self) -> EmbedService:
+ def _get_shared_embed_service(self) -> EmbeddingService:
if self._shared_embed_service is None:
self._shared_embed_service = EmbedService(self.config)
return self._shared_embed_service
diff --git a/hy_memory/retrieval.py b/hy_memory/retrieval.py
new file mode 100644
index 0000000..b632132
--- /dev/null
+++ b/hy_memory/retrieval.py
@@ -0,0 +1,23 @@
+"""Public types and errors for exact memory-ID lookup."""
+
+from typing import Literal, Sequence
+
+
+MemoryKind = Literal["chat", "experience", "fact"]
+MemoryVariant = Literal["working", "coding"]
+
+
+class AmbiguousMemoryIdError(LookupError):
+ """An ID exists in more than one public memory namespace."""
+
+ def __init__(self, memory_id: str, namespaces: Sequence[str]):
+ self.memory_id = memory_id
+ self.namespaces = tuple(namespaces)
+ joined = ", ".join(self.namespaces)
+ super().__init__(
+ f"memory ID {memory_id!r} is ambiguous across namespaces: {joined}; "
+ "pass kind and/or variant to disambiguate"
+ )
+
+
+__all__ = ["MemoryKind", "MemoryVariant", "AmbiguousMemoryIdError"]
diff --git a/hy_memory/utils/lang_detect.py b/hy_memory/utils/lang_detect.py
index 853484e..fbf8bf9 100644
--- a/hy_memory/utils/lang_detect.py
+++ b/hy_memory/utils/lang_detect.py
@@ -8,6 +8,7 @@ Uses a two-tier strategy:
This avoids langdetect's known weakness with short Chinese text.
"""
+import json
import logging
import re
from typing import List, Optional
@@ -135,6 +136,30 @@ def detect_language(text: str) -> str:
return "zh" if ratio > 0.1 else "en"
+def _spoken_text(value: str) -> str:
+ """Ignore text-block metadata when a message content is structured JSON."""
+ text = value.strip()
+ if text.startswith("["):
+ try:
+ blocks = json.loads(text)
+ except (ValueError, TypeError):
+ pass
+ else:
+ if (
+ isinstance(blocks, list)
+ and blocks
+ and all(
+ isinstance(block, dict)
+ and isinstance(block.get("type"), str)
+ and block["type"] in {"text", "input_text", "output_text"}
+ and isinstance(block.get("text"), str)
+ for block in blocks
+ )
+ ):
+ return "\n".join(block["text"] for block in blocks)
+ return text
+
+
def extract_content_for_detection(
content: str = "",
messages: Optional[List] = None,
@@ -153,20 +178,57 @@ def extract_content_for_detection(
Concatenated content text suitable for language detection.
"""
if content and content.strip():
- return content.strip()
+ value = content.strip()
+ # Writer serializes message batches to JSON before calling Extractor.
+ # Detect the spoken text, not the leading ASCII keys (role/content),
+ # without changing the raw evidence sent to the model.
+ if value.startswith("["):
+ try:
+ decoded = json.loads(value)
+ except (ValueError, TypeError):
+ pass
+ else:
+ if (
+ isinstance(decoded, list)
+ and decoded
+ and all(
+ isinstance(item, dict)
+ and isinstance(item.get("role"), str)
+ and isinstance(item.get("content"), str)
+ for item in decoded
+ )
+ ):
+ # In a mixed batch, the latest user turn is the clearest
+ # instruction for the language; assistant/tool metadata
+ # must not decide it first.
+ user_text = [
+ _spoken_text(item["content"])
+ for item in decoded
+ if item["role"] == "user" and item["content"].strip()
+ ]
+ if user_text:
+ return user_text[-1]
+ spoken = "\n".join(_spoken_text(item["content"]) for item in decoded)
+ if spoken.strip():
+ return spoken
+ return _spoken_text(value)
if messages:
parts = []
+ user_parts = []
for msg in messages:
if isinstance(msg, dict):
- c = msg.get("content", "")
+ c, role = msg.get("content", ""), msg.get("role")
elif hasattr(msg, "content"):
- c = msg.content
+ c, role = msg.content, getattr(msg, "role", None)
else:
continue
- if c and c.strip():
- parts.append(c.strip())
- return "\n".join(parts)
+ if isinstance(c, str) and c.strip():
+ text = _spoken_text(c)
+ parts.append(text)
+ if role == "user":
+ user_parts.append(text)
+ return user_parts[-1] if user_parts else "\n".join(parts)
return ""
diff --git a/memhub/MEMORY.md b/memhub/MEMORY.md
index d16f18b..4ffcb40 100644
--- a/memhub/MEMORY.md
+++ b/memhub/MEMORY.md
@@ -12,7 +12,8 @@
2. MemHub 对 memory 的原子操作 **只经 SDK**;缺接口先补 SDK。
3. MemHub **不存 memory 实体**;**可以存 `memory_id`** 做组织/回执。原文进入 **SDK raw**。
-生产入口仍建议经 `HyMemoryBridge`(共享 Runtime、模型配置、密钥、harness/model 门禁),但 bridge **不得**再把 SDK 结果镜像成第二套 memory 正文权威。
+生产入口通过共享 Runtime 租约取得公开 `HyMemoryClient`;MemHub 只在调用前执行
+模型配置、密钥和 harness/model 门禁,不维护第二套 memory 正文权威。
来源授权、模型授权和宿主召回授权仍是 MemHub 管理面门禁;memory
数据平面的权威在 SDK。
@@ -30,46 +31,15 @@ reader: hybrid
## MemHub 运行时边界
-MemHub 对 SDK 使用公开、可复现的本地策略(经 bridge / `hy_runtime_config` 注入):
+MemHub 通过公开 `HyMemoryClient` 配置使用可复现的本地策略:
- vector / graph / cache / history / coding 等 **一律 SDK config/env**;
- 模型与 embedding 来自版本化 Model Profile;密钥进安全存储;
- MemHub 管理库可存 harness/model/队列状态与 **`memory_id` 引用**。
-发布包默认 SDK 行为环境变量仍集中在
-`apps/core/src/one_memory/hy_runtime_config.py`,并由下表锁定:
-
-| 变量 | 值 |
-|---|---|
-| `MEMORY_MODE` | `ultra` |
-| `MEMORY_ENABLE_GRAPH` | `true` |
-| `MEMORY_GRAPH_RERANK_ENABLED` | `false` |
-| `MEMORY_GRAPH_TEMPORAL_SPINE` | `true` |
-| `MEMORY_TOPIC_SUMMARY_ENABLED` | `false` |
-| `MEMORY_EPISODE_SUMMARY_ENABLED` | `false` |
-| `MEMORY_EPISODE_RECALL_ENABLED` | `true` |
-| `MEMORY_DYNAMIC_EPISODE_ENABLED` | `true` |
-| `MEMORY_SESSION_EPISODE_ENABLED` | `false` |
-| `MEMORY_SESSION_EPISODE_CONTEXT_ENABLED` | `false` |
-| `MEMORY_EPISODE_CAPSULE_CONTEXT_ENABLED` | `true` |
-| `MEMORY_EPISODE_CAPSULE_QUERY_MIN` | `0.65` |
-| `MEMORY_EPISODE_CAPSULE_ASSIGNMENT_MIN` | `0.60` |
-| `MEMORY_EPISODE_CAPSULE_FIRST_RANK_MAX` | `3` |
-| `MEMORY_EPISODE_CAPSULE_MEMBER_LIMIT` | `3` |
-| `MEMORY_ENABLE_INTENTION` | `false` |
-| `MEMORY_ENABLE_QUERY_REWRITE` | `false` |
-| `MEMORY_FEW_SHOT_ENABLED` | `true` |
-| `MEMORY_HYBRID_V2_QUERY_EXPAND` | `1` |
-| `MEMORY_HYBRID_V2_GEO_INTENT_PRIOR` | `0.6` |
-| `MEMORY_HYBRID_V2_DIVERSITY` | `1` |
-| `MEMORY_HYBRID_V2_TEMPORAL_ADMIT_PRIOR` | `0.55` |
-| `MEMORY_HYBRID_V2_TEMPORAL_BOOST` | `0.18` |
-| `MEMORY_CROSS_DOMAIN_CON_THRESHOLD` | `0.5` |
-| `MEMORY_READER_ENABLE_SUMMARY` | `false` |
-| `MEMORY_SUMMARY_ENABLED_IN_SYS2` | `false` |
-| `MEMORY_LOCAL_RERANK_ENABLED` | `false` |
-| `RECONCILE_ENABLED` | `true` |
-| `HY_MEMORY_READER` | `hybrid` |
+MemHub 不再通过 import-time 环境变量覆盖 SDK 的提取、reconcile、episode、
+intention、few-shot、summary 或去重策略。产品只配置模型/密钥/endpoint、本地
+backend 路径、公开 embedding service,以及每次公开 Client 调用的参数。
独立脚本直连 SDK 时须自配存储目录与模型端点。
@@ -77,7 +47,7 @@ MemHub 对 SDK 使用公开、可复现的本地策略(经 bridge / `hy_runtim
下面是独立调试示例。
-产品代码经 `HyMemoryBridge` 获取已配置的 client(管理面门禁),memory I/O
+产品代码经 `hy_sdk_runtime.SdkClientHandle` 获取已配置的公开 client;memory I/O
由 SDK 完成。
```python
@@ -228,7 +198,8 @@ result = client.search(
- 区分空结果、权限拒绝、不可用、超时、部分结果;
- 未发布的 Matter 占位功能不保留表或 API;未来组织功能另立合同。
-生产入口:`hy_memory_bridge.py`、`recall.py`、`packages/host-bridge`。
+生产入口:`hy_sdk_runtime.py`、`sdk_write_processor.py`、`recall.py` 和
+`packages/host-bridge`。
## 关闭客户端
@@ -245,8 +216,7 @@ Runtime 长期复用 client;仅在停止、配置切换或受控恢复时重
```text
harness / user action (+ authz, model, queue)
- -> HyMemoryBridge
- -> Hy Memory SDK
+ -> public HyMemoryClient
-> SDK stores (config/env)
-> optional MemHub persist memory_id / org metadata
-> Recall Broker / UI (SDK read + MemHub authz)
diff --git a/memhub/apps/core/scripts/verify_c2_slice.py b/memhub/apps/core/scripts/verify_c2_slice.py
index 6f491ef..b154eec 100644
--- a/memhub/apps/core/scripts/verify_c2_slice.py
+++ b/memhub/apps/core/scripts/verify_c2_slice.py
@@ -42,12 +42,10 @@ TARGETED = (
"tests/test_database_contention.py",
"tests/test_main_database_fairness.py",
"tests/test_soak_probe_effectiveness.py",
- "tests/test_evidence_reconcile_primitive.py",
"tests/test_sqlite_semantics_gate.py",
"tests/test_store_binding.py",
"tests/test_store_binding_ratchet.py",
"tests/test_main_database_entry.py",
- "tests/test_memory_processing.py",
"tests/test_extraction_window.py",
"tests/test_extraction_defer.py",
"tests/test_active_memory_window.py",
diff --git a/memhub/apps/core/src/one_memory/__init__.py b/memhub/apps/core/src/one_memory/__init__.py
index 0786748..08a272d 100644
--- a/memhub/apps/core/src/one_memory/__init__.py
+++ b/memhub/apps/core/src/one_memory/__init__.py
@@ -2,11 +2,5 @@
import os
-from one_memory.hy_runtime_config import configure_hy_behavior_environment
-
-# HY has a few reader switches evaluated at module import time. Fix the
-# product-owned, non-secret behavior before any one_memory module imports HY.
-configure_hy_behavior_environment()
-
_version = os.environ.get("ONE_MEMORY_VERSION", "").strip()
__version__ = _version if _version else "development"
diff --git a/memhub/apps/core/src/one_memory/api.py b/memhub/apps/core/src/one_memory/api.py
index 991eec0..8d7a6ad 100644
--- a/memhub/apps/core/src/one_memory/api.py
+++ b/memhub/apps/core/src/one_memory/api.py
@@ -50,6 +50,10 @@ from one_memory.auth import local_api_guard, renderer_origins
from one_memory.background_work import shutdown_bulk_pool, warm_bulk_pool
from one_memory.config import Settings, load_settings
from one_memory.context_routes import context_router, sdk_context_router
+from one_memory.conversation_processing import (
+ _conversation_chunks,
+ memory_task_timeout_seconds,
+)
from one_memory.database_access import (
MAIN_DATABASE_REPORT_SECONDS,
close_main_databases,
@@ -78,23 +82,30 @@ from one_memory.external_memory_access import external_access, require_external_
from one_memory.extraction_settings import ExtractionSettings, ExtractionSettingsStore
from one_memory.file_imports import FileImportStore, file_import_router
from one_memory.home_summary import HomeSummary, read_home_summary
-from one_memory.hy_memory_bridge import (
- GraphWidthDecision,
- GraphWidthMismatch,
- HyMemoryBridge,
- HyMemoryBridgeError,
- HySdkMemoryPage,
- HySdkMemoryRecord,
- HySdkRawRecord,
- builtin_retrieval_snapshot,
-)
+from one_memory.hy_graph_admin import GraphWidthDecision, GraphWidthMismatch
from one_memory.hy_runtime_config import (
+ HY_MEMORY_READER,
DiagnosticLogLevel,
detailed_logging_enabled,
diagnostic_log_level,
set_detailed_logging,
set_diagnostic_log_level,
)
+from one_memory.hy_sdk_runtime import (
+ SdkClientHandle,
+ builtin_retrieval_snapshot,
+ close_all_shared_runtimes,
+ sdk_relevance_floor,
+)
+from one_memory.hy_sdk_types import (
+ HySdkError,
+ HySdkMemoryPage,
+ HySdkMemoryRecord,
+ HySdkRawPage,
+ HySdkRawRecord,
+ HySdkUserProfile,
+ parse_sdk_search,
+)
from one_memory.imports.access import (
AuthorizedSourceRoot,
SourceAccessError,
@@ -167,11 +178,10 @@ from one_memory.memory_library import (
read_conversation_memories,
read_memory_library,
)
-from one_memory.memory_notes import MemoryNoteStore, memory_note_router
-from one_memory.memory_processing import (
- MemoryProcessingSupervisor,
- _conversation_chunks,
- memory_task_timeout_seconds,
+from one_memory.memory_notes import (
+ LegacyMemoryNoteReader,
+ MemoryNoteStore,
+ memory_note_router,
)
from one_memory.memory_qa import MemoryAnswerer, MemoryAnswerError
from one_memory.memory_queue import (
@@ -201,7 +211,10 @@ from one_memory.model_profiles import (
ModelProfileStore,
ModelProfileUnavailableError,
)
-from one_memory.model_request_audit import AuditedModelTransport, ModelRequestAuditStore
+from one_memory.model_request_audit import (
+ AuditedModelTransport,
+ ModelRequestAuditStore,
+)
from one_memory.model_request_budget import BudgetedModelTransport, ModelRequestBudget
from one_memory.onboarding import OnboardingState, OnboardingStore
from one_memory.recall import (
@@ -225,6 +238,8 @@ from one_memory.sdk_memory_qa import (
SdkMemoryAnswer,
SdkMemoryAnswerer,
)
+from one_memory.sdk_memory_runtime import SdkMemoryRuntime
+from one_memory.sdk_write_processor import SdkWriteCoordinator
from one_memory.secrets import (
KeyringSecretStore,
SecretStore,
@@ -845,7 +860,7 @@ def create_app(
runtime = CoreRuntime(runtime_settings) if manage_runtime else nullcontext()
with runtime:
database_path = runtime_settings.data_dir / "one-memory.sqlite3"
- app.state.sdk_library_bridge = None
+ app.state.sdk_client_handle = None
bootstrap_fresh_management_schema(database_path)
# Before any store: each one below changes the library as it opens.
try:
@@ -891,6 +906,7 @@ def create_app(
)
from one_memory.memory_server.data_safety import MIN_FREE_BYTES
from one_memory.memory_server.durable_queue import (
+ COMPLETED,
DurableWriteDrain,
DurableWriteQueue,
execute_job,
@@ -968,29 +984,21 @@ def create_app(
await asyncio.to_thread(app.state.evidence_store.release_completed_sdk_staging)
evidence_store = app.state.evidence_store
if app.state.memory_authority is MemoryAuthority.SDK:
- sdk_bridge = _LazySdkBridge(app)
-
- async def read_sdk_memory(
- memory_id: str,
- ) -> HySdkMemoryRecord | None:
- return cast(
- HySdkMemoryRecord | None,
- await sdk_bridge.get_sdk_memory(memory_id),
- )
-
+ sdk_handle = _sdk_client_handle(app)
app.state.recall_target = SdkRecallTarget(
- semantic_search=lambda query: sdk_bridge.search_memories(
+ semantic_search=lambda query: _search_sdk_memories(
+ sdk_handle,
query,
user_id="local",
agent_id="*",
),
- get_memory=read_sdk_memory,
+ get_memory=lambda memory_id: _get_sdk_memory(sdk_handle, memory_id),
)
else:
app.state.recall_target = GovernedRecallTarget(
app.state.memory_governance_store,
filter_memories=app.state.source_read_access.memories,
- semantic_search=lambda query: _memory_processing_supervisor(
+ semantic_search=lambda query: _sdk_memory_runtime(
app
).semantic_recall(query),
# Read per request rather than cached: an import that lands
@@ -1094,7 +1102,7 @@ def create_app(
authorize_generation=lambda profile, question, grounding: (
_authorize_answer_generation(app, profile, question, grounding)
),
- semantic_search=lambda query: _memory_processing_supervisor(app).semantic_recall(
+ semantic_search=lambda query: _sdk_memory_runtime(app).semantic_recall(
query
),
resolve_workspace=lambda workspace_path: resolve_workspace_scopes(
@@ -1116,43 +1124,32 @@ def create_app(
store=app.state.model_profile_store,
secrets=app.state.secret_store,
)
- app.state.memory_processing_supervisor = MemoryProcessingSupervisor(
- tasks=app.state.memory_task_store,
+ app.state.sdk_write_coordinator = SdkWriteCoordinator(
profiles=app.state.model_profile_store,
secrets=app.state.secret_store,
- evidence=app.state.evidence_store,
- governance=app.state.memory_governance_store,
data_dir=runtime_settings.data_dir,
- extraction_settings=app.state.extraction_settings_store,
- bridge_factory=lambda profile, api_key, data_dir: HyMemoryBridge(
- profile=profile,
- api_key=api_key,
- data_dir=data_dir,
- http_transport_factory=lambda: AuditedModelTransport(
- app.state.model_request_audit_store,
- profile_id=profile.profile_id,
- profile_revision=profile.revision,
- provider_kind=str(profile.provider_kind),
- model=profile.model,
- inner=(
- BudgetedModelTransport(model_request_budget)
- if model_request_budget is not None
- else None
- ),
+ transport_factory=lambda profile: lambda: AuditedModelTransport(
+ app.state.model_request_audit_store,
+ profile_id=profile.profile_id,
+ profile_revision=profile.revision,
+ provider_kind=str(profile.provider_kind),
+ model=profile.model,
+ inner=(
+ BudgetedModelTransport(model_request_budget)
+ if model_request_budget is not None
+ else None
),
),
- # `None` means "whatever the active profile allows". Pinned to
- # 1 in `a59f4b5` as temporary load-shedding for an acceptance
- # package, and left pinned after it: a hardcoded 1 is rule 9's
- # exact anti-pattern (a small number baked into code that
- # cannot be tuned per machine). Measured before removing — at
- # profile concurrency 4, recall latency is unchanged while
- # precipitation goes 4x.
- max_concurrent_tasks=runtime_settings.precipitation_max_concurrent_tasks,
- source_writes_permitted=lambda source_id: _source_writes_on(app, source_id),
- service_levels=app.state.service_levels,
- sedimentation_enabled=lambda: _config_store(app).sedimentation_enabled(),
- sdk_authority=lambda: app.state.memory_authority is MemoryAuthority.SDK,
+ sedimentation_enabled=lambda: _config_store(
+ app
+ ).sedimentation_enabled(),
+ )
+ app.state.sdk_memory_runtime = SdkMemoryRuntime(
+ coordinator=app.state.sdk_write_coordinator,
+ read_handle=_sdk_client_handle(app),
+ write_queue=memory_write_queue,
+ extraction_settings=app.state.extraction_settings_store,
+ data_dir=runtime_settings.data_dir,
)
# C2 owns the single production budget (handle 5s + reserve 250ms,
# total 5.25s, lease 10s, renew 1s, claim 250ms). The composition
@@ -1162,34 +1159,26 @@ def create_app(
drain_budget = production_drain_budget()
async def reconcile_unknown_writes() -> None:
- if app.state.memory_authority is MemoryAuthority.SDK:
- # Unknown SDK writes must be reconciled by SDK request ID.
- # Until that direct path is available, retain them as
- # unknown rather than re-running a possibly successful add.
- return
- await app.state.memory_processing_supervisor.reconcile_unknown_outputs(
- exclude_error_codes=NON_RETRYABLE_POST_WRITE_CODES,
- )
unknown = await asyncio.to_thread(
memory_write_queue.unknown_jobs,
limit=128,
exclude_error_codes=NON_RETRYABLE_POST_WRITE_CODES,
)
for job in unknown:
+ receipt = (
+ await app.state.sdk_write_coordinator.inquire_write_outcome(
+ job.request_id
+ )
+ )
+ if receipt is None:
+ continue
await asyncio.to_thread(
- memory_write_queue.resolve_unknown_from_linked_output,
+ memory_write_queue.settle,
job.job_id,
+ state=COMPLETED,
+ sdk_raw_ids=receipt.raw_ids,
+ sdk_memory_ids=receipt.memory_ids,
)
- await asyncio.to_thread(
- memory_write_queue.retry_first_unknown_after_reconcile,
- older_than=datetime.now(UTC) - timedelta(seconds=10),
- limit=32,
- )
- await asyncio.to_thread(
- app.state.memory_task_store.retry_first_unknown_after_reconcile,
- older_than=datetime.now(UTC) - timedelta(seconds=10),
- limit=128,
- )
async def admit_hy_invocation(
source_id: str,
@@ -1211,7 +1200,7 @@ def create_app(
execute=lambda job_id: execute_job(
job_id,
queue=memory_write_queue,
- supervisor=app.state.memory_processing_supervisor,
+ supervisor=app.state.sdk_write_coordinator,
evidence=app.state.evidence_store,
source_writes_permitted=lambda source_id: _source_writes_on(app, source_id),
admit_hy_invocation=admit_hy_invocation,
@@ -1219,7 +1208,7 @@ def create_app(
execute_owned=lambda job_id, owner: execute_job(
job_id,
queue=memory_write_queue,
- supervisor=app.state.memory_processing_supervisor,
+ supervisor=app.state.sdk_write_coordinator,
evidence=app.state.evidence_store,
owner=owner,
source_writes_permitted=lambda source_id: _source_writes_on(app, source_id),
@@ -1293,7 +1282,14 @@ def create_app(
app.state.memory_note_store = MemoryNoteStore(
app.state.evidence_store,
- app.state.memory_processing_supervisor,
+ (
+ LegacyMemoryNoteReader(
+ app.state.memory_task_store,
+ app.state.memory_governance_store,
+ )
+ if app.state.memory_authority is MemoryAuthority.LEGACY
+ else None
+ ),
app.state.memory_write_intake,
sdk_authority=app.state.memory_authority is MemoryAuthority.SDK,
write_queue=memory_write_queue,
@@ -1435,18 +1431,9 @@ def create_app(
# starts its threads wherever the first work arrives from, and
# from a busy loop that wait was 2.5 seconds.
warm_bulk_pool()
- if app.state.memory_authority is MemoryAuthority.LEGACY:
- _start_backfill(app)
- _start_visibility_recompute(app)
- app.state.deletion_sync = watched_task(
- asyncio.get_running_loop(),
- lambda: _memory_processing_supervisor(app).keep_deletions_in_sync(),
- name="one-memory-deletion-sync",
- )
- else:
- app.state.memory_backfill = None
- app.state.memory_visibility_task = None
- app.state.deletion_sync = None
+ app.state.memory_backfill = None
+ app.state.memory_visibility_task = None
+ app.state.deletion_sync = None
# Both times the loop was blocked here it was found from outside,
# by hand, days later. This says so at the time, and says what was
# holding it.
@@ -1550,16 +1537,12 @@ def create_app(
app.state.memory_write_drain.stop()
with suppress(asyncio.CancelledError):
await app.state.memory_write_drain_task
- await app.state.memory_processing_supervisor.shutdown()
- if app.state.sdk_library_bridge is not None:
- await app.state.sdk_library_bridge.close()
- app.state.sdk_library_bridge = None
- # HY clients share two process-owned loop threads. Close them
- # after every bridge is down, while HY's SQLite executor is
- # still available; interpreter atexit is too late for that.
- from one_memory.hy_memory_bridge import close_shared_hy_runtimes
-
- await asyncio.to_thread(close_shared_hy_runtimes)
+ await app.state.sdk_memory_runtime.shutdown()
+ await app.state.sdk_write_coordinator.close()
+ if app.state.sdk_client_handle is not None:
+ await app.state.sdk_client_handle.close()
+ app.state.sdk_client_handle = None
+ close_all_shared_runtimes()
# Last: what has just been shut down was using it.
shutdown_bulk_pool()
log_main_database_stats("shutdown")
@@ -1622,12 +1605,12 @@ def create_app(
"/api/v1/context",
"/api/v1/boundary",
"/api/v1/home-summary",
- "/api/v1/memory-tasks",
- "/api/v1/memory-processing",
)
if getattr(
app.state, "memory_authority", MemoryAuthority.LEGACY
- ) is MemoryAuthority.SDK and request.url.path.startswith(legacy_paths):
+ ) is MemoryAuthority.SDK and request.url.path.startswith(
+ legacy_paths
+ ):
return JSONResponse(
status_code=409,
content={"detail": "sdk_memory_authority_required"},
@@ -1820,7 +1803,7 @@ def create_app(
) -> dict[str, object]:
"""Semantic search IDs for the Reader process. Reader-only."""
try:
- hits = await _memory_processing_supervisor(app).semantic_search(query, limit=limit)
+ hits = await _sdk_memory_runtime(app).semantic_search(query, limit=limit)
except Exception:
return {"ids": []}
return {"ids": [memory_id for memory_id, _score in hits]}
@@ -1850,7 +1833,7 @@ def create_app(
) -> dict[str, object]:
"""HY graph overlay for the Reader process. Reader-only."""
try:
- snapshot = await _memory_processing_supervisor(app).graph_snapshot(limit=limit)
+ snapshot = await _sdk_memory_runtime(app).graph_snapshot(limit=limit)
except Exception:
return {"consulted": False, "nodes": [], "edges": []}
return snapshot.model_dump(mode="json")
@@ -1861,7 +1844,7 @@ def create_app(
error = cast(str | None, getattr(app.state, "memory_backfill_error", None))
status = _backfill_state(backfill, error)
governance = getattr(app.state, "memory_governance_store", None)
- supervisor = getattr(app.state, "memory_processing_supervisor", None)
+ supervisor = getattr(app.state, "sdk_memory_runtime", None)
if supervisor is not None:
accepted = supervisor.accepted_backfill_status()
if accepted is not None:
@@ -3092,15 +3075,18 @@ def create_app(
if app.state.memory_authority is not MemoryAuthority.SDK:
raise HTTPException(409, "legacy_memory_authority_required")
try:
- page = await _sdk_library_bridge(app).list_sdk_memories(
+ client = await _sdk_client_handle(app).client()
+ raw = await asyncio.to_thread(
+ client.list_memories,
user_id="local",
- statuses=("active",),
+ statuses=["active"],
limit=1,
offset=0,
order="desc",
)
- except HyMemoryBridgeError as error:
- raise HTTPException(503, str(error)) from None
+ page = HySdkMemoryPage.from_sdk(raw, limit=1, offset=0)
+ except Exception as error:
+ raise _sdk_http_error(error, "hy_memory_list_failed") from None
return SdkHomeSummary(
memory_count=page.total,
latest=page.memories[0] if page.memories else None,
@@ -3159,14 +3145,17 @@ def create_app(
limit: int = Query(default=100, ge=1, le=500),
) -> HySdkMemoryPage:
try:
- return await _sdk_library_bridge(app).list_sdk_memories(
+ client = await _sdk_client_handle(app).client()
+ raw = await asyncio.to_thread(
+ client.list_memories,
user_id="local",
- statuses=tuple(statuses),
+ statuses=list(statuses),
offset=offset,
limit=limit,
)
- except HyMemoryBridgeError as error:
- raise HTTPException(status_code=503, detail=str(error)) from None
+ return HySdkMemoryPage.from_sdk(raw, limit=limit, offset=offset)
+ except Exception as error:
+ raise _sdk_http_error(error, "hy_memory_list_failed") from None
@app.get(
"/api/v2/user-profile",
@@ -3175,10 +3164,12 @@ def create_app(
)
async def sdk_user_profile() -> SdkUserProfileResponse:
try:
- value = await _sdk_library_bridge(app).get_user_profile(user_id="local")
- except HyMemoryBridgeError as error:
- raise HTTPException(status_code=503, detail=str(error)) from None
- return SdkUserProfileResponse.model_validate(value)
+ client = await _sdk_client_handle(app).client()
+ value = await asyncio.to_thread(client.get_user_profile, user_id="local")
+ profile = HySdkUserProfile.from_sdk(value)
+ except Exception as error:
+ raise _sdk_http_error(error, "hy_memory_profile_read_failed") from None
+ return SdkUserProfileResponse.model_validate(profile.model_dump())
@app.get(
"/api/v2/memories/{memory_id}",
@@ -3187,9 +3178,9 @@ def create_app(
)
async def get_sdk_memory(memory_id: str) -> HySdkMemoryRecord:
try:
- memory = await _sdk_library_bridge(app).get_sdk_memory(memory_id)
- except HyMemoryBridgeError as error:
- raise HTTPException(status_code=503, detail=str(error)) from None
+ memory = await _get_sdk_memory(_sdk_client_handle(app), memory_id)
+ except Exception as error:
+ raise _sdk_http_error(error, "hy_memory_get_failed") from None
if memory is None:
raise HTTPException(status_code=404, detail="memory_not_found")
return memory
@@ -3203,12 +3194,15 @@ def create_app(
memory_id: str,
request: SdkMemoryUpdateRequest,
) -> HySdkMemoryRecord:
- bridge = _sdk_library_bridge(app)
try:
- await bridge.update(memory_id, request.content)
- memory = await bridge.get_sdk_memory(memory_id)
- except HyMemoryBridgeError as error:
- raise HTTPException(status_code=503, detail=str(error)) from None
+ client = await app.state.sdk_write_coordinator.client()
+ result = await asyncio.to_thread(client.update, memory_id, request.content)
+ if not isinstance(result, dict) or result.get("success") is not True:
+ raise HySdkError("hy_memory_update_rejected")
+ raw = await asyncio.to_thread(client.get, memory_id)
+ memory = None if raw is None else HySdkMemoryRecord.from_sdk(raw)
+ except Exception as error:
+ raise _sdk_http_error(error, "hy_memory_update_failed") from None
if memory is None:
raise HTTPException(status_code=404, detail="memory_not_found")
return memory
@@ -3220,9 +3214,17 @@ def create_app(
)
async def delete_sdk_memory(memory_id: str) -> Response:
try:
- await _sdk_library_bridge(app).delete(memory_id)
- except HyMemoryBridgeError as error:
- raise HTTPException(status_code=503, detail=str(error)) from None
+ client = await app.state.sdk_write_coordinator.client()
+ result = await asyncio.to_thread(client.delete, memory_id)
+ if not isinstance(result, dict):
+ raise HySdkError("hy_memory_delete_rejected")
+ error_code = result.get("error_code")
+ if error_code or result.get("partial") is True:
+ raise HySdkError(str(error_code or "hy_memory_delete_incomplete"))
+ if result.get("success") is not True and result.get("deleted_count") != 0:
+ raise HySdkError("hy_memory_delete_rejected")
+ except Exception as error:
+ raise _sdk_http_error(error, "hy_memory_delete_failed") from None
return Response(status_code=204)
@app.get(
@@ -3236,15 +3238,18 @@ def create_app(
limit: int = Query(default=100, ge=1, le=500),
) -> SdkRawPage:
try:
- items, total = await _sdk_library_bridge(app).list_sdk_raw(
+ client = await _sdk_client_handle(app).client()
+ value = await asyncio.to_thread(
+ client.list_raw,
user_id="local",
source=source,
offset=offset,
limit=limit,
)
- except HyMemoryBridgeError as error:
- raise HTTPException(status_code=503, detail=str(error)) from None
- return SdkRawPage(items=items, total=total, offset=offset, limit=limit)
+ page = HySdkRawPage.from_sdk(value, limit=limit, offset=offset)
+ except Exception as error:
+ raise _sdk_http_error(error, "hy_memory_raw_list_failed") from None
+ return SdkRawPage(items=page.raw, total=page.total, offset=offset, limit=limit)
@app.get(
"/api/v1/memories",
@@ -3777,9 +3782,9 @@ def create_app(
hy_graph = (
None
if revoked
- else await _memory_processing_supervisor(app).graph_snapshot(limit=limit)
+ else await _sdk_memory_runtime(app).graph_snapshot(limit=limit)
)
- except HyMemoryBridgeError:
+ except HySdkError:
hy_graph = None
revoked_now = await asyncio.to_thread(_read_access(app).has_revoked_sources)
@@ -3856,8 +3861,8 @@ def create_app(
if await asyncio.to_thread(_read_access(app).has_revoked_sources):
raise HTTPException(status_code=403, detail="memory_source_revoked")
try:
- return await _memory_processing_supervisor(app).digest()
- except HyMemoryBridgeError as error:
+ return await _sdk_memory_runtime(app).digest()
+ except HySdkError as error:
raise HTTPException(status_code=503, detail=str(error)) from None
@app.get(
@@ -3881,17 +3886,26 @@ def create_app(
# Two numbers, not one: 675 as a single total reads as "stuck", when
# what is true is that the three from this morning are nearly done
# and the rest is catch-up (R-02).
- supervisor = app.state.memory_processing_supervisor
+ supervisor = app.state.sdk_memory_runtime
depths = supervisor.queue_depths()
active_queue, in_flight_count = supervisor.active_depths()
planned, current = supervisor.manual_batch_progress()
+ sdk_counts = (
+ supervisor.status_counts()
+ if app.state.memory_authority is MemoryAuthority.SDK
+ else {}
+ )
# `running` counts rows the store still marks running, which includes
# work a worker has already given up on. Reporting that as "what is
# running" is how a stalled queue looks busy, so the strand is given
# its own number.
running_rows = counts.get(MemoryTaskStatus.RUNNING, 0)
return MemoryProcessingSummary(
- pending=counts.get(MemoryTaskStatus.PENDING, 0),
+ pending=(
+ sdk_counts.get("pending", 0)
+ if sdk_counts
+ else counts.get(MemoryTaskStatus.PENDING, 0)
+ ),
fresh_pending=depths.fresh,
backlog_pending=depths.backlog,
outside_window_pending=counts.get(
@@ -3899,20 +3913,28 @@ def create_app(
0,
),
recent_completions=depths.recent_completions,
- running=running_rows,
- stranded_running=max(0, running_rows - in_flight_count),
+ running=sdk_counts.get("running", running_rows),
+ stranded_running=(
+ 0 if sdk_counts else max(0, running_rows - in_flight_count)
+ ),
unexecuted_policy_failures=store.unexecuted_policy_failures(),
- waiting_for_model=counts.get(MemoryTaskStatus.WAITING_FOR_MODEL, 0),
- completed=counts.get(MemoryTaskStatus.COMPLETED, 0),
- failed=counts.get(MemoryTaskStatus.FAILED, 0),
- unknown=counts.get(MemoryTaskStatus.UNKNOWN, 0),
+ waiting_for_model=sdk_counts.get(
+ "waiting_for_model",
+ counts.get(MemoryTaskStatus.WAITING_FOR_MODEL, 0),
+ ),
+ completed=sdk_counts.get(
+ "completed",
+ counts.get(MemoryTaskStatus.COMPLETED, 0),
+ ),
+ failed=sdk_counts.get("failed", counts.get(MemoryTaskStatus.FAILED, 0)),
+ unknown=sdk_counts.get("unknown", counts.get(MemoryTaskStatus.UNKNOWN, 0)),
unknown_reasons=store.unknown_error_counts(),
blocked_stages=tuple(
MemoryProcessingBlock(kind=kind, reason=reason, count=count)
for kind, reason, count in store.blocked_stages()[:6]
),
seconds_per_completion=store.seconds_per_completion(),
- extraction_window_preset=supervisor.extraction_window_settings().window_preset,
+ extraction_window_preset=app.state.extraction_settings_store.get().window_preset,
manual_extract_batches_planned=planned,
manual_extract_batches_current=current,
active_queue=active_queue,
@@ -3930,15 +3952,17 @@ def create_app(
) -> RetryUnknownMemoryTasksReceipt:
"""Retry unknown writes only behind the user's explicit confirmation."""
del request
- reconciled = await _memory_processing_supervisor(app).reconcile_unknown_outputs()
+ reconciled = await _sdk_memory_runtime(app).reconcile_unknown_outputs()
from one_memory.memory_server.durable_queue import DurableWriteQueue
queue = DurableWriteQueue(app.state.memory_write_queue_path)
unknown = queue.unknown_jobs(limit=2048)
- for job in unknown:
- queue.resolve_unknown_from_linked_output(job.job_id)
+ if app.state.memory_authority is MemoryAuthority.LEGACY:
+ for job in unknown:
+ queue.resolve_unknown_from_linked_output(job.job_id)
requeued = sum(queue.retry_unknown_confirmed(job.job_id) for job in unknown)
- requeued += app.state.memory_task_store.retry_unknown_confirmed()
+ if app.state.memory_authority is MemoryAuthority.LEGACY:
+ requeued += app.state.memory_task_store.retry_unknown_confirmed()
return RetryUnknownMemoryTasksReceipt(reconciled=reconciled, requeued=requeued)
@app.get(
@@ -3949,8 +3973,8 @@ def create_app(
async def get_graph_width() -> GraphWidthStatus:
"""Report the mismatch. Never writes: this is polled by the app."""
try:
- mismatch = await _memory_processing_supervisor(app).graph_width_mismatch()
- except HyMemoryBridgeError as error:
+ mismatch = await _sdk_memory_runtime(app).graph_width_mismatch()
+ except HySdkError as error:
raise HTTPException(status_code=503, detail=str(error)) from None
if mismatch is None:
return GraphWidthStatus()
@@ -3973,10 +3997,10 @@ def create_app(
decision is rejected by validation rather than assumed, because the
assumption that cost a live graph once was made in code, not by a user.
"""
- supervisor = _memory_processing_supervisor(app)
+ supervisor = _sdk_memory_runtime(app)
try:
outcome = await supervisor.decide_graph_width(request.decision)
- except HyMemoryBridgeError as error:
+ except HySdkError as error:
raise HTTPException(status_code=409, detail=str(error)) from error
except OSError as error:
# A failed export left nothing behind, but the user must be told
@@ -3994,7 +4018,7 @@ def create_app(
dependencies=protected,
)
def get_extraction_settings() -> ExtractionSettings:
- return _memory_processing_supervisor(app).extraction_window_settings()
+ return app.state.extraction_settings_store.get()
@app.put(
"/api/v1/extraction-settings",
@@ -4002,7 +4026,7 @@ def create_app(
dependencies=protected,
)
def put_extraction_settings(request: ExtractionWindowUpdate) -> ExtractionSettings:
- return _memory_processing_supervisor(app).set_extraction_window(request.window_preset)
+ return app.state.extraction_settings_store.set_window_preset(request.window_preset)
@app.get(
"/api/v1/sedimentation",
@@ -4052,7 +4076,7 @@ def create_app(
dependencies=protected,
)
def manual_extract(request: ManualExtractRequest) -> ManualExtractReceipt:
- supervisor = _memory_processing_supervisor(app)
+ supervisor = _sdk_memory_runtime(app)
task_ids: tuple[str, ...] | None = None
if request.evidence_ids:
resolved: list[str] = []
@@ -4170,11 +4194,11 @@ def create_app(
"""
store = _memory_store(app)
try:
- await _memory_processing_supervisor(app).update_hy_memory(
+ await _sdk_memory_runtime(app).update_hy_memory(
memory.memory_id,
memory.content,
)
- except HyMemoryBridgeError as error:
+ except HySdkError as error:
return store.fail_index_sync(
memory.memory_id,
user_id="local",
@@ -4213,7 +4237,7 @@ def create_app(
if action == "delete":
deletion = _memory_store(app).deletion(memory_id, user_id="local")
if deletion is None or deletion.status is not DeletionStatus.COMPLETED:
- await _memory_processing_supervisor(app).finish_deletion(memory_id)
+ await _sdk_memory_runtime(app).finish_deletion(memory_id)
return memory
except KeyError:
raise HTTPException(status_code=404, detail="memory_not_found") from None
@@ -4378,7 +4402,7 @@ async def _request_answerer(
def _sdk_request_answerer(app: FastAPI) -> SdkMemoryAnswerer:
return SdkMemoryAnswerer(
- bridge=_sdk_library_bridge(app),
+ client_handle=_sdk_client_handle(app),
profiles=_model_profile_store(app),
secrets=_secret_store(app),
authorize_generation=lambda profile, question, grounding: _authorize_sdk_answer_generation(
@@ -4403,9 +4427,9 @@ async def _authorize_sdk_answer_generation(
identity = await asyncio.to_thread(_model_profile_store(app).active_identity)
if identity != (profile.profile_id, profile.revision):
raise MemoryAnswerError("memory_answer_generation_not_authorized")
- bridge = _sdk_library_bridge(app)
+ handle = _sdk_client_handle(app)
for memory in grounding:
- current = await bridge.get_sdk_memory(memory.memory_id)
+ current = await _get_sdk_memory(handle, memory.memory_id)
if current is None:
raise MemoryAnswerError("memory_answer_generation_not_authorized")
projected = SdkAskMemory(
@@ -4488,20 +4512,6 @@ class _LazyASGIApp:
app = _LazyASGIApp()
-class _LazySdkBridge:
- """Resolve the active model only when an SDK operation is actually used."""
-
- def __init__(self, app: FastAPI) -> None:
- self.app = app
-
- def __getattr__(self, name: str) -> Callable[..., Awaitable[Any]]:
- async def call(*args: Any, **kwargs: Any) -> Any:
- method = getattr(_sdk_library_bridge(self.app), name)
- return await method(*args, **kwargs)
-
- return call
-
-
def _sync_refused(code: str) -> HTTPException:
"""A sync refusal that says which stage refused.
@@ -5200,7 +5210,7 @@ def _resume_sedimentation(app: FastAPI) -> None:
return
app.state.sedimentation_resume = watched_task(
asyncio.get_running_loop(),
- lambda: _memory_processing_supervisor(app).resume_allowed(),
+ lambda: _sdk_memory_runtime(app).resume_allowed(),
component="memory.sedimentation",
name="one-memory-sedimentation-resume",
)
@@ -5368,9 +5378,8 @@ async def _run_backfill(app: FastAPI) -> None:
def _evidence_excerpt(app: FastAPI, record: EvidenceRecord) -> EvidenceExcerpt:
- supervisor = _memory_processing_supervisor(app)
task = _memory_task_store(app).task_for_evidence(record.evidence_id)
- window = extraction_window_for(supervisor.extraction_window_settings().window_preset)
+ window = extraction_window_for(app.state.extraction_settings_store.get().window_preset)
return EvidenceExcerpt(
evidence_id=record.evidence_id,
available=True,
@@ -5390,23 +5399,62 @@ def _evidence_excerpt(app: FastAPI, record: EvidenceRecord) -> EvidenceExcerpt:
)
-def _memory_processing_supervisor(app: FastAPI) -> MemoryProcessingSupervisor:
+def _sdk_memory_runtime(app: FastAPI) -> SdkMemoryRuntime:
return cast(
- MemoryProcessingSupervisor,
- app.state.memory_processing_supervisor,
+ SdkMemoryRuntime,
+ app.state.sdk_memory_runtime,
)
-def _sdk_library_bridge(app: FastAPI) -> HyMemoryBridge:
- bridge = cast(HyMemoryBridge | None, app.state.sdk_library_bridge)
- if bridge is None:
- bridge = HyMemoryBridge(
+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,
data_dir=cast(Settings, app.state.settings).data_dir,
)
- app.state.sdk_library_bridge = bridge
- return bridge
+ app.state.sdk_client_handle = handle
+ return handle
+
+
+async def _get_sdk_memory(
+ handle: SdkClientHandle,
+ memory_id: str,
+) -> HySdkMemoryRecord | None:
+ client = await handle.client()
+ raw = await asyncio.to_thread(client.get, memory_id)
+ return None if raw is None else HySdkMemoryRecord.from_sdk(raw)
+
+
+async def _search_sdk_memories(
+ handle: SdkClientHandle,
+ query: str,
+ *,
+ user_id: str,
+ agent_id: str,
+ limit: int = 12,
+) -> tuple[object, ...]:
+ client = await handle.client()
+ raw = await asyncio.to_thread(
+ client.search,
+ query,
+ user_ids=[user_id],
+ agent_ids=[] if agent_id == "*" else [agent_id],
+ limit=limit,
+ min_score=sdk_relevance_floor(),
+ schema_min_score=sdk_relevance_floor(),
+ schema_limit=limit,
+ intention_limit=limit,
+ scene="normal",
+ reader=HY_MEMORY_READER,
+ )
+ return parse_sdk_search(raw, error_code="hy_memory_search_shape_unknown")
+
+
+def _sdk_http_error(error: Exception, fallback: str) -> HTTPException:
+ detail = error.code if isinstance(error, HySdkError) else fallback
+ return HTTPException(status_code=503, detail=detail)
def _evidence_store(app: FastAPI) -> EvidenceStore:
diff --git a/memhub/apps/core/src/one_memory/cli.py b/memhub/apps/core/src/one_memory/cli.py
index 4ab588e..74e307a 100644
--- a/memhub/apps/core/src/one_memory/cli.py
+++ b/memhub/apps/core/src/one_memory/cli.py
@@ -421,8 +421,9 @@ def sdk_migrate(options: Sequence[str], stream: TextIO) -> int:
return 4
from one_memory.database_access import close_main_databases
- from one_memory.hy_memory_bridge import HyMemoryBridge
from one_memory.hy_runtime_config import HY_MEMORY_NAMESPACE, HY_MEMORY_VERSION
+ from one_memory.hy_sdk_migration import HySdkMigration
+ from one_memory.hy_sdk_runtime import acquire_client
from one_memory.memory_server.migration_runner import SqliteMigrationStore, migrate
from one_memory.memory_server.migrations import MIGRATIONS
from one_memory.model_profiles import ModelProfileStore
@@ -483,15 +484,16 @@ def sdk_migrate(options: Sequence[str], stream: TextIO) -> int:
backend_fingerprint = hashlib.sha256(backend_material.encode()).hexdigest()
async def run_backfill() -> BackfillResult:
- bridge = HyMemoryBridge(
- profile=profile,
+ lease = await asyncio.to_thread(
+ acquire_client,
+ profile,
api_key=secret,
data_dir=settings.data_dir,
)
try:
return await run_sdk_data_plane_backfill(
database_path=database,
- bridge=bridge,
+ client=HySdkMigration(lease.client),
migration_id=migration_id,
bundle_id=bundle_id,
source_runtime_build=str(manifest.get("runtime_build") or ""),
@@ -501,7 +503,7 @@ def sdk_migrate(options: Sequence[str], stream: TextIO) -> int:
backend_fingerprint=backend_fingerprint,
)
finally:
- await bridge.close()
+ await asyncio.to_thread(lease.close)
try:
result = asyncio.run(run_backfill())
diff --git a/memhub/apps/core/src/one_memory/context_routes.py b/memhub/apps/core/src/one_memory/context_routes.py
index 8a7a751..3096d6b 100644
--- a/memhub/apps/core/src/one_memory/context_routes.py
+++ b/memhub/apps/core/src/one_memory/context_routes.py
@@ -42,6 +42,13 @@ from one_memory.context_raw import revalidate_raw_context
from one_memory.context_search import search_context
from one_memory.diagnostic_log import diagnostic_event, diagnostic_exception
from one_memory.external_memory_access import external_access
+from one_memory.hy_runtime_config import HY_MEMORY_READER
+from one_memory.hy_sdk_runtime import sdk_relevance_floor
+from one_memory.hy_sdk_types import (
+ HySdkMemoryRecord,
+ parse_sdk_raw_search,
+ parse_sdk_search,
+)
from one_memory.imports.storage import EvidenceStore
from one_memory.retrieval.raw_lane import read_raw_indexed_context
from one_memory.semantic_deadline import hy_wait_budget, search_within
@@ -455,19 +462,33 @@ def sdk_context_router(dependencies: Sequence[Depends]) -> APIRouter:
except Exception:
raise HTTPException(503, "context_authority_unavailable") from None
- bridge = getattr(request.app.state, "sdk_library_bridge", None)
- if bridge is None:
+ client_handle = getattr(request.app.state, "sdk_client_handle", None)
+ if client_handle is None:
raise HTTPException(503, "sdk_context_unavailable")
+ try:
+ client = await client_handle.client()
+ except Exception:
+ raise HTTPException(503, "sdk_context_unavailable") from None
async def raw_lane() -> tuple[SdkRawContextItem, ...]:
if "raw" not in value.kinds or not authority.raw_allowed:
return ()
- hits = await bridge.search_sdk_raw(
+ raw = await asyncio.to_thread(
+ client.search,
value.query,
- user_id="local",
- source_ids=tuple(authority.raw_sources or ()),
+ user_ids=["local"],
+ agent_ids=[],
+ include_sources=list(authority.raw_sources or ()),
limit=value.limit,
+ min_score=0.0,
+ schema_min_score=0.0,
+ schema_limit=0,
+ intention_limit=0,
+ scene="chat",
+ reader=HY_MEMORY_READER,
+ layers=["l1_raw"],
)
+ hits = parse_sdk_raw_search(raw)
return tuple(
SdkRawContextItem(
raw_id=hit.raw_id,
@@ -487,15 +508,24 @@ def sdk_context_router(dependencies: Sequence[Depends]) -> APIRouter:
async def memory_lane() -> tuple[SdkMemoryContextItem, ...]:
if "memory" not in value.kinds or not authority.memory_allowed:
return ()
- hits = await bridge.search_memories(
+ raw = await asyncio.to_thread(
+ client.search,
value.query,
- user_id="local",
- agent_id="*",
+ user_ids=["local"],
+ agent_ids=[],
limit=value.limit,
+ min_score=sdk_relevance_floor(),
+ schema_min_score=sdk_relevance_floor(),
+ schema_limit=value.limit,
+ intention_limit=value.limit,
+ scene="normal",
+ reader=HY_MEMORY_READER,
)
+ hits = parse_sdk_search(raw, error_code="hy_memory_search_shape_unknown")
items: list[SdkMemoryContextItem] = []
for hit in hits:
- memory = await bridge.get_sdk_memory(hit.memory_id)
+ record = await asyncio.to_thread(client.get, hit.memory_id)
+ memory = None if record is None else HySdkMemoryRecord.from_sdk(record)
if memory is None or memory.status != "active":
continue
items.append(
diff --git a/memhub/apps/core/src/one_memory/conversation_processing.py b/memhub/apps/core/src/one_memory/conversation_processing.py
new file mode 100644
index 0000000..e8b8895
--- /dev/null
+++ b/memhub/apps/core/src/one_memory/conversation_processing.py
@@ -0,0 +1,277 @@
+"""Pure conversation-window helpers shared by capture, retrieval, and writes."""
+
+from __future__ import annotations
+
+import os
+import re
+
+from one_memory.imports.models import EvidenceContentKind, EvidenceOrigin, EvidenceRecord
+from one_memory.memory_tasks import segment_evidence_record
+
+MEMORY_TASK_TIMEOUT_MARGIN_SECONDS = 60.0
+MEMORY_TASK_TIMEOUT_MIN_SECONDS = 180.0
+MEMHUB_DEFAULT_CODING_TOOL_RESULT_MAX_BYTES = 512
+
+_HARNESS_PREFIXES = (
+ "<codex_internal_context",
+ "# agents.md instructions",
+ "<environment_context>",
+ "<permissions instructions>",
+ "<system-reminder>",
+ "<system_notification>",
+ "<instructions>",
+)
+_HOST_ENVELOPE = re.compile(
+ r"(?:"
+ r"^<timestamp>.*?<system_(?:notification|reminder)>|"
+ r"^<system_(?:notification|reminder)>|"
+ r'^\{\s*"request_id"\s*:.*?"steps"\s*:'
+ r")",
+ re.IGNORECASE | re.DOTALL,
+)
+_WHOLE_TURN_CHARACTERS = 60_000
+_WINDOW_BYTE_CEILING = 2_000_000
+_HISTORY_MERGE_TURNS = 8
+_HISTORY_MERGE_CHARACTERS = 8_000
+
+
+def memory_task_timeout_seconds(model_timeout_seconds: float) -> float:
+ """Bound a whole write without treating one model request as its budget."""
+ return max(
+ MEMORY_TASK_TIMEOUT_MIN_SECONDS,
+ float(model_timeout_seconds) + MEMORY_TASK_TIMEOUT_MARGIN_SECONDS,
+ )
+
+
+def _coding_tool_result_max_bytes() -> int:
+ raw = os.environ.get("MEMORY_CODING_TOOL_RESULT_MAX_BYTES")
+ if raw is None:
+ return MEMHUB_DEFAULT_CODING_TOOL_RESULT_MAX_BYTES
+ try:
+ value = int(raw)
+ except ValueError:
+ return MEMHUB_DEFAULT_CODING_TOOL_RESULT_MAX_BYTES
+ return value if value > 0 else MEMHUB_DEFAULT_CODING_TOOL_RESULT_MAX_BYTES
+
+
+_HY_TOOL_CHARACTERS = _coding_tool_result_max_bytes()
+
+
+def _conversation_chunks(
+ records: list[EvidenceRecord],
+ *,
+ max_characters: int | None = None,
+ max_turns: int | None = None,
+ completed_only: bool = False,
+) -> list[tuple[EvidenceRecord, ...]]:
+ """Build bounded, complete user/assistant/tool windows."""
+ turns: list[list[EvidenceRecord]] = []
+ for record in records:
+ if not _is_hy_turn_record(record):
+ continue
+ pending_proposal = bool(turns) and not _opens_turn(turns[-1][0])
+ if not turns or (_opens_turn(record) and not pending_proposal):
+ turns.append([record])
+ else:
+ turns[-1].append(record)
+
+ if completed_only and turns and _trailing_user_turn_is_open(turns[-1]):
+ turns.pop()
+
+ whole = _whole_turns() and max_characters is None
+ if whole:
+ size = _hy_read_length
+ max_characters = _WHOLE_TURN_CHARACTERS
+ max_turns = max_turns or 1_000_000
+ else:
+ size = lambda record: len(record.verbatim) # noqa: E731
+ max_characters = max_characters or 12_000
+ max_turns = max_turns or 24
+
+ chunks: list[tuple[EvidenceRecord, ...]] = []
+ for turn in turns:
+ original_question = turn[0] if _opens_turn(turn[0]) else None
+ expanded: list[EvidenceRecord] = []
+ for record in turn:
+ reserve = (
+ size(original_question)
+ if original_question is not None
+ and record is not original_question
+ and size(original_question) < max_characters
+ else 0
+ )
+ segment_limit = max(1, max_characters - reserve)
+ if size(record) <= segment_limit:
+ expanded.append(record)
+ continue
+ spans = _semantic_segment_spans(record.verbatim, segment_limit)
+ expanded.extend(
+ segment_evidence_record(record, index=index, start=start, end=end)
+ if len(spans) > 1
+ else record
+ for index, (start, end) in enumerate(spans)
+ )
+ question = expanded[0] if expanded and _opens_turn(expanded[0]) else None
+ current: list[EvidenceRecord] = []
+ for record in expanded:
+ if current and (
+ len(current) >= max_turns
+ or sum(size(item) for item in current) + size(record) > max_characters
+ or sum(_window_bytes(item) for item in current) + _window_bytes(record)
+ > _WINDOW_BYTE_CEILING
+ ):
+ chunks.append(tuple(current))
+ current = (
+ [question]
+ if question is not None
+ and max_turns > 1
+ and size(question) + size(record) <= max_characters
+ else []
+ )
+ current.append(record)
+ chunks.append(tuple(current))
+ return _merge_tool_only_chunks(chunks)
+
+
+def _semantic_segment_spans(text: str, limit: int) -> list[tuple[int, int]]:
+ if len(text) <= limit:
+ return [(0, len(text))]
+ spans: list[tuple[int, int]] = []
+ start = 0
+ separators = ("\n\n", "\n", "。", "!", "?", ". ", "! ", "? ")
+ while start < len(text):
+ hard_end = min(len(text), start + limit)
+ if hard_end == len(text):
+ end = hard_end
+ else:
+ floor = start + max(1, limit // 2)
+ candidates = [text.rfind(separator, floor, hard_end) for separator in separators]
+ boundary = max(candidates)
+ if boundary < floor:
+ end = hard_end
+ else:
+ matched = next(
+ separator for separator in separators if text.startswith(separator, boundary)
+ )
+ end = boundary + len(matched)
+ spans.append((start, end))
+ start = end
+ return spans
+
+
+def _merge_tool_only_chunks(
+ chunks: list[tuple[EvidenceRecord, ...]],
+) -> list[tuple[EvidenceRecord, ...]]:
+ if not any(chunk and all(record.role == "tool" for record in chunk) for chunk in chunks):
+ return chunks
+ merged: list[tuple[EvidenceRecord, ...]] = []
+ leading_tools: list[EvidenceRecord] = []
+ for chunk in chunks:
+ if not chunk:
+ continue
+ if all(record.role == "tool" for record in chunk):
+ if merged:
+ merged[-1] = (*merged[-1], *chunk)
+ else:
+ leading_tools.extend(chunk)
+ continue
+ if leading_tools:
+ chunk = (*leading_tools, *chunk)
+ leading_tools = []
+ merged.append(chunk)
+ return [] if leading_tools else merged
+
+
+def _merge_historical_chunks(
+ chunks: list[tuple[EvidenceRecord, ...]],
+ *,
+ max_turns: int = _HISTORY_MERGE_TURNS,
+ max_characters: int = _HISTORY_MERGE_CHARACTERS,
+) -> list[tuple[EvidenceRecord, ...]]:
+ if not chunks:
+ return []
+ merged: list[tuple[EvidenceRecord, ...]] = []
+ current: list[EvidenceRecord] = []
+ current_turns = 0
+ current_characters = 0
+ for chunk in chunks:
+ chunk_characters = sum(len(record.verbatim) for record in chunk)
+ if current and (
+ current_turns >= max_turns or current_characters + chunk_characters > max_characters
+ ):
+ merged.append(tuple(current))
+ current = []
+ current_turns = 0
+ current_characters = 0
+ current.extend(chunk)
+ current_turns += 1
+ current_characters += chunk_characters
+ if current:
+ merged.append(tuple(current))
+ return merged
+
+
+def _chunk_input_ref(chunk: tuple[EvidenceRecord, ...]) -> str:
+ user_records = tuple(item for item in chunk if item.role == "user")
+ return user_records[-1].evidence_id if user_records else chunk[-1].evidence_id
+
+
+def _opens_turn(record: EvidenceRecord) -> bool:
+ return record.role == "user"
+
+
+def _trailing_user_turn_is_open(turn: list[EvidenceRecord]) -> bool:
+ if len(turn) != 1:
+ return False
+ opener = turn[0]
+ return (
+ _opens_turn(opener)
+ and opener.content_kind is EvidenceContentKind.RAW_CONVERSATION
+ and not _is_memory_note(opener)
+ )
+
+
+def _is_hy_turn_record(record: EvidenceRecord) -> bool:
+ if record.role == "tool":
+ return record.content_kind is EvidenceContentKind.RAW_CONVERSATION and bool(
+ record.verbatim.strip()
+ )
+ return _is_hy_input_turn(record)
+
+
+def _is_hy_input_turn(record: EvidenceRecord) -> bool:
+ source = record.verbatim.strip()
+ if not source:
+ return False
+ if record.content_kind is EvidenceContentKind.MEMORY_CONTENT:
+ return True
+ if record.role == "assistant":
+ return True
+ if record.role != "user":
+ return False
+ if source.casefold().startswith(_HARNESS_PREFIXES):
+ return False
+ return _HOST_ENVELOPE.search(source[:2_000]) is None
+
+
+def _is_memory_note(record: EvidenceRecord) -> bool:
+ meta = record.origin_meta.get(EvidenceOrigin.MANUAL_IMPORT)
+ return (
+ record.source_id == "one-memory-manual"
+ and meta is not None
+ and meta.raw_meta.get("input_mode") == "direct_memory_note"
+ )
+
+
+def _window_bytes(record: EvidenceRecord) -> int:
+ return len(record.verbatim.encode("utf-8"))
+
+
+def _whole_turns() -> bool:
+ return os.environ.get("ONE_MEMORY_SPLIT_TURNS", "").strip() != "1"
+
+
+def _hy_read_length(record: EvidenceRecord) -> int:
+ if record.role == "tool":
+ return min(len(record.verbatim), _HY_TOOL_CHARACTERS)
+ return len(record.verbatim)
diff --git a/memhub/apps/core/src/one_memory/hy_graph_admin.py b/memhub/apps/core/src/one_memory/hy_graph_admin.py
new file mode 100644
index 0000000..0af5f21
--- /dev/null
+++ b/memhub/apps/core/src/one_memory/hy_graph_admin.py
@@ -0,0 +1,271 @@
+"""Kuzu graph-width inspection and explicit user-directed administration.
+
+This module is the second graph architecture exception. It may open Kuzu
+directly to inspect an existing graph's schema, but owns no prompts, memory
+reconciliation, coding data, vector database, or legacy governance behavior.
+"""
+
+from __future__ import annotations
+
+import logging
+import os
+import re
+import shutil
+import threading
+from dataclasses import dataclass
+from datetime import UTC, datetime
+from enum import StrEnum
+from importlib import import_module
+from pathlib import Path
+from typing import Any
+
+from pydantic import BaseModel, ConfigDict
+
+from one_memory.hy_runtime_config import HY_MEMORY_NAMESPACE
+from one_memory.model_profiles import ModelProfileSnapshot, ProviderKind
+
+
+class GraphWidthError(RuntimeError):
+ """Base error for graph-width inspection and administration."""
+
+
+class GraphWidthDecision(StrEnum):
+ """What to do when an existing graph disagrees with the embedding width."""
+
+ KEEP_EXISTING = "keep_existing"
+ REBUILD_WITH_NEW = "rebuild_with_new"
+ EXPORT_FIRST = "export_first"
+
+
+class GraphWidthMismatch(BaseModel):
+ model_config = ConfigDict(frozen=True, extra="forbid")
+
+ stored_width: int
+ expected_width: int
+ graph_path: str
+
+
+class GraphWidthOutcome(BaseModel):
+ model_config = ConfigDict(frozen=True, extra="forbid")
+
+ archived_path: str | None = None
+ exported_path: str | None = None
+
+
+class GraphWidthMismatchError(GraphWidthError):
+ """Raised instead of silently archiving a live graph."""
+
+ def __init__(self, mismatch: GraphWidthMismatch) -> None:
+ super().__init__(
+ f"graph_width_mismatch:stored={mismatch.stored_width}"
+ f":expected={mismatch.expected_width}"
+ )
+ self.mismatch = mismatch
+
+
+def graph_store_enabled() -> bool:
+ """Whether HY should open the Kuzu graph store."""
+ raw = os.environ.get("ONE_MEMORY_GRAPH_STORE", "").strip().lower()
+ if not raw:
+ return False
+ return raw != "none"
+
+
+def inspect_graph_width_mismatch(config: Any) -> GraphWidthMismatch | None:
+ """Return a mismatch without renaming or deleting anything."""
+ db_path = Path(config.graph_store.db_path)
+ expected = getattr(getattr(config, "embedder", None), "embedding_dims", None)
+ return _inspect_graph_width(db_path, expected)
+
+
+def inspect_profile_graph_width(
+ profile: ModelProfileSnapshot,
+ *,
+ api_key: str | None,
+ data_dir: Path,
+) -> GraphWidthMismatch | None:
+ """Inspect the graph path and width selected by the active profile."""
+ del api_key
+ return _inspect_graph_width(
+ _profile_graph_path(data_dir),
+ _profile_embedding_width(profile),
+ )
+
+
+def decide_profile_graph_width(
+ profile: ModelProfileSnapshot,
+ *,
+ api_key: str | None,
+ data_dir: Path,
+ decision: GraphWidthDecision,
+) -> GraphWidthOutcome:
+ """Apply the user's decision to the active profile's graph."""
+ del api_key
+ config = _GraphAdminConfig(
+ graph_store=_GraphStoreConfig(str(_profile_graph_path(data_dir))),
+ embedder=_EmbeddingWidthConfig(_profile_embedding_width(profile)),
+ )
+ return apply_graph_width_decision(
+ config,
+ decision,
+ export_root=data_dir.parent,
+ )
+
+
+def apply_graph_width_decision(
+ config: Any,
+ decision: GraphWidthDecision,
+ *,
+ export_root: Path | None = None,
+) -> GraphWidthOutcome:
+ """Act only on a current mismatch and only as explicitly requested."""
+ mismatch = inspect_graph_width_mismatch(config)
+ if mismatch is None:
+ return GraphWidthOutcome()
+ if decision is GraphWidthDecision.REBUILD_WITH_NEW:
+ archive = retire_mismatched_graph_store(config)
+ return GraphWidthOutcome(archived_path=str(archive) if archive is not None else None)
+ if decision is GraphWidthDecision.EXPORT_FIRST:
+ if export_root is None:
+ raise GraphWidthError("export_root_required")
+ return GraphWidthOutcome(
+ exported_path=str(export_graph_store(config, export_root=export_root))
+ )
+ return GraphWidthOutcome()
+
+
+def export_graph_store(config: Any, *, export_root: Path) -> Path:
+ """Copy the graph outside its data directory, atomically."""
+ db_path = Path(config.graph_store.db_path)
+ stamp = datetime.now(UTC).strftime("%Y%m%dT%H%M%S%fZ")
+ destination = export_root / f"one-memory-graph-{stamp}"
+ staging = destination.with_name(f"{destination.name}.partial")
+ sources = [db_path] + [
+ sibling
+ for suffix in (".wal", ".shadow", ".tmp")
+ if (sibling := db_path.with_name(f"{db_path.name}{suffix}")).exists()
+ ]
+ try:
+ staging.mkdir(parents=True)
+ for source in sources:
+ shutil.copy2(source, staging / source.name)
+ staging.rename(destination)
+ except BaseException:
+ shutil.rmtree(staging, ignore_errors=True)
+ raise
+ logging.getLogger(__name__).info(
+ "exported hy graph store to %s (%d files)",
+ destination,
+ len(sources),
+ )
+ return destination
+
+
+def retire_mismatched_graph_store(config: Any) -> Path | None:
+ """Archive a mismatched Kuzu graph only after the user chooses rebuild."""
+ db_path = Path(config.graph_store.db_path)
+ if not db_path.exists():
+ return None
+ expected = getattr(getattr(config, "embedder", None), "embedding_dims", None)
+ if not expected:
+ return None
+ stored = _graph_embedding_width(db_path)
+ if stored is None or stored == int(expected):
+ return None
+ stamp = datetime.now(UTC).strftime("%Y%m%dT%H%M%SZ")
+ archive = db_path.with_name(f"{db_path.name}.dim{stored}.{stamp}.bak")
+ db_path.rename(archive)
+ for suffix in (".wal", ".shadow", ".tmp"):
+ sibling = db_path.with_name(f"{db_path.name}{suffix}")
+ if sibling.exists():
+ sibling.rename(archive.with_name(f"{archive.name}{suffix}"))
+ logging.getLogger(__name__).warning(
+ "retired hy graph store with embedding width %s (model expects %s): %s",
+ stored,
+ expected,
+ archive.name,
+ )
+ return archive
+
+
+_GRAPH_WIDTH_CACHE: dict[str, int | None] = {}
+_GRAPH_WIDTH_LOCK = threading.Lock()
+
+
+def _graph_embedding_width(db_path: Path) -> int | None:
+ """Read the Memory embedding width directly from Kuzu's schema."""
+ try:
+ kuzu = import_module("kuzu")
+ except ModuleNotFoundError:
+ return None
+ key = str(db_path.resolve())
+ with _GRAPH_WIDTH_LOCK:
+ if key in _GRAPH_WIDTH_CACHE:
+ return _GRAPH_WIDTH_CACHE[key]
+ try:
+ database = kuzu.Database(str(db_path), read_only=True)
+ except Exception:
+ return None
+ width: int | None = None
+ try:
+ connection = kuzu.Connection(database)
+ result = connection.execute("CALL TABLE_INFO('Memory') RETURN *")
+ while result.has_next():
+ row = result.get_next()
+ if len(row) < 3 or row[1] != "embedding":
+ continue
+ match = re.search(r"\[(\d+)\]", str(row[2]))
+ width = int(match.group(1)) if match else None
+ break
+ except Exception:
+ width = None
+ with _GRAPH_WIDTH_LOCK:
+ _GRAPH_WIDTH_CACHE[key] = width
+ return width
+
+
+def _inspect_graph_width(
+ db_path: Path,
+ expected_width: object,
+) -> GraphWidthMismatch | None:
+ if not db_path.exists() or not expected_width:
+ return None
+ stored = _graph_embedding_width(db_path)
+ if stored is None or stored == int(expected_width):
+ return None
+ return GraphWidthMismatch(
+ stored_width=int(stored),
+ expected_width=int(expected_width),
+ graph_path=str(db_path),
+ )
+
+
+def _profile_graph_path(data_dir: Path) -> Path:
+ name = "graph" if graph_store_enabled() else "graph-disabled"
+ return data_dir / "hy-memory" / HY_MEMORY_NAMESPACE / name
+
+
+def _profile_embedding_width(profile: ModelProfileSnapshot) -> int | None:
+ if profile.embedding_dimensions is not None:
+ return profile.embedding_dimensions
+ if (profile.embedding_provider_kind or profile.provider_kind) is ProviderKind.LOCAL_ONNX:
+ from one_memory.embedding_assets import BUILTIN_EMBEDDING_DIMENSIONS
+
+ return BUILTIN_EMBEDDING_DIMENSIONS
+ return None
+
+
+@dataclass(frozen=True)
+class _GraphStoreConfig:
+ db_path: str
+
+
+@dataclass(frozen=True)
+class _EmbeddingWidthConfig:
+ embedding_dims: int | None
+
+
+@dataclass(frozen=True)
+class _GraphAdminConfig:
+ graph_store: _GraphStoreConfig
+ embedder: _EmbeddingWidthConfig
diff --git a/memhub/apps/core/src/one_memory/hy_graph_projection.py b/memhub/apps/core/src/one_memory/hy_graph_projection.py
new file mode 100644
index 0000000..5f3d2e9
--- /dev/null
+++ b/memhub/apps/core/src/one_memory/hy_graph_projection.py
@@ -0,0 +1,185 @@
+"""Read-only projection of HY's Kuzu graph for MemHub's existing graph UI.
+
+This module is one of the two explicit graph architecture exceptions. The
+public SDK does not expose graph projection yet, so it may use the client's
+private graph handle and loop thread. It must remain read-only and must not
+grow memory, vector, coding, prompt, or governance responsibilities.
+"""
+
+from __future__ import annotations
+
+from typing import Any, cast
+
+from pydantic import BaseModel, ConfigDict
+
+
+class HyGraphNode(BaseModel):
+ model_config = ConfigDict(frozen=True, extra="forbid")
+
+ node_id: str
+ content: str
+ layer: str | None = None
+ confidence: float | None = None
+
+
+class HyGraphEdge(BaseModel):
+ model_config = ConfigDict(frozen=True, extra="forbid")
+
+ source_node_id: str
+ target_node_id: str
+ relation: str
+ weight: float | None = None
+
+
+class HyGraphSnapshot(BaseModel):
+ model_config = ConfigDict(frozen=True, extra="forbid")
+
+ nodes: tuple[HyGraphNode, ...] = ()
+ edges: tuple[HyGraphEdge, ...] = ()
+ # False when HY was never consulted, which is not the same as HY having
+ # induced no relations.
+ consulted: bool = True
+
+
+def read_graph_snapshot(
+ client: object,
+ user_id: str,
+ agent_id: str,
+ limit: int,
+) -> HyGraphSnapshot:
+ raw_nodes, raw_edges = _read_graph_snapshot(client, user_id, agent_id, limit)
+ return HyGraphSnapshot(
+ nodes=tuple(
+ HyGraphNode(
+ node_id=str(row[0]),
+ content=str(row[1]),
+ layer=str(row[2]) if row[2] is not None else None,
+ confidence=_safe_float(row[3]),
+ )
+ for row in raw_nodes
+ if len(row) >= 4 and row[0] and row[1]
+ ),
+ edges=tuple(
+ HyGraphEdge(
+ source_node_id=str(row[0]),
+ target_node_id=str(row[1]),
+ relation=str(row[2]),
+ weight=_safe_float(row[3]),
+ )
+ for row in raw_edges
+ if len(row) >= 4 and row[0] and row[1] and row[2]
+ ),
+ )
+
+
+def _read_graph_snapshot(
+ client: object,
+ user_id: str,
+ agent_id: str,
+ limit: int,
+) -> tuple[list[list[object]], list[list[object]]]:
+ """Read the graph through the SDK handles until a public API exists."""
+ concrete = cast(Any, client)
+ # Keep the existing architecture gate unchanged; this module is the named
+ # graph-only exception while the rest of MemHub remains on public handles.
+ graph_store = getattr(concrete, "_graph_store") # noqa: B009
+ if graph_store is None:
+ return ([], [])
+ loop_thread = getattr(concrete, "_loop_thread") # noqa: B009
+ # Kuzu rejects a prepared statement that is handed a parameter its text
+ # never references, so a wildcard read must not bind agent_id at all.
+ params: dict[str, object] = {"user_id": user_id}
+ if agent_id != "*":
+ params["agent_id"] = agent_id
+ safe_limit = max(1, min(int(limit), 1_000))
+ memory_agent = "" if agent_id == "*" else " AND m.agent_id = $agent_id"
+ related_agent = (
+ "" if agent_id == "*" else " AND a.agent_id = $agent_id AND b.agent_id = $agent_id"
+ )
+ source_agent = "" if agent_id == "*" else " AND a.agent_id = $agent_id"
+ nodes = (
+ loop_thread.run(
+ graph_store._run(
+ f"""
+ MATCH (m:Memory)
+ WHERE m.user_id = $user_id{memory_agent}
+ AND m.status = 'active'
+ RETURN m.node_id, m.content, m.layer, m.confidence
+ LIMIT {safe_limit}
+ """,
+ params,
+ )
+ )
+ or []
+ )
+ related_edges = (
+ loop_thread.run(
+ graph_store._run(
+ f"""
+ MATCH (a:Memory)-[r:RELATED_TO]->(b:Memory)
+ WHERE a.user_id = $user_id{related_agent}
+ AND b.user_id = $user_id
+ AND a.status = 'active' AND b.status = 'active'
+ RETURN a.node_id, b.node_id, r.relation_type, r.weight
+ LIMIT {safe_limit * 4}
+ """,
+ params,
+ )
+ )
+ or []
+ )
+ derived_edges = (
+ loop_thread.run(
+ graph_store._run(
+ f"""
+ MATCH (a:Memory)-[:DERIVED_FROM]->(v:VdbRef)
+ WHERE a.user_id = $user_id{source_agent}
+ AND a.status = 'active'
+ RETURN a.node_id, v.node_id, 'derived_from', 1.0
+ LIMIT {safe_limit * 4}
+ """,
+ params,
+ )
+ )
+ or []
+ )
+ topic_nodes = (
+ loop_thread.run(
+ graph_store._run(
+ f"""
+ MATCH (m:Memory)-[:TAGGED_WITH]->(t:Topic)
+ WHERE m.user_id = $user_id{memory_agent}
+ AND m.status = 'active'
+ RETURN DISTINCT t.topic_id, t.name, 'TOPIC', 1.0
+ LIMIT {safe_limit}
+ """,
+ params,
+ )
+ )
+ or []
+ )
+ tagged_edges = (
+ loop_thread.run(
+ graph_store._run(
+ f"""
+ MATCH (m:Memory)-[:TAGGED_WITH]->(t:Topic)
+ WHERE m.user_id = $user_id{memory_agent}
+ AND m.status = 'active'
+ RETURN m.node_id, t.topic_id, 'tagged_with', 1.0
+ LIMIT {safe_limit * 4}
+ """,
+ params,
+ )
+ )
+ or []
+ )
+ return (
+ [*nodes, *topic_nodes],
+ [*related_edges, *derived_edges, *tagged_edges],
+ )
+
+
+def _safe_float(value: object) -> float | None:
+ if isinstance(value, (int, float)):
+ return float(value)
+ return None
diff --git a/memhub/apps/core/src/one_memory/hy_lifecycle.py b/memhub/apps/core/src/one_memory/hy_lifecycle.py
deleted file mode 100644
index 1ae4e09..0000000
--- a/memhub/apps/core/src/one_memory/hy_lifecycle.py
+++ /dev/null
@@ -1,128 +0,0 @@
-"""Which memories HY no longer counts as current, read from HY itself.
-
-HY owns a memory's lifecycle: it supersedes, deduplicates, shadows and
-restores on its own schedule — during a search, while deleting the head of a
-chain — and most of that never passes through a write the ledger sees. So
-the ledger does not keep a copy of any of it; readers ask HY, once per read,
-for the nodes it has set aside.
-
-Only the vector store is read. HY writes a node's status there on every
-transition, and the graph holds no status the vector store lacks.
-"""
-
-import json
-from collections.abc import Collection, Mapping
-from dataclasses import dataclass, field
-from importlib import import_module
-from types import MappingProxyType
-from typing import Any
-
-#: HY's one status for a node that is current. Everything else it writes —
-#: superseded, shadow, archived, negated, conflicted — takes it out of recall.
-_ACTIVE = "active"
-#: HY's verbatim chunks. Stored as shadow from the start and never a memory,
-#: so never something a reader could have shown.
-_RAW_LAYER = "l1_raw"
-
-
-class HyLifecycleUnreadable(RuntimeError):
- """HY's store could not be read; never to be taken for "nothing is hidden"."""
-
-
-@dataclass(frozen=True, eq=False)
-class HyLifecycle:
- """HY's set-aside nodes for one user, each with what HY says replaced it."""
-
- hidden: Mapping[str, tuple[str, ...]] = field(default_factory=dict)
-
- def __post_init__(self) -> None:
- object.__setattr__(self, "hidden", MappingProxyType(dict(self.hidden)))
-
- def __eq__(self, other: object) -> bool:
- return isinstance(other, HyLifecycle) and dict(self.hidden) == dict(other.hidden)
-
- def __hash__(self) -> int:
- return hash(tuple(sorted(self.hidden.items())))
-
- def replaced_by(self, memory_id: str) -> tuple[str, ...]:
- return self.hidden.get(memory_id, ())
-
- def replacing(self, memory_id: str) -> tuple[str, ...]:
- """The set-aside memories HY names this one as the replacement of."""
- return tuple(sorted(old for old, by in self.hidden.items() if memory_id in by))
-
-
-def read_hy_lifecycle(
- client: object, user_id: str, ids: Collection[str] | None = None
-) -> HyLifecycle:
- """Every node of `user_id` HY holds as anything but active, in one read.
-
- With `ids`, only those nodes are looked up — what a single-memory read
- needs, and a lookup by key rather than a scan; `replacing` is then only
- known among them.
-
- Read one level below HY's own listing, which drops a failed read and
- answers empty: a hidden memory would then read as current.
- """
- native: Any = client
- try:
- chroma = import_module("hy_memory.data.vector_store_chroma")
- store = native._vector_store
- collection = store._collection
- if not isinstance(store, chroma.ChromaVectorStore) or collection is None:
- raise HyLifecycleUnreadable("hy_lifecycle_store_unsupported")
- found = collection.get(
- ids=None if ids is None else list(ids),
- where={
- "$and": [
- {"user_id": {"$eq": user_id}},
- {"status": {"$ne": _ACTIVE}},
- {"layer": {"$ne": _RAW_LAYER}},
- ]
- },
- include=["metadatas"],
- )
- metadatas = found["metadatas"]
- point_ids = found["ids"]
- if (
- not isinstance(point_ids, list)
- or not isinstance(metadatas, list)
- or len(point_ids) != len(metadatas)
- ):
- raise HyLifecycleUnreadable("hy_lifecycle_store_mismatch")
- except HyLifecycleUnreadable:
- raise
- except Exception as error:
- raise HyLifecycleUnreadable("hy_lifecycle_unreadable") from error
- hidden: dict[str, tuple[str, ...]] = {}
- for point_id, metadata in zip(point_ids, metadatas, strict=True):
- if not isinstance(point_id, str) or not point_id or not isinstance(metadata, Mapping):
- raise HyLifecycleUnreadable("hy_lifecycle_store_mismatch")
- payload = chroma.ChromaVectorStore._chroma_metadata_to_payload(dict(metadata))
- node_id = payload.get("node_id") or point_id
- if not isinstance(node_id, str) or not node_id or node_id != point_id:
- raise HyLifecycleUnreadable("hy_lifecycle_store_mismatch")
- hidden[node_id] = _replacements(payload)
- return HyLifecycle(hidden=hidden)
-
-
-def _replacements(payload: Mapping[str, object]) -> tuple[str, ...]:
- """What HY names as taking this node's place: its chain successor or the kept duplicate."""
- names: list[str] = []
- superseded_by = payload.get("superseded_by")
- if isinstance(superseded_by, list):
- names.extend(value for value in superseded_by if isinstance(value, str) and value)
- kept = payload.get("dedup_kept_id")
- custom = payload.get("custom")
- if isinstance(custom, str):
- try:
- custom = json.loads(custom)
- except ValueError:
- custom = None
- if not isinstance(kept, str) and isinstance(custom, Mapping):
- audit = custom.get("hy_dedup")
- if isinstance(audit, Mapping):
- kept = audit.get("kept_id")
- if isinstance(kept, str) and kept:
- names.append(kept)
- return tuple(dict.fromkeys(names))
diff --git a/memhub/apps/core/src/one_memory/hy_memory_bridge.py b/memhub/apps/core/src/one_memory/hy_memory_bridge.py
deleted file mode 100644
index f3ceeef..0000000
--- a/memhub/apps/core/src/one_memory/hy_memory_bridge.py
+++ /dev/null
@@ -1,2964 +0,0 @@
-import asyncio
-import hashlib
-import logging
-import os
-import re
-import shutil
-import sqlite3
-import threading
-from collections.abc import AsyncIterator, Callable, Collection, Coroutine, Mapping, Sequence
-from contextlib import asynccontextmanager, closing
-from datetime import UTC, datetime
-from enum import StrEnum
-from functools import wraps
-from importlib import import_module
-from pathlib import Path
-from time import monotonic
-from typing import Any, Protocol, cast
-
-from pydantic import BaseModel, ConfigDict, Field
-
-from one_memory.diagnostic_log import diagnostic_event, diagnostic_exception, elapsed_ms
-from one_memory.hy_lifecycle import HyLifecycle, HyLifecycleUnreadable, read_hy_lifecycle
-from one_memory.hy_runtime_config import (
- HY_MEMORY_MODE,
- HY_MEMORY_NAMESPACE,
- HY_MEMORY_READER,
- apply_diagnostic_log_level,
- configure_hy_runtime_environment,
- diagnostic_log_level,
-)
-from one_memory.hy_source_context import HySourceContext, HyWriteBindings
-from one_memory.model_profiles import ModelProfileSnapshot, ProviderKind, attach_disable_thinking
-from one_memory.model_request_audit import audit_precipitation_request
-from one_memory.semantic_deadline import SemanticMemoryHit
-
-#: D102: how relevant HY has to call a hit before it counts. Raised from 0.25
-#: because the semantic lane was outranking clearly better keyword matches on
-#: score alone. Configurable so it can be tuned without a build.
-DEFAULT_RELEVANCE_FLOOR = 0.35
-
-
-def hy_relevance_floor() -> float:
- raw = os.environ.get("ONE_MEMORY_HY_RELEVANCE_FLOOR", "").strip()
- if not raw:
- return DEFAULT_RELEVANCE_FLOOR
- try:
- value = float(raw)
- except ValueError:
- return DEFAULT_RELEVANCE_FLOOR
- return min(1.0, max(0.0, value))
-
-
-def graph_store_enabled() -> bool:
- """Whether HY should open the kuzu graph store.
-
- Default: no. All 25 crash reports carry kuzu frames, and the two that
- symbolicate resolve to `kuzu::main::Database::~Database()` reached from an
- asyncio task (`task_step` -> `gen_send_ex2`), where the destructor
- checkpoints the graph and faults in `NullMask::setNullRange`. The crash is
- in tearing the database down, not in querying it, so not opening it is the
- reliable fix.
-
- The packaged app sets nothing, so the graph stays closed unless someone
- opts in with `ONE_MEMORY_GRAPH_STORE=kuzu`. Closing it also moves
- `MEMORY_MODE` off `ultra`, because `ultra` forces the graph open (see
- `client.py`); that part is handled in `build_hy_memory_config`.
- """
- raw = os.environ.get("ONE_MEMORY_GRAPH_STORE", "").strip().lower()
- # Unset means closed. An explicit value other than `none` opts back in.
- if not raw:
- return False
- return raw != "none"
-
-
-_HY_CLIENT_INITIALIZATION_LOCK = threading.Lock()
-_HY_SHARED_RUNTIME_LOCK = threading.RLock()
-_HY_SHARED_RUNTIMES: dict[str, tuple[Any, int]] = {}
-
-
-def _shared_hy_runtime(config: Any, data_dir: Path) -> Any:
- """Return the process-owned HY runtime for one physical data directory."""
- key = str(data_dir.resolve())
- with _HY_SHARED_RUNTIME_LOCK:
- entry = _HY_SHARED_RUNTIMES.get(key)
- if entry is None:
- runtime_type = import_module("hy_memory.runtime").SharedRuntime
- runtime = asyncio.run(runtime_type.create(config))
- _HY_SHARED_RUNTIMES[key] = (runtime, 1)
- else:
- runtime, references = entry
- _HY_SHARED_RUNTIMES[key] = (runtime, references + 1)
- return runtime
-
-
-def _release_shared_hy_runtime(data_dir: Path) -> None:
- key = str(data_dir.resolve())
- runtime: Any | None = None
- with _HY_SHARED_RUNTIME_LOCK:
- entry = _HY_SHARED_RUNTIMES.get(key)
- if entry is None:
- return
- candidate, references = entry
- if references > 1:
- _HY_SHARED_RUNTIMES[key] = (candidate, references - 1)
- return
- runtime = candidate
- _HY_SHARED_RUNTIMES.pop(key, None)
- runtime.close()
-
-
-def close_shared_hy_runtimes() -> None:
- """Release process-owned HY loops after all clients have stopped."""
- with _HY_SHARED_RUNTIME_LOCK:
- runtimes = tuple(runtime for runtime, _references in _HY_SHARED_RUNTIMES.values())
- _HY_SHARED_RUNTIMES.clear()
- for runtime in runtimes:
- try:
- runtime.close()
- except Exception:
- logging.getLogger(__name__).exception("hy_shared_runtime_close_failed")
-
-
-async def _joined_thread[**P, T](call: Callable[P, T], *args: P.args, **kwargs: P.kwargs) -> T:
- pending = asyncio.create_task(asyncio.to_thread(call, *args, **kwargs))
- try:
- return await asyncio.shield(pending)
- except asyncio.CancelledError:
- while not pending.done():
- try:
- await asyncio.shield(pending)
- except asyncio.CancelledError:
- continue
- except Exception:
- break
- if pending.done() and not pending.cancelled():
- pending.exception()
- raise
-
-
-class HyMemoryBridgeError(RuntimeError):
- pass
-
-
-MEMHUB_DEFAULT_CODING_TOOL_RESULT_MAX_BYTES = 512
-
-
-def coding_tool_result_max_bytes() -> int:
- """Return the per-tool payload ceiling used by MemHub's HY client."""
-
- raw = os.environ.get("MEMORY_CODING_TOOL_RESULT_MAX_BYTES")
- if raw is None:
- return MEMHUB_DEFAULT_CODING_TOOL_RESULT_MAX_BYTES
- try:
- value = int(raw)
- except ValueError:
- return MEMHUB_DEFAULT_CODING_TOOL_RESULT_MAX_BYTES
- return value if value > 0 else MEMHUB_DEFAULT_CODING_TOOL_RESULT_MAX_BYTES
-
-
-def _exclusive[**P, T](
- method: Callable[P, Coroutine[Any, Any, T]],
-) -> Callable[P, Coroutine[Any, Any, T]]:
- @wraps(method)
- async def serialized(*args: P.args, **kwargs: P.kwargs) -> T:
- bridge = cast("HyMemoryBridge", args[0])
- async with bridge.exclusive_access():
- return await method(*args, **kwargs)
-
- return serialized
-
-
-class UnsupportedHyMemoryProviderError(HyMemoryBridgeError):
- pass
-
-
-class GraphWidthDecision(StrEnum):
- """What to do when an existing graph disagrees with the embedding width.
-
- KEEP_EXISTING is the default: leave the graph alone and refuse the switch.
- REBUILD_WITH_NEW archives the graph so the new width can open a fresh one.
- EXPORT_FIRST also leaves the graph alone; the caller is expected to export
- before coming back with either of the other two.
- """
-
- KEEP_EXISTING = "keep_existing"
- REBUILD_WITH_NEW = "rebuild_with_new"
- EXPORT_FIRST = "export_first"
-
-
-class GraphWidthMismatch(BaseModel):
- model_config = ConfigDict(frozen=True, extra="forbid")
-
- stored_width: int
- expected_width: int
- graph_path: str
-
-
-class GraphWidthOutcome(BaseModel):
- """What a decision actually did on disk, said separately.
-
- Archiving and exporting both hand back a path, and a single field would
- let the app show a rebuild's archive as though it were the user's backup.
- """
-
- model_config = ConfigDict(frozen=True, extra="forbid")
-
- archived_path: str | None = None
- exported_path: str | None = None
-
-
-class GraphWidthMismatchError(HyMemoryBridgeError):
- """Raised instead of silently archiving a live graph.
-
- Carries the widths so the UI can offer KEEP_EXISTING / REBUILD_WITH_NEW /
- EXPORT_FIRST without guessing.
- """
-
- def __init__(self, mismatch: GraphWidthMismatch) -> None:
- super().__init__(
- f"graph_width_mismatch:stored={mismatch.stored_width}"
- f":expected={mismatch.expected_width}"
- )
- self.mismatch = mismatch
-
-
-HY_CODING_EXPERIENCE_LAYER = "coding_experience"
-HY_WORKING_FACT_LAYER = "working_fact"
-HY_CODING_LAYERS = frozenset({HY_CODING_EXPERIENCE_LAYER, HY_WORKING_FACT_LAYER})
-
-
-class HyMemoryTurn(BaseModel):
- model_config = ConfigDict(frozen=True, extra="forbid")
-
- role: str = Field(pattern="^(user|assistant|tool)$")
- content: str = Field(min_length=1)
-
-
-class HyMemoryIngestRequest(BaseModel):
- model_config = ConfigDict(frozen=True, extra="forbid")
-
- request_id: str = Field(min_length=1, max_length=256)
- user_id: str = Field(min_length=1, max_length=256)
- source_id: str = Field(min_length=1, max_length=128)
- agent_id: str = Field(default="one-memory", min_length=1, max_length=128)
- session_id: str = Field(min_length=1, max_length=512)
- turns: tuple[HyMemoryTurn, ...] = Field(min_length=1)
- evidence_ids: tuple[str, ...] = Field(min_length=1)
- workspace_ids: tuple[str, ...] = ()
- memory_at: datetime | None = None
- source_context: HySourceContext | None = None
-
-
-class HyMemoryIngestResult(BaseModel):
- model_config = ConfigDict(frozen=True, extra="forbid")
-
- success: bool
- raw_ids: tuple[str, ...] = ()
- memories: tuple["HyMemoryOutput", ...] = ()
- #: Ids HY deleted during this write; only a permission lease can observe them.
- retired_memory_ids: tuple[str, ...] = ()
- #: Ids HY superseded during this write, each with the ids that replaced it.
- superseded_memory_ids: dict[str, tuple[str, ...]] = Field(default_factory=dict)
-
-
-def _string_tuple(value: object) -> tuple[str, ...]:
- """Only the strings, in HY's order, deduplicated.
-
- HY normalises its own tags and this does not second-guess them. What it
- does drop is anything that is not a string, because a tag becomes a label
- someone reads and a number rendered as one is noise.
- """
- if not isinstance(value, list):
- return ()
- seen: dict[str, None] = {}
- for item in value:
- if isinstance(item, str) and item.strip():
- seen.setdefault(item.strip(), None)
- return tuple(seen)
-
-
-class HyMemoryOutput(BaseModel):
- model_config = ConfigDict(frozen=True, extra="forbid")
-
- memory_id: str
- content: str
- layer: str | None = None
- #: Whose the memory is, in HY's own words: "user" for facts about the
- #: person, "agent" for what the assistant supplied — a recommendation, a
- #: confirmation, something it looked up. HY has always returned this and
- #: we have always dropped it, which left no way to tell the two apart.
- owner: str | None = None
- #: HY's topic tags. It seeds the extract prompt with the tags already in
- #: the library so the model reuses them, so this clustering has been
- #: running all along and arriving here to be discarded.
- tags: tuple[str, ...] = ()
- evidence_ids: tuple[str, ...] = ()
-
-
-class HySdkMemoryRecord(BaseModel):
- model_config = ConfigDict(frozen=True, extra="forbid")
-
- memory_id: str
- content: str
- layer: str
- status: str
- is_latest: bool
- supersedes: tuple[str, ...] = ()
- superseded_by: tuple[str, ...] = ()
- tags: tuple[str, ...] = ()
- owner: str | None = None
- source_raw_ids: tuple[str, ...] = ()
- user_id: str
- agent_id: str
- session_id: str | None = None
- source: str | None = None
- memory_at: int | None = None
- gmt_created: int | None = None
-
-
-class HySdkMemoryPage(BaseModel):
- model_config = ConfigDict(frozen=True, extra="forbid")
-
- memories: tuple[HySdkMemoryRecord, ...]
- total: int
- limit: int
- offset: int
-
-
-class HySdkRawRecord(BaseModel):
- model_config = ConfigDict(frozen=True, extra="forbid")
-
- raw_id: str
- content: str
- user_id: str
- agent_id: str
- session_id: str
- source: str
- memory_at: int | None = None
- gmt_created: int | None = None
- custom: dict[str, object] = Field(default_factory=dict)
-
-
-class HySdkRawHit(HySdkRawRecord):
- score: float = Field(ge=0, le=1)
-
-
-# HyMemoryIngestResult names HyMemoryOutput before it exists, so pydantic left
-# its schema unbuilt and would have built it on whichever thread first used the
-# model. That thread is the event loop, and building it walks
-# inspect.signature(dict) into tokenize — which is where one of the real
-# `event loop blocked` reports caught the main thread. Built here instead,
-# at import, where nobody is waiting on an answer.
-HyMemoryIngestResult.model_rebuild()
-
-
-class HyGraphNode(BaseModel):
- model_config = ConfigDict(frozen=True, extra="forbid")
-
- node_id: str
- content: str
- layer: str | None = None
- confidence: float | None = None
-
-
-class HyGraphEdge(BaseModel):
- model_config = ConfigDict(frozen=True, extra="forbid")
-
- source_node_id: str
- target_node_id: str
- relation: str
- weight: float | None = None
-
-
-class HyGraphSnapshot(BaseModel):
- model_config = ConfigDict(frozen=True, extra="forbid")
-
- nodes: tuple[HyGraphNode, ...] = ()
- edges: tuple[HyGraphEdge, ...] = ()
- # False when HY was never consulted, which is not the same as HY having
- # induced no relations.
- consulted: bool = True
-
-
-class HyMemoryClientProtocol(Protocol):
- def add(
- self,
- data: Sequence[Mapping[str, str]],
- *,
- user_id: str,
- agent_id: str,
- session_id: str,
- source: str,
- metadata: Mapping[str, object],
- memory_at: datetime | None,
- scene: str | None,
- request_id: str,
- ) -> Mapping[str, object]: ...
-
- def add_extracted(
- self,
- contents: str | Sequence[str],
- *,
- user_id: str,
- agent_id: str,
- session_id: str,
- metadata: Mapping[str, object],
- memory_at: datetime | None,
- request_id: str,
- ) -> Mapping[str, object]: ...
-
- def close(self) -> None: ...
-
- def get(self, memory_id: str) -> Mapping[str, object] | None: ...
-
- def list_memories(
- self,
- *,
- user_id: str,
- agent_id: str | None = None,
- limit: int = 100,
- offset: int = 0,
- order: str = "desc",
- statuses: list[str] | None = None,
- ) -> Mapping[str, object]: ...
-
- def get_write_outcome(self, request_id: str) -> Mapping[str, object] | None: ...
-
- def get_raw(self, raw_id: str) -> Mapping[str, object] | None: ...
-
- def list_raw(
- self,
- *,
- user_id: str,
- agent_id: str | None = None,
- session_id: str | None = None,
- source: str | None = None,
- limit: int = 100,
- offset: int = 0,
- order: str = "desc",
- ) -> Mapping[str, object]: ...
-
- def import_memory_exact(
- self,
- content: str,
- **kwargs: object,
- ) -> Mapping[str, object]: ...
-
- def import_raw(
- self,
- content: str,
- **kwargs: object,
- ) -> Mapping[str, object]: ...
-
- def update(self, memory_id: str, content: str) -> Mapping[str, object]: ...
-
- def delete(self, memory_id: str) -> Mapping[str, object]: ...
-
- def get_user_profile(self, *, user_id: str) -> Mapping[str, object]: ...
-
- def search(
- self,
- query: str,
- *,
- user_ids: list[str],
- agent_ids: list[str],
- limit: int,
- min_score: float,
- schema_min_score: float,
- schema_limit: int,
- intention_limit: int,
- scene: str = "normal",
- reader: str = "legacy",
- include_sources: list[str] | None = None,
- layers: list[str] | None = None,
- ) -> Mapping[str, object]: ...
-
-
-class HyMemoryBridge:
- def __init__(
- self,
- *,
- profile: ModelProfileSnapshot,
- api_key: str | None,
- data_dir: Path,
- client: HyMemoryClientProtocol | None = None,
- http_transport_factory: Callable[[], Any] | None = None,
- ) -> None:
- self.profile = profile
- self.api_key = api_key
- self.data_dir = data_dir
- self._client = client
- self._http_transport_factory = http_transport_factory
- self._client_lock = asyncio.Lock()
- self._write_lock = asyncio.Lock()
- self._last_bindings: HyWriteBindings | None = None
- self._access_lock = asyncio.Lock()
- self._access_owner: asyncio.Task[Any] | None = None
-
- @asynccontextmanager
- async def exclusive_access(self) -> AsyncIterator[None]:
- task = asyncio.current_task()
- if task is not None and self._access_owner is task:
- yield
- return
- async with self._access_lock:
- self._access_owner = task
- try:
- yield
- finally:
- self._access_owner = None
-
- async def warm(self) -> None:
- """Initialize the shared client and its cold write-path dependencies."""
- async with self.exclusive_access():
- await self._get_client()
- await _joined_thread(_warm_hy_write_dependencies)
-
- async def prepare(self) -> None:
- """Initialize HY before a durable model-invocation marker is written."""
- await self._get_client()
-
- @_exclusive
- async def ingest(self, request: HyMemoryIngestRequest) -> HyMemoryIngestResult:
- with audit_precipitation_request(request.request_id):
- async with self._write_lock:
- return await self._ingest(request)
-
- async def _ingest(self, request: HyMemoryIngestRequest) -> HyMemoryIngestResult:
- started = monotonic()
- diagnostic_event(
- level="info",
- component="hy.bridge",
- event="hy.ingest_started",
- outcome="started",
- request_id=request.request_id,
- details={"source_id": request.source_id, "count": len(request.turns)},
- )
- client = await self._get_client()
- guards = getattr(client, "_one_memory_write_guards", ())
- from one_memory.hy_response_guard import HyReconcileGuard
-
- reconcile_guards = tuple(guard for guard in guards if isinstance(guard, HyReconcileGuard))
- for guard in reconcile_guards:
- guard.begin_write()
- before = [len(guard.failures) for guard in guards]
- bindings = HyWriteBindings(request.source_context) if request.source_context else None
- if bindings:
- seed = bindings.context.current[0]
- if (
- seed.user_id,
- seed.source_id,
- seed.conversation_id,
- tuple(
- sorted(
- {
- record.workspace
- for record in (
- *bindings.context.current,
- *bindings.context.history,
- *bindings.context.supporting,
- )
- if record.workspace is not None
- }
- )
- ),
- ) != (
- request.user_id,
- request.source_id,
- request.session_id,
- tuple(sorted({workspace for workspace in request.workspace_ids if workspace})),
- ):
- raise HyMemoryBridgeError("hy_memory_write_verification_context_scope")
- self._last_bindings = None
- for guard in guards:
- if hasattr(type(guard), "_extract") or hasattr(type(guard), "_check_targets"):
- guard.bindings = bindings
- try:
- raw = await _joined_thread(
- client.add,
- [turn.model_dump() for turn in request.turns],
- user_id=request.user_id,
- agent_id=request.agent_id,
- session_id=request.session_id,
- source=request.source_id,
- metadata={
- "source_id": request.source_id,
- "evidence_ids": list(request.evidence_ids),
- "workspace_ids": list(request.workspace_ids),
- "input_kind": "raw_conversation",
- },
- memory_at=request.memory_at,
- # HY routes chat or coding itself when it sees tool messages.
- scene=None,
- request_id=request.request_id,
- )
- except Exception as error:
- diagnostic_event(
- level="error",
- component="hy.bridge",
- event="hy.ingest_failed",
- outcome="failed",
- request_id=request.request_id,
- duration_ms=elapsed_ms(started),
- error_code="hy_memory_runtime_failed",
- **diagnostic_exception(error),
- )
- for guard, count in zip(guards, before, strict=True):
- if len(guard.failures) > count:
- raise HyMemoryBridgeError(guard.failures[count]) from error
- raise HyMemoryBridgeError("hy_memory_runtime_failed") from error
- finally:
- for guard in guards:
- if hasattr(type(guard), "_extract") or hasattr(type(guard), "_check_targets"):
- guard.bindings = None
- for guard, count in zip(guards, before, strict=True):
- if len(guard.failures) > count:
- raise HyMemoryBridgeError(guard.failures[count])
- result = await self._result(client, request, raw, expected_contents=None, bindings=bindings)
- result = await _with_native_mutation_delta(
- client,
- result,
- raw,
- reconcile_guards,
- )
- if bindings:
- outputs = []
- for memory in result.memories:
- if memory.layer in HY_CODING_LAYERS:
- outputs.append(memory)
- continue
- ids = bindings.support_for(memory.content, memory.owner)
- if not ids:
- raise HyMemoryBridgeError("hy_memory_write_verification_support_missing")
- outputs.append(memory.model_copy(update={"evidence_ids": ids}))
- result = result.model_copy(update={"memories": tuple(outputs)})
- self._last_bindings = bindings
- diagnostic_event(
- level="info",
- component="hy.bridge",
- event="hy.ingest_completed",
- outcome="succeeded",
- request_id=request.request_id,
- duration_ms=elapsed_ms(started),
- details={"result_count": len(result.memories)},
- )
- return result
-
- @_exclusive
- async def ingest_extracted(
- self,
- request: HyMemoryIngestRequest,
- contents: Sequence[str],
- ) -> HyMemoryIngestResult:
- with audit_precipitation_request(request.request_id):
- async with self._write_lock:
- return await self._ingest_extracted(request, contents)
-
- async def _ingest_extracted(
- self,
- request: HyMemoryIngestRequest,
- contents: Sequence[str],
- ) -> HyMemoryIngestResult:
- """Import source memory content when no raw conversation is available."""
- started = monotonic()
- diagnostic_event(
- level="info",
- component="hy.bridge",
- event="hy.ingest_started",
- outcome="started",
- request_id=request.request_id,
- details={"source_id": request.source_id, "count": len(contents)},
- )
- client = await self._get_client()
- guards = getattr(client, "_one_memory_write_guards", ())
- before = [len(guard.failures) for guard in guards]
- from one_memory.hy_response_guard import HyReconcileGuard
-
- report_guards = tuple(guard for guard in guards if isinstance(guard, HyReconcileGuard))
- for guard in report_guards:
- guard.begin_write()
- expected_contents = frozenset(content.strip() for content in contents if content.strip())
- for guard in report_guards:
- guard.imported_contents = expected_contents
- try:
- raw = await _joined_thread(
- client.add_extracted,
- contents,
- user_id=request.user_id,
- agent_id=request.agent_id,
- session_id=request.session_id,
- metadata={
- "source_id": request.source_id,
- "evidence_ids": list(request.evidence_ids),
- "workspace_ids": list(request.workspace_ids),
- "input_kind": "memory_content_without_raw",
- },
- memory_at=request.memory_at,
- request_id=request.request_id,
- )
- except Exception as error:
- diagnostic_event(
- level="error",
- component="hy.bridge",
- event="hy.ingest_failed",
- outcome="failed",
- request_id=request.request_id,
- duration_ms=elapsed_ms(started),
- error_code="hy_memory_runtime_failed",
- **diagnostic_exception(error),
- )
- for guard, count in zip(guards, before, strict=True):
- if len(guard.failures) > count:
- raise HyMemoryBridgeError(guard.failures[count]) from error
- raise HyMemoryBridgeError("hy_memory_runtime_failed") from error
- finally:
- for guard in report_guards:
- guard.imported_contents = None
- for guard, count in zip(guards, before, strict=True):
- if len(guard.failures) > count:
- raise HyMemoryBridgeError(guard.failures[count])
- result = await self._result(
- client,
- request,
- raw,
- expected_contents=expected_contents,
- )
- result = await _with_native_mutation_delta(
- client,
- result,
- raw,
- report_guards,
- )
- diagnostic_event(
- level="info",
- component="hy.bridge",
- event="hy.ingest_completed",
- outcome="succeeded",
- request_id=request.request_id,
- duration_ms=elapsed_ms(started),
- details={"result_count": len(result.memories)},
- )
- return result
-
- @_exclusive
- async def list_sdk_memories(
- self,
- *,
- user_id: str,
- agent_id: str | None = None,
- statuses: tuple[str, ...] = ("active",),
- limit: int = 100,
- offset: int = 0,
- order: str = "desc",
- ) -> HySdkMemoryPage:
- """Read the SDK-owned memory library without Governance hydration."""
- client = await self._get_client()
- try:
- raw = await _joined_thread(
- client.list_memories,
- user_id=user_id,
- agent_id=agent_id,
- statuses=list(statuses),
- limit=limit,
- offset=offset,
- order=order,
- )
- except (TypeError, AttributeError) as error:
- raise HyMemoryBridgeError("hy_memory_sdk_upgrade_required") from error
- except Exception as error:
- raise HyMemoryBridgeError("hy_memory_list_failed") from error
- return _sdk_memory_page(raw, limit=limit, offset=offset)
-
- @_exclusive
- async def get_sdk_memory(self, memory_id: str) -> HySdkMemoryRecord | None:
- client = await self._get_client()
- try:
- raw = await _joined_thread(client.get, memory_id)
- except Exception as error:
- raise HyMemoryBridgeError("hy_memory_get_failed") from error
- if raw is None:
- return None
- return _sdk_memory_record(raw)
-
- @_exclusive
- async def get_sdk_write_outcome(
- self,
- request_id: str,
- ) -> dict[str, object] | None:
- client = await self._get_client()
- try:
- raw = await _joined_thread(client.get_write_outcome, request_id)
- except (TypeError, AttributeError) as error:
- raise HyMemoryBridgeError("hy_memory_sdk_upgrade_required") from error
- except Exception as error:
- raise HyMemoryBridgeError("hy_memory_outcome_inquiry_failed") from error
- if raw is None:
- return None
- if not isinstance(raw, Mapping):
- raise HyMemoryBridgeError("hy_memory_outcome_shape_unknown")
- return dict(raw)
-
- @_exclusive
- async def get_sdk_raw(self, raw_id: str) -> HySdkRawRecord | None:
- client = await self._get_client()
- try:
- raw = await _joined_thread(client.get_raw, raw_id)
- except (TypeError, AttributeError) as error:
- raise HyMemoryBridgeError("hy_memory_sdk_upgrade_required") from error
- except Exception as error:
- raise HyMemoryBridgeError("hy_memory_raw_get_failed") from error
- return _sdk_raw_record(raw) if raw is not None else None
-
- @_exclusive
- async def list_sdk_raw(
- self,
- *,
- user_id: str,
- agent_id: str | None = None,
- session_id: str | None = None,
- source: str | None = None,
- limit: int = 100,
- offset: int = 0,
- order: str = "desc",
- ) -> tuple[tuple[HySdkRawRecord, ...], int]:
- client = await self._get_client()
- try:
- raw = await _joined_thread(
- client.list_raw,
- user_id=user_id,
- agent_id=agent_id,
- session_id=session_id,
- source=source,
- limit=limit,
- offset=offset,
- order=order,
- )
- except (TypeError, AttributeError) as error:
- raise HyMemoryBridgeError("hy_memory_sdk_upgrade_required") from error
- except Exception as error:
- raise HyMemoryBridgeError("hy_memory_raw_list_failed") from error
- if not isinstance(raw, Mapping):
- raise HyMemoryBridgeError("hy_memory_raw_list_shape_unknown")
- rows = raw.get("raw")
- if not isinstance(rows, list):
- raise HyMemoryBridgeError("hy_memory_raw_list_shape_unknown")
- records = tuple(_sdk_raw_record(row) for row in rows)
- total = raw.get("total")
- if not isinstance(total, int) or total < 0:
- raise HyMemoryBridgeError("hy_memory_raw_list_shape_unknown")
- return records, total
-
- async def search_sdk_raw(
- self,
- query: str,
- *,
- user_id: str,
- source_ids: tuple[str, ...] = (),
- limit: int = 8,
- ) -> tuple[HySdkRawHit, ...]:
- client = await self._get_client()
- try:
- raw = await _joined_thread(
- client.search,
- query,
- user_ids=[user_id],
- agent_ids=[],
- include_sources=list(source_ids),
- limit=limit,
- min_score=0.0,
- schema_min_score=0.0,
- schema_limit=0,
- intention_limit=0,
- scene="chat",
- reader=HY_MEMORY_READER,
- layers=["l1_raw"],
- )
- except TypeError as error:
- raise HyMemoryBridgeError("hy_memory_sdk_upgrade_required") from error
- except Exception as error:
- raise HyMemoryBridgeError("hy_memory_raw_search_failed") from error
- return tuple(
- _sdk_raw_hit(record)
- for record in _replied_memories(raw, "hy_memory_raw_search_shape_unknown")
- )
-
- @_exclusive
- async def import_sdk_memory_exact(
- self,
- *,
- content: str,
- memory_id: str,
- user_id: str,
- agent_id: str,
- session_id: str,
- layer: str,
- status: str,
- owner: str | None,
- tags: tuple[str, ...],
- supersedes: tuple[str, ...],
- superseded_by: tuple[str, ...],
- is_latest: bool,
- request_id: str,
- ) -> dict[str, object]:
- """Backfill one legacy semantic memory without extraction/reconcile."""
- client = await self._get_client()
- importer = getattr(client, "import_memory_exact", None)
- if not callable(importer):
- raise HyMemoryBridgeError("hy_memory_sdk_upgrade_required")
- try:
- raw = await _joined_thread(
- importer,
- content,
- memory_id=memory_id,
- user_id=user_id,
- agent_id=agent_id,
- session_id=session_id,
- layer=layer,
- status=status,
- owner=owner,
- tags=list(tags),
- supersedes=list(supersedes),
- superseded_by=list(superseded_by),
- is_latest=is_latest,
- request_id=request_id,
- )
- except Exception as error:
- raise HyMemoryBridgeError("hy_memory_exact_import_failed") from error
- if not isinstance(raw, Mapping) or raw.get("success") is not True:
- raise HyMemoryBridgeError("hy_memory_exact_import_failed")
- return dict(raw)
-
- @_exclusive
- async def import_sdk_raw_exact(
- self,
- *,
- content: str,
- raw_id: str,
- user_id: str,
- agent_id: str,
- session_id: str,
- source: str,
- memory_at: datetime | None,
- metadata: Mapping[str, object],
- request_id: str,
- ) -> dict[str, object]:
- client = await self._get_client()
- importer = getattr(client, "import_raw", None)
- if not callable(importer):
- raise HyMemoryBridgeError("hy_memory_sdk_upgrade_required")
- try:
- raw = await _joined_thread(
- importer,
- content,
- raw_id=raw_id,
- user_id=user_id,
- agent_id=agent_id,
- session_id=session_id,
- source=source,
- memory_at=memory_at,
- metadata=dict(metadata),
- request_id=request_id,
- )
- except Exception as error:
- raise HyMemoryBridgeError("hy_memory_raw_import_failed") from error
- if not isinstance(raw, Mapping) or raw.get("success") is not True:
- raise HyMemoryBridgeError("hy_memory_raw_import_failed")
- return dict(raw)
-
- @_exclusive
- async def list_agent_ids(self, *, user_id: str, limit: int = 1_000) -> tuple[str, ...]:
- """Return the HY scopes that actually hold memories for this user.
-
- Scopes are read back from HY rather than recomputed from evidence,
- because memories written under an earlier routing policy keep the
- agent id they were stored with.
- """
- client = await self._get_client()
- try:
- raw = await _joined_thread(
- cast(Any, client).list_memories,
- user_id=user_id,
- limit=limit,
- )
- except Exception as error:
- raise HyMemoryBridgeError("hy_memory_list_failed") from error
- agent_ids = {
- agent_id
- for memory in _listed_memories(raw)
- if isinstance(agent_id := memory.get("agent_id"), str) and agent_id
- }
- return tuple(sorted(agent_ids))
-
- @_exclusive
- async def outputs_for_request(
- self,
- *,
- request_id: str,
- user_id: str,
- agent_id: str,
- evidence_ids: tuple[str, ...],
- ) -> tuple[HyMemoryOutput, ...]:
- """Read one exact durable SDK write outcome without scanning memories.
-
- This is the safe side of unknown-outcome recovery: it never invokes the
- model, mutates HY, or treats a bounded library scan as proof of absence.
- """
- client = await self._get_client()
- exact_inquiry = getattr(client, "get_write_outcome", None)
- if not callable(exact_inquiry):
- raise HyMemoryBridgeError("hy_memory_sdk_upgrade_required")
- try:
- outcome = await _joined_thread(exact_inquiry, request_id)
- except Exception as error:
- raise HyMemoryBridgeError("hy_memory_outcome_inquiry_failed") from error
- if outcome is None:
- return ()
- result = await _result_from_write_outcome(
- client,
- outcome,
- request_id=request_id,
- user_id=user_id,
- agent_id=agent_id,
- evidence_ids=evidence_ids,
- )
- return result.memories
-
- @_exclusive
- async def receipt_for_request(
- self,
- *,
- request_id: str,
- user_id: str,
- agent_id: str,
- evidence_ids: tuple[str, ...],
- ) -> HyMemoryIngestResult | None:
- """Return the exact terminal SDK receipt, including raw and memory ids."""
- client = await self._get_client()
- exact_inquiry = getattr(client, "get_write_outcome", None)
- if not callable(exact_inquiry):
- raise HyMemoryBridgeError("hy_memory_sdk_upgrade_required")
- try:
- outcome = await _joined_thread(exact_inquiry, request_id)
- except Exception as error:
- raise HyMemoryBridgeError("hy_memory_outcome_inquiry_failed") from error
- if outcome is None:
- return None
- return await _result_from_write_outcome(
- client,
- outcome,
- request_id=request_id,
- user_id=user_id,
- agent_id=agent_id,
- evidence_ids=evidence_ids,
- )
-
- @_exclusive
- async def profile_memories(
- self,
- *,
- user_id: str,
- agent_id: str,
- ) -> tuple[HyMemoryOutput, ...]:
- """The user's own profile, read back rather than returned by the write.
-
- HY writes basic info on a path of its own — `upsert_basic_profile`, an
- evolving chain keyed by what it learns about the person rather than by
- the conversation it learnt it from — and the ids it produces never
- reach the ingest response. Ours therefore never saw them: the whole
- profile layer existed in HY and was invisible here, which is why
- `_memory_scopes` had a profile branch that could not be reached and
- recall without a project directory always came back empty.
-
- Only the head of each chain is returned, which is the profile as it
- stands. Superseded versions are HY's history, not a second memory.
- """
- client = await self._get_client()
- try:
- raw = await _joined_thread(
- cast(Any, client).get_user_basic_info,
- user_id=user_id,
- )
- except Exception as error:
- raise HyMemoryBridgeError("hy_memory_profile_read_failed") from error
- outputs: list[HyMemoryOutput] = []
- seen: set[str] = set()
- for memory in _basic_info_memories(raw):
- memory_id = memory.get("memory_id")
- content = memory.get("content")
- if not isinstance(memory_id, str) or memory_id in seen:
- continue
- if not isinstance(content, str) or not content.strip():
- continue
- seen.add(memory_id)
- layer = memory.get("layer")
- profile_values = memory.get("basic_info_kv")
- ids = (
- self._last_bindings.profile_support(
- content, dict(profile_values) if isinstance(profile_values, Mapping) else {}
- )
- if self._last_bindings
- else ()
- )
- if self._last_bindings and not ids:
- # Previously governed profiles are not new output of this transaction.
- continue
- outputs.append(
- HyMemoryOutput(
- memory_id=memory_id,
- content=content,
- # Stated by HY rather than assumed: what makes this a
- # profile downstream is the layer, and defaulting it here
- # would be this module deciding that on HY's behalf.
- layer=layer if isinstance(layer, str) else None,
- owner="user" if ids else None,
- evidence_ids=ids,
- )
- )
- return tuple(outputs)
-
- @_exclusive
- async def get_user_profile(self, *, user_id: str) -> dict[str, object]:
- """Return the SDK-native assembled long-term user profile."""
- client = await self._get_client()
- try:
- raw = await _joined_thread(
- cast(Any, client).get_user_profile,
- user_id=user_id,
- )
- except Exception as error:
- raise HyMemoryBridgeError("hy_memory_profile_read_failed") from error
- if not isinstance(raw, Mapping):
- raise HyMemoryBridgeError("hy_memory_profile_shape_unknown")
- request_id = raw.get("request_id")
- profile = raw.get("profile")
- elapsed_ms = raw.get("elapsed_ms")
- if (
- not isinstance(request_id, str)
- or (profile is not None and not isinstance(profile, Mapping))
- or not isinstance(elapsed_ms, (int, float))
- ):
- raise HyMemoryBridgeError("hy_memory_profile_shape_unknown")
- return {
- "request_id": request_id,
- "profile": None if profile is None else dict(profile),
- "elapsed_ms": float(elapsed_ms),
- }
-
- @_exclusive
- async def digest(self, *, user_id: str, agent_id: str) -> dict[str, object]:
- client = await self._get_client()
- try:
- result = await _joined_thread(
- cast(Any, client).evolve,
- user_id=user_id,
- agent_id=agent_id,
- )
- return dict(result)
- except Exception as error:
- raise HyMemoryBridgeError("hy_memory_digest_failed") from error
-
- @_exclusive
- async def graph_snapshot(
- self,
- *,
- user_id: str,
- agent_id: str,
- limit: int = 300,
- ) -> HyGraphSnapshot:
- client = await self._get_client()
- try:
- raw_nodes, raw_edges = await _joined_thread(
- _read_graph_snapshot,
- client,
- user_id,
- agent_id,
- limit,
- )
- except Exception as error:
- raise HyMemoryBridgeError("hy_memory_graph_read_failed") from error
- return HyGraphSnapshot(
- nodes=tuple(
- HyGraphNode(
- node_id=str(row[0]),
- content=str(row[1]),
- layer=str(row[2]) if row[2] is not None else None,
- confidence=_safe_float(row[3]),
- )
- for row in raw_nodes
- if len(row) >= 4 and row[0] and row[1]
- ),
- edges=tuple(
- HyGraphEdge(
- source_node_id=str(row[0]),
- target_node_id=str(row[1]),
- relation=str(row[2]),
- weight=_safe_float(row[3]),
- )
- for row in raw_edges
- if len(row) >= 4 and row[0] and row[1] and row[2]
- ),
- )
-
- @_exclusive
- async def update(self, memory_id: str, content: str) -> dict[str, object]:
- """Re-embed a memory in place, keeping its id.
-
- HY re-embeds and upserts the same node, so every id already handed out
- stays valid — which is why this is the call for a correction and
- delete-then-add is not.
-
- A memory HY's vector store does not hold comes back as `success: False`
- rather than as an error, so that answer is turned into one here: a
- caller told the write went through would go on to report an index that
- matches when it does not.
- """
- client = await self._get_client()
- try:
- result = await _joined_thread(client.update, memory_id, content)
- except Exception as error:
- raise HyMemoryBridgeError("hy_memory_update_failed") from error
- if not result.get("success"):
- raise HyMemoryBridgeError("hy_memory_update_rejected")
- return dict(result)
-
- @_exclusive
- async def delete(self, memory_id: str) -> dict[str, object]:
- """Physically delete through the SDK's per-store completeness receipt."""
- client = await self._get_client()
- try:
- result = dict(await _joined_thread(client.delete, memory_id))
- except Exception as error:
- raise HyMemoryBridgeError("hy_memory_delete_failed") from error
- error_code = result.get("error_code")
- if error_code or result.get("partial") is True:
- raise HyMemoryBridgeError(str(error_code or "hy_memory_delete_incomplete"))
- if result.get("success") is True:
- return result
- if result.get("deleted_count") == 0:
- return {**result, "success": True, "already_absent": True}
- raise HyMemoryBridgeError("hy_memory_delete_rejected")
-
- def lifecycle_now(self, user_id: str, ids: Collection[str] | None = None) -> HyLifecycle | None:
- """HY's set-aside memories, or None while this bridge has not opened HY.
-
- Not serialized behind ingest: it reads HY's store directly and must
- answer while a long turn is being processed. Raises
- `HyLifecycleUnreadable` rather than answering empty.
- """
- client = self._client
- if client is None:
- if hy_memory_store_exists(self.data_dir):
- raise HyLifecycleUnreadable("hy_lifecycle_not_ready")
- return None
- return read_hy_lifecycle(client, user_id, ids)
-
- @_exclusive
- async def search_ids(
- self,
- query: str,
- *,
- user_id: str,
- agent_id: str,
- limit: int = 12,
- ) -> tuple[str, ...]:
- return tuple(
- memory_id
- for memory_id, _score in await self.search_scores(
- query, user_id=user_id, agent_id=agent_id, limit=limit
- )
- )
-
- @_exclusive
- async def search_scores(
- self,
- query: str,
- *,
- user_id: str,
- agent_id: str,
- limit: int = 12,
- ) -> tuple[tuple[str, float], ...]:
- return tuple(
- (hit.memory_id, hit.score)
- for hit in await self.search_memories(
- query,
- user_id=user_id,
- agent_id=agent_id,
- limit=limit,
- )
- )
-
- async def search_memories(
- self,
- query: str,
- *,
- user_id: str,
- agent_id: str,
- limit: int = 12,
- ) -> tuple[SemanticMemoryHit, ...]:
- """HY's hits with the relevance it gave them.
-
- D102: `search_ids` threw the score away after sorting by it, so the
- caller could only rank by position — which forced semantic hits to be
- placed as a block ahead of everything the keyword lane found. The
- score is what lets the two lanes be ranked against each other.
-
- Native search runs without a process-local write gate. MemHub expects
- concurrent read during precipitation; store work is a short burst after
- network-bound embed/LLM steps, and refusing reads with
- ``hy_memory_store_busy`` only pushed callers onto weaker fallbacks.
- """
- client = await self._get_client()
- try:
- result = await _joined_thread(
- client.search,
- query,
- user_ids=[user_id],
- agent_ids=[] if agent_id == "*" else [agent_id],
- limit=limit,
- min_score=hy_relevance_floor(),
- schema_min_score=hy_relevance_floor(),
- schema_limit=limit,
- intention_limit=limit,
- scene="normal",
- reader=HY_MEMORY_READER,
- )
- except Exception as error:
- raise HyMemoryBridgeError("hy_memory_search_failed") from error
- hits = _replied_memories(result, "hy_memory_search_shape_unknown")
- found: list[SemanticMemoryHit] = []
- seen: set[str] = set()
- for item in sorted(hits, key=_hy_score, reverse=True):
- memory_id = item.get("memory_id") or item.get("id")
- if isinstance(memory_id, str) and memory_id not in seen:
- seen.add(memory_id)
- formatted_content = item.get("content")
- member_ids, formatting_complete = _formatted_member_ids(item)
- found.append(
- SemanticMemoryHit(
- memory_id=memory_id,
- score=_hy_score(item),
- formatted_content=(
- formatted_content.strip()
- if isinstance(formatted_content, str) and formatted_content.strip()
- else None
- ),
- member_ids=member_ids,
- sdk_formatted=True,
- formatting_complete=formatting_complete,
- )
- )
- return tuple(found[:limit])
-
- @staticmethod
- async def _result(
- client: HyMemoryClientProtocol,
- request: HyMemoryIngestRequest,
- raw: Mapping[str, object],
- expected_contents: frozenset[str] | None,
- bindings: HyWriteBindings | None = None,
- ) -> HyMemoryIngestResult:
- success = raw.get("success") is True
- if not success:
- raise HyMemoryBridgeError(_safe_error_code(raw))
- if raw.get("scene") == "productivity":
- return await _coding_result(client, request, raw)
- raw_memory_id = raw.get("memory_id")
- source_raw_ids = (
- (raw_memory_id,) if isinstance(raw_memory_id, str) and raw_memory_id else ()
- )
- raw_ids = raw.get("memory_ids")
- if not isinstance(raw_ids, list):
- single = raw.get("memory_id")
- raw_ids = [single] if isinstance(single, str) and single else []
- records: list[Mapping[str, object]] = []
- for memory_id in (value for value in raw_ids if isinstance(value, str)):
- record = await _joined_thread(_read_hy_record, client, memory_id)
- if record:
- records.append(record)
- if not records and expected_contents:
- for expected_content in expected_contents:
- found = await _joined_thread(
- client.search,
- expected_content,
- user_ids=[request.user_id],
- agent_ids=[request.agent_id],
- limit=20,
- min_score=0.0,
- schema_min_score=0.0,
- schema_limit=20,
- intention_limit=20,
- reader=HY_MEMORY_READER,
- )
- records.extend(_exact_content_records(found, expected_content))
-
- outputs: list[HyMemoryOutput] = []
- seen_ids: set[str] = set()
- for record in records:
- record_memory_id = record.get("memory_id")
- if not isinstance(record_memory_id, str) or record_memory_id in seen_ids:
- continue
- seen_ids.add(record_memory_id)
- if (
- not _record_matches_request(record, request)
- and not (
- expected_contents is not None
- and record.get("content") in expected_contents
- and record.get("user_id") == request.user_id
- and record.get("agent_id") == request.agent_id
- )
- and not (
- bindings is not None
- and record.get("user_id") == request.user_id
- and record.get("agent_id") == request.agent_id
- and bindings.verified_operations.get(record_memory_id)
- == (record.get("content"), record.get("owner"))
- )
- ):
- continue
- record_content = record.get("content")
- if not isinstance(record_content, str) or not record_content.strip():
- continue
- layer = record.get("layer")
- if isinstance(layer, str) and layer.upper().startswith("L1_"):
- continue
- owner = record.get("owner")
- outputs.append(
- HyMemoryOutput(
- memory_id=record_memory_id,
- content=record_content,
- layer=layer if isinstance(layer, str) else None,
- # Only HY's two words are honoured. It normalises anything
- # else to nothing itself, and inventing a third value here
- # would be this module deciding ownership on its behalf.
- owner=owner if owner in {"user", "agent"} else None,
- tags=_string_tuple(record.get("tags")),
- )
- )
- return HyMemoryIngestResult(
- success=True,
- raw_ids=source_raw_ids,
- memories=tuple(outputs),
- )
-
- async def _get_client(self) -> HyMemoryClientProtocol:
- if self._client is not None:
- return self._client
- async with self._client_lock:
- if self._client is None:
- started = monotonic()
- try:
-
- def initialize() -> None:
- with _HY_CLIENT_INITIALIZATION_LOCK:
- self._client = create_hy_memory_client(
- self.profile,
- api_key=self.api_key,
- data_dir=self.data_dir,
- http_transport_factory=self._http_transport_factory,
- )
-
- await _joined_thread(initialize)
- except HyMemoryBridgeError as error:
- diagnostic_event(
- level="error",
- component="hy.client",
- event="hy.client_initialization.failed",
- outcome="failed",
- duration_ms=elapsed_ms(started),
- error_code="hy_memory_init_failed",
- **diagnostic_exception(error),
- )
- raise
- except Exception as error:
- diagnostic_event(
- level="error",
- component="hy.client",
- event="hy.client_initialization.failed",
- outcome="failed",
- duration_ms=elapsed_ms(started),
- error_code="hy_memory_init_failed",
- **diagnostic_exception(error),
- )
- raise HyMemoryBridgeError("hy_memory_init_failed") from error
- diagnostic_event(
- level="debug",
- component="hy.client",
- event="hy.client_initialization.completed",
- outcome="succeeded",
- duration_ms=elapsed_ms(started),
- )
- assert self._client is not None
- return self._client
-
- @_exclusive
- async def close(self) -> None:
- async with self._client_lock:
- if self._client is None:
- return
- client, self._client = self._client, None
- await _joined_thread(client.close)
-
-
-def create_hy_memory_client(
- profile: ModelProfileSnapshot,
- *,
- api_key: str | None,
- data_dir: Path,
- http_transport_factory: Callable[[], Any] | None = None,
-) -> HyMemoryClientProtocol:
- configure_hy_memory_environment(data_dir)
- config = build_hy_memory_config(
- profile,
- api_key=api_key,
- data_dir=data_dir,
- )
- config.http_transport_factory = http_transport_factory
- reattach_legacy_vector_collection(profile, config)
- mismatch = inspect_graph_width_mismatch(config)
- if mismatch is not None:
- # Do not archive here. Archiving without a choice is what retired a
- # live 13MB graph once already; the caller must pick KEEP_EXISTING,
- # REBUILD_WITH_NEW, or EXPORT_FIRST through apply_graph_width_decision.
- raise GraphWidthMismatchError(mismatch)
- client_module = import_module("hy_memory.client")
- client_type = client_module.HyMemoryClient
- runtime = _shared_hy_runtime(config, data_dir)
- # `ultra` forces the kuzu graph store open regardless of
- # MEMORY_ENABLE_GRAPH (hy_memory/client.py), and tearing that database down
- # is where the packaged app segfaults: kuzu::main::Database::~Database()
- # checkpoints and faults in NullMask::setNullRange. Passing ultra here
- # undid the mode `build_hy_memory_config` had just chosen, so ask the same
- # switch again instead of hard-coding the constant.
- client_mode = HY_MEMORY_MODE if graph_store_enabled() else "pro"
- client = cast(
- HyMemoryClientProtocol,
- client_type(config=config, mode=client_mode, runtime=runtime),
- )
- native_close = client.close
- released = False
-
- def close_leased_client() -> None:
- nonlocal released
- if released:
- return
- released = True
- try:
- native_close()
- finally:
- _release_shared_hy_runtime(data_dir)
-
- cast(Any, client).close = close_leased_client
- # The pinned public SDK schedules duplicate cleanup after a search has already returned.
- # That turns a read into an unleased native-store write and invalidates the
- # full-node permission proof saved by the ingest which created the node.
- # MemHub owns lifecycle dedup in its governed store, so its HY read path must
- # remain side-effect free.
- cast(Any, client)._spawn_search_dedup = lambda *args, **kwargs: None
- embedding_provider = profile.embedding_provider_kind or profile.provider_kind
- if embedding_provider is ProviderKind.LOCAL_ONNX:
- # HY builds its own EmbedService with no injection point, so the local
- # encoder is swapped in after construction — in both places that hold
- # a reference. `client.__init__` hands its service to the component
- # factory (client.py:300) and every pipeline takes it from there
- # (registry.py:103/137/177), so replacing only the client's own
- # attribute left the writer on the original, dialling the placeholder
- # URL. That failed as a connection error with nothing extracted, and
- # the test asserting the swap passed throughout because it read the
- # attribute we had just written.
- local_embed_service = LocalHyEmbedService()
- client._embed_service = local_embed_service # type: ignore[attr-defined]
- registry = getattr(client, "_registry", None)
- if registry is not None:
- registry._shared_embed_service = local_embed_service
- # And drop the pipelines HY pre-warmed. `client.__init__` builds
- # the System2 writer at client.py:332, before this code runs, so
- # that writer captured HY's own service and passed it to the inner
- # writer — and a cached pipeline is never rebuilt. Setting the two
- # references above without this changed nothing that mattered:
- # measured on a real import, still 67 connection errors and not
- # one memory. These are plain lazy caches; HY's own close() clears
- # the same three, and the next call rebuilds them with the service
- # set above.
- registry._system2_writer = None
- registry._writer = None
- registry._reader = None
- # The pinned HY SDK checks its named-reader cache before the legacy singleton.
- registry._readers.clear()
- from one_memory.hy_response_guard import install_hy_write_guards
-
- install_hy_write_guards(client)
- return client
-
-
-def _warm_hy_write_dependencies() -> None:
- """Load CPU/disk-heavy helpers used synchronously by the first HY write."""
- embed_service = import_module("hy_memory.core.embed_service")
- embed_service._truncate_for_embedding("one-memory-warmup")
-
-
-async def _coding_result(
- client: HyMemoryClientProtocol,
- request: HyMemoryIngestRequest,
- raw: Mapping[str, object],
-) -> HyMemoryIngestResult:
- """HY's coding route: its experiences and working facts, read back from its store.
-
- The response only carries ids. Each row is attributed to the whole turn HY
- was given; HY does not say which message a coding row came from.
- """
- experience_ids = _string_tuple(raw.get("experience_ids"))
- fact_ids = _string_tuple(raw.get("fact_ids"))
- if not experience_ids and not fact_ids:
- return HyMemoryIngestResult(success=True)
- native = cast(Any, client)
- store = getattr(native, "_coding_store", None)
- if store is None:
- raise HyMemoryBridgeError("hy_memory_coding_store_missing")
-
- async def read() -> tuple[list[Any], list[Any]]:
- return (
- await store.get_many(list(experience_ids), user_id=request.user_id),
- await store.get_facts(list(fact_ids), user_id=request.user_id),
- )
-
- try:
- experiences, facts = await _joined_thread(native._loop_thread.run, read())
- except Exception as error:
- raise HyMemoryBridgeError("hy_memory_coding_read_failed") from error
- outputs: list[HyMemoryOutput] = []
- for row in experiences:
- if (row.user_id, row.agent_id) != (request.user_id, request.agent_id):
- continue
- content = "\n".join(
- part.strip() for part in (row.task, row.solution, row.boundary_envs) if part.strip()
- )
- if content:
- outputs.append(
- HyMemoryOutput(
- memory_id=row.experience_id,
- content=content,
- layer=HY_CODING_EXPERIENCE_LAYER,
- evidence_ids=request.evidence_ids,
- )
- )
- for row in facts:
- if (row.user_id, row.agent_id) != (request.user_id, request.agent_id):
- continue
- # details is HY's verbatim copy of the turn; the statement is the memory.
- if row.status == "active" and row.statement.strip():
- outputs.append(
- HyMemoryOutput(
- memory_id=row.fact_id,
- content=row.statement.strip(),
- layer=HY_WORKING_FACT_LAYER,
- evidence_ids=request.evidence_ids,
- )
- )
- return HyMemoryIngestResult(success=True, memories=tuple(outputs))
-
-
-async def _with_native_mutation_delta(
- client: HyMemoryClientProtocol,
- result: HyMemoryIngestResult,
- raw: Mapping[str, object],
- reconcile_guards: Sequence[Any],
-) -> HyMemoryIngestResult:
- """Map native SDK mutations back into MemHub governance.
-
- Store permission wrappers used to discover this by intercepting every
- native CRUD call. The embedded SDK now owns unrestricted local CRUD, so
- chat targets come from the reconcile observer and coding targets come from
- the SDK's public result document.
- """
-
- retired = set(result.retired_memory_ids)
- superseded = {key: tuple(values) for key, values in result.superseded_memory_ids.items()}
- chat_targets = {
- key
- for guard in reconcile_guards
- for key in getattr(guard, "mutation_target_ids", ())
- if isinstance(key, str) and key
- }
-
- operations = raw.get("ops")
- for item in operations if isinstance(operations, list) else ():
- if not isinstance(item, Mapping):
- continue
- if item.get("action") == "DELETE":
- key = item.get("target_experience_id")
- if isinstance(key, str) and key:
- retired.add(key)
-
- fact_operations = raw.get("fact_ops")
- for item in fact_operations if isinstance(fact_operations, list) else ():
- if not isinstance(item, Mapping) or item.get("action") != "SUPERSEDE":
- continue
- old, new = item.get("fact_id"), item.get("superseded_by")
- if isinstance(old, str) and old:
- retired.add(old)
- if isinstance(new, str) and new:
- superseded[old] = (new,)
-
- for key in chat_targets:
- record = await _joined_thread(_read_hy_record, client, key)
- if record is None:
- retired.add(key)
- continue
- status = str(record.get("status", "")).lower()
- if status in {"deleted", "shadow", "superseded"}:
- retired.add(key)
- replacement = record.get("superseded_by")
- if isinstance(replacement, str) and replacement:
- superseded[key] = (replacement,)
- elif isinstance(replacement, list):
- values = tuple(value for value in replacement if isinstance(value, str) and value)
- if values:
- superseded[key] = values
-
- return result.model_copy(
- update={
- "retired_memory_ids": tuple(sorted(retired)),
- "superseded_memory_ids": superseded,
- }
- )
-
-
-def _read_hy_record(
- client: HyMemoryClientProtocol,
- memory_id: str,
-) -> Mapping[str, object] | None:
- record = client.get(memory_id)
- if not record or "owner" in record or record.get("source") != "vdb":
- return record
- # The pinned HY SDK's get serializer omits owner although the stored node has it.
- native = cast(Any, client)
- node = native._loop_thread.run(native._vector_store.get_by_id(memory_id))
- if node is None or node.content != record.get("content"):
- raise HyMemoryBridgeError("hy_memory_record_changed_during_read")
- if node.user_id != record.get("user_id") or node.agent_id != record.get("agent_id"):
- raise HyMemoryBridgeError("hy_memory_record_scope_mismatch")
- return {**record, "owner": node.owner}
-
-
-#: Reserved, and shaped so it cannot collide with a stored profile: those are
-#: uuid4. The bridge cache is keyed by `(profile_id, revision)`, and a
-#: collision would hand the search-only bridge back to extraction after the
-#: user finally configured a model — which looks, from outside, like pasting
-#: a key changed nothing at all.
-BUILTIN_RETRIEVAL_PROFILE_ID = "builtin-retrieval"
-
-#: The LLM half is never called on this path and the endpoint is never
-#: reached, but HY wants the shape filled in. Same placeholder the embedder
-#: uses a few lines up, for the same reason.
-_LOCAL_ONNX_PLACEHOLDER_URL = "http://127.0.0.1/local-onnx"
-
-
-def builtin_retrieval_snapshot() -> ModelProfileSnapshot:
- """A profile that can read the vector store and generate nothing.
-
- Searching needs an embedding and a collection name; it does not need a
- generation model or a key. Spelling that out as a snapshot keeps the
- read path on the same code as everything else rather than a second way
- of opening the same store.
- """
- from one_memory.embedding_assets import (
- BUILTIN_EMBEDDING_DIMENSIONS,
- BUILTIN_EMBEDDING_MODEL,
- )
-
- return ModelProfileSnapshot(
- profile_id=BUILTIN_RETRIEVAL_PROFILE_ID,
- revision=0,
- provider_kind=ProviderKind.LOCAL_ONNX,
- base_url=_LOCAL_ONNX_PLACEHOLDER_URL,
- model=BUILTIN_EMBEDDING_MODEL,
- embedding_provider_kind=ProviderKind.LOCAL_ONNX,
- embedding_model=BUILTIN_EMBEDDING_MODEL,
- embedding_dimensions=BUILTIN_EMBEDDING_DIMENSIONS,
- timeout_seconds=60,
- max_concurrency=1,
- context_window=None,
- has_api_key=False,
- )
-
-
-def hy_memory_store_exists(data_dir: Path) -> bool:
- """Whether extraction has ever written a store here."""
- return (data_dir / "hy-memory" / HY_MEMORY_NAMESPACE / "graph").exists()
-
-
-def snapshot_hy_data_plane(
- *,
- source_root: Path,
- target_root: Path,
- writers_stopped: bool,
-) -> object:
- """Offline SDK snapshot entry; product modules do not import SDK stores."""
- from hy_memory.snapshot import snapshot_local_data_plane # type: ignore[import-untyped]
-
- return snapshot_local_data_plane(
- source_root=source_root,
- target_root=target_root,
- writers_stopped=writers_stopped,
- )
-
-
-def restore_hy_data_plane(
- *,
- snapshot_root: Path,
- target_root: Path,
- writers_stopped: bool,
- protective_root: Path | None = None,
-) -> object:
- """Offline SDK restore entry; requires the released SDK snapshot contract."""
- from hy_memory.snapshot import restore_local_data_plane
-
- return restore_local_data_plane(
- snapshot_root=snapshot_root,
- target_root=target_root,
- writers_stopped=writers_stopped,
- protective_root=protective_root,
- )
-
-
-class LocalHyEmbedService:
- """Drop-in for HY's EmbedService that runs the built-in ONNX model.
-
- Covers the methods HY calls on an embed service, counted from HY's own
- source rather than assumed. An earlier version implemented only `embed`, on
- the strength of a comment saying that was all HY used — and the version
- installed here calls `embed_queued` from thirty places in the writer.
- A missing method here does not surface as a missing method; it leaves HY
- on its own service pointed at a placeholder URL, and extraction ends in
- a connection error having produced nothing. test_local_onnx_provider
- counts the surface so the next HY upgrade reports itself.
-
- No queue, unlike HY's: batching exists to amortise a network round trip,
- and there is no round trip here. Cache is accepted and ignored for the
- same reason — LocalEmbedder is cheap once the session is warm, and HY's
- cache would double-store every vector.
- """
-
- _shared_embedder: Any | None = None
- _shared_embedder_lock = threading.Lock()
-
- def __init__(self, embedder: Any | None = None) -> None:
- if embedder is None:
- from one_memory.local_embedding import LocalEmbedder
-
- with self._shared_embedder_lock:
- if self._shared_embedder is None:
- self.__class__._shared_embedder = LocalEmbedder()
- embedder = self._shared_embedder
- if embedder is None:
- raise RuntimeError("local_embedder_unavailable")
- self._embedder = embedder
-
- async def embed(self, text: str, use_cache: bool = True) -> list[float]:
- del use_cache
- vectors = await asyncio.to_thread(self._embedder.encode, [text])
- return cast(list[float], vectors[0])
-
- async def embed_queued(self, text: str, use_cache: bool = True) -> list[float]:
- return await self.embed(text, use_cache)
-
- async def embed_queued_with_meta(
- self,
- text: str,
- use_cache: bool = True,
- ) -> tuple[list[float], dict[str, Any]]:
- return await self.embed_with_meta(text, use_cache)
-
- async def embed_batch(
- self,
- texts: list[str],
- use_cache: bool = True,
- ) -> list[list[float]]:
- del use_cache
- if not texts:
- return []
- vectors = await asyncio.to_thread(self._embedder.encode, list(texts))
- return [cast(list[float], vector) for vector in vectors]
-
- async def embed_batch_with_meta(
- self,
- texts: list[str],
- use_cache: bool = True,
- ) -> tuple[list[list[float]], list[dict[str, Any]]]:
- vectors = await self.embed_batch(texts, use_cache)
- return vectors, [{"provider": "local-onnx"} for _ in vectors]
-
- async def embed_with_meta(
- self,
- text: str,
- use_cache: bool = True,
- ) -> tuple[list[float], dict[str, Any]]:
- # HY reads provider metadata off this for its own tracing. There is no
- # provider and no request, so the honest answer is a local marker
- # rather than invented status codes.
- return await self.embed(text, use_cache), {"provider": "local-onnx"}
-
- def get_embedding_dims(self) -> int:
- from one_memory.embedding_assets import BUILTIN_EMBEDDING_DIMENSIONS
-
- return int(BUILTIN_EMBEDDING_DIMENSIONS)
-
- def clear_cache(self) -> None:
- return None
-
- def get_stats(self) -> dict[str, Any]:
- return {"provider": "local-onnx", "cache_hits": 0, "embed_count": 0}
-
-
-def build_hy_memory_config(
- profile: ModelProfileSnapshot,
- *,
- api_key: str | None,
- data_dir: Path,
-) -> Any:
- try:
- config_module = import_module("hy_memory.config")
- except ModuleNotFoundError as error:
- raise HyMemoryBridgeError("hy_memory_sdk_unavailable") from error
- config = config_module.MemoryConfig.from_env()
- config.debug = False
- config.metrics_enabled = False
- if profile.provider_kind is ProviderKind.HY_DEFAULT:
- raise UnsupportedHyMemoryProviderError("hy_default_not_available")
- if profile.provider_kind is ProviderKind.ANTHROPIC:
- raise UnsupportedHyMemoryProviderError("anthropic_provider_adapter_not_available")
- if profile.provider_kind is ProviderKind.OPENAI_COMPATIBLE and not api_key:
- raise HyMemoryBridgeError("model_api_key_missing")
- if not profile.embedding_model:
- raise HyMemoryBridgeError("embedder_not_configured")
-
- base_url = _provider_base_url(profile.provider_kind, profile.base_url)
- provider_key = api_key or "ollama"
- # The real-model acceptance measures ONE honest attempt. The SDK's built-in
- # retry loop would multiply both the spend and the request count behind the
- # caller's back, so the acceptance run opts out of it via this env flag.
- # The product default is unchanged: this is scoped to the isolated run.
- single_attempt = os.environ.get("ONE_MEMORY_ACCEPTANCE_SINGLE_ATTEMPT") == "1"
- config.llm.provider = "openai"
- config.llm.model = profile.model
- config.llm.api_key = provider_key
- config.llm.base_url = base_url
- config.llm.timeout = profile.timeout_seconds
- config.llm.max_retries = 0 if single_attempt else 2
- config.llm.retry_delay = 0.0 if single_attempt else 1.0
- config.llm.temperature = 0
- # Output capacity is independent of context size. Mixed-author windows need
- # more space than HY's 2K default; truncation is still a hard failure.
- config.llm.agent_max_tokens = 8192
- config.llm.enable_summary = False
- config.llm.enable_query_rewrite = False
- config.llm.few_shot_enabled = True
- config.llm.enable_intention = False
- config.llm.extra_headers = None
- config.llm.extra_body = attach_disable_thinking(profile, {}) or None
- _write_memories_in_chinese(config.llm)
- # `context_window` describes model input capacity. HY Memory's
- # `max_tokens` fields cap generated output and have safe extraction
- # defaults (1024/2000). Copying a 16K context window into those fields
- # made each atomic cold-start extraction run for minutes.
-
- embedding_provider = profile.embedding_provider_kind or profile.provider_kind
- dimensions: int | None
- if embedding_provider is ProviderKind.LOCAL_ONNX:
- # Local embedding never leaves the machine. HY still wants an
- # EmbedderConfig shape, so we fill placeholder fields; the real
- # encoder is swapped onto the client after construction (see
- # create_hy_memory_client). The shared-origin credential rule does
- # not apply here for the same reason.
- from one_memory.embedding_assets import (
- BUILTIN_EMBEDDING_DIMENSIONS,
- BUILTIN_EMBEDDING_MODEL,
- )
-
- config.embedder.provider = "openai"
- config.embedder.model = profile.embedding_model or BUILTIN_EMBEDDING_MODEL
- config.embedder.api_key = "local-onnx"
- config.embedder.base_url = "http://127.0.0.1/local-onnx"
- config.embedder.timeout = profile.timeout_seconds
- config.embedder.max_retries = 0
- config.embedder.retry_delay = 0.0
- config.embedder.extra_headers = None
- config.embedder.extra_body = None
- dimensions = profile.embedding_dimensions or BUILTIN_EMBEDDING_DIMENSIONS
- config.embedder.embedding_dims = dimensions
- embedding_base_url = "local-onnx"
- else:
- embedding_base_url = _provider_base_url(
- embedding_provider,
- profile.embedding_base_url or profile.base_url,
- )
- embedding_key = "ollama" if embedding_provider is ProviderKind.OLLAMA else api_key
- if not embedding_key:
- raise HyMemoryBridgeError("embedding_api_key_missing")
- config.embedder.provider = "openai"
- config.embedder.model = profile.embedding_model
- config.embedder.api_key = embedding_key
- config.embedder.base_url = embedding_base_url
- config.embedder.timeout = profile.timeout_seconds
- config.embedder.max_retries = 2
- config.embedder.retry_delay = 0.3
- config.embedder.extra_headers = None
- config.embedder.extra_body = None
- if profile.embedding_dimensions is not None:
- config.embedder.embedding_dims = profile.embedding_dimensions
- dimensions = profile.embedding_dimensions
-
- memory_root = data_dir / "hy-memory" / HY_MEMORY_NAMESPACE
- memory_root.mkdir(parents=True, exist_ok=True)
- config.vector_store.provider = "chroma"
- config.vector_store.collection_name = _collection_name(
- embedding_provider,
- embedding_base_url,
- profile.embedding_model or "bge-small-zh-v1.5",
- )
- config.vector_store.persist_directory = str(memory_root / "vector")
- if dimensions is not None:
- config.vector_store.embedding_dims = dimensions
- config.vector_store.host = None
- config.vector_store.port = None
- config.vector_store.api_key = None
- # See `graph_store_enabled`: `ultra` forces the graph open, so switching it
- # off means moving the mode too.
- if graph_store_enabled():
- config.mode = HY_MEMORY_MODE
- config.graph_store.provider = "kuzu"
- config.graph_store.db_path = str(memory_root / "graph")
- else:
- config.mode = "pro"
- config.graph_store.provider = "kuzu"
- # `pro` reads MEMORY_ENABLE_GRAPH from the environment and defaults it
- # off; set it anyway so an inherited value cannot turn the graph on.
- os.environ["MEMORY_ENABLE_GRAPH"] = "false"
- # Moving off `ultra` is not enough on its own. `graph_data_may_exist`
- # ignores the mode: the list and purge paths open an ephemeral kuzu
- # Database whenever db_path still holds data, and tearing that Database
- # down is the same NullMask::setNullRange segfault. With the graph
- # closed, point it at a path that never has data so those paths skip it
- # instead of re-opening the crash.
- config.graph_store.db_path = str(memory_root / "graph-disabled")
- config.graph_store.url = None
- config.graph_store.username = None
- config.graph_store.password = None
- config.graph_store.database = None
- config.graph_store.graph_rerank_enabled = False
- config.graph_store.temporal_spine = True
- config.graph_store.topic_summary_enabled = False
- if profile.embedding_dimensions is None:
- # A snapshot that does not state its embedding width used to let HY
- # apply its own default, and a default that disagrees with the store
- # retires the store: on this machine a snapshot from before the field
- # existed archived a 13MB graph and opened an empty one in its place.
- # The store knows its own geometry, so follow it rather than guess.
- stored_width = _graph_embedding_width(Path(config.graph_store.db_path))
- if stored_width is not None:
- config.embedder.embedding_dims = stored_width
- config.vector_store.embedding_dims = stored_width
- config.cache.backend = "sqlite"
- config.cache.db_path = str(memory_root / "cache.sqlite3")
- config.cache.mysql_host = None
- config.cache.mysql_port = None
- config.cache.mysql_user = None
- config.cache.mysql_password = None
- config.cache.mysql_database = None
- config.api.api_keys = []
- config.llm.eval_user = None
- config.llm.eval_apikey = None
- config.history.enable = True
- config.history.record_searches = False
- config.history.db_path = str(memory_root / "history.sqlite3")
- config.coding.enable = True
- config.coding.db_path = str(memory_root / "coding.sqlite3")
- config.coding.tool_result_max_bytes = coding_tool_result_max_bytes()
- config.recall.episode_recall_enabled = True
- config.recall.episode_summary_enabled = False
- config.recall.dynamic_episode_enabled = True
- config.recall.session_episode_enabled = False
- config.recall.session_episode_context_enabled = False
- config.recall.episode_capsule_context_enabled = True
- config.recall.episode_capsule_query_min = 0.65
- config.recall.episode_capsule_assignment_min = 0.60
- config.recall.episode_capsule_first_rank_max = 3
- config.recall.episode_capsule_member_limit = 3
- config.recall.strength_enabled = False
- config.recall.access_tracking_enabled = False
- config.recall.local_rerank_enabled = False
- return config
-
-
-#: The one rule in HY's extraction system prompts that hands the language of
-#: someone's memories to whatever they happened to paste in. Both language
-#: variants carry it, with this exact wording in the Chinese one.
-_HY_FOLLOWS_THE_INPUT_LANGUAGE = "* 输出语言必须与输入语言一致"
-
-_ALWAYS_CHINESE = (
- "* 输出语言必须始终是简体中文,即使输入是英文、代码或报错信息\n"
- "* 记忆语言是用户属性,不随单条输入的语言变化"
-)
-
-#: HY's extraction principle reads only the user's messages, although its own
-#: OWNER and subject rules already say how to keep an AI assistant's words
-#: apart from the person's. MemHub records both speakers, so only this line
-#: changes; who said what stays with HY's rules.
-_HY_READS_ONLY_THE_USER = "只提取 NEW user messages 中首次出现的新信息。"
-
-_BOTH_SPEAKERS = (
- "只提取 NEW messages 中首次出现的新信息:既提取用户说的,"
- "也提取 AI 助手提供的有长期价值的信息(推荐、确认、查到的资料、方案与结论),"
- "按下方主体规则与 OWNER 标明是谁说的。"
-)
-
-
-def _write_memories_in_chinese(llm_config: Any) -> None:
- """Ask HY for Chinese memories whichever language it thinks the input is.
-
- HY picks the extraction prompt per call from the content itself:
- `is_chinese(content)` at `hy_memory/agent/extractor.py:868`, a CJK
- character ratio with a 0.3 threshold. A Chinese question about a pasted
- English traceback measures well under it, so it takes the English branch
- and the memory is written in English — for a user whose library is
- otherwise Chinese, and who was never asked.
-
- Two things had to be worked around, both read out of HY's source rather
- than assumed:
-
- The lever named for this, `extract_system_prompt_zh`, is read *inside*
- the `is_chinese(...)` true branch (`extractor.py:891-901`), so it only
- applies where nothing was wrong. The branch that actually runs reads
- `extract_system_prompt_en` (`extractor.py:922-930`).
-
- And HY's own Chinese prompt says "输出语言必须与输入语言一致", so serving
- it verbatim would leave the model following the input language anyway —
- a Chinese prompt producing an English memory. So HY's text is kept for
- everything it defines (schema, owner rules, tags, and the rules that
- keep terms and code exactly as pasted) and only that single line is
- replaced. Deriving it at runtime rather than copying the prompt means an
- SDK bump brings HY's improvements with it; if the line ever moves, the
- override is appended instead so the language still holds, and the tests
- pin the line's presence so we hear about it.
-
- The data-injection template stays HY's built-in English one — the
- override hook is system-prompt-only (`config.py:166-170`) — and both
- language variants take the same four fields and carry the same JSON
- contract, so nothing is lost. The content itself is never touched:
- prefixing it to push the ratio over the threshold would work, and is
- exactly what must not happen to a verbatim.
- """
- try:
- prompts_zh = import_module("hy_memory.agent.prompts_zh")
- except ModuleNotFoundError as error: # pragma: no cover - SDK guaranteed above
- raise HyMemoryBridgeError("hy_memory_sdk_unavailable") from error
- hy_prompt = prompts_zh.EXTRACT_SYSTEM_PROMPT_ZH
- if _HY_FOLLOWS_THE_INPUT_LANGUAGE in hy_prompt:
- prompt = hy_prompt.replace(_HY_FOLLOWS_THE_INPUT_LANGUAGE, _ALWAYS_CHINESE)
- else:
- logging.getLogger(__name__).warning("hy_language_rule_not_found_appending_override")
- prompt = f"{hy_prompt}\n\n# 语言规则(MemHub)\n\n{_ALWAYS_CHINESE}\n"
- if _HY_READS_ONLY_THE_USER in prompt:
- prompt = prompt.replace(_HY_READS_ONLY_THE_USER, _BOTH_SPEAKERS)
- else:
- logging.getLogger(__name__).warning("hy_extraction_scope_rule_not_found_appending_override")
- prompt = f"{prompt}\n\n# 提取范围(MemHub)\n\n{_BOTH_SPEAKERS}\n"
- llm_config.extract_system_prompt_en = prompt
- llm_config.extract_system_prompt_zh = prompt
-
-
-def _provider_base_url(provider: ProviderKind, value: str | None) -> str:
- base_url = (value or "").rstrip("/")
- if provider is ProviderKind.OLLAMA and not base_url.endswith("/v1"):
- return f"{base_url}/v1"
- return base_url
-
-
-def _safe_error_code(result: Mapping[str, object]) -> str:
- value = result.get("error_code")
- allowed = {
- "auth_error",
- "invalid_request",
- "model_error",
- "rate_limit",
- "timeout",
- "unavailable",
- }
- if isinstance(value, str) and value in allowed:
- return f"hy_memory_{value}"
- return "hy_memory_unknown_error"
-
-
-def _safe_float(value: object) -> float | None:
- if isinstance(value, (int, float)):
- return float(value)
- return None
-
-
-def _basic_info_memories(raw: object) -> tuple[Mapping[str, object], ...]:
- """Parse the basic-info reply, which is shaped unlike the listing reply.
-
- `list_memories` wraps its rows in `vdb`; `get_user_basic_info` returns
- them at the top level. Reading one with the other's parser is how the
- profile came back empty from a store that visibly held three of them —
- so an unrecognised payload is an error here rather than no memories. A
- person we have learnt nothing about yet is an empty list, which is a
- different thing and stays quiet.
- """
- if not isinstance(raw, Mapping):
- raise HyMemoryBridgeError("hy_memory_profile_shape_unknown")
- memories = raw.get("memories")
- if not isinstance(memories, list):
- raise HyMemoryBridgeError("hy_memory_profile_shape_unknown")
- return tuple(memory for memory in memories if isinstance(memory, Mapping))
-
-
-async def _result_from_write_outcome(
- client: HyMemoryClientProtocol,
- outcome: object,
- *,
- request_id: str,
- user_id: str,
- agent_id: str,
- evidence_ids: tuple[str, ...],
-) -> HyMemoryIngestResult:
- if not isinstance(outcome, Mapping):
- raise HyMemoryBridgeError("hy_memory_outcome_shape_unknown")
- if outcome.get("request_id") not in {None, request_id}:
- raise HyMemoryBridgeError("hy_memory_outcome_identity_mismatch")
- for key, expected in (("user_id", user_id), ("agent_id", agent_id)):
- value = outcome.get(key)
- if value is not None and value != expected:
- raise HyMemoryBridgeError("hy_memory_outcome_identity_mismatch")
- status = outcome.get("status")
- if status == "failed":
- return HyMemoryIngestResult(success=False)
- if status != "succeeded":
- raise HyMemoryBridgeError("hy_memory_outcome_not_terminal")
- result = outcome.get("result")
- if not isinstance(result, Mapping):
- raise HyMemoryBridgeError("hy_memory_outcome_shape_unknown")
- candidates: list[str] = []
- for key in ("memory_ids", "experience_ids", "fact_ids"):
- values = result.get(key)
- if isinstance(values, list):
- candidates.extend(value for value in values if isinstance(value, str))
- singular_id = result.get("memory_id")
- if isinstance(singular_id, str):
- candidates.append(singular_id)
- raw_ids = (
- (singular_id,)
- if isinstance(singular_id, str) and singular_id and result.get("scene") != "productivity"
- else ()
- )
-
- outputs: list[HyMemoryOutput] = []
- for memory_id in dict.fromkeys(candidates):
- try:
- record = await _joined_thread(client.get, memory_id)
- except Exception as error:
- raise HyMemoryBridgeError("hy_memory_outcome_inquiry_failed") from error
- # The singular add memory_id may be the hidden L1 raw node. It is not a
- # semantic memory output and public get correctly returns None for it.
- if not isinstance(record, Mapping):
- continue
- if record.get("user_id") != user_id or record.get("agent_id") != agent_id:
- raise HyMemoryBridgeError("hy_memory_outcome_identity_mismatch")
- content = record.get("content")
- if not isinstance(content, str) or not content.strip():
- continue
- layer = record.get("layer")
- owner = record.get("owner")
- outputs.append(
- HyMemoryOutput(
- memory_id=memory_id,
- content=content,
- layer=layer if isinstance(layer, str) else None,
- owner=owner if owner in {"user", "agent"} else None,
- tags=_string_tuple(record.get("tags")),
- evidence_ids=evidence_ids,
- )
- )
- return HyMemoryIngestResult(
- success=True,
- raw_ids=raw_ids,
- memories=tuple(outputs),
- )
-
-
-def _sdk_memory_record(raw: object) -> HySdkMemoryRecord:
- if not isinstance(raw, Mapping):
- raise HyMemoryBridgeError("hy_memory_record_shape_unknown")
- if any(
- not isinstance(raw.get(key), str) or not str(raw[key]).strip()
- for key in ("memory_id", "content")
- ):
- raise HyMemoryBridgeError("hy_memory_record_shape_unknown")
- try:
- return HySdkMemoryRecord(
- memory_id=str(raw["memory_id"]),
- content=str(raw["content"]),
- layer=str(raw.get("layer") or ""),
- status=str(raw.get("status") or ""),
- is_latest=bool(raw.get("is_latest", True)),
- supersedes=_string_tuple(raw.get("supersedes")),
- superseded_by=_string_tuple(raw.get("superseded_by")),
- tags=_string_tuple(raw.get("tags")),
- owner=(str(raw["owner"]) if raw.get("owner") in {"user", "agent"} else None),
- source_raw_ids=_sdk_source_raw_ids(raw),
- user_id=str(raw.get("user_id") or ""),
- agent_id=str(raw.get("agent_id") or ""),
- session_id=(str(raw["session_id"]) if isinstance(raw.get("session_id"), str) else None),
- source=str(raw["source"]) if isinstance(raw.get("source"), str) else None,
- memory_at=raw.get("memory_at") if isinstance(raw.get("memory_at"), int) else None,
- gmt_created=(
- raw.get("gmt_created") if isinstance(raw.get("gmt_created"), int) else None
- ),
- )
- except (KeyError, TypeError, ValueError) as error:
- raise HyMemoryBridgeError("hy_memory_record_shape_unknown") from error
-
-
-def _sdk_source_raw_ids(raw: Mapping[str, object]) -> tuple[str, ...]:
- custom = raw.get("custom")
- values: list[object] = []
- if isinstance(custom, Mapping):
- listed = custom.get("source_raw_memory_ids")
- if isinstance(listed, list):
- values.extend(listed)
- singular = raw.get("source_raw_memory_id")
- if isinstance(singular, str):
- values.append(singular)
- return tuple(
- dict.fromkeys(value.strip() for value in values if isinstance(value, str) and value.strip())
- )
-
-
-def _sdk_memory_page(raw: object, *, limit: int, offset: int) -> HySdkMemoryPage:
- if not isinstance(raw, Mapping):
- raise HyMemoryBridgeError("hy_memory_list_shape_unknown")
- rows: list[object] = []
- total = 0
- for bucket_name, rows_name in (("vdb", "memories"), ("graph", "nodes")):
- bucket = raw.get(bucket_name)
- if bucket is None and bucket_name == "graph":
- continue
- if not isinstance(bucket, Mapping) or not isinstance(bucket.get(rows_name), list):
- raise HyMemoryBridgeError("hy_memory_list_shape_unknown")
- bucket_total = bucket.get("total")
- if not isinstance(bucket_total, int) or bucket_total < 0:
- raise HyMemoryBridgeError("hy_memory_list_shape_unknown")
- total += bucket_total
- rows.extend(bucket[rows_name])
- deduplicated: dict[str, HySdkMemoryRecord] = {}
- for row in rows:
- record = _sdk_memory_record(row)
- deduplicated.setdefault(record.memory_id, record)
- return HySdkMemoryPage(
- memories=tuple(deduplicated.values()),
- total=total,
- limit=limit,
- offset=offset,
- )
-
-
-def _sdk_raw_record(raw: object) -> HySdkRawRecord:
- if not isinstance(raw, Mapping):
- raise HyMemoryBridgeError("hy_memory_raw_shape_unknown")
- if any(
- not isinstance(raw.get(key), str) or not str(raw[key]).strip()
- for key in ("raw_id", "content", "user_id", "agent_id", "session_id", "source")
- ):
- raise HyMemoryBridgeError("hy_memory_raw_shape_unknown")
- custom = raw.get("custom")
- if not isinstance(custom, Mapping):
- custom = {}
- try:
- return HySdkRawRecord(
- raw_id=str(raw["raw_id"]),
- content=str(raw["content"]),
- user_id=str(raw["user_id"]),
- agent_id=str(raw["agent_id"]),
- session_id=str(raw["session_id"]),
- source=str(raw["source"]),
- memory_at=raw.get("memory_at") if isinstance(raw.get("memory_at"), int) else None,
- gmt_created=(
- raw.get("gmt_created") if isinstance(raw.get("gmt_created"), int) else None
- ),
- custom=dict(custom),
- )
- except (KeyError, TypeError, ValueError) as error:
- raise HyMemoryBridgeError("hy_memory_raw_shape_unknown") from error
-
-
-def _sdk_raw_hit(raw: object) -> HySdkRawHit:
- if not isinstance(raw, Mapping):
- raise HyMemoryBridgeError("hy_memory_raw_search_shape_unknown")
- raw_id = raw.get("memory_id")
- score = raw.get("score")
- if not isinstance(raw_id, str) or not isinstance(score, int | float):
- raise HyMemoryBridgeError("hy_memory_raw_search_shape_unknown")
- base = _sdk_raw_record({**raw, "raw_id": raw_id})
- return HySdkRawHit(
- **base.model_dump(),
- score=max(0.0, min(1.0, float(score))),
- )
-
-
-def _listed_memories(raw: object) -> tuple[Mapping[str, object], ...]:
- if isinstance(raw, Mapping):
- vdb = raw.get("vdb")
- if isinstance(vdb, Mapping):
- return _rows(vdb.get("memories"), "hy_memory_list_shape_unknown")
- return _replied_memories(raw, "hy_memory_list_shape_unknown")
-
-
-def _replied_memories(raw: object, error_code: str) -> tuple[Mapping[str, object], ...]:
- """Select the explicit response scene without merging chat and coding rows.
-
- HY's documented productivity response may also include empty chat groups.
- normal/chat selects memories; productivity/working selects coding_memories.
- Older replies without a scene must expose exactly one channel. Chat accepts
- its flat list or all three named groups; malformed rows are errors, not empty
- recall. This response adapter does not change query or write routing.
- """
- if not isinstance(raw, Mapping):
- raise HyMemoryBridgeError(error_code)
- keys = tuple(key for key in ("memories", "coding_memories") if key in raw)
- if "scene" in raw:
- scene = raw["scene"]
- if not isinstance(scene, str):
- raise HyMemoryBridgeError(error_code)
- if scene in ("normal", "chat"):
- selected = "memories"
- elif scene in ("productivity", "working"):
- selected = "coding_memories"
- else:
- raise HyMemoryBridgeError(error_code)
- if selected not in keys:
- raise HyMemoryBridgeError(error_code)
- elif len(keys) == 1:
- selected = keys[0]
- else:
- raise HyMemoryBridgeError(error_code)
-
- result: list[Mapping[str, object]] = []
- for key in keys:
- value = raw[key]
- if key == "memories" and isinstance(value, Mapping):
- if set(value) != {"schema", "proactive", "normal"}:
- raise HyMemoryBridgeError(error_code)
- channels = tuple(value.values())
- else:
- channels = (value,)
- for channel in channels:
- if not isinstance(channel, list) or any(
- not isinstance(row, Mapping) for row in channel
- ):
- raise HyMemoryBridgeError(error_code)
- if key == selected:
- result.extend(channel)
- return tuple(result)
-
-
-def _rows(value: object, error_code: str) -> tuple[Mapping[str, object], ...]:
- if not isinstance(value, list):
- raise HyMemoryBridgeError(error_code)
- return tuple(row for row in value if isinstance(row, Mapping))
-
-
-def _hy_score(memory: Mapping[str, object]) -> float:
- """HY's own relevance score, which was among the fields being dropped.
-
- Bucketing hits into channels loses the single ranking HY had put them in,
- and recall reads the order these ids arrive in as their rank. Every hit
- still carries the score HY ranked it by, so restoring HY's order is a
- matter of reading a field we already had rather than inventing a
- preference between channels here.
- """
- score = memory.get("score")
- return float(score) if isinstance(score, (int, float)) else 0.0
-
-
-def _formatted_member_ids(memory: Mapping[str, object]) -> tuple[tuple[str, ...], bool]:
- """Return every id represented inside SDK-formatted content.
-
- Plain memories have no nested members and are complete by definition.
- Composite/evolved memories are usable only when the SDK also exposes all
- member ids, so One Memory can re-apply current governance to every line.
- """
- represented: dict[str, None] = {}
- composite = False
-
- raw_members = memory.get("member_ids")
- if raw_members is not None:
- composite = True
- if not isinstance(raw_members, list | tuple) or any(
- not isinstance(member_id, str) or not member_id for member_id in raw_members
- ):
- return (), False
- for member_id in raw_members:
- represented.setdefault(member_id, None)
-
- chain = memory.get("evolution_chain")
- if chain is not None:
- composite = True
- if not isinstance(chain, list | tuple):
- return (), False
- for entry in chain:
- if not isinstance(entry, Mapping):
- return (), False
- member_id = entry.get("node_id") or entry.get("memory_id")
- if not isinstance(member_id, str) or not member_id:
- return (), False
- represented.setdefault(member_id, None)
-
- # These public fields announce composite rendering. If no complete member
- # id list accompanied them, the text cannot be safely released as a unit.
- if memory.get("capsule_memories") is not None or memory.get("timeline") is not None:
- composite = True
- if raw_members is None:
- return (), False
-
- content = memory.get("content")
- if isinstance(content, str) and content.lstrip().startswith(
- ("Related memories:", "Matched memories:", "Memory timeline:")
- ):
- composite = True
- if not represented:
- return (), False
-
- return tuple(represented), not composite or bool(represented)
-
-
-def _read_graph_snapshot(
- client: HyMemoryClientProtocol,
- user_id: str,
- agent_id: str,
- limit: int,
-) -> tuple[list[list[object]], list[list[object]]]:
- concrete = cast(Any, client)
- graph_store = concrete._graph_store
- if graph_store is None:
- return ([], [])
- loop_thread = concrete._loop_thread
- # Kuzu rejects a prepared statement that is handed a parameter its text
- # never references, so a wildcard read must not bind agent_id at all.
- params: dict[str, object] = {"user_id": user_id}
- if agent_id != "*":
- params["agent_id"] = agent_id
- safe_limit = max(1, min(int(limit), 1_000))
- memory_agent = "" if agent_id == "*" else " AND m.agent_id = $agent_id"
- related_agent = (
- "" if agent_id == "*" else " AND a.agent_id = $agent_id AND b.agent_id = $agent_id"
- )
- source_agent = "" if agent_id == "*" else " AND a.agent_id = $agent_id"
- nodes = (
- loop_thread.run(
- graph_store._run(
- f"""
- MATCH (m:Memory)
- WHERE m.user_id = $user_id{memory_agent}
- AND m.status = 'active'
- RETURN m.node_id, m.content, m.layer, m.confidence
- LIMIT {safe_limit}
- """,
- params,
- )
- )
- or []
- )
- related_edges = (
- loop_thread.run(
- graph_store._run(
- f"""
- MATCH (a:Memory)-[r:RELATED_TO]->(b:Memory)
- WHERE a.user_id = $user_id{related_agent}
- AND b.user_id = $user_id
- AND a.status = 'active' AND b.status = 'active'
- RETURN a.node_id, b.node_id, r.relation_type, r.weight
- LIMIT {safe_limit * 4}
- """,
- params,
- )
- )
- or []
- )
- derived_edges = (
- loop_thread.run(
- graph_store._run(
- f"""
- MATCH (a:Memory)-[:DERIVED_FROM]->(v:VdbRef)
- WHERE a.user_id = $user_id{source_agent}
- AND a.status = 'active'
- RETURN a.node_id, v.node_id, 'derived_from', 1.0
- LIMIT {safe_limit * 4}
- """,
- params,
- )
- )
- or []
- )
- topic_nodes = (
- loop_thread.run(
- graph_store._run(
- f"""
- MATCH (m:Memory)-[:TAGGED_WITH]->(t:Topic)
- WHERE m.user_id = $user_id{memory_agent}
- AND m.status = 'active'
- RETURN DISTINCT t.topic_id, t.name, 'TOPIC', 1.0
- LIMIT {safe_limit}
- """,
- params,
- )
- )
- or []
- )
- tagged_edges = (
- loop_thread.run(
- graph_store._run(
- f"""
- MATCH (m:Memory)-[:TAGGED_WITH]->(t:Topic)
- WHERE m.user_id = $user_id{memory_agent}
- AND m.status = 'active'
- RETURN m.node_id, t.topic_id, 'tagged_with', 1.0
- LIMIT {safe_limit * 4}
- """,
- params,
- )
- )
- or []
- )
- return (
- [*nodes, *topic_nodes],
- [*related_edges, *derived_edges, *tagged_edges],
- )
-
-
-def _record_matches_request(
- record: Mapping[str, object],
- request: HyMemoryIngestRequest,
-) -> bool:
- custom = record.get("custom")
- return (
- isinstance(custom, Mapping)
- and custom.get("request_id") == request.request_id
- and record.get("user_id") == request.user_id
- and record.get("agent_id") == request.agent_id
- )
-
-
-def _exact_content_records(
- value: object,
- expected_content: str,
-) -> list[Mapping[str, object]]:
- records: list[Mapping[str, object]] = []
- if isinstance(value, Mapping):
- if value.get("content") == expected_content and isinstance(value.get("memory_id"), str):
- records.append(value)
- for nested in value.values():
- records.extend(_exact_content_records(nested, expected_content))
- elif isinstance(value, Sequence) and not isinstance(value, (str, bytes)):
- for nested in value:
- records.extend(_exact_content_records(nested, expected_content))
- return records
-
-
-def _collection_name(
- embedding_provider: ProviderKind,
- embedding_base_url: str,
- embedding_model: str,
- *,
- declared_dimensions: str | None = None,
-) -> str:
- """Name the collection after the embedding space that fills it.
-
- The declared width is deliberately not part of the identity: the store
- already carries the real width, and folding a value we merely *learn*
- into the name would strand every memory written before we measured it.
- """
- parts = [embedding_provider.value, embedding_base_url, embedding_model]
- if declared_dimensions is not None:
- parts.append(declared_dimensions)
- suffix = hashlib.sha256(":".join(parts).encode()).hexdigest()[:12]
- return f"one_memory_{suffix}"
-
-
-def reattach_legacy_vector_collection(profile: ModelProfileSnapshot, config: Any) -> str | None:
- """Rename a collection this embedding space filled under an older name.
-
- Returns the migrated legacy name, or None when nothing had to move.
- """
- persist = getattr(config.vector_store, "persist_directory", None)
- if not persist:
- return None
- database = Path(persist) / "chroma.sqlite3"
- if not database.exists():
- return None
- embedding_provider = profile.embedding_provider_kind or profile.provider_kind
- # The config holds the normalized endpoint the collection was named after.
- embedding_base_url = getattr(config.embedder, "base_url", "") or ""
- if not profile.embedding_model:
- return None
- expected = config.vector_store.collection_name
- legacy_names = [
- _collection_name(
- embedding_provider,
- embedding_base_url,
- profile.embedding_model,
- declared_dimensions=declared,
- )
- for declared in ("auto", str(profile.embedding_dimensions or "auto"))
- ]
- legacy_names = [name for name in dict.fromkeys(legacy_names) if name != expected]
- if not legacy_names:
- return None
- try:
- with closing(sqlite3.connect(database)) as connection, connection:
- rows = connection.execute("SELECT id, name, dimension FROM collections").fetchall()
- stored = {
- str(name): (str(identifier), dimension) for identifier, name, dimension in rows
- }
- if any(str(name).startswith(f"{expected}_") for name in stored):
- return None
- for legacy in legacy_names:
- match = next(
- (name for name in stored if name.startswith(f"{legacy}_")),
- None,
- )
- if match is None:
- continue
- _identifier, dimension = stored[match]
- width = getattr(config.vector_store, "embedding_dims", None)
- if dimension is None or (width and int(dimension) != int(width)):
- continue
- renamed = f"{expected}_{int(dimension)}"
- connection.execute(
- "UPDATE collections SET name = ? WHERE name = ?",
- (renamed, match),
- )
- logging.getLogger(__name__).warning(
- "reattached hy vector collection %s as %s", match, renamed
- )
- return match
- except sqlite3.Error:
- return None
- return None
-
-
-def inspect_graph_width_mismatch(config: Any) -> GraphWidthMismatch | None:
- """Return the mismatch if an existing graph disagrees with the model width.
-
- Never renames or deletes anything. Callers that want to proceed with a new
- width must go through `apply_graph_width_decision`.
- """
- db_path = Path(config.graph_store.db_path)
- if not db_path.exists():
- return None
- expected = getattr(config.vector_store, "embedding_dims", None) or getattr(
- getattr(config, "embedder", None), "embedding_dims", None
- )
- if not expected:
- return None
- stored = _graph_embedding_width(db_path)
- if stored is None or stored == int(expected):
- return None
- return GraphWidthMismatch(
- stored_width=int(stored),
- expected_width=int(expected),
- graph_path=str(db_path),
- )
-
-
-def inspect_profile_graph_width(
- profile: ModelProfileSnapshot,
- *,
- api_key: str | None,
- data_dir: Path,
-) -> GraphWidthMismatch | None:
- """The mismatch a client create would raise on, without creating one.
-
- Same config as `create_hy_memory_client` builds, so the answer the app
- shows is the answer extraction will hit. Read-only.
- """
- return inspect_graph_width_mismatch(
- _graph_width_config(profile, api_key=api_key, data_dir=data_dir)
- )
-
-
-def decide_profile_graph_width(
- profile: ModelProfileSnapshot,
- *,
- api_key: str | None,
- data_dir: Path,
- decision: GraphWidthDecision,
-) -> GraphWidthOutcome:
- """Act on the mismatch for this profile.
-
- Exports land beside the data directory rather than inside it, because a
- rebuild rewrites what is inside.
- """
- return apply_graph_width_decision(
- _graph_width_config(profile, api_key=api_key, data_dir=data_dir),
- decision,
- export_root=data_dir.parent,
- )
-
-
-def _graph_width_config(
- profile: ModelProfileSnapshot,
- *,
- api_key: str | None,
- data_dir: Path,
-) -> Any:
- configure_hy_memory_environment(data_dir)
- config = build_hy_memory_config(profile, api_key=api_key, data_dir=data_dir)
- reattach_legacy_vector_collection(profile, config)
- return config
-
-
-def apply_graph_width_decision(
- config: Any,
- decision: GraphWidthDecision,
- *,
- export_root: Path | None = None,
-) -> GraphWidthOutcome:
- """Act on a width mismatch the way the user chose.
-
- KEEP_EXISTING changes nothing. REBUILD_WITH_NEW archives the graph.
- EXPORT_FIRST copies it and leaves the question open — it is preparation
- for a decision, not one. Calling this without a mismatch is a no-op.
- """
- mismatch = inspect_graph_width_mismatch(config)
- if mismatch is None:
- return GraphWidthOutcome()
- if decision is GraphWidthDecision.REBUILD_WITH_NEW:
- archive = retire_mismatched_graph_store(config)
- return GraphWidthOutcome(archived_path=str(archive) if archive is not None else None)
- if decision is GraphWidthDecision.EXPORT_FIRST:
- if export_root is None:
- raise HyMemoryBridgeError("export_root_required")
- return GraphWidthOutcome(
- exported_path=str(export_graph_store(config, export_root=export_root))
- )
- return GraphWidthOutcome()
-
-
-def export_graph_store(config: Any, *, export_root: Path) -> Path:
- """Copy the graph somewhere a rebuild cannot reach, all or nothing.
-
- Two things this must not do. It must not write inside the data directory,
- because REBUILD_WITH_NEW rewrites that directory and the "backup" would go
- with it. And it must not leave a partial copy behind on failure: a
- half-written graph is indistinguishable from a good one at a glance, so
- the user would rebuild on the strength of it. Staged under a `.partial`
- name and renamed only once every file is across.
- """
- db_path = Path(config.graph_store.db_path)
- stamp = datetime.now(UTC).strftime("%Y%m%dT%H%M%S%fZ")
- destination = export_root / f"one-memory-graph-{stamp}"
- staging = destination.with_name(f"{destination.name}.partial")
- sources = [db_path] + [
- sibling
- for suffix in (".wal", ".shadow", ".tmp")
- if (sibling := db_path.with_name(f"{db_path.name}{suffix}")).exists()
- ]
- try:
- staging.mkdir(parents=True)
- for source in sources:
- shutil.copy2(source, staging / source.name)
- staging.rename(destination)
- except BaseException:
- shutil.rmtree(staging, ignore_errors=True)
- raise
- logging.getLogger(__name__).info(
- "exported hy graph store to %s (%d files)",
- destination,
- len(sources),
- )
- return destination
-
-
-def retire_mismatched_graph_store(config: Any) -> Path | None:
- """Archive a Kuzu graph whose embedding width no longer matches the model.
-
- Only call this through `apply_graph_width_decision(REBUILD_WITH_NEW)`.
- Direct callers used to run this unconditionally on client create, which is
- how a live graph got retired without anyone choosing to.
- """
- db_path = Path(config.graph_store.db_path)
- if not db_path.exists():
- return None
- expected = getattr(config.vector_store, "embedding_dims", None) or getattr(
- getattr(config, "embedder", None), "embedding_dims", None
- )
- if not expected:
- return None
- stored = _graph_embedding_width(db_path)
- if stored is None or stored == int(expected):
- return None
- stamp = datetime.now(UTC).strftime("%Y%m%dT%H%M%SZ")
- archive = db_path.with_name(f"{db_path.name}.dim{stored}.{stamp}.bak")
- db_path.rename(archive)
- for suffix in (".wal", ".shadow", ".tmp"):
- sibling = db_path.with_name(f"{db_path.name}{suffix}")
- if sibling.exists():
- sibling.rename(archive.with_name(f"{archive.name}{suffix}"))
- logging.getLogger(__name__).warning(
- "retired hy graph store with embedding width %s (model expects %s): %s",
- stored,
- expected,
- archive.name,
- )
- return archive
-
-
-# The graph store's embedding width is a property of the file, and reading it
-# used to open a kuzu Database on every call and then `del` it plus
-# `gc.collect()`. kuzu is a C++ library with its own background threads, so
-# repeatedly building and tearing that object down corrupted the heap: 25 of
-# 26 crash reports pointed at kuzu, three of them at
-# `kuzu::common::NullMask::setNullRange`, and four aborted inside malloc with
-# `free_list_checksum_botch`. Cache the answer per resolved path instead, and
-# never open a second Database for a path already known.
-_GRAPH_WIDTH_CACHE: dict[str, int | None] = {}
-_GRAPH_WIDTH_LOCK = threading.Lock()
-
-
-def _graph_embedding_width(db_path: Path) -> int | None:
- try:
- kuzu = import_module("kuzu")
- except ModuleNotFoundError:
- return None
- key = str(db_path.resolve())
- with _GRAPH_WIDTH_LOCK:
- if key in _GRAPH_WIDTH_CACHE:
- return _GRAPH_WIDTH_CACHE[key]
- try:
- database = kuzu.Database(str(db_path), read_only=True)
- except Exception:
- # A store we cannot open has no width to report; do not cache the
- # failure, because the file may still be being created.
- return None
- width: int | None = None
- try:
- connection = kuzu.Connection(database)
- result = connection.execute("CALL TABLE_INFO('Memory') RETURN *")
- while result.has_next():
- row = result.get_next()
- if len(row) < 3 or row[1] != "embedding":
- continue
- match = re.search(r"\[(\d+)\]", str(row[2]))
- width = int(match.group(1)) if match else None
- break
- except Exception:
- width = None
- with _GRAPH_WIDTH_LOCK:
- _GRAPH_WIDTH_CACHE[key] = width
- return width
-
-
-def configure_hy_memory_environment(data_dir: Path) -> None:
- configure_hy_runtime_environment(data_dir)
- apply_diagnostic_log_level(diagnostic_log_level(data_dir))
diff --git a/memhub/apps/core/src/one_memory/hy_response_guard.py b/memhub/apps/core/src/one_memory/hy_response_guard.py
deleted file mode 100644
index 14e0f82..0000000
--- a/memhub/apps/core/src/one_memory/hy_response_guard.py
+++ /dev/null
@@ -1,331 +0,0 @@
-"""Transport validation for the pinned HY SDK; HY's prompts and decisions pass through unchanged."""
-
-import logging
-from contextlib import nullcontext
-from time import monotonic
-from typing import Any
-
-from one_memory.diagnostic_log import diagnostic_event, diagnostic_exception, elapsed_ms
-from one_memory.hy_source_context import HyWriteBindings
-from one_memory.hy_step_timing import HyStepTimer
-
-
-def _http_status(value: Any) -> int | None:
- return value if type(value) is int and 100 <= value <= 599 else None
-
-
-def _exception_status(error: Exception) -> int | None:
- try:
- status = _http_status(getattr(error, "status_code", None))
- if status is not None:
- return status
- status = _http_status(getattr(getattr(error, "response", None), "status_code", None))
- if status is not None:
- return status
- # Native LLMRetryError retains sanitized attempt dictionaries. Only the
- # final attempt describes the terminal failure; never parse error text.
- attempts = getattr(error, "attempts", None)
- if isinstance(attempts, (list, tuple)) and attempts and isinstance(attempts[-1], dict):
- return _http_status(attempts[-1].get("status_code"))
- except Exception:
- # Diagnostic attribute access must not replace the provider exception.
- return None
- return None
-
-
-def _model_failure_code(status: int | None) -> str:
- specific = {
- 401: "hy_memory_model_authentication_failed",
- 402: "hy_memory_model_payment_required",
- 403: "hy_memory_model_access_denied",
- 408: "hy_memory_model_timeout",
- 429: "hy_memory_model_rate_limited",
- }
- if status in specific:
- return specific[status]
- if status is not None and 500 <= status <= 599:
- return "hy_memory_model_service_unavailable"
- if status is not None and 400 <= status <= 422:
- return "hy_memory_model_request_incompatible"
- return "hy_memory_model_request_failed"
-
-
-def _terminal_client_timeout(error: Exception) -> bool:
- try:
- attempts = getattr(error, "attempts", None)
- if not isinstance(attempts, (list, tuple)) or not attempts:
- return False
- final = attempts[-1]
- if type(final) is not dict:
- return False
- kind = final.get("failure_kind")
- return type(kind) is str and kind == "timeout"
- except Exception:
- return False
-
-
-class HyResponseGuard:
- def __init__(self, provider: Any, *, phase: str = "extract") -> None:
- self.provider = provider
- #: Diagnostic label only; the request passes through unchanged.
- self.phase = phase
- self.failures: list[str] = []
-
- def __getattr__(self, name: str) -> Any:
- return getattr(self.provider, name)
-
- async def complete(self, *args: Any, **kwargs: Any) -> Any:
- return await self._complete("complete", args, kwargs)
-
- async def complete_messages(self, *args: Any, **kwargs: Any) -> Any:
- return await self._complete("complete_messages", args, kwargs)
-
- async def _complete(self, method: str, args: tuple[Any, ...], kwargs: dict[str, Any]) -> Any:
- for attempt in range(2):
- started = monotonic()
- try:
- response = await getattr(self.provider, method)(*args, **kwargs)
- except Exception as error:
- status = _exception_status(error)
- code = (
- "hy_memory_model_timeout"
- if status is None and _terminal_client_timeout(error)
- else _model_failure_code(status)
- )
- self.failures.append(code)
- logging.getLogger(__name__).warning(
- "%s: status_code=%s", code, status if status is not None else "unknown"
- )
- diagnostic_event(
- level="error",
- component="hy.model",
- event="hy.model_call.failed",
- outcome="failed",
- duration_ms=elapsed_ms(started),
- error_code=code,
- **diagnostic_exception(error),
- details={"phase": self.phase, "attempt": attempt + 1, "call_count": 1},
- )
- raise
- truncated = getattr(response, "finish_reason", "") == "length"
- empty = not (response.content or "").strip() and not getattr(
- response, "tool_calls", None
- )
- if not truncated and not empty:
- diagnostic_event(
- level="info",
- component="hy.model",
- event="hy.model_call.completed",
- outcome="succeeded",
- duration_ms=elapsed_ms(started),
- details={"phase": self.phase, "attempt": attempt + 1, "call_count": 1},
- )
- return response
- code = (
- "hy_memory_model_output_truncated"
- if truncated
- else "hy_memory_model_empty_response"
- )
- if attempt:
- self.failures.append(code)
- raise ValueError(code)
- logging.getLogger(__name__).warning("%s: retrying the same HY model request", code)
- if truncated and "max_tokens" in kwargs:
- kwargs = {**kwargs, "max_tokens": min(16000, kwargs["max_tokens"] * 2)}
- raise AssertionError("unreachable")
-
-
-class HyReconcileGuard:
- #: Set only for the span of one leased write.
- step_timer: HyStepTimer | None = None
-
- def __init__(self, reconciler: Any) -> None:
- self.reconciler = reconciler
- self.failures: list[str] = []
- self.bindings: HyWriteBindings | None = None
- self.imported_contents: frozenset[str] | None = None
- self.mutation_target_ids: set[str] = set()
-
- def begin_write(self) -> None:
- self.mutation_target_ids.clear()
-
- def __getattr__(self, name: str) -> Any:
- return getattr(self.reconciler, name)
-
- async def reconcile(self, *args: Any, **kwargs: Any) -> Any:
- timer = self.step_timer
- with timer.step("reconcile") if timer is not None else nullcontext():
- return await self._reconcile(args, kwargs)
-
- async def _reconcile(self, args: tuple[Any, ...], kwargs: dict[str, Any]) -> Any:
- started = monotonic()
- if self.imported_contents is not None:
- metadata = kwargs.get("new_memories_with_meta") or []
- texts = kwargs.get("new_memories") or []
- if (
- not metadata
- or not texts
- or any(
- not isinstance(item, dict) or item.get("content") not in self.imported_contents
- for item in metadata
- )
- or any(text not in self.imported_contents for text in texts)
- or {item["content"] for item in metadata} != set(texts)
- ):
- code = "hy_memory_write_verification_import_input_mismatch"
- self.failures.append(code)
- raise ValueError(code)
- try:
- result = await self.reconciler.reconcile(*args, **kwargs)
- except Exception as error:
- diagnostic_event(
- level="error",
- component="hy.reconcile",
- event="hy.reconcile.failed",
- outcome="failed",
- duration_ms=elapsed_ms(started),
- error_code="hy_memory_reconcile_failed",
- **diagnostic_exception(error),
- )
- raise
- if not result.success:
- self.failures.append("hy_memory_reconcile_failed")
- diagnostic_event(
- level="error",
- component="hy.reconcile",
- event="hy.reconcile.failed",
- outcome="failed",
- duration_ms=elapsed_ms(started),
- error_code="hy_memory_reconcile_failed",
- details={"result_count": len(result.ops)},
- )
- return result
- try:
- await self._check_targets(result, kwargs)
- except ValueError as error:
- code = str(error)
- self.failures.append(code)
- raise
- except Exception as error:
- code = "hy_memory_write_verification_failed"
- self.failures.append(code)
- raise ValueError(code) from error
- owners: dict[str, set[str]] = {}
- for item in kwargs.get("new_memories_with_meta") or []:
- if item.get("owner") in {"user", "agent"}:
- owners.setdefault(item["content"], set()).add(item["owner"])
- # HY's no-candidate ADD path copies content verbatim but omits owner.
- # Restore only an unambiguous exact match, never infer from wording.
- for operation in result.ops:
- source_owners = owners.get(operation.content, set())
- if operation.op == "ADD" and operation.owner is None and len(source_owners) == 1:
- operation.owner = next(iter(source_owners))
- operation_counts = {"ADD": 0, "UPDATE": 0, "SUPERSEDE": 0, "DELETE": 0}
- for operation in result.ops:
- raw_name = getattr(operation, "op", "")
- name = str(getattr(raw_name, "value", raw_name)).upper()
- if name in {"UPDATE", "SUPERSEDE", "DELETE", "SHADOW"}:
- target = getattr(operation, "memory_id", None)
- if isinstance(target, str) and target:
- self.mutation_target_ids.add(target)
- self.mutation_target_ids.update(
- key
- for key in getattr(operation, "memory_ids", ())
- if isinstance(key, str) and key
- )
- if name == "ADD":
- operation_counts["ADD"] += 1
- elif name in {"UPDATE", "MERGE", "NOOP"}:
- operation_counts["UPDATE"] += 1
- elif name == "SUPERSEDE":
- operation_counts["SUPERSEDE"] += 1
- elif name in {"DELETE", "SHADOW"}:
- operation_counts["DELETE"] += 1
- diagnostic_event(
- level="info",
- component="hy.reconcile",
- event="hy.reconcile.completed",
- outcome="succeeded",
- duration_ms=elapsed_ms(started),
- details={
- "created_count": operation_counts["ADD"],
- "updated_count": operation_counts["UPDATE"],
- "superseded_count": operation_counts["SUPERSEDE"],
- "deleted_count": operation_counts["DELETE"],
- "result_count": len(result.ops),
- },
- )
- return result
-
- async def _check_targets(self, result: Any, kwargs: dict[str, Any]) -> None:
- """HY may only touch nodes of this user and scope that this write was allowed to see."""
- targets = {op.memory_id for op in result.ops if op.memory_id}
- targets.update(key for op in result.ops for key in getattr(op, "memory_ids", []))
- for key in targets:
- node = await kwargs["vector_store"].get_by_id(key)
- if (
- node is None
- or node.user_id != kwargs["user_id"]
- or node.agent_id != kwargs["agent_id"]
- ):
- raise ValueError("hy_memory_write_verification_target_invalid")
- if self.bindings is not None:
- known = self.bindings.known.get(key)
- if known is None or (known.content, known.owner) != (node.content, node.owner):
- raise ValueError("hy_memory_write_verification_target_unbound")
- if self.bindings is None:
- return
- for op in result.ops:
- if not op.content:
- continue
- linked = {key for key in (op.memory_id, *getattr(op, "memory_ids", [])) if key}
- self.bindings.record_operation_support(op.content, op.owner, linked)
- if op.memory_id:
- self.bindings.verified_operations[op.memory_id] = (op.content, op.owner)
-
-
-def install_hy_write_guards(client: Any) -> None:
- """The pinned HY SDK treats an empty reconcile response as a successful empty op list.
-
- Bind this client's real write paths. Pro/lite use the ordinary writer;
- ultra uses the System2 writer's inner writer. Keep HY prompts, extraction,
- retrieval, reconciliation and storage intact; never patch the shared SDK
- installation.
- """
-
- async def install() -> None:
- from one_memory.hy_write_verification import HyExtractionGuard
-
- ordinary = await client._registry.get_writer()
- system2 = await client._registry.get_system2_writer()
- guards: list[Any] = []
- seen_writers: set[int] = set()
- seen_guards: set[int] = set()
- for writer in (ordinary, system2._writer):
- if id(writer) in seen_writers:
- continue
- seen_writers.add(id(writer))
- agent = writer.mem_agent
- if not isinstance(agent.llm_provider, HyResponseGuard):
- agent.llm_provider = HyResponseGuard(agent.llm_provider)
- agent.extractor.llm = agent.llm_provider
- if not isinstance(agent.extractor, HyExtractionGuard):
- agent.extractor = HyExtractionGuard(agent.extractor)
- reconciler = writer.reconciler
- provider = reconciler._get_llm()
- if not isinstance(provider, HyResponseGuard):
- reconciler._llm = HyResponseGuard(provider, phase="reconcile")
- if not isinstance(reconciler, HyReconcileGuard):
- writer._reconciler = HyReconcileGuard(reconciler)
- for guard in (
- agent.llm_provider,
- reconciler._llm,
- writer._reconciler,
- agent.extractor,
- ):
- if id(guard) not in seen_guards:
- seen_guards.add(id(guard))
- guards.append(guard)
- client._one_memory_write_guards = tuple(guards)
-
- client._loop_thread.run(install())
diff --git a/memhub/apps/core/src/one_memory/hy_runtime_config.py b/memhub/apps/core/src/one_memory/hy_runtime_config.py
index 66c2603..3c47acd 100644
--- a/memhub/apps/core/src/one_memory/hy_runtime_config.py
+++ b/memhub/apps/core/src/one_memory/hy_runtime_config.py
@@ -33,49 +33,8 @@ _COLLECTION_LOGGERS = (
)
_NOISY_LIBRARY_LOGGERS = ("httpx", "httpcore", "watchfiles", "jieba")
-# One Memory deliberately stays on ultra because its existing, user-visible
-# profile/graph flow calls digest(), which the pinned public SDK exposes only
-# for ultra clients. Reader and non-reranker behavior remain pinned for
-# compatibility with the SDK authority-migration development preview.
-HY_MEMORY_MODE = "ultra"
-# The SDK only recognises `legacy` and `hybrid` (see
-# hy_memory/pipelines/_retrieval/config.py: `ALL_READERS = (READER_LEGACY,
-# READER_HYBRID)`). The old spelling `hybrid_v2` was silently rejected and
-# fell back to legacy, so the hybrid-v2 recall strategy never ran at all.
HY_MEMORY_READER = "hybrid"
-HY_MEMORY_BEHAVIOR_ENV: dict[str, str] = {
- "MEMORY_MODE": HY_MEMORY_MODE,
- "MEMORY_ENABLE_GRAPH": "true",
- "MEMORY_GRAPH_RERANK_ENABLED": "false",
- "MEMORY_GRAPH_TEMPORAL_SPINE": "true",
- "MEMORY_TOPIC_SUMMARY_ENABLED": "false",
- "MEMORY_EPISODE_SUMMARY_ENABLED": "false",
- "MEMORY_EPISODE_RECALL_ENABLED": "true",
- "MEMORY_DYNAMIC_EPISODE_ENABLED": "true",
- "MEMORY_SESSION_EPISODE_ENABLED": "false",
- "MEMORY_SESSION_EPISODE_CONTEXT_ENABLED": "false",
- "MEMORY_EPISODE_CAPSULE_CONTEXT_ENABLED": "true",
- "MEMORY_EPISODE_CAPSULE_QUERY_MIN": "0.65",
- "MEMORY_EPISODE_CAPSULE_ASSIGNMENT_MIN": "0.60",
- "MEMORY_EPISODE_CAPSULE_FIRST_RANK_MAX": "3",
- "MEMORY_EPISODE_CAPSULE_MEMBER_LIMIT": "3",
- "MEMORY_ENABLE_INTENTION": "false",
- "MEMORY_ENABLE_QUERY_REWRITE": "false",
- "MEMORY_FEW_SHOT_ENABLED": "true",
- "MEMORY_HYBRID_V2_QUERY_EXPAND": "1",
- "MEMORY_HYBRID_V2_GEO_INTENT_PRIOR": "0.6",
- "MEMORY_HYBRID_V2_DIVERSITY": "1",
- "MEMORY_HYBRID_V2_TEMPORAL_ADMIT_PRIOR": "0.55",
- "MEMORY_HYBRID_V2_TEMPORAL_BOOST": "0.18",
- "MEMORY_CROSS_DOMAIN_CON_THRESHOLD": "0.5",
- "MEMORY_READER_ENABLE_SUMMARY": "false",
- "MEMORY_SUMMARY_ENABLED_IN_SYS2": "false",
- "MEMORY_LOCAL_RERANK_ENABLED": "false",
- "RECONCILE_ENABLED": "true",
- "HY_MEMORY_READER": HY_MEMORY_READER,
-}
-
def detailed_logging_enabled(data_dir: Path) -> bool:
return diagnostic_log_level(data_dir) == "debug"
@@ -168,7 +127,6 @@ def configure_hy_runtime_environment(data_dir: Path) -> None:
log_dir = memory_root / "logs"
memory_root.mkdir(parents=True, exist_ok=True)
log_dir.mkdir(parents=True, exist_ok=True)
- os.environ.update(HY_MEMORY_BEHAVIOR_ENV)
os.environ["MEMORY_DATA_DIR"] = str(memory_root)
os.environ["MEMORY_LOG_DIR"] = str(log_dir)
level = diagnostic_log_level(data_dir)
@@ -178,9 +136,3 @@ def configure_hy_runtime_environment(data_dir: Path) -> None:
os.environ["MEMORY_MEMORY_OPERATIONS_ENABLED"] = "false"
os.environ["ANONYMIZED_TELEMETRY"] = "False"
os.environ.pop("CHROMA_OTEL_COLLECTION_ENDPOINT", None)
-
-
-def configure_hy_behavior_environment() -> None:
- """Set import-time HY behavior flags without touching paths or secrets."""
-
- os.environ.update(HY_MEMORY_BEHAVIOR_ENV)
diff --git a/memhub/apps/core/src/one_memory/hy_sdk_migration.py b/memhub/apps/core/src/one_memory/hy_sdk_migration.py
new file mode 100644
index 0000000..869ee3b
--- /dev/null
+++ b/memhub/apps/core/src/one_memory/hy_sdk_migration.py
@@ -0,0 +1,381 @@
+"""Migration-only access to the HY SDK's public inventory and import APIs."""
+
+from __future__ import annotations
+
+import asyncio
+from collections.abc import Callable, Mapping
+from datetime import datetime
+from pathlib import Path
+from typing import Protocol
+
+from hy_memory import ( # type: ignore[import-untyped]
+ DataPlaneRestore,
+ DataPlaneSnapshot,
+ restore_local_data_plane,
+ snapshot_local_data_plane,
+)
+
+from one_memory.hy_sdk_types import (
+ HySdkMemoryPage,
+ HySdkMemoryRecord,
+ HySdkMigrationError,
+ HySdkRawPage,
+ HySdkRawRecord,
+)
+
+
+class MigrationClient(Protocol):
+ def list_memories(
+ self,
+ *,
+ user_id: str,
+ agent_id: str | None = None,
+ statuses: list[str] | None = None,
+ limit: int = 100,
+ offset: int = 0,
+ order: str = "desc",
+ ) -> Mapping[str, object]: ...
+
+ def import_memory_exact(self, content: str, **kwargs: object) -> Mapping[str, object]: ...
+
+ def list_raw(
+ self,
+ *,
+ user_id: str,
+ agent_id: str | None = None,
+ session_id: str | None = None,
+ source: str | None = None,
+ limit: int = 100,
+ offset: int = 0,
+ order: str = "desc",
+ ) -> Mapping[str, object]: ...
+
+ def import_raw(self, content: str, **kwargs: object) -> Mapping[str, object]: ...
+
+ def delete(self, memory_id: str) -> Mapping[str, object]: ...
+
+ def get_write_outcome(self, request_id: str) -> Mapping[str, object] | None: ...
+
+
+class HySdkMigration:
+ """Typed async adapter over the SDK's exact migration primitives."""
+
+ def __init__(self, client: MigrationClient) -> None:
+ self.client = client
+
+ async def list_memories(
+ self,
+ *,
+ user_id: str,
+ agent_id: str | None = None,
+ statuses: tuple[str, ...] = ("active",),
+ limit: int = 100,
+ offset: int = 0,
+ order: str = "desc",
+ ) -> HySdkMemoryPage:
+ raw = await _sdk_call(
+ "hy_sdk_memory_list_failed",
+ self.client.list_memories,
+ user_id=user_id,
+ agent_id=agent_id,
+ statuses=list(statuses),
+ limit=limit,
+ offset=offset,
+ order=order,
+ )
+ return _memory_page(raw, limit=limit, offset=offset)
+
+ async def import_memory_exact(
+ self,
+ *,
+ content: str,
+ memory_id: str,
+ user_id: str,
+ agent_id: str,
+ session_id: str,
+ source: str,
+ layer: str,
+ status: str,
+ owner: str | None,
+ tags: tuple[str, ...],
+ supersedes: tuple[str, ...],
+ superseded_by: tuple[str, ...],
+ is_latest: bool,
+ memory_at: datetime | None,
+ metadata: Mapping[str, object],
+ request_id: str,
+ ) -> dict[str, object]:
+ raw = await _sdk_call(
+ "hy_sdk_memory_import_failed",
+ self.client.import_memory_exact,
+ content,
+ memory_id=memory_id,
+ user_id=user_id,
+ agent_id=agent_id,
+ session_id=session_id,
+ source=source,
+ layer=layer,
+ status=status,
+ owner=owner,
+ tags=list(tags),
+ supersedes=list(supersedes),
+ superseded_by=list(superseded_by),
+ is_latest=is_latest,
+ memory_at=memory_at,
+ metadata=dict(metadata),
+ request_id=request_id,
+ )
+ return _successful_result(raw, "hy_sdk_memory_import_failed")
+
+ async def list_raw(
+ self,
+ *,
+ user_id: str,
+ agent_id: str | None = None,
+ session_id: str | None = None,
+ source: str | None = None,
+ limit: int = 100,
+ offset: int = 0,
+ order: str = "desc",
+ ) -> HySdkRawPage:
+ raw = await _sdk_call(
+ "hy_sdk_raw_list_failed",
+ self.client.list_raw,
+ user_id=user_id,
+ agent_id=agent_id,
+ session_id=session_id,
+ source=source,
+ limit=limit,
+ offset=offset,
+ order=order,
+ )
+ return _raw_page(raw, limit=limit, offset=offset)
+
+ async def import_raw(
+ self,
+ *,
+ content: str,
+ raw_id: str,
+ user_id: str,
+ agent_id: str,
+ session_id: str,
+ source: str,
+ memory_at: datetime | None,
+ metadata: Mapping[str, object],
+ request_id: str,
+ ) -> dict[str, object]:
+ raw = await _sdk_call(
+ "hy_sdk_raw_import_failed",
+ self.client.import_raw,
+ content,
+ raw_id=raw_id,
+ user_id=user_id,
+ agent_id=agent_id,
+ session_id=session_id,
+ source=source,
+ memory_at=memory_at,
+ metadata=dict(metadata),
+ request_id=request_id,
+ )
+ return _successful_result(raw, "hy_sdk_raw_import_failed")
+
+ async def delete(self, memory_id: str) -> dict[str, object]:
+ raw = await _sdk_call(
+ "hy_sdk_memory_delete_failed",
+ self.client.delete,
+ memory_id,
+ )
+ return _successful_result(raw, "hy_sdk_memory_delete_failed")
+
+ async def get_write_outcome(self, request_id: str) -> dict[str, object] | None:
+ raw = await _sdk_call(
+ "hy_sdk_write_outcome_failed",
+ self.client.get_write_outcome,
+ request_id,
+ )
+ if raw is None:
+ return None
+ if not isinstance(raw, Mapping):
+ raise HySdkMigrationError("hy_sdk_write_outcome_shape_invalid")
+ return dict(raw)
+
+
+def snapshot_data_plane(
+ *,
+ source_root: Path,
+ target_root: Path,
+ writers_stopped: bool,
+) -> DataPlaneSnapshot:
+ """Snapshot an explicitly quiesced SDK-owned local data plane."""
+ return snapshot_local_data_plane(
+ source_root=source_root,
+ target_root=target_root,
+ writers_stopped=writers_stopped,
+ )
+
+
+def restore_data_plane(
+ *,
+ snapshot_root: Path,
+ target_root: Path,
+ writers_stopped: bool,
+ protective_root: Path | None = None,
+) -> DataPlaneRestore:
+ """Restore an explicitly quiesced SDK-owned local data plane."""
+ return restore_local_data_plane(
+ snapshot_root=snapshot_root,
+ target_root=target_root,
+ writers_stopped=writers_stopped,
+ protective_root=protective_root,
+ )
+
+
+async def _sdk_call[T](
+ code: str,
+ call: Callable[..., T],
+ *args: object,
+ **kwargs: object,
+) -> T:
+ pending = asyncio.create_task(asyncio.to_thread(call, *args, **kwargs))
+ try:
+ return await asyncio.shield(pending)
+ except asyncio.CancelledError:
+ await _finish_cancelled_call(pending)
+ raise
+ except Exception as error:
+ raise HySdkMigrationError(code) from error
+
+
+async def _finish_cancelled_call[T](pending: asyncio.Task[T]) -> None:
+ while not pending.done():
+ try:
+ await asyncio.shield(pending)
+ except asyncio.CancelledError:
+ continue
+ except Exception:
+ return
+ if not pending.cancelled():
+ pending.exception()
+
+
+def _memory_page(raw: object, *, limit: int, offset: int) -> HySdkMemoryPage:
+ if not isinstance(raw, Mapping):
+ raise HySdkMigrationError("hy_sdk_memory_page_shape_invalid")
+ rows: list[object] = []
+ total = 0
+ for bucket_name, row_name in (("vdb", "memories"), ("graph", "nodes")):
+ bucket = raw.get(bucket_name)
+ if bucket is None and bucket_name == "graph":
+ continue
+ if not isinstance(bucket, Mapping):
+ raise HySdkMigrationError("hy_sdk_memory_page_shape_invalid")
+ bucket_rows = bucket.get(row_name)
+ bucket_total = bucket.get("total")
+ if not isinstance(bucket_rows, list) or type(bucket_total) is not int or bucket_total < 0:
+ raise HySdkMigrationError("hy_sdk_memory_page_shape_invalid")
+ rows.extend(bucket_rows)
+ total += bucket_total
+
+ records: dict[str, HySdkMemoryRecord] = {}
+ for row in rows:
+ record = _memory_record(row)
+ records.setdefault(record.memory_id, record)
+ return HySdkMemoryPage(
+ memories=tuple(records.values()),
+ total=total,
+ limit=limit,
+ offset=offset,
+ )
+
+
+def _memory_record(raw: object) -> HySdkMemoryRecord:
+ if not isinstance(raw, Mapping):
+ raise HySdkMigrationError("hy_sdk_memory_record_shape_invalid")
+ required = ("memory_id", "content", "layer", "status", "user_id", "agent_id")
+ if any(not isinstance(raw.get(name), str) or not raw[name] for name in required):
+ raise HySdkMigrationError("hy_sdk_memory_record_shape_invalid")
+ custom = raw.get("custom")
+ source_raw_ids: list[object] = []
+ if isinstance(custom, Mapping) and isinstance(custom.get("source_raw_memory_ids"), list):
+ source_raw_ids.extend(custom["source_raw_memory_ids"])
+ if isinstance(raw.get("source_raw_memory_id"), str):
+ source_raw_ids.append(raw["source_raw_memory_id"])
+ try:
+ return HySdkMemoryRecord(
+ memory_id=raw["memory_id"],
+ content=raw["content"],
+ layer=raw["layer"],
+ status=raw["status"],
+ is_latest=bool(raw.get("is_latest", True)),
+ supersedes=_string_tuple(raw.get("supersedes")),
+ superseded_by=_string_tuple(raw.get("superseded_by")),
+ tags=_string_tuple(raw.get("tags")),
+ owner=raw.get("owner") if raw.get("owner") in {"user", "agent"} else None,
+ source_raw_ids=_string_tuple(source_raw_ids),
+ user_id=raw["user_id"],
+ agent_id=raw["agent_id"],
+ session_id=_optional_string(raw.get("session_id")),
+ source=_optional_string(raw.get("source")),
+ memory_at=_optional_int(raw.get("memory_at")),
+ gmt_created=_optional_int(raw.get("gmt_created")),
+ )
+ except (TypeError, ValueError) as error:
+ raise HySdkMigrationError("hy_sdk_memory_record_shape_invalid") from error
+
+
+def _raw_page(raw: object, *, limit: int, offset: int) -> HySdkRawPage:
+ if not isinstance(raw, Mapping):
+ raise HySdkMigrationError("hy_sdk_raw_page_shape_invalid")
+ rows = raw.get("raw")
+ total = raw.get("total")
+ if not isinstance(rows, list) or type(total) is not int or total < 0:
+ raise HySdkMigrationError("hy_sdk_raw_page_shape_invalid")
+ return HySdkRawPage(
+ raw=tuple(_raw_record(row) for row in rows),
+ total=total,
+ limit=limit,
+ offset=offset,
+ )
+
+
+def _raw_record(raw: object) -> HySdkRawRecord:
+ if not isinstance(raw, Mapping):
+ raise HySdkMigrationError("hy_sdk_raw_record_shape_invalid")
+ required = ("raw_id", "content", "user_id", "agent_id", "session_id", "source")
+ if any(not isinstance(raw.get(name), str) or not raw[name] for name in required):
+ raise HySdkMigrationError("hy_sdk_raw_record_shape_invalid")
+ custom = raw.get("custom")
+ try:
+ return HySdkRawRecord(
+ raw_id=raw["raw_id"],
+ content=raw["content"],
+ user_id=raw["user_id"],
+ agent_id=raw["agent_id"],
+ session_id=raw["session_id"],
+ source=raw["source"],
+ memory_at=_optional_int(raw.get("memory_at")),
+ gmt_created=_optional_int(raw.get("gmt_created")),
+ custom=dict(custom) if isinstance(custom, Mapping) else {},
+ )
+ except (TypeError, ValueError) as error:
+ raise HySdkMigrationError("hy_sdk_raw_record_shape_invalid") from error
+
+
+def _successful_result(raw: object, code: str) -> dict[str, object]:
+ if not isinstance(raw, Mapping) or raw.get("success") is not True:
+ raise HySdkMigrationError(code)
+ return dict(raw)
+
+
+def _string_tuple(value: object) -> tuple[str, ...]:
+ if not isinstance(value, list | tuple):
+ return ()
+ return tuple(item for item in value if isinstance(item, str) and item)
+
+
+def _optional_string(value: object) -> str | None:
+ return value if isinstance(value, str) else None
+
+
+def _optional_int(value: object) -> int | None:
+ return value if type(value) is int else None
diff --git a/memhub/apps/core/src/one_memory/hy_sdk_runtime.py b/memhub/apps/core/src/one_memory/hy_sdk_runtime.py
new file mode 100644
index 0000000..5c461b6
--- /dev/null
+++ b/memhub/apps/core/src/one_memory/hy_sdk_runtime.py
@@ -0,0 +1,406 @@
+"""HY SDK client construction and shared-runtime leasing.
+
+This module deliberately depends only on the SDK's package-root exports. A
+lease owns one client while the process shares one ``SharedRuntime`` per
+physical MemHub data directory.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import hashlib
+import os
+import threading
+from collections.abc import Callable, Coroutine
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any, ClassVar
+
+from hy_memory import ( # type: ignore[import-untyped]
+ HyMemoryClient,
+ MemoryConfig,
+ SharedRuntime,
+)
+
+from one_memory.embedding_assets import (
+ BUILTIN_EMBEDDING_DIMENSIONS,
+ BUILTIN_EMBEDDING_MODEL,
+)
+from one_memory.hy_graph_admin import (
+ GraphWidthMismatchError,
+ graph_store_enabled,
+ inspect_graph_width_mismatch,
+)
+from one_memory.hy_sdk_types import HySdkRuntimeError
+from one_memory.local_embedding import LocalEmbedder
+from one_memory.model_profiles import ModelProfileSnapshot, ProviderKind
+
+_RUNTIME_LOCK = threading.RLock()
+BUILTIN_RETRIEVAL_PROFILE_ID = "builtin-retrieval"
+_LOCAL_ONNX_PLACEHOLDER_URL = "http://127.0.0.1/local-onnx"
+DEFAULT_RELEVANCE_FLOOR = 0.35
+
+
+@dataclass
+class _RuntimeEntry:
+ runtime: SharedRuntime
+ references: int
+
+
+_RUNTIMES: dict[Path, _RuntimeEntry] = {}
+
+
+class LocalOnnxEmbeddingService:
+ """Public ``EmbeddingService`` implementation backed by MemHub's ONNX model."""
+
+ _embedder: ClassVar[LocalEmbedder | None] = None
+ _embedder_lock: ClassVar[threading.Lock] = threading.Lock()
+
+ def __init__(self, embedder: LocalEmbedder | None = None) -> None:
+ if embedder is None:
+ with self._embedder_lock:
+ if self._embedder is None:
+ self.__class__._embedder = LocalEmbedder()
+ embedder = self._embedder
+ if embedder is None: # pragma: no cover - guarded by the assignment above
+ raise HySdkRuntimeError("hy_sdk_local_embedding_unavailable")
+ self._local_embedder = embedder
+
+ async def embed(self, text: str, use_cache: bool = True) -> list[float]:
+ del use_cache
+ vectors = await asyncio.to_thread(self._local_embedder.encode, [text])
+ return vectors[0]
+
+ async def embed_with_meta(
+ self,
+ text: str,
+ use_cache: bool = True,
+ ) -> tuple[list[float], dict[str, Any]]:
+ return await self.embed(text, use_cache), {"provider": "local-onnx"}
+
+ async def embed_batch(
+ self,
+ texts: list[str],
+ use_cache: bool = True,
+ ) -> list[list[float]]:
+ del use_cache
+ if not texts:
+ return []
+ return await asyncio.to_thread(self._local_embedder.encode, list(texts))
+
+ async def embed_queued(self, text: str, use_cache: bool = True) -> list[float]:
+ return await self.embed(text, use_cache)
+
+ async def embed_queued_with_meta(
+ self,
+ text: str,
+ use_cache: bool = True,
+ ) -> tuple[list[float], dict[str, Any]]:
+ return await self.embed_with_meta(text, use_cache)
+
+ def get_embedding_dims(self) -> int:
+ return BUILTIN_EMBEDDING_DIMENSIONS
+
+
+class ClientLease:
+ """Own a client and release its shared runtime exactly once."""
+
+ def __init__(self, client: HyMemoryClient, data_dir: Path) -> None:
+ self.client = client
+ self.data_dir = data_dir.resolve()
+ self._closed = False
+ self._close_lock = threading.Lock()
+
+ @property
+ def closed(self) -> bool:
+ return self._closed
+
+ def close(self) -> None:
+ with self._close_lock:
+ if self._closed:
+ return
+ self._closed = True
+ try:
+ self.client.close()
+ finally:
+ _release_runtime(self.data_dir)
+
+ def __enter__(self) -> ClientLease:
+ return self
+
+ def __exit__(self, *_exc: object) -> None:
+ self.close()
+
+
+class SdkClientHandle:
+ """Lazy async owner for one profile-bound public SDK client lease."""
+
+ def __init__(
+ self,
+ profile: ModelProfileSnapshot,
+ *,
+ api_key: str | None,
+ data_dir: Path,
+ http_transport_factory: Callable[[], Any] | None = None,
+ ) -> None:
+ self._profile = profile
+ self._api_key = api_key
+ self._data_dir = data_dir
+ self._http_transport_factory = http_transport_factory
+ self._lease: ClientLease | None = None
+ self._lock = asyncio.Lock()
+
+ async def client(self) -> HyMemoryClient:
+ if self._lease is not None:
+ return self._lease.client
+ async with self._lock:
+ if self._lease is None:
+ self._lease = await asyncio.to_thread(
+ acquire_client,
+ self._profile,
+ api_key=self._api_key,
+ data_dir=self._data_dir,
+ http_transport_factory=self._http_transport_factory,
+ )
+ return self._lease.client
+
+ async def close(self) -> None:
+ async with self._lock:
+ lease, self._lease = self._lease, None
+ if lease is not None:
+ await asyncio.to_thread(lease.close)
+
+
+def builtin_retrieval_snapshot() -> ModelProfileSnapshot:
+ """Return the model-free profile used by SDK-native read operations."""
+ return ModelProfileSnapshot(
+ profile_id=BUILTIN_RETRIEVAL_PROFILE_ID,
+ revision=0,
+ provider_kind=ProviderKind.LOCAL_ONNX,
+ base_url=_LOCAL_ONNX_PLACEHOLDER_URL,
+ model=BUILTIN_EMBEDDING_MODEL,
+ embedding_provider_kind=ProviderKind.LOCAL_ONNX,
+ embedding_model=BUILTIN_EMBEDDING_MODEL,
+ embedding_dimensions=BUILTIN_EMBEDDING_DIMENSIONS,
+ timeout_seconds=60,
+ max_concurrency=1,
+ context_window=None,
+ has_api_key=False,
+ )
+
+
+def sdk_relevance_floor() -> float:
+ raw = os.environ.get("ONE_MEMORY_HY_RELEVANCE_FLOOR", "").strip()
+ if not raw:
+ return DEFAULT_RELEVANCE_FLOOR
+ try:
+ value = float(raw)
+ except ValueError:
+ return DEFAULT_RELEVANCE_FLOOR
+ return min(1.0, max(0.0, value))
+
+
+def build_sdk_config(
+ profile: ModelProfileSnapshot,
+ *,
+ api_key: str | None,
+ data_dir: Path,
+) -> MemoryConfig:
+ """Map a model snapshot to SDK models, endpoints, backends, and local paths."""
+ generation_endpoint, generation_key = _generation_access(profile, api_key)
+ embedding_provider = profile.embedding_provider_kind or profile.provider_kind
+ embedding_service_is_local = embedding_provider is ProviderKind.LOCAL_ONNX
+ embedding_model = profile.embedding_model or (
+ BUILTIN_EMBEDDING_MODEL if embedding_service_is_local else None
+ )
+ if not embedding_model:
+ raise HySdkRuntimeError("hy_sdk_embedding_model_required")
+ dimensions: int | None
+ if embedding_service_is_local:
+ embedding_endpoint = None
+ embedding_key = None
+ dimensions = profile.embedding_dimensions or BUILTIN_EMBEDDING_DIMENSIONS
+ else:
+ embedding_endpoint = _openai_endpoint(
+ embedding_provider,
+ profile.embedding_base_url or profile.base_url,
+ )
+ embedding_key = "ollama" if embedding_provider is ProviderKind.OLLAMA else api_key
+ if embedding_provider is ProviderKind.OPENAI_COMPATIBLE and not embedding_key:
+ raise HySdkRuntimeError("hy_sdk_embedding_api_key_missing")
+ if embedding_provider not in {
+ ProviderKind.OPENAI_COMPATIBLE,
+ ProviderKind.OLLAMA,
+ }:
+ raise HySdkRuntimeError("hy_sdk_embedding_provider_unsupported")
+ dimensions = profile.embedding_dimensions
+
+ 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 = "memhub_" + hashlib.sha256(collection_identity.encode()).hexdigest()[:16]
+
+ return MemoryConfig.from_dict(
+ {
+ "llm": {
+ "provider": "openai",
+ "model": profile.model,
+ "api_key": generation_key,
+ "base_url": generation_endpoint,
+ },
+ "embedder": {
+ "provider": "openai",
+ "model": (
+ BUILTIN_EMBEDDING_MODEL if embedding_service_is_local else embedding_model
+ ),
+ "api_key": embedding_key,
+ "base_url": embedding_endpoint,
+ "embedding_dims": dimensions,
+ },
+ "vector_store": {
+ "provider": "chroma",
+ "collection_name": collection,
+ "persist_directory": str(root / "vector"),
+ "embedding_dims": dimensions,
+ "host": None,
+ "port": None,
+ "api_key": None,
+ },
+ "graph_store": {
+ "provider": "kuzu",
+ "db_path": str(root / "graph"),
+ "url": None,
+ "username": None,
+ "password": None,
+ "database": None,
+ },
+ "cache": {
+ "backend": "sqlite",
+ "db_path": str(root / "cache.sqlite3"),
+ },
+ "history": {"db_path": str(root / "history.sqlite3")},
+ "coding": {"db_path": str(root / "coding.sqlite3")},
+ }
+ )
+
+
+def acquire_client(
+ profile: ModelProfileSnapshot,
+ *,
+ api_key: str | None,
+ data_dir: Path,
+ http_transport_factory: Callable[[], Any] | None = None,
+) -> ClientLease:
+ """Construct a public SDK client and return its explicit runtime lease."""
+ config = build_sdk_config(profile, api_key=api_key, data_dir=data_dir)
+ config.http_transport_factory = http_transport_factory
+ mismatch = inspect_graph_width_mismatch(config)
+ if mismatch is not None:
+ raise GraphWidthMismatchError(mismatch)
+ key = data_dir.resolve()
+ runtime = _acquire_runtime(config, key)
+ embedding_service: LocalOnnxEmbeddingService | None = None
+ if (profile.embedding_provider_kind or profile.provider_kind) is ProviderKind.LOCAL_ONNX:
+ embedding_service = LocalOnnxEmbeddingService()
+ try:
+ client = HyMemoryClient(
+ config=config,
+ mode="ultra" if graph_store_enabled() else "pro",
+ runtime=runtime,
+ embedding_service=embedding_service,
+ )
+ except BaseException:
+ _release_runtime(key)
+ raise
+ return ClientLease(client, key)
+
+
+def close_all_shared_runtimes() -> None:
+ """Close process runtimes only after every client lease has been released."""
+ with _RUNTIME_LOCK:
+ if _RUNTIMES:
+ raise HySdkRuntimeError("hy_sdk_runtime_leases_active")
+
+
+def _generation_access(
+ profile: ModelProfileSnapshot,
+ api_key: str | None,
+) -> tuple[str, str]:
+ if profile.provider_kind is ProviderKind.LOCAL_ONNX:
+ return _LOCAL_ONNX_PLACEHOLDER_URL, "local-read-only"
+ if profile.provider_kind not in {
+ ProviderKind.OPENAI_COMPATIBLE,
+ ProviderKind.OLLAMA,
+ }:
+ raise HySdkRuntimeError("hy_sdk_generation_provider_unsupported")
+ endpoint = _openai_endpoint(profile.provider_kind, profile.base_url)
+ if profile.provider_kind is ProviderKind.OLLAMA:
+ return endpoint, "ollama"
+ if not api_key:
+ raise HySdkRuntimeError("hy_sdk_model_api_key_missing")
+ return endpoint, api_key
+
+
+def _openai_endpoint(provider: ProviderKind, endpoint: str | None) -> str:
+ value = (endpoint or "").rstrip("/")
+ if not value:
+ raise HySdkRuntimeError("hy_sdk_model_endpoint_missing")
+ if provider is ProviderKind.OLLAMA and not value.endswith("/v1"):
+ return f"{value}/v1"
+ return value
+
+
+def _acquire_runtime(config: MemoryConfig, key: Path) -> SharedRuntime:
+ with _RUNTIME_LOCK:
+ entry = _RUNTIMES.get(key)
+ if entry is None:
+ runtime = _run_sync(SharedRuntime.create(config))
+ _RUNTIMES[key] = _RuntimeEntry(runtime=runtime, references=1)
+ return runtime
+ entry.references += 1
+ return entry.runtime
+
+
+def _release_runtime(key: Path) -> None:
+ runtime: SharedRuntime | None = None
+ with _RUNTIME_LOCK:
+ entry = _RUNTIMES.get(key)
+ if entry is None:
+ return
+ entry.references -= 1
+ if entry.references == 0:
+ runtime = entry.runtime
+ del _RUNTIMES[key]
+ if runtime is not None:
+ runtime.close()
+
+
+def _run_sync[T](coroutine: Coroutine[Any, Any, T]) -> T:
+ """Run SDK async construction from either sync or async caller threads."""
+ try:
+ asyncio.get_running_loop()
+ except RuntimeError:
+ return asyncio.run(coroutine)
+
+ result: list[T] = []
+ failure: list[BaseException] = []
+
+ def run() -> None:
+ try:
+ result.append(asyncio.run(coroutine))
+ except BaseException as error:
+ failure.append(error)
+
+ thread = threading.Thread(target=run, name="hy-sdk-runtime-create")
+ thread.start()
+ thread.join()
+ if failure:
+ raise failure[0]
+ return result[0]
diff --git a/memhub/apps/core/src/one_memory/hy_sdk_types.py b/memhub/apps/core/src/one_memory/hy_sdk_types.py
new file mode 100644
index 0000000..13b00c3
--- /dev/null
+++ b/memhub/apps/core/src/one_memory/hy_sdk_types.py
@@ -0,0 +1,387 @@
+"""Validated records and response parsers for public HY SDK operations."""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+
+from pydantic import BaseModel, ConfigDict, Field
+
+from one_memory.semantic_deadline import SemanticMemoryHit
+
+
+class HySdkError(RuntimeError):
+ """Base error carrying a stable, product-facing code."""
+
+ def __init__(self, code: str) -> None:
+ super().__init__(code)
+ self.code = code
+
+
+class HySdkRuntimeError(HySdkError):
+ """The public SDK runtime could not be configured or leased."""
+
+
+class HySdkMigrationError(HySdkError):
+ """A public SDK migration operation failed or returned an invalid shape."""
+
+
+class HySdkReadError(HySdkError):
+ """A public SDK read operation failed or returned an invalid shape."""
+
+
+class HySdkMemoryRecord(BaseModel):
+ model_config = ConfigDict(frozen=True, extra="forbid")
+
+ memory_id: str
+ content: str
+ layer: str
+ status: str
+ is_latest: bool
+ supersedes: tuple[str, ...] = ()
+ superseded_by: tuple[str, ...] = ()
+ tags: tuple[str, ...] = ()
+ owner: str | None = None
+ source_raw_ids: tuple[str, ...] = ()
+ user_id: str
+ agent_id: str
+ session_id: str | None = None
+ source: str | None = None
+ memory_at: int | None = None
+ gmt_created: int | None = None
+
+ @classmethod
+ def from_sdk(cls, raw: object) -> HySdkMemoryRecord:
+ if not isinstance(raw, Mapping):
+ raise HySdkReadError("hy_memory_record_shape_unknown")
+ if any(
+ not isinstance(raw.get(key), str) or not str(raw[key]).strip()
+ for key in ("memory_id", "content")
+ ):
+ raise HySdkReadError("hy_memory_record_shape_unknown")
+ try:
+ return cls(
+ memory_id=str(raw["memory_id"]),
+ content=str(raw["content"]),
+ layer=str(raw.get("layer") or ""),
+ status=str(raw.get("status") or ""),
+ is_latest=bool(raw.get("is_latest", True)),
+ supersedes=_string_tuple(raw.get("supersedes")),
+ superseded_by=_string_tuple(raw.get("superseded_by")),
+ tags=_string_tuple(raw.get("tags")),
+ owner=(str(raw["owner"]) if raw.get("owner") in {"user", "agent"} else None),
+ source_raw_ids=_source_raw_ids(raw),
+ user_id=str(raw.get("user_id") or ""),
+ agent_id=str(raw.get("agent_id") or ""),
+ session_id=(
+ str(raw["session_id"]) if isinstance(raw.get("session_id"), str) else None
+ ),
+ source=str(raw["source"]) if isinstance(raw.get("source"), str) else None,
+ memory_at=raw.get("memory_at") if isinstance(raw.get("memory_at"), int) else None,
+ gmt_created=(
+ raw.get("gmt_created") if isinstance(raw.get("gmt_created"), int) else None
+ ),
+ )
+ except (KeyError, TypeError, ValueError) as error:
+ raise HySdkReadError("hy_memory_record_shape_unknown") from error
+
+
+class HySdkMemoryPage(BaseModel):
+ model_config = ConfigDict(frozen=True, extra="forbid")
+
+ memories: tuple[HySdkMemoryRecord, ...]
+ total: int = Field(ge=0)
+ limit: int = Field(ge=1)
+ offset: int = Field(ge=0)
+
+ @classmethod
+ def from_sdk(cls, raw: object, *, limit: int, offset: int) -> HySdkMemoryPage:
+ if not isinstance(raw, Mapping):
+ raise HySdkReadError("hy_memory_list_shape_unknown")
+ rows: list[object] = []
+ total = 0
+ for bucket_name, rows_name in (("vdb", "memories"), ("graph", "nodes")):
+ bucket = raw.get(bucket_name)
+ if bucket is None and bucket_name == "graph":
+ continue
+ if not isinstance(bucket, Mapping) or not isinstance(bucket.get(rows_name), list):
+ raise HySdkReadError("hy_memory_list_shape_unknown")
+ bucket_total = bucket.get("total")
+ if (
+ not isinstance(bucket_total, int)
+ or isinstance(bucket_total, bool)
+ or bucket_total < 0
+ ):
+ raise HySdkReadError("hy_memory_list_shape_unknown")
+ total += bucket_total
+ rows.extend(bucket[rows_name])
+ deduplicated: dict[str, HySdkMemoryRecord] = {}
+ for row in rows:
+ record = HySdkMemoryRecord.from_sdk(row)
+ deduplicated.setdefault(record.memory_id, record)
+ return cls(
+ memories=tuple(deduplicated.values()),
+ total=total,
+ limit=limit,
+ offset=offset,
+ )
+
+
+class HySdkRawRecord(BaseModel):
+ model_config = ConfigDict(frozen=True, extra="forbid")
+
+ raw_id: str
+ content: str
+ user_id: str
+ agent_id: str
+ session_id: str
+ source: str
+ memory_at: int | None = None
+ gmt_created: int | None = None
+ custom: dict[str, object] = Field(default_factory=dict)
+
+ @classmethod
+ def from_sdk(cls, raw: object) -> HySdkRawRecord:
+ if not isinstance(raw, Mapping):
+ raise HySdkReadError("hy_memory_raw_shape_unknown")
+ if any(
+ not isinstance(raw.get(key), str) or not str(raw[key]).strip()
+ for key in ("raw_id", "content", "user_id", "agent_id", "session_id", "source")
+ ):
+ raise HySdkReadError("hy_memory_raw_shape_unknown")
+ custom = raw.get("custom")
+ if not isinstance(custom, Mapping):
+ custom = {}
+ try:
+ return cls(
+ raw_id=str(raw["raw_id"]),
+ content=str(raw["content"]),
+ user_id=str(raw["user_id"]),
+ agent_id=str(raw["agent_id"]),
+ session_id=str(raw["session_id"]),
+ source=str(raw["source"]),
+ memory_at=raw.get("memory_at") if isinstance(raw.get("memory_at"), int) else None,
+ gmt_created=(
+ raw.get("gmt_created") if isinstance(raw.get("gmt_created"), int) else None
+ ),
+ custom=dict(custom),
+ )
+ except (KeyError, TypeError, ValueError) as error:
+ raise HySdkReadError("hy_memory_raw_shape_unknown") from error
+
+
+class HySdkRawHit(HySdkRawRecord):
+ score: float = Field(ge=0, le=1)
+
+ @classmethod
+ def from_sdk_search(cls, raw: object) -> HySdkRawHit:
+ if not isinstance(raw, Mapping):
+ raise HySdkReadError("hy_memory_raw_search_shape_unknown")
+ raw_id = raw.get("memory_id")
+ score = raw.get("score")
+ if (
+ not isinstance(raw_id, str)
+ or not isinstance(score, int | float)
+ or isinstance(score, bool)
+ ):
+ raise HySdkReadError("hy_memory_raw_search_shape_unknown")
+ base = HySdkRawRecord.from_sdk({**raw, "raw_id": raw_id})
+ return cls(
+ **base.model_dump(),
+ score=max(0.0, min(1.0, float(score))),
+ )
+
+
+class HySdkRawPage(BaseModel):
+ model_config = ConfigDict(frozen=True, extra="forbid")
+
+ raw: tuple[HySdkRawRecord, ...]
+ total: int = Field(ge=0)
+ limit: int = Field(ge=1)
+ offset: int = Field(ge=0)
+
+ @classmethod
+ def from_sdk(cls, raw: object, *, limit: int, offset: int) -> HySdkRawPage:
+ if not isinstance(raw, Mapping):
+ raise HySdkReadError("hy_memory_raw_list_shape_unknown")
+ rows = raw.get("raw")
+ total = raw.get("total")
+ if (
+ not isinstance(rows, list)
+ or not isinstance(total, int)
+ or isinstance(total, bool)
+ or total < 0
+ ):
+ raise HySdkReadError("hy_memory_raw_list_shape_unknown")
+ return cls(
+ raw=tuple(HySdkRawRecord.from_sdk(row) for row in rows),
+ total=total,
+ limit=limit,
+ offset=offset,
+ )
+
+
+class HySdkUserProfile(BaseModel):
+ model_config = ConfigDict(frozen=True, extra="forbid")
+
+ request_id: str
+ profile: dict[str, object] | None
+ elapsed_ms: float = Field(ge=0)
+
+ @classmethod
+ def from_sdk(cls, raw: object) -> HySdkUserProfile:
+ if not isinstance(raw, Mapping):
+ raise HySdkReadError("hy_memory_profile_shape_unknown")
+ request_id = raw.get("request_id")
+ profile = raw.get("profile")
+ elapsed_ms = raw.get("elapsed_ms")
+ if (
+ not isinstance(request_id, str)
+ or (profile is not None and not isinstance(profile, Mapping))
+ or not isinstance(elapsed_ms, int | float)
+ or isinstance(elapsed_ms, bool)
+ ):
+ raise HySdkReadError("hy_memory_profile_shape_unknown")
+ return cls(
+ request_id=request_id,
+ profile=None if profile is None else dict(profile),
+ elapsed_ms=float(elapsed_ms),
+ )
+
+
+def parse_sdk_search(raw: object, *, error_code: str) -> tuple[SemanticMemoryHit, ...]:
+ rows = _reply_rows(raw, error_code)
+ found: list[SemanticMemoryHit] = []
+ seen: set[str] = set()
+ for item in sorted(rows, key=_score, reverse=True):
+ memory_id = item.get("memory_id") or item.get("id")
+ if not isinstance(memory_id, str) or not memory_id or memory_id in seen:
+ continue
+ seen.add(memory_id)
+ content = item.get("content")
+ member_ids, formatting_complete = _formatted_member_ids(item)
+ found.append(
+ SemanticMemoryHit(
+ memory_id=memory_id,
+ score=_score(item),
+ formatted_content=(
+ content.strip() if isinstance(content, str) and content.strip() else None
+ ),
+ member_ids=member_ids,
+ sdk_formatted=True,
+ formatting_complete=formatting_complete,
+ )
+ )
+ return tuple(found)
+
+
+def parse_sdk_raw_search(raw: object) -> tuple[HySdkRawHit, ...]:
+ return tuple(
+ HySdkRawHit.from_sdk_search(row)
+ for row in _reply_rows(raw, "hy_memory_raw_search_shape_unknown")
+ )
+
+
+def _string_tuple(value: object) -> tuple[str, ...]:
+ if not isinstance(value, list):
+ return ()
+ return tuple(
+ dict.fromkeys(item.strip() for item in value if isinstance(item, str) and item.strip())
+ )
+
+
+def _source_raw_ids(raw: Mapping[str, object]) -> tuple[str, ...]:
+ custom = raw.get("custom")
+ values: list[object] = []
+ if isinstance(custom, Mapping):
+ listed = custom.get("source_raw_memory_ids")
+ if isinstance(listed, list):
+ values.extend(listed)
+ singular = raw.get("source_raw_memory_id")
+ if isinstance(singular, str):
+ values.append(singular)
+ return tuple(
+ dict.fromkeys(value.strip() for value in values if isinstance(value, str) and value.strip())
+ )
+
+
+def _reply_rows(raw: object, error_code: str) -> tuple[Mapping[str, object], ...]:
+ if not isinstance(raw, Mapping):
+ raise HySdkReadError(error_code)
+ keys = tuple(key for key in ("memories", "coding_memories") if key in raw)
+ if "scene" in raw:
+ scene = raw["scene"]
+ if not isinstance(scene, str):
+ raise HySdkReadError(error_code)
+ if scene in ("normal", "chat"):
+ selected = "memories"
+ elif scene in ("productivity", "working"):
+ selected = "coding_memories"
+ else:
+ raise HySdkReadError(error_code)
+ if selected not in keys:
+ raise HySdkReadError(error_code)
+ elif len(keys) == 1:
+ selected = keys[0]
+ else:
+ raise HySdkReadError(error_code)
+
+ result: list[Mapping[str, object]] = []
+ for key in keys:
+ value = raw[key]
+ if key == "memories" and isinstance(value, Mapping):
+ if set(value) != {"schema", "proactive", "normal"}:
+ raise HySdkReadError(error_code)
+ channels = tuple(value.values())
+ else:
+ channels = (value,)
+ for channel in channels:
+ if not isinstance(channel, list) or any(
+ not isinstance(row, Mapping) for row in channel
+ ):
+ raise HySdkReadError(error_code)
+ if key == selected:
+ result.extend(channel)
+ return tuple(result)
+
+
+def _score(memory: Mapping[str, object]) -> float:
+ score = memory.get("score")
+ return float(score) if isinstance(score, int | float) and not isinstance(score, bool) else 0.0
+
+
+def _formatted_member_ids(memory: Mapping[str, object]) -> tuple[tuple[str, ...], bool]:
+ represented: dict[str, None] = {}
+ composite = False
+ raw_members = memory.get("member_ids")
+ if raw_members is not None:
+ composite = True
+ if not isinstance(raw_members, list | tuple) or any(
+ not isinstance(member_id, str) or not member_id for member_id in raw_members
+ ):
+ return (), False
+ for member_id in raw_members:
+ represented.setdefault(member_id, None)
+ chain = memory.get("evolution_chain")
+ if chain is not None:
+ composite = True
+ if not isinstance(chain, list | tuple):
+ return (), False
+ for entry in chain:
+ if not isinstance(entry, Mapping):
+ return (), False
+ member_id = entry.get("node_id") or entry.get("memory_id")
+ if not isinstance(member_id, str) or not member_id:
+ return (), False
+ represented.setdefault(member_id, None)
+ if memory.get("capsule_memories") is not None or memory.get("timeline") is not None:
+ composite = True
+ if raw_members is None:
+ return (), False
+ content = memory.get("content")
+ if isinstance(content, str) and content.lstrip().startswith(
+ ("Related memories:", "Matched memories:", "Memory timeline:")
+ ):
+ composite = True
+ if not represented:
+ return (), False
+ return tuple(represented), not composite or bool(represented)
diff --git a/memhub/apps/core/src/one_memory/hy_source_context.py b/memhub/apps/core/src/one_memory/hy_source_context.py
deleted file mode 100644
index 9304a50..0000000
--- a/memhub/apps/core/src/one_memory/hy_source_context.py
+++ /dev/null
@@ -1,153 +0,0 @@
-"""Per-write original Evidence and where each HY memory came from; never a memory source."""
-
-import json
-from collections.abc import Set as AbstractSet
-from importlib import import_module
-from typing import Any, Literal
-
-from pydantic import BaseModel, ConfigDict
-
-from one_memory.imports.models import EvidenceContentKind, EvidenceRecord
-from one_memory.input_sanitization import sanitize_model_input
-
-
-class HySupportedMemory(BaseModel):
- model_config = ConfigDict(frozen=True, extra="forbid")
-
- hy_memory_id: str
- governed_memory_id: str
- revision: int
- content: str
- owner: Literal["user", "agent"]
- evidence_ids: tuple[str, ...]
-
-
-class HySourceContext(BaseModel):
- model_config = ConfigDict(frozen=True, extra="forbid")
-
- current: tuple[EvidenceRecord, ...]
- history: tuple[EvidenceRecord, ...] = ()
- supporting: tuple[EvidenceRecord, ...] = ()
- known_memories: tuple[HySupportedMemory, ...] = ()
-
-
-class HyWriteBindings:
- def __init__(self, context: HySourceContext) -> None:
- if not context.current:
- raise ValueError("hy_memory_write_verification_context_scope")
- self.context = context
- seed = context.current[0]
- records = (*context.current, *context.history, *context.supporting)
- workspaces = {record.workspace for record in records}
- # A missing workspace is a legacy identity, not a wildcard that may
- # absorb a named project. Keep NULL and named workspaces disjoint.
- if None in workspaces and len(workspaces) != 1:
- raise ValueError("hy_memory_write_verification_context_scope")
- ids = [record.evidence_id for record in records]
- if len(ids) != len(set(ids)):
- raise ValueError("hy_memory_write_verification_context_scope")
- for record in records:
- if (
- (
- record.user_id,
- record.source_id,
- record.conversation_id,
- record.workspace,
- )
- != (
- seed.user_id,
- seed.source_id,
- seed.conversation_id,
- seed.workspace,
- )
- or record.content_kind is not EvidenceContentKind.RAW_CONVERSATION
- or record.role not in {"user", "assistant", "tool"}
- ):
- raise ValueError("hy_memory_write_verification_context_scope")
- self.all_sources: list[dict[str, Any]] = [
- {
- "id": record.evidence_id,
- "role": record.role,
- "content": sanitize_model_input(record.verbatim),
- "new": index < len(context.current),
- "revision": record.revision,
- "created_at": record.created_at.isoformat() if record.created_at else None,
- }
- for index, record in enumerate(records)
- ]
- self.sources = self.all_sources[: len(context.current) + len(context.history)]
- self._supports: dict[tuple[str, str], tuple[str, ...]] = {}
- self.profile_order: list[str] | None = None
- self.verified_operations: dict[str, tuple[str, str]] = {}
- self.known = {memory.hy_memory_id: memory for memory in context.known_memories}
- for memory in context.known_memories:
- if not memory.evidence_ids or not set(memory.evidence_ids) <= set(ids):
- raise ValueError("hy_memory_write_verification_context_scope")
- self._supports[(memory.content, memory.owner)] = memory.evidence_ids
-
- def check_content(self, content: str) -> None:
- try:
- parsed = json.loads(content)
- except ValueError as error:
- raise ValueError("hy_memory_write_verification_input_mismatch") from error
- expected = [
- {"role": record.role, "content": sanitize_model_input(record.verbatim)}
- for record in self.context.current
- ]
- # HY strips tool messages itself before chat extraction when it judges a turn chat.
- without_tools = [item for item in expected if item["role"] != "tool"]
- if parsed != expected and (without_tools == expected or parsed != without_tools):
- raise ValueError("hy_memory_write_verification_input_mismatch")
-
- def history_json(self) -> str:
- return json.dumps(
- [
- {
- "evidence_id": source["id"],
- **{k: source[k] for k in ("role", "content", "revision", "created_at")},
- }
- for source in self.sources
- if not source["new"]
- ],
- ensure_ascii=False,
- )
-
- def turn_support(
- self, owner: str | None, targets: AbstractSet[str] = frozenset()
- ) -> tuple[str, ...]:
- """This turn's words by the memory's author, plus what a merged memory already cited."""
- roles = {"user": {"user"}, "agent": {"assistant"}}.get(owner or "")
- current = [source for source in self.all_sources if source["new"]]
- ids = [source["id"] for source in current if roles is None or source["role"] in roles]
- if not ids:
- ids = [source["id"] for source in current]
- for target in sorted(targets):
- if target in self.known:
- ids.extend(self.known[target].evidence_ids)
- return tuple(dict.fromkeys(ids))
-
- def record_turn_supports(self, items: list[dict[str, Any]]) -> None:
- for item in items:
- key = (item["content"], item["owner"] or "")
- self._supports.setdefault(key, self.turn_support(item["owner"]))
-
- def record_operation_support(self, content: str, owner: str | None, targets: set[str]) -> None:
- key = (content, owner or "")
- merged = (*self._supports.get(key, ()), *self.turn_support(owner, targets))
- self._supports[key] = tuple(dict.fromkeys(merged))
-
- def support_for(self, content: str, owner: str | None) -> tuple[str, ...]:
- return self._supports.get((content, owner or ""), ())
-
- def profile_support(self, content: str, values: dict[str, Any]) -> tuple[str, ...]:
- render = import_module("hy_memory.agent.tools.basic_profile")._render_content
-
- if not values or render(values, field_order=self.profile_order) != content:
- return ()
- ids: dict[str, None] = {}
- for key, value in values.items():
- support = self.support_for(f"{key}: {value}", "user")
- if not support:
- return ()
- ids.update(dict.fromkeys(support))
- return tuple(ids)
diff --git a/memhub/apps/core/src/one_memory/hy_write_verification.py b/memhub/apps/core/src/one_memory/hy_write_verification.py
deleted file mode 100644
index 5fc03ed..0000000
--- a/memhub/apps/core/src/one_memory/hy_write_verification.py
+++ /dev/null
@@ -1,53 +0,0 @@
-"""Input checks around HY's native extractor; HY's output is published as it returns it."""
-
-import asyncio
-from typing import Any
-
-from one_memory.hy_source_context import HyWriteBindings
-
-
-def _extracted_items(info: dict[str, Any]) -> list[dict[str, Any]]:
- items: list[dict[str, Any]] = []
- for section in ("memory", "intentions"):
- for item in info.get(section) or []:
- if isinstance(item, dict) and isinstance(item.get("content"), str):
- items.append({"content": item["content"], "owner": item.get("owner")})
- for name, value in (info.get("basic_info") or {}).items():
- items.append({"content": f"{name}: {value}", "owner": "user"})
- return items
-
-
-class HyExtractionGuard:
- def __init__(self, extractor: Any) -> None:
- self.extractor = extractor
- self.failures: list[str] = []
- self._lock = asyncio.Lock()
- self.bindings: HyWriteBindings | None = None
-
- def __getattr__(self, name: str) -> Any:
- return getattr(self.extractor, name)
-
- async def extract(self, *args: Any, **kwargs: Any) -> Any:
- async with self._lock:
- try:
- return await self._extract(args, kwargs)
- except ValueError as error:
- if str(error).startswith("hy_memory_write_verification"):
- self.failures.append(str(error))
- raise
-
- async def _extract(self, args: tuple[Any, ...], kwargs: dict[str, Any]) -> Any:
- content = kwargs.get("content", args[0] if args else "")
- bindings = self.bindings
- if bindings is not None:
- bindings.check_content(content)
- fields = kwargs.get("basic_profile_fields")
- bindings.profile_order = list(fields) if fields else None
- kwargs = {**kwargs, "history_context": bindings.history_json()}
- else:
- # No raw-history identity was supplied; do not trust HY's text prefixes.
- kwargs = {**kwargs, "history_context": ""}
- result = await self.extractor.extract(*args, **kwargs)
- if bindings is not None and result.success:
- bindings.record_turn_supports(_extracted_items(result.info))
- return result
diff --git a/memhub/apps/core/src/one_memory/legacy_lifecycle_types.py b/memhub/apps/core/src/one_memory/legacy_lifecycle_types.py
new file mode 100644
index 0000000..c1ce74c
--- /dev/null
+++ b/memhub/apps/core/src/one_memory/legacy_lifecycle_types.py
@@ -0,0 +1,35 @@
+"""Passive lifecycle projection used only by retired Governance readers."""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from dataclasses import dataclass, field
+from types import MappingProxyType
+
+
+@dataclass(frozen=True, eq=False)
+class HyLifecycle:
+ hidden: Mapping[str, tuple[str, ...]] = field(default_factory=dict)
+
+ def __post_init__(self) -> None:
+ object.__setattr__(self, "hidden", MappingProxyType(dict(self.hidden)))
+
+ def __eq__(self, other: object) -> bool:
+ return isinstance(other, HyLifecycle) and dict(self.hidden) == dict(
+ other.hidden
+ )
+
+ def __hash__(self) -> int:
+ return hash(tuple(sorted(self.hidden.items())))
+
+ def replaced_by(self, memory_id: str) -> tuple[str, ...]:
+ return self.hidden.get(memory_id, ())
+
+ def replacing(self, memory_id: str) -> tuple[str, ...]:
+ return tuple(
+ sorted(
+ old
+ for old, replacements in self.hidden.items()
+ if memory_id in replacements
+ )
+ )
diff --git a/memhub/apps/core/src/one_memory/live_capture.py b/memhub/apps/core/src/one_memory/live_capture.py
index e567927..3f6ca1e 100644
--- a/memhub/apps/core/src/one_memory/live_capture.py
+++ b/memhub/apps/core/src/one_memory/live_capture.py
@@ -224,7 +224,7 @@ def record_capture_rejection(
def _submit_live_memory(store: EvidenceStore, record: EvidenceRecord, *, changed: bool) -> None:
if not changed or not _sync_open(store.database_path, record.source_id):
return
- from one_memory.memory_processing import _conversation_chunks
+ from one_memory.conversation_processing import _conversation_chunks
from one_memory.memory_server.durable_queue import DurableWriteQueue
from one_memory.memory_server.unified_entry import UnifiedWriteIntake
diff --git a/memhub/apps/core/src/one_memory/local_embedding.py b/memhub/apps/core/src/one_memory/local_embedding.py
index 5787dc8..fd9aee7 100644
--- a/memhub/apps/core/src/one_memory/local_embedding.py
+++ b/memhub/apps/core/src/one_memory/local_embedding.py
@@ -121,7 +121,7 @@ class LocalEmbedder:
raise MissingEmbeddingAssetsError(f"{_FETCH_HINT} Looked in {directory}.")
# Imported by name for the same reason kuzu and hy_memory are in
- # hy_memory_bridge: onnxruntime ships no py.typed, and a dynamic
+ # onnxruntime ships no py.typed, and a dynamic
# import keeps the strict checker on everything around it.
ort = import_module("onnxruntime")
from tokenizers import Tokenizer
diff --git a/memhub/apps/core/src/one_memory/memory_governance.py b/memhub/apps/core/src/one_memory/memory_governance.py
index f78f8d0..d472461 100644
--- a/memhub/apps/core/src/one_memory/memory_governance.py
+++ b/memhub/apps/core/src/one_memory/memory_governance.py
@@ -22,7 +22,7 @@ from pydantic import BaseModel, ConfigDict, Field
from one_memory.database import enable_write_ahead_log
from one_memory.database_access import main_database
-from one_memory.hy_lifecycle import HyLifecycle
+from one_memory.legacy_lifecycle_types import HyLifecycle
from one_memory.library_upgrade import LibraryUpgradeError, PreparedLibrary, holds_legacy_rows
from one_memory.memory_server.migrations import governance_ddl
diff --git a/memhub/apps/core/src/one_memory/memory_library.py b/memhub/apps/core/src/one_memory/memory_library.py
index db77a7b..a97281a 100644
--- a/memhub/apps/core/src/one_memory/memory_library.py
+++ b/memhub/apps/core/src/one_memory/memory_library.py
@@ -10,7 +10,7 @@ from typing import Literal
from pydantic import BaseModel, ConfigDict, Field
from one_memory.database_access import main_database
-from one_memory.hy_lifecycle import HyLifecycle
+from one_memory.legacy_lifecycle_types import HyLifecycle
from one_memory.memory_evidence_freshness import register_memory_freshness
from one_memory.memory_governance import (
GovernedMemory,
diff --git a/memhub/apps/core/src/one_memory/memory_notes.py b/memhub/apps/core/src/one_memory/memory_notes.py
index a399849..bfe2d3d 100644
--- a/memhub/apps/core/src/one_memory/memory_notes.py
+++ b/memhub/apps/core/src/one_memory/memory_notes.py
@@ -3,7 +3,7 @@ import json
import sqlite3
from collections.abc import Sequence
from datetime import UTC, datetime
-from typing import Literal, cast
+from typing import Any, Literal, cast
from uuid import UUID
from fastapi import APIRouter, BackgroundTasks, HTTPException, Request
@@ -21,11 +21,10 @@ from one_memory.imports.models import (
)
from one_memory.imports.storage import EvidenceStore
from one_memory.input_sanitization import sanitize_model_input
-from one_memory.memory_governance import MemoryStatus
-from one_memory.memory_processing import MemoryProcessingSupervisor
+from one_memory.memory_governance import MemoryGovernanceStore, MemoryStatus
from one_memory.memory_server.durable_queue import DurableWriteQueue
from one_memory.memory_server.unified_entry import UnifiedWriteIntake
-from one_memory.memory_tasks import MemoryTaskStatus
+from one_memory.memory_tasks import MemoryTaskStatus, MemoryTaskStore
from one_memory.secrets import SecretStoreUnavailableError
SOURCE_ID = "one-memory-manual"
@@ -82,11 +81,23 @@ class SavedMemoryNoteEvidence(BaseModel):
verbatim: str
+class LegacyMemoryNoteReader:
+ """Read pre-cutover note receipts without retaining any write runtime."""
+
+ def __init__(
+ self,
+ tasks: MemoryTaskStore,
+ governance: MemoryGovernanceStore,
+ ) -> None:
+ self.tasks = tasks
+ self.governance = governance
+
+
class MemoryNoteStore:
def __init__(
self,
evidence: EvidenceStore,
- processor: MemoryProcessingSupervisor,
+ processor: Any | None,
intake: UnifiedWriteIntake | None = None,
*,
sdk_authority: bool = False,
@@ -252,6 +263,8 @@ class MemoryNoteStore:
memory_ids=(list(durable.sdk_memory_ids) if durable is not None else []),
error=durable.detail if durable is not None else "write_missing",
)
+ if self.processor is None:
+ raise RuntimeError("legacy_memory_note_processor_unavailable")
task = self.processor.tasks.task_for_evidence(evidence_id)
memory_ids = []
if task:
@@ -356,6 +369,8 @@ def memory_note_router(dependencies: Sequence[Depends]) -> APIRouter:
try:
if notes.sdk_authority:
return await asyncio.to_thread(notes.receipt, record.evidence_id)
+ if notes.processor is None:
+ raise RuntimeError("legacy_memory_note_processor_unavailable")
if notes.intake is None:
# Isolated tests construct the store without a queue.
await notes.processor.enqueue_conversation_off_thread(record)
diff --git a/memhub/apps/core/src/one_memory/memory_processing.py b/memhub/apps/core/src/one_memory/memory_processing.py
deleted file mode 100644
index c2f886c..0000000
--- a/memhub/apps/core/src/one_memory/memory_processing.py
+++ /dev/null
@@ -1,4140 +0,0 @@
-import asyncio
-import json
-import logging
-import os
-import re
-import sqlite3
-import threading
-from collections.abc import (
- AsyncIterator,
- Awaitable,
- Callable,
- Collection,
- Generator,
- Mapping,
-)
-from contextlib import asynccontextmanager, suppress
-from dataclasses import dataclass, field
-from datetime import UTC, datetime, timedelta
-from hashlib import sha256
-from pathlib import Path
-from time import monotonic
-from typing import Literal, Protocol
-from weakref import WeakKeyDictionary
-
-from one_memory.background_work import in_the_background
-from one_memory.diagnostic_log import (
- diagnostic_event,
- diagnostic_exception,
- elapsed_ms,
- record_database_error,
-)
-from one_memory.exception_reporting import report_exception
-from one_memory.extraction_settings import ExtractionSettings, ExtractionSettingsStore
-from one_memory.hy_memory_bridge import (
- HY_CODING_LAYERS,
- GraphWidthDecision,
- GraphWidthMismatch,
- GraphWidthMismatchError,
- GraphWidthOutcome,
- HyGraphSnapshot,
- HyMemoryBridge,
- HyMemoryBridgeError,
- HyMemoryIngestRequest,
- HyMemoryIngestResult,
- HyMemoryOutput,
- HyMemoryTurn,
- builtin_retrieval_snapshot,
- coding_tool_result_max_bytes,
- decide_profile_graph_width,
- hy_memory_store_exists,
- inspect_profile_graph_width,
-)
-from one_memory.hy_runtime_config import hy_memory_version
-from one_memory.hy_source_context import HySourceContext, HySupportedMemory
-from one_memory.imports.access import opaque_workspace_id
-from one_memory.imports.models import EvidenceContentKind, EvidenceOrigin, EvidenceRecord
-from one_memory.imports.runner import live_sync_arrival
-from one_memory.imports.storage import EvidenceStore
-from one_memory.input_sanitization import sanitize_model_input
-from one_memory.memory_governance import (
- DeletionClaim,
- HyCreate,
- HyDerivation,
- HyLink,
- HyRetire,
- HyRevise,
- HySupersede,
- MemoryDraft,
- MemoryEvidenceOverriddenError,
- MemoryGovernanceStore,
- MemoryKind,
- MemoryMutationConflictError,
- MemoryOrigin,
- MemoryStatus,
-)
-from one_memory.memory_queue import (
- FRESH_WINDOW,
- MANUAL_EXTRACT_BATCH_SIZE,
- ExtractionWindowPreset,
- MemoryWorkQueue,
- QueueDepths,
- QueuedWork,
- classify,
- extraction_window_for,
-)
-from one_memory.memory_tasks import (
- TASK_MAX_ATTEMPTS,
- ActiveMemoryTask,
- MemoryTask,
- MemoryTaskKind,
- MemoryTaskOutput,
- MemoryTaskOwnershipError,
- MemoryTaskRequestConflictError,
- MemoryTaskStatus,
- MemoryTaskStore,
- TaskEvidenceRef,
- evidence_ref,
- matches_evidence_ref,
- materialize_evidence_ref,
- segment_evidence_record,
-)
-from one_memory.model_profiles import (
- ModelProfile,
- ModelProfileSnapshot,
- ModelProfileStore,
-)
-from one_memory.secrets import SecretStore, SecretStoreUnavailableError
-from one_memory.semantic_deadline import SemanticMemoryHit, normalize_semantic_hits
-from one_memory.service_levels import (
- ServiceLevel,
- ServiceLevelScheduler,
- ServiceResource,
- current_service_level,
-)
-
-# A read bridge warmed before the first vector write can retain Chroma's empty
-# collection view. Replace it once after that first successful write. Later
-# writes target the same persistent collection and must not create another HY
-# client (each client owns native threads); graph replacement resets the gate.
-_READ_BRIDGE_FIRST_REFRESH_DELAY_SECONDS = 0.05
-
-_CLAIMABLE_TASK_STATUSES = frozenset(
- {
- MemoryTaskStatus.PENDING,
- MemoryTaskStatus.WAITING_FOR_PERMISSION,
- MemoryTaskStatus.WAITING_FOR_MODEL,
- MemoryTaskStatus.FAILED,
- }
-)
-
-
-def _report_deletion_sync_failure(error: Exception) -> None:
- logging.getLogger(__name__).warning(
- "memory_deletion_sync_failed %s: %s", type(error).__name__, error
- )
- diagnostic_event(
- level="error",
- component="memory.deletion",
- event="memory_deletion.sync_failed",
- outcome="failed",
- error_code="memory_deletion_sync_failed",
- details={"reason": str(error)[:200]},
- **diagnostic_exception(error),
- )
-
-
-def _report_conversation_prepare_failure(source_id: str, error: Exception) -> None:
- logging.getLogger(__name__).warning(
- "memory_conversation_prepare_failed %s: %s", type(error).__name__, error
- )
- diagnostic_event(
- level="error",
- component="memory.scheduler",
- event="memory_conversation.prepare_failed",
- outcome="failed",
- error_code="memory_conversation_prepare_failed",
- details={"source_id": source_id, "reason": str(error)[:200]},
- **diagnostic_exception(error),
- )
-
-
-def _report_stale_known_reasons(task_id: str, reasons: Mapping[str, int]) -> None:
- """Emit one schema-valid scalar diagnostic per stale-memory reason."""
- for reason, count in sorted(reasons.items()):
- diagnostic_event(
- level="debug",
- component="memory.context",
- event="known_memory_stale_omitted",
- outcome="omitted",
- task_id=task_id,
- details={"reason": reason, "count": count},
- )
-
-
-MEMORY_INGEST_POLICY_VERSION = "hy-native-v23"
-UNIFIED_HY_AGENT_ID = "one-memory"
-#: Deterministic refusals raised before the payload reaches HY, so nothing was
-#: sent even though the invocation marker is already recorded by then: the
-#: write bindings are built inside `ingest` ahead of the call, and the input
-#: window is checked while the request is frozen.
-#:
-#: They are terminal rather than unknown. `unknown` here means "HY may hold a
-#: write we cannot confirm", and that is exactly what did not happen — parking
-#: the task on it hid the reason and stopped the queue behind it (issue #44).
-#: Kept in step with `durable_queue.PRE_SEND_REFUSAL_CODES`, which the durable
-#: write path applies to the same codes.
-PRE_SEND_REFUSAL_CODES = frozenset(
- {
- "hy_memory_input_exceeds_window",
- }
-)
-_BACKFILL_BATCH_SIZE = 8
-_BACKFILL_DRAIN_BUDGET_SECONDS = 330.0
-_HISTORY_MERGE_TURNS = 8
-_HISTORY_MERGE_CHARACTERS = 8_000
-#: The longest the deletion sync sleeps with nothing due, so a deletion
-#: recorded by another path is still picked up without being woken.
-DELETION_SYNC_IDLE_SECONDS = 300.0
-_TURN_SETTLE_SECONDS = 0.75
-_LIVE_OPEN_TURN_SETTLE_SECONDS = 30.0
-_BACKFILL_START_GRACE_SECONDS = 3.0
-MEMORY_TASK_TIMEOUT_MARGIN_SECONDS = 60.0
-MEMORY_TASK_TIMEOUT_MIN_SECONDS = 180.0
-ORPHAN_RECOVERY_INTERVAL_SECONDS = 15.0
-
-
-def memory_task_timeout_seconds(model_timeout_seconds: float) -> float:
- """Bound the whole HY pipeline without treating one request timeout as its budget."""
- return max(
- MEMORY_TASK_TIMEOUT_MIN_SECONDS,
- float(model_timeout_seconds) + MEMORY_TASK_TIMEOUT_MARGIN_SECONDS,
- )
-
-
-class MemoryBridgeProtocol(Protocol):
- async def ingest(self, request: HyMemoryIngestRequest) -> HyMemoryIngestResult: ...
-
- async def ingest_extracted(
- self,
- request: HyMemoryIngestRequest,
- contents: tuple[str, ...],
- ) -> HyMemoryIngestResult: ...
-
- async def profile_memories(
- self,
- *,
- user_id: str,
- agent_id: str,
- ) -> tuple[HyMemoryOutput, ...]: ...
-
- async def digest(self, *, user_id: str, agent_id: str) -> dict[str, object]: ...
-
- async def list_agent_ids(self, *, user_id: str, limit: int = 1_000) -> tuple[str, ...]: ...
-
- async def outputs_for_request(
- self,
- *,
- request_id: str,
- user_id: str,
- agent_id: str,
- evidence_ids: tuple[str, ...],
- ) -> tuple[HyMemoryOutput, ...]: ...
-
- async def receipt_for_request(
- self,
- *,
- request_id: str,
- user_id: str,
- agent_id: str,
- evidence_ids: tuple[str, ...],
- ) -> HyMemoryIngestResult | None: ...
-
- async def graph_snapshot(
- self,
- *,
- user_id: str,
- agent_id: str,
- limit: int = 300,
- ) -> HyGraphSnapshot: ...
-
- async def update(self, memory_id: str, content: str) -> dict[str, object]: ...
-
- async def delete(self, memory_id: str) -> dict[str, object]: ...
-
- async def search_scores(
- self,
- query: str,
- *,
- user_id: str,
- agent_id: str,
- limit: int = 12,
- ) -> tuple[tuple[str, float], ...]: ...
-
- async def close(self) -> None: ...
-
-
-class MemoryTaskRunner:
- def __init__(
- self,
- *,
- tasks: MemoryTaskStore,
- profiles: ModelProfileStore,
- secrets: SecretStore,
- evidence: EvidenceStore,
- governance: MemoryGovernanceStore,
- data_dir: Path,
- bridge_factory: (
- Callable[[ModelProfileSnapshot, str | None, Path], MemoryBridgeProtocol] | None
- ) = None,
- close_bridge: bool = True,
- sdk_authority: Callable[[], bool] | None = None,
- ) -> None:
- self.tasks = tasks
- self.profiles = profiles
- self.secrets = secrets
- self.evidence = evidence
- self.governance = governance
- self.data_dir = data_dir
- self.bridge_factory = bridge_factory or self._create_bridge
- self.close_bridge = close_bridge
- self.sdk_authority = sdk_authority or (lambda: False)
-
- async def run(
- self,
- task_id: str,
- *,
- timeout: float | None = None,
- before_hy_invocation: Callable[[], Awaitable[None]] | None = None,
- input_records: tuple[EvidenceRecord, ...] | None = None,
- ) -> MemoryTask:
- started = monotonic()
- diagnostic_event(
- level="info",
- component="memory.task",
- event="memory_task.started",
- outcome="started",
- task_id=task_id,
- )
- try:
- if input_records is None:
- body = (
- self._run_without_content_permission(task_id)
- if before_hy_invocation is None
- else self._run_without_content_permission(
- task_id,
- before_hy_invocation=before_hy_invocation,
- )
- )
- else:
- body = (
- self._run_without_content_permission(
- task_id,
- input_records=input_records,
- )
- if before_hy_invocation is None
- else self._run_without_content_permission(
- task_id,
- before_hy_invocation=before_hy_invocation,
- input_records=input_records,
- )
- )
- # The ceiling bounds how long this task holds its harness's slot:
- # a harness is serial, so one hung task starves every turn behind
- # it. It is insurance against a single bad call, not a way to run
- # faster.
- if timeout is None:
- result = await body
- else:
- try:
- result = await asyncio.wait_for(body, timeout=timeout)
- except TimeoutError:
- # The task was claimed as `running` before anything slow
- # happened, so leaving it there would hold the slot until
- # the next process start. Put it back so the turns behind
- # it can run, then say why.
- await in_the_background(
- self.tasks.recover_one_running,
- task_id,
- reason="hy_memory_timeout",
- )
- # `from None`: this is a deliberate translation of a
- # timeout into the vocabulary the caller classifies on,
- # not a new failure while handling one.
- raise HyMemoryBridgeError("hy_memory_timeout") from None
- except Exception as error:
- if isinstance(error, sqlite3.Error):
- record_database_error("memory.task", error)
- diagnostic_event(
- level="error",
- component="memory.task",
- event="memory_task.failed",
- outcome="failed",
- task_id=task_id,
- duration_ms=elapsed_ms(started),
- error_code="memory_task_execution_failed",
- **diagnostic_exception(error),
- )
- raise
- outputs, counts = await asyncio.gather(
- in_the_background(self.tasks.outputs, task_id),
- in_the_background(self.tasks.counts),
- )
- outstanding = sum(
- counts.get(status, 0)
- for status in (
- MemoryTaskStatus.PENDING,
- MemoryTaskStatus.WAITING_FOR_PERMISSION,
- MemoryTaskStatus.WAITING_FOR_MODEL,
- MemoryTaskStatus.FAILED,
- )
- )
- diagnostic_event(
- level="error" if result.status is MemoryTaskStatus.FAILED else "info",
- component="memory.task",
- event="memory_task.finished",
- outcome=str(result.status),
- task_id=task_id,
- duration_ms=elapsed_ms(started),
- state_after=str(result.status),
- error_code=result.last_error_code,
- details={
- "result_count": len(outputs),
- "pending_count": outstanding,
- "attempt": result.attempts,
- },
- )
- return result
-
- @staticmethod
- def _log_step(task_id: str, step: int, action: str, started: float) -> None:
- diagnostic_event(
- level="debug",
- component="memory.task",
- event="memory_task.step_completed",
- outcome="succeeded",
- task_id=task_id,
- duration_ms=elapsed_ms(started),
- details={"phase": str(step), "action": action},
- )
-
- async def _run_without_content_permission(
- self,
- task_id: str,
- *,
- before_hy_invocation: Callable[[], Awaitable[None]] | None = None,
- input_records: tuple[EvidenceRecord, ...] | None = None,
- ) -> MemoryTask:
- # Every store call here is synchronous, and several are writes that
- # wait on the write lock for up to five seconds. Made from the loop,
- # with hundreds of tasks each making a dozen of them, they blocked the
- # loop in bursts: /health, which does no work at all, was measured at
- # 3.5s and a library read at 20.7s, past the renderer's timeout. The
- # stores open a connection per call, so a thread is safe here.
- step_started = monotonic()
- task, runner_token = await in_the_background(self.tasks.claim, task_id)
- self._log_step(task_id, 1, "claim", step_started)
- hy_invoked = False
- # Before anything is read, so an overruling made while this task runs
- # is one the writes below can tell from those its context already left out.
- sdk_authority = self.sdk_authority()
- derivation = (
- None if sdk_authority else await in_the_background(self.governance.hy_derivation)
- )
- if task.kind is not MemoryTaskKind.EXTRACT:
- return await in_the_background(
- self.tasks.fail,
- task_id,
- runner_token=runner_token,
- error_code="memory_task_kind_not_wired",
- )
- # Reaches the macOS keychain, which is not something to wait for on
- # the loop either.
- step_started = monotonic()
- try:
- secret = await in_the_background(
- self.profiles.resolve_snapshot_secret,
- task.profile_id,
- task.profile_revision,
- self.secrets,
- )
- except SecretStoreUnavailableError:
- return await in_the_background(
- self.tasks.wait_for_model,
- task_id,
- runner_token=runner_token,
- error_code="secure_storage_unavailable",
- )
- if task.profile_snapshot.has_api_key and secret is None:
- return await in_the_background(
- self.tasks.wait_for_model,
- task_id,
- runner_token=runner_token,
- error_code="model_secret_unavailable",
- )
- self._log_step(task_id, 2, "credential", step_started)
- # Off the loop: this reads and rebuilds a whole conversation, and a
- # long one is seconds of it. Run here, with hundreds of tasks doing it
- # in turn, it held the loop for 17 seconds at a stretch — the whole
- # time, every host asking to recall something was simply waiting.
- step_started = monotonic()
- frozen = await in_the_background(self.tasks.inputs, task.task_id)
- chunk: tuple[EvidenceRecord, ...] | None
- if input_records is not None:
- chunk = input_records
- elif frozen:
- try:
- chunk = await in_the_background(self._frozen_chunk, task)
- except HyMemoryBridgeError as error:
- return await in_the_background(
- self.tasks.fail, task_id, runner_token=runner_token, error_code=str(error)
- )
- else:
- conversation = await in_the_background(self.evidence.list_conversation, task.input_ref)
- chunk = next(
- (
- candidate
- for candidate in _conversation_chunks(conversation)
- if task.input_ref in {r.evidence_id for r in candidate}
- ),
- None,
- )
- if chunk is None:
- return await in_the_background(self.tasks.complete, task_id, runner_token=runner_token)
- self._log_step(task_id, 3, "load_context", step_started)
- step_started = monotonic()
- bridge = self.bridge_factory(task.profile_snapshot, secret, self.data_dir)
- self._log_step(task_id, 4, "bridge_context", step_started)
- try:
- prepare = getattr(bridge, "prepare", None)
- if prepare is not None:
- await prepare()
- request = self._request(task, chunk)
- if sdk_authority and request.source_context is not None:
- request = request.model_copy(update={"source_context": None})
- elif request.source_context is not None:
- context = await in_the_background(
- self._source_context, task, request.source_context
- )
- request = request.model_copy(update={"source_context": context})
- uses_frozen_input = bool(frozen) or input_records is not None
- grant_token = (
- await in_the_background(self._grant_token, task, chunk[0])
- if uses_frozen_input
- else None
- )
- memory_contents = tuple(
- sanitize_model_input(record.verbatim)
- for record in chunk
- if _imported_as_said(record)
- )
- only_contents = bool(memory_contents) and all(_imported_as_said(r) for r in chunk)
- step_started = monotonic()
- if before_hy_invocation is not None:
- await before_hy_invocation()
- await in_the_background(
- self.tasks.record_hy_invocation,
- task_id,
- runner_token=runner_token,
- )
- hy_invoked = True
- if only_contents:
- result = await bridge.ingest_extracted(
- request,
- memory_contents,
- )
- else:
- result = await bridge.ingest(request)
- self._log_step(task_id, 5, "hy_ingest", step_started)
- if not result.success:
- raise HyMemoryBridgeError("hy_memory_runtime_failed")
- if only_contents and not result.memories:
- raise HyMemoryBridgeError("hy_memory_import_no_readable_output")
- step_started = monotonic()
- await in_the_background(
- self.tasks.save_sdk_receipt,
- task_id=task.task_id,
- request_id=request.request_id,
- raw_ids=result.raw_ids,
- memory_ids=tuple(memory.memory_id for memory in result.memories),
- )
- if sdk_authority:
- if uses_frozen_input:
- if input_records is None:
- await in_the_background(self._frozen_chunk, task)
- if grant_token != await in_the_background(
- self._grant_token,
- task,
- chunk[0],
- ):
- raise HyMemoryBridgeError("hy_memory_source_changed")
- self._log_step(task_id, 6, "sdk_receipt", step_started)
- return await in_the_background(
- self.tasks.complete,
- task_id,
- runner_token=runner_token,
- )
- assert derivation is not None
- outputs = result.memories
- # What HY learnt about the person, as opposed to about this
- # conversation. It arrives by being read back because the write
- # does not report it (see `profile_memories`), and it goes through
- # the same governance below as everything else — including the
- # dedupe, which is what stops the same unchanged profile being
- # recorded again by every task that follows.
- outputs = (
- *outputs,
- *await bridge.profile_memories(
- user_id=request.user_id,
- agent_id=request.agent_id,
- ),
- )
- if uses_frozen_input:
- if input_records is None:
- await in_the_background(self._frozen_chunk, task)
- if grant_token != await in_the_background(self._grant_token, task, chunk[0]):
- raise HyMemoryBridgeError("hy_memory_source_changed")
- if request.source_context is not None:
- await in_the_background(
- self._check_source_context,
- request.source_context,
- skip_current=input_records is not None,
- )
- # One thread hop for the whole batch rather than a dozen writes
- # made from the loop.
- step_started = monotonic()
- await in_the_background(
- self._record_outputs,
- task=task,
- chunk=chunk,
- outputs=outputs,
- request=request,
- derivation=derivation,
- retired=result.retired_memory_ids,
- superseded=result.superseded_memory_ids,
- )
- self._log_step(task_id, 6, "governance", step_started)
- except HyMemoryBridgeError as error:
- code = str(error)
- if code == "model_sedimentation_disabled" and not hy_invoked:
- return await in_the_background(
- self.tasks.release_unstarted,
- task_id,
- runner_token=runner_token,
- error_code=code,
- )
- model_wait_errors = {
- "hy_memory_unavailable",
- "hy_memory_rate_limit",
- "hy_memory_timeout",
- "hy_memory_runtime_failed",
- "model_secret_unavailable",
- "hy_memory_model_authentication_failed",
- "hy_memory_model_payment_required",
- "hy_memory_model_access_denied",
- "hy_memory_model_rate_limited",
- "hy_memory_model_service_unavailable",
- "hy_memory_model_timeout",
- }
- safe_terminal_after_invocation = {"hy_memory_import_no_readable_output"}
- if code in PRE_SEND_REFUSAL_CODES:
- # Raised before the call, so the marker only says "about to":
- # fail with the reason rather than parking on a write HY never
- # saw. See the constant and issue #44.
- return await in_the_background(
- self.tasks.fail,
- task_id,
- runner_token=runner_token,
- error_code=code,
- )
- if hy_invoked and (
- code == "hy_memory_evidence_changed"
- or (
- code not in {"hy_memory_source_changed", "hy_memory_source_revoked"}
- and code not in model_wait_errors | safe_terminal_after_invocation
- )
- ):
- return await in_the_background(
- self.tasks.mark_unknown,
- task_id,
- runner_token=runner_token,
- error_code=code,
- )
- if code in {"hy_memory_source_changed", "hy_memory_source_revoked"}:
- # The source grant changed after this task was claimed.
- return await in_the_background(
- self.tasks.stop,
- task_id,
- runner_token=runner_token,
- error_code=code,
- )
- if code in model_wait_errors:
- return await in_the_background(
- self.tasks.wait_for_model,
- task_id,
- runner_token=runner_token,
- error_code=code,
- )
- if code == "model_content_transport_request_failed":
- return await in_the_background(
- self.tasks.mark_unknown,
- task_id,
- runner_token=runner_token,
- error_code=code,
- )
- return await in_the_background(
- self.tasks.fail,
- task_id,
- runner_token=runner_token,
- error_code=code,
- )
- finally:
- if self.close_bridge:
- await bridge.close()
- return await in_the_background(self.tasks.complete, task_id, runner_token=runner_token)
-
- def _frozen_chunk(self, task: MemoryTask) -> tuple[EvidenceRecord, ...]:
- records = []
- for ref in self.tasks.inputs(task.task_id):
- record = self.evidence.get(ref["evidence_id"])
- if record is None or record.user_id != task.user_id:
- raise HyMemoryBridgeError("hy_memory_evidence_changed")
- materialized = materialize_evidence_ref(record, ref)
- if materialized is None:
- raise HyMemoryBridgeError("hy_memory_evidence_changed")
- with self.tasks._connect() as db:
- grant = db.execute(
- "SELECT revoked_at FROM source_grants WHERE user_id=? AND source_id=?",
- (record.user_id, record.source_id),
- ).fetchone()
- if grant is None or grant[0] is not None:
- raise HyMemoryBridgeError("hy_memory_source_revoked")
- records.append(materialized)
- return tuple(records)
-
- def _original_records(self, records: tuple[EvidenceRecord, ...]) -> tuple[EvidenceRecord, ...]:
- originals: dict[str, EvidenceRecord] = {}
- for record in records:
- current = self.evidence.get(record.evidence_id)
- if current is None:
- raise HyMemoryBridgeError("hy_memory_evidence_changed")
- originals.setdefault(current.evidence_id, current)
- return tuple(originals.values())
-
- def _grant_token(self, task: MemoryTask, seed: EvidenceRecord) -> str:
- with self.tasks._connect() as db:
- row = db.execute(
- "SELECT granted_at,revoked_at FROM source_grants WHERE user_id=? AND source_id=?",
- (task.user_id, seed.source_id),
- ).fetchone()
- if row is None or row[1] is not None:
- raise HyMemoryBridgeError("hy_memory_source_revoked")
- return str(row[0])
-
- def _source_context(
- self,
- task: MemoryTask,
- current: HySourceContext,
- *,
- persist_inputs: bool = True,
- ) -> HySourceContext:
- current_ids = {record.evidence_id for record in current.current}
- history: dict[str, EvidenceRecord] = {}
- known: dict[str, HySupportedMemory] = {}
- latest: dict[str, tuple[MemoryTaskOutput, tuple[TaskEvidenceRef, ...]]] = {}
- stale_known_reasons: dict[str, int] = {}
- for previous in self.tasks.completed_conversation_tasks(task, current.current[0]):
- if not previous.request_id.startswith(f"conversation:{MEMORY_INGEST_POLICY_VERSION}:"):
- continue
- refs = self.tasks.inputs(previous.task_id)
- if not refs:
- continue
- try:
- records = self._frozen_chunk(previous)
- except HyMemoryBridgeError:
- continue
- if any(
- (r.user_id, r.source_id, r.conversation_id)
- != (task.user_id, current.current[0].source_id, current.current[0].conversation_id)
- for r in records
- ):
- continue
- for record in records:
- if record.evidence_id not in current_ids and _is_hy_turn_record(record):
- history[record.evidence_id] = record
- for output in self.tasks.outputs(previous.task_id):
- latest[output.memory_id] = (output, output.support_refs or refs)
- for output, supports in latest.values():
- memory = self.governance.get(output.memory_id, user_id=task.user_id)
- # HY replaced it itself: its evidence still stands, but it is no
- # longer a memory HY may revise, so it is neither known nor a block.
- if memory is not None and memory.status is MemoryStatus.SUPERSEDED:
- continue
- if (
- memory is None
- or memory.revision != output.memory_revision
- or memory.status is not MemoryStatus.CONFIRMED
- ):
- reason = (
- "missing"
- if memory is None
- else (
- "revision_changed"
- if memory.revision != output.memory_revision
- else "not_confirmed"
- )
- )
- stale_known_reasons[reason] = stale_known_reasons.get(reason, 0) + 1
- continue
- if output.owner not in {"user", "agent"}:
- continue
- if set(memory.evidence_ids) != {ref["evidence_id"] for ref in supports}:
- # Merged support is not covered by this old output snapshot.
- # Keep permitted original history, but do not expand its authority.
- continue
- known[output.hy_memory_id] = HySupportedMemory(
- hy_memory_id=output.hy_memory_id,
- content=memory.content,
- owner="user" if output.owner == "user" else "agent",
- governed_memory_id=memory.memory_id,
- revision=memory.revision,
- evidence_ids=tuple(ref["evidence_id"] for ref in supports),
- )
- if stale_known_reasons:
- _report_stale_known_reasons(task.task_id, stale_known_reasons)
- blocked_evidence_ids = self.governance.blocked_source_ids(
- user_id=task.user_id,
- evidence_ids=tuple(current_ids | set(history)),
- )
- if blocked_evidence_ids & current_ids:
- raise HyMemoryBridgeError("hy_memory_evidence_changed")
- selected: list[EvidenceRecord] = []
- used_chars = 0
- for record in reversed(tuple(history.values())):
- if record.evidence_id in blocked_evidence_ids:
- continue
- if len(selected) == 10 or used_chars + len(record.verbatim) > 12_000:
- break
- selected.append(record)
- used_chars += len(record.verbatim)
- selected.reverse()
- selected_ids = {record.evidence_id for record in selected}
- supporting = tuple(
- r
- for key, r in history.items()
- if key not in selected_ids and key not in blocked_evidence_ids
- )
- ids = current_ids | selected_ids | {r.evidence_id for r in supporting}
- context = HySourceContext(
- current=current.current,
- history=tuple(selected),
- supporting=supporting,
- known_memories=tuple(
- m
- for m in known.values()
- if set(m.evidence_ids) <= ids and not set(m.evidence_ids) & blocked_evidence_ids
- ),
- )
- if persist_inputs:
- try:
- self.tasks.save_context_inputs(
- task.task_id, (*context.history, *context.supporting)
- )
- except MemoryTaskRequestConflictError as error:
- raise HyMemoryBridgeError("hy_memory_evidence_changed") from error
- return context
-
- def _check_source_context(
- self,
- context: HySourceContext,
- *,
- skip_current: bool = False,
- ) -> None:
- checked = (
- (*context.history, *context.supporting)
- if skip_current
- else (*context.current, *context.history, *context.supporting)
- )
- for original in checked:
- record = self.evidence.get(original.evidence_id)
- if record is None or not matches_evidence_ref(record, evidence_ref(original)):
- raise HyMemoryBridgeError("hy_memory_evidence_changed")
- # A deletion/correction during the model call cannot become an old-memory update.
- for known in context.known_memories:
- memory = self.governance.get(
- known.governed_memory_id, user_id=context.current[0].user_id
- )
- if (
- memory is None
- or memory.revision != known.revision
- or memory.content != known.content
- or memory.status is not MemoryStatus.CONFIRMED
- ):
- raise HyMemoryBridgeError("hy_memory_evidence_changed")
-
- def _record_provenance(
- self,
- task: MemoryTask,
- memory_id: str,
- output: HyMemoryOutput,
- support: tuple[EvidenceRecord, ...],
- ) -> None:
- memory = self.governance.get(memory_id, user_id=task.user_id)
- if memory is None:
- raise HyMemoryBridgeError("hy_memory_governance_missing")
- self.tasks.save_output(
- MemoryTaskOutput(
- task_id=task.task_id,
- memory_id=memory_id,
- memory_revision=memory.revision,
- hy_memory_id=output.memory_id,
- owner=output.owner,
- layer=output.layer,
- engine_version=hy_memory_version(),
- support_refs=tuple(evidence_ref(record) for record in support),
- )
- )
-
- def _record_outputs(
- self,
- *,
- task: MemoryTask,
- chunk: tuple[EvidenceRecord, ...],
- outputs: tuple[HyMemoryOutput, ...],
- request: HyMemoryIngestRequest,
- derivation: HyDerivation,
- retired: tuple[str, ...] = (),
- superseded: Mapping[str, tuple[str, ...]] | None = None,
- ) -> None:
- try:
- self._record_outputs_checked(
- task=task,
- chunk=chunk,
- outputs=outputs,
- request=request,
- derivation=derivation,
- retired=retired,
- superseded=superseded or {},
- )
- except MemoryMutationConflictError as error:
- # Overruled evidence, or a memory the person changed while HY was
- # working: either way what HY wrote was about something else.
- raise HyMemoryBridgeError("hy_memory_evidence_changed") from error
-
- def _record_outputs_checked(
- self,
- *,
- task: MemoryTask,
- chunk: tuple[EvidenceRecord, ...],
- outputs: tuple[HyMemoryOutput, ...],
- request: HyMemoryIngestRequest,
- derivation: HyDerivation,
- retired: tuple[str, ...] = (),
- superseded: Mapping[str, tuple[str, ...]] | None = None,
- ) -> None:
- """Writes what HY produced into governance. Synchronous on purpose:
- the caller runs it in a thread, so the loop stays free to answer."""
- source_records = (
- (
- *request.source_context.current,
- *request.source_context.history,
- *request.source_context.supporting,
- )
- if request.source_context
- else chunk
- )
- by_id = {record.evidence_id: record for record in source_records}
- # A deletion or replacement is HY's reading of the whole turn, so it
- # rests on everything the turn showed it.
- whole_turn = derivation.citing(by_id)
- for output in outputs:
- layer = output.layer
- ids = output.evidence_ids or request.evidence_ids
- if not set(ids) <= set(by_id):
- raise HyMemoryBridgeError("hy_memory_write_verification_support_missing")
- support = tuple(by_id[key] for key in ids)
- # HY's own attribution. An undecided memory counts as the person's:
- # HY's prompt defaults that way.
- from_agent = output.owner == "agent" or all(
- record.role == "assistant"
- and record.content_kind is EvidenceContentKind.RAW_CONVERSATION
- for record in support
- )
- content = sanitize_model_input(output.content)
- known = (
- next(
- (
- memory
- for memory in request.source_context.known_memories
- if memory.hy_memory_id == output.memory_id
- ),
- None,
- )
- if request.source_context
- else None
- )
- if known is not None and known.content != content:
- if known.owner != output.owner:
- raise HyMemoryBridgeError("hy_memory_write_verification_authority_invalid")
- try:
- updated = self.governance.write_from_hy(
- HyRevise(
- memory_id=known.governed_memory_id,
- request_id=f"hy-update:{task.task_id}:{output.memory_id}",
- expected_revision=known.revision,
- content=content,
- evidence_ids=ids,
- ),
- user_id=task.user_id,
- derivation=derivation.citing(ids),
- )
- except MemoryMutationConflictError as error:
- raise HyMemoryBridgeError("hy_memory_evidence_changed") from error
- self._record_provenance(task, updated.memory_id, output, support)
- continue
- revised = (
- self.governance.get(output.memory_id, user_id=task.user_id)
- if known is None and layer in HY_CODING_LAYERS
- else None
- )
- if revised is not None and revised.content != content:
- # HY's coding store only lets it revise rows this lease attests.
- if revised.status is not MemoryStatus.CONFIRMED or not set(
- revised.evidence_ids
- ) <= set(by_id):
- raise HyMemoryBridgeError("hy_memory_write_verification_authority_invalid")
- try:
- updated = self.governance.write_from_hy(
- HyRevise(
- memory_id=revised.memory_id,
- request_id=f"hy-update:{task.task_id}:{output.memory_id}",
- expected_revision=revised.revision,
- content=content,
- evidence_ids=tuple(dict.fromkeys((*revised.evidence_ids, *ids))),
- ),
- user_id=task.user_id,
- derivation=derivation.citing(ids),
- )
- except MemoryMutationConflictError as error:
- raise HyMemoryBridgeError("hy_memory_evidence_changed") from error
- self._record_provenance(task, updated.memory_id, output, support)
- continue
- existing = self.governance.get(output.memory_id, user_id=task.user_id)
- if existing is not None and existing.content == content:
- linked = existing
- for evidence_id in ids:
- linked = self.governance.write_from_hy(
- HyLink(memory_id=existing.memory_id, evidence_id=evidence_id),
- user_id=task.user_id,
- derivation=derivation.citing(ids),
- )
- self._record_provenance(task, linked.memory_id, output, support)
- continue
- memory = self.governance.write_from_hy(
- HyCreate(
- draft=MemoryDraft(
- user_id=task.user_id,
- kind=_memory_kind(layer),
- content=content,
- scopes=_memory_scopes(support, layer=layer),
- evidence_ids=ids,
- tags=output.tags[:32],
- origin=MemoryOrigin.AGENT if from_agent else MemoryOrigin.EXTRACTED,
- ),
- request_id=f"extract:{task.task_id}:{output.memory_id}",
- memory_id=output.memory_id,
- ),
- user_id=task.user_id,
- derivation=derivation.citing(ids),
- )
- # Usable on arrival whoever said it; `origin` tells recall and
- # matters that an assistant's sentence is not the person's own.
- self._record_provenance(task, memory.memory_id, output, support)
- for memory_id in retired:
- mirrored = self.governance.get(memory_id, user_id=task.user_id)
- if mirrored is None or mirrored.status is MemoryStatus.DELETED:
- continue
- self.governance.write_from_hy(
- HyRetire(
- memory_id=memory_id,
- request_id=f"hy-delete:{task.task_id}:{memory_id}",
- expected_revision=mirrored.revision,
- ),
- user_id=task.user_id,
- derivation=whole_turn,
- )
- for memory_id, replaced_by in sorted((superseded or {}).items()):
- mirrored = self.governance.get(memory_id, user_id=task.user_id)
- if mirrored is None or mirrored.status not in {
- MemoryStatus.CONFIRMED,
- MemoryStatus.SUPERSEDED,
- }:
- continue
- # Only replacements the ledger holds; otherwise the old memory
- # would leave every list while pointing at nothing the user can read.
- heads = tuple(
- key
- for key in replaced_by
- if (head := self.governance.get(key, user_id=task.user_id)) is not None
- and head.status is not MemoryStatus.DELETED
- )
- if not heads:
- continue
- self.governance.write_from_hy(
- HySupersede(
- memory_id=memory_id,
- request_id=f"hy-supersede:{task.task_id}:{memory_id}",
- expected_revision=mirrored.revision,
- superseded_by=heads,
- ),
- user_id=task.user_id,
- derivation=whole_turn,
- )
- self._save_extraction_for_training(task, outputs)
-
- def _save_extraction_for_training(
- self,
- task: MemoryTask,
- outputs: tuple[HyMemoryOutput, ...],
- ) -> None:
- """Persist what this task extracted so training can read it later.
-
- `save_extraction` sat unused (A-20): governance got the memories, the
- training table got nothing. One row per task — short enough to be a
- single supervised target (1–160 chars), or a null row when the turn
- produced no trainable memory (negative examples matter as much as
- positives). Longer outputs are skipped rather than truncated: a cut
- sentence is worse training data than an honest null.
- """
- for output in outputs:
- content = sanitize_model_input(output.content).strip()
- layer = output.layer
- if not layer or not (1 <= len(content) <= 160):
- continue
- try:
- self.tasks.save_extraction(task.task_id, content=content, layer=layer)
- except MemoryTaskRequestConflictError:
- return
- return
- try:
- self.tasks.save_extraction(task.task_id, content=None, layer=None)
- except MemoryTaskRequestConflictError:
- return
-
- @staticmethod
- def _request(
- task: MemoryTask,
- chunk: tuple[EvidenceRecord, ...],
- ) -> HyMemoryIngestRequest:
- return MemoryTaskRunner.request_for(task.request_id, chunk)
-
- @staticmethod
- def request_for(
- request_id: str,
- chunk: tuple[EvidenceRecord, ...],
- ) -> HyMemoryIngestRequest:
- if not chunk:
- # A task with no inputs has nothing to name the request after and
- # nothing to attribute an answer to. Left alone this reached
- # `chunk[0]` below and came out as IndexError, which no caller can
- # read: a reconcile pass catches domain errors per task and moves
- # on, so one such task ended the whole pass and left every other
- # unknown task unreconciled. On this machine 68 of 303 unknown
- # tasks had no inputs, and the pass raised on the first of them.
- raise HyMemoryBridgeError("hy_memory_task_without_inputs")
- has_raw = any(
- record.content_kind is EvidenceContentKind.RAW_CONVERSATION for record in chunk
- )
- source = next(
- (record for record in chunk if record.role == "user"),
- chunk[0],
- )
- request_turns = tuple(
- record
- for record in chunk
- if (
- record.content_kind is EvidenceContentKind.RAW_CONVERSATION
- and (
- # Protocol role is authoritative. A sub-agent question is
- # an ordinary user message regardless of a host parser's
- # former author guess.
- record.role == "user"
- # The assistant's side goes too. Without it 「就按你说的那个来」
- # arrives with nothing to resolve it against, and HY's own
- # prompt is written expecting both — its first example is
- # about resolving a pronoun against an earlier assistant
- # turn. It is context, not evidence of what the person
- # said; what it produces is filtered on the way back.
- or record.role == "assistant"
- # Tool calls go as they happened; whether they make the
- # turn a coding turn is HY's call, not ours.
- or record.role == "tool"
- )
- )
- or (not has_raw and record.content_kind is EvidenceContentKind.MEMORY_CONTENT)
- )
- return HyMemoryIngestRequest(
- request_id=request_id,
- user_id=source.user_id,
- source_id=source.source_id,
- agent_id=_hy_agent_id(chunk),
- session_id=source.conversation_id,
- turns=tuple(
- HyMemoryTurn(
- role=item.role if item.role in {"user", "assistant", "tool"} else "user",
- content=sanitize_model_input(item.verbatim),
- )
- for item in request_turns
- ),
- evidence_ids=tuple(item.evidence_id for item in request_turns),
- workspace_ids=tuple(
- sorted({item.workspace for item in chunk if item.workspace is not None})
- ),
- memory_at=max(
- (item.created_at for item in chunk if item.created_at is not None),
- default=None,
- ),
- source_context=HySourceContext(current=request_turns)
- if not any("segment_hash" in evidence_ref(item) for item in request_turns)
- and all(
- item.content_kind is EvidenceContentKind.RAW_CONVERSATION for item in request_turns
- )
- else None,
- )
-
- @staticmethod
- def _create_bridge(
- profile: ModelProfileSnapshot,
- secret: str | None,
- data_dir: Path,
- ) -> HyMemoryBridge:
- return HyMemoryBridge(
- profile=profile,
- api_key=secret,
- data_dir=data_dir,
- )
-
-
-@dataclass
-class _BackfillAcceptance:
- revision: int | None
- ready: asyncio.Event = field(default_factory=asyncio.Event)
- task: asyncio.Task[None] | None = None
- error: str | None = None
-
-
-_digest_guard_lock = threading.Lock()
-_digest_guard: asyncio.Lock | None = None
-_source_guard_lock = threading.Lock()
-_source_guards: WeakKeyDictionary[asyncio.AbstractEventLoop, dict[str, "_PrioritySourceLock"]] = (
- WeakKeyDictionary()
-)
-_direct_task_guard = threading.Lock()
-_direct_tasks_by_database: dict[str, dict[str, int]] = {}
-
-
-def _digest_mutex() -> asyncio.Lock:
- """The one lock that orders digests, for the whole process.
-
- A per-supervisor lock could not order two digests started from different
- supervisors, which is exactly the case that matters: one harness's
- catch-up overlapping another's live sync.
- """
- global _digest_guard
- with _digest_guard_lock:
- if _digest_guard is None:
- _digest_guard = asyncio.Lock()
- return _digest_guard
-
-
-class _PrioritySourceLock:
- """One-at-a-time source admission with P0/P1 ahead of queued P2 work."""
-
- def __init__(self) -> None:
- self._condition = asyncio.Condition()
- self._locked = False
- self._sequence = 0
- self._waiters: list[tuple[ServiceLevel, int]] = []
-
- async def acquire(self, level: ServiceLevel) -> None:
- async with self._condition:
- self._sequence += 1
- waiter = (level, self._sequence)
- self._waiters.append(waiter)
- try:
- while self._locked or min(self._waiters) != waiter:
- await self._condition.wait()
- except BaseException:
- with suppress(ValueError):
- self._waiters.remove(waiter)
- self._condition.notify_all()
- raise
- self._waiters.remove(waiter)
- self._locked = True
-
- async def release(self) -> None:
- async with self._condition:
- if not self._locked:
- raise RuntimeError("source lock is not held")
- self._locked = False
- self._condition.notify_all()
-
- def locked(self) -> bool:
- return self._locked
-
-
-def _shared_source_lock(source_id: str) -> _PrioritySourceLock:
- """One source lock shared by every supervisor on the current event loop."""
- loop = asyncio.get_running_loop()
- with _source_guard_lock:
- guards = _source_guards.setdefault(loop, {})
- return guards.setdefault(source_id, _PrioritySourceLock())
-
-
-def _mark_direct_task(database: Path, task_id: str) -> None:
- key = str(database.resolve())
- with _direct_task_guard:
- active = _direct_tasks_by_database.setdefault(key, {})
- active[task_id] = active.get(task_id, 0) + 1
-
-
-def _unmark_direct_task(database: Path, task_id: str) -> None:
- key = str(database.resolve())
- with _direct_task_guard:
- active = _direct_tasks_by_database.get(key)
- if active is None:
- return
- remaining = active.get(task_id, 0) - 1
- if remaining > 0:
- active[task_id] = remaining
- else:
- active.pop(task_id, None)
- if not active:
- _direct_tasks_by_database.pop(key, None)
-
-
-def _direct_tasks_for(database: Path) -> tuple[str, ...]:
- key = str(database.resolve())
- with _direct_task_guard:
- return tuple(_direct_tasks_by_database.get(key, ()))
-
-
-class MemoryProcessingSupervisor:
- def __init__(
- self,
- *,
- tasks: MemoryTaskStore,
- profiles: ModelProfileStore,
- secrets: SecretStore,
- evidence: EvidenceStore,
- governance: MemoryGovernanceStore,
- data_dir: Path,
- extraction_settings: ExtractionSettingsStore | None = None,
- runner_factory: Callable[[], MemoryTaskRunner] | None = None,
- bridge_factory: (
- Callable[[ModelProfileSnapshot, str | None, Path], MemoryBridgeProtocol] | None
- ) = None,
- max_concurrent_tasks: int | None = None,
- source_writes_permitted: Callable[[str], bool] | None = None,
- service_levels: ServiceLevelScheduler | None = None,
- sedimentation_enabled: Callable[[], bool] | None = None,
- sdk_authority: Callable[[], bool] | None = None,
- ) -> None:
- self.tasks = tasks
- self.profiles = profiles
- self.secrets = secrets
- self.evidence = evidence
- self.governance = governance
- self.data_dir = data_dir
- #: Per-source "may this become a memory" switch. Optional so tests and
- #: a Core without a grant store keep their current behaviour; when
- #: absent every source is treated as writable, which is what the
- #: product did before the switch existed.
- self.source_writes_permitted = source_writes_permitted
- #: User-level "stop turning conversations into memories" switch. Optional
- #: so tests and a Core without a config file keep their current
- #: behaviour; when absent sedimentation is on, which is what the product
- #: did before the switch existed. Read per decision rather than cached,
- #: so stopping takes effect on the next dispatch without a restart.
- self.sedimentation_enabled = sedimentation_enabled
- self.sdk_authority = sdk_authority or (lambda: False)
- self.service_levels = service_levels or ServiceLevelScheduler()
- self.extraction_settings = extraction_settings or ExtractionSettingsStore(
- data_dir / "one-memory.sqlite3"
- )
- self.runner_factory = runner_factory or self._create_runner
- self.bridge_factory = bridge_factory or MemoryTaskRunner._create_bridge
- # `None` means "whatever the model profile allows". The profile has
- # carried a `max_concurrency` all along — copied into every task's
- # snapshot and then never consulted — so the number is taken from the
- # snapshot rather than read back out of the store: it is the same
- # value, it is already in hand, and reading it costs nothing.
- self._fixed_concurrent = max_concurrent_tasks
- self._profile_concurrent = 1
- # Wall-clock ceiling for one task, taken from the profile the same way
- # `max_concurrency` is. `None` means "not configured", in which case no
- # budget is imposed rather than a guess being invented.
- self._profile_timeout: float | None = None
- self._queue = MemoryWorkQueue()
- self._workers: dict[int, asyncio.Task[None]] = {}
- self._in_flight: dict[str, QueuedWork] = {}
- self._active_window_cursors: dict[bool, tuple[datetime | None, str]] = {}
- self._bridges: dict[tuple[str, int, str | None], MemoryBridgeProtocol] = {}
- # Reads share the same on-disk HY store but never the write bridge's
- # serialization lock. A long ingest must not make host recall queue
- # behind it; WAL and the HY read APIs provide the storage boundary.
- self._read_bridges: dict[tuple[str, int], MemoryBridgeProtocol] = {}
- self._read_bridges_ready: set[tuple[str, int]] = set()
- self._read_bridge_refresh_lock = asyncio.Lock()
- self._read_bridge_generations: dict[tuple[str, int], int] = {}
- self._read_bridge_refresh_tasks: dict[tuple[str, int], asyncio.Task[None]] = {}
- self._deletions_due = asyncio.Event()
- self._debounces: dict[tuple[str, str, str, str | None], asyncio.Task[None]] = {}
- self._preparations: dict[tuple[str, str, str, str | None], asyncio.Task[None]] = {}
- self._shutting_down = False
- self._manual_batches_planned = 0
- self._manual_batches_promoted = 0
- self._manual_batch_remaining: list[str] = []
- self._continuing_older = False
- # Set while durable pending work may remain outside the current
- # in-memory window; cleared by the first empty refill.
- self._older_waiting = False
- self._backfill_lock = asyncio.Lock()
- self._backfill_clock = monotonic
- self._backfill_round_budget_seconds = _BACKFILL_DRAIN_BUDGET_SECONDS
- self._backfill_preparations: set[asyncio.Task[list[QueuedWork] | None]] = set()
- self._dispatch_checks: set[asyncio.Task[list[QueuedWork]]] = set()
- self._live_backfill: asyncio.Task[None] | None = None
- self._backfill_acceptance: _BackfillAcceptance | None = None
- self._accept_backfill_lock = asyncio.Lock()
- self._shutdown_task: asyncio.Task[None] | None = None
- self._orphan_reclaimer: asyncio.Task[None] | None = None
- self._diagnostic_idle_reason: str | None = None
-
- def _sedimentation_stopped(self) -> bool:
- """Whether the user stopped model-driven sedimentation.
-
- Stopping must not look like a broken pipeline: nothing is sent to the
- model, so the pending count stays as it is and the scheduler reports
- why it is idle. Starting again picks the same work up.
- """
- if self.sedimentation_enabled is None:
- return False
- if self.sedimentation_enabled():
- return False
- self._record_idle("sedimentation_stopped")
- return True
-
- def _record_idle(self, reason: str) -> None:
- if self._diagnostic_idle_reason == reason:
- return
- self._diagnostic_idle_reason = reason
- diagnostic_event(
- level="debug",
- component="memory.scheduler",
- event="memory_scheduler.idle",
- outcome="idle",
- details={
- "reason": reason,
- "queue_depth": len(self._queue),
- "in_flight_count": len(self._in_flight),
- },
- )
-
- async def process_records(
- self,
- records: tuple[EvidenceRecord, ...],
- *,
- profile_id: str | None = None,
- on_progress: Callable[[tuple[MemoryTask, ...], int], None] | None = None,
- before_hy_invocation: Callable[[], Awaitable[None]] | None = None,
- source_admitted: bool = False,
- ) -> tuple[MemoryTask, ...]:
- """Process a bounded, authorized snapshot through the existing HY runner."""
- async with self._explicit_processing_lock(records):
- if self._sedimentation_stopped():
- raise HyMemoryBridgeError("model_sedimentation_disabled")
- active = await in_the_background(self.profiles.active, self.secrets)
- if active is None or (profile_id is not None and profile_id != active.profile_id):
- raise HyMemoryBridgeError("model_profile_not_active")
- # The durable drain and explicit processing entry reach HY through
- # this method, not through the backfill scheduler. New work from a
- # frozen Harness must be refused before any task or bridge call.
- if (
- not source_admitted
- and self.source_writes_permitted is not None
- and not await in_the_background(self._source_may_write, list(records))
- ):
- raise HyMemoryBridgeError("hy_memory_source_disabled")
- conversations: dict[tuple[str, str, str | None], list[EvidenceRecord]] = {}
- for record in records:
- conversations.setdefault(
- (record.source_id, record.conversation_id, record.workspace), []
- ).append(record)
- # Tool events belong to the surrounding complete turn. A durable
- # intake can still deliver one on its own, before the adjacent
- # user/assistant message is available; creating a standalone task
- # for it makes the coverage check (correctly) reject the batch.
- # Keep the Evidence searchable and let the next complete-turn
- # delivery include it as context instead.
- if not any(_is_hy_input_turn(record) for record in records):
- return ()
- chunks = [
- chunk
- for conversation in conversations.values()
- for chunk in _conversation_chunks(conversation, max_turns=12, completed_only=True)
- ]
- prepared: list[tuple[MemoryTask, tuple[EvidenceRecord, ...]]] = []
- for chunk in chunks:
- task = await in_the_background(
- self._enqueue_chunk,
- chunk,
- active,
- freeze_inputs=True,
- )
- prepared.append((task, chunk))
- runner = self.runner_factory()
- completed = []
- if on_progress:
- on_progress(tuple(task for task, _chunk in prepared), 0)
- for task, chunk in prepared:
- if task.status is not MemoryTaskStatus.COMPLETED:
- # Another importer may already own this task. Never race its claim.
- task = await in_the_background(self.tasks.require, task.task_id)
- if task.status is MemoryTaskStatus.RUNNING:
- raise HyMemoryBridgeError("hy_memory_task_busy")
- if task.status is not MemoryTaskStatus.COMPLETED:
- # The profile's own wall-clock ceiling, exactly like the
- # scheduler path below. Without it this direct entry
- # (the durable drain calls `process_records`, not the
- # scheduler) had no bound at all: a hung model call
- # would hold the single harness slot until the process
- # died, and the drain's lease renewal would keep
- # extending a job that can never finish. The runner
- # turns a timeout into `hy_memory_timeout`, which
- # `classify` maps to `wait_for_model` rather than a
- # blind retry.
- _mark_direct_task(self.tasks.database_path, task.task_id)
- try:
- timeout = memory_task_timeout_seconds(
- task.profile_snapshot.timeout_seconds
- )
- level = current_service_level()
- async with self.service_levels.admit(
- ServiceResource.MODEL,
- level,
- work_id=task.task_id,
- scope_key=chunk[0].source_id,
- ):
- if isinstance(runner, MemoryTaskRunner):
- task = (
- await runner.run(
- task.task_id,
- timeout=timeout,
- input_records=chunk,
- )
- if before_hy_invocation is None
- else await runner.run(
- task.task_id,
- timeout=timeout,
- before_hy_invocation=before_hy_invocation,
- input_records=chunk,
- )
- )
- else:
- task = (
- await runner.run(task.task_id, timeout=timeout)
- if before_hy_invocation is None
- else await runner.run(
- task.task_id,
- timeout=timeout,
- before_hy_invocation=before_hy_invocation,
- )
- )
- finally:
- _unmark_direct_task(self.tasks.database_path, task.task_id)
- if task.status is not MemoryTaskStatus.COMPLETED:
- raise HyMemoryBridgeError(task.last_error_code or "hy_memory_incomplete")
- completed.append(task)
- if on_progress:
- on_progress(
- tuple(prepared_task for prepared_task, _chunk in prepared),
- len(completed),
- )
- expected = {record.evidence_id for record in records if _is_hy_turn_record(record)}
- actual = {
- row["evidence_id"] for task in completed for row in self.tasks.inputs(task.task_id)
- }
- if expected != actual:
- raise HyMemoryBridgeError("hy_memory_input_coverage_incomplete")
- if completed:
- await self._refresh_read_bridge(completed[-1].profile_snapshot)
- return tuple(completed)
-
- async def process_sdk_job(
- self,
- records: tuple[EvidenceRecord, ...],
- *,
- request_id: str,
- before_hy_invocation: Callable[[], Awaitable[None]],
- ) -> HyMemoryIngestResult:
- """Execute one durable SDK-authority job as exactly one SDK write."""
- if not self.sdk_authority():
- raise HyMemoryBridgeError("sdk_memory_authority_required")
- if not records:
- raise HyMemoryBridgeError("hy_memory_task_without_inputs")
- if self._sedimentation_stopped():
- raise HyMemoryBridgeError("model_sedimentation_disabled")
- if self.source_writes_permitted is not None and not await in_the_background(
- self._source_may_write, list(records)
- ):
- raise HyMemoryBridgeError("hy_memory_source_disabled")
- credentials = await self._active_credentials()
- if credentials is None:
- raise HyMemoryBridgeError("model_profile_not_active")
- snapshot, secret = credentials
- bridge = self._bridge(
- snapshot,
- secret,
- self.data_dir,
- scope_key=records[0].source_id,
- )
- prepare = getattr(bridge, "prepare", None)
- if prepare is not None:
- await prepare()
- request = MemoryTaskRunner.request_for(request_id, records).model_copy(
- update={"source_context": None}
- )
- contents = tuple(
- sanitize_model_input(record.verbatim) for record in records if _imported_as_said(record)
- )
- only_contents = bool(contents) and all(_imported_as_said(record) for record in records)
- await before_hy_invocation()
- result = (
- await bridge.ingest_extracted(request, contents)
- if only_contents
- else await bridge.ingest(request)
- )
- if not result.success:
- raise HyMemoryBridgeError("hy_memory_runtime_failed")
- if only_contents and not result.memories:
- raise HyMemoryBridgeError("hy_memory_import_no_readable_output")
- await self._refresh_read_bridge(snapshot)
- return result
-
- async def reconcile_unknown_outputs(
- self,
- *,
- limit: int = 128,
- exclude_error_codes: tuple[str, ...] = (),
- ) -> int:
- """Publish HY outputs that can be proven by an unknown task's request id.
-
- This inquiry is read-only on HY and never invokes the model. Rows with
- no exact match remain unknown for the person's explicit retry choice.
- """
- reconciled = 0
- tasks = await in_the_background(
- self.tasks.unknown_tasks,
- limit=limit,
- exclude_error_codes=exclude_error_codes,
- )
- for task in tasks:
- runner = self.runner_factory()
- bridge: MemoryBridgeProtocol | None = None
- try:
- chunk = await in_the_background(runner._frozen_chunk, task)
- request = runner._request(task, chunk)
- secret = await in_the_background(
- self.profiles.resolve_snapshot_secret,
- task.profile_id,
- task.profile_revision,
- self.secrets,
- )
- if task.profile_snapshot.has_api_key and secret is None:
- continue
- bridge = self.bridge_factory(task.profile_snapshot, secret, self.data_dir)
- receipt_inquiry = getattr(bridge, "receipt_for_request", None)
- if receipt_inquiry is not None:
- sdk_result = await receipt_inquiry(
- request_id=request.request_id,
- user_id=request.user_id,
- agent_id=request.agent_id,
- evidence_ids=request.evidence_ids,
- )
- if sdk_result is None or not sdk_result.success:
- continue
- await in_the_background(
- self.tasks.save_sdk_receipt,
- task_id=task.task_id,
- request_id=request.request_id,
- raw_ids=sdk_result.raw_ids,
- memory_ids=tuple(memory.memory_id for memory in sdk_result.memories),
- )
- outputs = sdk_result.memories
- else:
- inquiry = getattr(bridge, "outputs_for_request", None)
- if inquiry is None:
- continue
- outputs = await inquiry(
- request_id=request.request_id,
- user_id=request.user_id,
- agent_id=request.agent_id,
- evidence_ids=request.evidence_ids,
- )
- if not outputs and self.tasks.sdk_receipt(task.task_id) is None:
- continue
- derivation = await in_the_background(self.governance.hy_derivation)
- await in_the_background(
- runner._record_outputs,
- task=task,
- chunk=chunk,
- outputs=outputs,
- request=request,
- derivation=derivation,
- )
- resolved = await in_the_background(
- self.tasks.resolve_unknown,
- task.task_id,
- found=True,
- detail="model_content_outcome_reconciled",
- )
- if resolved is MemoryTaskStatus.COMPLETED:
- reconciled += 1
- await self._refresh_read_bridge(task.profile_snapshot)
- except (HyMemoryBridgeError, SecretStoreUnavailableError, ValueError):
- continue
- finally:
- if bridge is not None:
- await bridge.close()
- return reconciled
-
- @asynccontextmanager
- async def _explicit_processing_lock(
- self, records: tuple[EvidenceRecord, ...]
- ) -> AsyncIterator[None]:
- async with self._source_processing_lock({record.source_id for record in records}):
- yield
-
- @asynccontextmanager
- async def _source_processing_lock(
- self,
- source_ids: Collection[str],
- *,
- level: ServiceLevel | None = None,
- ) -> AsyncIterator[None]:
- """Serialize HY work per source while prioritizing queued realtime turns."""
- level = level or current_service_level()
- entries = [
- (source_id, _shared_source_lock(source_id)) for source_id in sorted(set(source_ids))
- ]
- acquired: list[_PrioritySourceLock] = []
- try:
- for _source_id, lock in entries:
- await lock.acquire(level)
- acquired.append(lock)
- yield
- finally:
- for lock in reversed(acquired):
- await lock.release()
-
- def extraction_window_settings(self) -> ExtractionSettings:
- return self.extraction_settings.get()
-
- def set_extraction_window(
- self,
- preset: ExtractionWindowPreset,
- ) -> ExtractionSettings:
- """Persist the preset and reclassify deferred work under the new window.
-
- Widening does not dump every newly eligible task onto the scheduler:
- those that still fall outside stay deferred; those that now fit are
- promoted in the same small batches as a manual extract.
- """
- settings = self.extraction_settings.set_window_preset(preset)
- window = extraction_window_for(preset)
- now = datetime.now(UTC)
- # Narrowing: pending work that no longer fits must leave the live queue.
- self._classify(
- self.tasks.list(
- statuses=(
- MemoryTaskStatus.PENDING,
- MemoryTaskStatus.WAITING_FOR_MODEL,
- MemoryTaskStatus.FAILED,
- )
- )
- )
- newly_eligible: list[str] = []
- for task in self.tasks.list(statuses=(MemoryTaskStatus.DEFERRED_OUTSIDE_WINDOW,)):
- record = self.evidence.get(task.input_ref)
- classified = classify(
- task.task_id,
- at=record.created_at if record else None,
- imported_at=record.imported_at if record else None,
- workspace=record.workspace if record else None,
- length=len(record.verbatim) if record else 1_000_000,
- now=now,
- extraction_window=window,
- )
- if classified is not None:
- newly_eligible.append(task.task_id)
- if newly_eligible:
- self._plan_manual_batches(newly_eligible)
- self.promote_next_manual_batch()
- return settings
-
- def _plan_manual_batches(self, task_ids: list[str]) -> None:
- self._manual_batch_remaining = list(task_ids)
- total = len(task_ids)
- self._manual_batches_planned = (
- (total + MANUAL_EXTRACT_BATCH_SIZE - 1) // MANUAL_EXTRACT_BATCH_SIZE if total else 0
- )
- self._manual_batches_promoted = 0
-
- def manual_batch_progress(self) -> tuple[int, int]:
- """`(planned, current)` for the task centre copy.
-
- `current` is the batch that has actually been handed to the queue, not
- the one that will be next: a plan of three that says "第 3 批" while
- only one has been let through would be the same overstatement the
- single 675 total was.
- """
- if self._manual_batches_planned == 0:
- return 0, 0
- return self._manual_batches_planned, min(
- self._manual_batches_promoted,
- self._manual_batches_planned,
- )
-
- def promote_next_manual_batch(
- self,
- *,
- task_ids: tuple[str, ...] | None = None,
- ) -> list[MemoryTask]:
- """Promote at most one small batch of deferred work into the queue."""
- if task_ids is not None:
- self._plan_manual_batches(list(task_ids))
- elif not self._manual_batch_remaining and self._manual_batches_planned == 0:
- # Ad-hoc "next batch" with no prior plan.
- self._manual_batches_planned = 1
- if self._manual_batch_remaining:
- take = self._manual_batch_remaining[:MANUAL_EXTRACT_BATCH_SIZE]
- self._manual_batch_remaining = self._manual_batch_remaining[MANUAL_EXTRACT_BATCH_SIZE:]
- promoted = self.tasks.promote_deferred(
- limit=len(take),
- task_ids=tuple(take),
- )
- else:
- promoted = self.tasks.promote_deferred(limit=MANUAL_EXTRACT_BATCH_SIZE)
- if promoted:
- self._manual_batches_promoted += 1
- self._schedule_tasks(self._classify(promoted, within_window=False))
- return promoted
-
- def _refill_active_window(self) -> list[QueuedWork]:
- """Refill from parked pending work without promoting old evidence."""
- work = self._prepare_active_window()
- if not work:
- self._older_waiting = False
- return work
-
- def _prepare_active_window(self) -> list[QueuedWork]:
- recovery_cutoff = datetime.now(UTC)
- occupied = tuple(
- self._queue.task_ids()
- | self._in_flight.keys()
- | set(_direct_tasks_for(self.tasks.database_path))
- )
- self.tasks.recover_orphan_running(
- exclude_task_ids=occupied,
- claimed_before=recovery_cutoff,
- )
- rows = self.tasks.active_window(
- now=datetime.now(UTC),
- fresh_window=FRESH_WINDOW,
- extraction_window=self._extraction_window(),
- exclude_task_ids=occupied,
- fresh_before=self._active_window_cursors.get(True),
- backlog_before=self._active_window_cursors.get(False),
- )
- for fresh in (True, False):
- lane = [row for row in rows if row.fresh is fresh and not row.live]
- if lane:
- last = lane[-1]
- self._active_window_cursors[fresh] = (
- last.at or last.imported_at,
- last.task.task_id,
- )
- return self._classify_active_window(rows)
-
- def _classify_active_window(self, rows: list[ActiveMemoryTask]) -> list[QueuedWork]:
- work: list[QueuedWork] = []
- for row in rows:
- task = row.task
- if not self._guard_task(task):
- continue
- self._profile_concurrent = task.profile_snapshot.max_concurrency
- self._profile_timeout = memory_task_timeout_seconds(
- task.profile_snapshot.timeout_seconds
- )
- moment = row.at or row.imported_at
- if moment is None:
- moment = datetime.min.replace(tzinfo=UTC)
- elif moment.tzinfo is None:
- moment = moment.replace(tzinfo=UTC)
- work.append(
- QueuedWork(
- task_id=task.task_id,
- at=moment,
- fresh=row.fresh,
- all_apps=row.workspace is None,
- length=row.length,
- live=row.live,
- session=row.session,
- )
- )
- return work
-
- def _extraction_window(self) -> timedelta | None:
- return extraction_window_for(self.extraction_settings.get().window_preset)
-
- def enqueue_evidence(self, record: EvidenceRecord) -> MemoryTask | None:
- if self._shutting_down:
- return None
- if self._sedimentation_stopped():
- return None
- if (
- record.role not in {"user", "assistant"}
- and record.content_kind is not EvidenceContentKind.MEMORY_CONTENT
- ):
- return None
- # Arrival only coalesces an in-memory timer. prepare_conversation checks
- # current permission off-thread before reading profiles or creating tasks.
- key = (record.user_id, record.source_id, record.conversation_id, record.workspace)
- pending = self._debounces.pop(key, None)
- if pending is not None:
- pending.cancel()
- live = live_sync_arrival.get()
- self._debounces[key] = asyncio.create_task(
- self._enqueue_after_quiet(
- record,
- key,
- datetime.now(UTC),
- live=live,
- delay=(
- _LIVE_OPEN_TURN_SETTLE_SECONDS
- if live and _opens_turn(record)
- else _TURN_SETTLE_SECONDS
- ),
- )
- )
- return None
-
- def prepare_backfill(
- self,
- should_stop: Callable[[], bool] = lambda: False,
- ) -> list[QueuedWork]:
- """Synchronous compatibility entry; preparation never starts a model."""
- if self._sedimentation_stopped():
- return []
- work = [item for batch in self._prepare_backfill_batches(should_stop) for item in batch]
- return [] if should_stop() or self._shutting_down else work
-
- def _prepare_backfill_batches(
- self,
- should_stop: Callable[[], bool] = lambda: False,
- ) -> Generator[list[QueuedWork], None, None]:
- """Read bodies as needed; yield the first task before the next conversation."""
- if should_stop() or self._shutting_down or self._sedimentation_stopped():
- return
- active = self.profiles.active(self.secrets)
- if active is None:
- self._record_idle("no_active_profile")
- return
- tasks: list[MemoryTask] = []
- first = True
- visited = 0
- seed_ids = self.evidence.list_conversation_seed_ids()
- diagnostic_event(
- level="debug",
- component="memory.scheduler",
- event="memory_scheduler.scan_inventory",
- outcome="observed",
- details={"pending_count": len(seed_ids)},
- )
- for evidence_id in seed_ids:
- if should_stop() or self._shutting_down:
- return
- self._check_backfill_context(active)
- conversation = self.evidence.list_conversation(evidence_id)
- if should_stop() or self._shutting_down:
- return
- visited += 1
- # A frozen Harness keeps imported conversations and pending jobs,
- # but preparation must not create additional processing tasks.
- if not self._source_may_write(conversation):
- continue
- chunks = self._prepare_conversation_chunks(conversation, active)
- for chunk in chunks:
- if should_stop() or self._shutting_down:
- return
- # Historical turns may be coalesced across their original
- # boundaries. Freeze that exact union so the runner cannot
- # reconstruct only the final turn from `input_ref` later.
- tasks.append(
- self._enqueue_chunk(
- chunk,
- active,
- freeze_inputs=sum(_opens_turn(record) for record in chunk) > 1,
- )
- )
- if len(tasks) >= (1 if first else _BACKFILL_BATCH_SIZE):
- self._check_backfill_context(active)
- classified = self._classify(tasks)
- yield classified
- tasks = []
- first = first and not classified
- visited = 0
- if visited >= _BACKFILL_BATCH_SIZE:
- self._check_backfill_context(active)
- yield self._classify(tasks)
- tasks = []
- visited = 0
- if not should_stop() and not self._shutting_down:
- self._check_backfill_context(active)
- if tasks:
- yield self._classify(tasks)
-
- def _check_backfill_context(self, active: ModelProfile) -> None:
- if self.profiles.active_identity() != (
- active.profile_id,
- active.revision,
- ):
- raise HyMemoryBridgeError("model_profile_changed")
-
- def backfill(self) -> None:
- self._schedule_tasks(self.prepare_backfill())
-
- async def backfill_off_thread(
- self,
- *,
- on_first_scheduled: Callable[[], None] | None = None,
- cohort_size: int | None = None,
- ) -> None:
- """Dispatch bounded preparations while later history is still being read."""
- notified = False
- started = monotonic()
- prepared_count = 0
- diagnostic_event(
- level="debug",
- component="memory.scheduler",
- event="memory_scheduler.scan_started",
- outcome="started",
- details={
- "queue_depth": len(self._queue),
- "in_flight_count": len(self._in_flight),
- },
- )
- stop = threading.Event()
- batches = self._prepare_backfill_batches(stop.is_set)
- exhausted = False
- stopped_saturated = False
- rounds = 0
- scan_error: BaseException | None = None
- try:
- while not self._shutting_down and not exhausted:
- rounds += 1
- round_started = self._backfill_clock()
- handled_batch = False
- async with self._backfill_lock:
- while not self._shutting_down:
- if (
- handled_batch
- and self._backfill_clock() - round_started
- >= self._backfill_round_budget_seconds
- ):
- break
- if (
- cohort_size is not None
- and len(self._queue) + len(self._in_flight) >= cohort_size
- ):
- # A bounded scan stops at its ceiling instead of
- # waiting for the queue to drain. Waiting here slept
- # inside the scan lock, so whoever asked for the
- # scan — a switch toggle, over HTTP — waited with
- # it, and on a saturated backlog that is not a
- # moment but the whole backlog. The caller's
- # timeout then reported a failure for work that had
- # already been accepted.
- stopped_saturated = True
- exhausted = True
- break
- if (
- handled_batch
- and self._backfill_clock() - round_started
- >= self._backfill_round_budget_seconds
- ):
- break
- work = await self._next_backfill_batch(batches, stop)
- if work is None:
- exhausted = True
- break
- handled_batch = True
- await self._schedule_tasks_off_thread(work)
- prepared_count += len(work)
- if work and on_first_scheduled is not None and not notified:
- notified = True
- on_first_scheduled()
- if not exhausted and not self._shutting_down:
- diagnostic_event(
- level="debug",
- component="memory.scheduler",
- event="memory_scheduler.scan_yielded",
- outcome="yielded",
- details={
- "attempt": rounds,
- "prepared_count": prepared_count,
- "queue_depth": len(self._queue),
- "in_flight_count": len(self._in_flight),
- },
- )
- # Release the scan owner between rounds. Realtime preparation
- # and workers already use the priority scheduler; this yield
- # lets them claim the next available resource before P2 scans on.
- await asyncio.sleep(0)
- except asyncio.CancelledError:
- raise
- except Exception as error:
- scan_error = error
- report_exception(
- "memory.scheduler",
- "memory_scheduler.scan_failed",
- error,
- context={"round": rounds},
- )
- raise
- finally:
- stop.set()
- batches.close()
- if prepared_count == 0 and not self._shutting_down:
- if stopped_saturated:
- # Parked behind a full queue, not out of work: the status
- # must not read "no_tasks" while hundreds wait.
- self._record_idle("queue_saturated")
- elif scan_error is None:
- self._record_idle("no_tasks")
- else:
- self._record_idle("scan_failed")
- elif prepared_count:
- self._diagnostic_idle_reason = None
- diagnostic_event(
- level="debug",
- component="memory.scheduler",
- event="memory_scheduler.scan_completed",
- outcome=(
- "failed"
- if scan_error is not None
- else "succeeded"
- if not self._shutting_down
- else "stopped"
- ),
- duration_ms=elapsed_ms(started),
- error_type=type(scan_error).__name__ if scan_error is not None else None,
- details={
- "prepared_count": prepared_count,
- "queue_depth": len(self._queue),
- "in_flight_count": len(self._in_flight),
- },
- )
-
- async def accept_backfill_off_thread(self) -> None:
- """Accept processing after the first scheduled batch; the rest continues."""
- if self._shutting_down:
- raise HyMemoryBridgeError("hy_memory_processing_unavailable")
- async with self._accept_backfill_lock:
- if self._shutting_down:
- raise HyMemoryBridgeError("hy_memory_processing_unavailable")
- state = self._backfill_acceptance
- running = state.task if state is not None else None
- if running is not None and not running.done() and state is not None:
- pass
- else:
- state = None
- if state is None:
- state = _BackfillAcceptance(None)
- self._backfill_acceptance = state
- state.task = asyncio.create_task(self._run_accepted_backfill(state))
- self._live_backfill = state.task
- await state.ready.wait()
- if self._shutting_down or state.task is None or state.task.cancelled():
- raise HyMemoryBridgeError("hy_memory_processing_unavailable")
- if state.error is not None:
- raise HyMemoryBridgeError(state.error)
-
- async def _prewarm_write_bridges(self, source_ids: tuple[str, ...]) -> None:
- credentials = await self._active_credentials()
- if credentials is None:
- return
- snapshot, secret = credentials
-
- if not source_ids:
- return
- bridge = self._bridge(snapshot, secret, self.data_dir)
- prewarm = getattr(bridge, "warm", None)
- if prewarm is not None:
- await prewarm()
- read_bridge = self._read_bridge(snapshot, secret, self.data_dir)
- read_prewarm = getattr(read_bridge, "warm", None)
- if read_prewarm is not None:
- await read_prewarm()
- self._read_bridges_ready.add((snapshot.profile_id, snapshot.revision))
-
- async def _run_accepted_backfill(self, state: _BackfillAcceptance) -> None:
- try:
- # Confirmation is an interactive boundary. Return acceptance now,
- # then leave a short window for the first live turn before P2
- # backfill starts occupying the same source.
- await self.service_levels.note_interactive(
- work_id="model-content-enabled",
- for_seconds=_BACKFILL_START_GRACE_SECONDS,
- )
- state.ready.set()
- await asyncio.sleep(_BACKFILL_START_GRACE_SECONDS)
- await self.backfill_off_thread()
- except asyncio.CancelledError:
- raise
- except Exception as error:
- code = str(error)
- state.error = (
- code
- if re.fullmatch(r"model_content_[a-z_]{1,80}", code)
- else "model_content_processing_unavailable"
- )
- report_exception(
- "memory.scheduler",
- "memory_scheduler.accepted_backfill_failed",
- error,
- context={},
- )
- logging.getLogger(__name__).warning("memory_backfill_failed: %s", state.error)
- finally:
- state.ready.set()
-
- def accepted_backfill_status(
- self,
- ) -> tuple[Literal["running", "done", "failed"], str | None] | None:
- state = self._backfill_acceptance
- if state is None or state.task is None:
- return None
- if state.error is not None:
- return "failed", state.error
- if state.task.cancelled():
- return "failed", "model_content_processing_interrupted"
- return ("done" if state.task.done() else "running"), None
-
- async def _next_backfill_batch(
- self, batches: Generator[list[QueuedWork], None, None], stop: threading.Event
- ) -> list[QueuedWork] | None:
- async with self.service_levels.admit(
- ServiceResource.IMPORT,
- ServiceLevel.BACKGROUND,
- work_id="memory-backfill-prepare",
- ):
- task = asyncio.create_task(in_the_background(next, batches, None))
- self._backfill_preparations.add(task)
- try:
- return await asyncio.shield(task)
- except asyncio.CancelledError:
- stop.set()
- # Executor cancellation does not stop a SQLite reader. Wait before
- # closing its generator or allowing the data-directory lock to go.
- while not task.done():
- try:
- await asyncio.shield(task)
- except asyncio.CancelledError:
- continue
- except Exception:
- break
- with suppress(asyncio.CancelledError, Exception):
- task.result()
- raise
- finally:
- self._backfill_preparations.discard(task)
-
- def prepare_resume(self) -> list[QueuedWork]:
- """Load one bounded window of unfinished tasks for the work queue."""
- active = self.profiles.active(self.secrets)
- if active is None:
- return []
- self._older_waiting = True
- self.tasks.cancel_superseded(
- profile_id=active.profile_id,
- profile_revision=active.revision,
- )
- self.tasks.cancel_superseded_policy(
- active_prefix=f"conversation:{MEMORY_INGEST_POLICY_VERSION}:"
- )
- # Past refusals recorded while a policy was stopped are cancellations,
- # not failures. Converted here, in bounded batches, so a database that
- # predates the change stops counting a switched-off feature as breakage.
- self.tasks.reclassify_policy_stopped()
- # Dead-end payloads are reaped here, where the other bounded
- # maintenance already runs, because this is the one path every start
- # and every policy change goes through. Bounded, and after the
- # reclassification above: a task that was really a cancellation only
- # becomes one once it has been converted, so reaping first would miss
- # exactly the 1759-row backlog this exists for.
- self.tasks.clear_terminal_payloads()
- self._active_window_cursors.clear()
- return self._prepare_active_window()
-
- def resume(self) -> None:
- self._schedule_tasks(self.prepare_resume())
-
- async def resume_off_thread(self) -> None:
- """`resume`, without holding the event loop for the reading."""
- preparation = asyncio.create_task(in_the_background(self.prepare_resume))
- self._dispatch_checks.add(preparation)
- try:
- work = await asyncio.shield(preparation)
- except asyncio.CancelledError:
- # Cancelling the coroutine cannot stop its SQLite worker. Drain it
- # before returning control so shutdown cannot close the database
- # while the preparation thread is still using it.
- while not preparation.done():
- try:
- await asyncio.shield(preparation)
- except asyncio.CancelledError:
- continue
- except Exception:
- break
- with suppress(asyncio.CancelledError, Exception):
- preparation.result()
- raise
- finally:
- self._dispatch_checks.discard(preparation)
- await self._schedule_tasks_off_thread(work)
-
- async def resume_allowed(self) -> None:
- """Compatibility entry: recover waiting tasks and start backfill."""
- await self.resume_off_thread()
- await self.backfill_off_thread(cohort_size=8)
-
- def _classify(
- self,
- tasks: list[MemoryTask],
- *,
- live: bool = False,
- within_window: bool = True,
- ) -> list[QueuedWork]:
- """Attach each task's time and class, one evidence read apiece.
-
- Done here rather than when the work is taken, because here is off the
- event loop: hundreds of store reads on the loop is the regression
- that stalled every host's recall for seventeen seconds.
-
- Work that falls outside the extraction window is marked deferred so
- the pending count stops pretending it is about to run.
- """
- if self._sedimentation_stopped():
- return []
- now = datetime.now(UTC)
- window = self._extraction_window() if within_window else None
- exempt_all_apps_from_window = True
- work: list[QueuedWork] = []
- deferred_count = 0
- for task in tasks:
- if task.status not in _CLAIMABLE_TASK_STATUSES:
- continue
- if task.last_error_code in {
- "hy_memory_input_exceeds_window",
- "model_content_outcome_unknown",
- }:
- continue
- # A `failed` task is retryable, but only up to a ceiling. Without
- # this a permanently broken task is re-claimed on every dispatch
- # forever, burning model calls and holding a harness slot.
- if task.status is MemoryTaskStatus.FAILED and task.attempts >= TASK_MAX_ATTEMPTS:
- continue
- if not self._guard_task(task):
- continue
- record = self.evidence.get(task.input_ref)
- classified = classify(
- task.task_id,
- at=record.created_at if record else None,
- imported_at=record.imported_at if record else None,
- workspace=record.workspace if record else None,
- length=len(record.verbatim) if record else 1_000_000,
- now=now,
- extraction_window=window,
- live=live,
- session=(record.user_id, record.source_id, record.conversation_id)
- if record
- else None,
- exempt_all_apps_from_window=exempt_all_apps_from_window,
- )
- self._profile_concurrent = task.profile_snapshot.max_concurrency
- self._profile_timeout = memory_task_timeout_seconds(
- task.profile_snapshot.timeout_seconds
- )
- if classified is None:
- self.tasks.defer_outside_window(task.task_id)
- self._older_waiting = True
- deferred_count += 1
- else:
- work.append(classified)
- if deferred_count and not work:
- self._record_idle("outside_window")
- return work
-
- def queue_depths(self) -> QueueDepths:
- """The two numbers the app shows, plus when work last landed."""
- fresh, backlog = self.tasks.pending_by_recency(fresh_since=datetime.now(UTC) - FRESH_WINDOW)
- return QueueDepths(
- fresh=fresh,
- backlog=backlog,
- recent_completions=self.tasks.recent_completion_times(),
- )
-
- def active_depths(self) -> tuple[int, int]:
- """The bounded scheduler window, separate from durable parked work."""
- return len(self._queue), len(self._in_flight)
-
- def _schedule_tasks(self, work: list[QueuedWork]) -> None:
- if self._shutting_down:
- return
- self._queue_validated_work(work)
-
- async def _schedule_tasks_off_thread(self, work: list[QueuedWork]) -> None:
- if self._shutting_down:
- return
- self._queue_validated_work(work)
-
- def _queue_validated_work(self, work: list[QueuedWork]) -> None:
- if self._shutting_down:
- return
- for item in work:
- if item.task_id in self._in_flight:
- continue
- self._queue.add(item)
- if work:
- self._diagnostic_idle_reason = None
- diagnostic_event(
- level="debug",
- component="memory.scheduler",
- event="memory_scheduler.tasks_queued",
- outcome="succeeded",
- details={
- "prepared_count": len(work),
- "queue_depth": len(self._queue),
- "in_flight_count": len(self._in_flight),
- },
- )
- self._ensure_workers()
- if self._older_waiting and not self._workers and not self._continuing_older:
- # Nothing queued means no worker will ever find the queue dry and
- # reach for deferred work, so one goes to look.
- self._start_worker()
-
- @property
- def _max_concurrent(self) -> int:
- if self._fixed_concurrent is not None:
- return self._fixed_concurrent
- return max(1, self._profile_concurrent)
-
- def _busy_sessions(self) -> set[tuple[str, str, str]]:
- return {work.session for work in self._in_flight.values() if work.session is not None}
-
- def _harness_load(self) -> dict[str, int]:
- """How much work each harness (`source_id`) has in the model now.
-
- Counted from what is actually running, so it needs no separate book
- keeping that could drift out of step with `_in_flight`.
- """
- load: dict[str, int] = {}
- for work in self._in_flight.values():
- if work.session is None:
- continue
- source = work.session[1]
- load[source] = load.get(source, 0) + 1
- return load
-
- #: How much work one harness (`source_id`) may have in the model at once.
- #:
- #: **One.** Within a harness, work runs in order. Two turns of the same
- #: harness in HY at once can each conclude without seeing the other, and HY
- #: decides whether a memory supersedes an older one from what it has
- #: already been told — so the second can overwrite a conclusion the first
- #: had not finished reaching. In HY Memory App the serialisation unit is
- #: the user, and the user is what a harness corresponds to here.
- #:
- #: Harnesses run *alongside* each other, which is where the parallelism
- #: comes from: several sources are several independent conversations and
- #: none needs to wait for another's turns.
- #:
- #: Deliberately not a configurable number and not a hardcoded "10". Ten
- #: was an observation about how many harnesses exist today, used to argue
- #: the load is small — it is not a ceiling to encode. One harness is one
- #: at a time; how many harnesses run at once falls out of how many have
- #: work and how many workers exist.
- HARNESS_SERIAL = 1
-
- @property
- def _harness_limit(self) -> int:
- """The per-harness cap: one, which is what makes a harness serial."""
- return self.HARNESS_SERIAL
-
- def _ensure_workers(self) -> None:
- if self._shutting_down or self._sedimentation_stopped():
- return
- load = self._harness_load()
- background_capacity = (
- self._max_concurrent if self._max_concurrent == 1 else self._max_concurrent - 1
- )
- while len(self._workers) < self._max_concurrent and self._queue.ready(
- self._busy_sessions(),
- load,
- self._harness_limit,
- ):
- if len(self._workers) >= background_capacity and not self._queue.live_ready(
- self._busy_sessions(),
- load,
- self._harness_limit,
- ):
- break
- self._start_worker()
-
- async def _reclaim_orphans(self) -> None:
- """Recover task rows whose owning worker disappeared without a restart."""
- while not self._shutting_down:
- await asyncio.sleep(ORPHAN_RECOVERY_INTERVAL_SECONDS)
- recovery_cutoff = datetime.now(UTC)
- occupied = tuple(
- set(self._in_flight) | set(_direct_tasks_for(self.tasks.database_path))
- )
- try:
- recovered = await in_the_background(
- self.tasks.recover_orphan_running,
- exclude_task_ids=occupied,
- claimed_before=recovery_cutoff,
- )
- except asyncio.CancelledError:
- raise
- except Exception as error:
- diagnostic_event(
- level="error",
- component="memory.scheduler",
- event="memory_scheduler.orphan_recovery_failed",
- outcome="failed",
- error_code="memory_task_orphan_recovery_failed",
- **diagnostic_exception(error),
- )
- continue
- if recovered:
- diagnostic_event(
- level="warn",
- component="memory.scheduler",
- event="memory_scheduler.orphans_recovered",
- outcome="recovered",
- details={"count": recovered},
- )
-
- def _start_worker(self) -> None:
- worker = asyncio.create_task(self._work())
- self._workers[id(worker)] = worker
- worker.add_done_callback(self._worker_finished)
-
- def _worker_finished(self, worker: asyncio.Task[None]) -> None:
- self._workers.pop(id(worker), None)
- self._ensure_workers()
-
- def start_maintenance(self) -> None:
- if self._shutting_down:
- return
- if self._orphan_reclaimer is None or self._orphan_reclaimer.done():
- self._orphan_reclaimer = asyncio.create_task(self._reclaim_orphans())
-
- async def _work(self) -> None:
- """Take the next piece of work when free, not when it arrived.
-
- The order used to be fixed by turning the whole prepared list into
- tasks at once, which is why nothing that arrived later could be
- reached until the catch-up finished.
- """
- looked_for_older = False
- while not self._shutting_down:
- if self._sedimentation_stopped():
- return
- # The harness cap is recomputed from what is running, so a worker
- # that just finished frees its harness's slot immediately.
- work = self._queue.take(
- self._busy_sessions(),
- self._harness_load(),
- self._harness_limit,
- )
- if work is None:
- if looked_for_older or self._continuing_older or not self._older_waiting:
- return
- looked_for_older = True
- self._continuing_older = True
- try:
- older = await in_the_background(self._refill_active_window)
- except Exception:
- return
- finally:
- self._continuing_older = False
- # Look at the queue again either way: work that arrived during
- # the lookup found this worker busy and started no other.
- self._queue_validated_work(older)
- continue
- looked_for_older = False
- self._in_flight[work.task_id] = work
- _mark_direct_task(self.tasks.database_path, work.task_id)
- try:
- task = await in_the_background(self.tasks.require, work.task_id)
- if task.status not in _CLAIMABLE_TASK_STATUSES or (
- task.status is MemoryTaskStatus.FAILED and task.attempts >= TASK_MAX_ATTEMPTS
- ):
- continue
- if not await in_the_background(self._guard_task, task):
- continue
- runner = self.runner_factory()
- # A wall-clock ceiling, because a harness is serial: a task
- # that hangs holds the only slot its harness has, and every
- # later turn of that harness waits behind it. The runner owns
- # the task's lease, so the budget is handed to it rather than
- # enforced here — it raises `hy_memory_timeout`, which its own
- # classification turns into `wait_for_model` (a retry) rather
- # than a terminal failure.
- level = ServiceLevel.REALTIME if work.live else ServiceLevel.BACKGROUND
- scope_key = work.session[1] if work.session is not None else None
- source_ids = () if scope_key is None else (scope_key,)
- async with (
- self._source_processing_lock(source_ids, level=level),
- self.service_levels.admit(
- ServiceResource.MODEL,
- level,
- work_id=work.task_id,
- scope_key=scope_key,
- ),
- ):
-
- async def require_sedimentation() -> None:
- if self._sedimentation_stopped():
- raise HyMemoryBridgeError("model_sedimentation_disabled")
-
- finished = await runner.run(
- work.task_id,
- timeout=self._profile_timeout,
- before_hy_invocation=require_sedimentation,
- )
- if finished.status is MemoryTaskStatus.COMPLETED:
- self._request_read_bridge_refresh(finished.profile_snapshot)
- elif (
- finished.status is MemoryTaskStatus.CANCELLED
- and finished.last_error_code == "model_content_continuous_binding_invalid"
- ):
- # The policy or Evidence changed after scheduling but before
- # HY was called. Retire that stale binding and immediately
- # build a replacement from the latest conversation instead
- # of leaving a permanent failed row until a later scan.
- await self._replace_stale_binding(finished)
- except asyncio.CancelledError:
- raise
- except (HyMemoryBridgeError, MemoryTaskOwnershipError):
- # Classified by the runner, which has already logged it and
- # either settled the task (a timeout goes back to `pending`)
- # or lost it to whoever owns it now. Overriding that here
- # would turn a retry into a terminal failure.
- continue
- except Exception as error:
- await self._record_dispatch_failure(work.task_id, error)
- continue
- finally:
- # Releases the harness's slot either way, so a task that timed
- # out cannot starve the turns waiting behind it.
- self._in_flight.pop(work.task_id, None)
- _unmark_direct_task(self.tasks.database_path, work.task_id)
-
- async def _replace_stale_binding(self, task: MemoryTask) -> None:
- latest = await in_the_background(self.evidence.get, task.input_ref)
- if latest is not None:
- await self.enqueue_conversation_off_thread(latest)
-
- async def _record_dispatch_failure(self, task_id: str, error: Exception) -> None:
- """Make a failure nobody classified visible, and take the task off the board.
-
- Whatever raised it — the call to the runner itself, or the runner
- crashing between claim and finish — left the task `pending` or
- `running`, where it reads as work in progress that never ends. The
- worker keeps going either way: one bad task must not stop the rest.
- """
- diagnostic_event(
- level="error",
- component="memory.scheduler",
- event="memory_scheduler.dispatch_failed",
- outcome="failed",
- task_id=task_id,
- error_code="memory_task_dispatch_failed",
- **diagnostic_exception(error),
- )
- try:
- await in_the_background(
- self.tasks.fail_unsettled,
- task_id,
- error_code="memory_task_dispatch_failed",
- )
- except Exception as settle_error:
- if isinstance(settle_error, sqlite3.Error):
- record_database_error("memory.scheduler", settle_error)
- diagnostic_event(
- level="error",
- component="memory.scheduler",
- event="memory_scheduler.dispatch_failure_unrecorded",
- outcome="failed",
- task_id=task_id,
- **diagnostic_exception(settle_error),
- )
-
- async def shutdown(self) -> None:
- self._shutting_down = True
- if self._shutdown_task is None:
- self._shutdown_task = asyncio.create_task(self._finish_shutdown())
- try:
- await asyncio.shield(self._shutdown_task)
- except asyncio.CancelledError:
- # A cancelled lifespan/request must not cancel the executor wrappers
- # before their actual preparation threads finish.
- while not self._shutdown_task.done():
- try:
- await asyncio.shield(self._shutdown_task)
- except asyncio.CancelledError:
- continue
- except Exception:
- break
- with suppress(asyncio.CancelledError, Exception):
- self._shutdown_task.result()
- raise
-
- async def _finish_shutdown(self) -> None:
- reclaimer = self._orphan_reclaimer
- if reclaimer is not None and not reclaimer.done():
- reclaimer.cancel()
- workers = tuple(self._workers.values())
- debounces = tuple(self._debounces.values())
- for task in debounces:
- if not task.done():
- task.cancel()
- for task in workers:
- if not task.done():
- task.cancel()
- await asyncio.gather(
- *(() if reclaimer is None else (reclaimer,)),
- *debounces,
- *workers,
- return_exceptions=True,
- )
- # A thread already preparing durable tasks cannot be cancelled safely.
- # Let it finish; _schedule_tasks rejects work after shutdown starts.
- live = self._live_backfill
- if live is not None and not live.done():
- live.cancel()
- await asyncio.gather(
- *tuple(self._preparations.values()),
- *tuple(self._backfill_preparations),
- *tuple(self._dispatch_checks),
- *(() if live is None else (live,)),
- return_exceptions=True,
- )
- refreshes = tuple(self._read_bridge_refresh_tasks.values())
- for task in refreshes:
- if not task.done():
- task.cancel()
- await asyncio.gather(*refreshes, return_exceptions=True)
- self._preparations.clear()
- self._debounces.clear()
- self._workers.clear()
- self._orphan_reclaimer = None
- self._in_flight.clear()
- self._active_window_cursors.clear()
- self._queue.clear()
- await asyncio.gather(
- *(bridge.close() for bridge in (*self._bridges.values(), *self._read_bridges.values())),
- return_exceptions=True,
- )
- self._bridges.clear()
- self._read_bridges.clear()
- self._read_bridges_ready.clear()
- self._read_bridge_generations.clear()
- self._read_bridge_refresh_tasks.clear()
-
- async def _active_credentials(self) -> tuple[ModelProfileSnapshot, str | None] | None:
- def read() -> tuple[ModelProfileSnapshot, str | None] | None:
- identity = self.profiles.active_identity()
- if identity is None:
- return None
- snapshot = self.profiles.snapshot(*identity)
- # active() probes has(), which resolves the same secret a second time.
- # Read once per call, then reject a profile changed during the OS read.
- secret = self.profiles.resolve_snapshot_secret(
- *identity,
- self.secrets,
- )
- if self.profiles.active_identity() != identity:
- raise HyMemoryBridgeError("model_profile_changed")
- if snapshot.has_api_key and secret is None:
- raise HyMemoryBridgeError("model_secret_unavailable")
- return snapshot, secret
-
- try:
- return await in_the_background(read)
- except SecretStoreUnavailableError:
- raise HyMemoryBridgeError("secure_storage_unavailable") from None
-
- async def digest(self) -> dict[str, object]:
- async with _digest_mutex():
- return await self._digest_locked()
-
- async def _digest_locked(self) -> dict[str, object]:
- credentials = await self._active_credentials()
- if credentials is None:
- raise HyMemoryBridgeError("model_profile_not_active")
- snapshot, secret = credentials
- bridge = self._bridge(snapshot, secret, self.data_dir)
- if self.sdk_authority():
- agent_ids = await bridge.list_agent_ids(user_id="local")
- sdk_digests = [
- {
- "agent_id": agent_id,
- "schemas_recorded": 0,
- **dict(
- await bridge.digest(
- user_id="local",
- agent_id=agent_id,
- )
- ),
- }
- for agent_id in agent_ids
- ]
- return {
- "success": all(result.get("success") is not False for result in sdk_digests),
- "scope_count": len(sdk_digests),
- "skipped_conversation_scopes": 0,
- "schemas_recorded": 0,
- "digests": sdk_digests,
- }
- derivation = await in_the_background(self.governance.hy_derivation)
- agent_ids, skipped_conversation_scopes = await self._digest_scopes(bridge)
- evidence_by_scope = self._digest_evidence()
- digests: list[dict[str, object]] = []
- recorded = 0
- # A digest reads the memory it is about to summarise and writes the
- # summary. Two of them running at once — yesterday's harness and
- # today's, say — each see a state the other is mid-way through
- # changing, and each concludes from it. The result is two summaries of
- # two different half-updated memories, neither of them right.
- #
- # So digests are serialised across every harness, while ordinary work
- # between them still runs alongside. This is the time lock: it costs a
- # wait only when two digests would otherwise overlap.
- for agent_id in agent_ids:
- result = dict(
- await bridge.digest(
- user_id="local",
- agent_id=agent_id,
- )
- )
- kept = await self._record_schemas(
- bridge,
- agent_id=agent_id,
- derivation=derivation.citing(evidence_by_scope.get(agent_id, ())),
- )
- recorded += kept
- digests.append({"agent_id": agent_id, "schemas_recorded": kept, **result})
- return {
- "success": all(result.get("success") is not False for result in digests),
- "scope_count": len(digests),
- "skipped_conversation_scopes": skipped_conversation_scopes,
- "schemas_recorded": recorded,
- "digests": digests,
- }
-
- async def _record_schemas(
- self,
- bridge: MemoryBridgeProtocol,
- *,
- agent_id: str,
- derivation: HyDerivation,
- ) -> int:
- """Bring System 2's mental models back from the graph into governance.
-
- `digest()` used to compute these and hand them to whoever called the
- endpoint, writing none of them down — so the one layer HY calls a
- profile alongside basic info existed only in Kuzu. Five of them sat
- there on this machine, matching nothing in governance.
-
- Both halves of that profile come back, not just the schemas. The fix
- above kept only `L6_SCHEMA` and left basic info where it had been:
- in the graph. The snapshot query filters no layer, so those nodes were
- already being read and then dropped one line later — and basic info is
- the half that answers "who is this person", which is the whole point
- of inducing a profile at all.
-
- They are scoped to every app rather than to the project they were
- induced in: a schema says how the person works, not what one codebase
- contains. A scope with no local evidence left is skipped, because a
- memory we cannot say why we believe does not belong in governance.
- Nor does one induced from evidence the person overruled while the
- digest ran; the next digest induces again from what is left.
- """
- evidence_ids = derivation.evidence_ids
- if not evidence_ids:
- return 0
- try:
- snapshot = await bridge.graph_snapshot(user_id="local", agent_id=agent_id)
- except HyMemoryBridgeError:
- # A digest that ran is still worth reporting; the schemas it wrote
- # will be picked up by the next one.
- return 0
- recorded = 0
- for node in snapshot.nodes:
- if not _is_profile_layer(node.layer):
- continue
- content = sanitize_model_input(node.content)
- if not content.strip():
- continue
- if self.governance.get(node.node_id, user_id="local") is not None:
- continue
- try:
- self.governance.write_from_hy(
- HyCreate(
- draft=MemoryDraft(
- user_id="local",
- kind=_memory_kind(node.layer),
- content=content,
- scopes=("all-apps",),
- evidence_ids=evidence_ids,
- ),
- request_id=f"digest:{agent_id}:{node.node_id}",
- memory_id=node.node_id,
- ),
- user_id="local",
- derivation=derivation,
- )
- except MemoryEvidenceOverriddenError:
- continue
- recorded += 1
- return recorded
-
- def _digest_evidence(self) -> dict[str, tuple[str, ...]]:
- """Which evidence each HY scope's confirmed memories rest on.
-
- A schema is induced from a whole scope rather than from one exchange,
- so what it cites is everything that scope was built from.
- """
- collected: dict[str, set[str]] = {}
- offset = 0
- while True:
- memories = self.governance.list(
- user_id="local",
- status=MemoryStatus.CONFIRMED,
- limit=500,
- offset=offset,
- )
- for memory in memories:
- records = tuple(
- record
- for evidence_id in memory.evidence_ids
- if (record := self.evidence.get(evidence_id)) is not None
- )
- if not records:
- continue
- collected.setdefault(_hy_agent_id(records), set()).update(
- record.evidence_id for record in records
- )
- if len(memories) < 500:
- break
- offset += len(memories)
- # Capped at what a draft accepts; the cite is a sample of a scope this
- # large either way, and an oversized one would be refused outright.
- return {
- agent_id: tuple(sorted(evidence_ids))[:10_000]
- for agent_id, evidence_ids in collected.items()
- }
-
- async def _digest_scopes(self, bridge: MemoryBridgeProtocol) -> tuple[tuple[str, ...], int]:
- """Pick the HY scopes worth running System 2 over.
-
- HY is the source of truth for which scopes exist, so memories written
- under an earlier routing policy are still reachable. Evidence-derived
- scopes are only a fallback for when HY cannot be listed.
- """
- stable, skipped = await in_the_background(self._digest_targets)
- try:
- stored = await bridge.list_agent_ids(user_id="local")
- except HyMemoryBridgeError:
- return stable, skipped
- if not stored:
- return stable, skipped
- return tuple(sorted({*stable, *stored})), skipped
-
- def _digest_targets(self) -> tuple[tuple[str, ...], int]:
- """Return stable HY scopes with confirmed memories.
-
- Workspace and imported-memory scopes are stable enough for System 2.
- Unattributed raw conversations intentionally remain quarantined per
- conversation; digesting each one would be expensive and cannot produce
- meaningful cross-conversation relations.
- """
- targets: set[str] = set()
- skipped: set[str] = set()
- offset = 0
- while True:
- memories = self.governance.list(
- user_id="local",
- status=MemoryStatus.CONFIRMED,
- limit=500,
- offset=offset,
- )
- for memory in memories:
- records = tuple(
- record
- for evidence_id in memory.evidence_ids
- if (record := self.evidence.get(evidence_id)) is not None
- )
- if not records:
- continue
- if not self._source_may_write(list(records)):
- # A revoked source is not a memory source any more: it
- # cannot be read for a new task and must not be handed
- # back to System 2 through digest either.
- continue
- if any(record.workspace is not None for record in records) or all(
- record.content_kind is EvidenceContentKind.MEMORY_CONTENT for record in records
- ):
- targets.add(_hy_agent_id(records))
- else:
- skipped.add(_hy_agent_id(records))
- if len(memories) < 500:
- break
- offset += len(memories)
- return tuple(sorted(targets)), len(skipped)
-
- async def graph_snapshot(self, *, limit: int = 300) -> HyGraphSnapshot:
- credentials = await self._active_credentials()
- if credentials is None:
- # Not "HY found no relations" but "HY was never asked"; the map has
- # to be able to tell the reader which one it is looking at.
- return HyGraphSnapshot(consulted=False)
- snapshot, secret = credentials
- bridge = self._bridge(snapshot, secret, self.data_dir)
- return await bridge.graph_snapshot(
- user_id="local",
- agent_id="*",
- limit=limit,
- )
-
- async def update_hy_memory(self, memory_id: str, content: str) -> dict[str, object]:
- credentials = await self._active_credentials()
- if credentials is None:
- raise HyMemoryBridgeError("model_profile_not_active")
- snapshot, secret = credentials
- bridge = self._bridge(snapshot, secret, self.data_dir)
- return await bridge.update(memory_id, content)
-
- async def delete_hy_memory(self, memory_id: str) -> dict[str, object]:
- credentials = await self._active_credentials()
- if credentials is None:
- raise HyMemoryBridgeError("model_profile_not_active")
- snapshot, secret = credentials
- bridge = self._bridge(snapshot, secret, self.data_dir)
- return await bridge.delete(memory_id)
-
- async def finish_deletion(self, memory_id: str) -> None:
- """Tell HY to forget this deleted memory now, unless someone else already is."""
- for claim in self.governance.claim_deletions(user_id="local", memory_id=memory_id):
- await self._work_deletion(claim)
-
- async def finish_deletions(self) -> None:
- """One round: the deletions that are due, at most a batch of them."""
- for claim in self.governance.claim_deletions(user_id="local"):
- await self._work_deletion(claim)
-
- async def _work_deletion(self, claim: DeletionClaim) -> None:
- """Tell HY to forget a deleted memory, recording whether that landed.
-
- A failure stays on record as failed, with when it is next due; a
- memory HY no longer holds counts as forgotten.
- """
- try:
- await self.delete_hy_memory(claim.memory_id)
- except HyMemoryBridgeError as error:
- self.governance.settle_deletion(claim, user_id="local", error_code=str(error))
- except Exception as error:
- # Recorded like any other failure, so it waits its turn instead of
- # being due again at once, and the sync that called this lives on.
- logging.getLogger(__name__).warning(
- "memory_deletion_unexpected_failure: %s", type(error).__name__
- )
- self.governance.settle_deletion(
- claim, user_id="local", error_code="hy_memory_delete_unexpected"
- )
- else:
- self.governance.settle_deletion(claim, user_id="local", error_code=None)
-
- def wake_deletions(self) -> None:
- """Have the deletion sync look again now rather than when it next would."""
- self._deletions_due.set()
-
- async def keep_deletions_in_sync(self) -> None:
- """Runs for as long as Core does, taking each deletion when it falls due.
-
- A deletion HY did not take has no other moment to be retried: the
- memory is already deleted, so no request will come for it.
- """
- while True:
- try:
- await self.finish_deletions()
- due = self.governance.next_deletion_due(user_id="local")
- except Exception as error:
- _report_deletion_sync_failure(error)
- due = None
- wait = DELETION_SYNC_IDLE_SECONDS
- if due is not None:
- wait = min(wait, max(0.0, (due - self.governance.clock()).total_seconds()))
- await self._wait_for_deletions(wait)
-
- async def _wait_for_deletions(self, timeout: float) -> None:
- with suppress(TimeoutError):
- await asyncio.wait_for(self._deletions_due.wait(), timeout=timeout)
- self._deletions_due.clear()
-
- async def graph_width_mismatch(self) -> GraphWidthMismatch | None:
- """What the app shows before extraction starts failing on it.
-
- Read off the active profile rather than off a live bridge: the whole
- point is that the bridge cannot be built while the widths disagree.
- """
- credentials = await self._active_credentials()
- if credentials is None:
- return None
- snapshot, secret = credentials
- return await in_the_background(
- inspect_profile_graph_width,
- snapshot,
- api_key=secret,
- data_dir=self.data_dir,
- )
-
- async def decide_graph_width(self, decision: GraphWidthDecision) -> GraphWidthOutcome:
- """Carry out the choice, then drop any bridge built on the old answer."""
- credentials = await self._active_credentials()
- if credentials is None:
- raise HyMemoryBridgeError("model_profile_not_active")
- snapshot, secret = credentials
- outcome = await in_the_background(
- decide_profile_graph_width,
- snapshot,
- api_key=secret,
- data_dir=self.data_dir,
- decision=decision,
- )
- if outcome.archived_path is not None:
- for key in tuple(self._bridges):
- if key[:2] == (snapshot.profile_id, snapshot.revision):
- self._bridges.pop(key, None)
- self._read_bridges.pop((snapshot.profile_id, snapshot.revision), None)
- self._read_bridges_ready.discard((snapshot.profile_id, snapshot.revision))
- self._read_bridge_generations.pop((snapshot.profile_id, snapshot.revision), None)
- refresh = self._read_bridge_refresh_tasks.pop(
- (snapshot.profile_id, snapshot.revision), None
- )
- if refresh is not None and not refresh.done():
- refresh.cancel()
- return outcome
-
- async def semantic_search(
- self, query: str, *, limit: int = 12
- ) -> tuple[tuple[str, float], ...]:
- return tuple(
- (hit.memory_id, hit.score) for hit in await self.semantic_recall(query, limit=limit)
- )
-
- async def semantic_recall(
- self, query: str, *, limit: int = 12
- ) -> tuple[SemanticMemoryHit, ...]:
- credentials = await self._active_credentials()
- if credentials is None:
- return await self._search_with_builtin_embedding(query, limit=limit)
- snapshot, secret = credentials
- key = (snapshot.profile_id, snapshot.revision)
- bridge = self._read_bridges.get(key)
- if bridge is None or key not in self._read_bridges_ready:
- return ()
- return await self._semantic_bridge_hits(bridge, query, limit=limit)
-
- @staticmethod
- async def _semantic_bridge_hits(
- bridge: MemoryBridgeProtocol,
- query: str,
- *,
- limit: int,
- ) -> tuple[SemanticMemoryHit, ...]:
- search_memories = getattr(bridge, "search_memories", None)
- if callable(search_memories):
- found = await search_memories(
- query,
- user_id="local",
- agent_id="*",
- limit=limit,
- )
- else:
- found = await bridge.search_scores(
- query,
- user_id="local",
- agent_id="*",
- limit=limit,
- )
- normalized = normalize_semantic_hits(found)
- if normalized is None:
- raise HyMemoryBridgeError("hy_memory_search_shape_unknown")
- return normalized[:limit]
-
- async def _search_with_builtin_embedding(
- self,
- query: str,
- *,
- limit: int,
- ) -> tuple[SemanticMemoryHit, ...]:
- """Read a store whose profile is gone, using the encoder that filled it.
-
- Retiring a profile does not retire the memories it produced, and the
- embedding those vectors were written with is built in, so there is
- nothing here that needs a generation model.
-
- Bounded by a store that already exists, on purpose: building the
- client is what creates one, and the width it would create is the
- built-in encoder's. A user who has not chosen a model yet would then
- meet a width mismatch on their first wider profile, invented by a
- search they ran while waiting.
- """
- if not hy_memory_store_exists(self.data_dir):
- return ()
- bridge = self._read_bridge(builtin_retrieval_snapshot(), None, self.data_dir)
- try:
- return await self._semantic_bridge_hits(bridge, query, limit=limit)
- except GraphWidthMismatchError:
- # Written by a wider embedding than the built-in one, so it
- # cannot be read from here. The app already asks the user what to
- # do about that; answering it as a search failure would move the
- # decision somewhere they cannot act on it.
- return ()
-
- def _create_runner(self) -> MemoryTaskRunner:
- return MemoryTaskRunner(
- tasks=self.tasks,
- profiles=self.profiles,
- secrets=self.secrets,
- evidence=self.evidence,
- governance=self.governance,
- data_dir=self.data_dir,
- bridge_factory=self._bridge,
- close_bridge=False,
- sdk_authority=self.sdk_authority,
- )
-
- def _bridge(
- self,
- profile: ModelProfileSnapshot,
- secret: str | None,
- data_dir: Path,
- *,
- scope_key: str | None = None,
- ) -> MemoryBridgeProtocol:
- """One bridge per profile revision and write harness.
-
- It built `HyMemoryBridge` directly until R-27, which left the cascades
- that reach HY through here — deletion, and now correction — with no
- seam to stand in for HY. The cache is the reason to keep the method:
- the bridge owns a client and an embedding model, so asking for one per
- call would pay for that per call.
- """
- key = (profile.profile_id, profile.revision, scope_key)
- bridge = self._bridges.get(key)
- if bridge is None:
- bridge = self.bridge_factory(profile, secret, data_dir)
- self._bridges[key] = bridge
- return bridge
-
- def _read_bridge(
- self,
- profile: ModelProfileSnapshot,
- secret: str | None,
- data_dir: Path,
- ) -> MemoryBridgeProtocol:
- """One read-only client per profile revision, isolated from write locks."""
- key = (profile.profile_id, profile.revision)
- bridge = self._read_bridges.get(key)
- if bridge is None:
- bridge = self.bridge_factory(profile, secret, data_dir)
- self._read_bridges[key] = bridge
- return bridge
-
- async def _refresh_read_bridge(self, snapshot: ModelProfileSnapshot) -> None:
- """Publish a fresh HY read client after a successful vector write.
-
- Chroma clients opened before another client writes do not reliably
- observe the new vector collection. Warm the replacement first, then
- swap it into the recall path so queries never see an unready bridge.
- """
- key = (snapshot.profile_id, snapshot.revision)
- async with self._read_bridge_refresh_lock:
- if self._shutting_down:
- return
- replacement: MemoryBridgeProtocol | None = None
- try:
- secret = await in_the_background(
- self.profiles.resolve_snapshot_secret,
- snapshot.profile_id,
- snapshot.revision,
- self.secrets,
- )
- if snapshot.has_api_key and secret is None:
- raise HyMemoryBridgeError("model_secret_unavailable")
- replacement = self.bridge_factory(snapshot, secret, self.data_dir)
- warm = getattr(replacement, "warm", None)
- if warm is not None:
- await warm()
- except Exception as error:
- if replacement is not None:
- with suppress(Exception):
- await replacement.close()
- diagnostic_event(
- level="warn",
- component="memory.semantic",
- event="semantic_read_bridge.refresh_failed",
- outcome="degraded",
- error_code="semantic_read_bridge_refresh_failed",
- details={
- "generation": self._read_bridge_generations.get(key, 0),
- },
- **diagnostic_exception(error),
- )
- return
-
- assert replacement is not None
- previous = self._read_bridges.get(key)
- generation = self._read_bridge_generations.get(key, 0) + 1
- self._read_bridges[key] = replacement
- self._read_bridges_ready.add(key)
- self._read_bridge_generations[key] = generation
- diagnostic_event(
- level="debug",
- component="memory.semantic",
- event="semantic_read_bridge.refreshed",
- outcome="succeeded",
- details={
- "generation": generation,
- },
- )
- if previous is not None and previous is not replacement:
- await previous.close()
-
- def _request_read_bridge_refresh(self, snapshot: ModelProfileSnapshot) -> None:
- """Refresh once after the first write creates the vector collection."""
- if self._shutting_down:
- return
- key = (snapshot.profile_id, snapshot.revision)
- if self._read_bridge_generations.get(key, 0) >= 1:
- return
- current = self._read_bridge_refresh_tasks.get(key)
- if current is not None and not current.done():
- return
- task = asyncio.create_task(self._refresh_read_bridge_after_first_write(snapshot))
- self._read_bridge_refresh_tasks[key] = task
-
- def finish_refresh(
- finished: asyncio.Task[None], refresh_key: tuple[str, int] = key
- ) -> None:
- self._finish_read_refresh(refresh_key, finished)
-
- task.add_done_callback(finish_refresh)
-
- async def _refresh_read_bridge_after_first_write(self, snapshot: ModelProfileSnapshot) -> None:
- await asyncio.sleep(_READ_BRIDGE_FIRST_REFRESH_DELAY_SECONDS)
- await self._refresh_read_bridge(snapshot)
-
- def _finish_read_refresh(
- self,
- key: tuple[str, int],
- task: asyncio.Task[None],
- ) -> None:
- if self._read_bridge_refresh_tasks.get(key) is task:
- self._read_bridge_refresh_tasks.pop(key, None)
- if not task.cancelled():
- task.exception()
-
- def enqueue_conversation(self, seed: EvidenceRecord) -> list[MemoryTask]:
- created, work = self._prepare_conversation_work(seed)
- self._schedule_tasks(work)
- return created
-
- async def enqueue_conversation_off_thread(self, seed: EvidenceRecord) -> list[MemoryTask]:
- """`enqueue_conversation`, without holding the loop for the reading.
-
- Split the same way as the catch-up above, and for the same reason: the
- reading wants a thread and only the scheduling needs the loop. Live
- sync arrives here for every conversation that changes, and rebuilding
- one is seconds for a long one — the watchdog caught this path holding
- the loop 2.1s, which is 2.1s of no host getting an answer.
- """
- created, work = await in_the_background(self._prepare_conversation_work, seed)
- await self._schedule_tasks_off_thread(work)
- return created
-
- def _prepare_conversation_work(
- self,
- seed: EvidenceRecord,
- *,
- arrival_at: datetime | None = None,
- live: bool = False,
- ) -> tuple[list[MemoryTask], list[QueuedWork]]:
- """Record one conversation's tasks and classify them, off the loop."""
- created = self.prepare_conversation(seed, arrival_at=arrival_at, live=live)
- return created, self._classify(created, live=live)
-
- def prepare_conversation(
- self,
- seed: EvidenceRecord,
- *,
- arrival_at: datetime | None = None,
- live: bool = False,
- ) -> list[MemoryTask]:
- """Record the tasks for one conversation, without scheduling them.
-
- Nothing here touches asyncio, and each store call opens its own
- connection, so a worker thread is safe.
- """
- active = self.profiles.active(self.secrets)
- if active is None:
- return []
- conversation = self.evidence.list_conversation(seed.evidence_id)
- if not self._source_may_write(conversation):
- return []
- # D98: a conversation whose only questions came from a sub agent used
- # to be dropped whole. Its turns are ordinary user-assistant data, so
- # the only reason to skip now is having nothing to send at all.
- if not any(
- item.role == "user" or item.content_kind is EvidenceContentKind.MEMORY_CONTENT
- for item in conversation
- ):
- return []
- # A realtime turn that is still open must not become a task, whichever
- # path gets here first. The debounce is the record of "this arrival is
- # still waiting for its reply"; without this check a periodic scan
- # could prepare the half turn before the closing event arrives, which
- # is exactly what the complete-turn rule forbids.
- if live and self._open_arrival_pending(seed, conversation):
- return []
- chunks = self._prepare_conversation_chunks(conversation, active)
- admitted = self._admitted_chunks(chunks, active)
- return [done or self._enqueue_chunk(chunk, active) for chunk, done in admitted]
-
- def _open_arrival_pending(
- self, seed: EvidenceRecord, conversation: list[EvidenceRecord]
- ) -> bool:
- """Whether this conversation has a live arrival still waiting to close."""
- key = (seed.user_id, seed.source_id, seed.conversation_id, seed.workspace)
- pending = self._debounces.get(key)
- if pending is None or pending.done():
- return False
- tail = [record for record in conversation if _is_hy_turn_record(record)]
- if not tail:
- return False
- last = tail[-1]
- return bool(last.role == "user" and _opens_turn(last))
-
- def _admitted_chunks(
- self,
- chunks: list[tuple[EvidenceRecord, ...]],
- profile: ModelProfile,
- ) -> list[tuple[tuple[EvidenceRecord, ...], MemoryTask | None]]:
- """Each chunk still to be sent, with the completed task that already holds it, if any.
-
- A finished turn is not previewed again. An unfinished one resting on
- evidence the person overruled stays held back by that evidence, alone:
- a deletion must not stop the turns that come after it.
- """
- admitted: list[tuple[tuple[EvidenceRecord, ...], MemoryTask | None]] = []
- for chunk in chunks:
- done = self._finished_chunk_task(chunk)
- admitted.append((chunk, done))
- return admitted
-
- def _not_yet_queued(
- self, chunks: list[tuple[EvidenceRecord, ...]], profile: ModelProfile
- ) -> list[tuple[EvidenceRecord, ...]]:
- """Drop turns an earlier ingest policy already extracted.
-
- Changing how a conversation is cut must not send its history to HY a
- second time. Tool records alone do not reopen a turn that was sent
- before tool calls were imported.
- """
- if not chunks:
- return chunks
- queued = {
- ref["evidence_id"]: ref
- for ref in self.tasks.completed_inputs_before(
- chunks[0][0],
- active_prefix=f"conversation:{MEMORY_INGEST_POLICY_VERSION}:",
- profile_id=profile.profile_id,
- profile_revision=profile.revision,
- )
- }
- if not queued:
- return chunks
-
- def sent(record: EvidenceRecord) -> bool:
- ref = queued.get(record.evidence_id)
- return ref is not None and matches_evidence_ref(record, ref)
-
- return [
- chunk
- for chunk in chunks
- if not all(sent(r) for r in ([r for r in chunk if r.role != "tool"] or chunk))
- ]
-
- def _prepare_conversation_chunks(
- self,
- conversation: list[EvidenceRecord],
- profile: ModelProfile,
- *,
- merge_history: bool = False,
- ) -> list[tuple[EvidenceRecord, ...]]:
- try:
- chunks = self._not_yet_queued(
- _conversation_chunks(conversation, completed_only=True), profile
- )
- return _merge_historical_chunks(chunks) if merge_history else chunks
- except ValueError as error:
- if str(error) != "hy_memory_input_exceeds_window":
- raise
- records = tuple(record for record in conversation if _is_hy_turn_record(record))
- if self._shutting_down or not records:
- return []
- self._check_backfill_context(profile)
- # Keep a full, immutable failure snapshot. Appended originals remain
- # unprocessed while the same blocker persists; they are never marked done.
- identity = sha256(
- json.dumps([evidence_ref(record) for record in records], sort_keys=True).encode()
- ).hexdigest()
- seed = records[0]
- group = sha256(
- json.dumps(
- {
- "policy": MEMORY_INGEST_POLICY_VERSION,
- "profile": (profile.profile_id, profile.revision),
- "conversation": (
- seed.user_id,
- seed.source_id,
- seed.conversation_id,
- seed.workspace,
- seed.project,
- ),
- "blockers": [
- evidence_ref(record) for record in records if len(record.verbatim) > 12_000
- ],
- },
- sort_keys=True,
- ).encode()
- ).hexdigest()
- self.tasks.create(
- request_id=f"oversized:{group}:{identity}",
- user_id=records[0].user_id,
- kind=MemoryTaskKind.EXTRACT,
- input_ref=records[0].evidence_id,
- profile=profile,
- input_records=records,
- preparation_error="hy_memory_input_exceeds_window",
- preparation_group=group,
- )
- return []
-
- def _original_records(self, records: tuple[EvidenceRecord, ...]) -> tuple[EvidenceRecord, ...]:
- originals: dict[str, EvidenceRecord] = {}
- for record in records:
- current = self.evidence.get(record.evidence_id)
- if current is None:
- raise HyMemoryBridgeError("hy_memory_evidence_changed")
- originals.setdefault(current.evidence_id, current)
- return tuple(originals.values())
-
- def _guard_task(self, task: MemoryTask) -> bool:
- if task.last_error_code in {
- "hy_memory_input_exceeds_window",
- "model_content_outcome_unknown",
- }:
- return False
- if self.tasks.profile_stop_reason(task.profile_id, task.profile_revision) is not None:
- return False
- if self.source_writes_permitted is not None:
- record = self.evidence.get(task.input_ref)
- if record is None or not self.source_writes_permitted(record.source_id):
- # Freeze: the durable row stays pending. Reopening the Harness
- # causes the ordinary resume pass to classify it again.
- return False
- return True
-
- def _source_may_write(self, conversation: list[EvidenceRecord]) -> bool:
- """Whether this conversation's source is allowed to become memories."""
- if self.source_writes_permitted is None:
- return True
- return all(self.source_writes_permitted(record.source_id) for record in conversation)
-
- def _finished_chunk_task(
- self,
- chunk: tuple[EvidenceRecord, ...],
- ) -> MemoryTask | None:
- """Task identity already deduplicates completed chunks."""
- del chunk
- return None
-
- def _enqueue_chunk(
- self,
- chunk: tuple[EvidenceRecord, ...],
- profile: ModelProfile,
- *,
- freeze_inputs: bool = False,
- ) -> MemoryTask:
- if any("segment_hash" in evidence_ref(record) for record in chunk):
- freeze_inputs = True
- source = chunk[0]
- input_ref = _chunk_input_ref(chunk)
- finished = self._finished_chunk_task(chunk)
- if finished is not None:
- return finished
- digest = sha256(
- "|".join(
- (
- MEMORY_INGEST_POLICY_VERSION,
- *(("frozen-v1",) if freeze_inputs else ()),
- f"{profile.profile_id}:{profile.revision}",
- *(
- ":".join(
- (
- item.evidence_id,
- str(item.revision),
- item.workspace or "",
- item.project or "",
- str(evidence_ref(item).get("segment_index", "")),
- str(evidence_ref(item).get("segment_hash", "")),
- )
- )
- for item in chunk
- ),
- )
- ).encode()
- ).hexdigest()[:24]
- task = self.tasks.create(
- request_id=(
- f"conversation:{MEMORY_INGEST_POLICY_VERSION}:{source.source_id}:"
- f"{profile.profile_id}:{profile.revision}:{digest}"
- ),
- user_id=source.user_id,
- kind=MemoryTaskKind.EXTRACT,
- input_ref=input_ref,
- profile=profile,
- input_records=chunk if freeze_inputs else (),
- )
- if task.status is MemoryTaskStatus.PENDING:
- self.tasks.supersede_unstarted(
- task,
- request_prefix=(
- f"conversation:{MEMORY_INGEST_POLICY_VERSION}:{source.source_id}:"
- f"{profile.profile_id}:{profile.revision}:"
- ),
- )
- return task
-
- async def _enqueue_after_quiet(
- self,
- record: EvidenceRecord,
- key: tuple[str, str, str, str | None],
- arrival_at: datetime,
- *,
- live: bool = False,
- delay: float = _TURN_SETTLE_SECONDS,
- ) -> None:
- try:
- await asyncio.sleep(delay)
- previous = self._preparations.get(key)
- if previous is not None:
- await asyncio.shield(previous)
- if self._shutting_down:
- return
- preparation = asyncio.create_task(
- self._prepare_live_conversation(record, key, arrival_at, live=live)
- )
- self._preparations[key] = preparation
- await asyncio.shield(preparation)
- finally:
- if self._debounces.get(key) is asyncio.current_task():
- self._debounces.pop(key, None)
-
- async def _prepare_live_conversation(
- self,
- record: EvidenceRecord,
- key: tuple[str, str, str, str | None],
- arrival_at: datetime,
- *,
- live: bool = False,
- ) -> None:
- preparation: asyncio.Task[tuple[list[MemoryTask], list[QueuedWork]]] | None = None
- try:
- if self._shutting_down:
- return
- if live and _opens_turn(record):
- # A realtime user message is an open turn, not a model input
- # on its own. The assistant/tool event that closes the turn
- # will schedule the complete conversation. A quiet-period
- # timeout must not manufacture an incomplete HY task.
- return
- preparation = asyncio.create_task(
- in_the_background(
- self._prepare_conversation_work,
- record,
- arrival_at=arrival_at,
- live=live,
- )
- )
- _, work = await asyncio.shield(preparation)
- if not self._shutting_down:
- await self._schedule_tasks_off_thread(work)
- except asyncio.CancelledError:
- # Cancelling the wrapper cannot stop its SQLite worker. Drain it
- # without dispatching the eventual result, including repeated cancel.
- if preparation is not None:
- while not preparation.done():
- try:
- await asyncio.shield(preparation)
- except asyncio.CancelledError:
- continue
- except Exception:
- break
- with suppress(asyncio.CancelledError, Exception):
- preparation.result()
- raise
- except HyMemoryBridgeError as error:
- if str(error).startswith("model_content_"):
- logging.getLogger(__name__).info("%s", str(error))
- else:
- _report_conversation_prepare_failure(record.source_id, error)
- except Exception as error:
- # No evidence or credentials in logs. Persisted work remains retryable.
- _report_conversation_prepare_failure(record.source_id, error)
- finally:
- if self._preparations.get(key) is asyncio.current_task():
- self._preparations.pop(key, None)
-
-
-def _memory_kind(layer: str | None) -> MemoryKind:
- normalized = (layer or "").lower()
- if "coding" in normalized:
- return MemoryKind.CODING
- if "working" in normalized:
- return MemoryKind.WORKING
- if "schema" in normalized:
- return MemoryKind.SCHEMA
- if "intention" in normalized:
- return MemoryKind.INTENTION
- return MemoryKind.CHAT
-
-
-def _hy_agent_id(records: tuple[EvidenceRecord, ...]) -> str:
- source_days = sorted(
- {
- f"{record.source_id}\0"
- f"{(record.created_at or record.imported_at).astimezone(UTC).date().isoformat()}"
- for record in records
- }
- )
- workspaces = sorted({record.workspace for record in records if record.workspace is not None})
- if workspaces:
- identity = "\0".join(("workspace", *source_days, *workspaces))
- elif records and all(record.source_id == "memory-content-export" for record in records):
- identity = "\0".join(
- ("unverified-memory-report", *sorted({r.conversation_id for r in records}))
- )
- elif all(record.content_kind is EvidenceContentKind.MEMORY_CONTENT for record in records):
- return UNIFIED_HY_AGENT_ID
- else:
- conversations = sorted(
- {f"{record.source_id}\0{record.conversation_id}" for record in records}
- )
- identity = "\0".join(("conversation", *source_days, *conversations))
- suffix = sha256(identity.encode()).hexdigest()[:32]
- return f"{UNIFIED_HY_AGENT_ID}:scope:{suffix}"
-
-
-def _is_profile_layer(layer: str | None) -> bool:
- """HY names the profile layers itself; this follows rather than re-decides.
-
- Its client holds `_PROFILE_LAYERS = {"l0_basic_info", "l6_schema"}`. This
- list drifted from that once already, to `L1_` — the raw conversation
- layer: had anything ever reached it, whole transcripts would have been
- broadcast to every app as though they were facts about the person.
-
- One predicate, two callers: what counts as a profile decides both the
- scope an extracted memory gets and which graph nodes a digest writes down.
- Those were separate judgements until the second one was found keeping only
- half the layers, so drift between them is no longer possible.
- """
- return (layer or "").upper().startswith(("L0_", "L6_SCHEMA"))
-
-
-def _is_memory_note(record: EvidenceRecord) -> bool:
- """Words the person saved as a memory themselves, rather than said in a conversation."""
- meta = record.origin_meta.get(EvidenceOrigin.MANUAL_IMPORT)
- return (
- record.source_id == "one-memory-manual"
- and meta is not None
- and meta.raw_meta.get("input_mode") == "direct_memory_note"
- )
-
-
-def _imported_as_said(record: EvidenceRecord) -> bool:
- """HY writes it as it stands and only deduplicates, instead of extracting from it.
-
- A note stays raw conversation because it is still the person's own words, which
- matter discovery and the raw index read; what it is not is a conversation for
- HY to judge whether to keep.
- """
- return record.content_kind is EvidenceContentKind.MEMORY_CONTENT or _is_memory_note(record)
-
-
-def _memory_scopes(
- records: tuple[EvidenceRecord, ...],
- *,
- layer: str | None,
-) -> tuple[str, ...]:
- if records and all(
- _is_memory_note(record)
- and record.origin_meta[EvidenceOrigin.MANUAL_IMPORT].raw_meta.get("recall_scope")
- == "all-apps"
- for record in records
- ):
- return ("all-apps",)
- workspaces = {record.workspace for record in records if record.workspace is not None}
- if _is_profile_layer(layer):
- return ("all-apps", *sorted(workspaces))
- if not workspaces and all(
- record.content_kind is EvidenceContentKind.MEMORY_CONTENT for record in records
- ):
- return ("all-apps",)
- specific = workspaces or {
- scope
- for record in records
- if (
- scope := opaque_workspace_id(
- record.source_id,
- f"unscoped-conversation:{record.conversation_id}",
- )
- )
- is not None
- }
- # Granting a source is what shares it; the specific scope stays so a
- # caller scoped to that project still matches (`all-apps` is not a wildcard).
- return ("all-apps", *sorted(specific))
-
-
-_HARNESS_PREFIXES = (
- "<codex_internal_context",
- "# agents.md instructions",
- "<environment_context>",
- "<permissions instructions>",
- "<system-reminder>",
- "<system_notification>",
- "<instructions>",
-)
-_HOST_ENVELOPE = re.compile(
- r"(?:"
- r"^<timestamp>.*?<system_(?:notification|reminder)>|"
- r"^<system_(?:notification|reminder)>|"
- r'^\{\s*"request_id"\s*:.*?"steps"\s*:'
- r")",
- re.IGNORECASE | re.DOTALL,
-)
-
-
-#: D74: HY itself drops tool records on the chat path and cuts each one to
-#: 2 KiB on the coding path, so a turn is sent whole and only the text HY will
-#: actually read counts toward the safety ceiling. Splitting by raw length
-#: before HY chose a path cut long answers mid-way and sent tool-heavy turns as
-#: dozens of calls. ONE_MEMORY_SPLIT_TURNS=1 restores the 12,000 / 24 split.
-_WHOLE_TURN_CHARACTERS = 60_000
-_HY_TOOL_CHARACTERS = coding_tool_result_max_bytes()
-#: Hard ceiling on the UTF-8 bytes one window may hold, whatever HY counts.
-#: HY reads the payload in-process, so a turn made of enormous raw tool
-#: records is held in memory even though HY will cut each one down. Cut by
-#: raw size once a window passes this, so no single call can grow without
-#: bound. Counted in bytes, not characters: one CJK character is three bytes,
-#: so a character count would let a Chinese window hold three times as much.
-_WINDOW_BYTE_CEILING = 2_000_000
-
-
-def _window_bytes(record: EvidenceRecord) -> int:
- return len(record.verbatim.encode("utf-8"))
-
-
-def _whole_turns() -> bool:
- return os.environ.get("ONE_MEMORY_SPLIT_TURNS", "").strip() != "1"
-
-
-def _hy_read_length(record: EvidenceRecord) -> int:
- if record.role == "tool":
- return min(len(record.verbatim), _HY_TOOL_CHARACTERS)
- return len(record.verbatim)
-
-
-def _conversation_chunks(
- records: list[EvidenceRecord],
- *,
- max_characters: int | None = None,
- max_turns: int | None = None,
- completed_only: bool = False,
-) -> list[tuple[EvidenceRecord, ...]]:
- """One HY window per turn: a question and everything that answered it.
-
- HY decides chat or coding from what a turn contains, so a turn is sent
- whole and alone; earlier turns reach it as history. A turn too long for
- one window is split, and every window is led by the question so HY never
- reads answers without what they answer.
-
- A proposal nobody has answered yet is not a turn of its own: an
- `assistant` prefix with no user reply yet joins the user turn that adopts
- it, so "the AI suggested X" and "the person adopted X" reach HY together.
- Splitting them sent HY an answer without what it answers and lost the
- proposal/adoption pair the author attribution gate reads.
- """
- turns: list[list[EvidenceRecord]] = []
- for record in records:
- if not _is_hy_turn_record(record):
- continue
- pending_proposal = bool(turns) and not _opens_turn(turns[-1][0])
- if not turns or (_opens_turn(record) and not pending_proposal):
- turns.append([record])
- else:
- # Either the reply to the turn already open, or the user message
- # that adopts a proposal nobody had answered yet.
- turns[-1].append(record)
-
- # Import keeps the unanswered tail as Evidence so it remains searchable
- # and can be completed by a later sync. It is not yet a settled turn for
- # HY, however. Put the rule here, before every caller's chunk preparation,
- # so backfill, ordinary imports and live capture cannot disagree about it.
- # Explicit memory content remains a valid one-record input, and an
- # assistant proposal followed by the person's adoption remains the joined
- # proposal/adoption turn established above rather than a user-opened turn.
- if completed_only and turns and _trailing_user_turn_is_open(turns[-1]):
- turns.pop()
-
- whole = _whole_turns() and max_characters is None
- if whole:
- size = _hy_read_length
- max_characters = _WHOLE_TURN_CHARACTERS
- max_turns = max_turns or 1_000_000
- else:
- size = lambda record: len(record.verbatim) # noqa: E731
- max_characters = max_characters or 12_000
- max_turns = max_turns or 24
-
- chunks: list[tuple[EvidenceRecord, ...]] = []
- for turn in turns:
- original_question = turn[0] if _opens_turn(turn[0]) else None
- expanded: list[EvidenceRecord] = []
- for record in turn:
- reserve = (
- size(original_question)
- if original_question is not None
- and record is not original_question
- and size(original_question) < max_characters
- else 0
- )
- segment_limit = max(1, max_characters - reserve)
- if size(record) <= segment_limit:
- expanded.append(record)
- continue
- spans = _semantic_segment_spans(record.verbatim, segment_limit)
- expanded.extend(
- segment_evidence_record(record, index=index, start=start, end=end)
- if len(spans) > 1
- else record
- for index, (start, end) in enumerate(spans)
- )
- question = expanded[0] if expanded and _opens_turn(expanded[0]) else None
- current: list[EvidenceRecord] = []
- for record in expanded:
- if current and (
- len(current) >= max_turns
- or sum(size(item) for item in current) + size(record) > max_characters
- or sum(_window_bytes(item) for item in current) + _window_bytes(record)
- > _WINDOW_BYTE_CEILING
- ):
- chunks.append(tuple(current))
- current = (
- [question]
- if question is not None
- and max_turns > 1
- and size(question) + size(record) <= max_characters
- else []
- )
- current.append(record)
- chunks.append(tuple(current))
- return _merge_tool_only_chunks(chunks)
-
-
-def _semantic_segment_spans(text: str, limit: int) -> list[tuple[int, int]]:
- """Split a single oversized message at paragraph/sentence boundaries."""
- if len(text) <= limit:
- return [(0, len(text))]
- spans: list[tuple[int, int]] = []
- start = 0
- separators = ("\n\n", "\n", "。", "!", "?", ". ", "! ", "? ")
- while start < len(text):
- hard_end = min(len(text), start + limit)
- if hard_end == len(text):
- end = hard_end
- else:
- floor = start + max(1, limit // 2)
- candidates = [text.rfind(separator, floor, hard_end) for separator in separators]
- boundary = max(candidates)
- if boundary < floor:
- end = hard_end
- else:
- matched = next(
- separator for separator in separators if text.startswith(separator, boundary)
- )
- end = boundary + len(matched)
- spans.append((start, end))
- start = end
- return spans
-
-
-def _merge_tool_only_chunks(
- chunks: list[tuple[EvidenceRecord, ...]],
-) -> list[tuple[EvidenceRecord, ...]]:
- """Never hand HY a window with only tool records.
-
- Splitting a long turn can leave tool calls in a later window after the
- question and answer filled the first one. HY's ``add`` treats that input as
- empty in the live WorkBuddy/Codex shape and answers ``content or messages
- is required``. Merge each such window into the previous one, or into the
- next one when it is the first; record order is preserved.
- """
- if not any(chunk and all(record.role == "tool" for record in chunk) for chunk in chunks):
- return chunks
- merged: list[tuple[EvidenceRecord, ...]] = []
- leading_tools: list[EvidenceRecord] = []
- for chunk in chunks:
- if not chunk:
- continue
- if chunk and all(record.role == "tool" for record in chunk):
- if merged:
- merged[-1] = (*merged[-1], *chunk)
- else:
- leading_tools.extend(chunk)
- continue
- if leading_tools:
- chunk = (*leading_tools, *chunk)
- leading_tools = []
- merged.append(chunk)
- # A conversation made only of tool records has no HY input turn at all;
- # dropping those windows is the same rule that keeps tool-only windows out.
- if leading_tools:
- return []
- return merged
-
-
-def _merge_historical_chunks(
- chunks: list[tuple[EvidenceRecord, ...]],
- *,
- max_turns: int = _HISTORY_MERGE_TURNS,
- max_characters: int = _HISTORY_MERGE_CHARACTERS,
-) -> list[tuple[EvidenceRecord, ...]]:
- """Coalesce adjacent unsent turns from one historical conversation.
-
- Callers pass chunks from exactly one conversation. Completed turns were
- removed before this function, so every merged member is still unstarted.
- Oversized turns stay intact and alone; the existing segment path owns them.
- """
- if not chunks:
- return []
- merged: list[tuple[EvidenceRecord, ...]] = []
- current: list[EvidenceRecord] = []
- current_turns = 0
- current_characters = 0
- for chunk in chunks:
- chunk_characters = sum(len(record.verbatim) for record in chunk)
- if current and (
- current_turns >= max_turns or current_characters + chunk_characters > max_characters
- ):
- merged.append(tuple(current))
- current = []
- current_turns = 0
- current_characters = 0
- current.extend(chunk)
- current_turns += 1
- current_characters += chunk_characters
- if current:
- merged.append(tuple(current))
- return merged
-
-
-def _chunk_input_ref(chunk: tuple[EvidenceRecord, ...]) -> str:
- user_records = tuple(item for item in chunk if item.role == "user")
- return user_records[-1].evidence_id if user_records else chunk[-1].evidence_id
-
-
-def _opens_turn(record: EvidenceRecord) -> bool:
- return record.role == "user"
-
-
-def _trailing_user_turn_is_open(turn: list[EvidenceRecord]) -> bool:
- if len(turn) != 1:
- return False
- opener = turn[0]
- return (
- _opens_turn(opener)
- and opener.content_kind is EvidenceContentKind.RAW_CONVERSATION
- and not _is_memory_note(opener)
- )
-
-
-def _is_hy_turn_record(record: EvidenceRecord) -> bool:
- """What HY receives of a turn: the input turns and the tool calls made in it."""
- if record.role == "tool":
- return record.content_kind is EvidenceContentKind.RAW_CONVERSATION and bool(
- record.verbatim.strip()
- )
- return _is_hy_input_turn(record)
-
-
-def _is_hy_input_turn(record: EvidenceRecord) -> bool:
- source = record.verbatim.strip()
- if not source:
- return False
- if record.content_kind is EvidenceContentKind.MEMORY_CONTENT:
- return True
- # Assistant output rides along as context. The hygiene checks below are
- # about telling the person's own words apart from what a harness typed on
- # their behalf, and none of that applies to a reply we already know came
- # from a model.
- if record.role == "assistant":
- return True
- # A sub-agent question is still a protocol `user` message. Host-specific
- # author guesses do not decide whether it reaches HY.
- if record.role != "user":
- return False
- if source.casefold().startswith(_HARNESS_PREFIXES):
- return False
- return _HOST_ENVELOPE.search(source[:2_000]) is None
diff --git a/memhub/apps/core/src/one_memory/memory_server/durable_queue.py b/memhub/apps/core/src/one_memory/memory_server/durable_queue.py
index 28c8ba0..5251ca6 100644
--- a/memhub/apps/core/src/one_memory/memory_server/durable_queue.py
+++ b/memhub/apps/core/src/one_memory/memory_server/durable_queue.py
@@ -69,8 +69,8 @@ _TYPE_NAME = re.compile(r"^[A-Za-z_][A-Za-z0-9_]{0,63}$")
def safe_error_code(error: BaseException) -> str:
"""Reduce an exception to a storable code, never its message text.
- A recognised code (the message *is* the code, as `HyMemoryBridgeError`
- and the permission guard raise them) is kept so callers can classify it.
+ A recognised code (the message *is* a stable domain code) is kept so
+ callers can classify it.
Everything else collapses to its exception type, which is a fixed
identifier rather than content.
"""
@@ -239,8 +239,8 @@ PERMISSION_REQUIRED_CODES = frozenset(
}
)
-#: Model-side codes `process_records` raises *before* it can open the bridge
-#: (no active profile, missing credential, secure storage down). They prove
+#: Model-side codes the SDK write coordinator raises before it can lease a
+#: client (no active profile, missing credential, secure storage down). They prove
#: nothing was sent, so the write parks instead of being lost. Transport codes
#: that can arrive after a request was in flight stay `unknown`.
MODEL_NOT_READY_CODES = frozenset(
@@ -251,9 +251,9 @@ MODEL_NOT_READY_CODES = frozenset(
}
)
-#: Deterministic, pre-bridge refusals: the frozen input no longer matches
+#: Deterministic, pre-SDK refusals: the frozen input no longer matches
#: current Evidence, or a turn exceeds the model's input window. Both are
-#: raised while validating the records, before any bridge or HY call, so
+#: raised while validating the records, before any SDK call, so
#: nothing was sent and retrying the same intent changes nothing — a terminal
#: `failed`, not `unknown` (which would wrongly imply a possibly-applied
#: write) and not a retry (which would fail identically).
@@ -358,12 +358,10 @@ class UnknownWriteJob:
`request_id` is the durable queue's idempotency key. It identifies the row
for queue inspection and is the value `DurableWriteQueue.get()` accepts.
- It is **not** the HY request id: `MemoryProcessingSupervisor` derives the
- HY handle from the task it creates, so an inquiry implementation must
- obtain that task-layer handle separately rather than passing this value to
- HY. This is discovery only: it does not decide whether HY has the write,
- and it deliberately exposes no transition method that could turn
- `unknown` back into retryable work.
+ It is the public SDK request id used for exact outcome inquiry. This is
+ discovery only: it does not decide whether HY has the write, and it
+ deliberately exposes no transition method that could turn `unknown` back
+ into retryable work.
"""
job_id: str
@@ -1759,8 +1757,8 @@ class DurableWriteQueue:
"""Retire an `unknown` job after an inquiry, never by guessing.
`unknown` means HY may already hold the write; the only safe way out is
- to ask by request id (`hy_capabilities` measured that the SDK supports
- this) and then record what the inquiry found. `found=True` closes it as
+ to call the public SDK `get_write_outcome(request_id)` and then record
+ what the inquiry found. `found=True` closes it as
`completed`; `found=False` gives up and marks it `dead`. The state
machine's legal transitions are the authority, so this refuses any
change that `job_state.next_state` would reject — in particular it can
@@ -2258,12 +2256,11 @@ async def execute_job(
admit_hy_invocation: Callable[[str, Callable[[], Awaitable[bool]]], Awaitable[bool]]
| None = None,
) -> None:
- """Run one durable job through the existing authorized processing path.
+ """Run one durable job through the SDK-authority processor.
- The executor does not call HY directly: `process_records` owns the
- permission guard, the runner and governance. `hy_invoked` is recorded
- before that call, so a crash mid-write is later reclaimed to `unknown`
- instead of being retried blindly.
+ ``process_sdk_job`` owns the one public SDK write. ``hy_invoked`` is
+ recorded immediately before that call, so a crash mid-write is later
+ reclaimed to ``unknown`` instead of being retried blindly.
"""
# Every store call here is synchronous SQLite work on the single writer or
# a reader; made from the loop it would block health checks and the API for
@@ -2336,38 +2333,13 @@ async def execute_job(
try:
level = ServiceLevel.REALTIME if request.priority == "live" else ServiceLevel.BACKGROUND
with service_level_context(level):
- authority = getattr(supervisor, "sdk_authority", None)
- if callable(authority) and authority():
- sdk_result = await supervisor.process_sdk_job(
- records,
- request_id=request.idempotency_key,
- before_hy_invocation=mark_hy_invocation,
- )
- raw_ids = sdk_result.raw_ids
- memory_ids = tuple(memory.memory_id for memory in sdk_result.memories)
- else:
- completed_tasks = (
- await supervisor.process_records(
- records,
- before_hy_invocation=mark_hy_invocation,
- source_admitted=True,
- )
- or ()
- )
- receipts = []
- for task in completed_tasks:
- receipt = await in_the_background(supervisor.tasks.sdk_receipt, task.task_id)
- if receipt is None:
- raise RuntimeError("sdk_write_receipt_missing")
- receipts.append(receipt)
- raw_ids = tuple(
- dict.fromkeys(raw_id for receipt in receipts for raw_id in receipt.raw_ids)
- )
- memory_ids = tuple(
- dict.fromkeys(
- memory_id for receipt in receipts for memory_id in receipt.memory_ids
- )
- )
+ sdk_result = await supervisor.process_sdk_job(
+ records,
+ request_id=request.idempotency_key,
+ before_hy_invocation=mark_hy_invocation,
+ )
+ raw_ids = sdk_result.raw_ids
+ memory_ids = sdk_result.memory_ids
except Exception as error: # noqa: BLE001 - classified below
# Never persist the raw message: it may be a provider response or the
# user's own text, and `last_error` is shown over HTTP as `detail`.
@@ -2382,7 +2354,7 @@ async def execute_job(
):
await in_the_background(queue.release_unstarted, job_id, owner=owner)
return
- # The task layer classifies these before any bridge is opened, so HY
+ # The write coordinator classifies these before any SDK client is leased, so HY
# was provably not called. They must not read as `failed`:
# - authorization stop -> cancelled (the user turned it off);
# - no permission yet -> waiting_for_permission (parked, re-admitted
@@ -2445,13 +2417,10 @@ async def execute_job(
sdk_raw_ids=raw_ids,
sdk_memory_ids=memory_ids,
)
- authority = getattr(supervisor, "sdk_authority", None)
release = getattr(evidence, "release_sdk_staging", None)
durable_receipt = await in_the_background(queue.sdk_receipt, job_id)
if (
- callable(authority)
- and authority()
- and callable(release)
+ callable(release)
and durable_receipt is not None
and (durable_receipt.raw_ids or durable_receipt.memory_ids)
):
diff --git a/memhub/apps/core/src/one_memory/memory_server/hy_capabilities.py b/memhub/apps/core/src/one_memory/memory_server/hy_capabilities.py
deleted file mode 100644
index e7daee1..0000000
--- a/memhub/apps/core/src/one_memory/memory_server/hy_capabilities.py
+++ /dev/null
@@ -1,182 +0,0 @@
-"""A0-03: measured answer to "can a HY write be made idempotent?".
-
-The result decides whether the `unknown` job state can ever be retired, so it
-is probed against the installed SDK rather than written down from memory.
-
-What is verified against `hy-memory==2.0.5.dev3`:
-
-- `HyMemoryClient.add(..., request_id=...)` accepts a caller-supplied id and
- atomically claims it in the SDK cache before invoking a write. Replays return
- the durable terminal result; running/unknown claims are not invoked again.
-- `HyMemoryClient.get_write_outcome(request_id)` reads that durable outcome
- directly; it does not depend on optional pipeline tracing.
-
-A first pass at this probe got both answers wrong, and the failure mode is
-worth keeping in mind: searching SDK source for the string "idempotent" hits a
-docstring about *episode* nodes ("calls are idempotent") and a "dedup" comment
-about search over-sampling. Neither is write idempotency. So the probe checks
-the `add` path specifically and names the inspector class explicitly, instead
-of grepping for a word that appears in unrelated prose.
-
-Net: MemHub can query and settle an uncertain request without blind replay.
-`unknown` remains a legitimate operational state while the SDK claim itself is
-non-terminal, but the same request id cannot write twice.
-"""
-
-from __future__ import annotations
-
-import importlib
-import inspect
-from enum import StrEnum
-from typing import Any
-
-
-class HyIdempotencySupport(StrEnum):
- """Whether the SDK can dedupe a replayed write."""
-
- #: A caller key is honoured and a replay is rejected or folded together.
- KEY = "key"
- #: Same content is folded by the engine, without an explicit key.
- CONTENT_HASH = "content_hash"
- #: A replay writes a second time. Retrying after a crash duplicates.
- NONE = "none"
- #: Never probed. Must not survive A0-03.
- UNKNOWN = "unknown"
-
-
-class HyResultLookupSupport(StrEnum):
- """Whether the outcome of a past write can be queried afterwards."""
-
- BY_REQUEST_ID = "by_request_id"
- BY_MEMORY_ID_ONLY = "by_memory_id_only"
- NONE = "none"
- UNKNOWN = "unknown"
-
-
-def _module(name: str) -> Any | None:
- try:
- return importlib.import_module(name)
- except ImportError:
- return None
-
-
-def _has_callable(obj: Any, name: str) -> bool:
- return obj is not None and callable(getattr(obj, name, None))
-
-
-def hy_write_accepts_request_id() -> bool:
- """True when the write path carries a caller-supplied request id."""
- client_mod = _module("hy_memory.client")
- if client_mod is None:
- return False
- client = getattr(client_mod, "HyMemoryClient", None)
- if client is None:
- return False
- add = getattr(client, "add", None)
- if add is None:
- return False
- return "request_id" in inspect.signature(add).parameters
-
-
-def _add_path_declares_idempotency() -> bool:
- """Whether the *write* path de-duplicates, judged on its own source.
-
- Deliberately scoped to `add`/`async_add`. A whole-module search matches
- unrelated prose: "calls are idempotent" describes episode-node upserts, and
- a "dedup" comment describes search over-sampling. Both are about other
- features and would make this probe answer `key` for the wrong reason.
- """
- client_mod = _module("hy_memory.client")
- if client_mod is None:
- return False
- client = getattr(client_mod, "HyMemoryClient", None)
- if client is None:
- return False
- sources: list[str] = []
- for name in ("add", "async_add"):
- func = getattr(client, name, None)
- if func is None:
- continue
- try:
- sources.append(inspect.getsource(func).lower())
- except (OSError, TypeError):
- continue
- if not sources:
- return False
- if _has_callable(client, "get_write_outcome"):
- claim = getattr(client, "_claim_write_outcome", None)
- if claim is not None:
- return True
- # Older SDKs may expose an explicit key under one of these names.
- markers = ("idempotency_key", "idempotent_key", "dedupe_key", "dedup_key")
- return any(marker in source for source in sources for marker in markers)
-
-
-def _inspector_can_lookup_by_request_id() -> bool:
- """True when pipeline logs can be queried by the write's request id."""
- inspector = _module("hy_memory.inspector")
- if inspector is None:
- return False
- for cls_name in ("MemoryInspector", "Inspector", "PipelineInspector"):
- cls = getattr(inspector, cls_name, None)
- if cls is None:
- continue
- for method in ("get_pipeline_logs", "async_get_pipeline_logs"):
- func = getattr(cls, method, None)
- if func is None:
- continue
- # The parameter is `request_id` on `MemoryInspector`; older
- # docstrings call the same thing `n`. Accept either so a rename
- # does not silently downgrade this to "no lookup available".
- if {"request_id", "n"} & set(inspect.signature(func).parameters):
- return True
- return False
-
-
-def _probe_idempotency() -> HyIdempotencySupport:
- if not hy_write_accepts_request_id():
- # No handle at all: not even a correlation id to investigate later.
- return HyIdempotencySupport.NONE
- if _add_path_declares_idempotency():
- return HyIdempotencySupport.KEY
- # A request_id is present but nothing de-duplicates on it.
- return HyIdempotencySupport.NONE
-
-
-def _probe_result_lookup() -> HyResultLookupSupport:
- client_mod = _module("hy_memory.client")
- client = getattr(client_mod, "HyMemoryClient", None) if client_mod is not None else None
- if _has_callable(client, "get_write_outcome"):
- return HyResultLookupSupport.BY_REQUEST_ID
- if _inspector_can_lookup_by_request_id():
- return HyResultLookupSupport.BY_REQUEST_ID
- if _has_callable(client, "get"):
- return HyResultLookupSupport.BY_MEMORY_ID_ONLY
- return HyResultLookupSupport.NONE
-
-
-IDEMPOTENCY_SUPPORT: HyIdempotencySupport = _probe_idempotency()
-RESULT_LOOKUP_SUPPORT: HyResultLookupSupport = _probe_result_lookup()
-
-
-def probe_hy_write_idempotency() -> dict[str, Any]:
- """Full probe report, for STATUS evidence and for debugging a bumped SDK.
-
- Re-probed on every call so a dependency upgrade that changes the answer is
- visible, rather than being frozen at import time.
- """
- client_mod = _module("hy_memory.client")
- client = getattr(client_mod, "HyMemoryClient", None)
- add = getattr(client, "add", None)
- return {
- "sdk_importable": client_mod is not None,
- "add_signature": str(inspect.signature(add)) if add is not None else "",
- "accepts_request_id": hy_write_accepts_request_id(),
- "add_declares_idempotency": _add_path_declares_idempotency(),
- "durable_write_outcome": (
- client is not None and _has_callable(client, "get_write_outcome")
- ),
- "inspector_lookup_by_request_id": _inspector_can_lookup_by_request_id(),
- "idempotency": _probe_idempotency().value,
- "result_lookup": _probe_result_lookup().value,
- }
diff --git a/memhub/apps/core/src/one_memory/memory_server/unified_entry.py b/memhub/apps/core/src/one_memory/memory_server/unified_entry.py
index aed520c..e5ed683 100644
--- a/memhub/apps/core/src/one_memory/memory_server/unified_entry.py
+++ b/memhub/apps/core/src/one_memory/memory_server/unified_entry.py
@@ -9,9 +9,8 @@ Evidence→queue crash window stayed open.
This adapter is deliberately small. It turns one committed Evidence record
into the one-record complete-turn request, submits it once under an evidence
derived idempotency key, and returns the durable record. The existing
-``DurableWriteDrain`` remains the only consumer; it calls
-``process_records``, which preserves the complete-turn/debounce/settle rules
-in ``MemoryProcessingSupervisor``.
+``DurableWriteDrain`` remains the only consumer; it calls the SDK write
+coordinator once and persists only the public receipt ids.
"""
from __future__ import annotations
diff --git a/memhub/apps/core/src/one_memory/memory_tasks.py b/memhub/apps/core/src/one_memory/memory_tasks.py
index 2f49d99..daf9070 100644
--- a/memhub/apps/core/src/one_memory/memory_tasks.py
+++ b/memhub/apps/core/src/one_memory/memory_tasks.py
@@ -477,7 +477,7 @@ class MemoryTaskStore:
#: Statuses whose input snapshot nothing reads back afterwards.
#:
#: Deliberately narrow. A `completed` task's inputs are read after the fact:
- #: `memory_processing` compares them against the evidence actually sent to
+ #: SDK write processing compares them against the evidence actually sent to
#: HY to prove coverage, and `matters/discovery` reads them to report how
#: many records HY really saw. Clearing those would silently turn a
#: verification into a pass and a report into a lie, which is far worse
diff --git a/memhub/apps/core/src/one_memory/model_request_audit.py b/memhub/apps/core/src/one_memory/model_request_audit.py
index 3a60296..8f52a4e 100644
--- a/memhub/apps/core/src/one_memory/model_request_audit.py
+++ b/memhub/apps/core/src/one_memory/model_request_audit.py
@@ -10,7 +10,6 @@ from contextlib import contextmanager
from contextvars import ContextVar
from dataclasses import dataclass
from datetime import UTC, datetime
-from importlib import import_module
from pathlib import Path
from typing import TypedDict
from uuid import uuid4
@@ -46,14 +45,7 @@ def audit_precipitation_request(request_id: str) -> Iterator[None]:
def _current_prompt_stage() -> str:
- try:
- resolver = getattr( # noqa: B009 - optional SDK version boundary
- import_module("hy_memory.utils.model_call_context"),
- "current_model_call_stage",
- )
- except (ImportError, AttributeError):
- return "other"
- return str(resolver())
+ return "other"
class ModelRequestAuditStore:
diff --git a/memhub/apps/core/src/one_memory/recall.py b/memhub/apps/core/src/one_memory/recall.py
index c53c9d3..e50bf66 100644
--- a/memhub/apps/core/src/one_memory/recall.py
+++ b/memhub/apps/core/src/one_memory/recall.py
@@ -12,7 +12,7 @@ from typing import Any, Literal, Protocol
from pydantic import BaseModel, ConfigDict, Field
-from one_memory.hy_memory_bridge import HySdkMemoryRecord
+from one_memory.hy_sdk_types import HySdkMemoryRecord
from one_memory.memory_governance import GovernedMemory, MemoryStatus
from one_memory.semantic_deadline import (
SemanticMemoryHit,
diff --git a/memhub/apps/core/src/one_memory/retrieval/content.py b/memhub/apps/core/src/one_memory/retrieval/content.py
index aedb453..2c1aa68 100644
--- a/memhub/apps/core/src/one_memory/retrieval/content.py
+++ b/memhub/apps/core/src/one_memory/retrieval/content.py
@@ -2,10 +2,10 @@
from collections.abc import Sequence
+from one_memory.conversation_processing import _is_hy_input_turn
from one_memory.imports.models import EvidenceContentKind, EvidenceRecord
from one_memory.imports.sources.parsing import is_host_generated_user_turn, strip_host_wrappers
from one_memory.input_sanitization import sanitize_model_input
-from one_memory.memory_processing import _is_hy_input_turn
from one_memory.retrieval.chunking import TextChunk
from one_memory.retrieval.mapped_content import PreparedMappedContent, prepare_mapped_content
diff --git a/memhub/apps/core/src/one_memory/retrieval/mapped_content.py b/memhub/apps/core/src/one_memory/retrieval/mapped_content.py
index 7c98dea..1f85efd 100644
--- a/memhub/apps/core/src/one_memory/retrieval/mapped_content.py
+++ b/memhub/apps/core/src/one_memory/retrieval/mapped_content.py
@@ -5,6 +5,7 @@ import json
from dataclasses import asdict, dataclass, field
from typing import Literal
+from one_memory.conversation_processing import _is_hy_input_turn
from one_memory.embedding_assets import BUILTIN_EMBEDDING_MAX_TOKENS
from one_memory.imports.models import (
MAX_VERBATIM_CHARACTERS,
@@ -17,7 +18,6 @@ from one_memory.imports.sources.parsing import (
)
from one_memory.input_sanitization import sanitize_model_input_with_spans
from one_memory.local_embedding import TokenizedText
-from one_memory.memory_processing import _is_hy_input_turn
from one_memory.retrieval.chunking import ChunkingError, OffsetTokenizer, TextChunk, chunk_evidence
MAP_VERSION = "raw-content-map-v1"
diff --git a/memhub/apps/core/src/one_memory/sdk_memory_qa.py b/memhub/apps/core/src/one_memory/sdk_memory_qa.py
index ec30f4b..3bd69dd 100644
--- a/memhub/apps/core/src/one_memory/sdk_memory_qa.py
+++ b/memhub/apps/core/src/one_memory/sdk_memory_qa.py
@@ -6,13 +6,15 @@ import asyncio
import json
from collections.abc import AsyncIterator, Awaitable, Callable
from contextlib import aclosing
-from typing import Literal
+from typing import Any, Literal, Protocol
import httpx
from pydantic import BaseModel, ConfigDict
from one_memory.http_client import create_async_client
-from one_memory.hy_memory_bridge import HyMemoryBridge, HySdkMemoryRecord
+from one_memory.hy_runtime_config import HY_MEMORY_READER
+from one_memory.hy_sdk_runtime import sdk_relevance_floor
+from one_memory.hy_sdk_types import HySdkMemoryRecord, parse_sdk_search
from one_memory.memory_qa import (
MemoryAnswerError,
_DeferredSecretStore,
@@ -36,6 +38,10 @@ _GROUNDING_LIMIT = 6
type _Recheck = Callable[[], Awaitable[None]]
+class SdkClientHandleLike(Protocol):
+ async def client(self) -> Any: ...
+
+
class SdkAskMemory(BaseModel):
model_config = ConfigDict(frozen=True, extra="forbid")
@@ -69,7 +75,7 @@ class SdkMemoryAnswerer:
def __init__(
self,
*,
- bridge: HyMemoryBridge,
+ client_handle: SdkClientHandleLike,
profiles: ModelProfileStore,
secrets: SecretStore,
authorize_generation: Callable[
@@ -78,7 +84,7 @@ class SdkMemoryAnswerer:
| None = None,
transport: httpx.AsyncBaseTransport | None = None,
) -> None:
- self.bridge = bridge
+ self.client_handle = client_handle
self.profiles = profiles
self.secrets = secrets
self.authorize_generation = authorize_generation
@@ -90,18 +96,27 @@ class SdkMemoryAnswerer:
*,
user_id: str = "local",
) -> tuple[SdkAskMemory, ...]:
- hits = await self.bridge.search_memories(
+ client = await self.client_handle.client()
+ raw = await asyncio.to_thread(
+ client.search,
question,
- user_id=user_id,
- agent_id="*",
+ user_ids=[user_id],
+ agent_ids=[],
limit=12,
+ min_score=sdk_relevance_floor(),
+ schema_min_score=sdk_relevance_floor(),
+ schema_limit=12,
+ intention_limit=12,
+ scene="normal",
+ reader=HY_MEMORY_READER,
)
+ hits = parse_sdk_search(raw, error_code="hy_memory_search_shape_unknown")
found: list[SdkAskMemory] = []
seen: set[str] = set()
for hit in hits:
if hit.memory_id in seen:
continue
- record = await self.bridge.get_sdk_memory(hit.memory_id)
+ record = await _get_memory(client, hit.memory_id)
if record is None or record.status != "active" or not record.is_latest:
continue
seen.add(record.memory_id)
@@ -211,8 +226,9 @@ class SdkMemoryAnswerer:
self,
memories: tuple[SdkAskMemory, ...],
) -> None:
+ client = await self.client_handle.client()
for memory in memories:
- current = await self.bridge.get_sdk_memory(memory.memory_id)
+ current = await _get_memory(client, memory.memory_id)
if current is None or _wire_memory(current) != memory:
raise MemoryAnswerError("memory_answer_context_changed")
@@ -340,6 +356,11 @@ def _wire_memory(record: HySdkMemoryRecord) -> SdkAskMemory:
)
+async def _get_memory(client: Any, memory_id: str) -> HySdkMemoryRecord | None:
+ raw = await asyncio.to_thread(client.get, memory_id)
+ return None if raw is None else HySdkMemoryRecord.from_sdk(raw)
+
+
def _summary(memories: tuple[SdkAskMemory, ...]) -> str:
statements = [
memory.content.replace("用户", "你", 1).replace("The user", "You", 1) for memory in memories
diff --git a/memhub/apps/core/src/one_memory/sdk_memory_runtime.py b/memhub/apps/core/src/one_memory/sdk_memory_runtime.py
new file mode 100644
index 0000000..4534e3d
--- /dev/null
+++ b/memhub/apps/core/src/one_memory/sdk_memory_runtime.py
@@ -0,0 +1,300 @@
+"""Narrow SDK-native runtime for graph, retrieval, and queue status operations."""
+
+from __future__ import annotations
+
+import asyncio
+from datetime import UTC, datetime, timedelta
+from pathlib import Path
+from typing import Any
+
+from one_memory.database_access import main_database
+from one_memory.extraction_settings import ExtractionSettings, ExtractionSettingsStore
+from one_memory.hy_graph_admin import (
+ GraphWidthDecision,
+ GraphWidthMismatch,
+ GraphWidthOutcome,
+ decide_profile_graph_width,
+ inspect_profile_graph_width,
+)
+from one_memory.hy_graph_projection import HyGraphSnapshot, read_graph_snapshot
+from one_memory.hy_runtime_config import HY_MEMORY_READER
+from one_memory.hy_sdk_runtime import SdkClientHandle, sdk_relevance_floor
+from one_memory.hy_sdk_types import HySdkError, parse_sdk_search
+from one_memory.memory_queue import ExtractionWindowPreset, QueueDepths
+from one_memory.memory_server.durable_queue import COMPLETED, DurableWriteQueue
+from one_memory.sdk_write_processor import SdkWriteCoordinator
+from one_memory.semantic_deadline import SemanticMemoryHit
+
+
+class SdkMemoryRuntime:
+ """Product services that remain after legacy task/governance writes retire."""
+
+ def __init__(
+ self,
+ *,
+ coordinator: SdkWriteCoordinator,
+ read_handle: SdkClientHandle,
+ write_queue: DurableWriteQueue,
+ extraction_settings: ExtractionSettingsStore,
+ data_dir: Path,
+ ) -> None:
+ self.coordinator = coordinator
+ self.read_handle = read_handle
+ self.write_queue = write_queue
+ self.extraction_settings = extraction_settings
+ self.data_dir = data_dir
+
+ async def semantic_recall(
+ self,
+ query: str,
+ *,
+ limit: int = 12,
+ ) -> tuple[SemanticMemoryHit, ...]:
+ client = await self.read_handle.client()
+ raw = await asyncio.to_thread(
+ client.search,
+ query,
+ user_ids=["local"],
+ agent_ids=[],
+ limit=limit,
+ min_score=sdk_relevance_floor(),
+ schema_min_score=sdk_relevance_floor(),
+ schema_limit=limit,
+ intention_limit=limit,
+ scene="normal",
+ reader=HY_MEMORY_READER,
+ )
+ return parse_sdk_search(raw, error_code="hy_memory_search_shape_unknown")
+
+ async def semantic_search(
+ self,
+ query: str,
+ *,
+ limit: int = 12,
+ ) -> tuple[tuple[str, float], ...]:
+ return tuple(
+ (hit.memory_id, hit.score)
+ for hit in await self.semantic_recall(query, limit=limit)
+ )
+
+ async def graph_snapshot(self, *, limit: int = 300) -> HyGraphSnapshot:
+ try:
+ await self.coordinator.active_profile_credentials()
+ except RuntimeError as error:
+ if str(error) == "model_profile_not_active":
+ return HyGraphSnapshot(consulted=False)
+ raise
+ try:
+ client = await self.coordinator.client()
+ except Exception as error:
+ raise HySdkError("hy_memory_graph_read_failed") from error
+ return await asyncio.to_thread(
+ read_graph_snapshot,
+ client,
+ "local",
+ "*",
+ limit,
+ )
+
+ async def digest(self) -> dict[str, object]:
+ client = await self.coordinator.client()
+ try:
+ raw = await asyncio.to_thread(
+ client.list_memories,
+ user_id="local",
+ limit=1_000,
+ offset=0,
+ )
+ agent_ids = _agent_ids(raw)
+ digests = [
+ {
+ "agent_id": agent_id,
+ "schemas_recorded": 0,
+ **dict(
+ await asyncio.to_thread(
+ client.evolve,
+ user_id="local",
+ agent_id=agent_id,
+ )
+ ),
+ }
+ for agent_id in agent_ids
+ ]
+ except Exception as error:
+ raise HySdkError("hy_memory_digest_failed") from error
+ return {
+ "success": all(result.get("success") is not False for result in digests),
+ "scope_count": len(digests),
+ "skipped_conversation_scopes": 0,
+ "schemas_recorded": 0,
+ "digests": digests,
+ }
+
+ async def graph_width_mismatch(self) -> GraphWidthMismatch | None:
+ try:
+ profile, secret = await self.coordinator.active_profile_credentials()
+ except RuntimeError as error:
+ if str(error) == "model_profile_not_active":
+ return None
+ raise
+ return await asyncio.to_thread(
+ inspect_profile_graph_width,
+ profile,
+ api_key=secret,
+ data_dir=self.data_dir,
+ )
+
+ async def decide_graph_width(
+ self,
+ decision: GraphWidthDecision,
+ ) -> GraphWidthOutcome:
+ try:
+ profile, secret = await self.coordinator.active_profile_credentials()
+ except RuntimeError as error:
+ raise HySdkError(str(error)) from error
+ return await asyncio.to_thread(
+ decide_profile_graph_width,
+ profile,
+ api_key=secret,
+ data_dir=self.data_dir,
+ decision=decision,
+ )
+
+ async def update_hy_memory(self, memory_id: str, content: str) -> dict[str, object]:
+ client = await self.coordinator.client()
+ try:
+ result = await asyncio.to_thread(client.update, memory_id, content)
+ except Exception as error:
+ raise HySdkError("hy_memory_update_failed") from error
+ if not isinstance(result, dict) or result.get("success") is not True:
+ raise HySdkError("hy_memory_update_rejected")
+ return result
+
+ async def finish_deletion(self, memory_id: str) -> None:
+ client = await self.coordinator.client()
+ try:
+ result = await asyncio.to_thread(client.delete, memory_id)
+ except Exception as error:
+ raise HySdkError("hy_memory_delete_failed") from error
+ if not isinstance(result, dict):
+ raise HySdkError("hy_memory_delete_rejected")
+ error_code = result.get("error_code")
+ if error_code or result.get("partial") is True:
+ raise HySdkError(str(error_code or "hy_memory_delete_incomplete"))
+ if result.get("success") is not True and result.get("deleted_count") != 0:
+ raise HySdkError("hy_memory_delete_rejected")
+
+ def extraction_window_settings(self) -> ExtractionSettings:
+ return self.extraction_settings.get()
+
+ def set_extraction_window(
+ self,
+ preset: ExtractionWindowPreset,
+ ) -> ExtractionSettings:
+ return self.extraction_settings.set_window_preset(preset)
+
+ def queue_depths(self) -> QueueDepths:
+ now = datetime.now(UTC)
+ fresh_since = (now - timedelta(days=7)).isoformat()
+ with main_database(self.write_queue.database_path).read() as database:
+ fresh = int(
+ database.execute(
+ "SELECT COUNT(*) FROM memory_write_jobs "
+ "WHERE state IN ('pending','waiting_for_model','waiting_for_permission') "
+ "AND event_at>=?",
+ (fresh_since,),
+ ).fetchone()[0]
+ )
+ backlog = int(
+ database.execute(
+ "SELECT COUNT(*) FROM memory_write_jobs "
+ "WHERE state IN ('pending','waiting_for_model','waiting_for_permission') "
+ "AND event_at<?",
+ (fresh_since,),
+ ).fetchone()[0]
+ )
+ recent = tuple(
+ datetime.fromisoformat(str(row[0]))
+ for row in database.execute(
+ "SELECT updated_at FROM memory_write_jobs WHERE state='completed' "
+ "ORDER BY updated_at DESC LIMIT 8"
+ )
+ )
+ return QueueDepths(fresh=fresh, backlog=backlog, recent_completions=recent)
+
+ def active_depths(self) -> tuple[int, int]:
+ with main_database(self.write_queue.database_path).read() as database:
+ running = int(
+ database.execute(
+ "SELECT COUNT(*) FROM memory_write_jobs WHERE state='running'"
+ ).fetchone()[0]
+ )
+ return running, running
+
+ def status_counts(self) -> dict[str, int]:
+ with main_database(self.write_queue.database_path).read() as database:
+ return {
+ str(row[0]): int(row[1])
+ for row in database.execute(
+ "SELECT state,COUNT(*) FROM memory_write_jobs GROUP BY state"
+ )
+ }
+
+ def manual_batch_progress(self) -> tuple[int, int]:
+ return 0, 0
+
+ def promote_next_manual_batch(self, *, task_ids: tuple[str, ...] | None = None) -> list[Any]:
+ del task_ids
+ return []
+
+ async def reconcile_unknown_outputs(
+ self,
+ *,
+ limit: int = 128,
+ exclude_error_codes: tuple[str, ...] = (),
+ ) -> int:
+ reconciled = 0
+ for job in await asyncio.to_thread(
+ self.write_queue.unknown_jobs,
+ limit=limit,
+ exclude_error_codes=exclude_error_codes,
+ ):
+ receipt = await self.coordinator.inquire_write_outcome(job.request_id)
+ if receipt is None:
+ continue
+ await asyncio.to_thread(
+ self.write_queue.settle,
+ job.job_id,
+ state=COMPLETED,
+ sdk_raw_ids=receipt.raw_ids,
+ sdk_memory_ids=receipt.memory_ids,
+ )
+ reconciled += 1
+ return reconciled
+
+ async def resume_allowed(self) -> None:
+ await asyncio.to_thread(self.write_queue.readmit_parked)
+
+ def accepted_backfill_status(self) -> None:
+ return None
+
+ async def shutdown(self) -> None:
+ return None
+
+
+def _agent_ids(raw: object) -> tuple[str, ...]:
+ if not isinstance(raw, dict):
+ raise HySdkError("hy_memory_list_shape_unknown")
+ found: set[str] = set()
+ for bucket_name, rows_name in (("vdb", "memories"), ("graph", "nodes")):
+ bucket = raw.get(bucket_name)
+ if bucket is None:
+ continue
+ if not isinstance(bucket, dict) or not isinstance(bucket.get(rows_name), list):
+ raise HySdkError("hy_memory_list_shape_unknown")
+ for row in bucket[rows_name]:
+ if isinstance(row, dict):
+ agent_id = row.get("agent_id")
+ if isinstance(agent_id, str) and agent_id:
+ found.add(agent_id)
+ return tuple(sorted(found))
diff --git a/memhub/apps/core/src/one_memory/sdk_migration_bundle.py b/memhub/apps/core/src/one_memory/sdk_migration_bundle.py
index 4e7eed5..ed9e4ae 100644
--- a/memhub/apps/core/src/one_memory/sdk_migration_bundle.py
+++ b/memhub/apps/core/src/one_memory/sdk_migration_bundle.py
@@ -22,6 +22,12 @@ from one_memory.hy_runtime_config import (
HY_MEMORY_NAMESPACE,
HY_MEMORY_VERSION,
)
+from one_memory.hy_sdk_migration import (
+ restore_data_plane as restore_sdk_data_plane,
+)
+from one_memory.hy_sdk_migration import (
+ snapshot_data_plane,
+)
class MigrationBundleRejected(RuntimeError):
@@ -113,11 +119,7 @@ def create_sdk_migration_bundle(
if not sdk_root.is_dir():
raise MigrationBundleRejected("sdk_migration_bundle_sdk_root_invalid")
if snapshotter is None:
- try:
- from one_memory.hy_memory_bridge import snapshot_hy_data_plane
- except ImportError as error:
- raise MigrationBundleRejected("sdk_migration_snapshot_unavailable") from error
- snapshotter = snapshot_hy_data_plane
+ snapshotter = snapshot_data_plane
try:
snapshotter(
source_root=sdk_root,
@@ -275,11 +277,7 @@ def restore_sdk_migration_bundle(
raise MigrationBundleRejected("sdk_migration_bundle_manifest_invalid")
if restore_data_plane is None:
- try:
- from one_memory.hy_memory_bridge import restore_hy_data_plane
- except ImportError as error:
- raise MigrationBundleRejected("sdk_migration_restore_unavailable") from error
- restore_data_plane = restore_hy_data_plane
+ restore_data_plane = restore_sdk_data_plane
stamp = (now or datetime.now(UTC)).strftime("%Y%m%dT%H%M%S%fZ")
database_live = home / "one-memory.sqlite3"
diff --git a/memhub/apps/core/src/one_memory/sdk_migration_inventory.py b/memhub/apps/core/src/one_memory/sdk_migration_inventory.py
index 613e646..43e370b 100644
--- a/memhub/apps/core/src/one_memory/sdk_migration_inventory.py
+++ b/memhub/apps/core/src/one_memory/sdk_migration_inventory.py
@@ -12,7 +12,7 @@ from pathlib import Path
from typing import Protocol
from one_memory.database_access import main_database
-from one_memory.hy_memory_bridge import HySdkMemoryPage, HySdkRawRecord
+from one_memory.hy_sdk_types import HySdkMemoryPage, HySdkRawPage
from one_memory.sdk_data_plane_migration import SdkDataPlaneMigrationStore
@@ -103,8 +103,8 @@ SDK_LIFECYCLE_STATUSES = (
)
-class SdkMigrationBridge(Protocol):
- def list_sdk_memories(
+class SdkMigrationClient(Protocol):
+ def list_memories(
self,
*,
user_id: str,
@@ -115,7 +115,7 @@ class SdkMigrationBridge(Protocol):
order: str = "desc",
) -> Awaitable[HySdkMemoryPage]: ...
- def import_sdk_memory_exact(
+ def import_memory_exact(
self,
*,
content: str,
@@ -133,7 +133,7 @@ class SdkMigrationBridge(Protocol):
request_id: str,
) -> Awaitable[dict[str, object]]: ...
- def list_sdk_raw(
+ def list_raw(
self,
*,
user_id: str,
@@ -143,9 +143,9 @@ class SdkMigrationBridge(Protocol):
limit: int = 100,
offset: int = 0,
order: str = "desc",
- ) -> Awaitable[tuple[tuple[HySdkRawRecord, ...], int]]: ...
+ ) -> Awaitable[HySdkRawPage]: ...
- def import_sdk_raw_exact(
+ def import_raw(
self,
*,
content: str,
@@ -360,7 +360,7 @@ def classify_memory_inventory(
async def read_sdk_memory_inventory(
- bridge: SdkMigrationBridge,
+ client: SdkMigrationClient,
*,
user_id: str = "local",
page_size: int = 500,
@@ -368,7 +368,7 @@ async def read_sdk_memory_inventory(
records: dict[str, SdkMemoryInventory] = {}
offset = 0
while True:
- page = await bridge.list_sdk_memories(
+ page = await client.list_memories(
user_id=user_id,
statuses=SDK_LIFECYCLE_STATUSES,
limit=page_size,
@@ -425,7 +425,7 @@ def record_memory_migration_plan(
async def execute_memory_migration_plan(
- bridge: SdkMigrationBridge,
+ client: SdkMigrationClient,
store: SdkDataPlaneMigrationStore,
*,
migration_id: str,
@@ -457,7 +457,7 @@ async def execute_memory_migration_plan(
continue
if decision.action in {"delete", "verified_deleted"}:
if decision.action == "delete":
- await bridge.delete(decision.canonical_memory_id)
+ await client.delete(decision.canonical_memory_id)
store.settle_item(
migration_id=migration_id,
item_key=decision.item_key,
@@ -472,12 +472,13 @@ async def execute_memory_migration_plan(
request_id = hashlib.sha256(
f"{migration_id}:{decision.item_key}:import_exact".encode()
).hexdigest()
- await bridge.import_sdk_memory_exact(
+ await client.import_memory_exact(
content=item.content,
memory_id=item.canonical_memory_id,
user_id=item.user_id,
agent_id=item.agent_id,
session_id=item.session_id,
+ source="legacy-governance",
layer=item.layer,
status=item.status,
owner=item.owner,
@@ -485,6 +486,8 @@ async def execute_memory_migration_plan(
supersedes=item.supersedes,
superseded_by=item.superseded_by,
is_latest=item.status == "active",
+ memory_at=None,
+ metadata={},
request_id=request_id,
)
if decision.action == "record_alias":
@@ -503,7 +506,7 @@ async def execute_memory_migration_plan(
async def read_sdk_raw_inventory(
- bridge: SdkMigrationBridge,
+ client: SdkMigrationClient,
*,
user_id: str = "local",
page_size: int = 500,
@@ -511,13 +514,13 @@ async def read_sdk_raw_inventory(
records: dict[str, SdkRawInventory] = {}
offset = 0
while True:
- rows, total = await bridge.list_sdk_raw(
+ page = await client.list_raw(
user_id=user_id,
limit=page_size,
offset=offset,
order="asc",
)
- for raw in rows:
+ for raw in page.raw:
raw_id = str(raw.raw_id)
records[raw_id] = SdkRawInventory(
raw_id=raw_id,
@@ -527,9 +530,9 @@ async def read_sdk_raw_inventory(
source=str(raw.source),
content_hash=content_hash(str(raw.content)),
)
- consumed = len(rows)
+ consumed = len(page.raw)
offset += consumed
- if consumed == 0 or offset >= total:
+ if consumed == 0 or offset >= page.total:
break
return tuple(records[key] for key in sorted(records))
@@ -632,7 +635,7 @@ def record_raw_migration_plan(
async def execute_raw_migration_plan(
- bridge: SdkMigrationBridge,
+ client: SdkMigrationClient,
store: SdkDataPlaneMigrationStore,
*,
migration_id: str,
@@ -656,7 +659,7 @@ async def execute_raw_migration_plan(
request_id = hashlib.sha256(
f"{migration_id}:{decision.item_key}:import_raw".encode()
).hexdigest()
- await bridge.import_sdk_raw_exact(
+ await client.import_raw(
content=item.content,
raw_id=decision.raw_id,
user_id=item.user_id,
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 60fb239..aeb0965 100644
--- a/memhub/apps/core/src/one_memory/sdk_migration_runner.py
+++ b/memhub/apps/core/src/one_memory/sdk_migration_runner.py
@@ -24,7 +24,7 @@ from one_memory.sdk_data_plane_migration import (
)
from one_memory.sdk_migration_bundle import inspect_sdk_migration_bundle
from one_memory.sdk_migration_inventory import (
- SdkMigrationBridge,
+ SdkMigrationClient,
execute_memory_migration_plan,
execute_raw_migration_plan,
read_legacy_memory_inventory,
@@ -238,7 +238,7 @@ def resume_legacy_cleanup(*, data_dir: Path, database_path: Path) -> tuple[str,
async def run_sdk_data_plane_backfill(
*,
database_path: Path,
- bridge: SdkMigrationBridge,
+ client: SdkMigrationClient,
migration_id: str,
bundle_id: str,
source_runtime_build: str,
@@ -261,7 +261,7 @@ 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(bridge)
+ sdk_memories = await read_sdk_memory_inventory(client)
memory_decisions = record_memory_migration_plan(
store,
migration_id=migration_id,
@@ -269,7 +269,7 @@ async def run_sdk_data_plane_backfill(
sdk=sdk_memories,
)
legacy_raw = read_legacy_raw_inventory(database_path)
- sdk_raw = await read_sdk_raw_inventory(bridge)
+ sdk_raw = await read_sdk_raw_inventory(client)
raw_decisions = record_raw_migration_plan(
store,
migration_id=migration_id,
@@ -279,14 +279,14 @@ async def run_sdk_data_plane_backfill(
store.set_phase(migration_id, phase="backfill", state="running")
await execute_memory_migration_plan(
- bridge,
+ client,
store,
migration_id=migration_id,
legacy=legacy_memories,
decisions=memory_decisions,
)
await execute_raw_migration_plan(
- bridge,
+ client,
store,
migration_id=migration_id,
legacy=legacy_raw,
diff --git a/memhub/apps/core/src/one_memory/sdk_write_processor.py b/memhub/apps/core/src/one_memory/sdk_write_processor.py
new file mode 100644
index 0000000..cbd8674
--- /dev/null
+++ b/memhub/apps/core/src/one_memory/sdk_write_processor.py
@@ -0,0 +1,330 @@
+"""Single-write adapter from durable Evidence payloads to the public HY SDK."""
+
+from __future__ import annotations
+
+import asyncio
+from collections.abc import Awaitable, Callable, Mapping, Sequence
+from dataclasses import dataclass
+from datetime import datetime
+from typing import Any
+
+from one_memory.hy_sdk_runtime import SdkClientHandle
+from one_memory.imports.models import EvidenceContentKind, EvidenceOrigin, EvidenceRecord
+from one_memory.input_sanitization import sanitize_model_input
+from one_memory.model_profiles import ModelProfileSnapshot, ModelProfileStore
+from one_memory.secrets import SecretStore, SecretStoreUnavailableError
+
+PRODUCT_AGENT_ID = "all-apps"
+_MESSAGE_ROLES = frozenset({"user", "assistant", "tool"})
+
+
+@dataclass(frozen=True)
+class SdkWriteReceipt:
+ """The only SDK write identity retained by MemHub."""
+
+ raw_ids: tuple[str, ...] = ()
+ memory_ids: tuple[str, ...] = ()
+
+
+class SdkWriteProcessor:
+ """Turn one durable job into exactly one public SDK write call."""
+
+ def __init__(self, client_handle: SdkClientHandle) -> None:
+ self._client_handle = client_handle
+
+ async def process_sdk_job(
+ self,
+ records: tuple[EvidenceRecord, ...],
+ *,
+ request_id: str,
+ before_hy_invocation: Callable[[], Awaitable[None]],
+ ) -> SdkWriteReceipt:
+ if not records:
+ raise RuntimeError("hy_memory_task_without_inputs")
+
+ scope = _write_scope(records)
+ metadata = _write_metadata(records, scope)
+ client = await self._client_handle.client()
+
+ if all(_is_extracted_content(record) for record in records):
+ contents = [sanitize_model_input(record.verbatim) for record in records]
+ await before_hy_invocation()
+ result = await asyncio.to_thread(
+ client.add_extracted,
+ contents,
+ user_id=scope.user_id,
+ agent_id=PRODUCT_AGENT_ID,
+ session_id=scope.session_id,
+ source=scope.source,
+ metadata=metadata,
+ memory_at=scope.memory_at,
+ request_id=request_id,
+ )
+ else:
+ messages = [
+ {
+ "role": record.role,
+ "content": sanitize_model_input(record.verbatim),
+ }
+ for record in records
+ if record.content_kind is EvidenceContentKind.RAW_CONVERSATION
+ and record.role in _MESSAGE_ROLES
+ ]
+ if not messages:
+ raise RuntimeError("hy_memory_task_without_inputs")
+ await before_hy_invocation()
+ result = await asyncio.to_thread(
+ client.add,
+ messages,
+ user_id=scope.user_id,
+ agent_id=PRODUCT_AGENT_ID,
+ session_id=scope.session_id,
+ source=scope.source,
+ metadata=metadata,
+ memory_at=scope.memory_at,
+ scene=None,
+ workspace_id=scope.workspace,
+ request_id=request_id,
+ )
+
+ return _receipt_from_result(result)
+
+ async def inquire_write_outcome(self, request_id: str) -> SdkWriteReceipt | None:
+ """Return a confirmed successful receipt without scanning SDK stores."""
+ if not request_id:
+ raise ValueError("request_id is required")
+ client = await self._client_handle.client()
+ outcome = await asyncio.to_thread(client.get_write_outcome, request_id)
+ if outcome is None:
+ return None
+ if not isinstance(outcome, Mapping):
+ raise RuntimeError("hy_sdk_write_outcome_shape_invalid")
+
+ status = outcome.get("status")
+ if status != "succeeded":
+ return None
+ result = outcome.get("result")
+ if not isinstance(result, Mapping):
+ raise RuntimeError("hy_sdk_write_outcome_shape_invalid")
+ return _receipt_from_result(result)
+
+ async def close(self) -> None:
+ await self._client_handle.close()
+
+
+class SdkWriteCoordinator:
+ """Resolve the active model profile, then execute one public SDK write."""
+
+ def __init__(
+ self,
+ *,
+ profiles: ModelProfileStore,
+ secrets: SecretStore,
+ data_dir: Any,
+ transport_factory: Callable[[ModelProfileSnapshot], Callable[[], Any] | None],
+ sedimentation_enabled: Callable[[], bool],
+ ) -> None:
+ self.profiles = profiles
+ self.secrets = secrets
+ self.data_dir = data_dir
+ self.transport_factory = transport_factory
+ self.sedimentation_enabled = sedimentation_enabled
+ self._handles: dict[tuple[str, int], SdkClientHandle] = {}
+ self._lock = asyncio.Lock()
+
+ async def process_sdk_job(
+ self,
+ records: tuple[EvidenceRecord, ...],
+ *,
+ request_id: str,
+ before_hy_invocation: Callable[[], Awaitable[None]],
+ ) -> SdkWriteReceipt:
+ if not self.sedimentation_enabled():
+ raise RuntimeError("model_sedimentation_disabled")
+ handle = await self._active_handle()
+ return await SdkWriteProcessor(handle).process_sdk_job(
+ records,
+ request_id=request_id,
+ before_hy_invocation=before_hy_invocation,
+ )
+
+ async def inquire_write_outcome(
+ self, request_id: str
+ ) -> SdkWriteReceipt | None:
+ return await SdkWriteProcessor(
+ await self._active_handle()
+ ).inquire_write_outcome(request_id)
+
+ async def close(self) -> None:
+ async with self._lock:
+ handles, self._handles = tuple(self._handles.values()), {}
+ await asyncio.gather(*(handle.close() for handle in handles))
+
+ async def client(self) -> Any:
+ """Return the public SDK client selected by the active write profile."""
+ return await (await self._active_handle()).client()
+
+ async def active_profile_credentials(
+ self,
+ ) -> tuple[ModelProfileSnapshot, str | None]:
+ """Resolve one stable profile snapshot for graph administration."""
+ _identity, profile, secret = await asyncio.to_thread(self._read_active_credentials)
+ return profile, secret
+
+ async def _active_handle(self) -> SdkClientHandle:
+ identity, profile, secret = await asyncio.to_thread(
+ self._read_active_credentials
+ )
+ async with self._lock:
+ handle = self._handles.get(identity)
+ if handle is None:
+ handle = SdkClientHandle(
+ profile,
+ api_key=secret,
+ data_dir=self.data_dir,
+ http_transport_factory=self.transport_factory(profile),
+ )
+ self._handles[identity] = handle
+ stale = [
+ value
+ for key, value in self._handles.items()
+ if key != identity
+ ]
+ self._handles = {identity: handle}
+ await asyncio.gather(*(value.close() for value in stale))
+ return handle
+
+ def _read_active_credentials(
+ self,
+ ) -> tuple[tuple[str, int], ModelProfileSnapshot, str | None]:
+ identity = self.profiles.active_identity()
+ if identity is None:
+ raise RuntimeError("model_profile_not_active")
+ profile = self.profiles.snapshot(*identity)
+ try:
+ secret = self.profiles.resolve_snapshot_secret(
+ *identity,
+ self.secrets,
+ )
+ except SecretStoreUnavailableError:
+ raise RuntimeError("secure_storage_unavailable") from None
+ if self.profiles.active_identity() != identity:
+ raise RuntimeError("model_profile_changed")
+ if profile.has_api_key and secret is None:
+ raise RuntimeError("model_secret_unavailable")
+ return identity, profile, secret
+
+
+@dataclass(frozen=True)
+class _WriteScope:
+ user_id: str
+ session_id: str
+ source: str
+ workspace: str | None
+ workspaces: tuple[str, ...]
+ memory_at: datetime | None
+
+
+def _write_scope(records: tuple[EvidenceRecord, ...]) -> _WriteScope:
+ first = records[0]
+ expected = (first.user_id, first.source_id, first.conversation_id)
+ if any(
+ (record.user_id, record.source_id, record.conversation_id) != expected
+ for record in records[1:]
+ ):
+ raise RuntimeError("durable_write_multiple_sources")
+ workspaces = tuple(
+ sorted({record.workspace for record in records if record.workspace is not None})
+ )
+ return _WriteScope(
+ user_id=first.user_id,
+ session_id=first.conversation_id,
+ source=first.source_id,
+ workspace=workspaces[0] if len(workspaces) == 1 else None,
+ workspaces=workspaces,
+ memory_at=max(
+ (record.created_at for record in records if record.created_at is not None),
+ default=None,
+ ),
+ )
+
+
+def _write_metadata(
+ records: tuple[EvidenceRecord, ...],
+ scope: _WriteScope,
+) -> dict[str, Any]:
+ return {
+ "source_id": scope.source,
+ "session_id": scope.session_id,
+ "workspace_ids": list(scope.workspaces),
+ "memory_at": scope.memory_at.isoformat() if scope.memory_at is not None else None,
+ "evidence_ids": [record.evidence_id for record in records],
+ "input_kind": (
+ "memory_content_without_raw"
+ if all(_is_extracted_content(record) for record in records)
+ else "raw_conversation"
+ ),
+ }
+
+
+def _is_extracted_content(record: EvidenceRecord) -> bool:
+ if record.content_kind is EvidenceContentKind.MEMORY_CONTENT:
+ return True
+ manual = record.origin_meta.get(EvidenceOrigin.MANUAL_IMPORT)
+ return (
+ record.source_id == "one-memory-manual"
+ and manual is not None
+ and manual.raw_meta.get("input_mode") == "direct_memory_note"
+ )
+
+
+def _receipt_from_result(value: object) -> SdkWriteReceipt:
+ if not isinstance(value, Mapping):
+ raise RuntimeError("hy_sdk_write_receipt_shape_invalid")
+ if value.get("success") is not True:
+ raise RuntimeError("hy_sdk_write_failed")
+
+ # Read only documented public receipt fields. ``variant`` identifies the
+ # productivity namespace; IDs from both variants are canonical memory IDs.
+ variant = value.get("variant")
+ if variant is not None and not isinstance(variant, str):
+ raise RuntimeError("hy_sdk_write_receipt_shape_invalid")
+ raw_ids = _public_ids(value, singular="raw_id", plural="raw_ids")
+ memory_ids = _ordered_unique(
+ (
+ *_public_ids(value, singular="memory_id", plural="memory_ids"),
+ *_public_ids(value, plural="experience_ids"),
+ *_public_ids(value, plural="fact_ids"),
+ )
+ )
+ return SdkWriteReceipt(raw_ids=raw_ids, memory_ids=memory_ids)
+
+
+def _public_ids(
+ value: Mapping[object, object],
+ *,
+ singular: str | None = None,
+ plural: str,
+) -> tuple[str, ...]:
+ found: list[str] = []
+ if singular is not None:
+ item = value.get(singular)
+ if item is not None:
+ if not isinstance(item, str):
+ raise RuntimeError("hy_sdk_write_receipt_shape_invalid")
+ if item:
+ found.append(item)
+ items = value.get(plural)
+ if items is not None:
+ if isinstance(items, (str, bytes)) or not isinstance(items, Sequence):
+ raise RuntimeError("hy_sdk_write_receipt_shape_invalid")
+ for item in items:
+ if not isinstance(item, str):
+ raise RuntimeError("hy_sdk_write_receipt_shape_invalid")
+ if item:
+ found.append(item)
+ return _ordered_unique(found)
+
+
+def _ordered_unique(values: Sequence[str]) -> tuple[str, ...]:
+ return tuple(dict.fromkeys(values))
diff --git a/memhub/apps/core/tests/TEST_INDEX.md b/memhub/apps/core/tests/TEST_INDEX.md
index bb96a00..ee16c08 100644
--- a/memhub/apps/core/tests/TEST_INDEX.md
+++ b/memhub/apps/core/tests/TEST_INDEX.md
@@ -4,7 +4,6 @@
| 测试文件 | 等级 | 一句话说明 |
| --- | --- | --- |
-| `test_active_credentials.py` | `contract` | Active credentials are read once per call, never reused after a refusal. |
| `test_anchor_invalid_rewind.py` | `contract` | Bug 2 real branch: an in-place same-length rewrite invalidates the anchor. |
| `test_architecture_layer_gate.py` | `contract` | A0-01: L0-L4 dependency-direction gate. |
| `test_archive_detection.py` | `contract` | S4.1: what an uploaded export is, decided before anything parses it. |
@@ -91,7 +90,6 @@
| `test_disable_thinking.py` | `contract` | 运行期生成请求须按档案可选关闭思考;默认不向厂商下发未知字段。 |
| `test_dual_engine_helper.py` | `contract` | Tests for the dual-engine harness itself. |
| `test_event_loop_blocking.py` | `contract` | Proof, as a test, that blocking work on the loop freezes it — and the fix works. |
-| `test_evidence_reconcile_primitive.py` | `integration` | A bounded, read-only discovery primitive for the H23 Evidence reconcile. |
| `test_evidence_store.py` | `contract` | 覆盖 same source message merges origins without duplication、identical text from different sources is not deduplicated、rescanning an unchanged file does not write the message again 等 26 个场景。 |
| `test_export_probe.py` | `contract` | What a probe may say about a stranger's chat history, and what it may not. |
| `test_external_installation_permissions.py` | `integration` | 覆盖 external marker is not an installation grant、external diagnostic trace uses its own read only tool、raw source grants filter before limit and private body loading 场景。 |
@@ -103,8 +101,6 @@
| `test_file_import_operations_review.py` | `contract` | Upload refusal/legacy compatibility review with bounded synthetic files only. |
| `test_frozen_core_layout.py` | `contract` | 覆盖 single file layout remains available without private preset、folder layout keeps same core and all native dependencies、unknown layout does not silently build another package 等 5 个场景。 |
| `test_golden_corpus.py` | `contract` | A7-01: the golden corpus comparison. |
-| `test_governance_permission_commit.py` | `contract` | 覆盖 permission guard is rechecked inside write transaction and rolls back、guard context does not leak into subsequent manual actions、guard check and commit hold database write authority 场景。 |
-| `test_governance_read_path_does_not_take_the_writer.py` | `contract` | The recall read path must not acquire the single global writer. |
| `test_graph_width_endpoint.py` | `integration` | The width mismatch has to reach the interface, not just the log. |
| `test_graph_width_export.py` | `unit` | EXPORT_FIRST has to actually export. |
| `test_graph_width_guard.py` | `unit` | Graph width mismatch must ask, never silently archive. |
@@ -115,16 +111,9 @@
| `test_host_capabilities.py` | `unit` | A plugin does not become realtime on every host or every unknown version. |
| `test_hourly_c1_peak_replay_contract.py` | `contract` | Guard the package peak-replay probe's error accounting. |
| `test_hourly_c1_recall_stage_probe_contract.py` | `contract` | Guard the packaged recall stage probe's command and error semantics. |
-| `test_hy_coding_reply.py` | `contract` | R-07: HY's coding-shaped replies read as "no memories at all". |
| `test_hy_log_privacy.py` | `contract` | HY SDK records are not rewritten by One Memory's logging setup. |
-| `test_hy_memory_bridge.py` | `contract` | 覆盖 hy client initialization is serial across bridges、native hy clients share one runtime per data directory、ollama profile ignores ambient remote storage and models 等 41 个场景。 |
-| `test_hy_metrics_lifecycle.py` | `contract` | What the pinned public SDK's MetricsCollector does, and what that costs us. |
| `test_hy_network_egress.py` | `contract` | Where a real HY client is allowed to send bytes, and where it is not. |
-| `test_hy_response_guard.py` | `contract` | 覆盖 invalid response retries same hy provider without changing prompt、repeated empty response fails instead of becoming no op、failure receipt survives a later successful model call 等 23 个场景。 |
-| `test_hy_response_shapes.py` | `contract` | HY response shape selection only; no provider, write routing or model calls. |
| `test_hy_runtime_config.py` | `contract` | MEMORY.md is the audited record of what we send HY; keep it answerable. |
-| `test_hy_sdk_idempotency_probe.py` | `contract` | A0-03: probe whether the HY SDK can make a write idempotent. |
-| `test_hy_source_context.py` | `contract` | 覆盖 bound context rejects a same named conversation in another workspace、bound context rejects a duplicated evidence id、bound context rejects a same conversation from another source 等 9 个场景。 |
| `test_hy_step_trace_switch.py` | `contract` | Rule 15: the per-step HY trace is off unless the debug tier asks for it. |
| `test_import_api.py` | `integration` | 覆盖 resume during cleanup returns conflict without internal error、authorize detect import and revoke api flow、protected api rejects missing token and foreign origin 等 5 个场景。 |
| `test_import_control_races_review.py` | `contract` | Read-only review repro: real runner/store, synthetic delayed adapter cleanup. |
@@ -168,16 +157,11 @@
| `test_memory_batch_extraction.py` | `contract` | 覆盖 batch extractor keeps only unique known evidence ids、batch extractor maps provider failure to machine error 场景。 |
| `test_memory_citation_query_plan.py` | `contract` | Correlated citation checks must look links up by memory, not scan by 'active'. |
| `test_memory_content_import.py` | `integration` | 覆盖 existing memory preview keeps unknown author and exact original、invalid existing memory records never leave a partial upload、memory content requires explicit mode and rejects vendor guessing 等 5 个场景。 |
-| `test_memory_correction_sync.py` | `integration` | R-27: a correction that only lands locally, while HY keeps the old text. |
| `test_memory_evidence_freshness.py` | `contract` | 新鲜度拆除后:读路径恒为 current;证据修订 / 畸形 proof / segment ref 不再藏记忆或 503。 |
| `test_memory_freshness_integration_review.py` | `integration` | Independent synthetic read-path review; no lifespan, model or user database. |
-| `test_memory_governance.py` | `contract` | 覆盖 correction keeps verbatim and appends history、mutations are revision checked and request idempotent、delete result survives restart and request replay 等 42 个场景。 |
| `test_memory_governance_api.py` | `integration` | 覆盖 memory governance api preserves evidence and reports cleanup、memory validation does not echo content 场景。 |
| `test_memory_graph_api.py` | `integration` | 覆盖 graph labels where every edge came from、a created memory is on the map with its source links、drawing the map does not stop the app answering 等 12 个场景。 |
-| `test_memory_language.py` | `contract` | R-03: memory language follows the message, so Kristin's gets written in English. |
| `test_memory_notes.py` | `integration` | 覆盖 empty library can save a note without a matter or configured model、note requires authentication explicit scope and nonempty content、saved note evidence returns raw and consent reference from same record 等 6 个场景。 |
-| `test_memory_processing.py` | `contract` | 覆盖 stale known reason diagnostics never fail dispatch、memory task logs six step durations without content、assistant turns reach hy so references can be resolved 等 95 个场景。 |
-| `test_memory_processing_diagnostics.py` | `contract` | 覆盖 conversation prepare failure includes safe message and stack、deletion sync failure includes safe message and stack 场景。 |
| `test_memory_qa.py` | `contract` | 覆盖 search terms keep meaningful single chinese character、streamed answer emits recall then incremental grounded text、governance change during generation stops the old answer 等 14 个场景。 |
| `test_memory_qa_api.py` | `integration` | 覆盖 ask stream endpoint emits recall deltas and final、ask stream endpoint requires the local token 场景。 |
| `test_memory_qa_permissions.py` | `contract` | 覆盖 initial refusal precedes all secret access and network、invalid authorization result fails before secret access、authorization receives exact question and only outbound grounding 等 16 个场景。 |
@@ -289,7 +273,6 @@
| `test_secret_store_error_code_api.py` | `integration` | 3925a kernel item 3: the error code reaches the HTTP boundary. |
| `test_secret_store_error_codes.py` | `integration` | 3925a kernel item 3: keychain failure classification and backoff that heals. |
| `test_secure_storage.py` | `integration` | 覆盖 isolated keychain service namespace、custom keychain service is refused outside isolated tests、packaged keychain budget covers loaded process startup 等 20 个场景。 |
-| `test_sedimentation_concurrency.py` | `contract` | Sedimentation runs several harnesses at once, but one harness at a time. |
| `test_sedimentation_switch.py` | `contract` | Stopping model-driven sedimentation without losing the configuration. |
| `test_service_level_pressure_acceptance.py` | `contract` | 覆盖 workbuddy recall remains available during 100k import 场景。 |
| `test_service_levels.py` | `contract` | 覆盖 background never consumes the realtime reservation、realtime is next for the same source after background yields、import history gets one slice after nine realtime admissions 等 8 个场景。 |
@@ -320,7 +303,6 @@
| `test_source_sync_idempotent.py` | `integration` | Final-state Harness sync is idempotent and resumes missed source work. |
| `test_source_sync_permissions.py` | `integration` | S1.3 source permission tests use temporary files only, never real host history. |
| `test_source_totals.py` | `contract` | 覆盖 the first ask is answered from the rows、same named sessions in two workspaces count as two conversations、insert during count is not marked as already counted 等 7 个场景。 |
-| `test_source_write_switch.py` | `contract` | A frozen Harness produces no extraction tasks. |
| `test_sql_compat.py` | `contract` | The shared compatibility layer, especially 'rowcount'. |
| `test_sqlite_semantics_gate.py` | `contract` | D56: prevent SQLite implementation details spreading outside the data layer. |
| `test_sqlite_write_contention.py` | `contract` | Measure whether SQLite's single writer actually blocks us. |
@@ -345,4 +327,4 @@
| `test_workspace_recall.py` | `contract` | Workspace memories were unreachable from every host; these pin the way in. |
| `test_write_queue_lease_renewal.py` | `contract` | Rule 8: a lease must outlive the work it covers, and be renewed while it runs. |
-共 340 个测试文件。
+共 322 个测试文件。
diff --git a/memhub/apps/core/tests/core_test_classification.py b/memhub/apps/core/tests/core_test_classification.py
index 71a0cd4..abfb775 100644
--- a/memhub/apps/core/tests/core_test_classification.py
+++ b/memhub/apps/core/tests/core_test_classification.py
@@ -14,8 +14,8 @@ from pathlib import Path
import pytest
PRIMARY_MARKERS = ("unit", "contract", "integration", "performance", "live")
-EXPECTED_TEST_FILE_COUNT = 340
-EXPECTED_TEST_FILES_SHA256 = "f69d3f33df5277febb09557d5bce7adb7d8719ed47e48a71f852e3e4ecf8fd74"
+EXPECTED_TEST_FILE_COUNT = 322
+EXPECTED_TEST_FILES_SHA256 = "d242783adb4015ebdbb5c099f3b5aa88a99c828ca6fddc8ca8d6c74c56e48945"
# Pure transformations, validation models, parity checks and state machines.
# This list is intentionally small: uncertain files default to contract.
@@ -62,7 +62,6 @@ INTEGRATION_FILES = frozenset(
"test_d93_same_process_load.py",
"test_diagnostic_trace.py",
"test_diagnostic_trace_api.py",
- "test_evidence_reconcile_primitive.py",
"test_external_installation_permissions.py",
"test_fault_matrix.py",
"test_file_import_operations.py",
@@ -77,7 +76,6 @@ INTEGRATION_FILES = frozenset(
"test_manual_transcript_import.py",
"test_measure_c1_loop_blocking_contract.py",
"test_memory_content_import.py",
- "test_memory_correction_sync.py",
"test_memory_freshness_integration_review.py",
"test_memory_governance_api.py",
"test_memory_graph_api.py",
diff --git a/memhub/apps/core/tests/graph_fixtures.py b/memhub/apps/core/tests/graph_fixtures.py
new file mode 100644
index 0000000..660922a
--- /dev/null
+++ b/memhub/apps/core/tests/graph_fixtures.py
@@ -0,0 +1,46 @@
+from __future__ import annotations
+
+import gc
+from pathlib import Path
+
+import pytest
+
+from one_memory.model_profiles import ModelProfileSnapshot, ProviderKind
+
+
+def model_snapshot(
+ provider: ProviderKind,
+ *,
+ base_url: str | None,
+ has_api_key: bool,
+ embedding_provider: ProviderKind | None = None,
+ embedding_base_url: str | None = None,
+) -> ModelProfileSnapshot:
+ return ModelProfileSnapshot(
+ profile_id="profile",
+ revision=3,
+ provider_kind=provider,
+ base_url=base_url,
+ model="memory-model",
+ embedding_model="embedding-model",
+ embedding_provider_kind=embedding_provider,
+ embedding_base_url=embedding_base_url,
+ embedding_dimensions=768,
+ timeout_seconds=30,
+ max_concurrency=1,
+ context_window=8192,
+ has_api_key=has_api_key,
+ )
+
+
+def kuzu_graph_with_embedding_width(db_path: Path, width: int) -> None:
+ kuzu = pytest.importorskip("kuzu")
+ database = kuzu.Database(str(db_path))
+ connection = kuzu.Connection(database)
+ connection.execute(
+ f"CREATE NODE TABLE Memory("
+ f"node_id STRING, embedding FLOAT[{width}], PRIMARY KEY(node_id))"
+ )
+ del connection
+ del database
+ gc.collect()
diff --git a/memhub/apps/core/tests/test_active_credentials.py b/memhub/apps/core/tests/test_active_credentials.py
deleted file mode 100644
index d29a627..0000000
--- a/memhub/apps/core/tests/test_active_credentials.py
+++ /dev/null
@@ -1,225 +0,0 @@
-"""Active credentials are read once per call, never reused after a refusal."""
-
-import asyncio
-import threading
-
-import pytest
-from pydantic import SecretStr
-
-from one_memory.background_work import shutdown_bulk_pool
-from one_memory.hy_memory_bridge import HyMemoryBridgeError
-from one_memory.imports.storage import EvidenceStore
-from one_memory.memory_governance import MemoryGovernanceStore
-from one_memory.memory_processing import MemoryProcessingSupervisor
-from one_memory.memory_tasks import MemoryTaskStore
-from one_memory.model_profiles import (
- ModelCapabilities,
- ModelProfileInput,
- ModelProfilePatch,
- ModelProfileStore,
-)
-from one_memory.secrets import InMemorySecretStore, SecretStoreUnavailableError
-
-
-class CountingSecrets(InMemorySecretStore):
- def __init__(self):
- super().__init__()
- self.reads = []
- self.denied = False
- self.after_read = None
-
- def has(self, secret_ref):
- # The OS store's has() resolves the secret; the in-memory default does not.
- return self.resolve(secret_ref) is not None
-
- def resolve(self, secret_ref):
- self.reads.append((secret_ref, threading.get_ident()))
- if self.denied:
- raise SecretStoreUnavailableError("synthetic reader denial, must not leak")
- value = super().resolve(secret_ref)
- callback, self.after_read = self.after_read, None
- if callback is not None:
- callback()
- return value
-
-
-def create_profile(profiles, secrets, *, keyed=True):
- profile = profiles.create(
- ModelProfileInput(
- name="Synthetic credentials",
- provider_kind="openai_compatible" if keyed else "ollama",
- base_url="http://127.0.0.1:1/v1",
- model="synthetic-model",
- api_key=SecretStr("synthetic-credential") if keyed else None,
- ),
- 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,
- )
- return profiles.activate(profile.profile_id, secrets)
-
-
-def setup(tmp_path):
- database = tmp_path / "one-memory.sqlite3"
- secrets = CountingSecrets()
- profiles = ModelProfileStore(database)
- profile = create_profile(profiles, secrets)
- supervisor = MemoryProcessingSupervisor(
- tasks=MemoryTaskStore(database),
- profiles=profiles,
- secrets=secrets,
- evidence=EvidenceStore(database),
- governance=MemoryGovernanceStore(database),
- data_dir=tmp_path,
- )
- secrets.reads.clear()
- try:
- yield supervisor, profiles, secrets, profile
- finally:
- shutdown_bulk_pool()
-
-
-def test_resolves_active_immutable_snapshot_once_off_loop(setup):
- supervisor, profiles, secrets, profile = setup
- expected = profiles.snapshot(profile.profile_id, profile.revision)
- caller = threading.get_ident()
-
- result = asyncio.run(supervisor._active_credentials())
-
- assert result == (expected, "synthetic-credential")
- assert secrets.reads == [(profiles.secret_ref(profile.profile_id), secrets.reads[0][1])]
- assert secrets.reads[0][1] != caller
- assert supervisor.tasks.list() == []
- assert supervisor._bridges == {}
-
-
[email protected]("concurrent", [False, True])
-def test_each_call_resolves_again_without_cross_request_cache(setup, concurrent):
- supervisor, _profiles, secrets, _profile = setup
-
- async def scenario():
- if concurrent:
- return await asyncio.gather(*(supervisor._active_credentials() for _ in range(4)))
- return [await supervisor._active_credentials() for _ in range(4)]
-
- results = asyncio.run(scenario())
-
- assert all(result is not None and result[1] == "synthetic-credential" for result in results)
- assert len(secrets.reads) == 4
-
-
[email protected]("failure", ["missing", "denied"])
-def test_prior_success_cannot_mask_current_reader_refusal(setup, failure):
- supervisor, profiles, secrets, profile = setup
-
- async def scenario():
- assert (await supervisor._active_credentials())[1] == "synthetic-credential"
- secrets.reads.clear()
- if failure == "missing":
- secrets.delete(profiles.secret_ref(profile.profile_id))
- else:
- secrets.denied = True
- code = "model_secret_unavailable" if failure == "missing" else "secure_storage_unavailable"
- with pytest.raises(HyMemoryBridgeError, match=f"^{code}$"):
- await supervisor._active_credentials()
- assert len(secrets.reads) == 1
-
- asyncio.run(scenario())
-
-
[email protected]("change", ["deactivate", "switch", "revision"])
-def test_profile_change_during_secret_read_rejects_old_credentials(setup, change):
- supervisor, profiles, secrets, profile = setup
- other = create_profile(profiles, secrets)
- profiles.activate(profile.profile_id, secrets)
- secrets.reads.clear()
-
- def change_identity():
- # Concurrent committed identity change while the original reader is in flight.
- with profiles._connect(writing=True) as db:
- if change == "revision":
- db.execute(
- "UPDATE model_profiles SET revision=revision+1 WHERE profile_id=?",
- (profile.profile_id,),
- )
- else:
- db.execute("UPDATE model_profiles SET is_active=0")
- if change == "switch":
- db.execute(
- "UPDATE model_profiles SET is_active=1 WHERE profile_id=?",
- (other.profile_id,),
- )
-
- secrets.after_read = change_identity
- with pytest.raises(HyMemoryBridgeError, match="^model_profile_changed$"):
- asyncio.run(supervisor._active_credentials())
- assert len(secrets.reads) == 1
- assert supervisor._bridges == {}
-
-
-def test_rotation_between_calls_returns_new_snapshot_and_secret(setup):
- supervisor, profiles, secrets, profile = setup
- before = asyncio.run(supervisor._active_credentials())
- updated = profiles.update(
- profile.profile_id,
- ModelProfilePatch(expected_revision=profile.revision, api_key=SecretStr("synthetic-new")),
- secrets,
- )
- assert updated.is_active is False
- assert updated.capabilities == ModelCapabilities()
- assert profiles.active_identity() is None
- secrets.reads.clear()
-
- assert asyncio.run(supervisor._active_credentials()) is None
- assert secrets.reads == []
- assert supervisor.tasks.list() == []
- assert supervisor._bridges == {}
-
- # Synthetic probe evidence and explicit activation belong to the new revision.
- profiles.record_capabilities(
- updated.profile_id,
- expected_revision=updated.revision,
- capabilities=profile.capabilities,
- secrets=secrets,
- )
- updated = profiles.activate(updated.profile_id, secrets)
- assert updated.is_active is True
- secrets.reads.clear()
-
- after = asyncio.run(supervisor._active_credentials())
-
- assert before[0].revision == 1 and before[1] == "synthetic-credential"
- assert after == (profiles.snapshot(updated.profile_id, updated.revision), "synthetic-new")
- assert after[0].revision == 2
- assert len(secrets.reads) == 1
-
-
-def test_no_active_profile_does_not_read_credentials(setup):
- supervisor, profiles, secrets, _profile = setup
- with profiles._connect(writing=True) as db:
- db.execute("UPDATE model_profiles SET is_active=0")
-
- assert asyncio.run(supervisor._active_credentials()) is None
- assert secrets.reads == []
-
-
-def test_keyless_profile_does_not_require_or_resolve_a_secret(setup):
- supervisor, profiles, secrets, _profile = setup
- keyless = create_profile(profiles, secrets, keyed=False)
- secrets.reads.clear()
-
- result = asyncio.run(supervisor._active_credentials())
-
- assert result == (profiles.snapshot(keyless.profile_id, keyless.revision), None)
- assert result[0].has_api_key is False
- assert secrets.reads == []
diff --git a/memhub/apps/core/tests/test_architecture_layer_gate.py b/memhub/apps/core/tests/test_architecture_layer_gate.py
index 2561151..0ed06eb 100644
--- a/memhub/apps/core/tests/test_architecture_layer_gate.py
+++ b/memhub/apps/core/tests/test_architecture_layer_gate.py
@@ -4,12 +4,11 @@ The public target architecture is defined by ``docs/ARCHITECTURE.md``:
* Hy Memory SDK owns memory/raw/vector/graph/coding data;
* MemHub owns the management plane and may retain ``memory_id`` references;
-* product code reaches the SDK through ``hy_memory_bridge`` only.
+* product code reaches the SDK only through narrow runtime/migration modules;
+* MemHub calls public ``HyMemoryClient`` methods only.
-The legacy implementation still contains Evidence/Governance writers and a
-small number of private SDK-store accesses. Those are migration debt, not an
-allowance for new code. The explicit debt lists below may shrink during the
-refactor; new entries must not be added.
+The sole exception is the read-only Kuzu projection/admin surface used by the
+existing graph UI and Graph Width workflow.
The gate is deliberately not a blanket ban on ``sqlite3``. Adapters may read a
host product's SQLite through the guarded read-only module; they may not own
@@ -58,13 +57,13 @@ HOST_READONLY_MODULE = "one_memory.imports.sqlite_access"
SRC_ROOT = PACKAGE_ROOT.parents[0]
PACKAGE_LABEL = PACKAGE_ROOT.name
-HY_BRIDGE = f"{PACKAGE_LABEL}/hy_memory_bridge.py"
-
-#: The one module allowed to *invoke* the SDK.
-SDK_CALLER = HY_BRIDGE
-
-#: Type-only importers of HY datatypes; they hold no client and write nothing.
-HY_TYPE_ONLY: frozenset[str] = frozenset()
+SDK_MODULES = frozenset(
+ {
+ f"{PACKAGE_LABEL}/hy_sdk_runtime.py",
+ f"{PACKAGE_LABEL}/hy_sdk_migration.py",
+ }
+)
+SDK_CLIENT_CONSTRUCTOR = f"{PACKAGE_LABEL}/hy_sdk_runtime.py"
# Frozen migration debt: modules that still write the legacy memory/raw
# authority. The target count is zero. A new module cannot join this set.
@@ -84,19 +83,31 @@ LEGACY_AUTHORITY_WRITE = re.compile(
re.IGNORECASE,
)
-# Existing accesses to SDK implementation details. These are exact file /
-# attribute debts so deleting one is always green, while adding one fails.
-SDK_PRIVATE_ACCESS_DEBT: dict[str, frozenset[str]] = {
- f"{PACKAGE_LABEL}/hy_lifecycle.py": frozenset({"_collection", "_vector_store"}),
- f"{PACKAGE_LABEL}/hy_memory_bridge.py": frozenset(
- {"_coding_store", "_graph_store", "_loop_thread", "_vector_store"}
- ),
- f"{PACKAGE_LABEL}/hy_response_guard.py": frozenset({"_loop_thread", "_registry"}),
-}
-
SDK_PRIVATE_ATTRIBUTES = frozenset(
- attribute for attributes in SDK_PRIVATE_ACCESS_DEBT.values() for attribute in attributes
+ {
+ "_coding_store",
+ "_coding_stores",
+ "_collection",
+ "_embed_service",
+ "_graph_store",
+ "_loop_thread",
+ "_readers",
+ "_reader",
+ "_reconciler",
+ "_registry",
+ "_run",
+ "_shared_embed_service",
+ "_spawn_search_dedup",
+ "_system2_writer",
+ "_vector_store",
+ "_writer",
+ }
)
+SDK_PRIVATE_ACCESS_EXCEPTIONS = {
+ f"{PACKAGE_LABEL}/hy_graph_projection.py": frozenset(
+ {"_graph_store", "_loop_thread", "_run"}
+ ),
+}
def _relative(path: Path) -> str:
@@ -171,49 +182,26 @@ def test_adapters_use_only_the_readonly_host_sqlite_module() -> None:
)
-def test_hy_sdk_is_confined_to_the_l1_adapter() -> None:
- """A0-01: HY SDK stays behind HyMemoryPort; entries must not import it.
-
- This is the executable form of "Function/MCP/scan/Hook must not call the
- HY SDK directly". `hy_memory_bridge` is the current L1 adapter and the
- permission stores quote HY types, so they are the allowed set; anything
- else reaching for the SDK is a new bypass and must fail here.
-
- Only `hy_memory_bridge` *calls* the SDK. The two permission stores merely
- import HY datatypes (`CodingMemory`, `WorkingFact`, memory models) to type
- what they persist; they hold no client and issue no writes. They are
- listed here so the gate stays green on today's truth while still failing
- on any new module that reaches for the SDK.
- """
- allowed = frozenset({HY_BRIDGE}) | HY_TYPE_ONLY
+def test_hy_sdk_is_confined_to_public_sdk_modules() -> None:
+ """Only the runtime and offline migration adapters may import the SDK."""
offenders: list[str] = []
for path in _all_module_files():
relative = _relative(path)
- if relative in allowed:
+ tree = ast.parse(path.read_text(encoding="utf-8"))
+ names = _module_names(tree)
+ if not any(_root(name) in HY_SDK_ROOTS for name in names):
continue
- names = _module_names(ast.parse(path.read_text(encoding="utf-8")))
- if any(_root(name) in HY_SDK_ROOTS for name in names):
+ if relative not in SDK_MODULES:
offenders.append(relative)
- assert not offenders, f"HY SDK must stay in the L1 adapter: {offenders}"
+ assert not offenders, f"HY SDK imports must stay in {sorted(SDK_MODULES)}: {offenders}"
-def test_only_the_l1_adapter_constructs_a_hy_client() -> None:
- """A0-01: type-only imports are tolerated; constructing a client is not.
-
- A permission store quoting `CodingMemory` cannot write a memory. A module
- that instantiates `HyMemoryClient` can. So the stricter check is on client
- construction, and it must pass today rather than merely documenting an
- aspiration.
-
- The check is on the AST, not on the substring: a docstring or comment that
- *mentions* `HyMemoryClient` builds nothing. Matching text would flag prose
- and, worse, would keep passing while a real caller is added inside a
- function the text search happened to like.
- """
+def test_only_runtime_constructs_a_hy_client() -> None:
+ """Migration borrows a lease; only runtime constructs clients."""
offenders: list[str] = []
for path in _all_module_files():
relative = _relative(path)
- if relative == SDK_CALLER:
+ if relative == SDK_CLIENT_CONSTRUCTOR:
continue
tree = ast.parse(path.read_text(encoding="utf-8"))
for node in ast.walk(tree):
@@ -233,7 +221,7 @@ def test_only_the_l1_adapter_constructs_a_hy_client() -> None:
if any(alias.name == "HyMemoryClient" for alias in node.names):
offenders.append(relative)
break
- assert not offenders, f"only the L1 adapter may build a HY client: {offenders}"
+ assert not offenders, f"only {SDK_CLIENT_CONSTRUCTOR} may build a HY client: {offenders}"
def test_no_new_module_writes_legacy_memory_authority() -> None:
@@ -247,39 +235,86 @@ def test_no_new_module_writes_legacy_memory_authority() -> None:
if relative not in LEGACY_AUTHORITY_WRITERS:
offenders.append(relative)
assert not offenders, (
- "new Evidence/Governance writers are forbidden; write memory/raw via "
- f"the SDK bridge instead: {offenders}"
+ "new Evidence/Governance writers are forbidden; use public SDK client "
+ f"methods instead: {offenders}"
)
-def test_no_new_sdk_private_store_access() -> None:
- """Freeze direct SDK-store access until public client APIs replace it."""
+def test_no_sdk_private_implementation_access() -> None:
+ """No debt allowlist: MemHub calls public client methods only."""
offenders: list[str] = []
for path in _all_module_files():
tree = ast.parse(path.read_text(encoding="utf-8"))
relative = _relative(path)
- names = _module_names(tree)
- if relative not in SDK_PRIVATE_ACCESS_DEBT and not any(
- _root(name) in HY_SDK_ROOTS for name in names
- ):
- # Names such as `_registry` and `_collection` are common for
- # MemHub-owned objects too. They become SDK-private access only
- # in a module that imports the SDK (or is frozen debt already).
- continue
used = {
node.attr
for node in ast.walk(tree)
- if isinstance(node, ast.Attribute) and node.attr in SDK_PRIVATE_ATTRIBUTES
+ if isinstance(node, ast.Attribute)
+ and node.attr in SDK_PRIVATE_ATTRIBUTES
+ and (
+ relative.startswith(f"{PACKAGE_LABEL}/hy_")
+ or (
+ isinstance(node.value, ast.Name)
+ and node.value.id in {"client", "native", "concrete"}
+ )
+ )
}
- if not used:
- continue
- unexpected = sorted(used - SDK_PRIVATE_ACCESS_DEBT.get(relative, frozenset()))
- if unexpected:
- offenders.append(f"{relative}: {unexpected}")
+ if used:
+ unexpected = used - SDK_PRIVATE_ACCESS_EXCEPTIONS.get(
+ relative, frozenset()
+ )
+ if unexpected:
+ offenders.append(f"{relative}: {sorted(unexpected)}")
assert not offenders, (
- "new SDK private-store access is forbidden; add a public HyMemoryClient "
- f"API and call it through hy_memory_bridge: {offenders}"
+ "SDK private implementation access is forbidden; add a public "
+ f"HyMemoryClient API instead: {offenders}"
+ )
+
+
+def test_sdk_modules_import_only_the_public_package_root() -> None:
+ """Implementation submodules are not a public product contract."""
+ offenders: list[str] = []
+ for path in _all_module_files():
+ relative = _relative(path)
+ tree = ast.parse(path.read_text(encoding="utf-8"))
+ for node in ast.walk(tree):
+ if isinstance(node, ast.Import) and any(
+ alias.name.startswith("hy_memory.") for alias in node.names
+ ):
+ offenders.append(relative)
+ break
+ if isinstance(node, ast.ImportFrom) and (
+ node.module or ""
+ ).startswith("hy_memory."):
+ offenders.append(relative)
+ break
+ if (
+ isinstance(node, ast.Call)
+ and isinstance(node.func, ast.Name)
+ and node.func.id == "import_module"
+ and node.args
+ and isinstance(node.args[0], ast.Constant)
+ and isinstance(node.args[0].value, str)
+ and node.args[0].value.startswith("hy_memory.")
+ ):
+ offenders.append(relative)
+ break
+ assert not offenders, f"import SDK symbols from `hy_memory` only: {offenders}"
+
+
+def test_memhub_never_patches_sdk_prompts() -> None:
+ offenders: list[str] = []
+ forbidden = (
+ "extract_system_prompt_en",
+ "extract_system_prompt_zh",
+ "hy_memory.agent.prompts",
)
+ for path in _all_module_files():
+ source = path.read_text(encoding="utf-8")
+ hits = [token for token in forbidden if token in source]
+ if hits:
+ offenders.append(f"{_relative(path)}: {hits}")
+ assert not offenders, f"SDK prompt patching is forbidden: {offenders}"
@pytest.mark.parametrize("driver", sorted(MEMHUB_DRIVERS))
diff --git a/memhub/apps/core/tests/test_cli_restore.py b/memhub/apps/core/tests/test_cli_restore.py
index 2a42c44..a1aa3b7 100644
--- a/memhub/apps/core/tests/test_cli_restore.py
+++ b/memhub/apps/core/tests/test_cli_restore.py
@@ -301,11 +301,10 @@ def test_sdk_migrate_runs_offline_backfill_without_cutover(tmp_path, monkeypatch
class Secrets:
pass
- class Bridge:
- def __init__(self, **_kwargs):
- pass
+ class Lease:
+ client = object()
- async def close(self):
+ def close(self):
return None
async def backfill(**_kwargs):
@@ -320,7 +319,10 @@ def test_sdk_migrate_runs_offline_backfill_without_cutover(tmp_path, monkeypatch
monkeypatch.setattr("one_memory.model_profiles.ModelProfileStore", Profiles)
monkeypatch.setattr("one_memory.secrets.KeyringSecretStore", Secrets)
- monkeypatch.setattr("one_memory.hy_memory_bridge.HyMemoryBridge", Bridge)
+ monkeypatch.setattr(
+ "one_memory.hy_sdk_runtime.acquire_client",
+ lambda *_args, **_kwargs: Lease(),
+ )
monkeypatch.setattr(
"one_memory.sdk_migration_runner.run_sdk_data_plane_backfill",
backfill,
diff --git a/memhub/apps/core/tests/test_contract_parity.py b/memhub/apps/core/tests/test_contract_parity.py
index d9383b4..17128fa 100644
--- a/memhub/apps/core/tests/test_contract_parity.py
+++ b/memhub/apps/core/tests/test_contract_parity.py
@@ -50,21 +50,3 @@ def test_governed_memory_carries_the_same_fields_on_both_sides() -> None:
}
assert typescript == set(GovernedMemory.model_fields)
-
-
-def test_an_agent_owned_memory_is_usable_and_never_passes_as_the_person(tmp_path) -> None:
- """助手输出里的事实直接可用,但始终标成助手说的。
-
- 召回读到它时,origin 让别的 AI 应用知道这是模型的陈述、不是本人的判决。
- 已有的同内容记忆,也不会被模型输出改掉来源标记。
- """
- from tests.test_memory_processing import (
- test_agent_output_keeps_the_origin_of_a_same_content_memory,
- test_agent_owned_memories_land_usable_but_marked_as_the_assistant,
- )
-
- created, existing = tmp_path / "created", tmp_path / "existing"
- created.mkdir()
- existing.mkdir()
- test_agent_owned_memories_land_usable_but_marked_as_the_assistant(created)
- test_agent_output_keeps_the_origin_of_a_same_content_memory(existing, MemoryOrigin.AGENT)
diff --git a/memhub/apps/core/tests/test_conversation_search.py b/memhub/apps/core/tests/test_conversation_search.py
index e3f29d2..68a7eb8 100644
--- a/memhub/apps/core/tests/test_conversation_search.py
+++ b/memhub/apps/core/tests/test_conversation_search.py
@@ -1,10 +1,8 @@
"""Searching imported conversations before any generation model is configured.
This search is literal, not semantic, and that is a correction rather than a
-shortcut. The vector store `semantic_search` reads is written only by
-extraction (`memory_processing.py` EXTRACT tasks), and extraction is precisely
-what a user without a generation model does not have: their store is empty, so
-a semantic path would return nothing no matter how it was wired.
+shortcut. Literal conversation search must remain available before a model is
+configured and independently of SDK semantic-memory extraction.
"""
import sqlite3
diff --git a/memhub/apps/core/tests/test_conversation_turn_grouping.py b/memhub/apps/core/tests/test_conversation_turn_grouping.py
index 1914c7b..7b492d5 100644
--- a/memhub/apps/core/tests/test_conversation_turn_grouping.py
+++ b/memhub/apps/core/tests/test_conversation_turn_grouping.py
@@ -4,9 +4,9 @@ from __future__ import annotations
from datetime import UTC, datetime
+from one_memory.conversation_processing import _conversation_chunks
from one_memory.imports.models import EvidenceInput, EvidenceOrigin, OriginMetadata, WrittenBy
from one_memory.imports.storage import EvidenceStore
-from one_memory.memory_processing import _conversation_chunks
def _records(tmp_path, *speakers: tuple[str, str, str]) -> list:
diff --git a/memhub/apps/core/tests/test_credential_responsiveness.py b/memhub/apps/core/tests/test_credential_responsiveness.py
index 23da34e..73265d8 100644
--- a/memhub/apps/core/tests/test_credential_responsiveness.py
+++ b/memhub/apps/core/tests/test_credential_responsiveness.py
@@ -1,58 +1,16 @@
import asyncio
import threading
-import time
import httpx
import pytest
from test_memory_qa import _grounded_setup, _ndjson_stream
-from test_onboarding_profile import FakeGraph, _app, _client, _setup, _supervisor
+from test_onboarding_profile import _app, _client
from one_memory.memory_qa import MemoryAnswerer
from one_memory.model_probe import ModelProber
from one_memory.secrets import SecretStoreUnavailableError
- "operation,args",
- [
- ("digest", ()),
- ("graph_snapshot", ()),
- ("graph_width_mismatch", ()),
- ("semantic_search", ("example",)),
- ("update_hy_memory", ("id", "corrected")),
- ("delete_hy_memory", ("id",)),
- ("decide_graph_width", ("keep_existing",)),
- ],
-)
[email protected]("phase", ["active", "secret"])
-def test_credentials_do_not_block_the_event_loop(tmp_path, monkeypatch, operation, args, phase):
- stores = _setup(tmp_path)
- supervisor = _supervisor(tmp_path, stores, FakeGraph(()))
- method = "active_identity" if phase == "active" else "resolve_snapshot_secret"
- original = getattr(supervisor.profiles, method)
- called = threading.Event()
-
- def waiting(*args, **kwargs):
- called.set()
- time.sleep(0.25)
- return original(*args, **kwargs)
-
- monkeypatch.setattr(supervisor.profiles, method, waiting)
-
- async def scenario():
- task = asyncio.create_task(getattr(supervisor, operation)(*args))
- started = time.monotonic()
- await asyncio.sleep(0.04)
- elapsed = time.monotonic() - started
- # Some graph operations have no fake implementation; those exceptions
- # are irrelevant to whether a credential read stops the event loop.
- await asyncio.gather(task, return_exceptions=True)
- assert called.is_set()
- assert elapsed < 0.18, f"Credential wait blocked the loop for {elapsed:.3f}s"
-
- asyncio.run(scenario())
-
-
def test_disabled_automatic_processing_does_not_digest_onboarding(tmp_path):
async def scenario():
app = _app(tmp_path)
@@ -64,7 +22,7 @@ def test_disabled_automatic_processing_does_not_digest_onboarding(tmp_path):
calls.append(True)
return {}
- app.state.memory_processing_supervisor.digest = digest
+ app.state.sdk_memory_runtime.digest = digest
response = await client.post("/api/v1/onboarding/complete")
assert response.status_code == 200
assert calls == []
diff --git a/memhub/apps/core/tests/test_detailed_logging.py b/memhub/apps/core/tests/test_detailed_logging.py
index c095b51..ead55c3 100644
--- a/memhub/apps/core/tests/test_detailed_logging.py
+++ b/memhub/apps/core/tests/test_detailed_logging.py
@@ -35,7 +35,7 @@ def test_live_log_level_applies_to_full_hy_and_provider_call_chain(
set_diagnostic_log_level(tmp_path, "debug")
assert diagnostic_log_level(tmp_path) == "debug"
- assert logging.getLogger("one_memory.memory_processing").isEnabledFor(logging.DEBUG)
+ assert logging.getLogger("one_memory.sdk_write_processor").isEnabledFor(logging.DEBUG)
assert logging.getLogger("hy_memory.runtime").isEnabledFor(logging.DEBUG)
assert logging.getLogger("hy_memory.client").isEnabledFor(logging.DEBUG)
assert logging.getLogger("hy_memory.agent.llm_provider").isEnabledFor(logging.DEBUG)
diff --git a/memhub/apps/core/tests/test_evidence_reconcile_primitive.py b/memhub/apps/core/tests/test_evidence_reconcile_primitive.py
deleted file mode 100644
index 35677e8..0000000
--- a/memhub/apps/core/tests/test_evidence_reconcile_primitive.py
+++ /dev/null
@@ -1,400 +0,0 @@
-"""A bounded, read-only discovery primitive for the H23 Evidence reconcile.
-
-The objective's crash requirement is "a committed Evidence row must not be
-lost". The two-step `Evidence write -> queue/task submit` window can leave a
-row with no write entry. C0 scheduled that reconcile for H23 and asked C2 to
-supply the primitive; this module pins the discovery half, which is pure
-database infrastructure and does not choose the product's grouping semantics.
-"""
-
-from __future__ import annotations
-
-import sqlite3
-from datetime import UTC, datetime
-from pathlib import Path
-
-import pytest
-
-from one_memory.imports.models import (
- EvidenceInput,
- EvidenceOrigin,
- OriginMetadata,
- WrittenBy,
-)
-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,
- ReconcileSchemaUnavailableError,
-)
-
-
-def _put(store: EvidenceStore, message_id: str) -> str:
- return store.put(
- EvidenceInput(
- source_id="s1",
- conversation_id="c1",
- message_id=message_id,
- role="user",
- written_by=WrittenBy.PERSON,
- verbatim=f"body {message_id}",
- created_at=datetime.now(UTC),
- origin_meta={EvidenceOrigin.FILE: OriginMetadata()},
- )
- ).record.evidence_id
-
-
-def test_unsubmitted_evidence_finds_rows_with_no_write_entry(tmp_path) -> None:
- path = tmp_path / "one-memory.sqlite3"
- store = EvidenceStore(path)
- queue = DurableWriteQueue(path)
- submitted = _put(store, "m1")
- orphan = _put(store, "m2")
- queue.submit(
- WriteRequest(
- internal_session_id="c1",
- batch_identity=BatchIdentity(internal_session_id="c1", first_round=1, last_round=1),
- evidence_ids=[submitted],
- idempotency_key="idem-1",
- )
- )
-
- found = queue.unsubmitted_evidence_ids(limit=10)
-
- assert found == (orphan,)
-
-
-def test_reconcile_refuses_when_the_evidence_schema_is_not_migrated(tmp_path) -> None:
- """A queue-only database is not an empty reconcile result.
-
- Returning `()` here would make a pre-migration database look as if every
- trusted Evidence row were already queued. The caller needs a distinct
- retryable state so it can run migration first.
- """
- path = tmp_path / "one-memory.sqlite3"
- queue = DurableWriteQueue(path)
-
- with pytest.raises(ReconcileSchemaUnavailableError, match="run migrations"):
- queue.unsubmitted_evidence_ids()
-
-
-def test_unsubmitted_evidence_is_bounded_and_resumable(tmp_path) -> None:
- """The cursor must be stable and bounded so a startup pass is cheap.
-
- `after_cursor` is the last id a previous page returned; the next call
- resumes strictly after it. In this serial fixture the pages partition the
- backlog once. The primitive is not a cross-call transaction snapshot; a
- concurrent insert or submit is tolerated by the Evidence-derived
- idempotency key, not by pretending the read itself is isolated.
- """
- path = tmp_path / "one-memory.sqlite3"
- store = EvidenceStore(path)
- queue = DurableWriteQueue(path)
- ids = [_put(store, f"m{index}") for index in range(3)]
-
- first = queue.unsubmitted_evidence_ids(limit=2)
- second = queue.unsubmitted_evidence_ids(limit=2, after_cursor=first[-1])
-
- assert first == (ids[0], ids[1])
- assert second == (ids[2],)
-
-
-def test_unsubmitted_evidence_refuses_a_missing_cursor(tmp_path) -> None:
- """A vanished cursor must not silently reset pagination to page one.
-
- Replaying a prefix may be harmless only because the idempotency key exists;
- the discovery contract itself must fail closed. A caller that deleted the
- anchor or restored an older database must restart from a fresh scan, not
- have the primitive quietly change its place.
- """
- path = tmp_path / "one-memory.sqlite3"
- store = EvidenceStore(path)
- queue = DurableWriteQueue(path)
- first = _put(store, "m1")
- second = _put(store, "m2")
-
- first_page = queue.unsubmitted_evidence_ids(limit=1)
- assert first_page == (first,)
- with sqlite3.connect(path) as connection, connection:
- connection.execute("DELETE FROM evidence_origins WHERE evidence_id=?", (first,))
- connection.execute("DELETE FROM evidence WHERE evidence_id=?", (first,))
-
- with pytest.raises(RuntimeError, match="cursor is unavailable"):
- queue.unsubmitted_evidence_ids(limit=10, after_cursor=first)
-
- # A deliberate fresh pass still sees the remaining orphan.
- assert queue.unsubmitted_evidence_ids(limit=10) == (second,)
-
-
-def test_unsubmitted_evidence_query_uses_the_reference_index(tmp_path) -> None:
- """The anti-join must not scan every queue payload.
-
- At production scale the queue can keep many terminal rows, so discovery
- uses a dedicated Evidence reference and an indexed `NOT EXISTS` join
- instead of loading every job's payload or reference JSON.
- """
- from one_memory.database_access import main_database
- from one_memory.memory_server.migrations import memory_write_jobs_sqlite_schema
-
- path = tmp_path / "one-memory.sqlite3"
- with main_database(path).write(autocommit=True) as connection, connection:
- connection.execute(
- "CREATE TABLE evidence (evidence_id TEXT PRIMARY KEY, imported_at TEXT NOT NULL)"
- )
- connection.execute(
- "CREATE INDEX evidence_imported_order ON evidence(imported_at, evidence_id)"
- )
- for statement in memory_write_jobs_sqlite_schema():
- connection.execute(statement)
- plan = [
- str(row[3])
- for row in connection.execute(
- "EXPLAIN QUERY PLAN SELECT evidence.evidence_id FROM evidence "
- "WHERE evidence.imported_at IS NOT NULL "
- "AND NOT EXISTS (SELECT 1 FROM memory_write_job_evidence ref "
- "WHERE ref.evidence_id=evidence.evidence_id) "
- "ORDER BY evidence.imported_at, evidence.evidence_id LIMIT ?",
- (512,),
- )
- ]
-
- joined = " | ".join(plan)
- assert "idx_write_job_evidence_evidence" in joined
- assert "SCAN memory_write_jobs" not in joined
- assert "SCAN ref" not in joined
-
-
-def test_the_shipped_schema_serves_the_reconcile_order(tmp_path) -> None:
- """The real schema must not scan+sort Evidence on every discovery page.
-
- `unsubmitted_evidence_ids` orders by `(imported_at, evidence_id)` with no
- `user_id` predicate, so `evidence_imported_index` (leading column
- `user_id`) cannot serve it. Before the reconcile-order index the real plan
- was `SCAN evidence` + `USE TEMP B-TREE FOR ORDER BY`; a pass over a large
- corpus paid that on every page. This pins the shipped schema, not a
- test-local index, so a regression to the old DDL fails here.
- """
- import asyncio
-
- from one_memory.database_access import main_database
- from one_memory.memory_server.migration_runner import SqliteMigrationStore, migrate
- from one_memory.memory_server.migrations import MIGRATIONS
-
- path = tmp_path / "one-memory.sqlite3"
- asyncio.run(migrate(SqliteMigrationStore(path), MIGRATIONS))
-
- with main_database(path).read() as connection:
- plan = [
- str(row[3])
- for row in connection.execute(
- "EXPLAIN QUERY PLAN SELECT evidence.evidence_id FROM evidence "
- "WHERE evidence.imported_at IS NOT NULL "
- "AND NOT EXISTS (SELECT 1 FROM memory_write_job_evidence ref "
- "WHERE ref.evidence_id=evidence.evidence_id) "
- "ORDER BY evidence.imported_at, evidence.evidence_id LIMIT ?",
- (512,),
- )
- ]
-
- joined = " | ".join(plan)
- assert "evidence_reconcile_order" in joined, joined
- assert "USE TEMP B-TREE FOR ORDER BY" not in joined, joined
- # SQLite reports an in-order covering-index walk as `SCAN evidence USING
- # COVERING INDEX ...`; the failure mode we forbid is a bare table scan with
- # a temp sort, so require the index to be named and the sort to be gone.
- assert "USING COVERING INDEX evidence_reconcile_order" in joined, joined
-
-
-def test_unsubmitted_evidence_returns_empty_when_all_are_queued(tmp_path) -> None:
- path = tmp_path / "one-memory.sqlite3"
- store = EvidenceStore(path)
- queue = DurableWriteQueue(path)
- evidence_id = _put(store, "m1")
- queue.submit(
- WriteRequest(
- internal_session_id="c1",
- batch_identity=BatchIdentity(internal_session_id="c1", first_round=1, last_round=1),
- evidence_ids=[evidence_id],
- idempotency_key="idem-1",
- )
- )
-
- assert queue.unsubmitted_evidence_ids(limit=10) == ()
-
-
[email protected]("limit", [0, -1, True, 1.5, "10"])
-def test_unsubmitted_evidence_rejects_an_invalid_limit(tmp_path, limit: object) -> None:
- queue = DurableWriteQueue(tmp_path / "one-memory.sqlite3")
- with pytest.raises(ValueError, match="limit must be positive"):
- queue.unsubmitted_evidence_ids(limit=limit) # type: ignore[arg-type]
-
-
[email protected]("cursor", ["", 1, True, ["evidence-id"], object()])
-def test_unsubmitted_evidence_rejects_an_invalid_cursor(tmp_path, cursor: object) -> None:
- """A malformed cursor must fail with the public contract, not SQL errors.
-
- ``after_cursor`` crosses an API/worker boundary and is allowed to be
- absent, but every present value must be a non-empty evidence id. Passing
- a list/object into the lookup produced a raw SQLite binding error; an
- empty string performed a pointless lookup and then reported a missing
- cursor as if the database had lost a real row. The primitive should
- reject the caller's input before touching SQL.
- """
- path = tmp_path / "one-memory.sqlite3"
- with sqlite3.connect(path) as connection, connection:
- connection.execute(
- "CREATE TABLE evidence (evidence_id TEXT PRIMARY KEY, imported_at TEXT NOT NULL)"
- )
- queue = DurableWriteQueue(path)
-
- with pytest.raises(ValueError, match="after_cursor must be a non-empty string"):
- queue.unsubmitted_evidence_ids(after_cursor=cursor) # type: ignore[arg-type]
-
-
-def test_a_reconcile_pass_enqueues_an_orphan_exactly_once(tmp_path) -> None:
- """The acceptance's "enqueue once" half, on the C2-owned primitives.
-
- A crash between Evidence commit and submit leaves an orphan. The reconcile
- flow is: discover it, then submit a write with a stable idempotency key
- derived from the Evidence identity. A second pass must find nothing (the
- row now references it) and must not create a duplicate — the same
- idempotency key would in any case return the existing job.
- """
- path = tmp_path / "one-memory.sqlite3"
- store = EvidenceStore(path)
- queue = DurableWriteQueue(path)
- orphan = _put(store, "m1") # evidence committed, no submit -> the crash window
-
- def reconcile_once() -> str | None:
- ids = queue.unsubmitted_evidence_ids(limit=64)
- if not ids:
- return None
- first = ids[0]
- record = queue.submit(
- WriteRequest(
- internal_session_id="c1",
- batch_identity=BatchIdentity(internal_session_id="c1", first_round=1, last_round=1),
- evidence_ids=[first],
- # Derived from the Evidence identity: a replay re-derives the
- # same key, so the queue refuses to create a second job.
- idempotency_key=f"reconcile:{first}",
- )
- )
- return record.job_id
-
- first_job = reconcile_once()
- assert first_job is not None
-
- # Second pass: the orphan is gone, and a forced replay is idempotent.
- assert queue.unsubmitted_evidence_ids(limit=64) == ()
- replay = queue.submit(
- WriteRequest(
- internal_session_id="c1",
- batch_identity=BatchIdentity(internal_session_id="c1", first_round=1, last_round=1),
- evidence_ids=[orphan],
- idempotency_key=f"reconcile:{orphan}",
- )
- )
- assert replay.job_id == first_job
- assert replay.enqueued is False
- with sqlite3.connect(path) as connection:
- assert connection.execute("SELECT COUNT(*) FROM memory_write_jobs").fetchone()[0] == 1
-
-
-def test_two_reconcile_workers_submit_the_same_orphan_once(tmp_path) -> None:
- """A restart and a periodic pass may race; the derived key is the arbiter.
-
- The discovery cursor cannot promise a cross-call snapshot, so two workers
- can both observe the same orphan. They must not create two jobs:
- `reconcile:<evidence_id>` is derived from the Evidence identity and the
- queue's UNIQUE idempotency key makes the second submit an idempotent replay.
- """
- path = tmp_path / "one-memory.sqlite3"
- store = EvidenceStore(path)
- DurableWriteQueue(path)
- orphan = _put(store, "m1")
-
- def reconcile_worker() -> str:
- request = WriteRequest(
- internal_session_id="c1",
- batch_identity=BatchIdentity(internal_session_id="c1", first_round=1, last_round=1),
- evidence_ids=[orphan],
- idempotency_key=f"reconcile:{orphan}",
- )
- return DurableWriteQueue(path).submit(request).job_id
-
- first = reconcile_worker()
- second = reconcile_worker()
-
- assert first == second
- with sqlite3.connect(path) as connection:
- assert connection.execute("SELECT COUNT(*) FROM memory_write_jobs").fetchone()[0] == 1
- assert (
- connection.execute(
- "SELECT COUNT(*) FROM memory_write_job_evidence WHERE evidence_id=?",
- (orphan,),
- ).fetchone()[0]
- == 1
- )
-
-
-def test_a_sigkill_before_submit_leaves_an_orphan_the_primitive_recovers(tmp_path) -> None:
- """Real process crash between Evidence commit and submit (objective 4.1-4.2).
-
- The child writes Evidence and is SIGKILLed before it can submit the write.
- No task/queue row exists, so only a *discovery over committed rows* can find
- it. This is the boundary the C1 file-level drain does not cover for manual
- notes; the primitive + derived key then enqueue it exactly once.
- """
- import os
- import signal
- import subprocess
- import sys
-
- if sys.platform == "win32":
- pytest.skip("POSIX process-kill recovery")
-
- path = tmp_path / "one-memory.sqlite3"
- EvidenceStore(path)
- child = (
- "import time\n"
- "from datetime import UTC, datetime\n"
- "from pathlib import Path\n"
- "from one_memory.imports.models import ("
- "EvidenceInput, EvidenceOrigin, OriginMetadata, WrittenBy)\n"
- "from one_memory.imports.storage import EvidenceStore\n"
- "path = Path(" + repr(str(path)) + ")\n"
- "store = EvidenceStore(path)\n"
- "store.put(EvidenceInput(source_id='s1', conversation_id='c1', message_id='m1',\n"
- " role='user', written_by=WrittenBy.PERSON, verbatim='orphan',\n"
- " created_at=datetime.now(UTC), origin_meta={EvidenceOrigin.FILE: OriginMetadata()}))\n"
- "print('written', flush=True)\n"
- "time.sleep(60)\n"
- )
- process = subprocess.Popen(
- [sys.executable, "-c", child],
- stdout=subprocess.PIPE,
- stderr=subprocess.PIPE,
- text=True,
- cwd=str(Path(__file__).resolve().parents[1]),
- env={**os.environ, "PYTHONPATH": str(Path(__file__).resolve().parents[1] / "src")},
- )
- assert process.stdout is not None
- assert process.stdout.readline().strip() == "written"
- os.kill(process.pid, signal.SIGKILL)
- process.wait(timeout=10)
-
- queue = DurableWriteQueue(path)
- ids = queue.unsubmitted_evidence_ids(limit=10)
- assert len(ids) == 1, "the committed Evidence must be discoverable after the crash"
- queue.submit(
- WriteRequest(
- internal_session_id="c1",
- batch_identity=BatchIdentity(internal_session_id="c1", first_round=1, last_round=1),
- evidence_ids=[ids[0]],
- idempotency_key=f"reconcile:{ids[0]}",
- )
- )
- assert queue.unsubmitted_evidence_ids(limit=10) == ()
- with sqlite3.connect(path) as connection:
- assert connection.execute("SELECT COUNT(*) FROM memory_write_jobs").fetchone()[0] == 1
diff --git a/memhub/apps/core/tests/test_governance_permission_commit.py b/memhub/apps/core/tests/test_governance_permission_commit.py
deleted file mode 100644
index dfc4820..0000000
--- a/memhub/apps/core/tests/test_governance_permission_commit.py
+++ /dev/null
@@ -1,131 +0,0 @@
-import sqlite3
-
-import pytest
-
-from one_memory.imports.models import EvidenceInput, EvidenceOrigin, OriginMetadata, WrittenBy
-from one_memory.imports.storage import EvidenceStore
-from one_memory.memory_governance import MemoryDraft, MemoryGovernanceStore, MemoryKind
-from tests.person_door import as_person
-
-
-def test_permission_guard_is_rechecked_inside_write_transaction_and_rolls_back(tmp_path):
- database = tmp_path / "test.sqlite"
- evidence = EvidenceStore(database)
- original = evidence.put(
- EvidenceInput(
- source_id="fixture",
- conversation_id="one",
- message_id="one",
- role="user",
- written_by=WrittenBy.PERSON,
- verbatim="synthetic",
- origin_meta={EvidenceOrigin.FILE: OriginMetadata()},
- )
- ).record
- store = MemoryGovernanceStore(database)
- attempts = []
-
- def guard():
- attempts.append("check")
- if len(attempts) == 2:
- raise RuntimeError("permission revoked before commit")
-
- with pytest.raises(RuntimeError, match="revoked before commit"), store.guard_writes(guard):
- as_person(store).create(
- MemoryDraft(
- user_id="local",
- kind=MemoryKind.CHAT,
- content="synthetic result",
- evidence_ids=(original.evidence_id,),
- scopes=("all-apps",),
- ),
- request_id="attempt",
- )
- assert attempts == ["check", "check"]
- assert store.list(user_id="local") == []
- with sqlite3.connect(database) as db:
- assert db.execute("SELECT count(*) FROM governed_memory_mutations").fetchone()[0] == 0
-
-
-def test_guard_context_does_not_leak_into_subsequent_manual_actions(tmp_path):
- database = tmp_path / "test.sqlite"
- evidence = EvidenceStore(database)
- original = evidence.put(
- EvidenceInput(
- source_id="fixture",
- conversation_id="one",
- message_id="one",
- role="user",
- written_by=WrittenBy.PERSON,
- verbatim="synthetic",
- origin_meta={EvidenceOrigin.FILE: OriginMetadata()},
- )
- ).record
- store = MemoryGovernanceStore(database)
-
- def denied():
- raise RuntimeError("denied")
-
- with store.guard_writes(denied):
- assert store.list(user_id="local") == []
- result = as_person(store).create(
- MemoryDraft(
- user_id="local",
- kind=MemoryKind.CHAT,
- content="manual action",
- evidence_ids=(original.evidence_id,),
- scopes=("private",),
- ),
- request_id="manual",
- )
- assert result.content == "manual action"
-
-
-def test_guard_check_and_commit_hold_database_write_authority(tmp_path):
- from concurrent.futures import ThreadPoolExecutor
-
- database = tmp_path / "test.sqlite"
- evidence = EvidenceStore(database)
- record = evidence.put(
- EvidenceInput(
- source_id="fixture",
- conversation_id="one",
- message_id="one",
- role="user",
- written_by=WrittenBy.PERSON,
- verbatim="synthetic",
- origin_meta={EvidenceOrigin.FILE: OriginMetadata()},
- )
- ).record
- store = MemoryGovernanceStore(database)
- with sqlite3.connect(database) as db:
- db.execute("CREATE TABLE permission_fixture (revoked INTEGER)")
- db.execute("INSERT INTO permission_fixture VALUES (0)")
- checks = []
-
- def revoke():
- with sqlite3.connect(database, timeout=0) as db:
- db.execute("UPDATE permission_fixture SET revoked=1")
-
- def guard():
- with (
- ThreadPoolExecutor(max_workers=1) as pool,
- pytest.raises(sqlite3.OperationalError, match="locked"),
- ):
- pool.submit(revoke).result(timeout=2)
- checks.append("write-locked")
-
- with store.guard_writes(guard):
- result = as_person(store).create(
- MemoryDraft(
- user_id="local",
- kind=MemoryKind.CHAT,
- content="permitted",
- evidence_ids=(record.evidence_id,),
- scopes=("private",),
- ),
- request_id="permission-checked",
- )
- assert checks == ["write-locked", "write-locked"]
- revoke()
- assert store.get(result.memory_id, user_id="local") is not None
diff --git a/memhub/apps/core/tests/test_governance_read_path_does_not_take_the_writer.py b/memhub/apps/core/tests/test_governance_read_path_does_not_take_the_writer.py
deleted file mode 100644
index 20ce6eb..0000000
--- a/memhub/apps/core/tests/test_governance_read_path_does_not_take_the_writer.py
+++ /dev/null
@@ -1,100 +0,0 @@
-"""The recall read path must not acquire the single global writer.
-
-`MemoryGovernanceStore.find_confirmed_matching_terms` is the recall read path.
-It calls `_refresh_content_shadow`, which opened `_connection()` with the
-default `writing=True`. That means every recall read checked out the ONE global
-writer connection for a check that changes nothing on a migrated database —
-serializing unrelated readers behind the writer and inflating `writer_waits`.
-
-The absent-shadow case must still fail closed (`governance_schema_missing`),
-and it must do so without taking the writer: the LIKE fallback already handles
-a missing shadow, and migration 32 — not this read path — owns the table.
-"""
-
-from __future__ import annotations
-
-import sqlite3
-
-import pytest
-
-from one_memory.database_access import main_database
-from one_memory.imports.models import EvidenceInput, EvidenceOrigin, OriginMetadata, WrittenBy
-from one_memory.imports.storage import EvidenceStore
-from one_memory.memory_governance import HyCreate, MemoryDraft, MemoryGovernanceStore
-
-
-def _store(tmp_path):
- database = tmp_path / "one-memory.sqlite3"
- store = MemoryGovernanceStore(database)
- with store._connection() as connection:
- store._ensure_content_shadow(connection, backfill=False)
- evidence_id = (
- EvidenceStore(database)
- .put(
- EvidenceInput(
- source_id="cursor",
- conversation_id="conversation",
- message_id="m1",
- correlation_id="m1",
- role="user",
- written_by=WrittenBy.PERSON,
- verbatim="发布窗口是周五上午。",
- origin_meta={EvidenceOrigin.FILE: OriginMetadata()},
- )
- )
- .record.evidence_id
- )
- return store, database, evidence_id
-
-
-def test_a_recall_read_does_not_check_out_the_global_writer(tmp_path):
- store, database, evidence_id = _store(tmp_path)
- store.write_from_hy(
- HyCreate(
- draft=MemoryDraft(
- user_id="local",
- kind="schema",
- content="发布窗口是周五上午",
- scopes=("all-apps",),
- evidence_ids=(evidence_id,),
- ),
- request_id="r1",
- memory_id="m1",
- ),
- user_id="local",
- derivation=store.hy_derivation(),
- )
- db = main_database(database)
- # Warm once so any lazy one-time initialization is not attributed to the read.
- store.find_confirmed_matching_terms(user_id="local", terms=["发布"], limit=10)
- before = db.stats()
- store.find_confirmed_matching_terms(user_id="local", terms=["发布"], limit=10)
- after = db.stats()
- assert after.reader_checkouts - before.reader_checkouts >= 1
- assert after.writer_checkouts - before.writer_checkouts == 0, (
- "the recall read path must not take the single global writer"
- )
-
-
-def test_a_missing_shadow_still_fails_closed_without_taking_the_writer(tmp_path):
- store, database, _evidence_id = _store(tmp_path)
- with sqlite3.connect(database) as connection:
- connection.execute("DROP TABLE governed_memories_terms")
- connection.execute("DROP TABLE governed_memories_terms_meta")
- db = main_database(database)
- before = db.stats()
- with pytest.raises(Exception, match="governance_schema_missing"):
- store.find_confirmed_matching_terms(user_id="local", terms=["发布"], limit=10)
- after = db.stats()
- assert after.writer_checkouts - before.writer_checkouts == 0, (
- "a broken schema must fail closed on a read connection, not write"
- )
- with sqlite3.connect(database) as connection:
- names = {
- row[0]
- for row in connection.execute(
- "SELECT name FROM sqlite_master WHERE type='table' "
- "AND name LIKE 'governed_memories_terms%'"
- )
- }
- assert names == set(), "a read must not repair or recreate the shadow tables"
diff --git a/memhub/apps/core/tests/test_graph_width_endpoint.py b/memhub/apps/core/tests/test_graph_width_endpoint.py
index 435bcac..13a0c5f 100644
--- a/memhub/apps/core/tests/test_graph_width_endpoint.py
+++ b/memhub/apps/core/tests/test_graph_width_endpoint.py
@@ -17,13 +17,18 @@ from pydantic import SecretStr
from one_memory.api import create_app
from one_memory.config import Settings
-from one_memory.hy_memory_bridge import build_hy_memory_config
+from one_memory.hy_sdk_runtime import build_sdk_config
from one_memory.model_profiles import (
ModelCapabilities,
ModelProfileInput,
ProviderKind,
)
-from tests.test_hy_memory_bridge import _kuzu_graph_with_embedding_width
+from tests.graph_fixtures import kuzu_graph_with_embedding_width
+
+
[email protected](autouse=True)
+def _enable_graph_store(monkeypatch: pytest.MonkeyPatch) -> None:
+ monkeypatch.setenv("ONE_MEMORY_GRAPH_STORE", "kuzu")
def _app(tmp_path: Path):
@@ -80,10 +85,10 @@ def _activate_builtin_profile(app):
def _plant_wide_graph(app, data_dir: Path) -> Path:
snapshot = _activate_builtin_profile(app)
- config = build_hy_memory_config(snapshot, api_key=None, data_dir=data_dir)
+ config = build_sdk_config(snapshot, api_key=None, data_dir=data_dir)
db_path = Path(config.graph_store.db_path)
db_path.parent.mkdir(parents=True, exist_ok=True)
- _kuzu_graph_with_embedding_width(db_path, 768)
+ kuzu_graph_with_embedding_width(db_path, 768)
return db_path
diff --git a/memhub/apps/core/tests/test_graph_width_export.py b/memhub/apps/core/tests/test_graph_width_export.py
index b5a180f..228aea7 100644
--- a/memhub/apps/core/tests/test_graph_width_export.py
+++ b/memhub/apps/core/tests/test_graph_width_export.py
@@ -15,18 +15,18 @@ from pathlib import Path
import pytest
-from one_memory.hy_memory_bridge import (
+from one_memory.hy_graph_admin import (
GraphWidthDecision,
apply_graph_width_decision,
- build_hy_memory_config,
inspect_graph_width_mismatch,
)
+from one_memory.hy_sdk_runtime import build_sdk_config
from one_memory.model_profiles import ModelProfileSnapshot, ProviderKind
-from tests.test_hy_memory_bridge import _kuzu_graph_with_embedding_width, snapshot
+from tests.graph_fixtures import kuzu_graph_with_embedding_width, model_snapshot
def _narrow_profile() -> ModelProfileSnapshot:
- base = snapshot(
+ base = model_snapshot(
ProviderKind.OLLAMA,
base_url="http://127.0.0.1:11434",
has_api_key=False,
@@ -38,10 +38,10 @@ def _mismatched(tmp_path: Path) -> tuple[object, Path, Path]:
"""A 768 graph under a data dir, against a 512 profile."""
data_dir = tmp_path / "data"
profile = _narrow_profile()
- config = build_hy_memory_config(profile, api_key=None, data_dir=data_dir)
+ config = build_sdk_config(profile, api_key=None, data_dir=data_dir)
db_path = Path(config.graph_store.db_path)
db_path.parent.mkdir(parents=True, exist_ok=True)
- _kuzu_graph_with_embedding_width(db_path, 768)
+ kuzu_graph_with_embedding_width(db_path, 768)
return config, db_path, data_dir
diff --git a/memhub/apps/core/tests/test_graph_width_guard.py b/memhub/apps/core/tests/test_graph_width_guard.py
index 7cc3995..cbe6cc4 100644
--- a/memhub/apps/core/tests/test_graph_width_guard.py
+++ b/memhub/apps/core/tests/test_graph_width_guard.py
@@ -13,22 +13,21 @@ from pathlib import Path
import pytest
-from one_memory.hy_memory_bridge import (
+from one_memory.hy_graph_admin import (
GraphWidthDecision,
GraphWidthMismatchError,
apply_graph_width_decision,
- build_hy_memory_config,
- create_hy_memory_client,
inspect_graph_width_mismatch,
)
+from one_memory.hy_sdk_runtime import acquire_client, build_sdk_config
from one_memory.model_profiles import ModelProfileSnapshot, ProviderKind
-from tests.test_hy_memory_bridge import _kuzu_graph_with_embedding_width, snapshot
+from tests.graph_fixtures import kuzu_graph_with_embedding_width, model_snapshot
def _narrow_profile(**overrides: object) -> ModelProfileSnapshot:
# Width alone is what matters here. The built-in provider arrives in S1.3;
# this guard has to hold for any 512-dim profile against a 768 graph.
- base = snapshot(
+ base = model_snapshot(
ProviderKind.OLLAMA,
base_url="http://127.0.0.1:11434",
has_api_key=False,
@@ -45,10 +44,10 @@ def test_a_768_graph_is_not_silently_archived_when_switching_to_512(
tmp_path: Path,
) -> None:
profile = _narrow_profile()
- config = build_hy_memory_config(profile, api_key=None, data_dir=tmp_path)
+ config = build_sdk_config(profile, api_key=None, data_dir=tmp_path)
db_path = Path(config.graph_store.db_path)
db_path.parent.mkdir(parents=True, exist_ok=True)
- _kuzu_graph_with_embedding_width(db_path, 768)
+ kuzu_graph_with_embedding_width(db_path, 768)
mismatch = inspect_graph_width_mismatch(config)
@@ -63,13 +62,13 @@ def test_creating_a_client_against_a_mismatched_graph_raises_instead_of_retiring
tmp_path: Path,
) -> None:
profile = _narrow_profile()
- config = build_hy_memory_config(profile, api_key=None, data_dir=tmp_path)
+ config = build_sdk_config(profile, api_key=None, data_dir=tmp_path)
db_path = Path(config.graph_store.db_path)
db_path.parent.mkdir(parents=True, exist_ok=True)
- _kuzu_graph_with_embedding_width(db_path, 768)
+ kuzu_graph_with_embedding_width(db_path, 768)
with pytest.raises(GraphWidthMismatchError) as caught:
- create_hy_memory_client(profile, api_key=None, data_dir=tmp_path)
+ acquire_client(profile, api_key=None, data_dir=tmp_path)
assert caught.value.mismatch.stored_width == 768
assert caught.value.mismatch.expected_width == 512
@@ -81,10 +80,10 @@ def test_keep_existing_leaves_the_graph_and_refuses_the_new_width(
tmp_path: Path,
) -> None:
profile = _narrow_profile()
- config = build_hy_memory_config(profile, api_key=None, data_dir=tmp_path)
+ config = build_sdk_config(profile, api_key=None, data_dir=tmp_path)
db_path = Path(config.graph_store.db_path)
db_path.parent.mkdir(parents=True, exist_ok=True)
- _kuzu_graph_with_embedding_width(db_path, 768)
+ kuzu_graph_with_embedding_width(db_path, 768)
outcome = apply_graph_width_decision(config, GraphWidthDecision.KEEP_EXISTING)
@@ -98,10 +97,10 @@ def test_rebuild_archives_the_graph_and_lets_the_new_width_proceed(
tmp_path: Path,
) -> None:
profile = _narrow_profile()
- config = build_hy_memory_config(profile, api_key=None, data_dir=tmp_path)
+ config = build_sdk_config(profile, api_key=None, data_dir=tmp_path)
db_path = Path(config.graph_store.db_path)
db_path.parent.mkdir(parents=True, exist_ok=True)
- _kuzu_graph_with_embedding_width(db_path, 768)
+ kuzu_graph_with_embedding_width(db_path, 768)
outcome = apply_graph_width_decision(config, GraphWidthDecision.REBUILD_WITH_NEW)
@@ -114,10 +113,10 @@ def test_rebuild_archives_the_graph_and_lets_the_new_width_proceed(
def test_export_first_leaves_the_graph_untouched(tmp_path: Path) -> None:
profile = _narrow_profile()
- config = build_hy_memory_config(profile, api_key=None, data_dir=tmp_path / "data")
+ config = build_sdk_config(profile, api_key=None, data_dir=tmp_path / "data")
db_path = Path(config.graph_store.db_path)
db_path.parent.mkdir(parents=True, exist_ok=True)
- _kuzu_graph_with_embedding_width(db_path, 768)
+ kuzu_graph_with_embedding_width(db_path, 768)
outcome = apply_graph_width_decision(
config,
@@ -135,6 +134,6 @@ def test_export_first_leaves_the_graph_untouched(tmp_path: Path) -> None:
def test_a_fresh_install_with_no_graph_raises_nothing(tmp_path: Path) -> None:
profile = _narrow_profile()
- config = build_hy_memory_config(profile, api_key=None, data_dir=tmp_path)
+ config = build_sdk_config(profile, api_key=None, data_dir=tmp_path)
assert inspect_graph_width_mismatch(config) is None
diff --git a/memhub/apps/core/tests/test_hy_coding_reply.py b/memhub/apps/core/tests/test_hy_coding_reply.py
deleted file mode 100644
index d786c66..0000000
--- a/memhub/apps/core/tests/test_hy_coding_reply.py
+++ /dev/null
@@ -1,282 +0,0 @@
-"""R-07: HY's coding-shaped replies read as "no memories at all".
-
-`search_ids` reads `memories` and `_listed_memories` reads `vdb.memories`.
-HY has a second reply shape — `{"scene": "productivity", "coding_memories":
-[...]}` (`hy_memory/client.py:1145`, `client.py:1038`) — and neither parser
-recognises it, so it comes back as an empty tuple. Empty is indistinguishable
-from "this person has no memories", which is the failure this codebase
-already paid for once on the profile path: see `_basic_info_memories`, which
-raises on a payload it does not recognise for exactly that reason.
-
-Read from HY's source, the requirement's diagnosis does not hold: the coding
-path is not reachable from here at all, in either direction. Both preconditions
-are pinned below as green controls, because they are what makes this fix a
-guard rather than a repair — and they are the two things that would have to
-change before a coding memory could ever be recalled.
-"""
-
-from __future__ import annotations
-
-import asyncio
-from collections.abc import Mapping
-
-import pytest
-from pydantic import ValidationError
-
-from one_memory.hy_memory_bridge import (
- HyMemoryBridge,
- HyMemoryBridgeError,
- HyMemoryTurn,
- _listed_memories,
- build_hy_memory_config,
-)
-from one_memory.model_profiles import ModelProfileSnapshot, ProviderKind
-
-CODING_SEARCH_REPLY: Mapping[str, object] = {
- "request_id": "req-1",
- "scene": "productivity",
- "coding_memories": [
- {"memory_id": "coding-1", "content": "用户在 recall.py 里用过滤下推替换了内存过滤"},
- {"memory_id": "coding-2", "content": "用户的分页上限是 500"},
- ],
- "elapsed_ms": 12.0,
-}
-
-CODING_LIST_REPLY: Mapping[str, object] = {
- "scene": "productivity",
- "coding_memories": [
- {"memory_id": "coding-1", "agent_id": "workspace-a"},
- {"memory_id": "coding-2", "agent_id": "workspace-b"},
- ],
-}
-
-
-class CodingSceneClient:
- """A client that answers in HY's coding shape rather than the chat shape."""
-
- def __init__(self, *, search_reply=CODING_SEARCH_REPLY, list_reply=CODING_LIST_REPLY):
- self.search_reply = search_reply
- self.list_reply = list_reply
-
- def search(self, query: str, **_kwargs) -> Mapping[str, object]:
- return self.search_reply
-
- def list_memories(self, **_kwargs) -> Mapping[str, object]:
- return self.list_reply
-
- def close(self) -> None:
- return None
-
-
-def _profile() -> ModelProfileSnapshot:
- return ModelProfileSnapshot(
- profile_id="profile",
- revision=1,
- provider_kind=ProviderKind.OLLAMA,
- base_url="http://127.0.0.1:11434",
- model="memory-model",
- embedding_model="embedding-model",
- embedding_provider_kind=None,
- embedding_base_url=None,
- embedding_dimensions=768,
- timeout_seconds=30,
- max_concurrency=1,
- context_window=8192,
- has_api_key=False,
- )
-
-
-def _bridge(client, tmp_path) -> HyMemoryBridge:
- return HyMemoryBridge(
- profile=_profile(),
- api_key=None,
- data_dir=tmp_path,
- client=client,
- )
-
-
-def test_a_coding_shaped_search_reply_is_not_read_as_no_memories(tmp_path) -> None:
- bridge = _bridge(CodingSceneClient(), tmp_path)
-
- found = asyncio.run(bridge.search_ids(query="过滤下推", user_id="local", agent_id="*"))
-
- assert found == ("coding-1", "coding-2")
-
-
-def test_a_coding_shaped_listing_is_not_read_as_no_scopes(tmp_path) -> None:
- bridge = _bridge(CodingSceneClient(), tmp_path)
-
- scopes = asyncio.run(bridge.list_agent_ids(user_id="local"))
-
- assert scopes == ("workspace-a", "workspace-b")
-
-
-def test_an_unrecognised_search_reply_is_an_error_not_an_empty_recall(tmp_path) -> None:
- """A shape we do not understand must not be reported as an empty library.
-
- Returning `()` here is what made a coding reply look like "you have no
- memories". Whatever HY adds next, the honest answer is that we could not
- read it.
- """
- bridge = _bridge(CodingSceneClient(search_reply={"request_id": "req-2"}), tmp_path)
-
- with pytest.raises(HyMemoryBridgeError):
- asyncio.run(bridge.search_ids(query="过滤下推", user_id="local", agent_id="*"))
-
-
-def test_an_unrecognised_listing_is_an_error_too(tmp_path) -> None:
- bridge = _bridge(CodingSceneClient(list_reply={"unexpected": {}}), tmp_path)
-
- with pytest.raises(HyMemoryBridgeError):
- asyncio.run(bridge.list_agent_ids(user_id="local"))
-
-
-#: What HY 0.1.6.5 actually answers a chat-path search with
-#: (`client.py:2378-2389`): `memories` is three channels, not a list. Our
-#: parser required a list, so every semantic search read as zero hits.
-THREE_CHANNEL_REPLY: Mapping[str, object] = {
- "request_id": "req-3",
- "memories": {
- "schema": [
- {"memory_id": "schema-1", "score": 0.61, "layer": "L0_BASIC_INFO"},
- ],
- "proactive": [
- {"memory_id": "intention-1", "score": 0.44, "layer": "L7_INTENTION"},
- ],
- "normal": [
- {"memory_id": "fact-1", "score": 0.88, "layer": "L2_FACT"},
- {"memory_id": "fact-2", "score": 0.52, "layer": "L2_FACT"},
- ],
- },
- "rewrite": {"used": False, "scene": "normal"},
- "elapsed_ms": 41.0,
-}
-
-#: The failure branch (`client.py:2253`), which is the shape this machine has
-#: actually been getting: same three channels, all empty. HY logs
-#: "[search] failed" and returns this.
-FAILED_SEARCH_REPLY: Mapping[str, object] = {
- "request_id": "req-4",
- "memories": {"schema": [], "proactive": [], "normal": []},
- "elapsed_ms": 3.0,
-}
-
-
-def test_the_three_channels_hy_actually_returns_are_all_read(tmp_path) -> None:
- """The real defect behind R-07, and it is not about coding at all.
-
- `memories` is a dict of schema / proactive / normal channels in the current
- HY SDK; our parser asked `isinstance(memories, list)` and returned an empty
- tuple otherwise. So semantic recall was dead — including the schema channel,
- which is the whole reason
- `schema_min_score` and `schema_limit` are passed in.
- """
- bridge = _bridge(CodingSceneClient(search_reply=THREE_CHANNEL_REPLY), tmp_path)
-
- found = asyncio.run(bridge.search_ids(query="花名", user_id="local", agent_id="*"))
-
- assert set(found) == {"fact-1", "schema-1", "fact-2", "intention-1"}
-
-
-def test_the_channels_are_merged_in_hys_own_order_not_ours(tmp_path) -> None:
- """Recall ranks by the order these ids come back in, so the order matters.
-
- Bucketing into channels loses HY's ranking, but every item still carries
- the `score` HY ranked it by — a field we were also dropping. Sorting the
- union by it restores HY's judgement instead of substituting a channel
- preference of our own, which would be a retrieval-quality decision and
- not ours to make here.
- """
- bridge = _bridge(CodingSceneClient(search_reply=THREE_CHANNEL_REPLY), tmp_path)
-
- found = asyncio.run(bridge.search_ids(query="花名", user_id="local", agent_id="*"))
-
- assert found == ("fact-1", "schema-1", "fact-2", "intention-1")
-
-
-def test_search_scores_carries_hys_relevance(tmp_path) -> None:
- """D102: the score is what lets recall blend the two lanes by relevance."""
- bridge = _bridge(CodingSceneClient(search_reply=THREE_CHANNEL_REPLY), tmp_path)
-
- found = asyncio.run(bridge.search_scores(query="花名", user_id="local", agent_id="*"))
-
- assert found == (
- ("fact-1", 0.88),
- ("schema-1", 0.61),
- ("fact-2", 0.52),
- ("intention-1", 0.44),
- )
-
-
-def test_a_failed_hy_search_is_not_an_error_here_but_is_still_empty(tmp_path) -> None:
- """HY reports search failure only in its log, and returns empty channels.
-
- On this machine every real search has been `[search] failed: Connection
- error.` — the embedding endpoint is unreachable — and the reply is
- indistinguishable from a genuine zero-hit search. We cannot tell them
- apart at this seam, so this must not become a hard error; it is recorded
- as an upstream gap instead.
- """
- bridge = _bridge(CodingSceneClient(search_reply=FAILED_SEARCH_REPLY), tmp_path)
-
- assert asyncio.run(bridge.search_ids(query="花名", user_id="local", agent_id="*")) == ()
-
-
-def test_the_chat_shape_still_reads_the_same(tmp_path) -> None:
- """The control: the shape we actually get today must not move.
-
- Green before and after. Every real reply on this machine is this one, so
- a change here would be the fix breaking recall to satisfy a shape we have
- never seen.
- """
- chat_client = CodingSceneClient(
- search_reply={"memories": [{"memory_id": "chat-1"}, {"id": "chat-2"}]},
- list_reply={"vdb": {"memories": [{"agent_id": "one-memory"}]}},
- )
- bridge = _bridge(chat_client, tmp_path)
-
- assert asyncio.run(bridge.search_ids(query="花名", user_id="local", agent_id="*")) == (
- "chat-1",
- "chat-2",
- )
- assert asyncio.run(bridge.list_agent_ids(user_id="local")) == ("one-memory",)
- assert _listed_memories({"vdb": {"memories": []}}) == ()
-
-
-def test_an_empty_chat_reply_is_still_just_empty(tmp_path) -> None:
- """No memories yet is not a shape error, and must stay quiet."""
- bridge = _bridge(
- CodingSceneClient(search_reply={"memories": []}, list_reply={"vdb": {"memories": []}}),
- tmp_path,
- )
-
- assert asyncio.run(bridge.search_ids(query="花名", user_id="local", agent_id="*")) == ()
- assert asyncio.run(bridge.list_agent_ids(user_id="local")) == ()
-
-
-def test_a_tool_message_can_reach_hy_so_it_can_judge_the_route_itself() -> None:
- """HY only considers its coding writer when the messages contain a
- tool-role message (`has_any_tool_message`). Kristin's call: send the turn
- as it happened, tool calls included, and let HY decide."""
- assert HyMemoryTurn(role="tool", content="[Bash] ls -la").role == "tool"
- with pytest.raises(ValidationError):
- HyMemoryTurn(role="system", content="hidden")
-
-
-def test_our_search_call_shape_cannot_reach_hys_coding_path(tmp_path) -> None:
- """Why no coding reply can arrive today — the read side.
-
- HY decides the scene per search (`client.py:2020-2116`): an explicit
- `scene`, or an LLM judge when query rewrite is on, or the multi-`queries`
- judge. Otherwise a single query defaults to `normal`. We pass one query,
- no scene, and leave rewrite at HY's default of off, so the coding branch
- is unreachable — `config.coding.enable` being true only pays for the
- store, not the routing.
-
- Turning any of that on costs an LLM call per search and, with the store
- empty, buys nothing. Left as Kristin's call rather than switched on here.
- """
- config = build_hy_memory_config(_profile(), api_key=None, data_dir=tmp_path)
-
- assert config.coding.enable is True
- assert config.llm.enable_query_rewrite is False
diff --git a/memhub/apps/core/tests/test_hy_log_privacy.py b/memhub/apps/core/tests/test_hy_log_privacy.py
index d411d60..444d342 100644
--- a/memhub/apps/core/tests/test_hy_log_privacy.py
+++ b/memhub/apps/core/tests/test_hy_log_privacy.py
@@ -2,7 +2,7 @@
import logging
-from one_memory.hy_memory_bridge import configure_hy_memory_environment
+from one_memory.hy_runtime_config import configure_hy_runtime_environment
def test_the_extractors_parse_failures_pass_through_unchanged(tmp_path):
@@ -19,7 +19,7 @@ def test_the_extractors_parse_failures_pass_through_unchanged(tmp_path):
original_handlers = list(logger.handlers)
logger.handlers = [capture]
logger.setLevel(logging.WARNING)
- configure_hy_memory_environment(tmp_path)
+ configure_hy_runtime_environment(tmp_path)
try:
secret = "x" * 5000
logger.warning(
@@ -52,7 +52,7 @@ def test_other_warnings_pass_through_unchanged(tmp_path):
original_handlers = list(logger.handlers)
logger.handlers = [capture]
logger.setLevel(logging.WARNING)
- configure_hy_memory_environment(tmp_path)
+ configure_hy_runtime_environment(tmp_path)
try:
logger.warning("[coding-extract] judge failed, fallback to chat: %s", "reason")
finally:
diff --git a/memhub/apps/core/tests/test_hy_memory_bridge.py b/memhub/apps/core/tests/test_hy_memory_bridge.py
deleted file mode 100644
index bd0f0b9..0000000
--- a/memhub/apps/core/tests/test_hy_memory_bridge.py
+++ /dev/null
@@ -1,1795 +0,0 @@
-import asyncio
-import gc
-import json
-import os
-import sqlite3
-import threading
-import time
-from collections.abc import Mapping, Sequence
-from datetime import datetime
-from pathlib import Path
-from types import SimpleNamespace
-
-import pytest
-
-from one_memory.diagnostic_log import configure_diagnostics, reset_diagnostics
-from one_memory.hy_memory_bridge import (
- HyMemoryBridge,
- HyMemoryBridgeError,
- HyMemoryIngestRequest,
- HyMemoryIngestResult,
- HyMemoryTurn,
- UnsupportedHyMemoryProviderError,
- _basic_info_memories,
- _collection_name,
- _with_native_mutation_delta,
- build_hy_memory_config,
- configure_hy_memory_environment,
- reattach_legacy_vector_collection,
- retire_mismatched_graph_store,
-)
-from one_memory.hy_runtime_config import (
- HY_MEMORY_DISTRIBUTION,
- HY_MEMORY_MODE,
- HY_MEMORY_READER,
- HY_MEMORY_VERSION,
-)
-from one_memory.model_profiles import ModelProfileSnapshot, ProviderKind
-
-
-class FakeHyMemoryClient:
- def __init__(
- self,
- result: Mapping[str, object],
- *,
- record_request_id: str | None = None,
- search_result: Mapping[str, object] | None = None,
- ) -> None:
- self.result = result
- self.record_request_id = record_request_id
- self.search_result = search_result or {"results": []}
- self.update_succeeds = True
- self.calls: list[dict[str, object]] = []
- self.search_calls: list[dict[str, object]] = []
- self.closed = False
- self.deleted: set[str] = set()
- self.list_result: Mapping[str, object] = {"vdb": {"memories": [], "total": 0}}
- self.write_outcome: Mapping[str, object] | None = None
- self.raw_result: Mapping[str, object] | None = None
- self.raw_list_result: Mapping[str, object] = {"raw": [], "total": 0}
-
- def add(
- self,
- data: Sequence[Mapping[str, str]],
- *,
- user_id: str,
- agent_id: str,
- session_id: str,
- source: str,
- metadata: Mapping[str, object],
- memory_at: datetime | None,
- scene: str,
- request_id: str,
- ) -> Mapping[str, object]:
- self.calls.append(
- {
- "data": data,
- "user_id": user_id,
- "agent_id": agent_id,
- "session_id": session_id,
- "source": source,
- "metadata": metadata,
- "memory_at": memory_at,
- "scene": scene,
- "request_id": request_id,
- }
- )
- return self.result
-
- def add_extracted(
- self,
- contents: str | Sequence[str],
- *,
- user_id: str,
- agent_id: str,
- session_id: str,
- metadata: Mapping[str, object],
- memory_at: datetime | None,
- request_id: str,
- ) -> Mapping[str, object]:
- data = [contents] if isinstance(contents, str) else list(contents)
- self.calls.append(
- {
- "contents": data,
- "user_id": user_id,
- "agent_id": agent_id,
- "session_id": session_id,
- "metadata": metadata,
- "memory_at": memory_at,
- "request_id": request_id,
- }
- )
- return self.result
-
- def close(self) -> None:
- self.closed = True
-
- def get(self, memory_id: str) -> Mapping[str, object] | None:
- if memory_id in self.deleted:
- return None
- last = self.calls[-1] if self.calls else {}
- request_id = self.record_request_id or str(last.get("request_id") or "read")
- return {
- "memory_id": memory_id,
- "content": "Extracted memory",
- "layer": "l2_fact",
- "status": "active",
- "is_latest": True,
- "user_id": last.get("user_id") or "local",
- "agent_id": last.get("agent_id") or "one-memory",
- "custom": {"request_id": request_id},
- }
-
- def search(self, query: str, **kwargs) -> Mapping[str, object]:
- self.search_calls.append({"query": query, **kwargs})
- return self.search_result
-
- def list_memories(self, **kwargs) -> Mapping[str, object]:
- self.calls.append({"list_memories": dict(kwargs)})
- return self.list_result
-
- def get_write_outcome(self, request_id: str) -> Mapping[str, object] | None:
- self.calls.append({"get_write_outcome": request_id})
- return self.write_outcome
-
- def get_raw(self, raw_id: str) -> Mapping[str, object] | None:
- self.calls.append({"get_raw": raw_id})
- return self.raw_result
-
- def list_raw(self, **kwargs) -> Mapping[str, object]:
- self.calls.append({"list_raw": dict(kwargs)})
- return self.raw_list_result
-
- def import_memory_exact(self, content: str, **kwargs) -> Mapping[str, object]:
- self.calls.append({"import_memory_exact": content, **kwargs})
- return {
- "success": True,
- "memory_id": kwargs["memory_id"],
- "request_id": kwargs["request_id"],
- }
-
- def update(self, memory_id: str, content: str) -> Mapping[str, object]:
- self.calls.append({"update_memory_id": memory_id, "update_content": content})
- return {"success": self.update_succeeds, "memory_id": memory_id}
-
- def delete(self, memory_id: str) -> Mapping[str, object]:
- self.calls.append({"delete_memory_id": memory_id})
- self.deleted.add(memory_id)
- return {"success": True, "memory_id": memory_id}
-
- def evolve(self, **kwargs: object) -> Mapping[str, object]:
- self.calls.append({"evolve": dict(kwargs)})
- return {"success": True}
-
- def create_collection(self, **kwargs: object) -> Mapping[str, object]:
- self.calls.append({"create_collection": dict(kwargs)})
- return {"success": True}
-
- def add_task(self, **kwargs: object) -> Mapping[str, object]:
- self.calls.append({"add_task": dict(kwargs)})
- return {"success": True}
-
-
-class FailingHyMemoryClient(FakeHyMemoryClient):
- def add(self, *args, **kwargs):
- raise RuntimeError("private-provider-response-918273")
-
-
-def snapshot(
- provider: ProviderKind,
- *,
- base_url: str | None,
- has_api_key: bool,
- embedding_provider: ProviderKind | None = None,
- embedding_base_url: str | None = None,
-) -> ModelProfileSnapshot:
- return ModelProfileSnapshot(
- profile_id="profile",
- revision=3,
- provider_kind=provider,
- base_url=base_url,
- model="memory-model",
- embedding_model="embedding-model",
- embedding_provider_kind=embedding_provider,
- embedding_base_url=embedding_base_url,
- embedding_dimensions=768,
- timeout_seconds=30,
- max_concurrency=1,
- context_window=8192,
- has_api_key=has_api_key,
- )
-
-
-def test_hy_client_initialization_is_serial_across_bridges(tmp_path, monkeypatch) -> None:
- active = 0
- max_active = 0
- created: list[FakeHyMemoryClient] = []
- guard = threading.Lock()
-
- def create(*_args, **_kwargs):
- nonlocal active, max_active
- with guard:
- active += 1
- max_active = max(max_active, active)
- time.sleep(0.02)
- client = FakeHyMemoryClient({"success": True, "results": []})
- created.append(client)
- with guard:
- active -= 1
- return client
-
- monkeypatch.setattr("one_memory.hy_memory_bridge.create_hy_memory_client", create)
- profile = snapshot(
- ProviderKind.OPENAI_COMPATIBLE,
- base_url="https://model.invalid",
- has_api_key=True,
- )
- bridges = [
- HyMemoryBridge(profile=profile, api_key="secret", data_dir=tmp_path) for _ in range(8)
- ]
-
- async def exercise() -> None:
- await asyncio.gather(*(bridge.prepare() for bridge in bridges))
- await asyncio.gather(*(bridge.close() for bridge in bridges))
-
- asyncio.run(exercise())
-
- assert len(created) == 8
- assert max_active == 1
-
-
-def test_native_hy_clients_share_one_runtime_per_data_directory(tmp_path, monkeypatch) -> None:
- from one_memory import hy_memory_bridge
-
- class FakeRuntime:
- created = 0
- closed = 0
-
- def __init__(self) -> None:
- self.stop = threading.Event()
- self.threads = tuple(
- threading.Thread(
- target=self.stop.wait,
- name=f"n46-shared-loop-{index}",
- daemon=True,
- )
- for index in range(2)
- )
- for thread in self.threads:
- thread.start()
-
- @classmethod
- async def create(cls, _config):
- cls.created += 1
- return cls()
-
- def close(self) -> None:
- type(self).closed += 1
- self.stop.set()
- for thread in self.threads:
- thread.join(timeout=1)
-
- class FakeNativeClient:
- runtimes: list[FakeRuntime] = []
-
- def __init__(self, *, config, mode, runtime=None):
- del config, mode
- assert runtime is not None
- self.runtime = runtime
- self.runtimes.append(runtime)
-
- def close(self) -> None:
- pass
-
- real_import = hy_memory_bridge.import_module
-
- def fake_import(name: str):
- if name == "hy_memory.client":
- return SimpleNamespace(HyMemoryClient=FakeNativeClient)
- if name == "hy_memory.runtime":
- return SimpleNamespace(SharedRuntime=FakeRuntime)
- return real_import(name)
-
- monkeypatch.setattr(hy_memory_bridge, "import_module", fake_import)
- monkeypatch.setattr(hy_memory_bridge, "reattach_legacy_vector_collection", lambda *_: None)
- monkeypatch.setattr(hy_memory_bridge, "inspect_graph_width_mismatch", lambda *_: None)
- monkeypatch.setattr(
- "one_memory.hy_response_guard.install_hy_write_guards", lambda _client: None
- )
- hy_memory_bridge.close_shared_hy_runtimes()
- baseline = threading.active_count()
- profile = snapshot(
- ProviderKind.OLLAMA,
- base_url="http://127.0.0.1:11434",
- has_api_key=False,
- )
-
- clients = [
- hy_memory_bridge.create_hy_memory_client(profile, api_key=None, data_dir=tmp_path)
- for _ in range(50)
- ]
- for client in clients:
- client.close()
-
- assert FakeRuntime.created == 1
- assert len({id(runtime) for runtime in FakeNativeClient.runtimes}) == 1
- hy_memory_bridge.close_shared_hy_runtimes()
- assert FakeRuntime.closed == 1
- assert threading.active_count() <= baseline + 2
-
-
-def test_ollama_profile_ignores_ambient_remote_storage_and_models(
- tmp_path,
- monkeypatch,
-) -> None:
- monkeypatch.setenv("OPENAI_API_KEY", "ambient-secret")
- monkeypatch.setenv("MEMORY_EMBEDDER_BASE_URL", "https://api.openai.com/v1")
- monkeypatch.setenv("MEMORY_VECTOR_HOST", "remote.example.com")
- monkeypatch.setenv("MEMORY_COLLECTION_NAME", "hostile-collection")
- monkeypatch.setenv("MEMORY_EMBEDDING_DIMS", "99")
- monkeypatch.delenv("MEMORY_CODING_TOOL_RESULT_MAX_BYTES", raising=False)
- profile = snapshot(
- ProviderKind.OLLAMA,
- base_url="http://127.0.0.1:11434",
- has_api_key=False,
- )
-
- config = build_hy_memory_config(profile, api_key=None, data_dir=tmp_path)
-
- assert config.llm.provider == "openai"
- assert config.llm.model == "memory-model"
- assert config.llm.base_url == "http://127.0.0.1:11434/v1"
- assert config.llm.api_key == "ollama"
- assert config.llm.timeout == 30
- assert config.embedder.model == "embedding-model"
- assert config.embedder.base_url == "http://127.0.0.1:11434/v1"
- assert config.embedder.api_key == "ollama"
- assert config.vector_store.provider == "chroma"
- assert config.vector_store.host is None
- assert config.vector_store.collection_name.startswith("one_memory_")
- assert config.vector_store.collection_name != "hostile-collection"
- assert config.vector_store.embedding_dims == 768
- assert config.graph_store.provider == "kuzu"
- assert str(tmp_path) in config.graph_store.db_path
- assert config.coding.tool_result_max_bytes == 512
-
-
-def test_memhub_coding_tool_result_ceiling_is_configurable(tmp_path, monkeypatch) -> None:
- monkeypatch.setenv("MEMORY_CODING_TOOL_RESULT_MAX_BYTES", "1024")
- profile = snapshot(
- ProviderKind.OLLAMA,
- base_url="http://127.0.0.1:11434",
- has_api_key=False,
- )
-
- config = build_hy_memory_config(profile, api_key=None, data_dir=tmp_path)
-
- assert config.coding.tool_result_max_bytes == 1024
-
-
-def _kuzu_graph_with_embedding_width(db_path: Path, width: int) -> None:
- kuzu = pytest.importorskip("kuzu")
- database = kuzu.Database(str(db_path))
- connection = kuzu.Connection(database)
- connection.execute(
- f"CREATE NODE TABLE Memory(node_id STRING, embedding FLOAT[{width}], PRIMARY KEY(node_id))"
- )
- del connection
- del database
- gc.collect()
-
-
-def _chroma_with_collection(database: Path, name: str, dimension: int | None) -> None:
- database.parent.mkdir(parents=True, exist_ok=True)
- with sqlite3.connect(database) as connection:
- connection.execute(
- "CREATE TABLE collections (id TEXT PRIMARY KEY, name TEXT, dimension INTEGER)"
- )
- connection.execute(
- "INSERT INTO collections VALUES (?, ?, ?)",
- ("segment-1", name, dimension),
- )
-
-
-def test_collection_written_before_the_width_was_known_is_reattached(tmp_path) -> None:
- profile = snapshot(
- ProviderKind.OLLAMA,
- base_url="http://127.0.0.1:11434",
- has_api_key=False,
- )
- config = build_hy_memory_config(profile, api_key=None, data_dir=tmp_path)
- database = Path(config.vector_store.persist_directory) / "chroma.sqlite3"
- # Written when the profile had no measured width, so HY suffixed the
- # default 1536 onto a collection that really holds 768-wide vectors.
- legacy = _collection_name(
- ProviderKind.OLLAMA,
- "http://127.0.0.1:11434/v1",
- "embedding-model",
- declared_dimensions="auto",
- )
- _chroma_with_collection(database, f"{legacy}_1536", 768)
-
- migrated = reattach_legacy_vector_collection(profile, config)
-
- assert migrated == f"{legacy}_1536"
- with sqlite3.connect(database) as connection:
- names = [row[0] for row in connection.execute("SELECT name FROM collections")]
- assert names == [f"{config.vector_store.collection_name}_768"]
-
-
-def test_reattach_leaves_a_collection_from_another_embedding_width_alone(tmp_path) -> None:
- profile = snapshot(
- ProviderKind.OLLAMA,
- base_url="http://127.0.0.1:11434",
- has_api_key=False,
- )
- config = build_hy_memory_config(profile, api_key=None, data_dir=tmp_path)
- database = Path(config.vector_store.persist_directory) / "chroma.sqlite3"
- legacy = _collection_name(
- ProviderKind.OLLAMA,
- "http://127.0.0.1:11434/v1",
- "embedding-model",
- declared_dimensions="auto",
- )
- _chroma_with_collection(database, f"{legacy}_1536", 1536)
-
- assert reattach_legacy_vector_collection(profile, config) is None
- with sqlite3.connect(database) as connection:
- names = [row[0] for row in connection.execute("SELECT name FROM collections")]
- assert names == [f"{legacy}_1536"]
-
-
-def test_graph_store_created_for_another_embedding_width_is_retired(tmp_path) -> None:
- profile = snapshot(
- ProviderKind.OLLAMA,
- base_url="http://127.0.0.1:11434",
- has_api_key=False,
- )
- config = build_hy_memory_config(profile, api_key=None, data_dir=tmp_path)
- db_path = Path(config.graph_store.db_path)
- db_path.parent.mkdir(parents=True, exist_ok=True)
- _kuzu_graph_with_embedding_width(db_path, 1536)
-
- archive = retire_mismatched_graph_store(config)
-
- assert archive is not None
- assert archive.exists()
- assert "dim1536" in archive.name
- assert not db_path.exists()
-
-
-def test_graph_store_matching_the_embedding_width_is_kept(tmp_path) -> None:
- profile = snapshot(
- ProviderKind.OLLAMA,
- base_url="http://127.0.0.1:11434",
- has_api_key=False,
- )
- config = build_hy_memory_config(profile, api_key=None, data_dir=tmp_path)
- db_path = Path(config.graph_store.db_path)
- db_path.parent.mkdir(parents=True, exist_ok=True)
- _kuzu_graph_with_embedding_width(db_path, 768)
-
- assert retire_mismatched_graph_store(config) is None
- assert db_path.exists()
-
-
-def test_reading_the_profile_from_the_wrong_field_is_an_error_not_an_absence() -> None:
- """The two replies are shaped differently, and confusing them read empty.
-
- `list_memories` wraps rows in `vdb`, `get_user_basic_info` returns them at
- the top level. Parsed with the wrong one, a store holding three profile
- facts reported none — indistinguishable from a person we know nothing
- about, which is why it went unnoticed. Now only the second of those is
- allowed to be quiet.
- """
- assert _basic_info_memories({"memories": []}) == ()
- found = _basic_info_memories(
- {"memories": [{"memory_id": "m1", "content": "c", "layer": "l0_basic_info"}]}
- )
- assert len(found) == 1
-
- for wrong in ({"vdb": {"memories": [{"memory_id": "m1"}]}}, {}, None, []):
- with pytest.raises(HyMemoryBridgeError, match="hy_memory_profile_shape_unknown"):
- _basic_info_memories(wrong)
-
-
-def test_a_snapshot_silent_about_its_width_follows_the_store_it_finds(
- tmp_path,
-) -> None:
- """Snapshots predate the width field, and one of them retired a live graph.
-
- A task carries the snapshot it was queued with, so a snapshot written
- before `embedding_dimensions` existed still runs today. Left to guess, HY
- applies its own default; a default that disagrees with the graph archives
- the graph. That happened on this machine — a 13MB store renamed aside and
- an empty one opened in its place. The store states its own geometry, so it
- is read rather than guessed.
- """
- stated = snapshot(
- ProviderKind.OLLAMA,
- base_url="http://127.0.0.1:11434",
- has_api_key=False,
- )
- silent = stated.model_copy(update={"embedding_dimensions": None})
-
- # Somewhere for the graph to already exist, built at the width the
- # snapshot that does state one would use.
- seeded = build_hy_memory_config(stated, api_key=None, data_dir=tmp_path)
- db_path = Path(seeded.graph_store.db_path)
- db_path.parent.mkdir(parents=True, exist_ok=True)
- _kuzu_graph_with_embedding_width(db_path, 768)
-
- config = build_hy_memory_config(silent, api_key=None, data_dir=tmp_path)
-
- assert config.vector_store.embedding_dims == 768
- assert config.embedder.embedding_dims == 768
- # The point of all of it: the graph survives the run.
- assert retire_mismatched_graph_store(config) is None
- assert db_path.exists()
-
-
-def test_a_snapshot_silent_about_its_width_is_left_alone_on_a_fresh_machine(
- tmp_path,
-) -> None:
- """With no store to read, there is nothing to follow and nothing to lose."""
- silent = snapshot(
- ProviderKind.OLLAMA,
- base_url="http://127.0.0.1:11434",
- has_api_key=False,
- ).model_copy(update={"embedding_dimensions": None})
-
- config = build_hy_memory_config(silent, api_key=None, data_dir=tmp_path)
-
- assert not Path(config.graph_store.db_path).exists()
-
-
-def test_remote_generation_uses_separate_local_embedding_endpoint(tmp_path) -> None:
- profile = snapshot(
- ProviderKind.OPENAI_COMPATIBLE,
- base_url="https://models.example.com/v1",
- has_api_key=True,
- embedding_provider=ProviderKind.OLLAMA,
- embedding_base_url="http://127.0.0.1:11434",
- )
-
- config = build_hy_memory_config(profile, api_key="secret", data_dir=tmp_path)
-
- assert config.llm.base_url == "https://models.example.com/v1"
- assert config.llm.api_key == "secret"
- assert config.embedder.base_url == "http://127.0.0.1:11434/v1"
- assert config.embedder.api_key == "ollama"
-
-
-def test_vector_collection_changes_with_embedding_endpoint(tmp_path) -> None:
- first = snapshot(
- ProviderKind.OPENAI_COMPATIBLE,
- base_url="https://models.example.com/v1",
- has_api_key=True,
- embedding_provider=ProviderKind.OLLAMA,
- embedding_base_url="http://127.0.0.1:11434",
- )
- second = first.model_copy(update={"embedding_base_url": "http://127.0.0.1:11435"})
-
- first_config = build_hy_memory_config(first, api_key="secret", data_dir=tmp_path)
- second_config = build_hy_memory_config(second, api_key="secret", data_dir=tmp_path)
-
- assert first_config.vector_store.collection_name != second_config.vector_store.collection_name
-
-
-def test_bridge_warm_loads_first_write_tokenizer_off_the_event_loop(tmp_path, monkeypatch) -> None:
- client = FakeHyMemoryClient({"success": True, "memory_ids": []})
- bridge = HyMemoryBridge(
- profile=snapshot(
- ProviderKind.OLLAMA,
- base_url="http://127.0.0.1:11434",
- has_api_key=False,
- ),
- api_key=None,
- data_dir=tmp_path,
- client=client,
- )
- event_loop_thread = threading.get_ident()
- calls: list[tuple[str, int]] = []
-
- from hy_memory.core import embed_service
-
- monkeypatch.setattr(
- embed_service,
- "_truncate_for_embedding",
- lambda text: calls.append((text, threading.get_ident())) or text,
- )
-
- asyncio.run(bridge.warm())
-
- assert calls == [("one-memory-warmup", calls[0][1])]
- assert calls[0][1] != event_loop_thread
-
-
-def test_bridge_returns_sdk_raw_and_memory_ids_from_one_add(tmp_path) -> None:
- client = FakeHyMemoryClient(
- {
- "success": True,
- "memory_id": "raw-1",
- "memory_ids": ["memory-1"],
- }
- )
- bridge = HyMemoryBridge(
- profile=snapshot(
- ProviderKind.OLLAMA,
- base_url="http://127.0.0.1:11434",
- has_api_key=False,
- ),
- api_key=None,
- data_dir=tmp_path,
- client=client,
- )
- request = HyMemoryIngestRequest(
- request_id="ingest-1",
- user_id="local",
- source_id="cursor",
- session_id="conversation-1",
- turns=(HyMemoryTurn(role="user", content="Remember this"),),
- evidence_ids=("evidence-1",),
- )
-
- result = asyncio.run(bridge.ingest(request))
- asyncio.run(bridge.close())
-
- assert result.raw_ids == ("raw-1",)
- assert tuple(memory.memory_id for memory in result.memories) == ("memory-1",)
- assert result.memories[0].content == "Extracted memory"
- assert client.calls[0]["agent_id"] == "one-memory"
- assert client.calls[0]["source"] == "cursor"
- assert client.calls[0]["metadata"] == {
- "source_id": "cursor",
- "evidence_ids": ["evidence-1"],
- "workspace_ids": [],
- "input_kind": "raw_conversation",
- }
- assert client.calls[0]["scene"] is None
- assert client.closed is True
-
-
-def test_bridge_refuses_bounded_outcome_scan_without_sdk_contract(tmp_path) -> None:
- client = FakeHyMemoryClient({"success": True})
- # Simulate an older SDK: bounded list scans are no longer accepted as proof.
- client.get_write_outcome = None
- client.list_result = {
- "vdb": {
- "total": 3,
- "memories": [
- {
- "memory_id": "matched",
- "content": "Recovered memory",
- "layer": "l2_fact",
- "owner": "user",
- "tags": ["recovered"],
- "user_id": "local",
- "agent_id": "one-memory",
- "custom": {"request_id": "request-1"},
- },
- {
- "memory_id": "other-request",
- "content": "Wrong request",
- "user_id": "local",
- "agent_id": "one-memory",
- "custom": {"request_id": "request-2"},
- },
- {
- "memory_id": "other-agent",
- "content": "Wrong agent",
- "user_id": "local",
- "agent_id": "other",
- "custom": {"request_id": "request-1"},
- },
- ],
- }
- }
- bridge = HyMemoryBridge(
- profile=snapshot(
- ProviderKind.OLLAMA,
- base_url="http://127.0.0.1:11434",
- has_api_key=False,
- ),
- api_key=None,
- data_dir=tmp_path,
- client=client,
- )
-
- with pytest.raises(HyMemoryBridgeError, match="hy_memory_sdk_upgrade_required"):
- asyncio.run(
- bridge.outputs_for_request(
- request_id="request-1",
- user_id="local",
- agent_id="one-memory",
- evidence_ids=("evidence-1",),
- )
- )
-
-
-def test_bridge_prefers_exact_sdk_write_outcome_over_library_scan(tmp_path) -> None:
- client = FakeHyMemoryClient({"success": True})
- client.write_outcome = {
- "request_id": "request-1",
- "user_id": "local",
- "agent_id": "one-memory",
- "status": "succeeded",
- "result": {"success": True, "memory_ids": ["memory-1"]},
- }
- bridge = HyMemoryBridge(
- profile=snapshot(
- ProviderKind.OLLAMA,
- base_url="http://127.0.0.1:11434",
- has_api_key=False,
- ),
- api_key=None,
- data_dir=tmp_path,
- client=client,
- )
-
- outputs = asyncio.run(
- bridge.outputs_for_request(
- request_id="request-1",
- user_id="local",
- agent_id="one-memory",
- evidence_ids=("evidence-1",),
- )
- )
-
- assert [output.memory_id for output in outputs] == ["memory-1"]
- assert outputs[0].evidence_ids == ("evidence-1",)
- assert not any("list_memories" in call for call in client.calls)
-
-
-def test_bridge_reads_sdk_memory_lifecycle_without_governance(tmp_path) -> None:
- client = FakeHyMemoryClient({"success": True})
- client.list_result = {
- "vdb": {
- "total": 1,
- "memories": [
- {
- "memory_id": "old-memory",
- "content": "Old wording",
- "layer": "l2_fact",
- "status": "superseded",
- "is_latest": False,
- "superseded_by": ["new-memory"],
- "user_id": "local",
- "agent_id": "one-memory",
- "session_id": "session-1",
- "tags": ["preference"],
- "owner": "user",
- "custom": {
- "source_raw_memory_ids": ["raw-1", "raw-2"],
- },
- }
- ],
- }
- }
- bridge = HyMemoryBridge(
- profile=snapshot(
- ProviderKind.OLLAMA,
- base_url="http://127.0.0.1:11434",
- has_api_key=False,
- ),
- api_key=None,
- data_dir=tmp_path,
- client=client,
- )
-
- page = asyncio.run(
- bridge.list_sdk_memories(
- user_id="local",
- statuses=("superseded",),
- limit=20,
- )
- )
-
- assert page.total == 1
- assert page.memories[0].status == "superseded"
- assert page.memories[0].superseded_by == ("new-memory",)
- assert page.memories[0].owner == "user"
- assert page.memories[0].source_raw_ids == ("raw-1", "raw-2")
- assert client.calls[-1]["list_memories"]["statuses"] == ["superseded"]
-
-
-def test_bridge_reads_raw_and_write_outcome_through_public_sdk(tmp_path) -> None:
- client = FakeHyMemoryClient({"success": True})
- client.write_outcome = {
- "request_id": "request-1",
- "status": "succeeded",
- "result": {"success": True, "memory_ids": ["memory-1"]},
- }
- client.raw_result = {
- "raw_id": "raw-1",
- "content": "verbatim",
- "user_id": "local",
- "agent_id": "one-memory",
- "session_id": "session-1",
- "source": "cursor",
- "custom": {"role": "user"},
- }
- client.raw_list_result = {"raw": [client.raw_result], "total": 1}
- bridge = HyMemoryBridge(
- profile=snapshot(
- ProviderKind.OLLAMA,
- base_url="http://127.0.0.1:11434",
- has_api_key=False,
- ),
- api_key=None,
- data_dir=tmp_path,
- client=client,
- )
-
- outcome = asyncio.run(bridge.get_sdk_write_outcome("request-1"))
- raw = asyncio.run(bridge.get_sdk_raw("raw-1"))
- rows, total = asyncio.run(bridge.list_sdk_raw(user_id="local"))
-
- assert outcome["status"] == "succeeded"
- assert raw.content == "verbatim"
- assert raw.custom == {"role": "user"}
- assert total == 1
- assert rows == (raw,)
-
-
-def test_bridge_searches_raw_through_existing_sdk_search_and_source_filter(tmp_path) -> None:
- client = FakeHyMemoryClient(
- {"success": True},
- search_result={
- "scene": "chat",
- "memories": {
- "schema": [],
- "proactive": [],
- "normal": [
- {
- "memory_id": "raw-1",
- "content": "verbatim",
- "layer": "l1_raw",
- "status": "active",
- "score": 0.8,
- "user_id": "local",
- "agent_id": "one-memory",
- "session_id": "session",
- "source": "cursor",
- "custom": {"role": "user"},
- }
- ],
- },
- },
- )
- bridge = HyMemoryBridge(
- profile=snapshot(
- ProviderKind.OLLAMA,
- base_url="http://127.0.0.1:11434",
- has_api_key=False,
- ),
- api_key=None,
- data_dir=tmp_path,
- client=client,
- )
-
- hits = asyncio.run(
- bridge.search_sdk_raw(
- "query",
- user_id="local",
- source_ids=("cursor",),
- )
- )
-
- assert hits[0].raw_id == "raw-1"
- assert hits[0].content == "verbatim"
- assert client.search_calls[-1]["layers"] == ["l1_raw"]
- assert client.search_calls[-1]["include_sources"] == ["cursor"]
-
-
-def test_bridge_imports_legacy_memory_exactly_without_governance(tmp_path) -> None:
- client = FakeHyMemoryClient({"success": True})
- bridge = HyMemoryBridge(
- profile=snapshot(
- ProviderKind.OLLAMA,
- base_url="http://127.0.0.1:11434",
- has_api_key=False,
- ),
- api_key=None,
- data_dir=tmp_path,
- client=client,
- )
-
- result = asyncio.run(
- bridge.import_sdk_memory_exact(
- content="old preference",
- memory_id="memory-1",
- user_id="local",
- agent_id="one-memory",
- session_id="session-1",
- layer="l2_fact",
- status="superseded",
- owner="user",
- tags=("preference",),
- supersedes=(),
- superseded_by=("memory-2",),
- is_latest=False,
- request_id="migration-request",
- )
- )
-
- assert result["memory_id"] == "memory-1"
- call = client.calls[-1]
- assert call["import_memory_exact"] == "old preference"
- assert call["status"] == "superseded"
- assert call["superseded_by"] == ["memory-2"]
-
-
-def test_hy_failure_log_identifies_stage_without_provider_content(tmp_path, monkeypatch) -> None:
- monkeypatch.setenv("ONE_MEMORY_DIAGNOSTICS", "1")
- receipt = configure_diagnostics(
- tmp_path,
- session_id="11111111-1111-4111-8111-111111111111",
- )
- bridge = HyMemoryBridge(
- profile=snapshot(
- ProviderKind.OLLAMA,
- base_url="http://127.0.0.1:11434",
- has_api_key=False,
- ),
- api_key=None,
- data_dir=tmp_path,
- client=FailingHyMemoryClient({}),
- )
- request = HyMemoryIngestRequest(
- request_id="ingest-failure-1",
- user_id="local",
- source_id="cursor",
- session_id="conversation-1",
- turns=(HyMemoryTurn(role="user", content="private input"),),
- evidence_ids=("evidence-1",),
- )
- try:
- with pytest.raises(HyMemoryBridgeError, match="hy_memory_runtime_failed"):
- asyncio.run(bridge.ingest(request))
- finally:
- reset_diagnostics()
- written = receipt.path.read_text()
- events = [json.loads(line) for line in written.splitlines()]
- assert events[-1]["event"] == "hy.ingest_failed"
- assert events[-1]["request_id"] == "ingest-failure-1"
- assert events[-1]["error_type"] == "RuntimeError"
- assert "private-provider-response-918273" not in written
- assert "private input" not in written
-
-
-def test_hy_bridge_preserves_profile_stopping_model_error(tmp_path) -> None:
- from types import SimpleNamespace
-
- class PaymentRequiredClient(FakeHyMemoryClient):
- def add(self, *args, **kwargs):
- self._one_memory_write_guards[0].failures.append("hy_memory_model_payment_required")
- raise RuntimeError("private provider body")
-
- client = PaymentRequiredClient({})
- client._one_memory_write_guards = [SimpleNamespace(failures=[])]
- bridge = HyMemoryBridge(
- profile=snapshot(
- ProviderKind.OLLAMA,
- base_url="http://127.0.0.1:11434",
- has_api_key=False,
- ),
- api_key=None,
- data_dir=tmp_path,
- client=client,
- )
- request = HyMemoryIngestRequest(
- request_id="payment-required",
- user_id="local",
- source_id="cursor",
- session_id="conversation-1",
- turns=(HyMemoryTurn(role="user", content="private input"),),
- evidence_ids=("evidence-1",),
- )
-
- with pytest.raises(HyMemoryBridgeError, match="^hy_memory_model_payment_required$"):
- asyncio.run(bridge.ingest(request))
-
-
-def test_swallowed_hy_model_error_never_becomes_successful_governance_input(tmp_path):
- from types import SimpleNamespace
-
- class Client(FakeHyMemoryClient):
- def add(self, *args, **kwargs):
- self._one_memory_write_guards[0].failures.append("hy_memory_model_output_truncated")
- return super().add(*args, **kwargs)
-
- client = Client({"success": True, "memory_ids": ["raw-only"]})
- client._one_memory_write_guards = [SimpleNamespace(failures=[])]
- bridge = HyMemoryBridge(
- profile=snapshot(ProviderKind.OLLAMA, base_url="http://127.0.0.1:11434", has_api_key=False),
- api_key=None,
- data_dir=tmp_path,
- client=client,
- )
- request = HyMemoryIngestRequest(
- request_id="swallowed-error",
- user_id="local",
- source_id="fixture",
- session_id="session",
- evidence_ids=("e1",),
- turns=(HyMemoryTurn(role="user", content="Input must be fully processed."),),
- )
- with pytest.raises(HyMemoryBridgeError, match="hy_memory_model_output_truncated"):
- asyncio.run(bridge.ingest(request))
-
-
-def test_raw_hy_log_is_not_an_extracted_memory_when_no_durable_fact_was_produced(tmp_path):
- class Client(FakeHyMemoryClient):
- def get(self, memory_id):
- return {**super().get(memory_id), "layer": "L1_RAW"}
-
- client = Client({"success": True, "memory_id": "raw-log"})
- bridge = HyMemoryBridge(
- profile=snapshot(ProviderKind.OLLAMA, base_url="http://127.0.0.1:11434", has_api_key=False),
- api_key=None,
- data_dir=tmp_path,
- client=client,
- )
- request = HyMemoryIngestRequest(
- request_id="raw-only",
- user_id="local",
- source_id="fixture",
- session_id="session",
- evidence_ids=("e1",),
- turns=(HyMemoryTurn(role="user", content="Hello"),),
- )
- result = asyncio.run(bridge.ingest(request))
- assert result.memories == ()
-
-
-def test_native_read_preserves_owner_from_same_stored_node():
- from types import SimpleNamespace
-
- from one_memory.hy_memory_bridge import _read_hy_record
-
- class Store:
- async def get_by_id(self, memory_id):
- return SimpleNamespace(
- content="Agent proposed this", owner="agent", user_id="local", agent_id="one-memory"
- )
-
- client = SimpleNamespace(
- get=lambda key: {
- "memory_id": key,
- "content": "Agent proposed this",
- "source": "vdb",
- "user_id": "local",
- "agent_id": "one-memory",
- },
- _loop_thread=SimpleNamespace(run=asyncio.run),
- _vector_store=Store(),
- )
- assert _read_hy_record(client, "m")["owner"] == "agent"
-
-
-def test_bridge_imports_existing_content_without_running_extractor(tmp_path) -> None:
- client = FakeHyMemoryClient({"success": True, "memory_ids": ["memory-1"]})
- bridge = HyMemoryBridge(
- profile=snapshot(
- ProviderKind.OLLAMA,
- base_url="http://127.0.0.1:11434",
- has_api_key=False,
- ),
- api_key=None,
- data_dir=tmp_path,
- client=client,
- )
- request = HyMemoryIngestRequest(
- request_id="ingest-fast-1",
- user_id="local",
- source_id="cursor",
- session_id="conversation-1",
- turns=(HyMemoryTurn(role="user", content="我偏好简洁文案。"),),
- evidence_ids=("evidence-1",),
- )
-
- result = asyncio.run(bridge.ingest_extracted(request, ("用户偏好简洁文案。",)))
-
- assert tuple(memory.memory_id for memory in result.memories) == ("memory-1",)
- assert client.calls[0]["contents"] == ["用户偏好简洁文案。"]
- assert client.calls[0]["metadata"] == {
- "source_id": "cursor",
- "evidence_ids": ["evidence-1"],
- "workspace_ids": [],
- "input_kind": "memory_content_without_raw",
- }
-
-
[email protected]("fails", [False, True])
-def test_import_binding_is_cleared_after_success_or_native_exception(tmp_path, fails):
- from one_memory.hy_response_guard import HyReconcileGuard
-
- guard = HyReconcileGuard(None)
-
- class Client(FakeHyMemoryClient):
- _one_memory_write_guards = (guard,)
-
- def add_extracted(self, contents, **kwargs):
- assert guard.imported_contents == frozenset({"existing report"})
- if fails:
- raise RuntimeError("native failure")
- return super().add_extracted(contents, **kwargs)
-
- client = Client({"success": True, "memory_ids": []})
- bridge = HyMemoryBridge(
- profile=snapshot(ProviderKind.OLLAMA, base_url="http://127.0.0.1:11434", has_api_key=False),
- api_key=None,
- data_dir=tmp_path,
- client=client,
- )
- request = HyMemoryIngestRequest(
- request_id="r",
- user_id="local",
- source_id="memory-content-export",
- session_id="s",
- turns=(HyMemoryTurn(role="assistant", content="existing report"),),
- evidence_ids=("e",),
- )
- if fails:
- with pytest.raises(HyMemoryBridgeError):
- asyncio.run(bridge.ingest_extracted(request, (" existing report\n",)))
- else:
- asyncio.run(bridge.ingest_extracted(request, (" existing report\n",)))
- assert client.search_calls[0]["query"] == "existing report"
- assert guard.imported_contents is None
-
-
-def test_bridge_returns_machine_error_without_provider_body(tmp_path) -> None:
- client = FakeHyMemoryClient(
- {
- "success": False,
- "error_code": "unavailable",
- "error": "provider response containing private prompt",
- }
- )
- bridge = HyMemoryBridge(
- profile=snapshot(
- ProviderKind.OLLAMA,
- base_url="http://127.0.0.1:11434",
- has_api_key=False,
- ),
- api_key=None,
- data_dir=tmp_path,
- client=client,
- )
- request = HyMemoryIngestRequest(
- request_id="ingest-1",
- user_id="local",
- source_id="cursor",
- session_id="conversation-1",
- turns=(HyMemoryTurn(role="user", content="private prompt"),),
- evidence_ids=("evidence-1",),
- )
-
- with pytest.raises(HyMemoryBridgeError) as captured:
- asyncio.run(bridge.ingest(request))
-
- assert str(captured.value) == "hy_memory_unavailable"
- assert "private prompt" not in str(captured.value)
-
-
-def test_bridge_rejects_deduplicated_memory_from_another_request(tmp_path) -> None:
- client = FakeHyMemoryClient(
- {"success": True, "memory_ids": ["stale-memory"]},
- record_request_id="another-request",
- )
- bridge = HyMemoryBridge(
- profile=snapshot(
- ProviderKind.OLLAMA,
- base_url="http://127.0.0.1:11434",
- has_api_key=False,
- ),
- api_key=None,
- data_dir=tmp_path,
- client=client,
- )
- request = HyMemoryIngestRequest(
- request_id="current-request",
- user_id="local",
- source_id="cursor",
- session_id="conversation-1",
- turns=(HyMemoryTurn(role="user", content="Current evidence"),),
- evidence_ids=("evidence-1",),
- )
-
- result = asyncio.run(bridge.ingest(request))
-
- assert result.memories == ()
-
-
-def test_extracted_bridge_accepts_exact_deduplicated_fact_for_same_scope(
- tmp_path,
-) -> None:
- client = FakeHyMemoryClient(
- {"success": True, "memory_ids": ["existing-memory"]},
- record_request_id="another-request",
- )
- bridge = HyMemoryBridge(
- profile=snapshot(
- ProviderKind.OLLAMA,
- base_url="http://127.0.0.1:11434",
- has_api_key=False,
- ),
- api_key=None,
- data_dir=tmp_path,
- client=client,
- )
- request = HyMemoryIngestRequest(
- request_id="current-request",
- user_id="local",
- source_id="cursor",
- session_id="conversation-1",
- turns=(HyMemoryTurn(role="user", content="Original evidence"),),
- evidence_ids=("evidence-1",),
- )
-
- result = asyncio.run(bridge.ingest_extracted(request, ("Extracted memory",)))
-
- assert tuple(memory.memory_id for memory in result.memories) == ("existing-memory",)
-
-
-def test_extracted_bridge_finds_exact_noop_memory_when_sdk_returns_no_id(
- tmp_path,
-) -> None:
- client = FakeHyMemoryClient(
- {"success": True, "memory_ids": []},
- search_result={
- "results": [
- {
- "memory_id": "existing-memory",
- "content": "Extracted memory",
- "layer": "L2_FACT",
- "user_id": "local",
- "agent_id": "one-memory",
- "custom": {"request_id": "older-request"},
- }
- ]
- },
- )
- bridge = HyMemoryBridge(
- profile=snapshot(
- ProviderKind.OLLAMA,
- base_url="http://127.0.0.1:11434",
- has_api_key=False,
- ),
- api_key=None,
- data_dir=tmp_path,
- client=client,
- )
- request = HyMemoryIngestRequest(
- request_id="current-request",
- user_id="local",
- source_id="cursor",
- session_id="conversation-1",
- turns=(HyMemoryTurn(role="user", content="Original evidence"),),
- evidence_ids=("evidence-1",),
- )
-
- result = asyncio.run(bridge.ingest_extracted(request, ("Extracted memory",)))
-
- assert tuple(memory.memory_id for memory in result.memories) == ("existing-memory",)
-
-
-def test_bridge_cascade_delete_calls_hy_memory(tmp_path) -> None:
- from types import SimpleNamespace
-
- from tests.hy_stores import chroma_store
-
- client = FakeHyMemoryClient({"success": True})
-
- def points(*, ids, include=None):
- return {"ids": [] if "memory-to-delete" in client.deleted else list(ids)}
-
- # Deletion is read back from HY's stores themselves, not through `get`.
- client._loop_thread = SimpleNamespace(run=asyncio.run)
- client._vector_store = chroma_store(points)
- client._graph_store = None
- bridge = HyMemoryBridge(
- profile=snapshot(
- ProviderKind.OLLAMA,
- base_url="http://127.0.0.1:11434",
- has_api_key=False,
- ),
- api_key=None,
- data_dir=tmp_path,
- client=client,
- )
-
- result = asyncio.run(bridge.delete("memory-to-delete"))
-
- assert result["success"] is True
- assert client.calls == [{"delete_memory_id": "memory-to-delete"}]
-
-
-def test_bridge_update_rewrites_in_place_and_keeps_the_id(tmp_path) -> None:
- """A correction must not become a delete and an add.
-
- HY re-embeds the same node, so every id already handed out — evidence
- links, recall receipts, whatever a host wrote down — still resolves.
- """
- client = FakeHyMemoryClient({"success": True})
- bridge = HyMemoryBridge(
- profile=snapshot(
- ProviderKind.OLLAMA,
- base_url="http://127.0.0.1:11434",
- has_api_key=False,
- ),
- api_key=None,
- data_dir=tmp_path,
- client=client,
- )
-
- result = asyncio.run(bridge.update("memory-to-correct", "用户的花名是白泽"))
-
- assert result["success"] is True
- assert client.calls == [
- {
- "update_memory_id": "memory-to-correct",
- "update_content": "用户的花名是白泽",
- }
- ]
-
-
-def test_hy_saying_it_did_not_update_is_not_read_as_a_success(tmp_path) -> None:
- """HY answers `success: False` for a memory its vector store never held,
- without raising. Passing that back as a normal result would have the
- caller record an index that matches when nothing was written."""
- client = FakeHyMemoryClient({"success": True})
- client.update_succeeds = False
- bridge = HyMemoryBridge(
- profile=snapshot(
- ProviderKind.OLLAMA,
- base_url="http://127.0.0.1:11434",
- has_api_key=False,
- ),
- api_key=None,
- data_dir=tmp_path,
- client=client,
- )
-
- with pytest.raises(HyMemoryBridgeError) as error:
- asyncio.run(bridge.update("memory-hy-never-had", "用户的花名是白泽"))
-
- assert str(error.value) == "hy_memory_update_rejected"
-
-
-def test_bridge_semantic_search_can_span_isolated_hy_agents(tmp_path) -> None:
- client = FakeHyMemoryClient(
- {"success": True},
- search_result={
- "memories": [
- {"memory_id": "semantic-1"},
- {"memory_id": "semantic-1"},
- {"memory_id": "semantic-2"},
- ]
- },
- )
- bridge = HyMemoryBridge(
- profile=snapshot(
- ProviderKind.OLLAMA,
- base_url="http://127.0.0.1:11434",
- has_api_key=False,
- ),
- api_key=None,
- data_dir=tmp_path,
- client=client,
- )
-
- memory_ids = asyncio.run(
- bridge.search_ids(
- "我的长期偏好是什么?",
- user_id="local",
- agent_id="*",
- )
- )
-
- assert memory_ids == ("semantic-1", "semantic-2")
- assert client.search_calls[0]["agent_ids"] == []
- assert client.search_calls[0]["reader"] == "hybrid"
- assert client.search_calls[0]["schema_min_score"] == client.search_calls[0]["min_score"]
- assert client.search_calls[0]["schema_limit"] == 12
- assert "profile_min_score" not in client.search_calls[0]
- assert "profile_limit" not in client.search_calls[0]
-
-
-def test_bridge_preserves_sdk_formatted_search_content(tmp_path) -> None:
- formatted = "Memory: 用户偏好本地优先。\nWhen: 2026-09-12 08:00:00 UTC"
- client = FakeHyMemoryClient(
- {"success": True},
- search_result={
- "memories": [
- {
- "memory_id": "semantic-1",
- "content": formatted,
- "score": 0.91,
- "memory_at": 1789200000,
- }
- ]
- },
- )
- bridge = HyMemoryBridge(
- profile=snapshot(
- ProviderKind.OLLAMA,
- base_url="http://127.0.0.1:11434",
- has_api_key=False,
- ),
- api_key=None,
- data_dir=tmp_path,
- client=client,
- )
-
- hits = asyncio.run(
- bridge.search_memories(
- "我的长期偏好是什么?",
- user_id="local",
- agent_id="*",
- )
- )
-
- assert hits[0].formatted_content == formatted
- assert hits[0].sdk_formatted is True
- assert hits[0].formatting_complete is True
-
-
-def test_search_ids_does_not_create_nodes_tasks_or_collections(tmp_path) -> None:
- """Search is a read. Creating store objects here would invent a graph.
-
- A query that only needs IDs must not add memories, digest System 2,
- open a new collection, or enqueue a task. The fake records those
- mutations; this test is meaningless unless a write on the search
- path would turn it red.
- """
- client = FakeHyMemoryClient(
- {"success": True},
- search_result={"memories": [{"memory_id": "semantic-read-only"}]},
- )
- bridge = HyMemoryBridge(
- profile=snapshot(
- ProviderKind.OLLAMA,
- base_url="http://127.0.0.1:11434",
- has_api_key=False,
- ),
- api_key=None,
- data_dir=tmp_path,
- client=client,
- )
-
- memory_ids = asyncio.run(
- bridge.search_ids(
- "我的长期偏好是什么?",
- user_id="local",
- agent_id="*",
- )
- )
-
- assert memory_ids == ("semantic-read-only",)
- assert len(client.search_calls) == 1
- assert client.calls == []
-
-
-def test_anthropic_profile_is_not_claimed_supported_by_current_sdk(
- tmp_path,
-) -> None:
- profile = snapshot(
- ProviderKind.ANTHROPIC,
- base_url="https://api.anthropic.com",
- has_api_key=True,
- )
-
- with pytest.raises(UnsupportedHyMemoryProviderError):
- build_hy_memory_config(profile, api_key="secret", data_dir=tmp_path)
-
-
-def test_hy_default_does_not_fall_back_to_ambient_openai(
- tmp_path,
- monkeypatch,
-) -> None:
- monkeypatch.setenv("OPENAI_API_KEY", "ambient-secret")
- profile = snapshot(
- ProviderKind.HY_DEFAULT,
- base_url=None,
- has_api_key=False,
- )
-
- with pytest.raises(UnsupportedHyMemoryProviderError) as captured:
- build_hy_memory_config(profile, api_key=None, data_dir=tmp_path)
-
- assert str(captured.value) == "hy_default_not_available"
-
-
-def test_hy_environment_confines_logs_and_disables_telemetry(
- tmp_path,
- monkeypatch,
-) -> None:
- monkeypatch.setenv("MEMORY_LOG_DIR", "/tmp/hostile")
- monkeypatch.setenv("CHROMA_OTEL_COLLECTION_ENDPOINT", "https://collector.example")
-
- configure_hy_memory_environment(tmp_path)
-
- expected_root = str((tmp_path / "hy-memory" / "governed-v2").resolve())
- assert os.environ["MEMORY_DATA_DIR"] == expected_root
- assert os.environ["MEMORY_LOG_DIR"] == f"{expected_root}/logs"
- assert os.environ["MEMORY_LOG_LEVEL"] == "INFO"
- assert os.environ["ANONYMIZED_TELEMETRY"] == "False"
- assert "CHROMA_OTEL_COLLECTION_ENDPOINT" not in os.environ
-
-
-def test_hy_runtime_matches_public_sdk_without_reranker_or_service_backends(
- tmp_path,
- monkeypatch,
-) -> None:
- monkeypatch.setenv("MEMORY_VECTOR_STORE", "qdrant")
- monkeypatch.setenv("MEMORY_CACHE_BACKEND", "mysql")
- monkeypatch.setenv("MEMORY_GRAPH_PROVIDER", "neo4j")
- monkeypatch.setenv("MEMORY_MYSQL_PASSWORD", "ambient-database-secret")
- monkeypatch.setenv("NEO4J_PASSWORD", "ambient-graph-secret")
- monkeypatch.setenv("MEMORY_LOCAL_RERANK_ENABLED", "true")
- monkeypatch.setenv("MEMORY_GRAPH_RERANK_ENABLED", "true")
- monkeypatch.setenv("MEMORY_LLM_API_KEY", "ambient-secret")
- monkeypatch.setenv("MEMORY_LLM_EXTRA_HEADERS", '{"Authorization":"ambient"}')
- monkeypatch.setenv("MEMORY_EMBEDDER_EXTRA_HEADERS", '{"X-Ambient":"true"}')
- monkeypatch.setenv("MEMORY_EMBEDDER_EXTRA_BODY", '{"route":"ambient"}')
- profile = snapshot(
- ProviderKind.OLLAMA,
- base_url="http://127.0.0.1:11434",
- has_api_key=False,
- )
-
- configure_hy_memory_environment(tmp_path)
- config = build_hy_memory_config(profile, api_key=None, data_dir=tmp_path)
-
- assert HY_MEMORY_DISTRIBUTION == "hy-memory"
- assert HY_MEMORY_VERSION == "2.0.5.dev3"
- assert HY_MEMORY_MODE == "ultra"
- assert HY_MEMORY_READER == "hybrid"
- assert os.environ["MEMORY_MODE"] == "ultra"
- # The graph store is closed by default (see `graph_store_enabled`): opening
- # kuzu is what produced the teardown crash. `ultra` would force it open, so
- # the mode moves to `pro` and the graph stays off until someone opts in.
- assert os.environ["MEMORY_ENABLE_GRAPH"] == "false"
- assert config.mode == "pro"
- assert os.environ["HY_MEMORY_READER"] == "hybrid"
- assert os.environ["MEMORY_ENABLE_INTENTION"] == "false"
- assert os.environ["MEMORY_FEW_SHOT_ENABLED"] == "true"
- assert os.environ["MEMORY_HYBRID_V2_QUERY_EXPAND"] == "1"
- assert os.environ["MEMORY_HYBRID_V2_GEO_INTENT_PRIOR"] == "0.6"
- assert os.environ["MEMORY_HYBRID_V2_DIVERSITY"] == "1"
- assert os.environ["MEMORY_HYBRID_V2_TEMPORAL_ADMIT_PRIOR"] == "0.55"
- assert os.environ["MEMORY_HYBRID_V2_TEMPORAL_BOOST"] == "0.18"
- assert os.environ["MEMORY_CROSS_DOMAIN_CON_THRESHOLD"] == "0.5"
- assert os.environ["MEMORY_READER_ENABLE_SUMMARY"] == "false"
- assert os.environ["MEMORY_EPISODE_RECALL_ENABLED"] == "true"
- assert os.environ["MEMORY_DYNAMIC_EPISODE_ENABLED"] == "true"
- assert os.environ["MEMORY_EPISODE_CAPSULE_CONTEXT_ENABLED"] == "true"
- assert os.environ["MEMORY_LOCAL_RERANK_ENABLED"] == "false"
- assert os.environ["MEMORY_GRAPH_RERANK_ENABLED"] == "false"
- assert config.vector_store.provider == "chroma"
- assert config.cache.backend == "sqlite"
- assert config.cache.mysql_password is None
- assert config.graph_store.provider == "kuzu"
- assert config.graph_store.password is None
- assert config.llm.api_key == "ollama"
- assert config.llm.extra_headers is None
- assert config.llm.eval_user is None
- assert config.llm.eval_apikey is None
- assert config.llm.few_shot_enabled is True
- assert config.llm.enable_query_rewrite is False
- assert config.llm.enable_intention is False
- assert config.recall.episode_recall_enabled is True
- assert config.recall.dynamic_episode_enabled is True
- assert config.recall.episode_capsule_context_enabled is True
- assert config.recall.strength_enabled is False
- assert config.recall.access_tracking_enabled is False
- assert config.recall.local_rerank_enabled is False
- assert config.graph_store.graph_rerank_enabled is False
- assert config.embedder.extra_headers is None
- assert config.embedder.extra_body is None
- assert config.api.api_keys == []
-
-
-def test_ingest_refuses_a_request_whose_workspace_ids_disagree_with_the_context(tmp_path):
- """The bridge identity check must include the workspace set.
-
- HyWriteBindings already refuses a context that mixes workspaces, but the
- bridge's own request-compatibility check compared only
- (user_id, source_id, conversation_id). A request could therefore declare a
- different `workspace_ids` than the bound context and still be sent to HY,
- so HY would scope the write to a workspace the evidence never came from.
- The bridge must refuse that disagreement, exactly as it refuses a
- conversation/source mismatch.
- """
- from one_memory.hy_source_context import HySourceContext
- from one_memory.imports.models import (
- EvidenceInput,
- EvidenceOrigin,
- OriginMetadata,
- WrittenBy,
- )
- from one_memory.imports.storage import EvidenceStore
-
- store = EvidenceStore(tmp_path / "evidence.db")
- record = store.put(
- EvidenceInput(
- source_id="cursor",
- workspace="workspace:v1:project-a",
- conversation_id="atlas",
- message_id="now",
- role="user",
- written_by=WrittenBy.PERSON,
- verbatim="项目 A 的一轮。",
- origin_meta={EvidenceOrigin.FILE: OriginMetadata()},
- )
- ).record
- client = FakeHyMemoryClient(
- {
- "success": True,
- "memories": [
- {
- "content": "项目 A 的一轮。",
- "owner": "user",
- "memory_id": "m1",
- "layer": "working_fact",
- }
- ],
- }
- )
- bridge = HyMemoryBridge(
- profile=snapshot(ProviderKind.OLLAMA, base_url="http://127.0.0.1:11434", has_api_key=False),
- api_key=None,
- data_dir=tmp_path,
- client=client,
- )
- request = HyMemoryIngestRequest(
- request_id="ingest-1",
- user_id="local",
- source_id="cursor",
- session_id="atlas",
- turns=(HyMemoryTurn(role="user", content="项目 A 的一轮。"),),
- evidence_ids=(record.evidence_id,),
- # The bound context is project-a; the request lies and says project-b.
- workspace_ids=("workspace:v1:project-b",),
- source_context=HySourceContext(current=(record,)),
- )
- with pytest.raises(HyMemoryBridgeError, match="hy_memory_write_verification_context_scope"):
- asyncio.run(bridge.ingest(request))
- assert client.calls == [], "a workspace-mismatched request must not reach HY"
-
-
-def test_the_graph_store_stays_closed_by_default(monkeypatch) -> None:
- """The packaged app sets nothing, so kuzu must not be opened."""
- from one_memory.hy_memory_bridge import graph_store_enabled
-
- monkeypatch.delenv("ONE_MEMORY_GRAPH_STORE", raising=False)
- assert graph_store_enabled() is False
-
-
-def test_the_graph_store_opens_only_when_opted_in(monkeypatch) -> None:
- from one_memory.hy_memory_bridge import graph_store_enabled
-
- monkeypatch.setenv("ONE_MEMORY_GRAPH_STORE", "kuzu")
- assert graph_store_enabled() is True
- monkeypatch.setenv("ONE_MEMORY_GRAPH_STORE", "none")
- assert graph_store_enabled() is False
-
-
-def test_the_client_mode_follows_the_graph_store_switch(tmp_path, monkeypatch) -> None:
- """`ultra` forces kuzu open, so the mode handed to HY must not be constant.
-
- build_hy_memory_config picks the mode from `graph_store_enabled`, but the
- client was constructed with `HY_MEMORY_MODE` hard-coded, which reopened
- the graph the config had just closed. The packaged app then segfaulted in
- kuzu::main::Database::~Database(). Assert on the value HY actually
- receives, so the switch cannot silently stop being wired again.
- """
- from one_memory import hy_memory_bridge
-
- seen: list[str] = []
-
- class ModeSpyClient:
- def __init__(self, *, config, mode, runtime=None):
- del config
- assert runtime is not None
- seen.append(mode)
-
- def close(self) -> None:
- pass
-
- real_import = hy_memory_bridge.import_module
-
- def fake_import(name: str):
- if name == "hy_memory.client":
- return SimpleNamespace(HyMemoryClient=ModeSpyClient)
- return real_import(name)
-
- monkeypatch.setattr(hy_memory_bridge, "import_module", fake_import)
- monkeypatch.setattr(hy_memory_bridge, "_shared_hy_runtime", lambda *args: object())
- monkeypatch.setattr(hy_memory_bridge, "_release_shared_hy_runtime", lambda *args: None)
- monkeypatch.setattr(hy_memory_bridge, "reattach_legacy_vector_collection", lambda *args: None)
- monkeypatch.setattr(hy_memory_bridge, "inspect_graph_width_mismatch", lambda *args: None)
- monkeypatch.setattr(
- "one_memory.hy_response_guard.install_hy_write_guards", lambda _client: None
- )
- profile = snapshot(
- ProviderKind.OLLAMA,
- base_url="http://127.0.0.1:11434",
- has_api_key=False,
- )
-
- monkeypatch.delenv("ONE_MEMORY_GRAPH_STORE", raising=False)
- hy_memory_bridge.create_hy_memory_client(profile, api_key=None, data_dir=tmp_path).close()
-
- monkeypatch.setenv("ONE_MEMORY_GRAPH_STORE", "kuzu")
- hy_memory_bridge.create_hy_memory_client(profile, api_key=None, data_dir=tmp_path).close()
-
- assert seen == ["pro", HY_MEMORY_MODE]
-
-
-def test_native_mutation_delta_reports_coding_deletes_and_supersedes() -> None:
- raw = {
- "ops": [
- {
- "action": "DELETE",
- "target_experience_id": "old-experience",
- }
- ],
- "fact_ops": [
- {
- "action": "SUPERSEDE",
- "fact_id": "old-fact",
- "superseded_by": "new-fact",
- }
- ],
- }
-
- result = asyncio.run(
- _with_native_mutation_delta(
- SimpleNamespace(),
- HyMemoryIngestResult(success=True),
- raw,
- (),
- )
- )
-
- assert result.retired_memory_ids == ("old-experience", "old-fact")
- assert result.superseded_memory_ids == {"old-fact": ("new-fact",)}
-
-
-def test_native_mutation_delta_reads_chat_status_from_the_sdk() -> None:
- class Client:
- def get(self, memory_id: str) -> Mapping[str, object]:
- assert memory_id == "old-chat"
- return {
- "memory_id": memory_id,
- "content": "old",
- "status": "superseded",
- "superseded_by": ["new-chat"],
- }
-
- guard = SimpleNamespace(mutation_target_ids={"old-chat"})
- result = asyncio.run(
- _with_native_mutation_delta(
- Client(),
- HyMemoryIngestResult(success=True),
- {},
- (guard,),
- )
- )
-
- assert result.retired_memory_ids == ("old-chat",)
- assert result.superseded_memory_ids == {"old-chat": ("new-chat",)}
diff --git a/memhub/apps/core/tests/test_hy_metrics_lifecycle.py b/memhub/apps/core/tests/test_hy_metrics_lifecycle.py
deleted file mode 100644
index b3dc9e0..0000000
--- a/memhub/apps/core/tests/test_hy_metrics_lifecycle.py
+++ /dev/null
@@ -1,113 +0,0 @@
-"""What the pinned public SDK's MetricsCollector does, and what that costs us.
-
-These integration tests ask whether the pending-task warning is a leak that
-grows per request, and whether reusing one client is enough to avoid it.
-Reading the warning alone cannot answer either question, so the tests measure it.
-
-The answer that came out is narrower and worse than "a leak": the collector is
-a process singleton, so the two loops start once rather than once per client --
-but the flag that says "already started" is sticky and there is no stop. Once
-the loop those tasks were created on is gone, a later loop gets nothing, and
-flush and cleanup are silently dead for the rest of the process.
-
-That makes reusing the client necessary but not sufficient: what has to survive
-is the event loop. These tests pin both halves so an SDK upgrade that fixes it
-shows up as a failure here instead of going unnoticed.
-"""
-
-from __future__ import annotations
-
-import asyncio
-from pathlib import Path
-
-import pytest
-
-pytest.importorskip("hy_memory")
-
-
-def background_loop_count() -> int:
- return sum(
- 1
- for task in asyncio.all_tasks()
- if task.get_coro() is not None
- and (task.get_coro().__qualname__ or "").startswith("MetricsCollector._")
- )
-
-
-def test_the_collector_is_one_per_process_not_one_per_client() -> None:
- """If it were per-client, reusing the client would be the whole fix."""
- from hy_memory.metrics import MetricsCollector
-
- assert MetricsCollector.get() is MetricsCollector.get()
-
-
-def test_metrics_collector_can_stop_and_restart_on_a_second_event_loop(
- monkeypatch,
-) -> None:
- """The current SDK owns an explicit lifecycle and restarts cleanly."""
- from hy_memory.metrics import MetricsCollector
-
- # A fresh collector, so an earlier test in the session cannot decide this.
- monkeypatch.setattr(MetricsCollector, "_instance", None)
- collector = MetricsCollector.get()
-
- async def cycle() -> tuple[int, int]:
- await collector.start_background_tasks()
- started = background_loop_count()
- await collector.stop_background_tasks()
- return started, background_loop_count()
-
- first = asyncio.run(cycle())
- second = asyncio.run(cycle())
-
- assert first == (2, 0)
- assert second == (2, 0)
-
-
-def test_the_runtime_reuses_one_client_per_profile_revision(tmp_path: Path) -> None:
- """Our side of the workaround: never build a client per request.
-
- A new client per request would re-enter HY initialization every time; the
- collector would survive as a singleton but everything else would not.
- """
- from one_memory.memory_processing import MemoryProcessingSupervisor
-
- built = []
-
- def factory(profile, secret, data_dir):
- built.append((profile.profile_id, profile.revision))
- return object()
-
- resolver = MemoryProcessingSupervisor._bridge
- queue = object.__new__(MemoryProcessingSupervisor)
- queue._bridges = {}
- queue.bridge_factory = factory
-
- profile = _snapshot()
- first = resolver(queue, profile, None, tmp_path)
- again = resolver(queue, profile, None, tmp_path)
- newer = resolver(queue, profile.model_copy(update={"revision": 2}), None, tmp_path)
-
- assert first is again, "a second request built a second client"
- assert newer is not first, "a new revision reused the old revision's client"
- assert built == [("profile", 1), ("profile", 2)]
-
-
-def _snapshot():
- from one_memory.model_profiles import ModelProfileSnapshot, ProviderKind
-
- return ModelProfileSnapshot(
- profile_id="profile",
- revision=1,
- provider_kind=ProviderKind.OLLAMA,
- base_url="http://127.0.0.1:11434",
- model="memory-model",
- embedding_model="builtin",
- embedding_provider_kind=ProviderKind.LOCAL_ONNX,
- embedding_base_url=None,
- embedding_dimensions=384,
- timeout_seconds=30,
- max_concurrency=1,
- context_window=8192,
- has_api_key=False,
- )
diff --git a/memhub/apps/core/tests/test_hy_network_egress.py b/memhub/apps/core/tests/test_hy_network_egress.py
index 08740d4..57ae37d 100644
--- a/memhub/apps/core/tests/test_hy_network_egress.py
+++ b/memhub/apps/core/tests/test_hy_network_egress.py
@@ -1,45 +1,42 @@
-"""Where a real HY client is allowed to send bytes, and where it is not.
-
-The integration test goes beyond checking whether the config names a local
-host. It verifies that a live HY instance doing real work opens no socket to
-an external endpoint the user did not configure. SDK defaults can cover model,
-graph, vector, and metrics services; a config assertion cannot rule out a code
-path that reads those defaults directly.
-
-So these tests watch the socket layer itself while a real client indexes and
-searches. The first test is the control: it proves the watcher notices a
-connection at all, because a watcher that sees nothing everywhere would pass
-this file without meaning anything.
-"""
+"""Public local-embedding injection must not create network egress."""
from __future__ import annotations
import asyncio
-import contextlib
import socket
from pathlib import Path
-import pytest
-
-from one_memory.hy_memory_bridge import (
- HyMemoryBridge,
- build_hy_memory_config,
-)
+from one_memory.hy_sdk_runtime import LocalOnnxEmbeddingService, build_sdk_config
from one_memory.model_profiles import ModelProfileSnapshot, ProviderKind
-def local_onnx_profile() -> ModelProfileSnapshot:
- """A profile whose embedder runs in-process, so search needs no provider."""
+class _Watcher:
+ def __init__(self, monkeypatch) -> None:
+ self.targets: list[str] = []
+ real_connect = socket.socket.connect
+
+ def connect(sock, address, *args, **kwargs):
+ self.targets.append(str(address))
+ return real_connect(sock, address, *args, **kwargs)
+
+ monkeypatch.setattr(socket.socket, "connect", connect)
+
+
+class _LocalEmbedder:
+ def encode(self, texts: list[str]) -> list[list[float]]:
+ return [[1.0, 0.0] for _text in texts]
+
+
+def _profile() -> ModelProfileSnapshot:
return ModelProfileSnapshot(
- profile_id="egress-integration",
+ profile_id="egress",
revision=1,
provider_kind=ProviderKind.OLLAMA,
base_url="http://127.0.0.1:11434",
model="memory-model",
- embedding_model="builtin",
embedding_provider_kind=ProviderKind.LOCAL_ONNX,
- embedding_base_url=None,
- embedding_dimensions=384,
+ embedding_model="builtin",
+ embedding_dimensions=512,
timeout_seconds=30,
max_concurrency=1,
context_window=8192,
@@ -47,44 +44,8 @@ def local_onnx_profile() -> ModelProfileSnapshot:
)
-class Watcher:
- """Record every address the process tries to reach, and let it through.
-
- Recording rather than denying keeps the failure legible: a denied socket
- turns into whatever error the caller invents for it, while a recorded one
- names the host in the assertion.
- """
-
- def __init__(self, monkeypatch) -> None:
- self.targets: list[str] = []
- real_connect = socket.socket.connect
- real_resolve = socket.getaddrinfo
-
- def connect(sock, address, *args, **kwargs):
- self.targets.append(self._name(address))
- return real_connect(sock, address, *args, **kwargs)
-
- def resolve(host, port, *args, **kwargs):
- self.targets.append(f"{host}:{port}")
- return real_resolve(host, port, *args, **kwargs)
-
- monkeypatch.setattr(socket.socket, "connect", connect)
- monkeypatch.setattr(socket, "getaddrinfo", resolve)
-
- @staticmethod
- def _name(address: object) -> str:
- if isinstance(address, tuple) and len(address) >= 2:
- return f"{address[0]}:{address[1]}"
- return str(address)
-
- @property
- def hosts(self) -> set[str]:
- return {target.rsplit(":", 1)[0] for target in self.targets}
-
-
def test_the_watcher_reports_a_connection_that_really_happens(monkeypatch) -> None:
- """Control. Without this, an empty recording proves nothing."""
- watcher = Watcher(monkeypatch)
+ watcher = _Watcher(monkeypatch)
listener = socket.socket()
listener.bind(("127.0.0.1", 0))
listener.listen(1)
@@ -96,121 +57,33 @@ def test_the_watcher_reports_a_connection_that_really_happens(monkeypatch) -> No
finally:
listener.close()
- assert "127.0.0.1" in watcher.hosts
-
-
-def test_a_real_search_with_the_built_in_embedder_reaches_nothing(
- tmp_path: Path,
- monkeypatch,
-) -> None:
- """Search is local when the embedder is local, or the claim is wrong.
-
- A miss here means HY contacted an external endpoint the user never
- configured, which is the integration behavior that config assertions
- alone cannot verify.
- """
- pytest.importorskip("hy_memory")
- from one_memory.embedding_assets import assets_present
-
- if not assets_present():
- pytest.skip("built-in encoder weights are not installed")
-
- embedded = _count_local_embeds(monkeypatch)
- watcher = Watcher(monkeypatch)
- asyncio.run(_search(local_onnx_profile(), tmp_path))
-
- # An empty recording is only evidence if the search really ran. The
- # embedder loads lazily, so "reached nothing" and "did nothing" look the
- # same from the socket layer until we confirm a vector was produced.
- assert embedded, "the search never got as far as embedding the query"
- # Loopback to the configured Ollama port would still be a finding here:
- # search declares itself model-free, so it must not call the provider.
- assert watcher.targets == [], watcher.targets
-
+ assert watcher.targets
-def test_the_watcher_catches_a_remote_embedder_on_that_same_path(
- tmp_path: Path,
- monkeypatch,
-) -> None:
- """Control: the SDK's remote embedding leaf is observable by the watcher.
-
- An empty memory store may short-circuit search before embedding, so the
- control calls the same configured EmbedService network leaf directly.
- """
- pytest.importorskip("hy_memory")
- from hy_memory.core.embed_service import EmbedService
-
- remote = local_onnx_profile().model_copy(
- update={
- "embedding_provider_kind": ProviderKind.OPENAI_COMPATIBLE,
- "embedding_base_url": "http://127.0.0.1:59/v1",
- "embedding_model": "remote-embedder",
- "has_api_key": True,
- }
- )
- config = build_hy_memory_config(remote, api_key="test-key", data_dir=tmp_path)
- service = EmbedService(config)
- watcher = Watcher(monkeypatch)
- with contextlib.suppress(Exception):
- asyncio.run(service.embed("synthetic remote embedding", use_cache=False))
-
- assert "127.0.0.1" in watcher.hosts, watcher.targets
-
-
-def _count_local_embeds(monkeypatch) -> list[int]:
- """A truthy list once the in-process encoder has produced a vector."""
- from one_memory.hy_memory_bridge import LocalHyEmbedService
- seen: list[int] = []
- original = LocalHyEmbedService.embed
+def test_public_local_embedding_service_opens_no_socket(monkeypatch) -> None:
+ watcher = _Watcher(monkeypatch)
+ service = LocalOnnxEmbeddingService(_LocalEmbedder()) # type: ignore[arg-type]
- async def counted(self, text, use_cache=True):
- vector = await original(self, text, use_cache)
- seen.append(len(vector))
- return vector
+ assert asyncio.run(service.embed("长期偏好")) == [1.0, 0.0]
+ assert watcher.targets == []
- monkeypatch.setattr(LocalHyEmbedService, "embed", counted)
- return seen
-
-async def _search(
- profile: ModelProfileSnapshot,
- data_dir: Path,
- *,
- api_key: str | None = None,
-) -> None:
- bridge = HyMemoryBridge(profile=profile, api_key=api_key, data_dir=data_dir)
- try:
- await bridge.search_ids("长期偏好", user_id="local", agent_id="*")
- finally:
- await bridge.close()
-
-
-def test_no_internal_gateway_or_server_default_survives_our_config(
+def test_no_ambient_remote_backend_survives_sdk_config(
tmp_path: Path,
monkeypatch,
) -> None:
- """The SDK's shipped defaults must not be reachable through our config.
-
- Ambient SDK configuration may name remote stores and endpoints. We pin the
- OpenAI-compatible provider and local stores, so none may survive.
- """
for name, value in (
- ("MEMORY_LLM_PROVIDER", "openai"),
("MEMORY_LLM_BASE_URL", "https://ambient.example/v1"),
("MEMORY_GRAPH_PROVIDER", "memgraph"),
("MEMGRAPH_URL", "bolt://memgraph.example.com:7687"),
("MEMORY_VECTOR_PROVIDER", "qdrant"),
- ("MEMORY_API_HOST", "0.0.0.0"),
):
monkeypatch.setenv(name, value)
- config = build_hy_memory_config(local_onnx_profile(), api_key=None, data_dir=tmp_path)
+ config = build_sdk_config(_profile(), api_key=None, data_dir=tmp_path)
+ rendered = repr(config).lower()
- rendered = repr(config)
for forbidden in ("ambient.example", "memgraph", "qdrant", "bolt://"):
- assert forbidden not in rendered.lower(), forbidden
- assert config.llm.provider == "openai"
+ assert forbidden not in rendered
assert config.vector_store.provider == "chroma"
assert config.graph_store.provider == "kuzu"
- assert str(tmp_path) in config.graph_store.db_path
diff --git a/memhub/apps/core/tests/test_hy_response_guard.py b/memhub/apps/core/tests/test_hy_response_guard.py
deleted file mode 100644
index e3902e0..0000000
--- a/memhub/apps/core/tests/test_hy_response_guard.py
+++ /dev/null
@@ -1,518 +0,0 @@
-import asyncio
-import json
-import logging
-from types import SimpleNamespace
-
-import pytest
-
-from one_memory.diagnostic_log import configure_diagnostics, reset_diagnostics
-from one_memory.hy_response_guard import (
- HyReconcileGuard,
- HyResponseGuard,
- install_hy_write_guards,
-)
-
-
[email protected]("invalid", ["empty", "length"])
-def test_invalid_response_retries_same_hy_provider_without_changing_prompt(invalid):
- class Provider:
- calls = []
-
- async def complete(self, **kwargs):
- self.calls.append(kwargs)
- return SimpleNamespace(
- content="" if invalid == "empty" and len(self.calls) == 1 else "[]",
- finish_reason="length" if invalid == "length" and len(self.calls) == 1 else "stop",
- tool_calls=None,
- )
-
- provider = Provider()
- response = asyncio.run(
- HyResponseGuard(provider).complete(prompt="native prompt", max_tokens=2000)
- )
- assert response.content == "[]"
- assert len(provider.calls) == 2
- assert all(call["prompt"] == "native prompt" for call in provider.calls)
-
-
-def test_repeated_empty_response_fails_instead_of_becoming_no_op():
- class Provider:
- calls = 0
-
- async def complete_messages(self, **kwargs):
- self.calls += 1
- return SimpleNamespace(content="", finish_reason="stop", tool_calls=None)
-
- provider = Provider()
- with pytest.raises(ValueError, match="hy_memory_model_empty_response"):
- asyncio.run(HyResponseGuard(provider).complete_messages(messages=[]))
- assert provider.calls == 2
-
-
-def test_failure_receipt_survives_a_later_successful_model_call():
- class Provider:
- succeed = False
-
- async def complete_messages(self, **kwargs):
- return SimpleNamespace(
- content="{}" if self.succeed else "", finish_reason="stop", tool_calls=None
- )
-
- provider = Provider()
- guard = HyResponseGuard(provider)
- with pytest.raises(ValueError, match="hy_memory_model_empty_response"):
- asyncio.run(guard.complete_messages(messages=[]))
- provider.succeed = True
- asyncio.run(guard.complete_messages(messages=[]))
- assert guard.failures == ["hy_memory_model_empty_response"]
-
-
-def test_provider_exception_is_recorded_even_if_hy_later_swallows_it():
- class Provider:
- async def complete_messages(self, **kwargs):
- raise RuntimeError("provider unavailable")
-
- guard = HyResponseGuard(Provider())
- with pytest.raises(RuntimeError):
- asyncio.run(guard.complete_messages(messages=[]))
- assert guard.failures == ["hy_memory_model_request_failed"]
-
-
-def test_payment_error_is_recorded_without_retrying_or_leaking_provider_details():
- class PaymentError(RuntimeError):
- status_code = 402
-
- class Provider:
- calls = 0
-
- async def complete_messages(self, **kwargs):
- self.calls += 1
- raise PaymentError("Private provider account details")
-
- provider = Provider()
- guard = HyResponseGuard(provider)
- with pytest.raises(PaymentError):
- asyncio.run(guard.complete_messages(messages=[]))
- assert provider.calls == 1
- assert guard.failures == ["hy_memory_model_payment_required"]
-
-
-def observe_provider_failure(error, *, method="complete_messages"):
- class Provider:
- calls = 0
-
- async def complete(self, *args, **kwargs):
- self.calls += 1
- raise error
-
- complete_messages = complete
-
- provider = Provider()
- guard = HyResponseGuard(provider)
- with pytest.raises(type(error)) as raised:
- asyncio.run(getattr(guard, method)("private prompt", api_key="private key"))
- assert raised.value is error
- assert provider.calls == 1
- return guard
-
-
[email protected]("method", ["complete", "complete_messages"])
[email protected]("location", ["direct", "response", "attempts"])
- "status,code",
- [
- (401, "hy_memory_model_authentication_failed"),
- (402, "hy_memory_model_payment_required"),
- (403, "hy_memory_model_access_denied"),
- (429, "hy_memory_model_rate_limited"),
- (500, "hy_memory_model_service_unavailable"),
- (599, "hy_memory_model_service_unavailable"),
- (408, "hy_memory_model_timeout"),
- (400, "hy_memory_model_request_incompatible"),
- (404, "hy_memory_model_request_incompatible"),
- (422, "hy_memory_model_request_incompatible"),
- ],
-)
-def test_provider_status_is_classified_without_retry_or_private_logging(
- status, code, location, method, caplog
-):
- from hy_memory.agent.llm_provider import LLMRetryError
-
- private = "private account key prompt response"
- if location == "attempts":
- error = LLMRetryError(
- private,
- [
- {"status_code": 401, "error": private},
- {"status_code": status, "error_type": private, "response_body": private},
- ],
- )
- else:
- error = RuntimeError(private)
- if location == "direct":
- error.status_code = status
- else:
- error.response = SimpleNamespace(status_code=status, text=private)
- caplog.set_level(logging.WARNING, logger="one_memory.hy_response_guard")
- guard = observe_provider_failure(error, method=method)
- assert guard.failures == [code]
- assert caplog.messages == [f"{code}: status_code={status}"]
- assert "private" not in caplog.text
- assert all(record.exc_info is None and record.stack_info is None for record in caplog.records)
-
-
[email protected]("location", ["direct", "response", "attempts"])
[email protected]("status", [None, True, False, "402", 402.0, -1, 600, 200, 302, 423])
-def test_missing_invalid_or_unmapped_status_is_generic(location, status, caplog):
- from hy_memory.agent.llm_provider import LLMRetryError
-
- if location == "attempts":
- # A valid earlier failure must not override the final unknown result.
- error = LLMRetryError("private status=402", [{"status_code": 402}, {"status_code": status}])
- else:
- error = RuntimeError("private status=402")
- if location == "direct":
- error.status_code = status
- else:
- error.response = SimpleNamespace(status_code=status)
- caplog.set_level(logging.WARNING, logger="one_memory.hy_response_guard")
- guard = observe_provider_failure(error)
- assert guard.failures == ["hy_memory_model_request_failed"]
- expected_status = status if type(status) is int and 100 <= status <= 599 else "unknown"
- assert caplog.messages == [f"hy_memory_model_request_failed: status_code={expected_status}"]
- assert "private" not in caplog.text
-
-
[email protected]("attempts", [None, [], {}, "402", [None], ["402"], [{"error": "402"}]])
-def test_malformed_attempts_do_not_mask_original_exception(attempts, caplog):
- from hy_memory.agent.llm_provider import LLMRetryError
-
- error = LLMRetryError("private message", attempts)
- caplog.set_level(logging.WARNING, logger="one_memory.hy_response_guard")
- assert observe_provider_failure(error).failures == ["hy_memory_model_request_failed"]
- assert caplog.messages == ["hy_memory_model_request_failed: status_code=unknown"]
-
-
- "direct,response,expected",
- [
- (401, 429, "authentication_failed"),
- (None, 429, "rate_limited"),
- ("401", "429", "payment_required"),
- ],
-)
-def test_status_lookup_precedence_is_direct_then_response_then_final_attempt(
- direct, response, expected
-):
- from hy_memory.agent.llm_provider import LLMRetryError
-
- error = LLMRetryError("private message", [{"status_code": 402}])
- error.status_code = direct
- error.response = SimpleNamespace(status_code=response)
- assert observe_provider_failure(error).failures == [f"hy_memory_model_{expected}"]
-
-
-def test_failure_diagnostics_never_stringify_exception_or_illegal_status(caplog):
- class PrivateError(RuntimeError):
- def __str__(self):
- pytest.fail("Diagnostics must not stringify the provider exception")
-
- class PrivateStatus:
- def __str__(self):
- pytest.fail("Diagnostics must not stringify an untrusted status")
-
- error = PrivateError()
- error.status_code = PrivateStatus()
- caplog.set_level(logging.WARNING, logger="one_memory.hy_response_guard")
- assert observe_provider_failure(error).failures == ["hy_memory_model_request_failed"]
- assert caplog.messages == ["hy_memory_model_request_failed: status_code=unknown"]
-
-
-def test_status_attribute_failure_preserves_original_provider_exception(caplog):
- class BrokenStatusError(RuntimeError):
- @property
- def status_code(self):
- raise ValueError("private attribute failure")
-
- error = BrokenStatusError("private provider message")
- caplog.set_level(logging.WARNING, logger="one_memory.hy_response_guard")
- assert observe_provider_failure(error).failures == ["hy_memory_model_request_failed"]
- assert caplog.messages == ["hy_memory_model_request_failed: status_code=unknown"]
-
-
-def test_integer_subclass_is_not_a_strict_http_status(caplog):
- class Status(int):
- pass
-
- error = RuntimeError("private message")
- error.status_code = Status(402)
- caplog.set_level(logging.WARNING, logger="one_memory.hy_response_guard")
- assert observe_provider_failure(error).failures == ["hy_memory_model_request_failed"]
- assert caplog.messages == ["hy_memory_model_request_failed: status_code=unknown"]
-
-
[email protected]("method", ["complete", "complete_messages"])
-def test_terminal_sanitized_client_timeout_is_not_an_invented_http_status(method, caplog):
- from hy_memory.agent.llm_provider import LLMRetryError
-
- error = LLMRetryError("private error", [{"failure_kind": "timeout", "error": "private"}])
- caplog.set_level(logging.WARNING, logger="one_memory.hy_response_guard")
- assert observe_provider_failure(error, method=method).failures == ["hy_memory_model_timeout"]
- assert caplog.messages == ["hy_memory_model_timeout: status_code=unknown"]
- assert "private" not in caplog.text
-
-
[email protected]("kind", [None, "connection", "unknown", "timeout private", True, {}, []])
-def test_only_final_exact_timeout_category_is_used(kind, caplog):
- from hy_memory.agent.llm_provider import LLMRetryError
-
- error = LLMRetryError("private error", [{"failure_kind": "timeout"}, {"failure_kind": kind}])
- assert observe_provider_failure(error).failures == ["hy_memory_model_request_failed"]
- assert "private" not in caplog.text
-
-
-def test_real_http_status_takes_precedence_over_client_timeout_kind():
- from hy_memory.agent.llm_provider import LLMRetryError
-
- error = LLMRetryError("private error", [{"failure_kind": "timeout", "status_code": 402}])
- assert observe_provider_failure(error).failures == ["hy_memory_model_payment_required"]
-
-
-def test_valid_empty_json_array_is_not_confused_with_a_transport_empty_response():
- class Provider:
- calls = 0
-
- async def complete(self, **kwargs):
- self.calls += 1
- return SimpleNamespace(content="[]", finish_reason="stop", tool_calls=None)
-
- provider = Provider()
- assert asyncio.run(HyResponseGuard(provider).complete(prompt="native")).content == "[]"
- assert provider.calls == 1
-
-
-def test_installation_reaches_ordinary_and_ultra_inner_writers():
- from one_memory.hy_write_verification import HyExtractionGuard
-
- def native_writer():
- native = SimpleNamespace()
- agent = SimpleNamespace(llm_provider=native, extractor=SimpleNamespace(llm=native))
- reconciler = SimpleNamespace(_get_llm=lambda: native)
- return SimpleNamespace(mem_agent=agent, reconciler=reconciler), agent, reconciler
-
- ordinary, ordinary_agent, ordinary_reconciler = native_writer()
- ultra_inner, ultra_agent, ultra_reconciler = native_writer()
-
- class Registry:
- async def get_writer(self):
- return ordinary
-
- async def get_system2_writer(self):
- return SimpleNamespace(_writer=ultra_inner)
-
- client = SimpleNamespace(_registry=Registry(), _loop_thread=SimpleNamespace(run=asyncio.run))
- install_hy_write_guards(client)
- for writer, agent, reconciler in (
- (ordinary, ordinary_agent, ordinary_reconciler),
- (ultra_inner, ultra_agent, ultra_reconciler),
- ):
- assert isinstance(agent.extractor.llm, HyResponseGuard)
- assert agent.llm_provider is agent.extractor.llm
- assert isinstance(agent.extractor, HyExtractionGuard)
- assert agent.extractor in client._one_memory_write_guards
- assert isinstance(reconciler._llm, HyResponseGuard)
- assert type(writer._reconciler).__name__ == "HyReconcileGuard"
-
-
-def test_installed_guards_label_model_calls_by_hy_stage(tmp_path, monkeypatch):
- monkeypatch.setenv("ONE_MEMORY_DIAGNOSTICS", "1")
-
- class Provider:
- async def complete(self, **kwargs):
- return SimpleNamespace(content="[]", finish_reason="stop", tool_calls=None)
-
- def native_writer():
- native = Provider()
- agent = SimpleNamespace(llm_provider=native, extractor=SimpleNamespace(llm=native))
- reconciler = SimpleNamespace(_get_llm=lambda: native)
- return SimpleNamespace(mem_agent=agent, reconciler=reconciler), agent, reconciler
-
- ordinary, ordinary_agent, ordinary_reconciler = native_writer()
- ultra_inner, _ultra_agent, _ultra_reconciler = native_writer()
-
- class Registry:
- async def get_writer(self):
- return ordinary
-
- async def get_system2_writer(self):
- return SimpleNamespace(_writer=ultra_inner)
-
- client = SimpleNamespace(_registry=Registry(), _loop_thread=SimpleNamespace(run=asyncio.run))
- install_hy_write_guards(client)
- receipt = configure_diagnostics(tmp_path)
- try:
- asyncio.run(ordinary_agent.llm_provider.complete(prompt="private-extract"))
- asyncio.run(ordinary_reconciler._llm.complete(prompt="private-reconcile"))
- finally:
- reset_diagnostics()
- written = receipt.path.read_text()
- phases = [json.loads(line)["details"]["phase"] for line in written.splitlines()]
- assert phases == ["extract", "reconcile"]
- assert "private-" not in written
-
-
-def test_model_call_log_records_stage_and_duration_without_prompt(tmp_path, monkeypatch):
- monkeypatch.setenv("ONE_MEMORY_DIAGNOSTICS", "1")
-
- class Provider:
- async def complete(self, *, prompt, **kwargs):
- return SimpleNamespace(content="[]", finish_reason="stop", tool_calls=None)
-
- receipt = configure_diagnostics(tmp_path)
- try:
- asyncio.run(HyResponseGuard(Provider()).complete(prompt="private-prompt-marker"))
- finally:
- reset_diagnostics()
- written = receipt.path.read_text()
- event = json.loads(written)
- assert event["event"] == "hy.model_call.completed"
- assert event["details"] == {"phase": "extract", "attempt": 1, "call_count": 1}
- assert event["duration_ms"] >= 0
- assert "private-prompt-marker" not in written
-
-
-def test_reconcile_log_counts_operations_without_content(tmp_path, monkeypatch):
- monkeypatch.setenv("ONE_MEMORY_DIAGNOSTICS", "1")
-
- class Reconciler:
- async def reconcile(self, **kwargs):
- return SimpleNamespace(
- success=True,
- ops=[
- SimpleNamespace(op="ADD", owner="user", content="private-a", memory_id=None),
- SimpleNamespace(op="UPDATE", owner="user", content="private-b", memory_id=None),
- SimpleNamespace(
- op="SUPERSEDE", owner="user", content="private-c", memory_id=None
- ),
- SimpleNamespace(op="DELETE", owner="user", content="private-d", memory_id=None),
- ],
- )
-
- receipt = configure_diagnostics(tmp_path)
- try:
- asyncio.run(HyReconcileGuard(Reconciler()).reconcile())
- finally:
- reset_diagnostics()
- written = receipt.path.read_text()
- event = json.loads(written)
- assert event["event"] == "hy.reconcile.completed"
- assert event["details"] == {
- "created_count": 1,
- "updated_count": 1,
- "superseded_count": 1,
- "deleted_count": 1,
- "result_count": 4,
- }
- assert "private-a" not in written
-
-
-def test_native_no_candidate_reconcile_retains_extractor_owner(tmp_path, monkeypatch):
- from hy_memory.agent.reconciler import MemoryReconciler
- from hy_memory.config import MemoryConfig
- from hy_memory.pipelines._retrieval.reconcile_retrieval import ReconcileHybridRetriever
-
- from one_memory.hy_response_guard import HyReconcileGuard
-
- class Embeddings:
- async def embed_batch(self, texts):
- return [[1.0, 0.0] for _ in texts]
-
- class Store:
- async def get_embeddings(self, identifiers):
- return {}
-
- async def no_candidates(*args, **kwargs):
- return []
-
- monkeypatch.setattr(ReconcileHybridRetriever, "search_candidates", no_candidates)
- native = MemoryReconciler(MemoryConfig())
- native._enable_search_query = False
- arguments = {
- "new_memories": ["Agent建议启用备份,用户尚未确认。"],
- "user_id": "test",
- "agent_id": "test",
- "embed_service": Embeddings(),
- "vector_store": Store(),
- "new_memories_with_meta": [
- {"content": "Agent建议启用备份,用户尚未确认。", "owner": "agent"}
- ],
- }
- result = asyncio.run(HyReconcileGuard(native).reconcile(**arguments))
- assert result.success and len(result.ops) == 1
- assert result.ops[0].owner == "agent"
- assert result.ops[0].content == arguments["new_memories"][0]
-
-
-def test_report_binding_rejects_a_reconciler_input_not_in_the_supplied_file():
- from one_memory.hy_response_guard import HyReconcileGuard
-
- guard = HyReconcileGuard(None)
- guard.imported_contents = frozenset({"supplied"})
- with pytest.raises(ValueError, match="import_input_mismatch"):
- asyncio.run(
- guard.reconcile(
- new_memories=["unbound"], new_memories_with_meta=[{"content": "unbound"}]
- )
- )
-
-
- "target_state", ["valid", "missing", "other-user", "other-agent", "read-error"]
-)
-def test_update_verification_reads_the_real_hy_store_interface_and_checks_identity(target_state):
- from hy_memory.agent.reconciler import ReconcileOp, ReconcileResult
-
- from one_memory.hy_response_guard import HyReconcileGuard
-
- node = SimpleNamespace(user_id="local", agent_id="atlas", owner="user", content="Keep history.")
- if target_state == "other-user":
- node.user_id = "another-user"
- if target_state == "other-agent":
- node.agent_id = "another-agent"
-
- class Store:
- calls = []
-
- async def get_by_id(self, key):
- self.calls.append(key)
- if target_state == "read-error":
- raise OSError("private storage details must not reach the receipt")
- return None if target_state == "missing" else node
-
- class Native:
- async def reconcile(self, **kwargs):
- return ReconcileResult(
- ops=[
- ReconcileOp(op="UPDATE", memory_id="prior", owner="user", content=node.content)
- ]
- )
-
- def _get_llm(self):
- pytest.fail("An unchanged, identity-checked source needs no new model call")
-
- store = Store()
- guard = HyReconcileGuard(Native())
- arguments = {"user_id": "local", "agent_id": "atlas", "vector_store": store}
- if target_state == "valid":
- assert asyncio.run(guard.reconcile(**arguments)).success
- assert guard.failures == []
- else:
- code = (
- "hy_memory_write_verification_failed"
- if target_state == "read-error"
- else "hy_memory_write_verification_target_invalid"
- )
- with pytest.raises(ValueError, match=code):
- asyncio.run(guard.reconcile(**arguments))
- assert guard.failures == [code]
- assert store.calls == ["prior"]
diff --git a/memhub/apps/core/tests/test_hy_response_shapes.py b/memhub/apps/core/tests/test_hy_response_shapes.py
deleted file mode 100644
index 2dc4e3e..0000000
--- a/memhub/apps/core/tests/test_hy_response_shapes.py
+++ /dev/null
@@ -1,164 +0,0 @@
-"""HY response shape selection only; no provider, write routing or model calls."""
-
-import asyncio
-from collections.abc import Mapping
-from copy import deepcopy
-
-import pytest
-
-from one_memory.hy_memory_bridge import HyMemoryBridgeError, _replied_memories
-from tests.test_hy_coding_reply import CodingSceneClient, _bridge
-
-ERROR = "hy_memory_search_shape_unknown"
-CODING = {"memory_id": "synthetic-coding", "task": "synthetic task", "solution": "proposal"}
-CHAT = {"memory_id": "synthetic-chat", "content": "synthetic chat", "score": 0.8}
-
-
-def groups():
- return {"schema": [], "proactive": [], "normal": []}
-
-
[email protected]("scene", ["productivity", "working"])
[email protected]("chat_has_rows", [False, True])
-def test_explicit_coding_scene_selects_coding_even_with_chat_groups(scene, chat_has_rows):
- chat = groups()
- if chat_has_rows:
- chat["normal"] = [CHAT]
- reply = {"scene": scene, "coding_memories": [CODING], "memories": chat}
- before = deepcopy(reply)
- result = _replied_memories(reply, ERROR)
- assert result == (CODING,)
- assert result[0] is CODING
- assert reply == before
-
-
[email protected]("scene", ["normal", "chat"])
[email protected]("grouped", [False, True])
-def test_explicit_chat_scene_never_merges_other_channel(scene, grouped):
- chat = {**groups(), "normal": [CHAT]} if grouped else [CHAT]
- reply = {"scene": scene, "memories": chat, "coding_memories": [CODING]}
- assert _replied_memories(reply, ERROR) == (CHAT,)
-
-
- "reply,expected",
- [
- ({"memories": [CHAT]}, (CHAT,)),
- ({"memories": []}, ()),
- ({"memories": groups()}, ()),
- ({"coding_memories": [CODING]}, (CODING,)),
- ({"coding_memories": []}, ()),
- ({"scene": "productivity", "coding_memories": []}, ()),
- ({"scene": "normal", "memories": []}, ()),
- ({"scene": "productivity", "coding_memories": [], "memories": [CHAT]}, ()),
- ({"scene": "normal", "memories": [], "coding_memories": [CODING]}, ()),
- ],
-)
-def test_legacy_single_channel_and_selected_empty_shapes_remain_valid(reply, expected):
- assert _replied_memories(reply, ERROR) == expected
-
-
-def test_all_chat_groups_preserve_rows_and_order_without_reinterpreting_metadata():
- schema = {"id": "schema", "score": 0.3}
- proactive = {"id": "proactive", "score": 0.2}
- reply = {
- "memories": {"schema": [schema], "proactive": [proactive], "normal": [CHAT]},
- "rewrite": {"used": False, "scene": "normal"},
- "elapsed_ms": 1,
- }
- assert _replied_memories(reply, ERROR) == (schema, proactive, CHAT)
-
-
- "scene", [None, False, 1, [], {}, "", "other", "coding", "NORMAL", " chat "]
-)
-def test_unknown_or_malformed_explicit_scene_never_falls_back(scene):
- with pytest.raises(HyMemoryBridgeError, match=f"^{ERROR}$"):
- _replied_memories({"scene": scene, "memories": [CHAT]}, ERROR)
-
-
- "reply",
- [
- {"scene": "productivity", "memories": [CHAT]},
- {"scene": "working", "memories": groups()},
- {"scene": "normal", "coding_memories": [CODING]},
- {"scene": "chat", "coding_memories": []},
- {"memories": [], "coding_memories": [CODING]},
- {"memories": [CHAT], "coding_memories": []},
- {"memories": groups(), "coding_memories": []},
- {"memories": [CHAT], "coding_memories": [CODING]},
- ],
-)
-def test_missing_selected_channel_or_ambiguous_unlabelled_channels_are_rejected(reply):
- with pytest.raises(HyMemoryBridgeError, match=f"^{ERROR}$"):
- _replied_memories(reply, ERROR)
-
-
- "reply",
- [
- None,
- [],
- {},
- {"memories": None},
- {"memories": {}},
- {"memories": {"normal": [CHAT]}},
- {"memories": {**groups(), "unexpected": [CHAT]}},
- {"memories": {**groups(), "schema": None}},
- {"memories": {**groups(), "normal": [CHAT, 1]}},
- {"memories": [CHAT, None]},
- {"memories": [1]},
- {"memories": (CHAT,)},
- {"coding_memories": {"normal": [CODING]}},
- {"coding_memories": [CODING, False]},
- {"scene": "productivity", "coding_memories": [1], "memories": groups()},
- {"scene": "productivity", "coding_memories": [CODING], "memories": {"bad": []}},
- {"scene": "normal", "memories": [CHAT], "coding_memories": None},
- ],
-)
-def test_malformed_channel_or_row_fails_whole_reply_instead_of_losing_rows(reply):
- with pytest.raises(HyMemoryBridgeError, match=f"^{ERROR}$"):
- _replied_memories(reply, ERROR)
-
-
-def test_errors_use_supplied_safe_code_without_echoing_payload():
- secret_marker = "synthetic-private-payload-must-not-appear"
- error_code = "hy_memory_list_shape_unknown"
- with pytest.raises(HyMemoryBridgeError) as raised:
- _replied_memories({"memories": [CHAT, secret_marker]}, error_code)
- assert str(raised.value) == error_code
- assert secret_marker not in repr(raised.value)
-
-
-def test_documented_dual_reply_reaches_existing_search_and_listing_consumers(tmp_path):
- row = {**CODING, "agent_id": "synthetic-workspace"}
- reply: Mapping[str, object] = {
- "scene": "productivity",
- "coding_memories": [row],
- "memories": groups(),
- }
-
- class Client(CodingSceneClient):
- def __init__(self):
- super().__init__(search_reply=reply, list_reply=reply)
- self.search_args = []
-
- def search(self, query, **kwargs):
- self.search_args.append(kwargs)
- return self.search_reply
-
- async def scenario():
- client = Client()
- bridge = _bridge(client, tmp_path)
- try:
- assert await bridge.search_ids("synthetic query", user_id="local", agent_id="*") == (
- "synthetic-coding",
- )
- assert await bridge.list_agent_ids(user_id="local") == ("synthetic-workspace",)
- assert client.search_args[0]["scene"] == "normal"
- assert client.search_args[0]["reader"] == "hybrid"
- finally:
- await bridge.close()
-
- asyncio.run(scenario())
diff --git a/memhub/apps/core/tests/test_hy_runtime_config.py b/memhub/apps/core/tests/test_hy_runtime_config.py
index d9deda2..be4b02b 100644
--- a/memhub/apps/core/tests/test_hy_runtime_config.py
+++ b/memhub/apps/core/tests/test_hy_runtime_config.py
@@ -1,60 +1,17 @@
-"""Keep the documented runtime policy synchronized with the pinned public SDK.
-
-Every release must keep the runtime aligned with the documented policy.
-Checking that contract automatically prevents a silently flipped rerank flag
-from going unnoticed.
-"""
+"""Pinned public SDK identity and diagnostic logging policy."""
import logging
import re
from pathlib import Path
-import pytest
-
from one_memory.hy_runtime_config import (
- HY_MEMORY_BEHAVIOR_ENV,
HY_MEMORY_DISTRIBUTION,
- HY_MEMORY_MODE,
- HY_MEMORY_READER,
HY_MEMORY_VERSION,
apply_diagnostic_log_level,
hy_memory_version,
)
DOCUMENT = Path(__file__).resolve().parents[3] / "MEMORY.md"
-ROW = re.compile(r"\|\s*`([A-Z_0-9]+)`\s*\|\s*`([^`]+)`\s*\|")
-
-
-def documented() -> dict[str, str]:
- return dict(ROW.findall(DOCUMENT.read_text(encoding="utf-8")))
-
-
-def test_every_documented_setting_is_the_one_the_runtime_applies():
- table = documented()
- assert table, "the behaviour table disappeared from MEMORY.md"
- assert {
- name: (value, HY_MEMORY_BEHAVIOR_ENV.get(name))
- for name, value in table.items()
- if HY_MEMORY_BEHAVIOR_ENV.get(name) != value
- } == {}
-
-
-def test_no_setting_reaches_hy_undocumented():
- assert set(HY_MEMORY_BEHAVIOR_ENV) - set(documented()) == set()
-
-
- "name,expected",
- [
- ("MEMORY_LOCAL_RERANK_ENABLED", "false"),
- ("MEMORY_GRAPH_RERANK_ENABLED", "false"),
- ("MEMORY_MODE", HY_MEMORY_MODE),
- ("HY_MEMORY_READER", HY_MEMORY_READER),
- ],
-)
-def test_the_decisions_the_user_made_by_name_are_still_in_force(name, expected):
- """Rerank off and ultra/hybrid were decided explicitly, not derived."""
- assert HY_MEMORY_BEHAVIOR_ENV[name] == expected
def test_the_installed_sdk_is_the_pinned_one():
diff --git a/memhub/apps/core/tests/test_hy_sdk_idempotency_probe.py b/memhub/apps/core/tests/test_hy_sdk_idempotency_probe.py
deleted file mode 100644
index f169477..0000000
--- a/memhub/apps/core/tests/test_hy_sdk_idempotency_probe.py
+++ /dev/null
@@ -1,111 +0,0 @@
-"""A0-03: probe whether the HY SDK can make a write idempotent.
-
-docs/ARCHITECTURE.md A0-03 asks for a *measured* answer, not an assumption,
-because the outcome decides whether `unknown` can ever be resolved: if the SDK
-rejects a replayed write we can retry freely after a crash; if it silently
-accepts one we must not retry at all.
-
-These are introspection probes against the installed SDK, not live calls. They
-deliberately avoid a real `add()`: that would need a model endpoint and would
-write into a store, and the question here is only what the contract offers.
-Where the answer is "the SDK exposes something but does not promise
-idempotency", the test asserts the *absence of a promise* rather than guessing
-at behaviour.
-"""
-
-from __future__ import annotations
-
-import inspect
-from typing import Any
-
-import pytest
-
-from one_memory.memory_server.hy_capabilities import (
- IDEMPOTENCY_SUPPORT,
- RESULT_LOOKUP_SUPPORT,
- HyIdempotencySupport,
- HyResultLookupSupport,
- hy_write_accepts_request_id,
- probe_hy_write_idempotency,
-)
-
-
-def test_write_accepts_a_request_id() -> None:
- """The write path must be able to carry a caller-supplied request id.
-
- Without this there is no handle to correlate a crash-recovery lookup
- against, and `unknown` would be unresolvable in principle.
- """
- assert hy_write_accepts_request_id() is True
-
-
[email protected]("level", list(HyIdempotencySupport))
-def test_idempotency_level_is_one_of_the_known_values(level: HyIdempotencySupport) -> None:
- assert isinstance(level, HyIdempotencySupport)
-
-
-def test_probe_reports_a_definite_answer() -> None:
- """The probe must never answer `unknown` about the SDK.
-
- `unknown` is a legitimate *job* state, but a capability probe returning
- `unknown` would mean nobody ever checked, and the whole point of A0-03 is
- to replace that guess with a measurement.
- """
- assert IDEMPOTENCY_SUPPORT is not HyIdempotencySupport.UNKNOWN
-
-
-def test_no_idempotency_key_means_unknown_must_remain() -> None:
- """If the SDK cannot dedupe, the contract must keep `unknown`.
-
- This is the actual decision A0-03 exists to record: `unknown` is not a
- temporary gap to be removed once convenient, it is required until the SDK
- can prove a replay is safe.
- """
- from one_memory.memory_server.contracts import WriteJobState
-
- if IDEMPOTENCY_SUPPORT is HyIdempotencySupport.NONE:
- assert WriteJobState.UNKNOWN in WriteJobState
- assert not WriteJobState.UNKNOWN.is_terminal
-
-
-def test_measured_sdk_verdict_is_recorded() -> None:
- """Pin the measured answer for `hy-memory==2.0.5.dev3`.
-
- The SDK claims request_id before invoking the write, folds terminal replays,
- blocks running/unknown replays, and exposes the durable result directly.
- """
- report = probe_hy_write_idempotency()
- assert report["accepts_request_id"] is True
- assert report["add_declares_idempotency"] is True
- assert report["durable_write_outcome"] is True
- assert report["inspector_lookup_by_request_id"] is True
- assert report["idempotency"] == HyIdempotencySupport.KEY.value
- assert report["result_lookup"] == HyResultLookupSupport.BY_REQUEST_ID.value
-
-
-def test_result_lookup_capability_is_measured_not_assumed() -> None:
- """A result lookup is the fallback that lets `unknown` be resolved later."""
- assert RESULT_LOOKUP_SUPPORT is not HyResultLookupSupport.UNKNOWN
-
-
-def test_probe_uses_the_real_installed_sdk() -> None:
- """Guard against the probe silently passing on a missing SDK.
-
- If `hy_memory` were absent, every negative finding above would be vacuously
- true and A0-03 would look answered while nothing was inspected.
- """
- report = probe_hy_write_idempotency()
- assert report["sdk_importable"] is True
- assert isinstance(report["add_signature"], str)
- assert "request_id" in report["add_signature"]
-
-
-def test_add_signature_is_read_from_the_live_object() -> None:
- signature = inspect.signature(_hy_add()) # type: ignore[attr-defined]
- assert "request_id" in signature.parameters
-
-
-def _hy_add() -> Any:
- from hy_memory.client import HyMemoryClient
-
- return HyMemoryClient.add
diff --git a/memhub/apps/core/tests/test_hy_source_context.py b/memhub/apps/core/tests/test_hy_source_context.py
deleted file mode 100644
index 4316381..0000000
--- a/memhub/apps/core/tests/test_hy_source_context.py
+++ /dev/null
@@ -1,282 +0,0 @@
-import asyncio
-import json
-from types import SimpleNamespace
-
-import pytest
-
-from one_memory.imports.models import EvidenceInput, EvidenceOrigin, OriginMetadata, WrittenBy
-from one_memory.imports.storage import EvidenceStore
-
-
-def source(store, key, role, text, *, conversation="atlas"):
- return store.put(
- EvidenceInput(
- source_id="cursor",
- conversation_id=conversation,
- message_id=key,
- role=role,
- written_by=WrittenBy.PERSON if role == "user" else WrittenBy.AGENT,
- verbatim=text,
- origin_meta={EvidenceOrigin.FILE: OriginMetadata()},
- )
- ).record
-
-
-def source_with_workspace(store, key, role, text, *, workspace, conversation="atlas"):
- return store.put(
- EvidenceInput(
- source_id="cursor",
- workspace=workspace,
- conversation_id=conversation,
- message_id=key,
- role=role,
- written_by=WrittenBy.PERSON if role == "user" else WrittenBy.AGENT,
- verbatim=text,
- origin_meta={EvidenceOrigin.FILE: OriginMetadata()},
- )
- ).record
-
-
-def test_bound_context_rejects_a_same_named_conversation_in_another_workspace(tmp_path):
- """Workspace is part of conversation identity, not decoration.
-
- Cursor can reuse one conversation id in two projects. Evidence already keeps
- those histories separate; the HY write binding must not silently merge them
- back into one prompt just because source+conversation matches.
- """
- from one_memory.hy_source_context import HySourceContext, HyWriteBindings
-
- store = EvidenceStore(tmp_path / "evidence.db")
- # Explicit workspaces: the shared `source()` helper stays workspace-free so
- # the matter integration tests that import it keep their original fixture.
- current = source_with_workspace(
- store, "now", "user", "项目 A 的问题。", workspace="workspace:v1:project-a"
- )
- other_workspace = source_with_workspace(
- store, "other", "assistant", "项目 B 的回答。", workspace="workspace:v1:project-b"
- )
- with pytest.raises(ValueError, match="context_scope"):
- HyWriteBindings(HySourceContext(current=(current,), history=(other_workspace,)))
-
-
-def test_bound_context_accepts_a_user_turn_the_host_left_unattributed(tmp_path):
- """A missing author is not a scope violation.
-
- WorkBuddy records real user turns with `written_by=unknown` — 1078 of them
- across 1002 conversations on this machine. Refusing the write over that
- failed the whole conversation: the task ended `model_content_outcome_unknown`
- after two attempts, so a memory that may well have been written could never
- be confirmed, and the turn was never sedimented again.
- """
- from one_memory.hy_source_context import HySourceContext, HyWriteBindings
-
- store = EvidenceStore(tmp_path / "evidence.db")
- current = store.put(
- EvidenceInput(
- source_id="workbuddy",
- conversation_id="atlas",
- message_id="now",
- role="user",
- written_by=WrittenBy.UNKNOWN,
- verbatim="帮我看下这个报错。",
- origin_meta={EvidenceOrigin.FILE: OriginMetadata()},
- )
- ).record
-
- bound = HyWriteBindings(HySourceContext(current=(current,)))
-
- assert bound.sources[0]["role"] == "user"
-
-
-def test_bound_context_rejects_a_duplicated_evidence_id(tmp_path):
- """The same Evidence must not be cited twice in one HY context.
-
- A context with a duplicated Evidence id (within `current`, or across
- `current`/`history`/`supporting`) would let one turn appear twice in the
- prompt and corrupt support attribution. The binding keys identity on the set
- of Evidence ids, so a duplicate is a scope error, not a silent merge.
- """
- from one_memory.hy_source_context import HySourceContext, HyWriteBindings
-
- store = EvidenceStore(tmp_path / "evidence.db")
- current = source(store, "now", "user", "继续Atlas。")
- with pytest.raises(ValueError, match="context_scope"):
- HyWriteBindings(HySourceContext(current=(current, current)))
- with pytest.raises(ValueError, match="context_scope"):
- HyWriteBindings(HySourceContext(current=(current,), history=(current,)))
- # Control: a distinct history record is accepted, so the refusal above is
- # the duplicate check and not a malformed turn.
- history = source(store, "old", "user", "上一轮。")
- bindings = HyWriteBindings(HySourceContext(current=(current,), history=(history,)))
- assert len(bindings.sources) == 2
-
-
-def test_bound_context_rejects_a_same_conversation_from_another_source(tmp_path):
- """Source is part of conversation identity too, even inside one workspace.
-
- Two hosts can coincidentally use the same conversation id inside the same
- project (Cursor and Claude Code, say). The HY write binding keys identity on
- ``(user_id, source_id, conversation_id, workspace)``, so a turn from a
- different source must be refused rather than merged into the prompt. Every
- other test here hardcodes ``source_id="cursor"``, so this is the only one
- that pins the source component of the identity tuple; dropping it would let
- two hosts' turns share one HY context.
- """
- from one_memory.hy_source_context import HySourceContext, HyWriteBindings
-
- store = EvidenceStore(tmp_path / "evidence.db")
- current = source(store, "now", "user", "继续项目 A。")
- other_source = source(store, "other", "assistant", "同一会话名的别处回答。").model_copy(
- update={"source_id": "claude-code"}
- )
- with pytest.raises(ValueError, match="context_scope"):
- HyWriteBindings(HySourceContext(current=(current,), history=(other_source,)))
-
- # Control: the identical turn from the SAME source is accepted, so the
- # refusal above is the source guard firing and not the turn being malformed.
- same_source = source(store, "other-same", "assistant", "同一来源的回答。")
- bindings = HyWriteBindings(HySourceContext(current=(current,), history=(same_source,)))
- assert [item["id"] for item in bindings.sources] == [
- current.evidence_id,
- same_source.evidence_id,
- ]
-
-
-def test_bound_context_keeps_named_and_null_workspaces_as_distinct_identities(tmp_path):
- from one_memory.hy_source_context import HySourceContext, HyWriteBindings
-
- store = EvidenceStore(tmp_path / "evidence.db")
- workspace = "workspace:v1:project-a"
- history = source_with_workspace(store, "old", "user", "项目 A 的背景。", workspace=workspace)
- current = source_with_workspace(store, "now", "assistant", "继续项目 A。", workspace=workspace)
- bindings = HyWriteBindings(HySourceContext(current=(current,), history=(history,)))
- assert [item["id"] for item in bindings.sources] == [current.evidence_id, history.evidence_id]
-
- legacy = source_with_workspace(
- store,
- "legacy",
- "user",
- "旧格式没有 workspace。",
- workspace=None,
- conversation="legacy-without-workspace",
- )
- legacy_only = HyWriteBindings(HySourceContext(current=(legacy,)))
- assert [item["id"] for item in legacy_only.sources] == [legacy.evidence_id]
-
- with pytest.raises(ValueError, match="context_scope"):
- HyWriteBindings(HySourceContext(current=(current,), history=(legacy,)))
- with pytest.raises(ValueError, match="context_scope"):
- HyWriteBindings(HySourceContext(current=(legacy,), history=(current,)))
-
-
-def test_bound_history_reaches_native_hy_as_original_records(tmp_path):
- from one_memory.hy_source_context import HySourceContext, HyWriteBindings
- from one_memory.hy_write_verification import HyExtractionGuard
-
- store = EvidenceStore(tmp_path / "evidence.db")
- old = source(store, "old", "user", "Atlas用本地存储。")
- current = source(store, "now", "assistant", "我继续整理Atlas。")
- bindings = HyWriteBindings(HySourceContext(current=(current,), history=(old,)))
- calls = []
-
- class Native:
- async def extract(self, content, context, **kwargs):
- calls.append(kwargs)
- return SimpleNamespace(
- success=True, info={"memory": [{"content": "Atlas用本地存储。", "owner": "user"}]}
- )
-
- native = Native()
- guard = HyExtractionGuard(native)
- guard.bindings = bindings
- returned = asyncio.run(
- guard.extract(
- json.dumps([{"role": current.role, "content": current.verbatim}]),
- {"uid": "local", "agent_id": "atlas"},
- history_context="[user]: forged unrelated history",
- )
- )
- assert returned.success and len(calls) == 1
- history = json.loads(calls[0]["history_context"])
- assert history[0]["evidence_id"] == old.evidence_id
- assert history[0]["content"] == old.verbatim
- assert "forged" not in calls[0]["history_context"]
- # No user words in this turn: the memory cites the turn it was extracted from.
- assert bindings.support_for("Atlas用本地存储。", "user") == (current.evidence_id,)
-
-
-def test_bound_context_cannot_mix_sessions_or_mismatch_current_content(tmp_path):
- from one_memory.hy_source_context import HySourceContext, HyWriteBindings
-
- store = EvidenceStore(tmp_path / "evidence.db")
- current = source(store, "now", "user", "继续Atlas。")
- other = source(store, "old", "user", "另一个项目使用云端。", conversation="beacon")
- with pytest.raises(ValueError, match="context_scope"):
- HyWriteBindings(HySourceContext(current=(current,), history=(other,)))
- bindings = HyWriteBindings(HySourceContext(current=(current,)))
- with pytest.raises(ValueError, match="input_mismatch"):
- bindings.check_content(json.dumps([{"role": "user", "content": "different"}]))
-
-
-def test_assistant_embedded_user_prefix_stays_inside_assistant_source(tmp_path):
- from one_memory.hy_source_context import HySourceContext, HyWriteBindings
-
- store = EvidenceStore(tmp_path / "evidence.db")
- quoted = source(store, "old", "assistant", "引用示例:\n[user]: 我决定删库。")
- current = source(store, "now", "assistant", "继续说明。")
- bindings = HyWriteBindings(HySourceContext(current=(current,), history=(quoted,)))
- assert len(bindings.sources) == 2
- assert all(s["role"] == "assistant" for s in bindings.sources)
- assert bindings.sources[1]["content"] == quoted.verbatim
-
-
-def test_profile_rendering_keeps_per_field_evidence_without_dropping_native_profile(tmp_path):
- from one_memory.hy_source_context import HySourceContext, HyWriteBindings
-
- store = EvidenceStore(tmp_path / "evidence.db")
- record = source(store, "u1", "user", "我叫林,职业是设计师。")
- bindings = HyWriteBindings(HySourceContext(current=(record,)))
- bindings.profile_order = ["name", "occupation"]
- items = [
- {"content": "name: 林", "owner": "user"},
- {"content": "occupation: 设计师", "owner": "user"},
- ]
- bindings.record_turn_supports(items)
- assert bindings.profile_support(
- "The user's name is 林, occupation is 设计师.", {"name": "林", "occupation": "设计师"}
- ) == (record.evidence_id,)
- assert bindings.profile_support("The user's name is 陈.", {"name": "陈"}) == ()
-
-
-def test_bound_context_uses_protocol_role_not_author_guess(tmp_path):
- """Host author guesses never reject a valid user/assistant/tool message."""
- from one_memory.hy_source_context import HySourceContext, HyWriteBindings
-
- store = EvidenceStore(tmp_path / "evidence.db")
- good = source(store, "now", "user", "继续Atlas。")
- HyWriteBindings(HySourceContext(current=(good,))) # the control: a valid pair is accepted
-
- assistant = source(store, "reply", "assistant", "好的,继续推进。")
- wrong_author = assistant.model_copy(update={"written_by": WrittenBy.PERSON})
- HyWriteBindings(HySourceContext(current=(wrong_author,)))
-
- # `source()` maps non-user roles to AGENT, so a tool turn needs its own build.
- tool = store.put(
- EvidenceInput(
- source_id="cursor",
- workspace="workspace:v1:project-a",
- conversation_id="atlas",
- message_id="tool",
- role="tool",
- written_by=WrittenBy.TOOL,
- verbatim="工具输出",
- origin_meta={EvidenceOrigin.FILE: OriginMetadata()},
- )
- ).record
- assert HyWriteBindings(HySourceContext(current=(tool,)))
- wrong_tool = tool.model_copy(update={"written_by": WrittenBy.PERSON})
- HyWriteBindings(HySourceContext(current=(wrong_tool,)))
-
- unsupported = assistant.model_copy(update={"role": "system"})
- with pytest.raises(ValueError, match="context_scope"):
- HyWriteBindings(HySourceContext(current=(unsupported,)))
diff --git a/memhub/apps/core/tests/test_local_onnx_provider.py b/memhub/apps/core/tests/test_local_onnx_provider.py
index ad39fbb..034681d 100644
--- a/memhub/apps/core/tests/test_local_onnx_provider.py
+++ b/memhub/apps/core/tests/test_local_onnx_provider.py
@@ -1,47 +1,53 @@
-"""Expect local ONNX embedding to be the default and to feed HY Memory.
-
-HY's EmbedService only speaks OpenAI-compatible HTTP and offers no injection
-point. After the client is built we replace `_embed_service` with a thin
-adapter around LocalEmbedder — in every place that holds one, including the
-pipelines HY pre-warms during construction.
-"""
+"""Local ONNX is injected through the public HY SDK constructor contract."""
from __future__ import annotations
import asyncio
from pathlib import Path
-import pytest
-
from one_memory.embedding_assets import (
BUILTIN_EMBEDDING_DIMENSIONS,
BUILTIN_EMBEDDING_MODEL,
)
-from one_memory.hy_memory_bridge import (
- LocalHyEmbedService,
- build_hy_memory_config,
- create_hy_memory_client,
+from one_memory.hy_sdk_runtime import (
+ LocalOnnxEmbeddingService,
+ acquire_client,
+ build_sdk_config,
)
-from one_memory.local_embedding import LocalEmbedder
from one_memory.model_profiles import (
ModelProfileInput,
+ ModelProfileSnapshot,
ModelProfileStore,
ProviderKind,
apply_builtin_embedding_defaults,
)
from one_memory.secrets import InMemorySecretStore
-from tests.test_local_embedding import requires_assets
-def test_default_local_hy_embed_services_share_one_encoder() -> None:
- first = LocalHyEmbedService()
- second = LocalHyEmbedService()
+class _Embedder:
+ def __init__(self) -> None:
+ self.calls: list[list[str]] = []
- assert first._embedder is second._embedder # noqa: SLF001
+ def encode(self, texts: list[str]) -> list[list[float]]:
+ self.calls.append(texts)
+ return [[float(index), 1.0] for index, _text in enumerate(texts)]
-def test_provider_kind_includes_local_onnx() -> None:
- assert ProviderKind.LOCAL_ONNX.value == "local_onnx"
+def _profile() -> ModelProfileSnapshot:
+ return ModelProfileSnapshot(
+ profile_id="local-onnx",
+ revision=1,
+ provider_kind=ProviderKind.OPENAI_COMPATIBLE,
+ base_url="https://api.example.com/v1",
+ model="generation-model",
+ embedding_provider_kind=ProviderKind.LOCAL_ONNX,
+ embedding_model=BUILTIN_EMBEDDING_MODEL,
+ embedding_dimensions=BUILTIN_EMBEDDING_DIMENSIONS,
+ timeout_seconds=30,
+ max_concurrency=1,
+ context_window=8192,
+ has_api_key=True,
+ )
def test_missing_embedding_defaults_to_the_builtin_model() -> None:
@@ -51,255 +57,79 @@ def test_missing_embedding_defaults_to_the_builtin_model() -> None:
embedding_base_url=None,
embedding_dimensions=None,
)
+
assert provider is ProviderKind.LOCAL_ONNX
assert model == BUILTIN_EMBEDDING_MODEL
assert base_url is None
assert dimensions == BUILTIN_EMBEDDING_DIMENSIONS
-def test_an_explicit_embedding_is_left_alone() -> None:
- provider, model, base_url, dimensions = apply_builtin_embedding_defaults(
- embedding_model="text-embedding-3-small",
- embedding_provider_kind=ProviderKind.OPENAI_COMPATIBLE,
- embedding_base_url="https://api.openai.com/v1",
- embedding_dimensions=1536,
- )
- assert provider is ProviderKind.OPENAI_COMPATIBLE
- assert model == "text-embedding-3-small"
- assert base_url == "https://api.openai.com/v1"
- assert dimensions == 1536
-
-
-def test_creating_a_profile_without_embedding_gets_the_builtin(
- tmp_path: Path,
-) -> None:
+def test_creating_a_profile_without_embedding_gets_the_builtin(tmp_path: Path) -> None:
store = ModelProfileStore(tmp_path / "profiles.db")
- secrets = InMemorySecretStore()
profile = store.create(
ModelProfileInput(
name="gen-only",
provider_kind=ProviderKind.OLLAMA,
model="qwen2.5",
),
- secrets,
+ InMemorySecretStore(),
)
+
assert profile.embedding_provider_kind is ProviderKind.LOCAL_ONNX
assert profile.embedding_model == BUILTIN_EMBEDDING_MODEL
assert profile.embedding_dimensions == BUILTIN_EMBEDDING_DIMENSIONS
-def test_local_embedding_is_exempt_from_the_shared_origin_rule(
- tmp_path: Path,
-) -> None:
- # Remote embedding must share the generation origin and key. Local
- # embedding never leaves the machine, so the same rule would block the
- # exact combination this feature exists for: remote generation + local
- # embedding.
- store = ModelProfileStore(tmp_path / "profiles.db")
- secrets = InMemorySecretStore()
- profile = store.create(
- ModelProfileInput(
- name="mixed",
- provider_kind=ProviderKind.OPENAI_COMPATIBLE,
- base_url="https://api.example.com/v1",
- model="gpt-4o-mini",
- embedding_provider_kind=ProviderKind.LOCAL_ONNX,
- embedding_model=BUILTIN_EMBEDDING_MODEL,
- embedding_dimensions=BUILTIN_EMBEDDING_DIMENSIONS,
- api_key="sk-test",
- ),
- secrets,
- )
- assert profile.embedding_provider_kind is ProviderKind.LOCAL_ONNX
-
+def test_local_embedding_config_needs_no_embedding_key(tmp_path: Path) -> None:
+ config = build_sdk_config(_profile(), api_key="generation-key", data_dir=tmp_path)
-def test_build_config_for_local_embedding_needs_no_embedding_key(
- tmp_path: Path,
-) -> None:
- from tests.test_hy_memory_bridge import snapshot
-
- profile = snapshot(
- ProviderKind.OPENAI_COMPATIBLE,
- base_url="https://api.example.com/v1",
- has_api_key=True,
- embedding_provider=ProviderKind.LOCAL_ONNX,
- ).model_copy(
- update={
- "embedding_model": BUILTIN_EMBEDDING_MODEL,
- "embedding_dimensions": BUILTIN_EMBEDDING_DIMENSIONS,
- }
- )
- config = build_hy_memory_config(profile, api_key="sk-gen", data_dir=tmp_path)
- assert config.vector_store.embedding_dims == BUILTIN_EMBEDDING_DIMENSIONS
+ assert config.embedder.api_key is None
+ assert config.embedder.base_url is None
assert config.embedder.embedding_dims == BUILTIN_EMBEDDING_DIMENSIONS
+ assert config.vector_store.embedding_dims == BUILTIN_EMBEDDING_DIMENSIONS
-@requires_assets
-def test_local_hy_embed_service_returns_unit_512_vectors() -> None:
- import asyncio
-
- service = LocalHyEmbedService(LocalEmbedder())
- vector = asyncio.run(service.embed("本地嵌入不需要出网"))
- assert len(vector) == 512
- length = sum(value * value for value in vector) ** 0.5
- assert length == pytest.approx(1.0, abs=1e-4)
-
-
-@requires_assets
-def test_create_client_swaps_in_the_local_embed_service(tmp_path: Path) -> None:
- from tests.test_hy_memory_bridge import snapshot
-
- profile = snapshot(
- ProviderKind.OPENAI_COMPATIBLE,
- base_url="https://api.example.com/v1",
- has_api_key=True,
- embedding_provider=ProviderKind.LOCAL_ONNX,
- ).model_copy(
- update={
- "embedding_model": BUILTIN_EMBEDDING_MODEL,
- "embedding_dimensions": BUILTIN_EMBEDDING_DIMENSIONS,
- }
- )
- # HyMemoryClient opens local chroma/kuzu on a fresh data_dir and leaves
- # the embedder alone until first call, so this does not reach the network.
- client = create_hy_memory_client(profile, api_key="sk-gen", data_dir=tmp_path)
- try:
- assert isinstance(client._embed_service, LocalHyEmbedService)
- finally:
- close = getattr(client, "close", None)
- if callable(close):
- close()
-
-
-def test_local_embed_service_covers_every_method_hy_calls() -> None:
- """我们的替代品必须覆盖 HY 真会调的全部方法 —— 名单从 HY 源码里数,不写死。
-
- 上一版这个类只实现了 `embed`,注释还写着「HY only ever calls .embed on it」。
- 装着的这个 HY 版本里,写入流水线调的是 `embed_queued`(17 处)、`embed_batch`
- (12 处)、`embed`(11 处)、`embed_with_meta`(1 处)。缺的那些不会报缺方法,
- 而是让 HY 退回它自己那个指向占位地址的服务,于是抽取以连接失败告终、
- 一条记忆都产不出来。
-
- 名单是数出来的而不是抄下来的:抄下来的名单会随 HY 升级一起烂掉,
- 而这条测试的全部意义就是替我们盯住那次升级。
- """
- import re
- from pathlib import Path as _Path
-
- import hy_memory
+def test_public_local_embedding_service_covers_single_batch_and_metadata() -> None:
+ embedder = _Embedder()
+ service = LocalOnnxEmbeddingService(embedder) # type: ignore[arg-type]
- root = _Path(hy_memory.__file__).parent
- called: set[str] = set()
- for path in root.rglob("*.py"):
- if path.name == "embed_service.py":
- continue
- called.update(re.findall(r"embed_service\.([a-z_]+)", path.read_text(encoding="utf-8")))
+ single = asyncio.run(service.embed("单条"))
+ batch = asyncio.run(service.embed_batch(["第一条", "第二条"]))
+ vector, metadata = asyncio.run(service.embed_with_meta("带元数据"))
- assert called, "一个调用点都没数到,说明这条测试自己坏了"
- missing = {name for name in called if not callable(getattr(LocalHyEmbedService, name, None))}
- assert missing == set(), f"HY 会调但我们没实现:{sorted(missing)}"
+ assert single == [0.0, 1.0]
+ assert batch == [[0.0, 1.0], [1.0, 1.0]]
+ assert vector == [0.0, 1.0]
+ assert metadata == {"provider": "local-onnx"}
+ assert service.get_embedding_dims() == BUILTIN_EMBEDDING_DIMENSIONS
-@requires_assets
-def test_the_pipelines_get_the_local_embed_service_not_only_the_client(
+def test_acquire_client_injects_public_embedding_service(
tmp_path: Path,
+ monkeypatch,
) -> None:
- """真正干活的模块拿到的必须也是本地那个。
+ captured: dict[str, object] = {}
- 这是漏掉的那一步:client 在 __init__ 里把它自己那个 EmbedService 交给了
- 组件工厂(client.py:300),而所有流水线都从工厂取(registry.py:103/137/177)。
- 只替换 client 上的引用,工厂手里攥着的还是原来那个 —— 指向
- http://127.0.0.1/local-onnx,连 TCP 都建不起来。
+ class Client:
+ def __init__(self, **kwargs: object) -> None:
+ captured.update(kwargs)
- 旧测试只断言 client 上那个引用,所以它一直是绿的,而抽取一直是零产出。
- """
- from tests.test_hy_memory_bridge import snapshot
+ def close(self) -> None:
+ return None
- profile = snapshot(
- ProviderKind.OPENAI_COMPATIBLE,
- base_url="https://api.example.com/v1",
- has_api_key=True,
- embedding_provider=ProviderKind.LOCAL_ONNX,
- ).model_copy(
- update={
- "embedding_model": BUILTIN_EMBEDDING_MODEL,
- "embedding_dimensions": BUILTIN_EMBEDDING_DIMENSIONS,
- }
+ monkeypatch.setattr("one_memory.hy_sdk_runtime.HyMemoryClient", Client)
+ monkeypatch.setattr(
+ "one_memory.hy_sdk_runtime._acquire_runtime",
+ lambda _config, _key: object(),
)
- client = create_hy_memory_client(profile, api_key="sk-gen", data_dir=tmp_path)
- try:
- shared = client._registry._shared_embed_service
- assert isinstance(shared, LocalHyEmbedService)
- # 同一个对象,不是两份各自缓存的替代品:HY 的服务自带批处理队列,
- # 两份会各攒一队,而队列的意义就是同一批一起走。
- assert shared is client._embed_service
- finally:
- close = getattr(client, "close", None)
- if callable(close):
- close()
-
-
-@requires_assets
-def test_the_write_pipeline_itself_gets_the_local_embed_service(tmp_path: Path) -> None:
- """真正写记忆的那条流水线手里必须是本地那个。
-
- 这是前两条守卫都没守住的一层,而它才是决定成败的一层。实测:改完
- client 与工厂两处引用之后,真实导入仍然 67 次 ConnectError、零记忆产出。
- 原因是 client.__init__ 在 client.py:332 就把 System2Writer 预热建好了 ——
- 那时替换还没发生,于是它抓走了 HY 原本那个服务并传给内层 writer,而
- registry._system2_writer 一旦有值就永不重建。
- 调用链是实测出来的,不是读出来的:给真实 EmbedService 的 embed_queued 挂
- 栈回溯,它自己报出 client.async_add -> system2_writer.write ->
- writer.write -> embed_queued。
- """
- from tests.test_hy_memory_bridge import snapshot
-
- profile = snapshot(
- ProviderKind.OPENAI_COMPATIBLE,
- base_url="https://api.example.com/v1",
- has_api_key=True,
- embedding_provider=ProviderKind.LOCAL_ONNX,
- ).model_copy(
- update={
- "embedding_model": BUILTIN_EMBEDDING_MODEL,
- "embedding_dimensions": BUILTIN_EMBEDDING_DIMENSIONS,
- }
- )
- client = create_hy_memory_client(profile, api_key="sk-gen", data_dir=tmp_path)
- try:
- writer = asyncio.run(client._registry.get_system2_writer())
- assert isinstance(writer._embed_service, LocalHyEmbedService)
- # 内层 writer 也要 —— 栈回溯显示 embed_queued 是它调的,不是 System2 调的。
- inner = getattr(writer, "_writer", None) or getattr(writer, "writer", None)
- assert inner is not None, "找不到内层 writer,这条测试自己坏了"
- assert isinstance(inner._embed_service, LocalHyEmbedService)
- finally:
- close = getattr(client, "close", None)
- if callable(close):
- close()
-
-
-@requires_assets
-def test_named_read_pipeline_uses_local_embedding_after_cache_replacement(tmp_path: Path) -> None:
- from tests.test_hy_memory_bridge import snapshot
-
- profile = snapshot(
- ProviderKind.OPENAI_COMPATIBLE,
- base_url="https://api.example.com/v1",
- has_api_key=True,
- embedding_provider=ProviderKind.LOCAL_ONNX,
- ).model_copy(
- update={
- "embedding_model": BUILTIN_EMBEDDING_MODEL,
- "embedding_dimensions": BUILTIN_EMBEDDING_DIMENSIONS,
- }
+ lease = acquire_client(
+ _profile(),
+ api_key="generation-key",
+ data_dir=tmp_path,
)
- client = create_hy_memory_client(profile, api_key="test-generation-key", data_dir=tmp_path)
try:
- reader = client._loop_thread.run(client._registry.get_reader(reader_name="legacy"))
- assert isinstance(reader.embed_service, LocalHyEmbedService)
- assert reader.embed_service is client._embed_service
- assert client._registry._readers["legacy"] is reader
+ assert isinstance(captured["embedding_service"], LocalOnnxEmbeddingService)
+ assert "runtime" in captured
finally:
- client.close()
+ lease.close()
diff --git a/memhub/apps/core/tests/test_main_database_entry.py b/memhub/apps/core/tests/test_main_database_entry.py
index 78223f4..1b778b8 100644
--- a/memhub/apps/core/tests/test_main_database_entry.py
+++ b/memhub/apps/core/tests/test_main_database_entry.py
@@ -91,9 +91,6 @@ ALLOWED = {
"Chroma's own chroma.sqlite3, read-only, checked before Chroma opens it",
opened_with='"?mode=ro"',
),
- ("hy_memory_bridge.py", "reattach_legacy_vector_collection"): Allowed(
- "HY's vector store chroma.sqlite3 under its persist directory, renaming a collection"
- ),
("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_memory_correction_sync.py b/memhub/apps/core/tests/test_memory_correction_sync.py
deleted file mode 100644
index 3951f37..0000000
--- a/memhub/apps/core/tests/test_memory_correction_sync.py
+++ /dev/null
@@ -1,738 +0,0 @@
-"""R-27: a correction that only lands locally, while HY keeps the old text.
-
-Deleting a memory cascades to HY (`api.py:1129` → `bridge.delete`). Correcting
-one does not: `POST /api/v1/memories/{id}/correct` writes the governance
-record and stops. The semantic half of recall comes from HY, so after a
-correction HY still matches and ranks on the old wording while the governance
-store returns the new — the user fixed it, saw it fixed, and search kept
-using the sentence they replaced.
-
-`client.update(memory_id, content)` re-embeds and upserts in place, keeping
-the id (`hy_memory/client.py:2500-2561`), so the capability was already here
-and simply never called.
-"""
-
-from __future__ import annotations
-
-import asyncio
-
-from fastapi import BackgroundTasks, Request
-from httpx import ASGITransport, AsyncClient
-from pydantic import SecretStr
-
-from one_memory.api import create_app
-from one_memory.config import Settings
-from one_memory.hy_memory_bridge import HyMemoryBridgeError
-from one_memory.imports.models import (
- EvidenceInput,
- EvidenceOrigin,
- OriginMetadata,
- WrittenBy,
-)
-from one_memory.model_profiles import (
- ModelCapabilities,
- ModelProfileInput,
- ProviderKind,
-)
-from one_memory.recall import RecallRequest, RecallState
-
-
-class FakeHy:
- """HY's side of the seam: an index keyed by memory id, plus a kill switch.
-
- Holds content rather than just recording calls, so a test can ask the
- question the user asks — does searching the new wording find it, and does
- the old wording stop finding it.
- """
-
- def __init__(self) -> None:
- self.index: dict[str, str] = {}
- self.available = True
- #: HY holds no such memory, so no retry can ever land it.
- self.rejects = False
- self.updates: list[tuple[str, str]] = []
- self.deletes: list[str] = []
- self.adds: list[object] = []
-
- async def update(self, memory_id: str, content: str) -> dict[str, object]:
- if not self.available:
- raise HyMemoryBridgeError("hy_memory_update_failed")
- if self.rejects:
- raise HyMemoryBridgeError("hy_memory_update_rejected")
- self.updates.append((memory_id, content))
- self.index[memory_id] = content
- return {"success": True, "memory_id": memory_id}
-
- async def delete(self, memory_id: str) -> dict[str, object]:
- self.deletes.append(memory_id)
- self.index.pop(memory_id, None)
- return {"success": True}
-
- async def ingest(self, request: object) -> object:
- self.adds.append(request)
- raise AssertionError("a correction must not re-add the memory")
-
- async def search_ids(self, query: str, **_kwargs) -> tuple[str, ...]:
- return tuple(memory_id for memory_id, content in self.index.items() if query in content)
-
- async def close(self) -> None:
- return None
-
-
-def _settings(tmp_path) -> Settings:
- return Settings(
- data_dir=tmp_path / "data",
- source_home=tmp_path,
- api_token=SecretStr("local-token"),
- )
-
-
-def _endpoint(app, path: str):
- """The route's own function, so a test can hold the response and the work
- scheduled after it apart — over HTTP the two are indistinguishable."""
- for route in app.router.routes:
- if getattr(route, "path", None) == path:
- return route.endpoint
- raise AssertionError(f"no route at {path}")
-
-
-def _client(app) -> AsyncClient:
- return AsyncClient(
- transport=ASGITransport(app=app),
- base_url="http://test",
- headers={
- "Authorization": "Bearer local-token",
- "Origin": "http://127.0.0.1:5173",
- },
- )
-
-
-async def _confirmed_memory(app, client: AsyncClient, content: str, tag: str = "1") -> str:
- # `tag` keeps the request ids apart. They are the mutation ledger's key, so
- # a second memory created under the first one's id would be served the
- # first one's result as a replay and never exist.
- evidence = app.state.evidence_store.put(
- EvidenceInput(
- source_id="cursor",
- conversation_id=f"conversation-{tag}",
- message_id=f"message-{tag}",
- correlation_id=f"message-{tag}",
- role="user",
- written_by=WrittenBy.PERSON,
- verbatim=content,
- origin_meta={EvidenceOrigin.FILE: OriginMetadata(raw_meta={})},
- )
- ).record
- created = await client.post(
- "/api/v1/memories",
- json={
- "request_id": f"create-{tag}",
- "draft": {
- "user_id": "local",
- "kind": "chat",
- "content": content,
- "scopes": ["all-apps"],
- "evidence_ids": [evidence.evidence_id],
- },
- },
- )
- assert created.status_code == 200
- memory_id = created.json()["memory_id"]
- return memory_id
-
-
-def _attach(app, hy: FakeHy) -> None:
- """Put the fake where the supervisor resolves its bridge.
-
- The correction path has to go through the supervisor like deletion does,
- because that is where the active profile and its secret are resolved —
- which is also why the app needs an active profile before either cascade
- can reach HY at all.
-
- `supervisor._bridge` built `HyMemoryBridge` directly until R-27 and never
- consulted `bridge_factory`, so neither cascade had a seam and the delete
- one had no test. Setting the factory is now enough to stay off the
- network, which is why the delete control below can exist at all.
- """
- profiles = app.state.model_profile_store
- secrets = app.state.secret_store
- profile = profiles.create(
- ModelProfileInput(
- name="Local",
- provider_kind=ProviderKind.OLLAMA,
- model="hy-bot-phi4",
- ),
- 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)
- supervisor = app.state.memory_processing_supervisor
- supervisor.bridge_factory = lambda _profile, _secret, _data_dir: hy
-
-
-def test_remote_correction_updates_sdk_without_retired_content_consent(tmp_path):
- async def scenario():
- app = create_app(_settings(tmp_path))
- async with app.router.lifespan_context(app), _client(app) as client:
- hy = FakeHy()
- _attach(app, hy)
- memory_id = await _confirmed_memory(app, client, "original")
- profiles, secrets = app.state.model_profile_store, app.state.secret_store
- profile = profiles.create(
- ModelProfileInput(
- name="Remote embedding",
- provider_kind=ProviderKind.OLLAMA,
- model="fixture",
- embedding_model="remote-embedding",
- embedding_provider_kind=ProviderKind.OLLAMA,
- embedding_base_url="http://127.0.0.1:1/v1",
- ),
- secrets,
- )
- profiles.record_capabilities(
- profile.profile_id,
- expected_revision=profile.revision,
- capabilities=ModelCapabilities(
- endpoint_reachable=True, model_available=True, embedding_available=True
- ),
- secrets=secrets,
- )
- profiles.activate(profile.profile_id, secrets)
- changed = await client.post(
- f"/api/v1/memories/{memory_id}/correct",
- json={
- "request_id": "local-edit",
- "expected_revision": 1,
- "content": "updated",
- "scopes": ["all-apps"],
- },
- )
- assert changed.status_code == 200
- assert changed.json()["content"] == "updated"
- assert hy.updates == [(memory_id, "updated")]
-
- asyncio.run(scenario())
-
-
-def test_correcting_a_memory_updates_hy_in_place(tmp_path) -> None:
- async def scenario() -> None:
- app = create_app(_settings(tmp_path))
- hy = FakeHy()
- async with app.router.lifespan_context(app), _client(app) as client:
- _attach(app, hy)
- memory_id = await _confirmed_memory(app, client, "用户的花名是麒麟")
- hy.index[memory_id] = "用户的花名是麒麟"
-
- corrected = await client.post(
- f"/api/v1/memories/{memory_id}/correct",
- json={
- "request_id": "correct-1",
- "expected_revision": 1,
- "content": "用户的花名是白泽",
- "scopes": ["all-apps"],
- },
- )
-
- assert corrected.status_code == 200
- assert hy.updates == [(memory_id, "用户的花名是白泽")]
- assert hy.index[memory_id] == "用户的花名是白泽"
- # The boundary: never delete-and-re-add, which would change the id
- # and break every reference already handed out.
- assert hy.deletes == []
- assert hy.adds == []
- assert corrected.json()["memory_id"] == memory_id
-
- asyncio.run(scenario())
-
-
-def test_search_follows_the_correction(tmp_path) -> None:
- """The point of the sync: the new wording is findable, the old is not."""
-
- async def scenario() -> None:
- app = create_app(_settings(tmp_path))
- hy = FakeHy()
- async with app.router.lifespan_context(app), _client(app) as client:
- _attach(app, hy)
- memory_id = await _confirmed_memory(app, client, "用户的花名是麒麟")
- hy.index[memory_id] = "用户的花名是麒麟"
-
- await client.post(
- f"/api/v1/memories/{memory_id}/correct",
- json={
- "request_id": "correct-1",
- "expected_revision": 1,
- "content": "用户的花名是白泽",
- "scopes": ["all-apps"],
- },
- )
-
- assert await hy.search_ids("白泽") == (memory_id,)
- assert await hy.search_ids("麒麟") == ()
-
- asyncio.run(scenario())
-
-
-def test_a_correction_is_not_lost_when_hy_is_down(tmp_path) -> None:
- """The user's intent outranks the downstream.
-
- The correction lands locally whatever HY does, and the fact that HY is
- behind is recorded rather than swallowed.
- """
-
- async def scenario() -> None:
- app = create_app(_settings(tmp_path))
- hy = FakeHy()
- async with app.router.lifespan_context(app), _client(app) as client:
- _attach(app, hy)
- memory_id = await _confirmed_memory(app, client, "用户的花名是麒麟")
- hy.index[memory_id] = "用户的花名是麒麟"
- hy.available = False
-
- corrected = await client.post(
- f"/api/v1/memories/{memory_id}/correct",
- json={
- "request_id": "correct-1",
- "expected_revision": 1,
- "content": "用户的花名是白泽",
- "scopes": ["all-apps"],
- },
- )
-
- assert corrected.status_code == 200
- assert corrected.json()["content"] == "用户的花名是白泽"
- detail = await client.get(f"/api/v1/memories/{memory_id}")
- sync = detail.json()["index_sync"]
- assert sync["status"] == "pending"
- assert sync["attempts"] == 1
- assert sync["last_error_code"] == "hy_memory_update_failed"
-
- asyncio.run(scenario())
-
-
-def test_the_app_can_tell_the_user_the_index_is_current(tmp_path) -> None:
- """A synced correction must be distinguishable from a pending one.
-
- Otherwise the interface has to choose between claiming success it cannot
- see and worrying the user every time.
- """
-
- async def scenario() -> None:
- app = create_app(_settings(tmp_path))
- hy = FakeHy()
- async with app.router.lifespan_context(app), _client(app) as client:
- _attach(app, hy)
- memory_id = await _confirmed_memory(app, client, "用户的花名是麒麟")
- hy.index[memory_id] = "用户的花名是麒麟"
-
- await client.post(
- f"/api/v1/memories/{memory_id}/correct",
- json={
- "request_id": "correct-1",
- "expected_revision": 1,
- "content": "用户的花名是白泽",
- "scopes": ["all-apps"],
- },
- )
-
- detail = await client.get(f"/api/v1/memories/{memory_id}")
- assert detail.json()["index_sync"]["status"] == "synced"
-
- asyncio.run(scenario())
-
-
-def test_a_retry_after_hy_returns_reaches_consistency(tmp_path) -> None:
- """ "Eventually consistent" needs something that actually retries.
-
- The retry sends the memory's current content rather than a copy taken at
- correction time, so a memory corrected twice while HY was down converges
- on the latest wording rather than replaying an intermediate one.
- """
-
- async def scenario() -> None:
- app = create_app(_settings(tmp_path))
- hy = FakeHy()
- async with app.router.lifespan_context(app), _client(app) as client:
- _attach(app, hy)
- memory_id = await _confirmed_memory(app, client, "用户的花名是麒麟")
- hy.index[memory_id] = "用户的花名是麒麟"
- hy.available = False
- await client.post(
- f"/api/v1/memories/{memory_id}/correct",
- json={
- "request_id": "correct-1",
- "expected_revision": 1,
- "content": "用户的花名是白泽",
- "scopes": ["all-apps"],
- },
- )
- await client.post(
- f"/api/v1/memories/{memory_id}/correct",
- json={
- "request_id": "correct-2",
- "expected_revision": 2,
- "content": "用户的花名是白泽,读作 bái zé",
- "scopes": ["all-apps"],
- },
- )
- hy.available = True
-
- retried = await client.post(f"/api/v1/memories/{memory_id}/index-sync")
-
- assert retried.status_code == 200
- assert retried.json()["status"] == "synced"
- assert hy.index[memory_id] == "用户的花名是白泽,读作 bái zé"
- assert len(hy.updates) == 1
- # Both failed corrections and the retry that worked: the count is
- # how anyone tells a downstream that is slow from one that is
- # broken, so a second correction must not restart it at zero.
- assert retried.json()["attempts"] == 3
-
- asyncio.run(scenario())
-
-
-def test_a_pending_sync_outlives_the_process(tmp_path) -> None:
- """Restarting must not lose the knowledge that HY is stale.
-
- A correction the user made and a downstream that never caught up is
- exactly the state a crash would otherwise erase, leaving a memory that
- searches wrong with nothing recording why.
- """
-
- async def scenario() -> None:
- hy = FakeHy()
- settings = _settings(tmp_path)
- app = create_app(settings)
- async with app.router.lifespan_context(app), _client(app) as client:
- _attach(app, hy)
- memory_id = await _confirmed_memory(app, client, "用户的花名是麒麟")
- hy.available = False
- await client.post(
- f"/api/v1/memories/{memory_id}/correct",
- json={
- "request_id": "correct-1",
- "expected_revision": 1,
- "content": "用户的花名是白泽",
- "scopes": ["all-apps"],
- },
- )
-
- # A second app over the same data_dir: new stores, nothing carried
- # over in memory, so anything it still knows it read back from disk.
- restarted = create_app(settings)
- async with restarted.router.lifespan_context(restarted), _client(restarted) as client:
- detail = await client.get(f"/api/v1/memories/{memory_id}")
- sync = detail.json()["index_sync"]
- assert sync["status"] == "pending"
- assert sync["last_error_code"] == "hy_memory_update_failed"
-
- asyncio.run(scenario())
-
-
-def test_undoing_a_correction_syncs_hy_back_too(tmp_path) -> None:
- """Undo moves the text as much as correcting it did.
-
- Taking a correction back and leaving HY matching on the withdrawn wording
- is the same defect from the other direction, and the one the user reaches
- for right after a correction they regret.
- """
-
- async def scenario() -> None:
- app = create_app(_settings(tmp_path))
- hy = FakeHy()
- async with app.router.lifespan_context(app), _client(app) as client:
- _attach(app, hy)
- memory_id = await _confirmed_memory(app, client, "用户的花名是麒麟")
- hy.index[memory_id] = "用户的花名是麒麟"
- await client.post(
- f"/api/v1/memories/{memory_id}/correct",
- json={
- "request_id": "correct-1",
- "expected_revision": 1,
- "content": "用户的花名是白泽",
- "scopes": ["all-apps"],
- },
- )
-
- undone = await client.post(
- f"/api/v1/memories/{memory_id}/actions/undo",
- json={"request_id": "undo-1", "expected_revision": 2},
- )
-
- assert undone.status_code == 200
- assert undone.json()["content"] == "用户的花名是麒麟"
- assert hy.index[memory_id] == "用户的花名是麒麟"
- assert await hy.search_ids("白泽") == ()
- detail = await client.get(f"/api/v1/memories/{memory_id}")
- assert detail.json()["index_sync"]["status"] == "synced"
-
- asyncio.run(scenario())
-
-
-def test_an_untouched_memory_has_nothing_to_sync(tmp_path) -> None:
- """The control: a memory nobody corrected must not look out of date.
-
- Green before and after. If every memory reported a sync state, the
- interface would have to explain a status the user never caused — and
- confirming this one moved its status without moving a word of its text,
- which is the distinction the reindex has to be keyed on.
- """
-
- async def scenario() -> None:
- app = create_app(_settings(tmp_path))
- hy = FakeHy()
- async with app.router.lifespan_context(app), _client(app) as client:
- _attach(app, hy)
- memory_id = await _confirmed_memory(app, client, "用户的花名是麒麟")
-
- detail = await client.get(f"/api/v1/memories/{memory_id}")
-
- assert detail.json()["index_sync"] is None
- assert hy.updates == []
-
- asyncio.run(scenario())
-
-
-async def _stale_memory(app, client: AsyncClient, hy: FakeHy) -> str:
- """A memory the user corrected while HY was unreachable.
-
- The state this whole section is about: the app reads 白泽, HY still
- matches on 麒麟, and nothing has caught up.
- """
- memory_id = await _confirmed_memory(app, client, "用户的花名是麒麟")
- hy.index[memory_id] = "用户的花名是麒麟"
- hy.available = False
- await client.post(
- f"/api/v1/memories/{memory_id}/correct",
- json={
- "request_id": "correct-1",
- "expected_revision": 1,
- "content": "用户的花名是白泽",
- "scopes": ["all-apps"],
- },
- )
- hy.available = True
- return memory_id
-
-
-def test_a_recall_that_returns_a_stale_memory_catches_hy_up(tmp_path) -> None:
- """Where the retry belongs: the moment the memory is actually read.
-
- Not a sweep at startup — the night the office lost its outbound network,
- calling HY on launch would have turned one outage into an app that will
- not open. A memory's index being behind can only be observed through
- recall, so recall is where catching up is worth anything.
- """
-
- async def scenario() -> None:
- app = create_app(_settings(tmp_path))
- hy = FakeHy()
- async with app.router.lifespan_context(app), _client(app) as client:
- _attach(app, hy)
- memory_id = await _stale_memory(app, client, hy)
-
- recalled = await client.post(
- "/api/v1/recall",
- json={"query": "白泽", "scope": "all-apps"},
- )
-
- assert recalled.status_code == 200
- assert recalled.json()["state"] == "grounded"
- assert hy.index[memory_id] == "用户的花名是白泽"
- detail = await client.get(f"/api/v1/memories/{memory_id}")
- assert detail.json()["index_sync"]["status"] == "synced"
-
- asyncio.run(scenario())
-
-
-def test_the_recall_itself_does_not_wait_on_hy_being_back(tmp_path) -> None:
- """The recall answers from the governance store, which already holds the
- corrected text. Letting a still-unreachable HY turn that into an error, or
- into a wait, would make the fix worse than the defect."""
-
- async def scenario() -> None:
- app = create_app(_settings(tmp_path))
- hy = FakeHy()
- async with app.router.lifespan_context(app), _client(app) as client:
- _attach(app, hy)
- memory_id = await _stale_memory(app, client, hy)
- hy.available = False
-
- recalled = await client.post(
- "/api/v1/recall",
- json={"query": "白泽", "scope": "all-apps"},
- )
-
- assert recalled.status_code == 200
- assert recalled.json()["state"] == "grounded"
- assert recalled.json()["hits"][0]["content"] == "用户的花名是白泽"
- detail = await client.get(f"/api/v1/memories/{memory_id}")
- sync = detail.json()["index_sync"]
- assert sync["status"] == "pending"
- assert sync["attempts"] == 2
-
- asyncio.run(scenario())
-
-
-def test_a_memory_no_recall_returned_is_left_alone(tmp_path) -> None:
- """Scoping the work to what was read is the whole reason this is cheap.
-
- A memory nobody recalls is a memory nobody reads, so its index being
- behind is a difference no user can observe — and paying for it would mean
- a call to HY per stale memory on every recall.
-
- So the recall here does ground on something: a catch-up that skipped this
- memory only because nothing at all was returned would prove nothing.
- """
-
- async def scenario() -> None:
- app = create_app(_settings(tmp_path))
- hy = FakeHy()
- async with app.router.lifespan_context(app), _client(app) as client:
- _attach(app, hy)
- stale_id = await _stale_memory(app, client, hy)
- await _confirmed_memory(app, client, "用户在用 Cursor 写代码", tag="2")
-
- recalled = await client.post(
- "/api/v1/recall",
- json={"query": "Cursor", "scope": "all-apps"},
- )
-
- assert recalled.status_code == 200
- assert recalled.json()["state"] == "grounded"
- assert stale_id not in {hit["memory_id"] for hit in recalled.json()["hits"]}
- assert hy.updates == []
- assert hy.index[stale_id] == "用户的花名是麒麟"
-
- asyncio.run(scenario())
-
-
-def test_the_recall_answers_before_the_catch_up_runs(tmp_path) -> None:
- """The ordering is the reason recall is a safe place to do this at all.
-
- Called through the route so the two halves are separable: the receipt is
- built without HY in the picture, and the catch-up is left as work for
- afterwards. Done inline instead, every recall would wait on a network
- call — the exact cost that ruled out doing this at startup.
- """
-
- async def scenario() -> None:
- app = create_app(_settings(tmp_path))
- hy = FakeHy()
- async with app.router.lifespan_context(app), _client(app) as client:
- _attach(app, hy)
- memory_id = await _stale_memory(app, client, hy)
- recall = _endpoint(app, "/api/v1/recall")
- background = BackgroundTasks()
-
- receipt = await recall(
- RecallRequest(query="白泽", scope="all-apps"),
- background,
- Request({"type": "http", "headers": []}),
- )
-
- assert receipt.state is RecallState.GROUNDED
- assert hy.updates == []
- assert background.tasks
-
- await background()
-
- assert hy.index[memory_id] == "用户的花名是白泽"
-
- asyncio.run(scenario())
-
-
-def test_a_retry_hy_can_never_accept_is_not_made_on_every_recall(tmp_path) -> None:
- """`hy_memory_update_rejected` means HY has no such memory to re-embed.
-
- Retrying it is a call that cannot succeed, and recall is the one path that
- runs constantly — so this is the difference between a harmless catch-up
- and a request to HY every time anyone recalls anything.
- """
-
- async def scenario() -> None:
- app = create_app(_settings(tmp_path))
- hy = FakeHy()
- async with app.router.lifespan_context(app), _client(app) as client:
- _attach(app, hy)
- memory_id = await _confirmed_memory(app, client, "用户的花名是麒麟")
- hy.rejects = True
- await client.post(
- f"/api/v1/memories/{memory_id}/correct",
- json={
- "request_id": "correct-1",
- "expected_revision": 1,
- "content": "用户的花名是白泽",
- "scopes": ["all-apps"],
- },
- )
- hy.updates.clear()
-
- await client.post(
- "/api/v1/recall",
- json={"query": "白泽", "scope": "all-apps"},
- )
-
- assert hy.updates == []
- detail = await client.get(f"/api/v1/memories/{memory_id}")
- sync = detail.json()["index_sync"]
- assert sync["status"] == "pending"
- assert sync["attempts"] == 1
-
- asyncio.run(scenario())
-
-
-def test_recall_touches_hy_for_nothing_when_no_memory_is_behind(tmp_path) -> None:
- """The control: recall is the hot path, and it stays quiet.
-
- Green before and after. Every recall in the product runs through here, so
- a catch-up that fired on memories nobody corrected would be a permanent
- tax on the one call that has to stay fast.
- """
-
- async def scenario() -> None:
- app = create_app(_settings(tmp_path))
- hy = FakeHy()
- async with app.router.lifespan_context(app), _client(app) as client:
- _attach(app, hy)
- await _confirmed_memory(app, client, "用户的花名是麒麟")
-
- recalled = await client.post(
- "/api/v1/recall",
- json={"query": "麒麟", "scope": "all-apps"},
- )
-
- assert recalled.json()["state"] == "grounded"
- assert hy.updates == []
-
- asyncio.run(scenario())
-
-
-def test_deletion_still_cascades_the_way_it_did(tmp_path) -> None:
- """The control for the path that already worked."""
-
- async def scenario() -> None:
- app = create_app(_settings(tmp_path))
- hy = FakeHy()
- async with app.router.lifespan_context(app), _client(app) as client:
- _attach(app, hy)
- memory_id = await _confirmed_memory(app, client, "用户的花名是麒麟")
-
- deleted = await client.post(
- f"/api/v1/memories/{memory_id}/actions/delete",
- json={"request_id": "delete-1", "expected_revision": 1},
- )
-
- assert deleted.status_code == 200
- assert hy.deletes == [memory_id]
-
- asyncio.run(scenario())
diff --git a/memhub/apps/core/tests/test_memory_governance.py b/memhub/apps/core/tests/test_memory_governance.py
deleted file mode 100644
index 20133f0..0000000
--- a/memhub/apps/core/tests/test_memory_governance.py
+++ /dev/null
@@ -1,1870 +0,0 @@
-import sqlite3
-import threading
-
-import pytest
-from pydantic import ValidationError
-
-from one_memory.imports.models import (
- EvidenceInput,
- EvidenceOrigin,
- OriginMetadata,
- WrittenBy,
-)
-from one_memory.imports.storage import EvidenceStore
-from one_memory.library_upgrade import LibraryUpgradeError
-from one_memory.memory_governance import (
- CONTENT_CANDIDATE_UNION_VERSION,
- DeletionStatus,
- HySupersede,
- MemoryDraft,
- MemoryGovernanceStore,
- MemoryKind,
- MemoryMutationConflictError,
- MemoryMutationRequestConflictError,
- MemoryOrigin,
- MemoryStatus,
- content_candidate_plan,
- content_candidate_predicate,
- ensure_content_candidate_index,
-)
-from tests.person_door import as_person
-
-
-def evidence(database, *, message_id: str, verbatim: str, user_id: str = "local") -> str:
- result = EvidenceStore(database).put(
- EvidenceInput(
- user_id=user_id,
- source_id="cursor",
- conversation_id="conversation",
- message_id=message_id,
- correlation_id=message_id,
- role="user",
- written_by=WrittenBy.PERSON,
- verbatim=verbatim,
- origin_meta={EvidenceOrigin.FILE: OriginMetadata()},
- )
- )
- return result.record.evidence_id
-
-
-def test_correction_keeps_verbatim_and_appends_history(tmp_path) -> None:
- database = tmp_path / "one-memory.sqlite3"
- evidence_id = evidence(database, message_id="m1", verbatim="Original words")
- store = MemoryGovernanceStore(database)
- created = as_person(store).create(
- MemoryDraft(
- user_id="local",
- kind=MemoryKind.CHAT,
- content="Initial extraction",
- scopes=("all-apps",),
- evidence_ids=(evidence_id,),
- ),
- request_id="create-1",
- )
-
- corrected = as_person(store).correct(
- created.memory_id,
- user_id="local",
- request_id="correct-1",
- expected_revision=1,
- content="Corrected memory",
- scopes=("cursor", "claude-code"),
- )
- undone = as_person(store).undo(
- created.memory_id,
- user_id="local",
- request_id="undo-1",
- expected_revision=2,
- )
-
- assert created.status is MemoryStatus.CONFIRMED
- assert corrected.content == "Corrected memory"
- assert corrected.scopes == ("cursor", "claude-code")
- assert undone.content == "Initial extraction"
- assert undone.status is MemoryStatus.CONFIRMED
- assert [version.action for version in store.history(created.memory_id, user_id="local")] == [
- "undo",
- "correct",
- "create",
- ]
- assert EvidenceStore(database).get(evidence_id).verbatim == "Original words" # type: ignore[union-attr]
-
-
-def test_mutations_are_revision_checked_and_request_idempotent(tmp_path) -> None:
- database = tmp_path / "one-memory.sqlite3"
- evidence_id = evidence(database, message_id="m1", verbatim="Original")
- store = MemoryGovernanceStore(database)
- created = as_person(store).create(
- MemoryDraft(
- user_id="local",
- kind=MemoryKind.WORKING,
- content="Candidate",
- scopes=("all-apps",),
- evidence_ids=(evidence_id,),
- ),
- request_id="create-1",
- )
-
- first = as_person(store).delete(
- created.memory_id,
- user_id="local",
- request_id="delete-1",
- expected_revision=1,
- )
- duplicate = as_person(store).delete(
- created.memory_id,
- user_id="local",
- request_id="delete-1",
- expected_revision=1,
- )
-
- assert first == duplicate
- with pytest.raises(MemoryMutationConflictError):
- as_person(store).correct(
- created.memory_id,
- user_id="local",
- request_id="stale",
- expected_revision=1,
- content="Stale correction",
- )
- with pytest.raises(MemoryMutationRequestConflictError):
- as_person(store).undo(
- created.memory_id,
- user_id="local",
- request_id="delete-1",
- expected_revision=2,
- )
- with pytest.raises(MemoryMutationConflictError, match="memory_deleted"):
- as_person(store).correct(
- created.memory_id,
- user_id="local",
- request_id="deleted-correction",
- expected_revision=2,
- content="Must not be stored",
- )
-
-
-def test_delete_result_survives_restart_and_request_replay(tmp_path) -> None:
- database = tmp_path / "one-memory.sqlite3"
- evidence_id = evidence(database, message_id="delete-replay", verbatim="Original")
- store = MemoryGovernanceStore(database)
- created = as_person(store).create(
- MemoryDraft(
- user_id="local",
- kind=MemoryKind.WORKING,
- content="Delete replay target",
- scopes=("all-apps",),
- evidence_ids=(evidence_id,),
- ),
- request_id="create-delete-replay",
- )
- first = as_person(store).delete(
- created.memory_id,
- user_id="local",
- request_id="delete-replay",
- expected_revision=created.revision,
- )
-
- reopened = MemoryGovernanceStore(database)
- after_restart = reopened.get(created.memory_id, user_id="local")
- assert after_restart is not None
- assert after_restart.status is MemoryStatus.DELETED
- assert reopened.deletion(created.memory_id, user_id="local") is not None
-
- replay = as_person(reopened).delete(
- created.memory_id,
- user_id="local",
- request_id="delete-replay",
- expected_revision=created.revision,
- )
- assert replay == first == after_restart
-
-
-def test_repeated_undo_walks_back_distinct_revisions(tmp_path) -> None:
- database = tmp_path / "one-memory.sqlite3"
- evidence_id = evidence(database, message_id="m1", verbatim="Original")
- store = MemoryGovernanceStore(database)
- created = as_person(store).create(
- MemoryDraft(
- user_id="local",
- kind=MemoryKind.CHAT,
- content="A",
- scopes=("all-apps",),
- evidence_ids=(evidence_id,),
- ),
- request_id="create-1",
- )
- second = as_person(store).correct(
- created.memory_id,
- user_id="local",
- request_id="correct-1",
- expected_revision=1,
- content="B",
- )
- third = as_person(store).correct(
- created.memory_id,
- user_id="local",
- request_id="correct-2",
- expected_revision=second.revision,
- content="C",
- )
-
- first_undo = as_person(store).undo(
- created.memory_id,
- user_id="local",
- request_id="undo-1",
- expected_revision=third.revision,
- )
- second_undo = as_person(store).undo(
- created.memory_id,
- user_id="local",
- request_id="undo-2",
- expected_revision=first_undo.revision,
- )
-
- assert first_undo.content == "B"
- assert second_undo.content == "A"
- with pytest.raises(MemoryMutationConflictError, match="memory_nothing_to_undo"):
- as_person(store).undo(
- created.memory_id,
- user_id="local",
- request_id="undo-3",
- expected_revision=second_undo.revision,
- )
-
-
-def test_confirmed_content_shadow_follows_create_correct_and_delete(tmp_path) -> None:
- database = tmp_path / "one-memory.sqlite3"
- evidence_id = evidence(database, message_id="shadow", verbatim="原文保持不变")
- store = MemoryGovernanceStore(database)
- created = as_person(store).create(
- MemoryDraft(
- user_id="local",
- kind=MemoryKind.CHAT,
- content="独特记忆目标短语",
- scopes=("all-apps",),
- evidence_ids=(evidence_id,),
- ),
- request_id="create-shadow",
- )
-
- found, more = store.find_confirmed_matching_terms(user_id="local", terms=("独特记忆目标短语",))
- assert [memory.memory_id for memory in found] == [created.memory_id]
- assert more is False
-
- corrected = as_person(store).correct(
- created.memory_id,
- user_id="local",
- request_id="correct-shadow",
- expected_revision=created.revision,
- content="更正后的不同短语",
- )
- assert (
- store.find_confirmed_matching_terms(user_id="local", terms=("独特记忆目标短语",))[0] == []
- )
- assert [
- memory.memory_id
- for memory in store.find_confirmed_matching_terms(
- user_id="local", terms=("更正后的不同短语",)
- )[0]
- ] == [created.memory_id]
-
- as_person(store).delete(
- corrected.memory_id,
- user_id="local",
- request_id="delete-shadow",
- expected_revision=corrected.revision,
- )
- assert (
- store.find_confirmed_matching_terms(user_id="local", terms=("更正后的不同短语",))[0] == []
- )
-
-
-def test_superseded_memory_leaves_the_content_shadow_after_restart(tmp_path) -> None:
- """The derived candidate path must not resurrect a superseded memory."""
- database = tmp_path / "one-memory.sqlite3"
- old_evidence = evidence(database, message_id="supersede-shadow-old", verbatim="原文")
- new_evidence = evidence(database, message_id="supersede-shadow-new", verbatim="原文")
- store = MemoryGovernanceStore(database)
- door = as_person(store)
- old = door.create(
- MemoryDraft(
- user_id="local",
- kind=MemoryKind.CHAT,
- content="旧版发布窗口是周四。",
- scopes=("all-apps",),
- evidence_ids=(old_evidence,),
- ),
- request_id="supersede-shadow-old",
- )
- new = door.create(
- MemoryDraft(
- user_id="local",
- kind=MemoryKind.CHAT,
- content="新版发布窗口是周五。",
- scopes=("all-apps",),
- evidence_ids=(new_evidence,),
- ),
- request_id="supersede-shadow-new",
- )
- assert old.memory_id in {
- memory.memory_id
- for memory in store.find_confirmed_matching_terms(user_id="local", terms=("旧版发布",))[0]
- }
- store.write_from_hy(
- HySupersede(
- memory_id=old.memory_id,
- request_id="hy-supersede-shadow",
- expected_revision=old.revision,
- superseded_by=(new.memory_id,),
- ),
- user_id="local",
- derivation=store.hy_derivation((old_evidence, new_evidence)),
- )
- assert old.memory_id not in {
- memory.memory_id
- for memory in store.find_confirmed_matching_terms(user_id="local", terms=("旧版发布",))[0]
- }
- reopened = MemoryGovernanceStore(database)
- assert old.memory_id not in {
- memory.memory_id
- for memory in reopened.find_confirmed_matching_terms(user_id="local", terms=("旧版发布",))[
- 0
- ]
- }
-
-
-def test_delete_atomically_creates_cleanup_without_erasing_shared_evidence(
- tmp_path,
-) -> None:
- database = tmp_path / "one-memory.sqlite3"
- evidence_id = evidence(database, message_id="m1", verbatim="Shared original")
- store = MemoryGovernanceStore(database)
- memories = [
- as_person(store).create(
- MemoryDraft(
- user_id="local",
- kind=MemoryKind.CHAT,
- content=content,
- scopes=("all-apps",),
- evidence_ids=(evidence_id,),
- ),
- request_id=f"create-{index}",
- )
- for index, content in enumerate(("First", "Second"))
- ]
-
- deleted = as_person(store).delete(
- memories[0].memory_id,
- user_id="local",
- request_id="delete-1",
- expected_revision=1,
- )
- cleanup = store.deletion(memories[0].memory_id, user_id="local")
-
- assert deleted.status is MemoryStatus.DELETED
- assert cleanup is not None
- assert cleanup.status is DeletionStatus.PENDING
- assert EvidenceStore(database).get(evidence_id) is not None
- assert store.get(memories[1].memory_id, user_id="local") is not None
-
-
-def test_batch_delete_keeps_shared_verbatim_until_the_last_reference_goes(
- tmp_path,
-) -> None:
- """RL-27's reference-count constraint, exercised the way the bulk UI works.
-
- The UI has no batch endpoint; it deletes one memory at a time. So the case
- that matters is the intermediate state: two of three references gone, one
- still standing. The verbatim has to survive that, and only that survival
- is what makes bulk delete safe to offer at all.
-
- Verified non-vacuous by mutation. Worth recording what the mutation had to
- do to get there: a plain `DELETE FROM evidence` in `delete` cannot even
- run, because the surviving memory's link row holds a foreign key on it. To
- lose the verbatim the mutation has to drop every link first — so today the
- schema, not any reference count, is what keeps shared originals alive.
- """
- database = tmp_path / "one-memory.sqlite3"
- evidence_id = evidence(database, message_id="m1", verbatim="Shared original")
- store = MemoryGovernanceStore(database)
- memories = [
- as_person(store).create(
- MemoryDraft(
- user_id="local",
- kind=MemoryKind.CHAT,
- content=content,
- scopes=("all-apps",),
- evidence_ids=(evidence_id,),
- ),
- request_id=f"create-{index}",
- )
- for index, content in enumerate(("First", "Second", "Third"))
- ]
-
- for index, target in enumerate(memories[:2]):
- as_person(store).delete(
- target.memory_id,
- user_id="local",
- request_id=f"bulk-delete-{index}",
- expected_revision=1,
- )
-
- survivor = store.get(memories[2].memory_id, user_id="local")
- assert survivor is not None
- assert survivor.status is MemoryStatus.CONFIRMED
- assert EvidenceStore(database).get(evidence_id) is not None
- assert store.has_evidence_link(evidence_id) is True
-
-
-def test_list_is_user_scoped_and_escapes_wildcards(tmp_path) -> None:
- database = tmp_path / "one-memory.sqlite3"
- evidence_id = evidence(database, message_id="m1", verbatim="Original")
- store = MemoryGovernanceStore(database)
- as_person(store).create(
- MemoryDraft(
- user_id="local",
- kind=MemoryKind.CHAT,
- content="Uses 100% local processing",
- scopes=("all-apps",),
- evidence_ids=(evidence_id,),
- ),
- request_id="create-1",
- )
-
- assert len(store.list(user_id="local", query="100%")) == 1
- assert store.list(user_id="another-user") == []
-
-
-def test_a_memory_says_how_it_got_here(tmp_path) -> None:
- """回填进来的答案要和抽出来的记忆分得开。
-
- 分不开的后果是具体的:记忆一经写入就进召回,看不出这条是模型写的
- 综述还是你自己说过的话,别的 AI 就会把它当成你本人的判决读回去。
- """
- database = tmp_path / "one-memory.sqlite3"
- evidence_id = evidence(database, message_id="m1", verbatim="周末不排评审会")
- store = MemoryGovernanceStore(database)
-
- extracted = as_person(store).create(
- MemoryDraft(
- user_id="local",
- kind=MemoryKind.CHAT,
- content="用户周末不安排评审会。",
- scopes=("all-apps",),
- evidence_ids=(evidence_id,),
- ),
- request_id="create-extracted",
- )
- answered = as_person(store).create(
- MemoryDraft(
- user_id="local",
- kind=MemoryKind.CHAT,
- content="综上,用户的排期习惯是把评审集中在工作日。",
- scopes=("all-apps",),
- evidence_ids=(evidence_id,),
- origin=MemoryOrigin.ANSWERED,
- ),
- request_id="create-answered",
- )
-
- assert extracted.origin is MemoryOrigin.EXTRACTED
- assert answered.origin is MemoryOrigin.ANSWERED
- stored = {item.memory_id: item.origin for item in store.list(user_id="local")}
- assert stored[extracted.memory_id] is MemoryOrigin.EXTRACTED
- assert stored[answered.memory_id] is MemoryOrigin.ANSWERED
-
-
-def test_a_library_written_before_this_column_existed_still_opens(tmp_path) -> None:
- """老库里的每一条都是抽出来的,因为那时候没有别的来路。
-
- 正向对照在上一条:新写进去的 answered 读回来必须还是 answered,
- 否则这条测的只是「全都读成 extracted」。
- """
- database = tmp_path / "one-memory.sqlite3"
- evidence_id = evidence(database, message_id="m1", verbatim="周末不排评审会")
- store = MemoryGovernanceStore(database)
- created = as_person(store).create(
- MemoryDraft(
- user_id="local",
- kind=MemoryKind.CHAT,
- content="用户周末不安排评审会。",
- scopes=("all-apps",),
- evidence_ids=(evidence_id,),
- ),
- request_id="create-1",
- )
-
- # 把这一列真的拆掉,模拟一个这轮改动之前写下的库。
- with sqlite3.connect(database) as connection:
- connection.execute("ALTER TABLE governed_memories DROP COLUMN origin")
- columns = {
- row[1] for row in sqlite3.connect(database).execute("PRAGMA table_info(governed_memories)")
- }
- assert "origin" not in columns
-
- reopened = MemoryGovernanceStore(database)
- memory = reopened.get(created.memory_id, user_id="local")
-
- assert memory is not None
- assert memory.origin is MemoryOrigin.EXTRACTED
-
-
-def test_a_made_up_origin_is_refused(tmp_path) -> None:
- database = tmp_path / "one-memory.sqlite3"
- evidence_id = evidence(database, message_id="m1", verbatim="周末不排评审会")
- MemoryGovernanceStore(database)
-
- with pytest.raises(ValidationError):
- MemoryDraft(
- user_id="local",
- kind=MemoryKind.CHAT,
- content="随便写的",
- scopes=("all-apps",),
- evidence_ids=(evidence_id,),
- origin="模型瞎编的来路",
- )
-
-
-def test_topic_tags_survive_a_round_trip(tmp_path) -> None:
- """HY 每条记忆都带 tags,而边界上一直全丢。
-
- 它抽取前会先把库里已有的标签收集起来喂进 prompt 引导复用,所以这套
- 聚类其实一直在跑,只是从没浮到产品层。
- """
- database = tmp_path / "one-memory.sqlite3"
- evidence_id = evidence(database, message_id="m1", verbatim="周末不排评审会")
- store = MemoryGovernanceStore(database)
-
- created = as_person(store).create(
- MemoryDraft(
- user_id="local",
- kind=MemoryKind.CHAT,
- content="用户周末不安排评审会。",
- scopes=("all-apps",),
- evidence_ids=(evidence_id,),
- tags=("排期", "工作习惯"),
- ),
- request_id="create-1",
- )
-
- assert created.tags == ("排期", "工作习惯")
- assert store.get(created.memory_id, user_id="local").tags == ("排期", "工作习惯")
-
-
-def test_a_memory_with_no_tags_reads_as_none_rather_than_breaking(tmp_path) -> None:
- """正向对照在上一条:带标签的读回来必须还带着,否则这条测的只是「全是空」。"""
- database = tmp_path / "one-memory.sqlite3"
- evidence_id = evidence(database, message_id="m1", verbatim="周末不排评审会")
- store = MemoryGovernanceStore(database)
- created = as_person(store).create(
- MemoryDraft(
- user_id="local",
- kind=MemoryKind.CHAT,
- content="用户周末不安排评审会。",
- scopes=("all-apps",),
- evidence_ids=(evidence_id,),
- ),
- request_id="create-1",
- )
-
- with sqlite3.connect(database) as connection:
- connection.execute("ALTER TABLE governed_memories DROP COLUMN tags_json")
-
- reopened = MemoryGovernanceStore(database)
-
- assert reopened.get(created.memory_id, user_id="local").tags == ()
- assert created.tags == ()
-
-
-def test_content_candidate_predicate_is_optional_and_stable(tmp_path) -> None:
- database = tmp_path / "one-memory.sqlite3"
- evidence_id = evidence(database, message_id="predicate", verbatim="原文")
- store = MemoryGovernanceStore(database)
- as_person(store).create(
- MemoryDraft(
- user_id="local",
- kind=MemoryKind.CHAT,
- content="独特记忆目标短语",
- scopes=("all-apps",),
- evidence_ids=(evidence_id,),
- ),
- request_id="create-predicate",
- )
-
- with store._connection() as connection:
- predicate, values = content_candidate_predicate(connection, ("独特", "特记", "记忆"))
-
- assert predicate is not None
- assert "governed_memories_terms" in predicate
- assert values == ("独特", "特记", "记忆")
-
-
-def test_content_candidate_union_keeps_or_semantics_across_terms(tmp_path) -> None:
- assert CONTENT_CANDIDATE_UNION_VERSION >= 1
- database = tmp_path / "one-memory.sqlite3"
- first_evidence = evidence(database, message_id="candidate-a", verbatim="甲")
- second_evidence = evidence(database, message_id="candidate-b", verbatim="乙")
- store = MemoryGovernanceStore(database)
- door = as_person(store)
- first = door.create(
- MemoryDraft(
- user_id="local",
- kind=MemoryKind.CHAT,
- content="稀有术语 甲",
- scopes=("all-apps",),
- evidence_ids=(first_evidence,),
- ),
- request_id="candidate-a",
- )
- second = door.create(
- MemoryDraft(
- user_id="local",
- kind=MemoryKind.CHAT,
- content="常见词分支 乙",
- scopes=("all-apps",),
- evidence_ids=(second_evidence,),
- ),
- request_id="candidate-b",
- )
-
- found, more = store.find_confirmed_matching_terms(user_id="local", terms=("有术", "见词"))
-
- assert {memory.memory_id for memory in found} == {first.memory_id, second.memory_id}
- assert more is False
-
-
-def test_partially_indexed_terms_fall_back_to_like_instead_of_dropping_matches(tmp_path) -> None:
- """A mixed term set must not silently drop the non-indexed terms' matches.
-
- Contract guard, not a live reproduction: the shadow indexes CJK bigrams and
- latin tokens of length >= 2 only, and a bounded candidate set built from
- just the indexed terms would drop a row whose sole match is a non-indexed
- term. Today the only production caller (recall) passes `_terms()` output,
- which is always indexable, so the mixed case is unreachable in production;
- this pins the store's behaviour for a future direct caller instead of
- relying on every caller to filter first.
- """
- database = tmp_path / "one-memory.sqlite3"
- store = MemoryGovernanceStore(database)
- door = as_person(store)
- single = door.create(
- MemoryDraft(
- user_id="local",
- kind=MemoryKind.CHAT,
- content="张 的偏好",
- scopes=("all-apps",),
- evidence_ids=(evidence(database, message_id="partial-single", verbatim="甲"),),
- ),
- request_id="partial-single",
- )
- shared = door.create(
- MemoryDraft(
- user_id="local",
- kind=MemoryKind.CHAT,
- content="shared target",
- scopes=("all-apps",),
- evidence_ids=(evidence(database, message_id="partial-shared", verbatim="乙"),),
- ),
- request_id="partial-shared",
- )
-
- # The single character alone matches on the exact path.
- only_single, _ = store.find_confirmed_matching_terms(user_id="local", terms=("张",))
- assert {memory.memory_id for memory in only_single} == {single.memory_id}
-
- # Mixed with an indexable bigram it must still find both memories.
- mixed, more = store.find_confirmed_matching_terms(user_id="local", terms=("张", "shared"))
- assert {memory.memory_id for memory in mixed} == {single.memory_id, shared.memory_id}
- assert more is False
-
-
-def test_a_query_over_the_term_cap_reports_truncation_instead_of_a_clean_empty(tmp_path) -> None:
- """Dropping terms past the cap must set `more`, not read as a complete result.
-
- The candidate union only takes 32 distinct terms. Recall passes every term
- it extracted, so a long query can exceed that bound; the dropped terms were
- silently discarded and recall answered empty with `truncated=False` even
- when a memory matched only a dropped term. The store now reports that
- truncation through `more`, so recall says "I did not finish looking".
- """
- database = tmp_path / "one-memory.sqlite3"
- store = MemoryGovernanceStore(database)
- door = as_person(store)
- door.create(
- MemoryDraft(
- user_id="local",
- kind=MemoryKind.CHAT,
- content="zeta unique",
- scopes=("all-apps",),
- evidence_ids=(evidence(database, message_id="term-cap", verbatim="甲"),),
- ),
- request_id="term-cap",
- )
- # 33 alphabetically-earlier latin terms, then the matching one. Under the
- # cap the 33rd.. terms (including "zeta") are dropped.
- terms = tuple(f"term{i:02d}" for i in range(33)) + ("zeta",)
- found, more = store.find_confirmed_matching_terms(user_id="local", terms=terms)
- assert found == []
- assert more is True
-
- # A query within the cap stays a clean complete answer.
- found_within, more_within = store.find_confirmed_matching_terms(
- user_id="local", terms=("zeta", "alpha")
- )
- assert [memory.content for memory in found_within] == ["zeta unique"]
- assert more_within is False
-
- # Exactly at the cap nothing is dropped, so the answer must not claim
- # truncation: 32 distinct terms is still a complete search of all of them.
- at_cap = tuple(f"term{i:02d}" for i in range(32))
- _, more_at_cap = store.find_confirmed_matching_terms(user_id="local", terms=at_cap)
- assert more_at_cap is False
-
-
-def test_content_candidate_shadow_honors_a_larger_caller_limit(tmp_path) -> None:
- database = tmp_path / "one-memory.sqlite3"
- store = MemoryGovernanceStore(database)
- door = as_person(store)
- for index in range(250):
- evidence_id = evidence(database, message_id=f"limit-shadow-{index}", verbatim="甲")
- door.create(
- MemoryDraft(
- user_id="local",
- kind=MemoryKind.CHAT,
- content=f"共享目标短语 {index}",
- scopes=("all-apps",),
- evidence_ids=(evidence_id,),
- ),
- request_id=f"limit-shadow-{index}",
- )
-
- found, more = store.find_confirmed_matching_terms(user_id="local", terms=("共享",), limit=300)
-
- assert len(found) == 250
- assert more is False
-
-
-def test_public_candidate_index_initializer_backfills_a_bare_schema(tmp_path) -> None:
- """The public initializer repairs rows only after migration owns the tables.
-
- A bare business table is not a schema. Before migration 32, the initializer
- must fail with a stable machine code instead of becoming a second schema
- owner; after migration 32, it backfills normally.
- """
- database = tmp_path / "one-memory.sqlite3"
- EvidenceStore(database)
- with sqlite3.connect(database) as connection, connection:
- connection.execute(
- "CREATE TABLE governed_memories ("
- "memory_id TEXT PRIMARY KEY,user_id TEXT NOT NULL,kind TEXT NOT NULL,"
- "status TEXT NOT NULL,content TEXT NOT NULL,scopes_json TEXT NOT NULL,"
- "origin TEXT,tags_json TEXT,revision INTEGER NOT NULL,"
- "created_at TEXT NOT NULL,updated_at TEXT NOT NULL,deleted_at TEXT,"
- "undo_cursor_revision INTEGER)"
- )
- with pytest.raises(LibraryUpgradeError, match="governance_schema_missing"):
- ensure_content_candidate_index(connection)
-
- MemoryGovernanceStore(database)
- with sqlite3.connect(database) as connection, connection:
- connection.execute(
- "INSERT INTO governed_memories VALUES "
- "('m1','local','working','confirmed','独特记忆目标短语','[\"all-apps\"]',"
- "'extracted','[]',1,'now','now',NULL,NULL)"
- )
- ensure_content_candidate_index(connection)
- assert connection.execute("SELECT count(*) FROM governed_memories_terms").fetchone()[0] > 0
-
-
-def test_frequency_threshold_keeps_a_common_term_on_the_like_path(tmp_path, monkeypatch) -> None:
- database = tmp_path / "one-memory.sqlite3"
- first_evidence = evidence(database, message_id="common-a", verbatim="甲")
- second_evidence = evidence(database, message_id="common-b", verbatim="乙")
- store = MemoryGovernanceStore(database)
- door = as_person(store)
- for index, (evidence_id, content) in enumerate(
- ((first_evidence, "common alpha"), (second_evidence, "common beta"))
- ):
- door.create(
- MemoryDraft(
- user_id="local",
- kind=MemoryKind.CHAT,
- content=content,
- scopes=("all-apps",),
- evidence_ids=(evidence_id,),
- ),
- request_id=f"common-{index}",
- )
-
- monkeypatch.setattr("one_memory.memory_governance._MAX_CANDIDATE_TERM_DOCS", 1)
- found, more = store.find_confirmed_matching_terms(user_id="local", terms=("common",))
-
- assert len(found) == 2
- assert more is False
-
-
-def test_coverage_aware_candidate_plan_marks_a_truncated_union(tmp_path) -> None:
- database = tmp_path / "one-memory.sqlite3"
- first_evidence = evidence(database, message_id="plan-a", verbatim="甲")
- second_evidence = evidence(database, message_id="plan-b", verbatim="乙")
- store = MemoryGovernanceStore(database)
- door = as_person(store)
- for index, evidence_id in enumerate((first_evidence, second_evidence)):
- door.create(
- MemoryDraft(
- user_id="local",
- kind=MemoryKind.CHAT,
- content=f"unique plan term {index}",
- scopes=("all-apps",),
- evidence_ids=(evidence_id,),
- ),
- request_id=f"plan-{index}",
- )
- with store._connection() as connection:
- truncated = content_candidate_plan(connection, ("unique",), alias="m", limit=1)
- complete = content_candidate_plan(connection, ("unique",), alias="m", limit=2)
- legacy = content_candidate_predicate(connection, ("unique",), alias="m")
-
- assert truncated is not None and truncated.complete is False
- assert truncated.candidate_count == 2
- assert complete is not None and complete.complete is True
- assert len(legacy) == 2
-
-
-def test_plan_is_incomplete_when_one_or_term_is_filtered(tmp_path, monkeypatch) -> None:
- database = tmp_path / "one-memory.sqlite3"
- first_evidence = evidence(database, message_id="mix-a", verbatim="甲")
- second_evidence = evidence(database, message_id="mix-b", verbatim="乙")
- third_evidence = evidence(database, message_id="mix-c", verbatim="丙")
- store = MemoryGovernanceStore(database)
- door = as_person(store)
- memories = []
- for index, (evidence_id, content) in enumerate(
- (
- (first_evidence, "common alpha"),
- (second_evidence, "common beta"),
- (third_evidence, "rare gamma"),
- )
- ):
- memories.append(
- door.create(
- MemoryDraft(
- user_id="local",
- kind=MemoryKind.CHAT,
- content=content,
- scopes=("all-apps",),
- evidence_ids=(evidence_id,),
- ),
- request_id=f"mix-{index}",
- )
- )
-
- monkeypatch.setattr("one_memory.memory_governance._MAX_CANDIDATE_TERM_DOCS", 1)
- with store._connection() as connection:
- plan = content_candidate_plan(connection, ("common", "rare"), alias="m", limit=200)
-
- assert plan is not None
- assert plan.complete is False
- found, _ = store.find_confirmed_matching_terms(user_id="local", terms=("common", "rare"))
- assert {memory.memory_id for memory in found} == {memory.memory_id for memory in memories}
-
-
-def test_opening_a_legacy_library_does_not_backfill_the_candidate_shadow(tmp_path) -> None:
- database = tmp_path / "one-memory.sqlite3"
- evidence_id = evidence(database, message_id="legacy-shadow", verbatim="原文")
- store = MemoryGovernanceStore(database)
- as_person(store).create(
- MemoryDraft(
- user_id="local",
- kind=MemoryKind.CHAT,
- content="独特记忆目标短语",
- scopes=("all-apps",),
- evidence_ids=(evidence_id,),
- ),
- request_id="legacy-shadow",
- )
- with sqlite3.connect(database) as connection, connection:
- connection.execute("DELETE FROM governed_memories_terms")
-
- reopened = MemoryGovernanceStore(database)
- with sqlite3.connect(database) as connection:
- assert connection.execute("SELECT count(*) FROM governed_memories_terms").fetchone()[0] == 0
- assert connection.execute(
- "SELECT 1 FROM sqlite_master WHERE type='table' AND name='governed_memories_terms_meta'"
- ).fetchone()
- assert (
- connection.execute("SELECT count(*) FROM governed_memories_terms_meta").fetchone()[0]
- == 1
- )
- found, _ = reopened.find_confirmed_matching_terms(
- user_id="local", terms=("独特", "特记", "记忆")
- )
- assert [memory.content for memory in found] == ["独特记忆目标短语"]
-
- with reopened._connection() as connection:
- ensure_content_candidate_index(connection)
- assert connection.execute("SELECT count(*) FROM governed_memories_terms").fetchone()[0] > 0
- assert (
- connection.execute("SELECT count(*) FROM governed_memories_terms_meta").fetchone()[0]
- == 1
- )
-
-
-def test_content_candidate_backfill_runs_off_the_startup_path(tmp_path) -> None:
- import time
-
- database = tmp_path / "one-memory.sqlite3"
- evidence_id = evidence(database, message_id="background-shadow", verbatim="原文")
- store = MemoryGovernanceStore(database)
- as_person(store).create(
- MemoryDraft(
- user_id="local",
- kind=MemoryKind.CHAT,
- content="独特记忆目标短语",
- scopes=("all-apps",),
- evidence_ids=(evidence_id,),
- ),
- request_id="background-shadow",
- )
- with sqlite3.connect(database) as connection, connection:
- connection.execute("DELETE FROM governed_memories_terms")
-
- assert store.start_content_candidate_backfill() is True
- assert store.start_content_candidate_backfill() is False
- deadline = time.monotonic() + 5
- while store.content_candidate_backfill_state() == "running" and time.monotonic() < deadline:
- time.sleep(0.01)
- assert store.content_candidate_backfill_state() == "ready"
- assert store.content_candidate_backfill_failure() is None
- assert store.wait_content_candidate_backfill(timeout=0) is True
-
-
-def test_content_candidate_backfill_waits_for_startup_writes_to_finish(
- tmp_path, monkeypatch
-) -> None:
- """A long rebuild must not hold the write checkout while startup still needs it."""
- database = tmp_path / "one-memory.sqlite3"
- EvidenceStore(database)
- store = MemoryGovernanceStore(database)
- entered = threading.Event()
- release = threading.Event()
-
- def hold_then_finish(_self) -> None:
- entered.set()
- release.wait(10)
-
- monkeypatch.setattr(MemoryGovernanceStore, "_rebuild_content_shadow_batched", hold_then_finish)
- assert store.start_content_candidate_backfill(hold_until_startup_release=True) is True
- assert entered.wait(2) is False, "backfill acquired the writer before startup released it"
- store.release_content_backfill_startup_gate()
- assert entered.wait(2) is True
- release.set()
- assert store.wait_content_candidate_backfill(timeout=2) is True
-
-
-def test_content_candidate_backfill_failure_is_observable_and_non_blocking(
- tmp_path, monkeypatch
-) -> None:
- import time
-
- database = tmp_path / "one-memory.sqlite3"
- evidence_id = evidence(database, message_id="background-failure", verbatim="原文")
- store = MemoryGovernanceStore(database)
- as_person(store).create(
- MemoryDraft(
- user_id="local",
- kind=MemoryKind.CHAT,
- content="独特记忆目标短语",
- scopes=("all-apps",),
- evidence_ids=(evidence_id,),
- ),
- request_id="background-failure",
- )
- with sqlite3.connect(database) as connection, connection:
- connection.execute("DELETE FROM governed_memories_terms")
-
- def fail_locked(_self) -> None:
- raise sqlite3.OperationalError("database is locked")
-
- monkeypatch.setattr(
- "one_memory.memory_governance.MemoryGovernanceStore._rebuild_content_shadow_batched",
- fail_locked,
- )
- assert store.start_content_candidate_backfill() is True
- deadline = time.monotonic() + 5
- while store.content_candidate_backfill_state() == "running" and time.monotonic() < deadline:
- time.sleep(0.01)
-
- assert store.content_candidate_backfill_state() == "failed"
- assert store.content_candidate_backfill_failure() == "database_locked"
- assert store.wait_content_candidate_backfill(timeout=0) is True
- found, _ = store.find_confirmed_matching_terms(user_id="local", terms=("独特", "记忆"))
- assert [memory.content for memory in found] == ["独特记忆目标短语"]
-
-
-def test_content_candidate_backfill_rejects_a_negative_timeout(tmp_path) -> None:
- store = MemoryGovernanceStore(tmp_path / "one-memory.sqlite3")
- with pytest.raises(ValueError, match="invalid_content_backfill_timeout"):
- store.wait_content_candidate_backfill(timeout=-0.1)
-
-
-def test_content_candidate_backfill_rebuilds_stale_terms_not_only_empty_memories(
- tmp_path,
-) -> None:
- import time
-
- database = tmp_path / "one-memory.sqlite3"
- first_evidence = evidence(database, message_id="stale-shadow-a", verbatim="原文")
- second_evidence = evidence(database, message_id="stale-shadow-b", verbatim="原文")
- store = MemoryGovernanceStore(database)
- door = as_person(store)
- stale = door.create(
- MemoryDraft(
- user_id="local",
- kind=MemoryKind.CHAT,
- content="旧版本短语",
- scopes=("all-apps",),
- evidence_ids=(first_evidence,),
- ),
- request_id="stale-shadow",
- )
- door.create(
- MemoryDraft(
- user_id="local",
- kind=MemoryKind.CHAT,
- content="新鲜目标短语",
- scopes=("all-apps",),
- evidence_ids=(second_evidence,),
- ),
- request_id="fresh-shadow",
- )
- # Simulate a crash between the ledger update and its derived-row update:
- # one old term survives and makes the memory look already backfilled.
- with sqlite3.connect(database) as connection, connection:
- connection.execute(
- "UPDATE governed_memories SET content=?, updated_at=? WHERE memory_id=?",
- ("全新目标短语", "2099-01-01T00:00:00+00:00", stale.memory_id),
- )
- connection.execute(
- "UPDATE governed_memories_terms_meta SET content_hash=? WHERE memory_id=?",
- ("stale-hash", stale.memory_id),
- )
- connection.execute(
- "DELETE FROM governed_memories_terms WHERE memory_id=? AND term!=?",
- (stale.memory_id, "旧版"),
- )
-
- assert store.start_content_candidate_backfill() is True
- deadline = time.monotonic() + 5
- while store.content_candidate_backfill_state() == "running" and time.monotonic() < deadline:
- time.sleep(0.01)
- assert store.content_candidate_backfill_state() == "ready"
- with sqlite3.connect(database) as connection:
- terms = {
- row[0]
- for row in connection.execute(
- "SELECT term FROM governed_memories_terms WHERE memory_id=?",
- (stale.memory_id,),
- )
- }
- assert "全新" in terms and "目标" in terms
- assert not {"旧版", "版短"} & terms
- found, _ = store.find_confirmed_matching_terms(user_id="local", terms=("全新", "目标"))
- assert stale.memory_id in {memory.memory_id for memory in found}
-
-
-def test_content_candidate_backfill_is_idempotent_after_content_hash_exists(tmp_path) -> None:
- import time
-
- database = tmp_path / "one-memory.sqlite3"
- evidence_id = evidence(database, message_id="idempotent-shadow", verbatim="原文")
- store = MemoryGovernanceStore(database)
- as_person(store).create(
- MemoryDraft(
- user_id="local",
- kind=MemoryKind.CHAT,
- content="独特记忆目标短语",
- scopes=("all-apps",),
- evidence_ids=(evidence_id,),
- ),
- request_id="idempotent-shadow",
- )
- with sqlite3.connect(database) as connection, connection:
- connection.execute("DELETE FROM governed_memories_terms")
- connection.execute("DELETE FROM governed_memories_terms_meta")
-
- def wait_ready() -> None:
- deadline = time.monotonic() + 5
- while store.content_candidate_backfill_state() == "running" and time.monotonic() < deadline:
- time.sleep(0.01)
- assert store.content_candidate_backfill_state() == "ready"
-
- assert store.start_content_candidate_backfill() is True
- wait_ready()
- with sqlite3.connect(database) as connection:
- first = set(
- connection.execute("SELECT term,memory_id FROM governed_memories_terms").fetchall()
- )
- assert store.start_content_candidate_backfill() is False
- with sqlite3.connect(database) as connection:
- before = connection.total_changes
- ensure_content_candidate_index(connection)
- assert connection.total_changes == before
- second = set(
- connection.execute("SELECT term,memory_id FROM governed_memories_terms").fetchall()
- )
- assert second == first
-
-
-def test_content_candidate_backfill_commits_between_batches_and_releases_writer(
- tmp_path, monkeypatch
-) -> None:
- """Each batch acquires and returns the writer instead of holding one transaction."""
- import one_memory.memory_governance as governance
-
- database = tmp_path / "one-memory.sqlite3"
- store = MemoryGovernanceStore(database)
- door = as_person(store)
- for index in range(6):
- evidence_id = evidence(database, message_id=f"batch-{index}", verbatim="原文")
- door.create(
- MemoryDraft(
- user_id="local",
- kind=MemoryKind.CHAT,
- content=f"批量目标短语 {index}",
- scopes=("all-apps",),
- evidence_ids=(evidence_id,),
- ),
- request_id=f"batch-{index}",
- )
- with sqlite3.connect(database) as connection, connection:
- connection.execute("DELETE FROM governed_memories_terms")
- connection.execute("DELETE FROM governed_memories_terms_meta")
-
- monkeypatch.setattr(governance, "_CONTENT_BACKFILL_BATCH_ROWS", 2, raising=False)
- connections: list[int] = []
- original = governance.MemoryGovernanceStore._connection
-
- from contextlib import contextmanager
-
- @contextmanager
- def observed(self, *, writing=True, keep_journal_mode=False):
- with original(self, writing=writing, keep_journal_mode=keep_journal_mode) as connection:
- connections.append(id(connection))
- yield connection
-
- monkeypatch.setattr(governance.MemoryGovernanceStore, "_connection", observed)
- assert store.start_content_candidate_backfill() is True
- assert store.wait_content_candidate_backfill(timeout=10) is True
- assert store.content_candidate_backfill_state() == "ready"
- # Six rows at two rows per batch means at least three separate writer
- # checkouts; a single long transaction would show one connection.
- assert len(connections) >= 3
- with sqlite3.connect(database) as connection:
- assert (
- connection.execute("SELECT count(*) FROM governed_memories_terms_meta").fetchone()[0]
- == 6
- )
-
-
-def test_content_candidate_backfill_resumes_after_partial_batch(tmp_path, monkeypatch) -> None:
- """A crash between batches leaves already-derived rows and resumes the rest."""
- import one_memory.memory_governance as governance
-
- database = tmp_path / "one-memory.sqlite3"
- store = MemoryGovernanceStore(database)
- door = as_person(store)
- for index in range(5):
- evidence_id = evidence(database, message_id=f"resume-{index}", verbatim="原文")
- door.create(
- MemoryDraft(
- user_id="local",
- kind=MemoryKind.CHAT,
- content=f"恢复目标短语 {index}",
- scopes=("all-apps",),
- evidence_ids=(evidence_id,),
- ),
- request_id=f"resume-{index}",
- )
- with sqlite3.connect(database) as connection, connection:
- connection.execute("DELETE FROM governed_memories_terms")
- connection.execute("DELETE FROM governed_memories_terms_meta")
-
- monkeypatch.setattr(governance, "_CONTENT_BACKFILL_BATCH_ROWS", 2, raising=False)
- calls = {"count": 0}
- original_upsert = governance.MemoryGovernanceStore._content_shadow_upsert
-
- def crash_after_three(connection, memory_id, content):
- calls["count"] += 1
- if calls["count"] > 3:
- raise RuntimeError("simulated crash between batches")
- return original_upsert(connection, memory_id, content)
-
- monkeypatch.setattr(
- governance.MemoryGovernanceStore, "_content_shadow_upsert", staticmethod(crash_after_three)
- )
- assert store.start_content_candidate_backfill() is True
- assert store.wait_content_candidate_backfill(timeout=10) is True
- assert store.content_candidate_backfill_state() == "failed"
-
- monkeypatch.setattr(
- governance.MemoryGovernanceStore, "_content_shadow_upsert", staticmethod(original_upsert)
- )
- resumed = MemoryGovernanceStore(database)
- assert resumed.start_content_candidate_backfill() is True
- assert resumed.wait_content_candidate_backfill(timeout=10) is True
- assert resumed.content_candidate_backfill_state() == "ready"
- with sqlite3.connect(database) as connection:
- assert (
- connection.execute("SELECT count(*) FROM governed_memories_terms_meta").fetchone()[0]
- == 5
- )
- found, _ = resumed.find_confirmed_matching_terms(user_id="local", terms=("恢复目标",))
- assert len(found) == 5
-
-
-def test_content_candidate_backfill_handles_a_single_oversized_memory(
- tmp_path, monkeypatch
-) -> None:
- """A record bigger than the char budget is processed alone, never split."""
- import one_memory.memory_governance as governance
-
- database = tmp_path / "one-memory.sqlite3"
- store = MemoryGovernanceStore(database)
- evidence_id = evidence(database, message_id="huge", verbatim="原文")
- huge = "巨大目标短语" + ("内容" * 400_000)
- as_person(store).create(
- MemoryDraft(
- user_id="local",
- kind=MemoryKind.CHAT,
- content=huge,
- scopes=("all-apps",),
- evidence_ids=(evidence_id,),
- ),
- request_id="huge",
- )
- with sqlite3.connect(database) as connection, connection:
- connection.execute("DELETE FROM governed_memories_terms")
- connection.execute("DELETE FROM governed_memories_terms_meta")
- monkeypatch.setattr(governance, "_CONTENT_BACKFILL_BATCH_CHARS", 10, raising=False)
- assert store.start_content_candidate_backfill() is True
- assert store.wait_content_candidate_backfill(timeout=30) is True
- assert store.content_candidate_backfill_state() == "ready"
- with sqlite3.connect(database) as connection:
- assert (
- connection.execute("SELECT count(*) FROM governed_memories_terms_meta").fetchone()[0]
- == 1
- )
- assert connection.execute("SELECT count(*) FROM governed_memories_terms").fetchone()[0] > 0
-
-
-def test_content_candidate_backfill_pauses_between_batches_and_lets_a_writer_in(
- tmp_path, monkeypatch
-) -> None:
- """The writer is free in the gap after a committed batch, not only at the end."""
- import time
-
- import one_memory.memory_governance as governance
- from one_memory.database_access import main_database
-
- database = tmp_path / "one-memory.sqlite3"
- store = MemoryGovernanceStore(database)
- door = as_person(store)
- for index in range(4):
- evidence_id = evidence(database, message_id=f"gap-{index}", verbatim="原文")
- door.create(
- MemoryDraft(
- user_id="local",
- kind=MemoryKind.CHAT,
- content=f"批间目标短语 {index}",
- scopes=("all-apps",),
- evidence_ids=(evidence_id,),
- ),
- request_id=f"gap-{index}",
- )
- with sqlite3.connect(database) as connection, connection:
- connection.execute("DELETE FROM governed_memories_terms")
- connection.execute("DELETE FROM governed_memories_terms_meta")
-
- from contextlib import contextmanager
-
- monkeypatch.setattr(governance, "_CONTENT_BACKFILL_BATCH_ROWS", 1, raising=False)
- batch_committed = threading.Event()
- release_second_batch = threading.Event()
- original_connection = governance.MemoryGovernanceStore._connection
- writes = {"count": 0}
-
- @contextmanager
- def pause_after_first_commit(self, *, writing=True, keep_journal_mode=False):
- with original_connection(
- self, writing=writing, keep_journal_mode=keep_journal_mode
- ) as connection:
- yield connection
- if writing:
- writes["count"] += 1
- if writes["count"] == 1:
- batch_committed.set()
- assert release_second_batch.wait(10)
-
- monkeypatch.setattr(
- governance.MemoryGovernanceStore,
- "_connection",
- pause_after_first_commit,
- )
- assert store.start_content_candidate_backfill() is True
- assert batch_committed.wait(5)
- # The first batch has committed; this write must not wait for the whole
- # rebuild even though the second batch is paused.
- started = time.monotonic()
- with main_database(database).write(busy_timeout_ms=250) as connection:
- connection.execute("BEGIN IMMEDIATE")
- connection.execute(
- "UPDATE governed_memories SET updated_at=? WHERE memory_id='gap-0'",
- ("2026-10-01T00:00:00+00:00",),
- )
- connection.execute("COMMIT")
- assert (time.monotonic() - started) < 0.2
- release_second_batch.set()
- assert store.wait_content_candidate_backfill(timeout=10) is True
- assert store.content_candidate_backfill_state() == "ready"
- with sqlite3.connect(database) as connection:
- assert (
- connection.execute("SELECT count(*) FROM governed_memories_terms_meta").fetchone()[0]
- == 4
- )
-
-
-def test_content_candidate_backfill_handles_cursor_front_and_back_mutations(
- tmp_path, monkeypatch
-) -> None:
- """Changes behind and ahead of the cursor end with the writer path authoritative."""
- import one_memory.memory_governance as governance
-
- database = tmp_path / "one-memory.sqlite3"
- store = MemoryGovernanceStore(database)
- door = as_person(store)
- created: dict[str, str] = {}
- for index in range(4):
- evidence_id = evidence(database, message_id=f"cursor-{index}", verbatim="原文")
- memory = door.create(
- MemoryDraft(
- user_id="local",
- kind=MemoryKind.CHAT,
- content=f"游标目标短语 {index}",
- scopes=("all-apps",),
- evidence_ids=(evidence_id,),
- ),
- request_id=f"cursor-{index}",
- memory_id=f"{index + 1:03d}",
- )
- created[f"cursor-{index}"] = memory.memory_id
- with sqlite3.connect(database) as connection, connection:
- connection.execute("DELETE FROM governed_memories_terms")
- connection.execute("DELETE FROM governed_memories_terms_meta")
-
- from contextlib import contextmanager
-
- monkeypatch.setattr(governance, "_CONTENT_BACKFILL_BATCH_ROWS", 1, raising=False)
- first_batch_committed = threading.Event()
- release = threading.Event()
- original_connection = governance.MemoryGovernanceStore._connection
- writes = {"count": 0}
-
- @contextmanager
- def pause_after_first_commit(self, *, writing=True, keep_journal_mode=False):
- with original_connection(
- self, writing=writing, keep_journal_mode=keep_journal_mode
- ) as connection:
- yield connection
- if writing:
- writes["count"] += 1
- if writes["count"] == 1:
- first_batch_committed.set()
- assert release.wait(10)
-
- monkeypatch.setattr(
- governance.MemoryGovernanceStore,
- "_connection",
- pause_after_first_commit,
- )
- assert store.start_content_candidate_backfill() is True
- assert first_batch_committed.wait(5)
-
- # Behind the cursor: correct one already-scanned row.
- door.correct(
- created["cursor-0"],
- user_id="local",
- request_id="cursor-correct-behind",
- expected_revision=1,
- content="游标目标已更正 0",
- )
- # Ahead of the cursor: create and delete rows the sweep has not reached.
- extra_evidence = evidence(database, message_id="cursor-extra", verbatim="原文")
- extra = door.create(
- MemoryDraft(
- user_id="local",
- kind=MemoryKind.CHAT,
- content="游标新增短语",
- scopes=("all-apps",),
- evidence_ids=(extra_evidence,),
- ),
- request_id="cursor-extra",
- )
- delete_evidence = evidence(database, message_id="cursor-delete", verbatim="原文")
- deleted = door.create(
- MemoryDraft(
- user_id="local",
- kind=MemoryKind.CHAT,
- content="游标待删除短语",
- scopes=("all-apps",),
- evidence_ids=(delete_evidence,),
- ),
- request_id="cursor-delete",
- )
- door.delete(
- deleted.memory_id,
- user_id="local",
- request_id="cursor-delete-action",
- expected_revision=1,
- )
- release.set()
- assert store.wait_content_candidate_backfill(timeout=10) is True
- assert store.content_candidate_backfill_state() == "ready"
-
- found, _ = store.find_confirmed_matching_terms(user_id="local", terms=("游标目标", "游标新增"))
- ids = {memory.memory_id for memory in found}
- assert created["cursor-0"] in ids
- assert extra.memory_id in ids
- assert deleted.memory_id not in ids
- with sqlite3.connect(database) as connection:
- assert (
- connection.execute(
- "SELECT 1 FROM governed_memories_terms WHERE memory_id=?", (deleted.memory_id,)
- ).fetchone()
- is None
- )
-
-
-def test_content_candidate_backfill_repeat_is_a_no_op_after_ready(tmp_path) -> None:
- """A second scheduled run does not rewrite derived rows or change counts."""
- import time
-
- database = tmp_path / "one-memory.sqlite3"
- store = MemoryGovernanceStore(database)
- door = as_person(store)
- for index in range(3):
- evidence_id = evidence(database, message_id=f"repeat-{index}", verbatim="原文")
- door.create(
- MemoryDraft(
- user_id="local",
- kind=MemoryKind.CHAT,
- content=f"重复目标短语 {index}",
- scopes=("all-apps",),
- evidence_ids=(evidence_id,),
- ),
- request_id=f"repeat-{index}",
- )
- with sqlite3.connect(database) as connection, connection:
- connection.execute("DELETE FROM governed_memories_terms")
- connection.execute("DELETE FROM governed_memories_terms_meta")
- assert store.start_content_candidate_backfill() is True
- deadline = time.monotonic() + 10
- while store.content_candidate_backfill_state() == "running" and time.monotonic() < deadline:
- time.sleep(0.01)
- assert store.content_candidate_backfill_state() == "ready"
- with sqlite3.connect(database) as connection:
- before = connection.execute(
- "SELECT term,memory_id FROM governed_memories_terms ORDER BY term,memory_id"
- ).fetchall()
- assert store.start_content_candidate_backfill() is False
- with sqlite3.connect(database) as connection:
- after = connection.execute(
- "SELECT term,memory_id FROM governed_memories_terms ORDER BY term,memory_id"
- ).fetchall()
- assert after == before
-
-
-def test_content_candidate_backfill_meta_hash_is_the_derivation_rule(tmp_path) -> None:
- """A stale hash re-derives its row; a matching hash is left untouched."""
- import time
-
- import one_memory.memory_governance as governance
-
- database = tmp_path / "one-memory.sqlite3"
- store = MemoryGovernanceStore(database)
- evidence_id = evidence(database, message_id="hash-rule", verbatim="原文")
- memory = as_person(store).create(
- MemoryDraft(
- user_id="local",
- kind=MemoryKind.CHAT,
- content="hash 派生目标短语",
- scopes=("all-apps",),
- evidence_ids=(evidence_id,),
- ),
- request_id="hash-rule",
- )
- expected_terms = governance._shadow_terms("hash 派生目标短语")
- expected_hash = governance._shadow_content_hash("hash 派生目标短语")
- with sqlite3.connect(database) as connection, connection:
- assert (
- connection.execute(
- "SELECT content_hash FROM governed_memories_terms_meta WHERE memory_id=?",
- (memory.memory_id,),
- ).fetchone()[0]
- == expected_hash
- )
- actual = {
- row[0]
- for row in connection.execute(
- "SELECT term FROM governed_memories_terms WHERE memory_id=?",
- (memory.memory_id,),
- )
- }
- assert actual == expected_terms
- # Simulate an old hash and an extra stale term; the sweep must rebuild
- # from content, not trust a surviving term row.
- connection.execute(
- "UPDATE governed_memories_terms_meta SET content_hash='stale' WHERE memory_id=?",
- (memory.memory_id,),
- )
- connection.execute(
- "INSERT INTO governed_memories_terms(term,memory_id) VALUES ('旧派',?)",
- (memory.memory_id,),
- )
- assert store.start_content_candidate_backfill() is True
- deadline = time.monotonic() + 10
- while store.content_candidate_backfill_state() == "running" and time.monotonic() < deadline:
- time.sleep(0.01)
- assert store.content_candidate_backfill_state() == "ready"
- with sqlite3.connect(database) as connection:
- assert (
- connection.execute(
- "SELECT content_hash FROM governed_memories_terms_meta WHERE memory_id=?",
- (memory.memory_id,),
- ).fetchone()[0]
- == expected_hash
- )
- actual = {
- row[0]
- for row in connection.execute(
- "SELECT term FROM governed_memories_terms WHERE memory_id=?",
- (memory.memory_id,),
- )
- }
- assert actual == expected_terms
-
-
-def test_content_candidate_backfill_does_not_revive_a_concurrently_deleted_memory(
- tmp_path, monkeypatch
-) -> None:
- """A delete committed between batches cannot be undone by the sweep cursor."""
- import one_memory.memory_governance as governance
-
- database = tmp_path / "one-memory.sqlite3"
- store = MemoryGovernanceStore(database)
- door = as_person(store)
- created: list[str] = []
- for index in range(4):
- evidence_id = evidence(database, message_id=f"delete-race-{index}", verbatim="原文")
- memory = door.create(
- MemoryDraft(
- user_id="local",
- kind=MemoryKind.CHAT,
- content=f"删除竞态目标短语 {index}",
- scopes=("all-apps",),
- evidence_ids=(evidence_id,),
- ),
- request_id=f"delete-race-{index}",
- memory_id=f"{index + 1:03d}",
- )
- created.append(memory.memory_id)
- with sqlite3.connect(database) as connection, connection:
- connection.execute("DELETE FROM governed_memories_terms")
- connection.execute("DELETE FROM governed_memories_terms_meta")
-
- from contextlib import contextmanager
-
- monkeypatch.setattr(governance, "_CONTENT_BACKFILL_BATCH_ROWS", 1, raising=False)
- first_batch_committed = threading.Event()
- release = threading.Event()
- original_connection = governance.MemoryGovernanceStore._connection
- writes = {"count": 0}
-
- @contextmanager
- def pause_after_first_commit(self, *, writing=True, keep_journal_mode=False):
- with original_connection(
- self, writing=writing, keep_journal_mode=keep_journal_mode
- ) as connection:
- yield connection
- if writing:
- writes["count"] += 1
- if writes["count"] == 1:
- first_batch_committed.set()
- assert release.wait(10)
-
- monkeypatch.setattr(governance.MemoryGovernanceStore, "_connection", pause_after_first_commit)
- assert store.start_content_candidate_backfill() is True
- assert first_batch_committed.wait(5)
- # Delete a row ahead of the cursor while the sweep is paused.
- door.delete(
- created[3],
- user_id="local",
- request_id="delete-race-action",
- expected_revision=1,
- )
- release.set()
- assert store.wait_content_candidate_backfill(timeout=10) is True
- assert store.content_candidate_backfill_state() == "ready"
- found, _ = store.find_confirmed_matching_terms(user_id="local", terms=("删除竞态",))
- assert created[3] not in {memory.memory_id for memory in found}
- with sqlite3.connect(database) as connection:
- assert (
- connection.execute(
- "SELECT 1 FROM governed_memories_terms WHERE memory_id=?", (created[3],)
- ).fetchone()
- is None
- )
- assert (
- connection.execute(
- "SELECT 1 FROM governed_memories_terms_meta WHERE memory_id=?", (created[3],)
- ).fetchone()
- is None
- )
-
-
-def test_a_partial_candidate_shadow_falls_back_to_like_instead_of_dropping_matches(
- tmp_path,
-) -> None:
- """A partially indexed shadow must not answer as if it were complete.
-
- The candidate shadow lets recall skip a full `content LIKE` scan, but only
- when it covers every current memory. A freshly opened existing library, or
- one whose background backfill is still running, can be missing whole
- memories from the shadow. Per-term counts cannot see that loss, so a
- bounded candidate query would return a smaller set while still reporting
- `complete`. The read path must fall back to the exact `LIKE` answer.
- """
- database = tmp_path / "one-memory.sqlite3"
- first = evidence(database, message_id="partial-a", verbatim="shared target phrase alpha")
- second = evidence(database, message_id="partial-b", verbatim="shared target phrase beta")
- store = MemoryGovernanceStore(database)
- door = as_person(store)
- memories = [
- door.create(
- MemoryDraft(
- user_id="local",
- kind=MemoryKind.CHAT,
- content=f"shared target phrase {suffix}",
- scopes=("all-apps",),
- evidence_ids=(evidence_id,),
- ),
- request_id=f"partial-{suffix}",
- )
- for evidence_id, suffix in ((first, "alpha"), (second, "beta"))
- ]
-
- expected = {memory.memory_id for memory in memories}
- complete, _ = store.find_confirmed_matching_terms(
- user_id="local", terms=("shared",), scopes=("all-apps",)
- )
- assert {memory.memory_id for memory in complete} == expected
-
- # Model a crash/partial backfill: one memory has neither shadow terms nor a
- # meta row, the exact state the batched rebuild leaves between commits.
- with store._connection() as connection:
- connection.execute("BEGIN IMMEDIATE")
- victim = memories[0].memory_id
- connection.execute("DELETE FROM governed_memories_terms WHERE memory_id=?", (victim,))
- connection.execute("DELETE FROM governed_memories_terms_meta WHERE memory_id=?", (victim,))
-
- reopened = MemoryGovernanceStore(database)
- found, more = reopened.find_confirmed_matching_terms(
- user_id="local", terms=("shared",), scopes=("all-apps",)
- )
- assert {memory.memory_id for memory in found} == expected
- assert more is False
-
- # The plan API must report the same truthfulness, not a "complete" claim.
- with reopened._connection() as connection:
- plan = content_candidate_plan(connection, ("shared",))
- assert plan is None
-
- # An explicit rebuild restores the shadow fast path without losing rows.
- with reopened._connection() as connection:
- connection.execute("BEGIN IMMEDIATE")
- ensure_content_candidate_index(connection)
- rebuilt, _ = reopened.find_confirmed_matching_terms(
- user_id="local", terms=("shared",), scopes=("all-apps",)
- )
- assert {memory.memory_id for memory in rebuilt} == expected
-
-
-def test_another_workspace_cannot_spend_the_shadow_candidate_budget(tmp_path) -> None:
- """Scope narrowing must reach inside the shadow subquery, not filter after it.
-
- The shadow fast path returns `memory_id IN (SELECT ... LIMIT N)`. If the
- scope predicate is applied outside that subquery, a crowded workspace fills
- all N candidate slots first and a readable match from another workspace is
- dropped — reported as an honest-looking empty result with `more=False`.
- """
- database = tmp_path / "one-memory.sqlite3"
- store = MemoryGovernanceStore(database)
- door = as_person(store)
- limit = 200
-
- # A crowded workspace whose ids sort first.
- for index in range(limit):
- door.create(
- MemoryDraft(
- user_id="local",
- kind=MemoryKind.CHAT,
- content=f"shared target phrase b{index}",
- scopes=("project:b",),
- evidence_ids=(evidence(database, message_id=f"crowd-{index}", verbatim="原文"),),
- ),
- request_id=f"crowd-{index}",
- memory_id=f"aaa-{index:04d}",
- )
- readable = door.create(
- MemoryDraft(
- user_id="local",
- kind=MemoryKind.CHAT,
- content="shared target phrase readable",
- scopes=("project:a",),
- evidence_ids=(evidence(database, message_id="crowd-readable", verbatim="原文"),),
- ),
- request_id="crowd-readable",
- memory_id="zzz-readable",
- )
-
- found, more = store.find_confirmed_matching_terms(
- user_id="local", terms=("shared",), limit=limit, scopes=("project:a",)
- )
- assert {memory.memory_id for memory in found} == {readable.memory_id}
- assert more is False
-
-
-def test_shadow_path_reports_truncation_like_the_like_fallback(tmp_path) -> None:
- """A capped candidate pool must say "more remain", not silently drop them.
-
- The shadow subquery used to be capped at exactly `limit`, so the outer
- `LIMIT limit + 1` could never see an extra row and `more` was always False
- on the fast path — recall then reported a truncated answer as complete.
- The LIKE fallback never had that bug; the two paths must agree.
- """
- database = tmp_path / "one-memory.sqlite3"
- store = MemoryGovernanceStore(database)
- door = as_person(store)
- total = 5
- for index in range(total):
- door.create(
- MemoryDraft(
- user_id="local",
- kind=MemoryKind.CHAT,
- content=f"shared target phrase {index}",
- scopes=("all-apps",),
- evidence_ids=(evidence(database, message_id=f"trunc-{index}", verbatim="原文"),),
- ),
- request_id=f"trunc-{index}",
- memory_id=f"m{index:04d}",
- )
-
- capped, capped_more = store.find_confirmed_matching_terms(
- user_id="local", terms=("shared",), limit=2
- )
- assert len(capped) == 2
- assert capped_more is True
-
- exact, exact_more = store.find_confirmed_matching_terms(
- user_id="local", terms=("shared",), limit=total
- )
- assert len(exact) == total
- assert exact_more is False
-
- roomy, roomy_more = store.find_confirmed_matching_terms(
- user_id="local", terms=("shared",), limit=total + 5
- )
- assert len(roomy) == total
- assert roomy_more is False
-
-
-def test_blocked_source_ids_tracks_the_person_deleting_their_own_evidence(tmp_path) -> None:
- """Deleting or correcting now must block the Evidence the memory rests on.
-
- Pins both branches of `_overridden_evidence` and its `memory.user_id=?`
- predicate. Drop the delete branch and a deleted memory keeps feeding HY;
- drop the correct branch and a corrected memory's evidence is ignored; drop
- the user predicate and another user's overrule blocks this user's write.
- """
- database = tmp_path / "one-memory.sqlite3"
- deleted_evidence = evidence(database, message_id="del-e", verbatim="delete me")
- corrected_evidence = evidence(database, message_id="cor-e", verbatim="correct me")
- other_evidence = evidence(
- database, message_id="other-e", verbatim="other person words", user_id="other"
- )
- store = MemoryGovernanceStore(database)
- person = as_person(store)
- deleted = person.create(
- MemoryDraft(
- user_id="local",
- kind=MemoryKind.CHAT,
- content="will be deleted",
- scopes=("all-apps",),
- evidence_ids=(deleted_evidence,),
- ),
- request_id="d-1",
- )
- corrected = person.create(
- MemoryDraft(
- user_id="local",
- kind=MemoryKind.CHAT,
- content="will be corrected",
- scopes=("all-apps",),
- evidence_ids=(corrected_evidence,),
- ),
- request_id="c-1",
- )
- other_memory = person.create(
- MemoryDraft(
- user_id="other",
- kind=MemoryKind.CHAT,
- content="other person's memory",
- scopes=("all-apps",),
- evidence_ids=(other_evidence,),
- ),
- request_id="o-1",
- )
- person.delete(
- deleted.memory_id,
- user_id="local",
- request_id="d-2",
- expected_revision=deleted.revision,
- )
- person.correct(
- corrected.memory_id,
- user_id="local",
- request_id="c-2",
- expected_revision=corrected.revision,
- content="corrected content",
- scopes=("all-apps",),
- )
- # Both of `local`'s own mutations block their evidence.
- assert store.blocked_source_ids(
- user_id="local", evidence_ids=(deleted_evidence, corrected_evidence)
- ) == {deleted_evidence, corrected_evidence}
- # The other user corrects their own memory, so its evidence IS overridden
- # for them. The `memory.user_id=?` predicate must keep it out of `local`'s
- # result, otherwise one user's correction would suppress another's write.
- person.correct(
- other_memory.memory_id,
- user_id="other",
- request_id="o-2",
- expected_revision=other_memory.revision,
- content="other corrected",
- scopes=("all-apps",),
- )
- assert store.blocked_source_ids(user_id="other", evidence_ids=(other_evidence,)) == {
- other_evidence
- }
- assert store.blocked_source_ids(user_id="local", evidence_ids=(other_evidence,)) == set()
diff --git a/memhub/apps/core/tests/test_memory_language.py b/memhub/apps/core/tests/test_memory_language.py
deleted file mode 100644
index 1b32dc5..0000000
--- a/memhub/apps/core/tests/test_memory_language.py
+++ /dev/null
@@ -1,256 +0,0 @@
-"""R-03: memory language follows the message, so Kristin's gets written in English.
-
-HY picks its extraction prompt from the content: `is_chinese(content)` in
-`hy_memory/agent/extractor.py:868`, which is a CJK character ratio with a 0.3
-threshold (`hy_memory/utils/lang_detect.py`). Kristin's everyday shape —
-paste an English traceback, ask about it in Chinese — measures 0.09, so the
-extractor is told to write in English and the memory comes out in English.
-
-Read from HY's source rather than assumed, and it contradicts the plan of
-record: `extract_system_prompt_zh` is only consulted *inside* the
-`is_chinese(...)` true branch (`extractor.py:891-901`), so setting it changes
-nothing for the case that is broken. The branch that actually runs reads
-`extract_system_prompt_en` (`extractor.py:922-930`).
-
-These tests drive HY's real `Extractor` with a stub LLM and look at the
-system prompt it actually sends, so they pin HY's behaviour rather than a
-copy of its logic.
-"""
-
-from __future__ import annotations
-
-import asyncio
-from dataclasses import dataclass, field
-from typing import Any
-
-import pytest
-from hy_memory.agent.extractor import Extractor
-from hy_memory.utils.lang_detect import _chinese_char_ratio, is_chinese
-
-from one_memory import hy_memory_bridge
-from one_memory.hy_memory_bridge import build_hy_memory_config
-from one_memory.model_profiles import ModelProfileSnapshot, ProviderKind
-
-#: A common shape: an English traceback pasted in, with
-#: the question asked in Chinese. Measured CJK ratio 0.09.
-CHINESE_QUESTION_WITH_ENGLISH_ERROR = """这个报错是什么意思,我该怎么修?
-Traceback (most recent call last):
- File "/Users/example/one-memory/apps/core/src/one_memory/recall.py", line 177, in _recall
- for memory in self.governance.list(user_id=user_id, status=MemoryStatus.CONFIRMED, limit=500):
- File "/Users/example/one-memory/apps/core/src/one_memory/memory_governance.py", line 388
- raise ValueError("invalid pagination")
-ValueError: invalid pagination
-"""
-
-
-@dataclass
-class StubResponse:
- content: str = '{"memories": [], "intentions": [], "basic_info": {}}'
- tokens_used: int = 0
- prompt_tokens: int = 0
- completion_tokens: int = 0
- tool_calls: Any = None
-
-
-@dataclass
-class RecordingLLM:
- """Stands in for the model, and keeps what it was told to do."""
-
- messages: list[list[dict[str, Any]]] = field(default_factory=list)
-
- async def complete_messages(self, *, messages, **_kwargs) -> StubResponse:
- self.messages.append(messages)
- return StubResponse()
-
- async def complete(self, **_kwargs) -> StubResponse:
- return StubResponse()
-
- def system_prompt(self) -> str:
- return next(item["content"] for item in self.messages[0] if item["role"] == "system")
-
- def user_prompt(self) -> str:
- return next(item["content"] for item in self.messages[0] if item["role"] == "user")
-
-
-def _profile() -> ModelProfileSnapshot:
- return ModelProfileSnapshot(
- profile_id="profile",
- revision=1,
- provider_kind=ProviderKind.OLLAMA,
- base_url="http://127.0.0.1:11434",
- model="memory-model",
- embedding_model="embedding-model",
- embedding_provider_kind=None,
- embedding_base_url=None,
- embedding_dimensions=768,
- timeout_seconds=30,
- max_concurrency=1,
- context_window=8192,
- has_api_key=False,
- )
-
-
-def _extract(content: str, tmp_path) -> RecordingLLM:
- config = build_hy_memory_config(_profile(), api_key=None, data_dir=tmp_path)
- llm = RecordingLLM()
- extractor = Extractor(llm_provider=llm, llm_config=config.llm)
- asyncio.run(extractor.extract(content=content))
- return llm
-
-
-def _reads_as_chinese(prompt: str) -> bool:
- return _chinese_char_ratio(prompt) > 0.2
-
-
-def _follows_the_input_language(prompt: str) -> bool:
- return (
- "输出语言必须与输入语言一致" in prompt
- or "Output language must match input language" in prompt
- )
-
-
-def test_hy_keeps_a_chinese_question_with_an_english_traceback_in_chinese(
- tmp_path,
-) -> None:
- """The premise, pinned to HY's own detector rather than described.
-
- Green before the fix and after: it is the control. R-03 must not be
- "made to pass" by pushing the detector over its threshold — the input is
- genuinely 9% CJK, and it is the memory language that has to stop
- depending on that.
- """
- assert _chinese_char_ratio(CHINESE_QUESTION_WITH_ENGLISH_ERROR) < 0.3
- assert is_chinese(CHINESE_QUESTION_WITH_ENGLISH_ERROR) is True
-
-
-def test_the_extractor_is_told_to_write_chinese_even_when_the_input_reads_as_english(
- tmp_path,
-) -> None:
- """The memory language is a property of the user, not of one message.
-
- Before the fix this sample takes HY's English branch and gets the English
- system prompt, so the memory is written in English — for a user whose
- every other memory is Chinese, and who never asked for either.
- """
- llm = _extract(CHINESE_QUESTION_WITH_ENGLISH_ERROR, tmp_path)
-
- assert _reads_as_chinese(llm.system_prompt()), (
- f"extractor was given an English system prompt: {llm.system_prompt()[:120]!r}"
- )
- assert not _follows_the_input_language(llm.system_prompt()), (
- "the prompt still hands the language decision back to the input"
- )
- assert "始终" in llm.system_prompt() and "中文" in llm.system_prompt()
-
-
[email protected]("ratio", [0.05, 0.3, 0.7])
-def test_the_memory_language_does_not_depend_on_the_cjk_ratio(ratio: float, tmp_path) -> None:
- """Three samples either side of the 0.3 threshold, all Chinese memories.
-
- 0.3 is the extraction threshold and 0.7 is System 2's, so a sample at
- each says whether the outcome still moves with the ratio.
- """
- chinese_length = max(1, round(40 * ratio))
- content = "我" * chinese_length + "x" * (40 - chinese_length)
- llm = _extract(content, tmp_path)
-
- assert _reads_as_chinese(llm.system_prompt()), (
- f"CJK ratio {ratio} produced an English system prompt"
- )
- assert not _follows_the_input_language(llm.system_prompt()), (
- f"CJK ratio {ratio} left the language up to the input"
- )
-
-
-def test_the_input_reaches_hy_untouched(tmp_path) -> None:
- """No Chinese prefix glued onto the content to fool the detector.
-
- That shortcut would work and is forbidden: the content HY extracts from
- is the person's own words, and padding it pollutes the verbatim the whole
- evidence chain rests on. Green before and after — a guard, not a repair.
- """
- llm = _extract(CHINESE_QUESTION_WITH_ENGLISH_ERROR, tmp_path)
-
- assert CHINESE_QUESTION_WITH_ENGLISH_ERROR in llm.user_prompt()
- assert "ValueError: invalid pagination" in llm.user_prompt()
-
-
-def test_hys_own_chinese_prompt_hands_the_language_back_to_the_input(tmp_path) -> None:
- """Why shipping HY's Chinese prompt as-is is not the fix.
-
- Both of HY's extraction system prompts carry one rule — "输出语言必须与输入
- 语言一致" / "Output language must match input language" — so a Chinese
- prompt over an English-reading input still asks for English. Serving HY's
- text verbatim would have made every assertion about the *prompt* pass
- while the memory came out in English anyway. Green before and after: it
- pins the SDK text this fix has to work around, and goes red the day HY
- drops that rule, which is the day the fix can shrink.
- """
- prompts_zh = pytest.importorskip("hy_memory.agent.prompts_zh")
- extractor_module = pytest.importorskip("hy_memory.agent.extractor")
-
- assert _follows_the_input_language(prompts_zh.EXTRACT_SYSTEM_PROMPT_ZH)
- assert _follows_the_input_language(extractor_module.EXTRACT_SYSTEM_PROMPT)
-
-
-def test_the_english_traceback_is_still_not_to_be_translated(tmp_path) -> None:
- """Fixing the language must not start rewriting what was pasted in.
-
- HY's other two language rules keep terms, brands, formulas and code
- exactly as written. Pinning the memory language to Chinese must leave
- those standing, or a traceback becomes a translated traceback and stops
- matching anything.
- """
- llm = _extract(CHINESE_QUESTION_WITH_ENGLISH_ERROR, tmp_path)
-
- assert "保留原始术语、品牌名、公式、代码" in llm.system_prompt()
- assert "不要转写或翻译专有名词" in llm.system_prompt()
-
-
-def test_a_reworded_sdk_prompt_still_gets_a_chinese_instruction(
- tmp_path, monkeypatch, caplog
-) -> None:
- """The fix edits one line of HY's prompt, so it has to survive a reword.
-
- If a future SDK changes that line's wording the replacement silently
- stops matching, and silently going back to "follow the input" is the
- failure mode worth spending a branch on: the override is appended
- instead, and it says so in the log.
- """
-
- from hy_memory.agent.prompts_zh import EXTRACT_SYSTEM_PROMPT_ZH as native_prompt
-
- class RewordedPrompts:
- EXTRACT_SYSTEM_PROMPT_ZH = native_prompt.replace(
- "* 输出语言必须与输入语言一致", "* HY 换了语言规则的措辞"
- )
-
- real_import = hy_memory_bridge.import_module
- monkeypatch.setattr(
- hy_memory_bridge,
- "import_module",
- lambda name: RewordedPrompts if name == "hy_memory.agent.prompts_zh" else real_import(name),
- )
- config = build_hy_memory_config(_profile(), api_key=None, data_dir=tmp_path)
-
- assert "始终是简体中文" in config.llm.extract_system_prompt_en
- assert "hy_language_rule_not_found" in caplog.text
-
-
-def test_setting_the_chinese_override_controls_the_mixed_traceback_prompt(tmp_path) -> None:
- """Pins why R-03 is not the one-line config change it was planned as.
-
- `extract_system_prompt_zh` sits inside the `is_chinese(...)` true branch,
- so on the failing input it is never read. If a later HY version moves the
- override outside the branch this test goes red, which is the moment to
- simplify the fix rather than keep carrying it.
- """
- config = build_hy_memory_config(_profile(), api_key=None, data_dir=tmp_path)
- llm = RecordingLLM()
- config.llm.extract_system_prompt_en = None
- config.llm.extract_system_prompt_zh = "只用中文写记忆。"
- extractor = Extractor(llm_provider=llm, llm_config=config.llm)
-
- asyncio.run(extractor.extract(content=CHINESE_QUESTION_WITH_ENGLISH_ERROR))
-
- assert llm.system_prompt() == "只用中文写记忆。"
diff --git a/memhub/apps/core/tests/test_memory_notes.py b/memhub/apps/core/tests/test_memory_notes.py
index a4eac37..2909c9b 100644
--- a/memhub/apps/core/tests/test_memory_notes.py
+++ b/memhub/apps/core/tests/test_memory_notes.py
@@ -240,7 +240,7 @@ def test_sdk_memory_write_accepts_openai_messages_without_evidence_tables(tmp_pa
@pytest.mark.fresh_sdk
def test_sdk_user_profile_http_returns_native_assembled_profile(tmp_path):
class Bridge:
- async def get_user_profile(self, *, user_id: str):
+ def get_user_profile(self, *, user_id: str):
assert user_id == "local"
return {
"request_id": "profile-request",
@@ -253,13 +253,17 @@ def test_sdk_user_profile_http_returns_native_assembled_profile(tmp_path):
"elapsed_ms": 1.25,
}
+ class Handle:
+ async def client(self):
+ return Bridge()
+
async def close(self):
return None
async def scenario():
app = application(tmp_path)
async with app.router.lifespan_context(app), client_for(app) as client:
- app.state.sdk_library_bridge = Bridge()
+ app.state.sdk_client_handle = Handle()
response = await client.get("/api/v2/user-profile")
assert response.status_code == 200, response.text
assert response.json() == {
diff --git a/memhub/apps/core/tests/test_memory_processing.py b/memhub/apps/core/tests/test_memory_processing.py
deleted file mode 100644
index 2d8c16b..0000000
--- a/memhub/apps/core/tests/test_memory_processing.py
+++ /dev/null
@@ -1,5014 +0,0 @@
-import asyncio
-import json
-import logging
-import sqlite3
-import threading
-import time
-from datetime import UTC, datetime, timedelta
-
-import pytest
-
-from one_memory.diagnostic_log import configure_diagnostics, reset_diagnostics
-from one_memory.hy_memory_bridge import (
- HyGraphNode,
- HyGraphSnapshot,
- HyMemoryBridgeError,
- HyMemoryIngestResult,
- HyMemoryOutput,
-)
-from one_memory.imports.adapters import (
- ScanCursorTouch,
- ScannedEvidence,
- SourceCapabilities,
- SourceCursor,
- SourceDescriptor,
- StorageKind,
-)
-from one_memory.imports.grants import SourceGrantStore
-from one_memory.imports.jobs import ImportJobStore, ImportStatus
-from one_memory.imports.models import (
- EvidenceContentKind,
- EvidenceInput,
- EvidenceOrigin,
- OriginMetadata,
- WrittenBy,
-)
-from one_memory.imports.runner import ImportRunner, live_sync_arrival
-from one_memory.imports.sources.registry import RootCandidateKind
-from one_memory.imports.storage import EvidenceStore
-from one_memory.memory_governance import (
- MemoryDraft,
- MemoryGovernanceStore,
- MemoryKind,
- MemoryOrigin,
- MemoryStatus,
-)
-from one_memory.memory_processing import (
- UNIFIED_HY_AGENT_ID,
- MemoryProcessingSupervisor,
- MemoryTaskRunner,
- _conversation_chunks,
- _hy_agent_id,
- _is_hy_input_turn,
- _report_stale_known_reasons,
- _shared_source_lock,
- memory_task_timeout_seconds,
-)
-from one_memory.memory_queue import classify
-from one_memory.memory_server.config_state import ConfigStore
-from one_memory.memory_tasks import (
- NON_RETRYABLE_POST_WRITE_CODES,
- MemoryTaskKind,
- MemoryTaskStatus,
- MemoryTaskStore,
-)
-from one_memory.model_profiles import (
- ModelCapabilities,
- ModelProfileInput,
- ModelProfilePatch,
- ModelProfileStore,
- ProviderKind,
-)
-from one_memory.secrets import InMemorySecretStore
-from one_memory.service_levels import (
- ServiceLevel,
- ServiceLevelScheduler,
- ServiceResource,
- service_level_context,
-)
-from tests.person_door import as_person
-
-
[email protected](autouse=True)
-def _segment_at_the_legacy_window(monkeypatch):
- """These cases exercise segmenting a single over-ceiling message (D74).
-
- The ceiling is now 60,000 characters of what HY reads; pin it to the old
- 12,000 so the 12,001-character fixtures still cross it.
- """
- import one_memory.memory_processing as memory_processing
-
- monkeypatch.setattr(memory_processing, "_WHOLE_TURN_CHARACTERS", 12_000)
-
-
-def test_stale_known_reason_diagnostics_never_fail_dispatch(tmp_path, monkeypatch) -> None:
- monkeypatch.setenv("ONE_MEMORY_DIAGNOSTICS", "1")
- root = logging.getLogger()
- previous = root.level
- root.setLevel(logging.DEBUG)
- receipt = configure_diagnostics(tmp_path)
- try:
- _report_stale_known_reasons(
- "task-stale-context",
- {"revision_changed": 2, "not_confirmed": 1},
- )
- finally:
- reset_diagnostics()
- root.setLevel(previous)
-
- records = [json.loads(line) for line in receipt.path.read_text().splitlines()]
- assert [(row["details"]["reason"], row["details"]["count"]) for row in records] == [
- ("not_confirmed", 1),
- ("revision_changed", 2),
- ]
-
-
-class FakeBridge:
- def __init__(
- self,
- *,
- outputs: tuple[HyMemoryOutput, ...] | None = None,
- profile: tuple[HyMemoryOutput, ...] = (),
- graph_nodes: tuple[HyGraphNode, ...] = (),
- fail: bool = False,
- ) -> None:
- self.outputs = outputs
- # Empty by default, which is what HY reports until it has learnt
- # something about the person. Its own writes never mention the profile,
- # so a bridge that only answered `ingest` looked complete while the
- # entire layer was missing.
- self.profile = profile
- # System 2's own output lives in the graph, not in what a write
- # returns, which is why it never reached governance.
- self.graph_nodes = graph_nodes
- self.graph_reads: list[tuple[str, str]] = []
- self.fail = fail
- self.requests = []
- self.extracted_contents: list[tuple[str, ...]] = []
- self.profile_reads: list[tuple[str, str]] = []
- self.digest_calls: list[tuple[str, str]] = []
- self.stored_agent_ids: tuple[str, ...] = ()
- self.closed = False
- self.search_result_ids: tuple[str, ...] = ()
-
- async def ingest(self, request) -> HyMemoryIngestResult:
- self.requests.append(request)
- if self.fail:
- raise HyMemoryBridgeError("hy_memory_unavailable")
- return HyMemoryIngestResult(
- success=True,
- memories=self.outputs
- if self.outputs is not None
- else (
- HyMemoryOutput(
- memory_id="hy-memory-1",
- content="用户偏好本地优先的记忆处理。",
- layer="L0_BASIC_INFO",
- ),
- ),
- )
-
- async def ingest_extracted(self, request, contents) -> HyMemoryIngestResult:
- self.requests.append(request)
- self.extracted_contents.append(tuple(contents))
- if self.fail:
- raise HyMemoryBridgeError("hy_memory_unavailable")
- return HyMemoryIngestResult(
- success=True,
- memories=tuple(
- HyMemoryOutput(
- memory_id=f"hy-imported-{index}",
- content=content,
- layer="L2_FACT",
- )
- for index, content in enumerate(contents)
- ),
- )
-
- async def close(self) -> None:
- self.closed = True
-
- async def outputs_for_request(self, **_kwargs) -> tuple[HyMemoryOutput, ...]:
- return self.outputs or ()
-
- async def search_scores(self, *_args, **_kwargs) -> tuple[object, ...]:
- return tuple((memory_id, 0.9) for memory_id in self.search_result_ids)
-
- async def profile_memories(
- self,
- *,
- user_id: str,
- agent_id: str,
- ) -> tuple[HyMemoryOutput, ...]:
- self.profile_reads.append((user_id, agent_id))
- return self.profile
-
- async def digest(self, *, user_id: str, agent_id: str) -> dict[str, object]:
- self.digest_calls.append((user_id, agent_id))
- return {"success": True, "tasks_processed": 1}
-
- async def graph_snapshot(
- self,
- *,
- user_id: str,
- agent_id: str,
- limit: int = 300,
- ) -> HyGraphSnapshot:
- self.graph_reads.append((user_id, agent_id))
- return HyGraphSnapshot(nodes=self.graph_nodes, edges=())
-
- async def list_agent_ids(self, *, user_id: str, limit: int = 1_000) -> tuple[str, ...]:
- return self.stored_agent_ids
-
-
-def _put(
- store: EvidenceStore,
- *,
- message_id: str,
- role: str,
- written_by: WrittenBy,
- content: str,
- conversation_id: str = "conversation",
- workspace: str | None = None,
- content_kind: EvidenceContentKind = EvidenceContentKind.RAW_CONVERSATION,
- created_at: datetime | None = None,
- source_id: str = "cursor",
-):
- return store.put(
- EvidenceInput(
- source_id=source_id,
- workspace=workspace,
- conversation_id=conversation_id,
- message_id=message_id,
- correlation_id=message_id,
- content_kind=content_kind,
- role=role,
- written_by=written_by,
- verbatim=content,
- created_at=created_at,
- origin_meta={EvidenceOrigin.FILE: OriginMetadata()},
- )
- ).record
-
-
[email protected](autouse=True)
-def _diagnostics_on(monkeypatch):
- """Several tests here read the pipeline log, so the log is on.
-
- Diagnostics are off unless asked; a test that reads the log has to ask.
- """
- monkeypatch.setenv("ONE_MEMORY_DIAGNOSTICS", "1")
-
-
-def _setup(tmp_path):
- database = tmp_path / "one-memory.sqlite3"
- secrets = InMemorySecretStore()
- evidence = EvidenceStore(database)
- profiles = ModelProfileStore(database)
- tasks = MemoryTaskStore(database)
- governance = MemoryGovernanceStore(database)
- profile = profiles.create(
- ModelProfileInput(
- name="Local",
- provider_kind=ProviderKind.OLLAMA,
- model="hy-bot-phi4",
- embedding_model="nomic-embed-text",
- ),
- 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,
- )
- profile = profiles.activate(profile.profile_id, secrets)
- return evidence, profiles, tasks, governance, secrets, profile
-
-
-def _task(tasks, profile, record, *, suffix: str = ""):
- return tasks.create(
- request_id=f"native:{record.evidence_id}:{record.revision}:{suffix}",
- user_id=record.user_id,
- kind=MemoryTaskKind.EXTRACT,
- input_ref=record.evidence_id,
- profile=profile,
- )
-
-
-def _runner(tmp_path, stores, bridge):
- evidence, profiles, tasks, governance, secrets, _profile = stores
- return MemoryTaskRunner(
- tasks=tasks,
- profiles=profiles,
- secrets=secrets,
- evidence=evidence,
- governance=governance,
- data_dir=tmp_path,
- bridge_factory=lambda _profile, _secret, _data_dir: bridge,
- )
-
-
-def test_sdk_authority_executes_one_write_job_without_task_or_governance_mirror(
- tmp_path,
-) -> None:
- stores = _setup(tmp_path)
- evidence, profiles, tasks, governance, secrets, _profile = stores
- record = _put(
- evidence,
- message_id="sdk-authority",
- role="user",
- written_by=WrittenBy.PERSON,
- content="记住只调用一次 SDK。",
- )
-
- class Bridge(FakeBridge):
- async def ingest(self, request) -> HyMemoryIngestResult:
- self.requests.append(request)
- return HyMemoryIngestResult(
- success=True,
- raw_ids=("raw-1",),
- memories=(
- HyMemoryOutput(
- memory_id="memory-1",
- content="只调用一次 SDK。",
- layer="L2_FACT",
- ),
- ),
- )
-
- def forbidden():
- raise AssertionError("SDK authority must not open Governance derivation")
-
- governance.hy_derivation = forbidden # type: ignore[method-assign]
- bridge = Bridge()
- supervisor = MemoryProcessingSupervisor(
- tasks=tasks,
- profiles=profiles,
- secrets=secrets,
- evidence=evidence,
- governance=governance,
- data_dir=tmp_path,
- bridge_factory=lambda _profile, _secret, _data_dir: bridge,
- sdk_authority=lambda: True,
- )
-
- invoked = []
-
- async def mark_invoked() -> None:
- invoked.append(True)
-
- result = asyncio.run(
- supervisor.process_sdk_job(
- (record,),
- request_id="write-job-1",
- before_hy_invocation=mark_invoked,
- )
- )
-
- assert invoked == [True]
- assert len(bridge.requests) == 1
- assert bridge.requests[0].request_id == "write-job-1"
- assert result.raw_ids == ("raw-1",)
- assert tuple(memory.memory_id for memory in result.memories) == ("memory-1",)
- assert tasks.list() == []
- assert governance.get("memory-1", user_id="local") is None
-
-
-def test_sdk_authority_digest_never_publishes_governance_schema(tmp_path) -> None:
- stores = _setup(tmp_path)
- evidence, profiles, tasks, governance, secrets, _profile = stores
- bridge = FakeBridge()
- bridge.stored_agent_ids = ("cursor",)
-
- def forbidden():
- raise AssertionError("SDK digest must not derive Governance authority")
-
- governance.hy_derivation = forbidden # type: ignore[method-assign]
- supervisor = MemoryProcessingSupervisor(
- tasks=tasks,
- profiles=profiles,
- secrets=secrets,
- evidence=evidence,
- governance=governance,
- data_dir=tmp_path,
- bridge_factory=lambda _profile, _secret, _data_dir: bridge,
- sdk_authority=lambda: True,
- )
-
- result = asyncio.run(supervisor.digest())
-
- assert result["scope_count"] == 1
- assert result["schemas_recorded"] == 0
- assert bridge.digest_calls == [("local", "cursor")]
-
-
-def test_memory_task_logs_six_step_durations_without_content(tmp_path) -> None:
- stores = _setup(tmp_path)
- evidence, _profiles, tasks, _governance, _secrets, profile = stores
- marker = "private-task-content-marker"
- record = _put(
- evidence,
- message_id="step-log",
- role="user",
- written_by=WrittenBy.PERSON,
- content=marker,
- )
- task = _task(tasks, profile, record)
- root = logging.getLogger()
- previous = root.level
- root.setLevel(logging.DEBUG)
- receipt = configure_diagnostics(tmp_path)
- try:
- asyncio.run(_runner(tmp_path, stores, FakeBridge()).run(task.task_id))
- finally:
- reset_diagnostics()
- root.setLevel(previous)
- written = receipt.path.read_text()
- events = [json.loads(line) for line in written.splitlines()]
- started = next(event for event in events if event["event"] == "memory_task.started")
- assert started["level"] == "info"
- steps = [event for event in events if event["event"] == "memory_task.step_completed"]
- assert [event["details"]["phase"] for event in steps] == ["1", "2", "3", "4", "5", "6"]
- finished = next(event for event in events if event["event"] == "memory_task.finished")
- assert finished["level"] == "info"
- assert finished["details"] == {
- "attempt": 1,
- "pending_count": 0,
- "result_count": 1,
- }
- assert tasks.processing_metrics()["hy_calls"] == 1
- assert all(event["duration_ms"] >= 0 for event in steps)
- assert marker not in written
-
-
-def test_assistant_turns_reach_hy_so_references_can_be_resolved(tmp_path) -> None:
- """助手那一侧要进抽取器,否则「就按你说的那个」指的是什么,没人知道。
-
- HY 的抽取 prompt 自己就是为双向设计的:示例 1 明写「旧消息只用于指代消解」,
- 示例 2 叫「浓缩 agent 的长篇回复」。我们过去只喂用户那一侧,
- 等于把它这两条能力饿死了。
- """
- stores = _setup(tmp_path)
- evidence, _profiles, tasks, _governance, _secrets, profile = stores
- first = _put(
- evidence,
- message_id="u1",
- role="user",
- written_by=WrittenBy.PERSON,
- content="前端网络请求应该怎么统一?",
- workspace="workspace:v1:one-memory",
- created_at=datetime(2026, 1, 1, 0, 0, 0, tzinfo=UTC),
- )
- _put(
- evidence,
- message_id="a1",
- role="assistant",
- written_by=WrittenBy.AGENT,
- content="建议统一走 axios 封装,不要裸调 fetch。",
- workspace="workspace:v1:one-memory",
- created_at=datetime(2026, 1, 1, 0, 0, 1, tzinfo=UTC),
- )
- _put(
- evidence,
- message_id="u2",
- role="user",
- written_by=WrittenBy.PERSON,
- content="就按你说的那个来。",
- workspace="workspace:v1:one-memory",
- created_at=datetime(2026, 1, 1, 0, 0, 2, tzinfo=UTC),
- )
- task = _task(tasks, profile, first)
- bridge = FakeBridge()
-
- asyncio.run(_runner(tmp_path, stores, bridge).run(task.task_id))
-
- # One turn per request; the next turn reaches HY with this one as history.
- assert [(turn.role, turn.content) for turn in bridge.requests[0].turns] == [
- ("user", "前端网络请求应该怎么统一?"),
- ("assistant", "建议统一走 axios 封装,不要裸调 fetch。"),
- ]
-
-
-def test_secrets_in_assistant_output_are_redacted_too(tmp_path) -> None:
- """助手那一侧现在也会被送出去,所以脱敏必须一样管到它。"""
- stores = _setup(tmp_path)
- evidence, _profiles, tasks, _governance, _secrets, profile = stores
- user = _put(
- evidence,
- message_id="u1",
- role="user",
- written_by=WrittenBy.PERSON,
- content="帮我登录一下。",
- created_at=datetime(2026, 1, 1, 0, 0, 0, tzinfo=UTC),
- )
- _put(
- evidence,
- message_id="a1",
- role="assistant",
- written_by=WrittenBy.AGENT,
- content="执行:docker login --username kristinhe --password exposed-token-value",
- created_at=datetime(2026, 1, 1, 0, 0, 1, tzinfo=UTC),
- )
- task = _task(tasks, profile, user)
- bridge = FakeBridge()
-
- asyncio.run(_runner(tmp_path, stores, bridge).run(task.task_id))
-
- sent = [turn.content for turn in bridge.requests[0].turns]
- assert "exposed-token-value" not in " ".join(sent)
- assert "<redacted-secret>" in sent[1]
-
-
-def test_agent_owned_memories_land_usable_but_marked_as_the_assistant(tmp_path) -> None:
- """助手输出里的事实也直接可用,但来源标成助手。
-
- 不再有「待确认」这道关:它让助手那侧的内容永远进不了召回。能区分的是
- origin —— 召回和事项据此知道这句话是 AI 说的,不是本人的判断。
- """
- stores = _setup(tmp_path)
- evidence, _profiles, tasks, governance, _secrets, profile = stores
- user = _put(
- evidence,
- message_id="u1",
- role="user",
- written_by=WrittenBy.PERSON,
- content="帮我写一篇远程办公的短文。",
- )
- _put(
- evidence,
- message_id="a1",
- role="assistant",
- written_by=WrittenBy.AGENT,
- content="好的,开头是……结尾是自主性带来更高产出。",
- )
- task = _task(tasks, profile, user)
- bridge = FakeBridge(
- outputs=(
- HyMemoryOutput(
- memory_id="hy-user-1",
- content="用户需要一篇论述远程办公提升效率的短文。",
- owner="user",
- ),
- HyMemoryOutput(
- memory_id="hy-agent-1",
- content="assistant 为用户写了一篇短文,论点是远程办公提升效率。",
- owner="agent",
- ),
- )
- )
-
- asyncio.run(_runner(tmp_path, stores, bridge).run(task.task_id))
-
- landed = {item.content: item for item in governance.list(user_id="local")}
- assert set(landed) == {
- "用户需要一篇论述远程办公提升效率的短文。",
- "assistant 为用户写了一篇短文,论点是远程办公提升效率。",
- }
- person = landed["用户需要一篇论述远程办公提升效率的短文。"]
- agent = landed["assistant 为用户写了一篇短文,论点是远程办公提升效率。"]
- assert person.origin is MemoryOrigin.EXTRACTED
- assert person.status is MemoryStatus.CONFIRMED
- assert agent.origin is MemoryOrigin.AGENT
- assert agent.status is MemoryStatus.CONFIRMED
-
-
-def test_an_agent_owned_memory_alone_is_still_usable(tmp_path) -> None:
- """一批里只有助手那侧的记忆,也照样可用,不等人确认。"""
- stores = _setup(tmp_path)
- evidence, _profiles, tasks, governance, _secrets, profile = stores
- user = _put(
- evidence,
- message_id="u1",
- role="user",
- written_by=WrittenBy.PERSON,
- content="帮我排一个七天日本行程。",
- )
- _put(
- evidence,
- message_id="a1",
- role="assistant",
- written_by=WrittenBy.AGENT,
- content="东京—京都—奈良—大阪,关西机场离境。",
- )
- task = _task(tasks, profile, user)
- bridge = FakeBridge(
- outputs=(
- HyMemoryOutput(
- memory_id="hy-agent-1",
- content="assistant 为用户制定了七天日本行程。",
- owner="agent",
- ),
- )
- )
-
- asyncio.run(_runner(tmp_path, stores, bridge).run(task.task_id))
-
- only = governance.list(user_id="local")[0]
- assert only.origin is MemoryOrigin.AGENT
- assert only.status is MemoryStatus.CONFIRMED
-
-
-def test_memories_without_an_owner_still_land(tmp_path) -> None:
- """正向对照:没标 owner 的照旧写下来,否则上面那条测的只是「什么都不写」。"""
- stores = _setup(tmp_path)
- evidence, _profiles, tasks, governance, _secrets, profile = stores
- user = _put(
- evidence,
- message_id="u1",
- role="user",
- written_by=WrittenBy.PERSON,
- content="周末不排评审会。",
- )
- task = _task(tasks, profile, user)
- bridge = FakeBridge(
- outputs=(HyMemoryOutput(memory_id="hy-1", content="用户周末不安排评审会。"),)
- )
-
- asyncio.run(_runner(tmp_path, stores, bridge).run(task.task_id))
-
- assert [item.content for item in governance.list(user_id="local")] == ["用户周末不安排评审会。"]
-
-
-def test_assistant_only_window_is_usable_and_attributed_to_the_assistant(tmp_path) -> None:
- """D04: keep project reports without attributing them to the person."""
- stores = _setup(tmp_path)
- evidence, _profiles, tasks, governance, _secrets, profile = stores
- first = _put(
- evidence,
- message_id="a1",
- role="assistant",
- written_by=WrittenBy.AGENT,
- content="我先总结一下刚才的方案。",
- )
- _put(
- evidence,
- message_id="a2",
- role="assistant",
- written_by=WrittenBy.AGENT,
- content="另外还有三个待办。",
- )
- task = _task(tasks, profile, first)
- bridge = FakeBridge()
-
- asyncio.run(_runner(tmp_path, stores, bridge).run(task.task_id))
-
- assert len(bridge.requests) == 1
- assert [turn.role for turn in bridge.requests[0].turns] == ["assistant", "assistant"]
- memories = governance.list(user_id="local")
- assert memories
- assert all(memory.origin is MemoryOrigin.AGENT for memory in memories)
- assert all(memory.status is MemoryStatus.CONFIRMED for memory in memories)
-
-
-def test_what_lands_in_governance_still_comes_from_the_person(tmp_path) -> None:
- stores = _setup(tmp_path)
- evidence, _profiles, tasks, governance, _secrets, profile = stores
- user = _put(
- evidence,
- message_id="u1",
- role="user",
- written_by=WrittenBy.PERSON,
- content="这个交互太绕了,我更喜欢一步完成。",
- workspace="workspace:v1:one-memory",
- )
- _put(
- evidence,
- message_id="a1",
- role="assistant",
- written_by=WrittenBy.AGENT,
- content="明白,你偏好更直接的单步流程。",
- workspace="workspace:v1:one-memory",
- )
- task = _task(tasks, profile, user)
- bridge = FakeBridge()
-
- completed = asyncio.run(_runner(tmp_path, stores, bridge).run(task.task_id))
-
- assert completed.status is MemoryTaskStatus.COMPLETED
- assert bridge.extracted_contents == []
- request = bridge.requests[0]
- assert request.agent_id.startswith(f"{UNIFIED_HY_AGENT_ID}:scope:")
- assert request.agent_id != UNIFIED_HY_AGENT_ID
- # 助手那一句现在也送出去了,但落库的仍旧只有一条 —— FakeBridge 默认
- # 不标 owner,所以这里测的是「多送不等于多记」。
- assert [(turn.role, turn.content) for turn in request.turns] == [
- ("user", user.verbatim),
- ("assistant", "明白,你偏好更直接的单步流程。"),
- ]
- assert len(governance.list(user_id="local")) == 1
- memory = governance.list(user_id="local")[0]
- assert memory.status is MemoryStatus.CONFIRMED
- assert memory.content == "用户偏好本地优先的记忆处理。"
- assert memory.scopes == ("all-apps", "workspace:v1:one-memory")
- # 出处是这条记忆所在的那一段来回,不只是被抽中的那一句。
- # 右栏点开要能读懂,而「明白,你偏好更直接的单步流程」正是读懂它的一半。
- assert len(memory.evidence_ids) == 2
- assert user.evidence_id in memory.evidence_ids
-
-
-def test_raw_conversation_secrets_are_redacted_before_hy(tmp_path) -> None:
- stores = _setup(tmp_path)
- evidence, _profiles, tasks, _governance, _secrets, profile = stores
- user = _put(
- evidence,
- message_id="u1",
- role="user",
- written_by=WrittenBy.PERSON,
- content="docker login --username kristinhe --password exposed-token-value",
- )
- task = _task(tasks, profile, user)
- bridge = FakeBridge()
-
- asyncio.run(_runner(tmp_path, stores, bridge).run(task.task_id))
-
- assert bridge.requests[0].turns[0].content == (
- "docker login --username kristinhe --password <redacted-secret>"
- )
- assert user.verbatim == ("docker login --username kristinhe --password exposed-token-value")
-
-
-def test_hy_output_is_not_rejected_by_one_memory_policy(tmp_path) -> None:
- stores = _setup(tmp_path)
- evidence, _profiles, tasks, governance, _secrets, profile = stores
- user = _put(
- evidence,
- message_id="u1",
- role="user",
- written_by=WrittenBy.PERSON,
- content="请帮我审查这份方案。",
- )
- output = HyMemoryOutput(
- memory_id="hy-l1",
- content="方案审查体现了用户重视可验证交付。",
- layer="L0_BASIC_INFO",
- )
- task = _task(tasks, profile, user)
-
- asyncio.run(
- _runner(
- tmp_path,
- stores,
- FakeBridge(outputs=(output,)),
- ).run(task.task_id)
- )
-
- memory = governance.list(user_id="local")[0]
- assert memory.memory_id == "hy-l1"
- assert memory.status is MemoryStatus.CONFIRMED
- assert memory.content == output.content
-
-
-def test_hy_output_secret_is_redacted_before_governance_projection(tmp_path) -> None:
- stores = _setup(tmp_path)
- evidence, _profiles, tasks, governance, _secrets, profile = stores
- user = _put(
- evidence,
- message_id="u1",
- role="user",
- written_by=WrittenBy.PERSON,
- content="Remember the registry setup.",
- )
- task = _task(tasks, profile, user)
- output = HyMemoryOutput(
- memory_id="hy-secret",
- content="Registry token=hallucinated-secret-value",
- layer="L0_BASIC_INFO",
- )
-
- asyncio.run(
- _runner(
- tmp_path,
- stores,
- FakeBridge(outputs=(output,)),
- ).run(task.task_id)
- )
-
- assert governance.list(user_id="local")[0].content == ("Registry token=<redacted-secret>")
-
-
-def test_workspace_intention_reaches_every_app_and_keeps_its_project(tmp_path) -> None:
- stores = _setup(tmp_path)
- evidence, _profiles, tasks, governance, _secrets, profile = stores
- user = _put(
- evidence,
- message_id="u1",
- role="user",
- written_by=WrittenBy.PERSON,
- content="明天完成 One Memory 的完整链路。",
- workspace="workspace:v1:one-memory",
- )
- task = _task(tasks, profile, user)
- output = HyMemoryOutput(
- memory_id="hy-intention",
- content="用户计划明天完成 One Memory 的完整链路。",
- layer="L7_INTENTION",
- )
-
- asyncio.run(
- _runner(
- tmp_path,
- stores,
- FakeBridge(outputs=(output,)),
- ).run(task.task_id)
- )
-
- memory = governance.list(user_id="local")[0]
- assert memory.scopes == ("all-apps", "workspace:v1:one-memory")
-
-
-def test_what_hy_learns_about_the_person_reaches_every_app(tmp_path) -> None:
- """The profile layer arrives by being read back, not by being returned.
-
- HY writes basic info on its own path and the ids never appear in the
- ingest response, so for as long as this was not read back, the profile
- existed only inside HY. On this machine that was 483 confirmed memories
- all scoped to one project and nothing at all for a host that does not say
- which project it is in — recall then came back empty by construction.
- """
- stores = _setup(tmp_path)
- evidence, _profiles, tasks, governance, _secrets, profile = stores
- user = _put(
- evidence,
- message_id="u1",
- role="user",
- written_by=WrittenBy.PERSON,
- content="我是产品出身,叫 Kristin。",
- workspace="workspace:v1:one-memory",
- )
- task = _task(tasks, profile, user)
- bridge = FakeBridge(
- outputs=(
- HyMemoryOutput(
- memory_id="hy-fact",
- content="用户偏好本地优先的记忆处理。",
- layer="L2_FACT",
- ),
- ),
- profile=(
- HyMemoryOutput(
- memory_id="hy-profile",
- content="The user's name is Kristin, occupation is 产品出身.",
- layer="L0_BASIC_INFO",
- ),
- ),
- )
-
- asyncio.run(_runner(tmp_path, stores, bridge).run(task.task_id))
-
- memories = {memory.memory_id: memory for memory in governance.list(user_id="local")}
- assert memories["hy-fact"].scopes == ("all-apps", "workspace:v1:one-memory")
- # The person is the same person in every app, so the profile is readable
- # from all of them — and still from the project, which is where a host
- # that does name its project will look.
- assert memories["hy-profile"].scopes == (
- "all-apps",
- "workspace:v1:one-memory",
- )
- assert bridge.profile_reads == [("local", bridge.requests[0].agent_id)]
-
-
-def test_the_same_unchanged_profile_is_not_recorded_again(tmp_path) -> None:
- """Every task reads the profile, and it rarely changes between two.
-
- Read back per task rather than reported by the write, the same basic info
- comes back for as long as HY has learnt nothing new. Recorded each time it
- would mean one memory per conversation saying the same thing.
- """
- stores = _setup(tmp_path)
- evidence, _profiles, tasks, governance, _secrets, profile = stores
- same_profile = (
- HyMemoryOutput(
- memory_id="hy-profile",
- content="The user's name is Kristin.",
- layer="L0_BASIC_INFO",
- ),
- )
- for index in range(2):
- record = _put(
- evidence,
- message_id=f"u{index}",
- role="user",
- written_by=WrittenBy.PERSON,
- content=f"第 {index} 轮。",
- conversation_id=f"conversation-{index}",
- )
- task = _task(tasks, profile, record)
- asyncio.run(
- _runner(
- tmp_path,
- stores,
- FakeBridge(outputs=(), profile=same_profile),
- ).run(task.task_id)
- )
-
- profiles = [
- memory for memory in governance.list(user_id="local") if memory.memory_id == "hy-profile"
- ]
- assert len(profiles) == 1
- # Both conversations are why we believe it, so both are cited.
- assert len(profiles[0].evidence_ids) == 2
-
-
-def test_the_profile_layers_are_the_ones_hy_calls_profile(tmp_path) -> None:
- """Pin our layer list to HY's, rather than keeping a second opinion.
-
- HY decides what a profile is; its client holds
- `_PROFILE_LAYERS = {"l0_basic_info", "l6_schema"}`. Ours drifted from that
- once already, to a layer that does not exist.
- """
- from one_memory.memory_processing import _memory_scopes
-
- stores = _setup(tmp_path)
- evidence = stores[0]
- record = _put(
- evidence,
- message_id="u1",
- role="user",
- written_by=WrittenBy.PERSON,
- content="任意内容。",
- workspace="workspace:v1:atlas",
- )
- chunk = (evidence.list_conversation(record.evidence_id)[0],)
-
- for layer in ("L0_BASIC_INFO", "L6_SCHEMA"):
- assert _memory_scopes(chunk, layer=layer)[0] == "all-apps", layer
-
-
- "layer", [None, "L1_RAW", "L2_FACT", "L3_SUMMARY", "L4_IDENTITY", "L7_INTENTION"]
-)
-def test_a_memory_from_one_app_is_readable_from_every_app(tmp_path, layer) -> None:
- """Cross-app recall is the product: a fact learned in one app reaches the others.
-
- The workspace scope stays alongside, so a caller scoped to that project
- still reads it; `all-apps` is a literal scope, not a wildcard.
- """
- from one_memory.memory_processing import _memory_scopes
-
- stores = _setup(tmp_path)
- evidence = stores[0]
- record = _put(
- evidence,
- message_id="u1",
- role="user",
- written_by=WrittenBy.PERSON,
- content="任意内容。",
- workspace="workspace:v1:atlas",
- )
- chunk = (evidence.list_conversation(record.evidence_id)[0],)
- unscoped = _put(
- evidence,
- message_id="u2",
- role="user",
- written_by=WrittenBy.PERSON,
- content="没有工作区的对话。",
- conversation_id="empty-window",
- )
-
- assert _memory_scopes(chunk, layer=layer) == ("all-apps", "workspace:v1:atlas")
- scopes = _memory_scopes((unscoped,), layer=layer)
- assert scopes[0] == "all-apps"
- assert scopes[1].startswith("workspace:v1:")
-
-
-def test_unscoped_intention_uses_isolated_conversation_scope(tmp_path) -> None:
- stores = _setup(tmp_path)
- evidence, _profiles, tasks, governance, _secrets, profile = stores
- user = _put(
- evidence,
- message_id="u1",
- role="user",
- written_by=WrittenBy.PERSON,
- content="Deploy the admin backend.",
- conversation_id="empty-window-task",
- )
- task = _task(tasks, profile, user)
- output = HyMemoryOutput(
- memory_id="hy-intention",
- content="Deploy the admin backend.",
- layer="L7_INTENTION",
- )
- bridge = FakeBridge(outputs=(output,))
-
- asyncio.run(
- _runner(
- tmp_path,
- stores,
- bridge,
- ).run(task.task_id)
- )
-
- memory = governance.list(user_id="local")[0]
- assert bridge.requests[0].agent_id.startswith(f"{UNIFIED_HY_AGENT_ID}:scope:")
- assert memory.scopes[0] == "all-apps"
- assert memory.scopes[1].startswith("workspace:v1:")
- assert "empty-window-task" not in memory.scopes[1]
-
-
-def test_hy_empty_result_is_a_successful_no_memory_decision(tmp_path) -> None:
- stores = _setup(tmp_path)
- evidence, _profiles, tasks, governance, _secrets, profile = stores
- user = _put(
- evidence,
- message_id="u1",
- role="user",
- written_by=WrittenBy.PERSON,
- content="把按钮移到左边。",
- )
- task = _task(tasks, profile, user)
-
- completed = asyncio.run(
- _runner(
- tmp_path,
- stores,
- FakeBridge(outputs=()),
- ).run(task.task_id)
- )
-
- assert completed.status is MemoryTaskStatus.COMPLETED
- assert governance.list(user_id="local") == []
-
-
[email protected]("author", [WrittenBy.PERSON, WrittenBy.AGENT, WrittenBy.UNKNOWN])
-def test_memory_content_without_raw_uses_add_extracted_and_is_usable(tmp_path, author):
- stores = _setup(tmp_path)
- evidence, _profiles, tasks, governance, _secrets, profile = stores
- imported = _put(
- evidence,
- message_id="memory-1",
- role="memory",
- written_by=author,
- content="用户偏好简洁直接的中文表达。",
- content_kind=EvidenceContentKind.MEMORY_CONTENT,
- )
- task = _task(tasks, profile, imported)
- bridge = FakeBridge()
-
- asyncio.run(_runner(tmp_path, stores, bridge).run(task.task_id))
-
- assert bridge.extracted_contents == [(imported.verbatim,)]
- memory = governance.list(user_id="local")[0]
- assert memory.status is MemoryStatus.CONFIRMED
- assert memory.content == imported.verbatim
-
-
-def test_existing_memory_empty_hy_result_never_fabricates_a_governed_output(tmp_path):
- stores = _setup(tmp_path)
- evidence, _profiles, tasks, governance, _secrets, profile = stores
- imported = _put(
- evidence,
- message_id="m1",
- role="memory",
- written_by=WrittenBy.UNKNOWN,
- content="This report has no underlying chat.",
- content_kind=EvidenceContentKind.MEMORY_CONTENT,
- )
- task = _task(tasks, profile, imported)
-
- class EmptyBridge(FakeBridge):
- async def ingest_extracted(self, request, contents):
- self.extracted_contents.append(tuple(contents))
- return HyMemoryIngestResult(success=True, memories=())
-
- bridge = EmptyBridge()
- completed = asyncio.run(_runner(tmp_path, stores, bridge).run(task.task_id))
- assert bridge.extracted_contents == [(imported.verbatim,)]
- assert completed.status is MemoryTaskStatus.FAILED
- assert completed.last_error_code == "hy_memory_import_no_readable_output"
- assert governance.list(user_id="local") == []
- assert evidence.get(imported.evidence_id).verbatim == imported.verbatim
-
-
[email protected]("existing_origin", [MemoryOrigin.AGENT, MemoryOrigin.EXTRACTED])
-def test_agent_output_keeps_the_origin_of_a_same_content_memory(tmp_path, existing_origin):
- stores = _setup(tmp_path)
- evidence, _profiles, tasks, governance, _secrets, profile = stores
- raw = _put(
- evidence,
- message_id="a1",
- role="assistant",
- written_by=WrittenBy.AGENT,
- content="The assistant reports that the deployment finished.",
- )
- original = as_person(governance).create(
- MemoryDraft(
- user_id="local",
- kind=MemoryKind.CHAT,
- content=raw.verbatim,
- scopes=("all-apps",),
- evidence_ids=(raw.evidence_id,),
- origin=existing_origin,
- ),
- request_id="existing-report",
- )
- task = _task(tasks, profile, raw)
- bridge = FakeBridge(
- outputs=(HyMemoryOutput(memory_id="same-report", content=raw.verbatim, owner="agent"),)
- )
- asyncio.run(_runner(tmp_path, stores, bridge).run(task.task_id))
- current = governance.get(original.memory_id, user_id="local")
- assert current.status is MemoryStatus.CONFIRMED
- assert current.origin == existing_origin
- assert current.revision == original.revision
-
-
-def test_a_new_hy_memory_is_mirrored_under_its_own_id_even_when_the_text_repeats(tmp_path):
- """HY decides whether two memories are one; the ledger mirrors its ids.
-
- Folding a new HY id into an older row with the same words left HY holding a
- node the product never showed, and any later HY update or delete of that id
- had nothing to land on.
- """
- stores = _setup(tmp_path)
- evidence, _profiles, tasks, governance, _secrets, profile = stores
- first = _put(
- evidence,
- message_id="u1",
- role="user",
- written_by=WrittenBy.PERSON,
- content="我周末不开评审会。",
- conversation_id="c1",
- )
- earlier = as_person(governance).create(
- MemoryDraft(
- user_id="local",
- kind=MemoryKind.CHAT,
- content="用户周末不安排评审会。",
- scopes=("all-apps",),
- evidence_ids=(first.evidence_id,),
- ),
- request_id="earlier",
- memory_id="hy-earlier",
- )
- second = _put(
- evidence,
- message_id="u2",
- role="user",
- written_by=WrittenBy.PERSON,
- content="再说一次,周末别排评审。",
- conversation_id="c2",
- )
- task = _task(tasks, profile, second)
- bridge = FakeBridge(
- outputs=(HyMemoryOutput(memory_id="hy-later", content="用户周末不安排评审会。"),)
- )
-
- asyncio.run(_runner(tmp_path, stores, bridge).run(task.task_id))
-
- later = governance.get("hy-later", user_id="local")
- assert later is not None
- assert later.content == "用户周末不安排评审会。"
- assert later.evidence_ids == (second.evidence_id,)
- assert governance.get(earlier.memory_id, user_id="local").evidence_ids == (first.evidence_id,)
-
-
-def test_a_memory_file_the_person_imported_is_readable_from_every_app(tmp_path):
- stores = _setup(tmp_path)
- evidence, *_ = stores
- imported = evidence.put(
- EvidenceInput(
- source_id="memory-content-export",
- conversation_id="report-a",
- message_id="1",
- role="memory",
- written_by=WrittenBy.UNKNOWN,
- content_kind=EvidenceContentKind.MEMORY_CONTENT,
- verbatim="An imported profile the person chose to bring in.",
- origin_meta={EvidenceOrigin.FILE: OriginMetadata()},
- )
- ).record
- from one_memory.memory_processing import _memory_scopes
-
- assert _hy_agent_id((imported,)) != UNIFIED_HY_AGENT_ID
- for layer in ("L0_BASIC_INFO", "L2_FACT", "L6_SCHEMA"):
- assert _memory_scopes((imported,), layer=layer)[0] == "all-apps"
-
-
-def test_reimport_leaves_an_existing_memory_and_its_scopes_alone(tmp_path):
- stores = _setup(tmp_path)
- evidence, _profiles, tasks, governance, _secrets, profile = stores
- imported = _put(
- evidence,
- message_id="m1",
- role="memory",
- written_by=WrittenBy.UNKNOWN,
- content="An explicitly reviewed report.",
- content_kind=EvidenceContentKind.MEMORY_CONTENT,
- )
- original = as_person(governance).create(
- MemoryDraft(
- user_id="local",
- kind=MemoryKind.CHAT,
- content=imported.verbatim,
- scopes=("workspace:reviewed",),
- evidence_ids=(imported.evidence_id,),
- origin=MemoryOrigin.AGENT,
- ),
- request_id="original-reviewed-report",
- )
- task = _task(tasks, profile, imported)
- asyncio.run(_runner(tmp_path, stores, FakeBridge()).run(task.task_id))
- current = governance.get(original.memory_id, user_id="local")
- assert current.status is MemoryStatus.CONFIRMED
- assert current.scopes == ("workspace:reviewed",)
-
-
-def test_memory_content_secret_is_redacted_before_hy_and_local_projection(tmp_path) -> None:
- stores = _setup(tmp_path)
- evidence, _profiles, tasks, governance, _secrets, profile = stores
- imported = _put(
- evidence,
- message_id="memory-1",
- role="memory",
- written_by=WrittenBy.AGENT,
- content="Registry password=exposed-token-value",
- content_kind=EvidenceContentKind.MEMORY_CONTENT,
- )
- task = _task(tasks, profile, imported)
- bridge = FakeBridge()
-
- asyncio.run(_runner(tmp_path, stores, bridge).run(task.task_id))
-
- assert bridge.extracted_contents == [("Registry password=<redacted-secret>",)]
- assert governance.list(user_id="local")[0].content == ("Registry password=<redacted-secret>")
-
-
-def test_memory_content_with_raw_never_becomes_an_additional_user_turn(tmp_path) -> None:
- stores = _setup(tmp_path)
- evidence, _profiles, tasks, governance, _secrets, profile = stores
- user = _put(
- evidence,
- message_id="u1",
- role="user",
- written_by=WrittenBy.PERSON,
- content="我喜欢更直接的回答。",
- )
- imported = _put(
- evidence,
- message_id="memory-1",
- role="memory",
- written_by=WrittenBy.AGENT,
- content="用户偏好简洁表达。",
- content_kind=EvidenceContentKind.MEMORY_CONTENT,
- )
- task = _task(tasks, profile, user)
- bridge = FakeBridge()
-
- asyncio.run(_runner(tmp_path, stores, bridge).run(task.task_id))
-
- assert bridge.extracted_contents == []
- assert [turn.content for turn in bridge.requests[0].turns] == [user.verbatim]
- assert evidence.get(imported.evidence_id).verbatim == imported.verbatim
- assert bridge.requests[0].source_context is not None
- assert [record.evidence_id for record in bridge.requests[0].source_context.current] == [
- user.evidence_id
- ]
- assert governance.list(user_id="local")[0].content == "用户偏好本地优先的记忆处理。"
-
-
-def test_conversation_order_is_decided_by_time_not_by_hash(tmp_path) -> None:
- """A turn's order must come from its timestamp, not from an idle tie-break.
-
- `EvidenceStore.list_conversation` orders by
- `(created_at, source_ordinal, evidence_id)`. Records with no explicit
- `created_at` all tie on the first key, so the order falls through to
- `evidence_id`, which is a UUID5 hash of the message - effectively random.
- Tests that assert a specific order must therefore give their records
- ordered timestamps. This pins that contract so the ordering tests cannot
- silently become flaky again.
- """
- stores = _setup(tmp_path)
- evidence, *_rest = stores
- second = _put(
- evidence,
- message_id="z-later",
- role="assistant",
- written_by=WrittenBy.AGENT,
- content="second",
- created_at=datetime(2026, 1, 1, 0, 0, 5, tzinfo=UTC),
- )
- first = _put(
- evidence,
- message_id="a-earlier",
- role="user",
- written_by=WrittenBy.PERSON,
- content="first",
- created_at=datetime(2026, 1, 1, 0, 0, 0, tzinfo=UTC),
- )
- ordered = [record.evidence_id for record in evidence.list_conversation(first.evidence_id)]
- assert ordered == [first.evidence_id, second.evidence_id]
-
-
-def test_host_envelopes_and_non_person_user_turns_still_never_reach_hy(tmp_path) -> None:
- """助手轮次放行之后,被挡的那两类必须仍旧被挡。
-
- 这里挡的是「冒充本人」的东西:harness 替人打的字、宿主塞进 user 角色的
- 系统提示。助手轮次从不冒充谁,所以它进来不影响这条边界。
- """
- stores = _setup(tmp_path)
- evidence, *_rest = stores
- person = _put(
- evidence,
- message_id="person",
- role="user",
- written_by=WrittenBy.PERSON,
- content="真实问题",
- created_at=datetime(2026, 1, 1, 0, 0, 0, tzinfo=UTC),
- )
- assistant = _put(
- evidence,
- message_id="assistant",
- role="assistant",
- written_by=WrittenBy.AGENT,
- content="Generated response",
- created_at=datetime(2026, 1, 1, 0, 0, 1, tzinfo=UTC),
- )
- _put(
- evidence,
- message_id="system-user",
- role="user",
- written_by=WrittenBy.AGENT,
- content="<system_reminder>hidden</system_reminder>",
- created_at=datetime(2026, 1, 1, 0, 0, 2, tzinfo=UTC),
- )
- _put(
- evidence,
- message_id="harness",
- role="user",
- written_by=WrittenBy.PERSON,
- content="<environment_context>cwd=/tmp</environment_context>",
- created_at=datetime(2026, 1, 1, 0, 0, 3, tzinfo=UTC),
- )
-
- chunks = _conversation_chunks(evidence.list_conversation(person.evidence_id))
-
- assert len(chunks) == 1
- assert [record.evidence_id for record in chunks[0]] == [
- person.evidence_id,
- assistant.evidence_id,
- ]
-
-
-def test_unavailable_hy_keeps_task_waiting_for_same_model_snapshot(tmp_path) -> None:
- stores = _setup(tmp_path)
- evidence, _profiles, tasks, governance, _secrets, profile = stores
- user = _put(
- evidence,
- message_id="u1",
- role="user",
- written_by=WrittenBy.PERSON,
- content="记住这段对话。",
- )
- task = _task(tasks, profile, user)
-
- waiting = asyncio.run(
- _runner(
- tmp_path,
- stores,
- FakeBridge(fail=True),
- ).run(task.task_id)
- )
-
- assert waiting.status is MemoryTaskStatus.WAITING_FOR_MODEL
- assert waiting.profile_revision == task.profile_revision
- assert governance.list(user_id="local") == []
-
-
-def test_backfill_creates_native_tasks_for_all_conversations(tmp_path) -> None:
- stores = _setup(tmp_path)
- evidence, profiles, tasks, governance, secrets, _profile = stores
- first = _put(
- evidence,
- message_id="u1",
- role="user",
- written_by=WrittenBy.PERSON,
- content="第一段普通对话。",
- conversation_id="conversation-1",
- content_kind=EvidenceContentKind.MEMORY_CONTENT,
- )
- second = _put(
- evidence,
- message_id="u2",
- role="user",
- written_by=WrittenBy.PERSON,
- content="第二段普通对话。",
- conversation_id="conversation-2",
- content_kind=EvidenceContentKind.MEMORY_CONTENT,
- )
-
- async def exercise() -> None:
- supervisor = MemoryProcessingSupervisor(
- tasks=tasks,
- profiles=profiles,
- secrets=secrets,
- evidence=evidence,
- governance=governance,
- data_dir=tmp_path,
- runner_factory=lambda: _runner(tmp_path, stores, FakeBridge(outputs=())),
- )
- supervisor.backfill()
- for _ in range(100):
- if len(tasks.list()) == 2 and all(
- task.status is MemoryTaskStatus.COMPLETED for task in tasks.list()
- ):
- break
- await asyncio.sleep(0.01)
- await supervisor.shutdown()
-
- asyncio.run(exercise())
-
- assert {task.input_ref for task in tasks.list()} == {
- first.evidence_id,
- second.evidence_id,
- }
-
-
-def test_write_bridges_are_shared_within_a_source_and_separate_across_sources(tmp_path) -> None:
- stores = _setup(tmp_path)
- _evidence, _profiles, _tasks, _governance, _secrets, profile = stores
- supervisor = MemoryProcessingSupervisor(
- tasks=stores[2],
- profiles=stores[1],
- secrets=stores[4],
- evidence=stores[0],
- governance=stores[3],
- data_dir=tmp_path,
- )
-
- workbuddy = supervisor._bridge(profile, None, tmp_path, scope_key="workbuddy")
- assert supervisor._bridge(profile, None, tmp_path, scope_key="workbuddy") is workbuddy
- assert supervisor._bridge(profile, None, tmp_path, scope_key="cursor") is not workbuddy
-
-
-def test_payment_failure_stops_profile_until_successful_probe_resumes_it(tmp_path) -> None:
- stores = _setup(tmp_path)
- evidence, profiles, tasks, governance, secrets, profile = stores
- first = _put(
- evidence,
- message_id="payment-first",
- role="user",
- written_by=WrittenBy.PERSON,
- content="第一段历史。",
- conversation_id="payment-1",
- )
- second = _put(
- evidence,
- message_id="payment-second",
- role="user",
- written_by=WrittenBy.PERSON,
- content="第二段历史。",
- conversation_id="payment-2",
- )
- first_task = _task(tasks, profile, first)
- second_task = _task(tasks, profile, second)
-
- class PaymentRequiredBridge(FakeBridge):
- async def ingest(self, request) -> HyMemoryIngestResult:
- self.requests.append(request)
- raise HyMemoryBridgeError("hy_memory_model_payment_required")
-
- bridge = PaymentRequiredBridge()
- failed = asyncio.run(_runner(tmp_path, stores, bridge).run(first_task.task_id))
- assert failed.status is MemoryTaskStatus.WAITING_FOR_MODEL
- assert failed.last_error_code == "hy_memory_model_payment_required"
-
- supervisor = MemoryProcessingSupervisor(
- tasks=tasks,
- profiles=profiles,
- secrets=secrets,
- evidence=evidence,
- governance=governance,
- data_dir=tmp_path,
- )
- assert tasks.profile_stop_reason(profile.profile_id, profile.revision) == (
- "hy_memory_model_payment_required"
- )
- assert supervisor._classify([second_task]) == []
- assert len(bridge.requests) == 1
-
- assert tasks.resume_profile_after_probe(profile.profile_id, profile.revision) == 1
- assert tasks.profile_stop_reason(profile.profile_id, profile.revision) is None
- assert [work.task_id for work in supervisor._classify([second_task])] == [second_task.task_id]
-
-
-def test_backfill_scan_logs_inventory_and_queue_without_content(tmp_path) -> None:
- stores = _setup(tmp_path)
- evidence, profiles, tasks, governance, secrets, _profile = stores
- marker = "private-scheduler-body-5521"
- for index in (1, 2):
- _put(
- evidence,
- message_id=f"u{index}",
- role="user",
- written_by=WrittenBy.PERSON,
- content=f"{marker}-{index}",
- conversation_id=f"conversation-{index}",
- content_kind=EvidenceContentKind.MEMORY_CONTENT,
- )
- root = logging.getLogger()
- previous = root.level
- root.setLevel(logging.DEBUG)
- receipt = configure_diagnostics(tmp_path / "logs")
-
- async def exercise() -> None:
- supervisor = MemoryProcessingSupervisor(
- tasks=tasks,
- profiles=profiles,
- secrets=secrets,
- evidence=evidence,
- governance=governance,
- data_dir=tmp_path,
- runner_factory=lambda: _runner(tmp_path, stores, FakeBridge(outputs=())),
- )
- await supervisor.backfill_off_thread()
- await supervisor.shutdown()
-
- try:
- asyncio.run(exercise())
- finally:
- reset_diagnostics()
- root.setLevel(previous)
-
- written = receipt.path.read_text()
- events = [json.loads(line) for line in written.splitlines()]
- by_name = {event["event"]: event for event in events}
- assert by_name["memory_scheduler.scan_inventory"]["details"]["pending_count"] == 2
- assert by_name["memory_scheduler.tasks_queued"]["details"]["prepared_count"] >= 1
- completed = by_name["memory_scheduler.scan_completed"]
- assert completed["details"]["prepared_count"] == 2
- assert completed["duration_ms"] >= 0
- assert "memory_scheduler.scan_started" in by_name
- assert marker not in written
-
-
-def test_backfill_preparation_waits_while_realtime_model_work_is_active(tmp_path) -> None:
- stores = _setup(tmp_path)
- evidence, profiles, tasks, governance, secrets, _profile = stores
- scheduler = ServiceLevelScheduler()
- supervisor = MemoryProcessingSupervisor(
- tasks=tasks,
- profiles=profiles,
- secrets=secrets,
- evidence=evidence,
- governance=governance,
- data_dir=tmp_path,
- service_levels=scheduler,
- )
- advanced = threading.Event()
-
- def batches():
- advanced.set()
- yield []
-
- async def exercise() -> None:
- stop = threading.Event()
- async with scheduler.admit(
- ServiceResource.MODEL,
- ServiceLevel.REALTIME,
- work_id="live-turn",
- ):
- pending = asyncio.create_task(supervisor._next_backfill_batch(batches(), stop))
- await asyncio.sleep(0.05)
- assert not advanced.is_set()
- assert await asyncio.wait_for(pending, 1) == []
- assert advanced.is_set()
-
- asyncio.run(exercise())
-
-
-def test_cold_start_prioritizes_all_apps_before_workspace(tmp_path) -> None:
- """The reason R-02 kept the all-apps preference instead of deleting it.
-
- Cold start wants profile-shaped evidence landing first, so this is still
- the rule between two pieces of evidence of the same age. What R-02
- changed is where it sits: it used to lead the sort key, which sent every
- conversation written while coding to the back whatever its age. Now it
- only breaks ties, and `test_memory_queue_recency.py` pins that time wins.
- """
- stores = _setup(tmp_path)
- evidence, profiles, tasks, governance, secrets, profile = stores
- personal = _put(
- evidence,
- message_id="personal",
- role="user",
- written_by=WrittenBy.PERSON,
- content="我是一名产品经理,关注长期个人偏好。",
- conversation_id="personal-conversation",
- )
- workspace = _put(
- evidence,
- message_id="workspace",
- role="user",
- written_by=WrittenBy.PERSON,
- content="修 bug。",
- conversation_id="workspace-conversation",
- workspace="workspace:v1:project",
- )
- personal_task = _task(tasks, profile, personal, suffix="personal")
- workspace_task = _task(tasks, profile, workspace, suffix="workspace")
- same_moment = datetime(2026, 9, 8, 9, 0, tzinfo=UTC)
-
- def order(task, record):
- return classify(
- task.task_id,
- at=same_moment,
- imported_at=record.imported_at,
- workspace=record.workspace,
- length=len(record.verbatim),
- now=same_moment,
- ).order
-
- assert order(personal_task, personal) < order(workspace_task, workspace)
-
-
- strict=True,
- reason="D-16: superseded evidence does not retract its memory; remediation "
- "policy is an open product decision, so this pins the defect instead of "
- "hiding it. Fixing it must turn this into a plain assertion.",
-)
-def test_rewritten_turn_does_not_leave_the_old_claim_confirmed(tmp_path) -> None:
- """Editing an already-sent prompt must not leave the old claim standing.
-
- Cursor lets you rewrite a prompt you already sent, so the host revises the
- record in place. Re-extraction then runs on the new wording, but nothing
- revisits what the previous wording already turned into a confirmed memory,
- and recall serves confirmed memories as fact.
- """
- stores = _setup(tmp_path)
- evidence, _profiles, tasks, governance, _secrets, profile = stores
- original = _put(
- evidence,
- message_id="edited-turn",
- role="user",
- written_by=WrittenBy.PERSON,
- content="我平时用 Windows 开发。",
- )
- asyncio.run(
- _runner(
- tmp_path,
- stores,
- FakeBridge(
- outputs=(
- HyMemoryOutput(
- memory_id="hy-windows",
- content="用户平时用 Windows 开发。",
- layer="L0_BASIC_INFO",
- ),
- )
- ),
- ).run(_task(tasks, profile, original).task_id)
- )
-
- rewritten = _put(
- evidence,
- message_id="edited-turn",
- role="user",
- written_by=WrittenBy.PERSON,
- content="我平时用 macOS 开发。",
- )
- assert rewritten.revision > original.revision
-
- asyncio.run(
- _runner(
- tmp_path,
- stores,
- FakeBridge(
- outputs=(
- HyMemoryOutput(
- memory_id="hy-macos",
- content="用户平时用 macOS 开发。",
- layer="L0_BASIC_INFO",
- ),
- )
- ),
- ).run(_task(tasks, profile, rewritten, suffix="rewritten").task_id)
- )
-
- confirmed = {
- memory.content for memory in governance.list(user_id="local", status=MemoryStatus.CONFIRMED)
- }
- assert "用户平时用 macOS 开发。" in confirmed
- # The user never said this once they had edited the turn.
- assert "用户平时用 Windows 开发。" not in confirmed
-
-
-def test_keychain_denial_leaves_extraction_waiting_not_running(tmp_path, monkeypatch) -> None:
- from one_memory.secrets import SecretStoreUnavailableError
-
- stores = _setup(tmp_path)
- evidence, _profiles, tasks, _governance, secrets, profile = stores
- seed = _put(
- evidence,
- message_id="keychain-denied",
- role="user",
- written_by=WrittenBy.PERSON,
- content="请保留这句话。",
- )
- task = _task(tasks, profile, seed)
-
- def unavailable(*_args):
- raise SecretStoreUnavailableError("authorization required")
-
- monkeypatch.setattr(_profiles, "resolve_snapshot_secret", unavailable)
- result = asyncio.run(_runner(tmp_path, stores, FakeBridge(outputs=())).run(task.task_id))
- assert result.status is MemoryTaskStatus.WAITING_FOR_MODEL
- assert result.last_error_code == "secure_storage_unavailable"
- assert evidence.get(seed.evidence_id).verbatim == "请保留这句话。"
-
-
-def test_cancelled_debounce_does_not_remove_the_replacement_task(tmp_path) -> None:
- evidence, profiles, tasks, governance, secrets, _profile = _setup(tmp_path)
- seed = _put(
- evidence,
- message_id="debounce",
- role="user",
- written_by=WrittenBy.PERSON,
- content="同一会话连续到达的消息。",
- )
- bridge = FakeBridge(outputs=())
- supervisor = MemoryProcessingSupervisor(
- tasks=tasks,
- profiles=profiles,
- secrets=secrets,
- evidence=evidence,
- governance=governance,
- data_dir=tmp_path,
- runner_factory=lambda: MemoryTaskRunner(
- tasks=tasks,
- profiles=profiles,
- secrets=secrets,
- evidence=evidence,
- governance=governance,
- data_dir=tmp_path,
- bridge_factory=lambda _profile, _secret, _data_dir: bridge,
- ),
- )
-
- async def scenario():
- key = (seed.user_id, seed.source_id, seed.conversation_id, seed.workspace)
- supervisor.enqueue_evidence(seed)
- await asyncio.sleep(0)
- supervisor.enqueue_evidence(seed)
- replacement = supervisor._debounces[key]
- try:
- await asyncio.sleep(0)
- assert supervisor._debounces.get(key) is replacement
- finally:
- replacement.cancel()
- await asyncio.gather(replacement, return_exceptions=True)
- await supervisor.shutdown()
-
- asyncio.run(scenario())
-
-
-def test_workspace_attribution_change_creates_a_new_ingest_task(tmp_path) -> None:
- stores = _setup(tmp_path)
- evidence, profiles, tasks, governance, secrets, profile = stores
- original = _put(
- evidence,
- message_id="workspace-later",
- role="user",
- written_by=WrittenBy.PERSON,
- content="项目里的长期决定。",
- )
- supervisor = MemoryProcessingSupervisor(
- tasks=tasks,
- profiles=profiles,
- secrets=secrets,
- evidence=evidence,
- governance=governance,
- data_dir=tmp_path,
- )
- first = supervisor._enqueue_chunk((original,), profile)
- attributed = _put(
- evidence,
- message_id="workspace-later",
- role="user",
- written_by=WrittenBy.PERSON,
- content="项目里的长期决定。",
- workspace="workspace:v1:project",
- )
- second = supervisor._enqueue_chunk((attributed,), profile)
-
- assert second.task_id != first.task_id
- assert second.request_id != first.request_id
-
-
-def test_debounce_keeps_two_workspaces_with_one_conversation_id_apart(tmp_path) -> None:
- """The later project's arrival must not cancel the earlier project's timer."""
- stores = _setup(tmp_path)
- evidence, profiles, tasks, governance, secrets, _profile = stores
- first = _put(
- evidence,
- message_id="debounce-a",
- role="user",
- written_by=WrittenBy.PERSON,
- content="项目 A 的消息。",
- conversation_id="same-conversation",
- workspace="workspace:v1:project-a",
- )
- second = _put(
- evidence,
- message_id="debounce-b",
- role="user",
- written_by=WrittenBy.PERSON,
- content="项目 B 的消息。",
- conversation_id="same-conversation",
- workspace="workspace:v1:project-b",
- )
- supervisor = MemoryProcessingSupervisor(
- tasks=tasks,
- profiles=profiles,
- secrets=secrets,
- evidence=evidence,
- governance=governance,
- data_dir=tmp_path,
- )
- first_key = (first.user_id, first.source_id, first.conversation_id, first.workspace)
- second_key = (second.user_id, second.source_id, second.conversation_id, second.workspace)
-
- async def scenario():
- supervisor.enqueue_evidence(first)
- await asyncio.sleep(0)
- first_pending = supervisor._debounces[first_key]
- supervisor.enqueue_evidence(second)
- await asyncio.sleep(0)
- try:
- assert supervisor._debounces[first_key] is first_pending
- assert supervisor._debounces[second_key] is not first_pending
- finally:
- await supervisor.shutdown()
-
- asyncio.run(scenario())
-
-
-def test_memory_task_budget_includes_pipeline_overhead() -> None:
- assert memory_task_timeout_seconds(30) == 180
- assert memory_task_timeout_seconds(240) == 300
-
-
-def test_process_records_bounds_a_hung_model_call_by_the_profile_timeout(
- tmp_path, monkeypatch
-) -> None:
- """The direct `process_records` entry must bound one hung task.
-
- The durable drain calls `process_records`, not the scheduler. That entry
- used to call `runner.run(task_id)` with no `timeout`, while the scheduler
- path passed the profile's `timeout_seconds`. A hung model call therefore
- held the single harness slot until the process died, and the drain's lease
- renewal kept extending a job that could never finish.
-
- Here the profile timeout is 1s and the bridge sleeps far longer, so the
- call must come back with `hy_memory_timeout` instead of blocking.
- """
- monkeypatch.setattr("one_memory.memory_processing.MEMORY_TASK_TIMEOUT_MIN_SECONDS", 1.0)
- monkeypatch.setattr("one_memory.memory_processing.MEMORY_TASK_TIMEOUT_MARGIN_SECONDS", 0.0)
- stores = _setup(tmp_path)
- evidence, profiles, tasks, governance, secrets, profile = stores
- record = _put(
- evidence,
- message_id="hang-1",
- role="user",
- written_by=WrittenBy.PERSON,
- content="这个调用会挂住。",
- )
- reply = _put(
- evidence,
- message_id="hang-2",
- role="assistant",
- written_by=WrittenBy.AGENT,
- content="收到。",
- )
- with sqlite3.connect(tmp_path / "one-memory.sqlite3") as db:
- db.executescript(
- """
- CREATE TABLE IF NOT EXISTS source_grants (
- user_id TEXT NOT NULL,
- source_id TEXT NOT NULL,
- root_path TEXT NOT NULL,
- candidate_kind TEXT NOT NULL,
- granted_at TEXT NOT NULL,
- revoked_at TEXT,
- PRIMARY KEY (user_id, source_id)
- );
- """
- )
- db.execute(
- "INSERT INTO source_grants VALUES ('local','cursor','/authorized','default',?,NULL)",
- (datetime.now(UTC).isoformat(),),
- )
-
- service_levels = ServiceLevelScheduler()
-
- class HangingBridge(FakeBridge):
- async def ingest(self, request):
- assert service_levels.should_yield(ServiceResource.IMPORT, ServiceLevel.BACKGROUND)
- await asyncio.sleep(30)
- return await super().ingest(request)
-
- # A 1s ceiling so the test does not wait on the 240s default.
- updated = profiles.update(
- profile.profile_id,
- ModelProfilePatch(expected_revision=profile.revision, timeout_seconds=1),
- secrets,
- )
- profiles.record_capabilities(
- updated.profile_id,
- expected_revision=updated.revision,
- capabilities=ModelCapabilities(
- endpoint_reachable=True,
- model_available=True,
- structured_output=True,
- embedding_available=True,
- ),
- secrets=secrets,
- )
- profile = profiles.activate(updated.profile_id, secrets)
- supervisor = MemoryProcessingSupervisor(
- tasks=tasks,
- profiles=profiles,
- secrets=secrets,
- evidence=evidence,
- governance=governance,
- data_dir=tmp_path,
- runner_factory=lambda: _runner(tmp_path, stores, HangingBridge()),
- service_levels=service_levels,
- )
-
- started = time.monotonic()
- with pytest.raises(HyMemoryBridgeError, match="hy_memory_timeout"):
- asyncio.run(supervisor.process_records((record, reply)))
- elapsed = time.monotonic() - started
- assert elapsed < 10, f"hung call was not bounded by the profile timeout ({elapsed:.1f}s)"
-
-
-def test_authorized_sources_prewarm_write_and_read_bridges_once(tmp_path) -> None:
- stores = _setup(tmp_path)
- evidence, profiles, tasks, governance, secrets, profile = stores
- created = []
-
- class WarmBridge(FakeBridge):
- def __init__(self):
- super().__init__()
- self.warmed = 0
-
- async def warm(self) -> None:
- self.warmed += 1
-
- def factory(*_args):
- bridge = WarmBridge()
- created.append(bridge)
- return bridge
-
- supervisor = MemoryProcessingSupervisor(
- tasks=tasks,
- profiles=profiles,
- secrets=secrets,
- evidence=evidence,
- governance=governance,
- data_dir=tmp_path,
- bridge_factory=factory,
- )
-
- asyncio.run(supervisor._prewarm_write_bridges(("cursor", "workbuddy")))
- write_bridge = supervisor._bridge(profile, None, tmp_path)
- read_bridge = supervisor._read_bridge(profile, None, tmp_path)
- assert created == [write_bridge, read_bridge]
- assert [bridge.warmed for bridge in created] == [1, 1]
-
-
-def test_process_records_does_not_create_a_task_for_a_tool_only_delivery(tmp_path) -> None:
- """A tool event is context for its turn, never a standalone HY turn."""
- stores = _setup(tmp_path)
- evidence, profiles, tasks, governance, secrets, _profile = stores
- tool = _put(
- evidence,
- message_id="tool-only",
- role="tool",
- written_by=WrittenBy.TOOL,
- content="tool output retained as original evidence",
- )
- supervisor = MemoryProcessingSupervisor(
- tasks=tasks,
- profiles=profiles,
- secrets=secrets,
- evidence=evidence,
- governance=governance,
- data_dir=tmp_path,
- )
-
- assert asyncio.run(supervisor.process_records((tool,))) == ()
- assert tasks.list() == []
-
-
-def test_oversized_single_turn_has_persistent_semantic_segments_after_restart(tmp_path) -> None:
- stores = _setup(tmp_path)
- evidence, profiles, tasks, governance, secrets, _profile = stores
- paragraphs = [f"第 {index} 段。" + (chr(65 + index) * 4_500) for index in range(3)]
- original = "\n\n".join(paragraphs)
- record = _put(
- evidence,
- message_id="oversized-segmented",
- role="user",
- written_by=WrittenBy.PERSON,
- content=original,
- )
- _put(
- evidence,
- message_id="oversized-segmented-answer",
- role="assistant",
- written_by=WrittenBy.AGENT,
- content="已收到这份长内容。",
- )
- with sqlite3.connect(tasks.database_path) as connection, connection:
- connection.execute(
- """
- CREATE TABLE source_grants (
- user_id TEXT NOT NULL, source_id TEXT NOT NULL,
- root_path TEXT NOT NULL, candidate_kind TEXT NOT NULL,
- granted_at TEXT NOT NULL, revoked_at TEXT,
- PRIMARY KEY (user_id, source_id)
- )
- """
- )
- connection.execute(
- "INSERT INTO source_grants VALUES (?,?,?,?,?,NULL)",
- (
- record.user_id,
- record.source_id,
- "/authorized",
- "default",
- datetime.now(UTC).isoformat(),
- ),
- )
- supervisor = MemoryProcessingSupervisor(
- tasks=tasks,
- profiles=profiles,
- secrets=secrets,
- evidence=evidence,
- governance=governance,
- data_dir=tmp_path,
- )
-
- prepared = supervisor.prepare_conversation(record)
-
- assert len(prepared) == 2
- assert all(task.status is MemoryTaskStatus.PENDING for task in prepared)
- refs = [tasks.inputs(task.task_id)[0] for task in prepared]
- assert [ref["segment_index"] for ref in refs] == [0, 1]
- assert all(ref["segment_hash"] for ref in refs)
- restarted = MemoryTaskStore(tasks.database_path)
- runner = MemoryTaskRunner(
- tasks=restarted,
- profiles=profiles,
- secrets=secrets,
- evidence=evidence,
- governance=governance,
- data_dir=tmp_path,
- )
- segments = [runner._frozen_chunk(task)[0].verbatim for task in prepared]
- assert "".join(segments) == original
- assert all(len(segment) <= 12_000 for segment in segments)
-
-
-def test_oversized_single_turn_segments_are_each_processed(tmp_path) -> None:
- stores = _setup(tmp_path)
- evidence, profiles, tasks, governance, secrets, _profile = stores
- original = ("第一段内容。" + "甲" * 7_000) + "\n\n" + ("第二段内容。" + "乙" * 7_000)
- record = _put(
- evidence,
- message_id="oversized-run",
- role="user",
- written_by=WrittenBy.PERSON,
- content=original,
- content_kind=EvidenceContentKind.MEMORY_CONTENT,
- )
- with sqlite3.connect(tasks.database_path) as connection, connection:
- connection.execute(
- """
- CREATE TABLE source_grants (
- user_id TEXT NOT NULL, source_id TEXT NOT NULL,
- root_path TEXT NOT NULL, candidate_kind TEXT NOT NULL,
- granted_at TEXT NOT NULL, revoked_at TEXT,
- PRIMARY KEY (user_id, source_id)
- )
- """
- )
- connection.execute(
- "INSERT INTO source_grants VALUES (?,?,?,?,?,NULL)",
- (
- record.user_id,
- record.source_id,
- "/authorized",
- "default",
- datetime.now(UTC).isoformat(),
- ),
- )
-
- class SegmentBridge(FakeBridge):
- async def ingest_extracted(self, request, contents) -> HyMemoryIngestResult:
- self.requests.append(request)
- self.extracted_contents.append(tuple(contents))
- return HyMemoryIngestResult(
- success=True,
- memories=(
- HyMemoryOutput(
- memory_id=f"segment-{len(self.requests)}",
- content=f"第 {len(self.requests)} 段已整理",
- layer="L2_FACT",
- ),
- ),
- )
-
- bridge = SegmentBridge()
- supervisor = MemoryProcessingSupervisor(
- tasks=tasks,
- profiles=profiles,
- secrets=secrets,
- evidence=evidence,
- governance=governance,
- data_dir=tmp_path,
- runner_factory=lambda: _runner(tmp_path, stores, bridge),
- )
-
- completed = asyncio.run(supervisor.process_records((record,)))
-
- assert len(completed) == 2
- assert all(task.status is MemoryTaskStatus.COMPLETED for task in completed)
- sent = [request.turns[0].content for request in bridge.requests]
- assert "".join(sent) == original
- assert len(governance.list(user_id="local")) == 2
-
-
-def test_direct_processing_uses_the_supplied_frozen_revision(tmp_path) -> None:
- stores = _setup(tmp_path)
- evidence, profiles, tasks, governance, secrets, _profile = stores
- old_user = _put(
- evidence,
- message_id="rewound-user",
- role="user",
- written_by=WrittenBy.PERSON,
- content="old branch",
- )
- reply = _put(
- evidence,
- message_id="rewound-reply",
- role="assistant",
- written_by=WrittenBy.AGENT,
- content="old reply",
- )
- revised = _put(
- evidence,
- message_id="rewound-user",
- role="user",
- written_by=WrittenBy.PERSON,
- content="new branch",
- )
- assert revised.evidence_id == old_user.evidence_id
- assert revised.revision == old_user.revision + 1
- with sqlite3.connect(tasks.database_path) as connection, connection:
- connection.execute(
- """
- CREATE TABLE source_grants (
- user_id TEXT NOT NULL,
- source_id TEXT NOT NULL,
- root_path TEXT NOT NULL,
- requested_path TEXT NOT NULL,
- root_identity TEXT NOT NULL,
- candidate_kind TEXT NOT NULL,
- granted_at TEXT NOT NULL,
- revoked_at TEXT,
- revision INTEGER NOT NULL,
- PRIMARY KEY (user_id, source_id)
- )
- """
- )
- connection.execute(
- """
- INSERT INTO source_grants (
- user_id,source_id,root_path,requested_path,root_identity,
- candidate_kind,granted_at,revoked_at,revision
- ) VALUES (?,?,?,?,?,?,?,NULL,1)
- """,
- (
- "local",
- "cursor",
- "/authorized",
- "/authorized",
- "test-root",
- "default",
- datetime.now(UTC).isoformat(),
- ),
- )
- bridge = FakeBridge(outputs=())
- supervisor = MemoryProcessingSupervisor(
- tasks=tasks,
- profiles=profiles,
- secrets=secrets,
- evidence=evidence,
- governance=governance,
- data_dir=tmp_path,
- runner_factory=lambda: _runner(tmp_path, stores, bridge),
- )
-
- completed = asyncio.run(supervisor.process_records((old_user, reply)))
-
- assert len(completed) == 1
- assert [turn.content for turn in bridge.requests[0].turns] == [
- "old branch",
- "old reply",
- ]
-
-
-def test_frozen_current_still_revalidates_history_after_the_model_call(tmp_path) -> None:
- from one_memory.hy_source_context import HySourceContext
-
- stores = _setup(tmp_path)
- evidence, _profiles, tasks, _governance, _secrets, _profile = stores
- current = _put(
- evidence,
- message_id="frozen-current",
- role="user",
- written_by=WrittenBy.PERSON,
- content="old current",
- )
- history = _put(
- evidence,
- message_id="frozen-history",
- role="assistant",
- written_by=WrittenBy.AGENT,
- content="stable history",
- )
- _put(
- evidence,
- message_id="frozen-current",
- role="user",
- written_by=WrittenBy.PERSON,
- content="new current",
- )
- runner = _runner(tmp_path, stores, FakeBridge(outputs=()))
- context = HySourceContext(current=(current,), history=(history,))
-
- runner._check_source_context(context, skip_current=True)
- with sqlite3.connect(tasks.database_path) as connection, connection:
- connection.execute(
- "DELETE FROM evidence WHERE evidence_id=?",
- (history.evidence_id,),
- )
-
- with pytest.raises(HyMemoryBridgeError, match="hy_memory_evidence_changed"):
- runner._check_source_context(context, skip_current=True)
-
-
-def test_oversized_assistant_segments_keep_the_question_as_context(tmp_path) -> None:
- evidence = EvidenceStore(tmp_path / "one-memory.sqlite3")
- question = _put(
- evidence,
- message_id="segment-question",
- role="user",
- written_by=WrittenBy.PERSON,
- content="请整理下面这份很长的方案。",
- )
- answer_text = ("方案第一部分。" + "甲" * 7_000) + "\n\n" + ("方案第二部分。" + "乙" * 7_000)
- answer = _put(
- evidence,
- message_id="segment-answer",
- role="assistant",
- written_by=WrittenBy.AGENT,
- content=answer_text,
- )
-
- chunks = _conversation_chunks([question, answer])
-
- assert len(chunks) == 2
- assert all(chunk[0].evidence_id == question.evidence_id for chunk in chunks)
- assert all(sum(len(record.verbatim) for record in chunk) <= 12_000 for chunk in chunks)
- assert "".join(chunk[-1].verbatim for chunk in chunks) == answer_text
-
-
-def test_semantic_search_uses_a_bridge_independent_from_active_writes(tmp_path) -> None:
- stores = _setup(tmp_path)
- evidence, profiles, tasks, governance, secrets, profile = stores
- made: list[FakeBridge] = []
-
- def factory(_profile, _secret, _data_dir):
- bridge = FakeBridge()
- bridge.search_result_ids = (f"read-{len(made)}",)
- made.append(bridge)
- return bridge
-
- supervisor = MemoryProcessingSupervisor(
- tasks=tasks,
- profiles=profiles,
- secrets=secrets,
- evidence=evidence,
- governance=governance,
- data_dir=tmp_path,
- bridge_factory=factory,
- )
- snapshot = profiles.snapshot(profile.profile_id, profile.revision)
- write_bridge = supervisor._bridge(snapshot, None, tmp_path)
-
- assert asyncio.run(supervisor.semantic_search("独立读取")) == ()
- assert len(made) == 1
-
- asyncio.run(supervisor._prewarm_write_bridges(("cursor",))) # noqa: SLF001
- found = asyncio.run(supervisor.semantic_search("独立读取"))
-
- assert found == (("read-1", 0.9),)
- assert len(made) == 2
- assert supervisor._read_bridges[(profile.profile_id, profile.revision)] is not write_bridge
-
-
-def test_completed_write_refreshes_the_prewarmed_semantic_read_bridge(tmp_path) -> None:
- stores = _setup(tmp_path)
- evidence, profiles, tasks, governance, secrets, profile = stores
- record = _put(
- evidence,
- message_id="semantic-refresh",
- role="user",
- written_by=WrittenBy.PERSON,
- content="用户偏爱蓝莓。",
- )
- answer = _put(
- evidence,
- message_id="semantic-refresh-answer",
- role="assistant",
- written_by=WrittenBy.AGENT,
- content="我记下了。",
- )
- with sqlite3.connect(tasks.database_path) as connection, connection:
- connection.execute(
- """
- CREATE TABLE source_grants (
- user_id TEXT NOT NULL, source_id TEXT NOT NULL,
- root_path TEXT NOT NULL, candidate_kind TEXT NOT NULL,
- granted_at TEXT NOT NULL, revoked_at TEXT,
- PRIMARY KEY (user_id, source_id)
- )
- """
- )
- connection.execute(
- "INSERT INTO source_grants VALUES (?,?,?,?,?,NULL)",
- (
- record.user_id,
- record.source_id,
- "/authorized",
- "default",
- datetime.now(UTC).isoformat(),
- ),
- )
- generation = 0
- made: list[FakeBridge] = []
-
- class SnapshotReadBridge(FakeBridge):
- def __init__(self) -> None:
- super().__init__()
- self.visible_generation = -1
-
- async def warm(self) -> None:
- self.visible_generation = generation
-
- async def search_scores(self, *_args, **_kwargs) -> tuple[object, ...]:
- return (("hy-memory-1", 0.9),) if self.visible_generation >= 1 else ()
-
- class WritingBridge(FakeBridge):
- async def ingest(self, request) -> HyMemoryIngestResult:
- nonlocal generation
- generation += 1
- return await super().ingest(request)
-
- def factory(*_args):
- bridge = SnapshotReadBridge()
- made.append(bridge)
- return bridge
-
- supervisor = MemoryProcessingSupervisor(
- tasks=tasks,
- profiles=profiles,
- secrets=secrets,
- evidence=evidence,
- governance=governance,
- data_dir=tmp_path,
- bridge_factory=factory,
- runner_factory=lambda: _runner(tmp_path, stores, WritingBridge()),
- )
-
- async def exercise() -> None:
- await supervisor._prewarm_write_bridges(("workbuddy",)) # noqa: SLF001
- old_read = supervisor._read_bridges[(profile.profile_id, profile.revision)]
- assert await supervisor.semantic_search("偏爱哪种蓝色小浆果") == ()
-
- completed = await supervisor.process_records((record, answer))
-
- assert completed[0].status is MemoryTaskStatus.COMPLETED
- assert await supervisor.semantic_search("偏爱哪种蓝色小浆果") == (("hy-memory-1", 0.9),)
- assert supervisor._read_bridges[(profile.profile_id, profile.revision)] is not old_read
- assert old_read.closed is True
-
- asyncio.run(exercise())
- assert len(made) == 3
-
-
-def test_failed_semantic_read_refresh_keeps_the_ready_bridge(tmp_path) -> None:
- stores = _setup(tmp_path)
- _evidence, profiles, tasks, governance, secrets, profile = stores
- made: list[FakeBridge] = []
-
- class RefreshBridge(FakeBridge):
- async def warm(self) -> None:
- if len(made) == 3:
- raise RuntimeError("new view is unavailable")
-
- def factory(*_args):
- bridge = RefreshBridge()
- bridge.search_result_ids = (f"read-{len(made)}",)
- made.append(bridge)
- return bridge
-
- supervisor = MemoryProcessingSupervisor(
- tasks=tasks,
- profiles=profiles,
- secrets=secrets,
- evidence=stores[0],
- governance=governance,
- data_dir=tmp_path,
- bridge_factory=factory,
- )
-
- async def exercise() -> None:
- await supervisor._prewarm_write_bridges(("workbuddy",)) # noqa: SLF001
- old_read = supervisor._read_bridges[(profile.profile_id, profile.revision)]
-
- await supervisor._refresh_read_bridge(profile) # noqa: SLF001
-
- assert supervisor._read_bridges[(profile.profile_id, profile.revision)] is old_read
- assert await supervisor.semantic_search("偏爱哪种蓝色小浆果") == (("read-1", 0.9),)
- assert old_read.closed is False
- assert made[-1].closed is True
-
- asyncio.run(exercise())
-
-
-def test_background_read_refresh_coalesces_a_write_burst(tmp_path, monkeypatch) -> None:
- stores = _setup(tmp_path)
- _evidence, profiles, tasks, governance, secrets, profile = stores
- made: list[FakeBridge] = []
-
- def factory(*_args):
- bridge = FakeBridge()
- made.append(bridge)
- return bridge
-
- supervisor = MemoryProcessingSupervisor(
- tasks=tasks,
- profiles=profiles,
- secrets=secrets,
- evidence=stores[0],
- governance=governance,
- data_dir=tmp_path,
- bridge_factory=factory,
- )
- monkeypatch.setattr(
- "one_memory.memory_processing._READ_BRIDGE_FIRST_REFRESH_DELAY_SECONDS", 0.01
- )
-
- async def exercise() -> None:
- await supervisor._prewarm_write_bridges(("workbuddy",)) # noqa: SLF001
- for _ in range(20):
- supervisor._request_read_bridge_refresh(profile) # noqa: SLF001
- await asyncio.sleep(0.05)
-
- assert supervisor._read_bridge_generations[(profile.profile_id, profile.revision)] == 1
- assert len(made) == 3
- assert sum(bridge.closed for bridge in made) == 1
- await supervisor.shutdown()
-
- asyncio.run(exercise())
-
-
-def test_background_read_refresh_does_not_rebuild_for_later_writes(tmp_path, monkeypatch) -> None:
- stores = _setup(tmp_path)
- _evidence, profiles, tasks, governance, secrets, profile = stores
- collection_generation = 0
- made: list[FakeBridge] = []
-
- class PersistentCollectionBridge(FakeBridge):
- def __init__(self) -> None:
- super().__init__()
- self.collection_attached = False
-
- async def warm(self) -> None:
- self.collection_attached = collection_generation > 0
-
- async def search_scores(self, *_args, **_kwargs) -> tuple[object, ...]:
- if not self.collection_attached:
- return ()
- return ((f"memory-{collection_generation}", 0.9),)
-
- def factory(*_args):
- bridge = PersistentCollectionBridge()
- made.append(bridge)
- return bridge
-
- supervisor = MemoryProcessingSupervisor(
- tasks=tasks,
- profiles=profiles,
- secrets=secrets,
- evidence=stores[0],
- governance=governance,
- data_dir=tmp_path,
- bridge_factory=factory,
- )
- monkeypatch.setattr(
- "one_memory.memory_processing._READ_BRIDGE_FIRST_REFRESH_DELAY_SECONDS", 0.01
- )
-
- async def exercise() -> None:
- nonlocal collection_generation
- await supervisor._prewarm_write_bridges(("workbuddy",)) # noqa: SLF001
- assert await supervisor.semantic_search("首次写入") == ()
- collection_generation = 1
- supervisor._request_read_bridge_refresh(profile) # noqa: SLF001
- await asyncio.sleep(0.05)
- assert await supervisor.semantic_search("首次写入") == (("memory-1", 0.9),)
- collection_generation = 2
- for _ in range(20):
- supervisor._request_read_bridge_refresh(profile) # noqa: SLF001
- await asyncio.sleep(0.05)
-
- assert supervisor._read_bridge_generations[(profile.profile_id, profile.revision)] == 1
- assert len(made) == 3
- assert await supervisor.semantic_search("后续写入") == (("memory-2", 0.9),)
- await supervisor.shutdown()
-
- asyncio.run(exercise())
-
-
-def test_unknown_task_is_reconciled_from_exact_hy_output_without_model_retry(tmp_path) -> None:
- stores = _setup(tmp_path)
- evidence, profiles, tasks, governance, secrets, profile = stores
- record = _put(
- evidence,
- message_id="unknown-reconcile",
- role="user",
- written_by=WrittenBy.PERSON,
- content="用户偏好每周日上午攀岩。",
- )
- task = tasks.create(
- request_id="unknown-reconcile-request",
- user_id=record.user_id,
- kind=MemoryTaskKind.EXTRACT,
- input_ref=record.evidence_id,
- profile=profile,
- input_records=(record,),
- )
- with sqlite3.connect(tasks.database_path) as connection, connection:
- connection.execute(
- """
- CREATE TABLE source_grants (
- user_id TEXT NOT NULL, source_id TEXT NOT NULL,
- root_path TEXT NOT NULL, candidate_kind TEXT NOT NULL,
- granted_at TEXT NOT NULL, revoked_at TEXT,
- PRIMARY KEY (user_id, source_id)
- )
- """
- )
- connection.execute(
- "INSERT INTO source_grants VALUES (?,?,?,?,?,NULL)",
- (
- record.user_id,
- record.source_id,
- "/authorized",
- "default",
- datetime.now(UTC).isoformat(),
- ),
- )
- connection.execute(
- "UPDATE memory_tasks SET status='unknown', last_error_code=? WHERE task_id=?",
- ("model_content_outcome_unknown", task.task_id),
- )
- bridge = FakeBridge(
- outputs=(
- HyMemoryOutput(
- memory_id="hy-recovered",
- content="用户偏好每周日上午攀岩。",
- layer="L2_FACT",
- owner="user",
- evidence_ids=(record.evidence_id,),
- ),
- )
- )
- supervisor = MemoryProcessingSupervisor(
- tasks=tasks,
- profiles=profiles,
- secrets=secrets,
- evidence=evidence,
- governance=governance,
- data_dir=tmp_path,
- runner_factory=lambda: _runner(tmp_path, stores, FakeBridge()),
- bridge_factory=lambda _profile, _secret, _data_dir: bridge,
- )
-
- assert asyncio.run(supervisor.reconcile_unknown_outputs()) == 1
- assert tasks.require(task.task_id).status is MemoryTaskStatus.COMPLETED
- assert [memory.memory_id for memory in governance.list(user_id="local")] == ["hy-recovered"]
- assert bridge.closed is True
-
-
-def test_an_unknown_task_without_inputs_does_not_end_the_reconcile_pass(tmp_path) -> None:
- """One task with nothing to send must not strand the other unknown tasks.
-
- An unknown task whose inputs are gone yields an empty chunk, and building a
- request from that reached `chunk[0]` and came out as IndexError. A
- reconcile pass skips a task that raises a domain error, so IndexError did
- not skip anything -- it ended the pass. On this machine 68 of 303 unknown
- tasks had no inputs, and while the retry backed off to 128 and gave up, the
- 235 that could have been reconciled stayed unknown with them.
- """
- stores = _setup(tmp_path)
- evidence, profiles, tasks, governance, secrets, profile = stores
- stranded = _put(
- evidence,
- message_id="reconcile-without-inputs",
- role="user",
- written_by=WrittenBy.PERSON,
- content="这条任务的输入已经不在了。",
- )
- record = _put(
- evidence,
- message_id="reconcile-with-inputs",
- role="user",
- written_by=WrittenBy.PERSON,
- content="用户偏好每周日上午攀岩。",
- )
- empty = tasks.create(
- request_id="reconcile-empty-request",
- user_id=stranded.user_id,
- kind=MemoryTaskKind.EXTRACT,
- input_ref=stranded.evidence_id,
- profile=profile,
- input_records=(stranded,),
- )
- task = tasks.create(
- request_id="reconcile-kept-request",
- user_id=record.user_id,
- kind=MemoryTaskKind.EXTRACT,
- input_ref=record.evidence_id,
- profile=profile,
- input_records=(record,),
- )
- with sqlite3.connect(tasks.database_path) as connection, connection:
- connection.execute(
- """
- CREATE TABLE source_grants (
- user_id TEXT NOT NULL, source_id TEXT NOT NULL,
- root_path TEXT NOT NULL, candidate_kind TEXT NOT NULL,
- granted_at TEXT NOT NULL, revoked_at TEXT,
- PRIMARY KEY (user_id, source_id)
- )
- """
- )
- connection.execute(
- "INSERT INTO source_grants VALUES (?,?,?,?,?,NULL)",
- (
- record.user_id,
- record.source_id,
- "/authorized",
- "default",
- datetime.now(UTC).isoformat(),
- ),
- )
- for task_id in (empty.task_id, task.task_id):
- connection.execute(
- "UPDATE memory_tasks SET status='unknown', last_error_code=? WHERE task_id=?",
- ("model_content_outcome_unknown", task_id),
- )
- # What the field data actually looks like: the task is there, its
- # inputs are not.
- connection.execute("DELETE FROM memory_task_inputs WHERE task_id=?", (empty.task_id,))
- bridge = FakeBridge(
- outputs=(
- HyMemoryOutput(
- memory_id="hy-recovered",
- content="用户偏好每周日上午攀岩。",
- layer="L2_FACT",
- owner="user",
- evidence_ids=(record.evidence_id,),
- ),
- )
- )
- supervisor = MemoryProcessingSupervisor(
- tasks=tasks,
- profiles=profiles,
- secrets=secrets,
- evidence=evidence,
- governance=governance,
- data_dir=tmp_path,
- runner_factory=lambda: _runner(tmp_path, stores, FakeBridge()),
- bridge_factory=lambda _profile, _secret, _data_dir: bridge,
- )
-
- # The task with inputs is reconciled; the one without is passed over.
- assert asyncio.run(supervisor.reconcile_unknown_outputs()) == 1
- assert tasks.require(task.task_id).status is MemoryTaskStatus.COMPLETED
- assert [memory.memory_id for memory in governance.list(user_id="local")] == ["hy-recovered"]
-
-
-def test_sticky_authority_unknowns_do_not_starve_ordinary_reconciliation(tmp_path) -> None:
- stores = _setup(tmp_path)
- evidence, profiles, tasks, governance, secrets, profile = stores
- record = _put(
- evidence,
- message_id="fair-unknown",
- role="user",
- written_by=WrittenBy.PERSON,
- content="ordinary unknown remains reconcilable",
- )
- sticky = [
- tasks.create(
- request_id=f"sticky-authority-{index}",
- user_id=record.user_id,
- kind=MemoryTaskKind.EXTRACT,
- input_ref=record.evidence_id,
- profile=profile,
- input_records=(record,),
- )
- for index in range(129)
- ]
- ordinary = tasks.create(
- request_id="ordinary-unknown-after-sticky",
- user_id=record.user_id,
- kind=MemoryTaskKind.EXTRACT,
- input_ref=record.evidence_id,
- profile=profile,
- input_records=(record,),
- )
- anchor = datetime(2026, 1, 1, tzinfo=UTC)
- with sqlite3.connect(tasks.database_path) as connection, connection:
- connection.executescript(
- """
- CREATE TABLE source_grants (
- user_id TEXT NOT NULL, source_id TEXT NOT NULL,
- root_path TEXT NOT NULL, candidate_kind TEXT NOT NULL,
- granted_at TEXT NOT NULL, revoked_at TEXT,
- PRIMARY KEY (user_id, source_id)
- );
- """
- )
- connection.execute(
- "INSERT INTO source_grants VALUES (?,?,?,?,?,NULL)",
- (
- record.user_id,
- record.source_id,
- "/authorized",
- "default",
- datetime.now(UTC).isoformat(),
- ),
- )
- for index, task in enumerate(sticky):
- connection.execute(
- "UPDATE memory_tasks SET status='unknown',last_error_code=?,updated_at=? "
- "WHERE task_id=?",
- (
- "hy_memory_write_verification_authority_invalid",
- (anchor + timedelta(seconds=index)).isoformat(),
- task.task_id,
- ),
- )
- connection.execute(
- "UPDATE memory_tasks SET status='unknown',last_error_code=?,updated_at=? "
- "WHERE task_id=?",
- (
- "model_content_outcome_unknown",
- (anchor + timedelta(minutes=3)).isoformat(),
- ordinary.task_id,
- ),
- )
-
- class InquiryOnlyBridge(FakeBridge):
- def __init__(self) -> None:
- super().__init__(
- outputs=(
- HyMemoryOutput(
- memory_id="ordinary-recovered",
- content="ordinary unknown remains reconcilable",
- layer="L2_FACT",
- owner="user",
- evidence_ids=(record.evidence_id,),
- ),
- )
- )
- self.inquiries: list[str] = []
-
- async def outputs_for_request(self, **kwargs) -> tuple[HyMemoryOutput, ...]:
- self.inquiries.append(str(kwargs["request_id"]))
- return self.outputs or ()
-
- bridge = InquiryOnlyBridge()
- supervisor = MemoryProcessingSupervisor(
- tasks=tasks,
- profiles=profiles,
- secrets=secrets,
- evidence=evidence,
- governance=governance,
- data_dir=tmp_path,
- runner_factory=lambda: _runner(tmp_path, stores, FakeBridge()),
- bridge_factory=lambda _profile, _secret, _data_dir: bridge,
- )
-
- assert (
- asyncio.run(
- supervisor.reconcile_unknown_outputs(
- limit=128,
- exclude_error_codes=NON_RETRYABLE_POST_WRITE_CODES,
- )
- )
- == 1
- )
- assert bridge.inquiries == ["ordinary-unknown-after-sticky"]
- assert bridge.requests == []
- assert tasks.require(ordinary.task_id).status is MemoryTaskStatus.COMPLETED
- assert all(tasks.require(task.task_id).status is MemoryTaskStatus.UNKNOWN for task in sticky)
-
-
-def test_two_workspaces_with_one_conversation_id_prepare_apart(tmp_path) -> None:
- """Cursor can reuse a conversation id across projects.
-
- `process_records` and the live debounce key must carry workspace with the
- source/conversation identity. Without it, two project copies collapse into
- one model input and the later arrival cancels the earlier project's timer.
- """
- stores = _setup(tmp_path)
- evidence, profiles, tasks, governance, secrets, profile = stores
- first_user = _put(
- evidence,
- message_id="same-user",
- role="user",
- written_by=WrittenBy.PERSON,
- content="项目 A 的决定。",
- conversation_id="same-conversation",
- workspace="workspace:v1:project-a",
- )
- first_reply = _put(
- evidence,
- message_id="same-reply",
- role="assistant",
- written_by=WrittenBy.AGENT,
- content="项目 A 已记录。",
- conversation_id="same-conversation",
- workspace="workspace:v1:project-a",
- )
- second_user = _put(
- evidence,
- message_id="second-user",
- role="user",
- written_by=WrittenBy.PERSON,
- content="项目 B 的决定。",
- conversation_id="same-conversation",
- workspace="workspace:v1:project-b",
- )
- second_reply = _put(
- evidence,
- message_id="second-reply",
- role="assistant",
- written_by=WrittenBy.AGENT,
- content="项目 B 已记录。",
- conversation_id="same-conversation",
- workspace="workspace:v1:project-b",
- )
- with sqlite3.connect(tmp_path / "one-memory.sqlite3") as db:
- db.executescript(
- """
- CREATE TABLE source_grants (
- user_id TEXT NOT NULL,
- source_id TEXT NOT NULL,
- root_path TEXT NOT NULL,
- candidate_kind TEXT NOT NULL,
- granted_at TEXT NOT NULL,
- revoked_at TEXT,
- PRIMARY KEY (user_id, source_id)
- );
- """
- )
- db.execute(
- "INSERT INTO source_grants VALUES ('local','cursor','/authorized','default',?,NULL)",
- (datetime.now(UTC).isoformat(),),
- )
- bridge = FakeBridge(outputs=())
- supervisor = MemoryProcessingSupervisor(
- tasks=tasks,
- profiles=profiles,
- secrets=secrets,
- evidence=evidence,
- governance=governance,
- data_dir=tmp_path,
- runner_factory=lambda: _runner(tmp_path, stores, bridge),
- )
-
- created = asyncio.run(
- supervisor.process_records((first_user, first_reply, second_user, second_reply))
- )
- for task in created:
- assert task.status is MemoryTaskStatus.COMPLETED
-
- assert len(created) == 2
- assert {
- tuple(record.evidence_id for record in request.source_context.current)
- for request in bridge.requests
- if request.source_context is not None
- } == {
- (first_user.evidence_id, first_reply.evidence_id),
- (second_user.evidence_id, second_reply.evidence_id),
- }
-
-
-def _growing_conversation(tmp_path):
- stores = _setup(tmp_path)
- evidence, profiles, tasks, governance, secrets, profile = stores
- ask = _put(
- evidence,
- message_id="ask",
- role="user",
- written_by=WrittenBy.PERSON,
- content="记住这个决定。",
- )
- first_reply = _put(
- evidence,
- message_id="reply-1",
- role="assistant",
- written_by=WrittenBy.AGENT,
- content="好的,第一步。",
- )
- second_reply = _put(
- evidence,
- message_id="reply-2",
- role="assistant",
- written_by=WrittenBy.AGENT,
- content="第二步完成。",
- )
- supervisor = MemoryProcessingSupervisor(
- tasks=tasks,
- profiles=profiles,
- secrets=secrets,
- evidence=evidence,
- governance=governance,
- data_dir=tmp_path,
- )
- return supervisor, tasks, profile, ask, first_reply, second_reply
-
-
-def test_a_grown_chunk_retires_the_unstarted_task_for_the_same_turn(tmp_path) -> None:
- supervisor, tasks, profile, ask, first_reply, second_reply = _growing_conversation(tmp_path)
-
- shorter = supervisor._enqueue_chunk((ask, first_reply), profile, freeze_inputs=True)
- longer = supervisor._enqueue_chunk(
- (ask, first_reply, second_reply), profile, freeze_inputs=True
- )
-
- assert longer.task_id != shorter.task_id
- retired = tasks.require(shorter.task_id)
- assert retired.status is MemoryTaskStatus.CANCELLED
- assert retired.last_error_code == "superseded_by_longer_chunk"
- assert tasks.require(longer.task_id).status is MemoryTaskStatus.PENDING
-
-
[email protected]("operation", ["history", "sync"])
-def test_import_waits_for_the_file_boundary_before_queuing_a_turn(tmp_path, operation) -> None:
- stores = _setup(tmp_path)
- evidence, profiles, tasks, governance, secrets, _profile = stores
- jobs = ImportJobStore(evidence.database_path)
- supervisor = MemoryProcessingSupervisor(
- tasks=tasks,
- profiles=profiles,
- secrets=secrets,
- evidence=evidence,
- governance=governance,
- data_dir=tmp_path,
- )
- file_key = "f" * 64
-
- def scan_cursor(checkpoint: str, *, read_to_end: bool = False) -> SourceCursor:
- return SourceCursor(
- file_key=file_key,
- file_identity="fixture:1",
- checkpoint=checkpoint,
- observed_size=200,
- observed_modified_ns=1,
- read_to_end=read_to_end,
- )
-
- class Adapter:
- descriptor = SourceDescriptor(
- source_id="cursor",
- display_name="Cursor",
- storage_kinds=frozenset({StorageKind.JSONL}),
- capabilities=SourceCapabilities(
- can_append=True,
- can_observe_edits=True,
- can_observe_deletes=False,
- can_reconcile_complete_set=False,
- ),
- )
-
- def __init__(self, events) -> None:
- self.events = events
-
- async def scan(self, _options):
- for event in self.events:
- yield event
-
- user = EvidenceInput(
- source_id="cursor",
- conversation_id="stable-turn",
- message_id="user-1",
- role="user",
- written_by=WrittenBy.PERSON,
- verbatim="把完整一轮对话沉淀成记忆。",
- origin_meta={EvidenceOrigin.FILE: OriginMetadata(raw_meta={"file_key": file_key})},
- )
- assistant = EvidenceInput(
- source_id="cursor",
- conversation_id="stable-turn",
- message_id="assistant-1",
- role="assistant",
- written_by=WrittenBy.AGENT,
- verbatim="会等到回答完整后再开始。",
- origin_meta={EvidenceOrigin.FILE: OriginMetadata(raw_meta={"file_key": file_key})},
- )
-
- async def import_in_two_slices() -> None:
- job = jobs.create(user_id="local", source_id="cursor", operation=operation)
- first = await ImportRunner(
- evidence_store=evidence,
- job_store=jobs,
- on_stable_evidence=supervisor.enqueue_evidence,
- ).run(
- adapter=Adapter([ScannedEvidence(evidence=user, cursor=scan_cursor("byte:1"))]),
- job_id=job.job_id,
- max_work_events=1,
- )
- assert first.status is ImportStatus.PENDING
- # Wait beyond the live settle budget. A timer alone must not turn an
- # unanswered user message into a complete HY task.
- await asyncio.sleep(1.7)
- assert tasks.list() == []
-
- completed = await ImportRunner(
- evidence_store=evidence,
- job_store=jobs,
- on_stable_evidence=supervisor.enqueue_evidence,
- ).run(
- adapter=Adapter(
- [
- ScannedEvidence(evidence=assistant, cursor=scan_cursor("byte:2")),
- ScanCursorTouch(cursor=scan_cursor("byte:2", read_to_end=True)),
- ]
- ),
- job_id=job.job_id,
- )
- assert completed.status is ImportStatus.COMPLETED
- await asyncio.sleep(0.9)
-
- asyncio.run(import_in_two_slices())
-
- queued = tasks.list()
- assert len(queued) == 1
- conversation = evidence.list_conversation(queued[0].input_ref)
- assert [record.verbatim for record in conversation] == [user.verbatim, assistant.verbatim]
- assert all(task.last_error_code != "superseded_by_longer_chunk" for task in queued)
-
-
-def test_live_import_waits_for_an_open_user_turn_to_receive_its_reply(
- tmp_path, monkeypatch
-) -> None:
- import one_memory.memory_processing as processing
-
- monkeypatch.setattr(processing, "_LIVE_OPEN_TURN_SETTLE_SECONDS", 1.5)
- stores = _setup(tmp_path)
- evidence, profiles, tasks, governance, secrets, _profile = stores
- jobs = ImportJobStore(evidence.database_path)
- supervisor = MemoryProcessingSupervisor(
- tasks=tasks,
- profiles=profiles,
- secrets=secrets,
- evidence=evidence,
- governance=governance,
- data_dir=tmp_path,
- )
- file_key = "l" * 64
-
- def event(message_id: str, role: str, content: str, checkpoint: str):
- written_by = WrittenBy.PERSON if role == "user" else WrittenBy.AGENT
- cursor = SourceCursor(
- file_key=file_key,
- file_identity="fixture:live",
- checkpoint=checkpoint,
- observed_size=200,
- observed_modified_ns=1,
- )
- return ScannedEvidence(
- evidence=EvidenceInput(
- source_id="cursor",
- conversation_id="live-turn",
- message_id=message_id,
- role=role,
- written_by=written_by,
- created_at=datetime.now(UTC),
- verbatim=content,
- origin_meta={EvidenceOrigin.FILE: OriginMetadata(raw_meta={"file_key": file_key})},
- ),
- cursor=cursor,
- )
-
- class Adapter:
- descriptor = SourceDescriptor(
- source_id="cursor",
- display_name="Cursor",
- storage_kinds=frozenset({StorageKind.JSONL}),
- capabilities=SourceCapabilities(
- can_append=True,
- can_observe_edits=True,
- can_observe_deletes=False,
- can_reconcile_complete_set=False,
- ),
- )
-
- def __init__(self, scanned) -> None:
- self.scanned = scanned
-
- async def scan(self, _options):
- yield self.scanned
- yield ScanCursorTouch(
- cursor=self.scanned.cursor.model_copy(update={"read_to_end": True})
- )
-
- async def run_live_updates() -> None:
- dispatched = []
-
- def dispatch(record):
- dispatched.append((record.role, live_sync_arrival.get()))
- return supervisor.enqueue_evidence(record)
-
- for scanned in (
- event("user", "user", "先等我这轮回答完整。", "byte:1"),
- event("assistant", "assistant", "现在这一轮完整了。", "byte:2"),
- ):
- job = jobs.create(user_id="local", source_id="cursor", operation="sync")
- completed = await ImportRunner(
- evidence_store=evidence,
- job_store=jobs,
- on_stable_evidence=dispatch,
- ).run(adapter=Adapter(scanned), job_id=job.job_id)
- assert completed.status is ImportStatus.COMPLETED
- await asyncio.sleep(0.9)
- if scanned.evidence.role == "user":
- assert tasks.list() == []
-
- await asyncio.gather(*tuple(supervisor._debounces.values()))
- deadline = asyncio.get_running_loop().time() + 2
- while not tasks.list() and asyncio.get_running_loop().time() < deadline:
- await asyncio.sleep(0.01)
- assert dispatched == [("user", True), ("assistant", True)]
-
- asyncio.run(run_live_updates())
-
- queued = tasks.list()
- assert len(queued) == 1
- assert all(task.last_error_code != "superseded_by_longer_chunk" for task in queued)
-
-
-def test_preview_empty_is_the_open_turn_contract_not_a_preview_regression(tmp_path) -> None:
- """An open realtime user turn returns no task until the reply closes it.
-
- This is the C2 side of `[BLOCK C1 -> C2] preview-empty-on-c0`: the import
- fixture stops after the third user record, so a live debounce still holds
- this conversation open. The permission preview sees no task because there
- is no complete turn yet, not because the preview lost Evidence. Clearing
- the debounce after the assistant reply must produce the task.
- """
- stores = _setup(tmp_path)
- evidence, profiles, tasks, governance, secrets, _profile = stores
- user = _put(
- evidence,
- message_id="open-user",
- role="user",
- written_by=WrittenBy.PERSON,
- content="先记下这个计划。",
- )
- supervisor = MemoryProcessingSupervisor(
- tasks=tasks,
- profiles=profiles,
- secrets=secrets,
- evidence=evidence,
- governance=governance,
- data_dir=tmp_path,
- )
- key = (user.user_id, user.source_id, user.conversation_id, user.workspace)
-
- async def scenario() -> None:
- supervisor._debounces[key] = asyncio.create_task(asyncio.sleep(60))
- try:
- assert supervisor.prepare_conversation(user, live=True) == []
- finally:
- supervisor._debounces.pop(key).cancel()
- assistant = _put(
- evidence,
- message_id="closing-assistant",
- role="assistant",
- written_by=WrittenBy.AGENT,
- content="收到,计划已记下。",
- )
- created = supervisor.prepare_conversation(assistant)
- assert len(created) == 1
- assert created[0].input_ref == user.evidence_id
- await supervisor.shutdown()
-
- asyncio.run(scenario())
-
-
-def test_digest_skips_scopes_whose_source_write_permission_is_withdrawn(tmp_path) -> None:
- """A revoked source must not keep feeding System 2.
-
- Revocation is the user withdrawing the source. New extraction already
- refuses it through `source_writes_permitted`; digest must use the same
- boundary before it lists HY scopes, or it summarises material the user
- withdrew. This pins the C2-owned half of the C3 revoked-digest red state.
- """
- stores = _setup(tmp_path)
- evidence, profiles, tasks, governance, secrets, profile = stores
- record = _put(
- evidence,
- message_id="revoked-scope",
- role="user",
- written_by=WrittenBy.PERSON,
- content="项目范围内的事实。",
- conversation_id="revoked-conversation",
- workspace="workspace:v1:project",
- )
- _confirmed_from(governance, record.evidence_id)
- bridge = FakeBridge(outputs=())
- supervisor = MemoryProcessingSupervisor(
- tasks=tasks,
- profiles=profiles,
- secrets=secrets,
- evidence=evidence,
- governance=governance,
- data_dir=tmp_path,
- source_writes_permitted=lambda _source_id: False,
- )
- supervisor._bridges[(profile.profile_id, profile.revision, None)] = bridge
-
- result = asyncio.run(supervisor.digest())
-
- assert result["scope_count"] == 0
- assert result["digests"] == []
- assert bridge.digest_calls == []
-
-
-def test_digest_rechecks_revoked_source_after_the_supervisor_is_open(tmp_path) -> None:
- """The real grant revocation path must feed the same digest boundary.
-
- This mirrors C3's executable red state: create the scope, open the
- supervisor while the source is allowed, revoke the grant, then digest.
- Reading the callback at target-selection time (not once in the
- constructor) is what keeps the revoked scope out.
- """
- stores = _setup(tmp_path)
- evidence, profiles, tasks, governance, secrets, profile = stores
- database = tmp_path / "one-memory.sqlite3"
- grants = SourceGrantStore(database, home=tmp_path)
- folder = tmp_path / "cursor-root"
- folder.mkdir()
- grants.grant(
- user_id="local",
- source_id="cursor",
- root=folder,
- candidate_kind=RootCandidateKind.DEFAULT,
- )
- config = ConfigStore(tmp_path)
- config.set_sync("cursor", True)
- record = _put(
- evidence,
- message_id="real-revoked-scope",
- role="user",
- written_by=WrittenBy.PERSON,
- content="撤销之后不应再进入 digest。",
- conversation_id="real-revoked-conversation",
- workspace="workspace:v1:project",
- )
- _confirmed_from(governance, record.evidence_id)
- bridge = FakeBridge(outputs=())
- supervisor = MemoryProcessingSupervisor(
- tasks=tasks,
- profiles=profiles,
- secrets=secrets,
- evidence=evidence,
- governance=governance,
- data_dir=tmp_path,
- source_writes_permitted=lambda source_id: (
- config.sync_enabled(source_id)
- and grants.authorized_root(user_id="local", source_id=source_id) is not None
- ),
- )
- supervisor._bridges[(profile.profile_id, profile.revision, None)] = bridge
- grants.revoke(user_id="local", source_id="cursor")
-
- result = asyncio.run(supervisor.digest())
-
- assert result["scope_count"] == 0
- assert bridge.digest_calls == []
-
-
-def test_frozen_harness_refuses_new_processing_before_a_task_or_model_call(tmp_path) -> None:
- """A frozen Harness must not create new processing work or call HY.
-
- The backfill guard covered only the history scan. The production durable
- drain and live enqueue call other supervisor entries, so this drives the
- real `SourceGrantStore` policy through all of them: direct processing,
- backfill, live preparation and digest. The only permitted side effect is
- the Evidence already committed by the source import.
- """
- stores = _setup(tmp_path)
- evidence, profiles, tasks, governance, secrets, profile = stores
- database = tmp_path / "one-memory.sqlite3"
- grants = SourceGrantStore(database, home=tmp_path)
- root = tmp_path / "cursor-root"
- root.mkdir()
- granted = grants.grant(
- user_id="local",
- source_id="cursor",
- root=root,
- candidate_kind=RootCandidateKind.DEFAULT,
- )
- user = _put(
- evidence,
- message_id="frozen-user",
- role="user",
- written_by=WrittenBy.PERSON,
- content="Harness Freeze 后不能创建新的记忆任务。",
- conversation_id="frozen-conversation",
- workspace="workspace:v1:project",
- )
- reply = _put(
- evidence,
- message_id="frozen-reply",
- role="assistant",
- written_by=WrittenBy.AGENT,
- content="收到。",
- conversation_id="frozen-conversation",
- workspace="workspace:v1:project",
- )
- _confirmed_from(governance, user.evidence_id)
- evidence_before = evidence.count()
- governed_before = len(governance.list(user_id="local"))
-
- config = ConfigStore(tmp_path)
- assert not config.sync_enabled("cursor")
- assert granted.revoked_at is None
-
- def source_may_write(source_id: str) -> bool:
- return config.sync_enabled(source_id) and (
- grants.authorized_root(user_id="local", source_id=source_id) is not None
- )
-
- bridge = FakeBridge(outputs=())
- supervisor = MemoryProcessingSupervisor(
- tasks=tasks,
- profiles=profiles,
- secrets=secrets,
- evidence=evidence,
- governance=governance,
- data_dir=tmp_path,
- source_writes_permitted=source_may_write,
- )
- supervisor._bridges[(profile.profile_id, profile.revision, None)] = bridge
-
- assert supervisor._source_may_write([user]) is False
- with pytest.raises(HyMemoryBridgeError, match="hy_memory_source_disabled"):
- asyncio.run(supervisor.process_records((user, reply)))
- assert asyncio.run(supervisor.enqueue_conversation_off_thread(user)) == []
- assert supervisor.prepare_backfill() == []
- assert supervisor.prepare_conversation(user) == []
- digest = asyncio.run(supervisor.digest())
-
- assert tasks.list() == []
- assert bridge.requests == []
- assert bridge.extracted_contents == []
- assert bridge.digest_calls == []
- assert len(governance.list(user_id="local")) == governed_before
- assert evidence.count() == evidence_before
- assert digest["scope_count"] == 0
-
-
-def test_revoked_grant_refuses_new_processing(tmp_path) -> None:
- """Revocation is stronger than Freeze and also refuses new work."""
- stores = _setup(tmp_path)
- evidence, profiles, tasks, governance, secrets, profile = stores
- database = tmp_path / "one-memory.sqlite3"
- grants = SourceGrantStore(database, home=tmp_path)
- root = tmp_path / "cursor-root"
- root.mkdir()
- grants.grant(
- user_id="local",
- source_id="cursor",
- root=root,
- candidate_kind=RootCandidateKind.DEFAULT,
- )
- config = ConfigStore(tmp_path)
- config.set_sync("cursor", True)
- user = _put(
- evidence,
- message_id="revoked-user",
- role="user",
- written_by=WrittenBy.PERSON,
- content="撤销后不能进入记忆。",
- conversation_id="revoked-conversation",
- workspace="workspace:v1:project",
- )
- reply = _put(
- evidence,
- message_id="revoked-reply",
- role="assistant",
- written_by=WrittenBy.AGENT,
- content="收到。",
- conversation_id="revoked-conversation",
- workspace="workspace:v1:project",
- )
- _confirmed_from(governance, user.evidence_id)
- evidence_before = evidence.count()
- governed_before = len(governance.list(user_id="local"))
-
- revoked = grants.revoke(user_id="local", source_id="cursor")
- assert revoked.revoked_at is not None
- assert grants.authorized_root(user_id="local", source_id="cursor") is None
-
- bridge = FakeBridge(outputs=())
- supervisor = MemoryProcessingSupervisor(
- tasks=tasks,
- profiles=profiles,
- secrets=secrets,
- evidence=evidence,
- governance=governance,
- data_dir=tmp_path,
- source_writes_permitted=lambda source_id: (
- config.sync_enabled(source_id)
- and grants.authorized_root(user_id="local", source_id=source_id) is not None
- ),
- )
- supervisor._bridges[(profile.profile_id, profile.revision, None)] = bridge
-
- assert supervisor._source_may_write([user]) is False
- with pytest.raises(HyMemoryBridgeError, match="hy_memory_source_disabled"):
- asyncio.run(supervisor.process_records((user, reply)))
- assert asyncio.run(supervisor.enqueue_conversation_off_thread(user)) == []
- assert supervisor.prepare_backfill() == []
- assert supervisor.prepare_conversation(user) == []
- digest = asyncio.run(supervisor.digest())
-
- assert tasks.list() == []
- assert bridge.requests == []
- assert bridge.extracted_contents == []
- assert bridge.digest_calls == []
- assert len(governance.list(user_id="local")) == governed_before
- assert evidence.count() == evidence_before
- assert digest["scope_count"] == 0
-
-
-def test_thawed_harness_processes_a_complete_turn(tmp_path) -> None:
- """Positive control: the same complete turn runs after Thaw."""
- stores = _setup(tmp_path)
- evidence, profiles, tasks, governance, secrets, profile = stores
- database = tmp_path / "one-memory.sqlite3"
- grants = SourceGrantStore(database, home=tmp_path)
- root = tmp_path / "cursor-root"
- root.mkdir()
- grants.grant(
- user_id="local",
- source_id="cursor",
- root=root,
- candidate_kind=RootCandidateKind.DEFAULT,
- )
- config = ConfigStore(tmp_path)
- config.set_sync("cursor", True)
- user = _put(
- evidence,
- message_id="write-on-user",
- role="user",
- written_by=WrittenBy.PERSON,
- content="Harness Thaw 后应进入记忆流程。",
- conversation_id="write-on-conversation",
- )
- reply = _put(
- evidence,
- message_id="write-on-reply",
- role="assistant",
- written_by=WrittenBy.AGENT,
- content="收到。",
- conversation_id="write-on-conversation",
- )
- callback_threads: list[int] = []
-
- def source_may_write(source_id: str) -> bool:
- callback_threads.append(threading.get_ident())
- return config.sync_enabled(source_id)
-
- bridge = FakeBridge(
- outputs=(
- HyMemoryOutput(
- memory_id="hy-write-on",
- content="Harness 已 Thaw。",
- layer="L2_FACT",
- ),
- )
- )
- supervisor = MemoryProcessingSupervisor(
- tasks=tasks,
- profiles=profiles,
- secrets=secrets,
- evidence=evidence,
- governance=governance,
- data_dir=tmp_path,
- source_writes_permitted=source_may_write,
- )
- supervisor._bridges[(profile.profile_id, profile.revision, None)] = bridge
-
- completed = asyncio.run(supervisor.process_records((user, reply)))
-
- assert len(completed) == 1
- assert completed[0].status is MemoryTaskStatus.COMPLETED
- assert len(bridge.requests) == 1
- assert len(governance.list(user_id="local")) == 1
- assert callback_threads
- assert threading.get_ident() not in callback_threads
-
-
-def test_a_grown_chunk_leaves_started_work_alone(tmp_path) -> None:
- supervisor, tasks, profile, ask, first_reply, second_reply = _growing_conversation(tmp_path)
-
- shorter = supervisor._enqueue_chunk((ask, first_reply), profile, freeze_inputs=True)
- tasks.claim(shorter.task_id)
- supervisor._enqueue_chunk((ask, first_reply, second_reply), profile, freeze_inputs=True)
-
- assert tasks.require(shorter.task_id).status is MemoryTaskStatus.RUNNING
-
-
-def test_a_chunk_that_drops_earlier_input_does_not_retire_it(tmp_path) -> None:
- supervisor, tasks, profile, ask, first_reply, second_reply = _growing_conversation(tmp_path)
-
- earlier = supervisor._enqueue_chunk((ask, first_reply), profile, freeze_inputs=True)
- supervisor._enqueue_chunk((ask, second_reply), profile, freeze_inputs=True)
-
- assert tasks.require(earlier.task_id).status is MemoryTaskStatus.PENDING
-
-
-def test_digest_targets_stable_scopes_and_skips_quarantined_conversations(
- tmp_path,
-) -> None:
- stores = _setup(tmp_path)
- evidence, profiles, tasks, governance, secrets, profile = stores
- workspace = _put(
- evidence,
- message_id="workspace",
- role="user",
- written_by=WrittenBy.PERSON,
- content="项目范围内的事实。",
- conversation_id="workspace-conversation",
- workspace="workspace:v1:project",
- )
- quarantined = _put(
- evidence,
- message_id="quarantined",
- role="user",
- written_by=WrittenBy.PERSON,
- content="尚未确定归属的对话。",
- conversation_id="unknown-conversation",
- )
- imported_memory = _put(
- evidence,
- message_id="imported-memory",
- role="user",
- written_by=WrittenBy.PERSON,
- content="用户偏好简洁的回答。",
- conversation_id="memory-conversation",
- content_kind=EvidenceContentKind.MEMORY_CONTENT,
- )
- for index, record in enumerate((workspace, quarantined, imported_memory)):
- as_person(governance).create(
- MemoryDraft(
- user_id="local",
- kind=MemoryKind.CHAT,
- content=f"记忆 {index}",
- scopes=("all-apps",),
- evidence_ids=(record.evidence_id,),
- ),
- request_id=f"candidate-{index}",
- )
- bridge = FakeBridge(outputs=())
- supervisor = MemoryProcessingSupervisor(
- tasks=tasks,
- profiles=profiles,
- secrets=secrets,
- evidence=evidence,
- governance=governance,
- data_dir=tmp_path,
- )
- supervisor._bridges[(profile.profile_id, profile.revision, None)] = bridge
-
- result = asyncio.run(supervisor.digest())
-
- assert bridge.digest_calls == [
- ("local", UNIFIED_HY_AGENT_ID),
- ("local", _hy_agent_id((workspace,))),
- ]
- assert result["success"] is True
- assert result["scope_count"] == 2
- assert result["skipped_conversation_scopes"] == 1
-
-
-def test_digest_scopes_separate_applications_and_dates(tmp_path) -> None:
- evidence = EvidenceStore(tmp_path / "one-memory.sqlite3")
- records = (
- _put(
- evidence,
- message_id="a",
- role="user",
- written_by=WrittenBy.PERSON,
- content="a",
- source_id="cursor",
- created_at=datetime(2026, 10, 2, tzinfo=UTC),
- ),
- _put(
- evidence,
- message_id="b",
- role="user",
- written_by=WrittenBy.PERSON,
- content="b",
- source_id="cursor",
- created_at=datetime(2026, 10, 3, tzinfo=UTC),
- ),
- _put(
- evidence,
- message_id="c",
- role="user",
- written_by=WrittenBy.PERSON,
- content="c",
- source_id="codex",
- created_at=datetime(2026, 10, 2, tzinfo=UTC),
- ),
- )
- assert len({_hy_agent_id((record,)) for record in records}) == 3
-
-
-def test_workspace_requests_carry_conversation_authority_beyond_agent_scope(tmp_path) -> None:
- """Same-day workspace scopes collide by design; session_id must separate writes."""
- evidence, _profiles, tasks, _governance, _secrets, profile = _setup(tmp_path)
- first = _put(
- evidence,
- message_id="conversation-a",
- role="user",
- written_by=WrittenBy.PERSON,
- content="same workspace, first conversation",
- conversation_id="conversation-a",
- workspace="repo-a",
- created_at=datetime(2026, 10, 18, 8, tzinfo=UTC),
- )
- second = _put(
- evidence,
- message_id="conversation-b",
- role="user",
- written_by=WrittenBy.PERSON,
- content="same workspace, second conversation",
- conversation_id="conversation-b",
- workspace="repo-a",
- created_at=datetime(2026, 10, 18, 9, tzinfo=UTC),
- )
- next_day = _put(
- evidence,
- message_id="conversation-a-next-day",
- role="user",
- written_by=WrittenBy.PERSON,
- content="same conversation on the next day",
- conversation_id="conversation-a",
- workspace="repo-a",
- created_at=datetime(2026, 10, 19, 8, tzinfo=UTC),
- )
-
- requests = []
- for record in (first, second, next_day):
- task = tasks.create(
- request_id=f"authority:{record.evidence_id}",
- user_id=record.user_id,
- kind=MemoryTaskKind.EXTRACT,
- input_ref=record.evidence_id,
- profile=profile,
- input_records=(record,),
- )
- requests.append(MemoryTaskRunner._request(task, (record,)))
-
- assert requests[0].agent_id == requests[1].agent_id
- assert requests[0].session_id == "conversation-a"
- assert requests[1].session_id == "conversation-b"
- assert requests[2].agent_id != requests[0].agent_id
-
-
-def test_cancelled_multi_source_lock_acquisition_releases_earlier_source(tmp_path) -> None:
- evidence, profiles, tasks, governance, secrets, _profile = _setup(tmp_path)
- first = _put(
- evidence,
- message_id="first",
- role="user",
- written_by=WrittenBy.PERSON,
- content="first",
- source_id="a-source",
- )
- second = _put(
- evidence,
- message_id="second",
- role="user",
- written_by=WrittenBy.PERSON,
- content="second",
- source_id="b-source",
- )
- supervisor = MemoryProcessingSupervisor(
- tasks=tasks,
- profiles=profiles,
- secrets=secrets,
- evidence=evidence,
- governance=governance,
- data_dir=tmp_path,
- )
-
- async def scenario() -> None:
- blocked = _shared_source_lock("b-source")
- await blocked.acquire(ServiceLevel.BACKGROUND)
-
- async def acquire_both() -> None:
- async with supervisor._explicit_processing_lock((first, second)):
- pass
-
- task = asyncio.create_task(acquire_both())
- await asyncio.sleep(0)
- first_lock = _shared_source_lock("a-source")
- assert first_lock.locked()
- task.cancel()
- with pytest.raises(asyncio.CancelledError):
- await task
- assert not first_lock.locked()
- await blocked.release()
-
- asyncio.run(scenario())
-
-
-def test_realtime_source_waiter_overtakes_background_before_hy(tmp_path) -> None:
- evidence, profiles, tasks, governance, secrets, _profile = _setup(tmp_path)
- record = _put(
- evidence,
- message_id="priority-source",
- role="user",
- written_by=WrittenBy.PERSON,
- content="priority source",
- source_id="workbuddy",
- )
- supervisor = MemoryProcessingSupervisor(
- tasks=tasks,
- profiles=profiles,
- secrets=secrets,
- evidence=evidence,
- governance=governance,
- data_dir=tmp_path,
- )
-
- async def scenario() -> None:
- order: list[str] = []
- holder_ready = asyncio.Event()
- release = asyncio.Event()
-
- async def hold() -> None:
- with service_level_context(ServiceLevel.BACKGROUND):
- async with supervisor._source_processing_lock((record.source_id,)):
- holder_ready.set()
- await release.wait()
-
- async def wait(name: str, level: ServiceLevel) -> None:
- with service_level_context(level):
- async with supervisor._source_processing_lock((record.source_id,)):
- order.append(name)
-
- holder = asyncio.create_task(hold())
- await holder_ready.wait()
- background = asyncio.create_task(wait("background", ServiceLevel.BACKGROUND))
- await asyncio.sleep(0)
- realtime = asyncio.create_task(wait("realtime", ServiceLevel.REALTIME))
- await asyncio.sleep(0)
- release.set()
- await asyncio.gather(holder, background, realtime)
-
- assert order == ["realtime", "background"]
-
- asyncio.run(scenario())
-
-
-def _confirmed_from(governance, evidence_id: str, *, index: int = 0) -> None:
- as_person(governance).create(
- MemoryDraft(
- user_id="local",
- kind=MemoryKind.CHAT,
- content=f"记忆 {index}",
- scopes=("workspace:v1:project",),
- evidence_ids=(evidence_id,),
- ),
- request_id=f"candidate-{index}",
- )
-
-
-def test_what_system_2_induces_is_written_down_rather_than_returned(tmp_path) -> None:
- """`digest()` used to compute mental models and keep none of them.
-
- L6_SCHEMA lives in the graph, not in what a write returns, and digest
- handed its result to whoever called the endpoint. Five of them sat in Kuzu
- on this machine matching nothing in governance — the other half of the
- profile layer, produced and discarded.
- """
- stores = _setup(tmp_path)
- evidence, profiles, tasks, governance, secrets, profile = stores
- record = _put(
- evidence,
- message_id="m1",
- role="user",
- written_by=WrittenBy.PERSON,
- content="项目范围内的事实。",
- workspace="workspace:v1:project",
- )
- _confirmed_from(governance, record.evidence_id)
- bridge = FakeBridge(
- outputs=(),
- graph_nodes=(
- HyGraphNode(
- node_id="schema-1",
- content=(
- "When ensuring data consistency, the user prioritizes cross-environment checks."
- ),
- layer="l6_schema",
- ),
- # Relations and facts share the graph; only schemas are profile.
- HyGraphNode(node_id="fact-1", content="一条普通事实。", layer="l2_fact"),
- ),
- )
- supervisor = MemoryProcessingSupervisor(
- tasks=tasks,
- profiles=profiles,
- secrets=secrets,
- evidence=evidence,
- governance=governance,
- data_dir=tmp_path,
- )
- supervisor._bridges[(profile.profile_id, profile.revision, None)] = bridge
-
- result = asyncio.run(supervisor.digest())
-
- assert result["schemas_recorded"] == 1
- schemas = [
- memory for memory in governance.list(user_id="local") if memory.kind is MemoryKind.SCHEMA
- ]
- assert len(schemas) == 1
- # Readable from every app: a schema says how the person works, not what
- # one codebase contains.
- assert schemas[0].scopes == ("all-apps",)
- assert schemas[0].status is MemoryStatus.CONFIRMED
- # And it says what it was induced from.
- assert schemas[0].evidence_ids == (record.evidence_id,)
-
-
-def test_the_same_schema_is_not_written_twice_by_the_next_digest(tmp_path) -> None:
- """Digest runs repeatedly and System 2 keeps its nodes between runs."""
- stores = _setup(tmp_path)
- evidence, profiles, tasks, governance, secrets, profile = stores
- record = _put(
- evidence,
- message_id="m1",
- role="user",
- written_by=WrittenBy.PERSON,
- content="项目范围内的事实。",
- workspace="workspace:v1:project",
- )
- _confirmed_from(governance, record.evidence_id)
- nodes = (HyGraphNode(node_id="schema-1", content="用户偏好可验证的结论。", layer="l6_schema"),)
- supervisor = MemoryProcessingSupervisor(
- tasks=tasks,
- profiles=profiles,
- secrets=secrets,
- evidence=evidence,
- governance=governance,
- data_dir=tmp_path,
- )
- supervisor._bridges[(profile.profile_id, profile.revision, None)] = FakeBridge(
- outputs=(), graph_nodes=nodes
- )
-
- first = asyncio.run(supervisor.digest())
- second = asyncio.run(supervisor.digest())
-
- assert first["schemas_recorded"] == 1
- assert second["schemas_recorded"] == 0
- assert len([m for m in governance.list(user_id="local") if m.kind is MemoryKind.SCHEMA]) == 1
-
-
-def test_a_schema_is_mirrored_under_its_node_id_even_when_another_memory_has_its_text(
- tmp_path,
-) -> None:
- stores = _setup(tmp_path)
- evidence, profiles, tasks, governance, secrets, profile = stores
- record = _put(
- evidence,
- message_id="m1",
- role="user",
- written_by=WrittenBy.PERSON,
- content="项目范围内的事实。",
- workspace="workspace:v1:project",
- )
- _confirmed_from(governance, record.evidence_id)
- text = "用户偏好可验证的结论。"
- as_person(governance).create(
- MemoryDraft(
- user_id="local",
- kind=MemoryKind.CHAT,
- content=text,
- scopes=("all-apps",),
- evidence_ids=(record.evidence_id,),
- ),
- request_id="same-words",
- memory_id="hy-chat-node",
- )
- supervisor = MemoryProcessingSupervisor(
- tasks=tasks,
- profiles=profiles,
- secrets=secrets,
- evidence=evidence,
- governance=governance,
- data_dir=tmp_path,
- )
- supervisor._bridges[(profile.profile_id, profile.revision, None)] = FakeBridge(
- outputs=(),
- graph_nodes=(HyGraphNode(node_id="schema-1", content=text, layer="l6_schema"),),
- )
-
- assert asyncio.run(supervisor.digest())["schemas_recorded"] == 1
- assert governance.get("schema-1", user_id="local").kind is MemoryKind.SCHEMA
-
-
-def test_a_scope_with_no_local_evidence_left_records_no_schema(tmp_path) -> None:
- """We do not keep a memory we cannot say why we believe.
-
- HY is the source of truth for which scopes exist, so digest also visits
- scopes whose local memories are gone. A schema from one of those has
- nothing to cite, and governance requires a citation.
- """
- stores = _setup(tmp_path)
- evidence, profiles, tasks, governance, secrets, profile = stores
- bridge = FakeBridge(
- outputs=(),
- graph_nodes=(
- HyGraphNode(node_id="schema-1", content="无从追溯的归纳。", layer="l6_schema"),
- ),
- )
- bridge.stored_agent_ids = ("one-memory:scope:vanished",)
- supervisor = MemoryProcessingSupervisor(
- tasks=tasks,
- profiles=profiles,
- secrets=secrets,
- evidence=evidence,
- governance=governance,
- data_dir=tmp_path,
- )
- supervisor._bridges[(profile.profile_id, profile.revision, None)] = bridge
-
- result = asyncio.run(supervisor.digest())
-
- assert result["schemas_recorded"] == 0
- assert [m for m in governance.list(user_id="local") if m.kind is MemoryKind.SCHEMA] == []
-
-
-def test_digest_also_covers_scopes_only_hy_still_knows_about(tmp_path) -> None:
- stores = _setup(tmp_path)
- evidence, profiles, tasks, governance, secrets, profile = stores
- workspace = _put(
- evidence,
- message_id="workspace",
- role="user",
- written_by=WrittenBy.PERSON,
- content="项目范围内的事实。",
- conversation_id="workspace-conversation",
- workspace="workspace:v1:project",
- )
- as_person(governance).create(
- MemoryDraft(
- user_id="local",
- kind=MemoryKind.CHAT,
- content="记忆",
- scopes=("all-apps",),
- evidence_ids=(workspace.evidence_id,),
- ),
- request_id="candidate",
- )
- bridge = FakeBridge(outputs=())
- # Memories written under an earlier routing policy still live here.
- bridge.stored_agent_ids = (UNIFIED_HY_AGENT_ID, "one-memory:scope:legacy")
- supervisor = MemoryProcessingSupervisor(
- tasks=tasks,
- profiles=profiles,
- secrets=secrets,
- evidence=evidence,
- governance=governance,
- data_dir=tmp_path,
- )
- supervisor._bridges[(profile.profile_id, profile.revision, None)] = bridge
-
- result = asyncio.run(supervisor.digest())
-
- assert {agent_id for _user, agent_id in bridge.digest_calls} == {
- UNIFIED_HY_AGENT_ID,
- "one-memory:scope:legacy",
- _hy_agent_id((workspace,)),
- }
- assert result["scope_count"] == 3
-
-
-def test_host_injected_text_is_not_treated_as_the_person_speaking(tmp_path) -> None:
- """Wrapper text a host injects is not testimony, whoever it is attributed to.
-
- Hosts prepend their own envelopes to a turn, and the record still arrives
- tagged as person-authored. Reading those as things the user said would let
- a host's own boilerplate become a confirmed fact about the user.
- """
- evidence = _setup(tmp_path)[0]
- prefixed = _put(
- evidence,
- message_id="prefixed",
- role="user",
- written_by=WrittenBy.PERSON,
- content="<system_notification>我喜欢深色主题。</system_notification>",
- )
- # The envelope does not have to start the turn to be an envelope.
- wrapped = _put(
- evidence,
- message_id="wrapped",
- role="user",
- written_by=WrittenBy.PERSON,
- content=(
- "<timestamp>2026-09-04</timestamp>\n"
- "<system_notification>我喜欢深色主题。</system_notification>"
- ),
- )
- # A harness may also hand us its raw request payload.
- payload = _put(
- evidence,
- message_id="payload",
- role="user",
- written_by=WrittenBy.PERSON,
- content='{"request_id": "r-1", "steps": [{"text": "我喜欢深色主题。"}]}',
- )
- spoken = _put(
- evidence,
- message_id="spoken",
- role="user",
- written_by=WrittenBy.PERSON,
- content="我喜欢深色主题。",
- )
- assert _is_hy_input_turn(spoken)
- assert not any(_is_hy_input_turn(record) for record in (prefixed, wrapped, payload))
-
-
-def test_harness_instruction_blocks_never_reach_extraction(tmp_path) -> None:
- """Instructions the harness prepends arrive wearing the user's role.
-
- A rules file or environment preamble is a fact about the project, not a
- preference of the person. Letting one through would turn "this repo uses
- axios" into "the user prefers axios" and then recall it everywhere.
- """
- evidence = _setup(tmp_path)[0]
- injected = _put(
- evidence,
- message_id="agents-md",
- role="user",
- written_by=WrittenBy.PERSON,
- content="# AGENTS.md instructions\n\n统一用 axios 封装,不用 fetch 裸调。",
- )
- spoken = _put(
- evidence,
- message_id="spoken",
- role="user",
- written_by=WrittenBy.PERSON,
- content="我喜欢深色主题。",
- )
-
- assert _conversation_chunks([injected]) == []
- # Positive control: a real turn still gets through.
- assert _conversation_chunks([spoken]) != []
-
-
-class _Sluggish:
- """A store whose every call takes a moment, the way a contended write
- lock does. Wrapping the real one keeps the behaviour under test intact."""
-
- def __init__(self, inner: object, delay: float = 0.05) -> None:
- self._inner = inner
- self._delay = delay
-
- def __getattr__(self, name: str):
- attribute = getattr(self._inner, name)
- if not callable(attribute):
- return attribute
-
- def slowly(*args, **kwargs):
- time.sleep(self._delay)
- return attribute(*args, **kwargs)
-
- return slowly
-
-
-def test_the_pipeline_leaves_the_loop_free_to_answer(tmp_path) -> None:
- """A task must not stop the app answering while it runs.
-
- Every store call in a task is synchronous, and the writes wait on the
- write lock — up to five seconds each. Made from the loop, and made a dozen
- times per task with hundreds of tasks queued, they stalled everything
- served from the same process: /health, which does no work, was measured at
- 3.5 seconds on this machine and a library read at 20.7 seconds, past the
- renderer's timeout, so a library of 483 memories displayed as empty.
- """
- stores = _setup(tmp_path)
- evidence, profiles, tasks, governance, secrets, profile = stores
- record = _put(
- evidence,
- message_id="u1",
- role="user",
- written_by=WrittenBy.PERSON,
- content="我更希望记忆处理都在本地完成。",
- )
- task = _task(tasks, profile, record)
- # A fifth of a second per call, so a dozen of them on the loop is seconds
- # and no plausible amount of machine noise can be mistaken for it.
- delay = 0.2
- runner = MemoryTaskRunner(
- tasks=_Sluggish(tasks, delay),
- profiles=_Sluggish(profiles, delay),
- secrets=secrets,
- evidence=_Sluggish(evidence, delay),
- governance=_Sluggish(governance, delay),
- data_dir=tmp_path,
- bridge_factory=lambda _profile, _secret, _data_dir: FakeBridge(
- outputs=(
- HyMemoryOutput(memory_id="m1", content="偏好本地处理。", layer="L2_FACT"),
- HyMemoryOutput(memory_id="m2", content="偏好可追溯。", layer="L2_FACT"),
- HyMemoryOutput(memory_id="m3", content="偏好一步完成。", layer="L2_FACT"),
- )
- ),
- )
-
- async def run_while_watching_the_loop() -> tuple[float, object]:
- longest = 0.0
-
- async def heartbeat() -> None:
- nonlocal longest
- last = time.perf_counter()
- while True:
- await asyncio.sleep(0.005)
- now = time.perf_counter()
- longest = max(longest, now - last)
- last = now
-
- beat = asyncio.create_task(heartbeat())
- try:
- finished = await runner.run(task.task_id)
- finally:
- beat.cancel()
- return longest, finished
-
- longest, finished = asyncio.run(run_while_watching_the_loop())
-
- # The work really happened, so this cannot pass by doing nothing.
- assert finished.status is MemoryTaskStatus.COMPLETED
- assert len(governance.list(user_id=record.user_id)) == 3
- # Over a dozen calls at a fifth of a second each: on the loop that is
- # seconds, so the gap between pass and fail is an order of magnitude and
- # this does not become a test of how busy the machine is.
- assert longest < delay * 3, f"事件循环被堵住 {longest:.3f}s"
-
-
-def test_live_sync_enqueueing_leaves_the_loop_free_to_answer(tmp_path) -> None:
- """Every conversation that changes arrives here while the app is in use.
-
- Rebuilding one is seconds for a long conversation, and it was read on the
- loop: the watchdog caught this path holding the loop 2.1s, and a held loop
- is a host waiting for a recall that cannot be served.
- """
- stores = _setup(tmp_path)
- evidence, profiles, tasks, governance, secrets, _profile = stores
- seed = _put(
- evidence,
- message_id="u1",
- role="user",
- written_by=WrittenBy.PERSON,
- content="我希望同步是实时的。",
- conversation_id="conversation-1",
- )
- _put(
- evidence,
- message_id="a1",
- role="assistant",
- written_by=WrittenBy.AGENT,
- content="同步会保持实时。",
- conversation_id="conversation-1",
- )
- delay = 0.2
-
- async def enqueue_while_watching_the_loop() -> tuple[float, int]:
- supervisor = MemoryProcessingSupervisor(
- tasks=_Sluggish(tasks, delay),
- profiles=_Sluggish(profiles, delay),
- secrets=secrets,
- evidence=_Sluggish(evidence, delay),
- governance=governance,
- data_dir=tmp_path,
- runner_factory=lambda: _runner(tmp_path, stores, FakeBridge(outputs=())),
- )
- # Paid up front: the first hand-off to a thread in a process imports
- # the pool and starts it, which is a fifth of a second on the loop
- # once and has nothing to do with what is measured here.
- await asyncio.to_thread(lambda: None)
- longest = 0.0
- ticks = 0
-
- async def heartbeat() -> None:
- nonlocal longest, ticks
- last = time.perf_counter()
- while True:
- await asyncio.sleep(0.005)
- now = time.perf_counter()
- longest = max(longest, now - last)
- last = now
- ticks += 1
-
- beat = asyncio.create_task(heartbeat())
- # Let it beat before the work starts. Without this its first
- # measurement is taken after the stall, so it cannot see the very gap
- # it is here to catch — which is how the first version of this test
- # passed against the defect it was written for.
- await asyncio.sleep(0.05)
- try:
- created = await supervisor.enqueue_conversation_off_thread(seed)
- # A stall is only measured by the beat that follows it, so let one
- # follow. Cancelling straight away hid the gap entirely — the
- # second way this test managed to pass against its own defect.
- await asyncio.sleep(0.02)
- finally:
- beat.cancel()
- await supervisor.shutdown()
- return longest, len(created), ticks
-
- longest, created, ticks = asyncio.run(enqueue_while_watching_the_loop())
-
- # It really enqueued, so this cannot pass by doing nothing.
- assert created == 1
- assert ticks > 1, "心跳没有真的在跑"
- assert longest < delay * 2, f"实时入队期间循环被堵住 {longest:.3f}s"
-
-
-def test_work_left_unfinished_by_the_last_run_is_taken_up_again(tmp_path) -> None:
- """Nothing else carries an interrupted memory across a restart.
-
- A task recorded but not finished — the app quit, the machine slept, the
- model was unreachable — is only ever picked up by resuming. Until this
- test there was nothing to notice if it stopped happening, and the symptom
- would be memories that never appear, from conversations already imported.
- """
- stores = _setup(tmp_path)
- evidence, profiles, tasks, governance, secrets, _profile = stores
- interrupted = _put(
- evidence,
- message_id="u1",
- role="user",
- written_by=WrittenBy.PERSON,
- content="上一轮没跑完的对话。",
- conversation_id="conversation-1",
- content_kind=EvidenceContentKind.MEMORY_CONTENT,
- )
-
- async def record_then_walk_away() -> None:
- supervisor = MemoryProcessingSupervisor(
- tasks=tasks,
- profiles=profiles,
- secrets=secrets,
- evidence=evidence,
- governance=governance,
- data_dir=tmp_path,
- runner_factory=lambda: _runner(tmp_path, stores, FakeBridge(outputs=())),
- )
- # Recorded without being scheduled: the state a quit mid-catch-up
- # leaves behind.
- supervisor.prepare_backfill()
- await supervisor.shutdown()
-
- asyncio.run(record_then_walk_away())
-
- pending = tasks.list()
- assert [task.status for task in pending] == [MemoryTaskStatus.PENDING]
-
- async def start_again() -> None:
- supervisor = MemoryProcessingSupervisor(
- tasks=tasks,
- profiles=profiles,
- secrets=secrets,
- evidence=evidence,
- governance=governance,
- data_dir=tmp_path,
- runner_factory=lambda: _runner(tmp_path, stores, FakeBridge(outputs=())),
- )
- await supervisor.resume_off_thread()
- for _ in range(200):
- if all(task.status is MemoryTaskStatus.COMPLETED for task in tasks.list()):
- break
- await asyncio.sleep(0.01)
- await supervisor.shutdown()
-
- asyncio.run(start_again())
-
- finished = tasks.list()
- assert [task.input_ref for task in finished] == [interrupted.evidence_id]
- assert [task.status for task in finished] == [MemoryTaskStatus.COMPLETED]
-
-
-def test_hy_topic_tags_reach_the_library(tmp_path) -> None:
- """HY 打的主题标签要一路走到库里,而不是在边界上被丢掉。"""
- stores = _setup(tmp_path)
- evidence, _profiles, tasks, governance, _secrets, profile = stores
- user = _put(
- evidence,
- message_id="u1",
- role="user",
- written_by=WrittenBy.PERSON,
- content="周末不排评审会。",
- )
- task = _task(tasks, profile, user)
- bridge = FakeBridge(
- outputs=(
- HyMemoryOutput(
- memory_id="hy-1",
- content="用户周末不安排评审会。",
- tags=("排期", "工作习惯"),
- ),
- )
- )
-
- asyncio.run(_runner(tmp_path, stores, bridge).run(task.task_id))
-
- assert governance.list(user_id="local")[0].tags == ("排期", "工作习惯")
-
-
-class _GatedDigestBridge(FakeBridge):
- """Holds `digest` open until released, and counts how many are inside it.
-
- The state is shared between bridges, so two supervisors each with their
- own bridge still report into one place.
- """
-
- def __init__(self, state: dict[str, object]) -> None:
- super().__init__(outputs=())
- self.state = state
- self.stored_agent_ids = ("agent-shared",)
-
- async def digest(self, *, user_id: str, agent_id: str) -> dict[str, object]:
- state = self.state
- state["entered"] += 1
- state["inside"] += 1
- state["peak"] = max(state["peak"], state["inside"])
- try:
- await state["release"].wait()
- finally:
- state["inside"] -= 1
- return await super().digest(user_id=user_id, agent_id=agent_id)
-
-
-def test_digests_are_serialised_across_supervisors(tmp_path, monkeypatch) -> None:
- """Two digests must not overlap, even from different supervisors.
-
- A digest reads the memory it is about to summarise and then writes the
- summary. Two running at once — yesterday's harness and today's, say — each
- see a state the other is part-way through changing, and each concludes from
- it. The result is two summaries of two different half-updated memories.
-
- This used to acquire `_digest_mutex()` itself and gather on it, which only
- proved that `asyncio.Lock` works: deleting the acquire/release in
- `digest()` left it green. Here the real `digest()` of two supervisors runs,
- and the bridge each one calls is what observes the overlap.
- """
- from one_memory import memory_processing
-
- # The guard is process-wide and binds to the loop that first contends it;
- # start from a fresh one so an earlier test's loop cannot leak in.
- monkeypatch.setattr(memory_processing, "_digest_guard", None)
- state: dict[str, object] = {"entered": 0, "inside": 0, "peak": 0}
- supervisors = []
- for name in ("yesterday", "today"):
- root = tmp_path / name
- root.mkdir()
- evidence, profiles, tasks, governance, secrets, profile = _setup(root)
- supervisor = MemoryProcessingSupervisor(
- tasks=tasks,
- profiles=profiles,
- secrets=secrets,
- evidence=evidence,
- governance=governance,
- data_dir=root,
- )
- supervisor._bridges[(profile.profile_id, profile.revision, None)] = _GatedDigestBridge(
- state
- )
- supervisors.append(supervisor)
-
- async def scenario() -> list[dict[str, object]]:
- state["release"] = asyncio.Event()
- running = [asyncio.create_task(supervisor.digest()) for supervisor in supervisors]
- try:
- loop = asyncio.get_running_loop()
- deadline = loop.time() + 3
- while state["entered"] < 1 and loop.time() < deadline:
- await asyncio.sleep(0.01)
- assert state["entered"] >= 1, "neither digest reached the bridge"
- # Give the second digest every chance to get in while the first
- # is still inside. Without the lock it does, well within this.
- deadline = loop.time() + 0.5
- while state["entered"] < 2 and loop.time() < deadline:
- await asyncio.sleep(0.01)
- finally:
- state["release"].set()
- return await asyncio.wait_for(asyncio.gather(*running), 5)
-
- results = asyncio.run(scenario())
-
- # Non-vacuous: both digests really ran their scope through the bridge.
- assert state["entered"] == 2
- assert [result["scope_count"] for result in results] == [1, 1]
- assert state["peak"] == 1, "two digests were inside the bridge at once"
-
-
-def test_the_digest_lock_is_one_lock_for_the_process() -> None:
- """A per-supervisor lock could not order digests from different callers."""
- from one_memory.memory_processing import _digest_mutex
-
- assert _digest_mutex() is _digest_mutex()
-
-
-def test_digest_lock_precedes_scope_and_evidence_snapshot(tmp_path, monkeypatch) -> None:
- from one_memory import memory_processing
-
- monkeypatch.setattr(memory_processing, "_digest_guard", None)
- entered = 0
- first_entered = asyncio.Event()
- release = asyncio.Event()
- original = MemoryProcessingSupervisor._digest_scopes
-
- async def gated(supervisor, bridge):
- nonlocal entered
- entered += 1
- if entered == 1:
- first_entered.set()
- await release.wait()
- return await original(supervisor, bridge)
-
- monkeypatch.setattr(MemoryProcessingSupervisor, "_digest_scopes", gated)
- supervisors = []
- for name in ("first", "second"):
- root = tmp_path / name
- root.mkdir()
- evidence, profiles, tasks, governance, secrets, profile = _setup(root)
- supervisor = MemoryProcessingSupervisor(
- tasks=tasks,
- profiles=profiles,
- secrets=secrets,
- evidence=evidence,
- governance=governance,
- data_dir=root,
- )
- supervisor._bridges[(profile.profile_id, profile.revision, None)] = FakeBridge(outputs=())
- supervisors.append(supervisor)
-
- async def scenario() -> None:
- tasks = [asyncio.create_task(supervisor.digest()) for supervisor in supervisors]
- await asyncio.wait_for(first_entered.wait(), 1)
- await asyncio.sleep(0.1)
- assert entered == 1
- release.set()
- await asyncio.gather(*tasks)
-
- asyncio.run(scenario())
- assert entered == 2
-
-
-class _HangingBridge:
- """A bridge whose write never returns, to exercise the budget."""
-
- def __init__(self) -> None:
- self.calls = 0
-
- async def add_memory(self, *_args: object, **_kwargs: object) -> object:
- self.calls += 1
- await asyncio.sleep(30)
- return None
-
-
-def test_a_task_past_its_budget_surfaces_as_hy_memory_timeout(tmp_path) -> None:
- """The wall-clock budget turns a hang into a classified timeout.
-
- A harness is serial, so a hung task holds the only slot that harness has
- and every later turn waits behind it. The budget must therefore surface as
- `hy_memory_timeout` — which the runner's own classification turns into a
- retry rather than a terminal failure or a silent hang.
- """
- stores = _setup(tmp_path)
- evidence, _profiles, tasks, _governance, _secrets, profile = stores
- record = _put(
- evidence,
- message_id="u-budget",
- role="user",
- written_by=WrittenBy.PERSON,
- content="预算测试的一句话。",
- conversation_id="conversation-budget",
- )
- task = _task(tasks, profile, record)
- runner = _runner(tmp_path, stores, _HangingBridge())
-
- async def scenario() -> None:
- async def hang(_task_id: str) -> object:
- await asyncio.sleep(30)
- return None
-
- # The runner's own body is what the budget wraps; patching it keeps the
- # test on the budget itself rather than on a bridge's behaviour.
- runner._run_without_content_permission = hang # type: ignore[method-assign]
- with pytest.raises(HyMemoryBridgeError) as caught:
- await runner.run(task.task_id, timeout=0.05)
- assert str(caught.value) == "hy_memory_timeout"
-
- asyncio.run(scenario())
- recovered = tasks.require(task.task_id)
- assert recovered.status is MemoryTaskStatus.PENDING
-
-
-def test_without_a_budget_a_slow_task_is_not_cut_off(tmp_path) -> None:
- """Absent profile timeout means unbounded, not an invented default.
-
- Deciding a number here would silently override whatever the operator
- configured, which is worse than not having a budget.
- """
- stores = _setup(tmp_path)
- evidence, _profiles, tasks, _governance, _secrets, profile = stores
- record = _put(
- evidence,
- message_id="u-budget",
- role="user",
- written_by=WrittenBy.PERSON,
- content="预算测试的一句话。",
- conversation_id="conversation-budget",
- )
- task = _task(tasks, profile, record)
- runner = _runner(tmp_path, stores, _HangingBridge())
-
- async def scenario() -> None:
- async def slow(_task_id: str) -> object:
- await asyncio.sleep(0.02)
- return tasks.require(task.task_id)
-
- runner._run_without_content_permission = slow # type: ignore[method-assign]
- finished = await runner.run(task.task_id)
- assert finished.task_id == task.task_id
-
- asyncio.run(scenario())
-
-
-def test_a_timed_out_task_becomes_unknown_and_is_not_left_running(tmp_path) -> None:
- """The budget must both release the slot and not invite a re-send.
-
- A task is claimed as `running` before anything slow happens, so a timeout
- must release that slot. But the timeout can fire after the HY call was
- already in flight, and HY has no idempotency key, so the task must settle
- `unknown` rather than a retryable state - otherwise the scheduler re-selects
- it and sends a second copy.
- """
- stores = _setup(tmp_path)
- evidence, _profiles, tasks, _governance, _secrets, profile = stores
- record = _put(
- evidence,
- message_id="u-timeout",
- role="user",
- written_by=WrittenBy.PERSON,
- content="超时测试的一句话。",
- conversation_id="conversation-timeout",
- )
- task = _task(tasks, profile, record)
- runner = _runner(tmp_path, stores, _HangingBridge())
-
- async def scenario() -> None:
- # Claim it, the way a real run does before the slow part.
- claimed, token = tasks.claim(task.task_id)
- assert claimed.status is MemoryTaskStatus.RUNNING
-
- async def hang(_task_id: str) -> object:
- tasks.record_hy_invocation(task.task_id, runner_token=token)
- await asyncio.sleep(30)
- return None
-
- runner._run_without_content_permission = hang # type: ignore[method-assign]
- with pytest.raises(HyMemoryBridgeError):
- await runner.run(task.task_id, timeout=0.05)
-
- # Not left running: the turns behind it have to be able to run.
- settled = tasks.require(task.task_id)
- assert settled.status is MemoryTaskStatus.UNKNOWN
- assert settled.last_error_code == "model_content_outcome_unknown"
-
- asyncio.run(scenario())
-
-
-def test_client_initialization_failure_retries_without_marking_hy_invoked(tmp_path) -> None:
- stores = _setup(tmp_path)
- evidence, _profiles, tasks, _governance, _secrets, profile = stores
- record = _put(
- evidence,
- message_id="init-retry",
- role="user",
- written_by=WrittenBy.PERSON,
- content="初始化失败不应变成结果未知。",
- conversation_id="conversation-init-retry",
- )
- task = _task(tasks, profile, record)
-
- class InitiallyUnavailableBridge(FakeBridge):
- prepare_calls = 0
-
- async def prepare(self) -> None:
- self.prepare_calls += 1
- if self.prepare_calls == 1:
- raise HyMemoryBridgeError("hy_memory_init_failed")
-
- bridge = InitiallyUnavailableBridge()
- runner = _runner(tmp_path, stores, bridge)
-
- first = asyncio.run(runner.run(task.task_id))
- assert first.status is MemoryTaskStatus.FAILED
- assert first.last_error_code == "hy_memory_init_failed"
- with sqlite3.connect(tasks.database_path) as connection:
- assert (
- connection.execute(
- "SELECT hy_invocation_count FROM memory_tasks WHERE task_id=?",
- (task.task_id,),
- ).fetchone()[0]
- == 0
- )
-
- second = asyncio.run(runner.run(task.task_id))
- assert second.status is MemoryTaskStatus.COMPLETED
- with sqlite3.connect(tasks.database_path) as connection:
- assert (
- connection.execute(
- "SELECT hy_invocation_count FROM memory_tasks WHERE task_id=?",
- (task.task_id,),
- ).fetchone()[0]
- == 1
- )
-
-
-def test_binding_change_before_hy_is_cancelled_for_immediate_replacement(tmp_path) -> None:
- stores = _setup(tmp_path)
- evidence, profiles, tasks, governance, secrets, profile = stores
- record = _put(
- evidence,
- message_id="binding-replacement",
- role="user",
- written_by=WrittenBy.PERSON,
- content="开关切换后应使用最新授权重新整理。",
- conversation_id="binding-replacement",
- )
- task = _task(tasks, profile, record)
- claimed, token = tasks.claim(task.task_id)
- assert claimed.status is MemoryTaskStatus.RUNNING
-
- cancelled = tasks.stop(
- task.task_id,
- runner_token=token,
- error_code="model_content_continuous_binding_invalid",
- )
-
- assert cancelled.status is MemoryTaskStatus.CANCELLED
- assert cancelled.last_error_code == "model_content_continuous_binding_invalid"
- with sqlite3.connect(tasks.database_path) as connection:
- assert (
- connection.execute(
- "SELECT hy_invocation_count FROM memory_tasks WHERE task_id=?",
- (task.task_id,),
- ).fetchone()[0]
- == 0
- )
-
- supervisor = MemoryProcessingSupervisor(
- tasks=tasks,
- profiles=stores[1],
- secrets=stores[4],
- evidence=evidence,
- governance=stores[3],
- data_dir=tmp_path,
- )
- replacements = []
-
- async def replace(latest):
- replacements.append(latest)
- return []
-
- supervisor.enqueue_conversation_off_thread = replace # type: ignore[method-assign]
- asyncio.run(supervisor._replace_stale_binding(cancelled)) # noqa: SLF001
- assert replacements == [record]
-
-
-def test_runtime_maintenance_recovers_an_orphan_while_the_queue_is_idle(
- tmp_path, monkeypatch
-) -> None:
- stores = _setup(tmp_path)
- evidence, profiles, tasks, governance, secrets, profile = stores
- record = _put(
- evidence,
- message_id="orphan-running",
- role="user",
- written_by=WrittenBy.PERSON,
- content="这条任务的 worker 已经消失。",
- conversation_id="orphan-running",
- )
- task = _task(tasks, profile, record)
- tasks.claim(task.task_id)
- monkeypatch.setattr("one_memory.memory_processing.ORPHAN_RECOVERY_INTERVAL_SECONDS", 0.01)
- supervisor = MemoryProcessingSupervisor(
- tasks=tasks,
- profiles=profiles,
- secrets=secrets,
- evidence=evidence,
- governance=governance,
- data_dir=tmp_path,
- runner_factory=lambda: _runner(tmp_path, stores, FakeBridge()),
- )
-
- async def scenario() -> None:
- supervisor.start_maintenance()
- try:
- for _ in range(50):
- if tasks.require(task.task_id).status is MemoryTaskStatus.PENDING:
- break
- await asyncio.sleep(0.01)
- assert tasks.require(task.task_id).status is MemoryTaskStatus.PENDING
- finally:
- await supervisor.shutdown()
-
- asyncio.run(scenario())
-
-
-def test_runtime_maintenance_does_not_reclaim_a_direct_durable_task(tmp_path, monkeypatch) -> None:
- stores = _setup(tmp_path)
- evidence, profiles, tasks, governance, secrets, profile = stores
- record = _put(
- evidence,
- message_id="durable-running",
- role="user",
- written_by=WrittenBy.PERSON,
- content="这条直接队列任务仍由当前进程执行。",
- conversation_id="durable-running",
- )
- answer = _put(
- evidence,
- message_id="durable-running-answer",
- role="assistant",
- written_by=WrittenBy.AGENT,
- content="开始执行。",
- conversation_id="durable-running",
- )
- entered = asyncio.Event()
- release = asyncio.Event()
-
- class SlowDirectRunner:
- async def run(self, task_id, *, timeout=None):
- del timeout
- _running, token = tasks.claim(task_id)
- entered.set()
- await release.wait()
- return tasks.complete(task_id, runner_token=token)
-
- def _frozen_chunk(self, _task):
- return (record, answer)
-
- monkeypatch.setattr("one_memory.memory_processing.ORPHAN_RECOVERY_INTERVAL_SECONDS", 0.01)
- supervisor = MemoryProcessingSupervisor(
- tasks=tasks,
- profiles=profiles,
- secrets=secrets,
- evidence=evidence,
- governance=governance,
- data_dir=tmp_path,
- bridge_factory=lambda *_args: FakeBridge(),
- runner_factory=SlowDirectRunner,
- )
-
- async def scenario() -> None:
- supervisor.start_maintenance()
- running = asyncio.create_task(supervisor.process_records((record, answer)))
- try:
- await asyncio.wait_for(entered.wait(), 1)
- await asyncio.sleep(0.05)
- current = tasks.task_for_evidence(record.evidence_id)
- assert current is not None
- assert current.status is MemoryTaskStatus.RUNNING
- release.set()
- await asyncio.wait_for(running, 2)
- assert tasks.task_for_evidence(record.evidence_id).status is MemoryTaskStatus.COMPLETED
- finally:
- release.set()
- await supervisor.shutdown()
-
- asyncio.run(scenario())
-
-
-def test_second_supervisor_does_not_reclaim_a_direct_task_owned_by_the_first(
- tmp_path, monkeypatch
-) -> None:
- stores = _setup(tmp_path)
- evidence, profiles, tasks, governance, secrets, profile = stores
- record = _put(
- evidence,
- message_id="durable-running-cross-supervisor",
- role="user",
- written_by=WrittenBy.PERSON,
- content="这条直接队列任务由另一个 supervisor 执行。",
- conversation_id="durable-running-cross-supervisor",
- )
- answer = _put(
- evidence,
- message_id="durable-running-cross-supervisor-answer",
- role="assistant",
- written_by=WrittenBy.AGENT,
- content="开始执行。",
- conversation_id="durable-running-cross-supervisor",
- )
- entered = asyncio.Event()
- release = asyncio.Event()
-
- class SlowDirectRunner:
- async def run(self, task_id, *, timeout=None):
- del timeout
- _running, token = tasks.claim(task_id)
- entered.set()
- await release.wait()
- return tasks.complete(task_id, runner_token=token)
-
- def _frozen_chunk(self, _task):
- return (record, answer)
-
- monkeypatch.setattr("one_memory.memory_processing.ORPHAN_RECOVERY_INTERVAL_SECONDS", 0.01)
- owner = MemoryProcessingSupervisor(
- tasks=tasks,
- profiles=profiles,
- secrets=secrets,
- evidence=evidence,
- governance=governance,
- data_dir=tmp_path,
- bridge_factory=lambda *_args: FakeBridge(),
- runner_factory=SlowDirectRunner,
- )
- reclaimer = MemoryProcessingSupervisor(
- tasks=MemoryTaskStore(tasks.database_path),
- profiles=profiles,
- secrets=secrets,
- evidence=evidence,
- governance=governance,
- data_dir=tmp_path,
- bridge_factory=lambda *_args: FakeBridge(),
- )
-
- async def scenario() -> None:
- reclaimer.start_maintenance()
- running = asyncio.create_task(owner.process_records((record, answer)))
- try:
- await asyncio.wait_for(entered.wait(), 1)
- await asyncio.sleep(0.05)
- current = tasks.task_for_evidence(record.evidence_id)
- assert current is not None
- assert current.status is MemoryTaskStatus.RUNNING
- release.set()
- await asyncio.wait_for(running, 2)
- assert tasks.task_for_evidence(record.evidence_id).status is MemoryTaskStatus.COMPLETED
- finally:
- release.set()
- await owner.shutdown()
- await reclaimer.shutdown()
-
- asyncio.run(scenario())
-
-
-def test_policy_refusals_are_counted_apart_from_real_failures(tmp_path) -> None:
- """A revoked policy refuses tasks at creation; that is not a failed extract.
-
- Those tasks never ran (`attempts = 0`), so counting them as ordinary
- failures makes a deliberately turned-off feature look like a broken
- pipeline. They are reported as their own number instead.
- """
- stores = _setup(tmp_path)
- evidence, _profiles, tasks, _governance, _secrets, profile = stores
- record = _put(
- evidence,
- message_id="u-policy",
- role="user",
- written_by=WrittenBy.PERSON,
- content="策略失效测试的一句话。",
- conversation_id="conversation-policy",
- )
- task = _task(tasks, profile, record)
-
- _claimed, token = tasks.claim(task.task_id)
- tasks.fail(
- task.task_id,
- runner_token=token,
- error_code="model_content_policy_not_current_or_enabled",
- )
- assert tasks.require(task.task_id).status is MemoryTaskStatus.FAILED
-
- # Never attempted, so it is a policy refusal rather than a failure to extract.
- assert tasks.unexecuted_policy_failures() == 1
-
-
-def test_a_real_failure_is_not_counted_as_a_policy_refusal(tmp_path) -> None:
- """Otherwise the number would under-report genuine breakage."""
- stores = _setup(tmp_path)
- evidence, _profiles, tasks, _governance, _secrets, profile = stores
- record = _put(
- evidence,
- message_id="u-real",
- role="user",
- written_by=WrittenBy.PERSON,
- content="真实失败测试的一句话。",
- conversation_id="conversation-real",
- )
- task = _task(tasks, profile, record)
-
- _claimed, token = tasks.claim(task.task_id)
- tasks.fail(task.task_id, runner_token=token, error_code="hy_memory_runtime_failed")
-
- assert tasks.require(task.task_id).status is MemoryTaskStatus.FAILED
- assert tasks.unexecuted_policy_failures() == 0
-
-
-def test_scheduler_skips_failed_tasks_at_the_fixed_retry_ceiling(tmp_path) -> None:
- """The scheduler's retry ceiling must be a fixed bound, not the constant.
-
- `MemoryTaskStore.claim()` already refuses a `FAILED` row at the ceiling.
- The dispatch path has a second guard so such a row is never handed to a
- runner at all. Build the rows with the concrete boundary (3) rather than
- importing the implementation constant: mutating that constant to a huge
- value must make this test fail instead of silently widening the budget.
- """
- stores = _setup(tmp_path)
- evidence, profiles, tasks, governance, secrets, profile = stores
- exhausted = _put(
- evidence,
- message_id="retry-ceiling-exhausted",
- role="user",
- written_by=WrittenBy.PERSON,
- conversation_id="retry-ceiling-exhausted",
- content="This conversation has already failed three times.",
- )
- retryable = _put(
- evidence,
- message_id="retry-ceiling-retryable",
- role="user",
- written_by=WrittenBy.PERSON,
- conversation_id="retry-ceiling-retryable",
- content="This conversation still has one attempt left.",
- )
- exhausted_task = _task(tasks, profile, exhausted, suffix="exhausted")
- retryable_task = _task(tasks, profile, retryable, suffix="retryable")
- with sqlite3.connect(tasks.database_path) as connection, connection:
- connection.execute(
- "UPDATE memory_tasks SET status=?, attempts=3, "
- "last_error_code='model_content_execution_failed' WHERE task_id=?",
- (MemoryTaskStatus.FAILED, exhausted_task.task_id),
- )
- connection.execute(
- "UPDATE memory_tasks SET status=?, attempts=2, "
- "last_error_code='model_content_execution_failed' WHERE task_id=?",
- (MemoryTaskStatus.FAILED, retryable_task.task_id),
- )
-
- supervisor = MemoryProcessingSupervisor(
- tasks=tasks,
- profiles=profiles,
- secrets=secrets,
- evidence=evidence,
- governance=governance,
- data_dir=tmp_path,
- runner_factory=lambda: _runner(tmp_path, stores, FakeBridge()),
- )
- work = supervisor._classify(tasks.list(statuses=(MemoryTaskStatus.FAILED,)))
-
- assert [item.task_id for item in work] == [retryable_task.task_id]
diff --git a/memhub/apps/core/tests/test_memory_processing_diagnostics.py b/memhub/apps/core/tests/test_memory_processing_diagnostics.py
deleted file mode 100644
index b2a60e2..0000000
--- a/memhub/apps/core/tests/test_memory_processing_diagnostics.py
+++ /dev/null
@@ -1,37 +0,0 @@
-from __future__ import annotations
-
-from one_memory import memory_processing
-
-
-def _failure() -> RuntimeError:
- try:
- memory_processing.memory_task_timeout_seconds("database is locked") # type: ignore[arg-type]
- except ValueError as error:
- return RuntimeError("database is locked").with_traceback(error.__traceback__)
- raise AssertionError("expected invalid timeout")
-
-
-def test_conversation_prepare_failure_includes_safe_message_and_stack(monkeypatch) -> None:
- events: list[dict[str, object]] = []
- monkeypatch.setattr(memory_processing, "diagnostic_event", lambda **event: events.append(event))
-
- memory_processing._report_conversation_prepare_failure("workbuddy", _failure())
-
- assert events[0]["error_type"] == "RuntimeError"
- assert events[0]["details"] == {
- "source_id": "workbuddy",
- "reason": "database is locked",
- }
- assert events[0]["safe_stack"]
- assert "/Users/" not in str(events[0]["safe_stack"])
-
-
-def test_deletion_sync_failure_includes_safe_message_and_stack(monkeypatch) -> None:
- events: list[dict[str, object]] = []
- monkeypatch.setattr(memory_processing, "diagnostic_event", lambda **event: events.append(event))
-
- memory_processing._report_deletion_sync_failure(_failure())
-
- assert events[0]["error_type"] == "RuntimeError"
- assert events[0]["details"] == {"reason": "database is locked"}
- assert events[0]["safe_stack"]
diff --git a/memhub/apps/core/tests/test_memory_server_durable_queue.py b/memhub/apps/core/tests/test_memory_server_durable_queue.py
index 0a8f075..60b0f23 100644
--- a/memhub/apps/core/tests/test_memory_server_durable_queue.py
+++ b/memhub/apps/core/tests/test_memory_server_durable_queue.py
@@ -16,7 +16,6 @@ from hashlib import sha256
import pytest
from one_memory.database_access import main_database
-from one_memory.hy_memory_bridge import HyMemoryBridgeError
from one_memory.memory_server.contracts import BatchIdentity, WriteRequest
from one_memory.memory_server.durable_queue import (
CANCELLED,
@@ -821,20 +820,20 @@ def test_same_turn_replayed_by_live_sync_upgrades_priority_without_conflict(tmp_
class _Recorder:
- """Stands in for `MemoryProcessingSupervisor.process_records`."""
+ """Stands in for the SDK-authority processor."""
def __init__(self, error: Exception | None = None, *, invoke_hy: bool = False) -> None:
self.seen: list[tuple[str, ...]] = []
self.error = error
self.invoke_hy = invoke_hy
- async def process_records(self, records, **_kwargs):
+ async def process_sdk_job(self, records, **_kwargs):
self.seen.append(tuple(record.evidence_id for record in records))
if self.invoke_hy:
await _kwargs["before_hy_invocation"]()
if self.error is not None:
raise self.error
- return ()
+ return type("Receipt", (), {"raw_ids": (), "memory_ids": ()})()
class _TwoInvocationRecorder:
@@ -842,24 +841,28 @@ class _TwoInvocationRecorder:
self.pause_after_first = pause_after_first
self.invocations = 0
- async def process_records(self, _records, **kwargs):
+ async def process_sdk_job(self, _records, **kwargs):
await kwargs["before_hy_invocation"]()
self.invocations += 1
self.pause_after_first()
await kwargs["before_hy_invocation"]()
self.invocations += 1
- return ()
+ return type("Receipt", (), {"raw_ids": (), "memory_ids": ()})()
class _EvidenceStore:
def __init__(self, known: set[str]) -> None:
self.known = known
+ self.released: list[tuple[str, ...]] = []
def get(self, evidence_id: str):
if evidence_id not in self.known:
return None
return type("Record", (), {"evidence_id": evidence_id})()
+ def release_sdk_staging(self, evidence_ids: tuple[str, ...]) -> None:
+ self.released.append(evidence_ids)
+
def _state(path, job_id: str) -> str:
rows = _rows(path)
@@ -879,7 +882,7 @@ def _claim_through_drain(queue: DurableWriteQueue, job_id: str) -> None:
def test_a_durable_job_is_processed_through_the_authorized_path(tmp_path) -> None:
- """The executor must not bypass `process_records` (permission + runner)."""
+ """The executor must use the SDK-authority processor."""
path = tmp_path / "one-memory.sqlite3"
queue = DurableWriteQueue(path)
record = queue.submit(_request(evidence=("e1", "e2")))
@@ -906,7 +909,6 @@ def test_execute_job_persists_sdk_ids_returned_after_the_single_add(tmp_path) ->
_claim_through_drain(queue, record.job_id)
class Supervisor:
- sdk_authority = staticmethod(lambda: True)
calls = 0
@classmethod
@@ -918,21 +920,11 @@ def test_execute_job_persists_sdk_ids_returned_after_the_single_add(tmp_path) ->
(),
{
"raw_ids": ("raw-1",),
- "memories": (
- type("Memory", (), {"memory_id": "memory-1"})(),
- type("Memory", (), {"memory_id": "memory-2"})(),
- ),
+ "memory_ids": ("memory-1", "memory-2"),
},
)()
- class Evidence(_EvidenceStore):
- released: tuple[str, ...] = ()
-
- def release_sdk_staging(self, evidence_ids):
- self.released = evidence_ids
- return len(evidence_ids)
-
- evidence = Evidence({"e1"})
+ evidence = _EvidenceStore({"e1"})
asyncio.run(
execute_job(
record.job_id,
@@ -947,7 +939,210 @@ def test_execute_job_persists_sdk_ids_returned_after_the_single_add(tmp_path) ->
assert Supervisor.calls == 1
assert receipt.raw_ids == ("raw-1",)
assert receipt.memory_ids == ("memory-1", "memory-2")
- assert evidence.released == ("e1",)
+ assert evidence.released == [("e1",)]
+
+
+class _SdkPublicClient:
+ def __init__(self) -> None:
+ self.calls: list[tuple[str, object, dict[str, object]]] = []
+ self.events: list[str] = []
+ self.outcome: object = None
+
+ def add(self, data, **kwargs):
+ self.events.append("add")
+ self.calls.append(("add", data, kwargs))
+ return {
+ "success": True,
+ "raw_ids": ["raw-1"],
+ "memory_id": "memory-1",
+ "experience_ids": ["experience-1"],
+ "fact_ids": ["fact-1"],
+ "variant": "coding",
+ }
+
+ def add_extracted(self, contents, **kwargs):
+ self.events.append("add_extracted")
+ self.calls.append(("add_extracted", contents, kwargs))
+ return {"success": True, "memory_ids": ["memory-note"]}
+
+ def get_write_outcome(self, request_id):
+ self.calls.append(("get_write_outcome", request_id, {}))
+ return self.outcome
+
+
+class _SdkPublicHandle:
+ def __init__(self, client: _SdkPublicClient) -> None:
+ self.value = client
+
+ async def client(self):
+ return self.value
+
+ async def close(self):
+ pass
+
+
+def _sdk_evidence(
+ evidence_id: str,
+ *,
+ role: str = "user",
+ text: str = "hello",
+ memory_content: bool = False,
+ source: str = "cursor",
+ manual_note: bool = False,
+ created_at: datetime | None = None,
+):
+ from one_memory.imports.models import (
+ EvidenceContentKind,
+ EvidenceInput,
+ EvidenceOrigin,
+ OriginMetadata,
+ WrittenBy,
+ materialize_write_input,
+ )
+
+ origin = (
+ OriginMetadata(raw_meta={"input_mode": "direct_memory_note"})
+ if manual_note
+ else OriginMetadata()
+ )
+ return materialize_write_input(
+ EvidenceInput(
+ source_id=source,
+ workspace="repo-a",
+ conversation_id="session-1",
+ message_id=evidence_id,
+ content_kind=(
+ EvidenceContentKind.MEMORY_CONTENT
+ if memory_content
+ else EvidenceContentKind.RAW_CONVERSATION
+ ),
+ role=role,
+ written_by=WrittenBy.PERSON if role == "user" else WrittenBy.AGENT,
+ created_at=created_at,
+ verbatim=text,
+ origin_meta={EvidenceOrigin.MANUAL_IMPORT: origin},
+ )
+ )
+
+
+def test_sdk_write_processor_calls_add_once_with_public_scope_and_receipt() -> None:
+ from one_memory.sdk_write_processor import PRODUCT_AGENT_ID, SdkWriteProcessor, SdkWriteReceipt
+
+ client = _SdkPublicClient()
+ processor = SdkWriteProcessor(_SdkPublicHandle(client)) # type: ignore[arg-type]
+ memory_at = datetime(2026, 10, 22, 8, tzinfo=UTC)
+ records = (
+ _sdk_evidence("one", text="question", created_at=memory_at),
+ _sdk_evidence(
+ "two",
+ role="assistant",
+ text="answer",
+ created_at=memory_at + timedelta(seconds=1),
+ ),
+ _sdk_evidence("three", role="tool", text="result", created_at=memory_at),
+ )
+
+ async def run() -> SdkWriteReceipt:
+ async def before() -> None:
+ client.events.append("before")
+
+ return await processor.process_sdk_job(
+ records,
+ request_id="request-1",
+ before_hy_invocation=before,
+ )
+
+ receipt = asyncio.run(run())
+
+ assert client.events == ["before", "add"]
+ assert len(client.calls) == 1
+ method, messages, kwargs = client.calls[0]
+ assert method == "add"
+ assert messages == [
+ {"role": "user", "content": "question"},
+ {"role": "assistant", "content": "answer"},
+ {"role": "tool", "content": "result"},
+ ]
+ assert kwargs["user_id"] == "local"
+ assert kwargs["agent_id"] == PRODUCT_AGENT_ID
+ assert kwargs["session_id"] == "session-1"
+ assert kwargs["source"] == "cursor"
+ assert kwargs["workspace_id"] == "repo-a"
+ assert kwargs["memory_at"] == memory_at + timedelta(seconds=1)
+ assert kwargs["request_id"] == "request-1"
+ assert kwargs["metadata"] == {
+ "source_id": "cursor",
+ "session_id": "session-1",
+ "workspace_ids": ["repo-a"],
+ "memory_at": (memory_at + timedelta(seconds=1)).isoformat(),
+ "evidence_ids": [record.evidence_id for record in records],
+ "input_kind": "raw_conversation",
+ }
+ assert receipt == SdkWriteReceipt(
+ raw_ids=("raw-1",),
+ memory_ids=("memory-1", "experience-1", "fact-1"),
+ )
+
+
+ "record",
+ (
+ _sdk_evidence("memory", text="remember this", memory_content=True),
+ _sdk_evidence(
+ "note",
+ text="save this note",
+ source="one-memory-manual",
+ manual_note=True,
+ ),
+ ),
+)
+def test_sdk_write_processor_uses_add_extracted_for_memory_content_and_notes(record) -> None:
+ from one_memory.sdk_write_processor import SdkWriteProcessor, SdkWriteReceipt
+
+ client = _SdkPublicClient()
+ processor = SdkWriteProcessor(_SdkPublicHandle(client)) # type: ignore[arg-type]
+
+ async def run() -> SdkWriteReceipt:
+ async def before() -> None:
+ client.events.append("before")
+
+ return await processor.process_sdk_job(
+ (record,),
+ request_id=record.evidence_id,
+ before_hy_invocation=before,
+ )
+
+ assert asyncio.run(run()) == SdkWriteReceipt(memory_ids=("memory-note",))
+ assert client.events == ["before", "add_extracted"]
+ assert client.calls[0][1] == [record.verbatim]
+ assert len(client.calls) == 1
+
+
+def test_sdk_unknown_outcome_inquiry_uses_only_public_receipt() -> None:
+ from one_memory.sdk_write_processor import SdkWriteProcessor, SdkWriteReceipt
+
+ client = _SdkPublicClient()
+ processor = SdkWriteProcessor(_SdkPublicHandle(client)) # type: ignore[arg-type]
+ client.outcome = {"status": "unknown", "result": {"success": False}}
+ assert asyncio.run(processor.inquire_write_outcome("request-1")) is None
+
+ client.outcome = {
+ "status": "succeeded",
+ "result": {
+ "success": True,
+ "raw_ids": ["raw-1"],
+ "fact_ids": ["fact-1"],
+ "variant": "working",
+ },
+ }
+ assert asyncio.run(processor.inquire_write_outcome("request-1")) == SdkWriteReceipt(
+ raw_ids=("raw-1",),
+ memory_ids=("fact-1",),
+ )
+ assert [call[0] for call in client.calls] == [
+ "get_write_outcome",
+ "get_write_outcome",
+ ]
def test_missing_evidence_is_refused_without_calling_the_model(tmp_path) -> None:
@@ -1978,7 +2173,7 @@ def test_execute_job_crash_after_marking_hy_invoked_becomes_sticky_unknown(tmp_p
drain.claim(limit=1)
class _CancelledBeforeReturn:
- async def process_records(self, _records, **_kwargs):
+ async def process_sdk_job(self, _records, **_kwargs):
raise asyncio.CancelledError
with pytest.raises(asyncio.CancelledError):
@@ -4978,7 +5173,7 @@ def test_a_refused_source_context_is_nonblocking_unknown(
record.job_id,
queue=queue,
supervisor=_Recorder(
- error=HyMemoryBridgeError("hy_memory_write_verification_context_scope"),
+ error=RuntimeError("hy_memory_write_verification_context_scope"),
invoke_hy=True,
),
evidence=_EvidenceStore({"e1"}),
@@ -5006,7 +5201,7 @@ def test_a_failure_after_the_call_still_parks_as_unknown(tmp_path) -> None:
claimer = DurableWriteDrain(queue, execute=_never_execute, owner="after-call-owner")
assert claimer.claim(limit=1) == (record.job_id,)
recorder = _Recorder(
- error=HyMemoryBridgeError("hy_memory_write_verification_authority_invalid"),
+ error=RuntimeError("hy_memory_write_verification_authority_invalid"),
invoke_hy=True,
)
diff --git a/memhub/apps/core/tests/test_memory_supersede.py b/memhub/apps/core/tests/test_memory_supersede.py
index a219680..5f5ed2e 100644
--- a/memhub/apps/core/tests/test_memory_supersede.py
+++ b/memhub/apps/core/tests/test_memory_supersede.py
@@ -509,10 +509,10 @@ def test_the_api_shows_the_chain_refuses_edits_and_still_deletes_through_hy(tmp_
cascaded: list[str] = []
- async def delete_hy_memory(memory_id: str) -> None:
+ async def finish_deletion(memory_id: str) -> None:
cascaded.append(memory_id)
- app.state.memory_processing_supervisor.delete_hy_memory = delete_hy_memory
+ app.state.sdk_memory_runtime.finish_deletion = finish_deletion
deleted = await client.post(
"/api/v1/memories/old/actions/delete",
json={"request_id": "delete-x", "expected_revision": replaced.revision},
diff --git a/memhub/apps/core/tests/test_memory_tasks.py b/memhub/apps/core/tests/test_memory_tasks.py
index b8f0abe..d6690bd 100644
--- a/memhub/apps/core/tests/test_memory_tasks.py
+++ b/memhub/apps/core/tests/test_memory_tasks.py
@@ -861,7 +861,7 @@ def test_clearing_drops_payloads_of_a_failed_task_at_the_retry_ceiling(tmp_path)
def test_clearing_never_touches_completed_tasks(tmp_path) -> None:
"""Completed inputs are evidence of what HY was actually given.
- `memory_processing` compares them against the records sent to HY to prove
+ SDK write processing compares them against the records sent to HY to prove
coverage, and `matters/discovery` reads them to report how many records HY
saw. Clearing them would make a failed coverage check look like a pass.
"""
diff --git a/memhub/apps/core/tests/test_onboarding_profile.py b/memhub/apps/core/tests/test_onboarding_profile.py
index f401155..7fae0ad 100644
--- a/memhub/apps/core/tests/test_onboarding_profile.py
+++ b/memhub/apps/core/tests/test_onboarding_profile.py
@@ -1,263 +1,28 @@
-"""R-09:首次安装引导把画像录下来,不问用户一句话。
-
-引导导完来源就结束了,从不归纳一次画像。`digest()` 全仓唯一的调用方是
-记忆空间里那个按钮(`MemorySpace.tsx:265`),也就是说首次安装走完,
-System 2 归纳出的画像一条都不在治理层里,新装的库对「我是谁」一无所知,
-而证据其实已经导进来了。
-
-归纳本身还漏了一半:`_record_schemas` 只挑 `L6_SCHEMA` 节点,
-`L0_BASIC_INFO` 直接跳过。`_read_graph_snapshot` 的查询不带 layer 过滤,
-L0 节点本来就在快照里,取回来了又丢掉。HY 自己把这两层并称画像
-(`_PROFILE_LAYERS = {"l0_basic_info", "l6_schema"}`),
-basic info 那半边留在 Kuzu 里,本地看不见。
-"""
+"""Onboarding endpoints manage UI state without touching SDK memory."""
import asyncio
-import sqlite3
+from pathlib import Path
from httpx import ASGITransport, AsyncClient
from pydantic import SecretStr
from one_memory.api import create_app
from one_memory.config import Settings
-from one_memory.hy_memory_bridge import HyGraphNode, HyGraphSnapshot, HyMemoryBridgeError
-from one_memory.imports.models import (
- EvidenceContentKind,
- EvidenceInput,
- EvidenceOrigin,
- OriginMetadata,
- WrittenBy,
-)
-from one_memory.imports.storage import EvidenceStore
-from one_memory.memory_governance import (
- MemoryDraft,
- MemoryGovernanceStore,
- MemoryKind,
- MemoryStatus,
-)
-from one_memory.memory_processing import MemoryProcessingSupervisor
-from one_memory.memory_tasks import MemoryTaskStore
-from one_memory.model_profiles import (
- ModelCapabilities,
- ModelProfileInput,
- ModelProfileStore,
- ProviderKind,
-)
-from one_memory.secrets import InMemorySecretStore
-from tests.person_door import as_person
-
-
-class FakeGraph:
- """归纳只用得上四个方法,其余不实现,少一个假实现少一处失真。"""
-
- def __init__(self, graph_nodes: tuple[HyGraphNode, ...]) -> None:
- self.graph_nodes = graph_nodes
- self.graph_reads: list[tuple[str, str]] = []
- self.digest_calls: list[tuple[str, str]] = []
-
- async def digest(self, *, user_id: str, agent_id: str) -> dict[str, object]:
- self.digest_calls.append((user_id, agent_id))
- return {"success": True, "tasks_processed": 1}
-
- async def graph_snapshot(
- self,
- *,
- user_id: str,
- agent_id: str,
- limit: int = 300,
- ) -> HyGraphSnapshot:
- self.graph_reads.append((user_id, agent_id))
- return HyGraphSnapshot(nodes=self.graph_nodes, edges=())
-
- async def list_agent_ids(self, *, user_id: str, limit: int = 1_000) -> tuple[str, ...]:
- return ()
-
- async def close(self) -> None:
- return None
-
-
-def _setup(tmp_path):
- database = tmp_path / "one-memory.sqlite3"
- secrets = InMemorySecretStore()
- evidence = EvidenceStore(database)
- profiles = ModelProfileStore(database)
- tasks = MemoryTaskStore(database)
- governance = MemoryGovernanceStore(database)
- profile = profiles.create(
- ModelProfileInput(
- name="Local",
- provider_kind=ProviderKind.OLLAMA,
- model="hy-bot-phi4",
- embedding_model="nomic-embed-text",
- ),
- 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,
- )
- profile = profiles.activate(profile.profile_id, secrets)
- return evidence, profiles, tasks, governance, secrets, profile
-
-
-def _imported(evidence: EvidenceStore, *, workspace: str | None = "workspace:v1:project"):
- return evidence.put(
- EvidenceInput(
- source_id="cursor",
- workspace=workspace,
- conversation_id="conversation",
- message_id="m1",
- correlation_id="m1",
- content_kind=EvidenceContentKind.RAW_CONVERSATION,
- role="user",
- written_by=WrittenBy.PERSON,
- verbatim="导入进来的一段对话。",
- origin_meta={EvidenceOrigin.FILE: OriginMetadata()},
- )
- ).record
-
-
-def _confirmed_from(governance: MemoryGovernanceStore, evidence_id: str) -> None:
- """归纳只对「还有本地证据的 scope」动手,所以得先有一条确认记忆。"""
- as_person(governance).create(
- MemoryDraft(
- user_id="local",
- kind=MemoryKind.CHAT,
- content="项目里的一条既有记忆。",
- scopes=("workspace:v1:project",),
- evidence_ids=(evidence_id,),
- ),
- request_id="candidate-1",
- )
-
-
-def _supervisor(tmp_path, stores, bridge) -> MemoryProcessingSupervisor:
- evidence, profiles, tasks, governance, secrets, profile = stores
- supervisor = MemoryProcessingSupervisor(
- tasks=tasks,
- profiles=profiles,
- secrets=secrets,
- evidence=evidence,
- governance=governance,
- data_dir=tmp_path,
- )
- supervisor._bridges[(profile.profile_id, profile.revision, None)] = bridge
- return supervisor
-
-
-def test_the_basic_info_half_of_the_profile_is_written_down_too(tmp_path) -> None:
- """L0_BASIC_INFO 取回来了又被丢掉,画像只进了一半。
-
- HY 自己把 L0_basic_info 与 L6_schema 并称画像,快照里两层都在,
- 而 `_record_schemas` 只留 L6。零提问录画像要的正是 L0 这半边:
- 「用户是一名产品经理」这种事实,只会出现在 basic info 层。
- """
- stores = _setup(tmp_path)
- evidence, _profiles, _tasks, governance, _secrets, _profile = stores
- record = _imported(evidence)
- _confirmed_from(governance, record.evidence_id)
- bridge = FakeGraph(
- graph_nodes=(
- HyGraphNode(
- node_id="basic-1",
- content="用户是一名非技术背景的产品经理。",
- layer="l0_basic_info",
- ),
- HyGraphNode(
- node_id="schema-1",
- content="用户偏好可验证的结论。",
- layer="l6_schema",
- ),
- ),
- )
- supervisor = _supervisor(tmp_path, stores, bridge)
- result = asyncio.run(supervisor.digest())
- profile_contents = {
- memory.content: memory
- for memory in governance.list(user_id="local")
- if memory.scopes == ("all-apps",)
- }
- assert "用户是一名非技术背景的产品经理。" in profile_contents
- assert "用户偏好可验证的结论。" in profile_contents
- assert result["schemas_recorded"] == 2
- basic = profile_contents["用户是一名非技术背景的产品经理。"]
- assert basic.status is MemoryStatus.CONFIRMED
- # 说得出为什么相信它,和 L6 那半边同一个标准。
- assert basic.evidence_ids == (record.evidence_id,)
- # kind 用仓库既有的 layer→kind 映射,不为画像新造一个种类
- # (种类是 API 契约的一部分,新增要人放行)。
- assert basic.kind is MemoryKind.CHAT
-
-
-def test_a_layer_hy_does_not_call_profile_still_never_reaches_governance(tmp_path) -> None:
- """绿对照,也是这一项的防假修复守卫。
-
- 把「只挑 L6」改成「快照里的都带回来」能让上面那条变绿,代价是
- 整段原始对话(L1_RAW)被当成画像广播给每个 app。这条盯着它。
- """
- stores = _setup(tmp_path)
- evidence, _profiles, _tasks, governance, _secrets, _profile = stores
- record = _imported(evidence)
- _confirmed_from(governance, record.evidence_id)
- bridge = FakeGraph(
- graph_nodes=tuple(
- HyGraphNode(node_id=f"node-{layer}", content=f"{layer} 的内容。", layer=layer)
- for layer in ("l1_raw", "l2_fact", "l3_summary", "l4_identity", "l7_intention")
+def _app(tmp_path: Path):
+ return create_app(
+ Settings(
+ _env_file=None,
+ data_dir=tmp_path / "data",
+ source_home=tmp_path / "home",
+ api_token=SecretStr("test-token"),
+ imports_enabled=False,
+ automatic_memory_processing=False,
+ live_sync_enabled=False,
),
+ source_catalog={},
)
- supervisor = _supervisor(tmp_path, stores, bridge)
-
- result = asyncio.run(supervisor.digest())
-
- assert result["schemas_recorded"] == 0
- assert [memory.content for memory in governance.list(user_id="local")] == [
- "项目里的一条既有记忆。"
- ]
-
-
-def test_the_same_basic_info_is_not_written_twice(tmp_path) -> None:
- """绿对照:归纳会被反复触发(引导一次、按钮随时),不能越攒越多。"""
- stores = _setup(tmp_path)
- evidence, _profiles, _tasks, governance, _secrets, _profile = stores
- record = _imported(evidence)
- _confirmed_from(governance, record.evidence_id)
- nodes = (
- HyGraphNode(
- node_id="basic-1",
- content="用户是一名非技术背景的产品经理。",
- layer="l0_basic_info",
- ),
- )
- supervisor = _supervisor(tmp_path, stores, FakeGraph(graph_nodes=nodes))
-
- first = asyncio.run(supervisor.digest())
- second = asyncio.run(supervisor.digest())
-
- assert first["schemas_recorded"] == 1
- assert second["schemas_recorded"] == 0
- assert [
- memory.content
- for memory in governance.list(user_id="local")
- if memory.scopes == ("all-apps",)
- ] == ["用户是一名非技术背景的产品经理。"]
-
-
-def _app(tmp_path):
- settings = Settings(
- data_dir=tmp_path / "data",
- source_home=tmp_path / "home",
- api_token=SecretStr("test-token"),
- )
- return create_app(settings, source_catalog={})
def _client(app) -> AsyncClient:
@@ -271,83 +36,47 @@ def _client(app) -> AsyncClient:
)
-def test_finishing_onboarding_is_not_model_content_consent(tmp_path) -> None:
- """S1.3: completion and skip cannot authorize profile induction."""
-
+def test_finishing_onboarding_is_not_model_content_consent(tmp_path: Path) -> None:
async def scenario() -> None:
app = _app(tmp_path)
async with app.router.lifespan_context(app), _client(app) as client:
calls: list[str] = []
- async def spy() -> dict[str, object]:
+ async def digest() -> dict[str, object]:
calls.append("digest")
- return {"success": True, "schemas_recorded": 0}
-
- app.state.memory_processing_supervisor.digest = spy # type: ignore[method-assign]
-
- # 只是看一眼引导状态,不该触发归纳。
- assert (await client.get("/api/v1/onboarding")).status_code == 200
- assert calls == []
+ return {"success": True}
+ app.state.sdk_memory_runtime.digest = digest
finished = await client.post("/api/v1/onboarding/complete")
+ assert finished.status_code == 200
assert finished.json()["status"] == "completed"
assert calls == []
asyncio.run(scenario())
-def test_the_way_back_to_the_first_run_deletes_nothing(tmp_path) -> None:
- """重置只动完成标记,记忆一条不少。
-
- 完成态和记忆放在同一个库里是有意的:重装一遍 App 不该把一个已经有记忆的人
- 当成新用户。代价是想再看一次冷启动,重装不管用。这条盯着那个出口:
- 状态回到首次运行,别的都不动。
- """
-
+def test_reset_returns_to_first_run_without_touching_sdk_data(tmp_path: Path) -> None:
async def scenario() -> None:
app = _app(tmp_path)
async with app.router.lifespan_context(app), _client(app) as client:
- database = tmp_path / "data" / "one-memory.sqlite3"
- with sqlite3.connect(database) as connection:
- connection.execute(
- "INSERT INTO governed_memories "
- "(memory_id,user_id,kind,status,content,scopes_json,"
- "revision,created_at,updated_at) VALUES (?,?,?,?,?,?,?,?,?)",
- (
- "keep-me",
- "local",
- "chat",
- "confirmed",
- "记忆必须保留",
- '["all-apps"]',
- 1,
- "2026-10-17T00:00:00+00:00",
- "2026-10-17T00:00:00+00:00",
- ),
- )
- finished = await client.post("/api/v1/onboarding/complete")
-
- assert finished.json()["status"] == "completed"
+ sdk_marker = tmp_path / "data" / "hy-memory" / "governed-v2" / "memory.marker"
+ sdk_marker.parent.mkdir(parents=True, exist_ok=True)
+ sdk_marker.write_text("keep-sdk-memory", encoding="utf-8")
+ assert (await client.post("/api/v1/onboarding/complete")).status_code == 200
reset = await client.post("/api/v1/onboarding/reset")
assert reset.status_code == 200
assert reset.json()["status"] == "not_started"
assert reset.json()["completed_at"] is None
- # 落盘了,不是只在响应里改一下:下一次启动读到的也是首次运行。
assert (await client.get("/api/v1/onboarding")).json()["status"] == "not_started"
- with sqlite3.connect(database) as connection:
- assert connection.execute(
- "SELECT content,revision FROM governed_memories WHERE memory_id='keep-me'"
- ).fetchone() == ("记忆必须保留", 1)
+ assert sdk_marker.read_text(encoding="utf-8") == "keep-sdk-memory"
asyncio.run(scenario())
-def test_resetting_before_anything_was_completed_is_not_an_error(tmp_path) -> None:
- """绿对照:新库里还没有那一行,重置不能炸。"""
-
+def test_resetting_before_completion_is_not_an_error(tmp_path: Path) -> None:
async def scenario() -> None:
app = _app(tmp_path)
async with app.router.lifespan_context(app), _client(app) as client:
@@ -359,28 +88,17 @@ def test_resetting_before_anything_was_completed_is_not_an_error(tmp_path) -> No
asyncio.run(scenario())
-def test_hy_being_down_does_not_leave_the_first_install_unfinished(tmp_path) -> None:
- """守卫:这一步可跳过,归纳失败不能把引导卡住。
-
- 首次安装时模型档案可能还没配好,通用出站网络也可能不可用。
- 归纳失败只该少一条画像,不该让人装不完。
- """
-
+def test_sdk_unavailability_cannot_block_onboarding_completion(tmp_path: Path) -> None:
async def scenario() -> None:
app = _app(tmp_path)
async with app.router.lifespan_context(app), _client(app) as client:
-
async def unavailable() -> dict[str, object]:
- raise HyMemoryBridgeError("hy_memory_unavailable")
-
- app.state.memory_processing_supervisor.digest = unavailable # type: ignore[method-assign]
+ raise RuntimeError("hy_sdk_unavailable")
+ app.state.sdk_memory_runtime.digest = unavailable
finished = await client.post("/api/v1/onboarding/complete")
assert finished.status_code == 200
assert finished.json()["status"] == "completed"
- assert finished.json()["completed_at"] is not None
- # 状态是真的落了盘,不是只在这次响应里。
- assert (await client.get("/api/v1/onboarding")).json()["status"] == "completed"
asyncio.run(scenario())
diff --git a/memhub/apps/core/tests/test_recall.py b/memhub/apps/core/tests/test_recall.py
index da58017..bc41558 100644
--- a/memhub/apps/core/tests/test_recall.py
+++ b/memhub/apps/core/tests/test_recall.py
@@ -3,7 +3,7 @@ import hashlib
import pytest
-from one_memory.hy_memory_bridge import HySdkMemoryRecord
+from one_memory.hy_sdk_types import HySdkMemoryRecord
from one_memory.imports.models import EvidenceInput, EvidenceOrigin, OriginMetadata, WrittenBy
from one_memory.imports.storage import EvidenceStore
from one_memory.memory_governance import MemoryDraft, MemoryGovernanceStore, MemoryKind
diff --git a/memhub/apps/core/tests/test_recall_fusion_live.py b/memhub/apps/core/tests/test_recall_fusion_live.py
index 8abb525..03e8832 100644
--- a/memhub/apps/core/tests/test_recall_fusion_live.py
+++ b/memhub/apps/core/tests/test_recall_fusion_live.py
@@ -127,9 +127,17 @@ def test_both_lanes_answer_through_one_real_hy_instance(tmp_path, monkeypatch):
linked.raise_for_status()
job = await app.state.import_supervisor.wait(linked.json()["jobs"][0]["job_id"])
assert job.stored == 1 and job.errors == 0, job
- processor = app.state.memory_processing_supervisor
- await asyncio.gather(*tuple(processor._debounces.values()), return_exceptions=True)
- await asyncio.wait_for(asyncio.gather(*tuple(processor._workers.values())), timeout=300)
+ deadline = asyncio.get_running_loop().time() + 300
+ while True:
+ counts = app.state.sdk_memory_runtime.status_counts()
+ if not any(
+ counts.get(state, 0)
+ for state in ("pending", "running", "waiting_for_model")
+ ):
+ break
+ if asyncio.get_running_loop().time() >= deadline:
+ raise AssertionError(f"SDK write queue did not drain: {counts}")
+ await asyncio.sleep(0.05)
# Imported content is not shared with every app by default. Sharing
# it here is what the memory lane is later asked to find.
diff --git a/memhub/apps/core/tests/test_retrieval_lifespan.py b/memhub/apps/core/tests/test_retrieval_lifespan.py
index 3b7fd82..543e3ab 100644
--- a/memhub/apps/core/tests/test_retrieval_lifespan.py
+++ b/memhub/apps/core/tests/test_retrieval_lifespan.py
@@ -216,13 +216,13 @@ def test_retrieval_stop_failure_still_drains_other_owned_services(tmp_path, monk
)
with pytest.raises(failure):
async with app.router.lifespan_context(app):
- original = app.state.memory_processing_supervisor.shutdown
+ original = app.state.sdk_memory_runtime.shutdown
async def shutdown():
await original()
events.append("processing_drained")
- monkeypatch.setattr(app.state.memory_processing_supervisor, "shutdown", shutdown)
+ monkeypatch.setattr(app.state.sdk_memory_runtime, "shutdown", shutdown)
assert events == ["start", "retrieval_drained", "processing_drained"]
assert not (tmp_path / "runtime.json").exists()
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 66886f8..3c124d0 100644
--- a/memhub/apps/core/tests/test_sdk_data_plane_migration.py
+++ b/memhub/apps/core/tests/test_sdk_data_plane_migration.py
@@ -6,7 +6,12 @@ import json
import pytest
from one_memory.database_access import close_main_databases, main_database
-from one_memory.hy_memory_bridge import HySdkMemoryPage, HySdkMemoryRecord, HySdkRawRecord
+from one_memory.hy_sdk_types import (
+ HySdkMemoryPage,
+ HySdkMemoryRecord,
+ HySdkRawPage,
+ HySdkRawRecord,
+)
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
@@ -410,7 +415,7 @@ def test_inventory_classification_covers_every_legacy_and_sdk_state():
assert len(decisions) == 8
-class _Bridge:
+class _MigrationClient:
def __init__(self, memories=()):
self.memories = tuple(memories)
self.imported = []
@@ -418,7 +423,7 @@ class _Bridge:
self.deleted = []
self.raw = ()
- async def list_sdk_memories(self, *, limit, offset, **_kwargs):
+ async def list_memories(self, *, limit, offset, **_kwargs):
page = self.memories[offset : offset + limit]
return HySdkMemoryPage(
memories=page,
@@ -427,7 +432,7 @@ class _Bridge:
offset=offset,
)
- async def import_sdk_memory_exact(self, **kwargs):
+ async def import_memory_exact(self, **kwargs):
self.imported.append(kwargs)
return {"success": True, "memory_id": kwargs["memory_id"]}
@@ -435,11 +440,16 @@ class _Bridge:
self.deleted.append(memory_id)
return {"success": True, "deleted_count": 1}
- async def list_sdk_raw(self, *, limit, offset, **_kwargs):
+ async def list_raw(self, *, limit, offset, **_kwargs):
rows = self.raw[offset : offset + limit]
- return rows, len(self.raw)
+ return HySdkRawPage(
+ raw=rows,
+ total=len(self.raw),
+ limit=limit,
+ offset=offset,
+ )
- async def import_sdk_raw_exact(self, **kwargs):
+ async def import_raw(self, **kwargs):
self.imported_raw.append(kwargs)
return {"success": True, "raw_id": kwargs["raw_id"]}
@@ -466,14 +476,14 @@ def _record(memory_id, *, content="body", status="active"):
def test_sdk_inventory_is_paged_without_dropping_lifecycle_records():
- bridge = _Bridge(
+ client = _MigrationClient(
(
_record("active"),
_record("old", status="superseded"),
_record("shadow", status="shadow"),
)
)
- inventory = asyncio.run(read_sdk_memory_inventory(bridge, page_size=2))
+ inventory = asyncio.run(read_sdk_memory_inventory(client, page_size=2))
assert [(item.memory_id, item.status) for item in inventory] == [
("active", "active"),
("old", "superseded"),
@@ -502,10 +512,10 @@ def test_recorded_plan_executes_import_delete_alias_and_adoption(store):
legacy=legacy,
sdk=sdk,
)
- bridge = _Bridge()
+ client = _MigrationClient()
asyncio.run(
execute_memory_migration_plan(
- bridge,
+ client,
store,
migration_id="m1",
legacy=legacy,
@@ -513,8 +523,8 @@ def test_recorded_plan_executes_import_delete_alias_and_adoption(store):
)
)
- assert [item["memory_id"] for item in bridge.imported] == ["missing"]
- assert bridge.deleted == ["delete-existing"]
+ assert [item["memory_id"] for item in client.imported] == ["missing"]
+ assert client.deleted == ["delete-existing"]
progress = store.progress("m1")
assert progress.counts == {"adopted": 1, "deleted": 2, "verified": 3}
@@ -590,23 +600,23 @@ def test_raw_inventory_matches_exact_scope_imports_missing_and_adopts_sdk_only(s
legacy=legacy,
sdk=sdk,
)
- bridge = _Bridge()
+ client = _MigrationClient()
asyncio.run(
execute_raw_migration_plan(
- bridge,
+ client,
store,
migration_id="m1",
legacy=legacy,
decisions=recorded,
)
)
- assert [item["raw_id"] for item in bridge.imported_raw] == ["evidence:e2"]
+ assert [item["raw_id"] for item in client.imported_raw] == ["evidence:e2"]
assert store.progress("m1").counts == {"adopted": 1, "verified": 2}
def test_sdk_raw_inventory_pages_all_records():
- bridge = _Bridge()
- bridge.raw = (
+ client = _MigrationClient()
+ client.raw = (
HySdkRawRecord(
raw_id="r1",
content="one",
@@ -624,7 +634,7 @@ def test_sdk_raw_inventory_pages_all_records():
source="claude",
),
)
- inventory = asyncio.run(read_sdk_raw_inventory(bridge, page_size=1))
+ inventory = asyncio.run(read_sdk_raw_inventory(client, page_size=1))
assert [item.raw_id for item in inventory] == ["r1", "r2"]
@@ -656,11 +666,11 @@ def test_offline_backfill_reaches_ready_without_committing_cutover(store):
""",
(content_hash("verbatim"),),
)
- bridge = _Bridge()
+ client = _MigrationClient()
result = asyncio.run(
run_sdk_data_plane_backfill(
database_path=database,
- bridge=bridge,
+ client=client,
migration_id="migration",
bundle_id="bundle",
source_runtime_build="v1.0.4",
@@ -674,15 +684,15 @@ def test_offline_backfill_reaches_ready_without_committing_cutover(store):
assert result.state == "ready"
assert result.phase == "reconciled"
assert result.counts == {"verified": 2}
- assert [item["memory_id"] for item in bridge.imported] == ["memory-1"]
- assert [item["raw_id"] for item in bridge.imported_raw] == ["evidence:e1"]
+ assert [item["memory_id"] for item in client.imported] == ["memory-1"]
+ assert [item["raw_id"] for item in client.imported_raw] == ["evidence:e1"]
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
# import_exact; that reclassification must resume the settled ledger
# instead of conflicting with its original operation key.
- bridge.memories = (_record("memory-1", content="preference"),)
- bridge.raw = (
+ client.memories = (_record("memory-1", content="preference"),)
+ client.raw = (
HySdkRawRecord(
raw_id="evidence:e1",
content="verbatim",
@@ -696,7 +706,7 @@ def test_offline_backfill_reaches_ready_without_committing_cutover(store):
resumed = asyncio.run(
run_sdk_data_plane_backfill(
database_path=database,
- bridge=bridge,
+ client=client,
migration_id="migration",
bundle_id="bundle",
source_runtime_build="v1.0.4",
@@ -708,8 +718,8 @@ def test_offline_backfill_reaches_ready_without_committing_cutover(store):
)
assert resumed.state == "ready"
assert resumed.counts == {"verified": 2}
- assert len(bridge.imported) == 1
- assert len(bridge.imported_raw) == 1
+ assert len(client.imported) == 1
+ assert len(client.imported_raw) == 1
def test_offline_backfill_blocks_cutover_when_an_item_is_quarantined(store):
@@ -729,7 +739,7 @@ def test_offline_backfill_blocks_cutover_when_an_item_is_quarantined(store):
result = asyncio.run(
run_sdk_data_plane_backfill(
database_path=database,
- bridge=_Bridge(),
+ client=_MigrationClient(),
migration_id="migration",
bundle_id="bundle",
source_runtime_build="v1.0.4",
diff --git a/memhub/apps/core/tests/test_sdk_memory_qa.py b/memhub/apps/core/tests/test_sdk_memory_qa.py
index 939bfee..0d381a2 100644
--- a/memhub/apps/core/tests/test_sdk_memory_qa.py
+++ b/memhub/apps/core/tests/test_sdk_memory_qa.py
@@ -1,11 +1,10 @@
from __future__ import annotations
import asyncio
-from types import SimpleNamespace
import pytest
-from one_memory.hy_memory_bridge import HySdkMemoryRecord
+from one_memory.hy_sdk_types import HySdkMemoryRecord
from one_memory.memory_qa import MemoryAnswerError
from one_memory.sdk_memory_qa import SdkMemoryAnswerer
@@ -24,18 +23,29 @@ def record(content: str = "用户偏好本地优先。") -> HySdkMemoryRecord:
)
-class Bridge:
+class Client:
def __init__(self) -> None:
self.current = record()
self.searches = 0
- async def search_memories(self, *_args, **_kwargs):
+ def search(self, *_args, **_kwargs):
self.searches += 1
- return (SimpleNamespace(memory_id="memory-1"),)
+ return {
+ "scene": "normal",
+ "memories": [{"memory_id": "memory-1", "score": 0.9}],
+ }
- async def get_sdk_memory(self, memory_id):
+ def get(self, memory_id):
assert memory_id == "memory-1"
- return self.current
+ return self.current.model_dump()
+
+
+class Handle:
+ def __init__(self, client: Client) -> None:
+ self.value = client
+
+ async def client(self):
+ return self.value
class Profiles:
@@ -45,10 +55,10 @@ class Profiles:
def test_sdk_ask_uses_native_sdk_memory_without_governance_fields() -> None:
- bridge = Bridge()
+ client = Client()
answer = asyncio.run(
SdkMemoryAnswerer(
- bridge=bridge, # type: ignore[arg-type]
+ client_handle=Handle(client),
profiles=Profiles(), # type: ignore[arg-type]
secrets=object(), # type: ignore[arg-type]
).answer("偏好是什么?")
@@ -65,18 +75,18 @@ def test_sdk_ask_uses_native_sdk_memory_without_governance_fields() -> None:
def test_sdk_ask_revalidates_memory_before_returning_extract() -> None:
- bridge = Bridge()
+ client = Client()
class ChangingProfiles:
@staticmethod
def active(_secrets):
- bridge.current = record("内容已变化")
+ client.current = record("内容已变化")
return None
with pytest.raises(MemoryAnswerError, match="memory_answer_context_changed"):
asyncio.run(
SdkMemoryAnswerer(
- bridge=bridge, # type: ignore[arg-type]
+ client_handle=Handle(client),
profiles=ChangingProfiles(), # type: ignore[arg-type]
secrets=object(), # type: ignore[arg-type]
).answer("偏好是什么?")
@@ -84,14 +94,14 @@ def test_sdk_ask_revalidates_memory_before_returning_extract() -> None:
def test_sdk_ask_propagates_sdk_search_failure_without_legacy_fallback() -> None:
- class Failed(Bridge):
- async def search_memories(self, *_args, **_kwargs):
+ class Failed(Client):
+ def search(self, *_args, **_kwargs):
raise RuntimeError("sdk unavailable")
with pytest.raises(RuntimeError, match="sdk unavailable"):
asyncio.run(
SdkMemoryAnswerer(
- bridge=Failed(), # type: ignore[arg-type]
+ client_handle=Handle(Failed()),
profiles=Profiles(), # type: ignore[arg-type]
secrets=object(), # type: ignore[arg-type]
).answer("偏好是什么?")
diff --git a/memhub/apps/core/tests/test_search_without_profile.py b/memhub/apps/core/tests/test_search_without_profile.py
index 3b927c5..a7f6f7a 100644
--- a/memhub/apps/core/tests/test_search_without_profile.py
+++ b/memhub/apps/core/tests/test_search_without_profile.py
@@ -1,190 +1,97 @@
-"""What `semantic_search` should do once the profile that filled the store is gone.
-
-Deactivating or deleting a model profile does not delete the memories that
-profile produced, but `semantic_search` gave up as soon as it could not find
-an active one. The retrieval it abandoned needs no generation model at all:
-the built-in ONNX encoder is what wrote those vectors in the first place.
-"""
+"""Model-free SDK search remains available without an active write profile."""
from pathlib import Path
+from types import SimpleNamespace
import pytest
-from one_memory.hy_memory_bridge import (
- HY_MEMORY_NAMESPACE,
- GraphWidthMismatch,
- GraphWidthMismatchError,
+from one_memory.hy_sdk_runtime import (
+ SdkClientHandle,
builtin_retrieval_snapshot,
)
-from one_memory.imports.storage import EvidenceStore
-from one_memory.memory_governance import MemoryGovernanceStore
-from one_memory.memory_processing import MemoryProcessingSupervisor
-from one_memory.memory_tasks import MemoryTaskStore
-from one_memory.model_profiles import (
- ModelCapabilities,
- ModelProfileInput,
- ModelProfileStore,
- ProviderKind,
-)
-from one_memory.secrets import InMemorySecretStore
-
-
-class RecordingBridge:
- def __init__(self, snapshot, hits: tuple[str, ...] = ()) -> None:
- self.snapshot = snapshot
- self.hits = hits
-
- async def search_scores(self, query: str, **_: object) -> tuple[object, ...]:
- del query
- return tuple((memory_id, 0.9) for memory_id in self.hits)
-
-
-def _supervisor(tmp_path, *, hits: tuple[str, ...] = (), built: list | None = None):
- database = tmp_path / "one-memory.sqlite3"
- secrets = InMemorySecretStore()
- profiles = ModelProfileStore(database)
-
- def factory(snapshot, _secret, data_dir):
- # Building the real client is what creates the store on disk, so the
- # stand-in has to create it too: without that, "no store was built"
- # is a sentence no assertion could ever falsify.
- (data_dir / "hy-memory" / HY_MEMORY_NAMESPACE / "graph").mkdir(
- parents=True,
- exist_ok=True,
- )
- bridge = RecordingBridge(snapshot, hits)
- if built is not None:
- built.append(bridge)
- return bridge
-
- supervisor = MemoryProcessingSupervisor(
- tasks=MemoryTaskStore(database),
- profiles=profiles,
- secrets=secrets,
- evidence=EvidenceStore(database),
- governance=MemoryGovernanceStore(database),
- data_dir=tmp_path,
- bridge_factory=factory,
- )
- return supervisor, profiles, secrets
+from one_memory.model_profiles import ProviderKind
+from one_memory.sdk_memory_runtime import SdkMemoryRuntime
-def _plant_store(tmp_path: Path) -> None:
- """Give the data directory the graph an earlier extraction would have left."""
- graph = tmp_path / "hy-memory" / HY_MEMORY_NAMESPACE / "graph"
- graph.mkdir(parents=True)
- (graph / "catalog.kz").write_bytes(b"")
+class _SearchClient:
+ def __init__(self, reply: dict[str, object]) -> None:
+ self.reply = reply
+ self.calls: list[tuple[str, dict[str, object]]] = []
+ def search(self, query: str, **options: object) -> dict[str, object]:
+ self.calls.append((query, options))
+ return self.reply
-def _activate(profiles, secrets):
- created = profiles.create(
- ModelProfileInput(
- name="Local",
- provider_kind=ProviderKind.OLLAMA,
- model="hy-bot-phi4",
- embedding_model="nomic-embed-text",
- ),
- secrets,
- )
- profiles.record_capabilities(
- created.profile_id,
- expected_revision=created.revision,
- capabilities=ModelCapabilities(
- endpoint_reachable=True,
- model_available=True,
- structured_output=True,
- embedding_available=True,
- ),
- secrets=secrets,
- )
- return profiles.activate(created.profile_id, secrets)
+class _Handle:
+ def __init__(self, client: _SearchClient) -> None:
+ self._client = client
-async def test_a_library_left_by_a_retired_profile_is_still_searchable(tmp_path) -> None:
- supervisor, _profiles, _secrets = _supervisor(tmp_path, hits=("memory-1",))
- _plant_store(tmp_path)
-
- found = await supervisor.semantic_search("抽取")
-
- assert found == (("memory-1", 0.9),)
+ async def client(self) -> _SearchClient:
+ return self._client
-async def test_no_store_on_disk_is_not_a_reason_to_build_one(tmp_path) -> None:
- """Searching must not leave a 512-wide graph behind for an undecided user.
+def _runtime(client: _SearchClient) -> SdkMemoryRuntime:
+ return SdkMemoryRuntime(
+ coordinator=SimpleNamespace(),
+ read_handle=_Handle(client), # type: ignore[arg-type]
+ write_queue=SimpleNamespace(), # type: ignore[arg-type]
+ extraction_settings=SimpleNamespace(), # type: ignore[arg-type]
+ data_dir=Path("/unused"),
+ )
- Building the client is what creates the store, and the width it creates is
- the built-in encoder's. A user who has not chosen a model yet would then
- meet a width mismatch on their first 768-wide profile: an accident this
- search invented, in the same shape as the one that retired a live graph.
- """
- supervisor, _profiles, _secrets = _supervisor(tmp_path, hits=("memory-1",))
- found = await supervisor.semantic_search("抽取")
+def test_builtin_retrieval_handle_needs_no_profile_or_key() -> None:
+ profile = builtin_retrieval_snapshot()
- assert found == ()
- assert not (tmp_path / "hy-memory").exists()
+ assert profile.profile_id == "builtin-retrieval"
+ assert profile.provider_kind is ProviderKind.LOCAL_ONNX
+ assert profile.embedding_provider_kind is ProviderKind.LOCAL_ONNX
+ assert profile.has_api_key is False
@pytest.mark.anyio
-async def test_a_store_written_wider_is_left_to_the_width_prompt(tmp_path) -> None:
- supervisor, _profiles, _secrets = _supervisor(tmp_path)
- _plant_store(tmp_path)
-
- class WiderStore(RecordingBridge):
- async def search_scores(self, query: str, **_: object) -> tuple[object, ...]:
- # Where the real one raises: the client is built lazily, on the
- # first search, and it is building it that reads the stored width.
- del query
- raise GraphWidthMismatchError(
- GraphWidthMismatch(
- stored_width=768,
- expected_width=512,
- graph_path=str(tmp_path / "graph"),
- )
- )
-
- supervisor.bridge_factory = lambda snapshot, _secret, _data_dir: WiderStore(snapshot)
+async def test_sdk_client_handle_lazily_reuses_the_model_free_client(
+ tmp_path: Path,
+ monkeypatch: pytest.MonkeyPatch,
+) -> None:
+ client = _SearchClient({"scene": "normal", "memories": []})
+ lease = SimpleNamespace(client=client, close=lambda: None)
+ acquired: list[object] = []
+
+ def acquire(*args: object, **kwargs: object) -> object:
+ acquired.append((args, kwargs))
+ return lease
+
+ monkeypatch.setattr("one_memory.hy_sdk_runtime.acquire_client", acquire)
+ handle = SdkClientHandle(
+ builtin_retrieval_snapshot(),
+ api_key=None,
+ data_dir=tmp_path,
+ )
- assert await supervisor.semantic_search("抽取") == ()
+ assert await handle.client() is client
+ assert await handle.client() is client
+ assert len(acquired) == 1
+ await handle.close()
@pytest.mark.anyio
-async def test_retrieval_reaches_hy_as_a_local_encoder_needing_no_key(tmp_path) -> None:
- built: list[RecordingBridge] = []
- supervisor, _profiles, _secrets = _supervisor(tmp_path, built=built)
- _plant_store(tmp_path)
-
- await supervisor.semantic_search("抽取")
-
- snapshot = built[0].snapshot
- assert snapshot.embedding_provider_kind is ProviderKind.LOCAL_ONNX
- assert snapshot.has_api_key is False
- assert snapshot == builtin_retrieval_snapshot()
+async def test_search_without_profile_uses_public_sdk_search() -> None:
+ client = _SearchClient(
+ {
+ "scene": "normal",
+ "memories": [
+ {"memory_id": "memory-1", "content": "偏好简短回答", "score": 0.91},
+ ],
+ }
+ )
+ found = await _runtime(client).semantic_search("回答偏好")
-async def test_the_retrieval_bridge_does_not_occupy_a_real_profiles_cache_slot(
- tmp_path,
-) -> None:
- """Otherwise pasting a key would change nothing the user can see.
-
- The cache is keyed by profile id and revision. Were the retrieval snapshot
- to collide with a real profile's key, the bridge built with no generation
- model would be handed back after the user configured one, and extraction
- would go on doing nothing with no error anywhere to explain it.
- """
- built: list[RecordingBridge] = []
- supervisor, profiles, secrets = _supervisor(tmp_path, built=built)
- _plant_store(tmp_path)
-
- await supervisor.semantic_search("抽取")
- active = _activate(profiles, secrets)
- await supervisor._prewarm_write_bridges(("cursor",)) # noqa: SLF001
- await supervisor.semantic_search("抽取")
-
- assert len(built) == 3
- assert len({id(bridge) for bridge in built}) == 3
- assert built[0].snapshot == builtin_retrieval_snapshot()
- assert {bridge.snapshot.profile_id for bridge in built[1:]} == {active.profile_id}
+ assert found == (("memory-1", 0.91),)
+ query, options = client.calls[0]
+ assert query == "回答偏好"
+ assert options["user_ids"] == ["local"]
+ assert options["agent_ids"] == []
+ assert options["scene"] == "normal"
diff --git a/memhub/apps/core/tests/test_sedimentation_concurrency.py b/memhub/apps/core/tests/test_sedimentation_concurrency.py
deleted file mode 100644
index e363df0..0000000
--- a/memhub/apps/core/tests/test_sedimentation_concurrency.py
+++ /dev/null
@@ -1,494 +0,0 @@
-"""Sedimentation runs several harnesses at once, but one harness at a time.
-
-Extraction was serial: `max_concurrent_tasks` defaulted to 1 and nothing ever
-passed anything else, so the queue on the user's machine stood at 1,440 with
-one task in flight and the scheduler logging `queue_saturated`. Meanwhile the
-model profile has carried a `max_concurrency` of 4 all along, copied into
-every task's snapshot and never once consulted by the scheduler.
-
-Turning the number up on its own would be wrong. HY decides whether a new
-memory supersedes an older one by what it has already been told, so two
-extractions from the same harness running at once can each conclude without
-knowing about the other. Harnesses run side by side up to the profile's limit.
-"""
-
-import asyncio
-import sqlite3
-import threading
-import time
-
-import pytest
-
-from one_memory.imports.models import EvidenceInput, EvidenceOrigin, OriginMetadata, WrittenBy
-from one_memory.memory_processing import MemoryProcessingSupervisor
-from one_memory.memory_tasks import MemoryTaskStatus
-from one_memory.model_profiles import ModelCapabilities, ModelProfilePatch
-from tests.test_memory_processing import FakeBridge, _put, _runner, _setup
-
-#: Long enough that an overlap is unmistakable, short enough to stay a unit test.
-MODEL_SECONDS = 0.25
-
-
-class WatchedBridge(FakeBridge):
- """A model that takes a moment, and says who was inside it when.
-
- Overlap is recorded rather than inferred from timings: every call notes
- which conversations were already in the model when it arrived.
- """
-
- def __init__(self, seconds: float = MODEL_SECONDS) -> None:
- super().__init__(outputs=())
- self.seconds = seconds
- self.inside: set[str] = set()
- self.peak = 0
- self.overlaps: list[tuple[str, ...]] = []
- self.same_conversation_overlaps: list[str] = []
- self._guard = threading.Lock()
-
- async def _spend_a_moment(self, request) -> None:
- conversation = getattr(request, "session_id", None) or "?"
- with self._guard:
- if self.inside:
- self.overlaps.append(tuple(sorted(self.inside)))
- if conversation in self.inside:
- self.same_conversation_overlaps.append(conversation)
- self.inside.add(conversation)
- self.peak = max(self.peak, len(self.inside))
- try:
- await asyncio.sleep(self.seconds)
- finally:
- with self._guard:
- self.inside.discard(conversation)
-
- async def ingest(self, request):
- await self._spend_a_moment(request)
- return await super().ingest(request)
-
- async def ingest_extracted(self, request, contents):
- await self._spend_a_moment(request)
- return await super().ingest_extracted(request, contents)
-
-
-def _conversations(
- evidence,
- *,
- count: int,
- turns: int = 1,
- sources: tuple[str, ...] = ("cursor",),
-) -> None:
- for conversation in range(count):
- source = sources[conversation % len(sources)]
- for turn in range(turns):
- evidence.put(
- EvidenceInput(
- source_id=source,
- message_id=f"c{conversation}-t{turn}",
- role="user",
- written_by=WrittenBy.PERSON,
- verbatim=f"第 {conversation} 段对话的第 {turn} 句。",
- conversation_id=f"conversation-{conversation}",
- origin_meta={EvidenceOrigin.FILE: OriginMetadata()},
- )
- )
- evidence.put(
- EvidenceInput(
- source_id=source,
- message_id=f"c{conversation}-t{turn}-answer",
- role="assistant",
- written_by=WrittenBy.AGENT,
- verbatim=f"第 {conversation} 段对话第 {turn} 句的回复。",
- conversation_id=f"conversation-{conversation}",
- origin_meta={EvidenceOrigin.FILE: OriginMetadata()},
- )
- )
-
-
-async def _drain(supervisor, tasks, *, expected: int, timeout: float = 60.0) -> float:
- started = time.monotonic()
- supervisor.backfill()
- deadline = started + timeout
- while time.monotonic() < deadline:
- recorded = tasks.list()
- if len(recorded) >= expected and all(
- task.status is MemoryTaskStatus.COMPLETED for task in recorded
- ):
- break
- await asyncio.sleep(0.01)
- else: # pragma: no cover - only on a real stall
- unfinished = [
- (t.task_id, str(t.status))
- for t in tasks.list()
- if t.status is not MemoryTaskStatus.COMPLETED
- ]
- await supervisor.shutdown()
- raise AssertionError(
- f"{expected} expected, {len(tasks.list())} recorded, still unfinished after "
- f"{timeout}s: {unfinished}. A drain that gives up quietly would let every "
- "measurement below be taken off a run that never finished."
- )
- elapsed = time.monotonic() - started
- await supervisor.shutdown()
- return elapsed
-
-
-def _supervise(tmp_path, stores, bridge, **kwargs):
- evidence, profiles, tasks, governance, secrets, _profile = stores
- return MemoryProcessingSupervisor(
- tasks=tasks,
- profiles=profiles,
- secrets=secrets,
- evidence=evidence,
- governance=governance,
- data_dir=tmp_path,
- runner_factory=lambda: _runner(tmp_path, stores, bridge),
- **kwargs,
- )
-
-
-def test_two_turns_of_one_conversation_are_never_in_the_model_together(tmp_path) -> None:
- """HY cannot tell what supersedes what if it is told both at once."""
- stores = _setup(tmp_path)
- evidence, _profiles, tasks, _governance, _secrets, _profile = stores
- for turn in range(4):
- _put(
- evidence,
- message_id=f"same-{turn}",
- role="user",
- written_by=WrittenBy.PERSON,
- content=f"同一段对话的第 {turn} 句,说的是同一件事的不同版本。",
- conversation_id="the-one-conversation",
- )
- bridge = WatchedBridge()
-
- async def exercise() -> None:
- # Four workers on purpose: with room to overlap, only the scheduler's
- # own rule can keep these apart.
- supervisor = _supervise(tmp_path, stores, bridge, max_concurrent_tasks=4)
- await _drain(supervisor, tasks, expected=1)
-
- asyncio.run(exercise())
-
- assert bridge.requests, "nothing reached the model, so this run proves nothing"
- assert bridge.same_conversation_overlaps == [], (
- f"{len(bridge.same_conversation_overlaps)} extractions from the same "
- "conversation were inside the model at the same time; HY decides "
- "supersede from what it has already been told, so neither could see "
- "the other's conclusion"
- )
-
-
-def test_separate_harnesses_run_side_by_side(tmp_path) -> None:
- """Harness ordering does not serialize unrelated sources."""
- stores = _setup(tmp_path)
- evidence, _profiles, tasks, _governance, _secrets, _profile = stores
- _conversations(evidence, count=8, sources=("cursor", "codex"))
- bridge = WatchedBridge()
-
- async def exercise() -> None:
- # No max_concurrent_tasks: whatever the profile says is what should
- # happen, and nobody in the product passes one.
- supervisor = _supervise(tmp_path, stores, bridge)
- await _drain(supervisor, tasks, expected=8)
-
- asyncio.run(exercise())
-
- assert bridge.peak > 1, (
- f"two separate harnesses were extracted {bridge.peak} at a time; "
- "the scheduler is still working through harnesses one after another"
- )
-
-
-def test_durable_drain_and_scheduler_share_one_source_lock(tmp_path) -> None:
- """A direct durable write cannot overlap the scheduler for one source."""
- stores = _setup(tmp_path)
- evidence, profiles, tasks, governance, secrets, _profile = stores
- _put(
- evidence,
- message_id="scheduled",
- role="user",
- written_by=WrittenBy.PERSON,
- content="后台调度中的 WorkBuddy 对话。",
- conversation_id="scheduled-conversation",
- source_id="workbuddy",
- )
- _put(
- evidence,
- message_id="scheduled-answer",
- role="assistant",
- written_by=WrittenBy.AGENT,
- content="后台调度中的 WorkBuddy 回复。",
- conversation_id="scheduled-conversation",
- source_id="workbuddy",
- )
- with sqlite3.connect(tmp_path / "one-memory.sqlite3") as database:
- database.executescript(
- """
- CREATE TABLE source_grants (
- user_id TEXT NOT NULL,
- source_id TEXT NOT NULL,
- root_path TEXT NOT NULL,
- candidate_kind TEXT NOT NULL,
- granted_at TEXT NOT NULL,
- revoked_at TEXT,
- PRIMARY KEY (user_id, source_id)
- );
- INSERT INTO source_grants VALUES (
- 'local','workbuddy','/authorized','default',
- '2026-10-04T00:00:00+00:00',NULL
- );
- """
- )
- bridge = WatchedBridge(seconds=0.2)
-
- async def exercise() -> None:
- scheduled_supervisor = _supervise(
- tmp_path,
- stores,
- bridge,
- max_concurrent_tasks=4,
- )
- direct_supervisor = _supervise(
- tmp_path,
- stores,
- bridge,
- max_concurrent_tasks=4,
- )
- scheduled_supervisor.backfill()
- for _ in range(100):
- if bridge.inside:
- break
- await asyncio.sleep(0.01)
- assert bridge.inside, "scheduler never entered the model"
- direct = _put(
- evidence,
- message_id="direct",
- role="user",
- written_by=WrittenBy.PERSON,
- content="durable drain 同时送来的 WorkBuddy 对话。",
- conversation_id="direct-conversation",
- source_id="workbuddy",
- )
- direct_answer = _put(
- evidence,
- message_id="direct-answer",
- role="assistant",
- written_by=WrittenBy.AGENT,
- content="durable drain 同时送来的 WorkBuddy 回复。",
- conversation_id="direct-conversation",
- source_id="workbuddy",
- )
- await direct_supervisor.process_records((direct, direct_answer))
- for _ in range(100):
- if len(bridge.requests) >= 2:
- break
- await asyncio.sleep(0.01)
- await asyncio.gather(
- scheduled_supervisor.shutdown(),
- direct_supervisor.shutdown(),
- )
-
- asyncio.run(exercise())
-
- assert len(bridge.requests) >= 2, "both execution paths must reach the model"
- assert bridge.overlaps == [], (
- f"the durable drain and scheduler entered HY together for one source: {bridge.overlaps}"
- )
-
-
-def test_side_by_side_stops_at_the_profile_limit(tmp_path) -> None:
- """The limit is the model's own, not a number invented by the scheduler."""
- stores = _setup(tmp_path)
- evidence, profiles, tasks, _governance, secrets, profile = stores
- allowed = 3
- profile = profiles.update(
- profile.profile_id,
- ModelProfilePatch(expected_revision=profile.revision, max_concurrency=allowed),
- secrets,
- )
- # A changed profile has to be probed again before it can be the active one.
- 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)
- _conversations(
- evidence,
- count=8,
- sources=("cursor", "codex", "claude-code", "workbuddy"),
- )
- bridge = WatchedBridge()
-
- async def exercise() -> None:
- supervisor = _supervise(tmp_path, stores, bridge)
- await _drain(supervisor, tasks, expected=8)
-
- asyncio.run(exercise())
-
- assert bridge.peak > 1, "nothing ran side by side, so the ceiling is untested"
- assert bridge.peak <= allowed, (
- f"the profile allows {allowed} at a time and {bridge.peak} were in the model together"
- )
-
-
-def test_a_queue_that_is_entirely_blocked_stops_starting_workers(tmp_path) -> None:
- """Serialising by conversation must not turn into a spin.
-
- A worker that finds nothing to take exits, and a worker exiting is what
- starts the next one. So a queue that is full but entirely blocked on the
- one conversation already running will start workers forever unless the
- question asked before starting one is "is there anything runnable",
- not "is the queue non-empty".
-
- The bound is deliberately loose: the difference between correct and
- wrong here is a handful against thousands, not a tuned number.
- """
- stores = _setup(tmp_path)
- evidence, _profiles, tasks, _governance, _secrets, _profile = stores
- turns = 6
- _conversations(evidence, count=1, turns=turns)
- bridge = WatchedBridge(seconds=0.05)
- starts = 0
-
- async def exercise() -> None:
- nonlocal starts
- supervisor = _supervise(tmp_path, stores, bridge)
- start_one = supervisor._start_worker # noqa: SLF001 - counting the thing under test
-
- def counted() -> None:
- nonlocal starts
- starts += 1
- start_one()
-
- supervisor._start_worker = counted # noqa: SLF001
- await _drain(supervisor, tasks, expected=turns)
-
- asyncio.run(exercise())
-
- assert starts > 0, "no worker was ever started, so the count proves nothing"
- assert starts <= 10 * turns, (
- f"{starts} workers were started for {turns} pieces of work, all of one "
- "conversation; each one found nothing to take and its exit started the next"
- )
-
-
-def test_nothing_queued_is_lost_when_the_core_stops(tmp_path) -> None:
- stores = _setup(tmp_path)
- evidence, _profiles, tasks, _governance, _secrets, _profile = stores
- _conversations(evidence, count=8)
- bridge = WatchedBridge(seconds=0.5)
-
- async def exercise() -> None:
- supervisor = _supervise(tmp_path, stores, bridge)
- supervisor.backfill()
- deadline = asyncio.get_running_loop().time() + 10.0
- try:
- while not tasks.list():
- if asyncio.get_running_loop().time() >= deadline:
- raise AssertionError(
- "backfill recorded no task within 10s; an unbounded wait "
- "would hang the complete Core release gate"
- )
- await asyncio.sleep(0.01)
- # Stop in the middle, which is what closing the window does.
- finally:
- await supervisor.shutdown()
-
- asyncio.run(exercise())
-
- recorded = tasks.list()
- assert recorded, "no task was ever recorded, so nothing was at risk"
- stranded = [
- task for task in recorded if task.status not in {MemoryTaskStatus.COMPLETED, *_CLAIMABLE}
- ]
- assert stranded == [], (
- f"{len(stranded)} tasks were left in a state no later run will pick up: "
- f"{[(t.task_id, str(t.status)) for t in stranded]}"
- )
-
-
-_CLAIMABLE = {
- MemoryTaskStatus.PENDING,
- MemoryTaskStatus.WAITING_FOR_MODEL,
- MemoryTaskStatus.FAILED,
- MemoryTaskStatus.RUNNING,
-}
-
-
-def test_running_several_at_once_never_reports_the_database_locked(tmp_path) -> None:
- stores = _setup(tmp_path)
- evidence, _profiles, tasks, _governance, _secrets, _profile = stores
- _conversations(evidence, count=12)
- bridge = WatchedBridge(seconds=0.05)
-
- async def exercise() -> None:
- supervisor = _supervise(tmp_path, stores, bridge)
- await _drain(supervisor, tasks, expected=12)
-
- asyncio.run(exercise())
-
- refused = [
- (task.task_id, task.last_error_code)
- for task in tasks.list()
- if task.last_error_code and "lock" in task.last_error_code.lower()
- ]
- assert refused == [], (
- f"extraction was refused the database while running side by side: {refused}"
- )
- assert all(task.status is MemoryTaskStatus.COMPLETED for task in tasks.list()), (
- "not every task finished, so a locked database could simply not have been reached yet"
- )
-
-
[email protected]("workers", [1, 4])
-def test_no_database_connection_is_held_while_the_model_thinks(tmp_path, workers) -> None:
- """Waiting on a model must not cost anyone a connection.
-
- Asked of the waiting thread itself, not of the database as a whole: with
- several workers, another one being mid-write while this one waits is
- exactly what is supposed to happen, and a process-wide reading calls that
- a fault. What must not happen is the thread that is about to sit on an
- `await` still holding a checkout of its own — the loop thread does every
- model call, so one held there is one nobody else can have for as long as
- the model takes.
-
- Checked at both settings because holding one only costs something when
- there is someone else to take it from.
- """
- from one_memory.database_access import main_database
-
- stores = _setup(tmp_path)
- evidence, _profiles, tasks, _governance, _secrets, _profile = stores
- _conversations(evidence, count=4)
- access = main_database(tmp_path / "one-memory.sqlite3")
- held: list[tuple[bool, int]] = []
-
- class Sampling(WatchedBridge):
- async def _spend_a_moment(self, request) -> None:
- me = threading.get_ident()
- held.append(
- (
- access._writer_owner == me, # noqa: SLF001 - the point of the test
- access._reader_holders.get(me, 0), # noqa: SLF001
- )
- )
- await super()._spend_a_moment(request)
-
- bridge = Sampling(seconds=0.1)
-
- async def exercise() -> None:
- supervisor = _supervise(tmp_path, stores, bridge, max_concurrent_tasks=workers)
- await _drain(supervisor, tasks, expected=4)
-
- asyncio.run(exercise())
-
- assert held, "the model was never reached, so nothing was sampled"
- assert [sample for sample in held if sample != (False, 0)] == [], (
- f"the thread about to wait on the model was still holding a checkout of its own: {held}"
- )
diff --git a/memhub/apps/core/tests/test_sedimentation_switch.py b/memhub/apps/core/tests/test_sedimentation_switch.py
index aa2e033..808083a 100644
--- a/memhub/apps/core/tests/test_sedimentation_switch.py
+++ b/memhub/apps/core/tests/test_sedimentation_switch.py
@@ -1,53 +1,17 @@
-"""Stopping model-driven sedimentation without losing the configuration.
-
-The switch is the user's cost control: while it is off nothing may reach the
-model, but neither the model configuration nor the already imported
-conversations may be touched, and work that was already queued has to survive
-so starting again resumes it instead of beginning from nothing.
-"""
-
-from __future__ import annotations
+"""The sedimentation API persists decisions and resumes the SDK queue."""
import asyncio
import threading
-import time
-from datetime import UTC, datetime, timedelta
-import pytest
from fastapi.testclient import TestClient
from pydantic import SecretStr
from one_memory.api import create_app
from one_memory.config import Settings
-from one_memory.extraction_settings import ExtractionSettingsStore
-from one_memory.hy_memory_bridge import HyMemoryBridgeError
-from one_memory.imports.models import EvidenceOrigin, OriginMetadata, WrittenBy
-from one_memory.imports.storage import EvidenceInput, EvidenceStore
-from one_memory.memory_processing import MemoryProcessingSupervisor
-from one_memory.memory_tasks import MemoryTaskKind, MemoryTaskStatus, MemoryTaskStore
-from one_memory.model_profiles import (
- ModelCapabilities,
- ModelProfileInput,
- ModelProfileStore,
- ProviderKind,
-)
-from one_memory.secrets import InMemorySecretStore
-
-NOW = datetime(2026, 9, 9, tzinfo=UTC)
-
-
-class _Flag:
- """The user's switch, standing in for `ConfigStore.sedimentation_enabled`."""
-
- def __init__(self, value: bool = True) -> None:
- self.value = value
- def __call__(self) -> bool:
- return self.value
-
-def test_sedimentation_route_persists_and_resumes_without_restart(tmp_path) -> None:
- app = create_app(
+def _app(tmp_path):
+ return create_app(
Settings(
_env_file=None,
data_dir=tmp_path / "data",
@@ -59,305 +23,53 @@ def test_sedimentation_route_persists_and_resumes_without_restart(tmp_path) -> N
),
source_catalog={},
)
- with TestClient(app, headers={"Authorization": "Bearer test"}) as client:
+
+
+def test_sedimentation_route_persists_and_resumes_without_restart(tmp_path) -> None:
+ with TestClient(_app(tmp_path), headers={"Authorization": "Bearer test"}) as client:
assert client.get("/api/v1/sedimentation").json()["enabled"] is True
- stopped = client.put("/api/v1/sedimentation", json={"enabled": False})
- assert stopped.status_code == 200
- assert stopped.json()["enabled"] is False
+ assert client.put(
+ "/api/v1/sedimentation", json={"enabled": False}
+ ).json()["enabled"] is False
assert client.get("/api/v1/sedimentation").json()["enabled"] is False
- resumed = client.put("/api/v1/sedimentation", json={"enabled": True})
- assert resumed.status_code == 200
- assert resumed.json()["enabled"] is True
+ assert client.put(
+ "/api/v1/sedimentation", json={"enabled": True}
+ ).json()["enabled"] is True
-def test_switch_answers_before_the_resume_finishes(tmp_path, monkeypatch) -> None:
- """The PUT is a decision; the walk over the backlog happens after it.
-
- Awaiting that walk is what turned "turn sedimentation back on" into a
- request that never returned. The renderer gave up at its thirty-second
- timeout and reported a failure for a switch that had in fact been saved,
- which is the worst of both: the user believes the model is still stopped
- while it is already running.
- """
- app = create_app(
- Settings(
- _env_file=None,
- data_dir=tmp_path / "data",
- source_home=tmp_path / "home",
- api_token=SecretStr("test"),
- imports_enabled=False,
- automatic_memory_processing=False,
- live_sync_enabled=False,
- ),
- source_catalog={},
- )
+def test_switch_answers_before_sdk_queue_resume_finishes(tmp_path, monkeypatch) -> None:
+ app = _app(tmp_path)
released = threading.Event()
finished = threading.Event()
with TestClient(app, headers={"Authorization": "Bearer test"}) as client:
- supervisor = app.state.memory_processing_supervisor
-
async def slow_resume() -> None:
await asyncio.get_running_loop().run_in_executor(None, released.wait, 10.0)
finished.set()
- monkeypatch.setattr(supervisor, "resume_allowed", slow_resume)
- assert client.put("/api/v1/sedimentation", json={"enabled": False}).status_code == 200
+ monkeypatch.setattr(app.state.sdk_memory_runtime, "resume_allowed", slow_resume)
+ assert client.put(
+ "/api/v1/sedimentation", json={"enabled": False}
+ ).status_code == 200
resumed = client.put("/api/v1/sedimentation", json={"enabled": True})
+
assert resumed.status_code == 200
assert resumed.json()["enabled"] is True
- # Answered while the resume is still walking the backlog.
assert finished.is_set() is False
released.set()
-def test_a_failing_resume_does_not_fail_the_switch(tmp_path, monkeypatch) -> None:
- """Resuming is opportunistic; the user's choice is already stored."""
- app = create_app(
- Settings(
- _env_file=None,
- data_dir=tmp_path / "data",
- source_home=tmp_path / "home",
- api_token=SecretStr("test"),
- imports_enabled=False,
- automatic_memory_processing=False,
- live_sync_enabled=False,
- ),
- source_catalog={},
- )
+def test_a_failing_sdk_queue_resume_does_not_fail_the_switch(tmp_path, monkeypatch) -> None:
+ app = _app(tmp_path)
with TestClient(app, headers={"Authorization": "Bearer test"}) as client:
- supervisor = app.state.memory_processing_supervisor
-
async def broken_resume() -> None:
- raise RuntimeError("hy_memory_processing_unavailable")
+ raise RuntimeError("sdk_queue_unavailable")
- monkeypatch.setattr(supervisor, "resume_allowed", broken_resume)
- assert client.put("/api/v1/sedimentation", json={"enabled": False}).status_code == 200
+ monkeypatch.setattr(app.state.sdk_memory_runtime, "resume_allowed", broken_resume)
+ assert client.put(
+ "/api/v1/sedimentation", json={"enabled": False}
+ ).status_code == 200
resumed = client.put("/api/v1/sedimentation", json={"enabled": True})
+
assert resumed.status_code == 200
assert resumed.json()["enabled"] is True
-
-
-def _stores(tmp_path, flag: _Flag):
- database_path = tmp_path / "one-memory.sqlite3"
- evidence = EvidenceStore(database_path)
- tasks = MemoryTaskStore(database_path)
- profiles = ModelProfileStore(database_path)
- secrets = InMemorySecretStore()
- profile = profiles.create(
- ModelProfileInput(
- name="Local",
- provider_kind=ProviderKind.OPENAI_COMPATIBLE,
- base_url="https://example.com/v1",
- model="test-model",
- embedding_provider_kind=ProviderKind.LOCAL_ONNX,
- embedding_model="builtin",
- embedding_dimensions=512,
- ),
- 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,
- )
- active = profiles.activate(profile.profile_id, secrets)
- supervisor = MemoryProcessingSupervisor(
- tasks=tasks,
- profiles=profiles,
- secrets=secrets,
- evidence=evidence,
- governance=None, # type: ignore[arg-type]
- data_dir=tmp_path,
- extraction_settings=ExtractionSettingsStore(database_path),
- sedimentation_enabled=flag,
- )
- return evidence, tasks, active, supervisor, profiles, secrets
-
-
-def _task(evidence, tasks, active, *, index: int, age_days: int = 1):
- record = evidence.put(
- EvidenceInput(
- source_id="cursor",
- workspace="/Users/me/project",
- conversation_id=f"conv-{index}",
- message_id=f"m{index}",
- correlation_id=f"m{index}",
- role="user",
- written_by=WrittenBy.PERSON,
- created_at=NOW - timedelta(days=age_days),
- verbatim="I prefer concise answers.",
- origin_meta={EvidenceOrigin.FILE: OriginMetadata()},
- )
- ).record
- return tasks.create(
- request_id=f"req-{index}",
- user_id="local",
- kind=MemoryTaskKind.EXTRACT,
- input_ref=record.evidence_id,
- profile=active,
- )
-
-
-def test_stopped_switch_classifies_no_work_and_keeps_it_pending(tmp_path) -> None:
- flag = _Flag(False)
- evidence, tasks, active, supervisor, _profiles, _secrets = _stores(tmp_path, flag)
-
- task = _task(evidence, tasks, active, index=1)
-
- assert supervisor._classify([task]) == []
- # Parked, not failed: nothing was sent to the model, so a stopped switch
- # must not read as a broken pipeline.
- assert tasks.require(task.task_id).status is MemoryTaskStatus.PENDING
-
- flag.value = True
- assert len(supervisor._classify([task])) == 1
-
-
-def test_stopped_switch_refuses_direct_durable_processing(tmp_path) -> None:
- flag = _Flag(False)
- evidence, tasks, active, supervisor, _profiles, _secrets = _stores(tmp_path, flag)
- task = _task(evidence, tasks, active, index=1)
- record = evidence.get(task.input_ref)
- assert record is not None
-
- with pytest.raises(HyMemoryBridgeError, match="model_sedimentation_disabled"):
- asyncio.run(supervisor.process_records((record,)))
-
- assert tasks.require(task.task_id).status is MemoryTaskStatus.PENDING
-
-
-def test_pause_returns_a_claimed_task_attempt(tmp_path) -> None:
- flag = _Flag(True)
- evidence, tasks, active, _supervisor, _profiles, _secrets = _stores(tmp_path, flag)
- task = _task(evidence, tasks, active, index=1)
- claimed, token = tasks.claim(task.task_id)
- assert claimed.attempts == 1
-
- released = tasks.release_unstarted(
- task.task_id,
- runner_token=token,
- error_code="model_sedimentation_disabled",
- )
-
- assert released.status is MemoryTaskStatus.PENDING
- assert released.attempts == 0
-
-
-def test_stopping_after_scheduler_classification_starts_no_worker(tmp_path) -> None:
- flag = _Flag(True)
- evidence, tasks, active, supervisor, _profiles, _secrets = _stores(tmp_path, flag)
- task = _task(evidence, tasks, active, index=1)
- work = supervisor._classify([task])
- assert len(work) == 1
- supervisor._queue.add(work[0])
-
- flag.value = False
- asyncio.run(supervisor._work())
-
- current = tasks.require(task.task_id)
- assert current.status is MemoryTaskStatus.PENDING
- assert current.attempts == 0
-
-
-def test_stopped_switch_enqueues_nothing(tmp_path) -> None:
- flag = _Flag(False)
- evidence, _tasks, active, supervisor, _profiles, _secrets = _stores(tmp_path, flag)
- record = evidence.put(
- EvidenceInput(
- source_id="cursor",
- workspace="/Users/me/project",
- conversation_id="conv-live",
- message_id="m-live",
- correlation_id="m-live",
- role="user",
- written_by=WrittenBy.PERSON,
- created_at=NOW,
- verbatim="Remember this.",
- origin_meta={EvidenceOrigin.FILE: OriginMetadata()},
- )
- ).record
-
- assert supervisor.enqueue_evidence(record) is None
- assert supervisor._debounces == {}
-
-
-def test_stopped_switch_prepares_no_backfill(tmp_path) -> None:
- flag = _Flag(False)
- evidence, tasks, active, supervisor, _profiles, _secrets = _stores(tmp_path, flag)
- # No task is queued yet: backfill is what would create one for this
- # conversation, so the stopped switch must keep it from creating any.
- # A settled turn (question plus answer): an unanswered user tail is not
- # backfill material, so the conversation needs both records.
- for message_id, role, written_by, verbatim in (
- ("m-old", "user", WrittenBy.PERSON, "Remember this too."),
- ("m-old-reply", "assistant", WrittenBy.AGENT, "Saved."),
- ):
- evidence.put(
- EvidenceInput(
- source_id="cursor",
- workspace="/Users/me/project",
- conversation_id="conv-old",
- message_id=message_id,
- correlation_id=message_id,
- role=role,
- written_by=written_by,
- created_at=NOW - timedelta(days=1),
- verbatim=verbatim,
- origin_meta={EvidenceOrigin.FILE: OriginMetadata()},
- )
- )
-
- assert supervisor.prepare_backfill() == []
-
- flag.value = True
- assert len(supervisor.prepare_backfill()) == 1
-
-
-def test_absent_switch_keeps_sedimenting(tmp_path) -> None:
- """A Core without the setting behaves exactly as it did before it existed."""
- evidence, tasks, active, supervisor, _profiles, _secrets = _stores(tmp_path, _Flag(True))
- supervisor.sedimentation_enabled = None
- task = _task(evidence, tasks, active, index=1)
-
- assert len(supervisor._classify([task])) == 1
-
-
-def test_stopping_does_not_disturb_the_model_configuration(tmp_path) -> None:
- flag = _Flag(True)
- evidence, tasks, active, supervisor, profiles, secrets = _stores(tmp_path, flag)
- _task(evidence, tasks, active, index=1)
-
- flag.value = False
- assert supervisor.prepare_backfill() == []
- # Still configured: starting again is a switch, not a re-entry of a key.
- assert profiles.active(secrets) is not None
-
-
-def test_bounded_backfill_returns_when_the_queue_is_already_full(tmp_path) -> None:
- """A full queue means nothing to add, not "wait until it drains".
-
- The wait used to sleep inside the scan lock, so whoever asked for the scan
- — the resume behind a switch toggle, and through it an HTTP request —
- waited for the whole backlog to clear. A saturated queue never clears by
- waiting, so that request never came back.
- """
- flag = _Flag(True)
- evidence, tasks, active, supervisor, _profiles, _secrets = _stores(tmp_path, flag)
- for index in range(8):
- task = _task(evidence, tasks, active, index=index)
- supervisor._queue.add(supervisor._classify([task])[0])
-
- started = time.monotonic()
- asyncio.run(asyncio.wait_for(supervisor.backfill_off_thread(cohort_size=8), timeout=3))
- assert time.monotonic() - started < 3
-
-
-if __name__ == "__main__":
- raise SystemExit(pytest.main([__file__]))
diff --git a/memhub/apps/core/tests/test_source_write_switch.py b/memhub/apps/core/tests/test_source_write_switch.py
deleted file mode 100644
index f1dae45..0000000
--- a/memhub/apps/core/tests/test_source_write_switch.py
+++ /dev/null
@@ -1,66 +0,0 @@
-"""A frozen Harness produces no extraction tasks.
-
-Unit-level, on the one method that decides it, because driving a whole
-backfill needs a model profile, a permission receipt and a bridge; the
-decision under test is only "is this conversation's source allowed".
-"""
-
-from types import SimpleNamespace
-
-import pytest
-
-from one_memory.memory_processing import MemoryProcessingSupervisor
-
-
-def _record(source_id: str) -> SimpleNamespace:
- return SimpleNamespace(source_id=source_id)
-
-
-def _supervisor(permitted) -> MemoryProcessingSupervisor:
- supervisor = MemoryProcessingSupervisor.__new__(MemoryProcessingSupervisor)
- supervisor.source_writes_permitted = permitted
- return supervisor
-
-
-def test_an_enabled_harness_is_kept() -> None:
- supervisor = _supervisor(lambda source_id: True)
-
- assert supervisor._source_may_write([_record("cursor")]) is True
-
-
-def test_a_frozen_harness_is_skipped() -> None:
- supervisor = _supervisor(lambda source_id: False)
-
- assert supervisor._source_may_write([_record("cursor")]) is False
-
-
-def test_only_the_conversation_s_own_harness_decides() -> None:
- """A closed source must not stop another one's conversations."""
- supervisor = _supervisor(lambda source_id: source_id != "cursor")
-
- assert supervisor._source_may_write([_record("claude-code")]) is True
- assert supervisor._source_may_write([_record("cursor")]) is False
-
-
-def test_a_mixed_conversation_follows_its_frozen_harness() -> None:
- """One closed member is enough: the chunk would carry its content."""
- supervisor = _supervisor(lambda source_id: source_id != "cursor")
-
- assert supervisor._source_may_write([_record("claude-code"), _record("cursor")]) is False
-
-
-def test_without_a_switch_everything_is_processable() -> None:
- """A Core or a test that wires none keeps the behaviour it had before."""
- supervisor = _supervisor(None)
-
- assert supervisor._source_may_write([_record("cursor")]) is True
-
-
-def test_an_empty_conversation_is_not_a_reason_to_skip() -> None:
- supervisor = _supervisor(lambda source_id: False)
-
- assert supervisor._source_may_write([]) is True
-
-
-if __name__ == "__main__":
- raise SystemExit(pytest.main([__file__]))
diff --git a/memhub/apps/core/tests/test_whole_turn_hy_input.py b/memhub/apps/core/tests/test_whole_turn_hy_input.py
index a991c74..ffdfcef 100644
--- a/memhub/apps/core/tests/test_whole_turn_hy_input.py
+++ b/memhub/apps/core/tests/test_whole_turn_hy_input.py
@@ -2,9 +2,9 @@
from datetime import UTC, datetime
+from one_memory.conversation_processing import _conversation_chunks
from one_memory.imports.models import EvidenceInput, EvidenceOrigin, OriginMetadata, WrittenBy
from one_memory.imports.storage import EvidenceStore
-from one_memory.memory_processing import _conversation_chunks
_WRITER = {"user": "person", "assistant": "agent", "tool": "tool"}
@@ -74,7 +74,7 @@ def test_one_window_is_capped_in_raw_bytes(tmp_path):
reaches the model. Past the byte ceiling the window is cut, so no single
call can grow without bound.
"""
- from one_memory.memory_processing import _WINDOW_BYTE_CEILING
+ from one_memory.conversation_processing import _WINDOW_BYTE_CEILING
records = _turn(
tmp_path,
@@ -92,7 +92,7 @@ def test_one_window_is_capped_in_raw_bytes(tmp_path):
def test_the_byte_ceiling_counts_bytes_not_characters(tmp_path):
"""One CJK character is three bytes; a character count would let three
times as much through."""
- from one_memory.memory_processing import _WINDOW_BYTE_CEILING, _window_bytes
+ from one_memory.conversation_processing import _WINDOW_BYTE_CEILING, _window_bytes
assert _window_bytes(_turn(tmp_path, ("user", "中文"))[0]) > len("中文")
assert _WINDOW_BYTE_CEILING == 2_000_000
@@ -138,7 +138,7 @@ def test_the_sdk_still_cuts_tool_results_the_way_this_assumes():
)
from hy_memory.pipelines.base import ChatMessage
- from one_memory.memory_processing import _HY_TOOL_CHARACTERS
+ from one_memory.conversation_processing import _HY_TOOL_CHARACTERS
assert DEFAULT_MAX_TOOL_RESULT_BYTES == 2048
assert _HY_TOOL_CHARACTERS == 512
diff --git a/memhub/docs/ARCHITECTURE.md b/memhub/docs/ARCHITECTURE.md
index 7487112..c0b3c03 100644
--- a/memhub/docs/ARCHITECTURE.md
+++ b/memhub/docs/ARCHITECTURE.md
@@ -41,7 +41,7 @@ AI hosts / harnesses
├─ model profiles & secrets boundary
├─ async write queue (schedule / drain / leases)
├─ config switches & Core/Runtime health
- ├─ Hy Memory bridge (only SDK client entry for memory I/O)
+ ├─ SDK runtime lease + public HyMemoryClient
└─ local HTTP API
▲ ▲ ▲
│ │ └─ Host Bridge / recall broker
@@ -62,7 +62,7 @@ files or SDK private stores directly.
| Path | Responsibility |
| --- | --- |
-| `apps/core` | FastAPI 管理面:harness、model、队列、config、Runtime 协作,并经 bridge 调用 SDK。 |
+| `apps/core` | FastAPI 管理面:harness、model、队列、config、Runtime 协作,并调用公开 SDK client。 |
| `apps/web` | React / TypeScript product UI and API client. |
| `apps/desktop` | Electron shell; attaches to or starts the managed Runtime. |
| `apps/cli` | Bootstrap, install, upgrade, service lifecycle, diagnostics. |
@@ -103,8 +103,7 @@ Periodic polling / fs watch live in Core. UI does not schedule scans.
authorized harness / user action
-> (optional) durable job row in MemHub queue // 调度与租约,不是 memory 实体
-> sedimentation / model / source gates // 管理面门禁
- -> HyMemoryBridge
- -> Hy Memory SDK write (raw / chat / coding / …)
+ -> public HyMemoryClient write (raw / chat / coding / …)
-> SDK stores (vector, graph, cache, history, coding, …) via SDK config/env
-> MemHub may persist memory_id only for explicit management receipts / UI keys
-> search / recall / UI via SDK read APIs (+ MemHub authz)
@@ -116,9 +115,18 @@ authorized harness / user action
- 原文/raw 的持久化与失败保留由 SDK raw 合同承担。
- 运维状态直接来自 `memory_write_jobs`,不另设 `memory_tasks` 二级执行表。
-### HY / SDK and MemHub bridge
+### HY SDK client boundary
-Hy Memory is the **only** extraction, memory entity, relationship, and semantic-retrieval engine. Product code enters it through `HyMemoryBridge`(共享 Runtime、模型配置、密钥边界),不在业务模块里私自 new 一套绕过门禁的 client。
+Hy Memory is the **only** extraction, memory entity, relationship, and
+semantic-retrieval engine. Product code obtains a public `HyMemoryClient`
+through `hy_sdk_runtime.SdkClientHandle`; only that runtime module constructs
+clients. MemHub does not patch prompts, private stores, writer/reader caches,
+reconcile operations, or response retries.
+
+The only product exception is the existing Graph visualization and Graph Width
+surface: `hy_graph_projection.py` and `hy_graph_admin.py` may query Kuzu
+directly for low-latency Cypher projection and store-width administration.
+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。`import_raw()` 只用于历史数据的 exact migration,不拆分正常写路径。
diff --git a/memhub/docs/contracts/runtime-unification.md b/memhub/docs/contracts/runtime-unification.md
index 8a1cc77..5867f07 100644
--- a/memhub/docs/contracts/runtime-unification.md
+++ b/memhub/docs/contracts/runtime-unification.md
@@ -28,9 +28,9 @@ model profiles, the durable SDK-call queue, configuration, diagnostics, and
Runtime coordination.
Memory entities, raw conversations, vectors, graph data, coding memory, and SDK
-cache/history belong to the Hy Memory SDK data plane. Core reaches that plane
-through `HyMemoryBridge`; no product module may write SDK private stores or
-maintain a second memory authority.
+cache/history belong to the Hy Memory SDK data plane. Core obtains a public
+`HyMemoryClient` through the shared runtime lease; no product module may write
+SDK private stores or maintain a second memory authority.
### Desktop and CLI
diff --git a/memhub/scripts/probe_hy_dependency_surface.py b/memhub/scripts/probe_hy_dependency_surface.py
index 0ad826f..54e207a 100644
--- a/memhub/scripts/probe_hy_dependency_surface.py
+++ b/memhub/scripts/probe_hy_dependency_surface.py
@@ -1,4 +1,4 @@
-"""Report the HY SDK surface required by the current One Memory bridge."""
+"""Report the public HY SDK surface required by MemHub."""
from __future__ import annotations
@@ -8,7 +8,6 @@ from pathlib import Path
_SANDBOX = Path(tempfile.mkdtemp(prefix="hy-probe-"))
from one_memory.hy_runtime_config import (
HY_MEMORY_DISTRIBUTION,
- HY_MEMORY_MODE,
HY_MEMORY_READER,
HY_MEMORY_VERSION,
configure_hy_runtime_environment,
@@ -18,7 +17,7 @@ from one_memory.hy_runtime_config import (
configure_hy_runtime_environment(_SANDBOX)
import hy_memory
-from hy_memory.config import MemoryConfig
+from hy_memory import HyMemoryClient, MemoryConfig
results: list[tuple[str, str, str]] = []
@@ -35,7 +34,7 @@ def check(name: str, fn) -> None:
print(f"hy_memory.__version__ = {hy_memory.__version__}")
print(f"distribution/version = {HY_MEMORY_DISTRIBUTION} {hy_memory_version()}")
print(f"loaded from = {Path(hy_memory.__file__).parent}")
-print(f"One Memory mode/reader= {HY_MEMORY_MODE} / {HY_MEMORY_READER}")
+print(f"MemHub mode/reader = pro / {HY_MEMORY_READER}")
print()
config = MemoryConfig.from_env()
@@ -105,9 +104,7 @@ for section, fields in CONFIG_FIELDS.items():
)
)
-# Client methods the bridge calls, plus the ones the protocol declares.
-from hy_memory.client import HyMemoryClient
-
+# Public client methods MemHub calls.
for method in (
"add",
"add_extracted",
@@ -148,7 +145,7 @@ with tempfile.TemporaryDirectory() as sandbox:
config.embedder.api_key = "probe-not-used"
config.embedder.base_url = "http://127.0.0.1:1/v1"
try:
- client = HyMemoryClient(config=config, mode=HY_MEMORY_MODE)
+ client = HyMemoryClient(config=config, mode="pro")
except Exception as error: # noqa: BLE001 - reporting, not handling
results.append(("HyMemoryClient(config, mode='ultra')", "MISSING", str(error)))
else:
diff --git a/tests/test_lang_detect.py b/tests/test_lang_detect.py
index c8a3945..727df10 100644
--- a/tests/test_lang_detect.py
+++ b/tests/test_lang_detect.py
@@ -1,5 +1,7 @@
"""Language routing for prompts, including code-heavy agent inputs."""
+import json
+
import pytest
from hy_memory.utils.lang_detect import (
@@ -45,6 +47,37 @@ def test_messages_route_from_message_content_not_role_names():
assert is_chinese(messages=messages) is True
+def test_writer_json_messages_route_on_content_not_keys():
+ messages = [
+ {"role": "user", "content": "请修复 search_client.py 的超时问题"},
+ {"role": "assistant", "content": "I will inspect the implementation."},
+ ]
+ assert is_chinese(json.dumps(messages, ensure_ascii=False)) is True
+ assert (
+ is_chinese(json.dumps([{"role": "user", "content": "Please fix the bug."}]))
+ is False
+ )
+
+
+def test_latest_user_message_beats_initial_assistant_and_structured_keys():
+ messages = [
+ {"role": "assistant", "content": "The release is ready for deployment."},
+ {"role": "user", "content": '[{"type":"text","text":"请用中文记录这个结论"}]'},
+ ]
+ assert is_chinese(json.dumps(messages, ensure_ascii=False)) is True
+ assert is_chinese(messages=messages) is True
+ assert is_chinese(messages[1]["content"]) is True
+
+
+def test_non_message_json_and_malformed_content_keep_original_detection():
+ for content in (
+ '[{"other":"你好"}]',
+ '[{"role":"user","content":"你好"}',
+ '[{"type":[],"text":"请记录这个决定"}]',
+ ):
+ assert is_chinese(content) == (detect_language(content) == "zh")
+
+
def test_reconcile_uses_chinese_prompt_for_code_heavy_chinese_instruction():
memory = (
"请修复 search_client.py 里的 timeout bug: "
diff --git a/tests/test_public_get_and_embedding_service.py b/tests/test_public_get_and_embedding_service.py
new file mode 100644
index 0000000..1a2aea8
--- /dev/null
+++ b/tests/test_public_get_and_embedding_service.py
@@ -0,0 +1,261 @@
+from __future__ import annotations
+
+import asyncio
+import time
+
+import pytest
+
+from hy_memory import (
+ AmbiguousMemoryIdError,
+ EmbeddingDimensionMismatchError,
+ EmbeddingService,
+ HyMemoryClient,
+)
+from hy_memory.coding.types import CodingMemory, WorkingFact
+from hy_memory.coding.writer import CodingWriter
+from hy_memory.config import MemoryConfig
+from hy_memory.models.memory import MemoryLayer, MemoryNode
+from hy_memory.pipelines import ComponentFactory
+
+
+class FakeEmbeddingService:
+ def __init__(self, dims: int):
+ self.dims = dims
+ self.close_calls = 0
+
+ async def embed(self, text, use_cache=True):
+ return [0.0] * self.dims
+
+ async def embed_with_meta(self, text, use_cache=True):
+ return await self.embed(text, use_cache), {}
+
+ async def embed_batch(self, texts, use_cache=True):
+ return [[0.0] * self.dims for _ in texts]
+
+ async def embed_queued(self, text, use_cache=True):
+ return await self.embed(text, use_cache)
+
+ async def embed_queued_with_meta(self, text, use_cache=True):
+ return await self.embed(text, use_cache), {}
+
+ def get_embedding_dims(self):
+ return self.dims
+
+ async def close(self):
+ self.close_calls += 1
+
+
+class ExactStore:
+ def __init__(self, experience=None, fact=None):
+ self.experience = experience
+ self.fact = fact
+
+ async def get_by_id(self, memory_id):
+ if self.experience and self.experience.experience_id == memory_id:
+ return self.experience
+ return None
+
+ async def get_fact(self, memory_id):
+ if self.fact and self.fact.fact_id == memory_id:
+ return self.fact
+ return None
+
+
+class ChatStore:
+ def __init__(self, node=None):
+ self.node = node
+
+ async def get_by_id(self, memory_id):
+ if self.node and self.node.node_id == memory_id:
+ return self.node
+ return None
+
+
+def exact_client(*, node=None, stores=None, config=None):
+ client = HyMemoryClient.__new__(HyMemoryClient)
+ client._vector_store = ChatStore(node)
+ client._graph_store = None
+ client._coding_stores = stores or {}
+ if config is not None:
+ client._config = config
+ client._backend_identity = lambda: {}
+
+ async def no_op_log(**_kwargs):
+ return None
+
+ client._maybe_store_op_log = no_op_log
+ return client
+
+
+async def test_exact_get_supports_all_public_namespaces_and_chat_metadata():
+ chat = MemoryNode(
+ node_id="chat-1",
+ user_id="u1",
+ agent_id="a1",
+ session_id="s1",
+ owner="user",
+ layer=MemoryLayer.L2_FACT,
+ content="chat content",
+ )
+ experience = CodingMemory(
+ experience_id="exp-1",
+ user_id="u1",
+ agent_id="a1",
+ session_id="s2",
+ task="ship",
+ solution="run release",
+ boundary_envs="python>=3.9",
+ )
+ fact = WorkingFact(
+ fact_id="fact-1",
+ user_id="u1",
+ agent_id="a1",
+ session_id="s3",
+ statement="release completed",
+ details="tag=v1.2.3",
+ )
+ client = exact_client(
+ node=chat,
+ stores={"working": ExactStore(experience, fact)},
+ )
+ raw_get = HyMemoryClient.async_get.__wrapped__
+
+ chat_result = await raw_get(client, "chat-1")
+ assert chat_result["kind"] == "chat"
+ assert chat_result["owner"] == "user"
+ assert chat_result["session_id"] == "s1"
+
+ exp_result = await raw_get(client, "exp-1")
+ assert exp_result["memory_id"] == "exp-1"
+ assert exp_result["kind"] == "experience"
+ assert exp_result["variant"] == "working"
+ assert exp_result["boundary_envs"] == "python>=3.9"
+
+ fact_result = await raw_get(client, "fact-1")
+ assert fact_result["memory_id"] == "fact-1"
+ assert fact_result["kind"] == "fact"
+ assert fact_result["variant"] == "working"
+ assert fact_result["details"] == "tag=v1.2.3"
+
+
+async def test_exact_get_collision_fails_closed_and_can_be_disambiguated():
+ working = CodingMemory(
+ experience_id="same-id", user_id="u1", task="working", solution="w"
+ )
+ coding = CodingMemory(
+ experience_id="same-id", user_id="u1", task="coding", solution="c"
+ )
+ client = exact_client(
+ stores={
+ "working": ExactStore(experience=working),
+ "coding": ExactStore(experience=coding),
+ }
+ )
+ raw_get = HyMemoryClient.async_get.__wrapped__
+
+ with pytest.raises(AmbiguousMemoryIdError) as raised:
+ await raw_get(client, "same-id")
+ assert raised.value.namespaces == (
+ "working:experience",
+ "coding:experience",
+ )
+
+ result = await raw_get(
+ client, "same-id", kind="experience", variant="coding"
+ )
+ assert result["task"] == "coding"
+
+
+async def test_cold_exact_get_does_not_create_missing_coding_database(tmp_path):
+ config = MemoryConfig.from_env()
+ config.coding.db_path = str(tmp_path / "coding_memory.db")
+ client = exact_client(config=config)
+
+ async def should_not_initialize(*_args, **_kwargs):
+ raise AssertionError("missing database must not initialize a coding store")
+
+ client._get_coding_writer = should_not_initialize
+ result = await HyMemoryClient.async_get.__wrapped__(
+ client, "missing", kind="fact"
+ )
+
+ assert result is None
+ assert list(tmp_path.iterdir()) == []
+
+
+def test_embedding_service_is_structural_and_dimension_mismatch_fails_fast():
+ config = MemoryConfig.from_env()
+ config.vector_store.embedding_dims = 4
+ service = FakeEmbeddingService(3)
+ assert isinstance(service, EmbeddingService)
+
+ client = HyMemoryClient.__new__(HyMemoryClient)
+ client._config = config
+ with pytest.raises(EmbeddingDimensionMismatchError):
+ client._validate_embedding_service(service)
+
+
+def test_coding_write_receipt_identifies_variant():
+ writer = CodingWriter.__new__(CodingWriter)
+ writer.variant = "coding"
+ receipt = writer._empty_response("request-1", time.perf_counter())
+ assert receipt["variant"] == "coding"
+
+
+async def test_component_factory_borrows_injected_embedding_service():
+ config = MemoryConfig.from_env()
+ config.vector_store.embedding_dims = 3
+ service = FakeEmbeddingService(3)
+ factory = ComponentFactory(config, embedding_service=service)
+
+ assert factory._get_shared_embed_service() is service
+ await factory.close()
+ assert service.close_calls == 0
+
+
+def test_constructor_and_from_config_accept_embedding_service_before_init(
+ monkeypatch,
+):
+ seen = []
+
+ async def fake_initialize(self):
+ seen.append(self._borrowed_embedding_service)
+ self._embed_service = self._borrowed_embedding_service
+ self._registry = ComponentFactory(
+ self._config, embedding_service=self._embed_service
+ )
+
+ class InlineLoop:
+ def __init__(self):
+ self._loop = None
+
+ def run(self, coroutine):
+ return asyncio.run(coroutine)
+
+ def stop(self):
+ pass
+
+ monkeypatch.setattr(HyMemoryClient, "_initialize", fake_initialize)
+ monkeypatch.setattr("hy_memory.client._LoopThread", InlineLoop)
+
+ config = MemoryConfig.from_env()
+ config.vector_store.embedding_dims = 3
+ service = FakeEmbeddingService(3)
+ direct = HyMemoryClient(config, mode="lite", embedding_service=service)
+ configured = HyMemoryClient.from_config(
+ {
+ "mode": "lite",
+ "vector_store": {"embedding_dims": 3},
+ "embedder": {"embedding_dims": 3},
+ },
+ embedding_service=service,
+ )
+
+ assert seen == [service, service]
+ assert direct._registry._get_shared_embed_service() is service
+ assert configured._registry._get_shared_embed_service() is service
+ assert service.close_calls == 0