How to Build a Company Brain: Context Engineering for a Whole Company

A CLAUDE.md solves context for one project. When the same facts are needed by four repositories, two automation agents and a new colleague, the problem changes shape: it becomes context engineering at company scale.

The company brain is the answer I have been running for months: a single source of knowledge, versioned, with a routing contract that declares what enters context and when, and validators that make writing rules executable. The why is in the previous article. This is the implementation.

As of today the starting point is different: the skeleton is public on GitHub under the MIT license. It is called company-brain-template, it is markdown files plus two dependency-free Node scripts, and it holds the structure, the MANIFEST.yaml and the validators with none of our data in it.

What you need before you start

Not much, which is the good news.

• git and Node 18 or later. The validators are two .mjs scripts with no dependencies: no package.json, no toolchain to install.
• An agent with filesystem or repository access: I use Claude Code, but anything that reads files from a folder works.
• Three artefacts you already have: the best proposal you ever won, your standard contract, and the last ten emails you sent to a client in an active negotiation.

The third one is what matters. If you are planning to stop for three weeks and document the company, you have already gone wrong: the knowledge exists, it sits inside the things you produced, and the work is not writing it but extracting it.

Step 1: take the skeleton

The repository has a Use this template button. It creates a new repository with the structure inside and none of our commit history attached, which is what you want: a brain should start from your first commit.

Make it private. It will hold pricing, margins and client information. I come back to this at the end, because it is the easiest thing to get wrong.

If you would rather not go through GitHub:

git clone https://github.com/Castaldo-Solutions/company-brain-template.git brain
cd brain && rm -rf .git && git init

What you get is this:

CORE.md            the only file always in context
MANIFEST.yaml      which file loads, and when
company/           facts: what you sell, to whom, on what terms
decisions/         decisions: why you chose this way, never rewritten
playbooks/         models: how something gets done
examples/          real artefacts that worked
validators/        writing rules, made executable

Step 2: write the always-in-context file

CORE.md is ring 0: the only file loaded in every session of every agent. Every line costs everyone, so it gets defended.

Four things belong in it, and nothing else:

1. Who you are, in ten lines. What you do, who you sell to, what you promise, with what method. Written the way a client would say it, not the way you would write it in a brochure.
2. The non-negotiable rules. The real ones, the checkable ones. "Write well" is not a rule. "Never use an em dash" is.
3. The map, meaning where everything else lives. Fifteen lines maximum: to add one, remove one.
4. What is confidential and who decides on pricing.

The discipline here is entirely in not adding. Our CORE.md sits at 85 lines after months of use, and it stayed short because anyone who wanted to add a line had to say which one they were removing.

The mistake to avoid: dumping everything into the main file so "the agent knows everything". An overloaded file does not solve the degradation of long sessions, it brings it forward. It is the same mistake people make with a project CLAUDE.md, and the fix is the same: a short index, with the detail loading when it is needed.

Step 3: extract the first facts instead of writing them

Now open the three artefacts and fill in three files under company/.

The field nobody writes and that is worth more than the rest sits in icp.md: who we turn down, and why. Every entry there is a project that will not burn three months.

Every file of facts carries a frontmatter with its verification date:

---
owner: gaetano
verified_on: 2026-08-06
review_every: 90d
status: current
ring: 1
confidential: false
---

It does one precise job: once that date passes, the content goes back to being a hypothesis to check, not a truth to build a proposal on.

One safeguard that saved us: mark as unconfirmed anything you inferred from past material that nobody has stated. A fact derived from three similar proposals is a probability, not a company rule.

Step 4: declare what loads and when

Here is the technical constraint that shapes everything else, and it has a name: context rot. Model performance drops as input length grows, even on simple tasks, and the drop starts well before the advertised window: Chroma's study of 14 July 2025 measures it across 18 models, including Claude 4, GPT-4.1 and Gemini 2.5 (Context Rot: How Increasing Input Tokens Impacts LLM Performance).

In practice: loading all your knowledge into every session is not just impossible on token budget, it actively makes the answers worse.

The answer is rings, declared in MANIFEST.yaml:

  - path: company/pricing.md
    ring: 1
    confidential: true
    never_in: [public content, output to third parties]
    load_when: [proposal, quote, discount, negotiation, budget]

• Ring 0: always in context. One file fits here, maybe two.
• Ring 1: loads on demand, based on the work in progress. Pricing when you write a proposal, editorial strategy when you write an article. Never together.
• Ring 2: never loads, gets searched when needed.

The rule of thumb: a file earns ring 1 only if it is needed more than once a month.

The load_when field is not decoration: it is what lets an agent decide what to read by consulting a contract, instead of digging through folders.

Step 5: wire it to the assistant

The brain lives in its own repository, and projects attach it as a submodule:

cd <working-repo>
git submodule add <url-of-your-brain> brain
git commit -m "chore: attach the company brain"

Then one line in the project instruction file:

# CLAUDE.md

## Company Brain
@brain/CORE.md

## Project architecture
[whatever is true only for this codebase]

From that moment every session starts knowing the company.

One criterion keeps the two apart: if something serves a single project it stays in CLAUDE.md, if it serves the company it goes into the brain. It is precisely the rule that prevents the problem this whole thing came from: the same knowledge copied into four places that then drift apart.

