Satori

Give your coding agent a map of the repository before it edits.

Satori turns a repository into a freshness-aware code map. MCP-compatible agents can find behavior by intent, open the real owner, follow nearby relationships, and read only the source needed to act. Offline search uses bundled Potion embeddings, BM25, and LanceDB—no model API key required.

Install

Requirements: Node.js 22.13+, Linux x64 (native Linux or WSL2), and at least 2 GiB of available runtime capacity for the qualified native deployment envelope. The capacity figure is an allowance, not measured steady consumption. The npm package installs the satori command.

npm install -g @zokizuan/satori-cli@latest
satori install
satori doctor

Running satori install (or using --client auto) detects the supported Codex, Claude Code, and OpenCode clients from their documented local markers or CLI executables. Use --client all to force configuration of all three. If no supported client is detected, Satori stops before runtime installation and shows explicit client commands. satori uninstall defaults to all supported clients; use --client auto to limit cleanup to currently detected clients.

Run satori without arguments at any time for human-readable help. Use satori -v to print the installed CLI, MCP runtime, and Core versions.

Codex receives global Satori guidance by default. To also install the optional Codex session-start reminder:

satori install --client codex --install-guidance-hook

Restart your coding agent and tell it:

Index /absolute/path/to/repo with Satori, then find where auth refresh is handled.

That is the complete local path. Satori installs a stable launcher under ~/.satori/; your agent does not download the server again on every startup.

On Linux x64 and WSL2, the default offline Potion + LanceDB runtime uses LateOn D32 as its query-time reranker and is shared behind that launcher. Multiple compatible Codex, Claude Code, OpenCode, or subagent sessions attach as independent MCP sessions to one private local host, shared provider/LanceDB state, and one Potion worker. The host uses a user-only Unix-domain socket, idles out after clients disconnect, and is not used for connected Voyage/Milvus or explicit Ollama runtimes.

To stop every verified Satori MCP runtime under the active state root:

satori terminate

The command shuts down registered servers and their provider workers without removing client configuration, indexes, or installed packages.

Upgrade the installed CLI, MCP runtime, and its compatible Core dependency:

satori upgrade

Satori reports each potentially slow phase as it works:

Checking latest Satori release...
Installing MCP <version> and Core <version>...
Verifying candidate runtime...
Activating verified runtime...

The CLI is updated first. Satori then stages and verifies the exact MCP/Core runtime before switching the stable launcher. If runtime verification fails, the updated CLI remains installed and the managed launcher is left unchanged; correct the reported problem and run satori upgrade again. Restart running coding agents after a successful runtime upgrade. The command does not rewrite client configuration, indexes, hooks, or repository profiles.

An upgrade follows one coordinated release closure declared by the latest CLI package. It does not independently combine the newest CLI, MCP, and Core versions. This keeps every activated runtime on an exact, tested MCP/Core pairing.

For a no-install invocation, replace satori with npx -y @zokizuan/satori-cli@latest.

plain-English question
        |
        v
exact evidence + BM25 + dense retrieval
        |
        v
symbol-owned results
        |
        v
outline, call graph, and bounded source reads

Related MCP server: code-search

What changes for your agent

Satori does not edit source code. It gives the agent better evidence before the edit.

Why Satori

• Find behavior by intent when filenames and exact identifiers are unknown.

• Keep exact paths, symbols, configuration keys, and lexical evidence in the retrieval path.

• Return owner-oriented groups instead of flooding the agent with duplicate chunks.

• Open exact symbols or bounded line ranges instead of dumping entire files.

• Detect source drift and publish complete searchable generations atomically.

• Run fully local retrieval with Potion Code 16M v2 and LanceDB on Linux x64.

• Share the managed offline runtime across compatible local agent sessions instead of starting one heavy runtime per session.

• Install one managed MCP runtime for Codex, Claude Code, OpenCode, or all three.

Measured on Satori

These are repository measurements, not borrowed model-card claims.

Local Potion + LanceDB

A checksum-sealed run on the Satori repository published 488 files and 10,830 chunks with 256-dimensional Potion vectors:

The bundled native feasibility run measured a 36.0 MiB model/helper closure, 104.3 MiB model-related RSS, and 232.404 ms model load. Its short-text microbenchmark reached 19,282 items/s, but that isolated throughput number is not a full indexing claim.

Potion versus Voyage

The same frozen 30 positive retrieval tasks were queried against compatible Potion and Voyage hybrid publications. BM25, exact evidence, fusion, grouping, source projection, and request policy were held constant; only the dense model/publication differed.

