1. 项目概述为AI智能体构建一个“活”的记忆系统如果你正在开发或使用像OpenClaw、Claude、Cursor这类AI智能体你一定遇到过这个核心痛点对话上下文窗口的限制。无论模型多强大一旦对话轮次超过限制或者你关闭了会话窗口之前讨论过的所有细节、达成的共识、甚至刚刚写好的代码片段都会瞬间“蒸发”。这就像让一个拥有超强学习能力的大脑却只能依赖金鱼般的短期记忆每次交互都得从头开始。这正是openclaw-neo4j-memory这个项目要解决的终极问题。它不是一个简单的日志记录器而是一个为AI智能体量身打造的、基于知识图谱的长期记忆系统。你可以把它想象成AI的“海马体”——大脑中负责将短期记忆转化为长期记忆的关键区域。这个系统能将AI与你的每一次交互无论是代码讨论、问题解答还是创意构思中蕴含的实体、概念和它们之间的关系自动抽取并结构化地存储在图数据库Neo4j中。当下次遇到相关话题时AI能像人类一样“回想”起过去的经历让对话具有连续性和深度。我花了相当长的时间来设计和迭代这套系统核心目标就一个让AI的“记忆”变得可查询、可关联、可进化。它不仅仅是存储文本而是构建一个动态的知识网络。这个网络会通过一个名为“冥思”的后台进程自动优化比如合并重复概念、提炼高阶策略、淘汰无效信息从而让记忆本身也具备“学习”和“成长”的能力。现在通过Docker Compose你可以在2分钟内一键部署包含Neo4j数据库、记忆API服务器和MCP协议网关的完整服务栈让任何兼容的AI智能体即刻获得史诗级的记忆增强。2. 核心架构与设计哲学2.1 为什么是知识图谱而不是向量数据库在构建长期记忆系统时技术选型是首要决策。市面上常见的方案多基于向量数据库如Chroma、Pinecone通过语义相似度来检索记忆。这固然有效但它存在一个根本性缺陷它只能回答“像什么”无法回答“为什么”和“怎么样”。举个例子假设你和AI讨论过一个关于“使用Redis实现分布式锁”的项目。向量检索或许能在你提到“缓存”或“并发控制”时找到这段记忆。但如果你问“我上次提到的那个分布式锁方案是如何解决死锁问题的” 向量检索就力不从心了因为它不理解“方案”、“解决”、“死锁”这些概念之间的逻辑关系。而知识图谱Neo4j的核心优势正在于此——关系是一等公民。它将记忆存储为“节点”实体如“项目A”、“Redis”、“死锁”和“边”关系如“使用”、“解决”、“有风险”。这种结构天然适合表达复杂的、关联性的知识。当AI需要回忆时它不仅可以找到相关的实体还能通过图遍历发现实体之间隐藏的连接路径从而进行更深层次的推理和联想。这更接近人类大脑中神经元网络的工作方式也是我选择Neo4j作为记忆基石的核心理由。2.2 系统核心工作流解析整个系统的运作流程可以概括为“感知-存储-回忆-优化”四个核心环节形成一个闭环。感知与铭刻Ingest当AI智能体如OpenClaw与用户产生对话时系统会自动介入。它利用大语言模型的能力实时从对话文本中抽取关键实体人物、项目、技术、问题和它们之间的关系。这个过程我称之为“铭刻”。例如对话中出现“我在项目A里用Docker部署了PostgreSQL”系统会抽取出[项目A] -[使用]- [Docker][项目A] -[部署]- [PostgreSQL]这样的三元组并立刻存入Neo4j图谱。为了保证写入的可靠性每次“铭刻”后都有一个即时验证步骤确保数据确实持久化了避免了“以为记住了实则丢失”的尴尬情况。关联与寻路Search当新的对话触发时AI会先向记忆系统发起查询。系统并非简单返回相似的文本片段而是执行一次“子图检索”。它会以当前对话中的核心实体为起点在知识图谱中进行有限深度的遍历找出所有与之直接或间接关联的节点和关系将这一小片关联紧密的知识子图返回。这样AI获得的是一组有上下文、有关联的记忆簇而不是孤立的碎片。近期我还为检索系统增加了混合检索Hybrid Search能力即结合图遍历的结果和传统向量相似度检索的结果取长补短确保召回的记忆既有关联性又有语义相关性大幅降低了遗漏关键记忆的概率。自省与进化Meditation这是让记忆“活”起来的关键。记忆系统不会只进不出那样很快就会变得臃肿不堪。我设计了一个名为“冥思”的异步后台进程。它像大脑在睡眠时的记忆整理过程定期或在特定条件下触发执行一系列优化操作剪枝与合并识别并合并表示相同概念的不同节点例如“Docker”和“docker”删除长期未被访问的孤立记忆。重标注利用LLM对已有的关系进行复审可能将模糊的“相关”关系细化为更精确的“依赖”、“替代”或“引发”关系。策略蒸馏这是更高级的功能。系统会分析图谱中的因果链例如一连串“遇到错误B”-“尝试方案C”-“最终解决”的事件序列从中抽象出可复用的高阶策略或经验法则并作为一个新的“策略”节点存入图中。未来AI遇到类似问题时可以直接调用这些策略而无需重新推理全过程。自然选择系统会评估不同策略节点的“适应度”例如被成功调用的次数逐渐淘汰低效或过时的策略实现记忆内容的优胜劣汰。2.3 分层记忆模型从碎片到智慧为了更精细地管理记忆我借鉴了认知科学中的理论引入了五层记忆模型。这就像把记忆从临时便签到图书馆藏书进行了分类管理记忆层级类比存储内容存活时间例子L1临时记忆便签纸当前会话的上下文、未决意图分钟级“用户刚才问了Python版本我回答了3.9”L2事实记忆个人日记具体的对话事实、代码片段、结论天至周“2023年10月5日用户决定在项目A中使用FastAPI框架”L3偏好记忆个人档案用户的习惯、偏好、常用工具月级“用户喜欢用black格式化代码讨厌过多的注释”L4任务记忆项目蓝图完成的任务步骤、项目结构、解决方案长期“部署一个Django应用的完整步骤清单”L5推理记忆哲学书籍蒸馏出的策略、抽象原则、因果模型永久“遇到数据库连接池报错优先检查最大连接数和空闲超时设置”系统在“铭刻”时会根据内容的性质自动或半自动地为其打上层级标签。不同层级的记忆在“寻路”检索和“冥思”优化时权重和策略也不同。例如L1记忆很快会被清理而L5记忆则会被重点保护和反复提炼。这种分层设计让记忆系统不仅能记住“发生了什么”还能逐渐积累“如何思考”的智慧。3. 从零到一的完整部署与集成指南3.1 环境准备与一键部署部署是整个体验中最流畅的部分这得益于完整的容器化封装。你只需要确保本地有Docker和Docker Compose环境。注意在运行任何命令前请务必使用docker --version和docker compose version确认命令行工具可用。如果不可用请先安装Docker Desktop或相应的Docker Engine。部署过程简单到只有四条命令# 1. 克隆项目代码到本地 git clone https://github.com/Garylauchina/openclaw-neo4j-memory.git cd openclaw-neo4j-memory # 2. 复制并配置环境变量文件 cp .env.example .env接下来用你喜欢的文本编辑器打开.env文件。这里最关键的是配置LLM的API因为实体抽取、冥思优化等核心功能都需要大语言模型的驱动。# .env 文件示例 # LLM配置支持任何OpenAI兼容的API如OpenAI, Azure OpenAI, 或本地部署的模型 OPENAI_API_KEYsk-你的真实api-key OPENAI_API_BASEhttps://api.openai.com/v1 # 如果是其他服务商请修改此处 OPENAI_MODELgpt-4o-mini # 根据你的需求选择模型平衡成本与效果 # Neo4j数据库配置通常无需修改除非你已有外部Neo4j实例 NEO4J_URIbolt://neo4j:7687 NEO4J_USERneo4j NEO4J_PASSWORDyour_secure_password_here # 强烈建议修改为一个强密码 # 服务端口配置 MEMORY_API_PORT18900 MCP_SERVER_PORT8000配置完成后一键启动所有服务# 3. 启动所有服务Neo4j, 记忆API, MCP Server make start # 或者使用 docker compose up -d等待片刻三个核心服务就会在后台运行起来。你可以用以下命令快速验证服务是否健康# 4. 验证服务状态 make status # 查看容器运行状态 curl http://localhost:18900/health # 记忆API健康检查应返回 {status:ok} curl http://localhost:8000/docs # 访问MCP Server的交互式API文档Swagger UI如果一切顺利你的AI记忆中枢就已经在本地localhost上准备就绪了。整个部署过程对网络和系统资源的要求极低2分钟内完成绝非虚言。3.2 与AI智能体深度集成以OpenClaw为例部署好记忆服务只是第一步更重要的是让你的AI智能体学会使用它。这里我以OpenClaw为例展示如何将其从一个“失忆者”变成“记忆大师”。OpenClaw通过插件机制加载外部能力。你需要将本项目的插件目录挂载或复制到OpenClaw的插件路径下。通常这涉及到修改OpenClaw的配置文件如config.toml或通过环境变量设置。# 在OpenClaw的配置中添加或修改插件路径 [plugins] paths [ /path/to/your/openclaw-neo4j-memory/plugins/neo4j-memory, # ... 其他插件路径 ]重启OpenClaw后它就能感知到记忆插件的存在。插件内部定义了几个关键的“技能”Skills自动铭刻在对话中自动分析并保存知识到图谱。自动寻路在生成回复前自动查询相关记忆并注入上下文。手动记忆操作提供命令让用户主动保存或查询记忆。一个典型的使用场景是开发对话。当你对OpenClaw说“我们之前讨论过的那个用户认证微服务它的数据库Schema是怎么设计的” 在没有记忆系统时AI要么要求你重新描述要么给出一个通用答案。但现在集成后的工作流如下OpenClaw接收到问题识别出核心实体“用户认证微服务”、“数据库Schema”。它自动调用记忆插件的search技能将这些实体作为查询种子。记忆API在Neo4j图谱中查找与这些实体相关的节点和关系可能返回一个包含“项目X”、“使用”、“JWT”、“表结构”等节点的子图。这个子图被作为上下文连同你的问题一起送入LLM。LLM基于这个具体的、历史相关的上下文生成精准的回复“根据我们上周二的记录那个基于Spring Boot的认证服务使用了users和auth_tokens两张表users表包含username唯一索引、hashed_password和email字段...”至此AI表现出了真正的“连续性”体验有了质的飞跃。3.3 通过MCP协议实现通用连接也许你使用的不是OpenClaw而是其他支持模型上下文协议Model Context Protocol, MCP的客户端比如Claude Desktop、Cursor或Windsurf。这正是本项目设计MCP Server的初衷——打破壁垒实现记忆服务的通用化。MCP是一种新兴的协议允许AI客户端以标准化的方式发现和调用外部工具、数据源。本项目内置的MCP Server提供了5个标准工具任何兼容的客户端都可以直接连接并使用。启动MCP Server后一键部署中已包含你需要在你的AI客户端配置中指向它。以Claude Desktop为例你需要编辑其配置文件通常在~/Library/Application Support/Claude/claude_desktop_config.json或类似位置{ mcpServers: { neo4j-memory: { command: python, args: [ /绝对路径/to/openclaw-neo4j-memory/mcp_server.py ], env: { MEMORY_API_URL: http://localhost:18900 } } } }配置完成后重启Claude Desktop你就可以在对话中直接使用记忆功能了。例如你可以说“/search_memory 查询所有关于‘Docker优化’的记忆”或者“/ingest_memory 将当前对话的要点保存到长期记忆”。这相当于为所有主流AI助手装备了一个统一的外接大脑。4. 高级功能与运维管理实战4.1 “冥思”进程的配置与监控“冥思”是系统保持健康的核心但它也是一个资源尤其是LLM API调用消耗者。因此合理配置至关重要。相关配置主要在.env和环境变量中。# .env 中关于冥思的配置示例 MEDITATION_ENABLEDtrue # 触发冥思的时机cron表达式定时或基于事件如记忆数量阈值 MEDITATION_TRIGGER_CRON0 2 * * * # 每天凌晨2点执行 MEDITATION_EVENT_THRESHOLD100 # 当新增记忆达到100条时触发 # 成本控制与降级策略防止意外消耗 MAX_TOKENS_PER_MEDITATION20000 # 单次冥思最大token消耗 DAILY_MEDITATION_BUDGET100000 # 每日冥思总预算 LLM_MODEL_FALLBACKgpt-3.5-turbo # 当预算超支或主模型不可用时降级使用的模型启动后你可以通过API监控冥思的状态curl http://localhost:18900/meditation/status返回的JSON会包含当前是否正在冥思、上次冥思的时间、消耗的token数以及提炼出的策略数量等信息。实操心得对于个人或小团队使用建议将冥思设置为夜间定时执行如上述的0 2 * * *并设置一个合理的每日预算。初期可以调高MEDITATION_EVENT_THRESHOLD先让系统积累一定量的原始记忆再开始优化。密切观察日志中冥思提炼出的“策略”这是衡量系统是否真正在“学习”的关键指标。4.2 数据备份、迁移与恢复策略记忆数据是核心资产Neo4j的数据持久化在Docker卷中。定期备份是必须的。手动备份# 进入项目目录 cd openclaw-neo4j-memory # 执行备份命令数据将打包到 ./backups/ 目录下以时间戳命名 make backup这个命令本质上是在调用docker exec执行Neo4j的neo4j-admin dump命令生成一个.dump文件。你应该将这个备份文件同步到云存储或其他安全位置。从备份恢复 如果遇到数据损坏或需要迁移到新机器恢复同样简单。首先确保新的环境中Neo4j容器是停止状态然后将备份文件放入./backups/目录并运行# 假设备份文件名为 neo4j-20231005.dump make restore fileneo4j-20231005.dump跨环境迁移 项目还提供了一个更强大的迁移工具用于从远程已有的Neo4j实例例如AuraDB云服务或公司内网的Neo4j迁移数据到本地容器。在.env中配置源数据库信息SOURCE_NEO4J_URIbolt://remote-neo4j-host:7687 SOURCE_NEO4J_USERneo4j SOURCE_NEO4J_PASSWORDsource_password运行迁移命令make migrate这个脚本会通过Cypher查询分批读取源数据库的数据并插入到本地库中适用于中等规模数据的迁移。4.3 性能调优与问题排查随着记忆条目增长到数万甚至数十万性能可能会成为关注点。以下是一些实战调优技巧1. Neo4j索引优化 记忆系统会自动在常用的实体属性如name,type上创建索引。但你如果有自己的特定查询模式可以手动优化。通过Neo4j Browser (http://localhost:7474) 登录执行-- 查看现有索引 SHOW INDEXES; -- 如果经常按记忆的创建时间范围查询可以添加索引 CREATE INDEX ON :Memory(created_at);2. 搜索查询调优 记忆检索的深度和宽度会影响速度和结果相关性。默认的子图检索深度是2即朋友的朋友。你可以在调用搜索API时通过参数调整curl -X POST http://localhost:18900/search \ -H Content-Type: application/json \ -d { query: Docker部署, max_depth: 3, // 增加遍历深度获取更广泛的关联 limit: 15 // 限制返回的节点数量 }深度越大查询越慢但关联可能更丰富。需要根据实际场景权衡。3. 常见问题排查清单现象可能原因排查步骤记忆API (/health) 不可用1. 容器未启动2. 端口冲突docker ps查看容器状态netstat -tuln | grep 18900检查端口占用冥思进程从未触发1. 配置未启用2. Cron表达式错误3. 事件阈值未达到检查.env中MEDITATION_ENABLED查看logs/meditation.log确认新增记忆量搜索返回结果为空1. 图谱中尚无相关记忆2. 实体抽取失败3. 查询词太模糊通过Neo4j Browser查看图谱数据检查API日志中ingest步骤的LLM调用是否成功尝试更具体的关键词LLM API调用超频或失败1. 网络问题2. API Key失效或额度不足3. 请求速率超限检查.env中的API配置查看OpenAI控制台用量在代码中增加请求重试和退避机制当遇到问题时第一时间的诊断命令是make logs它可以聚合查看所有容器的实时日志非常方便。5. 扩展开发与二次构建指南5.1 理解代码结构与核心模块如果你不满足于开箱即用的功能想要定制或扩展那么理解项目代码结构是第一步。核心逻辑主要集中在meditation_memory/目录下。openclaw-neo4j-memory/ ├── meditation_memory/ # 核心记忆处理包 │ ├── __init__.py │ ├── entity_extractor.py # 核心利用LLM从文本抽取实体关系 │ ├── graph_store.py # 核心Neo4j的CRUD操作封装 │ ├── subgraph_retrieval.py # 核心基于Cypher的智能检索 │ ├── meditation_scheduler.py # 冥思任务的调度与执行 │ └── meditation/ # 冥思的具体步骤实现 │ ├── base.py │ ├── prune.py # 剪枝 │ ├── merge.py # 合并 │ ├── relabel.py # 重标注 │ └── distill.py # 策略蒸馏 ├── cognitive_engine/ # 实验性更高级的认知层如元认知反馈 ├── plugins/neo4j-memory/ # OpenClaw插件实现 ├── mcp_server.py # MCP协议服务器 └── memory_api_server.py # FastAPI主应用提供REST API实体抽取器 (entity_extractor.py)是系统的感官。它接收一段文本调用LLM要求其按照预定义的格式通常是JSON输出识别出的实体和关系。这里的提示词工程非常关键直接决定了抽取质量。当前的提示词倾向于保守和精确如果你在处理特定领域如法律、医疗的文本可以调整提示词以识别该领域的专业实体。图存储 (graph_store.py)是与Neo4j交互的桥梁。它负责将三元组转换为Cypher查询语句并处理事务。如果你需要支持其他图数据库如JanusGraph、Nebula Graph理论上可以在此实现新的存储后端但需要重写Cypher查询部分。子图检索 (subgraph_retrieval.py)是系统的大脑皮层。它的算法决定了回忆的“智能”程度。当前的实现是基于多起点双向广度优先搜索并加入了简单的权重计算。你可以在这里尝试更复杂的图算法比如Personalized PageRank来寻找中心节点或者结合社区发现算法来聚类相关记忆。5.2 添加一个新的“冥思”步骤“冥思”框架是插件化的添加一个新的优化步骤相对简单。假设我们想添加一个“情感分析”步骤为记忆节点打上情感倾向标签。创建新步骤文件在meditation_memory/meditation/目录下创建sentiment.py。实现步骤类# meditation_memory/meditation/sentiment.py from .base import MeditationStep from ..llm_client import llm_client # 假设有统一的LLM客户端 import logging logger logging.getLogger(__name__) class SentimentAnalysisStep(MeditationStep): 为记忆节点分析并打上情感标签积极/消极/中性。 name sentiment_analysis description 分析记忆内容的情感倾向 async def execute(self, graph_store, context): 执行步骤的核心逻辑 # 1. 从上下文中获取需要处理的记忆节点例如最近新增的文本记忆 # context 中包含了本次冥思的上下文信息如上次执行后的状态 recent_memories await self._get_recent_text_memories(graph_store) if not recent_memories: logger.info(未找到需要情感分析的文本记忆。) return {processed: 0} processed_count 0 # 2. 批量或逐个调用LLM进行情感分析 for memory in recent_memories: content memory.get(content) if not content: continue prompt f 请分析以下文本的情感倾向。只返回一个词积极、消极或中性。 文本{content} try: sentiment await llm_client.complete(prompt, max_tokens5) sentiment sentiment.strip().lower() # 3. 将情感标签作为属性更新到图节点中 cypher MATCH (m:Memory {id: $memory_id}) SET m.sentiment $sentiment, m.updated_at timestamp() await graph_store.execute_write(cypher, { memory_id: memory[id], sentiment: sentiment }) processed_count 1 except Exception as e: logger.error(f分析记忆 {memory[id]} 情感时出错: {e}) continue logger.info(f情感分析步骤完成处理了 {processed_count} 条记忆。) # 4. 返回结果供后续步骤或日志记录使用 return {processed: processed_count} async def _get_recent_text_memories(self, graph_store): 一个辅助方法用于获取需要处理的记忆节点 cypher MATCH (m:Memory) WHERE m.content IS NOT NULL AND m.sentiment IS NULL RETURN m.id as id, m.content as content LIMIT 50 // 限制单次处理数量避免超时 results await graph_store.execute_read(cypher) return results注册新步骤在meditation_memory/meditation_scheduler.py中找到冥思流水线的定义处通常是DEFAULT_MEDITATION_PIPELINE列表将你的新步骤添加进去并决定其执行顺序。# meditation_scheduler.py 某处 from .meditation.sentiment import SentimentAnalysisStep DEFAULT_MEDITATION_PIPELINE [ PruneStep(), # 先剪枝 MergeStep(), # 再合并 SentimentAnalysisStep(), # 然后情感分析 RelabelStep(), # 接着重标注 DistillStep(), # 最后策略蒸馏 ]测试触发一次冥思可以通过API调用POST /meditation/start然后观察日志和数据库检查情感标签是否被正确添加。通过这种方式你可以无限扩展冥思的能力比如添加知识验证、矛盾检测、自动摘要等让记忆系统越来越智能。5.3 构建属于自己的记忆体定制化建议这个项目提供了一个强大的框架但最好的记忆系统一定是为你量身定制的。以下是一些定制化方向领域适配如果你主要用AI讨论法律、金融或医学等专业领域可以修改entity_extractor.py中的提示词并定义领域专用的实体类型和关系类型如[法律条文] -[引用]- [判例]。隐私与安全加固默认部署使用本地Neo4j数据在本地。但如果涉及敏感信息可以考虑启用Neo4j的加密连接。在记忆API前增加一层认证如JWT。对存入图谱的文本内容进行脱敏处理在ingest步骤前加入一个脱敏过滤器。多智能体协作记忆当前的记忆图谱是“单用户”视角。你可以扩展数据模型在节点上增加agent_id或user_id属性从而让多个AI智能体或用户共享同一个知识图谱但又可以隔离或共享特定记忆实现真正的多智能体协作学习。与现有工具链集成除了通过MCP你还可以将记忆API集成到你的CI/CD流程中。例如每次代码合并请求Pull Request的描述和评论可以被自动铭刻形成项目决策的知识库或者将生产环境的事故报告自动录入图谱方便后续故障排查时快速关联历史案例。这个项目的终极目标是成为AI智能体在数字世界中安身立命的“记忆宫殿”。它从解决上下文遗忘这个具体痛点出发但它的架构设计指向了一个更宏大的可能性一个可以持续学习、不断进化、并且能被多个智能体共享和协作的集体外脑。部署和使用它不仅仅是给AI加了一个功能更像是为它点燃了意识进化的第一簇火种。