Skip to content

Upgrading

An upgrade never asks you to wipe the cache. basemind keeps its index in a machine-global cache (BASEMIND_DATA_HOME, default ~/.local/share/basemind): per-workspace views, LanceDB tables and git history under cache/workspaces/<key>/, and one content-addressed blob store under cache/blobs/ shared by every workspace. The next scan migrates what changed and cleans up what it displaced.

The mode-dispatched MCP tools code, git, memory and admin are replaced by one tool per job. This is a breaking change with no aliases: a call to an old tool name fails. No tool below takes a mode argument. agents is unchanged; the workspace tool is removed. The plugin’s skills, commands, hooks and rules ship in the same release, and the plugin downloads the version-matched binary; update any MCP calls, permission allow-lists and scripts of your own. The tools are always loaded (_meta["anthropic/alwaysLoad"]: true), so an agent calls them directly, with no tool-search round trip. See the MCP tools reference for every argument.

Old New
code outline code_outline {path}
code symbols code_symbols {name}
code expand code_read {path, symbol}
code grep code_grep {pattern} (literal; add regex: true for a regex)
code semantic code_search {query}
code chunk code_read {path, line, end_line} on the hit’s span (the CLI keeps basemind code chunk)
code references code_refs {name}
code callers code_refs {name, path}
code implementations code_refs {name, relation: "implementations"}
code dependents code_refs {name, relation: "importers"}
code definition code_refs {name, relation: "definition", path, line}
code find find_files {query}
code files find_files {}
memory documents docs_search {query}
memory put memory_save {key, value}
memory get memory_search {key}
memory list memory_search {prefix} or memory_search {}
memory search memory_search {query}
memory delete CLI only: basemind memory delete <key>
git recent git_log {}
git touching git_log {path}
git by_path git_log {path: "dir/"}; an arbitrary regex is CLI only: basemind git by-path
git search git_log {query} / git_log {author}
git show git_log {rev}
git symbol_history git_log {path, symbol}
git churn CLI only: basemind git churn
git blame git_blame {path, line, end_line}
git blame_symbol git_blame {path, symbol}
git status git_diff {}
git diff git_diff {path, from, to}
git diff_outline git_diff {path, structural: true}
admin status, repo index_status {}
admin rescan index_rescan {paths?} (full is gone: {} is the whole workspace)
admin cache_stats / gc / cache_clear CLI only: basemind cache stats|gc|clear
admin telemetry CLI only: basemind admin telemetry
workspace workspaces / worktrees / branches CLI only: basemind workspace workspaces|worktrees|branches
workspace claim / release Removed, with the CLI commands: worktree claims enforced nothing and nothing read them
Tool Old New
code_grep path_contains path
code_grep include_context (default on) context (default off)
find_files path_contains path_prefix
docs_search entity_category entity
docs_search keywords_contains keywords
git_blame line_start / line_end line / end_line
git_diff rev_old / rev_new from / to
every tool start_row / end_row in results line / end_line, 1-based
  • mode, on every tool above.
  • format ("toon"): responses are JSON.
  • Hidden aliases such as q, needle and token_budget: only the documented names are accepted.
  • field on commit search: pass query for messages, author for authors.
  • full on index_rescan, and basemind rescan --full: index_rescan {} (basemind rescan with no path) already walks the whole workspace.

The command groups keep their names, and the old subcommands stay as shorthands (code callers, git recent, git blame-symbol, …). New commands mirror the tools: code read (alias expand), code search (alias semantic), code refs (alias references), git log, and git diff with --from / --to / --structural. See the CLI reference.

