Operational documentation

Satori Docs

Satori gives coding agents repo-aware retrieval through a fixed six-tool MCP surface: index lifecycle, semantic search, symbol outlines, exact reads, and bounded call-graph context.

Install Setup First Index Lifecycle Warnings Troubleshooting

Install the MCP Server

Satori runs as an MCP server. The easiest path is the CLI installer: it writes managed client config and copies the first-party workflow skills without adding new MCP tools.

Codex

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

Writes the Satori MCP entry to ~/.codex/config.toml and installs Satori skills in ~/.codex/skills.

Claude

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

Writes the Satori MCP entry to ~/.claude/settings.json and installs Satori skills in ~/.claude/skills.

Use --client all to install both clients, and uninstall with the same selector to remove only Satori-managed config and skills.

Manual MCP Config

For JSON-style clients, point the MCP server at the published package through npx. Keep the startup timeout long enough for first-run package resolution. 

{
  "mcpServers": {
    "satori": {
      "command": "npx",
      "args": ["-y", "@zokizuan/satori-mcp@4.8.0"],
      "timeout": 180000,
      "env": {
        "EMBEDDING_PROVIDER": "VoyageAI",
        "EMBEDDING_MODEL": "voyage-4-large",
        "EMBEDDING_OUTPUT_DIMENSION": "1024",
        "VOYAGEAI_API_KEY": "your-api-key",
        "VOYAGEAI_RERANKER_MODEL": "rerank-2.5",
        "MILVUS_ADDRESS": "your-milvus-endpoint",
        "MILVUS_TOKEN": "your-milvus-token"
      }
    }
  }
}

Managed Files

  • Codex config: ~/.codex/config.toml.
  • Codex skills: ~/.codex/skills.
  • Claude config: ~/.claude/settings.json.
  • Claude skills: ~/.claude/skills.

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

Minimum Runtime Setup

Configure the embedding provider and vector backend before indexing. Those values are part of the index fingerprint, so changing provider, model, dimension, or vector-store schema later requires a reindex.

Cloud Start

EMBEDDING_PROVIDER=VoyageAI
EMBEDDING_MODEL=voyage-4-large
EMBEDDING_OUTPUT_DIMENSION=1024
VOYAGEAI_API_KEY=your-api-key
VOYAGEAI_RERANKER_MODEL=rerank-2.5
MILVUS_ADDRESS=your-milvus-endpoint
MILVUS_TOKEN=your-milvus-token

This is the recommended first path for quality: VoyageAI embeddings plus Milvus or Zilliz for vector storage.

Local Start

EMBEDDING_PROVIDER=Ollama
EMBEDDING_MODEL=nomic-embed-text
OLLAMA_HOST=http://127.0.0.1:11434
MILVUS_ADDRESS=localhost:19530
MILVUS_TOKEN=your-token

Use this path when you want local embeddings. Keep model and dimension stable for any repo you have already indexed.

Index the First Repo

Satori only returns repo context after a codebase has been indexed. Start with one absolute repository path, confirm it appears in the codebase list, then search with runtime-first defaults.

1 Connect

Run list_codebases in your MCP client to verify the server starts and can see its local state.

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.

3 Search

Run search_codebase path="/absolute/path/to/repo" query="authentication flow". Defaults are scope=runtime, resultMode=grouped, and groupBy=symbol.

4 Navigate

Use file_outline, call_graph, and read_file to lock exact spans before editing.

Search Workflow

The default agent path is intentionally narrow. Search finds candidate symbols, outline locks deterministic spans, call graph adds nearby relationships, and exact reads provide edit context.

1 Search

Use search_codebase with the user requested path. Default scope is runtime, grouped by symbol, with changed-file awareness when the repository supports it.

2 Outline

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

3 Graph

Use call_graph with the returned callGraphHint.symbolRef. Treat the output as graph context, not a complete impact guarantee.

4 Read

Use read_file with open_symbol or the returned navigation fallback. Reads are bounded and return continuation hints when truncated.

If a tool returns requires_reindex, run manage_index(action="reindex") for the hinted path before retrying the original call.

Six Tools

Satori keeps the public MCP surface fixed. Diagnostics are added through existing tools, not through new product surface area.

list_codebases

Lists indexed repositories in deterministic buckets: ready, indexing, requires reindex, and failed.

manage_index

Creates, syncs, checks status, reindexes, or clears indexes. Status includes health diagnostics when available.

search_codebase

Semantic search with runtime/docs/mixed scopes, path operators, must/exclude filters, grouped output, and debug metadata.

file_outline

Reads sidecar symbol outlines and resolves exact symbols without guessing when matches are ambiguous.

call_graph

Traverses sidecar caller/callee relationships with deterministic depth, limits, and transparency metadata.

read_file

Reads plain text or annotated content. Exact symbol opening delegates to outline resolution.

Sync, Reindex, and Clear

Lifecycle operations have different meanings. Use sync for ordinary file changes, reindex for fingerprint or sidecar incompatibility, and clear only when you intentionally want to remove a tracked codebase.

Sync

manage_index action="sync" is the immediate convergence lever after normal file edits or ignore-rule changes. Search also runs freshness checks before returning results.

Reindex

manage_index action="reindex" rebuilds the index. Use it when a tool returns requires_reindex or a reindex hint. Do not substitute sync for fingerprint incompatibility.

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" answers why a repo is or is not usable right now.

  • Index state and remediation reason.
  • Completion marker proof.
  • Fingerprint match or mismatch.
  • Sidecar readiness and stale-state signals.
  • Watcher state and indexed file/chunk counts.

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 mean the result is usable but degraded. Examples include unsatisfied must filters, reranker failure, or a failed search pass that still left usable fallback output.

FILTER_MUST_UNSATISFIED RERANKER_FAILED SEARCH_PASS_FAILED:*

Blocking Status

requires_reindex is not a warning. It is a blocking status or remediation hint. Reindex the hinted path, then retry the original call.

Diagnostic Causes

fingerprint_mismatch, completion_marker_missing, sidecar readiness, and watcher state are status diagnostics. They explain why the tool chose a lifecycle state; they are not all search warnings.

Debug Payloads

Use debug=true on search_codebase when you need ranking, filter, freshness, reranker, or relaxed-pass explanations.

Debugging Search

Normal search output should stay compact. Use debug=true when you need to understand ranking, filters, fallback passes, or exclusions.

Debug payload

  • Filters applied in deterministic order.
  • Candidate counts before and after filtering.
  • Reranker attempt and usage state.
  • Freshness mode and changed-file boost state.
  • Relaxed search pass usage when grouped output underfills.

Warnings vs failures

Warnings mean usable but degraded. Failures and requires_reindex statuses 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

Run manage_index(action="reindex"). Do not use sync as a substitute for fingerprint incompatibility.

Noisy results

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

Unsupported graph

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