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.

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

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.

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