@memtensor/memos-local-openclaw-plugin 0.1.0

package/src/embedding/index.ts

@@ -0,0 +1,76 @@
+import type { EmbeddingConfig, Logger } from "../types";
+import { embedOpenAI } from "./providers/openai";
+import { embedGemini } from "./providers/gemini";
+import { embedCohere, embedCohereQuery } from "./providers/cohere";
+import { embedVoyage } from "./providers/voyage";
+import { embedMistral } from "./providers/mistral";
+import { embedLocal } from "./local";
+
+export class Embedder {
+  constructor(
+    private cfg: EmbeddingConfig | undefined,
+    private log: Logger,
+  ) {}
+
+  get provider(): string {
+    return this.cfg?.provider ?? "local";
+  }
+
+  get dimensions(): number {
+    if (this.provider === "local") return 384;
+    return this.cfg?.dimensions ?? 1536;
+  }
+
+  async embed(texts: string[]): Promise<number[][]> {
+    const batchSize = this.cfg?.batchSize ?? 32;
+    const results: number[][] = [];
+
+    for (let i = 0; i < texts.length; i += batchSize) {
+      const batch = texts.slice(i, i + batchSize);
+      const vecs = await this.embedBatch(batch);
+      results.push(...vecs);
+    }
+
+    return results;
+  }
+
+  async embedQuery(text: string): Promise<number[]> {
+    if (this.provider === "cohere" && this.cfg) {
+      return embedCohereQuery(text, this.cfg, this.log);
+    }
+    const vecs = await this.embedBatch([text]);
+    return vecs[0];
+  }
+
+  private async embedBatch(texts: string[]): Promise<number[][]> {
+    const provider = this.provider;
+    const cfg = this.cfg;
+
+    try {
+      switch (provider) {
+        case "openai":
+        case "openai_compatible":
+          return await embedOpenAI(texts, cfg!, this.log);
+        case "gemini":
+          return await embedGemini(texts, cfg!, this.log);
+        case "azure_openai":
+          return await embedOpenAI(texts, cfg!, this.log);
+        case "cohere":
+          return await embedCohere(texts, cfg!, this.log);
+        case "mistral":
+          return await embedMistral(texts, cfg!, this.log);
+        case "voyage":
+          return await embedVoyage(texts, cfg!, this.log);
+        case "local":
+        default:
+          return await embedLocal(texts, this.log);
+      }
+    } catch (err) {
+      if (provider !== "local") {
+        this.log.warn(`Embedding provider '${provider}' failed, falling back to local: ${err}`);
+        return await embedLocal(texts, this.log);
+      }
+      throw err;
+    }
+  }
+}

package/src/embedding/local.ts

@@ -0,0 +1,35 @@
+import type { Logger } from "../types";
+import { DEFAULTS } from "../types";
+
+let extractorPromise: Promise<any> | null = null;
+
+function getExtractor(log: Logger): Promise<any> {
+  if (extractorPromise) return extractorPromise;
+
+  extractorPromise = (async () => {
+    log.info("Loading local embedding model (first call may download ~23MB)...");
+    const { pipeline } = await import("@xenova/transformers");
+    const ext = await pipeline("feature-extraction", DEFAULTS.localEmbeddingModel, {
+      quantized: true,
+    });
+    log.info("Local embedding model ready");
+    return ext;
+  })().catch((err) => {
+    extractorPromise = null;
+    throw err;
+  });
+
+  return extractorPromise;
+}
+
+export async function embedLocal(texts: string[], log: Logger): Promise<number[][]> {
+  const ext = await getExtractor(log);
+  const results: number[][] = [];
+
+  for (const text of texts) {
+    const output = await ext(text, { pooling: "mean", normalize: true });
+    results.push(Array.from(output.data as Float32Array).slice(0, DEFAULTS.localEmbeddingDimensions));
+  }
+
+  return results;
+}

package/src/embedding/providers/cohere.ts

