Droste

Droste

An expanding code space. A fixed token window.

Search your local code graph, then zoom from a map to structure and source. The new explore interface keeps its entire response inside a measured token budget, including metadata, and reuses unchanged views the client still retains. Find definitions, inspect static references and verify source freshness.

Local-first · progressive zoom · measured tokens · CLI + MCP

*Explore the FastAPI code galaxy in motion. Watch the video or open the interactive galaxy.*

Code galaxy · Token zoom demo · Quickstart · Exploration · MCP

---

Quickstart

Install v1.3.0 from PyPI or GitHub Releases. See release status.

# Windows

python -m pip install --upgrade droste-memory

macOS / Linux

python3 -m pip install --upgrade droste-memory

droste index . # index the current repo droste view # open the fractal galaxy in your browser

Install once, then index and view. droste view opens a full-screen, zoomable map of your code — scroll to dive from the project star into folder orbits, down to the individual functions and their indexed relationships.

Need it for an agent instead of your eyes?

droste explore "checkout flow" --tokens 1500

Use returned node IDs as --focus and choose --level map, structure or source to navigate the same region at different detail. used measures the complete compact response under the selected tokenizer. Source bodies downgrade explicitly when they cannot fit. Prepare the small token vocabularies once with droste explore --prepare-tokenizers for later offline use. See the workflow, receipts and measured limits. The older droste context --budget interface still budgets characters.

For everyday code investigation:

droste check                         # verify source hashes and index coverage

droste find calculate # find symbol IDs, paths and line numbers droste references calculate --direction both droste references helper --file src/math.py --direction callers --depth 3 droste watch . # refresh after additions, edits, renames or deletions

references returns candidates for ambiguous names; choose a file or symbol ID instead of guessing. Python links include the call expression and source line. Other language links report their heuristic resolution method. check exits with status 1 for stale, partial or unverifiable indexes. Context responses warn about stale/partial coverage using a quick size/mtime check; check additionally verifies SHA-256 hashes. Run it before relying on an old index.

Indexing respects nested .gitignore rules and a project-root .drosteignore (Git ignore syntax; applied last). Symlinks, generated bundles, dependency directories and Droste's own storage are excluded. Use an explicit --db per project when running independent writers. watch batches root refreshes and reuses unchanged extraction/embeddings; view remains a snapshot, so reopen it to see a refreshed graph.

Running droste with no arguments prints the command palette:

                  .-----------------------.

.----' | '----. .---' .-----+-----. '---. .' .----' | '----. '. / .---' .---+---. '---. \ / .-' .-' | '-. '-. \ | .' .-' .---+---. '-. '. | | / .' .' | '. '. \ |

\ '-. '-. | .-' .-' / \ '---. '---+---' .---' / '. '----. | .----' .' '---. '-----+-----' .---' '----. | .----' '-----------------------'

DROSTE-MEMORY // RIGID FRACTAL RADIAL LAYOUT Local Graph Engine v1.3.0-Alpha-Sharded

Commands droste index [--reset] droste status droste zoom droste context [query] --budget 1500 droste explore [query] --tokens 2000 --level map|structure|source droste mcp

Fast path: droste context hub_core --budget 1000 | clip

---

Why it's different

Droste combines lexical and semantic retrieval with a static code graph and an interactive map. A graph can bring callers and callees into context even when they share few words with the query. Other tools also offer graph-based MCP retrieval; see the dated ecosystem review.

Droste focuses on a small Python CLI, budgeted context, and visual exploration. The graph is a static approximation: name matching and cross-language bridges can produce false positives and do not prove runtime behavior.

The useful building blocks are:

• Explainable static references. Python calls use lexical scopes, import aliases and explicit self/cls members. Dynamic receivers remain unresolved. Other languages use local/unique-name matching; ambiguous candidates are skipped.
• Cross-language bridges. Droste links across languages — app code to SQL functions/tables (.rpc('x'), .from('table')), to edge functions, and same-name handlers between any two languages. Your Dart/TS/Python frontend and your database stop being two separate worlds on the map.
• Visual exploration. Navigate files, symbols and indexed relationships in an interactive radial map.
• Zero-config and local. No cloud, no account, no API key. fastembed (ONNX, no torch) gives real semantics; a deterministic fallback keeps it runnable anywhere.

