DingyangLyu/MatOS

Describe a materials research task. MatOS assembles the scientific assets it needs, runs them as a stateful, checkable workflow, and turns every run into better assets for the next one.

Contents

• What is MatOS?
• Core Design
• Benchmark Results
• What's in This Edition
• Command Line
• Quick Start
• Basic Usage
• Architecture
• Configuration
• Running the Benchmarks
• Documentation
• Contributing
• Citation

What is MatOS?

MatOS is an agent operating system for materials research. Materials studies run for days, cross literature, computation and experiment, and keep changing as results arrive. Agents for this work have to take on new data and software, keep long tasks on track, and remember what earlier tasks taught them. MatOS builds these capabilities around versioned scientific assets: data, knowledge, tools, skills, roles and workflows.

Research tasks drive the stateful adaptive workflow, the layered scientific asset graph supplies composable capabilities, and execution traces and user feedback become reviewed asset revisions that return to the graph.

Key Features:

• Layered scientific asset graph — six versioned asset types on four semantic layers, linked by six typed relations, in shared, user and project scopes. Adding a capability means adding an asset, and roles reuse assets instead of copying them.
• Stateful adaptive workflows — nine node types, DAG and state-machine execution, MAP and LOOP, retries, pauses, cancellation and human approval. Snapshots, an event ledger and per-attempt artifacts let long tasks resume and stay traceable. The agent may propose changes to the graph, and the runtime admits them only after graph, policy and compile checks.
• Evidence-driven asset evolution — five hidden system roles turn execution records and feedback into focused asset edits. Each edit must pass structural checks and a semantic review. Approval can be off, manual or automatic, and the Evolution page shows proposals, history and per-asset version lineage.
• Measured on research benchmarks — +11.15% over the previous best agent on ResearchClawBench, extending the cost–score Pareto front, and ahead of Codex CLI and Claude Code on MatTools and SciAgentGym with the same base model (results).
• Browser workspace — a customized OpenDesign interface with projects, persistent conversations, files, previews, a terminal, asset and workflow views, and a MatterViz crystal-structure viewer.
• DeepSeek Harness engine — DeepSeek Harness (MIT) runs the agent loop and native tools. DeepSeek-V4-Flash is the default model, and any compatible gateway works through DEEPSEEK_BASE_URL.
• One-command deployment — ./deploy.sh asks a few questions, runs 18 system checks, downloads a private Node.js and Bun with checksum verification, installs, starts and verifies the model. It needs no root, and every error code has a documented fix.
• Benchmark runners — prepare, run and score entrypoints for MatTools, SciAgentGym and ResearchClawBench, with a frozen 28-asset benchmark profile and evolution turned off.

Core Design

Layered Scientific Asset Graph

A scientific asset is an object with a unique identifier and type, a declared version and dependencies, and a content entry point or external resource. MatOS distinguishes six types and places them on four semantic layers by their typical prerequisites:

Directed edges a → b point from the referencing asset to its referent:

For each task, a role's effective capabilities are composed from the subgraph reachable through DEP, MOUNT and CALL under the current scopes and accepted versions. Several roles can mount the same skill, and different workflows can call the same role.

Stateful Adaptive Workflow

Model sampling varies, and decisions drift as context changes over a long task. MatOS therefore runs critical computations through an explicit execution graph that holds steps, states and checking rules. The runtime manages parameters, jobs and evidence, while the agent revises plans and interprets anomalies.

• Two execution modes. In DAG mode the scheduler dispatches nodes whose predecessors, inputs and branch conditions are satisfied. In state-machine mode it advances stage by stage through explicit transitions, and transitions back to an earlier stage form feedback loops.
• State outlives the session. Graph snapshots, node records and an event ledger persist outside the model's context. A background process can carry a long run and write heartbeats. An observer wakes the agent when the run ends, waits for input or loses its heartbeat, and the agent reads new events through a cursor instead of polling.
• Checked graph changes. A proposed update δ becomes version W(k+1) only if it passes graph-structure, policy and compilation checks. Every proposal, check and decision is recorded, and a rejected proposal leaves the current graph running.

Evidence-Driven Asset Evolution

Task records and user feedback reveal reusable methods, failure causes, environment requirements and preferences. MatOS writes this experience into assets and keeps the base model fixed.

