EKOSdocs
Docs / Getting Started Build

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
Real output of ekos doctor
Real output of ekos doctor
Real output of ekos status
Real output of ekos status

The two captures above are real output from EKOS indexing its own repository. Non-fatal problems appear as diagnostics with codes — see Error Codes.