Skip to main content

​
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).
  6. Never try to authorize. duckbrain connect <app> mints a Pipedream link the user opens once; surface it, then duckbrain sync <app>. You cannot complete consent.

​
Machine output (--json)

The wire contract every host plugin shells. One line of JSON on stdout:
--json is valueless — put it after the query, since a positional is any token not preceded by a flag.

​
Getting duckbrain into your host

Recall is always keyed to the incoming message — there is no query-less session-start dump. Hooks fail open: a missing dep, empty recall, or any error injects nothing and never blocks a turn.

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