Semantic Search

Codanna is a local code intelligence MCP server and CLI for AI coding agents. Semantic search finds code and documents by meaning. Instead of matching exact text, it understands what you’re looking for and returns relevant results even when terminology differs.

Code Search

Search documentation comments on symbols using natural language.

JavaScript/TypeScript
Python
Rust

class AuthService {
  /**
   * Authenticate user with email and password.
   * Returns JWT token on success.
   */
  static default(config) { ... }
}

class AuthService:
    def __call__(self, email: str, password: str) -> str:
        """
        Authenticate user with email and password.
        Returns JWT token on success.
        """
        ...

impl AuthService {
    /// Authenticate user with email and password.
    /// Returns JWT token on success.
    pub fn new(email: &str, password: &str) -> Self { ... }
}

Symbol names don’t always describe their purpose - new(), Default, impl, or abbreviated names like above. Semantic search finds them through their documentation, not the name.

Basic Search

codanna mcp semantic_search_docs query:"user authentication" limit:3

Found 3 semantically similar result(s) for 'user authentication':

1. name (Field) - Similarity: 0.356
   File: src/plugins/marketplace.rs:40
   Doc: Owner name (user or organization)

2. name (Field) - Similarity: 0.356
   File: src/profiles/provider.rs:40
   Doc: Owner name (user or organization)

3. credential_callback (Function) - Similarity: 0.332
   File: src/profiles/git.rs:80
   Doc: Credential callback for git2 authentication

Search with Context

codanna mcp semantic_search_with_context query:"error handling" limit:1

Found 1 results for query: 'error handling'

1. error - Method at src/io/format.rs:149-163 [symbol_id:5240]
   Similarity Score: 0.642
   Documentation:
     Create a generic error response.
   Signature: pub fn error(code: ExitCode, message: &str, suggestions: Vec<&str>) -> Self

   error calls 2 function(s):
     -> Module collect at src/indexing/pipeline/stages/mod.rs:10 [symbol_id:3222]
     -> Method iter at src/storage/memory.rs:105 [symbol_id:4480]

   error uses 1 type(s):
     -> Enum ExitCode at src/io/exit_code.rs:19-47 [symbol_id:5076]

Returns symbols with line ranges, relationships (calls, callers, types), and [symbol_id:X] for follow-up queries.

Language Filtering

Filter results by programming language:

codanna mcp semantic_search_docs query:"configuration parsing" lang:rust
codanna mcp semantic_search_with_context query:"React components" lang:typescript

Document Search

Search markdown and text files indexed in collections.

# Add and index a collection
codanna documents add-collection docs docs/
codanna documents index

# Search
codanna documents search "authentication flow"

# Or via MCP
codanna mcp search_documents query:"setup guide" limit:5

Writing Good Queries

Be specific:

Bad: “error”
Good: “error handling in file operations”

Use domain terms:

Bad: “make things fast”
Good: “performance optimization for indexing”

Add context:

Bad: “parse”
Good: “parse TypeScript import statements”

Understanding Scores

Similarity scores range from 0 to 1:

Score	Relevance
0.7+	Strong match
0.5-0.7	Relevant
0.3-0.5	Weak match
<0.3	Likely irrelevant

Use threshold to filter weak results:

codanna mcp semantic_search_docs query:"validation" threshold:0.5

Remote Embedding Backend

Use an OpenAI-compatible HTTP embedding server instead of the local fastembed model. Supports OpenAI, Ollama, vLLM, Infinity, and any server implementing POST /v1/embeddings.

Configuration

Set environment variables to enable remote mode:

export CODANNA_EMBED_URL=http://localhost:11434    # Server base URL
export CODANNA_EMBED_MODEL=nomic-embed-text        # Model name
export CODANNA_EMBED_DIM=768                        # Output dimension

For servers requiring authentication (OpenAI, cloud providers):

export CODANNA_EMBED_API_KEY=sk-...

Or configure in settings.toml (except the API key, which is env-var only):

[semantic_search]
remote_url = "http://localhost:11434"
remote_model = "nomic-embed-text"
remote_dim = 768

Environment variables take precedence over settings.toml.

API keys are read from CODANNA_EMBED_API_KEY only. They are intentionally not stored in config files, which may be team-shared via profiles.

Switching Between Local and Remote

When you change embedding backends, the stored index dimension may not match the new backend. Codanna detects this and disables semantic search with an error:

ERROR: semantic search disabled -- index incompatible:
Index was built with 384-dimensional embeddings but current backend produces 768d.
Re-index with: codanna index <path> --force

Re-index with --force to rebuild with the new backend:

codanna index --force

Tested Providers

Provider	Model	Dimensions	Auth
Ollama	nomic-embed-text	768	None
OpenAI	text-embedding-3-small	1536	Bearer token
vLLM	Any supported model	Varies	Optional
Infinity	Any supported model	Varies	Optional

Overview

Features

Workflows

Semantic Search

Code Search

Basic Search

Search with Context

Language Filtering

Document Search

Writing Good Queries

Understanding Scores

Remote Embedding Backend

Configuration

Switching Between Local and Remote

Tested Providers

Next Steps

Relationships

Tool Tiers

​Code Search

​Basic Search

​Search with Context

​Language Filtering

​Document Search

​Writing Good Queries

​Understanding Scores

​Remote Embedding Backend

​Configuration

​Switching Between Local and Remote

​Tested Providers

​Next Steps

Relationships

Tool Tiers

Code Search

Basic Search

Search with Context

Language Filtering

Document Search

Writing Good Queries

Understanding Scores

Remote Embedding Backend

Configuration

Switching Between Local and Remote

Tested Providers

Next Steps