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. Time values state how replies write dates and instants.

With several selected brains:

• List entries also name their brain and portable uri.
• newer, also, sections, an outline's refs and a claim's target_ref 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.

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

• Only projects, and notes that set stale_after, get reminders; index.md, log.md and action attachments never do.
• A future event counts once it happens.
• 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.
• As in backlinks, a link through a name several items claim counts for none in new_links, unless it is a record's own ref.
• 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.

How periods place records:

• Period pages, their source counts, home activity and period search scopes use a record's time. They fall back to attributes.observed only when time is absent.
• Period items sort 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.

Time values¶

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

• Titles are previews of at most 200 characters ending in …; exact reads keep the whole title.
• A section's title reads Note — Parent — Child.
• An excerpt shows the query's words in context. Otherwise, like listings and relation pages, it shows up to 320 characters of the note's summary or opening text or of the record's text. … marks a cut.

Scopes¶

A search takes one scope:

A combined scope narrows a folder, note, source, identity or tag to a period, such as the records naming a repository this week. Items fall in the period by the same times as on period pages; see time meanings.

These scopes are invalid (exit 2):

• A period combined with another period, such as 7d memories/brief/7d, or with memories/SOURCE/undated.

• Other segments below memories/SOURCE.

• A fragment on a source, such as memories/brief#x.
• A section, whether its path, such as projects/new-website.md#decision, or its bf:// address: scope the whole note, then read the section.
• A page's address, such as bf://brain/projects or bf://brain/7d: use its brain-relative form, projects or 7d.

A source that no selected brain configures or indexes fails like its page, naming close sources such as did you mean memories/brief?. 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, are overdue or never collected, or fell silent. 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 and tag scopes, and tag searches without a memories scope, search notes alone and 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 ?. Percent-encode those as %23 and %3F only inside a bf:// address.
• A ref ending in a bare #, such as projects/new-website.md# or bf://brain/projects/new-website.md#, names no section and is invalid input (exit 2): read the whole note or name a section.

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. A ref they do not hold fails as incomplete instead of not found, since it could exist there.
• To recover, 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.

Cache freshness¶

Each search and read lists the authored folders and memories/ itself. It lists a source folder only when its fingerprint changed, it changed in the last 5 seconds or it holds a subfolder. Collection renames records into place, which always changes their folder. This assumes a POSIX file system that updates a folder's modification time when an entry is added, renamed or removed.

These changes go unseen until bf build:

• A record file edited in place, or made unreadable.
• A change on a filesystem with coarse timestamps whose clock runs more than 5 seconds behind this machine's, such as a lagging network share.
• A note saved in place twice at the same size within one file system timestamp tick, with a search or read indexing it in between. It also shows once it changes again. A coarse clock, such as FAT's 2 seconds, widens that window.

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, rel or offset, 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. It shows a path that starts with a selected brain root, the registry file or the home directory as <brain>, <registry> or ~.