How asi-rishi/boros-architecture works
1. What this repository is
Boros is an autonomous agent substrate, not a conventional app. The runtime repeatedly alternates between a self-improvement loop and a task-execution loop. The codebase is organized so the system can inspect itself, mutate its own skills, evaluate those mutations, and roll them back if they regress.
2. The bootstrap/runtime core
boros/kernel.py is the entrypoint and thin bootstrap layer. It reads the manifest, loads the boot skills in order, wires tool dispatch, and keeps the runtime small so most behavior lives in skills rather than the kernel.
3. Model/provider boundary
boros/adapters/providers/ contains LLM-provider adapters for Anthropic, OpenAI, Gemini, Ollama, and OpenAI-compatible endpoints. This is the model boundary: the kernel and skills call through adapters rather than hard-coding one model family. The readme indicates Claude is the primary substrate and GPT-4o is used for meta-evaluation / eval generation.
4. Configuration and system contract
boros/manifest.json, boros/config.json, .env, and boros/world_model.json define the operating contract. The manifest drives mode, boot order, and model selection; config.json controls runtime limits and logging; .env supplies API keys; world_model.json defines the scoring categories that steer evolution and is treated as read-only by Boros.
5. Skill-based architecture
The real system behavior lives under boros/skills/. Each skill is a self-contained module with:
- SKILL.md describing its contract,
- functions/ implementing callable tools,
- skill.json metadata,
- optional state/, metrics/, and changelog.md.
This makes the system modular and evolvable at the capability level rather than as a monolith.
6. Boot skills vs demand skills
The boot set establishes identity, mode, time, memory, routing, context loading, reflection, meta-evolution, meta-evaluation, and loop orchestration. Demand skills are invoked as needed for work: skill forge, mission control, reasoning, tool use, communication, web research, eval bridge, and scratchpad. That split is an important boundary: boot skills make the agent self-sustaining; demand skills provide operational capabilities.
7. Primary control loops
boros/skills/loop-orchestrator/ manages the lifecycle state machine, including starting cycles, advancing stages, ending cycles, and storing loop_state.json. The system runs in evolution, work, or dual mode, with cycle progression controlled by persisted loop state rather than ephemeral process memory.
8. Self-improvement pipeline
The evolutionary loop is REFLECT → EVOLVE → EVAL. Reflection draws on memory and logs to form a hypothesis; meta-evolution proposes and applies code changes; meta-evaluation reviews the patch with an external model; eval-bridge then connects to the independent eval generator. This pipeline is the core data flow for improving Boros itself.
9. Memory and context management
boros/skills/memory/ and boros/skills/context-orchestration/ implement the tiered memory system. Memory handles page-in/page-out, archival commits, and search; context orchestration decides what the model should see at a given moment. Persistent artifacts under boros/memory/, boros/session/, and boros/logs/ feed these skills, enabling long-running continuity without loading everything into context.
10. Evaluation subsystem
boros/eval-generator/ is a separate evaluation pipeline with its own config, shared request/result folders, and tool dispatcher. It executes isolated tasks, records outcomes, and feeds scores back through the eval bridge skills under boros/skills/eval-bridge/. This is a critical architectural boundary: Boros is tested by an external process that it does not directly control.
11. Self-modification and rollback
boros/skills/skill-forge/ is the code mutation boundary. It can snapshot code, apply diffs, validate changes, run test suites, invoke tooling, and roll back. The repository also contains boros/snapshots/ for saved states and rollback support. This is how the system edits its own implementation while preserving recovery paths.
12. Work execution and human-facing control
boros/skills/mission-control/, boros/skills/tool-use/, and boros/skills/director-interface/ handle task intake, terminal/file operations, and Director commands. The readme’s CLI commands map to these subsystems: status, pause/resume, inject, forge, set-mode, task, eval, approve/flag, rollback. This is the operational interface separating direct human intent from autonomous execution.
13. Specialized capability islands
Additional skills such as reasoning, reflection, communication, web research, scratchpad, identity, mode control, and temporal consciousness are narrow subsystems with explicit tool surfaces. They each persist their own metrics and state, which makes the architecture compositional: capability improvements can happen inside one island without rewriting the whole system.
14. Repository shape and non-runtime assets
predev-specs/ holds design/specification artifacts and historical decisions, not live runtime logic. commands/, session/, memory/, logs/, metrics/, and state/ directories are the persistent operational layer that records system history, scores, and control state. Together they form the traceability backbone for the agent’s continuous self-evolution.
Main entry points: skill-router Skill router · kernel.py Kernel · meta-evolution Meta-evolution · reflection Reflection
Components 30
Runtime core
Bootstrap, model boundary, and control wiring.
- Kernel · Entrypoint that reads the manifest, loads boot skills, and wires dispatch.
Boros/boros/kernel.py - Manifest · Declares mode, boot order, and model selection.
Boros/boros/manifest.json - Config · Controls limits, logging, and runtime behavior.
Boros/boros/config.json - Model adapters · Provider adapters for Anthropic, OpenAI, Gemini, Ollama, and compatible endpoints.
Boros/boros/adapters/providers - Skill router · Exposes skill metadata and the active tool set.
Boros/boros/skills/skill-router - World model · Read-only scoring categories that steer evolution.
Boros/boros/world_model.json
Boot skills
Skills loaded early to establish state and control.
- Identity · Reads and updates agent identity state.
Boros/boros/skills/identity - Mode control · Gets and sets operating mode.
Boros/boros/skills/mode-controller - Time · Provides cycle timing and elapsed-time awareness.
Boros/boros/skills/temporal-consciousness - Context · Loads manifest-derived context for the model.
Boros/boros/skills/context-orchestration - Memory · Pages context, archives commits, and searches stored memory.
Boros/boros/skills/memory - Loop orchestrator · Advances cycle stages and persists loop state.
Boros/boros/skills/loop-orchestrator
Capability skills
On-demand skills that handle work, reasoning, and communication.
- Mission control · Queues tasks and tracks mission status.
Boros/boros/skills/mission-control - Tool use · Performs terminal and file-edit operations.
Boros/boros/skills/tool-use - Reasoning · Decomposes problems and evaluates options.
Boros/boros/skills/reasoning - Communication · Broadcasts and listens within the agent substrate.
Boros/boros/skills/communication - Web research · Searches, browses, and archives external sources.
Boros/boros/skills/web-research - Scratchpad · Short-lived workspace for transient notes.
Boros/boros/skills/scratchpad
Self-improvement
Reflection, mutation, evaluation, and rollback loop.
- Reflection · Analyzes traces and writes hypotheses for improvement.
Boros/boros/skills/reflection - Meta-evolution · Proposes, applies, and rolls back repository changes.
Boros/boros/skills/meta-evolution - Meta-evaluation · Reviews proposals and maintains evaluation criteria.
Boros/boros/skills/meta-evaluation - Eval bridge · Connects Boros to the external evaluation pipeline.
Boros/boros/skills/eval-bridge - Skill forge · Snapshots, validates, tests, applies diffs, and rolls back code changes.
Boros/boros/skills/skill-forge - Eval generator · Independent task/eval generation and execution pipeline.
Boros/boros/eval-generator
Persistent state
Operational files, session state, logs, and snapshots.
- Session state · Stores current cycle and loop state.
Boros/boros/session - Logs · Cycle and operational logs for long-running continuity.
Boros/boros/logs - Memory store · Persistent score history and archived memory artifacts.
Boros/boros/memory - Commands · Pending human/director commands.
Boros/boros/commands - Snapshots · Saved repository states for recovery and rollback.
Boros/boros/snapshots
Specs
Design-time documentation and architecture guidance.
- Predev specs · Architecture notes, skill specs, and build-order guidance.
Boros/predev-specs
Connections 40
- Kernel → Manifest: reads · Bootstraps runtime from the declared manifest.
- Kernel → Config: loads · Applies runtime limits and logging settings.
- Kernel → Skill router: dispatches · Routes tool calls through the skill registry.
- Kernel → Model adapters: calls · Uses provider adapters as the model boundary.
- Kernel → Identity: boots · Loads identity early in startup.
- Kernel → Mode control: boots · Loads mode control early in startup.
- Kernel → Time: boots · Loads temporal awareness early in startup.
- Kernel → Context: boots · Loads context orchestration during startup.
- Kernel → Loop orchestrator: boots · Initializes the cycle state machine.
- Skill router → Memory: exposes · Makes memory tools available to the runtime.
- Skill router → Reflection: exposes · Makes reflection tools available to the runtime.
- Skill router → Meta-evolution: exposes · Makes mutation tools available to the runtime.
- Skill router → Meta-evaluation: exposes · Makes review tools available to the runtime.
- Skill router → Eval bridge: exposes · Makes evaluation bridge tools available to the runtime.
- Skill router → Skill forge: exposes · Makes self-modification tools available to the runtime.
- Skill router → Mission control: exposes · Makes task intake tools available to the runtime.
- Skill router → Tool use: exposes · Makes execution tools available to the runtime.
- Skill router → Reasoning: exposes · Makes reasoning tools available to the runtime.
- Skill router → Communication: exposes · Makes communication tools available to the runtime.
- Skill router → Web research: exposes · Makes research tools available to the runtime.
- Skill router → Scratchpad: exposes · Makes scratchpad tools available to the runtime.
- Loop orchestrator → Session state: persists · Stores cycle and stage progress in session state.
- Loop orchestrator → Logs: records · Writes cycle logs for later reflection.
- Reflection → Memory store: reads · Uses memory history and traces for hypotheses.
- Reflection → Logs: analyzes · Considers operational logs when reflecting.
- Reflection → Meta-evolution: feeds · Turns hypotheses into proposed changes.
- Meta-evolution → Skill forge: uses · Applies diffs, validates, tests, and rolls back through the forge boundary.
- Meta-evolution → Snapshots: writes · Captures rollback points and saved states.
- Meta-evolution → Loop orchestrator: updates · Can modify loop behavior as part of evolution.
- Meta-evaluation → World model: scores by · Evaluates changes against the scoring rubric.
- Meta-evaluation → Eval bridge: routes · Hands off review results to the eval bridge.
- Eval bridge → Eval generator: connects · Submits requests to the external eval pipeline.
- Eval generator → Meta-evaluation: returns scores · Feeds evaluation outcomes back to review and calibration.
- Mission control → Tool use: drives · Task intake leads to terminal and file operations.
- Mission control → Commands: reads · Consumes queued human/director commands.
- Tool use → Logs: traces · Operational actions are logged for continuity.
- Context → Manifest: derives · Builds context from the system contract.
- Memory → Memory store: pages · Moves persistent memory in and out of working context.
- Memory → Session state: uses · Relies on session artifacts for continuity.
- Predev specs → Skill router: specifies · Defines the intended skill topology and build order.