@alfe.ai/openclaw-memory-cloud 0.0.37 → 0.0.39

package/src/index.ts

@@ -1,464 +0,0 @@
-/**
- * memory-cloud — OpenClaw memory extension
- *
- * Replaces the builtin LanceDB memory extension with cloud-backed storage:
- * - Turbopuffer for vector storage (via services/memory Lambda proxy)
- * - DynamoDB for knowledge graph
- * - Haiku for classification + entity extraction
- *
- * Registers:
- * - Memory tools: memory_recall, memory_store, memory_forget, memory_navigate, memory_graph, memory_stats
- * - Lifecycle hooks: before_agent_start (auto-recall), agent_end (auto-capture), message_received (idle debounce)
- * - Memory runtime: replaces builtin SQLite backend with cloud backend
- */
-
-import * as fs from "node:fs/promises";
-import * as path from "node:path";
-import { resolveConfig } from "@alfe.ai/config";
-import { AgentApiClient, installToolErrorCapture } from "@alfe.ai/agent-api-client";
-import { AutoCapture } from "./auto-capture.js";
-import { AutoRecall } from "./auto-recall.js";
-import { formatSearchResults } from "./formatter.js";
-import { runSessionsBackfill } from "./session-backfill.js";
-import { resolveIngestEpoch } from "./ingest-epoch.js";
-import type { MemoryCloudConfig } from "./types.js";
-import { createRequire } from 'node:module';
-const require = createRequire(import.meta.url);
-const pkg = require('../package.json') as { version: string };
-
-// OpenClaw plugin types — these match the OpenClaw plugin API contract
-interface PluginApi {
-  pluginConfig?: Record<string, unknown>;
-  config: Record<string, unknown>;
-  logger: {
-    info: (msg: string, ctx?: Record<string, unknown>) => void;
-    debug: (msg: string, ctx?: Record<string, unknown>) => void;
-    warn: (msg: string, ctx?: Record<string, unknown>) => void;
-    error: (msg: string, ctx?: Record<string, unknown>) => void;
-  };
-  registerTool: (factory: (ctx: ToolContext) => Tool, opts?: { names?: string[] }) => void;
-  registerHook: (events: string | string[], handler: (...args: unknown[]) => unknown, opts?: { name?: string; description?: string }) => void;
-  on: (hookName: string, handler: (...args: unknown[]) => unknown, opts?: { priority?: number }) => void;
-  registerMemoryPromptSection: (builder: (params: { availableTools: Set<string> }) => string[]) => void;
-  registerMemoryRuntime: (runtime: unknown) => void;
-}
-
-interface ToolContext {
-  agentId?: string;
-  sessionKey?: string;
-  sessionId?: string;
-  messageChannel?: string;
-}
-
-interface Tool {
-  name: string;
-  label: string;
-  description: string;
-  parameters: Record<string, unknown>;
-  execute: (toolCallId: string, params: Record<string, unknown>) => Promise<unknown>;
-}
-
-
-
-const DEFAULT_CONFIG: MemoryCloudConfig = {
-  autoCapture: true,
-  autoRecall: true,
-  captureMaxChars: 500,
-  idleFlushSeconds: 60,
-  backfillSessions: true,
-  backfillMaxSessions: 50,
-};
-
-function resolvePluginConfig(pluginConfig?: Record<string, unknown>): MemoryCloudConfig {
-  return {
-    autoCapture: typeof pluginConfig?.autoCapture === "boolean" ? pluginConfig.autoCapture : DEFAULT_CONFIG.autoCapture,
-    autoRecall: typeof pluginConfig?.autoRecall === "boolean" ? pluginConfig.autoRecall : DEFAULT_CONFIG.autoRecall,
-    captureMaxChars: typeof pluginConfig?.captureMaxChars === "number" ? pluginConfig.captureMaxChars : DEFAULT_CONFIG.captureMaxChars,
-    idleFlushSeconds: typeof pluginConfig?.idleFlushSeconds === "number" ? pluginConfig.idleFlushSeconds : DEFAULT_CONFIG.idleFlushSeconds,
-    backfillSessions: typeof pluginConfig?.backfillSessions === "boolean" ? pluginConfig.backfillSessions : DEFAULT_CONFIG.backfillSessions,
-    backfillMaxSessions:
-      typeof pluginConfig?.backfillMaxSessions === "number" && Number.isFinite(pluginConfig.backfillMaxSessions) && pluginConfig.backfillMaxSessions > 0
-        ? Math.floor(pluginConfig.backfillMaxSessions)
-        : DEFAULT_CONFIG.backfillMaxSessions,
-  };
-}
-
-export default {
-  id: "@alfe.ai/openclaw-memory-cloud",
-  name: "Cloud Memory",
-  description: "Persistent agent memory backed by Turbopuffer + DynamoDB knowledge graph",
-  version: pkg.version,
-  kind: "memory" as const,
-
-  register(api: PluginApi): void {
-    // First thing, before any registerTool call: tool failures emit a
-    // deterministic [ERROR] line the gateway's runtime-output monitor captures
-    // to Sentry. See @alfe.ai/agent-api-client tool-error-capture.
-    installToolErrorCapture(api, { plugin: "openclaw-memory-cloud" });
-    const config = resolvePluginConfig(api.pluginConfig);
-    const logger = api.logger;
-
-    const alfeConfig = resolveConfig();
-    const client = new AgentApiClient({
-      apiKey: alfeConfig.apiKey,
-      apiUrl: alfeConfig.apiUrl,
-    });
-
-    // Strictly-monotonic per-boot epoch, resolved once at process start.
-    // Guards against a backward wall-clock step across a restart (which would
-    // otherwise trap every live-capture flush in the server's stale-boot
-    // branch and silently drop it). See ingest-epoch.ts.
-    const ingestEpoch = resolveIngestEpoch({ logger });
-    const autoCapture = new AutoCapture(client, config, logger, ingestEpoch);
-    const autoRecall = new AutoRecall(client, config, logger);
-
-    // ─── Memory prompt section ──────────────────────────────────
-    api.registerMemoryPromptSection(({ availableTools }) => {
-      const lines: string[] = ["## Memory"];
-      if (availableTools.has("memory_recall")) {
-        lines.push("Use memory_recall to search your conversation history and knowledge graph.");
-        lines.push("Results include structured facts (from knowledge graph) and relevant conversation excerpts.");
-      }
-      if (availableTools.has("memory_store")) {
-        lines.push("Use memory_store to explicitly save important information for future reference.");
-      }
-      if (availableTools.has("memory_learn")) {
-        lines.push("Use memory_learn when the user asks you to learn or remember something — or when you read a doc with durable facts. Pass the source text directly; the system auto-classifies and extracts entities.");
-      }
-      if (availableTools.has("memory_graph")) {
-        lines.push("Use memory_graph to look up what you know about a specific entity.");
-      }
-      return lines;
-    });
-
-    // ─── Tools ──────────────────────────────────────────────────
-    api.registerTool(() => ({
-      name: "memory_recall",
-      label: "Memory Recall",
-      description: "Search conversation memory and knowledge graph. Returns structured facts and relevant conversation excerpts.",
-      parameters: {
-        type: "object",
-        properties: {
-          query: { type: "string", description: "What to search for" },
-          limit: { type: "number", description: "Maximum results (default 10)" },
-          topic: { type: "string", description: "Filter by topic" },
-          tag: { type: "string", description: "Filter by tag (fact/decision/preference/event/discovery)" },
-        },
-        required: ["query"],
-      },
-      execute: async (_toolCallId: string, params: Record<string, unknown>) => {
-        const results = await client.memorySearch(
-          params.query as string,
-          {
-            limit: params.limit as number | undefined,
-            topic: params.topic as string | undefined,
-            tag: params.tag as string | undefined,
-          },
-        );
-        return formatSearchResults(results);
-      },
-    }), { names: ["memory_recall", "memory_search"] });
-
-    api.registerTool(() => ({
-      name: "memory_store",
-      label: "Memory Store",
-      description: "Explicitly save a piece of information to long-term memory.",
-      parameters: {
-        type: "object",
-        properties: {
-          text: { type: "string", description: "The information to remember" },
-          topic: { type: "string", description: "Topic category (e.g., person name, project)" },
-          tag: { type: "string", description: "Memory type: fact, decision, preference, event, discovery" },
-          importance: { type: "number", description: "Importance 0-1 (default 0.7)" },
-        },
-        required: ["text"],
-      },
-      execute: async (_toolCallId: string, params: Record<string, unknown>) => {
-        const result = await client.memoryStore(
-          params.text as string,
-          {
-            topic: params.topic as string | undefined,
-            tag: params.tag as string | undefined,
-            importance: params.importance as number | undefined,
-          },
-        );
-        return `Stored memory: ${result.memoryId}`;
-      },
-    }), { names: ["memory_store"] });
-
-    api.registerTool(() => ({
-      name: "memory_learn",
-      label: "Memory Learn",
-      description: "Save arbitrary content (a paragraph, a doc, a fact list) into long-term memory. The system auto-classifies and extracts entities. Use this when the user asks you to learn, remember, or study something — or when you read a document worth retaining. Pass the source text directly; do not paraphrase first.",
-      parameters: {
-        type: "object",
-        properties: {
-          content: { type: "string", description: "Inline text to ingest. Provide either content OR path, not both." },
-          path: { type: "string", description: "Workspace-relative file path to read and ingest. Provide either content OR path, not both." },
-          source: { type: "string", description: "Optional label describing where the content came from (e.g. doc title, url)." },
-        },
-      },
-      execute: async (_toolCallId: string, params: Record<string, unknown>) => {
-        const content = typeof params.content === "string" ? params.content : undefined;
-        const filePath = typeof params.path === "string" ? params.path : undefined;
-        const source = typeof params.source === "string" ? params.source : undefined;
-
-        if (!content && !filePath) {
-          return "Error: provide either `content` or `path`.";
-        }
-        if (content && filePath) {
-          return "Error: provide either `content` or `path`, not both.";
-        }
-
-        let text: string;
-        let resolvedSource = source;
-        let sourceType: "file" | "inline" = "inline";
-
-        if (filePath !== undefined) {
-          const cwd = process.cwd();
-          const resolved = path.resolve(cwd, filePath);
-          if (!resolved.startsWith(cwd + path.sep) && resolved !== cwd) {
-            return `Error: path "${filePath}" escapes the workspace.`;
-          }
-          try {
-            text = await fs.readFile(resolved, "utf8");
-          } catch (err) {
-            return `Error reading "${filePath}": ${err instanceof Error ? err.message : String(err)}`;
-          }
-          resolvedSource = source ?? filePath;
-          sourceType = "file";
-        } else if (content !== undefined) {
-          text = content;
-        } else {
-          return "Error: provide either `content` or `path`.";
-        }
-
-        try {
-          const result = await client.memoryLearn({ text, source: resolvedSource, sourceType });
-          const label = result.source ?? "content";
-          return `Stored ${String(result.memoriesStored)} memories (${String(result.triplesStored)} facts, ${String(result.chunks)} chunks) from ${label}.`;
-        } catch (err) {
-          logger.warn("memory_learn failed", { err: String(err) });
-          return `Error: failed to store memory — ${err instanceof Error ? err.message : String(err)}`;
-        }
-      },
-    }), { names: ["memory_learn"] });
-
-    api.registerTool(() => ({
-      name: "memory_forget",
-      label: "Memory Forget",
-      description: "Search for and delete memories matching a query.",
-      parameters: {
-        type: "object",
-        properties: {
-          query: { type: "string", description: "Search for memories to delete" },
-        },
-        required: ["query"],
-      },
-      execute: async (_toolCallId: string, params: Record<string, unknown>) => {
-        const results = await client.memorySearch(params.query as string, { limit: 5 });
-        if (results.memories.length === 0) return "No matching memories found.";
-
-        const deleted: string[] = [];
-        for (const mem of results.memories) {
-          try {
-            await client.memoryDelete(mem.id);
-            deleted.push(mem.id);
-          } catch {
-            logger.warn("Failed to delete memory", { memoryId: mem.id });
-          }
-        }
-        return `Deleted ${String(deleted.length)} of ${String(results.memories.length)} matching memories.`;
-      },
-    }), { names: ["memory_forget"] });
-
-    api.registerTool(() => ({
-      name: "memory_graph",
-      label: "Knowledge Graph",
-      description: "Look up what you know about a specific entity from the knowledge graph.",
-      parameters: {
-        type: "object",
-        properties: {
-          entity: { type: "string", description: "The entity to look up (person, concept, system)" },
-        },
-        required: ["entity"],
-      },
-      execute: async (_toolCallId: string, params: Record<string, unknown>) => {
-        const result = await client.memoryLookupEntity(params.entity as string);
-        if (result.triples.length === 0) return `No knowledge found about "${params.entity as string}".`;
-        const facts = result.triples.map((t) => `- ${result.subject} ${t.predicate} ${t.object} (since ${t.validFrom.slice(0, 10)})`);
-        return `Known facts about ${result.subject}:\n${facts.join("\n")}`;
-      },
-    }), { names: ["memory_graph"] });
-
-    api.registerTool(() => ({
-      name: "memory_stats",
-      label: "Memory Stats",
-      description: "Get memory storage statistics.",
-      parameters: { type: "object", properties: {} },
-      execute: async () => {
-        const s = await client.memoryStats();
-        return `Memories: ${String(s.vectorCount)}, Knowledge facts: ${String(s.tripleCount)}, Storage: ${String(Math.round(s.storageEstimateBytes / 1024))} KB`;
-      },
-    }), { names: ["memory_stats"] });
-
-    api.registerTool(() => ({
-      name: "memory_navigate",
-      label: "Memory Navigate",
-      description: "Browse your memory palace structure — list topics, subtopics, and memory counts.",
-      parameters: { type: "object", properties: {} },
-      execute: async () => {
-        const nav = await client.memoryNavigate();
-        const topics = nav.topics;
-        if (topics.length === 0) return "No memories stored yet.";
-        const lines = topics.map((t) => `- ${t.name} (${String(t.tripleCount)} facts, subtopics: ${t.subtopics.join(", ") || "none"})`);
-        return `Memory topics:\n${lines.join("\n")}`;
-      },
-    }), { names: ["memory_navigate"] });
-
-    // ─── Lifecycle hooks ────────────────────────────────────────
-
-    // Auto-recall: inject relevant memories at session start
-    api.on("before_agent_start", async (event: unknown, ctx: unknown) => {
-      const startEvent = event as Record<string, unknown>;
-      const agentCtx = ctx as Record<string, unknown>;
-      const prompt = typeof startEvent.prompt === "string" ? startEvent.prompt : "";
-      const sessionKey = typeof agentCtx.sessionKey === "string" ? agentCtx.sessionKey : undefined;
-      const channelId = typeof agentCtx.channelId === "string" ? agentCtx.channelId : undefined;
-
-      if (sessionKey) {
-        autoCapture.setSession(sessionKey, { channelId });
-      }
-
-      const contextXml = await autoRecall.loadForPrompt(prompt);
-      if (contextXml) {
-        return { prependContext: contextXml };
-      }
-      return undefined;
-    }, { priority: 10 });
-
-    // Track incoming messages for idle debounce
-    api.on("message_received", (event: unknown) => {
-      const msgEvent = event as Record<string, unknown>;
-      const content = typeof msgEvent.content === "string" ? msgEvent.content : "";
-      autoCapture.trackMessage("user", content);
-    });
-
-    // Track outgoing messages
-    api.on("message_sending", (event: unknown) => {
-      const msgEvent = event as Record<string, unknown>;
-      const content = typeof msgEvent.content === "string" ? msgEvent.content : "";
-      autoCapture.trackMessage("assistant", content);
-    });
-
-    // Final flush on session end
-    api.on("agent_end", async (event: unknown) => {
-      const endEvent = event as Record<string, unknown>;
-      if (endEvent.success !== false) {
-        await autoCapture.onAgentEnd();
-      }
-    });
-
-    // Fire-and-forget first-run sync: workspace files (MEMORY.md / memory/*.md)
-    // and pre-existing chat sessions, each idempotent via its own
-    // PalaceMetadata flag (bootstrapSyncedAt / sessionsBackfillSyncedAt).
-    void runStartupSync(client, config, logger).catch((err: unknown) => {
-      logger.warn("memory startup sync failed; will retry on next startup", { err: String(err) });
-    });
-
-    logger.info("memory-cloud extension registered", { autoCapture: config.autoCapture, autoRecall: config.autoRecall });
-  },
-};
-
-async function runStartupSync(
-  client: AgentApiClient,
-  config: MemoryCloudConfig,
-  logger: PluginApi["logger"],
-): Promise<void> {
-  // Fetch status ONCE, before the file bootstrap runs: the sessions backfill
-  // computes its dedup cutoff from the pre-bootstrap `syncedAt` (an agent
-  // that already had memory installed captured everything after that moment
-  // live, so backfilling past it would duplicate memories).
-  let status: { synced: boolean; syncedAt?: string; sessionsBackfillSynced?: boolean };
-  try {
-    status = await client.memoryBootstrapStatus();
-  } catch (err) {
-    logger.debug("memory bootstrap status check failed; skipping", { err: String(err) });
-    return;
-  }
-  const startupMs = Date.now();
-
-  if (status.synced) {
-    logger.debug("memory bootstrap: already synced, skipping");
-  } else {
-    try {
-      await runBootstrap(client, logger);
-    } catch (err) {
-      logger.warn("memory bootstrap failed; will retry on next startup", { err: String(err) });
-    }
-  }
-
-  // Strict `=== false` on purpose: an old server (deployed before the
-  // sessions-backfill release) omits the field entirely, and its mark
-  // endpoint would clobber `bootstrapSyncedAt` — corrupting the cutoff
-  // anchor. Defer until the service is deployed and reports the flag.
-  if (config.backfillSessions && status.sessionsBackfillSynced === false) {
-    const installedAtMs = status.syncedAt ? Date.parse(status.syncedAt) : Number.POSITIVE_INFINITY;
-    const cutoffMs = Math.min(startupMs, Number.isNaN(installedAtMs) ? Number.POSITIVE_INFINITY : installedAtMs);
-    await runSessionsBackfill(client, config, logger, { cutoffMs });
-  }
-}
-
-async function runBootstrap(
-  client: AgentApiClient,
-  logger: PluginApi["logger"],
-): Promise<void> {
-  const cwd = process.cwd();
-  const filesToSync: string[] = [];
-
-  try {
-    await fs.access(path.join(cwd, "MEMORY.md"));
-    filesToSync.push("MEMORY.md");
-  } catch { /* missing — fine */ }
-
-  try {
-    const memoryDir = path.join(cwd, "memory");
-    const entries = await fs.readdir(memoryDir, { withFileTypes: true });
-    for (const entry of entries) {
-      if (entry.isFile() && entry.name.endsWith(".md")) {
-        filesToSync.push(path.join("memory", entry.name));
-      }
-    }
-  } catch { /* no memory/ dir — fine */ }
-
-  if (filesToSync.length === 0) {
-    logger.debug("memory bootstrap: no files to sync, marking complete");
-    try { await client.memoryBootstrapStatusMark(); } catch { /* retry next start */ }
-    return;
-  }
-
-  logger.info("memory bootstrap: ingesting files", { count: filesToSync.length });
-
-  for (const relPath of filesToSync) {
-    try {
-      const text = await fs.readFile(path.join(cwd, relPath), "utf8");
-      if (text.trim().length === 0) continue;
-      const result = await client.memoryLearn({ text, source: relPath, sourceType: "file" });
-      logger.debug("memory bootstrap: file ingested", {
-        file: relPath,
-        memoriesStored: result.memoriesStored,
-        triplesStored: result.triplesStored,
-      });
-    } catch (err) {
-      logger.warn("memory bootstrap: file failed; will retry on next startup", { file: relPath, err: String(err) });
-      return;
-    }
-  }
-
-  try {
-    await client.memoryBootstrapStatusMark();
-    logger.info("memory bootstrap: complete");
-  } catch (err) {
-    logger.warn("memory bootstrap: mark failed; will retry on next startup", { err: String(err) });
-  }
-}