Old New
code expand <path> <name> code read <path> --symbol <name>
code grep --path-contains <p> code grep --path <p>
code grep <regex> code grep <regex> --regex (the pattern is literal by default)
code grep --no-context default; --context adds the surrounding lines
code files --path-contains <p> code files --path-prefix <p>
code definition <path> <line> code definition <path> <line> <name>
git blame --line-start <n> --line-end <m> git blame --line <n> --end-line <m>
git diff <path> <old> <new> git diff <path> --from <old> --to <new>
git search --field author <x> git log --author <x>
--format json|toon removed; the global --json prints the tool’s JSON
--l2, --body-chars, --hash-mode, --no-embed, --no-files removed
  • code_grep is literal by default. A pattern that relied on regex syntax needs regex: true (--regex). path is a substring of the repo-relative path; a glob is rejected.
  • Lines are 1-based everywhere: line, end_line and column, in arguments and results. Outline, symbol and caller rows used to be 0-based.
  • code_refs matches the exact identifier. name: "open" no longer counts call sites of open_store. Pass match: "substring" for the old behaviour.
  • Unknown arguments are rejected with a did-you-mean suggestion and the accepted list. They used to be dropped silently, so a misspelled filter ran unscoped and reported success.
  • Errors are tool results. A failure the caller can fix comes back with isError: true and text naming the fix, not as a JSON-RPC error.
  • Default token budget. Every list is trimmed to 6000 tokens unless max_tokens says otherwise; a trimmed response sets budgeted and returns next_cursor.
  • git_diff reads the working tree. No arguments returns the status; path alone diffs that file against HEAD.
  • find_files covers documents (markdown, config, PDFs) as well as code.
  • index_status.cache_dir is basemind’s cache directory. It used to report the tree-sitter grammar directory.
  • Results are inline. A server-side Task is returned only for a call still running after 3 s (index_rescan, code_search, docs_search). Fast calls used to come back as background tasks.
  • An empty index is reported, never returned as a plain empty result: the response carries a notice with state: "empty_index".
  • limit: 0 is refused by every tool that takes limit.
  • A filter that selects no file is an error. A path / path_prefix / language that no indexed file passes is refused with what would match (code_grep, find_files), as is a git_log path that no commit touches and that is not on disk. While the index is still being built the empty page comes back with its notice instead.
  • code_grep {regex: true} anchors ^ / $ at every line.
  • Edited and deleted files. code_outline, code_read and code_grep describe an edited file as it is now and say stale: true; code_refs with path returns an error naming index_rescan, and so does every tool for a file deleted since the scan.
  • git_blame {symbol} locates the symbol in the file as it is at rev, not in the working tree.
  • git_log {path, symbol} and git_log with a directory path page past their window: follow next_cursor until it is absent. A symbol or directory nothing has matched so far is named in unmatched, and is an error on the last page.
  • git_diff with a directory. A path ending in / returns the status under it; a directory that does not exist, or one given without the slash, is an error.
  • One vocabulary for a cut. A page that ends at limit sets nothing but next_cursor; the token budget also sets budgeted; a cut the caller did not ask for sets truncated and truncated_reason, with omitted counting the items left out. A client that read truncated as “there is another page” (code_grep, code_symbols, find_files, a memory_search listing) must read next_cursor. truncation_reason (code_grep), total_hunks (git_diff), imports_truncated (code_outline), total_is_partial (code_refs, code_symbols) and partial (git_log search) are gone, and code_read counts bytes in omitted_bytes. The full table is in docs/UPGRADING.md.
  • Telemetry keys are the tool names.

Running two basemind versions side by side

Section titled “Running two basemind versions side by side”

