Satori

Understand any codebase before you touch it.

Satori turns a repository into a local intelligence database that coding agents can search, navigate, and interrogate. It combines semantic retrieval, exact lexical evidence, symbol ownership, parser-derived structure, conservative code relationships, exact source spans, and source freshness—then exposes that intelligence through MCP to Codex, Claude Code, OpenCode, and other compatible harnesses.

The default managed runtime is local: Potion embeddings + BM25 + LateOn reranking + LanceDB on Linux x64 / WSL2. No model API key is required for the offline path after installation.

Repository
   |
   v
semantic + lexical evidence
   + symbols + structure
   + supported relationships
   + source freshness
   |
   v
Ask -> locate owner -> trace -> read exact source

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

30-second example

You open an unfamiliar repository and ask:

Where is refresh-token rotation implemented, what owns it,
and what exact code should I inspect before changing it?

Instead of repeatedly guessing filenames and dumping large files, an agent can use Satori to:

1. search by intent and exact evidence;

2. resolve relevant matches to owning symbols;

3. inspect the structure of the owning file;

4. follow supported callers/callees when useful;

5. read the exact symbol or bounded source span;

6. see whether that evidence is current, stale, or under maintenance.

That evidence funnel is the product.

Related MCP server: code-search

What can you ask Satori?

Where is authentication refresh handled?

What owns index publication?

Find the code responsible for automatic reindexing.

Where does this user-facing error originate?

Which code handles this configuration setting?

Show me the structure of this file without dumping the whole file.

What directly calls this symbol?

What code should I inspect before changing this subsystem?

You do not need to know the correct filename or identifier before you start.

What Satori knows about a repository

A Satori Publication is an immutable snapshot of everything Satori knows about one coherent repository generation. That knowledge includes:

Why developers use it

• Learn unfamiliar codebases. Ask where behavior lives before learning the repository tree by hand.

• Investigate bugs. Move from a symptom or error string to the owning implementation and related evidence.

• Plan refactors. Inspect the owner, nearby structure, exact source, and supported relationships before the first change.

• Reduce context waste. Prefer symbol-sized evidence and bounded source over broad repository/file dumps.

• Help smaller/local models. Spend scarce context on the code that matters rather than on discovery.

• Give multiple agents one code map. Compatible local sessions can share the managed runtime and repository intelligence.

• Keep the map current. Ordinary edits converge through sync; managed offline rebuild-safe incompatibilities can reindex automatically instead of making the user babysit the index.

Features

Hybrid repository search

Semantic retrieval finds concepts; BM25 and exact evidence keep literal code facts precise. Owner-oriented grouping reduces duplicate chunk noise.

Code map and exact source

TypeScript, JavaScript, Python, Go, Java, C#, C++, Rust, and Scala have production symbol navigation plus the current qualified CALLS v0 slice. file_outline exposes structure; read_file opens an exact indexed symbol or bounded source range.

Conservative relationship navigation

Satori prefers missing evidence over invented certainty. Call-graph results are navigation leads, not compiler-grade whole-program blast-radius proof.

Freshness and self-maintenance

Satori tracks repository source checkpoints, prepares replacement Publications atomically, and distinguishes fresh, changed, unverified, indexing, and rebuild-required states. On the managed offline path, rebuild-safe incompatibilities can automatically start or join one background reindex. Connected/remote and failed/unsafe recovery remains explicit.

Local-first runtime

The default Linux x64 / WSL2 path runs Potion embeddings, BM25, LateOn reranking, and LanceDB locally. Connected Voyage and Milvus/Zilliz remain optional advanced configurations.

Shared managed runtime

Compatible Codex, Claude Code, OpenCode, and subagent sessions can attach to one private local Satori host instead of starting one heavy provider/index stack per session.

Documentation

• docs/PRODUCT_GUIDE.md — how to think about Satori and use it for repository learning, debugging, refactors, local models, and multi-agent work.

• docs/README.md — documentation map and current-vs-historical guidance.

• satori-landing/docs/index.html — complete operational setup, tool, lifecycle, and troubleshooting reference.

• satori-landing/architecture.html — Publication, retrieval, navigation, freshness, and runtime architecture.

• docs/architecture/LANGUAGE_INTELLIGENCE.md — language backends and relationship capability boundaries.

• docs/RELEASING.md — release qualification and publication workflow.

Dated files under docs/plans/, docs/research/, docs/remediation/, and docs/superpowers/ are engineering history unless a current document explicitly points to them as an active contract.

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 recommended first run needs no global install:

npx -y @zokizuan/satori-cli@latest install
npx -y @zokizuan/satori-cli@latest doctor

For a persistent satori command, install the lightweight CLI globally and use the same flow without the npx prefix:

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

install auto-detects supported Codex, Claude Code, and OpenCode clients from their documented local markers or CLI executables. --client auto is the explicit equivalent; 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 update is an exact alias for satori upgrade. If you do not keep the CLI installed globally, run the same release flow through the latest CLI:

npx -y @zokizuan/satori-cli@latest 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 other no-install commands, replace satori with npx -y @zokizuan/satori-cli@latest.

First five minutes

1. Create the repository intelligence database

The first index is explicit: Satori will not silently decide to ingest an arbitrary workspace. Tell your coding agent:

Index /absolute/path/to/repo with Satori.

Full creation runs in the background. Once the Publication is ready, the repository has a durable intelligence layer the agent can query.

2. Ask for behavior, not filenames

Use Satori to find where auth refresh is handled,
identify the owner, and show me the exact implementation to inspect first.

3. Follow the evidence funnel

search_codebase
    -> owner-oriented result
    -> file_outline / call_graph when useful
    -> read_file for exact proof
    -> continue_search only if the frozen result has more useful evidence

