使用说明

项目简介

'mcp-neo4j-agent-memory' 是一个专用的MCP服务器，它将强大的Neo4j图数据库与AI代理无缝连接。通过一套精心设计的记忆管理工具，该服务器使AI代理能够以结构化的方式存储、回忆和关联各种信息，从而构建一个动态的知识图谱。这为LLM客户端提供了丰富、持久且上下文感知的记忆服务，支持更智能、更具深度的AI交互。服务器通过JSON-RPC协议与LLM客户端通信，提供标准化的上下文服务框架。

主要功能点

持久化记忆存储: 确保AI代理的记忆在不同会话和时间点之间得以保留和检索。
语义关系构建: 允许AI代理创建记忆之间有意义的连接，例如“X认识Y”、“A工作于B”或“C创建了D”，从而形成一个丰富的知识图谱。
智能检索: 提供自然语言搜索功能，LLM可以在所有记忆属性和关系中进行灵活查询，获取所需信息。
灵活标签系统: 支持使用任何自定义标签（如“人物”、“地点”、“项目”、“想法”等）来分类和组织记忆，提高数据管理的自由度。
时间追踪能力: 自动为记忆添加创建时间戳，并支持基于日期的查询，以便追溯信息的历史。
图谱探索: 允许LLM遍历记忆之间的关系，发现隐藏的关联和更深层次的知识。
LLM优化工具: 提供简洁、原子化的工具，将复杂的逻辑推理交给LLM处理，从而实现最大化的灵活性和适应性。
内置指导: 提供关于如何有效使用记忆工具的详细指南，包括最佳实践、标签和关系类型的建议。

安装步骤

安装Node.js: 确保您的系统已安装Node.js v18或更高版本，这是运行此MCP服务器的基础环境。您可以从 nodejs.org 下载安装。
安装Neo4j数据库:
- 下载并安装Neo4j Community 或 Enterprise Edition (v4.4+ 或 v5.x) 从 neo4j.com/download。
- 或者，您可以使用Docker快速启动一个Neo4j实例：
```
docker run -p 7474:7474 -p 7687:7687 -e NEO4J_AUTH=neo4j/your-password neo4j
```
  重要： 请将 'your-password' 替换为您为Neo4j设置的实际密码。

安装MCP服务器:

快速启动 (推荐): 您可以使用 'npx' 命令直接运行此MCP服务器：

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

集成到Claude Desktop: 如果您使用Claude Desktop作为MCP客户端，可以通过Smithery CLI自动安装和配置：

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

开发安装 (可选): 如果您需要进行开发或希望从源代码运行，请克隆仓库并手动构建：

git clone https://github.com/KnowAll-AI/mcp-neo4j-agent-memory.git
cd mcp-neo4j-agent-memory
npm install
npm run build

服务器配置

此MCP服务器需要配置Neo4j数据库的连接信息。这些信息通常通过环境变量提供，或者在您的MCP客户端（如Claude Desktop）的配置文件中直接指定。

以下是Claude Desktop的配置文件 ('settings.json' 或类似文件) 中添加此MCP服务器的示例配置。请根据您的实际环境修改相应的值：

{
  "mcpServers": {
    "neo4j-memory": {
      "command": "npx",                             // 启动MCP服务器的命令
      "args": ["@knowall-ai/mcp-neo4j-agent-memory"], // 传递给命令的参数，这里是包名
      "env": {
        "NEO4J_URI": "bolt://localhost:7687",     // Neo4j数据库的连接URI (例如: bolt://<您的Neo4j主机>:<端口>)
        "NEO4J_USERNAME": "neo4j",                // 连接Neo4j数据库的用户名 (通常为 "neo4j")
        "NEO4J_PASSWORD": "your-password",        // 连接Neo4j数据库的密码 (请替换为您在Neo4j中设置的密码)
        "NEO4J_DATABASE": "neo4j"                 // (可选) Neo4j数据库的名称 (企业版多数据库时使用，社区版默认为 "neo4j")
      }
    }
  }
}

请务必将 '"your-password"' 替换为您的Neo4j数据库密码。 如果您的Neo4j实例在不同的主机或端口上运行，也请相应地调整 'NEO4J_URI'。

基本使用方法

当MCP服务器成功运行并连接到LLM客户端后，LLM将能够利用其提供的工具进行智能记忆管理。以下是一些LLM与该服务器交互的示例场景：

存储新信息:
- 用户对LLM说：“请记住，John在Google担任软件工程师。”
- LLM内部操作: LLM会首先调用 'search_memories' 查找“John”和“Google”是否存在。如果不存在，它会使用 'create_memory' 工具分别创建“John”（类型：person）和“Google”（类型：organization）的记忆。随后，LLM会调用 'create_connection' 工具创建一条“John-[WORKS_AT]->Google”的关系，并添加如“role: Software Engineer”等属性。
检索已知信息:
- 用户对LLM提问：“你对John有什么记忆？”
- LLM内部操作: LLM会调用 'search_memories({"query": "John", "depth": 2})' 工具。'depth: 2' 表示不仅查找John的直接信息，还会探索与John有两层关系的其他记忆（例如，John工作的公司和他的同事）。
更新和管理记忆:
- 用户对LLM说：“John现在是Google的首席工程师了。”
- LLM内部操作: LLM会先通过 'search_memories' 找到John的记忆ID，然后使用 'update_memory' 工具更新John记忆中的“occupation”属性为“Lead Engineer”。如果还需要更新John与Google之间关系（WORKS_AT）的属性（例如，添加“promoted_date”），LLM将调用 'update_connection' 工具。
获取使用指南:
- 用户对LLM说：“给我一些关于如何有效使用记忆工具的建议。”
- LLM内部操作: LLM会调用 'get_guidance({"topic": "best-practices"})' 或不带参数调用 'get_guidance({})' 以获取全面的使用指南。

通过这种方式，LLM能够完全自主地管理其与Neo4j数据库连接的知识图谱，实现更灵活、更智能的记忆和上下文管理。

关键词