Skip to content
Beta. This surface may change before GA; breaking changes are dated in the changelog.

Decisions, rules, bets and beliefs

Most of what a team knows is not a fact about a customer. It is a choice somebody made, a rule that follows from it, a goal the team is betting on, and a belief they all lean on. Those live in docs, chats and heads, and they go stale without anyone noticing.

Every Brain on the default nicia-base vocabulary already declares kinds for them. Your agents write them from the material the team has, the Brain keeps track of what each one rests on, and when something underneath moves, every record that depended on it says so on its next read, to every agent that reads it. Nothing here needs a schema of your own. A Brain created with nicia-core, or with a custom schema that does not extend nicia-base, chose its own vocabulary and does not get these kinds. A custom schema that extends nicia-base keeps them.

Kind Means status values
decision A choice someone made, including a committed plan active, superseded, withdrawn
rule What someone must or must not do until it changes: a policy, a requirement, a standing instruction or preference active, superseded, withdrawn
bet A goal the team is working toward, with a target or a deadline open, supported, refuted, abandoned
belief Something assumed but not yet established open, supported, refuted, abandoned

For a bet, supported reads as met, refuted as missed and abandoned as dropped. A fact is not one of these: it is a statement, which a commitment can rest on. Anything else (a person, an invoice, a meeting, a system) is a kind of your Brain’s own, declared the first time an agent saves one.

All four also declare area and owner (strings). A decision adds origin (deliberate, correction or recurring), decided_on (a date) and decided_by, free text with three conventions: person:<slug>, model:<provider>/<model>@<version> and system:<name>. A body of people, such as a committee or a board, is group:<slug>, for example group:credit-committee. A plain name such as Maya Okafor is written as person:maya-okafor and reported as decided_by_normalized, so send group: for a body, never its bare name. A rule adds applies_to (a list), effective_on and review_by. A bet adds deadline (a date; moving it reopens nothing) and review_by, and a belief adds review_by. A review_by date raises a date.reached event two weeks before it and again on the day, so a rule can ask to be looked at on a schedule. From that day the rule, bet or belief reads needs_review with a review_due reason until its review_by is a later day, unless it was withdrawn, superseded, refuted or abandoned. The prose of a record is its fields.body (how to write it), and its display name is its label: name a record for what it says, never for the role of whoever owns it.

None of the four declares consequence. Agent writes to them land unless they would change a value a person set, like any other record; a team that wants every change looked at chooses the approval-only level.

Five links relate them. A link is written in links, like any other.

Link From → to Rests on it?
based_on decision, rule, bet or belief → decision or statement yes
exception_to rule → rule yes
assumes decision, rule or bet → belief or bet yes
states note → any kind yes
replaces decision or rule → decision or rule no

“Rests on it” is the point of the grounds links: the record at the other end is a ground of this one. A citation is a ground as well, so a record’s grounds are its citations and its outgoing based_on, exception_to, assumes and states links. replaces records a reversal and is not a ground. A link to a record the Brain does not hold yet is a 400, so write the target first or send both in one POST /batch.

Which links count as grounds depends on the kind that rests:

Record Rests on
decision the decision or statement it is based_on, the beliefs and bets it assumes, and its own citations
rule the decision or statement it is based_on, the rule it is an exception_to, the beliefs and bets it assumes, and its own citations
bet the decision or statement it is based_on, the beliefs and bets it assumes, and its own citations
belief the decision or statement it is based_on, and its own citations
note the records it states, and its own citations

A fact is a statement, a kind every Brain has: something a source says is so, such as a measurement, a finding or what a customer said. A commitment rests on one through based_on. A statement declares no grounds fields, so any accepted change to it reopens everything resting on it. To rest a record of your own on records of your own, declare a grounds link on your kinds: see Grounds on your own kinds.

A rule is a record, and nothing executes it. It reopens when what it rests on moves, or when its review_by date passes. Once the date has passed, saying it still holds means setting the next one: send fields.review_by with a revision, which writes the date and affirms the rule in one call (a plain affirm is a 400). The public HTTP API has no way to attach an action to a rule, so “re-run the valuation when the projections change” is something your own agent does when it reads the rule or decision as needs_review.

A document an agent writes for a person, such as an analysis, a memo or a plan, is a note record: its text is fields.body, and links.states names the records it reports. Saved in the same call, the note and the records it states are one write.

