154 lines
6.3 KiB
Markdown
154 lines
6.3 KiB
Markdown
# 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:
|
|
|
|
```text
|
|
__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:
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
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
|
|
|
|
```bash
|
|
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
|
|
```
|