߲j'\dZddlmZddlZddlZddlZddlZddlmZm Z ddl m Z ddl m Z mZmZmZmZej$eZddZdd dd  dd Zd Zd ZehdZddZe dGddZej:dej<ZddZ GddeZ!y)aHAbstract base class for pluggable memory providers. Plugins ship in ``plugins/memory//``, activated via ``memory.provider`` (ONE external provider at a time). Lifecycle, driven by MemoryManager: initialize -> system_prompt_block / prefetch / sync_turn per turn -> tool dispatch -> shutdown, plus optional ``on_*`` hooks. ) annotationsN)ABCabstractmethod) dataclass)AnyCallableDictListOptionalc:tjfdS)aBind ``fn`` to the CALLER's contextvars for another thread/executor. Profile isolation is a ContextVar-scoped HERMES_HOME override plus the per-turn secret scope; a worker started with an empty context silently lands on the default profile (or fails closed on secrets).c0jg|i|SN)run)argskwargsctxfns :/home/ubuntu/.hermes/hermes-agent/agent/memory_provider.pyzctx_bound..s73772#?#?#?) contextvars copy_context)rrs`@r ctx_boundrs  " " $C ??rT)daemonrrcHtjt|||||S)zUnstarted thread running *target* under the spawner's contextvars (see :func:`ctx_bound`). Every memory-provider background job (prefetch, sync, writer loops) must go through this.)targetrrnamer) threadingThreadr)rrrrrs rspawn_context_threadr!s$   9V#44UYbh iiru🧠>built-innonebuiltindefaultcdt|xsdjjtvS)zXTrue when ``memory.provider`` selects the built-in store rather than an external plugin.r$)strstriplowerCORE_MEMORY_PROVIDER_SENTINELS)rs ris_core_memory_providerr-/s( tzr? " ( ( *.L LLr)frozenc4eZdZUdZded<ded<eZded<y) RecallStatuszWhat the last prefetch injected, for the deterministic recall indicator (``MemoryManager.describe_recall``). ``count == 0`` means content without a discrete count (e.g. a synthesized reflect answer) and renders generically.r)provider_labelintcountglyphN)__name__ __module__ __qualname____doc____annotations__INDICATOR_GLYPHr4rrrr0r04sS J E3 rr0z^(yes|no|ok|okay|sure|thanks|thank you|y|n|yep|nope|yeah|nah|hi|hey|hello|yo|sup|continue|go ahead|do it|proceed|got it|cool|nice|great|done|next|lgtm|k)[\s!?.:;,"'~\u2018\u2019\u201c\u201d\u2014\u2013\u2026()\[\]{}<>*&^%$#@!+=`\u00a0]*$c|xsdj}|r|jdryttj |S)zTrue for empty input, slash commands and bare greetings/acknowledgements (skipping recall saves a round-trip and keeps stale context from derailing one-word replies).r$/T)r* startswithboolTRIVIAL_PROMPT_REmatch)textstrippeds ris_trivial_promptrCKs@ !!#H x**3/ !''1 22rcFeZdZdZdZeed dZed!dZed"dZ d dZ d dZ dd d#d Z dd d$d Z d%d Zdd d d d&dZed'dZd(dZd)dZd*dZd+dZd,dZdddd d-dZd.dZddd/dZd'dZd0dZd1d2dZd3dZy )4MemoryProviderz)Abstract base class for memory providers.cy)zKShort identifier for this provider (e.g. 'builtin', 'honcho', 'hindsight').Nrselfs rrzMemoryProvider.name[rcy)zYConfigured, credentialed and ready? Gates activation; check config/deps only, no network.NrrHs r is_availablezMemoryProvider.is_availablebrJrc y)uInitialize once at agent startup (connections, resources, threads). kwargs always include ``hermes_home`` (profile-scoped storage; never hardcode ``~/.hermes``) and ``platform``; may include ``agent_context`` ("primary" | "subagent" | "cron" | "flush" — skip writes for non-primary contexts), ``agent_identity``, ``agent_workspace``, ``parent_session_id``, ``user_id``, ``user_id_alt``. Nr)rI session_idrs r initializezMemoryProvider.initializefrJrcy)z[User-facing hint for the "provider unavailable" warning (``initialize()`` never runs then).r$rrHs runavailable_reasonz!MemoryProvider.unavailable_reasonprcy)zZSTATIC system-prompt text; "" to skip. Recalled context goes through prefetch(), not here.r$rrHs rsystem_prompt_blockz"MemoryProvider.system_prompt_blocktrRrr$)rNcy)uFormatted recall context for the upcoming turn ("" if none). Must be fast — recall in the background and return cached results; ``session_id`` scopes concurrent sessions.r$rrIqueryrNs rprefetchzMemoryProvider.prefetchxsrcy)zLQueue a background recall after each turn; prefetch() consumes it next turn.NrrVs rqueue_prefetchzMemoryProvider.queue_prefetch}rJrcy)zWhat the most recent :meth:`prefetch` injected (``None`` = no indicator). Must reflect only the LAST prefetch, never a stale prior count.NrrHs r recall_statuszMemoryProvider.recall_statussrN)rNmessages turn_authorcy)zPersist a completed turn (non-blocking). ``messages`` is the OpenAI-style list so far. ``turn_author`` (``{"id", "name", "is_bot"}``) is who wrote the user side; the manager sends it only to signatures that accept it.Nr)rI user_contentassistant_contentrNr]r^s r sync_turnzMemoryProvider.sync_turnrJrcy)zTOpenAI function-calling schemas ({"name", "description", "parameters"}); [] if none.NrrHs rget_tool_schemaszMemoryProvider.get_tool_schemasrJrc 8td|jd|)z?Handle one of this provider's tools; must return a JSON string.z Provider z does not handle tool )NotImplementedErrorr)rI tool_namerrs rhandle_tool_callzMemoryProvider.handle_tool_calls!Idii[8Nyk"Z[[rcy)u3Clean shutdown — flush queues, close connections.NrrHs rshutdownzMemoryProvider.shutdownrJrc y)aGPer-turn tick. kwargs may include remaining_tokens, model, platform, tool_count, author_id, author_name, author_is_bot. The author trio names who wrote THIS turn (None, None, False without one): a shared session carries several participants, so a provider keying durable state on identity must read it per turn.Nr)rI turn_numbermessagers r on_turn_startzMemoryProvider.on_turn_startrJrciS)a9Identity-mapping values that must bust a cached gateway agent when they change (writer identity, alias tables, session-name prefixing). Provider-namespaced keys, JSON-serializable values. The gateway calls this on an uninitialized instance on every inbound message, so keep it cheap and read-only.rrHs ridentity_signaturez!MemoryProvider.identity_signatures  rcy)zQEnd-of-session extraction; fires only at real session boundaries, never per-turn.NrrIr]s ron_session_endzMemoryProvider.on_session_endrJrF)parent_session_idresetrewoundc y)a<session_id reassigned mid-process (/resume, /branch, /reset, /new, compression) without teardown: rebind per-session state so later writes land in the right record. ``reset`` is True only for a genuinely new conversation (flush buffers); ``rewound``: same id but the transcript was truncated.Nr)rInew_session_idrtrurvrs ron_session_switchz MemoryProvider.on_session_switchrJrcy)zWExtract insights from ``messages`` about to be compressed, fed into the summary prompt.r$rrrs ron_pre_compresszMemoryProvider.on_pre_compressrRr)child_session_idc y)zYPARENT-side observation of a completed delegation (the subagent has no provider session).Nr)rItaskresultr|rs r on_delegationzMemoryProvider.on_delegationrJrcgS)aLSetup fields for ``hermes memory setup`` ([] if none): ``key``, ``description``, optional ``secret`` (goes to .env), ``required``, ``default``, ``choices``, ``type`` (text | integer | number | boolean), ``minimum``/``maximum``/``step``, ``url``, ``env_var`` (explicit secret env var; default auto-generated).rrHs rget_config_schemaz MemoryProvider.get_config_schemas  rcy)zWrite non-secret setup ``values`` to the provider's native config. Plugins MUST either override this or use only env vars (every schema field carrying ``env_var``).Nr)rIvalues hermes_homes r save_configzMemoryProvider.save_configrJrcy)zMirror a built-in memory-tool write (``action``: add | replace | remove; ``target``: memory | user; ``metadata``: provenance such as write_origin, session_id, tool_name).Nr)rIactionrcontentmetadatas ron_memory_writezMemoryProvider.on_memory_writerJrcgS)zAbsolute paths of provider state OUTSIDE HERMES_HOME for ``hermes backup``/``import`` (paths outside the home dir are skipped). MUST work without ``initialize()`` or network.rrHs r backup_pathszMemoryProvider.backup_pathss  r)returnr))rr>)rNr)rNone)rWr)rNr)rr))rWr)rNr)rr)rzOptional[RecallStatus]) r`r)rar)rNr)r]zOptional[List[Dict[str, Any]]]r^Optional[Dict[str, Any]]rr)rList[Dict[str, Any]])rgr)rDict[str, Any]rr))rr)rlr2rmr)rr)rr)r]rrr) rxr)rtr)rur>rvr>rr)r]rrr))r~r)rr)r|r)rr)rrrr)rrr) rr)rr)rr)rrrr)rz List[str])r5r6r7r8#pre_compress_checkpoint_api_versionpropertyrrrLrOrQrTrXrZr\rbrdrhrjrnrprsryr{rrrrrrrrrErETsW3+,' ZZ hh  9; ?A[04NN47NN(FN.N  Ncc\B o  `@BQVhm5!59<5JN5ae5 5PRhYarrE)rCallable[..., Any]rr) rrrr)rr>rtuplerrrzthreading.Thread)r Optional[str]rr>)rArrr>)"r8 __future__rrloggingrerabcrr dataclassesrtypingrrr r r getLoggerr5loggerrr!#PRE_COMPRESS_CHECKPOINT_API_VERSIONr: frozensetr,r-r0compile IGNORECASEr?rCrErrrrs# #!66   8 $@SW')dj$j3KjWgj'(#"++Y!ZM  $!!!BJJgMM 3uSur