i.dZddlmZddlZddlmZmZddlmZm Z m Z m Z ej e ZGddeZdS)uAbstract base class for pluggable memory providers. Memory providers give the agent persistent recall across sessions. One external provider is active at a time alongside the always-on built-in memory (MEMORY.md / USER.md). The MemoryManager enforces this limit. Built-in memory is always active as the first provider and cannot be removed. External providers (Honcho, Hindsight, Mem0, etc.) are additive — they never disable the built-in store. Only one external provider runs at a time to prevent tool schema bloat and conflicting memory backends. Registration: 1. Built-in: BuiltinMemoryProvider — always present, not removable. 2. Plugins: Ship in plugins/memory//, activated by memory.provider config. Lifecycle (called by MemoryManager, wired in run_agent.py): initialize() — connect, create resources, warm up system_prompt_block() — static text for the system prompt prefetch(query) — background recall before each turn sync_turn(user, asst) — async write after each turn get_tool_schemas() — tool schemas to expose to the model handle_tool_call() — dispatch a tool call shutdown() — clean exit Optional hooks (override to opt in): on_turn_start(turn, message, **kwargs) — per-turn tick with runtime context on_session_end(messages) — end-of-session extraction on_session_switch(new_session_id, **kwargs) — mid-process session_id rotation on_pre_compress(messages) -> str — extract before context compression on_memory_write(action, target, content, metadata=None) — mirror built-in memory writes on_delegation(task, result, **kwargs) — parent-side observation of subagent work ) annotationsN)ABCabstractmethod)AnyDictListOptionalceZdZdZeed7dZed8dZed9d Zd7d Z d d d:dZ d d d;dZ d d ddZd?dZd@dZdAdZd d d!dBd%ZdCd&Zd d'dDd+Zd=d,ZdEd/Z dFdGd6Zd0S)HMemoryProviderz)Abstract base class for memory providers.returnstrcdS)zKShort identifier for this provider (e.g. 'builtin', 'honcho', 'hindsight').Nselfs :/home/ubuntu/.hermes/hermes-agent/agent/memory_provider.pynamezMemoryProvider.name.boolcdS)uReturn True if this provider is configured, has credentials, and is ready. Called during agent init to decide whether to activate the provider. Should not make network calls — just check config and installed deps. Nrrs r is_availablezMemoryProvider.is_available5rr session_idNonec dS)aInitialize for a session. Called once at agent startup. May create resources (banks, tables), establish connections, start background threads, etc. kwargs always include: - hermes_home (str): The active HERMES_HOME directory path. Use this for profile-scoped storage instead of hardcoding ``~/.hermes``. - platform (str): "cli", "telegram", "discord", "cron", etc. kwargs may also include: - agent_context (str): "primary", "subagent", "cron", or "flush". Providers should skip writes for non-primary contexts (cron system prompts would corrupt user representations). - agent_identity (str): Profile name (e.g. "coder"). Use for per-profile provider identity scoping. - agent_workspace (str): Shared workspace name (e.g. "hermes"). - parent_session_id (str): For subagents, the parent's session_id. - user_id (str): Platform user identifier (gateway sessions). Nr)rrkwargss r initializezMemoryProvider.initialize=rrcdS)a Return text to include in the system prompt. Called during system prompt assembly. Return empty string to skip. This is for STATIC provider info (instructions, status). Prefetched recall context is injected separately via prefetch(). rrs rsystem_prompt_blockz"MemoryProvider.system_prompt_blockTs rrr)rquerycdS)uRecall relevant context for the upcoming turn. Called before each API call. Return formatted text to inject as context, or empty string if nothing relevant. Implementations should be fast — use background threads for the actual recall and return cached results here. session_id is provided for providers serving concurrent sessions (gateway group chats, cached agents). Providers that don't need per-session scoping can ignore it. rrrr!rs rprefetchzMemoryProvider.prefetch]s rrcdS)uQueue a background recall for the NEXT turn. Called after each turn completes. The result will be consumed by prefetch() on the next turn. Default is no-op — providers that do background prefetching should override this. Nrr#s rqueue_prefetchzMemoryProvider.queue_prefetchkrr user_contentassistant_contentcdS)uPersist a completed turn to the backend. Called after each turn. Should be non-blocking — queue for background processing if the backend has latency. Nr)rr'r(rs r sync_turnzMemoryProvider.sync_turnsrrList[Dict[str, Any]]cdS)aReturn tool schemas this provider exposes. Each schema follows the OpenAI function calling format: {"name": "...", "description": "...", "parameters": {...}} Return empty list if this provider has no tools (context-only). Nrrs rget_tool_schemaszMemoryProvider.get_tool_schemaszrr tool_nameargsDict[str, Any]c 6td|jd|)zHandle a tool call for one of this provider's tools. Must return a JSON string (the tool result). Only called for tool names returned by get_tool_schemas(). z Provider z does not handle tool )NotImplementedErrorr)rr.r/rs rhandle_tool_callzMemoryProvider.handle_tool_calls% ""Zdi"Z"Zy"Z"Z[[[rcdS)u3Clean shutdown — flush queues, close connections.Nrrs rshutdownzMemoryProvider.shutdownrr turn_numberintmessagec dS)aCalled at the start of each turn with the user message. Use for turn-counting, scope management, periodic maintenance. kwargs may include: remaining_tokens, model, platform, tool_count. Providers use what they need; extras are ignored. Nr)rr6r8rs r on_turn_startzMemoryProvider.on_turn_startrrmessagescdS)u6Called when a session ends (explicit exit or timeout). Use for end-of-session fact extraction, summarization, etc. messages is the full conversation history. NOT called after every turn — only at actual session boundaries (CLI exit, /reset, gateway session expiry). Nrrr;s ron_session_endzMemoryProvider.on_session_endrrF)parent_session_idresetnew_session_idr?r@c dS)uCalled when the agent switches session_id mid-process. Fires on ``/resume``, ``/branch``, ``/reset``, ``/new`` (CLI), the gateway equivalents, and context compression — any path that reassigns ``AIAgent.session_id`` without tearing the provider down. Providers that cache per-session state in ``initialize()`` (``_session_id``, ``_document_id``, accumulated turn buffers, counters) should update or reset that state here so subsequent writes land in the correct session's record. Parameters ---------- new_session_id: The session_id the agent just switched to. parent_session_id: The previous session_id, if meaningful — set for ``/branch`` (fork lineage), context compression (continuation lineage), and ``/resume`` (the session we're leaving). Empty string when no lineage applies. reset: ``True`` when this is a genuinely new conversation, not a resumption of an existing one. Fired by ``/reset`` / ``/new``. Providers should flush accumulated per-session buffers (``_session_turns``, ``_turn_counter``, etc.) when this is set. ``False`` for ``/resume`` / ``/branch`` / compression where the logical conversation continues under the new id. Default is no-op for backward compatibility. Nr)rrAr?r@rs ron_session_switchz MemoryProvider.on_session_switchrrcdS)aCalled before context compression discards old messages. Use to extract insights from messages about to be compressed. messages is the list that will be summarized/discarded. Return text to include in the compression summary prompt so the compressor preserves provider-extracted insights. Return empty string for no contribution (backwards-compatible default). rrr=s ron_pre_compresszMemoryProvider.on_pre_compresss rr)child_session_idtaskresultrFc dS)aCalled on the PARENT agent when a subagent completes. The parent's memory provider gets the task+result pair as an observation of what was delegated and what came back. The subagent itself has no provider session (skip_memory=True). task: the delegation prompt result: the subagent's final response child_session_id: the subagent's session_id Nr)rrGrHrFrs r on_delegationzMemoryProvider.on_delegationrrcgS)aReturn config fields this provider needs for setup. Used by 'hermes memory setup' to walk the user through configuration. Each field is a dict with: key: config key name (e.g. 'api_key', 'mode') description: human-readable description secret: True if this should go to .env (default: False) required: True if required (default: False) default: default value (optional) choices: list of valid values (optional) url: URL where user can get this credential (optional) env_var: explicit env var name for secrets (default: auto-generated) Return empty list if no config needed (e.g. local-only providers). rrs rget_config_schemaz MemoryProvider.get_config_schemas  rvalues hermes_homecdS)aWrite non-secret config to the provider's native location. Called by 'hermes memory setup' after collecting user inputs. ``values`` contains only non-secret fields (secrets go to .env). ``hermes_home`` is the active HERMES_HOME directory path. Providers with native config files (JSON, YAML) should override this to write to their expected location. Providers that use only env vars can leave the default (no-op). All new memory provider plugins MUST implement either: - save_config() for native config file formats, OR - use only env vars (in which case get_config_schema() fields should all have ``env_var`` set and this method stays no-op). Nr)rrMrNs r save_configzMemoryProvider.save_configrrNactiontargetcontentmetadataOptional[Dict[str, Any]]cdS)aCalled when the built-in memory tool writes an entry. action: 'add', 'replace', or 'remove' target: 'memory' or 'user' content: the entry content metadata: structured provenance for the write, when available. Common keys include ``write_origin``, ``execution_context``, ``session_id``, ``parent_session_id``, ``platform``, and ``tool_name``. Use to mirror built-in memory writes to your backend. Nr)rrQrRrSrTs ron_memory_writezMemoryProvider.on_memory_writerr)r r )r r)rr r r)r!r rr r r )r!r rr r r)r'r r(r rr r r)r r+)r.r r/r0r r )r r)r6r7r8r r r)r;r+r r)rAr r?r r@rr r)r;r+r r )rGr rHr rFr r r)rMr0rNr r r)N) rQr rRr rSr rTrUr r)__name__ __module__ __qualname____doc__propertyrrrrr r$r&r*r-r3r5r:r>rCrErJrLrPrWrrrr r +s"33 ZZZ^XZ    ^    ^ ,9;      ?A      Y[         ^ \\\\BBBB         "$ % % % % % % N    /1       $    ,.2        rr )r[ __future__rloggingabcrrtypingrrrr getLoggerrXloggerr rrrrcsB#"""""########,,,,,,,,,,,,  8 $ $m m m m m Sm m m m m r