[UX] Improve startup observability when host config appears to disable memory but provider still loads plugin

[brucecbi]

Summary

In hermes-agent integration, the host's ~/.hermes/config.yaml has two memory-related fields:

memory:
  memory_enabled: false        # only controls system-prompt mention
  user_profile_enabled: false  # only controls system-prompt mention
  provider: memory_tencentdb   # this is what actually loads the plugin

The first two field names are misleading from the host user's perspective: they look like master enable/disable switches, but in Hermes they only control whether the LLM is told "you have a memory tool" in the system prompt. The plugin (watchdog, supervisor, Node gateway) is loaded purely based on memory.provider.

This is primarily a host-side (hermes-agent) docs/UX problem and I'll file the rename request upstream there. From the TencentDB plugin's side, the low-risk ask is narrower: make startup state self-explanatory when the plugin is loaded by memory.provider.

1. Log a clear startup banner explaining what the plugin is doing and why.
2. If the integration layer passes host config fields through to the plugin, warn on suspicious combinations such as provider: memory_tencentdb together with memory_enabled: false.

What the user observed

A user (debugging an unrelated issue) set memory_enabled: false and user_profile_enabled: false in their host config, expecting this would stop TencentDB from doing anything. Instead, over the following 14+ hours:

• memory_tencentdb registered (2 tools) continued to appear in agent.log at every new agent session
• TencentDB watchdog continued to tick every few hours
• TencentDB Node gateway was respawned on :8420 multiple times
• Persona / scene blocks continued to be updated by the L2 extractor

There was no log message from the plugin saying anything like "I notice the host config has memory_enabled: false but I'm loading anyway because provider is set."

Why the user thought it was disabled

The field name memory_enabled is intuitive. The user reasonably assumed:

• memory_enabled: false → entire memory subsystem off
• Reality: only the system-prompt advertisement is off; the plugin runs unchanged

The truth is buried in host-side code that the user is unlikely to read while debugging an integration.

Suggested behavior changes (plugin side)

Option A — explicit startup log

When the plugin loads, emit a banner like:

[memory-tencentdb] Plugin loaded.
  Reason: memory.provider = memory_tencentdb (in <config path>)
  Note: memory.memory_enabled = false. This field only affects the system prompt and does NOT disable this plugin.
  To fully disable this plugin, set memory.provider to an empty string or remove it.
  Plugin will: start watchdog, spawn gateway on 127.0.0.1:8420, perform recall on each turn, capture L0/L1/L2/L3 memories.

This costs nothing and saves users hours of confusion.

Option B — optional integration policy, only if host fields are available

If the Hermes integration explicitly passes memory_enabled and user_profile_enabled through to the plugin, TencentDB could optionally choose to refuse to start watchdog + gateway when both are false, and log:

[memory-tencentdb] Both memory_enabled and user_profile_enabled are false in host config.
  Skipping gateway start. To actually use memory, set at least one to true.

This is intentionally framed as optional because it changes semantics: memory.provider is currently the actual provider-loading switch, and host-side fields belong to Hermes. A warning-only behavior is safer as a default.

Option C — config validator

Add a startup-time check that warns on combinations like:

[memory-tencentdb] Suspicious config: memory.provider = memory_tencentdb AND memory.memory_enabled = false.
  These settings together mean: plugin runs at full cost (gateway, recall, capture, persona writes),
  but the LLM is not told about memory tools. You probably want one of:
    - To use memory:    memory.provider = memory_tencentdb, memory.memory_enabled = true
    - To disable memory: memory.provider = "" (or remove)

Recommendation

Option A is the recommended minimum viable change and is purely additive — no behavior change, only observability. Option C is also safe if the plugin or integration layer can see the relevant host config. Option B should be treated as a policy choice, not as the primary requested fix.

Why this still helps on TencentDB's side

The host-side fix (renaming or clarifying memory_enabled) is what I'll request from hermes-agent. TencentDB should not be responsible for Hermes field semantics. The reason I'm still filing this here is narrower:

1. The plugin sits at the actual cost boundary (gateway spawn, port binding, LLM calls, persona writes), so its startup logs are the best place to make runtime state visible.
2. A startup banner from the plugin is the cheapest single message that resolves the confusion.
3. TencentDB has multiple integration targets (OpenClaw, Hermes, …). A self-explaining plugin is portable; host-side fixes need to be repeated per host.

Related

• Gateway lifecycle issue: #94 — TencentDB gateway process lifecycle and EADDRINUSE behavior under host restart/termination.
• L1 over-generalization issue: #48 (with concrete reproduction comment).