Skip to content

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.

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.

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.

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.

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.

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.

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.

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.

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