How niravrvaghasiya/brainos works
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: runtime.py Runtime cycle · storage/base.py Storage interface · loop.py Learning loop · adapters/base.py Agent adapters
Components 29
Cognitive runtime
- BrainOS API
brainos_runtime/__init__.py - Brain facade
brainos_runtime/core/brain.py - Runtime cycle
brainos_runtime/core/runtime.py - Cognitive cycle
brainos_runtime/core/cycle.py - Runtime events
brainos_runtime/core/events.py - Working memory
brainos_runtime/cognition/working_memory.py - Metacognition
brainos_runtime/cognition/metacognition.py
Memory and retrieval
- Temporal memory
brainos_runtime/memory/temporal.py - Memory schema
brainos_runtime/memory/schema.py - Retrieval engine
brainos_runtime/retrieval/engine.py - Storage interface
brainos_runtime/storage/base.py - Memory store
brainos_runtime/storage/memory_store.py - SQLite store
brainos_runtime/storage/sqlite_store.py - Postgres store
brainos_runtime/storage/postgres_store.py
Learning and safety
- Trust policy
brainos_runtime/security/trust.py - Belief conflicts
brainos_runtime/learning/beliefs.py - Learning loop
brainos_runtime/learning/loop.py - Memory consolidation
brainos_runtime/learning/consolidation.py - Memory forgetting
brainos_runtime/learning/forgetting.py
Integration and tools
- Agent adapters
brainos_runtime/adapters/base.py - LangGraph adapter
brainos_runtime/adapters/langgraph.py - MCP adapter
brainos_runtime/adapters/mcp.py - Vanilla adapter
brainos_runtime/adapters/vanilla.py - Session tracing
brainos_runtime/observability/tracer.py - Runtime CLI
brainos_runtime/cli.py - Plugin CLI
cli/brainos/cli.py - Plugin generator
cli/brainos/generator.py - Plugin loading
brainos_runtime/core/plugins.py
Other components
- AI agent
Connections 29
- 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