🧠➡️⚙️ BrainOS v2 — Cognitive Runtime

BrainOS is a cognitive runtime for long-lived AI agents, inspired by computational principles of human memory.

Beyond the knowledge base and plugins below, BrainOS now ships a runtime (brainos_runtime/) that coordinates memory, retrieval, working memory, learning and safety behind one small API — so an agent can remember better, reason better, learn from experience, use less context, recover from mistakes, and stay safe over long periods. Each component's contribution is measured by an ablation study, and the neuroscience mappings now carry explicit epistemic status.

from brainos_runtime import BrainOS

brain = BrainOS(actor_id="alex")
brain.observe("The production database is PostgreSQL 16")
brain.recall("what database do we use?")   # -> ["The production database is PostgreSQL 16"]

Start here: v2 Overview · Quickstart · Cognitive Runtime · Memory Model · Retrieval · Learning · Security · Evaluation

🚦 Getting Started (Step by Step)

New here? Pick the path that matches your goal. All three run offline with no API keys.

Prerequisites

• Python 3.10+ (3.10–3.12 are CI-tested; 3.13 works locally).
• git, pip, and optionally make (the Makefile just wraps the commands below).

Check your version:

python --version    # should be 3.10 or newer

Step 1 — Get the repo

git clone https://github.com/niravvaghasiya/BrainOS.git
cd BrainOS

Step 2 — Choose your path

# 1. install the package (ships the runtime + the plugin CLI), then optionally
#    generate the plugins the runtime prefers (it falls back to built-in
#    equivalents if you skip `brainos add all`).
pip install -e . && brainos add all

# 2. verify your environment is healthy
python -m brainos_runtime.cli doctor

# 3. run your first agent turns in a Python shell
python

from brainos_runtime import BrainOS

brain = BrainOS(actor_id="alex")
brain.observe("The production database is PostgreSQL 16")
brain.observe("Deploys happen on Fridays at 5pm")

brain.recall("what database do we use?")
# -> ["The production database is PostgreSQL 16"]

# It knows what it doesn't know:
brain.decide("what is the on-call rotation?")   # -> "ask"

# Explain its reasoning:
brain.why("when do deploys happen?")             # per-signal retrieval breakdown
print(brain.trace(formatted=True))               # step-by-step cognitive trace

pip install brainos-cli        # from PyPI
brainos list                   # see all 12 plugins
brainos init                   # scaffold brainos_plugins/, config/, tests/
brainos add hippocampal-index --with-config --with-tests
brainos add all                # or add everything at once
brainos info hippocampal-index # details on any plugin

01_sensory_buffer/README.md → mechanisms.md → examples.md → failures.md

Step 3 — Verify everything works

make install     # pip install -e .  + brainos add all
make test        # run the full test suite (316 tests)
make demo        # interactive memory-agent chat (Ctrl+C to exit)
make benchmark   # reproduce the token-savings numbers
make lint        # ruff

No make? Run the equivalents directly, e.g. python -m pytest tests/ -q, python -m brainos_runtime.cli eval.

Step 4 — Go deeper

🤔 What Is This?

BrainOS treats the human brain as a software system and documents it like one:

No paywall. No fluff. 116 markdown files of structured knowledge — plus a working cognitive runtime (brainos_runtime/) you can drop into an agent today.

Demo

An AI agent using sensory-gate + hippocampal-index + working-memory + forgetting-engine — retrieving conversation context from 20 turns ago in under 200ms. Run it yourself with make demo (see Try It Live below).

⚡ Install

Via pip (live on PyPI)

pip install brainos-cli

# See all 12 plugins
brainos list

# Initialize project structure
brainos init

# Add a specific plugin (generates working Python class + config + tests)
brainos add sensory-gate --with-config --with-tests

# Add all plugins at once
brainos add all

# Get details about any plugin
brainos info hippocampal-index

Or just clone the knowledge base

Clone and explore — zero dependencies, pure markdown:

git clone https://github.com/niravvaghasiya/BrainOS.git
cd BrainOS

Each plugin in _plugins/ is a complete architecture spec. The CLI generates starter code from these specs into your project.

🚀 Try It Live

Runnable, dependency-light examples that use the generated plugins end to end:

More resources:

• Integration Guide — wire BrainOS plugins into LangChain, LangGraph, CrewAI, or vanilla Python.
• Diagrams — architecture overview, information flow, brain vs. AI.

Common tasks are wrapped in a Makefile: make install, make test, make lint, make demo, make benchmark.

📐 Architecture

The brain's information storage system, mapped as 8 numbered modules + 4 support systems:

