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
/**
* Host pressure, measured honestly or refused by name (t_992f0c33).
*
* The quiet-window lane already gates heavy work on a measured pressure
* signal - interactive query rate. This module supplies the second one:
* how loaded the MACHINE is, normalised so a threshold means the same
* thing on a laptop and on a build box.
*
* ## Why this is mostly refusals
*
* `os.loadavg()` is the only dependency-free run-queue reading available,
* and it does not mean what its name suggests everywhere:
*
* - on the platform Node and Bun do not implement it for, it returns
* `[0, 0, 0]` - a constant, not a measurement, and indistinguishable
* from a genuinely idle host;
* - inside a cgroup with a CPU BANDWIDTH quota it still reports the
* whole host's run queue, while the denominator this module divides
* by is the CPU count the process may be scheduled on. A quota bounds
* how much CPU TIME the cgroup may consume without changing that
* count, so the ratio would be computed from two numbers that do not
* describe the same machine.
*
* Whether that second case holds is asked of the cgroup this process is
* actually in - `/proc/self/cgroup` and every ancestor of the path it
* names - never of the hierarchy root, which under cgroup v2 carries no
* `cpu.max` at all. {@link probeCpuQuota} says what each answer rests on.
*
* A gate that answered "idle" in either case would be the silent no-op
* this project forbids: it would read exactly like a quiet host, and the
* operator would have no way to tell that the gate never evaluated. So
* the reading is a two-state value - a number, or a named reason there is
* no number - following the precedent of
* `UnsupportedPlatformError` in `src/core/config.ts`, which refuses to
* invent a Windows config path rather than return "a plausible-looking
* answer to a question this build cannot answer".
*
* The caller decides what to do with a refusal. The lane leaves its gate
* OPEN and journals the reason, because refusing to maintain a vault
* forever on a platform where the metric does not exist would be a worse
* failure than not having the gate at all.
*/
import { availableParallelism, loadavg, platform } from "node:os";
import { readFileSync } from "node:fs";
import { join } from "node:path";
/**
* Platforms whose load average is a constant rather than a measurement.
* Named rather than inferred, exactly as `UNSUPPORTED_CONFIG_PLATFORMS`
* is: which platforms report a real run queue is a fact about the
* runtime, not something to discover by seeing whether the number moves.
*
* This is reachable rather than theoretical. `UNSUPPORTED_CONFIG_PLATFORMS`
* does not refuse win32 outright - `resolveDefaultConfigPath` bows out of
* the `$HOME/.config` CONVENTION there and says so, leaving
* `OPEN_SECOND_BRAIN_CONFIG` and `XDG_CONFIG_HOME` as two working ways to
* run this build on Windows - so a maintenance lane can and does reach
* this refusal on a real host.
*/
const LOAD_AVERAGE_BLIND_PLATFORMS: ReadonlyArray<string> = Object.freeze(["win32"]);
/** cgroup v2 CPU bandwidth interface file: `"<quota|max> <period>"`. */
const CGROUP_V2_CPU_MAX = "cpu.max";
/** cgroup v1 CPU bandwidth interface file: microseconds, or `-1` for none. */
const CGROUP_V1_CPU_QUOTA = "cpu.cfs_quota_us";
/** The cgroup v2 token meaning "no bandwidth limit". */
const CGROUP_V2_UNLIMITED = "max";
/** The v1 controller whose quota this asks about. */
const CGROUP_V1_CPU_CONTROLLER = "cpu";
/** The only platform with a cgroup hierarchy to consult. */
const CGROUP_PLATFORM = "linux";
/** Whether a pressure reading is a number or a named absence. */
export const HOST_PRESSURE = Object.freeze({
/** A normalised percentage of this host's usable capacity. */
measured: "measured",
/** No number: the accompanying reason says which question failed. */
unmeasurable: "unmeasurable",
});
export const HOST_PRESSURE_STATES: ReadonlyArray<string> = Object.freeze(
Object.values(HOST_PRESSURE),
);
export type HostPressureState = (typeof HOST_PRESSURE)[keyof typeof HOST_PRESSURE];
export function isHostPressureState(value: unknown): value is HostPressureState {
return typeof value === "string" && HOST_PRESSURE_STATES.includes(value);
}
/**
* Why no pressure number could be produced.
*
* Separate from the state for the reason every `*_UNDETERMINED_REASON`
* vocabulary in this repository is separate from its verdict: one guard
* over both would let `cpu_quota_in_force` be read back off a journal row
* where a load percentage belongs.
*/
export const HOST_PRESSURE_UNMEASURABLE_REASON = Object.freeze({
/** This platform's load average is a constant, not a run queue. */
platformBlind: "platform_blind",
/** A CPU bandwidth quota applies: the run queue is the host's, not ours. */
cpuQuotaInForce: "cpu_quota_in_force",
/**
* The quota question could not be answered: the interface exists and
* refused to be read, its contents did not parse, or which cgroup this
* process belongs to could not be established. Neither answer is
* provable, and `false` would be the one that lets a wrong number out.
*/
cpuQuotaUnknown: "cpu_quota_unknown",
/** No usable CPU count to normalise the run queue by. */
parallelismUnknown: "parallelism_unknown",
/** The run-queue reading itself is not a finite, non-negative number. */
loadAverageInvalid: "load_average_invalid",
});
export const HOST_PRESSURE_UNMEASURABLE_REASONS: ReadonlyArray<string> = Object.freeze(
Object.values(HOST_PRESSURE_UNMEASURABLE_REASON),
);
export type HostPressureUnmeasurableReason =
(typeof HOST_PRESSURE_UNMEASURABLE_REASON)[keyof typeof HOST_PRESSURE_UNMEASURABLE_REASON];
export function isHostPressureUnmeasurableReason(
value: unknown,
): value is HostPressureUnmeasurableReason {
return typeof value === "string" && HOST_PRESSURE_UNMEASURABLE_REASONS.includes(value);
}
/**
* The raw facts a reading is computed from, gathered in one place so the
* arithmetic and the refusal rules can be tested without a machine that
* happens to be loaded, containerised, or running Windows.
*/
export interface HostPressureProbe {
/** `process.platform`. */
readonly platform: string;
/** One-minute run-queue average, as the platform reports it. */
readonly loadAverage1m: number;
/** CPUs this process may be scheduled on. */
readonly cpuCount: number;
/**
* Whether a CPU bandwidth limit applies: `true` a limit was read off
* this process's own cgroup or one of its ancestors, `false` every
* interface on that chain declares none (or this platform has no such
* controller at all), `null` the question could not be answered - see
* {@link probeCpuQuota} for the three ways that happens.
*/
readonly cpuQuotaInForce: boolean | null;
}
export interface HostPressureMeasured {
readonly state: typeof HOST_PRESSURE.measured;
/** Run queue as a percentage of usable capacity; 100 means fully subscribed. */
readonly percent: number;
readonly load_average_1m: number;
readonly cpu_count: number;
}
export interface HostPressureUnmeasurable {
readonly state: typeof HOST_PRESSURE.unmeasurable;
readonly reason: HostPressureUnmeasurableReason;
}
export type HostPressureReading = HostPressureMeasured | HostPressureUnmeasurable;
function unmeasurable(reason: HostPressureUnmeasurableReason): HostPressureUnmeasurable {
return { state: HOST_PRESSURE.unmeasurable, reason };
}
/**
* Where the quota probe reads from.
*
* Two absolute paths and a platform, injected rather than hardcoded, so
* the walk below can be driven over a real directory tree with real
* permissions - including a `cpu.max` that exists and refuses to be read,
* which is the case this module got wrong and which no amount of
* arithmetic-level testing could have reached.
*/
export interface CgroupSource {
/** `process.platform`. */
readonly platform: string;
/** File naming the cgroups this process belongs to; `/proc/self/cgroup`. */
readonly selfCgroupPath: string;
/** Mount root of the cgroup hierarchy; `/sys/fs/cgroup`. */
readonly cgroupRoot: string;
}
/** What one read of a cgroup interface file found. */
type InterfaceRead =
| { readonly kind: "text"; readonly text: string }
/** No such file. Says nothing about any other cgroup in the chain. */
| { readonly kind: "absent" }
/** The file is there and this process may not read it. */
| { readonly kind: "unreadable"; readonly detail: string };
/**
* Read one file, keeping ABSENT and UNREADABLE apart.
*
* They used to be one `null`, under a comment claiming the caller told
* them apart - which it did not, so an `EACCES` on an existing `cpu.max`
* (a restricted `/sys` mount, a hardened runtime) was reported as "no
* quota in force". They are two different facts here because the walk
* below does two different things with them: an absent interface means
* keep looking up the chain, an unreadable one means stop and say so.
*/
function readInterface(path: string): InterfaceRead {
try {
return { kind: "text", text: readFileSync(path, "utf8") };
} catch (err) {
const code = (err as NodeJS.ErrnoException).code;
if (code === "ENOENT" || code === "ENOTDIR" || code === "EISDIR") return { kind: "absent" };
return { kind: "unreadable", detail: err instanceof Error ? err.message : String(err) };
}
}
/** Which cgroups this process is in, as `/proc/self/cgroup` reports them. */
interface CgroupMembership {
/** The unified (v2) path, e.g. `/user.slice/session-9.scope`, or `null`. */
readonly v2Path: string | null;
/** The v1 `cpu` controller's mount name and path, or `null`. */
readonly v1: { readonly controllers: string; readonly path: string } | null;
}
/**
* Parse `/proc/self/cgroup`.
*
* Every line is `<hierarchy-id>:<controllers>:<path>`. The unified
* hierarchy is the line with id `0` and an empty controller list; a v1
* hierarchy is any line whose comma-separated controller list contains
* `cpu`. A hybrid host has both, and the v2 line is preferred because a
* quota expressed there is the one the kernel enforces.
*/
function parseSelfCgroup(text: string): CgroupMembership {
let v2Path: string | null = null;
let v1: CgroupMembership["v1"] = null;
for (const raw of text.split("\n")) {
const line = raw.trim();
if (line === "") continue;
const first = line.indexOf(":");
const second = line.indexOf(":", first + 1);
if (first < 0 || second < 0) continue;
const id = line.slice(0, first);
const controllers = line.slice(first + 1, second);
const path = line.slice(second + 1);
if (id === "0" && controllers === "") {
v2Path = path;
continue;
}
if (controllers.split(",").includes(CGROUP_V1_CPU_CONTROLLER)) v1 = { controllers, path };
}
return { v2Path, v1 };
}
/**
* Every cgroup directory from the named one up to the mount root.
*
* The effective bandwidth limit is the MINIMUM over the whole ancestor
* chain, so a quota on `user.slice` binds a process in
* `user.slice/session-9.scope` exactly as one on the leaf does. Reading a
* single directory would answer for one link of that chain.
*/
function ancestorDirs(root: string, path: string): string[] {
const parts = path.split("/").filter((p) => p !== "");
const dirs: string[] = [];
for (let i = parts.length; i >= 0; i--) dirs.push(join(root, ...parts.slice(0, i)));
return dirs;
}
/** How one interface file's contents answered, or that it did not. */
type QuotaVerdict = "in_force" | "unlimited" | "unparseable";
/** `"<quota|max> <period>"`. */
function parseV2Quota(text: string): QuotaVerdict {
const token = text.split("\n", 1)[0]?.trim().split(/\s+/)[0];
if (token === undefined || token === "") return "unparseable";
return token === CGROUP_V2_UNLIMITED ? "unlimited" : "in_force";
}
/** Microseconds per period, or `-1` for "no limit". */
function parseV1Quota(text: string): QuotaVerdict {
const first = text.split("\n", 1)[0]?.trim() ?? "";
const quota = Number(first);
if (first === "" || !Number.isFinite(quota)) return "unparseable";
return quota > 0 ? "in_force" : "unlimited";
}
/**
* What one hierarchy had to say.
*
* `unknown` and `no_interface` are separate members for the reason this
* whole module exists: a file that refused to be read and a controller
* that is not enabled are different facts, and collapsing them is what
* turned an `EACCES` into "no quota in force".
*/
type ChainAnswer = "in_force" | "unlimited" | "unknown" | "no_interface";
/**
* Walk one chain of cgroup directories, leaf first, looking for a
* bandwidth limit. An absent interface on one link says nothing about the
* next, so the walk continues; an unreadable or unparseable one stops it.
*/
function walkChain(
dirs: ReadonlyArray<string>,
file: string,
parse: (text: string) => QuotaVerdict,
): ChainAnswer {
let sawInterface = false;
for (const dir of dirs) {
const read = readInterface(join(dir, file));
if (read.kind === "absent") continue;
if (read.kind === "unreadable") return "unknown";
sawInterface = true;
const verdict = parse(read.text);
if (verdict === "in_force") return "in_force";
if (verdict === "unparseable") return "unknown";
}
return sawInterface ? "unlimited" : "no_interface";
}
/** The three answers a walked chain maps onto, or `undefined` to keep looking. */
function fromChain(answer: ChainAnswer): boolean | null | undefined {
if (answer === "in_force") return true;
if (answer === "unlimited") return false;
if (answer === "unknown") return null;
return undefined;
}
/**
* Whether a CPU bandwidth quota applies to this process.
*
* `true` a limit is in force, `false` there is provably none, `null` the
* question could not be answered - and that third value is not a
* formality. This used to read `/sys/fs/cgroup/cpu.max` and nothing else.
* Under cgroup v2 the ROOT cgroup carries no `cpu.max`: the file exists on
* every child and never on the root, so the read missed on every v2 host,
* fell through to a v1 path that does not exist there either, and returned
* `false` - "no bandwidth controller" - about a process that might be
* inside a `CPUQuota=50%` unit. `measureHostPressure` then divided the
* HOST's run queue by a CPU count the process may not have, which is the
* confident-number-over-a-degenerate-metric this module opens by
* forbidding.
*
* So the cgroup this process is actually in is read from
* `/proc/self/cgroup` first, and the interface is looked up on it and on
* every ancestor, because the effective limit is the minimum over the
* chain.
*
* The three refusals, each its own answer rather than a shrug:
*
* - `/proc/self/cgroup` unreadable, or naming no hierarchy this build
* understands: which cgroup governs this process is unknown, so
* nothing may be claimed about its quota.
* - an interface file that exists and refuses to be read, or whose
* contents do not parse.
* - on Linux, a chain on which no interface file exists at all: the
* cpu controller is not enabled here, and no bandwidth limit can be
* applied through a controller that is not there - `false`.
*
* A platform with no cgroups at all (macOS) is `false` for the same
* reason and not `null`: the question is answerable there and the answer
* is that there is no such controller.
*/
export function probeCpuQuota(src: CgroupSource = liveCgroupSource()): boolean | null {
if (src.platform !== CGROUP_PLATFORM) return false;
const self = readInterface(src.selfCgroupPath);
if (self.kind !== "text") return null;
const membership = parseSelfCgroup(self.text);
if (membership.v2Path !== null) {
const answer = fromChain(
walkChain(ancestorDirs(src.cgroupRoot, membership.v2Path), CGROUP_V2_CPU_MAX, parseV2Quota),
);
// Answered - including "unknown" - it is the answer. Only
// `no_interface` falls through, and only to a v1 hierarchy this
// process was also told it belongs to (the hybrid layout).
if (answer !== undefined) return answer;
if (membership.v1 === null) return false;
}
if (membership.v1 === null) return null;
// The v1 cpu controller is mounted under its controller list
// (`cpu,cpuacct` on most hosts) or under the bare controller name.
const mounts = [membership.v1.controllers, CGROUP_V1_CPU_CONTROLLER].filter(
(m, i, all) => all.indexOf(m) === i,
);
for (const mount of mounts) {
const answer = fromChain(
walkChain(
ancestorDirs(join(src.cgroupRoot, mount), membership.v1.path),
CGROUP_V1_CPU_QUOTA,
parseV1Quota,
),
);
if (answer !== undefined) return answer;
}
// Named a cpu hierarchy and found no interface under either mount: the
// controller is not enabled where this build can see it.
return false;
}
/** The live paths, read at call time so a test never has to patch a module. */
export function liveCgroupSource(): CgroupSource {
return {
platform: platform(),
selfCgroupPath: "/proc/self/cgroup",
cgroupRoot: "/sys/fs/cgroup",
};
}
/**
* Everything {@link readHostPressureProbe} reads, in one injectable
* record.
*
* The three runtime readings are functions rather than values because
* two of them are syscalls that a runtime may not implement, and this
* module's whole argument is that an unavailable reading must arrive as a
* named refusal rather than as a plausible number or a thrown error.
*/
export interface HostPressureIo extends CgroupSource {
/** `os.loadavg()`. */
readonly loadAverage: () => ReadonlyArray<number>;
/** `os.availableParallelism()`. */
readonly cpuCount: () => number;
}
export const LIVE_HOST_PRESSURE_IO: HostPressureIo = Object.freeze({
...liveCgroupSource(),
platform: platform(),
loadAverage: () => loadavg(),
cpuCount: () => availableParallelism(),
});
/**
* Gather the live facts.
*
* `platform` is a property read that cannot fail. The other two are
* syscall-backed (`uv_loadavg`, `uv_available_parallelism`) and a runtime
* that does not implement one throws rather than returning a wrong
* number - so each is caught and turned into the value
* {@link measureHostPressure} already names: `NaN` is
* `load_average_invalid`, a non-count is `parallelism_unknown`. That is
* why this function does not throw: not because the reads cannot fail,
* but because a failure has somewhere honest to go.
*/
export function readHostPressureProbe(
io: HostPressureIo = LIVE_HOST_PRESSURE_IO,
): HostPressureProbe {
let loadAverage1m: number;
try {
loadAverage1m = io.loadAverage()[0] ?? Number.NaN;
} catch {
loadAverage1m = Number.NaN;
}
let cpuCount: number;
try {
cpuCount = io.cpuCount();
} catch {
cpuCount = Number.NaN;
}
return {
platform: io.platform,
loadAverage1m,
cpuCount,
cpuQuotaInForce: probeCpuQuota(io),
};
}
/**
* Turn a probe into a reading: a normalised percentage, or the named
* reason there is no number. The refusals are checked before the
* arithmetic, because every one of them would otherwise produce a
* plausible number from an implausible input.
*/
export function measureHostPressure(
probe: HostPressureProbe = readHostPressureProbe(),
): HostPressureReading {
if (LOAD_AVERAGE_BLIND_PLATFORMS.includes(probe.platform)) {
return unmeasurable(HOST_PRESSURE_UNMEASURABLE_REASON.platformBlind);
}
if (probe.cpuQuotaInForce === null) {
return unmeasurable(HOST_PRESSURE_UNMEASURABLE_REASON.cpuQuotaUnknown);
}
if (probe.cpuQuotaInForce) {
return unmeasurable(HOST_PRESSURE_UNMEASURABLE_REASON.cpuQuotaInForce);
}
if (!Number.isInteger(probe.cpuCount) || probe.cpuCount < 1) {
return unmeasurable(HOST_PRESSURE_UNMEASURABLE_REASON.parallelismUnknown);
}
if (!Number.isFinite(probe.loadAverage1m) || probe.loadAverage1m < 0) {
return unmeasurable(HOST_PRESSURE_UNMEASURABLE_REASON.loadAverageInvalid);
}
return {
state: HOST_PRESSURE.measured,
percent: (probe.loadAverage1m / probe.cpuCount) * 100,
load_average_1m: probe.loadAverage1m,
cpu_count: probe.cpuCount,
};
}