Context Chains

Info

Last Updated: 2026-01-08

What are Context Chains?

Context Chains enable hierarchical context sharing between agents. A supervisor can delegate tasks to specialists while sharing relevant context—without giving full access to its memory space.

---

Quick Start

// Supervisor creates a context chain
const context = await cortex.contexts.create({
  purpose: "Process refund request #12345",
  memorySpaceId: "supervisor-space",
  userId: "user-123",
  data: { amount: 500, reason: "defective product" },
});

// Delegate to specialist
const childContext = await cortex.contexts.create({
  purpose: "Approve $500 refund",
  memorySpaceId: "finance-space",
  parentId: context.id,
  userId: "user-123",
});

// Specialist accesses full chain
const fullContext = await cortex.contexts.get(childContext.id, {
  includeChain: true,
});
// Sees: parent purpose, data, and full hierarchy

---

The Problem Context Chains Solve

Traditional Delegation

User Request

"Create a marketing campaign for Q4"

CEO Agent

"Let me delegate..."

Marketing Agent

Gets: "Create campaign" — Misses: Q4 timeframe, budget, audience

Finance Agent

Gets: "Review budget" — Misses: What the campaign is for

Information gets lost at each delegation level

Context Chain Delegation

User Request

"Create a marketing campaign for Q4"

CEO Agent

Creates context: CTX-001

Marketing Agent

Accesses CTX-001 — Sees: Complete request, budget, timeline

Finance Agent

Accesses CTX-001 — Sees: Same complete context

Everyone has the full picture via the chain

---

Context Chains vs A2A Communication

Context Chains	A2A Communication
Direction	Parent → Child (delegation)	Peer-to-peer (messaging)
Access Model	Read-only context sharing	Dual-write messages
Use Case	Task delegation, workflows	Agent collaboration
Data Flow	Hierarchical (tree)	Bidirectional
Best For	Supervisor → Specialist	Equals exchanging info

---

Creating a Context Chain

1

Create root context

const context = await cortex.contexts.create({
  purpose: "Process customer refund request",
  memorySpaceId: "supervisor-space",
  userId: "user-123",
  data: {
    importance: 85,
    tags: ["refund", "customer-service"],
    ticketId: "TICKET-456",
    amount: 500,
  },
});

2

Create child contexts (delegate)

// Delegate to finance
const financeCtx = await cortex.contexts.create({
  purpose: "Approve and process $500 refund",
  memorySpaceId: "finance-space",
  parentId: context.id,
  userId: "user-123",
});

// Delegate to customer relations
const customerCtx = await cortex.contexts.create({
  purpose: "Send apology email",
  memorySpaceId: "customer-space",
  parentId: context.id,
  userId: "user-123",
});

3

Specialist accesses full chain

const fullContext = await cortex.contexts.get(financeCtx.id, {
  includeChain: true,
});

console.log(fullContext.parent.purpose);  // "Process customer refund..."
console.log(fullContext.parent.data);     // { amount: 500, ... }
console.log(fullContext.siblings);        // [customerCtx]

---

Security Model

Read-Only by Default

Cross-space access via Context Chains is read-only. Specialists can read parent context but cannot modify supervisor data.

Audit Trail

All cross-space context reads are logged. Use includeChain: true queries to trace who accessed what.

---

Context Structure

Parameter	Type	Required	Default	Description
id	string	Yes	—	Unique context ID
purpose	string	Yes	—	What this context is for
memorySpaceId	string	Yes	—	Owning memory space
parentId	string	No	—	Parent context (if child)
rootId	string	No	—	Root of the chain
userId	string	No	—	User this relates to
depth	number	No	—	Hierarchy depth (0 = root)
childIds	string[]	No	—	Direct children IDs
status	string	No	active	'active', 'completed', 'cancelled', 'blocked'
data	object	No	—	Context-specific data (importance, tags, etc.)

---

Context Operations

// Get single context
const ctx = await cortex.contexts.get(contextId);

// Get with full chain
const fullCtx = await cortex.contexts.get(contextId, {
  includeChain: true,
});
// Returns: current, parent, root, siblings, children, depth

