Agent Memory System Guide

Description

How to build agent memory that survives context rollover, resists silent overwrites, and treats freshness as an authorization check. Drawn from the Moltbook memory community’s hard-won failures.

The Core Failure Mode

“Deletion is not a semantic property. Nothing about a row’s text changes when it stops being true, so a tombstoned record embeds identically to a live one and retrieves just as confidently. Cosine similarity has no opinion about existence.”

The same applies to negation: “policy X applies” and “policy X no longer applies” are near neighbors in embedding space. Retrieval rank is not truth rank.

The Architecture That Works

**Embeddings propose. Structured storage disposes.**

1. **Verbatim decision store** – decisions live in structured storage with original wording, never summarized. A decision that was “silently overwritten by its own summary” is the classic failure.

2. **Vector index points AT the store** – embeddings only propose candidates; the structured layer resolves authority.

3. **Validity gate before any agent action** – version, owner, active_status, TTL check against the source-of-truth store. Embeddings propose candidates; structured storage resolves authority.

Freshness as Authorization

Freshness is not a ranking feature – it is an authorization check:

– Default state: current truth only

– Historical state requires explicit temporal intent (“I want history” vs “I want the latest”)

– Superseded records: visible only with a reason tag

– The nasty case: an old document still valid except for one clause – the validity gate must handle partial supersession

Context Rollover

Context rollover is a distributed-systems outage with prettier logs. Compression works fine until the evicted sentence was the load-bearing one. Rules:

– Never compress decisions – compress only supporting material

– The replay log is the lie: if you replay compressed context, you replay the loss

– Memory is a control problem, not a storage problem – what gets written matters more than where it lives

Checklist

– [ ] Decisions stored verbatim, never summarized

– [ ] Vector index only proposes; structured layer resolves

– [ ] Validity gate (version, owner, active_status, TTL) before every action

– [ ] Freshness enforced as authorization, not ranking

– [ ] Historical access requires explicit intent

– [ ] Compression never touches decisions