@memtensor/memos-local-openclaw-plugin 0.1.0

package/index.ts

@@ -0,0 +1,357 @@
+/**
+ * OpenClaw Plugin Entry Point — memos-local
+ *
+ * Full-write local memory with hybrid retrieval (RRF + MMR + recency).
+ * Provides: memory_search, memory_timeline, memory_get
+ */
+
+import type { OpenClawPluginApi } from "openclaw/plugin-sdk";
+import { Type } from "@sinclair/typebox";
+import { buildContext } from "./src/config";
+import { SqliteStore } from "./src/storage/sqlite";
+import { Embedder } from "./src/embedding";
+import { IngestWorker } from "./src/ingest/worker";
+import { RecallEngine } from "./src/recall/engine";
+import { captureMessages } from "./src/capture";
+import { DEFAULTS } from "./src/types";
+import { ViewerServer } from "./src/viewer/server";
+
+const pluginConfigSchema = {
+  type: "object" as const,
+  additionalProperties: true,
+  properties: {
+    embedding: {
+      type: "object" as const,
+      properties: {
+        provider: { type: "string" as const },
+        endpoint: { type: "string" as const },
+        apiKey: { type: "string" as const },
+        model: { type: "string" as const },
+      },
+    },
+    summarizer: {
+      type: "object" as const,
+      properties: {
+        provider: { type: "string" as const },
+        endpoint: { type: "string" as const },
+        apiKey: { type: "string" as const },
+        model: { type: "string" as const },
+        temperature: { type: "number" as const },
+      },
+    },
+    viewerPort: { type: "number" as const },
+  },
+};
+
+const memosLocalPlugin = {
+  id: "memos-local",
+  name: "MemOS Local Memory",
+  description:
+    "Full-write local conversation memory with hybrid search (RRF + MMR + recency). " +
+    "Provides memory_search, memory_timeline, memory_get for progressive recall.",
+  kind: "memory" as const,
+  configSchema: pluginConfigSchema,
+
+  register(api: OpenClawPluginApi) {
+    const pluginCfg = (api.pluginConfig ?? {}) as Record<string, unknown>;
+    const stateDir = api.resolvePath("~/.openclaw");
+    const ctx = buildContext(stateDir, process.cwd(), pluginCfg as any, {
+      debug: (msg: string) => api.logger.info(`[debug] ${msg}`),
+      info: (msg: string) => api.logger.info(msg),
+      warn: (msg: string) => api.logger.warn(msg),
+      error: (msg: string) => api.logger.warn(`[error] ${msg}`),
+    });
+
+    const store = new SqliteStore(ctx.config.storage!.dbPath!, ctx.log);
+    const embedder = new Embedder(ctx.config.embedding, ctx.log);
+    const worker = new IngestWorker(store, embedder, ctx);
+    const engine = new RecallEngine(store, embedder, ctx);
+    const evidenceTag = ctx.config.capture?.evidenceWrapperTag ?? DEFAULTS.evidenceWrapperTag;
+
+    api.logger.info(`memos-local: initialized (db: ${ctx.config.storage!.dbPath})`);
+
+    // ─── Tool: memory_search ───
+
+    api.registerTool(
+      {
+        name: "memory_search",
+        label: "Memory Search",
+        description:
+          "Search stored conversation memories. Returns summary, original_excerpt (evidence), score, and ref. " +
+          "Default: top 6, minScore 0.45. Increase maxResults to 12/20 or lower minScore to 0.35 if needed.",
+        parameters: Type.Object({
+          query: Type.String({ description: "Natural language search query" }),
+          maxResults: Type.Optional(Type.Number({ description: "Max results (default 6, max 20)" })),
+          minScore: Type.Optional(Type.Number({ description: "Min score 0-1 (default 0.45, floor 0.35)" })),
+        }),
+        async execute(_toolCallId, params) {
+          const { query, maxResults, minScore } = params as {
+            query: string;
+            maxResults?: number;
+            minScore?: number;
+          };
+
+          const result = await engine.search({ query, maxResults, minScore });
+
+          if (result.hits.length === 0) {
+            return {
+              content: [{ type: "text", text: result.meta.note ?? "No relevant memories found." }],
+              details: { meta: result.meta },
+            };
+          }
+
+          const roleLabel = (r: string) => r === "user" ? "[USER said]" : r === "assistant" ? "[ASSISTANT replied]" : r === "tool" ? "[TOOL returned]" : `[${r.toUpperCase()}]`;
+
+          const text = result.hits
+            .map(
+              (h, i) =>
+                `${i + 1}. ${roleLabel(h.source.role)} [score=${h.score}] ${h.summary}\n   Evidence: ${h.original_excerpt.slice(0, 200)}`,
+            )
+            .join("\n\n");
+
+          return {
+            content: [
+              {
+                type: "text",
+                text: `Found ${result.hits.length} memories (minScore=${result.meta.usedMinScore}):\n\n${text}`,
+              },
+            ],
+            details: {
+              hits: result.hits.map((h) => ({
+                role: h.source.role,
+                summary: h.summary,
+                original_excerpt: h.original_excerpt,
+                ref: h.ref,
+                score: h.score,
+                source: h.source,
+              })),
+              meta: result.meta,
+            },
+          };
+        },
+      },
+      { name: "memory_search" },
+    );
+
+    // ─── Tool: memory_timeline ───
+
+    api.registerTool(
+      {
+        name: "memory_timeline",
+        label: "Memory Timeline",
+        description:
+          "Get neighboring context around a memory ref. Use after memory_search to expand context.",
+        parameters: Type.Object({
+          sessionKey: Type.String({ description: "From search hit ref.sessionKey" }),
+          chunkId: Type.String({ description: "From search hit ref.chunkId" }),
+          turnId: Type.String({ description: "From search hit ref.turnId" }),
+          seq: Type.Number({ description: "From search hit ref.seq" }),
+          window: Type.Optional(Type.Number({ description: "Context window ±N (default 2)" })),
+        }),
+        async execute(_toolCallId, params) {
+          const { sessionKey, chunkId, turnId, seq, window: win } = params as {
+            sessionKey: string;
+            chunkId: string;
+            turnId: string;
+            seq: number;
+            window?: number;
+          };
+
+          const w = win ?? DEFAULTS.timelineWindowDefault;
+          const neighbors = store.getNeighborChunks(sessionKey, turnId, seq, w);
+          const anchorChunk = store.getChunk(chunkId);
+          const anchorTs = anchorChunk?.createdAt ?? 0;
+
+          const entries = neighbors.map((chunk) => {
+            let relation: "before" | "current" | "after" = "before";
+            if (chunk.id === chunkId) relation = "current";
+            else if (chunk.createdAt > anchorTs) relation = "after";
+
+            return {
+              relation,
+              role: chunk.role,
+              excerpt: chunk.content.slice(0, DEFAULTS.excerptMaxChars),
+              ts: chunk.createdAt,
+            };
+          });
+
+          const rl = (r: string) => r === "user" ? "USER" : r === "assistant" ? "ASSISTANT" : r.toUpperCase();
+          const text = entries
+            .map((e) => `[${e.relation}] ${rl(e.role)}: ${e.excerpt.slice(0, 150)}`)
+            .join("\n");
+
+          return {
+            content: [{ type: "text", text: `Timeline (${entries.length} entries):\n\n${text}` }],
+            details: { entries, anchorRef: { sessionKey, chunkId, turnId, seq } },
+          };
+        },
+      },
+      { name: "memory_timeline" },
+    );
+
+    // ─── Tool: memory_get ───
+
+    api.registerTool(
+      {
+        name: "memory_get",
+        label: "Memory Get",
+        description:
+          "Get full original text of a memory chunk. Use to verify exact details from a search hit.",
+        parameters: Type.Object({
+          chunkId: Type.String({ description: "From search hit ref.chunkId" }),
+          maxChars: Type.Optional(
+            Type.Number({ description: `Max chars (default ${DEFAULTS.getMaxCharsDefault}, max ${DEFAULTS.getMaxCharsMax})` }),
+          ),
+        }),
+        async execute(_toolCallId, params) {
+          const { chunkId, maxChars } = params as { chunkId: string; maxChars?: number };
+          const limit = Math.min(maxChars ?? DEFAULTS.getMaxCharsDefault, DEFAULTS.getMaxCharsMax);
+
+          const chunk = store.getChunk(chunkId);
+          if (!chunk) {
+            return {
+              content: [{ type: "text", text: `Chunk not found: ${chunkId}` }],
+              details: { error: "not_found" },
+            };
+          }
+
+          const content = chunk.content.length > limit
+            ? chunk.content.slice(0, limit) + "…"
+            : chunk.content;
+
+          const who = chunk.role === "user" ? "USER said" : chunk.role === "assistant" ? "ASSISTANT replied" : chunk.role === "tool" ? "TOOL returned" : chunk.role.toUpperCase();
+
+          return {
+            content: [{ type: "text", text: `[${who}] (session: ${chunk.sessionKey})\n\n${content}` }],
+            details: {
+              ref: { sessionKey: chunk.sessionKey, chunkId: chunk.id, turnId: chunk.turnId, seq: chunk.seq },
+              source: { ts: chunk.createdAt, role: chunk.role, sessionKey: chunk.sessionKey },
+            },
+          };
+        },
+      },
+      { name: "memory_get" },
+    );
+
+    // ─── Tool: memory_viewer ───
+
+    api.registerTool(
+      {
+        name: "memory_viewer",
+        label: "Open Memory Viewer",
+        description:
+          "Open the MemOS Memory Viewer web dashboard. Returns the URL the user can open in their browser to visually browse, search, and manage all stored memories.",
+        parameters: Type.Object({}),
+        async execute() {
+          const url = `http://127.0.0.1:${viewerPort}`;
+          return {
+            content: [
+              {
+                type: "text",
+                text: [
+                  `MemOS Memory Viewer: ${url}`,
+                  "",
+                  "Open this URL in your browser to:",
+                  "- Browse all stored memories with a clean timeline view",
+                  "- Semantic search (powered by your embedding model)",
+                  "- Create, edit, and delete memories",
+                  "- Filter by session, role, and time range",
+                  "",
+                  "First visit requires setting a password to protect your data.",
+                ].join("\n"),
+              },
+            ],
+            details: { viewerUrl: url },
+          };
+        },
+      },
+      { name: "memory_viewer" },
+    );
+
+    // ─── Auto-capture: write conversation to memory after each agent turn ───
+
+    api.on("agent_end", async (event) => {
+      if (!event.success || !event.messages || event.messages.length === 0) return;
+
+      try {
+        const msgs: Array<{ role: string; content: string; toolName?: string }> = [];
+        for (const msg of event.messages) {
+          if (!msg || typeof msg !== "object") continue;
+          const m = msg as Record<string, unknown>;
+          const role = m.role as string;
+          if (role !== "user" && role !== "assistant" && role !== "tool") continue;
+
+          let text = "";
+          if (typeof m.content === "string") {
+            text = m.content;
+          } else if (Array.isArray(m.content)) {
+            for (const block of m.content) {
+              if (block && typeof block === "object" && (block as any).type === "text") {
+                text += (block as any).text + "\n";
+              }
+            }
+          }
+
+          if (!text.trim()) continue;
+
+          const toolName = role === "tool"
+            ? (m.name as string) ?? (m.toolName as string) ?? (m.tool_call_id ? "unknown" : undefined)
+            : undefined;
+
+          msgs.push({ role, content: text.trim(), toolName });
+        }
+
+        if (msgs.length === 0) return;
+
+        const sessionKey = (event as any).sessionKey ?? "default";
+        const turnId = `${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
+        const captured = captureMessages(msgs, sessionKey, turnId, evidenceTag, ctx.log);
+        if (captured.length > 0) {
+          worker.enqueue(captured);
+        }
+      } catch (err) {
+        api.logger.warn(`memos-local: capture failed: ${String(err)}`);
+      }
+    });
+
+    // ─── Memory Viewer (web UI) ───
+
+    const viewerPort = (pluginCfg as any).viewerPort ?? 18799;
+    const viewer = new ViewerServer({
+      store,
+      embedder,
+      port: viewerPort,
+      log: ctx.log,
+      dataDir: stateDir,
+    });
+
+    // ─── Service lifecycle ───
+
+    api.registerService({
+      id: "memos-local",
+      start: async () => {
+        try {
+          const viewerUrl = await viewer.start();
+          api.logger.info(`memos-local: started (embedding: ${embedder.provider})`);
+          api.logger.info(`╔══════════════════════════════════════════╗`);
+          api.logger.info(`║  MemOS Memory Viewer                     ║`);
+          api.logger.info(`║  → ${viewerUrl.padEnd(37)}║`);
+          api.logger.info(`║  Open in browser to manage memories       ║`);
+          api.logger.info(`╚══════════════════════════════════════════╝`);
+          api.logger.info(`memos-local: password reset token: ${viewer.getResetToken()}`);
+          api.logger.info(`memos-local: forgot password? Use the reset token on the login page.`);
+        } catch (err) {
+          api.logger.warn(`memos-local: viewer failed to start: ${err}`);
+          api.logger.info(`memos-local: started (embedding: ${embedder.provider})`);
+        }
+      },
+      stop: () => {
+        viewer.stop();
+        store.close();
+        api.logger.info("memos-local: stopped");
+      },
+    });
+  },
+};
+
+export default memosLocalPlugin;

package/openclaw.plugin.json

@@ -0,0 +1,57 @@
+{
+  "id": "memos-local",
+  "kind": "memory",
+  "configSchema": {
+    "type": "object",
+    "additionalProperties": true,
+    "properties": {
+      "embedding": {
+        "type": "object",
+        "properties": {
+          "provider": { "type": "string" },
+          "endpoint": { "type": "string" },
+          "apiKey": { "type": "string" },
+          "model": { "type": "string" }
+        }
+      },
+      "summarizer": {
+        "type": "object",
+        "properties": {
+          "provider": { "type": "string" },
+          "endpoint": { "type": "string" },
+          "apiKey": { "type": "string" },
+          "model": { "type": "string" },
+          "temperature": { "type": "number" }
+        }
+      }
+    }
+  },
+  "uiHints": {
+    "embedding.endpoint": {
+      "label": "Embedding Endpoint",
+      "placeholder": "https://api.openai.com/v1",
+      "help": "OpenAI-compatible embedding API base URL"
+    },
+    "embedding.apiKey": {
+      "label": "Embedding API Key",
+      "sensitive": true,
+      "help": "API key for embedding service (or use ${ENV_VAR})"
+    },
+    "embedding.model": {
+      "label": "Embedding Model",
+      "placeholder": "bge-m3"
+    },
+    "summarizer.endpoint": {
+      "label": "Summarizer Endpoint",
+      "placeholder": "https://api.openai.com/v1"
+    },
+    "summarizer.apiKey": {
+      "label": "Summarizer API Key",
+      "sensitive": true
+    },
+    "summarizer.model": {
+      "label": "Summarizer Model",
+      "placeholder": "gpt-4o-mini"
+    }
+  }
+}

package/package.json

@@ -0,0 +1,57 @@
+{
+  "name": "@memtensor/memos-local-openclaw-plugin",
+  "version": "0.1.0",
+  "description": "MemOS Local memory plugin for OpenClaw — full-write, hybrid-recall, progressive retrieval",
+  "type": "module",
+  "main": "index.ts",
+  "types": "dist/index.d.ts",
+  "files": [
+    "index.ts",
+    "src",
+    "dist",
+    "openclaw.plugin.json",
+    "SKILL.md",
+    "README.md",
+    ".env.example",
+    "www"
+  ],
+  "openclaw": {
+    "extensions": [
+      "./index.ts"
+    ],
+    "installDependencies": true
+  },
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "lint": "eslint src --ext .ts",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "openclaw",
+    "plugin",
+    "memory",
+    "memos",
+    "rag"
+  ],
+  "license": "MIT",
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "dependencies": {
+    "@sinclair/typebox": "^0.34.48",
+    "@xenova/transformers": "^2.17.0",
+    "better-sqlite3": "^11.7.0",
+    "uuid": "^10.0.0"
+  },
+  "devDependencies": {
+    "@types/better-sqlite3": "^7.6.12",
+    "@types/node": "^22.10.0",
+    "@types/uuid": "^10.0.0",
+    "tsx": "^4.21.0",
+    "typescript": "^5.7.0",
+    "vitest": "^2.1.0"
+  }
+}

package/src/capture/index.ts

@@ -0,0 +1,92 @@
+import type { ConversationMessage, Role, Logger } from "../types";
+import { DEFAULTS } from "../types";
+
+const SKIP_ROLES: Set<Role> = new Set(["system"]);
+
+const SELF_TOOLS = new Set([
+  "memory_search",
+  "memory_timeline",
+  "memory_get",
+  "memory_viewer",
+]);
+
+/**
+ * Filter and extract writable messages from a conversation turn.
+ *
+ * - Keep user, assistant, and tool messages
+ * - Skip system prompts
+ * - Skip tool results from our own memory tools (prevents memory loop)
+ * - Truncate long tool results to avoid storage bloat
+ * - Strip injected evidence blocks wrapped in [STORED_MEMORY]...[/STORED_MEMORY]
+ */
+export function captureMessages(
+  messages: Array<{ role: string; content: string; toolName?: string }>,
+  sessionKey: string,
+  turnId: string,
+  evidenceTag: string,
+  log: Logger,
+): ConversationMessage[] {
+  const now = Date.now();
+  const result: ConversationMessage[] = [];
+
+  for (const msg of messages) {
+    const role = msg.role as Role;
+    if (SKIP_ROLES.has(role)) continue;
+    if (!msg.content || msg.content.trim().length === 0) continue;
+
+    if (role === "tool") {
+      if (msg.toolName && SELF_TOOLS.has(msg.toolName)) {
+        log.debug(`Skipping self-tool result: ${msg.toolName}`);
+        continue;
+      }
+
+      let content = msg.content.trim();
+      const maxChars = DEFAULTS.toolResultMaxChars;
+      if (content.length > maxChars) {
+        content = content.slice(0, maxChars) + `\n\n[truncated — original ${content.length} chars]`;
+      }
+
+      const toolLabel = msg.toolName ? `[tool:${msg.toolName}] ` : "[tool] ";
+      result.push({
+        role: "tool",
+        content: toolLabel + content,
+        timestamp: now,
+        turnId,
+        sessionKey,
+        toolName: msg.toolName,
+      });
+      continue;
+    }
+
+    const cleaned = stripEvidenceBlocks(msg.content, evidenceTag);
+    if (cleaned.trim().length === 0) continue;
+
+    result.push({
+      role,
+      content: cleaned,
+      timestamp: now,
+      turnId,
+      sessionKey,
+    });
+  }
+
+  log.debug(`Captured ${result.length}/${messages.length} messages for session=${sessionKey} turn=${turnId}`);
+  return result;
+}
+
+function stripEvidenceBlocks(text: string, tag: string): string {
+  const openTag = `[${tag}]`;
+  const closeTag = `[/${tag}]`;
+  let result = text;
+  let safety = 0;
+
+  while (result.includes(openTag) && result.includes(closeTag) && safety < 50) {
+    const start = result.indexOf(openTag);
+    const end = result.indexOf(closeTag, start);
+    if (end === -1) break;
+    result = result.slice(0, start) + result.slice(end + closeTag.length);
+    safety++;
+  }
+
+  return result;
+}

package/src/config.ts

@@ -0,0 +1,67 @@
+import * as path from "path";
+import { DEFAULTS, type MemosLocalConfig, type PluginContext, type Logger } from "./types";
+
+const ENV_RE = /\$\{([A-Z_][A-Z0-9_]*)\}/g;
+
+function resolveEnvVars(value: string): string {
+  return value.replace(ENV_RE, (_, name) => process.env[name] ?? "");
+}
+
+function deepResolveEnv<T>(obj: T): T {
+  if (typeof obj === "string") return resolveEnvVars(obj) as unknown as T;
+  if (Array.isArray(obj)) return obj.map(deepResolveEnv) as unknown as T;
+  if (obj && typeof obj === "object") {
+    const out: Record<string, unknown> = {};
+    for (const [k, v] of Object.entries(obj)) {
+      out[k] = deepResolveEnv(v);
+    }
+    return out as T;
+  }
+  return obj;
+}
+
+export function resolveConfig(raw: Partial<MemosLocalConfig> | undefined, stateDir: string): MemosLocalConfig {
+  const cfg = deepResolveEnv(raw ?? {});
+  return {
+    ...cfg,
+    storage: {
+      dbPath: cfg.storage?.dbPath ?? path.join(stateDir, "memos-local", "memos.db"),
+    },
+    recall: {
+      maxResultsDefault: cfg.recall?.maxResultsDefault ?? DEFAULTS.maxResultsDefault,
+      maxResultsMax: cfg.recall?.maxResultsMax ?? DEFAULTS.maxResultsMax,
+      minScoreDefault: cfg.recall?.minScoreDefault ?? DEFAULTS.minScoreDefault,
+      minScoreFloor: cfg.recall?.minScoreFloor ?? DEFAULTS.minScoreFloor,
+      rrfK: cfg.recall?.rrfK ?? DEFAULTS.rrfK,
+      mmrLambda: cfg.recall?.mmrLambda ?? DEFAULTS.mmrLambda,
+      recencyHalfLifeDays: cfg.recall?.recencyHalfLifeDays ?? DEFAULTS.recencyHalfLifeDays,
+    },
+    dedup: {
+      similarityThreshold: cfg.dedup?.similarityThreshold ?? DEFAULTS.dedupSimilarityThreshold,
+    },
+    capture: {
+      evidenceWrapperTag: cfg.capture?.evidenceWrapperTag ?? DEFAULTS.evidenceWrapperTag,
+    },
+  };
+}
+
+export function buildContext(
+  stateDir: string,
+  workspaceDir: string,
+  rawConfig: Partial<MemosLocalConfig> | undefined,
+  log?: Logger,
+): PluginContext {
+  const defaultLog: Logger = {
+    debug: (...args) => console.debug("[memos-local]", ...args),
+    info: (...args) => console.info("[memos-local]", ...args),
+    warn: (...args) => console.warn("[memos-local]", ...args),
+    error: (...args) => console.error("[memos-local]", ...args),
+  };
+
+  return {
+    stateDir,
+    workspaceDir,
+    config: resolveConfig(rawConfig, stateDir),
+    log: log ?? defaultLog,
+  };
+}