openclaw-memory-hierarchical 0.1.0

package/summarize.ts

@@ -0,0 +1,190 @@
+/**
+ * Summarization logic for hierarchical memory.
+ *
+ * Uses the LLM to generate autobiographical summaries of conversation chunks.
+ */
+
+import type { HierarchicalMemoryConfig, SummaryLevel } from "./types.js";
+import {
+  buildChunkSummarizationPrompt,
+  buildMergeSummariesPrompt,
+  MERGE_SUMMARIES_SYSTEM,
+  SUMMARIZE_CHUNK_SYSTEM,
+} from "./prompts.js";
+
+export type SummarizationParams = {
+  /** Model to use for summarization */
+  model: string;
+  /** Provider for the model */
+  provider: string;
+  /** API key for the provider */
+  apiKey: string;
+  /** Abort signal */
+  signal?: AbortSignal;
+  /** Target token count for the summary */
+  targetTokens?: number;
+};
+
+export type ChunkToSummarize = {
+  /** Messages in this chunk */
+  messages: Array<{ role: string; content?: unknown }>;
+  /** Entry IDs covered by this chunk */
+  entryIds: string[];
+  /** Session ID these entries came from */
+  sessionId: string;
+  /** Estimated token count of the chunk */
+  tokenEstimate: number;
+};
+
+/**
+ * Estimate tokens for an array of messages.
+ */
+export function estimateMessagesTokens(
+  messages: Array<{ role: string; content?: unknown }>,
+): number {
+  let total = 0;
+  for (const msg of messages) {
+    // Simple estimation based on content length
+    const content =
+      typeof msg.content === "string" ? msg.content : JSON.stringify(msg.content ?? "");
+    // Rough estimate: 4 chars per token
+    total += Math.ceil(content.length / 4);
+  }
+  return total;
+}
+
+/**
+ * Summarize a chunk of conversation messages.
+ */
+export async function summarizeChunk(params: {
+  chunk: ChunkToSummarize;
+  priorSummaries: string[];
+  config: HierarchicalMemoryConfig;
+  summarization: SummarizationParams;
+}): Promise<string> {
+  const { chunk, priorSummaries, config, summarization } = params;
+
+  const prompt = buildChunkSummarizationPrompt({
+    priorSummaries,
+    messages: chunk.messages,
+  });
+
+  const summary = await callLlmForSummary({
+    systemPrompt: SUMMARIZE_CHUNK_SYSTEM,
+    userPrompt: prompt,
+    targetTokens: config.summaryTargetTokens,
+    model: summarization.model,
+    provider: summarization.provider,
+    apiKey: summarization.apiKey,
+    signal: summarization.signal,
+  });
+
+  return summary;
+}
+
+/**
+ * Merge multiple summaries into one.
+ */
+export async function mergeSummaries(params: {
+  summaries: string[];
+  olderContext: string[];
+  config: HierarchicalMemoryConfig;
+  summarization: SummarizationParams;
+}): Promise<string> {
+  const { summaries, olderContext, config, summarization } = params;
+
+  const prompt = buildMergeSummariesPrompt({
+    summaries,
+    olderContext: olderContext.length > 0 ? olderContext : undefined,
+  });
+
+  const merged = await callLlmForSummary({
+    systemPrompt: MERGE_SUMMARIES_SYSTEM,
+    userPrompt: prompt,
+    targetTokens: config.summaryTargetTokens,
+    model: summarization.model,
+    provider: summarization.provider,
+    apiKey: summarization.apiKey,
+    signal: summarization.signal,
+  });
+
+  return merged;
+}
+
+/**
+ * Call the LLM to generate a summary.
+ * Uses completeSimple for a straightforward non-streaming completion.
+ */
+async function callLlmForSummary(params: {
+  systemPrompt: string;
+  userPrompt: string;
+  model: string;
+  provider: string;
+  apiKey: string;
+  signal?: AbortSignal;
+  targetTokens?: number;
+}): Promise<string> {
+  // Dynamic import to avoid loading heavy deps at module level
+  const { completeSimple, getModel } = await import("@mariozechner/pi-ai");
+
+  const model = getModel(params.provider, params.model);
+
+  if (!model) {
+    throw new Error(`Failed to resolve model: ${params.provider}/${params.model}`);
+  }
+
+  const maxTokens = params.targetTokens ?? 1000;
+
+  const res = await completeSimple(
+    model,
+    {
+      systemPrompt: params.systemPrompt,
+      messages: [
+        {
+          role: "user",
+          content: params.userPrompt,
+          timestamp: Date.now(),
+        },
+      ],
+    },
+    {
+      apiKey: params.apiKey,
+      maxTokens,
+      signal: params.signal,
+    },
+  );
+
+  // Extract text from the response
+  const textContent = res.content.find(
+    (c): c is { type: "text"; text: string } => c.type === "text",
+  );
+  return textContent?.text?.trim() ?? "";
+}
+
+/**
+ * Determine the source level for a target level.
+ */
+export function getSourceLevel(targetLevel: SummaryLevel): "L0" | "L1" | "L2" {
+  switch (targetLevel) {
+    case "L1":
+      return "L0";
+    case "L2":
+      return "L1";
+    case "L3":
+      return "L2";
+  }
+}
+
+/**
+ * Get the next level up from a given level.
+ */
+export function getNextLevel(level: SummaryLevel): SummaryLevel | null {
+  switch (level) {
+    case "L1":
+      return "L2";
+    case "L2":
+      return "L3";
+    case "L3":
+      return null; // No level above L3
+  }
+}

