# Code Intelligence Architecture: mcp-vector-search Technical Summary
**Date:** 2026-04-22
**Purpose:** Competitive analysis vs. Graphify — internal reference

---

## 1. Knowledge Graph (KG) Component

**Storage:** KuzuDB (embedded graph database, Cypher-compatible).

**Schema nodes:** `CodeEntity`, `DocSection`, `Document`, `Tag`, `Person`, `Project`, `Repository`, `Branch`, `Commit`, `ProgrammingLanguage`, `ProgrammingFramework`.

**Build process (`kg_builder.py` / `KGBuilder`):**
- Ingests indexed code chunks (already stored in LanceDB)
- Per-chunk: extracts entity name (function/class/module), resolves `self.method()` / `cls.method()` via class-membership scoping
- Detects relationships: `CALLS`, `INHERITS`, `CONTAINS`, `IMPORTS`, `AUTHORED_BY`, `MODIFIED_BY`, `PART_OF`
- Processes git blame to attach `Person` and `Commit` nodes (temporal layer)
- Builds IA (information architecture) topic tree from directory structure
- Supports differential builds: only re-processes changed file hashes

**Temporal dimension:** Last-modified timestamps drive decay multipliers on relevance scores, so stale code ranks lower automatically.

---

## 2. Hybrid Search Approach

Three parallel strategies fused via **Reciprocal Rank Fusion (RRF)**:

| Strategy | Backend | Description |
|----------|---------|-------------|
| Semantic | LanceDB (vector ANN) | Embedding similarity — finds conceptually related code |
| Text/Keyword | BM25Okapi (`rank_bm25`) | Probabilistic keyword match; indexes content + function name + class name + file path |
| KG | KuzuDB Cypher | Graph traversal — entities, relationships, callers/callees |

Each strategy retrieves `limit * 3` candidates; RRF fuses and deduplicates, then a minimum confidence threshold filters noise before the final `limit` results are returned.

**Status note:** README roadmap lists "Hybrid search (vector + keyword + BM25)" as a future item under the roadmap checkboxes, but the implementation in `hybrid_search_handler.py` is fully coded and shipping.

---

## 3. Token Delivery to LLMs

**Embedding-time context injection (`context_builder.py`):**

Each chunk is embedded with a compact pipe-separated metadata header prepended:
```
File: src/foo.py | Lang: python | Class: MyClass | Fn: my_method | Uses: os, re | Desc: Does X
---
<original code content>
```
- Header: ~15–25 tokens (MiniLM 256-token limit)
- Remaining budget for code: ~230–240 tokens
- Stored content in LanceDB is the raw code (unmodified); only the embedding input is enriched

**Search result output to LLMs (`_format_search_results`):**
Each result block contains: file path, function name, class name, line range, similarity score, and the full raw code content in a fenced code block. No truncation at the result-formatting layer for `search_code`; `search_similar` caps content preview at 500 chars.

**Claimed improvement:** 35–49% fewer retrieval failures (cites Anthropic contextual chunking research).

---

## 4. Indexing Structures

- **Vector store:** LanceDB (local, columnar ANN index)
- **Embedding models:** `sentence-transformers/all-MiniLM-L6-v2` (default), `microsoft/codebert-base`, or `Salesforce/codet5p-110m-embedding` (code-optimized)
- **MPS acceleration:** Apple Silicon Metal Performance Shaders for 2-4x faster embedding
- **BM25 index:** In-memory `BM25Okapi`, rebuilt from chunks on demand, serialized via pickle
- **KG store:** KuzuDB embedded graph (separate from LanceDB)
- **Chunk metadata stored:** `file_path`, `language`, `function_name`, `class_name`, `start_line`, `end_line`, `imports`, `docstring`, `content`, embedding vector
- **Storage estimate:** ~50MB baseline + ~1MB per 1000 chunks; ~1KB per chunk compressed

---

## 5. MCP Tools Inventory

| Tool | Description |
|------|-------------|
| `search_code` | Semantic vector search with similarity scores and code content |
| `search_similar` | Find code similar to a given file/function |
| `search_context` | High-level context search: accepts a natural-language description + optional focus_areas; uses hybrid mode by default |
| `search_hybrid` | Explicit 3-way RRF fusion (semantic + BM25 + KG) with configurable alpha |
| `kg_query` | Direct Cypher or structured KG query for relationships |
| `kg_ia` | Returns the information architecture (IA) topic tree — directory-level overview |
| `kg_build` | Trigger incremental or full KG build |
| `kg_stats` | Node/edge counts, build metadata |
| `kg_ontology` | Schema inspection |
| `kg_history` | Git-aware historical relationship queries |
| `kg_callers_at_commit` | Callers of a function at a specific git commit (temporal) |
| `trace_execution_flow` | Traverse call graph from an entry point; configurable depth (1–8), direction (outgoing/incoming/both), max 100 nodes; returns nodes, edges, ordered call-chain paths |
| `analyze_file`, `analyze_project` | Static complexity and smell analysis |
| `check_circular_dependencies` | Detect import cycles |
| `code_review`, `review_pull_request`, `review_repository` | LLM-assisted review workflows |
| `story_generate`, `wiki_generate` | Documentation generation |
| `save_report` | Persist analysis reports |

---

## 6. Token Efficiency Claims (README)

- Contextual chunking: **35–49% fewer retrieval failures**
- KG queries: **<0.2s** for relationship lookups
- Smart caching: unchanged chunks return cached results instantly
- Apple Silicon MPS: **2–4x faster** embedding generation

---

## 7. What Makes This "Code Intelligence" vs. Naive RAG

| Naive RAG | mcp-vector-search |
|-----------|-------------------|
| Chunk text, embed, ANN retrieve | Contextual chunking: metadata header injected at embed time, not retrieval time |
| Single-modality (vector only) | Three-modality fusion: semantic + BM25 + graph traversal (RRF) |
| No structural awareness | KG tracks CALLS, INHERITS, CONTAINS, IMPORTS — structural queries possible |
| No temporal awareness | Git blame integration: author, commit, last-modified decay |
| No execution tracing | `trace_execution_flow` traverses live call graph with configurable depth/direction |
| Static snapshots | Differential builds: only reindexes changed files |
| Generic text embeddings | Code-specific embedding model options (CodeBERT, CodeT5+) |

---

## Known Limitations

- BM25 index is in-memory and serialized as pickle (not persistent across restarts without rebuild)
- README roadmap checkbox for hybrid search is unchecked (implementation exists but may be considered experimental)
- MiniLM 256-token limit constrains chunk size; larger functions must be split, potentially losing context
- `trace_execution_flow` hard-caps at 8 hops and 100 nodes — deep monolithic codebases may truncate
- `search_similar` content preview truncates at 500 chars (may omit relevant code)
- KuzuDB is embedded (single-process); no multi-project KG federation (listed as future roadmap)

---

*Research file: docs/research/code-intelligence-architecture-vs-graphify-2026-04-22.md*
