Documentation

Quick Start (Cloud)

Add your VC token as a query parameter to the base URL. Your provider API key stays in the header as usual.

import anthropic
client = anthropic.Anthropic(
  base_url="https://anthropic.virtual-context.com?vckey=vc-YOUR_KEY"
  # api_key uses your normal Anthropic key
)

from openai import OpenAI
client = OpenAI(
  base_url="https://openai.virtual-context.com/v1?vckey=vc-YOUR_KEY",
  # api_key uses your normal OpenAI key
)

curl https://anthropic.virtual-context.com/v1/messages?vckey=vc-YOUR_KEY \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "content-type: application/json" \
  -d '{"model":"claude-sonnet-4-20250514","max_tokens":1024,"messages":[{"role":"user","content":"Hello"}]}'

The ?vckey= parameter identifies your VC tenant. Your target adjusted context window is sent to the LLM provider.

Self-Hosted Install

Python 3.11 or newer. Runs on macOS, Linux, and WSL. Every core dependency, including the proxy server, ships in the base install; the extras below only add storage backends and the proxy session cache.

pip install virtual-context

# Optional extras
pip install "virtual-context[postgres]"    # PostgreSQL backend
pip install "virtual-context[redis]"       # Redis session cache for the proxy
pip install "virtual-context[neo4j]"       # Neo4j backend
pip install "virtual-context[falkordb]"    # FalkorDB backend
pip install "virtual-context[all]"         # postgres + redis

Setting storage.backend: postgres requires the postgres extra.

macOS and Linux

curl -fsSL https://raw.githubusercontent.com/virtual-context/virtual-context/main/scripts/install.sh | bash

# Guided setup: writes a config, picks a tagger provider,
# and optionally installs the background daemon
virtual-context onboard --upstream https://api.anthropic.com

# Or start from a preset without the wizard
virtual-context init coding
virtual-context config validate

Windows (PowerShell)

iwr https://raw.githubusercontent.com/virtual-context/virtual-context/main/scripts/install.ps1 -useb | iex

virtual-context onboard --upstream https://api.anthropic.com

Run as a background daemon

One command installs the platform service (launchd on macOS, a systemd user unit on Linux) and starts it. The daemon serves the proxy on port 5757; multi-instance configurations set their ports per instance.

virtual-context daemon install --upstream https://api.anthropic.com

# Lifecycle
virtual-context daemon status
virtual-context daemon restart
virtual-context daemon stop
virtual-context daemon uninstall

Add --no-start to write the service files without starting immediately. Omit --upstream when the upstream is already set per instance in your config.

Config discovery

Commands look for virtual-context.yaml starting in the working directory and walking up to your home directory, then fall back to ~/.virtualcontext/config.yaml. The .yml and .json suffixes and the virtualcontext. prefix are also accepted. Pass -c <path> to select a file explicitly.

HTTP Proxy

The proxy sits between any LLM client and the upstream provider. It auto-detects Anthropic, OpenAI, and Gemini request formats.

# Start proxy (defaults to 127.0.0.1:5757)
virtual-context proxy --upstream https://api.anthropic.com

# Multi-instance: separate ports per provider
virtual-context proxy \
  --upstream https://api.anthropic.com \
  --port 5757 \
  --config ./anthropic.yaml &
virtual-context proxy \
  --upstream https://api.openai.com \
  --port 5758 \
  --config ./openai.yaml &

Session continuity: sessions resume across proxy restarts via SQLite persistence. Tool interception: large tool results (git diff, test output) are auto-truncated to head+tail and indexed into FTS5 for full-text search.

MCP Server

Works with Claude Desktop, Cursor, and any MCP-compatible client.

# Add to claude_desktop_config.json
{
  "mcpServers": {
    "virtual-context": {
      "command": "virtual-context",
      "args": ["mcp"]
    }
  }
}

Tools: recall_context, recall_all, find_quote, query_facts, expand_topic, collapse_topic

Resources: virtual-context://status, virtual-context://domains

Prompts: summarize_session, recall_topic

Python SDK

from virtual_context import VirtualContextEngine

engine = VirtualContextEngine(config_path="./virtual-context.yaml")

# Before sending to LLM: enrich with memory
assembled = engine.on_message_inbound(user_message, history)

# After LLM response: tag, segment, compact
report = engine.on_turn_complete(full_history)

# Ingest external documents
engine.ingest_document("meeting-notes.pdf")

CLI Reference

Configuration

Config is loaded from virtual-context.yaml in the working directory, or passed via --config flag.

# virtual-context.yaml
storage:
  backend: sqlite
  path: ./vc-store.db

compaction:
  watermark: 0.7          # compact when 70% of budget used
  protected_turns: 6      # never compact the last N turns
  budget_tokens: 128000

tagging:
  provider: ollama         # or openai, anthropic
  model: nomic-embed-text  # embedding model for inbound tagger
  max_tags: 5

retrieval:
  tools: true              # expose vc_* tools to the LLM
  max_context_tokens: 32000

Provider Routing (Cloud)

Use subdomains to route to different LLM providers. Append ?vckey=vc-YOUR_KEY to any URL below.

The ?vckey= parameter identifies your VC tenant. Your target adjusted context window is sent to the LLM provider.