# 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: top-level `status`, `rescan`, `cache`, `delta`, `checkpoint`, `detect-waste`, `doctor`, `completions`, documented exit codes (0 ok, 1 error, 2 usage, 3 busy, 4 daemon unreachable, 130 interrupted), and `--format json|toon`.
- MCP resources: `basemind://status`, `basemind://repo/map`, `basemind://outline/{path}`, `basemind://memory/{key}`.
- [Installation](https://basemind.ai/start/installation/): Plugin, MCP server, and standalone CLI setup.
- [Configuration](https://basemind.ai/reference/configuration/): `basemind.toml` (repo root or `.config/`), scan and document scoping, per-grammar `[languages]` overrides, the credential exclude floor, operator trust grants (`BASEMIND_ALLOW_*`), daemon caps (`BASEMIND_DAEMON_MAX_*`), 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 `outline`, `symbols`, `grep`, `files`, `find`, `definition`, `references`, `callers`, `implementations`, `dependents`, `expand`; the `graph` tool adds `calls`, `neighbors`, `path`, `subgraph`, `communities`, `map`, `export`, `display` and `open`). The code map is code only: Markdown, JSON, YAML, TOML and other prose/data/config files are document-tier content, searched with `memory` mode `documents` (`files` and `find` list documents too; `outline`, `grep` and `symbols` do not).
- [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 `status`, `recent`, `touching`, `by_path`, `blame`, `blame_symbol`, `diff`, `diff_outline`, `churn`, `symbol_history`, `search`, `show`).
- [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`, `list`, `search`, `delete`, `audit`, plus `documents`, `mine`, `proposals`, `accept`, `reject`).
- [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 `register`, `list`, `thread_start`, `thread_list`, `join`, `leave`, `members`, `add_member`, `remove_member`, `archive`, `post` (with an optional `idempotency_key` for safe retries), `history`, `message`, `inbox`, `ack`, `wait`, `cleanup`, `status`; plus the `workspace` tool's `workspaces` / `worktrees` / `branches` / `claim` / `release` 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.toml`.
- [.ai-rulez](https://github.com/Goldziher/basemind/tree/main/.ai-rulez): Project rules and skills for agents working in the repo.
- [Architecture](https://github.com/Goldziher/basemind/blob/main/docs/ARCHITECTURE.md): How the scanner, index, daemon and MCP surface fit together; [upgrading](https://github.com/Goldziher/basemind/blob/main/docs/UPGRADING.md) and the [ADRs](https://github.com/Goldziher/basemind/tree/main/docs/adr).
- [Benchmarks](https://github.com/Goldziher/basemind/blob/main/benchmarks/README.md): `basemind admin eval`, the retrieval-quality and token-savings harness, with measured results.
- [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`).
