Fj]FdZddlmZddlZddlZddlZddlmZmZm Z m Z ddl m Z ddl mZejeZejdejZejdejZejd ejZdd ZGddZddZGddZdS)uTMemoryManager — orchestrates memory providers for the agent. Single integration point in run_agent.py. Replaces scattered per-backend code with one manager that delegates to registered providers. Only ONE external plugin provider is allowed at a time — attempting to register a second external provider is rejected with a warning. This prevents tool schema bloat and conflicting memory backends. Usage in run_agent.py: self._memory_manager = MemoryManager() # Only ONE of these: self._memory_manager.add_provider(plugin_provider) # System prompt prompt_parts.append(self._memory_manager.build_system_prompt()) # Pre-turn context = self._memory_manager.prefetch_all(user_message) # Post-turn self._memory_manager.sync_all(user_msg, assistant_response) self._memory_manager.queue_prefetch_all(user_msg) ) annotationsN)AnyDictListOptional)MemoryProvider) tool_errorzz5<\s*memory-context\s*>[\s\S]*?z\[System note:\s*The following is recalled memory context,\s*NOT new user input\.\s*Treat as (?:informational background data|authoritative reference data[^\]]*)\.\]\s*textstrreturnctd|}td|}td|}|S)zQStrip fence tags, injected context blocks, and system notes from provider output.)_INTERNAL_CONTEXT_REsub_INTERNAL_NOTE_RE _FENCE_TAG_RE)r s 3/usr/local/lib/hermes-agent/agent/memory_manager.pysanitize_contextr6sF  # #B - -D  T * *D   R & &D KceZdZdZdZdZddZddZdd Zdd Z e ddZ ddZ ddZ d dZd dZd!dZd"dZdS)#StreamingContextScrubberaStateful scrubber for streaming text that may contain split memory-context spans. The one-shot ``sanitize_context`` regex cannot survive chunk boundaries: a ```` opened in one delta and closed in a later delta leaks its payload to the UI because the non-greedy block regex needs both tags in one string. This scrubber runs a small state machine across deltas, holding back partial-tag tails and discarding everything inside a span (including the system-note line). Usage:: scrubber = StreamingContextScrubber() for delta in stream: visible = scrubber.feed(delta) if visible: emit(visible) trailing = scrubber.flush() # at end of stream if trailing: emit(trailing) The scrubber is re-entrant per agent instance. Callers building new top-level responses (new turn) should create a fresh scrubber or call ``reset()``. zzr Nonec0d|_d|_d|_dSNFrT_in_span_buf_at_block_boundaryselfs r__init__z!StreamingContextScrubber.__init__[s#  (,rc0d|_d|_d|_dSrrrs rresetzStreamingContextScrubber.reset`s  "&rr r c|sdS|j|z}d|_g}|r|jr||j}|dkrD|||j}|r || dnd|_d|S||t|jzd}d|_n||}|dkr| |p|||j }|r0| ||d| || d|_n| ||d|S|dkr| ||d|||t|j zd}d|_|d|S)aReturn the visible portion of ``text`` after scrubbing. Any trailing fragment that could be the start of an open/close tag is held back in the internal buffer and surfaced on the next ``feed()`` call or discarded/emitted by ``flush()``. rNFrT) rrlowerfind _CLOSE_TAG_max_partial_suffixjoinlen_find_boundary_open_tag_max_pending_open_suffix _OPEN_TAG_append_visible)r r bufoutidxhelds rfeedzStreamingContextScrubber.feedes 2i$  %} %iikk&&t77"9933CIID/3 ;TEFF DI773<<'#DO 4 44556 % 22377"9955c::I33CHH7,,S#fuf+>>>$'K ,,S#666773<<'77((c$3$i888#DN 3 33445 $ ; %>wws||rcP|jrd|_d|_dS|j}d|_|S)aQEmit any held-back buffer at end-of-stream. If we're still inside an unterminated span the remaining content is discarded (safer: leaking partial memory context is worse than a truncated answer). Otherwise the held-back partial-tag tail is emitted verbatim (it turned out not to be a real tag). rF)rr)r tails rflushzStreamingContextScrubber.flushs4 = DI!DM2y  rr0tagintc|}|}tt|t|dz }t|ddD]$}||| dr|cS%dS)zReturn the length of the longest buf-suffix that is a tag-prefix. Case-insensitive. Returns 0 if no suffix could start the tag. rr%N)r&minr+range startswith)r0r8 tag_lower buf_lower max_checkis rr)z,StreamingContextScrubber._max_partial_suffixs IIKK IIKK II(:;; y!R((  A##IqbccN33  qrc|}d} ||j|}|dkrdS|||r|||r|S|dz}W)z>Cbyyr&&sC00 T5R5RSVX[5\5\  7L  #rc||jsdSt|t|jz }|||sdSt|jS)zBHold a complete boundary tag until the following char confirms it.r)r&endswithr.r+rD)r r0r2s rr-z1StreamingContextScrubber._max_pending_open_suffixsnyy{{##DN33 1#hhT^,,,&&sC00 14>"""rr2boolcn|t|jz}|t|krdS||dvS)NFz )r+r.)r r0r2 after_idxs rrEz1StreamingContextScrubber._has_block_opener_suffixs;#dn--- C 59~''rc|dkr|jS|d|}|d}|dkr|jo|dkS||dzddkS)Nr r%rr;)rrfindstrip)r r0r2 preceding last_newlines rrDz+StreamingContextScrubber._is_block_boundarys !88* *I  t,, 2  *Fy/@/@B/F F)**+1133r99rr1 list[str]cb|sdS||||dSN)append_update_block_boundary)r r1r s rr/z(StreamingContextScrubber._append_visibles;  F 4 ##D)))))rc|d}|dkr*||dzddk|_dS|jo|dk|_dS)NrMr%r;r)rNrOr)r r rQs rrVz/StreamingContextScrubber._update_block_boundarysqzz$'' 2  &*s2#I$J---- '''' ,,,,\    \  # # # #####(((( ::::**** UUUUUUrr raw_contextc|r|sdSt|}||krtdd|dS)z:Wrap prefetched memory in a fenced block with system note.rz6memory provider returned pre-wrapped context; strippedu [System note: The following is recalled memory context, NOT new user input. Treat as authoritative reference data — this is the agent's persistent memory and should inform all responses.] z )rOrloggerwarning)racleans rbuild_memory_context_blockrfsk k//11r [ ) )E OPPP      rceZdZdZdAdZdBdZedCd ZdDd ZdEdZ dddFdZ dddGdZ e dHdZ ddddIdZdJdZdKd!ZdLd#ZdMd&ZdNd*ZdOd+Zdd,d-dPd1ZdQd2Ze dRd3Z dSdTd9Zdd:dUd>ZdAd?ZdVd@ZdS)W MemoryManagerzOrchestrates the built-in provider plus at most one external provider. The builtin provider is always first. Only one non-builtin (external) provider is allowed. Failures in one provider never block the other. r rc0g|_i|_d|_dS)NF) _providers_tool_to_provider _has_externalrs rr!zMemoryManager.__init__s02<>#(rproviderrcp|jdk}|sP|jrBtd|jDd}td|j|dSd|_|j||D]i}|dd}|r||j vr ||j |<.||j vr2td ||j |j|jjt d |jt|dS) uRegister a memory provider. Built-in provider (name ``"builtin"``) is always accepted. Only **one** external (non-builtin) provider is allowed — a second attempt is rejected with a warning. builtinc3:K|]}|jdk |jVdS)roN)name.0ps r z-MemoryManager.add_provider..s0LL)8K8KQV8K8K8K8KLLrunknownuRejected memory provider '%s' — external provider '%s' is already registered. Only one external memory provider is allowed at a time. Configure which one via memory.provider in config.yaml.NTrqrzJMemory tool name conflict: '%s' already registered by %s, ignoring from %sz*Memory provider '%s' registered (%d tools)) rqrlnextrjrcrdrUget_tool_schemasgetrkinfor+)r rm is_builtinexistingschema tool_names r add_providerzMemoryManager.add_providersh]i/  &! LLT_LLLi&M8 !%D  x(((//11  F 62..I Yd.DDD4<&y11d444'*95:M   8 M ))++ , ,     rList[MemoryProvider]c*t|jS)z"All registered providers in order.)listrjrs r providerszMemoryManager.providers0sDO$$$rrqr Optional[MemoryProvider]c8|jD]}|j|kr|cSdS)z2Get a provider by name, or None if not registered.N)rjrq)r rqrts r get_providerzMemoryManager.get_provider5s1  Av~~trc4g}|jD]z} |}|r)|r||C#t$r+}t d|j|Yd}~sd}~wwxYwd|S)zCollect system prompt blocks from all providers. Returns combined text, or empty string if no providers contribute. Each non-empty block is labeled with the provider name. z5Memory provider '%s' system_prompt_block() failed: %sN ) rjsystem_prompt_blockrOrU Exceptionrcrdrqr*)r blocksrmblockes rbuild_system_promptz!MemoryManager.build_system_prompt>s   H  4466)U[[]])MM%(((   KM1  {{6"""s?A  B!A==Br session_idqueryrc:g}|jD]}} |||}|r)|r||F#t$r+}t d|j|Yd}~vd}~wwxYwd|S)zCollect prefetch context from all providers. Returns merged context text labeled by provider. Empty providers are skipped. Failures in one provider don't block others. rz4Memory provider '%s' prefetch failed (non-fatal): %sNr) rjprefetchrOrUrrcdebugrqr*)r rrpartsrmresultrs r prefetch_allzMemoryManager.prefetch_allSs   H !**5Z*HH)fllnn)LL(((    JM1  {{5!!!sAA B!BBc|jD]R} |||#t$r+}td|j|Yd}~Kd}~wwxYwdS)z=Queue background prefetch on all providers for the next turn.rz:Memory provider '%s' queue_prefetch failed (non-fatal): %sN)rjqueue_prefetchrrcrrq)r rrrmrs rqueue_prefetch_allz MemoryManager.queue_prefetch_allfs  H ''*'EEEE    PM1   s# A!AArIc tj|j}n#ttf$rYdSwxYwt |j}td|DrdSd|jvS)z4Return whether sync_turn accepts a messages keyword.Tc3JK|]}|jtjjkVdSrTkindinspect Parameter VAR_KEYWORDrrs rruz@MemoryManager._provider_sync_accepts_messages..{/GG1qv*66GGGGGGrmessages) r signature sync_turn TypeError ValueErrorr parametersvaluesany)rmrparamss r_provider_sync_accepts_messagesz-MemoryManager._provider_sync_accepts_messagesss )(*<==II:&   44 i*113344 GGGGG G G 4Y111 11Nrr user_contentassistant_contentrOptional[List[Dict[str, Any]]]c|jD]} |/||r|||||n||||M#t$r+}td|j|Yd}~}d}~wwxYwdS)z'Sync a completed turn to all providers.Nrrz)Memory provider '%s' sync_turn failed: %s)rjrrrrcrdrq)r rrrrrmrs rsync_allzMemoryManager.sync_alls  H 'D,P,PQY,Z,Z'&&$)#-!) '&&$)#-'    ?M1   sA A B !BB List[Dict[str, Any]]cfg}t}|jD]} |D]H}|dd}|r.||vr*||||Ia#t $r+}td|j |Yd}~d}~wwxYw|S)z(Collect tool schemas from all providers.rqrz2Memory provider '%s' get_tool_schemas() failed: %sN) setrjrxryrUaddrrcrdrq)r schemasseenrmr}rqrs rget_all_tool_schemasz"MemoryManager.get_all_tool_schemassuu  H &7799''F!::fb11D'D 0 0v... '    HM1  sAA99 B.!B))B.rcNt|jS)z2Return set of all tool names across all providers.)rrkkeysrs rget_all_tool_namesz MemoryManager.get_all_tool_namess4)..00111rr~c||jvS)z(Check if any provider handles this tool.)rk)r r~s rhas_toolzMemoryManager.has_toolsD222rargsDict[str, Any]c |j|}|td|dS |j||fi|S#t$rA}t d|j||td|d|cYd}~Sd}~wwxYw)zRoute a tool call to the correct provider. Returns JSON string result. Raises ValueError if no provider handles the tool. Nz!No memory provider handles tool ''z4Memory provider '%s' handle_tool_call(%s) failed: %sz Memory tool 'z ' failed: )rkryr handle_tool_callrrcerrorrq)r r~rkwargsrmrs rrzMemoryManager.handle_tool_calls)--i88  N)NNNOO O H,8,YGGGG G H H H LLF y!   FiFF1FFGG G G G G G G  HsA B  6BB B  turn_numberr9messagec |jD]J} |j||fi|#t$r+}td|j|Yd}~Cd}~wwxYwdS)zxNotify all providers of a new turn. kwargs may include: remaining_tokens, model, platform, tool_count. z-Memory provider '%s' on_turn_start failed: %sN)rj on_turn_startrrcrrq)r rrrrmrs rrzMemoryManager.on_turn_starts   H &&{GFFvFFFF    CM1   s A!A  Ac|jD]P} ||#t$r+}td|j|Yd}~Id}~wwxYwdS)z$Notify all providers of session end.z.Memory provider '%s' on_session_end failed: %sN)rjon_session_endrrcrrq)r rrmrs rrzMemoryManager.on_session_ends  H ''1111    DM1   s! A!AAFparent_session_idr#new_session_idrr#c |sdS|jD]L} |j|f||d|#t$r+}td|j|Yd}~Ed}~wwxYwdS)uNotify all providers that the agent's session_id has rotated. Fires on ``/resume``, ``/branch``, ``/reset``, ``/new``, and context compression — any path that reassigns ``AIAgent.session_id`` without tearing the provider down. Providers keep running; they only need to refresh cached per-session state so subsequent writes land in the correct session's record. See ``MemoryProvider.on_session_switch`` for the full contract. Nrz1Memory provider '%s' on_session_switch failed: %s)rjon_session_switchrrcrrq)r rrr#rrmrs rrzMemoryManager.on_session_switchs&  F  H **"&7      GM1   s! A!AAc6g}|jD]{} ||}|r)|r||D#t$r+}t d|j|Yd}~td}~wwxYwd|S)zNotify all providers before context compression. Returns combined text from providers to include in the compression summary prompt. Empty string if no provider contributes. z/Memory provider '%s' on_pre_compress failed: %sNr) rjon_pre_compressrOrUrrcrrqr*)r rrrmrrs rrzMemoryManager.on_pre_compress s   H !11(;;)fllnn)LL(((    EM1  {{5!!!sAA B!A>>BcF tj|j}n#ttf$rYdSwxYwt |j}td|DrdSd|jvrdSd|D}t|dkrdSdS)z>Return how to pass metadata to a provider's memory-write hook.keywordc3JK|]}|jtjjkVdSrTrrrs rruzEMemoryManager._provider_memory_write_metadata_mode..'rrmetadatacg|]=}|jtjjtjjtjjhv;|>Sr`)rrrPOSITIONAL_ONLYPOSITIONAL_OR_KEYWORD KEYWORD_ONLYrrs r zFMemoryManager._provider_memory_write_metadata_mode..,sW   v!1!7!. r positionallegacy) rron_memory_writerrrrrrr+)rmrraccepteds r$_provider_memory_write_metadata_modez2MemoryManager._provider_memory_write_metadata_modes )(*BCCII:&   99 i*113344 GGGGG G G 9 - - -9      x==A  <xractiontargetcontentrOptional[Dict[str, Any]]c |jD]}|jdkr ||}|dkr)||||t |pinE|dkr(||||t |pin||||#t $r+}t d|j|Yd}~d}~wwxYwdS)zNotify external providers when the built-in memory tool writes. Skips the builtin provider itself (it's the source of the write). ror)rrz/Memory provider '%s' on_memory_write failed: %sN)rjrqrrdictrrcr)r rrrrrm metadata_moders rrzMemoryManager.on_memory_write8s1  H} ))  $ I I( S S  I--,,$x~2:N:N-#l22,,VVWd8>WYFZFZ[[[[,,VVWEEE    EM1   sB B!! C+!CC)child_session_idtaskrrc |jD]L} |j||fd|i|#t$r+}td|j|Yd}~Ed}~wwxYwdS)z/Notify all providers that a subagent completed.rz-Memory provider '%s' on_delegation failed: %sN)rj on_delegationrrcrrq)r rrrrrmrs rrzMemoryManager.on_delegationVs  H &&&3CGM    CM1   s A!A  Act|jD]O} |#t$r+}td|j|Yd}~Hd}~wwxYwdS)z;Shut down all providers (reverse order for clean teardown).z(Memory provider '%s' shutdown failed: %sN)reversedrjshutdownrrcrdrq)r rmrs r shutdown_allzMemoryManager.shutdown_allds 11  H !!####   >M1   s- A"!AA"c d|vr ddlm}t||d<|jD]J} |jdd|i|#t $r+}t d|j|Yd}~Cd}~wwxYwdS)zInitialize all providers. Automatically injects ``hermes_home`` into *kwargs* so that every provider can resolve profile-scoped storage paths without importing ``get_hermes_home()`` themselves. hermes_homer)get_hermes_homerz*Memory provider '%s' initialize failed: %sNr`) hermes_constantsrr rj initializerrcrdrq)r rrrrmrs rinitialize_allzMemoryManager.initialize_allos  & & 8 8 8 8 8 8$'(9(9$:$:F= !  H ##DDzDVDDDD   @M1   s? A4 !A//A4rX)rmrr r)r r)rqr r rrZ)rr rr r r )rr rr r r)rmrr rI) rr rr rr rrr r)r r)r r)r~r r rI)r~r rrr r )rr9rr r r)rrr r)rr rr r#rIr r)rrr r )rmrr r rT) rr rr rr rrr r)rr rr rr r r)rr r r)r[r\r]r^r!rpropertyrrrrrr_rrrrrrrrrrrrrrrr`rrrhrhs^ )))), , , , \%%%X%####*=?""""""&CE       2 2 2\ 2 37 @$22223333HHHH,        "$ !!!!!!F""""&\<.2 >/1          rrhrY)rar r r )r^ __future__rloggingrertypingrrrragent.memory_providerrtools.registryr getLoggerr[rccompile IGNORECASErrrrrrfrhr`rrrs2#""""" ,,,,,,,,,,,,000000%%%%%%  8 $ $ 6 FF !rz<MBJpM bUbUbUbUbUbUbUbUJ"LLLLLLLLLLr