Python
"""记忆关系图(pro 模式)测试。
覆盖三层:
1. 读侧数学:用法 A 传播 / 用法 B 阈值松弛 / 用法 C 路径(纯函数,无 I/O)
2. 写侧建边:projector 的四种边来源 + 同步契约
3. Kuzu 端到端:投影 → get_related_edges → Topic 归一化
设计文档:docs/pro_graph_design.md
"""
from typing import Any, Dict
import pytest
from unittest.mock import AsyncMock
from hy_memory.pipelines._graph.rerank import (
TYPE_PRIOR,
build_adjacency,
collect_directed_edges,
edge_prior,
find_relation_paths,
propagate_support,
relax_admission,
)
from hy_memory.pipelines._graph.rerank import (
apply_temporal_affinity,
apply_type_quota,
edge_group,
normalize_by_degree,
reachable_within,
)
from hy_memory.pipelines._graph.topic_summary import (
SUMMARY_KIND_TOPIC,
covered_count_of,
maybe_summarize_topics,
)
from hy_memory.pipelines._graph.projector import (
LLM_RELATION_TYPES,
RELATION_CO_OCCURS,
RELATION_SEMANTIC_NEIGHBOR,
project_memories_to_graph,
sync_graph_on_shadow,
sync_graph_on_supersede,
)
from hy_memory.models.memory import MemoryLayer, MemoryNode, MemoryStatus
def _edge(src, tgt, rtype="causes", weight=1.0, status="active", directed=False):
return {
"source_id": src, "target_id": tgt, "relation_type": rtype,
"weight": weight, "target_status": status, "target_layer": "l2_fact",
"directed": directed,
}
# ================================================================
# 邻接表 / 类型先验
# ================================================================
class TestAdjacency:
def test_edges_are_undirected(self):
adj = build_adjacency([_edge("a", "b")])
assert [n for n, _t, _w in adj["a"]] == ["b"]
assert [n for n, _t, _w in adj["b"]] == ["a"]
def test_effective_weight_is_weight_times_prior(self):
adj = build_adjacency([_edge("a", "b", "causes", weight=0.5)])
_nb, _rt, eff = adj["a"][0]
assert eff == pytest.approx(0.5 * TYPE_PRIOR["causes"])
def test_shadow_targets_are_dropped(self):
"""被判重逻辑删除的记忆不能从图里绕回来。"""
adj = build_adjacency([_edge("a", "b", status="shadow")])
assert adj == {}
def test_self_loops_and_incomplete_edges_ignored(self):
assert build_adjacency([_edge("a", "a")]) == {}
assert build_adjacency([{"source_id": "a"}]) == {}
def test_parallel_edges_collapse_to_strongest(self):
"""同一对节点的多种关系折叠成一条,取先验最高的那种。
度数要数"不同邻居"而不是"平行边数",否则 hub 降权会被平行边稀释、
支持度会重复计。
"""
adj = build_adjacency([
_edge("a", "b", "semantic_neighbor", weight=1.0),
_edge("a", "b", "causes", weight=1.0),
])
assert len(adj["a"]) == 1
nb, rtype, eff = adj["a"][0]
assert nb == "b" and rtype == "causes"
assert eff == pytest.approx(TYPE_PRIOR["causes"])
def test_unknown_relation_gets_default_prior(self):
assert edge_prior("no_such_relation") == 0.5
assert edge_prior(None) == 0.5
def test_semantic_neighbor_prior_is_lowest(self):
"""semantic_neighbor 与向量检索高度冗余,先验必须最低。"""
assert TYPE_PRIOR["semantic_neighbor"] < TYPE_PRIOR["co_occurs"]
assert TYPE_PRIOR["co_occurs"] < TYPE_PRIOR["causes"]
# ================================================================
# 用法 A:池内支持度传播
# ================================================================
class TestPropagateSupport:
def test_linked_pair_both_rise_above_unlinked(self):
"""文档 §3.1 的例子:互相佐证的一对应该浮到无边候选之上。"""
scores = {"m2": 0.55, "m7": 0.53, "m3": 0.52, "m8": 0.51}
adj = build_adjacency([_edge("m2", "m3", "causes")])
out, support = propagate_support(scores, adj, beta=0.15)
assert out["m2"] > out["m3"] > out["m7"] > out["m8"]
assert out["m7"] == 0.53 and out["m8"] == 0.51 # 无边支持 → 分数不变
assert support["m2"] > 0 and support["m7"] == 0
def test_does_not_introduce_new_candidates(self):
"""A 的核心保证:召回集合不变,recall 恒定。"""
scores = {"a": 0.6, "b": 0.5}
adj = build_adjacency([_edge("a", "outside")])
out, _ = propagate_support(scores, adj, beta=0.15)
assert set(out) == {"a", "b"}
def test_only_propagates_within_pool(self):
"""池外的强节点不该给池内节点加分。"""
adj = build_adjacency([_edge("a", "outside", weight=1.0)])
out, support = propagate_support({"a": 0.5, "b": 0.4}, adj, beta=0.15)
assert out["a"] == 0.5
assert support["a"] == 0.0
def test_hub_penalty_via_degree_normalization(self):
"""度数归一化:高度数节点单条边的贡献被摊薄(tag hub 问题的解药)。"""
scores = {"hub": 0.5, "x1": 0.5, "x2": 0.5, "x3": 0.5, "x4": 0.5,
"lo": 0.5, "y1": 0.5}
hub_adj = build_adjacency([
_edge("hub", f"x{i}", "co_occurs") for i in range(1, 5)
])
lo_adj = build_adjacency([_edge("lo", "y1", "co_occurs")])
_o1, sup_hub = propagate_support(scores, hub_adj, beta=0.15)
_o2, sup_lo = propagate_support(scores, lo_adj, beta=0.15)
# 4 条边 / sqrt(4) = 2× 单边;而不是 4× —— 归一化生效
assert sup_hub["hub"] == pytest.approx(sup_lo["lo"] * 2.0)
def test_beta_zero_is_noop(self):
scores = {"a": 0.6, "b": 0.5}
adj = build_adjacency([_edge("a", "b")])
out, _ = propagate_support(scores, adj, beta=0.0)
assert out == scores
def test_support_cap_bounds_the_nudge(self):
scores = {"a": 0.5, "b": 1.0, "c": 1.0, "d": 1.0}
adj = build_adjacency([
_edge("a", "b"), _edge("a", "c"), _edge("a", "d"),
])
capped, _ = propagate_support(scores, adj, beta=0.2, support_cap=0.1)
assert capped["a"] == pytest.approx(0.5 + 0.2 * 0.1)
def test_empty_inputs(self):
assert propagate_support({}, {}, beta=0.1) == ({}, {})
# ================================================================
# 用法 B:阈值松弛
# ================================================================
class TestRelaxAdmission:
def test_hard_gate_admits_near_seed_sim(self):
"""硬闸:sim ≥ seed_sim − δ。seed=0.72 → 门槛 0.52。"""
adj = build_adjacency([_edge("knee", "running", "causes", weight=1.0)])
out = relax_admission(
seed_scores={"knee": 0.72},
adjacency=adj,
candidate_sims={"running": 0.55},
min_score=0.4, gamma=0.3, seed_floor=0.6, seed_sim_delta=0.2,
)
assert len(out) == 1
assert out[0]["node_id"] == "running"
assert out[0]["threshold"] == pytest.approx(0.52)
assert out[0]["sim"] == 0.55
def test_hard_gate_rejects_far_below_seed(self):
"""旧 gamma 路径会捞回 0.35;硬闸 δ=0.2 时相对 seed=0.72 进不来。"""
adj = build_adjacency([_edge("knee", "running", "causes", weight=1.0)])
out = relax_admission(
seed_scores={"knee": 0.72},
adjacency=adj,
candidate_sims={"running": 0.35},
min_score=0.4, gamma=0.3, seed_floor=0.6, seed_sim_delta=0.2,
)
assert out == []
def test_hard_gate_rejects_junk(self):
adj = build_adjacency([_edge("seed", "junk", "causes", weight=1.0)])
out = relax_admission(
seed_scores={"seed": 1.0}, adjacency=adj,
candidate_sims={"junk": 0.10},
min_score=0.4, gamma=0.3, seed_floor=0.6, seed_sim_delta=0.2,
)
assert out == []
def test_weak_seed_does_not_expand(self):
adj = build_adjacency([_edge("weak", "cand", "causes")])
out = relax_admission(
seed_scores={"weak": 0.3}, adjacency=adj,
candidate_sims={"cand": 0.39},
min_score=0.4, gamma=0.3, seed_floor=0.6, seed_sim_delta=0.2,
)
assert out == []
def test_pool_members_are_not_readmitted(self):
adj = build_adjacency([_edge("a", "b", "causes")])
out = relax_admission(
seed_scores={"a": 0.9, "b": 0.5}, adjacency=adj,
candidate_sims={"b": 0.5}, min_score=0.4, gamma=0.3,
seed_sim_delta=0.2,
)
assert out == []
def test_gamma_zero_disables_use_b(self):
adj = build_adjacency([_edge("a", "c", "causes")])
assert relax_admission(
seed_scores={"a": 0.9}, adjacency=adj,
candidate_sims={"c": 0.75}, min_score=0.4, gamma=0.0,
seed_sim_delta=0.2,
) == []
def test_max_admit_caps_output(self):
adj = build_adjacency([
_edge("seed", f"c{i}", "causes") for i in range(10)
])
out = relax_admission(
seed_scores={"seed": 1.0}, adjacency=adj,
candidate_sims={f"c{i}": 0.85 for i in range(10)},
min_score=0.4, gamma=0.3, max_admit=3, seed_sim_delta=0.2,
)
assert len(out) == 3
def test_strongest_supporting_seed_wins(self):
adj = build_adjacency([
_edge("s1", "c", "semantic_neighbor", weight=1.0),
_edge("s2", "c", "causes", weight=1.0),
])
out = relax_admission(
seed_scores={"s1": 0.9, "s2": 0.9}, adjacency=adj,
candidate_sims={"c": 0.75}, min_score=0.4, gamma=0.3,
seed_sim_delta=0.2,
)
assert out[0]["relation_type"] == "causes" # 先验更高
def test_channel_score_prefers_tag_over_co_occur(self):
adj = build_adjacency([_edge("s", "c", "co_occurs")])
out = relax_admission(
seed_scores={"s": 0.8}, adjacency=adj,
candidate_sims={"c": 0.65},
gamma=0.3, seed_floor=0.5, seed_sim_delta=0.2,
candidate_bm25={"c": 0.0},
candidate_tag={"c": 1.0},
candidate_temporal={"c": 1.0},
channel_weights={
"sem": 1.0, "bm25": 0.3, "tag": 0.5,
"temporal": 0.2, "co_occur": 0.15, "struct": 0.25,
},
)
assert len(out) == 1
# sem*0.65 + tag*0.5*1 + temporal*0.2 + co_occur*0.15*support
assert out[0]["score"] > out[0]["sim"]
assert out[0]["tag_overlap"] == 1.0
class TestMergeExpansionsIntoSeeds:
def test_merges_by_time_with_blank_line(self):
from datetime import datetime, timezone
from hy_memory.pipelines._graph.rerank import merge_expansions_into_seeds
from hy_memory.models.memory import MemoryNode, MemoryLayer
def _node(nid, text, ts):
return MemoryNode(
node_id=nid, user_id="u", agent_id="a",
layer=MemoryLayer.L2_FACT, content=text,
memory_at=datetime.fromtimestamp(ts, tz=timezone.utc),
)
seed = {
"node_id": "s1", "score": 0.8,
"node": _node("s1", "seed later", 200),
}
exp = {
"node_id": "e1", "score": 0.7, "graph_via": "s1",
"node": _node("e1", "exp earlier", 100),
}
out = merge_expansions_into_seeds([seed], [exp])
assert len(out) == 1
assert out[0]["content"] == "exp earlier\n\nseed later"
assert out[0]["graph_merged_ids"] == ["e1"]
assert out[0]["score"] == 0.8
# ================================================================
# 用法 C:关系路径
# ================================================================
class TestFindRelationPaths:
def test_one_hop_path_between_two_anchors(self):
adj = build_adjacency([_edge("a", "b", "causes")])
paths = find_relation_paths(
hit_scores={"a": 0.8, "b": 0.7}, adjacency=adj, high_floor=0.6,
)
assert len(paths) == 1
assert paths[0]["hops"] == 1
assert set(paths[0]["nodes"]) == {"a", "b"}
def test_two_hop_path_carries_low_scoring_middle_node(self):
"""中间节点自己分数很低也要带上 —— 它是路径的一部分。"""
adj = build_adjacency([
_edge("ramen", "dana_rec", "elaborates"),
_edge("dana_rec", "dana_chef", "co_occurs"),
])
paths = find_relation_paths(
hit_scores={"ramen": 0.85, "dana_chef": 0.65}, adjacency=adj,
high_floor=0.6,
)
assert len(paths) == 1
assert paths[0]["hops"] == 2
assert paths[0]["nodes"][1] == "dana_rec" # 中间节点不在 hit_scores 里
def test_low_scoring_anchors_are_skipped(self):
adj = build_adjacency([_edge("a", "b", "causes")])
assert find_relation_paths(
hit_scores={"a": 0.5, "b": 0.4}, adjacency=adj, high_floor=0.6,
) == []
def test_semantic_neighbor_excluded_by_default(self):
"""两条语义相近的记忆之间连一条路径对答案没有解释价值。"""
adj = build_adjacency([_edge("a", "b", "semantic_neighbor")])
assert find_relation_paths(
hit_scores={"a": 0.8, "b": 0.8}, adjacency=adj,
) == []
assert len(find_relation_paths(
hit_scores={"a": 0.8, "b": 0.8}, adjacency=adj, typed_only=False,
)) == 1
def test_needs_two_anchors(self):
adj = build_adjacency([_edge("a", "b", "causes")])
assert find_relation_paths(hit_scores={"a": 0.9}, adjacency=adj) == []
def test_duplicate_paths_deduped(self):
adj = build_adjacency([_edge("a", "b", "causes")])
paths = find_relation_paths(hit_scores={"a": 0.9, "b": 0.9}, adjacency=adj)
assert len(paths) == 1
def test_relations_are_dicts_with_type(self):
adj = build_adjacency([_edge("a", "b", "causes")])
paths = find_relation_paths(hit_scores={"a": 0.9, "b": 0.9}, adjacency=adj)
assert paths[0]["relations"][0]["type"] == "causes"
assert "direction" not in paths[0]["relations"][0] # 无向边不标方向
def test_temporal_direction_is_labelled(self):
"""有向边要标方向,否则"X 之后"和"X 之前"在输出里分不开。"""
edges = [_edge("early", "late", "temporal_next", directed=True)]
adj = build_adjacency(edges)
fwd = collect_directed_edges(edges)
paths = find_relation_paths(
hit_scores={"early": 0.9, "late": 0.8}, adjacency=adj, forward_dirs=fwd,
)
# 同一 anchor 对去重后只产出一条路径;方向随路径起点而定
assert len(paths) == 1
nodes, rel = paths[0]["nodes"], paths[0]["relations"][0]
assert rel["type"] == "temporal_next"
expected = "forward" if nodes == ["early", "late"] else "backward"
assert rel["direction"] == expected
class TestCollectDirectedEdges:
def test_only_directed_edges_collected(self):
out = collect_directed_edges([
_edge("a", "b", "causes", directed=False),
_edge("x", "y", "temporal_next", directed=True),
])
assert out == {("x", "y")}
def test_type_prior_ordering(self):
"""先验排序按"能否提供向量检索拿不到的信息"来定。
`co_occurs` 排在很高位:共同写入是**跨话题联系的主要来源**
("去公园/骑车/吃饭"一起写下来,三者向量互不相似但关联真实)。
它的噪声由写侧的批大小归一化 + 读侧的度数归一化控制,而不是靠压低先验 ——
压低先验会连带把"一批只有 2 条"这种几乎必然相关的情况也一起贬值。
"""
p = TYPE_PRIOR
assert p["causes"] > p["same_series"] > p["contrasts"]
assert p["contrasts"] == p["temporal_next"] > p["co_occurs"]
assert p["co_occurs"] > p["semantic_neighbor"]
# ================================================================
# 写侧:projector
# ================================================================
class _FakeGraphStore:
def __init__(self, topic_memories=None, topics=None):
self.nodes = []
self.edges = []
self.tags = []
self.updates = {}
self.temporal = []
self._topic_memories = topic_memories or {}
self._topics = topics or []
async def upsert_memory_node(self, node):
self.nodes.append(node)
return node.node_id
async def add_topic_tag(self, node_id, topic, isolation_key, embed_service=None,
similarity_threshold=0.85):
self.tags.append((node_id, topic, isolation_key, embed_service is not None))
return f"topic_{topic}"
async def add_edge(self, src, tgt, edge_type, properties=None):
self.edges.append((src, tgt, (properties or {}).get("relation_type"),
(properties or {}).get("weight")))
return True
async def update_node(self, node_id, updates):
self.updates[node_id] = updates
return True
async def add_temporal_edge(self, prev_id, next_id, topic_id=""):
self.temporal.append((prev_id, next_id, topic_id))
return True
async def get_topic_memories(self, topic_id, *, limit=200):
return self._topic_memories.get(topic_id, [])
async def get_all_topics(self, isolation_key):
return self._topics
def _node(nid, content="c", tags=None):
return MemoryNode(
node_id=nid, user_id="u1", agent_id="a1", session_id="s1",
layer=MemoryLayer.L2_FACT, content=content, tags=list(tags or []),
)
@pytest.mark.asyncio
class TestProjector:
async def test_native_graph_batches_cover_nodes_entities_and_edges(
self, monkeypatch,
):
from datetime import datetime
import hy_memory.pipelines._retrieval.ner as ner
monkeypatch.setattr(
ner, "extract_entities",
lambda _text, for_boost=True: [
("Paris", "GPE"), ("Paris", "GPE"), ("OpenAI", "ORG"),
],
)
class BatchGraph(_FakeGraphStore):
_supports_batch_memory_nodes = True
_supports_batch_entity_mentions = True
_supports_batch_related_edges = True
_supports_batch_temporal_edges = True
def __init__(self):
super().__init__()
self.memory_batches = []
self.entity_batches = []
self.edge_batches = []
self.temporal_batches = []
async def upsert_memory_node(self, _node):
raise AssertionError("per-node path must not be used")
async def upsert_memory_nodes_batch(self, nodes):
self.memory_batches.append(list(nodes))
return [node.node_id for node in nodes]
async def clear_entity_mentions(self, _node_id):
raise AssertionError("per-memory entity clear must not be used")
async def add_entity_mention(self, *_args, **_kwargs):
raise AssertionError("per-entity path must not be used")
async def replace_entity_mentions_batch(self, assignments):
self.entity_batches.append(list(assignments))
return [
(memory_id, f"entity-{name}-{label}")
for memory_id, entities, _scope in assignments
for name, label in entities
]
async def add_edge(self, *_args, **_kwargs):
raise AssertionError("per-edge path must not be used")
async def add_edges_batch(self, edges):
self.edge_batches.append(list(edges))
return [True] * len(edges)
async def add_temporal_edge(self, *_args, **_kwargs):
raise AssertionError("per-temporal-edge path must not be used")
async def add_temporal_edges_batch(self, edges):
self.temporal_batches.append(list(edges))
return [True] * len(edges)
n1 = _node("n1", "first", tags=["work"])
n2 = _node("n2", "second", tags=["work"])
n1.memory_at = datetime(2026, 1, 1)
n2.memory_at = datetime(2026, 2, 1)
gs = BatchGraph()
stats = await project_memories_to_graph(
graph_store=gs,
embed_service=None,
nodes=[n1, n2],
neighbors_by_node={"n1": [("old-sem", 0.8)]},
related_by_node={
"n2": [{"target_id": "old-cause", "relation_type": "causes"}],
},
temporal_spine_bulk=True,
)
assert len(gs.memory_batches) == 1
assert len(gs.entity_batches) == 1
assert len(gs.edge_batches) == 1
assert len(gs.edge_batches[0]) == 3
assert gs.temporal_batches == [[("n1", "n2", "topic_work")]]
assert stats == {
"nodes": 2, "tags": 2, "entities": 4,
"co_occurs": 1, "semantic": 1, "typed": 1, "temporal": 1,
"errors": 0, "hierarchy_paths": 0, "hierarchy_nodes": 0,
}
async def test_batch_failure_falls_back_to_per_item(self):
class FailingBatchGraph(_FakeGraphStore):
_supports_batch_memory_nodes = True
_supports_batch_related_edges = True
async def upsert_memory_nodes_batch(self, _nodes):
raise RuntimeError("transient node batch failure")
async def add_edges_batch(self, _edges):
raise RuntimeError("transient edge batch failure")
gs = FailingBatchGraph()
stats = await project_memories_to_graph(
graph_store=gs, embed_service=None,
nodes=[_node("n1"), _node("n2")],
)
assert [node.node_id for node in gs.nodes] == ["n1", "n2"]
assert len(gs.edges) == 1
assert stats["nodes"] == 2
assert stats["co_occurs"] == 1
assert stats["errors"] == 0
async def test_batch_topic_capability_avoids_per_tag_calls(self):
class BatchGraph(_FakeGraphStore):
_supports_batch_topic_tags = True
def __init__(self):
super().__init__()
self.batch_assignments = []
async def add_topic_tag(self, *args, **kwargs):
raise AssertionError("per-tag path must not be used")
async def add_topic_tags_batch(self, assignments, **kwargs):
self.batch_assignments = list(assignments)
return [
(memory_id, f"topic-{tag}")
for memory_id, tag, _scope in assignments
]
gs = BatchGraph()
node = _node("n1", tags=["work", "travel"])
stats = await project_memories_to_graph(
graph_store=gs,
embed_service=None,
nodes=[node],
)
assert len(gs.batch_assignments) == 2
assert stats["tags"] == 2
async def test_projects_nodes_and_tags(self):
gs = _FakeGraphStore()
stats = await project_memories_to_graph(
graph_store=gs, embed_service=object(),
nodes=[_node("n1", tags=["work", "health"])],
)
assert stats["nodes"] == 1 and stats["tags"] == 2
# embed_service 必须透传下去,否则 Topic 不做语义归一化
assert all(has_embed for *_x, has_embed in gs.tags)
async def test_co_occurs_pairwise_within_batch(self):
gs = _FakeGraphStore()
stats = await project_memories_to_graph(
graph_store=gs, embed_service=None,
nodes=[_node("n1"), _node("n2"), _node("n3")],
)
assert stats["co_occurs"] == 3 # C(3,2)
assert all(rt == RELATION_CO_OCCURS for _s, _t, rt, _w in gs.edges)
async def test_co_occurs_skipped_for_oversized_batch(self):
gs = _FakeGraphStore()
stats = await project_memories_to_graph(
graph_store=gs, embed_service=None,
nodes=[_node(f"n{i}") for i in range(5)],
co_occurs_max_batch=3,
)
assert stats["co_occurs"] == 0
async def test_semantic_neighbor_respects_threshold(self):
gs = _FakeGraphStore()
stats = await project_memories_to_graph(
graph_store=gs, embed_service=None, nodes=[_node("n1")],
neighbors_by_node={"n1": [("old1", 0.80), ("old2", 0.40)]},
edge_min_score=0.55,
)
assert stats["semantic"] == 1
assert ("n1", "old1", RELATION_SEMANTIC_NEIGHBOR, 0.80) in gs.edges
async def test_typed_relations_whitelisted(self):
gs = _FakeGraphStore()
stats = await project_memories_to_graph(
graph_store=gs, embed_service=None, nodes=[_node("n1")],
related_by_node={"n1": [
{"target_id": "old1", "relation_type": "causes"},
{"target_id": "old2", "relation_type": "made_up_relation"},
]},
)
assert stats["typed"] == 1
assert ("n1", "old1", "causes", 1.0) in gs.edges
async def test_no_graph_store_is_noop(self):
stats = await project_memories_to_graph(
graph_store=None, embed_service=None, nodes=[_node("n1")],
)
assert stats["nodes"] == 0
async def test_sync_contract(self):
gs = _FakeGraphStore()
assert await sync_graph_on_supersede(gs, ["old1"]) == 1
assert gs.updates["old1"]["status"] == "superseded"
assert await sync_graph_on_shadow(gs, ["dup1"]) == 1
assert gs.updates["dup1"]["status"] == "shadow"
async def test_llm_relation_vocabulary_is_small(self):
"""弱模型 + 大本体 = 垃圾;same_event 已按冗余删除。"""
assert LLM_RELATION_TYPES == (
"causes", "elaborates", "contrasts", "same_series",
)
@staticmethod
def _spine_setup(member_times):
"""图给同 Topic 成员,VDB 给事件时间 —— 图里没有 memory_at。"""
from datetime import datetime
gs = _FakeGraphStore(topic_memories={
"topic_work": [{"node_id": mid, "content": "c"} for mid in member_times]
})
class _VS:
async def get_by_ids(self, ids):
out = []
for mid in ids:
if mid not in member_times:
continue
n = _node(mid)
n.memory_at = datetime.fromtimestamp(member_times[mid])
out.append(n)
return out
return gs, _VS()
async def test_temporal_spine_picks_nearest_earlier_member(self):
from datetime import datetime
target_ts = datetime(2026, 5, 1).timestamp()
gs, vs = self._spine_setup({
"too_old": datetime(2020, 1, 1).timestamp(),
"nearest": datetime(2026, 4, 1).timestamp(), # 应选它
"later": datetime(2026, 9, 1).timestamp(), # 比新节点还晚,不能选
})
node = _node("new1", tags=["work"])
node.memory_at = datetime.fromtimestamp(target_ts)
stats = await project_memories_to_graph(
graph_store=gs, embed_service=None, nodes=[node],
vector_store=vs, temporal_spine=True,
)
assert stats["temporal"] == 1
assert gs.temporal == [("nearest", "new1", "topic_work")]
async def test_temporal_spine_no_earlier_member(self):
from datetime import datetime
gs, vs = self._spine_setup({
"later": datetime(2026, 9, 1).timestamp(),
})
node = _node("new1", tags=["work"])
node.memory_at = datetime(2026, 5, 1)
stats = await project_memories_to_graph(
graph_store=gs, embed_service=None, nodes=[node],
vector_store=vs, temporal_spine=True,
)
assert stats["temporal"] == 0 and gs.temporal == []
async def test_temporal_spine_off_by_default(self):
from datetime import datetime
gs, vs = self._spine_setup({"older": datetime(2020, 1, 1).timestamp()})
node = _node("new1", tags=["work"])
node.memory_at = datetime(2026, 5, 1)
stats = await project_memories_to_graph(
graph_store=gs, embed_service=None, nodes=[node], vector_store=vs,
)
assert stats["temporal"] == 0 and gs.temporal == []
async def test_temporal_spine_needs_topic_and_memory_at(self):
gs, vs = self._spine_setup({"older": 1.0})
# 无 tag → 无 Topic → 无从串脊
stats = await project_memories_to_graph(
graph_store=gs, embed_service=None, nodes=[_node("n1")],
vector_store=vs, temporal_spine=True,
)
assert stats["temporal"] == 0
async def test_bulk_spine_chains_whole_batch_in_time_order(self):
"""回填用的 bulk 版:整批按 Topic 分组、按事件时间逐对相连。"""
from datetime import datetime
gs = _FakeGraphStore()
nodes = []
# 故意乱序传入,验证是按 memory_at 排序而不是按入参顺序
for nid, month in (("b", 5), ("c", 9), ("a", 1)):
n = _node(nid, tags=["work"])
n.memory_at = datetime(2026, month, 1)
nodes.append(n)
stats = await project_memories_to_graph(
graph_store=gs, embed_service=None, nodes=nodes,
temporal_spine_bulk=True,
)
assert stats["temporal"] == 2
assert gs.temporal == [
("a", "b", "topic_work"), ("b", "c", "topic_work"),
]
async def test_incremental_spine_would_build_nothing_for_backfill(self):
"""回填若误用增量版,会因"排除批内节点"而一条边都建不出来。
这正是 bulk 版存在的理由 —— 两者的前驱来源不同。
"""
from datetime import datetime
gs = _FakeGraphStore(topic_memories={"topic_work": []})
nodes = []
for nid, month in (("a", 1), ("b", 5)):
n = _node(nid, tags=["work"])
n.memory_at = datetime(2026, month, 1)
nodes.append(n)
class _VS:
async def get_by_ids(self, ids):
return []
stats = await project_memories_to_graph(
graph_store=gs, embed_service=None, nodes=nodes,
vector_store=_VS(), temporal_spine=True,
)
assert stats["temporal"] == 0 and gs.temporal == []
# ================================================================
# Topic-scoped summary
# ================================================================
class _FakeVectorStore:
def __init__(self, l3_nodes=None):
self._l3 = l3_nodes or []
self.upserted = []
self.payload_updates = {}
async def list_by_user(self, **kw):
return list(self._l3)
async def get_by_ids(self, ids):
wanted = set(ids)
return [node for node in self._l3 if node.node_id in wanted]
async def upsert(self, node):
self.upserted.append(node)
return node.node_id
async def update_payload(self, node_id, updates):
self.payload_updates[node_id] = updates
return True
class _FakeEmbedService:
async def embed_queued(self, text):
return [0.1, 0.2, 0.3]
class _FakeLLM:
def __init__(self, text="The user works as a nurse in Berlin on night shifts."):
self.text = text
self.calls = []
async def complete(self, prompt, max_tokens=500, temperature=0.7, **kw):
self.calls.append(prompt)
class _R:
content = self.text
return _R()
def _l3(node_id, topic_id, covered):
from datetime import datetime
return MemoryNode(
node_id=node_id, user_id="u1", agent_id="a1", session_id="s1",
layer=MemoryLayer.L3_SUMMARY, content="old summary",
gmt_created=datetime(2026, 1, 1),
custom={
"summary_kind": SUMMARY_KIND_TOPIC,
"topic_id": topic_id, "covered_count": covered,
},
)
@pytest.mark.asyncio
class TestTopicSummary:
async def _run(self, *, mems, l3=None, min_memories=5, step=5, llm=None):
gs = _FakeGraphStore(
topic_memories={"t_work": mems},
topics=[{"topic_id": "t_work", "name": "work"}],
)
vs = _FakeVectorStore(l3_nodes=l3 or [])
llm = llm or _FakeLLM()
stats = await maybe_summarize_topics(
graph_store=gs, vector_store=vs, embed_service=_FakeEmbedService(),
llm_provider=llm, user_id="u1", agent_id="a1", session_id="s1",
isolation_key="u1::a1", touched_topic_ids=["t_work"],
min_memories=min_memories, step=step,
)
return stats, vs, llm
@staticmethod
def _mems(n):
return [{"node_id": f"m{i}", "content": f"fact {i}"} for i in range(n)]
async def test_summarizes_when_threshold_reached(self):
stats, vs, llm = await self._run(mems=self._mems(5))
assert stats["summarized"] == 1
node = vs.upserted[0]
assert node.layer == MemoryLayer.L3_SUMMARY
assert node.custom["summary_kind"] == SUMMARY_KIND_TOPIC
assert node.custom["topic_id"] == "t_work"
assert node.custom["covered_count"] == 5
assert len(node.custom["source_memory_ids"]) == 5
assert len(llm.calls) == 1
async def test_skips_below_min_memories(self):
stats, vs, _ = await self._run(mems=self._mems(3))
assert stats["summarized"] == 0 and stats["skipped"] == 1
assert vs.upserted == []
async def test_skips_when_increment_below_step(self):
"""已总结过 5 条,现在 7 条 → 增量 2 < step 5,不重算(省 LLM)。"""
stats, vs, llm = await self._run(
mems=self._mems(7), l3=[_l3("s1", "t_work", 5)],
)
assert stats["summarized"] == 0 and stats["skipped"] == 1
assert llm.calls == []
async def test_resummarizes_and_shadows_previous(self):
prev = _l3("s1", "t_work", 5)
stats, vs, _ = await self._run(mems=self._mems(10), l3=[prev])
assert stats["summarized"] == 1
# 旧摘要置 SHADOW,避免同一 Topic 多条摘要重复召回
assert vs.payload_updates["s1"]["status"] == MemoryStatus.SHADOW.value
assert vs.upserted[0].custom["supersedes_summary_id"] == "s1"
async def test_other_topics_summary_not_confused(self):
"""别的 Topic 的摘要不能被当成本 Topic 的上一版。"""
stats, vs, llm = await self._run(
mems=self._mems(6), l3=[_l3("s_other", "t_food", 100)],
)
assert stats["summarized"] == 1
assert vs.upserted[0].custom["covered_count"] == 6
async def test_strips_code_fence_from_llm_output(self):
stats, vs, _ = await self._run(
mems=self._mems(5), llm=_FakeLLM('```\nThe user is a nurse.\n```'),
)
assert vs.upserted[0].content == "The user is a nurse."
async def test_empty_llm_output_counts_as_error(self):
stats, vs, _ = await self._run(mems=self._mems(5), llm=_FakeLLM(" "))
assert stats["summarized"] == 0 and stats["errors"] == 1
assert vs.upserted == []
async def test_no_llm_provider_is_noop(self):
gs = _FakeGraphStore(topic_memories={"t": self._mems(10)})
stats = await maybe_summarize_topics(
graph_store=gs, vector_store=_FakeVectorStore(),
embed_service=_FakeEmbedService(), llm_provider=None,
user_id="u1", agent_id="a1", session_id="s1",
isolation_key="u1::a1", touched_topic_ids=["t"],
)
assert stats["summarized"] == 0
async def test_covered_count_handles_json_custom(self):
node = _l3("s1", "t", 7)
node.custom = '{"summary_kind": "topic", "topic_id": "t", "covered_count": 7}'
assert covered_count_of(node) == 7
assert covered_count_of(_node("x")) == 0
# ================================================================
# 架构不变量:light search / heavy write
# ================================================================
class TestReadPathHasNoLLM:
"""**检索链路不得有 LLM 调用** —— 架构约定是 light search / heavy write。
推理放在写入侧(reconcile 标 typed 边、Topic 摘要),读侧只做确定性的图遍历
和范围过滤。曾经在 reader 里加过 LLM 驱动的"推理多跳",已移除:
跨话题时序问题改用「派生时间锚点 + 二次纯向量检索」(用法 D),零 LLM。
这条不变量必须由**结构**保证而不是靠开关 —— 靠 flag 守着的话,
一旦全局 env 被打开,所有 search(含延迟敏感的 chat 路径)都会多一次 LLM。
"""
@pytest.mark.parametrize("mod_name", [
"reader", "reader_base", "reader_legacy", "reader_hybrid",
])
def test_readers_do_not_import_or_call_llm(self, mod_name):
import importlib
import inspect
mod = importlib.import_module(f"hy_memory.pipelines.{mod_name}")
src = inspect.getsource(mod)
for banned in ("LLMProvider", "llm_provider", "complete_messages"):
assert banned not in src, (
f"{mod_name} 出现 {banned!r} —— 检索链路不得引入 LLM"
)
def test_graph_read_helpers_are_llm_free(self):
import inspect
import hy_memory.pipelines._graph.rerank as rr
for mod in (rr,):
src = inspect.getsource(mod)
for banned in ("LLMProvider", "llm_provider", ".complete("):
assert banned not in src, f"{mod.__name__} 不得调用 LLM"
def test_multihop_module_is_gone(self):
"""LLM 驱动的推理多跳已从 SDK 移除,不留死代码。"""
with pytest.raises(ModuleNotFoundError):
import hy_memory.pipelines._graph.multihop # noqa: F401
# ================================================================
# 扩展候选的筛选漏斗
# ================================================================
#
# 扩展会带进很多新候选,筛选靠一个漏斗而不是一道关。顺序决定成本:
# 算候选与 query 的相似度是唯一有 I/O 的一步,必须先用免费的图信号砍到几十条。
class TestNormalizeByDegree:
"""度数归一化 —— 时间边能安全参与扩展的前提。"""
def test_high_degree_neighbor_edges_are_devalued(self):
# hub 有 4 个邻居,lonely 只有 1 个
adj = build_adjacency([
_edge("s", "hub", "co_occurs"), _edge("hub", "x1", "co_occurs"),
_edge("hub", "x2", "co_occurs"), _edge("hub", "x3", "co_occurs"),
_edge("s2", "lonely", "co_occurs"),
])
norm = normalize_by_degree(adj)
w_hub = next(w for nb, _t, w in norm["s"] if nb == "hub")
w_lonely = next(w for nb, _t, w in norm["s2"] if nb == "lonely")
assert w_hub < w_lonely, "高连接节点的每条边都该贬值"
def test_empty(self):
assert normalize_by_degree({}) == {}
class TestApplyTemporalAffinity:
"""时间维度:与锚点写入时间越近,联系越可能真实。"""
def test_closer_in_time_keeps_more_support(self):
day = 86400.0
reach = {"near": (1.0, "seed", "co_occurs", 1),
"far": (1.0, "seed", "co_occurs", 1)}
times = {"seed": 0.0, "near": day, "far": 90 * day}
out = apply_temporal_affinity(reach, times=times, tau_days=7.0, floor=0.3)
assert out["near"][0] > out["far"][0]
def test_same_write_point_keeps_full_support(self):
"""同批次写入(Δt≈0)→ 因子 = 1,这正是"公园/骑车/吃饭"那个场景。"""
reach = {"park": (0.8, "meal", "co_occurs", 1)}
out = apply_temporal_affinity(
reach, times={"meal": 1000.0, "park": 1000.0}, tau_days=7.0,
)
assert out["park"][0] == pytest.approx(0.8)
def test_floor_prevents_time_from_erasing_strong_relations(self):
"""时间远但关系强(如 LLM 标的 causes)的边不该被时间抹平。"""
reach = {"c": (1.0, "s", "causes", 1)}
out = apply_temporal_affinity(
reach, times={"s": 0.0, "c": 3650 * 86400.0}, tau_days=7.0, floor=0.3,
)
assert out["c"][0] == pytest.approx(0.3)
def test_missing_times_are_not_penalized(self):
reach = {"c": (0.7, "s", "causes", 1)}
out = apply_temporal_affinity(reach, times={"s": 0.0}, tau_days=7.0)
assert out["c"][0] == pytest.approx(0.7)
class TestApplyTypeQuota:
"""类型配额 —— 防止数量最多、信息量最低的时间边挤掉关系边。"""
def test_relational_survives_flood_of_temporal(self):
reach = {f"t{i}": (0.9, "s", "temporal_next", 1) for i in range(100)}
reach["rel"] = (0.1, "s", "causes", 1) # 分数最低,但类型信息量最高
out = apply_type_quota(reach, top_n=10)
assert "rel" in out, "关系边不该被时间边淹没"
assert len(out) <= 12 # 配额取整可能略超,但量级受控
def test_edge_group_mapping(self):
assert edge_group("causes") == "relational"
assert edge_group("co_occurs") == "relational"
assert edge_group("temporal_next") == "temporal"
assert edge_group("semantic_neighbor") == "semantic"
def test_empty_and_zero_budget(self):
assert apply_type_quota({}, top_n=10) == {}
assert apply_type_quota({"a": (1.0, "s", "causes", 1)}, top_n=0) == {}
class TestMultiSeedCorroboration:
"""多 seed 佐证:两个不同 seed 同时指向同一候选,才是真正的佐证。"""
def test_two_seeds_beat_one(self):
"""query 同时命中「吃饭」「骑车」,两者都指向「公园」→ 公园显著上浮。"""
adj = build_adjacency([
_edge("meal", "park", "co_occurs"),
_edge("bike", "park", "co_occurs"),
_edge("meal", "solo", "co_occurs"),
])
got = reachable_within(
{"meal": 0.8, "bike": 0.8}, adj, hops=1, seed_floor=0.6,
multi_seed_bonus=0.5,
)
assert got["park"][0] > got["solo"][0], "被两个 seed 指向的候选该更高"
def test_bonus_zero_falls_back_to_max_path(self):
adj = build_adjacency([
_edge("s1", "c", "co_occurs"), _edge("s2", "c", "co_occurs"),
])
got = reachable_within(
{"s1": 0.8, "s2": 0.8}, adj, hops=1, seed_floor=0.6,
multi_seed_bonus=0.0,
)
one = reachable_within({"s1": 0.8}, adj, hops=1, seed_floor=0.6)
assert got["c"][0] == pytest.approx(one["c"][0])
class TestExpandScoring:
"""打分:硬闸后多通道 / 或退回 sim + 有界结构加权。"""
def test_structural_boost_without_channels(self):
adj = build_adjacency([_edge("s", "c", "causes")])
out = relax_admission(
seed_scores={"s": 0.9}, adjacency=adj,
candidate_sims={"c": 0.75}, min_score=0.4, gamma=0.3,
boost_beta=0.1, boost_cap=1.0, seed_sim_delta=0.2,
)
assert len(out) == 1
o = out[0]
assert o["sim"] == 0.75
assert o["score"] > o["sim"]
assert o["score"] <= o["sim"] + 0.1
def test_beta_zero_keeps_pure_similarity_without_channels(self):
adj = build_adjacency([_edge("s", "c", "causes")])
out = relax_admission(
seed_scores={"s": 0.9}, adjacency=adj,
candidate_sims={"c": 0.75}, min_score=0.4, gamma=0.3,
boost_beta=0.0, seed_sim_delta=0.2,
)
assert out[0]["score"] == pytest.approx(0.75)
def test_graph_still_cannot_invent_relevance(self):
"""无论结构支持多强,远低于 seed_sim−δ 就进不来。"""
adj = build_adjacency([_edge("s", "junk", "causes")])
out = relax_admission(
seed_scores={"s": 1.0}, adjacency=adj,
candidate_sims={"junk": 0.05}, min_score=0.4, gamma=0.3,
boost_beta=0.5, seed_sim_delta=0.2,
)
assert out == []
class TestReachableWithin:
"""关系型结构多跳:k 跳可达 + 衰减 + 预算。"""
def test_one_hop(self):
adj = build_adjacency([_edge("s", "a", "causes")])
got = reachable_within({"s": 0.9}, adj, hops=1, seed_floor=0.6)
assert set(got) == {"a"} and got["a"][3] == 1
def test_two_hops_reaches_through_middle_node(self):
""""朋友推荐的餐厅"这类问题两端常隔一个中间节点 —— 1 跳到不了。"""
adj = build_adjacency([
_edge("s", "mid", "co_occurs"), _edge("mid", "far", "co_occurs"),
])
one = reachable_within({"s": 0.9}, adj, hops=1, seed_floor=0.6)
two = reachable_within({"s": 0.9}, adj, hops=2, seed_floor=0.6)
assert "far" not in one
assert "far" in two and two["far"][3] == 2
def test_support_decays_with_hops(self):
adj = build_adjacency([
_edge("s", "mid", "co_occurs"), _edge("mid", "far", "co_occurs"),
])
got = reachable_within({"s": 0.9}, adj, hops=2, seed_floor=0.6, hop_decay=0.5)
assert got["far"][0] < got["mid"][0], "越远支持度必须越低"
def test_pool_members_excluded(self):
adj = build_adjacency([_edge("s", "inpool", "causes")])
got = reachable_within({"s": 0.9, "inpool": 0.5}, adj, hops=2, seed_floor=0.6)
assert "inpool" not in got
def test_weak_seeds_do_not_expand(self):
adj = build_adjacency([_edge("s", "a", "causes")])
assert reachable_within({"s": 0.3}, adj, hops=2, seed_floor=0.6) == {}
def test_first_edge_relation_is_reported(self):
adj = build_adjacency([
_edge("s", "mid", "causes"), _edge("mid", "far", "co_occurs"),
])
got = reachable_within({"s": 0.9}, adj, hops=2, seed_floor=0.6)
assert got["far"][2] == "causes", "应报首跳关系,便于解释路径来源"
class TestRelaxAdmissionMultiHop:
def test_two_hop_candidate_can_be_admitted(self):
adj = build_adjacency([
_edge("seed", "mid", "causes"), _edge("mid", "far", "causes"),
])
out = relax_admission(
seed_scores={"seed": 0.9}, adjacency=adj,
candidate_sims={"mid": 0.75, "far": 0.75},
min_score=0.4, gamma=0.3, seed_floor=0.6, hops=2,
seed_sim_delta=0.2,
)
got = {o["node_id"]: o["hop"] for o in out}
assert got.get("mid") == 1
assert "far" in got and got["far"] == 2
def test_hops_one_keeps_old_behavior(self):
adj = build_adjacency([
_edge("seed", "mid", "causes"), _edge("mid", "far", "causes"),
])
out = relax_admission(
seed_scores={"seed": 0.9}, adjacency=adj,
candidate_sims={"mid": 0.75, "far": 0.75},
min_score=0.4, gamma=0.3, seed_floor=0.6, hops=1,
seed_sim_delta=0.2,
)
got = {o["node_id"] for o in out}
assert "mid" in got and "far" not in got
assert [o["node_id"] for o in out] == ["mid"]
# ================================================================
# Cypher 静态守卫(Neo4j 路 CI 里跑不到,只能静态兜)
# ================================================================
class TestNeo4jCypherGuards:
@pytest.mark.asyncio
async def test_native_clone_snapshot_import_batches_and_remaps_scope(self):
from datetime import datetime
from hy_memory.data.graph_store_neo4j import Neo4jGraphStore
gs = Neo4jGraphStore.__new__(Neo4jGraphStore)
source = _node("old", "source", tags=["work"])
source.user_id = "src"
source.session_id = "session"
source.memory_at = datetime(2026, 1, 1)
source._graph_embedding = [1.0, 0.0]
gs._record_to_memory_node = lambda record: source
memory_batches = []
edge_batches = []
temporal_batches = []
entity_batches = []
writes = []
async def memory_batch(nodes):
memory_batches.append(list(nodes))
return [node.node_id for node in nodes]
async def edge_batch(edges):
edge_batches.append(list(edges))
return [True] * len(edges)
async def temporal_batch(edges):
temporal_batches.append(list(edges))
return [True] * len(edges)
async def entity_batch(assignments):
entity_batches.append(list(assignments))
return []
async def capture(query, params=None):
writes.append((query, params or {}))
gs.upsert_memory_nodes_batch = memory_batch
gs.add_edges_batch = edge_batch
gs.add_temporal_edges_batch = temporal_batch
gs.replace_entity_mentions_batch = entity_batch
gs._run_write = capture
gs.add_topic_path = AsyncMock(return_value=[])
snapshot = {
"user_id": "src",
"nodes": [{"m": {"node_id": "old"}, "embedding": [1.0, 0.0], "beh_embedding": None}],
"evidence": [{"source_id": "old", "target_id": "v1", "layer": "l1_raw"}],
"related": [
{"source_id": "old", "target_id": "old", "relation_type": "causes", "weight": 0.7},
],
"temporal": [{"source_id": "old", "target_id": "old", "topic_id": "old-topic"}],
"cross": [{"source_id": "old", "target_id": "old"}],
"tags": [{
"source_id": "old", "topic_id": "old-topic", "name": "work",
"embedding": [0.5, 0.5], "isolation_key": "src::a",
}],
"entities": [{
"source_id": "old", "name": "Paris", "label": "GPE",
"isolation_key": "src::a",
}],
}
id_map = {"old": "new"}
count = await gs.import_clone_snapshot(
snapshot, dst_user_id="dst", id_map=id_map, embed_service=None,
)
assert count == 1
assert memory_batches[0][0].node_id == "new"
assert memory_batches[0][0].user_id == "dst"
assert memory_batches[0][0]._graph_embedding == [1.0, 0.0]
assert edge_batches and edge_batches[0][0][0:2] == ("new", "new")
expected_topic = Neo4jGraphStore._clone_scope("src::a", "src", "dst")
assert expected_topic == "dst::a"
tag_write = next(params for query, params in writes if "TAGGED_WITH" in query)
new_topic_id = tag_write["rows"][0]["tid"]
assert tag_write["rows"][0]["ik"] == "dst::a"
assert temporal_batches == [[("new", "new", new_topic_id)]]
assert entity_batches[0][0][0] == "new"
assert entity_batches[0][0][2] == "dst::a"
@pytest.mark.asyncio
async def test_native_batch_primitives_each_use_one_round_trip(self):
from datetime import datetime
from hy_memory.data.graph_store_neo4j import Neo4jGraphStore
gs = Neo4jGraphStore.__new__(Neo4jGraphStore)
writes = []
async def capture(query, params=None):
writes.append((query, params or {}))
gs._run_write = capture
node = _node("batch-node", "latest", tags=["work"])
node.memory_at = datetime(2026, 1, 1)
assert await gs.upsert_memory_nodes_batch([node]) == ["batch-node"]
assert len(writes) == 1
assert "UNWIND $rows" in writes[-1][0]
assert "MERGE (u:User" in writes[-1][0]
assert "MERGE (u)-[:HAS_MEMORY]->(m)" in writes[-1][0]
assert "WHEN row.emb IS NULL THEN m.embedding" in writes[-1][0]
assert writes[-1][1]["rows"][0]["content"] == "latest"
mentions = await gs.replace_entity_mentions_batch([
("batch-node", [("Paris", "gpe"), ("OpenAI", "ORG")], "u::a"),
])
assert len(writes) == 2
assert len(mentions) == 2
assert "DELETE old" in writes[-1][0]
assert "MERGE (e:Entity" in writes[-1][0]
assert "MERGE (m)-[:MENTIONS]->(e)" in writes[-1][0]
assert writes[-1][1]["rows"][0]["entities"][0]["lab"] == "GPE"
related = await gs.add_edges_batch([
("batch-node", "other", "RELATED_TO", {
"relation_type": "causes", "weight": 0.7,
}),
])
assert related == [True]
assert len(writes) == 3
assert writes[-1][0].count("MERGE") == 2
assert "CASE WHEN row.w > r1.weight" in writes[-1][0]
assert writes[-1][1]["rows"][0]["rtype"] == "causes"
temporal = await gs.add_temporal_edges_batch([
("batch-node", "later", "topic_work"),
])
assert temporal == [True]
assert len(writes) == 4
assert "MERGE (a)-[r:TEMPORAL_NEXT]->(b)" in writes[-1][0]
assert writes[-1][1]["rows"][0]["tid"] == "topic_work"
"""起因是一个真实 bug:`get_topic_memories` 写成
RETURN DISTINCT m.node_id AS node_id, m.content AS content
ORDER BY m.created_at
Neo4j 在 `DISTINCT` 之后只认投影里的变量,`m.created_at` 未投影 → SyntaxError。
而该方法的异常是 `logger.debug` 吞掉 + `return []`,**表面无声**:
`MEMORY_TOPIC_SUMMARY_ENABLED=true` 时永远拿不到成员记忆,摘要一条都不生成。
CI 里没有 Neo4j 实例(端到端测试跑的是 Kuzu),所以只能静态兜住这一类问题。
"""
def test_order_by_after_distinct_uses_projected_alias(self):
import inspect
import re
import hy_memory.data.graph_store_neo4j as m
src = inspect.getsource(m)
offenders = []
for match in re.finditer(r"RETURN\s+DISTINCT\b", src):
tail = src[match.end(): match.end() + 800]
ob = re.search(r"\bORDER\s+BY\s+([^\n]+)", tail)
if not ob:
continue
expr = ob.group(1).strip().rstrip(",")
# DISTINCT 之后只能按别名排序;出现 `var.prop` 就是本 bug
if re.search(r"\b\w+\.\w+", expr):
offenders.append(expr)
assert not offenders, (
"RETURN DISTINCT 之后的 ORDER BY 必须用投影别名,不能用 var.property: "
f"{offenders}"
)
def test_topic_memories_projects_its_sort_key(self):
import inspect
import hy_memory.data.graph_store_neo4j as m
src = inspect.getsource(m.Neo4jGraphStore.get_topic_memories)
assert "m.created_at AS created_at" in src, "排序键必须投影出来"
assert "ORDER BY created_at" in src, "ORDER BY 必须用别名"
def test_both_backends_return_same_topic_memory_shape(self):
"""两个后端 get_topic_memories 的返回形状要一致(只 node_id / content)。"""
import inspect
import hy_memory.data.graph_store_kuzu as k
import hy_memory.data.graph_store_neo4j as n
for mod, cls in ((k, "KuzuGraphStore"), (n, "Neo4jGraphStore")):
src = inspect.getsource(getattr(mod, cls).get_topic_memories)
assert '"node_id"' in src and '"content"' in src, cls
# created_at 只用于排序,不该进返回体
assert '"created_at":' not in src, f"{cls} 不该把 created_at 放进返回体"
# ================================================================
# 端到端:Kuzu + Neo4j 两个后端都跑
# ================================================================
#
# Neo4j 路此前零覆盖,直接导致 dev6 那个 bug 漏出去:
# `get_topic_memories` 的 `RETURN DISTINCT ... ORDER BY m.created_at` 在 Neo4j 上是
# SyntaxError,而异常被 logger.debug 吞掉 + return [],表面无声。
# Kuzu 版语法合法,所以单跑 Kuzu 永远测不出来 —— 两个后端必须都跑。
#
# Neo4j 连接信息从 env 取,取不到就 skip(CI 无实例时不阻塞):
# HY_TEST_NEO4J_URL / HY_TEST_NEO4J_USER / HY_TEST_NEO4J_PASSWORD
_BACKENDS = ["kuzu", "neo4j"]
def _neo4j_conn():
import os
return (
os.getenv("HY_TEST_NEO4J_URL", ""),
os.getenv("HY_TEST_NEO4J_USER", "neo4j"),
os.getenv("HY_TEST_NEO4J_PASSWORD", ""),
)
async def _make_graph_store(backend: str, tmp_path, suffix: str):
"""按 backend 建一个干净的 GraphStore;不可用则 pytest.skip。"""
from hy_memory.config import MemoryConfig, GraphStoreConfig
cfg = MemoryConfig()
if backend == "kuzu":
from hy_memory.data.graph_store_kuzu import KuzuGraphStore
cfg.graph_store = GraphStoreConfig(
provider="kuzu", db_path=str(tmp_path / f"kuzu_{suffix}"),
)
gs = KuzuGraphStore(cfg)
await gs.initialize()
if not getattr(gs, "_available", False):
pytest.skip("Kuzu unavailable in this environment")
return gs
url, user, pwd = _neo4j_conn()
if not url or not pwd:
pytest.skip(
"Neo4j 未配置:设 HY_TEST_NEO4J_URL / HY_TEST_NEO4J_PASSWORD 后才跑"
)
from hy_memory.data.graph_store_neo4j import Neo4jGraphStore
cfg.graph_store = GraphStoreConfig(
provider="neo4j", url=url, username=user, password=pwd, database="neo4j",
)
gs = Neo4jGraphStore(cfg)
try:
await gs.initialize()
except Exception as e:
pytest.skip(f"Neo4j unreachable: {e}")
# Community edition 只有一个 database,测试间必须自己清干净,否则互相污染
await _wipe_neo4j(gs)
return gs
async def _wipe_neo4j(gs) -> None:
for label in ("Memory", "Topic", "Entity", "VdbRef", "User"):
try:
await gs._run_write(f"MATCH (n:{label}) DETACH DELETE n")
except Exception:
pass
@pytest.mark.asyncio
@pytest.mark.parametrize("backend", _BACKENDS)
@pytest.mark.parametrize("with_embed", [True, False], ids=["normalized", "fallback"])
async def test_tagged_with_edge_created_in_both_paths(backend, with_embed, tmp_path):
"""`add_topic_tag` 的两条路径都必须真的建出 Memory→Topic 边。
回归一个真实 bug:Neo4j 的 fallback 分支(不传 embed_service,或归一化抛异常时)
给 `_run_write` 多传了一个 params dict → TypeError 被 `except` 静默吞掉,
**TAGGED_WITH 边从来没建出来**。后果是 tag 全变成孤立 Topic:
`get_topic_memories` 返回空 → Topic 摘要不触发、时序脊找不到同 Topic 成员。
单跑归一化路径测不出来(那条分支自己会建边),所以两条路径都要覆盖。
"""
gs = await _make_graph_store(backend, tmp_path, f"tagpath_{int(with_embed)}")
class _Embed:
async def embed_queued(self, text):
return [1.0, 0.0, 0.0]
async def embed(self, text): # 真实 EmbedService 两个都有
return [1.0, 0.0, 0.0]
try:
node = _node("tp1", "some fact", tags=["work"])
await gs.upsert_memory_node(node)
tid = await gs.add_topic_tag(
"tp1", "work", node.get_isolation_key(),
embed_service=_Embed() if with_embed else None,
)
assert tid, "add_topic_tag 应返回 topic_id"
mems = await gs.get_topic_memories(tid)
assert [m["node_id"] for m in mems] == ["tp1"], (
f"{backend}/{'normalized' if with_embed else 'fallback'} 路径没建出 "
f"TAGGED_WITH 边 —— Topic 成了孤岛"
)
finally:
await gs.close()
@pytest.mark.asyncio
@pytest.mark.parametrize("backend", _BACKENDS)
async def test_graph_end_to_end(backend, tmp_path):
"""投影 → get_related_edges → Topic 归一化,走真实图库。"""
gs = await _make_graph_store(backend, tmp_path, "db")
class _Embed:
"""fake 必须同时提供 embed_queued / embed —— 真实 EmbedService 两个都有。
只实现一个会让某个后端的 tag 归一化静默退化成字符串精确匹配。"""
_TABLE = {
# work / job 近似同义 → 应被归一化成同一个 Topic
"work": [1.0, 0.0, 0.0], "job": [0.99, 0.14, 0.0],
"food": [0.0, 1.0, 0.0],
}
async def embed_queued(self, text):
return self._TABLE.get(text, [0.0, 0.0, 1.0])
async def embed(self, text):
return self._TABLE.get(text, [0.0, 0.0, 1.0])
try:
n1 = _node("g1", "started running daily", tags=["fitness"])
n2 = _node("g2", "knee started hurting", tags=["health"])
stats = await project_memories_to_graph(
graph_store=gs, embed_service=_Embed(), nodes=[n1, n2],
related_by_node={"g1": [{"target_id": "g2", "relation_type": "causes"}]},
)
assert stats["nodes"] == 2
assert stats["co_occurs"] == 1 and stats["typed"] == 1
edges = await gs.get_related_edges(["g1"])
# 无向去重:g1↔g2 之间两种关系各一条(co_occurs + causes)
rtypes = sorted(e["relation_type"] for e in edges)
assert rtypes == ["causes", "co_occurs"]
assert all(e["target_status"] == "active" for e in edges)
# 关系类型过滤
only_causes = await gs.get_related_edges(["g1"], relation_types=["causes"])
assert [e["relation_type"] for e in only_causes] == ["causes"]
# shadow 后读侧必须能过滤掉
await sync_graph_on_shadow(gs, ["g2"])
adj = build_adjacency(await gs.get_related_edges(["g1"]))
assert adj == {}
# Topic 语义归一化:work / job 复用同一个 Topic,food 独立
ik = n1.get_isolation_key()
t_work = await gs.add_topic_tag("g1", "work", ik, embed_service=_Embed())
t_job = await gs.add_topic_tag("g1", "job", ik, embed_service=_Embed())
t_food = await gs.add_topic_tag("g1", "food", ik, embed_service=_Embed())
assert t_job == t_work, "同义 tag 应复用同一 Topic,否则 tag 图会碎成同义孤岛"
assert t_food != t_work
topics = await gs.get_all_topics(ik)
assert {t["name"] for t in topics} >= {"work", "food"}
# 两个后端的返回键必须一致 —— degree 缺失会让画像聚合(§7.1)静默失效
assert all({"topic_id", "name", "embedding", "degree"} <= set(t) for t in topics)
assert all(t["degree"] >= 1 for t in topics if t["name"] == "work")
# get_topic_memories:给 Topic-scoped summary 取素材
mems = await gs.get_topic_memories(t_work)
assert [m["node_id"] for m in mems] == ["g1"]
# 图里没有 memory_at(Memory 表只有 created_at),事件时间以 VDB 为准
assert "memory_at" not in mems[0]
finally:
await gs.close()
@pytest.mark.asyncio
@pytest.mark.parametrize("backend", _BACKENDS)
async def test_temporal_spine_end_to_end(backend, tmp_path):
"""时序脊:同 Topic 内按 memory_at 串有向边,两个方向都能查到。"""
from datetime import datetime
gs = await _make_graph_store(backend, tmp_path, "spine")
class _Embed:
async def embed_queued(self, text):
return [1.0, 0.0, 0.0]
async def embed(self, text):
return [1.0, 0.0, 0.0]
# 事件时间以 VDB 为准(图的 Memory 表没有 memory_at)
written: Dict[str, Any] = {}
class _VS:
async def get_by_ids(self, ids):
return [written[i] for i in ids if i in written]
try:
# 同一个 Topic(fitness)下三条按时间递进的记忆,分三批写入
specs = [
("t1", "started jogging", datetime(2026, 1, 1)),
("t2", "ran a 10k", datetime(2026, 3, 1)),
("t3", "ran a half marathon", datetime(2026, 6, 1)),
]
for nid, content, ts in specs:
node = _node(nid, content, tags=["fitness"])
node.memory_at = ts
st = await project_memories_to_graph(
graph_store=gs, embed_service=_Embed(), nodes=[node],
vector_store=_VS(), temporal_spine=True,
)
written[nid] = node
# 第一条没有前驱;后两条各接一条时序边
assert st["temporal"] == (0 if nid == "t1" else 1), nid
edges = await gs.get_related_edges(["t2"])
temporal = [e for e in edges if e["relation_type"] == "temporal_next"]
# t2 既有前驱 t1 也有后继 t3 —— 两个方向都要能查到,
# 否则 "X 之前发生了什么" 走不通
assert {(e["source_id"], e["target_id"]) for e in temporal} == {
("t1", "t2"), ("t2", "t3"),
}
assert all(e["directed"] for e in temporal)
# 方向要能落到路径输出上
fwd = collect_directed_edges(edges)
assert ("t1", "t2") in fwd and ("t2", "t3") in fwd
paths = find_relation_paths(
hit_scores={"t1": 0.9, "t3": 0.85},
adjacency=build_adjacency(edges),
forward_dirs=fwd,
)
two_hop = [p for p in paths if p["hops"] == 2 and p["nodes"][0] == "t1"]
assert two_hop, "t1 →(t2)→ t3 的时序路径应被找到"
assert all(r.get("direction") == "forward" for r in two_hop[0]["relations"])
# include_temporal=False 时不返回时序边
assert not [
e for e in await gs.get_related_edges(["t2"], include_temporal=False)
if e["relation_type"] == "temporal_next"
]
finally:
await gs.close()