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
15.0 KB
Raw Blame
/**
 * Operator standing rules: `Brain/standing-rules.md`
 * (silence-is-not-an-answer, U8).
 *
 * Every other lane of the session preamble is something the agent
 * learned about itself - preferences it recorded, lessons it distilled,
 * packs it assembled. This one is the operator talking, and the whole
 * point of the file is that it outranks all of that. So it is injected
 * first, it is exempt from the adaptive injection budget, it survives a
 * memory-layer failure because it is read outside that boundary, and no
 * tool can rewrite it.
 *
 * UNEDITABILITY IS MOSTLY INHERITED, AND THE REST IS ONE NAMED GUARD.
 * The honest scope of that claim belongs here rather than in a release
 * note. `Brain/` is the machinery root that `resolveNoteTarget` refuses
 * outright, so `Brain/standing-rules.md` is un-writable through the four
 * CALLER-NAMED note-write tools - `brain_create_note`,
 * `brain_update_note`, `brain_append_note` and `brain_write_batch` - which
 * all resolve their target through that one envelope. That class is the
 * boundary the write-site census maintains, and it is the class an agent
 * can address by naming a path.
 *
 * It is not the whole class, which is why {@link
 * assertStandingRulesNotTargeted} exists. `brain_labels` also takes a
 * caller-named path, and it reaches the file through the weaker
 * `resolveNotePath`, which checks containment and symlinks only - so the
 * inherited refusal did not cover it and a label write could rewrite the
 * operator's frontmatter. The guard is deliberately NOT the Brain-root
 * refusal moved down a layer: several legitimate callers write inside
 * `Brain/` through that same resolver (marker write-back, tombstones,
 * temporal replace), so what the guard names is one file.
 *
 * Neither mechanism is a claim that no code in this process can open the
 * file for writing; a module reaching `node:fs` directly is a different
 * population, counted by that same census.
 *
 * OPERATOR BYTES ARE OPAQUE. The reader performs exactly three
 * operations on them: read, trim, and line-boundary trimming at a
 * character cap. It never splits on headings, never inspects words,
 * never classifies, and the truncation notice is assembled from integers
 * and the path alone - so a rules file written in any language is capped
 * and reported identically to one written in English. Any future word
 * list or heading split here would break that, which is why the reader
 * has no branch that reads the content at all.
 *
 * ABSENCE AND FAILURE ARE DIFFERENT ANSWERS. {@link readStandingRules}
 * returns `null` only for a file that is not there or whose trimmed body
 * is empty. Every other outcome throws, naming the path and the reason,
 * and the hook path renders {@link renderStandingRulesFailure} rather
 * than degrading to nothing in silence. A constitution that disappears
 * without a word is worse than one that was never written.
 */

import { readFileSync, realpathSync } from "node:fs";
import { basename, dirname, join, resolve, sep } from "node:path";

import { BRAIN_SCOPED_RULES_DIR, BRAIN_STANDING_RULES_FILE } from "./path-constants.ts";
import { brainDirs, brainStandingRulesPath } from "./paths.ts";
import { applySectionBudget } from "./text/text-budget.ts";

/**
 * Character cap for the standing-rules block. Generous next to the
 * default injection budget because this lane is exempt from that budget
 * and is the operator's own voice: the cap exists to stop a runaway file
 * from swallowing the context window, not to ration the operator.
 * Override via `active.standing_rules_max_chars`.
 */
export const STANDING_RULES_MAX_CHARS_DEFAULT = 4000;
export const STANDING_RULES_MAX_CHARS_MIN = 200;
export const STANDING_RULES_MAX_CHARS_MAX = 100_000;

/**
 * Budget-section key for the single section the cap operates on. The
 * body is never split, so there is exactly one, and the key never
 * reaches a rendered surface - the notice is built from integers.
 */
export const STANDING_RULES_SECTION_KEY = "standing-rules";

/**
 * The precedence sentence this project prepends to the operator's text.
 *
 * Authored here, in English, and never derived from the file: the
 * operator writes rules, not the framing that gives them force. Keeping
 * the framing ours is also what lets the block below it be treated as
 * opaque bytes - the agent is told how to weigh the text without anyone
 * having had to read it.
 */
export const STANDING_RULES_HEADER =
  "## Operator standing rules\n\n" +
  "The rules below are written by the operator of this vault. " +
  "They take precedence over every recalled preference, lesson and context pack that follows.";

/** Blank-line separator between the header, the body and the notice. */
const BLOCK_SEPARATOR = "\n\n";

/** A capped or uncapped read of the operator's standing rules. */
export interface StandingRules {
  /** Absolute path the bytes came from; named in the truncation notice. */
  readonly path: string;
  /** Operator bytes: trimmed, and cut at a line boundary when over the cap. Never reformatted. */
  readonly text: string;
  /** True when the cap removed anything. */
  readonly truncated: boolean;
  readonly keptLines: number;
  readonly totalLines: number;
  readonly keptChars: number;
  readonly totalChars: number;
}

