Skip to content

README.md

Latest commit

 

History

History
235 lines (170 loc) · 8.67 KB

README.md

File metadata and controls

235 lines (170 loc) · 8.67 KB

Memory (Memoria) for OpenClaw

This package turns 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

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.

# 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:

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.

# 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:

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.

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:

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

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

Publishing to npm

Version is managed automatically by CI. Do not manually edit the version in package.json.

The workflow queries npm for the latest published version and auto-bumps patch by default.

# Patch release (e.g. 0.4.3 → 0.4.4) — most common
gh workflow run release-npm.yml --repo matrixorigin/Memoria

# Explicit version for minor/major releases
gh workflow run release-npm.yml --repo matrixorigin/Memoria -f version=0.5.0

After publishing, users can upgrade with:

openclaw plugins install @matrixorigin/thememoria