@evermind-ai/openclaw-plugin 1.1.0

package/src/context-engine.js

@@ -0,0 +1,283 @@
+/**
+ * EverMemOS ContextEngine Implementation for OpenClaw 3.8+
+ * Implements full-lifecycle memory management: bootstrap, assemble, afterTurn, compact, subagent
+ */
+
+import { resolveConfig } from "./config.js";
+import { toText, isSessionResetPrompt, collectMessages } from "./message-utils.js";
+import { ContextAssembler } from "./assembler.js";
+import { LifecycleManager } from "./lifecycle.js";
+import { CompactionHandler } from "./compaction.js";
+import { SubagentTracker } from "./subagent.js";
+
+/**
+ * @typedef {import("./types.js").EverMemOSConfig} EverMemOSConfig
+ * @typedef {import("./types.js").Logger} Logger
+ * @typedef {import("./types.js").BootstrapContext} BootstrapContext
+ * @typedef {import("./types.js").AssembleContext} AssembleContext
+ * @typedef {import("./types.js").AssembleResult} AssembleResult
+ * @typedef {import("./types.js").AfterTurnContext} AfterTurnContext
+ * @typedef {import("./types.js").CompactContext} CompactContext
+ * @typedef {import("./types.js").CompactResult} CompactResult
+ * @typedef {import("./types.js").PrepareSubagentContext} PrepareSubagentContext
+ * @typedef {import("./types.js").PrepareSubagentResult} PrepareSubagentResult
+ * @typedef {import("./types.js").SubagentEndedContext} SubagentEndedContext
+ */
+
+/**
+ * EverMemOS ContextEngine implementation for OpenClaw 3.8+
+ * Implements full-lifecycle memory management: bootstrap, assemble, afterTurn, compact, subagent
+ */
+export class EverMemOSContextEngine {
+  /**
+   * @param {EverMemOSConfig} config
+   * @param {Logger} logger
+   */
+  constructor(config, logger = console) {
+    this.cfg = resolveConfig(config);
+    this.log = logger;
+
+    // Session state tracking
+    this.turnCount = 0;
+    this.lastAssembleTime = 0;
+    this.pendingFlush = false;
+
+    // Submodules
+    this.assembler = new ContextAssembler(this.cfg, this.log);
+    this.lifecycle = new LifecycleManager(this.cfg, this.log);
+    this.compaction = new CompactionHandler(this.cfg, this.log);
+    this.subagentTracker = new SubagentTracker(this.cfg, this.log);
+  }
+
+  /**
+   * Bootstrap: Called once when plugin loads. Initialize connection and verify backend health.
+   * @param {BootstrapContext} ctx
+   * @returns {Promise<void>}
+   */
+  async bootstrap(ctx) {
+    this.log("[evermemos] bootstrap: initializing EverMemOS connection");
+    try {
+      const result = await this._healthCheck();
+      if (result?.status === "ok") {
+        this.log("[evermemos] bootstrap: backend healthy");
+      } else {
+        this.log.warn("[evermemos] bootstrap: backend unhealthy, will degrade gracefully");
+      }
+    } catch (err) {
+      this.log.warn(`[evermemos] bootstrap: health check failed: ${err.message}`);
+    }
+  }
+
+  /**
+   * Assemble: Build context from memories before agent processes the prompt.
+   * This replaces the old before_agent_start hook with query-aware assembly.
+   * @param {AssembleContext} ctx
+   * @returns {Promise<AssembleResult>}
+   */
+  async assemble(ctx) {
+    const { prompt, messages } = ctx;
+    const query = toText(prompt);
+
+    // Detect session reset (/new, /reset)
+    if (isSessionResetPrompt(query)) {
+      this.log("[evermemos] assemble: session reset detected, skipping search");
+      this.pendingFlush = true;
+      return { context: "", metadata: { skipped: "session_reset" } };
+    }
+
+    if (!query || query.length < 3) {
+      return { context: "", metadata: { skipped: "empty_query" } };
+    }
+
+    try {
+      this.lastAssembleTime = Date.now();
+      const result = await this.assembler.assemble(query, messages, this.turnCount);
+      this.log(`[evermemos] assemble: retrieved ${result.memoryCount} memories`);
+      return {
+        context: result.context,
+        metadata: {
+          memoryCount: result.memoryCount,
+          retrieveMethod: this.cfg.retrieveMethod,
+          turnCount: this.turnCount,
+        },
+      };
+    } catch (err) {
+      this.log.warn(`[evermemos] assemble: ${err.message}`);
+      return { context: "", metadata: { error: err.message } };
+    }
+  }
+
+  /**
+   * AfterTurn: Called after each agent turn. Extract memories promptly.
+   * This enables timely extraction instead of waiting for agent_end.
+   * @param {AfterTurnContext} ctx
+   * @returns {Promise<void>}
+   */
+  async afterTurn(ctx) {
+    const { messages, success } = ctx;
+    this.turnCount++;
+
+    if (!success || !messages?.length) {
+      this.log(`[evermemos] afterTurn: turn ${this.turnCount} skipped (no success/messages)`);
+      return;
+    }
+
+    try {
+      const collected = collectMessages(messages);
+      if (!collected.length) {
+        this.log(`[evermemos] afterTurn: turn ${this.turnCount} - no messages to save`);
+        return;
+      }
+
+      await this.lifecycle.ingestTurn({
+        userId: this.cfg.userId,
+        groupId: this.cfg.groupId,
+        messages: collected,
+        turnCount: this.turnCount,
+        flush: this.pendingFlush,
+      });
+
+      this.log(`[evermemos] afterTurn: turn ${this.turnCount} - saved ${collected.length} messages`);
+
+      // Consume flush flag after successful save
+      if (this.pendingFlush) {
+        this.pendingFlush = false;
+        this.log("[evermemos] afterTurn: flush flag consumed");
+      }
+    } catch (err) {
+      this.log.warn(`[evermemos] afterTurn: ${err.message}`);
+    }
+  }
+
+  /**
+   * Compact: Participate in session compaction decision and memory consolidation.
+   * @param {CompactContext} ctx
+   * @returns {Promise<CompactResult>}
+   */
+  async compact(ctx) {
+    const { messages, tokenCount } = ctx;
+
+    this.log(`[evermemos] compact: evaluating compaction (tokens: ${tokenCount}, turns: ${this.turnCount})`);
+
+    try {
+      const decision = await this.compaction.evaluate({
+        messages,
+        tokenCount,
+        turnCount: this.turnCount,
+        lastAssembleTime: this.lastAssembleTime,
+      });
+
+      if (decision.shouldCompact) {
+        this.log(`[evermemos] compact: compaction recommended - ${decision.reason}`);
+        return {
+          shouldCompact: true,
+          reason: decision.reason,
+          metadata: {
+            turnCount: this.turnCount,
+            memoryStrategy: decision.memoryStrategy,
+          },
+        };
+      }
+
+      this.log("[evermemos] compact: no compaction needed");
+      return { shouldCompact: false, reason: decision.reason };
+    } catch (err) {
+      this.log.warn(`[evermemos] compact: ${err.message}`);
+      return { shouldCompact: false, reason: "error evaluating compaction" };
+    }
+  }
+
+  /**
+   * PrepareSubagentSpawn: Called before spawning a subagent.
+   * @param {PrepareSubagentContext} ctx
+   * @returns {Promise<PrepareSubagentResult>}
+   */
+  async prepareSubagentSpawn(ctx) {
+    const { subagentId, parentMessages } = ctx;
+
+    this.log(`[evermemos] prepareSubagentSpawn: tracking subagent ${subagentId}`);
+
+    // Register the subagent
+    this.subagentTracker.register(subagentId, {
+      subagentType: ctx.subagentType,
+      parentTurnCount: this.turnCount,
+    });
+
+    try {
+      // Collect relevant memories for the subagent
+      const query = toText(ctx.prompt);
+      const context = query
+        ? await this.assembler.assembleForSubagent(query)
+        : "";
+
+      return {
+        prependContext: context || "",
+        metadata: {
+          subagentId,
+          parentTurnCount: this.turnCount,
+        },
+      };
+    } catch (err) {
+      this.log.warn(`[evermemos] prepareSubagentSpawn: ${err.message}`);
+      return { prependContext: "", metadata: {} };
+    }
+  }
+
+  /**
+   * OnSubagentEnded: Called after a subagent completes.
+   * @param {SubagentEndedContext} ctx
+   * @returns {Promise<void>}
+   */
+  async onSubagentEnded(ctx) {
+    const { subagentId, messages, success } = ctx;
+
+    this.log(`[evermemos] onSubagentEnded: subagent ${subagentId} ended, success=${success}`);
+
+    // Unregister the subagent
+    this.subagentTracker.unregister(subagentId);
+
+    try {
+      if (success && messages?.length) {
+        const collected = collectMessages(messages);
+        if (collected.length) {
+          await this.lifecycle.ingestTurn({
+            userId: this.cfg.userId,
+            groupId: this.cfg.groupId,
+            messages: collected,
+            turnCount: this.turnCount,
+            flush: false,
+          });
+          this.log(`[evermemos] onSubagentEnded: saved ${collected.length} messages from subagent`);
+        }
+      }
+    } catch (err) {
+      this.log.warn(`[evermemos] onSubagentEnded: ${err.message}`);
+    }
+  }
+
+  /**
+   * Internal: Verify backend health
+   * @private
+   * @returns {Promise<{status: string}|null>}
+   */
+  async _healthCheck() {
+    const { serverUrl } = this.cfg;
+    try {
+      const controller = new AbortController();
+      const timeout = setTimeout(() => controller.abort(), 5000);
+
+      const response = await fetch(`${serverUrl}/api/v0/health`, {
+        method: "GET",
+        signal: controller.signal,
+      });
+      clearTimeout(timeout);
+
+      if (response.ok) {
+        return await response.json();
+      }
+      return { status: "error", httpStatus: response.status };
+    } catch {
+      return { status: "error" };
+    }
+  }
+}

