Memory MCP Server Knowledge Graph Guide

Memory MCP Server Knowledge Graph Guide

Large language model conversations are traditionally ephemeral. When a developer terminates an inference session or resets a chat window, the agent suffers complete amnesia. Project constraints, team hierarchies, architectural decisions, and user preferences established over hours of interaction vanish from the context window. While system prompts and static retrieval-augmented generation (RAG) provide static background knowledge, they do not provide dynamic, agent-writable long-term memory.

The Memory Model Context Protocol (MCP) server addresses this challenge by providing AI hosts with a persistent, queryable Knowledge Graph engine. Operating over standard JSON-RPC 2.0 stdio streams, the server enables agents to autonomously extract structured entities, map interconnected relationships, record chronological observations, and recall past context across completely independent chat sessions.

1. Problem Statement and Architecture

Standard vector databases store dense embeddings of unstructured text chunks. While effective for semantic document search, vector stores struggle with structured relational recall—such as remembering that "Alex is the tech lead for Project Orion, which depends on Redis cluster 7.2 managed by DevOps". Unstructured chunk retrieval often misses exact entity relationships or pulls conflicting historical assertions.

The Memory MCP server implements a deterministic Entity-Relation-Observation (ERO) knowledge graph stored as a structured JSON database:

• ▸Entities: Discrete named concepts, services, users, or code repositories (Nodes).
• ▸Relations: Directed semantic connections between entities (Edges), such as manages, depends_on, owns, or migrated_from.
• ▸Observations: Fine-grained textual facts and chronological properties associated with individual entities.

+-----------------------------------------------------------------------------------+
|                              Client Architecture                                  |
|                                                                                   |
|  +--------------------+        JSON-RPC 2.0 (stdio)        +-------------------+  |
|  |  Claude / Cursor   | <================================> |   server-memory   |  |
|  +--------------------+                                    +---------+---------+  |
+----------------------------------------------------------------------|------------+
                                                                       | Read / Write
                                                                       v Atomic Lock
                                                             +-------------------+
                                                             |    memory.json    |
                                                             |  (Knowledge Graph)|
                                                             +-------------------+

When an agent interacts with the Memory MCP server, it can query existing graph subgraphs before planning an action, insert new entities during user discussions, and update or delete superseded observations when system parameters evolve.

2. Prerequisites and Environment Matrix

The official memory server is distributed through npm as @modelcontextprotocol/server-memory. It requires Node.js 18 or higher and direct write access to a local filesystem directory.

Verify that Node.js and npm are present in your workspace:

node --version
npm --version

3. Multi-Host Configuration Snippets

The server accepts an optional environment variable MEMORY_FILE_PATH pointing to the exact path where the knowledge graph JSON file should be persisted. If omitted, the server defaults to storing data in the application's working directory or temporary storage. Specifying an explicit absolute path is strongly recommended to prevent accidental data loss during system cleanups.

Claude Desktop

Edit your claude_desktop_config.json:

{
  "mcpServers": {
    "memory": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-memory"],
      "env": {
        "MEMORY_FILE_PATH": "/Users/developer/.mcp/memory.json"
      }
    }
  }
}

Cursor IDE

In your project .cursor/mcp.json or global user configuration:

{
  "mcpServers": {
    "memory": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-memory"],
      "env": {
        "MEMORY_FILE_PATH": "/Users/developer/.mcp/memory.json"
      }
    }
  }
}

OpenAI Codex CLI

In ~/.codex/config.toml:

[mcp_servers.memory]
command = "npx"
args = ["-y", "@modelcontextprotocol/server-memory@2026.8.31"]
env = { MEMORY_FILE_PATH = "/Users/developer/.mcp/memory.json" }

4. Step-by-Step Tool Discovery and Invocation

Upon client connection, the server registers seven graph manipulation tools:

Entity Creation Wire Frame

When the user tells an agent: "Remember that Project Alpha is a Next.js frontend managed by Jordan", the host issues:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "create_entities",
    "arguments": {
      "entities": [
        {
          "name": "ProjectAlpha",
          "entityType": "software_project",
          "observations": ["Built using Next.js 15 App Router", "Target deployment on Vercel"]
        },
        {
          "name": "Jordan",
          "entityType": "person",
          "observations": ["Engineering Lead for ProjectAlpha"]
        }
      ]
    }
  }
}

The server responds affirming node creation:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "Created 2 entities successfully."
      }
    ],
    "isError": false
  }
}

Relation Creation Wire Frame

The host then links the two entities together:

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/call",
  "params": {
    "name": "create_relations",
    "arguments": {
      "relations": [
        {
          "from": "Jordan",
          "to": "ProjectAlpha",
          "relationType": "leads_and_manages"
        }
      ]
    }
  }
}

5. Common Errors and Production Troubleshooting

1. EACCES: permission denied on Memory File

• ▸Symptom: Server initialization or tool invocation crashes with EACCES: permission denied, open '/var/root/memory.json'.
• ▸Root Cause: The client spawned the server under a restricted user profile or MEMORY_FILE_PATH points to a protected system directory.
• ▸Solution: Set MEMORY_FILE_PATH to a dedicated directory inside your user home folder (~/.mcp/memory.json on macOS/Linux or C:\Users\<USER>\.mcp\memory.json on Windows). Ensure parent directories exist prior to launching.

# macOS / Linux
mkdir -p ~/.mcp && chmod 700 ~/.mcp

# Windows PowerShell
New-Item -ItemType Directory -Force -Path "$HOME\.mcp"

2. Entity Fragmentation and Near-Duplicate Nodes

• ▸Symptom: The AI creates parallel disconnected nodes such as UserAuthService, user-auth-service, and AuthService.
• ▸Root Cause: The agent issues create_entities without first calling search_nodes to inspect existing nomenclature.
• ▸Solution: Include an explicit operating rule in your system prompt instructing the agent to always execute search_nodes before inserting new concepts, and perform graph consolidation when duplicates appear.

3. Stale Context and Conflicting Observations

• ▸Symptom: The agent asserts outdated specifications despite recent changes.
• ▸Root Cause: New observations were added without calling delete_observations on superseded statements.
• ▸Solution: Instruct your assistant to prune outdated observations whenever architectural decisions or version pins change.

6. External Citations and Security Guardrails

When persisting user context across sessions, observe core data privacy practices:

1. ▸Exclude Sensitive Secrets: Never store unencrypted API keys, database credentials, or sensitive personal data inside plaintext memory files.
2. ▸Backup and Versioning: Because the knowledge graph is stored as human-readable JSON, commit the file to a private Git repository or configure snapshot backups to prevent accidental graph corruption.
3. ▸Verified Package Hashes: Pin dependencies to audited registry releases to ensure server supply-chain security.

• ▸npm @modelcontextprotocol/server-memory Registry (opens in a new tab)
• ▸Model Context Protocol GitHub Memory Implementation (opens in a new tab)
• ▸Official Model Context Protocol Specification (opens in a new tab)