basemind

Code — Tree-sitter outlines, symbol search, reference + caller + implementation graphs, call chains, git history per symbol, blame at symbol-level resolution.

Documents — Ingest + semantic search over PDFs, Office (Word/Excel/iWork), HTML, email, archives. Built-in OCR, layout detection, keyword + NER extraction, cross-encoder reranking. All ONNX bundled — no system install needed.

Memory — Per-repo scoped key-value + semantic vector storage. Clones of the same git origin automatically share memory; unrelated repos isolated.

Web — On-demand HTTP scrape + follow-link crawl. Pages chunk, embed, and land in the documents store under scope web:<host> for unified search.

basemind tools return paths, line numbers, and signatures — not file bodies — so a structural answer costs a fraction of the tokens of reading source. The plugin ships this as the agent's default operating discipline (carried in the MCP server instructions, the basemind skill, and the SessionStart hook):

• outline a file before opening it — then read only the span you need.
• search_symbols instead of grep/rg for a definition.
• find_references / find_callers instead of grepping call sites.
• workspace_grep instead of shelling out to ripgrep for regex over content.
• rescan after edits instead of reconnecting the server.
• Don't re-read a file basemind already mapped.

The plugin also ships a PreToolUse guard hook that reaches the agent at the moment it reaches for search: by default (BASEMIND_GUARD=nudge) it points Grep/Glob calls at the matching basemind tool, once per session. Set BASEMIND_GUARD=redirect to enforce it (the call is blocked with a pointer to the basemind tool) or BASEMIND_GUARD=off to disable.

The live statusline surfaces the payoff: estimated tokens saved vs a grep + read baseline.

Choose the path that fits your workflow. Both paths use the same on-disk index at .basemind/.

MCP (Model Context Protocol) runs the basemind server in-process and exposes all tools as in-session function calls. Zero config — install and start using tools immediately.

Run these two commands in order:

/plugin marketplace add Goldziher/basemind   # 1. register the marketplace
/plugin install basemind@basemind            # 2. install the plugin

Restart the session after installing. The basemind binary installs automatically on first use (via npx, uvx, or direct download with checksum verification) — no manual cargo install needed.

To enable the optional live statusline (showing context % and per-capability metrics), run /bm-statusline once. This is a one-time opt-in because Claude Code plugins cannot set the main statusline — it is a platform limitation. See the Statusline section for details.

cargo install basemind --features full --locked

Add to your MCP config:

{
  "mcpServers": {
    "basemind": {
      "command": "basemind",
      "args": ["serve"]
    }
  }
}

Each harness has setup instructions in the Installation section.

Use the standalone basemind CLI binary and the basemind-cli skill for query-driven exploration. Same index, same tools, different interface — faster for scripting and batch operations.

# Install the binary
npm install -g basemind    # or: pip install basemind, cargo install basemind, brew install Goldziher/tap/basemind
basemind scan               # index the working tree once

Then use the CLI:

basemind query outline path/file.rs           # inspect file structure
basemind query symbol "parseQuery"            # find symbol by name
basemind query references "processFile"       # find all call sites
basemind git blame-file src/main.rs           # show per-line blame
basemind cache stats                          # cache stats
basemind cache gc                             # reclaim orphaned blobs
basemind watch --no-serve                     # live re-index on file change (no MCP server)

Add the basemind-cli skill to route CLI commands efficiently. See the CLI command reference below for the full command surface.

Both paths share the same .basemind/ index and are safe to run alongside each other (the CLI opens the index read-only; basemind serve watches and incrementally updates in the background).

• MCP: Wired as in-session tool calls. Zero config. Best for interactive agent workflows.
• CLI: Scriptable, headless, CI-friendly. Best for batch queries, integration into non-MCP harnesses, and when you want to control the tool routing explicitly.

The choice is not binary — use MCP for interactive sessions and CLI for scripting in the same repo.

To enable the live statusline in Claude Code (MCP only), run /bm-statusline once. This is a one-time opt-in because Claude Code plugins cannot set the main statusline — it is a platform limitation, not a basemind choice:

• The plugin manifest has no statusLine field.
• A plugin-shipped settings.json honors only agent and subagentStatusLine; any statusLine key is ignored.
• Hooks communicate via stdout/stderr only — they cannot write to ~/.claude/settings.json.

/bm-statusline works because Claude (the agent) performs the settings edit on your behalf, writing an absolute path into ~/.claude/settings.json. After that it persists across sessions.

It renders two lines — a context line (model · output-style · dir · branch · context%) and the basemind line below it:

Opus · basemind · ⎇ main · 12% ctx
◆ basemind  ●  1,247 files · 23m ago  │  312 calls · 180 srch · 44 git · 12 docs  │  1.4M saved

The state dot is green (serve active / scan < 1 h), amber (idle or scan 1–24 h), or red (no serve and stale index). The second segment breaks activity down per capability — searches, git, docs, memory, web — showing only the buckets with calls today; the last segment is estimated tokens saved. Layout adapts to terminal width ($COLUMNS): the per-capability breakdown drops on narrow terminals. Override with BASEMIND_STATUSLINE=full|compact|minimal (default auto) or hide the context line with BASEMIND_STATUSLINE_CONTEXT=0.

What ripgrep does well: blazing-fast line matching. What it misses:

• Grep returns 50+ hits in docs, tests, comments, variable names — agent wastes context filtering noise.
• No scope awareness: parseQuery() and parseQuery string both match; semantic signals lost.
• Every query re-scans the disk; no pre-computed structures to leverage.

basemind: semantic-quality answers at grep speed via tree-sitter + indexed call sites.

What vector RAG does well: fuzzy document semantic search. What it misses:

• Pure embeddings lose exact structure — which function calls which, which class implements which interface.
• No line/column resolution — agent can't map vector hits back to code symbols.
• No git history integration — "what changed recently?" and "who wrote this?" require separate systems.

basemind: code structure + git history + vector memory + document search all in one, unified scope.

What these do well: generate code-map summaries. What they miss:

• Static snapshots — stale after the first edit.
• No semantic indexing — every lookup re-parses or re-scans.
• Human-focused output (markdown) instead of agent-facing structure (JSON tools).

basemind: live-updated index with sub-millisecond MCP tools, built for agents not humans.

What GitHub does well: repository-wide fuzzy text search. What it misses:

• Cloud-only — your code leaves the machine, latency is network-bound.
• No local-editor integration — agent can't query in-progress edits before commit.
• No cross-language polyglot support — each language's search tuned separately.

basemind: local-only, always-fresh index of your working tree, 300+ languages in one sweep.

Measured on Apple Silicon, release build, --features full, default eager_l2 = true. Cold filesystem cache adds ~50% to first scan; numbers below are warm steady-state.

The TypeScript compiler is the worst case — 81k files scanned in 22 seconds. Most real repos sit between tokio and ripgrep. Re-scans skip unchanged content hashes, so warm rescans on edited working trees are typically dominated by the changed-set size, not repo size.

Against the 81k-file TypeScript index:

basemind preloads L1 outlines into RAM on serve start, so code-map queries hit no disk. The Fjall LSM inverted index handles ref/caller/impl lookups without scanning blobs. Git tools track gix walk cost; Fjall-backed tools dominate only on enormous histories.

Full config lives at schema/basemind-config-v1.schema.json. Minimal example:

# .basemind/basemind.toml
file_watch_glob = "**/*.{rs,ts,tsx,py,go}"
eager_l2 = true

[documents]
enabled = true

Per-query MCP overrides:

{
  "query": "what does kreuzberg do?",
  "reranker_enabled": true,
  "reranker_preset": "bge-reranker-base"
}

Environment variables map mechanically: --llm-api-key ↔ BASEMIND_LLM_API_KEY. Every MCP tool accepts per-query overrides that win over file/env/CLI layers.

CLI commands mirror MCP tools, grouped by capability. Run with --json for machine-readable output.