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
10.6 KB
Raw Blame
/**
 * Whole-vault (bank) export/import (Brain Portability & Interop suite,
 * Unit A).
 *
 * `exportBankBundle` composes the existing exporters - preferences
 * (`collectSharedExportRows`, the shared lanes' denying detail of
 * `collectExportRows`), the page link-graph (`exportVaultGraph`), the
 * page interchange contract (`projectPageContracts`), and the read-only
 * sources dashboard (`aggregateSources`) - into one schema-versioned
 * envelope for backup, cross-instance migration, or downstream-tool
 * ingest. It forks no serialisation path; it only assembles. Reserved
 * preference rows stay out of the shared composition and are named;
 * `includeReserved` is the personal-backup override that carries them
 * into the operator's own copy, where a reservation about shared
 * readers does not bind.
 *
 * `importBankBundle` reconstructs the two sections that round-trip: the
 * page graph, delegated to `importVaultGraph` under a conflict mode, and
 * the preferences, delegated to `restorePreferences` and through it to
 * `writePreferenceTxn` - the single chokepoint that owns the confidence
 * band, the trial window, the revision counter and the audit trail.
 * Preferences are not restored DESPITE that lifecycle but THROUGH it;
 * the alternative this module refused from the start - a raw write that
 * flattens the lifecycle - is still refused.
 *
 * The remaining sections are carried for fidelity and NOT restored: the
 * page contract is a read projection and the sources dashboard is
 * derived, so both are recomputed from the vault rather than written
 * into it. The result object names each of them, and names the exported
 * preference fields a write cannot reconstruct, so the bundle can never
 * be read as a full round-trip of material it did not reconstruct.
 *
 * `BANK_BUNDLE_SCHEMA_VERSION` stays `"1"`. Restoring preferences is
 * additive on both sides: an envelope written before the restore existed
 * carries rows without the trial window, and those rows are refused
 * per-entry with a named reason rather than by refusing the envelope.
 * Bumping the version would turn every existing bundle into a hard
 * refusal for material this reader already handles honestly.
 *
 * The same per-entry rule covers the other thing an older bundle can
 * carry: the redactor's placeholder in a field that names the record. The
 * export boundary now refuses to emit one, but a bundle already on disk
 * can hold it, and a placeholder is a constant - two records that lost a
 * name land on one. Both halves refuse those records and restore the rest:
 * preferences through `redacted_identifier` in `preferences.failed[]`, page
 * nodes through `graph.rejected[]`.
 */

import {
  collectExportRowsWithDenials,
  collectSharedExportRows,
  type ExportedPreferenceRow,
  type PreferenceDenial,
} from "../export.ts";
import { isoSecond } from "../time.ts";
import { vaultDisplayName } from "../templates.ts";
import {
  exportVaultGraph,
  importVaultGraph,
  type GraphImportMode,
  type GraphImportResult,
  type VaultGraph,
} from "./graph.ts";
import { projectPageContracts, type PageContract } from "./page-contract.ts";
import { restorePreferences, type PreferenceRestoreResult } from "./preference-restore.ts";
import { aggregateSources, type SourcesReport } from "./sources.ts";

export const BANK_BUNDLE_SCHEMA_VERSION = "1";

export interface BankBundle {
  readonly schema: string;
  /** Snapshot timestamp (ISO second). Not part of the content sections. */
  readonly generated_at: string;
  readonly vault_basename: string;
  readonly preferences: ReadonlyArray<ExportedPreferenceRow>;
  /**
   * The preferences the privacy deny markers kept out of this bundle,
   * each named with its id, the reason class and the key that denied it.
   * Absent when empty, so a vault with no reservation serialises with
   * exactly the keys it always carried (the schema stays "1" - additive,
   * the module's own versioning rule). Absent under
   * `includeReserved` too, for the same reason in reverse: nothing was
   * withheld, so there is nothing to report. The bank-export verb turns
   * the field into its stderr omission notice.
   */
  readonly preferences_omitted?: ReadonlyArray<PreferenceDenial>;
  readonly graph: VaultGraph;
  readonly pages: ReadonlyArray<PageContract>;
  readonly sources: SourcesReport;
}

/**
 * Export a whole-vault bank bundle. The content sections are
 * deterministic (each underlying exporter sorts); only `generated_at`
 * varies between runs. Pure and read-only on the vault.
 *
 * Preference rows the privacy deny markers reserve are left out of the
 * preferences section and named in `preferences_omitted` - the same
 * report the json preference export carries, so no two exporters
 * disagree about the same directory. `opts.includeReserved` is the
 * personal-backup override: the operator's own copy of their own vault,
 * where a reservation about shared readers does not bind, so the
 * reserved rows ride the section whole and the report is absent because
 * nothing was withheld.
 */
export function exportBankBundle(vault: string, opts: BankBundleExportOptions = {}): BankBundle {
  return exportBankBundleDetailed(vault, opts).bundle;
}

/** Options for {@link exportBankBundle}, stated beside the report. */
export interface BankBundleExportOptions {
  /**
   * Carry the reserved preference rows into the bundle's preferences
   * section. The personal-backup override, spelled
   * `--include-reserved` on the verb: a reservation is a statement about
   * shared readers, and a bundle the operator keeps for restore is not
   * one. Default (false): reserved rows stay out and are named in
   * `preferences_omitted`.
   */
  readonly includeReserved?: boolean;
}

