📌Overview

Purpose: The MCP DuckDB Knowledge Graph Memory Server aims to enhance the original knowledge graph memory capabilities by utilizing DuckDB for improved data handling and query performance.

Overview: This framework is a refined version of the MCP Knowledge Graph Memory Server, leveraging DuckDB as a backend for efficient storage and manipulation of large knowledge graphs. It replaces the former JSON-based system to ensure better scalability, speed, and data integrity.

Key Features:

• Fast Query Processing: Optimized for analytical queries, DuckDB delivers high performance even with extensive datasets, ensuring quick data retrieval and updates.

• SQL Interface: Users can execute complex queries easily using standard SQL, facilitating flexible data interactions and advanced search capabilities.

• Transaction Support: The framework supports transaction processing, which helps maintain data accuracy and integrity during CRUD operations.

• Indexing Capabilities: Allows users to create indexes for improved search performance, resulting in faster and more efficient information retrieval.

• Embedded Database: DuckDB operates within the application context, eliminating the need for an external database server, enhancing deployment simplicity.

---

MCP DuckDB Knowledge Graph Memory Server

A forked version of the official Knowledge Graph Memory Server.

Installation

Installing via Smithery

To install DuckDB Knowledge Graph Memory Server for Claude Desktop automatically via Smithery:

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

Manual install

Or add @IzumiSy/mcp-duckdb-memory-server in your claude_desktop_config.json manually (MEMORY_FILE_PATH is optional):

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

The data stored on that path is a DuckDB database file.

Docker

Build:

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

Run:

docker run -dit mcp-duckdb-graph-memory

Usage

Follow these steps for each interaction:

1. User Identification:

   • Assume interacting with default_user
   • If not identified, proactively identify default_user

2. Memory Retrieval:

   • Begin chat by saying only "Remembering..." and search relevant information from your knowledge graph
   • Create a search query from user words and search "memory". If nothing matches, break down query words (e.g., "A B" to "A" and "B")
   • Refer to your knowledge graph as your "memory"

3. Memory:

   • While conversing, pay attention to new information in these categories:
     • Basic Identity (age, gender, location, job title, education, etc.)
     • Behaviors (interests, habits)
     • Preferences (communication style, preferred language)
     • Goals (targets, aspirations)
     • Relationships (personal and professional up to 3 degrees)

4. Memory Update:

   • Update your memory with new information:
     • Create entities for recurring organizations, people, significant events
     • Connect them to current entities using relations
     • Store facts as observations

Motivation

This project replaces the original MCP Knowledge Graph Memory Server backend with DuckDB to improve:

• Performance
• Scalability
• Query flexibility
• Data integrity

Why DuckDB?

The original server used a JSON file and in-memory searches, which struggle with large datasets. DuckDB provides:

• Fast query processing optimized for analytics
• Standard SQL interface for complex queries
• Transaction support for data integrity
• Indexing capabilities for performance
• Embedded database requiring no external server

Implementation Details

Database Structure

The knowledge graph is stored in a relational database structure:

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"

Fuzzy Search Implementation

• DuckDB SQL retrieves base data
• Fuse.js adds fuzzy matching on top of data
• Hybrid enables structured queries plus flexible text matching
• Results include exact and partial matches ranked by relevance

Development

Setup

pnpm install

Testing

pnpm test

License

This project is licensed under the MIT License.