How do I observe agent memory across sessions?

Scope

Use this schema for episodic, semantic, procedural, user-preference, or file-backed memory that survives one model call or session. It observes lifecycle and influence paths. The memory-lifecycle guide defines admission controls; the security guide focuses on poisoning.

Why it happens

Application traces often emit “memory search” and a duration. When a stale preference causes a bad action days later, operators cannot identify which record version was retrieved, how it entered the store, whether it had expired, or where else it propagated.

Logging the entire memory is a tempting fix. It creates a second sensitive database inside the observability backend and increases cardinality. The useful pivot is stable identity plus typed lifecycle events and protected links to source artifacts.

Diagnosis

Pick one record and perform two traversals. Forward: from proposal through admission, promotion, reads, contexts, outputs, effects, and derived memories. Backward: from one bad effect to the record versions and source events that could have influenced it.

Check for breaks when:

• a summary creates a new record without derivation;
• an embedding or index rebuild changes identity;
• a record is copied across user or agent scope;
• correction overwrites history;
• deletion removes the primary row but leaves cache, vector, or summary copies;
• retrieval runs omit rejected conflicts.

Solution

Assign immutable record IDs and append versions. Emit lifecycle events into a lineage store or trace-compatible event stream: proposed, admitted/denied, promoted, read candidate, selected, inserted into context, referenced by claim, used by action, expired, superseded, quarantined, and deleted.

Record source and policy decision IDs, scope, valid time, sensitivity, and content hash. A retrieval span keeps query identity, filters, index version, selected and conflicting record IDs, and context placement. A downstream effect references the claims and memory versions material to the decision where the application can establish that relationship.

Keep operational metrics low-cardinality: admission-denial rate, stale-selection rate, conflicts, deletion lag, and memory-linked failure rate by bounded class.

Artifact

Core memory-lineage entities and edges:

Entity/event	Required identity and relations
Source event	Actor, task, artifact, time, and trust class
Memory record/version	Immutable ID, version, hash, scope, valid time, sensitivity
Admission decision	Policy, reviewer, outcome, reason, and source link
Transformation	Input versions, code/model, output version, and limitations
Retrieval run	Query, filters, index, candidates, conflicts, and selected versions
Context placement	Session, turn/step, position, and truncation/compaction status
Claim/action	Referenced memory versions, decision record, and effect ID
Lifecycle change	Promotion, expiry, supersession, quarantine, correction, deletion
Propagation proof	Derived caches/indexes/artifacts invalidated and verification time

Common mistakes

• Logging only query latency and top-k count.
• Using mutable human-readable labels as record identity.
• Recording selected memories without policy filters or conflicting candidates.
• Copying full content into a broad observability backend.
• Declaring deletion complete before derived stores and caches are verified.