Context Management

import { AgentContextNextGen } from 'oneringai';

// Create a context instance
const ctx = AgentContextNextGen.create({
  model: 'gpt-4.1',
  systemPrompt: 'You are a helpful assistant.',
  features: {
    workingMemory: true,      // WorkingMemoryPluginNextGen
    inContextMemory: true,    // InContextMemoryPluginNextGen
    persistentInstructions: false,
  },
  strategy: 'algorithmic', // 75% reclaim target; 90% critical trigger
});

// Add user message
ctx.addUserMessage('What is the weather in Paris?');

// Prepare context for LLM call (handles compaction if needed)
const { input, budget, compacted } = await ctx.prepare();

// After LLM call, add response
ctx.addAssistantResponse(response.output);

// Add tool results
ctx.addToolResults([{ tool_use_id: '...', content: '...', state: ToolCallState.COMPLETED }]);

// Access plugins
const memory = ctx.memory;  // WorkingMemoryPluginNextGen | null
await memory?.store('key', 'description', value);

// Access tools
ctx.tools.disable('risky_tool');

// Budget information
console.log(`Tokens: ${budget.totalUsed}/${budget.maxTokens}`);
console.log(`Utilization: ${budget.utilizationPercent}%`);
console.log(`Available: ${budget.available}`);

const result = await agent.rolloverContext({
  preserveRecentTurns: 8,
  maxSummaryTokens: 2048,
  reason: 'provider-session-expiring',
});

await agent.rolloverContext({
  summarize: async ({ items, estimatedTokens, preservedRecentTurns, reason }) =>
    summaryService.createContinuityBrief({
      items,
      estimatedTokens,
      preservedRecentTurns,
      reason,
    }),
});

const result = await agent.context.rollover({
  preserveRecentTurns: 8,
  reason: 'manual-handoff',
  summarize: ({ items }) => summarizeWithTrustedModel(items),
});

[Developer Message - All glued together]
  # System Prompt
  # Persistent Instructions (if plugin enabled)
  # Plugin Instructions (for enabled plugins)
  # In-Context Memory (if plugin enabled)
  # Working Memory Index (if plugin enabled)

[Conversation History]
  ... messages including tool_use/tool_result pairs ...

[Current Input]
  User message OR tool results (newest, never compacted)

import { Agent, AgentContextNextGen } from 'oneringai';

// AgentContextNextGen is auto-created with default config
const agent = Agent.create({
  connector: 'openai',
  model: 'gpt-4.1',
  tools: [weatherTool],
  context: {
    model: 'gpt-4.1',
    strategy: 'algorithmic',    // Default strategy; 75% reclaim threshold, 90% critical trigger
    features: { workingMemory: true },
  },
});

// UNIFIED TOOL MANAGEMENT: agent.tools and agent.context.tools are the SAME instance
console.log(agent.tools === agent.context.tools);  // true
console.log(agent.hasContext());  // Always true

// Tool changes via either path are immediately reflected
agent.tools.disable('weather_tool');
console.log(agent.context.tools.listEnabled().includes('weather_tool'));  // false

agent.context.tools.enable('weather_tool');
console.log(agent.tools.listEnabled().includes('weather_tool'));  // true

// Agent automatically tracks messages and tool calls
await agent.run('What is the weather?');

// Access the context (never null)
const ctx = agent.context;
const conversation = ctx.getConversation(); // InputItem[] - NextGen API
const budget = ctx.lastPreparation?.budget;
if (budget) console.log(`Used: ${budget.totalUsed}/${budget.maxTokens} tokens`);

// Option 2: Pass existing AgentContextNextGen instance
const sharedContext = AgentContextNextGen.create({ model: 'gpt-4.1' });
const agent1 = Agent.create({ connector: 'openai', model: 'gpt-4.1', context: sharedContext });
// Keep this context under one execution owner. Sharing history with another
// provider requires compatible state and explicit authorization; opaque signed
// continuations cannot simply transfer between accounts/providers.

