Summary

A fresh uv tool install memtomem can install a stale version because uv caches PyPI index metadata. First-time users may end up on an older release without realising it, hit a bug that was already fixed, and have no in-docs signal that --refresh exists.

Where (verified)

• README.md:45 — uv tool install memtomem # or: pipx install memtomem
• packages/memtomem/README.md:18 — uv tool install memtomem # or: pipx install memtomem
• docs/guides/getting-started.md:55 — uv tool install memtomem # or: pipx install memtomem
• grep -rn -- "--refresh" README.md packages/memtomem/README.md docs/ → 0 hits across all public docs.
• No version-verify step (e.g. mm --version) appears in the install section of any of the three landing docs.

Why (hypothesis, not verified end-to-end)

uv caches the PyPI index metadata per package. When a new memtomem version is published, the cached metadata can still point at the previous version for some window; uv tool install memtomem then resolves to the cached entry. Observed in practice around the v0.1.22/v0.1.23 releases. With v0.1.24 published on 2026-04-22, a first-time install right now is susceptible.

Mitigations at install time:

• uv tool install memtomem --refresh — forces metadata re-fetch.
• uv cache clean memtomem then re-run install — clears the cached entry.

Neither is currently discoverable from memtomem's own docs.

Handled by this issue

Docs-only, in all three first-touch surfaces:

• README.md (repo landing)
• packages/memtomem/README.md (PyPI page)
• docs/guides/getting-started.md

Add a short callout next to the primary install command and a mm --version verify step.

Sample wording (not final):

uv caches PyPI metadata. If mm --version doesn't show the expected version right after install, re-run with --refresh or clear the cache: uv cache clean memtomem.

Explicitly out of scope

• CLI self-check comparing installed version against PyPI at runtime — that's a separate enhancement and would add a network call to mm startup.
• Changing the primary install command's extras — tracked in mm init: auto-install consistency for python extras + mismatch banner (Phase 2 of #360) #362 (wizard runtime auto-install) and in a separate docs issue on [all].

Acceptance criteria

• --refresh and uv cache clean memtomem appear adjacent to the primary install command in all three files above.
• A mm --version verify step exists in at least one of the files (ideally the getting-started doc).
• No code changes.

File estimate

3 files, ≤10 lines total. Eligible as good first issue.