MCP Memory Server

The MCP Memory Server provides a persistent memory layer for model conversations, enabling your AI applications to create, manage, and query entities and their relationships in a durable knowledge graph. This makes it easy to store context, recall past interactions, and infer connections across conversations.

How to use

You interact with the MCP Memory Server through an MCP client. Start the server locally, connect to it from your client, and then perform common operations such as creating entities, adding observations, shaping relationships, and querying the graph to retrieve context and insights.

Typical usage patterns include creating a person or company as an entity, attaching observations to capture attributes, linking entities with relationships, and running searches to locate nodes or navigate the graph. You can also open specific nodes to view their details and read the full graph to understand the knowledge landscape.

You will access key graph endpoints such as the complete graph, all entities, all relationships, and graph statistics to monitor your data and queries over time.

How to install

Prerequisites: ensure Node.js is installed on your system. You will also use npm and npx for package management and running MCP tools.

Step 1 — Install the MCP Memory Server globally (recommended): install the package globally so you can run it from anywhere.

npm install -g mcp-memory-server

Step 2 — Build and prepare for local development: clone the repository, install dependencies, and build the project if you are working from source.

git clone <repository-url>
cd mcp_memory
npm install
npm install typescript --save-dev
npm run build

Step 3 — Run the server locally: you can start the server with an automatic Windows startup script or run it manually via a controller script.

# Auto-start on Windows
.\auto-start.ps1

# Or start manually
.\server-controller.ps1

Step 4 — Verify the server is running and tests pass: run the test suite and check the status using the provided scripts.

.\run-test.ps1
.\quick-status.ps1

Configuration

Claude Desktop configuration lets you connect to the MCP Memory Server and run memory-related tools directly from the editor. You can either point to a local build or use a package runner to start the server within Claude Desktop.

{
  "mcpServers": {
    "memory": {
      "command": "npx",
      "args": ["-y", "mcp-memory-server"],
      "env": {
        "MCP_MEMORY_DB_PATH": "./memory.db"
      }
    }
  }
}

If you prefer a local runtime directly from the build, you can run a Node-based server target with a working directory configured for your development path.

{
  "mcpServers": {
    "mcp_memory": {
      "command": "node",
      "args": ["./build/simple-index.js"],
      "cwd": "c:\\vscode\\mcp_memory"
    }
  }
}

Notes and troubleshooting

If you need to set a persistent JSON-based store, the server uses a simple memory.json or equivalent path for data persistence. You can verify persistence by performing operations and then restarting the server to confirm data is retained.

Common issues include connection timeouts, missing environment variables, or mismatched client configuration. Ensure your client references the correct MCP server endpoint and that the startup command matches what you configured in Claude Desktop.

Examples of common operations

Create entities, observations, and relations to populate your knowledge graph, then search and open nodes to inspect details.

await mcp_memory_create_entities({
  entities: [
    {
      name: "Ana Costa",
      entityType: "pessoa",
      observations: ["Email: ana@example.com", "Telefone: (11) 99999-9999"]
    }
  ]
});

await mcp_memory_add_observations({
  observations: [
    {
      entityName: "Ana Costa",
      contents: ["Gosta de programação", "Tem 5 anos de experiência"]
    }
  ]
});

await mcp_memory_create_relations({
  relations: [
    { from: "Ana Costa", to: "Startup XYZ", relationType: "fundadora" }
  ]
});

const resultado = await mcp_memory_search_nodes({ query: "startup" });
const entidades = await mcp_memory_open_nodes({ names: ["Ana Costa", "Startup XYZ"] });

Resources and endpoints

The server exposes several graph-related resources you can query to inspect the knowledge graph and its metadata.

• memory://graph — Full knowledge graph
• memory://entities — All entities
• memory://relations — All relationships
• memory://stats — Graph statistics

Project structure and development

The project organizes code for the main MCP server and a simplified JSON-based variant, along with tooling and scripts for development and testing.

Available tools

mcp_memory_create_entities

Create new entities with optional observations and metadata within the memory graph.

mcp_memory_add_observations

Add observations to existing entities to enrich their attributes and context.

mcp_memory_create_relations

Define relationships between entities to represent connections in the graph.

mcp_memory_search_nodes

Search for entities or relationships by content to locate relevant nodes.

mcp_memory_open_nodes

Open and retrieve detailed information about specific entities or relationships.

mcp_memory_read_graph

Read the complete memory graph or current subset for inspection.