{
"records": [
{
"id": "seattle-buyers-pay-list",
"kind": "belief",
"label": "Seattle buyers pay list price",
"fields": { "status": "supported" },
"sources": [{ "ref": "https://example.com/seattle-pricing", "quote": "Seattle buyers paid list price in all nine pilot deals." }]
},
{
"id": "seattle-entry-memo",
"kind": "note",
"label": "Seattle entry memo",
"fields": {
"body": "Enter Seattle in Q1. Buyers paid list price in all nine pilot deals.",
"original": "https://claude.ai/artifacts/seattle-memo"
},
"links": { "states": ["seattle-buyers-pay-list"] }
}
]
}

states is a grounds link, so the note has validity like a decision or rule. When a record it states changes, is withdrawn, or is a belief that is refuted, the note reads needs_review with the reason, on GET /records/{id} and on /context. A stated record whose own cited document changed reopens that record, not the note. A person’s Still holds clears it until the next move. The note is not served as confirmed; that line is for decisions, rules and beliefs.

Each stated record cites where it came from: the pages the agent read, or the conversation saved once as a pasted source. A record never cites the note that states it, since the note is built from the records and not the other way around.

For MCP save, omitted sources always preserves the exact existing citations on a merge, including when an existing assertion changes. The merge still goes through ordinary admission. Inherited citations remain useful for monitoring, but are not fresh grounding for changed values; the save response warns that the old sources may not support them. A full PUT is a replacement: identical data with omitted evidence is a no-op that keeps citations, while a changed replacement with omitted evidence clears them.

original is a plain field, not a link. It holds where the document was first rendered, such as an artifact URL or a file path. It is a pointer for a person to follow, never the authority: the Brain’s copy is the note.

Every Brain on nicia-base, including those created before the link existed, has states. A Brain that declares its own states link keeps it as declared and does not gain this one. states leaves a note only from the note kind. A schema that names its free-form kind something else, such as doc, does not carry it unless it declares the link itself.

Validity is worked out when a record is read and never stored. Every decision, rule and belief is served with validity, and so is a record of any other kind but a statement that cites a document by quote or anchor:

  • current: nothing the Brain monitors for this record has moved since it was last stood behind. A record that rests on nothing is current with nothing monitored.
  • needs_review: something it rests on moved. reasons says what.
  • monitoring_incomplete: the Brain cannot say. The reason names why, for example that a cited external source has gone unchecked for 30 days, or that the walk below hit a bound.

What counts as a move is defined by the kind. Changing a record’s body, a citation, or one of its grounds links always counts, and so does deleting it. Of the fields, only the ones the kind monitors count: for these kinds, status changing into superseded or withdrawn (refuted or abandoned for a belief), and applies_to on a rule. Editing owner or area reopens nothing.

Reopening is transitive, to three links. A rule based on a decision that assumes a belief reopens when the belief is refuted. A reason says how far the change travelled:

  • input_changed when the record it rests on changed itself;
  • upstream_changed when something further along the chain did.

reasons lists every move since the record was last stood behind, so a record that was reopened twice carries both: match a reason by its recordId rather than by position. Each carries path, the links from this record to what moved, and change, saying what moved: a field (with the value it changed to, for an enum), the body, a pin, a link, or a deleted record. A chain deeper than three links, or with more than 200 records behind it, reads monitoring_incomplete naming the bound rather than current. /context serves a reopened record with its text and at most three reasons, plus reasonsOmitted; GET /records/{id} and POST /query return all of them.

A record’s own citations count too. When a document it quotes gets a new version without the quoted words, or a section it anchors reads differently, the record reads needs_review with a support_at_risk reason whose citation says what the check found and which versions it compared, for example { "finding": "passage_absent", "citedVersion": 1, "version": 2 }. finding is passage_absent, anchor_changed, or anchor_missing.

A later version that holds the words again clears it with no one touching the record. A citation that names only the document never reopens anything; see Cite your sources for each case.

Moved evidence stays on the record that cites it. A note that states a rule, or a rule based_on a decision, does not reopen because the rule’s or the decision’s cited document changed. It reopens when that record’s own fields or body change, for example when someone revises the rule after reading its reason.

{
"validity": {
"state": "needs_review",
"reasons": [
{
"kind": "upstream_changed",
"recordId": "buyers-prefer-annual",
"path": [
{ "edge": "based_on", "recordId": "annual-billing-only" },
{ "edge": "assumes", "recordId": "buyers-prefer-annual" }
],
"change": { "kind": "field", "field": "status", "to": "refuted" }
}
]
}
}

current is not a claim about the world. It says the monitored scope did not move, and validity.monitored and validity.observedThrough say what that scope was and up to where in the Brain’s log it was checked.

