memorylake-openclaw 0.0.2 → 0.0.4

package/.github/workflows/release.yml

@@ -0,0 +1,23 @@
+name: Publish Package to npmjs
+on:
+  # Trigger on tag push
+  push:
+    tags:
+      - 'v*.*.*'
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      id-token: write
+    steps:
+      - uses: actions/checkout@v5
+      # Setup .npmrc file to publish to npm
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '24.x'
+          registry-url: 'https://registry.npmjs.org'
+      - run: npm i && npm ci
+      - run: npm publish
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

package/README.md

@@ -10,7 +10,7 @@ Your agent forgets everything between sessions. This plugin fixes that. It watch
   <img src="../docs/images/openclaw-architecture.png" alt="Architecture" width="800" />
 </p> -->
 
-**Auto-Recall** — Before the agent responds, the plugin searches MemoryLake for memories that match the current message and injects them into context.
+**Auto-Recall** — Before the agent responds, the plugin searches MemoryLake for memories and relevant document excerpts that match the current message and injects them into context.
 
 **Auto-Capture** — After the agent responds, the plugin sends the exchange to MemoryLake. MemoryLake decides what's worth keeping — new facts get stored, stale ones updated, duplicates merged.
 
@@ -29,16 +29,15 @@ Get an API key from [app.memorylake.ai](https://app.memorylake.ai), then add to
 "memorylake-openclaw": {
   "enabled": true,
   "config": {
-    "apiKey": "${MEMORYLAKE_API_KEY}",
-    "projectId": "proj-...",
-    "userId": "your-user-id"
+    "apiKey": "sk-...",
+    "projectId": "proj-..."
   }
 }
 ```
 
 ## Agent tools
 
-The agent gets five tools it can call during conversations:
+The agent gets six tools it can call during conversations:
 
 | Tool | Description |
 |------|-------------|
@@ -47,6 +46,7 @@ The agent gets five tools it can call during conversations:
 | `memory_store` | Explicitly save a fact |
 | `memory_get` | Retrieve a memory by ID |
 | `memory_forget` | Delete a memory by ID |
+| `document_search` | Search project documents for relevant paragraphs, tables, and figures |
 
 ## CLI
 

package/docs/openclaw.mdx

@@ -0,0 +1,98 @@
+---
+title: OpenClaw
+---
+
+Add long-term memory to [OpenClaw](https://github.com/openclaw/openclaw) agents with the `memorylake-openclaw` plugin. Your agent forgets everything between sessions — this plugin fixes that by automatically watching conversations, extracting what matters, and bringing it back when relevant.
+
+## Overview
+
+{/*<Frame>
+  <img src="/images/openclaw-architecture.png" alt="OpenClaw MemoryLake Architecture" />
+</Frame>*/}
+
+The plugin provides:
+1. **Auto-Recall** — Before the agent responds, memories and relevant document excerpts matching the current message are injected into context
+2. **Auto-Capture** — After the agent responds, the exchange is sent to MemoryLake which decides what's worth keeping
+3. **Agent Tools** — Six tools for memory and document operations during conversations
+
+Both auto-recall and auto-capture run silently with no manual configuration required.
+
+## Installation
+
+```bash
+openclaw plugins install memorylake-openclaw
+```
+
+## Setup and Configuration
+
+<Note>Get your API key and project ID from [app.memorylake.ai](https://app.memorylake.ai).</Note>
+
+Add to your `openclaw.json`:
+
+```json5
+// plugins.entries
+"memorylake-openclaw": {
+  "enabled": true,
+  "config": {
+    "apiKey": "sk-...",
+    "projectId": "proj-..."
+  }
+}
+```
+
+## Agent Tools
+
+The agent gets six tools it can call during conversations:
+
+| Tool | Description |
+|------|-------------|
+| `memory_search` | Search memories by natural language |
+| `memory_list` | List all stored memories for a user |
+| `memory_store` | Explicitly save a fact |
+| `memory_get` | Retrieve a memory by ID |
+| `memory_forget` | Delete a memory by ID |
+| `document_search` | Search project documents for relevant paragraphs, tables, and figures |
+
+## CLI Commands
+
+```bash
+# Search memories
+openclaw memorylake search "what languages does the user know"
+
+# View stats
+openclaw memorylake stats
+```
+
+## Configuration Options
+
+| Key | Type | Default | Description |
+|-----|------|---------|-------------|
+| `apiKey` | `string` | — | **Required.** MemoryLake API key (supports `${MEMORYLAKE_API_KEY}`) |
+| `projectId` | `string` | — | **Required.** MemoryLake project ID |
+| `host` | `string` | `https://app.memorylake.ai` | MemoryLake server endpoint URL |
+| `userId` | `string` | `"default"` | Scope memories per user |
+| `autoRecall` | `boolean` | `true` | Inject memories before each turn |
+| `autoCapture` | `boolean` | `true` | Store facts after each turn |
+| `topK` | `number` | `5` | Max memories per recall |
+| `searchThreshold` | `number` | `0.3` | Min similarity (0–1) |
+| `rerank` | `boolean` | `true` | Rerank search results for better relevance |
+
+## Key Features
+
+1. **Zero Configuration** — Auto-recall and auto-capture work out of the box with no prompting required
+2. **Async Processing** — Memory extraction runs asynchronously via MemoryLake's API
+3. **Session Tracking** — Conversations are tagged with `chat_session_id` for traceability
+4. **Rich Tool Suite** — Six agent tools for memory and document operations when needed
+
+## Conclusion
+
+The `memorylake-openclaw` plugin gives OpenClaw agents persistent memory with minimal setup. Your agents can remember user preferences, facts, and context across sessions automatically.
+
+{/*<CardGroup cols={2}>
+  <Card title="MemoryLake" icon="brain" href="https://app.memorylake.ai">
+    MemoryLake platform
+  </Card>
+  <Card title="OpenClaw" icon="robot" href="https://github.com/openclaw/openclaw">
+    OpenClaw agent framework
+  </Card>
+</CardGroup>*/}

package/index.ts

@@ -4,8 +4,8 @@
  * Long-term memory via MemoryLake platform.
  *
  * Features:
- * - 5 tools: memory_search, memory_list, memory_store, memory_get, memory_forget
- * - Auto-recall: injects relevant memories (both scopes) before each agent turn
+ * - 6 tools: memory_search, memory_list, memory_store, memory_get, memory_forget, document_search
+ * - Auto-recall: injects relevant memories and document excerpts before each agent turn
  * - Auto-capture: stores key facts scoped to the current session after each agent turn
  * - CLI: openclaw memorylake search, openclaw memorylake stats
  */
@@ -69,6 +69,35 @@ interface AddResult {
   results: AddResultItem[];
 }
 
+interface DocumentSearchResult {
+  type: "table" | "paragraph" | "figure";
+  document_id?: string;
+  document_name?: string;
+  source_document?: { file_name?: string };
+  highlight?: {
+    chunks?: Array<{ text?: string; range?: string }>;
+    inner_tables?: Array<{
+      id?: string;
+      columns?: Array<{ name?: string; data_type?: string }>;
+      num_rows?: number;
+    }>;
+    figure?: {
+      text?: string;
+      caption?: string;
+      summary_text?: string;
+    };
+  };
+  title?: string;
+  footnote?: string;
+  sheet_name?: string;
+  figure_id?: number;
+}
+
+interface DocumentSearchResponse {
+  count: number;
+  results: DocumentSearchResult[];
+}
+
 // ============================================================================
 // Unified Provider Interface
 // ============================================================================
@@ -82,6 +111,7 @@ interface MemoryLakeProvider {
   get(memoryId: string): Promise<MemoryItem>;
   getAll(options: ListOptions): Promise<MemoryItem[]>;
   delete(memoryId: string): Promise<void>;
+  searchDocuments(query: string, topN: number): Promise<DocumentSearchResponse>;
 }
 
 // ============================================================================
@@ -98,9 +128,11 @@ interface ApiResponse<T = unknown> {
 class PlatformProvider implements MemoryLakeProvider {
   private readonly http: ReturnType<typeof got.extend>;
   private readonly basePath: string;
+  private readonly docSearchPath: string;
 
   constructor(host: string, apiKey: string, projectId: string) {
     this.basePath = `openapi/memorylake/api/v2/projects/${projectId}/memories`;
+    this.docSearchPath = `openapi/memorylake/api/v1/projects/${projectId}/documents/search`;
     this.http = got.extend({
       prefixUrl: host,
       headers: {
@@ -175,6 +207,18 @@ class PlatformProvider implements MemoryLakeProvider {
       .json<ApiResponse>();
     if (!resp.success) throw new Error(resp.message ?? "delete failed");
   }
+
+  async searchDocuments(query: string, topN: number): Promise<DocumentSearchResponse> {
+    const resp = await this.http
+      .post(this.docSearchPath, { json: { query, topN } })
+      .json<ApiResponse>();
+    if (!resp.success) throw new Error(resp.message ?? "document search failed");
+    const data = resp.data as any;
+    return {
+      count: data?.count ?? 0,
+      results: Array.isArray(data?.results) ? data.results : [],
+    };
+  }
 }
 
 // ============================================================================
@@ -210,19 +254,57 @@ function normalizeAddResult(raw: any): AddResult {
 }
 
 // ============================================================================
-// Config Parser
+// Document Context Builder
 // ============================================================================
 
-function resolveEnvVars(value: string): string {
-  return value.replace(/\$\{([^}]+)\}/g, (_, envVar) => {
-    const envValue = process.env[envVar];
-    if (!envValue) {
-      throw new Error(`Environment variable ${envVar} is not set`);
+function buildDocumentContext(
+  results: DocumentSearchResult[],
+  maxChunkLength = 10000,
+): string {
+  const parts: string[] = [];
+
+  for (const result of results) {
+    const source = result.document_name ?? result.source_document?.file_name ?? "unknown";
+    const highlight = result.highlight;
+
+    if (result.type === "table") {
+      const title = result.title || "Untitled Table";
+      parts.push(`### Table: ${title} (from ${source})`);
+      if (result.footnote) parts.push(`Note: ${result.footnote}`);
+
+      for (const innerTable of highlight?.inner_tables ?? []) {
+        const colDesc = (innerTable.columns ?? [])
+          .map((c) => `${c.name}(${c.data_type})`)
+          .join(", ");
+        if (colDesc) parts.push(`Columns: ${colDesc}`);
+        if (innerTable.num_rows != null) parts.push(`Rows: ${innerTable.num_rows}`);
+      }
+      for (const chunk of highlight?.chunks ?? []) {
+        if (chunk.text) parts.push(chunk.text.slice(0, maxChunkLength));
+      }
+    } else if (result.type === "paragraph") {
+      parts.push(`### Paragraph (from ${source}):`);
+      for (const chunk of highlight?.chunks ?? []) {
+        if (chunk.text) parts.push(chunk.text.slice(0, maxChunkLength));
+      }
+    } else if (result.type === "figure") {
+      const figure = highlight?.figure;
+      if (figure) {
+        parts.push(`### Figure (from ${source}):`);
+        if (figure.caption) parts.push(`Caption: ${figure.caption}`);
+        const text = figure.text || figure.summary_text || "";
+        if (text) parts.push(text);
+      }
     }
-    return envValue;
-  });
+  }
+
+  return parts.join("\n\n");
 }
 
+// ============================================================================
+// Config Parser
+// ============================================================================
+
 // ============================================================================
 // Config Schema
 // ============================================================================
@@ -267,10 +349,10 @@ const memoryLakeConfigSchema = {
     return {
       host:
         typeof cfg.host === "string" && cfg.host
-          ? resolveEnvVars(cfg.host)
+          ? cfg.host
           : "https://app.memorylake.ai",
-      apiKey: resolveEnvVars(cfg.apiKey),
-      projectId: resolveEnvVars(cfg.projectId),
+      apiKey: cfg.apiKey as string,
+      projectId: cfg.projectId as string,
       userId:
         typeof cfg.userId === "string" && cfg.userId ? cfg.userId : "default",
       autoCapture: cfg.autoCapture !== false,
@@ -641,6 +723,66 @@ const memoryPlugin = {
       { name: "memory_forget" },
     );
 
+    api.registerTool(
+      {
+        name: "document_search",
+        label: "Document Search",
+        description:
+          "Search through documents stored in MemoryLake project. Returns relevant paragraphs, tables, and figures from uploaded documents.",
+        parameters: Type.Object({
+          query: Type.String({ description: "Search query" }),
+          topN: Type.Optional(
+            Type.Number({
+              description: `Max results (default: ${cfg.topK})`,
+              minimum: 1,
+            }),
+          ),
+        }),
+        async execute(_toolCallId, params) {
+          const { query, topN } = params as { query: string; topN?: number };
+
+          try {
+            const response = await provider.searchDocuments(
+              query,
+              topN ?? cfg.topK,
+            );
+
+            if (!response.results || response.results.length === 0) {
+              return {
+                content: [
+                  { type: "text", text: "No relevant documents found." },
+                ],
+                details: { count: 0 },
+              };
+            }
+
+            const context = buildDocumentContext(response.results);
+
+            return {
+              content: [
+                {
+                  type: "text",
+                  text: `Found ${response.results.length} document results:\n\n${context}`,
+                },
+              ],
+              details: { count: response.results.length },
+            };
+          } catch (err) {
+            return {
+              content: [
+                {
+                  type: "text",
+                  text: `Document search failed: ${String(err)}`,
+                },
+              ],
+              details: { error: String(err) },
+            };
+          }
+        },
+      },
+      { name: "document_search" },
+    );
+
     // ========================================================================
     // CLI Commands
     // ========================================================================
@@ -708,7 +850,7 @@ const memoryPlugin = {
     // Lifecycle Hooks
     // ========================================================================
 
-    // Auto-recall: inject relevant memories before agent starts
+    // Auto-recall: inject relevant memories and documents before agent starts
     if (cfg.autoRecall) {
       api.on("before_agent_start", async (event, ctx) => {
         if (!event.prompt || event.prompt.length < 5) return;
@@ -717,28 +859,42 @@ const memoryPlugin = {
         const sessionId = (ctx as any)?.sessionKey ?? undefined;
         if (sessionId) currentSessionId = sessionId;
 
-        try {
-          const results = await provider.search(
-            event.prompt,
-            buildSearchOptions(),
-          );
+        const [memoryResult, docResult] = await Promise.allSettled([
+          provider.search(event.prompt, buildSearchOptions()),
+          provider.searchDocuments(event.prompt, cfg.topK),
+        ]);
 
-          if (results.length === 0) return;
+        const contextParts: string[] = [];
 
-          const memoryContext = results
+        if (memoryResult.status === "fulfilled" && memoryResult.value.length > 0) {
+          const memoryContext = memoryResult.value
             .map((r) => `- ${r.content}`)
             .join("\n");
-
+          contextParts.push(
+            `<relevant-memories>\nThe following memories may be relevant to this conversation:\n${memoryContext}\n</relevant-memories>`,
+          );
           api.logger.info(
-            `memorylake-openclaw: injecting ${results.length} memories into context`,
+            `memorylake-openclaw: injecting ${memoryResult.value.length} memories into context`,
           );
+        } else if (memoryResult.status === "rejected") {
+          api.logger.warn(`memorylake-openclaw: memory recall failed: ${String(memoryResult.reason)}`);
+        }
 
-          return {
-            prependContext: `<relevant-memories>\nThe following memories may be relevant to this conversation:\n${memoryContext}\n</relevant-memories>`,
-          };
-        } catch (err) {
-          api.logger.warn(`memorylake-openclaw: recall failed: ${String(err)}`);
+        if (docResult.status === "fulfilled" && docResult.value.results.length > 0) {
+          const docContext = buildDocumentContext(docResult.value.results);
+          contextParts.push(
+            `<relevant-documents>\nThe following document excerpts may be relevant to this conversation:\n${docContext}\n</relevant-documents>`,
+          );
+          api.logger.info(
+            `memorylake-openclaw: injecting ${docResult.value.results.length} document results into context`,
+          );
+        } else if (docResult.status === "rejected") {
+          api.logger.warn(`memorylake-openclaw: document search failed: ${String(docResult.reason)}`);
         }
+
+        if (contextParts.length === 0) return;
+
+        return { prependContext: contextParts.join("\n\n") };
       });
     }
 
@@ -789,11 +945,14 @@ const memoryPlugin = {
             }
 
             if (!textContent) continue;
-            // Strip injected memory context, keep the actual user text
+            // Strip injected context, keep the actual user text
             if (textContent.includes("<relevant-memories>")) {
               textContent = textContent.replace(/<relevant-memories>[\s\S]*?<\/relevant-memories>\s*/g, "").trim();
-              if (!textContent) continue;
             }
+            if (textContent.includes("<relevant-documents>")) {
+              textContent = textContent.replace(/<relevant-documents>[\s\S]*?<\/relevant-documents>\s*/g, "").trim();
+            }
+            if (!textContent) continue;
 
             formattedMessages.push({
               role: role as string,

package/package.json

@@ -1,9 +1,13 @@
 {
   "name": "memorylake-openclaw",
-  "version": "0.0.2",
+  "version": "0.0.4",
   "type": "module",
   "description": "MemoryLake memory backend for OpenClaw",
   "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/memorylake-ai/memorylake-openclaw.git"
+  },
   "keywords": [
     "openclaw",
     "plugin",