Retrieving
Pull context back out — before acting, not after. The agent consults engrams at three
moments: session start (prime), before editing files (relevant),
and before designing or fixing (query, decision search). All output
is JSON, ranked and token-lean.
Session start — engrams prime
One call replaces half a dozen. prime fans out queries across product context,
active-context tracks, decisions, progress, and patterns, joins PRs and anchors, and returns
a single consolidated briefing. It is the first command of every session.
engrams prime
engrams prime --budget 1000 --paths src/ops,src/db.rs --tags database| Flag | Purpose |
|---|---|
--budget | Approximate token budget; lower-priority sections are shed to fit. |
--paths | Filter the briefing to items anchored to these paths. |
--tags | Filter by tags. |
Token estimation is payload length ÷ 4. When the estimate exceeds the budget, less critical
sections are discarded in a fixed order — but active-context is never shed,
because it carries the session's immediate goals, open questions, and next steps.
Before editing — engrams relevant
The anchor graph in reverse: give it paths, get back every decision and pattern anchored to them. This is how context stays anchored to the files being edited instead of the whole database. Run it before touching any file.
engrams relevant src/db.rs src/ops
engrams relevant --staged| Flag | Purpose |
|---|---|
[PATHS]... | Files or directories to match against stored anchors; directory anchors match recursively. |
--staged | Use git diff --cached --name-only as the path list — context for exactly what you're about to commit. |
--all | Include superseded decisions (default: active only) to see how an area evolved. |
Before designing — engrams query
Cross-type full-text search over decisions, patterns, and custom data, backed by SQLite FTS5
and ranked by BM25. Results come back as highlighted snippets — matching terms wrapped in
>>/<< markers — so the agent scans hits without pulling
full rows.
engrams query "authentication"
engrams query "redis" --types decision,pattern --tags database,cache --limit 5
engrams query "JWT" --since "2026-07-01T00:00:00Z" --all| Flag | Purpose |
|---|---|
--types | Restrict to decision, pattern, custom (comma-separated; default all three). |
--tags | Only items carrying these tags. |
--since | RFC3339 lower bound on timestamp. |
--limit | Max results (default 10). |
--all | Include superseded decisions. |
Decisions only — engrams decision search
FTS over decisions alone, for when the question is specifically "have we already decided this?" Settled choices stay settled instead of being re-litigated every session.
engrams decision search "database" --snippets --limit 10
engrams decision search "sqlite" --all| Flag | Purpose |
|---|---|
--snippets | Return highlighted FTS snippets instead of full rows — the token-lean default for agents. |
--limit | Max results (default 10). |
--all | Include superseded decisions. |