package/src/formatter.js

@@ -0,0 +1,152 @@
+export const CONTEXT_BOUNDARY = "user\u200b原\u200b始\u200bquery\u200b：\u200b\u200b\u200b\u200b";
+
+function timestampToLabel(ts) {
+  if (ts == null || ts === "") return "";
+
+  if (typeof ts === "number") {
+    const d = new Date(ts);
+    if (Number.isNaN(d.getTime())) return "";
+    const p = (n) => `${n}`.padStart(2, "0");
+    return `${d.getFullYear()}-${p(d.getMonth() + 1)}-${p(d.getDate())} ${p(d.getHours())}:${p(d.getMinutes())}`;
+  }
+
+  if (typeof ts === "string") {
+    const s = ts.trim();
+    if (!s) return "";
+    // Unix epoch as string
+    if (/^\d{10,13}$/.test(s)) return timestampToLabel(Number(s));
+    // ISO 8601: extract date and HH:MM
+    const dateEnd = s.indexOf("T");
+    if (dateEnd === 10 && s.length > 15) return `${s.slice(0, 10)} ${s.slice(11, 16)}`;
+    return s;
+  }
+
+  return "";
+}
+
+export function parseSearchResponse(raw) {
+  if (raw?.status !== "ok" || !raw?.result) return null;
+
+  const allMemories = raw.result.memories ?? [];
+
+  // episodic memories
+  const episodic = allMemories
+    .filter((m) => m.memory_type === "episodic_memory" && (m.score ?? 0) >= 0.1)
+    .map((m) => {
+      const body = m.summary || m.episode || m.content || "";
+      const subject = m.subject || "";
+      return {
+        text: subject ? `${subject}: ${body}` : body,
+        timestamp: m.timestamp ?? null,
+      };
+    });
+
+  const traits = (raw.result.profiles ?? []).filter((p) => (p.score ?? 0) >= 0.1).map((p) => {
+    const label = p.category || p.trait_name || "";
+    let kind = p.item_type || "";
+    if (kind === "explicit_info") kind = "explicit";
+    else if (kind === "implicit_trait") kind = "implicit";
+    return {
+      text: label ? `[${label}] ${p.description || ""}` : (p.description || ""),
+      kind,
+    };
+  });
+
+  // agent_case: top 1 by score (min 0.01)
+  const topCase = allMemories
+    .filter((m) => m.memory_type === "agent_case" && (m.score ?? 0) >= 0.01)
+    .sort((a, b) => (b.score ?? 0) - (a.score ?? 0))[0] || null;
+
+  // agent_skill: top 1 by score (min 0.01)
+  const topSkill = allMemories
+    .filter((m) => m.memory_type === "agent_skill" && (m.score ?? 0) >= 0.01)
+    .sort((a, b) => (b.score ?? 0) - (a.score ?? 0))[0] || null;
+
+  return { episodic, traits, case: topCase, skill: topSkill };
+}
+
+function oneLiner(text) {
+  return text == null ? "" : String(text).replace(/[\r\n]+/g, " ").trim();
+}
+
+function factLine(fact) {
+  const t = oneLiner(fact.text);
+  if (!t) return "";
+  const when = timestampToLabel(fact.timestamp);
+  return when ? `  - [${when}] ${t}` : `  - ${t}`;
+}
+
+function traitLine(trait) {
+  const t = oneLiner(trait.text);
+  if (!t) return "";
+  const k = trait.kind?.toLowerCase() ?? "";
+  const badge = k.includes("explicit") ? " [Explicit]"
+    : k.includes("implicit") ? " [Implicit]"
+    : trait.kind ? ` [${trait.kind.replace(/[_-]+/g, " ").replace(/\b\w/g, (c) => c.toUpperCase())}]`
+    : "";
+  return `  -${badge} ${t}`;
+}
+
+function caseBlock(c) {
+  if (!c) return [];
+  const intent = oneLiner(c.task_intent || "");
+  const approach = c.approach || "";
+  if (!intent && !approach) return [];
+  const when = timestampToLabel(c.timestamp ?? c.created_at ?? null);
+  return [
+    "  <case>",
+    ...(when ? [`    - time: ${when}`] : []),
+    ...(intent ? [`    - intent: ${intent}`] : []),
+    ...(approach ? [`    - approach: ${approach}`] : []),
+    "  </case>",
+  ];
+}
+
+function skillBlock(s) {
+  if (!s) return [];
+  const name = oneLiner(s.name || "");
+  const desc = oneLiner(s.description || "");
+  const content = s.content || "";
+  if (!name && !content) return [];
+  return [
+    "  <skill>",
+    ...(name ? [`    - name: ${name}`] : []),
+    ...(desc ? [`    - description: ${desc}`] : []),
+    ...(content ? [`    - content: ${content}`] : []),
+    "  </skill>",
+  ];
+}
+
+export function buildMemoryPrompt(parsed, opts = {}) {
+  if (!parsed) return "";
+
+  const episodicLines = parsed.episodic.map(factLine).filter(Boolean);
+  const traitLines = parsed.traits.map(traitLine).filter(Boolean);
+  const caseLines = caseBlock(parsed.case);
+  const skillLines = skillBlock(parsed.skill);
+
+  if (!episodicLines.length && !traitLines.length && !caseLines.length && !skillLines.length) return "";
+
+  const xmlBlock = [
+    "<memory>",
+    ...(episodicLines.length ? ["  <episodic>", ...episodicLines, "  </episodic>"] : []),
+    ...(traitLines.length ? ["  <trait>", ...traitLines, "  </trait>"] : []),
+    ...(caseLines.length ? ["  <!-- Similar past case. Use as reference if applicable to the current task. -->", ...caseLines] : []),
+    ...(skillLines.length ? ["  <!-- Relevant skill. Use as reference if applicable to the current task. -->", ...skillLines] : []),
+    "</memory>",
+  ];
+
+  const memSection = opts.wrapInCodeBlock ? ["```text", ...xmlBlock, "```"] : xmlBlock;
+  const nowLabel = timestampToLabel(Date.now());
+
+  return [
+    "Note: Reference memory below. Build on past successes; avoid repeating failed approaches.",
+    ...(nowLabel ? [`- Time: ${nowLabel}`] : []),
+    "",
+    ...memSection,
+    "",
+    "**Note**: for memory, please not read from or write to local `MEMORY.md` or `memory/*` files as they are provided above.",
+    "",
+    CONTEXT_BOUNDARY,
+  ].join("\n");
+}

package/src/http-client.js

@@ -0,0 +1,46 @@
+import { setTimeout as sleep } from "node:timers/promises";
+import { TIMEOUT_MS } from "./config.js";
+
+function buildUrl(base, path, params) {
+  const qs = new URLSearchParams();
+  for (const [k, v] of Object.entries(params ?? {})) {
+    if (v == null || v === "") continue;
+    if (Array.isArray(v)) {
+      v.filter((x) => x != null && x !== "").forEach((x) => qs.append(k, String(x)));
+    } else {
+      qs.set(k, String(v));
+    }
+  }
+  const q = qs.toString();
+  return q ? `${base}${path}?${q}` : `${base}${path}`;
+}
+
+async function send(url, method, headers, body, timeoutMs) {
+  const ac = new AbortController();
+  const t = setTimeout(() => ac.abort(new Error(`timed out after ${timeoutMs}ms`)), timeoutMs);
+  try {
+    const res = await fetch(url, { method, headers, body, signal: ac.signal });
+    if (!res.ok) {
+      const msg = await res.text().catch(() => "");
+      throw new Error(`HTTP ${res.status}${msg ? ` – ${msg.slice(0, 200)}` : ""}`);
+    }
+    return res.json();
+  } finally {
+    clearTimeout(t);
+  }
+}
+
+export async function request(cfg, method, path, params) {
+  const headers = { "Content-Type": "application/json" };
+  // GET and DELETE use query string, POST uses body
+  const url = (method === "GET" || method === "DELETE") ? buildUrl(cfg.serverUrl, path, params) : `${cfg.serverUrl}${path}`;
+  const body = method === "POST" && params ? JSON.stringify(params) : undefined;
+  const ms = TIMEOUT_MS;
+
+  try {
+    return await send(url, method, headers, body, ms);
+  } catch {
+    await sleep(150);
+    return send(url, method, headers, body, ms);
+  }
+}