Potion is a useful local first stage, not a claim of Voyage parity. The comparison found weaker Java and configuration/runtime retrieval for Potion. The paired latency observations are descriptive rather than a repeated cross-provider performance qualification.

Less context waste

Satori groups retrieval around owners and exposes bounded source instead of making an agent assemble context from repeated broad reads. In a fresh two-task OpenCode comparison, both the Satori and native file-discovery arms produced correct answers:

That exploratory run used 36% fewer tool calls, 21% fewer tool-output bytes, and 46% less wall time. Total model tokens were effectively unchanged, so this is evidence of a shorter evidence route—not a universal token-savings claim. It was one run per task, and OpenCode recovered from two rejected Satori tool calls in the exact-owner task.

The qualification details and limitations remain available in the Potion plan.

Runtime Choices

Connected install:

satori install --client all --runtime voyage
satori doctor

satori doctor prints an applied-runtime table for Codex, Claude Code, and OpenCode. Each row shows whether that client is configured, its effective profile, embedding provider/model/dimension, reranker, vector store, and whether the values come from the managed launcher or client config. Credentials and local artifact paths are never included in the table. This also works when the managed launcher temporarily points at a local repository build; doctor keeps the outside-managed-store warning while reporting the profile the launcher actually applies.

Existing Milvus deployments can select --vector-store milvus. Existing Ollama installations can select or retain an explicit model:

satori install --client all --runtime offline --ollama-model nomic-embed-text

Changing the embedding provider, model, dimensions, vector backend, or persisted projection changes index compatibility and requires a reindex. Satori never silently converts or deletes the previous backend's publication.

Test the repository runtime locally

From a Satori checkout, the development installer builds the local Core, MCP, and CLI packages, preflights the MCP runtime, updates the selected clients, and points the stable launcher at this checkout. It does not install or replace the globally published CLI.

pnpm dev:install-local-mcp -- --client opencode --runtime offline --reranker lateon

That exact command selects OpenCode, local Potion embeddings, LanceDB, and the LateOn reranker. Restart OpenCode after changing the launcher.

Useful local combinations:

# Offline Potion + LanceDB + LateOn
pnpm dev:install-local-mcp -- --client opencode --runtime offline --reranker lateon

# Offline Potion + LanceDB without neural reranking
pnpm dev:install-local-mcp -- --client opencode --runtime offline --reranker none

# Offline Ollama + LanceDB
pnpm dev:install-local-mcp -- --client opencode --runtime offline --ollama-model nomic-embed-text --reranker none

# Connected Voyage + LanceDB or Milvus
pnpm dev:install-local-mcp -- --client opencode --runtime voyage --vector-store lancedb
pnpm dev:install-local-mcp -- --client opencode --runtime voyage --vector-store milvus

To stop testing the checkout and restore OpenCode to the current published runtime, run the published installer again. The explicit form below also restores the same offline Potion + LateOn selection used in the first example:

npx -y @zokizuan/satori-cli@latest install --client opencode --runtime offline --reranker lateon
npx -y @zokizuan/satori-cli@latest doctor

If the latest CLI is already installed globally, the equivalent first command is satori install --client opencode --runtime offline --reranker lateon. Restart OpenCode after restoring the published runtime.

MCP Tools

Public paths are absolute. read_file is restricted to tracked searchable roots; it is not a general host-filesystem reader.

Recommended Agent Workflow

1. search_codebase for behavior or ownership
2. follow recommendedNextAction when returned
3. use file_outline to inspect one file's owners
4. use call_graph for advisory relationship context
5. use read_file for exact proof
6. use continue_search only when the frozen result has more useful evidence

If a tool returns requires_reindex, reindex before retrying the original call. Use sync for ordinary source changes. A search that arrives during a transient same-root sync joins it once and proceeds when it completes; other in-flight indexing returns not_ready with retryAfterMs and the active indexing operation so drivers can retry deterministically. For grouped pagination, limit bounds the frozen result set across every page and disclosureLimit controls only the initial page: limit=20, disclosureLimit=6 returns up to six initially and freezes up to twenty. Search continuation "complete" means complete for that caller-bounded frozen set, never for the full available pool; omittedBeyondLimitGroupCount reports groups excluded by limit. Treat inbound call-graph results as leads to verify, not compiler-grade blast-radius proof.

Index Profiles

Install with --profile default|minimal|all-text to write repository policy to satori.toml:

