Retrieval reference¶

Exact reply fields and rules for CLI and MCP clients. For everyday use, start with Search and read. Examples use the brain from Getting started.

Replies state a note's updated day as date (2026-09-27) and other instants with your local offset, to the second (2026-09-29T09:00:00+02:00). Values under attributes and fields are returned as stored. Collection stores timestamp fields in UTC (2026-10-05T07:00:00.000000Z), and listings show a note's timestamp fields the same way; its exact read keeps the note as written. With several selected brains, list entries also name their brain and portable uri, and newer, also and sections name items by bf:// address.

Pages¶

Pages are computed views, not files. They combine the selected brains; bf read bf://brain/projects selects one brain's page.

Listed items show declared single-value fields, such as a status, when the note or record sets them. A folder ref may end with /, as shell completion adds: tags/website/ reads like tags/website.

Ordering and review signals¶

Records of a priority: low source leave period items, changed and home upcoming; period sources and home activity keep their counts with "priority":"low". Only deprecated closes a note: it ranks last and leaves every home section, reminders and the task list.

Folder listings, home projects, actions and upcoming, and the whole read of a note that gets reminders carry review signals; home changed keeps only modified and review: true:

A future event counts once it happens, and editing the note clears newer_evidence until newer evidence arrives. observed never counts: an upstream change made before the edit but collected after it raises no signal. Only projects, and notes that set stale_after, get reminders; index.md, log.md and action attachments never do. Reads never change files.

Time meanings¶

A message sent last week and edited today keeps last week's event time and appears in today's changed list.

Period pages, their source counts, home activity and period search scopes use a record's time, falling back to attributes.observed only when time is absent. They sort period items by that placement time, newest first. Replies keep observed separate and never invent an event time. Records with neither timestamp stay out of periods; memories/SOURCE/undated still lists every record without event time, even one placed by observation. Observation alone never creates an upcoming event or a newer-evidence review signal. Try the fictional feed example.

Tasks¶

Tasks can share a section ref; their line tells them apart within one snapshot.

Search¶

Queries hold up to 4,096 characters. --limit is 1–50 (default 10).

Items carry ref, kind, title, excerpt, a note's date, type and status, and a record's time, source, url, provider updated time, BF's observed time and "partial":true when the sensor kept only part of the text. Titles are previews of at most 200 characters ending in …; exact reads keep the whole title. A section's title reads Note — Parent — Child.

Scopes¶

A search takes one scope:

Other segments below memories/SOURCE are invalid (exit 2), and so is a section, such as projects/new-website.md#decision, or a page's #fragment: scope the whole note, then read the section. A page's address, such as bf://brain/projects or bf://brain/7d, is invalid too: use its brain-relative form, projects or 7d. A source that no selected brain configures or indexes fails like its page; a folder or identity that names nothing returns no items.

Identity matching¶

Identities are case-sensitive and resolve only through explicit aliases, entities and resource URIs.

Source coverage¶

Search lists in sources the sources of returned records and those needing attention because they failed or are overdue or never collected. sources_omitted counts the others. A reply without items, or a search scoped to memories or memories/SOURCE, lists every searched source: coverage is then the answer. Authored-folder scopes omit both fields.

Notes, records and identities¶

sha256 covers the file's bytes, also on a section read: compare it before replacing a file you read. A record's text is record.text, never a top-level text. Record refs are SOURCE:ID: read a returned ref exactly as written, even when its id holds # or ?, and percent-encode those as %23 and %3F only inside a bf:// address. A ref ending in a bare #, such as projects/new-website.md#, names no section and is invalid input (exit 2): read the whole note or name a section. A bf:// address with an empty fragment reads the whole note.

Read a preview's ref for the evidence, or list the whole group with a relation page.

Relation pages¶

A relation page lists every item linking to a note, record or identity through one relation, newest first:

bf read projects/new-website.md --rel cites
bf read repo:github.com/example/new-website --rel depends-on --offset 50

After Connect two notes, the first returns "page":"relation", "relation":"cites" and the concept as an item with its excerpt.

Continuations¶

The last page still needs the completeness checks.

Large exact reads¶

An exact read whose reply would exceed 32 KiB returns its text in pages. A note's first page carries an outline when headings inside the read divide it and, for a whole note, its backlinks and claims. The outline lists the headings inside the read: never the H1 title spanning the whole note, nor the section being read. When such headings divide the text, the first page holds only its first 4 KiB; otherwise, as for a note with only a title or a section without subsections, it holds as much as fits. A record's first page carries every other field. Later pages carry brain, ref, any uri, their slice, the paging fields, sha256, modified, notice and any problems or stale of the read itself; problems with backlinks and claims stay on the first page.

1. Read a section from the outline when it answers the question.
2. Otherwise repeat the read with each next_offset and concatenate the slices in order.
3. Check that every page names the same sha256; restart at offset 0 if it changes.

A reply that fits returns whole and rejects a non-zero offset.

Incomplete answers and freshness¶

Malformed files, links and special files are skipped and reported while healthy brains still answer. While a selected brain is unavailable, an exact read returns what the others hold with a problems entry naming it, and a ref they do not hold fails as incomplete instead of not found, since it could exist there. Read a brain-qualified address, such as a search result's uri (bf://NAME/...), or repair that brain, for example with bf build. What BF does not do states what an incomplete reply cannot prove.

Reply schemas¶

bf search and bf read replies follow published JSON Schemas (draft 2020-12), shared by the CLI and MCP: search and read. Validate a saved reply against the installed version's schema:

bf schema --kind search-reply > search-reply.schema.json
bf search "visitors clear explanation" > reply.json
uvx check-jsonschema --schemafile search-reply.schema.json reply.json

The validator prints ok -- validation done. The schemas describe every reply shape and accept added fields: a minor release may add optional fields, and only a major release changes or removes one. Clients should ignore fields they do not know.

MCP tool contract¶

Transport: stdio. Set up your host.

Each tool publishes its reply schema as outputSchema. Text and structured results carry the same JSON value as the CLI. Integral numbers such as 5.0 count as integers. Arguments outside the tool's input schema, such as limit: 0, return an error result with the MCP SDK's message. Values the tool rejects after that return invalid input: ARGUMENT: reason, naming query, scope, ref or rel, such as invalid input: ref: invalid period: 2026-13; an unknown scope or relation names the valid choices. Other errors carry the CLI's message, naming the search and read tools where the CLI names commands. Error text escapes control and format characters like CLI diagnostics, and shows a path that starts with a selected brain root, the registry file or the home directory as <brain>, <registry> or ~.