Cont3xt
Virtual Infinite Context MCP Server
Ask AI about Cont3xt
Powered by Claude · Grounded in docs
I know everything about Cont3xt. Ask me about installation, configuration, usage, or troubleshooting.
0/500
Reviews
Documentation
cont3xt
Virtual Infinite Context for Agents and LLMs
An MCP server that maintains a continuous rolling context window, always surfacing the most relevant memories for the task at hand — while respecting your token budget.
Current Status
This repository includes an MVP MCP stdio server suitable for integration with the Cline extension for VS Code. It exposes a minimal, SQLite-only toolset over stdio with zero external services required by default.
- Version: 0.1.1
- Transport: MCP stdio
- Default storage: SQLite at ./data/memory.db (configurable; example config uses ./data/novel_memory.db)
- Optional backends: Qdrant / Neo4j (disabled by default in this MVP)
- Tools implemented:
- memory_upsert
- search_memory
- context_pack
- health_ping
Notes:
- Tool names use underscores for compatibility with the Python server decorator. Dotted aliases (e.g., context.pack) can be added later.
- All tools return a standard JSON envelope as text content: { "ok": boolean, "data": {...}, "meta": { "duration_ms": number, "backend": "sqlite", "version": "0.1.1" } }
Quickstart
1) Install
Requires Python 3.11+
git clone https://github.com/elevend0g/cont3xt.git
cd cont3xt
pip install -r requirements.txt
pip install -e .
2) Initialize local storage (SQLite)
virtual-context-mcp --init-db
This creates ./data/memory.db if it doesn’t exist (or the path specified by config/env).
3) Run (stdio transport)
virtual-context-mcp
This starts the MCP server over stdio.
Using with MCP Clients
Cline (VS Code)
Add an MCP server named cont3xt that launches the stdio server:
Example configuration shape (adapt for your Cline settings UI/JSON):
{
"mcpServers": {
"cont3xt": {
"command": "virtual-context-mcp",
"args": ["--config", "configs/novel_writing.yaml"],
"env": {
"CONTEXT_MAX_TOKENS": "12000",
"PYTHONUNBUFFERED": "1"
}
}
}
}
Notes:
- Ensure virtual-context-mcp is in PATH (pip install -e . creates the console script).
- The --config argument is optional; environment variables can override values (see Configuration).
Claude Desktop
{
"mcpServers": {
"cont3xt": {
"command": "virtual-context-mcp",
"args": ["--config", "configs/novel_writing.yaml"],
"env": {
"CONTEXT_MAX_TOKENS": "12000",
"PYTHONUNBUFFERED": "1"
}
}
}
}
Tools (MVP)
All tools return a JSON envelope as text content.
Envelope:
{
"ok": true,
"data": { /* tool-specific payload */ },
"meta": {
"duration_ms": 5.23,
"backend": "sqlite",
"version": "0.1.1"
}
}
1) memory_upsert
Upsert memory for a session from either combined content or a user/assistant pair.
Arguments:
- session_id: string (required)
- content: string (optional; direct content)
- user_input: string (optional; used if content not provided)
- assistant_response: string (optional; used if content not provided)
Response (example):
{
"ok": true,
"data": {
"session_id": "sess-1",
"ids": ["b1c...f"],
"count": 1
},
"meta": {
"duration_ms": 1.23,
"backend": "sqlite",
"version": "0.1.1"
}
}
2) search_memory
Simple substring search with a recency-biased score over recent SQLite chunks.
Arguments:
- session_id: string (required)
- query: string (required)
- max_results: number (optional, default 10)
Response (example):
{
"ok": true,
"data": {
"query": "emerald eyes",
"results_count": 2,
"results": [
{
"chunk_id": "b1c...f",
"score": 1.7,
"timestamp": "2025-08-09T17:30:00.000000",
"token_count": 142,
"preview": "User: ... Assistant: ..."
}
]
},
"meta": {
"duration_ms": 2.45,
"backend": "sqlite",
"version": "0.1.1"
}
}
3) context_pack
Packs a token-budgeted context using recent conversation chunks. Reserves a small buffer and includes the current input if provided.
Arguments:
- session_id: string (required)
- current_input: string (optional, default "")
- budget_tokens: number (optional, defaults to CONTEXT_MAX_TOKENS)
Response (example):
{
"ok": true,
"data": {
"pack": {
"schema_version": "ctx.v1",
"budget_tokens": 12000,
"used_tokens": 2834,
"sections": [
{"role": "user", "title": "Current Input", "content": "..."},
{
"role": "context",
"title": "Conversation (2025-08-09T17:30:00.000000)",
"content": "...",
"chunk_id": "b1c...f",
"token_count": 142
}
],
"provenance": {
"retriever": "recent-only",
"stores": {"sqlite": "./data/memory.db"}
},
"pack_stats": {
"num_candidates": 12,
"kept": 4,
"dropped": 8,
"buffer_tokens": 500
}
},
"meta": {
"input_tokens": 120,
"output_tokens": 2834,
"budget": 12000,
"sources": ["b1c...f", "a9d...1"]
}
},
"meta": {
"duration_ms": 7.89,
"backend": "sqlite",
"version": "0.1.1"
}
}
Notes:
- If nothing fits within the budget (after a fixed buffer of 500 tokens), the pack includes:
"reason": "BUDGET_TOO_SMALL". - Truncation policy: respect budget strictly; sections are assembled most-recent-first, then presented chronologically for readability.
4) health_ping
Returns basic status and configuration fingerprint.
Arguments: none
Response (example):
{
"ok": true,
"data": {
"server": "cont3xt",
"version": "0.1.1",
"datetime": "2025-08-09T17:32:00.000000",
"config": {
"sqlite_path": "./data/memory.db",
"max_tokens": 12000,
"token_model": "cl100k_base",
"optional_backends": {
"qdrant": false,
"neo4j": false
}
}
},
"meta": {
"duration_ms": 0.41,
"backend": "sqlite",
"version": "0.1.1"
}
}
Cline Demo Task (Code Gen Flow)
- In Cline, run a task like “Improve function X in file Y; add a unit test and make tests pass.”
- Cline should:
- Call
search_memory(session_id, query="project goals") - Call
context_pack(session_id, current_input="<file diff request>", budget_tokens=12000) - Generate plan → apply small diff → run tests
- Call
memory_upsertwith(user_input, assistant_response)to persist the session outcome
- Call
- Acceptance:
- From a clean clone,
pip install -e ., launch Cline, and complete a guided code edit PR in one go using the above flow.
- From a clean clone,
Configuration
Defaults are provided in code, optionally loaded from a YAML file (e.g., configs/novel_writing.yaml) and overridden by environment variables.
Environment variable overrides (examples):
-
CONTEXT_MAX_TOKENS (default 12000)
-
CONTEXT_PRESSURE_THRESHOLD (default 0.8)
-
CONTEXT_RELIEF_PERCENTAGE (default 0.4)
-
CONTEXT_CHUNK_SIZE (default 3200)
-
CONTEXT_TOKEN_MODEL (default cl100k_base)
-
DATABASE_SQLITE_PATH (default ./data/memory.db)
-
DATABASE_QDRANT_URL
-
DATABASE_QDRANT_COLLECTION
-
DATABASE_NEO4J_URL
-
DATABASE_NEO4J_USER
-
DATABASE_NEO4J_PASSWORD
For the MVP, only SQLite is used. Qdrant / Neo4j are intentionally not required; future versions can enable them via env/config flags.
Truncation policy:
- A fixed buffer of 500 tokens is reserved.
- Packing order: include current_input (if provided) and then pack recent conversation chunks until the budget is met.
- If no sections can be included, the pack includes
"reason": "BUDGET_TOO_SMALL".
Development
Entry points:
- Console script: virtual-context-mcp → virtual_context_mcp.main:main
- MCP server class: virtual_context_mcp.server:VirtualContextMCPServer
Local logs: standard output (set PYTHONUNBUFFERED=1 for real-time logs). SQLite file: ./data/memory.db by default.
Run unit/integration tests as needed (note that legacy story-focused modules may not reflect the MVP surface area).
Security
- MVP runs in a safe default mode: only persists to local SQLite.
- No filesystem ingestion or external network writes by default.
Roadmap
- Optional Qdrant/Neo4j integration behind env flags with graceful fallback.
- Aliased/dotted tool names for compatibility (e.g., context.pack).
- Richer retrieval (hybrid, deduplication), entity/graph memory, and pressure relief policies.
- DevContainer / Docker image for reproducible environments.
License
MIT © elevend0g
