A coding agent can remember the architecture decision and still edit the wrong file because the repository changed ten minutes ago. That is the central problem in AI agent context management: continuity is useful, but only when durable knowledge stays separate from live evidence.
For developers running migrations, multi-file features, or debugging sessions that outgrow one conversation, the practical goal is not to load the whole repository. It is to keep a small context packet, retrieve the next piece of evidence when needed, and refresh anything the task may have changed.
The operating rule is simple:
- Persist decisions and stable constraints.
- Retrieve code and documentation just in time.
- Recheck mutable evidence after every meaningful change.
- Compact progress without turning assumptions into facts.
Separate Current Task Context From Persistent Memory
Agent working memory is the information available to the model during the current inference: instructions, messages, file excerpts, tool definitions, command results, and prior outputs. It is finite. Adding more tokens can make important details harder to retrieve, which is why Anthropic frames effective context as the smallest high-signal set that can produce the desired behavior.
Persistent project memory serves a different purpose. It can retain conventions, preferences, architectural decisions, and recurring warnings between tasks. A repository rule such as “all database writes go through the service layer” belongs there. The current definition of OrderService, the branch being edited, and whether a test passes do not.
Use three lifecycles instead of one catch-all memory bucket:
| Context layer | What belongs there | How to validate it |
|---|---|---|
| Persistent memory | Stable conventions, approved decisions, recurring constraints | Review its scope and owner |
| Task context | Goal, exclusions, acceptance criteria, current plan | Compare with the active request |
| Live evidence | Files, Git state, test output, generated artifacts | Read or run again |
Persistent memory is retrievable knowledge, not a guarantee that the code is current. It also does not mean the underlying model was retrained on the project. Treat the repository and its executable checks as the source of current truth.
Build a Context Packet for One Code Change
A context packet is a compact index for one reviewable change. It tells the coding agent what must remain stable, where to look next, and what result will count as done. Copy this checklist into a task and replace the brackets:
## Goal
[One observable behavior to add, remove, or repair]
## Scope
- Repository/workspace: [path or project]
- In scope: [modules, interfaces, tests]
- Out of scope: [migration, deployment, adjacent refactor]
## Constraints
- Project rules: [AGENTS.md or equivalent]
- Architecture decision: [link/path + status]
- Permissions: [allowed tools, files, environments]
## Current evidence
- Relevant files: [paths]
- Starting revision: [branch + commit or clean-state note]
- Reproduction: [command + observed result]
## Acceptance
- Behavior: [specific result]
- Verification: [tests/checks]
- Human decision: [merge, schema, security, or release owner]
## Progress record
- Decisions made: [decision + reason + owner]
- Files changed: [paths]
- Checks run: [command + result]
- Open questions: [question + blocked work]
- Next retrieval: [file, diff, log, or test to inspect]Capture the Goal, Constraints, and Relevant Files
Start with the behavioral change, not a request to “improve the module.” Name exclusions because they protect the task from plausible expansion. A bug fix that excludes schema changes and production deployment is easier to review than a broad instruction whose permission boundary exists only in the agent’s interpretation.
Then point to stable project instructions. An AGENTS.md file can hold repository-specific commands, architecture rules, naming conventions, and review expectations. Keep it operational. Long explanations and historical debates belong in linked documents that the agent can retrieve when the current change actually reaches them.
Relevant files are starting points, not a frozen manifest. Include the files that establish the current interface and tests, then allow targeted exploration when imports, call sites, or failures reveal another dependency.
Retrieve Evidence Instead of Loading Everything
Repository-scale context retrieval should work like an index. Keep paths, symbols, issue IDs, and commands in the packet; open the underlying material only when the next decision depends on it. Targeted search, a narrow file excerpt, or one test failure usually carries more useful signal than an entire directory.
This avoids two opposite failures. Loading everything consumes the attention budget before implementation begins. Loading only the initial brief leaves the agent guessing about code it has not inspected. Just-in-time retrieval keeps the search accountable: every additional file should answer a current question.
Keep Context Useful During a Long Task
Long-running code work does not need perfect recall. It needs recoverable decisions and fresh evidence. Context compaction, repository refreshes, and bounded delegation each solve a different failure mode.
Preserve Decisions When Summarizing Progress
Compaction should remove bulky transcripts while preserving the task’s control surface. Keep the accepted goal, exclusions, decisions and owners, unresolved questions, changed files, current revision, failed checks, and the next verification step. Drop repeated explanations, obsolete plans, and raw command output that can be reproduced.
A useful summary distinguishes fact from intention:
- “
pnpm test authpassed at commitabc123” is recorded evidence. - “Run the integration suite after merging the fixture change” is a pending action.
- “The timeout probably comes from the cache” is a hypothesis until a trace supports it.
Over-aggressive compaction is dangerous because it can preserve a conclusion while deleting the condition that made the conclusion valid. Record the evidence pointer with the decision, not just the decision sentence.
Refresh Repository Evidence After Changes
Any action that changes the working tree can invalidate earlier context. After an edit, merge, generated migration, dependency install, or another agent’s handoff, refresh the affected evidence:
- Inspect the current diff and repository status.
- Reopen files whose interfaces or imports may have changed.
- Rerun the narrowest relevant check.
- Update the context packet with the current revision/HEAD, working-tree status, and result. If a new commit was created, record the new revision.
- Mark skipped or unavailable checks explicitly.
Do not let an old file excerpt outrank the current file. The same rule applies to external systems: retrieve the current issue, API schema, or deployment state before using it as a release decision.
Return Focused Results From Subagents
Subagents are useful when a focused investigation would flood the main coding agent context. Give each one a bounded question, permitted sources, and an output contract. A security reviewer might return findings with file and line evidence; a dependency investigator might return the call path, affected tests, and unresolved uncertainty.
The main agent needs results, not a second transcript. Verdent’s current configuration guidance uses this same boundary: subagents run in separate contexts and only their results return to the main context. Require the result to include evidence pointers and confidence limits, because a concise unsupported answer is merely harder to audit.
Applying Context Management in Verdent
Verdent offers several layers that should remain distinct. Manager can retain project choices, conventions, and past decisions across tasks. Use that long-term memory for stable working preferences, then use project rules for repository-wide instructions and explicit file references for the current implementation.
For a long code change, begin with the context packet as the task boundary. Reference only the files needed to establish the starting state, use Plan Mode when the repository or approach is unfamiliar, and delegate narrow retrieval or verification work. At a feature or module boundary, start a fresh session with the compacted packet and reread the current repository evidence.
This layering matters because Verdent’s context window is shared by instructions, files, conversation messages, and responses. Saved memory can reduce repeated explanation; it cannot make stale code current or turn an unrun test into evidence.
FAQ
Can a Verdent Manager's saved memory be edited?
Yes. Open the Manager’s configuration and adjust its Memory and style settings. Verdent says changes there affect only that Manager, so review the memory’s wording and scope before relying on it for a project.
Does duplicating a Manager copy its existing memory?
Yes. Duplicating a Manager uses its memory and setup as the starting point. The duplicate becomes independent afterward, so later changes to one Manager do not update the other.
Can Manager import earlier conversation history?
Yes. The current Manager page says it can import a selected period from the last 7 days through 6 months. Treat that import as source material for memory, then review the resulting preferences and decisions; an old conversation may describe code or policy that has since changed.
Does prompt caching preserve project decisions between sessions?
No. Prompt caching can reduce the cost or latency of processing an unchanged input prefix, but it is not durable project memory. For example, Claude prompt caching retains reusable cache representations for a limited TTL; it does not guarantee that a future session receives a project decision. Persist the decision in Manager memory or a repository-owned rule, then retrieve it into the new task.
Can switching models change the usable context budget?
Yes. Models and providers can expose different context limits, while system instructions, tool definitions, files, prior messages, and reserved output all consume part of the usable budget. Recheck the selected provider’s current model documentation and the context indicator in Verdent after switching; do not carry a previous model’s budget forward as an assumption.
Keep Durable Knowledge Separate From Live Evidence
Good AI agent context management does not attempt to remember every token. It preserves the decisions that should survive, keeps the task boundary visible, and retrieves mutable facts from their source when they matter.
For the next long-running code task, create the packet before implementation. After each meaningful change, refresh the diff, affected files, and checks. When the session becomes crowded, compact around decisions and evidence pointers. That gives a coding agent continuity without asking memory to impersonate the repository.
