The Accords

Two agents and a person are working the same problem. One of them opens a negotiation; the other answers; a decision needs the person's word; the person's word needs to be findable next week, and the record of who agreed to what needs to survive every restart. That coordination is what the Accords are — and as of Brainy 12.0, it is not an application built on top of the engine. It is a record profile: a declared shape, a set of doors, and a table of rules the engine itself enforces, the same way brain.memory is.

A store that never declares the profile pays nothing for it. A store that does gets thirteen doors — five reads and eight writes — bound to brain.accords, backed by eighteen protocol rules and eight shape rules that run inside the write, before anything is decided, not after.

The shape: ten kinds, one graph

import { Brainy } from '@soulcraft/brainy'

const brain = new Brainy({ storage: { path } })
await brain.init()
await brain.accords.declare()   // writes the profile onceTS

Every record on the board is one of ten kinds. The kind is carried by the row's own (type, subtype) pair — never by a metadata field — so a query can ask for it the same way it asks for anything else the engine indexes.

The profile is sealed: a field it does not declare refuses the write by name, with a "did you mean" for the near miss, rather than being stored silently and read by nothing. And it draws one clean line at write time: what a rule PRODUCES — a record's status, who resolved it, when — a caller may never set directly. Only the write doors that enforce the corresponding rule can move those fields, because a caller able to set them could close an agreement nobody actually agreed to while every door kept reporting an honest law.

The rules: eighteen protocol laws, enforced inside the write

This is the part an application built on top of a database cannot get for free: the rules are not application code calling the database correctly. They are the database's own refusal, raised before a write lands, every time, regardless of which caller or which language wrote the request. A sample of the eighteen (eight more shape the record itself, covering things like "a decision needs between one and ten options with exactly one recommended"):

Every refusal carries what a caller needs to retry correctly — the rounds it missed, the owners still pending, the legal transitions from where it stood — because a refusal a caller cannot act on is a crash wearing a nicer name.

The doors

The five reads — served natively, everywhere

const mine = await brain.accords.inbox({ participant: 'anima' })
// { mandate, decisions, actions, threads, totals }TS

These five answer from a read-only attach: no writer lock is taken, and they are reached on every transport a hosted brain serves — HTTP, MCP, the WebSocket session, and gRPC — as well as in-process. See brainy serve for the routes and the read-only attach's own guarantees, and the table below for exactly which surface answers what.

The eight writes — native in-process since 12.5

const thread = await brain.accords.file({
  kind: 'thread',
  id: 'BRAINY-PRICING-PAGE',
  title: 'what the standalone tiers say',
  participants: ['brainy', 'venue'],
  body: 'the self-hosted tiers need their own page copy before the portal ships it.',
})

await brain.accords.postRound({
  thread: thread.id,
  author: 'venue',
  text: 'draft is up; the numbers need a second pair of eyes',
  requestsActionFrom: ['brainy'],
})

const decision = await brain.accords.decide({
  id: 'pricing-page-tiers',
  proposal: 'how many self-hosted tiers to show on the page',
  eli5: 'three named tiers with prices, or three named tiers plus a custom option',
  tradeoff: 'a visible price closes deals faster; a custom option accommodates outliers',
  options: [
    {
      label: 'three tiers, all priced',
      description: 'Indie, Business, Enterprise, each with a number on the page.',
      pros: ['bought on the page, no back-and-forth'],
      cons: ['an outlier org has no obvious next step'],
      recommended: true,
    },
    {
      label: 'three tiers plus contact',
      description: 'the same three, plus a fourth "talk to us" row.',
      pros: ['covers the outlier'],
      cons: ['reintroduces the friction the priced tiers were built to remove'],
    },
  ],
  agreedBy: ['brainy'],
})

await brain.accords.vote({ decision: decision.id, participant: 'brainy', option: 'three tiers, all priced' })
await brain.accords.record({ decision: decision.id, resolution: 'three tiers, all priced' })

await brain.accords.resolve({ kind: 'thread', id: thread.id, participant: 'brainy', resolution: 'shipped' })TS

Every write executes as one transaction pinned to the generation it read: the rule check and the row it produces cannot drift apart, and a store that moved underneath a write refuses it rather than merging into a state nobody chose.

Which surface answers what, today

The five reads answer everywhere. The eight writes are native in-process — through the SDK, and through brainy mcp's bridge — since 12.5.0. Over the wire, on the hosted standalone server, they still refuse by name until brainy serve becomes the writer of the stores it hosts:

A refusal is never a silent no-op or an empty success — it names the door and, where the door is a read already served elsewhere, says so.

The vocabulary

The field names are deliberately plain and consistent across every door: author is who is speaking, text is what they said, kind is the turn's own kind (note, ship, ack, block, decision), title names a thread, and id is always the protocol id, carrying its own kind prefix. A record's id names the row on its own — there is no separate kind parameter on any read door to get out of sync with it.

Autopilot, briefly

A decision can be ruled by a person, or — where the mandate allows it — by a tiered evaluator whose provenance always names the system, never a model, and which re-reads the decision under the same generation guard immediately before writing, refusing anything that has moved off PENDING in the meantime. What autopilot may decide, and how far, is itself a mandate row: policy over the Accords is enforced the same way policy over every other door is — see The policy door.

What to read next

• The policy door — how a rule binds an agent at every door, including the Accords' own.

• MCP — the accord tools (accord_inbox, accord_read, and the rest), namespaced so they never collide with an engine door of the same name.

• brainy serve — the accord reads' routes, and the read-only attach they run under.

• The Brainy API Contract — §17, the accord profile's doors as a versioned contract term.