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:
- Performance: In-memory search performance degrades as the dataset grows
- Scalability: Memory usage increases significantly when handling large numbers of entities and relations
- Query Flexibility: Complex queries and conditional searches are difficult to implement
- 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:
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"
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.
[
{
"description": "Create multiple new entities in the knowledge graph",
"inputSchema": {
"properties": {
"entities": {
"items": {
"properties": {
"entityType": {
"description": "The type of the entity",
"type": "string"
},
"name": {
"description": "The name of the entity",
"type": "string"
},
"observations": {
"description": "An array of observation contents associated with the entity",
"items": {
"type": "string"
},
"type": "array"
}
},
"required": [
"name",
"entityType",
"observations"
],
"type": "object"
},
"type": "array"
}
},
"required": [
"entities"
],
"type": "object"
},
"name": "create_entities"
},
{
"description": "Create multiple new relations between entities in the knowledge graph. Relations should be in active voice",
"inputSchema": {
"properties": {
"relations": {
"items": {
"properties": {
"from": {
"description": "The name of the entity where the relation starts",
"type": "string"
},
"relationType": {
"description": "The type of the relation",
"type": "string"
},
"to": {
"description": "The name of the entity where the relation ends",
"type": "string"
}
},
"required": [
"from",
"to",
"relationType"
],
"type": "object"
},
"type": "array"
}
},
"required": [
"relations"
],
"type": "object"
},
"name": "create_relations"
},
{
"description": "Add new observations to existing entities in the knowledge graph",
"inputSchema": {
"properties": {
"observations": {
"items": {
"properties": {
"contents": {
"description": "An array of observation contents to add",
"items": {
"type": "string"
},
"type": "array"
},
"entityName": {
"description": "The name of the entity to add the observations to",
"type": "string"
}
},
"required": [
"entityName",
"contents"
],
"type": "object"
},
"type": "array"
}
},
"required": [
"observations"
],
"type": "object"
},
"name": "add_observations"
},
{
"description": "Delete multiple entities and their associated relations from the knowledge graph",
"inputSchema": {
"properties": {
"entityNames": {
"description": "An array of entity names to delete",
"items": {
"type": "string"
},
"type": "array"
}
},
"required": [
"entityNames"
],
"type": "object"
},
"name": "delete_entities"
},
{
"description": "Delete specific observations from entities in the knowledge graph",
"inputSchema": {
"properties": {
"deletions": {
"items": {
"properties": {
"entityName": {
"description": "The name of the entity containing the observations",
"type": "string"
},
"observations": {
"description": "An array of observations to delete",
"items": {
"type": "string"
},
"type": "array"
}
},
"required": [
"entityName",
"observations"
],
"type": "object"
},
"type": "array"
}
},
"required": [
"deletions"
],
"type": "object"
},
"name": "delete_observations"
},
{
"description": "Delete multiple relations from the knowledge graph",
"inputSchema": {
"properties": {
"relations": {
"description": "An array of relations to delete",
"items": {
"properties": {
"from": {
"description": "The name of the entity where the relation starts",
"type": "string"
},
"relationType": {
"description": "The type of the relation",
"type": "string"
},
"to": {
"description": "The name of the entity where the relation ends",
"type": "string"
}
},
"required": [
"from",
"to",
"relationType"
],
"type": "object"
},
"type": "array"
}
},
"required": [
"relations"
],
"type": "object"
},
"name": "delete_relations"
},
{
"description": "Search for nodes in the knowledge graph based on a query",
"inputSchema": {
"properties": {
"query": {
"description": "The search query to match against entity names, types, and observation content",
"type": "string"
}
},
"required": [
"query"
],
"type": "object"
},
"name": "search_nodes"
},
{
"description": "Open specific nodes in the knowledge graph by their names",
"inputSchema": {
"properties": {
"names": {
"description": "An array of entity names to retrieve",
"items": {
"type": "string"
},
"type": "array"
}
},
"required": [
"names"
],
"type": "object"
},
"name": "open_nodes"
}
]