Grain Type Deep Dive: Belief

Of the ten grain types defined by the Open Memory Specification, the Belief is the most versatile and the most frequently used. It is the type you reach for when an agent needs to record a piece of structured knowledge: a user preference, a relationship between entities, a measurement, a rule, a diagnosis. The Belief type is the knowledge graph primitive of OMS.

This post covers everything you need to know about Beliefs: the semantic triple model at their core, every required and optional field defined in Section 8.1 of the spec, confidence scoring, temporal modeling, protection policies, and practical examples drawn from the spec's test vectors.

The Semantic Triple Model

At its core, a Belief grain is a semantic triple — a subject, a relation, and an object. This model comes from the Resource Description Framework (RDF), the W3C standard for representing information about resources on the web.

The OMS specification defines the RDF mapping explicitly:

<grain:subject> <grain:relation> "grain:object" .

In RDF terms, the subject is the entity being described, the relation (predicate) is the semantic relationship, and the object is the value or target entity. Some examples:

This triple model is simple enough to represent a vast range of knowledge, from user preferences to organizational relationships to safety constraints. That simplicity is deliberate. The spec's design note for the Belief type states:

The Belief type intentionally serves as a broad knowledge representation primitive, accommodating optional fields for temporal validity, bi-temporal system tracking, consolidation history, confidence, and cross-links. This allows simple grains (subject, relation, object, confidence) to coexist with richly annotated ones in the same store without separate type hierarchies.

A Belief that says "user prefers dark mode" and a Belief that says "Alice works at Acme Corp, effective January 1 2025 through December 31 2025, as reported by the HR system on January 16 2025" are both Beliefs. They use the same type byte (0x01), the same required fields, and the same serialization rules. The difference is only in how many optional fields each one populates.

Required Fields

Every Belief grain MUST include these fields. In OMS v1.2, source_type is optional (it was required in v1.0):

That is the minimum viable Belief. Subject, relation, object form the semantic triple. Confidence scores how certain the knowledge is. Source type, when provided, records where it came from. Created_at anchors it in time. Type identifies it as a Belief.

A Minimal Example: Test Vector 1

Section 21.1 provides a minimal Belief grain as the first test vector:

{
  "type": "belief",
  "subject": "user",
  "relation": "prefers",
  "object": "dark mode",
  "confidence": 0.9,
  "source_type": "user_explicit",
  "created_at": 1768471200000,
  "namespace": "shared",
  "author_did": "did:key:z6MkhaXgBZDvotDkL5257faiztiGiC2QtKLGpbnnEGta2doK"
}

This grain records that a user prefers dark mode, with 0.9 confidence, explicitly stated by the user. It also includes three optional fields: source_type (provenance origin), namespace (set to "shared"), and author_did (identifying the creating agent via a W3C Decentralized Identifier).

After canonical serialization and hashing, this grain has the content address:

3288d0d41cf49a1d428e404f0b6a6fe60388be9536937557f6139b813d53a520

For a detailed walkthrough of how that hash is computed, see Content Addressing with SHA-256.

Confidence Scoring

The confidence field is a float64 value in the range [0.0, 1.0]. It represents how credible or certain the knowledge claim is. The spec enforces IEEE 754 double precision encoding and explicitly rejects NaN and Infinity values (ERR_FLOAT_INVALID).

Some practical guidelines for confidence values:

Test Vector 1 uses 0.9 because the belief was explicitly stated by the user (source_type: "user_explicit"). Test Vector 3 uses 0.95 for a bi-temporal employment belief. Test Vector 6 uses 1.0 for a safety constraint.

Source Type: The Open Enum

The source_type field records the provenance origin of the belief. It is an open enum — the spec defines common values but does not restrict implementations to only these — and in v1.2 it is optional for Belief grains:

Source type is critical for downstream consumers. An agent deciding whether to act on a Belief will weight a user_explicit belief differently from an llm_generated one. A compliance system may require that certain actions only be triggered by user_explicit beliefs. A consolidation engine may treat sensor beliefs differently from agent_inferred ones.

Optional Fields: The Full Toolkit

The Belief type defines a rich set of optional fields that accommodate everything from simple preferences to richly annotated bi-temporal knowledge with full provenance chains. Implementations SHOULD populate only the fields appropriate to their use case and treat unused optional fields as absent.

Temporal Modeling

Beliefs can model time in two distinct ways, following the bi-temporal data modeling pattern used in temporal databases.

temporal_type — Either "state" or "observation" (default: "observation"). A state belief represents an ongoing condition ("Alice works at Acme Corp"). An observation belief represents a point-in-time measurement or event ("server temperature was 22.5C").

valid_from / valid_to (int64, epoch ms) — When the belief was true in the real world. This is sometimes called "valid time" or "application time" in temporal database literature. For example, "Alice works at Acme Corp" might have valid_from of January 1, 2025 and valid_to of December 31, 2025.

