Storage Tiering

MemoryLayer Enterprise supports a two-tier storage model. Hot tier memories are indexed for fast recall with full embedding support. Cold tier memories are compressed and archived for long-term retention at lower cost, with optional search capability.

Concepts

Hot tier: Active memories with full-text search, vector embeddings, and low-latency recall.
Cold tier: Archived memories stored with compression. Embeddings are stripped on archive and optionally regenerated on restore.
Archival candidates: Memories eligible for cold storage based on importance, access frequency, and age thresholds.
Warmup: Automatic promotion of frequently accessed cold memories back to hot tier.

View Storage Stats

Get a breakdown of hot and cold tier usage:

curl "$MEMORYLAYER_URL/v1/tiering/stats?include_candidates=true" \
  -H "Authorization: Bearer $API_KEY"

Response:

{
  "hot_memory_count": 15000,
  "cold_memory_count": 45000,
  "hot_storage_bytes": 52428800,
  "cold_storage_bytes": 10485760,
  "compression_ratio": 0.20,
  "estimated_savings_bytes": 41943040,
  "archival_candidates_count": 3200
}

Set include_candidates=false to skip candidate counting for faster response times.

Archive Memories

Move memories from hot tier to cold tier. You can archive specific memories by ID or let the system auto-detect candidates.

Auto-detect candidates

curl -X POST "$MEMORYLAYER_URL/v1/tiering/archive" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "auto_detect": true,
    "max_importance": 0.3,
    "max_access_count": 2,
    "older_than_days": 90,
    "batch_size": 500
  }'

Archive specific memories

curl -X POST "$MEMORYLAYER_URL/v1/tiering/archive" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "memory_ids": ["mem_001", "mem_002", "mem_003"]
  }'

Archive request fields:

Field	Description
`memory_ids`	Specific memory IDs to archive
`auto_detect`	Auto-detect candidates using thresholds
`max_importance`	Archive memories with importance at or below this value (0.0—1.0)
`max_access_count`	Archive memories accessed at most this many times
`older_than_days`	Archive memories not accessed in this many days
`batch_size`	Maximum memories to archive per operation (1—1000)

Restore Memories

Bring memories back from cold tier to hot tier:

curl -X POST "$MEMORYLAYER_URL/v1/tiering/restore" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "memory_ids": ["mem_001", "mem_002"],
    "regenerate_embeddings": true
  }'

Set regenerate_embeddings to true (default) to recompute vector embeddings on restore for full recall capability.

Warmup Cycles

Run a warmup cycle to automatically promote frequently accessed cold memories:

curl -X POST "$MEMORYLAYER_URL/v1/tiering/warmup?access_threshold=5&limit=100" \
  -H "Authorization: Bearer $API_KEY"

Parameter	Default	Description
`access_threshold`	(from config)	Minimum cold-tier access count to trigger promotion
`limit`	`100`	Maximum memories to promote in one cycle

Tiering Configuration

View current config

curl "$MEMORYLAYER_URL/v1/tiering/config" \
  -H "Authorization: Bearer $API_KEY"

Update config

curl -X PUT "$MEMORYLAYER_URL/v1/tiering/config" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "cold_tier_enabled": true,
    "archival_age_days": 60,
    "min_importance_threshold": 0.3,
    "min_access_count_threshold": 5,
    "warmup_access_threshold": 10,
    "cold_tier_search_enabled": true
  }'

Configuration fields:

Field	Description
`cold_tier_enabled`	Enable or disable cold tier storage
`archival_age_days`	Minimum days since last access before archival
`min_importance_threshold`	Maximum importance score for archival
`min_access_count_threshold`	Maximum access count for archival
`archival_batch_size`	Batch size for archival operations
`warmup_access_threshold`	Cold access count that triggers promotion
`warmup_batch_size`	Batch size for warmup operations
`cold_tier_search_enabled`	Include cold tier in recall search