cleveragents-core/.opencode/skills/cleveragents-spec/references/acms

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:

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:

# 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