Context Engine gives your AI a complete, always-current understanding of your codebase — across every file, symbol, commit, and repository — so you can stop re-explaining things and start shipping faster.

The Problem

Every time you open a new chat with an AI assistant, you start from zero. You paste files, re-explain architecture, describe relationships between modules, and hope the model understands enough context to give a useful answer. On large codebases, this breaks down fast.

Context Engine solves this by indexing your entire codebase into a hybrid semantic + lexical search layer with a symbol graph and persistent memory. Your AI tools query this index directly via the Model Context Protocol (MCP), getting precise, grounded answers without requiring you to feed it context manually.

How It Works

Your Codebase
(files, git history, dependencies, docs)
        ↓
  Context Engine Index
  ┌─────────────────────────────────────┐
  │  Qdrant Vector Store             │
  │  Symbol Graph (call/import graph)│
  │  Memory Store (persistent notes) │
  └─────────────────────────────────────┘
        ↓
  MCP Tools (exposed to your AI client)
  repo_search · symbol_graph · context_answer
  memory_store · memory_find · cross_repo_search
        ↓
  Claude · Cursor · Windsurf · Copilot · Kiro
  (any MCP-compatible client)

Your code is indexed once — either automatically via the VS Code extension or manually via the CLI — and then every AI query is grounded in live, up-to-date context.

Core Capabilities

Semantic Code Search

repo_search finds code by meaning, not just keywords. Ask for "authentication token refresh logic" and get the right file and function, even if the code never uses those exact words.

Symbol Graph Navigation

symbol_graph lets your AI navigate callers, callees, definitions, importers, and inheritance chains. Ask who calls a function, what a class inherits from, or what would break if you change a method.

Natural Language Q&A

context_answer retrieves the relevant code spans and generates a cited explanation. Your AI answers questions like "how does the rate limiter decide when to reject requests?" with references to the actual implementation.

Cross-Repo Search

cross_repo_search traces data flow across repository boundaries — from a frontend API call to the backend handler that processes it — without switching contexts.

Persistent Memory

memory_store and memory_find let your AI remember architectural decisions, known gotchas, and team conventions across sessions. Knowledge accumulates rather than being lost at the end of each conversation.

By the Numbers

Supported AI Clients

Context Engine works with any tool that supports the Model Context Protocol (MCP):

• Claude (claude.ai, Claude Code CLI)
• Cursor
• Windsurf
• GitHub Copilot
• Kiro
• Any other MCP-compatible client

Deployment Options

SaaS — The fastest way to get started. Install the VS Code extension and your workspace is indexed automatically. No infrastructure to manage.

Self-Hosted (Singular Mode) — Run the full stack on your own infrastructure. Your code never leaves your network. Ideal for teams with data sovereignty requirements or private codebases.

Enterprise — Dedicated infrastructure with advanced graph query support (Memgraph-backed), higher indexing throughput, and SLA guarantees.

See Plans & Tiers for a full comparison.

Next Steps

• Get Started in 5 minutes — create an API key and connect your first repository
• Install the VS Code Extension — automatic indexing on every save
• Configure MCP — connect Context Engine to your AI client
• Developer Prompt Guide — learn which tools to use for which tasks

Plans & Tiers

Choose the right plan for your team.

Individual

For personal projects.

• 1 member
• 3 collections
• 2 API keys
• 100 MB storage

Team

For small teams.

• 5 members
• 10 collections
• 5 API keys
• 5 GB storage

Business

For growing teams.

• 15 members
• 30 collections
• 15 API keys
• 10 GB storage

Organization

For companies.

• 25 members
• 50 collections
• 25 API keys
• 20 GB storage

Enterprise

For large organizations.

• Unlimited members
• Unlimited collections
• Unlimited API keys
• Unlimited storage
• SSO & audit export

Getting Started with Context-Engine

Set up code intelligence for your projects in minutes.

Step 1: Create an API Key

Generate an API key to authenticate the VS Code extension and MCP tools. Use write scope for the extension and MCP tools, or admin scope for full workspace management.

Go to your workspace's API Keys page to create one.

Step 2: Install the VS Code Extension

The VS Code extension automatically indexes your codebase and keeps it in sync as you work.

• VS Code Marketplace
• Open VSX (Cursor, Windsurf)
• CLI (npm)

Step 3: Configure the Extension

Open VS Code Settings (Cmd+, or Ctrl+,) and search for contextEngineUploader. The server URLs are pre-filled — you only need to paste your API key:

Alternatively, you can edit settings.json directly — see the VS Code Extension section for the JSON format.