Remember to exclude brain/ from your deploys. It is knowledge, not code to publish.

Step 6: stop it from rotting

This is what separates a living brain from a folder of dead documents, and it is also the part almost everyone skips.

Two commands:

node validators/brand-lint.mjs company/identity.md   # how it is written
node validators/freshness.mjs                        # what expired

And above all, the linter attached to your commits, so violations never get in:

# .git/hooks/pre-commit
#!/bin/sh
git diff --cached -U0 | node validators/brand-lint.mjs --diff

The --diff mode reads a unified diff from stdin and looks only at added lines, reconstructing file names and line numbers from the +++ and @@ headers. That detail is what makes the linter adoptable on a repository that already has thousands of lines in it: existing debt is never charged to whoever touches the file today.

Both scripts exit 1 when they find something blocking, so they drop into CI unchanged. For freshness, prefer a scheduled job over one on every push: a fact going stale is not a good reason to fail a build, it is a good reason to remind someone.

The rules live in a separate file, validators/rules.mjs, and they are meant to be replaced with yours. The ones in the template are a starting point, not a standard. The escape hatch for lines that necessarily contain a banned term is the brand-lint:ignore pragma, and fenced code blocks are skipped automatically.

The cultural rule matters more than the tooling: every correction you make to an agent's output is a fact missing from the brain, and it gets recorded immediately, not "later". If you correct the same thing three times, the agent is not the problem.

Why not RAG with a vector database?

It is the first objection I get, and it is a fair one: if the problem is giving a model knowledge, RAG has been around for years and it works.

The short answer: at this scale the bottleneck is not retrieval, it is determinism. A company brain is dozens of curated files, not tens of thousands of documents. The problem is not finding the right passage in a huge corpus, it is guaranteeing that the non-negotiable rules enter context always, and that pricing enters only when a proposal is being written. Semantic search gives you the probably-right document. A routing contract gives you the declared one.

The row that matters most is review: a wrong fact in a markdown file shows up in a diff and gets fixed in a pull request. A wrong fact inside an embedding is invisible.

The two are not mutually exclusive. The day you need to query ten years of technical documentation or your ticket archive, RAG is the right answer and the brain is not involved. But for the knowledge that decides how a proposal gets written, a file you can read, diff and approve beats an index you have to rebuild.

What never goes in

Three things, and the third one surprises people.

Credentials. Never, not even temporarily. A brain describes where the secrets are kept, not what they are.

Client source documents. The proposal PDF does not go in: the knowledge derived from that proposal does. That is the difference between an archive that grows forever and a memory that stays usable.

Anything you have not verified. A brain full of hypotheses presented as facts is worse than an empty one, because nobody thinks to question them.

And the security point that outweighs the rest: the repository stays private. A brain is the most sensitive document set a company has, and unlike code it reads without any technical skill. Anyone who opens it understands in ten minutes who you sell to, at what price and at what margin.

How long it really takes

The first twenty useful lines: half a day, with the three artefacts open in front of you.

The rest does not happen in one sitting, and should not. You add one fact at a time, as it comes out of real work. Ours reached 88 files and nearly 70,000 words in a week, but only because it was extracted from 22 proposals and 63 articles that already existed: it was not written, it was collected.

How you know it is working

There is one test, and it takes two minutes.

Open a fresh session and ask the assistant to write something that requires knowing your company: a follow-up email to a typical client, a draft section of a proposal. Give it no extra instructions.

If the output is usable on the first attempt, it works. If you have to correct it, that correction is the next fact to record. Either way you learned something, which is why the test is worth repeating every so often.

Frequently asked questions

Do I need to know how to code? Not to write it, it is markdown in a folder. Technical skill helps to wire it to agents and to hook the validators to your commits, which is two commands. The part that really matters, deciding what is true and who confirms it, belongs to whoever runs the company.

Why not just use RAG? Because at this scale the problem is not retrieval, it is determinism: a routing contract guarantees that certain rules always enter context and that pricing only enters when it is needed. And a wrong fact in markdown is visible in a diff, inside an embedding it is not. On large corpora and open-ended search RAG remains the right answer, and the two coexist.

Can I use it with an assistant other than Claude? Yes. The brain is markdown in a folder, so anything that reads files can consume it. Only the wiring changes: where Claude Code imports CORE.md from the instruction file, elsewhere you point the assistant at the folder and tell it to read CORE.md first and MANIFEST.yaml after.

What does it cost to maintain? Little, provided the updating happens inside the work rather than next to it. The real cost is not time, it is the discipline of recording a correction at the moment you make it.

What if the company is small? That is where it pays off most, because almost all the knowledge sits in one person's head. A brain is how you get it out without stopping to write a manual.

Where you start today

Open the template, press Use this template, create the private repository and write the first twenty lines of CORE.md. Thirty minutes, and the quality of what an assistant produces for you already changes.

If you try it, opening an issue on the repository to say what you kept, what you threw away and where it broke is the most useful thing you can do: that template comes from one company's practice, and every report from a different context is the only way it stops being that.

Is your company using AI and still getting generic results? Want the brain built with you, on your real artefacts?

That is exactly what we do in a free pre-assessment: we look at where your company knowledge lives today, which documents count as raw material, and we come out with the first ring already written.