Obsidian Brain

A self-evolving knowledge base for agents and humans working together on what matters.

Agents are getting increasingly capable, but they're forgetful; and so are you. The brain gives you and your agent a long-term memory. Forget something? Ask your agent; it will find it. Working on a task? Your agent remembers what you mean, what you care about, what you've done. As you work, the brain builds a rich, linked graph of everything that matters: ideas connect to projects, decisions connect to context, notes connect to sources. Everything you do together makes your brain, your agent, and you, smarter. Plain Markdown in a local Obsidian vault; human-readable, editable in any tool, no lock-in.

Why Obsidian Brain?

Feature	Benefit
Never forget	Every conversation, decision, and idea goes into a linked graph. Your agent finds it when you need it; it remembers so you don't have to.
Context compounds	The richer the vault, the better the answers. Ideas link to projects, decisions link to reasons, notes link to sources. Every session builds on the last.
Self-evolving	Like a real brain, it grows around you and how you think. Your agent builds the vault out as you work; no one size fits all, and yours won't look like anyone else's.
Designed for retrieval	The faster your agent finds the right context, the smarter it can be. Session bootstrap supplies the vault's instructions and discovery routes. Search finds relevant artefacts; taxonomy describes how each type works.
Works with any agent	Any agent that can read files can understand the brain out of the box; the conventions are clear and the structure is self-documenting. We ship tooling that makes it even better.
You can read it too	This isn't a hidden vector database. Everything is human-readable Markdown in an Obsidian vault. Browse it, search it, edit it. You see what your agent sees.
Free your data	Your data is valuable and it's yours; put it to work. It stays on your machine by default. Keep it private, sync it to the cloud, access it from anywhere.
Durable	No database, no proprietary format, no lock-in. Standard files that any tool can read. Your knowledge survives tool changes, agent changes, platform changes.

How It Works

Each brain is an Obsidian vault. You talk to your agent; the agent reads the vault's structure, finds what matters, and extends it. You can browse and edit in Obsidian at any time. The structure holds either way.

All vault content is an artefact, either living (evolves over time; current version is truth) or temporal (bound to a moment; written once). Folders starting with _ or . are infrastructure, not artefacts. Living artefacts sit at the vault root; temporal artefacts sit under _Temporal/.

Agents normally start with MCP session.start (the session_start tool) and finish every bootstrap page before ordinary work. It supplies the vault's instructions, preferences and discovery routes. The launcher alternative is brain session start --json; supported direct scripts also provide tool-backed access where their runtime requirements are met.

The router (_Config/router.md) supplies workflow triggers, vault-specific rules and configuration links. Taxonomy files (_Config/Taxonomy/) define each artefact type. These authored files are configuration inputs to the tools. Agents discover and read the types they need through the session's routes.

The generated .brain/local/session.md is a Markdown mirror of the canonical bootstrap, not an independently authored source of truth. An agent that cannot use MCP, CLI or scripts can follow .brain-core/index.md to that mirror if present, or to .brain-core/md-bootstrap.md for the authored Markdown fallback. The latter works from copied .brain-core/ instructions, the router and relevant taxonomy with no generated assets or code execution.

The Getting Started guide walks through all of this with examples.

Quick Start

You need for installation: git and Python 3.12+, plus an agent you can run in the vault folder. An MCP-capable agent such as Claude Code, Codex or Grok Build uses the normal session bootstrap. CLI and direct scripts provide tool-backed alternatives; the authored Markdown fallback supports agents that cannot use any of those tools. Obsidian is strongly recommended — the brain is designed for it — but you can use any markdown editor or just talk to your agent directly.

Create your vault:

bash <(curl -fsSL https://raw.githubusercontent.com/rob-morris/obsidian-brain/main/install.sh)

This downloads the repo, creates the vault in the current directory, and then asks which MCP clients to configure (Claude Code, Codex, Grok, or All supported clients). Pass a path to install elsewhere. If you want the vault scaffold without the managed runtime / MCP setup, pass --skip-mcp (or add --non-interactive for non-interactive agent installs). From a local clone, use bash install.sh instead.

Optionally let Brain maintain normal read/write approvals for explicitly selected Codex or Claude clients: add --approval-client all --approval-scope user --approvals mcp, or use brain approvals inspect / brain approvals configure later. Client, scope and MCP/CLI surfaces are separate choices; transport setup never opts you in implicitly. See managed approvals for native compatibility, ownership preservation and recovery. Brain permissions and exceptional consent still apply.

On native Windows, use the PowerShell launcher from a local clone:

pwsh -NoProfile -ExecutionPolicy Bypass -File .\install.ps1 -VaultPath C:\path\to\brain

install.cmd is a cmd.exe wrapper over the same PowerShell launcher. Both launchers hand install policy to src/brain-core/scripts/install.py, the same Python installer core used by install.sh.

Brain installs the managed Python runtime to ~/.brain/venvs/py<X.Y>-<sha16>/, identified by the complete base and optional-semantic dependency exports. Vaults sharing that contract share one venv on disk; semantic installation remains opt-in. Install and repair verify exact locked package versions. Native release certification covers CPython 3.12 on macOS arm64, Linux x86_64 and Windows x86_64; other Python 3.12+ environments are best-effort. See DD-077 and the dependency workflow.

Semantic retrieval remains explicit opt-in. Enable it at install time with install.sh --enable-semantic, or later with brain retrieval enable --vault /path/to/brain --json. That flow writes the local semantic-retrieval flag first, installs the pinned semantic Python stack into the central managed runtime, snapshots the pinned model under .brain/local/semantic-models/, records .brain/local/semantic-model-manifest.json, and refreshes the embeddings sidecars so ordinary semantic search stays fully local.

Open in Obsidian (recommended): Open the vault folder, then enable the brain-folder-colours CSS snippet in Settings > Appearance > CSS Snippets.

Start talking: Open your agent in the vault folder (for example cd /path/to/brain && claude or cd /path/to/brain && codex). It calls session_start and follows range.next_cursor until bootstrap_complete is true, then starts work. If MCP is unavailable, use brain session start --json. See Getting Started for the alternatives and Workflows for everyday use.

Command-line usage: the installed brain CLI uses canonical noun/verb command IDs with domain-explicit CLI entry points. For example, brain vault check, brain artefact read, brain doctor, and brain runtime inspect. Every semantic request is supplied as strict JSON; brain command list --json and brain command describe <noun.verb> --json are authoritative discovery. Selected-Brain automation can invoke eligible commands through python3 .brain-core/scripts/command.py <noun> <verb> or the typed Python application. See Getting Started, User Reference, and the Script Reference.

Upgrade

The canonical upgrade path after CLI installation is the checked launcher transaction:

brain upgrade --vault /path/to/brain --request-json '{"acknowledge_global_cli_cutover":true}' --json

For the 0.55.0 cutover itself, or when recovering without the installed CLI, run the source upgrade wrapper:

bash install.sh /path/to/brain --acknowledge-global-cli-cutover

The cutover preflights the complete local Brain registry, requires an exact acknowledgement when other local Brains depend on the global CLI, and commits Brain Core plus the versioned CLI distribution as one checked transaction. Incomplete registries, unacknowledged affected Brains, stale entries without explicit exclusions, unsafe paths, and version mismatches fail before mutation. A failed commit restores the proven old set or retains explicit recovery material rather than claiming rollback without evidence. See CLI for the complete request contract.

Upgrading from before 0.70.3 also offers optional managed approvals setup: inspect first, then explicitly configure if wanted. No approvals are enabled or manually created rules removed by that notice.

Repair

If the local Brain runtime or generated state drifts, use the granular command interface:

brain runtime repair --vault /path/to/brain --json
brain mcp repair --vault /path/to/brain --json
brain runtime refresh-router --vault /path/to/brain --request-json '{"force":true}' --json
brain retrieval refresh-lexical --vault /path/to/brain --request-json '{"force":true}' --json
brain workspace repair-registry --vault /path/to/brain --json
brain retrieval repair-semantic --vault /path/to/brain --json

For most users, brain runtime repair is the main recovery path. Use it when the central managed runtime or its baseline packages have drifted. mcp.repair repairs recorded caller-workspace projections against that working runtime. Use --request-json '{"scope":"user"}' for the shared user connection, '{"breadth":"brain"}' for a selected Brain's runtime and registered integrations, or '{"breadth":"machine"}' for all registered local Brains. Repair never installs an unselected client. Existing legacy claims first require brain mcp migrate; see MCP lifecycle and recovery. retrieval.repair-semantic is the semantic equivalent after a vault has been opted in with retrieval.enable: it repairs the pinned runtime packages, the local model snapshot/manifest, and the embeddings sidecars together. The other scopes repair generated router/index state or the local workspace registry.

If you do not know what is broken, start with:

brain doctor --vault /path/to/brain --json
brain vault check --vault /path/to/brain --json

When vault.check detects router, MCP, semantic-runtime, or local workspace-registry drift, it returns the exact granular repair command to run. Launcher recovery may start from any compatible Python 3.12+ interpreter, but packageful repair converges into the central managed runtime at ~/.brain/venvs/py<X.Y>-<sha16>/; it does not install packages into your wider Python environment.

Existing vault

Point the script at a non-empty directory (with or without Obsidian) and it installs brain-core without touching your files:

bash install.sh ~/my-existing-vault

Uninstall

bash install.sh --uninstall /path/to/brain

Removes brain system files (.brain-core/, .brain/, and the legacy .venv/ if present), removes the Brain bootstrap line from CLAUDE.md (deleting the file only if it becomes empty), removes only recorded Brain-managed project MCP entries from .mcp.json / .codex/config.toml, and removes recorded Brain-managed Claude local state in .claude/. The central runtime at ~/.brain/venvs/ is not removed — other vaults may share it. Your notes are not affected. User-scope MCP cleanup stays explicit. Optionally offers to delete the entire vault with a multi-stage confirmation.

Non-interactive mode

bash install.sh --non-interactive --client all /path/to/brain
bash install.sh --non-interactive --skip-mcp /path/to/brain
bash install.sh --uninstall --non-interactive /path/to/brain

Skips all prompts. MCP setup requires --client claude|codex|grok|all; for example, bash install.sh --non-interactive --client all /path/to/brain. Add --skip-mcp to scaffold the vault without provisioning the central runtime or registering Claude/Codex/Grok MCP — useful in network-restricted agent sandboxes. Python 3.12+ is still required because the shell launcher now hands scaffold policy to the Python installer core. If MCP dependency install or registration fails, the installer leaves the vault in place and prints manual retry steps instead of aborting the whole install. On uninstall, --non-interactive removes system files without prompting and skips the vault-deletion offer entirely. On upgrade, install.sh just delegates to upgrade.py; it does not own upgrade override semantics or re-run MCP setup. If you need same-version re-apply, downgrade, or migration rerun behaviour, call upgrade.py --force directly.

Full reference: Scripts — install.sh covers all flags, safety guards, and edge-case behaviour.

Fully manual setup

If you prefer to do it yourself:

1. Clone this repo: git clone https://github.com/rob-morris/obsidian-brain.git
2. Copy template-vault/ to your preferred location: cp -R template-vault /path/to/brain
3. Copy brain-core into the vault: cp -R src/brain-core /path/to/brain/.brain-core
4. Install the CLI and its versioned distribution: python3.12 cli/_distribution.py . ~/.local/bin/brain (choose an equivalent user bin path on other platforms).
5. Provision the central managed runtime: cd /path/to/brain && python3.12 .brain-core/scripts/_common/_venv.py ensure --vault . --launcher python3.12. This creates ~/.brain/venvs/py3.12-<sha16>/ if missing, using the contract identity of both shipped runtime exports, and installs the complete base export into it.
6. Optionally configure MCP transport with brain mcp configure --vault /path/to/brain --request-json '{"scope":"project","client":"all"}'. This launcher command and the installer share the same launcher-safe transport owner. For project scope, the file write is not the whole story: Claude still needs /mcp approval for brain, Codex needs the project trusted with brain enabled, and Grok needs folder trust.
7. Optionally install the active-Brain shaping discovery adapter for all three clients: brain agent-skill configure --vault /path/to/brain --request-json '{"client":"all"}'. If an older unmanaged shaping skill is already installed, review it and rerun with {"client":"all","replace":true}; Brain archives the old directory instead of deleting it. Restart the clients after installation.
8. Open the folder as an Obsidian vault.
9. Enable the CSS snippet in Settings > Appearance > CSS Snippets (brain-folder-colours).

Connecting from Other Projects

When MCP setup is enabled, the installer registers only explicitly selected clients, using project scope by default. Workspace binding and machine-global transport policy remain separate granular commands:

# Make the Brain available to all projects for all three clients
brain mcp configure --vault /path/to/brain \
  --request-json '{"scope":"user","client":"all"}' --json

# Bind and configure a specific project for all three clients
brain workspace bind --vault /path/to/brain --workspace /path/to/project \
  --request-json '{}' --json
brain mcp configure --vault /path/to/brain --workspace /path/to/project \
  --request-json '{"scope":"project","client":"all"}' --json

# Or just converge the workspace bootstrap without MCP
brain workspace configure-bootstrap --vault /path/to/brain \
  --workspace /path/to/project --json

# Claude-only local scope for a specific project (gitignored; Codex and Grok have no local scope)
brain mcp configure --vault /path/to/brain --workspace /path/to/project \
  --request-json '{"scope":"local","client":"claude"}' --json

Use scope: "user" if you want the Brain everywhere. Bind a project without choosing transport, then run mcp.configure only when wanted. Use scope: "local", client: "claude" for gitignored Claude-only local configuration. For project scope, registration alone is not enough: approve brain via /mcp in Claude; trust the project and enable brain in Codex.

To expose shaping through each client's native skill discovery while keeping the workflow version-matched to the active Brain, install the small discovery adapters once with brain agent-skill configure --vault /path/to/brain --request-json '{"client":"all"}'. They start a session with session.start, then load .brain-core/skills/shaping/ with vault.read-file at invocation time; upgrades therefore do not copy workflow files into client-owned directories. Adapter installation is explicit and ownership-safe, not an implicit side effect of vault upgrade. If the stable discovery adapter itself changes, upgrade.py prints and records the explicit configuration command to run.

Hello, Is It Me You're Looking For?

You Can Just	Do Things
"I just had an idea about..."	"Build a board presentation from this quarter's work on Cairn"
"What did we decide about pricing for Longboard?"	"Optimise the pricing model for Tidepool based on user purchase behaviour to maximise gross revenue"
"What's changed on Helios since I went on leave?"	"Research real-time sync approaches that would work with Mosaic's event-driven architecture"
"Why did we drop the subscription model for Pace?"	"I have an idea for a preference engine. Interview me to shape it."
"We're getting Redis timeouts on Atlas. What could be causing them?"	"Turn my notes from the Sequoia offsite into something the product team can use"
"What went wrong with the Kite launch?"	"Write a brief for the new designer on Lantern. Bring them up to speed on everything we've decided."
"What's the status of everything I'm working on?"	"Draft a competitive analysis for Ridgeline. How are others solving the same distribution problem?"
"Who was that person I met at the conference in March?"	"Start planning the kitchen renovation. Start with the quotes and inspiration I've been collecting."
"Recommend three books I might like to read next"	"Put together talking points for my 1:1 with Marcus about the Rivian partnership"
"What are 3 high-impact things I could do differently next quarter?"	"Brainstorm ideas for something special for my anniversary with Sam. She loved that place in Byron last time."

Documentation

Most repo documentation lives under docs/README.md, which routes to the user, functional, architecture, and contributor docs.

Good starting points:

• Getting Started — install Obsidian Brain and create your first vault
• User Docs — user-facing guides, workflows, and reference
• Contributing — repo contribution guide, including links to contributor-specific docs
• Changelog — release history

Grok client support

Brain configures Grok natively; Claude compatibility settings are not required. Use brain mcp configure --request-json '{"client":"grok","scope":"project"}' from a bound workspace or vault, or choose "scope":"user" for the standard user configuration. "client":"all" includes Claude, Codex and Grok. Grok stores registration in .grok/config.toml and receives a small Brain-owned startup rule at .grok/rules/brain.md. Review Grok's folder-trust prompt before using project configuration, then verify with grok inspect and grok mcp doctor brain. See client configuration for ownership, removal and skill setup.