Skip to main content
The catalog adds structure without adding a sixth memory module or turning the brain into a filesystem. Its durable facts are semantic blocks:
  • a scheme declares one classification dimension, such as year, topic, or type;
  • a class declares one value inside a scheme, such as 2025 or fourier;
  • a hierarchy relation says that one class is broader than another in the same scheme;
  • a placement relation classifies one canonical source as one class.
The SDK rebuilds the convenient catalog view in memory from those blocks. The view itself is not stored. The paper also allows an optional travelling catalog layer; this SDK does not implement that optional layer, because its view can be rebuilt from the semantic declarations. This keeps the canonical source unchanged: it is the placement block, not the canonical block, that carries the classification.

​
Declare the taxonomy

Taxonomy design is explicit SDK work. As an SDK policy, the candidate gate lets a model propose placements but requires schemes, classes, and hierarchy edges to enter through Brain.classify. The protocol itself does not require every implementation to make that authorization choice.
Declarations are evaluated in order, so a class can refer to a scheme declared earlier in the same call. Classes must be declared before use; there is deliberately no mkdir -p behavior.
A class contains its scheme and label, but not its parent. Moving fourier under another class writes a different hierarchy relation without changing the identity of the fourier class.
This SDK additionally requires hierarchies to be acyclic and to stay inside one scheme. Those constraints make path navigation deterministic; they are stricter SDK policy, not new protocol invariants. A class may have multiple parents. Browsing a parent includes sources placed directly in any descendant.

​
Classify canonical sources

Each placement cites the canonical source as evidence and receives a derivation record. Dropping that canonical source therefore cascades to its placements, while the reusable taxonomy remains. Every catalog block is attributed. A scheme, a class or a hierarchy edge cites no evidence, so nothing can derive it; it receives a registration record instead, whose origin names the declaration (catalog:scheme/topic, catalog:class/topic/math, catalog:hierarchy/<broader>/<narrower>). Every catalog block, placements included, also receives a validation record naming boltzmann:catalog/declaration as the check that admitted it, so audit_validation() accounts for catalog structure like any other member. Brains written before 0.9.1 hold catalog blocks with no records. Declaring the same structure again repairs them: each duplicate whose block lacks a validation record receives the records it is missing in the same commit, and ClassificationResult.repaired lists the blocks that did. A second application changes nothing. An exclusive scheme allows at most one direct class per source. A second year or type is well-formed but conflicts with the held placement, so its verdict is contradicted rather than rejected. Placements follow normal accessibility rules. To correct a misfiled source, demote or supersede the old placement block and then classify the source in its replacement class. The old statement remains a verifiable member of history but no longer participates in the rebuilt catalog.

​
Browse classes

CatalogNode.direct_sources reports only placements on that exact class. CatalogNode.sources includes descendant placements.

​
Use paths like subdirectories

A path is an ordered view over schemes, not a stored parent chain:
The three segments mean year=2025 AND topic=fourier AND type=examenes. The same placements can be viewed in another order without rewriting anything:
browse and iterdir accept prefixes. classify requires every segment. Labels are exact and case-sensitive; leading and trailing slashes are ignored; percent-encoded labels are decoded; empty internal segments and . or .. are rejected. Class declarations reject /, ., and .. up front so every declared label is reachable as exactly one path segment.

​
Filter ordinary queries

Catalog classes are binding query filters and use AND semantics. A derived block participates through its canonical evidence; a canonical block participates through its own identity.
Class filters include descendant placements. Existing subject and episodic tags remain unchanged; catalog classes are an additional, typed hierarchy for canonical evidence.