1. Evidence critique: a critic asks whether the evidence in a trace, the feedback and the workflow outcomes is sufficient, plausible and reusable, and whether it belongs in shared methods or a user's or project's preferences.
2. Target location: explicitly named assets come first, and graph relations and textual relevance add related candidates, up to a bounded context.
3. Focused editing: an editor proposes a coordinated revision, possibly across several assets or as a new one. A rejected proposal is revised against the stated reasons, up to three attempts.
4. Dual acceptance: deterministic checks test descriptions, interfaces and relations. Where a pre-edit baseline exists, errors are compared before and after, so only new errors block the edit. A semantic reviewer then confirms that the edit addresses the evidence and preserves the method's applicability.
5. Adoption: the accepted version is published to its scope. New conversations use it at once, and open conversations pick it up on their next turn.

Set the mode on the Evolution page, in Settings, with matos evolve policy, or for a whole service with MATOS_EVOLUTION_APPROVAL_MODE.

Benchmark Results

MatOS is evaluated at three levels: end-to-end research on ResearchClawBench, materials tool use on MatTools, and multistep scientific problem solving on SciAgentGym. The figures below are from the MatOS technical report.

End-to-End Research: ResearchClawBench

Twelve chemistry, energy and materials tasks derived from published papers. The system gets the literature and raw data but not the target paper, and must run the study and write a report that experts score against weighted rubric items. MatOS scores 19.20 with DeepSeek-V4-Flash and 19.46 with GPT-5.4, which is 9.63% and 11.15% above MIRA, the strongest previously reported GPT-5.4 system. All baselines use GPT-5.4, with scores and costs taken from the MIRA report.

Domain scores (bars) and overall score (markers, also listed under each system name).

Both MatOS configurations extend the observed cost–score Pareto front. DeepSeek-V4-Flash reaches a higher score at a cost close to the strongest baseline's.

Mean execution cost (log scale) against overall score. The dashed line joins the non-dominated points.

Tool Use: MatTools and SciAgentGym

All three systems use DeepSeek-V4-Pro as the base model, so the comparison isolates the agent system. MatTools has 49 problems with 138 property-computation subtasks on pymatgen and its defect extension, checked by unit tests. SciAgentGym has 42 public chemistry and materials cases that require composing domain tools, and a case counts only when the answer is wholly correct.

(a) MatTools subtask success (solid) and complete-problem success (hatched). (b) SciAgentGym case success, with solved cases in parentheses.

Results Summary

What's in This Edition

This repository is the open, single-user MatOS edition. It ships two asset profiles:

Scientific Python environments, MLIP models and benchmark data are installed separately; point MatOS at them in the configuration.

Command Line

The workspace is the main interface, and everything it does is also available from bin/matos. Add bin/ to PATH (export PATH="$PWD/bin:$PATH") or call bin/matos directly.

Add --json to most commands for machine-readable output.

Quick Start

One-command setup (recommended)

git clone https://github.com/DingyangLyu/MatOS.git
cd MatOS
./deploy.sh init   # answer a few questions; writes matos-deploy.conf
./deploy.sh        # check → install → start → verify

./deploy.sh checks the machine, downloads a private Node.js 24 and Bun 1.3.14 if needed, installs, builds the workspace, starts the service and makes one real model call to verify it. A first deployment takes about 4–10 minutes, and redeploying takes tens of seconds.

Then open http://127.0.0.1:17474/. The service listens only on loopback, so from your own computer use an SSH tunnel:

ssh -N -L 17474:127.0.0.1:17474 you@server

On first visit, the welcome page asks for a DeepSeek API key if you did not give one during deployment.

Prerequisites

• Linux x86_64 with glibc 2.28+ (Ubuntu 20.04+, Debian 10+, RHEL/Rocky/Alma 8+).
• Python 3.9+, Git, a C/C++ compiler and make. Node.js and Bun are optional, because the deploy script fetches private copies.
• 4 GB RAM and about 3 GB for the program, plus space for the data directory.
• Network access to the npm registry, the Node/Bun downloads and the DeepSeek API, with mirrors and proxies supported.
• A DeepSeek API key or a compatible gateway. Root is not needed.

Day-to-day

Every check and failure prints a code (C01–C18, I01–I06, R01–R03, A01). The deployment guide (Chinese) explains each code and its fix, plus upgrades, backup and migration.

