@evermind-ai/openclaw-plugin 1.1.0

package/index.js

@@ -0,0 +1,397 @@
+/**
+ * EverMemOS ContextEngine Plugin for OpenClaw
+ * Registers EverMemOS as the context engine for memory management
+ */
+
+import { resolveConfig } from "./src/config.js";
+import { searchMemories, saveMemories } from "./src/memory-api.js";
+import { buildMemoryPrompt, parseSearchResponse } from "./src/formatter.js";
+import { collectMessages, toText, isSessionResetPrompt } from "./src/message-utils.js";
+
+const PLUGIN_ID = "evermemos-openclaw-plugin";
+
+/**
+ * Convert OpenClaw AgentMessage to EverMemOS message format
+ * Handles both OpenClaw format (toolCall/toolResult) and Anthropic format (tool_use/tool_result)
+ * @param {Object} msg - OpenClaw AgentMessage
+ * @returns {Object} - EverMemOS message format
+ */
+function convertMessage(msg) {
+  const content = msg.content;
+  const originalRole = msg.role;
+  let role = originalRole;
+  let toolCalls = undefined;
+  let toolCallId = undefined;
+  let textContent = "";
+
+  // Normalize role - preserve toolResult for EverMemOS
+  // OpenClaw uses "toolResult", we map it to "tool" for EverMemOS
+  if (role === "toolResult") {
+    role = "tool";
+    toolCallId = msg.toolCallId || undefined;
+  } else if (role !== "user" && role !== "assistant" && role !== "tool") {
+    role = "user";
+  }
+
+  // Handle text content (simple string)
+  if (typeof content === "string") {
+    const result = { role, content };
+    if (toolCallId) result.tool_call_id = toolCallId;
+    return result;
+  }
+
+  // Handle content blocks (array of {type, ...})
+  if (Array.isArray(content)) {
+    for (const block of content) {
+      if (!block || !block.type) continue;
+
+      if (block.type === "text") {
+        const text = block.text ?? "";
+        textContent += (textContent ? "\n" : "") + text;
+      }
+      // OpenClaw format: toolCall
+      else if (block.type === "toolCall") {
+        toolCalls = toolCalls || [];
+        const tc = {
+          id: block.id,
+          type: "function",
+          function: {
+            name: block.name || "unknown",
+            arguments: typeof block.arguments === "string"
+              ? block.arguments
+              : JSON.stringify(block.arguments ?? {}),
+          },
+        };
+        toolCalls.push(tc);
+        textContent += (textContent ? "\n" : "") + `[Tool: ${block.name || "unknown"}]`;
+      }
+      // Anthropic format: tool_use
+      else if (block.type === "tool_use") {
+        toolCalls = toolCalls || [];
+        const tc = {
+          id: block.id,
+          type: "function",
+          function: {
+            name: block.name || "unknown",
+            arguments: typeof block.input === "string"
+              ? block.input
+              : JSON.stringify(block.input ?? {}),
+          },
+        };
+        toolCalls.push(tc);
+        textContent += (textContent ? "\n" : "") + `[Tool: ${block.name || "unknown"}]`;
+      }
+      // Anthropic format: tool_result (in assistant content array)
+      else if (block.type === "tool_result") {
+        toolCallId = block.tool_use_id;
+        const preview = safePreview(block.content);
+        textContent += (textContent ? "\n" : "") + `[Tool Result: ${preview}]`;
+      }
+    }
+
+    const result = { role, content: textContent || "" };
+    if (toolCalls) result.tool_calls = toolCalls;
+    if (toolCallId) result.tool_call_id = toolCallId;
+    return result;
+  }
+
+  // Fallback for unexpected content types
+  const fallbackContent = content == null ? "" : String(content);
+  const result = { role, content: fallbackContent };
+  if (toolCallId) result.tool_call_id = toolCallId;
+  return result;
+}
+
+/**
+ * Safely create a preview of tool result content
+ * @param {*} content - Tool result content (string, object, array, null, undefined, Symbol, function)
+ * @param {number} maxLength - Maximum preview length
+ * @returns {string} - Safe preview string
+ */
+function safePreview(content, maxLength = 200) {
+  if (content == null) return "(empty)";
+
+  let str = "";
+  if (typeof content === "string") {
+    str = content;
+  } else {
+    try {
+      str = JSON.stringify(content);
+      // JSON.stringify returns undefined for Symbol/function/undefined values
+      if (typeof str !== "string") {
+        str = String(content);
+      }
+    } catch {
+      str = String(content);
+    }
+  }
+
+  if (str.length <= maxLength) return str;
+  return str.slice(0, maxLength) + "...";
+}
+
+/**
+ * Create EverMemOS ContextEngine instance
+ * @param {Object} pluginConfig - Plugin configuration
+ * @param {Object} logger - Logger instance
+ * @returns {Object} - ContextEngine implementation
+ */
+function createContextEngineInstance(pluginConfig, logger) {
+  const cfg = resolveConfig(pluginConfig);
+  const log = logger || { info: (...a) => console.log(...a), warn: (...a) => console.warn(...a) };
+
+  log.info(`[evermemos] ContextEngine config: baseUrl=${cfg.serverUrl}, userId=${cfg.userId}`);
+
+  // Session state - shared across all sessions for this engine instance
+  const sessionState = new Map();
+
+  return {
+    info: {
+      id: PLUGIN_ID,
+      name: "EverMemOS ContextEngine",
+      version: "1.0.0",
+      ownsCompaction: false,
+    },
+
+    async bootstrap({ sessionId, sessionKey }) {
+      log.info(`[evermemos] bootstrap: session=${sessionId}, key=${sessionKey}`);
+
+      // Verify EverMemOS backend health
+      try {
+        const response = await fetch(`${cfg.serverUrl}/health`, {
+          signal: AbortSignal.timeout(5000),
+        });
+        if (response.ok) {
+          const result = await response.json();
+          log.info(`[evermemos] bootstrap: backend healthy, status=${result.status}`);
+        } else {
+          log.warn(`[evermemos] bootstrap: backend unhealthy, status=${response.status}`);
+        }
+      } catch (err) {
+        log.warn(`[evermemos] bootstrap: health check failed: ${err.message}`);
+      }
+
+      // Initialize or get session state
+      if (!sessionState.has(sessionKey)) {
+        sessionState.set(sessionKey, {
+          turnCount: 0,
+          lastAssembleTime: 0,
+          pendingFlush: false,
+          pendingMessages: [],
+        });
+        log.info(`[evermemos] bootstrap: initialized state for ${sessionKey}`);
+      } else {
+        log.info(`[evermemos] bootstrap: reusing existing state for ${sessionKey}, turn=${sessionState.get(sessionKey).turnCount}`);
+      }
+
+      return { bootstrapped: true };
+    },
+
+    async ingest({ sessionId, sessionKey, message }) {
+      log.info(`[evermemos] ingest: session=${sessionKey}, role=${message?.role}, isHeartbeat=${message?.isHeartbeat}`);
+
+      const state = sessionState.get(sessionKey);
+      if (!state) {
+        log.warn(`[evermemos] ingest: no state for session=${sessionKey}`);
+        return { ingested: false };
+      }
+
+      // Don't ingest heartbeats
+      if (message.isHeartbeat) {
+        return { ingested: false };
+      }
+
+      // Store for batch processing in afterTurn
+      state.pendingMessages.push(message);
+      log.info(`[evermemos] ingest: collected ${state.pendingMessages.length} messages so far`);
+
+      return { ingested: true };
+    },
+
+    async ingestBatch({ sessionId, sessionKey, messages, isHeartbeat }) {
+      log.info(`[evermemos] ingestBatch: session=${sessionKey}, count=${messages?.length}, isHeartbeat=${isHeartbeat}`);
+
+      if (isHeartbeat) {
+        return { ingestedCount: 0 };
+      }
+
+      const state = sessionState.get(sessionKey);
+      if (!state) {
+        log.warn(`[evermemos] ingestBatch: no state for session=${sessionKey}`);
+        return { ingestedCount: 0 };
+      }
+
+      // Store messages for later processing
+      state.pendingMessages.push(...messages);
+      log.info(`[evermemos] ingestBatch: collected ${state.pendingMessages.length} messages so far`);
+
+      return { ingestedCount: messages.length };
+    },
+
+    async afterTurn({ sessionId, sessionKey, messages, prePromptMessageCount }) {
+      const state = sessionState.get(sessionKey);
+      if (!state) {
+        log.warn(`[evermemos] afterTurn: no state for session=${sessionKey}`);
+        return;
+      }
+
+      state.turnCount++;
+
+      // Get new messages (those added after prePromptMessageCount)
+      const newMessages = prePromptMessageCount !== undefined
+        ? messages.slice(prePromptMessageCount)
+        : messages;
+
+      log.info(`[evermemos] afterTurn: session=${sessionKey}, turn=${state.turnCount}, totalMessages=${messages.length}, newMessages=${newMessages.length}`);
+
+      if (newMessages.length === 0) {
+        log.info(`[evermemos] afterTurn: session=${sessionKey}, turn=${state.turnCount}, no new messages to save`);
+        return;
+      }
+
+      try {
+        const evermemosMessages = newMessages.map(convertMessage).filter((m) => m.content);
+        if (evermemosMessages.length === 0) {
+          log.info(`[evermemos] afterTurn: session=${sessionKey}, turn=${state.turnCount}, no valid messages to save`);
+          return;
+        }
+        await saveMemories(cfg, {
+          userId: cfg.userId,
+          groupId: cfg.groupId,
+          messages: evermemosMessages,
+          flush: state.pendingFlush || false,
+        });
+        log.info(`[evermemos] afterTurn: session=${sessionKey}, turn=${state.turnCount}, saved ${evermemosMessages.length} messages`);
+
+        if (state.pendingFlush) {
+          state.pendingFlush = false;
+          log.info(`[evermemos] afterTurn: flush flag consumed`);
+        }
+      } catch (err) {
+        log.warn(`[evermemos] afterTurn: save failed: ${err.message}`);
+      }
+    },
+
+    async assemble({ sessionId, sessionKey, messages, tokenBudget }) {
+      // Initialize state if not exists (assemble can be called before bootstrap)
+      if (!sessionState.has(sessionKey)) {
+        sessionState.set(sessionKey, {
+          turnCount: 0,
+          lastAssembleTime: 0,
+          pendingFlush: false,
+          pendingMessages: [],
+        });
+        log.info(`[evermemos] assemble: initialized state for ${sessionKey}`);
+      }
+
+      const state = sessionState.get(sessionKey);
+
+      // Get the last user message as query
+      const lastUserMsg = [...messages].reverse().find((m) => m.role === "user");
+      const query = lastUserMsg ? toText(lastUserMsg) : "";
+
+      if (!query || query.length < 3) {
+        return { messages, estimatedTokens: 0 };
+      }
+
+      // Detect session reset - flush memory but keep current messages
+      if (isSessionResetPrompt(query)) {
+        log.info(`[evermemos] assemble: session reset detected, keeping current messages`);
+        state.pendingFlush = true;
+        // Return original messages without memory injection
+        // The reset intent is captured in the query itself
+        return { messages, estimatedTokens: 0 };
+      }
+
+      try {
+        state.lastAssembleTime = Date.now();
+
+        // Early turns: retrieve more context
+        const earlyTurnMultiplier = state.turnCount <= 2 ? 2 : 1;
+        const topK = Math.min(cfg.topK * earlyTurnMultiplier, 20);
+
+        const params = {
+          query,
+          user_id: cfg.userId,
+          group_ids: cfg.groupId ? [cfg.groupId] : undefined,
+          memory_types: cfg.memoryTypes,
+          retrieve_method: cfg.retrieveMethod,
+          top_k,
+        };
+
+        const result = await searchMemories(cfg, params);
+        const parsed = parseSearchResponse(result);
+
+        const memoryCount =
+          (parsed.episodic?.length || 0) +
+          (parsed.traits?.length || 0) +
+          (parsed.case ? 1 : 0) +
+          (parsed.skill ? 1 : 0);
+
+        if (memoryCount === 0) {
+          return { messages, estimatedTokens: 0 };
+        }
+
+        // Build memory context as a system message
+        const memoryText = buildMemoryPrompt(parsed, { wrapInCodeBlock: true });
+        const memoryMessage = {
+          role: "system",
+          content: `[Relevant Memory]\n${memoryText}`,
+          _memory: true,
+        };
+
+        log.info(`[evermemos] assemble: session=${sessionKey}, retrieved ${memoryCount} memories`);
+
+        // Return memory message + existing messages
+        return {
+          messages: [memoryMessage, ...messages],
+          estimatedTokens: Math.floor((memoryText.length + JSON.stringify(messages).length) / 3),
+        };
+      } catch (err) {
+        log.warn(`[evermemos] assemble: ${err.message}`);
+        return { messages, estimatedTokens: 0 };
+      }
+    },
+
+    async compact({ sessionId, sessionKey, tokenBudget, currentTokenCount }) {
+      const state = sessionState.get(sessionKey);
+      if (!state) {
+        return { ok: true, compacted: false, reason: "no session state" };
+      }
+
+      log.info(`[evermemos] compact: session=${sessionKey}, tokens=${currentTokenCount}, budget=${tokenBudget}`);
+
+      // Simple compaction strategy: if over 80% of budget, recommend compaction
+      const threshold = tokenBudget ? tokenBudget * 0.8 : 8000;
+      if (currentTokenCount && currentTokenCount > threshold) {
+        return {
+          ok: true,
+          compacted: false,
+          reason: `token count (${currentTokenCount}) exceeds threshold (${threshold})`,
+        };
+      }
+
+      return { ok: true, compacted: false, reason: "within threshold" };
+    },
+
+    async dispose() {
+      // Clean up session states
+      sessionState.clear();
+    },
+  };
+}
+
+/**
+ * Plugin entry point - registers the ContextEngine
+ * @param {Object} api - OpenClaw API
+ */
+export default function register(api) {
+  const log = api.logger || { info: (...a) => console.log(...a), warn: (...a) => console.warn(...a) };
+
+  log.info(`[evermemos] Registering EverMemOS ContextEngine plugin`);
+
+  // Register the ContextEngine factory
+  api.registerContextEngine(PLUGIN_ID, (pluginConfig) => {
+    return createContextEngineInstance(pluginConfig, api.logger);
+  });
+}

