Learn the product first · reference it second

Satori Docs

Satori is a local repository-intelligence database for developers and coding agents. Start with what it helps you understand, create one repository Publication, ask a real code question, then use the deeper tool and lifecycle reference only when you need it.

Default managed path Potion + BM25 + LateOn + LanceDB · Linux x64 / WSL2 · no model API key after install
Five-minute path

Install once. Index one repo. Ask one useful question.

You do not need to learn the seven MCP tools before Satori becomes useful. The normal experience is an agent using those tools for you while you stay focused on the repository question.

1 · INSTALL 
npx -y @zokizuan/satori-cli@latest install
npx -y @zokizuan/satori-cli@latest doctor

Restart the supported MCP client after installation.

2 · INDEX Index /absolute/path/to/repo with Satori.

The first Publication is explicit. Satori does not silently ingest arbitrary workspaces.

3 · ASK
Where is auth refresh handled, what owns it, and what exact implementation should I inspect first?

Ask by behavior when you do not know the filename or symbol yet.

4 · VERIFY search → owner → outline / calls → exact source

Follow bounded evidence rather than opening large files by default.

Mental model

Repository intelligence, bound to one coherent generation.

A Publication is Satori's immutable snapshot of everything it knows about one repository generation. Search, symbols, structure, supported relationships, source checkpoints, and index policy are meant to agree about that same state.

Semanticbehavior by meaning
LexicalBM25 + exact identifiers
Ownerssymbols + structural spans
Relationsqualified navigation evidence
Freshnesssource + runtime compatibility
Sourceexact symbol or bounded lines

Satori is not a code editor, a generic chat-memory service, or a compiler-complete dependency oracle. It is the repository intelligence layer an agent consults before and during implementation work.

Install the MCP Server

Satori runs as an MCP server, so a compatible coding harness gains the repository-intelligence layer without implementing its own parser, symbol index, retrieval stack, freshness model, or call-navigation surface. The CLI installs the managed runtime and client configuration.

Recommended public setup: npx -y @zokizuan/satori-cli@latest install, then npx -y @zokizuan/satori-cli@latest doctor. No global install is required. The installer auto-detects supported clients; use --client all only to force all three. Restart the MCP client after install.

Codex

npx -y @zokizuan/satori-cli@latest install --client codex

Writes the Satori MCP entry to ~/.codex/config.toml and a managed guidance block to ~/.codex/AGENTS.md. Add --install-guidance-hook only when you also want an opt-in session reminder in ~/.codex/hooks.json.

Claude

npx -y @zokizuan/satori-cli@latest install --client claude

Writes the Satori MCP entry to ~/.claude.json.

OpenCode

npx -y @zokizuan/satori-cli@latest install --client opencode

Writes the Satori MCP entry to ~/.config/opencode/opencode.json and a managed guidance block to ~/.config/opencode/AGENTS.md.

Use --client all to install every supported client, and uninstall with the same selector to remove only Satori-managed config and guidance. Run npx -y @zokizuan/satori-cli@latest doctor to check every supported client's applied runtime without starting an MCP client. The table shows configuration status, profile, embedding provider/model/dimension, reranker, vector store, and whether the values come from the managed launcher or client config. It never prints credentials or local artifact paths. Repository-backed development launchers retain the outside-managed-store warning while still reporting the profile they actually apply.

Test a Repository Build, Then Restore the Published Runtime

From a Satori checkout, the development installer builds and preflights the local Core, MCP, and CLI, then points the stable launcher at that checkout. It does not replace a globally installed published CLI. 

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

This selects OpenCode, Potion embeddings, LanceDB, and LateOn. Supported development options are:

  • --client opencode|codex|claude|all (default: opencode).
  • --runtime offline|voyage; omission preserves the managed selection, or starts offline when no launcher exists.
  • --reranker lateon|none, available only with the offline runtime.
  • --ollama-model <id> to select Ollama instead of Potion for offline embeddings.
  • --vector-store lancedb|milvus; offline requires LanceDB and Milvus requires Voyage.
  • --no-build, --home <path>, and --node <path> for existing-build or isolated testing.

Restore OpenCode to the published runtime with:

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

Restart OpenCode after either switch. If the latest CLI is already installed globally, the equivalent restore command starts with satori install instead of npx -y @zokizuan/satori-cli@latest install.

Upgrade Satori

satori upgrade

This updates the globally installed CLI, then stages and verifies that release's exact MCP and Core runtime before switching the stable launcher. satori update is an exact alias. Restart running coding agents after a successful runtime upgrade.

If you did not install the CLI globally, run npx -y @zokizuan/satori-cli@latest upgrade. Upgrade does not rewrite client configuration, indexes, hooks, or repository profiles.

Satori follows the exact MCP/Core versions declared by the latest CLI package; it does not mix independently selected latest package versions.

Use --profile default|minimal|all-text when the current repository should write or update repo-local satori.toml. This file controls index policy only; it is not a place for API keys, model names, Milvus endpoints, or tokens.

Codex Runtime Env

The installer stores the selected runtime in ~/.satori/bin/satori-mcp.js. The generated ~/.codex/config.toml entry forwards optional credentials and operational overrides; it does not duplicate a second provider/model selection. Install and uninstall commands show a concise summary by default; use --format json before the command for the complete machine-readable receipt.

Claude Runtime Env

The generated ~/.claude.json entry writes mcpServers.satori.env with ${VAR:-} pass-through values. Replace any value with a literal if you want Claude to own that setting.

OpenCode Runtime Env

The generated OpenCode entry writes mcp.satori.environment with {env:VAR} pass-through values. Replace any value with a literal to store it directly in OpenCode.

Startup Model

The installer resolves the package once, writes the runtime under ~/.satori/mcp-runtime/, creates the stable launcher ~/.satori/bin/satori-mcp.js, and points supported clients at that launcher with Node.

Do not use resident npx commands for supported clients; package-manager startup latency is exactly what the installer avoids.

Managed Files

  • Codex config: ~/.codex/config.toml.
  • Codex guidance: ~/.codex/AGENTS.md.
  • Optional Codex hook: ~/.codex/hooks.json.
  • Claude config: ~/.claude.json.
  • OpenCode config: ~/.config/opencode/opencode.json.
  • OpenCode instructions: ~/.config/opencode/AGENTS.md.

The installer refuses to overwrite unmanaged Satori entries. If you already have one, remove or align it before rerunning install.

Repo Config and Profiles

satori.toml is a repository-local index policy file. It is separate from installer-managed client config and from provider runtime environment variables.

Config Shape

[index]
profile = "minimal"

Missing config defaults to default. Invalid index.profile values fail closed with an explicit profile error.

default

Safe-broad indexing for source, docs/text, config, scripts, infra/query files, and known extensionless files such as Dockerfile, Makefile, Justfile, Taskfile, Procfile, Jenkinsfile, and .dockerignore.

minimal

Source plus docs/text only. Use it when you want lower indexing cost and do not need config, scripts, or infra files in the index.

all-text

Safe-broad plus unknown UTF-8 text files under the size cap. SATORI_ALL_TEXT_MAX_BYTES can override that cap. The hard denylist still applies first.

Index profiles decide what enters the index. Search scope decides what gets queried. search_codebase still defaults to scope=runtime, so indexing docs/config does not make documentation beat implementation code by default.

satori.toml, .gitignore, and .satoriignore are index-policy control files. Ordinary changes can converge through search freshness or manage_index action="sync". On managed offline runtimes, a tracked rebuild-safe incompatibility automatically starts or joins background reindex maintenance and returns not_ready / indexing; unsafe, failed, or connected-runtime cases can still return requires_reindex for operator recovery.

Minimum Runtime Setup

Select the runtime through the installer before indexing. Provider, model, dimension, reranker projection, and vector-store identity are compatibility inputs; changing an incompatible selection requires a reindex. Restart every Satori MCP client after changing the managed launcher.

Offline Potion

npx -y @zokizuan/satori-cli@latest install --runtime offline

Uses local Potion embeddings with BM25 and LanceDB. Qualified Linux x64/WSL2 installs default to LateOn reranking; add --reranker none to disable neural reranking. Once installed, the qualified offline runtime requires no model API key and is designed for zero Satori runtime network requests.

Offline Ollama

npx -y @zokizuan/satori-cli@latest install --runtime offline --ollama-model nomic-embed-text --reranker none

Uses the selected loopback Ollama model with LanceDB. On qualified Linux x64/WSL2, --reranker lateon is also supported.

Connected Voyage + LanceDB

VOYAGEAI_API_KEY=your-api-key \
npx -y @zokizuan/satori-cli@latest install --runtime voyage --vector-store lancedb

Uses Voyage Code 3 embeddings and local LanceDB storage.

Connected Voyage + Milvus

VOYAGEAI_API_KEY=your-api-key \
MILVUS_ADDRESS=your-milvus-endpoint \
MILVUS_TOKEN=your-optional-token \
npx -y @zokizuan/satori-cli@latest install --runtime voyage --vector-store milvus

