Map / Outline
Self-evolving agents
A scheduled loop that studies sources and its own logs, promotes what is corroborated, and is graded on sealed tests.
What it is and why it exists
What
A self-evolving agent improves between conversations. On the reference build a nightly learner reads documents and logs, writes candidate claims, verifies and corroborates them, and promotes the survivors into what the agent can recall.
Why
Most improvement comes from noticing the same failure repeatedly and encoding the fix. Automating that is powerful and dangerous. The loop changes no model weights. It changes stored knowledge, routing exemplars, and rules, and all of it reaches an answer only through a tool call.
How it works
- Staged study: define terms, outline a document, extract claims, link them. Each stage has a queue ordered by authority.
- Promotion gate: a claim becomes serveable only with enough independent support. Copies of one passage count once.
- Verification: a two-vote check compares served claims with their sources. Failures leave service as unsupported.
- Self-observation: the loop mines logs for failures that returned success codes, such as an empty result that a relaxed filter would fill.
- Corroboration for self-observations is keyed on the day. Failing twice in one session earns nothing. The same failure on three separate days earns trust.
- Everything is graded on sealed sets the loop cannot read or write.
Where it sits in the build order
Needs first
- EvaluationA loop optimizes what it can measure. Sealed evals have to exist before the loop runs, or it grades itself.Build out of order Stub it with: None that is safe. You can run the loop in report-only mode without evals, and you should not let it apply changes.
- MemoryLearned claims and rules are a form of memory. They use the same store, status fields, and recall path.Build out of order Stub it with: Append findings to a Markdown file for human review.
- Guardrails and verificationPromotion gates and claim verification are guard logic applied to stored knowledge.Build out of order Stub it with: Human approval of every promotion.
- RAG and knowledge graphThe learner reads indexed chunks and writes claims that point back to passages.Build out of order Stub it with: Feed it plain text files.
Unlocks
Nothing depends on this. It is an end point of the map.
In the reference build
| Path | Role |
|---|---|
| apps/agent-server/nightly/scheduler.py | Duty cycle and preemption for background work. |
| apps/agent-server/nightly/self_observe.py | Finds confident wrong answers in the logs. |
| apps/agent-server/nightly/conversation_learn.py | Learns from real conversations, ignoring eval threads. |
| apps/agent-server/nightly/corroboration_audit.py | Checks that support is independent. |
| SELF-EVOLUTION-LESSONS.md | What went wrong and what was changed. |
The same idea on other platforms
| Platform | How this module maps |
|---|---|
| Databricks | Lakeflow Jobs schedule the loop. Traces and labeled feedback are the raw material. Evaluation datasets grow from production traces, and judges can be aligned with human labels. |
| IBM watsonx | Schedule jobs outside Orchestrate and write results to a governed store. Monitors in watsonx.governance provide the drift signals. |
| Codex | A scheduled headless run can review logs and propose changes to AGENTS.md or skills as a pull request for review. |
| Cursor | Background agents can do the same review and open a pull request. |
| Claude Code / Agent SDK | A scheduled headless session can read logs and propose skill or instruction edits. Keep a human merge step. |
| Another machine | A scheduler such as launchd, systemd timers, or cron, plus the same scripts. |
Explain it back
Answer aloud first. Then open the answer and compare.
What does the learner change, and what does it never change?
A strong answerIt changes rows in the knowledge store, routing exemplars, and rule files. It never changes model weights. Learned knowledge reaches an answer only when a tool returns it.
Why is corroboration counted by independent document and by day?
A strong answerTen copies of one paragraph are one source. Two failures in one session are one event. Counting them as many would let repetition pass for evidence.
From the live build
Recent changes and files the sync job filed under this module.
- Corroboration needs two independent texts: copies of one passage count once; duplicate the regulation copy retired from the learner queue
- Learner: 8 minutes of source checks in every window, so claim verification keeps pace with what is written
- Claim judges: the agency and the agency are one name; claims rejected for that are checked again
- claim_verify: a simplification alone keeps a claim in service; --redecide re-applies the rule to recorded votes
- Claim verification live: nightly two-vote check, claims failing both leave service as 'unsupported'; omission alone keeps a claim; VERIFY line in the daily report
- claim_verify: two-vote check of served claims against their source (dry run and calibration); off-topic the oversight body reports retired from the learner queue
- Out of tool rounds: one final turn without tools answers from the evidence gathered; restate standing after promotion; ordered promotion queue
- BUSY sentinel is held until a streamed response finishes, so the learner pauses for the whole chat answer
- Spending orchestration
- CLAUDE.md — build-host Mac Studio
- Fixes applied — 2026-09-07
- Self-evolution: what was broken, what changed
- BUILD-HOST — user guide
- What the failures teach about making the agent actually get smarter
- two copies of one text are one voice. venv/bin/python3 nightly/corroboration_audit.py # incremental venv/bin/python3 nightly/corroboration_audit.py --all # every claim with 2+ documents venv/bin/python3 nightly/corroboration_audit.py --stats "Corroborated" means a claim is ...
- the circadian clock (BRAIN-ARCHITECTURE.md §4.0). This is the piece that turns "a script you remember to run" into a system that runs itself. It owns two things and nothing else: R1 When the Vercel app calls the LLM server, learning PAUSES. External requests always win.
- check served claims against their source, two votes, and take the ones that fail both out of service.
- do the claims the agent serves say what their source says? venv/bin/python3 nightly/claim_fidelity.py --n 200 # print only venv/bin/python3 nightly/claim_fidelity.py --n 200 --write # + history "Authoritative" means the source document is tier 1.
- lets the agent answer questions ABOUT ITS OWN LEARNING with facts instead of assumptions. WHY THIS EXISTS --------------- Asked "what new knowledge did you gain in the last 100 hours?", the agent answered: "Honest answer: nothing. And that's not a gap — it's by design.
- go over EVERY file, in stages, resumably. This replaces the first Diet B, which walked 81,636 chunks in database order and had no idea what any of them were.
- learn from what people actually said. python3 nightly/conversation_learn.py # report, write nothing python3 nightly/conversation_learn.py --apply # record python3 nightly/conversation_learn.py --all # ignore the cursor WHY THIS EXISTS =============== This system had three ways ...
- Phase 1 of the nightly loop (BRAIN-ARCHITECTURE.md §4.1). "Hippocampal replay": read the day's traffic, find where the agent failed, turn each failure into a gap the agent can later study.