memorylake-openclaw 0.0.6 → 0.0.8

package/index.ts

@@ -10,6 +10,8 @@
  * - CLI: openclaw memorylake search, openclaw memorylake stats
  */
 
+import fs from "node:fs";
+import path from "node:path";
 import got from "got";
 import { Type } from "@sinclair/typebox";
 import type { OpenClawPluginApi } from "openclaw/plugin-sdk";
@@ -530,6 +532,52 @@ const memoryPlugin = {
     const cfg = memoryLakeConfigSchema.parse(api.pluginConfig);
     const provider: MemoryLakeProvider = new PlatformProvider(cfg.host, cfg.apiKey, cfg.projectId);
 
+    // Provider cache: avoids re-creating providers for the same host+apiKey+projectId
+    const providerCache = new Map<string, MemoryLakeProvider>();
+    const globalProviderKey = `${cfg.host}|${cfg.apiKey}|${cfg.projectId}`;
+    providerCache.set(globalProviderKey, provider);
+
+    function getProvider(effectiveCfg: MemoryLakeConfig): MemoryLakeProvider {
+      const key = `${effectiveCfg.host}|${effectiveCfg.apiKey}|${effectiveCfg.projectId}`;
+      let p = providerCache.get(key);
+      if (!p) {
+        p = new PlatformProvider(effectiveCfg.host, effectiveCfg.apiKey, effectiveCfg.projectId);
+        providerCache.set(key, p);
+      }
+      return p;
+    }
+
+    function resolveConfig(ctx: any): MemoryLakeConfig {
+      const workspaceDir = ctx?.workspaceDir;
+      if (!workspaceDir) return cfg;
+
+      const localPath = path.join(workspaceDir, ".memorylake", "config.json");
+      if (!fs.existsSync(localPath)) return cfg;
+
+      try {
+        const raw = JSON.parse(fs.readFileSync(localPath, "utf-8"));
+        if (!raw || typeof raw !== "object" || Array.isArray(raw)) {
+          api.logger.warn(
+            `memorylake-openclaw: workspace config exists but is not a JSON object; falling back to global config (path: ${localPath})`,
+          );
+          return cfg;
+        }
+
+        const allowed = new Set(ALLOWED_KEYS);
+        const overrides: Record<string, unknown> = {};
+        for (const [key, value] of Object.entries(raw)) {
+          if (allowed.has(key)) overrides[key] = value;
+        }
+
+        return { ...cfg, ...overrides } as MemoryLakeConfig;
+      } catch {
+        api.logger.warn(
+          `memorylake-openclaw: failed to parse workspace config JSON; falling back to global config (path: ${localPath})`,
+        );
+        return cfg;
+      }
+    }
+
     // Track current session ID for tool-level session scoping
     let currentSessionId: string | undefined;
 
@@ -538,9 +586,9 @@ const memoryPlugin = {
     );
 
     // Helper: build add options
-    function buildAddOptions(userIdOverride?: string, sessionId?: string): AddOptions {
+    function buildAddOptions(effectiveCfg: MemoryLakeConfig, userIdOverride?: string, sessionId?: string): AddOptions {
       const opts: AddOptions = {
-        user_id: userIdOverride || cfg.userId,
+        user_id: userIdOverride || effectiveCfg.userId,
         infer: true,
         metadata: { source: "OPENCLAW" },
       };
@@ -550,14 +598,15 @@ const memoryPlugin = {
 
     // Helper: build search options
     function buildSearchOptions(
+      effectiveCfg: MemoryLakeConfig,
       userIdOverride?: string,
       limit?: number,
     ): SearchOptions {
       return {
-        user_id: userIdOverride || cfg.userId,
-        top_k: limit ?? cfg.topK,
-        threshold: cfg.searchThreshold,
-        rerank: cfg.rerank,
+        user_id: userIdOverride || effectiveCfg.userId,
+        top_k: limit ?? effectiveCfg.topK,
+        threshold: effectiveCfg.searchThreshold,
+        rerank: effectiveCfg.rerank,
       };
     }
 
@@ -566,7 +615,7 @@ const memoryPlugin = {
     // ========================================================================
 
     api.registerTool(
-      {
+      (ctx) => ({
         name: "memory_search",
         label: "Memory Search",
         description:
@@ -596,6 +645,8 @@ const memoryPlugin = {
           ),
         }),
         async execute(_toolCallId, params) {
+          const effectiveCfg = resolveConfig(ctx);
+          const effectiveProvider = getProvider(effectiveCfg);
           const { query, limit, userId, scope = "all" } = params as {
             query: string;
             limit?: number;
@@ -604,9 +655,9 @@ const memoryPlugin = {
           };
 
           try {
-            const results = await provider.search(
+            const results = await effectiveProvider.search(
               query,
-              buildSearchOptions(userId, limit),
+              buildSearchOptions(effectiveCfg, userId, limit),
             );
 
             if (!results || results.length === 0) {
@@ -652,12 +703,12 @@ const memoryPlugin = {
             };
           }
         },
-      },
+      }),
       { name: "memory_search" },
     );
 
     api.registerTool(
-      {
+      (ctx) => ({
         name: "memory_store",
         label: "Memory Store",
         description:
@@ -676,6 +727,8 @@ const memoryPlugin = {
           ),
         }),
         async execute(_toolCallId, params) {
+          const effectiveCfg = resolveConfig(ctx);
+          const effectiveProvider = getProvider(effectiveCfg);
           const { text, userId } = params as {
             text: string;
             userId?: string;
@@ -683,9 +736,9 @@ const memoryPlugin = {
           };
 
           try {
-            const result = await provider.add(
+            const result = await effectiveProvider.add(
               [{ role: "user", content: text }],
-              buildAddOptions(userId, currentSessionId),
+              buildAddOptions(effectiveCfg, userId, currentSessionId),
             );
 
             const count = result.results?.length ?? 0;
@@ -716,12 +769,12 @@ const memoryPlugin = {
             };
           }
         },
-      },
+      }),
       { name: "memory_store" },
     );
 
     api.registerTool(
-      {
+      (ctx) => ({
         name: "memory_get",
         label: "Memory Get",
         description: "Retrieve a specific memory by its ID from MemoryLake.",
@@ -729,10 +782,12 @@ const memoryPlugin = {
           memoryId: Type.String({ description: "The memory ID to retrieve" }),
         }),
         async execute(_toolCallId, params) {
+          const effectiveCfg = resolveConfig(ctx);
+          const effectiveProvider = getProvider(effectiveCfg);
           const { memoryId } = params as { memoryId: string };
 
           try {
-            const memory = await provider.get(memoryId);
+            const memory = await effectiveProvider.get(memoryId);
 
             return {
               content: [
@@ -755,12 +810,12 @@ const memoryPlugin = {
             };
           }
         },
-      },
+      }),
       { name: "memory_get" },
     );
 
     api.registerTool(
-      {
+      (ctx) => ({
         name: "memory_list",
         label: "Memory List",
         description:
@@ -784,11 +839,13 @@ const memoryPlugin = {
           ),
         }),
         async execute(_toolCallId, params) {
+          const effectiveCfg = resolveConfig(ctx);
+          const effectiveProvider = getProvider(effectiveCfg);
           const { userId, scope = "all" } = params as { userId?: string; scope?: "session" | "long-term" | "all" };
 
           try {
-            const uid = userId || cfg.userId;
-            const memories = await provider.getAll({ user_id: uid });
+            const uid = userId || effectiveCfg.userId;
+            const memories = await effectiveProvider.getAll({ user_id: uid });
 
             if (!memories || memories.length === 0) {
               return {
@@ -833,12 +890,12 @@ const memoryPlugin = {
             };
           }
         },
-      },
+      }),
       { name: "memory_list" },
     );
 
     api.registerTool(
-      {
+      (ctx) => ({
         name: "memory_forget",
         label: "Memory Forget",
         description:
@@ -847,10 +904,12 @@ const memoryPlugin = {
           memoryId: Type.String({ description: "Memory ID to delete" }),
         }),
         async execute(_toolCallId, params) {
+          const effectiveCfg = resolveConfig(ctx);
+          const effectiveProvider = getProvider(effectiveCfg);
           const { memoryId } = params as { memoryId: string };
 
           try {
-            await provider.delete(memoryId);
+            await effectiveProvider.delete(memoryId);
             return {
               content: [
                 { type: "text", text: `Memory ${memoryId} forgotten.` },
@@ -869,12 +928,12 @@ const memoryPlugin = {
             };
           }
         },
-      },
+      }),
       { name: "memory_forget" },
     );
 
     api.registerTool(
-      {
+      (ctx) => ({
         name: "document_search",
         label: "Document Search",
         description:
@@ -889,12 +948,14 @@ const memoryPlugin = {
           ),
         }),
         async execute(_toolCallId, params) {
+          const effectiveCfg = resolveConfig(ctx);
+          const effectiveProvider = getProvider(effectiveCfg);
           const { query, topN } = params as { query: string; topN?: number };
 
           try {
-            const response = await provider.searchDocuments(
+            const response = await effectiveProvider.searchDocuments(
               query,
-              topN ?? cfg.topK,
+              topN ?? effectiveCfg.topK,
             );
 
             if (!response.results || response.results.length === 0) {
@@ -929,12 +990,12 @@ const memoryPlugin = {
             };
           }
         },
-      },
+      }),
       { name: "document_search" },
     );
 
     api.registerTool(
-      {
+      (ctx) => ({
         name: "advanced_web_search",
         label: "Advanced Web Search",
         description:
@@ -986,6 +1047,8 @@ const memoryPlugin = {
           ),
         }),
         async execute(_toolCallId, params) {
+          const effectiveCfg = resolveConfig(ctx);
+          const effectiveProvider = getProvider(effectiveCfg);
           const {
             query,
             domain: rawDomain,
@@ -1005,18 +1068,18 @@ const memoryPlugin = {
               : normalizeWebSearchDomain(rawDomain);
 
           try {
-            const response = await provider.searchWeb(query, {
+            const response = await effectiveProvider.searchWeb(query, {
               domain,
-              max_results: maxResults ?? cfg.topK,
+              max_results: maxResults ?? effectiveCfg.topK,
               start_date: startDate,
               end_date: endDate,
-              include_domains: cfg.webSearchIncludeDomains,
-              exclude_domains: cfg.webSearchExcludeDomains,
+              include_domains: effectiveCfg.webSearchIncludeDomains,
+              exclude_domains: effectiveCfg.webSearchExcludeDomains,
               user_location:
-                cfg.webSearchCountry || cfg.webSearchTimezone
+                effectiveCfg.webSearchCountry || effectiveCfg.webSearchTimezone
                   ? {
-                    country: cfg.webSearchCountry,
-                    timezone: cfg.webSearchTimezone,
+                    country: effectiveCfg.webSearchCountry,
+                    timezone: effectiveCfg.webSearchTimezone,
                   }
                   : undefined,
             });
@@ -1057,7 +1120,7 @@ const memoryPlugin = {
             };
           }
         },
-      },
+      }),
       { optional: true },
     );
 
@@ -1081,7 +1144,7 @@ const memoryPlugin = {
               const limit = parseInt(opts.limit, 10);
               const results = await provider.search(
                 query,
-                buildSearchOptions(undefined, limit),
+                buildSearchOptions(cfg, undefined, limit),
               );
 
               if (!results.length) {
@@ -1133,13 +1196,17 @@ const memoryPlugin = {
       api.on("before_agent_start", async (event, ctx) => {
         if (!event.prompt || event.prompt.length < 5) return;
 
+        // Resolve per-workspace config override
+        const effectiveCfg = resolveConfig(ctx);
+        const effectiveProvider = getProvider(effectiveCfg);
+
         // Track session ID
         const sessionId = (ctx as any)?.sessionKey ?? undefined;
         if (sessionId) currentSessionId = sessionId;
 
         const [memoryResult, docResult] = await Promise.allSettled([
-          provider.search(event.prompt, buildSearchOptions()),
-          provider.searchDocuments(event.prompt, cfg.topK),
+          effectiveProvider.search(event.prompt, buildSearchOptions(effectiveCfg)),
+          effectiveProvider.searchDocuments(event.prompt, effectiveCfg.topK),
         ]);
 
         const contextParts: string[] = [];
@@ -1183,6 +1250,10 @@ const memoryPlugin = {
           return;
         }
 
+        // Resolve per-workspace config override
+        const effectiveCfg = resolveConfig(ctx);
+        const effectiveProvider = getProvider(effectiveCfg);
+
         // Track session ID
         const sessionId = (ctx as any)?.sessionKey ?? undefined;
         if (sessionId) currentSessionId = sessionId;
@@ -1240,8 +1311,8 @@ const memoryPlugin = {
 
           if (formattedMessages.length === 0) return;
 
-          const addOpts = buildAddOptions(undefined, currentSessionId);
-          const result = await provider.add(
+          const addOpts = buildAddOptions(effectiveCfg, undefined, currentSessionId);
+          const result = await effectiveProvider.add(
             formattedMessages,
             addOpts,
           );

package/package.json

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

package/skills/agent-memorylake-config/SKILL.md

@@ -0,0 +1,43 @@
+---
+name: agent-memorylake-config
+description: Use when the user asks to configure agent-specific memorylake properties (e.g. projectId) for the current agent. Writes to the agent-specific config file which overrides the global config.
+---
+
+# Agent MemoryLake Config
+
+Configure agent-specific memorylake properties for the current agent. The config file is located at `{workspace}/.memorylake/config.json`, where `{workspace}` is the agent's workspace directory. This config overrides corresponding properties from the global config.
+
+## Step 1 — Confirm projectId
+
+Ask the user for the `projectId` to configure.
+
+If the user has already provided the `projectId` in their message, skip the question and proceed directly.
+
+## Step 2 — Write Config
+
+1. Ensure the `.memorylake/` directory exists inside the agent's workspace directory:
+
+```bash
+cd {workspace}
+mkdir -p .memorylake
+```
+
+2. If `.memorylake/config.json` already exists, read it first and merge the new properties into the existing config. Do NOT overwrite properties the user did not mention.
+
+3. If `.memorylake/config.json` does not exist, create it with the provided properties.
+
+4. Write the config file. Example format:
+
+```json
+{
+  "projectId": "xxx"
+}
+```
+
+## Step 3 — Confirm Result
+
+Read the written `.memorylake/config.json` and confirm to the user that the configuration is complete.
+
+## Common Mistakes
+
+- Do NOT overwrite existing properties that the user did not mention — always merge

package/skills/memorylake-api/SKILL.md

@@ -0,0 +1,200 @@
+---
+name: memorylake-api
+description: Use when the user asks about MemoryLake features, capabilities, or wants to perform a MemoryLake action but no specific tool or skill matches. This is the catch-all for any MemoryLake-related request -- discovers available APIs from the remote OpenAPI spec and calls them directly.
+---
+
+# MemoryLake API
+
+## Overview
+
+Directly call MemoryLake's REST APIs by discovering endpoints from the live OpenAPI spec. This skill covers any MemoryLake capability not already handled by a dedicated tool or skill — project management, document management, file uploads, memory trace, statistics, and more.
+
+## When to Use
+
+- User asks about MemoryLake capabilities or features, and no existing tool or skill covers the request
+- User wants to manage MemoryLake projects (create, update, delete, list, view stats)
+- User wants to manage documents (upload files, add to project, list, delete)
+- User wants to view the change history (trace) of a memory
+- User wants to call any MemoryLake API endpoint directly
+
+## Step 1 — Read MemoryLake Config
+
+Read `~/.openclaw/openclaw.json` and extract the plugin config:
+
+```bash
+cat ~/.openclaw/openclaw.json | jq '.plugins.entries["memorylake-openclaw"].config'
+```
+
+Extract these values:
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `host` | API host | `https://app.memorylake.ai` |
+| `apiKey` | API key for authentication | (required) |
+| `projectId` | MemoryLake project ID | (required) |
+
+If `apiKey` or `projectId` is missing, stop and inform the user.
+
+Auth header for all requests:
+
+```
+Authorization: Bearer {apiKey}
+```
+
+## Step 2 — Identify the Right API Endpoint
+
+### Option A: Use the Quick Reference Table
+
+If the user's intent clearly maps to one of the endpoints below, skip to Step 3.
+
+#### Projects
+
+| Method | Path | Description |
+|--------|------|-------------|
+| `GET` | `/api/v1/projects` | List projects (paginated, filterable by name) |
+| `POST` | `/api/v1/projects` | Create a new project |
+| `GET` | `/api/v1/projects/{id}` | Get project details (includes stats) |
+| `PUT` | `/api/v1/projects/{id}` | Update project name/description |
+| `DELETE` | `/api/v1/projects/{id}` | Delete a project |
+
+#### Memories (V2)
+
+| Method | Path | Description |
+|--------|------|-------------|
+| `POST` | `/api/v2/projects/{id}/memories` | Add memory from conversation |
+| `GET` | `/api/v2/projects/{id}/memories` | List memories (paginated, filter by `user_id`/`keyword`) |
+| `POST` | `/api/v2/projects/{id}/memories/search` | Search memories by natural language |
+| `GET` | `/api/v2/projects/{id}/memories/{memoryId}` | Get a single memory |
+| `DELETE` | `/api/v2/projects/{id}/memories/{memoryId}` | Delete a memory |
+| `GET` | `/api/v2/projects/{id}/memories/{memoryId}/trace` | Get memory change history |
+
+#### Documents
+
+| Method | Path | Description |
+|--------|------|-------------|
+| `GET` | `/api/v1/projects/{id}/documents` | List documents in project (paginated) |
+| `GET` | `/api/v1/projects/{id}/documents/{documentId}` | Get document details |
+| `DELETE` | `/api/v1/projects/{id}/documents` | Batch delete documents |
+| `POST` | `/api/v1/projects/{id}/documents/search` | Semantic search over documents |
+
+### Option B: Fetch the Live OpenAPI Spec
+
+If the user's request is ambiguous or might involve a new/undocumented endpoint, fetch the spec:
+
+```bash
+curl -s "{host}/openapi/memorylake/api-docs/open-api" | jq '.paths | keys'
+```
+
+To inspect a specific endpoint's schema:
+
+```bash
+curl -s "{host}/openapi/memorylake/api-docs/open-api" | jq '.paths["/api/v1/projects/{id}"]'
+```
+
+To inspect request/response schemas:
+
+```bash
+curl -s "{host}/openapi/memorylake/api-docs/open-api" | jq '.components.schemas["ProjectCreateRequest"]'
+```
+
+## Step 3 — Construct and Execute the API Call
+
+Build a `curl` command using:
+
+- **Base URL**: `{host}/openapi/memorylake` (the server base path from the OpenAPI spec)
+- **Full URL**: `{host}/openapi/memorylake{path}` (e.g., `{host}/openapi/memorylake/api/v1/projects`)
+- **Path params**: replace `{id}` with `{projectId}` from config (for project-scoped endpoints)
+- **Auth header**: `Authorization: Bearer {apiKey}`
+- **Content-Type**: `application/json` (for POST/PUT requests with a body)
+
+### Example: List Projects
+
+```bash
+curl -s -X GET "{host}/openapi/memorylake/api/v1/projects?page=1&size=20" \
+  -H "Authorization: Bearer {apiKey}" | jq
+```
+
+### Example: Create a Project
+
+```bash
+curl -s -X POST "{host}/openapi/memorylake/api/v1/projects" \
+  -H "Authorization: Bearer {apiKey}" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "name": "My New Project",
+    "description": "Project description"
+  }' | jq
+```
+
+### Example: Get Project Details (with Stats)
+
+```bash
+curl -s -X GET "{host}/openapi/memorylake/api/v1/projects/{projectId}" \
+  -H "Authorization: Bearer {apiKey}" | jq
+```
+
+### Example: Get Memory Trace
+
+```bash
+curl -s -X GET "{host}/openapi/memorylake/api/v2/projects/{projectId}/memories/{memoryId}/trace" \
+  -H "Authorization: Bearer {apiKey}" | jq
+```
+
+### Example: Search Documents
+
+```bash
+curl -s -X POST "{host}/openapi/memorylake/api/v1/projects/{projectId}/documents/search" \
+  -H "Authorization: Bearer {apiKey}" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "query": "quarterly sales figures",
+    "top_n": 10
+  }' | jq
+```
+
+## Step 4 — Present Results
+
+Parse the JSON response and present it to the user in a readable format:
+
+- Check `success` field — if `false`, report `message` and `error_code`
+- For list/search responses, format the `data.items` or `data.results` array as a table or structured list
+- For single-item responses, display key fields clearly
+- For paginated responses, report `page`, `total`, `total_pages` so the user knows if there are more results
+
+## Error Handling
+
+All responses follow the same wrapper format:
+
+```json
+{
+  "success": true|false,
+  "message": "Human-readable message",
+  "data": { ... },
+  "error_code": "VALIDATION_ERROR"
+}
+```
+
+| HTTP Status | Meaning | Action |
+|-------------|---------|--------|
+| 200 | Success | Parse `data` field |
+| 400 | Invalid request | Check `message` for validation details |
+| 404 | Not found | Verify project ID / memory ID / document ID |
+| 401/403 | Auth failure | Verify `apiKey` is correct and not expired |
+
+## Common Mistakes
+
+- **Wrong base URL**: The full URL must include `/openapi/memorylake` before the API path. E.g., `/openapi/memorylake/api/v1/projects`, NOT just `/api/v1/projects`
+- **Missing auth header**: Every request requires `Authorization: Bearer {apiKey}`
+- **Hardcoded project ID**: Always read `projectId` from `~/.openclaw/openclaw.json` config, not from user input (unless the user explicitly wants a different project)
+- **Pagination**: List endpoints default to `page=1, size=20`. Pass `page` and `size` query params if the user needs more results
+
+## Quick Reference
+
+| Item | Value |
+|------|-------|
+| OpenClaw config | `~/.openclaw/openclaw.json` |
+| Plugin config key | `plugins.entries["memorylake-openclaw"].config` |
+| Server base path | `/openapi/memorylake` |
+| OpenAPI spec URL | `{host}/openapi/memorylake/api-docs/open-api` |
+| Auth header | `Authorization: Bearer {apiKey}` |
+| Default host | `https://app.memorylake.ai` |

package/skills/memorylake-upload/SKILL.md

@@ -0,0 +1,60 @@
+---
+name: memorylake-upload
+description: Use when the user wants to upload files, documents, PDFs, or other data files to MemoryLake and associate them with a project.
+---
+
+# MemoryLake File Upload
+
+## Overview
+
+Upload local files to MemoryLake using the multipart upload API, then associate them with a project.
+
+## When to Use
+
+- User wants to upload a file (PDF, DOCX, image, etc.) to MemoryLake
+- User wants to add a local document to a MemoryLake project
+
+## Step 1 -- Read MemoryLake Config
+
+Read `~/.openclaw/openclaw.json` and extract the plugin config:
+
+```bash
+cat ~/.openclaw/openclaw.json | jq '.plugins.entries["memorylake-openclaw"].config'
+```
+
+Extract these values:
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `host` | API host | `https://app.memorylake.ai` |
+| `apiKey` | API key for authentication | (required) |
+| `projectId` | MemoryLake project ID | (required) |
+
+If `apiKey` or `projectId` is missing, stop and inform the user.
+
+## Step 2 -- Run the Upload Script
+
+The upload script is at `scripts/upload.mjs` relative to **this skill's SKILL.md**.
+
+```bash
+node {path-to-this-skill}/scripts/upload.mjs \
+  --host {host} \
+  --api-key {apiKey} \
+  --project-id {projectId} \
+  --file-name {fileName} \
+  /path/to/file
+```
+
+`--file-name` is the original file name as provided by the user (e.g., `report-Q1.pdf`). This is required because the local file path may be a temp path or renamed file that doesn't reflect the real name.
+
+## Step 3 -- Handle Output
+
+The script prints progress for each step (create upload, upload parts, complete, add to project).
+
+- **Success**: Report the document ID and file name to the user
+- **Failure**: The script prints the specific error (file not found, auth failed, API error). Read the error message and relay it to the user — don't guess the cause
+
+## Common Mistakes
+
+- **Skipping Step 1**: Directly hardcoding host/apiKey/projectId instead of reading from `~/.openclaw/openclaw.json`
+- **Relative file paths**: Always resolve the user's file path to an absolute path before passing to the script

package/skills/memorylake-upload/scripts/upload.mjs

@@ -0,0 +1,273 @@
+#!/usr/bin/env node
+
+/**
+ * MemoryLake File Upload Script
+ *
+ * Uploads a local file to MemoryLake using multipart upload,
+ * then associates it with a project.
+ *
+ * Usage:
+ *   node upload.mjs --host <url> --api-key <key> --project-id <id> <file_path>
+ *
+ * Parameters:
+ *   host       - Base URL (e.g., http://10.71.10.71:3002)
+ *   apiKey     - API key for authentication
+ *   projectId  - Project ID to associate the document with (required)
+ *   filePath   - Path to the file to upload
+ */
+
+import fs from 'fs';
+import path from 'path';
+import https from 'https';
+import http from 'http';
+
+// API base path
+const API_BASE = '/openapi/memorylake';
+
+/**
+ * Make an HTTP request
+ */
+function request(method, urlStr, body = null, headers = {}) {
+  return new Promise((resolve, reject) => {
+    const url = new URL(urlStr);
+    const isHttps = url.protocol === 'https:';
+    const lib = isHttps ? https : http;
+
+    const options = {
+      hostname: url.hostname,
+      port: url.port || (isHttps ? 443 : 80),
+      path: url.pathname + url.search,
+      method,
+      headers: {
+        ...headers,
+      },
+    };
+
+    if (body && typeof body === 'object' && !(body instanceof Buffer)) {
+      options.headers['Content-Type'] = 'application/json';
+    }
+
+    const req = lib.request(options, (res) => {
+      const chunks = [];
+      res.on('data', (chunk) => chunks.push(chunk));
+      res.on('end', () => {
+        const buffer = Buffer.concat(chunks);
+        const text = buffer.toString('utf8');
+        resolve({
+          status: res.statusCode,
+          headers: res.headers,
+          body: text,
+        });
+      });
+    });
+
+    req.on('error', reject);
+
+    if (body) {
+      if (body instanceof Buffer) {
+        req.write(body);
+      } else if (typeof body === 'object') {
+        req.write(JSON.stringify(body));
+      } else {
+        req.write(body);
+      }
+    }
+
+    req.end();
+  });
+}
+
+/**
+ * Create multipart upload session
+ */
+async function createMultipartUpload(host, apiKey, fileSize) {
+  const url = `${host}${API_BASE}/api/v1/upload/create-multipart`;
+  const response = await request('POST', url, { file_size: fileSize }, {
+    'Authorization': `Bearer ${apiKey}`,
+    'Content-Type': 'application/json',
+  });
+
+  const data = JSON.parse(response.body);
+  if (!data.success) {
+    throw new Error(`Create multipart failed: ${data.message || JSON.stringify(data)}`);
+  }
+  return data.data;
+}
+
+/**
+ * Upload a single part to pre-signed URL
+ */
+async function uploadPart(uploadUrl, buffer, partNumber, totalParts) {
+  process.stdout.write(`  Uploading part ${partNumber + 1}/${totalParts}...`);
+
+  const response = await request('PUT', uploadUrl, buffer, {
+    'Content-Length': buffer.length.toString(),
+  });
+
+  if (response.status < 200 || response.status >= 300) {
+    throw new Error(`Part upload failed with status ${response.status}: ${response.body}`);
+  }
+
+  // Get ETag from response headers (may be quoted)
+  let etag = response.headers['etag'] || response.headers['ETag'];
+  if (etag) {
+    etag = etag.replace(/"/g, '');
+  }
+
+  console.log(` done (ETag: ${etag || 'none'})`);
+  return etag;
+}
+
+/**
+ * Complete multipart upload
+ */
+async function completeMultipartUpload(host, apiKey, uploadId, objectKey, partEtags) {
+  const url = `${host}${API_BASE}/api/v1/upload/complete-multipart`;
+  const response = await request('POST', url, {
+    upload_id: uploadId,
+    object_key: objectKey,
+    part_etags: partEtags,
+  }, {
+    'Authorization': `Bearer ${apiKey}`,
+    'Content-Type': 'application/json',
+  });
+
+  const data = JSON.parse(response.body);
+  if (!data.success) {
+    throw new Error(`Complete multipart failed: ${data.message || JSON.stringify(data)}`);
+  }
+  return data;
+}
+
+/**
+ * Add document to project
+ */
+async function quickAddDocument(host, apiKey, projectId, objectKey, fileName) {
+  const url = `${host}${API_BASE}/api/v1/projects/${projectId}/documents/quick-add`;
+  const response = await request('POST', url, {
+    object_key: objectKey,
+    file_name: fileName,
+  }, {
+    'Authorization': `Bearer ${apiKey}`,
+    'Content-Type': 'application/json',
+  });
+
+  const data = JSON.parse(response.body);
+  if (!data.success) {
+    throw new Error(`Quick add document failed: ${data.message || JSON.stringify(data)}`);
+  }
+  return data.data;
+}
+
+/**
+ * Format file size for display
+ */
+function formatSize(bytes) {
+  if (bytes < 1024) return `${bytes} B`;
+  if (bytes < 1024 * 1024) return `${(bytes / 1024).toFixed(1)} KB`;
+  if (bytes < 1024 * 1024 * 1024) return `${(bytes / (1024 * 1024)).toFixed(1)} MB`;
+  return `${(bytes / (1024 * 1024 * 1024)).toFixed(2)} GB`;
+}
+
+/**
+ * Main upload function
+ */
+export async function upload({ host, apiKey, projectId, filePath, fileName }) {
+  if (!host) throw new Error('host is required');
+  if (!apiKey) throw new Error('apiKey is required');
+  if (!projectId) throw new Error('projectId is required');
+  if (!filePath) throw new Error('filePath is required');
+
+  if (!fs.existsSync(filePath)) {
+    throw new Error(`File not found: ${filePath}`);
+  }
+
+  const stats = fs.statSync(filePath);
+  const fileSize = stats.size;
+  if (!fileName) fileName = path.basename(filePath);
+
+  console.log(`\nUploading: ${fileName} (${formatSize(fileSize)})`);
+
+  // Step 1: Create multipart upload
+  console.log('Creating multipart upload...');
+  const uploadInfo = await createMultipartUpload(host, apiKey, fileSize);
+  const { upload_id, object_key, part_items } = uploadInfo;
+  console.log(`  Upload ID: ${upload_id}`);
+  console.log(`  Object Key: ${object_key}`);
+  console.log(`  Parts: ${part_items.length}`);
+
+  // Step 2: Upload each part (stream each chunk to avoid loading entire file into memory)
+  console.log('\nUploading parts:');
+  const fd = fs.openSync(filePath, 'r');
+  const partEtags = [];
+
+  let offset = 0;
+  for (const part of part_items) {
+    const partBuffer = Buffer.alloc(part.size);
+    fs.readSync(fd, partBuffer, 0, part.size, offset);
+    const etag = await uploadPart(part.upload_url, partBuffer, part.number, part_items.length);
+    partEtags.push({
+      number: part.number,
+      etag: etag,
+    });
+    offset += part.size;
+  }
+  fs.closeSync(fd);
+
+  // Step 3: Complete multipart upload
+  console.log('\nCompleting multipart upload...');
+  await completeMultipartUpload(host, apiKey, upload_id, object_key, partEtags);
+  console.log('  Upload completed');
+
+  // Step 4: Add to project
+  console.log(`\nAdding to project: ${projectId}`);
+  const doc = await quickAddDocument(host, apiKey, projectId, object_key, fileName);
+  console.log('  Document added to project');
+  console.log(`  Document ID: ${doc.document_id}`);
+  console.log(`  File name: ${doc.file_name}`);
+  return doc;
+}
+
+// CLI entry point
+async function main() {
+  const args = process.argv.slice(2);
+
+  if (args.length === 0 || args[0] === '--help' || args[0] === '-h') {
+    console.log(`
+MemoryLake File Upload
+
+Usage:
+  node upload.mjs --host <url> --api-key <key> --project-id <id> <file_path>
+
+Arguments:
+  --host       Base URL (e.g., http://10.71.10.71:3002)
+  --api-key    API key for authentication
+  --project-id Project ID to associate the document with (required)
+  --file-name  Custom file name (default: basename of file_path)
+  file_path    Path to the file to upload
+
+Examples:
+  node upload.mjs --host http://10.71.10.71:3002 --api-key sk-xxx --project-id proj-abc123 document.pdf
+`);
+    process.exit(0);
+  }
+
+  let host, apiKey, projectId, filePath, fileName;
+  for (let i = 0; i < args.length; i++) {
+    if (args[i] === '--host') host = args[++i];
+    else if (args[i] === '--api-key') apiKey = args[++i];
+    else if (args[i] === '--project-id') projectId = args[++i];
+    else if (args[i] === '--file-name') fileName = args[++i];
+    else if (!args[i].startsWith('-')) filePath = args[i];
+  }
+
+  try {
+    await upload({ host, apiKey, projectId, filePath, fileName });
+    console.log('\nDone!\n');
+  } catch (err) {
+    console.error(`\nError: ${err.message}\n`);
+    process.exit(1);
+  }
+}
+
+main();