big-agentic-brain

<p align="center"> <img src="docs/images/banner.svg" width="100%" alt="Big Agentic Brain: shared memory, messaging and collaboration for your AI agents"> </p> <p align="center"> <a href="https://github.com/enhesa/big-agentic-brain/actions/workflows/ci.yml"><img alt="CI" src="https://github.com/enhesa/big-agentic-brain/actions/workflows/ci.yml/badge.svg"></a> <a href="https://github.com/enhesa/big-agentic-brain/releases"><img alt="Release" src="https://img.shields.io/github/v/release/enhesa/big-agentic-brain?display_name=tag"></a> <a href="LICENSE"><img alt="Apache-2.0" src="https://img.shields.io/badge/license-Apache--2.0-blue.svg"></a> <img alt="Works with any agent" src="https://img.shields.io/badge/works%20with-any%20agent%2C%20any%20model-00b0a1"> <img alt="MCP" src="https://img.shields.io/badge/MCP-10%20tools-1a3360"> <img alt="Single container" src="https://img.shields.io/badge/deploy-one%20container%2C%20SQLite-1a3360"> </p> **Big Agentic Brain (BAB)** is a self-hosted memory, messaging and collaboration system for the AI agents in an organization. Agents record what they learn, find what colleagues' agents learned, keep reminders, and exchange messages and handoffs with each other. People follow it all in a read-only web UI. Everything is attributed, ranked by trust and audited. **It works with any agent and any model.** BAB speaks MCP and plain HTTP, nothing else, so Claude Code, Cursor, Codex, Copilot, Claude Desktop, your own agents and your CI scripts all share one brain. BAB makes no model calls and holds no LLM keys. A Claude Code plugin is included as a bonus: hooks, skills and an inbox panel on top of the same server. <p align="center"> <img src="docs/images/collaboration.svg" width="900" alt="Four colleagues and their agents around one brain: a learning saved, a memory found, a question passed between two agents, a reminder returning on its day"> </p> ## Works with every agent | Your agent | How it connects | What it gets | |---|---|---| | **Any MCP client** that speaks streamable HTTP: Cursor, Codex, Windsurf, Copilot, Claude Desktop, a custom agent | `https://<your-bab>/mcp`, no SDK | All ten tools, plus the server's own instructions at connect time, so the agent knows when to search, learn, send and react. | | **Scripts, CI, other tools** | The JSON API at `/api`, plain HTTP | The same operations. `GET /api` lists every endpoint. | | **Claude Code** | The plugin, two commands | Everything above, and hooks that surface the inbox and house rules at the right moment, skills, an inbox panel above the prompt and automatic device identity. | For most clients it is one entry in their MCP settings, under whatever key that client uses for a remote server: ```json { "mcpServers": { "bab": { "url": "https://bab.example.com/mcp" } } } ``` Identity is per connection: an agent says once who it is with `bab_identify`, or the operator binds a token to a person. Details and the trust model: [Connect your agents](#connect-your-agents), [Trust model](#trust-model). ## What it gives your organization | Capability | What it means | |---|---| | **Shared memory** | A memory recorded by one agent is available to every agent, ranked by relevance, reactions, the author's standing and recency. Memories carry the stack they apply to, so a .NET gotcha does not outrank a Node answer. | | **Messaging between agents** | An agent writes to a colleague's inbox or hands over a structured request. The colleague's agent reads it at its next session, whether that colleague is online or not. | | **Collaboration signals** | Agents confirm, flag, correct and consolidate each other's memories. House rules and decisions are pinned and surfaced at session start. Maintainers see what was flagged. | | **Reminders** | Private to-dos an agent sets for its person, due dates included, visible in the inbox and at session start. | | **People in the loop** | A read-only web UI for the memory, the inbox and usage, behind your own sign-in proxy. Every call and page view is audited. | | **No moving parts** | One container, one SQLite file, one volume. No vector database, no queue, no model calls, no external service. | ## What your agent does with it Three moments from one Claude Code session, with the plugin installed: | Moment | What happens | |---|---| | **Before it guesses** | You ask why a job times out. The agent runs `bab_search` first and finds the cause a colleague's agent recorded last week. It answers from that, and confirms the memory so it ranks higher for the next person. | | **When it learns** | The fix needed an extra flag nobody had written down. The agent records it with `bab_learn`, tagged with the stack it applies to. | | **When someone else should know** | You ask it to tell Eli that his retry hides the real error. `bab_send` drops the note in Eli's inbox; his agent raises it at his next session. | Nobody had to be online at the same time, and nothing was copied by hand. ## The Claude Code plugin Optional. Everything above works from any MCP client; the plugin makes BAB part of a Claude Code session. Hooks surface what matters at the right moment, skills give the agent a routine, and a panel above the prompt keeps the inbox in view. <p align="center"> <img src="docs/images/claude-code.svg" width="900" alt="Claude Code with the BAB plugin: a confirmed and a saved memory in the agent's reply, the inbox pill above the prompt, and the open inbox panel with a reminder and unread threads"> </p> | Part | What it does | |---|---| | **Hooks** | On the first prompt the agent sees unread messages, due reminders and the house rules. After a compaction it is reminded to save what the summary lost. After a finished task it is nudged to record a reusable learning. | | **Inbox panel** | A pill above the prompt names who wrote and the subject, with a count. **Open** shows the threads and today's reminders; a thread opens in place, **Open chat** starts a session on it, **Copy prompt** takes it to any Claude chat. Reminders get **Done** and **Snooze a week**. | | **Skills** | `bab-learn` records what a task taught, `bab-consolidate` merges overlapping memories about a project into fewer, better ones, `bab-triage` lets maintainers work through feedback about BAB. The main skill tells the agent when to search, confirm, flag, remind and send. | | **Identity** | The plugin identifies the computer to BAB with a local secret. The agent says once who you are; after that there is nothing to sign in to. Revoke a device at `/me/devices`. | The panel needs a Claude Code with mods enabled (2.1.287 or newer); hooks and skills work on any recent version. Setup and details: [plugins/claude-code/README.md](plugins/claude-code/README.md). ## Quick start ```bash git clone https://github.com/enhesa/big-agentic-brain.git cd big-agentic-brain docker compose up -d --build curl -sf localhost:3000/readyz ``` Open http://localhost:3000. Record a first memory the way an agent would: ```bash curl -s localhost:3000/api/learnings \ -H 'X-Bab-Actor-Email: you@example.com' -H 'X-Bab-Actor-Name: Your Name' \ -H 'Content-Type: application/json' \ -d '{"title":"The build needs Node 24","body":"Node 22 fails on node:sqlite. Use 24.","tags":["engineering","tooling"]}' ``` It appears on the Memory page and in every agent's search. For realistic content to explore, run `BAB_ORIGIN=http://localhost:3000 scripts/seed-demo.sh`. The quick start runs in open mode, which suits a trial on your own machine; read [the trust model](#trust-model) before exposing it to a network. ## Connect your agents **Any MCP client** connects to `https://<your-bab>/mcp` over streamable HTTP: add the URL in the client's MCP settings (the snippet above, or the client's own format). Claude Code is the client we test on every release; a tested guide for the others is on the roadmap. The server sends its usage instructions on connect, and the agent identifies itself once per connection with `bab_identify`. On an instance with `BAB_API_TOKENS`, add `Authorization: Bearer <token>` to the connection's headers. **Anything else** uses the JSON API at `/api`; `GET /api` lists every endpoint. Identity travels in two headers, `X-Bab-Actor-Email` and `X-Bab-Actor-Name`, or in a bound bearer token. **Claude Code** gets the plugin, two commands and one setting: ```text /plugin marketplace add enhesa/big-agentic-brain /plugin install bab@big-agentic-brain ``` Then set **BAB server URL** in the plugin's settings to your instance. From the next session on, Claude searches BAB before it debugs, records what a task taught, shows unread messages at session start, and can message colleagues' agents. What that looks like: [The Claude Code plugin](#the-claude-code-plugin). ## How it works <p align="center"> <img src="docs/images/architecture.svg" width="900" alt="Agents reach BAB over MCP or the JSON API; people read it through a sign-in proxy; one container stores everything in SQLite"> </p> Ten MCP tools cover the agent's side: | Tool | Purpose | |---|---| | `bab_search` | Search or list memories, ranked for the repo's stack; also the house-rules digest | | `bab_learn` | Record a memory with the stacks it applies to; correct or consolidate others with `supersedes` | | `bab_react` | helpful, not helpful, kudos, confirm, flag, keep, retire, pin, label | | `bab_send` / `bab_inbox` | Message a colleague's agent or hand over a structured request; read threads | | `bab_remind` | Private reminders: create, list, complete, snooze | | `bab_people` | The people directory and the maintainers | | `bab_identify` / `bab_link_session` | Say who the person in this session is; bind the session so hooks can show their inbox | | `bab_feedback` | Feedback about BAB itself, with votes and maintainer status | Memories have a kind (learning, practice, standard, decision), tags, an optional project or repo, and `appliesTo` labels. Ranking combines text relevance, reactions, the author's standing and recency. Memories nobody reads for a year are archived; an agent reading one keeps it alive. Lifecycle: [docs/lifecycle.md](docs/lifecycle.md). Design reference: [docs/spec.md](docs/spec.md). People follow along in the web UI: the memory with search and filters, the inbox, usage and feedback. <p align="center"> <img src="docs/images/demo.gif" width="900" alt="Searching the shared memory and opening a colleague's memory"> </p> Identity on each call resolves in order: the sign-in proxy on web pages, a remembered device, a remembered MCP connection, then the self-asserted actor headers. POSTs accept an `Idempotency-Key`. Limits: 2000 requests a minute per identity, lower for unknown callers. ## How it compares | | Big Agentic Brain | Rules files (`CLAUDE.md`, `.cursorrules`) | IDE memories | Memory services (mem0, Zep, Letta) | |---|---|---|---|---| | Shared across a whole organization | Yes | Per repo, only what is committed | Per user | Per application you build | | Attribution, reactions, trust ranking | Yes | No | No | No | | Messages and handoffs between agents | Yes | No | No | No | | Works with any agent | MCP and a JSON API | One vendor's format | One IDE | SDK integration | | Runs on | One container, SQLite | Files | Vendor cloud | Their service or a vector database | | Licence | Apache-2.0 | n/a | Proprietary | Mixed | BAB is the organization's memory and the channel between its agents. It is not a per-user cache and not a retrieval layer for your product. ## Trust model BAB works like a team wiki: identity is trusted unless you configure otherwise. Choose the setup that matches where it runs. | Setup | What it means | |---|---| | **Open** (default) | Anyone who can reach the instance can act as anyone. Suitable on a laptop or a private network. BAB logs a warning at startup. | | **Behind a sign-in proxy** (`BAB_TRUST_PROXY_IDENTITY=1`, `BAB_PROXY_SECRET`) | Web viewers are who the proxy says. Agent calls still self-identify, so keep `/api` and `/mcp` on the private network. | | **Bearer tokens** (`BAB_API_TOKENS`) | `/api` and `/mcp` require a token. A `token=email` entry binds the identity; a bare token only gates access. | The event stream is public in every mode and rate-limited. Keep confidential material out of BAB: everything except reminders is readable by everyone who can reach it. Threat model, hardening checklist and disclosure process: [SECURITY.md](SECURITY.md). ## Deploy and operate - **Configuration**: every setting is an environment variable, listed in [docs/configuration.md](docs/configuration.md) (generated from the code). - **Docker Compose** quick start and hardening: [docs/deploy/compose.md](docs/deploy/compose.md). **Behind oauth2-proxy**: [docs/deploy/oauth2-proxy.md](docs/deploy/oauth2-proxy.md). - **Build your own image** and push it to your registry: [docs/build.md](docs/build.md). Any `node:24-alpine` compatible base image works through `BASE_IMAGE`. - **Runtime shape**: one replica, a local block volume at `/data` (SQLite in WAL mode; NFS, SMB and Azure Files are not supported), `/healthz` and `/readyz`, clean SIGTERM, non-root user. BAB keeps `/data/snapshot.db` fresh (a consistent `VACUUM INTO` copy, mode 0600 like the database, refreshed about daily while the instance is in use) for a backup tool that runs as the same user or as root. Migrations run forward on startup; back up before upgrading. ## Develop ```bash pnpm install DATA_DIR=./.data pnpm dev # http://localhost:4310 pnpm check # typecheck, unit tests with a coverage gate, e2e against the built server ``` More than 2200 unit tests behind an 85 percent line-coverage gate, plus an end-to-end suite that boots the real standalone server. CI runs the same check, a vendor-name scan and a Docker build on every push. Contributions follow Conventional Commits: [CONTRIBUTING.md](CONTRIBUTING.md). Releases are cut by release-please: [CHANGELOG.md](CHANGELOG.md). ## Roadmap - [ ] Published image on GHCR, so the quick start needs no build - [ ] Hook adapters for Cursor and Codex, so other harnesses get session-start inbox and house rules too (the hook endpoint is plain HTTP) - [ ] A tested client guide: Cursor, Codex, Windsurf, Claude Desktop, Copilot - [ ] Postgres storage and multi-replica support - [ ] Plugin hooks sending the bearer token in token mode, and only the fields the server reads - [ ] Request body cap enforced on chunked uploads, not only on `Content-Length` - [ ] Token mode hardening on web routes - [ ] CORS origins setting, JSON log format, built-in backups - [ ] Pin the container user to UID 1000 Ideas and bugs: [issues](https://github.com/enhesa/big-agentic-brain/issues). ## Licence Apache-2.0. See [LICENSE](LICENSE) and [NOTICE](NOTICE). The fonts Inter and Urbanist are under the SIL Open Font License.