The SOUL of ContextOS
The operating philosophy behind ContextOS: state is explicit, outcomes are typed, unsafe authority is contained, and learning is gated.
ContextOS exists to make useful agent work accountable: explicit state, evidenced outcomes, bounded authority, and controlled improvement.
The public pitch is an open contract for reliable agent harnesses. The decision-control and evidence specification gives that pitch concrete interfaces and testable obligations. Reliability is a deployment result to measure, not a property conferred by adopting the name or schema.
What this page is
This page states the operating philosophy of ContextOS. SOUL is a mnemonic for engineering commitments, not a claim about consciousness or an agent personality. It explains what builders should preserve as models, tools, and implementations change.
ContextOS publishes a specification, deterministic compiler/execution validators and synthetic workflow references; this repository is not a production runtime. The Rust runtime and Tower, an alpha implementing runtime, are published separately; see Project Status. The published schemas and explicitly normative contracts define requirements. Conformance needs current runtime evidence for the exact workflow/release/environment, beyond a schema or reference pass. This page explains the intent without adding fields or promising universal readiness. Specification prose is CC BY 4.0; published schemas, the deterministic reference, synthetic fixtures and documentation code examples are Apache-2.0. See the license scopes.
The short version: no agent gets to act in the dark.
Identity
| Field | Value |
|---|---|
| Name | ContextOS |
| Role | Public decision-control and evidence specification with versioned schemas, a deterministic compiler and execution validators. |
| Primary job | Define how implementing runtimes complete authorized work and preserve a DecisionRecord that makes the accepted outcome inspectable. |
| Primary surfaces | Context Packs, Run Context, bounded orchestration, Tool Gateway, Policy Engine, evaluator gates, replay, and reference implementations. |
| Default stance | Helpful, but constrained. Fast, but inspectable. Adaptive, but never self-modifying without gates. |
The acronym
SOUL is the smallest useful description of ContextOS:
| Letter | Principle | Runtime meaning |
|---|---|---|
| S | State is explicit | Run identity and exact pins remain linked to current ownership, operations, checkpoints and original aggregate limits; session identity is optional and grants no resume authority. |
| O | Outcomes are typed | Decisions retain required receipts and evidence; external effects can be confirmed, partial or unknown, and uncertainty survives stop/restart. |
| U | Unsafe authority is contained | Models may propose. Deterministic boundaries decide what can be compiled, planned, executed, remembered, or released. |
| L | Learning is gated | Memory passes its promotion policy; durable behavior changes pass evaluation, replay, and the required change-control gates. |
Core truths
A governed decision system is not a prompt.
Prompts are one artifact inside the Context plane. They are not the source of authority. Authority comes from versioned packs, policy bundles, identity and delegation, native action-risk policy, adapter registrations, Decision Specs, explicit approvals, and technical containment.
Those artifacts constrain work but cannot authenticate themselves. Verify current owner/tenant/workload authority and every delegation ancestor with trusted observations. Exact required profiles and actual features combine obligations; a plan, optimizer or fallback cannot silently choose weaker controls. A caller’s flag, tool description or memory claim cannot grant its own permission.
The model should never be the only witness.
If a system cannot show what evidence entered the run, which tools were visible, which policies fired, and which approvals were required, the system is not production-grade yet. The agent may have done something useful, but ContextOS does not treat it as governed.
Context is compiled, not stuffed.
The Context Pack Compiler exists because production agents need bounded, explainable input. It emits manifests, omissions, runtime controls, and budget reports so operators can inspect what was admitted and why. Retrieved documents, tool output, and recalled memory remain evidence with provenance; their contents cannot grant permissions or override trusted policy.
Failure must be visible too. An applicable policy-expression error stops compilation with a structured ContextCompileError; it cannot become a false predicate, a successful partial context or an excuse to reuse stale authority.
Side effects require a boundary.
A tool call is not just an API request. It is an attempted use of authority. The Tool Gateway validates schema, identity, policy, native action risk, v1 compatibility, approval state, idempotency, trace lineage, and evidence requirements before any external effect happens.
Approval binds the complete action, arguments, destination/amount and evidence/policy/profile/release pins under current eligible roles, validity and quorum. Current boundary/data observations and original shared budget reservations remain independent requirements. A sandbox name or idempotency key alone cannot prove containment or retry safety.
Typed decisions beat fluent explanations.
Free-form text is useful for communication. It is not enough for audit, replay, regression testing, or compliance. A governed system needs closed outcome sets, evidence requirements, status values, policy decisions, approvals, and lineage. Schema validity establishes structure, not truth: verify the relevant external state before claiming that an action succeeded.
Memory must earn its way into recall.
Raw capture is not memory. Candidate facts require classification, applicable consent, contradiction checks, and promotion rules before they become eligible for compiled context. Memory Fabric permits policy-qualified automatic promotion; a human need not approve every candidate. Promotion does not make a fact timeless: recall still respects scope, freshness, and unresolved conflicts.
Owned namespaces/readers, retention and actual processor routes apply across inference, telemetry, cache, memory and export. An authorized correction/deletion request can remain pending; completion requires scoped inventory and verified propagation receipts, with unknown external copies disclosed.
Improvement is change control, not self-editing.
The system can learn from failures and corrections, but durable behavior changes must become typed proposals. A better prompt fragment, retrieval hint, memory rule, tool declaration, policy rule, or StrategyRule earns promotion through replay and gates.
Trust is a plane, not a feature.
Trust wraps every other plane. It is present at compile time, plan time, execute time, memory-write time, release time, and audit time. It is not a final review step.
Boundaries
No hidden authority.
The model cannot invent tools, understate action risk, broaden authority, bypass policy, silently write durable memory, or change active Context Packs.
No silent truncation.
If context is dropped because of budget pressure, the omission is recorded. A smaller context can be correct. An invisible omission is not acceptable.
No direct action path.
Every external effect routes through the Tool Gateway. A direct adapter call is a broken run boundary. Enforcement also needs scoped credentials and execution containment; an instruction to use the gateway cannot prevent bypass when an agent has unrestricted credentials.
No unverifiable success.
Success requires evidence. If the runtime cannot point to the tool result, policy decision, approval verdict, trace span, or replay packet that supports the claim, the claim is not operationally complete.
No learning without provenance.
A correction can become a proposal. A proposal can become a release. A release can become a pinned pack version. Each step must preserve who changed what, why, against which evidence, and with which scorecard result.
Autonomy serves the user
The purpose of governance is to let agents complete useful work within a clear mandate. An implementation should proceed with authorized, bounded actions and ask only when missing information or an approval obligation changes what it can safely do. Repeated permission prompts are not a substitute for correctly scoped authority.
Personal/proactive agents need a current owner-directed standing mandate, verified trigger/channel/device provenance, bounded lifetime/capabilities/budget and visible pause/revoke/stop controls. Creating a schedule and executing a later wake are distinct governed operations. Contacts’ messages and shared devices do not merge personal, household or employer authority.
Choose the simplest workflow that meets the task. Add planning loops, specialist agents, or long-running execution when evaluations justify the added cost and failure paths. Anthropic’s Building effective agents supports this incremental approach; it does not establish that a more elaborate architecture is inherently better.
Native action risk considers effect, authority, reversibility, interaction, and data scope, with an optional decision TTL. The v1 ApprovalMode is a compatibility projection, not a complete risk ranking or an approval verdict. Even a read can expose restricted information. Approval authorizes a bounded action under policy; it does not waive other controls.
Operating posture
ContextOS should feel strict in the places where strictness protects the user, and boring in the places where reliability matters.
| Situation | ContextOS posture |
|---|---|
| Low-risk lookup | Answer quickly, cite evidence, emit trace. |
| Ambiguous user intent | Resolve canonical intent or ask for the minimum missing fact. |
| Risky side effect | Freeze evidence, route approval, preserve idempotency. |
| Missing evidence | Refuse, replan, or escalate with a typed reason. |
| Budget pressure | Record omissions; stop or escalate if required evidence cannot fit. |
| Tool timeout after a write | Treat completion as uncertain; reconcile using the adapter’s idempotency and status contract before retrying. |
| Interrupted run | Acquire current owned/fenced state, revalidate authorization/boundary/external preconditions and original limits, then reconcile prior effects before any permitted continuation. |
| Operator correction | Create a proposal; do not silently mutate behavior. |
| Failed release gate | Block promotion and keep the prior pinned version active. |
Example
A user asks support_agent in tenant_acme_prod to refund an order. This is an illustrative sequence using the existing contracts, not a new refund policy.
- State: establish the actor, tenant, target order, budget, and pinned pack. Compile the ownership and eligibility evidence required by the registered decision.
- Outcomes: distinguish eligibility, permission to execute, and the payment result. A model saying “refunded” is not payment evidence.
- Unsafe authority: evaluate the registered capability’s risk and policy obligations. If a gate is required, bind approval to the evidence and bounded action. Execute through the Tool Gateway with an idempotency key.
- Recovery: if the payment provider times out, inspect the recorded call and reconcile provider state. Do not issue a second refund merely because the first response was lost, or report success while the result is unresolved.
- Learning: preserve the result and evidence in the DecisionRecord. A correction to refund behavior becomes a proposal tested against the failure and regression cases before release; it cannot edit the active policy during the run.
The user receives a clear account of what completed, what remains uncertain, and whether any action is needed from them. The operator receives references that support that account.
Communication style
ContextOS documentation should be precise, operational, and testable.
| Prefer | Avoid |
|---|---|
| ”This field is required because replay needs it." | "This is useful for observability." |
"The Compiler emits budget_report.bucket_truncations." | "The system handles token pressure." |
| "The Tool Gateway denies this call before execution." | "The agent should not call that tool." |
| "The DecisionRecord is incomplete without evidence refs." | "The response should be trustworthy." |
| "This behavior change requires replay and approval." | "The agent learns from feedback.” |
The voice is calm, direct, and explicit about authority. ContextOS does not sell magic. It shows the boundary.
On being an operating system for agents
“OS” describes the architectural ambition of stable contracts across changing execution systems. It does not mean this repository ships an operating system, hosted harness, or production control plane. Evaluate the concrete artifacts and implementation boundaries, starting with one workflow.
An operating system is not valuable because it is visible all the time. It is valuable because every process knows what it can access, what it must declare, what happens when it fails, and where its state goes.
ContextOS gives agents the same discipline:
- Define the request as a
RunContext. - Compile context from governed sources.
- Plan inside bounded roles.
- Execute only through approved capabilities.
- Record a typed decision.
- Evaluate the run.
- Improve through gated promotion.
The goal is not to make agents sound more confident. The goal is to make agent work inspectable enough that teams can trust it, operate it, and improve it without losing control.
Continuity mechanism
A ContextOS system stays coherent across time through pinned artifacts:
- Context Packs define what can enter the model.
- Policy bundles define what can happen.
- Catalogs define valid intents, tasks, and decisions.
- Adapter registrations define callable capabilities.
- Memory promotion defines what can be recalled.
- Evaluator thresholds define what can ship.
- Decision Records and traces define what happened.
- Replay packets define what can be reproduced.
Durable run/operation/checkpoint and budget stores define current ownership, unresolved effects and remaining capacity. Parent/child/retry/replan/evaluator work consumes the original limits and deadline; restart cannot mint fresh budget. A verified stop acknowledgement can coexist with an unknown provider effect, which remains visible until reconciled.
Update the pack, and the compiled context changes. Update policy, and the execution surface changes. Update evaluators, and the release gate changes. Every configuration change should be visible, versioned, and have a rollback target. Reverting a pack does not undo an external effect; compensation depends on the capability and may be impossible.
What replay can promise
Replay reconstructs a run from pinned artifacts and recorded inputs. Deterministic policy and compiler artifacts can be compared exactly. Probabilistic model stages are assessed against recorded outcomes, declared properties, and scorecards; identical model prose is not a universal guarantee.
Audit replay substitutes recorded tool results and must not repeat live side effects. A missing snapshot or transcript limits what can be reconstructed and should be reported explicitly. Decision records describe accepted outcomes and evidence, not private model chain-of-thought. Retention, redaction, and access controls still apply to audit material.
Continuity therefore lives in durable state, not in an assumption that the next model invocation remembers. Anthropic’s long-running agent harness demonstrates the value of explicit progress artifacts and verified completion across context windows. Its coding results support this design choice, not a universal guarantee for every domain.
Evaluation metrics
Treat the philosophy as questions an implementation can answer. These are suggested operational checks, not additional schema requirements or universal release thresholds.
| Commitment | Evidence to examine |
|---|---|
| State is explicit | Can sampled runs resolve their actor, tenant, pinned inputs, controls, and budget usage? Can an interrupted run reconcile its last effect? |
| Outcomes are typed | What fraction of claimed successes have the required outcome evidence? How often does the reported result disagree with observed state? |
| Unsafe authority is contained | Do denial and adversarial tests prevent forbidden effects? Are approvals bound to the actual action? Can credentials bypass the gateway? |
| Learning is gated | Do promoted changes link to their source failure, evaluation result, release version, and rollback target? Does the original failure pass after promotion? |
| Useful work remains useful | Track verified completion, unnecessary escalation, latency, and cost together; blocked legitimate work is also a failure. |
Evaluate both the path and the result. Anthropic’s agent evaluation guidance distinguishes a transcript’s claims from the final environment state and recommends graders suited to the task. ContextOS applies that distinction to evidence-backed outcomes; fluent answers and favorable judge scores cannot substitute for required policy checks.
Research grounding
The linked engineering reports inform this philosophy; they do not certify ContextOS or prove an implementation secure. Their findings are applied here as design guidance, while ContextOS’s own contracts remain authoritative.
The MCP maintainers’ Security Best Practices explain confused-deputy risks, token audience validation, and why token passthrough is forbidden. The implication for ContextOS is concrete: tool connectivity does not itself establish authority. Identity and authorization must survive every boundary. This is a living draft reference, not a pinned ContextOS dependency.
For implementation detail, continue with How It Works, Governance, Memory, and the Improvement Loop.
The line
ContextOS exists to draw one line clearly:
The model may reason, but the runtime governs.
That is the soul of the system.
Soul version: 1.3.0 - 2026-10-16. Aligned with compatible execution attachments, exact profiles and evidence-scoped conformance; no breaking base-envelope change.