# How Semantic Search Utilizes Bundled nomic-embed-code Embeddings in codebase-memory-mcp

> Discover how codebase-memory-mcp uses bundled nomic-embed-code embeddings for local semantic search. Enjoy fast, secure, API-free vector matching directly in the binary.

- Repository: [Martin Vogel/codebase-memory-mcp](https://github.com/DeusData/codebase-memory-mcp)
- Tags: how-to-guide
- Published: 2026-07-28

---

**The codebase-memory-mcp server embeds the nomic-embed-code model's 768-dimensional vectors directly into the compiled binary, enabling fully local semantic search via cosine similarity matching without requiring external API keys or network calls.**

The DeusData/codebase-memory-mcp repository implements a local-first semantic search engine that bundles the **nomic-embed-code** (7B) embedding model directly into its executable. By pre-computing token vectors at build time and compiling them into C headers, the system eliminates runtime dependencies on external embedding services while delivering sub-second similarity search across indexed codebases.

## Build-Time Embedding Generation

### Vector Extraction Pipeline

The embedding generation process begins in [`scripts/extract_nomic_vectors.py`](https://github.com/DeusData/codebase-memory-mcp/blob/main/scripts/extract_nomic_vectors.py), which downloads the open-source **nomic-embed-code** model and extracts **768-dimensional vectors** for every token in the vocabulary. According to the source analysis, this script writes the vector data to both a C header file at [`vendored/nomic/code_vectors.h`](https://github.com/DeusData/codebase-memory-mcp/blob/main/vendored/nomic/code_vectors.h) and a binary blob at `vendored/nomic/code_vectors.bin` (lines 3‑11), creating a static lookup table that gets baked into the final executable.

### Header Compilation

During the build process, [`src/semantic/semantic.c`](https://github.com/DeusData/codebase-memory-mcp/blob/main/src/semantic/semantic.c) includes the generated header via `#include "nomic/code_vectors.h"` (line 17), making the full token-vector lookup table available at runtime without requiring external model files or dynamic loading mechanisms.

## Runtime Query Processing Architecture

### Semantic Query Parsing

When a client invokes the `search_graph` tool with a `semantic_query` parameter, the request handler in [`src/mcp/mcp.c`](https://github.com/DeusData/codebase-memory-mcp/blob/main/src/mcp/mcp.c) parses the JSON argument using `yyjson_obj_get(..., "semantic_query")` (line 2972). The system expects an array of keyword strings that represent conceptual search terms rather than literal code tokens.

### Vector Lookup and Similarity Calculation

The function `run_semantic_query_core` validates the input array and prefixes each token with **`search_query:`** (a required formatting convention for the nomic-embed-code model). It then retrieves the corresponding 768-dimensional vectors from the bundled table and combines them to form a single query vector (lines 2957‑3001). The system computes **cosine similarity** between this query vector and every stored token vector in the compiled table, returning the top-N matches as `semantic_results`.

## Result Integration and Graph Construction

### Semantic Edge Creation

The matched tokens populate `semantic_results` in the JSON response (lines 3516‑3537 of [`src/mcp/mcp.c`](https://github.com/DeusData/codebase-memory-mcp/blob/main/src/mcp/mcp.c)). These results enable the creation of **`SIMILAR_TO`** and **`SEMANTICALLY_RELATED`** edges in the knowledge graph, linking conceptually related code symbols even when they don't share literal token names in the source.

### Conceptual Bridging

This architecture allows callers to discover code snippets that are semantically related to query terms. For example, searching for "publish" will return functions containing "send" because the **nomic-embed-code** embeddings capture the conceptual relationship between these terms in the shared 768-dimensional vector space.

## Practical Usage Examples

### Command-Line Interface

Execute semantic searches directly from the terminal using the `search_graph` command with the `--semantic_query` flag:

```bash
codebase-memory-mcp search_graph --semantic_query="send, publish"

```

### JSON API Request

The underlying MCP protocol accepts semantic queries as JSON arrays through the `search_graph` tool:

```json
{
  "project": "myrepo",
  "semantic_query": ["send", "publish"]
}

```

### Python Client Integration

Use the provided `cbm` wrapper for programmatic access to the semantic search capabilities:

```python
from codebase_memory_mcp import CBMClient

client = CBMClient()
results = client.search_graph(
    project="myrepo",
    semantic_query=["send", "publish"]
)
print(results["semantic_results"])

```

## Local-First Architecture Benefits

### Zero External Dependencies

Unlike cloud-based embedding services, this implementation operates entirely offline. As documented in [`docs/index.html`](https://github.com/DeusData/codebase-memory-mcp/blob/main/docs/index.html) (lines 176‑180): "Alongside structural and BM25 full-text search, it offers semantic vector search powered by **nomic-embed-code** embeddings compiled directly into the binary (768-dimensional) ... No API key, fully local."

### Performance and Privacy

By eliminating network round-trips and model loading overhead, the bundled approach delivers consistent sub-second query latency. All vector operations occur within the [`src/mcp/mcp.c`](https://github.com/DeusData/codebase-memory-mcp/blob/main/src/mcp/mcp.c) and [`src/semantic/semantic.c`](https://github.com/DeusData/codebase-memory-mcp/blob/main/src/semantic/semantic.c) modules, ensuring that proprietary codebases never leave the local environment during semantic analysis.

## Summary

- **[`scripts/extract_nomic_vectors.py`](https://github.com/DeusData/codebase-memory-mcp/blob/main/scripts/extract_nomic_vectors.py)** generates static C headers from the nomic-embed-code model at build time, creating [`vendored/nomic/code_vectors.h`](https://github.com/DeusData/codebase-memory-mcp/blob/main/vendored/nomic/code_vectors.h) and the binary blob.
- **[`src/semantic/semantic.c`](https://github.com/DeusData/codebase-memory-mcp/blob/main/src/semantic/semantic.c)** embeds these vectors into the executable via `#include "nomic/code_vectors.h"`, making 768-dimensional lookups available at runtime.
- **`run_semantic_query_core`** in [`src/mcp/mcp.c`](https://github.com/DeusData/codebase-memory-mcp/blob/main/src/mcp/mcp.c) processes queries by prefixing tokens with `search_query:` and computing cosine similarity against the bundled table.
- The **`semantic_results`** field enables creation of `SIMILAR_TO` and `SEMANTICALLY_RELATED` graph edges for conceptual code discovery.
- Fully local operation requires no API keys, Docker containers, or external services—embeddings are baked directly into the binary.

## Frequently Asked Questions

### How are the nomic-embed-code embeddings bundled into the binary?

The build process executes [`scripts/extract_nomic_vectors.py`](https://github.com/DeusData/codebase-memory-mcp/blob/main/scripts/extract_nomic_vectors.py) to download the model and export token vectors to [`vendored/nomic/code_vectors.h`](https://github.com/DeusData/codebase-memory-mcp/blob/main/vendored/nomic/code_vectors.h). The C compiler then embeds this data directly into the executable when compiling [`src/semantic/semantic.c`](https://github.com/DeusData/codebase-memory-mcp/blob/main/src/semantic/semantic.c), creating a static lookup table available at runtime without external dependencies.

### What embedding dimensions does the semantic search use?

The system utilizes **768-dimensional vectors** from the nomic-embed-code (7B) parameter model. These dimensions provide sufficient semantic resolution for accurate code similarity matching while maintaining efficient memory usage through static compilation.

### Do I need an API key to use the semantic search functionality?

No. Because the embeddings are compiled directly into the binary and all similarity computations occur locally within [`src/mcp/mcp.c`](https://github.com/DeusData/codebase-memory-mcp/blob/main/src/mcp/mcp.c), the system requires no API keys, network connectivity, or external embedding services. The documentation explicitly confirms this "fully local" architecture.

### Why does the system prefix queries with "search_query:"?

The `run_semantic_query_core` function prefixes each token with **`search_query:`** to conform to the nomic-embed-code model's input formatting requirements. This prefix signals to the embedding space that the input represents a retrieval query rather than raw code content, ensuring proper vector alignment during cosine similarity calculations.