how to build a company brain

How do you get an AI agent to give the same, correct answer to "what was our trial-to-paid conversion last month?" every time?

the problem

The agent first has to decide what counts as a trial and what counts as converted. If nobody wrote that down where it can read it, it picks something it can count, says the number with confidence, and may pick differently when you ask again.

• 64% of 130 organisations traced at least one confidently wrong agent answer to missing or inconsistent business context in the past six months; 32% of 130 traced more than one. vb pulse, august 2026 wave · organisations with 100+ staff · self-selected readers and panel members
• 67% vs 13% 67% are running, piloting or building a governed semantic layer, but only 13% name it as their agents' main source of business context. Document retrieval (32%) and live-system queries (21%) are named more often. vb pulse, august 2026 wave · base not printed for this split

So companies are writing their definitions down, and their agents are mostly reading something else.

the solution

Write the company's meanings down as a folder of small Markdown files, and make the agent use it like a library: catalogue card first, then the one book. Each metric gets a file with its definition, a link to the one query the agent may run but not edit, and a link to the decision behind it. Every folder has an index.md with one line per file. The agent starts at the root index, opens only what the question points to, and cites every file it used.

I've built this: lazy loading, like a library. An index file points the agent to the folder for the metric being asked, so the context stays small even when it has to know hundreds of metrics.

the format: open knowledge format (okf), v0.2

Google Cloud's Open Knowledge Format, version 0.2 (Apache-2.0), is a public spec for this shape. The parts used here:

• A bundle is a directory tree of Markdown files (§3), and a concept's ID is its path (§2).
• type is the only required frontmatter key (§4.1). sources (§5.1), verified (§5.2, giving three trust tiers, §5.3), status (§5.4) and stale_after (§5.5) say where a file came from, who checked it and when it expires.
• Any folder may have an index.md, one [Title](link) - description line per entry, "to support progressive disclosure" (§8), and a dated log.md of changes (§9).
• An Attested Computation holds the sanctioned query; the agent fills in its parameters and must not edit the query (§10, §10.3).

The spec is early and leaves the runtime protocol for later (§12). llms.txt, AGENTS.md and Agent Skills use the same small-map-first idea.

how lazy loading works

illustration · "dabba" is a made-up meal-subscription app. every file, name, date and count below is invented.

The question: what was our trial-to-paid conversion last month? The diagram is the agent's path through Dabba's bundle; the steps show each file it opens.

step 1 · read only the root index

Always /index.md first: four lines, one per folder. The question is about a number, so the metrics line matches.

# Dabba company brain

* [Metrics](metrics/) - what each number means; open for any question about a number
* [Computations](computations/) - the sanctioned queries; reached from a metric, not browsed
* [Decisions](decisions/) - why a definition is what it is, and when it changed
* [Glossary](glossary/) - words that mean something specific here

step 2 · pick the folder, read its index

/metrics/index.md has 120 lines, one per metric. The agent reads the lines, not the 120 files.

# Product metrics

* [Trial-to-paid conversion](trial-conversion.md) - self-serve trials that paid within 14 days; open for any question about trials converting
* [New subscribers](new-subscribers.md) - first paid order in the period; open for growth counts
* [Churned subscribers](churned-subscribers.md) - no paid order for 28 days; open for churn
* … 117 more lines

step 3 · open one definition

---
type: Metric
title: Trial-to-paid conversion
description: Self-serve trials ending in the month that paid within 14 days.
status: stable
verified: { by: human:head-of-product, at: 2026-10-20T09:00:00Z }
stale_after: 2027-01-20T00:00:00Z
sources:
  - id: q2-decision
    resource: /decisions/2026-04-trial-conversion.md
    title: Why sales-assisted deals were excluded
---

# Definition

A trial counts in the month its 14-day window ends, not the month it
starts. It converted if the first paid order came within that window.
Reactivations (former subscribers coming back) and sales-assisted deals
(corporate plans closed by the sales team) are excluded.[^q2-decision]

Computed only by [the computation](/computations/trial-conversion.md).

[^q2-decision]: Why sales-assisted deals were excluded

The agent checks the frontmatter first: status is stable, a human: verified it, and stale_after has not passed. If it had, the agent says so instead of answering.

step 4 · follow only the links that file declares

The definition names two files, the computation and the decision. The agent opens those and nothing else in their folders, not even their indexes.

---
type: Attested Computation
title: Monthly trial-to-paid conversion
runtime: postgres
parameters:
  - { name: month_start, type: date, required: true }
executor:
  resource: /references/run-on-postgres.md
  receipt: [executed_sql, result]
attester:
  resource: /references/attesters/trial-conversion.py
verified: { by: human:data-lead, at: 2026-10-20T09:00:00Z }
---

# Computation

    SELECT COUNT(*) FILTER (WHERE paid_at <= trial_end)::numeric
           / NULLIF(COUNT(*), 0) AS trial_to_paid
    FROM trials
    WHERE trial_end >= @month_start
      AND trial_end <  @month_start + INTERVAL '1 month'
      AND NOT is_reactivation
      AND NOT is_sales_assisted

It supplies one value, month_start = 2026-10-01, and writes no SQL. A check then compares the query that ran with this one.

---
type: Decision
title: Exclude sales-assisted deals from trial conversion
status: stable
verified: { by: human:head-of-product, at: 2026-04-14T15:00:00Z }
---

