Big Brain

big-brain 🧠

One memory for every AI assistant you use: your notes, projects, and tasks, kept as plain markdown you own.

Each AI tool keeps its own private memory of you, and none of them share it. big-brain flips that around. Point it at a folder of markdown (a new vault, or the Obsidian vault you already have) and Claude Code, Claude Desktop, Cursor, Codex, or any other MCP client can search it, read it, capture into it, and keep your projects and tasks current. Switch models whenever you like; your context comes with you.

Replay of a real Claude Code conversation with a demo vault ( transcript , recorded by scripts/demo-ai.mjs ); timing is illustrative.

60-second start

npx @jzhao234/big-brain setup

That one command installs big-brain, creates a vault at ~/brain, connects Claude Code, Codex, and Antigravity (agy) if you have them (MCP server plus the /brain, /capture, and /weekly skills), and prints the config to paste into Claude Desktop or Cursor. Pass a folder to use a different one, such as your Obsidian vault: npx @jzhao234/big-brain setup ~/Obsidian. It's safe to run again (anything already set up is left alone), and --dry-run shows the plan without changing anything.

Then restart your assistant and ask *"what am I working on?"* or *"capture: call the dentist on Friday"*. Other clients, and browser chats like claude.ai and ChatGPT, are covered in Connect your AI tools.

Prefer to do it by hand? These three lines are what setup does for Claude Code:

npm install -g @jzhao234/big-brain

big-brain init ~/brain claude mcp add --scope user big-brain -- big-brain-mcp --vault ~/brain

Already use Obsidian? big-brain reads an existing vault as is: no config file, no migration, and nothing is written until you ask for a change (setup writes nothing into it either). Add a brain.config.json later to map your folder names, one entry per folder (for example, "folders": {"projects": "Projects", "inbox": "Inbox"}), so projects and captures land where you keep them. See docs/vault-spec.md.

What you get

• Plain markdown files. No database and no lock-in. Open the vault in Obsidian, grep it, or put it in git.
• An MCP server with 23 tools: search, capture, daily logs, projects, tasks, the link graph, related notes, and a vault health check.
• A CLI for humans: big-brain status, big-brain capture, big-brain tasks, and more.
• Skills for Claude Code, Codex, and Antigravity (/brain, /capture, /weekly), installed with one command.
• Projects as the unit of work. Each project is one file with a goal, checkbox tasks, and a running log.
• Deterministic retrieval first: fuzzy full-text search with title boosting, [[wikilink]] backlinks, tags, and frontmatter filters. No API keys, and it works offline.
• Optional local semantic search. Turn on embeddings.enabled and a small on-device model (via @huggingface/transformers) adds meaning-based matches, fused with full-text search by Reciprocal Rank Fusion. Paraphrases match, exact terms still count, and nothing leaves your machine. It also powers related_notes. See docs/vault-spec.md.
• Optional git auto-commit and push. Turn on git.autoCommit and every note write from any tool commits only the files it touched; add git.autoPush to push in the background so your other machines stay in sync. A git failure never blocks a save: if the commit fails the note is still saved, and if the push fails the commit stays local until the next push.
• Edits that don't damage notes. Writes are atomic and locked per note, keep each note's line endings, never land inside code blocks or frontmatter, refuse to rewrite frontmatter they can't parse, and refuse to write anywhere that resolves outside the vault (such as through a symlink). docs/vault-spec.md lists the edge cases these don't cover.

Requires Node 20 or newer. big-brain is pre-1.0: it's used daily, but minor versions may still change behavior; see the changelog.

Install

npm install -g @jzhao234/big-brain

That puts three commands on your PATH: big-brain (the CLI), big-brain-mcp (the MCP server over stdio), and big-brain-mcp-http (the remote preview below). To try it without installing, npx @jzhao234/big-brain status --vault ~/brain works too.

The base install leaves out semantic search and its native dependencies. To enable local embeddings, install the add-on into the same place, then set embeddings.enabled to true in brain.config.json:

npm install -g @jzhao234/big-brain @huggingface/transformers@^3.8.1

To work on big-brain itself, install from source instead: git clone https://github.com/jzhao234/big-brain.git && cd big-brain && npm install && npm run build && npm link. See CONTRIBUTING.md.

Quickstart

big-brain init ~/brain --name "My Brain"   # scaffold a vault