Step 4: Index Your Codebase

Open the Command Palette (Cmd+Shift+P) and run Context Engine Uploader: Index Codebase. The extension will upload and index your code, then start watching for changes.

Step 5: Connect Your AI Tools

Configure MCP in Claude Code, Codex, OpenCode, Cursor, or other AI tools to enable code-aware assistance. See the MCP Configuration section for details.

API Keys

API keys authenticate your tools (VS Code extension, MCP clients, CI pipelines) with Context-Engine. Each key is scoped to your workspace and can be configured with different permissions. Keys start with the prefix ctxce_.

Key Scopes

Where to Use Your API Key

Best Practices

• Use minimal scope: Create keys with only the permissions needed
• Rotate regularly: Rotate keys periodically, especially after team changes
• Name descriptively: Use names like "VS Code - John's Laptop" or "CI Pipeline"
• Revoke unused keys: Delete keys that are no longer in use

CLI Quick Connect

If you prefer the command line or don't use VS Code, you can use the ctxce CLI to connect and index your workspace:

# Install the CLI
npm install -g @context-engine-bridge/context-engine-mcp-bridge

# Connect, index, and watch for changes (runs in foreground)
ctxce connect YOUR_API_KEY

# Or specify a different workspace path
ctxce connect YOUR_API_KEY -w /path/to/your/repo

The ctxce connect command will authenticate, index your codebase, and continuously watch for file changes. Press Ctrl+C to stop.

CLI Options

Installation

Install the Context-Engine extension from the VS Code Marketplace, Open VSX (for Cursor, Windsurf), or use the CLI:

• VS Code Marketplace
• Open VSX (Cursor, Windsurf)
• CLI (npm)

Cloud Configuration

Configure the extension using either the VS Code Settings UI or by editing settings.json directly. Both methods are equivalent.

Option A: Settings UI (recommended)

Open Settings (Cmd+, / Ctrl+,) and search for contextEngineUploader. The server URLs come pre-filled — you only need to paste your API key:

Option B: Edit settings.json

Open the Command Palette (Cmd+Shift+P) and run Preferences: Open User Settings (JSON), then add:

{{
  "contextEngineUploader.endpoint": "{{BASE_URL}}/upload",
  "contextEngineUploader.authSharedToken": "ctxce_YOUR_API_KEY",
  "contextEngineUploader.authBackendUrl": "{{BASE_URL}}",
  "contextEngineUploader.mcpIndexerUrl": "{{BASE_URL}}/indexer/mcp",
  "contextEngineUploader.mcpMemoryUrl": "{{BASE_URL}}/memory/mcp",
  "contextEngineUploader.mcpServerMode": "direct",
  "contextEngineUploader.mcpTransportMode": "http"
}}

Key Settings Reference

All settings use the prefix contextEngineUploader. in VS Code settings.

Features

• Auto-sync: Automatically indexes your codebase when you open a project
• Incremental updates: Only uploads changed files to minimize bandwidth
• Smart ignore: Respects .gitignore and excludes build artifacts, node_modules, etc.
• Git history: Indexes commit history for change lineage queries
• MCP config writer: Auto-generates MCP configs for Claude Code, Windsurf, Cursor, and more
• Status bar: Shows sync status and collection info in the VS Code status bar

What is MCP?

The Model Context Protocol (MCP) allows AI assistants to access your indexed codebase. This enables code-aware responses, accurate file references, and intelligent code search.

Context-Engine exposes two MCP servers:

• Indexer (/indexer/mcp) — code search, symbol graph, pattern matching, cross-repo search
• Memory (/memory/mcp) — persistent notes, team knowledge, session context

Authentication

All MCP endpoints require authentication via Authorization: Bearer header with your API key. A key with write scope covers search, queries, uploads, and memory storage. Use admin scope for full workspace management.

LLM Providers (BYOK)

Context-Engine includes a built-in LLM for query expansion and answer generation. BYOK (Bring Your Own Key) lets you offload some LLM work to your own provider, which increases your usage limits as a discount for reducing load on our infrastructure.

Note: BYOK does not eliminate all costs. Embeddings, vector storage, and other infrastructure costs still apply. BYOK only offloads specific LLM-powered tools (query expansion, context answers, info requests).

Built-in LLM vs BYOK

Built-in LLM:

• No configuration required
• Included in all plans
• Standard usage limits

With BYOK:

• Use your own API keys
• Increased usage limits
• Choose your preferred models

Supported Providers

Tools Using BYOK

When configured, your API key is used for these specific tools:

• Query expansion: Enhancing search queries for better results
• Context answers: Generating answers grounded in your code
• Info requests: Providing explanations and summaries

Benefits of BYOK

• Higher limits: Increased usage allowances as a discount for offloading LLM work
• Model choice: Use specific models that work best for your codebase
• Compliance: Route LLM requests through your own account for audit trails

Manual MCP Configuration

Choose your AI tool and add Context-Engine MCP servers to its config.

Already using the VS Code extension? You can skip manual config. Run Context Engine Uploader: Write MCP Config from the Command Palette to auto-generate these files.

Config file locations

Standard JSON template (Claude Code, OpenCode, Cursor, Gemini)

{{
  "mcpServers": {{
    "context-engine": {{
      "url": "{{BASE_URL}}/indexer/mcp",
      "headers": {{"Authorization": "Bearer YOUR_API_KEY"}}
    }},
    "context-engine-memory": {{
      "url": "{{BASE_URL}}/memory/mcp",
      "headers": {{"Authorization": "Bearer YOUR_API_KEY"}}
    }}
  }}
}}

OpenAI Codex CLI (TOML format)

[features]
rmcp_client = true

[mcp_servers.context-engine]
url = "{{BASE_URL}}/indexer/mcp"

[mcp_servers.context-engine.http_headers]
Authorization = "Bearer YOUR_API_KEY"

[mcp_servers.context-engine-memory]
url = "{{BASE_URL}}/memory/mcp"

[mcp_servers.context-engine-memory.http_headers]
Authorization = "Bearer YOUR_API_KEY"

Augment (Auggie CLI)

auggie mcp add --replace --transport http --url "{{BASE_URL}}/indexer/mcp" --header "Authorization: Bearer YOUR_API_KEY" context-engine
auggie mcp add --replace --transport http --url "{{BASE_URL}}/memory/mcp" --header "Authorization: Bearer YOUR_API_KEY" context-engine-memory
auggie mcp list

Claude Code CLI alternative (instead of .mcp.json)

claude mcp add --transport http context-engine {{BASE_URL}}/indexer/mcp --header "Authorization: Bearer YOUR_API_KEY"
claude mcp add --transport http context-engine-memory {{BASE_URL}}/memory/mcp --header "Authorization: Bearer YOUR_API_KEY"

Cursor & Claude Desktop config file locations

• Claude Desktop: ~/.config/claude/claude_desktop_config.json
• Cursor: ~/.cursor/mcp.json

Use the standard JSON template above for both.

Auto-Generate MCP Configs (via VS Code Extension)

Skip manual config: If you already have the VS Code extension configured, you do not need to create the MCP config files by hand. The extension can generate them automatically.

Open the Command Palette (Cmd+Shift+P) and run Context Engine Uploader: Write MCP Config. The extension uses your current settings (endpoint, API key, URLs) to write the correct config files for:

• Claude Code (.mcp.json) — always generated
• Windsurf — enable with the mcpWindsurfEnabled setting
• Augment — enable with the mcpAugmentEnabled setting
• Gemini CLI — enable with the mcpAntigravityEnabled setting
• Cursor — enable with the mcpCursorEnabled setting

The manual configs are for tools that are not launched from within VS Code (e.g., Claude Code CLI, OpenAI Codex CLI, OpenCode) or if you prefer not to use the extension.

Available MCP Tools

Once connected, your AI assistant will have access to these tools:

This table maps what you want to do → what to say to the AI.

AI Agent Rules for Context Engine MCP

To get the best results from Context-Engine, your AI assistant needs to know how to use the MCP tools effectively. Copy the rules block below and paste it into your assistant's system prompt or configuration file.

Compatible with

• Claude Code (CLAUDE.md)
• Cursor (.cursorrules)
• Codex (.codex/instructions.md)
• Windsurf (.windsurfrules)
• Augment (AUGMENT_GUIDELINES.md)
• Gemini (GEMINI.md)
• Generic system prompts

Rules

Context Engine MCP quick rules

Shared guidance pattern:
- Keep one canonical shared MCP guidance document.
- Keep client/provider wrappers thin and scoped to runtime-specific notes.

Defaults:
- Start with search().
- Use symbol_graph first for direct callers, definitions, importers, and inheritance.
- Use graph_query only if your runtime exposes it and you need transitive impact,
  dependency, or cycle analysis.
- Use cross_repo_search for multi-repo questions.
- Use context_search(include_memories=true) when code and stored notes both matter.

File and grep policy:
- Prefer MCP tools for exploration and cross-file understanding.
- Narrow grep/file-open use is still acceptable for exact literal confirmation,
  exact file/path confirmation, or opening a file you already identified for editing.

