Skip to content

Context Pack Spec

Purpose

A context pack is the bounded runtime context assembled for one question, task, or turn.

It exists to give the runtime the smallest useful set of evidence, memory, decisions, and controls for the current request.

Current Implementations

  • brain/context_packs/schema_v2.py
  • brain/context_packs/contextos_contract.py
  • brain/context_packs/service.py
  • brain/context/compiler.py
  • related committed schemas under contracts/runtime/

Main Fields

In the current typed model (ContextPackV2), the important fields are:

  • intent
  • constraints
  • preferences
  • durable facts
  • relevant facts / evidence
  • prior decisions
  • open loops
  • episode state
  • suggested plan
  • allowed actions
  • success criteria
  • policy controls
  • routing hints

Provenance Rules

  • facts should preserve path/anchor or equivalent source references
  • memory-derived content should retain memory identifiers where available
  • decisions should retain decision identifiers and source paths where available
  • pruning should prefer dropping low-score items over dropping provenance

Ranking And Pruning

Current ranking/pruning is pragmatic:

  • score-first ordering
  • bounded evidence sets
  • budget enforcement that drops lower-scored items first

See ContextPackV2.enforce_budget() in brain/context_packs/schema_v2.py.

Token Budget Philosophy

The repo favors bounded context over dumping the whole corpus into one prompt.

Practical rules:

  • assemble targeted evidence
  • keep provenance visible
  • prune low-value items first
  • prefer durable decisions and salient evidence over raw bulk

Safety / Policy Handling

Context packs can carry:

  • allowed actions
  • policy controls
  • routing hints

They are not just retrieval bundles; they are part of the runtime governance story.

Compiler Diagnostics

ContextPackCompiler emits a governed CompilerOutputEnvelope with four operator-facing diagnostics:

  • manifests.policy_manifest, manifests.evidence_manifest, and manifests.tool_manifest
  • runtime_controls
  • budget_report
  • context_ledger

The tool manifest now keeps capability kind and risk separate. Each surfaced capability can include:

  • capability_class: observe, recall, think_support, verify, or act
  • risk_level: read_safe, read_sensitive, write_reversible, write_external, or write_irreversible
  • approval_mode: read_only, local_write, network, delegated, or destructive

The context_ledger is the replay-oriented summary of one compile. It records the pack, request, policy rules, tool capabilities, evidence IDs, memory block IDs, budget warnings, dropped block IDs, and a context_snapshot_hash.

This gives downstream replay and diagnostics one stable place to answer:

  • which facts and evidence were selected
  • which tools were exposed and why
  • which policies were active
  • whether context was dropped to fit a budget
  • which immutable context hash should be tied to later decisions

ContextOS Compatibility

SecondBrain keeps ContextPackV2 as the live local runtime shape, then projects it into a ContextOS-compatible ten-layer deployment artifact when a strict contract boundary is needed. The adapter is contextos_pack_from_runtime() in brain/context_packs/contextos_contract.py.

The projected artifact has the required ContextOS layers:

  • contract_meta
  • pack_meta
  • intelligence_refs
  • business_context
  • policy_layer
  • tooling_layer
  • decision_layer
  • memory_layer
  • evaluation_layer
  • tone_and_comms

The projection preserves compiler evidence IDs, tool permissions, approval modes, runtime controls, memory policy defaults, evaluator targets, and a content hash for immutable pack_id@version replay. The generated contract schema is committed as contracts/runtime/contextos-context-pack.v2.schema.json.

Update Lifecycle

Typical lifecycle:

  1. ingest or promote source material
  2. retrieve and rank relevant items
  3. assemble the pack for a specific task
  4. execute the turn or workflow
  5. write traces, decisions, and memory updates back to local state

Context packs are the bounded input assembled for a turn. Long-running agentic runs also persist AgentContextChannels on AgenticRunRecord: a structured journal, credibility-scored review, and consolidated timeline. Those channels are runtime continuity state, not replacement retrieval evidence; future background-session resume paths can use them without replaying raw message history.