Grain Type Deep Dive: Event

Every conversation an AI agent has, every support ticket it processes, every meeting transcript it ingests — these are raw, messy, unstructured records of what happened. In the Open Memory Specification, these records have a name: Events.

Events are one of the ten grain types defined in OMS v1.2 (Section 8.2). They serve a specific and deliberate purpose in the memory lifecycle: they capture raw interaction text as-is, without any attempt to structure or interpret it. That interpretation comes later, through a process called consolidation, which extracts structured Beliefs from the unstructured event content.

This post covers everything you need to know about the Event grain type: its required and optional fields, how it fits into the consolidation pipeline, how to use content references for multi-modal events, and where Events provide real value in production systems.

What is an Event?

The spec defines an Event as:

Raw, unstructured interaction record. Events are input to consolidation, which extracts structured Beliefs.

That single sentence captures the key design insight. Events are not knowledge — they are the raw material from which knowledge is extracted. Think of it this way:

• An Event records what happened: "The user asked about dark mode settings and said they prefer reduced contrast."
• A Belief records what was learned: subject="user", relation="prefers", object="dark mode" with confidence=0.9.

The Event is a transcript. The Belief is the takeaway.

This distinction is fundamental to how OMS models the knowledge lifecycle. Raw interaction data enters the system as Events, gets processed through consolidation, and emerges as structured Beliefs that can be queried, linked, and reasoned about. The original Event is preserved as an immutable record — an audit trail of where the knowledge came from.

Required Fields

The Event type has a deliberately minimal set of required fields (Section 8.2):

That is it. Three required fields. The content field is a non-empty string containing the raw text of the interaction — a conversation transcript, a log entry, a meeting summary, whatever the event captured. The created_at timestamp follows the OMS datetime convention (Section 4.8): Unix epoch milliseconds as an int64.

{
  "type": "event",
  "content": "User asked about dark mode settings",
  "created_at": 1768471200000
}

This minimal grain is valid. It can be serialized, hashed, stored, and later retrieved. The header byte for Event is 0x02 (Section 3.1.1, Type enum), so this grain's 9-byte fixed header would begin with 01 00 02 — version 1, no flags set, Event type.

Optional Fields

Beyond the three required fields, Events support several optional fields that add context and enable richer workflows:

A few of these deserve closer examination.

The consolidated Flag

The consolidated field is a boolean (default false) that marks whether an Event has been processed through the consolidation pipeline. This is a simple but powerful mechanism for tracking the lifecycle of raw interaction data.

When an Event is first captured, consolidated is absent (meaning false per Section 4.5 null omission rules). Once a consolidation process has extracted Beliefs from the Event, the consuming system can mark it as consolidated. Since OMS grains are immutable, "marking" means creating a new grain with consolidated: true that supersedes the original — the supersession chain tracks the state change.

The importance Field

Events default to an importance of 0.5 — notably lower than Beliefs (which default to 0.7) and Workflows (also 0.7). This reflects the intuition that raw interaction data is less immediately valuable than the structured knowledge extracted from it. Importance values range from 0.0 to 1.0 as IEEE 754 float64 values (Section 4.3).

The namespace Field

The namespace defaults to "shared", which means Events are visible across the shared memory space unless explicitly partitioned. The first two bytes of SHA-256(namespace) are stored in the fixed header (bytes 3-4) as a routing hint, enabling efficient namespace-based filtering without deserialization.

Test Vector: Event in the Wild

Section 21.2 of the spec provides a test vector for the Event type:

{
  "type": "event",
  "content": "User asked about dark mode settings",
  "created_at": 1768471200000,
  "namespace": "shared",
  "author_did": "did:key:z6MkhaXgBZDvotDkL5257faiztiGiC2QtKLGpbnnEGta2doK",
  "importance": 0.5
}

This example includes the three required fields plus three optional fields: namespace, author_did, and importance. When serialized following OMS canonical rules (Section 4.9), the field names are compacted via the field map (Section 6.1), keys are sorted lexicographically, and the result is encoded as canonical MessagePack preceded by the 9-byte fixed header.

The header for this grain would be:

