Agent
Claude Code, Codex, Cursor-style workflows, or another MCP client.
How Satori gives MCP coding agents symbol-owned repo search, exact reads, bounded graph context, and freshness checks without hiding state or failures.
Agent requests route through a fixed six-tool registry. The MCP runtime enforces freshness/fingerprint gates and orchestrates search. Core sync provides deterministic file-state truth for indexing.
Claude Code, Codex, Cursor-style workflows, or another MCP client.
Exposes six agent-safe operations instead of a wide internal API.
Coordinates indexing, search, sync, freshness, and lifecycle state.
Vector store, symbol registry, relationship sidecars, local snapshots, and Merkle state.
@zokizuan/satori-coreOwns indexing, sync, chunking, metadata, and retrieval primitives.
@zokizuan/satori-mcpOwns the MCP server, six-tool contract, lifecycle state, and agent envelopes.
@zokizuan/satori-cliInstalls managed client config, copies the first-party skill, and exposes shell tool calls.
Public setup is installer-owned. Supported clients should not pay package-manager resolution cost during every MCP startup, and users should not have to copy cache paths into each harness by hand.
satori-cli install --client all resolves the MCP
runtime once, writes managed client config, and copies the
first-party workflow skill.
Client config launches the installer-owned Node launcher at
~/.satori/bin/satori-mcp.js. Resident startup does
not call npx, npm, or a package manager.
Codex, Claude, and OpenCode config differences live in the installer and its tests, not in user-maintained snippets.
Satori exposes six MCP tools. The point is not a large API; it is a small set of operations that return state, warnings, and next steps when context is unsafe. The MCP server does not expose source-code write tools.
list_codebasesLists tracked roots grouped by ready, indexing, failed, or requires-reindex state.
Refuses to flatten state into a single success/failure bit.
search_codebaseFinds relevant code from plain-English behavior queries, exact identifier lookup, symbol-owned grouping, freshness checks, recommended actions, structured warnings, and navigation hints.
Refuses stale or unsafe context when index gates require attention.
file_outlineMaps symbols in a file and resolves exact labels or IDs through sidecar metadata.
Refuses to guess when exact symbol resolution is ambiguous.
call_graphTraverses callers and callees from a search-provided symbolRef.
Refuses to fake graph data when the sidecar is absent or not ready.
read_fileReads files, line ranges, or exact symbols with optional annotated outline status.
Refuses unlimited context dumps; large reads are bounded.
manage_indexCreates, syncs, reindexes, checks status, clears, and handles force-reindex recovery paths.
Refuses destructive ambiguity: clear is explicit, backend timeouts preserve local state, and mixed live runtime owners block mutation.
Satori separates retrieval from navigation. The vector store finds candidate evidence; the symbol registry and relationship sidecar explain what that evidence belongs to.
Files remain the source of truth. The registry is a derived view for one compatible indexed snapshot, with owner symbol keys, exact symbol instances, file-owner fallbacks, and outline records.
The current sidecar stores conservative CALLS v0
edges plus TS/JS relative IMPORTS and
EXPORTS v0 edges. Ambiguous same-name targets are
skipped rather than guessed.
search_codebase returns exact registry hits or
symbols in grouped mode with action guidance, capability
confidence, structured warnings, and fallbacks. Matching chunks
are evidence for those symbols, not the final unit the agent
should edit from.
call_graph now traverses compatible relationship
sidecars directly. JSON sidecars remain canonical; SQLite is an
additive cache for validation or explicit experimental reads and
can serve only after parity with JSON registry and relationship
sidecars is proven.
Satori treats index state as part of the contract. Agents do not just receive search results; they also receive status, freshness, and recovery guidance when the index is unsafe or incomplete.
{ embeddingProvider, embeddingModel, embeddingDimension,
vectorStoreProvider, schemaVersion
}
Prevents silent reads from incompatible embedding models/dimensions or schema-mode mismatches.
The behavior below is shown directly because it is the core trust model: search is freshness-aware, sync is incremental, and cloud lifecycle operations are verified before local state is discarded.
Freshness gate -> operator parse -> dense/BM25 retrieval -> deterministic filters -> rerank policy -> owner-symbol grouping -> stable tie-breaks.
Dense vector hits and BM25 sparse keyword hits merge through reciprocal rank fusion, so concepts and exact tokens both count.
TypeScript, JavaScript, and Python are the only production-ready
call_graph languages. Go and Rust are
symbol_only: compatible registries can power
outlines, while graph traversal returns
unsupported_language.
Uses .gitignore, .satoriignore,
repo-local satori.toml, and configured patterns.
Signature checks converge even without watcher events.
satori.toml selects default,
minimal, or all-text. Profiles control
what enters the index; search scope controls what gets queried.
Stat-first scan, hash-on-change, deterministic Merkle root, and changed-file chunk updates. Navigation reuses changed-file symbol output, preserves unchanged registry state, and recomputes relationships globally without re-splitting unchanged files.
Missing, stale, incompatible, partial, or recovery-failed
navigation does not publish fake graph truth. Public tools return
precise reasons such as missing_symbol_registry,
missing_relationship_sidecar, or
partial_index_navigation_unavailable.
Cloud and local providers use different result budgets. Rerank is capability-driven, docs scope skips rerank, and failures degrade with warnings.
Search can start from a package path inside an indexed parent. Satori resolves the effective root while keeping navigation fallbacks executable.
Remote collection existence is not readiness proof. Missing or incompatible local readiness is recovered only through explicit create or reindex flows with matching completion proof.
Clear and force-reindex mutate local snapshot/Merkle state only after remote deletion is verified or the collection is already absent.
This is the intended architecture flow, not a simulated chat transcript.
search_codebase returns ranked behavior matches or exact identifier hits with freshness state, recommendedNextAction, capability confidence, and navigation hints.
file_outline and read_file.open_symbol resolve the implementation span from symbolInstanceId without guessing.
call_graph provides nearby dependency context from compatible relationship sidecars.
Requires-reindex, missing registry or relationship sidecar, noisy results, and backend timeout states return recovery guidance.
Satori does not edit code. It gives the coding agent enough repo evidence to avoid blind changes.