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
import { readFileSync } from "node:fs";

import { BankImportError, importBankBundle } from "../../../core/brain/portability/bundle.ts";
import type { GraphImportMode } from "../../../core/brain/portability/graph.ts";
import { brainVerbContext, fail, parse, resolveBrainAgent } from "../helpers.ts";

const MODES: ReadonlyArray<GraphImportMode> = ["skip", "overwrite", "merge"];

/**
 * `o2b brain bank-import <file> [--mode skip|overwrite|merge]
 * [--trusted-restore] [--agent <name>] [--json]` reconstruct the page
 * graph and the preferences from a bank bundle.json.
 *
 * `--mode` governs the page graph; `skip` (default) never overwrites.
 * Preferences restore through the audited preference transaction and are
 * governed by their revision instead: a bundle behind the vault is
 * refused per-row and named in the result, as is a row whose id, topic or
 * alias arrived carrying the redactor's placeholder - a name that is gone
 * and that every other redacted row shares. Page contracts and the
 * sources dashboard stay carried-not-restored. An unsupported bundle
 * schema fails loudly.
 *
 * Preference rows are restored UNTRUSTED by default: every row the bundle
 * carries lands `unconfirmed`, unpinned, at low confidence, on a fresh
 * trial window dated from the restore (one already `unconfirmed` too),
 * because the file argument is not a vouching for its contents. Pass
 * `--trusted-restore` to restore the carried state verbatim - the
 * round-trip of a backup the operator vouches for.
 */
export async function cmdBrainBankImport(argv: string[]): Promise<number> {
  const { flags, positional } = parse(argv, {
    vault: { type: "string" },
    json: { type: "boolean" },
    mode: { type: "string" },
    agent: { type: "string" },
    "trusted-restore": { type: "boolean" },
  });
  const file = positional[0];
  if (!file) {
    process.stderr.write(
      "usage: o2b brain bank-import <file> [--mode skip|overwrite|merge] [--trusted-restore]\n",
    );
    return 2;
  }

  const mode = (flags["mode"] as string | undefined) ?? "skip";
  if (!MODES.includes(mode as GraphImportMode)) {
    process.stderr.write(
      `error: bank-import: --mode must be one of ${MODES.join(" | ")}; got ${mode}\n`,
    );
    return 2;
  }

  const { vault, config } = brainVerbContext(flags);
  const agent = resolveBrainAgent(flags, config);

  // JSON boundary: parse then hand the loosely-typed shape to the
  // importer, which validates the schema and guards every graph node
  // and preference row.
  let bundle: {
    schema?: unknown;
    graph?: { nodes?: ReadonlyArray<unknown> };
    preferences?: unknown;
  };
  try {
    bundle = JSON.parse(readFileSync(file, "utf8")) as typeof bundle;
  } catch (exc) {
    return fail(`bank-import: failed to read ${file}: ${(exc as Error).message ?? exc}`);
  }

  let result;
  try {
    result = importBankBundle(vault, bundle, {
      mode: mode as GraphImportMode,
      agent,
      ...(flags["trusted-restore"] === true ? { trustedRestore: true } : {}),
    });
  } catch (exc) {
    if (exc instanceof BankImportError) return fail(`bank-import: ${exc.message}`);
    return fail(`bank-import failed: ${(exc as Error).message ?? exc}`);
  }

  if (flags["json"]) {
    process.stdout.write(JSON.stringify(result, null, 2) + "\n");
  } else {
    const g = result.graph;
    const p = result.preferences;
    const lines = [
      `graph: created ${g.created.length}, overwritten ${g.overwritten.length}, ` +
        `merged ${g.merged.length}, skipped ${g.skipped.length}, rejected ${g.rejected.length}`,
      `preferences: restored ${p.restored.length} of ${p.carried}, failed ${p.failed.length}` +
        `${p.fieldsNotRestored.length > 0 ? `, not restored: ${p.fieldsNotRestored.join(", ")}` : ""}` +
        `${p.demotedToUnconfirmed.length > 0 ? `, demoted to unconfirmed: ${p.demotedToUnconfirmed.length}` : ""}`,
      `carried (not restored): ${result.pagesCarried} page contracts, ` +
        `sources ${result.sourcesCarried ? "yes" : "no"}`,
    ];
    for (const failure of p.failed) {
      lines.push(`  ${failure.id ?? `#${failure.index}`}: ${failure.reason} (${failure.detail})`);
    }
    // A value the bundle did not carry is reported as derived, never folded
    // into the restored count as if the backup had contained it.
    for (const d of p.derived) {
      lines.push(`  ${d.id}: ${d.field} derived from ${d.derivedFrom} (${d.value})`);
    }
    // The untrusted default is a state change the bundle did not ask for,
    // so every demoted row is named: an operator restoring their own
    // backup sees exactly which rules need `--trusted-restore` to land
    // live, and an operator who did not vouch for the file sees which
    // rules it tried to land live.
    for (const id of p.demotedToUnconfirmed) {
      lines.push(
        `  ${id}: restored unconfirmed (trial window restarted); use --trusted-restore to keep the carried status`,
      );
    }
    // A contention this import created: the dream pass plans nothing for a
    // topic key two spellings claim, so an operator who is not told here
    // sees consolidation stop with no cause named.
    for (const collision of p.topicKeyCollisions) {
      lines.push(
        `  topic key '${collision.key}' is claimed by ${collision.topics.join(", ")} ` +
          `(${collision.prefIds.join(", ")}); consolidation plans nothing until one owner remains`,
      );
    }
    // The collision list above is a claim over every rule already in the
    // DESTINATION. A rule the scan could not parse makes it a partial
    // claim, and an empty list read as "no collisions" would be the
    // confident zero. The import itself is unaffected - those files are
    // not what the bundle carried - so it proceeds and says this instead
    // of refusing wholesale.
    for (const unreadable of p.topicScanUnreadable) {
      lines.push(
        `  topic-key check incomplete: ${unreadable.path} could not be parsed ` +
          `(${unreadable.reason}); an existing rule may already claim a restored topic key`,
      );
    }
    process.stdout.write(lines.join("\n") + "\n");
  }
  // A refused preference is a partial import, not a clean one: the caller
  // asked for the bundle's rules and did not get all of them. A row restored
  // on a DERIVED value did land, so it does not gate the code - it is
  // reported above instead, as is a topic-key collision the import created:
  // both are states an operator must see, neither is a rule left on the
  // floor. The graph half keeps its own per-entry tolerance and does not
  // gate the code either.
  return result.preferences.failed.length > 0 ? 1 : 0;
}