Core Concepts

Memory Tiers

A memory's tier is a coarse storage-hotness label that lives on the tier column and travels with the vector metadata. It is orthogonal to lifecycle: a memory can be active and cold at the same time. This page explains the three tiers, how they are assigned, and how they interact with retrieval.

The three allowed values

Tier	When you see it
`hot`	Newly created memories and rows under active recall.
`warm`	Older but still searchable rows. Lower priority during ranking.
`cold`	Long-term storage. Searchable, but typically only surfaced when explicit filters demand it.

Default value on insert is hot.

How the initial tier is computed

At write time the platform calls an internal helper that derives the tier from the row's projected lifetime — primarily from expires_at. A short TTL pushes a row toward warm/cold immediately because the policy already plans to age it out.

Default behaviour

If ttl_minutes is not set, the row starts hot and is not promoted or demoted by the write path itself.

Tier vs retention_status — they are different axes

Axis	Question it answers
`tier`	Where does this row live, performance-wise?
`retention_status`	Is this row visible at all?

A cold row with retention_status="active" is fully recallable. An archived row, regardless of tier, is not.

Filtering retrieval by tier

POST /memory/query accepts a tier filter accepting the literals hot, warm, cold. Use it when you need to narrow recall to recent memories or, conversely, sweep cold archives.

JSON

{
  "query": "last quarter goals",
  "tier": "cold",
  "limit": 10
}

Tier metadata on the vector index

Tier is also written to the metadata that travels with the vector — alongside memory_id, retention_status, environment, project_id, tags, and source. This is what lets a tier filter run inside the vector search itself rather than after the fact.

How a row moves between tiers over time

Tier is mutable. Background maintenance can promote or demote it as usage patterns and freshness shift.
usage_count and decay_score are the primary signals: high usage keeps a row hot; long stretches without recall demote it.
Tier changes do not change the row's identity, vector, or scope keys.

What tier does not do

It does not delete data — only retention_status can do that.
It does not change a row's encryption or its scope.
It does not affect billing of stored bytes — those count regardless of tier.

← Previous

Memory Lifecycle

Importance Scores