agent_init_memory_provider.py 4.2 KB

12345678910111213141516171819202122232425262728293031323334353637383940414243444546474849505152535455565758596061626364656667686970717273747576777879808182
  1. """Resolve the configured memory provider at agent init, telling the user once why it will not run."""
  2. from __future__ import annotations
  3. import logging
  4. logger = logging.getLogger("run_agent")
  5. # Deduped: the gateway builds a fresh AIAgent per message, so it would warn every turn.
  6. _warned_unavailable_providers: set[tuple[str, str, str]] = set()
  7. def _unavailable_warning_key(name: str, kind: str = "unavailable") -> tuple[str, str, str]:
  8. """Once per profile home, provider and kind of trouble: one multiplexed gateway/Desktop backend
  9. serves several profiles, each one running without its memory must be told, and a provider the
  10. user turns back on that is then unavailable is news even after the "turned off" notice."""
  11. from hermes_constants import get_hermes_home, hermes_home_key
  12. return hermes_home_key(get_hermes_home()), name, kind
  13. def _warn_once(name: str, message: str, say=None, kind: str = "unavailable") -> None:
  14. """Log *message* and hand it to the user's sink once per home, provider and kind."""
  15. key = _unavailable_warning_key(name, kind)
  16. if key in _warned_unavailable_providers:
  17. return
  18. _warned_unavailable_providers.add(key)
  19. logger.warning(message)
  20. if say is not None:
  21. say(message)
  22. def _warn_memory_provider_unavailable(name: str, reason: str = "", say=None) -> None:
  23. """Warn once per home and provider that a configured memory provider is unavailable.
  24. ``is_available()`` is a side-effect-free hot-path check and can't log itself; without this
  25. the provider is silently dropped. ``reason`` (the provider's ``unavailable_reason()`` hint)
  26. can only reach the user here, so it is appended when present. *say* is the agent's
  27. user-facing sink: a log line alone leaves the user running without memory unaware.
  28. """
  29. _warn_once(name, (
  30. f"⚠ Memory provider {name!r} is selected but reports unavailable — external memory "
  31. "is disabled for this session (built-in memory still works). Check the "
  32. "provider's credentials/config with 'hermes memory status'. Note: "
  33. "systemd/gateway services do not inherit ~/.hermes/.env automatically; set "
  34. f"any required variables in the service environment.{f' {reason}' if reason else ''}"
  35. ), say=say)
  36. def resolve_memory_provider(name: str, say=None):
  37. """The configured provider ready to add, or None after telling the user why not (once per home)."""
  38. from plugins.memory import find_provider_dir, load_memory_provider, parked_provider_notice
  39. provider = load_memory_provider(name)
  40. if provider is None:
  41. parked = parked_provider_notice(name)
  42. if parked:
  43. # Installed but turned off (by the user or by an update): say so, never re-install it.
  44. _warn_once(name, parked, say=say, kind="parked")
  45. return None
  46. if find_provider_dir(name) is None:
  47. # The provider left core for the catalog (or was never installed): fetch it once.
  48. from hermes_cli.memory_provider_migration import recover_at_startup
  49. if recover_at_startup(name, say=say):
  50. provider = load_memory_provider(name)
  51. # Installed (now or before) yet not loading: neither "not installed" nor an install notice explains that.
  52. if provider is None and find_provider_dir(name) is not None:
  53. _warn_once(name, f"⚠ Memory provider '{name}' is installed but failed to load, so external memory is off "
  54. "for this session (built-in memory still works). The log names the error; "
  55. "`hermes memory status` shows the plugin's state.", say=say, kind="load")
  56. if provider is None or provider.is_available():
  57. return provider
  58. if _unavailable_warning_key(name) not in _warned_unavailable_providers:
  59. # unavailable_reason() reads config/probes importlib — skip it once warned.
  60. reason = ""
  61. try:
  62. reason = provider.unavailable_reason()
  63. except Exception: # health: allow BLE001 -- a provider's own hint must never break agent init
  64. logger.debug("unavailable_reason() failed for %s", name, exc_info=True)
  65. _warn_memory_provider_unavailable(name, reason, say=say)
  66. return None