__init__.py 14 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285
  1. """ByteRover memory plugin — MemoryProvider interface.
  2. Persistent memory via the ByteRover CLI (``brv``): hierarchical context tree with tiered retrieval
  3. (fuzzy text → LLM-driven search), local-first with optional cloud sync (BRV_API_KEY). Requires the
  4. ``brv`` CLI (npm install -g byterover-cli, or byterover.dev/install.sh). Working directory is
  5. $HERMES_HOME/byterover/ (profile-scoped); ``memory.byterover.auto_extract: false`` disables curate hooks.
  6. """
  7. from __future__ import annotations
  8. import json
  9. import logging
  10. import os
  11. import shutil
  12. import subprocess
  13. import threading
  14. from pathlib import Path
  15. from typing import Any, Dict, List, Optional
  16. from agent.memory_provider import MemoryProvider, spawn_context_thread
  17. from tools.registry import tool_error
  18. logger = logging.getLogger(__name__)
  19. _QUERY_TIMEOUT = 10 # brv query — should be fast
  20. _CURATE_TIMEOUT = 120 # brv curate — may involve LLM processing
  21. _MIN_QUERY_LEN = 10 # noise filters
  22. _MIN_OUTPUT_LEN = 20
  23. _BOOL_WORDS = {**dict.fromkeys(("1", "true", "yes", "on"), True), **dict.fromkeys(("0", "false", "no", "off"), False)}
  24. def _coerce_bool(value: Any, default: bool = False) -> bool:
  25. """bool/number -> truthiness; common true/false words parsed; anything else -> default."""
  26. if isinstance(value, (bool, int, float)):
  27. return bool(value)
  28. return _BOOL_WORDS.get(value.strip().lower(), default) if isinstance(value, str) else default
  29. def _load_plugin_config() -> dict[str, Any]:
  30. """Read ``memory.byterover``; fall back to legacy ``memory.provider_config`` (early docs used it)."""
  31. try:
  32. from hermes_cli.config import load_config
  33. memory_config = load_config().get("memory", {})
  34. except Exception:
  35. return {}
  36. for key in ("byterover", "provider_config") if isinstance(memory_config, dict) else ():
  37. block = memory_config.get(key, {})
  38. if isinstance(block, dict) and (block or key == "provider_config"):
  39. return dict(block)
  40. return {}
  41. def _get_brv_cwd() -> Path:
  42. """Profile-scoped working directory for the brv context tree."""
  43. from hermes_constants import get_hermes_home
  44. return get_hermes_home() / "byterover"
  45. # brv binary resolution (cached, thread-safe): None = unresolved, "" = resolved-missing
  46. _brv_path_lock = threading.Lock()
  47. _cached_brv_path: Optional[str] = None
  48. def _resolve_brv_path() -> Optional[str]:
  49. """Find the brv binary on PATH or well-known install locations (resolved once; lookup is outside the lock)."""
  50. global _cached_brv_path
  51. with _brv_path_lock:
  52. if _cached_brv_path is not None:
  53. return _cached_brv_path or None
  54. candidates = (Path.home() / ".brv-cli/bin/brv", Path("/usr/local/bin/brv"), Path.home() / ".npm-global/bin/brv")
  55. found = shutil.which("brv") or next((str(c) for c in candidates if c.exists()), None)
  56. with _brv_path_lock:
  57. if _cached_brv_path is None:
  58. _cached_brv_path = found or ""
  59. return _cached_brv_path or None
  60. def _brv_child_env(brv_path: str) -> dict[str, str]:
  61. """Env for the ``brv`` child. Under gateway.multiplex_profiles ``os.environ`` holds the
  62. LAUNCH profile's ``.env``; the served profile's ``BRV_*`` (cloud identity) live only in its
  63. secret scope, so they are resolved through the scope — a miss means no cloud key, never
  64. another profile's — and the launch profile's ``.env`` residue is stripped. Outside multiplex
  65. the process env IS this profile's own and is passed through unchanged."""
  66. from agent.secret_scope import UnscopedSecretError, get_secret, is_multiplex_active
  67. from hermes_constants import get_hermes_home_override
  68. from tools.environments.local import build_subprocess_env, strip_launch_profile_env
  69. env = build_subprocess_env(scrub_secrets=False)
  70. if is_multiplex_active():
  71. env = strip_launch_profile_env(env, get_hermes_home_override())
  72. for key in [k for k in env if k.startswith("BRV_")]:
  73. env.pop(key, None)
  74. try:
  75. api_key = get_secret("BRV_API_KEY", "")
  76. except UnscopedSecretError:
  77. api_key = ""
  78. if api_key:
  79. env["BRV_API_KEY"] = api_key
  80. env["PATH"] = str(Path(brv_path).parent) + os.pathsep + env.get("PATH", "")
  81. return env
  82. def _run_brv(args: list[str], timeout: int = _QUERY_TIMEOUT, cwd: str | None = None) -> dict:
  83. """Run a brv CLI command. Returns {success, output, error}."""
  84. global _cached_brv_path
  85. brv_path = _resolve_brv_path()
  86. if not brv_path:
  87. return {"success": False, "error": "brv CLI not found. Install: npm install -g byterover-cli"}
  88. effective_cwd = cwd or str(_get_brv_cwd())
  89. Path(effective_cwd).mkdir(parents=True, exist_ok=True)
  90. env = _brv_child_env(brv_path)
  91. try:
  92. result = subprocess.run(
  93. [brv_path] + args, capture_output=True, text=True, encoding='utf-8', errors='replace',
  94. timeout=timeout, cwd=effective_cwd, env=env, stdin=subprocess.DEVNULL,
  95. check=False,
  96. )
  97. except subprocess.TimeoutExpired:
  98. return {"success": False, "error": f"brv timed out after {timeout}s"}
  99. except FileNotFoundError:
  100. with _brv_path_lock:
  101. _cached_brv_path = None # binary vanished; re-resolve next call
  102. return {"success": False, "error": "brv CLI not found"}
  103. except Exception as e:
  104. return {"success": False, "error": str(e)}
  105. stdout, stderr = result.stdout.strip(), result.stderr.strip()
  106. if result.returncode == 0:
  107. return {"success": True, "output": stdout}
  108. return {"success": False, "error": stderr or stdout or f"brv exited {result.returncode}"}
  109. def _schema(name: str, description: str, arg: str = "", arg_desc: str = "") -> dict:
  110. props = {arg: {"type": "string", "description": arg_desc}} if arg else {}
  111. return {"name": name, "description": description, "parameters": {"type": "object", "properties": props, "required": [arg] if arg else []}}
  112. QUERY_SCHEMA = _schema(
  113. "brv_query", "Search ByteRover's persistent knowledge tree for relevant context. Returns memories, project knowledge, "
  114. "architectural decisions, and patterns from previous sessions. Use for any question where past context would help.",
  115. "query", "What to search for.")
  116. CURATE_SCHEMA = _schema(
  117. "brv_curate", "Store important information in ByteRover's persistent knowledge tree. Use for architectural decisions, bug fixes, "
  118. "user preferences, project patterns — anything worth remembering across sessions. ByteRover's LLM automatically "
  119. "categorizes and organizes the memory.", "content", "The information to remember.")
  120. STATUS_SCHEMA = _schema("brv_status", "Check ByteRover status — CLI version, context tree stats, cloud sync state.")
  121. class ByteRoverMemoryProvider(MemoryProvider):
  122. """ByteRover persistent memory via the brv CLI."""
  123. def __init__(self, config: Optional[dict[str, Any]] = None):
  124. self._config = dict(config) if config is not None else _load_plugin_config()
  125. self._auto_extract = _coerce_bool(self._config.get("auto_extract"), True)
  126. self._cwd, self._session_id, self._turn_count = "", "", 0
  127. self._sync_thread: Optional[threading.Thread] = None
  128. @property
  129. def name(self) -> str:
  130. return "byterover"
  131. def is_available(self) -> bool:
  132. """Check if brv CLI is installed. No network calls."""
  133. return _resolve_brv_path() is not None
  134. def get_config_schema(self):
  135. return [
  136. {"key": "api_key", "description": "ByteRover API key (optional, for cloud sync)", "secret": True,
  137. "env_var": "BRV_API_KEY", "url": "https://app.byterover.dev"},
  138. {"key": "auto_extract", "description": "Automatically curate completed turns and compression/memory hooks",
  139. "default": "true", "choices": ["true", "false"]},
  140. ]
  141. def initialize(self, session_id: str, **kwargs) -> None:
  142. # Bind to the profile the manager names, not the ambient one (multiplexing contract, MemoryProvider).
  143. home = kwargs.get("hermes_home")
  144. cwd = Path(home) / "byterover" if home else _get_brv_cwd()
  145. self._cwd, self._session_id, self._turn_count = str(cwd), session_id, 0
  146. Path(self._cwd).mkdir(parents=True, exist_ok=True)
  147. def system_prompt_block(self) -> str:
  148. if not _resolve_brv_path():
  149. return ""
  150. return ("# ByteRover Memory\nActive. Persistent knowledge tree with hierarchical context.\n"
  151. "Use brv_query to search past knowledge, brv_curate to store important facts, brv_status to check state.")
  152. def _query(self, query: str) -> dict:
  153. return _run_brv(["query", "--", query.strip()[:5000]], timeout=_QUERY_TIMEOUT, cwd=self._cwd)
  154. def _curate(self, content: str) -> dict:
  155. return _run_brv(["curate", "--", content], timeout=_CURATE_TIMEOUT, cwd=self._cwd)
  156. def _curate_in_background(self, content: str, *, name: str, what: str, on_done: str = "") -> threading.Thread:
  157. """Spawn a daemon thread that curates ``content``; failures are logged at debug, never raised."""
  158. def _work():
  159. try:
  160. self._curate(content)
  161. if on_done:
  162. logger.info(on_done)
  163. except Exception as e:
  164. logger.debug("ByteRover %s failed: %s", what, e)
  165. t = spawn_context_thread(_work, name=name)
  166. t.start()
  167. return t
  168. def _auto_extract_enabled(self, what: str) -> bool:
  169. if not self._auto_extract:
  170. logger.debug("ByteRover %s skipped (auto_extract disabled)", what)
  171. return self._auto_extract
  172. def prefetch(self, query: str, *, session_id: str = "") -> str:
  173. """Run brv query synchronously (blocks up to _QUERY_TIMEOUT) so context is ready before the first LLM call."""
  174. if not query or len(query.strip()) < _MIN_QUERY_LEN:
  175. return ""
  176. result = self._query(query)
  177. output = (result.get("output") or "").strip() if result["success"] else ""
  178. return f"## ByteRover Context\n{output}" if len(output) > _MIN_OUTPUT_LEN else ""
  179. def queue_prefetch(self, query: str, *, session_id: str = "") -> None:
  180. """No-op: prefetch() runs synchronously at turn start."""
  181. def sync_turn(self, user_content: str, assistant_content: str, *, session_id: str = "") -> None:
  182. """Curate the conversation turn in background (non-blocking); only substantive turns."""
  183. self._turn_count += 1
  184. if not self._auto_extract_enabled("sync_turn") or len(user_content.strip()) < _MIN_QUERY_LEN:
  185. return
  186. if self._sync_thread and self._sync_thread.is_alive(): # wait for the previous sync so curates don't pile up
  187. self._sync_thread.join(timeout=5.0)
  188. self._sync_thread = self._curate_in_background(f"User: {user_content[:2000]}\nAssistant: {assistant_content[:2000]}",
  189. name="brv-sync", what="sync")
  190. def on_memory_write(self, action: str, target: str, content: str) -> None:
  191. """Mirror built-in memory writes to ByteRover."""
  192. if self._auto_extract_enabled("memory mirror") and action in {"add", "replace"} and content:
  193. label = "User profile" if target == "user" else "Agent memory"
  194. self._curate_in_background(f"[{label}] {content}", name="brv-memwrite", what="memory mirror")
  195. def on_pre_compress(self, messages: list[dict[str, Any]]) -> str:
  196. """Extract insights from the last 10 user/assistant messages before compression discards them."""
  197. if not self._auto_extract_enabled("pre-compression flush") or not messages:
  198. return ""
  199. parts = [f"{msg.get('role', '')}: {msg.get('content', '')[:500]}" for msg in messages[-10:]
  200. if msg.get("role", "") in {"user", "assistant"} and isinstance(msg.get("content", ""), str) and msg.get("content", "").strip()]
  201. if parts:
  202. self._curate_in_background("[Pre-compression context]\n" + "\n".join(parts), name="brv-flush", what="pre-compression flush",
  203. on_done=f"ByteRover pre-compression flush: {len(parts)} messages")
  204. return ""
  205. def get_tool_schemas(self) -> list[dict[str, Any]]:
  206. return [QUERY_SCHEMA, CURATE_SCHEMA, STATUS_SCHEMA]
  207. def handle_tool_call(self, tool_name: str, args: dict, **kwargs) -> str:
  208. if tool_name not in _TOOLS:
  209. return tool_error(f"Unknown tool: {tool_name}")
  210. arg, fail_msg, run, on_ok = _TOOLS[tool_name]
  211. value = args.get(arg, "") if arg else None
  212. if arg and not value:
  213. return tool_error(f"{arg} is required")
  214. result = run(self, value)
  215. return json.dumps(on_ok(result.get("output", ""))) if result["success"] else tool_error(result.get("error", fail_msg))
  216. def shutdown(self) -> None:
  217. if self._sync_thread and self._sync_thread.is_alive():
  218. self._sync_thread.join(timeout=10.0)
  219. def _format_query_output(output: str) -> dict:
  220. output = output.strip()
  221. if len(output) < _MIN_OUTPUT_LEN:
  222. return {"result": "No relevant memories found."}
  223. return {"result": output[:8000] + "\n\n[... truncated]" if len(output) > 8000 else output}
  224. # tool name -> (required arg or None, failure message, run(provider, arg_value) -> brv result, on_ok(output) -> JSON payload)
  225. _TOOLS = {
  226. "brv_query": ("query", "Query failed", lambda p, q: p._query(q), _format_query_output),
  227. "brv_curate": ("content", "Curate failed", lambda p, c: p._curate(c), lambda _: {"result": "Memory curated successfully."}),
  228. "brv_status": (None, "Status check failed", lambda p, _: _run_brv(["status"], timeout=15, cwd=p._cwd), lambda out: {"status": out}),
  229. }
  230. def register(ctx) -> None:
  231. """Register ByteRover as a memory provider plugin."""
  232. ctx.register_memory_provider(ByteRoverMemoryProvider())