Brain Ingest

Brains are taking over from content reservoirs. There is now one way to put outside material into a brain: post_brain_ingest. A URL, an article, a transcript or a quote becomes a note in the brain, and by default it waits in the brain's Triage lane until you promote or dismiss it.

Ingesting into a brain

post_brain_ingest({
  brain_id: "<uuid or exact name>",
  url: "https://example.com/article",
  content: "The part worth keeping.",
  source: "article"
})

• brain_id (required): the brain's UUID or exact name, from list_brains. If two of your brains share a name, pass the UUID.
• url or content: at least one is required. title is optional and falls back to the URL or the start of the content.
• source: where it came from. The vocabulary is the same one reservoirs used: manual, discovery, rss_feed, content_library, tweet, article, email, youtube, upload, v2_api. Common words are mapped (media and file become upload, x becomes tweet), so a transcript from transcribe_video can be forwarded with its own source value. An unknown value is rejected. Omit it and the note records v2_api.
• promote: true skips review and writes an ordinary brain note, included in the next compile.
• tags: optional.

The response says where the note landed: note_id, brain_id, triage_state (pending or promoted) and the normalized source.

An identical repeat is safe. Sending the same URL and content a brain already holds (pending or promoted) returns that note with duplicate: true and HTTP 200 instead of 201, and writes nothing, and a repeat with promote: true promotes the waiting note. New content for a URL already ingested, such as a full transcript after a bare link, is a new note. A dismissed or expired note does not count, so re-ingesting after a dismissal is a fresh look.

Promoting an ingested note into a vault-backed brain syncs it into the brain's folder, the same as any other brain note. While it waits in Triage it stays out of the vault.

Source lineage

The source survives on the note in three places: the note's source_type, its triage_source block (with the URL and which tool ingested it), and an ingest_source frontmatter key. A note can always say where it came from, before and after it is promoted.

Reference counts on notes

Reservoir items used to count how often they fed generated content. Notes do that now. Every note carries times_referenced and last_referenced_at, and record_note_references bumps both:

record_note_references({ note_ids: ["<uuid>", "<uuid>"] })

The seed builder calls it for the seed note and every note it drew on once a draft exists. list_notes can sort by times_referenced or last_referenced_at to find the notes you lean on most, or the ones you never use.

Reservoir tools are deprecated

Every reservoir tool still works for one more release, but each one now leads its description with DEPRECATED and returns a deprecation block naming its replacement:

Reservoir tool	Use instead
post_reservoir_ingest	post_brain_ingest
list_reservoirs	list_brains
get_reservoir	get_brain
list_reservoir_items	list_notes with brain_id (or list_triage for unreviewed items)
get_reservoir_item	get_note
patch_reservoir_item	patch_notes
delete_reservoir_item	delete_notes (or dismiss_triage_item)

post_reservoir_ingest is now a shim over brain ingest. With a brain_id it writes to that brain. Without one, it follows the target reservoir's brain mapping. A reservoir with no mapping yet still gets the old reservoir write, and the deprecation message says so. Reservoir-to-brain mappings arrive with the next migration step; until then, pass brain_id to move a caller onto brains today.

Related

• Brain Triage Lane: where ingested items wait for review.
• Brain Watches: monitoring that writes into the same lane on a schedule.
• Content Reservoirs: the system this replaces.