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

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.

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.
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.
Web crawl	Fetch a page or follow links from a starting URL; results join the document search.
Agent comms	A shared chat for agents on the same repo: rooms they auto-join, direct messages, and orchestration of many named subagents.
Agent shells	Let agents open, type into, and watch terminal sessions in the background.
Token saving	Hand an agent a file’s outline instead of its full text, pull back only the one function it needs, diff a re-read instead of resending it whole.

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

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

• outline a file before you open it. Read only the exact span you need from the outline, not the whole file.
• search_symbols instead of grep. It matches on indexed symbol names and returns path:line, skipping comment and test noise.
• find_references / find_callers instead of grepping call sites. Indexed call edges, not text matches.
• recent_changes / blame_symbol / diff_outline instead of git log / git blame. History at symbol resolution, in tens of microseconds.
• 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.

Two jobs from one server

1. Indexed context layer

basemind scan reads your project once, in parallel, and saves the result to a local cache in .basemind/. After that, basemind serve keeps the map in memory and answers questions instantly — no re-reading the project for each one. When files change, it updates only what changed.

Outlines are held in RAM. Git history is precomputed and indexed. Documents are vectorized once and cached. The result: most code questions answer in under a millisecond, call-graph searches in a few milliseconds, and document searches in around 200 ms.

2. Multi-agent comms

A single shared service in the background lets agents talk to each other — even across different tools and different repos on the same machine. Agents join rooms automatically based on what they’re working on, 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).

How to use it

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

InstallationThree ways to run basemind — pick your tool.

QuickstartScan a repo and ask your first questions.