Engine / Deployment

Deployment.

The Keyoku engine is a single Go binary with no external dependencies. Deploy it as a binary, a Docker container, or a systemd service. All it needs is a session token, an LLM API key, and a place to write its SQLite file.

Option 1

Download the binary.

Download a prebuilt binary from GitHub releases, or build from source.

# Download latest release (Linux amd64)
curl -L -o keyoku-engine \
  https://github.com/Keyoku-ai/keyoku-engine/releases/latest/download/keyoku-engine-linux-amd64
chmod +x keyoku-engine

# Or build from source
git clone https://github.com/Keyoku-ai/keyoku-engine.git
cd keyoku-engine
make build

# Run it
export KEYOKU_SESSION_TOKEN=$(openssl rand -hex 16)
export KEYOKU_EXTRACTION_PROVIDER=gemini
export GEMINI_API_KEY=your-api-key
./keyoku-engine

Option 2

Docker Compose.

Run the engine as a Docker container with persistent storage.

# docker-compose.yml
version: "3.8"

services:
  keyoku-engine:
    image: ghcr.io/keyoku-ai/keyoku-engine:latest
    ports:
      - "18900:18900"
    volumes:
      - keyoku-data:/data
    environment:
      - KEYOKU_SESSION_TOKEN=${KEYOKU_SESSION_TOKEN}
      - KEYOKU_DB_PATH=/data/keyoku.db
      - KEYOKU_EXTRACTION_PROVIDER=${KEYOKU_EXTRACTION_PROVIDER}
      - KEYOKU_EXTRACTION_MODEL=${KEYOKU_EXTRACTION_MODEL:-}
      - GEMINI_API_KEY=${GEMINI_API_KEY:-}
      - OPENAI_API_KEY=${OPENAI_API_KEY:-}
      - ANTHROPIC_API_KEY=${ANTHROPIC_API_KEY:-}
    restart: unless-stopped
    healthcheck:
      test: ["CMD", "curl", "--fail", "http://localhost:18900/api/v1/health"]
      interval: 30s
      timeout: 5s
      retries: 3

volumes:
  keyoku-data:

Option 3

Systemd service.

Run the engine as a background service on Linux with automatic restart.

# /etc/systemd/system/keyoku-engine.service
[Unit]
Description=Keyoku Memory Engine
After=network.target

[Service]
Type=simple
User=keyoku
Group=keyoku
ExecStart=/usr/local/bin/keyoku-engine
EnvironmentFile=/etc/keyoku/env
Restart=always
RestartSec=5
StandardOutput=journal
StandardError=journal

[Install]
WantedBy=multi-user.target

# /etc/keyoku/env
KEYOKU_SESSION_TOKEN=your-secret-token
KEYOKU_DB_PATH=/var/lib/keyoku/keyoku.db
KEYOKU_EXTRACTION_PROVIDER=gemini
GEMINI_API_KEY=your-api-key
KEYOKU_CORS_ORIGINS=https://yourdomain.com

# Enable and start
sudo systemctl daemon-reload
sudo systemctl enable keyoku-engine
sudo systemctl start keyoku-engine
sudo systemctl status keyoku-engine

Environment

Required environment variables.

These are the minimum variables needed for any deployment. See the Configuration page for the full list.

KEYOKU_SESSION_TOKEN

Bearer token for API authentication.

Generate with: openssl rand -hex 16.

KEYOKU_DB_PATH

Path to SQLite database file. Default: ./keyoku.db.

Use a persistent volume in containers to avoid data loss on restart.

KEYOKU_EXTRACTION_PROVIDER

LLM provider for memory extraction: gemini, openai, anthropic, or ollama.

KEYOKU_EXTRACTION_MODEL

Specific model name. Optional — falls back to provider default.

KEYOKU_EMBEDDING_PROVIDER

Embedding provider. Defaults to extraction provider if unset.

API key

GEMINI_API_KEY, OPENAI_API_KEY, ANTHROPIC_API_KEY, or OLLAMA_API_KEY — whichever matches your provider.

Verification

Health check.

After starting the engine, verify it is running by hitting the health endpoint.

# Check engine health
curl http://localhost:18900/api/v1/health

# Expected response
{
  "status": "ok",
  "version": "1.0.0",
  "uptime": "2h15m",
  "memories": 1247,
  "db_size": "12.4MB"
}

Production

Production tips.

WAL mode is automatic

SQLite WAL (Write-Ahead Logging) is enabled by default.

This allows concurrent reads during writes. No configuration needed.

CORS in production

Set KEYOKU_CORS_ORIGINS to add your specific domain(s).

Adds to the default localhost allowlist. Comma-separate multiple origins.

Backup strategy

Copy the SQLite database file while the engine is running.

WAL mode makes this safe. Use cp or rsync on a schedule. The file is fully self-contained.

Monitor health

Poll GET /api/v1/health on an interval.

The endpoint returns uptime, version, memory count, and database size. Use it for load balancer health checks.

Resource usage

Typical idle footprint: ~64MB RAM, near-zero CPU.

Memory grows with HNSW index size. The 10,000-entry default keeps the index under 100MB.

Log output

The engine logs to stdout in structured format.

Redirect to a file or log aggregator in production. Set KEYOKU_LOG_LEVEL for verbosity control.