basemind

In the session (not your shell), run in order:

/plugin marketplace add Goldziher/basemind
/plugin install basemind@basemind

Restart, then run /bm-statusline once to turn on the live statusline (a one-time step — see Statusline). Turn on auto-update for the basemind marketplace (Claude Code’s plugin manager): the plugin then tracks each new release automatically, and the launcher resolves the matching published release. Prefer to control timing? Update the marketplace regularly by hand instead.

codex plugin marketplace add Goldziher/basemind
codex plugin add basemind@basemind

In the app: open the Plugins sidebar and add basemind. The CLI and IDE share one config file. The generated plugin uses the matching published GitHub release, or a local BASEMIND_BIN override.

In Agent chat: /add-plugin basemind (once listed), or go to Dashboard → Settings → Plugins → Team Marketplaces → Import from Repo and point it at https://github.com/Goldziher/basemind.

git clone https://github.com/Goldziher/basemind
cd basemind
gemini extensions install ./plugin --skip-settings

Update later with gemini extensions update basemind.

droid plugin marketplace add https://github.com/Goldziher/basemind
droid plugin install basemind@basemind

copilot plugin marketplace add Goldziher/basemind
copilot plugin install basemind@basemind

Add to opencode.json (project) or ~/.config/opencode/opencode.json (global):

{ "plugin": ["basemind-opencode@latest"] }

/plugins install https://github.com/Goldziher/basemind

Kimi doesn’t support the comms auto-notifications, but the chat tools still work.

Load the plugin/ directory as an Agent Plugins 1.0.0 package. It contains plugin.json, mcp.json, and ten public skills. Copilot shares this portable layout. The MCP launcher downloads the matching published basemind binary, or uses BASEMIND_BIN for a local build.

Install the program first. Install the locally generated wheel into the same Python environment Hermes runs in, then enable the plugin:

git clone https://github.com/Goldziher/basemind
cd basemind
uv build --wheel --out-dir dist/hermes plugin/.hermes/package
python -m pip install --force-reinstall dist/hermes/basemind_hermes_plugin-0.29.3-py3-none-any.whl
hermes plugins enable basemind

Restart Hermes. The plugin registers ten skills, six slash commands, scoped comms notifications, and basemind_call, which bridges the local MCP server’s nine domains and returns JSON text. The binary must be on PATH. Comms notifications are best-effort. You can also configure mcp_servers.basemind with command: basemind and args: [serve] for direct domain tools.

PyPI version 0.29.3 predates the skill-registration fix and MCP bridge. Use the source wheel above until a newer release includes these changes; reinstalling that published version will not add them.

Antigravity uses a shared MCP config — install the program, then add the generic MCP block. If you already use the Gemini extension, agy plugin import gemini brings it across.

Install the basemind program first, then install the Pi package:

pi install git:github.com/Goldziher/basemind

The package includes ten skills and a native extension that loads basemind context at session start and after compaction. Pi runs basemind through its shell tool using the CLI. No MCP bridge or binary is included. Add -l to save the package in the current project’s configuration.

The next release adds these resources to the existing basemind-opencode npm package. After that release, use pi install npm:basemind-opencode for registry installation and Pi package-catalog discovery. Both installation paths carry the same extension and skills.

• Claude Code — claude mcp add basemind -- basemind serve (add --scope user for all projects; the -- is required). Or commit a .mcp.json at the repo root with the block above.
• Cursor — put the block above in .cursor/mcp.json (project) or ~/.cursor/mcp.json (global).
• Windsurf — ~/.codeium/windsurf/mcp_config.json (or Cascade → MCP servers → manage), then Refresh.
• Codex — codex mcp add basemind -- basemind serve, shared by the CLI and IDE.
• Gemini CLI — gemini mcp add basemind basemind serve, or the block above in ~/.gemini/settings.json.
• GitHub Copilot CLI — /mcp add in-session, or ~/.copilot/mcp-config.json with "type": "local" and "tools": ["*"].
• Factory Droid — droid mcp add basemind "basemind serve", or ~/.factory/mcp.json.
• Cline — MCP Servers icon → Configure → add the block above.
• Continue — .continue/mcpServers/basemind.yaml with command: basemind, args: [serve].
• OpenCode (without the plugin) — opencode.json under key mcp, with command as an array ["basemind", "serve"].
• Hermes — mcp_servers.basemind in ~/.hermes/config.yaml (YAML: command: basemind, args: [serve]). For helper skills and notifications, install the source wheel and enable the plugin as described in the Hermes installation section.
• Any other tool — point it at the command basemind with the argument serve.

