agentic-memory-hermes 0.1.1__py3-none-any.whl

agentic_memory_hermes/README.md

@@ -0,0 +1,184 @@
+# Agentic Memory for Hermes Agent
+
+This package is a showcase Hermes Agent integration for Agentic Memory. It ships
+two Hermes provider plugins side by side:
+
+- `plugins/memory/agentic-memory`
+  - a Hermes `MemoryProvider`
+  - recalls Agentic Memory context before model calls
+  - exposes explicit memory search/read tools
+  - persists completed turns to Agentic Memory in a background thread
+- `plugins/context_engine/agentic-memory`
+  - a Hermes `ContextEngine`
+  - replaces default compression with Agentic Memory-backed context resolution
+  - keeps Hermes token counters and returns valid OpenAI-format messages
+
+The directory layout follows the Hermes docs:
+
+```text
+plugins/
+├── memory/
+│   └── agentic-memory/
+│       ├── __init__.py
+│       ├── cli.py
+│       └── plugin.yaml
+└── context_engine/
+    └── agentic-memory/
+        ├── __init__.py
+        └── plugin.yaml
+```
+
+## One-Command Install
+
+Install the Hermes integration with `uvx` from the published wheel:
+
+```bash
+uvx --from https://github.com/jarmen423/agentic-memory/releases/download/hermes-v0.1.1/agentic_memory_hermes-0.1.1-py3-none-any.whl agentic-memory-hermes install --force
+```
+
+That command installs both Hermes plugin slots and configures Hermes to use
+Agentic Memory:
+
+- memory provider: `~/.hermes/plugins/agentic-memory`
+- context engine: `~/.hermes/hermes-agent/plugins/context_engine/agentic-memory`
+- `memory.provider = agentic-memory`
+- `context.engine = agentic-memory`
+
+For an isolated Hermes profile, pass the profile home explicitly:
+
+```bash
+uvx --from https://github.com/jarmen423/agentic-memory/releases/download/hermes-v0.1.1/agentic_memory_hermes-0.1.1-py3-none-any.whl agentic-memory-hermes install --force --hermes-home "$HERMES_HOME"
+```
+
+If you install the package directly into Hermes' own Python environment, Hermes
+can also discover the plugin through the `hermes_agent.plugins` entry point:
+
+```bash
+~/.hermes/hermes-agent/venv/bin/pip install agentic-memory-hermes
+```
+
+Once the project is published to PyPI, the shorter command will be:
+
+```bash
+uvx agentic-memory-hermes install --force
+```
+
+## Manual Install Into Hermes
+
+Copy the memory provider into the Hermes profile plugin directory, then copy
+the context engine into the Hermes project plugin directory. Hermes v0.13 scans
+those two plugin types differently:
+
+```bash
+cp -R packages/am-hermes/plugins/memory/agentic-memory \
+  ~/.hermes/plugins/agentic-memory
+
+cp -R packages/am-hermes/plugins/context_engine/agentic-memory \
+  ~/.hermes/hermes-agent/plugins/context_engine/agentic-memory
+```
+
+Configure Hermes:
+
+```bash
+hermes memory setup
+hermes config set memory.provider agentic-memory
+hermes config set context.engine agentic-memory
+```
+
+The setup wizard writes non-secret configuration to:
+
+```text
+$HERMES_HOME/agentic-memory.json
+```
+
+Secrets are expected in the Hermes `.env` file via:
+
+```bash
+AGENTIC_MEMORY_API_KEY=...
+```
+
+If you need a managed account key during Hermes setup, use the
+Hermes-attributed account URL:
+
+```text
+https://backend.agentmemorylabs.com/account/auth/google/start?connector_source=hermes
+```
+
+Direct website signups do not receive a free hosted runtime trial by default.
+Connector-attributed signups can receive a configured trial when Agent Memory
+Labs is running that acquisition campaign.
+
+Optional environment overrides:
+
+```bash
+AGENTIC_MEMORY_BACKEND_URL=https://backend.agentmemorylabs.com
+AGENTIC_MEMORY_DATA_PLANE_URL=
+AGENTIC_MEMORY_WORKSPACE_ID=hermes
+AGENTIC_MEMORY_DEVICE_ID=hermes-local
+AGENTIC_MEMORY_AGENT_ID=hermes-agent
+AGENTIC_MEMORY_PROJECT_ID=
+```
+
+For managed hosted accounts, `AGENTIC_MEMORY_BACKEND_URL` is the control-plane
+URL. During setup the memory provider tries to fetch
+`/product/account/runtime-route`; when the account runtime is ready it saves a
+branded data-plane URL such as `https://rt-abc123.agentmemorylabs.app` in
+`agentic-memory.json`. Normal memory and context calls then use that owned
+runtime URL. Raw provider origins are not written to Hermes config.
+
+## Troubleshooting
+
+If Hermes reports `HTTP 403` with `error code: 1010`, the request was blocked
+at the Cloudflare edge before it reached Agentic Memory. Check these first:
+
+- `AGENTIC_MEMORY_BACKEND_URL` should normally be
+  `https://backend.agentmemorylabs.com`.
+- `AGENTIC_MEMORY_DATA_PLANE_URL` should be empty unless setup saved a current
+  account runtime route in `~/.hermes/agentic-memory.json`.
+- `AGENTIC_MEMORY_WORKSPACE_ID` should match the workspace bound to the API key
+  when using workspace-bound keys. Account-scoped keys can use the default
+  `hermes` workspace.
+- `AGENTIC_MEMORY_API_KEY` must be present in the Hermes environment.
+- Hosted edge rules must allow the `agentic-memory-hermes/0.1.0` User-Agent.
+
+The plugin records background write failures instead of printing thread
+tracebacks, so search/context tool errors are the canonical symptom to inspect.
+
+## Backend Contract
+
+The Hermes plugins use the same backend routes as the OpenClaw integration:
+
+- `GET /product/account/runtime-route`
+- `POST /openclaw/session/register`
+- `POST /openclaw/memory/search`
+- `POST /openclaw/memory/read`
+- `POST /openclaw/memory/ingest-turn`
+- `POST /openclaw/context/resolve`
+
+That keeps this integration a thin host adapter. Agentic Memory remains the
+system of record for storage, retrieval, project scope, and hosted/self-hosted
+backend behavior.
+
+## Verify From This Repo
+
+The tests use local Hermes ABC shims so this module can be checked without a
+Hermes checkout:
+
+```powershell
+.\.venv-agentic-memory\Scripts\python.exe -m pytest packages/am-hermes/tests -q
+```
+
+## WSL Paths
+
+When this repo is checked out on Windows at `D:\code\agentic-memory`, the WSL
+copy commands are:
+
+```bash
+mkdir -p ~/.hermes/plugins ~/.hermes/hermes-agent/plugins/context_engine
+
+cp -R /mnt/d/code/agentic-memory/packages/am-hermes/plugins/memory/agentic-memory \
+  ~/.hermes/plugins/agentic-memory
+
+cp -R /mnt/d/code/agentic-memory/packages/am-hermes/plugins/context_engine/agentic-memory \
+  ~/.hermes/hermes-agent/plugins/context_engine/agentic-memory
+```

