# thu-nmrc/openharness architecture

> Architecture diagram of the GitHub repository thu-nmrc/openharness, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-04-02). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/thu-nmrc/openharness
- Repository: https://github.com/thu-nmrc/openharness

## Overview

1. **What this repository is**
   OpenHarness is not a product app; it is a **runtime framework for autonomous agent work**. The repo mainly contains **control scripts, markdown contracts, and templates** that govern how an agent behaves over long sessions inside an OpenClaw workspace.

2. **Primary execution boundary**
   The framework assumes it runs inside `~/.openclaw/workspace/harness/{task-slug}/` and interacts heavily with the **filesystem as the system of record**. Most state is stored in Markdown files rather than a database or service API, which makes the workspace itself the durable runtime boundary.

3. **Entry point and agent wiring**
   `SKILL.md` is the agent-facing entry point recognized by OpenClaw. The README positions this file as the trigger that equips the agent with harness behavior, while the scripts implement the runtime machinery behind that behavior.

4. **Bootstrap and lifecycle control**
   `scripts/harness_boot.py` is the top-level startup controller. It checks existing state, handles stuck sessions, enforces a circuit breaker after repeated failures, and starts the session lifecycle before any task work proceeds.

5. **Session state and cross-session memory**
   `scripts/harness_heartbeat.py` and `scripts/harness_memory.py` manage the persistent state model. The README describes a **three-layer memory design**:
   - `templates/heartbeat.md` as a compact Layer 1 pointer index
   - `templates/knowledge/` as Layer 2 topic knowledge
   - an append-only execution stream log as Layer 3  
   This is the main mechanism for resuming interrupted work and avoiding context-window blowup.

6. **Task contract and work plan**
   `templates/mission.md`, `templates/playbook.md`, and `templates/progress.md` form the operational contract for the agent. `mission.md` defines what must be achieved, `playbook.md` defines the stepwise execution path, and `progress.md` records current work status and checkpoints. These documents constrain behavior and make the task auditable.

7. **Validation boundary**
   `scripts/harness_eval.py` is the external judge. It consumes `templates/eval_criteria.md` and performs independent validation so the agent is not allowed to certify its own completion. Architecturally, this is a hard separation between **work execution** and **completion approval**.

8. **Entropy control and cleanup**
   `scripts/harness_cleanup.py` is the maintenance layer. It trims logs, archives old records, and keeps the runtime environment from accumulating too much noise. This is a core part of the design because long-lived agent sessions are expected to grow continuously unless cleaned.

9. **Scheduling and unattended operation**
   `scripts/harness_setup_cron.py` and `templates/cron_config.md` define the time-based trigger mechanism. The framework is designed for **24/7 unattended execution**, so cron is the external scheduler that repeatedly re-enters the boot/evaluate/cleanup loop.

10. **Parallelism and coordination**
   `scripts/harness_coordinator.py` introduces a file-system IPC model for multi-agent or multi-worker execution. The README describes coordinator-managed worker `inbox/` and `outbox/` directories, which means parallel tasks are dispatched and aggregated through files rather than a network service.

11. **Offline consolidation and learning**
   `scripts/harness_dream.py` is a low-activity consolidation process. It scans accumulated execution history, distills recurring patterns, updates knowledge files, and feeds lessons back into `playbook.md`. This is the repo’s “background learning” path.

12. **Architectural governance**
   `scripts/harness_linter.py`, `references/architecture.md`, and `references/anti-patterns.md` provide policy enforcement and design guidance. They define what the harness considers valid structure and what behaviors should be avoided, acting as the repository’s architectural guardrails.

13. **How data moves through the system**
   The dominant flow is: **bootstrap → read mission/heartbeat/playbook → execute steps → update progress/heartbeat → external validation → cleanup → wait for next scheduled run**. A successful run may also feed knowledge back into the Layer 2/Layer 1 memory structures. The key architectural idea is that execution state is always externalized into files, not held only in agent context.

14. **Repository composition**
   This repo is intentionally lightweight on code and heavy on **orchestration artifacts**. The scripts are the runtime engine; the templates are the durable contract/state format; the references are the policy layer; and the README/SKILL files explain how the agent should enter and operate within the harness.

