Versions & Deletion

Memory entries are immutable. Nothing in the store is ever edited in place — every change is a new version, and history is preserved.

Versions

• An entry starts at version 1. Each edit — body, tags, or priority — writes a new version that records which version it supersedes.
• memory_update returns the new version number; readers always see the head version.
• Deduplication: writing an entry with an identical scope, tags, and body deduplicates to the existing entry instead of creating a copy. One fact, one entry.
• Size cap: an entry body is capped at 8 KB. A larger write is refused with advice to store a summary instead.
• Secret scanning applies to every version. A new body that looks like a credential is refused with the detected pattern named — on first write and on every edit alike.

Deletion is a tombstone

memory_delete writes a tombstone version: the entry disappears from every list and query immediately, but the deletion is recorded as a version rather than erasing history — a recoverable tombstone, not a purge.

A deleted entry cannot be edited back to life. An update against it is refused with "This entry was deleted. Add a new one with memory_add instead."

Pinned entries are protected from both operations: an agent's edit or delete against a pin is refused and redirected to the human — see Pinning & Promotion.

Freshness: active → stale → archived

Separate from recency, every entry carries a durable freshness state that only moves forward:

State	Meaning
active	Live, current memory.
stale	Old enough that its scope's retention policy flagged it.
archived	Retired; the last stop before an archived entry is tombstoned.

Freshness is visible where memory is visible: the Memory card on an agent's page shows the distribution as bars, and on the Neural Map an entry whose freshness has left active renders dimmed — faded, but still there.

Retention is opt-in, per scope

By default nothing expires: a missing retention policy means no retention behavior at all. A retention policy is set per scope and measures three durations from the head version's last update:

Duration	Effect when exceeded
stale-after	The entry's freshness moves active → stale.
archive-after	The entry's freshness moves to archived.
delete-archived-after	An archived entry is tombstoned.

Retention maintenance runs as event-triggered sweeps. Each forward move is written as a new version — the same versioned, append-only mechanism every other change uses — so even aging leaves a trail.

Where to go next

• Memory tools — the tool calls behind each operation.
• Memory card — reading freshness and write activity per agent.
• Scopes — the visibility side of the same store.