@parkgogogo/openclaw-reflection 0.1.0

package/src/consolidation/consolidator.ts

@@ -0,0 +1,316 @@
+import * as path from "path";
+import type { JsonSchema, LLMService, Logger } from "../types.js";
+import { readFile, writeFileWithLock } from "../utils/file-utils.js";
+import { CONSOLIDATION_SYSTEM_PROMPT } from "./prompt.js";
+import type {
+  ConsolidatedFilename,
+  ConsolidationConfig,
+  ConsolidationPatch,
+  ConsolidationProposal,
+  ConsolidationResult,
+} from "./types.js";
+
+const MANAGED_FILES: ConsolidatedFilename[] = [
+  "MEMORY.md",
+  "USER.md",
+  "SOUL.md",
+  "TOOLS.md",
+];
+const VALID_PATCH_ACTIONS = new Set<ConsolidationPatch["action"]>([
+  "add",
+  "replace",
+  "remove",
+]);
+const CONSOLIDATION_RESPONSE_SCHEMA: JsonSchema = {
+  type: "object",
+  additionalProperties: false,
+  required: ["decision", "proposed_updates"],
+  properties: {
+    decision: {
+      type: "string",
+      enum: ["NO_WRITE", "WRITE_CLEANUP"],
+    },
+    proposed_updates: {
+      type: "object",
+      additionalProperties: false,
+      properties: {
+        "MEMORY.md": {
+          type: "array",
+          items: {
+            type: "object",
+            additionalProperties: false,
+            required: ["section", "action", "content"],
+            properties: {
+              section: { type: "string" },
+              action: { type: "string", enum: ["add", "replace", "remove"] },
+              content: { type: "string" },
+            },
+          },
+        },
+        "USER.md": {
+          type: "array",
+          items: {
+            type: "object",
+            additionalProperties: false,
+            required: ["section", "action", "content"],
+            properties: {
+              section: { type: "string" },
+              action: { type: "string", enum: ["add", "replace", "remove"] },
+              content: { type: "string" },
+            },
+          },
+        },
+        "SOUL.md": {
+          type: "array",
+          items: {
+            type: "object",
+            additionalProperties: false,
+            required: ["section", "action", "content"],
+            properties: {
+              section: { type: "string" },
+              action: { type: "string", enum: ["add", "replace", "remove"] },
+              content: { type: "string" },
+            },
+          },
+        },
+        "TOOLS.md": {
+          type: "array",
+          items: {
+            type: "object",
+            additionalProperties: false,
+            required: ["section", "action", "content"],
+            properties: {
+              section: { type: "string" },
+              action: { type: "string", enum: ["add", "replace", "remove"] },
+              content: { type: "string" },
+            },
+          },
+        },
+      },
+    },
+  },
+};
+
+function getErrorMessage(error: unknown): string {
+  if (error instanceof Error) {
+    return error.message;
+  }
+
+  return String(error);
+}
+
+function stripMdExtension(filename: string): string {
+  return filename.endsWith(".md") ? filename.slice(0, -3) : filename;
+}
+
+function splitContentLines(content: string): string[] {
+  const trimmed = content.trim();
+  return trimmed === "" ? [] : trimmed.split(/\r?\n/);
+}
+
+function findSectionRange(
+  lines: string[],
+  section: string
+): { start: number; end: number } | null {
+  const sectionHeader = `## ${section}`;
+  const start = lines.findIndex((line) => line.trim() === sectionHeader);
+
+  if (start === -1) {
+    return null;
+  }
+
+  let end = lines.length;
+  for (let index = start + 1; index < lines.length; index += 1) {
+    if (/^##\s+/.test(lines[index].trim())) {
+      end = index;
+      break;
+    }
+  }
+
+  return { start, end };
+}
+
+function applyPatchToContent(
+  existingContent: string,
+  patch: ConsolidationPatch
+): string {
+  const lines = existingContent.replace(/\r\n/g, "\n").split("\n");
+  const sectionHeader = `## ${patch.section}`;
+  const contentLines = splitContentLines(patch.content);
+  const range = findSectionRange(lines, patch.section);
+
+  if (!range) {
+    if (patch.action === "remove") {
+      return `${existingContent.trimEnd()}\n`;
+    }
+
+    const appended = [existingContent.trimEnd(), "", sectionHeader, ...contentLines]
+      .join("\n")
+      .trimEnd();
+    return `${appended}\n`;
+  }
+
+  const before = lines.slice(0, range.start);
+  const currentBody = lines.slice(range.start + 1, range.end);
+  const after = lines.slice(range.end);
+  let nextBody = currentBody;
+
+  if (patch.action === "replace") {
+    nextBody = contentLines;
+  } else if (patch.action === "add") {
+    const existing = new Set(
+      currentBody.map((line) => line.trim()).filter((line) => line !== "")
+    );
+    nextBody = [
+      ...currentBody,
+      ...contentLines.filter((line) => !existing.has(line.trim())),
+    ];
+  } else if (patch.action === "remove") {
+    const removed = new Set(contentLines.map((line) => line.trim()));
+    nextBody = currentBody.filter((line) => !removed.has(line.trim()));
+  }
+
+  return `${[...before, sectionHeader, ...nextBody, ...after].join("\n").trimEnd()}\n`;
+}
+
+export class Consolidator {
+  private config: ConsolidationConfig;
+  private logger: Logger;
+  private llmService: LLMService;
+
+  constructor(config: ConsolidationConfig, logger: Logger, llmService: LLMService) {
+    this.config = config;
+    this.logger = logger;
+    this.llmService = llmService;
+  }
+
+  async consolidate(): Promise<ConsolidationResult> {
+    const currentFiles = await this.readManagedFiles();
+    const proposal = await this.generateProposal(currentFiles);
+
+    if (proposal.decision === "NO_WRITE") {
+      this.logger.info("Consolidator", "Skipped consolidation cleanup", {
+        decision: proposal.decision,
+      });
+      return { updates: {} };
+    }
+
+    const updates = this.applyProposalToFiles(currentFiles, proposal);
+    await this.writeUpdates(updates);
+
+    this.logger.info("Consolidator", "Consolidation cleanup completed", {
+      updatedFiles: Object.keys(updates),
+    });
+
+    return { updates };
+  }
+
+  private async readManagedFiles(): Promise<Record<ConsolidatedFilename, string>> {
+    const files = {} as Record<ConsolidatedFilename, string>;
+
+    for (const filename of MANAGED_FILES) {
+      const filePath = path.join(this.config.workspaceDir, filename);
+      files[filename] =
+        (await readFile(filePath)) ?? `# ${stripMdExtension(filename)}\n`;
+    }
+
+    return files;
+  }
+
+  private buildPrompt(
+    currentFiles: Record<ConsolidatedFilename, string>
+  ): string {
+    return [
+      "Current MEMORY.md:",
+      currentFiles["MEMORY.md"].trim() || "(empty)",
+      "",
+      "Current USER.md:",
+      currentFiles["USER.md"].trim() || "(empty)",
+      "",
+      "Current SOUL.md:",
+      currentFiles["SOUL.md"].trim() || "(empty)",
+      "",
+      "Current TOOLS.md:",
+      currentFiles["TOOLS.md"].trim() || "(empty)",
+      "",
+      "Return JSON only as specified in the system prompt.",
+    ].join("\n");
+  }
+
+  private async generateProposal(
+    currentFiles: Record<ConsolidatedFilename, string>
+  ): Promise<ConsolidationProposal> {
+    try {
+      const response = await this.llmService.generateObject<{
+        decision: "NO_WRITE" | "WRITE_CLEANUP";
+        proposed_updates: Partial<Record<ConsolidatedFilename, ConsolidationPatch[]>>;
+      }>({
+        systemPrompt: CONSOLIDATION_SYSTEM_PROMPT,
+        userPrompt: this.buildPrompt(currentFiles),
+        schema: CONSOLIDATION_RESPONSE_SCHEMA,
+      });
+      return {
+        decision: response.decision,
+        proposedUpdates: response.proposed_updates ?? {},
+      };
+    } catch (error) {
+      const reason = getErrorMessage(error);
+      this.logger.error("Consolidator", "Consolidation LLM request failed", {
+        reason,
+      });
+      return {
+        decision: "NO_WRITE",
+        proposedUpdates: {},
+      };
+    }
+  }
+
+  private applyProposalToFiles(
+    currentFiles: Record<ConsolidatedFilename, string>,
+    proposal: ConsolidationProposal
+  ): ConsolidationResult["updates"] {
+    const updates: ConsolidationResult["updates"] = {};
+
+    for (const filename of MANAGED_FILES) {
+      const patches = proposal.proposedUpdates[filename];
+      if (!patches || patches.length === 0) {
+        continue;
+      }
+
+      let nextContent = currentFiles[filename];
+      for (const patch of patches) {
+        nextContent = applyPatchToContent(nextContent, patch);
+      }
+
+      updates[filename] = nextContent;
+    }
+
+    return updates;
+  }
+
+  private async writeUpdates(
+    updates: ConsolidationResult["updates"]
+  ): Promise<void> {
+    const entries = Object.entries(updates) as Array<
+      [ConsolidatedFilename, string | undefined]
+    >;
+
+    for (const [filename, content] of entries) {
+      if (typeof content !== "string") {
+        continue;
+      }
+
+      const filePath = path.join(this.config.workspaceDir, filename);
+
+      try {
+        await writeFileWithLock(filePath, content);
+      } catch (error) {
+        this.logger.error("Consolidator", "Failed to write consolidated file", {
+          filename,
+          filePath,
+          reason: getErrorMessage(error),
+        });
+      }
+    }
+  }
+}

