​

Core Concepts Overview

​

The Five Pillars

​

1. PACT Architecture

• Position components at precise coordinates like (0,1,0) or (d2, 1, -3)
• Adapt automatically as conversation history grows through ODI (Overlap Demotion Invariant)
• Tree structure enables infinite addressability and hierarchical organization

# Insert a component at a specific position
context.pact_insert("d0, 1, 0", component)

# Components automatically adapt as history grows
# (0,1,0) → (1,1,0) → (2,1,0) as messages are added

​

2. Context Management

• Permanent (ttl=None) - Never expire, most common for message content
• Temporary (ttl=N) - Expire after N turns, gone forever
• Sticky (ttl=1, cadence=1) - Follow their parent through ODI movements
• Cyclic (ttl=N, cadence=M) - Expire and reappear on a schedule

# Create a temporary reminder that lasts 3 turns
reminder = TextContent(
    content="Remember to check user preferences",
    ttl=3
)
context.pact_insert("d0, 1, 0", reminder)

​

3. Messaging System

# Messages are automatically formatted for any provider
thread = agent.thread.current

# Access different message types
system_msg = thread.system_header
responses = thread.provider_responses
requests = thread.client_requests

​

4. Provider System

# Works identically across all providers
agent = Agent(provider="openai:gpt-4")
agent = Agent(provider="anthropic:claude-3-5-sonnet-20241022")
agent = Agent(provider="google:gemini-pro")

# All support the same interface
response = agent.call("Hello!")
async for chunk in agent.stream("Tell me a story"):
    print(chunk, end="")

• Universal token counting across all providers
• OAuth interceptors for premium models (GPT-5, Claude, etc.)
• 3-tier parameter merging (defaults < model_config < kwargs)

​

5. Agent System

from egregore import Agent

# Create an agent with automatic context management
agent = Agent(
    provider="openai:gpt-4",
    system_prompt="You are a helpful assistant"
)

# Context is automatically maintained across calls
agent.call("What's the weather?")
agent.call("What did I just ask you?")  # Agent remembers

# Access the underlying systems
agent.context      # Context tree
agent.hooks        # Hook system
agent.scaffolds    # Persistent memory
agent.history      # Snapshot access

​

Advanced Systems

​

MessageScheduler

• Advances context episodes (turns) automatically
• Processes TTL expirations and lifecycle transitions
• Manages the render lifecycle for dynamic components
• Coordinates ODI depth shifting

​

ContextHistory

• Create snapshots at any point in conversation
• Access historical context states by episode number
• PACT-compliant serialization for persistence
• Query components using PACT selectors across snapshots

# Create a snapshot
snapshot_id = agent.context.seal(trigger="before_tool_call")

# Access historical state
historical_context = agent.history.at_snapshot(snapshot_id)
component = historical_context["d0, 1, 0"]

​

How It All Fits Together

​

Typical Flow

1. User sends message → Agent receives via messaging system
2. MessageScheduler → Advances episode, processes TTL expirations
3. Context updates → Message added to PACT tree at d0,0,0
4. ODI triggers → Previous messages shift to d1,0,0, d2,0,0, etc.
5. Hooks fire → Observe or modify context changes
6. Scaffolds render → Update persistent memory based on changes
7. Provider call → Formatted message sent to AI model
8. Response processed → Added to context, cycle repeats

​

What’s Next?