• Docker and Docker Compose installed
• OpenAI API key configured

Copy the example environment file and add your OpenAI API key:

cp sample_configs/env.dockercompose .env
# Edit .env and add your OPENAI_API_KEY

Copy the sample configuration file and update it with your settings:

cp sample_configs/episodic_memory_config.sample configuration.yml
# Edit configuration.yml and update:
# - Replace <YOUR_API_KEY> with your OpenAI API key
# - Replace <YOUR_PASSWORD_HERE> with your Neo4j password
# - Update host from 'localhost' to 'neo4j' for Docker environment

Run the startup script:

./memmachine-compose.sh

This will:

• ✅ Check Docker and Docker Compose availability
• ✅ Verify .env file and OpenAI API key
• ✅ Check and create configuration.yml if needed
• ✅ Validate configuration settings
• ✅ Pull and start all services (PostgreSQL, Neo4j 5.23, MemMachine)
• ✅ Wait for all services to be healthy
• ✅ Display service URLs and connection info

docker-compose up -d

Once started, you can access:

• MemMachine API: http://localhost:8080
• Neo4j Browser: http://localhost:7474
• Health Check: http://localhost:8080/health
• Metrics: http://localhost:8080/metrics

# Test health endpoint
curl http://localhost:8080/health

# Test memory storage
curl -X POST "http://localhost:8080/v1/memories" \
  -H "Content-Type: application/json" \
  -d '{
    "session": {
      "group_id": "test-group",
      "agent_id": ["test-agent"],
      "user_id": ["test-user"],
      "session_id": "test-session-123"
    },
    "producer": "test-user",
    "produced_for": "test-user",
    "episode_content": "Hello, this is a test message",
    "episode_type": "text",
    "metadata": {"test": true}
  }'

./memmachine-compose.sh logs

./memmachine-compose.sh stop

./memmachine-compose.sh restart

./memmachine-compose.sh clean

./memmachine-compose.sh help

docker-compose logs -f

docker-compose down

docker-compose restart

docker-compose down -v

• PostgreSQL (port 5432): Profile memory storage with pgvector
• Neo4j (ports 7474, 7687): Episodic memory with vector similarity
• MemMachine (port 8080): Main API server (uses pre-built memmachine/memmachine image)

Key files:

• .env - Environment variables
• configuration.yml - MemMachine configuration
• docker-compose.yml - Service definitions
• memmachine-compose.sh - Startup script with validation and health checks

1. Database Configuration Consistency Make sure the database configuration details in configuration.yml match the database configuration details in .env

Both files must have consistent:

• Database hostnames (use service names: postgres, neo4j)
• Database ports (5432 for PostgreSQL, 7687 for Neo4j)
• Database credentials (usernames and passwords)
• Database names

2. Configuration.yml Setup The configuration.yml file contains MemMachine-specific settings:

• Model configuration: OpenAI API settings for LLM and embeddings
• Storage configuration: Neo4j connection details
• Memory settings: Session memory capacity and limits
• Reranker configuration: Search and ranking algorithms

Key settings to update in configuration.yml:

• Replace <YOUR_API_KEY> with your OpenAI API key (appears in both Model and embedder sections)
• Replace <YOUR_PASSWORD_HERE> with your Neo4j password
• Ensure the Neo4j host is set to neo4j (not localhost) for Docker environment

This ensures MemMachine can properly connect to the Docker services and use your OpenAI API key for embeddings and LLM operations.