@atomicmemory/hermes-plugin 0.1.10 → 0.1.12

package/CHANGELOG.md

@@ -0,0 +1,23 @@
+# Changelog
+
+## 0.1.12 - 2026-05-14
+
+### Fixed
+
+- Added the Core Quickstart bearer key to the installer next-step output so the published package matches the local quickstart docs.
+
+## 0.1.11 - 2026-05-14
+
+### Added
+
+- Added the packaged Hermes provider installer exposed through the `atomicmemory-hermes` npm binary.
+
+### Fixed
+
+- Preserved the Python SDK import path when Hermes is installed from the packaged npm artifact.
+
+## 0.1.10 - 2026-05-14
+
+### Added
+
+- Initial public npm package for the AtomicMemory Hermes plugin.

package/README.md

@@ -24,19 +24,20 @@ hooks, tool schemas. Memory semantics flow through the published Python SDK.
 
 ## Prerequisites
 
-- Hermes Agent installed and `HERMES_HOME` set
+- Hermes Agent installed
 - AtomicMemory core URL exported as `ATOMICMEMORY_API_URL`
+- AtomicMemory bearer key exported as `ATOMICMEMORY_API_KEY` when using the Core Quickstart or any protected service
 
-## Install (dev)
+## Install
 
-The simplest dev install symlinks the plugin into Hermes' memory directory.
-Hermes installs the published `atomicmemory` SDK from `plugin.yaml`.
+Install the provider from the published npm package. The installer copies the
+Python provider files into Hermes' memory-provider directory; no repository
+clone is required.
 
 ```bash
-cd /path/to/atomicmemory-integrations
-mkdir -p "$HERMES_HOME/plugins/memory"
-ln -s "$(pwd)/plugins/hermes" "$HERMES_HOME/plugins/memory/atomicmemory"
-export ATOMICMEMORY_API_URL="http://localhost:3050"
+npx -y @atomicmemory/hermes-plugin install
+export ATOMICMEMORY_API_URL="http://127.0.0.1:3050"
+export ATOMICMEMORY_API_KEY="local-dev-key"
 ```
 
 Then select and verify the provider:
@@ -48,6 +49,14 @@ hermes memory status
 # confirm "atomicmemory" is active
 ```
 
+For source development, symlink the checkout instead:
+
+```bash
+cd /path/to/atomicmemory-integrations
+mkdir -p "$HERMES_HOME/plugins/memory"
+ln -s "$(pwd)/plugins/hermes" "$HERMES_HOME/plugins/memory/atomicmemory"
+```
+
 ## Config
 
 Hermes' setup wizard prompts for a minimal pair (`scope_user`, `memory_scope`).
@@ -62,7 +71,7 @@ have a default API URL and fails to start if `ATOMICMEMORY_API_URL` is unset.
 | Env var | Purpose |
 |---|---|
 | `ATOMICMEMORY_API_URL` | AtomicMemory core URL. Required. |
-| `ATOMICMEMORY_API_KEY` | Bearer credential for AtomicMemory core. Optional. |
+| `ATOMICMEMORY_API_KEY` | Bearer credential for the Core Quickstart service or any protected AtomicMemory core. |
 | `ATOMICMEMORY_PROVIDER` | SDK provider name. Defaults to `atomicmemory`. |
 | `ATOMICMEMORY_SCOPE_USER` | Hermes user identity. Defaults to `$USER`. |
 | `ATOMICMEMORY_MEMORY_SCOPE` | `shared` (default) or `siloed`. |
@@ -144,7 +153,7 @@ run while AtomicMemory is temporarily unavailable.
 
 | Symptom | Likely cause |
 |---|---|
-| Provider does not appear in `hermes memory setup` | Wrong install path. Memory providers must live under `$HERMES_HOME/plugins/memory/<name>/`, not `$HERMES_HOME/plugins/<name>/`. |
+| Provider does not appear in `hermes memory setup` | Wrong install path. User-installed memory providers must live under `$HERMES_HOME/plugins/memory/<name>/`. |
 | `is_available()` returns False | `ATOMICMEMORY_API_URL` unset, or the Hermes Python environment did not install the `atomicmemory` dependency from `plugin.yaml`. |
 | Import fails at startup | The Hermes Python environment is missing the SDK dependency from `plugin.yaml`. |
 | Calls fail with `PROVIDER_UNSUPPORTED` while `memory_scope=siloed` | The configured SDK provider is not the AtomicMemory core (e.g. it's `mem0`). Either switch `ATOMICMEMORY_PROVIDER=atomicmemory` or move to `memory_scope=shared`. |

package/install.mjs

@@ -0,0 +1,104 @@
+#!/usr/bin/env node
+/**
+ * Install the AtomicMemory Hermes provider from the published npm package.
+ *
+ * Hermes memory providers are filesystem plugins under
+ * `$HERMES_HOME/plugins/memory/<name>`. The npm package already contains the
+ * Python provider files, so this installer copies only that managed provider
+ * surface into the active Hermes profile without requiring a Git checkout.
+ */
+
+import { copyFileSync, mkdirSync, readFileSync } from 'node:fs';
+import { basename, dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const packageDir = dirname(fileURLToPath(import.meta.url));
+
+function main(argv) {
+  const options = parseArgs(argv);
+  if (options.help) {
+    printHelp();
+    return;
+  }
+  if (options.command !== 'install') {
+    throw new Error(`Unknown command '${options.command}'. Expected 'install'.`);
+  }
+  const target = options.target ?? defaultTarget();
+  installProvider(target);
+  printNextSteps(target);
+}
+
+function parseArgs(argv) {
+  const options = { command: 'install', target: undefined, help: false };
+  const args = [...argv];
+  if (args[0] && !args[0].startsWith('-')) {
+    options.command = args.shift();
+  }
+  while (args.length > 0) {
+    const arg = args.shift();
+    if (arg === '--help' || arg === '-h') {
+      options.help = true;
+      continue;
+    }
+    if (arg === '--target') {
+      const value = args.shift();
+      if (!value) throw new Error('--target requires a path');
+      options.target = resolve(value);
+      continue;
+    }
+    throw new Error(`Unknown option '${arg}'`);
+  }
+  return options;
+}
+
+function defaultTarget() {
+  const hermesHome = process.env.HERMES_HOME || defaultHermesHome();
+  return join(hermesHome, 'plugins', 'memory', 'atomicmemory');
+}
+
+function defaultHermesHome() {
+  const home = process.env.HOME;
+  if (!home) {
+    throw new Error('Set HERMES_HOME or HOME before installing the Hermes provider.');
+  }
+  return join(home, '.hermes');
+}
+
+function installProvider(target) {
+  mkdirSync(target, { recursive: true });
+  for (const file of providerFiles()) {
+    copyFileSync(join(packageDir, file), join(target, basename(file)));
+  }
+}
+
+function providerFiles() {
+  const pkg = JSON.parse(readFileSync(join(packageDir, 'package.json'), 'utf8'));
+  return pkg.files.filter((file) => file.endsWith('.py') || file === 'plugin.yaml' || file === 'README.md');
+}
+
+function printNextSteps(target) {
+  console.log(`Installed AtomicMemory Hermes provider to ${target}`);
+  console.log('');
+  console.log('Next:');
+  console.log('  export ATOMICMEMORY_API_URL="http://127.0.0.1:3050"');
+  console.log('  export ATOMICMEMORY_API_KEY="local-dev-key"');
+  console.log('  hermes memory setup');
+  console.log('  hermes memory status');
+}
+
+function printHelp() {
+  console.log(`Usage: atomicmemory-hermes [install] [--target <dir>]
+
+Installs the AtomicMemory Hermes memory provider into:
+  $HERMES_HOME/plugins/memory/atomicmemory
+
+When HERMES_HOME is unset, defaults to:
+  $HOME/.hermes/plugins/memory/atomicmemory`);
+}
+
+try {
+  main(process.argv.slice(2));
+} catch (error) {
+  console.error(error instanceof Error ? error.message : String(error));
+  process.exit(1);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@atomicmemory/hermes-plugin",
-  "version": "0.1.10",
+  "version": "0.1.12",
   "description": "AtomicMemory native Hermes memory provider — Python SDK-backed, cross-tool memory by default.",
   "publishConfig": {
     "access": "public",
@@ -12,7 +12,11 @@
     "url": "git+https://github.com/atomicstrata/atomicmemory-integrations.git",
     "directory": "plugins/hermes"
   },
+  "bin": {
+    "atomicmemory-hermes": "install.mjs"
+  },
   "files": [
+    "CHANGELOG.md",
     "__init__.py",
     "client.py",
     "config.py",
@@ -20,6 +24,8 @@
     "tools.py",
     "breaker.py",
     "worker.py",
+    "install.mjs",
+    "pyproject.toml",
     "plugin.yaml",
     "README.md"
   ],

package/plugin.yaml

@@ -1,5 +1,5 @@
 name: atomicmemory
-version: 0.1.10
+version: 0.1.11
 description: "AtomicMemory native Hermes memory provider — Python SDK-backed, cross-tool memory by default."
 pip_dependencies:
   - "atomicmemory>=1.0.1,<2.0.0"

package/pyproject.toml

@@ -0,0 +1,29 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "atomicmemory-hermes"
+version = "0.1.11"
+description = "AtomicMemory native Hermes memory provider."
+readme = "README.md"
+requires-python = ">=3.10"
+license = "Apache-2.0"
+authors = [{ name = "Atomic Strata" }]
+dependencies = ["atomicmemory>=1.0.1,<2.0.0"]
+
+[project.urls]
+Repository = "https://github.com/atomicstrata/atomicmemory-integrations"
+Documentation = "https://docs.atomicstrata.ai/integrations/coding-agents/hermes/local"
+
+[project.entry-points."hermes_agent.plugins"]
+atomicmemory = "atomicmemory_hermes:register"
+
+[tool.setuptools]
+packages = ["atomicmemory_hermes"]
+
+[tool.setuptools.package-dir]
+atomicmemory_hermes = "."
+
+[tool.setuptools.package-data]
+atomicmemory_hermes = ["plugin.yaml", "README.md"]

package/python_sdk.py

@@ -252,15 +252,7 @@ def _is_atomicmemory_module(name: str) -> bool:
 
 
 def _plugin_roots() -> set[Path]:
-    roots = {Path(__file__).resolve().parent}
-    module = sys.modules.get("atomicmemory")
-    file_name = getattr(module, "__file__", None)
-    if file_name:
-        try:
-            roots.add(Path(file_name).resolve().parent)
-        except OSError:
-            pass
-    return roots
+    return {Path(__file__).resolve().parent}
 
 
 def _remove_plugin_import_roots(plugin_roots: set[Path]) -> list[tuple[int, str]]: