High-Level Architecture
Relevant source files
The following files were used as context for generating this wiki page:
Claude Context is a multi-platform system designed to provide AI coding agents with deep, semantic context from entire codebases. It operates as a monorepo containing a core indexing engine, a Model Context Protocol (MCP) server, and extensions for VS Code and Chrome. The system bridges the gap between large-scale source code repositories and LLM-based agents by using vector embeddings and hybrid search to retrieve only relevant code snippets, thereby reducing token costs and improving retrieval quality.
Sources: README.md:16-24, packages/core/README.md:11-13, packages/mcp/README.md:12-14
System Components
The project is structured into three primary functional packages that work together to enable codebase indexing and retrieval.
| Package | Description |
|---|---|
@zilliz/claude-context-core | The fundamental engine handling file synchronization, code splitting (AST/LangChain), embedding generation, and vector database communication. |
@zilliz/claude-context-mcp | A server implementation of the Model Context Protocol that exposes tools for AI agents like Claude Code to index and search codebases. |
VSCode Extension | An IDE integration providing a UI for indexing, semantic search, and context-aware navigation directly within the developer workflow. |
Sources: README.md:330-340, packages/core/README.md:139-142, packages/mcp/README.md:652-656
Architectural Overview Diagram
The following diagram illustrates the relationship between the various clients, the core engine, and the external services (Embedding Providers and Vector Databases).
The Core Engine acts as the central orchestrator, managing data flow between various client interfaces and external AI/database services.
Sources: README.md:321-325, packages/core/README.md:144-156
Core Indexing Logic
The indexing process transforms raw source code into searchable vector representations. It utilizes intelligent chunking and incremental synchronization to maintain efficiency.
File Synchronization and Incremental Updates
Claude Context uses a Merkle tree-based approach to track file changes. By comparing SHA-256 hashes of file contents, the system identifies added, modified, or removed files without re-processing the entire codebase.
Sources: packages/core/README.md:118-135
Code Splitting Strategies
The system supports two primary methods for breaking code into manageable chunks:
- AST Code Splitter: Analyzes the Abstract Syntax Tree to split code by logical units like functions and classes.
- LangChain Splitter: A character-based chunking strategy with configurable overlap.
Sources: packages/core/README.md:73-76, examples/basic-usage/index.ts:50-55
Indexing Sequence Flow
The sequence diagram below describes the flow of a codebase indexing request.
This flow ensures that only necessary updates are sent to the vector database, significantly reducing API calls and processing time.
Sources: packages/core/README.md:118-135, packages/chrome-extension/src/background.ts:499-560
Search and Retrieval
Claude Context implements a Hybrid Code Search mechanism. While the primary search is semantic (dense vector), it also utilizes BM25 (sparse vector) for keyword-heavy queries to ensure accuracy across millions of lines of code.
Sources: README.md:325-327, packages/mcp/README.md:653-654
Search Data Structure
When a search is performed, the system returns a SemanticSearchResult object containing both the content and the exact location within the source file.
| Field | Type | Description |
|---|---|---|
content | string | The retrieved code snippet content. |
relativePath | string | Path to the file relative to the codebase root. |
startLine | number | Starting line number of the snippet. |
endLine | number | Ending line number of the snippet. |
score | number | Similarity score between 0 and 1. |
Sources: packages/core/README.md:95-102
MCP Server Implementation
The MCP server (@zilliz/claude-context-mcp) acts as an interface for AI agents using the standard Model Context Protocol. It exposes specific tools that the agent can invoke via stdio transport.
Available MCP Tools
index_codebase: Triggers the indexing process for a specific directory.search_code: Performs a natural language query against an indexed codebase.clear_index: Deletes the vector index for a specified path.get_indexing_status: Provides real-time progress for active indexing tasks.
Sources: packages/mcp/README.md:659-688, packages/mcp/CONTRIBUTING.md:66-84
Data Management
Vector Database (Milvus/Zilliz)
The system relies on Milvus or Zilliz Cloud for high-performance vector storage. It supports both gRPC (default) and RESTful API implementations. RESTful is typically used in environments like Chrome extensions where gRPC support is limited.
Sources: examples/basic-usage/index.ts:25-46, packages/chrome-extension/src/background.ts:117-122
Local Persistence
Persistence for synchronization data (Merkle snapshots) is managed locally on the user's machine to track codebase states between sessions.
Sources: packages/core/README.md:129-130
Conclusion
The High-Level Architecture of Claude Context is designed for scalability and efficiency. By separating the core indexing logic from specific client implementations and utilizing hybrid search with incremental indexing, it provides a robust infrastructure for feeding codebase context into AI models while maintaining cost-effectiveness for large projects.
Sources: README.md:20-24, packages/core/README.md:11-13