Skip to content
Press / to search

Implementation

Concrete contracts — Context Pack schema, Decision Record, Decision Catalog, Memory Fabric, and the canonical execution envelopes.

Living DocumentLast reviewed: Edit on GitHub
At a glance

The Foundations describe the spec narrative. The Implementation section is where the concrete contracts live: schemas, envelopes, lifecycle, and worked examples. These are the source of truth.

Start here

DocOwner-planeWhat it specifies
API ContractsDecision + ActioninvokeAgent, ToolCallEnvelope, ToolResultEnvelope, W3C trace propagation
Context PackContextContext Pack schema, layers, lifecycle, caching
Decision RecordDecision + Trustreplayable audit receipt with evidence, approvals, controls, lineage, and trace
Decision CatalogDecisionDecisionSpec, allowed outcomes, required evidence, decision binding
Intent-Task CatalogDecisionintent taxonomy, task templates, risk classification
Memory FabricIntelligenceconcrete memory storage, review queue, consolidation
Workflow ExamplesAllthree neutral end-to-end runs through the canonical contract
High-Risk WorkflowAllmulti-approver, irreversible, cross-tenant case

Implementation flow

A workable adoption path:

  1. Model — define ontology and identity-layer CEIDs for the entity types your workflow touches. (Ontology, Identity Layer)
  2. Declare — author a Context Pack with intelligence_refs, policy_layer, tooling_layer, decision_layer, memory_layer. (Context Pack)
  3. Compile — feed an invokeAgent envelope and a RunContext into the ContextPackCompiler to produce a CompiledContext.
  4. Invoke — run the bounded Planner / Executor / Critic loop; route every side effect through the Tool Gateway.
  5. Record — emit a typed DecisionRecord with evidence_refs, approvals, controls_active.
  6. Evaluate — score on the evaluators, replay against the pinned snapshot, feed the continuous improvement loop.

Authoritative artifacts

The schemas linked from each doc are the authoritative contracts. Prose snippets in foundations docs are blueprints. The TypeScript reference under src/lib/contextos/ mirrors the same schemas in code form for compile-time checking.

See it running

For a working open-source implementation of every primitive on this page — Context Pack compiler, Tool Gateway, ApprovalMode tiers, DecisionRecord receipts, autotune-driven improvement loop, promotion-aware memory, reviewer profiles — see SecondBrain (Reference Implementation). It runs locally with make quickstart-docker and exposes a Memory API plus MCP tools that other agents plug into.

Common pitfalls

  • Hand-assembled prompts. Bypassing the Compiler loses budget control, manifests, and runtime controls; use the pipeline.
  • Untyped decisions. Returning free-form text instead of a DecisionRecord makes the run unreplayable and uncomparable.
  • Direct adapter calls. Bypassing the Tool Gateway loses approval-mode binding, identity propagation, and trace propagation.
  • Ad-hoc gate names. Use the approval-mode tier taxonomy; gate names are runtime artifacts that bind to a tier, not a substitute for the tier.
  • Memory writes without promotion. All writes flow through the promotion pipeline; direct durable writes are not allowed.