shield_lock
JinDaGe
← Back to MCP directory
publicPublicdnsLocal runtime

mcp-neo4j-agent-memory

一个专为AI代理设计的MCP服务器，将Neo4j图数据库与智能代理连接，提供基于知识图谱的记忆存储、检索和关联功能。

article

README

🚀 Neo4j Agent Memory MCP Server

这是一个专门的MCP服务器，它将Neo4j图数据库与AI智能体连接起来，提供专注于记忆的工具，用于在知识图谱中存储、检索和关联信息。

🚀 快速开始

你可以直接使用npx运行这个MCP服务器：

npx @knowall-ai/mcp-neo4j-agent-memory

或者将其添加到你的Claude桌面配置中：

{
  "mcpServers": {
    "neo4j-memory": {
      "command": "npx",
      "args": ["@knowall-ai/mcp-neo4j-agent-memory"],
      "env": {
        "NEO4J_URI": "bolt://localhost:7687",
        "NEO4J_USERNAME": "neo4j",
        "NEO4J_PASSWORD": "your-password",
        "NEO4J_DATABASE": "neo4j"
      }
    }
  }
}

✨ 主要特性

  • 🧠 持久化记忆存储 - 在不同对话中存储和检索记忆
  • 🔗 语义关系 - 在记忆之间创建有意义的连接（如KNOWS、WORKS_AT、CREATED等）
  • 🔍 智能搜索 - 对所有记忆属性和关系进行自然语言搜索
  • 🏷️ 灵活标签 - 为记忆使用任意标签（如人、地点、项目、想法等）
  • ⏰ 时间跟踪 - 自动添加时间戳并支持基于日期的查询
  • 🌐 图探索 - 遍历关系以发现关联信息
  • 🎯 上下文感知 - 深度搜索以包含相关记忆
  • 🔧 大语言模型优化 - 提供简单工具，让AI处理复杂逻辑
  • 🏢 企业级支持 - 支持多个Neo4j数据库
  • 📚 内置指南 - 获取最佳实践和使用模式的帮助

📦 安装指南

通过Smithery安装

smithery徽章

要通过Smithery自动为Claude桌面安装Neo4j Agent Memory MCP服务器，请执行以下命令：

npx -y @smithery/cli install @knowall-ai/mcp-neo4j-agent-memory --client claude

开发环境安装

  1. 克隆仓库：
git clone https://github.com/KnowAll-AI/mcp-neo4j-agent-memory.git
cd mcp-neo4j-agent-memory
  1. 安装依赖：
npm install
  1. 构建项目：
npm run build

💻 使用示例

基础用法

大语言模型（LLM）负责处理决定存储内容和关联记忆的所有复杂逻辑：

存储信息

用户：“记住约翰是谷歌的软件工程师”

助手：我会记住约翰是谷歌的软件工程师。

[幕后，LLM执行以下操作：
1. search_memories({"query": "约翰"}) - 检查约翰是否存在
2. search_memories({"query": "谷歌"}) - 检查谷歌是否存在
3. create_memory({"label": "人", "properties": {"name": "约翰", "occupation": "软件工程师"}})
4. create_memory({"label": "组织", "properties": {"name": "谷歌"}})
5. create_connection({"fromMemoryId": 123, "toMemoryId": 456, "type": "WORKS_AT"})]

用户：“记住莎拉是约翰的经理，她于2019年开始任职”

助手：我会添加关于莎拉的信息。

[LLM搜索约翰，创建莎拉，并使用MANAGES关系将他们关联起来，同时包含开始日期]

检索信息

用户：“谁在谷歌工作？”

助手：让我搜索在谷歌工作的人。

[LLM使用：search_memories({"query": "谷歌", "depth": 2})]

根据我的记忆：
- 约翰 - 谷歌软件工程师
- 莎拉 - 谷歌经理（管理约翰，2019年开始任职）

