@memtensor/memos-local-openclaw-plugin 0.1.0

package/src/ingest/providers/anthropic.ts

@@ -0,0 +1,41 @@
+import type { SummarizerConfig, Logger } from "../../types";
+
+const SYSTEM_PROMPT = `Summarize the text in ONE concise sentence (max 60 tokens). Preserve exact names, commands, error codes. No bullet points, no preamble — output only the sentence.`;
+
+export async function summarizeAnthropic(
+  text: string,
+  cfg: SummarizerConfig,
+  log: Logger,
+): Promise<string> {
+  const endpoint = cfg.endpoint ?? "https://api.anthropic.com/v1/messages";
+  const model = cfg.model ?? "claude-3-haiku-20240307";
+  const headers: Record<string, string> = {
+    "Content-Type": "application/json",
+    "x-api-key": cfg.apiKey ?? "",
+    "anthropic-version": "2023-06-01",
+    ...cfg.headers,
+  };
+
+  const resp = await fetch(endpoint, {
+    method: "POST",
+    headers,
+    body: JSON.stringify({
+      model,
+      max_tokens: 100,
+      temperature: cfg.temperature ?? 0,
+      system: SYSTEM_PROMPT,
+      messages: [{ role: "user", content: text }],
+    }),
+    signal: AbortSignal.timeout(cfg.timeoutMs ?? 30_000),
+  });
+
+  if (!resp.ok) {
+    const body = await resp.text();
+    throw new Error(`Anthropic summarize failed (${resp.status}): ${body}`);
+  }
+
+  const json = (await resp.json()) as {
+    content: Array<{ type: string; text: string }>;
+  };
+  return json.content.find((c) => c.type === "text")?.text?.trim() ?? "";
+}

package/src/ingest/providers/bedrock.ts

@@ -0,0 +1,50 @@
+import type { SummarizerConfig, Logger } from "../../types";
+
+const SYSTEM_PROMPT = `Summarize the text in ONE concise sentence (max 60 tokens). Preserve exact names, commands, error codes. No bullet points, no preamble — output only the sentence.`;
+
+/**
+ * AWS Bedrock Converse API adapter.
+ * Expects cfg.endpoint to be the full Bedrock invoke URL and
+ * authentication handled via AWS SDK credential chain (env vars / IAM role).
+ */
+export async function summarizeBedrock(
+  text: string,
+  cfg: SummarizerConfig,
+  log: Logger,
+): Promise<string> {
+  const model = cfg.model ?? "anthropic.claude-3-haiku-20240307-v1:0";
+  const endpoint = cfg.endpoint;
+  if (!endpoint) {
+    throw new Error("Bedrock summarizer requires 'endpoint' to be set (e.g. https://bedrock-runtime.us-east-1.amazonaws.com)");
+  }
+
+  const url = `${endpoint}/model/${model}/converse`;
+  const headers: Record<string, string> = {
+    "Content-Type": "application/json",
+    ...cfg.headers,
+  };
+
+  const resp = await fetch(url, {
+    method: "POST",
+    headers,
+    body: JSON.stringify({
+      system: [{ text: SYSTEM_PROMPT }],
+      messages: [{ role: "user", content: [{ text }] }],
+      inferenceConfig: {
+        temperature: cfg.temperature ?? 0,
+        maxTokens: 100,
+      },
+    }),
+    signal: AbortSignal.timeout(cfg.timeoutMs ?? 30_000),
+  });
+
+  if (!resp.ok) {
+    const body = await resp.text();
+    throw new Error(`Bedrock summarize failed (${resp.status}): ${body}`);
+  }
+
+  const json = (await resp.json()) as {
+    output: { message: { content: Array<{ text: string }> } };
+  };
+  return json.output?.message?.content?.[0]?.text?.trim() ?? "";
+}

package/src/ingest/providers/gemini.ts

@@ -0,0 +1,41 @@
+import type { SummarizerConfig, Logger } from "../../types";
+
+const SYSTEM_PROMPT = `Summarize the text in ONE concise sentence (max 60 tokens). Preserve exact names, commands, error codes. No bullet points, no preamble — output only the sentence.`;
+
+export async function summarizeGemini(
+  text: string,
+  cfg: SummarizerConfig,
+  log: Logger,
+): Promise<string> {
+  const model = cfg.model ?? "gemini-1.5-flash";
+  const endpoint =
+    cfg.endpoint ??
+    `https://generativelanguage.googleapis.com/v1beta/models/${model}:generateContent`;
+
+  const url = `${endpoint}?key=${cfg.apiKey}`;
+  const headers: Record<string, string> = {
+    "Content-Type": "application/json",
+    ...cfg.headers,
+  };
+
+  const resp = await fetch(url, {
+    method: "POST",
+    headers,
+    body: JSON.stringify({
+      systemInstruction: { parts: [{ text: SYSTEM_PROMPT }] },
+      contents: [{ parts: [{ text }] }],
+      generationConfig: { temperature: cfg.temperature ?? 0, maxOutputTokens: 100 },
+    }),
+    signal: AbortSignal.timeout(cfg.timeoutMs ?? 30_000),
+  });
+
+  if (!resp.ok) {
+    const body = await resp.text();
+    throw new Error(`Gemini summarize failed (${resp.status}): ${body}`);
+  }
+
+  const json = (await resp.json()) as {
+    candidates: Array<{ content: { parts: Array<{ text: string }> } }>;
+  };
+  return json.candidates?.[0]?.content?.parts?.[0]?.text?.trim() ?? "";
+}

package/src/ingest/providers/index.ts

