Memory

What Memory does

Memory stores structured information in a local knowledge graph so an MCP client can reuse context across chats and sessions. The graph contains entities, relations, and observations:

• Entities are uniquely named nodes with an entity type and a collection of text observations.
• Relations connect two entities with a directed, active-voice relationship type.
• Observations are independent, removable facts attached to an entity.

The package is published as @modelcontextprotocol/server-memory. Storage uses a JSONL file, allowing the server to retain data between process runs. The design fits personal preferences, people, organizations, projects, events, and other information that an agent needs to recall later.

How it works

The server communicates with MCP clients over stdio. A client can create entities, add relationships, attach observations, and later search or open selected nodes. It can also read the complete graph when a broad view is needed. Entity names act as identifiers, so creating an existing name does not replace it; additional facts should be added with the observation tool instead.

The knowledge-graph resource at memory://knowledge-graph exposes the complete graph as JSON. Changes made through mutation tools emit resource-update notifications, allowing subscribed clients to refresh their view. Clients use protocol-era-specific subscription requests, while the available tools and resource remain the same.

When multiple MCP clients point to one memory file, each process uses an adjacent lock file during writes. This serializes changes and protects the file from concurrent overwrites. A write that cannot acquire the lock within 60 seconds returns an error.

Setup and configuration

Node.js 24 or later is required when running through npx or from source. The package can be launched with:

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

On Windows, launch npx through cmd /c. Docker is also supported; the documented configuration runs mcp/memory with a named volume mounted at /app/dist.

Set MEMORY_FILE_PATH to choose the JSONL storage location. Without it, the server uses memory.jsonl in its server directory. The directory must be writable because the server saves the graph atomically and creates a temporary lock file during writes.

Tools and capabilities

• create_entities adds multiple uniquely named entities, including their types and initial observations. Duplicate names are skipped.
• create_relations adds directed links between existing entities and skips duplicate links.
• add_observations appends facts to existing entities.
• delete_entities removes entities and cascades deletion to their relations.
• delete_observations removes selected facts without deleting the entity.
• delete_relations removes specified links.
• read_graph returns every entity and relation.
• search_nodes searches entity names, types, and observation text, returning matching entities and their relations.
• open_nodes retrieves named entities and relations among the requested nodes.

Limitations and notes

Relations require both endpoint entities to exist. The server silently skips nonexistent nodes when opening them, while deletion operations report missing names or unmatched items in their results. Sharing a file across processes depends on filesystem support for exclusive file creation; a network filesystem that does not honor that behavior is not safe for shared writes. A lock left by a crashed process is eventually treated as stale, and only one waiting process can break it at a time.