mr-memory 1.0.0

package/README.md

@@ -0,0 +1,67 @@
+# mr-memory
+
+Persistent AI memory plugin for [OpenClaw](https://github.com/openclaw/openclaw). Your AI remembers every conversation.
+
+Powered by [MemoryRouter](https://memoryrouter.ai).
+
+## Install
+
+```bash
+openclaw plugins install mr-memory
+```
+
+## Setup
+
+```bash
+openclaw mr enable <your-memory-key>   # Get a key at memoryrouter.ai
+openclaw mr upload                     # Upload workspace + session history
+```
+
+## Commands
+
+```bash
+openclaw mr status           # Vault stats
+openclaw mr upload           # Upload workspace + sessions
+openclaw mr upload --brain ~/.notopenclaw   # Upload from a different agent
+openclaw mr off              # Disable
+openclaw mr delete           # Clear vault
+openclaw mr enable <key>     # Enable with key
+```
+
+## Upload Options
+
+```bash
+openclaw mr upload [path]              # Specific file or directory
+openclaw mr upload --workspace <dir>   # Custom workspace directory
+openclaw mr upload --brain <dir>       # Custom state dir (sessions from another agent)
+```
+
+## How It Works
+
+When enabled, all LLM calls route through MemoryRouter which injects relevant past context and captures new conversations. Your provider API keys pass through untouched (BYOK).
+
+Only direct user-to-AI conversation is stored. Tool use and subagent work are excluded automatically.
+
+## Config
+
+After `openclaw mr enable <key>`, config is stored at:
+
+```json
+{
+  "plugins": {
+    "entries": {
+      "memoryrouter": {
+        "enabled": true,
+        "config": {
+          "key": "mk_xxx",
+          "endpoint": "https://api.memoryrouter.ai"
+        }
+      }
+    }
+  }
+}
+```
+
+## License
+
+MIT

package/index.ts

@@ -0,0 +1,236 @@
+/**
+ * MemoryRouter Plugin for OpenClaw
+ *
+ * Persistent AI memory via MemoryRouter (memoryrouter.ai).
+ * Routes LLM calls through MemoryRouter's API which injects relevant
+ * past context and captures conversations automatically.
+ *
+ * BYOK — provider API keys pass through untouched.
+ */
+
+import type { OpenClawPluginApi } from "openclaw/plugin-sdk";
+
+const DEFAULT_ENDPOINT = "https://api.memoryrouter.ai";
+
+type MemoryRouterConfig = {
+  key: string;
+  endpoint?: string;
+};
+
+/**
+ * Supported provider APIs that MemoryRouter can proxy.
+ */
+const SUPPORTED_APIS = new Set([
+  "anthropic-messages",
+  "openai-completions",
+  "openai-responses",
+  "azure-openai-responses",
+  "ollama",
+]);
+
+/**
+ * Detect if the current LLM call is a tool-use iteration (not direct user conversation).
+ * Tool iterations have tool_result (Anthropic) or tool-role (OpenAI) messages
+ * after the last real user message.
+ */
+function isToolUseIteration(context: { messages?: Array<{ role: string; content?: unknown }> }): boolean {
+  const messages = context.messages;
+  if (!messages || messages.length === 0) return false;
+
+  for (let i = messages.length - 1; i >= 0; i--) {
+    const msg = messages[i];
+
+    if (msg.role === "tool") return true;
+
+    if (msg.role === "user" && Array.isArray(msg.content)) {
+      const hasToolResult = (msg.content as Array<{ type?: string }>).some(
+        (block) => block.type === "tool_result",
+      );
+      if (hasToolResult) return true;
+    }
+
+    if (msg.role === "user" && typeof msg.content === "string") return false;
+    if (msg.role === "assistant") continue;
+  }
+
+  return false;
+}
+
+const memoryRouterPlugin = {
+  id: "memoryrouter",
+  name: "MemoryRouter",
+  description: "Persistent AI memory powered by MemoryRouter",
+
+  register(api: OpenClawPluginApi) {
+    const cfg = api.pluginConfig as MemoryRouterConfig | undefined;
+    const endpoint = cfg?.endpoint?.replace(/\/v1\/?$/, "") || DEFAULT_ENDPOINT;
+    const memoryKey = cfg?.key;
+
+    // ==================================================================
+    // Core: Route LLM calls through MemoryRouter (only when key is set)
+    // ==================================================================
+
+    if (memoryKey) {
+      api.logger.info?.(`memoryrouter: registered (endpoint: ${endpoint})`);
+    } else {
+      api.logger.info?.("memoryrouter: no key configured — run: openclaw mr enable <key>");
+    }
+
+    if (memoryKey) {
+      api.registerStreamFnWrapper((next) => {
+      return (model, context, options) => {
+        // Only proxy supported APIs
+        if (!SUPPORTED_APIS.has(model.api)) {
+          return next(model, context, options);
+        }
+
+        // Route through MemoryRouter
+        const mrModel = {
+          ...model,
+          baseUrl: model.api === "anthropic-messages"
+            ? endpoint  // Anthropic: baseUrl is without /v1
+            : `${endpoint}/v1`,
+        };
+
+        // Detect tool iterations — don't store intermediate work
+        const toolIteration = isToolUseIteration(
+          context as { messages?: Array<{ role: string; content?: unknown }> },
+        );
+
+        // Inject MemoryRouter headers
+        const mrOptions = {
+          ...options,
+          headers: {
+            ...options?.headers,
+            "X-Memory-Key": memoryKey,
+            "X-Memory-Store": toolIteration ? "false" : "true",
+          },
+        };
+
+        return next(mrModel, context, mrOptions);
+      };
+    });
+    } // end if (memoryKey) for streamFn wrapper
+
+    // ==================================================================
+    // CLI Commands (always registered — even without key, for enable/off)
+    // ==================================================================
+
+    api.registerCli(
+      ({ program }) => {
+        const mr = program.command("mr").description("MemoryRouter memory commands");
+
+        mr.command("enable")
+          .description("Enable MemoryRouter with a memory key")
+          .argument("<key>", "Your MemoryRouter memory key (mk_xxx)")
+          .action(async (key: string) => {
+            if (!key.startsWith("mk")) {
+              console.error("Invalid key format. Keys start with 'mk' (e.g. mk_xxx)");
+              return;
+            }
+            await api.updatePluginConfig({ key });
+            await api.updatePluginEnabled(true);
+            console.log(`✓ MemoryRouter enabled. Key: ${key.slice(0, 6)}...${key.slice(-3)}`);
+            console.log(`\nRun: openclaw mr upload    to upload your memories`);
+          });
+
+        mr.command("off")
+          .description("Disable MemoryRouter (removes key)")
+          .action(async () => {
+            await api.updatePluginConfig({});
+            console.log("✓ MemoryRouter disabled. LLM calls go direct to provider.");
+            console.log("  Key removed. Re-enable with: openclaw mr enable <key>");
+          });
+
+        mr.command("status")
+          .description("Show MemoryRouter vault stats")
+          .option("--json", "JSON output")
+          .action(async (opts) => {
+            if (!memoryKey) {
+              console.error("MemoryRouter not configured. Run: openclaw mr enable <key>");
+              return;
+            }
+            try {
+              const res = await fetch(`${endpoint}/v1/memory/stats`, {
+                headers: { Authorization: `Bearer ${memoryKey}` },
+              });
+              const data = await res.json() as Record<string, unknown>;
+
+              if (opts.json) {
+                console.log(JSON.stringify({ enabled: true, key: memoryKey, stats: data }, null, 2));
+              } else {
+                console.log("MemoryRouter Status");
+                console.log("───────────────────────────");
+                console.log(`Enabled:     ✓ Yes`);
+                console.log(`Key:         ${memoryKey.slice(0, 6)}...${memoryKey.slice(-3)}`);
+                console.log(`Endpoint:    ${endpoint}`);
+                console.log("");
+                console.log("Vault Stats:");
+                const stats = data as { totalVectors?: number; totalTokens?: number };
+                console.log(`  Memories:  ${stats.totalVectors ?? 0}`);
+                console.log(`  Tokens:    ${stats.totalTokens ?? 0}`);
+              }
+            } catch (err) {
+              console.error(`Failed to fetch stats: ${err instanceof Error ? err.message : String(err)}`);
+            }
+          });
+
+        mr.command("upload")
+          .description("Upload workspace + session history to vault")
+          .argument("[path]", "Specific file or directory to upload")
+          .option("--workspace <dir>", "Workspace directory (default: cwd)")
+          .option("--brain <dir>", "State directory with sessions (default: ~/.openclaw)")
+          .action(async (targetPath: string | undefined, opts: { workspace?: string; brain?: string }) => {
+            if (!memoryKey) {
+              console.error("MemoryRouter not configured. Run: openclaw mr enable <key>");
+              return;
+            }
+            const os = await import("node:os");
+            const path = await import("node:path");
+            const stateDir = opts.brain ? path.resolve(opts.brain) : path.join(os.homedir(), ".openclaw");
+            const workspacePath = opts.workspace ? path.resolve(opts.workspace) : process.cwd();
+            const { runUpload } = await import("./upload.js");
+            await runUpload({ memoryKey, endpoint, targetPath, stateDir, workspacePath });
+          });
+
+        mr.command("delete")
+          .description("Clear all memories from vault")
+          .action(async () => {
+            if (!memoryKey) {
+              console.error("MemoryRouter not configured. Run: openclaw mr enable <key>");
+              return;
+            }
+            try {
+              const res = await fetch(`${endpoint}/v1/memory`, {
+                method: "DELETE",
+                headers: { Authorization: `Bearer ${memoryKey}` },
+              });
+              const data = await res.json() as { message?: string };
+              console.log(`✓ ${data.message || "Vault cleared"}`);
+            } catch (err) {
+              console.error(`Failed to clear vault: ${err instanceof Error ? err.message : String(err)}`);
+            }
+          });
+      },
+      { commands: ["mr"] },
+    );
+
+    // ==================================================================
+    // Service
+    // ==================================================================
+
+    api.registerService({
+      id: "memoryrouter",
+      start: () => {
+        if (memoryKey) {
+          api.logger.info?.(`memoryrouter: active (key: ${memoryKey.slice(0, 6)}...)`);
+        }
+      },
+      stop: () => {
+        api.logger.info?.("memoryrouter: stopped");
+      },
+    });
+  },
+};
+
+export default memoryRouterPlugin;

package/openclaw.plugin.json

@@ -0,0 +1,31 @@
+{
+  "id": "memoryrouter",
+  "uiHints": {
+    "key": {
+      "label": "Memory Key",
+      "sensitive": true,
+      "placeholder": "mk_xxx",
+      "help": "Your MemoryRouter API key (get one at memoryrouter.ai)"
+    },
+    "endpoint": {
+      "label": "API Endpoint",
+      "placeholder": "https://api.memoryrouter.ai/v1",
+      "advanced": true,
+      "help": "Override for self-hosted MemoryRouter"
+    }
+  },
+  "configSchema": {
+    "type": "object",
+    "additionalProperties": false,
+    "properties": {
+      "key": {
+        "type": "string",
+        "pattern": "^mk[_-]"
+      },
+      "endpoint": {
+        "type": "string"
+      }
+    },
+    "required": []
+  }
+}

package/package.json

@@ -0,0 +1,28 @@
+{
+  "name": "mr-memory",
+  "version": "1.0.0",
+  "description": "MemoryRouter persistent memory plugin for OpenClaw — your AI remembers every conversation",
+  "type": "module",
+  "keywords": [
+    "openclaw",
+    "openclaw-plugin",
+    "memory",
+    "memoryrouter",
+    "ai-memory",
+    "persistent-memory",
+    "rag"
+  ],
+  "author": "John Rood <john@memoryrouter.ai>",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/John-Rood/MemoryRouter.git",
+    "directory": "integrations/openclaw-plugin"
+  },
+  "homepage": "https://memoryrouter.ai/openclaw",
+  "openclaw": {
+    "extensions": [
+      "./index.ts"
+    ]
+  }
+}

package/upload.ts

@@ -0,0 +1,309 @@
+/**
+ * MemoryRouter Upload — File discovery, parsing, batching, and upload.
+ */
+
+import fs from "node:fs/promises";
+import path from "node:path";
+
+type MemoryLine = {
+  content: string;
+  role: "user" | "assistant";
+  timestamp: number;
+};
+
+const MAX_ITEM_CHARS = 8000;
+const TARGET_CHUNK_CHARS = 4000;
+const MAX_BATCH_BYTES = 2_000_000;
+const MAX_BATCH_COUNT = 100;
+const BATCH_SLEEP_MS = 150;
+const MAX_HTTP_RETRIES = 3;
+
+function sleep(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+function chunkText(text: string, targetChars: number): string[] {
+  const chunks: string[] = [];
+  let remaining = text;
+
+  while (remaining.length > targetChars) {
+    let splitAt = remaining.lastIndexOf("\n\n", targetChars);
+    if (splitAt < targetChars * 0.5) {
+      splitAt = remaining.lastIndexOf("\n", targetChars);
+    }
+    if (splitAt < targetChars * 0.5) {
+      splitAt = remaining.lastIndexOf(" ", targetChars);
+    }
+    if (splitAt < targetChars * 0.3) {
+      splitAt = targetChars;
+    }
+    chunks.push(remaining.slice(0, splitAt).trim());
+    remaining = remaining.slice(splitAt).trim();
+  }
+  if (remaining) {
+    chunks.push(remaining);
+  }
+  return chunks;
+}
+
+async function fileToJsonl(filePath: string): Promise<MemoryLine[]> {
+  const content = await fs.readFile(filePath, "utf-8");
+  const stat = await fs.stat(filePath);
+  const timestamp = Math.floor(stat.mtimeMs);
+  const filename = path.basename(filePath);
+
+  const trimmed = content.trim();
+  if (trimmed.length < 50) return [];
+
+  if (trimmed.length <= MAX_ITEM_CHARS) {
+    return [{ content: `[${filename}] ${trimmed}`, role: "user", timestamp }];
+  }
+
+  const chunks = chunkText(trimmed, TARGET_CHUNK_CHARS);
+  return chunks.map((chunk, i) => ({
+    content: `[${filename} part ${i + 1}/${chunks.length}] ${chunk}`,
+    role: "user" as const,
+    timestamp,
+  }));
+}
+
+async function sessionToJsonl(filePath: string): Promise<MemoryLine[]> {
+  const content = await fs.readFile(filePath, "utf-8");
+  const lines: MemoryLine[] = [];
+
+  for (const line of content.split("\n")) {
+    if (!line.trim()) continue;
+    try {
+      const parsed = JSON.parse(line);
+      if (parsed.type !== "message") continue;
+      const msg = parsed.message;
+      if (!msg || !msg.role) continue;
+      if (msg.role !== "user" && msg.role !== "assistant") continue;
+
+      let text = "";
+      if (typeof msg.content === "string") {
+        text = msg.content;
+      } else if (Array.isArray(msg.content)) {
+        text = msg.content
+          .filter((block: { type: string }) => block.type === "text")
+          .map((block: { text: string }) => block.text)
+          .join("\n");
+      }
+
+      if (!text || text.trim().length < 20) continue;
+
+      let timestamp: number;
+      if (typeof parsed.timestamp === "string") {
+        timestamp = new Date(parsed.timestamp).getTime();
+      } else if (typeof parsed.timestamp === "number") {
+        timestamp = parsed.timestamp;
+      } else {
+        timestamp = Date.now();
+      }
+
+      lines.push({ content: text.trim(), role: msg.role, timestamp });
+    } catch {
+      // Skip invalid lines
+    }
+  }
+  return lines;
+}
+
+async function exists(p: string): Promise<boolean> {
+  try {
+    await fs.access(p);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+async function discoverFiles(workspacePath: string, stateDir: string): Promise<string[]> {
+  const files: string[] = [];
+
+  const memoryMd = path.join(workspacePath, "MEMORY.md");
+  if (await exists(memoryMd)) files.push(memoryMd);
+
+  const memoryDir = path.join(workspacePath, "memory");
+  if (await exists(memoryDir)) {
+    const allMemFiles = await fs.readdir(memoryDir, { recursive: true });
+    const mdFiles = (allMemFiles as string[]).filter((f) => f.endsWith(".md"));
+    files.push(...mdFiles.map((f) => path.join(memoryDir, f)));
+  }
+
+  for (const contextFile of ["AGENTS.md", "TOOLS.md"]) {
+    const p = path.join(workspacePath, contextFile);
+    if (await exists(p)) files.push(p);
+  }
+
+  const sessionsDir = path.join(stateDir, "agents", "main", "sessions");
+  if (await exists(sessionsDir)) {
+    const allSessionFiles = await fs.readdir(sessionsDir);
+    const sessionFiles = (allSessionFiles as string[]).filter((f) => f.endsWith(".jsonl"));
+    files.push(...sessionFiles.map((f) => path.join(sessionsDir, f)));
+  }
+
+  return files;
+}
+
+async function fetchWithRetry(
+  url: string,
+  init: RequestInit,
+  label: string,
+): Promise<Response> {
+  let lastError: Error | null = null;
+  for (let attempt = 1; attempt <= MAX_HTTP_RETRIES; attempt++) {
+    try {
+      const res = await fetch(url, { ...init, signal: AbortSignal.timeout(30000) });
+      if (res.ok || res.status < 500) return res;
+      lastError = new Error(`HTTP ${res.status}`);
+    } catch (err) {
+      lastError = err instanceof Error ? err : new Error(String(err));
+    }
+    if (attempt < MAX_HTTP_RETRIES) await sleep(1000 * attempt);
+  }
+  throw lastError ?? new Error(`${label}: failed after ${MAX_HTTP_RETRIES} attempts`);
+}
+
+export async function runUpload(params: {
+  memoryKey: string;
+  endpoint: string;
+  targetPath?: string;
+  stateDir: string;
+  workspacePath?: string;
+}): Promise<void> {
+  const { memoryKey, endpoint, targetPath, stateDir } = params;
+  const uploadUrl = `${endpoint}/v1/memory/upload`;
+
+  // Validate API reachability
+  try {
+    const res = await fetch(`${endpoint}/health`, { signal: AbortSignal.timeout(5000) });
+    if (!res.ok) throw new Error(`HTTP ${res.status}`);
+  } catch {
+    console.error("Error: Could not reach MemoryRouter API.");
+    return;
+  }
+
+  const workspacePath = params.workspacePath ?? process.cwd();
+
+  let files: string[];
+  if (targetPath) {
+    const resolved = path.resolve(targetPath);
+    const stat = await fs.stat(resolved);
+    if (stat.isDirectory()) {
+      const allDirFiles = await fs.readdir(resolved, { recursive: true });
+      files = (allDirFiles as string[])
+        .filter((f) => f.endsWith(".md") || f.endsWith(".jsonl"))
+        .map((f) => path.join(resolved, f));
+    } else {
+      files = [resolved];
+    }
+  } else {
+    files = await discoverFiles(workspacePath, stateDir);
+  }
+
+  if (files.length === 0) {
+    console.log("No files found to upload.");
+    return;
+  }
+
+  console.log(`Uploading ${files.length} files to MemoryRouter...`);
+
+  const allLines: MemoryLine[] = [];
+  let skippedEmpty = 0;
+
+  for (const file of files) {
+    const displayName = path.basename(file);
+    try {
+      const lines = file.endsWith(".jsonl") ? await sessionToJsonl(file) : await fileToJsonl(file);
+      if (lines.length === 0) {
+        skippedEmpty++;
+        continue;
+      }
+      allLines.push(...lines);
+      console.log(`  ${displayName.padEnd(40, ".")} ✓ (${lines.length} chunks)`);
+    } catch (err) {
+      console.log(`  ${displayName.padEnd(40, ".")} ✗ ${err instanceof Error ? err.message : "Error"}`);
+    }
+  }
+
+  if (skippedEmpty > 0) console.log(`  Skipped ${skippedEmpty} empty files`);
+  if (allLines.length === 0) {
+    console.log("\nNo content to upload.");
+    return;
+  }
+
+  // Batch
+  const batches: MemoryLine[][] = [];
+  let currentBatch: MemoryLine[] = [];
+  let currentBytes = 0;
+
+  for (const line of allLines) {
+    const lineBytes = JSON.stringify(line).length + 1;
+    if (currentBytes + lineBytes > MAX_BATCH_BYTES || currentBatch.length >= MAX_BATCH_COUNT) {
+      if (currentBatch.length > 0) batches.push(currentBatch);
+      currentBatch = [line];
+      currentBytes = lineBytes;
+    } else {
+      currentBatch.push(line);
+      currentBytes += lineBytes;
+    }
+  }
+  if (currentBatch.length > 0) batches.push(currentBatch);
+
+  console.log(`\nSending ${allLines.length} memories in ${batches.length} batches...`);
+
+  let totalProcessed = 0;
+  let totalFailed = 0;
+
+  for (let i = 0; i < batches.length; i++) {
+    if (i > 0) await sleep(BATCH_SLEEP_MS);
+
+    const batch = batches[i];
+    const jsonlBody = batch.map((line) => JSON.stringify(line)).join("\n");
+
+    if (batches.length > 1) {
+      process.stdout.write(`  Batch ${i + 1}/${batches.length} (${batch.length} items)... `);
+    }
+
+    try {
+      const response = await fetchWithRetry(
+        uploadUrl,
+        {
+          method: "POST",
+          headers: {
+            Authorization: `Bearer ${memoryKey}`,
+            "Content-Type": "text/plain",
+          },
+          body: jsonlBody,
+        },
+        `Batch ${i + 1}`,
+      );
+
+      const result = (await response.json()) as {
+        stats?: { stored?: number; failed?: number; inputItems?: number };
+        errors?: string[];
+      };
+
+      const batchStored = result.stats?.stored ?? result.stats?.inputItems ?? batch.length;
+      const batchFailed = result.stats?.failed ?? 0;
+      totalProcessed += batchStored;
+      totalFailed += batchFailed;
+
+      if (batchFailed > 0) {
+        const errHint = result.errors?.[0] ? ` (${result.errors[0].slice(0, 80)})` : "";
+        console.log(`⚠ ${batchStored} stored, ${batchFailed} skipped${errHint}`);
+      } else {
+        console.log(`✓ ${batchStored} stored`);
+      }
+    } catch (err) {
+      console.log(`✗ Failed: ${err instanceof Error ? err.message : String(err)}`);
+      totalFailed += batch.length;
+    }
+  }
+
+  console.log(`\n✅ ${totalProcessed} vectors stored in vault`);
+  if (totalFailed > 0) {
+    console.log(`⚠️ ${totalFailed} failed (${((totalFailed / (totalProcessed + totalFailed)) * 100).toFixed(0)}%)`);
+  }
+}