[index]
profile = "minimal"

Every profile honors .satoriignore, .gitignore, and the hard denylist for secrets, dependencies, generated output, lockfiles, binaries, logs, databases, bundles, source maps, and snapshots. Profiles control what is indexed; search_codebase still defaults to implementation-first scope="runtime".

Configuration

The installer owns the launcher and non-secret runtime identity. Provider credentials remain in the MCP client's environment.

Common variables:

SATORI_RUNTIME_PROFILE
VECTOR_STORE_PROVIDER
LANCEDB_PATH
EMBEDDING_PROVIDER
EMBEDDING_MODEL
EMBEDDING_OUTPUT_DIMENSION
VOYAGEAI_API_KEY
SATORI_RERANKER_PROVIDER
SATORI_LATEON_MODEL_PATH
SATORI_LATEON_PROFILE
SATORI_LATEON_REQUEST_DEADLINE_MS
SATORI_LATEON_MAX_QUEUE_WAIT_MS
SATORI_LATEON_RERANKER_STAGE_DEADLINE_MS
SATORI_LATEON_MAX_ACTIVE_RERANKS
SATORI_LATEON_MAX_QUEUED_RERANKS
SATORI_LATEON_INTRA_OP_THREADS
MILVUS_ADDRESS
MILVUS_TOKEN

Run doctor after changing runtime configuration. Restart every Satori MCP client before mutating an index under a new provider, model, backend, dimension, or package version; incompatible live runtime owners are blocked instead of racing one publication. Mutation ownership is scoped to the backend authority root: each LanceDB state root carries its own owner registry, and Milvus runtimes are keyed by endpoint, so isolated state roots do not block one another.

How Publication Works

Satori keeps source-derived navigation separate from model-specific vectors. A completed publication binds vector and lexical state, navigation, relationship evidence, source observation, checkpoint, and receipt to one generation. Readers use the complete previous generation or the complete new generation; failed candidate work does not replace the active publication.

Incremental synchronization scans for changed files, embeds changed chunks only, updates per-file navigation and graph contributions, and activates the complete replacement generation. Missing, corrupt, stale, or incompatible authority fails closed to repair or reindex guidance.

Repair is intentionally narrow. A fully proven healthy V4 publication is an exact no-op; navigation-only damage on an otherwise valid V4 publication uses the existing graph-only activation path. V3, missing, corrupt, changed, or ambiguous source authority requires a reindex instead of fabricating a compatible publication.

Offline Local Reranking

Offline install defaults to reranking eligible candidates with the Apache-2.0 lightonai/LateOn-Code-edge FP32 ONNX checkpoint at projection-v4 depth 32. D32 is operationally qualified but not held-out qualified; it became the managed offline default through an explicit owner activation decision scoped to Linux x64/WSL2 managed offline installations. Model weights are not bundled in each versioned MCP runtime. The CLI downloads the roughly 72 MB pinned closure once into ~/.satori/models/, verifies every artifact, and reuses it across upgrades. satori upgrade migrates previous managed combinations (context-v3 activated profile or the historical v3 rollout) to the context-v4 default atomically. Disable neural reranking explicitly with:

satori install --runtime offline --reranker none

--reranker none is the explicit opt-out: it keeps the selected embedding provider plus baseline ordering (exact + BM25 + single vector). With Ollama embeddings that is the Ollama model plus baseline ordering, not "Potion + BM25". The runtime also falls back to that baseline automatically on any LateOn failure; automatic failure fallback and explicit opt-out are different concepts.

Direct MCP runtimes can select the same reranker with:

SATORI_RERANKER_PROVIDER=lateon
SATORI_LATEON_MODEL_PATH=/absolute/path/to/LateOn-Code-edge

The default profile is:

SATORI_LATEON_PROFILE=lateon_offline_quality_projection_v4_d32_v1
SATORI_LATEON_ACTIVATION_POLICY=lateon_context_v4_d32_owner_default_v1

Explicit D16, projection-v2, and projection-v3 D32 choices remain available for compatible developer configurations (the v3 activated combination is admitted and migrated to the v4 default by satori upgrade):

SATORI_LATEON_PROFILE=lateon_projection_v1_d16_legacy
SATORI_LATEON_PROFILE=lateon_projection_v2_d16_v1
SATORI_LATEON_PROFILE=lateon_offline_quality_projection_v2_d32_v2

D16 and D32 are distinct identity-bearing profiles. Satori never switches between them automatically; an unavailable, overloaded, timed-out, cancelled, or invalid neural run restores the deterministic baseline order.

