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.1 KB
Raw Blame
/**
 * `o2b brain query` - read-only lookup by preference, topic, or log
 * timestamp.
 *
 * Topic mode is the one surface in this system that ENFORCES per-memory
 * expiry (`filterExpired`, reached only through `queryByRuleTopic`), so it is
 * also the only one where a point-in-time question is meaningful. Both
 * knobs the filter has always taken are exposed here:
 *
 *   --at <ISO|YYYY-MM-DD>  the instant `expiration_date` is compared
 *                          against, so a memory that lapsed after it is
 *                          recalled as it stood then;
 *   --show-expired         keep lapsed memories regardless of the clock.
 *
 * Neither reaches the preference or log-since modes, which run no expiry
 * filter, so supplying one there is refused rather than accepted and
 * ignored.
 */

import {
  queryByLogSince,
  queryByPreference,
  queryByRuleTopic,
  BrainNotFoundError,
  type QueryByTopicOptions,
} from "../../../core/brain/query.ts";
import { parseIsoUtc } from "../../../core/brain/health/iso-time.ts";
import {
  brainVerbContext,
  fail,
  parse,
  parseOptionalIsoDate,
  renderQueryLogText,
  renderQueryPreferenceText,
  renderQueryRuleTopicText,
  usageError,
} from "../helpers.ts";
import { CLI_TRANSPORT_REACH } from "../../transport-reach.ts";

/** The two point-in-time flags, which only the expiry filter reads. */
const AS_OF_FLAG = "--at";
const SHOW_EXPIRED_FLAG = "--show-expired";

/** Accepted `--at` forms, named in every refusal so the exit is actionable. */
const AS_OF_FORMS = "an ISO-8601 instant or YYYY-MM-DD date";

export async function cmdBrainQuery(argv: string[]): Promise<number> {
  const { flags } = parse(argv, {
    vault: { type: "string" },
    preference: { type: "string" },
    topic: { type: "string" },
    since: { type: "string" },
    at: { type: "string" },
    "show-expired": { type: "boolean" },
    json: { type: "boolean" },
  });
  const { vault } = brainVerbContext(flags);

  const modes = ["preference", "topic", "since"].filter(
    (k) => typeof flags[k] === "string" && (flags[k] as string).trim() !== "",
  );
  if (modes.length === 0)
    return fail("brain query requires exactly one of --preference, --topic, --since");
  if (modes.length > 1)
    return fail(
      `brain query: pick only one of --preference / --topic / --since (got ${modes.join(", ")})`,
    );

  // `--at` moves the clock the expiration filter compares against and
  // `--show-expired` turns that filter off; `queryByRuleTopic` is the only
  // reader of either. Naming that here beats accepting a flag on
  // `--preference` / `--since` that would quietly change nothing.
  const atRaw = typeof flags["at"] === "string" ? flags["at"].trim() : null;
  const showExpired = flags["show-expired"] === true;
  if (flags["topic"] === undefined) {
    const misplaced = [
      ...(atRaw !== null ? [AS_OF_FLAG] : []),
      ...(showExpired ? [SHOW_EXPIRED_FLAG] : []),
    ];
    if (misplaced.length > 0) {
      return usageError(
        `brain query: ${misplaced.join(" / ")} only applies to --topic (the expiration filter runs there)`,
      );
    }
  }
  let asOf: Date | null = null;
  if (atRaw !== null) {
    // An unparseable instant is refused, never coerced to the wall
    // clock: answering "as of now" for a caller who asked "as of then"
    // answers a different question without saying so.
    const atMs = parseIsoUtc(atRaw);
    if (!Number.isFinite(atMs)) {
      return usageError(`brain query ${AS_OF_FLAG} must be ${AS_OF_FORMS}; got ${atRaw}`);
    }
    asOf = new Date(atMs);
  }

  try {
    if (flags["preference"]) {
      const out = queryByPreference(vault, String(flags["preference"]));
      if (flags["json"]) {
        process.stdout.write(JSON.stringify(out, null, 2) + "\n");
      } else {
        renderQueryPreferenceText(out);
      }
      return 0;
    }
    if (flags["topic"]) {
      const topicOptions: QueryByTopicOptions = {
        showExpired,
        // The operator's own shell, stated rather than assumed: this verb
        // asks the same selection rule `brain_query` asks, and the answer
        // it gets is "admit everything" because of who the caller is, not
        // because nobody asked.
        transportReach: CLI_TRANSPORT_REACH,
        ...(asOf !== null ? { now: asOf } : {}),
      };
      const out = queryByRuleTopic(vault, String(flags["topic"]), topicOptions);
      if (flags["json"]) {
        process.stdout.write(JSON.stringify(out, null, 2) + "\n");
      } else {
        renderQueryRuleTopicText(out, String(flags["topic"]));
      }
      return 0;
    }
    if (flags["since"]) {
      const { value: sinceDate, error: sinceErr } = parseOptionalIsoDate(flags, "since");
      if (sinceErr) return fail(sinceErr);
      const entries = queryByLogSince(vault, sinceDate!);
      if (flags["json"]) {
        process.stdout.write(JSON.stringify(entries, null, 2) + "\n");
      } else {
        renderQueryLogText(entries);
      }
      return 0;
    }
  } catch (exc) {
    if (exc instanceof BrainNotFoundError) {
      process.stderr.write(`${exc.message}\n`);
      return 2;
    }
    return fail(`query failed: ${(exc as Error).message ?? exc}`);
  }
  return 0;
}