@matrixorigin/thememoria 0.4.0

package/openclaw.plugin.json

@@ -0,0 +1,254 @@
+{
+  "id": "memory-memoria",
+  "name": "Memory (Memoria)",
+  "description": "Memoria-backed long-term memory plugin for OpenClaw powered by the Rust memoria CLI and API.",
+  "version": "0.3.0",
+  "kind": "memory",
+  "uiHints": {
+    "backend": {
+      "label": "Backend Mode",
+      "help": "embedded runs the Rust memoria CLI locally against MatrixOne; http connects to an existing Memoria API.",
+      "placeholder": "embedded"
+    },
+    "dbUrl": {
+      "label": "MatrixOne Connection String",
+      "help": "Embedded mode only. Rust Memoria expects a MySQL DSN; old mysql+pymysql:// values are normalized automatically.",
+      "placeholder": "mysql://root:111@127.0.0.1:6001/memoria"
+    },
+    "apiUrl": {
+      "label": "Memoria API URL",
+      "help": "Only used when backend=http.",
+      "placeholder": "http://127.0.0.1:8100"
+    },
+    "apiKey": {
+      "label": "Memoria API Token",
+      "help": "Bearer token for backend=http.",
+      "sensitive": true,
+      "placeholder": "mem-..."
+    },
+    "memoriaExecutable": {
+      "label": "Memoria Executable",
+      "help": "Path or command name for the Rust memoria CLI.",
+      "advanced": true,
+      "placeholder": "memoria"
+    },
+    "defaultUserId": {
+      "label": "Default User ID",
+      "help": "Single-user quick-start identity used unless userIdStrategy derives one from the OpenClaw runtime context.",
+      "placeholder": "openclaw-user"
+    },
+    "userIdStrategy": {
+      "label": "User ID Strategy",
+      "help": "config keeps one shared Memoria user; agentId or sessionKey derive the identity from OpenClaw runtime context.",
+      "advanced": true,
+      "placeholder": "config"
+    },
+    "autoRecall": {
+      "label": "Auto-Recall",
+      "help": "Automatically inject relevant memories into the prompt before each run."
+    },
+    "autoObserve": {
+      "label": "Auto-Observe",
+      "help": "Automatically extract memories from recent conversation turns at agent_end."
+    },
+    "retrieveTopK": {
+      "label": "Recall Top K",
+      "help": "Maximum number of memories returned for memory_search and auto-recall.",
+      "placeholder": "5"
+    },
+    "recallMinPromptLength": {
+      "label": "Recall Min Length",
+      "help": "Prompts shorter than this are skipped for auto-recall.",
+      "advanced": true,
+      "placeholder": "8"
+    },
+    "includeCrossSession": {
+      "label": "Cross-Session Recall",
+      "help": "Compatibility flag retained from the Python plugin. Rust MCP currently uses the upstream default retrieval behavior.",
+      "advanced": true
+    },
+    "retrieveMemoryTypes": {
+      "label": "Memory Types",
+      "help": "Compatibility hint retained from the Python plugin. Rust MCP currently ignores this filter.",
+      "advanced": true
+    },
+    "observeTailMessages": {
+      "label": "Observe Tail Messages",
+      "help": "Number of recent user/assistant messages forwarded to memory_observe.",
+      "advanced": true,
+      "placeholder": "6"
+    },
+    "observeMaxChars": {
+      "label": "Observe Max Chars",
+      "help": "Maximum total characters forwarded to memory_observe.",
+      "advanced": true,
+      "placeholder": "6000"
+    },
+    "timeoutMs": {
+      "label": "Request Timeout",
+      "help": "Timeout for Rust Memoria CLI requests in milliseconds.",
+      "advanced": true,
+      "placeholder": "15000"
+    },
+    "maxListPages": {
+      "label": "List Scan Limit",
+      "help": "Used by OpenClaw-side fallback scans for memory_get and derived stats.",
+      "advanced": true,
+      "placeholder": "20"
+    },
+    "embeddingProvider": {
+      "label": "Embedding Provider",
+      "help": "Embedded mode only. Prebuilt Rust release binaries are typically used with openai-compatible embedding services.",
+      "placeholder": "openai"
+    },
+    "embeddingModel": {
+      "label": "Embedding Model",
+      "help": "Embedded mode only.",
+      "placeholder": "text-embedding-3-small"
+    },
+    "embeddingBaseUrl": {
+      "label": "Embedding Base URL",
+      "help": "Embedded mode only. Optional for official OpenAI; required for compatible gateways.",
+      "advanced": true,
+      "placeholder": "https://api.openai.com/v1"
+    },
+    "embeddingApiKey": {
+      "label": "Embedding API Key",
+      "help": "Embedded mode only. Required for OpenAI-compatible providers unless you built Memoria with local-embedding.",
+      "advanced": true,
+      "sensitive": true,
+      "placeholder": "sk-..."
+    },
+    "embeddingDim": {
+      "label": "Embedding Dimensions",
+      "help": "Embedded mode only. Set this before first startup so Memoria creates the right schema.",
+      "advanced": true,
+      "placeholder": "1536"
+    },
+    "llmApiKey": {
+      "label": "Observer LLM API Key",
+      "help": "Optional. Enables auto-observe extraction and internal LLM-backed Memoria tools.",
+      "advanced": true,
+      "sensitive": true,
+      "placeholder": "sk-..."
+    },
+    "llmBaseUrl": {
+      "label": "Observer LLM Base URL",
+      "help": "Optional OpenAI-compatible base URL for embedded auto-observe and reflection flows.",
+      "advanced": true,
+      "placeholder": "https://api.openai.com/v1"
+    },
+    "llmModel": {
+      "label": "Observer LLM Model",
+      "help": "Model used by embedded auto-observe and internal reflection/entity extraction.",
+      "advanced": true,
+      "placeholder": "gpt-4o-mini"
+    }
+  },
+  "configSchema": {
+    "type": "object",
+    "additionalProperties": false,
+    "properties": {
+      "backend": {
+        "type": "string",
+        "enum": ["embedded", "http"]
+      },
+      "dbUrl": {
+        "type": "string"
+      },
+      "apiUrl": {
+        "type": "string"
+      },
+      "apiKey": {
+        "type": "string"
+      },
+      "memoriaExecutable": {
+        "type": "string"
+      },
+      "pythonExecutable": {
+        "type": "string"
+      },
+      "memoriaRoot": {
+        "type": "string"
+      },
+      "defaultUserId": {
+        "type": "string"
+      },
+      "userIdStrategy": {
+        "type": "string",
+        "enum": ["config", "agentId", "sessionKey"]
+      },
+      "timeoutMs": {
+        "type": "integer",
+        "minimum": 1000,
+        "maximum": 120000
+      },
+      "maxListPages": {
+        "type": "integer",
+        "minimum": 1,
+        "maximum": 100
+      },
+      "autoRecall": {
+        "type": "boolean"
+      },
+      "autoObserve": {
+        "type": "boolean"
+      },
+      "retrieveTopK": {
+        "type": "integer",
+        "minimum": 1,
+        "maximum": 20
+      },
+      "recallMinPromptLength": {
+        "type": "integer",
+        "minimum": 1,
+        "maximum": 500
+      },
+      "includeCrossSession": {
+        "type": "boolean"
+      },
+      "retrieveMemoryTypes": {
+        "type": "array",
+        "items": {
+          "type": "string",
+          "enum": ["profile", "semantic", "procedural", "working", "tool_result"]
+        }
+      },
+      "observeTailMessages": {
+        "type": "integer",
+        "minimum": 2,
+        "maximum": 30
+      },
+      "observeMaxChars": {
+        "type": "integer",
+        "minimum": 256,
+        "maximum": 50000
+      },
+      "embeddingProvider": {
+        "type": "string"
+      },
+      "embeddingModel": {
+        "type": "string"
+      },
+      "embeddingBaseUrl": {
+        "type": "string"
+      },
+      "embeddingApiKey": {
+        "type": "string"
+      },
+      "embeddingDim": {
+        "type": "integer",
+        "minimum": 1
+      },
+      "llmApiKey": {
+        "type": "string"
+      },
+      "llmBaseUrl": {
+        "type": "string"
+      },
+      "llmModel": {
+        "type": "string"
+      }
+    }
+  }
+}

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "@matrixorigin/thememoria",
+  "version": "0.4.0",
+  "description": "OpenClaw memory plugin that uses the Rust Memoria CLI/API for embedded and remote backends.",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/matrixorigin/Memoria.git"
+  },
+  "homepage": "https://github.com/matrixorigin/Memoria/tree/main/plugins/openclaw",
+  "bugs": {
+    "url": "https://github.com/matrixorigin/Memoria/issues"
+  },
+  "keywords": [
+    "openclaw",
+    "openclaw-plugin",
+    "memory",
+    "memoria",
+    "matrixone",
+    "local-first"
+  ],
+  "license": "Apache-2.0",
+  "type": "module",
+  "files": [
+    "README.md",
+    "scripts/",
+    "skills/",
+    "openclaw/",
+    "openclaw.plugin.json"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "peerDependencies": {
+    "openclaw": ">=2026.3.0"
+  },
+  "peerDependenciesMeta": {
+    "openclaw": {
+      "optional": true
+    }
+  },
+  "openclaw": {
+    "extensions": [
+      "./openclaw/index.ts"
+    ]
+  }
+}

