660 lines
24 KiB
Python
660 lines
24 KiB
Python
"""
|
||
Agent Memory V2 - GraphStore 抽象基类
|
||
|
||
定义图存储层的统一接口（Provider 模式），允许切换不同的图数据库后端。
|
||
|
||
当前支持:
|
||
- Kuzu (嵌入式)
|
||
- Neo4j (客户端-服务端)
|
||
|
||
图 Schema:
|
||
节点类型:
|
||
User — 用户根节点
|
||
Memory — 记忆节点 (L6_SCHEMA / L7_INTENTION)
|
||
embedding FLOAT[dims] — 内容向量 V_con (HNSW 索引)
|
||
beh_embedding FLOAT[dims] — 行为向量 V_beh (HNSW 索引, 可 NULL)
|
||
Topic — 主题标签（LLM tags，≠ 正文 NER 实体）
|
||
Entity — 正文 NER 实体（GPE/ORG/PRODUCT…；不含 PERSON）
|
||
VdbRef — VDB 影子节点 (evidence 引用)
|
||
|
||
边类型:
|
||
HAS_MEMORY : User → Memory
|
||
TAGGED_WITH : Memory → Topic
|
||
MENTIONS : Memory → Entity
|
||
RELATED_TO : Memory ↔ Memory (双向)
|
||
DERIVED_FROM : Memory → VdbRef (evidence 关系)
|
||
CROSS_ABSTRACTS_TO : Memory → Memory (单向, L6 basic → L6 core)
|
||
"""
|
||
|
||
from abc import ABC, abstractmethod
|
||
from typing import Optional, List, Dict, Any, Sequence, Tuple
|
||
|
||
from ..models.memory import MemoryNode, MemoryLayer, MemoryStatus
|
||
from ..config import MemoryConfig
|
||
|
||
|
||
async def embed_text_for_graph(embed_service, text: str) -> Optional[List[float]]:
|
||
"""给图层用的 embedding 调用，兼容 `embed_queued` / `embed` 两种方法名。
|
||
|
||
历史上两个后端各写了一个：Kuzu 用 `embed_queued`、Neo4j 用 `embed`。真实
|
||
`EmbedService` 两个都有，所以都能跑；但任何只实现其中一个的实现（测试 fake、
|
||
精简版 embed service）会让另一个后端的 tag 归一化**静默退化成字符串精确匹配** ——
|
||
而不归一化，tag 图就会碎成一堆同义孤岛。这里统一入口，消掉这个隐患。
|
||
"""
|
||
if embed_service is None or not text:
|
||
return None
|
||
for name in ("embed_queued", "embed"):
|
||
fn = getattr(embed_service, name, None)
|
||
if fn is None:
|
||
continue
|
||
return await fn(text)
|
||
raise AttributeError(
|
||
"embed_service 需要提供 embed_queued() 或 embed() 之一"
|
||
)
|
||
|
||
|
||
def make_entity_id(isolation_key: str, label: str, name: str) -> str:
|
||
"""确定性 Entity 主键：isolation + label + casefold(name)。"""
|
||
import uuid as _uuid
|
||
norm = (name or "").strip().casefold()
|
||
lab = (label or "").strip().upper()
|
||
return (
|
||
f"ent_{_uuid.uuid5(_uuid.NAMESPACE_URL, f'{isolation_key}:{lab}:{norm}').hex[:12]}"
|
||
)
|
||
|
||
|
||
def normalize_entity_name(name: str) -> str:
|
||
return (name or "").strip().casefold()
|
||
|
||
|
||
class GraphStoreBase(ABC):
|
||
"""
|
||
图存储抽象基类
|
||
|
||
所有图数据库后端必须实现此接口。
|
||
"""
|
||
|
||
def __init__(self, config: MemoryConfig):
|
||
self.config = config
|
||
|
||
_supports_batch_topic_tags: bool = False
|
||
_supports_batch_memory_nodes: bool = False
|
||
_supports_batch_entity_mentions: bool = False
|
||
_supports_batch_related_edges: bool = False
|
||
_supports_batch_temporal_edges: bool = False
|
||
|
||
# ================================================================
|
||
# 生命周期
|
||
# ================================================================
|
||
|
||
@abstractmethod
|
||
async def initialize(self) -> None:
|
||
"""初始化图数据库连接和 Schema"""
|
||
...
|
||
|
||
@abstractmethod
|
||
async def close(self) -> None:
|
||
"""关闭连接"""
|
||
...
|
||
|
||
@abstractmethod
|
||
async def get_stats(self) -> Dict[str, Any]:
|
||
"""获取图统计信息"""
|
||
...
|
||
|
||
# ================================================================
|
||
# User 节点管理
|
||
# ================================================================
|
||
|
||
@abstractmethod
|
||
async def ensure_user_node(
|
||
self,
|
||
isolation_key: str,
|
||
user_id: str = "",
|
||
agent_id: str = "",
|
||
) -> None:
|
||
"""确保 User 节点存在"""
|
||
...
|
||
|
||
# ================================================================
|
||
# Memory 节点 CRUD
|
||
# ================================================================
|
||
|
||
@abstractmethod
|
||
async def upsert_memory_node(self, node: MemoryNode) -> str:
|
||
"""创建或更新 Memory 节点 + User→Memory 边，返回 node_id"""
|
||
...
|
||
|
||
async def upsert_memory_nodes_batch(
|
||
self, nodes: Sequence[MemoryNode],
|
||
) -> List[str]:
|
||
"""Batch-compatible Memory projection fallback.
|
||
|
||
Backends with a native bulk primitive can override this method and set
|
||
``_supports_batch_memory_nodes``. The default deliberately preserves
|
||
the old per-node failure boundary for other and third-party backends.
|
||
"""
|
||
out: List[str] = []
|
||
for node in nodes:
|
||
node_id = await self.upsert_memory_node(node)
|
||
if node_id:
|
||
out.append(node_id)
|
||
return out
|
||
|
||
@abstractmethod
|
||
async def get_node(self, node_id: str) -> Optional[MemoryNode]:
|
||
"""获取单个 Memory 节点"""
|
||
...
|
||
|
||
@abstractmethod
|
||
async def get_nodes_by_ids(self, node_ids: List[str]) -> List[MemoryNode]:
|
||
"""批量获取 Memory 节点"""
|
||
...
|
||
|
||
@abstractmethod
|
||
async def get_all_nodes(
|
||
self,
|
||
isolation_key: str,
|
||
layer: Optional[MemoryLayer] = None,
|
||
status: Optional[MemoryStatus] = None,
|
||
limit: int = 100,
|
||
) -> List[MemoryNode]:
|
||
"""按条件获取节点列表"""
|
||
...
|
||
|
||
async def get_nodes_by_user(
|
||
self,
|
||
user_id: str,
|
||
layer: Optional[MemoryLayer] = None,
|
||
status: Optional[MemoryStatus] = None,
|
||
limit: int = 100,
|
||
) -> List[MemoryNode]:
|
||
"""Return nodes across every historical agent scope for one user.
|
||
|
||
User-level profile artifacts use this to discover and retire legacy
|
||
agent-scoped catalog/supplement nodes. Third-party backends may keep the
|
||
safe empty fallback until they implement a native user_id query.
|
||
"""
|
||
return []
|
||
|
||
@abstractmethod
|
||
async def get_profile(self, isolation_key: str) -> Optional[MemoryNode]:
|
||
"""获取 L5 Identity Profile 节点"""
|
||
...
|
||
|
||
@abstractmethod
|
||
async def update_node(self, node_id: str, updates: Dict[str, Any]) -> bool:
|
||
"""更新节点属性"""
|
||
...
|
||
|
||
@abstractmethod
|
||
async def delete_node(self, node_id: str) -> bool:
|
||
"""删除 Memory 节点及其关联边"""
|
||
...
|
||
|
||
@abstractmethod
|
||
async def delete_all_nodes(self, isolation_key: str) -> int:
|
||
"""删除某隔离键下所有 Memory 节点，返回删除数量"""
|
||
...
|
||
|
||
async def clear_projection(
|
||
self,
|
||
user_id: str,
|
||
agent_id: Optional[str] = None,
|
||
*,
|
||
layer: str = "l2_fact",
|
||
) -> Dict[str, int]:
|
||
"""清掉某用户的 **pro 投影**（默认只删 `l2_fact`），供重建前使用。
|
||
|
||
为什么需要它：图是可重建的派生物，但重建**不会删旧节点**。改了投影规则之后
|
||
（例如 Topic 隔离键从 `user::agent::session` 收窄成 `user::agent`），旧的
|
||
session 粒度 Topic 仍挂着 `TAGGED_WITH` 边留在库里，`get_all_topics` 会同时
|
||
返回新旧两套，效果打折。
|
||
|
||
⚠️ 必须按 layer 收窄：一个用户的 Memory 节点里还有 System 2 / ultra 写的
|
||
`l6_schema`，无条件删会把那部分数据一起毁掉。
|
||
|
||
同时清掉因此变成孤儿的 Topic / Entity 节点（没有任何 Memory 挂着的）。
|
||
|
||
默认返回 0（未实现该能力的后端不做任何事）。
|
||
"""
|
||
return {"memories": 0, "topics": 0, "entities": 0}
|
||
|
||
@abstractmethod
|
||
async def delete_by_metadata(
|
||
self,
|
||
user_id: str,
|
||
agent_id: Optional[str] = None,
|
||
session_id: Optional[str] = None,
|
||
) -> int:
|
||
"""
|
||
按 metadata 字段组合删除 Memory 节点。
|
||
|
||
粒度:
|
||
- 仅 user_id → 删除该用户所有记忆
|
||
- user_id + agent_id → 删除该用户指定 agent 下所有记忆
|
||
- user_id + agent_id + session_id → 删除精确 session 的记忆
|
||
|
||
Returns:
|
||
删除的节点数量
|
||
"""
|
||
...
|
||
|
||
# ================================================================
|
||
# 边操作
|
||
# ================================================================
|
||
|
||
@abstractmethod
|
||
async def add_edge(
|
||
self,
|
||
source_id: str,
|
||
target_id: str,
|
||
edge_type: str,
|
||
properties: Optional[Dict[str, Any]] = None,
|
||
) -> bool:
|
||
"""添加 Memory→Memory 关系边 (RELATED_TO)"""
|
||
...
|
||
|
||
async def add_edges_batch(
|
||
self,
|
||
edges: Sequence[
|
||
Tuple[str, str, str, Optional[Dict[str, Any]]]
|
||
],
|
||
) -> List[bool]:
|
||
"""Batch-compatible fallback for Memory→Memory edges."""
|
||
return [
|
||
bool(await self.add_edge(source_id, target_id, edge_type, properties))
|
||
for source_id, target_id, edge_type, properties in edges
|
||
]
|
||
|
||
@abstractmethod
|
||
async def add_topic_tag(
|
||
self,
|
||
memory_node_id: str,
|
||
topic_name: str,
|
||
isolation_key: str,
|
||
) -> str:
|
||
"""记忆节点关联主题 (Memory→Topic)，返回 topic_id"""
|
||
...
|
||
|
||
async def add_topic_tags_batch(
|
||
self,
|
||
assignments: List[Tuple[str, str, str]],
|
||
*,
|
||
embed_service=None,
|
||
similarity_threshold: float = 0.85,
|
||
) -> List[Tuple[str, str]]:
|
||
"""Batch-compatible fallback for Memory→Topic projection.
|
||
|
||
Backends can override this to share topic lookup/embedding and reduce
|
||
storage round trips. The fallback preserves the existing semantics.
|
||
"""
|
||
out: List[Tuple[str, str]] = []
|
||
for memory_node_id, topic_name, isolation_key in assignments:
|
||
topic_id = await self.add_topic_tag(
|
||
memory_node_id,
|
||
topic_name,
|
||
isolation_key,
|
||
embed_service=embed_service,
|
||
similarity_threshold=similarity_threshold,
|
||
)
|
||
if topic_id:
|
||
out.append((memory_node_id, topic_id))
|
||
return out
|
||
|
||
async def add_topic_path(
|
||
self,
|
||
memory_node_id: str,
|
||
topic_path: List[str],
|
||
isolation_key: str,
|
||
subject: str,
|
||
*,
|
||
node_types: Optional[List[str]] = None,
|
||
role: str = "subject",
|
||
embed_service=None,
|
||
) -> List[str]:
|
||
"""Attach a memory to a typed, subject-scoped structural path.
|
||
|
||
Implementations create explicit hierarchy nodes and `SUBTOPIC_OF` edges,
|
||
then attach the memory only to the most-specific leaf. The default no-op
|
||
keeps third-party GraphStore implementations backward compatible.
|
||
"""
|
||
return []
|
||
|
||
async def clear_hierarchy_memberships(self, memory_node_id: str) -> int:
|
||
"""Remove direct `MEMBER_OF` edges before re-projecting an updated L2."""
|
||
return 0
|
||
|
||
async def prune_hierarchy_topics(self, isolation_key: str) -> int:
|
||
"""Delete empty hierarchy leaves, then empty ancestors, to convergence."""
|
||
return 0
|
||
|
||
async def get_hierarchy_topics(
|
||
self, isolation_key: str, *, subject: str = "",
|
||
) -> List[Dict[str, Any]]:
|
||
"""Return hierarchy nodes with path/depth/member-count metadata."""
|
||
return []
|
||
|
||
async def get_hierarchy_topic_memories(
|
||
self, hierarchy_topic_id: str, *, limit: int = 200,
|
||
) -> List[Dict[str, Any]]:
|
||
"""Return active canonical L2 members directly assigned to one node."""
|
||
return []
|
||
|
||
async def get_hierarchy_memberships(
|
||
self, isolation_key: str,
|
||
) -> List[Dict[str, str]]:
|
||
"""Return direct leaf memberships for one cross-session topic scope."""
|
||
return []
|
||
|
||
# ================================================================
|
||
# Entity（正文 NER）+ MENTIONS
|
||
# ================================================================
|
||
|
||
async def add_entity_mention(
|
||
self,
|
||
memory_node_id: str,
|
||
name: str,
|
||
label: str,
|
||
isolation_key: str,
|
||
) -> str:
|
||
"""Memory -[:MENTIONS]-> Entity。返回 entity_id；失败返回空串。
|
||
|
||
Entity ≠ Topic：Topic 来自 LLM tags；Entity 来自正文 spaCy NER。
|
||
默认 no-op（未实现的后端不影响主路径）。
|
||
"""
|
||
return ""
|
||
|
||
async def replace_entity_mentions_batch(
|
||
self,
|
||
assignments: Sequence[
|
||
Tuple[str, Sequence[Tuple[str, str]], str]
|
||
],
|
||
) -> List[Tuple[str, str]]:
|
||
"""Replace MENTIONS edges for several memories.
|
||
|
||
Each item is ``(memory_node_id, [(name, label), ...], isolation_key)``.
|
||
Empty entity lists still clear stale mentions, matching update-time
|
||
projection semantics. The default is the original clear-then-add
|
||
sequence so non-batch backends retain their existing behavior.
|
||
"""
|
||
out: List[Tuple[str, str]] = []
|
||
for memory_node_id, entities, isolation_key in assignments:
|
||
await self.clear_entity_mentions(memory_node_id)
|
||
for name, label in entities:
|
||
entity_id = await self.add_entity_mention(
|
||
memory_node_id, name, label, isolation_key,
|
||
)
|
||
if entity_id:
|
||
out.append((memory_node_id, entity_id))
|
||
return out
|
||
|
||
async def clear_entity_mentions(self, memory_node_id: str) -> int:
|
||
"""删掉某 Memory 的全部 MENTIONS 边（UPDATE 投影前重建用）。返回删边数。"""
|
||
return 0
|
||
|
||
async def find_memories_by_entities(
|
||
self,
|
||
isolation_key: str,
|
||
entities: Sequence[Tuple[str, str]],
|
||
limit: int = 100,
|
||
) -> List[Dict[str, Any]]:
|
||
"""按实体名（casefold）反查挂 MENTIONS 的 active Memory。
|
||
|
||
entities: [(name, label), ...]；label 仅作同组过滤提示（可空）。
|
||
返回 [{node_id, entity_name, entity_label, match_score}]，match_score∈(0,1]。
|
||
"""
|
||
return []
|
||
|
||
# ================================================================
|
||
# Topic 检索 (Tag 收敛 + Tag 桥接召回)
|
||
# ================================================================
|
||
|
||
async def get_all_topics(
|
||
self,
|
||
isolation_key: str,
|
||
) -> List[Dict[str, Any]]:
|
||
"""获取某 isolation_key 下的所有 Topic 节点
|
||
|
||
返回 [{topic_id, name, embedding, degree}]：
|
||
- `embedding` 可能为 None（旧数据 / 写入时未传 embed_service）
|
||
- `degree` = 挂在该 Topic 上的 active 记忆数，画像聚合用
|
||
（Topic 度数 + 新鲜度排序 ≈ "用户是什么样的人"，零 LLM 成本）
|
||
|
||
两个后端必须返回同样的键，否则依赖 `degree` 的能力会在某个后端上静默失效。
|
||
"""
|
||
return [] # 默认 no-op，子类覆盖
|
||
|
||
async def tag_bridge_search(
|
||
self,
|
||
topic_ids: List[str],
|
||
limit: int = 20,
|
||
) -> List[Dict[str, Any]]:
|
||
"""Tag 桥接召回：从 Topic 节点反向查找关联的 Memory 节点
|
||
|
||
即 MATCH (t:Topic)<-[:TAGGED_WITH]-(m:Memory) WHERE m.status = 'active'
|
||
返回 [{node_id, content, layer, confidence, topic_name, custom_json}]
|
||
"""
|
||
return [] # 默认 no-op，子类覆盖
|
||
|
||
# ================================================================
|
||
# V3: VdbRef (shadow node) + DERIVED_FROM edge
|
||
# ================================================================
|
||
|
||
async def ensure_vdbref(self, node_id: str, layer: str) -> None:
|
||
"""确保 VdbRef 影子节点存在（不存在则创建，已存在则跳过）"""
|
||
... # 默认 no-op，子类覆盖
|
||
|
||
async def add_derived_from(self, memory_node_id: str, vdbref_node_id: str) -> bool:
|
||
"""添加 DERIVED_FROM 边: Memory → VdbRef (evidence 关系)"""
|
||
return False # 默认 no-op
|
||
|
||
async def find_referencing_memories(
|
||
self,
|
||
vdb_node_ids: List[str],
|
||
limit: int = 50,
|
||
include_sources: Optional[List[str]] = None,
|
||
exclude_sources: Optional[List[str]] = None,
|
||
) -> List[Dict[str, Any]]:
|
||
"""反向查找: 给定 VDB node_id 列表，找到 Graph 中引用它们的 Memory 节点
|
||
|
||
即 MATCH (v:VdbRef)<-[:DERIVED_FROM]-(m:Memory)
|
||
返回 [{node_id, content, layer, confidence, evidence_vdb_id}]
|
||
"""
|
||
return [] # 默认 no-op
|
||
|
||
|
||
async def get_evidence_vdbrefs(self, memory_node_id: str) -> List[Dict[str, Any]]:
|
||
"""获取一个 Graph Memory 节点的所有 DERIVED_FROM evidence VdbRef
|
||
|
||
返回 [{node_id, layer}]
|
||
"""
|
||
return [] # 默认 no-op
|
||
|
||
# ================================================================
|
||
# 图检索
|
||
# ================================================================
|
||
|
||
@abstractmethod
|
||
async def expand_from_anchors(
|
||
self,
|
||
anchor_ids: List[str],
|
||
hop: int = 1,
|
||
max_nodes: int = 50,
|
||
) -> List[Dict[str, Any]]:
|
||
"""从锚点节点出发，沿图边扩展 N 跳"""
|
||
...
|
||
|
||
async def get_topic_memories(
|
||
self, topic_id: str, *, limit: int = 200,
|
||
) -> List[Dict[str, Any]]:
|
||
"""列出某个 Topic 下的 active 记忆，按 memory_at 正序。
|
||
|
||
给 Topic-scoped summary 和时序脊用。
|
||
刻意不复用 `tag_bridge_search` —— 那条是 legacy reader 的召回通道，
|
||
而 tag 共属已决定不作为遍历边（τ=0，见 docs/pro_graph_design.md §3.0）。
|
||
|
||
⚠️ **图里没有事件时间**：Kuzu 的 `Memory` 表只有 `created_at`（落库时间），
|
||
没有 `memory_at`，而新增列对已有 DB 不生效。所以时间一律以 VDB 为准 ——
|
||
调用方拿到 node_id 后回 VDB 取 `memory_at` 再排序
|
||
（见 `pipelines/_graph/projector.resolve_memory_times`）。
|
||
|
||
Returns:
|
||
[{"node_id", "content"}, ...]，按 created_at 正序
|
||
"""
|
||
return [] # 默认 no-op，子类覆盖
|
||
|
||
async def add_temporal_edge(
|
||
self, prev_id: str, next_id: str, topic_id: str = "",
|
||
) -> bool:
|
||
"""建一条时序脊边（TEMPORAL_NEXT，**有向**：prev → next）。
|
||
|
||
`topic_id` 为空串表示**全局脊**（跨话题，按事件时间连相邻两条）；
|
||
非空表示 Topic 内脊。两者共存：Topic 内脊表达"这个主题怎么演变"，
|
||
全局脊表达"那几天前后发生了什么"。
|
||
|
||
⚠️ 时间关系刻意**不建成"同天两两相连"的团**：一天 20 条记忆就是 190 条边、
|
||
度数 19，一跳把当天全拉进来、两跳把三天全拉进来 —— 和 tag hub 淹没结果同类。
|
||
全局脊每条只连时间最近的前一条，度数恒为 2，同天记忆仍可达但候选量由跳数预算控制。
|
||
|
||
与 `supersedes` 的区别：`supersedes` 表达矛盾取代（旧的不再成立），
|
||
`TEMPORAL_NEXT` 表达递进（旧的仍然成立，只是更早）。
|
||
"""
|
||
return False # 默认 no-op，子类覆盖
|
||
|
||
async def add_temporal_edges_batch(
|
||
self, edges: Sequence[Tuple[str, str, str]],
|
||
) -> List[bool]:
|
||
"""Batch-compatible fallback for directed TEMPORAL_NEXT edges."""
|
||
return [
|
||
bool(await self.add_temporal_edge(prev_id, next_id, topic_id))
|
||
for prev_id, next_id, topic_id in edges
|
||
]
|
||
|
||
async def get_related_edges(
|
||
self,
|
||
node_ids: List[str],
|
||
*,
|
||
max_edges: int = 2000,
|
||
relation_types: Optional[List[str]] = None,
|
||
include_temporal: bool = True,
|
||
include_sources: Optional[List[str]] = None,
|
||
exclude_sources: Optional[List[str]] = None,
|
||
) -> List[Dict[str, Any]]:
|
||
"""取出所有一端落在 node_ids 里的 RELATED_TO 边（无向，去重后每对只返回一次）。
|
||
|
||
这是读侧图重排的**唯一图查询原语**，一次查询同时服务三种用法：
|
||
- 用法 A（池内支持度传播）：过滤出两端都在召回池里的边
|
||
- 用法 B（阈值松弛）：取另一端不在池里的边 → 候选
|
||
- 用法 C（关系路径）：用同一批边在 Python 侧建邻接、找 ≤2 跳路径
|
||
|
||
返回里带上 target 的 status / layer，省掉一次回查：读侧必须能过滤
|
||
SHADOW（判重逻辑删除）节点，否则被删掉的记忆会从图里绕回来。
|
||
|
||
`include_temporal=True` 时把 TEMPORAL_NEXT 也一起返回，
|
||
`relation_type="temporal_next"` + `directed=True`（方向为 source→target，
|
||
即"更早 → 更晚"）。A/B 把它当普通边用（按 τ 先验加权），C 用它的方向。
|
||
|
||
Returns:
|
||
[{"source_id", "target_id", "relation_type", "weight",
|
||
"target_status", "target_layer", "directed"}, ...]
|
||
"""
|
||
return [] # 默认 no-op，子类覆盖
|
||
|
||
async def expand_with_tags(
|
||
self,
|
||
anchor_ids: List[str],
|
||
hop: int = 2,
|
||
max_nodes: int = 500,
|
||
isolation_key: str = "",
|
||
) -> List[Dict[str, Any]]:
|
||
"""从锚点出发，沿 RELATED_TO + TAGGED_WITH(双向) 展开 N 跳。
|
||
|
||
路径包括:
|
||
- Memory -[RELATED_TO]- Memory（双向）
|
||
- Memory -[TAGGED_WITH]-> Topic <-[TAGGED_WITH]- Memory（经 Topic 桥接）
|
||
|
||
isolation_key 非空时只展开属于同一 isolation_key 的节点。
|
||
|
||
返回 [{node_id, content, layer, confidence, hop, source}]
|
||
"""
|
||
return [] # 默认 no-op，子类覆盖
|
||
|
||
# ================================================================
|
||
# 向量检索 (Graph HNSW)
|
||
# ================================================================
|
||
|
||
async def vector_search(
|
||
self,
|
||
query_embedding: List[float],
|
||
isolation_key: str,
|
||
layers: Optional[List[str]] = None,
|
||
limit: int = 10,
|
||
score_threshold: float = 0.0,
|
||
user_id: str = "",
|
||
include_sources: Optional[List[str]] = None,
|
||
exclude_sources: Optional[List[str]] = None,
|
||
) -> List[Dict[str, Any]]:
|
||
"""V_con 向量检索 Graph Memory 节点
|
||
|
||
使用 embedding 列的 HNSW 索引做 ANN 检索。
|
||
|
||
当 isolation_key 为空但 user_id 非空时，执行跨 agent 搜索
|
||
（匹配 isolation_key 以 user_id + "::" 为前缀的所有节点）。
|
||
|
||
返回 [{node_id, content, layer, confidence, score}]
|
||
"""
|
||
return [] # 默认 no-op，子类覆盖
|
||
|
||
async def beh_vector_search(
|
||
self,
|
||
query_beh_embedding: List[float],
|
||
isolation_key: str,
|
||
limit: int = 10,
|
||
) -> List[Dict[str, Any]]:
|
||
"""V_beh 向量检索 L6 basic 节点 (sweeper 用)
|
||
|
||
使用 beh_embedding 列的 HNSW 索引做 ANN 检索。
|
||
返回 [{node_id, content, embedding, beh_distance}]
|
||
"""
|
||
return [] # 默认 no-op，子类覆盖
|
||
|
||
async def update_embedding(
|
||
self,
|
||
node_id: str,
|
||
embedding: Optional[List[float]] = None,
|
||
beh_embedding: Optional[List[float]] = None,
|
||
) -> bool:
|
||
"""更新节点的 embedding / beh_embedding 向量属性"""
|
||
return False # 默认 no-op
|
||
|
||
# ================================================================
|
||
# 跨域归纳 (Cross-Domain Schema Induction)
|
||
# ================================================================
|
||
|
||
async def add_cross_abstracts_to(
|
||
self,
|
||
basic_id: str,
|
||
core_id: str,
|
||
) -> bool:
|
||
"""添加 CROSS_ABSTRACTS_TO 边: L6 basic → L6 core (单向)"""
|
||
return False # 默认 no-op
|
||
|
||
async def find_cores_from_basics(
|
||
self,
|
||
basic_ids: List[str],
|
||
max_hops: int = 2,
|
||
) -> List[Dict[str, Any]]:
|
||
"""从 L6 basic 出发，沿 RELATED_TO / CROSS_ABSTRACTS_TO 找 L6 core 节点
|
||
|
||
返回 [{node_id, content, confidence}]，已去重
|
||
"""
|
||
return [] # 默认 no-op
|
||
|
||
async def get_cross_abstracts_targets(
|
||
self,
|
||
basic_id: str,
|
||
) -> List[str]:
|
||
"""查询某个 L6 basic 已有的 CROSS_ABSTRACTS_TO 边指向的 core node_id 列表"""
|
||
return [] # 默认 no-op
|