Go to website

Context Graph Guide

Introduction & Core Philosophy

Context graphs are partial non-homogeneous hierarchical state machines that become complete when composed with an agent and dynamic behaviors. They model problem spaces designed to deliver particular services to users through interconnected states and transitions that define conversational flows and behavioral constraints.

The Composition Metaphor

Designing a context graph is like creating a theatrical framework that combines with an actor (agent) and script adaptations (dynamic behaviors) to deliver a complete performance:

  1. The Stage & Direction (Context Graph): Provides the structural framework, scene transitions, and contextual requirements for the service being delivered

  2. The Actor (Agent): Brings identity, expertise, personality, and interpretive skills to animate the framework

  3. Script Adaptations (Dynamic Behaviors): Contextual modifications that adjust the performance based on real-time conditions

    • Can override (OVERWRITE mode) or enhance (MERGE mode) existing state instructions

    • Triggered per interaction (one behavior per state transition)

    • Multiple behaviors can be activated across a conversation session

    • Allow real-time adaptation without modifying the underlying context graph

The Identity-Context Density Model

When an agent is composed with a context graph, the graph's density determines the balance of influence between agent and graph:

  • Light Context Graph: The context graph provides minimal constraints, allowing the agent's identity, background, and natural behaviors to shine through prominently. The agent expresses its full personality and expertise within the service framework.

  • Dense Context Graph: The context graph overpowers the agent with extensive constraints, specific requirements, and detailed behavioral rules. The agent's personality becomes secondary to the graph's prescribed interactions.

The art of context graph design lies in calibrating this density to match the service requirements—using light graphs where agent expertise and personality enhance the user experience, and dense graphs where consistency, compliance, or safety require strict behavioral control.

Context Density Spectrum

AGENT IDENTITY EXPRESSION                          CONTEXT DEFINITION DOMINATES
|----------------------|----------------------|----------------------|
Minimal Context        Moderate Context      Dense Context         Override Context
(Agent-led)           (Collaborative)       (Context-driven)      (Context-only)
|----------------------|----------------------|----------------------|
Agent personality     Balanced interplay    Context requirements  Context procedure
Agent expertise       Guided by context     Context-specific      Context mandated
Agent intuition       Context-informed      Context priorities    Context control

Core Design Philosophy

The Density-Expression Relationship: The context graph's density determines how much the "stage direction" dominates versus how much the "actor's interpretation" shines through:

  • Light Context: Minimal stage direction—the agent's natural performance style and expertise drive the interaction

  • Dense Context: Detailed stage direction—the contextual requirements and service specifications dominate the agent's expression

Key Principle: Context graphs should be designed as incomplete frameworks that become complete and purposeful only when composed with an agent's identity and enhanced by dynamic behaviors. The framework should provide just enough contextual structure to deliver the intended service while preserving space for the agent to bring authentic expertise and personality to the user experience.

State Architecture & Implementation

Context Graph Schema Structure

Context graphs are implemented as ServiceHierarchicalStateMachine documents with the following core components:

{
    "service_hierarchical_state_machine_id": "ObjectId",
    "version": "int",
    "name": "string",
    "description": "string",
    "states": {
        "state_name": {
            "type": "action|decision|recall|annotation|reflection|side-effect",
            // State-specific fields
        }
    },
    "new_user_initial_state": "string",
    "returning_user_initial_state": "string", 
    "terminal_state": "string",
    "references": {
        "reference_name": ["ObjectId", "version_int"]
    },
    "global_intra_state_navigation_guidelines": ["string"],
    "global_action_guidelines": ["string"],
    "global_boundary_constraints": ["string"],
    "topology_description": "string"  // Contains all state names and exit conditions for current graph only
}

State Types and Visibility

The context graph state machine is composed of internal states (system-only operations) and external states (client-visible interactions):

Internal States (System Only)

DecisionState

Purpose: Internal routing states for conversation flow control that evaluate multiple contextual factors to determine optimal path forward.

Schema Fields:

{
    "type": "decision",
    "objective": "string",
    "decision_guidelines": ["string"],
    "exit_conditions": [
        {
            "description": "string", 
            "next_state": "string | [external_ref.state, return_state]"
        }
    ]
}

Key Characteristics: Decision states operate as passthrough mechanisms that must transition immediately to other states while remaining invisible to clients. They always operate with moderate to high context density for routing consistency, allowing agent intuition to influence evaluation within defined decision criteria. The agent's persona plays a significant role in influencing the decision logic used to evaluate conditions and select the next state.

RecallState

Purpose: Memory access and user model expansion through historical context retrieval.

Schema Fields:

{
    "type": "recall",
    "queries": ["string"] | null,
    "requested_information": "string" | null,
    "next_state": "string | [external_ref.state, return_state]"
}

Key Characteristics: Recall states function as passthrough mechanisms with automatic transition, supporting either predefined queries or dynamic query generation depending on the specific implementation needs. They provide guidance to expand user model information in targeted ways, with memory retrieval that goes beyond simple user model data to recontextualize historical information against the current user model. Context density varies significantly—light contexts allow agent discretion in query formulation, while dense contexts mandate specific queries. These states expand the user model by recontextualizing historical information and update working memory with retrieved information before transitioning to a single next state.

ReflectionState

Purpose: Strategic analysis placed at key decision points to generate clean deductions that anchor future interactions and guide conversation flow.

Schema Fields:

{
    "type": "reflection",
    "problem": "string",
    "word_limit": "int",
    "next_state": "string | [external_ref.state, return_state]"
}

Key Characteristics: Reflection states conduct internal analysis without client interaction, strategically positioned to anchor future interactions through identification of non-obvious patterns, connections, and strategic considerations. They produce clean, final deductions rather than random thoughts or reasoning traces, with output specifically designed to enrich context for subsequent agent actions. These states are constrained by word limits to ensure focused, actionable insights and transition to a single next state without exit conditions. Importantly, they don't always require reasoning models and can use standard analysis techniques.

Strategic Application:

Reflection states serve as "personal notes" that the agent takes but doesn't share with the client, creating contextual anchors that influence future reasoning and decision-making.

Example Use Case: After a user provides diagnostic information, a reflection state might analyze whether the provided information is internally consistent, identify signs of cognitive dissonance or potential deception, and surface patterns that weren't immediately obvious during the initial interaction.

The reflection output directly affects subsequent flow—if inconsistencies are detected, the agent might transition to collect additional information; if information appears reliable, it might proceed to diagnosis. This creates a strategic checkpoint that enriches the agent's understanding without exposing the analytical process to the client.

AnnotationState

Purpose: Internal conversation marking and progress tracking with multiple strategic applications for conversation flow management, external observability, and agent reasoning support.

Schema Fields:

{
    "type": "annotation",
    "inner_thought": "string",
    "next_state": "string | [external_ref.state, return_state]"
}

Key Characteristics: Annotation states operate with zero client visibility and immediate transitions, adding predetermined inner thoughts to the conversation log while maintaining purely organizational functionality with minimal impact on agent expression. These states automatically transition to a single next state without exit conditions.

Strategic Use Cases:

Boundary Marking: Essential for tracking boundaries between different interactions across states, particularly valuable when communication or actions are implicit and stage boundaries are difficult to distinguish.

Conceptual Grouping: Create logical wrappers around related state sequences to enhance agent internal reasoning. For example, in a simulated interview setup with three stages (persona → scenario → success criterion), annotation states can mark the beginning and end of this sequence, making it easier for the agent to recognize these stages as a cohesive unit.

Reflection Targeting: Enable targeted analysis by providing clear boundaries for reflection states. Using the interview example, a reflection state can analyze content between annotation wrappers (start/end) to design dynamic roleplay scenarios that fulfill the established conditions.

External Reference Landing Spots: Serve as designated return points when external state machines complete their execution and jump back to the parent state machine, providing clean re-entry semantics.

