hermes-memory-metronix 0.1.2

Standalone Hermes memory-provider plugin scaffold for Metronix

hermes-memory-metronix

Standalone Hermes MemoryProvider backed by Metronix Memory.

This repository owns the Hermes-native adapter layer:

• Hermes plugin packaging
• config and auth resolution
• prefetch and write-through behavior
• Hermes-focused unit, integration, and smoke tests

Metronix backend contracts and MCP integration docs remain in the metronix-memory repository.

Status

This is a scaffold, not a finished public plugin release.

What it already does:

• Implements the Hermes MemoryProvider contract
• Prefetches relevant Metronix memory records before a turn
• Mirrors Hermes memory(action="add") writes into Metronix
• Optionally writes completed turns as session-scoped Metronix memory
• Supports bearer-token auth, with email/password login fallback

What is intentionally still conservative:

• No custom Hermes setup wizard yet
• No extra provider-specific model tools yet
• Prefetch currently targets /api/v1/memory/search
• Knowledge-document / page retrieval is left as a follow-up

Layout

The installable Hermes plugin is this repository root. Its provider implementation lives in:

• plugin/metronix/

Hermes discovers user-installed memory providers from:

• ~/.hermes/plugins/<name>/__init__.py

Install for Hermes

Install the repository into your Hermes plugin directory:

hermes plugins install mtrnix/hermes-memory-metronix --no-enable

Then set Hermes to use it:

memory:
  provider: metronix

Python distribution

pip install hermes-memory-metronix distributes the adapter for development and Hermes-hosted environments. It does not register the provider with Hermes. For Hermes discovery, install this GitHub plugin with:

hermes plugins install mtrnix/hermes-memory-metronix --no-enable

Plugin config

The plugin reads non-secret config from:

• $HERMES_HOME/metronix.json

And secrets from:

• $HERMES_HOME/.env
• process environment

Example metronix.json:

{
  "base_url": "http://localhost:8000",
  "workspace_id": "MTRNIX",
  "agent_id": "hermes",
  "prefetch": true,
  "prefetch_top_k": 8,
  "prefetch_types": ["fact", "preference", "pinned"],
  "cite_sources": true,
  "write_through": true,
  "write_scope": "workspace",
  "sync_turns": true
}

Secrets:

METRONIX_AUTH_TOKEN=...
# or:
METRONIX_EMAIL=[e-mail]
METRONIX_PASSWORD=...

Important:

• METRONIX_AUTH_TOKEN must be a REST JWT or personal API key for /api/v1/*
• METRONIX_MCP_API_KEY is for /mcp, not /api/v1/memory/*
• if you provide both a bearer token and login credentials, the client will retry once with a fresh login JWT when the original bearer gets a 401

Mapping notes

Hermes write scopes map to Metronix scopes like this:

• per_agent -> per_agent
• workspace -> global
• shared -> global
• session -> session

The current prefetch path uses Metronix memory search, so prefetch_types maps to Metronix memory kinds:

• fact
• preference
• pinned

page is not wired yet because the current scaffold does not call a unified knowledge-search endpoint.

Migrating an existing llm-wiki into Metronix

Hermes's bundled llm-wiki skill maintains a directory of markdown pages (entities/, concepts/, comparisons/, queries/, raw/) at $WIKI_PATH (default ~/wiki). To bulk-ingest an existing wiki into Metronix's Knowledge Base (chunked, embedded, searchable via metronix_search_fast/metronix_get):

python scripts/migrate_wiki.py \
  --wiki-path ~/wiki \
  --base-url http://localhost:8000 \
  --workspace-id MTRNIX \
  --auth-token "$METRONIX_AUTH_TOKEN"

Each page becomes a document with source_type="hermes_llm_wiki" and a deterministic doc_label derived from its wiki-relative path, so re-running the script updates existing documents instead of duplicating them. By default, only raw/, entities/, concepts/, comparisons/, and queries/ are ingested; SCHEMA.md, index.md, log*.md, and _archive/** are skipped (pass --include-archive to include archived pages instead).

Requires METRONIX_AUTH_TOKEN to be a REST JWT or personal API key for /api/v1/*, not METRONIX_MCP_API_KEY, which is for /mcp only.

Development

Run the fast local checks:

uv run --extra dev pytest tests/unit -v
RUN_INTEGRATION_TESTS=1 uv run --extra dev pytest tests/integration/test_live_metronix.py -v

Verify against Hermes

Clone a clean Hermes checkout separately, then verify both the current MemoryProvider abstract base class and Hermes's real plugin loader:

HERMES_AGENT_SRC=/absolute/path/to/hermes-agent \
  uv run --extra dev pytest \
  tests/unit/test_real_abc_contract.py tests/unit/test_hermes_plugin.py -v

The compatibility tests skip with an explicit reason when HERMES_AGENT_SRC does not point to a Hermes checkout. They should pass before publishing a plugin release.