Optional session setup:
- set_session_defaults(output_format="toon", compact=true, limit=5)

Good defaults:
- Discovery: limit=3, compact=true, per_path=1
- Deep dive: limit=5-8, include_snippet=true, context_lines=3-5
- Run unrelated lookups in parallel.

If your host runtime already provides notes, tasks, comments, or delegated-agent
workflows, use those host features instead of inventing repo-local tracking files
unless the user explicitly asks for repo-local files.

Basic: Find code by what it does

"Find where we validate user permissions in the codebase"

Show me the code that handles file uploads

Where do we send emails in this project?

Narrow by language or folder

Find database query functions in Python only

Show me error handling code inside the src/api/ directory

Find TypeScript interfaces related to user profiles

Find a specific function or class

Find the definition of the ConnectionPool class

Search for a function called normalize_path

Exclude noise (test files, generated code)

Find authentication code, but exclude test files and migrations

Show me payment processing logic — skip anything in vendor/ or tests/

Search with multiple angles (better recall)

Search for "rate limiting", "throttling", and "request quota" together — I'm trying to find all the rate control code

Why this works: Passing multiple query terms triggers query fusion — the engine searches all variants and merges the best results.

Scope to a specific repo (multi-repo setups)

Search only in the backend repo for authentication middleware

Find payment processing code across both the orders-service and billing-service repos

What it does: Instead of just returning code snippets, this tool reads the relevant code and explains it to you - with citations pointing to exact file locations. Think of it as asking a senior engineer who's read your whole codebase.

Use this when you want understanding, not just a code location.

Understand a feature end-to-end

Explain how the authentication flow works from login to JWT token issuance

How does the caching layer decide when to invalidate entries?

Walk me through what happens when a user submits a payment

Understand architectural decisions

How is our database connection pooling set up and why?

Explain the retry strategy used in the upload service

Debug-oriented understanding

How does the session management work? I'm trying to understand why sessions might expire early

Explain the token refresh logic - I'm seeing intermittent expiration errors

Difference from just searching

Use "Find..." when you want to navigate to code. Use "Explain..." or "How does..." when you want to understand it.

What it does: Navigates the call graph and import graph of your codebase. It answers questions like "who calls this?", "where is this defined?", "what does this call?", and "what inherits from this?"

Use this when you're about to change something and need to understand its blast radius, or when you're trying to trace how data flows through the system.

Find who calls a function

Who calls the authenticate() function?

Find all the places that call process_payment() in the codebase

What code calls our send_email() function?

Find where something is defined

Where is UserService defined?

Find the definition of the ConnectionPool class

Where is the MAX_RETRY_ATTEMPTS constant defined?

Find what a function calls internally

What does the run_pipeline() function call internally?

Show me what authenticate() depends on - what functions does it call?

Find what imports a module

What files import the auth_utils module?

What code imports CacheManager?

Trace inheritance hierarchies

What classes inherit from BaseModel?

What does UserService extend or inherit from?

Multi-hop: callers of callers

Find everything that calls authenticate(), and also what calls *those* callers - go 2 levels deep

Why this matters: If you're changing authenticate(), you need to know not just direct callers but indirect callers that might be affected.

Scoped relationship search

Who calls get_embedding_model() inside the scripts/ directory?

What TypeScript files import the AuthContext component?

What it does: Goes deeper than symbol_graph - it traverses the full dependency graph multiple hops deep, finds circular dependencies, and tells you exactly what would break if you changed something.

Note: This tool requires a graph database backend (Memgraph/Neo4j). It's available in Enterprise and some SaaS deployments. If it's not available, symbol_graph with depth=2 is your fallback.

Before a major refactor: "what breaks?"

Before I refactor the User model, what would break? Show the full impact 3 levels deep

I'm about to change the normalize_path function - what's the full blast radius?

Full dependency tree

Show me the complete dependency tree of run_hybrid_search() - everything it calls and everything those call

Give me a full call chain from the API endpoint down to the database layer for the login flow

Detect circular dependencies

Are there any circular dependencies involving the auth module?

Check if ServiceA has any circular imports

Multi-hop caller tracing

Find everyone who calls processPayment(), including indirect callers 2 levels up

search_tests_for - Finding tests

What it does: Specifically searches test files related to a feature or module. It pre-filters to test file patterns so you don't get production code in results.

Find the tests for the authentication module

Show me the unit tests for UserService

What tests cover the payment processing logic?

Find integration tests for the database connection handling

search_config_for - Finding configuration

