Agent workflow · Updated July 22, 2026
Terminal coding agents need project memory before more generation
A coding agent can read the repository and still miss why a choice was made, which approach failed or which helper already passed review. Retrieval-first work restores that context before the next patch.
The repeated problem developers describe
A new session scans files, reconstructs conventions and produces a plausible solution. The code may compile while contradicting an earlier decision or reproducing a bug that another session already fixed.
More prompt context can postpone the problem, but it also fills the working window with information unrelated to the current task. Durable memory should be searched, not blindly attached.
Stable instructions
Security rules, repository boundaries and commands that apply to most tasks.
Decision memory
Why a library, schema or architecture path was accepted or rejected.
Implementation memory
Reviewed helpers, fixes, runbooks and the tests that prove them.
Session outcome
What changed, what failed and what the next agent should verify.
A retrieval-first terminal loop
- Read the small, stable repository instructions.
- Search memory with the task, framework and constraint.
- Preview likely decisions or patterns with source and review state.
- Retrieve only a strong, permitted match.
- Adapt the artifact to current names, paths and interfaces.
- Run repository tests and record the outcome or correction.
What belongs in AGENTS.md—and what does not
Keep compact, durable rules close to the repository: commands, protected paths, review requirements and constraints that apply repeatedly. Do not turn that file into a history of every incident, snippet and experiment.
Detailed implementation cards can stay outside the always-on prompt and appear only for relevant tasks. This preserves attention while keeping prior work discoverable.
When the agent should generate instead
Retrieval is not the objective. A weak or stale match can create more review work than a short new implementation. Generate normally when provenance is unclear, the framework differs, the artifact is revoked, no tests exist for a risky primitive or the current task is genuinely novel.
Record the miss. Repeated misses reveal which small helpers, recipes or test packs are worth reviewing for future reuse.
Give the next session the decision, not the whole conversation
Store compact rules, retrieve task-specific evidence and preserve a receipt for what the agent actually reused.
Frequently asked questions
Why does a terminal coding agent lose context?
The active session is not a durable record of every architecture decision, failed approach and reviewed implementation across the repository.
Is an AGENTS.md file enough?
It is useful for stable instructions, but detailed decisions, snippets, incidents and test evidence are better retrieved only when the current task needs them.
What should be stored as repo memory?
Store durable constraints, approved and rejected patterns, reusable implementations, tests, incidents and the provenance needed to review them.