@xfxstudio/claworld 2026.4.22-testing.5 → 2026.4.22-testing.7

package/src/openclaw/runtime/working-memory.js

@@ -0,0 +1,1086 @@
+import fs from 'fs/promises';
+import os from 'os';
+import path from 'path';
+import { resolveOpenClawWorkspaceRoot } from './workspace-resolver.js';
+
+export const CLAWORLD_WORKING_MEMORY_DIR = '.claworld';
+export const CLAWORLD_CONTEXT_DIR = 'context';
+export const CLAWORLD_JOURNAL_DIR = 'journal';
+export const CLAWORLD_REPORTS_DIR = 'reports';
+
+export const CLAWORLD_WORKING_MEMORY_FILES = Object.freeze({
+  index: 'INDEX.md',
+  now: 'context/NOW.md',
+  profile: 'context/PROFILE.md',
+  memory: 'context/MEMORY.md',
+});
+
+export const CLAWORLD_WORKING_MEMORY_DIRECTORIES = Object.freeze([
+  CLAWORLD_WORKING_MEMORY_DIR,
+  `${CLAWORLD_WORKING_MEMORY_DIR}/${CLAWORLD_CONTEXT_DIR}`,
+  `${CLAWORLD_WORKING_MEMORY_DIR}/${CLAWORLD_JOURNAL_DIR}`,
+  `${CLAWORLD_WORKING_MEMORY_DIR}/${CLAWORLD_REPORTS_DIR}`,
+]);
+
+export const CLAWORLD_BOOTSTRAP_TARGETS = Object.freeze({
+  MAIN: 'main',
+  MANAGEMENT: 'management',
+  CLAWORLD_CONVERSATION: 'claworld_conversation',
+  NONE: 'none',
+});
+
+export const CLAWORLD_MAINTENANCE_RUN_TYPES = Object.freeze({
+  L1_NOW_REFRESH: 'L1_NOW_REFRESH',
+  L2_MEMORY_PROFILE_REVIEW: 'L2_MEMORY_PROFILE_REVIEW',
+});
+
+const MAINTENANCE_RUN_TYPE_VALUES = new Set(Object.values(CLAWORLD_MAINTENANCE_RUN_TYPES));
+
+const L1_ALLOWED_TARGETS = new Set([
+  CLAWORLD_WORKING_MEMORY_FILES.now,
+]);
+
+const L2_ALLOWED_TARGETS = new Set([
+  CLAWORLD_WORKING_MEMORY_FILES.now,
+  CLAWORLD_WORKING_MEMORY_FILES.profile,
+  CLAWORLD_WORKING_MEMORY_FILES.memory,
+]);
+
+const MAX_EVENT_EXCERPT_CHARS = 600;
+const MAX_MEMORY_SLICE_CHARS = 4000;
+const MAX_BOOTSTRAP_FILE_CHARS = 2200;
+const MAX_BOOTSTRAP_TOTAL_CHARS = 6000;
+
+const MAIN_BOOTSTRAP_FILES = Object.freeze([
+  CLAWORLD_WORKING_MEMORY_FILES.memory,
+]);
+
+const MANAGEMENT_BOOTSTRAP_FILES = Object.freeze([
+  CLAWORLD_WORKING_MEMORY_FILES.profile,
+  CLAWORLD_WORKING_MEMORY_FILES.memory,
+  CLAWORLD_WORKING_MEMORY_FILES.now,
+]);
+
+const CONVERSATION_BOOTSTRAP_FILES = Object.freeze([
+  CLAWORLD_WORKING_MEMORY_FILES.now,
+  CLAWORLD_WORKING_MEMORY_FILES.memory,
+  CLAWORLD_WORKING_MEMORY_FILES.profile,
+]);
+
+export function buildClaworldContextPointer() {
+  return [
+    '# Claworld Context Pointer',
+    '',
+    'Claworld working memory is available at `.claworld/INDEX.md`.',
+    'When the user asks about detailed Claworld history, worlds, A2A conversations, people met in Claworld, activity opportunities, or previous Claworld progress, read `.claworld/INDEX.md` first.',
+    'Do not load raw Claworld transcripts by default.',
+    'Do not treat open Claworld loops as ordinary main-session todos before checking `.claworld/INDEX.md`.',
+  ].join('\n');
+}
+
+function normalizeBootstrapTotalChars(rawValue, fallback) {
+  return Number.isInteger(rawValue) && rawValue >= 0
+    ? rawValue
+    : fallback;
+}
+
+function truncateBootstrapText(text, maxChars, note = '\n\n_(Truncated to fit the total Claworld bootstrap budget.)_') {
+  const normalizedText = String(text || '');
+  if (normalizedText.length <= maxChars) {
+    return {
+      text: normalizedText,
+      truncated: false,
+    };
+  }
+  if (maxChars <= 0) {
+    return {
+      text: '',
+      truncated: normalizedText.length > 0,
+    };
+  }
+  if (note.length >= maxChars) {
+    return {
+      text: normalizedText.slice(0, maxChars),
+      truncated: true,
+    };
+  }
+  const excerpt = normalizedText.slice(0, maxChars - note.length).trimEnd();
+  if (!excerpt) {
+    return {
+      text: normalizedText.slice(0, maxChars),
+      truncated: true,
+    };
+  }
+  return {
+    text: `${excerpt}${note}`,
+    truncated: true,
+  };
+}
+
+function measureBootstrapParts(parts) {
+  return parts.filter(Boolean).join('\n\n').length;
+}
+
+export function buildClaworldWorkingMemoryTemplates() {
+  return {
+    [CLAWORLD_WORKING_MEMORY_FILES.index]: [
+      '# Claworld Working Memory',
+      '',
+      'This directory is the workspace-local private working memory for Claworld.',
+      'Read this file first when the user asks about Claworld, worlds, A2A conversations, people met in Claworld, activity opportunities, or previous Claworld progress.',
+      '',
+      '## Read Order',
+      '- `context/NOW.md` for current Claworld focus, active worlds, and recent progress.',
+      '- `context/MEMORY.md` for durable Claworld facts and decisions.',
+      '- `context/PROFILE.md` for user preferences and profile hints relevant to Claworld.',
+      '- `journal/YYYY-MM.md` for append-only summarized events.',
+      '- `reports/` for generated local progress reports.',
+      '',
+      '## Rules',
+      '- Do not load raw Claworld transcripts by default.',
+      '- Do not write this content into global `MEMORY.md` automatically.',
+      '- Prefer short summaries and references over raw chat history.',
+      '- `context/PROFILE.md` and `context/MEMORY.md` are updated only by L2 maintenance review.',
+      '',
+    ].join('\n'),
+    [CLAWORLD_WORKING_MEMORY_FILES.now]: [
+      '# Claworld Now',
+      '',
+      '## Current Focus',
+      '- No active Claworld focus recorded yet.',
+      '',
+      '## Recent Activity',
+      '- No recent Claworld activity recorded yet.',
+      '',
+      '## Open Questions',
+      '- none',
+      '',
+    ].join('\n'),
+    [CLAWORLD_WORKING_MEMORY_FILES.profile]: [
+      '# Claworld Profile',
+      '',
+      '## Stable Preferences',
+      '- No Claworld-specific preferences recorded yet.',
+      '',
+      '## People And Context',
+      '- No Claworld people context recorded yet.',
+      '',
+    ].join('\n'),
+    [CLAWORLD_WORKING_MEMORY_FILES.memory]: [
+      '# Claworld Memory',
+      '',
+      '## Durable Facts',
+      '- No durable Claworld facts recorded yet.',
+      '',
+      '## Decisions',
+      '- No durable Claworld decisions recorded yet.',
+      '',
+    ].join('\n'),
+  };
+}
+
+export function buildClaworldWorkingMemoryFileSpecs() {
+  const templates = buildClaworldWorkingMemoryTemplates();
+  return Object.entries(templates).map(([relativePath, content]) => ({
+    relativePath: `${CLAWORLD_WORKING_MEMORY_DIR}/${relativePath}`,
+    workingMemoryRelativePath: relativePath,
+    policy: 'durable',
+    content,
+  }));
+}
+
+function normalizeText(value, fallback = null) {
+  if (value == null) return fallback;
+  const normalized = String(value).trim();
+  return normalized || fallback;
+}
+
+function isPlainObject(value) {
+  return value && typeof value === 'object' && !Array.isArray(value);
+}
+
+function normalizeSessionType(value) {
+  const normalized = normalizeText(value, null);
+  return normalized ? normalized.toLowerCase().replace(/[\s-]+/g, '_') : null;
+}
+
+function expandUserPath(inputPath, homeDir = os.homedir()) {
+  const text = normalizeText(inputPath, null);
+  if (!text) return null;
+  if (text === '~') return homeDir;
+  if (text.startsWith('~/') || text.startsWith('~\\')) {
+    return path.join(homeDir, text.slice(2));
+  }
+  return text;
+}
+
+export function resolveClaworldWorkspaceRoot(options = {}, homeDir = os.homedir()) {
+  const source = typeof options === 'string'
+    ? options
+    : options?.workspaceRoot
+      ?? options?.workspacePath
+      ?? options?.workspaceDir
+      ?? options?.workspace
+      ?? options?.cwd
+      ?? process.cwd();
+  return path.resolve(expandUserPath(source, homeDir) || process.cwd());
+}
+
+export function resolveClaworldMemoryRoot(options = {}, homeDir = os.homedir()) {
+  return path.join(resolveClaworldWorkspaceRoot(options, homeDir), CLAWORLD_WORKING_MEMORY_DIR);
+}
+
+function collectBootstrapRecords(source, records) {
+  if (!isPlainObject(source)) return;
+  records.push(source);
+  for (const key of ['session', 'context', 'metadata', 'runtimeContext', 'delivery']) {
+    if (isPlainObject(source[key])) {
+      records.push(source[key]);
+    }
+  }
+}
+
+function firstBootstrapField(records, keys) {
+  for (const record of records) {
+    for (const key of keys) {
+      const value = normalizeText(record[key], null);
+      if (value) return value;
+    }
+  }
+  return null;
+}
+
+function buildBootstrapFileLabel(relativePath) {
+  return `${CLAWORLD_WORKING_MEMORY_DIR}/${relativePath}`;
+}
+
+function buildBootstrapSection(displayPath, content, note = null) {
+  return [
+    `## \`${displayPath}\``,
+    String(content || '').trimEnd(),
+    note ? `_${note}_` : null,
+  ].filter((line) => line != null && line !== '').join('\n');
+}
+
+function isMainBootstrapContext({ sessionKey = null, sessionType = null } = {}) {
+  const normalizedSessionType = normalizeSessionType(sessionType);
+  if (normalizedSessionType === 'main' || normalizedSessionType === 'main_session') {
+    return true;
+  }
+  return /^agent:[^:]+:main(?:$|:)/i.test(normalizeText(sessionKey, ''));
+}
+
+function isManagementBootstrapContext({ sessionKey = null, sessionType = null } = {}) {
+  const normalizedSessionType = normalizeSessionType(sessionType);
+  if (normalizedSessionType === 'management' || normalizedSessionType === 'management_session') {
+    return true;
+  }
+  return /^management:[^:]+/i.test(normalizeText(sessionKey, ''));
+}
+
+function isClaworldConversationBootstrapContext({
+  channel = null,
+  sessionKey = null,
+  sessionType = null,
+} = {}) {
+  const normalizedChannel = normalizeText(channel, null)?.toLowerCase() || null;
+  const normalizedSessionType = normalizeSessionType(sessionType);
+  const normalizedSessionKey = normalizeText(sessionKey, null);
+  const hasClaworldChannel = normalizedChannel === 'claworld'
+    || /:claworld:/i.test(normalizedSessionKey || '');
+  if (!hasClaworldChannel) return false;
+  if (
+    normalizedSessionType === 'conversation'
+    || normalizedSessionType === 'conversation_session'
+    || normalizedSessionType === 'chat'
+    || normalizedSessionType === 'direct'
+    || normalizedSessionType === 'world'
+  ) {
+    return true;
+  }
+  return (
+    /^agent:[^:]+:claworld:(direct|world):/i.test(normalizedSessionKey || '')
+    || /^conversation:.*:(direct|world)(:|$)/i.test(normalizedSessionKey || '')
+  );
+}
+
+function bootstrapFilesForTarget(target) {
+  if (target === CLAWORLD_BOOTSTRAP_TARGETS.MAIN) {
+    return MAIN_BOOTSTRAP_FILES;
+  }
+  if (target === CLAWORLD_BOOTSTRAP_TARGETS.MANAGEMENT) {
+    return MANAGEMENT_BOOTSTRAP_FILES;
+  }
+  if (target === CLAWORLD_BOOTSTRAP_TARGETS.CLAWORLD_CONVERSATION) {
+    return CONVERSATION_BOOTSTRAP_FILES;
+  }
+  return [];
+}
+
+function buildClaworldBootstrapFileSections(selectedFiles, slices = {}, options = {}) {
+  const maxTotalChars = normalizeBootstrapTotalChars(options.maxTotalChars, MAX_BOOTSTRAP_TOTAL_CHARS);
+  const summaryPrefix = '## Claworld Bootstrap Budget\nOmitted to fit the prompt budget: ';
+  const summarySuffix = '.';
+  const buildBudgetSummary = (files) => `${summaryPrefix}${files.map((filePath) => `\`${filePath}\``).join(', ')}${summarySuffix}`;
+  const sections = [];
+  const fallbackFiles = [];
+  const omittedFiles = [];
+  let totalChars = 0;
+  let truncated = false;
+
+  for (let index = 0; index < selectedFiles.length; index += 1) {
+    const relativePath = selectedFiles[index];
+    const displayPath = buildBootstrapFileLabel(relativePath);
+    const slice = slices[relativePath] || null;
+    const content = slice?.content || `No local content was available for \`${displayPath}\` at startup. Continue without this file.`;
+    if (slice == null) {
+      fallbackFiles.push(displayPath);
+    }
+    if (slice?.truncated) {
+      truncated = true;
+    }
+    const note = slice?.truncated
+      ? 'Truncated to the per-file Claworld bootstrap budget.'
+      : slice == null
+        ? 'Missing-file fallback.'
+        : null;
+    const section = buildBootstrapSection(displayPath, content, note);
+    const joinCost = sections.length > 0 ? 2 : 0;
+    if (totalChars + joinCost + section.length <= maxTotalChars) {
+      sections.push(section);
+      totalChars += joinCost + section.length;
+      continue;
+    }
+
+    truncated = true;
+    const remainingLabels = selectedFiles
+      .slice(index + 1)
+      .map((filePath) => buildBootstrapFileLabel(filePath));
+    const possibleSummary = remainingLabels.length > 0 ? buildBudgetSummary(remainingLabels) : '';
+    const summaryReserve = possibleSummary
+      ? (sections.length > 0 ? 2 : 0) + possibleSummary.length
+      : 0;
+    const remainingChars = maxTotalChars - totalChars - joinCost;
+    const header = `## \`${displayPath}\`\n`;
+    const suffix = '\n_(Truncated to fit the total Claworld bootstrap budget.)_';
+    const availableChars = Math.max(
+      0,
+      remainingChars - summaryReserve - header.length - suffix.length,
+    );
+    if (availableChars > 0) {
+      const excerpt = String(content).slice(0, availableChars).trimEnd();
+      if (excerpt) {
+        const truncatedSection = `${header}${excerpt}${suffix}`;
+        sections.push(truncatedSection);
+        totalChars += joinCost + truncatedSection.length;
+      } else {
+        omittedFiles.push(displayPath);
+      }
+    } else {
+      omittedFiles.push(displayPath);
+    }
+    omittedFiles.push(...remainingLabels);
+    break;
+  }
+
+  if (omittedFiles.length > 0) {
+    const summary = buildBudgetSummary(omittedFiles);
+    const joinCost = sections.length > 0 ? 2 : 0;
+    if (totalChars + joinCost + summary.length <= maxTotalChars) {
+      sections.push(summary);
+      totalChars += joinCost + summary.length;
+    }
+  }
+
+  return {
+    text: sections.join('\n\n'),
+    fallbackFiles,
+    omittedFiles,
+    truncated,
+  };
+}
+
+export function resolveClaworldBootstrapContext(...sources) {
+  const records = [];
+  const flattenedSources = sources.flat ? sources.flat() : sources;
+  for (const source of flattenedSources) {
+    collectBootstrapRecords(source, records);
+  }
+  return {
+    channel: firstBootstrapField(records, ['channel', 'channelId']),
+    sessionKey: firstBootstrapField(records, ['sessionKey', 'localSessionKey']),
+    sessionType: firstBootstrapField(records, ['sessionType', 'sessionKind', 'sessionMode', 'mode']),
+  };
+}
+
+export function resolveClaworldBootstrapTarget(context = {}) {
+  const normalizedContext = resolveClaworldBootstrapContext(context);
+  if (isMainBootstrapContext(normalizedContext)) {
+    return CLAWORLD_BOOTSTRAP_TARGETS.MAIN;
+  }
+  if (isManagementBootstrapContext(normalizedContext)) {
+    return CLAWORLD_BOOTSTRAP_TARGETS.MANAGEMENT;
+  }
+  if (isClaworldConversationBootstrapContext(normalizedContext)) {
+    return CLAWORLD_BOOTSTRAP_TARGETS.CLAWORLD_CONVERSATION;
+  }
+  return CLAWORLD_BOOTSTRAP_TARGETS.NONE;
+}
+
+async function readTextIfPresent(filePath) {
+  try {
+    return await fs.readFile(filePath, 'utf8');
+  } catch (error) {
+    if (error && error.code === 'ENOENT') return null;
+    throw error;
+  }
+}
+
+async function atomicWriteText(filePath, content, {
+  backup = true,
+  rejectEmptyOverwrite = true,
+} = {}) {
+  const nextContent = String(content ?? '');
+  const currentContent = await readTextIfPresent(filePath);
+  if (
+    rejectEmptyOverwrite
+    && currentContent != null
+    && normalizeText(currentContent, null)
+    && !normalizeText(nextContent, null)
+  ) {
+    throw new Error(`Refusing to overwrite non-empty Claworld memory file with empty content: ${filePath}`);
+  }
+
+  await fs.mkdir(path.dirname(filePath), { recursive: true });
+  if (backup && currentContent != null && currentContent !== nextContent) {
+    await fs.writeFile(`${filePath}.bak`, currentContent, 'utf8');
+  }
+
+  const tempPath = path.join(
+    path.dirname(filePath),
+    `.${path.basename(filePath)}.${process.pid}.${Date.now()}.tmp`,
+  );
+  await fs.writeFile(tempPath, nextContent, 'utf8');
+  await fs.rename(tempPath, filePath);
+}
+
+export async function ensureClaworldWorkingMemory(options = {}, ensureOptions = {}) {
+  const workspaceRoot = resolveClaworldWorkspaceRoot(options, ensureOptions.homeDir || os.homedir());
+  const memoryRoot = path.join(workspaceRoot, CLAWORLD_WORKING_MEMORY_DIR);
+  const directories = CLAWORLD_WORKING_MEMORY_DIRECTORIES.map((relativePath) => ({
+    relativePath,
+    absolutePath: path.join(workspaceRoot, relativePath),
+  }));
+  const files = buildClaworldWorkingMemoryFileSpecs().map((file) => ({
+    ...file,
+    absolutePath: path.join(workspaceRoot, file.relativePath),
+  }));
+  const actions = [];
+
+  if (ensureOptions.dryRun === true) {
+    for (const directory of directories) {
+      actions.push(`mkdir -p ${directory.absolutePath}`);
+    }
+    for (const file of files) {
+      actions.push(`seed ${file.absolutePath} if missing`);
+    }
+    return {
+      ok: true,
+      dryRun: true,
+      workspaceRoot,
+      memoryRoot,
+      directories,
+      files,
+      actions,
+    };
+  }
+
+  for (const directory of directories) {
+    await fs.mkdir(directory.absolutePath, { recursive: true });
+    actions.push(`ensured ${directory.absolutePath}`);
+  }
+
+  for (const file of files) {
+    const currentContent = await readTextIfPresent(file.absolutePath);
+    if (currentContent == null) {
+      await atomicWriteText(file.absolutePath, file.content, {
+        backup: false,
+        rejectEmptyOverwrite: false,
+      });
+      actions.push(`created ${file.absolutePath}`);
+    } else {
+      actions.push(`preserved ${file.absolutePath}`);
+    }
+  }
+
+  return {
+    ok: true,
+    dryRun: false,
+    workspaceRoot,
+    memoryRoot,
+    directories,
+    files,
+    actions,
+  };
+}
+
+function toIsoTimestamp(value = null) {
+  const date = value instanceof Date ? value : new Date(value || Date.now());
+  if (Number.isNaN(date.getTime())) return new Date().toISOString();
+  return date.toISOString();
+}
+
+function toMonthKey(timestamp) {
+  return toIsoTimestamp(timestamp).slice(0, 7);
+}
+
+function truncateText(value, maxChars = MAX_EVENT_EXCERPT_CHARS) {
+  const text = normalizeText(value, '');
+  if (text.length <= maxChars) return text;
+  return `${text.slice(0, Math.max(0, maxChars - 3))}...`;
+}
+
+function flattenInline(value) {
+  return truncateText(String(value ?? '').replace(/\s+/g, ' ').trim());
+}
+
+export function buildClaworldMaintenanceEvent(input = {}) {
+  const toolName = normalizeText(input.toolName, null);
+  const source = normalizeText(input.source, toolName ? 'claworld_tool' : 'claworld_runtime');
+  const kind = normalizeText(input.kind, toolName || 'milestone');
+  const timestamp = toIsoTimestamp(input.timestamp);
+  const summary = normalizeText(input.summary, toolName ? `${toolName} succeeded.` : 'Claworld milestone recorded.');
+  const refs = input.refs && typeof input.refs === 'object' && !Array.isArray(input.refs)
+    ? Object.fromEntries(
+      Object.entries(input.refs)
+        .map(([key, value]) => [key, normalizeText(value, null)])
+        .filter(([, value]) => value != null),
+    )
+    : {};
+  return {
+    id: normalizeText(input.id, `${source}:${kind}:${timestamp}`),
+    timestamp,
+    source,
+    kind,
+    summary,
+    excerpt: truncateText(input.excerpt || ''),
+    refs,
+  };
+}
+
+export function buildClaworldRuntimeMaintenanceEvent(input = {}) {
+  return buildClaworldMaintenanceEvent({
+    ...input,
+    source: normalizeText(input.source, 'claworld_runtime'),
+    kind: normalizeText(input.kind, 'milestone'),
+  });
+}
+
+function parseToolResultPayload(result) {
+  if (!result || typeof result !== 'object') return null;
+  if (result.payload && typeof result.payload === 'object' && !Array.isArray(result.payload)) {
+    return result.payload;
+  }
+  const textContent = Array.isArray(result.content)
+    ? result.content.find((entry) => entry?.type === 'text' && typeof entry.text === 'string')?.text
+    : null;
+  if (!textContent) return null;
+  try {
+    const parsed = JSON.parse(textContent);
+    return parsed && typeof parsed === 'object' && !Array.isArray(parsed) ? parsed : null;
+  } catch {
+    return null;
+  }
+}
+
+function compactResultPayload(payload = {}) {
+  const keys = [
+    'status',
+    'tool',
+    'accountId',
+    'worldId',
+    'displayName',
+    'chatRequestId',
+    'conversationKey',
+    'candidateId',
+    'feedbackId',
+    'nextAction',
+    'requiredAction',
+    'summary',
+    'message',
+  ];
+  const compact = {};
+  for (const key of keys) {
+    const value = normalizeText(payload[key], null);
+    if (value != null) compact[key] = value;
+  }
+  return compact;
+}
+
+export function buildClaworldToolMaintenanceEvent({
+  toolName,
+  params = {},
+  result = null,
+  timestamp = null,
+} = {}) {
+  const normalizedToolName = normalizeText(toolName, null);
+  if (!normalizedToolName || !normalizedToolName.startsWith('claworld_')) return null;
+  const payload = parseToolResultPayload(result) || {};
+  const compactPayload = compactResultPayload(payload);
+  const refs = {
+    accountId: params.accountId || payload.accountId,
+    worldId: params.worldId || payload.worldId,
+    chatRequestId: params.chatRequestId || payload.chatRequestId,
+    conversationKey: params.conversationKey || payload.conversationKey,
+    candidateId: params.candidateId || payload.candidateId,
+    agentCode: params.agentCode || payload.agentCode,
+  };
+  return buildClaworldMaintenanceEvent({
+    source: 'claworld_tool',
+    kind: normalizedToolName,
+    toolName: normalizedToolName,
+    timestamp,
+    refs,
+    summary: `${normalizedToolName} succeeded.`,
+    excerpt: Object.keys(compactPayload).length > 0
+      ? JSON.stringify(compactPayload)
+      : null,
+  });
+}
+
+function formatRefs(refs = {}) {
+  return Object.entries(refs)
+    .filter(([, value]) => value != null)
+    .map(([key, value]) => `${key}=${flattenInline(value)}`)
+    .join(', ');
+}
+
+export async function appendClaworldJournalEvent(options = {}, event = {}, appendOptions = {}) {
+  const workspaceRoot = resolveClaworldWorkspaceRoot(options, appendOptions.homeDir || os.homedir());
+  await ensureClaworldWorkingMemory(workspaceRoot, appendOptions);
+  const normalizedEvent = buildClaworldMaintenanceEvent(event);
+  const monthKey = toMonthKey(normalizedEvent.timestamp);
+  const journalPath = path.join(
+    workspaceRoot,
+    CLAWORLD_WORKING_MEMORY_DIR,
+    CLAWORLD_JOURNAL_DIR,
+    `${monthKey}.md`,
+  );
+  const currentContent = await readTextIfPresent(journalPath);
+  const refsLine = formatRefs(normalizedEvent.refs);
+  const entry = [
+    `## ${normalizedEvent.timestamp} - ${normalizedEvent.kind}`,
+    `- Source: ${normalizedEvent.source}`,
+    `- Summary: ${flattenInline(normalizedEvent.summary)}`,
+    normalizedEvent.excerpt ? `- Excerpt: ${flattenInline(normalizedEvent.excerpt)}` : null,
+    refsLine ? `- Refs: ${refsLine}` : null,
+    '',
+  ].filter((line) => line != null).join('\n');
+  if (currentContent == null) {
+    await atomicWriteText(journalPath, `# Claworld Journal ${monthKey}\n\n${entry}`, {
+      backup: false,
+      rejectEmptyOverwrite: false,
+    });
+  } else {
+    await fs.appendFile(journalPath, `${currentContent.endsWith('\n') ? '' : '\n'}${entry}`, 'utf8');
+  }
+  return {
+    ok: true,
+    journalPath,
+    event: normalizedEvent,
+  };
+}
+
+export async function readClaworldWorkingMemory(options = {}, readOptions = {}) {
+  const workspaceRoot = resolveClaworldWorkspaceRoot(options, readOptions.homeDir || os.homedir());
+  const maxCharsPerFile = Number.isInteger(readOptions.maxCharsPerFile) && readOptions.maxCharsPerFile > 0
+    ? readOptions.maxCharsPerFile
+    : MAX_MEMORY_SLICE_CHARS;
+  const slices = {};
+  for (const relativePath of Object.values(CLAWORLD_WORKING_MEMORY_FILES)) {
+    const absolutePath = path.join(workspaceRoot, CLAWORLD_WORKING_MEMORY_DIR, relativePath);
+    const content = await readTextIfPresent(absolutePath);
+    slices[relativePath] = content == null
+      ? null
+      : {
+        content: content.length > maxCharsPerFile ? content.slice(0, maxCharsPerFile) : content,
+        truncated: content.length > maxCharsPerFile,
+      };
+  }
+  return {
+    workspaceRoot,
+    memoryRoot: path.join(workspaceRoot, CLAWORLD_WORKING_MEMORY_DIR),
+    slices,
+  };
+}
+
+export async function buildClaworldBootstrapPromptContext(context = {}, options = {}) {
+  const normalizedContext = resolveClaworldBootstrapContext(context, options.context);
+  const target = resolveClaworldBootstrapTarget(normalizedContext);
+  const selectedFiles = bootstrapFilesForTarget(target);
+  const maxTotalChars = normalizeBootstrapTotalChars(options.maxTotalChars, MAX_BOOTSTRAP_TOTAL_CHARS);
+  const workspaceRoot = normalizeText(
+    options.workspaceRoot ?? context.workspaceRoot ?? context.workspaceDir ?? context.workspacePath ?? context.workspace,
+    null,
+  );
+  const resolvedWorkspaceRoot = workspaceRoot
+    ? resolveClaworldWorkspaceRoot(workspaceRoot, options.homeDir || os.homedir())
+    : null;
+  const workingMemory = target !== CLAWORLD_BOOTSTRAP_TARGETS.NONE && resolvedWorkspaceRoot
+    ? await readClaworldWorkingMemory(resolvedWorkspaceRoot, {
+      ...options,
+      maxCharsPerFile: options.maxCharsPerFile || MAX_BOOTSTRAP_FILE_CHARS,
+    })
+    : { slices: {} };
+  const pointerInjected = target === CLAWORLD_BOOTSTRAP_TARGETS.MAIN;
+  const parts = [];
+  let truncated = false;
+  if (pointerInjected) {
+    const pointerBudget = maxTotalChars - measureBootstrapParts(parts) - (parts.length > 0 ? 2 : 0);
+    const fittedPointer = truncateBootstrapText(buildClaworldContextPointer(), pointerBudget);
+    if (fittedPointer.text) {
+      parts.push(fittedPointer.text);
+    }
+    if (fittedPointer.truncated) {
+      truncated = true;
+    }
+  }
+  const sectionTitle = target === CLAWORLD_BOOTSTRAP_TARGETS.MAIN
+    ? '# Claworld Startup Memory'
+    : target === CLAWORLD_BOOTSTRAP_TARGETS.MANAGEMENT
+      ? '# Claworld Management Startup Memory'
+      : '# Claworld Conversation Startup Context';
+  const sectionPrefix = `${sectionTitle}\n\n`;
+  const remainingBudget = maxTotalChars - measureBootstrapParts(parts) - (parts.length > 0 ? 2 : 0);
+  const fileSections = buildClaworldBootstrapFileSections(selectedFiles, workingMemory.slices, {
+    ...options,
+    maxTotalChars: Math.max(0, remainingBudget - sectionPrefix.length),
+  });
+  if (fileSections.truncated) {
+    truncated = true;
+  }
+  if (fileSections.text) {
+    parts.push(`${sectionPrefix}${fileSections.text}`);
+  }
+  const appendSystemContext = parts.filter(Boolean).join('\n\n');
+  const finalContext = appendSystemContext.length > maxTotalChars
+    ? truncateBootstrapText(appendSystemContext, maxTotalChars)
+    : { text: appendSystemContext, truncated: false };
+  if (finalContext.truncated) {
+    truncated = true;
+  }
+  return {
+    target,
+    context: normalizedContext,
+    workspaceRoot: resolvedWorkspaceRoot,
+    files: selectedFiles.map((relativePath) => buildBootstrapFileLabel(relativePath)),
+    pointerInjected,
+    fallbackFiles: fileSections.fallbackFiles,
+    omittedFiles: fileSections.omittedFiles,
+    truncated,
+    appendSystemContext: finalContext.text,
+  };
+}
+
+function normalizePatchOperation(operation) {
+  const normalized = normalizeText(operation, 'replace');
+  if (normalized === 'replace' || normalized === 'append_section' || normalized === 'no_op') {
+    return normalized;
+  }
+  throw new Error(`Unsupported Claworld maintenance patch operation: ${normalized}`);
+}
+
+function normalizeMaintenanceRunType(runType) {
+  const normalized = normalizeText(runType, null);
+  if (MAINTENANCE_RUN_TYPE_VALUES.has(normalized)) return normalized;
+  throw new Error(`Unsupported Claworld maintenance run type: ${runType}`);
+}
+
+function stripClaworldPrefix(rawTarget) {
+  let target = String(rawTarget || '').replace(/\\/g, '/').trim();
+  target = target.replace(/^\/+/, '');
+  if (target.startsWith(`${CLAWORLD_WORKING_MEMORY_DIR}/`)) {
+    target = target.slice(CLAWORLD_WORKING_MEMORY_DIR.length + 1);
+  }
+  return target;
+}
+
+function normalizePatchTarget(rawTarget) {
+  const stripped = stripClaworldPrefix(rawTarget);
+  if (['NOW.md', 'PROFILE.md', 'MEMORY.md'].includes(stripped)) {
+    throw new Error(`Global ${stripped} is not a valid Claworld working-memory target; use context/${stripped}.`);
+  }
+  const normalized = path.posix.normalize(stripped);
+  if (!normalized || normalized === '.' || normalized.startsWith('../') || normalized === '..' || path.posix.isAbsolute(normalized)) {
+    throw new Error(`Invalid Claworld maintenance patch target: ${rawTarget}`);
+  }
+  return normalized;
+}
+
+function isAllowedTarget(runType, target) {
+  if (target.startsWith(`${CLAWORLD_JOURNAL_DIR}/`) || target.startsWith(`${CLAWORLD_REPORTS_DIR}/`)) {
+    return true;
+  }
+  if (runType === CLAWORLD_MAINTENANCE_RUN_TYPES.L1_NOW_REFRESH) {
+    return L1_ALLOWED_TARGETS.has(target);
+  }
+  if (runType === CLAWORLD_MAINTENANCE_RUN_TYPES.L2_MEMORY_PROFILE_REVIEW) {
+    return L2_ALLOWED_TARGETS.has(target);
+  }
+  return false;
+}
+
+function assertAllowedTarget(runType, target) {
+  if (!isAllowedTarget(runType, target)) {
+    throw new Error(`Claworld maintenance run ${runType} cannot write target ${target}`);
+  }
+}
+
+function normalizeReportPatch(report, index) {
+  const filename = normalizeText(report?.filename ?? report?.name, `report-${index + 1}.md`);
+  const normalizedFilename = path.posix.basename(filename.endsWith('.md') ? filename : `${filename}.md`);
+  return {
+    operation: 'replace',
+    target: `${CLAWORLD_REPORTS_DIR}/${normalizedFilename}`,
+    content: String(report?.md ?? report?.content ?? report?.text ?? ''),
+  };
+}
+
+function hasOwn(value, key) {
+  return Object.prototype.hasOwnProperty.call(value, key);
+}
+
+function readPatchContent(patch, fieldName) {
+  if (hasOwn(patch, 'content')) return patch.content;
+  if (hasOwn(patch, 'md')) return patch.md;
+  if (hasOwn(patch, 'text')) return patch.text;
+  throw new Error(`Claworld maintenance FilePatch ${fieldName} requires content for replace or append_section.`);
+}
+
+function normalizeFilePatchValue(value, target, fieldName) {
+  if (value && typeof value === 'object' && !Array.isArray(value)) {
+    const operation = normalizePatchOperation(value.operation);
+    const normalized = {
+      operation,
+      target,
+      content: operation === 'no_op' ? '' : String(readPatchContent(value, fieldName) ?? ''),
+    };
+    const rationale = normalizeText(value.rationale, null);
+    if (rationale) normalized.rationale = rationale;
+    return normalized;
+  }
+  return {
+    operation: 'replace',
+    target,
+    content: String(value ?? ''),
+  };
+}
+
+export function normalizeClaworldMaintenanceOutput(runType, output = {}, options = {}) {
+  if (!output || typeof output !== 'object' || Array.isArray(output)) {
+    throw new Error('Claworld maintenance output must be an object.');
+  }
+  const normalizedRunType = normalizeMaintenanceRunType(runType);
+  const patches = [];
+  if (Object.prototype.hasOwnProperty.call(output, 'nowMd')) {
+    patches.push(normalizeFilePatchValue(output.nowMd, CLAWORLD_WORKING_MEMORY_FILES.now, 'nowMd'));
+  }
+  if (Object.prototype.hasOwnProperty.call(output, 'profileMd')) {
+    patches.push(normalizeFilePatchValue(output.profileMd, CLAWORLD_WORKING_MEMORY_FILES.profile, 'profileMd'));
+  }
+  if (Object.prototype.hasOwnProperty.call(output, 'memoryMd')) {
+    patches.push(normalizeFilePatchValue(output.memoryMd, CLAWORLD_WORKING_MEMORY_FILES.memory, 'memoryMd'));
+  }
+  if (Object.prototype.hasOwnProperty.call(output, 'journalAppendMd')) {
+    const monthKey = toMonthKey(options.timestamp || output.timestamp || Date.now());
+    patches.push({
+      operation: 'append_section',
+      target: `${CLAWORLD_JOURNAL_DIR}/${monthKey}.md`,
+      content: String(output.journalAppendMd ?? ''),
+    });
+  }
+  if (Array.isArray(output.reports)) {
+    output.reports.forEach((report, index) => {
+      patches.push(normalizeReportPatch(report, index));
+    });
+  }
+  if (Array.isArray(output.patches)) {
+    for (const patch of output.patches) {
+      if (!patch || typeof patch !== 'object' || Array.isArray(patch)) {
+        throw new Error('Claworld maintenance patches entries must be FilePatch objects.');
+      }
+      const operation = normalizePatchOperation(patch.operation);
+      patches.push({
+        operation,
+        target: normalizePatchTarget(patch.target ?? patch.path ?? patch.relativePath),
+        content: operation === 'no_op' ? '' : String(readPatchContent(patch, 'patches[]') ?? ''),
+        rationale: normalizeText(patch.rationale, null),
+      });
+    }
+  }
+
+  const normalizedPatches = patches.map((patch) => {
+    const target = normalizePatchTarget(patch.target);
+    const operation = normalizePatchOperation(patch.operation);
+    assertAllowedTarget(normalizedRunType, target);
+    const normalizedPatch = {
+      operation,
+      target,
+      content: String(patch.content ?? ''),
+    };
+    const rationale = normalizeText(patch.rationale, null);
+    if (rationale) normalizedPatch.rationale = rationale;
+    return normalizedPatch;
+  });
+
+  return {
+    runType: normalizedRunType,
+    noOpReason: normalizeText(output.noOpReason, null),
+    patches: normalizedPatches,
+  };
+}
+
+export function validateClaworldMaintenanceOutput(runType, output = {}, options = {}) {
+  return normalizeClaworldMaintenanceOutput(runType, output, options);
+}
+
+async function applyMaintenancePatch(workspaceRoot, patch) {
+  if (patch.operation === 'no_op') {
+    return {
+      operation: patch.operation,
+      target: patch.target,
+      applied: false,
+    };
+  }
+  const absolutePath = path.join(workspaceRoot, CLAWORLD_WORKING_MEMORY_DIR, patch.target);
+  if (patch.operation === 'append_section') {
+    await fs.mkdir(path.dirname(absolutePath), { recursive: true });
+    const currentContent = await readTextIfPresent(absolutePath);
+    if (currentContent == null) {
+      const monthKey = path.basename(patch.target, '.md');
+      await atomicWriteText(absolutePath, `# Claworld Journal ${monthKey}\n\n${patch.content}`, {
+        backup: false,
+        rejectEmptyOverwrite: false,
+      });
+    } else {
+      await fs.appendFile(
+        absolutePath,
+        `${currentContent.endsWith('\n') ? '' : '\n'}${patch.content}`,
+        'utf8',
+      );
+    }
+    return {
+      operation: patch.operation,
+      target: patch.target,
+      applied: true,
+    };
+  }
+
+  await atomicWriteText(absolutePath, patch.content, {
+    backup: true,
+    rejectEmptyOverwrite: true,
+  });
+  return {
+    operation: patch.operation,
+    target: patch.target,
+    applied: true,
+  };
+}
+
+export async function runClaworldMemoryMaintenance(runType, requestBundle = {}, options = {}) {
+  const normalizedRunType = normalizeMaintenanceRunType(runType);
+  const workspaceRoot = resolveClaworldWorkspaceRoot(
+    options.workspaceRoot || requestBundle.workspaceRoot || requestBundle.workspaceDir || process.cwd(),
+    options.homeDir || os.homedir(),
+  );
+  await ensureClaworldWorkingMemory(workspaceRoot, options);
+  const workingMemory = await readClaworldWorkingMemory(workspaceRoot, options);
+  const request = {
+    ...requestBundle,
+    runType: normalizedRunType,
+    workspaceRoot,
+    workingMemory,
+  };
+  const output = options.output
+    ?? (typeof options.maintenanceRunner === 'function'
+      ? await options.maintenanceRunner(request)
+      : null);
+  if (!output) {
+    return {
+      ok: true,
+      runType: normalizedRunType,
+      noOpReason: 'no_maintenance_runner',
+      request,
+      applied: [],
+    };
+  }
+  const normalized = validateClaworldMaintenanceOutput(normalizedRunType, output, options);
+  const applied = [];
+  for (const patch of normalized.patches) {
+    applied.push(await applyMaintenancePatch(workspaceRoot, patch));
+  }
+  return {
+    ok: true,
+    runType: normalizedRunType,
+    noOpReason: normalized.noOpReason,
+    request,
+    applied,
+  };
+}
+
+function isOpenClawConfigCandidate(value) {
+  return isPlainObject(value);
+}
+
+function selectOpenClawConfig(...candidates) {
+  const withAgents = candidates.find((candidate) => (
+    isOpenClawConfigCandidate(candidate)
+    && candidate.agents
+    && typeof candidate.agents === 'object'
+    && !Array.isArray(candidate.agents)
+  ));
+  if (withAgents) return withAgents;
+  return candidates.find(isOpenClawConfigCandidate) || {};
+}
+
+export function resolveClaworldMaintenanceWorkspaceRoot(requestBundle = {}, options = {}) {
+  const config = selectOpenClawConfig(
+    options.openClawConfig,
+    options.config,
+    requestBundle.openClawConfig,
+    requestBundle.config,
+    requestBundle.cfg,
+  );
+  const agentId = options.agentId
+    ?? options.localAgentId
+    ?? requestBundle.agentId
+    ?? requestBundle.localAgentId
+    ?? options.agent?.id
+    ?? options.agent?.agentId
+    ?? requestBundle.agent?.id
+    ?? requestBundle.agent?.agentId
+    ?? null;
+  return resolveOpenClawWorkspaceRoot({
+    sources: [options, requestBundle],
+    config,
+    agentId,
+  }, options.homeDir || os.homedir());
+}
+
+export async function runClaworldMemoryMaintenanceForOpenClaw(runType, requestBundle = {}, options = {}) {
+  const workspaceRoot = resolveClaworldMaintenanceWorkspaceRoot(requestBundle, options);
+  if (!workspaceRoot) {
+    throw new Error('Unable to resolve Claworld maintenance workspace root from OpenClaw context.');
+  }
+  return runClaworldMemoryMaintenance(
+    runType,
+    {
+      ...requestBundle,
+      workspaceRoot,
+    },
+    {
+      ...options,
+      workspaceRoot,
+    },
+  );
+}