Run /bm-statusline once. This is a one-time step because Claude Code doesn’t let plugins set the main statusline themselves — so basemind asks the assistant to make the one-line settings change on your behalf, and it sticks from then on.

It shows two lines:

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

The dot is green when basemind is live and fresh, amber when idle, red when stale. The middle shows activity by type, then tokens saved, then unread messages. Adjust with BASEMIND_STATUSLINE=full|compact|minimal, or hide the top line with BASEMIND_STATUSLINE_CONTEXT=0.

basemind scan reads your project once, in parallel. It maps your code with [tree-sitter] (across [300+ languages][tslp]) and pulls text out of your documents with [xberg], then saves the result to a global cache under the XDG data directory, keyed by workspace — nothing is written into your repo. After that, the background daemon keeps the map in memory (one shared copy per workspace) and answers questions instantly — no re-reading the project for each one; basemind serve is a thin stdio relay to it. When files change, it updates only what changed. The daemon is the sole writer to that cache, so multiple sessions on the same repo (or on different worktrees of it) all read and write concurrently instead of one falling back read-only. See Global cache & the daemon below.

Navigation is scope- and import-aware for JavaScript/TypeScript, Python, and Java: basemind resolves each use to the definition it actually binds to, so a shadowed local isn’t confused with an import and code mode definition lands on the right target (including across files for imports). Every other language still gets fast tree-sitter scope binding. Precise Python/Java resolution runs GitHub stack-graphs-style .tsg name-binding rules via an in-tree engine (crates/), with no per-language LSP server.

Resolution refines, but never shrinks, a result set. code mode callers reports every call site whose callee matches the name — the same sound floor mode references uses — and marks each hit resolved when resolution proved it binds to that definition (resolved_total counts them). It deliberately does not return only the resolved subset: resolution cannot see through a module-object import (from pkg import mod then mod.f()) or an unresolvable path alias, so filtering to it would drop real callers and report the remainder as complete. Filter on resolved when you want precision; trust total when you need completeness.

The code map is code only. Prose, data and config files — Markdown, reStructuredText, AsciiDoc, vimdoc, CSV, JSON, YAML, TOML, INI, XML, .properties, .env, diffs, .gitignore/.gitattributes and Fluent — go to the document tier instead: they are chunked and searched as text with memory mode documents (gated by [documents] include / exclude), and no longer show up as symbols in code modes outline, symbols and grep. files and find still cover them, labelled by grammar name or extension. An existing index migrates on its next scan. A build without the documents feature keeps the old behaviour, where those files are outlined as code.

Search and memory are powered by a vector store ([LanceDB]).

The daemon answers the MCP handshake immediately and warms the code map into memory in the background, so a client never blocks waiting for a large repo to load. The status tool reports warming (still loading) and, once done, warm_ms; a first-time index build similarly reports indexing / index_build_ms.

While the server isn’t fully ready, status and every code-map read tool may carry a notice object — { state, message, retry } — instead of (or alongside) their normal result:

Treat an empty or partial result carrying a notice as “retry shortly,” not “no matches” — poll status (or just retry the call) until the notice clears.

Index state lives under a single global cache — ~/.local/share/basemind/ on Linux, ~/Library/Application Support/basemind/ on macOS (override with BASEMIND_DATA_HOME) — keyed by workspace, never inside your repo. The content-addressed blob store is machine-wide too: identical file content scanned from different repos or worktrees is extracted and stored once.

A new linked worktree’s working view is seeded from a sibling checkout’s index with a copy-on-write clone, so its first scan only touches files that differ. Only the view is cloned: the vector store is not, so the seeded worktree’s first scan rebuilds its vector rows from the cached blobs without re-embedding. A sibling whose workspace lock is held (a daemon or another scan is writing it) is not a seed source, and neither is one too large to copy on a filesystem without reflinks; the new worktree then scans from scratch. Set BASEMIND_NO_SEED=1 (any non-empty value other than 0) to opt out.