package/src/consolidation/index.ts

@@ -0,0 +1,9 @@
+export { Consolidator } from "./consolidator.js";
+export { ConsolidationScheduler } from "./scheduler.js";
+export type {
+  ConsolidationConfig,
+  ConsolidatedFilename,
+  ConsolidationPatch,
+  ConsolidationProposal,
+  ConsolidationResult,
+} from "./types.js";

package/src/consolidation/prompt.ts

@@ -0,0 +1,58 @@
+export const CONSOLIDATION_SYSTEM_PROMPT = `You are Lia's Memory Consolidation job.
+
+Inputs:
+- Current MEMORY.md
+- Current USER.md
+- Current SOUL.md
+- Current TOOLS.md
+
+Task:
+- Decide whether cleanup is needed
+- Merge repeated observations
+- Replace outdated long-term entries
+- Keep long-term memory concise and stable
+
+Rules:
+- Most runs should be NO_WRITE
+- At most 5 changes per run
+- Prefer replacing noisy detail with cleaner abstraction
+- Do NOT invent new facts
+- SOUL.md updates should be low-frequency
+- IDENTITY.md is out of scope
+- TOOLS.md cleanup should stay narrow: merge duplicate mappings, remove stale aliases, and keep local tool notes compact
+- Do not infer runtime tool availability from TOOLS.md
+
+Output JSON only:
+{
+  "decision": "NO_WRITE|WRITE_CLEANUP",
+  "proposed_updates": {
+    "MEMORY.md": [
+      {
+        "section": "target section",
+        "action": "add|replace|remove",
+        "content": "new markdown content"
+      }
+    ],
+    "USER.md": [
+      {
+        "section": "target section",
+        "action": "add|replace|remove",
+        "content": "new markdown content"
+      }
+    ],
+    "SOUL.md": [
+      {
+        "section": "target section",
+        "action": "add|replace|remove",
+        "content": "new markdown content"
+      }
+    ],
+    "TOOLS.md": [
+      {
+        "section": "target section",
+        "action": "add|replace|remove",
+        "content": "new markdown content"
+      }
+    ]
+  }
+}`;

