Belief Grain

What is a Belief grain?

A Belief grain stores a structured knowledge claim as a semantic triple: subject, relation, and object. It is the only grain type whose fields are indexed in the hexastore, giving the AI memory system graph traversal and triple-pattern query capabilities.

Beliefs represent facts, preferences, assumptions, or any knowledge that can be modeled as “X relates-to Y.” The context database indexes all six permutations of each triple (SPO, SOP, PSO, POS, OSP, OPS), so queries on any combination of subject, relation, or object resolve in constant time. This hexastore design comes from RDF database theory and makes Belief grains the backbone of structured knowledge in Areev’s autonomous memory layer.

When you add a Belief through the /add endpoint, Areev writes the triple to the hexastore indexes in addition to the standard BM25 and vector indexes. The text representation used for embedding and full-text search is the concatenation of subject, relation, and object: "john likes coffee". Beliefs added through /batch-add with grain_type: "belief" are stored but not triple-indexed — use /add when you need graph traversal.

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

How do I create a Belief?

Pass subject, relation, and object to the /add endpoint. All three fields are required. The endpoint returns a content-address hash that uniquely identifies the grain.

The /add endpoint is specifically designed for Belief grains. It validates the triple, writes it to the hexastore indexes, and generates the concatenated text representation for BM25 and vector search. You can also create Beliefs through /batch-add with grain_type: "belief", but those grains skip hexastore indexing and will not appear in triple-pattern queries.

Use confidence to express certainty in the knowledge claim. A belief with confidence: 0.5 represents an uncertain assumption; one with confidence: 1.0 represents a verified fact. Agents can use confidence scores to prioritize which beliefs to trust when multiple grains conflict.

import areev

db = areev.open("./data")
h = db.add("belief", {"subject": "john", "relation": "likes", "object": "coffee"})
print(h)  # content-address hash (hex)

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

{"subject": "john", "relation": "likes", "object": "coffee"}

areev add belief subject=john relation=likes object="coffee"

How do I query Beliefs?

Query by any combination of subject, relation, and object for structural lookups, or use full-text search across all grain text. The hexastore indexes all six permutations of the triple, so partial queries (just subject, just relation, or any pair) resolve efficiently.

Structural queries match exact field values against the hexastore. Full-text queries run against the concatenated text representation through BM25. You can combine both: filter by grain_type: "belief" and provide a query string for ranked retrieval. Namespace and tag filters apply on top of either query mode.

When you need to traverse the knowledge graph — for example, finding everything John likes, then finding what else relates to each of those objects — chain structural queries by feeding results back as query parameters. This is how agents build contextual understanding from the AI agent memory layer.

# Structural query -- find all of john's preferences
results = db.recall(subject="john", relation="likes")

# Full-text query -- BM25 search across all grain text
results = db.recall(query="john coffee")

# Filter by grain type
results = db.recall(query="preferences", grain_type="belief")

POST /api/memories/default/recall
Content-Type: application/json

{"subject": "john", "relation": "likes", "limit": 10}

How do I update a Belief?

Beliefs are immutable once stored. To update a belief, supersede it with a new version that carries the corrected fields. The old grain’s superseded_by field is set to the new grain’s hash, creating a verifiable edit history.

Supersession preserves the original grain for auditing. Recall queries skip superseded grains by default, so only the latest version surfaces. If you need the full history, query with include_superseded: true to walk the chain backward. This immutability guarantee matters for compliance scenarios where you must demonstrate what an agent believed at a specific point in time.

The supersession pattern works well for evolving knowledge. An agent might store a belief with confidence: 0.6 initially, then supersede it with confidence: 0.95 after verification, preserving both the uncertain and verified states.

old_hash = db.add("belief", {"subject": "john", "relation": "likes", "object": "coffee"})
new_hash = db.supersede(old_hash, "belief", {"object": "tea"})

POST /api/memories/default/supersede
Content-Type: application/json

{"blob_hash": "<old_hash>", "object": "tea"}

Related

• Grain Types: Overview of all 10 OMS grain types and shared fields
• Event: For timestamped occurrences rather than knowledge claims
• Observation: For perceptions that feed into belief formation
• Consensus: For beliefs agreed upon by multiple agents