package/openclaw.plugin.json

@@ -0,0 +1,50 @@
+{
+  "id": "@evermind-ai/openclaw-plugin",
+  "name": "EverMemOS ContextEngine",
+  "description": "Full-lifecycle memory management with EverMemOS - supports bootstrap, assemble, afterTurn, compact, and subagent tracking",
+  "version": "1.0.0",
+  "kind": "context-engine",
+  "contextEngine": true,
+  "main": "./index.js",
+  "configSchema": {
+    "type": "object",
+    "additionalProperties": false,
+    "properties": {
+      "baseUrl": {
+        "type": "string",
+        "description": "EverMemOS server base URL",
+        "default": "http://localhost:1995"
+      },
+      "userId": {
+        "type": "string",
+        "description": "Identity used for memory ownership and as message sender",
+        "default": "evermemos-user"
+      },
+      "groupId": {
+        "type": "string",
+        "description": "Group id for shared memory",
+        "default": "evermemos-group"
+      },
+      "topK": {
+        "type": "integer",
+        "description": "Maximum number of memory entries to retrieve",
+        "default": 5
+      },
+      "memoryTypes": {
+        "type": "array",
+        "description": "EverMemOS memory types to search",
+        "items": {
+          "type": "string",
+          "enum": ["episodic_memory", "profile", "agent_skill", "agent_case"]
+        },
+        "default": ["episodic_memory", "profile", "agent_skill", "agent_case"]
+      },
+      "retrieveMethod": {
+        "type": "string",
+        "description": "Retrieval strategy used by EverMemOS",
+        "enum": ["keyword", "vector", "hybrid", "rrf", "agentic"],
+        "default": "hybrid"
+      }
+    }
+  }
+}

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "@evermind-ai/openclaw-plugin",
+  "version": "1.1.0",
+  "description": "EverMemOS ContextEngine integration for OpenClaw 3.8+",
+  "type": "module",
+  "main": "./index.js",
+  "exports": {
+    ".": "./index.js"
+  },
+  "files": [
+    "index.js",
+    "openclaw.plugin.json",
+    "README.md",
+    "README.zh.md",
+    "src/"
+  ],
+  "keywords": [
+    "openclaw",
+    "plugin",
+    "context-engine",
+    "memory",
+    "evermemos",
+    "ai",
+    "agent"
+  ],
+  "author": "EverMind",
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/evermind-ai/evermemos-openclaw-plugin"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "openclaw": {
+    "id": "@evermind-ai/openclaw-plugin",
+    "kind": "context-engine",
+    "contextEngine": true
+  }
+}

