The brain that compounds

One root file, read first, every time

Lesson one gave you a repo that answers questions. This lesson is how a brain stays useful after a year of builds, taken from how we run our own: one repo holding every system we have shipped plus who we are and how we work. Its first rule is written at the top of the root CLAUDE.md: this is the file to read first, every session, and it is the only file we maintain by hand. Everything else self-describes.

• Who we are and who we build for, as a ranked list of customer types with an explicit "not for" line. Agents that know who you are not for stop proposing the wrong work.
• The default stack as a dated snapshot, with permission to bump it. Defaults are living; history is dated.
• How we engineer: the bar, the think-then-build habit, push back before implementing, verify before claiming done.
• How the repo is organized: one folder per build under clients/, our own systems under internal/, each with its own CLAUDE.md header so nothing central needs updating when a folder is added.
• The hard rules (below), then a pointer to the deep reference: playbooks, settled decisions, case files.

The current-best list: pick by dimension, not by project

The highest-leverage table in our brain is a "current best" list: one row per dimension, each pointing at the single folder that does that thing best today, with the reason in one sentence. Dimensions, not projects, because your newest build is rarely best at everything: the cleanest code may live in one repo, the best deploy setup in another, the best client-facing document in a third. Picking by dimension means you never inherit an outdated version of something just because it sat next to the part you wanted.

## Current best - copy from these (the one hand-maintained list)

| Dimension | Best example | Why |
|---|---|---|
| Cleanest code | clients/kb-north | Intent docstrings, typed boundaries, graceful degradation |
| Outbound pipeline | clients/agency-b | Ingest -> qualify -> enrich -> send, dedup + cost caps |
| LLM cost engineering | internal/outbound | Profile compaction + prompt caching + token accounting |
| Backend resilience / jobs | clients/ops-c | SKIP LOCKED scheduler, retry + dead-letter |
| Deploy setup | clients/agency-b | Procfile/runtime + root-dir convention |
| Client-facing one-pager | clients/docs-d | One renderer, many clients; judgment in a content dict |
| Verifying a list before a client sees it | clients/docs-d | Four passes ending in an adversarial audit |

_Update a row when a newer build does it better. That's the whole maintenance habit._

1. Starting a new build: read the root file, then find the nearest neighbor by skimming the CLAUDE.md headers across your project folders. Use the current-best list to pick the good example, not just any example.
2. Open that folder and replicate the working pieces (pipeline shape, integrations, structure). Adjust for the new case. Do not rewrite what already works.
3. Read the matching playbook for the type of thing you are building and any settled decision that applies ("we use X for search; here is why"), so the question is not re-litigated.
4. Finish by giving the new folder its own CLAUDE.md header. If it raised the bar on any dimension, update that one row. Five minutes per project is what makes the brain compound.

Playbooks, decisions, and the files that hold your judgment

Below the root sit the folders that hold judgment rather than facts. Ours look like this; the names matter less than the split.

• playbooks/: how we build each type of thing (outbound engine, inbound reply handling, knowledge base, client-facing document), distilled across projects. Each lists the standard shape, the projects that did it, and the gotchas.
• stack/decisions/: settled calls with the reasoning, so a new session does not spend an hour re-deciding what was decided in March.
• reference/positioning.md: ICP, messaging, one-liners. The file every outbound and content skill reads before it writes a word.
• Voice as a file: a voice model with gold examples, banned patterns, and a capture loop that files what you actually posted or sent as the next anchor. Skills import it, so every draft sounds like you instead of like a model.
• raw/calls/: every sales-call transcript imported as Markdown with a short summary heading (ours holds about 300). Mined by a skill for objections, buyer language, and what prospects ask for, with findings grounded in specific calls.
• projects/: one case file per finished build: stack, what to reuse, what went wrong.

Auto-memory: one fact per file, plus an index

Claude Code's auto memory persists notes across sessions; the first 200 lines or 25KB of the index load automatically. The pattern that has held up for us: an index file with one line per note (link plus the one-sentence lesson), and one file per fact. Not a journal. Each note says what happened, why it happened, and how to apply it next time. Examples from ours, anonymized: "never send to a prospect without approval: a bare send flag once sent 14 unapproved replies"; "a key being available is not permission to spend it"; "silent 100% failure reads as success" (module three takes that one apart).