interface AgentContextNextGenConfig {
  /** Model name (used for token limits) — REQUIRED */
  model: string;

  /** Max context tokens (overrides model default) */
  maxContextTokens?: number;

  /** Response token reserve in tokens (default: 4096) */
  responseReserve?: number;

  /** System prompt */
  systemPrompt?: string;

  /** Agent ID (used for persistent storage paths) */
  agentId?: string;

  /** Tools to register */
  tools?: ToolFunction[];

  /** Feature flags for enabling/disabling plugins */
  features?: ContextFeatures;

  /** Compaction strategy */
  strategy?: string;  // 'algorithmic' (default, 75%) or custom registered strategy name

  /** Context storage for session persistence */
  storage?: IContextStorage;

  /** Plugin configurations */
  plugins?: PluginConfigs;
}

interface ContextFeatures {
  /** Enable WorkingMemoryPluginNextGen (default: true) */
  workingMemory?: boolean;

  /** Enable InContextMemoryPluginNextGen (default: true) */
  inContextMemory?: boolean;

  /** Enable PersistentInstructionsPluginNextGen (default: false) */
  persistentInstructions?: boolean;

  /** Enable UserInfoPluginNextGen (default: false) */
  userInfo?: boolean;

  /** Enable ToolCatalogPluginNextGen for dynamic tool loading/unloading (default: false) */
  toolCatalog?: boolean;

  /** Enable SharedWorkspacePluginNextGen (default: false) */
  sharedWorkspace?: boolean;

  /** Enable MemoryPluginNextGen read tools/profile injection (default: false) */
  memory?: boolean;

  /** Enable MemoryWritePluginNextGen write tools (default: false; requires memory) */
  memoryWrite?: boolean;
}

import { AgentContextNextGen, DEFAULT_FEATURES } from 'oneringai';

// View default feature settings
console.log(DEFAULT_FEATURES);
// { taskState: false, workingMemory: true, inContextMemory: true, persistentInstructions: false, userInfo: false, toolCatalog: false, sharedWorkspace: false, memory: false, memoryWrite: false }
// evidence is separately opt-in; it is not enabled by these defaults.

// 1. Managed context without scratch notes (history and whiteboard still enabled)
const ctx = AgentContextNextGen.create({
  model: 'gpt-4.1',
  features: { workingMemory: false },  // Disable working memory
});

console.log(ctx.memory);  // null

// 2. Example with legacy compatibility stores enabled
const ctxVariant2 = AgentContextNextGen.create({
  model: 'gpt-4.1',
  features: {
    workingMemory: true,          // default: true
    inContextMemory: true,        // default: true
    persistentInstructions: true, // default: false
    userInfo: true,               // default: false
  },
});

// 3. Via Agent.create() - inline config
const agent = Agent.create({
  connector: 'openai',
  model: 'gpt-4.1',
  context: {
    model: 'gpt-4.1',
    features: { workingMemory: false },  // Disable working memory
  },
});

// 4. Agent with selected compatibility stores
const fullAgent = Agent.create({
  connector: 'openai',
  model: 'gpt-4.1',
  userId: 'alice',  // Optional for userInfo isolation
  context: {
    model: 'gpt-4.1',
    agentId: 'my-agent',
    features: {
      workingMemory: true,
      inContextMemory: true,
      persistentInstructions: true,
      userInfo: true,
    },
  },
});

// Check if a feature is enabled
ctx.features.workingMemory;           // boolean
ctx.features.inContextMemory;         // boolean
ctx.features.persistentInstructions;  // boolean
ctx.features.userInfo;                // boolean

// Get read-only feature configuration
ctx.features; // also includes sharedWorkspace, memory, memoryWrite, and registered external feature keys

// Access nullable memory
ctx.memory;  // WorkingMemoryPluginNextGen | null

