AI导哈

知识图谱存储服务

为LLM提供跨会话的持久化记忆存储服务，支持知识图谱结构的多后端存储与智能搜索。

  • by n-r-w
  • TypeScript
  • 本地部署
  • 26 星标
  • 更新于
在 GitHub 查看 n-r-w/knowledgegraph-mcp

使用说明

警告

我对这样的自动化上下文管理工具感到失望，因为它几乎不可能控制。过了一段时间，我总是不得不手动清理混乱或纠正不恰当的LLM笔记。 相反，我创建了一个工具，让LLM代理访问动态加载的上下文。但是，上下文本身是用户创建的：https://github.com/n-r-w/agent-standards-mcp

知识图谱MCP服务器

一种在对话中为LLM提供持久内存的简单方法。此服务器允许Claude或vscode使用知识图记住有关您、您的项目和您的偏好的信息。

主要特点：

  • 多个存储后端：PostgreSQL（推荐）或SQLite（本地文件）
  • 项目分离：保持不同项目的隔离（使用提示自动检测）
  • 更好的搜索：使用模糊搜索和分页查找信息

完整安装指南

按照以下步骤操作，以使知识图与Claude一起工作：

步骤1：选择安装方法

选项A:NPX（最简单-无需下载）

# Test that it works
npx knowledgegraph-mcp --help

选项B:Docker

# Clone and build
git clone https://github.com/n-r-w/knowledgegraph-mcp.git
cd knowledgegraph-mcp
docker build -t knowledgegraph-mcp .

第二步：选择数据库

SQLite（默认-无需设置）：

  • 无需安装数据库
  • 在中自动创建的数据库文件 [you home folder]/.knowledge-graph/
  • 非常适合个人使用和大多数场景
  • 这是默认后端

PostgreSQL（适用于高级用户）：

  • 在您的系统上安装PostgreSQL
  • 创建数据库： CREATE DATABASE knowledgegraph;
  • 更适合多个并发用户的生产使用

步骤3：配置客户端

克劳德桌面

编辑您的Claude Desktop配置文件：

查找您的配置文件：

  • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
  • 视窗: %APPDATA%\Claude\claude_desktop_config.json
  • Linux: ~/.config/Claude/claude_desktop_config.json

如果选择NPX+SQLite（默认且最简单）：

{
  "mcpServers": {
    "Knowledge Graph": {
      "command": "npx",
      "args": ["-y", "knowledgegraph-mcp"]
    }
  }
}

备注：SQLite将在中自动创建数据库 [you home folder]/.knowledge-graph/knowledgegraph.db。要使用自定义位置，请添加： "KNOWLEDGEGRAPH_SQLITE_PATH": "/path/to/your/database.db"

如果您选择Docker+SQLite（默认）：

{
  "mcpServers": {
    "Knowledge Graph": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-v", "[you home folder]/.knowledge-graph:/app/.knowledge-graph",
        "knowledgegraph-mcp"
      ]
    }
  }
}

备注：卷挂载可确保您的数据在Docker运行之间保持不变。对于自定义路径，请添加： -e KNOWLEDGEGRAPH_SQLITE_PATH=/app/.knowledge-graph/custom.db

如果你选择PostgreSQL：

{
  "mcpServers": {
    "Knowledge Graph": {
      "command": "npx",
      "args": ["-y", "knowledgegraph-mcp"],
      "env": {
        "KNOWLEDGEGRAPH_STORAGE_TYPE": "postgresql",
        "KNOWLEDGEGRAPH_CONNECTION_STRING": "postgresql://postgres:yourpassword@localhost:5432/knowledgegraph"
      }
    }
  }
}

VS Code

如果您还想将其与VS Code一起使用，请将其添加到您的用户设置（JSON）中或创建 .vscode/mcp.json:

使用NPX+SQLite（默认）：

{
  "mcp": {
    "servers": {
      "Knowledge Graph": {
        "command": "npx",
        "args": ["-y", "knowledgegraph-mcp"],
      }
    }
  }
}

使用Docker（默认SQLite）：

