openclaw-memory-alibaba-mysql_beta 0.1.5

package/README.md

@@ -0,0 +1,68 @@
+# OpenClaw Memory (Alibaba Cloud RDS MySQL)
+
+OpenClaw 记忆插件，使用阿里云 RDS MySQL 向量存储。用户记忆细分为三类写入与召回。
+
+## 记忆分类 (category)
+
+| 类型 | category | 说明 |
+|------|----------|------|
+| 用户事实 | `user_memory_fact` | 用户陈述的事实、习惯、身份信息等 |
+| 用户偏好 | `user_memory_preference` | 喜欢/不喜欢、偏好、意愿 |
+| 用户决策 | `user_memory_decision` | 已做的决定、打算、计划 |
+
+- **自动抓取 (autoCapture)**：从用户消息中按关键词推断类别并写入上述三者之一。
+- **memory_store 工具**：可显式指定 `category` 为 `user_memory_fact` / `user_memory_preference` / `user_memory_decision`，默认 `user_memory_fact`。
+- **召回**：`before_agent_start` 与 `memory_recall` 不区分子类型，统一按向量检索并注入上下文。
+
+## 配置示例
+
+```json
+{
+  "plugins": {
+    "slots": { "memory": "openclaw-memory-alibaba-mysql_beta" },
+    "entries": {
+      "openclaw-memory-alibaba-mysql_beta": {
+        "enabled": true,
+        "config": {
+          "mysql": {
+            "host": "your-rds.aliyuncs.com",
+            "port": 3306,
+            "user": "openclaw",
+            "password": "${MYSQL_PASSWORD}",
+            "database": "openclaw",
+            "ssl": true
+          },
+          "embedding": {
+            "apiKey": "${DASHSCOPE_API_KEY}",
+            "model": "text-embedding-v3",
+            "baseUrl": "https://dashscope.aliyuncs.com/compatible-mode/v1"
+          },
+          "autoRecall": true,
+          "autoCapture": false,
+          "captureMaxChars": 500,
+          "tableName": "openclaw_memories"
+        }
+      }
+    }
+  }
+}
+```
+
+## 环境变量
+
+- `MYSQL_HOST`, `MYSQL_USER`, `MYSQL_PASSWORD`：MySQL 连接（或写在 config 中，password 支持 `${VAR}`）。
+- `DASHSCOPE_API_KEY`：DashScope 用于 embedding（若 apiKey 用 `${DASHSCOPE_API_KEY}`）。
+
+## 测试
+
+```bash
+export MYSQL_HOST=your-host MYSQL_PASSWORD=xxx DASHSCOPE_API_KEY=xxx
+npx tsx test-agent-isolation.ts
+```
+
+## 文件说明
+
+- `categories.ts`：常量 `user_memory_fact` / `user_memory_preference` / `user_memory_decision` 及类型。
+- `config.ts`：MySQL、embedding、autoRecall、autoCapture、tableName 解析。
+- `db.ts`：MemoryDB 建表、store、search、delete（向量 COSINE）。
+- `index.ts`：插件注册、memory_recall / memory_store / memory_forget、before_agent_start / agent_end 钩子。

package/categories.ts

@@ -0,0 +1,57 @@
+/**
+ * Memory category constants.
+ * user_memory is subdivided into fact / preference / decision for storage and recall.
+ */
+
+/** User memory sub-categories (user-side facts, preferences, decisions) */
+export const USER_MEMORY_FACT = "user_memory_fact" as const;
+export const USER_MEMORY_PREFERENCE = "user_memory_preference" as const;
+export const USER_MEMORY_DECISION = "user_memory_decision" as const;
+
+/** All user memory category values (for recall: treat as one logical "user_memory" set) */
+export const USER_MEMORY_CATEGORIES = [
+  USER_MEMORY_FACT,
+  USER_MEMORY_PREFERENCE,
+  USER_MEMORY_DECISION,
+] as const;
+
+export type UserMemoryCategory =
+  | typeof USER_MEMORY_FACT
+  | typeof USER_MEMORY_PREFERENCE
+  | typeof USER_MEMORY_DECISION;
+
+/** Full context (conversation audit / per-message) */
+export const FULL_CONTEXT_MEMORY = "full_context_memory" as const;
+
+/** Self-improving memory sub-categories */
+export const SELF_IMPROVING_LEARNINGS = "self_improving_learnings" as const;
+export const SELF_IMPROVING_ERRORS = "self_improving_errors" as const;
+export const SELF_IMPROVING_FEATURE_REQUESTS = "self_improving_feature_requests" as const;
+
+export const SELF_IMPROVING_CATEGORIES = [
+  SELF_IMPROVING_LEARNINGS,
+  SELF_IMPROVING_ERRORS,
+  SELF_IMPROVING_FEATURE_REQUESTS,
+] as const;
+
+export type SelfImprovingCategory = (typeof SELF_IMPROVING_CATEGORIES)[number];
+
+/** All allowed category values */
+export type MemoryCategory =
+  | UserMemoryCategory
+  | typeof FULL_CONTEXT_MEMORY
+  | SelfImprovingCategory;
+
+export const ALL_CATEGORIES: readonly MemoryCategory[] = [
+  ...USER_MEMORY_CATEGORIES,
+  FULL_CONTEXT_MEMORY,
+  ...SELF_IMPROVING_CATEGORIES,
+];
+
+export function isUserMemoryCategory(cat: string): cat is UserMemoryCategory {
+  return USER_MEMORY_CATEGORIES.includes(cat as UserMemoryCategory);
+}
+
+export function isSelfImprovingCategory(cat: string): cat is SelfImprovingCategory {
+  return SELF_IMPROVING_CATEGORIES.includes(cat as SelfImprovingCategory);
+}

