memorylake-openclaw 0.0.5 → 0.0.6

package/README.md

@@ -37,7 +37,7 @@ Get an API key from [app.memorylake.ai](https://app.memorylake.ai), then add to
 
 ## Agent tools
 
-The agent gets six tools it can call during conversations:
+The agent gets seven tools it can call during conversations:
 
 | Tool | Description |
 |------|-------------|
@@ -47,6 +47,7 @@ The agent gets six tools it can call during conversations:
 | `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 |
+| `advanced_web_search` | Optional tool for web search with plugin-level domain and locale constraints |
 
 ## CLI
 
@@ -70,6 +71,12 @@ openclaw memorylake stats
 | `topK` | `number` | `5` | Max memories per recall |
 | `searchThreshold` | `number` | `0.3` | Min similarity (0–1) |
 | `rerank` | `boolean` | `true` | Rerank search results |
+| `webSearchIncludeDomains` | `string[]` | — | Optional allowlist for `advanced_web_search` results |
+| `webSearchExcludeDomains` | `string[]` | — | Optional denylist for `advanced_web_search` results |
+| `webSearchCountry` | `string` | — | Optional ISO country code for localizing `advanced_web_search` |
+| `webSearchTimezone` | `string` | — | Optional IANA timezone for localizing `advanced_web_search` |
+
+`advanced_web_search` is registered as an optional OpenClaw tool, so agents must explicitly allow it before they can call it.
 
 ## License
 

package/docs/openclaw.mdx

@@ -13,7 +13,7 @@ Add long-term memory to [OpenClaw](https://github.com/openclaw/openclaw) agents
 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
+3. **Agent Tools** — Seven tools for memory, document, and optional web search operations during conversations
 
 Both auto-recall and auto-capture run silently with no manual configuration required.
 
@@ -42,7 +42,7 @@ Add to your `openclaw.json`:
 
 ## Agent Tools
 
-The agent gets six tools it can call during conversations:
+The agent gets seven tools it can call during conversations:
 
 | Tool | Description |
 |------|-------------|
@@ -52,6 +52,7 @@ The agent gets six tools it can call during conversations:
 | `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 |
+| `advanced_web_search` | Optional web search tool backed by the unified search API with plugin-level domain and locale constraints |
 
 ## CLI Commands
 
@@ -75,13 +76,19 @@ openclaw memorylake stats
 | `topK` | `number` | `5` | Max memories per recall |
 | `searchThreshold` | `number` | `0.3` | Min similarity (0–1) |
 | `rerank` | `boolean` | `true` | Rerank search results for better relevance |
+| `webSearchIncludeDomains` | `string[]` | — | Optional allowlist for `advanced_web_search` results |
+| `webSearchExcludeDomains` | `string[]` | — | Optional denylist for `advanced_web_search` results |
+| `webSearchCountry` | `string` | — | Optional ISO country code for localizing `advanced_web_search` |
+| `webSearchTimezone` | `string` | — | Optional IANA timezone for localizing `advanced_web_search` |
+
+<Note>`advanced_web_search` is registered as an optional OpenClaw tool, so it must be explicitly allowed before an agent can call it.</Note>
 
 ## 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
+4. **Rich Tool Suite** — Seven agent tools for memory, document, and optional web search operations when needed
 
 ## Conclusion
 

package/index.ts

@@ -4,7 +4,7 @@
  * Long-term memory via MemoryLake platform.
  *
  * Features:
- * - 6 tools: memory_search, memory_list, memory_store, memory_get, memory_forget, document_search
+ * - 7 tools: memory_search, memory_list, memory_store, memory_get, memory_forget, document_search, advanced_web_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
@@ -29,6 +29,10 @@ type MemoryLakeConfig = {
   searchThreshold: number;
   topK: number;
   rerank: boolean;
+  webSearchIncludeDomains?: string[];
+  webSearchExcludeDomains?: string[];
+  webSearchCountry?: string;
+  webSearchTimezone?: string;
 };
 
 // V2 API option types
@@ -99,6 +103,68 @@ interface DocumentSearchResponse {
   results: DocumentSearchResult[];
 }
 
+/**
+ * Allowed values for web search domain (aligned with zootopia unified_search Domain).
+ * Declared as enum in schema; at runtime accept string and fall back to "auto" if invalid.
+ */
+const WebSearchDomainValues = [
+  "web",
+  "academic",
+  "news",
+  "people",
+  "company",
+  "financial",
+  "markets",
+  "code",
+  "legal",
+  "government",
+  "poi",
+  "auto",
+] as const;
+type WebSearchDomain = (typeof WebSearchDomainValues)[number];
+
+const WEB_SEARCH_DOMAIN_SET = new Set<string>(WebSearchDomainValues);
+
+/** Normalize domain: accept string at runtime; if not a valid enum value, return "auto". */
+function normalizeWebSearchDomain(value: unknown): WebSearchDomain {
+  if (value == null) return "auto";
+  const s = typeof value === "string" ? value.toLowerCase().trim() : "";
+  return (WEB_SEARCH_DOMAIN_SET.has(s) ? s : "auto") as WebSearchDomain;
+}
+
+interface WebSearchUserLocation {
+  country?: string;
+  timezone?: string;
+}
+
+interface WebSearchOptions {
+  /** Declared as enum in schema; at runtime accept string, normalized with fallback to "auto". */
+  domain?: WebSearchDomain | string;
+  max_results?: number;
+  start_date?: string;
+  end_date?: string;
+  include_domains?: string[];
+  exclude_domains?: string[];
+  user_location?: WebSearchUserLocation;
+}
+
+interface WebSearchResult {
+  url?: string;
+  title?: string;
+  summary?: string;
+  content?: string;
+  source?: string;
+  published_date?: string;
+  author?: string;
+  score?: number;
+  highlights?: string[];
+}
+
+interface WebSearchResponse {
+  results: WebSearchResult[];
+  total_results: number;
+}
+
 // ============================================================================
 // Unified Provider Interface
 // ============================================================================
@@ -113,6 +179,7 @@ interface MemoryLakeProvider {
   getAll(options: ListOptions): Promise<MemoryItem[]>;
   delete(memoryId: string): Promise<void>;
   searchDocuments(query: string, topN: number): Promise<DocumentSearchResponse>;
+  searchWeb(query: string, options: WebSearchOptions): Promise<WebSearchResponse>;
 }
 
 // ============================================================================
@@ -130,10 +197,12 @@ class PlatformProvider implements MemoryLakeProvider {
   private readonly http: ReturnType<typeof got.extend>;
   private readonly basePath: string;
   private readonly docSearchPath: string;
+  private readonly webSearchPath: 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.webSearchPath = "openapi/memorylake/api/v1/search"; 
     this.http = got.extend({
       prefixUrl: host,
       headers: {
@@ -220,6 +289,25 @@ class PlatformProvider implements MemoryLakeProvider {
       results: Array.isArray(data?.results) ? data.results : [],
     };
   }
+
+  async searchWeb(query: string, options: WebSearchOptions): Promise<WebSearchResponse> {
+    const domain = options.domain != null ? normalizeWebSearchDomain(options.domain) : "web";
+    const body: Record<string, unknown> = {
+      query,
+      domain,
+    };
+    if (options.max_results != null) body.max_results = options.max_results;
+    if (options.start_date) body.start_date = options.start_date;
+    if (options.end_date) body.end_date = options.end_date;
+    if (options.include_domains?.length) body.include_domains = options.include_domains;
+    if (options.exclude_domains?.length) body.exclude_domains = options.exclude_domains;
+    if (options.user_location) body.user_location = options.user_location;
+
+    const resp = await this.http
+      .post(this.webSearchPath, { json: body })
+      .json<WebSearchResponse>();
+    return normalizeWebSearchResponse(resp);
+  }
 }
 
 // ============================================================================
@@ -254,6 +342,13 @@ function normalizeAddResult(raw: any): AddResult {
   };
 }
 
+function normalizeWebSearchResponse(raw: any): WebSearchResponse {
+  return {
+    results: Array.isArray(raw?.results) ? raw.results : [],
+    total_results: typeof raw?.total_results === "number" ? raw.total_results : 0,
+  };
+}
+
 // ============================================================================
 // Document Context Builder
 // ============================================================================
@@ -302,6 +397,19 @@ function buildDocumentContext(
   return parts.join("\n\n");
 }
 
+function buildWebSearchContext(results: WebSearchResult[]): string {
+  return results
+    .map((result, index) => {
+      const parts = [`${index + 1}. ${result.title ?? result.url ?? "Untitled result"}`];
+      if (result.url) parts.push(`URL: ${result.url}`);
+      if (result.summary) parts.push(`Summary: ${result.summary}`);
+      if (result.source) parts.push(`Source: ${result.source}`);
+      if (result.published_date) parts.push(`Published: ${result.published_date}`);
+      return parts.join("\n");
+    })
+    .join("\n\n");
+}
+
 // ============================================================================
 // Config Parser
 // ============================================================================
@@ -320,6 +428,10 @@ const ALLOWED_KEYS = [
   "searchThreshold",
   "topK",
   "rerank",
+  "webSearchIncludeDomains",
+  "webSearchExcludeDomains",
+  "webSearchCountry",
+  "webSearchTimezone",
 ];
 
 function assertAllowedKeys(
@@ -332,6 +444,28 @@ function assertAllowedKeys(
   throw new Error(`${label} has unknown keys: ${unknown.join(", ")}`);
 }
 
+function parseOptionalStringArray(
+  value: unknown,
+  label: string,
+): string[] | undefined {
+  if (value == null) return undefined;
+  if (!Array.isArray(value) || !value.every((item) => typeof item === "string")) {
+    throw new Error(`${label} must be an array of strings`);
+  }
+  return value;
+}
+
+function parseOptionalString(
+  value: unknown,
+  label: string,
+): string | undefined {
+  if (value == null) return undefined;
+  if (typeof value !== "string") {
+    throw new Error(`${label} must be a string`);
+  }
+  return value;
+}
+
 const memoryLakeConfigSchema = {
   parse(value: unknown): MemoryLakeConfig {
     if (!value || typeof value !== "object" || Array.isArray(value)) {
@@ -361,6 +495,22 @@ const memoryLakeConfigSchema = {
         typeof cfg.searchThreshold === "number" ? cfg.searchThreshold : 0.3,
       topK: typeof cfg.topK === "number" ? cfg.topK : 5,
       rerank: cfg.rerank !== false,
+      webSearchIncludeDomains: parseOptionalStringArray(
+        cfg.webSearchIncludeDomains,
+        "webSearchIncludeDomains",
+      ),
+      webSearchExcludeDomains: parseOptionalStringArray(
+        cfg.webSearchExcludeDomains,
+        "webSearchExcludeDomains",
+      ),
+      webSearchCountry: parseOptionalString(
+        cfg.webSearchCountry,
+        "webSearchCountry",
+      ),
+      webSearchTimezone: parseOptionalString(
+        cfg.webSearchTimezone,
+        "webSearchTimezone",
+      ),
     };
   },
 };
@@ -783,6 +933,134 @@ const memoryPlugin = {
       { name: "document_search" },
     );
 
+    api.registerTool(
+      {
+        name: "advanced_web_search",
+        label: "Advanced Web Search",
+        description:
+          "Search the web using the unified search API with plugin-level domain and location constraints. Use this for recent information, public web pages, or web research that should respect configured allowed domains, blocked domains, and user locale.",
+        parameters: Type.Object({
+          query: Type.String({
+            description:
+              "The web search query to send to the unified search endpoint.",
+          }),
+          domain: Type.Optional(
+            Type.Union(
+              [
+                Type.Literal("web"),
+                Type.Literal("academic"),
+                Type.Literal("news"),
+                Type.Literal("people"),
+                Type.Literal("company"),
+                Type.Literal("financial"),
+                Type.Literal("markets"),
+                Type.Literal("code"),
+                Type.Literal("legal"),
+                Type.Literal("government"),
+                Type.Literal("poi"),
+                Type.Literal("auto"),
+              ],
+              {
+                description:
+                  "Search domain. Default: web. Invalid or unknown values are treated as auto.",
+              },
+            ),
+          ),
+          maxResults: Type.Optional(
+            Type.Number({
+              description: `Maximum number of web results to return (default: ${cfg.topK}).`,
+              minimum: 1,
+            }),
+          ),
+          startDate: Type.Optional(
+            Type.String({
+              description:
+                "Only include results published on or after this date (YYYY-MM-DD).",
+            }),
+          ),
+          endDate: Type.Optional(
+            Type.String({
+              description:
+                "Only include results published on or before this date (YYYY-MM-DD).",
+            }),
+          ),
+        }),
+        async execute(_toolCallId, params) {
+          const {
+            query,
+            domain: rawDomain,
+            maxResults,
+            startDate,
+            endDate,
+          } = params as {
+            query: string;
+            domain?: string;
+            maxResults?: number;
+            startDate?: string;
+            endDate?: string;
+          };
+          const domain: WebSearchDomain =
+            rawDomain === undefined || rawDomain === null
+              ? "web"
+              : normalizeWebSearchDomain(rawDomain);
+
+          try {
+            const response = await provider.searchWeb(query, {
+              domain,
+              max_results: maxResults ?? cfg.topK,
+              start_date: startDate,
+              end_date: endDate,
+              include_domains: cfg.webSearchIncludeDomains,
+              exclude_domains: cfg.webSearchExcludeDomains,
+              user_location:
+                cfg.webSearchCountry || cfg.webSearchTimezone
+                  ? {
+                    country: cfg.webSearchCountry,
+                    timezone: cfg.webSearchTimezone,
+                  }
+                  : undefined,
+            });
+
+            if (!response.results || response.results.length === 0) {
+              return {
+                content: [
+                  { type: "text", text: "No relevant web results found." },
+                ],
+                details: { count: 0, total_results: response.total_results },
+              };
+            }
+
+            const context = buildWebSearchContext(response.results);
+
+            return {
+              content: [
+                {
+                  type: "text",
+                  text: `Found ${response.results.length} web results:\n\n${context}`,
+                },
+              ],
+              details: {
+                count: response.results.length,
+                total_results: response.total_results,
+                results: response.results,
+              },
+            };
+          } catch (err) {
+            return {
+              content: [
+                {
+                  type: "text",
+                  text: `Web search failed: ${String(err)}`,
+                },
+              ],
+              details: { error: String(err) },
+            };
+          }
+        },
+      },
+      { optional: true },
+    );
+
     // ========================================================================
     // CLI Commands
     // ========================================================================

package/openclaw.plugin.json

@@ -35,6 +35,26 @@
     "rerank": {
       "label": "Rerank",
       "help": "Rerank search results"
+    },
+    "webSearchIncludeDomains": {
+      "label": "Web Search Allowed Domains",
+      "placeholder": "[\"example.com\", \"docs.example.com\"]",
+      "help": "Optional allowlist for advanced_web_search results."
+    },
+    "webSearchExcludeDomains": {
+      "label": "Web Search Blocked Domains",
+      "placeholder": "[\"example.com\"]",
+      "help": "Optional denylist for advanced_web_search results."
+    },
+    "webSearchCountry": {
+      "label": "Web Search Country",
+      "placeholder": "US",
+      "help": "Optional ISO country code used to localize advanced_web_search results."
+    },
+    "webSearchTimezone": {
+      "label": "Web Search Timezone",
+      "placeholder": "America/Los_Angeles",
+      "help": "Optional IANA timezone used to localize advanced_web_search results."
     }
   },
   "configSchema": {
@@ -64,6 +84,24 @@
       },
       "rerank": {
         "type": "boolean"
+      },
+      "webSearchIncludeDomains": {
+        "type": "array",
+        "items": {
+          "type": "string"
+        }
+      },
+      "webSearchExcludeDomains": {
+        "type": "array",
+        "items": {
+          "type": "string"
+        }
+      },
+      "webSearchCountry": {
+        "type": "string"
+      },
+      "webSearchTimezone": {
+        "type": "string"
       }
     },
     "required": []

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "memorylake-openclaw",
-  "version": "0.0.5",
+  "version": "0.0.6",
   "type": "module",
   "description": "MemoryLake memory backend for OpenClaw",
   "license": "MIT",