brain-wiki

One long-term memory for all your AI agents, kept as plain Markdown that you own.

Your agents (Claude Code, Codex, Antigravity, Cursor, OpenClaw, or any MCP client) share one brain: a folder of Markdown notes they search before answering and keep up to date as they work. It runs on your machine, needs no server or API keys, and opens in Obsidian.

• Plain files. Read, edit, diff, and sync the brain like any folder, or adopt an Obsidian vault as it is.
• Knows what changed. Search returns a note together with the notes that replace or contradict it.
• Safe to let agents write. Changes are checked, logged, and undoable, and committed when the brain is a git repository.
• No network calls. Your own agent does the thinking; brain-wiki stores and checks.

Quick start

Needs Python 3.11+ and uv.

1. Install.

uv tool install brain-wiki

2. Set it up.

• Recommended: paste this into your agent (Claude Code, Codex, Antigravity, Cursor, OpenClaw, ...):

  Set up brain-wiki by running brain setup --guide and following it.

• Or, in a terminal: run brain setup, which asks the same questions step by step.

Either way, setup explains each choice (where the brain lives, which agents to connect, what each may do) and shows every change before making it.

3. Use it in your agent.

Remember that I prefer pnpm over npm, and that our team ships on Thursdays.

What did we decide about the database migration last week?

Maya moved to the platform team. Update her note.

Consolidate my brain.

4. See your brain. brain viz opens a local 3D map of your notes, and brain obsidian opens the brain's folder as a vault in Obsidian. With several brains, both ask which one, or name it: brain viz work.

How it works

agents ──log──► inbox ──consolidate──► notes (topics/*.md) ◄── you, in Obsidian
  ▲                   (checked ops)            │
  └────────────── search · read ───────────────┘

Agents log what they learn to an inbox. When you ask, your agent folds the inbox into topic notes through small operations that brain-wiki checks before writing, and brain undo reverses any change.

Status

Alpha: expect breaking changes before 1.0. Known limits:

• No access scopes inside a brain: every connected agent reads all of it. Keep work and personal notes in separate brains.
• Maintenance runs when you ask; there is no scheduler.
• Chat apps that need a remote MCP server (ChatGPT, claude.ai, the Gemini app) are not supported yet.

Learn more

Getting started · Agents · Maintenance · Import a vault · Privacy · Reference · Design · Changelog

Contributing · Security · Apache 2.0 (visualizer notices)