ContextOS — Context Compilation Research Companion

The public research surface for context compilation: the idea that between what an AI system can retrieve and what it actually reasons with sits a compiler-like layer that most architectures never made explicit.

This repository publishes the object model, the lowering stage, the JSON schema, and the benchmark specification from the ContextOS paper series. The full compiler pipeline (retrieval, ranking, policy gating, compression) runs in a private reference implementation and is described, not shipped, here.

Memory determines what a system can know. Retrieval identifies candidate evidence. Context compilation determines what the system actually thinks with.

Read the full argument: Toward a Theory of Context Compilation for Human-AI Systems · paper PDF (Zenodo) · DOI 10.5281/zenodo.19490059

Python 3.10+. No third-party dependencies (jsonschema optional, for validation tests).

import sys; sys.path.insert(0, "src")
from context_ir import ContextIR, Fact, ProvenancePointer, SensitivityLabel, SensitivityClass, RuntimeTarget
import lowering

ir = ContextIR(task="pre-meeting brief", intent="brief before 1:1")
ir.add(Fact(
    claim="Budget approved for phase 2",
    evidence="Q3 planning note",
    provenance=[ProvenancePointer(source_path="docs/examples/planning-note.md")],
    sensitivity=SensitivityLabel(classification=SensitivityClass.INTERNAL),
    token_estimate=25,
))

# Policy is applied in IR space, before lowering:
ceiling = SensitivityClass.INTERNAL
banned = {id(o) for o in ir.policy_violations(ceiling)}
filtered = ContextIR(task=ir.task, intent=ir.intent)
for obj in ir.objects:
    if id(obj) not in banned:
        filtered.add(obj)

pack = lowering.lower(filtered, target=RuntimeTarget.CHAT)
print(pack["formatted_text"])

Run the tests:

python3 tests/test_public_surface.py

lower() renders the IR it is given — it does not silently filter. Policy ceilings are enforced by filtering the IR itself (ContextIR.policy_violations) so that exclusions are explicit, inspectable, and recordable as OmissionMarkers. Governance decisions belong in compile space, not render space. The tests encode this contract.

• Stable: IR object model, JSON schema, lowering targets, enforcement contract.
• Specification: CompileBench task families and metric surface; public seed dataset pending a stable grading surface.
• Private reference system: compiler passes above (retrieval, ranking, gating, compression) and their evaluation runs. Numbers in the papers come from that system.

The earlier records 19484541 / 19472618 are software records archiving snapshots of the predecessor project (MemoryOS), including the paper drafts as delivered then. This repository supersedes those snapshots for the published research surface; see CITATION.cff.

Apache-2.0. See LICENSE and NOTICE.