Skip to content

LocalHarness — architecture

The System

  1. 1
    you type into the terminal channel
  2. 2
    the orchestrator routes scores an agent card — live wiring is planned
  3. 3
    the agent loop reason → act → observe
  4. 4
    the context window built each turn, compacted at 80%
  5. 5
    the model completes locally — Ollama · vLLM · llama.cpp · LM Studio
  6. 6
    tools dispatch fenced — registry validates, pre/post hooks fire
  7. 7
    built-ins run and return a result for the loop to observe
  8. ↺
    the event bus every step lands here: typed, ordered, replayable
  9. ↺
    memory injects back recalled context each turn — see Plate II
fig. 01 — PLATE I — the shipped runtime: one request finding its way through

the parts

  • you a terminal or a chat app; every conversation comes in the same way.
  • the orchestrator one main agent reads your task and runs the loop: think, act, check, repeat.
  • tools read, write, run, search — an agent holds only the tools you allow.
  • the helpers specialists take delegated pieces, each in a fresh window, fenced to its job.
  • the model server the thinking runs on the server you already have — vLLM, Ollama, LM Studio, llama.cpp.
  • the bus every step is written down in order; the live view and the replay read it.
  • memory what it learns outlives the session — gated on the way in, filed while idle.
_deeper src/localharness/ ↗SECURITY.md ↗_getting started ↗

The Loop

One turn at a time — read, act, check. Gates keep a run honest and stop it running away.

  1. 1
    task in a turn begins
  2. 2
    think the model
  3. 3
    act a tool call
  4. 4
    look the result — then loop back to think
  5. ↺
    budgets cap the work before each step
  6. ↺
    parse-repair fix a malformed tool call
  7. ↺
    act-guard did it actually act, before answering?
  8. ↺
    self-check review the answer before it ships
  9. ↺
    stuck-detector nudge once, then stop a run that spins
  10. ✓
    answer the turn ends
fig. 02 — one turn — and the gates that keep it honest

the gates

  • Budgets every run gets a ceiling on how many actions it may take and how long it may run, checked before each step.
  • Act-guard if the model announces a plan but then stalls without doing anything, the harness nudges it once to actually take the step.
  • Self-check before a plain answer goes out, the model is asked to review its own work and confirm it, or fix it.
  • Parse-repair when the model’s tool request comes out garbled, the harness repairs the format and retries instead of crashing.
  • Stuck-detector if it keeps repeating the same move without progress, the harness first nudges it, then stops the run rather than spin forever.
_deeper agent/loop.py ↗_demo ↗

Each turn ends; what it learned doesn't — memory carries it to the next one.

Memory

It takes notes while it works, and files them while it sleeps — memory at every scale, from one window to forever.

  1. 1
    gates score every outcome as you work — write · predictive · user-signal
  2. 2
    below-line writes land SQLite knowledge graph — visible at conf≥0.7 AND rs≥0.2
  3. 3
    while idle, the sleep pass files them fold → promote → decay — any user turn cancels
  4. ↺
    idle_llm the one safe idle-LLM path — cancellable, grounding kills
  5. 4
    chapters cross the line one grounded 0.8 chapter per cluster — 100 lessons → 1 line
  6. ↺
    grounding kill · reconciliation · mining CONFIRM / REVERT / UNDECIDED — corrections + personal facts → ·65
  7. 5
    next sitting, recall injects byte-stable, each turn — back to PLATE I
  8. ↺
    chapters first ### Knowledge — one line per chapter
fig. 03 — PLATE II — hierarchical memory: fast capture, slow consolidation, recall

at every scale

  • the window big results park as short notes; one call pulls the full text back.
  • the task a document bigger than the window is read in sections — and the section notes persist.
  • the sitting every step is recorded in order; each sitting ends with a short summary on the shelf.
  • for good facts survive across sittings, in a database and a file you can read.

how it learns

  • two ways in it saves what you tell it to, and what surprises it.
  • surprise, measured it learns each tool’s usual result; a surprising failure is worth remembering.
  • new memories wait fresh notes stay out of view until idle time confirms them.
  • it sleeps on it while idle, it files recurring lessons and lets stale ones fade.
  • lessons become chapters related lessons are written up as one chapter that keeps its identity as it grows.
  • corrections stay careful when you say “that’s wrong,” the fix is saved separately and can be undone.
  • it never pretends every write is read back and checked; a failed write fails loudly.
  1. 1
    captured gates write at ·5 – ·69 — always below the line
  2. 2
    staged reads bump _staged access counters only
  3. 3
    folded fold_staged_access — only at a consolidation boundary
  4. 4
    promoted / decayed / superseded ≥2 episodes → ·8 crosses · decay floor ·05 · old row stays
  5. 5
    recalled injected above the line, or searched below it

the visibility line: the injected block reads only conf ≥ 0.7 AND rs ≥ 0.2 — and every write is read back or raises MemoryVerifyError.

fig. 04 — DETAIL A — inside the memory store: one fact's life
_deeper memory/sqlite.py ↗memory/consolidation.py ↗memory/gate.py ↗agent/context.py ↗_quality > speed ↗

The settings are just a starting point — the harness tunes them itself and keeps only what measurably helps.

Autoresearch

It tries one change at a time and keeps it only if it measurably helps.

  1. 1
    ParentSampler draws a parent config from the archive — ε-greedy over a Pareto front
  2. 2
    Proposer stronger model reads failed TRAIN traces, emits one GEPA-style change
  3. 3
    run_experiment isolated git worktree · Welch on TRAIN, non-regression on sealed HOLDOUT
  4. 4
    interpret one verdict — ADOPT · HOLD · REJECT · SKIP
  5. 5
    adopt auto, not a gate — a git commit, revert in one command
  6. 6
    Mutation Archive sqlite · records every attempt · feeds ParentSampler, closing the loop
  7. 7
    daily report HELD, inconclusive wins reviewed async — no human approval gate
  8. ↺
    parent the archive feeds the next sampler — the loop closes
  9. ✓
    New Baseline a clean adopt becomes the baseline for the next iteration

runs on its own corpus — a 25-scenario TRAIN slice the proposer may read, and a sealed 10-scenario HOLDOUT (scores only).

mutation surface: system_prompt · tool_description · compaction_threshold · stuck_detector · recovery_injection · hook_config.

guards never halt the loop — BudgetController circuit-breaks on wallclock / iterations / window; Eval Sentinel watches overfit & near-dupes to guard the holdout.

fig. 05 — PLATE III — the autoresearch loop: propose, gate, adopt — against its own corpus

the gate

  • a stronger model proposes a separate, stronger model suggests one change at a time.
  • tested in a throwaway copy the change runs a fixed task set in a disposable checkout; your setup is never touched.
  • held to a real bar kept only if it clearly beats the current version, not if it just edges ahead by luck.
  • a sealed set it never sees a final exam it cannot study for, checked only at the end.
  • adopted as a commit a win lands as a git commit; undoing it is one command.
  • the gate can say no a change that misses the bar is archived, never adopted.
_deeper autoresearch/experiment.py ↗autoresearch/proposer.py ↗autoresearch/archive.py ↗