Skip to content

agentic_context_engineering.md

Latest commit

 

History

History
165 lines (101 loc) · 8.34 KB

agentic_context_engineering.md

File metadata and controls

165 lines (101 loc) · 8.34 KB
Raw

Agentic Context Engineering: Theory & BAZINGA Implementation

Status: Reference Documentation Context: Explaining the architectural decisions behind BAZINGA's memory and orchestration systems. Based on: Agentic Context Engineering (Transcript Analysis)

1. Executive Summary

"Agentic Context Engineering" is the discipline of managing an AI agent's memory not as a simple chat log, but as a structured, engineered system. The core premise is that "context is not a window, it is a compiled view."

This document outlines the theoretical frameworks (Google ADK, ACCE, Manus) that define modern agent architecture and details how the BAZINGA system implements these principles to solve the "context window fallacy"—the mistaken belief that larger context windows equal better performance.

2. Theoretical Framework

The Core Problem: The "Infinite Context" Fallacy

While LLM context windows have grown (128k, 1M+ tokens), simply dumping entire session logs into the prompt leads to:

  • Signal Dilution: Irrelevant history drowns out critical instructions.
  • Context Rot: Outdated constraints ("don't use library X") persist even after decisions change.
  • Log Bloat: Debugging becomes impossible as prompts grow to megabytes of unstructured text.

Architectural Solutions

The industry has converged on three key patterns to solve this:

1. The Tiered Memory Model (Google ADK)

Instead of a flat log, memory is split into four distinct tiers mirroring computer architecture:

Tier Analogy Description
Working Context Cache The minimal set of instructions and immediate history needed for the current step
Sessions RAM Structured event logs of the current trajectory
Memory Disk Durable, searchable insights that survive across sessions
Artifacts File System Large objects (code files, PDFs) referenced by pointers, not pasted as text

2. Adaptive Context / "Evolving Playbooks" (ACCE/ACE)

Contexts must evolve. Static system prompts fail in long-horizon tasks. The Agentic Context Engineering (ACE) framework treats context as a "living playbook" that accumulates strategies and prunes failures using a loop of Generation, Reflection, and Curation.

3. State Offloading & Isolation (Manus)

For autonomous agents, heavy state (e.g., a 5,000-line file or a browser DOM) must be offloaded to a sandbox or file system. The agent receives only a handle/pointer to the data. Furthermore, sub-agents (Planner, Executor, Verifier) must have isolated scopes to prevent "hallucinated teamwork" where one agent confuses another's internal monologue for a task instruction.

3. The 9 Scaling Principles

The transcript identifies nine principles for production-grade agents:

  1. Context as a Compiled View: Every prompt is a fresh projection, not a transcript.
  2. Tiered Memory Model: Separate storage (DB) from presentation (Prompt).
  3. Scope by Default: Default context is empty; retrieval is an active decision.
  4. Retrieval Beats Pinning: Search for relevant memories; don't pin everything.
  5. Schema-Driven Summarization: Use structured schemas (JSON/YAML) over loose text summaries.
  6. Offload Heavy State: Keep large data in files/DB; pass pointers to LLM.
  7. Isolate Sub-Agent Scope: Distinct views for different roles (Dev vs. QA).
  8. Caching & Prefix Stability: Design prompts to maximize KV-cache hits.
  9. Evolving Strategies: Agents should update their own instructions/strategies.

4. BAZINGA Implementation Analysis

The BAZINGA system was explicitly architected to align with these principles. Below is the mapping of theory to actual code and database structures.

Principle 1 & 2: Tiered Memory & Compiled Views

Theory: Separate storage from the "view" presented to the LLM.

BAZINGA Implementation: The Orchestrator does not simply read a log file. Instead, it compiles the prompt dynamically using bazinga-db:

Tier BAZINGA Component Implementation Details
Working Context Capsules & Summaries The prompt receives only the summaries of relevant Context Packages and the last few "Capsule" status messages
Sessions sessions & orchestration_logs Tables Structured SQL tables track every interaction (id, timestamp, agent_type)
Memory Context Packages (DB) The context_packages table stores metadata (priority, summary) for research and decisions
Artifacts Context Files (.md) Actual heavy content (e.g., 20KB research reports) is stored in bazinga/artifacts/{SESSION_ID}/context/

Principle 6: Offload Heavy State (Context Package System)

Theory: Don't paste 50 pages of research into the prompt. Pass a pointer.

BAZINGA Implementation: We implemented the Context Package System to handle this exact problem.

The Problem: A "Research Agent" generates 20KB of analysis. Pasting this into the "Developer Agent" prompt wastes tokens and dilutes attention.

The Fix:

  1. Research Agent saves content to bazinga/artifacts/.../research-group-A.md
  2. Agent calls save_context_package to register the file path and a 1-sentence summary in the database
  3. Developer Agent receives only the summary and file path in its prompt
  4. Active Retrieval: The Developer must explicitly call the Read tool to access the full content if needed
# From bazinga_db.py - The "Pointer" approach
def get_context_packages(...):
    # Returns only metadata (summary + path), NOT full content
    return cursor.execute("SELECT summary, file_path, priority ...")

Principle 7: Isolate Sub-Agent Scope

Theory: Prevent "crosstalk" where agents see irrelevant information from other sub-teams.

BAZINGA Implementation: We use a Join Table approach for strict scoping.

Table: context_package_consumers

Mechanism: When a package is created, it is assigned specific consumers (e.g., ['developer', 'qa_expert']).

Result: A "Tech Lead" architecture decision package is not visible to a "Junior Developer" unless explicitly routed. This prevents the developer from being confused by high-level architectural debates that are irrelevant to their specific coding task.

Principle 5: Schema-Driven Summarization

Theory: Naive text summaries ("The dev worked on auth") lose critical details. Use schemas.

BAZINGA Implementation:

  • Context Packages: Use strictly validated YAML Front Matter for metadata (Priority, Type, Consumers)
  • Capsule Messages: Agents communicate status using a strict format: 🔨 Group {id} | {summary} | {status} → {next_phase}. This allows the Orchestrator to parse the state deterministically without guessing.

Principle 9: Evolving Strategies (Reasoning Capture)

Theory: Agents should learn and update their strategies, not just execute.

BAZINGA Implementation: The orchestration_logs table includes specific columns for Reasoning Capture:

  • log_type='reasoning'
  • reasoning_phase: Tracks where in the thought process the agent is (understanding, strategy, pivot, conclusion)
  • confidence_level: Allows the system to weigh high-confidence insights more heavily in future prompts

This allows the system to reconstruct why a decision was made (the "Playbook") separately from what was done (the "Log").

5. References

The Google Paper (ADK & Memory Bank)

The Anthropic / ACE Paper

The Manus Paper

Video Resource

Here is a relevant video on the topic: Agentic Context Engineering: Evolving Contexts for Self-Improving Language Models. This video provides a comprehensive overview of the ACE framework discussed in the document.

Last Updated: 2025-12-11