Executor Agent

The ExecutorAgent orchestrates the four cognition modules through an iterative decision cycle. It implements a Recognizer-first pipeline with a conditional Decayer→Activator thinking loop.

Execution Flow

sequenceDiagram
    participant U as User
    participant E as Executor
    participant R as Recognizer
    participant D as Decayer
    participant A as Activator
    participant M as Memory Manager

    U->>E: user_message
    E->>R: RecognizerInput
    R-->>E: RecognizerOutput (input_type, memories, utility_updates)
    E->>M: store new memories
    alt input_type == QUESTION or rule_statement
        E->>D: DecayerInput
        D-->>E: DecayerOutput (requires_activation, tier_metrics)
        alt requires_activation == true
            E->>A: ActivatorInput
            A->>M: retrieve from Qdrant
            M-->>A: retrieved memories
            A-->>E: ActivatorOutput (merged buffer)
        end
    end
    E->>E: generate_response (LLM + buffer)
    E-->>U: response
    E->>E: apply_interaction_decay
    

Step-by-Step

1. Recognizer (always first) — Classifies input type (statement / question / feedback), extracts semantic and episodic memories, assesses utility of existing memories, proposes topic updates.
2. Memory Manager (store) — New memories from the Recognizer are stored in Qdrant with embeddings.
3. Decayer (conditional) — Runs only for questions or rule-containing statements. Uses two-tier uncertainty (LLM + cosine similarity) to decide if activation is needed.
4. Activator (conditional) — Expands the query into a DAG of sub-queries, retrieves memories from Qdrant, curates and merges the buffer. May trigger multiple times in the thinking loop.
5. Response generation — LLM call with the curated memory buffer as context.
6. Post-response — Second Recognizer pass for meta-learning insights; Ebbinghaus decay applied to all buffer memories; low-scoring memories purged.

Module Internal Flows

Decayer Flow

flowchart LR
    I["DecayerInput
(query + buffer)"] --> T1["Tier 1: LLM
Uncertainty"]
    T1 --> T2["Tier 2: Cosine
Similarity"]
    T2 --> D{"Both tiers
high?"}
    D -->|Yes| ACT["requires_activation = true"]
    D -->|No| SUF["is_sufficient = true"]
    

Activator Flow

flowchart LR
    I["ActivatorInput
(query + clusters)"] --> QE["Query Expansion
DAG"]
    QE --> RET["Qdrant Retrieval
(per sub-query)"]
    RET --> CUR["Buffer Curation
(LLM or heuristic)"]
    CUR --> OUT["ActivatorOutput
(merged buffer)"]
    

Recognizer Flow

flowchart LR
    I["RecognizerInput
(user + response)"] --> CLS["Input
Classification"]
    CLS --> SEM["Semantic
Extraction"]
    CLS --> EPI["Episodic
Detection"]
    CLS --> UTL["Utility
Assessment"]
    CLS --> TOP["Topic
Construction"]
    SEM --> OUT["RecognizerOutput"]
    EPI --> OUT
    UTL --> OUT
    TOP --> OUT
    

Memory Hierarchy

flowchart TB
    subgraph MemoryHierarchy ["Memory Hierarchy Space"]
        direction TB
        L1["L1: Dynamic Procedural
(clustering topics, meta-learning)"]
        L2["L2: Semantic
(factual knowledge, rules, preferences)"]
        L3["L3: Episodic
(experiences, strategies, traces)"]
    end
    L1 --- L2
    L2 --- L3
    HIGH["High Accessibility"] -.-> L1
    LOW["Low Accessibility"] -.-> L3
    

Configuration Reference (ExecutorConfig)

Metrics Reference

The ExecutorAgent tracks detailed per-interaction metrics in last_metrics. These are grouped by module:

Recognizer Metrics

Decayer Metrics

Activator Metrics

Response Metrics

Memory & Thinking Loop Metrics

Logging Systems

IntermediateLogger

Full per-interaction snapshots when log_intermediate_data=true. Each entry contains: DecayerSnapshot (tier metrics, cluster assessments), ActivatorSnapshot (DAG nodes/edges, retrieved memory IDs), BufferSnapshot before and after (all memories with decay/utility/reward scores, token counts), judge score, and the complete metrics dict. Output: intermediate_<run_id>.json.

DecayTracker

Per-memory decay timelines when log_decay_curves=true. Records (memory_id, interaction_id, decay_score, was_accessed, was_reinforced) at each interaction. Enables plotting Ebbinghaus decay curves and analyzing reinforcement patterns.

ActivatorTracker

Activation trigger patterns when log_activator_triggers=true. Tracks trigger frequency, rate, uncertainty levels, and which clusters triggered activation.

MetricsCollector

Aggregated run-level statistics. Computes mean, std, min, max, p50, p95 for all numeric metrics across interactions. Tracks total token usage, activator trigger rate, and judge score distribution.