# Decision

From 14 Apr 2026, sales-assisted deals no longer count. One large
corporate deal could move the self-serve rate by itself.
Monthly rates before and after this date are not comparable.

step 5 · answer and cite the files

Trial-to-paid conversion, Oct 2026: <the rate the sanctioned query returned>

Definition: metrics/trial-conversion.md (human-reviewed 20 Oct 2026)
Computed by: computations/trial-conversion.md, month_start = 2026-10-01; check passed
Note: the definition changed on 14 Apr 2026 (decisions/2026-04-trial-conversion.md);
  rates before then included sales-assisted deals and are not comparable.

why the context stays small

The agent read a four-line map, a 120-line index and three short files: 5 of 329. Double the metrics and the only thing that grows is one index, by 120 lines. When an index gets too long to skim, split the folder (metrics/growth/, metrics/revenue/) and give each part its own index, which costs one more hop, not hundreds more lines.

why the answer repeats

The same question reaches the same index line, so the same files, so the same query with the same parameter. The agent picks a line; it does not invent a definition or write SQL. A model still makes the pick, so this is repeatable rather than guaranteed, and the citations are how you check: if two runs cite different files, an index line is ambiguous.

how to write an index line

A title and one description, and the description's job is to tell the agent when to open the file. Use the words people ask with, and say what is in and out.

weak:   * [Conversion](trial-conversion.md) - conversion metric
better: * [Trial-to-paid conversion](trial-conversion.md) - self-serve trials
          that paid within 14 days; open for any question about trials converting

If two lines could answer the same question, merge the files or say in each line which one to use.

how to build it

1. List your ten most argued metrics, the ones that come out different in every meeting.
2. Write one Markdown file per metric in metrics/: frontmatter as above, then the definition in plain words, including what is left out.
3. Put each metric's one sanctioned query in computations/, with only the parameters the agent may fill in, and link it from the metric.
4. Start decisions/ and a log.md: one dated file per change to a definition, linked from the metric.
5. Write an index.md in every folder, one line per file, and a root index.md with one line per folder.
6. Give the agent one MCP server (MCP is the standard way an agent calls a tool) that reads a file by path and runs a computation with its parameters, and make it the only route to these numbers.
7. Tell the agent to cite every file it opened, and to refuse a file whose stale_after has passed.
8. Once a month, re-verify every file near its stale_after date and move the date.

parts you can use

The Markdown bundle is enough for one team. At company scale, each part has open-source projects:

• definitions: metrics/ and computations/ as code.
• catalog & lineage: tables, owners, what feeds what.
• decisions & memory: decisions/, with when each fact was true.
• documents & threads: search over the wiki and chat.
• the agent's door: the one tool from step 6.
• the map: the index files.

Licence and last push from the GitHub API, 1 Nov 2026.

Licence notes, from each repo's licence file. ¹ Apache-2.0, some packages MIT. ² MIT outside ee directories (enterprise licence). ³ Moving from MIT to Apache-2.0. ⁴ Code Apache-2.0, docs CC BY 4.0; AGPL-3.0 text shipped for possible future modules. ⁵ No repo-wide licence; many skills Apache-2.0, document skills source-available.

method

1. On 1 Nov 2026 I read the two VentureBeat VB Pulse articles (5 and 6 Oct 2026) and copied each figure with its stated base. The August base, per the 5 Oct article: 184 responses, 139 qualified, 9 removed, 130 kept, at organisations with 100 or more employees.
2. The 6 Oct article prints no base for its August split. Document retrieval (32%) and live-system queries (21%) also appear in the 5 Oct article "across all respondents", so they share the 130; the other figures in it (67%, 13%, 19%) carry no base.
3. I read the Open Knowledge Format spec (SPEC.md, version 0.2), cited by section number, and the Agent Skills specification.
4. For the 24 projects, I called the GitHub API (repos/<owner>/<repo>) on 1 Nov 2026 for licence and last push, reading the licence file where the API said "Other" or nothing. Cut-off: a push after 1 Aug 2026; none was dropped.
5. I wrote the Dabba bundle, its file counts and the diagram myself, using OKF's fields as the spec defines them. I did not run it.

what this does not show

• Both surveys come from one publication's tracker: self-selected respondents, not a random sample, and 130 is small. The 5 Oct article says a subgroup of 38 can be off by about 15 points either way. The figures are reported and correlational.
• The 6 Oct article gives no sample size, and its four context sources add up to 85%.
• OKF is at version 0.2; field names may change.
• Dabba and its counts are invented. The files show the shape, not a system I tested.
• The project table is a list, not a benchmark, and the licences are as I read them on 1 Nov 2026.

sources

• Agentic context layers: 64% of enterprises traced a confidently wrong AI agent answer to problems in their own company data in the past six months · VentureBeat, 5 Oct 2026 · read 2026-11-01
• Companies are building governed semantic layers. Most say their AI agents are getting context somewhere else · VentureBeat, 6 Oct 2026 · read 2026-11-01
• Open Knowledge Format (OKF), version 0.2, SPEC.md · read 2026-11-01
• Agent Skills specification · read 2026-11-01
• The /llms.txt file · read 2026-11-01
• AGENTS.md · read 2026-11-01
• GitHub API repo metadata for the 24 projects in the table, linked in each row · read 2026-11-01

for agents

markdown: index.md · data: data.json · site index: llms.txt