Every consulting practice runs on accumulated judgement: which pattern applied where, what was decided and why, which fix survived contact with a second client. The standard prescription is a second brain, and the personal-knowledge-management shelf is full of apps, templates and capture rituals for keeping one. I kept one for years the usual way. It grew, and it was write-only memory: notes went in, and at the moment of use, when a decision actually needed the context, nothing came back out.
The version that finally works inverts one design decision. A second brain is normally built for its owner to operate: you file, you tag, you maintain, you retrieve. Mine is built to be operated by AI agents, and that choice drives everything else: the medium (plain markdown in a private git repository), the structure (one idea per file, conventions a script can verify), and the maintenance (named rituals an agent runs, with a human yes or no at every decision point).
What follows is the system as it runs today underneath this consultancy, ending, in the house tradition, with the parts I deliberately did not build.
Why second brains die
The failure mode of a second brain is almost never capture. Capture is the enjoyable part, and every tool optimises it: clippers, quick-add hotkeys, read-later queues. The failure lives downstream, at retrieval and maintenance. The note you filed in March does not resurface in September when it would have changed a decision, because resurfacing was always your job. Nobody prunes, so the archive silts up. Within a year the collection is too big to trust and too stale to search, and the honest name for what you are keeping is a museum.
Diagnosed that way, the fix was never a better app, because any medium can hold notes. The scarce input is a librarian: something that files consistently, links new material to what already exists, prunes what has been superseded, and brings the right context to the moment of use. That role has always fallen to the owner, which is why the systems decay. Agents change that arithmetic. A model with access to a repository of plain text is a tireless, cheap, adequately careful librarian, and once one of those exists, the design question flips from "which app do I enjoy writing in" to "which format can a machine read, edit and verify".
The one rule of admission
One admission rule keeps the corpus worth searching: something enters the brain only if it has cross-context value, or if a future decision will need it. Everything else stays in the tool where it was born. The brain sits on top of the systems of record (email, Slack, Notion, the client repos, the ad platforms) and does not duplicate them. It holds the layer of meaning: the conclusion goes in ("chose server-side tagging over rebuilding the pixel setup for this client, because of the consent profile"), dated, linked back to where the raw material lives.
Mirroring is the rule most collections break, because it feels like diligence. It is deferral: it moves the filtering from now, when you have the context to judge what mattered, to later, when you will not, and it bloats the corpus every ritual has to search. Distil at write time. A note that costs nothing to write is usually worth nothing to keep.
Don't mirror a tool into the brain, ever. A synced copy of your inbox is not knowledge; it is the same backlog with worse search. If an entry does not record a conclusion somebody reached, it has not earned a file.
Markdown in git, not an app
The medium is plain markdown files in a private git repository, and every part of that sentence is load-bearing. Markdown, because every agent can read and write it with no API, no export step and no vendor's permission. Files, because one idea per file makes each note individually addressable, diffable and movable. Git, because history comes free, every agent edit arrives as a reviewable diff before it becomes permanent, and the private remote doubles as the off-site backup.
An app can sit on top; it just cannot be the system. I run Obsidian as a view: it renders the link graph, and its own sync service puts a readable copy of the vault on my phone. It reads the files, never the reverse. One sharp edge: never place a git repository inside a file-syncing folder (iCloud, Drive and friends), because file-level sync fights git over its internals and eventually corrupts the history. Obsidian's sync works inside the vault and leaves git alone, which is the only reason it is allowed.
Redundancy is the boring 3-2-1 kind: local copy, private remote, the sync service's encrypted copy as a bonus. A second brain is close to free to run; what it costs is discipline, and discipline is the part the rest of this article delegates.
Structure a machine can verify
The folder tree is nine numbered regions, work at the top, life below: an inbox where capture lands, the business itself, one folder per client, the methods library, then investing, personal, health and finance, with an archive that keeps the live regions lean. The numbering is for sort order and nothing deeper. The structure that matters is finer-grained, and all of it exists so a machine can navigate and check it.
- One idea per file, one name per idea. Every filename is globally unique across the repo, and links are written against the bare filename. A note can move between folders for the rest of its life without a single link breaking.
- Folder indexes are named notes, not READMEs. Each folder's hub is a note carrying the folder's own name, so the link graph renders as a legible tree rather than a wall of 40 identical README nodes.
- Frontmatter on every substantive note. Type, status, client or method, stack, source. This is the query layer: "which clients run BigQuery", "which methods are still draft" and "what changed this quarter" are one grep each, not an afternoon of opening files.
- Provenance is typed, not prose. A method note lists the clients it was distilled from as structured links; a published article points back at its method. The lineage from client work to public article is a chain of references a script can walk.
--- type: method status: stable # draft | stable | published origin: ["[[client-a]]"] # distilled from · internal only services: [S04] published_as: null # Labs URL once public tags: [bigquery, ingestion, reconciliation] ---
None of it is decoration: naming discipline lets an agent refile without breakage, frontmatter answers cross-client questions from structured fields, and a validation script catches the drift. Structure an agent cannot verify is interior design.
The rituals are the system
Maintenance is delegated to a small set of named rituals, implemented as agent skills that can be invoked from any working session on the machine. Each has a trigger phrase, a bounded job and a defined stopping point; each proposes, and I approve. The naming matters more than it looks. A ritual with a name gets invoked rather than intended, and an agent handed a named, bounded job stays inside it.
| Ritual | Runs | The job |
|---|---|---|
| check | before work | loads the relevant context into the session: status, open items, recent decisions |
| commit | after work | distils what just happened into the right notes, with links back to source |
| dump | weekly | interviews me: open to-dos, the week per client, decisions made but never written down |
| drain | as captured | files quick captures, emailed from my phone with a subject prefix, into the inbox |
| defrag | occasionally | finds near-duplicates and superseded notes, proposes merges, applies what I approve |
| map | on demand | renders the link graph and reports health: orphans, dangling links, stale hubs |
Two of these do disproportionate work. The weekly interview keeps the record true, because the biggest hole in any knowledge base is the decision made on a call and never written down; a recurring agent that asks direct questions ("what did you decide about X, it is not in the log") is the cheapest fix I have found. And every writing session ends with one close command that validates the graph, regenerates the hub indexes, and commits only the files the session names. That last clause is learned caution: with several agent sessions sharing one working tree, a bulk stage once swept a parallel session's half-finished note into an unrelated commit.
To make it concrete, here is the most recent thing that travelled the whole loop. A recurring engagement question, "is this site technically sound, and what should we fix first", kept producing the same working checklist, and each session's conclusions were filed to the relevant client folder by the commit ritual. Once the pattern had clearly outgrown any single client, it was promoted: generalised into a method note with a small crawler script attached, client references stripped, leak-check passed, my yes at the gate. That method later earned the final promotion too, shipping as an open-source audit tool with its own article. Nothing in that chain depended on me remembering where the first version lived.
The division of labour never varies: agents file, link, propose and prune; I decide. It is the same conclusion conversational analytics over a warehouse arrives at: a model is only as trustworthy as the context and checks around it.
A boundary you can enforce
A consultant's second brain has a problem a personal one does not: the most valuable material in it is confidential. Client folders hold real names and real numbers; the methods library and everything downstream must hold none of that. Care at write time would eventually fail, so the boundary is mechanical.
- Direction. Client-identifying detail may exist only inside the client regions. The methods library is client-stripped by definition; promotion means generalising, never copying.
- A leak-check on every close. The validation script greps every method note against every client identifier the frontmatter knows about: slugs, brand aliases, project names. A hit fails the commit; the same pass catches dangling links, duplicate filenames and missing frontmatter.
- One sanctioned crossing. A method may cite its source clients in structured frontmatter, because a typed link renders as a graph edge without the name appearing in any shareable prose.
- History counts. Stripping a name from a note cleans the current version; it survives in the git log. So a method leaves the brain by copying the file out, and the repo itself, history included, is never shared.
Secrets (keys, tokens, credentials) never enter the repo at all. The leak-check exists for the softer material that reads like ordinary prose and identifies a client anyway.
The pipeline is the point
Everything above is plumbing. The reason to run it is a one-way promotion pipeline that compounds knowledge upward, and it is the part I would rebuild first if I lost the rest. Client work generates the raw material; patterns that prove themselves again are generalised into the methods library as runbooks the next engagement can execute; the methods worth showing publicly are promoted once more, into the articles on this index. Labs is the public tier of that pipeline, and a solo practice does not scale by hours; it scales by how much method survives from one engagement to the next.
Each promotion is deliberate. The agent proposes ("this pattern has now appeared twice; candidate for the library"), the leak-check gates the crossing, and I make the call. Travel is one-way: client detail never flows upward, while provenance links point back down, so every published method remembers where it was proven without saying so in public.
Even the editorial layer lives in the repo: the skill that writes these articles carries the house voice rules, the SEO checks and the signoff guardrails for case studies about real engagements, so publishing standards are versioned rather than remembered. In the interest of honest reporting: the methods library was seeded by backfilling articles already published here, and only the newest pieces have travelled the full pipeline. The tiers are real; the flywheel is young.
What I deliberately didn't build
Most of what makes this system dependable is what it refuses to do. What I skipped, and why the omissions are design choices rather than backlog:
- No automatic ingestion. No mirroring email, Slack or calendars on a schedule; that is the classic failure mode with better tooling. A pass that proposes distilled candidates may come later. Wholesale mirroring never will.
- No plugin stack or tag taxonomy. Frontmatter carries the schema, grep answers the queries, and taxonomy design is procrastination wearing a folder structure.
- No vector database. Megabytes of distilled text search instantly, and a grep hit is verifiable in a way an embedding match is not. For the same reason, an agent never loads the vault into context wholesale: it enters through the folder-note hubs, greps filenames, frontmatter and text to locate candidates, and reads only the handful of notes that match. If the corpus outgrows that, retrieval joins the rituals rather than replacing them.
- No unsupervised writes. The archive stays trustworthy precisely because approval is the write path.
- No multi-user brain. This is one practitioner's judgement, versioned. Sharing the repo would change the confidentiality model entirely.
Everything above, as the build order:
- One admission rule: cross-context value or decision-relevance, or it stays in the source tool.
- Plain markdown in a private git repo. One idea per file, globally unique filenames, links against bare filenames. Any app is a view; git is the record.
- Frontmatter on every note, provenance as typed links, and a validation script that checks all of it.
- Named rituals with bounded jobs: load context, distil sessions, interview weekly, drain capture, defrag occasionally. Agents propose; you approve.
- One close command: validate, regenerate indexes, commit only what the session names.
- A mechanical leak-check between client material and anything shareable, with git history treated as part of the secret.
- A one-way promotion pipeline: client work, then generalised method, then published article.
A second brain built for agents is a different artefact from a notes app with ambitions: an assistant that once started every session knowing nothing now starts knowing everything already learned, decided and rejected, with the receipts one link away. The notes were never the point. The point is that the next engagement starts with everything the previous ones taught, what worked, what failed and why. Keeping that true is finally somebody's actual job. It just no longer has to be mine.