Linked worktrees share one git-history index per clone. A worktree whose HEAD descends from the indexed head appends the new commits; one that diverges leaves the index alone and answers history queries by walking git directly (correct, just slower), rather than wiping and rebuilding it on every worktree switch. The first build may come from any worktree.

Memory is bounded by design:

• [resources] max_footprint_mb (auto by default) is a best-effort ceiling on the process footprint. The scan processes files in bounded chunks and pauses between them while over the ceiling; if it is still over after five seconds it halves its chunk size and worker count and carries on, then widens again once memory clears. A large-file parse is likewise admitted anyway after five seconds. Document extraction is admitted exclusively: over the ceiling exactly one document runs at a time (an otherwise idle process is admitted immediately), and a document whose header-derived working-set estimate exceeds the whole ceiling is skipped and counted as too large.
• ONNX Runtime runs on the CPU provider by default (onnx_provider = "cpu"): on macOS the platform default, CoreML, measured 7.6 GB resident after embedding one 2 KB SVG against 0.8 GB on CPU. In every basemind process ONNX has no memory-pattern planning and no retained CPU arena, which otherwise grow to the largest batch seen and never shrink. Intra-op threads are the auto embed-thread count (max(2, logical CPUs / 4)), or 2 in the daemon, which also drops its resident embedding models once the last concurrent embedding pass ends; the next pass reloads them.
• Precise Python/Java resolution abandons a file past 600,000 builder steps, 4,096 stitching phases (about a million path extensions), 50,000 partial paths or 3 seconds, and runs at most two stack-graph builds at once. The stitcher checks those budgets every 256 path extensions, not once per phase, so a pathological file cannot grow between checks.
• On macOS the allocator (mimalloc) heap is tagged as application memory (Mach VM tag 254), so footprint, vmmap and Activity Monitor no longer report it as IOAccelerator “GPU” memory.

A workspace root must be a project: a git repository, or a directory containing a basemind config (basemind.toml at the root, or under the .config/ convention). Anything else is refused, because basemind opens a root read-write and indexes every file beneath it — so an accidentally inherited root (/, your home directory, or wherever an MCP host happened to start) would become a whole-filesystem scan. Run basemind init to mark a directory you do want indexed, or set BASEMIND_ALLOW_ANY_ROOT=1 to skip the check. A filesystem or volume root is refused unconditionally and cannot be overridden.

A single background daemon per machine is the sole writer to that cache and hosts the MCP server: basemind serve is a thin stdio relay that ensures the daemon is up and pumps bytes to it, so N sessions on the same repo — or on different worktrees of it — share one read stack per workspace and all read and write concurrently instead of a second session silently falling back to a stale, read-only view. The daemon holds the single-writer index, so references, callers and implementations run inside it and return complete results with no per-session copy. The daemon also keeps a cheap, always-on registry of repos, worktrees, and branches (workspace modes workspaces / worktrees / branches), and modes claim / release give agent sessions an advisory way to avoid colliding on the same worktree.

basemind statusline queries the daemon for the workspaces currently active and prints a compact line for your shell prompt; it prints nothing when no daemon is running.

The daemon is started on demand, detached with setsid(2). That changes the session and the process group but not the cgroup, so on Linux an auto-spawned daemon lives in the cgroup of whatever shell or editor happened to start it — outside any MemoryMax you configured for basemind. No code in basemind can change that; a process cannot move its own children into a cgroup it does not control. If you want an enforced memory ceiling, your unit has to be the thing that starts the daemon: set BASEMIND_NO_AUTOSPAWN=1 everywhere (basemind then connects to a running daemon but never starts one; basemind comms start deliberately still does) and install the ready-made user unit at docs/systemd/basemind-comms.service, which also lists the two commands that verify the ceiling is real rather than merely configured.

The daemon can additionally serve MCP over streamable HTTP on loopback, but that front-end is opt-in: it binds only when BASEMIND_ALLOW_HTTP is truthy in the daemon’s environment, and every request must then present the bearer token published as the second line of <comms_dir>/http.addr (mode 0600). Plugin manifests and the CLI use the stdio transport and need none of this.

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 coordinate in threads — each addressed by at least two of subject / path-glob / members, discovered by scope rather than joined globally — and each has a personal inbox. Messages come in two parts: a short headline (subject and sender) that’s cheap to skim, and the full body, fetched only when an agent wants to read it. An agent never sees its own posts in its inbox. Idle threads auto-archive. wait blocks for 30 seconds by default (at most 40) and ends early when the client cancels the request.