External Observability: Support system monitoring and metrics collection since all state transition information is emitted during conversations. When an annotation state is traversed, external systems can trigger metrics collection, analytics, or other observational processes based on the current session state.

SideEffectState

Purpose: External system interactions and event emission.

Schema Fields:

{
    "type": "side-effect",
    "next_state": "string | [external_ref.state, return_state]",
    "side_effect": {
        "type": "send-email|emit-event",
        // Type-specific fields
    }
}

Key Characteristics:

  • Performs external actions (email, events)

  • Passthrough with automatic transition

  • Can trigger system integrations

  • Single next state (no exit conditions)

External States (Client Visible)

ActionState

Purpose: Interactive states where the agent engages with clients through a two-phase optimization process.

Schema Fields:

{
    "type": "action",
    "objective": "string",
    "actions": ["string"],
    "intra_state_navigation_guidelines": ["string"],
    "action_guidelines": ["string"],
    "boundary_constraints": ["string"],
    "exit_conditions": [
        {
            "description": "string",
            "next_state": "string | [external_ref.state, return_state]"
        }
    ],
    "message_metadata": ["string"]
}

Key Characteristics:

  • Two-phase execution (action selection → client engagement)

  • Client-visible interactions

  • Primary interaction points where agent personality and expertise are expressed

  • Multiple exit conditions based on conversation flow

  • Can reference external state machines with return points

  • Context density determines balance between agent expression and contextual requirements

The Two-Phase Action State Optimization

Action states uniquely operate as two distinct optimization problems, each with different configurations and objectives:

Phase 1: Action Selection (Internal Reasoning)

Configuration Components:

  • Agent behavioral guidelines (partial configuration)

  • Role definition for internal reasoning

  • Service description and context

  • Topological awareness of available states and transitions

  • Dynamic behavior activation tracking

  • Interaction history framework

  • Current context information

  • State-specific objectives and available actions

  • Decision framework for evaluation

Optimization Goal: Select optimal action or transition based on current context

Phase 2: Client Engagement (Conversational Agent)

Configuration Components:

  • Complete agent identity and persona

  • Full behavioral and communication guidelines

  • Service context and purpose

  • Agent capabilities and constraints

  • Memory system access

  • User model maintenance

  • Dynamic behavior integration

  • Enhanced contextual awareness

  • Selected action execution guidelines

Prioritization Hierarchy:

  1. Action-specific guidelines (highest priority)

  2. Persona embodiment and behavioral guidelines

  3. Communication style and patterns

  4. Action progress tracking (lowest priority)

Optimization Goal: Generate natural conversational response that fulfills the selected action

Dynamic Behavior Injection

Dynamic behaviors modify state execution through instruction modification:

In Action States:

  • Can merge with or replace existing guidelines

  • Affects both action selection and client engagement phases

  • Tracked with unique identifiers per conversation

In Other States:

  • Behaviors provide contextual awareness

  • Influence decisions indirectly through agent understanding

Key Principles:

  • Multiple behaviors can be active during a session

  • One behavior triggered per interaction

  • All activations tracked in system logs

Interaction Logs Schema

The interaction logs provide the agent's complete internal view of the conversation, containing significantly more information than what clients see externally.

Agent's Internal View

Log Components Include:

  • State boundaries and transitions

  • Internal reasoning and annotations

  • Message content with metadata

  • Dynamic behavior activations

  • Memory operations

  • Timing information

  • Historical vs current state grouping

Key Internal Elements:

  • Complete state transition history

  • Agent internal reasoning traces

  • System metadata and tracking

  • Memory query-response pairs

  • State duration calculations

  • Message indexing for current state

Client's External View

Clients See Only:

  • Agent conversational messages

  • Client messages

  • Natural conversation flow

Hidden from Clients:

  • All state management information

  • Internal reasoning and decision-making

  • System annotations and metadata

  • Memory operations

  • Dynamic behavior activations

Context Density Factors

