# 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

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

### ActorRole

```python
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

```python
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:

```python
from cleveragents.application.container import get_container

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