npm package: @t0ken.ai/memoryx-openclaw-plugin
Description: MemoryX real-time memory capture and recall plugin for OpenClaw (powered by @t0ken.ai/memoryx-sdk)
Author: MemoryX Team
Latest version: 2.2.76

# MemoryX OpenClaw Plugin

Official MemoryX plugin for OpenClaw. Enables long-term memory for agents by recalling context before execution and saving conversations after each run.

## Features

- **Auto Recall**: `before_agent_start` → semantic search for relevant memories
- **Auto Capture**: `message_received` + `assistant_response` → buffer and flush to MemoryX API
- **Function Calling**: LLM can actively search, list, and delete memories
- **Auto Registration**: Agents auto-register with machine fingerprint
- **Conversation Buffer**: Smart buffering with token counting and round-based flushing

## Function Calling Tools

The plugin registers three tools that LLM can call during conversations:

| Tool | Description | When to Use |
|------|-------------|-------------|
| `memoryx_recall` | Search through long-term memories | User asks "do you remember X?" or needs context |
| `memoryx_store` | Save important information to memory | User says "remember this" or you identify important info |
| `memoryx_list` | List all stored memories | User asks "what do you remember about me?" |
| `memoryx_forget` | Delete a specific memory | User asks to forget/remove something |

### memoryx_store Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `content` | string | Yes | The information to remember (server will auto-categorize) |

### Example Usage

**User**: "What do you remember about my preferences?"
**LLM**: *calls `memoryx_list`* → Returns list of stored memories

**User**: "Did I ever mention my favorite color?"
**LLM**: *calls `memoryx_recall` with query="favorite color"* → Searches and returns relevant memories

**User**: "Please forget about my old address"
**LLM**: *calls `memoryx_forget` with memory_id* → Deletes the memory

**User**: "Remember that my favorite color is blue"
**LLM**: *calls `memoryx_store` with content="User's favorite color is blue"* → Stores the memory

## Install

```bash
openclaw plugins install @t0ken.ai/memoryx-openclaw-plugin
openclaw gateway restart
```

## Update

```bash
openclaw plugins update @t0ken.ai/memoryx-openclaw-plugin
openclaw gateway restart
```

Or update all plugins:

```bash
openclaw plugins update --all
openclaw gateway restart
```

## Configuration

Edit `~/.openclaw/openclaw.json`:

```json
{
  "plugins": {
    "slots": {
      "memory": "memoryx-openclaw-plugin"
    },
    "entries": {
      "memoryx-openclaw-plugin": {
        "enabled": true,
        "config": {
          "apiBaseUrl": "https://memoryx.cloud/api"
        }
      },
      "memory-core": {
        "enabled": false
      },
      "memory-lancedb": {
        "enabled": false
      }
    }
  }
}
```

For self-hosted MemoryX:

```json
{
  "plugins": {
    "slots": {
      "memory": "memoryx-openclaw-plugin"
    },
    "entries": {
      "memoryx-openclaw-plugin": {
        "enabled": true,
        "config": {
          "apiBaseUrl": "http://192.168.31.65:8000/api"
        }
      },
      "memory-core": {
        "enabled": false
      },
      "memory-lancedb": {
        "enabled": false
      }
    }
  }
}
```

Restart the gateway after config changes:

```bash
openclaw gateway restart
```

## How it Works

Powered by **@t0ken.ai/memoryx-sdk** with conversation preset.

### Recall (`before_agent_start`)

- Builds a `/v1/memories/search` request using the current prompt
- Injects relevant memories via `prependContext`:
  ```
  [Relevant Memories]
  - [preference] User prefers dark mode
  - [fact] User's timezone is UTC+8
  [End of memories]
  ```

### Add (`message_received` + `assistant_response`)

- Buffers messages with precise token counting
- Flushes to `/v1/conversations/flush` when:
  - 30k tokens reached
  - 5 minutes idle timeout
- Server extracts entities, facts, and preferences automatically

### Auto Registration

On first run, the plugin:
1. Generates a machine fingerprint
2. Calls `/agents/auto-register` to get API key
3. Stores credentials locally for future sessions

## Memory Categories

Memories are categorized by the server:
- **preference**: User preferences and settings
- **fact**: Factual information about the user
- **plan**: Future plans and goals
- **experience**: Past experiences
- **opinion**: User opinions and views

## Notes

- Conversation buffer uses `cl100k_base` encoding (GPT-4 compatible)
- Maximum 8000 tokens per message
- Minimum 2 characters per message
- Short messages like "ok", "thanks" are skipped

## How the proxy works

**Current behavior:** The plugin starts a local Sidecar (port 3335) and tries to redirect your existing provider’s baseUrl to it (so you keep using e.g. `zai/glm-5`). Whether that works depends on how OpenClaw resolves the model (config vs. registry). See `OPENCLAW-BASEURL-FLOW.md` for details.

**SlimClaw-style (recommended, no file changes):** Like SlimClaw, you can use a **virtual provider** so all traffic goes through the Sidecar without the plugin mutating config or files. Add this to `~/.openclaw/openclaw.json` under `models.providers`:

```json
"memoryx-gateway": {
  "baseUrl": "http://localhost:3335/v1",
  "apiKey": "placeholder",
  "models": [{ "id": "auto" }]
}
```

Then add an auth profile for `memoryx-gateway` (e.g. in `~/.openclaw/agents/main/agent/auth-profiles.json` or global auth) with any placeholder key. In the UI, choose model **MemoryX Gateway** (id: `memoryx-gateway/auto`). Requests will go to the Sidecar, which forwards to the MemoryX server with your real provider credentials (you configure which provider/model to use via the plugin/Sidecar logic). The plugin does not modify your config or `models.json`; it only runs the Sidecar.

## License

MIT