// Access plugins by name
ctx.getPlugin('working_memory');            // WorkingMemoryPluginNextGen | null
ctx.getPlugin('in_context_memory');         // InContextMemoryPluginNextGen | null
ctx.getPlugin('persistent_instructions');   // PersistentInstructionsPluginNextGen | null
ctx.getPlugin('user_info');                 // UserInfoPluginNextGen | null
ctx.getPlugin('tool_catalog');              // ToolCatalogPluginNextGen | null
ctx.getPlugin('shared_workspace');          // SharedWorkspacePluginNextGen | null
ctx.getPlugin('memory');                    // MemoryPluginNextGen | null
ctx.getPlugin('memory_write');              // MemoryWritePluginNextGen | null

// Check if plugin exists
ctx.hasPlugin('working_memory');  // boolean

import { AgentContextNextGen } from 'oneringai';

// With workingMemory enabled (default)
const ctx = AgentContextNextGen.create({ model: 'gpt-4.1' });
console.log(ctx.tools.has('store_set'));     // true (store_* tools registered)

// With workingMemory disabled - memory store not available
const ctx2 = AgentContextNextGen.create({
  model: 'gpt-4.1',
  features: { workingMemory: false },
});
// store_* tools are still registered, but store_set("notes", ...) will fail

import { AgentContextNextGen } from 'oneringai';

const ctx = AgentContextNextGen.create({ model: 'gpt-4.1' });

// Add user message
ctx.addUserMessage('Hello!');

// Prepare for LLM call (handles compaction if needed)
const { input, budget } = await ctx.prepare();

// ... call LLM with input ...

// Add assistant response
ctx.addAssistantResponse(response.output);

// Add tool results
ctx.addToolResults([
  { tool_use_id: 'call_123', content: JSON.stringify({ result: 'success' }), state: ToolCallState.COMPLETED }
]);

// Get conversation history
const conversation = ctx.getConversation();

// Clear conversation
ctx.clearConversation('Starting fresh');

const { input, budget, compacted } = await ctx.prepare();

console.log(budget.utilizationPercent);  // Current usage %
console.log(budget.available);           // Remaining tokens
console.log(compacted);                  // true if compaction occurred

import { AgentContextNextGen, createFileContextStorage } from 'oneringai';

// Create storage
const storage = createFileContextStorage('my-agent');

// Create context with storage
const ctx = AgentContextNextGen.create({
  model: 'gpt-4.1',
  features: { workingMemory: true },
  storage,
});

// Add messages and data
ctx.addUserMessage('Hello');

// Save session
await ctx.save('session-001', { title: 'My Session' });

// Later: Load session
const ctx2 = AgentContextNextGen.create({ model: 'gpt-4.1', storage });
await ctx2.load('session-001');
// ctx2 now has full conversation and plugin states restored

import { type IContextPluginNextGen, BasePluginNextGen, AgentContextNextGen } from 'oneringai';

// Create a custom plugin by extending BasePluginNextGen
class MyPlugin extends BasePluginNextGen {
  readonly name = 'my_plugin';

  private data: string[] = [];

  // Static usage instructions for the LLM (never compacted)
  getInstructions(): string | null {
    return null;
  }

  // Return content to be included in context (must update the token cache)
  async getContent(): Promise<string | null> {
    if (this.data.length === 0) return null;
    const content = `## My Plugin Data\n${this.data.join('\n')}`;
    this.updateTokenCache(this.estimator.estimateTokens(content));
    return content;
  }

  // Raw data for programmatic inspection
  getContents(): unknown {
    return this.data;
  }

  addData(item: string) {
    this.data.push(item);
    this.invalidateTokenCache();
  }

  // Opt in to compaction (base class defaults to false)
  isCompactable(): boolean {
    return this.data.length > 0;
  }

  // Compact: reduce content to fit within targetTokensToFree
  async compact(targetTokensToFree: number): Promise<number> {
    const before = this.getTokenSize();
    while (this.getTokenSize() > Math.max(0, before - targetTokensToFree) && this.data.length > 1) {
      this.data.shift();
      await this.getContent(); // refreshes the token cache
    }
    return before - this.getTokenSize();
  }

