brains
A self-hosted AI knowledge agent that reads and writes your markdown.
brains lets you run an AI assistant around files you own. Your notes, posts, pages, images, and profile data live as markdown in a local brain-data/ folder. The running brain can search that content, update it, expose it to tools like Claude or Cursor, and publish a static website from the same source.
Status: 0.2.0 alpha; stable nomination is pending final authoring, live/eval, and deployment evidence. It works today, but APIs outside the documented 0.2 candidate surface may still change before 1.0. See the roadmap and STABILITY.md.
Who this is for
Use brains if you want to:
- keep your knowledge in markdown instead of a hosted app
- run a personal or site-focused AI assistant on your own machine or server
- connect that assistant to Claude Desktop, Cursor, or other MCP clients
- publish a website from the same content the assistant uses
- customize behavior with plugins when the defaults are not enough
It is not a hosted SaaS, a Notion/Obsidian clone, or a stable third-party plugin platform yet.
Quickstart
Install Bun first, then:
bun add -g @rizom/brain
brain init mybrain --recipe personal
cd mybrain
cp .env.example .env
# edit .env and set AI_API_KEY
brain startThis creates a new brain instance with:
- brain.yaml — main configuration
- .env.example and .env.schema — environment/secrets reference
- package.json — pins the runtime package
- tsconfig.json, .gitignore, and a local README.md
- brain-data/ — created/seeded on first run when file sync is active
On first start, site-enabled instances print a one-time /setup URL. Open it locally, register a passkey, and use that passkey for browser and OAuth-based MCP access. Auth state is stored in ./data/auth; keep it when deploying or backing up.
For the full walkthrough, see Getting Started.
Connect Claude, Cursor, or another MCP client
MCP is the protocol many AI apps use to connect to external tools and data.
For local stdio MCP, point the client at your brain directory: