<div align="center">

<img src="docs/assets/banner.svg" width="800" alt="Kleos Banner" />

# Kleos

**Cognitive infrastructure for AI agents. Not a memory engine -- a full operating system for how agents think, learn, coordinate, and stay safe.**

[![License](https://img.shields.io/badge/License-Elastic--2.0-blue.svg)](LICENSE) [![Rust](https://img.shields.io/badge/rust-1.94%2B-orange.svg)](https://www.rust-lang.org) [![Native](https://img.shields.io/badge/Native-No%20Python-blueviolet.svg)](#)

[Quickstart](https://github.com/Ghost-Frame/Kleos/wiki/Getting-Started) · [Why Kleos](https://github.com/Ghost-Frame/Kleos/wiki/Why-Kleos) · [Wiki](https://github.com/Ghost-Frame/Kleos/wiki)

</div>

---

Kleos is not a memory engine. Calling it one is like calling a brain a hard drive.

Yes, Kleos stores and retrieves memories. But it also consolidates them overnight through a six-stage dream cycle. It builds a knowledge graph with causal reasoning and community detection. It assembles context for LLMs through eight parallel retrieval layers with token budget management. It enforces structured reasoning protocols so agents spec before they code and hypothesize before they debug. It runs seven neuroscience-named coordination services for multi-agent orchestration. It gates every shell command and filesystem operation through a security policy engine. It watches agent sessions in real time and injects corrections when they drift.

The difference between Kleos and a memory tool is the difference between a notebook and a nervous system.

One Rust binary. Self-hosted. Your data never leaves your hardware.

![Kleos CLI demo](tools/cli-demo.gif)

![Kleos memory graph visualization](tools/gui-demo-v3.gif)

---

## What Kleos does

### Biological memory lifecycle

Memory in Kleos follows the same arc as biological memory -- acquisition, consolidation, decay:

- **FSRS-6 spaced repetition** with all 21 trained weights (the algorithm behind Anki). Memories strengthen with use and fade when ignored via power-law forgetting.
- **Six-stage dream cycle** runs during idle: replay, merge, prune, discover, decorrelate, resolve. Consolidates knowledge autonomously.
- **Modern Hopfield network** (feature-gated) with softmax attention and capacity exponential in dimension. Backs an associative instinct system with causal edge scoring.
- **Personality-shaped recall** -- six signal types (preference, value, motivation, decision, emotion, identity) extracted from stored text. Two agents querying the same memories get different results.
- **On-store processing** -- SimHash deduplication, SVO contradiction detection, atomic fact decomposition, entity extraction, and auto-linking all happen before the store call returns.

### Context assembly

The 8-layer system that builds what the agent actually sees:

| Layer | What it retrieves |
|-------|-------------------|
| Permanent facts | Memories marked as static/always-include |
| Semantic matches | 4-channel hybrid search (vector + FTS5 + graph + personality) |
| Evolution hints | Version history and lineage of retrieved memories |
| Graph neighbors | Memories connected via typed edges or cosine similarity |
| User preferences | Scoped personality and preference signals |
| Current state | Key-value pairs representing the active environment |
| Structured facts | Subject-verb-object triples extracted from text |
| Episode summaries | High-level summaries of past interaction sessions |

All eight layers run in parallel. Results are packed into a token budget with priority-based truncation and prompt-injection sandboxing.

### Knowledge graph

- Auto-linking via cosine similarity with typed, weighted edges: `similarity`, `updates`, `extends`, `contradicts`, `caused_by`, `prerequisite_for`, `generalizes`, `resolves`, and more
- Causal edge scoring with NLP markers (strong/context/weak weighting)
- Louvain community detection capped at 10K nodes per pass
- Weighted PageRank with temporal decay (180-day half-life) and deduplicated multi-edges
- 2-hop graph-augmented search -- initial hits expand into their neighborhood for hidden context
- Structural analysis: centrality hubs, bridge nodes between isolated communities

### Coordination

Seven neuroscience-named services sharing a single auth, audit, and rate-limit layer:

- **Axon** -- pub/sub event bus with channels, retention windows, cursor-based consumption, and webhook delivery
- **Broca** -- structured action log with causal tracing back to Axon events
- **Chiasm** -- task tracker with state machine lifecycle, history reconstruction, and multi-agent project scoping
- **Soma** -- agent registry with heartbeats, capability declarations, quality scores, and drift flags
- **Loom** -- DAG workflow engine with state persistence across server restarts
- **Thymus** -- quality evaluation with feedback signals and reinforcement learning integration
- **Brain** -- cognitive orchestrator that abstracts over Hopfield network and external backends

One `POST /activity` call fans out to all of them.

### Structured reasoning (Agent Forge)

A protocol that controls how agents think, not just what they remember:

- **Spec before code** -- `spec-task` requires acceptance criteria and edge cases before implementation begins
- **Hypothesis before fix** -- `log-hypothesis` with confidence scoring, `recall-errors` to prevent repeating mistakes
- **Verification before done** -- `verify` runs commands against spec criteria, `challenge-code` generates adversarial review
- **AST-aware code analysis** -- Tree-sitter parsing across Rust, TypeScript, Python, Go, C, C++, JS. `repo-map` builds ranked symbol lists within token budgets.
- **Session resilience** -- git checkpoints and rollback for recovery from destructive edits

### Skills, growth, and metacognition

- Skills with version history, execution tracking, trust scores, and lineage graphs
- LLM-backed skill evolution: analyze failure history, propose fixes, derive new skills, capture from natural language
- Cloud library for sharing skills across agents
- Growth system: agents reflect on their own patterns and materialize insights into structured memories
- Insights feed back into the spaced-repetition loop so useful self-knowledge stays accessible

### Security and policy enforcement

- **Encryption** -- SQLCipher at rest, key from file, env var, or YubiKey HMAC-SHA1 challenge-response
- **Credential vault** -- separate daemon (`kleos-credd`) with AES-256-GCM, master/agent two-tier key model, zero-knowledge agent bootstrapping via ECDH + PIV
- **Request signing** -- ECDSA-P256 or Ed25519 with replay-resistant nonces
- **Pre-action gate** -- every agent command checked against allow/warn/block policy before execution, with a human approval queue for risky operations
- **Shell command gating** (`kleos-sh`) -- static validation, SSRF guard, metacharacter blocking, Claude Code hook integration
- **Filesystem sandboxing** (`kleos-fs`) -- AST-aware read/write/edit with configurable allowed roots and path traversal prevention
- **Agent-marked shells** -- `cred get` blocked in agent contexts to prevent secret exfiltration; agents must use `cred exec` for subprocess injection
- **Audit log on every mutation**

### Real-time supervision

- **Eidolon supervisor** watches agent session transcripts as they're written, using async file-system monitoring with LRU-cached file positions
- **Rule-based detection** -- regex pattern matching on assistant text, tool commands, and commit messages
- **Retry loop detection** -- catches agents stuck repeating the same failing command (3+ consecutive repeats)
- **Scope enforcement** -- validates file modifications stay within allowed directory prefixes
- **Three-destination alerting** -- Kleos inbox (human review), Axon event bus (automation), supervisor inject (direct agent intervention)
- **Cooldown management** -- per-rule throttling prevents alert fatigue from runaway processes
- **Server can inject corrections or block the agent's next action**

---

<details>
<summary><strong>Quick start</strong></summary>

<br>

**Build and run:**

```bash
git clone https://github.com/Ghost-Frame/Kleos.git && cd Kleos
cargo build --release -p kleos-server -p kleos-cli
KLEOS_BOOTSTRAP_SECRET=pick-a-secret ./target/release/kleos-server
```

Server starts on `127.0.0.1:4200`. In another terminal:

**Bootstrap your admin key (one-time):**

```bash
curl -X POST http://localhost:4200/bootstrap \
  -H "Content-Type: application/json" \
  -d '{"secret": "pick-a-secret"}'
```

**Store a memory:**

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

**Search by meaning:**

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

For Claude Code hooks, encryption setup, the session sidecar, and client SDKs, see the [Getting Started](https://github.com/Ghost-Frame/Kleos/wiki/Getting-Started) guide.

</details>

<details>
<summary><strong>For developers: integration and architecture</strong></summary>

<br>

### Connecting your agent

Kleos speaks three protocols:

| Protocol | Details |
|----------|---------|
| **HTTP API** | 56 route modules -- memory, search, graph, coordination, skills, growth, ingestion, approvals, admin. Bearer token or signed-request auth. |
| **MCP** | 59 tools over stdio. Drop into Claude Code, Cursor, or any MCP-compatible client. |
| **Client SDKs** | TypeScript, Python (Pydantic v2 + httpx), Go (stdlib only). First-party, typed, tested. |

### Claude Code integration

Kleos ships ready-to-use hooks in `hooks/`:

- **Simple** -- session start/end, per-turn memory recall, tool observation. Bash + curl.
- **Full** -- adds Eidolon brain-aware context, automatic sidecar startup, Chiasm task tracking, growth materialization, Agent-Forge protocol enforcement, and session quality scoring.

Copy the hooks, configure `settings.json`, and your agent has persistent memory, coordination, structured reasoning, and real-time supervision across sessions.

### What runs inside

16-crate Rust workspace. The server handles:

- **Multi-tenancy** -- each tenant gets its own encrypted SQLite database, connection pools, and quota limits
- **8 middleware layers** -- auth, per-tenant rate limiting, audit log, IP extraction, JSON depth limits, Prometheus metrics, safe-mode, compression/timeouts
- **7 coordination services** -- Axon, Broca, Chiasm, Soma, Loom, Thymus, Brain
- **Skills platform** -- CRUD, versioned evolution, execution tracking, trust scoring, judgments, cloud library, LLM-backed fix/derive/capture
- **Growth engine** -- self-reflection, pattern observation, insight materialization
- **Ingestion pipeline** -- Markdown, JSON/JSONL, CSV, PDF, ZIP. Semantic chunking, format-aware parsing, Mem0/SuperMemory import
- **Resilience** -- circuit breakers, exponential backoff with jitter, dead-letter queue for failed operations

### Session sidecar

`kleos-sidecar` sits between your agent and the server:

- Buffers observations in memory instead of blocking on every write
- Optional compression via local Ollama
- Batched flushing to the server
- File-watching and persistent session support

### Security model

- SQLCipher encryption at rest -- key from file, env var, or YubiKey HMAC-SHA1
- Bearer tokens hashed with SHA-256 and peppered
- Request signing via ECDSA-P256 or Ed25519 with replay-resistant nonces
- Credential daemon (`kleos-credd`) -- AES-256-GCM vault, master/agent two-tier key model
- Zero-knowledge agent bootstrapping via ECDH + PIV
- Pre-action gate: allow/warn/block with human approval queue
- Shell command gating with static validation and SSRF guard
- Session grants with configurable TTL
- Audit log on every mutation

### Building from source

```bash
# Server-only (recommended for self-hosting)
cargo build --release -p kleos-server -p kleos-cli -p kleos-mcp

# Agent-host (CLI tools, credential daemon, supervisor)
cargo build --release -p kleos-cli -p kleos-sh -p kleos-cred -p kleos-credd \
  -p agent-forge -p eidolon-supervisor

# Full workspace (all 17 crates -- needs ~8 GiB RAM)
cargo build --release --workspace
```

The server-only build skips heavy workspace crates (approval TUI, tree-sitter
parsers, supervisor) and finishes significantly faster.

```bash
cargo test --workspace --exclude kleos-migrate                                # test suite
cargo clippy --workspace --exclude kleos-migrate --all-targets -- -D warnings # lint gate
```

Requires Rust 1.94+, `protoc`, and `libpcsclite-dev` (Linux) for smartcard support.

</details>

<details>
<summary><strong>For researchers: the cognitive science</strong></summary>

<br>

### Spaced repetition (FSRS-6)

- All 21 trained weights from the Free Spaced Repetition Scheduler (same algorithm behind Anki)
- Dual-strength model: storage strength accumulates with use, retrieval strength decays via power-law forgetting
- Live retrievability modulates search scores in real time
- Memories the agent uses stay sharp; ignored ones drift out of the way without deletion

### Hybrid retrieval

Four channels run per query:

| Channel | Implementation |
|---------|---------------|
| **Vector similarity** | BAAI/bge-m3 ONNX embeddings (1024-dim), LanceDB ANN index |
| **Full-text** | FTS5 BM25 scoring |
| **Graph traversal** | 2-hop expansion weighted by typed edges and PageRank |
| **Personality signals** | Preference, value, motivation, decision, emotion, identity |

- Results merge through Reciprocal Rank Fusion
- Question-type detection classifies the query (fact recall, preference, reasoning, generalization, timeline) and reweights channels
- IBM Granite cross-encoder reranks the top-K
- Contradiction damping suppresses stale markers ("no longer," "switched from," etc.)

### Knowledge graph

- Auto-linking by cosine similarity with six typed edges: `similarity`, `updates`, `extends`, `contradicts`, `caused_by`, `prerequisite_for`
- Link-type weights so a "causes" edge outranks an "extends" edge
- Louvain community detection capped at 10K nodes per pass
- Weighted PageRank with deduplicated multi-edges
- Sliding-window entity cooccurrence
- Structural and impact analysis

### Hopfield network (feature-gated)

- Continuous Hopfield network (Ramsauer et al. 2020) with softmax attention and capacity exponential in dimension
- Embedding compression via PCA using power iteration and deflation -- no LAPACK dependency
- Six-stage dream cycle during idle: replay, merge, prune, discover, decorrelate, resolve

### Personality engine

- Six signal types extracted from stored text: preference, value, motivation, decision, emotion, identity
- Each signal carries a subject, valence (positive/negative/neutral/mixed), intensity in [0,1], and the reasoning that produced it
- Recall is shaped by personality context -- two agents querying the same memories get different results

### Growth and self-reflection

- Agents reflect on recent activity to generate pattern observations
- Materialization converts raw observations into structured insight memories
- Deduplication against existing observations
- Integration with the spaced-repetition loop so useful insights stay accessible

### On-store processing

- SimHash near-duplicate suppression
- SVO contradiction detection against a structured-fact triple store
- Atomic fact decomposition (LLM-first with rule-based fallbacks) -- splits long memories into self-contained facts linked via `has_fact` edges

### Skill evolution

- Skills are versioned, tracked, and judged
- LLM analyzes execution history and proposes fixes for failed skills
- New skills can be derived from existing ones or captured from natural language
- Trust scores aggregate execution success rates and human/agent judgments
- Lineage graph tracks which skills evolved from which

</details>

<details>
<summary><strong>For those evaluating the engineering</strong></summary>

<br>

### Scope

- 16 Rust crates, ~204K lines of code
- ~6,000 test declarations across 113 test files
- Single statically linked binary with the mimalloc allocator
- No Python runtime. No external service dependencies at rest.

### Workspace

| Crate | What it does |
| --- | --- |
| `kleos-lib` | Core library: memory, search, embeddings, graph, intelligence, services, skills, growth, auth, gate, jobs. Feature-gated `brain` backend. |
| `kleos-server` | Axum HTTP server. 56 route modules, 8 middleware layers, embedded web GUI. |
| `kleos-cli` | Command-line client. Memory ops, skill management, handoffs, credential management. |
| `kleos-mcp` | MCP server. 59 tools across 8 domains. Stdio transport, HTTP behind a feature flag. |
| `kleos-sidecar` | Session-scoped memory proxy. File watcher, batched flushing, Ollama compression, persistent sessions. |
| `kleos-cred` | Credential library. YubiKey challenge-response, Argon2id KDF, ECDH agreement, CRED:v3 vault resolution. |
| `kleos-credd` | Credential daemon. Two-tier auth (master + agent keys), AES-256-GCM encryption, zero-knowledge agent bootstrap. |
| `kleos-ingest` | Transcript ingest daemon. PIV/software-key request signing, file watching, LLM summarization, real-time observation streaming. |
| `agent-forge` | Structured reasoning CLI. 20+ subcommands. Tree-sitter AST parsing for 7 languages. |
| `eidolon-supervisor` | Session drift detection daemon. Real-time transcript watching, rule-based alerts. |
| `kleos-sh` | Shell command gate. Static validation, SSRF guard, human approval queue. |
| `kleos-fs` | AST-aware filesystem operations. Guarded read/write with agent-forge integration. |
| `kleos-migrate` | One-shot ETL from encrypted monolith to per-tenant shards. |
| `kleos-cleanup` | Deduplication and log demotion utility. |
| `kleos-approval-tui` | Ratatui terminal UI for human-in-the-loop approval workflows. |
| `sdk` | Client SDKs: TypeScript, Python, Go. |

### Design decisions

- **No external services** -- embeddings run locally via ONNX, vector storage is embedded LanceDB, coordination is in-process. No message broker. No Python runtime.
- **Database-per-tenant isolation** -- not schema-per-tenant, not row-level. Each tenant gets its own SQLite file with its own encryption key and connection pool.
- **ServiceGuard on all external calls** -- three-state circuit breaker + exponential backoff + dead-letter queue. Failed work is inspectable and replayable.
- **Hardware-anchored trust** -- YubiKey-derived keys for both credential daemon and server. PIV request signing. ECDH agent bootstrapping so API keys never hit disk in plaintext.
- **Skills as a first-class system** -- versioned, trust-scored, LLM-evolvable, with execution analytics, judgment history, and lineage tracking.
- **Built-in supervision** -- Eidolon watches agent sessions in real time and can intervene before damage is done.

### Install profiles

The `dist/install.sh` script supports three profiles:

| Profile | Includes |
|---------|----------|
| `server` | kleos-server, kleos-cli, kleos-mcp |
| `agent-host` | kleos-cli, kleos-sh, kr, kw, ke, agent-forge, eidolon-supervisor, kleos-cred/credd |
| `full` | Every binary |

</details>

---

<div align="center">

[Wiki](https://github.com/Ghost-Frame/Kleos/wiki) · [Issues](https://github.com/Ghost-Frame/Kleos/issues)

Elastic License 2.0

</div>
