# niravrvaghasiya/brainos architecture

> Architecture diagram of the GitHub repository niravrvaghasiya/brainos, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-26). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/niravrvaghasiya/brainos
- Repository: https://github.com/niravrvaghasiya/brainos
- Video tour (about a minute): https://gitdiagram.com/niravrvaghasiya/brainos/video

## Overview

BrainOS combines a cognitive runtime for long-lived AI agents with a plugin-scaffolding CLI. The main workflow is an agent submitting observations and queries through the BrainOS API: the runtime applies trust and tenant controls, maintains temporal memories, retrieves budgeted evidence, and assesses whether to answer or ask. Learning and forgetting support durable adaptation; adapters, storage backends, and tracing extend the runtime. The README documents these capabilities, but several implementations were not sampled, so their internal wiring is left unspecified.

Main entry points: [`brainos_runtime/core/runtime.py`](https://github.com/niravrvaghasiya/brainos/blob/main/brainos_runtime/core/runtime.py) (Runtime cycle), [`brainos_runtime/storage/base.py`](https://github.com/niravrvaghasiya/brainos/blob/main/brainos_runtime/storage/base.py) (Storage interface), [`brainos_runtime/learning/loop.py`](https://github.com/niravrvaghasiya/brainos/blob/main/brainos_runtime/learning/loop.py) (Learning loop), [`brainos_runtime/adapters/base.py`](https://github.com/niravrvaghasiya/brainos/blob/main/brainos_runtime/adapters/base.py) (Agent adapters)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Cognitive runtime"]
  node_api["BrainOS API<br/>[__init__.py]"]
  node_brain["Brain facade<br/>[brain.py]"]
  node_runtime_core["Runtime cycle<br/>[runtime.py]"]
  node_cycle["Cognitive cycle<br/>[cycle.py]"]
  node_events["Runtime events<br/>[events.py]"]
  node_working_memory["Working memory<br/>[working_memory.py]"]
  node_metacognition["Metacognition<br/>[metacognition.py]"]
end

subgraph group_memory["Memory and retrieval"]
  node_temporal["Temporal memory<br/>[temporal.py]"]
  node_schema["Memory schema<br/>[schema.py]"]
  node_retrieval["Retrieval engine<br/>[engine.py]"]
  node_storage["Storage interface<br/>[base.py]"]
  node_memory_store[("Memory store<br/>[memory_store.py]")]
  node_sqlite_store[("SQLite store<br/>[sqlite_store.py]")]
  node_postgres_store[("Postgres store<br/>[postgres_store.py]")]
end

subgraph group_learning_safety["Learning and safety"]
  node_trust["Trust policy<br/>[trust.py]"]
  node_beliefs["Belief conflicts<br/>[beliefs.py]"]
  node_learning_loop["Learning loop<br/>[loop.py]"]
  node_consolidation["Memory consolidation<br/>[consolidation.py]"]
  node_forgetting["Memory forgetting<br/>[forgetting.py]"]
end

subgraph group_integration["Integration and tools"]
  node_adapters["Agent adapters<br/>[base.py]"]
  node_langgraph["LangGraph adapter<br/>[langgraph.py]"]
  node_mcp["MCP adapter<br/>[mcp.py]"]
  node_vanilla["Vanilla adapter<br/>[vanilla.py]"]
  node_tracer["Session tracing<br/>[tracer.py]"]
  node_runtime_cli["Runtime CLI<br/>[cli.py]"]
  node_plugin_cli["Plugin CLI<br/>[cli.py]"]
  node_generator["Plugin generator<br/>[generator.py]"]
  node_plugins["Plugin loading<br/>[plugins.py]"]
end

node_agent(("AI agent"))

node_agent -->|"submits observations"| node_api
node_agent -->|"queries memories"| node_api
node_api -->|"exposes facade"| node_brain
node_brain -->|"coordinates runtime"| node_runtime_core
node_runtime_core -->|"runs cycles"| node_cycle
node_runtime_core -->|"checks trust"| node_trust
node_runtime_core -->|"updates memories"| node_temporal
node_runtime_core -->|"requests retrieval"| node_retrieval
node_runtime_core -->|"maintains context"| node_working_memory
node_runtime_core -->|"assesses evidence"| node_metacognition
node_retrieval -->|"reads candidates"| node_temporal
node_temporal -->|"stores memories"| node_schema
node_temporal -->|"persists memories"| node_storage
node_storage -->|"implements"| node_memory_store
node_storage -->|"implements"| node_sqlite_store
node_storage -.->|"implements"| node_postgres_store
node_runtime_core -->|"learns from experience"| node_learning_loop
node_learning_loop -->|"resolves conflicts"| node_beliefs
node_learning_loop -->|"consolidates memories"| node_consolidation
node_learning_loop -->|"prunes memories"| node_forgetting
node_agent -->|"integrates through"| node_adapters
node_adapters -.->|"specializes as"| node_langgraph
node_adapters -.->|"specializes as"| node_mcp
node_adapters -->|"specializes as"| node_vanilla
node_runtime_core -->|"exposes traces"| node_tracer
node_agent -->|"runs commands"| node_runtime_cli
node_agent -->|"scaffolds plugins"| node_plugin_cli
node_plugin_cli -->|"generates code"| node_generator
node_runtime_core -->|"loads components"| node_plugins

click node_api "https://github.com/niravrvaghasiya/brainos/blob/main/brainos_runtime/__init__.py"
click node_brain "https://github.com/niravrvaghasiya/brainos/blob/main/brainos_runtime/core/brain.py"
click node_runtime_core "https://github.com/niravrvaghasiya/brainos/blob/main/brainos_runtime/core/runtime.py"
click node_cycle "https://github.com/niravrvaghasiya/brainos/blob/main/brainos_runtime/core/cycle.py"
click node_events "https://github.com/niravrvaghasiya/brainos/blob/main/brainos_runtime/core/events.py"
click node_working_memory "https://github.com/niravrvaghasiya/brainos/blob/main/brainos_runtime/cognition/working_memory.py"
click node_metacognition "https://github.com/niravrvaghasiya/brainos/blob/main/brainos_runtime/cognition/metacognition.py"
click node_temporal "https://github.com/niravrvaghasiya/brainos/blob/main/brainos_runtime/memory/temporal.py"
click node_schema "https://github.com/niravrvaghasiya/brainos/blob/main/brainos_runtime/memory/schema.py"
click node_retrieval "https://github.com/niravrvaghasiya/brainos/blob/main/brainos_runtime/retrieval/engine.py"
click node_trust "https://github.com/niravrvaghasiya/brainos/blob/main/brainos_runtime/security/trust.py"
click node_beliefs "https://github.com/niravrvaghasiya/brainos/blob/main/brainos_runtime/learning/beliefs.py"
click node_learning_loop "https://github.com/niravrvaghasiya/brainos/blob/main/brainos_runtime/learning/loop.py"
click node_consolidation "https://github.com/niravrvaghasiya/brainos/blob/main/brainos_runtime/learning/consolidation.py"
click node_forgetting "https://github.com/niravrvaghasiya/brainos/blob/main/brainos_runtime/learning/forgetting.py"
click node_storage "https://github.com/niravrvaghasiya/brainos/blob/main/brainos_runtime/storage/base.py"
click node_memory_store "https://github.com/niravrvaghasiya/brainos/blob/main/brainos_runtime/storage/memory_store.py"
click node_sqlite_store "https://github.com/niravrvaghasiya/brainos/blob/main/brainos_runtime/storage/sqlite_store.py"
click node_postgres_store "https://github.com/niravrvaghasiya/brainos/blob/main/brainos_runtime/storage/postgres_store.py"
click node_adapters "https://github.com/niravrvaghasiya/brainos/blob/main/brainos_runtime/adapters/base.py"
click node_langgraph "https://github.com/niravrvaghasiya/brainos/blob/main/brainos_runtime/adapters/langgraph.py"
click node_mcp "https://github.com/niravrvaghasiya/brainos/blob/main/brainos_runtime/adapters/mcp.py"
click node_vanilla "https://github.com/niravrvaghasiya/brainos/blob/main/brainos_runtime/adapters/vanilla.py"
click node_tracer "https://github.com/niravrvaghasiya/brainos/blob/main/brainos_runtime/observability/tracer.py"
click node_runtime_cli "https://github.com/niravrvaghasiya/brainos/blob/main/brainos_runtime/cli.py"
click node_plugin_cli "https://github.com/niravrvaghasiya/brainos/blob/main/cli/brainos/cli.py"
click node_generator "https://github.com/niravrvaghasiya/brainos/blob/main/cli/brainos/generator.py"
click node_plugins "https://github.com/niravrvaghasiya/brainos/blob/main/brainos_runtime/core/plugins.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_api,node_brain,node_runtime_core,node_cycle,node_events,node_working_memory,node_metacognition toneBlue
class node_temporal,node_schema,node_retrieval,node_storage,node_memory_store,node_sqlite_store,node_postgres_store toneAmber
class node_trust,node_beliefs,node_learning_loop,node_consolidation,node_forgetting toneMint
class node_adapters,node_langgraph,node_mcp,node_vanilla,node_tracer,node_runtime_cli,node_plugin_cli,node_generator,node_plugins toneRose
class node_agent toneIndigo
```

## Components

### Cognitive runtime

- [BrainOS API](https://github.com/niravrvaghasiya/brainos/blob/main/brainos_runtime/__init__.py): `brainos_runtime/__init__.py`
- [Brain facade](https://github.com/niravrvaghasiya/brainos/blob/main/brainos_runtime/core/brain.py): `brainos_runtime/core/brain.py`
- [Runtime cycle](https://github.com/niravrvaghasiya/brainos/blob/main/brainos_runtime/core/runtime.py): `brainos_runtime/core/runtime.py`
- [Cognitive cycle](https://github.com/niravrvaghasiya/brainos/blob/main/brainos_runtime/core/cycle.py): `brainos_runtime/core/cycle.py`
- [Runtime events](https://github.com/niravrvaghasiya/brainos/blob/main/brainos_runtime/core/events.py): `brainos_runtime/core/events.py`
- [Working memory](https://github.com/niravrvaghasiya/brainos/blob/main/brainos_runtime/cognition/working_memory.py): `brainos_runtime/cognition/working_memory.py`
- [Metacognition](https://github.com/niravrvaghasiya/brainos/blob/main/brainos_runtime/cognition/metacognition.py): `brainos_runtime/cognition/metacognition.py`

### Memory and retrieval

- [Temporal memory](https://github.com/niravrvaghasiya/brainos/blob/main/brainos_runtime/memory/temporal.py): `brainos_runtime/memory/temporal.py`
- [Memory schema](https://github.com/niravrvaghasiya/brainos/blob/main/brainos_runtime/memory/schema.py): `brainos_runtime/memory/schema.py`
- [Retrieval engine](https://github.com/niravrvaghasiya/brainos/blob/main/brainos_runtime/retrieval/engine.py): `brainos_runtime/retrieval/engine.py`
- [Storage interface](https://github.com/niravrvaghasiya/brainos/blob/main/brainos_runtime/storage/base.py): `brainos_runtime/storage/base.py`
- [Memory store](https://github.com/niravrvaghasiya/brainos/blob/main/brainos_runtime/storage/memory_store.py): `brainos_runtime/storage/memory_store.py`
- [SQLite store](https://github.com/niravrvaghasiya/brainos/blob/main/brainos_runtime/storage/sqlite_store.py): `brainos_runtime/storage/sqlite_store.py`
- [Postgres store](https://github.com/niravrvaghasiya/brainos/blob/main/brainos_runtime/storage/postgres_store.py): `brainos_runtime/storage/postgres_store.py`

### Learning and safety

- [Trust policy](https://github.com/niravrvaghasiya/brainos/blob/main/brainos_runtime/security/trust.py): `brainos_runtime/security/trust.py`
- [Belief conflicts](https://github.com/niravrvaghasiya/brainos/blob/main/brainos_runtime/learning/beliefs.py): `brainos_runtime/learning/beliefs.py`
- [Learning loop](https://github.com/niravrvaghasiya/brainos/blob/main/brainos_runtime/learning/loop.py): `brainos_runtime/learning/loop.py`
- [Memory consolidation](https://github.com/niravrvaghasiya/brainos/blob/main/brainos_runtime/learning/consolidation.py): `brainos_runtime/learning/consolidation.py`
- [Memory forgetting](https://github.com/niravrvaghasiya/brainos/blob/main/brainos_runtime/learning/forgetting.py): `brainos_runtime/learning/forgetting.py`

### Integration and tools

- [Agent adapters](https://github.com/niravrvaghasiya/brainos/blob/main/brainos_runtime/adapters/base.py): `brainos_runtime/adapters/base.py`
- [LangGraph adapter](https://github.com/niravrvaghasiya/brainos/blob/main/brainos_runtime/adapters/langgraph.py): `brainos_runtime/adapters/langgraph.py`
- [MCP adapter](https://github.com/niravrvaghasiya/brainos/blob/main/brainos_runtime/adapters/mcp.py): `brainos_runtime/adapters/mcp.py`
- [Vanilla adapter](https://github.com/niravrvaghasiya/brainos/blob/main/brainos_runtime/adapters/vanilla.py): `brainos_runtime/adapters/vanilla.py`
- [Session tracing](https://github.com/niravrvaghasiya/brainos/blob/main/brainos_runtime/observability/tracer.py): `brainos_runtime/observability/tracer.py`
- [Runtime CLI](https://github.com/niravrvaghasiya/brainos/blob/main/brainos_runtime/cli.py): `brainos_runtime/cli.py`
- [Plugin CLI](https://github.com/niravrvaghasiya/brainos/blob/main/cli/brainos/cli.py): `cli/brainos/cli.py`
- [Plugin generator](https://github.com/niravrvaghasiya/brainos/blob/main/cli/brainos/generator.py): `cli/brainos/generator.py`
- [Plugin loading](https://github.com/niravrvaghasiya/brainos/blob/main/brainos_runtime/core/plugins.py): `brainos_runtime/core/plugins.py`

### Other components

- **AI agent**

## Connections

- AI agent → BrainOS API: submits observations
- AI agent → BrainOS API: queries memories
- BrainOS API → Brain facade: exposes facade
- Brain facade → Runtime cycle: coordinates runtime
- Runtime cycle → Cognitive cycle: runs cycles
- Runtime cycle → Trust policy: checks trust
- Runtime cycle → Temporal memory: updates memories
- Runtime cycle → Retrieval engine: requests retrieval
- Runtime cycle → Working memory: maintains context
- Runtime cycle → Metacognition: assesses evidence
- Retrieval engine → Temporal memory: reads candidates
- Temporal memory → Memory schema: stores memories
- Temporal memory → Storage interface: persists memories
- Storage interface → Memory store: implements
- Storage interface → SQLite store: implements
- Storage interface → Postgres store: implements
- Runtime cycle → Learning loop: learns from experience
- Learning loop → Belief conflicts: resolves conflicts
- Learning loop → Memory consolidation: consolidates memories
- Learning loop → Memory forgetting: prunes memories
- AI agent → Agent adapters: integrates through
- Agent adapters → LangGraph adapter: specializes as
- Agent adapters → MCP adapter: specializes as
- Agent adapters → Vanilla adapter: specializes as
- Runtime cycle → Session tracing: exposes traces
- AI agent → Runtime CLI: runs commands
- AI agent → Plugin CLI: scaffolds plugins
- Plugin CLI → Plugin generator: generates code
- Runtime cycle → Plugin loading: loads components