Skip to content

opencontext.md

Latest commit

 

History

History
409 lines (309 loc) · 15.6 KB

opencontext.md

File metadata and controls

409 lines (309 loc) · 15.6 KB
Raw

OpenContext

LogicSRC OpenContext is an open specification for durable, portable, permissioned, provenance-aware context shared between humans and AI agents. It defines how organizational knowledge is described, authorized, versioned, resolved, audited, and handed between replaceable workers without losing institutional state.

An agent should be replaceable without losing organizational knowledge.

It is a standard, not a product. The normative contracts are JSON Schemas published under https://logicsrc.com/schemas/opencontext/. @logicsrc/opencontext is a reference implementation of those schemas — useful, but not the definition. Any language, storage engine, or model provider that satisfies the schemas and passes the conformance suite conforms.

  • Vendor-neutral — no LLM, framework, or database is required to validate, resolve, or explain anything.
  • Local-first — a folder and a Git repository are enough. No account, no server, no telemetry.
  • Not a memory database — memory is one possible context source. OpenContext is the control plane above your sources of truth.

Status: 1.0 Draft (OpenPRD 0003).

The problem

Organizational context is scattered across prompts, employee memory, agent histories, vector stores, wikis, chats, issue trackers, CRMs, spreadsheets, and SOPs. When an agent is replaced — a new model, a new vendor, a new framework — whatever it had learned goes with it. When an employee leaves, the same thing happens more slowly.

The result is familiar: agents that confidently quote last year's pricing, two teams operating from two different refund policies, and nobody able to say which one is authoritative or where either came from.

OpenContext makes the shared context plane explicit. It tells a runtime what context exists, where truth comes from, which information is authoritative, who may access it, how current it is, and which subset applies to a particular agent or task.

Five nouns

Everything in OpenContext is one of five things.

Noun What it is Example
Manifest The control plane: what exists, who may read it opencontext.yaml
Context object One durable unit of context with a stable id policies.refunds
Role The authorized subset available to a consumer support
Bundle Resolved, authorized context for one consumer and one task ocb_37c04d80…
Decision What was decided, why, and on what context decisions.2026-08-09-model-provider

Quick start

Five minutes, no account, no network, no model key.

npx @logicsrc/opencontext init my-context
cd my-context

opencontext validate --strict
opencontext doctor
opencontext resolve --role support --task "customer asked for a refund" --explain

init writes a project that passes strict validation and scores 100% with no edits:

Created opencontext.yaml
Created context/mission.md
Created context/organization.md
Created context/glossary.md
Created context/policies/refunds.md
Created context/sops/refund.md
Created context/decisions/2026-08-09-adopt-opencontext.md
OpenContext Health
────────────────────────────────
Why ACME Corporation e… ✓ canonical
How ACME Corporation i… ✓ canonical
Terminology             ✓ canonical

Orphaned context        0
Conflicting context     0
Expired context         0
Stale context           0
Missing owners          0
Broken sources          0

Context health: 100%

And resolve --explain shows the reasoning, not just the result:

Included:
  ✓ mission                                 canonical
  ✓ glossary                                canonical
  ✓ organization                            canonical
  ✓ policies.refunds                        canonical
  ✓ procedures.refund                       approved

Excluded:
  - decisions.2026-08-09-adopt-opencontext  not-in-scope   (no include pattern matches)

Warnings:
  none

Digest: sha256:81b41a915ee68f744e91ef0d7760440de51b603088de1a6f21ea6f337bb374a8

Run the same command as --role engineering and you get a different bundle from the same repository. That is the whole idea.

The six layers

Layers describe the kind of knowledge, never its authority.

Layer Name Purpose
L0 Mission Why the organization or project exists
L1 Identity Brand, values, organization, terminology
L2 Knowledge Products, customers, architecture, facts
L3 Policy Rules, permissions, compliance, constraints
L4 Procedure SOPs, workflows, playbooks
L5 Operational Tasks, incidents, conversations, temporary state

Authority

Authority is declared by the owner of the context, never inferred from retrieval rank, recency, or what the content says about itself.

