Colony Context Engine

Document Metadata

---

1. Purpose and Scope

This document defines how Colony manages AI context across its multi-agent runtime. Colony is not a single-model application — it is an orchestrated stack of specialist agents, each requiring coherent, scoped, and verifiable context to execute GTM workflows reliably. This document answers three questions for every engineering and product decision involving LLMs:

1. What does each agent know when it starts, and where did that knowledge come from?
2. How does knowledge accumulate and persist across sessions, users, and agent handoffs?
3. How is context density optimized so that every LLM token budget is spent on signal, not noise?

---

2. Domain Profile

2.1 Product Domain

Colony operates in the B2B go-to-market automation domain for ZoomProp, a proptech product targeting healthcare organizations. The GTM motion combines outbound prospecting, deal pipeline management, call intelligence, and post-sale onboarding — all orchestrated through a conversational command interface at /overview.

2.2 Key Entities

2.3 Domain Terminology

2.4 Constraints

---

3. Context Architecture

3.1 Structural Overview

Colony's context architecture has four layers, each with a distinct persistence model and retrieval mechanism:

┌─────────────────────────────────────────────────────────────────┐
│  LAYER 4 — Ephemeral / In-Flight                                │
│  SSE stream state · tool-call buffers · Inngest step variables  │
└──────────────────────────┬──────────────────────────────────────┘
                           │ hydrates
┌──────────────────────────▼──────────────────────────────────────┐
│  LAYER 3 — Session Context                                      │
│  Chat turn history · approval-queue state · active campaign run │
│  Stored: Postgres `chat_sessions`, `campaign_runs`              │
└──────────────────────────┬──────────────────────────────────────┘
                           │ augments
┌──────────────────────────▼──────────────────────────────────────┐
│  LAYER 2 — Org Context                                          │
│  ICP definition · sequence library · deal state · recordings   │
│  Stored: Postgres relational tables (per-org row isolation)     │
└──────────────────────────┬──────────────────────────────────────┘
                           │ grounds
┌──────────────────────────▼──────────────────────────────────────┐
│  LAYER 1 — Knowledge Core (Semantic / Persistent)               │
│  10-domain pgvector store · exemplar messages · case studies    │
│  Retrieved: cosine similarity search, top-k per domain          │
└─────────────────────────────────────────────────────────────────┘

3.2 Knowledge Core — The Semantic Foundation

The Knowledge Core is Colony's single source of truth for grounding LLM outputs. It is a pgvector-backed store (Cloud SQL Postgres 16, instance colony-39989:…:colony, extension pgvector at 1536 dimensions) partitioned into 10 domain buckets.

Every message, content piece, and brief generation first queries the Knowledge Core with a cosine similarity search and prepends the top-k exemplars into the LLM prompt. This is the primary mechanism for style and domain consistency.

10 Knowledge Core domains (from docs/phase1/action_plans/24_knowledge_core_editor.md):

Notion sync (docs/phase2/action_plans/15_notion_kc_sync.md) keeps KC-01 through KC-07 current with human-maintained knowledge documents, propagating updates through a webhook-triggered re-embedding pipeline.

3.3 Postgres Schema as Context Store

The relational schema serves as the structured context store for all non-semantic data. Key context-carrying tables:

3.4 GCS as Binary Context Store

Large artifacts that exceed Postgres row limits or require signed-URL delivery are stored in gs://colony-assets (CMEK-encrypted, infrastructure/gcp/storage.tf). These include:

• Deployment Kit documents (pitch deck PDFs, rollout calendar exports)
• Playwright scraper screenshots and session artifacts (runners/.artifacts/)
• Recording audio/video files prior to Gemini transcription

Agents receive signed URLs to these artifacts rather than raw content, keeping prompt payloads lean.

---

4. Agent Context Protocols

4.1 Agent Inventory and Context Scope

Each specialist agent receives a context bundle assembled by the orchestrator before invocation. The bundle follows a consistent structure:

AgentContextBundle {
  org_id: string                    // Clerk org ID — always present
  run_id: string                    // Inngest run ID — for trace correlation
  agent_role: AgentRoleEnum         // Typed role constant
  system_prompt: string             // Role-specific system instructions
  knowledge_core_exemplars: Array   // Top-k semantic retrievals
  org_context: OrgContext           // ICP def, sequence library, deal stage
  task_payload: Record<string, any> // Agent-specific inputs
  tool_definitions: ToolDefinition[]// Available tools for this invocation
}

4.2 Orchestrator Context Protocol

The GTM Orchestrator (AGT-001) is the primary entry point at /overview. It manages multi-turn context using a rolling window over chat_sessions:

1. Turn ingestion — Each user message appends to chat_sessions with role: user.
2. Context hydration — Before each LLM call, the orchestrator loads: (a) the most recent N turns from chat_sessions; (b) today's daily_brief as a system-level summary; (c) active approval_queue items as injected tool-state context; (d) top-3 KC retrievals relevant to the user's intent.
3. Tool dispatch — When a tool call is selected, the orchestrator serializes the tool invocation to campaign_runs via Inngest, then streams the tool output back into the chat context window as an assistant message.
4. Approval gates — When a downstream agent produces an item requiring human approval, the orchestrator pauses the turn, writes to approval_queue, and presents the pending item to the user inline in the stream.

4.3 Inngest as Context Checkpoint Engine

Inngest (docs/phase1/action_plans/04_inngest_agent_runtime.md) provides durable execution that functions as an implicit context persistence layer:

• Each Inngest step function receives its inputs as serialized JSON, which constitutes the agent's full context for that step.
• Step outputs are automatically persisted, enabling agents to resume after circuit-breaker pauses (CONST-005) without recomputing prior steps.
• The campaign_runs table records which Inngest run ID corresponds to which campaign state, allowing the GTM Orchestrator to re-attach context after an interruption.

4.4 Cross-Agent Context Handoff Pattern

When the Campaign Orchestrator (AGT-002) delegates to a specialist agent, it packages a handoff envelope:

HandoffEnvelope {
  parent_run_id: string     // AGT-002's Inngest run ID
  downstream_agent: string  // e.g. "message-generator"
  entity_ids: string[]      // IDs of contacts/deals/recordings in scope
  angle: OutboundAngle      // Signal | Pain | Referral | PatternBreak | Insight
  tier: SequenceTier        // T1 | T2 | T3 | T4 | T5
  kc_bucket_hints: string[] // Which KC domains to prioritize in retrieval
}

The receiving agent uses entity_ids to hydrate structured context from Postgres and kc_bucket_hints to focus its Knowledge Core retrieval, avoiding full-corpus searches that dilute context density.

---

5. Prompt Engineering Patterns

5.1 System Prompt Architecture

Every agent system prompt follows a four-section template:

[ROLE DECLARATION]
You are the {agent_name} for ZoomProp's GTM stack. Your sole responsibility 
is {primary_task}.

[DOMAIN GROUNDING]
ZoomProp sells {product_description} to healthcare organizations matching 
the following ICP: {icp_definition}. The following are ANTI-ICP conditions 
that disqualify a prospect regardless of other signals: {anti_icp_list}.

[BEHAVIORAL CONSTRAINTS]
- Never generate content for a contact whose org_id differs from {org_id}.
- Do not fabricate company facts; use only data present in the context below.
- If a required field is absent, emit a structured "missing_data" tool call 
  rather than hallucinating a value.

[CONTEXT BLOCK]
{dynamic_context: knowledge_core_exemplars + entity_data + task_payload}

This template enforces: (1) role clarity, (2) domain grounding via ICP/Anti-ICP constraints, (3) behavioral guardrails against hallucination, and (4) a clearly delimited dynamic context section that changes per invocation.

5.2 Outbound Message Generation Pattern (AGT-005)

The Message Generator uses a constraint-first, exemplar-guided pattern optimized for the 5 outbound angles:

SYSTEM:
You are the Message Generator for ZoomProp outbound sequences.
Angle: {angle}  |  Tier: {tier}  |  Sequence step: {step_number}

EXEMPLARS (KC-08, top-3 for this angle):
---
{exemplar_1}
---
{exemplar_2}
---
{exemplar_3}
---

CONTACT PROFILE:
Name: {contact.name} | Title: {contact.title} | Org: {contact.org_name}
Signal context: {contact.enrichment.signals}
ICP score: {contact.icp_score}

CONSTRAINTS:
- Maximum 3 sentences for T1/T2. Up to 5 sentences for T3-T5.
- No subject line longer than 8 words.
- Do not mention competitors by name.
- Reference exactly one signal from the contact profile.

OUTPUT FORMAT:
{ "subject": "...", "body": "...", "angle_used": "...", "signal_referenced": "..." }

The structured JSON output format is critical: it routes the message to approval_queue with machine-readable metadata (angle, signal referenced) that the orchestrator uses to present approval UI and log analytics.

5.3 Recording Intelligence Extraction Pattern (AGT-006)

The Recording Intelligence agent processes Gemini Meet Notes transcripts. Because transcripts can be long, it uses a two-pass extraction pattern:

Pass 1 — Signal Detection (focused, short context):

Given the following meeting transcript segment, identify any of these 
signal types: [budget_signals, timeline_signals, stakeholder_signals, 
objection_signals, competitor_mentions, product_gaps]. 
Output as a structured JSON array with type, quote, and confidence score.

TRANSCRIPT SEGMENT:
{chunk}

