tomtan/memory-gateway
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
c44af407d4d0d4303bcffcded08d353432ebfee5
memory-gateway/plugins/memory-gateway-agent/README.md

6.3 KiB
Raw Blame History

Memory Gateway Agent Plugin

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
ln -s /home/tom/memory-gateway/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 /home/tom/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 /home/tom/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