npm package: @matrixorigin/thememoria
Description: OpenClaw memory plugin that uses the Memoria cloud API.
Latest version: 0.4.3

# Memory (Memoria) for OpenClaw

This package turns [MatrixOrigin Memoria](https://github.com/matrixorigin/Memoria) into an installable OpenClaw `memory` plugin.

## Architecture

| Backend | Transport | Binary needed | Use case |
|---------|-----------|---------------|----------|
| `embedded` | Rust `memoria` CLI → local MatrixOne DB | Yes | Self-hosted / local dev |
| `api` | Direct HTTP → Memoria REST API | No | Cloud OpenClaw, any environment |

```
api mode:
  Plugin → MemoriaHttpTransport → fetch() → Memoria REST API

embedded mode:
  Plugin → MemoriaMcpSession → spawn("memoria mcp") → local MatrixOne DB
```

- Durable memory lives in MatrixOne
- Snapshots, rollback, branches, merge, diff, governance, reflect, and entity extraction are handled by Memoria
- In `embedded` mode the plugin shells out to the `memoria` binary via MCP stdio
- In `api` mode the plugin calls the Memoria REST API directly — no binary needed
- OpenClaw keeps its own tool and hook surface; the storage backend is Memoria

## Quick Start

### Prerequisites

```bash
openclaw --version
# -> OpenClaw vX.Y.Z (CLI is installed and in PATH)
```

### Cloud Setup (Recommended)

Cloud mode connects directly to the Memoria REST API. No binary download needed.

```bash
# 1. Install plugin
openclaw plugins install @matrixorigin/thememoria

# 2. Setup cloud backend (also enables the plugin)
openclaw memoria setup \
  --mode cloud \
  --api-url <MEMORIA_API_URL> \
  --api-key <MEMORIA_API_KEY>

# 3. Verify
openclaw memoria health
# Expected: "status": "ok"
```

If the npm package is not yet published, install from source:

```bash
mkdir -p ~/.openclaw/plugins-src
git clone https://github.com/matrixorigin/Memoria.git ~/.openclaw/plugins-src/Memoria
openclaw plugins install --link ~/.openclaw/plugins-src/Memoria/plugins/openclaw
```

Then continue with step 2 above.

### Local Setup (Embedded)

Local mode runs the Rust `memoria` binary against a self-hosted MatrixOne instance.

```bash
# 1. Install memoria CLI
curl -sSL https://raw.githubusercontent.com/matrixorigin/Memoria/main/scripts/install.sh | bash -s -- -y -d ~/.local/bin

# 2. Install plugin
openclaw plugins install @matrixorigin/thememoria

# 3. Setup local backend (also enables the plugin, quick start with defaults)
openclaw memoria setup \
  --mode local \
  --install-memoria \
  --embedding-api-key <EMBEDDING_API_KEY>

# 4. Verify
openclaw memoria health
# Expected: "status": "ok"
```

For advanced local configuration:

```bash
openclaw memoria setup \
  --mode local \
  --db-url <MATRIXONE_DSN> \
  --embedding-provider <provider> \
  --embedding-model <model> \
  --embedding-api-key <embedding_key> \
  --embedding-dim <dim> \
  --install-memoria \
  --memoria-bin ~/.local/bin/memoria
```

## Agent Install Prompt

Use this prompt to have an OpenClaw agent install the plugin automatically.
Replace `<MEMORIA_API_URL>` and `<MEMORIA_API_KEY>` with your credentials.

```text
Install the Memoria memory plugin for my OpenClaw in cloud mode.

Credentials:
- API URL: <MEMORIA_API_URL>
- API Key: <MEMORIA_API_KEY>

Run these steps in order. Stop and report if any step fails.

1) Install plugin:
   openclaw plugins install @matrixorigin/thememoria

2) Setup cloud backend (this also enables the plugin):
   openclaw memoria setup --mode cloud --api-url <MEMORIA_API_URL> --api-key <MEMORIA_API_KEY>

3) Verify:
   openclaw memoria health
   Expected: "status": "ok"

Rules:
- Show every command you run and its full raw output
- Do not summarize or hide errors
- If a step fails, classify the error (network / auth / config / missing-binary) and suggest the exact fix command
- Do NOT use `openclaw memory` commands — those are built-in file memory, not Memoria
```

## Environment Variables (Local/Embedded Only)

> Cloud users: skip this section. Cloud mode only needs `--api-url` and `--api-key`.

| Variable | Description | Default |
|----------|-------------|---------|
| `MEMORIA_DB_URL` | MatrixOne DSN | `mysql://root:111@127.0.0.1:6001/memoria` |
| `MEMORIA_EMBEDDING_PROVIDER` | Embedding service | `openai` |
| `MEMORIA_EMBEDDING_MODEL` | Model name | `text-embedding-3-small` |
| `MEMORIA_EMBEDDING_API_KEY` | Required unless provider is `local` | — |
| `MEMORIA_EMBEDDING_BASE_URL` | Optional for OpenAI, required for gateways | — |
| `MEMORIA_EMBEDDING_DIM` | Must match model before first startup | — |
| `MEMORIA_LLM_API_KEY` | Optional, for `autoObserve` and LLM-backed tools | — |
| `MEMORIA_LLM_BASE_URL` | Optional OpenAI-compatible base URL | — |
| `MEMORIA_LLM_MODEL` | Model for auto-observe and reflection | `gpt-4o-mini` |
| `MEMORIA_EXECUTABLE` | Explicit path to `memoria` binary | — |
| `MEMORIA_RELEASE_TAG` | Rust Memoria release tag to install | installer default |

## Tool Surface

The plugin exposes these tools to OpenClaw:

- `memory_search`, `memory_get`, `memory_store`, `memory_retrieve`, `memory_recall`
- `memory_list`, `memory_stats`, `memory_profile`, `memory_correct`, `memory_purge`, `memory_forget`, `memory_health`
- `memory_observe`, `memory_governance`, `memory_consolidate`, `memory_reflect`, `memory_extract_entities`, `memory_link_entities`, `memory_rebuild_index`, `memory_capabilities`
- `memory_snapshot`, `memory_snapshots`, `memory_rollback`
- `memory_branch`, `memory_branches`, `memory_checkout`, `memory_branch_delete`, `memory_merge`, `memory_diff`
- Compatibility CLI aliases under `openclaw ltm ...`

## Common Pitfalls

**`openclaw memoria` vs `openclaw memory`:** This plugin uses `openclaw memoria`. The `openclaw memory` namespace is OpenClaw's built-in file memory — a different system entirely.

**macOS `sh` vs `bash`:** The installer script uses bash syntax. If piping, use `bash -s --`, not `sh -s --`.

**Explicit memory mode is default (`autoObserve=false`):** The plugin does not auto-write memories from conversation turns. Writes happen when the agent explicitly calls tools like `memory_store`. To enable auto-capture, set `MEMORIA_AUTO_OBSERVE=true` and provide `MEMORIA_LLM_API_KEY` + `MEMORIA_LLM_MODEL`.

**Old schema vs new runtime:** If upgrading from an older Memoria setup, use a fresh database name in `MEMORIA_DB_URL` to avoid schema drift.

## Verification

| Level | Check | Command | Pass |
|---|---|---|---|
| 1. Plugin loaded | OpenClaw recognizes plugin | `openclaw plugins list` | `thememoria` listed and enabled |
| 2. Backend reachable | Memoria connectivity | `openclaw memoria health` | `status: ok` |
| 3. Memory persisted | Store → retrieve round-trip | `openclaw memoria stats` | Non-zero memory count after a write |

Additional diagnostics:

```bash
openclaw memoria capabilities   # config/plugin check (no live backend needed)
openclaw memoria verify          # deeper diagnostic
openclaw ltm list --limit 10     # list recent memories
```

Notes:
- `openclaw memoria setup` is the recommended onboarding command
- `openclaw memoria connect` remains available as the lower-level config-only variant (no `--install-memoria` support)
- `setup`/`connect` will merge `thememoria` into `plugins.allow` to satisfy OpenClaw allow-list policy
- OpenClaw may print "Restart the gateway" after `plugins install` — this is unnecessary for CLI commands like `setup` and `health`

## Uninstall

```bash
curl -fsSL https://raw.githubusercontent.com/matrixorigin/Memoria/main/plugins/openclaw/scripts/uninstall-openclaw-memoria.sh | \
  bash -s --
```

Removes the plugin entry, tool policy additions, managed skills, and the default managed checkout path.

## Compatibility Notes

- `memory_get` is resolved from recent tool results plus a bounded scan (Rust MCP has no direct get-by-id)
- `memory_stats` is derived from available MCP outputs (inactive-memory and entity totals not currently available)
- `memory_entities` is not exposed (no matching Rust MCP tool)
- Old `mysql+pymysql://...` DSNs are normalized to `mysql://...` automatically
- Schema drift from older Memoria stacks can cause runtime errors — use a fresh DB name to avoid

## Development

- `openclaw/client.ts` talks to Rust Memoria over MCP stdio (embedded) or HTTP (api)
- Plugin manifest and config use `memoriaExecutable` for embedded mode
- Installer/uninstaller are pure shell + Node, no Python dependency
- No bundled Python runtime