canonical    the organization's own source of truth
approved     reviewed and sanctioned
reference    useful, not binding
observed     seen in the wild, unverified
inferred     derived by a model or heuristic
historical   retained for the record only

Canonical outranks historical by default, and the order may be reordered — but a repository cannot invent a level that outranks canonical, and observed or inferred context never becomes canonical automatically.

Repository layout

opencontext.yaml
context/
├── mission.md
├── organization.md
├── glossary.md
├── brand.md
├── customers/
├── products/
├── policies/
├── sops/
├── decisions/
├── knowledge/
├── operations/
└── roles/

Alternative layouts work. Nothing depends on these directory names — the manifest maps names to paths, so pointing OpenContext at an existing docs/ folder is a supported starting point.

The manifest

opencontext: "1.0"
id: acme
name: ACME Corporation

context:
  mission: ./context/mission.md
  glossary: ./context/glossary.md

collections:
  policies: ./context/policies/**
  procedures: ./context/sops/**
  decisions: ./context/decisions/**

roles:
  support:
    include:
      - mission
      - policies.*
      - procedures.*
    exclude:
      - policies.internal.*
    permissions:
      - customer.read
      - ticket.write
    max_classification: internal

agents:
  support-agent:
    roles: [support]

freshness:
  default_ttl: 30d

provenance:
  required: true

Full reference: manifest.

A context object

Only id and type are required. Everything else exists so context can be governed rather than merely stored.

---
id: policies.refunds
type: policy
layer: L3
title: Refund policy
authority: canonical
owner: support
status: approved
version: 1
durability: long-lived
classification: internal
canonical_source: true
updated: 2026-08-09T00:00:00Z
tags: [refunds]
---

Refund requests are accepted within 30 days of purchase.

Full reference: context object.

Resolution

resolve(consumer, task, requestedContext, timestamp) -> ContextBundle

The pipeline runs in a fixed order:

discover -> load -> normalize -> authorize -> apply scope
  -> validate freshness -> resolve supersession -> resolve authority/conflicts
  -> rank task relevance -> redact -> compile -> bundle

Two properties matter most.

Authorization precedes relevance. An object the consumer may not read is removed before freshness, ranking, or compilation ever sees it — so unauthorized context cannot reach a ranker, a prompt, or even an explanation.

Resolution is deterministic. The same inputs and source state produce the same bundle and the same digest, because every ordering is total and the only wall-clock value in the output is excluded from the digest. That is what lets a decision record cite exactly the context that produced it.

Details: resolution and authority.

Context bundles

The portable output of resolution. JSON is canonical; YAML and Markdown are for humans and prompt assembly.

{
  "opencontext": "1.0",
  "bundle_id": "ocb_37c04d801d013b07",
  "generated_at": "2026-08-09T15:00:00Z",
  "consumer": { "type": "agent", "id": "support-agent", "roles": ["support"] },
  "task": "Handle refund request for ACME",
  "objects": [],
  "warnings": [],
  "provenance": [],
  "digest": "sha256:…"
}

Context health

opencontext doctor is a core feature, because context rot is quiet: nothing fails, agents just start answering from last year's pricing.

opencontext doctor --strict

It reports schema errors, stale and expired context, canonical conflicts, missing owners, broken references, inaccessible sources, supersession errors, invalid permissions, duplicate ids, and provenance violations — and computes a documented, configurable health score CI can fail on.

CLI

opencontext init        # create a project that validates immediately
opencontext validate    # schemas, references, supersession, permissions
opencontext doctor      # context health and score
opencontext get <id>    # one object, subject to authorization
opencontext list        # what exists
opencontext search "…"  # lexical search, still authorized
opencontext resolve     # authorized context for a consumer and task
opencontext bundle      # the portable bundle document
opencontext history <id>
opencontext diff <from> <to>
opencontext conflicts
opencontext stale
opencontext graph
opencontext schema
opencontext version

Also available as logicsrc context <command> — the same implementation, so the two cannot drift. Full reference: CLI.

TypeScript SDK

import { OpenContext } from "@logicsrc/opencontext";

const oc = await OpenContext.load("./opencontext.yaml");

const result = await oc.resolve({
  agent: "support-agent",
  task: "Handle ACME refund"
});

console.log(result.bundle);

The resolver core is importable without the CLI. Full reference: SDK.

Security and the trust boundary

Context frequently originates in systems that carry attacker-controlled text — tickets, chats, scraped pages. OpenContext treats that as a first-class concern.

trust: trusted     # authored inside the trust boundary
trust: verified    # external, integrity-checked
trust: untrusted   # arrived from a system that can carry hostile text

Trust is preserved through resolution, remote content defaults to untrusted, Markdown bundles fence and label it, and an object's authority is never elevated because its content claims to be authoritative. Full guide: security and trust.

Conformance

A v1 conforming implementation parses valid manifests, enforces scopes with deny-overrides-allow, calculates lifecycle state, processes supersession, applies authority precedence, preserves provenance, emits canonical JSON bundles with deterministic digests, reports canonical conflicts, and passes the published fixture suite.

The fixtures live in @logicsrc/schemas under fixtures/opencontext/ and need no LogicSRC code to run: every valid/ fixture must validate, every invalid/ fixture must fail, and the resolution/ scenarios pin resolver behaviour that schemas cannot express. Full guide: conformance.

Examples

Five working examples, all held to --strict and a 100% health score in CI:

Example Shows
minimal The floor: mission, one policy, one role
startup Every layer, L0 through L5, with decisions
support-agent Redaction, classification, and a worked prompt-injection case
engineering-team Architecture knowledge, runbooks, ADRs, supersession
multi-agent-company One repository, five agents, five different bundles

CI

name: OpenContext

on: [pull_request, push]

jobs:
  context:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: npx @logicsrc/opencontext validate --strict
      - run: npx @logicsrc/opencontext doctor --strict

Exit codes are stable: 0 ok, 1 invalid, 2 usage, 3 not found.

Guides

Guide Question it answers
Specification The normative contract
Manifest Every field of opencontext.yaml
Context object Every field of an object
Authority and conflicts Which context wins, and what happens when nothing does
Permissions and scopes Who may read what
Provenance Where a fact came from
Lifecycle and versioning Freshness, expiry, supersession, history
CLI Every command and flag
SDK The TypeScript API
Adapters Writing an adapter for your own system
Security and trust The trust boundary and prompt-injection safety
Conformance Implementing or verifying OpenContext
Versioning policy How the specification changes
Integration patterns System prompts, RAG, MCP, CI/CD, GitOps, API servers
OpenPRD and OpenTopology How the LogicSRC specifications fit together
FAQ The questions people actually ask

The specification family

Specification Primary question
OpenPRD What are we building and why?
OpenTopology How is the system organized?
OpenContext What does everyone need to know? 
OpenPRD       -> intent / requirements
OpenTopology  -> architecture / relationships
OpenContext   -> knowledge / policy / operational context
LogicSRC      -> execution by humans and agents

OpenContext is independently usable. The integrations are optional.

Foundational rules

  1. Context outlives workers. Humans and agents come and go.
  2. Authority is explicit. Retrieval rank does not equal truth.
  3. Authorization precedes relevance. An agent cannot retrieve what it may not access.
  4. Provenance survives resolution. Compiling context must not erase its origin.
  5. Canonical conflicts are visible. The resolver does not quietly guess.
  6. History is valuable. Supersession beats silent mutation.
  7. Agents are replaceable. Context is not coupled to a model vendor.
  8. Local-first is valid. A folder and a Git repository are enough.
  9. Hosted services are optional. The specification stands alone.
  10. OpenContext is a control plane, not the database. Existing systems remain sources of truth.
  11. Least context is better than all context. Return what is sufficient and authorized.
  12. Observed context does not become truth automatically. Promotion is explicit.
  13. Context is data, not executable instruction. Untrusted content never changes resolver policy by saying so.
  14. Interoperability beats feature lock-in. A compliant bundle should work across runtimes.

We used to manage people. Increasingly, we manage agents — and managing agents is largely managing context. Agents, models, and employees come and go. The organization's mission, policies, knowledge, procedures, decisions, and history should not disappear with them. OpenContext makes that shared brain portable.