bash scripts/matos-setup.sh
# Copy .env.example outside this checkout and set DEEPSEEK_API_KEY.
python3 scripts/matos-service.py start \
  --state-dir /path/to/matos-state \
  --env-file /path/to/private/provider.env \
  --port 17474 --daemon-port 17473

Basic Usage

Open a project in the workspace, pick a role and describe the task:

• Compute handles materials calculations and tool-centered problems. It plans, checks the local toolchain, writes and runs code, and finalizes answers in the requested form.
• Research Scientist handles open-ended studies: literature, data analysis, modeling and a written report.

From the terminal, the same thing is one command:

bin/matos run --role compute "Build a 2×2×2 rock-salt NaCl supercell with pymatgen and report its density and space group"

The agent will:

1. Compose the role's assets (skills, knowledge, tools, workflows) under your current scopes and accepted versions
2. Plan the task and check that the scientific environment it needs is available
3. Run code, tools or workflows, record every step, and check intermediate results
4. Write results, figures and files to the project, and answer in the conversation
5. Leave the trace and your feedback as evidence for the next round of asset evolution

Architecture

┌────────────────────────────────────────────────────────────────────┐
│ Browser · OpenDesign workspace                     127.0.0.1:17474 │
│ projects · conversations · files · terminal · assets               │
│ workflows · Evolution page · MatterViz structure viewer            │
└────────────────────────────────────────────────────────────────────┘
                                   │
                                   │ HTTP
                                   │
┌────────────────────────────────────────────────────────────────────┐
│ OpenDesign daemon → native matos commands                   :17473 │
└────────────────────────────────────────────────────────────────────┘
                                   │
                                   │ stream-json
                                   │
┌────────────────────────────────────────────────────────────────────┐
│ MatOS runtime                                                      │
│                                                                    │
│ ┌────────────────────┐ ┌─────────────────────┐ ┌─────────────────┐ │
│ │ Scientific assets  │ │ Workflow runtime    │ │ Evolution       │ │
│ │ D K T S R W        │ │ DAG / state machine │ │ critic → editor │ │
│ │ bundled · user ·   │ │ snapshots · events  │ │ checks → judge  │ │
│ │ project scopes     │ │ artifacts · resume  │ │ → new version   │ │
│ │ local Git refs     │ │ checked graph edits │ │ off/manual/auto │ │
│ └────────────────────┘ └─────────────────────┘ └─────────────────┘ │
│                                                                    │
│ DSH host: role composition · tool rules · skills · MCP             │
└────────────────────────────────────────────────────────────────────┘
                                   │
                                   │ DSH turns
                                   │
┌────────────────────────────────────────────────────────────────────┐
│ DeepSeek Harness: agent loop + native tools (shell, files, web…)   │
└────────────────────────────────────────────────────────────────────┘
                 │                                 │
                 │                                 │
  DeepSeek API / compatible gateway   Host scientific environment
                                      (conda envs, solvers, models)

How it works:

1. The browser workspace talks to the OpenDesign daemon, which calls native MatOS commands and presents their results
2. When a conversation starts, MatOS resolves the role's capability subgraph under the project's scopes and accepted asset versions
3. The DSH host translates the composed role, tool rules, skills, MCP configuration and session identifiers into DeepSeek Harness turns. DSH runs the agent loop and native tools and streams events back
4. Long or critical computations run as workflows. The runtime schedules nodes, persists state and wakes the agent when a run finishes or needs input
5. Turn feedback and execution records reach the hidden evolution roles. Accepted asset versions are published to the scope's accepted ref and used from the next turn

MatOS owns the scientific system, DeepSeek Harness owns the agent loop, and OpenDesign owns the interface.

Configuration

Running the Benchmarks

scripts/matos-benchmark.sh is the solver binary for all three harnesses. It pins DeepSeek-V4-Flash, full MatOS context and maximum effort, prepares a private profile per case and disables evolution. Get each benchmark's public data separately and put the provider key in an environment file:

export MATOS_BENCH_ENV_FILE=/abs/path/to/provider.env
python3 scripts/matos-mattools-agentic-bench.py prepare --mattools-root "$MATTOOLS_ROOT" \
  --mattools-python "$MATTOOLS_PYTHON" --output-root "$RUNS" --run-id matos --json
python3 scripts/matos-mattools-agentic-bench.py run --run-root "$RUNS/matos" --runner matos \
  --matos-bin "$PWD/scripts/matos-benchmark.sh" ...
