Architecture / Publication authority

Satori Architecture

Satori gives MCP-compatible coding harnesses a code-intelligence layer: intent retrieval, exact symbols, AST-derived structural evidence, qualified calls, and bounded source. One coherent Publication keeps every answer on the same repository generation.

Symbol + AST-derived intelligence Offline after install Atomic Publications Nine CALLS v0 languages Fail-closed navigation

System Overview

Agent requests route through a fixed seven-tool registry. The MCP runtime acquires the current Publication, validates freshness, and keeps each request pinned to that immutable generation. Indexing builds the next Publication off to the side and swaps it into authority only after its search, symbol, structural, and relationship state is complete.

Agent Claude / Codex / OpenCode

request

Tool Registry Seven 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 seven 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.

`@zokizuan/satori-core`

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

`@zokizuan/satori-mcp`

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

`@zokizuan/satori-cli`

Installs managed client config, conditional client guidance, the first-party skill, and optional Codex session reminders.

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 @zokizuan/satori-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, and OpenCode config differences live in the installer and its tests, not in user-maintained snippets.

Agent-Safe Tool Surface

Satori exposes exactly seven public MCP tools. They cover repository discovery, lifecycle, search/pagination, structural navigation, bounded source reads, and call-graph context. Every tool is read-only with respect to source code; only 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.

`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.

`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.

Lifecycle

`manage_index`

Supports create, sync, status, reindex, 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 Runtime/index contract changed; rebuild before serving as current.

manage_index(reindex)

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 }

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 stable: score descending, file path ascending, start line ascending, symbol label ascending, then symbol id ascending.

Hybrid Retrieval + Reranking

Dense and BM25 hits merge through reciprocal rank fusion, then LateOn reranks a bounded candidate set. Exploratory six-repo tuning reached 0.5046 MRR versus 0.2900 without reranking across 36 owner-discovery tasks; that is tuning evidence, not a held-out guarantee.

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.

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.