# CleverAgents Architecture FAQ
### Q: How does CleverAgents handle persistent repository knowledge beyond ephemeral context windows?
**What exists today architecturally**: The specification defines the Advanced Context Management System (ACMS) — a sophisticated, pluggable, strategy-driven framework that goes far beyond ephemeral context windows. At its core are three innovations: (1) the Universal Knowledge Ontology (UKO), an inheritance-based RDF ontology that represents any resource at multiple abstraction levels with full provenance and temporal versioning; (2) the Context Request Protocol (CRP), through which actors dynamically declare what information they need at what detail depth; and (3) a Context Assembly Pipeline — a 10-component pluggable pipeline that orchestrates strategy selection, budget allocation, parallel execution, fragment deduplication, depth resolution, scoring, budget packing, ordering, preamble generation, and skeleton compression. Each component is backed by a replaceable Protocol implementation configurable at global, project, or plan scope. Underlying this is the Decision Tree structure which provides a durable, queryable record of every choice made during planning.
**How the persistent model works in practice**:
When a strategy actor analyzes a codebase during the Strategize phase, the ACMS assembles context dynamically using the CRP. The actor issues `request_context` calls specifying focus nodes (UKO URIs), breadth (hop count), depth (an integer or named level like `SIGNATURES`, `FULL_SOURCE`), and optional depth gradients. The Context Assembly Pipeline then orchestrates the full assembly: the StrategySelector chooses applicable strategies (e.g., `breadth-depth-navigator` for graph traversal, `semantic-embedding` for similarity search, `plan-decision-context` for historical decisions), the BudgetAllocator distributes the token budget, the StrategyExecutor runs them in parallel, and the fusion phase (FragmentDeduplicator, DetailDepthResolver, FragmentScorer, BudgetPacker, FragmentOrderer) deduplicates, resolves detail conflicts, scores, and packs the results into the available budget.
Each decision creates a comprehensive Decision record that includes:
context_snapshot:
hot_context_hash: str # Cryptographic hash of the exact context
hot_context_ref: str # Pointer to the full stored snapshot
relevant_resources: list[ResourceRef] # Every file/symbol that influenced this decision
actor_state_ref: str # Complete LangGraph checkpoint
uko_focus_nodes: list[UKO_URI] # UKO nodes that were the focus of this context assembly
strategies_used: list[str] # Which ACMS strategies contributed to this context
Plan: Convert Firefox Renderer to Rust
├── [invariant_enforced] "Maintain API compatibility with existing C++ callers"
├── [invariant_enforced] "All converted modules must pass existing C++ test suites"
├── [strategy_choice] Architecture approach: Start with leaf modules, work inward
│ Context: Analyzed module dependency graph, 2,847 modules total
│ Resources: module_graph.json, architecture_docs.md
│
├── [subplan_parallel_spawn] Phase 1: Convert utility libraries (no external deps)
│ └── [subplan_spawn] Convert string_utils module
│ └── Plan: 01KH29R8WPKPBHRY7Q0NA9XW86
│ ├── [prompt_definition] "Convert string_utils module to Rust"
│ ├── [invariant_enforced] "Maintain API compatibility with existing C++ callers"
│ ├── [implementation_choice] Use Rust's String type, not custom implementation
│ │ Context: Analyzed 47 string_utils.cpp functions
│ │ Resources: string_utils.cpp, string_utils.h, 12 dependent files
│ │ Rationale: Rust's String provides same guarantees with better ergonomics
│ └── ...
# Pseudocode of what happens inside a strategy actor
def compute_closure_for_refactoring(target_module):
closure = ResourceClosure()
# Direct file dependencies
closure.add_files(find_imports(target_module))
closure.add_files(find_includes(target_module))
# Symbol dependencies
for symbol in extract_exported_symbols(target_module):
closure.add_files(find_symbol_usage(symbol, scope='project'))
# Test dependencies
closure.add_files(find_tests_for_module(target_module))
# Build system dependencies
closure.add_files(find_build_references(target_module))
return closure
# Individual child plan spawn
decision_type: subplan_spawn
chosen_option: "Refactor authentication module"
downstream_plan_ids: ["plan-auth-refactor-123"]
artifacts_produced:
- auth_module_files: ["auth.rs", "auth_test.rs", "auth_types.rs"]
- api_updates: ["api/v2/login.rs", "api/v2/logout.rs"]
# Parallel group of child plans
decision_type: subplan_parallel_spawn
chosen_option: "Convert utility libraries in parallel"
# Contains subplan_spawn children, each with their own downstream_plan_ids
STRATEGIZE PHASE:
1. Analyze network stack structure
- Identifies 847 C++ files in netwerk/ directory
- Traces public API surface (237 exported functions)
- Maps internal dependencies (1,432 internal calls)
2. Compute minimal closure for Phase 1 (DNS resolver):
- Core files: dns_resolver.cpp, dns_cache.cpp, dns_config.cpp (3 files)
- Direct dependencies: 12 files in netwerk/base/
- Test files: 8 test files specific to DNS
- Build files: 2 moz.build files
- Total closure: 25 files (not 847!)
3. Generate execution blueprint with child plans:
- [subplan_parallel_spawn] DNS module conversions:
- convert-dns-types: Closure of 5 files (type definitions)
- convert-dns-cache: Closure of 8 files (cache + tests)
- convert-dns-resolver: Closure of 12 files (resolver + integration)
Plan A (refactoring auth module):
- Sandbox A1: Contains only auth/*.cpp, auth_tests/*.cpp
- Cannot see Plan B's intermediate states
- Cannot accidentally depend on Plan B's half-done work
Plan B (updating API endpoints):
- Sandbox B1: Contains only api/*.cpp, api_tests/*.cpp
- Makes changes assuming current auth interface
- Protected from Plan A's intermediate refactoring
Git repositories:
- Strategy: git worktrees
- Coordination: Git's three-way merge algorithm
- Conflict detection: Built into Git
- Rollback: git reset/checkout
Databases:
- Strategy: Transaction isolation
- Coordination: MVCC (multi-version concurrency control)
- Conflict detection: Serialization failures
- Rollback: Transaction abort
Cloud Infrastructure:
- Strategy: Terraform workspaces
- Coordination: State locking
- Conflict detection: Resource conflicts in plan
- Rollback: Previous state restoration
def merge_subplan_results(subplan_results):
# Group by resource type
by_resource = group_by_resource_type(subplan_results)
# Apply resource-specific merge strategies
for resource_type, changes in by_resource:
if resource_type == 'git-checkout':
merge_git_changes(changes) # Three-way merge
elif resource_type == 'fs-mount':
merge_fs_changes(changes) # Copy-on-write reconciliation
elif resource_type.startswith('database'):
merge_db_changes(changes) # Sequential application
# Validate merged state
run_integration_tests()
PARALLEL EXECUTION WITHOUT COORDINATION (what we prevent):
- Service A refactors to async auth → breaks Service B
- Service B compensates with workaround → breaks Service C
- Service C changes error handling → breaks Services D, E, F
- Cascade of failures!
CLEVERAGENTS COORDINATED EXECUTION:
Parent Plan: Refactor auth library
├── [invariant_enforced] "Auth library public API must remain backward compatible during transition"
├── [subplan_spawn] Plan 1: Update auth library interface
│ Sandbox: Only auth library files
│ Output: New interface definition
│
├── Barrier: Wait for Plan 1 completion
│
├── [subplan_parallel_spawn] Plans 2-16: Update each service (in parallel)
│ Each sandbox: Only that service's files
│ Each uses: New interface from Plan 1
│ No inter-service dependencies during execution
│
└── Merge Phase:
- Collect all service updates
- Apply to main branch in order
- Run integration tests
- If conflicts: Parent plan resolves using semantic understanding
Two child plans both modify api/user.rs:
- Plan A: Adds async fn get_user_profile()
- Plan B: Adds fn validate_user_permissions()
Merge strategy:
- Git merge succeeds (different functions)
- Semantic validation ensures both functions work together
- Parent plan adds integration glue if needed
Execution timeline:
T1: Plan A creates checkpoint before major refactor
T2: Plan B creates checkpoint before API changes
T3: Plan A encounters error, rolls back to T1
T4: Plan B completes successfully
T5: Plan A retries with knowledge of B's success
When modifying shared schema files:
- Acquire exclusive lock on schema resources
- Make changes atomically
- Release lock with new version
- Other plans rebase on new schema
Decision: Refactor payment module to async
alternatives_considered:
- "Convert to async/await patterns" (chosen)
- "Use thread pool with channels" (rejected: doesn't integrate with async ecosystem)
- "Keep synchronous with timeout" (rejected: doesn't solve core latency issue)
confidence_score: 0.85
validation_performed:
- Checked all payment API consumers can handle async
- Verified database driver supports async operations
- Confirmed no regulatory requirement for sync processing
actors:
code_executor:
type: graph
skills:
- local/semantic-validators # Contains validation tools for LLM tool-calling
nodes:
- name: semantic_validator
type: tool
tool: local/validate-api-compat # Named tool from Tool Registry
# The system collects, reconciles, and enforces semantic invariants
class InvariantEnforcer:
def compute_effective_invariants(self, plan):
"""Compute the effective invariant view using the Invariant Reconciliation Actor."""
raw = self.collect_all_invariants(plan)
reconciler = (
self.get_plan_invariant_actor(plan)
or self.get_project_invariant_actor(plan)
or self.get_global_invariant_actor()
)
# Apply precedence: plan > project > global
return reconciler.reconcile(raw, precedence=['plan', 'project', 'global'])
def collect_all_invariants(self, plan):
"""Collect invariants from all scopes accessible to this plan."""
invariants = []
invariants.extend(self.get_global_invariants())
for project in plan.projects:
invariants.extend(self.get_project_invariants(project))
invariants.extend(self.get_action_invariants(plan.action))
invariants.extend(self.get_plan_invariants(plan))
return invariants
# Example invariants at different scopes:
# Global: "Payment processing must be idempotent"
# Project: "Database transactions must complete within 5 seconds"
# Action: "Test files must not import production secrets"
# Plan: "All API calls over TCP must be mocked"
def check_invariant_preservation(self, changes, enforced_invariants):
for invariant in enforced_invariants:
if not self.verify_invariant(invariant, changes):
return InvariantViolation(invariant, changes)
return Success()
Error Pattern Database:
- pattern: "Async conversion in payment module"
historical_failures:
- "Race condition in payment confirmation"
- "Timeout handling breaks idempotency"
preventive_checks:
- "Add explicit transaction boundaries"
- "Verify idempotency keys are preserved"
- "Check distributed lock acquisition"
PROACTIVE CONTAINMENT IN ACTION:
1. Strategy Phase Semantic Analysis:
- Decision: "Convert order service to event sourcing"
- Semantic check: "Event sourcing requires eventual consistency"
- Identifies: 3 services assume immediate consistency
- Adds decision: "Update dependent services for eventual consistency"
2. Execution Phase Invariant Checking:
- Detects: PaymentService.chargeCard() called after OrderCreated event
- Semantic issue: Payment before order confirmation violates business rules
- Automatic fix: Insert OrderConfirmed event requirement
3. Validation Node Catches Edge Case:
- Discovers: Audit service expects synchronous order numbers
- Impact: Async events break compliance reporting
- Resolution: Add audit event buffer with guaranteed ordering
4. Pre-Apply Semantic Verification:
- Simulates production event flow
- Detects: Under high load, events can arrive out of order
- Adds: Event ordering guarantees via vector clocks
definition_of_done:
must:
- "All API changes maintain backward compatibility"
- "No increase in p99 latency"
- "Audit trail remains complete"
should:
- "Improve code coverage by 10%"
- "Reduce cyclomatic complexity"
may:
- "Optimize for memory usage"
manual Profile (all thresholds = 1.0):
- Every phase transition pauses for human action
- Every decision point pauses for human input
- User sees: Context, alternatives, recommendation, confidence score
- User provides: Explicit choice or custom guidance
- Use case: New users, critical production changes, first-time codebase exploration
review Profile (phase thresholds = 0.0, decision thresholds = 1.0):
- Phases run automatically (Strategize, Execute proceed without pausing)
- Every decision within those phases pauses for human input
- Apply is manual; transient retries and child plans are automatic
- Use case: Teams that want to stay in the decision loop without triggering phases
supervised Profile (strategize thresholds = 0.0, execute/apply = 1.0):
- Strategize runs automatically with autonomous decisions
- System pauses before Execute for human review of strategy
- Transient failures retried automatically
- Use case: Projects where you trust planning but want to review before execution
cautious Profile (intermediate thresholds = 0.6-0.8):
- System proceeds automatically only when Semantic Escalation reports high confidence
- Escalates to human when uncertain (confidence below threshold)
- Higher bars (0.8) for risky operations, lower bars (0.6) for safer ones
- Use case: Gradual automation adoption, mixed-complexity projects
trusted Profile (most thresholds = 0.0, apply = 1.0):
- Strategize and Execute run automatically with autonomous decisions
- Validation failures self-fixed within strategy bounds
- Child plans spawned automatically
- System pauses before Apply for human diff review
- Use case: Normal feature development, refactoring
autonomous Profile (all thresholds = 0.0 except apply = 1.0):
- Everything automatic except Apply
- Can revise its own strategy if execution hits a wall
- Restores from checkpoints on failure
- Use case: Well-understood projects, batch operations
ci Profile (all thresholds = 0.0, sandbox + checkpoints required):
- Complete end-to-end automation including Apply
- Sandbox and checkpoints remain mandatory for safety
- Unsafe tools blocked
- Use case: CI/CD pipelines, headless batch jobs, scheduled automation
full-auto Profile (all thresholds = 0.0):
- Complete end-to-end automation including Apply
- No sandbox or checkpoint requirements
- Unsafe tools allowed
- Use case: Routine updates, environments with external safety mechanisms
Custom profiles with intermediate thresholds (e.g., 0.3, 0.5, 0.7):
- Fine-grained control: auto-execute with confidence >= 0.5 but escalate below
- Different thresholds per flag: low bar for retries, high bar for strategy revision
- Enables "trust but verify" patterns without binary on/off
- Use case: Teams building confidence gradually, mixed-risk projects
# User observes AI made suboptimal choice
agents plan tree <plan_id>
# Sees: [Decision] "Use REST API for service communication"
# User knows gRPC would be better for this use case
agents plan correct <decision_id> --mode=revert \
--guidance "Use gRPC instead of REST. This service requires streaming
updates and binary protocol efficiency. Set up protocol
buffer definitions and generate client/server stubs."
# System:
# 1. Marks original decision as superseded
# 2. Creates new decision with user guidance
# 3. Recomputes ONLY affected downstream decisions
# 4. Preserves all unrelated work
class AutonomyController:
def assess_decision_confidence(self, decision, context, profile):
factors = {
'past_success_rate': self.get_historical_success(decision.type),
'codebase_familiarity': self.get_familiarity_score(context.project),
'risk_assessment': self.evaluate_risk(decision),
'invariant_complexity': self.analyze_invariants(decision)
}
confidence = self.compute_confidence(factors) # Returns 0.0–1.0
threshold = profile.get_threshold(decision.flag) # From profile
if confidence >= threshold:
return ProceedAutonomously(decision, confidence)
else:
# Confidence below profile threshold — escalate to human
return RequestHumanGuidance(decision, confidence, threshold, factors)
Scenario: "Modernize legacy e-commerce system"
INITIAL PLAN (Full Automation Mode):
1. System analyzes 50,000 line codebase
2. Identifies modernization opportunities
3. Creates plan with 47 child plans
AUTONOMOUS EXECUTION WITH SMART ESCALATION:
[subplan_parallel_spawn] Plans 1-15: Update utility functions (executes autonomously)
- Confidence: 0.95 (straightforward transformations)
- Result: Success
[subplan_spawn] Plan 16: Refactor payment processing
- Confidence: 0.4 (critical business logic)
- [invariant_enforced] "Preserve exact penny rounding behavior"
- Action: ESCALATES to human
- Human provides: "Preserve exact penny rounding behavior"
- Continues autonomously with constraint
[subplan_parallel_spawn] Plans 17-30: UI component updates (executes autonomously)
- Confidence: 0.9 (isolated changes)
- Result: Success
[subplan_spawn] Plan 31: Database schema migration
- Detects: Would require 6-hour downtime
- Action: ESCALATES to human
- Human provides: "Use online migration with feature flags"
- Re-plans with zero-downtime approach
[subplan_parallel_spawn] Plans 32-47: Complete autonomously