Your agent watches your real work, finds where you're actually stuck, traces it to the discipline that studied it for decades, and feeds what it learned into your memory — so next time, it surfaces on its own.
Pairs with mneme.
mneme → can it store this, and find it again?
Evolve → what is worth storing in the first place?
Everything runs on your machine. Your work never leaves it.
Most "AI learning" tools generate a tidy daily digest that nobody reads. That is the collector's fallacy, automated.
The learning loop that actually compounds looks like this:
work → hit a wall → learn the thing → store it → it surfaces next time you hit that wall → better work
mneme already solves the last two arcs: storage and recall.
Nobody solves the first two. Who notices you were stuck? Who decides what's worth learning?
That is Evolve.
It learns what you're stuck on, not what a curriculum says you should know.
A reading list produces knowledge that never connects to today's work, so it never fires. Evolve reads your actual traces and works backwards from real friction.
It digs to the theory under the craft.
You're rarely stuck on a tool. You're stuck on the thing underneath it — and there's usually a field that has studied that thing for forty years. The real prize isn't the theory, it's its boundary conditions: that discipline already knows where this breaks. That's a free pre-mortem.
It only counts what fires.
A memory that never changes a decision is dead weight. Evolve tracks which memories actually fire during work and prunes the ones that don't. That's the difference between a system and a notebook.
That's the expected case. Run:
npx @agentgamelab/evolve initEvolve looks at where you already are and builds what's missing:
| Check | If missing |
|---|---|
| A memory store | installs and initializes mneme |
| A thinking core for your agent | writes a starter one (first-principles triggers, pre-mortem, working backwards) |
| A scheduled run | registers one |
| A diet — what's worth learning | derives one from your actual project (see below) |
Then it explains, in plain language, what it did and why. Nothing is hidden.
No questionnaire. You'd have to maintain it, and it would go stale. Your project folder already says what you do.
npx @agentgamelab/evolve init --keep-existingDetects what you have, fills only the gaps, touches nothing else.
Day one, you have no traces. But you have a project — and a project doesn't lie.
project folder → language, framework, deps, README, structure, commit history
→ what you actually work on
→ what that work is, underneath
→ which disciplines study that
→ a starter diet, specific to you
A Godot repo with heavy Tween use and a combat/ directory gets a very different diet than a repo full of Airflow DAGs. Neither gets a generic "top 10 books" list.
From day two, real traces take over and the seed diet gets corrected by what you're actually stuck on.
observe → read local traces (sessions, git, project files, mneme)
find gaps → where did work actually go wrong?
map → what discipline studies this? where does it break?
learn → read the canon, pass a 3-part gate
sediment → write to mneme as a situated heuristic
prune → which memories never fired? drop them
report → one short message: what, why, and from which real moment
Real friction leaves marks. Evolve looks for marks, not feelings.
| Signal | What it means |
|---|---|
| You were corrected | A human said "no, not like that" — the strongest signal there is |
| You looked it up again | Third time searching the same thing means it never stuck |
| You took the long way | Five attempts to get there means a missing model |
| It took too long | Way over your own baseline for that kind of task |
| You rebuilt an existing wheel | Prior art existed; the reflex to check was missing |
| You retracted yourself | Your reasoning wasn't standing on anything |
| You avoided it | You keep routing around a class of work. The most hidden, and the most valuable |
Nothing went wrong today? Evolve doesn't idle and doesn't fall back to a syllabus. It studies what you used but never examined — still anchored to real work.
A learning only counts if all three land:
- What is the principle?
- Why does it hold — and where does it break?
- How does it map to what I'm building?
Name-dropping doesn't count.
A biological theory does not become architectural evidence just because the names rhyme.
| Label | Meaning |
|---|---|
direct |
Mechanism is isomorphic to yours |
analogy |
Credible, gives design constraints, not proof |
heuristic |
A question frame only. Not a law |
An honest heuristic is worth more than an inflated direct. Evolve refuses to store a mapping without a label.
Store an inert fact and it will never appear when you need it. Store a situated heuristic and it matches by context.
✗ "CLS is a two-system theory of hippocampus and neocortex."
→ true, useless. It will never surface at the moment you need it.
✓ trigger: about to design any "novel" mechanism
principle: ask which discipline has studied this for decades
apply: use its boundary conditions as a free pre-mortem
Evolve won't write to mneme without a trigger.
Continuous re-summarization degrades. Utility rises, then falls. An episodic-only baseline stays competitive. — Useful Memories Become Faulty When Continuously Updated by LLMs (2026)
So:
- Raw traces are first-class evidence. Distillation never overwrites them.
- Every distillation is reversible. Provenance is kept.
- More summarizing is not more mature. Evolve will not crank the frequency for you.
| Reads | session transcripts, git, project files, mneme — all local |
| Uploads | nothing |
| Network | only to read public theory — never your work |
| Auditable | every stored item points back to the real moment that produced it |
core/ pure logic — observe → gap → map → diet → sediment
no harness imports. portable by construction.
adapters/
claude-code/ first adapter. reads ~/.claude transcripts,
registers via skill + cron + hook.
<yours>/ implement: read traces / schedule / trigger
deps: mneme (storage + recall). Not reinvented here.
Claude Code first, on purpose. We'd rather prove this changes real output on one harness than ship a universal abstraction nobody has run. The core stays harness-free so the second adapter is cheap.
Early. Built by a team that runs this on itself daily.
Honest limits:
- Claude Code is the only adapter today
- Gap detection is heuristic, not learned — it will miss things
- The theory mapper is only as good as the search behind it. Always check the source. It labels strength for exactly this reason
- Sediment quality is not yet measured against a ground truth. Fire-rate is a proxy, not proof
MIT
From the team behind mneme.