openclaw-memory-alibaba-mysql 0.2.0 → 0.2.2

package/README.md

@@ -1,33 +1,36 @@
-# openclaw_memory_alibaba_mysql
+# openclaw-memory-alibaba-mysql
 
-OpenClaw 记忆插件，使用阿里云 RDS MySQL 向量存储。用户记忆细分为 fact / preference / decision 三类；支持全文记忆与自我改进记忆，抽取方式可选 regex 或 llm。
+OpenClaw 记忆插件，使用阿里云 RDS MySQL 做向量存储。支持用户记忆、全文对话记录、自进化记忆；可与 OpenClaw 的 before_agent_start / agent_end 配合，自动召回与自动落库。
 
-## 记忆分类 (category)
+## 功能概览
 
-| 类型 | category | 说明 |
-|------|----------|------|
-| 用户事实 | `user_memory_fact` | 用户陈述的事实、习惯、身份信息等 |
-| 用户偏好 | `user_memory_preference` | 喜欢/不喜欢、偏好、意愿 |
-| 用户决策 | `user_memory_decision` | 已做的决定、打算、计划 |
+- **用户记忆**：从对话中自动抽取事实、偏好、决策（如「喜欢寿司」「打算用 Python」），支持按向量检索并注入到每轮上下文。
+- **全文记忆**：按消息来源分为用户、助手、系统、工具等 6 类，每类按会话保留一份，每轮更新；只存真实对话内容，不存系统注入的上下文块。
+- **自进化记忆**：从对话中抽取学习要点、错误、需求等，可选参与召回。
+- **冲突与去重**：可选用 LLM 判断新记忆与已有记忆是否矛盾或重复，避免重复、矛盾条目堆积。
+- **时间衰减**：召回时可对旧记忆降权，让近期信息更突出。
+- **工具**：提供 `memory_recall`（按查询搜记忆）、`memory_store`（显式写入）、`memory_forget`（删除）；若只依赖自动召回与自动抓取，可不给 agent 开放 recall/store，仅保留 forget 用于删除。
 
-- **自动抓取 (autoCapture)**：按 `memoryExtractionMethod` 用 regex 或 LLM 从用户/对话中抽取并写入。
-- **memory_store 工具**：可显式指定 `category`，默认 `user_memory_fact`。
-- **召回**：`before_agent_start` 与 `memory_recall` 统一按向量检索用户记忆（及可选 self_improving），注入上下文。
+## 记忆分类
 
----
+| 类型 | 说明 |
+|------|------|
+| 用户事实 / 偏好 / 决策 | 从用户话里抽取的事实、喜好、决定，用于后续对话的上下文 |
+| 全文·用户 / 助手 / 系统 / 工具 / 工具结果 / 其它 | 按消息角色分的完整对话记录，按会话维护、每轮更新 |
+| 自进化（学习 / 错误 / 需求） | 从对话中抽取的可复用经验，可选参与召回 |
 
 ## 配置示例
 
-### 最简配置（只接库 + 向量）
+### 最简配置
 
-只配必填的 MySQL 和 Embedding，其它用默认：自动召回开、自动抓取关、不启用全文/自我改进/记忆衰减。
+只接 MySQL 和向量服务，其余用默认（自动召回 + 自动抓取用户记忆，不开启全文与自进化）：
 
 ```json
 {
   "plugins": {
-    "slots": { "memory": "openclaw_memory_alibaba_mysql" },
+    "slots": { "memory": "openclaw-memory-alibaba-mysql" },
     "entries": {
-      "openclaw_memory_alibaba_mysql": {
+      "openclaw-memory-alibaba-mysql": {
         "enabled": true,
         "config": {
           "mysql": {
@@ -50,16 +53,16 @@ OpenClaw 记忆插件，使用阿里云 RDS MySQL 向量存储。用户记忆细
 }
 ```
 
-### 最全配置（功能全开）
+### 功能全开
 
