Giving several agents the same transcript does not establish a shared understanding of the current task state.
A user initially asks for a blue theme, then changes it to green. A UI agent writes a style guide. A frontend agent reports completion, but its build fails. The next agent needs to know which requirement applies, which design artifact to read, which files changed, and which acceptance checks remain unresolved.
This is the context problem I have been working on in AgentMeld, a local group-chat workspace for AI teams powered by Pi. It supports discussion, peer consultation, and task coordination when needed. For delegated execution, I want to supply a task-specific package with sources, status, and connections to execution evidence, instead of asking each receiver to reconstruct the group conversation.
This note follows the Task Context Compiler, fact records, output bindings, and verification pipeline. Implementation details refer to the pinned source snapshot linked below. The Todo scenario and example package illustrate the design; they are not measurements from a particular run.
Preserve current state alongside summaries
Shortening history and clarifying current state are different jobs.
A summary reduces repetitive discussion, but does not inherently express that green superseded blue. Nor does it establish that a successful build followed a claim of repair. Retelling an artifact can lose its identity and version. Reducing a failure to “there was a problem earlier” removes a useful starting point for diagnosis.
I therefore separate selection from compression: establish which materials apply to this attempt, then choose whether to carry content, structured state, or a reference. A summary remains useful as one possible source.
Give each task attempt its own context package
Compilation begins with the task and execution identity. taskId identifies the work, attemptId distinguishes attempts, and contextSnapshotId identifies the compiled context. Plan revision and assignee also belong to that identity.
This distinguishes a previous failure of the same task from a similar problem elsewhere. Evidence, artifact reads, and verification results need an attempt-level association rather than a connection inferred only from message order.
| Material | Question it should answer |
|---|---|
| Task and acceptance contract | What must this attempt deliver and report? |
| Active facts | Which requirements and constraints still apply? |
| Upstream inputs and output bindings | Which producer output resolves to which artifact? |
| Workspace snapshot and target paths | Where are the files relevant to this work? |
| Previous failure and tool evidence | What happened, and why did it not pass? |
| Messages, summaries, retrieved history | Which communication background helps? |
Candidates carry fields such as sourceType, sourceId, trustLevel, task associations, path references, and token estimates. These turn “why give this material to this agent?” into a question about inspectable records.
Compilation produces more than a string. TaskContextEnvelope carries identity, requirements, upstream inputs, included materials, failure context, budget, and a manifest. A renderer subsequently turns the envelope into model input.
task + active facts + upstream bindings + prior attempt
-> collect candidates
-> qualify -> classify -> rank
-> preserve metadata / externalize references
-> pack within budget
-> envelope + manifest -> rendered promptCheck eligibility before relevance
A highly relevant message may no longer be valid. An artifact mentioned in an agent's completion claim does not become a trusted input merely because its title matches.
Qualification considers conversation and dependency scope, fact lifecycle, and upstream trust state. These checks depend on correct scope and metadata supplied by their callers; they do not automatically resolve every natural-language conflict.
Lifecycle and source trust are separate axes
The Fact Registry preserves canonical keys, sources, and supersession links. Once a new value passes the relevant checks, it can replace an old active record, marking the previous record superseded.
active describes lifecycle. Labels such as authoritative, verified, and reported describe source trust. A currently active record may still be an extracted claim. Inserting it into a fact table does not establish human confirmation or tool verification.
Green replacing blue depends on correctly recognizing and recording the update. Historical messages may remain available, but retrieval similarity should not grant them authority over the currently confirmed constraint.
Scores express priority rather than correctness
Eligible candidates enter deterministic ranking. Some additive rules in the ranker are:
| Condition | Added score |
|---|---|
| Explicitly required material | +1000 |
| Current task | +900 |
| Input from a direct dependency | +800 |
| Failure context | +780 |
| Target-path match | +650 |
Scores accumulate and remain subject to tier rules. Failure context also belongs to the mandatory tier, so its treatment cannot be reduced to a 130-point advantage over path matches. These numbers are neither probabilities nor confidence judgments from another model call.
Budget packing must preserve the task contract
Materials fall into mandatory, high-priority, optional, and forbidden categories. The objective, explicitly required materials, and retry failure context take priority. Facts, upstream inputs, and workspace information compete for the remaining allocation under the policy.
The current packer includes mandatory items first, allocates 60% of the remaining budget to the high-priority group, then lets optional materials use subsequent room. This is an explainable grouped allocation, rather than a globally optimal selection algorithm.
If mandatory material alone exceeds the budget, compilation returns a blocked envelope and execution reports task_context_overflow. It does not silently remove requirements and call the model anyway. Budgeting must also reserve space for system instructions, tool schemas, output, and protocol overhead.
Module names can obscure implementation limits. context-compressor largely preserves structured content or lightweight metadata; it does not generally invoke a model to generate new semantic summaries. Token counts are also estimates, and task budgeting still uses a fixed default window rather than an exact model-specific input calculation.
At this stage, the practical mechanism is selection, tiering, references, and on-demand reading.
A reference is the start of a reading path
An upstream style guide need not be repeated in full on every invocation. The package can carry its actual artifact ID, version, producer task, and output key. The executor then uses read_artifact when it needs the body.
An output key identifies what a task promised to deliver; an artifact ID locates a real artifact. Neither a task name nor a key such as style_guide should be guessed into an existing artifact ID.
Several distinct states lie along this path:
source exists
-> candidate qualified
-> item packed
-> text or reference rendered
-> model receives input
-> artifact body read through a toolThe manifest's included flag records a packing decision. Artifact-read records in Context Trace provide a separate observation. Neither proves that the model understood or used the content.
This distinction also matters for historical retrieval. FTS5 hits can enter retrieved_history candidates and packing results, but the inspected renderer has no dedicated body section for that category. Retrieval hits or inclusion counts alone therefore do not establish that those passages reached the model. Rendering and delivery need inspection along the actual execution path.
Deliver acceptance requirements to both sides
Evidence-driven context should not tell an agent only to implement a page, then reject its result against requirements it never received.
buildRequirements carries target paths, expected outputs, required commands, evidence descriptions, and acceptance criteria into the envelope. The renderer emits the evidence contract. Automatically checked contract items and acceptance items requiring a report must also align with the evaluator's treatment.
Renderer regression tests specifically check that these fields appear in the prompt. They exercise the data path rather than merely checking that fields exist in storage.
After execution, the model submits claims through report_task_result. The runtime verifies them against persisted evidence. Different records support different conclusions:
| Material | What it supports | What it does not establish |
|---|---|---|
| An agent says “done” | A completion claim exists | Every requirement is satisfied |
| A command exits with code 0 | That invocation exited successfully | All functionality is correct |
| File or artifact creation evidence | Content was created or changed | Business requirements are satisfied |
| Browser acceptance results | Specified pages and interactions passed | Unchecked paths are correct |
Verification constructs output bindings from artifact evidence and checks type, content, and contract requirements. A binding connects a producer's output key to a real artifact so downstream tasks can resolve their inputs. A casually written ID in a report should not create that connection.
Retries and handoffs preserve task state
Retry context should preserve the previous attempt, failed commands and error excerpts, evidence references, unmet criteria, and changed files. Those records give a retry a concrete starting point.
For the Todo scenario, the receiver's materials might be summarized as follows. This is a reading illustration rather than a serialized envelope:
Goal: add category filtering and fix the previous build failure.
Active constraints: green theme; preserve existing task data.
Inputs: currently bound PRD and style-guide artifact references.
Failure: previous build command, error excerpt, and evidence ID.
Acceptance: build passes; filters work; existing data stays usable.
Next: read the relevant artifacts and files, then check current state.Previously passed checks are useful history, but related evidence may need renewal after files change. A past pass does not establish that the current version still passes.
The same approach informs task handoffs. Their packages preserve the executed task contract, evidence references, upstream artifact versions, active-fact fingerprints, and relevant file fingerprints. Human acceptance triggers freshness checks, while the runtime coordinates source teardown and a new receiving attempt.
Peer consultation has different semantics: it provides advice while responsibility stays with the source agent. A handoff transfers responsibility for unfinished work, and the receiver must still report results and pass verification. Taking over one task does not automatically resume every downstream task in a failed plan.
Context Trace makes failure more specific
When a result diverges from expectations, I want to answer inspectable questions first: did the material enter this snapshot, was it omitted for budget, was the upstream reference valid, was its body read, and which verification failed?
Context Trace combines snapshots, manifests, upstream inputs, tool evidence, verdicts, and output bindings at the attempt level. Warnings such as unread_verified_input and output_binding_missing help turn “the agent ignored the design” into specific diagnostic paths.
A trace can display only what the system collects and persists. The current manifest primarily comes from packing. It should not be assumed to capture every qualification rejection, ranking reason, and final model input in full. Observability needs its own complete data path, beyond a panel of attractive counts.
Pi and the platform manage different scopes
Pi handles model interaction, the tool loop, and history within an execution. AgentMeld handles team identities, task contracts, cross-task materials, and workspace collaboration. The Task Context Compiler primarily serves delegated task launches and new attempts; ordinary discussion does not require creating a DAG first.
Context is not recompiled for every generated token. The platform tracks supplements during execution. When an invocation must be replaced, it coordinates cleanup before organizing a new attempt around the updated requirements. A changed requirement and an old invocation still running are explicit states to reconcile.
Establishing whether the design helps
The repository includes strategy configurations for recent messages, summaries plus recent messages, evidence-aware context, and evidence-aware context with role contracts. It also has compiler, renderer, verifier, and handoff tests. These can check mechanism wiring; they do not establish which strategy performs better.
A meaningful comparison needs controlled models, tasks, tools, budgets, and acceptance checks, with repeated trials. I would examine completion rates, obsolete constraints adopted, upstream artifact reads, unsupported claims, retries, token use, and duration, rather than only the reduction in package size.
Current limits belong in that evaluation: FTS5 is full-text retrieval, supersession depends on correct updates, token estimation and rendering coverage need further work, and evidence supports only what was actually checked.
The outcome I want is an execution that can clearly identify its present task, still-valid requirements, supporting materials, and the state it should carry into the next attempt when work fails.
Implementation references: