brain-sync

brain-sync is a local-first tool for building markdown-native knowledge bases. It syncs external documents into a portable filesystem-based brain, maintains AI-generated summaries for each knowledge area, and exposes the result to MCP clients and agent workflows.

It gives you:

a portable brain rooted in normal files and folders
source sync into knowledge/
automatic reconciliation of online and offline changes
co-located summaries, journals, and attachments under .brain-sync/
a bootstrap-capable MCP launcher for chat-based access and management

For the normative on-disk contract, see docs/brain/ and the shared reference docs under docs/.

For synced-source lifecycle behavior, event/state models, and daemon/reconcile flow explanation, see docs/sync/README.md.

Getting Started

Prerequisites

Python 3.11+
Claude CLI for regeneration

Install and authenticate Claude Code first: Anthropic Claude Code docs

Install

pip install .

Google OAuth support is bundled in the packaged runtime. No separate .[google] extra is required for normal use.

The install provides two user-facing commands:

brain-sync for CLI operations and terminal foreground daemon runs
brain-sync-mcp for the shared bootstrap-capable MCP launcher used by all host integrations

Choose a Host

brain-sync supports three host integration styles, all pointing at the same shared brain-sync-mcp launcher seam:

Host	Integration model	Repo artifact
Claude Code	Direct MCP registration	`.mcp.json`
Claude Desktop	Manual MCP registration plus skill	`docs/examples/claude-desktop.mcp.json`, `src/brain_sync/interfaces/mcp/resources/brain_sync/SKILL.md`
Codex	Repo-local plugin	`plugins/brain-sync/`, `.agents/plugins/marketplace.json`

These host integrations are intentionally thin and share the same installed brain-sync-mcp launcher command. Before using any host integration, install the package into the Python environment you want the host to use:

python -m pip install -e .
brain-sync-mcp

If the second command starts the MCP launcher successfully, the launcher command surface is installed correctly. Stop it with Ctrl+C after the check.

Claude Code

Claude Code uses direct MCP registration. Register the MCP server once:

claude mcp add --transport stdio --scope user brain-sync -- brain-sync-mcp

Then restart Claude Code and mention your brain in the conversation.

Claude Desktop

Claude Desktop currently uses manual MCP registration plus the brain-sync skill.

Install the skill from src/brain_sync/interfaces/mcp/resources/brain_sync/SKILL.md
Register the MCP server manually:

{
  "mcpServers": {
    "brain-sync": {
      "command": "brain-sync-mcp"
    }
  }
}

You can also copy the checked-in example from docs/examples/claude-desktop.mcp.json.

Restart Claude Desktop

Codex

Codex uses a repo-local plugin. This repository ships a marketplace manifest at .agents/plugins/marketplace.json, and it points at the checked-in plugin bundle in plugins/brain-sync/.

To use it:

Install brain-sync so brain-sync-mcp is available on PATH.
Restart Codex with this repository open as the active workspace.
Codex should surface brain-sync from brain-sync Repo Plugins automatically because the repo marketplace marks it INSTALLED_BY_DEFAULT.
If it still is not enabled, open the plugin directory, choose brain-sync Repo Plugins, and enable brain-sync manually.

If you do not see the marketplace after the repo adds .agents/plugins/marketplace.json, fully quit and reopen Codex.

First Use

The primary interface is your host integration, not the raw tool names. If you are starting from scratch, ask Claude Code, Claude Desktop, or Codex to create a brain and show status:

"Create a new brain at C:\\Users\\you\\my-brain and show runtime status."

If you already have an initialized brain, ask the host to attach it:

"Attach C:\\Users\\you\\my-brain and show runtime status."

brain-sync can remember multiple registered brains on the same machine, but the runtime uses one active attached root at a time for shared daemon control and host sessions.

Talk To Your Brain

Once a brain is attached, you usually interact with brain-sync by asking your host to do work in plain language rather than naming MCP tools directly.

What You Can Ask

"Show runtime status for the attached brain."
"Search my brain for AAA and open the best match."
"Summarize what my brain knows about Project X."
"Open the platform area and show me the current summary."
"Start the shared daemon if needed."
"Add this Confluence page to initiatives/platform and sync attachments."
"Suggest where this document should live, then add it."
"Reconcile filesystem moves and regenerate changed areas."
"Compare the docs in my brain with this code change."

Configure Your Brain

Source authentication is still CLI-first in this slice. Configure credentials once, then use your host integration for the day-to-day work.

Confluence

brain-sync config confluence \
  --domain yourcompany.atlassian.net \
  --email you@example.com \
  --token your-api-token

