@alfe.ai/openclaw-memory-cloud 0.0.1

package/src/index.ts

@@ -0,0 +1,286 @@
+/**
+ * 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 { MemoryClient } from "./memory-client.js";
+import { AutoCapture } from "./auto-capture.js";
+import { AutoRecall } from "./auto-recall.js";
+import { formatSearchResults } from "./formatter.js";
+import type { MemoryCloudConfig } from "./types.js";
+
+// 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,
+};
+
+function resolveConfig(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,
+  };
+}
+
+export default {
+  id: "memory-cloud",
+  name: "Cloud Memory",
+  description: "Persistent agent memory backed by Turbopuffer + DynamoDB knowledge graph",
+  version: "0.1.0",
+  kind: "memory" as const,
+
+  register(api: PluginApi): void {
+    const config = resolveConfig(api.pluginConfig);
+    const logger = api.logger;
+
+    // Memory service URL from integration DESIRED_STATE config
+    const cfgUrl = api.pluginConfig?.memoryServiceUrl;
+    const cfgKey = api.pluginConfig?.agentApiKey;
+    const cfgAgent = api.pluginConfig?.agentId;
+    const memoryServiceUrl = typeof cfgUrl === "string" ? cfgUrl : "";
+    const agentApiKey = typeof cfgKey === "string" ? cfgKey : "";
+    const agentId = typeof cfgAgent === "string" ? cfgAgent : "";
+
+    if (!memoryServiceUrl) {
+      throw new Error("memory-cloud: memoryServiceUrl not configured — cannot register memory extension");
+    }
+
+    const client = new MemoryClient(memoryServiceUrl, agentApiKey, agentId);
+    const autoCapture = new AutoCapture(client, config, logger);
+    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_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.search(
+          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.store(
+          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_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.search(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.deleteMemory(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.lookupEntity(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.stats();
+        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.navigate() as { topics?: { name: string; tripleCount: number; subtopics: string[] }[] } | null;
+        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();
+      }
+    });
+
+    logger.info("memory-cloud extension registered", { autoCapture: config.autoCapture, autoRecall: config.autoRecall });
+  },
+};

package/src/memory-client.ts

@@ -0,0 +1,132 @@
+import type { MemorySearchResult, MemoryContext, MemoryMessage, SessionMetadata } from "./types.js";
+
+/**
+ * HTTP client for services/memory.
+ * All memory operations go through the Lambda service — no direct Turbopuffer/DynamoDB access.
+ */
+export class MemoryClient {
+  constructor(
+    private readonly baseUrl: string,
+    private readonly agentApiKey: string,
+    private readonly agentId: string,
+  ) {
+    if (!baseUrl) throw new Error("MemoryClient: baseUrl is required");
+  }
+
+  async search(query: string, opts?: {
+    limit?: number;
+    topic?: string;
+    subtopic?: string;
+    tag?: string;
+    includeKnowledge?: boolean;
+  }): Promise<MemorySearchResult> {
+    const resp = await this.post<{ data: MemorySearchResult }>("/memory/search", {
+      query,
+      limit: opts?.limit ?? 10,
+      topic: opts?.topic,
+      subtopic: opts?.subtopic,
+      tag: opts?.tag,
+      includeKnowledge: opts?.includeKnowledge ?? true,
+    });
+    return resp.data;
+  }
+
+  async store(text: string, opts?: {
+    topic?: string;
+    subtopic?: string;
+    tag?: string;
+    importance?: number;
+  }): Promise<{ memoryId: string }> {
+    const resp = await this.post<{ data: { memoryId: string } }>("/memory/store", {
+      text,
+      topic: opts?.topic ?? "general",
+      subtopic: opts?.subtopic ?? "general",
+      tag: opts?.tag ?? "fact",
+      importance: opts?.importance ?? 0.7,
+    });
+    return resp.data;
+  }
+
+  async ingest(sessionKey: string, messages: MemoryMessage[], metadata?: SessionMetadata): Promise<void> {
+    await this.post("/memory/ingest", {
+      agentId: this.agentId,
+      sessionKey,
+      lastProcessedIndex: messages.length > 0 ? messages[messages.length - 1].index : -1,
+      messages,
+      metadata,
+    });
+  }
+
+  async loadContext(tier: number, topicHint?: string): Promise<MemoryContext> {
+    const params = new URLSearchParams({ tier: String(tier) });
+    if (topicHint) params.set("topicHint", topicHint);
+    const resp = await this.get<{ data: MemoryContext }>(`/memory/context?${params.toString()}`);
+    return resp.data;
+  }
+
+  async lookupEntity(subject: string): Promise<{
+    subject: string;
+    triples: { tripleId: string; predicate: string; object: string; validFrom: string; validTo?: string; confidence: number }[];
+  }> {
+    const resp = await this.get<{ data: { subject: string; triples: { tripleId: string; predicate: string; object: string; validFrom: string; validTo?: string; confidence: number }[] } }>(
+      `/memory/knowledge/entities?subject=${encodeURIComponent(subject)}`,
+    );
+    return resp.data;
+  }
+
+  async navigate(): Promise<unknown> {
+    const resp = await this.get<{ data: unknown }>("/memory/navigate");
+    return resp.data;
+  }
+
+  async deleteMemory(memoryId: string): Promise<void> {
+    await this.del(`/memory/${encodeURIComponent(memoryId)}`);
+  }
+
+  async stats(): Promise<{ vectorCount: number; tripleCount: number; storageEstimateBytes: number }> {
+    const resp = await this.get<{ data: { vectorCount: number; tripleCount: number; storageEstimateBytes: number } }>("/memory/stats");
+    return resp.data;
+  }
+
+  private async post<T>(path: string, body: unknown): Promise<T> {
+    const resp = await fetch(`${this.baseUrl}${path}`, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        Authorization: `Bearer ${this.agentApiKey}`,
+        "x-agent-id": this.agentId,
+      },
+      body: JSON.stringify(body),
+    });
+    if (!resp.ok) {
+      throw new Error(`Memory API error: ${String(resp.status)} ${await resp.text()}`);
+    }
+    return resp.json() as Promise<T>;
+  }
+
+  private async get<T>(path: string): Promise<T> {
+    const resp = await fetch(`${this.baseUrl}${path}`, {
+      headers: {
+        Authorization: `Bearer ${this.agentApiKey}`,
+        "x-agent-id": this.agentId,
+      },
+    });
+    if (!resp.ok) {
+      throw new Error(`Memory API error: ${String(resp.status)} ${await resp.text()}`);
+    }
+    return resp.json() as Promise<T>;
+  }
+
+  private async del(path: string): Promise<void> {
+    const resp = await fetch(`${this.baseUrl}${path}`, {
+      method: "DELETE",
+      headers: {
+        Authorization: `Bearer ${this.agentApiKey}`,
+        "x-agent-id": this.agentId,
+      },
+    });
+    if (!resp.ok) {
+      throw new Error(`Memory API error: ${String(resp.status)} ${await resp.text()}`);
+    }
+  }
+}

