Agentic Context Engine: a Skillbook for agents that keep forgetting

The failure ACE is built around: an agent that relearns nothing

The README opens with a blunt claim: AI agents do not learn from experience, repeat the same mistakes every session, forget what worked, and ignore what failed. ACE exists to insert a persistent learning loop into that gap. The target user is not someone building a first prototype. It is someone running an agent repeatedly against similar tasks, watching it fail the same way, and currently fixing that failure by hand in a prompt, a system message or a tool description.

The README's own illustration is a seahorse emoji. The agent asserts that one exists, ACE reflects on the error, and on the next attempt the agent answers correctly without human intervention. That example is deliberately small, but it names the shape of the problem precisely: a factual or procedural error that a human would fix once and never think about again, except the agent has no place to put that fix.

The project also states that ACE is the open-source engine behind Kayba, a hosted service. That framing matters for anyone evaluating it. The repository is the engine; the managed loop, described as failure investigation through to fixes shipped as PRs, is a separate commercial product. You can use the engine without the service, and the README presents that as a supported path.

Skillbook, Reflector, SkillManager: the three roles and what each one writes

The mechanism is a Skillbook, described as a persistent collection of strategies that evolves with every task. Three roles manage the loop. The Agent executes tasks, enhanced with Skillbook strategies. The Reflector analyzes execution traces to extract what worked and what failed. The SkillManager curates the Skillbook by adding, refining and removing strategies.

Splitting curation from reflection is the design decision worth noticing. A system that only appends lessons will grow without bound and will eventually contradict itself, so the SkillManager's removal responsibility is doing real work. The README does not specify the criteria the SkillManager uses to decide a strategy should be dropped, and that is a gap. If you need to know why a strategy disappeared, the documentation as supplied does not answer it.

The README calls the Recursive Reflector the key innovation. Rather than summarizing a trace in a single pass, it writes and executes Python code in a sandboxed environment to search the trace programmatically. The supplied text cuts off mid-sentence at that point, so the rest of the mechanism is not visible here. What can be said is that a sandboxed code execution step is a different cost profile from a single summarization call: it is more capable at locating a specific failure inside a long trace, and it introduces an execution environment you now have to trust and operate.

The Quick Start example shows the loop in its simplest form. Learn from feedback is a single call, and the resulting strategies are readable through get_strategies(). That readability is a practical advantage over approaches that hide learned state inside model weights.

Installing ACE and running the learning loop

The package is published as ace-framework and installed with uv add ace-framework. Configuration has two paths. The interactive one is ace setup, which the README describes as walking you through model selection, API keys and connection validation. The manual path is an environment variable: export OPENAI_API_KEY for OpenAI, or ANTHROPIC_API_KEY for Anthropic, with the README stating that over 100 providers are supported.

The usage example is short enough to reproduce mentally. Import ACELiteLLM from ace, construct it with a model such as gpt-4o-mini, call ask with a question, call learn_from_feedback with a correction, call ask again, then call get_strategies to inspect what was learned. No fine-tuning, no training data, no vector database, according to the README.

That last sentence is the most consequential claim in the setup section. Skipping a vector database means the Skillbook is not a retrieval index over embeddings. It is a curated set of strategies, and the Reflector and SkillManager decide what belongs in it. For teams that already run a vector store for document retrieval, this means ACE does not replace it and does not depend on it. For teams expecting semantic search over past episodes, the mental model is wrong.

The README links to a Quick Start guide, a Setup guide, and a hosted API page titled Where Do Traces Come From. That last link is a signal about prerequisites: the learning loop consumes traces, and the documentation treats trace provenance as a question worth answering separately.

The numbers in the README, and what they do not tell you

The project lists three results. Doubling pass^4 on the Tau2 airline benchmark with 15 learned strategies and no reward signals. A 49 percent token reduction for browser automation across a 10-run learning curve. A $1.50 learning cost for a Claude Code translation of 14k lines to TypeScript with zero build errors and all tests passing.

These are the project's own reported figures. I have not reproduced them, and the README does not supply the harness, the exact configuration or the variance behind them. Treat them as directional. The pass^4 metric is the interesting one because it measures consistency across repeated attempts rather than a single best run, which is the right axis for a system whose whole premise is that agents fail inconsistently. The token reduction figure comes with a learning curve attached, which implies the saving accrues over runs rather than immediately.

