4 · 图谱记忆（Graph Memory）

图谱记忆

图记忆（图谱记忆）

相关源文件

以下文件为本 Wiki 页面生成时使用的上下文：

• docs/components/vectordbs/dbs/neptune_analytics.mdx
• examples/graph-db-demo/neptune-example.ipynb
• mem0/__init__.py
• mem0/configs/enums.py
• mem0/configs/prompts.py
• mem0/configs/vector_stores/neptune.py
• mem0/configs/vector_stores/supabase.py
• mem0/memory/main.py
• mem0/memory/storage.py
• mem0/memory/utils.py
• mem0/vector_stores/neptune_analytics.py
• tests/configs/test_prompts.py
• tests/memory/test_main.py
• tests/test_chatty_llm_parsing.py
• tests/test_main.py
• tests/test_memory.py
• tests/test_proxy.py
• tests/vector_stores/test_neptune_analytics.py

图记忆是 Mem0 的知识图谱层，用于存储实体-关系数据，同时支持向量嵌入。向量存储可以实现语义相似性搜索，而图记忆则能捕获显式关系，例如 "Alice -- works_at -- Google" 或 "Bob -- manages_team -- Engineering"。这种双存储架构同时提供了语义检索和结构化关系查询能力。

本文概述了图记忆的集成方式。详细文档请参考：

• 图记忆概述 —— 解释什么是图记忆、何时使用以及它与基于向量的记忆的区别
• 图存储提供商 —— 记录支持的图数据库：Neo4j、Kuzu、Memgraph、Neptune 及其配置
• 实体与关系提取 —— 解释基于大语言模型（LLM）的实体提取、关系建立和 Cypher 查询构建
• 图搜索与检索 —— 记录图遍历、BM25 重排序以及向量与图搜索结果的结合
• 相似性阈值 —— 解释用于实体去重和图节点匹配的向量相似性阈值

来源： mem0/memory/main.py:199-207、mem0/memory/utils.py:73-82

架构总览

mem0/memory/main.py 中的 Memory 类在提供 config.graph_store.config 时会条件性地启用图存储。图操作与向量操作通过 ThreadPoolExecutor 并发执行，以最小化延迟影响。

双存储架构

来源： mem0/memory/main.py:199-207、mem0/memory/main.py:369-384

初始化

图记忆通过 enable_graph 标志启用，该标志在 config.graph_store.config 存在时设置：

# 来自 mem0/memory/main.py 中的 Memory.__init__()
self.enable_graph = False

if self.config.graph_store.config:
    provider = self.config.graph_store.provider
    self.graph = GraphStoreFactory.create(provider, self.config)
    self.enable_graph = True
else:
    self.graph = None

来源： mem0/memory/main.py:199-207

GraphStoreFactory 将提供商名称映射到实现类。默认提供商使用 MemoryGraph，它与 LlmFactory 和 EmbedderFactory 集成以处理关系数据。

来源： mem0/utils/factory.py:36-41

核心组件

图记忆逻辑

图系统是关系操作的主要接口。它连接到图数据库，并使用基于大语言模型（LLM）的实体提取。

关键依赖：

来源： mem0/memory/main.py:35-48

图记忆的工作原理

图记忆使用多阶段大语言模型（LLM）管线从对话文本中提取实体和关系。该过程包括实体提取、关系建立、冲突检测和图更新。

实体与关系提取管线

来源： mem0/memory/main.py:599-608、mem0/utils/entity_extraction.py:35

管线阶段如下：

1. 实体提取 —— 使用 extract_entities 从对话中识别实体和类型 mem0/utils/entity_extraction.py:35。
2. 关系建立 —— 根据对话上下文确定提取的实体如何连接。
3. 冲突检测 —— 使用嵌入向量相似性搜索相似实体，防止重复。
4. 图更新 —— 执行数据库特定的查询以更新关系存储。

有关提取管线的详细文档，请参见实体与关系提取。

搜索与检索

图搜索从查询中提取实体，通过嵌入向量搜索找到相似节点，并使用 BM25 按相关性重排序结果。

图搜索流程

来源： mem0/memory/main.py:93-118、mem0/utils/scoring.py:43-48

搜索过程如下：

1. 使用 extract_entities 从查询中提取实体 mem0/memory/main.py:103。
2. 使用配置的 EmbedderFactory 为每个实体生成嵌入向量 mem0/memory/main.py:100。
3. 执行带有向量相似性匹配的图查询。
4. 使用 score_and_rank 重排序结果，该函数结合了语义分数和 BM25 分数 mem0/utils/scoring.py:47。

有关搜索机制的详细文档，请参见图搜索与检索。

配置

图记忆通过提供 graph_store 配置来启用。系统通过 GraphStoreFactory 支持多个图数据库提供商。

基本配置

from mem0 import Memory

config = {
    "graph_store": {
        "provider": "neo4j",
        "config": {
            "url": "bolt://localhost:7687",
            "username": "neo4j",
            "password": "password"
        }
    }
}

m = Memory(config)

来源： mem0/memory/main.py:199-207、tests/test_main.py:31-32

支持的提供商

有关提供商特定的配置详情，请参见图存储提供商。

使用示例

图记忆与常规记忆操作集成。启用后，会同时返回向量和图结果。

添加带图的记忆

# 添加包含关系的对话
messages = [
    {"role": "user", "content": "我是 Alice，我在 Google 担任工程师。"}
]

result = m.add(messages, user_id="alice")

当 enable_graph 为 true 时，输出结构包含 relations。

来源： mem0/memory/main.py:378-384

基于会话的过滤

图记忆会尊重会话标识符（user_id、agent_id、run_id）以实现多租户隔离。这些参数必须通过 filters 传递，以避免使用 _reject_top_level_entity_params 进行校验时出错。

来源： mem0/memory/main.py:100-110

与记忆操作的集成

Memory 类使用 ThreadPoolExecutor 并发执行图操作：

# 来自 mem0/memory/main.py 中的 Memory.add()
with concurrent.futures.ThreadPoolExecutor() as executor:
    future1 = executor.submit(self._add_to_vector_store, messages, metadata, filters, infer)
    future2 = executor.submit(self._add_to_graph, messages, filters)

    concurrent.futures.wait([future1, future2])

来源： mem0/memory/main.py:369-377

这种并行执行方式可以最小化延迟。结果会在响应中合并：

if self.enable_graph:
    return {
        "results": vector_store_result,
        "relations": graph_result,
    }

来源： mem0/memory/main.py:378-384