How it works
basemind turns your project into an always-current map through two simple steps: a one-time parallel scan that reads everything, then a background daemon that answers questions in milliseconds. When files change, it updates only what’s touched — no re-read of the whole codebase.
The scan
Section titled “The scan”basemind scan reads your project once, in parallel. It maps your code with
tree-sitter across
300+ languages and extracts text from
your documents using xberg, then saves the results to a local
global cache (never inside your repo).
This happens once at setup, then incrementally as you work: when you open a file editor, basemind detects the change and re-indexes only that file.
Structure extraction
Section titled “Structure extraction”The scan builds a structural index: for each file, it extracts the symbols (functions, classes, types), their signatures, their line/column positions, and what they call — all without running the code. This is tree-sitter’s job: it parses source code into an abstract syntax tree (AST), and basemind runs hand-tuned queries over that tree to find the pieces you care about.
Document extraction
Section titled “Document extraction”If you have PDFs, Office documents, HTML, email, or images, basemind extracts their text (with OCR for images and scanned PDFs in the published binaries) and indexes their content for semantic search.
The server
Section titled “The server”basemind serve is a thin stdio relay: it makes sure the machine-global daemon is up and
forwards your client’s MCP traffic to it. The daemon is the single writer of the index and hosts
the read side for every session. Code questions answer in milliseconds: “Where is parseQuery
defined?”, “What calls processFile?”, “Show me the outline of this file.”
Each tool call resolves to a lookup in the index, not a re-read of the project. Memory use is
bounded rather than proportional to the repo: decoded outlines live in an LRU cache capped by
[resources] max_map_cache_mb, symbol and import names in a compact resident term index, and
callee and trait names in small resident dictionaries, with the rest read from the on-disk index
on demand. code_refs lookups are scanned inside the daemon, so a
session holds no copy of the call index. See Memory and resources.
Re-scans
Section titled “Re-scans”When you edit code, basemind detects the change and re-scans the affected file. Other files stay unchanged. This means keeping the index fresh as you work costs far less than the initial scan.
Index lifecycle and freshness
Section titled “Index lifecycle and freshness”basemind serve answers the MCP handshake immediately and warms the code map into memory in the
background, so a client never blocks waiting for a large repo to load. index_status reports
warming (still loading) and, once done, warm_ms; a first-time index build similarly reports
indexing / index_build_ms.
While the server isn’t fully ready, index_status and every code-map read tool may carry a
notice object — { state, message, retry } — instead of (or alongside) their normal result:
state |
Meaning | retry |
|---|---|---|
warming_up |
Loading an existing index into memory. | true |
building_index |
Indexing from scratch (no index for this workspace yet). | true |
rescanning |
Incremental rescan after a file change; results are usable but may be stale. | false |
empty_index |
Nothing is indexed yet: run index_rescan or basemind scan. |
— |
Treat an empty or partial result carrying a notice as “retry shortly,” not “no matches” — poll
index_status (or just retry the call) until the notice clears.
Code versus documents
Section titled “Code versus documents”The code map holds code only. Prose, data and configuration files (Markdown, reStructuredText,
AsciiDoc, JSON, YAML, TOML, XML, CSV, INI, .env, diffs and the like) are routed to the document
tier instead: chunked, embedded and searched as text with docs_search, never listed as
symbols. That keeps code_outline, code_symbols and code_grep free of README headings and
config keys. [documents] include / exclude and mime_allowlist decide which of those files are
indexed; with the documents feature compiled out they fall back to the code map.
Markdown notes and Obsidian vaults are therefore searched by meaning and by keyword.
Vector search and memory
Section titled “Vector search and memory”Search and memory (semantic search over documents and stored notes) are powered by
LanceDB, an in-process vector database. When you call
docs_search, basemind compares your query against the embeddings of every document chunk
and returns the closest matches by meaning, not just by keywords.
The shared memory store works the same way: agents can write notes with memory_save, and other
agents search that memory with memory_search using semantic similarity.
flowchart LR A(["Coding agent"]) R["Your project<br/>code · documents · git"] S["basemind scan<br/>map code & read documents"] D[("global cache<br/>local index")] V["basemind serve<br/>answers questions"] R --> S --> D --> V A <-->|asks questions| V classDef accent fill:#2563eb,stroke:#1e40af,color:#fff class S,V accent