Getting Started

Getting Started

Kleos is a multi-tenant semantic memory system for AI agents, built as a Rust workspace monorepo. This page covers building, configuring, and deploying the infrastructure.

Build Requirements

System Dependencies

The following tools must be present on the host system:

• Rust Toolchain: Version 1.94.0 or later, as declared in the workspace MSRV.
• Protobuf Compiler (protoc): Required for LanceDB and GRPC-based OpenTelemetry export.
  • Linux: sudo apt install protobuf-compiler libpcsclite-dev
  • macOS: brew install protobuf
  • Windows: choco install protoc -y
• ONNX Runtime: Kleos uses ort with dynamic loading. No link-time dependency, but the shared library (libonnxruntime.so / onnxruntime.dll) must be discoverable at runtime for embedding generation.

Build Profiles

Profile	Configuration	Use Case
release	Fat LTO, 1 Codegen Unit, Stripped	Maximum runtime performance for stable releases.
release-prod	Thin LTO, 16 Codegen Units	Faster CI/CD builds with high performance.
release-local	Thin LTO, Debug Symbols	Local profiling and performance debugging.
bench	Thin LTO, No Stripping	Criterion benchmark suite execution.

Installation

Installer Scripts

Automated installer scripts in dist/ detect OS/architecture and download verified binaries from GitHub releases.

• Unix (Linux/macOS): dist/install.sh
• Windows (PowerShell): dist/install.ps1

Install Profiles

The installers support three functional profiles via the KLEOS_PROFILE environment variable:

1. server (Default): Installs kleos-server, kleos-cli, and kleos-mcp.
2. agent-host: Installs tools for the machine where the AI agent runs: kleos-cli, kleos-sh, kr, kw, ke, agent-forge, eidolon-supervisor, and kleos-cred/credd.
3. full: Installs every binary in the workspace.

Docker

A two-stage Dockerfile uses rust:1.94-bookworm for the builder and debian:bookworm-slim for runtime.

• Default Port: 4200
• Data Volume: /data

Configuration

Environment Variables

Kleos uses a prefix-migration shim. At startup, if KLEOS_X is set, it mirrors the value to ENGRAM_X to maintain compatibility with legacy integrations.

Variable	Description	Default
KLEOS_HOST	Server bind address.	127.0.0.1 (Container: 0.0.0.0)
KLEOS_PORT	Server bind port.	4200
KLEOS_DATA_DIR	Base directory for all tenant data.	./data
KLEOS_DB_PATH	Path to the primary SQLite database.	$DATA_DIR/kleos.db
KLEOS_DB_KEY	64-char hex key for SQLCipher encryption.	None

Database Resolution

The resolve_db_path function handles the transition from the legacy "Engram" name. If kleos.db is configured but does not exist and an engram.db is present in the same directory, the server falls back to the legacy file.

First-Run Setup

1. Start the Server

kleos-server

This initializes the base data directory and the global management database.

2. Bootstrap a Tenant

Kleos is strictly multi-tenant. You must create a user/tenant and an API key before storing memories. Set KLEOS_BOOTSTRAP_SECRET on the server, then POST the secret to the bootstrap endpoint:

# Server must have KLEOS_BOOTSTRAP_SECRET set in its environment
curl -s -X POST http://localhost:4200/bootstrap \
  -H "Content-Type: application/json" \
  -d '{"secret":"your_bootstrap_secret"}'

This returns a JSON response with an api_key field. Save this to your environment as KLEOS_API_KEY.

3. Minimal Workflow

The following sequence demonstrates the core memory pipeline: Store -> Search -> Context.

Store a Memory:

kleos-cli store "The project deadline is June 15th" --label "project-alpha" --importance 8

Implementation: Dispatches to MemoryService::store, which triggers embedding generation and SQLite/LanceDB indexing.

Search Memories:

kleos-cli search "When is the deadline?"

Implementation: Runs a 4-channel hybrid search, fusing FTS5 and Vector results via Reciprocal Rank Fusion (RRF).

Retrieve Context:

kleos-cli context "Prepare a report on project-alpha"

Implementation: Ranks memories by relevance and packs them into a structured prompt format for LLM consumption.