memorylake-openclaw 0.0.7 → 0.0.8

package/package.json

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

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();