sjvUdZddlmZddlZddlZddlZddlZddlZddlZddl m Z ddl m Z m Z mZmZddlmZerddlmZejeZe ejZdZiZd ed <d Zd4dZd5dZd5dZ d6dZ!d7dZ"dZ#d8dZ$d5dZ%d9dZ&d:d Z'd;d"Z(dd#dd+Z+Gd,d-Z,d?d/Z- d@dAd1Z.dBd3Z/dS)CaXMemory provider plugin discovery. Scans four sources for memory provider plugins: 1. Bundled providers: ``plugins/memory//`` (shipped with hermes-agent) 2. User-installed providers: ``$HERMES_HOME/plugins//`` 3. Project-local providers: ``./.hermes/plugins//``, opt-in via ``HERMES_ENABLE_PROJECT_PLUGINS`` 4. Pip-installed providers: ``hermes_agent.memory_providers`` entry points Directory providers must contain ``__init__.py`` with a class implementing the MemoryProvider ABC. Pip packages expose a provider or ``register(ctx)`` callback through the entry-point group. These are the same four sources the general ``PluginManager`` scans, but the precedence is deliberately the reverse of its later-source-wins order: here **bundled wins**, then user, then project, then entry point. A memory provider is activated by name, so letting a directory dropped into the working tree shadow a shipped provider would silently redirect the agent's memory. Changing this order is a breaking change, not a cleanup. Only ONE provider can be active at a time, selected via ``memory.provider`` in config.yaml. Usage: from plugins.memory import discover_memory_providers, load_memory_provider available = discover_memory_providers() # [(name, desc, available), ...] provider = load_memory_provider("mnemosyne") # MemoryProvider instance ) annotationsN)Path)ListOptionalTuple TYPE_CHECKING)cfg_getMemoryProviderzhermes_agent.memory_providerszdict[str, Path]"_REGISTERED_MEMORY_PROVIDER_SKILLS_hermes_user_memorynamestrsearch_locations List[str]returnNonec|tjvrdStj|dd}||_tj|tj|<dS)uRegister an empty package shell in sys.modules. User-installed providers import as ``_hermes_user_memory.``, a dotted name whose parents exist nowhere on disk. Unless those parents are present in ``sys.modules``, any relative import inside the plugin (``from . import config``) fails with ``ModuleNotFoundError: No module named '_hermes_user_memory'`` — the same reason the loader already registers ``plugins`` and ``plugins.memory`` for bundled providers. NT) is_package)sysmodules importlib machinery ModuleSpecsubmodule_search_locationsutilmodule_from_spec)rrspecs ;/home/agent/.hermes/hermes-agent/plugins/memory/__init__.py_register_synthetic_packager :s] s{   ) )$ ) F FD&6D#!77==CKOptional[Path]c| ddlm}|dz }|r|ndS#t$rYdSwxYw)z8Return ``$HERMES_HOME/plugins/`` or None if unavailable.r)get_hermes_homepluginsN)hermes_constantsr$is_dir Exception)r$ds r_get_user_plugins_dirr*Psd444444 O   )HHJJ(qqD( tts *- ;;c ddlm}|dsdStjdz dz }|r|ndS#t $rYdSwxYw)u$Return ``./.hermes/plugins/`` or None if unavailable or not opted in. Gated on ``HERMES_ENABLE_PROJECT_PLUGINS`` exactly as the general ``PluginManager`` gates its own project scan — a repository you merely ``cd`` into must not be able to offer the agent a memory backend. r) _env_enabledHERMES_ENABLE_PROJECT_PLUGINSNz.hermesr%)hermes_cli.pluginsr,rcwdr'r()r,r)s r_get_project_plugins_dirr0Zs333333|;<< 4 HJJ "Y .HHJJ(qqD( ttsA0A AApathrboolc|dz }|sdS |dddd}d|vpd |vS#t$rYdSwxYw) uHeuristic: does *path* look like a memory provider plugin? Checks for ``register_memory_provider`` or ``MemoryProvider`` in the ``__init__.py`` source. Cheap text scan — no import needed. __init__.pyFreplacezutf-8)errorsencodingNi register_memory_providerr )exists read_textr()r1 init_filesources r_is_memory_provider_dirr=ls }$I     u$$I$HH$O)V3Q7G67QQ uus&A AAList[Tuple[str, Path]]c.t}g}trttD]}|r|jdr1|dz sI||j| |j|fttfD]}|st|D]}|r|jdr1|j|vr;t|sK||j| |j|f|S)zYield ``(name, path)`` for all discovered provider directories. Scans bundled, then user-installed, then project-local. Bundled takes precedence on name collisions (first-seen wins via ``seen`` set). )_.r4) set_MEMORY_PLUGINS_DIRr'sortediterdirr startswithr9addappendr*r0r=)seendirschild source_dirs r_iter_provider_dirsrM|s D#%D!!##-/7799:: - -E<<>> UZ%:%::%F%F M)1133  HHUZ KKU+ , , , ,-..0H0J0JK - -   J..0011 - -E<<>> UZ%:%::%F%F zT!!*511  HHUZ KKU+ , , , , - Kr!c tj}t|dr(t |t St|tr(t | t gSd|DS#t$r'}t d|gcYd}~Sd}~wwxYw)z1Yield pip-installed memory provider entry points.select)groupc2g|]}|jtk|S)rPENTRY_POINTS_GROUP.0eps r z&_iter_entry_points..s%CCCrBH0B$B$B$B$B$Br!z+Memory provider entry-point scan failed: %sN) rmetadata entry_pointshasattrlistrOrS isinstancedictgetr(loggerdebug)epsexcs r_iter_entry_pointsrcs  --// 3 ! ! > ); <<== = c4  9 2B7788 8CCSCCCC  BCHHH s*AB!`` subcommands — working, but a second-class citizen next to a directory install. r4)rCr'r9r*r0r=_entry_point_package_dirfind_provider_entry_point)rbundledrL candidates rfind_provider_dirris "D(G~~W}4<<>>,..0H0J0JK   %      "9)"D"D     #$=d$C$C D DDr!c j|dS ddlm}|jpddd}||}|sdSt |}|jdkr|jndS#t$r6}t dt|dd |Yd}~dSd}~wwxYw) uThe directory of an entry point's module, resolved WITHOUT importing it. Discovery must stay free of third-party imports: ``find_provider_dir`` is called from the dashboard and from argparse setup, long before the operator has selected a provider, so importing every installed candidate would run arbitrary code on the strength of a package merely being present. ``resolve_module_origin`` walks the module's file layout instead. Only package entry points (``pkg/__init__.py``) yield a directory — a provider pointed at a bare ``module.py`` has nowhere to put a sibling ``config_schema.py``, so it correctly resolves to None. Nr)resolve_module_origin:r4z4Could not resolve directory for entry point '%s': %sr?) r.rkvaluesplitstriprrparentr(r_r`getattr) entry_pointrk module_nameoriginr1rbs rrerest <<<<<<"(.B55c::1=CCEE &&{33 4F||"i=88t{{dB  K[&#66 = = =tttttsAA2"A22 B2<+B--B2cFtD]}|j|kr|cSdS)z;Resolve a provider name to a pip entry point, if installed.N)rcr)rrts rrfrfs;)++  t # #    $ 4r!cdtD}|dtDt|S)uCheap name-only listing of discoverable memory providers. Unlike :func:`discover_memory_providers`, this does NOT import provider modules or run availability checks — a directory scan plus entry-point *enumeration*, which reads distribution metadata without executing any of it. Safe to call at module-import time (e.g. when building the dashboard config schema, where it fills the ``memory.provider`` dropdown). ch|]\}}|SrRrR)rUrr@s r z-list_memory_provider_names..s 7 7 7gdAT 7 7 7r!c3$K|] }|jV dSN)rrTs r z-list_memory_provider_names..s$88R888888r!)rMupdatercrD)namess rlist_memory_provider_namesrsR 8 7!4!6!6 7 7 7E LL88#5#7#7888888 %==r!List[Tuple[str, str, bool]]cNg}t}tD]\}}d}|dz }|rl ddl}t |d5}||pi}dddn #1swxYwY|dd}n#t$rYnwxYwd} t|d } | r| } nd } n#t$rd } YnwxYw| ||| f| |tD]}} | j }||vrd}d} t| d } | r| } nd } n#t$rd } YnwxYw| ||| f| |~|S) aScan directory and pip entry-point memory providers. Returns list of (name, description, is_available) tuples. Bundled providers take precedence on name collisions, followed by user-installed directory providers, then pip entry-point providers. rl plugin.yamlrN utf-8-sigr7 descriptionTFregister_skills)rBrMr9yamlopen safe_loadr^r(_load_provider_from_dir is_availablerHrGrcr_load_provider_from_entry_point) resultsrIrrKdesc yaml_filerfmeta availableproviderrts rdiscover_memory_providersrseGUUD*,, eM)        )k:::3a>>!,,2D333333333333333xx r22      .ueLLLH "$1133 !    III  dI./// )++  4<<   6 %H "$1133 !    III  dI.///  NsZBA9- B9A= =BA= B B('B(.*C C('C(:*E%% E43E4rrOptional[bool]Optional['MemoryProvider']c||tk}t|}|rdnt|}|s|td|dS |rt ||nt ||}|r|Std|dS#t$r'}td||Yd}~dSd}~wwxYw)aLoad and return a MemoryProvider instance by name. Checks bundled (``plugins/memory//``), user-installed (``$HERMES_HOME/plugins//``), and pip entry-point providers. Bundled providers take precedence on name collisions. Skills register only when *name* is the configured active provider unless ``register_skills`` is passed explicitly. This keeps status and setup inspection of inactive providers free of registry side effects. Returns None if the provider is not found or fails to load. NzHMemory provider '%s' not found in bundled, user plugins, or entry pointsrz:Memory provider '%s' loaded but no provider instance foundz'Failed to load memory provider '%s': %s) _get_active_memory_providerrirfr_r`rrwarningr()rr provider_dirrtres rload_memory_providerrBs""="?"??$T**L&K$$,Ed,K,KK K/ V    t  #L/ R R R R0 /   OSUYZZZt @$JJJttttts'BB C(C  CTcLddlm}|}t||r|St|tr+t ||r |S#t $rYnwxYwt|dr9t|j |}| ||j r|j St|rV |}t||r|Sn#t$rYnwxYwt|j |}|||j St|D]Y}t||d}t|tr1t ||r!||ur |cS#t $rYUwxYwZt d|j dS)zFImport a provider entry point and extract the MemoryProvider instance.rr registerrNz3Memory provider entry point '%s' loaded no provider)agent.memory_providerr loadr\type issubclassr(rZ_ProviderCollectorrrrcallable TypeErrordirrsr_r`)rtrr loaded collectorr attr_nameattrs rrrqs 544444     F&.)) &$Jv~$F$F 688O    D vz""&&{'7YYY  """   &% % " vxxH(N33      D '{'7YYY y!![[ vy$// tT " " z$'G'G .. tvv      LLF HXYYY 4s6 A A*)A*C## C0/C0' E33 F?Frc|j}t|jvp|jtk}|rd|n td|}|dz }|sdSt j|}|t|ddr|}ndD]}|t jvrttj} |dkr| j} | dz } | rtj |t| t| g} | rZtj | } | t j|< | j| #t&$rYwxYw|st)tgtj |t|t|g} | sdStj | }|t j|<|d D]} | jdkr| j}|d|}|t jvrtj |t| }|r}tj |}|t j|< |j|#t&$r&}t.d ||Yd}~d}~wwxYw | j|nT#t&$rG}t.d ||t j|dYd}~dSd}~wwxYwt5|d rt7|| } ||nW#t&$rJ}|jt.d||nt.d||Yd}~nd}~wwxYw|jr|jSddlm }tC|D]Y}t||d}tE|tFr1tI||r!||ur |cS#t&$rYUwxYwZdS)uImport a provider module and extract the MemoryProvider instance. The module must have either: - A register(ctx) function (plugin-style) — we simulate a ctx - A top-level class that extends MemoryProvider — we instantiate it plugins.memory.rAr4N__file__)r%zplugins.memoryr%)rz*.pyzFailed to load submodule %s: %szFailed to exec_module %s: %srrzregister() failed for %s: %suvMemory provider '%s' raised after registering (%s) — using the registered provider; later registrations were skippedrr )%rrCparentsrr_USER_NAMESPACEr9rrr^rsrrrrspec_from_file_locationrrloader exec_moduler(r globstemr_r`poprZrrrrrr rr\rr)rrr _is_bundledrur;cachedmodrr parent_path parent_initr parent_modsub_filesub_name full_sub_namesub_specsub_modrrr rrs rrrs  D&)==kATXkAkK.9Z*D***/?Z?ZTX?Z?ZK},I     t [__[ ) )F gfj$??4 ! !FS[(("8nn3 Y&&"-"4K)M9 %%'' !$>AAK 0 047 4D4D3EBD!%.^%D%DT%J%J .8 F+! K33J????(!!! D!  = ' < < <~55 Y(+L(9(9':6   4n--d33#& K %))&11 Z ZH} --}H*77X77MCK//$>AA!3x==Z'n==hGGG18CK .Z 33G<<<<$ZZZ %F WXYYYYYYYYZ  K # #C ( ( ( (    LL7a H H H KOOK . . .44444  sJ&&t_MMM   LL # # # #    !) ;T1EEEEV!    &% %544444XX sIt,, tT " " z$'G'G .. tvv      4sm E$$ E10E1J33 K#=KK#(L M ||_d|_||_d|_dSr|)rr_register_skills_context)selfrrs r__init__z_ProviderCollector.__init__*s#  / r!c||_dSr|)r)rrs rr8z+_ProviderCollector.register_memory_provider0s   r!c|jsdS |}|j|i||r|dn|d}|jd|}ddlm}||}| |t|<dSdS#t$r,}t d|j|Yd}~dSd}~wwxYw)uForward plugin-provided skills to the general plugin registry. Handled explicitly rather than through ``__getattr__`` because skills are tracked for pruning: switching the active provider has to retract the skills the previous one registered, which needs the qualified name and resolved path recorded here. Gated on ``register_skills`` so merely *inspecting* an inactive provider — ``hermes memory status``, the setup picker — leaves no registry side effects behind. Nrrrmget_plugin_managerz1Memory provider '%s' failed to register skill: %s) r_plugin_contextregister_skillr^rr.rfind_plugin_skillr r(r_r`) rargskwargsmanager_context skill_namequalified_namerregistered_pathrbs rrz!_ProviderCollector.register_skill3s$  F ^"2244O *O *D ;F ; ; ;$(@afjj.@.@J $ 88J88N = = = = = =0022DD^TTO*ET2>BBB+* ^ ^ ^ LLLdiY\ ] ] ] ] ] ] ] ] ] ^sA;B C!B;;CcdSr|rR)rrrs rregister_cli_commandz'_ProviderCollector.register_cli_commandOs r!rc^dstfd}|S)uVDelegate any other ``register_*`` call to a real ``PluginContext``. Memory providers used to get a hand-maintained stub of three no-ops here, which had two failure modes. Calls it *did* know about (``register_tool``, ``register_hook``) were silently dropped, so a provider's tools simply never appeared. Calls it did *not* know about raised ``AttributeError`` — and ``register_auxiliary_task`` is one of them, despite ``PluginContext.register_auxiliary_task`` documenting a memory provider (hindsight's pre-retain dedup) as its worked example. That exception surfaces as "register() failed" and costs the provider. Delegating instead of enumerating means this can never drift behind ``PluginContext`` again: a capability added there works for memory providers on the same commit, which is what the "widen the generic plugin surface" rule in AGENTS.md asks for. Only ``register_*`` is forwarded. Everything else raises normally, so a typo still fails loudly rather than being absorbed. register_c |i|S#t$r-}tdj|Yd}~dSd}~wwxYw)Nz%Memory provider '%s' failed to %s: %s)r__getattribute__r(r_rr)rrrbrrs r_forwardz0_ProviderCollector.__getattr__.._forwardis Dt++-->>tDDdUfUUU   ;TYcttttt s,0 A'"A""A')rFAttributeError)rrrs`` r __getattr__z_ProviderCollector.__getattr__RsM({++ ' && &      r!c|j:ddlm}m}m}||j|j}||||_|jS)u(A real ``PluginContext`` for this provider, built once on demand. Lazy because the common case — a provider that only calls ``register_memory_provider`` — must not pay for importing the general plugin manager, which discovery touches on every hermes startup. Nr) PluginContextPluginManifestr)rkey)rr.rrrr)rrrrmanifests rrz"_ProviderCollector._plugin_contextwsg = \ \ \ \ \ \ \ \ \ \%~49$)DDDH)M(4F4F4H4HIIDM}r!N)rrrr2)rr) __name__ __module__ __qualname____doc__rr8rrrrrRr!rrr!s>B !!!^^^8   ####J     r!r Optional[str]cl ddlm}|}t|ddpdS#t$rYdSwxYw)uRead the active memory provider name from config.yaml. Returns the provider name (e.g. ``"honcho"``) or None if no external provider is configured. Lightweight — only reads config, no plugin loading. r) load_configmemoryrN)hermes_cli.configrr r()rconfigs rrrs]111111vx44<< tts "% 33active_providercp|t}ddlm}|}ttD]n\}}|d\}}}||kr%|||kr||t |dodS)zCRemove tracked skills that no longer belong to the active provider.Nrrrm) rr.rr[r items partitionrremove_plugin_skillr)rrmanagerrr namespacer@s r&_prune_inactive_memory_provider_skillsrs577555555  ""G+/*0022,,EE')22377 1a  ' '   $ $^ 4 4 G G  ' ' 7 7 7*..~tDDDDEEr! List[dict]c <g}ts|St}|s|St|}|s|S|dz }|s|St|jvp|jtk}|rd|dn td|d} |tj vrtj |}n|s=ttgttd|t|gtj |t|}|r|js|Stj |}|tj |<|j|t%|dd}t'|s|Sd|d} d } |d z } | rr d dl} t+| d 5} | | pi}dddn #1swxYwY|dd }|r|} |} n#t0$rYnwxYwt%||ddpt%|dd}||| | |||dn3#t0$r&}t4d||Yd}~nd}~wwxYw|S)uReturn CLI commands for the **active** memory plugin only. Only one memory provider can be active at a time (set via ``memory.provider`` in config.yaml). This function reads that value and only loads CLI registration for the matching plugin. If no provider is active, no commands are registered. Looks for a ``register_cli(subparser)`` function in the active plugin's ``cli.py``. Returns a list of at most one dict with keys: ``name``, ``help``, ``description``, ``setup_fn``, ``handler_fn``. This is a lightweight scan — it only imports ``cli.py``, not the full plugin module. Safe to call during argparse setup before any provider is loaded. zcli.pyrz.clirA register_cliNzManage z memory pluginrlrrrrr_commandhoncho_command)rhelprsetup_fn handler_fnpluginz-Failed to scan CLI for memory plugin '%s': %s)rCr'rrir9rrrrrrr rrrrrrrrsrrrrr^r(rHr_r`)rr plugin_dircli_filerrucli_modrr help_textrrrrrrrrs rdiscover_plugin_cli_commandsrs"G  % % ' '133O #?33J H$H ??  %);;gz?PTg?gK=Hx9O9999Q`NxNxcrNxNxNxK:Z #+ % %k+.GG ,OR@@@+&::::S__99S]]D t{ n55d;;G'.CK $ K # #G , , ,w==  %% N>o===  .        )k:::3a>>!,,2D333333333333333xx r22' $I"&K    W&B&B&BDII>W&6==  #&$$%        ZZZ DoWXYYYYYYYYZ NsoBI)*A)I)!I)6H G/# H/G33H6G37HI) H$!I)#H$$AI)) J3JJ)rrrrrr)rr")r1rrr2)rr>)rrrr")rr)rr)rr)rrrrrr)rr2rr)rrrr2rr)rrr|)rrrr)rr)0r __future__rrimportlib.machineryimportlib.metadataimportlib.utilloggingrpathlibrtypingrrrrrr rr getLoggerrr_rrrrCrSr __annotations__rr r*r0r=rMrcrirerfrrrrrrrrrrRr!rr s>#""""" 777777777777%%%%%%5444444  8 $ $d8nn+468"8888(>>>>,$     """"J   EEEE<<    ::::@'+,,,,,,d!//////j!{{{{{{|bbbbbbbbJ     &*EEEEE*``````r!