Polyglot: Python (AST) + tree-sitter for Dart, TypeScript/JavaScript, Go, Rust, Java, C#, C/C++, Kotlin, Swift, Ruby, PHP, SQL — symbols *and* edges.

Honest scope: the measured advantage is structural / causal retrieval. On

pure semantic "concept" queries it's competitive with a vector baseline, not a

leap. Cross-language bridges are strongest where the target is actually defined

in the indexed repo (e.g. SQL schema in your migrations).

---

Benchmarks

The public source validation uses pinned Requests and CPython revisions with manually labelled edge assertions. It currently passes 19 of 20 assertions: 15/16 expected edges found, 0/4 forbidden edges emitted. The missed edge is documented; this small corpus is not an agent-task benchmark or a comparison against competing products.

python eval/public_corpus.py --output public-results.json

The evaluation script compares structural retrieval against lexical and vector baselines, using caller/callee relations extracted from the same code as the reference. This measures graph-neighbor retrieval, not agent task completion or superiority over another product. Previous headline numbers are omitted until we publish a fixed public corpus, pinned revisions and complete result files.

python eval/comparative_eval.py --repos /path/to/public/repo --sample 60 --seed 7 --json results.json

Use the real embedding backend for semantic comparisons; the offline hash mode is deterministic but does not provide semantic similarity.

---

How it works

• Static graph. Python scopes and imports resolve named calls; tree-sitter supplies definitions/references for other supported languages. Their name-based links and cross-language DB/string bridges are heuristics, labelled in reference results. No runtime behavior or complete type resolution is implied.
• Hybrid seed. A query is matched by a normalized blend of lexical score and semantic cosine (fastembed bge-small-en-v1.5, 384-dim), then the graph expands the seed bidirectionally (callees and callers).
• Progressive explorer. explore budgets its complete response in reference tokenizer tokens, including metadata. Navigate map, structure and source by node ID; acknowledge exact retained views to avoid resending their bodies.
• Legacy context packer. context --budget is characters, with a minimum of 500. Full source, contracts or explicit source stubs fit that effective limit, including separators. That legacy interface does not promise tokenizer-specific counts.
• Sharded persistence. One shard per file under a database-specific .droste/ directory, blake2b dirty-tracking so a re-index rewrites only what changed; atomic file replacement with metadata written last. Multi-file updates are not transactions; use one writer per DB and re-index after an interrupted write.

---

Use it as an MCP server

Droste is a drop-in MCP server — an AI agent can call it as primary code memory instead of doing blind file reads. Add this to your client configuration file (e.g., Cursor, Claude Desktop, or Codex):

First install or upgrade to the current PyPI release:

# Windows

python -m pip install --upgrade droste-memory

macOS / Linux

python3 -m pip install --upgrade droste-memory

droste mcp --help

For Codex, add this to C:\Users\ \.codex\config.toml on Windows, or ~/.codex/config.toml on macOS/Linux:

[mcp_servers.droste]

command = "droste" args = ["mcp"] startup_timeout_sec = 120

Installed packages store their default database in %LOCALAPPDATA%/Droste on Windows, ~/Library/Application Support/Droste on macOS, or ${XDG_DATA_HOME:-~/.local/share}/droste on Linux. Source checkouts preserve their repository-local database. Set DROSTE_DB or pass --db to override. Existing databases inside an older installation are not moved automatically; point --db at the old file to continue using it, or re-index your source.

For explicitly offline operation, set DROSTE_EMBEDDING_BACKEND=hash. The default auto backend may download an embedding model on first use; code is processed locally. Hash mode trades semantic retrieval for deterministic, network-free embedding. droste view serves a snapshot; rerun it after indexing.

By default, droste mcp uses Droste's global local database. That is fine for quick use and small workflows. For serious multi-repo work, use one database per repository so each project has isolated memory and agents can safely re-index that project with reset=true.

The --db option is global, so keep it before mcp:

# Windows example

[mcp_servers.droste] command = "droste" args = ["--db", "C:/Users/you/AppData/Local/Droste/my-project/droste_memory_db.json", "mcp"] startup_timeout_sec = 120

# macOS / Linux example

[mcp_servers.droste] command = "droste" args = ["--db", "/Users/you/.local/share/droste/my-project/droste_memory_db.json", "mcp"] startup_timeout_sec = 120

For JSON-