Pass 2 — Summary and CRM Field Mapping (full signal set):

Given the following extracted signals from a sales call, generate:
1. A 3-sentence executive summary suitable for the deal record.
2. Recommended CRM field updates (deal stage, next action, close date).
3. Any Knowledge Core entries to update (specify KC domain and content).

SIGNALS:
{aggregated_signals_from_pass_1}

DEAL CONTEXT:
{deal.current_stage} | {deal.value} | {deal.next_action}

This two-pass approach prevents transcript length from overwhelming the context window while ensuring fine-grained signal detection.

5.4 ICP Qualification Scoring Pattern (AGT-004)

The Qualification Agent uses a rubric-anchored scoring pattern to produce deterministic, auditable ICP scores:

Score this prospect against ZoomProp's ICP. Return a JSON object with:
- total_score: integer 0-100
- dimension_scores: { size: int, vertical: int, tech_stack: int, 
                      signals: int, timing: int }
- disqualifiers: string[] (any Anti-ICP matches — auto-score 0)
- recommendation: "qualify" | "hold" | "disqualify"
- reasoning: string (max 2 sentences)

ICP RUBRIC:
{icp_rubric_from_kc_02}

ANTI-ICP CONDITIONS:
{anti_icp_list}

PROSPECT DATA:
{candidate.enrichment_payload}

Disqualifiers short-circuit scoring to 0 (CONST-002), preventing any LLM tokens from being spent on ineligible prospects beyond the classification step.

5.5 Daily Brief Synthesis Pattern (AGT-010)

The Analytics Agent generates the morning brief using an aggregation-then-narrative pattern:

SYSTEM:
You are the Analytics Agent. Synthesize a daily GTM brief for the 
ZoomProp founders. Be direct and data-driven. No filler sentences.

DATA SNAPSHOT (generated by SQL aggregations, not LLM):
Pipeline today: {deals_by_stage_json}
Queue: {approval_queue_count} items pending
Yesterday's output: {messages_sent}, {content_pieces_published}
Alerts: {circuit_breaker_status}, {bounce_rate}, {reply_rate}

YESTERDAY'S BRIEF (for continuity):
{prior_brief.summary}

OUTPUT:
Generate a brief with sections: Pipeline, Alerts, Queue, Yesterday, 
Today's Priorities. Max 250 words total.

The prior brief is injected for continuity — the Analytics Agent can reference trend direction ("bounce rate is down for the third consecutive day") without requiring access to a full historical database query in the prompt.

---

6. Memory Management

6.1 Cross-Session Persistence Model

Colony uses a tiered persistence model that matches information longevity to storage medium:

6.2 Context Window Management

Colony's agents are invoked within bounded context windows. The orchestrator enforces a budget allocation policy per agent type:

These allocations are enforced by the context assembly layer before the LLM call. If entity data exceeds its budget, non-essential fields (e.g., raw enrichment HTML, full transcript text) are truncated in favor of structured signal fields.

6.3 Conversation Summarization Strategy

When chat_sessions exceeds the rolling window token budget, the GTM Orchestrator applies a structured summarization pass before compressing old turns:

Summarize the following conversation turns into a compact context block 
that preserves: (1) decisions made, (2) entities referenced by ID, 
(3) pending items not yet resolved, (4) user preferences expressed.
Discard pleasantries and redundant elaborations.
Max 300 tokens.

TURNS TO COMPRESS:
{old_turns}

The compressed summary is stored back to chat_sessions as a special role: summary entry, replacing the original turns. This ensures the GTM Orchestrator always has a coherent conversation history without unbounded growth.

6.4 Knowledge Core Update Lifecycle

When a Recording Intelligence or Post-Call Agent surfaces new domain knowledge (e.g., a novel objection or a case study data point), the update lifecycle is:

1. Agent emits a kc_update_candidate with domain, content, and confidence.
2. Update enters the approval_queue for human review (matching the human-in-the-loop pattern for all LLM-generated content).
3. On approval, the content is embedded via the re-embedding pipeline and upserted into knowledge_core with the appropriate domain bucket and org scope.
4. All future agent invocations immediately benefit from the updated exemplar pool.

Notion sync (docs/phase2/action_plans/15_notion_kc_sync.md) provides an alternative ingest path for human-authored knowledge updates, triggering the same re-embedding step via webhook.

---

7. Context Density Strategies

Context density is the ratio of decision-relevant signal to total tokens in an LLM prompt. Colony applies seven strategies to maximize this ratio:

7.1 Anti-ICP Hard Pre-Filter

Documented in docs/phase2/action_plans/16_anti_icp_hard_prefilter.md. Before any LLM is invoked for qualification or message generation, a deterministic SQL/rule-based filter eliminates prospects matching Anti-ICP conditions. This means zero LLM tokens are spent on ineligible contacts — the highest-ROI context density optimization in the stack.

