MCP DuckDB Memory Server

What is MCP DuckDB Memory Server about?

MCP DuckDB Memory Server is a fork of the official Model Context Protocol (MCP) Knowledge Graph Memory Server that replaces the JSON file backend with an embedded DuckDB database. It stores entities, observations, and relations in relational tables, allowing efficient analytical queries and fuzzy text matching.

How to use MCP DuckDB Memory Server?

1. Installation
   • Via Smithery (recommended for Claude Desktop):

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

   • Manual npm install (add to claude_desktop_config.json):

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

   • Docker:

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

2. Running The server starts automatically when invoked via the MCP client. It will create (or open) a DuckDB file at the path specified by MEMORY_FILE_PATH.
3. Interaction Follow the example instruction in the README: begin each chat with "Remembering...", let the server perform a fuzzy search on the knowledge graph, and update the graph with new facts as the conversation progresses.

Key features of MCP DuckDB Memory Server

• DuckDB backend – fast analytical queries, indexing, and transaction support.
• Relational schema for entities, observations, and relations.
• Hybrid fuzzy search using SQL for data retrieval combined with Fuse.js for flexible text matching.
• Scalable storage – handles large knowledge graphs without excessive memory consumption.
• Docker support for easy deployment.
• Simple MCP configuration via npx command.

Use cases of MCP DuckDB Memory Server

• Personal AI assistants that remember user identity, preferences, and goals across sessions.
• Enterprise chatbots that need to maintain a structured knowledge graph of customers, products, and interactions.
• Research tools that store and query complex relational data while allowing fuzzy text lookup.
• Any application built on the Model Context Protocol that requires persistent, query‑able memory.

FAQ from the MCP DuckDB Memory Server

Q: Do I need to install DuckDB separately? A: No. DuckDB is embedded and bundled with the npm package.

Q: How do I change the location of the memory file? A: Set the MEMORY_FILE_PATH environment variable in the server configuration.

Q: Can I run the server without Docker? A: Yes. Installing the npm package and invoking it via npx is sufficient.

Q: How does fuzzy search work? A: The server first fetches candidate rows with SQL, then applies Fuse.js on the returned strings to rank exact and partial matches.

Q: Is the data persisted across restarts? A: Yes. As long as the same DuckDB file is used, all entities, observations, and relations are retained.

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

Otherwise, 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

Use the example instruction below

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

Motivation

This project enhances the original MCP Knowledge Graph Memory Server by replacing its backend with DuckDB.

Why DuckDB?

The original MCP Knowledge Graph Memory Server used a JSON file as its data store and performed in-memory searches. While this approach works well for small datasets, it presents several challenges:

1. Performance: In-memory search performance degrades as the dataset grows
2. Scalability: Memory usage increases significantly when handling large numbers of entities and relations
3. Query Flexibility: Complex queries and conditional searches are difficult to implement
4. Data Integrity: Ensuring atomicity for transactions and CRUD operations is challenging

DuckDB was chosen to address these challenges:

• Fast Query Processing: DuckDB is optimized for analytical queries and performs well even with large datasets
• SQL Interface: Standard SQL can be used to execute complex queries easily
• Transaction Support: Supports transaction processing to maintain data integrity
• Indexing Capabilities: Allows creation of indexes to improve search performance
• Embedded Database: Works within the application without requiring an external database server

Implementation Details

This implementation uses DuckDB as the backend storage system, focusing on two key aspects:

Database Structure

The knowledge graph is stored in a relational database structure as shown below:

This schema design allows for efficient storage and retrieval of knowledge graph components while maintaining the relationships between entities, observations, and relations.

Fuzzy Search Implementation

The implementation combines SQL queries with Fuse.js for flexible entity searching:

• DuckDB SQL queries retrieve the base data from the database
• Fuse.js provides fuzzy matching capabilities on top of the retrieved data
• This hybrid approach allows for both structured queries and flexible text matching
• Search results include both exact and partial matches, ranked by relevance

Development

Setup

pnpm install

Testing

pnpm test

License

This project is licensed under the MIT License - see the LICENSE file for details.