ACE Context Evolution
Treat durable context as an evolving playbook, not a shrinking summary. Preserve proven detail, update incrementally, and require execution evidence before promoting lessons.
Use When
- Agent memory,
CLAUDE.md, AGENTS.md, skill docs, or prompt files are being revised after repeated runs.
- Summaries are getting shorter but less useful.
- Lessons learned from failures need to become reusable project context.
- The user wants self-improving agents without fine-tuning.
Core Workflow
- Separate context into stable instructions, reusable strategies, task evidence, rejected ideas, and open questions.
- Add new lessons as patches with source evidence instead of rewriting the whole context.
- Promote only lessons backed by run logs, tests, user corrections, benchmark deltas, or repeated task outcomes.
- Preserve provenance: include where the lesson came from, when it was observed, and when it should be reconsidered.
- Prune by invalidating obsolete entries, not deleting them silently, when future agents may need the reason.
- Run a collapse check before accepting a rewrite.
Context Patch Contract
Every durable update should include:
| Field |
Purpose |
claim |
The reusable instruction or lesson |
evidence |
Command, trace, eval, user correction, issue, PR, or paper source |
scope |
Where it applies and where it does not |
owner |
File, skill, team, or subsystem affected |
expiry |
Date or condition for review |
conflicts |
Older rules this supersedes or limits |
See context-evolution-contract.md for templates.
Collapse Guard
Before replacing any long-lived context, compare the old and new versions:
python skills/context-engineering/ace-context-evolution/scripts/context_update_guard.py OLD.md NEW.md
Reject the rewrite if it drops named tools, file paths, commands, metric thresholds, failure modes, citations, or explicit constraints without an invalidation note.
Common Mistakes
| Mistake |
Fix |
| Rewriting the whole context after each run |
Apply small patches grouped by evidence type |
| Treating shorter as better |
Preserve operational details that changed behavior |
| Promoting one-off anecdotes |
Require repeated evidence or a clear high-impact failure |
| Deleting stale rules |
Mark them superseded and keep the reason if future agents may rediscover them |
| Mixing task scratchpads with durable memory |
Keep transient reasoning out of permanent context |
References
1---2name: ace-context-evolution3description: Use when long-lived agents, project memories, system prompts, or playbooks are repeatedly summarized, rewritten, or optimized and risk losing domain detail, provenance, or execution learnings.4---56# ACE Context Evolution78Treat durable context as an evolving playbook, not a shrinking summary. Preserve proven detail, update incrementally, and require execution evidence before promoting lessons.910## Use When1112- Agent memory, `CLAUDE.md`, `AGENTS.md`, skill docs, or prompt files are being revised after repeated runs.13- Summaries are getting shorter but less useful.14- Lessons learned from failures need to become reusable project context.15- The user wants self-improving agents without fine-tuning.1617## Core Workflow18191. Separate context into stable instructions, reusable strategies, task evidence, rejected ideas, and open questions.202. Add new lessons as patches with source evidence instead of rewriting the whole context.213. Promote only lessons backed by run logs, tests, user corrections, benchmark deltas, or repeated task outcomes.224. Preserve provenance: include where the lesson came from, when it was observed, and when it should be reconsidered.235. Prune by invalidating obsolete entries, not deleting them silently, when future agents may need the reason.246. Run a collapse check before accepting a rewrite.2526## Context Patch Contract2728Every durable update should include:2930| Field | Purpose |31| --- | --- |32| `claim` | The reusable instruction or lesson |33| `evidence` | Command, trace, eval, user correction, issue, PR, or paper source |34| `scope` | Where it applies and where it does not |35| `owner` | File, skill, team, or subsystem affected |36| `expiry` | Date or condition for review |37| `conflicts` | Older rules this supersedes or limits |3839See [context-evolution-contract.md](references/context-evolution-contract.md) for templates.4041## Collapse Guard4243Before replacing any long-lived context, compare the old and new versions:4445```bash46python skills/context-engineering/ace-context-evolution/scripts/context_update_guard.py OLD.md NEW.md47```4849Reject the rewrite if it drops named tools, file paths, commands, metric thresholds, failure modes, citations, or explicit constraints without an invalidation note.5051## Common Mistakes5253| Mistake | Fix |54| --- | --- |55| Rewriting the whole context after each run | Apply small patches grouped by evidence type |56| Treating shorter as better | Preserve operational details that changed behavior |57| Promoting one-off anecdotes | Require repeated evidence or a clear high-impact failure |58| Deleting stale rules | Mark them superseded and keep the reason if future agents may rediscover them |59| Mixing task scratchpads with durable memory | Keep transient reasoning out of permanent context |6061## References6263- arXiv: Agentic Context Engineering: Evolving Contexts for Self-Improving Language Models - https://arxiv.org/abs/2510.0461864- Hugging Face Papers: Agentic Context Engineering - https://huggingface.co/papers/2510.0461865- GitHub: ACE implementation - https://github.com/ace-agent/ace66- GitHub: ACE AppWorld experiments - https://github.com/ace-agent/ace-appworld
mouadja02