Skip to content

docker.mdx

Latest commit

 

History

History
251 lines (177 loc) · 5.66 KB

docker.mdx

File metadata and controls

251 lines (177 loc) · 5.66 KB
layout @/layouts/DocsLayout.astro
title Docker
description Run Basic Memory in Docker containers for server deployments and SSE transport

import { Card, CardGroup, Info, Warning, Note, Tip, Steps, Step, CodeGroup, CodeTab } from '@/components'

The Docker image runs Basic Memory as an **SSE server** on port 8000. This is designed for server deployments where clients connect over HTTP, not for local MCP stdio connections with Claude Desktop.

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.

The `-v` flag mounts a local directory for persistent storage. Without it, your data will be lost when the container stops.

Image Details

Registry

Images are published to GitHub Container Registry (GHCR):

ghcr.io/basicmachines-co/basic-memory

Available Tags

Tag Description
latest Latest stable release
0.17.5 Specific version
0.17 Latest patch for minor version

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

Variable Default Description
BASIC_MEMORY_HOME /app/data/basic-memory Path to Basic Memory data
BASIC_MEMORY_PROJECT_ROOT /app/data Root directory for projects

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

The Docker image is configured for SSE transport only. It cannot be used as a stdio MCP server for Claude Desktop directly.

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