package/src/lifecycle.js

@@ -0,0 +1,65 @@
+/**
+ * Lifecycle Manager Module
+ * Handles turn-level memory ingestion
+ */
+
+import { saveMemories } from "./memory-api.js";
+
+/**
+ * @typedef {import("./types.js").EverMemOSConfig} EverMemOSConfig
+ * @typedef {import("./types.js").Logger} Logger
+ */
+
+/**
+ * Turn ingestion parameters
+ * @typedef {Object} IngestTurnParams
+ * @property {string} userId
+ * @property {string} groupId
+ * @property {Array} messages
+ * @property {number} turnCount
+ * @property {boolean} flush
+ */
+
+/**
+ * Handles turn-level memory ingestion
+ * Extracts and saves memories after each conversation turn
+ */
+export class LifecycleManager {
+  /**
+   * @param {EverMemOSConfig} cfg
+   * @param {Logger} logger
+   */
+  constructor(cfg, logger) {
+    this.cfg = cfg;
+    this.log = logger;
+  }
+
+  /**
+   * Ingest messages from a single turn
+   * @param {IngestTurnParams} params
+   * @returns {Promise<void>}
+   */
+  async ingestTurn({ userId, groupId, messages, turnCount, flush }) {
+    await saveMemories(this.cfg, {
+      userId,
+      groupId,
+      messages,
+      flush,
+    });
+  }
+
+  /**
+   * Flush pending memories to storage
+   * Called when session ends or reset is detected
+   * @returns {Promise<void>}
+   */
+  async flush() {
+    // Force save with flush=true
+    await saveMemories(this.cfg, {
+      userId: this.cfg.userId,
+      groupId: this.cfg.groupId,
+      messages: [],
+      flush: true,
+    });
+  }
+}

