How asi-rishi/boros works
1. Repository purpose
- This is a self-modifying agent framework called Boros/ARES.
- The core idea is a tiny Python kernel that boots a set of modular “skills,” then repeatedly runs an evolution loop to improve its own code, tools, and policies.
2. Top-level runtime boundary
- The main execution entry points are kernel.py, agent_loop.py, and supporting orchestration code.
- The kernel is intentionally thin: it loads the manifest, initializes skills, and routes tool/function calls. Most behavior lives in skills, not in the kernel.
3. Boot configuration and system contract
- manifest.json, config.json, and world_model.json define the runtime mode, LLM setup, boot order, and scoring targets.
- world_model.json is the externalized definition of “better,” while config.json controls operational limits like cycle duration and snapshot retention.
- These files act as the system’s policy/config layer and are treated as high-value, mostly read-only inputs.
4. Skill architecture
- The skills/ directory is the main evolvable surface.
- Each skill is a self-contained module with:
- a skill.json manifest,
- a SKILL.md description,
- Python functions/,
- optional state/ and metrics/.
- Skills are grouped by responsibility: boot-time infrastructure, demand-loaded capabilities, and meta-control.
5. Core boot-time skills
- The boot set includes identity, mode control, temporal awareness, memory, skill routing, context orchestration, reflection, meta-evolution, meta-evaluation, and loop orchestration.
- These form the control plane: they decide what mode Boros is in, what context to load, how to track time and state, and how to initiate improvement cycles.
6. Demand-loaded operational skills
- Additional skills provide actual work capability: tool use, communication, reasoning, web research, mission control, scratchpad, eval bridge, and skill forge.
- These are the execution plane: terminal/file operations, structured reasoning, remote research, task queueing, and code mutation.
- The architecture separates “control” from “capability,” which is important for understanding boundaries in a diagram.
7. State and memory subsystem
- Persistent runtime state is spread across memory/, session/, logs/, and some skill-local state/ directories.
- memory/ holds evolution records, experiences, score history, and session scratchpad data.
- session/ tracks the current cycle, loop state, hypotheses, and proposals.
- The memory system is explicitly file-backed and acts as the system’s long-term learning store.
8. Evolution loop and feedback path
- Boros runs a recurring REFLECT → EVOLVE → EVAL loop.
- Reflection consumes memory and recent failures to generate a hypothesis or target.
- Evolution uses the skill forge to modify code and skill definitions.
- Evaluation pushes the current build into an external eval pipeline, then feeds scores back into memory and high-water-mark tracking.
- This is the core closed loop to show in any architecture diagram.
9. Skill Forge and rollback boundary
- The skill forge is the mutation boundary for self-editing.
- It snapshots code, applies diffs, validates changes, and can roll back on failure or regression.
- The snapshots/ directory contains preserved states of prior skill implementations, showing that the system treats its own codebase as versioned, reversible infrastructure.
10. Meta-evaluation and scoring
- Meta-evaluation is an independent review layer that judges proposed changes before they are merged.
- Scores are tracked per category, with regression protection and high-water marks.
- The scoring artifacts live in eval-generator/scoring/, memory/score_history.jsonl, and related state files.
- This creates a separate quality-control boundary from the main agent loop.
11. External eval generator and sandboxes
- eval-generator/ is a distinct subsystem that creates executable evaluation tasks, runs them in isolated sandboxes, and stores generated tests, logs, and results.
- The eval-generator/sandboxes/ tree shows many task-specific workspaces with scripts, input/output files, and logs.
- This is the external capability-testing harness; it is not just prompt scoring, but execution-based verification.
12. Provider adapters
- adapters/ contains model/provider integration code for Anthropic, OpenAI, Gemini, Ollama, and OpenAI-compatible endpoints.
- These adapters are the boundary between Boros and its LLM substrates.
- The readme indicates Claude is typically the primary agent model, while GPT-family models are used for meta-evaluation and eval generation.
13. Commands, missions, and human interaction
- commands/, session/proposals/, and mission-control support queued directives and operator interaction.
- The system distinguishes between live autonomous cycles and queued work instructions such as task submission, pause/resume, rollback, and mode switching.
- This is the human/control interface boundary rather than the intelligence core.
14. Where to draw the diagram boundaries
- A clear diagram should show:
- Kernel/orchestrator in the center,
- skills as modular capability nodes,
- memory/session/logs as persistent state stores,
- LLM/provider adapters as external model dependencies,
- eval-generator as an isolated external validation system,
- snapshots/rollbacks as the safety/recovery layer.
- The dominant data flow is: configuration and memory into reflection, proposed code changes into forge, executed evals into scored results, and scores back into memory and session state.
Main entry points: skill-router Skill router · eval-bridge Eval bridge · agent_loop.py Agent loop · session Session store
Components 32
Runtime
Kernel, loop, and boot-time orchestration.
- Kernel · Thin runtime bootstrapping and tool-call router.
kernel.py - Agent loop · Main autonomous cycle driver.
agent_loop.py - Manifest · Runtime mode and boot-order contract.
manifest.json - Config · Operational limits and runtime tuning.
config.json - World model · Externalized definition of desired progress.
world_model.json - Tool schemas · Schema definitions for callable tools and function routing.
tool_schemas.py
Skills
Modular capability surface split into control and execution skills.
- Skill router · Resolves available tools and routing budget.
skills/skill-router - Context load · Loads context and manifest for the active cycle.
skills/context-orchestration - Mode control · Reads and switches runtime mode.
skills/mode-controller - Time sense · Tracks cycle timing and remaining budget.
skills/temporal-consciousness - Memory · Pages archival memory in and out and searches stored experience.
skills/memory - Reflection · Analyzes traces and writes hypotheses for the next improvement step.
skills/reflection - Meta-eval · Reviews proposals and maintains criteria and verdicts.
skills/meta-evaluation - Meta-evolve · Proposes, applies, validates, and rolls back self-edits.
skills/meta-evolution - Forge · Snapshots, applies diffs, tests, validates, and rolls back skill code.
skills/skill-forge - Tool use · Terminal, patching, editing, and process control.
skills/tool-use - Web research · Search, browse, and archive external sources.
skills/web-research - Reasoning · Plan decomposition, option evaluation, and logic checks.
skills/reasoning - Communication · Broadcast and listen for structured communication.
skills/communication - Mission control · Queues tasks and tracks mission status.
skills/mission-control - Scratchpad · Ephemeral note-taking and temporary working state.
skills/scratchpad - Eval bridge · Requests evals, reads scores, checks regressions, updates high-water marks.
skills/eval-bridge - Identity · Reads and updates system identity.
skills/identity
State
File-backed memory, session, logs, and proposal state.
- Memory store · Evolution records, experiences, score history, and session scratchpad.
memory - Session store · Current cycle, loop state, hypotheses, and proposals.
session - Logs · Cycle and eval logging output.
logs - Commands · Pending commands and queued directives.
commands
Evaluation
External eval generator, scoring, and sandboxed tasks.
- Eval generator · Generates executable tests, runs sandboxed tasks, and stores results.
eval-generator/eval_generator.py - Scoring · Stored category scores and evaluation artifacts.
eval-generator/scoring - Sandboxes · Isolated per-eval execution environments and logs.
eval-generator/sandboxes
Recovery
Snapshots and rollback-oriented preservation of prior code.
- Snapshots · Versioned snapshots of prior skill implementations.
snapshots
Providers
LLM adapter boundary to external model backends.
- Adapters · Provider boundary for Anthropic, OpenAI, Gemini, Ollama, and compatible endpoints.
adapters
Connections 33
- Kernel → Manifest: boot · Loads boot contract and runtime mode.
- Kernel → Context load: init · Initializes context for runtime startup.
- Kernel → Skill router: route tools · Dispatches tool and function calls.
- Agent loop → Reflection: reflect · Uses recent traces and memory to form hypotheses.
- Agent loop → Meta-evolve: evolve · Applies proposed self-changes through the mutation boundary.
- Agent loop → Eval bridge: evaluate · Sends builds to evaluation and ingests scores.
- Manifest → Mode control: policy · Defines runtime mode and boot order.
- Config → Agent loop: limits · Constrains cycle duration and retention.
- World model → Reflection: target · Defines what improvement means.
- Tool schemas → Skill router: contracts · Describes callable tools and routing metadata.
- Skill router → Tool use: expose · Makes execution tools available to the kernel.
- Skill router → Communication: expose · Makes communication tools available.
- Skill router → Reasoning: expose · Makes reasoning tools available.
- Skill router → Web research: expose · Makes research tools available.
- Skill router → Mission control: expose · Makes mission queue tools available.
- Context load → Memory store: load · Pages in persistent context and archives.
- Context load → Session store: hydrate · Loads current session state.
- Reflection → Memory store: read/write · Consumes experiences and stores hypotheses.
- Reflection → Session store: update · Writes current hypothesis for the cycle.
- Meta-eval → Session store: review · Reads proposals and writes verdicts.
- Meta-evolve → Forge: mutate · Delegates code edits, validation, and rollback.
- Forge → Snapshots: snapshot · Preserves prior code before mutation.
- Forge → Logs: record · Logs validation and rollback outcomes.
- Eval bridge → Eval generator: request · Triggers generation and execution of eval tasks.
- Eval generator → Sandboxes: run · Executes isolated task workspaces.
- Eval generator → Scoring: write · Stores generated scoring artifacts.
- Eval bridge → Scoring: read scores · Collects evaluation results.
- Eval bridge → Memory store: persist · Updates score history and learning records.
- Eval bridge → Session store: high water · Maintains regression protection state.
- Mode control → Commands: control · Applies queued operator directives for mode changes.
- Mission control → Commands: queue · Stores pending tasks and status changes.
- Identity → Session store: state · Tracks current identity configuration.
- Adapters → Agent loop: models · Provides LLM backends to the core loop.