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 31 tools for saving, searching, linking, synthesizing, 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 and encrypted in transit (TLS) and at rest.
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:
MCP Tools Reference
ContextQ exposes 31 MCP tools across seven groups. Your agent discovers them automatically after connecting. Below: an at-a-glance index, detailed schemas for the Core CRUD operations and Dream, and a compact reference for the rest.
For full request/response schemas of every tool, see api.contextq.dev/docs.
At a glance
| Group | Tools |
|---|---|
| Core CRUD | ctx_save, ctx_search, ctx_list, ctx_get, ctx_update, ctx_delete, ctx_bulk_update |
| Bulk + stats | ctx_import, ctx_stats |
| PKM | ctx_dream, ctx_link, ctx_links, ctx_evolve, ctx_chunks, ctx_mocs, ctx_regenerate_mocs |
| Saved searches | ctx_saved_searches_list, ctx_saved_searches_create, ctx_saved_searches_get, ctx_saved_searches_update, ctx_saved_searches_delete, ctx_saved_searches_run, ctx_run_saved_search |
| Ingest | ctx_ingest, ctx_ingest_status |
| Events / review | ctx_events_recent, ctx_memory_review_logs, ctx_memory_review_run |
| Admin | ctx_admin_rate_limit_get, ctx_admin_rate_limit_set, ctx_audit_cleanup_run |
Core CRUD
ctx_save
Save a new context entry.
| Parameter | Type | Description |
|---|---|---|
| name | string (required) | Short identifier for the entry. |
| description | string (required) | One-line summary surfaced in search results. |
| content | string (required) | The knowledge to store. Markdown supported. |
| type | enum (required) | reference | feedback | project | incident | lesson | synthesis | map | moc | user |
| company | string (required) | Tenant / company slug the entry belongs to. |
| scope | enum | company | personal — sharing scope. |
| project | string | Optional project slug for finer scoping. |
| tags | string[] | Tags for categorization and filtering. |
| metadata | object | Arbitrary key-value pairs (source, author, etc.). |
| lifecycle | enum | fleeting | working | evergreen | archived. Defaults to working. |
| valid_from | timestamp | Bi-temporal validity start. |
| valid_to | timestamp | Bi-temporal validity end. |
ctx_search
Search entries using hybrid full-text and vector similarity, fused with Reciprocal Rank Fusion.
| Parameter | Type | Description |
|---|---|---|
| query | string (required) | Search query. Natural language or keywords. |
| company | string | Scope to a specific company/tenant. |
| tags | string[] | Filter results to entries with these tags. |
| limit | number | Maximum results to return (default: 10). |
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, metadata, or lifecycle.
| 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. |
| lifecycle | enum | fleeting | working | evergreen | archived. |
ctx_delete
Delete a context entry by ID.
| Parameter | Type | Description |
|---|---|---|
| id | string (required) | The entry ID to delete. |
Dream synthesis
ctx_dream
LLM-assisted pass over your contexts. Clusters related entries, writes durable summaries, surfaces actionable insights. Available on Pro and above; Free is limited to one run per day.
| Parameter | Type | Description |
|---|---|---|
| dry-run | boolean | Preview changes without applying them (default: false). |
Other tools
The remaining tools cover bulk operations, the Personal Knowledge Management (PKM) layer, saved searches, ingest pipelines, event streams, and admin controls. Schemas at api.contextq.dev/docs.
Core CRUD & bulk
ctx_list— List entries with filters and pagination.ctx_bulk_update— Update lifecycle or archive flag on up to 200 entries at once.ctx_import— Bulk import entries from a file or structured payload.ctx_stats— Usage statistics: entry count, storage, search volume.
PKM
ctx_link— Create a typed link between two entries.ctx_links— List incoming/outgoing links for an entry.ctx_evolve— Run memory evolution (auto-archive, auto-organize) on a slice.ctx_chunks— Inspect chunk-level breakdown of an entry.ctx_mocs— List Maps of Content (MOCs) for a tenant.ctx_regenerate_mocs— Trigger MOC regeneration from current entries.
Saved searches
ctx_saved_searches_list— List saved searches owned by you or shared with the tenant.ctx_saved_searches_create— Save a query with its filters under a name.ctx_saved_searches_get— Retrieve a saved search by ID.ctx_saved_searches_update— Update a saved search you own.ctx_saved_searches_delete— Delete a saved search you own.ctx_saved_searches_run— Run a saved search by ID.ctx_run_saved_search— Run a saved search by name.
Ingest
ctx_ingest— Extract atomic claims from a URL or document and merge into the tenant's memory.ctx_ingest_status— Poll an in-flight ingest job.
Events / review
ctx_events_recent— Recent events from the tenant event bus (created/updated/archived/linked).ctx_memory_review_logs— Read memory-review verdicts (keep/retag/merge/archive/contradict).ctx_memory_review_run— Trigger a memory-review pass on a slice.
Admin
ctx_admin_rate_limit_get— Read the rate-limit bucket for a tenant.ctx_admin_rate_limit_set— Set per-tenant rate-limit capacity / refill.ctx_audit_cleanup_run— Manually run audit log retention cleanup (superadmin).
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_KEYAPI 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 four tiers. All plans include hybrid search (full-text + vector) and the core MCP tools.
| Feature | Free | Pro | Team | Enterprise |
|---|---|---|---|---|
| Context entries | 1,000 | 10,000 | 50,000 | Unlimited |
| Team seats | 1 | 1 | 5 (+$9 each) | Unlimited |
| Dream synthesis | 1 / day | 200 / mo | 1,000 / mo | Unlimited |
| Memory evolution (auto-archive, auto-organize) | -- | Yes | Yes | Yes |
| External LLM (Claude Sonnet) | -- | Yes | Yes | Yes + BYOK |
| Audit log retention | 7 days | 90 days | 365 days | Custom |
| Audit log CSV export | -- | Yes | Yes | Yes |
| Custom domain | -- | -- | -- | Yes |
| SSO / SAML | -- | -- | -- | Yes |
| Uptime SLA | -- | -- | 99.5% | 99.9% custom |
| Self-hosted | -- | -- | -- | Yes |
| Support | Community | Priority email | Dedicated |
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:
- Email: support@contextq.dev
- GitHub: github.com/contextq — file issues or feature requests
- Enterprise SLA: Dedicated support with guaranteed response times is included on Enterprise plans.