{
  "mcp": {
    "servers": {
      "Knowledge Graph": {
        "command": "docker",
        "args": [
          "run", "-i", "--rm",
          "-e", "KNOWLEDGEGRAPH_CONNECTION_STRING=sqlite://./knowledgegraph.db",
          "knowledgegraph-mcp"
        ]
      }
    }
  }
}

使用Docker+PostgreSQL：

首先，确保你的PostgreSQL数据库已经设置好：

# Create the database (run this once)
psql -h 127.0.0.1 -p 5432 -U postgres -c "CREATE DATABASE knowledgegraph;"

然后配置VS代码：

{
  "mcp": {
    "servers": {
      "Knowledge Graph": {
        "command": "docker",
        "args": [
          "run", "-i", "--rm",
          "--network", "host",
          "-e", "KNOWLEDGEGRAPH_STORAGE_TYPE=postgresql",
          "-e", "KNOWLEDGEGRAPH_CONNECTION_STRING=postgresql://postgres:yourpassword@127.0.0.1:5432/knowledgegraph",
          "knowledgegraph-mcp"
        ]
      }
    }
  }
}

Docker+PostgreSQL的替代方案（如果 --network host 不起作用）：

{
  "mcp": {
    "servers": {
      "Knowledge Graph": {
        "command": "docker",
        "args": [
          "run", "-i", "--rm",
          "--add-host", "host.docker.internal:host-gateway",
          "-e", "KNOWLEDGEGRAPH_STORAGE_TYPE=postgresql",
          "-e", "KNOWLEDGEGRAPH_CONNECTION_STRING=postgresql://postgres:yourpassword@host.docker.internal:5432/knowledgegraph",
          "knowledgegraph-mcp"
        ]
      }
    }
  }
}

重要说明:

  • 替换 yourpassword 使用您的实际PostgreSQL密码
  • 确保 knowledgegraph 启动前数据库已存在
  • 如果您遇到连接错误，请尝试上述替代配置
  • 有关Docker+PostgreSQL问题的疑难解答，请参阅 常见问题 章节

步骤4：选择LLM系统提示

定制：

  • 根据您的域修改实体类型
  • 根据您的数据模式调整搜索策略
  • 添加特定于域的标签和关系类型

LLM兼容性：

  • 所有LLM的行为都不同。对一些人来说，一般的说明就足够了，而另一些人则需要详细描述一切
  • 使用LLM解释为什么它没有使用知识图。问 Explain STEP-BY-STEP why you didn't use the knowledge graph? DO NOT DO ANYTHING ELSE 以获得详细的报告并确定说明中的问题。

可用提示：

步骤5：重新启动克劳德桌面（或VS代码）

关闭并重新打开Claude Desktop。现在，您应该在可用工具中看到“知识图谱”。

步骤6：测试它是否有效

LLM的快速测试命令：

  1. “记住，我更喜欢上午的会议”→ 创建首选项实体
  2. “约翰·史密斯在谷歌担任软件工程师”→ 创建个人+公司+关系
  3. “查找所有在谷歌工作的人”→ 测试搜索和关系
  4. “将上午的会议偏好标记为紧急”→ 测试标签

备注：该服务包括全面的输入验证，以防止错误。如果您遇到任何问题，请检查 故障排除指南 共同的解决方案。

工作原理-LLM电源特性

知识图通过四个相互关联的概念实现了强大的查询：

1.实体-您的知识节点

将人员、项目、公司、技术存储为可搜索的实体。

实例-项目管理：

{
  "name": "Sarah_Chen",
  "entityType": "person",
  "observations": ["Senior React developer", "Leads frontend team", "Available for urgent tasks"],
  "tags": ["developer", "team-lead", "available"]
}

LLM福利： 通过标签搜索立即找到“所有可用的团队线索”。

2.关系-启用发现查询

连接实体以回答复杂的问题，如“谁在做什么？”

真实示例-团队结构：

{
  "from": "Sarah_Chen",
  "to": "Project_Alpha",
  "relationType": "leads"
}

LLM福利： 查询“查找Sarah领导的所有项目”或“谁领导Alpha项目？”

