@evermind-ai/openclaw-plugin 1.1.0

package/src/message-utils.js

@@ -0,0 +1,163 @@
+import { CONTEXT_BOUNDARY } from "./formatter.js";
+
+const MAX_CHARS = 20000;
+
+/* ------------------------------------------------------------------ */
+/*  Helpers                                                            */
+/* ------------------------------------------------------------------ */
+
+export function toText(content) {
+  if (!content) return "";
+  if (typeof content === "string") return content;
+  if (!Array.isArray(content)) return "";
+  return content.reduce((out, block) => {
+    if (block?.type !== "text" || !block.text) return out;
+    return out ? `${out} ${block.text}` : block.text;
+  }, "");
+}
+
+function stripContext(text) {
+  if (!text) return text;
+  const cut = text.lastIndexOf(CONTEXT_BOUNDARY);
+  return cut < 0 ? text : text.slice(cut + CONTEXT_BOUNDARY.length).replace(/^\s+/, "");
+}
+
+function cap(s) {
+  return s && s.length > MAX_CHARS ? `${s.slice(0, MAX_CHARS)}…` : (s || "");
+}
+
+/* ------------------------------------------------------------------ */
+/*  OpenClaw unified format helpers                                    */
+/*                                                                     */
+/*  Tool call:   assistant content block  type:"toolCall"              */
+/*  Tool result: standalone message       role:"toolResult"            */
+/* ------------------------------------------------------------------ */
+
+/** Convert an OpenClaw toolCall block to EverMemOS tool_calls item */
+function toToolCallItem(block) {
+  const name = block.name || "unknown";
+  const args = block.arguments;
+  let argsStr = "";
+  if (args != null) {
+    try {
+      argsStr = typeof args === "string" ? args : JSON.stringify(args);
+    } catch {
+      argsStr = String(args);
+    }
+  }
+  return {
+    id: block.id || undefined,
+    type: "function",
+    function: { name, arguments: argsStr },
+  };
+}
+
+function toolResultContent(msg) {
+  const c = msg.content;
+  if (!c) return "";
+  if (typeof c === "string") return c;
+  if (Array.isArray(c)) {
+    return c.reduce((out, b) => {
+      if (b?.type === "text" && b.text) return out ? `${out}\n${b.text}` : b.text;
+      return out;
+    }, "");
+  }
+  return "";
+}
+
+/* ------------------------------------------------------------------ */
+/*  Entry conversion                                                   */
+/* ------------------------------------------------------------------ */
+
+function toEntries(msg) {
+  if (!msg?.role) return [];
+
+  /* --- toolResult message --- */
+  if (msg.role === "toolResult") {
+    const text = cap(toolResultContent(msg) || toText(msg.content));
+    if (!text) return [];
+    return [{
+      role: "tool",
+      tool_call_id: msg.toolCallId || undefined,
+      content: text,
+    }];
+  }
+
+  /* --- user message --- */
+  if (msg.role === "user") {
+    const text = cap(stripContext(toText(msg.content)));
+    return text ? [{ role: "user", content: text }] : [];
+  }
+
+  /* --- assistant message --- */
+  if (msg.role === "assistant") {
+    const text = cap(toText(msg.content));
+    const toolCalls = Array.isArray(msg.content)
+      ? msg.content.filter((b) => b?.type === "toolCall").map(toToolCallItem)
+      : [];
+    if (!text && !toolCalls.length) return [];
+    const effectiveText = text || toolCalls.map((tc) => `[tool_call: ${tc.function.name}]`).join(", ");
+    const entry = { role: "assistant", content: effectiveText };
+    if (toolCalls.length) entry.tool_calls = toolCalls;
+    return [entry];
+  }
+
+  return [];
+}
+
+/* ------------------------------------------------------------------ */
+/*  Public API                                                         */
+/* ------------------------------------------------------------------ */
+
+/**
+ * Collect the last turn (final user message and everything after it).
+ * Skips over toolResult messages when searching for the real user message.
+ */
+export function collectMessages(messages) {
+  let pivot = -1;
+  for (let i = messages.length - 1; i >= 0; i--) {
+    if (messages[i]?.role === "user") { pivot = i; break; }
+  }
+  if (pivot < 0) return [];
+
+  return messages.slice(pivot).flatMap((m) => toEntries(m));
+}
+
+/* ------------------------------------------------------------------ */
+/*  Session reset prompt detection                                     */
+/* ------------------------------------------------------------------ */
+
+export const BARE_SESSION_RESET_PROMPT =
+  "A new session was started via /new or /reset. Execute your Session Startup sequence now - read the required files before responding to the user. Then greet the user in your configured persona, if one is provided. Be yourself - use your defined voice, mannerisms, and mood. Keep it to 1-3 sentences and ask what they want to do. If the runtime model differs from default_model in the system prompt, mention the default model. Do not mention internal steps, files, tools, or reasoning.";
+
+/** Levenshtein edit distance (space-optimised O(m*n) time, O(n) space) */
+function levenshtein(a, b) {
+  const m = a.length;
+  const n = b.length;
+  const prev = Array.from({ length: n + 1 }, (_, i) => i);
+  const curr = new Array(n + 1);
+  for (let i = 1; i <= m; i++) {
+    curr[0] = i;
+    for (let j = 1; j <= n; j++) {
+      curr[j] = a[i - 1] === b[j - 1]
+        ? prev[j - 1]
+        : 1 + Math.min(prev[j - 1], prev[j], curr[j - 1]);
+    }
+    prev.splice(0, n + 1, ...curr);
+  }
+  return prev[n];
+}
+
+/**
+ * Returns true when the query is within 20% length of BARE_SESSION_RESET_PROMPT
+ * AND the edit-distance ratio is below 0.20 (i.e. ≥80% similar).
+ */
+export function isSessionResetPrompt(query) {
+  if (!query) return false;
+  const promptLen = BARE_SESSION_RESET_PROMPT.length;
+  const queryLen = query.length;
+  // Fast path: length must be within ±20% of the prompt
+  if (Math.abs(queryLen - promptLen) / promptLen > 0.20) return false;
+  const dist = levenshtein(query, BARE_SESSION_RESET_PROMPT);
+  return dist / Math.max(queryLen, promptLen) < 0.20;
+}

package/src/subagent.js

@@ -0,0 +1,116 @@
+/**
+ * Subagent Tracker Module
+ * Tracks subagent lifecycles for hierarchical memory management
+ */
+
+/**
+ * @typedef {import("./types.js").EverMemOSConfig} EverMemOSConfig
+ * @typedef {import("./types.js").Logger} Logger
+ * @typedef {import("./types.js").SubagentInfo} SubagentInfo
+ */
+
+/**
+ * Handles subagent lifecycle tracking
+ * Enables hierarchical memory management across parent and child agent conversations
+ */
+export class SubagentTracker {
+  /**
+   * @param {EverMemOSConfig} cfg
+   * @param {Logger} logger
+   */
+  constructor(cfg, logger) {
+    this.cfg = cfg;
+    this.log = logger;
+
+    /** @type {Map<string, SubagentInfo>} */
+    this.activeSubagents = new Map();
+  }
+
+  /**
+   * Register a new subagent
+   * @param {string} subagentId
+   * @param {Object} metadata
+   * @param {string} [metadata.subagentType]
+   * @param {number} [metadata.parentTurnCount]
+   */
+  register(subagentId, metadata = {}) {
+    this.activeSubagents.set(subagentId, {
+      startTime: Date.now(),
+      ...metadata,
+    });
+    this.log(`[evermemos] subagent tracker: registered ${subagentId}`);
+  }
+
+  /**
+   * Unregister a subagent
+   * @param {string} subagentId
+   * @returns {boolean} - True if subagent was found and removed
+   */
+  unregister(subagentId) {
+    const removed = this.activeSubagents.delete(subagentId);
+    if (removed) {
+      this.log(`[evermemos] subagent tracker: unregistered ${subagentId}`);
+    }
+    return removed;
+  }
+
+  /**
+   * Get active subagent count
+   * @returns {number}
+   */
+  getActiveCount() {
+    return this.activeSubagents.size;
+  }
+
+  /**
+   * Check if a subagent is active
+   * @param {string} subagentId
+   * @returns {boolean}
+   */
+  isActive(subagentId) {
+    return this.activeSubagents.has(subagentId);
+  }
+
+  /**
+   * Get info for a specific subagent
+   * @param {string} subagentId
+   * @returns {SubagentInfo|undefined}
+   */
+  getInfo(subagentId) {
+    return this.activeSubagents.get(subagentId);
+  }
+
+  /**
+   * Get all active subagent IDs
+   * @returns {string[]}
+   */
+  getActiveIds() {
+    return Array.from(this.activeSubagents.keys());
+  }
+
+  /**
+   * Clean up stale subagents (older than specified duration)
+   * @param {number} maxAgeMs - Maximum age in milliseconds (default: 1 hour)
+   * @returns {string[]} - List of cleaned up subagent IDs
+   */
+  cleanup(maxAgeMs = 60 * 60 * 1000) {
+    const now = Date.now();
+    const stale = [];
+
+    for (const [id, info] of this.activeSubagents.entries()) {
+      if (now - info.startTime > maxAgeMs) {
+        stale.push(id);
+      }
+    }
+
+    for (const id of stale) {
+      this.unregister(id);
+    }
+
+    if (stale.length > 0) {
+      this.log(`[evermemos] subagent tracker: cleaned up ${stale.length} stale subagents`);
+    }
+
+    return stale;
+  }
+}