  // Serialize state for persistence
  getState(): unknown {
    return { data: this.data };
  }

  // Restore state
  restoreState(state: unknown): void {
    this.data = ((state as { data?: string[] }).data) || [];
    this.invalidateTokenCache();
  }
}

// Use the plugin
const ctx = AgentContextNextGen.create({ model: 'gpt-4.1' });
const plugin = new MyPlugin();
ctx.registerPlugin(plugin);
plugin.addData('Custom data');

const ctx = AgentContextNextGen.create({ model: 'gpt-4.1' });

// Message events
ctx.on('message:added', ({ role }) => {
  console.log(`New ${role} message`);
});

// Compaction events
ctx.on('context:compacted', ({ tokensFreed }) => {
  console.log(`Freed ${tokensFreed} tokens`);
});

// Budget events
ctx.on('budget:warning', ({ budget }) => {
  console.log(`Context at ${budget.utilizationPercent.toFixed(1)}%`);
});

// Context prepared event
ctx.on('context:prepared', ({ budget }) => {
  console.log(`Context prepared: ${budget.totalUsed}/${budget.maxTokens} tokens`);
});

import { Agent, AgentContextNextGen, WorkingMemoryPluginNextGen } from 'oneringai';

// Create Agent with NextGen context
const agent = Agent.create({
  connector: 'openai',
  model: 'gpt-4.1',
  tools: [myTool],
  context: {
    model: 'gpt-4.1',
    features: { workingMemory: true, inContextMemory: true },
  },
});

// Access AgentContextNextGen directly
agent.context.addUserMessage('Hello');
const { input, budget } = await agent.context.prepare();
agent.context.addAssistantResponse(response.output);

// Get conversation
const conversation = agent.context.getConversation();  // InputItem[]

// Access WorkingMemory via plugin
const memoryPlugin = agent.context.getPlugin('working_memory') as WorkingMemoryPluginNextGen;
await memoryPlugin.store('key', 'description', value);

// Access tools via context
agent.context.tools.disable('tool_name');

// AgentContextNextGen provides clean context management:
ctx.addUserMessage(content);              // Set current user input
ctx.addAssistantResponse(response.output);       // Add response to conversation
await ctx.prepare();                      // Prepare context for LLM call, returns { input, budget }
ctx.getConversation();                    // Get conversation history
ctx.registerPlugin(plugin);               // Register context plugin
ctx.getPlugin(name);                      // Get registered plugin by name
await ctx.consolidate();                  // Post-cycle consolidation (strategy-driven cleanup)
await ctx.save(sessionId);                // Save session (if storage configured)
await ctx.load(sessionId);                // Load session (if storage configured)

// Access ToolManager:
ctx.tools;                                // ToolManager instance

import { BasePluginNextGen, WorkingMemoryPluginNextGen, InContextMemoryPluginNextGen } from 'oneringai';

// Built-in NextGen plugins:
// - WorkingMemoryPluginNextGen: Tiered memory (raw/summary/findings)
// - InContextMemoryPluginNextGen: Live key-value storage in context
// - PersistentInstructionsPluginNextGen: Disk-persisted instructions

// Custom plugin example:
class MyPlugin extends BasePluginNextGen {
  readonly name = 'my_plugin';

  getInstructions(): string | null {
    return null;
  }

  async getContent(): Promise<string | null> {
    const content = 'Custom context content';
    this.updateTokenCache(this.estimator.estimateTokens(content));
    return content;
  }

  getContents(): unknown {
    return null;
  }
}

ctx.registerPlugin(new MyPlugin());

import { Agent } from 'oneringai';

const agent = Agent.create({
  connector: 'openai',
  model: 'gpt-4.1',
  tools: [myTool],
  context: {
    model: 'gpt-4.1',
    strategy: 'algorithmic',  // Default: compact at 75% utilization
    features: { workingMemory: true },
  },
});

