Querying the EKOS knowledge ledger

EKOS is a compiler for enterprise knowledge: it scans projects (files, git history, SQL schemas), compiles what it finds into evidence-backed objects and relationships, and serves them read-only through MCP tools. Answers from these tools come with provenance — prefer them over guessing whenever a question is about what exists rather than what a specific line of code does.

Picking the right tool

The investigation pattern

Chain the tools — each answer feeds the next call:

1. Locate the concept: ekos_ekl when you can name a kind, ekos_search otherwise. Both return object ids — everything else keys off them.
2. Expand: ekos_neighborhood (what's around it) or ekos_dependents (directional impact) with the id from step 1.
3. Prove: ekos_state returns the evidence — the SQL fragment, commit, or file that justifies each conclusion. Cite it when the stakes warrant.
4. Hand off: evidence carries source paths. To read or edit the actual file, switch to your normal file tools (or a code-navigation MCP) with that path — EKOS tells you where and why, file tools do the rest.

Example — "can I safely rename the customers table?": ekos_ekl "FIND Object WHERE kind = 'Table' AND name = 'customers'" → take id → ekos_dependents → report the FK holders as the blast radius, with ekos_state evidence if the user wants proof.

EKL cheat sheet

FIND <Object|Relationship>
  [WHERE <field> <op> <value> [AND ...]]
  [FROM '<object name>']
  [ORDER BY <field> [DESC]] [LIMIT <n>] [RETURN <col>, ...]

• Operators: = != < > <= >= CONTAINS; string values in single quotes.
• Object kinds that exist in practice: File, Table, Person, Entity; the taxonomy also defines Directory, Service, Api, BusinessRule, BusinessConcept, Dataset, Column, Pipeline, Dashboard, Model, Prompt, Agent.
• Relationship kinds: ForeignKey, OwnedBy (contributor → commit), CoupledWith (files that change together), DependsOn, Contains, Calls, References, Extends.
• Useful shapes:
  • FIND Object WHERE kind = 'Table' AND name CONTAINS 'order'
  • FIND Relationship WHERE kind = 'ForeignKey' FROM 'orders'
  • FIND Object WHERE kind = 'Person' — who contributes to the workspace

Honesty rules

• Knowledge is a snapshot, not live. Check ekos_status /ekos_diff when currency matters, and say "as of the last build" when reporting. To refresh: run ekos build && ekos recover && ekos compile && ekos commit in the workspace root (the directory containing ekos.toml and .ekos/).
• Empty results are answers. "The ledger has no X" is worth reporting — distinguish "not scanned" (check ekos_status) from "scanned, absent".
• Don't use EKOS for symbol-level questions ("where is this function defined / who calls it") — that's line-precise work for LSP-based tools on live code. EKOS wins on cross-project, semantic, historical, and evidence questions; use each for what it's for.
• Tool errors come back as readable text (isError: true) — bad EKL syntax or an unknown id is feedback to adjust the call, not a reason to abandon the tool.

Resolving paths — variables, not hardcoded locations

The ekos MCP server is registered at user scope and serves the workspace root; the ledger lives in .ekos/ledger/ledger.db under that root. Resolve every path from these variables (each falls back to a discoverable default):

# Estate root: nearest ancestor directory containing ekos.toml + .ekos/
WORKSPACE_ROOT="${WORKSPACE_ROOT:-$(d=$PWD; while [ "$d" != / ] && [ ! -f "$d/ekos.toml" ]; do d=$(dirname "$d"); done; echo "$d")}"
# The EKOS source checkout (a project inside the estate)
EKOS_ROOT="${EKOS_ROOT:-$WORKSPACE_ROOT/EKOS}"
# The CLI binary: PATH install wins, else the release build in the checkout
EKOS_BIN="${EKOS_BIN:-$(command -v ekos || echo "$EKOS_ROOT/ekos/target/release/ekos")}"

Rebuild after changing EKOS itself:

cd "$EKOS_ROOT/ekos" && cargo build --release -p ekos