Building an Episode-Based Context System for Coding Agents

Why a task is a useful memory unit

A raw chat transcript records everything in order, including exploratory dead ends, repeated logs and tool output that may no longer matter. A coding agent needs a more selective form of continuity. An episode can group one logical task: the user's goal, files observed, actions attempted, commands run, failures and the final outcome. This structure makes it possible to retrieve a relevant prior decision without replaying an entire conversation.

The episode must remain scoped to a project. Similar requests across different repositories can otherwise contaminate one another. It should also distinguish a successful change from an attempted or failed action. A memory system that stores only the agent's confident final summary can lose the very failure evidence needed to avoid repeating a mistake.

Capture observations and actions separately

During a task, a recorder can collect files read by tools, files changed by edits or commands, command exit codes and failure markers. Observations are not the same as mutations. Reading a path does not mean the agent changed it; attempting an edit does not mean it succeeded. Preserve that distinction in the episode record. The Licuse EpisodeRecorder code reflects this idea by tracking observed files, changed files, actions, commands and failure codes.

Bound stored strings and paths so memory remains manageable and does not become an unreviewable log dump. Do not store secrets merely because they appeared in terminal output. The useful historical fact may be 'the test failed with this code' rather than the entire raw output. Keep enough provenance that a later agent can verify the conclusion.

Retrieve candidates before hydrating content

A scalable memory system searches lightweight episode candidates first. It might use recency, full-text matches, task identity or exact file hints. Then a selector chooses a small number worth opening. Licuse's native EpisodeStore exposes candidate search and hydration as separate operations. Its context layer also validates the selected episode IDs and source paths before use. That reduces the chance of an unrelated task being promoted into the current prompt.

Selection should be conservative. A new task about 'login' may resemble an old one but involve a different service or branch. Show the source of retrieved history, or at least keep it distinguishable from current-code evidence. If no candidate is useful, proceed without history rather than forcing a weak match.

The context budget matters

Even relevant history competes with the user's present request, current files and tool schemas for model context. Hydrate only the chosen episodes and bound the amount of historical text. A short summary of an earlier decision plus affected paths may be more useful than a complete tool trace. When the task changes, the memory system should be able to choose different episodes rather than carrying the same history indefinitely.

This is not only a cost optimization. Excess history can bias the agent toward an old solution. If a previous attempt failed, that failure can be useful, but it must be labeled as a failed attempt. The model should not mistake 'we tried this' for 'this is the current design.'

Verify history against the present checkout

The most important rule is that memory points to evidence; it does not replace evidence. After retrieving an episode, open the current file and check its revision. Run the relevant test or inspect the current API contract. A past success may no longer hold after a refactor, and a past failure may have been fixed. An agent that blindly repeats an old patch can overwrite new work.

A good episode system should make it easy to ask: what task was this, which files were involved, what actually succeeded, and what remains uncertain now? That allows continuity without pretending that a stored conversation is a live view of the repository.

Evaluate the design with an adversarial follow-up

Create a first task in a test repository, complete it and record the outcome. Then change one of the affected files and start a related second task. Check whether the system retrieves the correct episode, notices the changed source and adapts. Also create a similarly worded task in another project and ensure cross-project history is not selected. Finally, test behavior when the native store is unavailable; the agent should continue from current evidence without claiming nonexistent memory.

The payoff of episode-based context is not a magical permanent memory. It is a disciplined way to recover relevant intent and file leads while keeping the present task in control. The final measure is a correct, reviewable patch with an honest explanation of what came from history and what was verified now.

Storage and deletion deserve a design

Task episodes can contain file paths, user requests and summaries of commands. Even when stored locally, they may reveal sensitive project structure. Define where the database lives, who can read it, how long it remains and what happens when a workspace is deleted or moved. A web account deletion cannot automatically wipe every local copy or system backup. Give users a way to understand and remove local history, and avoid recording secret values when a bounded failure code would suffice. The memory system should also fail honestly if its native component cannot load. Preserving continuity is valuable, but it should not quietly create a second uncontrolled archive of private development work across multiple projects, devices and backups over time.