MemOS 基于 NebulaGraph 的图记忆后端：配置、多租户隔离与快速接入实战-平芜编程栈

人工智能
大模型
Agent 记忆
AI Agent
RAG
知识图谱
dsh-plugin

【免费下载链接】MemOS

Self-evolving memory OS for LLM & AI Agents: ultra-persistent memory, hybrid-retrieval, and cross-task skill reuse, with 35.24% token savings and DeepSeek Harness support.

项目地址：https://gitcode.com/gh_mirrors/memos/MemOS

点击查看免费下载

MemOS 在树形明文记忆（TreeTextMemory）体系中，通过BaseGraphDB抽象层隔离了不同的图数据库后端。本文聚焦其中的NebulaGraph（Nebula Graph）明文记忆后端，讲解其生产级配置模板、两种多租户架构（单库多用户与多库隔离）以及从工厂创建到节点写入的完整接入流程，并结合仓库源码给出可验证的实现依据。读完本文，你将能独立完成 NebulaGraph 后端的配置接入、租户隔离方案选型与基础记忆节点写入。

为什么选择 NebulaGraph

在 MemOS 的图后端矩阵中，NebulaGraph 的定位是面向大规模分布式部署的图数据库选项。根据记忆模块总览，它被归入为 TreeTextMemory 提供图存储能力的三个后端之一（另两个是 Neo4j 与 PolarDB），并强调其分布式与高可用特性。具体而言，选用 NebulaGraph 的核心理由有三点：

适合大规模分布式部署：NebulaGraph 原生采用存储与计算分离的分布式架构，Graph、Meta、Storage 服务可以独立水平扩展，适合记忆图谱规模增长到单机难以承载的场景；
点、边标签与属性灵活定义：NebulaGraph 允许在点和边上自由定义 Tag（标签）与属性（Property），正好契合记忆节点（Node）与关系（Edge）都需要携带丰富元数据（如memory_type、status、confidence、tags等）的存储诉求；
内置向量索引支持（Nebula 5 起）：从 NebulaGraph 5.0 开始支持向量类型与向量索引，这意味着图结构搜索与向量语义检索可以在同一套存储内完成，为记忆的混合检索（图遍历 + 向量相似度）提供了底座能力。

需要说明的是，文档中的后端标识统一写作"nebular"（而非"nebula"），配置、示例与安装指南的.env模板（NEO4J_BACKEND可选值列表）中均使用这一拼写，接入时请保持完全一致。

架构定位：BaseGraphDB 抽象与工厂模式

在深入配置之前，先理清 NebulaGraph 后端在整个记忆体系中的位置，这决定了你配置的字段会流向哪里、被谁消费。

抽象接口层：BaseGraphDB 是全部图后端的抽象基类，定义了统一的节点/边管理（add_node、update_node、delete_node、add_edge、edge_exists）、图查询与推理（get_node、get_neighbors、get_path、get_subgraph、get_context_chain）、召回（search_by_embedding、get_by_metadata）、结构维护（deduplicate_nodes、detect_conflicts、merge_nodes）以及持久化（export_graph、import_graph、get_all_memory_items）等接口。任何图后端只要实现这套契约，即可无缝接入 MemOS 记忆管线。
配置与工厂层：GraphDBConfigFactory 负责将backend字符串映射到对应的配置类，GraphStoreFactory 的from_config方法则根据config_factory.backend查表实例化具体的图存储对象。上层记忆模块不感知后端差异。
消费层：TreeTextMemory 在初始化时通过GraphStoreFactory.from_config(config.graph_db)拿到图存储实例（见 tree.py），后续的add、search、get_all、dump/load等操作全部委托给该实例。

因此，接入 NebulaGraph 本质上是两件事：在graph_db配置块中声明backend: "nebular"，并给出符合文档约定的连接参数。

生产级推荐配置模板

文档给出了一套面向生产场景、兼容多租户逻辑隔离的推荐配置，完整继承如下：

"graph_db": { "backend": "nebular", "config": { "uri": ["localhost:9669"], "user": "root", "password": "your_password", "space": "database_name", "user_name": "user_name", "use_multi_db": false, "auto_create": true, "embedding_dimension": 1024 } }

各参数的含义与调优要点：

参数	说明	取值建议
`uri`	NebulaGraph 服务地址（Graph 服务端口，默认 9669），支持字符串或地址列表	分布式环境填多地址列表，如`["192.168.1.10:9669", "192.168.1.11:9669"]`
`user`	连接 NebulaGraph 的账号	默认`root`（NebulaGraph 内置超级账号）
`password`	账号密码	生产环境务必使用强密码
`space`	Nebula 图空间名称，相当于数据库	按业务或租户命名
`user_name`	多用户逻辑隔离标识，系统会自动注入过滤条件	单库多用户模式下必填，多库模式下可省略
`use_multi_db`	是否启用多库（每用户一空间）的物理隔离模式	`false`表示单库 + 逻辑隔离
`auto_create`	是否自动创建图空间及 Schema	推荐测试环境开启；生产环境建议由 DBA 预建
`embedding_dimension`	向量维度，必须与嵌入模型输出维度一致	例如`text-embedding-3-large`为 3072，常用开源模型常为 768/1024

