@satori-code/core

The indexing, language-analysis, Publication, and hybrid-retrieval engine behind Satori.

Most coding-agent installations should use @satori-code/cli and @satori-code/mcp. Install Core directly when embedding Satori's lower-level analysis, indexing, storage, or retrieval APIs in another Node.js application.

What Core Owns

• repository discovery, ignore policy, source observation, and incremental synchronization;
• Oxc, Tree-sitter-WASM, and the CBM semantic engine (WebAssembly) for language analysis;
• structural chunks, symbols, navigation, and conservative relationship evidence;
• Potion, VoyageAI, OpenAI, Gemini, and Ollama embeddings;
• dense and BM25 hybrid retrieval;
• LanceDB and Milvus/Zilliz storage adapters; and
• atomic publication identity, compatibility, checkpoint, and receipt state.

Files remain the source of truth. Navigation and graph data are derived source evidence; vectors are model-specific derived state. Provider, model, dimensions, inference contract, projection, and schema participate in persisted compatibility.

Retrieval and Storage

Core supports Potion, VoyageAI, OpenAI, Gemini, and Ollama embeddings; LanceDB and Milvus/Zilliz storage; and dense + BM25 hybrid retrieval. The managed offline distribution uses Potion Code 16M v2 with 256-dimensional vectors, while the connected reference path uses Voyage Code 3.

The persistence model separates source-derived lexical/navigation state from model-specific vectors. That boundary preserves a complete exact + BM25 + single-vector baseline when an optional reranker is disabled, unavailable, or over deadline. The managed MCP/CLI distribution can apply local LateOn reranking at query time on the qualified offline path without making that reranker part of Core's persisted search authority.

Install

npm install @satori-code/core

Node.js 22.13 or newer is required. Provider and storage requirements depend on the adapters selected by the host application.

Repository Policy

Core reads the same repository-local satori.toml used by the MCP distribution:

[index]
profile = "minimal"

The file controls index breadth only. Credentials, provider models, dimensions, and backend endpoints belong in runtime configuration. As a policy-authority file, satori.toml must be a regular file at the repository root; symbolic links are rejected fail-closed.

Development

pnpm --filter @satori-code/core build
pnpm --filter @satori-code/core typecheck
pnpm --filter @satori-code/core test

License

Copyright (c) 2026 Hamza (@ham-zax)

Satori is licensed under the GNU Affero General Public License v3.0 only (AGPL-3.0-only). See LICENSE.

Alternative commercial licensing terms are available separately from the copyright holder.