package/src/ingest-epoch.ts

@@ -1,78 +0,0 @@
-/**
- * Strictly-monotonic per-boot ingest epoch.
- *
- * Live `AutoCapture` stamps each flush with a boot epoch so the memory service
- * can tell a restarted daemon (whose message-index counter has reset to 0) from
- * a continuing one and reset the per-session high-water mark accordingly (see
- * services/memory/src/lib/ingest-offset.ts).
- *
- * `Date.now()` alone is NOT safe as that epoch: if the wall clock steps BACKWARD
- * across a restart (NTP correction, or a boot before NTP sync), the new
- * process's epoch would be LESS than the epoch already stored on the server —
- * and the server's `incomingEpoch < storedEpoch` branch classifies every such
- * flush as a stale-boot late delivery and acks it WITHOUT storing. That would
- * silently drop ALL live captures for the entire life of that process (worse
- * than the pre-fix bug, which self-healed once the counter climbed).
- *
- * The guard: persist the last epoch to a single small file and take
- * `max(Date.now(), lastEpoch + 1)`. This is strictly increasing regardless of
- * clock direction, needs no server round-trip, and is written exactly once per
- * boot (a single integer — NOT the per-message counter that made a local state
- * file unattractive for the message index itself).
- */
-
-import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
-import { dirname, join } from "node:path";
-import { homedir } from "node:os";
-
-/**
- * `~/.alfe` is the plugin's canonical local-state dir (config lives at
- * `~/.alfe/config.toml`, chat sessions at `~/.alfe/sessions/chat`), and
- * `alfe remove` wipes it — so the epoch never outlives the agent it belongs to.
- */
-const DEFAULT_EPOCH_FILE = join(homedir(), ".alfe", "memory", "ingest-epoch.json");
-
-export interface ResolveIngestEpochOptions {
-  /** Override the state-file path (tests). */
-  epochFile?: string;
-  /** Override the clock (tests). */
-  now?: number;
-  logger?: { warn: (msg: string, ctx?: Record<string, unknown>) => void };
-}
-
-function readLastEpoch(epochFile: string): number {
-  try {
-    const parsed: unknown = JSON.parse(readFileSync(epochFile, "utf8"));
-    if (typeof parsed === "object" && parsed !== null) {
-      const epoch = (parsed as Record<string, unknown>).epoch;
-      if (typeof epoch === "number" && Number.isFinite(epoch)) {
-        return epoch;
-      }
-    }
-  } catch {
-    // Missing or corrupt file → treat as no prior epoch.
-  }
-  return 0;
-}
-
-/**
- * Resolve and persist a strictly-monotonic epoch for this process. Best-effort:
- * if the state dir isn't writable the returned epoch is still `>= now` (correct
- * in the common forward-clock case), and the failure is logged, not thrown.
- */
-export function resolveIngestEpoch(opts: ResolveIngestEpochOptions = {}): number {
-  const epochFile = opts.epochFile ?? DEFAULT_EPOCH_FILE;
-  const now = opts.now ?? Date.now();
-
-  const last = readLastEpoch(epochFile);
-  const epoch = Math.max(now, last + 1);
-
-  try {
-    mkdirSync(dirname(epochFile), { recursive: true });
-    writeFileSync(epochFile, JSON.stringify({ epoch }));
-  } catch (err) {
-    opts.logger?.warn("memory ingest epoch: could not persist monotonic epoch; a backward clock across a future restart could drop captures", { err: String(err) });
-  }
-
-  return epoch;
-}