fix(hindsight): actionable error when local_embedded runtime is missing (#7718)

[benfrank241]

Addresses #7718.

Background (verified against PyPI)

local_embedded runs from hindsight import HindsightEmbedded. I confirmed against the published wheels (0.8.5):

• hindsight-all ships the top-level hindsight/ package — hindsight/__init__.py does from .embedded import HindsightEmbedded and exports it in __all__. This is the only package that satisfies the import.
• hindsight-embed ships only hindsight_embed/ — no top-level hindsight, no HindsightEmbedded class (its deps are just httpx + rich).
• hindsight-client (what plugin.yaml declares) provides hindsight_client.* — enough for cloud / local_external only.

So a user who selects local_embedded without running hermes memory setup (hand-written config, the legacy "mode": "local" alias, or a restored backup — the wizard is the only path that installs hindsight-all) hits ModuleNotFoundError: No module named 'hindsight'.

What main already does vs. what's missing

initialize() already calls _check_local_runtime() and, when the import fails, logs one warning and disables the provider — so the silent per-sync memory loss and fake-healthy INFO log from the original v0.8.0 report are already gone. What's missing is that the warning just echoes No module named 'hindsight' with no fix.

Change

Add _local_runtime_hint() and append it to the disable warning. When the failure is a missing hindsight / hindsight_embed module, the user now sees:

Hindsight local mode disabled because its runtime could not be imported: No module named 'hindsight'. Install the embedded runtime with: uv pip install --python <exe> hindsight-all — or run hermes memory setup. (local_embedded needs the 'hindsight-all' package, which provides the top-level 'hindsight' module; 'hindsight-client' alone only covers cloud / local_external.)

Unrelated runtime failures (e.g. the NumPy-on-old-CPU case _check_local_runtime also guards) get no hint, so the message stays accurate.

Why not declare hindsight-all in plugin.yaml? It pulls the full server stack (hindsight-api-slim[all], torch/sentence-transformers). Declaring it unconditionally would bloat every cloud-only install with hundreds of MB they don't need. A runtime hint fixes the diagnosis for local users without penalizing the majority. (A mode-conditional pip_dependencies mechanism would be the clean long-term fix, but that's a plugin-loader change out of scope here.)

Tests

tests/plugins/memory/test_hindsight_local_runtime_hint.py:

• missing hindsight / hindsight_embed → hint names hindsight-all + hermes memory setup + the interpreter path
• unrelated errors (and None) → no hint

scripts/run_tests.sh tests/plugins/memory/test_hindsight_local_runtime_hint.py   # 3 passed

(The 2 pre-existing test_hindsight_provider.py::TestAvailability/TestConfig failures reproduce on a clean main and are unrelated.)

Note on #57243

#57243 targets the same issue but adds hindsight-embed to plugin.yaml to satisfy the import. Per the wheel contents above, hindsight-embed provides neither the top-level hindsight module nor HindsightEmbedded, so that approach would still ModuleNotFoundError. Flagging so the two aren't merged in conflict.

[benfrank241]

Superseded by the combined PR #74379 — same changes bundled into a single review surface. Closing this one to consolidate.