OpenClaw Integration

Copyconst provider = createProvider(cfg, api);
const lifecycle = createMemoryLifecycle();
lifecycle.beginSession();
 
// Create Backend instance — PlatformBackend for platform mode, providerToBackend adapter for OSS
let backend: Backend;
if (cfg.mode === "platform") {
  backend = new PlatformBackend({
    apiKey: cfg.apiKey!,
    baseUrl: cfg.baseUrl ?? "https://api.mem0.ai",
  });
} else {
  backend = providerToBackend(provider, cfg.userId);
}
 

Copy */
const SKIP_TRIGGERS = new Set(["cron", "heartbeat", "automation", "schedule"]);
 
/**
 * Returns true if the session trigger is non-interactive and memory
 * hooks should be skipped entirely.
 *
 * Also detects cron-style session keys (e.g. "agent:main:cron:<id>")
 * as a fallback when the trigger field is not set.
 */
export function isNonInteractiveTrigger(
  trigger: string | undefined,
  sessionKey: string | undefined,
): boolean {
  if (trigger && SKIP_TRIGGERS.has(trigger.toLowerCase())) return true;
 
  // Fallback: detect cron/heartbeat from the session key pattern
  if (sessionKey) {
    if (/:cron:/i.test(sessionKey) || /:heartbeat:/i.test(sessionKey))
      return true;
  }
 
  return false;
}

Copyexport function registerAllTools(deps: ToolDeps): void {
  const { api } = deps;
  const nonOptional = { optional: false };
 
  api.registerTool(createMemorySearchTool(deps), nonOptional);
  api.registerTool(createMemoryAddTool(deps), nonOptional);
  api.registerTool(createMemoryGetTool(deps), nonOptional);
  api.registerTool(createMemoryListTool(deps), nonOptional);
  api.registerTool(createMemoryUpdateTool(deps), nonOptional);
  api.registerTool(createMemoryDeleteTool(deps), nonOptional);
  api.registerTool(createMemoryEventListTool(deps), nonOptional);
  api.registerTool(createMemoryEventStatusTool(deps), nonOptional);
}

Copyif (scope === "session") {
  if (currentSessionId) {
    results = await provider.search(query, applyFilters(buildSearchOptions(uid, limit, undefined, currentSessionId)));
  }
} else if (scope === "long-term") {
  results = await provider.search(query, applyFilters(buildSearchOptions(uid, limit)));
} else {
  const longTerm = await provider.search(query, applyFilters(buildSearchOptions(uid, limit)));
  let session: MemoryItem[] = [];
  if (currentSessionId) {
    session = await provider.search(query, applyFilters(buildSearchOptions(uid, limit, undefined, currentSessionId)));
  }
  const seen = new Set(longTerm.map((r) => r.id));
  results = [...longTerm, ...session.filter((r) => !seen.has(r.id))];
}

