# ACMS — Advanced Context Management System

## Overview

The ACMS is the pluggable, strategy-driven framework for assembling actor context. It comprises:

1. **UKO** — Universal Knowledge Ontology
2. **CRP** — Context Request Protocol
3. **Pluggable Context Strategies**
4. **Context Assembly Pipeline** (10 components, 3 phases)
5. **Hot/Warm/Cold Storage Tiers**
6. **Skeleton Compressor** (for child plan context)

---

## UKO — Universal Knowledge Ontology

An RDF-based, inheritance-driven ontology representing resources at multiple abstraction levels with provenance and temporal versioning.

**Four Layers:**

| Layer | Description | Examples |
|-------|-------------|---------|
| Universal Foundation | Core relationships applying to all resources | Ownership, timestamps, permissions |
| Domain Specializations | Software, documents, data schemas, infrastructure domains | Code files, markdown docs, database tables |
| Paradigm/Format | Programming paradigms, document formats | Procedural programming, Markdown format |
| Technology-Specific | Specific languages/technologies | Python files, PostgreSQL tables |

**Key property:** Semantically aware — implicit relationships are **inferred from content analysis** (not just explicit declarations).

**URI format:** UKO URIs are stable identifiers — changing a file's content does not change its URI (the URI identifies the entity, not its content).

---

## CRP — Context Request Protocol

A structured vocabulary through which actors declare:
- What information they need
- At what detail depth
- What scope they want

Actors declare context needs via CRP; the ACMS satisfies them through the assembly pipeline.

---

## Context Strategies

Pluggable retrieval components that search for and assemble ContextFragments using a specific approach:

| Strategy Type | Mechanism |
|--------------|-----------|
| Keyword search | Full-text search via Tantivy |
| Semantic embedding | Vector similarity via FAISS/Qdrant |
| Graph navigation | Structural relationships via Neo4j/rdflib |
| Temporal archaeology | Historical context retrieval |

- Strategies are registered with the Context Assembly Pipeline
- Executed **in parallel** by the StrategyExecutor (with circuit-breaker protection per strategy)
- Each produces ContextFragments tagged with UKO URIs

---

## Context Assembly Pipeline

10 pluggable Protocol-defined components in 3 phases. Each ships with a default implementation and is **overridable at plan > project > global scope**.

### Phase 1: Strategy Orchestration

| Slot | Component | Role |
|------|-----------|------|
| 1 | StrategySelector | Selects which strategies to run based on CRP request |
| 2 | ParallelStrategyExecutor | Runs selected strategies concurrently |
| 3 | ResultValidator | Validates strategy outputs for correctness |

### Phase 2: Fragment Fusion

| Slot | Component | Role |
|------|-----------|------|
| 4 | FragmentFusionCoordinator | Coordinates combining fragments from multiple strategies |
| 5 | DeduplicationFilter | Removes duplicate fragments |
| 6 | RelevanceCoherenceOrderer | Orders fragments by relevance and coherence |
| 7 | GreedyKnapsackPacker | Fills context up to token budget greedily |

### Phase 3: Context Finalization

| Slot | Component | Role |
|------|-----------|------|
| 8 | Summarizer | Optionally summarizes fragments to fit budget |
| 9 | ContextFormatter | Formats assembled context for actor consumption |
| 10 | SkeletonCompressor | Produces compressed skeleton for child plan inheritance |

---

## Hot/Warm/Cold Storage Tiers

| Tier | What It Holds | Bounded By |
|------|--------------|-----------|
| **Hot** | Active context in memory; currently relevant to actor reasoning | `hot_max_tokens` |
| **Warm** | Recent decisions and context; quickly accessible | `warm_max_decisions` |
| **Cold** | Persistent storage; all historical context | `cold_max_decisions` |

**Eviction rules:**
- Hot → Warm: on overflow (hot_max_tokens exceeded)
- Warm → Cold: on age threshold
- Cold: persistent storage

**Per-actor scoped views:** Each actor has its own view of the hot/warm/cold tiers.

---

## Skeleton Compression

When a parent plan spawns child plans, the child plans receive a **compressed representation** of the parent's accumulated context (the "skeleton"). This provides child plans with:
- The parent's key decisions and their rationale
- The strategic context within which the child plan operates
- Inherited invariants and constraints

The skeleton size is governed by the `skeleton_ratio` budget parameter (configurable per project context view).

---

## Context View Configuration

Each project can configure context behavior independently per plan phase:

```bash
agents project context set \
  --view strategize \
  --include-resource local/api-repo \
  --exclude-path "**/__pycache__/**" \
  --hot-max-tokens 8000 \
  --warm-max-decisions 50 \
  --cold-max-decisions 200 \
  --query-limit 20 \
  --max-file-size 102400 \
  --max-total-size 10485760 \
  --summarize \
  --summary-max-tokens 2000 \
  --strategy keyword_search \
  --strategy semantic_embedding \
  --default-breadth 10 \
  --default-depth 3 \
  --skeleton-ratio 0.2 \
  --temporal-scope current \
  --execution-environment local/dev-container \
  --execution-env-priority fallback \
  my-api-service
```

**Available views:** strategize | execute | apply | default

**Context inspection commands:**
```bash
# Show current context policy for a project
agents project context show --view strategize my-api-service

# Run context assembly and show results (without executing a plan)
agents project context inspect \
  --view strategize \
  --strategy keyword_search \
  --focus uko:py:module:auth \
  --breadth 5 \
  --depth 2 \
  my-api-service

# Simulate context assembly and show token budget breakdown
agents project context simulate \
  --view strategize \
  --budget 8000 \
  --strategy semantic_embedding \
  my-api-service
```
