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.1 KB
Raw Blame
import { existsSync, mkdirSync, readFileSync } from "node:fs";
import { dirname, join } from "node:path";

import { atomicWriteFileSync } from "../fs-atomic.ts";
import { BRAIN_ROOT_REL } from "./paths.ts";
import { assertVaultIdentityForWrite } from "./vault-identity.ts";
import { isMachineStateRelocated, machineStatePath } from "../state/machine-state.ts";

export interface HostMemoryPromotionEntry {
  readonly pref_id: string;
  readonly sha256: string;
  readonly promoted_at: string;
}

export interface HostMemoryPromotionsManifest {
  readonly version: 1;
  readonly promotions: Readonly<Record<string, HostMemoryPromotionEntry>>;
}

/**
 * What a load observed about the sidecar. `corrupt` is true when the file
 * exists but could not be read as the manifest shape - truncated mid-run,
 * hand-edited to a non-object, an array where the map belongs. The load
 * still hands back the empty shape (the promotion planner needs SOMETHING
 * to plan against), but the flag rides along so a dry run can say the
 * plan was computed blind and an apply can refuse rather than save the
 * empty set over a file that was mostly recoverable.
 */
export interface LoadedPromotionsManifest extends HostMemoryPromotionsManifest {
  readonly corrupt: boolean;
}

const MANIFEST_SEGMENTS = [BRAIN_ROOT_REL, ".imports", "host-memory-promotions.json"] as const;

/** The manifest: in the vault, or in the device-local state once switched (D14). */
function manifestPath(vault: string): string {
  return machineStatePath(vault, ...MANIFEST_SEGMENTS);
}

/**
 * The file a load reads: the manifest, or on a switched machine that has
 * not saved one yet, the copy the legacy tree still holds (read only), so
 * the promotion history survives the switch.
 */
function manifestReadPath(vault: string): string {
  const p = manifestPath(vault);
  if (existsSync(p)) return p;
  const legacy = join(vault, ...MANIFEST_SEGMENTS);
  return existsSync(legacy) ? legacy : p;
}

/**
 * Load the promotion-history sidecar for continuity host-memory writes.
 * Treats a missing file as "empty manifest" - first-time promotions rely
 * on this. Type-validates the parsed `promotions` field defensively: a
 * malformed file (hand-edited to non-object, truncated, etc.) returns the
 * empty shape rather than propagating an unknown blob into the rest of
 * the promotion pipeline, with `corrupt` set so the verb can surface the
 * state instead of silently planning against a history it lost.
 *
 * Structure mirrors `claude-memory-manifest.ts` (the import-history
 * sidecar) deliberately: both sidecars answer "which source rows already
 * landed as which preference, under which content hash", so a promotion
 * plans CREATE/UPDATE/RECREATE/SKIP_UNCHANGED/CONFLICT with the same
 * semantics an import plans them. The manifest KEY is the continuity
 * record id, which - unlike a memory file basename - is unique per row
 * by construction.
 */
export function loadPromotionsManifest(vault: string): LoadedPromotionsManifest {
  const p = manifestReadPath(vault);
  if (!existsSync(p)) return { version: 1, promotions: {}, corrupt: false };
  let raw: unknown;
  try {
    raw = JSON.parse(readFileSync(p, "utf8"));
  } catch {
    return { version: 1, promotions: {}, corrupt: true };
  }
  if (
    raw === null ||
    typeof raw !== "object" ||
    typeof (raw as { promotions?: unknown }).promotions !== "object" ||
    (raw as { promotions?: unknown }).promotions === null ||
    Array.isArray((raw as { promotions?: unknown }).promotions)
  ) {
    return { version: 1, promotions: {}, corrupt: true };
  }
  return {
    version: 1,
    promotions: (raw as { promotions: Record<string, HostMemoryPromotionEntry> }).promotions,
    corrupt: false,
  };
}

export function savePromotionsManifest(vault: string, m: HostMemoryPromotionsManifest): void {
  const p = manifestPath(vault);
  // Vault-identity write guard (context-integrity-gates, Unit J), for a
  // manifest in the vault; the device-local one writes nothing there.
  if (!isMachineStateRelocated(vault)) assertVaultIdentityForWrite(vault);
  mkdirSync(dirname(p), { recursive: true });
  atomicWriteFileSync(p, JSON.stringify(m, null, 2) + "\n");
}