Knowledge Index
The compiled, queryable result — everything in a workspace's .ekos directory or a home project's state directory.
A knowledge index is what ekos commit leaves behind. It contains:
The state directory is .ekos/ inside a workspace, or <home>/data/<tenant>/<project>/state/ for a project kept in the EKOS home (ekos project add), where the source tree is never written to. Paths below are relative to it.
| Part | Location | Contents |
|---|---|---|
| Artifacts | artifacts/ |
Observation and recovery artifacts (content-addressed) |
| CKM | ckm/model.json.zst |
The compiled model before commit |
| Ledger | ledger/ |
The append-only store of objects, relationships, evidence, events |
| Search indexes | inside the ledger | BM25 (and optional vector) indexes |
| Current sets | identity/, semantics/, conflicts/ (current.json) |
Which ids the latest run proposed — the ledger keeps everything ever written, so reads filter by these |
| Integrity index | integrity/current.json |
The cross-reference findings of the last commit; derived, so kept out of the ledger |
| Review cache | review/state.json |
Every review subject's items and statuses, keyed by ledger counts |
| Committed manifest | committed-manifest.json |
Path, size and modification time of every source file at the last commit, for ekos freshness |
| Run logs | runs/ |
One JSON-lines file per pipeline (or changing) command, ending with its model-call count |
| Diagnostics | diagnostics/ |
Logs from each stage |
| Caches | llm-cache/, fingerprints.json |
LLM response cache; build fingerprints |
An index is self-describing: ekos status reports its size, ekos ledger audit shows the write history of any object, ekos ledger timeline shows growth over time, and ekos freshness lists the source files that changed since the last commit.
An index is local by default and portable — copy the workspace and the .ekos/ directory travels with it; ekos home backup packs every project of a home into one file (or, with --to, into S3, Azure Blob or Google Cloud Storage) and ekos home restore brings it back. See Storage for the fact-engine, SQLite and partitioned layouts.