Record context assembly

Context assembly evidence answers three questions about a model step: which sources were considered and included, whether the context overflowed or was compacted, and whether a provider cache reused input tokens. It travels as span events on the model-call span, keeping the model step itself a model step.

What is recorded

• An ordered source list containing kind, stable ID, optional version, digest, and owner, sensitivity, token count, position, visibility, and an optional reason code.
• The input budget, reserved output budget, assembled token count, overflow outcome, and an assembly SHA-256 digest.
• Compaction trigger and strategy, before and after counts and digests, summarizer identity, retained overlap, and IDs removed.
• Cache provider, outcome, optional cache and config digests, and optional measured savings.

Source IDs form the lineage. Use a document ID, memory item key, tool call ID, or other stable identifier—not text. A source with kind = memory must use its memory_item_key, which lets Anectico connect the model input back to memory provenance.

What is never recorded

These events do not accept prompt text, retrieved document bodies, memory content, generated summaries, or tool-result bytes. They are metadata-only even when the project's content policy would permit content. Prompt and completion and tool content remain separate, opt-in capture paths.

Record from an SDK

Start an agent run, make a model-category span current, and call the run handle's assembly, compaction, or cache method inside that span. The SDK refuses a call when no recording model span is active and validates the whole event before recording any part of it.

• Go: run.RecordContextAssembly(modelCtx, value), RecordContextCompaction, and RecordContextCache. Go takes modelCtx explicitly because its OpenTelemetry API has no ambient current-span accessor.
• JavaScript: run.recordContextAssembly(value), recordContextCompaction, and recordContextCache inside context.with(modelContext, ...).
• Python: run.record_context_assembly(value), record_context_compaction, and record_context_cache inside the current model span's context manager.

See the Go SDK, JavaScript SDK, and Python SDK for examples and Agent span and event attributes for every bound.

The OpenAI and Anthropic auto-instrumentation wrappers record cache evidence without an explicit cache call when their response includes the provider cache field. Reused tokens greater than zero produce hit; a reported zero produces miss; absence produces no cache event. Providers do not report the ordered source list or compaction decision, so those two events remain explicit.

Ask your agent

"For run <run-id>, which sources went into each model step, was the context compacted, and did the provider cache help?"

Job	MCP tool or action	CLI command
Read the context events of one run	list_context_events (read action)	anectico agent-runs context <run-id>
Read the whole run graph, with a context summary on every model step	get_agent_run_graph (read action)	anectico agent-runs graph <run-id>
Follow a memory source to where it flowed	get_memory_item_propagation (read action)	anectico memory-items propagation <memory-item-key>

The key needs mcp:read and agents:read. Read actions are reached through list_read_actions and execute_read_action.

What your agent gets back

All read surfaces return the same metadata-only fields; none resolves a digest or source ID into content.

• REST: GET /api/v1/agent-runs/{runId}/graph includes context on every model step. Use GET /api/v1/agent-events?run_id={runId}&category=context for the individual assembly, compaction, and cache rows. Add context_source_id={stable-id} to keep assembly events whose ordered source list contains that lineage ID.
• MCP: get_agent_run_graph includes the same step summary. The gatewayed list_context_events read takes run_id and optional context_source_id; it requires mcp:read plus agents:read and returns bounded identifiers, hashes, counts, and outcomes only.
• CLI: anectico agent-runs context <run-id> -o json prints the model-step summaries and all three context event kinds. Use -o table for a deterministic path and value view. context keeps only context-bearing steps; anectico agent-runs graph <run-id> prints the complete execution graph.

context.instrumented is the instrumentation answer. It is true only when at least one valid context event was accepted for that model step. A model step from an older producer, or one whose only context event was rejected, returns a summary with instrumented: false; its empty counters do not mean a measured zero. Conversely, instrumented: true with assembled_tokens: 0 is a real measured zero. Never infer instrumentation from a number or from provenance.normalizer_version.

Anectico preserves that step and event presence bit, but not a separate presence bit for each optional numeric member inside an accepted event. Consequently an accepted event can return numeric zero for a member the producer omitted. Treat those member-level zeroes as part of the stored projection; only instrumented distinguishes an uninstrumented step from an instrumented one.

Open the proof

The result of get_agent_run_graph carries a link to the run's proof page. The page is read-only. It opens the run in the project named in the link, so you can check the run itself next to the context evidence your agent reports. The context events have no proof page of their own: read them with the tools above. The result of list_context_events carries no link.

How to verify

Set the API base URL and a project-scoped API key with agents:read. Replace the project and run placeholders with the IDs you are investigating:

export ANECTICO_API_URL="https://app.anectico.com"
export ANECTICO_API_KEY="an_..."
export ANECTICO_PROJECT="<project-id>"
export RUN_ID="<run-id>"

Choose a run whose model span recorded assembly, compaction, and cache events. The following three reads must name the same model span and the same three accepted events:

curl -sS -H "X-Anectico-API-Key: $ANECTICO_API_KEY" \
  "$ANECTICO_API_URL/api/v1/agent-events?project_id=$ANECTICO_PROJECT&run_id=$RUN_ID&category=context"

curl -sS -H "X-Anectico-API-Key: $ANECTICO_API_KEY" \
  "$ANECTICO_API_URL/api/v1/agent-runs/$RUN_ID/graph?project_id=$ANECTICO_PROJECT"

anectico agent-runs context "$RUN_ID" --project "$ANECTICO_PROJECT" -o json

For MCP, call the read gateway twice: execute_read_action with action list_context_events and arguments {"run_id":"<run-id>"}, then with action get_agent_run_graph and the same run ID. The MCP credential needs mcp:read and agents:read.

Verify exact values rather than presence alone:

• assembly.sources has the expected IDs, positions, token counts, visibilities, and reason codes; assembly_sha256 is the lowercase SHA-256 of each source ordered by position as position<TAB>id<TAB>visibility<NEWLINE>.
• A truncated assembly has overflow: "truncated", at least one source with visibility: "truncated", and a bounded reason such as budget. Its assembled count is below budget_tokens - reserved_output_tokens.
• A compaction's ratio equals after_tokens / before_tokens; the producer should omit the ratio because Anectico derives it. Its removed source IDs and before and after hashes must match the producer's decision.
• A cache hit's reused_tokens equals the model step's model.usage.cache_read_tokens; a reported miss is a separate outcome and may carry a measured zero.
• steps[].context.instrumented is true, and its assembled-token, overflow, compaction-count, and cache-outcome summary agrees with the event rows. The CLI JSON is the REST graph projected onto those context fields, without renaming or recomputing them.

To verify one lineage link, add context_source_id=<stable-id> to the REST event request or to the MCP list_context_events arguments. For a memory source, use the exact 64-character memory_item_key, then read:

export MEMORY_ITEM_KEY="<64-character-memory-item-key>"
curl -sS -H "X-Anectico-API-Key: $ANECTICO_API_KEY" \
  "$ANECTICO_API_URL/api/v1/memory-items/$MEMORY_ITEM_KEY/propagation?project_id=$ANECTICO_PROJECT"

The context source ID must equal memory_item_key, and the propagation point at the model run's instant must carry the trust label then in force. Source IDs containing whitespace or more than 128 bytes are refused as a whole event; they never appear as partially accepted lineage.