brainos/
│
├── 01_sensory_buffer/          → Input preprocessing (200ms–3s buffer)
├── 02_working_memory/          → Active workspace (4±1 slots, 15–30s)
├── 03_hippocampus/             → Indexer & Consolidation Router
├── 04_long_term_memory/        → Permanent distributed storage (~2.5 PB)
│   ├── explicit_declarative/   → Conscious recall (episodic + semantic)
│   └── implicit_nondeclarative/→ Unconscious (procedural + priming + conditioning)
├── 05_emotional_tagging/       → Priority scoring (amygdala)
├── 06_motor_memory/            → Cerebellum (body autopilot)
├── 07_language_networks/       → Broca + Wernicke (speech/comprehension)
├── 08_default_mode_network/    → Background processing (creativity, simulation)
│
├── _system/                    → Infrastructure (neurotransmitters, sleep, plasticity)
├── _flows/                     → Information pathways between systems
├── _techniques/                → Evidence-based learning methods
├── _plugins/                   → Brain-inspired AI/Agent component specs
│
├── brainos_runtime/            → 🆕 v2 Cognitive Runtime (the product)
│   ├── core/                   → kernel: events, cycle, state, BrainOS facade
│   ├── memory/                 → canonical schema + temporal memory
│   ├── retrieval/              → multi-signal retrieval engine + metrics
│   ├── cognition/              → typed working memory + metacognition
│   ├── learning/               → consolidation, forgetting, beliefs, outcomes
│   ├── security/               → trust, tenant isolation, injection defense
│   ├── storage/                → InMemory / SQLite / Postgres backends
│   ├── observability/          → session tracing + why() explanations
│   ├── adapters/               → vanilla / LangGraph / MCP
│   ├── evidence/               → neuroscience epistemic-status layer
│   └── cli.py                  → runtime CLI (python -m brainos_runtime.cli)
├── brainos_eval/               → 🆕 evaluation suite + ablation + long-running
│
├── cli/                        → pip-installable plugin CLI (brainos add <plugin>)
├── examples/                   → Runnable demos (memory agent, benchmark, runtime, adapters)
├── tests/                      → pytest suite (316 tests: plugins + runtime + eval)
└── docs/                       → v2 docs, integration guide, diagrams, baseline

Every module contains:

• README.md — What it does and how it works
• mechanisms.md — Biological machinery (molecular → circuit level)
• examples.md — Real-world demonstrations and experiments
• failures.md — Disorders, decay, and what breaks

🔌 Plugins: Brain-Inspired AI Components

The killer feature. Each brain system is translated into an installable architecture component for AI agents.

Benchmarked Results

Measured on a simulated 50-turn agent conversation (see examples/02_token_benchmark/), counted with tiktoken cl100k_base:

Real, reproducible numbers from examples/02_token_benchmark/. Run it yourself: make benchmark. The naive baseline grows tokens O(n²) (each call resends all history); the full stack keeps it O(n) by bounding context.

Quick Start: Which plugins solve your problem?

Context window overflows?     → sensory-gate + attention-filter + forgetting-engine
Agent forgets conversations?  → episodic-store + consolidator
Redundant tool calls?         → procedural-cache + working-memory
Can't find relevant context?  → hippocampal-index + salience-tagger
No self-improvement?          → metacognition + dmn-incubator

Each plugin includes a Python interface, implementation patterns, YAML config, and integration examples.

🛠️ Techniques: Evidence-Based Methods

For humans who want to learn better — backed by the neuroscience in this repo.

🔀 Flows: Information Pathways

How data moves BETWEEN systems — from first contact to permanent storage to recall.

📊 Key Principles

📈 By the Numbers

🧭 How to Navigate

I want to understand a brain region:

01_sensory_buffer/README.md → mechanisms.md → examples.md → failures.md

I want to build better AI memory:

_plugins/README.md → Pick your problem → Install the plugin(s)

I want to study more effectively:

_techniques/README.md → Pick by effectiveness rating → Follow the protocol

I want to understand information flow:

_flows/README.md → Follow the numbered pathway → See cross-system interactions

I want to build an agent with the v2 runtime:

docs/v2/QUICKSTART.md → python -m brainos_runtime.cli doctor → from brainos_runtime import BrainOS

I want to run the code:

make install → make demo (chat agent) → make benchmark (token savings) → make test

🤝 Contributing

Contributions welcome! See CONTRIBUTING.md for guidelines.

Areas especially open for contribution:

• 🔬 Additional research citations and experiment descriptions
• 🧪 More framework integrations and example apps (LlamaIndex, Autogen, ...)
• 📊 Diagrams and visualizations of pathways
• 🌍 Translations
• 🧑‍⚕️ Clinical case studies for the failures.md files

📄 License

MIT License — see LICENSE. Use freely, build on it, credit appreciated.

⭐ Star History

If this helped you understand brains, build better AI, or study more effectively — consider starring the repo.