Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript
10.3 KB
Raw Blame
/**
 * Opt-in vector (HNSW) index prewarm for Postgres brains (GBRA-156).
 *
 * A search whose embedding has not been seen walks HNSW pages nobody has read
 * since the last restart or eviction: on a brain whose index exceeds the cache
 * that is 2-4.5k uncached index pages and 1.2-2.7 s of first-touch vector time.
 * `gbrain embeddings prewarm` (and `serve.vector_prewarm` at serve start) loads
 * every HNSW index of the brain's schema into shared_buffers with
 * pg_prewarm(..., 'buffer') once, so later searches find those pages cached.
 *
 * Which cache decides: shared_buffers. pg_prewarm's 'buffer' mode loads pages
 * into Postgres's own buffer cache, the one cache whose size the server knows
 * (current_setting('shared_buffers')) and whose contents it keeps. The total
 * HNSW size must fit in PREWARM_SHARED_BUFFERS_SHARE of it; past that the
 * prewarm would evict the heap, keyword-index and catalog pages every other
 * read needs, trading vector first touches for keyword ones. Nothing is read
 * before this check passes: index sizes come from pg_relation_size (file
 * sizes, no relation pages) and the settings from current_setting.
 * effective_cache_size is read when it can be and reported, but it decides
 * nothing: it is a planner hint the operator types in, the server never
 * allocates it, and it says nothing about what the OS page cache holds or can
 * keep, so a fit against it could not be honest.
 *
 * Local operator only: a CLI-only command (never an operation, so no MCP
 * caller can reach it) that thin clients refuse, plus an opt-in serve-start
 * hook that is off by default. PGLite has no server buffer cache that
 * outlives the process, so it is refused.
 */
import type { BrainEngine } from './engine.ts';
import type { Action } from './agent-output.ts';
import { opError } from './ops/contract.ts';

/** At most this share of shared_buffers may go to prewarmed HNSW pages; the rest stays for heap, keyword-index and catalog pages. */
export const PREWARM_SHARED_BUFFERS_SHARE = 0.5;

export interface VectorIndexSize { index: string; table: string; bytes: number }

export interface VectorPrewarmPlan {
  indexes: VectorIndexSize[];
  total_bytes: number;
  shared_buffers_bytes: number;
  /** Reported for context only; null when the server would not say. */
  effective_cache_size_bytes: number | null;
  budget_bytes: number;
  decided_by: 'shared_buffers';
  fits: boolean;
  /** Installed pg_prewarm version, null when the extension is not created in this database. */
  extension_version: string | null;
  extension_available: boolean;
}

export interface VectorPrewarmResult extends VectorPrewarmPlan {
  dry_run: boolean;
  mode: 'buffer';
  /** Per index: blocks pg_prewarm loaded and how long it took (empty on a dry run). */
  loaded: Array<{ index: string; blocks: number; ms: number }>;
  elapsed_ms: number;
}

const MB = 1024 * 1024;
const mb = (bytes: number) => `${Math.ceil(bytes / MB)} MB`;

/** The fit decision: shared_buffers alone, against PREWARM_SHARED_BUFFERS_SHARE of it. */
export function prewarmFits(totalBytes: number, sharedBuffersBytes: number): { fits: boolean; budget_bytes: number } {
  const budget = Math.floor(sharedBuffersBytes * PREWARM_SHARED_BUFFERS_SHARE);
  return { fits: totalBytes <= budget, budget_bytes: budget };
}

/** Index sizes, cache settings and extension state; reads catalogs and file sizes only, never a relation page. */
export async function readVectorPrewarmPlan(engine: BrainEngine): Promise<VectorPrewarmPlan> {
  const indexes = (await engine.executeRaw<{ index: string; table: string; bytes: string | number }>(
    `SELECT c.relname AS index, t.relname AS "table", pg_relation_size(c.oid)::bigint AS bytes
       FROM pg_index i
       JOIN pg_class c ON c.oid = i.indexrelid
       JOIN pg_class t ON t.oid = i.indrelid
       JOIN pg_namespace n ON n.oid = c.relnamespace
       JOIN pg_am am ON am.oid = c.relam
      WHERE am.amname = 'hnsw' AND i.indisvalid AND n.nspname = current_schema()
      ORDER BY 3 DESC, 1`)).map(r => ({ index: r.index, table: r.table, bytes: Number(r.bytes) }));
  const [s] = await engine.executeRaw<{ shared_buffers: string | number; effective_cache_size: string | number | null; extension_version: string | null; extension_available: boolean }>(
    `SELECT pg_size_bytes(current_setting('shared_buffers'))::bigint AS shared_buffers,
            pg_size_bytes(current_setting('effective_cache_size', true))::bigint AS effective_cache_size,
            (SELECT extversion FROM pg_extension WHERE extname = 'pg_prewarm') AS extension_version,
            EXISTS (SELECT 1 FROM pg_available_extensions WHERE name = 'pg_prewarm') AS extension_available`);
  const total = indexes.reduce((sum, i) => sum + i.bytes, 0);
  const sharedBuffers = Number(s!.shared_buffers);
  const { fits, budget_bytes } = prewarmFits(total, sharedBuffers);
  return {
    indexes, total_bytes: total, shared_buffers_bytes: sharedBuffers,
    effective_cache_size_bytes: s!.effective_cache_size === null ? null : Number(s!.effective_cache_size),
    budget_bytes, decided_by: 'shared_buffers', fits,
    extension_version: s!.extension_version, extension_available: s!.extension_available === true,
  };
}

