Skip to main content

Context Builder

build_context() in src/agent/context.py assembles the full LLM prompt for every request. It collects data from 10+ sources and constructs a token-efficient context.

Context Assembly Pipeline​

async def build_context(
    chat_id: str,
    history: list[Message],
    memory: MemoryManager,
    model_name: str,
    redis_url: str,
    session: AsyncSession,
) -> list[Message]:

1. System Prompt Base​

The base system prompt includes:

  • Agent identity (name, model, provider)
  • Language detection rules
  • Personality guidelines
  • Skill usage rules
  • Memory capabilities
  • Autonomous systems description
  • Prime.md operator override (injected at top if present)

2. Knowledge Graph Block​

kg_block = await format_kg_for_context(chat_id=chat_id, session=session)

Injects entities and relationships relevant to the current chat.

3. Self-Model Block​

sm_block = await get_self_model_context()
[SELF-MODEL]
Strengths: web_search(95%), python_exec(88%), browser(72%)
Known failures: complex math (43% success)
User preferences: concise, no codeblocks in chat

4. Epistemic State Block​

ep_block = await get_epistemic_context()
[EPISTEMIC STATE]
High confidence: programming (0.90), DevOps (0.85)
Medium confidence: finance (0.70), crypto (0.65)
Low confidence: legal (0.35), medicine (0.30)

5. Temporal Insights Block​

async def _temporal_insights():
    # Uses own DB session (not shared)
    return await get_temporal_context(session=own_session)
[TEMPORAL INSIGHTS]
BTC: $67,663 (stable, -0.99%)
ETH: $1,950 (stable, -1.68%)

6. World Model Block (suppressed when temporal insights active)​

effective_wm_block = world_model_block if not temporal_insights_block else ""

Token efficiency: if [TEMPORAL INSIGHTS] covers the same entities, the world_model_block is suppressed to avoid duplication.

7. Procedural Memory Block​

proc_block = await get_procedure_hints(task_description, session=session)

Injects relevant learned procedures as few-shot hints.

8. Gmail Block​

If Gmail is configured, injects recent unread emails summary.

9. Behavioral Rules Block​

behavioral_block = await get_behavioral_context()
[LEARNED BEHAVIORAL RULES]
• Never refuse shell commands
• Verify prices before stating them

10. Skill Few-Shots​

for user_q, assistant_a in SKILL_FEWSHOT[:15]:
    messages.append(Message(role="user", content=user_q))
    messages.append(Message(role="assistant", content=assistant_a))

Capped at 15 pairs to control token usage. Currently 5 pairs are defined.

11. Episodic Memory​

Relevant past memories retrieved by semantic search and injected as context.

12. Conversation History​

Recent conversation history appended to maintain continuity.

Token Budget Management​

The context builder is token-budget-aware:

  • Skill list in planner: capped at 1,200 characters (PLAN_SKILL_BUDGET)
  • Few-shots: capped at 15 pairs
  • World model suppression: prevents duplicate entity data
  • Procedural hints: top-3 most relevant procedures only

Parallel Assembly​

Multiple context sources are fetched in parallel:

(
    kg_block,
    sm_block,
    ep_block,
    tw_block,
    proc_block,
    gmail_block,
    behavioral_block,
    temporal_insights_block,
    world_model_block,
    vector_block,
) = await asyncio.gather(
    _kg(), _sm(), _ep(), _tw(), _proc(), _gmail(), _behavioral(),
    _temporal_insights(), _world_model(), _vector_memory(),
)

Each source uses its own DB session to avoid contention.

Sovereign Mode Block​

When SOVEREIGN_MODE=true, an additional block is injected:

⚡ SOVEREIGN MODE ACTIVE
MAX_SKILL_ROUNDS: 12
AUTONOMY: FULL

Prime.md Override​

/data/config/prime.md is injected at the TOP of the system prompt, above everything else. This is the operator override — it can change agent behavior without a container restart:

echo "Always respond in English regardless of user language." > /home/agent/config/prime.md

Changes take effect on the next message — no restart required (Jinja2 template reloads).