• Byte 0: 0x01 (version)
• Byte 1: 0x00 (no flags — unsigned, uncompressed, MessagePack, public sensitivity)
• Byte 2: 0x02 (Event type)
• Bytes 3-4: SHA-256("shared")[0:2] as uint16 big-endian = 0xa4 0xd2
• Bytes 5-8: created_at in epoch seconds (1768471200000 ms / 1000 = 1768471200) as uint32 big-endian = 0x69 0x68 0xba 0xa0

The full header: 01 00 02 a4 d2 69 68 ba a0.

The Event-to-Belief Consolidation Pipeline

The most important concept surrounding Events is consolidation — the process of extracting structured knowledge from unstructured interaction records.

Here is how the pipeline works:

1. Capture: Raw interactions are recorded as Event grains. The content field holds the full text. No interpretation is applied at this stage.

2. Consolidation: A consolidation process (typically an LLM or pattern-matching engine — the spec deliberately does not prescribe the mechanism) analyzes Event content and extracts structured Beliefs.

3. Tracking: Extracted Beliefs carry a consolidation_level field (Section 6.1) that tracks the depth of processing:

4. Provenance: The extracted Beliefs link back to their source Events through the derived_from field (an array of content addresses) and the provenance_chain (Section 14.1), which records:

{
  "provenance_chain": [
    {
      "source_hash": "<event-content-address>",
      "method": "frequency_consolidation",
      "weight": 0.8
    }
  ]
}

5. Marking: The original Event is marked with consolidated: true (via supersession — a new Event grain that supersedes the original).

This pipeline creates a clean separation of concerns. The Event captures everything faithfully. The consolidation process interprets it. The resulting Beliefs carry explicit provenance back to their source Events. And the immutability of all grains means you can always audit the complete chain from knowledge back to raw data.

A Concrete Example

Consider a customer support agent that processes the following conversation:

Event (captured raw):

{
  "type": "event",
  "content": "Customer Jane Doe called about order #4521. Said the package arrived damaged. Wants a replacement sent to her new address at 123 Oak St. Also mentioned she recently changed her last name to Smith.",
  "created_at": 1768471200000,
  "user_id": "jane-doe-001",
  "namespace": "support",
  "importance": 0.7,
  "structural_tags": ["customer-support", "order-issue"]
}

After consolidation, this single Event might produce multiple Beliefs:

Belief 1 — Order status:

{
  "type": "belief",
  "subject": "order-4521",
  "relation": "status",
  "object": "damaged_on_arrival",
  "confidence": 0.95,
  "source_type": "consolidated",
  "consolidation_level": 0,
  "derived_from": ["<event-hash>"]
}

Belief 2 — Address change:

{
  "type": "belief",
  "subject": "jane-doe-001",
  "relation": "address",
  "object": "123 Oak St",
  "confidence": 0.9,
  "source_type": "consolidated",
  "consolidation_level": 0,
  "derived_from": ["<event-hash>"]
}

Belief 3 — Name change:

{
  "type": "belief",
  "subject": "jane-doe-001",
  "relation": "last_name",
  "object": "Smith",
  "confidence": 0.85,
  "source_type": "consolidated",
  "consolidation_level": 0,
  "derived_from": ["<event-hash>"]
}

Each Belief carries source_type: "consolidated" and derived_from pointing back to the Event's content address. The consolidation level is 0 (raw) because these are directly extracted from a single event, not derived from frequency analysis across multiple events.

Multi-Modal Events with Content References

Events are not limited to text. The content_refs field (Section 7.1) allows an Event to reference external multi-modal content — audio recordings, images, video, or any other modality. The content itself is never embedded in the grain (Design Principle 1: "References, not blobs"), but the reference includes integrity verification.

For example, a field service event might reference a photo of damaged equipment:

{
  "type": "event",
  "content": "Inspected transformer T-4401. Visible corrosion on terminals A and B. Recommended immediate replacement.",
  "created_at": 1768471200000,
  "namespace": "field-service",
  "content_refs": [
    {
      "uri": "cas://sha256:e3b0c44298fc1c149afb...",
      "modality": "image",
      "mime_type": "image/jpeg",
      "size_bytes": 2048576,
      "checksum": "sha256:e3b0c44298fc1c149afb...",
      "metadata": {"width": 4032, "height": 3024}
    }
  ]
}