export interface ReadStandingRulesOptions {
  /** Character cap; defaults to {@link STANDING_RULES_MAX_CHARS_DEFAULT}. */
  readonly maxChars?: number;
}

/**
 * Read `Brain/standing-rules.md`, trimmed and capped at a line boundary.
 *
 * Returns `null` for exactly two conditions: the file does not exist, or
 * its trimmed body is empty. Both mean the operator has written no rules,
 * which is a legitimate state and not a failure. Anything else - a
 * permission denial, a directory where the file should be, a read that
 * fails mid-stream - throws with the path and the reason, because the
 * caller must be able to tell "no rules" from "the rules could not be
 * read" and there is no cached substitute for a constitution.
 */
export function readStandingRules(
  vault: string,
  opts: ReadStandingRulesOptions = {},
): StandingRules | null {
  const path = brainStandingRulesPath(vault);

  // Read first and classify the failure, rather than probing with
  // `existsSync` and reading after: the probe leaves a window in which
  // the answer changes between the two syscalls, and ENOENT from the
  // read itself IS the absence the probe was looking for.
  let raw: string;
  try {
    raw = readFileSync(path, "utf8");
  } catch (err) {
    if (isFileAbsent(err)) return null;
    throw new Error(`standing rules at ${path} could not be read: ${describeError(err)}`, {
      cause: err,
    });
  }

  const trimmed = raw.trim();
  if (trimmed.length === 0) return null;

  const totalChars = trimmed.length;
  const totalLines = countLines(trimmed);
  const maxChars = opts.maxChars ?? STANDING_RULES_MAX_CHARS_DEFAULT;
  if (totalChars <= maxChars) {
    return freeze(path, trimmed, false, totalLines, totalChars, totalLines, totalChars);
  }

  // The cap goes through the shared section budgeter so the cut is the
  // same line-boundary trim the injected memory bodies get. One section,
  // so there is nothing to drop whole and nothing to reorder: the only
  // behaviour reached is the tail trim.
  //
  // No `notice` is passed. The notice belongs to the RENDER, not to the
  // capped text: `text` is the operator's own bytes and `keptChars`
  // counts them, so letting this project's prose into that string would
  // make the record describe something partly ours.
  const capped = applySectionBudget(
    [{ key: STANDING_RULES_SECTION_KEY, priority: 0, text: trimmed }],
    maxChars,
  );
  const text = capped.body;
  return freeze(path, text, true, countLines(text), text.length, totalLines, totalChars);
}

/** Refusal raised by {@link assertStandingRulesNotTargeted}. */
export class StandingRulesWriteRefusedError extends Error {
  /** Absolute path the guard protects. */
  readonly path: string;
  /** The write path that was refused, as its caller named itself. */
  readonly surface: string;
  constructor(path: string, surface: string) {
    // Scoped to this surface deliberately: the guard speaks for the write
    // path that called it, not for every write path in the process.
    super(
      `${surface} refused: ${path} is the operator's standing-rules file, which this ` +
        "surface does not rewrite",
    );
    this.name = "StandingRulesWriteRefusedError";
    this.path = path;
    this.surface = surface;
  }
}

/**
 * Refuse a write whose target is `Brain/standing-rules.md` or any path
 * inside the scoped rules directory `Brain/standing-rules/`.
 *
 * Narrow on purpose: it names one file and one directory, and it is called from the write
 * paths that resolve a caller-named path without going through the
 * note-target envelope that already refuses the whole `Brain/` root. It
 * runs before any I/O in its callers, so a refused call also performs no
 * read and no validation side effect.
 *
 * `notePath` is the caller's own vault-relative (or absolute) argument,
 * resolved here rather than taken pre-resolved, so the guard can run
 * ahead of its caller's path resolution and vocabulary checks. Both sides
 * are compared lexically and then canonically: a symlink pointing at the
 * rules file is the same target, and a symlinked vault root must not make
 * two spellings of one path look like two paths.
 */
export function assertStandingRulesNotTargeted(
  vault: string,
  notePath: string,
  surface: string,
): void {
  // Lexical joins, not the containment-checked helpers: a rules file or
  // folder symlinked out of the vault must not break unrelated writes, and
  // the canonical comparison below still refuses its own paths.
  const brainDir = brainDirs(vault).brain;
  const target = join(brainDir, BRAIN_STANDING_RULES_FILE);
  const candidate = resolve(vault, notePath);
  if (candidate === target || canonicalPath(candidate) === canonicalPath(target)) {
    throw new StandingRulesWriteRefusedError(target, surface);
  }
  // The scoped rules directory (`Brain/standing-rules/`) is operator-authored
  // too. A write usually names a file that does not exist yet, so the
  // canonical side resolves the nearest existing ancestor and re-appends the
  // missing tail: a new file under a symlinked folder is still caught. Both
  // sides go through the same resolution, so a directory that does not
  // exist yet under a symlinked vault root compares like for like.
  const scopedDir = join(brainDir, BRAIN_SCOPED_RULES_DIR);
  if (
    isSameOrInside(candidate, scopedDir) ||
    isSameOrInside(canonicalTail(candidate), canonicalTail(scopedDir))
  ) {
    throw new StandingRulesWriteRefusedError(candidate, surface);
  }
}