package/timer.ts

@@ -0,0 +1,128 @@
+/**
+ * Timer for running the hierarchical memory worker periodically.
+ *
+ * All state is instance-scoped in the returned handle, so multiple
+ * timers (e.g., different agentIds or tests) don't collide.
+ */
+
+import type { PluginConfig } from "./config.js";
+import { resolveHierarchicalMemoryConfig } from "./config.js";
+import { runHierarchicalMemoryWorker } from "./worker.js";
+
+export type HierarchicalMemoryTimerHandle = {
+  /** Stop the timer */
+  stop: () => void;
+  /** Get the last run result */
+  getLastResult: () => WorkerRunInfo | null;
+};
+
+type WorkerRunInfo = {
+  timestamp: number;
+  success: boolean;
+  chunksProcessed?: number;
+  mergesPerformed?: number;
+  error?: string;
+  durationMs?: number;
+};
+
+/**
+ * Start the hierarchical memory worker timer.
+ * Returns a handle to stop the timer.
+ */
+export function startHierarchicalMemoryTimer(params: {
+  agentId: string;
+  pluginConfig: PluginConfig;
+  stateDir: string;
+  log?: {
+    info: (msg: string) => void;
+    warn: (msg: string) => void;
+    error: (msg: string) => void;
+  };
+}): HierarchicalMemoryTimerHandle {
+  const memoryConfig = resolveHierarchicalMemoryConfig(params.pluginConfig);
+
+  const log = params.log ?? {
+    info: console.log,
+    warn: console.warn,
+    error: console.error,
+  };
+
+  // Instance-scoped state
+  let handle: ReturnType<typeof setInterval> | null = null;
+  let lastResult: WorkerRunInfo | null = null;
+  let isRunning = false;
+
+  const runWorker = async () => {
+    if (isRunning) {
+      return; // Skip if previous run is still in progress
+    }
+
+    isRunning = true;
+    try {
+      const result = await runHierarchicalMemoryWorker({
+        agentId: params.agentId,
+        pluginConfig: params.pluginConfig,
+        stateDir: params.stateDir,
+      });
+
+      lastResult = {
+        timestamp: Date.now(),
+        success: result.success,
+        chunksProcessed: result.chunksProcessed,
+        mergesPerformed: result.mergesPerformed,
+        error: result.error,
+        durationMs: result.durationMs,
+      };
+
+      if (result.skipped) {
+        // Silent skip - lock held or disabled
+        return;
+      }
+
+      if (result.success) {
+        if ((result.chunksProcessed ?? 0) > 0 || (result.mergesPerformed ?? 0) > 0) {
+          log.info(
+            `hierarchical memory: processed ${result.chunksProcessed ?? 0} chunks, ` +
+              `${result.mergesPerformed ?? 0} merges (${result.durationMs}ms)`,
+          );
+        }
+      } else if (result.error) {
+        log.error(`hierarchical memory worker failed: ${result.error}`);
+      }
+    } catch (err) {
+      const error = err instanceof Error ? err.message : String(err);
+      lastResult = {
+        timestamp: Date.now(),
+        success: false,
+        error,
+      };
+      log.error(`hierarchical memory worker error: ${error}`);
+    } finally {
+      isRunning = false;
+    }
+  };
+
+  // Run immediately on start
+  void runWorker();
+
+  // Then run on interval
+  handle = setInterval(() => {
+    void runWorker();
+  }, memoryConfig.workerIntervalMs);
+
+  log.info(
+    `hierarchical memory timer started (interval: ${Math.round(memoryConfig.workerIntervalMs / 1000)}s)`,
+  );
+
+  const timerHandle: HierarchicalMemoryTimerHandle = {
+    stop: () => {
+      if (handle) {
+        clearInterval(handle);
+        handle = null;
+      }
+    },
+    getLastResult: () => lastResult,
+  };
+
+  return timerHandle;
+}

