Architecture

Knowledge is stored as typed, content-addressed blocks organized into five memory modules. Each module bundles its blocks, a Merkle DAG that pins the exact composition of a version, and the indices needed to query it.

Block          one typed, content-addressed record        → block_id
Composition    an immutable set of block identities       → merkle_root
Module         a composition + a store + its indices      → ModuleRef
Snapshot       one root per installed module              → OciDigest

Blocks

A block is a small immutable record with a payload wrapped in an envelope. The envelope is what block_id is computed over, and it has exactly five keys:

from boltzmann.blocks import ENVELOPE_KEYS

print(sorted(ENVELOPE_KEYS))
# ['boltzmann', 'memory_type', 'payload', 'schema_version', 'serialization']

block.payload()          # the payload as a JSON-shaped mapping
block.envelope()         # the full envelope block_id is computed over
block.canonical_bytes()  # the exact bytes that are hashed and stored
block.block_id           # the content-addressed identity

Blocks are never mutated. Every operation that looks like a change produces a new block, a new composition, or a new snapshot. See Memory types for the five schemas.

Content a block names but does not carry

A payload is JSON, canonically serialized and hashed on every access, so a datum large enough to matter does not belong inside one. A block may instead name its content by digest and leave the bytes in the store — which is what a canonical block has always done with the original it describes.

block.content_digests    # the content addresses this block names; () when self-contained

reference = brain.put_content(diagram, media_type="image/png")

brain.validate(CandidateSet(candidates=[Candidate(
    memory_type=MemoryType.SEMANTIC,
    evidence=[source],
    payload={
        "kind": "concept",
        "label": "Phase diagram",
        "statement": "The diagram shows the solid-liquid transition",
        "content": reference.model_dump(mode="json"),
    },
)]), task)

put_content stores the bytes and returns a ContentRef for a payload to name. It writes no block and publishes no snapshot: until a committed block names them, the bytes are unreachable and a prune reclaims them. The reference it returns is a fact, not a claim: size is measured from the bytes, and media_type must be a bare, lowercase type/subtype — no parameters, no trailing punctuation. Media types are parsed with the standard library’s RFC 2045 parser and then required to round-trip exactly, because image/png, IMAGE/PNG and image/png; charset=utf-8 are the same type to compare and three different strings to hash. Both fields are hashed into the resulting block_id and are what a consumer reads to decide whether to fetch content it does not hold, so a wrong value cannot be corrected later — only superseded by a different block. A payload assembled by a proposer rather than by put_content is checked in the validation gate instead, which also compares the declared size against the stored bytes when the brain holds them. Both checks sit on the write path and never on decode. NormalizedView extends ContentRef and takes its media type from a third-party normalization pipeline, so a malformed one may already be inside a published block_id; refusing it at decode would make this SDK unable to read a brain an older one wrote. Canonical has named its original since the beginning. Semantic, episodic and procedural blocks gained an optional content field in schema version 2, so an interpretation whose subject is an image, a recording, or any other file can state what it claims about that file without inlining it. The text stays required — statement, summary and goal are what a natural-language query can reach, and when the content is binary they are the interpretation.

A block is written under the oldest schema its payload satisfies. A payload naming no content is still built as v1, so adding a version does not re-version knowledge that does not use it. Since schema_version is inside the hashed envelope, that choice is a choice of block_id: a brain only becomes unreadable to an older client at the point where it genuinely uses something that client has no schema for.

Content is not evidence. Evidence is canonical — it lives in the canonical composition, other blocks cite it, and dropping it cascades to everything derived from it. Content is the block’s own datum, so nothing cites it and nothing needs to; it lives and dies with its block. A source other blocks will cite is a canonical block, through register.

Everything that must account for those bytes — packing a layer, marking reachability before a prune, destroying them on redaction — asks the block through content_digests rather than testing its type. So a schema that starts naming content is handled correctly by all of them at once, and an index is handed a reader for exactly this reason.

Publishing across SDK versions

An artifact declares which schema versions each of its modules holds, in the ai.gaussia.boltzmann.schema-versions manifest annotation. A pull checks it against the schemas the client implements, scoped to the modules being installed, and refuses before fetching any blob:

DistributionError: the semantic module holds blocks with schema version 2; this client
implements [1]. The artifact was published by a newer SDK -- upgrade boltzmann to one that
implements schema version 2 for semantic blocks, or install only the modules this client
has schemas for

The declaration is per module, so a client that lacks a schema for the semantic module can still install the episodic one. An artifact published before the annotation existed declares nothing, and absence is read as unknown rather than as permission: those fall through to the decode-time check instead.

Compositions

A Composition is an immutable set of block identities committed by a single Merkle root. Deriving one returns a new one:

from boltzmann import MemoryType
from boltzmann.module import Composition

version_1 = Composition(MemoryType.SEMANTIC, [a, b, c])
version_2 = version_1.drop([b])

version_1.root != version_2.root       # excluding a block publishes a different composition
version_1.verify()                     # and version_1 keeps verifying, unchanged

Because the root is computed over sorted leaves, it is a pure function of the set of blocks: two parties that assembled the same blocks in different orders obtain the same root.

diff = version_1.diff(version_2)
diff.added, diff.removed, diff.unchanged
diff.transfer_size                     # how many blocks a consumer must fetch

A root can be verified but not inverted, so the leaf list is stored alongside it as a composition document (composition.json). Without it a snapshot would identify a version it could not reopen.

Modules

A Module is one memory module at one version: a composition, the store its bytes live in, and its indices.

module = brain.module(MemoryType.SEMANTIC)

module.root                            # this version's identity
module.block_ids                       # canonical leaf order
module.get(block_id)                   # read, verifying membership in *this* version
list(module.blocks())                  # iterate every block of this version
module.resolvable()                    # which blocks can still be read
module.verify()                        # every membership proof, and every block's bytes

with_blocks and without_blocks derive new versions. Module exposes no write method at all — extending a brain goes through commit, which is the only write path.

Snapshots

A Snapshot is the state of a brain: one ModuleRef per installed module, plus the snapshots it succeeds, which form an auditable history.

snapshot = brain.snapshot()

snapshot.modules                       # {MemoryType: ModuleRef}
snapshot.parents                       # the snapshots this one succeeds
snapshot.first_parent                  # the history it was produced onto
snapshot.is_reconciliation             # True when it names more than one
snapshot.created_at
snapshot.boltzmann                     # protocol version

parents is a list because history is a DAG rather than a chain: a linear history carries one entry, a root snapshot none, and a snapshot that joined two histories two or more. Order matters in exactly one way — the first parent is the one every rule meaning the parent refers to. See Reconciliation. Each ModuleRef carries the module’s root, the composition digest, the block_count, the Merkle layout identifier, the identities whose bytes were deliberately destroyed in tombstones, and the embedding_model behind a travelling vector index when one ships with it. Tombstones remain composition members: they preserve membership while making the loss explicit and signed. Snapshots written before the field existed remain readable; newly written snapshots always emit the list, including when it is empty.

A brain may hold a subset of modules. Selective installation is the point of packaging each module separately, so “not installed” is a legitimate state — and therefore an error rather than an empty module when you ask for one you do not have.

The mutable state a brain has is which snapshot is current — and, while one is being resolved, a reconciliation in progress:

brain.state()               # the mutable pointer, for tooling that inspects a layout
brain.history()             # the retained snapshots, most recent first
brain.ancestry()            # the first-parent chain: how this brain got here
brain.reachable_history()   # every snapshot it contains, following all parents
brain.origin                # where this brain was pulled from, if it was

ancestry and reachable_history answer different questions. The first is the line an audit follows. The second is what a containment check asks — a history merged in is genuinely contained without appearing on the first-parent chain, which is why a push compares against that one.

The store

Blocks live in a BlockStore. Two ship with the SDK:

Store	Backing	Use
`OciLayoutStore`	An OCI Image Layout on disk	What `Brain.open` uses. Publishing is a copy, not a conversion
`MemoryBlockStore`	A dict	Tests, and ephemeral brains

A store must not normalize: bytes that are not canonical do not decode, and bytes that do not hash to the digest they are filed under are refused. A redacted block is tombstoned, never silently missing — a removed block must never look like a corrupted one.

Getting started

Core concepts

Guides

Blocks

Content a block names but does not carry

Publishing across SDK versions

Compositions

Modules

Snapshots

The store

​Blocks

​Content a block names but does not carry

​Publishing across SDK versions

​Compositions

​Modules

​Snapshots

​The store

Blocks

Content a block names but does not carry

Publishing across SDK versions

Compositions

Modules

Snapshots

The store