Architecture / repository intelligence authority

One repository generation. Multiple evidence layers.

Satori is built as one repository-intelligence authority rather than a pile of independent search tools. Natural-language semantic retrieval, lexical evidence, symbol ownership, structural navigation, supported relationships, source freshness, and exact source are bound to one immutable Publication so an agent knows which repository state produced the answer.

01Retrievesemantic + BM25 + exact evidence

02Ownsymbols + source spans

03Navigatequalified relationship evidence

04Provefreshness + runtime compatibility

05Servebounded exact source

One immutable Publication per read Local-first managed runtime Atomic replacement generations Nine qualified navigation languages Fail-closed relationship evidence

How the product stays coherent

System Overview

Agent requests route through a fixed 11-tool MCP surface into one repository-intelligence authority. The runtime selects the current Publication, validates compatibility and freshness, and keeps the request pinned to that immutable generation. Indexing and maintenance build the next Publication separately and activate it only after the replacement is ready to become current authority.

Agent Claude / Codex / OpenCode

request

Tool Registry 11 MCP tools

dispatch

MCP Runtime Tool handlers · freshness gate · Publication authority

coordinates

Runtime dependencies

Local Retrieval Potion / LanceDB

Publication Search · symbols · graph

Core Sync File sync · Merkle · hash

Agent

Claude Code, Codex, Cursor-style workflows, or another MCP client.

Tool Registry

Exposes 11 agent-safe operations instead of a wide internal API.

MCP Runtime

Coordinates indexing, search, sync, freshness, and lifecycle state.

Publication Store

Owns the current immutable generation: search state, symbols, structural evidence, relationships, manifest, and freshness identity.

`@satori-code/core`

Owns indexing, sync, chunking, metadata, and retrieval primitives.

`@satori-code/mcp`

Owns the MCP server, 11-tool contract, lifecycle state, and agent envelopes.

`@satori-code/cli`

Installs the managed runtime and launcher, marked client config, and the canonical satori skill. It never edits AGENTS.md or hook files, and a real directory at a Satori skill-link path is refused and left in place.

Runtime Boundaries

MCP Runtime Owns

Tool contracts and schema validation.
Runtime snapshot state and lifecycle status.
Index freshness, fingerprint gates, and recovery guidance.
Agent-safe responses, warnings, and refusal paths.
Coordination across the current Publication, local retrieval, and core engine.

Core Engine Owns

Stat-first sync, hash-on-change, and deterministic Merkle roots.
Path normalization and snapshot diff primitives.
Partial-scan safety for unreadable files and directories.
AST-aware chunking, symbol ownership, structural evidence, relationship construction, and ignore filtering.
Low-level indexing/search primitives behind MCP orchestration.

Installer Boundary

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.

One public command

npx -y @satori-code/cli@latest install resolves the MCP runtime once, auto-detects supported clients, and writes the installer-owned launcher, client config, and managed guidance where supported.

Stable resident startup

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.

Harness formats stay behind CLI

Codex, Claude, OpenCode, and Antigravity config differences live in the installer and its tests, not in user-maintained snippets.

Agent-Safe Tool Surface

Satori exposes exactly 11 public MCP tools. They cover repository discovery, lifecycle, natural-language + lexical search and pagination, architecture, structural and relationship navigation, exact references, bounded source reads, and change orientation. Every tool is read-only with respect to source code; only Satori index state is mutable through manage_index.

Discovery and Retrieval

`list_codebases`

Lists known indexed repositories with readiness and live runtime-owner state.

Does not flatten incompatible or in-progress repositories into a false “ready” state.

`search_codebase`

Runs freshness-aware hybrid search, exact/lexical recovery, symbol-owned grouping, filters, and optional debug modes.

Refuses to serve an incompatible Publication as current evidence.

`architecture_overview`

Summarizes bounded Publication architecture evidence as logical areas, cross-area boundaries, call hotspots, and coverage/filtering counts.

Does not infer layers, services, clusters, or relationships that are absent from the current Publication.

`continue_search`

Reveals more of one frozen grouped result set without rerunning embedding, retrieval, or reranking.

Expired, stale, conflicting, or authority-drifted handles fail closed.

Navigation and Evidence

`file_outline`

Returns Publication-owned symbols, ownership, spans, and supported structural analysis for one file.

Exact symbol resolution reports ambiguity instead of selecting a same-name guess.

`detect_changes`

Maps a Git diff to current indexed symbol seeds and bounded transitive callers for change orientation.

Does not claim complete blast-radius coverage when relationship evidence is unavailable or truncated.

`read_file`

Reads bounded source windows or opens one exact indexed symbol through current-source symbol resolution.

It is restricted to tracked searchable roots and is not a general host-filesystem reader.

`call_graph`

Traverses bounded caller/callee relationship context and supported test references for an exact symbol reference.

Unsupported dispatch or missing relationship authority returns a capability/readiness fallback rather than a fabricated edge.

`trace_path`

Finds one deterministic shortest path between exact published symbol IDs over selected persisted relationships.

Hard depth/node/edge budgets report truncation; an empty result is not global proof that no path exists.

`find_references`

Scans validated published source for exact textual occurrences of one canonical symbol, independent of semantic ranking.

Textual matches remain observational evidence and never become CALLS without normal relationship proof.

Lifecycle

`manage_index`

Supports create, sync, status, reindex, cancel, and clear while preserving atomic Publication activation.

Incomplete staging never becomes current; destructive actions stay explicit and incompatible live runtime owners block unsafe mutation.

Publication-Owned Navigation

Retrieval and navigation are different evidence layers, but they share one authority. A Publication binds the search snapshot, symbol registry, structural analysis, relationship evidence, manifest, and freshness identity into one immutable generation.

