Organizational Context Protocol

Git as the source of truth for AI-orchestrated organizations - and everything else as a disposable projection of it.

Author: Max Forbang · maxforbang.com
License: MIT - free to use, adapt, and redistribute (full text at the end of this document)
Status: Public draft, open for adoption

What it is: OCP is an open specification for how an organization exposes its structure, knowledge, and access rules to AI agents - with git and markdown as the single source of truth, and every database, index, and cache treated as a disposable projection of it.

Why it matters:

• A source of truth you can actually read. Your organization's context lives in git as plain markdown - versioned, diffable, forkable, portable - instead of locked inside an opaque vector store you can neither inspect nor leave.
• Structure agents can reason over. A recursive organizational hierarchy and a small, closed set of artifact types replace the flat "bag of chunks," so an agent knows where it is operating and what applies - no context bleeding across client or team boundaries.
• Access and trust live in the substrate. RBAC, visibility scopes, and trust tiers are declared alongside the content and versioned with it, so a poisoned document is quarantined at the boundary instead of hijacking every agent that retrieves it.

Contents:

1. The problem: the "AI brain" is built on sand
2. The core axiom: substrate vs. projection
3. What OCP specifies
4. The protocol triangle (OCP ↔ MCP)
5. Hexagonal architecture, applied to content
6. The structure: recursive and uniform
7. Five artifact types, closed and small
8. Organizational RBAC for agents and tools
9. Kernels: content-shape domain models
10. Access surfaces
11. Versioning
12. Why OCP is a standard, not a product
13. What conformance looks like

Every organization is about to be run by agents - not merely assisted by them, but run by them. Fleets of AI workers that source and sell, support and operate, decide and document, reading from and writing to the same shared reality hundreds of times a day. The constraint on that future is not the intelligence of the models; frontier models already outrun the context we hand them. The constraint is the substrate they read from. An agent is exactly as good as the organizational context it is given, and today that context is scattered across a dozen incompatible stores - a vendor's vector database, a SaaS tool's proprietary memory layer, a wiki, a spreadsheet, a Slack thread, someone's head - with no structure, no single source of truth, no version history, and no notion of who is allowed to see what. We are wiring superhuman workers into organizations whose institutional memory is a pile of unversioned, access-blind, vendor-locked embeddings, and then acting surprised when they hallucinate, leak, or drift.

The Organizational Context Protocol (OCP) is the correction, and it holds a single position defensible for fifteen years: the source of truth for an organization's reality should be git - plain markdown, versioned, forkable, equally legible to a human and to an agent - and everything else should be a disposable projection of it. Not a database you occasionally back up to git. Not a wiki you export. Git as the operating substrate for organizational context: the place where what-is-true lives, and from which every vector index, every dashboard, every cache, and every agent's working memory is derived - cheaply - and discarded when stale. This document explains why that position is correct, what the protocol specifies, and how any organization - a client-acquisition agency, a customer-support operation, an internal operations team, or a solo builder - adopts it.

OCP is free, open, and intended for adoption. It is a specification in the lineage of CommonMark and the Model Context Protocol: a standard derives its value from being adopted, not from being owned.

1. The problem: the "AI brain" is being built on sand

There is a craze underway to give every company a "second brain" for its agents - an AI-readable memory of everything the organization knows. The reflex is almost universal: take all your documents, chunk them, embed them, and stuff the vectors into a database that the agents query at runtime. Call it the brain. Ship it.

This pattern is quietly broken in four load-bearing ways, and the breakage is structural, not a matter of picking a better vendor.

There is no source of truth. The vector store is the memory, which means the memory is a lossy, opaque derivative with no canonical original. You cannot read it, diff it, review it in a pull request, or reason about why it says what it says. When two facts conflict, nothing adjudicates. When a fact is wrong, there is no upstream to correct - only re-ingestion, which is a prayer, not a fix.

There is no structure. Everything is a flat bag of chunks. An organization is not flat - it has altitudes (the whole company, a division, a client account, an individual), it has projects and initiatives and decisions, it has concerns that belong at one level and not another. Collapse all of that into one undifferentiated index and you get context bleed: the agent working on Client A retrieves a chunk about Client B because cosine similarity does not respect organizational boundaries. Structure is the thing that was thrown away, and structure is exactly what an agent needs to reason correctly about where it is and what applies.

