openclaw-memory-alibaba-mysql 0.2.4 → 0.2.5

package/config.ts

@@ -24,8 +24,10 @@ export type LLMConfig = {
 };
 
 export type MemoryConfig = {
-  mysql: MysqlConnectionConfig;
-  embedding: EmbeddingConfig;
+  /** Omitted when plugin is loaded without DB config (e.g. npm install); required at runtime for memory ops. */
+  mysql?: MysqlConnectionConfig;
+  /** Omitted when plugin is loaded without DB config; required at runtime for memory ops. */
+  embedding?: EmbeddingConfig;
   /** When true, use LLM to decide insert vs update among top-10 similar memories; requires llm config. Default false. */
   memory_duplication_conflict_process: boolean;
   /** Required when memory_duplication_conflict_process is true. */
@@ -204,6 +206,37 @@ export const memoryConfigSchema = {
       "memory config",
     );
 
+    // --- When DB config is missing, return minimal config without throwing (e.g. npm install) ---
+    if (!cfg.mysql || typeof cfg.mysql !== "object" || Array.isArray(cfg.mysql) ||
+        !cfg.embedding || typeof cfg.embedding !== "object" || Array.isArray(cfg.embedding)) {
+      const tableName =
+        typeof cfg.tableName === "string" && /^[a-zA-Z_][a-zA-Z0-9_]*$/.test(cfg.tableName)
+          ? cfg.tableName
+          : DEFAULT_TABLE_NAME;
+      const capChars =
+        typeof cfg.captureMaxChars === "number" && cfg.captureMaxChars >= 100 && cfg.captureMaxChars <= 100_000
+          ? Math.floor(cfg.captureMaxChars)
+          : DEFAULT_CAPTURE_MAX_CHARS;
+      return {
+        mysql: undefined,
+        embedding: undefined,
+        memory_duplication_conflict_process: false,
+        llm: undefined,
+        similarityThresholdUserMemory: 0.95,
+        similarityThresholdSelfImproving: 0.92,
+        enableFullContextMemory: false,
+        enableSelfImprovingMemory: false,
+        memoryExtractionMethod: "llm",
+        autoRecall: cfg.autoRecall !== false,
+        autoCapture: cfg.autoCapture !== false,
+        captureMaxChars: capChars,
+        enableMemoryDecay: false,
+        memoryDecayHalfLifeDays: 30,
+        memoryDecayStrategy: "exponential",
+        tableName,
+      };
+    }
+
     // --- LLM requirement ---
     const memory_duplication_conflict_process = cfg.memory_duplication_conflict_process === true;
     const rawMethod =

package/db.ts

@@ -1,6 +1,6 @@
 import { randomUUID } from "node:crypto";
 import mysql from "mysql2/promise";
-import type { Pool } from "mysql2/promise";
+import type { Connection } from "mysql2/promise";
 import type { MemoryCategory } from "./config.js";
 import { USER_MEMORY_FACT } from "./categories.js";
 import type { MysqlConnectionConfig } from "./config.js";
@@ -29,8 +29,6 @@ function stripFourByteUtf8(text: string): string {
 }
 
 export class MemoryDB {
-  private pool: Pool | null = null;
-  private initPromise: Promise<void> | null = null;
   private vectorIndexCreated = false;
 
   constructor(
@@ -39,58 +37,48 @@ export class MemoryDB {
     private readonly vectorDim: number,
   ) {}
 
-  private async ensureInitialized(): Promise<void> {
-    if (this.pool) {
-      return;
-    }
-    if (this.initPromise) {
-      return this.initPromise;
-    }
-    this.initPromise = this.doInitialize();
-    return this.initPromise;
-  }
-
-  private async doInitialize(): Promise<void> {
-    this.pool = mysql.createPool({
+  /** Short-lived connection: create, ensure table, run fn, close. */
+  private async withConnection<T>(fn: (conn: Connection) => Promise<T>): Promise<T> {
+    const conn = await mysql.createConnection({
       host: this.mysqlConfig.host,
       port: this.mysqlConfig.port,
       user: this.mysqlConfig.user,
       password: this.mysqlConfig.password,
       database: this.mysqlConfig.database,
       ssl: this.mysqlConfig.ssl ? {} : undefined,
-      connectionLimit: 5,
-      waitForConnections: true,
-      queueLimit: 0,
     });
-
-    const conn = await this.pool.getConnection();
     try {
       await conn.query("SET SESSION TRANSACTION ISOLATION LEVEL READ COMMITTED");
-      await conn.query(`
-        CREATE TABLE IF NOT EXISTS \`${this.tableName}\` (
-          id         VARCHAR(36)   NOT NULL PRIMARY KEY,
-          agent_id   VARCHAR(128)  NOT NULL,
-          user_id    VARCHAR(128)  NULL DEFAULT NULL,
-          session_id VARCHAR(128)  NULL DEFAULT NULL,
-          text       LONGTEXT      NOT NULL,
-          embedding  VECTOR(${this.vectorDim}) NOT NULL,
-          importance FLOAT         DEFAULT 0,
-          category   VARCHAR(64)   DEFAULT '${USER_MEMORY_FACT}',
-          created_at BIGINT        NOT NULL,
-          is_deleted TINYINT       NOT NULL DEFAULT 0,
-          INDEX idx_agent_id (agent_id),
-          INDEX idx_agent_session_category (agent_id, session_id, category)
-        ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci
-      `);
-      await this.ensureIsDeletedColumn(conn);
-      await this.ensureSessionCategoryIndex(conn);
-      await this.tryCreateVectorIndex(conn);
+      await this.ensureTable(conn);
+      return await fn(conn);
     } finally {
-      conn.release();
+      await conn.end();
     }
   }
 
-  private async ensureIsDeletedColumn(conn: mysql.PoolConnection): Promise<void> {
+  private async ensureTable(conn: Connection): Promise<void> {
+    await conn.query(`
+      CREATE TABLE IF NOT EXISTS \`${this.tableName}\` (
+        id         VARCHAR(36)   NOT NULL PRIMARY KEY,
+        agent_id   VARCHAR(128)  NOT NULL,
+        user_id    VARCHAR(128)  NULL DEFAULT NULL,
+        session_id VARCHAR(128)  NULL DEFAULT NULL,
+        text       LONGTEXT      NOT NULL,
+        embedding  VECTOR(${this.vectorDim}) NOT NULL,
+        importance FLOAT         DEFAULT 0,
+        category   VARCHAR(64)   DEFAULT '${USER_MEMORY_FACT}',
+        created_at BIGINT        NOT NULL,
+        is_deleted TINYINT       NOT NULL DEFAULT 0,
+        INDEX idx_agent_id (agent_id),
+        INDEX idx_agent_session_category (agent_id, session_id, category)
+      ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci
+    `);
+    await this.ensureIsDeletedColumn(conn);
+    await this.ensureSessionCategoryIndex(conn);
+    await this.tryCreateVectorIndex(conn);
+  }
+
+  private async ensureIsDeletedColumn(conn: Connection): Promise<void> {
     const [rows] = await conn.query(
       `SELECT COLUMN_NAME FROM information_schema.COLUMNS
        WHERE TABLE_SCHEMA = DATABASE() AND TABLE_NAME = ? AND COLUMN_NAME = 'is_deleted'`,
@@ -102,7 +90,7 @@ export class MemoryDB {
     );
   }
 
-  private async ensureSessionCategoryIndex(conn: mysql.PoolConnection): Promise<void> {
+  private async ensureSessionCategoryIndex(conn: Connection): Promise<void> {
     const [rows] = await conn.query(
       `SELECT COUNT(1) AS cnt FROM information_schema.statistics
        WHERE table_schema = DATABASE() AND table_name = ? AND index_name = 'idx_agent_session_category'`,
@@ -114,7 +102,7 @@ export class MemoryDB {
     );
   }
 
-  private async tryCreateVectorIndex(conn: mysql.PoolConnection): Promise<void> {
+  private async tryCreateVectorIndex(conn: Connection): Promise<void> {
     if (this.vectorIndexCreated) {
       return;
     }
@@ -151,38 +139,33 @@ export class MemoryDB {
       sessionId?: string | null;
     },
   ): Promise<MemoryEntry> {
-    await this.ensureInitialized();
+    return this.withConnection(async (conn) => {
+      const id = randomUUID();
+      const createdAt = Date.now();
+      const vectorStr = JSON.stringify(entry.vector);
+      const userId = entry.userId ?? null;
+      const sessionId = entry.sessionId ?? null;
+      const textSafe = stripFourByteUtf8(entry.text);
 
-    const id = randomUUID();
-    const createdAt = Date.now();
-    const vectorStr = JSON.stringify(entry.vector);
-    const userId = entry.userId ?? null;
-    const sessionId = entry.sessionId ?? null;
-    const textSafe = stripFourByteUtf8(entry.text);
-
-    await this.pool!.query(
-      `INSERT INTO \`${this.tableName}\` (id, agent_id, user_id, session_id, text, embedding, importance, category, created_at, is_deleted)
-       VALUES (?, ?, ?, ?, ?, VEC_FROMTEXT(?), ?, ?, ?, 0)`,
-      [id, agentId, userId, sessionId, textSafe, vectorStr, entry.importance, entry.category, createdAt],
-    );
+      await conn.query(
+        `INSERT INTO \`${this.tableName}\` (id, agent_id, user_id, session_id, text, embedding, importance, category, created_at, is_deleted)
+         VALUES (?, ?, ?, ?, ?, VEC_FROMTEXT(?), ?, ?, ?, 0)`,
+        [id, agentId, userId, sessionId, textSafe, vectorStr, entry.importance, entry.category, createdAt],
+      );
 
-    if (!this.vectorIndexCreated) {
-      const conn = await this.pool!.getConnection();
-      try {
+      if (!this.vectorIndexCreated) {
         await this.tryCreateVectorIndex(conn);
-      } finally {
-        conn.release();
       }
-    }
 
-    return {
-      id,
-      agentId,
-      text: textSafe,
-      importance: entry.importance,
-      category: entry.category,
-      createdAt,
-    };
+      return {
+        id,
+        agentId,
+        text: textSafe,
+        importance: entry.importance,
+        category: entry.category,
+        createdAt,
+      };
+    });
   }
 
   /**
@@ -200,32 +183,55 @@ export class MemoryDB {
       userId?: string | null;
     },
   ): Promise<{ action: "created" | "updated"; entry: MemoryEntry }> {
-    await this.ensureInitialized();
+    return this.withConnection(async (conn) => {
+      const textSafe = stripFourByteUtf8(entry.text);
+      const vectorStr = JSON.stringify(entry.vector);
+      const userId = entry.userId ?? null;
+      const createdAt = Date.now();
+
+      const [existingRows] = await conn.query(
+        `SELECT id FROM \`${this.tableName}\`
+         WHERE agent_id = ? AND category = ? AND is_deleted = 0
+           AND ((? IS NULL AND session_id IS NULL) OR (session_id = ?))
+         LIMIT 1`,
+        [agentId, entry.category, sessionId, sessionId],
+      );
+      const existing = (existingRows as Array<{ id: string }>)[0];
+
+      if (existing) {
+        await conn.query(
+          `UPDATE \`${this.tableName}\` SET text = ?, embedding = VEC_FROMTEXT(?), importance = ?, created_at = ?, user_id = ?
+           WHERE id = ? AND agent_id = ?`,
+          [textSafe, vectorStr, entry.importance, createdAt, userId, existing.id, agentId],
+        );
+        return {
+          action: "updated",
+          entry: {
+            id: existing.id,
+            agentId,
+            text: textSafe,
+            importance: entry.importance,
+            category: entry.category,
+            createdAt,
+          },
+        };
+      }
 
-    const textSafe = stripFourByteUtf8(entry.text);
-    const vectorStr = JSON.stringify(entry.vector);
-    const userId = entry.userId ?? null;
-    const createdAt = Date.now();
+      const id = randomUUID();
+      await conn.query(
+        `INSERT INTO \`${this.tableName}\` (id, agent_id, user_id, session_id, text, embedding, importance, category, created_at, is_deleted)
+         VALUES (?, ?, ?, ?, ?, VEC_FROMTEXT(?), ?, ?, ?, 0)`,
+        [id, agentId, userId, sessionId, textSafe, vectorStr, entry.importance, entry.category, createdAt],
+      );
 
-    const [existingRows] = await this.pool!.query(
-      `SELECT id FROM \`${this.tableName}\`
-       WHERE agent_id = ? AND category = ? AND is_deleted = 0
-         AND ((? IS NULL AND session_id IS NULL) OR (session_id = ?))
-       LIMIT 1`,
-      [agentId, entry.category, sessionId, sessionId],
-    );
-    const existing = (existingRows as Array<{ id: string }>)[0];
+      if (!this.vectorIndexCreated) {
+        await this.tryCreateVectorIndex(conn);
+      }
 
-    if (existing) {
-      await this.pool!.query(
-        `UPDATE \`${this.tableName}\` SET text = ?, embedding = VEC_FROMTEXT(?), importance = ?, created_at = ?, user_id = ?
-         WHERE id = ? AND agent_id = ?`,
-        [textSafe, vectorStr, entry.importance, createdAt, userId, existing.id, agentId],
-      );
       return {
-        action: "updated",
+        action: "created",
         entry: {
-          id: existing.id,
+          id,
           agentId,
           text: textSafe,
           importance: entry.importance,
@@ -233,35 +239,7 @@ export class MemoryDB {
           createdAt,
         },
       };
-    }
-
-    const id = randomUUID();
-    await this.pool!.query(
-      `INSERT INTO \`${this.tableName}\` (id, agent_id, user_id, session_id, text, embedding, importance, category, created_at, is_deleted)
-       VALUES (?, ?, ?, ?, ?, VEC_FROMTEXT(?), ?, ?, ?, 0)`,
-      [id, agentId, userId, sessionId, textSafe, vectorStr, entry.importance, entry.category, createdAt],
-    );
-
-    if (!this.vectorIndexCreated) {
-      const conn = await this.pool!.getConnection();
-      try {
-        await this.tryCreateVectorIndex(conn);
-      } finally {
-        conn.release();
-      }
-    }
-
-    return {
-      action: "created",
-      entry: {
-        id,
-        agentId,
-        text: textSafe,
-        importance: entry.importance,
-        category: entry.category,
-        createdAt,
-      },
-    };
+    });
   }
 
   /**
@@ -275,51 +253,50 @@ export class MemoryDB {
     minScore = 0.5,
     categories?: MemoryCategory[],
   ): Promise<MemorySearchResult[]> {
-    await this.ensureInitialized();
-
-    const vectorStr = JSON.stringify(vector);
-    const hasCategoryFilter = Array.isArray(categories) && categories.length > 0;
-    const placeholders = hasCategoryFilter ? categories!.map(() => "?").join(", ") : "";
-    const whereClause = hasCategoryFilter
-      ? `WHERE  agent_id = ? AND (is_deleted = 0 OR is_deleted IS NULL) AND category IN (${placeholders})`
-      : `WHERE  agent_id = ? AND (is_deleted = 0 OR is_deleted IS NULL)`;
-    const args: unknown[] = hasCategoryFilter
-      ? [vectorStr, agentId, ...categories!, limit]
-      : [vectorStr, agentId, limit];
+    return this.withConnection(async (conn) => {
+      const vectorStr = JSON.stringify(vector);
+      const hasCategoryFilter = Array.isArray(categories) && categories.length > 0;
+      const placeholders = hasCategoryFilter ? categories!.map(() => "?").join(", ") : "";
+      const whereClause = hasCategoryFilter
+        ? `WHERE  agent_id = ? AND (is_deleted = 0 OR is_deleted IS NULL) AND category IN (${placeholders})`
+        : `WHERE  agent_id = ? AND (is_deleted = 0 OR is_deleted IS NULL)`;
+      const args: unknown[] = hasCategoryFilter
+        ? [vectorStr, agentId, ...categories!, limit]
+        : [vectorStr, agentId, limit];
 
-    const [rows] = await this.pool!.query(
-      `SELECT id, text, importance, category, created_at, is_deleted,
-              VEC_DISTANCE_COSINE(embedding, VEC_FROMTEXT(?)) AS distance
-       FROM   \`${this.tableName}\`
-       ${whereClause}
-       ORDER  BY distance ASC
-       LIMIT  ?`,
-      args,
-    );
+      const [rows] = await conn.query(
+        `SELECT id, text, importance, category, created_at, is_deleted,
+                VEC_DISTANCE_COSINE(embedding, VEC_FROMTEXT(?)) AS distance
+         FROM   \`${this.tableName}\`
+         ${whereClause}
+         ORDER  BY distance ASC
+         LIMIT  ?`,
+        args,
+      );
 
-    const results: MemorySearchResult[] = [];
-    for (const row of rows as Array<Record<string, unknown>>) {
-      const distance = Number(row.distance) || 0;
-      const score = 1 - distance;
-      if (score < minScore) {
-        continue;
+      const results: MemorySearchResult[] = [];
+      for (const row of rows as Array<Record<string, unknown>>) {
+        const distance = Number(row.distance) || 0;
+        const score = 1 - distance;
+        if (score < minScore) {
+          continue;
+        }
+        const isDeleted = row.is_deleted;
+        results.push({
+          entry: {
+            id: row.id as string,
+            agentId,
+            text: row.text as string,
+            importance: Number(row.importance) || 0,
+            category: (row.category as MemoryCategory) || USER_MEMORY_FACT,
+            createdAt: Number(row.created_at) || 0,
+            isDeleted: isDeleted !== undefined && isDeleted !== null ? Number(isDeleted) : undefined,
+          },
+          score,
+        });
       }
-      const isDeleted = row.is_deleted;
-      results.push({
-        entry: {
-          id: row.id as string,
-          agentId,
-          text: row.text as string,
-          importance: Number(row.importance) || 0,
-          category: (row.category as MemoryCategory) || USER_MEMORY_FACT,
-          createdAt: Number(row.created_at) || 0,
-          isDeleted: isDeleted !== undefined && isDeleted !== null ? Number(isDeleted) : undefined,
-        },
-        score,
-      });
-    }
-
-    return results;
+      return results;
+    });
   }
 
   /** Soft-delete: set is_deleted = 1. Returns true if a row was updated. */
@@ -327,32 +304,29 @@ export class MemoryDB {
     if (!UUID_RE.test(id)) {
       throw new Error(`Invalid memory ID format: ${id}`);
     }
-    await this.ensureInitialized();
-    const [result] = await this.pool!.query(
-      `UPDATE \`${this.tableName}\` SET is_deleted = 1 WHERE id = ? AND agent_id = ?`,
-      [id, agentId],
-    );
-    return ((result as mysql.ResultSetHeader).affectedRows ?? 0) > 0;
+    return this.withConnection(async (conn) => {
+      const [result] = await conn.query(
+        `UPDATE \`${this.tableName}\` SET is_deleted = 1 WHERE id = ? AND agent_id = ?`,
+        [id, agentId],
+      );
+      return ((result as mysql.ResultSetHeader).affectedRows ?? 0) > 0;
+    });
   }
 
   async delete(agentId: string, id: string): Promise<boolean> {
     if (!UUID_RE.test(id)) {
       throw new Error(`Invalid memory ID format: ${id}`);
     }
-    await this.ensureInitialized();
-
-    const [result] = await this.pool!.query(
-      `DELETE FROM \`${this.tableName}\` WHERE id = ? AND agent_id = ?`,
-      [id, agentId],
-    );
-    return ((result as mysql.ResultSetHeader).affectedRows ?? 0) > 0;
+    return this.withConnection(async (conn) => {
+      const [result] = await conn.query(
+        `DELETE FROM \`${this.tableName}\` WHERE id = ? AND agent_id = ?`,
+        [id, agentId],
+      );
+      return ((result as mysql.ResultSetHeader).affectedRows ?? 0) > 0;
+    });
   }
 
   async close(): Promise<void> {
-    if (this.pool) {
-      this.pool.end();
-      this.pool = null;
-      this.initPromise = null;
-    }
+    this.vectorIndexCreated = false;
   }
 }

package/index.ts

@@ -745,15 +745,24 @@ const memoryPlugin = {
 
   register(api: OpenClawPluginApi) {
     const cfg = memoryConfigSchema.parse(api.pluginConfig);
-    const { model, dimensions, apiKey, baseUrl } = cfg.embedding;
-
-    const vectorDim = vectorDimsForModel(model, dimensions);
-    const db = new MemoryDB(cfg.mysql, cfg.tableName, vectorDim);
-    const embeddings = new Embeddings(apiKey, model, baseUrl, vectorDim);
+    let db: MemoryDB | null = null;
+    let embeddings: Embeddings | null = null;
+    if (cfg.mysql && cfg.embedding) {
+      const { model, dimensions, apiKey, baseUrl } = cfg.embedding;
+      const vectorDim = vectorDimsForModel(model, dimensions);
+      db = new MemoryDB(cfg.mysql, cfg.tableName, vectorDim);
+      embeddings = new Embeddings(apiKey, model, baseUrl, vectorDim);
+      api.logger.info(
+        `openclaw-memory-alibaba-mysql: registered (host: ${cfg.mysql.host}, table: ${cfg.tableName})`,
+      );
+    } else {
+      api.logger.info(
+        "openclaw-memory-alibaba-mysql: registered without mysql/embedding config (memory ops no-op until configured)",
+      );
+    }
 
-    api.logger.info(
-      `openclaw-memory-alibaba-mysql: registered (host: ${cfg.mysql.host}, table: ${cfg.tableName})`,
-    );
+    const getDbAndEmbeddings = (): { db: MemoryDB; embeddings: Embeddings } | null =>
+      db && embeddings ? { db, embeddings } : null;
 
     // --- Tools: memory_recall, memory_store, memory_forget ---
 
@@ -768,6 +777,14 @@ const memoryPlugin = {
           limit: Type.Optional(Type.Number({ description: "Max results (default: 5)" })),
         }),
         async execute(_toolCallId, params) {
+          const out = getDbAndEmbeddings();
+          if (!out) {
+            return {
+              content: [{ type: "text", text: "Memory plugin: configure mysql and embedding in plugin config to use memory." }],
+              details: { error: "not_configured" },
+            };
+          }
+          const { db, embeddings } = out;
           const { query, limit = RECALL_LIMIT_USER_DEFAULT } = params as { query: string; limit?: number };
           const agentId = ctx.agentId ?? "default";
           const vector = await embeddings.embed(query);
@@ -844,6 +861,14 @@ const memoryPlugin = {
           ),
         }),
         async execute(_toolCallId, params) {
+          const out = getDbAndEmbeddings();
+          if (!out) {
+            return {
+              content: [{ type: "text", text: "Memory plugin: configure mysql and embedding in plugin config to use memory." }],
+              details: { error: "not_configured" },
+            };
+          }
+          const { db, embeddings } = out;
           const {
             text,
             importance = DEFAULT_IMPORTANCE,
@@ -893,6 +918,14 @@ const memoryPlugin = {
           memoryId: Type.Optional(Type.String({ description: "Specific memory ID" })),
         }),
         async execute(_toolCallId, params) {
+          const out = getDbAndEmbeddings();
+          if (!out) {
+            return {
+              content: [{ type: "text", text: "Memory plugin: configure mysql and embedding in plugin config to use memory." }],
+              details: { error: "not_configured" },
+            };
+          }
+          const { db, embeddings } = out;
           const { query, memoryId } = params as { query?: string; memoryId?: string };
           const agentId = ctx.agentId ?? "default";
 
@@ -961,6 +994,7 @@ const memoryPlugin = {
 
     if (cfg.autoRecall) {
       api.on("before_agent_start", async (event, ctx) => {
+        if (!db || !embeddings) return;
         if (!event.prompt || event.prompt.length < 5) return;
 
         try {
@@ -993,6 +1027,7 @@ const memoryPlugin = {
 
     if (cfg.autoCapture) {
       api.on("agent_end", async (event, ctx) => {
+        if (!db || !embeddings) return;
         if (!event.success || !event.messages || event.messages.length === 0) return;
 
         try {
@@ -1042,7 +1077,7 @@ const memoryPlugin = {
         );
       },
       stop: async () => {
-        await db.close();
+        if (db) await db.close();
         api.logger.info("openclaw-memory-alibaba-mysql: stopped");
       },
     });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "openclaw-memory-alibaba-mysql",
-  "version": "0.2.4",
+  "version": "0.2.5",
   "description": "OpenClaw memory plugin using Alibaba Cloud RDS MySQL vector storage",
   "type": "module",
   "license": "MIT",