@evermind-ai/openclaw-plugin 1.1.0 → 1.3.0

package/SKILL.md

@@ -0,0 +1,333 @@
+---
+name: everos
+version: 1.1.0
+description: |
+  Install and configure EverOS for OpenClaw natural-language memory.
+
+  Use when users say:
+  - "install everos"
+  - "setup everos"
+  - "install everos plugin"
+  - "enable everos memory"
+  - "remember my preferences in OpenClaw"
+author: EverMind
+keywords:
+  - everos
+  - evermemos
+  - context engine
+  - persistent memory
+  - openclaw
+  - natural language memory
+metadata:
+  openclaw:
+    emoji: "🧠"
+---
+
+# EverOS
+
+EverOS OpenClaw Plugin gives OpenClaw persistent memory through the **ContextEngine API**.
+
+Important distinction:
+
+- This is a `context-engine` plugin, not a `memory` slot plugin.
+- Users do not need to call memory tools manually.
+- Memory is triggered by normal conversation:
+  - before reply: relevant memory is recalled and injected
+  - after reply: new conversation content is saved back automatically
+
+---
+
+## Trigger phrases
+
+Use this skill when the user wants to:
+
+- install EverOS
+- set up EverOS memory for OpenClaw
+- enable long-term memory for OpenClaw
+- make natural-language conversations persist across sessions
+- configure the EverOS context engine
+
+---
+
+## When to use this skill
+
+Use this skill when the user wants:
+
+- persistent memory across OpenClaw sessions
+- automatic recall and save during normal conversation
+- a self-hosted EverOS backend
+- memory without manually calling `memory_store` / `memory_search`
+
+---
+
+## When NOT to use this skill
+
+Do not use this skill for:
+
+- cloud-only `mem9` onboarding
+- troubleshooting unrelated OpenClaw issues
+- temporary context that only matters in the current session
+
+---
+
+## What the user gets
+
+Automatic lifecycle behavior:
+
+| Hook | Trigger | What happens |
+| --- | --- | --- |
+| `bootstrap()` | Session starts | Backend health check and session state init |
+| `assemble()` | Before each turn | Searches relevant memory and injects it as context |
+| `afterTurn()` | After each turn | Saves new messages from the turn |
+| `compact()` | Compaction check | Participates in token-budget decisions |
+| `dispose()` | Session ends | Clears in-memory session state |
+
+User-facing result:
+
+- the user chats naturally
+- EverOS recalls relevant past context automatically
+- EverOS stores new useful context automatically
+
+---
+
+## Definition of Done
+
+This task is not complete until all of the following are true:
+
+1. the EverOS backend is reachable or the user has been explicitly told it still needs to be started
+2. the plugin is installed
+3. `openclaw.json` is configured correctly
+4. OpenClaw has been restarted
+5. the user has been given a natural-language verification step
+6. the full final handoff message has been sent
+
+---
+
+## Onboarding
+
+### Step 0 - Set expectations
+
+Before changing anything, tell the user:
+
+> OpenClaw will need a restart during setup. After restart, wait about 1 minute, then send a short natural-language message here to verify memory.
+
+Do not skip this notice if you are going to restart OpenClaw automatically.
+
+### Step 1 - Check the EverOS backend
+
+Default backend:
+
+```bash
+curl -sf http://localhost:1995/health && echo "OK" || echo "NOT_RUNNING"
+```
+
+If the backend is healthy, continue.
+
+If it is not healthy, tell the user plainly:
+
+> The EverOS backend is not reachable yet. I can still finish plugin installation now, but automatic recall/save will not work until the backend is running.
+
+If the user asks how to start the backend, give the shortest useful path:
+
+```bash
+git clone https://github.com/EverMind-AI/EverMemOS.git
+cd EverMemOS
+docker compose up -d
+curl -LsSf https://astral.sh/uv/install.sh | sh
+uv sync
+cp env.template .env
+# edit .env
+uv run python src/run.py
+```
+
+### Step 2 - Install plugin
+
+Preferred one-shot install:
+
+```bash
+npx --yes --package @evermind-ai/openclaw-plugin everos-install
+```
+
+Manual alternative:
+
+```bash
+npm install -g @evermind-ai/openclaw-plugin
+everos-install
+```
+
+What the installer does:
+
+- adds the plugin path to `plugins.load.paths`
+- adds `@evermind-ai/openclaw-plugin` to `plugins.allow`
+- sets `plugins.slots.contextEngine = "@evermind-ai/openclaw-plugin"`
+- sets `plugins.slots.memory = "none"` to avoid slot conflicts
+- creates or updates `plugins.entries["@evermind-ai/openclaw-plugin"]`
+
+### Step 3 - Manual config fallback
+
+If the installer is unavailable, patch `~/.openclaw/openclaw.json` manually.
+
+Expected config shape:
+
+```json
+{
+  "plugins": {
+    "allow": ["@evermind-ai/openclaw-plugin"],
+    "slots": {
+      "memory": "none",
+      "contextEngine": "@evermind-ai/openclaw-plugin"
+    },
+    "entries": {
+      "@evermind-ai/openclaw-plugin": {
+        "enabled": true,
+        "config": {
+          "baseUrl": "http://localhost:1995",
+          "userId": "everos-user",
+          "groupId": "everos-group",
+          "topK": 5,
+          "memoryTypes": ["episodic_memory", "profile", "agent_skill", "agent_case"],
+          "retrieveMethod": "hybrid"
+        }
+      }
+    }
+  }
+}
+```
+
+Merge-safe patch:
+
+```bash
+jq '
+  .plugins = (.plugins // {}) |
+  .plugins.load = (.plugins.load // {}) |
+  .plugins.load.paths = ((.plugins.load.paths // []) + ["/path/to/evermemos-openclaw-plugin"] | unique) |
+  .plugins.allow = ((.plugins.allow // []) + ["@evermind-ai/openclaw-plugin"] | unique) |
+  .plugins.slots = (.plugins.slots // {}) |
+  .plugins.slots.memory = "none" |
+  .plugins.slots.contextEngine = "@evermind-ai/openclaw-plugin" |
+  .plugins.entries = (.plugins.entries // {}) |
+  .plugins.entries["@evermind-ai/openclaw-plugin"].enabled = true |
+  .plugins.entries["@evermind-ai/openclaw-plugin"].config = (
+    (.plugins.entries["@evermind-ai/openclaw-plugin"].config // {}) + {
+      "baseUrl": "http://localhost:1995",
+      "userId": "everos-user",
+      "groupId": "everos-group",
+      "topK": 5,
+      "memoryTypes": ["episodic_memory", "profile", "agent_skill", "agent_case"],
+      "retrieveMethod": "hybrid"
+    }
+  )
+' ~/.openclaw/openclaw.json > tmp.json && mv tmp.json ~/.openclaw/openclaw.json
+```
+
+### Step 4 - Restart OpenClaw
+
+Restart command:
+
+```bash
+openclaw gateway restart
+```
+
+Immediately before restart, tell the user:
+
+> EverOS is installed. I am restarting OpenClaw now. After about 1 minute, send a short message so we can verify memory recall.
+
+### Step 5 - Verify
+
+Verification has two parts.
+
+Backend:
+
+```bash
+curl http://localhost:1995/health
+```
+
+User-facing natural-language test:
+
+> Say: "Remember: I like espresso."
+>
+> Then ask: "What coffee do I like?"
+
+This is the preferred validation because it checks the real user flow instead of just config.
+
+---
+
+## Final handoff
+
+After successful setup, send this handoff message in the user's language.
+Do not remove sections.
+
+```text
+✅ EverOS is ready.
+
+🧭 WHAT YOU CAN DO NEXT
+
+From now on, you can use normal natural language to make OpenClaw remember information.
+You do not need to call memory tools manually.
+
+Examples:
+- "Remember: I like espresso."
+- "Remember: this project uses PostgreSQL by default."
+- "My coding style prefers small functions and explicit naming."
+
+Later you can ask:
+- "What coffee do I like?"
+- "What database does this project use by default?"
+
+⚙️ CURRENT CONNECTION
+
+EverOS backend:
+BASE_URL: <base-url>
+
+OpenClaw config file:
+~/.openclaw/openclaw.json
+
+♻️ RECOVERY
+
+1. Keep your EverOS backend data and configuration
+2. Reinstall this plugin on the new machine
+3. Write the same `baseUrl`, `userId`, and `groupId` back into `openclaw.json`
+4. Restart OpenClaw to reconnect to the same memory space
+
+📦 BACKUP
+
+- Back up `~/.openclaw/openclaw.json`
+- Back up the EverOS backend data directory or database
+- Back up the EverMemOS `.env` and deployment configuration
+```
+
+---
+
+## Troubleshooting
+
+| Symptom | Fix |
+| --- | --- |
+| Plugin not loading | Check `plugins.allow`, `plugins.load.paths`, and `plugins.slots.contextEngine` |
+| Backend unhealthy | Check `baseUrl` and ensure the EverOS backend is running |
+| No recall | Verify the backend contains memories and the query is meaningful |
+| No save | Verify `afterTurn()` is running and backend write API is reachable |
+| Memory plugin conflict | Make sure `plugins.slots.memory = "none"` |
+
+---
+
+## API reference
+
+Base: `http://localhost:1995`
+
+| Method | Path | Description |
+| --- | --- | --- |
+| GET | `/health` | Health check |
+| POST | `/api/v1/memories` | Save memory |
+| GET | `/api/v1/memories/search` | Search memory |
+| DELETE | `/api/v1/memories` | Delete memory |
+
+---
+
+## Communication style
+
+When talking to users:
+
+- say this is automatic natural-language memory
+- do not describe it as a `memory` slot plugin
+- keep the next step concrete: restart, then try one short memory sentence
+- prefer real conversational verification over low-level API demos

package/bin/install.js

@@ -0,0 +1,354 @@
+#!/usr/bin/env node
+
+/**
+ * EverOS OpenClaw Plugin Installer
+ * Configures OpenClaw to use the EverOS backend through a ContextEngine.
+ */
+
+import fs from "node:fs";
+import path from "node:path";
+import { exec } from "node:child_process";
+import { fileURLToPath } from "node:url";
+import readline from "node:readline";
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+const HOME_DIR = process.env.HOME || process.env.USERPROFILE;
+const CONFIG_PATH = path.join(HOME_DIR, ".openclaw", "openclaw.json");
+const PLUGIN_ID = "@evermind-ai/openclaw-plugin";
+const PLUGIN_DIR = path.join(__dirname, "..");
+const STABLE_PLUGIN_DIR = path.join(HOME_DIR, ".openclaw", "plugins", "evermind-ai-openclaw-plugin");
+const DEFAULT_CONFIG = {
+  baseUrl: "http://localhost:1995",
+  userId: "everos-user",
+  groupId: "everos-group",
+  topK: 5,
+  memoryTypes: ["episodic_memory", "profile", "agent_skill", "agent_case"],
+  retrieveMethod: "hybrid",
+};
+
+const colors = {
+  reset: "\x1b[0m",
+  green: "\x1b[32m",
+  yellow: "\x1b[33m",
+  blue: "\x1b[34m",
+  red: "\x1b[31m",
+  cyan: "\x1b[36m",
+};
+
+function log(message, color = "reset") {
+  console.log(`${colors[color]}${message}${colors.reset}`);
+}
+
+function success(message) {
+  log(`✓ ${message}`, "green");
+}
+
+function error(message) {
+  log(`✗ ${message}`, "red");
+}
+
+function info(message) {
+  log(`ℹ ${message}`, "cyan");
+}
+
+function warn(message) {
+  log(`⚠ ${message}`, "yellow");
+}
+
+function hr() {
+  log("-".repeat(60), "blue");
+}
+
+const rl = readline.createInterface({
+  input: process.stdin,
+  output: process.stdout,
+});
+
+async function prompt(question) {
+  return new Promise((resolve) => {
+    rl.question(question, (answer) => {
+      resolve(answer.trim());
+    });
+  });
+}
+
+async function promptWithDefault(label, defaultValue) {
+  const answer = await prompt(`${label} (default: ${defaultValue}): `);
+  return answer || defaultValue;
+}
+
+function closeAndExit(code) {
+  rl.close();
+  process.exit(code);
+}
+
+async function checkBackendHealth(baseUrl) {
+  try {
+    const response = await fetch(`${baseUrl.replace(/\/*$/, "")}/health`, {
+      signal: AbortSignal.timeout(5000),
+    });
+    if (!response.ok) {
+      return { ok: false, reason: `HTTP ${response.status}` };
+    }
+    const data = await response.json().catch(() => null);
+    return {
+      ok: data?.status === "healthy" || data?.status === "ok" || response.ok,
+      status: data?.status,
+    };
+  } catch (err) {
+    return { ok: false, reason: err.message };
+  }
+}
+
+function isDevelopmentCheckout(dir) {
+  return fs.existsSync(path.join(dir, ".git"));
+}
+
+function ensureStablePluginPath() {
+  if (isDevelopmentCheckout(PLUGIN_DIR)) {
+    info(`Using local development checkout: ${PLUGIN_DIR}`);
+    return PLUGIN_DIR;
+  }
+
+  if (path.resolve(PLUGIN_DIR) === path.resolve(STABLE_PLUGIN_DIR)) {
+    return STABLE_PLUGIN_DIR;
+  }
+
+  fs.mkdirSync(path.dirname(STABLE_PLUGIN_DIR), { recursive: true });
+  fs.cpSync(PLUGIN_DIR, STABLE_PLUGIN_DIR, {
+    recursive: true,
+    force: true,
+  });
+
+  const installerPath = path.join(STABLE_PLUGIN_DIR, "bin", "install.js");
+  if (fs.existsSync(installerPath)) {
+    fs.chmodSync(installerPath, 0o755);
+  }
+
+  info(`Installed plugin files to ${STABLE_PLUGIN_DIR}`);
+  return STABLE_PLUGIN_DIR;
+}
+
+function isLegacyPluginPath(entry, pluginPath) {
+  if (typeof entry !== "string") return false;
+  if (path.resolve(entry) === path.resolve(pluginPath)) return false;
+
+  const normalized = entry.replace(/\\/g, "/");
+  return normalized.includes("evermemos-openclaw-plugin") ||
+    normalized.includes("evermind-ai-openclaw-plugin") ||
+    normalized.includes("@evermind-ai/openclaw-plugin");
+}
+
+function loadConfig() {
+  if (!fs.existsSync(CONFIG_PATH)) {
+    return { exists: false, data: null };
+  }
+
+  try {
+    return { exists: true, data: JSON.parse(fs.readFileSync(CONFIG_PATH, "utf-8")) };
+  } catch (err) {
+    error(`Failed to parse ${CONFIG_PATH}: ${err.message}`);
+    error("Please fix the JSON syntax before continuing.");
+    error("Installation aborted to avoid corrupting your configuration.");
+    return { exists: true, error: err.message };
+  }
+}
+
+function saveConfig(config) {
+  try {
+    if (fs.existsSync(CONFIG_PATH)) {
+      fs.copyFileSync(CONFIG_PATH, `${CONFIG_PATH}.bak`);
+    }
+    fs.writeFileSync(CONFIG_PATH, `${JSON.stringify(config, null, 2)}\n`, "utf-8");
+    return true;
+  } catch (err) {
+    error(`Failed to save config: ${err.message}`);
+    return false;
+  }
+}
+
+function ensureConfigShape(config) {
+  config.plugins = config.plugins || {};
+  config.plugins.load = config.plugins.load || {};
+  config.plugins.load.paths = Array.isArray(config.plugins.load.paths) ? config.plugins.load.paths : [];
+  config.plugins.allow = Array.isArray(config.plugins.allow) ? config.plugins.allow : [];
+  config.plugins.slots = config.plugins.slots || {};
+  config.plugins.entries = config.plugins.entries || {};
+}
+
+function mergePluginConfig(existingConfig, overrides = {}) {
+  return {
+    ...DEFAULT_CONFIG,
+    ...(existingConfig || {}),
+    ...overrides,
+  };
+}
+
+function printSummary(pluginPath, entry) {
+  hr();
+  log("Installation Summary", "blue");
+  log(`  Plugin ID:   ${PLUGIN_ID}`);
+  log(`  Plugin path: ${pluginPath}`);
+  log(`  Config file: ${CONFIG_PATH}`);
+  log(`  Backend URL: ${entry.config.baseUrl}`);
+  log(`  User ID:     ${entry.config.userId}`);
+  log(`  Group ID:    ${entry.config.groupId}`);
+  log("  Mode:        context-engine (natural language auto memory)");
+  hr();
+}
+
+function printNextSteps(entry) {
+  log("Next Steps", "green");
+  log("  1. Make sure your EverOS backend is running.");
+  log(`     curl ${entry.config.baseUrl}/health`, "cyan");
+  log("");
+  log("  2. Restart OpenClaw so the context engine can load.");
+  log("     openclaw gateway restart", "cyan");
+  log("");
+  log("  3. Verify with natural language.");
+  log('     Say: "Remember: I like espresso."', "cyan");
+  log('     Then ask: "What coffee do I like?"', "cyan");
+  hr();
+}
+
+function restartGateway() {
+  return new Promise((resolve) => {
+    exec("openclaw gateway restart", (err) => {
+      if (err) {
+        warn(`Could not restart OpenClaw automatically: ${err.message}`);
+        info("Please restart manually: openclaw gateway restart");
+      } else {
+        success("OpenClaw gateway restarted.");
+        info('After about 1 minute, send a natural language test such as "Remember: I like espresso." to verify recall.');
+      }
+      resolve();
+    });
+  });
+}
+
+async function install() {
+  hr();
+  log("EverOS OpenClaw Plugin Installer", "blue");
+  log("This keeps your current ContextEngine flow and enables automatic memory recall/save.");
+  hr();
+
+  const configResult = loadConfig();
+  if (configResult.error) {
+    closeAndExit(1);
+  }
+
+  let config;
+  if (!configResult.exists) {
+    warn(`OpenClaw config not found at ${CONFIG_PATH}`);
+    const answer = await prompt("Create a new OpenClaw config now? (Y/n): ");
+    if (answer.toLowerCase() === "n") {
+      info("Installation cancelled.");
+      closeAndExit(0);
+    }
+
+    fs.mkdirSync(path.dirname(CONFIG_PATH), { recursive: true });
+    config = {};
+  } else {
+    config = configResult.data;
+  }
+
+  ensureConfigShape(config);
+
+  const pluginPath = ensureStablePluginPath();
+  config.plugins.load.paths = config.plugins.load.paths.filter((entry) => {
+    if (isLegacyPluginPath(entry, pluginPath)) {
+      warn(`Removing old plugin path: ${entry}`);
+      return false;
+    }
+    return true;
+  });
+
+  if (!config.plugins.load.paths.includes(pluginPath)) {
+    config.plugins.load.paths.push(pluginPath);
+    success(`Added plugin path: ${pluginPath}`);
+  } else {
+    info(`Plugin path already configured: ${pluginPath}`);
+  }
+
+  if (!config.plugins.allow.includes(PLUGIN_ID)) {
+    config.plugins.allow.push(PLUGIN_ID);
+    success(`Added to allow list: ${PLUGIN_ID}`);
+  } else {
+    info(`Plugin already allowed: ${PLUGIN_ID}`);
+  }
+
+  if (config.plugins.slots.contextEngine !== PLUGIN_ID) {
+    const previous = config.plugins.slots.contextEngine || "none";
+    config.plugins.slots.contextEngine = PLUGIN_ID;
+    success(`Set contextEngine slot: ${previous} -> ${PLUGIN_ID}`);
+  } else {
+    info(`contextEngine slot already points to ${PLUGIN_ID}`);
+  }
+
+  if (config.plugins.slots.memory !== "none") {
+    const previous = config.plugins.slots.memory || "unset";
+    config.plugins.slots.memory = "none";
+    warn(`Set memory slot to none to avoid conflicts (was: ${previous})`);
+  } else {
+    info("memory slot already set to none");
+  }
+
+  const entry = config.plugins.entries[PLUGIN_ID] || {};
+  const hadExistingConfig = !!entry.config;
+  entry.enabled = true;
+
+  if (hadExistingConfig) {
+    entry.config = mergePluginConfig(entry.config);
+    info("Reusing existing plugin config and filling any missing defaults.");
+  } else {
+    hr();
+    info("Enter the minimum settings needed for the EverOS backend.");
+    const baseUrl = await promptWithDefault("EverOS backend URL", DEFAULT_CONFIG.baseUrl);
+    const health = await checkBackendHealth(baseUrl);
+
+    if (health.ok) {
+      success(`EverOS backend is reachable (${health.status || "ok"}).`);
+    } else {
+      warn(`EverOS backend is not reachable yet (${health.reason || "unknown reason"}).`);
+      warn("You can continue, but memory recall/save will not work until the backend is running.");
+      info("Typical start command: cd EverMemOS && uv run python src/run.py");
+    }
+
+    const userId = await promptWithDefault("User ID", DEFAULT_CONFIG.userId);
+    const groupId = await promptWithDefault("Group ID", DEFAULT_CONFIG.groupId);
+    entry.config = mergePluginConfig(null, { baseUrl, userId, groupId });
+    success("Plugin config created.");
+  }
+
+  config.plugins.entries[PLUGIN_ID] = entry;
+
+  hr();
+  info("Saving OpenClaw configuration...");
+  if (!saveConfig(config)) {
+    closeAndExit(1);
+  }
+  success("Configuration saved.");
+
+  printSummary(pluginPath, entry);
+  printNextSteps(entry);
+
+  const shouldRestart = await prompt("Restart OpenClaw gateway now? (Y/n): ");
+  if (shouldRestart.toLowerCase() !== "n") {
+    info("Restarting OpenClaw gateway...");
+    info('After restart, wait about 1 minute and test with a natural language memory prompt.');
+    await restartGateway();
+  } else {
+    info("When ready, run: openclaw gateway restart");
+    info('Then test with: "Remember: I like espresso."');
+  }
+
+  closeAndExit(0);
+}
+
+install().catch((err) => {
+  error(`Installation failed: ${err.message}`);
+  console.error(err);
+  closeAndExit(1);
+});