package/config.ts

@@ -0,0 +1,290 @@
+import type { MemoryCategory } from "./categories.js";
+import { ALL_CATEGORIES, USER_MEMORY_FACT } from "./categories.js";
+
+export type MysqlConnectionConfig = {
+  host: string;
+  port: number;
+  user: string;
+  password: string;
+  database: string;
+  ssl: boolean;
+};
+
+export type EmbeddingConfig = {
+  apiKey: string;
+  model: string;
+  baseUrl?: string;
+  dimensions?: number;
+};
+
+export type LLMConfig = {
+  apiKey: string;
+  model: string;
+  baseUrl?: string;
+};
+
+export type MemoryConfig = {
+  mysql: MysqlConnectionConfig;
+  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. */
+  llm?: LLMConfig;
+  /** Similarity threshold for user_memory_* (0–1). Default 0.95. */
+  similarityThresholdUserMemory: number;
+  /** Similarity threshold for self_improving_* (0–1). Default 0.92. */
+  similarityThresholdSelfImproving: number;
+  /** When false, full_context_memory is not written or recalled. Default false. */
+  enableFullContextMemory: boolean;
+  /** When false, self_improving_* is not written or recalled. Default false. */
+  enableSelfImprovingMemory: boolean;
+  /** How to extract user and self_improving memories in auto-capture: "regex" (default) or "llm". Case-insensitive; invalid values fall back to "regex". When "llm", llm config is required. */
+  memoryExtractionMethod: "regex" | "llm";
+  autoRecall: boolean;
+  autoCapture: boolean;
+  captureMaxChars: number;
+  /** When true, apply time decay to recall scores (older = lower effective score). Default false. */
+  enableMemoryDecay: boolean;
+  /** Half-life in days for exponential decay. Used when enableMemoryDecay and strategy is exponential. Default 30. */
+  memoryDecayHalfLifeDays: number;
+  /** Decay curve: "exponential" (0.5^(age/halfLife)), "linear" (1 - age/(2*halfLife)), "none". Default "exponential". */
+  memoryDecayStrategy: "exponential" | "linear" | "none";
+  tableName: string;
+};
+
+/** Re-export for tools and DB (user_memory_* + full_context + self_improving_*) */
+export { ALL_CATEGORIES, USER_MEMORY_FACT };
+export type { MemoryCategory };
+
+const DEFAULT_MODEL = "text-embedding-v3";
+const DEFAULT_BASE_URL = "https://dashscope.aliyuncs.com/compatible-mode/v1";
+const DEFAULT_TABLE_NAME = "openclaw_memories";
+export const DEFAULT_CAPTURE_MAX_CHARS = 500;
+
+const EMBEDDING_DIMENSIONS: Record<string, number> = {
+  "text-embedding-v3": 1024,
+  "text-embedding-v2": 1536,
+  "text-embedding-3-small": 1536,
+  "text-embedding-3-large": 3072,
+  "text-embedding-ada-002": 1536,
+  "embed-english-v3.0": 1024,
+  "embed-multilingual-v3.0": 1024,
+  "embed-english-light-v3.0": 384,
+  "embed-multilingual-light-v3.0": 384,
+  "jina-embeddings-v3": 1024,
+  "jina-embeddings-v2-base-en": 768,
+  "jina-embeddings-v2-base-zh": 768,
+  "bge-large-zh-v1.5": 1024,
+  "bge-large-en-v1.5": 1024,
+  "bge-m3": 1024,
+  "nomic-embed-text": 768,
+  "text-embedding-004": 768,
+};
+
+const FLEX_DIMS_MODELS = new Set([
+  "text-embedding-v3",
+  "text-embedding-3-small",
+  "text-embedding-3-large",
+  "jina-embeddings-v3",
+]);
+
+export function vectorDimsForModel(model: string, explicit?: number): number {
+  if (explicit && explicit > 0) return explicit;
+  return EMBEDDING_DIMENSIONS[model] ?? 1024;
+}
+
+export function modelSupportsFlexDimensions(model: string): boolean {
+  return FLEX_DIMS_MODELS.has(model);
+}
+
+function resolveEnvVars(value: string): string {
+  return value.replace(/\$\{([^}]+)\}/g, (_, envVar) => {
+    const envValue = process.env[envVar];
+    if (!envValue) {
+      throw new Error(`Environment variable ${envVar} is not set`);
+    }
+    return envValue;
+  });
+}
+
+function assertAllowedKeys(value: Record<string, unknown>, allowed: string[], label: string) {
+  const unknown = Object.keys(value).filter((key) => !allowed.includes(key));
+  if (unknown.length > 0) {
+    throw new Error(`${label} has unknown keys: ${unknown.join(", ")}`);
+  }
+}
+
+function requireString(obj: Record<string, unknown>, key: string, label: string): string {
+  const v = obj[key];
+  if (typeof v !== "string" || v.length === 0) {
+    throw new Error(`${label}.${key} is required and must be a non-empty string`);
+  }
+  return v;
+}
+
+function parseMysqlConfig(raw: unknown): MysqlConnectionConfig {
+  if (!raw || typeof raw !== "object" || Array.isArray(raw)) {
+    throw new Error("mysql config is required");
+  }
+  const m = raw as Record<string, unknown>;
+  assertAllowedKeys(m, ["host", "port", "user", "password", "database", "ssl"], "mysql");
+
+  return {
+    host: requireString(m, "host", "mysql"),
+    port: typeof m.port === "number" ? m.port : 3306,
+    user: requireString(m, "user", "mysql"),
+    password: resolveEnvVars(requireString(m, "password", "mysql")),
+    database: requireString(m, "database", "mysql"),
+    ssl: m.ssl === true,
+  };
+}
+
+function parseEmbeddingConfig(raw: unknown): EmbeddingConfig {
+  if (!raw || typeof raw !== "object" || Array.isArray(raw)) {
+    throw new Error("embedding config is required");
+  }
+  const e = raw as Record<string, unknown>;
+  assertAllowedKeys(e, ["apiKey", "model", "baseUrl", "dimensions"], "embedding");
+
+  const model = typeof e.model === "string" ? e.model : DEFAULT_MODEL;
+  const explicitDims = typeof e.dimensions === "number" ? e.dimensions : undefined;
+
+  return {
+    apiKey: resolveEnvVars(requireString(e, "apiKey", "embedding")),
+    model,
+    baseUrl: typeof e.baseUrl === "string" ? resolveEnvVars(e.baseUrl) : DEFAULT_BASE_URL,
+    dimensions: explicitDims,
+  };
+}
+
+const DEFAULT_LLM_BASE_URL = "https://dashscope.aliyuncs.com/compatible-mode/v1";
+
+function parseLLMConfig(raw: unknown): LLMConfig {
+  if (!raw || typeof raw !== "object" || Array.isArray(raw)) {
+    throw new Error("llm config is required when memory_duplication_conflict_process is true");
+  }
+  const l = raw as Record<string, unknown>;
+  assertAllowedKeys(l, ["apiKey", "model", "baseUrl"], "llm");
+  return {
+    apiKey: resolveEnvVars(requireString(l, "apiKey", "llm")),
+    model: requireString(l, "model", "llm"),
+    baseUrl: typeof l.baseUrl === "string" ? resolveEnvVars(l.baseUrl) : DEFAULT_LLM_BASE_URL,
+  };
+}
+
+export const memoryConfigSchema = {
+  parse(value: unknown): MemoryConfig {
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+      throw new Error("memory-alibaba-mysql: plugin config is required");
+    }
+    const cfg = value as Record<string, unknown>;
+
+    // --- Allowed keys ---
+    assertAllowedKeys(
+      cfg,
+      [
+        "mysql",
+        "embedding",
+        "memory_duplication_conflict_process",
+        "llm",
+        "similarityThresholdUserMemory",
+        "similarityThresholdSelfImproving",
+        "enableFullContextMemory",
+        "enableSelfImprovingMemory",
+        "memoryExtractionMethod",
+        "autoRecall",
+        "autoCapture",
+        "captureMaxChars",
+        "enableMemoryDecay",
+        "memoryDecayHalfLifeDays",
+        "memoryDecayStrategy",
+        "tableName",
+      ],
+      "memory config",
+    );
+
+    // --- LLM requirement ---
+    const memory_duplication_conflict_process = cfg.memory_duplication_conflict_process === true;
+    const rawMethod =
+      typeof cfg.memoryExtractionMethod === "string"
+        ? cfg.memoryExtractionMethod.trim().toLowerCase()
+        : "";
+    const memoryExtractionMethod: "regex" | "llm" =
+      rawMethod === "llm" ? "llm" : "regex";
+    const needsLlm = memory_duplication_conflict_process || memoryExtractionMethod === "llm";
+    if (needsLlm && (!cfg.llm || typeof cfg.llm !== "object")) {
+      throw new Error(
+        "llm config is required when memory_duplication_conflict_process is true or memoryExtractionMethod is \"llm\"",
+      );
+    }
+
+    // --- Thresholds and feature flags ---
+    const similarityThresholdUserMemory =
+      typeof cfg.similarityThresholdUserMemory === "number"
+        ? cfg.similarityThresholdUserMemory
+        : 0.95;
+    const similarityThresholdSelfImproving =
+      typeof cfg.similarityThresholdSelfImproving === "number"
+        ? cfg.similarityThresholdSelfImproving
+        : 0.92;
+    if (
+      similarityThresholdUserMemory < 0 ||
+      similarityThresholdUserMemory > 1 ||
+      similarityThresholdSelfImproving < 0 ||
+      similarityThresholdSelfImproving > 1
+    ) {
+      throw new Error("similarityThresholdUserMemory and similarityThresholdSelfImproving must be between 0 and 1");
+    }
+
+    const enableFullContextMemory = cfg.enableFullContextMemory === true;
+    const enableSelfImprovingMemory = cfg.enableSelfImprovingMemory === true;
+
+    const captureMaxChars =
+      typeof cfg.captureMaxChars === "number" ? Math.floor(cfg.captureMaxChars) : undefined;
+    if (typeof captureMaxChars === "number" && (captureMaxChars < 100 || captureMaxChars > 10_000)) {
+      throw new Error("captureMaxChars must be between 100 and 10000");
+    }
+
+    // --- Memory decay ---
+    const enableMemoryDecay = cfg.enableMemoryDecay === true;
+    const memoryDecayHalfLifeDays =
+      typeof cfg.memoryDecayHalfLifeDays === "number" && cfg.memoryDecayHalfLifeDays > 0
+        ? cfg.memoryDecayHalfLifeDays
+        : 30;
+    const rawDecayStrategy =
+      typeof cfg.memoryDecayStrategy === "string" ? cfg.memoryDecayStrategy.trim().toLowerCase() : "";
+    const memoryDecayStrategy: "exponential" | "linear" | "none" =
+      rawDecayStrategy === "linear"
+        ? "linear"
+        : rawDecayStrategy === "none"
+          ? "none"
+          : "exponential";
+
+    // --- Table name and final object ---
+    const tableName = typeof cfg.tableName === "string" ? cfg.tableName : DEFAULT_TABLE_NAME;
+    if (!/^[a-zA-Z_][a-zA-Z0-9_]*$/.test(tableName)) {
+      throw new Error(
+        `Invalid tableName "${tableName}": must contain only alphanumeric characters and underscores`,
+      );
+    }
+
+    return {
+      mysql: parseMysqlConfig(cfg.mysql),
+      embedding: parseEmbeddingConfig(cfg.embedding),
+      memory_duplication_conflict_process,
+      llm: needsLlm ? parseLLMConfig(cfg.llm) : undefined,
+      similarityThresholdUserMemory,
+      similarityThresholdSelfImproving,
+      enableFullContextMemory,
+      enableSelfImprovingMemory,
+      memoryExtractionMethod,
+      autoRecall: cfg.autoRecall !== false,
+      autoCapture: cfg.autoCapture !== false,
+      captureMaxChars: captureMaxChars ?? DEFAULT_CAPTURE_MAX_CHARS,
+      enableMemoryDecay,
+      memoryDecayHalfLifeDays,
+      memoryDecayStrategy,
+      tableName,
+    };
+  },
+};

