@rizom/brain

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: pre-stable 0.x. It works today, but APIs and package names can still change before 1.0. See 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 --model rover
cd mybrain
cp .env.example .env
# edit .env and set AI_API_KEY
brain start

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, models with browser login 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: