@matrixorigin/thememoria 0.4.0

package/scripts/uninstall-openclaw-memoria.sh

@@ -0,0 +1,362 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+PLUGIN_ID="memory-memoria"
+DEFAULT_INSTALL_DIR="${HOME}/.local/share/openclaw-plugins/openclaw-memoria"
+
+MEMORIA_TOOL_NAMES=(
+  memory_search
+  memory_get
+  memory_store
+  memory_retrieve
+  memory_recall
+  memory_list
+  memory_stats
+  memory_profile
+  memory_correct
+  memory_purge
+  memory_forget
+  memory_health
+  memory_observe
+  memory_governance
+  memory_consolidate
+  memory_reflect
+  memory_extract_entities
+  memory_link_entities
+  memory_rebuild_index
+  memory_capabilities
+  memory_snapshot
+  memory_snapshots
+  memory_rollback
+  memory_branch
+  memory_branches
+  memory_checkout
+  memory_branch_delete
+  memory_merge
+  memory_diff
+)
+
+log() {
+  printf '[memory-memoria] %s\n' "$*"
+}
+
+fail() {
+  printf '[memory-memoria] error: %s\n' "$*" >&2
+  exit 1
+}
+
+need_cmd() {
+  command -v "$1" >/dev/null 2>&1 || fail "Missing required command: $1"
+}
+
+usage() {
+  cat <<'EOF'
+Remove the OpenClaw Memoria plugin and its OpenClaw config.
+
+Usage:
+  bash scripts/uninstall-openclaw-memoria.sh [options]
+  curl -fsSL <raw-script-url> | bash -s --
+
+Options:
+  --source-dir <path>  Also delete this plugin checkout after uninstall.
+  --keep-source        Keep the managed install directory on disk.
+  --help               Show this help text.
+
+Environment overrides:
+  OPENCLAW_HOME        Optional target OpenClaw home.
+
+What gets removed by default:
+  - plugins.entries["memory-memoria"]
+  - plugins.installs["memory-memoria"]
+  - plugins.allow entry for memory-memoria
+  - plugins.load.paths entries that point at this plugin
+  - tool policy entries for the Memoria tool surface
+  - managed companion skills in ~/.openclaw/skills: memoria-memory, memoria-recovery
+  - the default managed plugin dir: ~/.local/share/openclaw-plugins/openclaw-memoria
+
+What gets restored:
+  - plugins.slots.memory -> memory-core
+  - plugins.entries["memory-core"].enabled -> true
+EOF
+}
+
+config_file_path() {
+  if [[ -n "${OPENCLAW_HOME_VALUE}" ]]; then
+    printf '%s/.openclaw/openclaw.json' "${OPENCLAW_HOME_VALUE}"
+  else
+    printf '%s/.openclaw/openclaw.json' "${HOME}"
+  fi
+}
+
+skills_dir_path() {
+  if [[ -n "${OPENCLAW_HOME_VALUE}" ]]; then
+    printf '%s/.openclaw/skills' "${OPENCLAW_HOME_VALUE}"
+  else
+    printf '%s/.openclaw/skills' "${HOME}"
+  fi
+}
+
+OPENCLAW_HOME_VALUE="${OPENCLAW_HOME:-}"
+SOURCE_DIR=""
+KEEP_SOURCE=false
+
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --source-dir)
+      SOURCE_DIR="${2:?missing value for --source-dir}"
+      shift 2
+      ;;
+    --keep-source)
+      KEEP_SOURCE=true
+      shift
+      ;;
+    --help|-h)
+      usage
+      exit 0
+      ;;
+    *)
+      fail "Unknown option: $1"
+      ;;
+  esac
+done
+
+need_cmd node
+
+CONFIG_FILE="$(config_file_path)"
+MANAGED_SKILLS_DIR="$(skills_dir_path)"
+MEMORIA_TOOL_NAMES_JSON="$(printf '%s\n' "${MEMORIA_TOOL_NAMES[@]}" | node -e 'const fs=require("node:fs"); const lines=fs.readFileSync(0,"utf8").trim().split(/\n+/).filter(Boolean); process.stdout.write(JSON.stringify(lines));')"
+
+UNINSTALL_RESULT="$(
+  CONFIG_FILE="${CONFIG_FILE}" \
+  PLUGIN_ID="${PLUGIN_ID}" \
+  DEFAULT_INSTALL_DIR="${DEFAULT_INSTALL_DIR}" \
+  SOURCE_DIR_RAW="${SOURCE_DIR}" \
+  KEEP_SOURCE="${KEEP_SOURCE}" \
+  MEMORIA_TOOL_NAMES_JSON="${MEMORIA_TOOL_NAMES_JSON}" \
+  node - <<'NODE'
+const fs = require("node:fs");
+const path = require("node:path");
+
+const configPath = path.resolve(process.env.CONFIG_FILE);
+const pluginId = process.env.PLUGIN_ID;
+const defaultInstallDir = path.resolve(process.env.DEFAULT_INSTALL_DIR);
+const sourceDirRaw = process.env.SOURCE_DIR_RAW || "";
+const keepSource = process.env.KEEP_SOURCE === "true";
+const memoriaToolNames = JSON.parse(process.env.MEMORIA_TOOL_NAMES_JSON);
+
+function readJson(filePath) {
+  if (!fs.existsSync(filePath)) {
+    return {};
+  }
+  return JSON.parse(fs.readFileSync(filePath, "utf8"));
+}
+
+function writeJson(filePath, value) {
+  fs.mkdirSync(path.dirname(filePath), { recursive: true });
+  fs.writeFileSync(filePath, `${JSON.stringify(value, null, 2)}\n`);
+}
+
+function maybePath(rawPath) {
+  if (!rawPath) {
+    return null;
+  }
+  return path.resolve(rawPath.replace(/^~(?=$|\/|\\)/, process.env.HOME || "~"));
+}
+
+function manifestPluginId(candidatePath) {
+  try {
+    const manifestPath = path.join(candidatePath, "openclaw.plugin.json");
+    if (!fs.existsSync(manifestPath)) {
+      return null;
+    }
+    const manifest = JSON.parse(fs.readFileSync(manifestPath, "utf8"));
+    return typeof manifest.id === "string" ? manifest.id : null;
+  } catch {
+    return null;
+  }
+}
+
+const data = readJson(configPath);
+let changed = false;
+const plugins = data.plugins && typeof data.plugins === "object" && !Array.isArray(data.plugins)
+  ? data.plugins
+  : {};
+const tools = data.tools && typeof data.tools === "object" && !Array.isArray(data.tools)
+  ? data.tools
+  : {};
+
+const candidatePaths = new Set([defaultInstallDir]);
+const sourceDir = maybePath(sourceDirRaw);
+if (sourceDir) {
+  candidatePaths.add(sourceDir);
+}
+
+if (plugins.entries && typeof plugins.entries === "object" && !Array.isArray(plugins.entries)) {
+  if (pluginId in plugins.entries) {
+    delete plugins.entries[pluginId];
+    changed = true;
+  }
+  const quotedKey = JSON.stringify(pluginId);
+  if (quotedKey in plugins.entries) {
+    delete plugins.entries[quotedKey];
+    changed = true;
+  }
+  if (Object.keys(plugins.entries).length === 0) {
+    delete plugins.entries;
+  }
+}
+
+if (plugins.installs && typeof plugins.installs === "object" && !Array.isArray(plugins.installs)) {
+  if (pluginId in plugins.installs) {
+    delete plugins.installs[pluginId];
+    changed = true;
+  }
+  if (Object.keys(plugins.installs).length === 0) {
+    delete plugins.installs;
+  }
+}
+
+if (Array.isArray(plugins.allow)) {
+  const next = plugins.allow.filter((entry) => entry !== pluginId);
+  if (next.length !== plugins.allow.length) {
+    plugins.allow = next;
+    changed = true;
+  }
+  if (plugins.allow.length === 0) {
+    delete plugins.allow;
+  }
+}
+
+if (plugins.load && typeof plugins.load === "object" && !Array.isArray(plugins.load) && Array.isArray(plugins.load.paths)) {
+  const next = plugins.load.paths.filter((entry) => {
+    if (typeof entry !== "string") {
+      return true;
+    }
+    const resolved = maybePath(entry);
+    if (resolved && candidatePaths.has(resolved)) {
+      changed = true;
+      return false;
+    }
+    if (resolved && manifestPluginId(resolved) === pluginId) {
+      changed = true;
+      return false;
+    }
+    if ((entry.includes("openclaw-memoria") || entry.includes(pluginId)) && (!resolved || !fs.existsSync(resolved))) {
+      changed = true;
+      return false;
+    }
+    return true;
+  });
+  plugins.load.paths = next;
+  if (plugins.load.paths.length === 0) {
+    delete plugins.load.paths;
+  }
+  if (Object.keys(plugins.load).length === 0) {
+    delete plugins.load;
+  }
+}
+
+if (plugins.slots && typeof plugins.slots === "object" && !Array.isArray(plugins.slots) && plugins.slots.memory === pluginId) {
+  plugins.slots.memory = "memory-core";
+  plugins.entries = plugins.entries && typeof plugins.entries === "object" && !Array.isArray(plugins.entries)
+    ? plugins.entries
+    : {};
+  const coreEntry = plugins.entries["memory-core"] && typeof plugins.entries["memory-core"] === "object" && !Array.isArray(plugins.entries["memory-core"])
+    ? plugins.entries["memory-core"]
+    : (plugins.entries["memory-core"] = {});
+  coreEntry.enabled = true;
+  changed = true;
+}
+
+for (const key of ["allow", "alsoAllow"]) {
+  if (Array.isArray(tools[key])) {
+    const next = tools[key].filter((entry) => !memoriaToolNames.includes(entry));
+    if (next.length !== tools[key].length) {
+      tools[key] = next;
+      changed = true;
+    }
+    if (tools[key].length === 0) {
+      delete tools[key];
+    }
+  }
+}
+
+if (data.agents && typeof data.agents === "object" && Array.isArray(data.agents.list)) {
+  for (const agent of data.agents.list) {
+    if (!agent || typeof agent !== "object" || Array.isArray(agent) || !agent.tools || typeof agent.tools !== "object" || Array.isArray(agent.tools)) {
+      continue;
+    }
+    for (const key of ["allow", "alsoAllow"]) {
+      if (Array.isArray(agent.tools[key])) {
+        const next = agent.tools[key].filter((entry) => !memoriaToolNames.includes(entry));
+        if (next.length !== agent.tools[key].length) {
+          agent.tools[key] = next;
+          changed = true;
+        }
+        if (agent.tools[key].length === 0) {
+          delete agent.tools[key];
+        }
+      }
+    }
+    if (Object.keys(agent.tools).length === 0) {
+      delete agent.tools;
+    }
+  }
+}
+
+if (Object.keys(plugins).length > 0) {
+  data.plugins = plugins;
+} else {
+  delete data.plugins;
+}
+if (Object.keys(tools).length > 0) {
+  data.tools = tools;
+} else {
+  delete data.tools;
+}
+
+if (changed && fs.existsSync(configPath)) {
+  writeJson(`${configPath}.bak`, readJson(configPath));
+  writeJson(configPath, data);
+}
+
+const deletedPaths = [];
+if (!keepSource && fs.existsSync(defaultInstallDir)) {
+  fs.rmSync(defaultInstallDir, { recursive: true, force: true });
+  deletedPaths.push(defaultInstallDir);
+}
+if (sourceDir && fs.existsSync(sourceDir)) {
+  fs.rmSync(sourceDir, { recursive: true, force: true });
+  deletedPaths.push(sourceDir);
+}
+
+process.stdout.write(JSON.stringify({
+  ok: true,
+  configFile: configPath,
+  configChanged: changed,
+  deletedPaths
+}));
+NODE
+)"
+
+for skill_name in memoria-memory memoria-recovery; do
+  if [[ -d "${MANAGED_SKILLS_DIR}/${skill_name}" ]]; then
+    rm -rf "${MANAGED_SKILLS_DIR:?}/${skill_name}"
+    log "Removed managed skill: ${skill_name}"
+  fi
+done
+
+log "Removed OpenClaw Memoria plugin configuration"
+log "${UNINSTALL_RESULT}"
+
+cat <<EOF
+
+Uninstall complete.
+
+Config file: ${CONFIG_FILE}
+
+Recommended follow-up checks:
+  cd ~
+  openclaw plugins list --json | rg 'memory-memoria|openclaw-memoria' || true
+  openclaw config get 'plugins.slots.memory'
+EOF

package/scripts/verify_plugin_install.mjs

@@ -0,0 +1,149 @@
+#!/usr/bin/env node
+import { execFileSync } from "node:child_process";
+import fs from "node:fs";
+import net from "node:net";
+import path from "node:path";
+
+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;
+}
+
+const openclawBin = readArg("--openclaw-bin", "openclaw");
+const memoriaBin = readArg("--memoria-bin", "memoria");
+const configFile = path.resolve(readArg("--config-file", path.join(process.env.HOME || "", ".openclaw", "openclaw.json")));
+
+function run(command, args) {
+  return execFileSync(command, args, {
+    encoding: "utf8",
+    stdio: ["ignore", "pipe", "pipe"],
+  }).trim();
+}
+
+function tryParseJson(raw) {
+  try {
+    return JSON.parse(raw);
+  } catch {
+    return null;
+  }
+}
+
+function parseCommandJson(raw) {
+  const direct = tryParseJson(raw);
+  if (direct) {
+    return direct;
+  }
+  const start = raw.indexOf("{");
+  const end = raw.lastIndexOf("}");
+  if (start >= 0 && end > start) {
+    return tryParseJson(raw.slice(start, end + 1)) ?? raw;
+  }
+  return raw;
+}
+
+function parsePort(rawProtocol, rawPort) {
+  if (rawPort) {
+    return Number.parseInt(rawPort, 10);
+  }
+  return rawProtocol === "mysql:" ? 3306 : 80;
+}
+
+function checkTcp(host, port, timeoutMs = 1500) {
+  return new Promise((resolve) => {
+    const socket = new net.Socket();
+    let settled = false;
+
+    const finish = (value) => {
+      if (settled) {
+        return;
+      }
+      settled = true;
+      socket.destroy();
+      resolve(value);
+    };
+
+    socket.setTimeout(timeoutMs);
+    socket.once("connect", () => finish(true));
+    socket.once("timeout", () => finish(false));
+    socket.once("error", () => finish(false));
+    socket.connect(port, host);
+  });
+}
+
+if (!fs.existsSync(configFile)) {
+  throw new Error(`OpenClaw config file not found: ${configFile}`);
+}
+
+const config = JSON.parse(fs.readFileSync(configFile, "utf8"));
+const pluginEntry = config?.plugins?.entries?.["memory-memoria"];
+if (!pluginEntry || pluginEntry.enabled !== true) {
+  throw new Error("plugins.entries.memory-memoria is not enabled");
+}
+
+const pluginConfig = pluginEntry.config ?? {};
+if (pluginConfig.memoriaExecutable == null) {
+  throw new Error("plugins.entries.memory-memoria.config.memoriaExecutable is missing");
+}
+
+const resolvedMemoriaBin = pluginConfig.memoriaExecutable || memoriaBin;
+const openclawVersion = run(openclawBin, ["--version"]);
+const configValidation = tryParseJson(run(openclawBin, ["config", "validate", "--json"]));
+const memoriaVersion = run(resolvedMemoriaBin, ["--version"]);
+const capabilities = run(openclawBin, ["memoria", "capabilities"]);
+
+if (!capabilities.includes("memory_branch") || !capabilities.includes("memory_snapshot")) {
+  throw new Error("OpenClaw memoria capabilities output is missing expected Rust Memoria tools");
+}
+
+const result = {
+  ok: true,
+  configFile,
+  openclawVersion,
+  memoriaVersion,
+  memoriaExecutable: pluginConfig.memoriaExecutable,
+  configValidation,
+  deepChecks: {
+    backend: pluginConfig.backend ?? "embedded",
+    performed: false,
+    skipped: null,
+  },
+};
+
+if ((pluginConfig.backend ?? "embedded") === "embedded" && typeof pluginConfig.dbUrl === "string") {
+  const dbUrl = new URL(pluginConfig.dbUrl);
+  const dbReachable = await checkTcp(
+    dbUrl.hostname || "127.0.0.1",
+    parsePort(dbUrl.protocol, dbUrl.port),
+  );
+
+  result.deepChecks.dbUrl = pluginConfig.dbUrl;
+  result.deepChecks.dbReachable = dbReachable;
+
+  if (dbReachable) {
+    const userId =
+      typeof pluginConfig.defaultUserId === "string" && pluginConfig.defaultUserId.trim()
+        ? pluginConfig.defaultUserId.trim()
+        : "openclaw-user";
+    const statsRaw = run(openclawBin, ["memoria", "stats", "--user-id", userId]);
+    const listRaw = run(openclawBin, ["ltm", "list", "--limit", "1", "--user-id", userId]);
+    result.deepChecks.performed = true;
+    result.deepChecks.userId = userId;
+    result.deepChecks.stats = parseCommandJson(statsRaw);
+    result.deepChecks.list = parseCommandJson(listRaw);
+  } else {
+    result.deepChecks.skipped = "Embedded database is not reachable; skipped stats/list verification.";
+  }
+} else {
+  result.deepChecks.skipped = "Deep verification is only automatic for embedded mode.";
+}
+
+console.log(
+  JSON.stringify(
+    result,
+    null,
+    2,
+  ),
+);

package/skills/memoria-memory/SKILL.md

@@ -0,0 +1,43 @@
+---
+name: memoria-memory
+description: |
+  Use Memoria for durable user/project memory in OpenClaw.
+  Triggers: "remember this", "save to memory", "what do you remember",
+  "forget this", "correct memory", "update memory", "use memoria".
+---
+
+# Memoria Memory
+
+Use Memoria tools for durable memory. Do not default to `MEMORY.md` or `memory/YYYY-MM-DD.md` unless the user explicitly asks for file-based memory.
+
+## When to use
+
+- The user asks you to remember a fact, preference, decision, or workflow.
+- The user asks what you already know about them, the project, or a prior session.
+- The user asks to correct, update, or delete stored memory.
+
+## Store
+
+1. Choose the smallest durable fact worth keeping.
+2. Use the most specific tool available:
+   - `memory_profile` for stable user preferences or profile traits
+   - `memory_store` for facts, procedures, and project knowledge
+3. Prefer short, atomic entries.
+4. After storing something important, verify with `memory_recall` or `memory_search`.
+
+## Recall
+
+1. When the user asks "what do you know", "what do you remember", or refers to a prior session, query Memoria first.
+2. Use `memory_recall` for semantic retrieval and `memory_get` only when you already have a specific memory id.
+
+## Repair
+
+1. If the user says a memory is wrong, use `memory_correct`.
+2. If the user wants it removed, use `memory_forget` or `memory_purge`.
+3. After repair, verify with `memory_recall` or `memory_search`.
+
+## Rules
+
+- Do not claim only `memory_search` and `memory_get` exist when other `memory_*` tools are available.
+- Do not store transient small talk unless the user asks or it is clearly a stable preference.
+- Prefer Memoria for durable cross-session memory; prefer workspace files only for explicit file-based notes.

package/skills/memoria-recovery/SKILL.md

@@ -0,0 +1,29 @@
+---
+name: memoria-recovery
+description: |
+  Recover from accidental memory loss with snapshots and rollback.
+  Triggers: "restore memory", "rollback memory", "undo deleted memory",
+  "recover deleted memory", "take a memory snapshot".
+---
+
+# Memoria Recovery
+
+Use Memoria snapshot tools when memory state needs a checkpoint or a rollback.
+
+## Before risky changes
+
+1. If you are about to bulk-delete, purge, or rewrite memory, create a snapshot first with `memory_snapshot`.
+2. Tell the user a checkpoint exists and can be restored.
+
+## After accidental deletion or corruption
+
+1. Inspect available recovery points with `memory_snapshots`.
+2. Choose the most recent good snapshot.
+3. Restore with `memory_rollback`.
+4. Verify recovery with `memory_recall`, `memory_list`, or `memory_stats`.
+
+## Rules
+
+- Prefer rollback over manually re-creating many deleted memories.
+- If the user wants a selective logical fix rather than full restore, use `memory_correct` or `memory_forget` instead.
+- After rollback, state what was restored and what you verified.