You normally do not need to orchestrate these tools manually. They are the seven MCP primitives your coding agent uses to interrogate the repository database.

How Satori changes the workflow

Where it earns its keep

Unfamiliar codebases

Use Satori as the first map. Ask what owns a behavior, inspect the file structure, then open the implementation rather than browsing the tree at random.

Bug investigation

Start from a symptom, error string, or behavior description and move toward the owning source. Use supported relationships as leads, not as a substitute for compiler/test/runtime proof.

Refactor and feature planning

Find the owner and exact source before proposing a change. Inspect nearby symbols and qualified call evidence when they materially affect scope.

Smaller and local models

Use a strict retrieval funnel—search, owner, outline, exact span—so limited context is spent on implementation rather than repository discovery.

Multi-agent work

Compatible local sessions can share the managed runtime and current repository intelligence while keeping their MCP sessions independent.

The index maintains itself where it safely can

Satori distinguishes ordinary source drift from states that need a full rebuild:

• ordinary edits: incremental sync prepares a replacement Publication;

• compatible completed Publication + sync running: reads can continue from the proven generation with freshness metadata;

• managed offline rebuild-safe incompatibility: Satori automatically starts or joins one background reindex and returns deterministic not_ready / indexing state for retry;

• connected/remote, unsafe, or failed automatic recovery: explicit manage_index reindex remains the operator override;

• clear: always explicit.

This keeps routine local reindex maintenance out of the user's way without hiding cases where a rebuild can have operational or provider-cost consequences.

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.

Token-efficient retrieval

Satori groups retrieval around owners and exposes bounded source instead of making an agent assemble context from repeated broad reads. The product is designed to cut repository-discovery token waste dramatically by routing exact symbols and compact source windows instead of whole-file dumps.

A fresh two-task OpenCode comparison also reached the correct answers through a shorter evidence route. The detailed exploratory artifact retains the raw tool, context, and token accounting; this public page deliberately does not turn one small run into a universal token-reduction percentage.

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

When a tracked Publication becomes incompatible with a managed offline runtime, Satori automatically starts or joins one background reindex and returns not_ready/indexing so the caller can retry without asking the user to repair the index. Explicit manage_index reindex remains the recovery override when automatic maintenance is unavailable, suppressed after a failed automatic attempt, or intentionally disabled for connected/remote providers. Use sync for ordinary source changes when refreshed indexed evidence is needed. Search and navigation do not wait for a same-root sync: when a compatible completed Publication exists, they continue from that pinned generation with stale/unverified provenance and pending-sync metadata. Create/reindex operations that do not expose a readable generation still return not_ready with the active 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_ACTIVATION_POLICY
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 stores each index generation as one immutable Publication. A complete Publication owns the vector collection, navigation, selection policy and format identity, and source checkpoint for that generation. Readers pin one Publication for the lifetime of a request; activation makes a complete replacement Publication current, while failed candidate work leaves the active Publication unchanged.

Incremental synchronization scans for source changes, embeds changed chunks only, updates navigation and relationship evidence, and activates the complete replacement Publication. Ordinary source divergence converges through sync. Managed offline runtimes automatically rebuild a tracked Publication when the current format/runtime identity or runtime policy requires a full reindex; corrupt or unsupported authority still fails closed for explicit operator recovery. Satori does not expose a repair command or salvage retired authority formats into the current Publication model.

Offline Local Reranking

Offline install defaults to reranking eligible candidates with the Apache-2.0 lightonai/LateOn-Code-edge FP32 ONNX checkpoint under the managed v5 D32 profile. Its semantic rerank projection remains projection-v4; v5 pins the model, artifacts, projection, candidate depth, and sequential CPU execution semantics without encoding machine-speed assumptions such as queue wait, scoring latency, or a fixed CPU thread count. 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 LateOn combinations to the v5 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 current managed profile is:

SATORI_LATEON_PROFILE=lateon_offline_quality_projection_v5_d32_v1
SATORI_LATEON_ACTIVATION_POLICY=lateon_context_v5_d32_owner_default_v1

Older LateOn profile IDs are recognized only for migration guidance and cannot execute. satori upgrade migrates managed installations to v5. One local LateOn worker serves overlapping searches through a FIFO queue instead of falling back merely because another search is already reranking. Cancellation, a genuine worker/output failure, or the hard safety ceiling restores the frozen baseline retrieval order for that request.

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, Python, Go, Java, C#, C++, Rust, and Scala expose production CALLS v0 when the current Publication has compatible relationship navigation. Resolved test-reference navigation remains limited to the languages whose test-reference capability is separately qualified, including TypeScript, JavaScript, Python, and Go. Python and Go additionally expose on-demand file_outline(detail="analysis") structural metrics for exact functions and methods. TypeScript, JavaScript, and Scala use Satori's syntax/name-based advisory resolver; Scala v1 admits only direct non-member calls with a unique indexed target, while member/dynamic dispatch remains outside the claim. The CBM-backed languages use conservative direct-call slices: Go excludes receiver/type, embedded/interface dispatch, callbacks/callable aliases, and unknown strategies; Java and C# admit exact static bindings only within the same detected build root (Maven/Gradle or .csproj), falling back to the same source directory when no manifest establishes broader authority, and exclude receiver dispatch; C++ currently admits exact same-translation-unit direct calls and rejects unproved cross-translation-unit or conditional-preprocessor cases; Rust requires Cargo package ownership and rejects receiver dispatch plus unmodeled cfg-dependent sources. 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 or independent C type system. CALLS v0 for that routed subset is limited to exact same-translation-unit direct bindings that survive the C++ semantic gate.

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.