Engine / Configuration

Configuration.

All configuration is done through environment variables. The engine reads them on startup — no config files needed. Set them in your shell, a .env file, or your container orchestrator.

Only KEYOKU_SESSION_TOKEN is required. Everything else has sensible defaults.

Configuration

Server.

default: 18900

KEYOKU_PORT

HTTP server port. The engine listens on this port for all API requests.

default: ./keyoku.db

KEYOKU_DB_PATH

Path to the SQLite database file.

Created automatically on first run. WAL mode is enabled by default for concurrent read access.

default: localhost origins

KEYOKU_CORS_ORIGINS

Comma-separated list of additional allowed CORS origins.

Default allowlist includes localhost on ports 3000, 5173, 8080 and 127.0.0.1 equivalents. Add your own domains in production.

default: required

KEYOKU_SESSION_TOKEN

Bearer token for API authentication. All requests must include this token.

Generate with: openssl rand -hex 16. This is the only required configuration variable.

Configuration

LLM Extraction.

default: gemini

KEYOKU_EXTRACTION_PROVIDER

LLM provider for memory extraction.

Options: gemini, openai, anthropic, ollama. Determines which API is called to analyze conversation exchanges.

default: gemini-2.5-flash

KEYOKU_EXTRACTION_MODEL

Specific model to use for extraction.

Examples: gemini-2.5-flash, gpt-5-mini, claude-haiku-4-5-20251001, llama3.2. Falls back to provider default if unset.

Configuration

Embeddings.

default: same as extraction

KEYOKU_EMBEDDING_PROVIDER

Provider for generating embedding vectors.

Options: gemini, openai, anthropic, ollama. Defaults to the extraction provider if unset.

default: gemini-embedding-001

KEYOKU_EMBEDDING_MODEL

Specific model for embeddings.

Examples: gemini-embedding-001, text-embedding-3-small. Falls back to provider default if unset.

default: http://localhost:11434

OLLAMA_BASE_URL

Base URL for the Ollama server. Only used when provider is ollama.

default: 768

OLLAMA_EMBEDDING_DIMS

Embedding vector dimensions for Ollama models.

Must match the model output. Common values: 768, 1024, 1536.

Configuration

API Keys.

default: none

OPENAI_API_KEY

OpenAI API key. Required when using openai as extraction or embedding provider.

default: none

GEMINI_API_KEY

Google Gemini API key. Required when using gemini as extraction or embedding provider.

default: none

ANTHROPIC_API_KEY

Anthropic API key. Required when using anthropic as extraction or embedding provider.

default: none

OLLAMA_API_KEY

Ollama API key. Optional — only needed if your Ollama instance requires authentication.

Configuration

Quiet Hours.

default: false

KEYOKU_QUIET_HOURS_ENABLED

Enable quiet hours suppression.

When active, non-critical heartbeat signals are suppressed during the quiet window. Disabled by default.

default: 23

KEYOKU_QUIET_HOUR_START

Hour (0-23) when quiet hours begin. Signals below Immediate urgency are suppressed.

default: 7

KEYOKU_QUIET_HOUR_END

Hour (0-23) when quiet hours end. Normal signal processing resumes.

default: America/Los_Angeles

KEYOKU_QUIET_HOURS_TIMEZONE

IANA timezone string for quiet hours and time-period calculations.

Examples: America/New_York, Europe/London, Asia/Tokyo.

Configuration

Watcher.

default: false

KEYOKU_WATCHER_AUTO_START

Automatically start the heartbeat watcher when the engine boots.

If false, call POST /api/v1/watcher/start manually.

default: none

KEYOKU_WATCHER_ENTITY_IDS

Comma-separated entity IDs to watch on startup. Only used when auto_start is true.

default: 300000 (5m)

KEYOKU_WATCHER_BASE_INTERVAL

Base interval between heartbeat checks in milliseconds.

Adaptive multipliers adjust this based on context — time of day, signal density, memory velocity, and recent action.

default: 60000 (1m)

KEYOKU_WATCHER_MIN_INTERVAL

Minimum interval floor in milliseconds.

Even with aggressive multipliers, the watcher never checks faster than this.

default: 1800000 (30m)

KEYOKU_WATCHER_MAX_INTERVAL

Maximum interval ceiling in milliseconds.

Even in quiet periods, the watcher checks at least this often.

Configuration

Memory Lifecycle.

default: 0.95

SemanticDuplicateThresh

Cosine similarity threshold for semantic deduplication.

Memories above this threshold are considered duplicates and skipped during ingest.

default: 0.85

NearDuplicateThresh

Threshold for near-duplicate detection.

Memories between this and SemanticDuplicateThresh (0.95) are candidates for merging.

default: 0.3

DecayThreshold

Retention score below which a memory transitions from ACTIVE to STALE.

Stale memories are deprioritized in search results but still retrievable.

default: 30

ArchivalDays

Days after which STALE memories are moved to ARCHIVED state.

Archived memories are excluded from default searches but accessible via explicit ID lookup or archive queries.

default: 90

PurgeRetentionDays

Days after which DELETED memories are permanently purged from the database.

default: 500

HotCacheSize

Number of memories held in the LRU hot cache. Cache hits bypass HNSW search entirely.

default: 10000

MaxHNSWEntries

Maximum entries in the HNSW index before automatic consolidation triggers.

Keeps vector search performant by rebuilding the index when it grows beyond this limit.

Example

Minimal .env file.

# Required
KEYOKU_SESSION_TOKEN=a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6

# LLM provider
KEYOKU_EXTRACTION_PROVIDER=gemini
GEMINI_API_KEY=your-gemini-api-key

# Optional overrides
KEYOKU_PORT=18900
KEYOKU_DB_PATH=./data/keyoku.db
KEYOKU_QUIET_HOURS_TIMEZONE=America/New_York