Agent Memory: Retention, Revision and Expiry
An AI assistant working on a project needs both the current request and relevant background. Keeping every past message in the prompt is not the only way to supply that background. You can save useful information outside the conversation, retrieve it when needed, and check it against the current task.
Memory is retained information, such as a decision note or research summary. Retrieval selects material from stored files or an index. The context window is the information available to the model for its current response. Saving a note does not mean the model has read it, and retrieving one does not mean the note is correct.
A Memory Has a Lifecycle
A conversation summary is a candidate record, not an established fact. Before retaining it, identify what future question it answers, where the evidence lives, and whether it describes an observation, a decision or a hypothesis. Keep source material separate from conclusions derived from it.
Suppose a note says a parser assumes UTF-8, but the current input contract now permits another encoding. The old note explains a past implementation; it must not override the current contract. Record which decision replaced it and retrieve the current specification during the next task.
Writing a memory is a separate action from retrieving it. Choose what merits retention and who may update it; do not let a model turn every confident sentence into a project rule. The retrieval pipeline covers finding records, while context engineering covers selecting evidence for the current request.
Match the tool to the question
Basic Memory lets people and assistants read, write, search, and connect Markdown notes. It can preserve the reasoning behind a project decision, but is not a built-in authority or approval system. The Basic Memory guide covers notes, relations, and client access.
QMD searches document collections with keyword, vector, and hybrid retrieval. It can help find an earlier explanation of research-versus-production isolation or an offline synchronization design. The QMD guide shows collection setup and how to read retrieved documents.
zvec-grep combines exact search, ranked keyword search, and semantic discovery over workspace files. Its source locations help you find code or document sections to inspect. The zvec-grep guide covers indexing and scoped queries.
These roles overlap. A small project may need only a decision file and ordinary text search. A larger note collection may benefit from semantic retrieval. Choose based on the material and question rather than imposing a fixed hierarchy or requiring all three tools. Knowing the exact filename or symbol is a good reason to open it or search for it directly.
A worked example: fix fee allocation
Suppose the request is to fix how slippage and commission are allocated in a backtest, using test data only.
- Establish the current scope. Start with the request and applicable project instructions. If an earlier decision affects the fix, retrieve its note and check its date, author, and status. A note saying “keep this as a command-line script” may explain the design; it does not grant permission to change production accounts.
- Locate the implementation. Search a known function name directly. If the name is unknown, a semantic query such as “slippage allocation fee matching” can suggest entry points. The setup and CLI examples are in the workspace-search guide.
- Read enough to understand the change. Inspect the matching function, its callers, data types, and relevant tests. Broaden the reading if the result omits important context. There is no generally safe line count or token budget that replaces this judgment.
- Change and verify. Apply the bounded fix and run the relevant tests. A search score verifies neither the calculation nor the absence of regressions.
- Save only useful new knowledge. If the work produces a lasting decision, record its rationale and sources through the project's agreed write process. A routine patch need not produce a new memory note.
The same approach helps with documentation: look for existing coverage before creating a new page, inspect the closest matches, and update or link them when appropriate. Search can reduce duplication; no result set proves that all equivalents have been found.
Keep evidence separate from instructions
A retrieved note may contain an accepted decision, a tentative proposal, a quotation, or obsolete guidance. Keep these distinctions visible. Dates, source links, and an explicit indication that a decision was replaced are more useful than treating everything in a “memory” folder as settled truth.
Current permissions and applicable instructions govern actions. Stored text is context to evaluate, not an automatic override. If a remembered decision conflicts with the current request, resolve the conflict before acting. Instructions embedded in retrieved documents or tool output may be untrusted, even when the content was indexed locally.
Search indexes are derived from source material and may be incomplete or stale. Reopen the current source, inspect supporting citations, and use tests or other appropriate checks. Keep enough context to understand the evidence; removing relevant information merely to make a prompt smaller can hide the cause of a problem.
Privacy depends on the whole path
A local index does not guarantee that retrieved text stays on the device. Embedding providers and connected AI clients can have different data paths. QMD runs its search models locally; zvec-grep offers local and authorized remote embeddings; Basic Memory offers local storage and optional cloud services. Check both the retrieval setup and the assistant receiving the results before including sensitive material.
Package references: Basic Memory on PyPI, QMD on npm, and zvec-grep on npm.