QuickstartDocker Compose

Quickstart — Docker Compose

Two containers. Postgres with pgvector, and Mnemosyne. That’s the whole stack. You can run this on a laptop, a VPS, a Raspberry Pi, or a CI runner.

Save the compose file

docker-compose.yml
services:
  postgres:
    image: pgvector/pgvector:pg17
    environment:
      POSTGRES_PASSWORD: mnemo
      POSTGRES_USER: mnemo
      POSTGRES_DB: mnemo
    volumes:
      - mnemo_pg:/var/lib/postgresql/data
    ports:
      - "55432:5432"
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U mnemo -d mnemo"]
      interval: 2s
      timeout: 2s
      retries: 30
 
  mnemosyne:
    image: ghcr.io/lucasmailland/mnemosyne-server:latest
    environment:
      DATABASE_URL: postgres://mnemo:mnemo@postgres:5432/mnemo
      # The next two are OPTIONAL. Leave them empty and Mnemosyne runs in
      # FTS-only mode (Mode A). Set them to enable vector recall.
      # MNEMO_LLM_PROVIDER: openai
      # MNEMO_LLM_API_KEY: sk-...
    ports:
      - "3000:3000"
    depends_on:
      postgres:
        condition: service_healthy
 
volumes:
  mnemo_pg:

Boot the stack

docker compose up -d
docker compose logs -f mnemosyne

You should see the migration runner apply schema, the OpenAPI document publish on :3000/openapi.json, and the readiness probe go green.

Write your first fact

curl -X POST http://localhost:3000/v1/facts \
  -H "Authorization: Bearer mns_live_demo_key_change_me" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "Lucas prefers espresso to filter coffee in the morning",
    "tags": ["preferences", "coffee"]
  }'

You get back a fact id, a bitemporal window, and the trust attribution. None of those fields required a vector — Mnemosyne wrote the fact and queued it for embedding if a provider is configured.

Recall it

curl -X POST http://localhost:3000/v1/recall \
  -H "Authorization: Bearer mns_live_demo_key_change_me" \
  -H "Content-Type: application/json" \
  -d '{ "query": "coffee preferences", "topK": 3 }'

In Mode A (no embedding provider) the recall is FTS-only and instant. In Mode B/C (provider attached) the same call returns a vector-blended result set.

Health check

curl http://localhost:3000/v1/health \
  -H "Authorization: Bearer mns_live_demo_key_change_me"

You get a live snapshot — fact count, embedded ratio, recall hit rate, last write timestamp.

⚠️

The mns_live_demo_key_change_me token is a placeholder. Mint a real workspace key with the create-api-key script and use it in the Authorization header: docker compose exec server node scripts/create-api-key.cjs --workspace your-ws-id.

What just happened

  • PostgreSQL was brought up with the pgvector extension preloaded.
  • Mnemosyne booted, ran every migration in order, and started serving the OpenAPI spec on port 3000.
  • Your first fact was written to mnemo_fact with a valid_from = now() and valid_to = NULL — the row will stay current until something supersedes it.
  • The recall pipeline ran through tier 3 (full hybrid). With embeddings off it skipped the vector stages; with embeddings on it would have also done HNSW cosine + rerank.

Where to go next

  • Concepts — read Bitemporal model and Cognitive primitives before you build on top.
  • MCP — point Claude Desktop or Cursor at this instance and your IDE starts using Mnemosyne automatically.
  • Operations — learn how to back up and monitor before you put it in production.
Full guide — empty DB to first recallNode / TypeScript