Credentials are stored in ~/.brain-sync/config.json. You can also use CONFLUENCE_DOMAIN, CONFLUENCE_EMAIL, and CONFLUENCE_TOKEN.

After that, you can ask your host:

"Add this Confluence page to initiatives/platform."

Google Docs

brain-sync config google \
  --client-id your-google-client-id \
  --client-secret your-google-client-secret

--client-id and --client-secret must come from a Google OAuth client that already exists in a Google Cloud project. They are not generated by brain-sync. For most users, this means creating a Desktop App OAuth client in Google Cloud first, then supplying those values here.

This opens a browser for OAuth consent and stores both the OAuth client and the token in ~/.brain-sync/config.json. Use --reauth to force a new consent flow later.

After that, you can ask your host:

"Add this Google Doc to initiatives/platform."

Folder Structure

After `brain-sync init`

my-brain/
  .brain-sync/
    brain.json
    sources/
  knowledge/
    _core/

Runtime state is intentionally outside the brain root:

~/.brain-sync/
  config.json
  daemon.json
  db/brain-sync.sqlite

In Practice

Not sure how to structure your brain? See the Knowledge Tree Structure Guide for a shareable, generic example of top-level buckets, knowledge-area sizing, and practical placement rules.

Ownership Rules

knowledge/ is where your documents live.
.brain-sync/ is the reserved managed namespace.
Synced source files are managed content and may be overwritten on the next sync.
Co-located summaries and attachments move with their area automatically.
_core/ is the optional core-knowledge area that feeds global context.

Backing Up Your Brain

Initialize a private Git repository at the brain root and push it to a private remote. Commit the brain:

knowledge/
.brain-sync/

Do not commit machine-local runtime state from ~/.brain-sync/. That directory contains disposable caches, local credentials, daemon state, and the runtime DB.

Using a private Git repo matters for two reasons:

it gives you normal backups, history, branching, and multi-machine sync for the brain itself
it keeps your checked-out files consistent across Windows, macOS, and Linux, which helps avoid newline-only checkout differences being mistaken for content changes during reconcile and regen

For a brain repository, prefer byte-stable checkout rules over OS-native line ending translation. Add a .gitattributes file at the brain root like this:

* -text
*.png binary
*.jpg binary
*.jpeg binary
*.gif binary
*.pdf binary
*.sqlite binary

* -text tells Git not to rewrite line endings on checkout. That keeps the working tree bytes stable across supported platforms, which is especially important because brain-sync hashes the files it sees on disk when deciding whether a knowledge area changed.

CLI Reference

Most users can stay in Claude, Claude Desktop, or Codex once their host integration is set up. The CLI still matters for terminal-first workflows, automation, and source configuration.

Command	Description
`brain-sync init <root>`	Initialize a brain
`brain-sync run [--root <path>]`	Start the real foreground daemon engine
`brain-sync attach-root <root>`	Attach an existing initialized brain and make it the active runtime root
`brain-sync start`	Start or adopt the shared background daemon for the active runtime root
`brain-sync stop`	Stop the shared `launcher-background` daemon when remote control is supported
`brain-sync restart`	Restart the shared `launcher-background` daemon when remote control is supported
`brain-sync add <url> [...]`	Register a URL for sync
`brain-sync add-file <file> [...]`	Import a local markdown or text file
`brain-sync remove <canonical-id-or-url> [--delete-files]`	Remove a sync source and its synced files (`--delete-files` is accepted for compatibility); may return handled `not_found` or `lease_conflict`
`brain-sync remove-file <path>`	Remove a local file from `knowledge/`
`brain-sync list [--path <filter>] [--status]`	List registered sources and print `State: <knowledge_state>` for each source
`brain-sync move <canonical-id> --to <new-path>`	Move one registered source by exact canonical ID; may return handled `not_found` or `lease_conflict`
`brain-sync update <canonical-id-or-url> [...]`	Update source settings
`brain-sync sync [<canonical-id-or-url> ...]`	Schedule priority polling for all active sources or the listed active sources by updating `sync_polling`; handled `not_found` is returned when any listed selector is not currently active
`brain-sync reconcile [--root <path>]`	Reconcile filesystem moves
`brain-sync finalize-missing <canonical-id>`	Explicitly finalize one missing registered source after revalidation; requires an exact canonical ID, not a URL or path
`brain-sync status [--root <path>]`	Show setup, daemon, and sync status for the active runtime
`brain-sync tree [--json]`	Show the full semantic knowledge-area tree; `--json` emits the same sparse contract as `brain_sync_tree`
`brain-sync regen [<knowledge-path>]`	Trigger regeneration
`brain-sync doctor [--fix	--rebuild-db]`
`brain-sync config confluence ...`	Configure Confluence credentials
`brain-sync config google [--reauth]`	Authenticate Google Docs access
`brain-sync convert <file> [--comments-from <docx>]`	Convert `.docx` to markdown
`brain-sync migrate [--root <path>]`	Legacy attachment-layout migration helper
`brain-sync update-skill`	Re-install the Claude Desktop skill

