Read
The agent reads the complete canonical page first - including its current revision.
This is the company half of the two-brain split described in Two Brains, One Operator. It is published at the same conceptual level as that essay: the shape and the governance model, not hostnames, server paths, internal identifiers, product or agent names, security specifics, or live counts. The personal half has its own structure reference.
The problem the structure solves
A company brain has to solve one problem above all others: many writers, most of them models, and no reviewer with time to read them all. The structure below is the answer. It is not a filing convenience - the folder taxonomy, the source split, and the write-fences are what make autonomous writing survivable without a human reading every change.
One engine serves three sources. Git-backed Markdown is the durable authority; the database and the vector index are projections of it - diffable, revertible, replaceable. That single choice is what lets agents write freely: any bad write is a commit you can inspect and roll back.
The topology
Three sources beside one another, and the folder shape of the shared source.
company-brain/ one engine · three sources · git is authority │ ├── shared/ the one writable company source (~hundreds of pages) │ │ │ ├── decisions/ records of what was decided and why │ ├── standards/ company conventions and policy │ ├── domain/ business-domain knowledge │ ├── platform/ platform / engineering reference │ ├── runbooks/ operational procedures │ ├── incidents/ incident records │ ├── sources/ imported / external source material │ │ │ ├── products/ <product>/ one folder per registered product │ │ └─ product hub + its pages; a product id is the join key │ │ │ └── agents/ <agent>/ one folder per writer │ └─ each agent's own records; the default write fence │ ├── archive/ frozen · read-only · searchable │ historical imports (~thousands of pages); every hit labelled historical, │ never silently substituted for current company evidence │ └── internal/ restricted · no agent grants · deliberately empty a home for restricted material that agents cannot see write fences (server-enforced, per OAuth client): an agent may put_page only inside agents/<its-own-name>/ + products/ a write outside that prefix → permission denied (verified live, not policy prose) reads span shared/ + archive/
source / folder
writable / per-item
annotation
restricted / denied
the fence itself
Why the shape is what it is
Three sources, not one
A writable shared source, a frozen archive, and a restricted internal source that sits empty with no grants. Separation is the point: current evidence, historical evidence, and material agents must never touch are structurally distinct, not just tagged.
Subject folders + two axes
Shared documentation is filed by subject (decisions, standards, domain, platform, runbooks, incidents, sources). Alongside it, products/<id>/ joins knowledge to a product and agents/<name>/ gives every writer its own space.
Fences the server enforces
Each agent’s credential carries a server-enforced list of write prefixes - its own agents/<name>/ plus products/. A write outside the fence returns permission-denied from the server. An agent cannot widen its own surface at runtime.
Archive is labelled, not trusted
The archive is searchable and frozen; every hit is labelled historical. This replaced an old design where ~1,900 imported pages read as ~1,900 things waiting for a human verdict. Most never needed one - so they were frozen, not queued.
How a write lands
Revision-safe and asynchronous: a pending response is never treated as a completed write.
Write
It rewrites the whole page and calls put_page with the expected revision and a fresh request id.
Confirm
It polls a receipt until the write is committed and the Markdown file is on disk, then reads the page back in full.
Recover
A lost response replays the same request id; a revision conflict is re-read and retried, never forced.
Maintain
Nightly native jobs run inside the engine: backlinks, embeddings, orphan scan, and a weekly exceptions digest.
My role shrank to the edges: approve a new client, set its fence, handle
destructive operations, and decide anything touching internal or the
topology. Everything else is agents writing inside their fences, against a record
that git makes revertible.
Retrieval is not one verb
Described conceptually; the exact ranking and provider behaviour is deployment state, not a published guarantee.
| Verb | LLM? | What it is for |
|---|---|---|
search | no | Literal-oriented hybrid retrieval. Use it when you know the exact token, name, or slug fragment. |
query | optional | Hybrid retrieval that may expand into sub-queries. Use it for “all the X that do Y” concept and landscape questions. |
recall | no | Returns the service’s recall payload. Inspect the shape rather than assuming a populated fact store. |
synthesize | yes | Cross-page composition with citations and gap reporting. Output is a draft that still needs grounding checks. |
The operating rule that matters more than the verb choice: a ranked excerpt is not a support procedure. Inspect source, type, slug, revision, and applicability, then read the complete page. Do not infer completeness from index size or a retrieval score - a confident-looking top hit from the wrong product is the failure mode this rule exists to prevent.
The boundary that makes it safe
The company brain and the personal brain are separate systems with different owners, subjects, permissions, and costs of being wrong. Company work stays in company sources. The personal brain is never a fallback, never auto-searched, never federated into a company query, and never a place a company-only agent quietly writes personal or unrelated material.
Saving is manual and explicit. Knowledge enters through an authorized save request; session completion, entity mentions, and useful findings alone do not trigger a write. Reading never authorizes a save. These rules - not the retrieval quality - are what let a room full of model writers share one brain without eroding trust in it.
Related
- Personal Brain Structure - the other half: one numbered PARA vault, enumerated and redacted.
- Two Brains, One Operator - the full architecture and governance argument this reference summarizes.
- Why a Knowledge Management Layer Still Matters - why access and search alone are not an operating model.
- Building a Second Brain - the research track this reference belongs to.