package/src/types.js

@@ -0,0 +1,107 @@
+/**
+ * JSDoc type definitions for EverMemOS ContextEngine
+ * This file contains type definitions used across all ContextEngine modules
+ */
+
+/**
+ * @typedef {Object} EverMemOSConfig
+ * @property {string} serverUrl - EverMemOS server URL (e.g., "http://localhost:1995")
+ * @property {string} userId - User ID for memory storage
+ * @property {string} groupId - Group ID for shared memory
+ * @property {number} topK - Number of memories to retrieve
+ * @property {string[]} memoryTypes - Memory types to retrieve (episodic_memory, profile, agent_skill, agent_case)
+ * @property {string} retrieveMethod - Retrieval strategy (keyword, vector, hybrid, agentic)
+ */
+
+/**
+ * @typedef {Object} Logger
+ * @property {(...args: any[]) => void} log - Info level logging
+ * @property {(...args: any[]) => void} warn - Warning level logging
+ * @property {(...args: any[]) => void} error - Error level logging
+ */
+
+/**
+ * @typedef {Object} BootstrapContext
+ * @property {Object} api - OpenClaw API object
+ * @property {EverMemOSConfig} pluginConfig - Plugin configuration
+ */
+
+/**
+ * @typedef {Object} AssembleContext
+ * @property {string|Array} prompt - Current user prompt (can be string or content blocks)
+ * @property {Array} messages - Full conversation history
+ * @property {string} [sessionId] - Optional session identifier
+ */
+
+/**
+ * @typedef {Object} AssembleResult
+ * @property {string} context - Formatted context string to prepend
+ * @property {Object} metadata - Metadata about the assembly
+ * @property {number} [metadata.memoryCount] - Number of memories retrieved
+ * @property {string} [metadata.retrieveMethod] - Method used for retrieval
+ * @property {number} [metadata.turnCount] - Current turn number
+ * @property {string} [metadata.skipped] - Reason if assembly was skipped
+ * @property {string} [metadata.error] - Error message if failed
+ */
+
+/**
+ * @typedef {Object} AfterTurnContext
+ * @property {Array} messages - Messages from the completed turn
+ * @property {boolean} success - Whether the turn completed successfully
+ * @property {string} [errorMessage] - Error message if turn failed
+ */
+
+/**
+ * @typedef {Object} CompactContext
+ * @property {Array} messages - Current session messages
+ * @property {number} tokenCount - Estimated token count of context
+ * @property {string} [sessionId] - Optional session identifier
+ */
+
+/**
+ * @typedef {Object} CompactResult
+ * @property {boolean} shouldCompact - Whether compaction is recommended
+ * @property {string} reason - Explanation of the decision
+ * @property {Object} [metadata] - Additional metadata
+ * @property {string} [metadata.memoryStrategy] - Suggested memory consolidation strategy
+ * @property {number} [metadata.turnCount] - Turn count at evaluation time
+ */
+
+/**
+ * @typedef {Object} PrepareSubagentContext
+ * @property {string} subagentId - Unique identifier for the subagent
+ * @property {string|Array} prompt - Prompt for the subagent
+ * @property {Array} parentMessages - Parent agent's conversation history
+ * @property {string} [subagentType] - Type of subagent being spawned
+ */
+
+/**
+ * @typedef {Object} PrepareSubagentResult
+ * @property {string} prependContext - Context to prepend to subagent prompt
+ * @property {Object} metadata - Metadata about the preparation
+ * @property {string} [metadata.subagentId] - Subagent identifier
+ * @property {number} [metadata.parentTurnCount] - Parent's turn count
+ */
+
+/**
+ * @typedef {Object} SubagentEndedContext
+ * @property {string} subagentId - Unique identifier for the subagent
+ * @property {Array} messages - Messages from the subagent conversation
+ * @property {boolean} success - Whether the subagent completed successfully
+ * @property {string} [errorMessage] - Error message if subagent failed
+ */
+
+/**
+ * @typedef {Object} ParsedMemoryResponse
+ * @property {Array<{text: string, timestamp: number|string|null}>} episodic - Episodic memories
+ * @property {Array<{text: string, kind: string}>} traits - Profile traits
+ * @property {Object|null} case - Top agent case memory
+ * @property {Object|null} skill - Top agent skill memory
+ */
+
+/**
+ * @typedef {Object} SubagentInfo
+ * @property {number} startTime - Subagent spawn timestamp
+ * @property {string} [subagentType] - Type of subagent
+ * @property {number} [parentTurnCount] - Parent's turn count at spawn
+ */