Agent Long-Term Memory: Writing During Execution, Consolidating and Correcting Offline

1. What Agent Memory Is

Agent memory refers to content that an agent distills from past experience, keeps across sessions, and makes available to later tasks. To decide whether a mechanism counts as memory, check three conditions: whether the content still exists after the session ends, whether later sessions can retrieve or load it, and whether it is stored in a readable form.

Three mechanisms do not count as memory. The first is modifying model weights, which is training. The second is temporary state within a single session, which disappears when the session ends. The third is compressing older conversation into a summary when the context nears its limit. This only lets the current session continue. The summary does not automatically carry over into later sessions.

Distinguishing these concepts matters in practice. If an engineering team mistakes temporary state for long-term memory, the system will appear to have amnesia in new sessions. If it treats compression summaries as long-term memory, it will accumulate large amounts of content unrelated to current tasks.

2. The Core Difficulty: What to Remember

While executing a task, an agent does not know which information will be useful later. A seemingly trivial observation may become a key piece of evidence thirty turns of conversation later. This puts memory writing in a dilemma. If the system stores too little, there is nothing to check against in the future. If it stores too much, storage grows and retrieval gets noisier.

In practice, three failure modes are common:

1. Over-recording: Creating a separate entry for every object and every operation. The memory store eventually grows far beyond its useful content, and retrieval results are buried under many irrelevant entries.
2. Recording observable state: Writing information that can be read directly from the environment at any time, such as account balances, current positions, or values shown on a user interface. This information changes every turn, so storing it takes up space and goes stale quickly.
3. Locking in errors: Writing a wrong conclusion that every later session then follows. The mistake repeats and grows.

These three failures show that the value of a memory system lies in trade-offs. The bar for writing matters more than storage capacity.

3. A Four-Layer Memory Structure

A maintainable memory system is usually organized into four layers, each distilled from the layer below it:

• Raw record layer: Keeps complete session logs and supports search. This layer is not processed, and it is the factual basis for all judgments.
• Note layer: Entries the agent actively writes during execution. Their content consists of conclusions, rules, or verified facts.
• Structure layer: Groups notes by topic and builds linked indexes or knowledge pages, making it easier to find information by subject.
• Resident layer: A small amount of content loaded automatically at the start of every new session, typically including the current goal, long-term rules, and user preferences. This layer must stay lean, because it occupies context space in every session.

Data flows upward. Content in higher layers must trace back to its evidence in lower layers, or it cannot be verified. The raw records at the bottom are the only reliable source for correction.

4. Writing During Execution: Write Rules

Writes during execution should follow explicit rules. Those rules should be written into the resident layer so the agent reads them in every session. The following criteria can serve as a reference:

• State that can be read directly from the current environment is not written to memory.
• Patterns that require reasoning or induction to obtain are written first.
• Practices verified in real use are more valuable than unverified guesses.
• Each note expresses only one conclusion and cites its source, so it can be checked later.

Take a multi-step interactive task as an example. During the task, the agent repeatedly encounters different states, but the content worth keeping is an experiential rule, such as “after the same operation fails three times in a row, retry with a different operation pace.” This rule does not describe a specific interface at one moment, yet it can guide all similar situations afterward. By comparison, an observation like “on the third attempt, the button was in the upper left corner” has little value and goes stale easily.

Writes should also be limited in volume. The note layer can have a capacity limit and an eviction policy. For example, the system can prioritize removing entries that have not been used for a long time and that have been corrected or marked as expired.

5. Offline Consolidation: Replay, Verification, and Correction

Writing only during execution does not tell the system which notes are actually valid. During execution, the agent cannot see later results. A separate background process is therefore needed to review the raw records after the session ends, then verify and organize them. This process resembles how people replay and consolidate the day’s experiences during sleep.

The consolidation process usually includes the following steps:

1. Trigger: Runs automatically when a session ends, or in batches on a fixed schedule.
2. Read back: Reads the raw records of the session and compares them with existing notes.
3. Correct: When a note contradicts the original evidence, revises it to match the evidence. When a note has no supporting evidence in the original records, marks it for review.
4. Merge and split: Combines entries with duplicate content, and splits files that have become too large.
5. Distill: Summarizes verified patterns from the raw records and writes them into the note layer or structure layer.
6. Update indexes: Rebuilds indexes and resident-layer content so new sessions load correctly.
7. Log changes: Records the changes made in each consolidation run for auditing and rollback.

The sample code below shows the core logic of this process. The function names are for illustration only and do not correspond to any specific interface.

function consolidate(session_log, memory_store):
    for note in memory_store.recent_notes():
        evidence = session_log.find_evidence(note)
        if evidence is None:
            memory_store.mark_stale(note)
        elif evidence.contradicts(note):
            memory_store.revise(note, evidence.correct_version())
    for pattern in extract_verified_patterns(session_log):
        if not memory_store.contains(pattern):
            memory_store.add(pattern, layer="structured")
    memory_store.rebuild_index()
    memory_store.write_changelog()

The value of correction is straightforward. A wrongly recorded lesson makes the agent repeat the same detour in later sessions. Once the note is corrected, performance on the same scenario improves noticeably. Without offline consolidation, incorrect notes persist until someone cleans them up manually.

6. How to Evaluate a Memory System

Memory system effectiveness should be measured with controlled experiments. One feasible method is to design a set of independent tasks, each executed in a fresh session where the only information carried over is the memory directory. Then compare the results with memory and without memory.

Focus on the following metrics:

• Task success rate: The proportion of tasks completed.
• Step efficiency: The number of steps used to complete a task, and how many of those steps go to reading and writing memory rather than advancing the task.
• Memory size: The total number of notes and total characters, used to monitor growth trends.
• Useful entry ratio: The share of entries that are actually referenced in later tasks and help complete them.
• Change frequency: The number of entries added, modified, or deleted during consolidation. A consistently high change frequency usually indicates that the write rules are not clear enough.

Pay particular attention to one failure mode: the agent spends many steps organizing memory files without advancing the task itself. When this happens, tighten the write rules and limit the memory-operation budget per session.

7. Practical Recommendations

When deploying in a real system, consider the following points:

• Make rules explicit: Write the write criteria, directory structure, and consolidation rules into the resident layer, so the agent’s behavior is predictable and reviewable.
• Storage choices: Raw records can go into general-purpose object storage or a database with sufficient search capability. The note layer is small and suits file or key-value storage.
• Task scheduling: Consolidation jobs can be triggered by a message queue or a scheduler, decoupled from the main flow so they do not block user requests.
• Logging and monitoring: Record each consolidation run’s input, changes, and duration. Set alerts for unusual changes, such as deleting a large number of entries at once.
• Security and privacy: The memory store may contain sensitive user information. Apply redaction, restrict access, and set retention periods with automatic deletion when they expire.
• Rollback: Save a snapshot before each consolidation. If a correction goes wrong, the system can quickly restore the state from before consolidation.

8. Summary

The key to agent memory is handling it in stages. During execution, keep writes restrained and record only verified conclusions and rules. After a session ends, a separate process reads back the raw records to correct, merge, and update the index. A layered structure ensures that every memory can be traced to its evidence, and evaluation metrics test whether memory actually improves task performance. A system built on this approach can accumulate experience and correct mistakes in time.