Atomic Visibility

Indexing builds staged state without disturbing readers. Only a complete generation is promoted to current, so a request cannot mix new vectors with an old symbol graph or vice versa.

Publication Leases

A read acquires the current Publication and keeps that exact generation pinned for the request. Concurrent publication changes do not mutate the evidence underneath an in-flight tool call.

Symbol Authority

Matching chunks are retrieval evidence. Navigation resolves them to exact symbol instances and source spans before exposing symbol-owned actions to the agent.

Relationship Authority

CALLS edges are published only when the language-specific strategy proves the target within its public capability boundary. Ambiguity, unsupported receiver dispatch, and unproved build context abstain.

State and Safety

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.

not_indexed No active Publication yet.

manage_index(create)

indexing Build the next Publication off to the side.

result

ready Successful Publication activation.

failed Index build failed; current authority is not replaced.

manage_index(sync)

sync_completed Current Publication refreshed successfully.

fingerprint mismatch

requires_reindex Managed offline schedules a safe rebuild; other cases require operator recovery.

auto-reindex / operator override

indexing Re-enter the build path with the new fingerprint.

manage_index(clear) from any state → not_indexed

Fingerprint Fields

{ embeddingProvider, embeddingModel, embeddingDimension, vectorStoreProvider, schemaVersion, parserVersion, extractorVersion, relationshipVersion, embeddingProjectionVersion, lexicalProjectionVersion }

Safety Result

Prevents silent reads from incompatible embedding models/dimensions or schema-mode mismatches.

Retrieval, Language Intelligence, and Freshness

The trust model is simple: retrieve locally, resolve evidence through the current Publication, expose only language capabilities that are actually qualified, and refuse stale or incomplete authority.

query -> local retrieval -> owner symbol -> qualified relationships -> Publication freshness -> agent guidance

Search Pipeline

Freshness gate -> operator parse -> dense/BM25 retrieval -> deterministic filters -> rerank policy -> owner-symbol grouping -> bounded evidence -> stable tie-breaks.

Deterministic Ranking

Search ordering is deterministic: fused retrieval score first, with a stable candidate identity breaking ties. When LateOn runs, its order is final. Grouped results carry no score; the returned sequence is the ranking.

Hybrid Retrieval + Reranking

Dense and BM25 hits merge through reciprocal rank fusion, then LateOn reranks a bounded candidate set. If reranking fails, the retrieval order is kept.

Language Capabilities

TypeScript, JavaScript, Python, Go, Java, C#, C++, Rust, and Scala ship production symbols plus CALLS v0. The backend is language-specific: OXC/Satori syntactic for JS/TS, Python-native Satori resolution, CBM semantic resolution for Go/Java/C#/C++/Rust, and Satori syntactic direct-call resolution for Scala. Kotlin and PHP add conservative CALLS v0 over symbols from codebase-memory-mcp's definition extractors.

Ignore Rules

Uses .gitignore, .satoriignore, repo-local satori.toml, and configured patterns. Signature checks converge even without watcher events.

AST-Derived Code Intelligence

OXC, Tree-sitter, and qualified semantic backends produce symbols, structural evidence, exact spans, ownership, and relationship inputs. MCP clients get useful code intelligence rather than a raw parser dump.

Scope Filtering

Runtime scope keeps implementation discovery first and still includes test evidence (demoted unless test intent is explicit). Documentation stays out of runtime by default; use scope=docs for documentation-only results, or mixed for everything.

Index Profiles

satori.toml selects default, minimal, or all-text. Profiles control what enters the index; search scope controls what gets queried.

Publication Rebuilds

Stat-first scanning and hash-on-change keep source discovery bounded. Indexing assembles the next complete search/symbol/relationship generation in staging, then atomically publishes it when ready.

Fail-Closed Navigation

Missing, stale, incompatible, ambiguous, or unsupported navigation never becomes guessed graph truth. Public tools return explicit capability/readiness outcomes and keep callers/callees advisory.

Offline After Install

Potion + BM25 + LateOn + LanceDB is the managed Linux x64 / WSL2 path. Provisioning happens during install; the qualified offline runtime is designed for zero Satori runtime network requests afterward.

Path-Scoped Live Evidence

Exact path: searches can supplement dirty tracked files with bounded live reads, so fresh regression lines are not hidden by stale vector chunks.

Subdirectory Roots

Search can start from a package path inside an indexed parent. Satori resolves the effective root while keeping navigation fallbacks executable.

No Reconstructed Progress

Active indexing progress belongs to the live runtime. After a restart, status reports durable current Publication state rather than inventing a process history that no longer exists.

Shared Offline Runtime

The managed offline Potion + LanceDB path can share one resident runtime across compatible clients for the same state root. Mutation is blocked when live ownership would make Publication authority ambiguous.

Explicit Clear

Repository state removal is an explicit manage_index action. Ordinary reads never mutate source files or silently repair incompatible index state.

Example Flow

This is the intended architecture flow, not a simulated chat transcript.

Agent asks for the relevant implementation

search_codebase returns ranked behavior matches or exact identifier hits with freshness state, recommendedNextAction, capability confidence, and navigation hints.

Agent resolves and reads the exact owner

file_outline resolves symbol ownership and read_file opens the exact indexed symbol or a bounded source span from the same Publication.

Agent checks callers and callees

call_graph traverses the caller/callee directions supported by relationship evidence qualified for that language and Publication.

Agent handles unsafe state explicitly

Stale Publications, unsupported call semantics, ambiguous targets, and incomplete indexing return explicit readiness or capability guidance.

Agent edits with verified context

Satori does not edit code. It gives the coding agent enough repo evidence to avoid blind changes.