MORA: Meaning-Oriented Research Automation

Language / 语言: 中文 README

MORA is a research automation framework for agents that need to run real, auditable experiments without drifting into unsupported claims, baseline damage, or endless local tweaking.

MORA stands for Meaning-Oriented Research Automation. Its job is not to write a paper first. Its job is to preserve research meaning: question, hypothesis, isolated experiment, evidence grade, and append-only meaning update.

Current status: early production-oriented framework. The core guardrails, CLI, schemas, skills, isolated experiment capsules, evidence calibration, local runner, SSH/SLURM dry-run plans, agent bootstrap, and Meta-MORA self-evolution workflow exist. Some remote execution, UX, and full automation pieces are still intentionally limited. See Current Limits.

MORA mascot: guard the baseline, isolate experiments, calibrate evidence.

What MORA Is For

MORA is designed for long-running research work with a code agent such as Codex, Claude Code, OpenCode, or another compatible host. You give the agent a research intent; MORA turns it into a guarded internal workflow.

MORA protects the parts of research agents often damage:

• locked baselines should not be edited during experiments
• experiments should run in disposable isolated workspaces
• smoke tests and tiny runs should not become effectiveness claims
• failed runs should stay separate from negative scientific results
• claims should be bounded by evidence level and baseline noise floor
• long agent sessions should retain compact, auditable context
• self-evolution should happen through capsules and gates, not blind prompt edits

Normal Use: Tell The Agent mora

Install the host bridge once:

# Install the single Codex skill that lets Codex start or resume MORA.
mora install-agent codex

Then open Codex in your research project and say what you want:

mora I want to improve image classification robustness under common corruptions.
Baseline: /path/to/image-classifier-baseline.
Idea: compare label-preserving augmentation against the current training recipe.
Project: image-robustness.

That is the intended user-facing path. You should not need to manually say "lock the baseline", "create an experiment capsule", "compile", "run", "collect", or "audit claims". Those are MORA kernel responsibilities.

For requests such as "find an idea", "search ideas", "research direction", or "meaningful experiment", the installed host skill starts idea-search mode:

mora research "Find a meaningful robustness idea" \
  --host codex \
  --baseline /path/to/image-classifier-baseline \
  --project image-robustness

This first asks the host agent to write artifacts/meaning_seed.yaml and artifacts/idea_candidates.yaml, carrying novelty evidence, meaning rationale, falsifiable hypothesis, risks, and required next evidence into the normal experiment and claim-audit flow.

The installed mora skill starts or resumes an ephemeral MORA session, reads the generated directive, and asks the host agent to execute the next bounded step. After each step, MORA checks artifacts before issuing the next directive.

What Happens Internally

User intent
-> agent bridge (`mora`)
-> MORA session
-> meaning seed / idea candidates / search ledger
-> baseline lock / verify
-> meaning graph and experiment plan
-> isolated experiment capsule
-> compile / run / collect evidence
-> evidence interpretation and claim audit
-> append-only meaning update
-> promotion only after gated artifacts pass

The code layer enforces hard rules with Python, schemas, hashes, and validators. The Markdown skills tell the host agent how to behave inside those constraints.

Quick Install From Source

# From the repository root.
python3 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install -e .

# Optional sanity check.
mora doctor

For other agent hosts:

mora install-agent claude-code
mora install-agent opencode
mora install-agent generic

Example

For a tiny local demo without GPUs, use the generic example described in:

• Examples

A domain-specific Traf-align asynchronous-delay case study is also available, but it is not the default getting-started path:

• Traf-align async-delay case study

For Implementation Details

The README intentionally stays short. If you want to inspect or manually drive the lower-level workflow, start here:

• Manual CLI workflow

Focused docs:

• Agent bootstrap
• Runners: local, SSH, SLURM
• Meta-MORA evolution and SkillOpt import
• Baseline isolation
• Evidence calibration
• Skills contract

Current Limits

• MORA is not published to PyPI yet; editable source install is the expected path.
• SSH and SLURM runners currently generate safe plans; full remote sync, submission, monitoring, and log collection are later work.
• Promotion creates and validates a promotion request, but does not yet apply the patch to a candidate branch automatically.
• Meta-MORA scout is deterministic and lightweight. SkillOpt has a guarded import, but generic scouting is not yet a full literature/repository crawler or LLM-based comparative reviewer.
• doctor checks many project invariants, but full JSON Schema validation for every artifact is not yet wired everywhere.
• There is no dashboard, GitHub Actions CI, secrets manager, or remote provisioning layer yet.

Roadmap

1. Add CI for tests, schema checks, and constitution checks.
2. Make SSH and SLURM runners perform safe remote staging, submission, monitoring, and log collection.
3. Implement audited patch application for promotion into a candidate branch or workspace.
4. Expand artifact validation with full JSON Schema coverage.
5. Improve Meta-MORA scout beyond the current SkillOpt adapter.
6. Add a small dashboard for experiment state, evidence grades, and search ledger state.
7. Package and publish MORA with versioned releases.

Development Checks

PYTHONDONTWRITEBYTECODE=1 python -m unittest discover -s tests -v
mora doctor
mora evolve constitution-check --path skills --path bridges

Acknowledgements

MORA's guarded skill-optimization lane is inspired by SkillOpt: Executive Strategy for Self-Evolving Agent Skills and its official microsoft/SkillOpt implementation. MORA adapts the idea through its own capsule, evidence, constitution, provenance, and human stable-promotion gates.