Docker Setup

Run the full Engram Community Edition stack locally. One container, fully private, no external calls.

---

What's Inside

The engrammemory/engram-stack image bundles three services:

Everything runs locally. No data leaves the container.

---

System Requirements

---

Quick Start

docker run -d \
  --name engram \
  -p 8585:8585 \
  -p 6333:6333 \
  -p 11435:11435 \
  -v engram-data:/data \
  engrammemory/engram-stack

Verify it's running:

curl http://localhost:8585/v1/connect

Expected response:

{
  "connected": true,
  "latency_ms": 8,
  "qdrant": "healthy",
  "embedding": "healthy",
  "version": "0.2.0"
}

---

Configuration

Pass configuration as environment variables:

docker run -d \
  --name engram \
  -p 8585:8585 \
  -p 6333:6333 \
  -p 11435:11435 \
  -v engram-data:/data \
  -e ENGRAM_COLLECTION="my-project" \
  -e ENGRAM_AUTO_RECALL=true \
  -e ENGRAM_MIN_RECALL_SCORE=0.6 \
  engrammemory/engram-stack

Configuration Options

---

Data Persistence

Memory data lives in the /data directory inside the container. Mount a volume to persist across restarts:

# Named volume (recommended)
-v engram-data:/data

# Bind mount to host directory
-v /path/on/host/engram:/data

The /data directory contains:

Backup

# Stop the container first for a clean snapshot
docker stop engram
docker run --rm -v engram-data:/data -v $(pwd):/backup \
  alpine tar czf /backup/engram-backup.tar.gz /data
docker start engram

Restore

docker stop engram
docker run --rm -v engram-data:/data -v $(pwd):/backup \
  alpine tar xzf /backup/engram-backup.tar.gz -C /
docker start engram

---

External Qdrant

To use your own Qdrant instance instead of the bundled one, point ENGRAM_QDRANT_URL at it and skip exposing port 6333:

docker run -d \
  --name engram \
  -p 8585:8585 \
  -p 11435:11435 \
  -e ENGRAM_QDRANT_URL="https://my-qdrant.example.com:6333" \
  engrammemory/engram-stack

---

Upgrading

docker pull engrammemory/engram-stack:latest
docker stop engram
docker rm engram
docker run -d \
  --name engram \
  -p 8585:8585 \
  -p 6333:6333 \
  -p 11435:11435 \
  -v engram-data:/data \
  engrammemory/engram-stack

Data in the engram-data volume is preserved across upgrades. The container runs migrations automatically on startup.

---

Cloud Overflow

Connect your self-hosted instance to the Engram platform for cloud overflow storage. When local storage fills up or you want cross-device sync, memories overflow to the platform.

docker run -d \
  --name engram \
  -p 8585:8585 \
  -p 6333:6333 \
  -p 11435:11435 \
  -v engram-data:/data \
  -e ENGRAM_API_KEY="pr_live_xxxxx" \
  engrammemory/engram-stack

Setting ENGRAM_API_KEY enables:

• Overflow storage: Memories exceeding local capacity sync to the platform
• Cross-device recall: Search returns results from both local and cloud
• Intelligence pipeline: Access to advanced compression and deduplication

Local memories remain local. Only overflow and explicitly synced memories reach the platform.

---

Privacy

The Community Edition is designed for full privacy:

• No telemetry. No usage data, analytics, or phone-home behavior.
• No external calls. Embedding runs locally via FastEmbed. No API calls to OpenAI, Cohere, or any third party.
• No accounts required. Works without an API key for purely local use.
• Open source. Inspect every line of code.

The only time the container makes external network requests is when ENGRAM_API_KEY is set for cloud overflow, and only for explicit sync operations.

---

Connecting MCP Clients

Once the container is running, connect any MCP client:

Claude Code:

claude mcp add engram-memory --transport http --url http://localhost:8585/mcp

Claude Desktop — add to config JSON:

{
  "mcpServers": {
    "engram-memory": {
      "transport": "http",
      "url": "http://localhost:8585/mcp"
    }
  }
}

SDK:

from engrammemory import Engram
client = Engram(base_url="http://localhost:8585/v1")

See MCP Server for full client setup instructions.

---

Troubleshooting

Container exits immediately: Check logs with docker logs engram. Common cause: insufficient RAM (need 4 GB minimum).

Slow first request: The embedding model loads on first use. Initial request may take 10-30 seconds. Subsequent requests are fast.

Port conflicts: If ports 6333, 8585, or 11435 are in use, remap them:

docker run -d --name engram \
  -p 9585:8585 -p 7333:6333 -p 12435:11435 \
  -v engram-data:/data \
  engrammemory/engram-stack

Then connect to http://localhost:9585/mcp.

---

Next Steps

• MCP Server — Connect AI agents via MCP
• Agent Frameworks — LangChain, LlamaIndex, and more
• Platform vs Community — Compare deployment models