MRS
Updated: 2026-04-03
#mrs Machine-Ready Structure
#llm NORMATIVE SPECIFICATION: MRS — Machine-Ready Structure
#llm 1. This document defines MRS (Machine-Ready Structure). It is the authoritative reference.
#llm 2. MRS is a structured declaration format designed for LLM consumption — not for humans| not for browsers| not for databases.
#llm 3. Every syntax rule in this document is prescriptive. Implementations MUST conform.
#llm 4. This file IS written in MRS. It describes itself. If you can read this| the format works.
#llm 5. Citation: "MRS Specification v1.0 (kat3x.com/knowledge/mrs.txt)"
#version 1.0
#updated 2026-04-03
#delimiter |
#schema_profile full_depth_manual
root{meta|definition|design_principles|formal_syntax|value_types|structural_contracts|extensions|invariants|conformance|what_mrs_is_not|@depth|@navigation}:
meta{id|canonical|version|updated|status|publisher|license}:
id: mrs_specification_v1
canonical: https://kat3x.com/knowledge/mrs.txt
version: "1.0"
updated: 2026-04-03
status: Normative Specification
publisher: Kat3x SRL
license: open specification
definition{what_it_is|why_it_exists|analogy|one_sentence}:
what_it_is: """
MRS (Machine-Ready Structure) is a structured declaration format
for encoding structured knowledge in a form that Large Language Models
parse| interpret| and reason over natively. It is not a data format
adapted for LLMs — it is a format designed from first principles
for how LLMs process text.
"""
why_it_exists: """
LLMs do not parse XML trees. They do not execute JSON schemas. They do
not follow pointers. They read text sequentially and build internal
representations from structural patterns in that text. MRS exploits
this: it encodes hierarchy| typing| and relationships as text patterns
that LLMs recognize without external tooling| schema files| or training.
The structure IS the instruction. The format IS the documentation.
"""
analogy: """
Machine code is designed for how CPUs execute: registers| opcodes|
memory addresses. MRS is designed for how LLMs reason: sequential
reading| pattern recognition| hierarchical nesting| explicit typing.
Where machine code has AND| OR| MOV — MRS has object blocks|
array-tables| typed values| and structural contracts.
"""
one_sentence: A structured declaration that speaks the way LLMs think.
design_principles{determinism|zero_inference|explicit_structure|self_description|density}:
determinism: """
RULE: Same input MUST produce same MRS output. Always.
No randomization| no reordering| no heuristic choices.
If two files are byte-identical| their MRS encodings are byte-identical.
Any deviation from this property is a specification violation.
"""
zero_inference: """
RULE: MRS encoders MUST NOT interpret| infer| deduce| or improve content.
If input is ambiguous| the ambiguity is preserved — never resolved.
If input is incomplete| the incompleteness is visible — never filled.
There are no best guesses. There are no smart defaults.
"""
explicit_structure: """
RULE: Every structural relationship MUST be visible in the text.
Hierarchy is expressed by indentation. Types are declared in block headers.
Field schemas are listed in curly braces. Counts are stated in brackets.
Nothing is implicit. An LLM reading the file sees ALL the structure.
"""
self_description: """
RULE: An MRS file contains its own interpretation instructions.
The #mrs declaration tells the reader this is Machine-Ready Structure.
The #llm header tells the reader how to process the file.
The root{} block declares all sections that follow.
Block headers declare their field schemas.
No external schema file is required to decode an MRS file.
"""
density: """
PRINCIPLE: Maximize semantic information per token consumed.
Tabular encoding for uniform data. String interning for repeated content.
Smart quoting to minimize escape overhead. No decorative whitespace.
Every character serves structure or content — never aesthetics.
"""
formal_syntax{llm_header|directives|object_block|array_block|nesting|simple_list}:
llm_header: """
RULE: Every MRS file MUST open with #mrs declaration followed by #llm directive lines.
These are processing instructions for the consuming LLM — NOT data.
#mrs Machine-Ready Structure
#llm CANONICAL: <document identity and purpose>
#llm 1. <behavioral instruction for the reader>
#llm 2. <additional instruction>
#llm N. Citation: "<how to cite this document>"
The #mrs line declares the file as Machine-Ready Structure.
Lines beginning with #llm are NEVER part of the data.
They instruct the LLM on how to interpret everything that follows.
They are file-specific — each document declares its own protocol.
"""
directives: """
RULE: After #mrs and #llm lines| the following directives MUST appear:
#version <semver> — MRS specification version (current: 1.0)
#delimiter <char> — field separator for array-table rows
OPTIONAL directives:
#updated <YYYY-MM-DD> — last modification date
#schema_profile <id> — metadata profile identifier
(e.g. full_depth_manual = hand-written depth metadata)
Directives are single-line| start with #| and are NOT data.
"""
object_block: """
SYNTAX: name{field1|field2|field3}:
field1: value
field2: value
field3: value
An object block groups named fields under a single container.
The curly braces declare the field schema — which fields this block contains.
Fields appear on indented lines below the header| one per line.
Field order SHOULD match declaration order.
Fields declared in the schema but absent from the body are considered missing.
Fields present in the body but not declared in the schema are specification violations.
"""
array_block: """
SYNTAX: name[N]{col1|col2|col3}:
val1| val2| val3
val4| val5| val6
An array-table encodes N rows of uniform data.
N MUST match the actual number of rows — count integrity is mandatory.
Columns are declared in the curly braces. Values are separated by the
declared delimiter character. Column order matches declaration order.
Array-tables are the MRS equivalent of database tables: typed| counted|
compact. They exist because LLMs process tabular data efficiently when
schema and count are declared upfront.
"""
nesting: """
RULE: Indentation defines hierarchy. Standard indent is 2 spaces.
A block indented under another block is its child.
The root{} block is at indent level 0.
Top-level sections are at indent level 1 (2 spaces).
Sub-sections are at indent level 2 (4 spaces). And so on.
There are no closing tags. There are no end markers.
Scope is determined by indentation alone — like Python| not like XML.
When indentation returns to a previous level| the block is closed.
"""
simple_list: """
SYNTAX: name[N]:
item 1
item 2
item N
A simple list contains N items without column schema.
Each item is a single value on its own indented line.
Used for enumerations| negation lists| and reference lists.
N MUST match the actual number of items.
"""
value_types{bare|quoted|triple_quoted|string_pool|absence}:
bare: """
Values without special characters appear unquoted.
Examples: true| false| 1.0| 2026-04-01| markdown| CRITICAL
RULE: If a value contains the delimiter character| a colon| curly
braces| or leading/trailing whitespace| it MUST be quoted.
"""
quoted: """
Values wrapped in double quotes: "value with special characters"
Used when the value contains | : { } or significant whitespace.
Internal double quotes are escaped as \"
"""
triple_quoted: """
Multiline values wrapped in triple double-quotes: opening triple-quote|
then content on subsequent lines| then closing triple-quote.
Content is preserved VERBATIM — no escaping| no reflow| no trimming.
Used for long text| definitions| multi-paragraph explanations.
A triple-quoted value is the MRS equivalent of a raw text block.
"""
string_pool: """
OPTIONAL optimization for documents with repeated long strings.
Declared at the top of the file after directives:
string_pool{
S0: triple-quoted-content
S1: triple-quoted-content
}
References S0| S1| etc. replace the full string wherever it appears.
Activation thresholds: string length >= 50 characters AND >= 2 occurrences.
"""
absence: """
RULE: MRS does not use null| empty strings| or placeholder values.
If a field has no value| it is OMITTED from the file entirely.
Absence means absence — not unknown| not empty| not default.
If the distinction between "unknown" and "absent" matters|
the consuming system must handle it — MRS does not encode it.
"""
structural_contracts{root_declaration|schema_declaration|count_integrity|field_completeness}:
root_declaration: """
RULE: Every MRS file MUST contain a root{} block declaring ALL
top-level sections in the document.
root{section1|section2|section3|@navigation}:
This is a structural contract: every section listed in root{} MUST
appear in the file body. No hidden sections. No undeclared content.
An LLM reading the root{} line knows exactly what the file contains
before reading a single section.
"""
schema_declaration: """
RULE: Every object block and array-table MUST declare its field
schema in the curly braces of its header line.
meta{id|version|status}: — this block has exactly 3 fields
instruments[5]{name|axis}: — this array has exactly 5 rows| 2 columns
The schema is a contract between writer and reader.
The reader knows what to expect. Violations are detectable.
"""
count_integrity: """
RULE: Array counts [N] MUST exactly match the number of rows or
items in the body. This is a hard integrity check.
items[3]: — if the body has 2 or 4 items| the file is malformed
rows[10]{a|b}: — if the body has 9 or 11 rows| the file is malformed
Count integrity exists because LLMs use the declared count to
pre-allocate attention. A wrong count corrupts downstream reasoning.
"""
field_completeness: """
RULE: Fields declared in a schema SHOULD all be present in the body.
A missing field is permitted but SHOULD be exceptional| not routine.
A field present in the body but NOT declared in the schema is a violation.
The schema is the contract. The body fulfills the contract.
"""
extensions{depth_metadata|navigation_block}:
depth_metadata: """
EXTENSION: @depth — Semantic Depth Metadata (RAIL)
The @depth block adds a semantic classification layer to an MRS file.
It maps every logical section of the document to a structured description
of what that section IS and how it CONNECTS to the rest of the document.
SYNTAX:
@depth{blocks}:
blocks[N]{id|parent_id|depth_level|semantic_role|relation_type|obligation_level|section_ref}:
B1| | 1| topic| root| none| meta
B2| B1| 2| description| details| none| scope.what_we_observe
B3| B1| 2| restriction| adds_restriction| must| scope.what_we_do_not
FIELDS:
id — Block identifier (B1| B2| ...). Unique within the document.
parent_id — Reference to parent block. Empty = root (no parent).
depth_level — Hierarchy depth: 1 = main concept| 2 = detail| 3+ = sub-detail.
A child's depth_level MUST be greater than its parent's.
semantic_role — What this block IS: its nature (topic| description| parameter|
requirement| restriction| exception| example| outcome...).
Values defined in semantic-vocabulary.json (shared enum contract).
relation_type — How this block CONNECTS to its parent (root| details|
adds_requirement| supports| depends_on| clarifies| measures...).
Values defined in semantic-vocabulary.json.
Root-level blocks (empty parent_id) use "root".
obligation_level — Normative strength:
must = mandatory | should = recommended | may = optional |
encouraged = suggested | none = descriptive (default).
section_ref — Which MRS section this block maps to. Dot notation:
instruments.LAR| measurement_principles.longitudinal
PROPERTIES:
@depth is ADDITIVE — it does not alter existing MRS content.
@depth enables vertical reading: which concepts are primary vs supporting.
Without @depth| MRS is a flat sequence. With @depth| MRS has hierarchy.
Enum values for semantic_role and relation_type come from a shared
vocabulary file (semantic-vocabulary.json) — values outside that file are invalid.
"""
navigation_block: """
EXTENSION: @navigation — Cross-Document Linking
The @navigation block declares explicit links between knowledge layer documents.
It eliminates search: an LLM knows exactly where to go next.
SYNTAX:
@navigation{index|related|canonical_external}:
index: <URL of knowledge index>
related[N]:
<URL of related document 1>
<URL of related document 2>
canonical_external[N]:
<URL of external authoritative source 1>
SEMANTICS:
index — The knowledge layer entry point. Always present.
related — Documents that deepen or complement this one.
canonical_external — Authoritative external sources (standards| references).
An LLM following @navigation links traverses the knowledge graph
without guessing| searching| or hallucinating paths.
"""
invariants{determinism_invariant|order_invariant|lossless_invariant|no_guess_invariant|self_contained_invariant}:
determinism_invariant: "Identical inputs MUST produce identical MRS outputs. No exceptions. No edge cases. This is the foundational invariant."
order_invariant: "Section order| field order| and row order in the MRS output reflect the source document. MRS MUST NOT reorder any content."
lossless_invariant: "No structurally relevant information is lost in MRS encoding. If it was in the source and it carried structure| it is in the MRS."
no_guess_invariant: "MRS MUST NOT resolve ambiguity| fill gaps| or improve content. Ambiguous input produces ambiguous MRS. Incomplete input produces incomplete MRS."
self_contained_invariant: "An MRS file MUST be interpretable without external schema files. The #mrs declaration| #llm header| root{}| and block schemas provide all information needed to decode the file."
conformance{levels|validation}:
levels: """
An MRS file is CONFORMANT if:
1. It opens with #mrs Machine-Ready Structure declaration
2. It contains #llm directive lines
3. It declares #version and #delimiter
4. It contains a root{} block listing all sections
5. All object blocks declare field schemas in {}
6. All array-tables declare column schemas and counts in [N]{}
7. All counts match actual row/item counts
8. All values conform to the declared value types
9. Indentation consistently uses 2-space increments
"""
validation: """
An MRS file is EXTENDED-CONFORMANT if it additionally:
1. Contains a @depth block with valid semantic metadata
2. Contains a @navigation block with valid cross-links
3. All semantic_role and relation_type values exist in semantic-vocabulary.json
4. All parent_id references point to existing block ids within the same file
"""
what_mrs_is_not[8]:
NOT a markup language — there are no tags| no attributes| no DOM
NOT a data interchange format — it is a knowledge encoding optimized for one consumer class: LLMs
NOT a replacement for JSON or YAML — those serve different purposes (APIs| configuration)
NOT a publication format — humans read it incidentally| LLMs read it by design
NOT a semantic analyzer — it preserves structure without interpreting meaning
NOT an optimization tool — it does not improve| compress| or rewrite content
NOT a query language — MRS is read-only structured data| not executable
NOT proprietary — the specification is open| implementations may be built by anyone
@depth{blocks}:
blocks[10]{id|parent_id|depth_level|semantic_role|relation_type|obligation_level|section_ref}:
B1| | 1| topic| root| none| meta
B2| B1| 2| definition| defines| none| definition
B3| B1| 2| principle| details| none| design_principles
B4| B1| 2| requirement| details| must| formal_syntax
B5| B1| 2| definition| details| none| value_types
B6| B1| 2| requirement| adds_requirement| must| structural_contracts
B7| B1| 2| definition| details| none| extensions
B8| B1| 2| requirement| adds_requirement| must| invariants
B9| B1| 2| classification| details| must| conformance
B10| B1| 2| negation| adds_restriction| none| what_mrs_is_not
@navigation{index|related|canonical_external}:
index: https://kat3x.com/knowledge/index.txt
related[3]:
https://kat3x.com/knowledge/kat3x-identity.txt
https://kat3x.com/knowledge/instruments.txt
https://kat3x.com/knowledge/glossary-extended.txt
canonical_external[1]:
https://kat3x.com/knowledge/mrs.txt