// AgentContextNextGen will automatically:
// 1. Track context usage across all plugins
// 2. Compact when approaching limits (at prepare() time)
// 3. Evict low-priority memory entries when needed
// 4. Call plugin compact() methods in priority order
// 5. Emit events for monitoring

┌─────────────────────────────────────────────────────┐
│               AgentContextNextGen                    │
│  - Plugin-first architecture                        │
│  - Clean message flow (addUserMessage → prepare)    │
│  - Single compaction point (right before LLM call)  │
└─────────────────┬───────────────────────────────────┘
                  │
    ┌─────────────┼─────────────┐
    │             │             │
    ▼             ▼             ▼
┌─────────┐ ┌──────────┐ ┌───────────────┐
│ Strategy│ │ Plugins  │ │ Context       │
│ (how)   │ │ (what)   │ │ Structure     │
└─────────┘ └──────────┘ └───────────────┘

Critical gate: Decides WHEN to compact (90% content utilization by default)
Strategy: Decides HOW to reclaim and its target (algorithmic threshold: 75%)
Plugins: WorkingMemoryPluginNextGen, InContextMemoryPluginNextGen, etc.
Context: Developer Message → Conversation History → Current Input

import {
  AgentContextNextGen,
  WorkingMemoryPluginNextGen,
  InContextMemoryPluginNextGen,
} from 'oneringai';

// Create AgentContextNextGen with configuration
const ctx = AgentContextNextGen.create({
  model: 'gpt-4.1',
  systemPrompt: 'Your system instructions',
  maxContextTokens: 128000,    // Model's context window
  responseReserve: 4096,       // Reserve tokens for response
  strategy: 'algorithmic',     // Default strategy (75% reclaim threshold; critical gate controls triggering)
  features: {
    workingMemory: true,       // Enable WorkingMemoryPluginNextGen
    inContextMemory: true,     // Enable InContextMemoryPluginNextGen
  },
});

// Plugins are auto-registered when features are enabled
// Access them via getPlugin():
const memoryPlugin = ctx.getPlugin('working_memory') as WorkingMemoryPluginNextGen;
const inContextPlugin = ctx.getPlugin('in_context_memory') as InContextMemoryPluginNextGen;

// Add user message (sets _currentInput)
ctx.addUserMessage('Current task description');

// Prepare context before each LLM call
const { input, budget } = await ctx.prepare();
console.log(`Context: ${budget.totalUsed}/${budget.maxTokens} tokens`);
console.log(`Utilization: ${budget.utilizationPercent.toFixed(1)}%`);

// After LLM response, add it to conversation
ctx.addAssistantResponse(llmResponse);

// Get conversation history
const conversation = ctx.getConversation();  // InputItem[]

import { SummarizeCompactor, ApproximateTokenEstimator } from 'oneringai';

const estimator = new ApproximateTokenEstimator();

// Create summarize compactor with LLM
const summarizeCompactor = new SummarizeCompactor(estimator, {
  textProvider: myTextProvider,     // Required: LLM for summarization
  model: 'gpt-4o-mini',             // Optional: model to use (default: same as agent)
  maxSummaryTokens: 500,            // Optional: max tokens for summary
  preserveStructure: true,          // Optional: keep headings/lists (default: true)
  fallbackToTruncate: true,         // Optional: truncate if LLM fails (default: true)
});

// Components with strategy: 'summarize' will use this compactor
const component = {
  name: 'conversation_history',
  content: longConversation,
  priority: 6,
  compactable: true,
  metadata: { strategy: 'summarize' },  // Uses SummarizeCompactor
};

// Example: Research task with summarization
// AgentContextNextGen is the unified context manager - configure via Agent.create()
const agent = Agent.create({
  connector: 'openai',
  model: 'gpt-4.1',
  context: {
    model: 'gpt-4.1',
    features: { workingMemory: true },
  },
});

// Access context management via agent.context (AgentContextNextGen instance)
const budget = agent.context.lastPreparation?.budget; // Inspect after run/stream; do not prepare twice.

