Building COSMOS: A Front End for the Second Brain
I have spent two years arguing that you should build knowledge instead of documents. I have the posts to prove it, a second brain in Git to live by it, and Atlas reading the whole corpus back to me on demand. The philosophy was settled. The plumbing worked. And yet, most evenings, building a piece of that knowledge still meant the same thing it always had: a blank Markdown file, a blinking cursor, and the whole journey from raw capture to something publishable resting entirely on my own discipline.
That is the gap COSMOS exists to close. The second brain had a memory and a voice. What it never had was a front door — a place to actually do the work of turning a heap of captured fragments into a finished, durable note. So I built one. COSMOS — Content Organisation, Semantic Memory & Operational System, because every project of mine apparently needs a self-important acronym — is a self-hosted studio for exactly that journey. It is the hardest single thing I have built for this site, and I am prouder of it than I have any right to be.
A blank page is where good notes go to stall. I got tired of mine stalling, so I built the workbench I wished I had.
What COSMOS actually is
COSMOS is a small web application you run yourself, in Docker, alongside everything else in the homelab. You open it in a browser and it gives you a single, opinionated pipeline that takes a thought from “I scribbled this at 11pm” all the way to “this is live on the site and the knowledge base is richer for it.”
The shape of that pipeline is the whole point, so here it is end to end:
You capture raw material into an inbox — a pasted note, a saved link, an uploaded Markdown file — with no decisions required, because friction at the moment of capture is what kills every system like this. You point an AI writer at that material and it produces a first draft. A second model then reviews the draft critically, across multiple quality dimensions, the way a good editor would. The work gets scored — how original is this, how much does it overlap with things I already know, how confident should I be in it. You revise, with every version kept and restorable. And only when a human — me — clicks approve does anything get published, copied as a clean Markdown page bundle straight into this site’s Hugo content.
Nothing is automatic that should not be. COSMOS never publishes on its own and it never touches Git for me; it surfaces the exact command and lets me run it. The machine drafts, critiques and scores. The judgement stays mine.
Taming the mountain
The phrase I kept coming back to while building it was mountains of information. That is genuinely what the raw material is. Years of daily notes, half-finished thoughts, links I meant to read, transcripts, error messages and their fixes. The problem was never a shortage of input. It was that the input sat in a heap, and turning a heap into knowledge is slow, deliberate work that I kept not doing because the activation energy was too high.
COSMOS lowers that activation energy at every step. The inbox means capture costs nothing. The drafting means I start from a critiqued first pass instead of a blank page. The scoring means I can see, before I sink an evening into a piece, whether it is actually new or whether I am about to rewrite something I already said better eighteen months ago. The mountain stops being intimidating because the tool is built to climb it one switchback at a time, and to remember every step so the next climb is shorter.
That last part matters more than any single feature, and it is the same compounding argument I have made before: the work accumulates instead of evaporating. Every note that goes through COSMOS makes the next one faster, because the next one is partly assembled from notes that already exist, already corrected, already scored.
Knowledge that knows itself
The piece I am most quietly pleased with is the knowledge engine, because it is the bit that turns a publishing tool into something closer to a brain.
COSMOS embeds your entire Markdown corpus — this site’s content, plus everything it has published — into a local vector index. From that, it does the things a filing cabinet cannot. Semantic search, so I can ask for a concept and get the passages that mean it rather than the ones that happen to share a keyword. Related-article detection while I draft, so I am nudged toward the links I would otherwise forget to make. Duplicate and heavy-overlap warnings, so I stop accidentally re-deriving the Citrix sizing rationale for the fourth time. A similarity graph over the whole base, so the structure of my own thinking becomes something I can actually see. And a retrieval-augmented pass that reads a new draft against the existing corpus and tells me where it contradicts something I have already published, or leans on a reference I never wrote.
I built the vector maths in plain Python with no heavyweight numerical dependencies, because at personal scale — tens of documents, hundreds of chunks — a careful dot product is more than fast enough, and I would rather own a hundred lines I understand than inherit a framework I do not. The on-disk Markdown is canonical; the index is disposable and rebuildable from scratch. That is the same principle as everything else I build: the plain text is the asset, and every clever layer on top of it has to be willing to be deleted and regenerated without losing anything that matters.
The boring stack, on purpose
The architecture is deliberately unfashionable, and that is a feature. FastAPI on the back. HTMX and Jinja templates on the front, which means there is no Node build, no bundler, no thousand-dependency front-end toolchain quietly rotting — just HTML the server renders and swaps. SQLite for workflow state. A thin provider layer so the AI backend is swappable: local models on Ollama when I want privacy and zero marginal cost, an OpenAI-compatible endpoint or Anthropic when I want more power, and different providers for writing, reviewing and embeddings if I feel like mixing them.
FastAPI · HTMX + Jinja · SQLite · Markdown on disk
│
Provider layer
Ollama · OpenAI-compatible · Anthropic
Every layer is replaceable and the value lives in the bottom one. The models can change. The provider can change. The whole application could be thrown away tomorrow and the knowledge would be entirely intact, because it was never in COSMOS — it was always plain Markdown in Git, and COSMOS is just the best front door I have ever had to it. That is the same conviction that took this site off a platform and onto Hugo and Git, applied one layer up.
What it cost, honestly
I would be lying if I made this sound clean. It was not. It was weeks of evenings, more rewrites than I would like to admit, and a long tail of the unglamorous, fiddly problems that never make it into the architecture diagram.
The pipeline looks obvious in hindsight and was anything but while I was building it. Getting a second model to critique a first model’s output usefully — specific, grounded, not just a flattering paragraph of “this is great, here are three vague suggestions” — took a dozen passes at the prompts alone. The scoring had to be honest enough to tell me my draft was derivative, which meant resisting the temptation to build a tool that always told me I was clever. The publishing path had to be genuinely safe: never overwrite, never escape the content directory, handle image-bearing posts as proper page bundles, set the front matter correctly every time, because a publishing tool you cannot trust is worse than no tool at all. And the knowledge engine went through three shapes before I had one that returned results I actually believed.
None of that is hard in the way that sounds impressive at a conference. It is hard in the way real software is hard — a hundred small correct decisions, each boring on its own, that collectively decide whether the thing is a toy or something you reach for every day. I got plenty of them wrong first. I am sure some are still wrong. But it works now, it works well, and the version of me that started this with a vague idea and a blank repository would not quite believe how far it got. This is also exactly the failure mode I warned about in why most AI projects fail: the demo is easy and the last ten percent is the whole job. I tried very hard to do the last ten percent.
Why I am proud of it
I do not say that easily, because pride is usually the noise you make right before something breaks. But I have used COSMOS to build real notes that are live on this site now, and the experience is the one I had been chasing for two years. The blank page is gone. The mountain of raw material has a path up it. The knowledge I build today genuinely makes tomorrow’s faster, and I can see it happening in the graph and the scores.
It is the front end the second brain was always missing. Atlas gave the corpus a voice; COSMOS gives it a workbench. Between them, the loop I have been describing across half this site — capture, build, connect, retrieve, act — is finally a loop I can stand inside rather than one I have to hold together by hand.
Come and break it
Here is the part I am slightly nervous about: COSMOS is open source, and you can run it yourself right now.
It is a docker compose pull && docker compose up -d away from running on your own machine, on your own models, against your own Markdown — nothing leaves your network if you point it at a local model. There is a setup guide in the repo. Bring an existing site and it will index your back catalogue and let you import your published posts as a starting point. Bring nothing and start from an empty inbox.
What I would genuinely love is feedback. Tell me where the pipeline feels wrong. Tell me the prompt that produced a rubbish review. Open an issue when it breaks, because it will, and I would much rather hear about it than not. If you build something on top of it, or rip a piece out for your own setup, even better — that is the whole point of putting it in the open. I have spent a long time on this thing in private; I am ready for it to meet some people who did not build it and have no reason to be gentle.
The thing I keep relearning
Every project on this site ends up teaching me the same lesson in a new accent, and COSMOS is no exception. The tool is not the asset. The Markdown is the asset, and it always was. What COSMOS changes is not what I own but how cheaply I can turn what I capture into what I keep — and lowering that cost, it turns out, is the difference between a knowledge base that compounds and one that quietly stalls at the blank page like mine used to.
I built a memory. I built a voice. This year I finally built the front door, and I worked harder on it than on anything else here. It is open now, and the door is unlocked. Come in and have a look around.