Skip to content

Deploy

From the source repository

The Docker and compose files named here are in the source repository, which is not public. Any image that runs pip install kioko and kioko serve works the same way.

A Dockerfile based on python:3.14-slim, a one-command local stack (compose.yml: service + console + Postgres/pgvector on http://127.0.0.1:8770, API key kioko-local-test-key) and docker-compose.stores.yml (Postgres + pgvector, Qdrant and the service) are included.

docker compose up --build -d --wait                           # local stack, uses examples/config/pgvector.json

docker build -t kioko .                                       # SQLite / Qdrant
docker build -t kioko --build-arg KIOKO_EXTRAS=pgvector .     # + Postgres/pgvector (psycopg)
docker run -p 8765:8765 -v kioko-data:/data -e KIOKO_API_KEY=... kioko \
  kioko serve --host 0.0.0.0 --db /data/memory.db --intelligence

export KIOKO_PG_PASSWORD=... KIOKO_API_KEY=...
docker compose -f docker-compose.stores.yml up -d             # Postgres + pgvector, Qdrant, the service

Production notes

  • Embeddings. The default HashingEmbedder is lexical: it matches words, word pairs and character trigrams, not meaning, so "car" and "automobile" don't match. Use OpenAIEmbedder, AzureOpenAIEmbedder, AgnoEmbedder or FunctionEmbedder for semantic recall. After you change embedders, run memory.reembed() once. Tune HybridRanker(min_vector_only=...) to your embedder's cosine range.
  • Extraction and management. The offline rules and intelligence cover common English phrasings: identity, location, work, likes and dislikes, instructions, goals and progress, decisions and changes, procedures, lessons, dated events, "remember ..." and "forget ...". For open-ended conversations and other languages, give the intelligence a model (kioko.intelligent(llm=...)); the rules stay as gate and fallback.
  • Scale. Without vector_search, search scores every memory in the user's scope: about 5–30 ms for a few hundred memories, ~150 ms for 1,000. Past that, use the pgvector or Qdrant store. The service is a threaded standard-library server, which is enough for an internal agent fleet. For heavy traffic, run several instances behind a load balancer on Postgres, and lower context_cache_ttl.
  • Secrets and PII. DropSecrets is on by default (passwords, API keys, tokens, private keys, card numbers). Add RedactPII to mask e-mails and phone numbers. Processors run on every write and every update, through any channel (Python, REST, MCP, tools, console).
  • Languages. Storage, tokenization, the offline embedder and search work in any script, and tool and MCP output keeps non-ASCII text readable. The rule-based extraction only understands English, so use a model (LLMExtractor, or the intelligence with llm=) for other languages.
  • Python 3.14 annotations. Annotations are evaluated lazily in 3.14 (PEP 649), so an agent function may annotate with a class defined later in the module. attach() / with_memory never force that evaluation: they read signatures with annotationlib.Format.FORWARDREF and copy the lazy __annotate__ function.
  • Concurrency. SQLite runs in WAL mode with one serialized connection per process. That's fine for a service plus the console. For many writers, use Postgres + pgvector.