uv install/upgrade silently resolves to 0.22.1 — 0.23.2 pins a prerelease (fastmcp==4.0.0b1)

[nellins]

Summary

uv tool install basic-memory / uv tool upgrade basic-memory silently resolves to 0.22.1 instead of the latest 0.23.2, because 0.23.2 pins a prerelease dependency and uv excludes prereleases by default.

Repro

$ uv tool upgrade basic-memory
...
Installed 2 executables: basic-memory, bm
$ bm --version
Basic Memory version: 0.22.1        # expected 0.23.2

Asking for it explicitly explains why:

$ uv tool install "basic-memory==0.23.2" --force
  × No solution found when resolving dependencies:
  ╰─▶ Because there is no version of fastmcp==4.0.0b1 and basic-memory==0.23.2
      depends on fastmcp==4.0.0b1, we can conclude that basic-memory==0.23.2
      cannot be used.

      hint: `fastmcp` was requested with a pre-release marker (e.g.,
      fastmcp==4.0.0b1), but pre-releases weren't enabled (try:
      `--prerelease=allow`)

Works only with the extra flag:

$ uv tool install "basic-memory==0.23.2" --force --prerelease=allow
$ bm --version
Basic Memory version: 0.23.2

Why this matters beyond one machine

1. The upgrade path fails silently. No error, no warning — the user believes they're current and is a release behind. I only noticed because the version didn't match what the docs described.
2. The harness plugins are affected. Both the OpenClaw and Hermes plugins auto-install the CLI via uv tool install basic-memory on first start. They'll install 0.22.1 while the docs document v0.23 behavior.
3. Docs assume v0.23. Anyone following current docs against a silently-0.22.1 install may hit behavior mismatches.

Suggested fix

Depend on a stable fastmcp release rather than 4.0.0b1, so the default resolver path works. Failing that, document the --prerelease=allow requirement prominently in the install instructions and in the harness plugin pages.

Environment

macOS, uv-managed tool install, Python 3.13.1. Observed 2026-08-26 upgrading 0.15.0 → latest.

---

Filed on behalf of Drew.

[claude]

Claude finished @nellins's task in 35s —— View job

---

Triage

Type: Bug — pyproject.toml:32 pins fastmcp==4.0.0b1 (a prerelease), and constraint-dependencies (line 153) pins fastmcp-slim==4.0.0b1 too. Since uv/pip exclude prereleases by default, uv tool install/upgrade basic-memory can't resolve 0.23.2 and silently falls back to the last version (0.22.1) whose dependency tree resolves without --prerelease=allow. Confirmed the repro is consistent with current main.

Priority: High — the upgrade path fails with no error or warning, so affected users are silently left a release behind. This also affects the OpenClaw and Hermes plugin harnesses, which both auto-install the CLI via plain uv tool install basic-memory, so they'd provision 0.22.1 against docs written for 0.23.

Component: Packaging/dependencies (CLI install path); not cloud-specific.

Complexity: Simple-to-medium — pin fastmcp to a stable release if one satisfies the code's requirements, or otherwise document the --prerelease=allow requirement in install docs and the harness plugin pages. Needs an audit of what 4.0.0b1-specific behavior/API surface basic-memory actually depends on before downgrading to a stable fastmcp.

Duplicate check: No existing open/closed issue found for this (fastmcp prerelease pin / silent uv resolution).

Labeled bug, no cloud-component label applied.