cleveragents-core/docs/context.md

Advanced Context Management System (ACMS)

Milestone: v3.4.0 — ACMS v1 + Context Scaling

The Advanced Context Management System (ACMS) provides intelligent, budget-aware context assembly for CleverAgents. It enables projects with 10,000+ files to be indexed and queried efficiently, assembling scoped context views for actors within configurable budget constraints.

---

Overview

ACMS solves the fundamental challenge of providing LLM actors with the right context at the right time, without exceeding token budgets or degrading performance on large codebases.

Key capabilities:

• Large-scale indexing — Projects with 10,000+ files index without timeout
• Budget enforcement — Configurable max_file_size and max_total_size constraints
• Tiered storage — Hot/warm/cold storage tiers manage context lifecycle
• Scoped assembly — Context views are scoped per actor and per resource
• CLI integration — Full agents context command suite

---

Context Policies

Context policies define how context is assembled for a given view. Policies are configurable at the project level and can be overridden per view.

Configuration

Context policies are stored in .cleveragents/config.toml under the [context] section:

[context]
# Maximum size of a single file to include in context (bytes)
max_file_size = 262144        # 256 KB default

# Maximum total size of all context fragments combined (bytes)
max_total_size = 10485760     # 10 MB default

# Storage tier thresholds
hot_tier_max_fragments = 50
warm_tier_max_fragments = 200
cold_tier_max_fragments = 2000

# File patterns to exclude from indexing
exclude_patterns = [
    ".git/**",
    "node_modules/**",
    "__pycache__/**",
    "*.pyc",
    "*.bin",
    "*.exe",
]

View-Specific Settings

Individual context views can override global policy settings:

[context.views.execute]
max_file_size = 131072        # 128 KB for execute view
max_total_size = 5242880      # 5 MB for execute view

[context.views.strategize]
max_file_size = 524288        # 512 KB for strategize view
max_total_size = 20971520     # 20 MB for strategize view

---

Budget Enforcement

ACMS enforces two budget constraints during context assembly:

max_file_size

Controls the maximum size of any single file included in a context fragment. Files exceeding this limit are excluded from context assembly.

• Default: 256 KB (262144 bytes)
• Purpose: Prevents single large files from consuming the entire context budget
• Behavior: Files exceeding the limit are logged at DEBUG level and skipped

max_total_size

Controls the maximum combined size of all context fragments in a single assembled view.

• Default: 10 MB (10485760 bytes)
• Purpose: Ensures the assembled context fits within LLM token budgets
• Behavior: Once the total budget is reached, lower-priority fragments are excluded

Binary File Exclusion

Binary files are automatically excluded from context assembly regardless of size settings. Detection uses content-based heuristics (null byte scanning) rather than file extension matching.

---

CLI Commands

The agents context command suite provides full control over context management.

agents context list

Lists all context fragments currently in the tier service, grouped by storage tier.

agents context list [--plan PLAN_ID] [--format {table,json,plain}]

Options:

Option	Description
--plan PLAN_ID	Filter fragments by plan ID
--format	Output format (default: table)

agents context add

Manually adds a file or directory to the context tier service.

agents context add PATH [--tier {hot,warm,cold}] [--plan PLAN_ID]

Options:

Option	Description
PATH	File or directory path to add
--tier	Target storage tier (default: warm)
--plan PLAN_ID	Associate fragment with a specific plan

Example:

# Add a single file to hot tier
agents context add src/critical_module.py --tier hot

# Add a directory to warm tier
agents context add src/utils/ --tier warm --plan 01HXYZ...

agents context show

Displays detailed information about a specific context fragment or the assembled context view for a plan.

agents context show [FRAGMENT_ID | --plan PLAN_ID] [--format {table,json,plain}]

Options:

Option	Description
FRAGMENT_ID	Show details for a specific fragment
--plan PLAN_ID	Show assembled context view for a plan
--format	Output format (default: table)

agents context clear

Removes context fragments from the tier service.

agents context clear [--tier {hot,warm,cold,all}] [--plan PLAN_ID] [--confirm]

Options:

Option	Description
--tier	Clear only the specified tier (default: all)
--plan PLAN_ID	Clear only fragments for a specific plan
--confirm	Skip confirmation prompt

---

Hot/Warm/Cold Storage Tiers

ACMS uses a three-tier storage model to manage context lifecycle efficiently.

Tier Definitions

Tier	Description	Access Speed	Eviction Policy
Hot	Actively used fragments for the current actor	Immediate	LRU when capacity exceeded
Warm	Recently accessed fragments, likely to be reused	Fast	LRU + staleness-based
Cold	Indexed but infrequently accessed fragments	Slower	Age-based + LRU

Tier Promotion and Demotion

Fragments move between tiers automatically based on access patterns:

• Promotion: A fragment accessed from warm or cold is promoted toward hot
• Demotion: Fragments not accessed within the staleness window are demoted
• Eviction: When a tier reaches capacity, the least-recently-used fragment is evicted to the next tier or removed

Thread Safety

ContextTierService uses a reentrant lock (threading.RLock) to ensure thread safety when parallel subplans share the same DI Singleton instance. All public methods acquire the lock before accessing tier data structures.

---

Context Assembly Pipeline

The context assembly pipeline transforms raw file content into scoped, budget-constrained context views for LLM actors.

Pipeline Stages

1. Hydration — git ls-files / os.walk enumerates project files into TieredFragment objects
2. Filtering — Binary exclusion, size limits, and pattern exclusion applied
3. Tiering — Fragments assigned to hot/warm/cold based on relevance score
4. Assembly — Budget-constrained selection with scope application produces the final context view

Context Hydration

The context_tier_hydrator.py module reads files from linked project resources before context assembly in LLMExecuteActor.execute(). It:

1. Resolves project resource paths via plan.project_links
2. Enumerates files using git ls-files (for git projects) or os.walk (for non-git projects)
3. Applies size and binary filters
4. Creates TieredFragment objects with metadata
5. Stores fragments in ContextTierService

Scoped Context Views

Context views are scoped per actor and per resource to prevent cross-contamination between parallel subplans.

---

Large Project Indexing

ACMS is designed to handle projects with 10,000+ files without timeout.

Performance Characteristics

Project Size	Indexing Time	Memory Usage
1,000 files	< 1 second	~50 MB
10,000 files	< 10 seconds	~200 MB
50,000 files	< 60 seconds	~800 MB

Optimization Strategies

1. Lazy loading — File content is read on demand, not during initial indexing
2. Streaming hydration — Files are processed in batches to limit peak memory usage
3. Parallel enumeration — Directory traversal uses thread pools for I/O-bound operations
4. Incremental updates — Only changed files (via git diff) are re-indexed on subsequent runs

---

Integration with Plan Execution

ACMS integrates directly with the plan execution pipeline to provide LLM actors with relevant context.

Automatic Context Injection

When agents plan execute runs, ACMS automatically:

1. Hydrates the context tier from project resources
2. Assembles a scoped context view for the execute actor
3. Injects the context view into the LLM prompt
4. Tracks which fragments were used for observability

Context in Strategy Phase

During agents plan strategize, ACMS provides a broader context view to help the strategy actor understand the full project structure before decomposing the plan.

Context in Apply Phase

During agents plan apply, ACMS provides targeted context for validation actors to verify that applied changes are consistent with the project.

Configuration Example

[actor.execute]
context_view = "execute"
context_budget_bytes = 5242880

[actor.strategize]
context_view = "strategize"
context_budget_bytes = 20971520

---

Troubleshooting

Context is Empty

If the LLM receives no file context, check:

1. Project links — Ensure the plan has linked project resources (agents plan link)
2. File permissions — Ensure the agent process can read project files
3. Budget settings — Increase max_total_size if all files exceed the budget
4. Exclusion patterns — Check that source files are not matched by exclusion patterns

Indexing Timeout

For very large projects:

1. Increase the hydration timeout in config: context.hydration_timeout_seconds = 120
2. Add more specific exclusion patterns to reduce the file count
3. Use agents context add to manually add only the most relevant files

Thread Safety Errors

If you see RuntimeError: dictionary changed size during iteration:

• This was fixed in v3.4.0 (see ContextTierService thread safety fix)
• Ensure you are running v3.4.0 or later

---

See also: ACMS / UKO API Reference | Context Hydration Module