@@ -0,0 +1,69 @@
+import type { EmbeddingConfig, Logger } from "../../types";
+
+export async function embedCohere(
+  texts: string[],
+  cfg: EmbeddingConfig,
+  log: Logger,
+): Promise<number[][]> {
+  const endpoint = cfg.endpoint ?? "https://api.cohere.ai/v1/embed";
+  const model = cfg.model ?? "embed-english-v3.0";
+  const headers: Record<string, string> = {
+    "Content-Type": "application/json",
+    Authorization: `Bearer ${cfg.apiKey}`,
+    ...cfg.headers,
+  };
+
+  const resp = await fetch(endpoint, {
+    method: "POST",
+    headers,
+    body: JSON.stringify({
+      texts,
+      model,
+      input_type: "search_document",
+      truncate: "END",
+    }),
+    signal: AbortSignal.timeout(cfg.timeoutMs ?? 30_000),
+  });
+
+  if (!resp.ok) {
+    const body = await resp.text();
+    throw new Error(`Cohere embedding failed (${resp.status}): ${body}`);
+  }
+
+  const json = (await resp.json()) as { embeddings: number[][] };
+  return json.embeddings;
+}
+
+export async function embedCohereQuery(
+  text: string,
+  cfg: EmbeddingConfig,
+  log: Logger,
+): Promise<number[]> {
+  const endpoint = cfg.endpoint ?? "https://api.cohere.ai/v1/embed";
+  const model = cfg.model ?? "embed-english-v3.0";
+  const headers: Record<string, string> = {
+    "Content-Type": "application/json",
+    Authorization: `Bearer ${cfg.apiKey}`,
+    ...cfg.headers,
+  };
+
+  const resp = await fetch(endpoint, {
+    method: "POST",
+    headers,
+    body: JSON.stringify({
+      texts: [text],
+      model,
+      input_type: "search_query",
+      truncate: "END",
+    }),
+    signal: AbortSignal.timeout(cfg.timeoutMs ?? 30_000),
+  });
+
+  if (!resp.ok) {
+    const body = await resp.text();
+    throw new Error(`Cohere query embedding failed (${resp.status}): ${body}`);
+  }
+
+  const json = (await resp.json()) as { embeddings: number[][] };
+  return json.embeddings[0];
+}

package/src/embedding/providers/gemini.ts

@@ -0,0 +1,41 @@
+import type { EmbeddingConfig, Logger } from "../../types";
+
+export async function embedGemini(
+  texts: string[],
+  cfg: EmbeddingConfig,
+  log: Logger,
+): Promise<number[][]> {
+  const model = cfg.model ?? "text-embedding-004";
+  const endpoint =
+    cfg.endpoint ??
+    `https://generativelanguage.googleapis.com/v1beta/models/${model}:batchEmbedContents`;
+
+  const headers: Record<string, string> = {
+    "Content-Type": "application/json",
+    ...cfg.headers,
+  };
+
+  const url = `${endpoint}?key=${cfg.apiKey}`;
+
+  const resp = await fetch(url, {
+    method: "POST",
+    headers,
+    body: JSON.stringify({
+      requests: texts.map((text) => ({
+        model: `models/${model}`,
+        content: { parts: [{ text }] },
+      })),
+    }),
+    signal: AbortSignal.timeout(cfg.timeoutMs ?? 30_000),
+  });
+
+  if (!resp.ok) {
+    const body = await resp.text();
+    throw new Error(`Gemini embedding failed (${resp.status}): ${body}`);
+  }
+
+  const json = (await resp.json()) as {
+    embeddings: Array<{ values: number[] }>;
+  };
+  return json.embeddings.map((e) => e.values);
+}

package/src/embedding/providers/mistral.ts

@@ -0,0 +1,32 @@
+import type { EmbeddingConfig, Logger } from "../../types";
+
+export async function embedMistral(
+  texts: string[],
+  cfg: EmbeddingConfig,
+  log: Logger,
+): Promise<number[][]> {
+  const endpoint = cfg.endpoint ?? "https://api.mistral.ai/v1/embeddings";
+  const model = cfg.model ?? "mistral-embed";
+  const headers: Record<string, string> = {
+    "Content-Type": "application/json",
+    Authorization: `Bearer ${cfg.apiKey}`,
+    ...cfg.headers,
+  };
+
+  const resp = await fetch(endpoint, {
+    method: "POST",
+    headers,
+    body: JSON.stringify({ input: texts, model, encoding_format: "float" }),
+    signal: AbortSignal.timeout(cfg.timeoutMs ?? 30_000),
+  });
+
+  if (!resp.ok) {
+    const body = await resp.text();
+    throw new Error(`Mistral embedding failed (${resp.status}): ${body}`);
+  }
+
+  const json = (await resp.json()) as {
+    data: Array<{ embedding: number[] }>;
+  };
+  return json.data.map((d) => d.embedding);
+}

package/src/embedding/providers/openai.ts

@@ -0,0 +1,42 @@
+import type { EmbeddingConfig, Logger } from "../../types";
+
+export async function embedOpenAI(
+  texts: string[],
+  cfg: EmbeddingConfig,
+  log: Logger,
+): Promise<number[][]> {
+  const endpoint = normalizeEmbeddingEndpoint(cfg.endpoint ?? "https://api.openai.com/v1/embeddings");
+  const model = cfg.model ?? "text-embedding-3-small";
+  const headers: Record<string, string> = {
+    "Content-Type": "application/json",
+    Authorization: `Bearer ${cfg.apiKey}`,
+    ...cfg.headers,
+  };
+
+  const resp = await fetch(endpoint, {
+    method: "POST",
+    headers,
+    body: JSON.stringify({ input: texts, model }),
+    signal: AbortSignal.timeout(cfg.timeoutMs ?? 30_000),
+  });
+
+  if (!resp.ok) {
+    const body = await resp.text();
+    throw new Error(`OpenAI embedding failed (${resp.status}): ${body}`);
+  }
+
+  const json = (await resp.json()) as {
+    data: Array<{ embedding: number[] }>;
+  };
+  return json.data.map((d) => d.embedding);
+}
+
+/**
+ * Normalize endpoint: if user provides a base_url (e.g. https://host/v1)
+ * without the /embeddings suffix, append it automatically.
+ */
+function normalizeEmbeddingEndpoint(url: string): string {
+  const stripped = url.replace(/\/+$/, "");
+  if (stripped.endsWith("/embeddings")) return stripped;
+  return `${stripped}/embeddings`;
+}

package/src/embedding/providers/voyage.ts

@@ -0,0 +1,32 @@
+import type { EmbeddingConfig, Logger } from "../../types";
+
+export async function embedVoyage(
+  texts: string[],
+  cfg: EmbeddingConfig,
+  log: Logger,
+): Promise<number[][]> {
+  const endpoint = cfg.endpoint ?? "https://api.voyageai.com/v1/embeddings";
+  const model = cfg.model ?? "voyage-2";
+  const headers: Record<string, string> = {
+    "Content-Type": "application/json",
+    Authorization: `Bearer ${cfg.apiKey}`,
+    ...cfg.headers,
+  };
+
+  const resp = await fetch(endpoint, {
+    method: "POST",
+    headers,
+    body: JSON.stringify({ input: texts, model }),
+    signal: AbortSignal.timeout(cfg.timeoutMs ?? 30_000),
+  });
+
+  if (!resp.ok) {
+    const body = await resp.text();
+    throw new Error(`Voyage embedding failed (${resp.status}): ${body}`);
+  }
+
+  const json = (await resp.json()) as {
+    data: Array<{ embedding: number[] }>;
+  };
+  return json.data.map((d) => d.embedding);
+}

package/src/index.ts

@@ -0,0 +1,106 @@
+import { v4 as uuid } from "uuid";
+import { buildContext } from "./config";
+import { SqliteStore } from "./storage/sqlite";
+import { Embedder } from "./embedding";
+import { IngestWorker } from "./ingest/worker";
+import { RecallEngine } from "./recall/engine";
+import { captureMessages } from "./capture";
+import { createMemorySearchTool, createMemoryTimelineTool, createMemoryGetTool } from "./tools";
+import type { MemosLocalConfig, ToolDefinition, Logger } from "./types";
+
+export interface MemosLocalPlugin {
+  id: string;
+  tools: ToolDefinition[];
+  onConversationTurn: (messages: Array<{ role: string; content: string }>, sessionKey?: string) => void;
+  /** Wait for all pending ingest operations to complete. */
+  flush: () => Promise<void>;
+  shutdown: () => void;
+}
+
+export interface PluginInitOptions {
+  stateDir?: string;
+  workspaceDir?: string;
+  config?: Partial<MemosLocalConfig>;
+  log?: Logger;
+}
+
+/**
+ * Initialize the memos-local plugin.
+ *
+ * Typical usage inside OpenClaw plugin lifecycle:
+ *
+ * ```ts
+ * import { initPlugin } from "@memos/local-openclaw";
+ *
+ * export default function activate(ctx) {
+ *   const plugin = initPlugin({
+ *     stateDir: ctx.stateDir,
+ *     workspaceDir: ctx.workspaceDir,
+ *     config: ctx.pluginConfig,
+ *     log: ctx.log,
+ *   });
+ *   ctx.registerTools(plugin.tools);
+ *   ctx.onConversationTurn((msgs, session) => {
+ *     plugin.onConversationTurn(msgs, session);
+ *   });
+ *   ctx.onDeactivate(() => plugin.shutdown());
+ * }
+ * ```
+ */
+export function initPlugin(opts: PluginInitOptions = {}): MemosLocalPlugin {
+  const stateDir = opts.stateDir ?? defaultStateDir();
+  const workspaceDir = opts.workspaceDir ?? process.cwd();
+  const ctx = buildContext(stateDir, workspaceDir, opts.config, opts.log);
+
+  ctx.log.info("Initializing memos-local plugin...");
+
+  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 tools: ToolDefinition[] = [
+    createMemorySearchTool(engine),
+    createMemoryTimelineTool(store),
+    createMemoryGetTool(store),
+  ];
+
+  ctx.log.info(`Plugin ready. DB: ${ctx.config.storage!.dbPath}, Embedding: ${embedder.provider}`);
+
+  return {
+    id: "memos-local",
+
+    tools,
+
+    onConversationTurn(
+      messages: Array<{ role: string; content: string }>,
+      sessionKey?: string,
+    ): void {
+      const session = sessionKey ?? "default";
+      const turnId = uuid();
+      const tag = ctx.config.capture?.evidenceWrapperTag ?? "STORED_MEMORY";
+
+      const captured = captureMessages(messages, session, turnId, tag, ctx.log);
+      if (captured.length > 0) {
+        worker.enqueue(captured);
+      }
+    },
+
+    async flush(): Promise<void> {
+      await worker.flush();
+    },
+
+    shutdown(): void {
+      ctx.log.info("Shutting down memos-local plugin...");
+      store.close();
+    },
+  };
+}
+
+function defaultStateDir(): string {
+  const home = process.env.HOME ?? process.env.USERPROFILE ?? "/tmp";
+  return `${home}/.openclaw`;
+}
+
+// Re-export types for consumers
+export type { MemosLocalConfig, ToolDefinition, SearchResult, SearchHit, TimelineResult, GetResult } from "./types";

package/src/ingest/chunker.ts

