# elara-labs/code-context-engine architecture

> Architecture diagram of the GitHub repository elara-labs/code-context-engine, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-30). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/elara-labs/code-context-engine
- Repository: https://github.com/elara-labs/code-context-engine

## Overview

1. **Overall shape**
   - This repository is a Python 3.11+ CLI/runtime for “Code Context Engine,” a local code indexing and retrieval system that integrates with AI coding tools through MCP and editor-specific config files.
   - The core architectural boundary is between **project-local indexing/search state** and **external clients** such as Claude Code, Cursor, VS Code/Copilot, Gemini CLI, Codex, OpenCode, and Tabnine.

2. **Primary execution surfaces**
   - The main user entrypoint is the **`cce` CLI** in `src/context_engine/cli.py`.
   - Secondary surfaces are:
     - an **MCP server** for tool access,
     - a **local HTTP dashboard/server**,
     - and **editor/session hooks** that capture context and keep the index current.

3. **Indexing subsystem**
   - `src/context_engine/indexer/` is the ingestion pipeline for source files.
   - It handles file discovery, ignore rules, secret redaction, chunking, embedding, manifest tracking, git-aware indexing, and filesystem watching.
   - The important data flow is: repository files → semantic chunks → embeddings + metadata → persisted index state.

4. **Chunking and semantic parsing**
   - `chunker.py` and related indexer modules suggest AST-aware chunking for supported languages, with fallback line-based chunking for other text files.
   - README indicates Tree-sitter is used for semantic boundaries such as functions, classes, and modules.
   - This is the first major architecture boundary: raw files are transformed into smaller searchable units before any retrieval happens.

5. **Embedding and cache layer**
   - `embedder.py` and `embedding_cache.py` indicate embeddings are generated per chunk and cached by content hash.
   - The cache is central to fast re-indexing: unchanged chunks skip recomputation, which is why incremental updates are fast.
   - The repository supports both local embedding execution and Ollama-backed embedding via `compression/ollama_client.py` and README-described local vs Ollama modes.

6. **Storage subsystem**
   - `src/context_engine/storage/` is the persistence boundary.
   - It contains separate stores for:
     - **vector search**,
     - **full-text search**,
     - **graph relationships**,
     - and **backend selection** for local vs remote operation.
   - README states the system uses SQLite-based storage, including vector and FTS capabilities, with graph relationships persisted alongside the index. This implies the index is not just embeddings but a multi-index bundle.

7. **Retrieval subsystem**
   - `src/context_engine/retrieval/` turns a natural-language query into search candidates and ranks them.
   - Key pieces include query parsing, retrieval orchestration, and confidence scoring.
   - The retrieval path is hybrid: vector similarity + BM25/keyword matching, then graph expansion for related code. This is the main “search instead of re-read files” data flow exposed to agents.

8. **Graph expansion and code relationships**
   - `storage/graph_store.py` and `retrieval` modules imply explicit relationships such as imports and calls.
   - This is a distinct boundary from pure similarity search: once a chunk is found, related code can be pulled in through graph edges to give agents surrounding context without indexing entire files.

9. **Compression subsystem**
   - `src/context_engine/compression/` reduces the size of retrieved or generated text.
   - It includes rules, prompts, quality checks, and an Ollama client for LLM-assisted compression when available.
   - The output of retrieval is therefore not just “which chunks,” but “which chunks after compression,” which materially affects token economics and tool responses.

10. **Memory and session persistence**
   - `src/context_engine/memory/` stores cross-session knowledge such as decisions, code areas, and session summaries.
   - It uses its own database, grammar-based compression, extractive logic, migration support, and hook integration.
   - This forms a second persistence lane beside the code index: it remembers project decisions and prior work, not just source code.