embedding_dimension 与嵌入模型对齐

embedding_dimension是整个配置中最容易出现“配了却查不到”的隐性坑点：它必须严格等于你所用嵌入模型的输出维度。文档明确指出需“根据你的嵌入模型调整”——例如 OpenAItext-embedding-3-large输出 3072 维，则应填3072。MemOS 在 TreeTextMemoryConfig 中通过embedder字段配置嵌入模型，而图后端用embedding_dimension声明向量列宽度，两者不一致会导致写入或向量检索失败。若不确定模型维度，可用一次嵌入调用打印向量的len()来确认。

auto_create 的作用域

auto_create: true时，后端会尝试自动创建图空间（space）并初始化 Schema（节点 Tag 与边 Edge Type）。这在联调、测试环境非常省事；但在生产环境，图空间的副本数、分片数等物理参数通常需要按集群规划预先设定，因此文档建议生产环境由运维预建空间、关闭自动创建。

多租户使用模式

NebulaGraph 后端支持两种多租户架构，核心差异在于“隔离发生在物理层还是逻辑层”。

模式一：单库多用户（Shared DB + user_name）

适用于多个用户/Agent共用同一个图空间，通过逻辑隔离互相不可见：

GraphDBConfigFactory( backend="nebular", config={ "space": "shared_graph", "user_name": "alice", "use_multi_db": False, ... }, )

要点：use_multi_db=False时，user_name是必填项。系统会在写入节点时把user_name写入元数据，并在所有查询中自动注入过滤条件（WHERE），从而实现租户数据隔离。这一设计在 MemOS 的图后端实现中是一致性约定——以 neo4j.py 为例，add_node在非多库模式下会把metadata["user_name"] = user_name，update_node/delete_node/get_memory_count等操作则统一追加AND n.user_name = $user_name条件，NebulaGraph 后端沿用同样的隔离语义。

模式二：多库（Multi DB，每用户一空间）

适用于资源隔离要求更强的场景，每个用户独占一个图空间（space），物理隔离天然杜绝了跨租户查询的可能：

GraphDBConfigFactory( backend="nebular", config={ "space": "user_alice_graph", "use_multi_db": True, "auto_create": True, ... }, )

要点：use_multi_db=True时，通常按用户/Agent 命名space（如user_alice_graph），并建议配合auto_create: True让系统为新租户自动建空间。该模式隔离彻底，但空间数量会随用户数线性增长，适合租户数量可控、数据敏感度高的场景。

选型建议：先想清楚隔离粒度再选模式。逻辑隔离（模式一）部署成本低、空间复用率高；物理隔离（模式二）安全性强、便于独立扩容与备份，代价是资源开销更大。

快速使用示例：从工厂创建到节点写入

文档提供了完整的端到端接入代码，下面完整呈现并补充关键说明。示例演示了：从环境变量读取连接参数 → 通过GraphDBConfigFactory构建配置 → 经GraphStoreFactory实例化后端 → 构造一条带丰富元数据的记忆节点 → 写入图空间。

import os import json from memos.graph_dbs.factory import GraphStoreFactory from memos.configs.graph_db import GraphDBConfigFactory config = GraphDBConfigFactory( backend="nebular", config={ "uri": json.loads(os.getenv("NEBULAR_HOSTS", "localhost")), "user": os.getenv("NEBULAR_USER", "root"), "password": os.getenv("NEBULAR_PASSWORD", "xxxxxx"), "space": os.getenv("space"), "use_multi_db": True, "auto_create": True, "embedding_dimension": os.getenv("embedding_dimension", 1024), }, ) graph = GraphStoreFactory.from_config(config) topic = TextualMemoryItem( memory="This research addresses long-term multi-UAV navigation for energy-efficient communication coverage.", metadata=TreeNodeTextualMemoryMetadata( memory_type="LongTermMemory", key="Multi-UAV Long-Term Coverage", hierarchy_level="topic", type="fact", memory_time="2024-01-01", source="file", sources=["paper://multi-uav-coverage/intro"], status="activated", confidence=95.0, tags=["UAV", "coverage", "multi-agent"], entities=["UAV", "coverage", "navigation"], visibility="public", updated_at=datetime.now().isoformat(), embedding=embed_memory_item( "This research addresses long-term " "multi-UAV navigation for " "energy-efficient communication " "coverage." ), ), ) graph.add_node( id=topic.id, memory=topic.memory, metadata=topic.metadata.model_dump(exclude_none=True) )

