PACT Architecture

PACT (Positioned Adaptive Context Tree) is the foundational architecture that powers Egregore’s context management system. Think of it as a DOM for AI context - allowing you to precisely position, manipulate, and automatically adapt memory components as conversations evolve.

The Problem PACT Solves

Traditional chat-based AI systems treat context as a flat append-only log:

# Traditional approach - inefficient
conversation = [
    {"role": "user", "content": "What's the weather?"},
    {"role": "assistant", "content": "I don't have access to weather data."},
    {"role": "user", "content": "What did I just ask?"},
    # LLM has to re-read EVERYTHING each time
]

This creates several problems:

No addressability: Can’t reference or modify specific parts of context
Inefficient: LLM re-processes entire history every turn
No structure: Flat lists don’t represent hierarchical relationships
Limited control: Can’t expire, move, or manage individual pieces

PACT solves this with a tree structure and coordinate system.

The Three Pillars

1. Positioned

Every component has precise coordinates in 3D space:

# PACT coordinates: (depth, position, offset)
(0, 0, 0)    # Current message core
(0, 1, 0)    # Component attached to current message
(1, 0, 0)    # Previous message core
(1, 1, -2)   # Component at historical message, offset -2

Coordinates enable infinite addressability - you can reference any component precisely, just like DOM elements with IDs or CSS selectors.

2. Adaptive

Components automatically adjust positions as conversation grows through ODI (Overlap Demotion Invariant):

# Turn 1: Add a reminder
context.pact_insert("d0, 1, 0", reminder)  # At current message

# Turn 2: User sends new message
# → ODI automatically shifts reminder from (0,1,0) to (1,1,0)
# → Your code doesn't need to manually track positions!

3. Context Tree

Hierarchical organization mirrors DOM structure:

Context Tree
├── System (-1)
│   └── System instructions
├── Active Message (0)
│   ├── Core (0,0,0) - Current user/assistant message
│   ├── Component (0,1,0) - Attached metadata
│   └── Component (0,1,1) - Additional annotations
├── Previous Message (1)
│   ├── Core (1,0,0)
│   └── Components (1,1,*)
└── Historical Messages (2, 3, 4...)

PACT Coordinate System

Understanding Coordinates

PACT uses tuple coordinates with three dimensions:

(depth, position, offset)
   │       │        │
   │       │        └─ Relative positioning within container
   │       └────────── Attachment point (0=message, 1+=components)
   └────────────────── Conversation turn (0=current, 1+=history)

Depth: Conversation Timeline

-1: System level (static, never moves)
0: Current active message
1, 2, 3…: Historical messages (pushed back by ODI)

# Depth examples
context["d-1, 0, 0"]  # System instructions
context["d0, 0, 0"]   # Current message
context["d1, 0, 0"]   # Previous message
context["d5, 0, 0"]   # 5 messages ago

Position: Attachment Points

0: Message core content (user/assistant text)
1+: Components attached to the message
1-: Alternative component attachment (negative positions)

# Position examples
context["d0, 0, 0"]   # Current message content
context["d0, 1, 0"]   # Component #1 attached to current message
context["d0, 2, 0"]   # Component #2 attached to current message

Offset: Fine-Grained Placement

Relative positioning within a container:

0: Core/canvas position (always exists)
1, 2, 3…: Positive offsets
-1, -2, -3…: Negative offsets

# Offset examples
context["d0, 0, 0"]    # Core message
context["d0, 0, 1"]    # Offset +1 from core
context["d0, 0, -1"]   # Offset -1 from core
context["d0, 1, -2"]   # Component at offset -2

ODI: Overlap Demotion Invariant

The Magic of Automatic Adaptation ODI is the system that automatically shifts components as conversations grow, maintaining their relative positions.

How ODI Works

When a new message is added:

Current message (0,0,0) becomes historical (1,0,0)
All permanent/sticky components increment depth by 1
New message takes position (0,0,0)

# Turn 1: Add a note
note = TextContent("User prefers formal tone")
context.pact_insert("d0, 1, 0", note)

# State: note is at (0,1,0) - attached to current message

# Turn 2: User sends "Hello"
agent.call("Hello")

# ODI triggers:
# - note moves from (0,1,0) → (1,1,0)
# - "Hello" message is now at (0,0,0)
# - note still attached to same message, just deeper in history

ODI Rules

What triggers ODI?

ODI triggers when message count changes between turns:

Length increase → increment depths
Length decrease → decrement depths
Length same → no ODI processing

What components participate in ODI?

Permanent components (ttl=None)
Sticky components (ttl=1, cadence=1)
Components at depths ≥ 0

Excluded from ODI:

System depth (-1) - always static
Temporary/cyclic components (they expire instead)

Does ODI affect offset?

No! ODI only changes depth, never position or offset. This preserves relative positioning within messages.

# Before ODI: (0, 1, -2)
# After ODI:  (1, 1, -2)  ← Only depth changed

ODI Example: Multi-Turn Conversation

from egregore import Agent
from egregore.core.context_management.pact.components import TextContent

agent = Agent(provider="openai:gpt-4")

# Turn 1: Add metadata
metadata = TextContent("Important context")
agent.context.pact_insert("d0, 1, 0", metadata)
# Position: (0, 1, 0)

# Turn 2: User message
agent.call("Hello")
# ODI triggers → metadata moves to (1, 1, 0)

# Turn 3: Another message
agent.call("How are you?")
# ODI triggers → metadata moves to (2, 1, 0)

# Metadata stays attached to its original message
# as that message moves deeper into history

PACT Selectors

CSS-like syntax for querying context components:

# Get component by coordinates
component = context["d0, 1, 0"]

# Using selector strings
component = context.select("d0, 1, 0")

# Range queries
components = context.select("d1-3, 1, *")  # All components at depths 1-3, position 1

Learn More

Complete PACT selector syntax reference

Message vs Component Positioning

Message Structure (`dN,0`)

Message core content - permanent by default:

# Messages live at position 0
context["d0, 0, 0"]  # Current message
context["d1, 0, 0"]  # Previous message
context["d2, 0, 0"]  # 2 messages ago

Characteristics:

No TTL by default (permanent)
Automatically managed by MessageScheduler
Participate in ODI depth shifting

Component Structure (`dN,1+`)

Components attached to messages - MAY have TTL:

# Components at position 1+
context["d0, 1, 0"]   # Component attached to current message
context["d0, 2, 0"]   # Another component
context["d1, 1, -1"]  # Component at historical message, offset -1

Characteristics:

Most are permanent (participate in ODI)
Can have TTL for automatic expiration
Can use render lifecycle for dynamic positioning

Core Offset Layout Rule

Offset 0 is special - the core/canvas position that always exists:

# Offset 0 = core/canvas
context["d0, 0, 0"]  # Message core - always exists even if empty

# Other offsets: -1, 1, -2, 2, etc.
context["d0, 0, 1"]   # Offset +1
context["d0, 0, -1"]  # Offset -1
context["d0, 0, -2"]  # Offset -2

Deleting core (offset 0) may trigger container reorganization. If it empties the container, the entire container may cease to exist.

PACT v0.1 Canonical Compliance

All Context components inherit from PACTNode with canonical fields:

class PACTNode(BaseModel):
    id: str                    # Unique identifier
    parent_id: Optional[str]   # Parent node ID
    offset: int                # Relative offset
    ttl: Optional[int]         # Time-to-live (None = permanent)
    cad: Optional[int]         # Rehydration cadence
    created_at_ns: int         # Creation timestamp (nanoseconds)
    creation_index: int        # Order of creation
    key: Optional[str]         # Optional key for lookup
    tags: List[str]            # Metadata tags
    content: Any               # Component content

Automatic Serialization

# Components serialize to PACT-compliant format
component_dict = component.model_dump()

# Context serializes entire tree
context_dict = context.model_dump()

# ContextHistory preserves PACT compliance
snapshot = agent.context.seal(trigger="checkpoint")
# Snapshot is fully PACT v0.1 compliant

Best Practices

Use Descriptive Keys

component = TextContent(
    content="User preferences",
    key="user_prefs"
)

Leverage Tags

component = TextContent(
    content="Metadata",
    tags=["metadata", "user", "important"]
)

3-Coordinate Selectors

# Use full coordinates
context.pact_insert("d0, 0, 1", component)
# Not: context.pact_insert("d0, 1", component)

Trust ODI

# Don't manually track positions
# ODI handles it automatically
# Just reference by relative coordinates

Common Patterns

Adding Persistent Metadata

# Attach metadata that follows the message
metadata = TextContent(
    content="User from California",
    key="location_metadata"
)
context.pact_insert("d0, 1, 0", metadata)

# Metadata automatically moves with its message through ODI

System-Level Instructions

# System depth (-1) never participates in ODI
system_note = TextContent(
    content="Always be concise",
    key="concise_instruction"
)
context.pact_insert("d-1, 1, 0", system_note)

# Stays at depth -1 forever

Temporary Reminders

# Expires after 3 turns
reminder = TextContent(
    content="Ask about follow-up in 3 turns",
    ttl=3
)
context.pact_insert("d0, 1, 0", reminder)

What’s Next?

Context Management

Learn about context operations and component lifecycles

Message Scheduler

Understand episode management and ODI processing

PACT Selectors

Master selector syntax for querying components

Architecture Deep Dive

Full PACT specification and internals

​PACT Architecture

​The Problem PACT Solves

​The Three Pillars

​1. Positioned

​2. Adaptive

​3. Context Tree

​PACT Coordinate System

​Understanding Coordinates

​Depth: Conversation Timeline

​Position: Attachment Points

​Offset: Fine-Grained Placement

​ODI: Overlap Demotion Invariant

​How ODI Works

​ODI Rules

​ODI Example: Multi-Turn Conversation

​PACT Selectors

Learn More

​Message vs Component Positioning

​Message Structure (dN,0)

​Component Structure (dN,1+)

​Core Offset Layout Rule

​PACT v0.1 Canonical Compliance

​Automatic Serialization

​Best Practices

Use Descriptive Keys

Leverage Tags

3-Coordinate Selectors

Trust ODI

​Common Patterns

​Adding Persistent Metadata

​System-Level Instructions

​Temporary Reminders

​What’s Next?

Context Management

Message Scheduler

PACT Selectors

Architecture Deep Dive

PACT Architecture

The Problem PACT Solves

The Three Pillars

1. Positioned

2. Adaptive

3. Context Tree

PACT Coordinate System

Understanding Coordinates

Depth: Conversation Timeline

Position: Attachment Points

Offset: Fine-Grained Placement

ODI: Overlap Demotion Invariant

How ODI Works

ODI Rules

ODI Example: Multi-Turn Conversation

PACT Selectors

Message vs Component Positioning

Message Structure (`dN,0`)

Component Structure (`dN,1+`)

Core Offset Layout Rule

PACT v0.1 Canonical Compliance

Automatic Serialization

Best Practices

Common Patterns

Adding Persistent Metadata

System-Level Instructions

Temporary Reminders

What’s Next?