Memory

You run a lightweight Python-based memory server that stores a knowledge graph to help Claude remember information about users across chats. This memory enables persistent context, preferences, and relationships to improve personalization over time.

How to use

To use memory with your Claude desktop setup, configure the local memory MCP server and point your client to it. The memory server exposes a set of graph operations you can invoke through your MCP client, allowing you to create entities, link them with relations, and attach atomic observations. The memory is loaded at startup and updated as you interact with users.

Setup a memory server instance and connect your Claude client to it. You will store user details as entities (for example, a person or organization), define how those entities relate, and attach observations such as preferences or past actions. During conversations, your client can retrieve relevant memory before responding and push new facts back to memory after each interaction.

Typical workflow patterns include:

• Retrieve all relevant memories at the start of a chat and refer to the memory as your source of truth.
• When you learn new facts about a user, create or update entities and observations accordingly.
• Use relations to connect recurring organizations or people to a user, enabling richer context across conversations.

How to install

{
  "mcpServers": {
    "memory_py": {
      "type": "stdio",
      "command": "uvx",
      "args": ["--refresh", "--quiet", "mcp-memory-py"],
      "env": {
        "MEMORY_FILE_PATH": "/path/to/custom/memory.json"
      }
    }
  }
}

Prerequisites
- Install the MCP runtime (uvx) suitable for your environment. The memory server runs through uvx and expects a python-based MCP package named mcp-memory-py.
- Ensure you have a writable path for the memory file if you want a custom location; otherwise the default memory.json in the server directory is used.

Steps to run

1. Create or choose a path for the memory file, for example /path/to/custom/memory.json.
2. Start the MCP stdio server with the following command:
3. Verify the server is running and accessible to your Claude client. Commands shown here are the exact runtime you will use to launch the memory server.

Configuration and usage notes

Environment variable you may set:

• MEMORY_FILE_PATH: Path to the memory storage JSON file. Default is memory.json in the server directory.
• DEBUG_LOGGING: If enabled, a daily logfile is produced describing server calls (recommended for development).

System prompts and memory usage:

• When your chat starts, retrieve all relevant memory from the knowledge graph and refer to it as your memory.
• Update memory for new facts: create entities for recurring organizations, people, and events; connect them with relations; store new observations.

API and data model overview

Core concepts you will interact with:

• Entities: nodes in the knowledge graph with a unique name, an entity type, and a list of atomic observations.
• Relations: directed connections between entities expressed in active voice (e.g., from John_Smith to Anthropic with relationType works_at).
• Observations: atomic strings attached to entities describing facts (e.g., Speaks fluent Spanish).

Available actions you can perform through the MCP client:

• create_entities: add new entities with initial observations.
• create_relations: link entities with a specified relation type.
• add_observations: attach new facts to existing entities.
• delete_entities: remove entities and their relations (cascading).
• delete_observations: remove specific observations from entities.
• delete_relations: remove specific relations.
• read_graph: retrieve the full graph structure.
• search_nodes: find nodes by query across names, types, and observations.
• open_nodes: fetch specific nodes and the relations among them.

Tools and endpoints

The memory server exposes a set of graph operations that you can call from your MCP client to manage entities, relations, and observations, as described above. These tools enable persistent personalization by maintaining a structured memory across chats.

Available tools

create_entities

Create multiple new entities in the knowledge graph. Input consists of entities with name, entityType, and observations.

create_relations

Create multiple new relations between entities. Each relation has a from, to, and relationType.

add_observations

Add new observations to existing entities. Returns added observations per entity and fails if the entity does not exist.

delete_entities

Remove entities and their relations. Cascading deletion is performed and the operation is silent if the entity does not exist.

delete_observations

Remove specific observations from entities. Silent if observations do not exist.

delete_relations

Remove specific relations from the graph. Silent if relation does not exist.

read_graph

Return the complete knowledge graph including all entities and relations.

search_nodes

Search for nodes based on a query across names, types, and observations. Returns matching entities and their relations.

open_nodes

Retrieve specific nodes by name and return the requested entities along with the relations between them.