Repo: https://github.com/voku/agent-loop
Demo: https://voku.github.io/agent_loop_demo/
Coding agents repeat mistakes.
The obvious response is to give them more memory:
MEMORY.md
project-rules.md
agent-notes.md
lessons-learned.md
MEMORY_FINAL.md
Soon the agent receives old decisions, temporary workarounds, copied transcripts, abandoned ideas, and rules nobody remembers approving.
It has more context.
It does not necessarily have better context.
At some point, memory becomes landfill.
The problem is not that coding agents forget too much. The problem is that most workflows fail to distinguish between temporary context, evidence, proposed learning, and approved project guidance.
A transcript is not memory.
A note is not a rule.
A finding is not guidance.
And a successful patch is not automatically a project convention.
Instead of giving the agent one growing pile of context, I built voku/agent-loop
around a governed workflow:
task
-> approved plan
-> selective recall
-> implementation
-> verification
-> recorded evidence
-> reviewed learning
A coding agent should not begin by reading a ticket and creatively filling in everything the ticket forgot to mention.
It should begin with an explicit work brief:
For example:
vendor/bin/agent-loop workflow plan PROJECT-123 \
--by lars \
--learning-root infra/doc/agent-learning \
--file src/Order/OrderService.php \
--file tests/Order/OrderServiceTest.php \
--goal "Reject invalid order state transitions" \
--scope "Order state validation and its tests" \
--non-goal "Do not redesign the order aggregate" \
--validate "composer phpstan" \
--validate "composer test"
A human then approves that specific revision:
vendor/bin/agent-loop workflow approve PROJECT-123 --by lars
When the plan changes, the old revision becomes superseded
, and the new one requires approval again.
That sounds slightly bureaucratic until an agent performs a technically impressive refactoring nobody requested.
Approval should apply to a concrete plan, not permanently to a task ID whose meaning can silently change.
The agent usually needs two different kinds of context:
agent-recall-compiler
selects task-specific guidance.
agent-map
provides compact information about the relevant code.
These are separate because they answer separate questions:
Recall:
- Which rules apply?
- Which previous decisions matter?
- What must be validated?
Map:
- Where is this class defined?
- Which methods and dependencies are relevant?
- What is the smallest useful code neighbourhood?
The goal is not to compress the entire repository into the prompt.
The goal is to avoid most of it.
Dumping a complete AST or months of transcripts into the context window is not understanding. It is bulk data transport with unusually confident autocomplete.
During implementation, the agent may need to track:
That belongs in a task session.
It should be inspectable, closable, and removable.
Temporary observations should not silently become permanent project knowledge. A workaround that was useful for one task can become actively misleading after the code changes.
A useful system therefore has at least three levels:
session state temporary
finding evidence to review
guidance approved durable knowledge
Collapsing those levels into one memory file removes the provenance that makes information trustworthy.
An agent saying “done” is not evidence.
The work brief already contains the expected validation commands. The loop can verify that the task state, recall output, sessions, files, and repository checks agree.
For example:
vendor/bin/agent-loop verify PROJECT-123
The result should be based on repository-specific checks such as:
composer phpstan
composer test
composer cs
The exact commands matter less than the rule:
Validation must be declared before implementation, not invented afterwards to match whatever changed.
A passing test suite also does not prove that the agent stayed inside scope. That is why workflow verification and code validation are related but separate concerns.
Recall can select a rule for a task, but selection alone proves nothing.
The guidance may have been:
HELPFUL
IRRELEVANT
HARMFUL
NOT_USED
UNKNOWN
NOT_USED
is particularly important.
A guidance item may be selected for an audit or investigation but never actually consulted. Without that outcome, selection statistics quietly become usage statistics, and the metrics begin describing a workflow that never happened.
The distinction is simple:
selection = the system supplied it
usage = the agent consulted it
outcome = whether it helped
Recording those separately gives us evidence for improving recall instead of merely counting how often a file appeared in a generated prompt.
After the task, the agent may record findings.
A finding is evidence, not a new rule.
It can become a proposal with actions such as:
ADD
REPLACE
DELETE
REJECT
NO_DURABLE_LEARNING
A human reviews the proposal before durable guidance changes.
Most tasks should probably end with:
NO_DURABLE_LEARNING
Fixing one bug does not necessarily reveal a reusable project rule. Sometimes the correct lesson is simply that the bug was fixed.
That conclusion has its own terminal state:
ACKNOWLEDGED
It is neither approved as a guidance change nor rejected as incorrect. It records that the task was reviewed and no durable change was needed.
This may seem like excessive precision for one status name. It is not.
When lifecycle states use the wrong verbs, audit trails gradually stop saying what actually happened.
The approach became more credible when we used it to audit agent-learning
itself.
The audit found three real defects:
NO_DURABLE_LEARNING
had no semantically correct terminal transition.The fixes shipped in versions 0.8.2
, 0.8.3
, and 0.8.4
.
None required a new agent architecture.
They required:
That is what real dogfooding usually finds.
Not a revolutionary new autonomous platform. A missing state, an inconsistent helper call, and a silent continue
.
Software remains software, even after somebody adds the word “agentic” to the README.
agent-loop
actually does
voku/agent-loop
is a PHP 8.3 CLI that coordinates several focused packages:
agent-kanban work and task state
agent-session temporary working memory
agent-recall-compiler selective project guidance
agent-map compact code intelligence
agent-learning governed durable learning
agent-loop orchestration
It does not replace maintainers, code review, static analysis, tests, or domain knowledge.
It gives those existing engineering practices an explicit workflow around coding agents.
A typical task looks roughly like this:
vendor/bin/agent-loop board card show PROJECT-123
vendor/bin/agent-loop workflow plan PROJECT-123 ...
vendor/bin/agent-loop workflow approve PROJECT-123 --by lars
vendor/bin/agent-loop verify PROJECT-123
The important part is not the CLI syntax.
The important part is that every transition is visible:
What was requested?
What was approved?
Which context was selected?
What changed?
How was it verified?
What evidence remains?
Did anything deserve to become durable guidance?
Coding agents do not need to remember everything.
They need:
More memory hides bad context management.
A governed loop exposes it.
And once the workflow can reject stale approvals, irrelevant guidance, unsupported claims, and accidental “lessons,” the agent does not need to behave like it remembers the entire repository.
It only needs enough verified context to complete one controlled task.