The client–daemon protocol is version 4: the daemon serves it on an 8-worker async runtime, and every request carries an id, so replies are matched to requests and most calls have a deadline (BASEMIND_COMMS_REQUEST_TIMEOUT_SECS, 10 s; BASEMIND_COMMS_HANDSHAKE_TIMEOUT_SECS, 30 s). After an upgrade, run basemind comms stop so the old daemon is replaced. A post can carry an idempotency_key: a retry with the same key returns the original message id instead of storing a duplicate (keys are remembered for an hour, and generated when omitted). The stdio relay replays read-only requests and keyed posts once if the daemon restarts underneath it, instead of failing the call, and fails a request that outlives BASEMIND_RELAY_REQUEST_TIMEOUT_SECS (180 s). Other tool responses carry a short notice when you have unread messages. A detached daemon logs to a size-rotated <comms_dir>/daemon.log, which basemind comms doctor shows.

The plugin makes sure agents notice messages without being asked — through the built-in instructions, a notice at session start and each turn, and a quiet background check every few seconds.

Included in every prebuilt download (and in cargo install --features shells / full): agents can open terminal sessions in the background, type into them, and read what’s on screen — no extra tools to install. Sessions can be fully headless, or opened in a real terminal tab or window so you can watch along. A spawned session and the agent that started it can message each other over comms.

The plugin nudges agents toward the cheap path by default:

• Get a file’s outline before opening it — then read only the part you need.
• Search for a definition instead of grepping for it.
• Look up who calls a function instead of grepping for call sites.
• Refresh the index after edits instead of restarting the server.
• Don’t re-read a file basemind already mapped.

Optional guardrails enforce this at the moment a tool is used:

• Guard — gently redirects grep-style searches to the matching basemind tool. On by default; set BASEMIND_GUARD=off to disable, or redirect to block instead of nudge.
• Output compressor — BASEMIND_COMPRESS_OUTPUT=1 shrinks long command output. It never touches anything that looks like a credential and leaves output alone if it can’t help.
• Re-read shortcut — BASEMIND_DELTA_READS=1 shows just what changed when an agent re-reads a file it already read this session.

basemind shrinks code by keeping the shape and dropping the bodies — function signatures and imports stay, the implementations go — because a signature is useless without its shape. For prose it does a light cleanup (extra whitespace, filler, repeated paragraphs). It reports honest before/after token counts, and the code version is exact — nothing is lost, just set aside. expand brings any one function’s full body back when an agent actually needs it: compress to an outline, expand only what you need.

basemind admin eval runs a task file of lookups through the same code the MCP tools use, scores each answer against gold generated from your repository (precision/recall, hit@k, MRR, nDCG), records latency and response tokens, and compares the token cost with the grep-and-read baseline an agent would otherwise pay. Savings only count when basemind’s answer was actually correct, and the report flags any mode whose measured ratio deviates from the dashboard’s fixed multiplier. --baseline <report.json> turns it into a regression gate. Gold generators and the workflow are in benchmarks/eval/; measured savings, including the cases where grep is cheaper for a single narrow hit, are in benchmarks/README.md.

Measured on an Apple M4 (10 cores — 4 performance + 6 efficiency, 16 GB, macOS 26) with the hardening harness (scripts/harden.sh), which clones each upstream repo fresh and scans its code map. Warm, steady-state numbers; the first scan of a cold project is slower.

The TypeScript compiler is the worst case — 81k files in about 18 seconds. Re-scans only look at what changed, so keeping a project up to date is far faster than the first scan.

Once running, code questions answer from memory rather than from disk each time — in milliseconds even on a very large repository (next section).

Measured with the built-in harness (basemind admin eval --warmup, see Measure it on your own repo) on a 74k-file, ~350 MB monorepo checkout, 60 tasks per mode, in-process (no transport or process start-up). Gold is generated from the repository itself; benchmarks/eval/README.md states what each mode’s gold encodes.

symbols and dependents answer from a resident term index, and references, callers and implementations from a resident dictionary of distinct callee and trait names, which is why they sit in the millisecond range instead of walking every call site. grep skips files a per-file trigram bloom filter proves cannot match (index cost ≈ 12.8 % of the indexed code bytes; results are identical to the full sweep, which took 3.6–7.8 s p50 on the same tasks; see ADR-0012). Set BASEMIND_GREP_BLOOM=0 to force the full sweep. Numbers vary with hardware and load; rerun the harness on your repository.