const VERIFY: Action['verify'] = { argv: ['gbrain', 'embeddings', 'prewarm', '--dry-run', '--json'] };

function tooLarge(plan: VectorPrewarmPlan) {
  const needed = Math.ceil(plan.total_bytes / PREWARM_SHARED_BUFFERS_SHARE / MB);
  return opError('vector_prewarm_wont_fit',
    `The vector indexes total ${mb(plan.total_bytes)}, more than the ${mb(plan.budget_bytes)} prewarm budget (${PREWARM_SHARED_BUFFERS_SHARE * 100}% of shared_buffers ${mb(plan.shared_buffers_bytes)}); nothing was read.`,
    `Raise shared_buffers to at least ${needed} MB on the database host and restart Postgres, or leave the indexes cold.`,
    {
      why: 'pg_prewarm loads the indexes into shared_buffers; past half of it the prewarm would evict the heap and keyword-index pages other reads need, so the next searches would pay first-touch reads on those instead. effective_cache_size is not used: it is a planner hint, not memory the server holds.',
      fix: {
        argv: ['psql', '-c', `ALTER SYSTEM SET shared_buffers = '${needed}MB'`], consent: [], actor: 'host_admin', requires_exclusive: false,
        why: `shared_buffers takes effect only after a Postgres restart, and the host needs that much RAM to spare (a managed database sets it through its instance size).`,
        user_message: `Prewarming the vector index needs shared_buffers of at least ${needed} MB on the database (it is ${mb(plan.shared_buffers_bytes)}). That is a database setting and a restart; search keeps working without it.`,
        verify: VERIFY,
      },
    });
}

function extensionMissing(plan: VectorPrewarmPlan) {
  return opError('vector_prewarm_extension_missing',
    plan.extension_available
      ? 'The pg_prewarm extension is not created in this database; nothing was read.'
      : 'This Postgres server does not ship the pg_prewarm extension; nothing was read.',
    plan.extension_available
      ? 'Create it once as a role that may create extensions: CREATE EXTENSION IF NOT EXISTS pg_prewarm;'
      : 'Install the PostgreSQL contrib package on the database host (pg_prewarm is part of it), then CREATE EXTENSION IF NOT EXISTS pg_prewarm;',
    {
      why: 'gbrain loads index pages with pg_prewarm, the Postgres contrib function that reads a relation into shared_buffers; without it there is no supported way to fill the buffer cache.',
      fix: {
        argv: ['psql', '-c', 'CREATE EXTENSION IF NOT EXISTS pg_prewarm'], consent: [], actor: 'host_admin', requires_exclusive: false,
        why: 'Creating an extension needs a database owner or superuser (on a managed database, its extensions page).',
        user_message: 'Prewarming the vector index needs the pg_prewarm extension in the database. Creating it is a one-time step for whoever administers the database.',
        verify: VERIFY,
      },
    });
}

export function vectorPrewarmUnsupported() {
  return opError('vector_prewarm_unsupported_engine',
    'Vector index prewarm runs on Postgres brains only; this brain is PGLite, and nothing was read.',
    'Nothing to do: PGLite runs inside this process, with no server buffer cache that outlives it.',
    { why: 'Prewarm fills Postgres shared_buffers so later processes find index pages cached; PGLite has no shared server cache to fill.' });
}

/** Check the fit, then (unless a dry run) prewarm every HNSW index into shared_buffers, largest first. */
export async function runVectorPrewarm(engine: BrainEngine, opts: { dryRun?: boolean } = {}): Promise<VectorPrewarmResult> {
  if (engine.kind !== 'postgres') throw vectorPrewarmUnsupported();
  const t0 = performance.now();
  const plan = await readVectorPrewarmPlan(engine);
  if (!plan.fits) throw tooLarge(plan);
  if (!plan.extension_version && !opts.dryRun) throw extensionMissing(plan);
  const loaded: VectorPrewarmResult['loaded'] = [];
  if (!opts.dryRun) {
    for (const ix of plan.indexes) {
      const t = performance.now();
      const blocks = await engine.transaction(async tx => {
        await tx.executeRaw('SET LOCAL statement_timeout = 0');
        const [row] = await tx.executeRaw<{ blocks: string | number }>(`SELECT pg_prewarm(format('%I.%I', current_schema(), $1::text)::regclass, 'buffer')::bigint AS blocks`, [ix.index]);
        return Number(row?.blocks ?? 0);
      });
      loaded.push({ index: ix.index, blocks, ms: Math.round(performance.now() - t) });
    }
  }
  return { ...plan, dry_run: opts.dryRun === true, mode: 'buffer', loaded, elapsed_ms: Math.round(performance.now() - t0) };
}

/** serve.vector_prewarm: one prewarm after the serve boots, logged; a refusal or failure is logged and never stops the serve. */
export async function prewarmAtServeStart(engine: BrainEngine, log: (line: string) => void): Promise<void> {
  if (engine.kind !== 'postgres') { log('[gbrain serve] vector prewarm: skipped (Postgres only; this brain is PGLite)'); return; }
  try {
    const r = await runVectorPrewarm(engine);
    const blocks = r.loaded.reduce((sum, l) => sum + l.blocks, 0);
    log(`[gbrain serve] vector prewarm: loaded ${r.loaded.length} index(es), ${mb(blocks * 8192)}, into shared_buffers in ${(r.elapsed_ms / 1000).toFixed(1)} s`);
  } catch (error) {
    const e = error as { code?: string; message?: string };
    log(`[gbrain serve] vector prewarm: skipped (${e.code ?? 'error'}): ${e.message ?? String(error)}`);
  }
}