Semantic code search helps find an implementation when you can describe what it does but do not know its name. Instead of starting with an exact function or string, start with a question such as “Where is a failed operation retried, and what stops the retries?”
This is useful when investigating unfamiliar code, taking over an undocumented application, or giving an AI coding assistant a relevant starting point. It retrieves candidate source, not a verified explanation of the system.
Semantic search versus exact search
Exact search looks for the text you specify. Use it for a known identifier, error message, configuration key, or regular expression. An editor search or a tool such as rg can check that text directly in the current checkout without building a semantic index.
Semantic search compares the meaning represented by a query and indexed code chunks. An embedding model converts both into numerical vectors; retrieval finds chunks whose vectors are similar. The wording need not be identical, but similarity is not proof that a result implements the behaviour you asked about.
Use semantic search to discover where to look. Use exact search to narrow the investigation once the actual names are known. Neither replaces reading the surrounding source or testing behaviour.
How SocratiCode's hybrid retrieval works
SocratiCode combines two searches for a project:
- Semantic retrieval ranks indexed code chunks by vector similarity to the query.
- Keyword retrieval uses BM25 to rank chunks by matching terms. This is ranked lexical retrieval, not a literal substring or regular-expression scan.
- Reciprocal Rank Fusion (RRF) combines the positions in those two result lists into one ranked list.
This lets a question include both behaviour and a known identifier. The keyword side can favour code containing that identifier; the semantic side can surface related implementations with different wording. A fusion score is a retrieval score, not a probability that the result is correct.
The codebase_search tool documentation describes the available query, file, language, and result-limit parameters. Results include source paths, line ranges, and code to inspect. These are MCP tool calls made through a compatible assistant, not terminal commands.
A worked example: find the retry policy
Suppose an unfamiliar application contains this helper. The file name and code below are illustrative, not a recorded search result or benchmark.
// src/request-policy.js
export async function runWithRetry(operation) {
for (let attempt = 0; attempt < 3; attempt += 1) {
try {
return await operation();
} catch (error) {
if (attempt === 2) throw error;
await new Promise((resolve) => setTimeout(resolve, 200 * 2 ** attempt));
}
}
}
1. Start with the behaviour, not a guessed name
Connect SocratiCode using the setup guide for your coding host. Confirm with codebase_status that indexing has completed for the intended project and check which source revision the index represents.
Ask the assistant to call codebase_search with these arguments:
{
"query": "Where is a failed operation retried, and what stops the retries?",
"limit": 5
}
The phrase “failed operation” does not appear in the helper. A literal search for that phrase would miss it. Semantic retrieval may find it from the relationship between attempts, caught errors, and repeated calls. The result is not guaranteed: coverage, the embedding model, and other candidate code affect retrieval.
2. Open the candidate and check what it actually does
If a result points to runWithRetry, open the source and its surrounding code. In this example, the helper makes at most three attempts. After the first two failures it waits 200 milliseconds and 400 milliseconds respectively. A third failure is thrown to the caller; a successful attempt returns immediately.
That establishes what this helper does. It does not establish that every request uses it, which errors its callers supply, or whether repeating a particular operation is safe.
3. Switch to the exact identifier
Search the checkout for the discovered name:
rg -n -F 'runWithRetry' src/
Inspect its definitions and uses, then follow relevant callers or dependencies with SocratiCode's symbol and graph tools where supported. Exact-name matches alone may miss indirect calls or aliases. Check the applicable tests before concluding that a proposed change preserves the application's retry behaviour.
For a larger investigation, continue with the legacy-code workflow.
Local and shared deployment boundaries
The search method and the deployment choice are separate decisions. A team can use hybrid retrieval with a local index or with an explicitly configured shared index.
Local indexing and search
The default open-source setup uses Ollama for embeddings and managed local Qdrant for storage. Source chunks go to the configured embedding endpoint; Qdrant stores the searchable index, including code content and metadata. With local endpoints, those indexing and retrieval paths stay on the machine. Initial package, container-image, and model downloads can still require internet access.
The coding assistant is a separate boundary. A hosted assistant may send prompts and returned source excerpts to its provider even when embeddings and Qdrant run locally. Local indexing alone does not make the entire assistant workflow local or air-gapped. Review the source-code data boundaries before using sensitive code.
A shared team index
The documented open-source pattern uses an external Qdrant endpoint and a stable projectId. One designated checkout writes the index; teammates query it from reader checkouts. Keep the embedding and indexed-representation settings aligned, control who can access the endpoint, and coordinate source revisions. Pointing several machines at one database is not, by itself, an access-control or tenant-isolation policy.
A shared index represents the source its writer indexed. It is not a live union of every developer's branch or uncommitted changes. Read the shared-context operating pattern for writer ownership, reader settings, and revision checks.
Cloud embeddings send source chunks to the configured provider. External Qdrant sends stored code and metadata to the configured server. SocratiCode Cloud remains a private beta; managed deployment and required controls are discussed for each engagement, not assumed from the open-source configuration.
What a search result cannot establish
Search can only retrieve content covered by the index. Excluded files, unfinished indexing, stale source, and chunk or model limits can reduce what it finds. An empty result does not prove that a behaviour is absent.
Retrieved source can guide dependency inspection and change-impact analysis, but it does not prove runtime behaviour, recover missing business intent, or validate a refactor. Treat the result as a source reference to investigate, then check configuration, contracts, and the relevant tests.
Start with one question you can verify
Choose one behaviour already known to exist in the repository. Complete indexing, run a behaviour-led search, and check the returned source. Then try its actual identifier with exact search. This gives the team a concrete way to evaluate retrieval on its own code without relying on a generic performance claim.
Use the host setup guides to try the open-source engine. Teams evaluating a shared service or implementation support can discuss the design-partner route. Full configuration and index-profile details are in the technical documentation.