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.4 KB
Raw Blame
/**
 * Fail-open context load for lifecycle-hook injection.
 *
 * When session-start context assembly overruns or throws (a slow embedding,
 * a stuck reindex, a filesystem stall), the inject path must degrade to the
 * last-good context or an empty context - never error noisily and never emit
 * a partial or poisoned payload. This module wraps an assembler with that
 * guarantee and keeps a durable last-good snapshot under the machine-local
 * `.open-second-brain/inject-cache/` directory.
 *
 * A successful non-empty assembly is written to the cache. A legitimately
 * empty assembly (nothing to inject this session) is NOT cached, so it never
 * clobbers a good snapshot a later error would degrade to. Only a thrown
 * assembly degrades, and it audits exactly once.
 *
 * The cache directory sits inside the vault, so a symbolic link on the way
 * to it (`.open-second-brain` or `inject-cache`) is refused: nothing is read
 * from or written through it, and a cache file that is itself a link is not
 * followed (see `derived-store-guard.ts`).
 */

import { join } from "node:path";

import { derivedDirIsSymlinked, readRegularFileNoFollow } from "../derived-store-guard.ts";
import { atomicWriteText } from "../fs-atomic.ts";
import { machineStateRoot } from "../state/machine-state.ts";

const INJECT_CACHE_DIR = ".open-second-brain";
const INJECT_CACHE_SUBDIR = "inject-cache";

/**
 * The cache directory's root: the vault, or the device-local state once
 * switched (`state/machine-state.ts`). Resolved once per call and inside a
 * catch, so a fault resolving it costs the cache, never the inject path.
 */
function cacheRoot(vault: string): string | null {
  try {
    return machineStateRoot(vault);
  } catch {
    return null;
  }
}

/**
 * Read the last-good injected body for `key`, or null when none, unreadable,
 * not a regular file, or behind a symlinked cache directory.
 */
export function readInjectCache(vault: string, key: string): string | null {
  const root = cacheRoot(vault);
  if (root === null || derivedDirIsSymlinked(root, INJECT_CACHE_DIR, INJECT_CACHE_SUBDIR)) {
    return null;
  }
  const read = readRegularFileNoFollow(
    join(root, INJECT_CACHE_DIR, INJECT_CACHE_SUBDIR, `${key}.txt`),
  );
  return read.status === "ok" ? read.text : null;
}

/**
 * Persist a last-good injected body with mode 0600. Best-effort: a write
 * failure is swallowed, and a symlinked cache directory skips the write.
 */
export function writeInjectCache(vault: string, key: string, body: string): void {
  try {
    const root = cacheRoot(vault);
    if (root === null || derivedDirIsSymlinked(root, INJECT_CACHE_DIR, INJECT_CACHE_SUBDIR)) return;
    atomicWriteText(join(root, INJECT_CACHE_DIR, INJECT_CACHE_SUBDIR, `${key}.txt`), body, {
      mode: 0o600,
    });
  } catch {
    // The cache is an optimization; a failure to persist must never disturb
    // the inject path.
  }
}

/** Where a degrade landed: a fresh assembly, the cached last-good, or empty. */
export type InjectContextSource = "fresh" | "cached" | "empty";

export interface FailOpenResult {
  readonly context: string;
  readonly degraded: boolean;
  readonly source: InjectContextSource;
}

export interface LoadInjectContextOptions {
  readonly vault: string;
  /** Cache key (e.g. the hook/surface name). */
  readonly key: string;
  /** Assembles the injected context. May be sync or async; may throw. */
  readonly assemble: () => string | Promise<string>;
  /** Called once when the load degrades (source: cached | empty). */
  readonly audit?: (source: Exclude<InjectContextSource, "fresh">, error: unknown) => void;
}

/**
 * Run `assemble` fail-open. On success return the assembled context (caching
 * it when non-empty). On any throw degrade to the last-good cache, or to empty
 * when no cache exists, auditing the degrade once.
 */
export async function loadInjectContextFailOpen(
  opts: LoadInjectContextOptions,
): Promise<FailOpenResult> {
  try {
    const context = await opts.assemble();
    if (context.length > 0) {
      writeInjectCache(opts.vault, opts.key, context);
    }
    return { context, degraded: false, source: "fresh" };
  } catch (error) {
    const cached = readInjectCache(opts.vault, opts.key);
    if (cached !== null && cached.length > 0) {
      opts.audit?.("cached", error);
      return { context: cached, degraded: true, source: "cached" };
    }
    opts.audit?.("empty", error);
    return { context: "", degraded: true, source: "empty" };
  }
}