Zorya Search

Repository code search and retrieval for SDK and MCP clients, with optional code embeddings, semantic search, and reranking.

Читать по-русски

Zorya Search gives an existing app or agent a fast way to search an approved repository, inspect the current source behind a result, and gather related evidence. Use the SDK from a Node.js service or expose the same capabilities to a client through MCP. Search returns bounded source-backed results; the caller decides when to search, what to trust, and what to do next.

It is useful for questions such as “where is this initiative trigger handled?”, checking callers and tests around a known symbol, or finding repeated code bodies worth reviewing. It can also find and read public web sources when the owner enables web access. It does not replace the agent, edit files, or automatically repair a project.

What it can do

The default code path is lexical and makes no model-provider call. Optional code embeddings and reranking use the code-specialized voyageai/voyage-code-4 and voyageai/rerank-2.5-lite preset. Web search and web text models are configured separately. MCP exposes tools to a client; it does not impose a workflow or make Search autonomous.

Related MCP server: code-rag-mcp

Install the available release

Node.js >=20.19.0 is required. The currently available artifact is the GitHub release archive v0.1.6:

npm install --save-exact https://github.com/zoomplus/zorya-search/releases/download/v0.1.6/zorya-search-0.1.6.tgz
npm exec -- zorya-search setup --root .
npm exec -- zorya-search client-config

client-config prints connection examples; you register one with your chosen client, grant only the required access, and start indexing explicitly with npm exec -- zorya-search index. Installation alone does not connect a client or start indexing. See the English quickstart or Russian quickstart.

SDK example

This runnable example uses the public v0.1.6 SDK, lexical search, current-source verification, and duplicate candidates. Install the archive above and save this as search.mjs in that Node.js project:

import { isAbsolute, relative, resolve, sep } from 'node:path'
import { openEmbeddedDatabase } from '@zorya/search'
import { createCodeIndex } from '@zorya/search/code'

const rootInput = process.env.ZORYA_SEARCH_ROOT
const dataInput = process.env.ZORYA_SEARCH_DATA_DIR
if (!rootInput || !dataInput || !isAbsolute(rootInput) || !isAbsolute(dataInput)) {
  throw new Error('Set absolute ZORYA_SEARCH_ROOT and ZORYA_SEARCH_DATA_DIR paths')
}

const root = resolve(rootInput)
const dataDir = resolve(dataInput)
const dataFromRoot = relative(root, dataDir)
if (dataFromRoot === '' || (!dataFromRoot.startsWith(`..${sep}`) && dataFromRoot !== '..' && !isAbsolute(dataFromRoot))) {
  throw new Error('ZORYA_SEARCH_DATA_DIR must be outside the indexed repository')
}

const database = await openEmbeddedDatabase(dataDir)
const index = createCodeIndex({ database })
try {
  await index.indexRepository({ root })
  const result = await index.searchCode({
    root,
    query: 'initiative trigger',
    mode: 'lexical',
    limit: 5,
  })
  const hit = result.hits[0]
  const source = hit
    ? await index.readSource({
        root,
        path: hit.path,
        lineStart: hit.lineStart,
        lineEnd: hit.lineEnd,
        snapshotId: hit.snapshotId,
      })
    : undefined
  const duplicates = await index.findCodeDuplicates?.({ root, limit: 5 })
  console.log({ hits: result.hits, source: source?.text, duplicates: duplicates?.groups })
} finally {
  try {
    await index.close()
  } finally {
    await database.close()
  }
}

Run it with absolute paths; keep the database outside the repository:

ZORYA_SEARCH_ROOT=/absolute/path/to/repository \
ZORYA_SEARCH_DATA_DIR=/absolute/path/to/private/search-data \
node search.mjs

The sample is read-only with respect to source files and does not call an embedding provider. Index creation and database use are explicit. The caller can inspect duplicate groups and decide whether any are worth reviewing; Search does not merge or change them. It uses the default index limits; for a large repository, set suitable validated limits for your project as described in the CLI guide or SDK reference.

Which version has which features?

The GitHub archive v0.1.6 includes code search/source reading/context, duplicate candidates, indexing/status, and optional web and classification capabilities. Current main adds exact symbol/reference queries, bounded static call tracing, and includeLogical for getCodeContext / get_code_context. includeLogical is off by default and independent of includeRelated; its coverage and omissions are explicit, and it does not claim complete runtime calls or dynamic dispatch. These additions are source-only and are not in archive v0.1.6.

Current indexing supports Markdown .md/.mdx and selected source/config formats, but not editor rule files .mdc or plain .txt. A separate embedding feature for repository documentation, rules, and skills has been requested and is not implemented. See the capability guide for details.

Guides

• Getting started (English) · Начало работы (русский)

• Capabilities and version boundaries (Russian)

• SDK reference (Russian)

• MCP, local service, and remote OAuth (Russian)

• CLI setup and operation (Russian)

• Connect agent clients (Russian)

• Architecture (Russian)

• Changelog

• Code retrieval skill (Russian)

• Web-source retrieval skill (Russian)

• Contributing · Security

Project status

The source and package checks passed for the current main snapshot, including the full CI matrix. That verifies the tested source/package scope; it does not claim hosted ChatGPT, user-device/game, provider-quality, or full-program acceptance. The public GitHub artifact remains v0.1.6; npm publication has not happened. Use Search when its repository index, current-source identity, or configured retrieval capabilities help. Ordinary search and file-reading tools may be all a task needs.

MIT License. See LICENSE.