package/src/consolidation/scheduler.ts

@@ -0,0 +1,153 @@
+import type { LLMService, Logger } from "../types.js";
+import { Consolidator } from "./consolidator.js";
+import type { ConsolidationConfig } from "./types.js";
+
+const DAY_IN_MS = 24 * 60 * 60 * 1000;
+
+interface DailySchedule {
+  minute: number;
+  hour: number;
+}
+
+function getErrorMessage(error: unknown): string {
+  if (error instanceof Error) {
+    return error.message;
+  }
+
+  return String(error);
+}
+
+function parseNumber(value: string): number | null {
+  if (!/^\d+$/.test(value)) {
+    return null;
+  }
+
+  const parsed = Number(value);
+  return Number.isInteger(parsed) ? parsed : null;
+}
+
+function parseDailySchedule(schedule: string): DailySchedule {
+  const parts = schedule.trim().split(/\s+/);
+
+  if (parts.length !== 5) {
+    throw new Error(`Invalid schedule format: "${schedule}"`);
+  }
+
+  const [minutePart, hourPart, dayOfMonthPart, monthPart, dayOfWeekPart] = parts;
+
+  if (dayOfMonthPart !== "*" || monthPart !== "*" || dayOfWeekPart !== "*") {
+    throw new Error(`Only daily schedule is supported: "${schedule}"`);
+  }
+
+  const minute = parseNumber(minutePart);
+  const hour = parseNumber(hourPart);
+
+  if (minute === null || minute < 0 || minute > 59) {
+    throw new Error(`Invalid minute in schedule: "${schedule}"`);
+  }
+
+  if (hour === null || hour < 0 || hour > 23) {
+    throw new Error(`Invalid hour in schedule: "${schedule}"`);
+  }
+
+  return { minute, hour };
+}
+
+function getNextRunTime(schedule: DailySchedule, now: Date = new Date()): Date {
+  const next = new Date(now);
+  next.setSeconds(0, 0);
+  next.setHours(schedule.hour, schedule.minute, 0, 0);
+
+  if (next <= now) {
+    next.setDate(next.getDate() + 1);
+  }
+
+  return next;
+}
+
+export class ConsolidationScheduler {
+  private config: ConsolidationConfig;
+  private logger: Logger;
+  private consolidator: Consolidator;
+  private timeoutId: ReturnType<typeof setTimeout> | null;
+  private intervalId: ReturnType<typeof setInterval> | null;
+
+  constructor(config: ConsolidationConfig, logger: Logger, llmService: LLMService) {
+    this.config = config;
+    this.logger = logger;
+    this.consolidator = new Consolidator(config, logger, llmService);
+    this.timeoutId = null;
+    this.intervalId = null;
+  }
+
+  start(): void {
+    if (this.timeoutId !== null || this.intervalId !== null) {
+      this.logger.warn("ConsolidationScheduler", "Scheduler is already running", {
+        schedule: this.config.schedule,
+      });
+      return;
+    }
+
+    try {
+      const parsedSchedule = parseDailySchedule(this.config.schedule);
+      const nextRunAt = getNextRunTime(parsedSchedule);
+      const delayMs = Math.max(nextRunAt.getTime() - Date.now(), 0);
+
+      this.logger.info("ConsolidationScheduler", "Scheduler started", {
+        schedule: this.config.schedule,
+        nextRunAt: nextRunAt.toISOString(),
+        delayMs,
+      });
+
+      this.timeoutId = setTimeout(() => {
+        void this.runConsolidation();
+
+        this.intervalId = setInterval(() => {
+          void this.runConsolidation();
+        }, DAY_IN_MS);
+
+        this.timeoutId = null;
+      }, delayMs);
+    } catch (error) {
+      this.logger.error("ConsolidationScheduler", "Failed to start scheduler", {
+        schedule: this.config.schedule,
+        reason: getErrorMessage(error),
+      });
+    }
+  }
+
+  stop(): void {
+    if (this.timeoutId !== null) {
+      clearTimeout(this.timeoutId);
+      this.timeoutId = null;
+    }
+
+    if (this.intervalId !== null) {
+      clearInterval(this.intervalId);
+      this.intervalId = null;
+    }
+
+    this.logger.info("ConsolidationScheduler", "Scheduler stopped", {
+      schedule: this.config.schedule,
+    });
+  }
+
+  private async runConsolidation(): Promise<void> {
+    this.logger.info("ConsolidationScheduler", "Starting scheduled consolidation run", {
+      schedule: this.config.schedule,
+    });
+
+    try {
+      const result = await this.consolidator.consolidate();
+      this.logger.info("ConsolidationScheduler", "Scheduled consolidation run completed", {
+        decision: Object.keys(result.updates).length === 0 ? "NO_WRITE" : "WRITE_CLEANUP",
+        updatedFiles: Object.keys(result.updates),
+      });
+    } catch (error) {
+      const reason = getErrorMessage(error);
+      this.logger.error("ConsolidationScheduler", "Scheduled consolidation run failed", {
+        reason,
+      });
+    }
+  }
+}

