Context Assembly

The layered pipeline that builds agent context from identity, team files, daily logs, and memories

The ContextAssemblyService constructs the full context string passed to an agent at the start of each conversation. It uses a layered approach with per-layer token budgets within a total 16,000 token budget.

Layer Architecture

Layer	Label	Source	Max Tokens	Truncatable
L1	Identity	`IDENTITY.md`	Unlimited	No
L1	Instructions	`INSTRUCTIONS.md`	Unlimited	No
L2	Team Goals	`GOALS.md`	Remaining	Yes
L2	Team Context	`CONTEXT.md`	Remaining	Yes
L2	Team Rules	`RULES.md`	Remaining	Yes
L3	Recent Activity	Daily files (7 days)	3,000	Yes
L4	Team Knowledge	Team memories (top 5)	2,000	Yes
L5	Personal Memories	Agent memories (top 5)	2,000	Yes
L7	Knowledge Base	`KNOWLEDGE.md`	2,000	Yes

Pipeline Flow

graph TD
    A[assembleContext agentId, teamId?, topic?] --> B[L1: Load IDENTITY + INSTRUCTIONS]
    B --> C{teamId?}
    C -->|Yes| D[L2: Load Team MD Files]
    C -->|No| E[L3: Load Daily Files]
    D --> E
    E --> F{teamId?}
    F -->|Yes| G[L4: Search Team Memories]
    F -->|No| H[L5: Search Agent Memories]
    G --> H
    H --> I[L7: Load KNOWLEDGE.md]
    I --> J[Join sections with headers]

Token Budget Management

The service uses a simple estimateTokens() function: Math.ceil(text.length / 4).

Each addSection() call:

Checks remaining budget (tokenBudget - usedTokens)
Applies the smaller of the layer max and remaining budget
Truncates text to maxChars = effectiveMax * 4 if needed
Appends ... [truncated] marker

L1 (Identity/Instructions) is never truncated — it always gets full allocation.

Semantic vs. Recent Fallback

For L4 (Team) and L5 (Agent) memories, the service uses a two-step strategy:

If a sessionTopic is provided, use pipeline/scoring|semantic search to find relevant memories
If semantic search returns no results, fall back to most recent memories

This ensures context is always populated even for new or broad conversations.

Example Output Structure

## Identity
You are Luna, a creative writing assistant...

## Instructions
Always respond with empathy. Prioritize storytelling...

## Team Goals
Ship the Q1 product demo by March 15...

## Recent Activity
### 2025-03-14
Discussed character arc revisions with user...

### 2025-03-13
Reviewed plot outline for chapter 3...

## Team Knowledge
- [decision] Use three-act structure for the demo narrative
- [context] Target audience is enterprise product managers

## Personal Memories
- [preference] User prefers concise bullet points over paragraphs
- [learning] User's team uses Notion for documentation

## Knowledge Base
Reference materials for storytelling frameworks...

schema/md-files — How IDENTITY, INSTRUCTIONS, KNOWLEDGE files work
pipeline/scoring — Semantic search formula used in L4/L5
operations/configuration — Token budgets and limits