brainy

Brainy is a self-hosted shared brain for AI agents and the humans who work with them. It provides a knowledge base and task collaboration backend, which Claude, ChatGPT, and other MCP-capable AIs connect to through a controlled endpoint. All agents read the same knowledge, work on the same task list, and leave an audit trail, so work can be handed off between AIs instead of each being trapped in a separate chat silo.

Purpose

Brainy solves the coordination problem in multi-agent collaboration. When multiple AI agents need to share knowledge, assign tasks, and avoid duplicated work, Brainy provides a unified knowledge store and task queue. It is suited to scenarios where different AI clients (such as Claude and ChatGPT) need to work together to complete work, and also to teams that want to keep a human approval step.

Main capabilities

• Agent collaboration: ChatGPT creates tasks, Claude claims tasks, completes the work, and writes the results back, and humans review. Coordination happens through task completion, with no hidden inter-agent magic.
• Single source of truth: Knowledge is stored as plain Markdown in a Git repository. Every write is a commit, so history, diff comparison, and rollback come for free.
• Secure by default: No shell, no file system, no eval over MCP. It provides path allowlists, per-space ACLs, secret detection on write, rate limiting, hashed tokens, and append-only audit logs.
• Avoid duplicated work: Atomic task claiming with leases and claim tokens ensures that two agents will not work on the same task at the same time.
• Human in the loop: Agents can propose knowledge changes, which humans approve or reject through the Web UI or Telegram. Tasks can require review/approval before they count as complete.
• Zero dependencies: Pure Python standard library + SQLite. No pip installation required, and a minimal attack surface.

Difference from ordinary Markdown files

Keeping shared note files in a Git repository is a great way to store knowledge, and Brainy deliberately preserves this: knowledge is plain Markdown in Git, with history, diffs, and rollback. But when more than one agent touches the files, bare files cannot handle the following problems:

• Two agents overwriting each other: There is no mechanism to serialize concurrent writes to the same file. Brainy's writes use optimistic concurrency (expected_git_commit) plus a server-side write lock: exactly one writer commits, other writers receive a conflict and re-read, so no edits are lost.
• No task handoff: a file can list to-dos, but it cannot prevent two agents from grabbing the same task. Brainy tasks use atomic claiming (UPDATE ... WHERE status='READY', single row): exactly one agent wins, the rest receive a conflict and move on.
• No per-area permissions: files are all-or-nothing. Brainy has Spaces and per-space ACLs, so agents can only read/write the areas you grant them.
• No approval step: agents can propose changes for human approval (Web UI or Telegram) instead of writing directly to the source of truth.
• "Who changed what" goes beyond git blame: every operation—reading task status, claiming, writing, rejecting—goes into an append-only audit log enforced by database triggers.

The above two guarantees are covered by concurrency tests (tests/test_concurrency.py): 20 threads compete for one task, producing exactly 1 winner and 19 conflicts; 20 threads write to the same file, producing exactly 1 commit and 19 conflicts, and the repository remains clean.

Usage

Quick start (Docker)

Try it with one command—no cloning, no setup. Run a one-off demo (temporary database + sample knowledge, deleted on exit) as an MCP stdio server.

For a real installation, run the server (prebuilt image, published with every release).

Or build it yourself with Compose.

Brainy then listens on http://127.0.0.1:8765（MCP endpoints: /mcp, admin UI: /admin—log in with a token). For remote AI connectors, put it behind HTTPS (see deploy/nginx-brainy.conf.example) and set BRAINY_PUBLIC_BASE_URL.

Quick start (bare metal, Linux, Python ≥ 3.10)

Connect AI

• Claude Code: claude mcp add --transport http brainy http://127.0.0.1:8765/mcp --header "Authorization: Bearer <token>"
• Local stdio client (such as Claude Desktop): run Brainy as a subprocess: { "mcpServers": { "brainy": { "command": "python3", "args": ["/opt/brainy/scripts/stdio.py"], "env": { "BRAINY_DB_PATH": "/var/lib/brainy/brainy.db", "BRAINY_KNOWLEDGE_ROOT": "/opt/brainy-knowledge", "BRAINY_TOKEN": "<token>" }}}} Try it without any setup: python3 scripts/stdio.py --demo (temporary data, deleted on exit).
• Any other MCP client with custom headers: endpoint https://<your-host>/mcp, header Authorization: Bearer <service token>.
• Claude.ai / ChatGPT remote connectors: use the OAuth 2.1 flow (discovery address /.well-known/oauth-authorization-server). Set BRAINY_PUBLIC_BASE_URL to your HTTPS URL.

Brainy is registered in the official MCP Registry as io.github.memokar/brainy.

Give each AI its own principal (such as claude, chatgpt), role AGENT, and grant it only the spaces it needs. Every operation will then appear in the audit log under that name.

Example: two coding agents in one repository

Two agents working on the same repository can step on each other's files. With resource claiming, each agent reserves the area it is about to touch—one free-form key per space—and the other backs off until release or lease expiry. The same guarantees as task claiming—exactly one holder at a time, expired leases automatically released (see tests/test_resources.py). The resource claim reuses the task permission/scope (can_claim_tasks / brainy:tasks:write), so any agent that can claim tasks can also claim resources.

All configuration comes from environment variables—see .env.example. Secrets (tokens, keys) are never stored in the repository or the knowledge base.

The core ships with a worker plugin interface and a deterministic MockWorker. Real workers that let agents execute tasks autonomously (such as Claude Code, Codex) are separate extensions loaded via BRAINY_WORKER_PLUGINS. See docs/extensions.md.

Use cases

• Multiple AI agents need to share a knowledge base and task list to avoid duplicated work.
• AI workflows that require a human approval step.
• Teams that want knowledge changes to be traceable and rollback-capable.
• Scenarios that require controlling agent read/write permissions by zone.

Limitations

• Code comments are still partly in German; all user-facing text is in English.
• Single-node design (SQLite). Consider PostgreSQL only when real multi-writer load appears.

License

Brainy is dual-licensed:

• Open source: GNU AGPL-3.0. Free for everyone, including companies—but if you modify Brainy and provide it to others (including as a network service), you must release your changes under the AGPL.
• Commercial license: For companies that want to use or embed Brainy without the AGPL obligations. See COMMERCIAL.md.

Contributions require agreeing to a Contributor License Agreement (CLA).