Docker Deployment

Memory Service is distributed as a Docker image, making it easy to deploy in any container environment.

Quick Start

Pull and run the latest image:

docker run -d \
  --name memory-service \
  -p 8080:8080 \
  -e MEMORY_SERVICE_DB_URL=postgres://postgres:postgres@host.docker.internal:5432/memoryservice?sslmode=disable \
  ghcr.io/chirino/memory-service:latest

Docker Compose

For a complete local setup with all dependencies:

version: "3.8"

services:
  memory-service:
    image: ghcr.io/chirino/memory-service:latest
    ports:
      - "8080:8080" # REST API
      - "9000:9000" # gRPC API
    environment:
      - MEMORY_SERVICE_DB_URL=postgres://postgres:postgres@postgres:5432/memoryservice?sslmode=disable
      - MEMORY_SERVICE_DB_MIGRATE_AT_START=true
    depends_on:
      postgres:
        condition: service_healthy

  postgres:
    image: pgvector/pgvector:pg18
    environment:
      - POSTGRES_DB=memoryservice
      - POSTGRES_USER=postgres
      - POSTGRES_PASSWORD=postgres
    volumes:
      - postgres_data:/var/lib/postgresql
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U postgres"]
      interval: 5s
      timeout: 5s
      retries: 5

volumes:
  postgres_data:

Save as docker-compose.yml and run:

docker compose up -d

Environment Variables

Database Configuration

Vector Store Configuration

SQLite Example

services:
  memory-service:
    image: ghcr.io/chirino/memory-service:latest
    environment:
      MEMORY_SERVICE_DB_KIND: sqlite
      MEMORY_SERVICE_DB_URL: /data/memory-service.sqlite
      MEMORY_SERVICE_ATTACHMENTS_KIND: fs
      MEMORY_SERVICE_VECTOR_KIND: sqlite
      MEMORY_SERVICE_EMBEDDING_KIND: local
    volumes:
      - ./data:/data

With this configuration, attachment bytes are stored under /data/memory-service.sqlite.attachments unless MEMORY_SERVICE_ATTACHMENTS_FS_DIR is set explicitly.

Authentication

Health Checks

The container exposes health endpoints:

# Liveness
curl http://localhost:8080/health

# Readiness
curl http://localhost:8080/ready

Configure in Docker Compose:

healthcheck:
  test: ["CMD", "curl", "-f", "http://localhost:8080/ready"]
  interval: 30s
  timeout: 10s
  retries: 3
  start_period: 10s

Resource Limits

Set appropriate resource limits:

services:
  memory-service:
    deploy:
      resources:
        limits:
          cpus: "2"
          memory: 1G
        reservations:
          cpus: "0.5"
          memory: 512M

Production Configuration

For production deployments:

services:
  memory-service:
    image: ghcr.io/chirino/memory-service:999-SNAPSHOT  # Pin to specific version
    restart: unless-stopped
    environment:
      # Database connection
      - MEMORY_SERVICE_DB_URL=postgres://postgres:${DB_PASSWORD}@postgres:5432/memoryservice?sslmode=disable
      # Enable TLS
      - MEMORY_SERVICE_TLS_CERT_FILE=/certs/server.crt
      - MEMORY_SERVICE_TLS_KEY_FILE=/certs/server.key
    volumes:
      - ./certs:/certs:ro

Multi-Container Setup

With separate embedding service:

services:
  memory-service:
    image: ghcr.io/chirino/memory-service:latest
    environment:
      - MEMORY_SERVICE_EMBEDDING_URL=http://embedding-service:8000
    depends_on:
      - embedding-service
      - postgres

  embedding-service:
    image: your-embedding-service:latest
    environment:
      - MODEL=text-embedding-ada-002
      - OPENAI_API_KEY=${OPENAI_API_KEY}

  postgres:
    image: pgvector/pgvector:pg18
    # ... configuration

Logging

View container logs:

docker logs -f memory-service

The service writes structured log output to stdout. Use your container runtime’s log driver or a sidecar to ship logs to your preferred backend.

Networking

For inter-container communication:

networks:
  memory-network:
    driver: bridge

services:
  memory-service:
    networks:
      - memory-network

  postgres:
    networks:
      - memory-network

  my-agent:
    networks:
      - memory-network
    environment:
      - MEMORY_SERVICE_URL=http://memory-service:8080

Next Steps

• Configure Database Setup
• Learn about Service Configuration