"""记忆关系图（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()