Memory Supabase

Name: Memory Supabase
Rating: 3.5 (1 reviews)
Author: cfregly

By cfregly ⭐ 1 stars 👁 28 views ▲ 0 votes

Supabase pgvector memory plugin for OpenClaw

GitHub

Install

npm install --omit=dev`)

README

# OpenClaw Memory (Supabase)

OpenClaw memory plugin that stores long-term memory in Supabase (`pgvector`).

## Secret key best practices

- Use a Supabase server secret key (`sb_secret_...`) for plugin auth.
- Put that value in `SUPABASE_SERVICE_ROLE_KEY` for this plugin and setup scripts.
- Do not use publishable (`sb_publishable_...`) or legacy anon keys for server-side memory writes.
- Do not commit keys. `.env` and `.env.*` are gitignored.
- Rotate the secret key immediately if it is exposed in logs, chat, or commits.

## Prerequisites

- `pnpm`
- `npm`
- `openclaw`
- `psql`
- Supabase project URL
- Supabase server secret key (`sb_secret_...`)
- Supabase DB password
- OpenAI API key for embeddings

## Reproducible setup (macOS/Linux)

1. Copy env template and fill real values.

```bash
cd /Users/admin/Admin/dev/openclaw-memory-supabase
cp .env.example .env
```

2. Set values in `.env`.

- `SUPABASE_URL=https://<project-ref>.supabase.co`
- `SUPABASE_SERVICE_ROLE_KEY=sb_secret_...`
- `OPENAI_API_KEY=sk-proj-...`
- `SUPABASE_DB_URL=postgresql://postgres.<project-ref>:<db-password>@aws-0-<region>.pooler.supabase.com:5432/postgres?sslmode=require`

3. Run setup.

```bash
set -a
source .env
set +a
bash scripts/setup.sh
```

4. Restart and verify.

```bash
openclaw gateway restart
openclaw plugins doctor
openclaw channels status --probe
curl -sS --fail-with-body "$SUPABASE_URL/rest/v1/rpc/openclaw_memory_count" \
  -H "apikey: $SUPABASE_SERVICE_ROLE_KEY" \
  -H "Authorization: Bearer $SUPABASE_SERVICE_ROLE_KEY" \
  -H "Content-Type: application/json" \
  -d '{"match_agent_id":"main"}'
```

Expected result for the curl call is an integer count.

## Reproducible setup (PowerShell)

```powershell
cd /Users/admin/Admin/dev/openclaw-memory-supabase
Copy-Item .env.example .env
# edit .env with real values first
powershell -ExecutionPolicy Bypass -File scripts/setup.ps1
openclaw gateway restart
openclaw plugins doctor
```

## What setup scripts do

- Install project deps (`pnpm install`) unless `--skip-install`
- Copy plugin files to `~/.openclaw/extensions/memory-supabase`
- Install runtime deps inside extension dir (`npm install --omit=dev`)
- Apply `schema.sql` to Supabase via `psql` unless `--skip-db`
- Configure OpenClaw plugin path, enable `memory-supabase`, set memory slot, and write plugin config unless `--skip-config`

## Script flags

- `--skip-install`
- `--skip-db`
- `--skip-config`
- `--extensions-dir <path>`
- `--embedding-model <model>`

## Manual setup

1. Apply [`schema.sql`](./schema.sql) in Supabase SQL editor or via `psql`.
2. Configure plugin slot:

```json5
plugins: {
  slots: {
    memory: "memory-supabase"
  },
  entries: {
    "memory-supabase": {
      enabled: true,
      config: {
        supabase: {
          url: "${SUPABASE_URL}",
          serviceKey: "${SUPABASE_SERVICE_ROLE_KEY}" // set to sb_secret_...
        },
        embedding: {
          apiKey: "${OPENAI_API_KEY}",
          model: "text-embedding-3-small"
        },
        autoRecall: true,
        autoCapture: true
      }
    }
  }
}
```

3. Restart gateway:

```bash
openclaw gateway restart
```

## Troubleshooting

- If `plugin not found: "memory-supabase"` appears during config set, rerun `bash scripts/setup.sh --skip-install --skip-db`; the script includes a config-file fallback path.
- If `Cannot find module '@sinclair/typebox'` appears, runtime deps are missing in the extension dir. Run:

```bash
cd ~/.openclaw/extensions/memory-supabase
npm install --omit=dev
```

- If DB host `db.<project-ref>.supabase.co` does not resolve, use the pooler URL format in `.env.example`.

## End-to-end tests

This repo includes live E2E integration tests in [`index.e2e.test.ts`](./index.e2e.test.ts).
They exercise:

- Supabase RPC schema reachability
- OpenClaw plugin registration (tools/hooks/CLI/service)
- Full tool roundtrip (`memory_store` -> `memory_search` -> `memory_get` -> `memory_forget`)
- Auto-recall (`before_agent_start`) and auto-capture (`agent_end`) hooks
- CLI commands (`ltm stats`, `ltm search`)

Run:

```bash
export OPENCLAW_MEMORY_SUPABASE_E2E=1
export OPENCLAW_MEMORY_SUPABASE_URL="https://<project-ref>.supabase.co"
export OPENCLAW_MEMORY_SUPABASE_SERVICE_ROLE_KEY="sb_secret_..."
pnpm test:e2e
```

Notes:

- E2E tests are skipped unless `OPENCLAW_MEMORY_SUPABASE_E2E=1` and required env vars are set.
- Embeddings are mocked deterministically during E2E tests to keep runs stable while still exercising the full OpenClaw <-> Supabase integration path.

## Notes

- SQL schema defaults to `vector(1536)` for `text-embedding-3-small`.
- If you switch to `text-embedding-3-large`, update vector dimensions to `3072`.
- This plugin provides `memory_search`, `memory_get`, `memory_store`, and `memory_forget`.

tools