Docs / Architecture Learn
System Overview
The components of EKOS and how knowledge flows from sources to agents.
EKOS is a Rust (2024 edition) Cargo workspace whose root is ekos/. It is a compiler, not a database: it observes, compiles and stores; a separate read-only runtime serves.
Components
| Component | Crate(s) | Role |
|---|---|---|
| Observation | observation-sdk, plugins/* |
The Observer contract and the connectors; produce content-addressable artifacts |
| Artifacts | artifact |
Artifact types and the store (loose JSON or packed segments) |
| Compiler core | compiler-core, scheduler, compiler-sdk |
Compiler, PassManager, scheduling, diagnostics, EkosConfig |
| Recovery | recovery |
One analyzer per source kind plus LLM provider glue |
| IR | kir |
Typed intermediate representation |
| Identity | identity |
Same-source merging and cross-system candidate scoring |
| Semantic compiler | semantic |
KIR → CKM; the shared Transformation IR; concentration risks |
| Ledger | ledger, segment-backend, cluster, distributed |
Append-only store, indexes, partitioning, distribution |
| Runtime | runtime |
Read-only state reconstruction, retrieval, ekos ask grounding |
| Query language | ekl |
Parser and interpreter |
| Output | docs-gen, dbt-gen |
Deterministic docs and dbt export |
| Interface | cli |
Every subcommand and the MCP server; the extension seam |
| Shared | common |
Hashing, compression, redaction |
Invariants
- The ledger is append-only.
- Every conclusion is traceable to evidence.
- The runtime is read-only; agents use it, never the raw systems.
- Compiler passes are deterministic and side-effect-free.
- Artifacts are content-addressable.
- Secrets and PII are never observed or stored.