Core Concepts

Memory Lifecycle

The lifecycle of a memory is a five-state machine driven by the retention_status column. Time-based fields decide when a row moves between states. This page walks through each state, the transitions, and the side effects.

The five states

State	Searchable?	Meaning
`active` (default)	Yes	Normal record. Returned by `/memory/query`.
`archived`	No	Read-only. Excluded from search; still readable by id.
`soft_deleted`	No	Inside the recovery window. Restorable.
`hard_delete_pending`	No	Queued for permanent deletion after grace.
`purged`	No	Terminal. Row is gone (or tombstoned for audit).

The default retention policy

90 days active before retention triggers.
60 days archive window — moved to archived first if the policy enables it.
7 days grace period between soft_deleted and hard deletion.

Where this lives

Defaults are constants on the Memory model itself; tenant-level overrides can shorten or lengthen each window.

The time fields that drive transitions

Field	Triggers
`archive_at`	Move to `archived`.
`retention_expires_at`	Move to `soft_deleted`.
`hard_delete_at`	Move to `hard_delete_pending`, then `purged`.
`expires_at`	User-supplied via `ttl_minutes`. Hard cap on the `active` window.
`deleted_at`	Stamped when the row enters `soft_deleted`.

TTL — the user-controlled shortcut

On POST /memory/add you can pass ttl_minutes. The server computes expires_at = created_at + ttl_minutes. When that timestamp passes, the row exits active the same way the policy would push it out.

TTL is not an importance multiplier. It is an absolute deadline.

What <code>/memory/query</code> returns

Only rows where retention_status = "active".
Past expires_at rows are excluded even if no nightly policy job has run yet.
Archived rows can still be fetched by id but never appear in semantic recall.

Events recorded on transition

Every transition writes a row in memory_events with event_type, source, payload, and created_at. Observed event types include created, deduplicated, and deleted. The event log is the audit trail — the memory row only carries the current state.

Recovering a memory inside the grace window

1Identify the row by id. Its retention_status is soft_deleted and hard_delete_at is in the future.
2An admin or the owning user can flip retention_status back to active before hard_delete_at.
3After hard_delete_at the row enters hard_delete_pending; recovery is no longer guaranteed.
4Once purged, the row is unrecoverable.

Purging on demand

DELETE /memory/user/purge bypasses the gradual lifecycle and removes all of the authenticated user's memory data immediately. Use this for user-initiated data deletion (GDPR right-to-erasure).

← Previous

Memory Types

Memory Tiers