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
4.5 KB
Raw Blame
/**
 * The vault adapter (design D14 item 8, task 2.10): the one module that
 * owns everything Obsidian-specific, active only when a vault is
 * configured.
 *
 * The brain itself lives in the store and needs no vault. What still
 * needs one is user-note territory:
 *
 *  - `.base` view files for user notes (`./bases.ts`); none queries
 *    store data.
 *  - Wikilink audits over vault pages (`./wikilink-audits.ts`).
 *  - The note tools: their vault requirement and their vault identity
 *    guard ({@link assertNoteVaultForWrite}). The store writes check the
 *    store identity instead (`../store/store-identity.ts`, D14 item 13).
 *
 * "Active" is decided here once: a non-empty vault path. Every surface
 * that needs the adapter asks {@link requireVaultAdapter} and gets the
 * same `vault_required` refusal when there is none, so a machine with no
 * vault refuses note work cleanly instead of failing somewhere deep.
 */

import { assertVaultIdentityForWrite, vaultMarkerAbsentNotice } from "../brain/vault-identity.ts";
import type { DegradationNotice } from "../integrity/degradation.ts";
import { storeOnlyMode } from "../store/store-only.ts";
import { VAULT_ADAPTER_REQUIRED_CODE } from "./codes.ts";
import {
  assertVaultBindingForWrite,
  VaultBindingMismatchError,
  vaultBindingStatus,
} from "./vault-binding.ts";

export { VAULT_ADAPTER_REQUIRED_CODE } from "./codes.ts";

/** A vault-adapter feature was asked for on a machine with no vault. */
export class VaultAdapterRequiredError extends Error {
  readonly code = VAULT_ADAPTER_REQUIRED_CODE;
  constructor(readonly feature: string) {
    super(
      `${feature} needs a vault: it works on Obsidian notes, and no vault is configured. ` +
        "Run `o2b init --vault <path>` to use one; the brain itself works without it.",
    );
    this.name = "VaultAdapterRequiredError";
  }
}

/** Whether the vault adapter is active for `vault`: a vault is configured. */
export function vaultAdapterActive(vault: string | null | undefined): vault is string {
  return typeof vault === "string" && vault.trim() !== "";
}

/** The vault, or a {@link VaultAdapterRequiredError} naming `feature`. */
export function requireVaultAdapter(vault: string | null | undefined, feature: string): string {
  if (!vaultAdapterActive(vault)) throw new VaultAdapterRequiredError(feature);
  return vault;
}

/**
 * The note tools' write guard: a vault is required, and it must be the
 * vault this machine uses.
 *
 *  - The vault of an unswitched machine (one with a `Brain/` tree) keeps
 *    the vault identity guard: the `Brain/vault-id.json` marker pinned for
 *    this process, and the freeze marker on the content lane. A tree with
 *    no readable marker proves nothing about which vault it is, so such a
 *    vault is also compared against the binding; a binding file that
 *    cannot be read refuses nothing there (it is store-only state, and the
 *    marker notice already reports the missing marker), so an unswitched
 *    machine is never refused for a file it does not use.
 *  - The vault of a store-only machine (switched, its legacy tree kept or
 *    removed, or a vault with no tree) is compared against the vault bound
 *    to the store in the device-local state (`./vault-binding.ts`), and a
 *    swapped vault is refused. The freeze and migration gates of the
 *    identity guard still run; the absent marker is not reported, since a
 *    store-only vault needs none.
 */
export function assertNoteVaultForWrite(
  vault: string | null | undefined,
  feature: string,
  sink?: DegradationNotice[],
): string {
  const root = requireVaultAdapter(vault, feature);
  if (!storeOnlyMode({ vault: root }).storeOnly) {
    assertVaultIdentityForWrite(root, sink);
    if (vaultMarkerAbsentNotice(root) !== null) {
      const status = vaultBindingStatus(root);
      if (status.state === "mismatch") {
        throw new VaultBindingMismatchError(root, status.detail, status.reason);
      }
    }
    return root;
  }
  assertVaultIdentityForWrite(root);
  assertVaultBindingForWrite(root);
  return root;
}

export {
  BASE_TEMPLATES,
  BASES_TEMPLATE_DIR,
  basesFor,
  stampBaseTemplates,
  type BaseTemplate,
  type BaseStampResult,
} from "./bases.ts";
export { WIKILINK_AUDIT, type WikilinkAudit } from "./wikilink-audits.ts";
export {
  assertVaultBindingForWrite,
  bindVaultToStore,
  vaultBindingStatus,
  VAULT_BINDING_MISMATCH_CODE,
  VaultBindingMismatchError,
  VaultBindingsUnreadableError,
  type VaultBinding,
  type VaultBindingStatus,
} from "./vault-binding.ts";