Projection-v4 rerank context sends the exact question once plus a positive-only answer-type line (the implementation focus never names competing artifact classes), and each projected document is a bounded answer packet: factual candidate_role derived from path classification plus trusted structural context (direct callers, callees, and supporting tests resolved to exact instance identities in the same sealed navigation generation; sorted and capped; never a preference value). The reranker's published order remains final: Satori applies no ranking weights, score multipliers, or global test/documentation penalties. When only some candidates project, Satori reranks the projectable ones, keeps the failed candidate in its retrieval slot, and reports RERANKER_INPUT_DEGRADED; when none project, it skips the provider, preserves retrieval order, and reports RERANKER_SKIPPED_INPUT instead of RERANKER_FAILED.

The runtime verifies the pinned revision's artifact digests before use, performs ONNX inference in a killable child process, and preserves the complete deterministic baseline when model loading, scoring, validation, or the request deadline fails. Projection profiles freeze model, projection, depth, thread, and batching behavior. Operators may only reduce their request deadline, queue wait, reranker-stage deadline, or active/queued capacity using the corresponding variables listed above; deadlines are never increased. A terminal rerank execution reports qualified diagnostics — attempts, retries, timeouts, the effective deadline, observed wall time, and deadline lateness — alongside the frozen retrieval order. The resulting effective profile remains part of the shared-runtime and frozen-result identity.

LateOn is query-time ranking evidence only. It does not control candidate eligibility, source freshness, publication authority, or baseline search availability.

Search result score fields retain bounded retrieval evidence for diagnostics and compatibility; they are not the final relevance order. Consumers should preserve the returned sequence, or request includeResultIndex when they need an explicit authoritative rank.

Language Support

Search and bounded reads work across the indexed text and language catalog. Rich symbol navigation depends on parser evidence. TypeScript, JavaScript, and Python currently have the strongest call-graph support; other supported languages may provide symbols without authoritative graph traversal. Inspect manage_index status instead of assuming every indexed language is graph-ready.

Python inbound relationships are qualified for bounded static patterns, including absolute-import constructor receivers and direct service or callback value-origin flow. Reflection, arbitrary factories, collections, monkeypatching, unbounded aliases, and ambiguous environments remain outside that model. Individual edges may be exact under the supported model, but the inbound result set remains non-exhaustive and absence still requires deterministic verification.

Structural definition coverage is intentionally language-specific:

.c and .h files currently use the C++ parser for a proven common-C subset; Satori does not claim a native C parser. Definition coverage improves outline, exact-open, and ownership navigation. It does not by itself imply call-graph or type-resolution support.

Privacy and Limits

• Offline Potion embedding, LanceDB storage, search, and runtime telemetry make no network requests after installation.

• Connected providers receive the projected embedding or reranking input required for their service.

• Satori does not edit repository source.

• Local diagnostics exclude source, queries, paths, symbols, and repository identifiers and are never uploaded by Satori.

• Native Windows and macOS are not supported in this release. On Windows, run Satori inside WSL2.

• The relationship graph is conservative navigation evidence, not a full static-analysis proof.

• At revision 4138b1e…, fresh-process startup measured 645.95 ms p50, after which the first call_graph measured 7,204.25 ms p50 and 7,530.10 ms p95. Calls measured after two preparation calls were 11.97 ms p50 and 13.57 ms p95. The cold owners were checkpoint/completion validation and relationship loading/validation; adjacency construction was only about 21 ms.

• The six-publication memory experiment at that revision peaked at 881.82 MiB RSS and established memory_retained_capacity_bounded, not a proven plateau or multi-day guarantee. The separate 2 GiB deployment allowance comes from earlier integration evidence that observed a 1,447.21 MiB incremental publication peak.

• Those cold and memory measurements were not rerun after the current master's full-reindex V4 authority-publication change. They are retained release characterization, not strict proof of identical current-master performance.

Packages

Development

pnpm install
pnpm build
pnpm run check

Focused package tests:

pnpm --filter @zokizuan/satori-core test
pnpm --filter @zokizuan/satori-mcp test
pnpm --filter @zokizuan/satori-cli test

See CONTRIBUTING.md for repository conventions, docs/RELEASING.md for coordinated package releases, SECURITY.md for private vulnerability reporting, and THIRD_PARTY.md for attribution.

License

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

Satori is open-source software available 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 for organizations that require different licensing terms. See COMMERCIAL-LICENSING.md.