The $1.50 figure is the one most likely to be misread. It is a learning cost for one specific task, not a cost per task in general. A loop that calls a Reflector, executes sandboxed Python and runs a SkillManager will add calls to every learning cycle, and the README does not break down where those tokens go. If your workload is high-volume and low-value per call, that overhead is the thing to measure before adopting, not the benchmark result.

Where ACE is the wrong tool

The loop needs a feedback signal. The Quick Start works because a human supplies a correction through learn_from_feedback. The README's benchmark result mentions no reward signals, which suggests the loop can operate without them, but the supplied material does not explain what replaces the signal in that case. If your agent runs unattended with no ground truth, no test outcome and no human review, there is nothing for the Reflector to reflect on, and ACE adds cost without adding learning.

Single-turn, stateless calls are a poor fit for the same reason. The value of a Skillbook comes from persistence across sessions. An agent invoked once per request with no shared state has nothing to carry forward.

The Skillbook is also a new piece of state you own. It persists, it changes, and the SkillManager can remove entries. Nothing in the supplied README describes versioning, rollback or a diff view for Skillbook changes. If a strategy is refined badly and agent behaviour degrades, the material does not show how you would revert to a prior state. The get_strategies() call gives visibility, which is a start, but visibility is not version control.

Finally, the sandboxed Python execution inside the Recursive Reflector is an operational surface. The README states it is sandboxed but does not describe the sandbox. In an environment with strict execution policies, that is a question to resolve before deployment, not after.

Compared with fine-tuning and with a retrieval memory layer

Two alternatives are worth distinguishing, because they fail differently.

Fine-tuning changes model weights on a curated dataset. ACE changes an external Skillbook at runtime and leaves the model untouched. The practical difference is turnaround and reversibility. A Skillbook update happens inside a session, with no training run, and the learned content is inspectable through get_strategies(). A fine-tune is a batch job, and inspecting what changed is far harder. The trade is that a fine-tune can shift behaviour that no prompt can reach, while ACE is bounded by what the model can do when the right strategy is placed in its context.

A retrieval-based memory layer, the kind built on a vector database, stores past episodes and retrieves similar ones by embedding proximity. ACE explicitly does not use a vector database. It stores curated strategies and applies them. The difference shows up in what you get back: retrieval returns a similar past situation for the model to interpret, while a Skillbook returns a rule the SkillManager decided was worth keeping. Retrieval scales with the number of stored episodes; a Skillbook scales with the quality of curation and can shrink as well as grow. Neither is strictly better. Retrieval is easier to build and harder to keep useful; curation is harder to build and produces a smaller, more legible artifact.

Maintenance, release cadence and the licence

The repository is not archived and the last push is dated 2026-08-29. Recent releases include v0.12.0 on 2026-05-07, labelled as an RR/Skillbook v2 rewrite plus SM hardening, along with two tracing packages: openclaw-tracing v0.1.1 and kayba-tracing-ts v0.10.0. The v0.12.0 label is the one to note. A rewrite of the Reflector and Skillbook together, with hardening applied to the SkillManager, means the internals have moved recently. Anyone who adopted an earlier version should expect the Skillbook format or the reflection behaviour to have changed, and the supplied material does not include a migration note.

The existence of separate tracing packages in the release list suggests tracing is treated as its own integration concern rather than something bundled into the core install. The README's link to a hosted API page asking where traces come from supports that reading. If you already emit traces in a compatible format, integration is likely lighter than if you have to add instrumentation first.

The licence is Apache-2.0. That is a permissive licence, and it permits commercial use, modification and redistribution subject to its terms, including its patent grant and notice requirements. This is a description of the licence identifier, not legal advice. If you plan to redistribute ACE inside a product, or to combine it with code under a different licence, have your own counsel review the obligations rather than relying on the identifier alone.

On upgrade cost: the project ships frequently, the core loop was rewritten within the last few releases in the supplied timeline, and the Skillbook is state that lives outside your code. Budget for re-validating learned strategies after a version bump, not just for running the installer.

Editorial conclusion

Adopt ACE if you already capture execution traces and want corrections to persist across sessions without fine-tuning, and if you accept that the Skillbook becomes another artifact to version alongside prompts. Do not adopt it if your agent is a single-turn call with no feedback signal, or if you cannot curate what gets written into the Skillbook. Before committing, run ace setup, confirm your provider is among the supported ones, and inspect the output of agent.get_strategies() after a few learn_from_feedback calls to see whether the extracted strategies are specific enough to be worth replaying.

Official sources

1. kayba-ai/agentic-context-engine on GitHub
2. License: Apache-2.0
3. Project website
4. README
5. Releases