statewavedev/statewave repository overview

⁠Statewave server

Open-source memory runtime for AI agents — episodes in, distilled memories out.

Multi-arch (linux/amd64, linux/arm64), built with provenance + SBOM and signed via Sigstore.

⁠Quickstart with Docker Compose

services:
  db:
    image: pgvector/pgvector:pg16
    environment:
      POSTGRES_USER: statewave
      POSTGRES_PASSWORD: statewave
      POSTGRES_DB: statewave
    volumes:
      - pgdata:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U statewave"]
      interval: 2s
      timeout: 5s
      retries: 10

  api:
    image: statewavedev/statewave:latest
    ports: ["8100:8100"]
    environment:
      STATEWAVE_DATABASE_URL: postgresql+asyncpg://statewave:statewave@db:5432/statewave
      # Optional. With no key, Statewave runs in demo mode (local regex
      # compiler, no external calls). Set a key for real LLM extraction
      # and semantic search — see the Getting Started guide linked below.
      # STATEWAVE_LITELLM_API_KEY: sk-...
    depends_on:
      db:
        condition: service_healthy

volumes:
  pgdata:

docker compose up -d
curl http://localhost:8100/healthz   # → {"status":"ok"}
curl http://localhost:8100/readyz    # → {"status":"ready", ...}

New to Statewave? The Getting Started guide⁠ walks through clone → run → store and retrieve your first memory in about 5 minutes.

⁠Pin a version

STATEWAVE_VERSION=1.3.0 docker compose up -d

⁠Handling port conflicts

Local deployments frequently encounter port conflicts if services like PostgreSQL or other applications already use ports 5432 (database), 8100 (API) or 8080 (admin console). Override the host ports using environment variables. Only the host-side port changes — traffic between the containers (e.g. admin → API) stays on the internal compose network and is unaffected:

# Use custom ports instead of defaults
STATEWAVE_DB_HOST_PORT=5433 STATEWAVE_ADMIN_HOST_PORT=8081 docker compose up -d

Or set them in a .env file next to docker-compose.yml:

# .env
STATEWAVE_DB_HOST_PORT=5433
STATEWAVE_ADMIN_HOST_PORT=8081

Then start as usual:

docker compose up -d

⁠Service port reference

⁠Troubleshooting port conflicts

Error: bind: address already in use

1. Identify the conflicting process:

   # On macOS/Linux
   lsof -i :5432  # Check database port
   lsof -i :8100  # Check API port
   lsof -i :8080  # Check admin port
   

   Copy

2. Choose one of:

   • Kill the other process (if it's not needed)
   • Change the Statewave port (recommended for local dev) — set STATEWAVE_DB_HOST_PORT, STATEWAVE_API_HOST_PORT and/or STATEWAVE_ADMIN_HOST_PORT
   • Change the other service's port (if you control it)

3. Start Statewave with the new ports:

   STATEWAVE_DB_HOST_PORT=5433 STATEWAVE_ADMIN_HOST_PORT=8081 docker compose up -d
   

   Copy

4. Update anything that targets the remapped host ports. In-cluster addresses are unchanged — only host-side clients need the new port:

   # API remapped to host port 8101 instead of 8100
   curl http://localhost:8101/healthz
   
   # A client connecting directly to the DB on a custom host port (5433):
   export STATEWAVE_DATABASE_URL=postgresql+asyncpg://statewave:statewave@localhost:5433/statewave
   

   Copy

⁠Environment variable precedence

• Command-line variables override .env file variables: STATEWAVE_DB_HOST_PORT=5433 docker compose up -d takes precedence over STATEWAVE_DB_HOST_PORT=5434 in .env
• If neither is set, defaults are used (5432 for DB, 8100 for API, 8080 for admin)

⁠Tags

⁠Verify the build attestation

gh attestation verify \
  oci://docker.io/statewavedev/statewave:latest \
  --owner smaramwbc

⁠Source & docs

• Repository: https://github.com/smaramwbc/statewave⁠
• Documentation: https://statewave.ai⁠
• License: Apache-2.0