The content_refs entries use their own field compaction map (Section 7.1) with short keys: u for URI, m for modality, mt for MIME type, sz for size_bytes, ck for checksum, and md for metadata. These are compacted during serialization per Section 4.7 (nested compaction applies to content_refs).

When the has_content_refs flag (bit 3) is set in the header flags byte, consumers know before deserialization that external content is referenced. This supports the "index without deserialize" design principle.

Event vs. Belief: The Core Distinction

Understanding the boundary between Events and Beliefs is essential for correct use of OMS:

Events are intentionally lightweight. They require only a type, content string, and timestamp. Beliefs require a full semantic triple with confidence scoring. This asymmetry is deliberate: capturing raw data should have minimal friction, while creating structured knowledge requires more rigor.

Industry Use Cases

Customer Support Conversation Logs

Every customer interaction — chat, email, phone transcript — becomes an Event. The user_id field ties it to the customer for GDPR scoping. Consolidation extracts Beliefs about customer preferences, issues, and resolutions. The namespace field can partition by team ("support-tier1", "support-tier2") while the structural_tags field enables classification ("billing", "technical", "returns").

Therapy and Clinical Session Records

Clinical session notes can be captured as Events with appropriate sensitivity classification. The header flags (bits 6-7) support sensitivity levels: 00=public, 01=internal, 10=PII, 11=PHI. A therapy session record would use 11 (PHI) in the sensitivity bits. The content_refs field can link to audio recordings of sessions when consent is obtained.

Field Service Reports

Technicians in the field document inspections, repairs, and findings as Events. Multi-modal content_refs link to photos, videos, and sensor readings captured during the visit. Consolidation later extracts structured Beliefs about equipment status, failure patterns, and recommended actions.

Meeting Transcripts

Meeting recordings, once transcribed, become Events. The raw transcript preserves everything that was said. Consolidation extracts action items (which might become Goals), decisions (Beliefs), and process changes (Workflows). The content_refs field can reference the original audio or video recording.

Serialization Details

When an Event grain is serialized following the canonical algorithm (Section 4.9), the process is:

1. Validate required fields: type, content, created_at must all be present and non-empty.
2. Compact field names: type becomes t, created_at becomes ca, namespace becomes ns, importance becomes im, author_did becomes adid. The Event-specific fields content and consolidated remain unchanged (Section 6.2).
3. NFC-normalize all strings.
4. Omit null/None values — absent optional fields are simply not included.
5. Sort map keys lexicographically by UTF-8 bytes.
6. Encode as MessagePack.
7. Prepend the 9-byte fixed header.
8. Hash with SHA-256 to produce the content address.

For the test vector Event, the compacted and sorted keys in the payload would be: adid, ca, content, im, ns, t — six keys in lexicographic order.

Immutability and the Event Lifecycle

Like all OMS grains, Events are immutable. Once created, the binary blob never changes — its content address is its permanent identity. This has important implications for the Event lifecycle:

1. Capture: Event is created with consolidated absent (defaults to false).
2. Process: Consolidation extracts Beliefs, linking them via derived_from.
3. Mark: A new Event grain is created with consolidated: true and the same content, superseding the original. The original's superseded_by field (set by the index layer, per Section 15.3) points to the new grain.
4. Audit: The full chain is preserved — original Event, superseding Event with consolidated: true, and all derived Beliefs with provenance links.

This immutability model means you never lose data. The original transcript is always recoverable, the consolidation results always traceable, and the entire processing history always auditable.

Summary

Events are where agent memory begins. They are the raw, unstructured capture of what happened — conversation transcripts, interaction logs, session records, field reports. Their deliberately minimal schema (just type, content, and timestamp) makes them easy to create and hard to get wrong.

The real power of Events emerges through their relationship with Beliefs via the consolidation pipeline. Events hold the raw data; consolidation extracts the structured knowledge; provenance chains link everything together. This separation keeps the capture fast, the processing auditable, and the resulting knowledge trustworthy.

The next time your AI agent has a conversation, remember: that conversation is an Event. What the agent learns from it is a Belief. And the chain between them is what makes OMS memory verifiable.