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.
Upgrading to the verb tools (ADR-0018)
Section titled “Upgrading to the verb tools (ADR-0018)”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 tool and mode to new tool
Section titled “Old tool and mode to new tool”| 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 |
Renamed arguments
Section titled “Renamed arguments”| 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 |
Removed arguments
Section titled “Removed arguments”mode, on every tool above.format("toon"): responses are JSON.- Hidden aliases such as
q,needleandtoken_budget: only the documented names are accepted. fieldon commit search: passqueryfor messages,authorfor authors.fullonindex_rescan, andbasemind rescan --full:index_rescan {}(basemind rescanwith no path) already walks the whole workspace.
CLI changes
Section titled “CLI changes”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 |
Behaviour changes
Section titled “Behaviour changes”code_grepis literal by default. A pattern that relied on regex syntax needsregex: true(--regex).pathis a substring of the repo-relative path; a glob is rejected.- Lines are 1-based everywhere:
line,end_lineandcolumn, in arguments and results. Outline, symbol and caller rows used to be 0-based. code_refsmatches the exact identifier.name: "open"no longer counts call sites ofopen_store. Passmatch: "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: trueand text naming the fix, not as a JSON-RPC error. - Default token budget. Every list is trimmed to 6000 tokens unless
max_tokenssays otherwise; a trimmed response setsbudgetedand returnsnext_cursor. git_diffreads the working tree. No arguments returns the status;pathalone diffs that file against HEAD.find_filescovers documents (markdown, config, PDFs) as well as code.index_status.cache_diris 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
noticewithstate: "empty_index". limit: 0is refused by every tool that takeslimit.- A filter that selects no file is an error. A
path/path_prefix/languagethat no indexed file passes is refused with what would match (code_grep,find_files), as is agit_logpaththat no commit touches and that is not on disk. While the index is still being built the empty page comes back with itsnoticeinstead. code_grep {regex: true}anchors^/$at every line.- Edited and deleted files.
code_outline,code_readandcode_grepdescribe an edited file as it is now and saystale: true;code_refswithpathreturns an error namingindex_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 atrev, not in the working tree.git_log {path, symbol}andgit_logwith a directorypathpage past their window: follownext_cursoruntil it is absent. A symbol or directory nothing has matched so far is named inunmatched, and is an error on the last page.git_diffwith a directory. Apathending 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
limitsets nothing butnext_cursor; the token budget also setsbudgeted; a cut the caller did not ask for setstruncatedandtruncated_reason, withomittedcounting the items left out. A client that readtruncatedas “there is another page” (code_grep,code_symbols,find_files, amemory_searchlisting) must readnext_cursor.truncation_reason(code_grep),total_hunks(git_diff),imports_truncated(code_outline),total_is_partial(code_refs,code_symbols) andpartial(git_logsearch) are gone, andcode_readcounts bytes inomitted_bytes. The full table is indocs/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 frombin/. Launchers of 0.33 and older still do this to each other, and to a newer binary only if it was put underbin/by hand; update or remove them. The newer launcher reclaimsbin/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
initializewaits ten seconds for the index to come free and is then answered bybasemind serveitself, so the host shows the server as connected and lists its tools. Each tool call is answered with the retryable errorbackend_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’sbasemind comms stop. The waiting session connects on its next retry, at most a minute later, without being restarted by the host, and sendsnotifications/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.addrand thestore.fjall/directory with its message history) stay at the top of the comms directory untilbasemind comms cleanupremoves them. That command removes the pre-generation files, and any other generation’s directory, only when no daemon holds the rendezvous’sdaemon.lockand its newest file is more than 30 days old (--older-than <days>changes the age,--dry-runlists what would go with sizes).--older-than 0drops the age test, so the old message store goes as soon as no daemon of that release is running. A directory without adaemon.lockis 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 --allandbasemind 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.doctorsays 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.addrordaemon.logby path must look incomms/g1/. WithBASEMIND_ALLOW_HTTP, the HTTP front-end still prefers127.0.0.1:51786, but the second daemon to start finds it taken and binds a port the OS assigns: read the port fromhttp.addr(orbasemind daemon ensure), never assume it. An address set withBASEMIND_HTTP_ADDRis not substituted. - A long
BASEMIND_COMMS_DIRhas 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 runningand says to update. Abasemind servesession 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 abasemind servesession 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 runbasemind 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 --probeandbasemind comms stop --all.
Upgrading from 0.28 to 0.29
Section titled “Upgrading from 0.28 to 0.29”0.29 bumps the release minor, so the first scan rebuilds the index, and it reshapes the CLI.
- Stop the old daemon before the first scan:
basemind comms stop(add--allto stop every daemon on the machine). Otherwise the previous binary’s daemon keeps running with the old schema and still owns the index. - Run
basemind scan. Each view’sindex.msgpackand 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. - Re-run
basemind hook install. The new hook honourscore.hooksPathand 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 aspre-commit.bak). - 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
0ok,1error,2usage,3writer lock held,4daemon unreachable,130interrupted.scanandrescanexit3(not0) 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.
agentsandworkspace--jsonnow use the MCP response shapes.- MCP logging is gone, and document search no longer accepts the
documents.*/llm.*override fields.
What changes on upgrade
Section titled “What changes on upgrade”| 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).
Automatic cleanup
Section titled “Automatic cleanup”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.lockso two sweeps never run at once.BASEMIND_BLOB_GC_GRACE_SECSoverrides the six hours;0reclaims 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 gcperforms the same sweep;--dry-runonly reports. It used to be report-only.cache statsshows the result aslast_gc, and itsorphan_blob_countis tier-aware and drops to0after the sweep.
A second scan after the upgrade is a no-op: nothing is migrated, refreshed or reclaimed.
Clearing and downgrading
Section titled “Clearing and downgrading”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.
Plugin binaries
Section titled “Plugin binaries”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.