What it does: Specifically searches config files (yaml, json, toml, env, ini). Useful when you need to find where something is configured without wading through source code.

Find the database connection configuration

Where is the JWT secret key configured?

Show me the Redis configuration files

Find the Docker configuration for the API service

Where is the rate limiting configured - what are the limits set to?

What it does: Finds code with similar structure to what you describe, even if it uses different variable names or is written in a different language. It understands control flow - loops, try/catch, branches - not just text.

Note: Requires PATTERN_VECTORS=1 to be enabled on the server.

Find all places we use a specific pattern

Find all the places in the codebase where we do retry with exponential backoff

Show me every place we use the try/except/sleep retry pattern

Find code that follows the singleton pattern

Use an actual code snippet as the pattern

Find code similar to this pattern:
for i in range(3):
    try:
        result = fetch_data()
        break
    except Exception:
        time.sleep(2 ** i)

Cross-language pattern search

Find Go code that does the same thing as this Python error handling pattern:
if err != nil:
    return None, err

Find how we handle a category of problem

Find all the places we handle connection timeouts

Show me every place we validate user input before saving to the database

What it does: Searches your commit history semantically — find commits related to a feature, bug fix, or behavior change, even if you don't know the exact commit message wording.

Find when a feature was added

When was rate limiting added? Show me the relevant commits

Find the commits where we migrated from sessions to JWT tokens

Find commits related to a bug

Find commits that mention fixing authentication or token expiration bugs

When did we change the database connection pooling behavior?

Find commits that touched a specific file

Show me the history of changes to src/auth/middleware.py

Predict what else needs to change (co-change prediction)

If I change src/api/auth.py, what other files have historically been changed at the same time?

What files usually change together with the payment module?

Why this is useful: Files that historically co-change often have hidden coupling. This predicts what else you'll probably need to update.

What it does: Searches across multiple repositories at once, and can trace API boundaries between them — finding how a frontend call connects to a backend route, or how an event publisher connects to its consumer.

Simple multi-repo search

Search both the frontend and backend repos for how user login is handled

Find authentication code across all our microservices

Trace an API call from frontend to backend

I see the frontend calls /api/auth/login — find where that route is handled in the backend

Trace the full flow: user clicks "Submit Payment" in the frontend → find the backend handler

Trace an event through services

Find where the USER_CREATED event is published and where it's consumed across our services

Find shared types/contracts

Find where the UserProfile type is defined and which repos use it

What it does: memory_store saves important findings, decisions, or gotchas to a persistent knowledge base. memory_find retrieves them later. This knowledge survives across sessions - come back days later and it's still there.

Think of it as: a shared team wiki that lives inside your AI assistant, searchable by meaning rather than exact keywords.

Saving architectural decisions

Remember this: we use JWT tokens with 24-hour expiry for access tokens and 7-day expiry for refresh tokens. The refresh tokens are stored in Redis with LRU eviction. Don't change the expiry without updating the mobile app too.

Save this as a team decision: we chose PostgreSQL over MongoDB because our data is highly relational and we need ACID transactions for payment processing.

Saving bugs and gotchas

Save this as a gotcha: RefreshTokenManager.py line 89 uses session.expire_in instead of constants.REFRESH_TTL. This was introduced in PR #1234 and causes intermittent 3-day expiry instead of 7-day expiry.

Remember this bug trap: when you import UserService in test files, it triggers a database connection attempt. You need to mock the db module first or tests will fail silently.

Saving conventions

Save this convention: all API endpoints must return responses in the envelope format: { "status": "ok|error", "data": {}, "errors": [] }. Any deviation breaks the frontend client SDK.

Recalling knowledge

What do we know about our JWT token strategy?

What gotchas or bugs have been found in the auth module?

What architectural decisions have we made about the database?

I'm new to this codebase - what are the most important things to know? (priority: high)

Memory kinds - how to save things with context

When saving, you can specify the type to make retrieval more targeted:

Example: full memory workflow

Day 1 - you discover something important:

Save this as a gotcha with high priority: The upload service has a race condition when two workers process the same file ID simultaneously. The file gets written twice and one version is lost. Fix is in PR #456, not yet merged. Topic: file-processing.

Day 5 - you or a teammate hits a related issue:

What do we know about bugs in the file processing or upload service?

→ AI retrieves the Day 1 note immediately, saving 30 minutes of debugging.

What it does: Runs several independent searches in a single call. Faster and cheaper (token-wise) than asking one search at a time.

Use this when you're about to ask 2+ separate search questions that don't depend on each other.

Instead of asking one at a time...

Slow way (3 separate asks):

