@alfe.ai/openclaw-memory-cloud 0.0.38 → 0.0.39

package/src/__tests__/session-backfill.test.ts

@@ -1,289 +0,0 @@
-import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
-import { mkdtemp, writeFile, rm, mkdir, chmod } from "node:fs/promises";
-import { tmpdir } from "node:os";
-import { join } from "node:path";
-import { runSessionsBackfill } from "../session-backfill.js";
-import type { MemoryCloudConfig, MemoryMessage, SessionMetadata } from "../types.js";
-
-const CONFIG: MemoryCloudConfig = {
-  autoCapture: true,
-  autoRecall: true,
-  captureMaxChars: 500,
-  idleFlushSeconds: 60,
-  backfillSessions: true,
-  backfillMaxSessions: 50,
-};
-
-const logger = { info: vi.fn(), debug: vi.fn(), warn: vi.fn() };
-
-function makeClient() {
-  return {
-    memoryIngest: vi.fn(async (sessionKey: string, messages: MemoryMessage[], metadata?: SessionMetadata) => {
-      void sessionKey;
-      void metadata;
-      return { queued: true, messageCount: messages.length };
-    }),
-    memoryBootstrapStatusMark: vi.fn(async (scope?: "files" | "sessions") => {
-      void scope;
-      return { synced: true as const, syncedAt: new Date().toISOString() };
-    }),
-  };
-}
-
-function sessionFile(sessionId: string, messages: { role: string; content: string; timestamp: number }[], extra?: Record<string, unknown>) {
-  return JSON.stringify({
-    sessionId,
-    agentId: "",
-    channel: "alfe",
-    createdAt: new Date(0).toISOString(),
-    updatedAt: new Date().toISOString(),
-    messages,
-    ...extra,
-  });
-}
-
-describe("runSessionsBackfill", () => {
-  let dir: string;
-
-  beforeEach(async () => {
-    dir = await mkdtemp(join(tmpdir(), "memory-backfill-"));
-    vi.clearAllMocks();
-  });
-
-  afterEach(async () => {
-    await rm(dir, { recursive: true, force: true });
-  });
-
-  it("marks complete immediately when the sessions directory is missing", async () => {
-    const client = makeClient();
-    await runSessionsBackfill(client, CONFIG, logger, { cutoffMs: Date.now(), sessionsDir: join(dir, "nope") });
-    expect(client.memoryIngest).not.toHaveBeenCalled();
-    expect(client.memoryBootstrapStatusMark).toHaveBeenCalledWith("sessions");
-  });
-
-  it("marks complete when no eligible sessions exist", async () => {
-    const client = makeClient();
-    await runSessionsBackfill(client, CONFIG, logger, { cutoffMs: Date.now(), sessionsDir: dir });
-    expect(client.memoryIngest).not.toHaveBeenCalled();
-    expect(client.memoryBootstrapStatusMark).toHaveBeenCalledWith("sessions");
-  });
-
-  it("skips corrupt and shape-mismatched files but ingests valid ones", async () => {
-    await writeFile(join(dir, "corrupt.json"), "{not json");
-    await writeFile(join(dir, "no-messages.json"), JSON.stringify({ sessionId: "x" }));
-    await writeFile(join(dir, "good.json"), sessionFile("alfe:dm:user1", [
-      { role: "user", content: "hello", timestamp: 1000 },
-      { role: "assistant", content: "hi there", timestamp: 2000 },
-    ]));
-
-    const client = makeClient();
-    await runSessionsBackfill(client, CONFIG, logger, { cutoffMs: Date.now(), sessionsDir: dir });
-
-    expect(client.memoryIngest).toHaveBeenCalledTimes(1);
-    const [sessionKey, messages] = client.memoryIngest.mock.calls[0];
-    expect(sessionKey).toBe("alfe:dm:user1");
-    expect(messages).toHaveLength(2);
-    expect(client.memoryBootstrapStatusMark).toHaveBeenCalledWith("sessions");
-  });
-
-  it("excludes messages at or after the cutoff (retrofit dedup)", async () => {
-    await writeFile(join(dir, "s.json"), sessionFile("alfe:dm:u", [
-      { role: "user", content: "before install", timestamp: 1000 },
-      { role: "user", content: "after install", timestamp: 5000 },
-    ]));
-
-    const client = makeClient();
-    await runSessionsBackfill(client, CONFIG, logger, { cutoffMs: 5000, sessionsDir: dir });
-
-    const [, messages] = client.memoryIngest.mock.calls[0];
-    expect(messages).toHaveLength(1);
-    expect((messages as MemoryMessage[])[0].content).toBe("before install");
-  });
-
-  it("preserves file-array positions as indexes and skips invalid entries without renumbering", async () => {
-    await writeFile(join(dir, "s.json"), sessionFile("alfe:dm:u", [
-      { role: "user", content: "first", timestamp: 1000 },
-      { role: "system", content: "not a chat role", timestamp: 1500 },
-      { role: "assistant", content: "second", timestamp: 2000 },
-    ]));
-
-    const client = makeClient();
-    await runSessionsBackfill(client, CONFIG, logger, { cutoffMs: Date.now(), sessionsDir: dir });
-
-    const [, messages] = client.memoryIngest.mock.calls[0] as [string, MemoryMessage[]];
-    expect(messages.map((m) => m.index)).toEqual([0, 2]);
-    expect(messages[0].timestamp).toBe(new Date(1000).toISOString());
-  });
-
-  it("truncates message content to captureMaxChars", async () => {
-    await writeFile(join(dir, "s.json"), sessionFile("alfe:dm:u", [
-      { role: "user", content: "x".repeat(2000), timestamp: 1000 },
-    ]));
-
-    const client = makeClient();
-    await runSessionsBackfill(client, CONFIG, logger, { cutoffMs: Date.now(), sessionsDir: dir });
-
-    const [, messages] = client.memoryIngest.mock.calls[0] as [string, MemoryMessage[]];
-    expect(messages[0].content).toHaveLength(500);
-  });
-
-  it("sends each session as exactly one ingest call (no cross-chunk race)", async () => {
-    const messages = Array.from({ length: 101 }, (_, i) => ({
-      role: "user",
-      content: `msg ${String(i)}`,
-      timestamp: 1000 + i,
-    }));
-    await writeFile(join(dir, "s.json"), sessionFile("alfe:dm:u", messages));
-
-    const client = makeClient();
-    await runSessionsBackfill(client, CONFIG, logger, { cutoffMs: Date.now(), sessionsDir: dir });
-
-    expect(client.memoryIngest).toHaveBeenCalledTimes(1);
-    expect(client.memoryIngest.mock.calls[0][1]).toHaveLength(101);
-  });
-
-  it("keeps only the most recent 500 messages of a session, preserving original indexes", async () => {
-    const messages = Array.from({ length: 600 }, (_, i) => ({
-      role: "user",
-      content: `msg ${String(i)}`,
-      timestamp: 1000 + i,
-    }));
-    await writeFile(join(dir, "s.json"), sessionFile("alfe:dm:u", messages));
-
-    const client = makeClient();
-    await runSessionsBackfill(client, CONFIG, logger, { cutoffMs: Date.now(), sessionsDir: dir });
-
-    expect(client.memoryIngest).toHaveBeenCalledTimes(1);
-    const sent = client.memoryIngest.mock.calls[0][1] as MemoryMessage[];
-    expect(sent).toHaveLength(500);
-    expect(sent[0].index).toBe(100);
-    expect(sent[sent.length - 1].index).toBe(599);
-  });
-
-  it("shrinks the window to the most recent messages when the byte budget would overflow", async () => {
-    // ~40KB of content per message → only 4 fit in the 180KB budget.
-    const messages = Array.from({ length: 10 }, (_, i) => ({
-      role: "user",
-      content: "x".repeat(40_000),
-      timestamp: 1000 + i,
-    }));
-    await writeFile(join(dir, "s.json"), sessionFile("alfe:dm:u", messages));
-
-    const client = makeClient();
-    await runSessionsBackfill(client, { ...CONFIG, captureMaxChars: 50_000 }, logger, { cutoffMs: Date.now(), sessionsDir: dir });
-
-    expect(client.memoryIngest).toHaveBeenCalledTimes(1);
-    const sent = client.memoryIngest.mock.calls[0][1] as MemoryMessage[];
-    expect(sent).toHaveLength(4);
-    expect(sent[sent.length - 1].index).toBe(9);
-  });
-
-  it("skips sessions whose sessionId exceeds the server's 256-char cap", async () => {
-    await writeFile(join(dir, "long.json"), sessionFile("x".repeat(300), [
-      { role: "user", content: "hello", timestamp: 1000 },
-    ]));
-
-    const client = makeClient();
-    await runSessionsBackfill(client, CONFIG, logger, { cutoffMs: Date.now(), sessionsDir: dir });
-
-    expect(client.memoryIngest).not.toHaveBeenCalled();
-    expect(client.memoryBootstrapStatusMark).toHaveBeenCalledWith("sessions");
-  });
-
-  it("does not let post-cutoff sessions starve pre-cutoff sessions out of the cap (retrofit)", async () => {
-    // Newest session is entirely post-install — emptied by the cutoff. It
-    // must not occupy the single cap slot.
-    await writeFile(join(dir, "post-install.json"), sessionFile("alfe:dm:recent", [
-      { role: "user", content: "captured live already", timestamp: 9000 },
-    ]));
-    await writeFile(join(dir, "pre-install.json"), sessionFile("alfe:dm:old", [
-      { role: "user", content: "history worth keeping", timestamp: 1000 },
-    ]));
-
-    const client = makeClient();
-    await runSessionsBackfill(client, { ...CONFIG, backfillMaxSessions: 1 }, logger, { cutoffMs: 5000, sessionsDir: dir });
-
-    expect(client.memoryIngest).toHaveBeenCalledTimes(1);
-    expect(client.memoryIngest.mock.calls[0][0]).toBe("alfe:dm:old");
-  });
-
-  it("caps at backfillMaxSessions, keeping the most recent sessions", async () => {
-    await writeFile(join(dir, "old.json"), sessionFile("alfe:dm:old", [
-      { role: "user", content: "old", timestamp: 1000 },
-    ]));
-    await writeFile(join(dir, "new.json"), sessionFile("alfe:dm:new", [
-      { role: "user", content: "new", timestamp: 9000 },
-    ]));
-
-    const client = makeClient();
-    await runSessionsBackfill(client, { ...CONFIG, backfillMaxSessions: 1 }, logger, { cutoffMs: Date.now(), sessionsDir: dir });
-
-    expect(client.memoryIngest).toHaveBeenCalledTimes(1);
-    expect(client.memoryIngest.mock.calls[0][0]).toBe("alfe:dm:new");
-  });
-
-  it("aborts without marking when an ingest call fails", async () => {
-    await writeFile(join(dir, "s.json"), sessionFile("alfe:dm:u", [
-      { role: "user", content: "hello", timestamp: 1000 },
-    ]));
-
-    const client = makeClient();
-    client.memoryIngest.mockRejectedValueOnce(new Error("boom"));
-    await runSessionsBackfill(client, CONFIG, logger, { cutoffMs: Date.now(), sessionsDir: dir });
-
-    expect(client.memoryBootstrapStatusMark).not.toHaveBeenCalled();
-    expect(logger.warn).toHaveBeenCalled();
-  });
-
-  it("passes session channel and userId as ingest metadata", async () => {
-    await writeFile(join(dir, "s.json"), sessionFile("alfe:dm:u", [
-      { role: "user", content: "hello", timestamp: 1000 },
-    ], { channel: "alfe", userId: "user_123" }));
-
-    const client = makeClient();
-    await runSessionsBackfill(client, CONFIG, logger, { cutoffMs: Date.now(), sessionsDir: dir });
-
-    const metadata = client.memoryIngest.mock.calls[0][2];
-    expect(metadata).toEqual({ channelId: "alfe", userId: "user_123" });
-  });
-
-  it("does not warn or fail when the mark call itself fails (retries next startup)", async () => {
-    await writeFile(join(dir, "s.json"), sessionFile("alfe:dm:u", [
-      { role: "user", content: "hello", timestamp: 1000 },
-    ]));
-
-    const client = makeClient();
-    client.memoryBootstrapStatusMark.mockRejectedValueOnce(new Error("mark failed"));
-    await expect(
-      runSessionsBackfill(client, CONFIG, logger, { cutoffMs: Date.now(), sessionsDir: dir }),
-    ).resolves.toBeUndefined();
-    expect(logger.warn).toHaveBeenCalledWith(
-      "sessions backfill: mark failed; will retry on next startup",
-      expect.anything(),
-    );
-  });
-
-  it("does not mark complete when the directory read fails for a non-ENOENT reason", async () => {
-    const locked = join(dir, "locked");
-    await mkdir(locked);
-    await chmod(locked, 0o000);
-    try {
-      const client = makeClient();
-      await runSessionsBackfill(client, CONFIG, logger, { cutoffMs: Date.now(), sessionsDir: locked });
-      expect(client.memoryIngest).not.toHaveBeenCalled();
-      expect(client.memoryBootstrapStatusMark).not.toHaveBeenCalled();
-      expect(logger.warn).toHaveBeenCalled();
-    } finally {
-      await chmod(locked, 0o755);
-    }
-  });
-
-  it("ignores non-json files and nested directories", async () => {
-    await writeFile(join(dir, "notes.txt"), "not a session");
-    await mkdir(join(dir, "sub.json.d"));
-    const client = makeClient();
-    await runSessionsBackfill(client, CONFIG, logger, { cutoffMs: Date.now(), sessionsDir: dir });
-    expect(client.memoryIngest).not.toHaveBeenCalled();
-    expect(client.memoryBootstrapStatusMark).toHaveBeenCalledWith("sessions");
-  });
-});

