State-Based Architecture

A context graph is a structured topological field of interconnected states that guides agent behavior and decision-making. Context graphs implement a hierarchical state machine (HSM) architecture, where states are organized in a structured hierarchy that enables efficient organization of complex problem spaces.

State Types

Each state type serves a specific purpose in managing conversation flow and agent behavior.

State Reference

Designing a State

Side-Effect states exist to produce effects outside the conversation loop. They hand off control to Actions and other tooling, ensuring that every external operation is versioned and auditable without overloading Action states with non-dialog responsibilities.

Each state definition should answer five questions before it ships to production:

1. Objective – What outcome must be true before the state can exit?

2. Guidance – Which ordered actions or prompts keep the model on the intended path?

3. Boundaries – Which behaviors are forbidden, especially for safety or compliance?

4. Exit criteria – What explicit signals trigger each transition, and which state should follow?

In the API schema this maps to action_tool_call_specs, exit_condition_tool_call_specs, and the skip_active_memory_retrieval flag for each state.

Action State Implementation Example

Each state type has its unique set of structured parameters and implementation best practices. For example, see below for a more detailed summary of the Action State.

Required Parameters

• type: Must be "action"

• objective: Clear statement of the state's goal

• actions: Ordered list of client-facing interaction steps

Optional Parameters

• action_tool_call_specs: Optional tool calls the agent may use while executing actions

• exit_condition_tool_call_specs: Tool calls available when evaluating exit conditions

• skip_active_memory_retrieval: Set to true when the state should not trigger active memory retrieval on entry

Example

Reasoning States and Abstract Topology

Reasoning states (which include Decision and Reflection states) play a critical role in the traversal of context graphs, acting as key nodes in the integrated Memory-Knowledge-Reasoning (M-K-R) process. They impact traversal by providing a local and global view of the problem space via an abstract topology. This abstract topological view:

1. Prevents Loops: Avoids repetitive cycles of states that don't make progress toward goals

2. Prevents Bad Traversals: Eliminates paths that don't properly consider the more global problem space view

3. Optimizes Transitions: Prevents both premature and late transitions to adjacent problem spaces even without perfect exit conditions

The abstract topology effectively provides a "map" of the entire problem space, allowing the agent to make informed decisions about where to go next based on both immediate context and the overall structure of the problem. This is similar to how a human expert would consider the current details of a situation and their broader understanding of the entire domain when making decisions.

Here's a simplified example of an abstract topology for a medical check-in flow:

This abstract topology provides a concise map of the problem space, showing key states and transitions. With this global view, the agent can make informed decisions about state traversal, ensuring that the conversation follows a coherent and purposeful path while avoiding problematic patterns like loops or premature transitions.

Multi-State Traversal: The Hidden Journey Between Action States

A fundamental aspect of context graphs is that agents can traverse multiple states internally before responding to users. The core guarantee: agents always start and end on action states, but the journey between them can involve sophisticated internal processing that remains invisible to users.

Core Traversal Principles

1. Action State Guarantee: Agents always start and end on action states

2. Arbitrary Steps: Agents can take an arbitrary number of internal steps before responding

3. Quantum Composition: Each state can be composed of smaller quantas of actions (like tool calls)

4. Internal Processing: Between action states, agents traverse internal states for reasoning, memory operations, and decision-making

Quantum Patterns

Each interaction is composed of quantas of patterns - fundamental units of state transitions:

Basic Quantas:

• action → action - Direct response

• action → decision → reflection → action - Thoughtful evaluation

• action → action → action - Multi-step direct engagement

Complex Quantas:

Traversal Patterns

Each interaction follows patterns like:

• [A] action → [A] action - Direct transition

• [A] action → [D] decision → [R] reflection → [A] action - Thoughtful evaluation

• [A] action → [R] reflection → [D] decision → [A] action - Analysis before routing

These patterns represent "quanta" of agent behavior - fundamental units of processing that compose into complex interactions.

Three Levels of Navigation Intelligence

Agents navigate using three complementary information levels that provide both global and local perspectives:

1. Conceptual Level (Description)

   • The "why" - service philosophy and methodology

   • Sparse, conceptual global view of the entire service

   • Provides understanding of overall purpose and approach

This multi-resolution approach is powerful because it gives agents both the "forest and the trees" - they can see the big picture through sparse conceptual and structural views while having dense, detailed guidance for local execution. This enables intelligent navigation that balances global strategy with local precision.

Example: Hidden Therapeutic Processing

User: "I feel like I'm not making progress in therapy"

Internal traversal:

1. [A] get_therapeutic_agreement_get_focus - Acknowledges concern about therapy progress

2. [C] recall - Retrieves past session goals, breakthroughs, and patterns

3. [R] reflect_on_therapeutic_agreement - Analyzes the gap between expectations and experience

User experience: The therapist responds with deep understanding of their therapeutic journey, acknowledging past work while exploring their current feelings, all without revealing the complex internal analysis.

Navigation Strategies

For Non-Intuitive Transitions: When jumps might surprise users

• Highly detailed exit conditions

• Explicit descriptions of when/why transitions occur

• Clear documentation of edge cases

For Intuitive Navigation: When flow should feel natural

• Rich conceptual descriptions

• Lighter transition guidelines

• Agent discretion based on context

Implementation Considerations

1. Context Density Calibration (Entropy Control in Practice):

   • High-density (Low Entropy): "Verify all required regulatory compliance elements while maintaining strict protocol adherence"

   • Medium-density (Medium Entropy): "Engage the client on their current query while handling natural topic changes within conversation flow"