7.2 KC Bucket Hints

Agents receive kc_bucket_hints in their handoff envelope (§4.4), directing semantic search to specific Knowledge Core domains rather than full-corpus search. A message generator working on a pain-led angle queries KC-08 (outbound exemplars) and KC-04 (objections) only — not KC-10 (onboarding playbooks), which would dilute retrieval quality.

7.3 Compact JSON Entity Serialization

Structured entity data (contacts, deals, recordings) is serialized into a compact, field-selected JSON format rather than full ORM output. Non-LLM-relevant fields (internal IDs beyond org_id/entity_id, timestamps, audit columns) are stripped before context assembly.

7.4 Two-Pass Extraction for Long Inputs

For recordings and long documents, the two-pass pattern (§5.3) ensures no single LLM call receives a full transcript. Chunked signal extraction followed by signal aggregation keeps each pass focused and within a dense context window.

7.5 Structured Output Contracts

All agents output structured JSON rather than free prose (except the Daily Brief narrative and post-call summaries). Structured outputs allow downstream agents to consume specific fields without re-parsing natural language, preventing error accumulation across the agent chain.

7.6 Daily Brief as Session Priming Document

Each morning's daily_brief is injected into the GTM Orchestrator's system context at session start. This means the orchestrator begins each conversation with a compressed, high-signal snapshot of organizational state — pipeline, alerts, queue, recent output — without the user needing to re-establish context.

7.7 Exemplar-Guided Generation

Knowledge Core exemplars provide the LLM with concrete, org-specific examples of high-quality outputs rather than abstract style instructions. Showing three approved outbound messages in the target angle is more token-efficient and more reliable than describing the desired style in natural language instructions.

---

8. Observability and Context Tracing

8.1 Langfuse Integration

Every LLM call emits a trace to Langfuse (platform key stored in GCP Secret Manager, infrastructure/gcp/secrets.tf). Each trace includes mandatory metadata:

{
  "org_id": "{clerk_org_id}",
  "agent_id": "{AGT-XXX}",
  "run_id": "{inngest_run_id}",
  "kc_domains_queried": ["KC-08", "KC-04"],
  "tokens_in": 3420,
  "tokens_out": 187,
  "model": "gemini-pro / gpt-4o",
  "context_budget_used": { "system": 794, "kc": 1143, "entity": 1285, "history": 1987, "task": 211 }
}

This trace structure enables retroactive analysis of context budget utilization, retrieval quality (which KC exemplars were selected vs. how the output quality rated), and per-agent token economics.

8.2 Sentry for Agent Runtime Errors

Agent-level errors (context assembly failures, tool call parse errors, circuit breaker triggers) are reported to Sentry with org_id and run_id as tags. This allows debugging of context-related failures without exposing org-specific prompt content in error logs.

---

9. Knowledge Graph Structure

Colony's project documentation and IDs form a queryable knowledge graph through consistent cross-referencing. The graph has three node types and two edge types:

9.1 Node Types

9.2 Edge Types

9.3 Document ID System

Colony uses a hierarchical ID system derived from the action plan numbering:

9.4 Cross-Reference Map (Selected)

AGT-005 (Message Generator)
  ├── implements → docs/phase1/action_plans/13_message_generator_agent.md
  ├── tested by → docs/phase1/testing/04_e2e_outbound_flow.spec.md
  ├── reads from → KC-08 (ENT-007, domain "outbound exemplars")
  ├── reads from → ENT-002 (contact profile)
  ├── writes to  → ENT-011 (approval_queue)
  └── constrained by → CONST-001, CONST-002

AGT-006 (Recording Intelligence)
  ├── implements → docs/phase1/action_plans/14_recording_intelligence_agent.md
  ├── tested by → docs/phase1/testing/06_e2e_recording_intelligence.spec.md
  ├── reads from → ENT-006 (recordings), KC-09
  ├── writes to  → ENT-006.signals, ENT-003 (deal fields), KC-09
  └── triggered by → Google Drive webhook (Gemini Meet Notes)

ENT-007 (Knowledge Core)
  ├── defined in → docs/phase1/action_plans/24_knowledge_core_editor.md
  ├── tested by → docs/phase1/testing/08_e2e_knowledge_core.spec.md
  ├── synced from → Notion (docs/phase2/action_plans/15_notion_kc_sync.md)
  ├── indexed as → pgvector 1536-dim (TECH-001)
  └── queried by → AGT-004, AGT-005, AGT-006, AGT-007, AGT-008, AGT-009, AGT-010

---

10. Context Engineering Lifecycle Alignment

Colony's context architecture maps to the PRD lifecycle stages as follows: