EKOSdocs
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
  • build fingerprints 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.
  • commit reports Objects skipped: N (already in ledger) — identical objects are not rewritten.
  • recover --parallel runs independent passes concurrently.
  • Live databases ([[databases]]) are read on every build, 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), build also 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 compile and ekos commit warn FRESH001 when the source moved after ekos build, because that commit would record the older source.
  • Agents see it too: MCP ekos_status carries a freshness block. While the ledger is behind, read tools add a one-line note to their answers.
  • [freshness] enabled = false turns 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.