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.8 KB
Raw Blame
/**
 * The vault a migration journal row belongs to (design D11, step 5). The
 * same legacy item can exist in two vaults: vault A and vault B each hold
 * an identical first log row at the same relative path. A row keyed only
 * by path and checksum would let B's item count as imported from A, and
 * B's tree could be bound and removed while its item has no record. So
 * every new row, and the `migrated` mark of every record it names, carries
 * the identity of the vault it came from:
 *
 *   { vault_id, path_sum }
 *
 * `vault_id` is the vault's identity marker id (null without a marker),
 * `path_sum` the SHA-256 of its real path (a hash, so the store, which
 * syncs to every device, never holds a machine's folder names). Two
 * identities name the same vault by the rule a rollback uses
 * ({@link sameVault}): the marker decides when both carry one, otherwise
 * the paths do.
 *
 * Rows and marks written before the identity existed name no vault. They
 * belong to the first vault this machine migrated, the one its migration
 * backup names (or, before this machine took a backup, the vault the run
 * imports), and never to another vault:
 *
 *  - a mark without an identity whose record carries a `vault_id` came
 *    from the vault with that marker;
 *  - otherwise it, and every journal row on disk without one, came from
 *    that first vault.
 *
 * A path is a device's own: a mark whose identity is a path alone, or no
 * identity at all, is trusted only on the device that wrote it, and only
 * for the vault at that path. Another device's mark proves a vault only by
 * a marker id ({@link markVault}). So every migration gives its vault a
 * marker before it writes a mark (`migrate.ts`); only the transition on a
 * switched machine, which writes nothing into a vault's legacy tree
 * (design D14), still writes a path-only mark for a vault with no marker.
 */

import { sha256Hex } from "../integrity/digest.ts";
import { parseJournalVault, type JournalVault } from "./migration-records.ts";

export { parseJournalVault, type JournalVault };

/** What a run needs to tell its own vault's rows from another vault's. */
export interface JournalScope {
  /** The vault the run imports. */
  readonly vault: JournalVault;
  /** This machine's device id. */
  readonly device: string;
  /** The vault a row or a mark that names none came from. */
  readonly unscoped: JournalVault;
}

/** A vault by its marker id and its real path, as a migration backup records it. */
export interface VaultByPath {
  readonly vault_id: string | null;
  readonly path: string;
}

/**
 * Whether two vault identities name the same vault: the identity marker
 * decides when both carry one (a vault moved to another path is the same
 * vault); otherwise the paths do.
 */
export function sameVault(a: VaultByPath, b: VaultByPath): boolean {
  return a.vault_id !== null && b.vault_id !== null ? a.vault_id === b.vault_id : a.path === b.path;
}

function journalVaultOf(vault: VaultByPath): JournalVault {
  return { vault_id: vault.vault_id, path_sum: sha256Hex(vault.path) };
}

/**
 * The scope of a run that imports the vault `here` on `device`, where
 * `migrated` is the vault this machine's migration backup names (null
 * before it took one). Built by `backup.ts` `journalScopeFor`.
 */
export function journalScope(
  here: VaultByPath,
  migrated: VaultByPath | null,
  device: string,
): JournalScope {
  const vault = journalVaultOf(here);
  return { vault, device, unscoped: migrated === null ? vault : journalVaultOf(migrated) };
}

/** Whether two journal identities name the same vault. */
export function sameJournalVault(a: JournalVault, b: JournalVault): boolean {
  return sameVault(
    { vault_id: a.vault_id, path: a.path_sum },
    { vault_id: b.vault_id, path: b.path_sum },
  );
}

/**
 * A path sum that only the device that wrote a mark can trust. It never
 * equals a real path sum, so a path-only comparison with it fails.
 */
function elsewhere(device: string, pathSum: string): string {
  return `\u0000${device}\u0000${pathSum}`;
}

/**
 * The vault a `migrated` mark's record came from.
 *
 * On the device that wrote it: the mark's identity, else the record's
 * `vault_id`, else the scope's first vault. From another device only a
 * marker id proves a vault: the mark's, else the record's `vault_id`.
 * Its path is that device's own, so it never matches a path here, and a
 * mark with no marker id matches no vault at all (its item is imported
 * again here rather than merged with another vault's).
 */
export function markVault(
  scope: JournalScope,
  mark: JournalVault | null,
  record: { readonly device: string; readonly body: Readonly<Record<string, unknown>> },
): JournalVault {
  const body = record.body["vault_id"];
  const bodyId = mark === null && typeof body === "string" ? body : null;
  if (record.device === scope.device) {
    if (mark !== null) return mark;
    return bodyId !== null ? { vault_id: bodyId, path_sum: "" } : scope.unscoped;
  }
  return {
    vault_id: mark?.vault_id ?? bodyId,
    path_sum: elsewhere(record.device, mark?.path_sum ?? ""),
  };
}

/**
 * Whether a dual-written copy (a record with no `migrated` mark) came from
 * the vault the run imports, so it may stand in for one of its items. A
 * dual write stamps the vault's marker id as `vault_id` when the vault
 * has one: such a copy counts only for the vault with that marker. A copy
 * without one names no vault: it counts only on the device that wrote it,
 * and only for the vault that device migrated (`scope.unscoped`, the run's
 * own vault before this machine took a backup). Anything else is imported
 * again rather than merged with another vault's item.
 */
export function dualWriteFromVault(
  scope: JournalScope,
  record: { readonly device: string; readonly body: Readonly<Record<string, unknown>> },
): boolean {
  const id = record.body["vault_id"];
  if (typeof id === "string") return scope.vault.vault_id === id;
  return record.device === scope.device && sameJournalVault(scope.vault, scope.unscoped);
}

/**
 * Whether a dual-written copy (a record with no `migrated` mark) names a
 * vault other than the one the run works on: a dual write stamped another
 * vault's marker id as `vault_id`. Such a copy is never this vault's
 * occurrence of an item. A copy that names no vault proves nothing either
 * way; the caller decides (the import imports again,
 * {@link dualWriteFromVault}; the rollback keeps its content match).
 */
export function copyNamesOtherVault(
  scope: JournalScope,
  record: { readonly body: Readonly<Record<string, unknown>> },
): boolean {
  const id = record.body["vault_id"];
  return typeof id === "string" && scope.vault.vault_id !== id;
}

/** The vault a journal row on this machine's disk came from. */
export function rowVault(scope: JournalScope, row: JournalVault | null): JournalVault {
  return row ?? scope.unscoped;
}