mcp-duckdb-memory

This MCP server provides a DuckDB-backed knowledge graph memory for persistent storage and querying of entities, observations, and relations. It replaces the previous JSON-based in-memory store with a relational backend, enabling SQL queries, structured data integrity, and scalable memory management. You can load and query memory entries, perform fuzzy searches on entities, and maintain a structured knowledge graph where entities are linked to observations and relations. Typical workflows involve starting the server via your preferred package manager and interacting with the memory through its exposed API or tooling that the server provides.

To use the server, install it via npx using the package name and run it in your environment. You can optionally point MEMORY_FILE_PATH to a DuckDB database file, so your memory persists across sessions. Use the server to store new entities, observations, and relations, and to retrieve memory by performing SQL-based or fuzzy searches over the stored knowledge graph. Remember to treat the memory as your reference against which new information is validated and linked, updating entities and relationships as conversations evolve.

Prerequisites:

• Node.js (with npm or npx) installed on your system
• Optional: Docker if you prefer containerized usage

Installation steps (Smithery method):

1. Install via Smithery for Claude Desktop integration: npx -y @smithery/cli install @IzumiSy/mcp-duckdb-memory-server --client claude

Manual installation: 2) Add the MCP server to your claude_desktop_config.json (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" } } } }

Docker (alternative): 3) Build and run using Docker: docker build -t mcp-duckdb-graph-memory . docker run -dit mcp-duckdb-graph-memory

Notes:

• Ensure the MEMORY_FILE_PATH points to a writable location where the DuckDB file will reside. If omitted, the server may store data in memory or a default path depending on implementation.
• If you use Smithery, follow the specific client integration steps provided by Smithery for your setup.

Tips and common considerations:

• The server uses DuckDB as the backend, enabling SQL queries and transactional operations. You can leverage standard SQL for advanced querying over entities, observations, and relations.
• If you need persistent memory, provide MEMORY_FILE_PATH to a real file path; otherwise, data may be lost when the process terminates.
• When updating memory during conversations, consider creating entities for recurring organizations, people, and events and linking them with appropriate relations to maintain a coherent knowledge graph.
• If you encounter startup issues, check that the environment supports DuckDB dependencies and that the memory file path is accessible with proper permissions.
• The package name for Node.js installation is @izumisy/mcp-duckdb-memory-server; ensure you are using the correct scope and casing in your commands.