An AI agent does not remember your project the way a colleague does. It sees a fixed amount of text at a time, called the context window, and everything outside it is invisible. Most surprising agent behaviour traces back to that boundary: a rule from ten messages ago is forgotten, a file it read earlier has scrolled out, or an old assumption persists after the code has changed.
What goes into the window
The window holds the instructions, the conversation so far, the files the agent has read, the output of its tool calls, and its own replies. Long logs, large files, and verbose tool output fill it quickly. When it fills, older content is dropped or summarised, and the agent continues without it.
Symptoms
- The agent forgets a constraint you stated early in the session.
- It repeats a mistake it already fixed.
- It reads a file, then edits code as if the file still said what it said earlier.
- It gives a confident answer that contradicts something it read earlier.
Each of these is a sign that the important information is no longer in view.
Managing the window
Keep instructions short and specific. A long preamble competes with the task for space.
Give only the relevant files. Point the agent at the files it needs, not the whole repository.
Bound tool output. Ask for the last 200 log lines, not the whole log. A tool that returns bounded results is easier for an agent to use.
Start a new session for a new task. Carrying a finished task forward costs space and invites confusion.
Restate the key constraints when the work changes direction.
Durable memory
Some information should outlast a session. Store it outside the conversation, where the agent can read it again:
- a project instructions file, such as
AGENTS.mdor a similar file your agent reads at the start, - a plan file that lists the goal, the decisions, and what is left,
- a short notes file for conventions the team has agreed on.
Keep these files current. Stale memory is worse than none, because the agent treats it as true.
Tools as memory
An agent can also look things up when it needs them. A documentation server, a repository search, or a tool that reports the current state of a running system gives it fresh facts instead of recalled ones. The agent asks for what it needs at the moment it needs it.
TDK CLI is one example. Its MCP server lets an agent ask for the stack's status and recent logs directly, so the agent works from the live state rather than from what it remembers about the stack.
Summary
Context windows are finite, and anything outside them is invisible to the agent. Keep instructions short, bound the output of tools, start fresh sessions for new work, and store durable facts in files the agent reads. Prefer fresh lookups over remembered facts whenever the facts can change.
Top comments (0)