AI agent memory across runs: a practical architecture
A skill gives an agent a procedure. Durable memory preserves what happened, what remains open, and what the agent learned after the current context disappears.
Short answer
A skill is the procedure. Memory is the state.
An AI skill and an AI memory solve different problems. A skill is a reusable procedure: it tells an agent when to act, which tools to call, and what sequence to follow. Memory is the state that survives after the run ends. For a long-running agent, useful memory must preserve at least three different things without blending them together: an ordered record of completed and open work, curated findings that remain useful later, and source material the agent can retrieve with evidence. The architecture matters because a single transcript, summary file, or vector index rarely handles all three jobs safely.
The memory stack
Five layers that should not collapse into one blob
The same storage engine can support several layers, but each layer needs a distinct contract.
Skill: the procedure
A skill describes behavior. It can tell an agent to recall state before working, write checkpoints after milestones, or cite evidence. The instructions can be installed repeatedly, but they do not contain the changing project state. Reinstalling the same skill tomorrow gives the agent the same procedure, not yesterday's decisions or unfinished work.
Session context: the current working set
Messages, tool results, temporary files, and an in-process plan help the agent complete the current run. They are valuable precisely because they are immediate and detailed. They are also volatile: compaction, a new process, a scheduled invocation, or a different agent can remove or hide them. Treat session context as working memory rather than the durable record.
Progress ledger: what happened and what is next
Operational continuity needs an ordered, append-oriented ledger. A useful entry records a status such as done, next, or blocked; a stable run identifier; related files or URLs; and an idempotency key so a retry does not create a second milestone. This is not semantic knowledge. Its main job is to let the next run resume without repeating or silently skipping work.
Durable findings: what the system now knows
A decision, correction, constraint, or verified fact may remain useful long after the task that produced it. Store that knowledge separately from progress noise and attach provenance. Stable topics can maintain one current note per subject while history preserves prior versions. Retrieval should return only relevant findings and the evidence needed to judge them.
RAG corpus: the source library
Retrieval-augmented generation is strongest when finding passages from manuals, policies, notes, and other source material. It can be part of an agent's memory, but retrieval alone does not define how agents write, order progress, resolve conflicting updates, reverse a bad write, or hand unfinished work to the next run. Those are lifecycle and governance decisions around the index.
Resumable loop
A practical write-and-recall protocol
Recall before acting
At the beginning of each run, query memory with the current goal. Load open next and blocked items, the recent ordered progress tail, and only the durable findings relevant to the goal. If the result is empty, the workflow can treat the run as its first invocation instead of guessing what happened previously.
Checkpoint meaningful progress
Write a progress entry after a meaningful milestone, not only at shutdown. Use a stable run ID and a deterministic idempotency key for each step. Mark completed work done, keep unresolved work next, and record blockers with the reason and supporting references. The next process should be able to reconstruct the operational state from these entries alone.
Promote only durable findings
Do not turn every intermediate thought into long-term memory. Promote a finding when it is a verified fact, a durable decision, an important correction, or a constraint future runs must respect. Give it a stable topic and source references. This keeps retrieval useful and makes later correction possible without searching through a transcript dump.
Retrieve with provenance
When memory influences an answer or action, carry the source label or record reference forward. Provenance lets a person or another agent distinguish a company document from a model-written note, inspect when the memory changed, and decide whether it is authoritative enough for the current task.
Leave a clean handoff
Before the run ends, append what was completed and one explicit next action. If a write is unavailable because of a quota or service boundary, stop cleanly and report that state rather than retrying indefinitely. A durable workflow should remain resumable even when the process is killed immediately after any completed milestone.
Choose deliberately
Which memory approach fits the workflow?
These approaches can be combined. The useful question is which responsibility each one owns.
| Approach | Best for | Across runs | Across agents | Semantic retrieval | Main tradeoff |
|---|---|---|---|---|---|
| Workspace memory file | Small, local projects with one primary agent | Yes, when the same filesystem remains available | Possible through a shared repository, with merge discipline | Usually manual or filename-based unless another index is added | Simple and inspectable, but coordination, scoping, and retrieval are your responsibility |
| Conversation or session store | Continuing one user's dialogue or one agent thread | Yes, within the session system's identity and retention rules | Usually limited to the session or application that owns it | Varies; often optimized for recent conversation history | Good continuity, but operational handoffs and source governance need separate design |
| RAG or vector index | Finding relevant passages in a source library | Yes, while the corpus and index are retained | Yes, if tenant and permission scopes are enforced | Core capability, often paired with keyword search or reranking | Excellent retrieval substrate; write semantics, ordered progress, and rollback are not automatic |
| Governed memory capsule | Long-running or multi-agent work that reads and writes shared state | Yes, independently of an individual model context | Yes, through scoped authenticated tools | Supports relevant recall alongside explicit progress records | Adds an external service and requires deliberate write, provenance, and cost policies |
Failure modes
What breaks after the demo works
The skill is mistaken for the memory
Symptom
Every run follows the right instructions but still asks what happened last time, repeats completed work, or has no reliable handoff.
Mitigation
Keep the skill as a stable procedure and connect it to a separate durable state store. Test restart behavior by ending one process and resuming from only persisted records.
Progress and knowledge are mixed together
Symptom
Semantic recall returns status chatter, while the activity history fills with repeated summaries and contradictory current-state notes.
Mitigation
Use an ordered ledger for milestones and open work, then a separate curated collection for durable findings. Define promotion rules for moving information into long-term memory.
Retries duplicate writes
Symptom
Network retries or at-least-once jobs append the same milestone multiple times, making the latest state ambiguous and inflating storage.
Mitigation
Assign a stable run identifier and deterministic idempotency key to each logical write. The write path should return the prior result when that key is seen again.
Model-written notes become authority
Symptom
An inferred or maliciously supplied statement is recalled later as if it came from an approved policy or verified source.
Mitigation
Record author, source, time, and write type. Keep model-authored memory distinguishable from source material, and require review before sensitive memories gain authoritative status.
Nothing can be corrected safely
Symptom
Updating a note destroys the prior state, while deleting a bad memory removes the evidence needed to understand what changed and why.
Mitigation
Use versions or append-only correction markers. Make the current view easy to retrieve while retaining enough history to audit and reverse a mistaken write.
Recall grows without a budget
Symptom
The agent loads an expanding transcript or every stored note at the start of each run, increasing latency and token cost while burying the current task.
Mitigation
Load open operational state directly and retrieve durable findings by goal. Set explicit result and token limits, then archive or summarize low-value history without erasing provenance.
Before production
Agent-memory readiness checklist
- 1
Define the memory scope—user, project, agent, tenant, or workflow—before choosing storage or retrieval technology.
- 2
Separate volatile session context, ordered operational progress, durable findings, and the source corpus into explicit record types.
- 3
Require recall at the start of every resumable run and define what an empty result means.
- 4
Make progress writes retry-safe with stable run IDs and deterministic idempotency keys.
- 5
Attach author, timestamp, source references, and write type so recalled information does not lose its authority boundary.
- 6
Define how corrections, superseded notes, compliance deletion, and rollback differ instead of exposing one destructive delete operation.
- 7
Test a real process restart, a failed write, a duplicated job, two concurrent agents, and a poisoned or untrusted memory input.
- 8
Set recall, storage, and write budgets so a successful long-running workflow cannot silently become an unbounded cost center.
- 9
Keep an exportable source record so the memory can be rebuilt independently of one embedding model or index provider.
Common architecture questions
Does installing an AI skill give the agent persistent memory?
No. A skill can instruct an agent to read and write memory, but the changing state must live somewhere that survives the current process or context. The skill is the procedure; the memory service, file, session store, or capsule is the durable state.
Is RAG the same as agent memory?
RAG is an important retrieval technique, especially for finding relevant source passages. Agent memory also needs write rules, state scopes, progress ordering, provenance, correction, and lifecycle controls. A RAG index can be one component of that larger memory architecture.
What should an agent remember between runs?
Persist unfinished work, verified decisions, durable constraints, important corrections, and the evidence needed to trust them. Avoid storing raw chain-of-thought, temporary guesses, secrets, or every intermediate message merely because storage is available.
Official references
These sources define the adjacent standards and platform concepts; they do not endorse Retenta.
- Agent Skills specificationAgent Skills
Defines the portable SKILL.md format and its instruction-oriented structure.
Official documentation for using sessions as a persistent memory layer across runs.
- Cloudflare Agent MemoryCloudflare
Official documentation for Cloudflare's durable memory service for agents.
Put the protocol to work
Related agent-memory skills
Retenta · Claude Code
Retenta Memory for Claude Code
An official Retenta skill and MCP connector that teaches multi-run Claude Code workflows to recall state, log progress, and preserve durable findings in a capsule.
Retenta · Codex
Retenta Memory for Codex
An official Retenta skill for giving scheduled and multi-run Codex workflows a durable memory spine through a Retenta MCP capsule.
From architecture to working memory
Give a long-running agent durable state with provenance and a clean handoff.
Create a Retenta capsule, connect it over MCP, and use the recall → progress → remember protocol across runs.