Flagship independent systems project
Satori
A freshness-aware code map for AI coding agents, with exact evidence, BM25 and dense retrieval, owner-oriented navigation, bounded reads, and a fully local default runtime.
Repository snapshot
Satori
Local-first code mapping for AI coding agents.
- Commits
- 1,377
- MCP tools
- 7
- Default
- Local-first
Work done
Satori
Fast edits are cheap. Evidence before the edit is the scarce part.
- Problem: coding agents can move quickly from a weak search result to a confident edit, especially when repository context is stale, semantically noisy, or too broad.
- Decision: build a freshness-aware code map that combines exact lexical evidence, BM25, dense retrieval, owner-oriented navigation, and bounded source reads before the host agent edits anything.
- Proof: Satori now ships a fully local Potion + LanceDB runtime, seven public MCP tools, atomic searchable publications, managed installs for Codex/Claude Code/OpenCode, and repository-measured retrieval/agent-discovery evidence.
- Status: flagship independent system; local-first runtime is the default path and qualification work is ongoing.
What Satori is now
Satori turns a repository into a freshness-aware code map. An MCP-compatible agent can search by intent, inspect the real owner, follow nearby relationships, and read an exact symbol or bounded span instead of reconstructing the codebase from repeated broad file dumps.
The default Linux x64 / WSL2 path is local-first:
source repository
-> AST-aware source/navigation evidence
-> exact evidence + BM25 + dense retrieval
-> Potion Code 16M v2 embeddings
-> LanceDB publication
-> optional local LateOn reranking
-> owner-oriented groups + bounded readsNo model API key is required for that default runtime.
Connected deployments can still use Voyage Code 3 and LanceDB or Milvus/Zilliz. Existing Ollama users can select an explicit local embedding model. The important boundary is that provider choice changes model-specific vectors; it does not become the authority for source truth.
The public surface is seven tools
The original portfolio described a fixed six-tool surface. Satori has since added continuation for a frozen search result without rerunning retrieval.
| Tool | What it owns |
|---|---|
manage_index | create, sync, inspect, repair, reindex, clear |
search_codebase | freshness-aware hybrid search |
continue_search | disclose more from the same frozen result set |
file_outline | indexed symbols and exact spans in one file |
call_graph | advisory callers, callees, imports, exports |
read_file | bounded source span or exact indexed symbol |
list_codebases | known repositories and readiness/runtime state |
Satori intentionally has no write-capable MCP tool. The host environment still owns source edits.
Publication became a first-class contract
A search index is dangerous when “ready” only means some local metadata exists.
Satori now treats a publication as a complete generation that binds lexical/vector search state, navigation, relationship evidence, source observation, checkpoints, and receipts. Readers see the complete previous generation or the complete new one. Failed candidate work does not replace active search state.
Incremental sync embeds changed chunks and replaces the complete generation only when the new publication is ready. Missing, corrupt, stale, or incompatible authority fails closed to repair or reindex guidance.
That is a much stronger contract than the earlier “local snapshot + remote vector collection” model described in some older notes.
Measured on the Satori repository
The current repository publishes its own qualification evidence rather than borrowing model-card numbers.
A checksum-sealed local Potion + LanceDB run indexed 488 files and 10,830 chunks. The recorded warm-search p95 was 154.543 ms; zero-change synchronization p95 was 185.662 ms.
A separate exploratory two-task OpenCode comparison produced correct answers in both Satori and native file-discovery arms:
| Observation | Satori tools | Native grep / glob / read |
|---|---|---|
| Tool calls | 16 | 25 |
| Tool-output bytes | 76,113 | 96,801 |
| Agent wall time | 51.65 s | 96.04 s |
| Total model tokens | 46,767 | 46,759 |
That run is evidence of a shorter evidence route on those tasks, not a universal token or speed claim. It was one run per task, and total model-token usage was effectively unchanged.
Local-first changed the architecture
Making Satori work without a hosted embedding/vector dependency forced cleaner ownership boundaries.
Source-derived navigation has to remain useful even when model-specific state changes. A new embedding provider, vector dimension, backend, or projection can require a reindex without silently rewriting the old publication. Runtime ownership also has to prevent incompatible live clients from racing the same state root.
The result is less magical and more explicit: Satori can say which runtime is applied, which client owns it, whether the index is compatible, and what the agent should do next.
What I learned
The project started as “semantic search for coding agents.” That description is now too small.
The harder system is the evidence contract around search: source freshness, exact identifiers, lexical and semantic retrieval, publication atomicity, bounded disclosure, runtime compatibility, and a tool surface that tells the agent when it should stop guessing.
That is the part I now consider the product.
Related notes
- Why semantic code search is not enough for coding agents
- When index cleanup lies, agents make unsafe decisions
- Why MCP CLIs fail when stdout is treated like logs
- Why naive RAG fails for coding agents