代码要点拆解

环境变量驱动的连接配置：uri通过json.loads(os.getenv("NEBULAR_HOSTS", "localhost"))解析，意味着你可以把地址列表以 JSON 数组字符串的形式放进环境变量（如'["192.168.1.10:9669"]'）。user、password、space、embedding_dimension同样全部可由环境变量注入，便于不同环境（开发/测试/生产）复用同一套代码。
工厂解耦：GraphDBConfigFactory负责校验backend合法性并实例化对应配置类；GraphStoreFactory.from_config(config)返回的是符合 BaseGraphDB 契约的图存储对象，上层业务完全不感知后端是 NebulaGraph 还是 Neo4j。这正是 GraphStoreFactory 的设计目的——backend_to_class查表实例化，切换后端只改一个字符串。
记忆节点结构：节点由TextualMemoryItem（memory主文本 +metadata元数据）构成。TreeNodeTextualMemoryMetadata的字段在树形明文记忆中有完整定义，其中memory_type（WorkingMemory/LongTermMemory/UserMemory）、status（activated/archived/deleted）、visibility（private/public/session）等字段直接参与后续的结构化检索与状态过滤，建议写入时认真填充。
写入前先做嵌入：示例中的embedding由embed_memory_item(...)生成，维度必须与配置中的embedding_dimension一致；add_node时通过metadata.model_dump(exclude_none=True)将元数据序列化为字典传入，exclude_none=True会剔除空值字段，避免向图空间写入空属性。

接入 MemOS 记忆管线：与 TreeTextMemory 联动

NebulaGraph 后端不只能被单独调用，更常规的用法是作为tree_text记忆的存储层整体接入。在 TreeTextMemoryConfig 中，graph_db字段的类型就是GraphDBConfigFactory，因此你可以在记忆配置里直接声明backend: "nebular"：

{ "text_mem": { "backend": "tree_text", "config": { "extractor_llm": { ... }, "dispatcher_llm": { ... }, "embedder": { ... }, "graph_db": { "backend": "nebular", "config": { "uri": ["localhost:9669"], "user": "root", "password": "your_password", "space": "shared_graph", "user_name": "alice", "use_multi_db": false, "auto_create": true, "embedding_dimension": 1024 } } } } }

TreeTextMemory 初始化时会执行self.graph_store = GraphStoreFactory.from_config(config.graph_db)（见 tree.py），随后tree_memory.add(memories)、tree_memory.search(query, top_k)、tree_memory.get_all()、tree_memory.dump(dir)/load(dir)等方法全部经由该图存储实例落库。也就是说，把backend从neo4j换成nebular，即可在不改任何上层代码的情况下切换到分布式图后端。作为参考，仓库给出了同结构的 mem_cube 树形记忆配置示例（使用neo4j后端），其字段组织方式与 NebulaGraph 完全同构。

后端注册状态说明（基于当前源码结构）

需要如实指出：虽然本文档及安装指南、REST API 服务器指南的.env模板中均把nebular列为NEO4J_BACKEND的可选值之一，但从当前仓库的源码结构看，GraphStoreFactory 的backend_to_class注册表目前包含的是neo4j、neo4j-community、polardb、postgres四个后端，nebular尚未出现在该注册表中；GraphDBConfigFactory 的配置类映射同样如此。因此可以推断：NebulaGraph 后端当前处于文档先行、实现待合入（或由发行版/分支提供）的状态。在官方注册表包含nebular之前，直接使用backend="nebular"会触发Unsupported graph db backend: nebular校验异常。接入时请以你所安装的 MemOS 版本实际支持的 backend 列表为准，并优先关注该版本是否已合入 NebulaGraph 后端实现。

总结

NebulaGraph 后端为 MemOS 的树形记忆提供了面向大规模分布式部署的图存储选项：通过BaseGraphDB抽象与工厂模式无缝嵌入既有记忆管线；space+user_name+use_multi_db三个字段的组合即可完成从逻辑隔离到物理隔离的租户方案选型；auto_create与embedding_dimension则分别控制 Schema 的初始化方式与向量检索的维度一致性。接入时只需牢记：配置模板照抄、维度与嵌入模型对齐、租户模式先行决策、以当前版本的 backend 注册表为准。后续可继续阅读树形明文记忆完整指南了解记忆抽取、混合检索与备份恢复的完整工作流。

人工智能
大模型
Agent 记忆
AI Agent
RAG
知识图谱
dsh-plugin

【免费下载链接】MemOS

Self-evolving memory OS for LLM & AI Agents: ultra-persistent memory, hybrid-retrieval, and cross-task skill reuse, with 35.24% token savings and DeepSeek Harness support.

项目地址：https://gitcode.com/gh_mirrors/memos/MemOS

点击查看免费下载