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

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, 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 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 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 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). 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:

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:

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

Python Client Integration

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

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 (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 and src/semantic/semantic.c modules, ensuring that proprietary codebases never leave the local environment during semantic analysis.

Summary

• scripts/extract_nomic_vectors.py generates static C headers from the nomic-embed-code model at build time, creating vendored/nomic/code_vectors.h and the binary blob.
• 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 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 to download the model and export token vectors to vendored/nomic/code_vectors.h. The C compiler then embeds this data directly into the executable when compiling 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, 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}