import { MemoryEvictionCompactor } from 'oneringai';

const evictionCompactor = new MemoryEvictionCompactor(estimator);

// Components with strategy: 'evict' will use this compactor
const memoryComponent = {
  name: 'memory_index',
  content: memoryIndex,
  priority: 8,
  compactable: true,
  metadata: {
    strategy: 'evict',
    avgEntrySize: 100,                    // Average tokens per entry
    evict: async (count) => { await evictMemoryEntries(count); },
    getUpdatedContent: async () => getMemoryIndex(),
  },
};

import { Agent } from 'oneringai';
// The callback parameter is inferred from AgentConfig; component summaries contain metadata only.

// Define lifecycle hooks when creating the agent
const agent = Agent.create({
  connector: 'openai',
  model: 'gpt-4.1',
  lifecycleHooks: {
    beforeCompaction: async (context) => {
      console.log(`Agent ${context.agentId}: Compaction starting`);
      console.log(`Current usage: ${context.currentBudget.used}/${context.currentBudget.total}`);
      console.log(`Need to free: ${context.estimatedTokensToFree} tokens`);
      console.log(`Strategy: ${context.strategy}`);
      console.log(`Components to compact: ${context.components.length}`);

      // These are metadata summaries, not source bodies.
      for (const component of context.components) {
        console.log(component.name, component.compactable);
      }
      // Preserve application-owned findings through the enabled memory plugin;
      // see the native-hooks example for a complete bounded implementation.
    },
  },
});

// AgentContextNextGen handles all context management internally
// No separate ContextManager needed

interface BeforeCompactionContext {
  /** Agent identifier */
  agentId: string;

  /** Current context budget info (a lightweight summary, not the full ContextBudget) */
  currentBudget: {
    total: number;
    used: number;
    available: number;
    utilizationPercent: number;
    status: 'ok' | 'warning' | 'critical';
  };

  /** Strategy being used (e.g. 'algorithmic') */
  strategy: string;

  /** Components about to be compacted (read-only summaries) */
  components: ReadonlyArray<{
    name: string;
    priority: number;
    compactable: boolean;
  }>;

  /** Estimated tokens that need to be freed */
  estimatedTokensToFree: number;
}

const hooks = {
  beforeCompaction: async (context) => {
    // Even if this throws, compaction will continue
    throw new Error('Hook error');
  },
};

// Compaction proceeds, error is logged to console

// Default - uses algorithmic strategy automatically
const agent = Agent.create({
  connector: 'openai',
  model: 'gpt-4.1',
  context: { model: 'gpt-4.1', features: { workingMemory: true } },
});

// Explicit strategy selection
const agentVariant2 = Agent.create({
  connector: 'openai',
  model: 'gpt-4.1',
  context: { model: 'gpt-4.1', strategy: 'algorithmic' },
});

import { Agent, StrategyRegistry } from 'oneringai';

const earlierReclaim = StrategyRegistry.create('algorithmic', { threshold: 0.60 });
const agent = Agent.create({
  connector: 'openai', model: 'gpt-4.1',
  context: { model: 'gpt-4.1', compactionStrategy: earlierReclaim },
});

// Default - algorithmic strategy (recommended for most use cases)
const agent = Agent.create({
  connector: 'openai',
  model: 'gpt-4.1',
  // strategy defaults to 'algorithmic' (75% reclaim target; 90% critical trigger)
});

// Custom registered strategy
const agentVariant2 = Agent.create({
  connector: 'openai',
  model: 'gpt-4.1',
  context: { model: 'gpt-4.1', compactionStrategy: earlierReclaim },  // Instance configured above
});

import { ApproximateTokenEstimator } from 'oneringai';

const estimator = new ApproximateTokenEstimator();

// Basic estimation (mixed content assumed)
const tokens1 = estimator.estimateTokens('Hello, world!');

