| name | context-infrastructure |
| description | Design, audit, or improve durable context and memory systems for AI agents using layered observations, reflection, conservative promotion, progressive disclosure, and replayable boundary artifacts. Use when building long-running agent memory, deciding what belongs in sessions versus rules or skills, preventing context bloat, or turning repeated corrections and workflows into durable assets. Do not use it to copy another person's private axioms or automatically promote one-off observations. |
Context Infrastructure
Treat context as a compounding system, not a giant prompt. Route, filter, test,
and promote experience so future agents receive the smallest useful context.
This AX adaptation is inspired by the public
grapeot/context-infrastructure
reference implementation and the Observer/Reflector pattern described by
Mastra Observational Memory.
Reuse the architecture, not another person's accumulated axioms, preferences,
or private data.
Define four layers
| Layer | Purpose | Typical contents |
|---|
| L0 Session | Execute the current task | Prompt, active diff, command output, current plan |
| L1 Observations | Preserve selected raw signals | User corrections, repeated friction, notable failures, explicit preferences |
| L2 Reflection | Distill and discard | Deduplicated patterns, contradictions, counterexamples, promotion proposals |
| L3 Durable assets | Change future behavior | Axioms, reusable skills, global methodology, technical knowledge, project memory |
Do not skip layers. Keep a new signal in L1 until reflection shows that it is
repeated, stable, useful outside the original task, and routed to the right
scope.
Separate observation from promotion
Make the Observer append concise evidence. Make the Reflector merge, discard, or
propose promotion.
- Record only explicit corrections, preferences, retractions, and recurring
workflow lessons worth reconsidering. Most tasks should produce no memory.
- Preserve source, date, scope, and counterexamples needed to evaluate a signal.
- Merge duplicates and flag contradictions during reflection.
- Generate a reviewable promotion proposal before changing durable rules,
axioms, skills, or shared memory.
- Keep automatic promotion off by default unless the domain has deterministic
validation, rollback, and an explicitly authorized policy.
This split prevents one intense session from rewriting long-term behavior.
Route promotion by scope
| Repeated signal | Durable target |
|---|
| Stable personal preference | Personal axiom or preference profile |
| Repeated cross-project workflow | Reusable skill |
| Global operating methodology | Focused rule or policy |
| Reusable technical lesson | Knowledge entry |
| Project-specific decision or constraint | Project memory or source-of-truth documentation |
| One-off task fact | Keep ephemeral or discard |
Promote only claims that change future decisions. Preserve dissent and edge
conditions; a rule without boundaries is usually too broad.
Design for progressive disclosure
- Keep the global entrypoint as a routing table, not the whole memory system.
- Use indexes to tell agents when to load focused rules, skills, or knowledge.
- Put triggering information in skill metadata and detailed procedure in the
skill body or directly linked references.
- Retrieve project-specific context before global history when the task depends
on current source truth.
- Prefer sparse, high-density context over broad dumps and repeated summaries.
Do not add another agent when a fixed-contract parser, index, or API call can
route the context deterministically.
Make boundaries inspectable
For every context-producing workflow, define:
- Input boundary: source records, time window, permissions, and freshness.
- Selection boundary: inclusion, exclusion, deduplication, and privacy rules.
- Artifact boundary: an inspectable observation or reflection record before
AI judgment becomes durable.
- Promotion boundary: owner, threshold, review, target, and rollback.
- Consumption boundary: which task shape loads which durable asset.
Store AI-facing inputs and AI-produced intermediate outputs when they affect
visible or durable behavior. Debug bad output by inspecting freshness,
timestamps, filters, ordering, and fallbacks before changing the model or prompt.
Protect integrity
Test the parts that future agents rely on:
- parser and schema shape;
- time-window and freshness filtering;
- deduplication and contradiction handling;
- fallback and retry signals;
- privacy, secret, and retention scans;
- deterministic replay from saved boundary artifacts;
- promotion thresholds and rollback behavior.
Minimize collection. Do not inspect private stores, upload records, or broaden
retention without authorization. Redact secrets before an observation becomes a
shared or durable artifact.
Completion contract
Return a compact system design or audit containing:
- the L0–L3 stores and owners;
- Observer and Reflector contracts;
- the signal-to-target promotion table and review threshold;
- progressive-disclosure routing;
- privacy, freshness, replay, and rollback checks;
- remaining manual decisions.
Complete only when a new observation can be traced from source to consumption
without silent promotion or an uninspectable context jump.
