为OpenClaw构建基于时间线的知识图谱大脑：Graphiti插件实战指南

1. 项目概述为OpenClaw构建一个基于时间线的知识大脑如果你和我一样长期使用OpenClaw这类AI助手进行项目协作、知识整理和深度对话你可能会遇到一个核心痛点对话是线性的、易逝的。一次长达数小时的头脑风暴一旦会话窗口被压缩或重置那些宝贵的洞见、决策背后的逻辑、以及不同概念之间千丝万缕的联系就仿佛沉入了记忆的深海难以系统性地追溯和复用。这正是robertogongora/graphiti插件要解决的根本问题。它不是一个简单的记忆插件而是一个为OpenClaw注入“时间感知”和“关系思维”的知识图谱引擎。它将你和AI助手之间的每一次对话、每一个决策、每一段文本都转化为一个动态演化的知识网络存储在Neo4j图数据库中。简单来说它让你的AI助手拥有了一个基于时间线的、可查询、可推理的“长期记忆大脑”。这个插件巧妙地桥接了两种记忆范式memory-core插件提供的基于文件的、静态的语义搜索擅长回答“我笔记里写过什么”以及Graphiti提供的基于图结构的、动态的关联记忆擅长回答“X和Y有什么关系”、“项目A的历史演进是怎样的”。两者协同工作构成了一个既稳固又灵活的记忆体系。1.1 核心价值与适用场景这个插件的价值在于它将对话从“一次性消费品”变成了可沉淀、可挖掘的“知识资产”。它特别适合以下几类深度用户复杂项目协作者如果你在用OpenClaw管理一个软件开发、研究论文或产品设计项目这个插件能自动记录每次讨论中提到的功能点、技术决策、依赖关系和待办事项并理清它们之间的关联。持续学习者与研究者当你围绕一个主题比如“机器学习优化算法”进行多轮、跨时间的对话时插件能帮你构建概念图谱清晰展示不同算法之间的演进、优劣对比和应用场景形成结构化的学习笔记。创意与内容创作者对于小说构思、视频脚本策划等内容创作插件可以追踪角色关系、情节线索、世界观设定在不同会话中的发展和变化防止设定冲突或遗忘关键伏笔。追求自动化的工作流构建者插件提供的自动捕获Auto-capture、自动索引Auto-index和可选的自动回忆Auto-recall功能能极大减少手动整理知识的工作量让知识积累成为一个无缝的后台进程。它的核心运作依赖于两个外部服务Graphiti服务器负责接收文本并调用LLM进行实体与关系抽取和Neo4j数据库负责存储和查询图谱数据。因此部署前需要确保这两个服务正常运行。2. 架构设计与核心工作流解析理解这个插件如何工作是有效使用它的前提。它的设计哲学是“非侵入式增强”即在OpenClaw现有工作流的基础上透明地添加一层知识图谱能力。整个架构可以看作一个双通道记忆系统。2.1 双通道记忆模型文件记忆与图谱记忆插件与memory-core并非替代关系而是互补关系。自v0.3.0起它不再独占记忆槽位推荐配置是让两者并行运行。通道一文件记忆 (memory-core)数据源你工作区中的MEMORY.md和memory/目录下的Markdown文件。能力提供基于关键词BM25和语义向量的混合搜索 (memory_search)。擅长处理“我在笔记的哪个文件里提过‘用户画像’”这类问题。特点静态、文档化、易于人类直接阅读和编辑。通道二图谱记忆 (graphiti)数据源自动从对话内容中提取的实体人、物、概念和关系。能力提供基于图数据库的关联查询 (graphiti_search)。擅长处理“用户画像和A/B测试功能之间有哪些关联讨论”“我们上周决定推迟哪个功能的发布”这类涉及关系和时序的问题。特点动态、关联性强、支持时间旅行查询如“显示三月所有关于‘数据库’的讨论”。这种设计让你可以根据需求灵活选择工具而不是被限定在单一的记忆模式中。2.2 核心数据流从对话到知识图谱插件通过几种方式将信息注入知识图谱其核心流程涉及一个关键的异步处理环节。1. 自动捕获 (Auto-capture)这是最主要的知识来源。当OpenClaw会话发生特定事件时具体取决于运行模式插件会拦截对话内容发送给Graphiti服务器。在Hooks模式旧版下仅在会话压缩 (compaction) 或重置 (/new) 时触发一次性批量处理累积的对话。在ContextEngine模式v0.6.0推荐下在每一轮对话 (afterTurn)后立即触发实现近乎实时的知识沉淀。这是更优的设计避免了信息在压缩前丢失的风险。2. 自动索引 (Auto-index)这是一个非常实用的功能它桥接了文件记忆和图谱记忆。当OpenClaw或你通过它向memory/目录写入一个.md或.txt文件时插件会感知到这个操作并自动将该文件的内容摘要作为一个“索引事件”发送给Graphiti。随后Graphiti的LLM管道会分析这个文件提取其中的实体和关系并入知识图谱。这意味着你手动整理的笔记也能自动丰富图谱。3. 手动工具注入你或AI助手可以随时使用graphiti_ingest工具主动将一段关键文本例如会议纪要、项目章程送入图谱。graphiti_forget工具则用于删除过时或错误的事实维护图谱的准确性。关键异步环节LLM实体关系抽取这里有一个至关重要的细节当插件向Graphiti的/messages端点发送内容后Graphiti会立即返回一个202 Accepted响应表示“已接收正在处理”。真正的重头戏——使用OpenAI的模型如gpt-4o-mini分析文本、识别实体如“项目Alpha”、“张三”、“Python库Pandas”和关系如“项目Alpha 使用 Python库Pandas”、“张三 是 项目Alpha 的 负责人”——是在后台异步完成的。注意这意味着如果你在Graphiti服务器的环境变量中没有正确设置OPENAI_API_KEY虽然“发送”步骤会成功返回202但后续的“分析”步骤会静默失败。你的对话内容看似被“记忆”了但实际上图谱里空空如也。这是最常见的配置陷阱务必通过openclaw graphiti episodes命令检查事件是否成功创建。2.3 两种运行模式Hooks vs. ContextEngine插件为了兼容不同版本的OpenClaw实现了两套内部逻辑。Hooks模式 (Legacy)适用于OpenClaw v2026.3.7之前的版本。插件通过事件钩子before_agent_start,before_compaction等介入OpenClaw的生命周期。知识捕获是批量的、事件驱动的仅在压缩/重置时不够实时。ContextEngine模式 (Modern)适用于OpenClaw v2026.3.7及之后版本。插件声明kind: context-engine被OpenClaw核心运行时直接调用。它提供了更精细的生命周期方法如afterTurn,ingest支持单轮对话后立即捕获、子代理知识融合等高级特性。这是未来发展的方向能提供更稳定、更强大的记忆体验。对于新用户建议直接使用支持ContextEngine的OpenClaw版本。插件会自动检测并启用对应模式无需手动配置。3. 从零开始完整部署与配置指南理论清晰后我们进入实战环节。我将带你完成从服务部署、插件安装到深度配置的全过程并穿插我踩过坑后总结的注意事项。3.1 基础服务部署Docker Compose一键启动最省心的方式是使用Docker Compose同时启动Neo4j和Graphiti。请确保你的环境已安装Docker和Docker Compose。1. 创建docker-compose.yml文件在你喜欢的位置例如~/graphiti-stack创建该文件内容如下version: 3.8 services: neo4j: image: neo4j:5-community container_name: openclaw-neo4j environment: - NEO4J_AUTHneo4j/your-strong-password-here # 务必修改 - NEO4J_PLUGINS[apoc, graph-data-science] # 可选安装常用插件 ports: - 7474:7474 # 浏览器访问 http://localhost:7474 使用Neo4j Browser - 7687:7687 # Bolt协议端口Graphiti通过此端口连接 volumes: - neo4j_data:/data - neo4j_logs:/logs - neo4j_import:/var/lib/neo4j/import - neo4j_plugins:/plugins healthcheck: test: [CMD-SHELL, cypher-shell -u neo4j -p your-strong-password-here RETURN 1 || exit 1] interval: 10s timeout: 10s retries: 5 start_period: 40s restart: unless-stopped graphiti: image: zepai/graphiti:latest container_name: openclaw-graphiti environment: - NEO4J_URIbolt://neo4j:7687 - NEO4J_USERneo4j - NEO4J_PASSWORDyour-strong-password-here # 必须与上面一致 - OPENAI_API_KEY${OPENAI_API_KEY} # 从宿主机环境变量读取 - MODEL_NAMEgpt-4o-mini # 实体抽取模型平衡效果与成本 - SERVER_HOST0.0.0.0 - SERVER_PORT8000 ports: - 127.0.0.1:8100:8000 # 仅本地访问Graphiti服务端口 depends_on: neo4j: condition: service_healthy volumes: - graphiti_logs:/app/logs restart: unless-stopped volumes: neo4j_data: neo4j_logs: neo4j_import: neo4j_plugins: graphiti_logs:2. 设置关键环境变量在运行Compose命令的终端中你需要先设置OpenAI的API密钥。这个密钥是给Graphiti服务用的与OpenClaw自身可能使用的密钥是分开的。export OPENAI_API_KEYsk-你的真实OpenAI API Key重要提示你也可以将OPENAI_API_KEY写入一个.env文件放在docker-compose.yml同目录下Docker Compose会自动加载。但务必确保.env文件不被提交到版本控制系统已加入.gitignore。3. 启动服务在docker-compose.yml所在目录执行docker-compose up -d使用docker-compose logs -f graphiti可以实时查看Graphiti的启动日志确保没有报错。4. 验证服务健康Neo4j浏览器打开http://localhost:7474使用用户名neo4j和你设置的密码登录。能进入Neo4j Browser即表示成功。Graphiti在终端执行curl http://localhost:8100/health应该返回{status:ok}。3.2 插件安装与基础配置服务就绪后我们来安装和配置OpenClaw插件。1. 安装插件推荐从npm直接安装稳定版本openclaw plugins install robertogongora/graphiti如果你想体验最新特性可能包含未稳定功能可以安装beta版但生产环境不建议openclaw plugins install robertogongora/graphitibeta2. 核心配置安装后需要修改OpenClaw的配置文件通常是~/.openclaw/config.json。以下是推荐的基础配置{ plugins: { slots: { memory: memory-core // 记忆槽位仍由 memory-core 占据 }, entries: { memory-core: { enabled: true // 确保文件记忆启用 }, graphiti: { enabled: true, config: { url: http://localhost:8100, // Graphiti服务地址 groupId: my_primary_agent, // 命名空间用于隔离不同代理的数据 autoCapture: true, // 启用自动捕获对话 autoRecall: false, // 新手建议先关闭手动搜索更可控 autoIndex: true, // 启用自动索引 memory/ 下的文件 debug: true // 启用调试日志方便排错 } } } } }groupId这是一个非常重要的概念。它相当于知识图谱中的一个“命名空间”或“数据库”。如果你有多个不同用途的OpenClaw代理例如一个用于工作一个用于学习为它们设置不同的groupId如work,study可以完全隔离彼此的记忆避免信息交叉污染。autoRecall我强烈建议在熟悉插件工作方式前将其设为false。当开启时插件会在每轮对话前自动向AI的上下文注入它认为相关的图谱事实。虽然这听起来很智能但如果图谱中积累了大量信息可能会导致无关信息干扰当前对话或消耗大量token。更好的方式是让AI在需要时主动使用graphiti_search工具。3. 验证插件状态配置完成后重启OpenClaw或重新加载配置。然后使用插件自带的CLI命令检查openclaw graphiti status如果一切正常你会看到Graphiti服务器健康状态为“OK”并且当前groupId下的事件数量。3.3 高级配置与调优基础配置能满足大部分需求但了解以下高级选项能让你用得更顺手。1. 身份验证与远程连接如果你的Graphiti部署在远程服务器或需要API密钥访问配置如下{ plugins: { entries: { graphiti: { config: { url: https://your-graphiti-server.com, apiKey: your-bearer-token-here, groupId: production_agent } } } } }2. 自动索引文件类型过滤默认只索引.md和.txt文件。如果你也用OpenClaw处理其他格式的文本文件可以扩展{ config: { autoIndexExtensions: [.md, .txt, .rst, .org, .tex] } }避坑指南切勿将.json,.yaml,.csv等结构化数据文件加入列表。Graphiti的LLM会试图从这些文件的每一行中提取实体结果会产生大量无意义的、来自键名、路径、时间戳的“垃圾”实体严重污染你的知识图谱。3. 调试日志管理插件内置了详细的调试日志记录所有API调用的状态码和耗时但不记录任何对话内容或个人信息可安全分享。查看日志openclaw graphiti logs清空日志openclaw graphiti logs --clear自定义日志路径{ config: { logFile: /path/to/your/custom-graphiti.log } }4. 实战应用工具使用、场景分析与问题排查配置妥当后我们来看看如何在日常对话中与这个“知识大脑”互动。4.1 工具使用详解AI与你的联合记忆操作插件为OpenClaw Agent提供了四个核心工具你可以在对话中直接指示AI使用它们。1.graphiti_search- 知识图谱查询这是最常用的工具。当你想追溯历史、探寻关联时就让AI使用它。你“我们之前讨论过关于‘用户认证’有哪些不同的方案把它们和各自的优缺点找出来。”AI调用graphiti_search查询“用户认证 方案 优缺点”“根据知识图谱记录我们讨论过三种方案1. JWT令牌... 2. OAuth 2.0... 3. 会话Cookie... 其中在[某月某日]的对话中提到JWT的无状态特性适合微服务但密钥管理是个挑战...”2.graphiti_ingest- 手动知识注入当你有一份重要的文档或一段总结性文字需要永久纳入记忆时使用。你“这是本次项目评审会的最终决议文档请把它存入长期记忆。”AI调用graphiti_ingest传入文档内容“已将该决议文档的关键内容提取并存入知识图谱。涉及实体‘项目里程碑V2’、‘后端团队’、‘前端团队’关系‘负责’、‘依赖于’等。”3.graphiti_forget- 事实修正人非圣贤AI也会记错。或者有些信息已过时需要清理。你“我们之前错误地记录了‘系统依赖Redis 6.0’实际是Redis 7.0。请修正这个信息。”AI调用graphiti_forget指定要删除的错误事实“已从图谱中移除关于‘系统依赖Redis 6.0’的事实。你可以现在重新注入正确的版本信息。”4.graphiti_episodes- 记忆事件浏览想看看最近都“记住”了些什么这个工具可以列出最近的捕获事件。你“显示最近有哪些对话被存成了记忆”AI调用graphiti_episodes“过去24小时内有5个事件被捕获1. 关于API设计的讨论压缩事件 2.memory/project_plan.md文件索引事件 3. ...”4.2 场景化工作流示例让我们结合具体场景看看这套系统如何运转。场景一软件开发项目跟踪你正在开发一个“智能待办”应用。日常对话你和AI讨论“我们需要一个任务优先级算法可以基于截止日期和标签。”“数据库用PostgreSQLORM用Prisma。”“用户界面需要支持拖拽排序。”自动捕获每轮对话后autoCapture将这些讨论送入Graphiti。LLM从中提取出实体任务优先级算法、截止日期、标签、PostgreSQL、Prisma、用户界面、拖拽排序。并建立关系任务优先级算法 基于 截止日期、任务优先级算法 基于 标签、项目 使用 PostgreSQL、项目 使用 Prisma、用户界面 支持 拖拽排序。后续查询一周后你问“我们当初为什么选Prisma而不是TypeORM”AI使用graphiti_search能定位到当时讨论的上下文甚至引用出你当时说的原话片段如果原始对话还在上下文中或者至少给出基于提取事实的总结“根据记录在[日期]的讨论中提到了Prisma的强类型安全和更简洁的迁移工作流。”文件索引你将会议纪要写成memory/design_review_20241010.md。autoIndex会将其内容也提取到图谱中与之前的对话记忆关联起来。场景二个人学习研究你在学习“量子计算”。多轮对话今天你问了“量子比特和经典比特的区别”明天你问了“超导量子计算机的原理”后天你问了“Shor算法是如何工作的”。图谱构建Graphiti逐渐构建起一个包含量子比特、经典比特、叠加态、超导、约瑟夫森结、Shor算法、因数分解等实体及其关系的知识网络。关联发现你可以问“Shor算法和之前讨论的量子比特特性有什么联系”AI通过图谱查询能解释Shor算法如何利用量子比特的叠加和纠缠特性来实现并行计算从而高效分解大数。4.3 常见问题排查与调试实录即使配置正确你也可能会遇到一些棘手情况。以下是我在实践中总结的排查清单。问题1对话后openclaw graphiti episodes显示为空或没有新事件。这是最常见的问题根本原因通常是Graphiti的后台实体抽取失败了。检查步骤确认Graphiti服务日志运行docker-compose logs graphiti如果你用Docker。重点查找与OpenAI API调用相关的错误如Invalid API Key,Rate limit exceeded,Model not available。验证OpenAI API密钥确保在Graphiti容器环境中设置的OPENAI_API_KEY有效且有余额。可以进入容器内测试docker exec openclaw-graphiti curl -H Authorization: Bearer $OPENAI_API_KEY https://api.openai.com/v1/models。检查插件调试日志运行openclaw graphiti logs。查看ingest操作是否返回status202。如果是202说明插件成功发送了内容问题出在Graphiti后续处理。如果返回4xx或5xx则是网络或Graphiti服务本身的问题。检查Graphiti配置模型确保MODEL_NAME如gpt-4o-mini是你有权限访问的模型。如果你只有GPT-3.5的权限却配置了GPT-4也会失败。问题2graphiti_search返回的结果不相关或太少。可能原因1数据尚未被处理。从发送内容到实体被提取、索引到图谱有几分钟的延迟取决于LLM处理速度。刚发送的内容立即搜索可能找不到。可能原因2查询方式问题。graphiti_search本质上是语义搜索。尝试使用更自然、包含关键实体的短语而不是单个关键词。例如用“项目Alpha的数据库设计讨论”比只用“数据库”更好。可能原因3图谱数据质量。LLM的实体抽取并非完美可能会遗漏某些实体或关系。你可以通过graphiti_ingest手动注入一份结构更清晰的摘要来补充。问题3开启autoRecall后AI的回复变得奇怪或偏离主题。原因autoRecall会在每轮对话前自动向AI上下文注入它认为最相关的N个由recallMaxFacts控制图谱事实。如果图谱中积累了广泛的主题可能会注入不相关的历史事实干扰AI对当前问题的判断。解决方案关闭autoRecall回归到按需使用graphiti_search的模式。这是最可控的方式。如果仍想使用可以尝试调小recallMaxFacts比如从10调到3减少注入量。更高级的做法是利用groupId进行主题隔离。为不同的对话主题创建不同的OpenClaw配置使用不同的groupId确保自动回忆的内容高度相关。问题4autoIndex功能似乎没有为memory/下的旧文件创建索引。原因autoIndex只监听新写入的文件事件。已有的文件不会被自动扫描。解决方案使用openclaw graphiti backfill命令。它会扫描指定的memory/目录为所有尚未索引的、符合扩展名要求的文件创建索引事件。使用--dry-run参数可以先预览哪些文件会被处理。问题5升级插件后配置被重置了。原因在插件v0.7.0-beta.5之前OpenClaw的插件安装/更新机制有时会用模式schema的默认值覆盖用户的自定义配置。解决方案升级到最新版插件该问题已缓解。每次运行openclaw plugins install/update后习惯性地用openclaw config get plugins.entries.graphiti.config检查一下配置是否还在。将你的稳定配置备份到另一个文件万一被覆盖可以快速恢复。5. 进阶技巧与最佳实践经过一段时间的深度使用我总结出一些能让这个插件发挥更大效能的技巧。1. 精心设计groupId策略不要所有对话都用默认的core。根据你的生活工作领域进行划分work_projectApersonal_learning_quantumcreative_writing_novelX这样当你为“工作项目A”开启自动回忆时绝不会混入“个人学习量子计算”的记忆保持上下文的纯净性。你可以在OpenClaw的配置文件目录下为不同场景准备不同的config_work.json,config_study.json通过openclaw --config path/to/config_work.json来切换。2. 主动进行“记忆维护”知识图谱和笔记一样需要偶尔整理。定期审查每周用openclaw graphiti episodes看看都记了些什么。如果发现大量无关紧要的对话被捕获比如闲聊可以考虑临时关闭autoCapture或者事后用graphiti_forget进行清理虽然目前forget需要精确匹配但未来插件可能会增强批量管理能力。高质量注入对于非常重要的结论、设计文档、会议纪要不要完全依赖自动捕获。主动使用graphiti_ingest工具并附上一段你精心提炼的、结构清晰的总结文本。这能极大提升图谱中事实的质量和可检索性。3. 结合memory-core进行混合搜索培养一种新的信息检索习惯。当AI无法直接回答你的问题时可以引导它 “请先用memory_search在我的笔记文件中查找关于‘用户画像’的详细描述然后再用graphiti_search查一下我们过去对话中提到的与‘用户画像’相关的功能点和讨论。” 这样你能同时获得文档细节和对话上下文信息最全面。4. 利用Neo4j Browser进行深度探索对于高级用户直接访问Neo4j Browser (http://localhost:7474) 可以打开新世界。你可以用Cypher查询语言直接探索图谱// 查找与“API设计”相关的所有实体和关系 MATCH (n)-[r]-(m) WHERE n.name CONTAINS API OR m.name CONTAINS API RETURN n, r, m LIMIT 50这能让你直观地看到知识网络的全貌发现一些自动工具可能未直接揭示的深层关联。5. 关注性能与成本Token消耗autoCapture和autoIndex都会向OpenAI发送文本进行实体抽取。长时间、高频度的对话会产生持续的API调用成本。如果你使用GPT-4等高级模型成本不容忽视。建议在Graphiti配置中使用gpt-4o-mini或gpt-3.5-turbo这类性价比高的模型进行抽取平衡效果和成本。存储考量Neo4j数据库会随着时间增长。定期备份你的Neo4j数据卷neo4j_data。如果不再需要某个groupId的全部数据可以通过Neo4j Browser执行删除操作。6. 拥抱ContextEngine模式如果你的OpenClaw版本 v2026.3.7你已经在使用更先进的ContextEngine模式了。这意味着记忆的捕获更及时与OpenClaw核心的集成更紧密。关注插件的更新日志未来针对ContextEngine的优化如更智能的autoRecall、子代理间的记忆传递都将基于此模式开发。这个插件从根本上改变了我和AI协作的方式。它让对话不再是沙滩上的字迹潮水一过就了无痕迹。而是像在共同培育一棵知识树每一次交流都在为它增添枝叶而你可以随时回溯任何一根枝桠的生长轨迹。从手动整理到自动沉淀从线性搜索到关联追溯这套系统带来的信息掌控感是革命性的。当然它也需要你像打理花园一样偶尔进行修剪和维护。