MCP DuckDB Knowledge Graph Memory Server

MCP DuckDB 知识图谱记忆服务

这是 官方知识图谱记忆服务 的一个分支版本。

安装

通过 Smithery 安装

要通过 Smithery 为 Claude Desktop 自动安装 DuckDB 知识图谱记忆服务：

npx -y @smithery/cli install @IzumiSy/mcp-duckdb-memory-server --client claude

手动安装

也可以在 claude_desktop_config.json 中手动添加 @IzumiSy/mcp-duckdb-memory-server（MEMORY_FILE_PATH 为可选项）

{
  "mcpServers": {
    "graph-memory": {
      "command": "npx",
      "args": [
        "-y",
        "@izumisy/mcp-duckdb-memory-server"
      ],
      "env": {
        "MEMORY_FILE_PATH": "/path/to/your/memory.data"
      }
    }
  }
}

该路径下存储的数据是一个 DuckDB 数据库文件。

Docker

构建

docker build -t mcp-duckdb-graph-memory .

运行

docker run -dit mcp-duckdb-graph-memory

使用方法

使用以下示例指令

Follow these steps for each interaction:

1. User Identification:
   - You should assume that you are interacting with default_user
   - If you have not identified default_user, proactively try to do so.

2. Memory Retrieval:
   - Always begin your chat by saying only "Remembering..." and search relevant information from your knowledge graph
   - Create a search query from user words, and search things from "memory". If nothing matches, try to break down words in the query at first ("A B" to "A" and "B" for example).
   - Always refer to your knowledge graph as your "memory"

3. Memory
   - While conversing with the user, be attentive to any new information that falls into these categories:
     a) Basic Identity (age, gender, location, job title, education level, etc.)
     b) Behaviors (interests, habits, etc.)
     c) Preferences (communication style, preferred language, etc.)
     d) Goals (goals, targets, aspirations, etc.)
     e) Relationships (personal and professional relationships up to 3 degrees of separation)

4. Memory Update:
   - If any new information was gathered during the interaction, update your memory as follows:
     a) Create entities for recurring organizations, people, and significant events
     b) Connect them to the current entities using relations
     b) Store facts about them as observations

动机

本项目通过将后端替换为 DuckDB，增强了原始 MCP 知识图谱记忆服务。

为什么选择 DuckDB？

原始 MCP 知识图谱记忆服务使用 JSON 文件作为数据存储，并在内存中执行搜索。这种方式适用于小型数据集，但也存在一些问题：

1. 性能：随着数据集增大，内存搜索性能会下降
2. 可扩展性：处理大量实体和关系时，内存使用量会显著增加
3. 查询灵活性：复杂查询和条件搜索难以实现
4. 数据完整性：难以确保事务和 CRUD 操作的原子性

DuckDB 可以应对这些问题：

• 快速查询处理：DuckDB 针对分析型查询进行了优化，即使处理大型数据集也能保持良好性能
• SQL 接口：可以使用标准 SQL 轻松执行复杂查询
• 事务支持：支持事务处理，确保数据完整性
• 索引功能：可以创建索引以提升搜索性能
• 嵌入式数据库：可在应用程序中运行，无需外部数据库服务

实现细节

本实现使用 DuckDB 作为后端存储系统，重点关注两个方面：

数据库结构

知识图谱以关系型数据库结构存储，如下所示：

erDiagram
    ENTITIES {
        string name PK
        string entityType
    }
    OBSERVATIONS {
        string entityName FK
        string content
    }
    RELATIONS {
        string from_entity FK
        string to_entity FK
        string relationType
    }

    ENTITIES ||--o{ OBSERVATIONS : "has"
    ENTITIES ||--o{ RELATIONS : "from"
    ENTITIES ||--o{ RELATIONS : "to"

此架构设计能够高效存储和检索知识图谱组件，同时维护实体、观察结果和关系之间的关联。

模糊搜索实现

本实现将 SQL 查询与 Fuse.js 结合，以灵活地搜索实体：

• DuckDB SQL 查询从数据库中检索基础数据
• Fuse.js 基于检索到的数据提供模糊匹配功能
• 这种混合方式同时支持结构化查询和灵活的文本匹配
• 搜索结果包含完全匹配和部分匹配项，并按相关性排序

开发

设置

pnpm install

测试

pnpm test

许可证

本项目采用 MIT 许可证授权，详情请参阅 LICENSE 文件。