There is no version history. Institutional memory that cannot be replayed is not memory; it is a mood. "What did we believe about this account in Q1, and what changed?" is unanswerable in a mutable vector store. Every serious organizational substrate in history - the ledger, the lab notebook, the codebase - is append-aware and auditable. The AI brain, as commonly built, is none of these.

There is no access control, and this is where it gets dangerous. A flat vector store makes every chunk equally retrievable by every agent. There is no concept of which agent may read which fact, no trust boundary between a vetted internal SOP and an unvetted note scraped from an inbound email. This produces two failure modes that are now appearing in the wild. First, exfiltration: a low-privilege agent retrieves high-sensitivity context because retrieval has no notion of privilege. Second, prompt injection at scale: a single poisoned document - an email, a support ticket, a web page someone pasted in - enters the index, and from then on any agent that retrieves it can be hijacked by instructions hiding in the "data." The brain becomes an attack surface, and the standard mitigation today is a pile of bespoke, one-off guardrails bolted on beside the store.

The first-principles reading is simple. An agent is only as trustworthy as the substrate it reads from. If the substrate has no source of truth, no structure, no history, and no access model, then no amount of model quality upstream will save you downstream. The problem is not the brain. The problem is that the brain has no skeleton.

2. The core axiom: substrate is sovereign, projections are regenerable

OCP begins from one axiom that reorganizes everything else:

Every piece of organizational reality is either sovereign substrate - authored once, versioned, canonical - or a derived projection, rendered from substrate on demand and never canonical in its own right.

Git holds the substrate: markdown files with structured frontmatter, versioned by commit, forkable, and readable by any human or agent without a special client. Everything a runtime system needs for speed or shape - a vector index for semantic search, a Postgres table for queries, an in-memory cache, a CDN mirror, a dashboard, an agent's hydrated working context - is a projection. Projections are deterministic functions of the substrate. They are allowed, encouraged, and disposable. If a projection is lost or corrupted, you rebuild it from git and lose nothing. If two projections disagree, git breaks the tie.

This single distinction dissolves the four problems above at once. There is a source of truth (git). There is structure (the directory tree and frontmatter). There is history (the commit log). And - critically - access and trust become properties of the substrate, carried in the same files the content lives in, rather than a policy engine grafted onto a projection after the fact.

The vector store does not go away. It is demoted. It stops being the brain and becomes one projection among many - rebuildable, subordinate, and safe to throw away.

3. What OCP specifies

OCP is the canonical standard for how an AI-orchestrated organization exposes its structural reality to agents. It makes six commitments, and conformance means honoring all six.

1. Substrate. Git is the source of truth. Markdown with YAML frontmatter is the canonical content format. The two together are the complete authoring stack.
2. Structure. Organizations have a recursive, uniform nested structure under five positional altitudes (platform, tenant, agency, account, user). Depth is chosen per organization; the rules at one level are identical to the rules at every other.
3. Artifact types. The registry contains exactly five canonical types (note, adr, prompt, template, report), closed at the type level and extended through a role field and an open metadata object.
4. Kernels. Content-shape canonical domain models with strict admission criteria. The Initiative Kernel is the universal primitive for goal-directed work; new kernels are rare and heavyweight by design.
5. Access surfaces. The same git tree is consumed through many surfaces (filesystem, web UI, MCP server, project-knowledge indexers, OAuth tools, git APIs, agent SDKs, CDN mirrors), each with characterized latency, freshness, authentication, and write capability - but never a different content shape.
6. Inheritance. Any organization that adopts OCP, and any concern authored under its conventions, inherits all of the above automatically. The cost is conformance to the standard; the benefit is N+M ecosystem integration complexity instead of N×M.

The protocol does not prescribe how to implement any of this. It prescribes what conformant content looks like. Everything else - which git host, which database for projections, which branching strategy - is left to the adopter.

4. The protocol triangle: OCP is to context what MCP is to tools

Developers who have met the Model Context Protocol (MCP) already understand the shape of OCP, because they are the same architectural move applied to different substrates.

All three reduce combinatorial integration cost. Without a standard, N consumers times M producers is N×M bespoke integrations. With a standard, it collapses to N+M: every consumer speaks the protocol once, every producer emits it once, and they compose. MCP did this for tools. OCP does it for context. An agent that speaks both reads its organization's reality through OCP and takes action through MCP - the two protocols compose without conflict, because one answers what is true and what applies here and the other answers what can be done.

This is the whole case for OCP being a standard rather than a feature: the value is in adoption. The more organizations expose their context in OCP shape, the more every OCP-aware tool works everywhere, and the more every organization benefits from tools it did not have to build.