@@ -0,0 +1,217 @@
+import type { ChunkKind } from "../types";
+
+export interface RawChunk {
+  content: string;
+  kind: ChunkKind;
+}
+
+const MAX_CHUNK_CHARS = 3000;
+const MIN_CHUNK_CHARS = 40;
+const IDEAL_CHUNK_CHARS = 1500;
+
+const FENCED_CODE_RE = /^(`{3,})[^\n]*\n[\s\S]*?^\1\s*$/gm;
+
+const FUNC_OPEN_RE =
+  /^[ \t]*(?:(?:export\s+)?(?:async\s+)?(?:function|class|const\s+\w+\s*=\s*(?:\([^)]*\)|[^=])*=>)|(?:def |class )|(?:func |fn |pub\s+fn )|(?:public |private |protected |static )+.*\{)\s*$/;
+const BLOCK_CLOSE_RE = /^[ \t]*[}\]]\s*;?\s*$/;
+
+const ERROR_STACK_RE =
+  /(?:(?:Error|Exception|Traceback)[^\n]*\n(?:\s+at\s+[^\n]+\n?|.*File "[^\n]+\n?|.*line \d+[^\n]*\n?){2,})/gm;
+const LIST_BLOCK_RE = /(?:^[\s]*[-*•]\s+.+\n?){3,}/gm;
+const COMMAND_LINE_RE = /^(?:\$|>|#)\s+.+$/gm;
+
+/**
+ * Semantic-aware chunking:
+ * 1. Extract fenced code blocks as whole units (never split inside)
+ * 2. Detect unfenced code regions by brace-matching (functions/classes kept intact)
+ * 3. Extract error stacks, list blocks, command lines
+ * 4. Split remaining prose at paragraph boundaries (double newline)
+ * 5. Merge short adjacent chunks of the same kind
+ */
+export function chunkText(text: string): RawChunk[] {
+  let remaining = text;
+  const slots: Array<{ placeholder: string; chunk: RawChunk }> = [];
+  let counter = 0;
+
+  function ph(content: string, kind: ChunkKind): string {
+    const tag = `\x00SLOT_${counter++}\x00`;
+    slots.push({ placeholder: tag, chunk: { content: content.trim(), kind } });
+    return tag;
+  }
+
+  remaining = remaining.replace(FENCED_CODE_RE, (m) => ph(m, "code_block"));
+
+  remaining = extractBraceBlocks(remaining, ph);
+
+  const structural: Array<{ re: RegExp; kind: ChunkKind }> = [
+    { re: ERROR_STACK_RE, kind: "error_stack" },
+    { re: LIST_BLOCK_RE, kind: "list" },
+    { re: COMMAND_LINE_RE, kind: "command" },
+  ];
+  for (const { re, kind } of structural) {
+    remaining = remaining.replace(re, (m) => ph(m, kind));
+  }
+
+  const raw: RawChunk[] = [];
+  const sections = remaining.split(/\n{2,}/);
+
+  for (const sec of sections) {
+    const trimmed = sec.trim();
+    if (!trimmed) continue;
+
+    if (trimmed.includes("\x00SLOT_")) {
+      const parts = trimmed.split(/(\x00SLOT_\d+\x00)/);
+      for (const part of parts) {
+        const slot = slots.find((s) => s.placeholder === part);
+        if (slot) {
+          raw.push(slot.chunk);
+        } else if (part.trim().length >= MIN_CHUNK_CHARS) {
+          raw.push({ content: part.trim(), kind: "paragraph" });
+        }
+      }
+    } else if (trimmed.length >= MIN_CHUNK_CHARS) {
+      raw.push({ content: trimmed, kind: "paragraph" });
+    }
+  }
+
+  for (const s of slots) {
+    if (!raw.some((c) => c.content === s.chunk.content)) {
+      raw.push(s.chunk);
+    }
+  }
+
+  const merged = mergeSmallChunks(raw);
+  const final = splitOversized(merged);
+
+  return final.length > 0 ? final : [{ content: text.trim(), kind: "paragraph" }];
+}
+
+/**
+ * Detect function/class bodies that aren't inside fenced blocks.
+ * Tracks brace depth to keep complete blocks together.
+ */
+function extractBraceBlocks(
+  text: string,
+  ph: (content: string, kind: ChunkKind) => string,
+): string {
+  const lines = text.split("\n");
+  const result: string[] = [];
+  let blockLines: string[] = [];
+  let depth = 0;
+  let inBlock = false;
+
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+
+    if (line.includes("\x00SLOT_")) {
+      if (inBlock) {
+        blockLines.push(line);
+      } else {
+        result.push(line);
+      }
+      continue;
+    }
+
+    if (!inBlock && FUNC_OPEN_RE.test(line)) {
+      inBlock = true;
+      blockLines = [line];
+      depth = countBraces(line);
+      if (depth <= 0) depth = 1;
+      continue;
+    }
+
+    if (inBlock) {
+      blockLines.push(line);
+      depth += countBraces(line);
+      if (depth <= 0 || (BLOCK_CLOSE_RE.test(line) && depth <= 0)) {
+        const block = blockLines.join("\n");
+        if (block.trim().length >= MIN_CHUNK_CHARS) {
+          result.push(ph(block, "code_block"));
+        } else {
+          result.push(block);
+        }
+        inBlock = false;
+        blockLines = [];
+        depth = 0;
+      }
+    } else {
+      result.push(line);
+    }
+  }
+
+  if (blockLines.length > 0) {
+    const block = blockLines.join("\n");
+    if (block.trim().length >= MIN_CHUNK_CHARS) {
+      result.push(ph(block, "code_block"));
+    } else {
+      result.push(block);
+    }
+  }
+
+  return result.join("\n");
+}
+
+function countBraces(line: string): number {
+  let d = 0;
+  for (const ch of line) {
+    if (ch === "{" || ch === "(") d++;
+    else if (ch === "}" || ch === ")") d--;
+  }
+  return d;
+}
+
+function mergeSmallChunks(chunks: RawChunk[]): RawChunk[] {
+  if (chunks.length <= 1) return chunks;
+  const merged: RawChunk[] = [];
+  let buf: RawChunk | null = null;
+
+  for (const c of chunks) {
+    if (!buf) {
+      buf = { ...c };
+      continue;
+    }
+
+    const sameKind = buf.kind === c.kind;
+    const bothSmall = buf.content.length < IDEAL_CHUNK_CHARS && c.content.length < IDEAL_CHUNK_CHARS;
+    const mergedLen = buf.content.length + c.content.length + 2;
+
+    if (sameKind && bothSmall && mergedLen <= MAX_CHUNK_CHARS) {
+      buf.content = buf.content + "\n\n" + c.content;
+    } else {
+      merged.push(buf);
+      buf = { ...c };
+    }
+  }
+  if (buf) merged.push(buf);
+  return merged;
+}
+
+function splitOversized(chunks: RawChunk[]): RawChunk[] {
+  const result: RawChunk[] = [];
+  for (const c of chunks) {
+    if (c.content.length <= MAX_CHUNK_CHARS || c.kind === "code_block") {
+      result.push(c);
+      continue;
+    }
+    result.push(...splitAtSentenceBoundary(c.content, c.kind));
+  }
+  return result;
+}
+
+function splitAtSentenceBoundary(text: string, kind: ChunkKind): RawChunk[] {
+  const sentences = text.match(/[^.!?。！？\n]+(?:[.!?。！？]+|\n{2,})/g) ?? [text];
+  const result: RawChunk[] = [];
+  let buf = "";
+
+  for (const s of sentences) {
+    if (buf.length + s.length > MAX_CHUNK_CHARS && buf.length > 0) {
+      result.push({ content: buf.trim(), kind });
+      buf = "";
+    }
+    buf += s;
+  }
+  if (buf.trim().length >= MIN_CHUNK_CHARS) {
+    result.push({ content: buf.trim(), kind });
+  }
+  return result;
+}

package/src/ingest/dedup.ts

@@ -0,0 +1,37 @@
+import { cosineSimilarity } from "../storage/vector";
+import type { SqliteStore } from "../storage/sqlite";
+import type { Logger } from "../types";
+
+/**
+ * Check if a new summary embedding is a near-duplicate of any
+ * existing embedding. If similarity >= threshold, return the
+ * existing chunk ID to merge/update instead of creating a new entry.
+ *
+ * PRD §4.4: dedup threshold 0.92–0.95
+ */
+export function findDuplicate(
+  store: SqliteStore,
+  newVec: number[],
+  threshold: number,
+  log: Logger,
+): string | null {
+  const all = store.getAllEmbeddings();
+
+  let bestId: string | null = null;
+  let bestScore = 0;
+
+  for (const { chunkId, vector } of all) {
+    const sim = cosineSimilarity(newVec, vector);
+    if (sim > bestScore) {
+      bestScore = sim;
+      bestId = chunkId;
+    }
+  }
+
+  if (bestId && bestScore >= threshold) {
+    log.debug(`Dedup: found duplicate chunk=${bestId} sim=${bestScore.toFixed(4)}`);
+    return bestId;
+  }
+
+  return null;
+}