Create Your First Knowledge Index
Run the compiler pipeline over a project and inspect the result.
An index is the .ekos/ directory next to your ekos.toml — or, for a project in the EKOS
home, ~/.ekos/data/<tenant>/<project>/state/, with its ekos.toml beside it and nothing
written into the sources.
1. Initialize
cd /path/to/my-project
ekos init
This creates .ekos/ and, if absent, a starter ekos.toml:
[workspace]
root = "."
log-level = "info"
log-format = "pretty"
[observe]
paths = ["."]
ignore-patterns = [".ekos", ".git", "target", "node_modules"]
ekos init --detect writes a fuller file instead: the SQL dialect your schema is written in and
exclusions for third-party and generated directories. A build from main also writes one
[[recover.sql.dialect-rules]] per engine-named directory (oracle/, postgresql/, …) and
proposes [tickets] keys it finds in file names. --dry-run prints the file without writing it.
Add every dependency, virtualenv and generated directory you do not want observed to
ignore-patterns. Entries are names, matched against any path component — a directory or a
file name, not a path or a glob. Preview the effect first:
ekos config validate # syntax, plus [observe] mistakes such as a path or glob in ignore-patterns
ekos config preview-scan # what ekos build would observe, without reading anything
A project of several repositories names each one as a source ([[sources]], or
ekos source add <name> --path <dir>), and a live database is added with ekos database add; see Configuration File.
2. Compile
ekos build # observe files, redact secrets, store artifacts
ekos recover # run analyzers: SQL, code ASTs, Git, docs, ...
ekos resolve # merge duplicate identities
ekos compile # KIR -> Canonical Knowledge Model
ekos commit # append to the ledger, build search indexes
Each stage prints a summary. ekos status shows the ledger's entry and object counts. On a
build from main, every stage also writes a JSON-lines run log — one line per step with its
counts, ending with how many model calls the run made — to <state>/runs/<stamp>-<command>.jsonl,
or to the file EKOS_RUN_LOG names.
3. Check health
ekos doctor
ekos status
ekos coverage # which input kinds compiled into objects; --strict exits non-zero on a silent one
ekos freshness # source files changed since the last commit, and the objects that cite them
ekos check refs # references that resolve to nothing or to several objects
The two captures above are real output from EKOS indexing its own repository. Non-fatal problems appear as diagnostics with codes — see Error Codes.