MCP Memoria - Docker Quick Start & Automated Releases

Zero-Install Setup

Since launching MCP Memoria and adding the Web UI & Knowledge Graph, the most common friction point has been the initial setup: cloning the repo, installing Python dependencies, configuring paths. Too many steps for what should be a straightforward tool.

Starting with v1.4, Memoria ships pre-built Docker images on GitHub Container Registry. The setup is now two commands and a config paste — no git clone, no Python install, no build step.

Quick Start

All you need is Docker and Ollama running with the nomic-embed-text model.

1. Start backend services

mkdir -p memoria && cd memoria
curl -O https://raw.githubusercontent.com/trapias/memoria/main/docker/docker-compose.server.yml
docker compose -f docker-compose.server.yml up -d

This starts Qdrant (vector search), PostgreSQL (knowledge graph & time tracking), and the Web UI with REST API.

2. Configure your MCP client

Add this to your Claude Code config (~/.claude.json):

{
  "mcpServers": {
    "memoria": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "--network", "memoria-network",
        "-e", "MEMORIA_QDRANT_HOST=qdrant",
        "-e", "MEMORIA_QDRANT_PORT=6333",
        "-e", "MEMORIA_DATABASE_URL=postgresql://memoria:memoria_dev@postgres:5432/memoria",
        "-e", "MEMORIA_OLLAMA_HOST=http://host.docker.internal:11434",
        "-e", "MEMORIA_LOG_LEVEL=WARNING",
        "ghcr.io/trapias/memoria:latest"
      ]
    }
  }
}

The same configuration works with Claude Desktop, OpenCode, Cursor, and any MCP-compatible client — just adapt the format. See the README for examples.

3. Verify

Open a Claude session and ask:

Show me the memoria stats

If you see statistics, you’re done. Open http://localhost:3000 for the Web UI.

How It Works

Each MCP session spawns its own ephemeral Memoria container via docker run --rm -i. The container connects to the shared backend services (Qdrant, PostgreSQL) through a Docker network, and communicates with the MCP client via stdio.

┌─────────────────────────────────────────────────────┐
│  Docker Services (docker-compose.server.yml)        │
│  ┌──────────┐  ┌──────────┐  ┌──────────────────┐  │
│  │  Qdrant  │  │ Postgres │  │ Web UI + REST API│  │
│  │  :6333   │  │  :5433   │  │ :3000    :8765   │  │
│  └──────────┘  └──────────┘  └──────────────────┘  │
└────────────────────────┬────────────────────────────┘
                         │ memoria-network
┌────────────────────────┼────────────────────────────┐
│  MCP Client            │                            │
│       ┌────────────────┴─────────────────┐          │
│       │  ghcr.io/trapias/memoria:latest  │          │
│       │  (one container per session)     │          │
│       └──────────────────────────────────┘          │
└─────────────────────────────────────────────────────┘

Why one container per session? Memoria maintains in-memory WorkingMemory — current project context, session history, recently accessed memories. Sharing a single container between concurrent Claude sessions would mix context. The per-session approach ensures complete isolation, and --rm cleans up automatically when the session ends.

Automated Release Pipeline

Releases are now fully automated via GitHub Actions. The workflow:

1. A version bump in pyproject.toml is pushed to main
2. The CI detects the new version and creates a git tag
3. Both Docker images are built and pushed to GHCR in parallel
4. A GitHub Release is created with auto-generated release notes

No manual tagging, no manual builds. Change the version number, push, and the pipeline handles the rest.

Update Checker

Memoria now checks for updates at startup. When a newer version is available, you’ll see a message in the logs suggesting the update command — docker compose pull for Docker users, pip install --upgrade for native installs.

The check is non-blocking (2-second timeout), cached for 24 hours, and can be disabled with MEMORIA_SKIP_UPDATE_CHECK=true or the --skip-update-check flag.

CLI Improvements

The mcp-memoria command now supports:

mcp-memoria                      # Start MCP server
mcp-memoria --version            # Show version
mcp-memoria --update             # Self-update (native installs)
mcp-memoria --skip-update-check  # Start without update check

Updating

# Update backend services
docker compose -f docker-compose.server.yml pull
docker compose -f docker-compose.server.yml up -d

# Update the MCP client image
docker pull ghcr.io/trapias/memoria:latest

To pin a specific version, replace :latest with a version tag (e.g., :1.4.2) in your MCP client config.

Docker Images

The pre-built images are available on GitHub Container Registry:

• ghcr.io/trapias/memoria — MCP server (stdio client)
• ghcr.io/trapias/memoria-ui — Web UI + REST API

Full documentation and source code: github.com/trapias/memoria