Documentation
Everything you need to integrate ContextQ into your workflow.
01Overview
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 16 tools for saving, searching and listing context, booting and checkpointing agent sessions, and working a shared goal board. Dream synthesis, updates and administration are available through the REST API.
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 and encrypted in transit (TLS).
02API 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:
03MCP Tools Reference
The hosted endpoint https://app.contextq.dev/mcp exposes 16 MCP tools across 4 groups. Your agent discovers them automatically after connecting. Below: an at-a-glance index, parameters for the memory tools, and a compact reference for the rest.
For full request/response schemas, see app.contextq.dev/docs.
At a glance
| Group | Tools |
|---|---|
| Memory | ctx_save, ctx_search, ctx_get, ctx_list |
| Session | agent_boot, agent_checkpoint, agent_handoff, agent_handoff_save |
| Goal board | goal_add, goal_advance, goal_frontier, goal_list, goal_sync_relay |
| Workspace | ctx_workspace_list, ctx_workspace_ensure, ctx_project_ensure |
Memory
ctx_save
Save a new context entry.
| Parameter | Type | Description |
|---|---|---|
| name | string (required) | Short, descriptive title. |
| description | string (required) | One-line summary used for search ranking. |
| content | string (required) | Full content / body of the entry. Markdown supported. |
| type | enum (required) | reference | feedback | project | incident | lesson | user | synthesis |
| workspace | string (required) | Workspace that owns the entry. |
| scope | enum | personal | workspace | team. Defaults to personal. |
| project | string | Optional project within the workspace. |
| tags | string[] | Tags for categorization and filtering. |
| metadata | object | Arbitrary key-value pairs (source, author, etc.). |
ctx_search
Search entries with hybrid full-text and vector similarity, fused with Reciprocal Rank Fusion.
| Parameter | Type | Description |
|---|---|---|
| query | string (required) | Search query. Natural language or keywords. |
| workspace | string | Filter by workspace. |
| project | string | Filter by project. |
| type | enum | Filter by context type. |
| tags | string[] | Filter by tags (all must match). |
| scope | enum | Filter by visibility scope. |
| limit | number | Maximum results to return (default: 20). |
| offset | number | Offset for pagination. |
ctx_get
Retrieve a single context entry by its ID.
| Parameter | Type | Description |
|---|---|---|
| id | number (required) | The entry ID to retrieve. |
ctx_list
List entries without a search query.
| Parameter | Type | Description |
|---|---|---|
| workspace | string | Filter by workspace. |
| project | string | Filter by project. |
| type | enum | Filter by context type. |
| tag | string | Filter by a single tag. |
| scope | enum | Filter by visibility scope. |
| limit | number | Maximum results to return (default: 20). |
| offset | number | Offset for pagination. |
Session
agent_bootOne call at session start: last checkpoint, open tasks, latest handoff, relevant lessons and facts.agent_checkpointSnapshot the agent's working state so a restart can resume from exactly there.agent_handoffGenerate an end-of-run handoff (TL;DR, in progress, next steps) for the workspace. LLM-written, so it needs a paid plan; on Free it returns a skipped handoff.agent_handoff_saveSave a handoff you wrote yourself, keyed so a re-run updates the same entry. No LLM, available on every plan.
Goal board
goal_addAdd a node to the goal graph, a durable board that outlives any one session.goal_advanceAdvance a node's status; a leaf moving to done requires evidence.goal_frontierThe ready frontier: nodes whose blocking dependencies are all done.goal_listList goal-graph nodes filtered by lane, status or kind.goal_sync_relayCarry one request for the local task-board sync engine when it runs in relay mode.
Workspace
ctx_workspace_listList the workspaces this credential can write to.ctx_workspace_ensureGet or create a workspace, idempotently.ctx_project_ensureGet or create a project inside a workspace, idempotently.
Dream synthesis (REST)
POST /api/dream
LLM-assisted pass over a workspace. Clusters related entries, writes durable summaries, and archives the originals. Not an MCP tool: call it with an API key that has admin scope. Free workspaces get one manual dream every 14 days, without synthesis preview or auto-trigger; paid plans are unlimited and dream automatically.
| Parameter | Type | Description |
|---|---|---|
| workspace | string (required) | Workspace to consolidate. |
| project | string | Limit the pass to one project. |
| dryRun | boolean | Preview changes without applying them (default: false). |
| minAgeDays | number | Only consider entries at least this old (default: 30). |
| autoArchive | boolean | Archive the originals a summary supersedes (default: true). |
04Authentication
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 each key inherits the permissions of the team it belongs to. On Claude Code, the installer in Getting Started mints a key through a one-time browser approval (device authorization) and stores it in Claude Code for you, on every plan. On every plan you can also create and revoke keys from the dashboard at app.contextq.dev. Every plan can create API keys; the cap counts active keys, and keys behind MCP OAuth connectors do not count. Key expiry and workspace-bound keys are available on every plan. IP allowlists on keys are available from Pro.
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.
05Plans and Limits
ContextQ offers four tiers. All plans include hybrid search (full-text + vector) and the core MCP tools. LLM-powered memory features are included from Pro.
| Feature | Free | Pro | Team | Enterprise |
|---|---|---|---|---|
| Context entries | 1,000 | 5,000 | 25,000 | Custom |
| Code contexts | 2,000 | 5,000 | 25,000 | Custom |
| Search + retrieve queries / month | 5,000 | 20,000 | 150,000 | Custom |
| Seats | 1 | 1 | 5 | Unlimited |
| Active API keys | 3 | 20 | Unlimited | Unlimited |
| Dream (memory consolidation) | 1 manual dream / 14 days | Unlimited dream, auto-triggered | Unlimited dream, auto-triggered | Unlimited dream, auto-triggered |
| CSV export | Yes | Yes | Yes | Yes |
| Webhooks | -- | Yes | Yes | Yes |
| Grounded answers | -- | Yes | Yes | Yes |
| Team mode | -- | -- | Yes | Yes |
| Priority support | -- | -- | Yes | Yes |
| SSO | -- | -- | -- | Yes |
| Audit log export | -- | -- | -- | Yes |
| AI memory features | -- | Yes | Yes | Yes |
| Search reranking | -- | -- | Yes | Yes |
| LLM query rewrite | -- | -- | -- | Yes |
| API key IP allowlist | -- | Yes | Yes | Yes |
Every new account starts with a 14-day Pro trial, no card required. When it ends, the account moves to Free unless you upgrade. See pricing for current rates.
06Self-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.
07Support
Need help? Here is how to reach us:
- Email: support@contextq.dev
- Enterprise SLA: Dedicated support with guaranteed response times is included on Enterprise plans.