Uses Voyage Code 3 embeddings with Milvus or Zilliz. Milvus is not accepted with the offline runtime.

Measured on Satori: warm Potion + LanceDB search reached 154.543 ms p95 across 10,830 chunks. Owner-oriented retrieval and bounded source reads are designed to cut repository-discovery token waste dramatically instead of feeding broad files into the model. An exploratory six-repo LateOn tuning run reached 0.5046 MRR versus 0.2900 without reranking across 36 owner-discovery tasks; that MRR result is tuning evidence, not a held-out release guarantee.

Index the First Repo

Satori serves repository intelligence from a completed Publication. Start with one absolute repository path (relative paths are rejected), create the first Publication, confirm readiness with status, then search with runtime-first defaults.

1 Connect

Run manage_index action="status" path="/absolute/path/to/repo" to verify the MCP runtime starts and to inspect whether a current Publication already exists.

2 Create

Run manage_index action="create" path="/absolute/path/to/repo". Use the repository root for the first index unless you have a specific subdirectory workflow. Create returns after accepting the operation; while the same runtime is active, poll manage_index action="status" until its process-lifetime operation phase reaches completed, failed, or blocked. Phase, progress, and error are process-lifetime state and are not reconstructed after restart; status then reports the durable current Publication state.

3 Search

Run a plain-English behavior query, for example search_codebase path="/absolute/path/to/repo" query="where is authentication flow enforced". Defaults are scope=runtime, resultMode=grouped, and groupBy=symbol.

4 Navigate and read

Use file_outline to lock the owner symbol, then read_file to open that exact indexed symbol or a bounded source window. Use call_graph when relationship evidence is qualified for that symbol.

Practical workflows

Start from the job, not the tool name.

The default agent path starts with a repository question, narrows to the owner, and ends with exact evidence. The same primitives support onboarding, debugging, and change planning without requiring a different Satori mode.

LEARN A REPO “What owns this behavior?”

Search by intent, inspect the owning file, then read the exact symbol.

DEBUG “Where does this error originate?”

Use the literal clue plus semantic context, then follow supported relationship evidence.

PLAN A CHANGE “What should I inspect before editing this subsystem?”

Resolve the owner, structure, direct navigation evidence, and exact source before mutation.

1 Search

Use search_codebase with the user requested path and a behavior or concept query. Default scope is runtime, grouped by symbol, with changed-file awareness when the repository supports it. Prefer recommendedNextAction when present.

2 Outline

Use file_outline to lock symbol spans before reading or editing. Exact mode resolves symbolInstanceId and reports ambiguity instead of guessing.

3 Graph

Use call_graph with the returned callGraphHint.symbolRef. On symbol-owned flows, symbolRef.symbolId carries the exact symbolInstanceId. Treat the output as nearby context, not a complete impact guarantee.

4 Read exact evidence

Use read_file with the exact indexed symbol returned by navigation, or request a bounded source window. If graph traversal abstains, use the returned fallback plus scoped search rather than treating an unsupported relationship as missing code.

Managed offline runtimes normally turn a rebuild-safe incompatibility into background indexing automatically. If a tool still returns requires_reindex, automatic maintenance was unavailable, suppressed after failure, or unsafe for that authority; use manage_index(action="reindex") as the operator recovery override, then retry the original call.

If manage_index returns reason="runtime_owner_conflict", restart all Satori MCP clients so only one runtime fingerprint/config identity is active, then retry the mutation. MCP tools never kill processes or ask interactive cleanup questions.

Publication-Owned Navigation

Each completed Publication owns one immutable JSON navigation tree alongside its exact vector and source checkpoint. Reads select and pin that Publication before resolving symbols or relationships.

Symbol Registry

Grouped search returns owner symbols, not loose chunks. Matching chunks remain supporting evidence for the selected symbol, and synthesized file symbols provide a safe fallback for files without extracted source symbols. Exact navigation uses symbolInstanceId; symbolKey is stable-ish candidate lookup only.

Relationship Navigation

Publication relationship navigation stores conservative CALLS v0 edges plus TS/JS IMPORTS and EXPORTS v0 edges. Syntactic tiers may use bounded name-based evidence; CBM-backed languages require semantic target provenance. Ambiguous or unproved targets are skipped.

Current Limits

TS/JS import/export edges cover resolvable relative modules and unambiguous local export declarations only. Package imports, unresolved paths, ambiguous local exports, and multiline module syntax are intentionally skipped.

TypeScript, JavaScript, Python, Go, Java, C#, C++, Rust, and Scala provide production-ready CALLS v0 navigation when the current Publication has compatible relationship navigation. Resolved test-reference navigation remains separately qualified for TypeScript, JavaScript, Python, and Go. Python and Go additionally provide on-demand file_outline structural analysis for exact functions and methods. TypeScript, JavaScript, and Scala use Satori's syntax/name-based advisory resolver; Scala v1 admits direct non-member calls only when the indexed target is unique, while member/dynamic dispatch remains outside the claim. The CBM-backed languages expose conservative direct-call slices: Go excludes receiver/type, embedded/interface dispatch, callbacks, and callable aliases; 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++ 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.

Runtime Navigation

call_graph traverses relationship navigation from the exact Publication pinned for the request. Immutable JSON is the serving representation; there is no alternate SQLite backend or fallback navigation authority.

Seven Tools

The live MCP registry exposes exactly seven tools. Together they cover repository discovery, lifecycle, search/pagination, structural navigation, bounded source reads, and call-graph context without adding source-code write commands.

list_codebases

Lists known indexed repositories with readiness and runtime-owner state so an agent can discover an existing Publication before starting another index operation.

manage_index

Supports create, reindex, sync, status, and clear. Indexing builds a complete staged generation before it becomes the current Publication; status separates durable Publication state from process-lifetime progress.

search_codebase

Searches by behavior or identifier with runtime, docs, or mixed scope, path operators, filters, owner-symbol grouping, freshness checks, structured warnings, and optional debug modes.

continue_search

Reveals more groups from one frozen grouped-search result without rerunning embedding, retrieval, or reranking. Exact-offset retries are idempotent; expiry or authority drift fails closed.

file_outline

Returns the current structural outline for a file. Supported languages expose exact symbol ownership and spans; Python and Go also expose on-demand structural analysis details.

call_graph

Traverses bounded caller/callee relationship context and supported test references from an exact symbol reference. Output follows the language's declared capability boundary.

read_file

Reads bounded source windows or opens one exact indexed symbol. It is restricted to tracked searchable roots and is not a general host-filesystem reader.

Publication Lifecycle

manage_index owns the public lifecycle. Use create for the first Publication, sync for ordinary source divergence, reindex when current authority is missing/corrupt/incompatible, status to inspect durable readiness, and clear only for intentional removal. Mutations are blocked when live runtime ownership would make authority ambiguous.

Sync

manage_index action="sync" converges ordinary source or ignore-rule changes. The replacement generation is assembled in staging and becomes current only after its search, symbol, structural, and relationship state is complete.

Reindex

manage_index action="reindex" creates a fresh Publication when the current generation is absent, corrupt, or incompatible with the running architecture/configuration. Satori does not expose a repair action for retired authority formats.

A failed build leaves the previous complete Publication in authority when possible; partial staging is never promoted.

Clear

manage_index action="clear" is destructive. Do not call it for routine refresh. Use it only when the user explicitly asks to remove Satori's tracked index for a codebase.

Status

manage_index action="status" is the authoritative readiness view. While the same runtime is alive it can also project active mutation phase/progress/error. Those process-lifetime fields are not reconstructed after restart; durable status then reflects the current Publication that actually exists.

  • Current Publication/readiness state and remediation reason.
  • Runtime/config compatibility and navigation capability evidence.
  • Source freshness and indexed file/chunk observations.
  • Active mutation metadata only when the owning runtime still has it.

Publication safety

Readers acquire a lease on one current immutable Publication for the request. A concurrent sync/reindex may publish a newer generation, but it does not change the evidence underneath an in-flight read.

Warnings and Status

Satori separates usable degraded output from blocking lifecycle states. Agents should branch on structured statuses and warnings instead of parsing prose.

Stable Warnings

Warnings are structured objects with a stable code, severity, blocking flag, message, and action. They mean the result is usable but degraded unless blocksUse=true.

FILTER_MUST_UNSATISFIED SEARCH_PARTIAL_INDEX:limit_reached RERANKER_FAILED SEARCH_PASS_FAILED:*

Blocking Status

requires_reindex is not a warning. Managed offline runtimes automatically rebuild the tracked incompatibilities that are safe to repair; a surviving requires_reindex status means explicit operator recovery is required before the result can be treated as current.

Diagnostic Causes

Current Publication state, missing_symbol_registry, missing_relationship_navigation, incompatible_symbol_registry, incompatible_relationship_navigation, watcher state, and Publication navigation readiness explain why the tool chose a lifecycle state. Incompatible or unsupported pre-clean-break index state requires a fresh index or reindex.

Debug Payloads

