Kleos

Native Nervous System for Autonomous Agents. Built in Rust.

High-integrity backbone for agentic reasoning, deterministic coordination, and associative memory. One binary. Total autonomy.

Why Kleos?

Building agents on loose collections of Python scripts creates fragile systems. Kleos provides the structural integrity autonomous software requires.

• Unified Cognitive OS. Seven built-in coordination services including Axon for events, Chiasm for tasks, and Loom for workflows. These form a deterministic foundation for complex behavior.
• High-Integrity Reasoning. You enforce engineering standards with Agent-Forge. It uses Tree-sitter for symbol-aware repository mapping and mandates a Spec, Hypothesis, and Verify workflow to prevent chaos.
• Native Performance and Security. You get an async Tokio core and in-process ONNX models. No Python dependencies or massive Docker images. SQLCipher encryption and YubiKey authority keep data on your hardware.
• Biologically-Inspired State. Kleos manages state with FSRS-6 decay and background dream cycles. It replays and consolidates memory traces to keep knowledge stable and relevant.

Quick Start

git clone https://github.com/Ghost-Frame/Kleos.git && cd Kleos
cargo build --release
./target/release/kleos-server

Server binds to 127.0.0.1:4200 by default. Set a bootstrap secret, start the server, then claim the admin key:

# Start the server with a bootstrap secret
KLEOS_BOOTSTRAP_SECRET=my-setup-secret ./target/release/kleos-server

# Bootstrap the admin key (one-time only)
curl -X POST http://localhost:4200/bootstrap \
  -H "Content-Type: application/json" \
  -d '{"secret": "my-setup-secret"}'

# Store a memory
curl -X POST http://localhost:4200/store \
  -H "Authorization: Bearer eg_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"content": "Production DB is PostgreSQL 16 on db.example.com:5432", "category": "reference"}'

# Search
curl -X POST http://localhost:4200/search \
  -H "Authorization: Bearer eg_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "database connection info"}'

MCP stdio entrypoint:

KLEOS_MCP_BEARER_TOKEN=eg_... cargo run -p kleos-mcp

The Ecosystem

Features

• FSRS-6 Spaced Repetition. Memories strengthen with use and decay when ignored. Power-law forgetting with trained parameters.
• 4-Channel Hybrid Search. Vector similarity, FTS5 full-text, personality signals, and graph traversal fused via Reciprocal Rank Fusion.
• Knowledge Graph. Auto-linking, Louvain community detection, weighted PageRank, cooccurrence, structural analysis.
• Personality Engine. Preferences, values, motivations, identity. Recall is shaped by the agent's current personality context.
• Self-Hosted. One Rust binary. One SQLite database. Local ONNX embeddings. No cloud keys.
• Encryption at Rest. SQLCipher database encryption with keyfile, environment variable, or YubiKey HMAC-SHA1 challenge-response.
• Atomic Fact Decomposition. Long memories split into self-contained facts. Each fact links back to its parent via has_fact.
• Contradiction Detection. When agents learn conflicting information, Engram surfaces the conflict.
• Guardrails. The gate system checks commands before agents act. Stored rules return allow/warn/block on proposed actions, with optional human-in-the-loop approval.
• Episodic Memory. Conversation episodes stored as searchable narratives.
• Bulk Ingestion. 11 parsers: Markdown, PDF, HTML, DOCX, CSV, JSONL, ZIP archives, ChatGPT exports, Claude exports, and raw message formats through the async ingestion pipeline.
• LanceDB Vector Index. Optional ANN backend for large corpora. Small tenants fall back to in-memory scan.
• Claude Code Hooks. Ready-to-use hooks for session memory, context injection, and tool tracking. See hooks/README.md.

1. Neural Associative Recall

Unlike simple vector search, Kleos leverages in-process Hopfield Networks for pattern-based associative recall. The system reconstructs context from partial cues rather than just finding similar text.

2. Biological Memory Lifecycle

• Dual-Strength Model: Tracks storage stability against retrieval accessibility.
• Consolidation: Background workers replay and merge memory traces to optimize the knowledge graph while agents rest.
• Evolution: A self-improving weight system trains node importance based on retrieval feedback.

3. Hardware-is-Law Security

Kleos secures environments where cloud providers are liabilities. All embeddings run locally. You gate sensitive agent actions with physical YubiKey touch to ensure humans remain the ultimate authority.

For full implementation details, algorithm specs, and API docs, see the Project Wiki.

Workspace

Ten Cargo crates:

cargo build --release --workspace   # build everything
cargo test --workspace               # run the test suite
cargo clippy --workspace             # lint