Memory

Memory MCP Server provides a persistent knowledge graph for entities, relations, and observations, enabling your AI assistants to remember and reuse context across conversations. It is implemented in Swift and focuses on reliable memory management through a simple JSON line-delimited storage format.

How to use

You interact with Memory MCP Server through a client that speaks the MCP protocol to manage a knowledge graph. Use the server to create entities, define relations between them, and attach observations over time. Before answering complex questions, you can search and open relevant nodes to bring past context into the current conversation. All data persists to disk, so context survives restarts.

Practical usage patterns you can follow:

• Create entities to represent people, places, or concepts you want to remember.
• Define relations to capture how those entities relate to each other.
• Add observations to store notable facts or updates about an entity.
• Read the full graph to get a complete view of your memory, or search for specific nodes by name, type, or observed content.
• Open individual nodes to retrieve detailed information about a single entity and its connections.

How to install

Prerequisites you need before installation:

• macOS 14.0 or later
• Swift 6.0 or later
• Access to a shell (zsh or bash) with curl and git available
• A working development environment for Swift projects (optional for building from source)

Option 1: Build from source and install locally

• Ensure you have Swift toolchain installed. If you have Xcode, you already have it.
• Clone the project and navigate to the repository root:
• Build the project in release mode:
• Install the binary to your local bin directory and ensure it is on your PATH.

Concrete commands to run sequentially:

• git clone https://github.com/okooo5km/memory-mcp-server.git
• cd memory-mcp-server
• swift build -c release
• mkdir -p ~/.local/bin
• cp $(swift build -c release --show-bin-path)/memory-mcp-server ~/.local/bin/
• echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc
• source ~/.zshrc

Option 2: Run a prebuilt binary (if you prefer not to build)

• After installation, you can start memory-mcp-server directly from your PATH environment.

Configuration and runtime options

Environment variable to control storage location:

• MEMORY_FILE_PATH: Custom path for storing the knowledge graph. If not set, the server uses memory.json in the current working directory.

Example usage in a shell session:

• export MEMORY_FILE_PATH="/path/to/your/memory.json"

Starting the server after building and installation:

• memory-mcp-server

Available tools and actions

The server exposes a set of MCP tools to manage the knowledge graph. Use these actions to build and maintain your memory:

• create_entities: Create multiple new entities in the knowledge graph
• create_relations: Create multiple new relations between entities
• add_observations: Add new observations to existing entities
• delete_entities: Delete multiple entities and their associated relations
• delete_observations: Delete specific observations from entities
• delete_relations: Delete multiple relations from the knowledge graph
• read_graph: Read the entire knowledge graph
• search_nodes: Search for nodes based on a query
• open_nodes: Open specific nodes by their names

Troubleshooting and notes

If you encounter issues starting memory-mcp-server, verify that MEMORY_FILE_PATH is set correctly and that you can write to the target directory. Check that the binary memory-mcp-server is on your PATH and that you are running it in an environment with the required permissions.

Examples of usage scenarios

Long-term memory for AI assistants: remember user preferences and past interactions across sessions. Knowledge management: organize details about people, places, events, and concepts. Context persistence: keep essential context across multiple conversations.

Available tools

create_entities

Create multiple new entities in the knowledge graph by providing an array of entity objects with name, entityType, and observations.

create_relations

Create multiple new relations between entities by specifying from, to, and relationType in active voice.

add_observations

Add new observations to existing entities by listing the entityName and contents to append.

delete_entities

Delete one or more entities and their associated relations by providing the entityNames to remove.

delete_observations

Delete specific observations from entities by listing entityName and observations to delete.

delete_relations

Delete multiple relations from the knowledge graph by specifying from, to, and relationType.

read_graph

Read and retrieve the entire knowledge graph to inspect all entities, relations, and observations.

search_nodes

Search for nodes by a query that matches names, types, or observations to find relevant context.

open_nodes

Open specific nodes by name to retrieve detailed information about an entity.