Satori

Semantic code search for coding agents.

Ask where behavior lives in plain English. Satori finds the owning code and hands your agent the exact source, locally, through MCP.

Website  ·  Get started  ·  Docs  ·  Architecture  ·  Full reference

Start

Beta. Satori supports Linux only for now (x64, including WSL2 on Windows). macOS and native Windows are not supported yet.

Needs Node.js 22.13+ on Linux x64 or WSL2.

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

install sets up Codex, Claude Code, and OpenCode (Antigravity with --client agy). Restart your agent and say:

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

That's it. No account, no API key.

Or let your agent do the setup. Paste this:

Install Satori by following the "For AI agents" section of
https://github.com/ham-zax/satori, then index this repository.

For AI agents

If you are a coding agent setting up or using Satori, follow these steps.

Install

1. Check the platform: node -v must be 22.13 or newer, on Linux x64 or WSL2. Native Windows and macOS are not supported; on Windows, run inside WSL2.
2. Run npx -y @satori-code/cli@latest install, then npx -y @satori-code/cli@latest doctor.
3. If install reports no supported client, rerun it with --client codex, claude, opencode, agy, or all.
4. Tell the user to restart you. The Satori MCP tools load only at agent startup.

Use

1. Call list_codebases. If the repository is not indexed, call manage_index with action="create" and the repository's absolute path. Indexing runs in the background; check it with action="status".
2. Start every "where is…", "what owns…", or "what calls…" question with search_codebase. For plain-English questions, pass up to 4 likely code identifiers or terms in alt_terms.
3. Follow recommendedNextAction when it is returned. Use file_outline to pick a symbol, and call_graph or trace_path for relationships.
4. Read the exact code with read_file before you claim anything or edit.
5. After editing files, call manage_index with action="sync" when you need fresh results.

Rules

• Every path is absolute.
• manage_index action="status" can start or join an automatic rebuild for an incompatible tracked root. Check roots serially on memory-constrained hosts.
• Treat call_graph results as leads to verify, not complete proof.
• Satori is read-only. Make source edits with your own tools.
• The installer also ships a satori skill (~/.agents/skills/satori) with the full workflow.

How it works

You ask a question. Your agent follows the evidence:

search_codebase  →  owner  →  file_outline / call_graph  →  read_file
  by meaning         the         structure and              exact source
  and exact text     symbol      supported relationships    to verify

Satori combines embeddings with BM25 and exact matches, maps hits to the symbols that own them, and keeps every answer on one indexed snapshot of the repository. Edits sync incrementally, and every answer says whether its evidence is still current.

The 11 MCP tools

Tool	What it does
manage_index	Create, sync, inspect, cancel, reindex, or clear the index.
search_codebase	Find behavior by meaning and exact evidence. Start here.
architecture_overview	Summarize areas, boundaries, and hotspots.
continue_search	Page through a result set without searching again.
file_outline	List the symbols and spans in one file.
call_graph	Callers, callees, imports, and exports where supported.
trace_path	Shortest relationship path between two symbols.
find_references	Exact textual occurrences of one symbol.
detect_changes	Map a Git diff to affected symbols and callers.
read_file	Read one symbol or a bounded source span.
list_codebases	List indexed repositories and their readiness.

Why use it

• Unfamiliar code. Ask where behavior lives before you know a filename.
• Bugs. Go from an error string to the code that owns it.
• Refactors. See the owner, its structure, and its callers before the first edit.
• Less context waste. Your agent reads symbol-sized evidence, not whole files. Smaller local models benefit most.
• Many agents, one index. Local sessions share one runtime.

Free, local, read-only

• Free and open source under AGPL-3.0. No account and no telemetry upload.
• The default stack runs offline after install: Potion embeddings, BM25, LateOn reranking, and LanceDB.
• Satori never edits your source and adds nothing to AGENTS.md or hooks.
• satori uninstall removes client config; --purge also deletes ~/.satori.
• Connected Voyage and Milvus/Zilliz are optional. See the reference.

Benchmarks

The offline stack. Potion is a 16M-parameter static code embedding, fast enough to embed a whole repository on a laptop CPU. BM25 and exact matching catch the identifiers it misses. LateOn is a 17M-parameter late-interaction code model. It is too costly to run over everything, so Satori uses it only to rerank the top candidates (budget 64), together with each candidate's role, callers, callees, and tests.

What reranking adds. 36 owner-finding tasks across 6 repositories, where "owner at 1" means the right symbol comes first:

Stack	Owner at 1	Owner at 3	MRR
Potion + BM25 + exact	0.19	0.36	0.29
+ LateOn reranking (depth 32)	0.39	0.64	0.50

Tuning-set results, measured on an earlier prompt projection; the held-out run is still pending. Evidence and limits. On the current build (budget 64), baseline reaches 0.44 owner@1 and 0.78 owner@10 across 18 judged real-repo tasks.

On the current default (LateOn reranking plus definition fusion, which runs only with reranking), 19 named-symbol questions across 4 repositories went from 4 to 13 owners at rank 1 against no reranker; owner in the top 10 stayed at 15 either way. Corrected comparison.

Choosing a reranker. LateOn is the local default. Voyage is an opt-in online reranker (satori reranker use voyage); it works with the offline Potion index and sends each query and its candidate code excerpts to Voyage AI, a MongoDB company. Each Voyage account gets 200 million free tokens per model, about 8,000 searches. 28 plain-English questions over React, Polars, and FlatBuffers, same Potion index for every row:

Reranker	Right answer first	In top 5	In top 10	MRR	Search time: median / mean / p90
LateOn (local, default)	13/28	19/28	21/28	0.556	2.40 s / 3.10 s / 4.19 s
Voyage rerank-3-lite (Voyage default)	18/28	24/28	24/28	0.738	1.04 s / 1.65 s / 3.09 s
Voyage rerank-3	17/28	24/28	24/28	0.711	1.12 s / 2.15 s / 3.23 s
Voyage rerank-2.5	19/28	24/28	24/28	0.759	1.25 s / 2.20 s / 5.21 s

One run per row on one WSL2 laptop; times are the whole search. How to choose, and the limits of these numbers.

Plain-English questions. 46 conceptual questions over React, Polars, and FlatBuffers ("cleanup of useEffect" → commitHookEffectListUnmount). Agents can pass up to 4 code-vocabulary guesses in alt_terms; Satori searches them as separate passes, including definitions, and fuses them with the original question:

alt_terms	Owner at 1	Owner in top 10	Median request
None	8	16	2.7 s
The agent's own guesses	16	34	2.9 s
Another question's guesses (stress test)	1	8	2.8 s

Tuning set with seven labels corrected to the pinned commits. Wrong guesses cost more than none; fixes that limited that cost also cost owners with good guesses, so they were rejected. Details.

Search latency. Measured on React (6,918 files, 36,233 chunks) with the offline CPU stack:

Phase / Mode	Median latency	Notes
Fast retrieval (Potion + BM25)	178 ms	Dense vector search and lexical candidate fusion
+ LateOn reranking (budget 64, CPU FP32)	2.5–3.1 s	Full cross-attention reranking of top 64 code passages, one model session
Fast mode (--reranker none)	~200 ms	Disables LateOn; pure embedding + BM25 search
Cold query with filesystem watcher	< 1 s	Bounded watcher settle; avoids recursive directory stat scan

Reranking adapts to the machine. LateOn encodes candidates in parallel model sessions sized from the host's CPUs and free memory: 1 session on 1 CPU, 4 single-threaded sessions on 4–6 CPUs, 4 × 2 threads on 8–16 CPUs, up to 8 × 2 on 32 or more (above 16 CPUs the rule is extrapolated, not measured). Scores are bit-identical to the single-session path. On a Ryzen 7 3800X under WSL2 (15 logical CPUs visible):

Measurement	One session (1 × 8 threads)	Adaptive pool (4 × 2)
Rerank 64 candidates (median of 3 runs)	1.86 s	1.22 s
Plain-English question to ranked owners (46 questions, median)	2.63 s	2.24 s
Rerank phase of those requests (median)	2.12 s	1.68 s
Peak reranker memory	0.53 GB	1.64 GB

Each session needs 1 GiB of free memory at worker start, so memory-limited hosts and containers run fewer sessions with more threads. The worker is released after 2 minutes idle.

Against codebase-memory-mcp 0.11.0. Same machine, 5 public repositories; each range spans two runs:

Repository	System	Full index	Symbol lookup (p50)	Callers (p50)	One-file edit
ripgrep (Rust)	Satori	5.8 s	8–9 ms	136–146 ms	3.3 s
	CBM 0.11	2.8–2.9 s	13 ms	13 ms	2.1–2.2 s
trufflehog (Go)	Satori	42–55 s	22–23 ms	29–30 ms	19 s
	CBM 0.11	8.9–9.2 s	17–18 ms	15 ms	24–32 s
satori (TypeScript)	Satori	42–46 s	11 ms	21–24 ms	13 s
	CBM 0.11	20 s	29–30 ms	20 ms	13 s

codebase-memory-mcp builds only a graph, so it indexes and answers caller queries faster. Satori also builds embeddings and a vector index, which is what lets it answer plain-English "where is this behavior" questions that a graph cannot. All 5 repositories and the raw results.

Languages

Call graphs for TypeScript, JavaScript, Python, Go, Java, C#, C++, Rust, Scala, Kotlin, and PHP. Symbols and outlines for 88 more languages. Semantic search across about 140. Details.

Commands

Command	Does
satori install	Install the runtime and configure your agents.
satori doctor	Check the installation.
satori upgrade	Upgrade to the latest verified release.
satori terminate	Stop running Satori servers.
satori uninstall	Remove client config (--purge removes everything).

Without a global install, prefix commands with npx -y @satori-code/cli@latest.

Learn more

• Docs: setup, tools, and troubleshooting.
• Full reference: runtimes, configuration, index profiles, benchmarks.
• Product guide: how to get the most out of Satori.

Development

pnpm install
pnpm build
pnpm run check

See CONTRIBUTING.md, SECURITY.md, and docs/RELEASING.md.

License

AGPL-3.0-only. Commercial licensing is available: see COMMERCIAL-LICENSING.md.

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