This plugin is an adapter for the existing Memory Gateway. It is not Memory Gateway core and it does not import core service, repository, or server modules.

The plugin calls the existing HTTP API:

POST /v1/memory/search
POST /v1/episodes
POST /v1/sessions/{session_id}/commit
POST /v1/memory
POST /v1/memory/{memory_id}/feedback

Configuration

Environment variables:

MEMORY_GATEWAY_URL, default http://127.0.0.1:1934
MEMORY_GATEWAY_API_KEY, optional
MEMORY_GATEWAY_DEFAULT_USER_ID, optional
MEMORY_GATEWAY_DEFAULT_AGENT_ID, optional
MEMORY_GATEWAY_DEFAULT_WORKSPACE_ID, optional
MEMORY_GATEWAY_AUTO_SEARCH, default true
MEMORY_GATEWAY_AUTO_APPEND_EPISODE, default true
MEMORY_GATEWAY_AUTO_COMMIT_SESSION, default false
MEMORY_GATEWAY_REVIEW_MODE, default true
MEMORY_GATEWAY_PLUGIN_DEBUG_RAW, default false
MEMORY_GATEWAY_PLUGIN_TRACE_HOOKS, default false

If an API key is configured, the plugin sends X-API-Key. It never logs the API key.

Validation Status

Check	Status
Mock unit tests	passed
Hermes plugin discovery	passed
Hermes tool registration	passed
Hermes hook registration	passed
Gateway E2E	passed
PluginManager.invoke_hook probe	passed
Real Hermes interactive session	passed
OpenClaw runtime validation	pending

Hermes

Use hermes.plugin.yaml as the Hermes-facing manifest. The entrypoint is:

__init__:register

The plugin attempts to register tools and best-effort hooks. If the Hermes runtime does not expose hook registration, it still works in tools-only mode.

Install locally:

mkdir -p ~/.hermes/plugins
cd /opt/memory-gateway
ln -s "$(pwd)/plugins/memory-gateway-agent" ~/.hermes/plugins/memory-gateway-agent
hermes plugins enable memory-gateway-agent
hermes plugins list
hermes tools list

Example runtime configuration:

export MEMORY_GATEWAY_URL=http://127.0.0.1:1934
export MEMORY_GATEWAY_API_KEY=
export MEMORY_GATEWAY_AUTO_SEARCH=true
export MEMORY_GATEWAY_AUTO_APPEND_EPISODE=true
export MEMORY_GATEWAY_AUTO_COMMIT_SESSION=false

OpenClaw

openclaw.plugin.yaml is a best-effort draft manifest. Adjust field names to the actual OpenClaw runtime schema before production use.

Tools-Only Mode

Agent runtimes can call:

memory_search
memory_append_episode
memory_commit_session
memory_upsert
memory_feedback

Tools-only mode does not automatically remember anything. The agent policy must decide when to call tools.

Lifecycle Hooks

Best-effort hooks:

on_session_start: initializes session memory context without writing long-term memory.
pre_llm_call: searches memory and returns compact memory context.
post_llm_call: appends a safe candidate episode when policy allows it.
on_session_end: commits session only when MEMORY_GATEWAY_AUTO_COMMIT_SESSION=true.

Plugin support for hooks depends on the agent runtime context API. This plugin should be described as tools-only plus best-effort hooks unless the target runtime has been verified.

Verified boundaries:

Tools-only is usable through the registered memory_gateway toolset.
pre_llm_call automatic search has passed hook-probe and real hermes chat -Q -q validation.
post_llm_call automatic candidate episode append has passed hook-probe and real hermes chat -Q -q validation.
on_session_end auto commit is off by default, stays off when MEMORY_GATEWAY_AUTO_COMMIT_SESSION=false, and commits when MEMORY_GATEWAY_AUTO_COMMIT_SESSION=true.

Defaults

Automatic search can be enabled.
Automatic append episode can be enabled.
Automatic commit is disabled by default.
Automatic direct long-term upsert is disabled by default.

Safety And Privacy

The plugin rejects memory writes containing passwords, API keys, bearer tokens, cookies, private keys, SSH keys, one-time verification codes, large logs, full raw transcripts, and chain-of-thought.

The plugin writes summarized candidate episodes. It does not store full raw conversations. Long-term memory should normally be produced by memory_commit_session, allowing Memory Gateway and EverMemOS to deduplicate, detect conflicts, and route review drafts.

Direct long-term memory_upsert is high risk and is not called automatically. If a user asks to forget or delete a memory, the agent should call memory_feedback or a delete-capable tool instead of silently keeping the memory.

Script output is redacted by default: no API key, headers, cookies, tokens, or raw result payloads are printed. Set MEMORY_GATEWAY_PLUGIN_DEBUG_RAW=true only for local debugging with non-sensitive test data.

Hook trace is disabled by default. Set MEMORY_GATEWAY_PLUGIN_TRACE_HOOKS=true to write minimal hook events to plugins/memory-gateway-agent/.tmp/hook_trace.log. Trace entries contain hook name, timestamp, shortened session id, Gateway action, and status only; they do not include user or assistant message bodies.

Cleanup Test Data

Integration tests use:

user_id=test_user_memory_gateway_plugin
tags such as integration_test, plugin, and safe_to_delete

Run cleanup:

cd /opt/memory-gateway
PYTHONPATH=plugins/memory-gateway-agent python plugins/memory-gateway-agent/scripts/cleanup_test_memories.py

The cleanup script refuses non-test_user_ users. It first tries DELETE /v1/memory/{memory_id} for local test memories. If deletion fails, it falls back to memory_feedback with incorrect. Current cleanup is limited by the search API: it can only clean local MemoryRecord rows returned by search, not arbitrary OpenViking context rows.

Local Smoke Test

cd /opt/memory-gateway
PYTHONPATH=plugins/memory-gateway-agent python plugins/memory-gateway-agent/scripts/health.py
PYTHONPATH=plugins/memory-gateway-agent python plugins/memory-gateway-agent/scripts/smoke_test.py
PYTHONPATH=plugins/memory-gateway-agent python plugins/memory-gateway-agent/scripts/hermes_smoke_check.py
PYTHONPATH=plugins/memory-gateway-agent python plugins/memory-gateway-agent/scripts/gateway_e2e_check.py
PYTHONPATH=plugins/memory-gateway-agent python plugins/memory-gateway-agent/scripts/hermes_hook_probe.py
PYTHONPATH=plugins/memory-gateway-agent python plugins/memory-gateway-agent/scripts/hermes_interactive_session_check.py