Docs / Guides Build
Updating an Index
Re-run the pipeline after changes; unchanged sources are skipped.
ekos build && ekos recover && ekos resolve && ekos compile && ekos commit
buildfingerprints each observe path (.ekos/fingerprints.json); an unchanged tree reuses cached artifacts. The fingerprint includes the pipeline's logic version, so upgrading EKOS re-processes what its new logic would change — no manual wipe.commitreportsObjects skipped: N (already in ledger)— identical objects are not rewritten.recover --parallelruns independent passes concurrently.- Live databases (
[[databases]]) are read on everybuild, outside the fingerprint, so a dropped table leaves the model on the next run. - Each pipeline command writes a JSON-lines run log, one line per step with its counts, ending with the number of model calls:
.ekos/runs/<timestamp>-<command>.jsonl, or<state>/runs/for a project in the EKOS home.
When do you need to update?
ekos status tells you. Since RFC 0171 the ledger remembers which files it was compiled from, by size and modification time, and compares them with the disk:
ekos status # … Source : source changed — ledger reflects the source as of 2026-10-09 12:35 UTC (git c4f01c7); 1 changed, 1 added, 1 removed since
ekos freshness # the files, and the compiled objects that cite them
Changed (1):
schema.sql
may be stale: File schema.sql, Table customers, Table orders
- Only metadata is read, never file contents, so a file that was only touched also counts as changed. With
[freshness] content-hash = true(off by default),buildalso records a hash per file, and a file whose time moved but whose bytes did not is no longer reported. Files excluded as secrets are never hashed. ekos compileandekos commitwarnFRESH001when the source moved afterekos build, because that commit would record the older source.- Agents see it too: MCP
ekos_statuscarries afreshnessblock. While the ledger is behind, read tools add a one-line note to their answers. [freshness] enabled = falseturns it off.ttl-seconds(default 30) is how long the MCP server reuses one check.
Starting fresh
ekos clean clears the artifact cache (.ekos/artifacts/). Deleting the whole state directory (.ekos/, or <home>/data/<tenant>/<project>/state/ for a project in the EKOS home) is the only way to remove content from the ledger — see Security for why that matters if something sensitive was indexed.
After upgrading EKOS
Read Upgrades. If a read-only client reports a stale search index, run ekos ledger repair.