README

CI
npm version
VS Code Marketplace
Join our Discord

Documentation: Getting Started · README · Configuration · IDE Clients · MCP API · ctx CLI · Memory Guide · Architecture · Multi-Repo · Observability · Kubernetes · VS Code Extension · Troubleshooting · Development

Context-Engine

Open-source, self-improving code search that gets smarter every time you use it.

Quick Start: Stack in 30 Seconds

VS Code Extension (Easiest)

1. Install Context Engine Uploader
2. Open any project → extension prompts to set up Context-Engine stack
3. Opened workspace is indexed
4. MCP configs can configure your agent/IDE

That's it! The extension handles everything:

• Clones Context-Engine to your chosen location (keeps it separate from your project)
• Starts the Docker stack automatically
• Sets up MCP bridge configuration
• Writes MCP configs for Claude Code, Windsurf, and Augment

Claude Code users: Install the skill plugin:

/plugin marketplace add m1rl0k/Context-Engine
/plugin install context-engine

Manual Setup (Alternative)

git clone https://github.com/m1rl0k/Context-Engine.git && cd Context-Engine
make bootstrap  # One-shot: up → wait → index → warm → health

Or step-by-step:

docker compose up -d
HOST_INDEX_PATH=/path/to/your/project docker compose run --rm indexer

See Configuration for environment variables and IDE_CLIENTS.md for MCP setup.

Why This Stack Works Better

What You Get Out of the Box

• ReFRAG-inspired micro-chunking: Research-grade precision retrieval
• Self-hosted stack: No cloud dependency, no vendor lock-in
• Universal compatibility: Claude Code, Windsurf, Cursor, Cline, etc.
• Auto-syncing: Extension watches for changes and re-indexes automatically
• Memory system: Store team knowledge alongside your code
• Optional LLM features: Local decoder (llama.cpp), cloud integration (GLM, MiniMax), adaptive rerank learning

Works With Your Local Files

No complicated path setup - Context-Engine automatically handles the mapping between your local files and the search index.

Enterprise-Ready Features

• Built-in authentication with session management (optional)
• Unified MCP endpoint that combines indexer and memory services
• Automatic collection injection for workspace-aware queries

Alternative: Direct HTTP endpoints

{
  "mcpServers": {
    "qdrant-indexer": { "url": "http://localhost:8003/mcp" },
    "memory": { "url": "http://localhost:8002/mcp" }
  }
}

Using other IDEs? See docs/IDE_CLIENTS.md for complete MCP configuration examples.

Supported Clients

Endpoints

VS Code Extension

Context Engine Uploader provides:

• One-click upload — Sync workspace to Context-Engine
• Auto-sync — Watch for changes and re-index automatically
• Prompt+ button — Enhance prompts with code context before sending
• MCP auto-config — Writes Claude/Windsurf MCP configs

See docs/vscode-extension.md for full documentation.

MCP Tools

Search (Indexer MCP):

• repo_search — Hybrid code search with filters
• context_search — Blend code + memory results
• context_answer — LLM-generated answers with citations
• search_tests_for, search_config_for, search_callers_for

Memory (Memory MCP):

• store — Save knowledge with metadata
• find — Retrieve stored memories

Indexing:

• qdrant_index_root — Index the workspace
• qdrant_status — Check collection health
• qdrant_prune — Remove stale entries

See docs/MCP_API.md for complete API reference.

Documentation

How It Works

flowchart LR
  subgraph Your Machine
    A[IDE / AI Tool]
    V[VS Code Extension]
  end
  subgraph Docker
    U[Upload Service]
    I[Indexer MCP]
    M[Memory MCP]
    Q[(Qdrant)]
    L[[LLM Decoder]]
    W[[Learning Worker]]
  end
  V -->|sync| U
  U --> I
  A -->|MCP| I
  A -->|MCP| M
  I --> Q
  M --> Q
  I -.-> L
  I -.-> W
  W -.-> Q

Language Support

Python, TypeScript/JavaScript, Go, Java, Rust, C#, PHP, Shell, Terraform, YAML, PowerShell

Benchmarks

CoSQA (Dense Retrieval, No Rerank)

Corpus: 20,604 code snippets | 500 queries | Pure dense retrieval, no reranking
Jina-Code: jinaai/jina-embeddings-v2-base-code (code-specific, 8k context)

License

BUSL-1.1