agentic_memory_hermes/__init__.py

@@ -0,0 +1,9 @@
+"""Installer package for the Agentic Memory Hermes Agent plugins.
+
+The package does not implement the Hermes memory provider directly. Instead it
+ships the two Hermes plugin directories as package data and exposes a small CLI
+that copies them into the active Hermes profile.
+"""
+
+__version__ = "0.1.1"
+

agentic_memory_hermes/hermes_plugin.py

@@ -0,0 +1,70 @@
+"""Hermes entry-point wrapper for Agentic Memory plugins.
+
+Hermes can discover Python packages that expose the `hermes_agent.plugins`
+entry-point group, but the existing Hermes memory provider and context engine
+live in file-based plugin directories because Hermes also supports direct
+profile installs. This wrapper lets both distribution styles share the same
+runtime code by loading those bundled plugin modules and forwarding Hermes'
+registration context to each one.
+"""
+
+from __future__ import annotations
+
+import importlib.util
+import sys
+from importlib import resources
+from pathlib import Path
+from types import ModuleType
+from typing import Any
+
+PACKAGE_NAME = "agentic_memory_hermes"
+
+
+def _bundled_plugins_root() -> Path:
+    """Return the bundled plugin directory from a wheel or source checkout."""
+
+    source_root = Path(__file__).resolve().parents[2] / "plugins"
+    if source_root.is_dir():
+        return source_root
+
+    packaged_root = resources.files(PACKAGE_NAME).joinpath("plugins")
+    if packaged_root.is_dir():
+        return Path(str(packaged_root))
+
+    raise FileNotFoundError("Could not locate bundled Hermes plugin files.")
+
+
+def _load_plugin_module(relative_init: str, module_name: str) -> ModuleType:
+    """Load one bundled Hermes plugin module from its `__init__.py` file."""
+
+    init_path = _bundled_plugins_root() / relative_init
+    spec = importlib.util.spec_from_file_location(module_name, init_path)
+    if spec is None or spec.loader is None:
+        raise ImportError(f"Cannot create module spec for {init_path}")
+
+    module = importlib.util.module_from_spec(spec)
+    sys.modules[module_name] = module
+    spec.loader.exec_module(module)
+    return module
+
+
+def register(ctx: Any) -> None:
+    """Register both Agentic Memory Hermes plugin surfaces.
+
+    Args:
+        ctx: Hermes' plugin registration context. It is expected to expose
+            `register_memory_provider` and `register_context_engine`.
+    """
+
+    memory_module = _load_plugin_module(
+        "memory/agentic-memory/__init__.py",
+        "agentic_memory_hermes._memory_plugin",
+    )
+    context_module = _load_plugin_module(
+        "context_engine/agentic-memory/__init__.py",
+        "agentic_memory_hermes._context_engine_plugin",
+    )
+
+    memory_module.register(ctx)
+    context_module.register(ctx)
+

