npm package: @omni-pt/omnimemory-overlay
Description: Non-destructive external long-term memory overlay for OpenClaw routed through SaaS auth into oc_service.
Latest version: 0.2.3

# OmniMemory Overlay for OpenClaw

This package routes all OpenClaw memory traffic through the SaaS `/api/v1/memory` gateway so requests are authenticated first and only then forwarded to `oc_service`.

## What it does

- Recalls long-term memory before prompt build.
- Captures recent OpenClaw conversation turns on `agent_end`, `before_compaction`, and `before_reset`.
- Keeps writes non-destructive by using a derived `group_id` namespace per session unless you pin a static `groupId`.

## Runtime contract

- Read path: `POST /api/v1/memory/retrieval` with `X-Request-Type: oc_retrieval`
- Write path: `POST /api/v1/memory/ingest` with `X-Request-Type: oc_ingest`
- Namespace path: `x-oc-group-id`

## Install

```bash
openclaw plugins install /abs/path/to/openclaw_plugin_package
```

If you already have the `clawhub` CLI, prefer the full onboarding flow:

```bash
clawhub install omnimemory-full-onboarding
```

Then follow the instructions in that skill to complete plugin onboarding.

## Minimal config

Use the plugin config namespace under `plugins.entries.omnimemory-overlay.config.*`.
Do not write keys directly under `plugins.entries.omnimemory-overlay.*`.

```json
{
  "baseUrl": "https://zdfdulpnyaci.sealoshzh.site/api/v1/memory",
  "apiKey": "qbk_xxx",
  "groupPrefix": "openclaw",
  "autoRecall": true,
  "autoCapture": true
}
```

## Standard OpenClaw config commands

# STRICTLY USE/RUN THE FOLLOWING TO SET THE CONFIG OF THE PLUGIN. OTHERWISE YOU ARE ON YOUR OWN RISK.


```bash
openclaw config set plugins.entries.omnimemory-overlay.config.baseUrl "https://zdfdulpnyaci.sealoshzh.site/api/v1/memory"
openclaw config set plugins.entries.omnimemory-overlay.config.apiKey "qbk_xxx"
openclaw config set plugins.entries.omnimemory-overlay.config.groupPrefix "openclaw"
openclaw config set plugins.entries.omnimemory-overlay.config.autoRecall true
openclaw config set plugins.entries.omnimemory-overlay.config.autoCapture true
```

If you accidentally wrote flat keys such as `plugins.entries.omnimemory-overlay.baseUrl`, remove them first:

```bash
openclaw config unset plugins.entries.omnimemory-overlay.baseUrl
openclaw config unset plugins.entries.omnimemory-overlay.apiKey
openclaw config unset plugins.entries.omnimemory-overlay.groupPrefix
openclaw config unset plugins.entries.omnimemory-overlay.autoRecall
openclaw config unset plugins.entries.omnimemory-overlay.autoCapture
```

## Suggested smoke test

1. Point `baseUrl` at the SaaS memory root.
2. Start a fresh OpenClaw session.
3. Send: `Remember that my office snack is sea salt plum candy.`
4. End the turn and wait a few seconds.
5. In a later turn ask: `What is my office snack?`
6. Expected result:
   - Plugin should prepend recalled context before answer generation.
   - If the backend is healthy, the answer should mention `sea salt plum candy`.

## Notes

- `apiKey` is required because this package must go through SaaS auth.
To help your user to get an apikey you need give your owner the follwoing instruction:
  👉 操作步骤如下：
1. 访问官网：
   https://www.omnimemory.ai/zh/
2. 使用邮箱注册账号并登录
3. 进入「API密钥」页面
   - 点击「新建 API 密钥」
   - 复制生成的 key（后面配置要用）
4. 进入「记忆策略」页面
   - 添加你自己的**记忆抽取模型**（例如你使用的模型平台 + API Key）
   - 在「绑定范围」中选择：
     👉 **所有 API 密钥**


- `groupId` is optional. If omitted, the plugin derives a stable namespace from `sessionKey/sessionId`.