Copytry {
  const memory = await provider.get(memoryId);
  deps.captureToolEvent("memory_get", { success: true, latency_ms: Date.now() - start });
  return {
    content: [{ type: "text", text: `Memory ${memory.id}:\n${memory.memory}\n\nCreated: ${memory.created_at ?? "unknown"}\nUpdated: ${memory.updated_at ?? "unknown"}` }],
    details: { memory },
  };

Copyconst allFacts = rawFacts
  .map((f) => stripNoiseFromContent(f))
  .filter((f) => f.length > 0 && !isNoiseMessage(f));
 
if (allFacts.length === 0) {
  return { content: [{ type: "text", text: "All provided facts were filtered as noise. Nothing stored." }], details: { error: "all_noise" } };
}

Copyif (isSubagentSession(getCurrentSessionId())) {
  return { content: [{ type: "text", text: "Memory update is not available in subagent sessions." }], details: { error: "subagent_blocked" } };
}

Copyexport function sanitizeQuery(raw: string): string {
  let cleaned = raw.replace(
    /Sender\s*\(untrusted metadata\):\s*```json[\s\S]*?```\s*/gi,
    "",
  );
  cleaned = cleaned.replace(/^\[.*?\]\s*/g, "");
  cleaned = cleaned.trim();
  return cleaned || raw;
}
 
// ============================================================================
// Public API
// ============================================================================
 
/**
 * Perform token-budgeted, category-ranked recall.
 */
export async function recall(
  provider: Mem0Provider,
  query: string,
  userId: string,
  config: SkillsConfig = {},
  sessionId?: string,
): Promise<RecallResult> {
  const recallConfig = config.recall ?? {};
  const tokenBudget = recallConfig.tokenBudget ?? DEFAULT_TOKEN_BUDGET;
  const maxMemories = recallConfig.maxMemories ?? DEFAULT_MAX_MEMORIES;
  const threshold = recallConfig.threshold ?? DEFAULT_THRESHOLD;
  const categoryOrder = recallConfig.categoryOrder ?? DEFAULT_CATEGORY_ORDER;
  const identityAlwaysInclude = recallConfig.identityAlwaysInclude !== false;
 
  // Build search options (v3.0.0: keyword_search, reranking, filter_memories removed)
  const searchOpts: SearchOptions = {
    user_id: userId,
    top_k: maxMemories * 2, // Over-fetch for ranking
    threshold,
    source: "OPENCLAW",
  };
 

Copy// Search session memories if we have a session
let sessionMemories: MemoryItem[] = [];
if (sessionId) {
  try {
    sessionMemories = await provider.search(cleanQuery, {
      ...searchOpts,
      run_id: sessionId,
      top_k: 5,
    });
  } catch {
    // Session search failure is non-critical
  }
}
 
// Deduplicate: session memories that are also in long-term
const longTermIds = new Set(longTermMemories.map((m) => m.id));
const uniqueSession = sessionMemories.filter((m) => !longTermIds.has(m.id));
 

Copyfunction getMemoryCategory(memory: MemoryItem): string {
  // Check metadata first (skill-stored memories have explicit category)
  if (
    memory.metadata?.category &&
    typeof memory.metadata.category === "string"
  ) {
    return memory.metadata.category;
  }
  // Check categories array (mem0-extracted memories)
  if (memory.categories?.length) {
    return memory.categories[0];
  }
  return "uncategorized";
}
 
function getMemoryImportance(memory: MemoryItem): number {
  if (
    memory.metadata?.importance &&
    typeof memory.metadata.importance === "number"
  ) {
    return memory.metadata.importance;
  }
  // Default importance by category
  const cat = getMemoryCategory(memory);
  const defaults: Record<string, number> = {
    identity: 0.95,
    configuration: 0.95,
    rule: 0.9,
    preference: 0.85,
    decision: 0.8,
    technical: 0.8,
    relationship: 0.75,
    project: 0.75,
    operational: 0.6,
  };
  return defaults[cat] ?? 0.5;
}

Copyfunction rankMemories(
  memories: MemoryItem[],
  categoryOrder: string[],
): MemoryItem[] {
  const orderMap = new Map(categoryOrder.map((cat, i) => [cat, i]));
 
  return [...memories].sort((a, b) => {
    const catA = getMemoryCategory(a);
    const catB = getMemoryCategory(b);
    const orderA = orderMap.get(catA) ?? 999;
    const orderB = orderMap.get(catB) ?? 999;
 
    // Primary sort: category priority
    if (orderA !== orderB) return orderA - orderB;
 
    // Secondary sort: importance (higher first)
    const impA = getMemoryImportance(a);
    const impB = getMemoryImportance(b);
    if (impA !== impB) return impB - impA;
 
    // Tertiary sort: search relevance score
    return (b.score ?? 0) - (a.score ?? 0);
  });
}

Copy// Rough token estimate: ~4 chars per token for English text
const CHARS_PER_TOKEN = 4;

Copyfunction budgetMemories(
  rankedMemories: MemoryItem[],
  tokenBudget: number,
  maxMemories: number,
  identityAlwaysInclude: boolean,
): MemoryItem[] {
  const selected: MemoryItem[] = [];
  let usedTokens = 0;
 
  for (const memory of rankedMemories) {
    if (selected.length >= maxMemories) break;
 
    const memTokens = estimateTokens(memory.memory);
    const isIdentity =
      getMemoryCategory(memory) === "identity" ||
      getMemoryCategory(memory) === "configuration";
 
    // Identity/config always included if flag is set
    if (identityAlwaysInclude && isIdentity) {
      selected.push(memory);
      usedTokens += memTokens;
      continue;
    }
 
    // Budget check for non-identity memories
    if (usedTokens + memTokens > tokenBudget) continue;
 
    selected.push(memory);
    usedTokens += memTokens;
  }
 
  return selected;
}

Copy* Registers all `openclaw mem0 <subcommand>` commands:
*
* Memory:
*   - add         : Add a memory from text (--user-id, --agent-id)
*   - search      : Search memories (--top-k, --scope, --agent-id, --user-id)
*   - get         : Get a specific memory by ID
*   - list        : List memories with optional filters (--user-id, --agent-id, --top-k)
*   - update      : Update a memory's text
*   - delete      : Delete a memory or all memories (--all, --confirm)
*   - import      : Import memories from a JSON file
*
* Management:
*   - init        : Authenticate with Mem0 Platform (email or API key)
*   - status      : Check API connectivity and show current config
*   - config show : Display current plugin configuration
*   - config get  : Get a single config value
*   - config set  : Update a plugin config field
*   - event list  : List recent background events
*   - event status: Get status of a specific event
*

Copy* Plugin auth and settings are stored in ~/.openclaw/openclaw.json under
* plugins.entries.openclaw-mem0.config — the single source of truth.
*
* Uses fs-safe.ts for all filesystem operations to pass the OpenClaw
* code_safety scanner.
*/

Copyexport function buildOssLlmConfig(
  providerId: string,
  input: LlmConfigInput,
): { provider: string; config: Record<string, unknown> } {
  const def = LLM_PROVIDERS.find((p) => p.id === providerId);
  if (!def) throw new Error(`Unknown LLM provider: ${providerId}`);
 
  const config: Record<string, unknown> = {
    model: input.model || def.defaultModel,
  };
  if (input.apiKey) config.apiKey = input.apiKey;
  if (providerId === "ollama") {
    config.url = input.url || def.defaultUrl;
  }
  return { provider: providerId, config };
}

Copyexport const KNOWN_EMBEDDER_DIMS: Record<string, number> = {
  "text-embedding-3-small": 1536,
  "text-embedding-3-large": 3072,
  "text-embedding-ada-002": 1536,
  "nomic-embed-text": 768,
  "mxbai-embed-large": 1024,
  "all-minilm": 384,
  "snowflake-arctic-embed": 1024,
};
 
export function collectionNameForDims(dims: number): string {
  return `mem0_${dims}d`;
}

Copyexport function buildOssVectorConfig(
  providerId: string,
  input: VectorConfigInput,
): { provider: string; config: Record<string, unknown> } {
  const config: Record<string, unknown> = {};
 
  if (providerId === "qdrant") {
    config.url = input.url || "http://localhost:6333";
    config.onDisk = true;
    if (input.apiKey) config.apiKey = input.apiKey;
  } else if (providerId === "pgvector") {
    config.host = input.host || "localhost";
    config.port = parseInt(input.port || "5432", 10);
    if (input.user) config.user = input.user;
    if (input.password) config.password = input.password;
    config.dbname = input.dbname || "postgres";
  }
 
  if (input.dims) {
    config.dimension = input.dims;
    config.embeddingModelDims = input.dims;
    config.collectionName = collectionNameForDims(input.dims);
  }
  return { provider: providerId, config };
}

Copyexport async function checkOllamaConnectivity(url: string): Promise<{ ok: boolean; error?: string }> {
  try {
    const resp = await fetch(`${url.replace(/\/+$/, "")}/api/tags`, { signal: AbortSignal.timeout(3000) });
    if (resp.ok) return { ok: true };
    return { ok: false, error: `Ollama returned HTTP ${resp.status}` };
  } catch {
    return { ok: false, error: `Cannot reach Ollama at ${url}. Install: https://ollama.com/download` };
  }
}
 
export async function checkPgConnectivity(host: string, port: number): Promise<{ ok: boolean; error?: string }> {
  return new Promise((resolve) => {
    import("node:net").then(({ createConnection }) => {
      const sock = createConnection({ host, port, timeout: 3000 });
      sock.once("connect", () => { sock.destroy(); resolve({ ok: true }); });
      sock.once("timeout", () => { sock.destroy(); resolve({ ok: false, error: `PostgreSQL not reachable at ${host}:${port}` }); });
      sock.once("error", () => { sock.destroy(); resolve({ ok: false, error: `PostgreSQL not reachable at ${host}:${port}. Ensure PostgreSQL with pgvector extension is running.` }); });
    });
  });
}
 
export async function checkQdrantConnectivity(url: string): Promise<{ ok: boolean; error?: string }> {
  try {
    const resp = await fetch(`${url.replace(/\/+$/, "")}/healthz`, { signal: AbortSignal.timeout(3000) });
    if (resp.ok) return { ok: true };
    return { ok: false, error: `Qdrant returned HTTP ${resp.status}` };
  } catch (err) {
    return { ok: false, error: `Cannot reach Qdrant at ${url}. Start it with: docker run -d -p 6333:6333 qdrant/qdrant` };
  }
}