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.
The kinds
Section titled “The kinds”| 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.
What a decision rests on
Section titled “What a decision rests on”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 |
Facts are statements
Section titled “Facts are statements”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.
Documents an agent writes
Section titled “Documents an agent writes”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.
When something underneath moves
Section titled “When something underneath moves”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 iscurrentwith nothing monitored.needs_review: something it rests on moved.reasonssays 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_changedwhen the record it rests on changed itself;upstream_changedwhen 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.
Reversing a decision is one change
Section titled “Reversing a decision is one change”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:
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.
Still holds, and confirmed
Section titled “Still holds, and confirmed”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_reviewuntil something it rests on moves again, and emits arecord.affirmedevent on the preview/eventsstream; - is
409with the record’s currentvalidityinerror.detailsif a move landed after the position you read, or a cited document was served at a new version since; - is
403for an ordinary Brain key or OAuth agent session without a person attestation. An organization management key or signed-in console session can attach the optionalattestedPerson: { id, name }when it mints a Brain key; Nicia records the issuer’s organization and credential on the resulting immutablepersonAttestation. 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.
Revise and stand behind it
Section titled “Revise and stand 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.
One rule, from capture to Still holds
Section titled “One rule, from capture to Still holds”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.
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:
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: activearea: pricingbased_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:
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.
Cite a source where it lives
Section titled “Cite a source where it lives”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.
Checking cited sources
Section titled “Checking cited sources”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.
Who was served it
Section titled “Who was served it”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.