package/src/types.ts

@@ -0,0 +1,47 @@
+export interface MemoryCloudConfig {
+  autoCapture: boolean;
+  autoRecall: boolean;
+  captureMaxChars: number;
+  idleFlushSeconds: number;
+}
+
+export interface MemoryMessage {
+  role: string;
+  content: string;
+  index: number;
+  timestamp?: string;
+}
+
+export interface SessionMetadata {
+  channelId?: string;
+  userId?: string;
+  userName?: string;
+}
+
+export interface MemorySearchResult {
+  facts: {
+    subject: string;
+    predicate: string;
+    object: string;
+    since: string;
+    confidence: number;
+  }[];
+  memories: {
+    id: string;
+    text: string;
+    topic: string;
+    subtopic: string;
+    tag: string;
+    importance: number;
+    timestamp: number;
+    score: number;
+  }[];
+}
+
+export interface MemoryContext {
+  tier: number;
+  facts: { subject: string; predicate: string; object: string; since: string }[];
+  memories: { text: string; topic: string; subtopic: string; score: number }[];
+  tokenEstimate: number;
+  formatted: string;
+}

package/sst-env.d.ts

@@ -0,0 +1,10 @@
+/* This file is auto-generated by SST. Do not edit. */
+/* tslint:disable */
+/* eslint-disable */
+/* deno-fmt-ignore-file */
+/* biome-ignore-all lint: auto-generated */
+
+/// <reference path="../../sst-env.d.ts" />
+
+import "sst"
+export {}

package/tsconfig.json

@@ -0,0 +1,20 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "Node16",
+    "moduleResolution": "Node16",
+    "lib": ["ES2022"],
+    "outDir": "dist",
+    "rootDir": "src",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "resolveJsonModule": true,
+    "declaration": true,
+    "declarationMap": true,
+    "sourceMap": true
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist"]
+}