Main entry points: [`scripts/harness_boot.py`](https://github.com/thu-nmrc/openharness/blob/main/scripts/harness_boot.py) (Bootstrap), [`scripts/harness_heartbeat.py`](https://github.com/thu-nmrc/openharness/blob/main/scripts/harness_heartbeat.py) (Heartbeat), [`templates/progress.md`](https://github.com/thu-nmrc/openharness/blob/main/templates/progress.md) (Progress), [`scripts/harness_memory.py`](https://github.com/thu-nmrc/openharness/blob/main/scripts/harness_memory.py) (Memory)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry_runtime["Entry & Runtime"]
  node_readme["README<br/>overview doc<br/>[README.md]"]
  node_skill["SKILL<br/>agent entry<br/>[SKILL.md]"]
  node_boot["Bootstrap<br/>session controller<br/>[harness_boot.py]"]
end

subgraph group_state_contracts["State & Contracts"]
  node_heartbeat["Heartbeat<br/>session state"]
  node_memory["Memory<br/>[harness_memory.py]"]
  node_mission["Mission<br/>task contract<br/>[mission.md]"]
  node_playbook["Playbook<br/>execution plan<br/>[playbook.md]"]
  node_progress["Progress<br/>run ledger<br/>[progress.md]"]
  node_dream["Dream<br/>offline consolidation<br/>[harness_dream.py]"]
  node_knowledge["Knowledge<br/>layered memory<br/>[README.md]"]
  node_mem_evolve["Memory Evolution<br/>memory tooling"]
end

subgraph group_governance["Governance"]
  node_evalcrit["Eval Criteria<br/>validation spec<br/>[eval_criteria.md]"]
  node_eval["Evaluator<br/>external judge<br/>[harness_eval.py]"]
  node_cleanup["Cleanup<br/>maintenance<br/>[harness_cleanup.py]"]
  node_cron["Cron Setup<br/>scheduler setup"]
  node_croncfg["Cron Config<br/>schedule spec<br/>[cron_config.md]"]
  node_coordinator["Coordinator<br/>worker orchestrator"]
  node_linter["Linter<br/>policy check<br/>[harness_linter.py]"]
  node_arch["Architecture<br/>guideline<br/>[architecture.md]"]
  node_anti["Anti-patterns<br/>guideline<br/>[anti-patterns.md]"]
end

node_readme -->|"introduces"| node_skill
node_skill -->|"activates"| node_boot
node_boot -->|"loads"| node_mission
node_boot -->|"restores"| node_heartbeat
node_boot -->|"loads"| node_playbook
node_boot -->|"initializes"| node_progress
node_heartbeat -->|"indexes"| node_memory
node_memory -->|"stores"| node_knowledge
node_memory -->|"evolves"| node_mem_evolve
node_playbook -->|"drives"| node_progress
node_progress -->|"persists"| node_heartbeat
node_boot -->|"dispatches"| node_coordinator
node_coordinator -->|"returns"| node_cleanup
node_coordinator -->|"aggregates"| node_progress
node_eval -->|"consumes"| node_evalcrit
node_boot -->|"invokes"| node_eval
node_cleanup -->|"prunes"| node_heartbeat
node_cron -->|"configures"| node_croncfg
node_cron -->|"re-enters"| node_boot
node_dream -->|"refines"| node_knowledge
node_dream -->|"feeds"| node_playbook
node_linter -->|"checks"| node_arch
node_linter -->|"guards"| node_anti
node_eval -->|"follows"| node_cleanup
node_readme -->|"describes"| node_arch

click node_readme "https://github.com/thu-nmrc/openharness/blob/main/README.md"
click node_skill "https://github.com/thu-nmrc/openharness/blob/main/SKILL.md"
click node_boot "https://github.com/thu-nmrc/openharness/blob/main/scripts/harness_boot.py"
click node_heartbeat "https://github.com/thu-nmrc/openharness/blob/main/scripts/harness_heartbeat.py"
click node_memory "https://github.com/thu-nmrc/openharness/blob/main/scripts/harness_memory.py"
click node_mission "https://github.com/thu-nmrc/openharness/blob/main/templates/mission.md"
click node_playbook "https://github.com/thu-nmrc/openharness/blob/main/templates/playbook.md"
click node_progress "https://github.com/thu-nmrc/openharness/blob/main/templates/progress.md"
click node_evalcrit "https://github.com/thu-nmrc/openharness/blob/main/templates/eval_criteria.md"
click node_eval "https://github.com/thu-nmrc/openharness/blob/main/scripts/harness_eval.py"
click node_cleanup "https://github.com/thu-nmrc/openharness/blob/main/scripts/harness_cleanup.py"
click node_cron "https://github.com/thu-nmrc/openharness/blob/main/scripts/harness_setup_cron.py"
click node_croncfg "https://github.com/thu-nmrc/openharness/blob/main/templates/cron_config.md"
click node_coordinator "https://github.com/thu-nmrc/openharness/blob/main/scripts/harness_coordinator.py"
click node_dream "https://github.com/thu-nmrc/openharness/blob/main/scripts/harness_dream.py"
click node_linter "https://github.com/thu-nmrc/openharness/blob/main/scripts/harness_linter.py"
click node_arch "https://github.com/thu-nmrc/openharness/blob/main/references/architecture.md"
click node_anti "https://github.com/thu-nmrc/openharness/blob/main/references/anti-patterns.md"
click node_knowledge "https://github.com/thu-nmrc/openharness/blob/main/templates/knowledge/README.md"
click node_mem_evolve "https://github.com/thu-nmrc/openharness/blob/main/scripts/memory_evolution.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_readme,node_skill,node_boot toneBlue
class node_heartbeat,node_memory,node_mission,node_playbook,node_progress,node_dream,node_knowledge,node_mem_evolve toneAmber
class node_evalcrit,node_eval,node_cleanup,node_cron,node_croncfg,node_coordinator,node_linter,node_arch,node_anti toneMint
```

## Components

### Entry & Runtime

Agent entrypoint and control scripts that drive execution.

- [README](https://github.com/thu-nmrc/openharness/blob/main/README.md): overview doc · Explains the harness model, runtime loop, memory layers, and filesystem-centric operation. · `README.md`
- [SKILL](https://github.com/thu-nmrc/openharness/blob/main/SKILL.md): agent entry · Agent-facing entry file that activates harness behavior inside OpenClaw. · `SKILL.md`
- [Bootstrap](https://github.com/thu-nmrc/openharness/blob/main/scripts/harness_boot.py): session controller · Top-level startup logic that resumes, recovers, and starts runs. · `scripts/harness_boot.py`

### State & Contracts

Filesystem-backed runtime state and operational markdown templates.

- [Heartbeat](https://github.com/thu-nmrc/openharness/blob/main/scripts/harness_heartbeat.py): session state · Persistent session pulse and pointer index used to resume long-running work. · `scripts/harness_heartbeat.py`
- [Memory](https://github.com/thu-nmrc/openharness/blob/main/scripts/harness_memory.py): memory manager · Manages durable layered memory and cross-session recall. · `scripts/harness_memory.py`
- [Mission](https://github.com/thu-nmrc/openharness/blob/main/templates/mission.md): task contract · Defines the task objective and completion target. · `templates/mission.md`
- [Playbook](https://github.com/thu-nmrc/openharness/blob/main/templates/playbook.md): execution plan · Stepwise operating plan that guides agent actions. · `templates/playbook.md`
- [Progress](https://github.com/thu-nmrc/openharness/blob/main/templates/progress.md): run ledger · Records current status, checkpoints, and work advancement. · `templates/progress.md`
- [Dream](https://github.com/thu-nmrc/openharness/blob/main/scripts/harness_dream.py): offline consolidation · Distills lessons from history and feeds them back into knowledge and playbooks. · `scripts/harness_dream.py`
- [Knowledge](https://github.com/thu-nmrc/openharness/blob/main/templates/knowledge/README.md): layered memory · Topic knowledge store for Layer 2 memory. · `templates/knowledge/README.md`
- [Memory Evolution](https://github.com/thu-nmrc/openharness/blob/main/scripts/memory_evolution.py): memory tooling · Utility for evolving stored memory and knowledge representations. · `scripts/memory_evolution.py`

### Governance

Validation, scheduling, coordination, and architectural guardrails.

- [Eval Criteria](https://github.com/thu-nmrc/openharness/blob/main/templates/eval_criteria.md): validation spec · Independent criteria used to judge completion. · `templates/eval_criteria.md`
- [Evaluator](https://github.com/thu-nmrc/openharness/blob/main/scripts/harness_eval.py): external judge · Checks results against criteria without self-certification. · `scripts/harness_eval.py`
- [Cleanup](https://github.com/thu-nmrc/openharness/blob/main/scripts/harness_cleanup.py): maintenance · Trims logs and archives old records to control runtime entropy. · `scripts/harness_cleanup.py`
- [Cron Setup](https://github.com/thu-nmrc/openharness/blob/main/scripts/harness_setup_cron.py): scheduler setup · Configures unattended re-entry into the harness loop. · `scripts/harness_setup_cron.py`
- [Cron Config](https://github.com/thu-nmrc/openharness/blob/main/templates/cron_config.md): schedule spec · Template for time-based trigger configuration. · `templates/cron_config.md`
- [Coordinator](https://github.com/thu-nmrc/openharness/blob/main/scripts/harness_coordinator.py): worker orchestrator · Dispatches work through filesystem inbox/outbox coordination. · `scripts/harness_coordinator.py`
- [Linter](https://github.com/thu-nmrc/openharness/blob/main/scripts/harness_linter.py): policy check · Enforces repository structure and harness conventions. · `scripts/harness_linter.py`
- [Architecture](https://github.com/thu-nmrc/openharness/blob/main/references/architecture.md): guideline · Documents the intended system structure and boundaries. · `references/architecture.md`
- [Anti-patterns](https://github.com/thu-nmrc/openharness/blob/main/references/anti-patterns.md): guideline · Documents invalid patterns and behaviors to avoid. · `references/anti-patterns.md`

## Connections

- README → SKILL: introduces · README explains how the agent enters the harness through SKILL.md.
- SKILL → Bootstrap: activates · Agent entry routes into bootstrap control.
- Bootstrap → Mission: loads · Bootstrap reads the task objective before execution.
- Bootstrap → Heartbeat: restores · Bootstrap checks session state to resume or recover work.
- Bootstrap → Playbook: loads · Bootstrap uses the playbook as the execution path.
- Bootstrap → Progress: initializes · Bootstrap establishes current run status.
- Heartbeat → Memory: indexes · Heartbeat points into layered memory and execution history.
- Memory → Knowledge: stores · Memory manager maintains topic knowledge as durable state.
- Memory → Memory Evolution: evolves · Memory tooling updates and reshapes stored knowledge.
- Playbook → Progress: drives · Plan execution updates progress checkpoints.
- Progress → Heartbeat: persists · Run status is reflected back into session memory.
- Bootstrap → Coordinator: dispatches · Bootstrap can hand work to coordinated workers.
- Coordinator → Cleanup: returns · Distributed work still feeds maintenance and housekeeping.
- Coordinator → Progress: aggregates · Worker outcomes are merged into shared progress state.
- Evaluator → Eval Criteria: consumes · Evaluator applies the external completion criteria.
- Bootstrap → Evaluator: invokes · Bootstrap can trigger validation after work steps.
- Cleanup → Heartbeat: prunes · Cleanup removes old session noise while preserving live pointers.
- Cron Setup → Cron Config: configures · Scheduler setup is driven by the cron template.
- Cron Setup → Bootstrap: re-enters · Scheduled triggers cycle back into bootstrap.
- Dream → Knowledge: refines · Offline consolidation updates knowledge files.
- Dream → Playbook: feeds · Learned patterns are fed back into the playbook.
- Linter → Architecture: checks · Linter enforces documented architecture rules.
- Linter → Anti-patterns: guards · Linter helps prevent known anti-patterns.
- Evaluator → Cleanup: follows · Validation is followed by maintenance and entropy control.
- README → Architecture: describes · README frames the architecture and operating model.
