cleveragents-core/docs/reference/context_strategies.md

Context Strategy Registry

The Context Strategy Registry manages pluggable retrieval strategies for the ACMS Context Assembly Pipeline. Strategies implement the ContextStrategy protocol and are registered via TOML configuration or programmatic API.

Architecture

ContextRequest
  ┌─── StrategySelector ───┐
  │  can_handle() polling   │
  └──────────┬──────────────┘
             v
  ┌─── BudgetAllocator ────┐
  │  proportional alloc     │
  └──────────┬──────────────┘
             v
  ┌─── StrategyExecutor ───┐
  │  parallel w/ timeout    │
  │  circuit breaker        │
  └──────────┬──────────────┘
             v
      ContextFragment[]

ContextStrategy Protocol

Every strategy implements:

Member	Type	Description
name	property -> str	Unique strategy name
capabilities	property -> StrategyCapabilities	Backend requirements and quality score
can_handle(request, backends)	-> float	0.0-1.0 confidence for this request
assemble(request, backends, budget, plan_context)	-> list[ContextFragment]	Execute and return fragments; must respect budget
explain()	-> str	Human-readable description

StrategyCapabilities

Field	Type	Default	Description
uses_text	bool	False	Requires TextBackend
uses_vector	bool	False	Requires VectorBackend
uses_graph	bool	False	Requires GraphBackend
uses_temporal	bool	False	Requires temporal/cold-tier data
resource_types	tuple[str, ...]	()	Supported resource types (empty = all)
quality_score	float	0.5	Intrinsic quality score (0.0-1.0)
supports_depth_breadth	bool	False	Supports depth/breadth projection
supports_plan_hierarchy	bool	False	Supports plan hierarchy traversal
supports_temporal	bool	False	Supports temporal archaeology queries

Built-in Strategies

Strategy	Quality	Backends	Description
simple-keyword	0.3	Text	Basic keyword/regex text search. Universal fallback.
semantic-embedding	0.6	Vector	Vector similarity search.
breadth-depth-navigator	0.85	Graph	Graph-aware UKO traversal. Primary code-aware strategy.
arce	0.95	All	Multi-modal ARCE pipeline. Highest quality.
temporal-archaeology	0.5	Graph + Cold	Historical pattern discovery.
plan-decision-context	0.7	Warm/Cold	Parent/ancestor plan context retrieval.

Default enabled (spec context.strategies.enabled): ["simple-keyword", "semantic-embedding", "breadth-depth-navigator"]

Configuration

Global (config.toml)

[context.strategies]
enabled = ["simple-keyword", "semantic-embedding", "breadth-depth-navigator"]

[context.strategies.custom]
"my-strategy" = "my_package.strategies:MyStrategy"

Per-strategy settings

Key	Type	Default	Description
timeout_seconds	int	30	Per-strategy assembly timeout
max_fragments	int	100	Maximum fragments per call
max_workers	int	4	Parallel workers for executor
circuit_breaker_threshold	int	3	Failures before circuit opens
enabled	bool	true	Whether the strategy is active

Per-project overrides

Projects can override the global enabled list using:

agents project context set --strategy simple-keyword --strategy semantic-embedding

This replaces the global context.strategies.enabled list for that project.

ContextStrategyResult

Output of a single strategy execution:

Field	Type	Description
strategy_name	str	Name of the producing strategy
fragments	tuple[ContextFragment, ...]	Deterministically ordered fragments
total_fragments	int	Total fragments before limits
tokens_used	int	Total tokens across fragments
execution_time_ms	float	Execution wall-clock time (ms)
errors	tuple[str, ...]	Error messages
stats	dict[str, Any]	Strategy-specific statistics

Fragment ordering: (relevance_score DESC, uko_node ASC).

Registry Validation

The registry validates that:

1. Every enabled strategy is actually registered.
2. Every strategy declares at least one backend capability.
3. Every strategy declares supported resource types.

Fallback Degradation Path

When backends are unavailable, the system degrades gracefully:

1. arce (requires all) → 2. breadth-depth-navigator (graph) →
2. semantic-embedding (vector) → 4. simple-keyword (text only)

This ensures context is always produced.