> ## Documentation Index
> Fetch the complete documentation index at: https://docs.codanna.sh/llms.txt
> Use this file to discover all available pages before exploring further.

# Semantic Search

> Find code and documents by meaning, not just text

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.

<Tabs>
  <Tab title="JavaScript/TypeScript">
    ```javascript theme={null}
    class AuthService {
      /**
       * Authenticate user with email and password.
       * Returns JWT token on success.
       */
      static default(config) { ... }
    }
    ```
  </Tab>

  <Tab title="Python">
    ```python theme={null}
    class AuthService:
        def __call__(self, email: str, password: str) -> str:
            """
            Authenticate user with email and password.
            Returns JWT token on success.
            """
            ...
    ```
  </Tab>

  <Tab title="Rust">
    ```rust theme={null}
    impl AuthService {
        /// Authenticate user with email and password.
        /// Returns JWT token on success.
        pub fn new(email: &str, password: &str) -> Self { ... }
    }
    ```
  </Tab>
</Tabs>

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

```bash theme={null}
codanna mcp semantic_search_docs query:"user authentication" limit:3
```

```text theme={null}
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

```bash theme={null}
codanna mcp semantic_search_with_context query:"error handling" limit:1
```

```text theme={null}
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:

```bash theme={null}
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.

```bash theme={null}
# 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:

```bash theme={null}
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:

```bash theme={null}
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):

```bash theme={null}
export CODANNA_EMBED_API_KEY=sk-...
```

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

```toml theme={null}
[semantic_search]
remote_url = "http://localhost:11434"
remote_model = "nomic-embed-text"
remote_dim = 768
```

Environment variables take precedence over `settings.toml`.

<Warning>
  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.
</Warning>

### 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:

```text theme={null}
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:

```bash theme={null}
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 |

## Next Steps

<CardGroup cols={2}>
  <Card title="Relationships" icon="diagram-project" href="/features/relationships">
    Trace calls, callers, and impact.
  </Card>

  <Card title="Tool Tiers" icon="layer-group" href="/workflows/tool-tiers">
    Which tool to use when.
  </Card>
</CardGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.