The release after 0.33 moves the daemon’s socket, lock, log and comms store from the comms directory (comms/ under the per-user data directory, or BASEMIND_COMMS_DIR) into a protocol-generation subdirectory, comms/g1/, and its record in the daemon registry from daemons/ to daemons/g1/ under the data directory. On Windows the named pipe is named from a hash of the generation directory, so its name changes too.

  • A 0.33 or older binary and a newer one no longer share a daemon. Each starts its own, and neither contacts or stops the other’s. Before this, every session start by one version stopped (and if needed killed) the other version’s daemon.
  • A 0.33 plugin left installed does not reach the newer version. The plugin launcher of 0.33 and older sends SIGTERM and SIGKILL to every basemind process of another version started from its cache, ~/.cache/basemind/bin/<version>/, each time one of its own sessions starts, and deletes the other version directories there. The newer launcher installs under ~/.cache/basemind/versions/<version>/, which the old launcher neither matches nor deletes, and it never installs into or launches from bin/. Launchers of 0.33 and older still do this to each other, and to a newer binary only if it was put under bin/ by hand; update or remove them. The newer launcher reclaims bin/ once it is abandoned: on each launch it removes a version directory there that was installed more than 14 days ago (BASEMIND_PRUNE_AFTER_DAYS), that no running process was started from and that no install holds the lock for. A 0.33 plugin still in use after that downloads its version again on its next launch. A Homebrew, npm or pip install does not run a launcher.
  • The workspace index, memory notes and git-history stores are not per generation. They are keyed by workspace and admit one daemon at a time. While the daemon of one generation holds a workspace, the daemon of the other cannot serve its index, memory or git history; that lasts until the first daemon lets go (it exits ten minutes after its last client). Two generations side by side is a state to pass through during an upgrade, not one to work in on the same repository.
  • What a session shows while another version holds the repository. With a 0.33 session still open in a repository, a session of the newer version started there comes up without an index. Its initialize waits ten seconds for the index to come free and is then answered by basemind serve itself, so the host shows the server as connected and lists its tools. Each tool call is answered with the retryable error backend_unavailable: another basemind holds this workspace's index (the basemind v0.33.0 daemon, pid 4242). This session connects by itself once that process lets go: a daemon of another basemind version exits when its sessions are closed and it is idle, a command when it finishes (JSON-RPC code -32003); so are requests for resources and prompts. The parentheses name the lock’s holder: a daemon by the version it registered under, any other process by its command (`basemind scan`, pid 4242), and they are left out when the lock records nobody. Closing the old version’s sessions fixes it: that daemon exits ten minutes after its last client, or at once on that version’s basemind comms stop. The waiting session connects on its next retry, at most a minute later, without being restarted by the host, and sends notifications/tools/list_changed.
  • The comms store is not carried over: threads, messages and the agent roster start empty in the new generation. Agents on a 0.33 binary and agents on a newer one do not see each other’s threads.
  • The old daemon exits when its sessions end. Its files (comms.sock, daemon.lock, daemon.pid, daemon.log, http.addr and the store.fjall/ directory with its message history) stay at the top of the comms directory until basemind comms cleanup removes them. That command removes the pre-generation files, and any other generation’s directory, only when no daemon holds the rendezvous’s daemon.lock and its newest file is more than 30 days old (--older-than <days> changes the age, --dry-run lists what would go with sizes). --older-than 0 drops the age test, so the old message store goes as soon as no daemon of that release is running. A directory without a daemon.lock is not taken for a rendezvous and is left as it is, and so is one whose lock cannot be opened. It contacts and signals nothing and never touches the generation of the binary that runs it. Nothing runs it automatically.
  • basemind comms stop --all and basemind comms doctor (with or without --probe) now cover the daemons of their own generation only. To stop or inspect a 0.33 daemon, use the 0.33 binary. doctor says how many daemons of other generations it counted; all of them count toward the ceiling of eight (BASEMIND_MAX_DAEMONS).
  • A client that reads http.addr or daemon.log by path must look in comms/g1/. With BASEMIND_ALLOW_HTTP, the HTTP front-end still prefers 127.0.0.1:51786, but the second daemon to start finds it taken and binds a port the OS assigns: read the port from http.addr (or basemind daemon ensure), never assume it. An address set with BASEMIND_HTTP_ADDR is not substituted.
  • A long BASEMIND_COMMS_DIR has three fewer bytes to spare: the socket is now <dir>/g1/comms.sock, and a Unix socket path is limited to 103 bytes on macOS and 107 on Linux. A path over the limit fails with a message naming the variable.
  • Between versions that share a generation, a running daemon is never killed while it answers. A daemon of the same or a newer release is never asked to stop: it is used, or, when it is newer and speaks another protocol, the older binary fails with a newer basemind comms daemon ... is running and says to update. A basemind serve session that meets this on reconnect answers its pending requests with that message and exits.
  • An older daemon is asked to stop and keeps running if it is serving sessions. When it also speaks another protocol, sessions of the new version get no daemon until it goes: commands fail with a basemind comms daemon from another build ... refused to stop, and a basemind serve session answers each request with that error and retries with a growing back-off (it asks again at most once a minute). Close the sessions of the old version (its daemon exits ten minutes after the last one) or run basemind comms stop, which now reaches a daemon on another protocol version and reports its refusal instead of killing it.
  • A daemon whose store is broken answers every request with a store error. A client that meets one names the store directory and tells you to run basemind comms doctor --probe and basemind comms stop --all.