5. Hexagonal architecture, applied to content

The cleanest way to hold OCP in your head, if you know Clean Architecture and Ports & Adapters, is this: OCP is hexagonal architecture for content instead of code.

The symmetry is exact. A port defines what a domain needs, independent of any vendor; adapters implement it. A kernel defines what an organizational concern needs, independent of any tool; instances populate it and surfaces render it. The same discipline that keeps vendor types from leaking across a code boundary keeps one organization's vocabulary from dictating another's structure.

The picture completes when you add tools: tools are to actions what kernels are to context. A tool (send_email, schedule_meeting, create_invoice) is a canonical interface for an action; adapters implement it against Gmail, Outlook, a billing provider. Kernels are canonical interfaces for context; adapters render them to a UI, an index, an agent. Agents are the orchestrators that read context (kernels, via OCP) and take action (tools, via MCP). Four concepts - ports, kernels, tools, adapters - one pattern, three substrates: executable behavior, organizational context, agent capability.

The payoff is that any engineer who already understands hexagonal architecture for code understands OCP the moment it is framed this way. There is nothing new to learn about the shape; only a new substrate to apply it to.

6. The structure: recursive, uniform, fractal

An organization under OCP is a tree of organizations. Every organization, at every altitude, contains the same canonical subdirectories, and every organization may contain child organizations under orgs/. The recursion has no fixed depth. You build only the altitudes you need.

Three conventions make this work in practice.

Altitude is positional vocabulary, not schema. The five altitudes - platform, tenant, agency, account, user - are descriptive positions an organization may occupy, not baked into directory names and not written into any file: an org's capabilities are data rather than a canonical type, and the only structural distinction is root-vs-child, keyed on parent_org_id (null at the root). This is what lets OCP be a universal standard rather than one company's hierarchy: a solo builder constructs two altitudes (platform → user); a services agency constructs three (platform → agency → account); a white-label reseller constructs four or five. Child organizations always live under orgs/, uniformly, regardless of their altitude - so the recursion never breaks.

Every directory has a README.md entry point. When a human, an agent, or a tool enters any directory, it reads README.md first, and the file's role frontmatter field declares the directory's purpose (org_definition, user_definition, kernel_index, and so on). This is universally rendered by git hosts and IDEs for free.

Underscore-prefixed directories are substrate. _kernels/, _adrs/, _system/, _users/ carry a leading underscore to signal "this is metadata of the repository or definition of the containing entity," distinct from the un-prefixed content directories. The convention echoes static-site generators (_posts/, _index.md) and is filesystem-safe everywhere.

The structure scales by adding nodes, never by restructuring existing ones. When a direct-operating agency starts white-labeling, its existing subtree slots underneath a new tenant org without a single file moving. Growth is insertion, not migration.

Concretely, the same shape serves very different organizations. A customer-support operation models each supported product as an account, with support initiatives and their SOPs as notes. A client-acquisition agency models each client as an account, with campaigns as initiatives. An internal operations team models its own programs as initiatives at the platform or tenant altitude. A company knowledge base is simply the notes/ substrate at whatever altitude the knowledge belongs to. One structure; many organizations.

7. Five artifact types, closed and small

Every canonical artifact in an OCP repository is exactly one of five types, declared in frontmatter via artifact_type.

The set is closed (adding a new type requires amending the protocol itself) and this closure is the point, not a limitation. Five known types means five known frontmatter schemas, which means every protocol-aware tool (a web UI, an MCP server, a search index, a linter, a renderer) can be written once against exactly five shapes and work against every conformant organization. Uncoordinated artifact types would demand ecosystem-wide tool updates; closure buys ecosystem composability.

Extensibility lives in two open dimensions that require zero ecosystem coordination. The role field discriminates within a type: a note with role: kernel_index is structurally a note but plays the part of a directory's entry point; a note with role: roster is the canonical client registry. The metadata object holds any user-domain fields the standard does not know about (journey_stage, sender_pool_size, criticality, anything). Conformant tooling relies on the closed universal fields; it never reads metadata, so you extend without ever migrating a schema. This is the same discipline MCP applies to its closed set of primitives: closure at the primitive level, freedom at the composition level.

8. Organizational RBAC for agents and tools: the piece nobody has standardized

