Documentation

Everything you need to integrate ContextQ into your workflow.

Overview

ContextQ is a shared context database for AI coding agents. It gives tools like Claude Code, Cursor, Codex, Gemini CLI, Windsurf, and Cline persistent, searchable memory that survives across conversations and projects.

Under the hood, ContextQ is an HTTP-based MCP server. Your agent connects to it like any other MCP tool and gets access to 9 tools for saving, searching, and managing context entries.

Architecture

Context entries are stored in PostgreSQL with pgvector for embedding-based similarity search. Full-text search is powered by Elasticsearch. When you search, ContextQ runs both engines in parallel and fuses the results using Reciprocal Rank Fusion (RRF) to return the most relevant matches.

All data is tenant-isolated with row-level security. On Pro and Enterprise plans, entry content is encrypted at rest with AES-256.

API Reference

ContextQ provides both an MCP interface (for AI agents) and a REST API (for programmatic access, dashboards, and integrations).

The full REST API documentation, including request/response schemas and interactive examples, is available at:

api.contextq.dev/docs

MCP Tools Reference

The MCP server exposes 9 tools. Your agent discovers these automatically after connecting. Below is a detailed reference for each tool, including parameters.

ctx_save

Save a new context entry.

Parameter Type Description
content string (required) The knowledge to store.
tags string[] Tags for categorization and filtering.
metadata object Arbitrary key-value pairs (project, source, author).

ctx_search

Search entries using hybrid full-text and vector similarity.

Parameter Type Description
query string (required) Search query. Natural language or keywords.
tags string[] Filter results to entries with these tags.
limit number Maximum results to return (default: 10).

ctx_list

List all context entries with optional filtering and pagination.

Parameter Type Description
tags string[] Filter by tags.
limit number Maximum entries to return (default: 20).
offset number Number of entries to skip for pagination.

ctx_get

Retrieve a single context entry by its ID.

Parameter Type Description
id string (required) The entry ID to retrieve.

ctx_update

Update an existing entry's content, tags, or metadata.

Parameter Type Description
id string (required) The entry ID to update.
content string New content to replace existing.
tags string[] Updated tags (replaces existing tags).
metadata object Updated metadata key-value pairs.

ctx_delete

Delete a context entry by ID.

Parameter Type Description
id string (required) The entry ID to delete.

ctx_import

Bulk import context entries from a file or structured data.

Parameter Type Description
entries object[] (required) Array of entries, each with content and optional tags/metadata.
source string Label for the import source (e.g., "confluence", "notion").

ctx_stats

View usage statistics: entry count, storage used, and search volume.

No parameters required.

ctx_dream

AI-powered context consolidation and insight generation. Analyzes your stored entries, merges duplicates, identifies patterns, and surfaces actionable insights. Available on Pro and Enterprise plans.

Parameter Type Description
dry-run boolean Preview changes without applying them (default: false).

Authentication

ContextQ uses two authentication methods depending on the interface:

API Keys (MCP and REST API)

All MCP and REST API requests are authenticated with a Bearer token. Include your API key in the Authorization header: 

Authorization: Bearer YOUR_API_KEY

API keys are scoped to a team and can be created or revoked from the dashboard at app.contextq.dev. Each key inherits the permissions of the team it belongs to.

JWT (Dashboard)

The web dashboard at app.contextq.dev uses JWT-based session authentication. Tokens are issued on login and refreshed automatically. You do not need to manage JWTs directly — this is handled by the dashboard client.

Plans and Limits

ContextQ offers three tiers. All plans include hybrid search and the core MCP tools.

Feature Free Pro Enterprise
Context entries 100 10,000 Unlimited
Team members 1 10 Unlimited
Hybrid search Yes Yes Yes
Vector search -- Yes Yes
Dream (AI consolidation) -- Yes Yes
Content encryption -- AES-256 AES-256
SSO / SAML -- -- Yes
Self-hosted -- -- Yes

See pricing for current rates and trial details.

Self-hosted

For organizations that need to keep data on their own infrastructure, ContextQ offers a self-hosted deployment option on the Enterprise plan.

The self-hosted distribution ships as a Docker Compose stack that includes the API server, PostgreSQL with pgvector, and Elasticsearch. You provide your own hardware or cloud instances; ContextQ handles the application layer.

To discuss self-hosted deployment, reach out to the team at support@contextq.dev.

Support

Need help? Here is how to reach us: