BrainOutside

Your brain, kept outside your head — where your agents can read it.

A self-hosted memory server for your AI agents. One git repo full of markdown is your brain; BrainOutside serves it over REST and MCP, with visibility tiers enforced server-side and a human gate on every write.

Single-user and single-brain by design. That is the product, not a limitation waiting to be fixed.

Two ways to run a brain, one repo between them. Start local: clone brainoutside-template, open it in VS Code, and Claude Code is the whole interface — free, private, zero infrastructure. Or self-host this server as the brain's online head, so every agent you run anywhere can read your mind over MCP and REST. They compose: the local repo IS the repo the server clones. Start local today, add the server when you want it, migrate nothing. Site and docs: brainoutside.com.

Status: pre-release. The engine and the first-run wizard are built and verified end to end; what remains before the public beta is packaging, docs, and launch assets.

📖 Read the guide

The full walkthrough lives on my site: what a second brain is actually for, why plain markdown beats a vector database for personal knowledge, and how to go from an empty repo to a self-hosted brain your agents can read. How to Build an AI Second Brain

Free to read, no login.

Where this came from

This project grew out of Andrej Karpathy's llm-wiki and the wave of markdown knowledge bases around it. The core insight there is right, and it is the foundation this builds on: plain markdown plus a coding agent beats RAG for personal knowledge — compile knowledge in at ingestion time and the artifact compounds, instead of being re-assembled from chunks on every query.

Building mine, I kept hitting four walls, and they became this project:

• A wiki holds knowledge, not you. An agent could recall from mine, but it couldn't write as me — there was no identity, no voice, no beliefs in it. Here identity/ is first-class, and the note kinds (take, story, lesson, fact) are shaped for creating content, not just referencing it.
• No safe way to grow. A wiki that maintains itself fills up with unreviewed extractions, and a brain you don't trust is a brain you stop using. Here every write is gated: agents propose, you approve, approval is one signed commit.
• Recall isn't the point — creation is. I built this to make things from my brain — replies, posts, scripts — in my own voice. Lenses and context packs turn the brain into a writing instrument.
• A local folder serves one tool on one machine. I wanted every agent I run, anywhere, to read my mind. That is this server: the brain's online head — self-hosted, private, with visibility tiers enforced server-side.

The llm-wiki was not the only influence; if you recognize your project in this lineage and want a link here, open an issue.

The server itself grew out of my MCP API boilerplate — a Django starter that already had the REST + MCP plumbing, API keys and self-documenting endpoint pages wired up. That heritage is why you may occasionally find a feature the brain doesn't use; they get removed as they're found, and a report is welcome.

Why not just use a vector database

Because you cannot read one. Your brain here is plain markdown in a normal git repo:

• You can read it. Open it in any editor. git log it. Fix a note by editing a file.
• You can leave. It is your repo. Delete the server and the brain is still there, intact and useful.
• It has history. Change your mind and the old note is superseded, not deleted — so your brain records how your thinking moved, not just where it landed.

How it works

One repo is the brain. Atomic notes with a strict frontmatter contract: opinionated takes, storys with real numbers, lessons, citable facts. Every note carries provenance back to its source.

Agents read it through a lens. A lens is a named retrieval scope — topics, note types, and a visibility ceiling. Ask for a context pack and you get the right 3–7 files, not the whole repo.

Nothing enters without you. Feed a source — a video, a post, a transcript, a raw thought — and an agent proposes notes. You approve in a UI. Approval is one signed git commit. A brain that fills itself with unreviewed extractions is a brain you stop trusting.

Tiers are enforced, not decorative. Every note resolves to public, agents-only or private, and each API key sees only its tier — because the reader agent runs against a materialized snapshot of that tier and physically cannot read above it.

What you get

• REST + MCP — point Claude Code, or any MCP client, at your own mind
• A gated write path — proposals land in an approval queue; approval commits and pushes
• A chat test bench — talk to your brain at any tier, with the sources it used shown per message
• Visuals — visibility rings, a topic graph, live read activity, and a timeline of every position you have revised
• A full ledger — every token, every read, every SDK run

Requirements

Somewhere to run Docker (a VPS with Coolify, or docker compose on any box), a GitHub account, and a Claude credential — an Anthropic API key or a Claude subscription token (sk-ant-oat), so you can run this without API billing.

Getting started

The 10-minute path is docs/INSTALL.md: two environment variables, docker compose up, and the /setup wizard does the rest in the browser — account, brain repo from the template, deploy key, write credential, Claude credential, first build. No terminal after the compose command. On Coolify it is shorter still: docs/DEPLOY.md.

Your brain repo

Start from the brainoutside-template repo (developed in-tree at brain-template/): the contract, both agent skills, note templates and placeholder identity files. It ships with zero notes on purpose — an empty brain that is truly yours beats a seeded one you have to clean out.

Docs

docs/INSTALL.md	Installing: compose happy path, Coolify pointer, updating
docs/DEPLOY.md	The full Coolify runbook — proxy/CDN client IPs, backups, webhook
docs/SECURITY.md	The honest security posture, and how to report a vulnerability
docs/PLAN.md	Full architecture, data model, milestones
CONTRIBUTING.md	Ground rules, dev stack, tests, guardrails

Running it locally

./dev.sh        # macOS / Linux
.\dev.ps1       # Windows — same commands

Builds on first run and starts web + mcp + worker + postgres + redis, waits for the healthcheck, prints the URLs. Same containers as the deploy; only docker-compose.local.yml differs.

Command
./dev.sh	build if needed, start everything, wait for health
./dev.sh reload [svc]	restart app containers — picks up code, no rebuild
./dev.sh rebuild [--no-cache]	rebuild images and recreate containers
./dev.sh down [--volumes]	stop and remove (--volumes also drops the DB)
./dev.sh logs [svc] / ps / status	follow logs / container state / + /readyz
./dev.sh shell [svc] / manage <args> / superuser	bash in / manage.py in / create a login
./dev.sh css [--watch]	rebuild the committed Tailwind artifact

Source edits are live — the repo is bind-mounted, so web reloads itself. mcp and worker need ./dev.sh reload. Only a requirements.txt or Dockerfile change needs rebuild.

App on http://localhost:8000, Postgres on localhost:5433, Redis on localhost:6380 (offset so a host install keeps its default port).

---

📘 The free book

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