What makes a context "dense"?

  • Specificity of objectives - Vague vs precise goals

  • Number of constraints - Few vs many boundary conditions

  • Prescriptiveness of guidelines - Principles vs exact steps

  • Flexibility in exit conditions - Multiple paths vs single route

  • Detail in action definitions - High-level vs step-by-step

Abstract Topology Structure

Context graphs follow a hierarchical state machine topology with defined entry and exit points:

Entry Points:
START(new user) → [A] new_user_initial_state
START(returning user) → [A] returning_user_initial_state

State Flow Examples:
[A] action_state
  (condition 1) → [D] decision_state
  (condition 2) → [C] recall_state → [A] next_action
  (condition 3) → [R] reflection_state → [A] informed_action

[D] decision_state  
  (evaluation 1) → [A] path_a_action
  (evaluation 2) → [N] annotation_state → [A] path_b_action
  (evaluation 3) → [S] side_effect_state → [A] continuation

External References:
[A] local_state → [A] external_ref.entry_state [returns to local_return_state]
  - System maintains a stack of return points for nested state machine calls
  - When external state machine reaches terminal state, automatic jumpback occurs

Exit Point:
[A] terminal_state → END

State Type Abbreviations:

  • [A] Action State (client-visible)

  • [D] Decision State (internal routing)

  • [C] Recall State (memory access)

  • [N] aNnotation State (tracking)

  • [R] Reflection State (analysis)

  • [S] Side-effect State (external actions)

Topology Characteristics:

  • Entry differentiation: New vs returning users can start at different states

  • Branching logic: Action and Decision states support multiple exit paths

  • Linear flow: Recall, Annotation, Reflection, and Side-effect states have single transitions

  • External composition: States can reference other state machines with return points

  • Jumpback transitions: Automatic transitions when reaching terminal state of a referenced state machine

  • Terminal convergence: All paths eventually lead to a single terminal action state

Key Design Principle: The topology enables sophisticated conversation flows while maintaining clear entry/exit semantics and composability with other context graphs through external references.

Agent Traversal Model

Core Traversal Guarantees

The agent traversal system operates with fundamental guarantees that shape all conversation flows:

  1. Always Start and End on Action States: Every user interaction begins with an action state and must conclude with an action state response

  2. Arbitrary Internal Steps: Between action states, agents can traverse any number of internal states (decision, reflection, recall, annotation) to process and reason

  3. Single Response Point: The agent only generates client-visible responses in action states

  4. State Quantas: Each state itself can contain multiple micro-operations (like tool calls or memory queries)

Quantum Patterns of Interaction

Agent traversals are composed of "quantas" - fundamental patterns of state transitions that represent complete interaction units:

Basic Quantum Patterns

  1. Direct Action: [A] → [A] - Simple progression between action states

  2. Reflective Path: [A] → [R] → [A] - Action followed by reflection then informed action

  3. Decision Branch: [A] → [D] → [A] - Action leading to decision point then appropriate next action

  4. Memory-Enhanced: [A] → [C] → [A] - Action triggering memory recall then contextualized response

  5. Complex Chain: [A] → [D] → [R] → [A] - Multi-step internal processing before response

  6. Multi-Decision: [A] → [D] → [D] → [A] - Sequential decision evaluations

  7. Annotated Flow: [A] → [N] → [A] - Action with progress marking

  8. Side-Effect Chain: [A] → [S] → [A] - Action triggering external system interaction

Advanced Quantum Patterns

  • Deep Analysis: [A] → [C] → [R] → [D] → [A] - Memory recall informing reflection guiding decision

  • Marked Transition: [A] → [N] → [D] → [R] → [N] → [A] - Complex flow with boundary markers

  • External Reference: [A] → [external_ref.state] → [jumpback] → [A] - Nested state machine traversal

Key Principles

  • User Visibility: Only action states produce client-visible output

  • Internal Processing: All non-action states are internal agent reasoning

  • Flexible Composition: Quantas can be combined in any valid sequence

  • Contextual Adaptation: Agent selects appropriate quantum based on needs

