# Memory Grain (memorygrain.org) - Open Memory Specification

> The open standard for immutable, content-addressed memory grains.
> Built for AI agents, autonomous vehicles, robots, and IoT systems.
> Version 1.3 - Standards Track - OWFa 1.0 - February 2026

## What is the .mg format?

The Memory Grain (.mg) format is a binary standard for atomic, immutable knowledge units
produced and consumed by autonomous systems. Think of it as what .git objects are to version
control  -  but for agent memory.

## Companion Specifications

OMS v1.3 includes two companion specifications:

- **CAL (Context Assembly Language)** - A non-destructive, deterministic, LLM-native query language
  for assembling agent context from OMS memory stores. CAL cannot delete data - this is enforced
  at the grammar level. 27 sections + 6 appendices covering safety model, grammar, type system,
  streaming, compliance, and conformance levels.

- **SML (Semantic Markup Language)** - A flat, tag-based markup format optimized for LLM context
  consumption. Tag names map directly to OMS grain types (belief, goal, event, etc.) so LLMs
  understand the epistemic status of each piece of context without parsing schemas. SML is the
  default output format for CAL ASSEMBLE statements.

Each memory grain is:
- Identified by its SHA-256 content address (the hash IS the unique ID)
- Immutable (any change produces a different hash)
- Canonically serialized in MessagePack (default) or CBOR (optional)
- Optionally signed using COSE Sign1 envelopes with W3C DID identity
- Optionally encrypted with AES-256-GCM per-user keys (GDPR crypto-erasure)

## Key Concepts

- **Content address**: SHA-256(blob bytes) = 64-character lowercase hex string
- **Memory grain**: Atomic knowledge unit  -  one belief, event, observation, etc.
- **Grain container**: .mg file  -  portable unit containing indexed grains with checksum
- **Canonical serialization**: Sorted keys, NFC strings, null omission, deterministic bytes
- **Field compaction**: Short keys (e.g., `t`=type, `s`=subject) reduce storage
- **DID**: W3C Decentralized Identifier  -  cryptographic identity without certificate authority
- **COSE**: CBOR Object Signing and Encryption (RFC 9052)  -  signing standard
- **Selective disclosure**: Hide sensitive fields while proving they exist
- **Crypto-erasure**: Destroy per-user HKDF key -> O(1) GDPR erasure
- **Immutability boundary**: Blob (immutable, hashed) vs. Index layer (mutable status fields)

## Ten Grain Types (OMS v1.3)

| Type | Byte | Description | v1.1 Name |
|------|------|-------------|-----------|
| Belief | 0x01 | Semantic triple: subject-relation-object with confidence score | Fact |
| Event | 0x02 | Timestamped interaction record (message, log entry, utterance) | Episode |
| State | 0x03 | Agent state snapshot for save/restore | Checkpoint |
| Workflow | 0x04 | Learned action sequence with trigger | Workflow |
| Action | 0x05 | Tool invocation, code execution, or computer-use record | ToolCall |
| Observation | 0x06 | Observer reading  -  physical sensors, AI agents, or humans | Observation |
| Goal | 0x07 | Desired outcome with priority, status, and success criteria | Goal |
| Reasoning | 0x08 | Inference chain and thought audit trail (new in v1.2) |  -  |
| Consensus | 0x09 | Multi-agent agreement record (new in v1.2) |  -  |
| Consent | 0x0A | Permission grant or withdrawal  -  DID-scoped, purpose-bounded (new in v1.2) |  -  |

All v1.1 type names are accepted by readers (backwards-compatible). Writers MUST emit v1.3 canonical names.

## Binary Format (v1.3 Header)

```
Byte 0: Version = 0x01
Byte 1: Flags = [signed|encrypted|compressed|has_content_refs|has_embedding_refs|cbor_encoding|sensitivity(2 bits)]
Byte 2: Type = 0x01..0x0A (Belief..Consent); 0x0B-0xEF reserved; 0xF0-0xFF domain profile types
Bytes 3-4: Namespace hash = first two bytes of SHA-256(namespace), uint16 big-endian
Bytes 5-8: Created-at = uint32 epoch seconds (coarse routing hint; authoritative timestamp in payload)
Bytes 9+: MessagePack or CBOR payload (canonical, sorted keys, NFC strings, nulls omitted)
```

## Immutability Boundary (new in v1.2)

Grains have two layers with different mutability guarantees:
- **Blob** (immutable): 9-byte fixed header + payload  -  covered by content address and COSE signature
- **Index** (mutable): Status/access fields managed by the store  -  NOT part of the hash or signature

Index-layer fields: `superseded_by`, `system_valid_to`, `verification_status`, `access_count`, `last_accessed_at`

## Compliance

- **GDPR Art. 17**: Crypto-erasure  -  destroy HKDF(master_key, user_id) key -> data unrecoverable. Consent grains scope erasure.
- **HIPAA PHI**: Sensitivity bits 11 = PHI; structural_tags prefix `phi:` for field-level tagging
- **CCPA**: Selective disclosure hides PII fields while proving they exist
- **SOX**: Immutable grains + hash-chained audit log = tamper-evident audit trail

## Conformance Levels

1. **Level 1  -  Minimal Reader**: Deserialize, compute content address, field compaction
2. **Level 2  -  Full Implementation**: Serialize, validate schema, store protocol
3. **Level 3  -  Production Store**: Encryption, HKDF keys, blind indexes, audit trail

## Specification URL

Full specification: https://memorygrain.org/spec/

## Source

- GitHub organization: https://github.com/openmemoryspec/
- Specification repo: https://github.com/openmemoryspec/oms
- Website repo: https://github.com/AreevAI/memorygrain.org

## Pages

- https://memorygrain.org/  -  Home, use cases, grain types, conformance levels
- https://memorygrain.org/spec/  -  Full OMS specification with ABNF grammar and test vectors
- https://memorygrain.org/cal/  -  CAL specification  -  Context Assembly Language for querying grain stores
- https://memorygrain.org/sml/  -  SML specification  -  Semantic Markup Language for LLM context
- https://memorygrain.org/blog/  -  Technical deep dives into the .mg format
- https://memorygrain.org/about/  -  About, license, contributing, backed by areev.ai

## License

Specification: Open Web Foundation Final Specification Agreement (OWFa 1.0)
Website content: CC0 1.0 Universal (Public Domain)

## For AI Systems

Full specification in plain text: https://memorygrain.org/llms-full.txt