IMPORTANT: VS Code Extension Temporarily Unavailable

We are migrating Context-Engine to the cloud

We are currently in the middle of a major platform migration to new cloud-hosted infrastructure. During this transition, the Context-Engine VS Code extension is temporarily not working while we move services, endpoints, and authentication flows.

What this means for you

• The extension may fail to connect, time out, or return no results
• Behavior may be inconsistent during the cutover window
• This is expected while the migration is in progress

Apologies

We know this is disruptive, especially if Context-Engine is part of your daily workflow. We’re moving as quickly as possible while keeping the migration stable and secure.

Thank you for your patience.

Join the Beta

If you want early access to the updated cloud-backed experience (and the fastest path to getting unblocked), please sign up for the beta at:

https://context-engine.ai

Beta signups will receive:

• Early access to cloud migration builds
• Updates as milestones land
• A smoother onboarding path once the extension is re-enabled

Status updates

We will post restoration updates as the migration completes. If you are currently blocked, please sign up for the beta so we can keep you informed and prioritize issues.

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-core, self-improving code search that gets smarter every time you use it.

---

Quick Start

Install the CLI

# Using pip
pip install context-engine

# Or using uv (recommended)
uv pip install context-engine

This installs the ctx command (also available as ctx-cli).

One Command Setup

ctx quickstart

This single command starts all services, indexes your codebase, and warms up models.

Common Commands

ctx status              # Check service health
ctx reset --mcp         # Reset with HTTP MCP endpoints (for Codex, modern clients)
ctx reset --mcp --db-reset  # Hard reset: wipe database and rebuild everything
ctx search "auth flow"  # Search your codebase
ctx answer "How does caching work?"  # Get answers with citations

See ctx CLI Reference for all commands.

Legacy: Makefile Commands

The ctx CLI deprecates the Makefile, but legacy commands retest available:

git clone https://github.com/m1rl0k/Context-Engine.git && cd Context-Engine
make bootstrap  # Equivalent to: ctx quickstart
make reset      # Equivalent to: ctx reset --mcp

---

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

Direct HTTP endpoints:

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

See docs/IDE_CLIENTS.md for MCP configuration examples and docs/MCP_API.md for the complete API reference.

---

Agent Skills (Codex / Claude / Gemini / Augment)

Context-Engine includes agent skills that teach AI coding assistants how to use the MCP tools effectively.

For Claude Code:

Install the skill plugin via marketplace:

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

Or copy the CLAUDE.md file manually:

# Project-specific
cp CLAUDE.md /path/to/your/project/

# Or global
cp CLAUDE.md ~/.claude/CLAUDE.md

For Codex (OpenAI):

Install directly from GitHub using the $skill-installer:

$skill-installer install https://github.com/Context-Engine-AI/Context-Engine/tree/test/.codex/skills/context-engine

Or copy manually:

# Global install
cp -r .codex/skills/context-engine ~/.codex/skills/

# Or project-specific
cp -r .codex/skills/context-engine /path/to/your/project/.codex/skills/

Restart Codex after installing to pick up the new skill.

For Claude:

cp CLAUDE.md /path/to/your/project/

For Gemini:

cp GEMINI.md /path/to/your/project/

For Augment:

cp -r .augment /path/to/your/project/

Skills teach agents to prefer Context-Engine MCP tools over grep/find/cat for code exploration.

---

How It Works

Local Mode Architecture

Zero auth, single-tenant, perfect for personal use