package/db.ts

@@ -0,0 +1,248 @@
+import { randomUUID } from "node:crypto";
+import mysql from "mysql2/promise";
+import type { Pool } from "mysql2/promise";
+import type { MemoryCategory } from "./config.js";
+import { USER_MEMORY_FACT } from "./categories.js";
+import type { MysqlConnectionConfig } from "./config.js";
+
+export type MemoryEntry = {
+  id: string;
+  agentId: string;
+  text: string;
+  importance: number;
+  category: MemoryCategory;
+  createdAt: number;
+  /** 0 = active, 1 = soft-deleted. Omitted when reading from old rows without column. */
+  isDeleted?: number;
+};
+
+export type MemorySearchResult = {
+  entry: MemoryEntry;
+  score: number;
+};
+
+const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+
+export class MemoryDB {
+  private pool: Pool | null = null;
+  private initPromise: Promise<void> | null = null;
+  private vectorIndexCreated = false;
+
+  constructor(
+    private readonly mysqlConfig: MysqlConnectionConfig,
+    private readonly tableName: string,
+    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({
+      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,
+          text       TEXT          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)
+        ) ENGINE=InnoDB
+      `);
+      await this.ensureIsDeletedColumn(conn);
+      await this.tryCreateVectorIndex(conn);
+    } finally {
+      conn.release();
+    }
+  }
+
+  private async ensureIsDeletedColumn(conn: mysql.PoolConnection): 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'`,
+      [this.tableName],
+    );
+    if ((rows as Array<unknown>).length > 0) return;
+    await conn.query(
+      `ALTER TABLE \`${this.tableName}\` ADD COLUMN is_deleted TINYINT NOT NULL DEFAULT 0`,
+    );
+  }
+
+  private async tryCreateVectorIndex(conn: mysql.PoolConnection): Promise<void> {
+    if (this.vectorIndexCreated) {
+      return;
+    }
+    try {
+      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_embedding'`,
+        [this.tableName],
+      );
+      const cnt = (rows as Array<{ cnt: number }>)[0]?.cnt ?? 0;
+      if (cnt > 0) {
+        this.vectorIndexCreated = true;
+        return;
+      }
+      await conn.query(
+        `ALTER TABLE \`${this.tableName}\` ADD VECTOR INDEX idx_embedding (embedding) DISTANCE=COSINE`,
+      );
+      this.vectorIndexCreated = true;
+    } catch {
+      // HNSW index creation may fail on empty tables; will retry after first insert.
+    }
+  }
+
+  async store(
+    agentId: string,
+    entry: { text: string; vector: number[]; importance: number; category: MemoryCategory },
+  ): Promise<MemoryEntry> {
+    await this.ensureInitialized();
+
+    const id = randomUUID();
+    const createdAt = Date.now();
+    const vectorStr = JSON.stringify(entry.vector);
+
+    await this.pool!.query(
+      `INSERT INTO \`${this.tableName}\` (id, agent_id, text, embedding, importance, category, created_at, is_deleted)
+       VALUES (?, ?, ?, VEC_FROMTEXT(?), ?, ?, ?, 0)`,
+      [id, agentId, entry.text, vectorStr, entry.importance, entry.category, createdAt],
+    );
+
+    if (!this.vectorIndexCreated) {
+      const conn = await this.pool!.getConnection();
+      try {
+        await this.tryCreateVectorIndex(conn);
+      } finally {
+        conn.release();
+      }
+    }
+
+    return {
+      id,
+      agentId,
+      text: entry.text,
+      importance: entry.importance,
+      category: entry.category,
+      createdAt,
+    };
+  }
+
+  /**
+   * Search memories by vector similarity.
+   * @param categories - When non-empty, only return rows with category IN (categories). Omit for no category filter.
+   */
+  async search(
+    agentId: string,
+    vector: number[],
+    limit = 5,
+    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];
+
+    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 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,
+      });
+    }
+
+    return results;
+  }
+
+  /** Soft-delete: set is_deleted = 1. Returns true if a row was updated. */
+  async softDelete(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(
+      `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;
+  }
+
+  async close(): Promise<void> {
+    if (this.pool) {
+      this.pool.end();
+      this.pool = null;
+      this.initPromise = null;
+    }
+  }
+}