Architecture
A modular monolith with internal service boundaries that map one-to-one to the spec's layers (section 4).
Scientific computation, orchestration, evidence grading and UI are separate packages. Agents reach everything
through typed tools (agents/tools.py) and never through solver internals or the filesystem.
| Spec layer | Package(s) | Key entry points |
|---|---|---|
| Experience | apps/dashboard, visualization/ |
dashboard index.html, viewer.js, visualization/viewer.structure_payload |
| API/application | apps/api.py, matter_os/app.py |
create_app(), MatterOS container (Project API) |
| Orchestration | orchestration/ |
MissionOrchestrator, JobRunner, ResourceManager, scheduler.execute, failures.classify |
| Agent runtime | agents/ |
AgentRuntime, ResearchCoordinator, 12 specialists, DynamicAgent, MessageBus, debate.resolve |
| Scientific core | core/, discovery/ |
MatterStructure, ConstraintSet, transformations, generators, searches, Pareto, active learning |
| Simulation adapters | simulation/ |
SolverAdapter contract, MethodRegistry, SimulationRouter, SimulationService, benchmarks |
| Knowledge | knowledge/ |
KnowledgeGraph, governance rules, provenance registry, ingestion connectors |
| Infrastructure | storage/, orchestration/jobs.py |
SQLite Database (+migrations, immutability triggers), ArtifactStore, archives/snapshots |
End-to-end flow (one mission)
mission -> hypotheses -> design -> screening -> method_selection -> execution -> analysis -> learning -> replication -> novelty -> evidence_grading -> knowledge_update -> next_action
The coordinator routes each stage to its agent with a TaskContract. The result is validated against the StageResult
schema, posted as a structured message and persisted into the mission checkpoint, so a crash resumes at the next stage.
Data stores (SQLite, var/matter_os.sqlite3)
projects, missions, candidates (+candidate_versions), run_records (immutable), claims (+claim_versions), jobs, kg_entities, kg_edges, kg_events (append-only), audit_log (append-only), agent_memory, messages, artifacts, data_sources, failures, strategy_stats, agent_evaluations, improvements, metrics, schema_migrations.
Artifacts are content-addressed files under var/artifacts/<sha[:2]>/<sha>/<name>, each with an HMAC signature row.
Execution isolation
JobRunner forks one worker per job (multiprocessing "fork" context). The worker sets RLIMIT_CPU and thread caps,
runs in var/jobs/<job_id>/, and returns a pickled SolverOutput. The parent enforces wall time, a resident-RAM
watchdog (USS sampled every 0.5 s) and cancellation (cooperative flag file, then terminate). Checkpoints are ASE
trajectories, and resume continues from the last frame.
Decisions recorded as ADRs
See docs/decisions/.