Context Engine

Context-Engine

Search and retrieve code context from any codebase using hybrid vector search (semantic + lexical) with neural reranking.

Client- or provider-specific wrapper files should stay thin and defer to this document for shared MCP tool-selection and search guidance.

Quickstart

1. Start with search for most codebase questions.
2. Use symbol_graph first for direct symbol relationships such as callers, definitions, importers, subclasses, and base classes.
3. Use graph_query only if that tool is available and you need transitive impact, dependency, or cycle analysis; otherwise combine symbol_graph with targeted search.
4. Prefer MCP tools for exploration. Narrow grep/file-open use is still fine for exact literal confirmation, exact file/path confirmation, or opening a file you already identified for editing.
5. Use cross_repo_search for multi-repo questions. For public V1 context_search, treat include_memories=true as compatibility-only: it preserves response shape but keeps results code-only and may add memory_note.

Decision Tree: Choosing the Right Tool

What do you need?
    |
    +-- UNSURE or GENERAL QUERY --> search (RECOMMENDED DEFAULT)
    |       |
    |       +-- Auto-detects intent and routes to the best tool
    |       +-- Handles: code search, Q&A, tests, config, symbols, imports
    |       +-- Use this when you don't know which specialized tool to pick
    |
    +-- Find code locations/implementations
    |       |
    |       +-- Unsure what tool to use → search (DEFAULT - routes to repo_search if needed)
    |       +-- Speed-critical or complex filters → repo_search (skip routing overhead)
    |       +-- Want LLM explanation → context_answer
    |
    +-- Understand how something works
    |       |
    |       +-- Want LLM explanation --> search OR context_answer
    |       +-- Just code snippets --> search OR repo_search with include_snippet=true
    |
    +-- Find similar code patterns (retry loops, error handling, etc.)
    |       |
    |       +-- Have code example --> pattern_search with code snippet (if enabled)
    |       +-- Describe pattern --> pattern_search with natural language (if enabled)
    |
    +-- Find specific file types
    |       |
    |       +-- Test files --> search OR search_tests_for
    |       +-- Config files --> search OR search_config_for
    |
    +-- Find relationships
    |       |
    |       +-- Direct callers/defs/importers/inheritance --> search OR symbol_graph
    |       +-- Multi-hop callers --> symbol_graph (depth=2+)
    |       +-- Deep impact/dependencies/cycles --> graph_query (if available) OR symbol_graph + targeted search
    |
    +-- Git history
    |       |
    |       +-- Find commits --> search_commits_for
    |       +-- Predict co-changing files --> search_commits_for with predict_related=true
    |
    +-- Store/recall knowledge --> memory_store, memory_find
    |
    +-- Preserve public search shape while accepting memory flags --> context_search with include_memories=true (compatibility-only in V1)
    |
    +-- Multiple independent searches at once
            |
            +-- batch_search (runs N repo_search calls in one invocation, ~75% token savings)

Standard Parameters Reference

All SaaS-exposed tools organize parameters into families with consistent naming and behavior.

Family 1: Code Search Tools

Applies to: search, repo_search, code_search, batch_search, info_request, context_search

Standard Parameters:

Standard Constraints:

• limit max 100 (higher values slow queries)
• query max 400 characters / 50 words
• language must be valid code language or auto-detection will fail silently
• path_glob / not_glob support glob patterns (*, **, ?)
• Multiple query terms are fused via Reciprocal Rank Fusion (RRF) for better recall

Family 2: Symbol Graph Tools

Applies to: symbol_graph, batch_symbol_graph, graph_query, batch_graph_query

Standard Parameters:

Standard Constraints:

• symbol must be exact match or use fuzzy fallback
• query_type is case-sensitive
• depth > 3 may be slow on large graphs
• Results are auto-hydrated with code snippets

Family 3: Specialized Search Tools

Applies to: search_tests_for, search_config_for, search_callers_for, search_importers_for, search_commits_for

Standard Parameters:

Additional Parameters:

Family 4: Memory Tools

Applies to: memory_store, memory_find

Standard Parameters:

Family 5: Batch Tools

Applies to: batch_search, batch_symbol_graph, batch_graph_query

Standard Parameters (Shared across all queries):

Per-Search Overrides: Each item in searches / queries can override ANY shared parameter.

Example: searches[0] has different limit than searches[1]

