This repo is a brain: one structured, git-versioned knowledge base that your AI agents read from for context, facts, and voice. Plain markdown, one idea per file, with a contract strict enough that agents can be trusted to retrieve from it — and to propose additions to it.
It is designed to be served by BrainOutside, which clones this repo and exposes it over REST + MCP with visibility tiers and a human-gated write path. It also works perfectly well on its own, read directly by Claude Code.
CLAUDE.md is the contract. Read it before anything else. Two skills in
.claude/skills/ are the only interfaces: mind-feeder writes (gated),
mind-reader reads.
- Use this template (the GitHub button) to create your copy — and make it private. This repo will hold your unpublished thinking; private is not optional.
- Clone it and open the folder in VS Code (or any editor) with Claude Code.
- Feed something: say "feed this into my brain" with a link, a
transcript, or just a raw thought.
mind-feederproposes 2–4 notes and stops — nothing is written until you approve. - Ask something: "using my brain, what's my take on …".
mind-readerpulls the right handful of files through a lens and answers in your voice.
That is the whole local loop — no server, no accounts, nothing beyond Claude Code. When you want the same brain served to every agent you run, over MCP and REST with visibility tiers enforced server-side, that's BrainOutside — and this repo is already the exact shape it clones.
- Write your identity core.
identity/core.md,identity/beliefs.mdandidentity/voice.mdship as placeholders with instructions inside. These get loaded on nearly every retrieval, so they matter more than any single note. Keep them short and specific — "I explain things by building the smallest working version first" beats "I am passionate about tech". - Edit the taxonomy in
CLAUDE.md§7 to your actual topics. The list there is an example. Short is better: ~15–25 tags. - Add one project card per thing you build, from
projects/_TEMPLATE.md. Deleteprojects/example-project.md. - Adjust the example lens in
lenses/, or delete it and write your own once you know what your agents keep asking for. - Feed your first source. A video, a blog post, a thread, or just a raw thought. The feeder proposes notes; you approve; it commits.
Optional: the skills and contract say "the owner" throughout. Search-replace that with your name if you'd rather the agents read it that way — it makes voice-grounded output slightly more consistent.
| Folder | What belongs |
|---|---|
identity/ |
Who you are, what you believe, how you write. 3 small files. |
projects/ |
One card per project: pitch, status, numbers, architecture, pointers. |
knowledge/takes/ |
Opinionated positions — "my angle on X". |
knowledge/stories/ |
Personal narratives with numbers, failures, outcomes. |
knowledge/lessons/ |
Transferable "what I learned building/testing X". |
knowledge/facts/ |
Stable, citable facts about your work and results. |
content-catalog/ |
Inventory of what you've already published, per platform. |
lenses/ |
Named retrieval scopes: topics + note types + a visibility ceiling. |
raw/ |
Full transcripts and source text. Linked from notes, never browsed. |
eval/ |
The falsification test — does the mind actually improve output? |
Supersede, never delete. When you change your mind, the old note stays
and gets marked superseded. Your brain becomes a record of how your
thinking moved, not just where it landed.
Nothing enters without your approval. Agents propose; you decide. A brain that fills itself with unreviewed extractions is a brain you stop trusting, and an untrusted brain is worse than no brain.
There are no example notes in knowledge/ — an empty brain that is truly
yours beats a seeded one you have to clean out. The _TEMPLATE.md files
show the shape; the app ignores them when indexing.
Run the eval in eval/ once you have ~10 notes. If retrieval doesn't
visibly improve your agents' output, fix the notes before adding more.
This design descends from Andrej Karpathy's llm-wiki idea — plain markdown that a coding agent compiles knowledge into, so the artifact compounds instead of being re-retrieved per query. The template adds what a wiki doesn't have: identity and voice as first-class files (so agents can write as you, not just recall), content-shaped note kinds, and a hard human gate on every write. And when you want this brain readable by every agent you run — not just the one on this machine — BrainOutside is its online head.
The scaffolding — the contract, the skills, the templates, the folder shape — is MIT. Everything you put into your copy is yours, obviously and entirely: the license governs the template, not your mind.
This repo is one thing I built with AI. The book is the system underneath it.
Vibe Engineering Blocks is my free 74-page book. 47 building blocks for shipping real apps with AI. One block per page, each with the exact prompt to hand your AI.
Built by Hasan Aboul Hasan. I build real products with AI and write down exactly how. Guides · YouTube · Community