Keep it good

A shared brain decays the same way a wiki does — unless contributing is easy and accepting is deliberate. That is what review is for.

The queue

Everything an agent proposes waits here with the passage behind it. Settle it in app.nicia.ai, which shows the diff and the source side by side, or over the API:

curl "$API/v1/brains/team:acme/changes?status=staged" \
  -H "authorization: Bearer $NICIA_KEY"

curl -X POST "$API/v1/brains/team:acme/changes/chg_44a1e0/lifecycle/approve" \
  -H "authorization: Bearer $NICIA_KEY"

curl -X POST "$API/v1/brains/team:acme/changes/chg_44a1e0/lifecycle/publish" \
  -H "authorization: Bearer $NICIA_KEY" \
  -H "content-type: application/json" \
  -H "idempotency-key: publish-chg_44a1e0" \
  -d '{}'

curl -X POST "$API/v1/brains/team:acme/changes/chg_51c8b2/lifecycle/reject" \
  -H "authorization: Bearer $NICIA_KEY" \
  -H "content-type: application/json" \
  -d '{ "reason": "Shipped to staging, not prod" }'

Approving binds the change and publishing applies it; a rejection needs a reason. To take only part of a change, select its operations first.

You are always approving evidence, not an assertion. If a proposal has no passage behind it, that is itself a reason to reject it. See Review for the full model.

Who writes directly

mode sets the policy default, not a per-write override. On an open Brain most writes land immediately; on a reviewed one most agent writes wait, but your own edits and additive schema still land, and destructive changes always wait on both modes. No credential can ask for an exception, because an exception a caller can request is an exception an agent can request. When a service genuinely needs to write straight in while people’s agents are reviewed, give it its own Brain and read across both. See Review.

Let an agent tend it

Nicia’s built-in Brain Agent reads what has landed and proposes maintenance: contradictions between two documents, pages that have gone stale, questions people keep asking that nothing answers.

npx nicia tend team:acme          # or POST /v1/brains/team:acme/tend

Proposed 4 changes:
  · handbook/oncall.md contradicts notes/2026-07-02-oncall-change.md
    on the escalation path
  · 3 documents reference "Project Mercury" — no page defines it
  · handbook/pricing.md last updated 2026-01-14, cited 41 times since

It always proposes and can never write directly. Run it on a schedule and the queue becomes a to-do list for keeping the brain honest.

Standing questions

For the questions your team asks constantly, keep a maintained answer rather than re-deriving it every time. Install the standing-answers schema pack with POST /v1/brains/{id}/schema-packs and { "packId": "standing-answers" }. That one is a console-plane call, not part of the Brain API: it takes the Brain’s platform id — the id field PUT/GET /v1/brains/{handle} returns — rather than the handle, and an organization key rather than a Brain key. Once it is installed, the console’s Pages rail pins a “Standing answers” group above source material, with pending updates routed to Review like any other change.

Installing the pack gives you the kinds, not the maintenance. The maintenance agents and the rebuild automation are configured separately — the Brain’s maintained-knowledge panel in the console walks through that setup and reports what is still missing. Once it is complete, Nicia keeps the answer current as the underlying documents change and tells you when the sources behind it move, so a stale answer becomes a review item instead of a wrong answer.

It is your knowledge

Export the whole Brain, any time, and take it somewhere else.

You arrived with a folder. You leave with a model. No proprietary format, no lock-in, no support ticket.

From the API, an export is an asynchronous job: start it, poll it, download the archive. It needs the read capability, because an export carries the whole Brain out.

curl -X POST "$API/v1/brains/team:acme/exports" \
  -H "authorization: Bearer $NICIA_KEY" \
  -H "idempotency-key: nightly-2026-09-21"

curl "$API/v1/brains/team:acme/exports/0198b6a3-4c5d-7e8f-9a0b-1c2d3e4f5a6b" \
  -H "authorization: Bearer $NICIA_KEY"

curl -o brain-export.zip \
  "$API/v1/brains/team:acme/exports/0198b6a3-4c5d-7e8f-9a0b-1c2d3e4f5a6b/download" \
  -H "authorization: Bearer $NICIA_KEY"

Start answers 202 with a queued export. Poll until its status is completed; the response then carries the downloadPath the archive is fetched from. Repeating a start under the same Idempotency-Key returns the export the first request created instead of a second one, and a key can have one export running at a time — a second start is a 409. Only the key that started an export can read or download it. In TypeScript, @nicia/brain-client wraps the three calls as startExport, waitForExport, and downloadExport.

The .zip holds:

your documents, at the address you gave each one (notes/renewal.md comes back as notes/renewal.md) or the path they were imported from, byte for byte;
every typed record as the Markdown it is stored as — frontmatter and body — under records/<kind>/<slug>.md, plus records.json, its structured projection;
evidence.json, the evidence behind each record, with anchors and your own locators intact, and history.json plus blobs/, the complete revision history with every version’s exact bytes;
receipts.json, the read receipts the exporting key can list — the ones it committed, or every key’s when it holds admin — each with its snapshot, hashes and the version of every source it pinned, but not the text a read was handed;
answers.json, each standing answer’s validity as of the export;
manifest.json, whose root hash covers the documents and their history — the hash the export reports as manifestRootHash;
index.md cataloguing every page, log.md as a greppable activity log, and an AGENTS.md describing the Brain’s own conventions, so any agent can pick the export up and work with it.

What leaves is accepted knowledge and the record of what was served from it. A change still waiting in Review is not part of the Brain yet, so it is not exported, and neither is the external operation ledger.

The Brain menu in app.nicia.ai (“Export brain”) downloads a lighter .zip in one click. It carries your documents, not your accepted state: records.json and evidence.json come out empty, and history.json holds a single genesis entry per document rather than its revision chain. Use the API export when you need everything.

That is the point of the boundary being ours and the knowledge being yours: what leaves is structurally better than what arrived, and it is legible without us.

Review — the API underneath the queue.
Receipts — proving what an answer was based on.