Find authentication middleware

(wait)

Find rate limiting implementation

(wait)

Find error handling patterns

Fast way (one ask):

Search for all three of these at once:
1. Authentication middleware implementation
2. Rate limiting logic
3. Error handling patterns in the API layer

Good use cases

At the same time, find:
- Where we validate user input
- Where we sanitize database queries
- Where we handle SQL injection prevention

Search in parallel for the login handler, the logout handler, and the session refresh handler

What it does: Lets you verify that the codebase is properly indexed and searchable.

When searches return unexpected results

Check if the codebase index is healthy - how many files are indexed and when was it last updated?

List all the collections that are currently indexed

When you're not sure which collection to search

What collections are available? I want to make sure I'm searching the right repo

At the start of a session on a new project

Before we start, check the index health and tell me what's indexed so I know what you can search

Be specific about what you want

Tell the AI the context of your task

I'm about to refactor the User model. Before I start, find all the code that depends on it - callers, importers, and tests

I'm debugging an intermittent token expiration bug. Search the codebase for JWT refresh logic and also check if we have any saved notes about auth issues

I'm onboarding to this project. Explain how the payment processing flow works end-to-end

Scope your search when you know where to look

Find error handling inside the src/api/ directory only

Search only in Python files under the workers/ folder

Find the middleware functions, but skip anything in test files or migrations

Ask for multiple things at once when they're independent

At the same time:
1. Find where JWT tokens are generated
2. Find where JWT tokens are validated
3. Find the tests for the auth module

Ask follow-up questions naturally

// First ask
Find the authentication middleware

// Follow-up (AI has context)
Now show me who calls that middleware and what it depends on

// Deeper follow-up
What would break if I removed the token expiry check from that middleware?

Use memory proactively

Before starting a long investigation:

Before we start debugging this auth issue, check if we have any saved notes about JWT or token expiration problems

After finding something important:

Save what we just found as a gotcha - the token refresh logic has a race condition when two requests arrive simultaneously for the same user

The "before I change X" pattern

This pattern makes full use of symbol relationships + tests + memory together:

Before I change the UserService class:
1. Find all the callers of UserService
2. Find all the tests that cover it
3. Check if we have any saved notes about UserService or the user model
4. Show me what UserService itself calls internally

The "I'm new here" pattern

I'm new to this codebase. Help me understand:
1. How does authentication work end-to-end?
2. What are the main services and how do they communicate?
3. What saved architectural decisions or gotchas should I know about?

Guide based on Context Engine Private documentation. Source: docs/MCP_API.md, skills/context-engine/SKILL.md

Use this page to diagnose common problems. Start with the quick diagnostics below before jumping to a specific section.

Quick Diagnostics

The fastest way to diagnose most issues is to ask your AI client directly. Once Context Engine is connected via MCP, you can prompt your AI (Claude, Cursor, Windsurf, etc.) with natural language and it will call the right diagnostic tool automatically.

Run these three checks first by typing them as prompts in your AI client:

1. Check index health

Prompt your AI:

"Check my Context Engine index health using qdrant_status"

Look at point_count in the response. If it's 0 or unexpectedly low, your workspace hasn't been fully indexed yet. Wait for the VS Code extension upload to finish and retry.

2. List available collections

Prompt your AI:

"List my Context Engine collections using qdrant_list"

This confirms which collections exist and that your session is targeting the right one. If your repo isn't listed, re-trigger indexing from the VS Code extension (command palette → Context Engine: Upload Workspace).

3. Check embedding pipeline stats

Prompt your AI:

"Show my Context Engine embedding pipeline stats"

Look at cache_hit_rate. A very low rate means indexing is still in progress — wait a few minutes and retry your original search.

Note: These diagnostics require MCP to already be connected. If MCP isn't set up yet, start with Installation & Connection below.

Installation & Connection

MCP server isn't showing up in my AI client

Symptoms: The MCP tools (repo_search, symbol_graph, etc.) don't appear in Claude, Cursor, Windsurf, or your other client.

Steps:

1. Confirm the MCP bridge process is running. For the npm bridge:

   npx @context-engine-bridge/context-engine-mcp-bridge --version
   

2. Check your MCP config file points to the correct server URL and API key. See the MCP Configuration guide for the correct format per client.
3. Restart your AI client fully — most clients only load MCP servers at startup.
4. Verify your API key starts with ctxce_ and hasn't expired. You can regenerate it from the API Keys page in your workspace.

VS Code extension shows "Disconnected" or won't upload

Symptoms: The status bar shows a red indicator, or uploads fail silently.

