Skip to content
Python

feat(sdk): add MemHub authority migration contracts (#129)

feitianxiangfd12c8f1c0f0
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 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` or
diff --git a/hy_memory/__init__.py b/hy_memory/__init__.py
index 7408dd3..e8944a7 100644
--- a/hy_memory/__init__.py
+++ b/hy_memory/__init__.py
@@ -55,6 +55,13 @@ except Exception:
from .client import HyMemoryClient
from .inspector import MemoryInspector
from .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.py
index 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 True
try:
gs = self._graph_store
# Kuzu backend
if hasattr(gs, '_execute') and hasattr(gs, '_available'):
if not gs._available:
- return
+ return False
gs._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 True
except 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_loop
async 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_loop
async 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_loop
async 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,
+ }
+
@staticmethod
def _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 = False
if node is not None:
@@ -4085,19 +4461,27 @@ class HyMemoryClient:
# 删除图数据库节点 + 清理 evidence(如有)
graph_deleted = False
+ graph_cleanup_ok = True
if 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
+
@staticmethod
def _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, MemoryStatus
from .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, MemoryStatus
graph_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 empty
try:
await self._get_coding_writer() # 副作用:lazy init store
except 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_loop
async 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.py
index 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.py
index 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.py
index 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.py
new file mode 100644
index 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.py
index 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 SqliteCache
STATEFUL_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.py
new file mode 100644
index 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.py
new file mode 100644
index 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.py
index 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 random
n = 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.py
new file mode 100644
index 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.py
new file mode 100644
index 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 None
diff --git a/tests/test_write_outcome_client.py b/tests/test_write_outcome_client.py
new file mode 100644
index 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()