Consensus Grain

What is a Consensus grain?

A Consensus grain records an agreement reached by multiple agents or observers. It tracks who participated, how many agreed versus dissented, what threshold was required, and the content that was agreed upon. Consensus grains are the outcome layer for multi-agent deliberation in the context database.

In the AI agent memory system, Consensus grains turn individual observations into collective decisions. The autonomous memory engine uses the threshold and agreement count to determine whether quorum was reached — enabling quorum-based decision-making across agent fleets. A typical multi-agent pipeline flows from Observation (each agent perceives) to Consensus (agents vote) to Belief (the agreed fact is stored as a triple).

The text representation used for embedding and BM25 indexing is the agreed_content field. When no content is set, a summary like "5/0.67 agreement" is generated from the agreement count and threshold. This lets you search for consensus decisions by their content.

Plus all common fields (confidence, tags, namespace, etc.).

How do I create a Consensus?

Pass the participant list, vote counts, threshold, and agreed content through the /batch-add endpoint with grain_type: "consensus". All fields are optional, but include at minimum agreed_content and participating_observers to make the grain useful.

Set threshold to the minimum agreement ratio required for the consensus to be valid. A threshold: 0.67 requires two-thirds majority; threshold: 1.0 requires unanimity. The agreement_count and dissent_count fields record the actual vote totals, so downstream consumers can verify whether the threshold was met.

Use confidence to express the overall certainty in the agreed conclusion. A unanimous consensus (agreement_count: 3, dissent_count: 0) might carry confidence: 0.95, while a bare-majority consensus (agreement_count: 2, dissent_count: 1) might carry confidence: 0.70. This score propagates to any Belief grains derived from the consensus.

import areev

db = areev.open("./data")
h = db.add("consensus", {
    "participating_observers": ["agent-1", "agent-2", "agent-3"],
    "threshold": 0.67,
    "agreement_count": 3,
    "dissent_count": 0,
    "agreed_content": "Customer intent is purchase, not browsing",
    "confidence": 0.95
})

POST /api/memories/default/batch-add
Content-Type: application/json

{
  "grains": [
    {
      "grain_type": "consensus",
      "fields": {
        "participating_observers": ["agent-1", "agent-2", "agent-3"],
        "threshold": 0.67,
        "agreement_count": 3,
        "dissent_count": 0,
        "agreed_content": "Customer intent is purchase, not browsing"
      }
    }
  ]
}

areev add consensus agreed_content="Customer intent is purchase" agreement_count=3 threshold=0.67

How do I record dissent?

When not all participants agree, record both the agreement and dissent counts along with the hashes of grains that represent the dissenting positions. The dissent_grains array links directly to the observations or reasoning grains that represent minority views.

Preserving dissent is critical for audit trails and for agents that revisit past decisions. If new evidence emerges that supports a previously dissenting position, the agent can find the original dissent grain, re-evaluate, and create a new consensus that supersedes the old one. Without recorded dissent, the context of the original disagreement is lost.

The dissent grains are typically Observation or Reasoning grains written by the dissenting agents before the vote. Link them by hash in the dissent_grains array so that the full deliberation history is traversable from the consensus grain.

dissent_obs = db.add("observation", {
    "content": "customer intent is browsing",
    "observer_id": "agent-3",
    "observer_type": "llm",
    "subject": "customer-intent"
})

h = db.add("consensus", {
    "participating_observers": ["agent-1", "agent-2", "agent-3"],
    "threshold": 0.67,
    "agreement_count": 2,
    "dissent_count": 1,
    "dissent_grains": [dissent_obs],
    "agreed_content": "Customer intent is purchase",
    "confidence": 0.78
})

POST /api/memories/default/batch-add
Content-Type: application/json

{
  "grains": [
    {
      "grain_type": "consensus",
      "fields": {
        "participating_observers": ["agent-1", "agent-2", "agent-3"],
        "threshold": 0.67,
        "agreement_count": 2,
        "dissent_count": 1,
        "dissent_grains": ["<dissent_observation_hash>"],
        "agreed_content": "Customer intent is purchase"
      }
    }
  ]
}

When should I use Consensus vs. Belief?

Use Consensus to record that multiple agents deliberated and reached an agreement, preserving the voting record and any dissent. Use Belief to store the resulting knowledge claim as a structured triple.

A consensus grain says “3 out of 4 agents agreed on X”; a belief grain says “X is true.” Both serve different query patterns: consensus grains answer “how was this decided?” while beliefs answer “what do we know?” The recommended pattern is to create both — a Consensus grain for the process and a Belief grain for the outcome — linked via related_to.

If only a single agent makes a determination without multi-agent deliberation, skip Consensus and store a Reasoning grain instead. Consensus is specifically for scenarios where multiple independent observers contribute to a collective decision.

Related

• Grain Types: Overview of all 10 OMS grain types and shared fields
• Observation: For individual perceptions that feed into consensus
• Belief: For storing the agreed conclusion as a knowledge triple
• Reasoning: For inference chains behind each participant’s position