用户：“关于约翰你记得什么？”

助手：这是我关于约翰的信息：

[LLM使用：search_memories({"query": "约翰", "depth": 2})]

- 在谷歌担任软件工程师
- 莎拉是他的经理
- [搜索中找到的任何其他关联记忆]

建立关系

用户：“约翰和莎拉正在一起参与阿特拉斯项目”

助手：我会将约翰和莎拉与阿特拉斯项目关联起来。

[LLM执行以下操作：
1. 搜索约翰和莎拉以获取他们的ID
2. 创建阿特拉斯项目：create_memory({"label": "项目", "properties": {"name": "阿特拉斯项目"}})
3. 关联他们：create_connection({"fromMemoryId": johnId, "toMemoryId": projectId, "type": "WORKS_ON"})
4. create_connection({"fromMemoryId": sarahId, "toMemoryId": projectId, "type": "WORKS_ON"})]

高级用法

连接到特定数据库

对于使用多个数据库的Neo4j企业版用户，你可以指定要连接的数据库：

{
  "env": {
    "NEO4J_URI": "bolt://localhost:7687",
    "NEO4J_USERNAME": "neo4j",
    "NEO4J_PASSWORD": "your-password",
    "NEO4J_DATABASE": "myCustomDatabase"
  }
}

这将连接到“myCustomDatabase”而不是默认的“neo4j”数据库。

更复杂的示例

查找相关信息
用户：“显示销售部门的所有员工”

助手：让我搜索销售部门的员工。

[LLM使用：search_memories({"query": "销售部门", "depth": 2})]

我找到了销售部门的这些员工：
- 约翰·史密斯（销售经理）
- 莎拉·约翰逊（销售代表）  
- 迈克·布朗（客户经理）
创建特定领域的记忆
用户：“创建一个名为‘高级咖啡’的产品，价格为24.99美元”

助手：我会为你创建该产品。

[LLM使用：create_memory({"label": "产品", "properties": {"name": "高级咖啡", "price": 24.99}})]

创建了ID为456的高级咖啡产品
管理关系
用户：“高级咖啡使用我们哥伦比亚供应商的咖啡豆”

助手：我会将高级咖啡与哥伦比亚供应商关联起来。

[LLM执行以下操作：
1. search_memories({"query": "高级咖啡"})
2. search_memories({"query": "哥伦比亚供应商"})
3. create_connection({"fromMemoryId": 456, "toMemoryId": 789, "type": "SUPPLIED_BY"})]

已将高级咖啡与哥伦比亚供应商关联起来

高级查询

LLM可以通过智能使用搜索工具处理复杂查询：

基于单词的搜索
用户：“查找本·威克斯”

助手：我会搜索包含“本”或“威克斯”的记忆。

[LLM使用：search_memories({"query": "本·威克斯"})]

我找到了几个与你搜索匹配的人：
- 本·威克斯 - 科技公司的软件工程师（精确匹配）
- 莎拉·本 - 数据公司的数据科学家（包含“本”）
- 约翰·威克斯 - 项目经理（包含“威克斯”）

最可能的匹配似乎是软件工程师本·威克斯。
最近7天的记忆
用户：“我上周结识了哪些新人？”

助手：我会搜索过去7天添加到你记忆中的人。

[LLM计算7天前的日期并使用： 
search_memories({
  "query": "", 
  "label": "人", 
  "since_date": "2024-01-20T00:00:00Z",
  "order_by": "created_at DESC"
})]

以下是你上周结识的新人：
- 莎拉·陈 - 周一在科技会议上结识
- 迈克尔·罗伯茨博士 - 新医生，周二首次预约  
- 艾玛·威尔逊 - 周三加入你的项目团队
- 詹姆斯·帕克 - 周四喝咖啡讨论潜在合作
消除歧义
用户：“约翰是做什么的？”

助手：我找到了多个名为约翰的人。让我告诉你我所知道的：

