Summary
The primary install command in every first-touch doc (README.md, PyPI page, getting-started) is uv tool install memtomem with no extras. [all] in pyproject.toml is onnx,ollama,openai,korean,code,web. A user installing with the primary command silently ships without dense embeddings, LLM providers, the Korean tokenizer, the code chunker, and the Web UI — all of which the same README advertises as features.
This is the docs-layer counterpart to #362 (wizard runtime auto-install for missing extras). The two are orthogonal: #362 catches the problem after the user runs mm init; this issue is about what the landing docs tell them to install in the first place.
Where (verified)
README.md:45 — uv tool install memtomem (no extras)packages/memtomem/README.md:18 — samedocs/guides/getting-started.md:55 — same (Option A)packages/memtomem/pyproject.toml:49 — all = ["memtomem[onnx,ollama,openai,korean,code,web]"]docs/guides/getting-started.md:65 — Option B already offers uv add memtomem[all] as an alternative, implying [all] is the "full" target but the primary path doesn't take it.
Why the silent degrade matters (needs verification on a fresh install)
Each extra corresponds to a feature the README or docs mention. If an extra is missing, the failure mode is a runtime fallback, not an error:
onnx — dense embedder; without it, DenseEmbedder falls back to NoopEmbedder. Hybrid search becomes BM25-only, silently.ollama / openai — LLM providers; query expansion / entity extraction / auto-tag fall back.korean — Kiwi tokenizer; FTS falls back to unicode61, which substantially hurts Korean search quality.code — code chunker; disabled.web — FastAPI + uvicorn; mm web won't run.
The wizard in #362 will eventually catch this if the user runs mm init. But the docs page is what the user reads before touching the CLI, and it currently promises features the primary install doesn't deliver.
Note: the above failure modes are described from memory/code structure and should be double-checked by installing bare memtomem in a clean env and observing which features actually run.
Handled by this issue
Pure documentation. Pick one of the two directions and apply it consistently to the three files above:
Option 1 — Primary install becomes uv tool install "memtomem[all]". The lightweight BM25-only install (uv tool install memtomem) moves into a <details> "minimal install" section with a warning about which features are off.
- Pros: docs match the advertised feature list out of the box.
- Cons: heavier first download (fastembed model on first embed, fastapi, kiwipiepy, openai/ollama SDKs).
Option 2 — Primary install stays uv tool install memtomem. A highlighted bullet immediately under the install command lists what's OFF by default ("no dense search, no web UI, no Korean tokenizer, BM25 only") and points to [all] for the full experience.
- Pros: cheap default install, easier on CI / uvx / first-try contexts.
- Cons: users have to read the bullet and opt in; otherwise they experience BM25-only and may not connect it back to
[all].
Either direction is acceptable; the decision belongs in this issue's discussion or in the resulting PR. What is not acceptable is leaving the mismatch silent.
Explicitly out of scope
Acceptance criteria
File estimate
3–6 files depending on direction (README, PyPI README, getting-started at minimum; mcp-clients and integrations if they also show install commands). No API changes.
Related
Summary
The primary install command in every first-touch doc (
README.md, PyPI page, getting-started) isuv tool install memtomemwith no extras.[all]inpyproject.tomlisonnx,ollama,openai,korean,code,web. A user installing with the primary command silently ships without dense embeddings, LLM providers, the Korean tokenizer, the code chunker, and the Web UI — all of which the same README advertises as features.This is the docs-layer counterpart to #362 (wizard runtime auto-install for missing extras). The two are orthogonal: #362 catches the problem after the user runs
mm init; this issue is about what the landing docs tell them to install in the first place.Where (verified)
README.md:45—uv tool install memtomem(no extras)packages/memtomem/README.md:18— samedocs/guides/getting-started.md:55— same (Option A)packages/memtomem/pyproject.toml:49—all = ["memtomem[onnx,ollama,openai,korean,code,web]"]docs/guides/getting-started.md:65— Option B already offersuv add memtomem[all]as an alternative, implying[all]is the "full" target but the primary path doesn't take it.Why the silent degrade matters (needs verification on a fresh install)
Each extra corresponds to a feature the README or docs mention. If an extra is missing, the failure mode is a runtime fallback, not an error:
onnx— dense embedder; without it,DenseEmbedderfalls back toNoopEmbedder. Hybrid search becomes BM25-only, silently.ollama/openai— LLM providers; query expansion / entity extraction / auto-tag fall back.korean— Kiwi tokenizer; FTS falls back tounicode61, which substantially hurts Korean search quality.code— code chunker; disabled.web— FastAPI + uvicorn;mm webwon't run.The wizard in #362 will eventually catch this if the user runs
mm init. But the docs page is what the user reads before touching the CLI, and it currently promises features the primary install doesn't deliver.Note: the above failure modes are described from memory/code structure and should be double-checked by installing bare
memtomemin a clean env and observing which features actually run.Handled by this issue
Pure documentation. Pick one of the two directions and apply it consistently to the three files above:
Option 1 — Primary install becomes
uv tool install "memtomem[all]". The lightweight BM25-only install (uv tool install memtomem) moves into a<details>"minimal install" section with a warning about which features are off.Option 2 — Primary install stays
uv tool install memtomem. A highlighted bullet immediately under the install command lists what's OFF by default ("no dense search, no web UI, no Korean tokenizer, BM25 only") and points to[all]for the full experience.[all].Either direction is acceptable; the decision belongs in this issue's discussion or in the resulting PR. What is not acceptable is leaving the mismatch silent.
Explicitly out of scope
[all]composition inpyproject.toml— separate packaging discussion. This issue is docs-only.mm initwizard messaging — belongs in mm init: auto-install consistency for python extras + mismatch banner (Phase 2 of #360) #362 or a separate wizard UX issue.Acceptance criteria
File estimate
3–6 files depending on direction (README, PyPI README, getting-started at minimum; mcp-clients and integrations if they also show install commands). No API changes.
Related
mm initwizard auto-install for extras (complementary, do not merge into the same PR)