Knowledge as files

Why files beat a vector database at your size

The deliverable here is a brain repo that answers real company questions - "who owns the Acme account?" - with the right file cited. The mechanism is a simple idea: put your company's knowledge in plain markdown files, in one git repo, and let Claude Code read, search, and edit those files directly. No embeddings, no vector database, no retrieval pipeline to babysit.

The alternatives each have a place. Claude for Work projects suit people who chat but do not build. Notion AI is fine if you live entirely in Notion and only need search. Glean wins at 200+ people with strict per-document permissions. But none of them keep the knowledge versioned and ownable in git - the diff history, the review gate, and the portability that everything later in this track builds on.

The line to remember: files + git + Claude Code when knowledge must be owned, versioned, and acted on. RAG products when knowledge must only be found. The two compose - even Glean ships official Claude Code plugins, so Glean shops still use files as the action layer.

This is not theory. Anthropic's own report on internal use describes a one-person growth marketing team, the legal team, and finance staff all running this pattern - describing what they need in plain language and getting working output, with no engineering background.

The reference architecture

Here is the repo structure we deploy with clients. Copy it as-is, then prune what you do not need.

company-brain/
├── CLAUDE.md                  # <200 lines: who we are, what we sell,
│                              #   where everything lives, hard rules
├── .claude/
│   ├── settings.json          # shared permissions (deny .env reads,
│   │                          #   deny finance writes, allow read tools)
│   ├── rules/
│   │   ├── tone-of-voice.md   # paths: ["content/**"]
│   │   ├── finance.md         # paths: ["finance/**"]
│   │   └── client-privacy.md
│   └── skills/                # the SOP library (next lesson)
├── company/
│   ├── positioning.md         # ICP, messaging, one-liners
│   ├── org-chart.md           # who owns what (routing knowledge)
│   ├── pricing.md
│   └── policies/              # PTO, expenses, security policy
├── playbooks/                 # how we do each type of work
├── clients/
│   └── acme/
│       ├── CLAUDE.md          # who, deal, status, links
│       ├── meetings/          # dated: 2026-06-09_kickoff.md
│       ├── deliverables/
│       └── _intake/           # raw dumps awaiting processing
├── meetings/                  # internal meeting notes, dated
├── reports/                   # generated reports (output + history)
├── templates/                 # proposal.md, sow.md, invoice.html
├── scripts/                   # small utilities Claude wrote & reuses
└── .githooks/                 # pre-commit secret scan

• ISO dates in filenames (2026-06-09_kickoff.md) so files sort chronologically and Claude can filter "this week" with a glob.
• One folder per entity - client, project, department - each with its own short CLAUDE.md header, so the repo indexes itself.
• An _intake/ folder in each client directory: the convention for "raw stuff Claude should process and file."
• reports/ holds generated output, which doubles as history - last week's report is the diff baseline for this week's.

The CLAUDE.md index: facts, not procedures

The root CLAUDE.md is the one file Claude loads every session. It answers: who are we, what do we sell, where does everything live, what are the hard rules. That is it.

• Keep the root CLAUDE.md under 200 lines. Past that, quality drops and you start paying for context you rarely use.
• Use @path/to/file imports (max 4 hops) to compose the root index from department files.
• Put scope-specific facts in .claude/rules/*.md with a paths: frontmatter glob - tone-of-voice.md loads only when someone works in content/, finance.md only in finance/.
• Subfolder CLAUDE.md files lazy-load when Claude reads files there - this is what makes per-client folders self-describing without bloating every session.
• HTML comments are stripped before Claude sees the file - free space for maintainer notes.
• If another tool on your team already reads an AGENTS.md, Claude Code reads it natively when no CLAUDE.md exists (since v2.1.277, September 2026). When both exist only CLAUDE.md loads, so import AGENTS.md from it rather than keeping two indexes.
• Two audits keep it honest: /doctor proposes trims when the file has grown, and /doctor prompt-audit flags instructions written for older models that the current ones no longer need.

Scaffold your brain repo

Do this now, on your real company. Thirty minutes of typing, and every later lesson builds on it.

1. Create the repo: make a company-brain folder, run git init inside it, and create the folder tree from this lesson (company/, playbooks/, clients/, meetings/, reports/, templates/, scripts/, .claude/skills/, .claude/rules/).
2. Open Claude Code in the repo root and run /init - it drafts a starting CLAUDE.md from what it sees. Edit it down to facts only: who you are, what you sell, where things live, three to five hard rules.
3. Write company/positioning.md (your ICP and messaging), company/org-chart.md (every person, what they own, their email), and company/pricing.md. These three files power half the later automations.
4. Pick one real client or project. Create clients/<name>/ with a five-line CLAUDE.md header (who, deal size, status, key links) and a _intake/ folder. Drop two or three real documents in.
5. Add a .gitignore with .env, *token*.json, and credentials.json before anything else goes in. Secrets never enter this repo.
6. Commit. Then test it: ask Claude "what is our refund policy?" and "who owns the Acme account?" - questions it can only answer from your files. If it answers with the right file cited, the brain works.

That last step is recipe one of this whole track: ask the brain. No connections, no skills, no automation - just files and questions. It is also rung one of the ladder every later lesson climbs: chat once, find or build a skill, put it on a schedule, grow it into an agent. If rung one feels useful on day one, everything after it compounds.

What stays out

A brain that holds everything holds too much. Four categories never enter the repo - and deciding this on day one is far cheaper than scrubbing history later.

• Secrets: API keys, OAuth files, credentials of any kind. They live in a gitignored .env or the platform's variables tab, never in markdown, never in CLAUDE.md.
• Anything legally sensitive at rest: candidate personal data, medical info, payroll detail. The brain is widely readable by design - keep regulated data in the system built to hold it.
• Stale duplicates: if the canonical version lives in your billing tool or CRM, link to it instead of copying it. Copies rot.
• Giant binaries: recordings and large decks stay in Drive; the brain holds the transcript or the markdown summary plus a link.

Do this now

Sources and further reading

• Claude Code memory docs (CLAUDE.md hierarchy)
• How Anthropic teams use Claude Code
• The GTM repository pattern for Claude Code