// Content-type-aware estimation for better accuracy
const codeTokens = estimator.estimateTokens(sourceCode, 'code');    // ~3 chars/token
const proseTokens = estimator.estimateTokens(essay, 'prose');       // ~4 chars/token
const mixedTokens = estimator.estimateTokens(readme, 'mixed');      // ~3.5 chars/token

// Estimate structured data
const dataTokens = estimator.estimateDataTokens({ users: [], config: {} });

// Get budget from prepare() call
const { input, budget, compacted } = await agent.context.prepare();

console.log(`Max tokens: ${budget.maxTokens}`);
console.log(`Used tokens: ${budget.totalUsed}`);
console.log(`Available: ${budget.available}`);
console.log(`Utilization: ${budget.utilizationPercent.toFixed(1)}%`);

// Check if compaction occurred
if (compacted) {
  console.log('Context was compacted to make room');
}

// Detailed breakdown
console.log('Breakdown:');
console.log(`  System prompt: ${budget.breakdown.systemPrompt} tokens`);
console.log(`  Plugin instructions: ${budget.breakdown.pluginInstructions} tokens`);
console.log(`  Conversation: ${budget.breakdown.conversation} tokens`);
console.log(`  Current input: ${budget.breakdown.currentInput} tokens`);

import type { AgentConfig } from 'oneringai';

type LifecycleHooks = NonNullable<AgentConfig['lifecycleHooks']>;

const hooks: LifecycleHooks = {
  // This is the lifecycle hook currently wired by Agent.
  beforeCompaction: async (context) => {
    await monitoring.record({
      event: 'context_compaction_starting',
      agentId: context.agentId,
      utilizationPercent: context.currentBudget.utilizationPercent,
      strategy: context.strategy,
      estimatedTokensToFree: context.estimatedTokensToFree,
    });
  },
};

// Apply hooks to agent
agent.setLifecycleHooks(hooks);

import { Agent } from 'oneringai';

// Default algorithmic strategy - recommended for most use cases
const agent = Agent.create({
  connector: 'openai',
  model: 'gpt-4.1',
  context: { model: 'gpt-4.1', features: { workingMemory: true } },
});

// For custom compaction behavior, register a custom strategy via StrategyRegistry

// Set up monitoring with AgentContextNextGen events
const ctx = agent.context;

ctx.on('context:compacted', async ({ tokensFreed }) => {
  await metrics.gauge('context.tokens_freed', tokensFreed);
});

ctx.on('context:prepared', async ({ budget }) => {
  await metrics.gauge('context.usage', budget.totalUsed);
  await metrics.gauge('context.total', budget.maxTokens);
});

ctx.on('budget:warning', async ({ budget }) => {
  const utilization = Math.round(budget.utilizationPercent);
  await alerts.warn(`Context warning: ${utilization}%`);
});

// Store data in appropriate tiers based on importance
const memoryPlugin = ctx.getPlugin('working_memory') as WorkingMemoryPluginNextGen;

// Raw tier: Large, unprocessed data (evicted first)
await memoryPlugin.store('search.results', 'Raw search results', largeResults, { tier: 'raw' });

// Summary tier: Condensed information
await memoryPlugin.store('search.summary', 'Search summary', summaryData, { tier: 'summary' });

// Findings tier: Key insights (evicted last)
await memoryPlugin.store('search.findings', 'Key findings', findings, { tier: 'findings' });

// Structure data for efficient compaction using tiers
const memoryPlugin = ctx.getPlugin('working_memory') as WorkingMemoryPluginNextGen;

// BAD: Single large object in findings (won't be evicted easily)
await memoryPlugin.store('all.data', 'All data', hugeObject, { tier: 'findings' });

// GOOD: Split by importance using tiers
// Raw tier: Evicted first during compaction
await memoryPlugin.store('data.raw', 'Raw data', rawData, { tier: 'raw' });

// Summary tier: Evicted second
await memoryPlugin.store('data.summary', 'Summarized data', summaryData, { tier: 'summary' });

// Findings tier: Evicted last (most important)
await memoryPlugin.store('data.findings', 'Key findings', findings, { tier: 'findings' });