package/types.ts

@@ -0,0 +1,139 @@
+/**
+ * Hierarchical Memory System Types
+ *
+ * A 2048-style compression system for long-running conversations.
+ * Chunks of ~6k tokens are summarized to ~1k, then 6 summaries merge into 1.
+ */
+
+export type SummaryLevel = "L1" | "L2" | "L3";
+
+export type SummaryEntry = {
+  /** Unique ID within the level (e.g., "0001") */
+  id: string;
+
+  /** When this summary was created */
+  createdAt: number;
+
+  /** Estimated token count of the summary */
+  tokenEstimate: number;
+
+  /** What level this summary belongs to */
+  level: SummaryLevel;
+
+  /** Source level that was summarized */
+  sourceLevel: "L0" | "L1" | "L2";
+
+  /**
+   * IDs of source items:
+   * - For L1: entry IDs from the session JSONL
+   * - For L2/L3: summary IDs from the lower level
+   */
+  sourceIds: string[];
+
+  /** Session ID this summary originated from (for L1 only) */
+  sourceSessionId?: string;
+
+  /** If merged into a higher level, the ID of that summary */
+  mergedInto: string | null;
+};
+
+export type SummaryIndex = {
+  /** Schema version for migrations */
+  version: 1;
+
+  /** Agent this index belongs to */
+  agentId: string;
+
+  /** Last entry ID from JSONL that was summarized */
+  lastSummarizedEntryId: string | null;
+
+  /** Session ID of the last summarized entry */
+  lastSummarizedSessionId: string | null;
+
+  /** Summaries organized by level */
+  levels: {
+    L1: SummaryEntry[];
+    L2: SummaryEntry[];
+    L3: SummaryEntry[];
+  };
+
+  /** Worker state */
+  worker: {
+    lastRunAt: number | null;
+    lastRunDurationMs: number | null;
+    lastError: string | null;
+  };
+};
+
+export type HierarchicalMemoryConfig = {
+  /** Enable the hierarchical memory system (default: false) */
+  enabled: boolean;
+
+  /** How often the worker runs in milliseconds (default: 300000 = 5 min) */
+  workerIntervalMs: number;
+
+  /** Minimum tokens in a chunk before summarization (default: 6000) */
+  chunkTokens: number;
+
+  /** Target token count for summaries (default: 1000) */
+  summaryTargetTokens: number;
+
+  /** Number of summaries before merging to next level (default: 6) */
+  mergeThreshold: number;
+
+  /** Messages must be this many tokens behind current to be eligible (default: 30000) */
+  pruningBoundaryTokens: number;
+
+  /** Model to use for summarization (default: session's model) */
+  model?: string;
+
+  /** Maximum levels (default: 3) */
+  maxLevels: number;
+};
+
+export const DEFAULT_HIERARCHICAL_MEMORY_CONFIG: HierarchicalMemoryConfig = {
+  enabled: false,
+  workerIntervalMs: 5 * 60 * 1000, // 5 minutes
+  chunkTokens: 6000,
+  summaryTargetTokens: 1000,
+  mergeThreshold: 6,
+  pruningBoundaryTokens: 30000,
+  maxLevels: 3,
+};
+
+export function createEmptyIndex(agentId: string): SummaryIndex {
+  return {
+    version: 1,
+    agentId,
+    lastSummarizedEntryId: null,
+    lastSummarizedSessionId: null,
+    levels: {
+      L1: [],
+      L2: [],
+      L3: [],
+    },
+    worker: {
+      lastRunAt: null,
+      lastRunDurationMs: null,
+      lastError: null,
+    },
+  };
+}
+
+/** Get summaries that haven't been merged into a higher level */
+export function getUnmergedSummaries(index: SummaryIndex, level: SummaryLevel): SummaryEntry[] {
+  return index.levels[level].filter((s) => s.mergedInto === null);
+}
+
+/** Get all summaries for context injection (oldest to newest) */
+export function getAllSummariesForContext(index: SummaryIndex): {
+  L3: SummaryEntry[];
+  L2: SummaryEntry[];
+  L1: SummaryEntry[];
+} {
+  return {
+    L3: getUnmergedSummaries(index, "L3"),
+    L2: getUnmergedSummaries(index, "L2"),
+    L1: getUnmergedSummaries(index, "L1"),
+  };
+}