Docker

Run Basic Memory in Docker containers for server deployments and SSE transport

Overview

Basic Memory provides official Docker images published to GitHub Container Registry. The container runs the MCP server with SSE (Server-Sent Events) transport, suitable for:

• Server deployments where multiple clients connect remotely
• Kubernetes or Docker Compose orchestration
• CI/CD environments
• Development and testing

For local use with Claude Desktop or other MCP clients that use stdio transport, we recommend installing via Homebrew or pip.

Quick Start

Pull the Image

docker pull ghcr.io/basicmachines-co/basic-memory:latest

Run the Container

docker run -d \
  --name basic-container \
  -p 8000:8000 \
  -v ~/basic-memory-data:/app/data \
  ghcr.io/basicmachines-co/basic-memory:latest

The server will be available at http://localhost:8000/mcp.

Image Details

Registry

Images are published to GitHub Container Registry (GHCR):

ghcr.io/basicmachines-co/basic-memory

Available Tags

Architectures

Multi-platform images are available for:

• linux/amd64 (Intel/AMD)
• linux/arm64 (Apple Silicon, ARM servers)

Docker automatically pulls the correct architecture for your platform.

Configuration

Environment Variables

Volume Mounts

Mount a local directory to persist data:

docker run -d \
  -v /path/to/local/data:/app/data \
  -p 8000:8000 \
  ghcr.io/basicmachines-co/basic-memory:latest

Port Configuration

The container exposes port 8000 by default. Map to a different host port if needed:

docker run -d \
  -p 3000:8000 \
  ghcr.io/basicmachines-co/basic-memory:latest

Docker Compose

For more complex setups, use Docker Compose:

version: '3.8'

services:
  basic-container:
    image: ghcr.io/basicmachines-co/basic-memory:latest
    container_name: basic-container
    ports:
      - "8000:8000"
    volumes:
      - ./data:/app/data
    environment:
      - BASIC_MEMORY_HOME=/app/data/basic-memory
    restart: unless-stopped
    healthcheck:
      test: ["CMD", "basic-memory", "--version"]
      interval: 30s
      timeout: 10s
      retries: 3

Run with:

docker compose up -d

Connecting to the Server

MCP SSE Configuration

Configure your MCP client to connect via SSE transport:

{
  "mcpServers": {
    "basic-memory": {
      "transport": {
        "type": "sse",
        "url": "http://localhost:8000/mcp"
      }
    }
  }
}

Health Check

Verify the server is running:

curl http://localhost:8000/health

Or check container health:

docker inspect --format='{{.State.Health.Status}}' basic-container

Running CLI Commands

You can run Basic Memory CLI commands inside the container. Note that the first argument is the container name (basic-container) and the second is the CLI command (basic-memory):

# Check version
docker exec basic-container basic-memory --version

# Check status
docker exec basic-container basic-memory status

# List projects
docker exec basic-container basic-memory project list

Security

The container runs as a non-root user (appuser) for security. Key security features:

• Non-root execution (UID/GID 1000 by default)
• No unnecessary packages installed
• Health checks enabled
• Slim base image (Python 3.12 slim-bookworm)

Custom UID/GID

Build with custom user IDs for permission compatibility:

docker build --build-arg UID=1001 --build-arg GID=1001 -t basic-memory:custom .

Troubleshooting

Permission Denied Errors

If you see permission errors with mounted volumes:

# Fix ownership on host
sudo chown -R 1000:1000 /path/to/local/data

# Or run with matching UID
docker run --user $(id -u):$(id -g) ...

Container Exits Immediately

Check the logs:

docker logs basic-container

Common causes:

• Port 8000 already in use
• Volume mount path doesn’t exist
• Insufficient permissions

SSE vs Stdio Transport

For Claude Desktop integration, either:

1. Install Basic Memory locally via Homebrew or pip
2. Use the SSE transport configuration (if your Claude Desktop version supports it)

Building from Source

Clone the repository and build locally:

git clone https://github.com/basicmachines-co/basic-memory.git
cd basic-memory
docker build -t basic-memory:local .

See Also

• Getting Started - Local installation options
• CLI Reference - Command line interface
• MCP Tools Reference - Available MCP tools