memory_setup.py 18 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462
  1. """hermes memory setup|status — configure memory provider plugins."""
  2. from __future__ import annotations
  3. import os
  4. import sys
  5. import shlex
  6. from pathlib import Path
  7. from hermes_constants import get_hermes_home
  8. from hermes_cli.secret_prompt import masked_secret_prompt
  9. _CANCELLED = -1
  10. def _curses_select(
  11. title: str, items: list[tuple[str, str]], default: int = 0, *, cancel_returns: int | None = None
  12. ) -> int:
  13. """Interactive single-select with arrow keys."""
  14. from hermes_cli.curses_ui import curses_radiolist
  15. if cancel_returns is None:
  16. cancel_returns = default
  17. display_items = [f"{label} - {desc}" if desc else label for label, desc in items]
  18. result = curses_radiolist(title, display_items, selected=default, cancel_returns=cancel_returns)
  19. _clear_interactive_transition()
  20. return result
  21. def _print_cancelled_setup() -> None:
  22. print("\n Cancelled. No changes saved.\n")
  23. def _clear_interactive_transition() -> None:
  24. """Clear stale curses content before entering a follow-up setup screen."""
  25. if not sys.stdout.isatty():
  26. return
  27. sys.stdout.write("\033[2J\033[H")
  28. sys.stdout.flush()
  29. def _prompt(label: str, default: str | None = None, secret: bool = False) -> str:
  30. """Prompt for a value with optional default and secret masking."""
  31. suffix = f" [{default}]" if default else ""
  32. if secret:
  33. val = masked_secret_prompt(f" {label}{suffix}: ")
  34. else:
  35. sys.stdout.write(f" {label}{suffix}: ")
  36. sys.stdout.flush()
  37. val = sys.stdin.readline().strip()
  38. return val or (default or "")
  39. def memory_provider_dependency_inputs(provider_name: str) -> tuple[dict, dict]:
  40. """Read one candidate declaration for preparation and passive readiness."""
  41. from hermes_cli.plugins_cmd import PluginOperationError, _read_manifest_for_install
  42. from pm.package import InstallError
  43. from pm.plugin_inputs import Candidates
  44. from pm.workspace import _is_member_candidate
  45. from plugins.memory import find_provider_dir
  46. plugin_dir = find_provider_dir(provider_name)
  47. if not plugin_dir:
  48. return {}, {}
  49. try:
  50. meta = _read_manifest_for_install(plugin_dir)
  51. member = _is_member_candidate(plugin_dir)
  52. except (PluginOperationError, OSError, ValueError) as exc:
  53. raise InstallError(provider_name, str(exc)) from exc
  54. extra = meta.get("extra")
  55. extras = [extra] if isinstance(extra, str) and extra else []
  56. if not extras and not member:
  57. return meta, {}
  58. # Without a proposed home, selection retains every configured member.
  59. inputs = {"plugins": Candidates([plugin_dir])} if member else {}
  60. return meta, {"extras": extras, **inputs}
  61. def prepare_memory_provider_dependencies(provider_name: str) -> tuple[dict, str | None]:
  62. """Prepare the candidate union; PM owns constraint and currency checks."""
  63. import pm
  64. meta, inputs = memory_provider_dependency_inputs(provider_name)
  65. if not inputs:
  66. return meta, None
  67. pm.sync_venv(explicit=True, **inputs)
  68. from pm.environments import running_from_selected_environment
  69. from pm.paths import repo_root
  70. return meta, "installed" if running_from_selected_environment(repo_root()) else "restart_required"
  71. def _install_dependencies(provider_name: str) -> None:
  72. """Render CLI preparation and external-sidecar guidance."""
  73. import subprocess
  74. meta, status = prepare_memory_provider_dependencies(provider_name)
  75. if status:
  76. print(f" ✓ Dependencies prepared for {provider_name}")
  77. if status == "restart_required":
  78. print(" Restart Hermes to use the prepared dependencies.")
  79. # Also show external (non-pip) dependencies that are missing.
  80. for dep in meta.get("external_dependencies", []):
  81. check_cmd = dep.get("check", "")
  82. install_cmd = dep.get("install", "")
  83. if check_cmd:
  84. try:
  85. subprocess.run(shlex.split(check_cmd), check=True, capture_output=True, timeout=5)
  86. except Exception:
  87. if install_cmd:
  88. print(f"\n ⚠ '{dep.get('name', '')}' not found. Install with:")
  89. print(f" {install_cmd}")
  90. def _schema_of(provider) -> list:
  91. return provider.get_config_schema() if hasattr(provider, "get_config_schema") else []
  92. def _get_available_providers() -> list:
  93. """Discover memory providers from plugins/memory/ as ``(name, setup_hint, provider)`` tuples."""
  94. try:
  95. from plugins.memory import discover_memory_providers, load_memory_provider
  96. raw = discover_memory_providers()
  97. except Exception:
  98. raw = []
  99. results = []
  100. for name, desc, available in raw:
  101. try:
  102. provider = load_memory_provider(name)
  103. if not provider:
  104. continue
  105. except Exception:
  106. continue
  107. schema = _schema_of(provider)
  108. has_secrets = any(f.get("secret") for f in schema)
  109. has_non_secrets = any(not f.get("secret") for f in schema)
  110. if has_secrets and has_non_secrets:
  111. setup_hint = "API key / local"
  112. elif has_secrets:
  113. setup_hint = "requires API key"
  114. elif not schema:
  115. setup_hint = "no setup needed"
  116. else:
  117. setup_hint = "local"
  118. results.append((name, setup_hint, provider))
  119. return results
  120. def _find_provider(providers: list, provider_name: str):
  121. return next((p for p in providers if p[0] == provider_name), None)
  122. def _catalog_install_hint(provider_name: str):
  123. """The install command for a catalog memory provider that resolves nowhere, else None."""
  124. from plugins.memory import find_provider_dir
  125. from hermes_cli.memory_provider_migration import catalog_install_hint
  126. if not provider_name or find_provider_dir(provider_name) is not None:
  127. return None
  128. return catalog_install_hint(provider_name, category="memory")
  129. def _post_setup_hook(provider, config: dict) -> bool:
  130. """Normalize the ``memory`` block; True when the provider's ``post_setup`` took over (it owns
  131. config, connection test and activation), so the caller must stop."""
  132. if not isinstance(config.get("memory"), dict):
  133. config["memory"] = {}
  134. if hasattr(provider, "post_setup"):
  135. provider.post_setup(str(get_hermes_home()), config)
  136. return True
  137. return False
  138. def cmd_setup_provider(provider_name: str) -> None:
  139. """Run memory setup for a specific provider, skipping the picker."""
  140. from hermes_cli.config import load_config, save_config
  141. match = _find_provider(_get_available_providers(), provider_name)
  142. if not match:
  143. print(f"\n Memory provider '{provider_name}' not found.")
  144. install = _catalog_install_hint(provider_name)
  145. if install:
  146. print(f" It is a catalog plugin that is not installed. Install it with: {install}\n")
  147. else:
  148. print(" Run 'hermes memory setup' to see available providers.\n")
  149. return
  150. name, _, provider = match
  151. _clear_interactive_transition()
  152. _install_dependencies(name)
  153. config = load_config()
  154. if _post_setup_hook(provider, config):
  155. return
  156. # Fallback: generic schema-based setup (same as cmd_setup)
  157. config["memory"]["provider"] = name
  158. save_config(config)
  159. print(f"\n Memory provider: {name}")
  160. print(" Activation saved to config.yaml\n")
  161. def _prompt_schema_fields(name: str, schema: list, provider_config: dict, env_writes: dict) -> bool:
  162. """Walk a provider's config schema, prompting per field. False when the user cancelled."""
  163. print(f"\n Configuring {name}:\n")
  164. for field in schema:
  165. key = field["key"]
  166. desc = field.get("description", key)
  167. default = field.get("default")
  168. # Dynamic default: look up default from another field's value
  169. default_from = field.get("default_from")
  170. if default_from and isinstance(default_from, dict):
  171. ref_value = provider_config.get(default_from.get("field", ""), "")
  172. ref_map = default_from.get("map", {})
  173. if ref_value and ref_value in ref_map:
  174. default = ref_map[ref_value]
  175. is_secret = field.get("secret", False)
  176. choices = field.get("choices")
  177. env_var = field.get("env_var")
  178. url = field.get("url")
  179. when = field.get("when")
  180. if when and isinstance(when, dict) and not all(provider_config.get(k) == v for k, v in when.items()):
  181. continue
  182. if choices and not is_secret:
  183. current = provider_config.get(key, default)
  184. current_idx = choices.index(current) if current and current in choices else 0
  185. sel = _curses_select(
  186. f" {desc}", [(c, "") for c in choices], default=current_idx, cancel_returns=_CANCELLED
  187. )
  188. if sel == _CANCELLED:
  189. _print_cancelled_setup()
  190. return False
  191. provider_config[key] = choices[sel]
  192. elif is_secret:
  193. existing = os.environ.get(env_var, "") if env_var else ""
  194. if existing:
  195. masked = f"...{existing[-4:]}" if len(existing) > 4 else "set"
  196. val = _prompt(f"{desc} (current: {masked}, blank to keep)", secret=True)
  197. else:
  198. if url:
  199. print(f" Get yours at {url}")
  200. val = _prompt(desc, secret=True)
  201. if val and env_var:
  202. env_writes[env_var] = val
  203. else:
  204. effective_default = provider_config.get(key) or default
  205. val = _prompt(desc, default=str(effective_default) if effective_default else None)
  206. if val:
  207. provider_config[key] = val
  208. if env_var and env_var not in env_writes:
  209. env_writes[env_var] = val
  210. return True
  211. def cmd_setup(args) -> None:
  212. """Interactive memory provider setup wizard."""
  213. from hermes_cli.config import load_config, save_config
  214. providers = _get_available_providers()
  215. if not providers:
  216. print("\n No memory provider plugins detected.")
  217. print(" Install a plugin to ~/.hermes/plugins/ and try again.\n")
  218. return
  219. items = [(name, f"— {desc}") for name, desc, _ in providers]
  220. items.append(("Built-in only", "— MEMORY.md / USER.md (default)"))
  221. builtin_idx = len(items) - 1
  222. selected = _curses_select("Memory provider setup", items, default=builtin_idx, cancel_returns=_CANCELLED)
  223. if selected == _CANCELLED:
  224. _print_cancelled_setup()
  225. return
  226. config = load_config()
  227. if not isinstance(config.get("memory"), dict):
  228. config["memory"] = {}
  229. if selected >= len(providers):
  230. config["memory"]["provider"] = ""
  231. save_config(config)
  232. print("\n ✓ Memory provider: built-in only")
  233. print(" Saved to config.yaml\n")
  234. return
  235. name, _, provider = providers[selected]
  236. _clear_interactive_transition()
  237. _install_dependencies(name)
  238. if _post_setup_hook(provider, config):
  239. return
  240. provider_config = config["memory"].get(name, {})
  241. if not isinstance(provider_config, dict):
  242. provider_config = {}
  243. env_writes: dict = {}
  244. schema = _schema_of(provider)
  245. if schema and not _prompt_schema_fields(name, schema, provider_config, env_writes):
  246. return
  247. # Write activation key to config.yaml
  248. config["memory"]["provider"] = name
  249. save_config(config)
  250. if provider_config and hasattr(provider, "save_config"):
  251. try:
  252. provider.save_config(provider_config, str(get_hermes_home()))
  253. except Exception as e:
  254. print(f" Failed to write provider config: {e}")
  255. if env_writes:
  256. _write_env_vars(env_writes)
  257. print(f"\n Memory provider: {name}")
  258. print(" Activation saved to config.yaml")
  259. if provider_config:
  260. print(" Provider config saved")
  261. if env_writes:
  262. print(" API keys saved to .env")
  263. print("\n Start a new session to activate.\n")
  264. def _write_env_vars(
  265. env_writes: dict, hermes_home: str | os.PathLike[str] | None = None) -> None:
  266. """Persist memory-provider env vars through the canonical ``.env`` writer.
  267. Delegates to ``hermes_cli.config.save_env_value`` so every key flows
  268. through the same input-validation gate as every other ``.env`` writer:
  269. the ``_ENV_VAR_NAME_RE`` regex (no malformed identifiers), the
  270. ``_ENV_VAR_NAME_DENYLIST`` (no ``LD_PRELOAD`` / ``PYTHONPATH`` /
  271. ``HERMES_HOME`` / etc.), CR/LF stripping on the value, and the atomic
  272. 0o600-from-creation write (no TOCTOU permission window).
  273. Validation failures (``ValueError`` from ``save_env_value`` — a
  274. denylisted name or an identifier rejected by ``_ENV_VAR_NAME_RE``) are
  275. surfaced and skipped rather than aborting the wizard, so a single bad
  276. key from one schema field doesn't take down the rest of the batch.
  277. Non-validation errors (filesystem failures, permission errors) are
  278. intentionally NOT caught — those indicate the wizard cannot safely
  279. persist any subsequent key either and should propagate.
  280. ``hermes_home`` may be supplied by plugin ``post_setup`` hooks that
  281. already received an explicit home directory (e.g. a non-default
  282. profile). It is applied through the context-local Hermes home override
  283. so ``save_env_value`` still owns the validation, sanitization, and
  284. atomic-write path without mutating global ``os.environ``.
  285. """
  286. from hermes_cli.config import save_env_value
  287. from hermes_constants import reset_hermes_home_override, set_hermes_home_override
  288. token = set_hermes_home_override(hermes_home) if hermes_home is not None else None
  289. try:
  290. for key, val in env_writes.items():
  291. try:
  292. save_env_value(key, val)
  293. except ValueError as exc:
  294. print(f" Skipping {key}: {exc}")
  295. finally:
  296. if token is not None:
  297. reset_hermes_home_override(token)
  298. def _mark(enabled) -> str:
  299. return "enabled ✓" if enabled else "disabled ✗"
  300. def cmd_status(args) -> None:
  301. """Show current memory provider config."""
  302. from hermes_cli.config import load_config
  303. config = load_config()
  304. mem_config = config.get("memory", {})
  305. provider_name = mem_config.get("provider", "")
  306. # Memory tool enablement for the CLI platform via the canonical resolver, respecting the
  307. # check_fn gate when both stores are disabled.
  308. from hermes_cli.tools_config import _get_platform_tools
  309. from tools.memory_tool import check_memory_requirements
  310. cli_tools = _get_platform_tools(config, "cli", include_default_mcp_servers=False)
  311. memory_tool_enabled = ("memory" in cli_tools) and check_memory_requirements()
  312. print("\nMemory status\n" + "─" * 40)
  313. print(" Built-in (MEMORY.md / USER.md):")
  314. print(f" Memory injection: {_mark(mem_config.get('memory_enabled', True))}")
  315. print(f" User profile: {_mark(mem_config.get('user_profile_enabled', True))}")
  316. print(f" Memory tool: {_mark(memory_tool_enabled)}")
  317. print(f" Provider: {provider_name or '(none — built-in only)'}")
  318. providers = _get_available_providers()
  319. match = _find_provider(providers, provider_name)
  320. provider = match[2] if match else None
  321. if provider_name:
  322. provider_config = mem_config.get(provider_name, {})
  323. display_config = provider_config
  324. if provider and hasattr(provider, "get_status_config"):
  325. try:
  326. display_config = provider.get_status_config(provider_config)
  327. except Exception as e:
  328. display_config = dict(provider_config) if isinstance(provider_config, dict) else provider_config
  329. if isinstance(display_config, dict):
  330. display_config["status_config_error"] = str(e)
  331. if display_config:
  332. print(f"\n {provider_name} config:")
  333. for key, val in display_config.items():
  334. print(f" {key}: {val}")
  335. from plugins.memory import parked_provider_notice
  336. parked = parked_provider_notice(provider_name)
  337. if parked:
  338. print(f"\n Plugin: turned off ✗\n {parked}")
  339. elif provider:
  340. print("\n Plugin: installed ✓")
  341. if provider.is_available():
  342. print(" Status: available ✓")
  343. else:
  344. print(" Status: not available ✗")
  345. # All fields with env_var (secret and non-secret)
  346. required_fields = [f for f in _schema_of(provider) if f.get("env_var")]
  347. if required_fields:
  348. print(" Missing:")
  349. for f in required_fields:
  350. env_var = f.get("env_var", "")
  351. url = f.get("url", "")
  352. is_set = bool(os.environ.get(env_var))
  353. line = f" {'✓' if is_set else '✗'} {env_var}"
  354. if url and not is_set:
  355. line += f" → {url}"
  356. print(line)
  357. print(" Note: systemd/gateway services do not inherit ~/.hermes/.env —")
  358. print(" set any variables above in the service environment.")
  359. else:
  360. print("\n Plugin: NOT installed ✗")
  361. install = _catalog_install_hint(provider_name)
  362. if install:
  363. print(f" Install it with: {install}")
  364. else:
  365. print(f" Install the '{provider_name}' memory plugin to ~/.hermes/plugins/")
  366. if providers:
  367. print("\n Installed plugins:")
  368. for pname, desc, _ in providers:
  369. active = " ← active" if pname == provider_name else ""
  370. print(f" • {pname} ({desc}){active}")
  371. print()
  372. def memory_command(args) -> None:
  373. """Route memory subcommands."""
  374. if getattr(args, "memory_command", None) == "setup":
  375. from pm.package import InstallError
  376. provider = getattr(args, "provider", None)
  377. try:
  378. if provider:
  379. cmd_setup_provider(provider)
  380. else:
  381. cmd_setup(args)
  382. except InstallError as exc:
  383. print(f"Memory setup failed: {exc}", file=sys.stderr)
  384. print("Correct the dependency error and retry setup.", file=sys.stderr)
  385. raise SystemExit(1) from exc
  386. else:
  387. cmd_status(args)