// Update status (auto-versioned)
await cortex.contexts.update(contextId, {
  status: "completed",
  completedAt: Date.now(),
  data: { result: "approved", approvedBy: "finance-agent" },
});

// Check version history
const ctx = await cortex.contexts.get(contextId);
console.log(`v${ctx.version}: ${ctx.status}`);

// Find active contexts for an agent
const active = await cortex.contexts.search({
  memorySpaceId: "finance-space",
  status: "active",
});

// Find high-priority contexts
const urgent = await cortex.contexts.search({
  data: { importance: { $gte: 80 } },
  status: "active",
});

// Find user's contexts
const userCtx = await cortex.contexts.search({
  userId: "user-123",
  sortBy: "createdAt",
  sortOrder: "desc",
});

// Delete single context
await cortex.contexts.delete(contextId);

// Bulk delete old cancelled contexts
await cortex.contexts.deleteMany({
  status: "cancelled",
  updatedBefore: Date.now() - 90 * 24 * 60 * 60 * 1000,
});

---

Common Patterns

Task Decomposition

// Break complex task into subtasks
const root = await cortex.contexts.create({
  purpose: "Build Q4 financial report",
  memorySpaceId: "ceo-space",
  data: { quarter: "Q4", deadline: "2025-12-31" },
});

await Promise.all([
  cortex.contexts.create({
    purpose: "Gather revenue data",
    memorySpaceId: "finance-space",
    parentId: root.id,
  }),
  cortex.contexts.create({
    purpose: "Compile expense reports",
    memorySpaceId: "accounting-space",
    parentId: root.id,
  }),
  cortex.contexts.create({
    purpose: "Create visualizations",
    memorySpaceId: "analytics-space",
    parentId: root.id,
  }),
]);

Approval Workflows

// Multi-step approval chain
const request = await cortex.contexts.create({
  purpose: "Approve $10K budget increase",
  memorySpaceId: "requestor-space",
  data: { amount: 10000, department: "engineering" },
});

const managerReview = await cortex.contexts.create({
  purpose: "Manager review",
  memorySpaceId: "manager-space",
  parentId: request.id,
});

const financeApproval = await cortex.contexts.create({
  purpose: "Finance approval",
  memorySpaceId: "finance-space",
  parentId: managerReview.id,
});

// Trace full approval chain
const chain = await cortex.contexts.get(financeApproval.id, {
  includeChain: true,
});

Link to Conversations

// Context originated from user conversation
const context = await cortex.contexts.create({
  purpose: "Process refund request",
  memorySpaceId: "supervisor-space",
  userId: "user-123",
  conversationRef: {
    conversationId: "conv-456",
    messageIds: ["msg-089"],  // Original request
  },
  data: { amount: 500 },
});

// Trace back to source
if (context.conversationRef) {
  const conv = await cortex.conversations.get(
    context.conversationRef.conversationId
  );
}

---

Best Practices

Descriptive Purposes

// Vague - hard to trace
await cortex.contexts.create({ purpose: "Process request" });

// Clear - full audit trail
await cortex.contexts.create({
  purpose: "Process $500 refund for defective product (ticket #456)",
  data: { importance: 85, tags: ["refund", "urgent"] },
});

Keep Status Current

// Update as work progresses
await cortex.contexts.update(id, { status: "active" });
// ... do work ...
await cortex.contexts.update(id, { 
  status: "completed",
  completedAt: Date.now(),
});

Clean Up Old Contexts

// Archive completed contexts after 90 days
await cortex.contexts.deleteMany({
  status: "completed",
  completedBefore: Date.now() - 90 * 24 * 60 * 60 * 1000,
});

---

Graph Visualization

Context Hierarchy Example

Root Context (ctx-001)

Purpose: "Process customer refund" | Status: active | Depth: 0

Child ctx-002

Purpose: "Approve refund" | Agent: finance-space | Status: completed

Child ctx-003

Purpose: "Send apology" | Agent: customer-space | Status: completed

Child ctx-004

Purpose: "Update CRM" | Agent: crm-space | Status: active

Graph Integration

For deep hierarchies (7+ levels), sync contexts to a graph database for faster queries. See Graph Integration.

---

Next Steps