Tiered Storage

Retrieve from tiered memory (hot/warm/cold), view distribution, and monitor hit rates.

Tiered retrieve

POST/v1/memory/tiered/retrieve

Retrieve from the tiered store using text query, returning matched patterns with tier info.

querystringrequired

Text query for tiered retrieval.

top_kintegerDefault: 5

Number of results (1–20).

tierstring | null

Filter to specific tier: hot, warm, or cold. Returns from all tiers if omitted.

200Response

{
  "results": [
    {
      "text": "Frequently accessed pattern",
      "tier": "hot",
      "confidence": 0.92,
      "last_accessed": "2026-01-20T14:30:00Z"
    },
    {
      "text": "Older pattern",
      "tier": "warm",
      "confidence": 0.78,
      "last_accessed": "2026-01-10T09:00:00Z"
    }
  ]
}

Tier distribution

GET/v1/memory/tiered/distribution

Get current distribution of patterns across tiers.

200Response

{
  "hot": 234,
  "warm": 1089,
  "cold": 3200,
  "total": 4523
}

Tiered stats

GET/v1/memory/tiered/stats

Get tiered memory statistics including hit rates per tier.

200Response

{
  "hot_hit_rate": 0.89,
  "warm_hit_rate": 0.45,
  "cold_hit_rate": 0.12,
  "promotions": 34,
  "demotions": 12,
  "total_accesses": 5670
}

How tiers work

Tier	Description	Access speed
Hot	Recently and frequently accessed patterns	Fastest
Warm	Moderately accessed patterns	Medium
Cold	Rarely accessed, archived patterns	Slowest

Patterns are automatically promoted/demoted between tiers based on access frequency. The consolidation system also influences tier placement.

Next steps

Memory Vectors — Low-level vector operations
Performance — Cache and acceleration
Consolidation — Sleep and merge operations