[LLM使用：search_memories({"query": "约翰", "type": "人", "depth": 1})]

1. 约翰· Doe - 谷歌软件工程师
2. 约翰·史密斯 - 销售部门的销售经理
3. 约翰·布朗 - 阿特拉斯项目的项目经理

你问的是哪个约翰？
时间查询
用户：“我上个月参加了哪些活动？”

助手：我会搜索活动记忆并检查它们的日期。

[LLM使用：search_memories({"query": "", "label": "活动", "sort_by": "created_at", "sort_order": "desc"})]

[根据created_at或date属性过滤结果到上个月]

以下是你上个月参加的活动：
- 科技创新峰会（3月5 - 6日） - 主旨演讲者
- 团队建设研讨会（3月12日） - 与工程团队一起
- 客户晚宴会议（3月18日） - 与ABC公司的项目启动会
- 网络开发会议（3月25 - 27日） - 参加了5场关于React的会议

灵活的记忆类型

系统不强制使用严格的类型 - 你可以创建任何有意义的记忆类型： 常见类型（小写）：人、地点、组织、项目、活动、主题、对象、动物、植物、食物、活动、媒体、技能、文档、会议、任务、习惯、健康、车辆、工具、想法、目标 但你可以使用任何类型（小写）：食谱、梦想、记忆、名言、书籍、电影、情感、关系、约会、药物、锻炼、症状、付款、合同等 LLM会在适当的时候智能重用现有类型以保持一致性。

连接的力量

这个记忆系统的真正价值不仅在于存储单个记忆，还在于在它们之间创建连接。随着你建立关系，知识图谱的实用性会呈指数级增长：

为什么连接很重要

  • 上下文发现：关联的记忆提供了孤立事实无法提供的丰富上下文
  • 关系模式：通过关系分析揭示隐藏的模式和见解
  • 时间理解：跟踪关系随时间的演变
  • 网络效应：每个新连接都会增加现有记忆的价值

建立连接的最佳实践

  1. 存储新信息时始终寻找关系：
不好的做法：只存储“约翰是开发者”
好的做法：存储约翰并将他与他的公司、项目、技能和同事关联起来
  1. 使用具有语义的关系类型：
WORKS_AT、MANAGES、KNOWS、LIVES_IN、CREATED、USES、LEARNED_FROM
  1. 添加关系属性以提供更丰富的上下文：
create_connection({
  "fromMemoryId": 123,
  "toMemoryId": 456, 
  "type": "WORKS_ON",
  "properties": {"role": "负责人", "since": "2023-01", "hours_per_week": 20}
})
  1. 以图的思维思考：检索信息时，使用深度大于1来探索网络：
search_memories({"query": "约翰", "depth": 3})  // 探索最多3跳的关联信息

请记住：没有连接的记忆就像图书馆里没有目录的书 - 它存在，但实用性有限。你关联的记忆越多，知识图谱就越智能和有用。

📚 详细文档

哲学理念：大语言模型驱动的智能

与传统方法将复杂逻辑嵌入工具不同，这个服务器提供简单的原子操作，让大语言模型处理所有智能逻辑：

  • 无隐藏逻辑：工具的功能与描述完全一致 - 没有自动消歧或智能匹配
  • 大语言模型决定一切：实体识别、关系推断和冲突解决
  • 操作透明：每个操作都是明确且可预测的
  • 最大灵活性：大语言模型可以实现任何策略，不受工具限制

搜索行为

search_memories工具使用单词分词：

  • 查询“约翰·史密斯”会找到包含“约翰”或“史密斯”的记忆
  • 这会返回更多结果，让大语言模型选择最相关的结果
  • 对于姓名和多词查询，比精确子字符串匹配更好

这种方法使系统更强大和灵活，因为大语言模型能力的提升直接转化为更好的记忆管理。

Neo4j企业版支持