package/src/memory-api.js

@@ -0,0 +1,77 @@
+import { request } from "./http-client.js";
+
+export async function searchMemories(cfg, params) {
+  const { memory_types, ...baseParams } = params;
+
+  const episodicTypes = (memory_types ?? []).filter((t) => t === "episodic_memory" || t === "profile");
+  const caseTypes = (memory_types ?? []).filter((t) => t === "agent_case" || t === "agent_skill");
+
+  const searches = [];
+  if (episodicTypes.length) searches.push({ label: "episodic+profile", types: episodicTypes });
+  if (caseTypes.length) searches.push({ label: "case+skill", types: caseTypes });
+
+  const results = await Promise.all(
+    searches.map(async ({ label, types }) => {
+      const p = { ...baseParams, memory_types: types };
+      console.log("[memory-api] GET /api/v1/memories/search", label, JSON.stringify(p));
+      const r = await request(cfg, "GET", "/api/v1/memories/search", p);
+      console.log("[memory-api] GET response", label, JSON.stringify(r));
+      return r;
+    }),
+  );
+
+  // merge into a single response in order: episodic/profile first, then case/skill
+  const merged = {
+    status: "ok",
+    result: {
+      profiles: [],
+      memories: [],
+    },
+  };
+  for (const r of results) {
+    if (r?.result?.profiles?.length) merged.result.profiles.push(...r.result.profiles);
+    if (r?.result?.memories?.length) merged.result.memories.push(...r.result.memories);
+  }
+  return merged;
+}
+
+export async function saveMemories(cfg, { userId, groupId, messages = [], flush = false }) {
+  if (!messages.length) return;
+  const stamp = Date.now();
+  for (let i = 0; i < messages.length; i++) {
+    const { role = "user", content = "", tool_calls, tool_call_id } = messages[i];
+    const sender = role === "assistant" ? role : (role === "tool" ? "tool" : userId);
+    const isLast = i === messages.length - 1;
+
+    const payload = {
+      message_id: `em_${stamp}_${i}`,
+      create_time: new Date().toISOString(),
+      role,
+      sender,
+      sender_name: sender,
+      content,
+      group_id: groupId,
+      group_name: groupId,
+      scene: "assistant",
+      raw_data_type: "AgentConversation",
+      ...(tool_calls && { tool_calls }),
+      ...(tool_call_id && { tool_call_id }),
+      ...(flush && isLast && { flush: true }),
+    };
+    console.log("[memory-api] POST /api/v1/memories", JSON.stringify(payload));
+    const result = await request(cfg, "POST", "/api/v1/memories", payload);
+    console.log("[memory-api] POST response", JSON.stringify(result));
+  }
+}
+
+export async function deleteMemories(cfg, { memoryId, userId, groupId }) {
+  const payload = {};
+  if (memoryId) payload.memory_id = memoryId;
+  if (userId) payload.user_id = userId;
+  if (groupId) payload.group_id = groupId;
+
+  console.log("[memory-api] DELETE /api/v1/memories", JSON.stringify(payload));
+  const result = await request(cfg, "DELETE", "/api/v1/memories", payload);
+  console.log("[memory-api] DELETE response", JSON.stringify(result));
+  return result;
+}