The Evolution Loop

Previously learns how to treat you better — but it cannot quietly rewrite itself. Every change starts from evidence, the trigger math lives in deterministic code, and most of the time the loop's verdict is to change nothing at all.

Self-evolution in Previously is Darwinian, not accretive. Four roles, mapped onto the biology:

No trigger, no evolution

The loop is checked on every turn, before the agent answers — and the check is one number, computed in code. The fitness store is not a credit history; it is the current generation's pressure gauge. When a bucket's net score reaches −5, evolution runs now. That is five weak signals (−1), or two explicit complaints (−2) plus one: noise never fires it, a sustained pattern does.

A successful run settles the generation — the ledger is cleared, because the outcome has already sedimented into the direction, the card, or a playbook, and "checked, no change" counts as an outcome too. A failed run settles nothing: the pressure is still there next turn. Your explicit requests — "remember this…", "stop doing that" — never enter this accounting; they ride a separate instruction channel and fire their own run.

A mandatory check is not a mandatory mutation. The most common result of an evolution run is no_change. The trigger only buys a careful re-read of the original evidence — whether to change anything, and what, is the evolution agent's own ruling.

The environment: a portrait, not a rulebook

memory/evolution/direction.md is what the loop has learned about you as a person — the environment the products adapt to. It has exactly two sections.

# Portrait — confirmed understanding, organized into six fixed dimensions: Traits & cognitive style · Triggers & rhythms · Patterns & loops · Strengths & resilience · Communication preferences · Values & boundaries. An entry earns its place only when it meets three hard conditions:

• it holds across contexts, not just in the conversation that evidenced it;
• it outlives the event — still true after the deadline passed, the trip ended, the project shipped;
• it predicts — what you will do or need next time.

The portrait is descriptive, never imperative: it describes you, it never tells the agent what to do. And its body text carries no names, dates, or events — specificity lives only in the trailing — refs: slice pointers, so every line can be drilled back to the raw record.

# Hypotheses — a bounded pool (≤ 10) of trait-level guesses that haven't earned promotion yet:

- [proposed 2026-08-10-2130] You commit faster after talking a decision through — falsify if: you twice decided without needing the dialogue first

A guess without a falsification condition is a fantasy, so the condition is mandatory. The lifecycle is enforced in code, not by good intentions: confirmed (evidence from at least two distinct slices, or your explicit confirmation) → promoted into the Portrait in the same run; refuted → removed; still unverified four slices after it was proposed → retired automatically, re-proposable on new evidence. Every run refills the pool toward ten. The portrait and its open hypotheses ride the main agent's system prompt — the guesses visibly marked as unverified, probed gently, never asserted as fact.

The first-ever portrait and legacy-format documents are covered by bootstrap/migrate gates in code, with a correspondingly lowered evidence bar.

Scores are sensors, not judges

Selection pressure comes from a turn analyzer that reviews each turn after the fact — the agent never grades itself. Five buckets — card / recall / search / thinkdeep / interaction — each keeping its own account of ordinal deltas from −2 (explicit complaint or correction) to +1 (explicit approval). Two structural rules keep the ledger honest:

• No evidence, no score. Every non-zero delta must carry your own words as evidence; an evidence-less delta is force-zeroed inside the store, not by prompt discipline. A score may be wrong, but it may not be sourceless.
• Scores decide whether, never what. A trigger buys a re-read of the evidence, not a mutation.

The analyzer scores against the portrait as its learned rubric: a turn that matches a known failure pattern earns −1 with evidence even without an explicit complaint. And not every signal is a score — your own UI reactions are instrumented mechanically: a regenerate and a stopped answer are recorded as bare facts (interaction_regenerate, interaction_interrupt), candidates for a −1 the analyzer may or may not assign. The recall colleague has its own instrumentation too: when the main agent re-reads a slice recall already answered from, the read is classified as verify, rework, or repeat — rework being the quiet demerit.

One merged run, one writer

When evolution fires, it fires once — a single merged run. The Previously Agent evaluates the direction first, propose-only, holding no write tools; the proposal is validated in code (fixed skeleton, per-hypothesis metadata, an evidence bar of at least two distinct slices in steady state). A rejected proposal is surfaced honestly as rejected — never dressed up as "no change" — and the gate backs off for the rest of the slice, so a persistently invalid proposal cannot drag the full agent up every turn.

Then, in the same run and under the possibly-new portrait, the agent evolves the products: the user card through validated per-entry mutations (the tool list is in The User Card), and the playbooks of exactly the buckets that triggered. A playbook is one short behavioral brief per colleague — memory/agent-playbooks/{recall,search,thinkdeep}.md — injected into the colleague's user prompt, never the static system prompt, so the provider's prefix cache survives; capped at 2,000 characters, and a missing playbook simply omits the block.

The whole run streams live into the chat — including a skipped run, with its reason. A silent skip would read as "it never runs".

Why there is no mutation archive

Earlier versions kept an append-only archive of every accepted mutation — expected benefits, evidence pointers, self-evaluations. It was deleted, on principle: evolution has no direction, only fit. A mutation is never judged against its predecessor, because there is no progress axis to judge it on — there is only whether the system still fits who you are now. When you change, an old portrait entry should retire; nothing rolls back, because there is no truer past to roll back to. The record of what changed still exists — every file is plain Markdown in git — but it is the version history of the living documents, not a ledger the loop consults.

Related

• The User Card — the evolution loop's main product
• Colleagues, Not Tools — where the fitness buckets come from
• Recall — the rework signal: the most reliable implicit scoring source