Steps:

1. Open the VS Code Output panel (View → Output) and select Context Engine from the dropdown. Error details appear here.
2. Confirm your workspace URL and API key are set correctly in VS Code settings (context-engine.serverUrl, context-engine.apiKey). There should be no trailing slash on the URL.
3. Check that the upload service is reachable. For SaaS, this is https://upload.context-engine.ai. For self-hosted, it's your configured UPLOAD_SERVICE_URL.
4. If you're behind a corporate proxy or VPN, the extension may be blocked. Try temporarily disabling the proxy and re-uploading.
5. Re-authenticate: run Context Engine: Sign In from the VS Code command palette.

API key is rejected with 401

Symptoms: Requests return "Invalid or expired API key" or "Missing Authorization header".

Checks:

• The key must be passed as Authorization: Bearer ctxce_xxxxxxxx. Confirm no extra whitespace.
• Keys scoped to read cannot create or update docs. Admin operations (doc management, indexing) require admin scope.
• Keys expire. Check the expiry date on your API Keys page and generate a new one if needed.

Search & Indexing

Search returns no results

Most common cause: The collection hasn't been indexed, or the session is targeting the wrong collection name.

Steps:

1. Ask your AI client: "Check my Context Engine index health" — it will call qdrant_status and show point_count. If 0, indexing hasn't completed.
2. Ask your AI client: "List my Context Engine collections" — it will call qdrant_list so you can confirm the collection name matches what your session expects. If the name is wrong, tell your AI: "Set my default Context Engine collection to [name from the list]".
3. Remove any filters you've added (language, under, path_glob) and retry with just a plain query. A filter may be excluding all results.
4. Broaden the query. Very specific queries (exact function names, niche variable names) can miss if the embedding model generalises differently. Try a more conceptual query.

Results feel outdated — changes I made aren't appearing

Cause: The index reflects the state of the workspace at the time of the last upload. It doesn't update in real time unless the VS Code extension is active and watching.

Steps:

1. In VS Code, check the extension's status bar badge. A spinning indicator means an upload is in progress. A checkmark means it's up to date.
2. Trigger a manual re-upload: open the command palette and run Context Engine: Upload Workspace.
3. For self-hosted deployments, the watcher process may have stopped. Check your server logs and restart the indexer service.
4. Large deletions or renames may leave stale entries. In self-hosted mode, ask your AI: "Prune stale entries from my Context Engine index" — it will call qdrant_prune to clean up files that no longer exist.

Results are coming from the wrong language or wrong files

Cause: The session's auto-detected language filter doesn't match what you intended, or REPO_AUTO_FILTER is matching the wrong repo.

Fix: Be explicit with filters:

repo_search(
  query="authentication handler",
  language="python",
  under="src/auth/"
)

If using search() (auto-routing), it may detect the wrong intent. Switch to repo_search() directly when you need precise filter control.

"Collection not found" error

Cause: The collection name passed (or inferred from session defaults) doesn't exist in Qdrant.

Steps:

1. Ask your AI: "List my Context Engine collections". Collection names are case-sensitive and include an org-scoped suffix (e.g. myorg_my-repo-a848ec78).
2. Once you have the exact name, tell your AI: "Set my default Context Engine collection to myorg_my-repo-a848ec78".
3. If the collection doesn't appear at all, re-trigger indexing from the VS Code extension (command palette → Context Engine: Upload Workspace).

Reranking timeout

Symptom: Error: "Timeout during rerank".

Fix options (in order of preference):

1. Reduce limit — reranking all 50+ results is slower than reranking 10.
2. Disable reranking for that query:

   repo_search(query="...", rerank_enabled=false)
   

3. Increase the timeout:

   repo_search(query="...", rerank_timeout_ms=15000)
   

Symbol Graph

symbol_graph returns no results for a symbol I know exists

Steps:

1. Confirm the exact symbol name. Use repo_search(symbol="MyClass") to verify spelling and casing — symbol names are case-sensitive.
2. If the symbol is defined in a dependency (not your own code), it may not be in the graph. Graph traversal covers indexed source files only.
3. Try query_type="definition" first to confirm the symbol is in the graph at all before querying callers or callees.
4. If the graph backend is unavailable, symbol_graph falls back to semantic search. Results will still appear but won't represent true call graph relationships.

Callers list seems incomplete

Cause: The symbol is called under a different name (aliased import, monkey-patched, or called via a wrapper), or the call is in a file that was excluded from indexing.

Steps:

1. Try depth=2 to find indirect callers:

   symbol_graph(symbol="my_function", query_type="callers", depth=2)
   