package/src/auto-capture.ts

@@ -1,108 +0,0 @@
-import type { MemoryApi, MemoryCloudConfig, MemoryMessage, SessionMetadata } from "./types.js";
-
-/**
- * Auto-capture manages the idle debounce timer and flushes
- * accumulated messages to the memory service.
- *
- * Flow:
- * 1. on_message_received: track message, reset timer
- * 2. Timer fires (60s idle): flush batch to /memory/ingest
- * 3. agent_end: final flush of remaining messages
- */
-export class AutoCapture {
-  private static readonly MAX_QUEUE_SIZE = 500;
-  private pendingMessages: MemoryMessage[] = [];
-  private messageIndex = 0;
-  private idleTimer: ReturnType<typeof setTimeout> | null = null;
-  private sessionKey: string | null = null;
-  private metadata: SessionMetadata = {};
-
-  /**
-   * Per-boot STRICTLY-monotonic epoch, resolved once at process start by
-   * `resolveIngestEpoch` (index.ts) as `max(Date.now(), lastEpoch + 1)` from a
-   * persisted state file — so it never regresses even if the wall clock steps
-   * backward across a restart. Stamped on every flush so the memory service can
-   * tell a restarted daemon (whose `messageIndex` counter has reset to 0) from
-   * a continuing one and reset the server-side high-water mark accordingly —
-   * otherwise post-restart captures are silently dropped by the surviving
-   * watermark. Defaults to `Date.now()` only for tests that don't exercise the
-   * restart path. See ingest-epoch.ts + services/memory/src/lib/ingest-offset.ts.
-   */
-  constructor(
-    private readonly client: MemoryApi,
-    private readonly config: MemoryCloudConfig,
-    private readonly logger: { debug: (msg: string, ctx?: Record<string, unknown>) => void; warn: (msg: string, ctx?: Record<string, unknown>) => void },
-    private readonly ingestEpoch: number = Date.now(),
-  ) {}
-
-  setSession(sessionKey: string, metadata?: SessionMetadata): void {
-    this.sessionKey = sessionKey;
-    if (metadata) this.metadata = metadata;
-  }
-
-  trackMessage(role: string, content: string): void {
-    if (!this.config.autoCapture) return;
-    if (content.length > this.config.captureMaxChars) {
-      content = content.slice(0, this.config.captureMaxChars);
-    }
-
-    // Enforce max queue size — drop oldest if exceeded
-    if (this.pendingMessages.length >= AutoCapture.MAX_QUEUE_SIZE) {
-      this.logger.warn("Memory queue full — dropping oldest message", { queueSize: this.pendingMessages.length });
-      this.pendingMessages.shift();
-    }
-
-    this.pendingMessages.push({
-      role,
-      content,
-      index: this.messageIndex++,
-      timestamp: new Date().toISOString(),
-    });
-
-    this.resetIdleTimer();
-  }
-
-  async flush(): Promise<void> {
-    if (this.pendingMessages.length === 0 || !this.sessionKey) return;
-
-    const batch = [...this.pendingMessages];
-    this.pendingMessages = [];
-
-    this.logger.debug("Flushing memory batch", {
-      sessionKey: this.sessionKey,
-      messageCount: batch.length,
-    });
-
-    try {
-      await this.client.memoryIngest(this.sessionKey, batch, this.metadata, this.ingestEpoch);
-    } catch (err) {
-      this.logger.warn("Failed to flush memories", { error: String(err) });
-      // Re-add failed messages for next flush attempt
-      this.pendingMessages.unshift(...batch);
-    }
-  }
-
-  async onAgentEnd(): Promise<void> {
-    this.clearIdleTimer();
-    await this.flush();
-  }
-
-  destroy(): void {
-    this.clearIdleTimer();
-  }
-
-  private resetIdleTimer(): void {
-    this.clearIdleTimer();
-    this.idleTimer = setTimeout(() => {
-      void this.flush();
-    }, this.config.idleFlushSeconds * 1000);
-    this.idleTimer.unref();
-  }
-
-  private clearIdleTimer(): void {
-    if (this.idleTimer) {
-      clearTimeout(this.idleTimer);
-      this.idleTimer = null;
-    }
-  }
-}

package/src/auto-recall.ts

@@ -1,66 +0,0 @@
-import type { MemoryApi, MemoryCloudConfig } from "./types.js";
-
-/**
- * Auto-recall loads tiered memory context at session start
- * and formats it for injection into the agent's prompt.
- *
- * Called from the before_agent_start hook.
- */
-export class AutoRecall {
-  constructor(
-    private readonly client: MemoryApi,
-    private readonly config: MemoryCloudConfig,
-    private readonly logger: { debug: (msg: string, ctx?: Record<string, unknown>) => void; warn: (msg: string, ctx?: Record<string, unknown>) => void },
-  ) {}
-
-  /**
-   * Load memory context and return formatted XML for prompt injection.
-   * Returns prependContext string for the before_agent_start hook result.
-   */
-  async loadForPrompt(userMessage: string): Promise<string | undefined> {
-    if (!this.config.autoRecall) return undefined;
-
-    try {
-      // Detect topic from user message (first significant word)
-      const topicHint = extractTopicHint(userMessage);
-
-      // Load L1 (facts) + L2 (topic context) in one call
-      const tier = topicHint ? 2 : 1;
-      const context = await this.client.memoryLoadContext(tier, topicHint);
-
-      if (!context.formatted || context.formatted.length === 0) {
-        this.logger.debug("No relevant memories found for prompt");
-        return undefined;
-      }
-
-      this.logger.debug("Loaded memory context for prompt", {
-        tier,
-        topicHint,
-        factCount: Array.isArray(context.facts) ? context.facts.length : 0,
-        memoryCount: Array.isArray(context.memories) ? context.memories.length : 0,
-        tokenEstimate: typeof context.tokenEstimate === "number" ? context.tokenEstimate : 0,
-      });
-
-      return context.formatted;
-    } catch (err) {
-      this.logger.warn("Failed to load memory context", { error: String(err) });
-      return undefined;
-    }
-  }
-}
-
-/**
- * Simple topic hint extraction from user message.
- * Returns the first capitalized word or proper noun as a potential topic.
- */
-function extractTopicHint(message: string): string | undefined {
-  // Look for proper nouns (capitalized words not at sentence start)
-  const words = message.split(/\s+/);
-  for (let i = 1; i < words.length; i++) {
-    const word = words[i];
-    if (word && word.length > 2 && /^[A-Z]/.test(word) && !/^(The|And|But|For|With|This|That|What|How|Why|When|Where)$/.test(word)) {
-      return word.toLowerCase();
-    }
-  }
-  return undefined;
-}

package/src/formatter.ts

@@ -1,30 +0,0 @@
-import type { MemorySearchResult } from "./types.js";
-
-/**
- * Format memory search results into an XML block for agent context injection.
- * KG facts appear first (precise), then vector results (supporting context).
- */
-export function formatSearchResults(results: MemorySearchResult): string {
-  const parts: string[] = [];
-
-  if (results.facts.length > 0) {
-    parts.push("Known facts:");
-    for (const fact of results.facts) {
-      const since = typeof fact.since === "string" ? fact.since.slice(0, 10) : "unknown";
-      parts.push(`- ${fact.subject} ${fact.predicate} ${fact.object} (since ${since}, confidence: ${String(fact.confidence)})`);
-    }
-  }
-
-  if (results.memories.length > 0) {
-    if (parts.length > 0) parts.push("");
-    parts.push("Related conversations:");
-    for (const mem of results.memories) {
-      const truncated = mem.text.length > 200 ? `${mem.text.slice(0, 200)}...` : mem.text;
-      parts.push(`- [${mem.topic}/${mem.subtopic}] ${truncated}`);
-    }
-  }
-
-  if (parts.length === 0) return "";
-
-  return `<relevant-memories>\n${parts.join("\n")}\n</relevant-memories>`;
-}