Python
feat(sdk): add MemHub authority migration contracts (#129)
feitianxiangfd12c8f1c0f0
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex 55c0e9f..eb3fe01 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -14,6 +14,12 @@ Hy Memory and MemHub are versioned and released independently.## Unreleased+- Added SDK-authoritative lifecycle listing with explicit status filters,+ idempotent durable write outcomes, exact raw import/get/list APIs, and+ quiesced local data-plane snapshot/restore contracts for the MemHub+ authority migration.+- Physical delete now reports incomplete VDB/Graph cleanup as a partial failure+ instead of claiming success after only one store was changed.- Coding search no longer injects the version-evolution diff block(`chain_block`) by default. Enable with`MEMORY_CODING_CHAIN_BLOCK_ENABLED=true` ordiff --git a/hy_memory/__init__.py b/hy_memory/__init__.pyindex 7408dd3..e8944a7 100644--- a/hy_memory/__init__.py+++ b/hy_memory/__init__.py@@ -55,6 +55,13 @@ except Exception:from .client import HyMemoryClientfrom .inspector import MemoryInspectorfrom .runtime import SharedRuntime+from .snapshot import (+ DataPlaneRestore,+ DataPlaneSnapshot,+ DataPlaneSnapshotRejected,+ restore_local_data_plane,+ snapshot_local_data_plane,+)# ====== 配置 ======from .config import MemoryConfig@@ -111,6 +118,11 @@ __all__ = ["HyMemoryClient","MemoryInspector","SharedRuntime",+ "DataPlaneRestore",+ "DataPlaneSnapshot",+ "DataPlaneSnapshotRejected",+ "restore_local_data_plane",+ "snapshot_local_data_plane",# 配置"MemoryConfig",# Embedding 端点覆盖diff --git a/hy_memory/client.py b/hy_memory/client.pyindex 24bfeee..62cc96c 100644--- a/hy_memory/client.py+++ b/hy_memory/client.py@@ -1913,6 +1913,7 @@ class HyMemoryClient:user_ids: Optional[List[str]] = None,agent_ids: Optional[List[str]] = None,layers: Optional[List[Any]] = None,+ statuses: Optional[List[Any]] = None,with_evolution: bool = False,) -> Dict[str, Any]:"""@@ -1935,6 +1936,9 @@ class HyMemoryClient:agent_ids: 可选,多 agent 批量列举。非空时优先于 agent_id。layers: 可选,只返回指定层级(字符串或 MemoryLayer)。不传时返回L1_RAW 以外的全部层级,与改动前一致。+ statuses: 可选,只返回指定生命周期(字符串或 MemoryStatus)。不传时+ 保持兼容,只返回 ACTIVE。可显式读取 SUPERSEDED / SHADOW /+ NEGATED / CONFLICTED / ARCHIVED;物理删除的节点不会返回。with_evolution: 可选,为当前页条目附加 evolution_chain(默认关闭)。Returns:@@ -1947,7 +1951,7 @@ class HyMemoryClient:user_ids=user_ids, agent_ids=agent_ids,limit=limit, offset=offset, order=order,workspace_id=workspace_id, branch=branch,- layers=layers, with_evolution=with_evolution,+ layers=layers, statuses=statuses, with_evolution=with_evolution,))@@ -2242,6 +2246,10 @@ class HyMemoryClient:self.async_get_recent_history(user_id=user_id, agent_ids=agent_ids, limit=limit))+ def get_write_outcome(self, request_id: str) -> Optional[Dict[str, Any]]:+ """Return the exact durable outcome for one idempotent write request."""+ return self._loop_thread.run(self.async_get_write_outcome(request_id))+async def _close_async(self):if self._owns_runtime:from .metrics import MetricsCollector@@ -2383,7 +2391,7 @@ class HyMemoryClient:except Exception as e:logger.warning(f"[delete] chain repair failed for {node_id}: {e}")- async def _cleanup_graph_evidence(self, deleted_node_id: str) -> None:+ async def _cleanup_graph_evidence(self, deleted_node_id: str) -> bool:"""清理已删除 VDB 节点在 Graph 中的 evidence 引用。@@ -2394,13 +2402,13 @@ class HyMemoryClient:直接用底层 execute 删 VdbRef + DERIVED_FROM 边。"""if self._graph_store is None:- return+ return Truetry:gs = self._graph_store# Kuzu backendif hasattr(gs, '_execute') and hasattr(gs, '_available'):if not gs._available:- return+ return Falsegs._execute("MATCH (v:VdbRef {node_id: $nid}) DETACH DELETE v;",{"nid": deleted_node_id},@@ -2412,13 +2420,73 @@ class HyMemoryClient:{"nid": deleted_node_id},)logger.debug(f"[delete] VdbRef {deleted_node_id} cleaned from Graph")+ return Trueexcept Exception as e:logger.debug(f"[delete] VdbRef cleanup for {deleted_node_id}: {e}")+ return False# ================================================================# 异步 API# ================================================================+ async def _claim_write_outcome(+ self,+ *,+ request_id: str,+ user_id: str,+ agent_id: str,+ session_id: str,+ operation: str,+ ) -> Optional[Dict[str, Any]]:+ existing = await self._cache.claim_write_outcome(+ request_id,+ user_id,+ agent_id,+ session_id,+ operation,+ )+ if existing is None:+ return None+ expected = (user_id, agent_id, session_id, operation)+ actual = tuple(+ str(existing.get(key) or "")+ for key in ("user_id", "agent_id", "session_id", "operation")+ )+ if actual != expected:+ raise ValueError("request_id is already bound to another write scope")+ result = existing.get("result")+ if isinstance(result, dict) and existing.get("status") in {"succeeded", "failed"}:+ return {**result, "replayed": True}+ return {+ "success": False,+ "request_id": request_id,+ "outcome_status": str(existing.get("status") or "unknown"),+ "error_code": "write_outcome_not_terminal",+ "error_message": "write outcome is not terminal; query get_write_outcome",+ "replayed": True,+ }++ async def _finish_write_outcome(+ self,+ request_id: str,+ status: str,+ result: Dict[str, Any],+ ) -> None:+ if not await self._cache.finish_write_outcome(request_id, status, result):+ raise RuntimeError("write outcome disappeared before completion")++ async def _mark_write_outcome_unknown(self, request_id: str) -> None:+ await self._finish_write_outcome(+ request_id,+ "unknown",+ {+ "success": False,+ "request_id": request_id,+ "outcome_status": "unknown",+ "error_code": "write_outcome_unknown",+ },+ )+@_ensure_internal_loopasync def async_add(self,@@ -2443,27 +2511,48 @@ class HyMemoryClient:dict,可含 base_url / api_key / extra_headers / timeout;None = 用 client 配置。可用于按请求切换任意 OpenAI-compatible embedding endpoint。"""- if embed_override:- with embed_endpoint_override(- base_url=embed_override.get("base_url"),- api_key=embed_override.get("api_key"),- extra_headers=embed_override.get("extra_headers"),- timeout=embed_override.get("timeout"),- ):- return await self._async_add_impl(+ request_id = request_id or str(uuid.uuid4())+ replay = await self._claim_write_outcome(+ request_id=request_id,+ user_id=user_id,+ agent_id=agent_id,+ session_id=session_id,+ operation="add",+ )+ if replay is not None:+ return replay+ try:+ if embed_override:+ with embed_endpoint_override(+ base_url=embed_override.get("base_url"),+ api_key=embed_override.get("api_key"),+ extra_headers=embed_override.get("extra_headers"),+ timeout=embed_override.get("timeout"),+ ):+ result = await self._async_add_impl(+ data, user_id=user_id, agent_id=agent_id, session_id=session_id,+ source=source,+ metadata=metadata, memory_at=memory_at,+ scene=scene, workspace_id=workspace_id, branch=branch,+ request_id=request_id, meta=meta,+ )+ else:+ result = await self._async_add_impl(data, user_id=user_id, agent_id=agent_id, session_id=session_id,source=source,metadata=metadata, memory_at=memory_at,scene=scene, workspace_id=workspace_id, branch=branch,request_id=request_id, meta=meta,)- return await self._async_add_impl(- data, user_id=user_id, agent_id=agent_id, session_id=session_id,- source=source,- metadata=metadata, memory_at=memory_at,- scene=scene, workspace_id=workspace_id, branch=branch,- request_id=request_id, meta=meta,+ except BaseException:+ await self._mark_write_outcome_unknown(request_id)+ raise+ await self._finish_write_outcome(+ request_id,+ "succeeded" if result.get("success") is True else "failed",+ result,)+ return result@_ensure_internal_loopasync def async_finalize_session(@@ -2818,6 +2907,63 @@ class HyMemoryClient:include_runtime_diag=True,)+ def import_raw(+ self,+ content: str,+ *,+ user_id: str,+ agent_id: str = "default_agent",+ session_id: str = "default_session",+ source: str = "default",+ memory_at: Optional[datetime] = None,+ metadata: Optional[Dict[str, Any]] = None,+ raw_id: Optional[str] = None,+ request_id: Optional[str] = None,+ ) -> Dict[str, Any]:+ """Persist one exact raw record without extraction or reconciliation."""+ return self._loop_thread.run(+ self.async_import_raw(+ content,+ user_id=user_id,+ agent_id=agent_id,+ session_id=session_id,+ source=source,+ memory_at=memory_at,+ metadata=metadata,+ raw_id=raw_id,+ request_id=request_id,+ ),+ include_runtime_diag=True,+ )++ def get_raw(self, raw_id: str) -> Optional[Dict[str, Any]]:+ """Read one SDK raw record through the explicit raw API."""+ return self._loop_thread.run(self.async_get_raw(raw_id))++ def list_raw(+ self,+ *,+ user_id: str,+ agent_id: Optional[str] = None,+ session_id: Optional[str] = None,+ source: Optional[str] = None,+ limit: int = 100,+ offset: int = 0,+ order: str = "desc",+ ) -> Dict[str, Any]:+ """List raw records for an authorized SDK owner/scope."""+ return self._loop_thread.run(+ self.async_list_raw(+ user_id=user_id,+ agent_id=agent_id,+ session_id=session_id,+ source=source,+ limit=limit,+ offset=offset,+ order=order,+ )+ )+@_ensure_internal_loopasync def async_add_extracted(self,@@ -2830,6 +2976,50 @@ class HyMemoryClient:metadata: Optional[Dict[str, Any]] = None,memory_at: Optional[datetime] = None,request_id: Optional[str] = None,+ ) -> Dict[str, Any]:+ """Idempotent async wrapper for extracted-memory writes."""+ request_id = request_id or str(uuid.uuid4())+ replay = await self._claim_write_outcome(+ request_id=request_id,+ user_id=user_id,+ agent_id=agent_id,+ session_id=session_id,+ operation="add_extracted",+ )+ if replay is not None:+ return replay+ try:+ result = await self._async_add_extracted_impl(+ contents,+ user_id=user_id,+ agent_id=agent_id,+ session_id=session_id,+ source=source,+ metadata=metadata,+ memory_at=memory_at,+ request_id=request_id,+ )+ except BaseException:+ await self._mark_write_outcome_unknown(request_id)+ raise+ await self._finish_write_outcome(+ request_id,+ "succeeded" if result.get("success") is True else "failed",+ result,+ )+ return result++ async def _async_add_extracted_impl(+ self,+ contents: Union[str, List[str]],+ *,+ user_id: str = "",+ agent_id: str = "default_agent",+ session_id: str = "default_session",+ source: str = "default",+ metadata: Optional[Dict[str, Any]] = None,+ memory_at: Optional[datetime] = None,+ request_id: Optional[str] = None,) -> Dict[str, Any]:"""写入已抽取好的记忆(异步);跳过 extract,直接 reconcile。详见 add_extracted()。"""request_id = request_id or str(uuid.uuid4())@@ -2908,6 +3098,183 @@ class HyMemoryClient:return resp+ @staticmethod+ def _raw_node_to_public(node) -> Dict[str, Any]:+ def _timestamp(value):+ return int(value.timestamp()) if isinstance(value, datetime) else None++ return {+ "raw_id": node.node_id,+ "content": node.content,+ "user_id": node.user_id,+ "agent_id": node.agent_id,+ "session_id": node.session_id,+ "source": node.source,+ "memory_at": _timestamp(node.memory_at),+ "gmt_created": _timestamp(node.gmt_created),+ "custom": node.custom or {},+ }++ @_ensure_internal_loop+ async def async_import_raw(+ self,+ content: str,+ *,+ user_id: str,+ agent_id: str = "default_agent",+ session_id: str = "default_session",+ source: str = "default",+ memory_at: Optional[datetime] = None,+ metadata: Optional[Dict[str, Any]] = None,+ raw_id: Optional[str] = None,+ request_id: Optional[str] = None,+ ) -> Dict[str, Any]:+ """Persist exact source content as L1_RAW without running a model."""+ from .utils.source_filter import normalize_source++ if not isinstance(content, str) or not content:+ raise ValueError("content is required")+ if not user_id:+ raise ValueError("user_id is required")+ request_id = request_id or str(uuid.uuid4())+ replay = await self._claim_write_outcome(+ request_id=request_id,+ user_id=user_id,+ agent_id=agent_id,+ session_id=session_id,+ operation="import_raw",+ )+ if replay is not None:+ return replay+ try:+ result = await self._async_import_raw_impl(+ content,+ user_id=user_id,+ agent_id=agent_id,+ session_id=session_id,+ source=normalize_source(source),+ memory_at=memory_at,+ metadata=metadata,+ raw_id=raw_id,+ request_id=request_id,+ )+ except BaseException:+ await self._mark_write_outcome_unknown(request_id)+ raise+ await self._finish_write_outcome(request_id, "succeeded", result)+ return result++ async def _async_import_raw_impl(+ self,+ content: str,+ *,+ user_id: str,+ agent_id: str,+ session_id: str,+ source: str,+ memory_at: Optional[datetime],+ metadata: Optional[Dict[str, Any]],+ raw_id: Optional[str],+ request_id: str,+ ) -> Dict[str, Any]:+ from .models.memory import MemoryLayer, MemoryNode, MemoryStatus, SourceType++ node_id = raw_id or str(uuid.uuid4())+ existing = await self._vector_store.get_by_id(node_id)+ if existing is not None:+ identity = (+ existing.layer == MemoryLayer.L1_RAW,+ existing.content == content,+ existing.user_id == user_id,+ existing.agent_id == agent_id,+ existing.session_id == session_id,+ existing.source == source,+ )+ if not all(identity):+ raise ValueError("raw_id is already bound to different source content")+ return {+ "success": True,+ "raw_id": node_id,+ "request_id": request_id,+ "replayed": True,+ }++ custom = dict(metadata or {})+ custom["request_id"] = request_id+ custom["input_kind"] = "raw_exact_import"+ embedding = await self._embed_service.embed(content)+ node = MemoryNode(+ node_id=node_id,+ user_id=user_id,+ agent_id=agent_id,+ session_id=session_id,+ source=source,+ layer=MemoryLayer.L1_RAW,+ content=content,+ source_type=SourceType.EXPLICIT,+ status=MemoryStatus.ACTIVE,+ is_latest=True,+ embedding=embedding,+ memory_at=memory_at,+ custom=custom,+ )+ stored_id = await self._vector_store.upsert(node)+ if stored_id != node_id:+ raise RuntimeError("raw import changed the requested identity")+ return {"success": True, "raw_id": node_id, "request_id": request_id}++ @_ensure_internal_loop+ async def async_get_raw(self, raw_id: str) -> Optional[Dict[str, Any]]:+ from .models.memory import MemoryLayer++ node = await self._vector_store.get_by_id(raw_id)+ if node is None or node.layer != MemoryLayer.L1_RAW:+ return None+ return self._raw_node_to_public(node)++ @_ensure_internal_loop+ async def async_list_raw(+ self,+ *,+ user_id: str,+ agent_id: Optional[str] = None,+ session_id: Optional[str] = None,+ source: Optional[str] = None,+ limit: int = 100,+ offset: int = 0,+ order: str = "desc",+ ) -> Dict[str, Any]:+ from .models.memory import MemoryLayer, MemoryStatus++ if not user_id:+ raise ValueError("user_id is required")+ if limit < 1 or offset < 0:+ raise ValueError("limit must be positive and offset must be non-negative")+ nodes = await self._vector_store.list_by_user(+ user_id=user_id,+ agent_id=agent_id,+ status_filter=[MemoryStatus.ACTIVE],+ layers=[MemoryLayer.L1_RAW],+ include_sources=[source] if source else None,+ limit=100_000,+ only_latest=False,+ with_vectors=False,+ allow_raw_layer=True,+ )+ if session_id:+ nodes = [node for node in nodes if node.session_id == session_id]+ nodes = self._sort_memory_nodes(nodes, order=order)+ total = len(nodes)+ return {+ "raw": [+ self._raw_node_to_public(node)+ for node in nodes[offset: offset + limit]+ ],+ "total": total,+ "limit": limit,+ "offset": offset,+ }+@staticmethoddef _public_search_views(result_memories: List[Dict[str, Any]],@@ -4070,6 +4437,15 @@ class HyMemoryClient:except Exception:old_isolation_key = ""+ graph_node = None+ graph_inspection_failed = False+ if self._graph_store is not None:+ try:+ graph_node = await self._graph_store.get_node(memory_id)+ except Exception as e:+ graph_inspection_failed = True+ logger.warning(f"[delete] graph_store lookup failed: {e}")+# ── 演化链修复(VDB 删除前执行)──chain_repaired = Falseif node is not None:@@ -4085,19 +4461,27 @@ class HyMemoryClient:# 删除图数据库节点 + 清理 evidence(如有)graph_deleted = False+ graph_cleanup_ok = Trueif self._graph_store is not None:- try:- await self._graph_store.delete_node(memory_id)- graph_deleted = True- except Exception as e:- logger.warning(f"[delete] graph_store delete failed: {e}")+ if graph_node is not None:+ try:+ graph_deleted = bool(await self._graph_store.delete_node(memory_id))+ except Exception as e:+ logger.warning(f"[delete] graph_store delete failed: {e}")# 清理该节点作为 VdbRef 被其他 Schema 引用的情况- try:- await self._cleanup_graph_evidence(memory_id)- except Exception as e:- logger.debug(f"[delete] graph evidence cleanup failed (non-fatal): {e}")-- deleted_count = 1 if deleted else 0+ if node is not None or graph_node is not None:+ graph_cleanup_ok = await self._cleanup_graph_evidence(memory_id)++ found = node is not None or graph_node is not None+ stores_complete = (+ not graph_inspection_failed+ and (node is None or bool(deleted))+ and (graph_node is None or graph_deleted)+ and graph_cleanup_ok+ )+ success = found and stores_complete+ partial = found and not stores_complete and (bool(deleted) or graph_deleted)+ deleted_count = 1 if success else 0# 清理 tag_index:此 memory 删除后,检查其每个 tag 是否还有其他 memory 引用;# 无引用则从 tag_index 中移除。失败静默降级,不影响 delete 语义。@@ -4136,10 +4520,14 @@ class HyMemoryClient:_parsed = {"memory_id": memory_id,**_ident,- "found": node is not None,+ "found": found,"vdb_deleted": bool(deleted),+ "graph_found": graph_node is not None,"graph_deleted": graph_deleted,+ "graph_cleanup_ok": graph_cleanup_ok,+ "graph_inspection_failed": graph_inspection_failed,"deleted_count": deleted_count,+ "partial": partial,"chain_repaired": chain_repaired,}if node is not None:@@ -4156,8 +4544,17 @@ class HyMemoryClient:)return {- "success": deleted,+ "success": success,"deleted_count": deleted_count,+ "partial": partial,+ "vdb_deleted": bool(deleted),+ "graph_deleted": graph_deleted,+ "graph_cleanup_ok": graph_cleanup_ok,+ "error_code": (+ "delete_incomplete"+ if graph_inspection_failed or (found and not stores_complete)+ else None+ ),"request_id": request_id,"elapsed_ms": round((time.perf_counter() - t0) * 1000, 2),}@@ -4444,6 +4841,20 @@ class HyMemoryClient:out.append(layer)return out+ @staticmethod+ def _normalize_statuses(statuses: Optional[List[Any]]) -> Optional[List]:+ """Normalize public lifecycle filters without inventing product states."""+ from .models.memory import MemoryStatus++ if not statuses:+ return None+ out: List[MemoryStatus] = []+ for item in statuses:+ status = item if isinstance(item, MemoryStatus) else MemoryStatus(str(item).lower())+ if status not in out:+ out.append(status)+ return out+@staticmethoddef _sort_memory_nodes(nodes: List, *, order: str) -> List:reverse = (order.lower() != "asc")@@ -4472,14 +4883,16 @@ class HyMemoryClient:user_ids: Optional[List[str]] = None,agent_ids: Optional[List[str]] = None,layers: Optional[List] = None,+ statuses: Optional[List] = None,with_evolution: bool = False,) -> Dict[str, Any]:from .models.memory import MemoryLayer, MemoryStatusfrom .pipelines._retrieval.user_level_l0 import collapse_user_level_l0_hits- # 过滤条件维持改动前原样(仅 status=ACTIVE),本次只加多值枚举。- # 不叠加 only_latest:正常数据下 writer 对 is_latest/status 成对写,两者等效,- # 加了只能多拦脏数据,却会改变现网 list 的返回口径。+ # Default stays ACTIVE for compatibility. An explicit filter is how+ # callers inspect SDK-owned superseded/shadow lifecycle records.+ effective_statuses = statuses or [MemoryStatus.ACTIVE]+ # 不叠加 only_latest:正常数据下 writer 对 is_latest/status 成对写,两者等效。# 列表页只需 payload(content/tags/custom/链头信息)与排序字段,# 不涉及向量运算,一概 with_vectors=False,避免拉回大量 embedding。#@@ -4491,7 +4904,7 @@ class HyMemoryClient:agent_id=agent_id,user_ids=user_ids,agent_ids=agent_ids,- status_filter=[MemoryStatus.ACTIVE],+ status_filter=effective_statuses,layers=layers,with_vectors=False,)@@ -4505,7 +4918,7 @@ class HyMemoryClient:l0_nodes = await self._vector_store.list_by_user(user_id=user_id,user_ids=user_ids,- status_filter=[MemoryStatus.ACTIVE],+ status_filter=effective_statuses,layers=[MemoryLayer.L0_BASIC_INFO],with_vectors=False,)@@ -4579,9 +4992,10 @@ class HyMemoryClient:user_ids: Optional[List[str]] = None,agent_ids: Optional[List[str]] = None,layers: Optional[List] = None,+ statuses: Optional[List] = None,) -> Optional[Dict[str, Any]]:"""列出图库 L6/L7 节点;无图数据、不可用或 layers 不含图层时返回 None。"""- from .models.memory import MemoryLayer, MemoryNode+ from .models.memory import MemoryLayer, MemoryNode, MemoryStatusgraph_layers = [MemoryLayer.L6_SCHEMA, MemoryLayer.L7_INTENTION]if layers:@@ -4619,6 +5033,11 @@ class HyMemoryClient:for layer in graph_layers])graph_nodes = [n for chunk in chunks for n in chunk]+ effective_statuses = statuses or [MemoryStatus.ACTIVE]+ graph_nodes = [+ node for node in graph_nodes+ if getattr(node, "status", None) in effective_statuses+ ]graph_nodes = self._sort_memory_nodes(graph_nodes, order=order)total = len(graph_nodes)@@ -4649,6 +5068,7 @@ class HyMemoryClient:offset: int,request_id: str,t0: float,+ statuses: Optional[List] = None,) -> Dict[str, Any]:"""按 workspace_id(+可选 branch)纯过滤列出经验层完整详情。@@ -4664,6 +5084,9 @@ class HyMemoryClient:"offset": offset,"elapsed_ms": round((time.perf_counter() - t0) * 1000, 2),}+ from .models.memory import MemoryStatus+ if statuses and MemoryStatus.ACTIVE not in statuses:+ return emptytry:await self._get_coding_writer() # 副作用:lazy init storeexcept Exception as e:@@ -4692,6 +5115,7 @@ class HyMemoryClient:"files": list(d.files),"source_fact_ids": list(d.source_fact_ids),"confidence": d.confidence,+ "status": MemoryStatus.ACTIVE.value,"updated_at": d.updated_at.isoformat() if d.updated_at else None,"source": d.source,}@@ -4726,6 +5150,7 @@ class HyMemoryClient:user_ids: Optional[List[str]] = None,agent_ids: Optional[List[str]] = None,layers: Optional[List[Any]] = None,+ statuses: Optional[List[Any]] = None,with_evolution: bool = False,) -> Dict[str, Any]:"""@@ -4746,6 +5171,12 @@ class HyMemoryClient:显式指定则完全以传入为准,包含只要 L1_RAW 的场景。- 指定的层级都不在图库(L6/L7)时跳过图库查询,返回中省略 graph 键。+ statuses(默认空):+ - 不传时保持兼容,只返回 ACTIVE。+ - 可传 MemoryStatus 或其字符串值,读取 SDK 内现存的 superseded /+ shadow / negated / conflicted / archived 记录。+ - delete 是物理删除,不存在可列出的 deleted 状态。+with_evolution(默认 False):- 为 VDB 条目附加 `evolution_chain`(latest → oldest),结构与 search 一致,仅在该条记忆确有演化链时出现。@@ -4779,12 +5210,14 @@ class HyMemoryClient:request_id = str(uuid.uuid4())set_request_id(request_id)t0 = time.perf_counter()+ effective_statuses = self._normalize_statuses(statuses)# workspace_id 非空 → 走 coding memory 列表路径if workspace_id:return await self._list_coding(user_id=user_id, workspace_id=workspace_id, branch=branch,limit=limit, offset=offset, request_id=request_id, t0=t0,+ statuses=effective_statuses,)effective_layers = self._normalize_layers(layers)@@ -4793,13 +5226,14 @@ class HyMemoryClient:user_id=user_id, agent_id=agent_id,user_ids=user_ids, agent_ids=agent_ids,limit=limit, offset=offset, order=order,- layers=effective_layers, with_evolution=with_evolution,+ layers=effective_layers, statuses=effective_statuses,+ with_evolution=with_evolution,)graph = await self._list_graph_bucket(user_id=user_id, agent_id=agent_id,user_ids=user_ids, agent_ids=agent_ids,limit=limit, offset=offset, order=order,- layers=effective_layers,+ layers=effective_layers, statuses=effective_statuses,)elapsed = round((time.perf_counter() - t0) * 1000, 2)@@ -6147,6 +6581,13 @@ class HyMemoryClient:# History API(异步)# ================================================================+ @_ensure_internal_loop+ async def async_get_write_outcome(self, request_id: str) -> Optional[Dict[str, Any]]:+ """Read a durable write result without scanning memory records."""+ if not request_id:+ raise ValueError("request_id is required")+ return await self._cache.get_write_outcome(request_id)+@_ensure_internal_loopasync def async_history(self, memory_id: str) -> List[Dict[str, Any]]:"""查询某条记忆的变更历史(异步)"""diff --git a/hy_memory/data/cache_base.py b/hy_memory/data/cache_base.pyindex df47cd6..011c994 100644--- a/hy_memory/data/cache_base.py+++ b/hy_memory/data/cache_base.py@@ -114,6 +114,37 @@ class CacheBase(ABC):"""查询 pipeline 中间结果日志"""...+ # ================================================================+ # Durable write outcomes+ # ================================================================++ @abstractmethod+ async def claim_write_outcome(+ self,+ request_id: str,+ user_id: str,+ agent_id: str,+ session_id: str,+ operation: str,+ ) -> Optional[Dict[str, Any]]:+ """Claim one idempotent write; return the existing row if already claimed."""+ ...++ @abstractmethod+ async def finish_write_outcome(+ self,+ request_id: str,+ status: str,+ result: Dict[str, Any],+ ) -> bool:+ """Persist the terminal/unknown result for a claimed write."""+ ...++ @abstractmethod+ async def get_write_outcome(self, request_id: str) -> Optional[Dict[str, Any]]:+ """Read one durable write outcome by exact request id."""+ ...+# ================================================================# Summary Buffer(rolling summary 的未消费 turn 暂存)#diff --git a/hy_memory/data/cache_mysql.py b/hy_memory/data/cache_mysql.pyindex 31adc72..4903de0 100644--- a/hy_memory/data/cache_mysql.py+++ b/hy_memory/data/cache_mysql.py@@ -81,6 +81,21 @@ _CREATE_TABLES_SQL = [)""","""+ CREATE TABLE IF NOT EXISTS write_outcomes (+ request_id VARCHAR(256) NOT NULL,+ user_id VARCHAR(255) NOT NULL,+ agent_id VARCHAR(255) NOT NULL DEFAULT '',+ session_id VARCHAR(255) NOT NULL DEFAULT '',+ operation VARCHAR(32) NOT NULL,+ status VARCHAR(32) NOT NULL,+ result_json LONGTEXT NOT NULL,+ created_at VARCHAR(64) NOT NULL,+ updated_at VARCHAR(64) NOT NULL,+ PRIMARY KEY (request_id),+ KEY idx_write_outcomes_owner (user_id, agent_id, session_id)+ ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4+ """,+ """CREATE TABLE IF NOT EXISTS system_metrics (minute_ts VARCHAR(32) NOT NULL,data LONGTEXT NOT NULL,@@ -459,6 +474,62 @@ class MysqlCache(CacheBase):logger.warning(f"get_pipeline_logs failed: {e}")return []+ async def claim_write_outcome(+ self,+ request_id: str,+ user_id: str,+ agent_id: str,+ session_id: str,+ operation: str,+ ) -> Optional[Dict[str, Any]]:+ now = datetime.now().isoformat()+ inserted = await self._execute(+ """+ INSERT IGNORE INTO write_outcomes (+ request_id, user_id, agent_id, session_id, operation,+ status, result_json, created_at, updated_at+ ) VALUES (%s, %s, %s, %s, %s, 'running', '{}', %s, %s)+ """,+ (request_id, user_id, agent_id, session_id, operation, now, now),+ )+ if inserted == 1:+ return None+ return await self.get_write_outcome(request_id)++ async def finish_write_outcome(+ self,+ request_id: str,+ status: str,+ result: Dict[str, Any],+ ) -> bool:+ updated = await self._execute(+ """+ UPDATE write_outcomes+ SET status = %s, result_json = %s, updated_at = %s+ WHERE request_id = %s+ """,+ (+ status,+ json.dumps(result, ensure_ascii=False, default=str),+ datetime.now().isoformat(),+ request_id,+ ),+ )+ return updated == 1++ async def get_write_outcome(self, request_id: str) -> Optional[Dict[str, Any]]:+ row = await self._fetchone(+ "SELECT * FROM write_outcomes WHERE request_id = %s",+ (request_id,),+ )+ if row is None:+ return None+ try:+ row["result"] = json.loads(row.pop("result_json") or "{}")+ except (TypeError, json.JSONDecodeError):+ row["result"] = {}+ return row+# ================================================================# System Metrics(分钟粒度落盘)# ================================================================diff --git a/hy_memory/data/cache_sqlite.py b/hy_memory/data/cache_sqlite.pyindex 8f1db60..3cca357 100644--- a/hy_memory/data/cache_sqlite.py+++ b/hy_memory/data/cache_sqlite.py@@ -87,6 +87,20 @@ CREATE TABLE IF NOT EXISTS pipeline_logs_v2 (CREATE INDEX IF NOT EXISTS idx_plog_request ON pipeline_logs_v2(request_id);CREATE INDEX IF NOT EXISTS idx_plog_user ON pipeline_logs_v2(user_id);+CREATE TABLE IF NOT EXISTS write_outcomes (+ request_id TEXT PRIMARY KEY,+ user_id TEXT NOT NULL,+ agent_id TEXT NOT NULL DEFAULT '',+ session_id TEXT NOT NULL DEFAULT '',+ operation TEXT NOT NULL,+ status TEXT NOT NULL,+ result_json TEXT NOT NULL DEFAULT '{}',+ created_at TEXT NOT NULL,+ updated_at TEXT NOT NULL+);+CREATE INDEX IF NOT EXISTS idx_write_outcomes_owner+ON write_outcomes(user_id, agent_id, session_id);+CREATE TABLE IF NOT EXISTS system_metrics (minute_ts TEXT PRIMARY KEY,data TEXT NOT NULL,@@ -414,6 +428,88 @@ class SqliteCache(CacheBase):logger.warning(f"get_pipeline_logs failed: {e}")return []+ # ================================================================+ # Durable write outcomes+ # ================================================================++ async def claim_write_outcome(+ self,+ request_id: str,+ user_id: str,+ agent_id: str,+ session_id: str,+ operation: str,+ ) -> Optional[Dict[str, Any]]:+ def _claim():+ with self._lock:+ now = datetime.now().isoformat()+ cursor = self._conn.execute(+ """+ INSERT OR IGNORE INTO write_outcomes (+ request_id, user_id, agent_id, session_id, operation,+ status, result_json, created_at, updated_at+ ) VALUES (?, ?, ?, ?, ?, 'running', '{}', ?, ?)+ """,+ (request_id, user_id, agent_id, session_id, operation, now, now),+ )+ self._conn.commit()+ if cursor.rowcount == 1:+ return None+ row = self._conn.execute(+ "SELECT * FROM write_outcomes WHERE request_id = ?",+ (request_id,),+ ).fetchone()+ return dict(row) if row else None++ existing = await _run_in_sqlite_pool(_claim)+ if existing is None:+ return None+ return await self.get_write_outcome(request_id)++ async def finish_write_outcome(+ self,+ request_id: str,+ status: str,+ result: Dict[str, Any],+ ) -> bool:+ def _finish():+ with self._lock:+ cursor = self._conn.execute(+ """+ UPDATE write_outcomes+ SET status = ?, result_json = ?, updated_at = ?+ WHERE request_id = ?+ """,+ (+ status,+ json.dumps(result, ensure_ascii=False, default=str),+ datetime.now().isoformat(),+ request_id,+ ),+ )+ self._conn.commit()+ return cursor.rowcount == 1++ return await _run_in_sqlite_pool(_finish)++ async def get_write_outcome(self, request_id: str) -> Optional[Dict[str, Any]]:+ def _get():+ with self._lock:+ row = self._conn.execute(+ "SELECT * FROM write_outcomes WHERE request_id = ?",+ (request_id,),+ ).fetchone()+ return dict(row) if row else None++ row = await _run_in_sqlite_pool(_get)+ if row is None:+ return None+ try:+ row["result"] = json.loads(row.pop("result_json") or "{}")+ except (TypeError, json.JSONDecodeError):+ row["result"] = {}+ return row+# ================================================================# System Metrics(分钟粒度落盘)# ================================================================diff --git a/hy_memory/snapshot.py b/hy_memory/snapshot.pynew file mode 100644index 0000000..4ff1ec5--- /dev/null+++ b/hy_memory/snapshot.py@@ -0,0 +1,150 @@+"""Public, offline snapshot support for the SDK-owned local data plane."""++from __future__ import annotations++import hashlib+import os+import shutil+from dataclasses import dataclass+from pathlib import Path+++class DataPlaneSnapshotRejected(RuntimeError):+ def __init__(self, code: str) -> None:+ super().__init__(code)+ self.code = code+++@dataclass(frozen=True)+class DataPlaneSnapshot:+ source_root: Path+ snapshot_root: Path+ files: tuple[dict[str, object], ...]+ total_bytes: int+++@dataclass(frozen=True)+class DataPlaneRestore:+ restored_root: Path+ previous_root: Path | None+ files_restored: int+ total_bytes: int+++def _sha256(path: Path) -> str:+ digest = hashlib.sha256()+ with path.open("rb") as handle:+ for chunk in iter(lambda: handle.read(1024 * 1024), b""):+ digest.update(chunk)+ return digest.hexdigest()+++def snapshot_local_data_plane(+ *,+ source_root: Path,+ target_root: Path,+ writers_stopped: bool,+) -> DataPlaneSnapshot:+ """Copy one quiesced local SDK root and return a verified inventory.++ Remote providers require their own export implementation and must not call+ this local-path contract.+ """+ if not writers_stopped:+ raise DataPlaneSnapshotRejected("data_plane_snapshot_writers_running")+ source = source_root.resolve()+ target = target_root.resolve()+ if source.is_symlink() or not source.is_dir():+ raise DataPlaneSnapshotRejected("data_plane_snapshot_source_invalid")+ if target.exists():+ raise DataPlaneSnapshotRejected("data_plane_snapshot_target_exists")++ try:+ target.mkdir(parents=True)+ for root, directories, files in os.walk(source, followlinks=False):+ root_path = Path(root)+ relative = root_path.relative_to(source)+ target_directory = target / relative+ target_directory.mkdir(parents=True, exist_ok=True)+ for name in directories:+ if (root_path / name).is_symlink():+ raise DataPlaneSnapshotRejected("data_plane_snapshot_symlink")+ for name in files:+ item = root_path / name+ if item.is_symlink():+ raise DataPlaneSnapshotRejected("data_plane_snapshot_symlink")+ shutil.copy2(item, target_directory / name)++ inventory: list[dict[str, object]] = []+ for path in sorted(item for item in target.rglob("*") if item.is_file()):+ inventory.append(+ {+ "path": path.relative_to(target).as_posix(),+ "bytes": path.stat().st_size,+ "sha256": _sha256(path),+ }+ )+ for item in inventory:+ copied = target / str(item["path"])+ if copied.stat().st_size != item["bytes"] or _sha256(copied) != item["sha256"]:+ raise DataPlaneSnapshotRejected("data_plane_snapshot_verify_failed")+ except DataPlaneSnapshotRejected:+ shutil.rmtree(target, ignore_errors=True)+ raise+ except OSError as error:+ shutil.rmtree(target, ignore_errors=True)+ raise DataPlaneSnapshotRejected("data_plane_snapshot_failed") from error++ return DataPlaneSnapshot(+ source_root=source,+ snapshot_root=target,+ files=tuple(inventory),+ total_bytes=sum(int(item["bytes"]) for item in inventory),+ )+++def restore_local_data_plane(+ *,+ snapshot_root: Path,+ target_root: Path,+ writers_stopped: bool,+ protective_root: Path | None = None,+) -> DataPlaneRestore:+ """Replace one local SDK root from a verified snapshot with rollback."""+ if not writers_stopped:+ raise DataPlaneSnapshotRejected("data_plane_restore_writers_running")+ source = snapshot_root.resolve()+ target = target_root.resolve()+ protective = (+ protective_root.resolve()+ if protective_root is not None+ else target.parent / f".{target.name}.pre-restore"+ )+ staging = target.parent / f".{target.name}.restore.tmp"+ if target.is_symlink() or protective.exists() or staging.exists():+ raise DataPlaneSnapshotRejected("data_plane_restore_target_unsafe")++ copied = snapshot_local_data_plane(+ source_root=source,+ target_root=staging,+ writers_stopped=True,+ )+ previous: Path | None = None+ try:+ if target.exists():+ target.replace(protective)+ previous = protective+ staging.replace(target)+ except OSError as error:+ if previous is not None and previous.exists() and not target.exists():+ previous.replace(target)+ previous = None+ shutil.rmtree(staging, ignore_errors=True)+ raise DataPlaneSnapshotRejected("data_plane_restore_replace_failed") from error++ return DataPlaneRestore(+ restored_root=target,+ previous_root=previous,+ files_restored=len(copied.files),+ total_bytes=copied.total_bytes,+ )diff --git a/tests/test_cache_backend_parity.py b/tests/test_cache_backend_parity.pyindex 8204a6a..3b359a4 100644--- a/tests/test_cache_backend_parity.py+++ b/tests/test_cache_backend_parity.py@@ -24,6 +24,9 @@ from hy_memory.data.cache_sqlite import SqliteCacheSTATEFUL_METHODS = ["get_episode_state","upsert_episode_state",+ "claim_write_outcome",+ "finish_write_outcome",+ "get_write_outcome",]BACKENDS = [@@ -70,6 +73,16 @@ def test_episode_state_table_declared(backend):)[email protected]("backend", BACKENDS)+def test_write_outcomes_table_declared(backend):+ import hy_memory.data.cache_mysql as m+ import hy_memory.data.cache_sqlite as s++ mod = s if backend is SqliteCache else m+ src = inspect.getsource(mod)+ assert "CREATE TABLE IF NOT EXISTS write_outcomes" in src++class TestRollingSummaryFullyRemoved:"""rolling summary 已整体移除,残留引用会让应用在启动路径报错。"""diff --git a/tests/test_data_plane_snapshot.py b/tests/test_data_plane_snapshot.pynew file mode 100644index 0000000..fc49b23--- /dev/null+++ b/tests/test_data_plane_snapshot.py@@ -0,0 +1,125 @@+from __future__ import annotations++import hashlib++import pytest++from hy_memory.snapshot import (+ DataPlaneSnapshotRejected,+ restore_local_data_plane,+ snapshot_local_data_plane,+)+++def _sha256(path):+ return hashlib.sha256(path.read_bytes()).hexdigest()+++def test_snapshot_copies_and_verifies_local_sdk_tree(tmp_path):+ source = tmp_path / "source"+ (source / "vector").mkdir(parents=True)+ (source / "vector" / "nodes.bin").write_bytes(b"vector")+ (source / "cache.sqlite3").write_bytes(b"cache")+ target = tmp_path / "snapshot"++ result = snapshot_local_data_plane(+ source_root=source,+ target_root=target,+ writers_stopped=True,+ )++ assert {item["path"] for item in result.files} == {+ "cache.sqlite3",+ "vector/nodes.bin",+ }+ for item in result.files:+ copied = target / item["path"]+ assert copied.stat().st_size == item["bytes"]+ assert _sha256(copied) == item["sha256"]+ assert result.total_bytes == len(b"vector") + len(b"cache")+++def test_snapshot_refuses_active_writers(tmp_path):+ source = tmp_path / "source"+ source.mkdir()+ with pytest.raises(DataPlaneSnapshotRejected) as caught:+ snapshot_local_data_plane(+ source_root=source,+ target_root=tmp_path / "snapshot",+ writers_stopped=False,+ )+ assert caught.value.code == "data_plane_snapshot_writers_running"+++def test_snapshot_rejects_symlink_and_removes_partial_target(tmp_path):+ source = tmp_path / "source"+ source.mkdir()+ outside = tmp_path / "outside"+ outside.write_text("outside", encoding="utf-8")+ try:+ (source / "linked").symlink_to(outside)+ except OSError:+ pytest.skip("symlinks unavailable")+ target = tmp_path / "snapshot"++ with pytest.raises(DataPlaneSnapshotRejected) as caught:+ snapshot_local_data_plane(+ source_root=source,+ target_root=target,+ writers_stopped=True,+ )+ assert caught.value.code == "data_plane_snapshot_symlink"+ assert not target.exists()+++def test_snapshot_target_must_not_exist(tmp_path):+ source = tmp_path / "source"+ target = tmp_path / "snapshot"+ source.mkdir()+ target.mkdir()+ with pytest.raises(DataPlaneSnapshotRejected) as caught:+ snapshot_local_data_plane(+ source_root=source,+ target_root=target,+ writers_stopped=True,+ )+ assert caught.value.code == "data_plane_snapshot_target_exists"+++def test_restore_replaces_data_plane_and_keeps_protective_copy(tmp_path):+ snapshot = tmp_path / "snapshot"+ target = tmp_path / "live"+ (snapshot / "vector").mkdir(parents=True)+ (snapshot / "vector" / "nodes.bin").write_bytes(b"new")+ (target / "vector").mkdir(parents=True)+ (target / "vector" / "nodes.bin").write_bytes(b"old")+ protective = tmp_path / "previous"++ result = restore_local_data_plane(+ snapshot_root=snapshot,+ target_root=target,+ protective_root=protective,+ writers_stopped=True,+ )++ assert (target / "vector" / "nodes.bin").read_bytes() == b"new"+ assert (protective / "vector" / "nodes.bin").read_bytes() == b"old"+ assert result.previous_root == protective+ assert result.files_restored == 1+++def test_restore_refuses_active_writers_without_touching_live_data(tmp_path):+ snapshot = tmp_path / "snapshot"+ target = tmp_path / "live"+ snapshot.mkdir()+ target.mkdir()+ (target / "value").write_text("old", encoding="utf-8")++ with pytest.raises(DataPlaneSnapshotRejected) as caught:+ restore_local_data_plane(+ snapshot_root=snapshot,+ target_root=target,+ writers_stopped=False,+ )+ assert caught.value.code == "data_plane_restore_writers_running"+ assert (target / "value").read_text(encoding="utf-8") == "old"diff --git a/tests/test_delete_complete.py b/tests/test_delete_complete.pynew file mode 100644index 0000000..db1f6e6--- /dev/null+++ b/tests/test_delete_complete.py@@ -0,0 +1,120 @@+from __future__ import annotations++from unittest.mock import AsyncMock++import pytest++from hy_memory.client import HyMemoryClient+from hy_memory.config import MemoryConfig+from hy_memory.models.memory import MemoryLayer, MemoryNode+++class VectorStore:+ _collection_name = "test"++ def __init__(self, node=None, *, delete_result=True):+ self.node = node+ self.delete_result = delete_result++ async def get_by_id(self, _memory_id):+ return self.node++ async def delete(self, _memory_id):+ result = self.node is not None and self.delete_result+ if result:+ self.node = None+ return result++ async def delete_retrieval_clauses(self, _memory_id):+ return None+++class GraphStore:+ def __init__(self, node=None, *, delete_result=True, lookup_error=False):+ self.node = node+ self.delete_result = delete_result+ self.lookup_error = lookup_error++ async def get_node(self, _memory_id):+ if self.lookup_error:+ raise RuntimeError("graph unavailable")+ return self.node++ async def delete_node(self, _memory_id):+ if self.delete_result:+ self.node = None+ return self.delete_result+++def _node():+ return MemoryNode(+ node_id="m1",+ user_id="u1",+ agent_id="a1",+ session_id="s1",+ content="body",+ layer=MemoryLayer.L2_FACT,+ )+++def _client(vector, graph):+ client = HyMemoryClient.__new__(HyMemoryClient)+ client._vector_store = vector+ client._graph_store = graph+ client._history_store = None+ client._config = MemoryConfig.from_dict(+ {"vector_store": {"provider": "faiss", "collection_name": "test"}}+ )+ client._maybe_store_op_log = AsyncMock()+ client._cleanup_graph_evidence = AsyncMock(return_value=True)+ return client+++async def test_delete_succeeds_only_when_every_existing_store_is_deleted():+ client = _client(VectorStore(_node()), GraphStore(_node()))+ result = await HyMemoryClient.async_delete.__wrapped__(client, "m1")++ assert result["success"] is True+ assert result["deleted_count"] == 1+ assert result["vdb_deleted"] is True+ assert result["graph_deleted"] is True+ assert result["partial"] is False+ assert result["error_code"] is None+++async def test_graph_failure_is_reported_as_partial_not_success():+ client = _client(+ VectorStore(_node()),+ GraphStore(_node(), delete_result=False),+ )+ result = await HyMemoryClient.async_delete.__wrapped__(client, "m1")++ assert result["success"] is False+ assert result["deleted_count"] == 0+ assert result["vdb_deleted"] is True+ assert result["graph_deleted"] is False+ assert result["partial"] is True+ assert result["error_code"] == "delete_incomplete"+++async def test_graph_only_memory_can_be_physically_deleted():+ client = _client(VectorStore(None), GraphStore(_node()))+ result = await HyMemoryClient.async_delete.__wrapped__(client, "m1")++ assert result["success"] is True+ assert result["vdb_deleted"] is False+ assert result["graph_deleted"] is True+ assert result["deleted_count"] == 1+++async def test_graph_lookup_failure_never_collapses_to_not_found_success():+ client = _client(VectorStore(None), GraphStore(lookup_error=True))+ result = await HyMemoryClient.async_delete.__wrapped__(client, "m1")++ assert result["success"] is False+ assert result["partial"] is False+ assert result["error_code"] == "delete_incomplete"diff --git a/tests/test_list_layer_filter_client.py b/tests/test_list_layer_filter_client.pyindex 6be814e..ce8569e 100644--- a/tests/test_list_layer_filter_client.py+++ b/tests/test_list_layer_filter_client.py@@ -31,7 +31,12 @@ def run(coro):DIMS = 32-def _node(user_id="u1", content="x", layer=MemoryLayer.L2_FACT):+def _node(+ user_id="u1",+ content="x",+ layer=MemoryLayer.L2_FACT,+ status=MemoryStatus.ACTIVE,+):import randomn = MemoryNode(node_id=str(uuid.uuid4()),@@ -40,8 +45,8 @@ def _node(user_id="u1", content="x", layer=MemoryLayer.L2_FACT):session_id="s1",content=content,layer=layer,- status=MemoryStatus.ACTIVE,- is_latest=True,+ status=status,+ is_latest=status == MemoryStatus.ACTIVE,)vec = [random.gauss(0, 1) for _ in range(DIMS)]norm = sum(v * v for v in vec) ** 0.5@@ -104,6 +109,22 @@ class TestNormalizeLayers:HyMemoryClient._normalize_layers(["l3_identity"])+class TestNormalizeStatuses:+ def test_none_and_empty_preserve_active_default(self):+ assert HyMemoryClient._normalize_statuses(None) is None+ assert HyMemoryClient._normalize_statuses([]) is None++ def test_string_and_enum_values_are_deduplicated(self):+ got = HyMemoryClient._normalize_statuses(+ ["superseded", MemoryStatus.SHADOW, "superseded"]+ )+ assert got == [MemoryStatus.SUPERSEDED, MemoryStatus.SHADOW]++ def test_invalid_status_raises(self):+ with pytest.raises(ValueError):+ HyMemoryClient._normalize_statuses(["deleted"])++class TestVdbBucketLayerFilter:def _seed(self, store):run(store.upsert_batch([@@ -163,6 +184,24 @@ class TestVdbBucketLayerFilter:))assert [m["content"] for m in got["memories"]] == ["fact"]+ def test_status_filter_defaults_to_active_and_can_read_superseded(self, faiss_store):+ run(faiss_store.upsert_batch([+ _node(content="active", status=MemoryStatus.ACTIVE),+ _node(content="old", status=MemoryStatus.SUPERSEDED),+ _node(content="hidden", status=MemoryStatus.SHADOW),+ ]))++ default_page = run(_client_with(faiss_store)._list_vdb_bucket(+ user_id="u1", agent_id=None, limit=100, offset=0, order="desc",+ ))+ assert [m["content"] for m in default_page["memories"]] == ["active"]++ lifecycle_page = run(_client_with(faiss_store)._list_vdb_bucket(+ user_id="u1", agent_id=None, limit=100, offset=0, order="desc",+ statuses=[MemoryStatus.SUPERSEDED, MemoryStatus.SHADOW],+ ))+ assert {m["content"] for m in lifecycle_page["memories"]} == {"old", "hidden"}+def test_layer_filter_composes_with_multi_user(self, faiss_store):"""R3 与 R1 叠加:多用户 + 层级筛选同时生效。"""run(faiss_store.upsert_batch([@@ -215,3 +254,37 @@ class TestGraphBucketLayerSkip:user_id="u1", agent_id=None, limit=10, offset=0, order="desc",))assert calls == [1], "不传 layers 时行为与改动前一致"++ def test_graph_status_filter_matches_vdb_contract(self):+ active = _node(content="active graph", layer=MemoryLayer.L6_SCHEMA)+ old = _node(+ content="old graph",+ layer=MemoryLayer.L6_SCHEMA,+ status=MemoryStatus.SUPERSEDED,+ )++ class GraphStore:+ async def get_all_nodes(self, *_args, **_kwargs):+ return [active, old]++ async def close(self):+ return None++ c = HyMemoryClient.__new__(HyMemoryClient)++ async def _acquire():+ return GraphStore(), True++ c._acquire_graph_store_for_purge = _acquire+ default_page = run(c._list_graph_bucket(+ user_id="u1", agent_id=None, limit=10, offset=0, order="desc",+ layers=[MemoryLayer.L6_SCHEMA],+ ))+ assert [item["content"] for item in default_page["nodes"]] == ["active graph"]++ old_page = run(c._list_graph_bucket(+ user_id="u1", agent_id=None, limit=10, offset=0, order="desc",+ layers=[MemoryLayer.L6_SCHEMA],+ statuses=[MemoryStatus.SUPERSEDED],+ ))+ assert [item["content"] for item in old_page["nodes"]] == ["old graph"]diff --git a/tests/test_raw_public_api.py b/tests/test_raw_public_api.pynew file mode 100644index 0000000..20d71f5--- /dev/null+++ b/tests/test_raw_public_api.py@@ -0,0 +1,162 @@+from __future__ import annotations++from unittest.mock import AsyncMock++import pytest++from hy_memory.client import HyMemoryClient+from hy_memory.models.memory import MemoryLayer+++class OutcomeCache:+ def __init__(self):+ self.rows = {}++ async def claim_write_outcome(+ self, request_id, user_id, agent_id, session_id, operation+ ):+ if request_id in self.rows:+ return self.rows[request_id]+ self.rows[request_id] = {+ "request_id": request_id,+ "user_id": user_id,+ "agent_id": agent_id,+ "session_id": session_id,+ "operation": operation,+ "status": "running",+ "result": {},+ }+ return None++ async def finish_write_outcome(self, request_id, status, result):+ self.rows[request_id].update(status=status, result=dict(result))+ return True++ async def get_write_outcome(self, request_id):+ return self.rows.get(request_id)+++class RawStore:+ def __init__(self):+ self.nodes = {}+ self.upserts = 0++ async def get_by_id(self, node_id):+ return self.nodes.get(node_id)++ async def upsert(self, node):+ self.upserts += 1+ self.nodes[node.node_id] = node+ return node.node_id++ async def list_by_user(+ self,+ *,+ user_id,+ agent_id=None,+ include_sources=None,+ **_kwargs,+ ):+ return [+ node+ for node in self.nodes.values()+ if node.user_id == user_id+ and (agent_id is None or node.agent_id == agent_id)+ and (not include_sources or node.source in include_sources)+ ]+++def _client():+ client = HyMemoryClient.__new__(HyMemoryClient)+ client._cache = OutcomeCache()+ client._vector_store = RawStore()+ client._embed_service = AsyncMock()+ client._embed_service.embed.return_value = [0.1, 0.2]+ return client+++async def test_import_raw_preserves_identity_without_extraction():+ client = _client()+ result = await HyMemoryClient.async_import_raw.__wrapped__(+ client,+ "verbatim",+ user_id="u1",+ agent_id="a1",+ session_id="s1",+ source="cursor",+ raw_id="raw-1",+ request_id="request-1",+ metadata={"role": "user", "source_order": 7},+ )++ assert result == {+ "success": True,+ "raw_id": "raw-1",+ "request_id": "request-1",+ }+ node = client._vector_store.nodes["raw-1"]+ assert node.layer == MemoryLayer.L1_RAW+ assert node.content == "verbatim"+ assert node.custom["role"] == "user"+ assert node.custom["source_order"] == 7+ assert node.custom["input_kind"] == "raw_exact_import"+++async def test_import_raw_request_replay_does_not_write_twice():+ client = _client()+ first = await HyMemoryClient.async_import_raw.__wrapped__(+ client, "same", user_id="u1", raw_id="raw-1", request_id="request-1"+ )+ second = await HyMemoryClient.async_import_raw.__wrapped__(+ client, "same", user_id="u1", raw_id="raw-1", request_id="request-1"+ )++ assert second == {**first, "replayed": True}+ assert client._vector_store.upserts == 1+++async def test_existing_raw_id_must_match_exact_content_and_owner():+ client = _client()+ await HyMemoryClient.async_import_raw.__wrapped__(+ client, "first", user_id="u1", raw_id="raw-1", request_id="request-1"+ )++ with pytest.raises(ValueError, match="different source content"):+ await HyMemoryClient.async_import_raw.__wrapped__(+ client, "changed", user_id="u1", raw_id="raw-1", request_id="request-2"+ )+++async def test_raw_get_and_list_use_explicit_api():+ client = _client()+ for raw_id, session_id, source in (+ ("raw-1", "s1", "cursor"),+ ("raw-2", "s2", "claude"),+ ):+ await HyMemoryClient.async_import_raw.__wrapped__(+ client,+ raw_id,+ user_id="u1",+ session_id=session_id,+ source=source,+ raw_id=raw_id,+ request_id=f"request-{raw_id}",+ )++ item = await HyMemoryClient.async_get_raw.__wrapped__(client, "raw-1")+ assert item["raw_id"] == "raw-1"+ assert item["content"] == "raw-1"++ page = await HyMemoryClient.async_list_raw.__wrapped__(+ client,+ user_id="u1",+ source="claude",+ limit=10,+ offset=0,+ )+ assert page["total"] == 1+ assert [item["raw_id"] for item in page["raw"]] == ["raw-2"]diff --git a/tests/test_write_outcome_cache.py b/tests/test_write_outcome_cache.pynew file mode 100644index 0000000..a4656bd--- /dev/null+++ b/tests/test_write_outcome_cache.py@@ -0,0 +1,47 @@+from __future__ import annotations++import pytest++from hy_memory.config import MemoryConfig+from hy_memory.data.cache_sqlite import SqliteCache+++async def cache(tmp_path):+ config = MemoryConfig.from_dict(+ {"cache": {"backend": "sqlite", "db_path": str(tmp_path / "cache.sqlite3")}}+ )+ value = SqliteCache(config)+ await value.initialize()+ yield value+ await value.close()+++async def test_claim_is_atomic_and_returns_existing_scope(cache):+ claimed = await cache.claim_write_outcome("r1", "u1", "a1", "s1", "add")+ assert claimed is None++ existing = await cache.claim_write_outcome("r1", "u1", "a1", "s1", "add")+ assert existing["status"] == "running"+ assert existing["user_id"] == "u1"+ assert existing["operation"] == "add"+++async def test_terminal_result_round_trips(cache):+ await cache.claim_write_outcome("r2", "u1", "a1", "s1", "add_extracted")+ assert await cache.finish_write_outcome(+ "r2",+ "succeeded",+ {"success": True, "memory_ids": ["m1", "m2"]},+ )++ outcome = await cache.get_write_outcome("r2")+ assert outcome["status"] == "succeeded"+ assert outcome["result"] == {"success": True, "memory_ids": ["m1", "m2"]}+++async def test_missing_outcome_is_distinct_from_running(cache):+ assert await cache.get_write_outcome("missing") is Nonediff --git a/tests/test_write_outcome_client.py b/tests/test_write_outcome_client.pynew file mode 100644index 0000000..960f6b9--- /dev/null+++ b/tests/test_write_outcome_client.py@@ -0,0 +1,128 @@+from __future__ import annotations++from unittest.mock import AsyncMock++import pytest++from hy_memory.client import HyMemoryClient+++class OutcomeCache:+ def __init__(self):+ self.rows: dict[str, dict] = {}++ async def claim_write_outcome(+ self,+ request_id,+ user_id,+ agent_id,+ session_id,+ operation,+ ):+ existing = self.rows.get(request_id)+ if existing is not None:+ return existing+ self.rows[request_id] = {+ "request_id": request_id,+ "user_id": user_id,+ "agent_id": agent_id,+ "session_id": session_id,+ "operation": operation,+ "status": "running",+ "result": {},+ }+ return None++ async def finish_write_outcome(self, request_id, status, result):+ row = self.rows.get(request_id)+ if row is None:+ return False+ row.update(status=status, result=dict(result))+ return True++ async def get_write_outcome(self, request_id):+ return self.rows.get(request_id)+++def _client():+ client = HyMemoryClient.__new__(HyMemoryClient)+ client._cache = OutcomeCache()+ return client+++async def test_same_request_replays_terminal_result_without_writing_twice():+ client = _client()+ client._async_add_impl = AsyncMock(+ return_value={"success": True, "request_id": "r1", "memory_id": "m1"}+ )++ first = await HyMemoryClient.async_add.__wrapped__(+ client, "hello", user_id="u1", request_id="r1"+ )+ second = await HyMemoryClient.async_add.__wrapped__(+ client, "hello", user_id="u1", request_id="r1"+ )++ assert first["memory_id"] == "m1"+ assert second == {**first, "replayed": True}+ client._async_add_impl.assert_awaited_once()+++async def test_exception_marks_outcome_unknown_and_blocks_blind_retry():+ client = _client()+ client._async_add_impl = AsyncMock(side_effect=RuntimeError("after commit is unknown"))++ with pytest.raises(RuntimeError):+ await HyMemoryClient.async_add.__wrapped__(+ client, "hello", user_id="u1", request_id="r2"+ )++ replay = await HyMemoryClient.async_add.__wrapped__(+ client, "hello", user_id="u1", request_id="r2"+ )+ assert replay["success"] is False+ assert replay["outcome_status"] == "unknown"+ assert replay["error_code"] == "write_outcome_not_terminal"+ client._async_add_impl.assert_awaited_once()+++async def test_request_id_cannot_cross_write_scope():+ client = _client()+ client._async_add_impl = AsyncMock(+ return_value={"success": True, "request_id": "r3", "memory_id": "m1"}+ )+ await HyMemoryClient.async_add.__wrapped__(+ client, "hello", user_id="u1", agent_id="a1", request_id="r3"+ )++ with pytest.raises(ValueError, match="another write scope"):+ await HyMemoryClient.async_add.__wrapped__(+ client, "hello", user_id="u2", agent_id="a1", request_id="r3"+ )+++async def test_add_extracted_uses_the_same_idempotent_outcome_contract():+ client = _client()+ client._async_add_extracted_impl = AsyncMock(+ return_value={+ "success": True,+ "request_id": "r4",+ "memory_id": "m1",+ "memory_ids": ["m1"],+ }+ )++ first = await HyMemoryClient.async_add_extracted.__wrapped__(+ client, ["fact"], user_id="u1", request_id="r4"+ )+ second = await HyMemoryClient.async_add_extracted.__wrapped__(+ client, ["fact"], user_id="u1", request_id="r4"+ )++ assert first["memory_ids"] == ["m1"]+ assert second == {**first, "replayed": True}+ client._async_add_extracted_impl.assert_awaited_once()