2. Search for the symbol name as a string to catch aliased or dynamic calls:

   repo_search(query="my_function", include_snippet=true)
   

3. Check whether the calling file is in an excluded path (e.g. a vendor/ or node_modules/ directory that was filtered during indexing).

Memory

Memories aren't persisting across sessions

Cause: Memories are scoped to an org/workspace. If you're using a different workspace or org in a new session, the memories from the previous session won't be visible.

Fix: Confirm you're in the same workspace. Ask your AI: "List my Context Engine collections" — the collection names include your org prefix. If the names differ between sessions, the memories are in a different workspace scope.

memory_find returns nothing

Steps:

1. Confirm memories were stored in this workspace:

   memory_find(query="architecture", limit=20)
   

   A very broad query with a high limit should return something if memories exist.
2. Remove metadata filters (topic, kind, priority_min) — they may be filtering out valid results.
3. Check whether memory storage actually succeeded in the session where you stored them. memory_store returns {"ok": true, "id": "..."} on success. If it returned an error, the memory wasn't saved.

Performance

Search is slower than expected

Normal baselines:

If you're consistently above these baselines:

• Use batch_search instead of sequential search calls. Five sequential calls at ~200ms each = ~1s. One batch_search with five queries = ~300ms.
• Set output_format="toon" to reduce token serialisation overhead on large result sets.
• Reduce limit — fetching 100 results and reranking them takes significantly longer than fetching 10.
• For latency-critical loops, use repo_search directly instead of search (saves ~20–40ms routing overhead per call).

Multi-Repo

Searches are hitting the wrong repository

Cause: The session default collection is pointing at a different repo, or REPO_AUTO_FILTER is auto-scoping to the wrong repo based on the query.

Fix: Tell your AI explicitly which repo to search:

"Search my frontend Context Engine collection for login handler"

Or lock it for the whole session:

"Set my default Context Engine collection to myorg_frontend-abc123"

cross_repo_search returns nothing

Steps:

1. Ask your AI: "Search across all my Context Engine repos for authentication flow, force discovery" — this triggers cross_repo_search with discover="always".
2. Ask your AI: "List my Context Engine collections" to confirm both repositories are indexed.
3. If they are indexed but not being searched together, tell your AI explicitly: "Search for login across both my frontend and backend Context Engine collections".

Does my code get stored on Context Engine's servers?

In SaaS mode, embeddings and symbol graph entries are stored in Context Engine's managed Qdrant instance. Your actual source files are not stored — only vector representations and metadata (file paths, line numbers, symbol names). In Self-Hosted (Singular) mode, everything stays on your own infrastructure and nothing leaves your network.

How often does the index update?

In SaaS mode with the VS Code extension active, the index updates incrementally on every file save. Only changed files are re-indexed, so updates are fast. Without the extension running, the index reflects the last manual upload. There is no scheduled background sync — you control when uploads happen.

Can I index multiple repositories in the same workspace?

Yes. Each repository gets its own collection, and cross_repo_search can query across all of them. You can also use repo_search with repo=["frontend", "backend"] to search a subset of collections simultaneously, as long as they share the same Qdrant instance.

What's the difference between search and repo_search?

search is the recommended default — it auto-detects intent and routes to the right tool (which might be repo_search, context_answer, symbol_graph, or something else). Use repo_search directly when you need full control over filters, when speed is critical (saves ~20–40ms routing overhead), or when search is mis-detecting your intent.

How do I reset or rebuild my index from scratch?

In SaaS mode: delete the collection from the workspace Collections page, then trigger a full re-upload from the VS Code extension (Context Engine: Upload Workspace).

In Self-Hosted mode: run qdrant_prune() to remove stale entries, or delete the collection entirely via the Qdrant dashboard and re-run qdrant_index_root().

Why does context_answer take so long?

context_answer retrieves relevant code spans and then generates an LLM explanation with citations. The LLM generation step typically takes 2–8 seconds depending on answer length and provider. If you just need code locations (not an explanation), use repo_search with include_snippet=true instead — it's 10–50x faster.

I'm getting different results every time I run the same query. Is that expected?

Minor variation is normal. Neural reranking uses learned relevance scores that can shift slightly as the learning model updates. If results are dramatically different between runs, check whether the index was updated between queries (a new upload may have changed point counts) or whether you have rerank_enabled=false set on one of the calls.

Still stuck?

• Join the Discord community — most questions get answered within a few hours.
• Open an issue on GitHub.
• Check the Developer Prompt Guide for correct tool usage patterns before reporting a bug.