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.
The problem basemind solves
Section titled “The problem basemind solves”When an agent needs to understand code, it has three expensive options:
- Read whole files — costs hundreds of tokens per file, and most of a file is irrelevant to the question.
- Shell out to grep — and wade through comment noise, test file matches, and lines torn from context.
- 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.
What you get
Section titled “What you get”| 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_outlinea file before you open it. Thencode_readonly the symbol or span you need, not the whole file.code_symbolsinstead of grep. It matches on indexed symbol names and returnspath:line, skipping comment and test noise.code_refsinstead of grepping call sites. Indexed call edges, not text matches.git_log,git_blameandgit_diffinstead ofgit log/git blame/git diff. History at symbol resolution, in tens of microseconds.index_rescanafter 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.
Two jobs from one server
Section titled “Two jobs from one server”1. Indexed context layer
Section titled “1. Indexed context layer”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.
2. Multi-agent comms
Section titled “2. Multi-agent comms”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.
How to use it
Section titled “How to use it”Pick a plugin (recommended — it sets up everything for you), or run it as an MCP server or standalone CLI.