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
/**
* The capacity gate: one measured-or-refused decision about whether this
* vault has room for more bytes.
*
* ## Fresh at decision time
*
* The decision RE-MEASURES the vault. The stored `storage_usage`
* aggregate is advisory - a sample taken yesterday says nothing about a
* vault an agent wrote into this morning - so a gate that decided from
* it would enforce a stale-counter lie. The forecast supplies the trend;
* the fresh census supplies the bytes the tiers compare against. A gate
* that needed no fresh bytes is an unbounded one, and it does not
* measure at all: no cap, no cost.
*
* ## Two skip lines, two callers
*
* By default only a measured `critical` tier skips - the posture the
* interactive ingest wall keeps, where `critical` is the refusal line.
* A caller may also pass `pausePercent` (`storage.pause_percent`, the
* maintenance lane's knob): any measured percent at or past that line
* then skips too, one band before the wall, so background production
* backs off while interactive ingest still works. An unmeasurable store
* leaves the gate OPEN with the refused surfaces named, exactly as the
* maintenance lane's host-pressure gate stays open when the machine
* cannot be read: refusing to work forever on a vault one directory
* cannot be listed in would be a worse failure than the gate not
* closing. Only a MEASURED breach skips.
*/
import { loadGateStorageConfig, StorageGateConfigError } from "./gate-config.ts";
import type { StorageForecastTier } from "./forecast.ts";
import { STORAGE_FORECAST_TIER, forecastStorageUsage } from "./forecast.ts";
import { measureStorageUsage, type StorageUsage } from "./usage.ts";
/** The closed decision vocabulary. */
export const CAPACITY_GATE_DECISION = Object.freeze({
run: "run",
skip: "skip",
} as const);
export type CapacityGateDecisionKind =
(typeof CAPACITY_GATE_DECISION)[keyof typeof CAPACITY_GATE_DECISION];
/** The fresh measurement the decision rests on, when one was taken. */
export interface CapacityGateReading {
readonly measuredBytes: number;
readonly capBytes: number;
readonly percentUsed: number | null;
readonly daysToCap: number | null;
readonly slopeBytesPerDay: number | null;
/** ISO-8601 stamp of the fresh census, from its injected `now`. */
readonly measuredAt: string;
}
/** One gate decision: whether to run, on which tier, on what reading. */
export interface CapacityGateDecision {
readonly decision: CapacityGateDecisionKind;
readonly tier: StorageForecastTier;
/**
* Why no number could be attached - the refused surface names, when
* the tier is `unmeasurable`. Surface names only, never paths.
*/
readonly reason?: string;
/** The fresh census behind the decision; absent for unbounded and unmeasurable. */
readonly reading?: CapacityGateReading;
/**
* The fresh census itself, when one was taken - present for
* `unmeasurable` too, because a partial census is still a census. The
* usage sampler records it instead of re-walking the vault (see
* `sampleStorageUsage`), so a decision costs one walk and never two.
*/
readonly census?: StorageUsage;
/**
* The percent-of-cap line the caller asked background work to pause
* at, when one was passed. Rides every decision it shaped - `run` as
* much as `skip` - so a report can show how far the vault stands from
* the pause line, not only the tier it measured.
*/
readonly pausePercent?: number;
}
export interface EvaluateCapacityGateOptions {
/** The configured cap in bytes, or `null`/absent for an unbounded vault. */
readonly capBytes?: number | null;
/** Threshold overrides; every one defaults to the forecast constant. */
readonly warnPercent?: number;
readonly criticalPercent?: number;
/**
* The percent-of-cap line background work pauses at. Absent, only the
* critical tier skips (the interactive ingest wall's posture); the
* maintenance lane passes the configured `storage.pause_percent`, so
* background production backs off one band before the wall.
*/
readonly pausePercent?: number;
readonly warnDays?: number;
readonly criticalDays?: number;
/** Wall clock for the fresh census's stamp; defaults to the current time. */
readonly now?: Date;
/**
* The explicit machine-config file the caller resolved from, so a
* `search_db_path` in it moves the measured store the same way it moves
* the indexer (`measureStorageUsage`'s option). Absent, the default file.
*/
readonly configPath?: string;
}
/**
* Decide whether `vault` has room, from a fresh census.
*
* Unbounded stores run without measuring. Everything else is measured
* now; a census that could not read every surface runs with the refusal
* named, and a measured critical tier is the only skip.
*/
export function evaluateCapacityGate(
vault: string,
opts: EvaluateCapacityGateOptions = {},
): CapacityGateDecision {
const capBytes = opts.capBytes ?? null;
if (capBytes === null) {
return { decision: CAPACITY_GATE_DECISION.run, tier: STORAGE_FORECAST_TIER.unbounded };
}
const fresh = measureStorageUsage(vault, {
...(opts.now !== undefined ? { now: opts.now } : {}),
...(opts.configPath !== undefined ? { configPath: opts.configPath } : {}),
});
if (!fresh.complete) {
return {
decision: CAPACITY_GATE_DECISION.run,
tier: STORAGE_FORECAST_TIER.unmeasurable,
reason: `unmeasured surfaces: ${fresh.unmeasured.map((u) => u.surface).join(", ")}`,
census: fresh,
};
}
const forecast = forecastStorageUsage(vault, {
capBytes,
latestUsage: fresh,
...(opts.warnPercent !== undefined ? { warnPercent: opts.warnPercent } : {}),
...(opts.criticalPercent !== undefined ? { criticalPercent: opts.criticalPercent } : {}),
...(opts.warnDays !== undefined ? { warnDays: opts.warnDays } : {}),
...(opts.criticalDays !== undefined ? { criticalDays: opts.criticalDays } : {}),
});
// A measured critical tier skips for every caller. A percent at or
// past the caller's pause line skips too, but only for the caller that
// asked for the band: the ingest wall (no pausePercent) keeps its
// critical-only posture.
const pauseBreached =
opts.pausePercent !== undefined &&
forecast.percentUsed !== null &&
forecast.percentUsed >= opts.pausePercent;
const decision: CapacityGateDecision = {
decision:
forecast.tier === STORAGE_FORECAST_TIER.critical || pauseBreached
? CAPACITY_GATE_DECISION.skip
: CAPACITY_GATE_DECISION.run,
tier: forecast.tier,
reading: {
measuredBytes: fresh.totalBytes,
capBytes,
percentUsed: forecast.percentUsed,
daysToCap: forecast.daysToCap,
slopeBytesPerDay: forecast.slopeBytesPerDay,
measuredAt: fresh.measuredAt,
},
census: fresh,
...(opts.pausePercent !== undefined ? { pausePercent: opts.pausePercent } : {}),
};
return decision;
}
export interface EvaluateIngestAdmissionOptions {
/** Wall clock for the fresh census; defaults to the current time. */
readonly now?: Date;
/** The explicit machine-config file; see {@link EvaluateCapacityGateOptions.configPath}. */
readonly configPath?: string;
}
/** One admission evaluation: a gate decision, or the refusal that replaces one. */
export interface IngestAdmission {
/**
* The gate decision, when a configured cap was measured. `null` means
* no measurement was taken - an unbounded vault, or a storage block the
* wall cannot see through (see {@link configRefusal}).
*/
readonly decision: CapacityGateDecision | null;
/**
* Present when the `storage:` block (or the file it sits in) cannot be
* read, parsed or validated: the wall refuses ingest, naming the field,
* exactly as `brain_ingest_source` refuses with `config_invalid`. Every
* other block is never read here, so a typo elsewhere cannot wedge the
* wall either way.
*/
readonly configRefusal?: string;
}
/**
* The write-admission check behind `brain_ingest_source`, resolved once
* for every background route that ingests - the capture inbox drain's
* source-reference route included.
*
* An unbounded vault admits (`null`: no cap, no gate, no byte walk). A
* configured cap is measured fresh, and only a MEASURED critical tier is
* the refusal - exactly the interactive wall's posture, no pause line:
* a capture an agent could not ingest by hand must not be sneaked in by
* a drain, and a capture the wall would admit must not be refused by
* one.
*
* The policy is read from the `storage:` block alone
* ({@link loadGateStorageConfig}, the reader `brain_ingest_source` uses),
* so the two walls apply one rule: a malformed unrelated block is never
* read and cannot wedge the capture inbox shut, while a storage block the
* wall cannot see through refuses ingest by name - reading it as "no cap"
* would run writes past an operator's bound.
*/
export function evaluateIngestAdmission(
vault: string,
opts: EvaluateIngestAdmissionOptions = {},
): IngestAdmission {
let storage;
try {
storage = loadGateStorageConfig(vault);
} catch (err) {
if (!(err instanceof StorageGateConfigError)) throw err;
return { decision: null, configRefusal: err.message };
}
if (storage.cap_bytes === null) return { decision: null };
return {
decision: evaluateCapacityGate(vault, {
now: opts.now ?? new Date(),
...(opts.configPath !== undefined ? { configPath: opts.configPath } : {}),
capBytes: storage.cap_bytes,
warnPercent: storage.warn_percent,
criticalPercent: storage.critical_percent,
warnDays: storage.warn_days,
criticalDays: storage.critical_days,
}),
};
}