Overview

agentmemory distinguishes searchable observations from durable memories, episodic summaries, semantic facts, procedures, lessons, and insights. Explicit memories can supersede similar current versions, leaving older records in state but removing them from search indexes. Conditional consolidation raises abstraction only with enough evidence and providers; retention combines salience, time, and access, while TTLs, eviction, and governance deletion change what remains. These mechanisms preserve history and currentness, but similarity and confidence are not proof of truth, and forgetting can discard rare value.

Learning outcomes

A compressed observation records what happened; an explicit memory makes a stronger claim about future usefulness without becoming objective truth.
Supersession normally keeps the latest version in search while retaining older versions for history; Jaccard similarity cannot resolve negation or causality.
Consolidation and retention are conditional policies: recurring evidence can form higher abstractions, while decay or forgetting may remove valuable rare warnings.

Keywords

agentmemoryObservationsSupersessionConsolidationRetentionProvenance

When an Observation Becomes Knowledge

agentmemory becomes more than a searchable event log when it decides what should survive as a current fact, a reusable lesson, or a procedure. This chapter traces that lifecycle: explicit memories can replace older versions, sessions can consolidate into higher abstractions, and time, access, confidence, and deletion rules can change what remains available. The goal is to distinguish evidence from derived knowledge so that persistence does not become a license to trust every stored sentence.

A record of work is not yet a durable fact

A compressed observation answers a narrow question: what happened at a particular point in a session? It may describe a file edit, a command result, a discovered error, or a user request. That evidence is valuable because it can be searched and inspected later. But a tool event is not automatically a rule for the project, and a session narrative is not automatically a procedure that another agent should follow.

A durable memory makes a stronger claim about future usefulness. Agentmemory's explicit memory path accepts categories such as pattern, preference, architecture, bug, workflow, and fact. It can attach concepts, relevant files, a project, source observation IDs, and an agent identity. Those fields give a memory a context and a provenance path. They do not transform it into objective truth. They make its intended role and origin visible enough for later recall, correction, and scope decisions.

The distinction is practical. Suppose an agent first records that a library was selected for compatibility with a particular runtime. That observation may be a useful explanation of a past decision. If the project later moves to a different runtime, the old explanation should not remain the only current account. A new explicit memory needs to supersede it, while the old version may still matter for understanding why earlier code looks the way it does. The lifecycle must preserve history without allowing history to masquerade as the present.

Supersession keeps current recall current

When a new memory is saved, agentmemory does not blindly append it to the corpus. It generates candidate matches and compares normalized token sets with Jaccard similarity, a measure of how much two sets overlap. The exact threshold is a policy choice in the implementation: a sufficiently high match marks an active memory for supersession, while a lower but meaningful match is returned as an advisory near-duplicate hint.

The high-similarity path creates a new version. The new record points to the previous one, increments the version number, and becomes the latest record. The older record is marked not latest. It remains in the key-value state so the version chain can be inspected, but it is removed from the BM25 and vector indexes. That last step is essential. If the old version remained searchable, a query could retrieve an outdated decision with the same status as the current one, even though the system knows that a newer account exists.

This is index hygiene, not merely bookkeeping. Persistent state answers “what records exist?” Search indexes answer “what records should compete for recall?” Those sets are intentionally different. Historical versions belong in the first set for inspection; only current versions should normally compete in the second. A saved memory is added to the indexes immediately, and if indexing fails the durable KV write is still allowed to stand so that a restart-time rebuild can recover it. The result is a system that treats persistence and retrieval as coupled but not identical responsibilities.

The matching method also explains what supersession does not solve. Jaccard overlap compares tokens; it does not understand negation, causality, or whether two similar sentences describe incompatible environments. A high-overlap update can be a true replacement, but it can also be a different statement that happens to use the same vocabulary. The implementation's “current” marker is a recency-and-version decision, not a proof that the newest text is correct.

Project scoping narrows the risk.

Published by DeepMox

FAQ

How does agentmemory prevent an updated memory from competing with its old version?

On a sufficiently similar update, agentmemory creates a new version, marks the old one not latest, retains it in state, and removes it from BM25 and vector indexes. The similarity rule is heuristic rather than a proof that the new text is correct.

What is the difference between episodic, semantic, and procedural memory in agentmemory?

Episodic memory summarizes one session, semantic memory extracts recurring facts across sessions, and procedural memory expresses a recurring workflow. These higher abstractions are conditional on available evidence, recurrence, and provider-backed processing.

Can agentmemory's retention or forgetting rules guarantee that unimportant memories are safe to delete?

No. Retention scores and forgetting policies manage storage under uncertainty; a rarely accessed warning may still matter, and similarity can mistake related statements for contradictions. Deliberate governance deletion is a separate, intentional action.

Previous12 minagentmemory: Recall Loop in Practice

Next11 minagentmemory: One Service, Many Hosts

agentmemory: From Observation to Knowledge

When an Observation Becomes Knowledge

A record of work is not yet a durable fact

Supersession keeps current recall current

FAQ