Skip to content

Local-first 🧠 memory for Hermes Agent that lives in your Obsidian vault and remembers project context. Nightly 😴 dream passes turn repeat corrections into confirmed preferences with measurable confidence. Adapters ship for Claude Code, Codex, and OpenClaw, with an MCP server for anything else.

TypeScript
6.5 KB
Raw Blame
/**
 * `o2b brain payload get|list|gc` (payload registry, t_35440e83).
 *
 * Session import moves oversized content - data URIs, long base64 runs,
 * turn text past `sessions.payload_max_text_chars` - into
 * `Brain/.payloads/<sha256>.txt` and leaves a
 * `[payload: osb-payload://<sha256> chars=N]` placeholder in the
 * continuity row. These verbs are the operator's way back to the bytes
 * and the way to keep the store from growing without bound:
 *
 *   get <ref> [--offset N] [--limit N] [--json]
 *       One bounded page of the exact stored content. Without --json the
 *       page is written to stdout verbatim, so `--limit` large enough
 *       pipes the whole payload into a file.
 *   list [--json]
 *       Every stored payload with its size and reference count, plus every
 *       referenced payload whose file is gone.
 *   gc [--apply] [--json]
 *       Dry-run by default: names the payloads nothing in the vault
 *       references. --apply removes exactly those, behind a recovery
 *       point (`payload-gc-<stamp>`), re-planning inside it.
 */

import {
  buildPayloadInventory,
  collectPayloadGarbage,
} from "../../../core/brain/payload-inventory.ts";
import {
  DEFAULT_PAYLOAD_PAGE_CHARS,
  PAYLOAD_GC_GRACE_MS,
  PayloadNotFoundError,
  PayloadRefError,
  PayloadRegistry,
} from "../../../core/brain/payload-registry.ts";
import { brainVerbContext, CliError, fail, ok, okJson, parse } from "../helpers.ts";

const USAGE =
  "usage: o2b brain payload get <osb-payload://sha256> [--offset N] [--limit N] [--json]\n" +
  "       o2b brain payload list [--json]\n" +
  "       o2b brain payload gc [--apply] [--json]";

export async function cmdBrainPayload(argv: string[]): Promise<number> {
  const sub = argv[0];
  if (sub === "get") return payloadGet(argv.slice(1));
  if (sub === "list") return payloadList(argv.slice(1));
  if (sub === "gc") return payloadGc(argv.slice(1));
  return fail(USAGE);
}

function payloadGet(argv: string[]): number {
  const { flags, positional } = parse(argv, {
    vault: { type: "string" },
    json: { type: "boolean" },
    offset: { type: "string" },
    limit: { type: "string" },
  });
  const ref = positional[0];
  if (ref === undefined) return fail(USAGE);
  const offset = integerFlag(flags["offset"], "--offset", 0) ?? 0;
  const limit = integerFlag(flags["limit"], "--limit", 1) ?? DEFAULT_PAYLOAD_PAGE_CHARS;
  const vault = brainVerbContext(flags).vault;
  // Thresholds do not matter to a read; the registry only needs the vault.
  const registry = new PayloadRegistry({ vault, maxInlineChars: 1 });
  let page;
  try {
    page = registry.get(ref, { offset, limit });
  } catch (err) {
    if (err instanceof PayloadRefError || err instanceof PayloadNotFoundError) {
      return fail(`brain payload get: ${err.message}`);
    }
    throw err;
  }
  if (flags["json"] === true) {
    okJson({
      ref: page.ref,
      offset: page.offset,
      limit: page.limit,
      total_chars: page.totalChars,
      next_offset: page.nextOffset,
      content: page.content,
    });
    return 0;
  }
  process.stdout.write(page.content);
  if (page.nextOffset !== null) {
    process.stderr.write(
      `\n[payload: ${page.totalChars} chars total; next page: --offset ${page.nextOffset}]\n`,
    );
  }
  return 0;
}

function payloadList(argv: string[]): number {
  const { flags } = parse(argv, { vault: { type: "string" }, json: { type: "boolean" } });
  const vault = brainVerbContext(flags).vault;
  const inventory = buildPayloadInventory(vault);
  if (flags["json"] === true) {
    okJson({
      stored: inventory.stored.map((entry) => ({
        ref: entry.ref,
        path: entry.path,
        bytes: entry.bytes,
        referrers: entry.referrers,
        orphan: entry.referrers === 0,
      })),
      missing: inventory.missing.map((entry) => ({
        ref: entry.ref,
        referrers: entry.referrers.map((r) => ({
          path: r.path,
          ...(r.line !== undefined ? { line: r.line } : {}),
        })),
      })),
    });
    return 0;
  }
  if (inventory.stored.length === 0 && inventory.missing.length === 0) {
    ok("no payloads stored and none referenced");
    return 0;
  }
  for (const entry of inventory.stored) {
    const tag = entry.referrers === 0 ? "orphan" : `${entry.referrers} ref(s)`;
    ok(`${entry.ref}  ${entry.bytes} bytes  ${tag}`);
  }
  for (const entry of inventory.missing) {
    ok(`${entry.ref}  MISSING  referenced by ${entry.referrers.length} place(s)`);
  }
  return 0;
}

function payloadGc(argv: string[]): number {
  const { flags } = parse(argv, {
    vault: { type: "string" },
    json: { type: "boolean" },
    apply: { type: "boolean" },
  });
  const vault = brainVerbContext(flags).vault;
  const apply = flags["apply"] === true;
  const result = collectPayloadGarbage(vault, { apply });
  if (flags["json"] === true) {
    okJson({
      applied: result.applied,
      orphans: result.orphans.map((entry) => ({
        ref: entry.ref,
        path: entry.path,
        bytes: entry.bytes,
      })),
      deferred: result.deferred.map((entry) => ({
        ref: entry.ref,
        path: entry.path,
        bytes: entry.bytes,
      })),
      removed: result.removed,
      bytes: result.bytes,
      snapshot: result.snapshot?.runId ?? null,
    });
    return 0;
  }
  if (result.deferred.length > 0) {
    ok(
      `${result.deferred.length} unreferenced payload(s) younger than ` +
        `${PAYLOAD_GC_GRACE_MS / 60_000} minutes left for a later pass`,
    );
  }
  if (result.orphans.length === 0) {
    ok("no unreferenced payloads to remove");
    return 0;
  }
  if (!apply) {
    for (const entry of result.orphans) ok(`would remove ${entry.path} (${entry.bytes} bytes)`);
    ok(
      `${result.orphans.length} unreferenced payload(s), ${result.bytes} bytes; ` +
        "re-run with --apply to remove them behind a recovery point",
    );
    return 0;
  }
  for (const path of result.removed) ok(`removed ${path}`);
  ok(
    `removed ${result.removed.length} payload(s), ${result.bytes} bytes; ` +
      `recovery point: ${result.snapshot?.runId ?? "none"}`,
  );
  return 0;
}

function integerFlag(
  value: string | boolean | string[] | undefined,
  flag: string,
  min: number,
): number | undefined {
  if (value === undefined) return undefined;
  if (typeof value !== "string" || !/^[0-9]+$/.test(value.trim())) {
    throw new CliError(`brain payload get: ${flag} must be an integer >= ${min}`);
  }
  const parsed = Number.parseInt(value.trim(), 10);
  if (parsed < min) throw new CliError(`brain payload get: ${flag} must be an integer >= ${min}`);
  return parsed;
}