Reflective self-improvement

Type: kb/articles/types/article.md · Status: draft

Your agent can read its own source: the prompts that steer it, the instruction files it obeys, the skills it loads — plain prose, sitting in a repository the agent itself can open, search, and criticize. Beside the prose sit the actuators — the code of its validators, the harness that runs it — and the agent can read and interpret those too, in the same pass that reads the instructions. Software that acts on a representation of itself is not new — computational reflection has a decades-old literature. Prose that steers behavior is not new either: legal codes and operating procedures have always been operative, through human readers. What is new is who does the reading: with LLM agents, part of the interpretation, criticism, and rewriting moves inside the computational boundary, and that pulls the prose into the reflective system beside the code. A system that keeps its definition in prose and code together can improve itself by analyzing and rewriting that definition — a reflective system that includes prose, and a single reader connecting the two halves, are both new. The name for this is reflective self-improvement, and Commonplace is a framework for doing it systematically.

The bootstrap, with the author inside

The nearest precedent is the self-hosting compiler — and the differences are the point. Once a language compiles itself, every improvement to the compiler is written in the language it improves. But the compiler never analyzes its own source. It has no opinion about its code: every change was searched for, judged, and adopted by humans; self-hosting contributed only the causal wire from artifact to behavior. Agents move part of the author inside the system. An agent can analyze its own instructions and code, find what is wrong with them, and propose better ones — and once a proposal is accepted, the improved artifacts define the next run, without touching a single weight.

This is reflection in the older, computational sense — a system containing a causally connected representation of itself — not "the model reflects on its mistakes." It also buys what fine-tuning cannot: addressability. A lesson retained as an artifact can be inspected, explained, revised, or deleted one at a time. Suppose last month the agent recorded a rule: "always pin the dependency versions." You can find that note, ask what incident produced it, tighten it, or retire it. A weight update can be trained over, rolled back wholesale, or steered against from outside — never addressed one lesson at a time.

Two more payoffs follow, held with different confidence. The first is the one safety-minded readers should care about: the loop is legible. Self-improvement in weights hands oversight a tensor delta — behavior can be measured before and after, but the change itself cannot be read. Self-improvement in artifacts hands oversight a plain-text diff that carries its own rationale, so an overseer can hope to decide about a change by reading it rather than by probing its behavior. The second payoff is openly a conjecture: sample efficiency. A retained theory that captures structure surviving a task shift may adapt the system with fewer new target observations than retraining or fine-tuning would need — a directional prediction with a proposed test, not a result.

What the compiler had and the agent loses

Two safeguards do not survive the transfer. The compiler's wire is exhaustive: every build consumes the whole source, and nothing depends on being found. The agent's wire is retrieval, and retrieval is best-effort. A retained lesson counts only if a later run finds it — the note that would have prevented today's mistake, sitting unread two directories away, might as well not exist. That is why retrieval failure is reflection failure. The compiler bootstrap also carries at least a fixed-point check: recompile the compiler with itself and compare the outputs. Ken Thompson showed in his Turing Award lecture that even this check can be fooled — a compiler corrupted in the right spot reproduces its own corruption while passing cleanly — so it was never proof of soundness, only a tripwire for accidental breakage. The agent has no tripwire at all: there is no fixed-point check for "this rewritten instruction is better," and the agent judges its proposed changes using the very instructions being changed — trusting trust again, with fuzzier tools.

Structure makes the missing half explicit

So a serious agent bootstrap must supply the verification that self-hosting never had built in. It needs contracts for what counts as a claim, and validation that runs as code rather than as self-assessment. It needs review that can say no from outside the text it judges, and navigation that makes retrieval reliable. Commonplace is that structure. Its typed artifacts declare what kind of claim a note makes; its validators are code; its review gates apply fixed criteria in a fresh context, so a note never grades itself; its curated indexes give retrieval a maintained map. Yet the goal is not mere accumulation. A memory file that piles up lessons is a junk drawer whatever its format. The loop is aimed at theories with explanatory reach — retained claims that explain why something works and hold beyond the episodes that produced them. "Retry the flaky login test" is a lesson; "tests that read the wall clock flake, so freeze the clock" is a theory, and it keeps working on tests that have not been written yet. Review exists to test whether a claimed reach is genuine rather than a coincidence dressed as an explanation.

The framework practices what it sells: Commonplace retains its own methodology as a Commonplace knowledge base and improves through it. One traced episode: an index page promised to list every note carrying its tag, and grew until that promise quietly broke. The strain became a recorded decision; the decision became validator code; and the new validator caught a case the old prose search instructions had missed — which corrected the instructions. Operation revised the system's definition, and the revised definition changed operation. At every step, though, the operative "no" belonged to a human maintainer reviewing and merging: the structure produced the artifacts and the evidence; a maintainer inside the loop accepted them. That is an allocation, not a rung — which functions are human, joint, or computational, read per decision. Removing the human would not make the loop a more advanced version of itself; it would move one function to a different actor, and moving a judgment to a model changes who decides without establishing that the decision is sound. Migration inward is earned rather than waited for: a decision becomes safely computational once its criterion is written down and something can check it. Until then the structure earns its keep by making each acceptance localized, evidenced, and reversible. The whole trail is in the commit history.

Where to go next

If your agent stack retains lessons about its own operation and later uses them to alter that operation, you are already running one of these — loosely. Two questions measure how loosely: where can your loop say no, and which artifact absorbs the accepted change?

The pattern is being measured, too: a July 2026 preprint on knowledge-centric self-improvement keeps its agents generic and disposable, makes a curated knowledge base the only object that improves, and reports gains that survive freezing the artifact and handing it to a different model family. A theory earns its keep by profiling such systems claim by claim — what is retained, when it becomes operative, what is addressable, and where its warrant stops. The self-improving-systems cluster maps that theory, and the repository is the framework itself, bootstrapping in public.