AI Agent Memory: Why Saving Preferences Isn't Enough Without Indexing
This article explains why AI agents fail to recall user preferences across sessions despite saving them to files, detailing the critical role of an index file (MEMORY.md) for discovery, the two-step save-and-index process, failure modes when indexing fails, and verification techniques using unique content markers.
When you tell a coding agent to “explain constraints before trade-offs,” it saves that preference to a file and confirms it. Yet in a new session the agent starts from scratch again. The file exists, but the preference never appears in the response. The gap lies between what the application saves, what the new session loads, and what the model actually reads.
What Changes in the Next Request After a File Is Saved?
A language model only processes the context provided in the current request: system prompt, conversation history, and tool-returned content. A new file in the application directory does not automatically enter the model’s input, nor does writing the file modify model weights. In the current session the instruction may still be in the conversation history, so the agent appears to follow it. Only when a new session starts without that history does the application need to resupply the saved information.
The save function save_memory creates directories, composes a filename, writes the content, and returns the path — for example feedback_explanation.md containing “When explaining a solution, first state constraints, then give the rationale.” At this point the application has a durable artifact.
However, when a new session starts the main program calls load_memory_index, which reads MEMORY.md and passes its contents to the prompt builder. The builder adds usage instructions and the index, but does not automatically open every content file in the directory.
Therefore, verifying a successful save means checking the preference file; verifying that the new session received an entry point means inspecting the actual constructed prompt. If the former passes but the latter is missing, the investigation should focus on the index-loading path, not on tweaking the model prompt to “remember harder.”
Index Guides Discovery, Content Holds the Full Agreement
MEMORY.mdcan keep a line like:
- [feedback_explanation](feedback_explanation.md) — Explain constraints and trade-offs before presenting a solutionThe filename provides the read location; the description helps the model judge relevance to the current task. Only when this line enters the prompt does the model learn that a preference about explanation style is worth consulting before answering a deployment question.
If the model then requests feedback_explanation.md, the read tool returns the full content, and the model can apply it: list known constraints (intranet access, machine resources, ops capacity) before comparing options, and ask for missing critical conditions. Whether the preference is actually followed must still be checked against the real read and response.
Why not put all full texts into the startup prompt? With few records it’s manageable, but as files grow, not every deployment consultation needs past writing habits, test conventions, or project decisions. A short description first, then on-demand reading, keeps irrelevant details out of the context window.
This design has a cost: a vague description like “user preference” makes it hard for the model to decide when to open the file; a terse description like “constraints first” may omit the applicability scope noted in the full text. The index guides selection; the content preserves the complete agreement. Both must cooperate — a single catalog entry cannot replace the full text.
The same codebase also has load_memories, which scans content files (skipping MEMORY.md) and feeds the first 100 characters of each record into the memory extractor to help decide whether recent conversation produced new storable material. This serves memory consolidation, not the default loading at session start.
Consequently, an unindexed file may be discovered by the extractor scan yet remain outside the main session’s default discovery scope. A tool that knows the exact path can still read it. During debugging you must confirm which consumer lacks the material; finding the file in the directory does not prove the main session received it.
What State Remains Between Writing Content and Registering the Index?
The normal extraction flow saves the content first, then calls update_memory_index to register the index, and finally adds the memory name to the return list. Index updates replace an existing same-name entry or append a new one. Calling these two functions sequentially does not make the two file writes a single atomic commit.
In the project, the first preference (“constraints before trade-offs”) is already saved and indexed. Then a second preference (“verify evidence coverage before stating conclusions”) is saved. If the second content write succeeds but the index update throws an OSError, the disk ends up with a content file that never entered the default catalog.
A controlled test injects this failure: the extractor receives fixed second content, the content save uses the real function, but the index call throws OSError. Result: the second content file exists, the index still has only the first link; rebuilding the main session prompt shows no second entry, yet scanning content files finds both records.
This also shows why an error return cannot be taken as the definitive disk state. The exception bubbles from the extractor layer, which never returns the new memory name, but the content was already written. The background call layer catches the exception and logs a skipped extraction — the agent as a whole does not necessarily crash.
Observed States and Required Actions
Content exists, no index entry — Content file present, integrity to verify → Verify content and filename, then add index entry
Index entry exists, target file missing — Catalog retains a pointer → Locate file, correct or remove stale entry
Both content and entry exist — Save and registration both have results → Check if new session loads it, then check actual read
The test fault was injected before the index write, so the original index stayed intact. Real mid-write file failures require checking whether the index itself remains consistent; this test cannot generalize to all disk faults.
When Repairing, Preserve Existing Content First
Finding the second preference missing from the index, first open the saved file and verify content and filename. If the content is complete, just add the index entry; if incomplete, fix the content first. This preserves completed work and avoids re-extraction generating different content that could overwrite a correct record.
In the test, the verification script manually calls the index update function to add the link for the second content. Rebuilding the prompt then shows the second filename and description, but the unique content marker inside the file does not appear — consistent with design: re-registration restores the discovery entry, but the full text still requires an explicit read to enter context.
Following the link to open the file confirms it points to the just-saved second preference. Seeing only a new catalog line could miss a mistyped path or moved file; seeing only a tool-returned path does not prove that line was loaded into the next prompt.
There is also a timing gap: the index on disk is fixed, but an already-built system prompt may not refresh automatically. This implementation reads the index at prompt-build time (e.g., at startup), so a manual patch does not instantly update the current session. Re-verification must specify which prompt build is being inspected.
For automatic repair, a reconciliation process could scan existing content, compare with the index, identify missing descriptions and pointers, and backfill them. The existing content scanner provides the raw material, but that does not mean automatic compensation is already implemented; decisions on which files need registration and how to preserve human curation must also be made.
Ongoing maintenance revolves around the same correspondence. When a user changes a preference, both the content and the index description are checked; renaming or deleting a file requires handling the old link. For example, if the user later says “complex solutions need constraints first, simple Q&A can go straight to the answer,” keeping the old generic description could apply the preference too broadly. Even when both file and entry are found, you must still judge whether the record applies to the task at hand.
Verify the Exact Step by Inspecting Its Actual Input
Asking the agent “Did you remember?” cannot distinguish between using the current conversation and reading persistent memory. The earlier checks use a temporary directory and fixed content to separately observe files, index, built prompt, and read results, comparing these stages in isolation.
A useful technique: place a unique marker inside the memory content, but not in the filename or index description. When only the content is saved, the file contains the marker but the default prompt has no link. After index backfill, the prompt has the link but still no content marker. Only after an explicit read of the target file does the marker appear.
This prevents mistaking “the catalog line appeared” for “the full text was loaded.” The marker only traces how far the content traveled; its presence in the input does not prove the model understood and correctly applied the preference.
Fault diagnosis must examine both call results and saved results. In the second-step exception sample, the return failed but the second content file existed; after manual backfill, the link and target file matched again. Checking only whether a function errored, or only whether a file exists, would miss part of the state.
These checks use fixed responses in place of the extraction model to verify how the program passes materials and handles injected errors. To further validate whether preferences actually influence answers, you can ask a deployment question in a new session of the same project, inspect the index sent to the model, the content returned by the read tool, and the final answer’s structure. Only then can you distinguish missing entry, unread content, and read-but-not-used.
In an Interview, Connect One Save to One Use
Answering “How does an agent remember user preferences?” you can chain the process:
I would write long-lived preferences to persistent storage and explicitly define where a new session discovers them. In a file-based design, a concise index provides descriptions and paths, while full preferences stay in separate content files, read on demand via tools. Saving content and updating the index are two operations. If the second step fails, the first may have already succeeded, so recovery must verify files and index separately, preserve valid content, then add the missing entry. After repair, check the rebuilt prompt and actual read results. Once the record is readable, verify that the current task adopts the applicable preference. File existence, index visibility, and answer compliance each require their own evidence.
Signed-in readers can open the original source through BestHub's protected redirect.
This article has been distilled and summarized from source material, then republished for learning and reference. If you believe it infringes your rights, please contactand we will review it promptly.
How this landed with the community
Was this worth your time?
0 Comments
Thoughtful readers leave field notes, pushback, and hard-won operational detail here.
