Skip to main content

​
Getting Started with MemMachine in Claude Code

This guide will help you integrate MemMachine into Claude Code, Anthropic’s official CLI tool for software engineering tasks. With MemMachine, Claude Code can remember context across sessions, making it more helpful for ongoing projects.

​
What is Claude Code?

Claude Code is a command-line interface that provides Claude with powerful tools for software development, including file operations, code execution, and now—with MemMachine—persistent memory across conversations.

​
Prerequisites

Before you begin, ensure you have:
  1. Claude Code installed and configured
  2. MemMachine running (either via Docker or as a Python package)
  3. A MemMachine configuration file (config.yml)
Unlike Claude Desktop, Claude Code does not use claude_desktop_config.json. To integrate MemMachine MCP, you must use .mcp.json at your project root and .claude/settings.local.json for persistent settings.
Starting Your Docker Container: Make sure your MemMachine Docker container is running: 
docker compose up -d
Or if you’re using the provided script: 
./memmachine-compose.sh
1

Choose Your Setup Method

MemMachine can be integrated with Claude Code in two ways:Option A: Using Docker (Recommended)
  • Best for isolated, reproducible environments
  • MemMachine runs in a container
  • Requires Docker installed and running
Option B: Direct Command
  • Simpler setup if you have MemMachine installed locally
  • Uses your system Python environment
  • Requires MemMachine installed via pip or uv
Choose the method that best fits your workflow.
2

Option A: Configure for Claude Code (Docker)

To allow Claude Code to access the MemMachine MCP, create or edit the .mcp.json file in your project root:
{
  "mcpServers": {
    "memmachine": {
      "command": "docker",
      "args": [
        "exec",
        "-i",
        "memmachine-app",
        "/app/.venv/bin/memmachine-mcp-stdio"
      ],
      "env": {
        "MEMORY_CONFIG": "/app/configuration.yml",
        "MM_USER_ID": "your-username",
        "PYTHONUNBUFFERED": "1"
      }
    }
  }
}
Crucial for Claude Code: You must verify that your connection settings in .mcp.json match the bridge configuration in ./.claude/settings.local.json. Claude Code uses the latter to maintain persistent authorization for the MCP server.
Ensure Persistence: To ensure the connection remains active across sessions, verify or add these settings to your local Claude settings file located at ./.claude/settings.local.json.Configuration Details: To ensure the MCP server communicates correctly with your environment, verify the following parameters in your .mcp.json and .claude/settings.local.json files:
ParameterValue / Description
commandUse docker for containerized setups or memmachine-mcp-stdio for local installs.
MEMORY_CONFIGPath to your configuration.yml. Note: Use absolute paths for local (Option B) setups.
userIdYour unique identifier for memory sessions (corresponds to MM_USER_ID).
PYTHONUNBUFFEREDAlways set to 1 to ensure immediate output and logging from Python.
3

Option B: Configure with Direct Command

Reference Implementation: This method follows the standard MCP stdio pattern. While it uses the same configuration files as the Docker method, ensure your local Python environment is correctly mapped.
If you have MemMachine installed locally, create or edit the .mcp.json file in your project root:
{
  "mcpServers": {
    "memmachine": {
      "command": "memmachine-mcp-stdio",
      "env": {
        "MEMORY_CONFIG": "/absolute/path/to/config.yml",
        "MM_USER_ID": "your-username",
        "PYTHONUNBUFFERED": "1"
      }
    }
  }
}
Using uv (Recommended for local setup): If you are managing your environment with uv, use the following configuration in your .mcp.json:
{
  "mcpServers": {
    "memmachine": {
      "command": "uv",
      "args": ["run", "memmachine-mcp-stdio"],
      "env": {
        "MEMORY_CONFIG": "/absolute/path/to/config.yml",
        "MM_USER_ID": "your-username",
        "PYTHONUNBUFFERED": "1"
      }
    }
  }
}
Important: Use absolute paths for MEMORY_CONFIG to avoid path resolution issues.
Crucial for Claude Code: You must verify that your connection settings in .mcp.json match the bridge configuration in ./.claude/settings.local.json. Claude Code uses the latter to maintain persistent authorization for the MCP server.
4

Test the Integration

Once configured, start Claude Code in your project directory:
claude
Verify the connection by checking the active MCP servers:
/MCP
If MemMachine is listed, Claude will automatically use the add_memory and search_memory tools to manage your project context.
You: Remember that I prefer using TypeScript for new projects
Claude should use the add_memory tool to store this preference.Test memory recall by starting a new conversation and asking:
You: What programming language do I prefer?
Claude should search memory and recall your TypeScript preference.
5

Using Memory with Claude Code

MemMachine provides two main tools that Claude Code can use:add_memory: Stores new information
  • Called automatically when you share facts, preferences, or important context
  • Stores both episodic (conversation) and profile (long-term) memory
search_memory: Retrieves relevant context
  • Called automatically when context from previous sessions might be helpful
  • Searches both conversation history and user profile
You don’t need to explicitly ask Claude to use these tools—they’re integrated into the workflow automatically.
6

Troubleshooting

Claude Code can’t connect to MemMachine:
  • Verify your Docker container is running: docker ps | grep memmachine
  • Check the container name matches your config
  • Review Claude Code logs for connection errors
Memory not persisting:
  • Ensure MEMORY_CONFIG points to a valid configuration file
  • Check that your Neo4j and PostgreSQL databases are running
  • Verify MM_USER_ID is consistent across sessions
Permission errors:
  • If using Docker, ensure the container has proper volume mounts
  • Check file permissions on your configuration file
  • Verify the path to memmachine-mcp-stdio is correct
Getting logs: You can check the MCP server output by viewing:
docker logs memmachine-app
Or if running directly, check the stderr output in your terminal.