package/src/assembler.js

@@ -0,0 +1,96 @@
+/**
+ * Context Assembler Module
+ * Handles query-aware context assembly from EverMemOS memories
+ */
+
+import { searchMemories } from "./memory-api.js";
+import { buildMemoryPrompt, parseSearchResponse } from "./formatter.js";
+
+/**
+ * @typedef {import("./types.js").EverMemOSConfig} EverMemOSConfig
+ * @typedef {import("./types.js").Logger} Logger
+ * @typedef {import("./types.js").ParsedMemoryResponse} ParsedMemoryResponse
+ */
+
+/**
+ * Handles query-aware context assembly
+ * Retrieves relevant memories based on current query and conversation state
+ */
+export class ContextAssembler {
+  /**
+   * @param {EverMemOSConfig} cfg
+   * @param {Logger} logger
+   */
+  constructor(cfg, logger) {
+    this.cfg = cfg;
+    this.log = logger;
+  }
+
+  /**
+   * Assemble context from memories based on current query and conversation state
+   * @param {string} query - Current user query
+   * @param {Array} messages - Full conversation history
+   * @param {number} turnCount - Current turn number
+   * @returns {Promise<{context: string, memoryCount: number}>}
+   */
+  async assemble(query, messages, turnCount) {
+    // Early turns: retrieve more context for grounding
+    const earlyTurnMultiplier = turnCount <= 2 ? 2 : 1;
+    const topK = Math.min(this.cfg.topK * earlyTurnMultiplier, 20);
+
+    /** @type {Object} */
+    const params = {
+      query,
+      user_id: this.cfg.userId,
+      group_ids: this.cfg.groupId ? [this.cfg.groupId] : undefined,
+      memory_types: this.cfg.memoryTypes,
+      retrieve_method: this.cfg.retrieveMethod,
+      top_k: topK,
+    };
+
+    /** @type {any} */
+    const result = await searchMemories(this.cfg, params);
+    /** @type {ParsedMemoryResponse} */
+    const parsed = parseSearchResponse(result);
+
+    // Count total memories
+    const memoryCount =
+      (parsed.episodic?.length || 0) +
+      (parsed.traits?.length || 0) +
+      (parsed.case ? 1 : 0) +
+      (parsed.skill ? 1 : 0);
+
+    const context = buildMemoryPrompt(parsed, { wrapInCodeBlock: true });
+
+    return { context, memoryCount };
+  }
+
+  /**
+   * Build minimal context for subagents (smaller context window)
+   * @param {string} query - Subagent query
+   * @returns {Promise<string>}
+   */
+  async assembleForSubagent(query) {
+    if (!query || query.length < 3) return "";
+
+    const topK = Math.min(this.cfg.topK, 3);
+
+    /** @type {Object} */
+    const params = {
+      query,
+      user_id: this.cfg.userId,
+      group_ids: this.cfg.groupId ? [this.cfg.groupId] : undefined,
+      memory_types: this.cfg.memoryTypes,
+      retrieve_method: this.cfg.retrieveMethod,
+      top_k: topK,
+    };
+
+    /** @type {any} */
+    const result = await searchMemories(this.cfg, params);
+    /** @type {ParsedMemoryResponse} */
+    const parsed = parseSearchResponse(result);
+
+    // Use no code block for subagents (cleaner format)
+    return buildMemoryPrompt(parsed, { wrapInCodeBlock: false });
+  }
+}

package/src/compaction.js

@@ -0,0 +1,85 @@
+/**
+ * Compaction Handler Module
+ * Handles session compaction evaluation and participation
+ */
+
+/**
+ * @typedef {import("./types.js").EverMemOSConfig} EverMemOSConfig
+ * @typedef {import("./types.js").Logger} Logger
+ */
+
+/**
+ * Compaction evaluation parameters
+ * @typedef {Object} CompactionEvalParams
+ * @property {Array} messages
+ * @property {number} tokenCount
+ * @property {number} turnCount
+ * @property {number} lastAssembleTime
+ */
+
+/**
+ * Compaction decision result
+ * @typedef {Object} CompactionDecision
+ * @property {boolean} shouldCompact
+ * @property {string} reason
+ * @property {string} [memoryStrategy]
+ */
+
+/**
+ * Handles session compaction evaluation and participation
+ * Evaluates when to compact the conversation context
+ */
+export class CompactionHandler {
+  /**
+   * @param {EverMemOSConfig} cfg
+   * @param {Logger} logger
+   */
+  constructor(cfg, logger) {
+    this.cfg = cfg;
+    this.log = logger;
+
+    // Configurable thresholds
+    this.compactThresholdTokens = 8000;
+    this.compactThresholdTurns = 10;
+  }
+
+  /**
+   * Evaluate whether session should be compacted
+   * @param {CompactionEvalParams} params
+   * @returns {Promise<CompactionDecision>}
+   */
+  async evaluate({ messages, tokenCount, turnCount, lastAssembleTime }) {
+    // Compact if token count exceeds threshold
+    if (tokenCount > this.compactThresholdTokens) {
+      return {
+        shouldCompact: true,
+        reason: `token count (${tokenCount}) exceeds threshold (${this.compactThresholdTokens})`,
+        memoryStrategy: "consolidate_to_long_term",
+      };
+    }
+
+    // Compact if turn count exceeds threshold
+    if (turnCount > this.compactThresholdTurns) {
+      return {
+        shouldCompact: true,
+        reason: `turn count (${turnCount}) exceeds threshold (${this.compactThresholdTurns})`,
+        memoryStrategy: "consolidate_to_long_term",
+      };
+    }
+
+    // Compact if no recent memory assembly (stale session)
+    const timeSinceAssemble = Date.now() - lastAssembleTime;
+    if (lastAssembleTime > 0 && timeSinceAssemble > 30 * 60 * 1000) { // 30 minutes
+      return {
+        shouldCompact: true,
+        reason: `session inactive for ${Math.round(timeSinceAssemble / 60000)} minutes`,
+        memoryStrategy: "consolidate_to_long_term",
+      };
+    }
+
+    return {
+      shouldCompact: false,
+      reason: "token and turn counts within acceptable range",
+    };
+  }
+}

package/src/config.js

@@ -0,0 +1,14 @@
+const DEFAULT_URL = "http://localhost:1995";
+
+export const TIMEOUT_MS = 60000;
+
+export function resolveConfig(pc = {}) {
+  return {
+    serverUrl: (pc.baseUrl || DEFAULT_URL).replace(/\/*$/, ""),
+    userId: pc.userId || "evermemos-user",
+    groupId: pc.groupId || "evermemos-group",
+    topK: pc.topK ?? 5,
+    memoryTypes: pc.memoryTypes ?? ["episodic_memory", "profile", "agent_skill", "agent_case"],
+    retrieveMethod: pc.retrieveMethod ?? "hybrid",
+  };
+}