Knowledge Graph Memory Server

A Knowledge Graph Memory Server provides a persistent memory system that stores entities, relations, observations, and lessons in a local knowledge graph. It lets you remember user details across chats, model behavior over time, and capture error lessons so you can learn and improve interactions.

How to use

You integrate the memory server with your MCP client to enable memory-driven interactions. Create and manage entities (for people, organizations, events), establish relations between them, and attach observations to capture discrete facts. Use lessons to document errors and their fixes, then reference those lessons to guide future responses. When you start a chat, retrieve relevant memory first, then update memory with any new information gathered during the conversation.

Typical workflows include: setting up a few core entities (e.g., user profiles or organizations), adding observations like preferences or past interactions, and wiring relations to reflect connections (for example, a user works_at a company). When an error occurs, create a lesson with the error pattern, solution steps, and verification, then monitor its success rate to prioritize effective fixes in future sessions.

How to install

Prerequisites: ensure you have Node.js and npm installed if you plan to use npm/npx workflows, and Docker if you prefer the container approach.

Option A — Run memory server via Docker (recommended for quick local startups): start a memory container aligned with your MCP client setup.

{
  "mcpServers": {
    "memory": {
      "type": "stdio",
      "name": "memory_docker",
      "command": "docker",
      "args": ["run", "-i", "-v", "claude-memory:/app/dist", "--rm", "mcp/memory"]
    }
  }
}

How to install

Option B — Run memory server with NPX (local, no Docker): use the MCP NPX configuration to start the server in place.

{
  "mcpServers": {
    "memory": {
      "type": "stdio",
      "name": "memory_npx",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-memory"]
    }
  }
}

How to install

Option C — NPX with custom environment path (if you want a custom memory file location): configure the environment variable MEMORY_FILE_PATH in the NPX setup.

{
  "mcpServers": {
    "memory": {
      "type": "stdio",
      "name": "memory_npx_custom",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-memory"],
      "env": {
        "MEMORY_FILE_PATH": "/path/to/custom/memory.json"
      }
    }
  }
}

Configuration and usage notes

The memory server stores data in two JSON files: memory.json for basic entities and relations, and lesson.json for lesson entities with error patterns. Files are automatically split if they grow beyond 1000 lines to maintain performance.

Security and maintenance

Keep memory data secured and backed up. Use environment isolation when running multiple MCP servers on the same host. Regularly review lessons to avoid stale or redundant error patterns, and prune observations as needed to keep the graph concise.

Troubleshooting tips

If memory data doesn’t load on startup, verify that the memory.json path is writable and that the server process has sufficient permissions to read/write. Check for conflicts in entity names or duplicate relations. If a lesson fails verification steps, validate the command and expected output against the actual results and update the lesson accordingly.

Notes and examples

Examples of core concepts you can model include:
- Entity: {"name": "John_Smith", "entityType": "person", "observations": ["Speaks fluent Spanish"]}
- Relation: {"from": "John_Smith", "to": "Anthropic", "relationType": "works_at"}
- Observation: {"entityName": "John_Smith", "observations": ["Graduated in 2019"]}
- Lesson: {"name": "NPM_VERSION_MISMATCH_01", "entityType": "lesson", "observations": ["Error occurs when using incompatible package versions"], "errorPattern": {"type": "dependency", "message": "Cannot find package @shadcn/ui", "context": "package installation"}, "metadata": {"severity": "high", "environment": {"os": "windows", "nodeVersion": "18.x"}, "createdAt": "2025-02-13T13:21:58.523Z", "updatedAt": "2025-02-13T13:22:21.336Z", "frequency": 1, "successRate": 1.0}, "verificationSteps": [{"command": "pnpm add shadcn@latest", "expectedOutput": "Successfully installed shadcn", "successIndicators": ["added shadcn"]}]}

Available tools and endpoints

The server provides programmatic tools to manage memory and lessons. These tools allow you to create and modify entities, relations, and observations, search the graph, manage lessons, and retrieve recommendations based on current context.

Available tools

create_entities

Create multiple new entities in the knowledge graph. Input is an array of entities with name, entityType, and observations. Entities with existing names are ignored.

create_relations

Create multiple new relations between entities. Input is an array of relations with from, to, and relationType. Duplicate relations are skipped.

add_observations

Add new observations to existing entities. Input is an array of objects with entityName and contents. Returns added observations per entity and fails if the target entity does not exist.

delete_entities

Remove entities and their relations. Input is an array of entity names. Performs cascading deletion of related connections and remains silent if an entity does not exist.

delete_observations

Remove specific observations from entities. Input is an array of objects with entityName and observations to delete. Slient if observations are not found.

delete_relations

Remove specific relations from the graph. Input is an array of relations with from, to, and relationType. Silent if not found.

read_graph

Read the entire knowledge graph and return all entities and relations.

search_nodes

Search for nodes by query across entity names, types, and observation contents. Returns matching entities and their relations.

open_nodes

Retrieve specific nodes by name and return requested entities with their inter-relations. Silently skips non-existent nodes.

create_lesson

Create a new lesson from an error and its solution. Validates required fields, initializes timestamps, and stores verification steps.

find_similar_errors

Find similar errors by errorPattern and return matching lessons sorted by success rate, with related solutions and verification steps.

update_lesson_success

Update the success tracking for a lesson, adjusting the success rate, frequency, and last updated timestamp.

get_lesson_recommendations

Get relevant lessons for the current context, sorted by relevance and success rate, with full solution details and verification steps.