rekal

Rekal — which substrate answers this?

Most wasted effort is the wrong substrate. Decide before you grep or recall.

Substrate	Holds	Tense	Reach it with	Answers
Tree	current code	now	grep / read	what does X do, where is it
Knowledge	current prose	now	rekal "<q>" → Read HEAD	convention / what we know
Ledger	session intent	past	rekal "<q>", drill rekal query --session	why, tried, rejected
Map	structure	—	map.sh + workflow	how is it built

Boundary

1. Is it true now, or something that was?
   • Was — a reason, a rejected path, a past correction, or a fact whose only record is a past conversation → Ledger. (On a pure-dialogue corpus only the ledger has content — go there.)
2. If now — code or prose?
   • Code (path/symbol, present tense) → Tree. Grep; do not recall.
   • Prose → Knowledge. Never invent an episode when HEAD prose answers.

grep for code that is · knowledge for prose that is · ledger for the why that was.

Commands — text by default, --json for machines

Rekal's read commands print compact agent-readable text; add --json only when a program needs to parse it.

• rekal "<q>" — recall. Prints a seed digest: line 1 is the verdict (INJECT / KNOWLEDGE / SILENCE), then per-seed sid conf=… t<n> "snippet". One call already widens itself — it fuses several deterministic reformulations of your query (keyword-only, clause splits, a temporal variant) so you get the full picture in one go; still reformulate by hand only when the answer needs a genuinely different angle the mechanical variants miss. A seed may carry [reached N× drilled M×· "past query"] before its snippet — a usage hint. reached counts how often the search surfaced it, which is the engine quoting itself: on a small store nearly everything is reached, so a bare high count means little. drilled counts how often an agent opened it — that is the load-bearing signal and a good first drill. The echoed query is the one that most often surfaced this memory, so it shows how the need is usually framed. Neither raises conf= — judge relevance from conf= + content as always. No tag just means newly surfaced, not worse.
• rekal find "<term>" [role] — every ledger mention of a term, complete and in time order (the "all / every / how many" sweep). A partial list is a wrong answer to a set question — this is the set.
• rekal query --session <sid|ulid> [--offset N --limit 5 --role …] — drill a session into readable turns. rekal query --sql "SELECT …" for analytical / complete-set SQL (see references/reference.md for the full schema; ts is a TIMESTAMP — use BETWEEN, not LIKE).