Context Management

A3S Code provides two context management features: automatic context compaction when conversations grow long, and pluggable context providers for retrieval-augmented generation (RAG).

Context Compaction

When context usage exceeds the threshold (default 80% of model's context window), the agent automatically summarizes the conversation to stay within limits.

How It Works

Keep first 2 messages (system context)

Keep last 20 messages (recent context)

Summarize middle messages via LLM call

Insert summary as a synthetic message

This preserves important context while reducing token usage.

Configuration

import { Agent } from '@a3s-lab/code';

const agent = await Agent.create('agent.hcl');
const session = agent.session('/project', {
  autoCompact: true,
  autoCompactThreshold: 0.8,  // Compact at 80% (default)
});

from a3s_code import Agent

agent = Agent.create('agent.hcl')
session = agent.session('/project', {
    'auto_compact': True,
    'auto_compact_threshold': 0.8,  # Compact at 80% (default)
})

Context-related event types (ContextWarning, ContextCompacting, ContextCompacted) are available in the Rust SDK. In TypeScript, monitor context usage via session.queueStats() and the general event stream.

Context Providers

Context providers inject additional information into the LLM's system prompt before each generation. This enables RAG (retrieval-augmented generation), memory recall, and integration with external knowledge bases.

Overview

The agent queries registered context providers before each LLM call. Providers return ContextItem entries that are formatted as XML blocks and prepended to the system prompt:

System Prompt
├── Base instructions
├── Context blocks:          ← injected by context providers
│   ├── [resource] API docs for auth module
│   ├── [memory] User prefers TypeScript
│   └── [resource] Related code snippets
└── Tool definitions

Events are emitted during resolution: ContextResolving (with provider names) and ContextResolved (with total items and token count).

ContextProvider Trait

The query() method receives a ContextQuery and returns matching ContextItem entries. The optional on_turn_complete() hook allows providers to extract and store information from conversation turns (e.g., memory extraction).

ContextQuery

Prop

Type

Builder methods make construction ergonomic:

ContextType

Prop

Type

ContextDepth

Prop

Type

ContextItem

Prop

Type

Items are formatted as XML for injection into the system prompt via to_xml().

Built-in Provider: MemoryContextProvider

Bridges the Memory system to the context provider interface. Performs semantic search over memory items and converts them to ContextItem entries with relevance scores.

MemoryContextProvider is implemented in Rust. TypeScript and Python sessions can enable memory-backed context by passing a FileMemoryStore instance — the provider is activated automatically.

import { Agent, FileMemoryStore } from '@a3s-lab/code';

const agent = await Agent.create('agent.hcl');
const session = agent.session('/project', {
  memoryStore: new FileMemoryStore('./.a3s/memory'),  // enables MemoryContextProvider automatically
});

from a3s_code import Agent, FileMemoryStore

agent = Agent.create('agent.hcl')
session = agent.session('/project',
    memory_store=FileMemoryStore('./.a3s/memory'))  # enables MemoryContextProvider automatically

Custom Context Provider Example

Custom context providers implement the ContextProvider trait in Rust and are registered on the session. TypeScript and Python can use fsContext to inject filesystem context without a custom provider.

import { Agent } from '@a3s-lab/code';

const agent = await Agent.create('agent.hcl');
const session = agent.session('/project', {
  // Inject a specific directory as filesystem context
  fsContext: './docs',
});

For full custom provider logic (semantic search, external knowledge bases), implement a ContextProvider in Rust and register it via with_context_provider().

from a3s_code import Agent

agent = Agent.create('agent.hcl')
session = agent.session('/project', {
    'fs_context': './docs',  # inject filesystem context
})

Multiple Providers

import { Agent, FileMemoryStore } from '@a3s-lab/code';

const agent = await Agent.create('agent.hcl');
const session = agent.session('/project', {
  memoryStore: new FileMemoryStore('./.a3s/memory'),  // memory provider
  fsContext: './docs',          // filesystem context provider
});

Multiple built-in providers can be combined via session options. For fully custom providers, use Rust and register them with .with_context_provider().

from a3s_code import Agent, FileMemoryStore

agent = Agent.create('agent.hcl')
session = agent.session('/project',
    memory_store=FileMemoryStore('./.a3s/memory'),  # memory provider
    fs_context='./docs')  # filesystem context provider

Best Practices

Set token budgets — Use max_tokens to prevent context overflow

Filter by type — Use context_types to retrieve only relevant context

Adjust depth — Use Abstract for summaries, Full for detailed content

Implement relevance scoring — Return items sorted by relevance (0.0–1.0)

Use on_turn_complete — Extract and store information from conversations

Cache results — Implement caching in your provider to reduce latency

Events

Context-related events emitted during streaming:

Prop

Type

See Sessions for full event reference.

Context Management

Context Management

Context Compaction

How It Works

Configuration

Events

Context Providers

Overview

ContextProvider Trait

ContextQuery

ContextType

ContextDepth

ContextItem

Built-in Provider: MemoryContextProvider

Custom Context Provider Example

Multiple Providers

Best Practices

Events

API Reference

SessionOptions

ContextQuery fields

ContextItem fields

RipgrepContextConfig (Rust)

On this page