Use debugMode=full on search_codebase when you need ranking, filter, freshness, exact-registry, tracked-lexical, reranker, or phase-timing explanations. Start with hints.debugSummary, then drill into hints.debugSearch only when needed.

Debugging Search

Normal search output should stay compact. Use debugMode=summary|ranking|freshness|full when you need to understand ranking, filters, fallback passes, or exclusions.

Debug payload

  • Filters applied in deterministic order.
  • Candidate counts before and after filtering.
  • Exact-registry hit, miss, ambiguity, or registry-unavailable state.
  • Phase timings for freshness, registry lookup, semantic search, lexical recovery, rerank, grouping, and navigation validation.
  • Reranker attempt and usage state.
  • Freshness mode and changed-file boost state.
  • Relaxed search pass usage when grouped output underfills.
  • Tracked lexical and live path-scoped evidence when exact lookup supplements semantic chunks.

Warnings vs failures

Warnings mean usable but degraded; follow each warning action. Failures and any requires_reindex status that survives automatic offline maintenance require remediation before treating results as current.

Troubleshooting

Prefer status and debug output before guessing. The goal is to make repo state visible enough for the agent to choose the next operation.

Not indexed

Run manage_index(action="create") on the repository root, then retry search.

Requires reindex

Managed offline runtimes normally start or join the rebuild automatically and return not_ready / indexing. If requires_reindex is still returned, run manage_index(action="reindex") as the recovery override. Do not use sync as a substitute for a full runtime or format incompatibility.

Noisy results

Apply suggested ignore patterns through repo .satoriignore, then run manage_index(action="sync") for immediate convergence.

Runtime configuration mismatch

The default offline Potion + LanceDB install needs no model API key. If a connected or manually overridden runtime returns MISSING_PROVIDER_CONFIG, run npx -y @zokizuan/satori-cli@latest doctor, fix the reported provider/backend values, restart the MCP clients, then retry the original tool call. Inside search results, the same text may simply be matched repository content rather than an active error.

Unsupported graph

Follow the returned navigation fallback. Read exact spans and use additional scoped searches to enumerate usages.

Generated output in context

If generated files such as dist, build, or .output appear in search context, verify the generated artifact directly. Source matches do not prove generated output is current.

Partial index

If a full index hits a limit, search may still return partial chunks, but navigation may be unavailable or incomplete. Treat the warning as evidence to narrow scope, sync, or reindex before relying on related-code navigation.

Connected backend timeout

This applies only to the optional Milvus/Zilliz path. If the remote backend times out during validation or lifecycle work, follow the returned retryable backend guidance; do not treat it as a failure of the default local LanceDB runtime.

Connected collection limit

This applies only to optional Zilliz/Milvus deployments. If the backend reports a collection-capacity limit, follow the returned manage_index guidance for that backend before retrying.

FAQ

Questions people usually have before adopting it.

Do I need to reindex every time code changes?

No. Ordinary source changes use incremental synchronization. Full reindex is reserved for states that actually require rebuilding the Publication.

Will Satori ask me before routine reindexing?

On the managed offline path, rebuild-safe automatic maintenance starts or joins the background reindex without making the user babysit it. Connected/remote, unsafe, unavailable, or failed automatic recovery remains explicit.

Does Satori send my code to a model API?

The qualified default offline runtime uses local Potion embeddings, BM25, LateOn reranking, and LanceDB and requires no model API key after installation. Connected Voyage/Milvus configurations are optional.

Is call_graph a complete dependency graph?

No. It is conservative navigation evidence. Dynamic dispatch, reflection, framework wiring, generated calls, and unsupported language semantics can exceed the qualified relationship model.

Is Satori a replacement for grep or an IDE language server?

No. Literal search and language-server/compiler tooling remain useful. Satori adds a persistent evidence layer that combines intent retrieval, exact evidence, ownership, bounded source, freshness, and supported repository relationships for coding agents.

Does Satori edit my repository?

No. Source access is read-only through the MCP product surface. Your editor or coding agent owns source mutation.

Operational Boundaries

Satori provides retrieval, structural/relationship navigation, warnings, and recovery guidance. It does not replace the developer's normal editing, testing, or review workflow.

Not a source-code write server

Satori does not expose source-code write tools through MCP. Edits stay in the user's editor or agent host.

Not an agent framework

Satori works alongside coding agents and MCP clients. It is focused on repository context, not orchestration.

Not a test replacement

Static evidence helps agents investigate, but runtime behavior still needs tests, typechecks, review, and developer validation.

Local-first product boundary

The current release is designed to run on the developer machine or self-managed infrastructure. The public product contract does not depend on a hosted Satori control plane.