Return to the security failure of Section 1. The reason a flat vector store leaks and gets hijacked is that access and trust are absent from the substrate - retrieval sees only vectors, not who-may-read-what or how-far-to-trust-this. OCP fixes this at the root, because when context lives in git under a declared organizational hierarchy with typed frontmatter, access control and trust become first-class, declarative, versioned properties of the content itself.

Access cascades along the structure. Authorization is a path-prefix decision. A principal's membership is declared in their memberships.md; a request for a path walks up the tree to the controlling organization and checks membership. Admin authority cascades downward - an admin of an organization is automatically an admin of its descendants - while non-admin roles require explicit membership at each altitude and never cascade. This is the ordinary, well-understood hierarchy model of serious B2B systems, except here it is expressed in versioned files, so who could see what, and when is answerable by reading git history rather than interrogating a black-box policy store.

Trust and visibility ride on each artifact. Because every artifact is self-describing, its frontmatter can carry the metadata that a retrieval layer needs to fence itself: a trust tier, a visibility scope, and - as agent fleets mature - which agent roles may read or write it, and which tools may be dispatched against which altitude. A vetted internal SOP and an unvetted note captured from an inbound email are different artifacts with different declared trust, so a projection built from the substrate can refuse to expose low-trust content to a high-privilege reasoning path. The policy is not a wrapper bolted on beside the index; it is authored in the same file as the content, reviewed in the same pull request, and versioned by the same commit.

---
artifact_type: note
role: capture
status: active
trust_tier: 2                     # unvetted; captured from an external source
visibility: [account:acme-co]     # scope of who/what may retrieve this
metadata:
  source: inbound-email
  agent_roles_read: [triage]      # low-privilege reasoning only
  agent_roles_write: []           # agents may not mutate a capture
---

And then the invariant that ties it together, carried over from the substrate-vs-projection axiom:

Derivation does not launder trust. A fact inherits the trust tier of its lowest-trust source, no matter how many LLM hops it passes through.

A summary generated by an agent from a Tier-2 capture is still Tier 2. It does not become trusted merely because a model rewrote it, because it landed in a nicer document, or because it now sits next to vetted content in an index. In the flat-vector-store world this guarantee is impossible - provenance is dissolved at ingestion, and a laundered instruction is indistinguishable from a vetted one. Under OCP, provenance is substrate, trust is declared, and the projection can enforce a fence the model cannot talk its way past.

This is the current, near-universal gap in company knowledge bases racing to plug in AI agents, and it is the reason the "AI brain" pattern is producing bespoke, one-off security patches instead of a general answer. OCP's answer is general: make organizational RBAC and trust a versioned, auditable, extensible primitive that lives in the substrate, so it is the same for a two-person shop and a white-label platform serving hundreds of client accounts - and so the poisoned document can be quarantined at the boundary instead of hijacking every agent downstream.

9. Kernels: content-shape domain models

A kernel is to organizational context what a port is to code: the canonical shape a concern requires, independent of any particular instance. Kernels are deliberately heavyweight - admitting one requires a full decision record and clearing strict criteria (universally applicable, substrate-independent, agent-readable without translation, at least three genuinely independent use cases, a stable multi-year lifespan grounded in a first principle of how organizations actually work). The criteria exist to prevent proliferation: without them, every feature gets called a kernel and the substrate fragments.

Today there is one canonical kernel, and it is enough for an enormous surface area: the Initiative Kernel, the universal primitive for goal-directed work. Its atom is a work unit; each work unit declares a tier_type - initiative, project, ticket, sub-ticket - that turns on the appropriate fields. Initiatives carry goals and measurement; projects carry a definition of done; tickets carry binary completion. Depth is a per-organization choice: a solo operator might use only initiatives and tickets; a mature team uses all three.

The same kernel covers concerns that look unrelated on the surface. A client-acquisition campaign, a customer-support initiative, an internal operations program, and a personal accountability sprint are all instances of the Initiative Kernel with different parameters - because the underlying truth (goal-directed work is a measurable end state with sub-units of execution) does not change across domains. That invariance is precisely why it qualifies as a kernel and a hundred domain-specific concepts do not.

10. Access surfaces: one substrate, many consumers

The same git tree is consumed through many surfaces, and OCP characterizes them so integration authors can locate their pattern rather than reinvent it.

The guarantee that makes this tractable is uniform content shape: freshness differs across surfaces; content does not. An artifact read through a local filesystem, an MCP server, a project-knowledge index, or a public mirror returns the same content, frontmatter included. No surface elides the schema bridge that makes the content machine-readable. This is what "agent-native" means concretely - any agent that can read markdown can consume any OCP-conformant organization with no bespoke integration, no parsing library, no vendor client.

