Skip to content

Introduction

basemind turns any repository into an always-current map of its code, documents, history, and memory — so agents answer from structure and search instead of burning their context window on grep and file reads, and gives a team of agents a shared channel to coordinate while they work.

One server does both.

When an agent needs to understand code, it has three expensive options:

  1. Read whole files — costs hundreds of tokens per file, and most of a file is irrelevant to the question.
  2. Shell out to grep — and wade through comment noise, test file matches, and lines torn from context.
  3. Navigate back and forth — opening one file to find a call, opening another to find the definition, parsing manually to understand the shape.

basemind does all three jobs in milliseconds, and answers with paths, line numbers, and signatures — a fraction of the tokens, and no manual parsing.

Once an agent knows a symbol lives at src/parser.rs:142, it can read_file that exact span instead of the whole file. Once it knows what calls a function, it stops guessing. Once it knows what changed yesterday, it stops reading git logs.

Capability What it does
Code intelligence Find where things are defined, what calls what, who implements what, and how calls chain — across 300+ languages.
Git intelligence Ask what changed recently, who last touched a function, where the churn is, how a file’s structure differs across commits, and search commit authors + messages.
Document search Search PDFs, Office files, HTML, email, and images by meaning — with built-in text extraction and OCR, no extra setup (a source build needs the documents-ocr Cargo feature for OCR).
Code search Find source code by meaning, term, or symbol — vector KNN, native BM25, or exact-symbol lanes, with optional reranking. Returns pointers; fetch bodies on demand.
Shared memory Per-repo memory agents can write to and search; clones of the same repo share it, unrelated repos stay separate.
Agent comms A shared chat for agents on the same repo: rooms they auto-join, direct messages, and orchestration of many named subagents.
Token saving Hand an agent a file’s outline instead of its full text, and pull back only the one function it needs.

The operating rule: basemind first, shell/grep/git fallback

Section titled “The operating rule: basemind first, shell/grep/git fallback”

basemind is built on one discipline: prefer structure over content.

  • code_outline a file before you open it. Then code_read only the symbol or span you need, not the whole file.
  • code_symbols instead of grep. It matches on indexed symbol names and returns path:line, skipping comment and test noise.
  • code_refs instead of grepping call sites. Indexed call edges, not text matches.
  • git_log, git_blame and git_diff instead of git log / git blame / git diff. History at symbol resolution, in tens of microseconds.
  • index_rescan after you edit code, not a server reconnect. Optionally limit it to the files you touched.
  • Do not re-read a file basemind already mapped. If the outline answered the question, stop.

basemind scan reads your project once, in parallel, and forwards the result to a background daemon that manages a machine-global cache under ~/.local/share/basemind/. All repos/worktrees on one machine share this cache. After scanning, basemind serve relays your client to that daemon, which answers from the index it already holds — no re-reading the project for each question. When files change, only what changed is updated.

Decoded outlines sit in a bounded in-memory cache, symbol and import names in a compact resident index, and the rest in an on-disk index. Git history is precomputed and indexed. Documents are vectorized once and cached. The result, measured in-process on a 74k-file monorepo: an outline in about a millisecond (p50), symbol, reference and caller lookups in 1–5 ms, and document searches in roughly 100–260 ms (p50–p95). Smaller repos are faster. See Performance.

A single shared background daemon lets agents coordinate — even across different tools and repos on the same machine. Agents join threads explicitly by subject, scope, or membership, and each has a personal inbox. Messages come in two parts: a short headline (cheap to skim) and the full body (fetched only when an agent wants to read it). The daemon also tracks worktrees and branches for optional collision detection.

Pick a plugin (recommended — it sets up everything for you), or run it as an MCP server or standalone CLI.