@memoryrelay/plugin-memoryrelay-ai 0.16.3 → 0.17.1

package/src/cache/sync-daemon.ts

@@ -0,0 +1,199 @@
+import type { LocalCache } from "./local-cache.js";
+import type { MemoryRelayClient } from "../client/memoryrelay-client.js";
+import type { Memory } from "../pipelines/types.js";
+import type { LocalCacheConfig } from "./types.js";
+
+// Backoff schedule: consecutiveErrors → interval ms
+const BACKOFF_SCHEDULE: Record<number, number> = {
+  0: 0, // use base interval
+  1: 60_000, // 1 minute
+  2: 300_000, // 5 minutes
+};
+const MAX_BACKOFF_MS = 1_800_000; // 30 minutes
+
+const PULL_PAGE_SIZE = 100;
+
+export class SyncDaemon {
+  private readonly cache: LocalCache;
+  private readonly client: MemoryRelayClient;
+  private readonly config: LocalCacheConfig;
+
+  private intervalId: ReturnType<typeof setInterval> | null = null;
+  private consecutiveErrors = 0;
+  private _lastError: string | null = null;
+
+  constructor(cache: LocalCache, client: MemoryRelayClient, config: LocalCacheConfig) {
+    this.cache = cache;
+    this.client = client;
+    this.config = config;
+  }
+
+  start(): void {
+    if (this.intervalId !== null) return;
+
+    const baseMs = this.config.syncIntervalMinutes * 60_000;
+    this.scheduleNext(baseMs);
+  }
+
+  stop(): void {
+    if (this.intervalId !== null) {
+      clearInterval(this.intervalId);
+      this.intervalId = null;
+    }
+  }
+
+  isRunning(): boolean {
+    return this.intervalId !== null;
+  }
+
+  lastError(): string | null {
+    return this._lastError;
+  }
+
+  getConsecutiveErrors(): number {
+    return this.consecutiveErrors;
+  }
+
+  async pull(): Promise<{ added: number; updated: number }> {
+    let added = 0;
+    let updated = 0;
+
+    try {
+      const syncState = this.cache.getSyncState();
+      let offset = syncState.cursor ? parseInt(syncState.cursor, 10) : 0;
+      let hasMore = true;
+
+      while (hasMore) {
+        const memories: Memory[] = await this.client.list(PULL_PAGE_SIZE, offset);
+
+        if (memories.length === 0) {
+          hasMore = false;
+          break;
+        }
+
+        for (const memory of memories) {
+          const existed = this.cache.get(memory.id) !== null;
+          this.cache.upsert({
+            id: memory.id,
+            remote_id: memory.id,
+            content: memory.content,
+            agent_id: memory.agent_id,
+            user_id: memory.user_id ?? "",
+            metadata: memory.metadata ?? {},
+            entities: memory.entities ?? [],
+            importance: memory.importance ?? 0.5,
+            tier: memory.tier ?? "warm",
+            scope: "long-term",
+            synced_at: new Date().toISOString(),
+            updated_at: memory.updated_at,
+            created_at: memory.created_at,
+          });
+          if (existed) {
+            updated++;
+          } else {
+            added++;
+          }
+        }
+
+        offset += memories.length;
+        hasMore = memories.length >= PULL_PAGE_SIZE;
+      }
+
+      // Update sync state
+      this.cache.setSyncState({
+        cursor: String(offset),
+        lastPull: new Date().toISOString(),
+      });
+
+      this.onSuccess();
+      return { added, updated };
+    } catch (err) {
+      this.onError(err);
+      throw err;
+    }
+  }
+
+  async push(): Promise<{ flushed: number; failed: number }> {
+    let flushed = 0;
+    let failed = 0;
+
+    try {
+      const entries = this.cache.bufferReadPending();
+      if (entries.length === 0) {
+        return { flushed: 0, failed: 0 };
+      }
+
+      const flushedIds: string[] = [];
+
+      for (const entry of entries) {
+        try {
+          await this.client.store(entry.content, entry.metadata as Record<string, string>, {
+            scope: entry.scope,
+          });
+          flushedIds.push(String(entry.id));
+          flushed++;
+        } catch {
+          failed++;
+        }
+      }
+
+      if (flushedIds.length > 0) {
+        this.cache.bufferMarkFlushed(flushedIds);
+        this.cache.setSyncState({ lastPush: new Date().toISOString() });
+      }
+
+      if (failed === 0) {
+        this.onSuccess();
+      } else if (flushed === 0) {
+        this.onError(new Error(`All ${failed} buffer entries failed to push`));
+      }
+
+      return { flushed, failed };
+    } catch (err) {
+      this.onError(err);
+      throw err;
+    }
+  }
+
+  // --- Internal ---
+
+  private scheduleNext(delayMs: number): void {
+    this.intervalId = setInterval(async () => {
+      try {
+        await this.pull();
+        await this.push();
+      } catch {
+        // errors already handled in pull/push via onError
+      }
+    }, delayMs);
+  }
+
+  private getBackoffMs(): number {
+    if (this.consecutiveErrors === 0) {
+      return this.config.syncIntervalMinutes * 60_000;
+    }
+    return BACKOFF_SCHEDULE[this.consecutiveErrors] ?? MAX_BACKOFF_MS;
+  }
+
+  private onSuccess(): void {
+    if (this.consecutiveErrors > 0) {
+      this.consecutiveErrors = 0;
+      this._lastError = null;
+      this.reschedule();
+    }
+  }
+
+  private onError(err: unknown): void {
+    this.consecutiveErrors++;
+    this._lastError = err instanceof Error ? err.message : String(err);
+    this.reschedule();
+  }
+
+  private reschedule(): void {
+    if (this.intervalId === null) return;
+    clearInterval(this.intervalId);
+    this.intervalId = null;
+    const nextMs = this.getBackoffMs();
+    this.scheduleNext(nextMs);
+  }
+}

package/src/cache/types.ts

@@ -0,0 +1,53 @@
+export interface LocalCacheConfig {
+  enabled: boolean;
+  dbPath: string;
+  syncIntervalMinutes: number;
+  maxLocalMemories: number;
+  vectorSearch: { enabled: boolean; provider: string };
+  ttl: { hot: number; warm: number; cold: number };
+}
+
+export interface BufferEntry {
+  id: number;
+  content: string;
+  metadata: Record<string, string>;
+  scope: "session" | "long-term";
+  session_id?: string;
+  namespace: string;
+  created_at: string;
+  flushed: boolean;
+}
+
+export interface SyncState {
+  lastPull: string | null;
+  lastPush: string | null;
+  cursor: string | null;
+}
+
+export interface CacheStats {
+  totalMemories: number;
+  tierBreakdown: { hot: number; warm: number; cold: number };
+  bufferDepth: number;
+  lastSync: string | null;
+  dbSizeBytes: number;
+}
+
+export interface LocalMemory {
+  id: string;
+  remote_id: string | null;
+  content: string;
+  agent_id: string;
+  user_id: string;
+  metadata: Record<string, unknown>;
+  entities: unknown[];
+  importance: number;
+  tier: "hot" | "warm" | "cold";
+  scope: "session" | "long-term";
+  session_id: string | null;
+  namespace: string;
+  created_at: string;
+  updated_at: string;
+  synced_at: string | null;
+  expires_at: string | null;
+  embedding: Buffer | null;
+}

package/src/cache/vector.ts

@@ -0,0 +1,162 @@
+import type Database from "better-sqlite3";
+import type { LocalMemory } from "./types.js";
+
+/**
+ * Attempt to load the sqlite-vec extension into the database.
+ * Returns true if loaded successfully, false otherwise.
+ */
+export async function loadVectorExtension(db: Database.Database): Promise<boolean> {
+  try {
+    const sqliteVec = await import("sqlite-vec");
+    sqliteVec.load(db);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Create the vec0 virtual table for vector search.
+ * Only call after loadVectorExtension returns true.
+ */
+export function createVecTable(db: Database.Database): void {
+  const fn = (db as unknown as { exec: (sql: string) => void }).exec.bind(db);
+  fn(
+    "CREATE VIRTUAL TABLE IF NOT EXISTS memories_vec USING vec0(memory_id TEXT PRIMARY KEY, embedding float[768])",
+  );
+}
+
+/**
+ * Store an embedding for a memory. Upserts into the vec0 table.
+ */
+export function storeEmbedding(
+  db: Database.Database,
+  memoryId: string,
+  embedding: Float32Array,
+): void {
+  db.prepare(
+    "INSERT OR REPLACE INTO memories_vec (memory_id, embedding) VALUES (?, ?)",
+  ).run(memoryId, Buffer.from(embedding.buffer, embedding.byteOffset, embedding.byteLength));
+}
+
+/**
+ * Search for similar vectors. Returns memory IDs ordered by similarity.
+ */
+export function searchVector(
+  db: Database.Database,
+  queryEmbedding: Float32Array,
+  limit: number,
+): string[] {
+  const rows = db
+    .prepare(
+      "SELECT memory_id FROM memories_vec WHERE embedding MATCH ? ORDER BY distance LIMIT ?",
+    )
+    .all(
+      Buffer.from(queryEmbedding.buffer, queryEmbedding.byteOffset, queryEmbedding.byteLength),
+      limit,
+    ) as { memory_id: string }[];
+  return rows.map((r) => r.memory_id);
+}
+
+/**
+ * Hybrid search combining FTS5 text search with vector similarity.
+ * Falls back to FTS5-only when queryEmbedding is null.
+ */
+export function searchHybrid(
+  db: Database.Database,
+  queryText: string,
+  queryEmbedding: Float32Array | null,
+  limit: number,
+  vectorAvailable: boolean = true,
+): LocalMemory[] {
+  const resultMap = new Map<string, { memory: LocalMemory; score: number }>();
+
+  // FTS5 search
+  if (queryText.trim()) {
+    const safeQuery = queryText
+      .replace(/['"]/g, " ")
+      .split(/\s+/)
+      .filter(Boolean)
+      .map((term) => `"${term}"`)
+      .join(" ");
+
+    if (safeQuery) {
+      const ftsRows = db
+        .prepare(
+          `SELECT m.*, fts.rank
+           FROM memories_fts fts
+           JOIN memories m ON m.rowid = fts.rowid
+           WHERE memories_fts MATCH ?
+           ORDER BY fts.rank
+           LIMIT ?`,
+        )
+        .all(safeQuery, limit * 2) as (MemoryRow & { rank: number })[];
+
+      for (let i = 0; i < ftsRows.length; i++) {
+        const row = ftsRows[i];
+        const ftsScore = 1.0 - i / ftsRows.length; // normalize to 0-1
+        resultMap.set(row.id, { memory: rowToMemory(row), score: ftsScore });
+      }
+    }
+  }
+
+  // Vector search (only if extension available and embedding provided)
+  if (vectorAvailable && queryEmbedding) {
+    try {
+      const vecIds = searchVector(db, queryEmbedding, limit * 2);
+      for (let i = 0; i < vecIds.length; i++) {
+        const vecScore = 1.0 - i / vecIds.length;
+        const existing = resultMap.get(vecIds[i]);
+        if (existing) {
+          // Boost items found by both methods
+          existing.score += vecScore;
+        } else {
+          const row = db
+            .prepare("SELECT * FROM memories WHERE id = ?")
+            .get(vecIds[i]) as MemoryRow | undefined;
+          if (row) {
+            resultMap.set(vecIds[i], { memory: rowToMemory(row), score: vecScore });
+          }
+        }
+      }
+    } catch {
+      // Vector search failed — continue with FTS results only
+    }
+  }
+
+  // Sort by combined score descending, return top N
+  return Array.from(resultMap.values())
+    .sort((a, b) => b.score - a.score)
+    .slice(0, limit)
+    .map((r) => r.memory);
+}
+
+// --- Internal helpers (duplicated from local-cache.ts to keep module self-contained) ---
+
+interface MemoryRow {
+  id: string;
+  remote_id: string | null;
+  content: string;
+  agent_id: string;
+  user_id: string;
+  metadata: string;
+  entities: string;
+  importance: number;
+  tier: "hot" | "warm" | "cold";
+  scope: "session" | "long-term";
+  session_id: string | null;
+  namespace: string;
+  created_at: string;
+  updated_at: string;
+  synced_at: string | null;
+  expires_at: string | null;
+  embedding: Buffer | null;
+}
+
+function rowToMemory(row: MemoryRow): LocalMemory {
+  return {
+    ...row,
+    metadata: JSON.parse(row.metadata),
+    entities: JSON.parse(row.entities),
+  };
+}

package/src/client/memoryrelay-client.ts

@@ -153,7 +153,7 @@ export class MemoryRelayClient implements IMemoryRelayClient {
           headers: {
             "Content-Type": "application/json",
             Authorization: `Bearer ${this.apiKey}`,
-            "User-Agent": "openclaw-memory-memoryrelay/0.16.3",
+            "User-Agent": "openclaw-memory-memoryrelay/0.17.1",
           },
           body: body ? JSON.stringify(body) : undefined,
         },

package/src/hooks/agent-end.ts

@@ -1,6 +1,6 @@
 // src/hooks/agent-end.ts
 import type { OpenClawPluginApi } from "openclaw/plugin-sdk";
-import type { PluginConfig, MemoryRelayClient, ConversationMessage, SessionResolverLike } from "../pipelines/types.js";
+import type { PluginConfig, MemoryRelayClient, ConversationMessage, SessionResolverLike, LocalCacheLike, SyncDaemonLike } from "../pipelines/types.js";
 import { buildRequestContext } from "../context/request-context.js";
 import { runPipeline } from "../pipelines/runner.js";
 import { capturePipeline } from "../pipelines/capture/index.js";
@@ -10,6 +10,8 @@ export function registerAgentEnd(
   config: PluginConfig,
   client: MemoryRelayClient,
   sessionResolver?: SessionResolverLike,
+  localCache?: LocalCacheLike,
+  syncDaemon?: SyncDaemonLike,
 ): void {
   if (!config.autoCapture?.enabled) return;
 
@@ -39,7 +41,7 @@ export function registerAgentEnd(
       if (messages.length === 0) return;
 
       const requestCtx = buildRequestContext(event, config);
-      const pipelineCtx = { requestCtx, config, client, sessionResolver };
+      const pipelineCtx = { requestCtx, config, client, sessionResolver, localCache, syncDaemon };
       await runPipeline(capturePipeline, { messages }, pipelineCtx);
     } catch (err) {
       api.logger.warn?.(`memory-memoryrelay: capture failed: ${String(err)}`);

package/src/hooks/before-prompt-build.ts

@@ -1,6 +1,6 @@
 // src/hooks/before-prompt-build.ts
 import type { OpenClawPluginApi } from "openclaw/plugin-sdk";
-import type { PluginConfig, MemoryRelayClient, SessionResolverLike } from "../pipelines/types.js";
+import type { PluginConfig, MemoryRelayClient, SessionResolverLike, LocalCacheLike, SyncDaemonLike } from "../pipelines/types.js";
 import { buildRequestContext } from "../context/request-context.js";
 import { runPipeline } from "../pipelines/runner.js";
 import { recallPipeline } from "../pipelines/recall/index.js";
@@ -10,6 +10,8 @@ export function registerBeforePromptBuild(
   config: PluginConfig,
   client: MemoryRelayClient,
   sessionResolver?: SessionResolverLike,
+  localCache?: LocalCacheLike,
+  syncDaemon?: SyncDaemonLike,
 ): void {
   api.on("before_prompt_build", async (event) => {
     if (!config.autoRecall) return;
@@ -29,7 +31,7 @@ export function registerBeforePromptBuild(
 
     try {
       const requestCtx = buildRequestContext(event, config);
-      const pipelineCtx = { requestCtx, config, client, sessionResolver };
+      const pipelineCtx = { requestCtx, config, client, sessionResolver, localCache, syncDaemon };
       const result = await runPipeline(recallPipeline, {
         prompt: requestCtx.prompt, memories: [], scope: "all" as const,
       }, pipelineCtx);

package/src/pipelines/capture/store.ts

@@ -20,14 +20,38 @@ export const captureStore: CaptureStage = {
       }
     }
 
+    let buffered = false;
+
     for (const msg of toStore) {
       const scope = resolveScope(msg.content);
-      const opts: Record<string, unknown> = { scope };
+      const metadata: Record<string, unknown> = { source: "auto-capture", scope };
       if (scope === "session" && sessionId) {
-        opts.session_id = sessionId;
+        metadata.session_id = sessionId;
+      }
+      metadata.namespace = ctx.requestCtx.namespace;
+
+      if (ctx.localCache) {
+        try {
+          ctx.localCache.bufferWrite(msg.content, metadata);
+          buffered = true;
+        } catch {
+          // Buffer write failed — fall back to direct API call
+          const opts: Record<string, unknown> = { scope };
+          if (scope === "session" && sessionId) {
+            opts.session_id = sessionId;
+          }
+          await ctx.client.store(msg.content, { source: "auto-capture", scope }, opts);
+        }
+      } else {
+        // No local cache — direct API call (existing behavior)
+        const opts: Record<string, unknown> = { scope };
+        if (scope === "session" && sessionId) {
+          opts.session_id = sessionId;
+        }
+        await ctx.client.store(msg.content, { source: "auto-capture", scope }, opts);
       }
-      await ctx.client.store(msg.content, { source: "auto-capture", scope }, opts);
     }
-    return { action: "continue", data: input };
+
+    return { action: "continue", data: input, buffered };
   },
 };

package/src/pipelines/recall/search.ts

@@ -1,4 +1,12 @@
-import type { RecallStage } from "../types.js";
+import type { RecallStage, ScoredMemory } from "../types.js";
+
+function isCacheStale(lastPull: string | null, syncIntervalMinutes: number): boolean {
+  if (!lastPull) return true;
+  const lastPullTime = new Date(lastPull).getTime();
+  if (isNaN(lastPullTime)) return true;
+  const staleAfterMs = syncIntervalMinutes * 60 * 1000;
+  return Date.now() - lastPullTime > staleAfterMs;
+}
 
 export const recallSearch: RecallStage = {
   name: "search",
@@ -20,13 +28,84 @@ export const recallSearch: RecallStage = {
         });
         sessionId = entry.sessionId;
       } catch {
-        // Fall back to raw session key if resolution fails
         sessionId = resolvedSessionKey;
       }
     } else {
       sessionId = resolvedSessionKey;
     }
 
+    // Local-first search: try local cache before API
+    if (ctx.localCache) {
+      try {
+        const localCount = ctx.localCache.count();
+        if (localCount > 0) {
+          const localLongTerm = ctx.localCache.search(input.prompt, {
+            limit,
+            scope: "long-term",
+            namespace,
+          });
+          const localSession = ctx.localCache.search(input.prompt, {
+            limit,
+            scope: "session",
+            sessionId,
+            namespace,
+          });
+
+          if (localLongTerm.length > 0 || localSession.length > 0) {
+            // Trigger background refresh if stale
+            if (ctx.syncDaemon) {
+              const syncIntervalMinutes = ctx.config.syncIntervalMinutes ?? 5;
+              const syncState = ctx.localCache.getSyncState();
+              if (isCacheStale(syncState.lastPull, syncIntervalMinutes)) {
+                ctx.syncDaemon.pull().catch(() => {});
+              }
+            }
+
+            return {
+              action: "continue",
+              data: {
+                ...input,
+                longTerm: localLongTerm.map((m) => ({
+                  memory: {
+                    id: m.id,
+                    content: m.content,
+                    agent_id: m.agent_id,
+                    user_id: m.user_id,
+                    metadata: m.metadata as Record<string, string>,
+                    entities: m.entities as string[],
+                    created_at: m.created_at,
+                    updated_at: m.updated_at,
+                    importance: m.importance,
+                    tier: m.tier,
+                  },
+                  finalScore: m.importance ?? 0.5,
+                })) as ScoredMemory[],
+                session: localSession.map((m) => ({
+                  memory: {
+                    id: m.id,
+                    content: m.content,
+                    agent_id: m.agent_id,
+                    user_id: m.user_id,
+                    metadata: m.metadata as Record<string, string>,
+                    entities: m.entities as string[],
+                    created_at: m.created_at,
+                    updated_at: m.updated_at,
+                    importance: m.importance,
+                    tier: m.tier,
+                  },
+                  finalScore: m.importance ?? 0.5,
+                })) as ScoredMemory[],
+                source: "local" as const,
+              },
+            };
+          }
+        }
+      } catch {
+        // Graceful degradation: fall through to API search
+      }
+    }
+
+    // Fallback: API search
     const [longTerm, session] = await Promise.all([
       client.search(input.prompt, limit, threshold, { scope: "long-term", namespace }),
       client.search(input.prompt, limit, threshold, { scope: "session", session_id: sessionId, namespace }),
@@ -37,6 +116,7 @@ export const recallSearch: RecallStage = {
         ...input,
         longTerm: longTerm.map(r => ({ memory: r.memory, finalScore: r.score })),
         session: session.map(r => ({ memory: r.memory, finalScore: r.score })),
+        source: "api" as const,
       },
     };
   },

package/src/pipelines/types.ts

@@ -66,6 +66,7 @@ export interface PluginConfig {
     importanceBoost?: boolean;
     tierBoost?: boolean;
   };
+  syncIntervalMinutes?: number;
   sessionTimeoutMinutes?: number;
   sessionCleanupIntervalMinutes?: number;
   debug?: boolean;
@@ -115,11 +116,34 @@ export interface SessionResolverLike {
   resolve(requestCtx: RequestContext): Promise<{ sessionId: string; externalId: string }>;
 }
 
+export interface LocalCacheLike {
+  bufferWrite(content: string, metadata: Record<string, unknown>): string;
+  bufferDepth(): number;
+  count(): number;
+  search(query: string, opts?: { limit?: number; scope?: string; sessionId?: string; namespace?: string }): Array<{
+    id: string; content: string; agent_id: string; user_id: string;
+    metadata: Record<string, unknown>; entities: unknown[];
+    importance: number; tier: "hot" | "warm" | "cold";
+    created_at: string; updated_at: string;
+  }>;
+  getSyncState(): { lastPull: string | null; lastPush: string | null; cursor: string | null };
+  close(): void;
+}
+
+export interface SyncDaemonLike {
+  start(): void;
+  stop(): void;
+  pull(): Promise<{ added: number; updated: number }>;
+  isRunning(): boolean;
+}
+
 export interface PipelineContext {
   readonly requestCtx: RequestContext;
   readonly config: PluginConfig;
   readonly client: MemoryRelayClient;
   readonly sessionResolver?: SessionResolverLike;
+  readonly localCache?: LocalCacheLike;
+  readonly syncDaemon?: SyncDaemonLike;
 }
 
 export interface RecallInput {
@@ -129,6 +153,7 @@ export interface RecallInput {
   resolvedSessionKey?: string;
   longTerm?: ScoredMemory[];
   session?: ScoredMemory[];
+  source?: "local" | "api";
   formatted?: string;
 }
 
@@ -147,7 +172,7 @@ export interface CaptureInput {
 }
 
 export type CaptureResult =
-  | { action: "continue"; data: CaptureInput }
+  | { action: "continue"; data: CaptureInput; buffered?: boolean }
   | { action: "skip" };
 
 export interface CaptureStage {

package/src/status-reporter.ts

@@ -280,7 +280,7 @@ export class StatusReporter {
   /**
    * Format time ago string
    */
-  private static formatTimeAgo(date: Date): string {
+  static formatTimeAgo(date: Date): string {
     const seconds = Math.floor((Date.now() - date.getTime()) / 1000);
 
     if (seconds < 60) return `${seconds} seconds ago`;