0.29 bumps the release minor, so the first scan rebuilds the index, and it reshapes the CLI.

  1. Stop the old daemon before the first scan: basemind comms stop (add --all to stop every daemon on the machine). Otherwise the previous binary’s daemon keeps running with the old schema and still owns the index.
  2. Run basemind scan. Each view’s index.msgpack and Fjall index are reset on open and every file is re-extracted, overwriting stale blobs in place; the git cache refills lazily. The LanceDB document tables and the blob store are not wiped, and the scan’s cleanup pass reclaims orphaned blobs. Expect a full-scan duration once.
  3. Re-run basemind hook install. The new hook honours core.hooksPath and linked worktrees, fails open, and it will not overwrite a pre-commit hook it did not write unless you pass --force (the old one is kept as pre-commit.bak).
  4. Update scripts for the renamed commands. No aliases remain:
0.28 0.29
admin status status
admin rescan rescan
admin cache-stats cache stats
admin gc cache gc (deletes; --dry-run reports)
admin cache-clear cache clear (needs --yes outside a terminal)
serve --git-cache-mem, --no-git-cache-disk, --no-watch, --documents-* removed (serve takes no flags)

admin delta, admin checkpoint and admin waste moved to the top level in 0.29 and were removed afterwards, together with admin compress and compress-output; they have no replacement.

The web tool and the basemind web commands (scrape, crawl, map) were removed, with the crawl cargo feature; they have no replacement. A [crawl] table in basemind.toml is still accepted and ignored. Pages already ingested stay searchable under their web:<host> scope (basemind memory documents <query> --scope web:<host>) and are no longer refreshed.

The shell tool and the basemind shell commands (spawn, send, capture, kill, list, broadcast) were removed, with the shells cargo feature; they have no replacement. A [shells] table in basemind.toml is still accepted and ignored. Stop a shells daemon an older version left running before upgrading (basemind shell kill each session, or kill the process); this version cannot talk to it and, since it is registered by an older release, does not list it in basemind comms doctor.

The memory review queue (audit, mine, proposals, accept, reject) and its basemind memory commands were removed; they have no replacement. Stored notes keep every field, including the verdict and importance an audit wrote, which nothing updates any more. Archived notes and pending proposals stay on disk in the repo’s memory.fjall and are never read. The comms protocol version is now 5: the first upgraded session replaces a running older daemon, and a client and daemon that still disagree fail the handshake with proto_skew.

The graph tool and the basemind graph commands (calls, neighbors, path, subgraph, communities, map, export, display, open) were removed, with the basemind://repo/map resource and the daemon’s /ui page; they have no replacement. code_refs answers the who-calls-what questions. The daemon’s HTTP front-end now serves /mcp only and takes the bearer token in the Authorization header only: ?token= is refused.

The documents cargo feature was split into tiers. documents is document search without OCR or named-entity recognition; documents-ocr adds Tesseract OCR (raster images and PDFs with no text layer) and documents-ner adds ONNX named-entity recognition ([documents.ner] and the entity_category filter). full includes all three, so the published binaries are unchanged except that they no longer contain PaddleOCR, which is the source-only documents-ocr-paddle feature. A source build that used --features documents needs --features "documents documents-ocr documents-ner" (or full) to keep OCR and NER. 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, [documents.ner] enabled = true logs a warning and has no effect, and a search with entity_category returns an error. A build with both tiers keeps its cached documents. A build missing a tier extracts every document again on its first scan, and so does the first scan after switching to a binary with a different set of tiers.

Archive extraction, LLM-backed (abstractive) summarization and the LLM NER backend were removed, with HEIC/HEIF, SQLite, WordPerfect, HWP/HWPX and Apple iWork extraction and SVG rasterisation (SVG text is still read as XML); they have no replacement. These settings are still accepted and ignored, each with a one-time warning: [documents] extract_archives = true (archives are always skipped, and BASEMIND_DAEMON_ALLOW_EXTRACT_ARCHIVES has no effect), [documents.summarization] strategy = "abstractive" (extractive summaries are used), [documents.ner] backend = "llm" (no entities are extracted) and a non-empty [llm] table. The --llm-* flags on basemind scan and the BASEMIND_LLM_* variables are accepted and ignored too. max_archive_bytes and max_archive_entries still apply, to the zip containers that Office files are. A config that set [llm] model or extract_archives = true has its documents extracted again once, on the first scan after upgrading; any other config keeps its cached documents.