/**
 * The bundle beside the reservation report, whatever the override
 * decided: `reserved` names the preferences the privacy deny markers
 * hold, on an override run (where they rode the section IN and the run
 * must say so) exactly as on a default run (where they stayed out and
 * the report rides the bundle).
 */
export interface BankBundleExport {
  readonly bundle: BankBundle;
  readonly reserved: ReadonlyArray<PreferenceDenial>;
}

/**
 * The one-walk composition behind {@link exportBankBundle}: callers that
 * must say on stderr what the reservation did - in either direction -
 * read `reserved` here instead of walking the directory a second time.
 */
export function exportBankBundleDetailed(
  vault: string,
  opts: BankBundleExportOptions = {},
): BankBundleExport {
  const includeReserved = opts.includeReserved === true;
  const { rows, denied } = includeReserved
    ? collectExportRowsWithDenials(vault)
    : collectSharedExportRows(vault);
  return {
    bundle: {
      schema: BANK_BUNDLE_SCHEMA_VERSION,
      generated_at: isoSecond(),
      vault_basename: vaultDisplayName(vault),
      preferences: rows,
      // Absent-when-empty keeps a reservation-free vault's bytes exactly
      // what they always were; absent under the override because nothing
      // was withheld.
      ...(denied.length > 0 && !includeReserved ? { preferences_omitted: denied } : {}),
      graph: exportVaultGraph(vault),
      pages: projectPageContracts(vault),
      sources: aggregateSources(vault),
    },
    reserved: denied,
  };
}

/** Raised when a whole-bundle invariant fails (e.g. an unknown schema). */
export class BankImportError extends Error {
  constructor(message: string) {
    super(message);
    this.name = "BankImportError";
  }
}

export interface BankImportResult {
  readonly schema: string;
  /** Page-graph reconstruction outcome (delegated to importVaultGraph). */
  readonly graph: GraphImportResult;
  /**
   * Preference reconstruction outcome (delegated to the audited
   * transaction): what was carried, what landed, what was refused and
   * why, and which exported fields a write cannot reconstruct.
   */
  readonly preferences: PreferenceRestoreResult;
  /** Page-contract records present in the bundle but not restored (a read projection). */
  readonly pagesCarried: number;
  /** Whether the bundle carried a sources dashboard (derived; not restored). */
  readonly sourcesCarried: boolean;
}

/** Rows the preferences section carries; see the call site for the rule. */
function preferenceSection(section: unknown): ReadonlyArray<unknown> {
  if (section === undefined || section === null) return [];
  return Array.isArray(section) ? section : [section];
}

/** Loosely-typed bundle input - untrusted JSON, validated here. */
interface BankBundleInput {
  readonly schema?: unknown;
  readonly graph?: { readonly nodes?: ReadonlyArray<unknown> };
  readonly preferences?: unknown;
  readonly pages?: unknown;
  readonly sources?: unknown;
}

/**
 * Import a bank bundle: reconstruct the page graph and the preferences,
 * and report what else the bundle carried. An unsupported schema fails
 * loudly with a {@link BankImportError}; a malformed individual graph
 * node or preference row is rejected per-entry and the run continues.
 *
 * `mode` governs the PAGE graph only. Preferences are governed by their
 * revision: a bundle behind the vault, or divergent at the same
 * revision, is refused per-row. Wiring the graph's conflict mode into
 * the preference restore would add a way to discard carried rules while
 * still reporting a successful import, which is the failure this unit
 * exists to remove.
 */
export function importBankBundle(
  vault: string,
  bundle: BankBundleInput,
  opts: { mode?: GraphImportMode; agent?: string; trustedRestore?: boolean } = {},
): BankImportResult {
  if (bundle === null || typeof bundle !== "object") {
    throw new BankImportError("invalid bank bundle payload: expected an object");
  }
  if (bundle.schema !== BANK_BUNDLE_SCHEMA_VERSION) {
    throw new BankImportError(
      `unsupported bank bundle schema: expected ${BANK_BUNDLE_SCHEMA_VERSION}, got ${String(bundle.schema)}`,
    );
  }

  const graphInput = bundle.graph ?? { nodes: [] };
  const graph = importVaultGraph(vault, graphInput, { mode: opts.mode ?? "skip" });
  // An absent section carried nothing. A present section that is not an
  // array carried SOMETHING unreadable, so it travels as a single row and
  // is refused by the row guard - reporting it as zero carried rows would
  // be the same silent drop this unit removes.
  const preferenceRows = preferenceSection(bundle.preferences);
  const preferences = restorePreferences(vault, preferenceRows, {
    ...(opts.agent !== undefined ? { agent: opts.agent } : {}),
    ...(opts.trustedRestore !== undefined ? { trustedRestore: opts.trustedRestore } : {}),
  });

  return {
    schema: BANK_BUNDLE_SCHEMA_VERSION,
    graph,
    preferences,
    pagesCarried: Array.isArray(bundle.pages) ? bundle.pages.length : 0,
    sourcesCarried: bundle.sources !== undefined && bundle.sources !== null,
  };
}