> ## Documentation Index
> Fetch the complete documentation index at: https://docs.duckbrain.sh/llms.txt
> Use this file to discover all available pages before exploring further.

# For Agents

> How AI agents should use duckbrain: search-first, filter-first, hydrate last

## 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.


## Related topics

- [DuckBrain](/index.md)
- [Instances](/instances.md)
- [Apple Photos](/sources/apple-photos.md)
- [Claude Code Sessions](/sources/claude-sessions.md)
- [context](/commands/context.md)