-显式写出 MySQL、Embedding、LLM、自动抓取/召回、全文记忆、自我改进、记忆衰减、相似度阈值、表名等，便于按需裁剪。
+开启全文记忆、自进化、LLM 抽取与冲突处理、时间衰减等：
 
 ```json
 {
   "plugins": {
-    "slots": { "memory": "openclaw_memory_alibaba_mysql" },
+    "slots": { "memory": "openclaw-memory-alibaba-mysql" },
     "entries": {
-      "openclaw_memory_alibaba_mysql": {
+      "openclaw-memory-alibaba-mysql": {
         "enabled": true,
         "config": {
           "mysql": {
@@ -89,7 +92,7 @@ OpenClaw 记忆插件，使用阿里云 RDS MySQL 向量存储。用户记忆细
           "memoryExtractionMethod": "llm",
           "autoRecall": true,
           "autoCapture": true,
-          "captureMaxChars": 500,
+          "captureMaxChars": 5000,
           "enableMemoryDecay": true,
           "tableName": "openclaw_memories"
         }
@@ -99,38 +102,21 @@ OpenClaw 记忆插件，使用阿里云 RDS MySQL 向量存储。用户记忆细
 }
 ```
 
-**配置要点**
+**常用配置说明**
 
-- **必填**：`mysql`（host / user / password / database 等）、`embedding`（apiKey、model）。
-- **memoryExtractionMethod**：`"regex"` 或 `"llm"`，对 user_memory_* 与 self_improving_* 同时生效；选 `"llm"` 需配 `llm`。
-- **enableFullContextMemory** / **enableSelfImprovingMemory**：开启后可写全文记忆、自我改进记忆；全文记忆不参与常规召回。
-- **memory_duplication_conflict_process**：为 true 时用 LLM 做写入前去重/冲突判断，需配 `llm`。
-- **enableMemoryDecay**：为 true 时对召回结果做时间衰减（半衰期与策略使用内置默认：30 天、指数衰减）。
-
----
+- **mysql** / **embedding**：必填，用于连接数据库与生成向量。
+- **llm**：使用「LLM 抽取」或「冲突/去重」时必填。
+- **memoryExtractionMethod**：`"llm"`（默认）或 `"regex"`，控制如何从对话里抽取用户记忆与自改进记忆。
+- **enableFullContextMemory**：是否按角色保存全文对话（每会话每类一份，每轮更新）。
+- **enableSelfImprovingMemory**：是否启用自进化记忆的写入与召回。
+- **memory_duplication_conflict_process**：是否用 LLM 做写入前的去重与矛盾判断。
+- **captureMaxChars**：单条记忆与全文截断的最大字符数，建议 5000 以保留完整当轮对话。
+- **enableMemoryDecay**：召回时是否对旧记忆做时间衰减（近期记忆权重更高）。
+- **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
-npx tsx test-three-memory-types.ts
-npx tsx test-full-context-memory.ts
-```
-
----
-
-## 文件说明
+配置中可使用占位符引用环境变量，例如 `${MYSQL_PASSWORD}`、`${DASHSCOPE_API_KEY}`。常见需要准备的有：
 
-- `categories.ts`：常量与类型（user_memory_*、self_improving_*、full_context_memory）。
-- `config.ts`：配置解析与默认值。
-- `db.ts`：MemoryDB 建表、store、search、softDelete（向量 COSINE）。
-- `index.ts`：插件注册、memory_recall / memory_store / memory_forget、before_agent_start / agent_end。
-- `prompts.ts`：用户记忆与 self_improving 的 LLM 抽取 Prompt。
+- **MYSQL_HOST**, **MYSQL_USER**, **MYSQL_PASSWORD**：MySQL 连接信息。
+- **DASHSCOPE_API_KEY**：DashScope API Key，用于 embedding（以及 LLM 若使用 DashScope）。

package/config.ts

@@ -114,43 +114,66 @@ function assertAllowedKeys(value: Record<string, unknown>, allowed: string[], la
   }
 }
 
-function requireString(obj: Record<string, unknown>, key: string, label: string): string {
+function requireString(obj: Record<string, unknown>, key: string, label: string, allowEmpty = false): string {
   const v = obj[key];
-  if (typeof v !== "string" || v.length === 0) {
+  if (typeof v !== "string") {
+    throw new Error(`${label}.${key} is required and must be a string`);
+  }
+  if (!allowEmpty && v.length === 0) {
     throw new Error(`${label}.${key} is required and must be a non-empty string`);
   }
   return v;
 }
 
 function parseMysqlConfig(raw: unknown): MysqlConnectionConfig {
+  // Allow empty mysql config - will be validated at connection time
   if (!raw || typeof raw !== "object" || Array.isArray(raw)) {
-    throw new Error("mysql config is required");
+    return {
+      host: "",
+      port: 3306,
+      user: "",
+      password: "",
+      database: "openclaw_memory",
+      ssl: false,
+    };
   }
   const m = raw as Record<string, unknown>;
   assertAllowedKeys(m, ["host", "port", "user", "password", "database", "ssl"], "mysql");
 
+  const host = typeof m.host === "string" ? m.host : "";
+  const user = typeof m.user === "string" ? m.user : "";
+  const password = typeof m.password === "string" ? resolveEnvVars(m.password) : "";
+  const database = typeof m.database === "string" ? m.database : "openclaw_memory";
+
   return {
-    host: requireString(m, "host", "mysql"),
+    host,
     port: typeof m.port === "number" ? m.port : 3306,
-    user: requireString(m, "user", "mysql"),
-    password: resolveEnvVars(requireString(m, "password", "mysql")),
-    database: requireString(m, "database", "mysql"),
+    user,
+    password,
+    database,
     ssl: m.ssl === true,
   };
 }
 
 function parseEmbeddingConfig(raw: unknown): EmbeddingConfig {
+  // Allow empty embedding config - will be validated at connection time
   if (!raw || typeof raw !== "object" || Array.isArray(raw)) {
-    throw new Error("embedding config is required");
+    return {
+      apiKey: "",
+      model: DEFAULT_MODEL,
+      baseUrl: DEFAULT_BASE_URL,
+      dimensions: undefined,
+    };
   }
   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;
+  const apiKey = typeof e.apiKey === "string" ? resolveEnvVars(e.apiKey) : "";
 
   return {
-    apiKey: resolveEnvVars(requireString(e, "apiKey", "embedding")),
+    apiKey,
     model,
     baseUrl: typeof e.baseUrl === "string" ? resolveEnvVars(e.baseUrl) : DEFAULT_BASE_URL,
     dimensions: explicitDims,

package/db.ts

@@ -51,6 +51,20 @@ export class MemoryDB {
   }
 
   private async doInitialize(): Promise<void> {
+    // Validate MySQL config before connecting
+    if (!this.mysqlConfig.host || this.mysqlConfig.host.length === 0) {
+      throw new Error("MySQL host is not configured. Please set mysql.host in the plugin config.");
+    }
+    if (!this.mysqlConfig.user || this.mysqlConfig.user.length === 0) {
+      throw new Error("MySQL user is not configured. Please set mysql.user in the plugin config.");
+    }
+    if (!this.mysqlConfig.password || this.mysqlConfig.password.length === 0) {
+      throw new Error("MySQL password is not configured. Please set mysql.password in the plugin config.");
+    }
+    if (!this.mysqlConfig.database || this.mysqlConfig.database.length === 0) {
+      throw new Error("MySQL database is not configured. Please set mysql.database in the plugin config.");
+    }
+
     this.pool = mysql.createPool({
       host: this.mysqlConfig.host,
       port: this.mysqlConfig.port,

package/index.ts

@@ -81,6 +81,10 @@ class Embeddings {
   }
 
   async embed(text: string): Promise<number[]> {
+    // Validate API key before making request
+    if (!this.client.apiKey || this.client.apiKey.length === 0) {
+      throw new Error("Embedding API key is not configured. Please set embedding.apiKey in the plugin config.");
+    }
     const params: { model: string; input: string; dimensions?: number } = {
       model: this.model,
       input: text,

package/package.json

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