package/scripts/connect_openclaw_memoria.mjs

@@ -0,0 +1,172 @@
+#!/usr/bin/env node
+import fs from "node:fs";
+import path from "node:path";
+
+function fail(message) {
+  console.error(`[memory-memoria] ${message}`);
+  process.exit(1);
+}
+
+function readArg(name, fallback = "") {
+  const index = process.argv.indexOf(name);
+  if (index >= 0 && index + 1 < process.argv.length) {
+    return process.argv[index + 1];
+  }
+  return fallback;
+}
+
+function asObject(value) {
+  return value && typeof value === "object" && !Array.isArray(value) ? value : {};
+}
+
+function normalizeUrl(value) {
+  return value.trim().replace(/\/+$/, "");
+}
+
+const modeRaw = readArg("--mode", "cloud").trim().toLowerCase();
+if (modeRaw !== "cloud" && modeRaw !== "local") {
+  fail("mode must be one of: cloud, local");
+}
+const mode = modeRaw;
+
+const pluginId = readArg("--plugin-id", "memory-memoria").trim() || "memory-memoria";
+const configFile = path.resolve(
+  readArg(
+    "--config-file",
+    path.join(process.env.HOME || "", ".openclaw", "openclaw.json"),
+  ),
+);
+
+const apiUrl = readArg("--api-url", "").trim();
+const apiKey = readArg("--api-key", "").trim();
+const dbUrl = readArg("--db-url", "").trim();
+const memoriaExecutable = readArg("--memoria-executable", "").trim();
+const defaultUserId = readArg("--default-user-id", "").trim();
+const embeddingProviderArg = readArg("--embedding-provider", "").trim();
+const embeddingModelArg = readArg("--embedding-model", "").trim();
+const embeddingApiKeyArg = readArg("--embedding-api-key", "").trim();
+const embeddingBaseUrlArg = readArg("--embedding-base-url", "").trim();
+const embeddingDimArg = readArg("--embedding-dim", "").trim();
+
+const embeddingDim =
+  embeddingDimArg.length > 0 ? Number.parseInt(embeddingDimArg, 10) : undefined;
+if (embeddingDimArg.length > 0 && (!Number.isFinite(embeddingDim) || embeddingDim < 1)) {
+  fail("embedding-dim must be a positive integer");
+}
+
+let data = {};
+if (fs.existsSync(configFile)) {
+  try {
+    data = JSON.parse(fs.readFileSync(configFile, "utf8"));
+  } catch (error) {
+    fail(`failed to parse config file ${configFile}: ${String(error)}`);
+  }
+} else {
+  fs.mkdirSync(path.dirname(configFile), { recursive: true });
+}
+
+const root = asObject(data);
+const plugins = asObject(root.plugins);
+const entries = asObject(plugins.entries);
+const slots = asObject(plugins.slots);
+const allow = Array.isArray(plugins.allow)
+  ? plugins.allow.filter((entry) => typeof entry === "string" && entry.trim())
+  : [];
+const pluginEntry = asObject(entries[pluginId]);
+const pluginConfig = asObject(pluginEntry.config);
+
+if (mode === "cloud") {
+  if (!apiUrl) {
+    fail("--api-url required when mode=cloud");
+  }
+  if (!apiKey) {
+    fail("--api-key required when mode=cloud");
+  }
+  pluginConfig.backend = "http";
+  pluginConfig.apiUrl = normalizeUrl(apiUrl);
+  pluginConfig.apiKey = apiKey;
+  delete pluginConfig.dbUrl;
+  delete pluginConfig.embeddingProvider;
+  delete pluginConfig.embeddingModel;
+  delete pluginConfig.embeddingApiKey;
+  delete pluginConfig.embeddingBaseUrl;
+  delete pluginConfig.embeddingDim;
+} else {
+  if (!dbUrl) {
+    fail("--db-url required when mode=local");
+  }
+
+  const embeddingProvider = embeddingProviderArg || String(pluginConfig.embeddingProvider || "openai");
+  const embeddingModel =
+    embeddingModelArg || String(pluginConfig.embeddingModel || "text-embedding-3-small");
+  const embeddingApiKey =
+    embeddingApiKeyArg || (typeof pluginConfig.embeddingApiKey === "string" ? pluginConfig.embeddingApiKey.trim() : "");
+
+  if (embeddingProvider !== "local" && !embeddingApiKey) {
+    fail("--embedding-api-key required for mode=local when embedding-provider is not 'local'");
+  }
+
+  pluginConfig.backend = "embedded";
+  pluginConfig.dbUrl = dbUrl;
+  pluginConfig.embeddingProvider = embeddingProvider;
+  pluginConfig.embeddingModel = embeddingModel;
+  delete pluginConfig.apiUrl;
+  delete pluginConfig.apiKey;
+  if (embeddingApiKey) {
+    pluginConfig.embeddingApiKey = embeddingApiKey;
+  }
+  if (embeddingBaseUrlArg) {
+    pluginConfig.embeddingBaseUrl = normalizeUrl(embeddingBaseUrlArg);
+  }
+  if (typeof embeddingDim === "number" && Number.isFinite(embeddingDim)) {
+    pluginConfig.embeddingDim = embeddingDim;
+  }
+}
+
+if (memoriaExecutable) {
+  pluginConfig.memoriaExecutable = memoriaExecutable;
+}
+if (defaultUserId) {
+  pluginConfig.defaultUserId = defaultUserId;
+}
+
+pluginEntry.enabled = true;
+pluginEntry.config = pluginConfig;
+entries[pluginId] = pluginEntry;
+slots.memory = pluginId;
+if (!allow.includes(pluginId)) {
+  allow.push(pluginId);
+}
+plugins.allow = allow;
+plugins.entries = entries;
+plugins.slots = slots;
+root.plugins = plugins;
+
+fs.writeFileSync(configFile, `${JSON.stringify(root, null, 2)}\n`, "utf8");
+
+console.log(
+  JSON.stringify(
+    {
+      ok: true,
+      mode,
+      configFile,
+      pluginId,
+      backend: pluginConfig.backend,
+      apiUrl:
+        pluginConfig.backend === "http" && typeof pluginConfig.apiUrl === "string"
+          ? pluginConfig.apiUrl
+          : undefined,
+      apiKeySet:
+        pluginConfig.backend === "http" &&
+        typeof pluginConfig.apiKey === "string" &&
+        pluginConfig.apiKey.length > 0,
+      dbUrl: typeof pluginConfig.dbUrl === "string" ? pluginConfig.dbUrl : undefined,
+      memoriaExecutable:
+        typeof pluginConfig.memoriaExecutable === "string"
+          ? pluginConfig.memoriaExecutable
+          : undefined,
+    },
+    null,
+    2,
+  ),
+);