memokar/brainy

**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.
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.
Why not just a markdown file?
A shared notes file in a Git repo is a great *knowledge* store — and Brainy keeps that part on
purpose: knowledge is plain Markdown in Git, with history, diff and rollback. The problem is
everything a bare file *doesn't* do once more than one agent touches it:
- **Two agents overwrite each other.** Nothing serializes concurrent writes to the same file.
Brainy writes go through optimistic concurrency (expected_git_commit) plus a server-side write
lock: exactly one writer commits, the others get a Conflict and re-read — no lost edits.
- **No task hand-off.** A file can list TODOs, but it can't stop two agents from grabbing the same
one. Brainy tasks use an **atomic claim** (UPDATE ... WHERE status='READY', one row): exactly
one agent wins, the rest get a conflict and move on.
- **No per-area permissions.** A file is all-or-nothing. Brainy has Spaces with per-space ACLs, so
an agent only reads/writes the areas you grant it.
- **No approval step.** Agents can *propose* changes for a human to approve (web UI or Telegram)
instead of writing straight to the source of truth.
- **"Who changed what?" beyond git blame.** Every action — reads of task state, claims, writes,
rejections — lands in an append-only audit log enforced by a DB trigger.
Both guarantees above are covered by a concurrency test
(tests/test_concurrency.py): 20 threads racing on one task yield
exactly **1 winner and 19 conflicts**, and 20 threads writing the same file yield exactly **1
commit and 19 conflicts**, with the repo left clean.
How is Brainy different?
Honest comparison with the tools people mention most. Beads is closest to Brainy's *task* side, and
Central Brain to its *knowledge* side; neither is a one-to-one match. Facts are from each project's
own docs (links below); where something isn't documented, it says so rather than guessing.
| | **Brainy** | **Beads** [^beads] | **Central Brain** [^cb] | **Shared notes file** |
|---|---|---|---|---|
| What it is | Knowledge base **+** task queue | AI-agent issue/task tracker | AI memory layer | Markdown in a repo |
| Knowledge store | Markdown in Git | — (issue tracker) | Plain files + local vector index | Markdown in Git |