/**
 * The default file systems of macOS and Windows compare names without
 * case, so there `brain/Standing-Rules/x.md` names the guarded directory.
 * The native realpath returns the on-disk casing for the part that
 * exists; the fold covers the tail that does not exist yet.
 */
const FOLD_PATH_CASE = process.platform === "darwin" || process.platform === "win32";

function isSameOrInside(path: string, dir: string): boolean {
  const p = FOLD_PATH_CASE ? path.toLowerCase() : path;
  const d = FOLD_PATH_CASE ? dir.toLowerCase() : dir;
  return p === d || p.startsWith(d.endsWith(sep) ? d : d + sep);
}

/**
 * Canonical form of `path` when part of it does not exist yet: the nearest
 * existing ancestor is canonicalized and the missing tail re-appended.
 */
function canonicalTail(path: string): string {
  const missing: string[] = [];
  let current = path;
  for (;;) {
    try {
      const real = realpathSync.native(current);
      return missing.length === 0 ? real : join(real, ...missing.toReversed());
    } catch {
      const parent = dirname(current);
      if (parent === current) return path;
      missing.push(basename(current));
      current = parent;
    }
  }
}

/**
 * Canonical form of `path`, or the path itself when it cannot be
 * canonicalized. A missing file has nothing to resolve, and falling back
 * to the lexical form keeps the comparison total - the guard must never
 * fail open because one side does not exist yet.
 */
function canonicalPath(path: string): string {
  try {
    return realpathSync.native(path);
  } catch {
    return path;
  }
}

/**
 * Render the injected block: the precedence header, the operator's text,
 * and - only when the cap removed something - a notice built from
 * integers and the path.
 */
export function renderStandingRules(rules: StandingRules): string {
  const parts = [STANDING_RULES_HEADER, rules.text];
  if (rules.truncated) parts.push(renderTruncationNotice(rules));
  return parts.join(BLOCK_SEPARATOR);
}

/**
 * The block emitted in place of the rules when the read threw.
 *
 * The constitution never degrades to nothing without saying so, so this
 * names the file, names the reason, and states in one sentence that no
 * standing rules are in force for this session. An agent that sees the
 * ordinary header and no rules would reasonably conclude the operator
 * wrote none; this is what stops that conclusion being drawn from a
 * permission error.
 */
export function renderStandingRulesFailure(path: string, error: unknown): string {
  return [
    STANDING_RULES_HEADER,
    `UNAVAILABLE: ${path} could not be read (${describeError(error)}). ` +
      "No standing rules are in force this session.",
  ].join(BLOCK_SEPARATOR);
}

/**
 * The truncation notice: kept and total lines, kept and total
 * characters, and where the whole text lives.
 *
 * Integers and a path only. That is not terseness - it is what makes the
 * sentence identical whatever language the operator writes in, because
 * nothing in it is derived from the bytes that were cut.
 */
function renderTruncationNotice(rules: StandingRules): string {
  return (
    `_Standing rules truncated to the configured cap: kept ${rules.keptLines} of ` +
    `${rules.totalLines} lines, ${rules.keptChars} of ${rules.totalChars} characters. ` +
    `Read ${rules.path} for the full text._`
  );
}

function freeze(
  path: string,
  text: string,
  truncated: boolean,
  keptLines: number,
  keptChars: number,
  totalLines: number,
  totalChars: number,
): StandingRules {
  return Object.freeze({
    path,
    text,
    truncated,
    keptLines,
    totalLines,
    keptChars,
    totalChars,
  });
}

/** The one errno that means "the operator has not written this file". */
const ENOENT = "ENOENT";

function isFileAbsent(err: unknown): boolean {
  return typeof err === "object" && err !== null && (err as NodeJS.ErrnoException).code === ENOENT;
}

function describeError(err: unknown): string {
  return err instanceof Error ? err.message : String(err);
}

/**
 * Newline-delimited line count. Empty text is 0 lines; a trailing
 * newline does not add a phantom line. The body is always trimmed
 * before it gets here, so the second case is theoretical and cheap to
 * keep correct anyway.
 */
function countLines(text: string): number {
  if (text.length === 0) return 0;
  let count = 0;
  for (let i = 0; i < text.length; i++) {
    if (text.charCodeAt(i) === 0x0a) count++;
  }
  if (text.charCodeAt(text.length - 1) !== 0x0a) count++;
  return count;
}