此服务器现在支持连接到Neo4j企业版中的特定数据库。默认情况下，它连接到“neo4j”数据库，但你可以使用NEO4J_DATABASE环境变量指定不同的数据库。

记忆工具

  • search_memories：从知识图谱中搜索和检索记忆
    • 基于单词的搜索：搜索查询中的任何单词（例如，“本·威克斯”会找到包含“本”或“威克斯”的记忆）
    • 对所有记忆属性进行自然语言搜索（或留空以获取所有记忆）
    • 按记忆类型过滤（人、地点、项目等）
    • 使用since_date参数按日期过滤（ISO格式）
    • 控制关系深度和结果限制
    • 按任何字段排序（创建时间、名称等）
  • create_memory：在知识图谱中创建新记忆
    • 灵活的类型系统 - 使用任何小写标签（人、地点、项目、技能等）
    • 以键值对形式存储任何属性
    • 自动添加时间戳以进行时间跟踪
  • create_connection：在记忆之间创建关系
    • 使用语义关系类型（KNOWS、WORKS_AT、LIVES_IN等）关联记忆
    • 为关系添加属性（自何时、角色、状态等）
    • 构建复杂的知识网络
  • update_memory：更新现有记忆的属性
    • 添加或修改任何属性
    • 将属性设置为null以删除它们
  • update_connection：更新关系属性
    • 修改关系元数据
    • 跟踪随时间的变化
  • delete_memory：删除记忆及其所有连接
    • 谨慎使用 - 永久删除
    • 自动删除所有关系
  • delete_connection：删除特定关系
    • 精确删除关系
    • 保留记忆不变
  • list_memory_labels：列出所有使用的唯一记忆标签
    • 显示所有标签及其计数
    • 有助于保持一致性
    • 防止标签重复变化
  • get_guidance：获取有效使用记忆工具的帮助
    • 主题：标签、关系、最佳实践、示例
    • 为大语言模型返回全面的指南
    • 在不确定标签/关系命名时使用

配置

环境变量

服务器需要以下环境变量：

  • NEO4J_URI：Neo4j数据库URI（必需，例如bolt://localhost:7687）
  • NEO4J_USERNAME：Neo4j用户名（必需）
  • NEO4J_PASSWORD：Neo4j密码（必需）
  • NEO4J_DATABASE：Neo4j数据库名称（可选） - 用于具有多个数据库的Neo4j企业版

设置环境变量

开发环境

将.env.example复制到.env并使用你的凭证进行更新：

cp .env.example .env
# 使用你的Neo4j凭证编辑.env
Claude桌面

将环境变量添加到你的Claude桌面配置中（见上面的快速开始部分）。

🔧 技术细节

测试

运行测试套件：

npm test

使用MCP Inspector进行交互式测试

要进行交互式测试和调试，请使用MCP Inspector：

# 使用.env中的环境变量快速启动
./run-inspector.sh

# 或者手动指定特定的环境变量
NEO4J_URI=bolt://localhost:7687 \
NEO4J_USERNAME=neo4j \
NEO4J_PASSWORD=your-password \
npx @modelcontextprotocol/inspector build/index.js

Inspector提供了一个Web界面，用于：

  • 交互式测试所有可用工具
  • 查看实时请求/响应数据
  • 验证你的Neo4j连接
  • 调试工具参数和响应

📄 许可证

MIT

help

Runtime guide

cloud

Hosted runtime

Hosted servers run from a provider-managed environment. You usually connect the MCP client to the hosted endpoint or follow the provider's authorization flow, without keeping a local process alive

  1. Open provider connection page
  2. Authorize or copy endpoint
  3. Connect from your MCP client
terminal

Local runtime / other methods

Local servers run on your own machine or infrastructure. You normally copy the server_config into your MCP client, install the required package, and provide env variables from env_schema when needed

  1. Copy server_config
  2. Install required package
  3. Fill env variables and restart client