A decision that is reversed is a new decision linked to the old one with replaces, and the old one is marked superseded. Fixing what was recorded, a typo or a wrong fact, is an ordinary update in place. The difference matters because an in-place rewrite still reopens what rests on the record, but loses the fact that one decision replaced another.

The Brain refuses a half-written reversal. A batch that adds replaces to an active record without setting that record’s status to superseded is rejected, and the reason names the write that is missing. Send both together:

Terminal window
curl -X POST "$API/v1/brains/tenant:acme/batch" \
-H "authorization: Bearer $NICIA_KEY" \
-H "content-type: application/json" \
-d '{
"records": [
{
"id": "annual-and-monthly-billing",
"kind": "decision",
"label": "Bill annually and monthly",
"fields": { "status": "active", "origin": "deliberate", "area": "pricing" },
"links": { "replaces": ["annual-billing-only"] }
},
{
"id": "annual-billing-only",
"kind": "decision",
"fields": { "status": "superseded" }
}
]
}'

A target that is already superseded or withdrawn is accepted. When a proposal waits in Review, the same rule applies at publication: a selection that would publish replaces without the target’s status change is refused with the same reason. Statements keep their own model, where an accepted supersedes_statement link makes the older one superseded; they do not use replaces.

The next read of every rule that rests on the old decision says needs_review, with the reason above.

A reopened record is not wrong, only unchecked. A person looks at what moved and either revises it, withdraws it, or says it still holds, with POST /v1/brains/{handle}/records/{recordId}/affirm. Send the observedThrough position of the validity you read, and optionally ifMatch and a note of 500 characters or fewer. A person may use a signed-in session or a Brain key whose issuer attached a personAttestation; either needs the review capability. An affirmation:

  • is a statement about the record’s current version and changes no value. It is not support for what the record says, needs no evidence, and may rest on knowledge from outside the Brain;
  • clears needs_review until something it rests on moves again, and emits a record.affirmed event on the preview /events stream;
  • is 409 with the record’s current validity in error.details if a move landed after the position you read, or a cited document was served at a new version since;
  • is 403 for an ordinary Brain key or OAuth agent session without a person attestation. An organization management key or signed-in console session can attach the optional attestedPerson: { id, name } when it mints a Brain key; Nicia records the issuer’s organization and credential on the resulting immutable personAttestation. This records the issuer’s identity assertion; Nicia does not independently verify the named person’s identity. It is not offered over MCP. A management key (nsk_) used directly continues to act as the person who minted it.

Served decisions, rules and beliefs also carry confirmed: true when a person stands behind this version, by affirming it, approving it in Review, or creating it, and nothing it says has changed since. An affirmation through an attested Brain key stands under that key’s attested identity; it does not make the key a person for its writes. Any later change to its body, a grounds link or a grounds field drops it, a person’s change included. A label edit changes nothing. When a change dropped it, lastConfirmed names who confirmed it last, when, and how: by is the native user id or a namespaced external subject, and byName is the display name as it was when they confirmed. The attestation and issuer facts, when present, are retained in the affirmation response, record history, lastConfirmed, affirmedSince on receipt /now, and export. The /context text names them by that name (confirmed: yes — a person stands behind it as it reads: Dana Reyes (approval) on 2026-10-30), or as “a person” when none was recorded, and never by user id. /context tells the reading agent to treat an unconfirmed rule as context, not policy, because an agent write may not have a native-person approval or an issuer-attested affirmation behind it.

To revise a record and stand behind the revision in one call, send POST /v1/brains/{handle}/records/{recordId}/revise with the record token you read as ifMatch, the label, fields or links you change, and evidence when what it rests on changes: evidence replaces what the record cites, so send every citation it keeps. The write is a merge, and the affirmation lands through the write’s own log position, so nothing another writer landed in between is affirmed past. A native person may use a signed-in session; an organization may also issue a Brain key with a personAttestation and both review and write. The key’s merge is still admitted as an agent write under the Brain’s normal policy and protections. If it stages, /revise returns unaffirmed with reason staged; a staged revision is never auto-affirmed. Sent with only evidence, it re-cites the record as it reads: that is how a person who says a rule still holds after its cited passage changed pins it to the passage the document says now. Like an affirmation it is 403 for an ordinary program credential without person attestation, and nothing is written. A write that is rejected, moves nothing, or has something move right after it is answered with unaffirmed and its reason instead of an affirmation.