python3 scripts/matos-mattools-agentic-bench.py score --run-root "$RUNS/matos" --runner matos ...

SciAgentGym (scripts/matos-sciagentgym-bench.py) and ResearchClawBench (scripts/matos-rcbench-dsh.py) follow the same prepare, run and score pattern. Full commands, judge settings and the asset-profile export are in docs/benchmarks.md.

MatOS/
├── deploy.sh                    # One-command deployment → scripts/matos-deploy.py
├── bin/matos                    # Command-line entrypoint
├── src/
│   ├── entrypoints/             # matos CLI, agent and evolution-worker entrypoints
│   └── matos/                   # Native runtime
│       ├── assets/              # Asset model, validation, local Git acceptance
│       ├── workflows/           # Workflow runtime: scheduler, snapshots, observers
│       ├── learning/            # Evidence-driven evolution
│       ├── host/                # DSH host: role composition into DSH turns
│       ├── runtime/             # DeepSeek Harness engine, scopes, deployment roots
│       ├── sessions/            # Event and trace recording
│       ├── workbench/           # Actions behind the browser workspace
│       └── cli/                 # matos commands
├── ui/open-design/              # Customized OpenDesign workspace and daemon
├── vendor/deepseek-harness/     # Pinned DeepSeek Harness bundle and MatOS plugin
├── distribution/benchmark-minimal/
│   └── assets/packs/            # The 37-asset workspace / 28-asset benchmark packs
├── scripts/                     # Setup, service, state, export, benchmarks, tests
└── docs/                        # Deployment guide, benchmark guide, figures

Documentation

Contributing

Contributions are welcome, especially scientific assets. A new capability is a new asset: an asset.json manifest with its id, type, version, dependencies and permissions, plus the content entry point.

distribution/benchmark-minimal/assets/packs/<pack>/
├── skills/<name>/      asset.json · SKILL.md
├── roles/<name>/       asset.json · ROLE.md
├── tools/<name>/       asset.json · prompt.md · tool.py · input.schema.json
├── knowledge/<name>/   asset.json · KNOWLEDGE.md
├── data/<name>/        asset.json · DATA.md (references, not large files)
└── workflows/<name>/   asset.json · workflow.json

Submissions should include validation evidence and the redistribution license. Validate with matos assets validate and run bash scripts/matos-user-test-regression.sh before sending changes. Report reproducible issues with the source revision, OS/CPU, toolchain versions and sanitized logs. See CONTRIBUTING.md.

Related Projects

• MatClaw: our earlier agent for autonomous materials computation. Describe a task in plain language, and it writes the code, runs DFT, molecular dynamics or Monte Carlo simulations in a container and reports the results.

Acknowledgments

MatOS builds on the following open-source projects:

• DeepSeek Harness: the agent execution engine (MIT)
• OpenDesign: the browser workspace and daemon this interface is derived from (Apache-2.0)
• Coze Studio: native-module code, including graph components, that keeps its Apache-2.0 headers
• MatterViz and Svelte: the bundled crystal-structure viewer (MIT)

The workflow runtime follows the dynamic workflows, error handling and provenance of FireWorks, AiiDA and atomate2. Evaluation uses ResearchClawBench, MatTools and SciAgentGym.

Roadmap

• Layered asset graph with shared, user and project scopes, local Git acceptance and rollback
• Stateful workflows with checked graph updates, persistent state and background execution
• Evidence-driven evolution with off, manual and automatic approval and an Evolution page
• One-command deployment with system checks and a documented error catalog
• Connect instruments and experimental protocols to the workflow runtime
• Link computational and experimental evidence
• Cross-project asset governance and evaluations of scientific reliability
• Validated ARM64 and Kylin builds

Citation

If you use MatOS in your research, please cite the technical report:

@techreport{matos2026,
  title       = {{MatOS}: An Agent Operating System for Materials Research},
  author      = {{AI Materials Team}},
  institution = {Zhongguancun Academy and Zhongguancun Institute of Artificial Intelligence},
  address     = {Beijing, China},
  year        = {2026},
  month       = oct
}

Contact: [email protected]

License

MatOS-authored material is licensed under the PolyForm Noncommercial License 1.0.0: free for noncommercial use such as research and education. Commercial use is not permitted; for commercial inquiries, contact [email protected]. Third-party components keep their own licenses; see LICENSING.md.