Visual Representation:

User Message → [A] initial_action
                 ↓
              (internal processing quantum)
              [D] decision → [R] reflection
                               ↓
                          [A] informed_response → User sees response

The Three-Level Navigation Framework

Agent traversal through context graphs relies on three interconnected levels of information that provide comprehensive understanding:

1. Description (Conceptual Understanding)

  • Purpose: High-level natural language explanation of the service or domain

  • Content: Rich narrative describing the overall mission, approach philosophy, and service goals

  • Function: Gives agents conceptual grounding to understand the "why" behind their navigation

  • Example: "A therapeutic session initiates with professional rapport-building and, when indicated, a clinical review of homework assignments and therapeutic interventions from the previous session..."

2. Abstract Topology (Global Structural View)

  • Purpose: Bird's-eye view of all possible paths through the state machine

  • Content: Complete map showing state names, types, and transition conditions

  • Function: Enables agents to understand their position in the larger flow and plan strategic navigation

  • Format:

START(new user) -> [A] greeting
[A] greeting
  (User wants to learn) -> [A] education
  (User has health concern) -> [A] identify_presenting_complaint
  (Intent unclear) -> [A] determine_intent

3. Local Guidelines (Zoomed-In State Details)

  • Purpose: Specific operational instructions for the current state

  • Content: Objectives, actions, guidelines, boundary constraints, and exit conditions

  • Function: Provides detailed guidance for immediate decision-making and action selection

  • Components:

    • State objective

    • Available actions

    • Intra-state navigation guidelines

    • Action guidelines

    • Boundary constraints

    • Exit conditions with detailed descriptions

Understanding-Driven Navigation

The three-level model enables sophisticated navigation strategies:

For Non-Intuitive Transitions

  • Rely on Detailed Exit Conditions: Make exit condition descriptions rich and descriptive

  • Provide Clear Local Guidelines: Offer specific instructions in state guidelines

  • Use Dense Context: Apply tighter constraints to guide navigation

  • Document Edge Cases: Explicitly handle unusual transition scenarios

For Intuitive Navigation

  • Emphasize Conceptual Description: Let the service description carry more weight

  • Use Light Guidelines: Trust the agent's understanding of the domain

  • Create Natural Flow: Design transitions that align with conversational logic

  • Allow Agent Expertise: Let the agent's background and identity guide decisions

Example: Therapeutic Session Navigation

This production-grade therapeutic example demonstrates the three-level model in action:

Description Level: "A therapeutic session initiates with professional rapport-building... The therapist facilitates patient reflection on recent progress and systematically assesses contributing factors to symptom improvement..."

Topology Level:

[A] greeting
  (User has specific concern) -> [A] identify_presenting_complaint
  (Need to prioritize complaints) -> [R] reflection_planning
[R] reflection_planning -> [A] questions_consult
[A] questions_consult
  (Need more information) -> [A] follow_up_questions
  (Ready for diagnosis) -> [R] reflection_risk_stratification

Local Level (follow_up_questions state):

{
  "objective": "Ask targeted follow-up questions to increase diagnostic confidence",
  "actions": [
    "Ask specific questions based on differential diagnosis",
    "Clarify ambiguous symptoms",
    "Gather additional history"
  ],
  "action_guidelines": [
    "Connect questions back to original concerns",
    "Acknowledge patience with additional questions"
  ],
  "boundary_constraints": [
    "Don't ask unnecessary questions",
    "Stay focused on diagnostic clarity"
  ],
  "exit_conditions": [
    {
      "description": "Have gathered sufficient additional information",
      "next_state": "reflection_risk_stratification"
    }
  ]
}

This framework allows the agent to:

  1. Understand Context: Grasp the therapeutic session's purpose and flow

  2. See Position: Know where they are in the overall conversation

  3. Make Decisions: Select appropriate actions based on all three levels

  4. Plan Ahead: Anticipate future states and prepare accordingly

Designing for Quantum Traversal

When creating context graphs, consider how quantum patterns will emerge:

State Design Principles

  1. Entry/Exit Clarity: Every path must start and end with action states

  2. Internal Flexibility: Allow multiple internal state combinations

  3. Purpose Alignment: Each quantum should serve a clear conversational purpose

  4. Natural Transitions: Quantum patterns should feel conversationally appropriate

Common Design Patterns

  • Information Gathering: [A] question → [C] recall → [A] informed_question

  • Decision Making: [A] options → [D] evaluate → [A] recommendation

  • Problem Solving: [A] problem → [R] analyze → [D] strategize → [A] solution

  • Progress Tracking: [A] milestone → [N] mark_progress → [A] next_step

Performance Considerations

Quantum Efficiency

  • Minimize Hops: Use direct action-to-action when internal processing isn't needed

  • Batch Processing: Combine related internal states when possible

  • Early Decisions: Place decision states early to avoid unnecessary traversals

  • Strategic Recalls: Position memory queries before states that need historical context

State Machine Optimization

  • Shallow Hierarchies: Limit external reference depth to 3-4 levels

  • Clear Terminal Paths: Ensure all paths efficiently reach terminal states

  • Avoid Loops: Design exit conditions to prevent infinite traversal loops

  • Cache Considerations: Frequently accessed states should be lightweight

Best Practices for Three-Level Design

  1. Align All Levels: Ensure description, topology, and local guidelines tell a coherent story

  2. Balance Detail: Don't overload any single level - distribute guidance appropriately

  3. Consider Agent Capabilities: Design for agents that can truly understand and reason

  4. Enable Strategic Planning: Give agents enough global context to plan multi-step interactions

  5. Support Natural Conversation: Allow for fluid movement through the state space

  6. Document Quantum Patterns: Make common traversal patterns explicit in documentation

  7. Test Edge Cases: Verify unusual quantum combinations work as intended

The Power of Understanding-Based Navigation

This three-level model with quantum patterns transforms context graphs from rigid flowcharts into dynamic problem spaces where:

  • Agents navigate with true comprehension of their purpose

  • Complex multi-step reasoning happens invisibly to users

  • Transitions feel natural and conversationally appropriate

  • The same graph supports varied interaction styles based on user needs

  • Internal processing enriches responses without user awareness

Quick Reference Guide

State Type Summary

  • [A] Action: Client interaction (two-phase: selection → engagement)

  • [D] Decision: Internal routing based on conditions

  • [C] Recall: Memory query and retrieval

  • [N] Annotation: Progress marking and boundary tracking

  • [R] Reflection: Deep analysis and insight generation

  • [S] Side-effect: External system interactions

Quantum Pattern Quick Reference

Basic Patterns:
[A] → [A]                     Direct progression
[A] → [D] → [A]              Decision-based routing
[A] → [R] → [A]              Reflection-informed response
[A] → [C] → [A]              Memory-enhanced interaction

Complex Patterns:
[A] → [C] → [R] → [D] → [A]  Full analysis chain
[A] → [D] → [D] → [A]        Multi-criteria evaluation
[A] → [N] → [D] → [R] → [A]  Tracked complex flow

Navigation Levels At-a-Glance

  1. Description: WHY - Conceptual understanding of the service

  2. Topology: WHERE - Global map of all states and transitions

  3. Local: WHAT - Specific instructions for current state

Key Traversal Rules

  1. ✓ Always start on an action state

  2. ✓ Always end on an action state

  3. ✓ Only action states produce client output

  4. ✓ Internal states are invisible to clients

  5. ✓ Any valid quantum pattern is allowed

  6. ✓ Agents select quantas based on need

Final Notes

Context graphs are living frameworks that orchestrate the dance between agent identity and structural requirements. The art lies not in maximum control but in minimal viable constraint—creating just enough structure to ensure quality outcomes while preserving the authentic, intuitive presence that makes agents genuinely helpful.

PreviousAgent Identity & Background GuideNextDynamic Behaviors Guide

Last updated

Was this helpful?