npm package: @rds-memory/rds-cloud-memory
Description: OpenClaw plugin for Mem0-compatible cloud RDS long-term memory
Latest version: 0.0.3

# @rds-memory/rds-cloud-memory

Mem0-compatible cloud RDS long-term memory plugin for OpenClaw. Works alongside the built-in local memory plugins (`memory-core` / `memory-lancedb`) to provide hybrid local+cloud or cloud-only memory storage.

## Features

- Connects to a self-hosted Mem0-compatible cloud memory API
- Three storage strategies: `local`, `mix`, `remote`
- Auto-capture: automatically stores conversation memories to the cloud after each agent run
- Auto-recall: automatically retrieves relevant cloud memories before each agent run
- CLI commands for managing cloud memories
- Agent tools for explicit cloud memory store/search/delete

## Installation

### As a bundled extension (development)

The plugin lives in `extensions/rds-cloud-memory/` and is bundled with OpenClaw. It is enabled by default.

### As an npm package (external users)

1. Install the package:

```bash
npm install @rds-memory/rds-cloud-memory
```

2. Add the plugin to your OpenClaw config (`~/.openclaw/openclaw.json`):

```json
{
  "plugins": {
    "load": {
      "paths": ["@rds-memory/rds-cloud-memory"]
    },
    "entries": {
      "rds-cloud-memory": {
        "enabled": true,
        "config": {
          "storageStrategy": "mix"
        }
      }
    }
  }
}
```

## Configuration

Configuration is resolved in this order: **plugin config** > **environment variables** > **defaults**.

### Environment Variables

| Variable                | Description                                | Default           |
| ----------------------- | ------------------------------------------ | ----------------- |
| `MEM0_API_KEY`          | API key for Mem0 cloud memory service      | Built-in fallback |
| `MEM0_HOST`             | Base URL for Mem0 cloud memory service     | Built-in fallback |
| `MEM0_STORAGE_STRATEGY` | Storage strategy: `local`, `mix`, `remote` | `local`           |

### Plugin Config

Set in `~/.openclaw/openclaw.json` under `plugins.entries.rds-cloud-memory.config`:

```json
{
  "apiKey": "your-api-key",
  "host": "http://your-host:8000/memory",
  "storageStrategy": "mix",
  "userId": "custom-user-id",
  "autoCapture": true,
  "autoRecall": true
}
```

| Key               | Type    | Default         | Description                                                          |
| ----------------- | ------- | --------------- | -------------------------------------------------------------------- |
| `apiKey`          | string  | `$MEM0_API_KEY` | API key for authentication. Supports `${ENV_VAR}` syntax.            |
| `host`            | string  | `$MEM0_HOST`    | Base URL for the Mem0 API. Supports `${ENV_VAR}` syntax.             |
| `storageStrategy` | string  | `local`         | `local`, `mix`, or `remote`.                                         |
| `userId`          | string  | (agent ID)      | Fixed user ID for cloud memory. Defaults to the agent ID at runtime. |
| `autoCapture`     | boolean | `true`          | Auto-capture conversation memories to cloud after agent runs.        |
| `autoRecall`      | boolean | `true`          | Auto-recall relevant cloud memories before agent starts.             |

## Storage Strategies

### `local` (default)

Cloud operations are completely disabled. Only the local memory plugins (memory-core / memory-lancedb) are active. The plugin registers but takes no action.

### `mix`

Both local and cloud memory operate in parallel:

- **Writes**: when the local memory plugin captures a memory, this plugin also sends conversation data to the cloud concurrently.
- **Reads**: both local and cloud memories are recalled and injected into the agent context. Local memory results take priority in ordering.

This is the recommended mode for production use. It provides redundancy and enables cross-device memory access.

### `remote`

Only cloud memory is used. To fully disable local memory, set the memory slot to `"none"`:

```json
{
  "plugins": {
    "slots": {
      "memory": "none"
    },
    "entries": {
      "rds-cloud-memory": {
        "enabled": true,
        "config": {
          "storageStrategy": "remote"
        }
      }
    }
  }
}
```

## Agent Tools

When the storage strategy is `mix` or `remote`, the plugin registers these tools:

| Tool                  | Description                                         |
| --------------------- | --------------------------------------------------- |
| `cloud_memory_store`  | Save information to cloud long-term memory          |
| `cloud_memory_search` | Search cloud memory for relevant information        |
| `cloud_memory_forget` | Delete specific memories or all memories from cloud |

## CLI Commands

```bash
openclaw cloud-memory search "user preferences"
openclaw cloud-memory list
openclaw cloud-memory status
```

## Publishing to npm

To publish this plugin as a standalone npm package:

1. Update `package.json`:
   - Remove `"private": true`
   - Move `openclaw` from `peerDependencies` to `peerDependencies` (already done)
   - Ensure `"type": "module"` is set

2. Build the plugin (transpile TypeScript):

   ```bash
   npx tsc --outDir dist --declaration
   ```

3. Update `package.json` entry point:

   ```json
   {
     "main": "dist/index.js",
     "types": "dist/index.d.ts",
     "openclaw": {
       "extensions": ["./dist/index.js"]
     }
   }
   ```

4. Publish:

   ```bash
   npm publish --access public
   ```

5. Users install with:
   ```bash
   openclaw plugin install @rds-memory/rds-cloud-memory
   ```
   Or manually:
   ```bash
   npm install @rds-memory/rds-cloud-memory
   ```

## Architecture

This plugin does **not** use `kind: "memory"`, so it does not compete for the exclusive memory slot. It operates as a general-purpose plugin that hooks into the agent lifecycle (`agent_end` for capture, `before_agent_start` for recall) independently of whatever memory slot plugin is active.

This design allows it to work alongside `memory-core` and `memory-lancedb` without conflicts, enabling true hybrid local+cloud memory when using the `mix` strategy.