This walks one rule through the whole loop on a Brain created with no schema. An agent holds a Brain key with read and write in $NICIA_BRAIN_KEY. A person holds the organization key in $NICIA_KEY, which acts as the person who minted it.

1. The agent captures a belief, a decision that assumes it, and a rule based on the decision. One batch, so each link’s target exists when the link is written. The decision cites the memo where it lives.

Terminal window
curl -X POST "$API/v1/brains/tenant:acme/batch" \
-H "authorization: Bearer $NICIA_BRAIN_KEY" \
-H "content-type: application/json" \
-d @capture.json
{
"records": [
{
"id": "buyers-prefer-annual",
"kind": "belief",
"label": "Buyers prefer annual plans",
"fields": {
"status": "open",
"area": "pricing",
"body": "Most buyers would rather pay once a year than every month."
}
},
{
"id": "annual-billing-only",
"kind": "decision",
"label": "Bill annually only",
"fields": {
"status": "active",
"origin": "deliberate",
"area": "pricing",
"decided_by": "person:maya-okafor",
"decided_on": "2026-03-02"
},
"links": { "assumes": ["buyers-prefer-annual"] },
"evidence": [
{
"uri": "https://docs.example.com/memos/billing-2026-q1",
"quote": "We bill annually only.",
"versionToken": "rev-3"
}
]
},
{
"id": "quote-annual-first",
"kind": "rule",
"label": "Quote annual pricing first",
"fields": {
"status": "active",
"area": "pricing",
"body": "Every quote leads with the annual price."
},
"links": { "based_on": ["annual-billing-only"] }
}
]
}

GET /records/quote-annual-first now reads validity.state: "current", with annual-billing-only in validity.monitored.claims, and confirmed: false: an agent wrote it and no person has stood behind it.

2. The belief is disproved. An agent records it as an ordinary update:

Terminal window
curl -X POST "$API/v1/brains/tenant:acme/batch" \
-H "authorization: Bearer $NICIA_BRAIN_KEY" \
-H "content-type: application/json" \
-d '{ "records": [ { "id": "buyers-prefer-annual", "kind": "belief", "fields": { "status": "refuted" } } ] }'

Nothing is written to the decision or the rule. On the next read, both say needs_review: the decision with input_changed, the rule, two links away, with the upstream_changed reason shown under When something underneath moves. An agent that asks /context how to quote is served the rule with that reason in its text:

Quote annual pricing first (rule)
status: active
area: pricing
based_on: [[annual-billing-only]]
validity: needs_review — what this rests on moved or cannot be checked since it was affirmed; treat it as needing review (upstream_changed buyers-prefer-annual: status → refuted via based_on annual-billing-only → assumes buyers-prefer-annual; rests on: annual-billing-only through log position 3)
confirmed: no — no person has confirmed it; treat it as context, not policy
Every quote leads with the annual price.

3. A person looks and decides the rule still holds. They send the validity.observedThrough.position they read, here 3:

Terminal window
curl -X POST "$API/v1/brains/tenant:acme/records/quote-annual-first/affirm" \
-H "authorization: Bearer $NICIA_KEY" \
-H "content-type: application/json" \
-d @affirm.json
{
"observedThrough": 3,
"note": "Annual is still the better deal for most buyers; we lead with it."
}
{
"data": {
"affirmation": {
"recordId": "quote-annual-first",
"kind": "rule",
"version": "88fe30f1-ca7b-86ab-87ac-344013fe400d@r1",
"affirmedBy": "usr_4471",
"affirmedAt": "2026-10-30T18:04:35.441Z",
"position": 4,
"observedThrough": 3,
"note": "Annual is still the better deal for most buyers; we lead with it.",
"acknowledgedEvidence": []
}
}
}

The same call with an ordinary agent key is 403, even with review. An organization management key or signed-in console session can instead mint a Brain key with review and an attestedPerson; that key can affirm under its attested identity while its writes remain agent writes. The issuer and identity facts are shown in the response and the record.affirmed event.

4. The rule reads current and confirmed. The affirmation moved validity.affirmed to its own position, so the refuted belief, which moved before it, no longer reopens the rule. lastConfirmed says who stands behind it and how:

{
"data": {
"record": {
"id": "quote-annual-first",
"kind": "rule",
"label": "Quote annual pricing first",
"fields": {
"status": "active",
"area": "pricing",
"body": "Every quote leads with the annual price."
},
"links": { "based_on": ["annual-billing-only"] },
"validity": {
"state": "current",
"reasons": [],
"accepted": { "position": 2, "at": "2026-10-30T18:04:34.575Z" },
"affirmed": { "position": 4, "at": "2026-10-30T18:04:35.441Z" },
"monitored": {
"claims": ["annual-billing-only"],
"sources": [],
"closure": 2
},
"observedThrough": { "position": 4, "at": "2026-10-30T18:04:35.441Z" }
},
"confirmed": true,
"lastConfirmed": {
"by": "usr_4471",
"byName": "Dana Reyes",
"at": "2026-10-30T18:04:35.441Z",
"via": "affirmation"
},
"token": "brain-record-token-v1:e127a8e0e7ad6f376d4ff5411ad2d60c0bf3351b146d1fca283b5f16f3eef288",
"updatedAt": "2026-10-30T18:04:34.558Z"
},
"staged": 0,
"warnings": [],
"receipt": "01a18dfc-295e-7512-8693-da2e44cffc80"
}
}

The decision still reads needs_review until a native person or an issuer-attested person affirms, revises or withdraws it too: an affirmation covers one record. Had the person decided the rule no longer holds, they would have withdrawn it (status: "withdrawn"), or written a new rule that replaces it, as in Reversing a decision is one change.

Evidence on these records may point at a document in the Brain or at a source outside it. Cite in place when the source has an address your team controls (a Drive file, a Notion page, a GitHub file, a URL), and save a document to the Brain only when it has none.

{
"kind": "decision",
"label": "Weekly release train",
"fields": {
"status": "active",
"origin": "deliberate",
"area": "engineering"
},
"evidence": [
{
"uri": "https://example.com/memos/release-train",
"quote": "We ship every Thursday.",
"versionToken": "rev-41"
}
]
}

A citation belongs to the version of the record that carried it. A later write that changes the record and does not cite the source again leaves the new version without the citation, so send evidence again on a write that should keep it, as the status change in a reversal does for the decision it supersedes.

The Brain keeps the quote, so a receipt shows the words that were cited. It does not hold the source, cannot check the quote against it, and never fetches it. Reads serve the citation with lastObserved, the last report of what the source said.

An agent that re-reads a cited source reports what it found with POST /v1/brains/{handle}/citations/observations, per quote it checked: present or absent in the version it read. Only a reported absent reopens the citing records, with support_at_risk, and it stays until a person says the record still holds or the record is cited again with a quote that is present in the version read. A present report refreshes lastObserved but never clears an outstanding absence, because version tokens cannot be ordered. A citation nobody has observed for 30 days reads monitoring_incomplete with bound: "unobserved", naming the source. Over MCP, save reports them: a URL source that carries found reports the quote present or absent.

GET /v1/brains/{handle}/citations/unchecked lists the external citations that nothing has observed lately, for a person or an agent to work through when they choose to. Each entry names the citing record, the citation, its lastObserved when there is one, and its state: unobserved when nothing is known of the quote, stale when nothing has observed it for 30 days. Either state reads monitoring_incomplete in the record’s validity. The read needs read and writes no receipt.

{
"data": {
"citations": [
{
"record": {
"id": "weekly-release-train",
"kind": "decision",
"title": "Weekly release train"
},
"citation": {
"uri": "https://example.com/memos/release-train",
"quote": "We ship every Thursday.",
"versionToken": "rev-41"
},
"lastObserved": {
"at": "2026-09-28T16:12:03.000Z",
"versionToken": "rev-41",
"result": "present"
},
"state": "stale"
}
],
"nextCursor": "eyJzbHVnIjoid2Vla2x5LXJlbGVhc2UtdHJhaW4iLCJpbmRleCI6MH0"
}
}

Re-read the source and report what you found with POST /citations/observations. A present report takes the citation off the list; an absent one reopens every record citing that quote, which then waits for a person like any other reopened record. A citation whose reported absence is outstanding is not listed, because its record has reopened. Leaving a citation unchecked is a valid choice: the list feeds no count of what needs a person, and nothing reminds anyone of it.

A page reads at most 200 citing records, in record id order, so it can hold fewer than limit citations and still carry nextCursor. Paging is done when nextCursor is absent.

In the console, a person checks a citation from the record’s Evidence or from Knowledge: Still there reports the quote present and Changed or gone reports it absent, both attributed to that person.

GET /receipts/{receiptId}/now covers every record a receipt served that carries validity, not only standing answers. A record whose grounds moved, or whose own cited evidence moved, after the receipt’s read reports grounds_moved in answers[], even if a person affirmed it afterwards, and adds affirmedSince with who and when. That is how you tell which agents acted on a rule before it reopened.