memory_provider.py 14 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253
  1. """Abstract base class for pluggable memory providers.
  2. Plugins ship in ``plugins/memory/<name>/``, activated via ``memory.provider`` (ONE external
  3. provider at a time). Lifecycle, driven by MemoryManager: initialize -> system_prompt_block /
  4. prefetch / sync_turn per turn -> tool dispatch -> shutdown, plus optional ``on_*`` hooks.
  5. """
  6. from __future__ import annotations
  7. import contextvars
  8. import logging
  9. import re
  10. import threading
  11. from abc import ABC, abstractmethod
  12. from dataclasses import dataclass
  13. from typing import Any, Callable, Dict, List, Optional
  14. logger = logging.getLogger(__name__)
  15. def ctx_bound(fn: Callable[..., Any]) -> Callable[..., Any]:
  16. """Bind ``fn`` to the CALLER's contextvars for another thread/executor. Profile isolation
  17. is a ContextVar-scoped HERMES_HOME override plus the per-turn secret scope; a worker started
  18. with an empty context silently lands on the default profile (or fails closed on secrets)."""
  19. ctx = contextvars.copy_context()
  20. return lambda *args, **kwargs: ctx.run(fn, *args, **kwargs)
  21. def spawn_context_thread(target: Callable[..., Any], *, name: str, daemon: bool = True,
  22. args: tuple = (), kwargs: Optional[dict[str, Any]] = None) -> threading.Thread:
  23. """Unstarted thread running *target* under the spawner's contextvars (see :func:`ctx_bound`).
  24. Every memory-provider background job (prefetch, sync, writer loops) must go through this."""
  25. return threading.Thread(target=ctx_bound(target), args=args, kwargs=kwargs, name=name, daemon=daemon)
  26. # v1 = best-effort on_pre_compress() with the raw message list; v2 = opt-in fail-closed
  27. # checkpoint (normalized evidence handoff + strict-mode failure propagation).
  28. PRE_COMPRESS_CHECKPOINT_API_VERSION = 2
  29. # Default glyph for recall indicators; providers may use their own brand mark.
  30. INDICATOR_GLYPH = "🧠"
  31. # ``memory.provider`` values that mean "the built-in store, no external plugin". The built-in
  32. # store is core: doctor, migration and dependency refresh must never look these up as plugins.
  33. CORE_MEMORY_PROVIDER_SENTINELS = frozenset({"", "default", "builtin", "built-in", "none"})
  34. def is_core_memory_provider(name: Optional[str]) -> bool:
  35. """True when ``memory.provider`` selects the built-in store rather than an external plugin."""
  36. return str(name or "").strip().lower() in CORE_MEMORY_PROVIDER_SENTINELS
  37. @dataclass(frozen=True)
  38. class RecallStatus:
  39. """What the last prefetch injected, for the deterministic recall indicator
  40. (``MemoryManager.describe_recall``). ``count == 0`` means content without a
  41. discrete count (e.g. a synthesized reflect answer) and renders generically."""
  42. provider_label: str
  43. count: int
  44. glyph: str = INDICATOR_GLYPH
  45. # Prompts with no semantic signal; single source of truth for the core prefetch gate and
  46. # provider-side classifiers. Anchored and followed only by whitespace/punctuation, so
  47. # "k8s"/"yolo"/"note" do NOT match while "hi!"/"thanks :)"/"done???" do.
  48. TRIVIAL_PROMPT_RE = re.compile(
  49. r'^(yes|no|ok|okay|sure|thanks|thank you|y|n|yep|nope|yeah|nah|'
  50. r'hi|hey|hello|yo|sup|'
  51. r'continue|go ahead|do it|proceed|got it|cool|nice|great|done|next|lgtm|k)'
  52. r'[\s!?.:;,"' + "'" + r'~\u2018\u2019\u201c\u201d\u2014\u2013\u2026()\[\]{}<>*&^%$#@!+=`\u00a0]*$',
  53. re.IGNORECASE,
  54. )
  55. def is_trivial_prompt(text: Optional[str]) -> bool:
  56. """True for empty input, slash commands and bare greetings/acknowledgements (skipping
  57. recall saves a round-trip and keeps stale context from derailing one-word replies)."""
  58. stripped = (text or "").strip()
  59. if not stripped or stripped.startswith("/"):
  60. return True
  61. return bool(TRIVIAL_PROMPT_RE.match(stripped))
  62. class MemoryProvider(ABC):
  63. """Abstract base class for memory providers.
  64. Multiplexing contract (#140058). One gateway process can serve several profiles, and each agent's
  65. ``MemoryManager`` owns its own provider instance, initialized for one profile. A provider must:
  66. - hand every load a NEW instance (``register(ctx)`` / the loader constructs one per agent). The
  67. manager refuses an instance another profile's manager already bound, rather than rebinding it;
  68. - bind every store, path, client, bank or tenant from ``initialize()``'s ``hermes_home`` (and
  69. scoped secrets read during ``initialize``) and keep that binding on the instance;
  70. - keep no profile-specific mutable state at module or class level, and never "rebind" a shared
  71. binding per call: two profiles' calls interleave on different threads.
  72. The manager runs tool calls and lifecycle hooks only from the profile the instance was initialized
  73. for (refusing callers that name another profile, or none on a multiplexed process), runs its
  74. background hooks under that profile's ``HERMES_HOME``, and passes ``hermes_home`` /
  75. ``agent_identity`` / ``caller_gsk`` to ``handle_tool_call`` when it accepts ``**kwargs``. Those
  76. keywords name the same profile the instance is bound to; they are not a reason to rebind. Core
  77. cannot see inside a provider: one that keeps a process-wide binding still breaks this contract.
  78. """
  79. # Providers that durably checkpoint every successful on_pre_compress() set this to
  80. # PRE_COMPRESS_CHECKPOINT_API_VERSION; 1 = best-effort legacy.
  81. pre_compress_checkpoint_api_version = 1
  82. @property
  83. @abstractmethod
  84. def name(self) -> str:
  85. """Short identifier for this provider (e.g. 'builtin', 'honcho', 'hindsight')."""
  86. # -- Core lifecycle (implement these) ------------------------------------
  87. @abstractmethod
  88. def is_available(self) -> bool:
  89. """Configured, credentialed and ready? Gates activation; check config/deps only, no network."""
  90. @abstractmethod
  91. def initialize(self, session_id: str, **kwargs) -> None:
  92. """Initialize once at agent startup (connections, resources, threads).
  93. kwargs always include ``hermes_home`` (profile-scoped storage; never hardcode
  94. ``~/.hermes``) and ``platform``; may include ``agent_context`` ("primary" |
  95. "subagent" | "cron" | "flush" — skip writes for non-primary contexts),
  96. ``agent_identity``, ``agent_workspace``, ``parent_session_id``, ``user_id``, ``user_id_alt``.
  97. """
  98. def unavailable_reason(self) -> str:
  99. """User-facing hint for the "provider unavailable" warning (``initialize()`` never runs then)."""
  100. return ""
  101. def system_prompt_block(self) -> str:
  102. """STATIC system-prompt text; "" to skip. Recalled context goes through prefetch(), not here."""
  103. return ""
  104. def prefetch(self, query: str, *, session_id: str = "") -> str:
  105. """Formatted recall context for the upcoming turn ("" if none). Must be fast — recall
  106. in the background and return cached results; ``session_id`` scopes concurrent sessions."""
  107. return ""
  108. def queue_prefetch(self, query: str, *, session_id: str = "") -> None:
  109. """Queue a background recall after each turn; prefetch() consumes it next turn."""
  110. def recall_status(self) -> Optional[RecallStatus]:
  111. """What the most recent :meth:`prefetch` injected (``None`` = no indicator). Must reflect
  112. only the LAST prefetch, never a stale prior count."""
  113. return None
  114. def sync_turn(
  115. self, user_content: str, assistant_content: str, *,
  116. session_id: str = "", messages: Optional[list[dict[str, Any]]] = None,
  117. turn_author: Optional[dict[str, Any]] = None,
  118. ) -> None:
  119. """Persist a completed turn (non-blocking). ``messages`` is the OpenAI-style list so far.
  120. ``turn_author`` (``{"id", "name", "is_bot"}``) is who wrote the user side; the manager sends it only to signatures that accept it."""
  121. @abstractmethod
  122. def get_tool_schemas(self) -> list[dict[str, Any]]:
  123. """OpenAI function-calling schemas ({"name", "description", "parameters"}); [] if none."""
  124. def handle_tool_call(self, tool_name: str, args: dict[str, Any], **kwargs) -> str:
  125. """Handle one of this provider's tools; must return a JSON string."""
  126. raise NotImplementedError(f"Provider {self.name} does not handle tool {tool_name}")
  127. def shutdown(self) -> None:
  128. """Clean shutdown — flush queues, close connections."""
  129. # -- Optional hooks (override to opt in) ---------------------------------
  130. def on_turn_start(self, turn_number: int, message: str, **kwargs) -> None:
  131. """Per-turn tick. kwargs may include remaining_tokens, model, platform, tool_count, author_id, author_name,
  132. author_is_bot. The author trio names who wrote THIS turn (None, None, False without one): a shared session
  133. carries several participants, so a provider keying durable state on identity must read it per turn."""
  134. def identity_signature(self) -> dict[str, Any]:
  135. """Identity-mapping values that must bust a cached gateway agent when they change (writer identity, alias
  136. tables, session-name prefixing). Provider-namespaced keys, JSON-serializable values. The gateway calls this
  137. on an uninitialized instance on every inbound message, so keep it cheap and read-only."""
  138. return {}
  139. def on_session_end(self, messages: list[dict[str, Any]]) -> None:
  140. """End-of-session extraction; fires only at real session boundaries, never per-turn."""
  141. def on_session_switch(
  142. self, new_session_id: str, *, parent_session_id: str = "", reset: bool = False, rewound: bool = False, **kwargs,
  143. ) -> None:
  144. """session_id reassigned mid-process (/resume, /branch, /reset, /new, compression)
  145. without teardown: rebind per-session state so later writes land in the right record.
  146. ``reset`` is True only for a genuinely new conversation (flush buffers); ``rewound``:
  147. same id but the transcript was truncated."""
  148. def on_pre_compress(self, messages: list[dict[str, Any]]) -> str:
  149. """Extract insights from ``messages`` about to be compressed, fed into the summary prompt."""
  150. return ""
  151. def on_delegation(self, task: str, result: str, *, child_session_id: str = "", **kwargs) -> None:
  152. """PARENT-side observation of a completed delegation (the subagent has no provider session)."""
  153. def get_config_schema(self) -> list[dict[str, Any]]:
  154. """Setup fields for ``hermes memory setup`` ([] if none): ``key``, ``description``,
  155. optional ``secret`` (goes to .env), ``required``, ``default``, ``choices``, ``type``
  156. (text | integer | number | boolean), ``minimum``/``maximum``/``step``, ``url``,
  157. ``env_var`` (explicit secret env var; default auto-generated)."""
  158. return []
  159. def save_config(self, values: dict[str, Any], hermes_home: str) -> None:
  160. """Write non-secret setup ``values`` to the provider's native config. Plugins MUST either
  161. override this or use only env vars (every schema field carrying ``env_var``)."""
  162. def on_memory_write(self, action: str, target: str, content: str, metadata: Optional[dict[str, Any]] = None) -> None:
  163. """Mirror a built-in memory-tool write (``action``: add | replace | remove; ``target``:
  164. memory | user; ``metadata``: provenance such as write_origin, session_id, tool_name).
  165. For replace/remove, ``metadata["previous_content"]`` is the full entry selected
  166. under the native-store lock. A memory-tool patch arrives as a replace whose
  167. ``content`` is the whole entry after the edit. Notifications follow a successful complete write
  168. or batch; each batch operation sees the preceding operation's result. Older
  169. callers may omit this field: ``old_text`` alone is not authoritative identity.
  170. """
  171. def backup_paths(self) -> list[str]:
  172. """Absolute paths of provider state OUTSIDE HERMES_HOME for ``hermes backup``/``import``
  173. (paths outside the home dir are skipped). MUST work without ``initialize()`` or network."""
  174. return []
  175. # -- Profile lifecycle (uninitialized instance; that profile's home and secrets bound; errors are
  176. # logged). Keep them fast: the dashboard and Desktop run them inside the create/rename request,
  177. # so put network work (creating a remote peer) on a background thread. --
  178. def on_profile_created(self, profile_name: str, hermes_home: str) -> None:
  179. """A profile whose config selects this provider was just created by ``create_profile`` (CLI,
  180. dashboard, Desktop/TUI; a clone carries ``memory.provider``). Not called for profile import.
  181. Set up per-profile provider state here (a peer, a host entry)."""
  182. def on_profile_renamed(self, old_name: str, new_name: str, hermes_home: str) -> None:
  183. """A profile whose config selects this provider was renamed; ``hermes_home`` is its new
  184. directory. Re-key anything the provider stores under the old profile name."""
  185. # -- Dashboard config panel for a ``config_schema.py`` declaring ``storage=STORAGE_PROVIDER`` --
  186. def read_config_fields(self, hermes_home: str) -> dict[str, Any]:
  187. """``{"values": {field key: stored native value}, "placeholders": {field key: text}}``. A key
  188. absent from ``values`` reads as unset; a placeholder shows what a blank field resolves to.
  189. A stored secret may be included: it only marks the field as set and is never sent out."""
  190. return {"values": {}, "placeholders": {}}
  191. def write_config_fields(self, values: dict[str, Any], hermes_home: str) -> None:
  192. """Persist the submitted fields (only those present): natives already coerced, ``None`` clears a
  193. key, non-blank secrets included (core saves each to ``.env`` under its ``env_key`` once this
  194. returns). Raise ``ValueError`` (a subclass such as ``json.JSONDecodeError`` counts, also under
  195. ``plugins.isolation: host``) to refuse the save (the dashboard shows it as a 400)."""
  196. raise NotImplementedError(f"memory provider {self.name} declares storage=provider but cannot write it")