All commands accept --log-level. Commands that operate on a brain root accept --root.

Common CLI Tasks

Initialize a new brain:

brain-sync init ~/my-brain

Attach an existing initialized brain and make it active:

brain-sync attach-root ~/my-existing-brain

Start the real foreground daemon engine:

brain-sync run --root ~/my-brain

Use the launcher-managed background daemon for the active attached root:

brain-sync start
brain-sync status
brain-sync stop
brain-sync restart

brain-sync start is idempotent when a healthy daemon is already running for the same runtime config dir. brain-sync stop and brain-sync restart remotely control only launcher-background daemons in v1. A healthy terminal-started brain-sync run daemon is still adoptable for status and normal use, but remote stop/restart remains intentionally unsupported.

Register a source:

brain-sync add https://yourcompany.atlassian.net/wiki/spaces/SPACE/pages/123456/Page+Title \
  --path initiatives/my-project \
  --fetch-children \
  --sync-attachments

brain-sync add "https://docs.google.com/document/d/1A2B3C/edit" --path area

--path is optional. If omitted, brain-sync can suggest placement based on your existing tree.

--fetch-children and --sync-attachments are execution-time sync options.

Request immediate polling for active sources:

brain-sync sync [<canonical-id-or-url> ...]

With no selectors, all active sources are marked due immediately. With one or more selectors, only those active sources are marked due immediately. The command does not fetch remote content itself; it only updates sync_polling so the targeted sources are due on the next daemon refresh or the next brain-sync run.

Add a local markdown or text file:

brain-sync add-file ./notes.md --path area

Supported direct file imports: .md, .txt

For .docx, use brain-sync convert first.

MCP Tool Reference

Most users will not invoke these tools directly. They are the MCP surface that Claude, Claude Desktop, Codex, and other compatible hosts call under the hood.

brain-sync exposes a bootstrap-capable MCP launcher for querying, reading, and managing the brain.

MCP Daemon Lifecycle

This section applies when a host starts brain-sync-mcp as an MCP stdio server.

You do not normally need to keep a separate brain-sync-mcp terminal open for host-driven use. The host starts the MCP server process when needed.

Bootstrap and admin tools can run without a daemon. When a full brain tool is used, the MCP surface first requires a usable attached root and then ensures a healthy shared daemon exists for the active runtime root, reusing one if it is already running or starting one if it is not.

If MCP starts the daemon, it starts a detached launcher-background daemon for the current runtime config directory. That daemon is shared across later host sessions for the same runtime and is not tied to the lifetime of one Claude or Codex terminal session. If the host kills the MCP server process, the detached daemon can continue running and be adopted later. When the installed CLI wrapper is available, the launcher starts the daemon via brain-sync, which makes it easier to identify in process lists on platforms such as Windows.

You can still use the CLI directly. Normal CLI commands can coexist with host-driven MCP use, but brain-sync run is still a daemon start. brain-sync allows only one daemon per runtime config directory, so starting a second daemon for the same runtime is refused.

If you choose to run brain-sync run yourself in a terminal, MCP clients can adopt that healthy daemon for status and normal use. In v1, remote brain_sync_stop and brain_sync_restart support applies only to launcher-background daemons, not terminal-owned foreground daemons.

When no usable active root is attached, the launcher starts in bootstrap mode. Setup/admin tools work immediately, and full brain tools remain visible for MCP clients that cache the initial tool list, but those full tools fail closed until brain_sync_init or brain_sync_attach_root completes:

Tool	Description
`brain_sync_setup_status`	Report whether an active usable root is attached
`brain_sync_init`	Initialize and attach a new brain root
`brain_sync_attach_root`	Attach an existing initialized brain root
`brain_sync_status`	Show runtime bootstrap, daemon, and content status
`brain_sync_start`	Start or adopt the shared background daemon
`brain_sync_stop`	Stop a `launcher-background` daemon when supported
`brain_sync_restart`	Restart a `launcher-background` daemon when supported

After brain_sync_init or brain_sync_attach_root, those same full tools become usable in the current session.

Primary tools:

Tool	Description
`brain_sync_query`	Search areas by query
`brain_sync_tree`	Return the full semantic knowledge-area tree as a sparse read-only JSON structure
`brain_sync_get_context`	Load global context from the `_core` summary at `knowledge/_core/.brain-sync/insights/summary.md`
`brain_sync_open_area`	Load an area's summary, artifacts, and children
`brain_sync_open_file`	Read a text file from the brain
`brain_sync_list`	List registered sources, including `knowledge_state` for missing registered sources
`brain_sync_add`	Register a sync source
`brain_sync_add_file`	Add a local markdown or text file
`brain_sync_update`	Update source settings
`brain_sync_remove`	Remove a sync source; may return handled `not_found` or `lease_conflict`
`brain_sync_move`	Move one registered source by exact canonical ID to a new path; may return handled `not_found` or `lease_conflict`
`brain_sync_finalize_missing`	Explicitly finalize one missing registered source by exact canonical ID
`brain_sync_reconcile`	Reconcile filesystem moves
`brain_sync_regen`	Regenerate summaries

Run manually:

brain-sync-mcp

Updating brain-sync

Stop the daemon
Pull the latest code
Reinstall the package:

python -m pip install -e .

If you use Claude Desktop with the manual skill, update the skill:

brain-sync update-skill

Restart your host
Start brain-sync run again

Configuration

brain-sync stores machine-local configuration in ~/.brain-sync/config.json.

Typical fields include:

registered brain roots, with brains[0] as the active runtime root
log level
Confluence credentials
Google token
regen settings
operational event retention settings
token retention settings

Local telemetry retention keys:

operational_events.retention_days defaults to 90
token_events.retention_days defaults to 90

Converting .docx Files

Google Docs comments survive best through .docx exports.

Hybrid mode:

brain-sync convert document.md --comments-from document.docx

Full conversion:

brain-sync convert document.docx

State and Recovery

brain-sync uses three broad state layers:

durable manifests in .brain-sync/sources/
durable per-area insight state in knowledge/**/.brain-sync/insights/
machine-local runtime DB and daemon state in ~/.brain-sync/

If the runtime DB is lost, it can be rebuilt from the durable brain state.

Run brain-sync doctor after upgrades or if the brain looks inconsistent.

Offline Knowledge Management

You can move, rename, create, and delete files under knowledge/ while the daemon is stopped.

On the next brain-sync run:

manifests are reconciled with filesystem truth
moved synced files are rediscovered
missing synced sources remain registered until you explicitly run brain-sync finalize-missing <canonical-id>
changed areas are re-queued for regeneration
co-located summaries and attachments already move with their folders

brain-sync finalize-missing is intentionally conservative: it accepts one exact canonical ID at a time, not a URL, path, or bulk target, revalidates local presence first, finalizes immediately when an already-missing source is still absent, and returns not_missing instead of deleting anything if the source reappears during revalidation. Likewise, brain-sync move now requires an exact canonical ID, while brain-sync remove accepts either a canonical ID or URL; both return handled not_found when the target source cannot be resolved, rather than partially entering lifecycle work.

Development

pip install -e ".[dev]"
python -m pytest -n auto

Supported Sources

Source	Status	Auth
Confluence	Working	REST API credentials via config or env
Google Docs	Working	Native OAuth browser consent

Name		Name	Last commit message	Last commit date
Latest commit History 269 Commits
.agents/plugins		.agents/plugins
.github/workflows		.github/workflows
docs		docs
plugins/brain-sync		plugins/brain-sync
scripts		scripts
src/brain_sync		src/brain_sync
tests		tests
.gitattributes		.gitattributes
.gitignore		.gitignore
.mcp.json		.mcp.json
.pre-commit-config.yaml		.pre-commit-config.yaml
AGENTS.md		AGENTS.md
CLAUDE.md		CLAUDE.md
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
README.md		README.md
pyproject.toml		pyproject.toml
pyrightconfig.json		pyrightconfig.json

Folders and files

Latest commit

History

Repository files navigation

brain-sync

Getting Started

Prerequisites

Install

Choose a Host

Claude Code

Claude Desktop

Codex

First Use

Talk To Your Brain

What You Can Ask

Configure Your Brain

Confluence

Google Docs

Folder Structure

After brain-sync init

In Practice

Ownership Rules

Backing Up Your Brain

CLI Reference

Common CLI Tasks

MCP Tool Reference

MCP Daemon Lifecycle

Updating brain-sync

Configuration

Converting .docx Files

State and Recovery

Offline Knowledge Management

Development

Supported Sources

About

Resources

License

Contributing

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Uh oh!

Contributors

Uh oh!

Languages

After `brain-sync init`

Packages