basemind precomputes a per-repo git-history index (path → commit posting lists, stored newest-first) so the history modes — touching, recent, churn, by_path, and symbol_history’s commit walk — are posting-list lookups. Warm in-process query latency on the same M4:

History queries answer in tens of microseconds, flat across history depth, because the newest-first posting lists decode only the commits a query returns. The index builds in well under a second to a few seconds and costs 6–22 % of .git on disk.

It is a pure accelerator: the tools use it only when it is fresh (last_indexed_head == HEAD) and otherwise walk history directly, so it can never serve stale results — and it rebuilds automatically when history is rewritten (filter-repo / rebase / force-push). Reproduce with cargo bench --bench git_history or the git-ops block in scripts/harden.sh.

Every latency-relevant mode — all of code and graph, all of git, the admin read modes, and the document / memory search modes — reports its own latency as elapsed_us on its response. Don’t wrap the CLI in time; ask basemind.

Resolution is microseconds on purpose: an indexed git mode touching is ~37 µs, so millisecond granularity would round the hot path to 0.

What elapsed_us includes — the tool body’s own execution: index and store lookups, git walks, ranking, and building the response.

What it excludes — MCP / JSON-RPC transport (which the server cannot observe), argument deserialization, and serialization of the response itself. Excluding encoding keeps the number comparable across format: "json" and format: "toon" and across result-set sizes: it reports query cost, not encoding cost.

The one caveat, stated plainly: most read tools begin by awaiting the in-RAM code map, and the git tools lazily build their history index on first use. Both waits happen inside the measured region, so a first call against a cold server is much slower than the steady-state call after it. When the server is still warming or building, the response carries a notice (warming_up / building_index / rescanning) — discard any sample carrying a notice if you are measuring steady-state latency.

The CLI adds a second number, startup_us, covering process startup: clap parsing, the tokio runtime, the store open, and the config/git-cache load. It is reported separately because it is exactly the part of a time basemind … measurement that was never the query — and a long-running MCP server pays it once at boot, not per call:

$ basemind code symbols run_workspace_grep --limit 1 --json
{
  ...
  "elapsed_us": 90,        # the query
  "startup_us": 957887     # everything else a `time` wrapper would have charged to it
}

$ basemind code references parse_kind --limit 3
...
(6.5 ms query · 852.9 ms startup)    # stderr: stdout carries only the answer

That first example is the whole point: the query took 90 µs, while the process spent ~0.96 s getting ready to run it. A time basemind … wrapper would have reported the second number and told you nothing about the first.

The config lives at the repo root as basemind.toml (committed). The cache it drives is derived state — held in the global cache under the XDG data directory, wiped and rebuilt on schema bumps — so config never belongs there and nothing basemind-owned is written into your repo. Run basemind init to drop a fully-commented scaffold (documenting every option) at the root. It can also live under the project-level .config/ convention — .config/basemind.toml or .config/basemind/config.toml — which is auto-discovered read-only; the root basemind.toml still wins when both exist. basemind init --config-dir .config (or --config-dir .config/basemind) scaffolds the convention. The legacy in-cache path (.basemind/basemind.toml, from before the global-cache move) is still read as a fallback for older checkouts. The full schema is at schema/basemind-config-v1.schema.json:

# basemind.toml  (repo root — commit this)
"$schema" = "v1"

