cleveragents-core/docs/reference/context_tiers.md

Context Tiers

The ACMS Context Tier system manages context fragments across three storage tiers — hot, warm, and cold — with per-actor visibility, project scoping, and LRU eviction.

Overview

Tier	Backend	Latency	Capacity
Hot	In-memory	Low	Token-budget
Warm	SQLite stub	Medium	Decision-count
Cold	File stub	High	Decision-count

Models

ContextTier

class ContextTier(StrEnum):
    HOT = "hot"
    WARM = "warm"
    COLD = "cold"

ActorRole

class ActorRole(StrEnum):
    STRATEGIST = "strategist"  # sees hot + warm + cold
    EXECUTOR = "executor"      # sees hot + warm
    REVIEWER = "reviewer"      # sees hot only

TieredFragment

Extends the CRP ContextFragment concept with tier placement and access tracking metadata:

• fragment_id — stable unique identifier
• content — rendered text content
• tier — current storage tier
• resource_id — originating resource
• project_name — project scope for isolation
• token_count — token count of content
• last_accessed — timestamp for LRU eviction
• access_count — access frequency counter
• created_at — creation timestamp

TierBudget

Controls capacity per tier:

• max_tokens_hot (default: 8000)
• max_decisions_warm (default: 500)
• max_decisions_cold (default: 5000)

ActorContextView

Per-actor filtered view configuration with role-based default tiers.

TierMetrics

Hit/miss counters: hot_hit_count, hot_miss_count, warm_hit_count, warm_miss_count, plus population counts per tier.

ScopedBackendView

Project-scoped filter that enforces resource isolation. Fragments with empty project_name are excluded by default.

Service

ContextTierService

from cleveragents.application.services.context_tiers import ContextTierService

svc = ContextTierService()
svc.store(fragment)
svc.get("fragment-id")
svc.promote("fragment-id")     # cold→warm or warm→hot
svc.demote("fragment-id")      # hot→warm or warm→cold (with summarisation)
svc.evict_lru(ContextTier.HOT, count=5)
svc.get_for_actor(ActorRole.STRATEGIST, project_names=["my-project"])
svc.get_scoped_view(["my-project"])
svc.get_metrics()

Configuration

Environment variables (via Settings):

Variable	Default	Description
CLEVERAGENTS_CONTEXT_MAX_TOKENS_HOT	8000	Max tokens in hot tier
CLEVERAGENTS_CONTEXT_MAX_DECISIONS_WARM	500	Max fragments in warm tier
CLEVERAGENTS_CONTEXT_MAX_DECISIONS_COLD	5000	Max fragments in cold tier

DI Container

The ContextTierService is registered as a singleton in the DI container:

from cleveragents.application.container import get_container

container = get_container()
svc = container.context_tier_service()