rizom-ai/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:
This 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:
For HTTP MCP, use:
or, after deployment:
OAuth-capable clients can use the built-in browser/passkey login. MCP_AUTH_TOKEN still exists as a legacy fallback for clients that cannot use OAuth.
How it works
A brain has three main pieces:
1. **Content** — markdown files in brain-data/
2. **Definition + bundles** — one ordered catalog with eight capability bundles and the policy-only team bundle
3. **Runtime** — the brain process that resolves selection, indexes content, serves tools, and optionally builds a site
Recipes and postures
- headless — core
- personal — core + media + web + chat
- professional — core + media + automation + web + chat + site + publishing + federation
- team — core + media + automation + web + chat + site + team, plus docs
If you are trying brains for the first time, use brain init --recipe personal. Recipes expand to explicit YAML and have no runtime meaning.
Documentation
Start here:
- Documentation Index
- Getting Started
- brain.yaml Reference
- CLI Reference
- Deployment Guide
Deeper topics: