Skip to content
Nella

RAG & Indexing

AST-aware code indexing and hybrid search for grounding AI agents in real code.

Nella’s indexing system turns your codebase into a searchable knowledge base that agents can query in real time. Every answer is grounded in actual code — not hallucinated APIs.

How It Works

  1. Index your workspace with nella_index — files are parsed into AST-aware chunks
  2. Search with nella_search — hybrid semantic + lexical retrieval finds relevant code
  3. Carry trust forward with nella_heartbeat — each tool call can verify continuity between steps

Indexing (nella_index)

Scans your workspace, chunks files intelligently, generates embeddings, and persists the index to disk. Subsequent runs skip unchanged files when the index is still valid.

Parameters

ParameterTypeRequiredDescription
forcebooleanNoRe-index all files, ignoring cache
pathsstring[]NoOnly index specific paths

Chunking Strategy

The local MCP flow uses AST chunking by default with maxTokens: 512 and overlap: 50. Nella stores the resulting index under .nella/index in the workspace.

Indexing prerequisites

Local indexing requires either nella auth login for Nella-hosted embeddings or Azure embedding environment variables.

Hybrid search combining vector similarity and BM25 lexical matching, fused with Reciprocal Rank Fusion (RRF).

Parameters

ParameterTypeRequiredDescription
querystringYesNatural-language or code search query
modestringNo"hybrid" (default), "semantic", or "lexical"
topKnumberNoMaximum results to return
languagestringNoRestrict results to a language or file type
filePatternstringNoRestrict results to matching file paths

Search Modes

  • Hybrid combines semantic and lexical retrieval and is the best default for most code questions.
  • Semantic is useful for conceptual queries when you know what you want but not the exact symbol name.
  • Lexical is best for exact identifiers, filenames, and tight string matches.

The current server defaults to a lexical-heavy blend with vectorWeight: 0.4, lexicalWeight: 0.6, and reranking enabled.

Response

{
  results: SearchResult[];   // chunk + scores
  query: string;
  totalMatches: number;
  searchTime: number;        // milliseconds
  tokensUsed: number;
  cost: number;
  confidence: number;        // 0-1
  suggestion: "use_results" | "query_unclear" | "no_matches" | "low_confidence";
}

Trust Chain (nella_heartbeat)

nella_search results are wrapped with integrity metadata, and nella_heartbeat lets the agent prove it kept the expected challenge value between tool calls. This is part of Nella’s prompt-injection defense layer rather than a replacement for search.

Practical Notes

  • Run nella_index again after major file changes or branch switches.
  • Use mode: "lexical" when searching for exact symbols or filenames.
  • Use language and filePattern when a broad query returns low-confidence results.