Installation

Requirements

• Go 1.26 or later
• Git (required for worktree isolation and auto-checkpoint features)

Embedding service memory

The local embedding sidecar (bmo-embedding) launches as a separate process when the embedding service is first used. The sidecar (ONNX Runtime inference session, vector index, and tokenizer vocabulary) uses approximately 500–700 MB of RAM in its own process when active. The main BMO binary’s memory footprint is separate and significantly smaller.

The sidecar starts lazily: it launches only when [options.embedding] is enabled (the default) and a semantic_search or find_similar_code tool call is first made. Until then it consumes no memory.

On machines with less than 2 GB of available RAM, consider disabling the embedding service:

[options.embedding]
enabled = false

Disabling the embedding service does not affect persistent-memory embeddings ([options.persistent_memory.embeddings]), which use a separate code path and can delegate to remote providers.

Install with Go

go install github.com/instagrim-dev/bmo@<release-tag>

Replace <release-tag> with the reviewed version from the GitHub release page (for example vX.Y.Z). Public installs are intentionally tag-first so the binary you install, the release notes you read, and the evidence bundle you verify all refer to the same release.

What you should see: Go downloads, compiles, and places the bmo binary in $GOPATH/bin (usually ~/go/bin) with no errors.

Recovery: If the install fails with a network error, check your internet connection and Go proxy settings (go env GOPROXY). If you see permission errors, verify that $GOPATH/bin is writable.

Public installs do not require GOPRIVATE, GONOSUMDB, or Git URL rewrites. Only private, unreleased github.com/instagrim-dev/* checkouts still need manual Go/Git private-module configuration.

The bmo binary is placed in $GOPATH/bin (or ~/go/bin). Make sure that directory is on your $PATH.

Verify the installation

bmo --version

What you should see: A version string like bmo v0.x.y. If the command is not found, add $GOPATH/bin to your $PATH (e.g., export PATH="$PATH:$(go env GOPATH)/bin").

Update BMO

go install github.com/instagrim-dev/bmo@<release-tag>

bmo update-providers does not upgrade the BMO binary. It only refreshes the provider/model catalog metadata:

bmo update-providers

Verify it worked: Run bmo --version after updating to confirm the new version. Run bmo update-providers and check for a success message to confirm the catalog refreshed.

Config and data directories

By default, BMO reads global config from ~/.config/bmo/bmo.toml and stores runtime data under ~/.local/share/bmo/. If an existing bmo.json is present, BMO still loads it as a fallback, but TOML is the canonical format for new configs.

Override these with environment variables:

BMO_GLOBAL_CONFIG=/custom/config-dir
BMO_GLOBAL_DATA=/custom/data-dir

BMO_GLOBAL_CONFIG points at the directory that should contain bmo.toml. BMO_GLOBAL_DATA points at the data directory.

Run bmo dirs, bmo dirs config, and bmo dirs data to print the active directories for your installation.

Verify it worked: Run bmo dirs and confirm the printed paths match your overrides (or the defaults if you have not set overrides).

Recovery: To reset to defaults, unset the environment variables: unset BMO_GLOBAL_CONFIG BMO_GLOBAL_DATA.

Project-local data

BMO stores session data and logs in a .bmo/ directory under your project root. Add it to .gitignore if you don’t want to commit it:

echo ".bmo/" >> .gitignore

Warning: deleting .bmo/ removes all BMO session history and local logs for that project. Only run this when you intentionally want to reset local BMO state.

Undo/reset command: rm -rf .bmo/

Versioning

See Versioning for details on release channels, semver policy, and upgrade notes.