basemind

# basemind

> The context and communication layer for coding agents. basemind turns any repository into an
> always-current map of its code, documents, git history, and shared memory — served over MCP — so
> agents answer from structure and search instead of spending their context window on `grep` and file
> reads. One server also gives a team of agents a shared channel to coordinate while they work.

basemind is a pure-Rust, content-addressed, Fjall + LanceDB-backed index. It pre-parses a repo with
tree-sitter across 300+ languages and exposes a structured code map (outlines, symbol search,
references, callers, call graphs, implementations), semantic + keyword code search, git history +
blame at symbol resolution, full-text + semantic document search over 90+ formats (with OCR and
cross-encoder reranking), shared per-repo memory, on-demand web crawl, and an agent-to-agent comms
broker. Every tool returns paths, line numbers, and signatures — not file bodies — so a structural
answer costs a fraction of the tokens of reading source. The operating rule for agents: **basemind
first, shell/grep/git fallback.**

## Documentation

- [Documentation site](https://basemind.ai): Guides, capability deep-dives, MCP tool + CLI reference, architecture, and performance.
- [How it works](https://basemind.ai/concepts/how-it-works/): One scan, then instant answers held in memory.
- [Token economy](https://basemind.ai/concepts/token-economy/): Why structural answers cost a fraction of the tokens of reading files.
- [MCP tool reference](https://basemind.ai/reference/mcp-tools/): Every tool, its parameters, and matching semantics.
- [CLI reference](https://basemind.ai/reference/cli/): The scriptable CLI, at parity with the MCP tools.
- [Installation](https://basemind.ai/start/installation/): Plugin, MCP server, and standalone CLI setup.
- [Configuration](https://basemind.ai/reference/configuration/): `.basemind/basemind.toml`, feature flags, and layered overrides.
- [Hosted llms.txt](https://basemind.ai/llms.txt): Always-current docs map, generated from the site (this repo-root file is the hand-curated project map).
- [llms-full.txt](https://basemind.ai/llms-full.txt): The complete documentation as a single file, for LLM ingestion.
- [GitHub repository](https://github.com/Goldziher/basemind): Source, issues, and releases.
- [README](https://github.com/Goldziher/basemind/blob/main/README.md): Installation, feature overview, how it works, and performance.
- [CHANGELOG](https://github.com/Goldziher/basemind/blob/main/CHANGELOG.md): Release history and schema-version bump notes.

## Capabilities

- [Code intelligence](https://basemind.ai/capabilities/code-intelligence/): Find where code is defined and used — symbol search, file outlines, references, callers, call graphs, implementations, dependents, go-to-definition, fuzzy path search, indexed regex (one `code` tool: modes `symbols`, `outline`, `references`, `callers`, `implementations`, `find`, `dependents`, `definition`, `grep`; call graphs live on the `graph` tool, mode `calls`).
- [Semantic code search](https://basemind.ai/capabilities/code-search/): Search code by meaning, term, or symbol over indexed chunks — hybrid RRF fusion, vector KNN, or BM25, with optional reranking (`code` modes `semantic` and `chunk`; requires `--features code-search`).
- [Git intelligence](https://basemind.ai/capabilities/git-intelligence/): Recent commits, commits touching a path, per-line and per-symbol blame, structural diffs across revisions, churn ranking, symbol history, and full-text search over commit authors + messages (one `git` tool: modes `recent`, `touching`, `blame`, `blame_symbol`, `diff`, `diff_outline`, `churn`, `symbol_history`, `search`).
- [Document search](https://basemind.ai/capabilities/document-search/): Semantic + full-text search over PDFs, Office, HTML, email, and images (OCR) plus scraped/crawled web pages, with reranking, keyword and named-entity filters, and per-document summaries (`memory` mode `documents`).
- [Web crawl](https://basemind.ai/capabilities/web-crawl/): Fetch, crawl, and map web pages into the document index (one `web` tool: modes `scrape`, `crawl`, `map`).
- [Shared memory](https://basemind.ai/concepts/memory/): Per-repo key/value + semantic memory that agents read and write, shared across clones of the same repo (one `memory` tool: modes `put`, `get`, `search`, `list`, `audit`).
- [Agent comms](https://basemind.ai/concepts/agent-comms/): Coordinate with other agents via explicit threads (per-repo, path-scoped, or subject-based), a per-agent inbox, and two-tier messages. Advisory worktree claims for collision detection (one `agents` tool: modes `thread_start`, `post`, `history`, `join`, `leave`, `members`, `inbox`, `message`, `list`; plus the `workspace` tool's `worktrees` / `claim` modes).
- [Agent shells](https://basemind.ai/capabilities/agent-shells/): Spawn headless terminal sessions agents can drive — send stdin, capture the screen, list, kill, and broadcast (one `shell` tool: modes `spawn`, `send`, `capture`, `kill`, `list`, `broadcast`; requires `--features shells`).

## Skills

- [basemind](https://github.com/Goldziher/basemind/blob/main/skills/basemind/SKILL.md): Umbrella overview of the whole indexed context layer and tool-routing table.
- [basemind-code-search](https://github.com/Goldziher/basemind/blob/main/skills/basemind-code-search/SKILL.md): Navigate code without reading files.
- [basemind-git-history](https://github.com/Goldziher/basemind/blob/main/skills/basemind-git-history/SKILL.md): Git intelligence over the index.
- [basemind-documents](https://github.com/Goldziher/basemind/blob/main/skills/basemind-documents/SKILL.md): Document RAG and web ingestion.
- [basemind-comms](https://github.com/Goldziher/basemind/blob/main/skills/basemind-comms/SKILL.md): Agent coordination via explicit threads.
- [basemind-cli](https://github.com/Goldziher/basemind/blob/main/skills/basemind-cli/SKILL.md): The scriptable CLI surface, at parity with the MCP tools.
- [basemind-scan](https://github.com/Goldziher/basemind/blob/main/skills/basemind-scan/SKILL.md): Build or refresh the index with `basemind scan`.
- [basemind-doctor](https://github.com/Goldziher/basemind/blob/main/skills/basemind-doctor/SKILL.md): Diagnose and recover basemind when it isn't working.
- [basemind-stats](https://github.com/Goldziher/basemind/blob/main/skills/basemind-stats/SKILL.md): Session usage dashboard and estimated tokens saved.
- [multi-agent-room](https://github.com/Goldziher/basemind/blob/main/skills/multi-agent-room/SKILL.md): Orchestrate a team of named subagents in a shared room.

## Optional

- [crates.io](https://crates.io/crates/basemind): Install the Rust binary with `cargo install basemind`.
- [npm](https://www.npmjs.com/package/basemind): Node wrapper that downloads the prebuilt binary.
- [PyPI](https://pypi.org/project/basemind/): Python wrapper that downloads the prebuilt binary.
- [Config schema](https://github.com/Goldziher/basemind/blob/main/schema/basemind-config-v1.schema.json): JSON Schema for `.basemind/basemind.toml`.
- [CLAUDE.md](https://github.com/Goldziher/basemind/blob/main/CLAUDE.md): Project rules, crate layout, and conventions for agents working in the repo.
- [Cargo.toml](https://github.com/Goldziher/basemind/blob/main/Cargo.toml): Crate manifest and feature flags (`documents`, `memory`, `crawl`, `comms`, `shells`, `code-intel`, `code-search`, `full`).