Configuration
basemind merges configuration from five layers. Highest precedence wins: a per-request MCP
override, then a CLI flag, then an environment variable, then the config file, then the built-in
default (Mcp > Cli > Env > File > Default).
Config File
Section titled “Config File”Create basemind.toml at the repo root to customize behavior. basemind init (see
Get started) writes a fully-commented starter file there if
one doesn’t already exist — optional, since all settings have sensible defaults. The file is
validated against a JSON Schema and rejects unknown keys, so a typo fails loudly rather than
being silently ignored.
The config can also live under the project-level
.config/ convention, either flat (.config/basemind.toml)
or nested (.config/basemind/config.toml); both are auto-discovered when no root file is present.
The root basemind.toml wins when more than one exists, and any of these locations marks the
directory as a basemind workspace root. Scaffold the convention with
basemind init --config-dir .config or --config-dir .config/basemind. A legacy
.basemind/basemind.toml path is still read as a fallback for older checkouts.
Minimal Example
Section titled “Minimal Example”# basemind.toml (repo root)"$schema" = "v1"
[scan]include = ["**/*.{rs,ts,tsx,py,go}"]eager_l2 = trueextra_roots = ["/private/var/tmp/_bazel_you/abc123/external"]
[documents]enabled = trueThe only required key is $schema ("v1"). Everything else is optional and falls back to defaults.
All tunables live under a named section — there are no bare top-level options.
Sections
Section titled “Sections”| Section | Purpose |
|---|---|
[scan] |
What to index: globs, size caps, gitignore, submodules, L2, extra roots. |
[code_intel] |
Precise, scope- and import-aware name resolution (precise_resolution, default true). |
[watch] |
Live-watch debounce and whether the watcher extracts L2. |
[cache] |
In-memory FileMap LRU size. |
[mcp] |
MCP transport (stdio). |
[documents] |
Document extraction + RAG (needs --features documents). |
[resources] |
Resource-governance knobs: scanner/embedder thread caps, batch size, footprint ceiling, document model profile. |
[code_search] |
Semantic/keyword code search chunking + embedding (needs --features code-search). |
[memory] |
Shared-memory scope and default visibility (needs --features memory). |
[comms] |
Agent comms identity + retention (needs --features comms). |
[llm] |
Deprecated: still accepted, and ignored. |
[languages.<grammar>] |
Per-grammar toggles and extension/file-name mappings. |
[scan] Section
Section titled “[scan] Section”[scan]include = ["**/*"]exclude = ["**/target/**", "**/node_modules/**", "**/bazel-*/**"]floor_allow = []respect_gitignore = truefollow_symlinks = falsemax_file_bytes = 2097152 # 2 MiBskip_submodules = trueeager_l2 = trueextra_roots = ["/path/to/external/repo"]max_candidates = 500000Globs are repo-relative with forward slashes and case-sensitive; * 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, and docs/api is anchored at the
root and matches that path and everything beneath it. Exclusion beats inclusion. The same syntax
applies to every include / exclude / embed_include / embed_exclude list in the file. An
invalid glob, or a negated pattern (!foo), is a config error. For extra_roots files the globs are
matched against the path relative to that root.
| Key | Type | Default | Notes |
|---|---|---|---|
include |
array of globs | ["**/*"] |
Files to index; at least one entry is required (an empty list would index nothing and is rejected at load). Language detection still filters by tree-sitter support. |
exclude |
array of globs | build/vendor dirs | Excludes target/, node_modules/, dist/, .venv/, .git/, .basemind/, and bazel-* trees. Applied on top of the always-on exclude floor below. |
floor_allow |
array of strings | [] |
Entries to remove from the always-on exclude floor, by directory (build, vendor), file name or glob (.env.*, *.pem), or floor pattern (**/build/**). A directory also listed in the default exclude must be removed from exclude too. A credential entry is honoured only with the operator’s BASEMIND_ALLOW_REPO_CREDENTIALS=1 grant. .git and .basemind can never be allowed; an entry naming nothing in the floor is ignored with a warning. |
respect_gitignore |
bool | true |
Honor .gitignore during the walk. |
follow_symlinks |
bool | false |
Follow symlinks during the walk, including extra_roots walks. Symlinks often escape the repo (Bazel’s bazel-* convenience links), so the repository’s own basemind.toml cannot turn this on: it is forced to false with a warning unless the operator sets BASEMIND_ALLOW_FOLLOW_SYMLINKS=1. Without it, working-tree reads (including the watcher and rescan paths) refuse symlinked files and paths resolving outside the workspace. |
max_file_bytes |
integer | 2097152 |
Skip files larger than this (2 MiB). Prevents minified-bundle stalls. |
skip_submodules |
bool | true |
Skip paths under submodule roots listed in .gitmodules. |
eager_l2 |
bool | true |
Extract L2 (call sites) inline with the scan. false trades reference search for a faster scan. |
extra_roots |
array of absolute paths | [] |
Index directories outside the repo root (e.g., a Bazel external cache). External files are keyed by absolute path; (re-)indexed on full basemind scan only (not live-watched); they count toward max_candidates. Ignored with a warning unless the operator grants it (see Trust boundary). Missing roots, roots inside the repo, filesystem roots and credential directories (.ssh, .aws, .gnupg, /etc) are skipped. |
max_candidates |
integer | 500000 |
Ceiling on files one scan may keep, across the repo walk and every extra root (minimum 0). Exceeding it aborts before any extraction or index write, and the error names the heaviest directories. The walk also aborts if it visits far more entries than this. 0 disables both bounds. Does not apply to --staged / --rev scans. |
Exclude floor
Section titled “Exclude floor”Independent of exclude, a floor of paths is never indexed: node_modules, dist, build, out,
coverage, .next, .nuxt, .svelte-kit, .venv, venv, __pycache__, *.pyc, the pytest /
mypy / ruff caches, .tox, target, .gradle, vendor, .terraform, bazel-*, .git,
.basemind, .idea and .DS_Store.
The floor also holds credential and key material, 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, and *.pem, *.key,
*.p12, *.pfx, *.jks, *.keystore.
[watch] Section
Section titled “[watch] Section”[watch]debounce_ms = 250live_l2 = false| Key | Type | Default | Notes |
|---|---|---|---|
debounce_ms |
integer | 250 |
Coalesce filesystem events within this window (0–60000 ms). |
live_l2 |
bool | false |
Reserved: parsed but has no effect yet (a warning is logged when set). |
[cache] and [mcp] Sections
Section titled “[cache] and [mcp] Sections”[cache]file_map_lru = 256
[mcp]transport = "stdio"| Key | Type | Default | Notes |
|---|---|---|---|
cache.file_map_lru |
integer | 256 |
Reserved: parsed but has no effect yet (a warning is logged when set). See [resources] max_map_cache_mb for the outline cache. |
mcp.transport |
string | stdio |
Reserved: stdio is the only transport and nothing reads this key. |
[documents] Section
Section titled “[documents] Section”Document indexing (PDFs, Office, HTML, etc.) and full-text + semantic search. Requires
--features documents; OCR needs documents-ocr and named-entity recognition needs documents-ner
(see Cargo Features). The document tier also holds the prose, data and config files the code map
no longer indexes (Markdown, reStructuredText, AsciiDoc, JSON, YAML, TOML, XML, CSV, INI, .env,
diffs and the like), so include / exclude and mime_allowlist decide which of those are
searchable. A build without the documents feature keeps them in the code map.
[documents]enabled = trueembed = truemax_chunks_per_document = 2000| Key | Type | Notes |
|---|---|---|
enabled |
bool | Enable/disable document indexing (default true). Requires the model files, which download on first use. |
embed |
bool | Generate vector embeddings for semantic search (default true). Set false to keep full-text only. |
embedding_preset |
string | Named embedding model preset used to embed chunks (default balanced). |
max_chunks_per_document |
integer | Cap on chunks embedded per document (default 2000), so one pathological file can’t explode a scan. |
max_pages / extraction_timeout_secs |
integer | Per-document extraction bounds: pages (default 500) and wall-clock seconds (default 120). A document that overruns the time budget is abandoned and counted as doc_timeouts. It is remembered by content hash and skipped (docs_tombstoned) while the file and these limits (the timeout, the two chunk cutovers and max_pages) are unchanged; editing the file or changing a limit retries it. |
phase_budget_secs |
integer | Wall-clock budget in seconds for the whole document phase of one scan (default 1800, minimum 1, never below extraction_timeout_secs). It starts at the first document that needs a real extraction. Once spent, the remaining documents are deferred (docs_deferred, not failed) and picked up by the next scan, so several documents timing out together cost this budget rather than one timeout each. |
max_abandoned_extractions |
integer | Cap (default 4, range 1 to 64) on timed-out extractions still running. A timed-out extraction cannot be cancelled and keeps a core busy until it finishes; at the cap, further documents are deferred (docs_deferred) instead of spawning another thread. The live count shows as abandoned_extractions in the scan summary. A soft bound: extractions already in flight may still time out past it. |
markdown_chunk_max_bytes / plain_text_chunk_max_bytes |
integer | Size cutovers (bytes, minimum 1024; defaults 1048576 and 4194304) above which a text-like document (markdown; plain text/plain for the second key) is chunked by a linear fixed-size chunker instead of xberg’s quadratic markdown splitter. Structured data (json, yaml, xml, svg, csv/tsv) is always chunked linearly, whatever its size. Counted as docs_degraded in the scan summary; PDFs and Office files are never affected. The same linear path is used when xberg rejects a text-like file outright (a Helm template named .yaml, a CSV past the table-cell limit, an SVG with an oversized entity): it is re-read as text/plain and counted as docs_degraded and docs_text_fallback. |
max_characters / overlap |
integer | Chunk size (default 1000, minimum 64) and overlap (default 200); overlap must stay below max_characters. |
extract_archives |
bool | Deprecated: still accepted, and ignored. Archive extraction was removed, so archives (.zip, .tar, .jar, …) are always skipped; true logs a one-time warning. |
max_archive_bytes / max_archive_entries |
integer | Cap on total uncompressed bytes (default 64 MiB) and entries (default 1000) unpacked from one zip container, which is what an Office file (docx, pptx, xlsx, odt) is. A file past either cap fails extraction instead of being unpacked into memory. |
mime_allowlist |
array of strings | Restrict extraction to specific MIME types (empty = accept all supported types). |
extension_denylist |
array of strings | File extensions never routed to extraction (archives and binaries are denied by default). |
include |
array of globs | Allow-list selecting which non-code files are indexed as documents. Empty (default) = every non-code file that passes [scan]. exclude wins. |
exclude |
array of globs | Deny-list applied to document indexing itself: matching files are not extracted, chunked or searchable. Defaults to the *.svg vector assets, the lockfiles pnpm-lock.yaml, package-lock.json, yarn.lock, Cargo.lock, poetry.lock and *.lock, and the test-data directories **/test_data/**, **/testdata/**, **/fixtures/** and **/__snapshots__/**. Setting the key replaces the default list: exclude = [] indexes all of them, and a custom list must repeat any default entry it still wants. |
max_file_bytes |
integer | Per-document size cap in bytes (minimum 1024, default 52428800 = 50 MiB), independent of [scan] max_file_bytes, so PDFs and Office files above the 2 MiB source cap are still extracted. Larger files are skipped and counted as too large in the scan summary. |
embed_include / embed_exclude |
array of globs | Embedding scope, only consulted when embed = true: with a non-empty embed_include only matching documents are embedded; embed_exclude beats it. Both only narrow what include / exclude already index. Excluded documents stay extracted and keyword-searchable. Changing either removes the vector rows of newly excluded files on the next scan. |
The [documents] tree also carries sub-tables for reranking, keywords, NER, summarization, and OCR
([documents.reranker], [documents.keywords], and so on). [documents.ocr] backend / languages
and [documents.language] preferred_languages are reserved: they parse but have no effect yet.
[documents.ner] needs a build with the documents-ner feature: without it enabled = true has no
effect and logs a warning naming the key and the feature. Two values are deprecated, still accepted
and logged once: [documents.summarization] strategy = "abstractive" falls back to extractive
(TextRank) summaries, and [documents.ner] backend = "llm" extracts no entities. OCR needs
no configuration: a build with documents-ocr runs it on raster images and on PDFs with no text layer. See the
JSON Schema
for the exhaustive field set.
[resources] Section
Section titled “[resources] Section”Bounds basemind’s memory and CPU footprint: scanner/embedder thread caps, embed batch size, a
best-effort footprint ceiling, and which document model families run. 0 is the “auto” sentinel
for the thread/concurrency caps — it means “let basemind pick a bounded fraction of the machine”
rather than “use zero threads”.
[resources]scan_threads = 8embed_threads = 4embed_batch_size = 16max_footprint_mb = 4096document_models = "code_only"| Key | Type | Default | Notes |
|---|---|---|---|
scan_threads |
integer | 0 |
Cap on the code-map scanner’s rayon pool. 0 (auto) keeps rayon’s default (one worker per logical CPU). The pool is built once per process and fixed after the first scan. |
embed_threads |
integer | 0 |
Cap on the ONNX embedding pool. 0 (auto) resolves to max(2, logical_cpus / 4), so the embedder never pins the machine and ORT arenas aren’t replicated across every core. Supersedes the deprecated [documents].embed_max_threads; resources.embed_threads wins whenever it’s set (non-zero). |
embed_batch_size |
integer | 32 |
Number of chunks the embedder submits to ONNX per batch. Larger batches amortize per-call overhead at the cost of a higher transient memory spike; lower it to shrink that spike. |
max_concurrent_documents |
integer | 0 |
Upper bound on documents extracted concurrently. 0 (auto) leaves dispatch unbounded. Documents beyond the bound wait for a free slot before they are read, so a burst of large files cannot all be held in memory at once. The daemon clamps the value (see BASEMIND_DAEMON_MAX_CONCURRENT_DOCUMENTS). |
max_footprint_mb |
integer, "auto" or "off" |
0 |
Advisory memory ceiling in mebibytes. A positive integer is an explicit ceiling; 0 or "auto" derives one (75% of an enforced cgroup limit, else 50% of machine RAM, floored at 512 MiB); "off" disables it. Workers park at the document-extraction and code-chunk embedding admit points while the process is over the ceiling. Document extraction then runs one document at a time (an otherwise idle process is admitted immediately), and a document whose own estimated working set exceeds the ceiling is skipped, counted as too large, with a warning naming the estimate and the limit. The ceiling shapes peak memory rather than enforcing a hard limit. The daemon clamps it (see BASEMIND_DAEMON_MAX_FOOTPRINT_MB). |
max_map_cache_mb |
integer | 256 |
Byte budget in MiB for the MCP read stack’s decoded-outline cache, per workspace; 0 is unbounded. A miss costs one blob read and never changes an answer. code_refs scans from a daemon-backed session are forwarded to the daemon and hold no projection in the session, so this budget only bounds the last-resort in-RAM call/implementation projection used when no daemon is reachable (the projections_capped notice appears only then). The daemon clamps it (see BASEMIND_DAEMON_MAX_MAP_CACHE_MB). |
document_models |
enum | full |
Which model families run during document extraction. full runs every configured post-processor the build has (OCR needs the documents-ocr feature, NER needs documents-ner). code_only keeps embeddings but forces keyword extraction, NER, and summarization off and disables OCR. none also drops embeddings — documents are still extracted for text + metadata (keyword search) but never routed to any model. [documents].enabled = false remains the zero-cost total short-circuit. |
onnx_provider |
enum | cpu |
ONNX Runtime execution provider for every model basemind loads (embeddings, reranker, NER): cpu, auto, coreml, cuda or tensorrt. The default is cpu because the platform default on macOS (CoreML) compiled a graph per input shape and measured 7.6 GB resident for one tiny document against 0.8 GB on CPU (and 3x slower), which let a document-heavy scan reach tens of GB. auto restores the platform default (CoreML on macOS, CUDA on a GPU-enabled Linux build). |
[code_search] Section
Section titled “[code_search] Section”Semantic + keyword search over source chunks (code_search). Requires
--features code-search.
[code_search]enabled = trueembed = true
[code_search.reranker]enabled = false| Key | Type | Default | Notes |
|---|---|---|---|
enabled |
bool | true |
Chunk + index source on scan. |
max_characters |
integer | 1500 |
Max chunk size (minimum 64); longer chunks split into overlapping windows. |
overlap |
integer | 200 |
Overlap between split windows, in characters. |
max_chunks_per_file |
integer | 2000 |
Cap on chunks indexed per source file, so a generated table or bundle cannot fan out into an unbounded chunk count. |
embed |
bool | false |
Emit vector rows for the semantic lane. Off by default: the BM25 keyword lane covers most code queries and no ONNX model is downloaded. With false the vector lane returns nothing. |
embed_include |
array of globs | [] |
When non-empty only matching files are embedded; the rest stay chunked and keyword-searchable. Only used with embed = true. |
embed_exclude |
array of globs | [] |
Files that are chunked and indexed but never embedded. Beats embed_include. |
[code_search.reranker] enabled |
bool | false |
Optional cross-encoder rerank of fused hits (downloads an ONNX model on first use). |
[memory] Section
Section titled “[memory] Section”Shared per-repo memory. Requires --features memory.
[memory]enabled = truescope_strategy = "git_remote_with_fallback"default_visibility = "group"| Key | Type | Default | Notes |
|---|---|---|---|
enabled |
bool | true |
Reserved: the memory cargo feature alone decides whether memory is available. |
scope_strategy |
enum | git_remote_with_fallback |
Reserved. Intended: git_remote_with_fallback shares memory across clones of the same remote; workdir_only keeps each clone separate. |
default_visibility |
enum | group |
Reserved. Intended: default tier when a memory_save / memory_search call omits visibility (group shared, individual private to the calling agent). |
All three [memory] keys parse but currently have no effect (see Reserved keys).
Removed sections
Section titled “Removed sections”[crawl] configured web crawling and [shells] configured agent shells; both features were
removed. The tables are still accepted so that a basemind.toml written for an older version keeps
loading (basemind init used to write an empty [crawl]): their contents are not validated and
nothing reads them. A removed table with keys in it logs one warning per process; delete the table
to silence it.
[comms] Section
Section titled “[comms] Section”Agent communication. Requires --features comms.
[comms]enabled = trueagent_id = "my-agent"| Key | Type | Default | Notes |
|---|---|---|---|
enabled |
bool | true |
Reserved: the comms cargo feature alone decides whether comms runs. |
agent_id |
string | auto | Stable identity presented to the broker. Falls back to BASEMIND_AGENT_ID, then a generated per-session id. |
idle_timeout_secs |
integer | 1800 |
Reserved: idle window before the broker sheds caches. |
max_messages_per_room |
integer | 1000 |
Reserved: per-thread front-matter retention cap. |
retention_secs |
integer | 604800 |
Reserved: message retention window; older messages become prune-eligible. |
max_rooms |
integer | 256 |
Reserved: hard cap on concurrently registered threads. |
workspace_root |
string | unset | Reserved. |
Only agent_id is read. The other [comms] keys, including enabled, parse but currently have no
effect (see Reserved keys).
[llm] Section
Section titled “[llm] Section”Deprecated and ignored. basemind no longer calls a language model: LLM-backed (abstractive)
summarization and the LLM NER backend were removed, and the reranker is a local ONNX cross-encoder.
The table and its keys (model, api_key, base_url, temperature, timeout_secs, max_retries,
max_tokens) are still accepted so an older basemind.toml keeps loading; a table with content logs
one warning. The --llm-* flags on basemind scan and the BASEMIND_LLM_* environment variables
are accepted and ignored too, and BASEMIND_ALLOW_REPO_LLM has nothing left to grant.
[languages.<grammar>] Section
Section titled “[languages.<grammar>] Section”Per-grammar overrides, keyed by a tree-sitter-language-pack grammar name.
[languages.vimdoc]enabled = false # stop parsing .txt as vimdoc; the files fall through to the document tier
[languages.jinja2]extensions = [".j2"] # extra suffixes mapped to this grammar (leading dot optional)filenames = ["Jinjafile"] # exact file names mapped to this grammarpreload = true # also fetch the grammar in `basemind lang install`| Key | Type | Default | Notes |
|---|---|---|---|
enabled |
bool | true |
false stops parsing the grammar’s files as code; they are handled as if no grammar recognised them and fall through to the document tier, where [documents] exclude can drop them. Use it for misdetections such as .txt (vimdoc) or .conf (nginx). |
extensions |
array of strings | [] |
Extra suffixes mapped to the grammar: leading dot optional, case-insensitive, compound suffixes like .html.erb allowed. |
filenames |
array of strings | [] |
Exact file names mapped to the grammar. A file name beats an extension. |
preload |
bool | false |
Also fetch the grammar in basemind lang install. By default only the languages basemind ships queries for are pre-fetched; the rest download on first use. |
The table key must be a tree-sitter-language-pack grammar name (basemind lang list shows them). An
unknown name is a config error with near-match suggestions. Overrides take precedence over built-in
detection; already-indexed files of a disabled or remapped language are updated on the next scan
(files of a disabled language are dropped).
Environment Variables
Section titled “Environment Variables”Settings map to environment variables by prefixing BASEMIND_, uppercasing, and joining the
section and key with an underscore. Only the documents.* keys have CLI-flag and
environment overrides (the flags are --documents-* on basemind scan); every other
setting is file-only. The --llm-* flags and BASEMIND_LLM_* variables are deprecated: still
accepted, and ignored.
BASEMIND_DOCUMENTS_ENABLED=trueBASEMIND_DOCUMENTS_OVERLAP=100Trust boundary
Section titled “Trust boundary”basemind.toml is authored by the repository, not by the operator running basemind, so settings that
reach outside the process are honoured only when the operator grants them in the environment. The
gate applies to the file layer only; env and CLI overrides are operator-supplied and never gated.
Grant variables accept 1, true or yes (case-insensitive).
| Setting in the repo’s file | Honoured only when |
|---|---|
[scan] follow_symlinks = true |
BASEMIND_ALLOW_FOLLOW_SYMLINKS=1; otherwise reset to false with a warning. |
[scan] floor_allow (a credential entry) |
BASEMIND_ALLOW_REPO_CREDENTIALS=1; otherwise the entry is ignored with a warning and the secret stays excluded. Build-artifact entries need no grant. |
[scan] extra_roots |
BASEMIND_ALLOW_EXTRA_ROOTS set to 1 / true / yes (every workspace the process scans), or to a list of absolute workspace roots separated by : (; on Windows) that grants only those workspaces and their descendants. A relative entry, or another word such as on, is ignored with a warning. Prefer the list form for a daemon, which serves many repositories: the bare 1 also opens extra_roots for any workspace it serves later. |
A basemind.toml that is a symlink leaving the workspace is not followed, so a parse error cannot
quote a file the repository does not own.
Daemon
Section titled “Daemon”The shared daemon serves every workspace on the machine, so it treats resource settings as ceilings:
the effective value is the smaller of the file’s value and the daemon’s cap. The [resources]
sentinels and [scan] max_candidates = 0 mean “no limit” and resolve to the cap; the other limits
are clamped directly (min(file, cap)). The operator raises a cap in the daemon’s own
environment, which a repository cannot write. A cap variable must be a positive integer; anything else
falls back to the default.
| Variable | Caps | Default |
|---|---|---|
BASEMIND_DAEMON_MAX_SCAN_THREADS |
[resources] scan_threads |
4 |
BASEMIND_DAEMON_MAX_EMBED_THREADS |
[resources] embed_threads |
4 |
BASEMIND_DAEMON_MAX_EMBED_BATCH |
[resources] embed_batch_size |
8 |
BASEMIND_DAEMON_MAX_CONCURRENT_DOCUMENTS |
[resources] max_concurrent_documents |
4 |
BASEMIND_DAEMON_MAX_FOOTPRINT_MB |
[resources] max_footprint_mb |
3072 |
BASEMIND_DAEMON_MAX_MAP_CACHE_MB |
[resources] max_map_cache_mb |
1024 |
BASEMIND_DAEMON_MAX_CANDIDATES |
[scan] max_candidates |
2000000 |
BASEMIND_DAEMON_MAX_FILE_BYTES |
[scan] max_file_bytes |
67108864 (64 MiB) |
BASEMIND_DAEMON_MAX_DOCUMENT_BYTES |
[documents] max_file_bytes |
536870912 (512 MiB) |
BASEMIND_DAEMON_MAX_DOCUMENT_PAGES |
[documents] max_pages |
5000 |
BASEMIND_DAEMON_MAX_EXTRACTION_SECS |
[documents] extraction_timeout_secs |
1800 |
BASEMIND_DAEMON_MAX_CHUNKS_PER_DOCUMENT |
[documents] max_chunks_per_document |
20000 |
BASEMIND_DAEMON_MIN_DEBOUNCE_MS |
floor for [watch] debounce_ms (a minimum, not a ceiling) |
50 |
Reload. The daemon re-reads a workspace’s basemind.toml on the next request after it changes
(size and modification time, plus a content hash for very recent edits) and logs config changed; reloaded. 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). index_status reports config_stamp
(<bytes>B@<unix seconds>) to spot an edit. The file watcher rebuilds its include/exclude filter on
the same change.
Worktree seeding. A new linked worktree’s working view is cloned (copy-on-write where the
filesystem allows) from a sibling checkout of the same repository, preferring the main worktree, so
its first scan only re-reads files that differ. The vector store is not cloned; the first scan rebuilds
its rows from the cached blobs without re-embedding. A sibling whose workspace lock is held, or one too
large to copy without reflinks, is skipped and the new worktree scans from scratch.
ONNX memory. Every process bounds ONNX Runtime (no memory-pattern planning, no retained CPU arena,
so memory does not stay sized to the largest batch seen); intra-op threads are the auto embed-thread
count (max(2, logical CPUs / 4)), or 2 in the comms daemon. The daemon drops its resident embedding models when the last concurrent
embedding pass ends.
Git history. Linked worktrees share one git-history index. A worktree whose HEAD descends from the indexed head appends; one that diverges leaves the index untouched and reads history by walking git directly.
Reserved keys
Section titled “Reserved keys”These parse but nothing reads them yet; setting one to a non-default value logs a warning:
[watch] live_l2, [cache] file_map_lru, [memory] enabled / scope_strategy /
default_visibility, [comms] enabled / idle_timeout_secs / max_messages_per_room /
retention_secs / max_rooms / workspace_root, [documents.ocr] backend /
languages, and [documents.language] preferred_languages. ([mcp] transport is also unread, but
stdio is its only value.)
Deprecated keys are still accepted and ignored: the [llm] table,
[documents] extract_archives, [documents.summarization] strategy = "abstractive" and
[documents.ner] backend = "llm". BASEMIND_ALLOW_REPO_LLM and
BASEMIND_DAEMON_ALLOW_EXTRACT_ARCHIVES no longer have any effect.
Config changes
Section titled “Config changes”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 and
[resources] document_models), 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 as well: 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.
Other variables
Section titled “Other variables”Read directly rather than mapped from a config key:
| Variable | Effect |
|---|---|
BASEMIND_NO_SEED |
Any non-empty value other than 0 stops a new linked-worktree view from being seeded from a sibling worktree’s index. |
BASEMIND_DATA_HOME |
Overrides the global cache root. |
BASEMIND_GREP_BLOOM |
0 disables the per-file trigram bloom prefilter of code_grep and forces the full sweep. Anything else (or unset) leaves it on. See Performance. |
BASEMIND_BLOB_GC_GRACE_SECS |
Whole seconds a blob must age before the sweep (basemind cache gc, post-migration cleanup, the daemon’s hourly sweep) may reclaim it. Default 21600 (6 h); 0 reclaims every unreferenced blob at once. |
BASEMIND_GH_INDEX |
0 disables the git-history index (the history tools then walk git directly); scan / rescan --no-git-history does the same per run. |
BASEMIND_GIT_DISCOVER_PARENTS |
Restores indexing an ancestor repository’s history for a workspace root that is only a subdirectory of it. |
BASEMIND_BLAME_MAX_BYTES / BASEMIND_BLAME_MAX_LINES |
Size limits past which git_blame refuses a file (defaults 1 MiB and 5000 lines). |
BASEMIND_PARSE_TIMEOUT_MS |
Hard ceiling on one tree-sitter parse, in milliseconds (default 5000). |
BASEMIND_GRAMMAR_OFFLINE |
Any non-empty value other than 0 stops basemind downloading tree-sitter grammars. |
BASEMIND_MCP_LEAN |
Advertises three lean wrapper tools in tools/list instead of the full tool list. |
BASEMIND_COMMS_DIR |
Overrides the comms directory. The daemon’s files (singleton socket, daemon.log, http.addr, the comms store) are in its protocol-generation subdirectory, g1/. Keep the path short: the socket is <dir>/g1/comms.sock, and a Unix socket path is limited to 103 bytes on macOS and 107 on Linux. |
BASEMIND_HTTP_ADDR |
host:port for the opt-in HTTP front-end (needs BASEMIND_ALLOW_HTTP). Unset, the daemon binds 127.0.0.1:51786, or an OS-assigned port when that is in use, as it is when a daemon of another protocol generation runs; the bound address is the first line of http.addr. A value set here is bound as given or not at all. |
BASEMIND_COMMS_REQUEST_TIMEOUT_SECS |
Seconds a coordination request waits for the broker’s reply (default 10). Forwarded work is exempt. |
BASEMIND_COMMS_HANDSHAKE_TIMEOUT_SECS |
Seconds for connect plus Hello (default 30; a cold daemon answers only once its store is open). |
BASEMIND_RELAY_REQUEST_TIMEOUT_SECS |
Seconds the basemind serve relay waits for the daemon before answering -32002 backend_timeout (default 180; 0 disables). |
BASEMIND_COMMS_IDLE_REAP_SECS / BASEMIND_COMMS_IDLE_CHECK_SECS |
How long an unused daemon lingers before exiting (default 600) and how often that is checked (default 60). |
Daemon-side knobs that are not config keys (BASEMIND_WARM_READ_STACKS, BASEMIND_CACHE_BUDGET_MB,
BASEMIND_CACHE_GRACE_MINUTES, BASEMIND_INDEX_CACHE_BYTES, BASEMIND_MAX_DAEMONS, BASEMIND_NO_AUTOSPAWN) are listed in
Memory and resources.
Per-Request Overrides
Section titled “Per-Request Overrides”The documents.* overrides are CLI flags and environment variables only; the MCP tools
do not accept them (they used to inflate every session’s tool schema). Set those keys in
basemind.toml. The per-call knobs MCP does expose are the ones that change a single query:
docs_search takes max_tokens, mime_type, scope, entity (needs the documents-ner
feature) and keywords, and code_search takes lane.
Cargo Features
Section titled “Cargo Features”When installing basemind, select which features to compile.
A vanilla cargo install basemind builds the code-map and git tools only (default features off, no
ONNX Runtime). Opt into the rest:
| Feature | Includes | In full |
|---|---|---|
documents |
Document search over local files (xberg): PDF (text layer), Office formats, spreadsheets, email, HTML, XML (SVG text is read as XML), Markdown/MDX and Jupyter notebooks, with chunking, language detection, quality scoring, keywords (YAKE/RAKE), extractive (TextRank) summaries, the cross-encoder reranker and embeddings. No OCR, no NER. | yes |
documents-ocr |
documents plus Tesseract OCR: raster images and scanned PDFs (no text layer). Runs implicitly, no configuration. |
yes |
documents-ner |
documents plus ONNX named-entity recognition (GLiNER): [documents.ner] and the docs_search entity filter. |
yes |
documents-ocr-paddle |
documents-ocr plus PaddleOCR as an optional fallback stage. Source builds only; not in the published binaries. |
no |
memory |
LanceDB-backed shared memory (memory_save, memory_search). |
yes |
code-search |
Hybrid code search — vector + BM25 + exact-symbol lanes (code_search). |
yes |
comms |
Agent-to-agent comms — threads, per-agent inbox, DMs (the agents tool and the workspace CLI listings; Unix domain sockets + Windows named pipes). |
yes |
code-intel |
Scope- and import-resolved JS/TS code_refs resolution (oxc). |
yes |
full |
documents + documents-ocr + documents-ner + memory + code-search + comms + code-intel. |
— |
--features documents alone no longer includes OCR or NER. A source build that wants both uses
--features "documents documents-ocr documents-ner" (or full). Without documents-ocr, raster
images are not indexed as documents and a PDF with no text layer is indexed with no text, with a
warning naming the file and the feature. Without documents-ner, a docs_search call with
entity returns an error naming the feature. Archive extraction, LLM-backed summarization
and HEIC/HEIF, SQLite, WordPerfect, HWP/HWPX and Apple iWork extraction are not in any build.
Installation Examples
Section titled “Installation Examples”# Everything (documents with OCR and NER, memory, code-search, comms)cargo install basemind --features full --locked
# Document search without OCR or NERcargo install basemind --features documents --locked
# Code + git only (smallest build)cargo install basemind --locked
# Code + git + commscargo install basemind --features comms --locked
# Homebrew / npm / pip (all features by default)brew install Goldziher/tap/basemindpnpm add -g basemindpip install basemindPrebuilt downloads (GitHub releases, Homebrew, npm, pip) are built with full, so they include OCR
and NER but not PaddleOCR.
Schema Versioning
Section titled “Schema Versioning”basemind uses RELEASE_MINOR from src/version.rs as the single source of truth for both:
INDEX_SCHEMA_VER— Fjall keyspace format (<cache>/workspaces/<key>/views/<view>/index.fjall/)SCHEMA_VER— msgpack blob format (<cache>/blobs/<hash>.{l1,l2,l3}.msgpack, global + content-addressed)
When either schema changes (a minor version bump), the next basemind scan automatically wipes the old caches and rebuilds from source. Patch releases are always cache-compatible: a change to what extraction should produce for an unchanged file bumps an internal extractor epoch instead, and only the files whose entry or blob predates it are re-extracted. See Upgrading.
Directory Layout
Section titled “Directory Layout”Nothing basemind-owned is written into the repository. State lives in a machine-global cache
(~/.local/share/basemind/ on Linux, ~/Library/Application Support/basemind/ on macOS, or
$BASEMIND_DATA_HOME):
<data>/cache/├── blobs/ # content-addressed, shared by every workspace│ ├── <hash>.l1.msgpack # Outlines (symbols, signatures, imports)│ ├── <hash>.l2.msgpack # Call sites (if eager_l2 = true)│ ├── <hash>.l3.msgpack # Structural hashes│ └── <hash>.{fm,chunk,rref,doc}.msgpack # Frontmatter, code chunks, doc-link refs, documents├── gc.lock # Machine-wide blob sweep lock├── gc-state.json # Last sweep result (shown as `last_gc` by `cache stats`)└── workspaces/<workspace_key>/ # one per worktree root ├── views/<view>/ # `working`, `staged`, ... │ ├── index.msgpack │ └── index.fjall/ # Fjall LSM index ├── lance/ # Vector store (documents, memory, code search) ├── git-history.fjall/ # Precomputed git-history index ├── git-cache/ # Cached git payloads ├── workspace.json # Records the worktree root this key was derived from ├── status.json # File counts + scan age for the statusline └── .lock, .lock.meta # Writer lock and its holderThe cache is safe to delete; basemind scan rebuilds it (basemind cache clear removes parts of it).
Troubleshooting
Section titled “Troubleshooting”Slow first scan? The first scan indexes everything. Re-scans only touch what changed (scan_paths). For large projects, eager_l2 = false under [scan] speeds initial indexing by skipping L2 (call-site) extraction, at the cost of disabling reference search.
basemind serve not starting? Check that basemind is on your PATH (which basemind). In .mcp.json, use the full path if needed: "command": "/path/to/basemind".
Out of disk space? Run basemind cache gc to reclaim blobs no workspace on the machine references (blobs younger than six hours are kept). basemind cache stats shows per-component sizes.
Schema mismatch after upgrade? Run basemind scan to automatically rebuild. Or run basemind cache clear and re-scan. No data loss — everything is rebuilt from source.