Family 6: Cross-Repo & Admin Tools

Applies to: cross_repo_search, qdrant_status, qdrant_list, set_session_defaults

Standard Parameters:

Unified Search: search (RECOMMENDED DEFAULT)

Use search as your PRIMARY tool. It auto-detects query intent and routes to the best specialized tool. No need to choose between 15+ tools.

{
  "query": "authentication middleware"
}

Returns:

{
  "ok": true,
  "intent": "search",
  "confidence": 0.92,
  "tool": "repo_search",
  "result": {
    "results": [...],
    "total": 8
  },
  "plan": ["detect_intent", "dispatch_repo_search"],
  "execution_time_ms": 245
}

What it handles automatically:

• Code search ("find auth middleware") -> routes to repo_search
• Q&A ("how does caching work?") -> routes to context_answer
• Test discovery ("tests for payment") -> routes to search_tests_for
• Config lookup ("database settings") -> routes to search_config_for
• Symbol queries ("who calls authenticate") -> routes to symbol_graph
• Import tracing ("what imports CacheManager") -> routes to search_importers_for

Override parameters (all optional):

{
  "query": "error handling patterns",
  "limit": 5,
  "language": "python",
  "under": "src/api/",
  "include_snippet": true
}

When to use search:

• You're unsure which specialized tool to use
• You want intent auto-detection (routing to repo_search, context_answer, symbol_graph, tests, etc.)
• Acceptable latency overhead: ~50-100ms for routing + tool execution
• You're doing exploratory queries where routing overhead is negligible

When NOT to use search:

• You know you need raw code results (use repo_search directly)
• Time is critical (<100ms target) and routing overhead matters
• You're in a tight loop doing 10+ sequential searches (use batch_search instead)

Routing Performance:

• Intent detection: ~10-20ms
• Tool dispatch: ~5-10ms
• Total routing overhead: ~20-40ms typical, up to ~100ms worst-case
• For time-critical loops: skip routing with repo_search directly

When to use specialized tools instead:

• Cross-repo search -> cross_repo_search
• Multiple independent searches -> batch_search (N searches in one call, ~75% token savings)
• Memory storage/retrieval -> memory_store, memory_find
• Admin/diagnostics -> qdrant_status, qdrant_list
• Pattern matching (structural) -> pattern_search

When to use repo_search instead of search:

• Full control over filters: You know exactly what you're searching for and want to apply specific language, path, or symbol filters without auto-detection overhead
  • Example: "In a polyglot repo, I need Python code only" → use repo_search with language="python" to avoid search's auto-detected language=javascript
  • Example: "Find only test files matching a pattern" → use repo_search with path_glob="**/test_*.py" directly
• Speed-critical queries (<100ms target): You can't afford the ~20-40ms routing overhead
  • Example: Time-sensitive tool loops where each query must complete in <50ms
• Complex filter combinations: You need language + under + not_glob together, not guessed by auto-detection
• Guaranteed exact behavior: You want reproducible results without routing confidence variations (search routing confidence varies 0.6-0.95)
• Known tool type: You already know you need code results (not Q&A, tests, configs, or symbols) so routing is wasted

Example: When search guesses wrong:

SEARCH (auto-routes, may detect wrong intent):
query: "authenticate in FastAPI"
confidence: 0.75
intent: "Q&A - what does authenticate do in FastAPI?"
→ routes to context_answer, returns explanation instead of code

REPO_SEARCH (explicit, predictable):
query: "authenticate"
language: "python"
under: "src/auth/"
→ returns code implementations in src/auth/ only, no routing overhead

Routing Overhead: When It Matters

Latency Impact of Using search vs repo_search directly:

Decision Criteria:

• Use search when: One-off query, exploratory, unsure which tool, latency <200ms is acceptable
• Use repo_search when: Speed <100ms required, complex filter combo needed, tight loop (use batch_search if >2 queries), know you need code (not Q&A)
• Use batch_search when: 2+ independent code searches to reduce routing overhead by 75-85% per batch

Real-world example - Interactive AI assistant loop:

Bad (repeated routing overhead):
for query in user_queries:  # 5 queries
    result = search(query)  # ~70-100ms routing × 5 = 350-500ms wasted

Good (one batch call):
results = batch_search([query1, query2, query3, query4, query5])  # Routing once, ~25ms × 5 = 125ms
# Saves ~300ms+ per iteration