cd ~/brain big-brain status # look around big-brain install-skills # add the /brain, /capture, /weekly skills

Then connect an AI tool (below) and, optionally, seed the vault from your existing AI history.

Connect your AI tools

For local clients, run big-brain-mcp. The vault is chosen by --vault or the BIG_BRAIN_VAULT environment variable.

Claude Code

claude mcp add --scope user big-brain -- big-brain-mcp --vault ~/brain

claude mcp list # expect: big-brain ... ✔ Connected

Antigravity CLI (`agy`)

agy mcp add big-brain -- big-brain-mcp --vault ~/brain

agy mcp list # expect: big-brain stdio enabled ...

Claude Desktop / Cursor / other MCP clients: add to the MCP config (e.g. claude_desktop_config.json). Use an absolute command path: GUI apps are launched without your shell's PATH, so a bare big-brain-mcp may not resolve (run which big-brain-mcp to get it).

{

"mcpServers": { "big-brain": { "command": "/absolute/path/to/big-brain-mcp", "args": ["--vault", "/absolute/path/to/brain"] } } }

Other local MCP clients: any client that speaks MCP over stdio works the same way. For clients without MCP, the CLI's --json output makes the vault scriptable.

Remote MCP preview: Big Brain can expose the same 23 tools through an authenticated Streamable HTTP endpoint:

export BIG_BRAIN_MCP_TOKEN="$(openssl rand -hex 32)"

big-brain mcp-http --vault ~/brain

endpoint: http://127.0.0.1:3333/mcp

It binds to localhost by default and checks Authorization: Bearer before parsing JSON. Bodies are capped at 1 MB (larger requests get HTTP 413 with a JSON-RPC error). Requests without Origin are allowed; requests with one require an exact match in --allowed-origins / BIG_BRAIN_MCP_ALLOWED_ORIGINS, which defaults to empty and refuses browser origins. Keep it behind an HTTPS reverse proxy or secure tunnel; never expose the plain HTTP listener directly. The static token is the first self-hosted transport milestone, not an OAuth implementation, so browser connectors that require OAuth still need an OAuth-capable gateway. See docs/mcp-setup.md.

Browser fallback (claude.ai / ChatGPT): the zero-infrastructure option is to connect the AI to your vault's GitHub repo so it can read the markdown directly, and write it where the connector allows (some GitHub connectors are read-only; you also lose the computed overview/search/task tools, since it's raw file access). See docs/browser-github-connector.md and paste prompts/browser-github-instructions.md.

Then teach the assistant how to use the vault: Claude Code reads the vault's CLAUDE.md automatically when you work inside the vault folder; elsewhere, and for other tools, paste prompts/agent-instructions.md into their custom instructions.

Using it: load and save

The whole point is that you never re-feed context. The assistant loads a small, relevant slice on demand and saves small pieces as you work. You just talk to it.

Load: orient at the start, pull details as needed:

Save as decisions, progress, and ideas happen (append-first; never destructive):

Review: /weekly runs a guided pass: triage the inbox, prune projects, reschedule overdue tasks, fix broken links, and consolidate: big-brain doctor flags bloated notes and near-duplicates, and the review proposes splits/merges/stale-fact pruning for your approval. Capture and search keep a brain useful; consolidation keeps it trustworthy.

Skills

Three skills wrap the tools into commands, for Claude Code and Antigravity (/brain) and Codex ($brain):

• `brain`: load the overview and switch into brain-aware mode for the session
• `capture`: zero-friction capture to the inbox
• `weekly`: a guided weekly review

big-brain agents install claude codex agy installs them for each agent (see below). big-brain install-skills still copies the Claude versions into ~/.claude/skills (--force overwrites). They're path-agnostic: they call the big-brain CLI / MCP tools and resolve the vault from BIG_BRAIN_VAULT (or --vault), so the same skill works on every machine.

Agent profiles: your agent setup in the vault

Your coding agents' personal setup (skills, global instructions, hooks, the status line, a few settings) can live in the vault too, so every machine gets the same setup from one command and a change made on one machine reaches the others through git.

agents/claude/instructions.md   -> ~/.claude/CLAUDE.md

agents/claude/skills/ / -> ~/.claude/skills/ (one link per skill) agents/claude/files/ -> ~/.claude/ (one link per file: s