The context compiler

compile_context is the primitive that decides what the model sees on every turn. It gathers from every tier, orders them by priority, and fits them into an explicit token budget — all with pure indexed reads and no LLM call, so it's cheap enough to run on the response path.

Why it matters

The prompt is the agent's entire view of the world for a turn. Stuff it blindly and you blow the context window and the latency budget; under-fill it and the agent forgets what matters. The compiler makes this a deliberate, inspectable decision: you set a budget and a strategy, and it tells you exactly what it included and what it dropped.

What it assembles

In priority order (highest first):

1. System prompt + pins + execution state (C) + hints (H) — the fixed head. Never dropped.
2. Recent turns (R) — working memory, the live conversation.
3. Live context (T6) — current state you injected (never stored).
4. Narrative (T5) · episodic (T3) · semantic (T4) — the retrieved memory tiers.

Under budget pressure it sheds lowest-priority first. The drop order is the events-vs-state principle in code:

T4  →  T3  →  T5  →  T6  →  R
(stale semantic memory drops first; live context survives longest; R never drops)

How it works

You call it with a query, a budget, and a strategy:

context = await session.compile_context(
    query="What did we decide about billing?",
    token_budget=12_000,
    strategy="recall",          # conversation | task | recall
    injected_context=[live],    # optional Tier 6 live state
)

strategy weights retrieval depth per tier — conversation is balanced, task favours session-scoped episodic recall, recall favours cross-session narrative for "what happened before." Set depths once on CompilerConfig, or pass retrieval_depths= for a one-off.

The result is fully inspectable — provenance and budget decisions, not just text:

context.messages          # ready to send to your model
context.recalled_facts    # T3 episodic provenance
context.recalled_sagas    # T5 narrative provenance
context.recalled_semantic # T4 graph provenance
context.injected          # T6 live context that survived
context.dropped           # e.g. ["T4"] — tiers shed to fit the budget

Because it depends only on the store and a tokenizer, the compiler also runs standalone — for pre-session warming, cross-session queries, or evaluation — not just inside a live session.

Tradeoffs & pitfalls

• compaction_triggered: true (or dropped: ["T1"]) means recent turns were trimmed for this prompt only — it is not durable compaction. Treat it as a cue to compact_async().
• The semantic tier (T4) is only retrieved when an embedder is wired; without one it's silently skipped.

Related

• How a turn flows — the compiler on the turn
• The five-tier model — what each tier holds
• Use live system-of-record state — feeding Tier 6
• Tune retrieval — strategies, depths, budget