# 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? By Rohit Gawli · 2026-11-04 · light · https://www.rohitgawli.com/reports/company-brain/ Public data only. Licence: CC BY 4.0. Structured version: https://www.rohitgawli.com/reports/company-brain/data.json ## 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](https://github.com/AnswerDotAI/llms-txt), [AGENTS.md](https://github.com/agentsmd/agents.md) and [Agent Skills](https://agentskills.io/specification) 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 agent's path through Dabba's bundle; `[n]` marks a file opened at step n, everything else stays closed. ```text [1] index.md root map: 4 lines, one per folder metrics/ [2] index.md 120 lines, one per metric [3] trial-conversion.md the definition; it declares 2 links new-subscribers.md churned-subscribers.md … 117 more computations/ index.md [4] trial-conversion.md linked from 3: the one query … 119 more decisions/ index.md [4] 2026-04-trial-conversion.md linked from 3: why it changed … 47 more glossary/ index.md … 36 more 5 of 329 files opened · 324 stayed closed (counts invented, for illustration) ``` **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. ```markdown # 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. ```markdown # 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.** `/metrics/trial-conversion.md`: ```markdown --- 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. `/computations/trial-conversion.md`: ```markdown --- 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. `/decisions/2026-04-trial-conversion.md`: ```markdown --- 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.** ```text Trial-to-paid conversion, Oct 2026: 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. ```text 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. | layer | project | licence | last push | |---|---|---|---| | definitions | [MetricFlow](https://github.com/dbt-labs/metricflow) | Apache-2.0 | 2026-10-13 | | definitions | [Cube](https://github.com/cube-js/cube) | mixed (1) | 2026-11-01 | | definitions | [Malloy](https://github.com/malloydata/malloy) | MIT | 2026-10-31 | | definitions | [Apache Ossie](https://github.com/apache/ossie) | Apache-2.0 | 2026-11-01 | | catalog & lineage | [OpenMetadata](https://github.com/open-metadata/OpenMetadata) | Apache-2.0 | 2026-11-01 | | catalog & lineage | [DataHub](https://github.com/datahub-project/datahub) | Apache-2.0 | 2026-10-31 | | catalog & lineage | [Unity Catalog](https://github.com/unitycatalog/unitycatalog) | Apache-2.0 | 2026-10-31 | | catalog & lineage | [Apache Gravitino](https://github.com/apache/gravitino) | Apache-2.0 | 2026-10-30 | | catalog & lineage | [OpenLineage](https://github.com/OpenLineage/OpenLineage) | Apache-2.0 | 2026-11-01 | | catalog & lineage | [Marquez](https://github.com/MarquezProject/marquez) | Apache-2.0 | 2026-10-29 | | decisions & memory | [Graphiti](https://github.com/getzep/graphiti) | Apache-2.0 | 2026-11-01 | | decisions & memory | [Cognee](https://github.com/topoteretes/cognee) | Apache-2.0 | 2026-11-01 | | decisions & memory | [GraphRAG](https://github.com/microsoft/graphrag) | MIT | 2026-10-29 | | decisions & memory | [Mem0](https://github.com/mem0ai/mem0) | Apache-2.0 | 2026-10-30 | | decisions & memory | [Letta](https://github.com/letta-ai/letta) | Apache-2.0 | 2026-10-18 | | documents & threads | [Onyx](https://github.com/onyx-dot-app/onyx) | mixed (2) | 2026-11-01 | | the agent's door | [MCP reference servers](https://github.com/modelcontextprotocol/servers) | mixed (3) | 2026-10-29 | | the agent's door | [MCP Toolbox for Databases](https://github.com/googleapis/mcp-toolbox) | Apache-2.0 | 2026-11-01 | | the agent's door | [dbt-mcp](https://github.com/dbt-labs/dbt-mcp) | Apache-2.0 | 2026-10-30 | | the agent's door | [WrenAI](https://github.com/Canner/WrenAI) | mixed (4) | 2026-10-30 | | the map | [Open Knowledge Format](https://github.com/GoogleCloudPlatform/open-knowledge-format) | Apache-2.0 | 2026-08-21 | | the map | [llms.txt](https://github.com/AnswerDotAI/llms-txt) | Apache-2.0 | 2026-09-24 | | the map | [AGENTS.md](https://github.com/agentsmd/agents.md) | MIT | 2026-09-10 | | the map | [Agent Skills (example skills)](https://github.com/anthropics/skills) | mixed (5) | 2026-10-28 | Licence notes, from each repo's licence file: 1. Cube: Apache-2.0, some packages MIT. 2. Onyx: MIT outside `ee` directories (enterprise licence). 3. MCP reference servers: moving from MIT to Apache-2.0. 4. WrenAI: code Apache-2.0, docs CC BY 4.0; AGPL-3.0 text shipped for possible future modules. 5. Agent Skills examples: 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//`) 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](https://venturebeat.com/resources/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](https://venturebeat.com/data/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](https://github.com/GoogleCloudPlatform/open-knowledge-format/blob/main/SPEC.md) — read 2026-11-01 - [Agent Skills specification](https://agentskills.io/specification) — read 2026-11-01 - [The /llms.txt file](https://github.com/AnswerDotAI/llms-txt) — read 2026-11-01 - [AGENTS.md](https://github.com/agentsmd/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 This file is the Markdown version of https://www.rohitgawli.com/reports/company-brain/. Structured findings, method, limits, build steps and sources: [data.json](https://www.rohitgawli.com/reports/company-brain/data.json). Site index: [llms.txt](https://www.rohitgawli.com/llms.txt).