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

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 for retrieval in future sessions.

The /refine command is a core feature of 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. This function accepts refine.run requests containing the user's instructions and a global flag indicating scope.

// 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. 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

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 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. Default location:

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

Override via environment variable:

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:

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	HarnessState class, record_refinement, _sync_from_disk, JSON persistence
packages/coding-agent/src/core/agent-session.ts	handleRefineHostRequest, scheduling, host-side request handling
packages/coding-agent/docs/usage.md	User-facing /refine CLI documentation
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 (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 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 while the agent is stopped (though this bypasses synchronization safeguards).

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}