For Agents

​

The contract

1. Search before you SELECT. Start with duckbrain search "<terms>" [facets] — never guess schemas or scan tables first.
2. Filter first, rank second. Use the four facets (--source, --in, --since/--until, --person) to shrink the pool before relevance does the rest.
3. Budget your context. Use duckbrain context "<query>" --budget <chars> for prompt-ready blocks instead of raw row dumps.
4. Hydrate last. Snippets are ~400 chars; drill into full records only for the hits that matter.
5. Read-only by default. Direct SQL access: duckdb -init ~/.duckbrain/default/state.sql attaches the lake read-only and defines brain_search(query).

​

Anti-patterns

• SELECT * FROM raw_records — floods context; always search first.
• Re-ranking by re-querying with tiny variations — adjust facets instead.
• Parsing user questions into flags with a model — compose flags directly from intent.