Skip to content

Soul-driven AI agent with permission-hardened tools, token budgets, and multi-channel access. Runs 24/7 from CLI, Telegram or More.

4.7 KB
Raw Blame
const MB = 1024 * 1024;

/**
 * Step-level memory governor for agent loops.
 *
 * The wall-clock memory guard (setInterval) cannot fire while the event loop
 * is blocked (stream floods, big tool executions). This governor runs at
 * deterministic points — between AI SDK steps — so growth is checked at
 * every tool-step boundary regardless of event loop pressure.
 *
 * Graduated response (per task):
 *   ok       → no action
 *   relief   → trim conversation budget (oldest tool results)
 *   abort    → abort the current generation; the task fails gracefully
 *   exit     → the allocator is beyond abort reach; exit while state persists
 */
export type MemoryGovernorVerdict = 'ok' | 'relief' | 'abort' | 'exit';

export interface MemoryGovernorThresholds {
  /** heapUsed above this triggers conversation relief (trim old tool results). */
  reliefBytes: number;
  /** heapUsed above this aborts the current generation. */
  abortBytes: number;
  /** heapUsed above this exits the process while persistence is still possible. */
  exitBytes: number;
}

export interface MemoryGovernorDeps {
  heapSizeLimit: number;
  baselineHeapUsed: number;
  /** Minimum heap the process needs to survive (persist, render, respond). */
  reservedHeapBytes?: number;
}

export function memoryGovernorThresholds(deps: MemoryGovernorDeps): MemoryGovernorThresholds {
  const reserve = deps.reservedHeapBytes ?? 512 * MB;
  const usable = Math.max(256 * MB, deps.heapSizeLimit - reserve);
  const floor = deps.baselineHeapUsed + 256 * MB;
  const relief = Math.min(Math.max(floor, 384 * MB), usable);
  const abort = Math.min(Math.max(relief + 128 * MB, Math.floor(usable * 0.6)), usable);
  const exit = Math.min(Math.max(abort + 256 * MB, deps.heapSizeLimit - 64 * MB), deps.heapSizeLimit);
  return { reliefBytes: relief, abortBytes: abort, exitBytes: exit };
}

export function memoryGovernorVerdict(heapUsed: number, t: MemoryGovernorThresholds): MemoryGovernorVerdict {
  if (heapUsed >= t.exitBytes) return 'exit';
  if (heapUsed >= t.abortBytes) return 'abort';
  if (heapUsed >= t.reliefBytes) return 'relief';
  return 'ok';
}

/**
 * Conversation budget for one task: total retained characters of tool-result
 * content in the messages array sent to the model. Oldest tool results are
 * summarized (head + tail) once the budget is exceeded, so a long analysis
 * cannot retain gigabytes of file/command output in the conversation history.
 */
export const CONVERSATION_TOOL_BUDGET_CHARS = 512 * 1024;

/** Keep the most recent tool results verbatim regardless of budget. */
export const TOOL_RESULT_KEEP_RECENT = 8;

/** Per-result summary size when a result is compacted (head/tail). */
export const TOOL_RESULT_SUMMARY_CHARS = 4 * 1024;

/**
 * Compact an oversized tool result string in place (returns new string).
 * Preserves head + tail so file reads stay useful while bounding heap.
 */
export function summarizeToolResult(content: string): string {
  if (content.length <= TOOL_RESULT_SUMMARY_CHARS * 2 + 200) return content;
  const head = content.slice(0, TOOL_RESULT_SUMMARY_CHARS);
  const tail = content.slice(-TOOL_RESULT_SUMMARY_CHARS);
  return `${head}\n\n[…compacted by Mercury memory governor: ${content.length} chars → head+tail. Re-read specific sections if needed.]\n\n${tail}`;
}
/** Newest messages kept verbatim during aggressive compaction. */
export const COMPACTION_KEEP_RECENT = 8;

/**
 * Aggressive conversation compaction — the OpenCode practice: on memory
 * pressure, COMPACT and continue instead of aborting the task. Oldest
 * messages (beyond the recent window) have oversized tool results and long
 * text replaced with head+tail summaries, in place. Returns chars freed.
 * The model keeps full awareness of WHAT was done (tool narrative lives in
 * the step log) and only loses verbatim bulk output it can re-read.
 */
export function compactConversation(messages: unknown[]): number {
  if (messages.length <= COMPACTION_KEEP_RECENT) return 0;
  let freed = 0;
  const cutoff = messages.length - COMPACTION_KEEP_RECENT;
  for (let i = 0; i < cutoff; i++) {
    const msg = messages[i] as any;
    if (!msg || typeof msg !== 'object') continue;
    if (msg.role === 'tool' && Array.isArray(msg.content)) {
      for (const part of msg.content) {
        if (part?.type === 'tool-result' && typeof part.result === 'string' && part.result.length > TOOL_RESULT_SUMMARY_CHARS * 2) {
          freed += part.result.length;
          part.result = summarizeToolResult(part.result);
        }
      }
    } else if (typeof msg.content === 'string' && msg.content.length > TOOL_RESULT_SUMMARY_CHARS * 2) {
      freed += msg.content.length;
      msg.content = summarizeToolResult(msg.content);
    }
  }
  return freed;
}