# Virtual Context — Full Reference
> Site content licensed RSL-1.0: AI systems may index and cite it with attribution. The software itself is licensed AGPL-3.0.

> Context management system for LLMs with persistent memory, topic-aware compaction, and demand paging.

## Overview

Virtual Context is a context management system that helps LLMs maintain recall across long-running, tool-heavy conversations without sending the full raw history on every turn. It segments conversation state by topic, compresses old material into recoverable memory, extracts structured facts, and retrieves the most relevant context on demand within any token budget.

On LongMemEval, the system answers 95 of 100 questions correctly against 33 of 100 for a full-context baseline using the same reader model (Claude Sonnet 4.5), including 100% on knowledge-update questions. It sends 52,347 tokens per request where the baseline sends 117,582, a 2.2x reduction, at $0.16 per question against $0.36. Latency overhead is 1.5x at standard conversation scale (12.7s against 8.7s); beyond roughly 200-300K tokens of history the system becomes both faster and cheaper than the baseline.

## Architecture

Virtual Context sits in front of any OpenAI-compatible API as a transparent proxy. Integration requires changing one base URL — no SDK rewrite needed.

### Pipeline Stages

1. **Segmenter**: Breaks conversation history into topic-coherent chunks using semantic similarity and topic drift detection.
2. **Compactor**: Applies hierarchical compression in two tiers. Tier 1 produces segment summaries and extracts structured facts (entities, preferences, decisions, relationships). Tier 2 merges related segments into topic-level summaries.
3. **Retriever**: Uses 3-signal reciprocal rank fusion (recency decay, embedding similarity, BM25 keyword match) to select the most relevant memory for the current request.
4. **Assembler**: Reconstructs the prompt by weaving together recent turns, retrieved summaries, structured facts, and system context within the model's token budget.

### Storage

- SQLite for single-instance deployments
- PostgreSQL for production multi-tenant setups
- Redis for session caching in proxy mode

## Engine Internals

### Hierarchical Compression

Conversation history is compressed in tiers rather than all at once. When a segment grows beyond its token budget, Tier 1 compaction produces a summary and structured metadata. When multiple Tier 1 segments share a topic, Tier 2 merges them into a consolidated topic summary. Original text is preserved and recoverable through demand paging.

### Structured Fact Extraction

During compaction, the system extracts structured facts from conversation content:
- **Personal facts**: User preferences, roles, goals, background
- **Experience facts**: Activities, trips, events with dates and locations
- **World facts**: External knowledge, technical decisions, project states

Each fact has a subject, verb, object, optional date, optional location, and temporal status (active, completed, planned, recurring, abandoned).

### Retrieval

The retriever combines three signals via reciprocal rank fusion:
- **Recency**: Exponential decay favoring recent segments
- **Similarity**: Embedding-based semantic match against the current query
- **Keyword**: BM25 scoring for exact term matches

Retrieved segments are assembled into the prompt with budget-aware truncation.

### Demand Paging

When a model needs information from a compacted segment, it can request the original text via a tool call. The system pages in the full original content, similar to how an OS pages virtual memory from disk to RAM.

## Interfaces

- **HTTP proxy**: sits between any LLM client and the upstream provider, auto-detecting Anthropic, OpenAI and Gemini request formats. Listens on 127.0.0.1:5757 by default.
- **MCP server**: exposes 8 tools for Claude Desktop, Cursor and other MCP clients — `recall_context`, `compact_context`, `expand_topic`, `recall_all`, `remember_when`, `find_quote`, `search_summaries`, `domain_status`.
- **Proxy tool loop**: exposes a separate set of 8 tools to the model during a request — `vc_expand_topic`, `vc_find_quote`, `vc_find_session`, `vc_search_summaries`, `vc_query_facts`, `vc_recall_all`, `vc_remember_when`, `vc_restore_tool`. These are distinct from the MCP tool set.
- **Python SDK**: `on_message_inbound()` before the model call, `on_turn_complete()` after, plus `ingest_document()`.

## Proxy

The proxy provides conversation continuity across sessions:
- Streaming passthrough with SSE event forwarding
- History ingestion for attaching existing conversations
- Multi-instance routing with Redis session affinity
- Error-resilient routing with automatic failover
- Compatible with Anthropic, OpenAI, Gemini, Groq, Mistral, Together, and any OpenAI-compatible endpoint

## Installation

```bash
pip install virtual-context
```

Python 3.11 or newer.

## Configuration

Configuration covers storage backend, tagging and summarization models, retrieval scoring weights, compaction thresholds, and context assembly budgets. Parameter names and defaults are documented at https://virtual-context.com/docs/configuration/, which tracks the engine's configuration dataclasses.

## Hosted Access

Seven provider subdomains route to different upstreams: `anthropic`, `openai`, `gemini`, `groq`, `mistral`, `together` and `openrouter`, each at `*.virtual-context.com`. Authenticate with the `?vckey=` query parameter; your provider API key stays in the header as usual.

## Pricing

- **Free**: 2M token context window, 1 conversation, 50 requests/day, community support
- **Pro** ($19/month): 10M token window, unlimited conversations and requests, priority support, session analytics
- **Team** ($99/month): 100M token window, 5 seats, shared memory namespaces, dedicated support

## Links

- Homepage: https://virtual-context.com/
- Research Paper: https://virtual-context.com/paper/
- Documentation: https://virtual-context.com/docs/
- Architecture: https://virtual-context.com/docs/architecture/
- Engine: https://virtual-context.com/docs/engine/
- Proxy: https://virtual-context.com/docs/proxy/
- Benchmarks: https://virtual-context.com/docs/benchmarks/
- Commands: https://virtual-context.com/docs/commands/
- Configuration: https://virtual-context.com/docs/configuration/
- GitHub: https://github.com/virtual-context/virtual-context
- PyPI: https://pypi.org/project/virtual-context/
- Pricing: https://virtual-context.com/pricing/
- Contact Sales: https://virtual-context.com/contact-sales/
- About: https://virtual-context.com/about/

## Citation

Kidwai, Y. Ahmed. Virtual Context: Unbounded Context for LLM Agents via OS-Style Memory Management. Virtual Context, March 21, 2026. https://virtual-context.com/paper/