11. **Integration layer for AI tools**
   - `src/context_engine/integration/` bridges the engine to external AI workflows.
   - `mcp_server.py` exposes the tool surface to MCP clients; `bootstrap.py`, `git_context.py`, and `session_capture.py` support initialization and session-aware behavior.
   - The README’s listed tools (`context_search`, `expand_chunk`, `related_context`, `session_recall`, `record_decision`, etc.) map to this layer.

12. **Editor and project bootstrap**
   - `editors.py`, `project_commands.py`, and `config.py` support auto-detecting editors and writing the correct per-editor configuration files.
   - `cce init` is the orchestration point that installs hooks, registers MCP servers, and writes instructions/config for the target editor(s).
   - This is where the repository crosses from “engine” into “workspace integration.”

13. **Dashboard and service hosting**
   - `src/context_engine/dashboard/` and `serve_http.py` provide a local status/dashboard UI.
   - The dashboard consumes index, session, and savings data to show freshness, history, and token savings.
   - It is a read-only observability surface over the same underlying index and memory stores.

14. **Operational boundaries and safety**
   - `indexer/secrets.py` and `memory` redaction logic show that sensitive data is filtered before persistence.
   - `ignorefile.py`, git hooks, and watcher support keep indexing scoped to relevant files and current changes.
   - `event_bus.py`, `services.py`, and `utils.py` likely provide internal coordination across these subsystems without exposing them directly to clients.

15. **Non-runtime parts of the repo**
   - `docs-src/`, `docs/`, and `benchmarks/` are substantial but ancillary: they support documentation, site generation, and reproducible benchmark reporting.
   - `benchmarks/run_benchmark.py` and the saved results show the project’s claim that retrieval/compression efficiency is a core product concern, not just a development detail.

16. **Diagramming summary**
   - If drawing the architecture, the main boxes are:
     - **CLI/bootstrap**
     - **Indexing pipeline**
     - **Storage backends**
     - **Retrieval/search**
     - **Compression**
     - **Memory/session store**
     - **MCP/editor integration**
     - **Dashboard/observability**
   - The key arrows are:
     - repository files → indexer → storage,
     - user query → retrieval → compressed context → MCP client,
     - sessions/hooks → memory store → recall tools,
     - and CLI/init → editor configs + hook installation.