system_valid_from / system_valid_to (int64, epoch ms) — When the belief was active in the system. This is "transaction time" — the period during which the system considered this belief to be current. system_valid_to is typically set when the grain is superseded.

The distinction between valid time and system time is powerful. It answers two fundamentally different questions:

• Valid time: "When was this belief true in the real world?"
• System time: "When did our system know about (and act on) this belief?"

A Bi-Temporal Example: Test Vector 3

Section 21.3 provides a bi-temporal Belief:

{
  "type": "belief",
  "subject": "Alice",
  "relation": "works_at",
  "object": "Acme Corp",
  "confidence": 0.95,
  "source_type": "user_explicit",
  "created_at": 1737000000000,
  "valid_from": 1735689600000,
  "valid_to": 1767225600000,
  "system_valid_from": 1737000000000,
  "author_did": "did:key:z6MkhaXgBZDvotDkL5257faiztiGiC2QtKLGpbnnEGta2doK"
}

Breaking down the timestamps:

This tells a precise story: Alice's employment at Acme Corp is valid from January 1, 2025 through the end of the year (valid_to is the start of January 1, 2026, marking the exclusive upper bound), and the system became aware of this belief on January 16, 2025 (system time). The belief has no system_valid_to, meaning it is still considered current in the system.

If Alice leaves Acme Corp early, a new grain would supersede this one. The original grain's system_valid_to would be set (by the index layer) to the timestamp of supersession, while the valid_to of the new grain would reflect when Alice actually left. The two timelines evolve independently.

Note that in this example source_type is still included — it is optional in v1.2 but providing it is always recommended when provenance is known.

Knowledge Management Fields

context (map string->string) — A flexible key-value map for contextual metadata. This could include the conversation ID where the belief was learned, the application that produced it, or any domain-specific metadata that does not warrant its own field.

superseded_by (string) — The content address of a grain that replaces this one. When set, this grain is no longer the current version of this knowledge. The supersession chain is the mechanism for knowledge evolution in an immutable system.

verification_status (string) — Index-layer field managed by the store (not embedded in the blob). Values: "unverified" (default), "verified", "contradicted", "disputed". Distinct from supersession: a contradicted belief is not replaced by a better version, its verification_status is updated by the store to "contradicted". Because this field lives in the index layer it is NOT part of the content address or COSE signature.

importance (float64, [0.0, 1.0], default 0.7) — A weighting score for retrieval prioritization. An agent with limited context window space can use importance to decide which facts to include.

Identity and Organization

namespace (string, default "shared") — The memory partition or category. Namespaces enable multi-tenant stores and logical separation of knowledge domains. The namespace is also hashed into the 9-byte header (bytes 3-4) as a routing hint for efficient scanning.

user_id (string) — The data subject identifier, critical for GDPR compliance. This field scopes erasure requests: when a user exercises their right to erasure, the system can identify all grains associated with that user_id.

author_did (string) — The DID (Decentralized Identifier) of the creating agent. This enables cryptographic verification of authorship without a central authority.

structural_tags (array[string]) — Classification tags for organizing and filtering beliefs. Unlike the semantic triple (which represents meaning), tags represent categories: ["preference", "ui"], ["medical", "diagnosis"], ["phi:blood-type"].

Consolidation and Feedback

consolidation_level (int, [0, 3]) — Tracks how refined a belief is:

success_count / failure_count (int, non-negative) — Feedback counters tracking how many times the belief was successfully or unsuccessfully used in downstream tasks. These enable reinforcement-style learning: beliefs that consistently lead to good outcomes have their success_count incremented; beliefs that lead to errors have their failure_count incremented.

derived_from (array[string]) — An array of content addresses identifying the parent grains from which this belief was derived. This is the structural backbone of provenance tracking.

Provenance Chain

provenance_chain (array[map]) — A full derivation trail recording every transformation step:

{
  "source_hash": "abc123...",
  "method": "frequency_consolidation",
  "weight": 0.8
}

Each entry records which source grain was used, what method produced the derivation, and how much weight that source carried. This is more detailed than derived_from (which records only the parent hashes) and enables rich audit trails.

Protected Beliefs: Invalidation Policy

Some beliefs are too important to be casually overridden. Section 23 defines the invalidation_policy field, which governs who can supersede or contradict a grain.

Test Vector 6: A Safety Constraint

Section 21.6 provides an example of a protected Belief:

{
  "type": "belief",
  "subject": "agent-007",
  "relation": "constraint",
  "object": "never delete user files without confirmation",
  "confidence": 1.0,
  "source_type": "user_explicit",
  "created_at": 1768471200000,
  "namespace": "safety",
  "invalidation_policy": {
    "mode": "locked",
    "authorized": ["did:key:z6MkhaXgBZDvotDkL5257faiztiGiC2QtKLGpbnnEGta2doK"]
  }
}

This grain has a content address of:

df928038769506fb66671aced0eb97d45871e169e505ed55a382c744e620550e

The invalidation_policy with mode: "locked" means that no supersession or contradiction is permitted — the store MUST reject any attempt and return ERR_INVALIDATION_DENIED. Only the DID listed in authorized could potentially override this (in modes that check authorization).

Protection Modes

The spec defines eight modes for invalidation policies:

The Design Philosophy: One Type, Many Uses

The Belief type's breadth is a conscious design choice. The spec's design note acknowledges this directly:

This allows simple grains (subject, relation, object, confidence) to coexist with richly annotated ones in the same store without separate type hierarchies. Implementations SHOULD populate only the fields appropriate to their use case and treat unused optional fields as absent.

This means the same store, the same serialization code, and the same query infrastructure handle all of the following:

Customer preferences — Simple subject-relation-object triples with user_explicit source type and high confidence:

{
  "subject": "customer-42",
  "relation": "preferred_language",
  "object": "Spanish",
  "confidence": 1.0,
  "source_type": "user_explicit"
}

Medical diagnoses — Bi-temporal beliefs with provenance chains and PHI tagging:

{
  "subject": "patient-A",
  "relation": "diagnosed_with",
  "object": "Type 2 Diabetes",
  "confidence": 0.92,
  "source_type": "imported",
  "valid_from": 1735689600000,
  "system_valid_from": 1737000000000,
  "structural_tags": ["phi:diagnosis", "medical"],
  "provenance_chain": [
    {"source_hash": "abc123...", "method": "ehr_import", "weight": 1.0}
  ]
}

Regulatory rules — Protected beliefs with locked invalidation policies:

{
  "subject": "trading-system",
  "relation": "constraint",
  "object": "maximum single trade size is $10M",
  "confidence": 1.0,
  "source_type": "system",
  "invalidation_policy": {"mode": "locked"},
  "structural_tags": ["compliance", "trading-limits"]
}

Agent-inferred knowledge — Consolidated beliefs with derivation trails and feedback counters:

{
  "subject": "user",
  "relation": "typically_active",
  "object": "9am-6pm EST weekdays",
  "confidence": 0.78,
  "source_type": "consolidated",
  "consolidation_level": 2,
  "derived_from": ["a1b2c3...", "d4e5f6...", "g7h8i9..."],
  "success_count": 14,
  "failure_count": 2
}

Product specifications — Imported beliefs from external systems with content references:

{
  "subject": "widget-X100",
  "relation": "max_operating_temperature",
  "object": "85C",
  "confidence": 1.0,
  "source_type": "imported",
  "context": {"datasheet_version": "3.2", "manufacturer": "Acme"},
  "content_refs": [
    {"uri": "cas://sha256:abc123...", "modality": "document", "mime_type": "application/pdf"}
  ]
}

All of these are valid Belief grains. They share the same type byte (0x01), the same required fields, and the same canonical serialization. The optional fields allow each to carry exactly the metadata it needs — no more, no less.

Field Compaction in Practice

When a Belief is serialized, human-readable field names are replaced by short keys to minimize blob size. The mapping (from Section 6.1) is applied before MessagePack encoding:

After compaction, the keys are sorted lexicographically for canonical serialization. For Vector 6 (the protected belief), the compacted key order is: c, ca, ip, ns, o, r, s, st, t. The nested invalidation_policy map is also sorted: authorized before mode.

Lifecycle of a Belief

Because grains are immutable, the lifecycle of a Belief is expressed through chains of grains rather than mutations to a single record:

1. Creation — A new Belief grain is serialized and stored. Its content address becomes its permanent identity.

2. Supersession — When knowledge changes, a new Belief is created. The old Belief's superseded_by field is set (by the index layer) to the new Belief's content address. The old grain's bytes never change.

3. Contradiction — If a Belief is discovered to be wrong (not just outdated), the store updates verification_status to "contradicted" in the index layer. The original blob bytes remain unchanged — this field is NOT embedded in the grain.

4. Consolidation — Multiple raw Beliefs (level 0) may be consolidated into a higher-level Belief (level 1, 2, or 3). The consolidated Belief records its sources via derived_from and provenance_chain.

5. Feedback — As the Belief is used in downstream tasks, success_count and failure_count are tracked. Because grains are immutable, these counters exist on the latest grain in the supersession chain.

This lifecycle model ensures a complete audit trail. You can trace any current Belief back through its supersession chain, seeing every version, every confidence change, and every derivation.

Summary

The Belief type is the workhorse of OMS. Its semantic triple model provides natural knowledge graph compatibility. Its required fields keep the minimum viable grain small. Its extensive optional fields support temporal modeling, provenance tracking, consolidation, feedback, and protection without requiring type hierarchies or schema extensions.

For details on how the content address of a Belief grain is computed, including the role of the 9-byte header and temporal uniqueness, see Content Addressing with SHA-256.