Elyra's @elyracode/semantic-index — local semantic code search

grep is great until it isn't. It finds text, not meaning. Search for "authentication" and you miss the file that calls it "login flow." Search for "retry" and you miss the exponential-backoff loop that never uses the word. In a large or unfamiliar codebase, the thing you're looking for is often named something you wouldn't guess.

Semantic search fixes this: find code by what it does, not what it's called. The new @elyracode/semantic-index extension brings it to Elyra — and, true to Elyra's character, it can run entirely on your own machine.

How it works

Two tools. First, build the index:

semantic_index_build

This walks your tracked source files (via git ls-files, so it respects .gitignore and skips node_modules), splits each into overlapping chunks, embeds them, and stores the vectors locally:

for (let i = 0; i < chunks.length; i += BATCH) {
    const batch = chunks.slice(i, i + BATCH);
    const vectors = await embed(config, batch.map((c) => c.text));
    // ... store { file, startLine, endLine, text, vector } ...
}
// saved to .elyra/semantic-index.json

Then search by meaning:

> Where do we handle session timeout?

  Calling semantic_search({ query: "session timeout handling" })

  Top 8 matches:
  ── src/auth/session.ts:40-79  (score 0.834)
  ── src/middleware/expiry.ts:12-48  (score 0.791)
  ...

Under the hood it embeds your query and ranks every stored chunk by cosine similarity:

const scored = index.chunks
    .map((chunk) => ({ chunk, score: cosineSimilarity(queryVector, chunk.vector) }))
    .sort((a, b) => b.score - a.score)
    .slice(0, limit);

The match on expiry.ts — which might never contain the word "timeout" — is exactly what grep would have missed.

The part that's actually different: it stays on your machine

Semantic code search isn't new. What's different here is where the data goes.

The embeddings endpoint is configurable. Point it at OpenAI if you want, but you don't have to:

export ELYRA_EMBED_BASE_URL=http://localhost:11434/v1   # Ollama
export ELYRA_EMBED_MODEL=nomic-embed-text

With that one change, your entire codebase is indexed by a model running on your own laptop. Nothing — not a single chunk of your source — leaves the machine. The index file lives at .elyra/semantic-index.json, local and yours.

For a freelancer working on a client's proprietary code, or a team under a strict data-handling policy, that's the difference between "can't use it" and "ship it." Most hosted semantic-search tools require sending your code to their servers. This one asks where you want the embeddings to come from, and local is a first-class answer.

How the agent uses it

With the index built, the agent reaches for semantic_search when it needs to find something conceptual, and grep when it needs an exact symbol. The two complement each other: grep for "where is validateToken defined," semantic search for "where do we deal with expired credentials."

The skill that ships with the extension teaches the agent exactly this division of labor, so it picks the right tool for the question.

The honest limitations

This is an MVP, and I'd rather you know its edges:

• Re-indexing is full, not incremental. After big changes, you rebuild from scratch. (Incremental updates are the obvious next step.)

• Search is a linear scan. Fine for thousands of chunks; you'd want a real vector store at hundreds of thousands.

• The index is JSON. Simple and inspectable, but not the most compact format for large repos.

None of these stop it from being genuinely useful today — and the design leaves room to grow without changing how you use it.

Why it matters

An agent that can only find code by keyword is an agent that misses things — and acts on incomplete context. Semantic search lets it find the relevant code, named whatever it happens to be named, before it makes a change.

And doing it locally means you don't have to choose between that capability and keeping your code private. With Elyra, you get both.

elyra install npm:@elyracode/semantic-index