Storage Layers

Cold Archive

Cold archive is the long-tail end of the lifecycle. It is governed entirely by the retention policy resolution chain. This page walks through how dates are computed, the state machine they drive, and how recovery and compliance proof both work.

How the policy is resolved

Namespace-specific override (rare; used for compliance carve-outs).
Tenant-level retention policy applied by the platform for compliance-sensitive workloads.
System defaults below.

System defaults

Key	Value
`<code>DEFAULT_RETENTION_DAYS</code>`	90 — active life of a memory.
`<code>DEFAULT_ARCHIVE_DAYS</code>`	60 — after this, the memory becomes archived (read-only, excluded from recall).
`<code>SOFT_DELETE_GRACE_DAYS</code>`	7 — the recoverable window between soft-delete and hard-delete.
`<code>MINIMUM_RETENTION_DAYS</code>`	1 — floor enforced on tenant overrides.
`<code>MAXIMUM_RETENTION_DAYS</code>`	3650 — ceiling (10 years).

How the dates are computed at write time

TEXT

retention_expires_at = created_at + retention_days
archive_at           = created_at + archive_after_days
hard_delete_at       = retention_expires_at + SOFT_DELETE_GRACE_DAYS

The state machine that fires on those dates

Window	State	Behaviour
Day 0–60	`active`	Fully searchable, readable, usable.
Day 60–90	`archived`	Read-only. Excluded from recall. Admins can still view and restore.
Day 90–97	`soft_deleted`	Invisible to all users. Admins can restore via the restore endpoint.
Day 97	`hard_delete_pending`	Queued for the deletion worker.
Terminal	`purged`	Row gone; only the audit trail and the deletion receipt remain.

The ordered hard-delete steps

Hard deletion is broken into ordered, idempotent steps so a worker crash never produces a half-deleted row. The deletion checkpoint table records the last completed step; recovery resumes from the next.

NOT_STARTED — placeholder.
VECTOR_DELETED — vector removed from the index.
SUMMARY_EMBEDDINGS_DELETED — child summary embeddings removed.
SUMMARIES_DELETED — child summary rows removed.
MEMORY_EVENTS_DELETED — audit trail rows for this memory deleted.
RECALL_LOGS_DELETED — query log rows that referenced the memory deleted.
DEK_DESTROYED — the data encryption key for this memory destroyed; from this point the row is unrecoverable even with backups.
MEMORY_ROW_DELETED — durable row deleted.
RECEIPT_CREATED — the WORM compliance receipt is written.
COMPLETED — the deletion-progress row is closed.

Recovery during the grace window

While the memory is in soft_deleted and now < soft_deleted_at + 7 days, an admin can call the restore endpoint. The platform flips retention_status back to active, clears the timestamps, and re-upserts the vector if it had already been removed. After the seven days have elapsed, restoration is no longer possible — the next worker pass advances the row to hard_delete_pending.

Tenant-level overrides

Custom retention timelines are available for compliance-sensitive contracts (regulated industries, longer legal-hold horizons, shorter aggressive-purge schedules). Overrides are applied by platform operators and are bounded by the system minimum and maximum retention windows so a misconfiguration cannot disable retention entirely or hold data indefinitely.

A right-to-be-forgotten request transitions the memory to soft_deleted with deletion method gdpr_request.
Hard deletion proceeds after the seven-day grace unless a legal hold is placed on the memory or its tenant.
When the legal hold is released, the deletion resumes (deletion method legal_hold_release).
Every transition writes a row to retention_audit_log; the final deletion writes a WORM deletion_receipt with user id, request date, completion date, and reason.

The cold-storage pathway for archived vectors

Archived memories can have their vectors exported to a cold object-storage bucket and removed from the active collection. Cold-tier recall (the computation_tier=high path) restores them lazily on demand. The cold-storage purge schedule mirrors the row's hard-delete schedule, so deleting from the row also expires the archived vector.

← Previous

Hot Cache

API Overview