package/src/consolidation/types.ts

@@ -0,0 +1,25 @@
+export interface ConsolidationConfig {
+  workspaceDir: string;
+  schedule: string;
+}
+
+export type ConsolidatedFilename =
+  | "MEMORY.md"
+  | "USER.md"
+  | "SOUL.md"
+  | "TOOLS.md";
+
+export interface ConsolidationPatch {
+  section: string;
+  action: "add" | "replace" | "remove";
+  content: string;
+}
+
+export interface ConsolidationProposal {
+  decision: "NO_WRITE" | "WRITE_CLEANUP";
+  proposedUpdates: Partial<Record<ConsolidatedFilename, ConsolidationPatch[]>>;
+}
+
+export interface ConsolidationResult {
+  updates: Partial<Record<ConsolidatedFilename, string>>;
+}

package/src/evals/cli.ts

@@ -0,0 +1,45 @@
+export type EvalSuite = "all" | "memory-gate" | "writer-guardian";
+
+export interface EvalCliOptions {
+  suite: EvalSuite;
+  useJudge: boolean;
+  datasetRoot?: string;
+  sharedDatasetPath?: string;
+  memoryGateDatasetPath?: string;
+  writerGuardianDatasetPath?: string;
+}
+
+function getArgValue(argv: string[], flag: string): string | undefined {
+  const index = argv.indexOf(flag);
+  if (index === -1 || index + 1 >= argv.length) {
+    return undefined;
+  }
+
+  return argv[index + 1];
+}
+
+function parseSuite(value: string | undefined): EvalSuite {
+  const suite = value ?? "all";
+  if (
+    suite === "all" ||
+    suite === "memory-gate" ||
+    suite === "writer-guardian"
+  ) {
+    return suite;
+  }
+
+  throw new Error(
+    `Unsupported suite: ${suite}. Expected one of: all, memory-gate, writer-guardian`
+  );
+}
+
+export function parseEvalCliOptions(argv: string[]): EvalCliOptions {
+  return {
+    suite: parseSuite(getArgValue(argv, "--suite")),
+    useJudge: !argv.includes("--no-judge"),
+    datasetRoot: getArgValue(argv, "--dataset-root"),
+    sharedDatasetPath: getArgValue(argv, "--shared-dataset"),
+    memoryGateDatasetPath: getArgValue(argv, "--memory-gate-dataset"),
+    writerGuardianDatasetPath: getArgValue(argv, "--writer-guardian-dataset"),
+  };
+}

