@parallelclaw/memex-openclaw 0.1.0

package/README.md

@@ -0,0 +1,135 @@
+# memex-openclaw
+
+**OpenClaw plugin that captures every turn verbatim into the [memex](https://memex.parallelclaw.ai) unified SQLite corpus.**
+
+Replaces the v0.11.x `memex-sync` file-watcher daemon. Captures via OpenClaw's native plugin lifecycle hooks — no file watching, no JSON parsing, no daemon to manage.
+
+> [!IMPORTANT]
+> **memex-openclaw is a bridge plugin, not a memory replacement.** It's most useful when you ALSO run other clients (Claude Code / Hermes / Cursor / Telegram exports) captured into the same [memex-mvp](https://www.npmjs.com/package/memex-mvp) corpus. If you only use OpenClaw with built-in memory-core / Memoria / Mem0 — that's already a complete memory stack; memex-openclaw mostly earns its place when you want **unified search across multiple AI clients**.
+
+## What it does
+
+Three lifecycle hooks + one corpus supplement:
+
+| Hook | What we do |
+|---|---|
+| `agent_end` | Insert the just-completed turn's user + assistant messages into memex.db, verbatim. Channel comes from `ctx.messageProvider` — no parsing. |
+| `before_compaction` | Save messages that are about to be dropped from active context. They become searchable from memex even after OpenClaw forgets them. |
+| `session_end` | Update conversation last_ts. Safety-net marker. |
+| `registerMemoryCorpusSupplement` | Memex contents are surfaced through OpenClaw's built-in `memory_search` / `memory_get` tools — the model sees memex rows alongside workspace memory in one search result. |
+
+Storage: `~/.memex/data/memex.db` (override via plugin config `dbPath`). Same SQLite schema as memex-mvp (npm) and memex-hermes (pip) — all three can write to the same DB concurrently.
+
+## Install
+
+Once published to npm:
+
+```bash
+openclaw plugins install @parallelclaw/memex-openclaw
+```
+
+For development / local install:
+
+```bash
+git clone https://github.com/parallelclaw/memex-mvp.git
+cd memex-mvp/plugins/memex-openclaw
+npm install
+openclaw plugins install --link "$(pwd)"
+```
+
+Enable in `~/.openclaw/openclaw.json`:
+
+```json
+{
+  "plugins": {
+    "entries": {
+      "memex-openclaw": {
+        "enabled": true
+      }
+    }
+  }
+}
+```
+
+Optional config (default db path is `~/.memex/data/memex.db`):
+
+```json
+{
+  "plugins": {
+    "entries": {
+      "memex-openclaw": {
+        "enabled": true,
+        "config": {
+          "dbPath": "/some/other/path/memex.db"
+        }
+      }
+    }
+  }
+}
+```
+
+Restart OpenClaw:
+
+```bash
+openclaw gateway restart
+```
+
+## Conversation routing
+
+| OpenClaw context | memex conversation_id |
+|---|---|
+| `messageProvider="telegram", channelId="97592799"` | `openclaw-telegram-97592799` |
+| `messageProvider="discord", channelId="..."` | `openclaw-discord-<channelId>` |
+| `messageProvider="cli"` (no channelId) | `openclaw-cli-<session8>` |
+| `messageProvider="cron"` | `openclaw-cron-<session8>` |
+
+Per-user threading: same Telegram chat across multiple OpenClaw sessions ends up in **one** memex conversation, just like memex-hermes does with Hermes.
+
+## Verify
+
+```bash
+# Hermes / OpenClaw / memex-mvp can all coexist — check OpenClaw rows:
+sqlite3 ~/.memex/data/memex.db \
+  "SELECT COUNT(*), MIN(date(ts,'unixepoch')), MAX(date(ts,'unixepoch'))
+     FROM messages WHERE source='openclaw'"
+
+# Or via memex-mvp CLI (npm i -g memex-mvp):
+memex recent --source openclaw
+memex search "your test query" --source openclaw
+```
+
+## What this plugin is NOT
+
+- ❌ Not a replacement for OpenClaw's built-in memory (memory-core / Active Memory). It augments — registers as a corpus supplement.
+- ❌ Not a fact extractor. Stores raw turns. Use Mem0 / Memoria alongside if you want extraction.
+- ❌ Not a vector store (yet). FTS5 lexical search only.
+- ❌ Not a single-client product. Earns its value when paired with memex-mvp + at least one other captured client.
+
+## Testing
+
+```bash
+npm install
+npm test     # 40 tests, ~1 second
+```
+
+## Architecture vs old memex-sync daemon (v0.11.x)
+
+| | Old (v0.11.x file-watcher) | New (this plugin) |
+|---|---|---|
+| Where it runs | Separate `memex-sync` Node daemon | Inside OpenClaw runtime |
+| How it captures | Polls `~/.openclaw/agents/main/sessions/*.jsonl` | Subscribes to `agent_end` hook |
+| Channel detection | Regex on message text + sessions.json parsing | `ctx.messageProvider` — no parsing |
+| Knowledge of OpenClaw file format | Hardcoded (paths, naming, `.reset.`, `.checkpoint.`) | None |
+| Lines of code | ~1000 (in memex-mvp lib/) | ~250 (this package) |
+| What breaks when OpenClaw changes its file format | Everything | Nothing |
+| What breaks when OpenClaw changes its plugin API | This plugin (one file to update) | — |
+
+## License
+
+MIT. See parent repository.
+
+## Related
+
+- [memex-mvp](https://www.npmjs.com/package/memex-mvp) — Node.js CLI + MCP server for the same `memex.db`. Install for search tools, dashboard, and capturing other clients (Claude Code, Cursor, Telegram).
+- [memex-hermes](https://pypi.org/project/memex-hermes/) — Python plugin doing the same for [Hermes Agent](https://github.com/NousResearch/hermes-agent).
+- [install-memex-claw](https://clawhub.ai/sedelev/install-memex-claw) — ClawHub skill that walks through the install.

package/index.js

@@ -0,0 +1,202 @@
+/**
+ * memex-openclaw — OpenClaw plugin that captures every turn verbatim
+ * into the memex unified SQLite corpus.
+ *
+ * Replaces the v0.11.x file-watcher daemon approach. This plugin:
+ *   • Subscribes to `agent_end` for per-turn capture — no file watching
+ *   • Subscribes to `before_compaction` to preserve messages before
+ *     they're dropped from active context
+ *   • Subscribes to `session_end` as a safety-net flush
+ *   • Registers a `MemoryCorpusSupplement` so the model's built-in
+ *     `memory_search` tool sees memex content alongside workspace memory
+ *
+ * Channel detection: zero parsing. OpenClaw 2026.5+ hands us
+ * `ctx.messageProvider` (e.g. "telegram") and `ctx.channelId` (e.g.
+ * "97592799") directly in the hook context.
+ *
+ * Storage: ~/.memex/data/memex.db (override via plugin config db_path).
+ * Schema parity with memex-mvp (npm) and memex-hermes (pip) — all three
+ * write to the same database with the same UNIQUE-constraint dedup.
+ *
+ * @see openclaw.plugin.json for manifest
+ * @see package.json for npm distribution
+ */
+
+import {
+  definePluginEntry,
+  registerMemoryCorpusSupplement,
+} from 'openclaw/plugin-sdk/core';
+
+import { MemexStore } from './lib/store.js';
+import { deriveConvId, deriveMsgId, extractText } from './lib/conv_id.js';
+import { buildCorpusSupplement } from './lib/corpus_supplement.js';
+
+export default definePluginEntry({
+  id: 'memex-openclaw',
+  name: 'Memex',
+  description:
+    'Captures every OpenClaw turn verbatim into the memex unified SQLite corpus. ' +
+    'Pair with memex-mvp (npm) to search OpenClaw + Hermes + Claude Code + Telegram from one place.',
+  kind: 'memory',
+
+  register(api) {
+    const logger = api.logger;
+    const cfg = api.pluginConfig || {};
+    let store;
+
+    try {
+      store = new MemexStore(cfg.dbPath);
+      logger.info(`memex-openclaw: opened ${store.dbPath} (current rows: ${store.count()})`);
+    } catch (err) {
+      logger.error(`memex-openclaw: failed to open memex.db: ${err.message}`);
+      return; // can't operate without store
+    }
+
+    // -------------------------------------------------------------
+    // 1. Primary capture — every turn that completes successfully
+    // -------------------------------------------------------------
+    api.on('agent_end', async (event, ctx) => {
+      if (!event?.success) return; // failed turns are skipped (LLM error, etc.)
+      try {
+        const platform = ctx?.messageProvider || 'unknown';
+        const channelId = ctx?.channelId;
+        const sessionId = ctx?.sessionId;
+        const agentId = ctx?.agentId || 'main';
+        const convId = deriveConvId({ messageProvider: platform, channelId, sessionId });
+
+        // Capture only the LAST TURN's user + assistant messages —
+        // earlier history was captured by prior agent_end invocations.
+        // (OpenClaw passes full conversation history but most of it is
+        // already in memex.db from previous turns; UNIQUE dedup makes
+        // re-inserting harmless but wasteful.)
+        const messages = Array.isArray(event.messages) ? event.messages : [];
+        const lastTurn = messages.slice(-2);
+
+        const baseTs = Math.floor(Date.now() / 1000);
+        for (let i = 0; i < lastTurn.length; i++) {
+          const msg = lastTurn[i];
+          if (!msg || (msg.role !== 'user' && msg.role !== 'assistant')) continue;
+          const text = extractText(msg);
+          if (!text || !text.trim()) continue;
+
+          const msgId = deriveMsgId({ role: msg.role, text, convId });
+          store.insertMessage({
+            conversationId: convId,
+            msgId,
+            role: msg.role,
+            text,
+            ts: baseTs + i, // tiny offset to preserve order
+            channel: platform,
+            metadata: {
+              raw_type: 'openclaw-agent-end',
+              session_id: sessionId,
+              agent_id: agentId,
+              platform,
+              channel_id: channelId,
+              model_provider: ctx?.modelProviderId,
+              model_id: ctx?.modelId,
+              run_id: event.runId,
+            },
+          });
+        }
+
+        // Keep conversations.last_ts current.
+        store.upsertConversation({
+          conversationId: convId,
+          title: convId,
+          firstTs: baseTs,
+          lastTs: baseTs,
+        });
+      } catch (err) {
+        logger.error(`memex-openclaw: agent_end capture failed: ${err.message}`);
+      }
+    });
+
+    // -------------------------------------------------------------
+    // 2. Preserve messages before they're compacted out of context
+    // -------------------------------------------------------------
+    api.on('before_compaction', async (event, ctx) => {
+      try {
+        const messages = Array.isArray(event?.messages) ? event.messages : [];
+        if (messages.length === 0) return;
+
+        const platform = ctx?.messageProvider || 'unknown';
+        const channelId = ctx?.channelId;
+        const sessionId = ctx?.sessionId;
+        const convId = deriveConvId({ messageProvider: platform, channelId, sessionId });
+
+        const baseTs = Math.floor(Date.now() / 1000);
+        let saved = 0;
+        for (let i = 0; i < messages.length; i++) {
+          const msg = messages[i];
+          if (!msg || (msg.role !== 'user' && msg.role !== 'assistant')) continue;
+          const text = extractText(msg);
+          if (!text || !text.trim()) continue;
+          const wrote = store.insertMessage({
+            conversationId: convId,
+            msgId: deriveMsgId({ role: msg.role, text, convId }),
+            role: msg.role,
+            text,
+            ts: baseTs + i,
+            channel: platform,
+            metadata: {
+              raw_type: 'openclaw-pre-compaction',
+              session_id: sessionId,
+              platform,
+              channel_id: channelId,
+            },
+          });
+          if (wrote) saved++;
+        }
+        if (saved > 0) {
+          logger.info(
+            `memex-openclaw: preserved ${saved} message(s) before compaction (conv=${convId})`,
+          );
+        }
+      } catch (err) {
+        logger.error(`memex-openclaw: before_compaction failed: ${err.message}`);
+      }
+    });
+
+    // -------------------------------------------------------------
+    // 3. Session-end safety net — flush the full final history
+    // -------------------------------------------------------------
+    api.on('session_end', async (event, ctx) => {
+      try {
+        // session_end doesn't carry messages[] in OpenClaw 2026.5 —
+        // we have sessionId + sessionKey + reason. The hook serves as
+        // a marker that this conv is "done"; we update conv last_ts
+        // and let agent_end captures already-in-DB stand.
+        const platform = ctx?.messageProvider || 'unknown';
+        const channelId = ctx?.channelId;
+        const sessionId = event?.sessionId || ctx?.sessionId;
+        const convId = deriveConvId({ messageProvider: platform, channelId, sessionId });
+        store.upsertConversation({
+          conversationId: convId,
+          title: convId,
+          lastTs: Math.floor(Date.now() / 1000),
+        });
+        logger.debug(`memex-openclaw: session_end conv=${convId} reason=${event?.reason}`);
+      } catch (err) {
+        logger.error(`memex-openclaw: session_end failed: ${err.message}`);
+      }
+    });
+
+    // -------------------------------------------------------------
+    // 4. Expose memex contents to OpenClaw's built-in memory_search
+    // -------------------------------------------------------------
+    try {
+      const supplement = buildCorpusSupplement(store, logger);
+      registerMemoryCorpusSupplement('memex-openclaw', supplement);
+      logger.info('memex-openclaw: registered as memory corpus supplement');
+    } catch (err) {
+      // Non-fatal — capture still works without supplement registration.
+      logger.warn(
+        `memex-openclaw: could not register corpus supplement: ${err.message} ` +
+        '(capture still active; built-in memory_search will not surface memex rows)',
+      );
+    }
+
+    logger.info('memex-openclaw: plugin activated');
+  },
+});

package/lib/corpus_supplement.js

@@ -0,0 +1,131 @@
+/**
+ * MemoryCorpusSupplement adapter — exposes memex contents to OpenClaw's
+ * built-in `memory_search` and `memory_get` tools.
+ *
+ * The OpenClaw runtime ships memory-core, which provides workspace-based
+ * memory (MEMORY.md / USER.md / memory/YYYY-MM-DD.md). Plugins can
+ * REGISTER A SUPPLEMENT — additional rows that show up in the same tool
+ * output, prefixed/labelled so the model knows which corpus a row came
+ * from.
+ *
+ * This is the strategic positioning: memex doesn't REPLACE memory-core,
+ * it ADDS to it. The model sees a single `memory_search` tool, gets
+ * results from BOTH built-in workspace memory AND memex's verbatim
+ * cross-client corpus, in one shot.
+ *
+ * Multi-plugin coexistence: Mem0, Memoria, memex can all register
+ * their own supplements. OpenClaw merges results.
+ */
+
+const CORPUS_LABEL = 'memex';
+
+/**
+ * Build the supplement object that gets handed to OpenClaw's
+ * `registerMemoryCorpusSupplement(pluginId, supplement)` call.
+ *
+ * Contract (from OpenClaw 2026.5.4 plugin-sdk/memory-state.d.ts):
+ *
+ *   supplement.search({ query, maxResults, agentSessionKey })
+ *     → Promise<MemoryCorpusSearchResult[]>
+ *
+ *   supplement.get({ lookup, fromLine, lineCount, agentSessionKey })
+ *     → Promise<MemoryCorpusGetResult | null>
+ */
+export function buildCorpusSupplement(store, logger) {
+  return {
+    async search({ query, maxResults = 10 } = {}) {
+      try {
+        const rows = store.search(query || '', maxResults);
+        return rows.map((r) => toSearchResult(r));
+      } catch (err) {
+        logger?.warn?.(`memex-openclaw: corpus search failed: ${err.message}`);
+        return [];
+      }
+    },
+
+    async get({ lookup }) {
+      // `lookup` is the id we returned in search results' `id` field.
+      // We use the message row id as a string for portability.
+      try {
+        const numericId = parseInt(String(lookup).replace(/^memex:/, ''), 10);
+        if (!Number.isFinite(numericId)) return null;
+        const row = store.getById(numericId);
+        return row ? toGetResult(row) : null;
+      } catch (err) {
+        logger?.warn?.(`memex-openclaw: corpus get failed: ${err.message}`);
+        return null;
+      }
+    },
+  };
+}
+
+/**
+ * Map a memex row (from store.search) to OpenClaw's
+ * MemoryCorpusSearchResult shape:
+ *
+ *   { corpus, path, title?, kind?, score, snippet, id?,
+ *     startLine?, endLine?, citation?, source?,
+ *     provenanceLabel?, sourceType?, sourcePath?, updatedAt? }
+ */
+function toSearchResult(row) {
+  const date = row.ts ? new Date(row.ts * 1000).toISOString() : undefined;
+  return {
+    corpus: CORPUS_LABEL,
+    id: `memex:${row.id}`,
+    path: `memex://${row.conversation_id}/#msg-${row.id}`,
+    title: titleFromRow(row),
+    kind: row.channel || 'openclaw',
+    score: 1.0, // memex returns ranked-by-ts; bm25 inside FTS would refine
+    snippet: row.preview || '',
+    source: 'openclaw',
+    provenanceLabel: row.channel
+      ? `memex • ${row.channel}`
+      : 'memex • openclaw',
+    sourceType: 'verbatim',
+    sourcePath: row.conversation_id,
+    updatedAt: date,
+  };
+}
+
+/**
+ * Map a memex row (from store.getById) to OpenClaw's
+ * MemoryCorpusGetResult shape:
+ *
+ *   { corpus, path, title?, kind?, content, fromLine, lineCount,
+ *     id?, provenanceLabel?, sourceType?, sourcePath?, updatedAt? }
+ */
+function toGetResult(row) {
+  const date = row.ts ? new Date(row.ts * 1000).toISOString() : undefined;
+  const lineCount = row.text ? row.text.split('\n').length : 1;
+  return {
+    corpus: CORPUS_LABEL,
+    id: `memex:${row.id}`,
+    path: `memex://${row.conversation_id}/#msg-${row.id}`,
+    title: titleFromRow(row),
+    kind: row.channel || 'openclaw',
+    content: row.text || '',
+    fromLine: 1,
+    lineCount,
+    provenanceLabel: row.channel
+      ? `memex • ${row.channel}`
+      : 'memex • openclaw',
+    sourceType: 'verbatim',
+    sourcePath: row.conversation_id,
+    updatedAt: date,
+  };
+}
+
+function titleFromRow(row) {
+  const role = row.role || '?';
+  const when = row.ts
+    ? new Date(row.ts * 1000).toISOString().slice(0, 10)
+    : '?';
+  // First ~40 chars of text → title-ish
+  const preview = (row.text || row.preview || '')
+    .replace(/\s+/g, ' ')
+    .trim()
+    .slice(0, 40);
+  return preview
+    ? `[${when} ${role}] ${preview}${preview.length === 40 ? '…' : ''}`
+    : `${role} @ ${when}`;
+}

package/lib/store.js

@@ -0,0 +1,227 @@
+/**
+ * SQLite layer for memex-openclaw.
+ *
+ * Opens the shared memex.db at ~/.memex/data/memex.db (override via
+ * plugin config db_path), creates the schema if absent, exposes
+ * insert/search/get operations.
+ *
+ * Schema parity with memex-mvp (Node) and memex-hermes (Python) — all
+ * three write to the SAME memex.db using identical tables, columns,
+ * and the UNIQUE(source, conversation_id, msg_id) constraint that
+ * makes inserts idempotent.
+ *
+ * WAL mode → concurrent reads from memex CLI / MCP server are safe
+ * while we write.
+ */
+
+import Database from 'better-sqlite3';
+import { mkdirSync } from 'node:fs';
+import { dirname } from 'node:path';
+import { homedir } from 'node:os';
+import { resolve } from 'node:path';
+
+export const DEFAULT_DB_PATH = '~/.memex/data/memex.db';
+
+/**
+ * Expand `~` and turn a possibly-relative path into an absolute one.
+ */
+export function resolveDbPath(p) {
+  if (!p || typeof p !== 'string') p = DEFAULT_DB_PATH;
+  let s = p.trim();
+  if (s.startsWith('~/')) s = homedir() + s.slice(1);
+  else if (s === '~') s = homedir();
+  return resolve(s);
+}
+
+function safeAlter(db, sql) {
+  try {
+    db.exec(sql);
+  } catch (err) {
+    if (!String(err.message).toLowerCase().includes('duplicate column')) throw err;
+  }
+}
+
+/**
+ * Apply the memex.db schema. Idempotent — every CREATE uses IF NOT
+ * EXISTS, ALTERs swallow "duplicate column" errors. Safe to call
+ * against an existing memex.db created by memex-mvp or memex-hermes.
+ */
+export function initialiseSchema(db) {
+  db.pragma('journal_mode = WAL');
+  db.pragma('synchronous = NORMAL');
+
+  db.exec(`
+    CREATE TABLE IF NOT EXISTS messages (
+      id              INTEGER PRIMARY KEY AUTOINCREMENT,
+      source          TEXT NOT NULL,
+      conversation_id TEXT NOT NULL,
+      msg_id          TEXT,
+      role            TEXT,
+      sender          TEXT,
+      text            TEXT,
+      ts              INTEGER,
+      metadata        TEXT,
+      UNIQUE(source, conversation_id, msg_id)
+    );
+    CREATE INDEX IF NOT EXISTS idx_messages_ts ON messages(ts);
+    CREATE INDEX IF NOT EXISTS idx_messages_conv ON messages(conversation_id);
+    CREATE INDEX IF NOT EXISTS idx_messages_source ON messages(source);
+
+    CREATE VIRTUAL TABLE IF NOT EXISTS messages_fts USING fts5(
+      text, sender, conversation_id, source,
+      content=messages, content_rowid=id,
+      tokenize='unicode61 remove_diacritics 2'
+    );
+
+    CREATE TABLE IF NOT EXISTS conversations (
+      conversation_id        TEXT PRIMARY KEY,
+      source                 TEXT NOT NULL,
+      title                  TEXT,
+      first_ts               INTEGER,
+      last_ts                INTEGER,
+      message_count          INTEGER DEFAULT 0
+    );
+  `);
+
+  safeAlter(db, 'ALTER TABLE messages ADD COLUMN edited_at INTEGER');
+  safeAlter(db, 'ALTER TABLE messages ADD COLUMN uuid TEXT');
+  safeAlter(db, 'ALTER TABLE messages ADD COLUMN channel TEXT');
+  safeAlter(db, 'ALTER TABLE conversations ADD COLUMN archived_at INTEGER');
+  safeAlter(db, 'ALTER TABLE conversations ADD COLUMN parent_conversation_id TEXT');
+  safeAlter(db, 'ALTER TABLE conversations ADD COLUMN project_path TEXT');
+
+  db.exec(`
+    CREATE INDEX IF NOT EXISTS idx_messages_uuid
+      ON messages(uuid) WHERE uuid IS NOT NULL;
+    CREATE INDEX IF NOT EXISTS idx_messages_channel
+      ON messages(channel) WHERE channel IS NOT NULL;
+
+    DROP TRIGGER IF EXISTS messages_fts_ai;
+    DROP TRIGGER IF EXISTS messages_fts_ad;
+    DROP TRIGGER IF EXISTS messages_fts_au;
+    CREATE TRIGGER messages_fts_ai AFTER INSERT ON messages
+      WHEN new.role != 'summary' BEGIN
+        INSERT INTO messages_fts(rowid, text, sender, conversation_id, source)
+        VALUES (new.id, new.text, new.sender, new.conversation_id, new.source);
+      END;
+    CREATE TRIGGER messages_fts_ad AFTER DELETE ON messages BEGIN
+      DELETE FROM messages_fts WHERE rowid = old.id;
+    END;
+    CREATE TRIGGER messages_fts_au AFTER UPDATE ON messages BEGIN
+      DELETE FROM messages_fts WHERE rowid = old.id;
+      INSERT INTO messages_fts(rowid, text, sender, conversation_id, source)
+        SELECT new.id, new.text, new.sender, new.conversation_id, new.source
+         WHERE new.role != 'summary';
+    END;
+  `);
+}
+
+export class MemexStore {
+  constructor(dbPath) {
+    this.dbPath = resolveDbPath(dbPath);
+    mkdirSync(dirname(this.dbPath), { recursive: true });
+    this.db = new Database(this.dbPath);
+    initialiseSchema(this.db);
+
+    // Prepared statements (faster on the hot path).
+    this._insertMsg = this.db.prepare(`
+      INSERT OR IGNORE INTO messages
+        (source, conversation_id, msg_id, role, sender, text, ts, metadata, channel)
+      VALUES ('openclaw', @conversationId, @msgId, @role, @sender, @text, @ts, @metadata, @channel)
+    `);
+
+    this._upsertConv = this.db.prepare(`
+      INSERT INTO conversations
+        (conversation_id, source, title, first_ts, last_ts, message_count)
+      VALUES (@conversationId, 'openclaw', @title, @firstTs, @lastTs, 0)
+      ON CONFLICT(conversation_id) DO UPDATE SET
+        title    = COALESCE(conversations.title, excluded.title),
+        first_ts = MIN(COALESCE(conversations.first_ts, excluded.first_ts), excluded.first_ts),
+        last_ts  = MAX(COALESCE(conversations.last_ts,  excluded.last_ts),  excluded.last_ts),
+        message_count = (
+          SELECT COUNT(*) FROM messages
+           WHERE messages.conversation_id = conversations.conversation_id
+        )
+    `);
+
+    this._searchStmt = this.db.prepare(`
+      SELECT m.id, m.ts, m.role, m.conversation_id, m.channel,
+             substr(m.text, 1, 100) AS preview
+        FROM messages_fts f
+        JOIN messages m ON m.id = f.rowid
+       WHERE f.text MATCH ? AND m.source = 'openclaw'
+       ORDER BY m.ts DESC
+       LIMIT ?
+    `);
+
+    this._getStmt = this.db.prepare(`
+      SELECT id, ts, role, sender, conversation_id, channel, text, metadata
+        FROM messages
+       WHERE id = ? AND source = 'openclaw'
+    `);
+
+    this._countStmt = this.db.prepare(`
+      SELECT COUNT(*) AS n FROM messages WHERE source = 'openclaw'
+    `);
+  }
+
+  close() {
+    try { this.db.close(); } catch { /* already closed */ }
+  }
+
+  /**
+   * Insert one verbatim message. Returns true if a new row was created,
+   * false if the UNIQUE constraint deduped it (idempotent).
+   */
+  insertMessage({ conversationId, msgId, role, text, ts, channel, sender, metadata }) {
+    if (!text || !String(text).trim()) return false;
+    const senderNorm = sender || (role === 'user' ? 'me' : 'openclaw');
+    const result = this._insertMsg.run({
+      conversationId,
+      msgId,
+      role,
+      sender: senderNorm,
+      text: String(text),
+      ts: ts || Math.floor(Date.now() / 1000),
+      metadata: JSON.stringify(metadata || {}),
+      channel: channel ?? null,
+    });
+    return result.changes > 0;
+  }
+
+  upsertConversation({ conversationId, title, firstTs, lastTs }) {
+    this._upsertConv.run({
+      conversationId,
+      title: title || conversationId,
+      firstTs: firstTs ?? null,
+      lastTs: lastTs ?? null,
+    });
+  }
+
+  /**
+   * FTS5 search restricted to source='openclaw'. Returns abbreviated rows
+   * (id + ts + role + 100-char preview) — full text is fetched via getById()
+   * to support the progressive-disclosure pattern.
+   */
+  search(query, limit = 10) {
+    if (!query || !String(query).trim()) return [];
+    try {
+      return this._searchStmt.all(String(query).trim(), Math.min(Math.max(Number(limit) || 10, 1), 50));
+    } catch (err) {
+      // Malformed FTS5 syntax — return empty rather than crash.
+      return [];
+    }
+  }
+
+  getById(id) {
+    const row = this._getStmt.get(Number(id));
+    if (!row) return null;
+    try { row.metadata = JSON.parse(row.metadata || '{}'); }
+    catch { row.metadata = {}; }
+    return row;
+  }
+
+  count() {
+    return this._countStmt.get().n;
+  }
+}

package/openclaw.plugin.json

@@ -0,0 +1,17 @@
+{
+  "id": "memex-openclaw",
+  "name": "Memex",
+  "description": "Captures every OpenClaw turn verbatim into the memex unified SQLite corpus. Pair with memex-mvp (npm) to search OpenClaw + Hermes + Claude Code + Telegram from one place.",
+  "version": "0.1.0",
+  "kind": "memory",
+  "activation": {
+    "onStartup": true
+  },
+  "contracts": {
+    "memoryCorpusSupplements": ["memex-openclaw"]
+  },
+  "uiHints": {
+    "category": "memory",
+    "displayName": "Memex (verbatim corpus)"
+  }
+}

package/package.json

@@ -0,0 +1,66 @@
+{
+  "name": "@parallelclaw/memex-openclaw",
+  "version": "0.1.0",
+  "description": "OpenClaw plugin that captures every turn verbatim into the memex unified SQLite corpus. Pair with memex-mvp for one searchable history across OpenClaw, Hermes, Claude Code, Telegram, and more.",
+  "type": "module",
+  "main": "index.js",
+  "exports": {
+    ".": "./index.js"
+  },
+  "files": [
+    "index.js",
+    "openclaw.plugin.json",
+    "lib/",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "test": "node --test tests/*.test.js"
+  },
+  "openclaw": {
+    "extensions": [
+      "./index.js"
+    ]
+  },
+  "engines": {
+    "node": ">=22.12.0"
+  },
+  "dependencies": {
+    "better-sqlite3": "^11.0.0"
+  },
+  "peerDependencies": {
+    "openclaw": ">=2026.5.0"
+  },
+  "peerDependenciesMeta": {
+    "openclaw": {
+      "optional": false
+    }
+  },
+  "keywords": [
+    "openclaw",
+    "openclaw-plugin",
+    "memex",
+    "memory",
+    "verbatim",
+    "local-first",
+    "sqlite",
+    "fts5",
+    "parallelclaw",
+    "ai-memory"
+  ],
+  "author": {
+    "name": "parallelclaw",
+    "email": "sedelev@gmail.com",
+    "url": "https://memex.parallelclaw.ai"
+  },
+  "license": "MIT",
+  "homepage": "https://memex.parallelclaw.ai",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/parallelclaw/memex-mvp.git",
+    "directory": "plugins/memex-openclaw"
+  },
+  "bugs": {
+    "url": "https://github.com/parallelclaw/memex-mvp/issues"
+  }
+}