FalkorDB 图存储集成

August 14, 2026 · View on GitHub

本 Fork 已将 FalkorDB 直接编译进 GraphStoreFactory，配置 graph_store.provider="falkordb" 即可使用，无需额外插件或 monkey-patch。

本文档说明图存储的接入方式、数据模型、检索机制与注意事项，配套根目录 README.md 的「图存储与检索」章节阅读。

为什么用图存储

纯向量检索只能按「语义相似度」找记忆，回答不了关系型问题：

「发哥部署在哪台服务器？」——向量库里是两条独立记忆（发哥 和 web-1.example.com），没有边连接
图存储把实体抽成节点、关系抽成边：(发哥)-[部署于]->(web-1.example.com)

搜索时图召回的结果会合并进最终结果（full 深度），让 agent 拿到「谁和谁有什么关系」的结构化上下文。

架构

┌─────────────────────────────────────────────────────────────┐
│ mem0 Memory 实例                                             │
│  config.graph_store.provider="falkordb"                     │
└──────────────────────────┬──────────────────────────────────┘
                           │ GraphStoreFactory.create("falkordb")
┌──────────────────────────▼──────────────────────────────────┐
│  mem0/graphs/falkordb/MemoryGraph                            │
│  ┌────────────────────────────────────────────────────────┐  │
│  │ · _retrieve_nodes_from_data        → LLM 实体提取       │  │
│  │ · _establish_nodes_relations_from_data → LLM 关系提取  │  │
│  │ · _search_graph_db                 → BM25 重排图召回    │  │
│  │ · _add_entities                    → Cypher MERGE 写入  │  │
│  │ · _invalidate_entities             → 冲突失效标记       │  │
│  └────────────────────────────────────────────────────────┘  │
└──────────────────────────┬──────────────────────────────────┘
                           │ FalkorDB driver
┌──────────────────────────▼──────────────────────────────────┐
│  FalkorDB（图数据库）                                        │
│  每用户独立图：mem0_{user_id}                                │
└─────────────────────────────────────────────────────────────┘

快速接入

Server 部署

在 config.json 中配置：

{
  "graph_store": {
    "provider": "falkordb",
    "config": {
      "host": "falkordb",
      "port": 6379,
      "database": "mem0"
    }
  }
}

Docker Compose 环境下 host 用服务名 falkordb（容器间通信）。FalkorDB 默认端口 6379。

Python SDK

from mem0 import Memory

config = {
    "graph_store": {
        "provider": "falkordb",
        "config": {"host": "localhost", "port": 6379, "database": "mem0"},
    },
    "vector_store": {
        "provider": "pgvector",
        "config": {"host": "localhost", "port": 5432, "user": "postgres", "password": "...", "dbname": "mem0"},
    },
    "llm": {"provider": "openai", "config": {"model": "gpt-4o-mini"}},
    "embedder": {"provider": "openai", "config": {"model": "text-embedding-3-small"}},
}

m = Memory.from_config(config)

不需要 from mem0.graphs.falkordb import register; register()——FalkorDB 已内置在工厂里。

验证

调用 m.add() 写入记忆
打开 FalkorDB Web UI（Docker 部署默认端口 3003）
执行查询：

GRAPH.QUERY mem0_alice "MATCH (n)-[r]->(m) RETURN n, r, m"

应能看到实体节点（人物/地点/概念等）和关系边。

也可以通过搜索验证图召回生效（full 深度）：

results = m.search("发哥部署在哪里", user_id="alice", depth="full")
# results 中会出现 source="graph" 的片段

数据模型

每用户图隔离

每个 user_id 对应一个独立图，命名规则 mem0_{user_id}：

user_id	FalkorDB 图名
`alice`	`mem0_alice`
`bob`	`mem0_bob`

用户之间的图数据完全隔离，互不干扰。

图数据生命周期

写入链路（add()）：

_retrieve_nodes_from_data() → LLM 实体提取
_establish_nodes_relations_from_data() → LLM 关系提取
_search_graph_db() → BM25 重排已有关系
_add_entities() → Cypher MERGE 写入

搜索链路（search()，full 深度）：

从查询提取实体
_search_graph_db() 查询实体关联
BM25 重排后合并进搜索结果

delete_all()：自动清理对应图数据（整图删除）。delete() 单条删除不清图——图按用户共享，逐条删除会破坏图结构（代码明确跳过：graph cleanup skipped (shared knowledge graph)）。

图记忆时效

冲突消解采用失效保留策略，而非物理删除：

行为	说明
冲突消解	旧关系写入 `invalidated_at` 标记失效，不删除
检索	默认只返回有效关系（`invalidated_at IS NULL`）
同事实重现	自动复活（MERGE 命中失效边时重置标记）
存量数据	无标记视为有效，向后兼容
LLM 成本	失效时间戳由 Cypher 生成，写入零 LLM 成本（冲突判定复用既有 LLM 消解链路）

价值：① 被推翻的事实不再污染图上下文；② LLM 判断错了只是「误失效」，可追溯、可恢复，而非永久丢失。

参数

参数	默认值	说明
`host`	`localhost`	FalkorDB 服务器地址
`port`	`6379`	FalkorDB 端口
`database`	`mem0`	图名前缀
`username`	—	认证用户名
`password`	—	认证密码
`base_label`	`true`	是否使用 `__Entity__` 基础标签

注意事项

FalkorDB 使用 Cypher 查询语言（与 Neo4j 兼容）
中文 entity_type / relationship 经 backtick 转义后直接写入（FalkorDB v42001+ 原生支持 CJK 标识符，无需英文映射）；非法字符（;/括号等注入面）替换为下划线
每用户独立图，互不干扰
图搜索为 full 深度的可选增强：MEM0_SEARCH_DEPTH_DEFAULT=standard 时跳过图查询（降本但丢失关系召回）
清理脚本会同步清理 FalkorDB 孤立实体节点（无任何关系的节点）
图召回合成条目：搜索时图召回会生成「src 关系 dst」的合成文本条目（如「发哥偏好龙井茶」），id 为临时 uuid，不含 payload/metadata/memory_type。当搜索带 memory_type 类型过滤时（filters 含 memory_type 或别名 type），图召回整体跳过——合成条目无类型无法满足过滤条件；普通搜索（无类型过滤）图召回照常。