package/src/evals/datasets.ts

@@ -0,0 +1,39 @@
+import path from "node:path";
+
+export interface ResolveEvalDatasetPathsInput {
+  rootDir: string;
+  datasetRoot?: string;
+  sharedDatasetPath?: string;
+  memoryGateDatasetPath?: string;
+  writerGuardianDatasetPath?: string;
+}
+
+export interface EvalDatasetPaths {
+  sharedDatasetPath: string;
+  memoryGateDatasetPath: string;
+  writerGuardianDatasetPath: string;
+}
+
+function resolvePath(rootDir: string, targetPath: string): string {
+  return path.isAbsolute(targetPath) ? targetPath : path.join(rootDir, targetPath);
+}
+
+export function resolveEvalDatasetPaths(
+  input: ResolveEvalDatasetPathsInput
+): EvalDatasetPaths {
+  const datasetRoot = input.datasetRoot
+    ? resolvePath(input.rootDir, input.datasetRoot)
+    : path.join(input.rootDir, "evals/datasets");
+
+  return {
+    sharedDatasetPath: input.sharedDatasetPath
+      ? resolvePath(input.rootDir, input.sharedDatasetPath)
+      : path.join(datasetRoot, "shared/scenarios.jsonl"),
+    memoryGateDatasetPath: input.memoryGateDatasetPath
+      ? resolvePath(input.rootDir, input.memoryGateDatasetPath)
+      : path.join(datasetRoot, "memory-gate/benchmark.jsonl"),
+    writerGuardianDatasetPath: input.writerGuardianDatasetPath
+      ? resolvePath(input.rootDir, input.writerGuardianDatasetPath)
+      : path.join(datasetRoot, "writer-guardian/benchmark.jsonl"),
+  };
+}