Context Engineering

Relevant source files

The following files were used as context for generating this wiki page:

• loom-py/src/loom/context/engineering/compactor.py
• loom-py/src/loom/context/engineering/offloader.py
• loom-py/src/loom/context/engineering/reducer.py
• loom-py/src/loom/context/window.py
• ROADMAP.md
• loom-py/src/loom/context/README.md
• loom-py/src/loom/context/init.py
• loom-py/tests/integration/test_context_engineering.py
• loom-py/src/loom/cognitive/README.md

Context Engineering in Loom is a production-grade system for managing and optimizing the context provided to Large Language Models (LLMs). It resides within the Python "Brain" part of Loom's "Brain/Hand" architecture, focusing on token efficiency, history compression, and scalability for long-running, complex agent tasks. The primary goal is to maintain high-quality context while staying within the LLM's token limits, achieving up to 90% total token reduction through its various stages.

This system is crucial for enabling long-lifecycle agents by transforming verbose tool outputs and long conversation histories into concise, information-rich prompts. It follows key design principles: Reduction over Retention, Compaction over Summarization, and Offloading over Embedding. The main capabilities include Reduction, Compaction, Isolation, Offloading, and managing Memory Tiers.

Sources: ROADMAP.md, loom-py/src/loom/context/README.md

Architecture and Data Flow

The Context Engineering pipeline is a multi-stage process integrated directly into the CognitiveAgent's perceive-think-act loop. It processes tool outputs and conversation history before they are used to construct the next prompt for the LLM.

The following diagram illustrates the high-level flow of context optimization within Loom.

Integration with CognitiveAgent

The Context Engineering components are integrated within the CognitiveAgent to automate the optimization process.

The following sequence diagram shows how CognitiveAgent, StepReducer, DataOffloader, and StepCompactor interact.

Core Components

The system is composed of three main optimization components: StepReducer, DataOffloader, and StepCompactor.

1. Reduction (StepReducer)

Sources: loom-py/src/loom/context/engineering/reducer.py, ROADMAP.md

Reduction is the first stage, focused on creating a minimal, yet descriptive, summary of a tool's execution. The StepReducer class uses a set of tool-specific ToolReducer implementations to generate a Step object. This Step contains a concise observation instead of the full, verbose tool output.

Key Classes and Data Structures

Class/Data Structure	Description	Source File
Step	A dataclass representing a single, reduced step in an agent's history. It includes a minimal observation of the tool's outcome.	loom-py/src/loom/context/__init__.py:29
StepReducer	The main class that orchestrates reduction. It contains a registry of ToolReducer instances for different tools.	loom-py/src/loom/context/engineering/reducer.py
ToolReducer	An abstract base class for creating tool-specific reduction logic.	loom-py/src/loom/context/engineering/reducer.py

Tool-Specific Reducers

Loom provides several built-in reducers for common tools:

Reducer Class	Target Tool(s)	Reduction Logic
FileReadReducer	fs:read	Summarizes file reads by stating the file path, lines read, and size, instead of including the content.
FileWriteReducer	fs:write	Confirms a file write with path, line count, and size.
ShellReducer	shell:run	Summarizes shell command output, often showing exit code and a preview.
SearchReducer	web:search	Reports the number of search results found for a query.
WebFetchReducer	web:fetch	Confirms a web page was fetched and provides a summary of its content length.
DefaultReducer	(fallback)	Provides a generic summary for any tool without a specific reducer.

Sources: loom-py/src/loom/context/engineering/reducer.py, loom-py/src/loom/context/init.py:32-40

2. Offloading (DataOffloader)

Sources: loom-py/src/loom/context/engineering/offloader.py, ROADMAP.md

When a tool's output is too large to be effectively summarized (e.g., a large file or a complex API response), the DataOffloader saves the full content to a file in the workspace. The Step object is then updated with an outcome_ref pointing to this file. This removes the large data from the prompt context entirely, replacing it with a reference.

Configuration (OffloadConfig)

The behavior of the DataOffloader is controlled by the OffloadConfig dataclass.

Parameter	Type	Default	Description
enabled	bool	True	Toggles the offloading feature.
size_threshold	int	2048	Content size in bytes to trigger offloading.
line_threshold	int	50	Line count to trigger offloading.
preview_lines	int	10	Number of lines to keep as a preview in the observation.

Sources: loom-py/src/loom/context/engineering/offloader.py

Offloading Process

The CLI display is designed to handle offloaded steps, showing the user a summary and a reference to the offloaded file.

# Example of a ThoughtStep with an offloaded reference
reduced_step = Step(
    ...,
    observation="Search completed with 5 results",
    outcome_ref=".loom/cache/search/websearch_123.json",
)

step = ThoughtStep(
    ...,
    observation=Observation(
        ...,
        reduced_step=reduced_step,
    ),
    reduced_step=reduced_step,
)

# The CLI would display:
# ✅ Tool Result:
#    Summary: Search completed with 5 results
#    Offloaded to: .loom/cache/search/websearch_123.json
#    View with: cat .loom/cache/search/websearch_123.json

Sources: loom-py/tests/integration/test_context_engineering.py:65-99

3. Compaction (StepCompactor)

Sources: loom-py/src/loom/context/engineering/compactor.py, ROADMAP.md

Compaction addresses the problem of long conversation histories. The StepCompactor compresses a sequence of Step objects into a more concise representation. It groups similar consecutive steps (e.g., multiple file reads) into a single CompactStep and keeps recent steps uncompacted for immediate context.

This process is triggered automatically by the prompt builder when the number of steps exceeds a threshold (typically >5 steps).

Configuration (CompactionConfig)

Parameter	Type	Default	Description
enabled	bool	True	Toggles the compaction feature.
compaction_threshold	int	5	Number of steps required to trigger compaction.
keep_recent	int	3	Number of recent steps to leave uncompacted.

Sources: loom-py/src/loom/context/engineering/compactor.py

Compaction Logic

The following diagram shows how the StepCompactor processes a list of steps.

Summary

Loom's Context Engineering system is a sophisticated, multi-stage pipeline designed to make AI agents more efficient and capable of handling long-running tasks. By systematically applying reduction, offloading, and compaction, it dramatically reduces the number of tokens sent to the LLM without losing critical information. This ensures that agents can operate robustly over long periods, manage large amounts of data, and ultimately perform more complex and useful work.

Sources: ROADMAP.md, loom-py/src/loom/context/README.md