3.观察-原子事实

存储有关实体的特定、可搜索的事实。

真实示例-可操作信息：

  • “可用于紧急任务”→ 查找可用人员
  • “使用React 18.2”→ 寻找具有特定技术的项目
  • “截止日期：2024年3月15日”→ 查找即将到来的截止日期

4.标签-即时过滤

启用即时状态和类别搜索。

实例-项目工作流程：

  • ["urgent", "in-progress", "frontend"] → 查找紧急前端任务
  • ["completed", "bug-fix"] → 跟踪已完成的错误修复
  • ["available", "senior"] → 查找可用的高级职员

配置选项

环境变量

服务器支持多种环境变量进行自定义：

数据库配置

  • KNOWLEDGEGRAPH_STORAGE_TYPE：数据库类型(sqlite 或 postgresql，默认值： sqlite)
  • KNOWLEDGEGRAPH_CONNECTION_STRING：数据库连接字符串
  • KNOWLEDGEGRAPH_SQLITE_PATH：自定义SQLite数据库路径（可选）
  • KNOWLEDGEGRAPH_PROJECT：数据隔离的项目标识符（默认值： knowledgegraph_default_project)

搜索配置

  • KNOWLEDGEGRAPH_SEARCH_MAX_RESULTS：数据库搜索返回的最大结果数（默认值： 100，最大值： 1000)
  • KNOWLEDGEGRAPH_SEARCH_BATCH_SIZE：处理大型查询数组的批处理大小（默认值： 10，最大值： 50)
  • KNOWLEDGEGRAPH_SEARCH_MAX_CLIENT_ENTITIES：客户端搜索要加载的最大实体数（默认值： 10000，最大值： 100000)
  • KNOWLEDGEGRAPH_SEARCH_CLIENT_CHUNK_SIZE：用于在客户端搜索中处理大型数据集的块大小（默认值： 1000，最大值： 10000)

备注：搜索限制会自动验证并限制在安全范围内，以防止性能问题。

性能优化

搜索系统包括几个性能优化：

实体加载限制：

  • KNOWLEDGEGRAPH_SEARCH_MAX_CLIENT_ENTITIES 限制客户端搜索加载的实体数量
  • 防止大型数据集的内存问题
  • 达到限制时记录警告
  • 适用于SQLite和PostgreSQL后端

块状处理：

  • KNOWLEDGEGRAPH_SEARCH_CLIENT_CHUNK_SIZE 控制大型实体集的块大小
  • 当实体计数超过块大小时自动使用
  • 提高内存使用率和搜索性能
  • 通过重复数据删除保持结果准确性

按数据集大小推荐的值：

  • 小型（<1000个实体）：默认值运行良好
  • 中等（1000-10000个实体）：考虑 KNOWLEDGEGRAPH_SEARCH_MAX_CLIENT_ENTITIES=5000, KNOWLEDGEGRAPH_SEARCH_CLIENT_CHUNK_SIZE=500
  • 大型（>10000个实体）：尽可能使用数据库级搜索，或 KNOWLEDGEGRAPH_SEARCH_MAX_CLIENT_ENTITIES=2000, KNOWLEDGEGRAPH_SEARCH_CLIENT_CHUNK_SIZE=200

性能监控：

  • 应用限制时记录警告
  • 自动记录分块以提高透明度
  • 配置验证可防止次优设置

可用工具

服务器提供以下工具来管理您的知识图谱：

数据创建工具

create_entities

创建 知识图中的新实体（人、概念、对象）。

  • 什么时候： 用于尚未存在的实体
  • 约束： 每个实体必须有≥1个非空观察值
  • 行为： 忽略具有现有名称的实体（使用add_observations进行更新）

输入：

  • entities （Entity[]）：实体对象数组。每项要求：
    • name （string）：唯一标识符，非空
    • entityType （string）：类别（例如，“人”、“项目”），非空
    • observations （string[]）：关于实体的事实，必须包含≥1个非空字符串
    • tags （string[]，可选）：用于过滤的精确匹配标签
  • project_id （字符串，可选）：用于隔离数据的项目名称

创建关系

连接 实体，以实现强大的查询和发现。

  • 即时利益： 查找公司的所有人员、使用某项技术的所有项目、所有依赖关系
  • 关键在于： 团队结构、项目依赖关系、技术栈
  • 示例： “John在谷歌工作”，“React依赖于JavaScript”，“Sarah管理的Project Alpha”

输入：

  • relations （Relations[]）：关系对象数组。每项要求：
    • from （string）：源实体名称（必须存在）
    • to （string）：目标实体名称（必须存在）
    • relationType （string）：活动语音中的关系类型（works_at、manages、depends_on、uses）
  • project_id （字符串，可选）：用于隔离数据的项目名称

添加观察结果

加 对现有实体的事实观察。

  • 要求： 目标实体必须存在，每次更新≥1个非空观察值
  • 最佳实践： 保持观察的原子性和特异性

输入：

  • observations （ObservationUpdate[]）：观测更新数组。每项要求：
    • entityName （string）：目标实体名称（必须存在）
    • observations （string[]）：要添加的新事实，必须包含≥1个非空字符串
  • project_id （字符串，可选）：用于隔离数据的项目名称

添加标签

加 用于即时筛选的状态/类别标签。

  • 即时利益： 按状态（紧急、已完成、进行中）或类型（技术、个人）查找实体
  • 必修的： 用于高效的项目管理和快速检索
  • 示例： [“目标”、“完成”、“错误”、“功能”、“个人”]

输入：

  • updates （TagUpdate[]）：标签更新数组。每项要求：
    • entityName （string）：目标实体名称（必须存在）
    • tags （string[]）：要添加的状态/类别标签（精确匹配，区分大小写）
  • project_id （字符串，可选）：用于隔离数据的项目名称

数据检索工具

read_graph

检索 包含所有实体和关系的完整知识图。

  • 用例： 全面概述，了解当前状态，查看所有连接
  • 范围： 返回指定项目中的所有内容

输入：

  • project_id （字符串，可选）：用于隔离数据的项目名称

搜索知识

搜索 通过文本或标签显示实体。 支持多个查询 用于批量搜索。

  • 强制性策略： 1） 首先尝试searchMode='exact'2）如果没有结果，则使用searchMode='模糊'3）如果仍然为空，则将模糊阈值降低到0.1
  • 精确模式： 完美的子字符串匹配（快速、精确）
  • 模糊模式： 相似/拼写错误的术语（较慢、较宽）
  • 标签搜索： 使用exactTags进行精确的类别过滤
  • 多个查询： 使用自动重复数据删除功能在一次调用中搜索多个对象

输入：

  • query （string | string[]，可选）：用于文本搜索的搜索查询。对于多对象搜索，可以是单个字符串或字符串数组。当exactTags仅用于标签搜索时为可选。
  • searchMode （字符串，可选）：“精确”或“模糊”（默认值：“确切”）。仅当精确返回无结果时才使用模糊
  • fuzzyThreshold （数字，可选）：模糊相似性阈值。0.3=默认值，0.1=非常宽泛，0.7=非常严格。值越低，结果越多
  • exactTags （string[]，可选）：用于精确匹配搜索的标签（区分大小写）。用于类别筛选
  • tagMatchMode （string，可选）：对于exactTags：“any”=具有any标签的实体，“all”=具有all标签的实体（默认值：“any”）
  • page （数字，可选）：分页页码（从0开始，默认值：0）
  • pageSize （数字，可选）：每页结果数（1-1000，默认值：50）
  • project_id （字符串，可选）：用于隔离数据的项目名称

示例：

  • 基本搜索： search_knowledge(query="JavaScript", searchMode="exact")
  • 分页搜索： search_knowledge(query="React", page=0, pageSize=20)
  • 大型数据集： search_knowledge(query="components", page=2, pageSize=100)
  • 多个查询： search_knowledge(query=["JavaScript", "React"], page=0, pageSize=30)
  • 标签+分页： search_knowledge(query="React", exactTags=["frontend"], page=1, pageSize=25)
  • 仅标记搜索： search_knowledge(exactTags=["urgent", "bug"], tagMatchMode="all") -无需查询

分页优势：

  • 演出：使用OFFSET/LIMIT进行数据库级分页，以实现高效的大型数据集处理
  • 记忆：通过限制每个请求的结果来减少内存使用
  • 导航：分页元数据提供totalPages、currentPage和导航提示
  • 可扩展性：高效处理包含数千个实体的知识图

open_nodes

检索 特定实体的确切名称及其相互连接。

  • 返回： 请求的实体及其之间的关系
  • 用例： 当你知道确切的实体名称并想要详细信息时

输入：

  • names （string[]）：要检索的实体名称数组
  • project_id （字符串，可选）：用于隔离数据的项目名称

数据管理工具

删除内容

永久删除 实体及其所有关系。

  • 警告： 无法撤消，级联以删除所有连接
  • 用例： 实体不再相关或创建错误

输入：

  • entityNames （string[]）：要删除的实体名称数组
  • project_id （字符串，可选）：用于隔离数据的项目名称

删除观察

移除 在保持实体完整的同时，对实体进行具体观察。

  • 用例： 纠正错误信息或删除过时的细节
  • 保存： 实体和其他意见保持不变

输入：

  • deletions （ObservationDeleation[]）：删除请求数组。每项要求：
    • entityName （string）：目标实体名称
    • observations （string[]）：要删除的具体观察结果
  • project_id （字符串，可选）：用于隔离数据的项目名称

删除关系

更新 当连接发生变化时的关系结构。

  • 关键在于： 作业更改（删除旧的“works_at”）、项目完成（删除“assigned_to”）、技术迁移（删除旧“use”）
  • 维护： 准确的网络结构，防止混淆
  • 工作流： 创建新关系时，始终删除过时的关系

输入：

  • relations （关系[]）：要删除的关系数组。每项要求：
    • from （string）：源实体名称
    • to （string）：目标实体名称
    • relationType （string）：要删除的确切关系类型
  • project_id （字符串，可选）：用于隔离数据的项目名称

移除标签

更新 通过删除过时的标签来显示实体状态。

  • 关键： 对于状态跟踪-完成时删除“进行中”，解决后删除“紧急”
  • 维护： 干净的搜索结果和准确的状态
  • 工作流： 添加新状态标签时，始终删除旧状态标签

输入：

  • updates （TagUpdate[]）：标签删除请求数组。每项要求：
    • entityName （string）：目标实体名称
    • tags （string[]）：要删除的过时标签（精确匹配，区分大小写）
  • project_id （字符串，可选）：用于隔离数据的项目名称

开发和测试

多后端测试

该项目包括全面的多后端测试，以确保SQLite和PostgreSQL之间的兼容性：

对两个后端运行测试：

npm run test:multi-backend

运行所有测试（原始+多后端）：

npm run test:all-backends

使用Taskfile（如果已安装）：

task test:multi-backend
task test:comprehensive

开发设置

克隆和设置：

git clone https://github.com/n-r-w/knowledgegraph-mcp.git
cd knowledgegraph-mcp
npm install
npm run build

运行测试：

npm test                    # All tests including multi-backend
npm run test:unit          # Unit tests only
npm run test:performance   # Performance benchmarks

故障排除

如果您在设置或使用过程中遇到任何问题，请参阅我们的综合 故障排除指南，其中包括：

  • 输入验证错误
  • 数据库连接问题
  • 配置问题
  • Docker相关挑战
  • 测试执行失败
  • 性能优化

该指南包括常见问题的分步解决方案和诊断命令，以帮助识别问题。

基于MCP内存服务器

这是官方的增强版 MCP内存服务器 具有附加功能：

  • 多种存储选项：PostgreSQL（推荐）或SQLite（本地文件）
  • 项目分离：将不同的项目隔离开来
  • 更好的搜索：使用模糊搜索查找信息
  • 轻松设置：Docker支持和简单安装

许可证

MIT许可证-您可以自由使用、修改和分发此软件。

相关 MCP