Brainy

Brainy

为你的 AI Agent，以及与你协作的人类打造的共享大脑。

Brainy 是一个可自托管的知识与任务基础设施，Claude、ChatGPT 及其他支持 MCP 的 AI 都通过一个受控端点连接到它。 每个 Agent 都读取相同的知识、处理相同的任务列表，并留下审计记录 — 因此，你的 AI 可以互相交接工作，而不必各自困在独立的聊天孤岛中。

   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)

为什么选择 Brainy？

• 让 AI 协作。 ChatGPT 创建任务，Claude 领取任务、完成工作并写回结果；人类进行审核。协作通过任务完成 — 没有隐藏的 Agent 间魔法。
• 单一可信来源。 知识以纯 Markdown 格式存储在 Git 仓库中。每次写入都是一次提交，因此你可以免费获得历史记录、差异对比和回滚。
• 默认安全。 MCP 不提供 shell、文件系统或 eval。路径允许列表、按空间设置的 ACL、写入时检测机密信息、速率限制、哈希令牌，以及仅追加的审计日志。
• 杜绝重复劳动。 带租约和领取令牌的原子任务领取机制，确保两个 Agent 不会同时处理同一任务。
• 人类参与其中。 Agent 可以提议知识变更，由人类批准或拒绝（通过 Web UI 或 Telegram）。任务也可以要求先审核或批准，再标记为完成。
• 零依赖。 仅使用 Python 标准库和 SQLite。无需 pip install，攻击面极小。

为什么不只用 Markdown 文件？

Git 仓库中的共享笔记文件是很好的知识存储方式 — 而 Brainy 也正是有意保留了这一部分：知识以纯 Markdown 格式存储在 Git 中，并保留历史记录、差异对比和回滚功能。问题在于，一旦多个 Agent 共同使用，普通文件无法处理其他事情：

• 两个 Agent 会互相覆盖。 没有任何机制能串行处理对同一文件的并发写入。Brainy 的写入通过乐观并发控制（expected_git_commit）和服务端写入锁执行：只有一个写入者能提交，其他写入者会收到 Conflict 并重新读取 — 不会丢失编辑内容。
• 无法交接任务。 文件可以列出待办事项，却无法阻止两个 Agent 领取同一项任务。Brainy 的任务采用原子领取（UPDATE ... WHERE status='READY'，只影响一行）：只有一个 Agent 能成功，其余 Agent 会收到冲突并继续处理其他任务。
• 无法设置分区权限。 文件的权限只能全开或全关。Brainy 提供空间和按空间设置的 ACL，因此 Agent 只能读取或写入你授权的区域。
• 没有审批步骤。 Agent 可以提议变更，由人类批准（通过 Web UI 或 Telegram），而不是直接写入可信来源。
• 不止于 git blame，还能回答“谁改了什么？” 每项操作 — 读取任务状态、领取任务、写入、拒绝提议 — 都会记录在由数据库触发器强制执行的仅追加审计日志中。

上述两项保障均由并发测试覆盖 （tests/test_concurrency.py）：20 个线程争抢同一任务时，结果恰好是 1 个成功、19 个冲突；20 个线程写入同一文件时，结果恰好是 1 次提交、19 个冲突，且仓库保持干净。

Brainy 有何不同？

诚实地比较人们最常提到的工具。Beads 最接近 Brainy 的任务部分，而 Central Brain 最接近其知识部分；两者都不能与之完全对应。信息均来自各项目自己的文档（见下方链接）；对于未记录的信息，我们会如实说明，而非猜测。

	Brainy	Beads 1	Central Brain 2	共享笔记文件
产品定位	知识库 + 任务队列	面向 AI Agent 的问题／任务跟踪器	AI 记忆层	仓库中的 Markdown
知识存储	Git 中的 Markdown	—（问题跟踪器）	纯文件 + 本地向量索引	Git 中的 Markdown
带原子认领机制的任务队列	✅	✅	未记录	❌
按区域设置权限（ACL）	✅ Spaces/roles	❌	❌	❌
仅追加审计日志	✅（由数据库强制执行）	部分支持（Git/数据库历史记录）	❌	仅 git blame
写入需经人工批准	✅（网页／Telegram）	❌	❌	❌
MCP 服务	✅	✅	✅	❌
多 Agent 并发控制	✅ 认领 + 写入锁	✅ 认领 + 并发写入者	未记录	❌
依赖项	无（标准库 + SQLite）	捆绑 Dolt（Go）	捆绑嵌入模型	不适用
可自托管	✅	✅	✅（云服务可选）	✅
许可证	AGPL-3.0（+ 商业授权）	MIT	专有	不适用

功能

领域	提供的功能
知识	list_documents、get_document、search_knowledge、write_document（通过 Git 提交实现乐观并发控制）、append_document、propose_write
任务	create_task、claim_task、renew_claim、complete_task、fail_task、release_task、依赖项、优先级、审查／批准／拒绝
资源认领	claim_resource、renew_resource、release_resource、list_resource_claims — 使用原子租约预留任意资源（每个空间的自由格式键，例如文件路径或区域），采用与任务认领相同的模式
访问	Spaces（租户／区域）、角色 ADMIN / EDITOR / AGENT / READER、按空间设置的 ACL、服务令牌、OAuth 2.1（用于 Claude/ChatGPT 远程连接器）
运维	Web 管理界面、审计日志、Agent 注册表 + 调度器框架、备份与验证还原脚本

