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 --client all
satori doctor

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 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: codesurface

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

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.

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. 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
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.

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.

Future Local Reranking

The current offline product is intentionally simple: exact evidence + BM25 + Potion retrieval, followed by Satori grouping and disclosure. It does not ship a local neural reranker today.

Candidate identity and provenance are kept separate from primary publication authority so a future local second stage can score a complete bounded candidate set and fall back entirely to the existing ordering on failure. Optional LateOn/NextPLAID-style state remains future work; it will never control source freshness or baseline search availability.

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

MIT