> ## Documentation Index
> Fetch the complete documentation index at: https://docs.memmachine.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Claude Code

> Setting up MemMachine with Claude Code

## 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`)

<Warning>
  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.
</Warning>

**Starting Your Docker Container:**

Make sure your MemMachine Docker container is running:

```bash theme={null}
docker compose up -d
```

Or if you're using the provided script:

```bash theme={null}
./memmachine-compose.sh
```

<Steps>
  <Step title="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.
  </Step>

  <Step title="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**:

    ```json theme={null}
    {
      "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"
          }
        }
      }
    }
    ```

    <Note>
      **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.
    </Note>

    **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:

    | Parameter              | Value / Description                                                                         |
    | :--------------------- | :------------------------------------------------------------------------------------------ |
    | **`command`**          | Use `docker` for containerized setups or `memmachine-mcp-stdio` for local installs.         |
    | **`MEMORY_CONFIG`**    | Path to your `configuration.yml`. **Note:** Use absolute paths for local (Option B) setups. |
    | **`userId`**           | Your unique identifier for memory sessions (corresponds to `MM_USER_ID`).                   |
    | **`PYTHONUNBUFFERED`** | Always set to `1` to ensure immediate output and logging from Python.                       |
  </Step>

  <Step title="Option B: Configure with Direct Command">
    <Note>
      **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.
    </Note>

    If you have MemMachine installed locally, create or edit the `.mcp.json` file in your **project root**:

    ```json theme={null}
    {
      "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`:

    ```json theme={null}
    {
      "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.

    <Note>
      **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.
    </Note>
  </Step>

  <Step title="Test the Integration">
    Once configured, start Claude Code in your project directory:

    ```bash theme={null}
    claude
    ```

    **Verify the connection** by checking the active MCP servers:

    ```bash theme={null}
    /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.
  </Step>

  <Step title="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.
  </Step>

  <Step title="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:

    ```bash theme={null}
    docker logs memmachine-app
    ```

    Or if running directly, check the stderr output in your terminal.
  </Step>
</Steps>