Main entry points: [`src/context_engine/retrieval/retriever.py`](https://github.com/elara-labs/code-context-engine/blob/main/src/context_engine/retrieval/retriever.py) (Retriever), [`src/context_engine/storage`](https://github.com/elara-labs/code-context-engine/tree/main/src/context_engine/storage) (Storage), [`src/context_engine/integration`](https://github.com/elara-labs/code-context-engine/tree/main/src/context_engine/integration) (Integration), [`src/context_engine/indexer`](https://github.com/elara-labs/code-context-engine/tree/main/src/context_engine/indexer) (Indexer)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_g1["Entry & integration"]
  node_n1["CCE CLI<br/>entrypoint<br/>[cli.py]"]
  node_n2["Integration<br/>adapter layer"]
  node_n3["MCP server<br/>tool server<br/>[mcp_server.py]"]
  node_n4["Bootstrap<br/>workspace setup<br/>[bootstrap.py]"]
  node_n5["Project commands<br/>workspace commands"]
end

subgraph group_g2["Indexing pipeline"]
  node_n8["Indexer<br/>ingestion pipeline"]
  node_n9["Chunker<br/>semantic split<br/>[chunker.py]"]
  node_n10["Embedder<br/>embedding engine<br/>[embedder.py]"]
  node_n11["Embed cache<br/>content cache<br/>[embedding_cache.py]"]
end

subgraph group_g3["Storage backends"]
  node_n12["Storage<br/>persistence layer"]
  node_n13[("Vector store<br/>similarity index<br/>[vector_store.py]")]
  node_n14[("FTS store<br/>keyword index<br/>[fts_store.py]")]
  node_n15[("Graph store<br/>relationship index<br/>[graph_store.py]")]
end

subgraph group_g4["Retrieval & compression"]
  node_n16["Retriever<br/>search orchestration<br/>[retriever.py]"]
  node_n17["Query parser<br/>query analysis<br/>[query_parser.py]"]
  node_n18["Compressor<br/>context reduction<br/>[compressor.py]"]
end

subgraph group_g5["Memory & sessions"]
  node_n19["Memory<br/>session store"]
  node_n20["Hook server<br/>session capture<br/>[hook_server.py]"]
end

subgraph group_g6["Observability"]
  node_n6["HTTP server<br/>local service<br/>[serve_http.py]"]
  node_n7["Dashboard<br/>observability UI"]
end

node_n1 -->|"starts indexing"| node_n8
node_n1 -->|"boots integrations"| node_n2
node_n1 -->|"writes config"| node_n5
node_n2 -->|"exposes tools"| node_n3
node_n2 -->|"initializes workspace"| node_n4
node_n2 -->|"captures sessions"| node_n20
node_n6 -->|"serves ui"| node_n7
node_n8 -->|"chunks files"| node_n9
node_n8 -->|"embeds chunks"| node_n10
node_n10 -->|"reuses cache"| node_n11
node_n8 -->|"persists index"| node_n12
node_n12 -->|"stores vectors"| node_n13
node_n12 -->|"stores text"| node_n14
node_n12 -->|"stores graph"| node_n15
node_n16 -->|"parses query"| node_n17
node_n16 -->|"scores semantics"| node_n13
node_n16 -->|"matches keywords"| node_n14
node_n16 -->|"expands graph"| node_n15
node_n16 -->|"compresses context"| node_n18
node_n18 -->|"feeds tools"| node_n3
node_n20 -->|"writes memory"| node_n19
node_n19 -->|"serves recall"| node_n3
node_n7 -->|"reads metrics"| node_n19
node_n7 -->|"reads status"| node_n12

click node_n1 "https://github.com/elara-labs/code-context-engine/blob/main/src/context_engine/cli.py"
click node_n2 "https://github.com/elara-labs/code-context-engine/tree/main/src/context_engine/integration"
click node_n3 "https://github.com/elara-labs/code-context-engine/blob/main/src/context_engine/integration/mcp_server.py"
click node_n4 "https://github.com/elara-labs/code-context-engine/blob/main/src/context_engine/integration/bootstrap.py"
click node_n5 "https://github.com/elara-labs/code-context-engine/blob/main/src/context_engine/project_commands.py"
click node_n6 "https://github.com/elara-labs/code-context-engine/blob/main/src/context_engine/serve_http.py"
click node_n7 "https://github.com/elara-labs/code-context-engine/tree/main/src/context_engine/dashboard"
click node_n8 "https://github.com/elara-labs/code-context-engine/tree/main/src/context_engine/indexer"
click node_n9 "https://github.com/elara-labs/code-context-engine/blob/main/src/context_engine/indexer/chunker.py"
click node_n10 "https://github.com/elara-labs/code-context-engine/blob/main/src/context_engine/indexer/embedder.py"
click node_n11 "https://github.com/elara-labs/code-context-engine/blob/main/src/context_engine/indexer/embedding_cache.py"
click node_n12 "https://github.com/elara-labs/code-context-engine/tree/main/src/context_engine/storage"
click node_n13 "https://github.com/elara-labs/code-context-engine/blob/main/src/context_engine/storage/vector_store.py"
click node_n14 "https://github.com/elara-labs/code-context-engine/blob/main/src/context_engine/storage/fts_store.py"
click node_n15 "https://github.com/elara-labs/code-context-engine/blob/main/src/context_engine/storage/graph_store.py"
click node_n16 "https://github.com/elara-labs/code-context-engine/blob/main/src/context_engine/retrieval/retriever.py"
click node_n17 "https://github.com/elara-labs/code-context-engine/blob/main/src/context_engine/retrieval/query_parser.py"
click node_n18 "https://github.com/elara-labs/code-context-engine/blob/main/src/context_engine/compression/compressor.py"
click node_n19 "https://github.com/elara-labs/code-context-engine/tree/main/src/context_engine/memory"
click node_n20 "https://github.com/elara-labs/code-context-engine/blob/main/src/context_engine/memory/hook_server.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_n1,node_n2,node_n3,node_n4,node_n5 toneBlue
class node_n8,node_n9,node_n10,node_n11 toneAmber
class node_n12,node_n13,node_n14,node_n15 toneMint
class node_n16,node_n17,node_n18 toneRose
class node_n19,node_n20 toneIndigo
class node_n6,node_n7 toneTeal
```

## Components

### Entry & integration

CLI, MCP, editor bootstrap, and local serving surfaces.

- [CCE CLI](https://github.com/elara-labs/code-context-engine/blob/main/src/context_engine/cli.py): entrypoint · Main command-line interface and orchestration surface. · `src/context_engine/cli.py`
- [Integration](https://github.com/elara-labs/code-context-engine/tree/main/src/context_engine/integration): adapter layer · Bridges the engine to MCP clients, editor setup, and session capture. · `src/context_engine/integration`
- [MCP server](https://github.com/elara-labs/code-context-engine/blob/main/src/context_engine/integration/mcp_server.py): tool server · Exposes search, expansion, and memory tools to AI clients. · `src/context_engine/integration/mcp_server.py`
- [Bootstrap](https://github.com/elara-labs/code-context-engine/blob/main/src/context_engine/integration/bootstrap.py): workspace setup · Initializes project integrations, git context, and session wiring. · `src/context_engine/integration/bootstrap.py`
- [Project commands](https://github.com/elara-labs/code-context-engine/blob/main/src/context_engine/project_commands.py): workspace commands · Writes editor configs and installs project-local command hooks. · `src/context_engine/project_commands.py`

### Indexing pipeline

Turns repository files into chunks, embeddings, and index state.

- [Indexer](https://github.com/elara-labs/code-context-engine/tree/main/src/context_engine/indexer): ingestion pipeline · Repository file discovery, chunking, embedding, and persistence. · `src/context_engine/indexer`
- [Chunker](https://github.com/elara-labs/code-context-engine/blob/main/src/context_engine/indexer/chunker.py): semantic split · AST-aware and fallback chunk boundaries for source and text files. · `src/context_engine/indexer/chunker.py`
- [Embedder](https://github.com/elara-labs/code-context-engine/blob/main/src/context_engine/indexer/embedder.py): embedding engine · Generates embeddings for chunks and coordinates embedding backends. · `src/context_engine/indexer/embedder.py`
- [Embed cache](https://github.com/elara-labs/code-context-engine/blob/main/src/context_engine/indexer/embedding_cache.py): content cache · Caches embeddings by content hash to accelerate incremental re-indexing. · `src/context_engine/indexer/embedding_cache.py`

### Storage backends

Persistence for vector, text, graph, and backend selection.

- [Storage](https://github.com/elara-labs/code-context-engine/tree/main/src/context_engine/storage): persistence layer · Backend selection and store implementations for index data. · `src/context_engine/storage`
- [Vector store](https://github.com/elara-labs/code-context-engine/blob/main/src/context_engine/storage/vector_store.py): similarity index · Persists vector search data for semantic retrieval. · `src/context_engine/storage/vector_store.py`
- [FTS store](https://github.com/elara-labs/code-context-engine/blob/main/src/context_engine/storage/fts_store.py): keyword index · Persists full-text search data for BM25 and lexical matching. · `src/context_engine/storage/fts_store.py`
- [Graph store](https://github.com/elara-labs/code-context-engine/blob/main/src/context_engine/storage/graph_store.py): relationship index · Persists code relationships such as imports and call links. · `src/context_engine/storage/graph_store.py`

### Retrieval & compression

Query handling, ranking, expansion, and context reduction.

- [Retriever](https://github.com/elara-labs/code-context-engine/blob/main/src/context_engine/retrieval/retriever.py): search orchestration · Combines query parsing, hybrid ranking, and graph expansion. · `src/context_engine/retrieval/retriever.py`
- [Query parser](https://github.com/elara-labs/code-context-engine/blob/main/src/context_engine/retrieval/query_parser.py): query analysis · Interprets natural-language search requests and retrieval intent. · `src/context_engine/retrieval/query_parser.py`
- [Compressor](https://github.com/elara-labs/code-context-engine/blob/main/src/context_engine/compression/compressor.py): context reduction · Shrinks retrieved or generated context to fit token budgets. · `src/context_engine/compression/compressor.py`

### Memory & sessions

Cross-session decisions, summaries, and hook-based capture.

- [Memory](https://github.com/elara-labs/code-context-engine/tree/main/src/context_engine/memory): session store · Persists decisions, summaries, and cross-session knowledge. · `src/context_engine/memory`
- [Hook server](https://github.com/elara-labs/code-context-engine/blob/main/src/context_engine/memory/hook_server.py): session capture · Receives editor and agent events for memory capture workflows. · `src/context_engine/memory/hook_server.py`

### Observability

Local dashboard and service endpoints for status and savings.

- [HTTP server](https://github.com/elara-labs/code-context-engine/blob/main/src/context_engine/serve_http.py): local service · Serves the local dashboard and related HTTP endpoints. · `src/context_engine/serve_http.py`
- [Dashboard](https://github.com/elara-labs/code-context-engine/tree/main/src/context_engine/dashboard): observability UI · Read-only view over index freshness, history, and savings. · `src/context_engine/dashboard`

## Connections

- CCE CLI → Indexer: starts indexing · The CLI orchestrates repository indexing and maintenance.
- CCE CLI → Integration: boots integrations · The CLI sets up MCP, hooks, and editor-facing integrations.
- CCE CLI → Project commands: writes config · Project commands install editor configs and local project commands.
- Integration → MCP server: exposes tools · Integration layer publishes engine capabilities through MCP.
- Integration → Bootstrap: initializes workspace · Bootstrap wires project context and session-aware setup.
- Integration → Hook server: captures sessions · Integration forwards session events into memory capture.
- HTTP server → Dashboard: serves ui · HTTP service hosts the dashboard and related views.
- Indexer → Chunker: chunks files · Source files are segmented into searchable units.
- Indexer → Embedder: embeds chunks · Chunks are transformed into embeddings.
- Embedder → Embed cache: reuses cache · Embedding computation skips unchanged content via cache.
- Indexer → Storage: persists index · Ingested chunks and metadata are written to storage.
- Storage → Vector store: stores vectors · Vector data is persisted for semantic search.
- Storage → FTS store: stores text · Lexical index data is persisted for keyword search.
- Storage → Graph store: stores graph · Relationship edges are persisted alongside the index.
- Retriever → Query parser: parses query · Search requests are interpreted before retrieval execution.
- Retriever → Vector store: scores semantics · Retriever consults vector similarity for candidate search.
- Retriever → FTS store: matches keywords · Retriever consults full-text search for lexical candidates.
- Retriever → Graph store: expands graph · Retriever pulls related code through graph edges.
- Retriever → Compressor: compresses context · Retrieved context is reduced before returning to clients.
- Compressor → MCP server: feeds tools · Compressed context is returned through tool surfaces.
- Hook server → Memory: writes memory · Captured sessions and decisions are persisted for recall.
- Memory → MCP server: serves recall · Memory is surfaced to clients through MCP tools.
- Dashboard → Memory: reads metrics · Dashboard consumes session and savings information.
- Dashboard → Storage: reads status · Dashboard reflects index and storage state.
