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
5.2 KB
Raw Blame
/**
 * `o2b brain capture <body>` - stage one inbound capture from a terminal.
 *
 * The capture contract shipped with exactly one writer: the inbound
 * Telegram bot. Everything downstream of it - the staging area, the
 * inbox drain, the `/catchup` watermark - was therefore reachable only by
 * an install that had configured a chat channel, and an operator sitting
 * in front of the vault had no way in at all.
 *
 * This verb is that door and nothing more. It builds a
 * {@link WriteCaptureInput} and hands it to the same
 * {@link writeCaptureNote} the bot calls, so the id hash, the frontmatter,
 * the guidance section and the collision ladder are the contract's and
 * cannot drift into a second set of rules.
 *
 * The body may be an argument or arrive on stdin - a captured thought is
 * as often the output of another command as it is something typed - and
 * the two paths produce the same page. `--sender` names who is capturing
 * and defaults to the configured agent, because a capture with no
 * attributable sender is a record whose provenance nobody can reconstruct.
 */

import {
  CaptureContractError,
  writeCaptureNote,
  type CaptureNote,
} from "../../../core/brain/capture/capture-note.ts";
import { isoSecond } from "../../../core/brain/time.ts";
import { readStdinText } from "../../stdin.ts";
import { CliError } from "../../argparse.ts";
import {
  brainVerbContext,
  normalizeFlagString,
  ok,
  okJson,
  parse,
  parseOptionalIsoDate,
  resolveBrainAgent,
} from "../helpers.ts";

const USAGE =
  "usage: o2b brain capture [<body>] [--source <channel>] [--sender <who>] " +
  "[--guidance <text>] [--at <ISO>] [--vault <path>] [--json]";

/** Channel recorded when the caller names none: this verb itself. */
const DEFAULT_SOURCE = "cli";

/**
 * Refuse a request this verb understood and declined. Exit 2, with the
 * reason on stderr for a human and inside the payload for a machine - the
 * `dream` verb's shape, so a caller parsing one parses both.
 */
function refuse(message: string, asJson: boolean): number {
  if (asJson) {
    okJson({ ok: false, message });
    return 2;
  }
  process.stderr.write(`error: ${message}\n`);
  return 2;
}

function renderJson(note: CaptureNote): Record<string, unknown> {
  return {
    ok: true,
    id: note.id,
    path: note.path,
    body: note.body,
    guidance: note.guidance,
    source: note.provenance.source,
    sender: note.provenance.sender,
    captured_at: note.provenance.capturedAt,
    staged: note.staged,
  };
}

export async function cmdBrainCapture(argv: string[]): Promise<number> {
  const { flags, positional } = parse(argv, {
    vault: { type: "string" },
    source: { type: "string" },
    sender: { type: "string" },
    guidance: { type: "string" },
    agent: { type: "string" },
    at: { type: "string" },
    json: { type: "boolean" },
  });
  const asJson = flags["json"] === true;

  // The argument wins over stdin. Reading both and concatenating would
  // silently merge two authors' text into one capture; reading stdin when
  // an argument was given would discard what the caller typed.
  let body = positional.join(" ").trim();
  if (body.length === 0) {
    try {
      body = (await readStdinText()).trim();
    } catch (exc) {
      return refuse(
        `capture could not read the body from stdin: ${(exc as Error).message ?? String(exc)}`,
        asJson,
      );
    }
  }
  if (body.length === 0) {
    return refuse(`capture body is empty; pass it as an argument or on stdin. ${USAGE}`, asJson);
  }

  // An explicit `--at` keeps a backfilled capture on its own instant
  // rather than the wall clock of the shell that replayed it.
  const at = parseOptionalIsoDate(flags, "at");
  if (at.error !== null) return refuse(at.error, asJson);
  const capturedAt = isoSecond(at.value ?? new Date());

  let context;
  try {
    context = brainVerbContext(flags);
  } catch (exc) {
    if (exc instanceof CliError) return refuse(exc.message, asJson);
    throw exc;
  }

  const guidance = normalizeFlagString(flags["guidance"]);
  // A `--guidance` that was passed and normalises away is whitespace the
  // caller meant as an instruction. The contract refuses it by name; this
  // check exists so the refusal names the FLAG rather than the field.
  if (flags["guidance"] !== undefined && guidance === null) {
    return refuse(
      "capture --guidance was passed with no text; drop the flag or say something",
      asJson,
    );
  }

  try {
    const note = writeCaptureNote(context.vault, {
      body,
      provenance: {
        source: normalizeFlagString(flags["source"]) ?? DEFAULT_SOURCE,
        sender: normalizeFlagString(flags["sender"]) ?? resolveBrainAgent(flags, context.config),
        capturedAt,
      },
      ...(guidance === null ? {} : { guidance }),
    });
    if (asJson) okJson(renderJson(note));
    else {
      ok(`captured: ${note.id}`);
      ok(`  path: ${note.path}`);
      ok(`  source: ${note.provenance.source} / sender: ${note.provenance.sender}`);
      if (note.guidance !== null) ok(`  guidance: ${note.guidance}`);
    }
    return 0;
  } catch (exc) {
    if (exc instanceof CaptureContractError) return refuse(exc.message, asJson);
    if (exc instanceof CliError) return refuse(exc.message, asJson);
    throw exc;
  }
}