Imagine asking a research agent when a fictional API raised its batch limit from 100 to 250 items. The agent finds an older manual and a newer release note. After dozens of tool calls, can it still explain which limit applied in April, which applies today, and where each number came from? Can it do that after the run is interrupted and resumed?
That example calls for four kinds of memory. The agent needs a working memory for the next decision, an episodic memory of what it tried, a semantic memory of what the evidence supports, and a procedural memory for how to check it. Start with a project directory and make each kind of memory responsible for a different job.
Four kinds of agent memory
The CoALA framework separates working memory from three kinds of long-term memory. For a research agent, the distinction determines what to save, when to load it, and how to update it. Cognitive Architectures for Language Agents
| Kind | What it holds | When to load it | Update rule |
|---|---|---|---|
| Working | Current question, user constraints, next step, recent results, relevant evidence excerpts | Every model call | Rebuild a bounded view for the next decision. Keep user constraints outside the rolling summary. |
| Episodic | Queries run, pages visited, failed attempts, and decision outcomes | When resuming or revisiting a line of inquiry | Append events. Retain or expire routine traces according to project policy. |
| Semantic | Claims about the world, with evidence, scope, and dates | When a finding informs the next step or the report | Keep revisions and record which claims they supersede. Preserve unresolved conflicts. |
| Procedural | Search playbooks, source-ranking rules, verification steps, and scripts | When the task calls for that procedure | Version shared procedures and review changes before adopting them. |
Two pieces of infrastructure support these patterns. A checkpoint captures enough execution state to resume a particular run, including where it stopped and the references it already wrote. A source registry records what evidence was captured and points to its stored snapshot. Source snapshots can support several claims and survive the pruning of routine search traces. LangGraph makes a related distinction between thread-scoped checkpoints and application-managed stores that can serve multiple threads. LangGraph persistence documentation
How evidence moves through the system
The diagram follows one search result. The agent stores the full source before sending a short excerpt to the model. Once a finding has been checked against the source, the claim carries a reference back to that exact snapshot and passage.
flowchart TD
accTitle: How a research agent stores and recalls evidence
accDescr: At startup the agent restores checkpoint state and loads a playbook. It saves each tool result as a source snapshot and passes an excerpt to working memory. Verified claims cite the snapshot and can be recalled in later runs.
Start["Start or resume research"] --> Load["Load plan, checkpoint,<br/>and playbook"]
Load --> Search["Search or fetch a source"]
Search --> Store["Save snapshot and source ID"]
Store --> Context["Put excerpt and ID<br/>in working memory"]
Context --> Check["Check a claim<br/>against the source"]
Check --> Claim["Save verified claim<br/>with evidence and dates"]
Claim -. "Recall in later runs" .-> Context
1. Keep the working context small and recoverable
Build each request from a stable prefix, a compact record of progress, recent tool exchanges, and the evidence needed for the next decision. Keep system instructions and tool definitions stable so providers can reuse the matching prompt prefix. Keep timestamps and other changing metadata later in the request. The execution log can remain append-only while the prompt is rebuilt from a bounded selection of it. When you edit earlier context during compaction, expect prefix reuse to stop at the first changed token. Manus context engineering notes
Give tools a way to return short excerpts and fetch more by ID, page, or line range. A result such as src-014, lines 42–46 lets the agent load the relevant passage when it needs it. This keeps competing snippets out of the prompt and gives the agent a way to revisit its evidence. Chroma's long-context experiments found that longer inputs and similar distractors can make retrieval less reliable even when the answer is still present. Chroma's Context Rot study
When the prompt grows too large, apply two steps in order.
- Mask old observations. Save the full result before replacing it in the prompt with a stable snapshot ID and a brief description. Keep recent results and useful errors, and preserve each tool call with its matching response in the prompt representation. Lindenbauer and colleagues found that masking older results was competitive with summarization in their software-engineering agent experiments. Validate the trade-off on your own research traces. The Complexity Trap
- Summarize the newly evicted turns. Update the existing research summary with the latest findings and source IDs, failed paths, unresolved conflicts, and next actions. Keep the original question and user constraints in a separate record and reload them on resume. Add this step when masking alone leaves too much history in the prompt. Anthropic's context engineering guide
2. Start with files and make resume explicit
A small project can start with this layout. Keep the workspace scoped to the project and apply access controls to both stored artifacts and retrieval.
research/
plan.md # Objective, user constraints, and open questions
checkpoint.json # Last completed step and pending work
events.jsonl # Queries, failures, and outcomes
sources.jsonl # Source IDs, URLs, retrieval times, and snapshot paths
artifacts/src-014.txt # Captured source with stable passage locations
claims.jsonl # Findings and revisions linked to source passages
playbooks/source-review.md # Versioned instructions for checking sources
Save the plan before the first tool call. When a result arrives, save the artifact, register its ID, then advance the checkpoint. On restart, resume from the last completed step and make source registration idempotent so retrying a step can reuse its saved artifact. Give each changed capture a distinct snapshot ID, even if the URL stays the same. An evidence reference should resolve to the text seen during that run.
Load playbooks/source-review.md when the agent starts checking sources, and record the playbook version in the checkpoint so a resumed run can use the same procedure. If several event logs show that the live manual omits older limits, review that pattern and add an archived-manual lookup to the playbook. Future runs can reuse the procedure without loading the old search histories.
3. Give claims evidence and a validity period
In the fictional API example, the release note says the new limit took effect on May 1, and the agent retrieves it on May 3. A claim record can capture both dates and point directly to the passage it used.
{
"id": "claim-002",
"subject": "API batch size limit",
"value": 250,
"unit": "items per request",
"valid_from": "2026-05-01",
"recorded_at": "2026-05-03T09:30:00Z",
"supersedes": "claim-001",
"evidence": [{ "source_id": "src-014", "lines": [42, 46] }]
}
Record that the previous 100-item limit ended on May 1 while retaining its original claim and evidence. This gives you two different answers to two questions. The limit in effect on May 2 was 250 items. As of May 2, the agent's records still showed 100 items. If the effective date is unknown, store it as unknown and send the discrepancy back to the research plan. The same distinction between effective time and recorded time underlies bi-temporal systems such as Graphiti. Zep's temporal knowledge graph paper
For a report, have the model return findings with source IDs and passage locations. Application code can reject unknown references and render citation links consistently. Then verify that each cited passage supports the specific value, date, and scope in the finding. A valid link can still point to a document that describes a different API version or plan. Keep those disagreements visible until the evidence resolves them.
4. Add parallel workers or a search index when the workload calls for it
When a question splits into independent branches, give each worker its own context. One worker can trace release notes while another checks archived manuals. Give each an explicit scope and ask for findings, contradictions, and source IDs. Workers can save artifacts under separate run paths and pass their findings to the lead for registration and verification. That keeps exploratory tool output out of the synthesis prompt and gives one process responsibility for merging claims. Anthropic's multi-agent research system reports gains on parallelizable research alongside higher token use, so measure the benefit against the cost of doing the same job with one agent. Anthropic's multi-agent research system
Choose a storage upgrade based on what your evaluations show.
| What is breaking? | What to add |
|---|---|
| Interruptions lose progress across processes or sessions. | A durable, thread-scoped checkpointer with explicit resume semantics. |
| Relevant passages are slow to find or missed because wording differs. | Hybrid keyword and semantic retrieval. Index extracted facts alongside the original text and return the original passage for verification. |
| Queries repeatedly cross related entities and ask what was true or known at a particular time. | Explicit temporal records and indexes. Consider a bi-temporal graph if relationship traversal becomes a recurring need. |
LongMemEval found that adding extracted facts to search keys can improve recall while keeping the original text available. Its tasks come from user–assistant conversations, so use it as a design clue and test retrieval on your own research sources. LongMemEval
Test what the agent can recover
Force a small context budget and bury the April limit in an early tool result. After masking and compaction, ask for the historical number and require the exact source passage. Interrupt another run between saving an artifact and advancing the checkpoint, then check that resume preserves the source reference without registering it twice. Finally, feed the agent a newer but less authoritative source that conflicts with the release note and check whether it exposes the discrepancy.
Track recovery accuracy, citation support, repeated fetches, and total tokens per completed report. If the agent can recover the evidence, explain when the claim held, and resume without losing its place, the file-backed design is already doing its job.
