Agent-readable docs index: /llms.txt. Full docs in one file: /llms-full.txt. Download /docs.zip to grep all markdown files locally.

Getting Things In

A brain is only as useful as what reaches it. Everything a person captures lands in one place — People/<them>/Inbox/ — where their assistant summarizes it, extracts decisions and action items, and files it. This page is about the step before that: how a transcript, an email, or a voice memo actually gets into the Inbox.
The Inbox is an ordinary folder. Anything that writes a markdown file there is a valid intake — a drag-and-drop in Obsidian, an agent, or an automated feed. The brain ingest command is the safe, server-side way to do it.

The primitive: brain ingest

brain ingest writes one provenance-stamped note into a person's Inbox in the master vault and commits it. It is the single code path that lets an outside channel drop a note into someone's private space — so all the safety checks live here, not in any channel:
echo "Client agreed to renew. Follow up Monday." \
  | brain ingest --master /srv/brain/master --person bob --source chat --title "Renewal call"
That writes People/bob/Inbox/2026-07-08-renewal-call.md:
---
title: Renewal call
source: chat
from: bob
created: 2026-07-08
---
Client agreed to renew. Follow up Monday.
The next brain cycle compiles that note into bob's vault — and, because of the compiler, only bob's. From there the assistant protocol in the master AGENTS.md routes it out of the Inbox. See the CLI reference for every flag.

It fails closed

  • Unknown senders are refused. With --from <email>, the address must match a person's email in org.yaml; an unrecognized sender is rejected, never guessed onto someone.
  • The note can only land in that person's Inbox. The target path is constructed, not taken from input, and is re-checked against write permissions — a crafted title can't escape into a shared space.
  • Untrusted content can't forge metadata. A newline or stray --- in the title, sender, or source is rejected, so channel input can't inject frontmatter keys.
  • Every intake is auditable. Each note is its own git commit under the Brain Ingest <ingest@brain.local> identity, distinct from authenticated write-backs.

Channels

Each channel below is an integration recipe — a thin wrapper that turns an incoming message into a brain ingest call. None of them ship as a running service; they're patterns you wire up with tools you already have.

Email in

Give each person an address that forwards to a small handler which extracts the sender, subject, and body, then calls brain ingest:
# invoked by your mail pipe with the parsed message on stdin
brain ingest --master /srv/brain/master \
  --from "$SENDER_EMAIL" --title "$SUBJECT" --source email
Set each person's email: in org.yaml so --from can resolve them. Anything they can email — a forwarded thread, a note to self — becomes an Inbox item. The recipe supplies plain text; brain ingest does not parse raw .eml or attachments.

Chat DM

Let someone text their own brain. In the per-person gateway model, each employee runs their own chat bot locked to them, so the person is already known — the handler just calls:
brain ingest --master /srv/brain/master --person bob --source chat
A shared, multi-user bot is deliberately avoided: it would be one process that can write into everyone's Inbox. Per-person gateways keep each intake path scoped to one person.

Voice memos

Record a thought, transcribe it (any speech-to-text step), and pipe the transcript in:
transcribe memo.m4a | brain ingest --master /srv/brain/master --person bob --source voice

Share sheet & uploads

Point a synced "drop" folder or a phone share-sheet target at a tiny loop that ingests each new file:
brain ingest --master /srv/brain/master --person bob --file "$DROPPED_FILE" --source upload
With --file, the original filename is recorded as original-name and, absent --title, becomes the note's title.

Webhooks — automatic intake from other services

For services that can push events — meeting-notes tools (Fathom), automation platforms (Zapier, Make, n8n), or Composio triggers watching your email and chat — brainkit ships a small authenticated receiver:
brain webhook --master /srv/brain/master
Unlike the recipes above, this one is a running service, because webhook senders need a URL that's always listening. Sources are declared in _meta/webhook.yaml (server-only, never compiled into any vault):
sources:
  - id: fathom-alice                # POST /hook/fathom-alice
    person: alice                   # every delivery lands in alice's Inbox
    verify: standard-webhooks       # HMAC signatures (Fathom, Composio, …)
    secret_env: WEBHOOK_FATHOM_ALICE_SECRET
    source: fathom                  # provenance label on the note
    body_field: transcript          # payload field holding the note text

  - id: zapier-intake
    route: sender-email             # resolve the person from the payload's
    email_field: email              #   email via org.yaml — unknown senders refused
    verify: token                   # shared-secret header, for senders that can't sign
    secret_env: WEBHOOK_ZAPIER_TOKEN
    source: zapier
Secrets never live in the file — each source names an environment variable, and a source whose variable is unset refuses to start. Two verify modes cover the sender landscape: standard-webhooks checks the Standard Webhooks HMAC signature (with replay protection) that Fathom, Composio, and a growing list of providers send; token checks a shared secret in the Authorization: Bearer or X-Brain-Token header for platforms like Zapier and Make that can add headers but not sign requests. Duplicate deliveries (providers retry) are detected by webhook-id and ingested once. Each source is also rate limited — 60 accepted deliveries per minute by default, tunable per source with rate_limit — so even a leaked secret can only trickle notes in, not flood an Inbox. Refused deliveries get a retryable 429, so providers redeliver them and nothing is lost.
After authentication, every delivery goes through the same brain ingest primitive as every other channel — same constructed path, same write-permission check, same frontmatter sanitizing, same audit commit. The receiver decides who may deliver; it never decides where bytes land.
The receiver binds 127.0.0.1 by default. To accept deliveries from the internet, put a TLS reverse proxy (Caddy, nginx) in front and point providers at https://your-host/hook/<source-id>. brain doctor checks that webhook.yaml parses, its people exist, and every secret variable is set.
Getting started is deliberately short: brain init scaffolds a commented _meta/webhook.yaml.example you can copy and fill in, brain status reminds you when intake isn't configured yet, and deploy/brain-box/ ships a ready-to-install systemd unit (brain-webhook.service) and Caddy snippet (Caddyfile.webhook). That snippet assumes Caddy terminates TLS itself; if your box sits behind edge-terminated TLS (a CDN plus an outbound-only tunnel), use the adapted wiring under "Fronting the receiver" in the reference deployment instead.

The dashboard's Capture button

The live brain dashboard is itself a capture surface: a Capture composer in the header writes a note straight into your Inbox, and the composer names the exact destination (People/<you>/Inbox) before you save. It reuses the same constructed-path, sanitized-frontmatter, symlink-refusing builder as brain ingest — the difference is only where the note lands first. Under the admin (master) lens it calls brain ingest directly and commits immediately; under a person's own vault lens (the compiled slice, which has no master to write) it writes into that slice's People/<you>/Inbox/, and the next brain cycle's write-back carries it to master — the same trust boundary Obsidian edits already pass through.
Ingest writes directly to master; the next cycle compiles it out. A heavy pipeline should funnel through one queue rather than run many ingests concurrently against the same master — there is no cross-process lock. Content still lands correctly; this only avoids an ingest racing a cycle's commit.

Articles and links: the Intel wiki

Sending an article link, a PDF, or a screenshot of a post to your agent uses the same channels as everything else — the difference is what the agent does with it. It reads whatever you send (fetches a URL, extracts a PDF's text, reads an image with vision or OCR), then follows the vault protocol: distill, never archive. It pulls the durable facts and routes them to Company/Intel/ — one flat page per subject, every claim cited [source](URL), as of YYYY-MM. The source is the URL when there is one, or the publication, title, or uploaded filename when there isn't; the date is the source's own, or captured YYYY-MM (today's) when the source shows none. The full text or file never enters the vault — the citation is the record. The person's own take on the piece stays in their People/<person>/Notes/.
Not everything distilled belongs in Intel, though: a piece about a client you already track lands on that client's page, and a personal read of an article lands in Notes/. Those pages carry no folder convention saying "this came from somewhere else", so the agent marks them explicitly — distilled: <URL or title> in frontmatter — and cites the claims the same way. brain doctor holds those pages to the same rule as Intel (citations: no dated citation, or a newest one over 12 months old), and brain doctor --net can go further and check whether the cited source still resolves. See brain doctor.
Writes follow the normal promotion gate, using whichever mode fits:
  • New subject → the agent promotes a new page (say, Company/Intel/Portugal.md) with mode: create, linked both ways with related pages and from the Intel/Home.md map.
  • Page already exists → the agent promotes with mode: append to add its note under a divider, or mode: patch carrying the complete revised page when the update reshapes more than one section. Either way the target is the existing page itself — no separate file, no addendum to fold in later.
A lingering <Name> — updates YYYY-MM.md file in Company/Intel/ is legacy unfolded work from the old addendum flow, not something a current agent should create. brain doctor flags it as a warning — fold it into the main page and delete it by hand if you spot one.
The compiled protocol also tells agents the vault is their only knowledge base, and the profile disables the runtime's bundled wiki skill — otherwise a "add this article to my knowledge base" request could build an unsynced wiki inside the container, invisible to the brain, exactly like a native memory tool would.
Powered byHolocron