agentic_memory_hermes/installer.py

@@ -0,0 +1,180 @@
+"""Install Agentic Memory's Hermes Agent plugins into a Hermes profile.
+
+Hermes discovers memory providers and context engines from two different
+directories. That makes a raw Python package insufficient by itself: after the
+package is downloaded by `uvx` or `pipx`, the plugin files still need to be
+placed under the user's Hermes home. This module is the bridge from package
+manager install to Hermes' file-based plugin discovery.
+"""
+
+from __future__ import annotations
+
+import argparse
+import os
+import shutil
+import subprocess
+import sys
+from importlib import resources
+from pathlib import Path
+
+PACKAGE_NAME = "agentic_memory_hermes"
+PLUGIN_NAME = "agentic-memory"
+
+
+def _default_hermes_home() -> Path:
+    """Return the Hermes profile home used by Hermes Agent.
+
+    Hermes honors `HERMES_HOME` for profile isolation. When that variable is
+    absent, Hermes defaults to `~/.hermes`.
+    """
+
+    return Path(os.environ.get("HERMES_HOME", "~/.hermes")).expanduser()
+
+
+def _bundled_plugins_root() -> Path:
+    """Locate bundled plugin files in a wheel or in the source checkout.
+
+    Wheels include `agentic_memory_hermes/plugins` through Hatch's
+    `force-include` setting. During repo-local tests, the files live beside the
+    packaging metadata under `packages/am-hermes/plugins`, so the fallback keeps
+    the installer runnable before the wheel is built.
+    """
+
+    source_root = Path(__file__).resolve().parents[2] / "plugins"
+    if source_root.is_dir():
+        return source_root
+
+    packaged_root = resources.files(PACKAGE_NAME).joinpath("plugins")
+    if packaged_root.is_dir():
+        return Path(str(packaged_root))
+
+    raise FileNotFoundError("Could not locate bundled Hermes plugin files.")
+
+
+def _copy_tree(source: Path, target: Path, *, force: bool, dry_run: bool) -> None:
+    """Copy one Hermes plugin directory to its discovery target.
+
+    Args:
+        source: Bundled plugin directory inside this package.
+        target: Hermes discovery directory to create.
+        force: Remove an existing target before copying.
+        dry_run: Print intended actions without touching the filesystem.
+
+    Raises:
+        FileExistsError: If the target exists and `force` is false.
+    """
+
+    if target.exists() and not force:
+        raise FileExistsError(
+            f"{target} already exists. Re-run with --force to replace the installed plugin."
+        )
+
+    print(f"{'Would install' if dry_run else 'Installing'} {source} -> {target}")
+    if dry_run:
+        return
+
+    if target.exists():
+        shutil.rmtree(target)
+    target.parent.mkdir(parents=True, exist_ok=True)
+    ignore = shutil.ignore_patterns("__pycache__", "*.pyc", "*.pyo")
+    shutil.copytree(source, target, ignore=ignore)
+
+
+def _run_hermes_config(key: str, value: str, *, dry_run: bool) -> bool:
+    """Set one Hermes config key through Hermes' own CLI when available.
+
+    Returns:
+        True when the command was run successfully, or False when Hermes is not
+        on PATH or rejected the setting.
+    """
+
+    command = ["hermes", "config", "set", key, value]
+    print(f"{'Would run' if dry_run else 'Running'}: {' '.join(command)}")
+    if dry_run:
+        return True
+
+    try:
+        subprocess.run(command, check=True)
+    except (FileNotFoundError, subprocess.CalledProcessError) as exc:
+        print(f"Warning: could not run {' '.join(command)} ({exc}).", file=sys.stderr)
+        return False
+    return True
+
+
+def install(args: argparse.Namespace) -> int:
+    """Install the memory provider and context engine into Hermes."""
+
+    hermes_home = Path(args.hermes_home).expanduser()
+    plugins_root = _bundled_plugins_root()
+
+    memory_source = plugins_root / "memory" / PLUGIN_NAME
+    context_source = plugins_root / "context_engine" / PLUGIN_NAME
+    memory_target = hermes_home / "plugins" / PLUGIN_NAME
+    context_target = hermes_home / "hermes-agent" / "plugins" / "context_engine" / PLUGIN_NAME
+
+    _copy_tree(memory_source, memory_target, force=args.force, dry_run=args.dry_run)
+    _copy_tree(context_source, context_target, force=args.force, dry_run=args.dry_run)
+
+    if args.configure:
+        _run_hermes_config("memory.provider", PLUGIN_NAME, dry_run=args.dry_run)
+        _run_hermes_config("context.engine", PLUGIN_NAME, dry_run=args.dry_run)
+
+    print("Agentic Memory Hermes plugin install complete.")
+    print(f"Hermes home: {hermes_home}")
+    print(f"Memory provider: {memory_target}")
+    print(f"Context engine: {context_target}")
+    return 0
+
+
+def build_parser() -> argparse.ArgumentParser:
+    """Build the command-line parser for the installer."""
+
+    parser = argparse.ArgumentParser(
+        prog="agentic-memory-hermes",
+        description="Install Agentic Memory's Hermes Agent plugins.",
+    )
+    subparsers = parser.add_subparsers(dest="command")
+
+    install_parser = subparsers.add_parser(
+        "install",
+        help="Copy Agentic Memory's Hermes plugins into the active Hermes profile.",
+    )
+    install_parser.add_argument(
+        "--hermes-home",
+        default=str(_default_hermes_home()),
+        help="Hermes profile home. Defaults to HERMES_HOME or ~/.hermes.",
+    )
+    install_parser.add_argument(
+        "--force",
+        action="store_true",
+        help="Replace existing Agentic Memory Hermes plugin directories.",
+    )
+    install_parser.add_argument(
+        "--no-configure",
+        dest="configure",
+        action="store_false",
+        help="Copy files only; do not run `hermes config set`.",
+    )
+    install_parser.add_argument(
+        "--dry-run",
+        action="store_true",
+        help="Show intended file copies and config commands without changing anything.",
+    )
+    install_parser.set_defaults(func=install, configure=True)
+
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    """Entry point used by `uvx agentic-memory-hermes` and `pipx run`."""
+
+    parser = build_parser()
+    args = parser.parse_args(argv)
+    if not hasattr(args, "func"):
+        parser.print_help()
+        return 2
+    return args.func(args)
+
+
+if __name__ == "__main__":  # pragma: no cover
+    raise SystemExit(main())