flowchart TB
    subgraph client["CLIENT LAYER"]
        direction LR
        IDE["<b>IDE / AI Tool</b><br/>Claude, Cursor, etc."]
        VSC["<b>VS Code Extension</b><br/>File Watcher"]
    end

    subgraph mcp["MCP LAYER"]
        direction LR
        subgraph search["Search Services"]
            MCP_SSE["<b>Memory MCP</b><br/>:8000 SSE"]
            MCP_HTTP["<b>Memory MCP</b><br/>:8002 RMCP"]
        end
        subgraph index["Index Services"]
            IDX_SSE["<b>Indexer MCP</b><br/>:8001 SSE"]
            IDX_HTTP["<b>Indexer MCP</b><br/>:8003 RMCP"]
        end
    end

    subgraph processing["PROCESSING LAYER"]
        direction LR
        EMB["<b>Embedding Service</b><br/>:8100-8101<br/>ONNX (2 replicas)"]
        LLAMA["<b>LLM Decoder</b><br/>:8080<br/>llama.cpp"]
        LEARN["<b>Learning Worker</b><br/>Background<br/>Adaptive Reranker"]
        WATCH["<b>Watcher</b><br/>File Monitor<br/>Auto-reindex"]
    end

    subgraph storage["STORAGE LAYER"]
        direction LR
        QDRANT[("<b>Qdrant</b><br/>:6333/:6334<br/>Vector DB")]
        REDIS[("<b>Redis</b><br/>:6379<br/>Cache/State")]
        FS[("<b>Filesystem</b><br/>/work<br/>Direct Access")]
    end

    %% Client connections
    IDE -->|"MCP Protocol"| MCP_SSE & MCP_HTTP
    IDE -->|"MCP Protocol"| IDX_SSE & IDX_HTTP
    VSC -->|"File Sync"| FS

    %% MCP to Processing
    MCP_SSE & MCP_HTTP -->|"embed()"| EMB
    IDX_SSE & IDX_HTTP -->|"embed()"| EMB
    IDX_SSE & IDX_HTTP -->|"expand query"| LLAMA

    %% Processing to Storage
    EMB -->|"vectors"| QDRANT
    LEARN -->|"update weights"| QDRANT
    WATCH -->|"file events"| FS
    WATCH -->|"reindex"| QDRANT

    %% Storage connections
    MCP_SSE & MCP_HTTP -->|"search"| QDRANT
    IDX_SSE & IDX_HTTP -->|"upsert"| QDRANT
    IDX_SSE & IDX_HTTP -->|"state"| REDIS

    %% Styling - GitHub light/dark compatible
    classDef clientStyle fill:#4a90d9,stroke:#2563eb,stroke-width:2px,color:#fff
    classDef mcpStyle fill:#8b5cf6,stroke:#6d28d9,stroke-width:2px,color:#fff
    classDef processStyle fill:#f59e0b,stroke:#d97706,stroke-width:2px,color:#000
    classDef storageStyle fill:#10b981,stroke:#059669,stroke-width:2px,color:#fff

    class IDE,VSC clientStyle
    class MCP_SSE,MCP_HTTP,IDX_SSE,IDX_HTTP mcpStyle
    class EMB,LLAMA,LEARN,WATCH processStyle
    class QDRANT,REDIS,FS storageStyle

Loading

Service Port Reference

Service	Port	Protocol	Description
Memory MCP (SSE)	8000	SSE	Legacy streaming transport
Memory MCP (RMCP)	8002	HTTP	Modern streamable HTTP
Indexer MCP (SSE)	8001	SSE	Legacy streaming transport
Indexer MCP (RMCP)	8003	HTTP	Modern streamable HTTP
Upload Service	8004	HTTP	Delta bundle uploads
Embedding Service	8100-8101	HTTP	ONNX embeddings (2 replicas)
LLM Decoder	8080	HTTP	llama.cpp query expansion
Qdrant	6333/6334	HTTP/gRPC	Vector database
Redis	6379	TCP	Cache and state backend

---

Benchmarks

CoSQA (Dense Retrieval, No Rerank)

Method	MRR	R@1	R@5	R@10	NDCG@10
Context-Engine (Jina-Code)	0.276	0.146	0.448	0.658	0.365
Context-Engine (BGE-base)	0.253	0.150	0.374	0.550	0.322
CodeT5+ embedding	0.266	-	-	-	-
BM25 (Lucene)	0.167	-	-	-	-
BoW	0.065	-	-	-	-

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

CoIR Benchmark (Full Corpus, Dense Retrieval)

Benchmark	Corpus	Queries	NDCG@10
CodeSearchNet-Python	280K	14.9K	74.37%
CodeSearchNet-Go	280K	14.9K	74.51%
CodeSearchNet-JavaScript	280K	14.9K	57.19%

Full CoIR corpus evaluation with dense retrieval (Jina-Code embeddings)

---

License

BUSL-1.1