• One fact per file. A file that holds three lessons gets cited for none of them.
• Group the index by topic (rules and taste, secrets and infra, providers, clients) so the 200 lines that load are the map, not the territory.
• Write the failure and the date, not the mood. "On the 23rd, 14 unapproved replies went out because --send had no confirmation" beats "be careful with sending."
• Dated status lines expire. A note saying "decision expected next week" is a question the next time it is read, not a fact. Rewrite it when the decision lands.
• Promote: when a memory note is cited three times, it belongs in a skill or in the root hard rules, where it is enforced rather than remembered.

Search: hybrid, local, wrapped in a skill

The 100K-token math from lesson one holds until it does not. When grep starts missing things you know are in there (paraphrases across hundreds of call transcripts, mostly), you still do not need a hosted vector database. Our brain runs a local hybrid search: BM25 keyword scoring plus local vector embeddings from an open embeddings library, the two score lists min-max normalized and fused, over every Markdown file in the brain. No API call, re-index in seconds, and the transcripts never leave the machine.

---
name: brain-search
description: Search the company brain (playbooks, case files,
  call transcripts, founder profile) with local hybrid search.
  Trigger whenever recalling something from the brain would help:
  "what did we learn about X", "find the call with ...", or before
  answering from memory about past work, clients, or calls.
  Prefer this over blind grep.
---

From the brain root:

    brain-search/brain-search search "your question" -k 6

Returns the top chunks (BM25 + vector, fused and ranked), each with
file path, heading, and snippet. Open the cited files, then answer
grounded in them. After adding or editing content, rebuild:

    brain-search/brain-search index

• Hybrid, because the two halves fail differently: keywords catch names, numbers, and product terms; vectors catch "the call where they worried about lock-in" when nobody said lock-in.
• Local, because the corpus is your calls and your clients. A search that ships transcripts to a third party to answer "what did we promise them" is a data-handling decision, not a convenience.
• Wrapped in a skill, because a search nobody invokes is a search that does not exist. The description tells Claude to run it before answering from memory.
• Re-index is part of the capture habit: import the call, write the summary, rebuild. Ask Claude Code to build the tool itself; the pattern matters more than the code.

Skills every project inherits, and the hard rules

The next lesson teaches you to write skills. Here is where they live once written: in the brain, under a foundation folder, installed into every new project's .claude/skills/ by one install script. Ours ships eight doctrine skills (engineering standard, building agents, subagents and context, self-verify and debug, retrieval, backend conventions, styling standard, ship-to-own) plus a spend policy, and the same script lays down curated vendor skills pulled from source: Anthropic's skill-creator, mcp-builder, and the document skills. The installer overwrites only the managed skills, never a project's own, so it is safe to re-run. Improve a skill once in the brain and every project picks it up on its next install.

Then the hard rules, at the bottom of the root file where every session reads them. Ours, generalized:

• Never commit secrets. Keys live in a gitignored .env or the deploy platform's variables tab. A local pre-commit scan in .githooks/ blocks any commit containing one; enable it once per clone with git config core.hooksPath .githooks.
• A key being available is not permission to spend it. Shared secrets auto-load into every shell, so every paid key is always just there. Before any run that costs money, either the owner asked for that run or you ask, stating per-unit cost times unit count.
• Never print a secret's value. Check presence and length (${VAR:+set}), never echo the variable. A key printed into a log or transcript is a key to rotate.
• Commit and push only the project you were asked to work on. A monorepo working tree is usually dirty across several folders; stage explicit paths, never git add -A, and check git status --short <project>/ before committing.
• Self-describe on finish. Every folder ends with a CLAUDE.md header, so the brain stays self-indexing as it grows.

Do this now

Sources and further reading

• Claude Code memory docs (CLAUDE.md, auto memory, imports)
• Claude Code skills docs
• Anthropic's official skills repo (skill-creator, document skills)