@clawchatsai/connector 0.0.86 → 0.0.87

package/README.md

@@ -1,30 +1,84 @@
 # @clawchatsai/connector
 
-OpenClaw plugin for [ClawChats](https://clawchats.ai) — connects your local gateway to the ClawChats web app via WebRTC P2P.
+OpenClaw plugin that bridges the [ClawChats](https://clawchats.ai) web app to your local OpenClaw gateway.
 
-## Install
+## What it does
+
+When installed, this plugin runs as a background service alongside your OpenClaw gateway. It:
+
+- Connects to the OpenClaw gateway WebSocket and persists conversation history to a local SQLite database
+- Connects to the ClawChats signaling server (`wss://login.clawchats.ai`) to establish a P2P WebRTC session with your browser
+- Once the P2P connection is established, your browser communicates directly with this plugin — no data passes through any external server
+- Exposes a local HTTP/WebSocket API for threads, messages, workspaces, file management, and memory
+
+## How the connection works
+
+```
+app.clawchats.ai  ──── signaling server ────  connector plugin (your machine)
+  (browser UI)        (handshake only)          (OpenClaw gateway)
+        │                                               │
+        └──────── WebRTC DataChannel (P2P) ────────────┘
+                  encrypted, direct, no relay
+```
+
+1. You open [app.clawchats.ai](https://app.clawchats.ai) in your browser
+2. The browser authenticates with `login.clawchats.ai` and gets a session token
+3. The signaling server coordinates a WebRTC handshake between your browser and this plugin
+4. Your browser connects directly to your gateway via an encrypted P2P DataChannel
+5. All conversation data — messages, files, memory — travels over that direct connection
+
+The signaling server only facilitates the handshake. After step 4, it is out of the picture.
+
+## Installation
 
 ```bash
 openclaw plugins install @clawchatsai/connector
+openclaw gateway restart
 ```
 
-## Setup
+Then open [app.clawchats.ai](https://app.clawchats.ai) and follow the setup flow.
 
-After installing, run the setup command from your OpenClaw session:
+## Architecture
 
 ```
-/shellchat setup <token>
+server/                   # Local backend server (Node.js, plain ESM)
+  index.js                # createApp() factory — HTTP API + WebSocket relay to OpenClaw
+  gateway.js              # GatewayClient — maintains connection to local OpenClaw gateway
+  config.js               # Config discovery (env vars → openclaw.json → defaults)
+  debug.js                # Debug session logger
+  gateway-cleanup.js      # Session cleanup on thread/workspace delete
+  bootstrap/
+    native.js             # node:sqlite initialisation (built into Node ≥22.5, no compilation)
+    identity.js           # ed25519 device signing for OpenClaw ≥2.15
+  controllers/            # HTTP route handlers (threads, messages, workspaces, files, memory)
+  providers/              # Memory backends (Qdrant, Postgres)
+  util/                   # HTTP helpers, multipart parser, context builder, misc
+src/                      # OpenClaw plugin wrapper (TypeScript)
+  index.ts                # Plugin entry point — registers with OpenClaw, manages lifecycle
+  signaling-client.ts     # Connects to ClawChats signaling server for P2P handshake
+  webrtc-peer.ts          # WebRTC DataChannel peer — direct browser ↔ gateway connection
+  auth-handler.ts         # TOTP + Google session auth for DataChannel connections
 ```
 
-Get your token at [clawchats.ai](https://clawchats.ai)
+## Security & permissions
 
-## Update
+**Filesystem access:** The plugin reads/writes under `~/.openclaw/` (gateway data) and the user's home directory for workspace file browsing. File serving is restricted to an explicit allowlist (`HOME`, `/tmp`). Write access is limited to within `HOME`.
 
-```bash
-openclaw plugins update @clawchatsai/connector
-```
+**Session cleanup:** When a thread or workspace is deleted, the plugin removes the associated OpenClaw session files (`.jsonl`) to prevent stale context. These are files created by the gateway itself during that session.
+
+**Auth:** The DataChannel connection is authenticated with TOTP + Google session token before any data is processed. The HTTP API uses a local bearer token (set via `CLAWCHATS_AUTH_TOKEN` or `config.js`). No credentials are sent to external servers.
+
+**No shell execution:** The plugin contains no `exec`, `spawn`, or shell calls. SQLite is handled by Node's built-in `node:sqlite` module — no native binary compilation required.
+
+## Configuration
+
+Config is read in priority order:
+1. Environment variables (`CLAWCHATS_AUTH_TOKEN`, `GATEWAY_WS_URL`, `OPENCLAW_SESSIONS_DIR`)
+2. `~/.openclaw/openclaw.json` (OpenClaw gateway config)
+3. `config.js` in the plugin directory (local override, gitignored)
+
+## License
 
-## Links
+[AGPL-3.0-only](LICENSE) — source is open for audit and contribution.
 
-- [Website](https://clawchats.ai)
-- [npm](https://www.npmjs.com/package/@clawchatsai/connector)
+For commercial licensing, contact [clawchats.ai](https://clawchats.ai).

package/dist/index.js

@@ -71,7 +71,6 @@ async function ensureNativeModules(ctx) {
     // Check if native modules are usable; if not, rebuild them automatically.
     const pluginDir = path.resolve(__dirname, '..');
     const modules = [
-        { name: 'better-sqlite3', binding: 'build/Release/better_sqlite3.node', strategy: 'rebuild' },
         { name: 'node-datachannel', binding: 'build/Release/node_datachannel.node', strategy: 'install-script' },
     ];
     const missing = modules.filter(m => !fs.existsSync(path.join(pluginDir, 'node_modules', m.name, m.binding)));

package/openclaw.plugin.json

@@ -1,7 +1,7 @@
 {
   "id": "connector",
   "name": "ClawChats",
-  "description": "Connects your OpenClaw gateway to ClawChats via WebRTC P2P",
+  "description": "Local chat backend and API bridge for OpenClaw.",
   "kind": "integration",
   "configSchema": {
     "type": "object",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@clawchatsai/connector",
-  "version": "0.0.86",
+  "version": "0.0.87",
   "type": "module",
   "description": "ClawChats OpenClaw plugin — P2P tunnel + local API bridge",
   "main": "dist/index.js",
@@ -8,23 +8,22 @@
   "files": [
     "dist",
     "server.js",
+    "server/",
     "openclaw.plugin.json"
   ],
   "publishConfig": {
     "access": "public"
   },
   "engines": {
-    "node": ">=18"
+    "node": ">=22.5.0"
   },
   "scripts": {
     "prebuild": "node esbuild.config.mjs",
     "build": "tsc",
     "dev": "tsc --watch",
-    "prepublishOnly": "npm run build",
-    "postinstall": "npm rebuild better-sqlite3 2>/dev/null || true"
+    "prepublishOnly": "npm run build"
   },
   "dependencies": {
-    "better-sqlite3": ">=9.0.0",
     "jose": "^5.10.0",
     "node-datachannel": "^0.32.1",
     "ws": "^8.0.0"
@@ -38,5 +37,10 @@
     "@types/ws": "^8.0.0",
     "esbuild": "^0.27.4",
     "typescript": "^5.4.0"
+  },
+  "license": "AGPL-3.0-only",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/clawchatsai/connector"
   }
 }

package/server/bootstrap/identity.js

@@ -0,0 +1,47 @@
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+import path from 'node:path';
+
+const ED25519_SPKI_PREFIX = Buffer.from('302a300506032b6570032100', 'hex');
+
+function derivePublicKeyRaw(publicKeyPem) {
+  const spki = crypto.createPublicKey(publicKeyPem).export({ type: 'spki', format: 'der' });
+  if (spki.length === ED25519_SPKI_PREFIX.length + 32 &&
+      spki.subarray(0, ED25519_SPKI_PREFIX.length).equals(ED25519_SPKI_PREFIX)) {
+    return spki.subarray(ED25519_SPKI_PREFIX.length);
+  }
+  return spki;
+}
+
+function fingerprintPublicKey(publicKeyPem) {
+  return crypto.createHash('sha256').update(derivePublicKeyRaw(publicKeyPem)).digest('hex');
+}
+
+function base64UrlEncode(buf) {
+  return buf.toString('base64').replaceAll('+', '-').replaceAll('/', '_').replace(/=+$/g, '');
+}
+
+export function loadOrCreateDeviceIdentity(identityPath) {
+  try {
+    if (fs.existsSync(identityPath)) {
+      const parsed = JSON.parse(fs.readFileSync(identityPath, 'utf8'));
+      if (parsed?.version === 1 && parsed.deviceId && parsed.publicKeyPem && parsed.privateKeyPem) return parsed;
+    }
+  } catch { /* regenerate */ }
+  const { publicKey, privateKey } = crypto.generateKeyPairSync('ed25519');
+  const publicKeyPem = publicKey.export({ type: 'spki', format: 'pem' }).toString();
+  const privateKeyPem = privateKey.export({ type: 'pkcs8', format: 'pem' }).toString();
+  const identity = { version: 1, deviceId: fingerprintPublicKey(publicKeyPem), publicKeyPem, privateKeyPem, createdAtMs: Date.now() };
+  fs.mkdirSync(path.dirname(identityPath), { recursive: true });
+  fs.writeFileSync(identityPath, JSON.stringify(identity, null, 2) + '\n', { mode: 0o600 });
+  return identity;
+}
+
+export function buildDeviceAuth(identity, { clientId, clientMode, role, scopes, token, nonce }) {
+  const signedAt = Date.now();
+  const payload = ['v2', identity.deviceId, clientId, clientMode, role, scopes.join(','), String(signedAt), token || '', nonce].join('|');
+  const privateKey = crypto.createPrivateKey(identity.privateKeyPem);
+  const signature = base64UrlEncode(crypto.sign(null, Buffer.from(payload, 'utf8'), privateKey));
+  const publicKeyB64Url = base64UrlEncode(derivePublicKeyRaw(identity.publicKeyPem));
+  return { id: identity.deviceId, publicKey: publicKeyB64Url, signature, signedAt, nonce };
+}

package/server/bootstrap/native.js

@@ -0,0 +1,9 @@
+import { DatabaseSync as Database } from 'node:sqlite';
+import { AsyncLocalStorage } from 'node:async_hooks';
+
+// Per-request workspace DB — isolates concurrent clients on different workspaces.
+export const requestDbStore = new AsyncLocalStorage();
+
+// node:sqlite is a built-in Node.js module (available since Node 22.5).
+// No native compilation required — SQLite is bundled directly into Node.
+export { Database };

package/server/config.js

@@ -0,0 +1,62 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+import { fileURLToPath } from 'node:url';
+
+export const HOME = os.homedir();
+export const MAX_PREAMBLE_CHARS = 50000;
+
+// Resolve __dirname for ESM (esbuild inlines this correctly)
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+export function parseConfigField(field) {
+  // Try both plugin root and parent of server/ — handles bundled and standalone modes
+  const candidates = [path.join(__dirname, 'config.js'), path.join(__dirname, '..', 'config.js')];
+  for (const configPath of candidates) {
+    try {
+      const configText = fs.readFileSync(configPath, 'utf8');
+      const match = configText.match(new RegExp(`${field}:\\s*['"]([^'"]+)['"]`));
+      if (match) return match[1];
+    } catch { /* try next */ }
+  }
+  return null;
+}
+
+// Auth token: env var → config.js → empty (open/unauthenticated mode)
+export const AUTH_TOKEN = process.env.CLAWCHATS_AUTH_TOKEN || parseConfigField('authToken') || '';
+
+// Gateway WebSocket URL — uses the internal/local gateway address, NOT config.js gatewayUrl
+// (that's the browser's external-facing URL and would cause a routing loop through Caddy)
+export function discoverGatewayWsUrl() {
+  if (process.env.GATEWAY_WS_URL) return process.env.GATEWAY_WS_URL;
+  for (const cfgPath of [path.join(HOME, '.openclaw', 'openclaw.json'), '/etc/openclaw/openclaw.json']) {
+    try {
+      const raw = JSON.parse(fs.readFileSync(cfgPath, 'utf8'));
+      const port = raw.gateway?.port || raw.port;
+      const host = raw.gateway?.host || raw.host || 'localhost';
+      if (port) return `ws://${host}:${port}`;
+    } catch { /* try next */ }
+  }
+  return 'ws://localhost:18789';
+}
+export const GATEWAY_WS_URL = discoverGatewayWsUrl();
+
+// Sessions directory — where OpenClaw stores session .jsonl files
+export const OPENCLAW_SESSIONS_DIR =
+  process.env.OPENCLAW_SESSIONS_DIR ||
+  parseConfigField('sessionsDir') ||
+  path.join(HOME, '.openclaw', 'agents', 'main', 'sessions');
+
+export function getSessionsDirForAgent(agentId) {
+  if (!agentId || agentId === 'main') return OPENCLAW_SESSIONS_DIR;
+  return path.join(HOME, '.openclaw', 'agents', agentId, 'sessions');
+}
+
+export function validateAgent(agentId) {
+  if (!agentId) return 'main';
+  if (!/^[a-zA-Z0-9_-]+$/.test(agentId)) throw new Error('Invalid agent ID');
+  const agentDir = path.join(HOME, '.openclaw', 'agents', agentId);
+  if (!fs.existsSync(agentDir)) throw new Error(`Agent not found: ${agentId}`);
+  return agentId;
+}

package/server/controllers/files.js

@@ -0,0 +1,64 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { send, sendError, parseBody, uuid } from '../util/http.js';
+import { parseMultipart } from '../util/multipart.js';
+
+export class FileController {
+  constructor({ getActiveDb, getWorkspaces, uploadsDir, intelligenceDir }) {
+    this.getActiveDb = getActiveDb;
+    this.getWorkspaces = getWorkspaces;
+    this.uploadsDir = uploadsDir;
+    this.intelligenceDir = intelligenceDir;
+  }
+
+  async upload(req, res, params) {
+    if (!this.getActiveDb().prepare('SELECT id FROM threads WHERE id = ?').get(params.id)) return sendError(res, 404, 'Thread not found');
+    const files = await parseMultipart(req);
+    const dir = path.join(this.uploadsDir, params.id);
+    fs.mkdirSync(dir, { recursive: true });
+    const savedFiles = [];
+    for (const file of files) {
+      const fileId = uuid();
+      const ext = path.extname(file.filename) || '';
+      fs.writeFileSync(path.join(dir, fileId + ext), file.data);
+      savedFiles.push({ id: fileId, filename: file.filename, path: `/api/uploads/${params.id}/${fileId}${ext}`, mimeType: file.mimeType, size: file.data.length });
+    }
+    send(res, 200, { files: savedFiles });
+  }
+
+  serveUpload(req, res, params) {
+    const base = path.join(this.uploadsDir, params.threadId, params.fileId);
+    let resolved = base;
+    if (!fs.existsSync(resolved)) {
+      try {
+        const match = fs.readdirSync(path.join(this.uploadsDir, params.threadId)).find(e => e.startsWith(params.fileId.replace(/\.[^.]+$/, '')));
+        if (match) resolved = path.join(this.uploadsDir, params.threadId, match);
+      } catch { /* ok */ }
+    }
+    if (!fs.existsSync(resolved)) return sendError(res, 404, 'File not found');
+    const MIME = { '.png': 'image/png', '.jpg': 'image/jpeg', '.jpeg': 'image/jpeg', '.gif': 'image/gif', '.webp': 'image/webp', '.pdf': 'application/pdf', '.txt': 'text/plain', '.json': 'application/json' };
+    const stat = fs.statSync(resolved);
+    res.writeHead(200, { 'Content-Type': MIME[path.extname(resolved).toLowerCase()] || 'application/octet-stream', 'Content-Length': stat.size, 'Cache-Control': 'public, max-age=86400', 'Access-Control-Allow-Origin': '*' });
+    fs.createReadStream(resolved).pipe(res);
+  }
+
+  _intelligencePath(threadId) {
+    return path.join(this.intelligenceDir, this.getWorkspaces().active, `${threadId}.json`);
+  }
+
+  getIntelligence(req, res, params) {
+    const filePath = this._intelligencePath(params.id);
+    if (!fs.existsSync(filePath)) return send(res, 200, { versions: [], currentVersion: -1 });
+    try { return send(res, 200, JSON.parse(fs.readFileSync(filePath, 'utf8'))); }
+    catch { return send(res, 200, { versions: [], currentVersion: -1 }); }
+  }
+
+  async saveIntelligence(req, res, params) {
+    const body = await parseBody(req);
+    const filePath = this._intelligencePath(params.id);
+    fs.mkdirSync(path.dirname(filePath), { recursive: true });
+    const data = { versions: body.versions || [], currentVersion: body.currentVersion ?? -1, updatedAt: Date.now() };
+    fs.writeFileSync(filePath, JSON.stringify(data, null, 2));
+    send(res, 200, data);
+  }
+}

package/server/controllers/filesystem.js

@@ -0,0 +1,139 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+import { send, sendError } from '../util/http.js';
+import { parseMultipart } from '../util/multipart.js';
+
+const HOME = os.homedir();
+const ALLOWED_FILE_DIRS = [HOME, '/tmp'];
+
+export function handleServeFile(req, res, query, memoryConfig) {
+  const filePath = query.path;
+  if (!filePath) return sendError(res, 400, 'Missing path parameter');
+  const resolved = (filePath.startsWith('./') || filePath.startsWith('../'))
+    ? path.resolve(memoryConfig.workspaceDir, filePath)
+    : path.resolve(filePath);
+  if (!ALLOWED_FILE_DIRS.some(dir => resolved.startsWith(dir + '/') || resolved === dir)) return sendError(res, 403, 'Access denied: path not in allowed directories');
+  if (!fs.existsSync(resolved) || !fs.statSync(resolved).isFile()) return sendError(res, 404, 'File not found');
+
+  const MIME = {
+    '.png': 'image/png', '.jpg': 'image/jpeg', '.jpeg': 'image/jpeg',
+    '.gif': 'image/gif', '.webp': 'image/webp', '.svg': 'image/svg+xml',
+    '.pdf': 'application/pdf', '.txt': 'text/plain', '.json': 'application/json',
+    '.md': 'text/markdown', '.csv': 'text/csv', '.xml': 'text/xml',
+    '.html': 'text/html', '.css': 'text/css', '.js': 'text/javascript',
+    '.py': 'text/x-python', '.sh': 'text/x-shellscript',
+    '.yaml': 'text/yaml', '.yml': 'text/yaml', '.toml': 'text/toml',
+    '.zip': 'application/zip', '.gz': 'application/gzip', '.tar': 'application/x-tar',
+    '.xlsx': 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet',
+    '.docx': 'application/vnd.openxmlformats-officedocument.wordprocessingml.document',
+    '.mp3': 'audio/mpeg', '.wav': 'audio/wav', '.ogg': 'audio/ogg',
+    '.mp4': 'video/mp4', '.webm': 'video/webm',
+  };
+  const stat = fs.statSync(resolved);
+  res.writeHead(200, { 'Content-Type': MIME[path.extname(resolved).toLowerCase()] || 'application/octet-stream', 'Content-Length': stat.size, 'Cache-Control': 'public, max-age=86400', 'Access-Control-Allow-Origin': '*' });
+  fs.createReadStream(resolved).pipe(res);
+}
+
+export function handleWorkspaceList(req, res, query) {
+  const reqPath = query.path || '~/.openclaw/workspace';
+  const depth = parseInt(query.depth || '2', 10);
+  const showHidden = query.hidden === '1' || query.hidden === 'true';
+  const resolved = path.resolve(reqPath.replace(/^~/, HOME));
+  if (!resolved.startsWith(HOME)) return sendError(res, 403, 'Access denied');
+  if (!fs.existsSync(resolved)) return sendError(res, 404, 'Path not found');
+
+  const files = [{ path: resolved + '/', type: 'dir', name: path.basename(resolved), size: 0 }];
+  const walk = (dir, d) => {
+    if (d > depth) return;
+    try {
+      for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+        if (entry.name.startsWith('.') && entry.name !== '.openclaw' && !showHidden) continue;
+        if (entry.name === 'node_modules') continue;
+        const fullPath = path.join(dir, entry.name);
+        const isDir = entry.isDirectory();
+        files.push({ path: fullPath + (isDir ? '/' : ''), type: isDir ? 'dir' : 'file', name: entry.name, size: isDir ? 0 : (() => { try { return fs.statSync(fullPath).size; } catch { return 0; } })() });
+        if (isDir) walk(fullPath, d + 1);
+      }
+    } catch { /* permission denied */ }
+  };
+  walk(resolved, 1);
+  send(res, 200, { files, cwd: resolved });
+}
+
+export function handleWorkspaceFileRead(req, res, query) {
+  const filePath = query.path;
+  if (!filePath) return sendError(res, 400, 'Missing path parameter');
+  const resolved = path.resolve(filePath.replace(/^~/, HOME));
+  if (!resolved.startsWith(HOME)) return sendError(res, 403, 'Access denied');
+  if (!fs.existsSync(resolved) || !fs.statSync(resolved).isFile()) return sendError(res, 404, 'File not found');
+
+  const stat = fs.statSync(resolved);
+  const ext = path.extname(resolved).toLowerCase().slice(1);
+  const binaryMime = { png: 'image/png', jpg: 'image/jpeg', jpeg: 'image/jpeg', gif: 'image/gif', webp: 'image/webp', svg: 'image/svg+xml', bmp: 'image/bmp', ico: 'image/x-icon', pdf: 'application/pdf', mp3: 'audio/mpeg', mp4: 'video/mp4', wav: 'audio/wav', ogg: 'audio/ogg', webm: 'video/webm' };
+  const mime = binaryMime[ext];
+
+  if (mime) {
+    if (stat.size > 20 * 1024 * 1024) return sendError(res, 413, 'File too large (max 20MB)');
+    res.writeHead(200, { 'Content-Type': mime, 'Cache-Control': 'private, max-age=60' });
+    res.end(fs.readFileSync(resolved));
+  } else {
+    if (stat.size > 1024 * 1024) return sendError(res, 413, 'File too large (max 1MB)');
+    res.writeHead(200, { 'Content-Type': 'text/plain; charset=utf-8' });
+    res.end(fs.readFileSync(resolved, 'utf8'));
+  }
+}
+
+export async function handleWorkspaceFileWrite(req, res, query) {
+  const filePath = query.path;
+  if (!filePath) return sendError(res, 400, 'Missing path parameter');
+  const resolved = path.resolve(filePath.replace(/^~/, HOME));
+  if (!resolved.startsWith(HOME)) return sendError(res, 403, 'Can only write to workspace directory');
+  const chunks = [];
+  for await (const chunk of req) chunks.push(chunk);
+  const dir = path.dirname(resolved);
+  if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
+  fs.writeFileSync(resolved, Buffer.concat(chunks).toString('utf8'), 'utf8');
+  send(res, 200, { ok: true });
+}
+
+export function handleWorkspaceFileDelete(req, res, query) {
+  const filePath = query.path;
+  if (!filePath) return sendError(res, 400, 'Missing path parameter');
+  const resolved = path.resolve(filePath.replace(/^~/, HOME));
+  if (!resolved.startsWith(HOME)) return sendError(res, 403, 'Access denied');
+  if (!fs.existsSync(resolved)) return sendError(res, 404, 'Path not found');
+  try {
+    const stat = fs.statSync(resolved);
+    if (stat.isDirectory()) { fs.rmSync(resolved, { recursive: true, force: true }); send(res, 200, { ok: true, type: 'dir' }); }
+    else { fs.unlinkSync(resolved); send(res, 200, { ok: true, type: 'file' }); }
+  } catch (err) { sendError(res, 500, 'Delete failed: ' + err.message); }
+}
+
+export async function handleWorkspaceUpload(req, res, query) {
+  const targetDir = query.path;
+  if (!targetDir) return sendError(res, 400, 'Missing path parameter');
+  const resolved = path.resolve(targetDir.replace(/^~/, HOME));
+  if (!resolved.startsWith(HOME)) return sendError(res, 403, 'Access denied');
+  if (!fs.existsSync(resolved) || !fs.statSync(resolved).isDirectory()) return sendError(res, 404, 'Target directory not found');
+  if (!(req.headers['content-type'] || '').includes('multipart/form-data')) return sendError(res, 400, 'Expected multipart/form-data');
+
+  let files;
+  try { files = await parseMultipart(req); }
+  catch (err) { return sendError(res, 400, 'Invalid multipart data: ' + err.message); }
+
+  const uploaded = [];
+  for (const { filename, data } of files) {
+    if (!filename || !data.length) continue;
+    const safeName = path.basename(filename);
+    let finalPath = path.join(resolved, safeName);
+    let counter = 1;
+    while (fs.existsSync(finalPath)) {
+      const ext = path.extname(safeName);
+      finalPath = path.join(resolved, `${path.basename(safeName, ext)} (${counter++})${ext}`);
+    }
+    fs.writeFileSync(finalPath, data);
+    uploaded.push({ name: path.basename(finalPath), size: data.length });
+  }
+  send(res, 200, { ok: true, uploaded });
+}

package/server/controllers/memory.js

@@ -0,0 +1,86 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { send, sendError } from '../util/http.js';
+
+export class MemoryController {
+  constructor({ memoryProvider, memoryFilesDir, memoryConfig }) {
+    this.provider = memoryProvider;
+    this.filesDir = memoryFilesDir;
+    this.config = memoryConfig;
+  }
+
+  async list(req, res, query) {
+    const limit = Math.min(parseInt(query.limit) || 20, 100);
+    try { send(res, 200, await this.provider.list(limit, query.offset || null)); }
+    catch (err) { send(res, 502, { error: `Failed to reach ${this.provider.name}`, detail: err.message }); }
+  }
+
+  async search(req, res, query) {
+    const q = (query.query || '').toLowerCase().trim();
+    if (!q) return send(res, 400, { error: 'Missing query parameter' });
+    try { send(res, 200, await this.provider.search(q)); }
+    catch (err) { send(res, 502, { error: `Failed to reach ${this.provider.name}`, detail: err.message }); }
+  }
+
+  files(req, res, query) {
+    const q = (query.query || '').toLowerCase().trim();
+    const memories = this._parseFiles();
+    const filtered = q ? memories.filter(m => m.data.toLowerCase().includes(q) || m.title.toLowerCase().includes(q)) : memories;
+    filtered.sort((a, b) => (b.createdAt || '').localeCompare(a.createdAt || ''));
+    send(res, 200, { memories: filtered });
+  }
+
+  _parseFiles() {
+    const memories = [];
+    const scanDir = (dir, prefix = '') => {
+      let entries;
+      try { entries = fs.readdirSync(dir); } catch { return; }
+      for (const entry of entries) {
+        const fullPath = path.join(dir, entry);
+        const stat = (() => { try { return fs.statSync(fullPath); } catch { return null; } })();
+        if (!stat) continue;
+        if (stat.isDirectory() && !prefix) { scanDir(fullPath, entry + '/'); continue; }
+        if (!entry.endsWith('.md') || !stat.isFile()) continue;
+        const content = fs.readFileSync(fullPath, 'utf8');
+        const basename = entry.replace(/\.md$/, '');
+        const dateMatch = basename.match(/^(\d{4}-\d{2}-\d{2})/);
+        if (prefix) {
+          memories.push({ id: `file:${prefix + basename}`, source: 'file', file: prefix + basename, title: basename, data: content.trim(), createdAt: stat.mtime.toISOString() });
+        } else {
+          for (const section of content.split(/^(?=## )/m)) {
+            const trimmed = section.trim();
+            if (!trimmed) continue;
+            const headingMatch = trimmed.match(/^##\s+(.+)/);
+            const heading = headingMatch ? headingMatch[1].trim() : null;
+            const body = headingMatch ? trimmed.slice(trimmed.indexOf('\n') + 1).trim() : trimmed;
+            if (!heading && body.match(/^#\s+/) && body.split('\n').length <= 2) continue;
+            const title = heading || basename;
+            memories.push({ id: `file:${basename}:${title}`, source: 'file', file: basename, title, data: heading ? `**${title}**\n${body}` : body, createdAt: dateMatch ? `${dateMatch[1]}T00:00:00Z` : stat.mtime.toISOString() });
+          }
+        }
+      }
+    };
+    scanDir(this.filesDir);
+    return memories;
+  }
+
+  async update(req, res, params) {
+    try {
+      const chunks = [];
+      for await (const chunk of req) chunks.push(chunk);
+      const { data } = JSON.parse(Buffer.concat(chunks).toString());
+      if (!(data || '').trim()) return send(res, 400, { error: 'Missing data field' });
+      send(res, 200, { ok: true, result: await this.provider.update(params.id, data.trim()) });
+    } catch (err) { send(res, 502, { error: 'Failed to update memory', detail: err.message }); }
+  }
+
+  async delete(req, res, params) {
+    try { send(res, 200, { ok: true, result: await this.provider.delete(params.id) }); }
+    catch (err) { send(res, 502, { error: `Failed to reach ${this.provider.name}`, detail: err.message }); }
+  }
+
+  async status(req, res) {
+    const status = await this.provider.status();
+    send(res, 200, { provider: this.provider.name, host: this.config.host, port: this.config.port, collection: this.config.collection, backend: status, memoryFilesDir: this.filesDir, memoryFilesDirExists: fs.existsSync(this.filesDir) });
+  }
+}