# How the `/refine` Command Persists Harness Improvements in Prime Agent

> Discover how the /refine command persists harness improvements in Prime Agent. Learn how user instructions are saved to harness_state.json for future sessions.

- Repository: [Prime Intellect/prime-agent](https://github.com/PrimeIntellect-ai/prime-agent)
- Tags: how-to-guide
- Published: 2026-08-15

---

**The `/refine` command persists harness improvements by converting user instructions into structured `RefinementEvent` objects, safely merging them with any concurrent changes via disk synchronization, and atomically writing the updated state to [`harness_state.json`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/harness_state.json) for retrieval in future sessions.**

The `/refine` command is a core feature of [PrimeIntellect-ai/prime-agent](https://github.com/PrimeIntellect-ai/prime-agent) that lets users record evidence-backed updates to the *continual harness*—the persistent store containing prompt notes, memories, skills, subagent specifications, and refinement events. Understanding how `/refine` persists these improvements reveals the architectural safeguards that prevent data loss and enable cross-session learning.

---

## Architecture of the Refine Persistence Flow

When a user invokes `/refine`, a multi-stage pipeline ensures reliable persistence:

1. **Host Request Handling** – The TypeScript host receives a `refine.run` request
2. **Scheduling** – Execution is deferred to avoid deadlocks
3. **Recording** – A `RefinementEvent` is constructed and merged
4. **State Synchronization** – External changes are reconciled
5. **Atomic Persistence** – The harness is written to disk

This design separates concerns between the TypeScript host (UI/scheduling) and Python runtime (state management), with careful coordination around concurrent access.

---

## Step 1: Host Receives and Schedules the Refine Request

The entry point in the TypeScript host is `handleRefineHostRequest` in [`packages/coding-agent/src/core/agent-session.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/coding-agent/src/core/agent-session.ts). This function accepts `refine.run` requests containing the user's instructions and a `global` flag indicating scope.

```typescript
// Inside an active turn
session.handleRefineHostRequest("refine.run", {
    instructions: "capture a lesson",
    global: false
});

```

The scheduling logic prevents a critical deadlock: refine operations must run *after* the current turn completes because they may modify the same state the turn is actively using. In **serialized mode**, background planning may begin immediately, but the actual refinement waits for turn completion.

---

## Step 2: Kernel Records the Refinement in Python

After the turn ends, the kernel invokes `record_refinement` on the `HarnessState` object defined in [`prime-agent-runtime/src/rlm/harness.py`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/prime-agent-runtime/src/rlm/harness.py). This method constructs a `RefinementEvent` with:

- A **unique identifier** (e.g., `refine_0001`)
- The **trigger description** explaining what prompted the refinement
- The **list of changes** to be applied
- Optional **evidence** supporting the change
- Optional **outcome** describing results
- A **timestamp** for chronological ordering

```python
state = get_harness_state()
event = state.record_refinement(
    trigger="observed repeated failure",
    changes=["create memory: validation rule"],
    evidence="log shows missing check",
    outcome="validation succeeded",
)
print(event.id)  # e.g. "refine_0001"

```

The `RefinementEvent` structure enables **version-controlled, auditable** improvements to the harness.

---

## Step 3: Disk Synchronization Prevents Clobbering

Before writing, `record_refinement` calls `_sync_from_disk` to reload any external edits. This protects against a race condition: the host-side `/refine` handler may have rewritten [`harness_state.json`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/harness_state.json) while the Python runtime was processing the current turn.

The synchronization uses **modification time caching** (`_loaded_mtime`) to detect external changes. If the file on disk is newer than the cached version, the harness is reloaded and changes are merged before the new refinement is appended.

---

## Step 4: Atomic Persistence to JSON

The `HarnessState.save` method serializes the complete harness—including all entries (memories, skills, notes) and the full refinement history—to [`harness_state.json`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/harness_state.json). Default location:

```bash
~/.prime/agent/harness/harness_state.json

```

Override via environment variable:

```bash
export RLM_HARNESS_STATE_DIR=/custom/path

```

The write is **atomic**: the file is written to a temporary location and moved into place, ensuring readers never see partially written state. The modification time is then cached for future synchronization checks.

---

## Step 5: Future Sessions Retrieve Persisted State

Subsequent sessions call `get_harness_state`, which implements **lazy reloading**:

- Returns the cached `HarnessState` if the file hasn't changed
- Reloads from JSON if `_loaded_mtime` differs from the file's actual mtime

Once loaded, stored refinements appear in `overview()` and feed into prompt-building logic:

```python
state = get_harness_state()
print(state.overview())

# Shows "refinements: 1" and the latest event details

```

This retrieval mechanism makes `/refine` improvements **durable and automatically available** without manual intervention.

---

## Key Implementation Files

| File | Responsibility |
|------|---------------|
| [`prime-agent-runtime/src/rlm/harness.py`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/prime-agent-runtime/src/rlm/harness.py) | `HarnessState` class, `record_refinement`, `_sync_from_disk`, JSON persistence |
| [`packages/coding-agent/src/core/agent-session.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/coding-agent/src/core/agent-session.ts) | `handleRefineHostRequest`, scheduling, host-side request handling |
| [`packages/coding-agent/docs/usage.md`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/coding-agent/docs/usage.md) | User-facing `/refine` CLI documentation |
| [`packages/coding-agent/test/suite/agent-session-refine-skill.test.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/coding-agent/test/suite/agent-session-refine-skill.test.ts) | End-to-end refine flow validation |

---

## Summary

- **`/refine`** triggers a `refine.run` request handled by `handleRefineHostRequest` in the TypeScript host
- Execution is **scheduled after turn completion** to prevent deadlocks
- **RefinementEvent** objects capture structured change records with evidence and outcomes
- **`_sync_from_disk`** reloads external changes before writing, preventing clobbering
- **Atomic JSON persistence** to [`harness_state.json`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/harness_state.json) (default: `~/.prime/agent/harness/`) ensures durability
- **`get_harness_state`** provides cached or fresh access, with automatic mtime-based invalidation
- Stored refinements surface in `overview()` and integrate into future prompt construction

---

## Frequently Asked Questions

### Where is the harness state physically stored?

The harness state is stored as [`harness_state.json`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/harness_state.json) in `~/.prime/agent/harness/` by default. You can override this location by setting the `RLM_HARNESS_STATE_DIR` environment variable before starting the agent.

### What happens if two processes try to refine simultaneously?

The `_sync_from_disk` mechanism detects concurrent modifications via file modification times. Before writing, the runtime reloads any external changes and merges them with the pending refinement. This prevents clobbering but does not implement true distributed locking—rapid concurrent writes in the same millisecond could theoretically race.

### How can I inspect my accumulated refinements programmatically?

Call `get_harness_state().overview()` in Python to see a summary including refinement count and recent events. For full details, access `state.refinements` directly to iterate through the `RefinementEvent` history.

### Does `/refine` support undoing or reverting changes?

The source code does not expose a native undo operation. Each `/refine` appends an immutable `RefinementEvent`. To effectively undo, you would issue a compensating refinement that documents the reversal, or manually edit [`harness_state.json`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/harness_state.json) while the agent is stopped (though this bypasses synchronization safeguards).