@@ -0,0 +1,67 @@
+import type { SummarizerConfig, Logger } from "../../types";
+import { summarizeOpenAI } from "./openai";
+import { summarizeAnthropic } from "./anthropic";
+import { summarizeGemini } from "./gemini";
+import { summarizeBedrock } from "./bedrock";
+
+export class Summarizer {
+  constructor(
+    private cfg: SummarizerConfig | undefined,
+    private log: Logger,
+  ) {}
+
+  async summarize(text: string): Promise<string> {
+    if (!this.cfg) {
+      return ruleFallback(text);
+    }
+
+    try {
+      return await this.callProvider(text);
+    } catch (err) {
+      this.log.warn(`Summarizer provider failed, using rule fallback: ${err}`);
+      return ruleFallback(text);
+    }
+  }
+
+  private async callProvider(text: string): Promise<string> {
+    const cfg = this.cfg!;
+    switch (cfg.provider) {
+      case "openai":
+      case "openai_compatible":
+        return summarizeOpenAI(text, cfg, this.log);
+      case "anthropic":
+        return summarizeAnthropic(text, cfg, this.log);
+      case "gemini":
+        return summarizeGemini(text, cfg, this.log);
+      case "azure_openai":
+        return summarizeOpenAI(text, cfg, this.log);
+      case "bedrock":
+        return summarizeBedrock(text, cfg, this.log);
+      default:
+        throw new Error(`Unknown summarizer provider: ${cfg.provider}`);
+    }
+  }
+}
+
+/**
+ * Rule-based fallback: produce a single short sentence from the first
+ * meaningful line, appending any key entities found in the text.
+ */
+function ruleFallback(text: string): string {
+  const lines = text.split("\n").filter((l) => l.trim().length > 10);
+  const first = (lines[0] ?? text).trim();
+
+  const entityRe = [/`[^`]+`/g, /\b(?:error|Error|ERROR)\s*[:：]\s*.{5,60}/g];
+  const entities: string[] = [];
+  for (const re of entityRe) {
+    for (const m of text.matchAll(re)) {
+      if (entities.length < 3) entities.push(m[0].slice(0, 50));
+    }
+  }
+
+  let summary = first.length > 120 ? first.slice(0, 117) + "..." : first;
+  if (entities.length > 0) {
+    summary += ` (${entities.join(", ")})`;
+  }
+  return summary.slice(0, 200);
+}

package/src/ingest/providers/openai.ts

@@ -0,0 +1,48 @@
+import type { SummarizerConfig, Logger } from "../../types";
+
+const SYSTEM_PROMPT = `Summarize the text in ONE concise sentence (max 60 tokens). Preserve exact names, commands, error codes. No bullet points, no preamble — output only the sentence.`;
+
+export async function summarizeOpenAI(
+  text: string,
+  cfg: SummarizerConfig,
+  log: Logger,
+): Promise<string> {
+  const endpoint = normalizeChatEndpoint(cfg.endpoint ?? "https://api.openai.com/v1/chat/completions");
+  const model = cfg.model ?? "gpt-4o-mini";
+  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({
+      model,
+      temperature: cfg.temperature ?? 0,
+      messages: [
+        { role: "system", content: SYSTEM_PROMPT },
+        { role: "user", content: text },
+      ],
+    }),
+    signal: AbortSignal.timeout(cfg.timeoutMs ?? 30_000),
+  });
+
+  if (!resp.ok) {
+    const body = await resp.text();
+    throw new Error(`OpenAI summarize failed (${resp.status}): ${body}`);
+  }
+
+  const json = (await resp.json()) as {
+    choices: Array<{ message: { content: string } }>;
+  };
+  return json.choices[0]?.message?.content?.trim() ?? "";
+}
+
+function normalizeChatEndpoint(url: string): string {
+  const stripped = url.replace(/\/+$/, "");
+  if (stripped.endsWith("/chat/completions")) return stripped;
+  if (stripped.endsWith("/completions")) return stripped;
+  return `${stripped}/chat/completions`;
+}

package/src/ingest/worker.ts

@@ -0,0 +1,130 @@
+import { v4 as uuid } from "uuid";
+import type { ConversationMessage, Chunk, PluginContext } from "../types";
+import type { SqliteStore } from "../storage/sqlite";
+import type { Embedder } from "../embedding";
+import { Summarizer } from "./providers";
+import { chunkText } from "./chunker";
+import { findDuplicate } from "./dedup";
+
+export class IngestWorker {
+  private summarizer: Summarizer;
+  private queue: ConversationMessage[] = [];
+  private processing = false;
+  private flushResolvers: Array<() => void> = [];
+
+  constructor(
+    private store: SqliteStore,
+    private embedder: Embedder,
+    private ctx: PluginContext,
+  ) {
+    this.summarizer = new Summarizer(ctx.config.summarizer, ctx.log);
+  }
+
+  enqueue(messages: ConversationMessage[]): void {
+    this.queue.push(...messages);
+    if (!this.processing) {
+      this.processQueue().catch((err) => {
+        this.ctx.log.error(`Ingest worker error: ${err}`);
+        this.processing = false;
+      });
+    }
+  }
+
+  /** Wait until all queued messages have been processed. */
+  async flush(): Promise<void> {
+    if (this.queue.length === 0 && !this.processing) return;
+    return new Promise((resolve) => {
+      this.flushResolvers.push(resolve);
+    });
+  }
+
+  private async processQueue(): Promise<void> {
+    this.processing = true;
+
+    while (this.queue.length > 0) {
+      const msg = this.queue.shift()!;
+      try {
+        await this.ingestMessage(msg);
+      } catch (err) {
+        this.ctx.log.error(`Failed to ingest message turn=${msg.turnId}: ${err}`);
+      }
+    }
+
+    this.processing = false;
+    for (const resolve of this.flushResolvers) resolve();
+    this.flushResolvers = [];
+  }
+
+  private async ingestMessage(msg: ConversationMessage): Promise<void> {
+    if (msg.role === "tool") {
+      await this.ingestToolResult(msg);
+      return;
+    }
+
+    const rawChunks = chunkText(msg.content);
+    this.ctx.log.debug(`Chunked turn=${msg.turnId} into ${rawChunks.length} chunks`);
+
+    for (let seq = 0; seq < rawChunks.length; seq++) {
+      const raw = rawChunks[seq];
+      await this.storeChunk(msg, raw.content, raw.kind, seq);
+    }
+  }
+
+  private async ingestToolResult(msg: ConversationMessage): Promise<void> {
+    this.ctx.log.debug(`Ingesting tool result turn=${msg.turnId} tool=${msg.toolName ?? "unknown"} len=${msg.content.length}`);
+    await this.storeChunk(msg, msg.content, "tool_result", 0);
+  }
+
+  private async storeChunk(
+    msg: ConversationMessage,
+    content: string,
+    kind: Chunk["kind"],
+    seq: number,
+  ): Promise<void> {
+    const chunkId = uuid();
+    const summary = await this.summarizer.summarize(content);
+
+    let embedding: number[] | null = null;
+    try {
+      [embedding] = await this.embedder.embed([summary]);
+    } catch (err) {
+      this.ctx.log.warn(`Embedding failed for chunk=${chunkId}, storing without vector: ${err}`);
+    }
+
+    if (embedding) {
+      const dupId = findDuplicate(
+        this.store,
+        embedding,
+        this.ctx.config.dedup?.similarityThreshold ?? 0.93,
+        this.ctx.log,
+      );
+
+      if (dupId) {
+        this.store.updateSummary(dupId, summary);
+        this.store.upsertEmbedding(dupId, embedding);
+        this.ctx.log.debug(`Dedup-merged into existing chunk=${dupId}`);
+        return;
+      }
+    }
+
+    const chunk: Chunk = {
+      id: chunkId,
+      sessionKey: msg.sessionKey,
+      turnId: msg.turnId,
+      seq,
+      role: msg.role,
+      content,
+      kind,
+      summary,
+      embedding: null,
+      createdAt: msg.timestamp,
+      updatedAt: msg.timestamp,
+    };
+
+    this.store.insertChunk(chunk);
+    if (embedding) {
+      this.store.upsertEmbedding(chunkId, embedding);
+    }
+    this.ctx.log.debug(`Stored chunk=${chunkId} kind=${kind} role=${msg.role} len=${content.length} hasVec=${!!embedding}`);
+  }
+}

package/src/recall/engine.ts

@@ -0,0 +1,182 @@
+import type { SqliteStore } from "../storage/sqlite";
+import type { Embedder } from "../embedding";
+import type { PluginContext, SearchHit, SearchResult } from "../types";
+import { vectorSearch } from "../storage/vector";
+import { rrfFuse } from "./rrf";
+import { mmrRerank } from "./mmr";
+import { applyRecencyDecay } from "./recency";
+
+export interface RecallOptions {
+  query?: string;
+  maxResults?: number;
+  minScore?: number;
+}
+
+const MAX_RECENT_QUERIES = 20;
+
+export class RecallEngine {
+  private recentQueries: Array<{ query: string; maxResults: number; minScore: number; hitCount: number }> = [];
+
+  constructor(
+    private store: SqliteStore,
+    private embedder: Embedder,
+    private ctx: PluginContext,
+  ) {}
+
+  async search(opts: RecallOptions): Promise<SearchResult> {
+    const recallCfg = this.ctx.config.recall!;
+    const maxResults = Math.min(
+      opts.maxResults ?? recallCfg.maxResultsDefault!,
+      recallCfg.maxResultsMax!,
+    );
+    const minScore = opts.minScore ?? recallCfg.minScoreDefault!;
+    const query = opts.query ?? "";
+
+    const repeatNote = this.checkRepeat(query, maxResults, minScore);
+    const candidatePool = maxResults * 5;
+
+    // Step 1: Gather candidates from both FTS and vector search
+    const ftsCandidates = query
+      ? this.store.ftsSearch(query, candidatePool)
+      : [];
+
+    let vecCandidates: Array<{ chunkId: string; score: number }> = [];
+    if (query) {
+      try {
+        const queryVec = await this.embedder.embedQuery(query);
+        vecCandidates = vectorSearch(this.store, queryVec, candidatePool);
+      } catch (err) {
+        this.ctx.log.warn(`Vector search failed, using FTS only: ${err}`);
+      }
+    }
+
+    // Step 2: RRF fusion
+    const ftsRanked = ftsCandidates.map((c) => ({ id: c.chunkId, score: c.score }));
+    const vecRanked = vecCandidates.map((c) => ({ id: c.chunkId, score: c.score }));
+    const rrfScores = rrfFuse([ftsRanked, vecRanked], recallCfg.rrfK);
+
+    if (rrfScores.size === 0) {
+      this.recordQuery(query, maxResults, minScore, 0);
+      return {
+        hits: [],
+        meta: {
+          usedMinScore: minScore,
+          usedMaxResults: maxResults,
+          totalCandidates: 0,
+          note: repeatNote ?? "No candidates found for the given query.",
+        },
+      };
+    }
+
+    // Step 3: MMR re-ranking
+    const rrfList = [...rrfScores.entries()]
+      .map(([id, score]) => ({ id, score }))
+      .sort((a, b) => b.score - a.score);
+
+    const mmrResults = mmrRerank(rrfList, this.store, recallCfg.mmrLambda, maxResults * 2);
+
+    // Step 4: Time decay
+    const withTs = mmrResults.map((r) => {
+      const chunk = this.store.getChunk(r.id);
+      return { ...r, createdAt: chunk?.createdAt ?? 0 };
+    });
+    const decayed = applyRecencyDecay(withTs, recallCfg.recencyHalfLifeDays);
+
+    // Step 5: Normalize scores to [0,1]
+    const maxScore = Math.max(...decayed.map((d) => d.score), 1e-10);
+    const normalized = decayed.map((d) => ({
+      ...d,
+      score: d.score / maxScore,
+    }));
+
+    // Step 6: Filter by minScore and limit
+    const filtered = normalized
+      .filter((d) => d.score >= minScore)
+      .sort((a, b) => b.score - a.score)
+      .slice(0, maxResults);
+
+    // Step 7: Build hits
+    const hits: SearchHit[] = [];
+    for (const candidate of filtered) {
+      const chunk = this.store.getChunk(candidate.id);
+      if (!chunk) continue;
+
+      hits.push({
+        summary: chunk.summary,
+        original_excerpt: makeExcerpt(chunk.content),
+        ref: {
+          sessionKey: chunk.sessionKey,
+          chunkId: chunk.id,
+          turnId: chunk.turnId,
+          seq: chunk.seq,
+        },
+        score: Math.round(candidate.score * 1000) / 1000,
+        source: {
+          ts: chunk.createdAt,
+          role: chunk.role,
+          sessionKey: chunk.sessionKey,
+        },
+      });
+    }
+
+    this.recordQuery(query, maxResults, minScore, hits.length);
+
+    return {
+      hits,
+      meta: {
+        usedMinScore: minScore,
+        usedMaxResults: maxResults,
+        totalCandidates: rrfScores.size,
+        ...(repeatNote ? { note: repeatNote } : {}),
+      },
+    };
+  }
+
+  /**
+   * PRD §6.1: Detect repeated identical/similar queries and produce a
+   * warning note so the model knows to vary its approach.
+   */
+  private checkRepeat(query: string, maxResults: number, minScore: number): string | undefined {
+    const normalized = query.toLowerCase().trim();
+    if (!normalized) return undefined;
+
+    const dup = this.recentQueries.find(
+      (q) => q.query === normalized && q.maxResults === maxResults && q.minScore === minScore,
+    );
+
+    if (dup) {
+      if (dup.hitCount === 0) {
+        return "This exact query with the same parameters was already tried and returned 0 results. Try rephrasing with different keywords, or adjust maxResults/minScore.";
+      }
+      return "This exact query with the same parameters was already executed. Consider varying the query or expanding parameters to get different results.";
+    }
+
+    return undefined;
+  }
+
+  private recordQuery(query: string, maxResults: number, minScore: number, hitCount: number): void {
+    const normalized = query.toLowerCase().trim();
+    if (!normalized) return;
+
+    this.recentQueries = this.recentQueries.filter(
+      (q) => !(q.query === normalized && q.maxResults === maxResults && q.minScore === minScore),
+    );
+    this.recentQueries.push({ query: normalized, maxResults, minScore, hitCount });
+
+    if (this.recentQueries.length > MAX_RECENT_QUERIES) {
+      this.recentQueries.shift();
+    }
+  }
+}
+
+function makeExcerpt(content: string): string {
+  const min = 200;
+  const max = 500;
+  if (content.length <= max) return content;
+
+  let cut = content.lastIndexOf(".", max);
+  if (cut < min) cut = content.lastIndexOf(" ", max);
+  if (cut < min) cut = max;
+
+  return content.slice(0, cut) + "…";
+}

package/src/recall/mmr.ts

@@ -0,0 +1,60 @@
+import { cosineSimilarity } from "../storage/vector";
+import type { SqliteStore } from "../storage/sqlite";
+
+/**
+ * Maximal Marginal Relevance (PRD §5.3)
+ *
+ * Re-ranks candidates to balance relevance with diversity,
+ * preventing top-K results from being too similar.
+ *
+ * MMR = λ · sim(q, d) - (1-λ) · max(sim(d, d_selected))
+ */
+export function mmrRerank(
+  candidates: Array<{ id: string; score: number }>,
+  store: SqliteStore,
+  lambda: number = 0.7,
+  topK: number = 20,
+): Array<{ id: string; score: number }> {
+  if (candidates.length <= 1) return candidates;
+
+  const embeddings = new Map<string, number[]>();
+  for (const c of candidates) {
+    const vec = store.getEmbedding(c.id);
+    if (vec) embeddings.set(c.id, vec);
+  }
+
+  const selected: Array<{ id: string; score: number }> = [];
+  const remaining = [...candidates];
+
+  while (selected.length < topK && remaining.length > 0) {
+    let bestIdx = 0;
+    let bestMmr = -Infinity;
+
+    for (let i = 0; i < remaining.length; i++) {
+      const cand = remaining[i];
+      const candVec = embeddings.get(cand.id);
+
+      let maxSimToSelected = 0;
+      if (candVec && selected.length > 0) {
+        for (const s of selected) {
+          const sVec = embeddings.get(s.id);
+          if (sVec) {
+            const sim = cosineSimilarity(candVec, sVec);
+            maxSimToSelected = Math.max(maxSimToSelected, sim);
+          }
+        }
+      }
+
+      const mmrScore = lambda * cand.score - (1 - lambda) * maxSimToSelected;
+      if (mmrScore > bestMmr) {
+        bestMmr = mmrScore;
+        bestIdx = i;
+      }
+    }
+
+    const chosen = remaining.splice(bestIdx, 1)[0];
+    selected.push({ id: chosen.id, score: bestMmr });
+  }
+
+  return selected;
+}

package/src/recall/recency.ts

@@ -0,0 +1,27 @@
+/**
+ * Time decay scoring (PRD §5.3)
+ *
+ * Applies exponential decay based on document age, biasing towards
+ * more recent memories. Uses configurable half-life (default 14 days).
+ *
+ * decay(t) = 0.5 ^ (age_days / half_life)
+ * final = base_score * (alpha + (1-alpha) * decay)
+ *
+ * alpha=0.3 ensures old but highly relevant results are not zeroed out.
+ */
+export function applyRecencyDecay(
+  candidates: Array<{ id: string; score: number; createdAt: number }>,
+  halfLifeDays: number = 14,
+  now?: number,
+): Array<{ id: string; score: number }> {
+  const currentTime = now ?? Date.now();
+  const halfLifeMs = halfLifeDays * 24 * 60 * 60 * 1000;
+  const alpha = 0.3;
+
+  return candidates.map((c) => {
+    const ageMs = Math.max(0, currentTime - c.createdAt);
+    const decay = Math.pow(0.5, ageMs / halfLifeMs);
+    const adjustedScore = c.score * (alpha + (1 - alpha) * decay);
+    return { id: c.id, score: adjustedScore };
+  });
+}

package/src/recall/rrf.ts

@@ -0,0 +1,31 @@
+/**
+ * Reciprocal Rank Fusion (PRD §5.2)
+ *
+ * Merges ranked lists from different retrieval sources (FTS, vector)
+ * into a single ranking. Handles score scale mismatch between BM25
+ * and cosine similarity.
+ *
+ * RRF(d) = Σ 1 / (k + rank_i(d))
+ * where k is a constant (default 60) and rank_i is the rank in list i.
+ */
+export interface RankedItem {
+  id: string;
+  score: number;
+}
+
+export function rrfFuse(
+  lists: RankedItem[][],
+  k: number = 60,
+): Map<string, number> {
+  const scores = new Map<string, number>();
+
+  for (const list of lists) {
+    for (let rank = 0; rank < list.length; rank++) {
+      const item = list[rank];
+      const prev = scores.get(item.id) ?? 0;
+      scores.set(item.id, prev + 1 / (k + rank + 1));
+    }
+  }
+
+  return scores;
+}