[scan]
respect_gitignore = true
# Follow symlinks during the walk. Off by default — symlinks often escape the repo (e.g. Bazel's
# bazel-* convenience symlinks). Turn on for repos that symlink real source into place. Ignored
# (forced false) in a repository's own file unless the operator sets BASEMIND_ALLOW_FOLLOW_SYMLINKS=1.
follow_symlinks = false
# Glob syntax (include / exclude here, and every include / exclude / embed_* list below): paths are
# repo-relative with forward slashes, matching is case-sensitive, and `*` also crosses `/` (so
# `src/*.rs` matches `src/a/b.rs`). A pattern with no glob characters is gitignore-like: `generated`
# matches every path segment of that name at any depth and everything beneath it; `docs/api` is
# anchored at the root. Exclude beats include. An invalid glob, a negated (`!`) pattern, or an empty
# `include` (it would index nothing) is a config error. For `extra_roots` files the globs are
# matched against the path relative to that root.
include = ["**/*"]
# `exclude` is ADDED ON TOP of an always-on floor (node_modules, target, dist, build, out, .venv,
# venv, __pycache__, *.pyc, .pytest_cache/.mypy_cache/.ruff_cache/.tox, .next/.nuxt/.svelte-kit,
# vendor, .gradle, .terraform, coverage, bazel-*, .git, .basemind, .idea, .DS_Store) and of a
# credential floor, so a secret never becomes searchable by every agent that can query the index:
# .env and .env.*, .aws/, .ssh/, .gnupg/, .npmrc, .pypirc, .netrc, .git-credentials, id_rsa /
# id_dsa / id_ecdsa / id_ed25519, *.pem, *.key, *.p12, *.pfx, *.jks, *.keystore. Note `.env.*` also
# drops `.env.example`; list `.env.*` in floor_allow to index those templates (needs the
# BASEMIND_ALLOW_REPO_CREDENTIALS grant below).
exclude = []
# Remove entries from that floor so the tree is indexed, by directory name (`build`), file name or
# glob (`.env.*`, `*.pem`) or floor pattern (`**/build/**`). `.git` and `.basemind` can never be
# allowed; an entry naming nothing is ignored with a warning. A credential entry (`.env`, `*.pem`,
# keys) is honoured only with BASEMIND_ALLOW_REPO_CREDENTIALS=1 in the environment — a repository's
# own file cannot un-exclude your secrets. The default `exclude` separately lists
# dist/target/node_modules/.venv/bazel-*, so drop those from `exclude` too when allowing them.
floor_allow = []
# Index directories outside the repo root too — e.g. a Bazel external repo cache — so their
# symbols resolve in search / references / outlines. External files are keyed by absolute path;
# (re-)indexed on a full `basemind scan` only (not live-watched). Requires the operator to set
# BASEMIND_ALLOW_EXTRA_ROOTS in the environment: this file lives inside the repository, so
# without that opt-in a cloned repo could point basemind at your ~/.ssh. Even with the grant, a root
# under .ssh / .aws / .gnupg or /etc, a filesystem root, and a root inside the repo are skipped.
# Extra roots count toward max_candidates and follow symlinks only when follow_symlinks is on.
extra_roots = ["/private/var/tmp/_bazel_you/abc123/external"]
# Ceiling on how many candidate files one scan may keep, across the repo walk and every extra root.
# Exceeding it aborts before any extraction or index write, and the error names the heaviest
# contributing directories — so a vendored tree that slipped past .gitignore is a one-line fix
# instead of an out-of-memory kill. It also bounds how far the walk may travel to find them. It does
# NOT bound bytes read or index size, and does not apply to `--staged` / `--rev` (those enumerate
# from git, not from a walk). 0 disables both bounds.
max_candidates = 500_000

# Per-grammar overrides, keyed by tree-sitter-language-pack grammar name (see `basemind lang list`;
# an unknown key is a config error that suggests near matches).
[languages.vimdoc]
# false stops parsing that grammar's files as code (fixes misdetections: `.txt` is vimdoc, `.conf`
# is nginx). They are then handled like any unrecognised file: routed to the document tier, where
# `[documents] exclude` can drop them entirely. Already-indexed files are removed on the next scan.
enabled = false
[languages.jinja2]
# Map extra suffixes (leading dot optional, case-insensitive, compound allowed) and exact file
# names onto the grammar. Overrides beat built-in detection; a filename beats an extension.
extensions = [".mako", ".tpl"]
filenames = ["BUILD.in"]
# `basemind lang install` also fetches this grammar (otherwise only the languages basemind ships
# queries for are pre-fetched and the rest download on first use).
preload = true

[code_intel]
# Precise, scope- and import-aware resolution (JS/TS via oxc; Python/Java via stack-graphs). On by
# default. Set false to fall back to fast tree-sitter locals binding for every language. Applies to
# files (re)scanned after the change.
precise_resolution = true

[documents]
enabled = true
# Embed documents for semantic search (ON — embeddings pay off on real pr

提示：代码过长已自动截断

