7.0 KiB
name, description, depth, links
| name | description | depth | links | |||
|---|---|---|---|---|---|---|
| Core Context Submodule Spec | Specification for :core:context – context synthesis and compression | 2 |
|
:core:context module specification
version: 0.1-draft status: foundational specification
1. purpose
:core:context is responsible for synthesizing minimal, relevant, token‑efficient context packs that are fed to models before each inference call.
It owns:
- context layer architecture (L0–L4)
- compression strategies
- token budgeting
- relevance ranking
- deduplication
- context pack building
- context event ownership
Context synthesis is the primary defense against context window overflow and degradation of model performance due to irrelevant history.
2. responsibilities
:core:context owns:
- context layer definitions
- compression strategy contracts
- token budget model
- relevance ranking algorithms
- deduplication logic
- context pack structure
- rebuild triggers
- context synthesis events
- router context management (separate L2 for router)
- session‑level context cap enforcement
3. non-responsibilities
:core:context MUST NOT own:
- long‑term memory persistence (that’s infrastructure)
- model execution
- tool execution
- approval decisions
- transition logic
- archiving policy (archival layer L4 is defined, but storage mechanics are external)
4. architectural role
:core:context acts as:
- the information bottleneck
- a stateless synthesizer that transforms raw event history into a compressed, actionable model prompt
- the owner of what the model “sees”
5. design principles
5.1 context is synthesized, not accumulated
Raw events are never fed to models. They are filtered, ranked, compressed, and bounded.
5.2 layers separate freshness from history
- L0 – live execution stream (current stage inputs/outputs)
- L1 – stage‑local context (artifacts from the current stage)
- L2 – compressed session memory (summaries of completed stages)
- L3 – durable project memory (key decisions, architecture, persistent facts)
- L4 – archival history (full event log, used only for deep replay)
Only L0–L2 are included in the context pack for a typical inference.
5.3 token budgets are enforced
Every context pack has a hard token limit. The budget is configurable per model and per stage. The context processor must trim aggressively.
5.4 router context is separate
The router has its own L2 memory, rebuilt from summaries after each stage. It never sees raw execution context unless needed for a specific user query.
6. context pack model
data class ContextPack(
val layers: Map<ContextLayer, List<ContextEntry>>,
val budgetUsed: Int,
val budgetLimit: Int,
val compressionMetadata: CompressionMetadata
)
Context entries are structured records pointing to artifact excerpts, summaries, policy hints, and steering notes.
7. synthesis pipeline
Pipeline steps (executed in order):
- Retrieve relevant events from projection store (cursor‑based).
- Deduplicate – remove repeated identical tool outputs, duplicate artifact versions.
- Rank – score entries by relevance to current stage goals (may use a quick heuristic or a tiny model).
- Compress – apply layer‑specific strategies (summarize tool logs, keep only latest valid artifact, semantic conversation compression).
- Inject policies – insert active constraints relevant to the stage.
- Tokenize and trim to budget.
- Assemble final
ContextPack.
8. compression strategies
Config‑driven, per data type:
| data type | default strategy |
|---|---|
| tool output | summarize (extract errors, key values) |
| artifacts | latest valid only |
| events | deduplicate + temporal decay |
| conversation | semantic summary (L2 only) |
| approvals | retain all (small) |
| steering notes | retain verbatim |
Semantic compression may use a dedicated small local model, but it must be deterministic‑enough (same model, same prompt → same compressed output). The harness treats compression as an inference call of its own, recorded as a CompressionEvent.
9. token budget model
Budgets are defined per model and per stage, with enforcement:
- hard limit on total context pack tokens
- reservation for system prompt/policies
- dynamic overflow: if compression cannot fit within limit, oldest L2 entries are dropped first.
10. session‑level token cap
A session‑wide total token cap exists for L2 memory. When exceeded, older L2 entries are merged into L3 project memory, and L2 is truncated. This prevents silent memory bloat in long sessions.
11. event ownership
:core:context emits:
ContextBuildingStartedContextPackBuiltCompressionAppliedLayerTruncated
These events carry causation from the preceding stage schedule event.
12. consumed events
Consumes:
StageScheduled(trigger)- All domain events that feed the projection needed for context retrieval.
13. replay semantics
During replay, context compressions are either replayed from compression events (if available) or re‑executed deterministically. For inference‑skipping replay, context packs are still built to validate budget logic but not fed to models.
14. threading/concurrency
Context building is a CPU‑bound operation that runs within the orchestration coroutine. It must be cancellable and should not block the event loop for extreme histories (use batching/sampling if needed).
15. failure semantics
If context building fails (e.g., compression model unavailable), the stage cannot proceed. Event ContextBuildingFailed is emitted, and the transition engine may retry or fail the session.
16. observability requirements
- token usage per stage
- compression effectiveness (e.g., compression ratio)
- L2 memory size over time
- context building duration
- deduplication hit rate
17. security boundaries
Context packs may contain sensitive data. The module must support redaction/secret scrubbing before delivery to models (plugin point). No model should see raw secrets.
18. extension model
Extensions may provide:
- custom rankers
- custom compressors
- additional context layers (if needed)
All extensions must produce valid ContextEntry types and respect the token budget.
19. forbidden patterns
- raw event accumulation in context pack
- unbounded context growth
- mutable context state (context packs are ephemeral, built per stage)
- cross‑session context leaking
- hidden injection of unauthorized data
20. testing requirements
- determinism of deduction/ranking (given fixed input)
- token budget compliance
- compression quality metrics
- replay of context building
- router context isolation
21. philosophy
The context processor is the harness’s memory manager. It ensures that models never drown in their own history, and that every inference receives a sharp, purposeful slice of the past—nothing more, nothing less.