快速开始（Docker）

只需一条命令即可试用——无需克隆或设置。它会以 MCP stdio 服务的形式运行一个临时演示（临时数据库 + 示例知识，退出时删除）：

docker run --rm -i ghcr.io/memokar/brainy:latest --demo

如需正式安装，请运行服务（预构建镜像会在每次发布时推送）：

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

或者使用 Compose 自行构建：

git clone https://github.com/memokar/brainy.git
cd brainy
docker compose up -d
docker compose logs brainy   # prints your one-time ADMIN token on first start

Brainy 现在会在 http://127.0.0.1:8765 上监听（MCP 端点：/mcp，管理界面：/admin — 使用令牌登录）。如需连接远程 AI 连接器，请将其置于 HTTPS 后方（参见 deploy/nginx-brainy.conf.example），并设置 BRAINY_PUBLIC_BASE_URL。

快速开始（裸机，Linux，Python ≥ 3.10）

export BRAINY_DB_PATH=$PWD/data/brainy.db
export BRAINY_KNOWLEDGE_ROOT=$PWD/data/knowledge
export 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 once
python3 scripts/init_prod_db.py "$BRAINY_DB_PATH"             # seeds default spaces
python3 scripts/serve.py

连接 AI

• Claude Code：

  claude mcp add --transport http brainy http://127.0.0.1:8765/mcp --header "Authorization: Bearer <token>"
  

• 本地 stdio 客户端（例如 Claude Desktop）： 将 Brainy 作为子进程运行：

  {"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>"}}}}
  

  无需任何设置即可试用：python3 scripts/stdio.py --demo（临时数据会在退出时删除）。
• 任何支持自定义请求头的其他 MCP 客户端： 端点 https://<your-host>/mcp，请求头 Authorization: Bearer <service token>。
• Claude.ai / ChatGPT 远程连接器： 使用 OAuth 2.1 流程（通过 /.well-known/oauth-authorization-server 发现）。将 BRAINY_PUBLIC_BASE_URL 设置为你的 HTTPS URL。

Brainy 已列入官方 MCP Registry，标识为 io.github.memokar/brainy。

为每个 AI 创建独立主体（例如 claude、chatgpt），赋予 AGENT 角色，并仅授予其所需的空间。这样，每项操作都会以相应名称记录在审计日志中。

示例：同一代码库中的两个编码 Agent

在同一个代码库中工作的两个 Agent 可能会互相覆盖对方的文件。通过资源认领， 每个 Agent 都可以预留即将修改的区域——每个空间对应一个自由格式的键——而另一个 Agent 则会等待，直到预留被释放或租约到期：

// Agent A, before editing the auth code:
claim_resource   { "space": "shared", "resource_key": "repo:app/src/auth/**", "lease_seconds": 1800 }
// -> { "claim_token": "…", "lease_until": "…" }   A now owns that area

// Agent B, about to touch the same area:
claim_resource   { "space": "shared", "resource_key": "repo:app/src/auth/**" }
// -> Conflict: already claimed  → B picks a different area (e.g. "repo:app/src/api/**")

renew_resource   { "space": "shared", "resource_key": "repo:app/src/auth/**", "claim_token": "…" }   // A keeps working
release_resource { "space": "shared", "resource_key": "repo:app/src/auth/**", "claim_token": "…" }   // A done → free again
list_resource_claims { "space": "shared" }   // who holds what right now

与任务认领的保障相同——同一时间恰好只有一个持有者，租约到期后会自动释放 （参见 tests/test_resources.py）。资源认领复用任务 权限/范围（can_claim_tasks / brainy:tasks:write），因此任何可以认领任务的 Agent 都可以 认领资源。

配置

所有配置均来自环境变量——参见 .env.example。 密钥（令牌、密钥）绝不会存储在代码库或知识库中。

扩展

核心版本提供了工作器插件接口和确定性的 MockWorker。让 Agent 能够自主执行任务的真实工作器 （例如 Claude Code、Codex）是通过 BRAINY_WORKER_PLUGINS 加载的独立扩展。参见 docs/extensions.md。

运行测试

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

状态与路线图

Brainy 已在其作者的生产环境中运行。目前的局限：

• 代码注释仍有部分是德语；所有面向用户的文本均为英语。
• 单节点设计（SQLite）。只有出现真实的多写入器负载时，才会考虑 PostgreSQL。

许可证

版权所有 (C) 2026 Mehmet Karakolcu

Brainy 采用双重许可：

• 开源：GNU AGPL-3.0。所有人均可免费使用，包括公司——但如果你修改 Brainy 并将其提供给他人（包括作为网络服务），就必须根据 AGPL 发布你的修改。
• **商业许可证：**供希望在不受 AGPL 义务约束的情况下使用或嵌入 Brainy 的公司使用。 参见 COMMERCIAL.md。

贡献者必须同意贡献者许可协议。

Footnotes

1. Beads — https://github.com/steveyegge/beads（MIT，Go；将问题存储在 Dolt 中。Dolt 是一个版本控制型 SQL 数据库；早期版本使用 SQLite + JSONL）。 ↩

2. NeuroAIgent 推出的 Central Brain — https://neuroaigent.ai（本地优先的 AI 记忆，支持 Windows + Apple 芯片 macOS，并集成 MCP；截至撰写时，网站标示的价格为：个人版 $12/月，4 个许可证 $35/月）。 ↩