SatoriSemantic + lexical retrieval
Behavior by meaning, BM25, exact paths, identifiers, configuration keys, and literal evidence.
find intent without losing literals
Repository intelligence · local by default
Satori
Understand any codebase before you touch it.
Satori turns a repository into a local intelligence database your coding agent can search, navigate, and interrogate: semantic meaning, exact identifiers, symbol owners, structure, supported relationships, freshness, and the exact source that matters.
Codex · Claude Code · OpenCode · MCP
Linux x64 / WSL2
No model API key on the offline path
Install Satori
npx -y @zokizuan/satori-cli@latest install
npx -y @zokizuan/satori-cli@latest doctor
Repository intelligence ledger
one coherent Publication
ASK
Where is auth refresh handled, what owns it, and what should I read first?
REPOSITORY
src/auth/refresh.ts
src/session/store.ts
src/http/middleware.ts
config/security.ts
files · paths · checkpoints
INTELLIGENCE
semanticbehavior by meaning
lexicalBM25 + exact identifiers
structuresymbols + source spans
relationsqualified navigation evidence
freshnesscurrent source authority
EVIDENCE
OWNER · rank 1
AuthRefreshCoordinator.refresh
src/auth/refresh.ts:84–146
NEXT
outline · callers · exact source
FRESHNESS
current · publication-bound
Search broadly.
Resolve the owner.
Read narrowly.
Local Potion + BM25 + LateOn + LanceDB
Nine production navigation languages
Exact symbol + bounded source reads
Automatic managed-offline reindex
Read-only source access
What the product actually stores
A code map that survives the prompt.
Satori is not just semantic search. One Publication binds multiple evidence layers to the same repository generation, so an agent can move from a vague question to exact source without reconstructing the map from scratch every time.
Symbols + structural spans
Parser-derived functions, methods, classes, file outlines, and bounded source ownership.
rank evidence around real owners
Supported relationships
Qualified callers, callees, imports, and exports when the language backend can prove them.
advisory, conservative, fail-closed
Freshness + Publication authority
Source checkpoints, runtime compatibility, policy, navigation readiness, and atomic replacement generations.
know which repo state answered
Ask your repository
From a human question to source evidence.
The agent does not need a perfect identifier up front. Satori narrows the search in stages and keeps each stage tied to repository evidence.
QUESTION
“Find the code that keeps a detached background mutation alive after the client disconnects.”
SEARCH
shared runtime · lifecycle · detached mutation
semantic + lexical evidence
OWNER
SharedRuntimeHost.ownDetachedMutationCompletion
symbol-owned result
TRACE
host activity → shutdown drain
supported relationship context
SOURCE
exact method + bounded neighbors
read only what you need
freshness: current
Publication-bound evidence
source remains read-only
Useful evidence, not more noise
The public surface stays small. Behind it, Satori gives a generic MCP harness the code-intelligence stack it would otherwise have to rebuild.
154 ms local search
Potion + LanceDB measured 154.543 ms warm-search p95 on Satori's 10,830-chunk release benchmark.
AST-derived code map
Parser-backed symbols, structural evidence, exact spans, and qualified CALLS v0 navigation ship across nine production languages.
Token-efficient by design
Exact symbols and bounded reads keep broad file dumps out of the prompt, so repository discovery spends context on the code that matters instead of scanning whole files.
Reranking that finds owners
Exploratory six-repo tuning reached 0.5046 MRR versus 0.2900 without reranking across 36 owner-discovery tasks—not a held-out release claim.
Offline after install
Potion embeddings, BM25 search, LanceDB storage, and managed local retrieval need no model API key and make no Satori runtime network requests after installation.
One coherent Publication
Search, symbols, structural evidence, and qualified calls activate together; unsupported or ambiguous relationships fail closed.
Where it earns its keep
Use Satori when the repository is larger than the prompt.
Walk into an unfamiliar codebase with a map.
Ask where a behavior lives, identify the owning symbol, inspect the file structure, then read the implementation instead of browsing the tree at random.
“What owns billing retries?”
Turn a symptom into source.
Start from an error or behavior, then follow owner and relationship evidence toward the exact code.
Plan before the first edit.
Find the owner, nearby structure, bounded source, and supported call paths before changing a subsystem.
Spend context on implementation.
A strict search → owner → exact source funnel helps smaller models avoid context-heavy repository discovery.
Share the code map, not the prompt.
Compatible local sessions attach to one managed runtime and current repository intelligence while keeping independent MCP sessions.
Try it on one repo
The qualified Linux x64 / WSL2 path is offline after installation: local Potion embeddings, BM25 search, LateOn reranking, LanceDB storage, and parser-derived code intelligence. No model API key is required.
Install supported clients
Current packaged runtime target: Linux x64. WSL2 is the primary qualified path.
npx -y @zokizuan/satori-cli@latest install
npx -y @zokizuan/satori-cli@latest doctor
1. Index
Create the repository Publication and wait until status is ready.
2. Ask
Ask for the behavior, owner, or source area the agent needs to understand.
3. Follow evidence
Open the exact symbol, bounded source, outline, or qualified call path returned by Satori.
Local intelligence, maintained for you
The index is not a static cache you have to babysit.
DEFAULT OFFLINE STACK
Potionlocal semantic embeddings
BM25lexical + exact evidence
LateOnlocal query-time reranking
LanceDBlocal Publication storage
No model API key is required for the qualified managed offline path after installation. Connected Voyage and Milvus/Zilliz remain optional advanced runtimes.
FRESHNESS + REPAIR
Source changedincremental sync prepares a replacement Publication
Sync runninga compatible proven Publication can remain readable with freshness metadata
Rebuild required · managed offlineSatori starts or joins one background reindex automatically
Remote / failed / unsafeexplicit reindex remains the operator recovery override
Clearalways explicit; never automatic maintenance
Read-only source — Satori does not modify repository files.
Conservative graph — absent edges are not proof of no caller.
Open source — AGPL-3.0-only.
Build with it. Break it. Tell me.
If Satori helps, fails, or feels confusing in a real repository, I want the case. Send the language, repo size, MCP client, and what you were trying to understand.