Also check scripts for these behaviour changes:

  • Exit codes are 0 ok, 1 error, 2 usage, 3 writer lock held, 4 daemon unreachable, 130 interrupted. scan and rescan exit 3 (not 0) when another process holds the lock.
  • The timing footer is on stderr; stdout carries only the answer. Human output no longer truncates values to 200 characters.
  • agents and workspace --json now use the MCP response shapes.
  • MCP logging is gone, and document search no longer accepts the documents.* / llm.* override fields.
Change How it migrates Cost
Prose, data and config files (Markdown, JSON, YAML, TOML, XML, CSV, INI, …) left the code map for the document tier The next scan, full or incremental, notices a path indexed in the other tier, purges its code-map rows and indexes it as a document Documents are chunked, and embedded when [documents] embed is on
Symbol signature now ends at the grammar’s body field instead of embedding the body Only files whose entry or blob predates the new extractor epoch are re-extracted, in the normal memory-bounded scan One parse per affected file, no wipe
Release-minor schema bump (for example 0.28.x to 0.29.x) Each view’s index is reset on open and every file is re-extracted, overwriting stale blobs in place Full re-extraction, by design
Resident term index, name dictionaries, macOS heap retag In memory only None
Daemon IndexRead forwarding for code_refs Wire protocol only None
Code map is code-only; find_files covers documents Same tier migration as the first row See above
Grep bloom filters Built on the next scan; until then code_grep runs the full sweep Small, at scan time

Patch releases keep the persisted format. A change that alters what an unchanged file’s blob should contain, without changing how it is serialized, bumps an internal extractor epoch instead of the release minor. Every file entry and blob records the epoch it was produced under, so only stale files are re-extracted, and the scan summary reports them as refreshed (and tier_migrated for tier moves).

Content-addressed blobs are shared and never rewritten on their own, so a migration can orphan some of them. For example, the old .fm, .chunk and .rref blobs of a Markdown file that became a document kept the same content hash as its live document blob and were pinned forever.

  • The sweep is tier-aware: a document blob is live only if some workspace’s document table references the hash; code-lane blobs are live only if a code-map file entry does.
  • It reference-counts against every workspace on the machine, keeps blobs younger than six hours (a concurrent scan may be about to reference them), and takes a machine-wide cache/gc.lock so two sweeps never run at once. BASEMIND_BLOB_GC_GRACE_SECS overrides the six hours; 0 reclaims every unreferenced blob immediately.
  • A scan that migrated a path, refreshed an extraction, or reset a view for a schema bump runs the sweep itself and prints cleanup: reclaimed N orphaned blob(s), B bytes. In the daemon the same condition triggers a sweep a minute later, and the daemon also sweeps hourly.
  • basemind cache gc performs the same sweep; --dry-run only reports. It used to be report-only.
  • cache stats shows the result as last_gc, and its orphan_blob_count is tier-aware and drops to 0 after the sweep.

A second scan after the upgrade is a no-op: nothing is migrated, refreshed or reclaimed.

basemind cache clear --component blobs|views|lance|git-cache|telemetry|all --yes covers every on-disk component a migration touches. The term index and name dictionaries are memory only. The sweep lock is an empty file removed with the cache root, and git-history.fjall is removed only by all because the daemon holds it open.

Opening upgraded data with an older binary fails safe. The index extras are ignored; a binary on the same schema minor re-maps the files it still treats as code (and drops their document entries), and one on a different minor resets the view and re-extracts, as for any schema change. Going back and forth costs re-extraction, never correctness, and the next sweep reclaims what is left.

The plugin launcher keeps one ~/.cache/basemind/versions/<version>/ per release (XDG_CACHE_HOME replaces ~/.cache) and writes a .last-used marker into the directory of the version it starts, on every launch. On every launch of the current version it removes another version’s directory only when all of these hold: nothing has launched that version for 14 days (BASEMIND_PRUNE_AFTER_DAYS changes the number), no running process was started from it, and no install holds its lock. It removes none when it cannot read the process list (on Git Bash, MSYS2 and Cygwin that is ps -W, with the cache path converted by cygpath). A version directory left under ~/.cache/basemind/bin/ by a launcher up to 0.33 goes by the same rule, judged by the directory’s own age since those launchers write no marker. Install locks and staging directories of other versions go only after ten minutes untouched, a staging directory only when the process installing into it is gone. It does not stop processes of other versions: their sessions and daemons keep running, and a daemon exits on its own once idle. That cache is a few tens of MB per version and is not touched by the migration above.