Overrides. Only the documents.* and llm.* keys can be overridden, by a CLI flag or its environment variable (each flag’s name is in --help; the variable is the flag upper-cased with a BASEMIND_ prefix and underscores, e.g. --llm-model is BASEMIND_LLM_MODEL, --documents-overlap is BASEMIND_DOCUMENTS_OVERLAP). Every other setting is file-only. Overrides apply to the CLI command they are passed to (the MCP tools do not accept them); a daemon-hosted scan or read stack loads only the file (plus the daemon caps below), so set those keys in basemind.toml for daemon workloads. Overrides are validated after merging, so an override cannot smuggle in a value the file would be rejected for (documents.max_characters under 64, overlap >= max_characters, language.min_confidence outside 0…1).

Trust boundary. basemind.toml is authored by the repository, not by you, so settings that reach outside the process are gated on the operator’s environment:

Grant variables accept 1, true or yes (case-insensitive). They are read from the process environment; the env and CLI override layers are operator-supplied and never gated.

Credential and key files are not indexed by default: the exclude floor (see [scan] above) drops .env, .env.* (which includes .env.example), .aws/, .ssh/, .gnupg/, .npmrc, .pypirc, .netrc, .git-credentials, SSH private keys and *.pem / *.key / *.p12 / *.pfx / *.jks / *.keystore. Opt a file class back in with [scan] floor_allow = [".env.*"] — a credential entry only takes effect with the operator’s BASEMIND_ALLOW_REPO_CREDENTIALS=1 grant, so a repository’s own file cannot un-exclude it. Unless follow_symlinks is granted, working-tree reads (including the watcher and rescan paths) refuse a symlinked file or a path that resolves outside the workspace, and a basemind.toml that is a symlink leaving the workspace is not followed.

The daemon treats [resources] and [scan] max_candidates as ceilings. The effective value is the smaller of the file’s and the daemon’s cap; the [resources] sentinels 0 / "auto" / "off" resolve to the cap. The operator raises a cap in the daemon’s own environment (a repository cannot):

A cap variable must be a positive integer; anything else falls back to the default.

Other operator variables.

Reload. The daemon re-reads a workspace’s basemind.toml on the next request after it changes (size or modification time) and logs config changed. A file that no longer parses keeps the last good config and logs a warning. A hosted read stack with live sessions keeps its config until they reconnect, and scan_threads is fixed for the process lifetime (the daemon logs that a restart is required). admin status reports config_stamp (<bytes>B@<unix seconds>) to spot an edit.

Reserved keys. These parse but nothing reads them yet, and setting one to a non-default value logs a warning: [watch] live_l2, [cache] file_map_lru, [mcp] transport, [memory] enabled / scope_strategy / default_visibility, [comms] enabled / idle_timeout_secs / max_messages_per_room / retention_secs / max_rooms / workspace_root, [shells] keep_on_exit, [documents.ocr] backend / languages, and [documents.language] preferred_languages.

Config changes take effect on the next scan. Cached chunks and documents carry a fingerprint of the settings that shape them ([code_search] max_characters / overlap / max_chunks_per_file; [documents] chunk size, page cap, language detection, keywords, NER, summarization, extract_archives, [resources] document_models and [llm] model), so changing one re-chunks or re-extracts only the affected files. Embedding scope (embed, embed_include, embed_exclude, and the enabled switches) is reconciled too: the first scan after a change deletes the vector rows of files that are no longer eligible (and, when [code_search] enabled = false, their keyword postings) and rebuilds the rows of files that became eligible from the cached blobs, without re-embedding.

Every MCP tool mode maps to a CLI command, or is declared CLI-only / MCP-only with a reason (enforced by tests/cli_parity/). Add --json for machine-readable output (the same response types the MCP tools return, including agents and workspace). Human output prints source bodies, diffs and exports in full; only table cells are cut (to 200 characters, with a note on stderr), and the timing line goes to stderr. List commands take --cursor (resume from a previous next_cursor) and --max-tokens; code semantic also takes --rerank-top-k; --format toon returns compact TOON tables.

Exit codes

With a comms daemon running, the one-shot CLI forwards memory operations, reference/caller reads, the grep prefilter and rescans to it (the daemon is the sole index writer) instead of failing or degrading to a truncated in-memory view.

Code (basemind code)

README 内容过长，已截取前 64 KB。完整内容请前往 GitHub 仓库查看。