aibrain 1.8.1

AI agent brain with memory, teams, flows, document ingestion, and MCP — your agent, but better every day

AIBrain — Self-compounding agent substrate with persistent memory and multi-agent fleet

80.0% recall on LongMemEval M with a 109M model. 99.8% on MSDialog. Zero-parameter FTS5 achieves 96.9% NDCG@5 on dialogue retrieval. All on a consumer laptop, no GPU required. One install. 80 workflows. Agent teams. Flow engine. Document ingestion. Universal MCP. Dual-system memory that compounds across sessions. Runs locally, no cloud lock-in.

AIBrain is a self-hosted memory substrate and fleet orchestration layer for AI agents. It gives any agent persistent memory, typed task composition, and inter-agent communication — designed to install alongside agents like Hermes, not replace them. The architectural bet: compounding comes from a fleet of cooperating agents, not from one agent alone.

Shipped: Dual-system memory (CLS), 80 workflows, multi-model routing, 42-page dashboard, MCP server, inter-agent comms backbone (CloudEvents pub/sub), agent spawn infrastructure. Specced, filed, targeted v1.7-v1.9: Cross-agent handoff verification loop, agent skill marketplace integration, fleet compounding demonstrations. Design target v2.0: Self-compounding fleet.

AIBrain is a self-hosted operating system for AI agents. It gives any agent persistent memory, typed Agent/Task/Team composition, a decorator-driven Flow engine, document ingestion, universal MCP client connectivity, a reactive workflow engine, a Complementary Learning Systems (CLS) cognitive substrate with a weekly consolidation cycle, multi-model LLM routing, an approval queue, inter-agent messaging, and 80 ready-to-run workflows — all behind a 42-page Next.js dashboard. Deploy it on a laptop, a VPS, or in Docker; your agent carries its entire brain with it.

---

Why AIBrain?

Most AI memory systems are toys. They store everything, retrieve nothing useful, and require expensive GPUs to run. AIBrain is different:

• Verified retrieval performance. On LongMemEval M (500 instances, the standard benchmark for long-term conversational memory), AIBrain's SelRoute system achieves Ra@5 = 0.800 with a 109M bge-base model — beating the strongest published baseline (Contriever + LLM fact keys, 0.762) by +0.038 on recall and +0.180 on NDCG@5. A 22MB MiniLM model achieves Ra@5 = 0.785, statistically equivalent to models 50% larger. The zero-parameter FTS5 baseline (zero trainable parameters, zero GPU) achieves NDCG@5 = 0.692 on LongMemEval M, exceeding every published system including 1.5B-parameter models.
• Near-perfect on domain-specific retrieval. On MSDialog (2,199 tech-support dialogues), AIBrain achieves Ra@5 = 0.998 with a 22MB MiniLM model — near-perfect retrieval for technical support contexts.
• Zero-parameter dialogue retrieval. On LMEB dialogue (840 instances), the FTS5 zero-ML retriever achieves NDCG@5 = 0.971 — no neural parameters, no GPU, no training data.
• Total evaluation instances: 62,792+. Every number is from verified JSON files in the benchmarks/ directory. The methodology is described in the peer-reviewed SelRoute paper (McKee, 2026, arXiv:2604.02431).
• All benchmarks run on a consumer laptop. No GPU required. No cloud credits. No special hardware.

The secret is the CLS architecture: a Complementary Learning Systems dual-system memory inspired by the mammalian brain. Every session writes to fast hippocampal memory. A weekly aibrain dream consolidation cycle slow-extracts patterns and upgrades routing weights. The brain gets measurably better at subsequent tasks — not just stores more.

---

What's New in v1.6.1

• Multi-agent fleet infrastructure shipped. 4 keystone specs: F-COMMS-1 (CloudEvents pub/sub + direct-RPC), F-FIX-AGENT-1 (always-on Fix-Agent), F-AGENT-TEMPLATE-1 (reusable agent template), F-AGENT-SPAWN-1 (agent spawn CLI + daemon). 7 agents registered. Cross-agent handoff 5/5 validated.
• SA-2026-002 security audit complete. 32 fixes across 29 commits. 3 CRITICAL + 20 HIGH findings resolved.
• Lucy autonomy. Multi-root path confinement. LLM-callable task creation. Lucy ships as a thin pip install lucy wheel that installs on top of aibrain==1.8.1 (separate-but-synergistic — sum greater than the parts). Full code-independence (Lucy without aibrain) is on the next-update roadmap. Currently DeepSeek-proven; broader provider support in progress.
• Previously in v1.5.39-v1.5.40: 8 carry-forward fixes, HardenedSession, MCP connection pool, FTS lazy migrate, encryption fail-open fix.

Install

Pick the path that matches your environment. All paths install the same package from PyPI.

One-line installer (macOS / Linux / WSL)

curl -sSL https://myaibrain.org/install | sh

Creates an isolated venv at ~/.aibrain/venv, pip-installs aibrain, and symlinks the CLI into /usr/local/bin (or ~/.local/bin fallback). Re-run any time to upgrade. Python 3.10+ required.

One-line installer (Windows PowerShell)

irm https://myaibrain.org/install.ps1 | iex

Creates an isolated venv at %USERPROFILE%\.aibrain\venv, pip-installs aibrain, and adds the venv Scripts dir to your user PATH. Python 3.10+ required.

Homebrew (macOS / Linux)

brew tap sindecker/tap
brew install aibrain

Installs into a Homebrew-managed venv and symlinks the CLI.

pip (any platform)

pip install aibrain

Docker

docker pull sindecker/aibrain:latest

---

Telegram Quickstart (BotFather)

Lucy can run as a Telegram bot you can DM.

1. Open Telegram, message @BotFather, send /newbot, choose a name and username. BotFather returns an HTTP API token — copy it.
2. Set the bot token as an environment variable:
   • Linux/macOS: export LUCY_TELEGRAM_TOKEN=<your-token>
   • Windows Command Prompt: set LUCY_TELEGRAM_TOKEN=<your-token>
   • PowerShell: $env:LUCY_TELEGRAM_TOKEN="<your-token>"
3. Set your DeepSeek API key (Lucy is currently DeepSeek (proven); broader provider support in progress):
   • Linux/macOS: export DEEPSEEK_API_KEY=<your-key>
   • Windows Command Prompt: set DEEPSEEK_API_KEY=<your-key>
   • PowerShell: $env:DEEPSEEK_API_KEY="<your-key>"
4. Start the Telegram poller:

   python -m aibrain.lucy_telegram
   

5. DM your new bot on Telegram. Messages will route through the real Lucy agent.

Run Lucy in the terminal instead

To use Lucy interactively in your terminal, run:

lucy

For autonomous goal-driven runs, start an interactive session and use the /loop command:

/loop --project <name> --goal "<goal>"

Note: Lucy does not accept a goal as a command-line argument. Always use the /loop command inside the interactive session for autonomous tasks.

Quick Start

# Install
pip install aibrain

# Initialize your brain
aibrain init

# Start the server
aibrain serve

# Open the dashboard
open http://localhost:3000

Your agent now has persistent memory. Every conversation, every workflow, every decision is stored and retrievable. Run aibrain dream weekly to consolidate patterns and improve retrieval.

---

Benchmark Results

AIBrain's SelRoute retrieval system has been evaluated on 62,792+ instances across multiple benchmarks. All results are from verified JSON files in the benchmarks/ directory.

LongMemEval M (500 instances)

System	Parameters	Ra@5	NDCG@5
SelRoute bge-base (metadata routing)	109M	0.800	0.812
SelRoute bge-small (metadata routing)	33M	0.786	0.718
SelRoute FTS5 (zero-ML, zero-GPU)	0	0.745	0.692
all-MiniLM-L6-v2	22M	0.785	0.717

LongMemEval S (500 instances)

System	Parameters	Ra@5
SelRoute bge-base	109M	0.920
SelRoute Oracle	—	0.992

MSDialog (2,199 tech-support dialogues)

System	Parameters	Ra@5
SelRoute MiniLM	22M	0.998

LoCoMo (1,986 QA pairs)

System	Parameters	Recall@5	Ra@5
SelRoute FTS5 (zero-ML)	0	0.859	0.767

QReCC (52,678 conversational queries)

System	Parameters	MRR
SelRoute FTS5+reasoning	0	51.66

LMEB dialogue (840 instances)

System	Parameters	NDCG@5
SelRoute FTS5 (zero-ML)	0	0.971

Key findings:

1. A 22MB MiniLM model achieves Ra@5 = 0.785 on LongMemEval M — competitive retrieval with a model that fits in RAM on any device.
2. A zero-parameter FTS5 retriever achieves NDCG@5 = 0.971 on LMEB dialogue — no neural parameters, no GPU, no training data.
3. All benchmarks run on a consumer laptop. No GPU required.

---

Architecture

Complementary Learning Systems (CLS)

AIBrain implements a dual-system memory architecture inspired by the mammalian brain:

• Hippocampal fast encoding. Every session writes immediately to short-term memory. No indexing delay, no batch processing. Your agent remembers what just happened.
• Neocortical consolidation. A weekly aibrain dream cycle slow-extracts patterns from accumulated sessions, upgrades routing weights, and consolidates long-term knowledge. The brain gets measurably better at subsequent tasks.
• SelRoute routing. The SelRoute system (arXiv:2604.02431) routes each query to the optimal retrieval strategy — dense embedding, sparse FTS5, or hybrid — based on query characteristics. This is what enables a 22MB model to match 1.5B-parameter systems.

Boss Agent

Multi-agent orchestration with one orchestrator and multiple isolated workers sharing a single brain. Each worker has its own context, memory, and tool access, but all share the same persistent knowledge base.

Companies / RBAC

Full organizational hierarchy — agents, tasks, roles, and approval flows. Manage team access, delegate tasks, and enforce governance policies.

Brain Marketplace

Share or sell trained brains via git. Export your brain, push it to a repository, and let others import it. Brains carry learned patterns, routing weights, and consolidated knowledge.

Satellite DBs

Federated search across multiple brain instances. Query one brain and get results from all connected brains.

---

Pricing

Tier	Price	Features
Free	$0	Unlimited local usage. All features. No cloud dependency.
Pro	$9.95/mo	Priority support, early access to new features, cloud sync.
Team	$29.95/mo	Everything in Pro, plus RBAC, audit logs, dedicated support.

All tiers include the same core AIBrain software. The difference is support level and cloud features.

---

CLI Entrypoints

• aibrain — Main CLI
• aibrain-server — Start the backend server
• aibrain-mcp — MCP server
• aibrain-compress — SelRoute compression library (50-99% token savings on git/build/test output)
• aibrain-settings — Configure AIBrain
• aibrain-demo — Run a demo

---

License

Proprietary. See LICENSE file for details.

---

Contributing

See CONTRIBUTING.md for development setup and contribution guidelines.