Primary Search: repo_search

Use repo_search (or its alias code_search) for direct code lookups when you need full control. Reranking is ON by default.

{
  "query": "database connection handling",
  "limit": 10,
  "include_snippet": true,
  "context_lines": 3
}

Returns:

{
  "results": [
    {"score": 3.2, "path": "src/db/pool.py", "symbol": "ConnectionPool", "start_line": 45, "end_line": 78, "snippet": "..."}
  ],
  "total": 8,
  "used_rerank": true
}

Multi-query for better recall - pass a list to fuse results:

{
  "query": ["auth middleware", "authentication handler", "login validation"]
}

Apply filters to narrow results:

{
  "query": "error handling",
  "language": "python",
  "under": "src/api/",
  "not_glob": ["**/test_*", "**/*_test.*"]
}

Search across repos (same collection):

{
  "query": "shared types",
  "repo": ["frontend", "backend"]
}

Use repo: "*" to search all indexed repos.

Search across repos (separate collections — use cross_repo_search):

// cross_repo_search
{"query": "shared types", "target_repos": ["frontend", "backend"]}
// With boundary tracing for cross-repo flow discovery
{"query": "login submit", "trace_boundary": true}

Available Filters

• language - Filter by programming language
• under - Path prefix (e.g., "src/api/")
• path_glob - Include patterns (e.g., ["/*.ts", "lib/"])
• not_glob - Exclude patterns (e.g., ["**/test_*"])
• symbol - Symbol name match
• kind - AST node type (function, class, etc.)
• ext - File extension
• repo - Repository filter for multi-repo setups
• case - Case-sensitive matching

Batch Search: batch_search

Run N independent repo_search calls in a single MCP tool invocation. Reduces token overhead by ~75-85% compared to sequential calls.

Token Savings & Latency Metrics:

Decision Rule: Always use batch_search when you have 2+ independent code searches. The latency savings alone (30-100ms faster) justify batching, plus you save ~40-75% tokens.

{
  "searches": [
    {"query": "authentication middleware", "limit": 5},
    {"query": "rate limiting implementation", "limit": 5},
    {"query": "error handling patterns"}
  ],
  "compact": true,
  "output_format": "toon"
}

Returns:

{
  "ok": true,
  "batch_results": [result_set_0, result_set_1, result_set_2],
  "count": 3,
  "elapsed_ms": 245
}

Each result_set has the same schema as repo_search output.

Shared parameters (applied to all searches unless overridden per-search):

• collection, output_format, compact, limit, language, under, repo, include_snippet, rerank_enabled

Per-search overrides: Each entry in searches can include any repo_search parameter to override the shared defaults.

Limits: Maximum 10 searches per batch.

When to use batch_search vs multiple search calls:

• Use batch_search when you have 2+ independent code searches and want to minimize token usage and round-trips
• Use individual search calls when you need intent routing (Q&A, symbol graph, etc.) or when searches depend on each other's results

Simple Lookup: info_request

Use info_request for natural language queries with minimal parameters:

{
  "info_request": "how does user authentication work"
}

Add explanations:

{
  "info_request": "database connection pooling",
  "include_explanation": true
}

Q&A with Citations: context_answer

Use context_answer when you need an LLM-generated explanation grounded in code:

{
  "query": "How does the caching layer invalidate entries?",
  "budget_tokens": 2000
}

Returns an answer with file/line citations. Use expand: true to generate query variations for better retrieval.

Pattern Search: pattern_search (Optional)

Note: This tool may not be available in all deployments. If pattern detection is disabled, calls return {"ok": false, "error": "Pattern search module not available"}.

Find structurally similar code patterns across all languages. Accepts either code examples or natural language descriptions—auto-detects which.

Code example query - find similar control flow:

{
  "query": "for i in range(3): try: ... except: time.sleep(2**i)",
  "limit": 10,
  "include_snippet": true
}

Natural language query - describe the pattern:

{
  "query": "retry with exponential backoff",
  "limit": 10,
  "include_snippet": true
}

Cross-language search - Python pattern finds Go/Rust/Java equivalents:

{
  "query": "if err != nil { return err }",
  "language": "go",
  "limit": 10
}

Explicit mode override - force code or description mode:

{
  "query": "error handling",
  "query_mode": "description",
  "limit": 10
}

Key parameters:

• query - Code snippet OR natural language description
• query_mode - "code", "description", or "auto" (default)
• language - Language hint for code examples (python, go, rust, etc.)
• limit - Max results (default 10)
• min_score - Minimum similarity threshold (default 0.3)
• include_snippet - Include code snippets in results
• context_lines - Lines of context around matches
• aroma_rerank - Enable AROMA structural reranking (default true)
• aroma_alpha - Weight for AROMA vs original score (default 0.6)
• target_languages - Filter results to specific languages

Returns:

{
  "ok": true,
  "results": [...],
  "total": 5,
  "query_signature": "L2_2_B0_T2_M0",
  "query_mode": "code",
  "search_mode": "aroma"
}

The query_signature encodes control flow: L (loops), B (branches), T (try/except), M (match).

Specialized Search Tools

search_tests_for - Find test files:

{"query": "UserService", "limit": 10}

search_config_for - Find config files:

{"query": "database connection", "limit": 5}

search_callers_for - Find callers of a symbol:

{"query": "processPayment", "language": "typescript"}

search_importers_for - Find importers:

{"query": "utils/helpers", "limit": 10}

symbol_graph - Symbol graph navigation (callers / callees / definition / importers / subclasses / base classes):

Query types:

Examples:

{"symbol": "ASTAnalyzer", "query_type": "definition", "limit": 10}

{"symbol": "get_embedding_model", "query_type": "callers", "under": "scripts/", "limit": 10}

{"symbol": "qdrant_client", "query_type": "importers", "limit": 10}

{"symbol": "authenticate", "query_type": "callees", "limit": 10}

{"symbol": "BaseModel", "query_type": "subclasses", "limit": 20}

{"symbol": "MyService", "query_type": "base_classes"}

• Supports language, under, depth, and output_format like other tools.
• Use depth=2 or depth=3 for multi-hop traversals (callers of callers).
• If there are no graph hits, it falls back to semantic search.
• Note: Results are "hydrated" with ~500-char source snippets for immediate context.

graph_query - Advanced graph traversals and impact analysis (available to all SaaS users):

Query types:

Examples:

{"symbol": "UserService", "query_type": "impact", "depth": 3}

{"symbol": "auth_module", "query_type": "cycles"}

{"symbol": "processPayment", "query_type": "transitive_callers", "depth": 2, "limit": 20}

• Supports language, under, depth, limit, include_paths, and output_format.
• Use include_paths: true to get full traversal paths in results.
• Use depth to control how many hops to traverse (default varies by query type).
• Note: symbol_graph is always available (Qdrant-backed). graph_query provides advanced Memgraph-backed traversals and is available to all SaaS users.

Comparison: symbol_graph vs graph_query

Decision Guide:

• Use symbol_graph for: direct callers/callees/definitions, inheritance queries, when you need speed, always as first stop
• Use graph_query for: impact analysis ("what breaks?"), cycle detection, transitive chains, when available and you need depth >3

search_commits_for - Search git history:

{"query": "fixed authentication bug", "limit": 10}

Predict co-changing files (predict_related mode):

{"path": "src/api/auth.py", "predict_related": true, "limit": 10}

Returns ranked files that historically co-change with the given path, along with the most relevant commit message explaining why.

change_history_for_path - File change summary:

{"path": "src/api/auth.py", "include_commits": true}

Memory: Store and Recall Knowledge

Memory tools allow you to persist team knowledge, architectural decisions, and findings for later retrieval across sessions.

Memory Workflow: Store → Retrieve → Reuse

Phase 1: During Exploration (Session 1) As you discover important patterns, decisions, or findings, store them for future reference:

{
  "memory_store": {
    "information": "Auth service uses JWT tokens with 24h expiry. Refresh tokens last 7 days. Stored in Redis with LRU eviction.",
    "metadata": {
      "kind": "decision",
      "topic": "auth",
      "priority": 5,
      "tags": ["security", "jwt", "session-management"]
    }
  }
}

Phase 2: In Later Sessions Retrieve and reuse stored knowledge by similarity:

{
  "memory_find": {
    "query": "token expiration policy",
    "topic": "auth",
    "limit": 5
  }
}

Returns the exact note stored in Phase 1, plus any other auth-related memories.

Phase 3: Blend Code + Memory When you want BOTH code search results AND stored team knowledge:

{
  "context_search": {
    "query": "authentication flow",
    "include_memories": true,
    "per_source_limits": {"code": 6, "memory": 3}
  }
}

Returns: 6 code snippets + 3 memory notes, all ranked by relevance.

Timeline and Persistence

Real-World Example: Session Continuity

Session 1 (Day 1) - Discovery:

Context: Investigating why JWT refresh tokens sometimes expire unexpectedly

→ memory_store(
    information="Found: RefreshTokenManager.py line 89 uses session.expire_in instead of constants.REFRESH_TTL. This was a bug introduced in PR #1234 where the constant was 7 days but the session value was hardcoded to 3 days. The mismatch causes premature expiration.",
    metadata={"kind": "gotcha", "topic": "auth", "tags": ["bug", "jwt"], "priority": 4}
  )

Session 2 (Day 5) - Troubleshooting a Similar Issue:

→ memory_find(query="refresh token expiration problem", topic="auth")

Response: Found Session 1's note about the RefreshTokenManager bug, plus similar findings about token TTL misconfigurations.

→ User goes directly to line 89 of RefreshTokenManager.py and verifies the fix status.

Result: Problem solved in 2 minutes instead of 30 minutes of debugging.

When to Store What

Integration with Code Search

Pattern 1: Pure Code Search

{"search": "authentication validation"}

Returns: code snippets only. Fast, no memory overhead.

Pattern 2: Code + Memory Blend

{
  "context_search": {
    "query": "authentication validation",
    "include_memories": true,
    "per_source_limits": {"code": 5, "memory": 2}
  }
}

Returns: 5 code snippets + 2 relevant memory notes (team insights about auth validation patterns).

Pattern 3: Memory Only

{"memory_find": {"query": "authentication patterns", "limit": 10}}

Returns: stored team knowledge about auth, useful for onboarding or architecture review.

Common Patterns

Team Onboarding:

• New engineer joins → memory_find(query="project architecture", topic="architecture")
• Retrieves all stored architectural decisions in one place
• Much faster than reading scattered code comments

Incident Response:

• Production auth bug occurs
• → memory_find(query="auth failures", priority_min=3)
• Retrieves gotchas, prior incidents, and known traps
• Faster root-cause diagnosis

Code Review Efficiency:

• Reviewer checks PR modifying auth module
• → context_search(query="authentication standards", include_memories=true)
• Sees both current code AND team conventions/policies
• Makes more informed review decisions

Error Cases and Recovery

Admin and Diagnostics

qdrant_status - Check index health:

{}

qdrant_list - List all collections:

{}

embedding_pipeline_stats - Get cache efficiency, bloom filter stats, pipeline performance:

{}

set_session_defaults - Set defaults for session:

{"collection": "my-project", "language": "python"}

Deployment Mode Capabilities

SaaS Mode: In SaaS deployments, indexing is handled automatically by the VS Code extension upload service. The tools below marked "Self-Hosted Only" are not available in SaaS mode. All search, symbol graph, memory, and session tools work normally.

Self-Hosted Only Tools (not available in SaaS):

Tool Availability Matrix

Which tools are available in which deployment modes:

Legend:

• ✅ = Available
• ❌ = Not available
• ✅* = Pattern search available only if enabled during deployment
• ✅ (limited)** = SaaS graph_query has limited depth/performance vs Enterprise with dedicated Memgraph

Choosing Your Deployment Mode

Error Handling and Recovery

Tools return structured errors via error field or ok: false flag. Below are common errors and recovery steps by category.

Search Tools (search, repo_search, batch_search, info_request)

Silent Failure Watches:

• Empty results when expecting matches → check under path filter (may be excluding files)
• Results from wrong language → verify language parameter is set correctly
• Reranking disabled silently → check rerank_timeout_ms if you set custom timeout
• Wrong collection queried → session defaults may not match workspace (use set_session_defaults to "cd" into correct collection)

Symbol Graph Tools (symbol_graph, batch_symbol_graph, graph_query)

Silent Failure Watches:

• No callers found when method is clearly called → fuzzy fallback may have triggered, use repo_search to verify method exists
• Symbol seems undefined but code uses it → cross-module imports may not be resolved in graph yet

Context Answer (LLM-powered explanation)

Memory Tools (memory_store, memory_find)

Batch Tools (batch_search, batch_symbol_graph)

Cross-Repo & Discovery

…(truncated)