11. Versioning: the commit is the truth

OCP commits to one authoritative version reference and three conveniences layered on top. The commit SHA is canonical: every artifact at every path has a current SHA and a full history, and when any system needs to refer to "this version of this fact," the reference is the SHA. A frontmatter version field is human courtesy and may drift. Tags mark notable boundaries (a launch, an audit snapshot). Branches carry parallel evolution (experiments, drafts, candidate amendments). All of them resolve to SHAs at the substrate layer, at every scope - per artifact, per directory, per repository. Institutional memory is not a mood; it is a log you can replay.

12. Why OCP is a standard, not a product

OCP is free on purpose, and the reasoning is structural, not charitable. A standard derives its value from adoption, not from exclusion: a gated, proprietary format that nobody else emits is worth nothing to the organizations that would have to live inside it. An open one compounds - every organization that speaks OCP makes every OCP-aware tool more useful, which draws more tools, which in turn makes every adopter's own content more valuable than it was the day before. This is the CommonMark story, the OpenAPI story, the 12-Factor story, and the MCP story: an open specification is a rising tide that lifts everyone standing in it. The organizations that adopt OCP are the ones who benefit - they are never locked in, never charged rent for the format their own knowledge lives in, and never stranded when a vendor changes direction, because their substrate is plain git and plain markdown, portable by construction, and the ecosystem's tooling comes to them.

There is a discipline that follows from this, worth stating as a maxim: sacrifice perfection for conformity. Where a de-facto convention already exists, conform to it and contribute upstream rather than ship an opinionated competing root. The sequence is build, then adopt, then standardize - never the reverse. It is Postel's law applied to agent ecosystems: be conservative in what you emit, liberal in what you accept. A standard that optimizes for its author's elegance over its ecosystem's adoption has misunderstood what a standard is for.

13. What conformance looks like

Adoption is deliberately cheap, because a standard nobody can start using in an afternoon is a standard nobody uses. The bar OCP holds itself to is thirty-minute operability: a first-time operator - human or agent - should be able to read the platform README.md, read the relevant kernel definition, read an initiative's README.md, and run a competent operation within half an hour. Complexity that exceeds that budget is a defect to be fixed with better entry points or an explicit decision record, not accepted as the cost of doing business.

In practice, conforming means: put your organizational content in a git repository as markdown with frontmatter; give every directory a README.md that declares its role; keep the closed artifact-type registry honest; and let your runtime systems treat their indexes and databases as projections they rebuild from git. The fastest on-ramp is to fork a conformant template and replace its content with your own - the structure is portable; only the domain content is yours to write. Everything downstream - agents reading the tree, tools rendering it, indexers projecting it - then works by inheritance, because that is what a protocol buys you.

Closing

The models will keep getting better; that was never the bottleneck. What determines whether an organization can be run by agents is whether those agents stand on solid ground - a substrate with a source of truth, a structure that respects boundaries, a history that can be replayed, and an access model that decides who may read what and how far to trust it. Build the brain on a flat, mutable, access-blind index and you have built an oracle with no skeleton, no memory, and an open door. Build it on git, and the same properties that made version control the foundation of modern software - canonical source, cheap forking, auditable history, reviewable change - become the foundation of modern organizations.

The source of truth is git. The structure is recursive, uniform organizational nesting. The artifact-type set is closed and small. Access and trust are declared in the substrate, versioned alongside the content, and never laundered by derivation. Everything else is a projection, rebuildable and disposable. Speak the protocol, and every tool works with your organization; adopt it, and inherit every guarantee; deviate from it, and the ecosystem fragments.

This is the substrate for AI-orchestrated organizational reality. It is free, it is open, and it is meant to be adopted.

OCP descends from the "LLM wiki" lineage - markdown-in-a-folder, the agent as its own maintainer, persistent structured knowledge in place of opaque retrieval - and generalizes it from a single repository into a recursive, multi-tenant organizational standard with a closed artifact-type system, a kernel model, and a declarative access-and-trust layer. This document is a conceptual overview; a companion scaffolding guide walks an operator from a blank repository to a conformant organization. The specification and its reference tooling are open and free in perpetuity.

License

The OCP specification and this overview document are released under the MIT License - you may use, copy, modify, publish, distribute, and build upon them freely, including in commercial and closed-source projects.

MIT License

Copyright (c) 2026 Max Forbang

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.