Brainy

io.github.memokarv0.1.0Updated Oct 6, 2026

Shared knowledge base + task queue so Claude, ChatGPT and other agents can work together safely.

VerifiedSTDIODesktop onlyKnowledge & MemoryProductivity & Workflow

Overview

AI-generated overview

Self-hosted shared knowledge base and task queue that lets multiple AI agents read the same Markdown knowledge and coordinate work through tasks.

What it does
Brainy gives agents one controlled MCP endpoint for shared knowledge and tasks. Knowledge tools include list_documents, get_document, search_knowledge, write_document, append_document and propose_write, with writes committed to a Git repository. Task tools include create_task, claim_task, renew_claim, complete_task, fail_task and release_task, with atomic claims, leases, dependencies and review. Spaces, roles, per-space ACLs and an append-only audit log govern access.
When to use it
Use it when several AI clients such as Claude, ChatGPT or custom bots should share one knowledge base and one task list instead of working in separate chat silos. It suits teams that want human review of agent-proposed knowledge changes and an audit trail of agent actions.
Requirements
Runs as a local process, typically via the published container image or from source with Python 3.10 or newer and SQLite. Needs a data directory and knowledge root, plus a service token sent in the Authorization header; the admin token is printed once on first start. Remote connectors require HTTPS and OAuth 2.1 configuration.
Before you install
The Authorization header carries a Brainy service token, and the admin token is shown once at first start, so store it securely. Agents can write and append knowledge documents and create, claim, complete or fail tasks, and proposed writes may need human approval. Give each agent its own principal with only the spaces it needs.

Installation

In SourceWeft

  1. Open Brainy in the dashboard and add it to a workspace.
  2. Enable the server for the chats that should use its tools.

Desktop only via STDIO. STDIO servers start a local process, so they need the SourceWeft desktop host.

Other MCP clients

Follow the launch instructions in the repository.

README

Brainy

[CI] [License: AGPL-3.0] [Dependencies: none]

A shared brain for your AI agents — and for the humans who work with them.

Brainy is a self-hosted knowledge and task backbone that Claude, ChatGPT and any other MCP-capable AI connect to through one controlled endpoint. Every agent reads the same knowledge, works on the same task list and leaves an audit trail — so your AIs can hand work to each other instead of living in separate chat silos.

   ChatGPT ─┐                                   ┌─ Git-versioned knowledge (Markdown)   Claude  ─┼──►  MCP endpoint  ──►  Brainy  ───┼─ Tasks with atomic claim/lease   Your bot ┘     (OAuth / tokens)   ACL+Audit  └─ Spaces, roles, append-only audit log                                       ▲                          Humans: web admin UI (+ optional Telegram approvals)

Why Brainy?

  • AIs that collaborate. ChatGPT creates a task, Claude claims it, does the work and writes the result back; a human reviews. Coordination happens through tasks — no hidden agent-to-agent magic.
  • One source of truth. Knowledge lives as plain Markdown in a Git repository. Every write is a commit, so you get history, diffs and rollback for free.
  • Safe by default. No shell, no filesystem, no eval over MCP. Path allowlist, per-space ACLs, secret detection on writes, rate limits, hashed tokens and an append-only audit log.
  • No double work. Atomic task claims with leases and claim tokens guarantee that two agents never process the same task at the same time.
  • Human in the loop. Agents can propose knowledge changes; a human approves or rejects them (web UI or Telegram). Tasks can require review/approval before they count as done.
  • Zero dependencies. Pure Python standard library + SQLite. No pip install, tiny attack surface.

Features

AreaWhat you get
Knowledgelist_documents, get_document, search_knowledge, write_document (optimistic concurrency via Git commit), append_document, propose_write
Taskscreate_task, claim_task, renew_claim, complete_task, fail_task, release_task, dependencies, priorities, review/approve/reject
AccessSpaces (tenants/areas), roles ADMIN / EDITOR / AGENT / READER, per-space ACL, service tokens, OAuth 2.1 (for Claude/ChatGPT remote connectors)
OperationsWeb admin UI, audit log, agent registry + dispatcher framework, backup & verified restore scripts

Quickstart (Docker)

Prebuilt image (published on every release):

bash
docker run -d --name brainy -p 127.0.0.1:8765:8765 -v brainy-data:/data ghcr.io/memokar/brainy:latestdocker logs brainy   # prints your one-time ADMIN token on first start

Or build it yourself with Compose:

bash
git clone https://github.com/memokar/brainy.gitcd brainydocker compose up -ddocker compose logs brainy   # prints your one-time ADMIN token on first start

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

Quickstart (bare metal, Linux, Python ≥ 3.10)

bash
export BRAINY_DB_PATH=$PWD/data/brainy.dbexport BRAINY_KNOWLEDGE_ROOT=$PWD/data/knowledgeexport BRAINY_WEB_SESSION_KEY=$PWD/data/web_session.key
cp -r examples/knowledge "$BRAINY_KNOWLEDGE_ROOT"git -C "$BRAINY_KNOWLEDGE_ROOT" init -q && git -C "$BRAINY_KNOWLEDGE_ROOT" add -A \  && git -C "$BRAINY_KNOWLEDGE_ROOT" commit -qm "initial knowledge"
python3 scripts/bootstrap.py "$BRAINY_DB_PATH" --with-token   # prints ADMIN token oncepython3 scripts/init_prod_db.py "$BRAINY_DB_PATH"             # seeds default spacespython3 scripts/serve.py

Connecting an AI

  • Claude Code:
    bash
    claude mcp add --transport http brainy http://127.0.0.1:8765/mcp --header "Authorization: Bearer <token>"
  • Local stdio clients (e.g. Claude Desktop): run Brainy as a subprocess:
    json
    {"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 at /.well-known/oauth-authorization-server). Set BRAINY_PUBLIC_BASE_URL to your HTTPS URL.

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

Give each AI its own principal (e.g. claude, chatgpt) with role AGENT and only the spaces it needs. Every action then shows up in the audit log under that name.

Configuration

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

Extensions

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

Running the tests

bash
for t in tests/test_*.py; do python3 "$t" || exit 1; done

Status & roadmap

Brainy runs in production for its author. Current limitations:

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

License

Copyright (C) 2026 Mehmet Karakolcu

Brainy is dual-licensed:

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

Contributions require agreeing to the Contributor License Agreement.

Source: README.md at commit 79e0ec7

Tools

0
Tool metadata has not been indexed yet.

Version history

1
  1. v0.1.0LatestOct 6, 2026