Package Exports

contextguard-ai

Readme

ContextGuard

Token counters tell you how much you spent. ContextGuard tells you whether it was worth it.

Context budget management for AI applications. Visibility, governance, and health scoring for LLM context windows.

The Problem

AI teams dump everything into context windows — massive system prompts, full conversation histories, raw tool outputs. Performance degrades, costs scale linearly, but nobody knows why or what to cut.

ContextGuard proved it: In a realistic security review agent workflow, unmanaged context overflows the window (111%), scores a C health grade, and buries final synthesis under stale search results. With ContextGuard: 52% utilization, A grade, 53% token reduction, zero violations.

The Solution

Treat context as a budget, not a dump. Three capabilities:

Inspect — Real-time breakdown of what's in your context window by category
Govern — Set budgets per category, auto-prune when exceeded, enforce caps
Score — Composite health across 4 dimensions (Utilization, Freshness, Diversity, Signal-to-Noise)

Quick Start

# See the budget enforcement demo (before/after proof)
npx contextguard scenario

# Inspect with sample data
npx contextguard demo

# Analyze your own messages file
npx contextguard inspect conversation.json

# Quick health check
npx contextguard health messages.json

# Different model (auto-detects provider)
npx contextguard demo --model gpt-4o

# JSON output for piping
npx contextguard inspect messages.json --json

# Web dashboard
npx contextguard dashboard

# Session analytics
npx contextguard stats

Programmatic Usage

One-Shot Analysis

import { analyzeMessages } from 'contextguard';

const result = analyzeMessages([
  { role: 'system', content: 'You are a helpful assistant.' },
  { role: 'user', content: 'Help me with...' },
  { role: 'assistant', content: 'Sure, here is...' },
]);

console.log(result.health.grade);        // "A"
console.log(result.health.score);        // 92
console.log(result.budget.utilization);  // 0.001

Tracked Conversation (Middleware)

import { createTrackedConversation } from 'contextguard';

// Create a tracked conversation
const conv = createTrackedConversation({
  model: 'claude-sonnet-4-6',
  printWarnings: true,  // Warns on stderr when budgets exceeded
});

// Track your system prompt
conv.trackSystem('You are a security analyst...');

// Track each message exchange
conv.trackUser('Review this code for vulnerabilities');
// ... call your LLM API ...
conv.trackAssistant('I found 3 issues: ...');

// Track tool results
conv.trackTool('code_search', 'Results from searching auth module...');

// Track injected documents
conv.trackDocument('architecture.md', 'Service mesh auth flow...');

// Track memory/knowledge packs
conv.trackMemory('security-patterns-v1', 'OWASP patterns...');

// Check health anytime
console.log(conv.grade());              // "B"
console.log(conv.inspect().display);    // Formatted output

// Reset for new conversation
conv.reset();

Budget Manager (Low-Level)

import { BudgetManager } from 'contextguard';

const manager = new BudgetManager({
  maxTotalTokens: 200000,
  autoPrune: true,
  pruneStrategy: 'oldest',    // 'oldest' | 'lowest-relevance' | 'largest-first'
});

// Add context items
manager.add('You are a helpful assistant.', 'system', 'system_prompt');
manager.add('Help me with my code', 'conversation', 'user_msg_1');
manager.add('Search results: ...', 'tool_results', 'tool:search');

// Budget automatically enforced — stale items pruned when over limit

const status = manager.getStatus();
console.log(status.utilization);      // 0.003
console.log(status.hasOverage);       // false
console.log(status.categories);       // Per-category breakdown

const health = manager.getHealth();
console.log(health.grade);            // "A"
console.log(health.recommendations);  // Actionable suggestions

Web Dashboard

import { startDashboard } from 'contextguard';

// Start the dashboard server
startDashboard(4200);

// Send inspection data from your app
await fetch('http://localhost:4200/update', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    budget: result.budget,
    health: result.health,
    itemCount: result.items.length,
  }),
});

Session Analytics (SQLite)

import { AnalyticsStore } from 'contextguard';

const store = new AnalyticsStore();  // ~/.contextguard/analytics.db

// Track sessions
store.startSession('session-1', 'claude-sonnet-4-6');
store.recordSnapshot('session-1', budget, health);
store.endSession('session-1', analytics, 'A');

// Query history
const recent = store.getRecentSessions(10);
const stats = store.getStats();  // { avgHealth, totalPruned, ... }

store.close();

Context Categories

ContextGuard tracks 7 categories of context content:

Category	What It Tracks	Default Budget
`system`	System prompts, instructions	15%
`conversation`	User + assistant message history	40%
`tool_results`	Tool call outputs, search results	20%
`documents`	Injected docs, RAG results	15%
`memory`	Memory packs, persistent knowledge	5%
`examples`	Few-shot examples	5%
`other`	Uncategorized content	5%

Health Dimensions

Dimension	Weight	What It Measures
Utilization	25%	Sweet spot: 40-80%. Too low = wasted. Too high = no room for responses.
Freshness	25%	How recent is the content? Items >30min flagged as stale.
Diversity	20%	Is context balanced? Any category >70% = red flag.
Signal-to-Noise	30%	Duplicates, near-empty items, dead weight.

Supported Providers

Provider	Models	Context Window
Anthropic	Claude Opus 4.6 (1M), Sonnet 4.6 (200K), Haiku 4.5 (200K)	Auto-detected
OpenAI	GPT-4o (128K), GPT-4 Turbo (128K), o1/o3 (128-200K)	Auto-detected
Generic	Any messages-based API	Defaults to 128K

Provider is auto-detected from model name. Override with --provider flag or provider config option.

CLI Reference

contextguard demo                  Sample data inspection
contextguard scenario              Budget enforcement before/after proof
contextguard inspect <file>        Analyze a messages JSON file
contextguard health <file>         Quick health grade
contextguard dashboard [--port N]  Web dashboard (default: 4200)
contextguard stats                 Session analytics summary
contextguard --help                Help

Options:
  --model <name>      Model name (default: claude-sonnet-4-6)
  --provider <name>   anthropic | openai | generic
  --json              JSON output instead of formatted text
  --port <number>     Dashboard port (default: 4200)

Messages Format

Standard OpenAI/Anthropic messages array:

[
  { "role": "system", "content": "You are a helpful assistant." },
  { "role": "user", "content": "Hello" },
  { "role": "assistant", "content": "Hi! How can I help?" },
  { "role": "tool", "content": "Search results: ..." }
]

License

MIT

Built by ACE — Advanced Consulting Experts

Unlimited context feels powerful, but controlled context is what actually produces reliable results.

contextguard-ai