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 write binding — a config-declared boundary over CALLER-NAMED
* write destinations (provenance-at-the-boundary, unit B).
*
* ## What this is, said precisely
*
* It is a WRITE BOUNDARY over the paths a caller names. It is NOT a
* security boundary and it is NOT per-credential, and neither wording
* belongs on any surface that reports it.
*
* There is no credential in this system to key a fence to. Agent
* identity resolves as `VAULT_AGENT_NAME`, else the config `agent_name`,
* else the literal `agent`, and twenty-five MCP tool schemas
* additionally accept a caller-supplied `agent` string that overrides
* it, taken verbatim after a placeholder check. (That count is pinned as
* an equality by `tests/core/architecture/origin-channel-census.test.ts`,
* which measures it with `grep -rn '^\s*agent:\s*{' src/mcp/` - it used
* to be a number kept here by hand, and this docblock still said
* twenty-two after it had reached twenty-five. Understating it
* understates this argument.) A caller who can call the tool can
* name itself anything, so a fence keyed to that name is bypassed by
* passing a different string. The binding therefore reads NO identity at
* all: its whole authority is `<vault>/Brain/_brain.yaml`, which the
* operator controls and which no MCP call can rewrite.
*
* ## What it covers, and what it cannot
*
* Write destinations in this codebase split three ways, and only the
* first admits a prefix boundary:
*
* - CALLER-NAMED — `brain_create_note`, `brain_update_note`,
* `brain_append_note` and `brain_write_batch` take a vault-relative
* path from the caller. All four resolve it through one shared
* envelope (`resolveNoteTarget`), which is where this check runs.
* - SLUG-DERIVED — a signal, a preference, a dead end: the caller
* supplies a topic and the writer derives the filename.
* - FULLY DERIVED — daily logs, dream runs, continuity records and all
* telemetry compute their own destination.
*
* A prefix boundary over the last two could only refuse them wholesale,
* which is an off switch rather than a boundary, so they are out of
* scope and said so. `tests/core/architecture/write-site-census.test.ts`
* is the standing record of every in-vault write site this does not
* cover, so the gap is an asserted fact rather than a silent one.
*
* ## Absent is inert
*
* No block, or a block without `path_prefixes`, means no binding: every
* write path behaves exactly as it did before the key existed, and
* `tests/core/write-binding.test.ts` proves it by running all three
* caller-named arms against a vault with no config and a vault whose
* config omits the block and comparing the bytes.
*
* Inert means inert on the FAILURE paths too. A vault whose
* `Brain/_brain.yaml` exists but does not validate raises here, and that
* is not a new failure mode the binding introduced: the same shared
* envelope already resolves the vault scope through the same loader one
* step earlier, so a malformed config has always stopped every
* caller-named write. What the envelope now guarantees is that the stop
* is a TYPED refusal naming a vault-relative source and a registered
* exit, on the binding arm and the scope arm alike.
*
* ## What the binding compares
*
* The REALPATH, not the name. A lexical comparison is not a boundary: one
* symlinked directory under a declared prefix
* (`Projects/link -> <vault>/Journal`) would turn `path_prefixes:
* [Projects]` into "may write anywhere in the vault", and the success
* payload would name a path that does not hold the bytes. Every check
* therefore resolves the destination through the filesystem and requires
* BOTH the name the caller gave and the place it resolves to to lie
* under a declared prefix.
*/
import { realpathSync, statSync } from "node:fs";
import { relative, resolve } from "node:path";
import {
BRAIN_PAGE_LANES_REL,
BRAIN_ROOT_REL,
brainConfigPath,
isInBrainLane,
isUnderBrainRoot,
} from "../brain/paths.ts";
import { requireNextStep } from "../brain/next-step.ts";
import { loadBrainConfig } from "../brain/policy.ts";
import { brainSettingsFromStore } from "../brain/policy/load.ts";
import { realVaultRelative, toPosix } from "../path-safety.ts";
import { normaliseWriteBindingPrefix, writeBindingPrefixCovers } from "./prefix.ts";
export { normaliseWriteBindingPrefix, writeBindingPrefixCovers };
/**
* Registry code the refusal resolves its forward pointer through. The
* refusal NAMES no command of its own — the registry does, so the exit
* is the same structural CLI string on every surface that reports it.
*/
export const WRITE_BINDING_REFUSED_CODE = "write-binding-refused";
/**
* Resolved at module scope on purpose. A refusal whose value is telling
* the operator where to look is meaningless without its exit, so an
* unregistered code is registry drift and fails at import rather than
* inside the very refusal it was meant to explain (see `next-step.ts`).
*/
const REFUSED_EXIT = requireNextStep(WRITE_BINDING_REFUSED_CODE).nextCommand;
/** The declared binding in force for one vault. Never empty when present. */
export interface WriteBinding {
/**
* Vault-relative POSIX prefixes, already normalised by the block
* parser. A target is admitted when it equals one of these or lies
* under it segment-wise.
*/
readonly pathPrefixes: ReadonlyArray<string>;
}
/** A caller-named target the declared binding does not admit. */
export interface WriteBindingRefusal {
/** Always {@link WRITE_BINDING_REFUSED_CODE}; carried so a surface can resolve it. */
readonly code: string;
/** The vault-relative target that was refused, as the caller named it. */
readonly relPath: string;
/**
* Where that name actually resolves on disk, vault-relative — the path
* that would have held the bytes. Equal to {@link relPath} in the
* ordinary case; different when a symlinked directory component
* redirects the write, which is the case a lexical check missed. Null
* when the destination resolves outside the vault entirely, which is a
* different answer from "somewhere else inside it".
*/
readonly resolvedRelPath: string | null;
/** The prefixes in force, so the operator sees what WOULD be admitted. */
readonly pathPrefixes: ReadonlyArray<string>;
/** The registered exit for {@link code}. */
readonly nextCommand: string;
/**
* The refusal, composed HERE and only here. Call sites raise it in
* whatever error type their surface already speaks; none of them
* assembles a sentence, so the wording cannot drift between the four
* tools that share the envelope.
*/
readonly message: string;
}
/** Separator between prefixes when the refusal lists them. */
const PREFIX_LIST_SEPARATOR = ", ";
/** How the refusal names a destination that leaves the vault entirely. */
const OUTSIDE_VAULT_LABEL = "a location outside the vault";
/**
* One resolved binding plus the identity of the config bytes it was read
* from, so the answer can be reused for as long as those bytes are the
* ones on disk.
*/
interface CachedBinding {
readonly vault: string;
readonly identity: string;
readonly binding: WriteBinding | null;
}
/**
* Single-slot memo over {@link resolveWriteBinding}.
*
* A write batch resolves its target through the shared envelope once per
* operation, so without this the whole `_brain.yaml` was read, parsed and
* revalidated N times for one atomic batch against one unchanging file.
* One slot is the right size: the loop that pays the cost hits the same
* vault every iteration.
*
* The key is the config file's own identity, never a clock — see
* {@link brainConfigIdentity}. A file that changed by any of inode, size
* or mtime misses, so a cached answer can never outlive the declaration
* it came from.
*/
let cachedBinding: CachedBinding | null = null;
/**
* Identity of the config bytes at `path`, or `null` when the file is
* ABSENT. Absence and inability-to-examine are different answers: an
* ENOENT is a vault that predates `_brain.yaml`, while a permission
* error is a declaration that may exist and cannot be read, and
* answering "no binding" for the latter would silently widen the
* boundary. Only ENOENT becomes `null`; every other errno is raised.
*/
function brainConfigIdentity(path: string): string | null {
try {
const st = statSync(path, { bigint: true });
return `${st.ino}:${st.size}:${st.mtimeNs}`;
} catch (err) {
if ((err as NodeJS.ErrnoException)?.code === "ENOENT") return null;
throw err;
}
}
/**
* The binding declared for `vault`, or `null` when none is.
*
* `null` is the absent result rather than an empty-prefix record because
* the two are different answers: an empty record would have to be read
* as "admits nothing", and the block parser refuses that declaration
* precisely so it can never arrive here.
*
* A vault with no `_brain.yaml` is absent, not broken — existing vaults
* predate the file. A config that is present but does not load raises,
* matching `loadBrainConfig`: the operator's settings exist and are not
* the ones in force, and answering "no binding" would silently widen the
* boundary they declared. Callers on a caller-named write path translate
* that raise into their own typed refusal rather than letting it surface
* as an untyped fault.
*/
export function resolveWriteBinding(vault: string): WriteBinding | null {
// On a store-only machine `write_binding` is a shared setting (design
// D14 item 3): the store reader keeps its own cache, so none here.
if (brainSettingsFromStore(vault)) return bindingOf(loadBrainConfig(vault).write_binding);
const configPath = brainConfigPath(vault);
const identity = brainConfigIdentity(configPath);
if (identity === null) return null;
const hit = cachedBinding;
if (hit !== null && hit.vault === vault && hit.identity === identity) return hit.binding;
const binding = bindingOf(loadBrainConfig(vault).write_binding);
cachedBinding = Object.freeze({ vault, identity, binding });
return binding;
}
function bindingOf(
block: { readonly path_prefixes?: ReadonlyArray<string> } | undefined,
): WriteBinding | null {
const declared = block?.path_prefixes;
return declared === undefined || declared.length === 0
? null
: Object.freeze({ pathPrefixes: Object.freeze([...declared]) });
}
/** Whether `binding` admits the vault-relative `relPath`. */
export function writeBindingAdmits(binding: WriteBinding, relPath: string): boolean {
return binding.pathPrefixes.some((prefix) => writeBindingPrefixCovers(prefix, relPath));
}
/**
* The refusal for a caller-named write to `relPath`, or `null` when the
* write is admitted — including when no binding is declared at all.
*
* Both the name and the destination must be admitted. The name alone is
* not enough (a symlinked component redirects the bytes), and the
* destination alone is not enough either (a caller must not be able to
* name a path outside the binding and have it accepted because it
* happens to resolve inside one).
*
* Takes no identity, by construction. See the module docblock for why a
* fence keyed to the caller's claimed name would fence nothing.
*/
export function checkWriteBinding(vault: string, relPath: string): WriteBindingRefusal | null {
const binding = resolveWriteBinding(vault);
if (binding === null) return null;
if (!writeBindingAdmits(binding, relPath)) return writeBindingRefusal(binding, relPath, relPath);
let resolved: string | null;
try {
resolved = realVaultRelative(vault, relPath);
} catch (exc) {
// A destination that cannot be resolved is not one the binding can
// be shown to admit: refuse, naming why, rather than raise an I/O
// error out of a policy check.
const refusal = writeBindingRefusal(binding, relPath, null);
const code = (exc as NodeJS.ErrnoException)?.code ?? "unknown";
return Object.freeze({
...refusal,
message: `${refusal.relPath} cannot be resolved on disk (${code}); ${REFUSED_EXIT}`,
});
}
if (resolved !== null && writeBindingAdmits(binding, resolved)) return null;
return writeBindingRefusal(binding, relPath, resolved);
}
/** Refusal raised by {@link governCallerNamedWritePath}. */
export class GovernedPathWriteRefusedError extends Error {
/** The surface name its caller gave itself, for audit symmetry with `StandingRulesWriteRefusedError`. */
readonly surface: string;
constructor(surface: string, message: string) {
super(`${surface} refused: ${message}`);
this.name = "GovernedPathWriteRefusedError";
this.surface = surface;
}
}
/**
* The governance walls the note-target envelope applies that a
* caller-named write reaching through a weaker resolver (labels,
* attributes, marker write-back - containment only) must apply itself,
* because containment alone says nothing about WHICH file is being
* rewritten:
*
* 1. The write binding's own authority is refused by name -
* `Brain/_brain.yaml` - lexically and canonically, so a symlink to it
* is the same target. (Wall 2 refuses it too; the named refusal
* keeps the operator-facing message about what the file IS.)
* 2. The target must be a Markdown note, and not Brain machinery. These
* surfaces rewrite a note's frontmatter; pointed at anything else they
* corrupt it - `Brain/vault-id.json` (which disables the vault
* identity guard), `Brain/search/embedding-providers.json`,
* `_vault-map.yaml`. Under `Brain/`, only the page lanes
* ({@link BRAIN_PAGE_LANES_REL}: sources, reports, distillations) hold
* notes; everything else there is owned by the Brain's own writers.
* Checked on the caller's spelling AND on where the bytes actually
* land, so a vault note that is a symlink into `Brain/` is refused.
* Holds whether or not a write binding is declared.
* 3. The operator's declared write binding (`write_binding.path_prefixes`)
* admits the target before any byte is read. Absent declaration the
* check is inert, exactly as on the note path.
*
* Lives beside {@link checkWriteBinding} rather than beside the resolver
* on purpose: the guard is the binding boundary extended to writers that
* bypass the note envelope, and keeping it here keeps the resolver
* module free of the binding's config-loading dependency graph.
*
* Returns the vault-relative POSIX path the walls read, so a caller that
* wants to reuse it resolves the same segments these checks saw. POSIX
* because the binding matcher splits on `/`: handing it the native
* `relative()` form refused every write on Windows once a binding was
* declared.
*/
export function governCallerNamedWritePath(
vault: string,
relPath: string,
surface: string,
): string {
const vaultRoot = resolve(vault);
const candidate = resolve(vaultRoot, relPath);
const normalized = toPosix(relative(vaultRoot, candidate));
const configPath = brainConfigPath(vault);
if (candidate === configPath || canonicalPath(candidate) === canonicalPath(configPath)) {
throw new GovernedPathWriteRefusedError(
surface,
`${normalized} is the write binding's own config, which this surface does not rewrite`,
);
}
const namedRefusal = callerNamedTargetRefusal(normalized);
if (namedRefusal !== null) throw new GovernedPathWriteRefusedError(surface, namedRefusal);
let landsAt: string | null;
try {
landsAt = realVaultRelative(vault, normalized);
} catch (exc) {
const code = (exc as NodeJS.ErrnoException)?.code ?? "unknown";
throw new GovernedPathWriteRefusedError(
surface,
`${normalized} cannot be resolved on disk (${code})`,
);
}
if (landsAt !== null && landsAt !== normalized) {
const landedRefusal = callerNamedTargetRefusal(landsAt);
if (landedRefusal !== null) {
throw new GovernedPathWriteRefusedError(
surface,
`${normalized} resolves to ${landsAt}: ${landedRefusal}`,
);
}
}
const bindingRefusal = checkWriteBinding(vault, normalized);
if (bindingRefusal !== null) {
throw new GovernedPathWriteRefusedError(surface, bindingRefusal.message);
}
return normalized;
}
/**
* Wall 2 of {@link governCallerNamedWritePath} for one vault-relative
* POSIX path: the refusal message, or `null` when the path names a
* Markdown note outside Brain machinery.
*/
function callerNamedTargetRefusal(relPath: string): string | null {
if (!relPath.toLowerCase().endsWith(".md")) {
return `${relPath} is not a Markdown note, and this surface only rewrites note frontmatter`;
}
if (isUnderBrainRoot(relPath) && !isInBrainLane(relPath, BRAIN_PAGE_LANES_REL)) {
return (
`${relPath} is Brain machinery; under ${BRAIN_ROOT_REL}/ this surface writes only the ` +
`page lanes (${BRAIN_PAGE_LANES_REL.map((lane) => `${lane}/`).join(", ")})`
);
}
return null;
}
/**
* Canonical form of `path`, or the path itself when it cannot be
* canonicalized - the same total comparison
* `assertStandingRulesNotTargeted` runs, for the same reason: a symlink
* pointing at the config file is the same target, and a missing file
* must not make the guard fail open.
*/
function canonicalPath(path: string): string {
try {
return realpathSync(path);
} catch {
return path;
}
}
/**
* Build the refusal record for a target the binding does not admit.
*
* `resolvedRelPath` is where the bytes would have gone; the message
* names it beside the caller's own spelling whenever the two differ, so
* an operator reading the refusal sees the redirection rather than
* having to discover it.
*/
export function writeBindingRefusal(
binding: WriteBinding,
relPath: string,
resolvedRelPath: string | null,
): WriteBindingRefusal {
const normalised = normaliseWriteBindingPrefix(relPath);
const prefixes = binding.pathPrefixes.join(PREFIX_LIST_SEPARATOR);
const redirect =
resolvedRelPath === normalised
? ""
: ` (resolves to ${resolvedRelPath ?? OUTSIDE_VAULT_LABEL})`;
return Object.freeze({
code: WRITE_BINDING_REFUSED_CODE,
relPath: normalised,
resolvedRelPath,
pathPrefixes: binding.pathPrefixes,
nextCommand: REFUSED_EXIT,
message:
`${normalised}${redirect} is outside the write binding declared in Brain/_brain.yaml ` +
`(write_binding.path_prefixes: ${prefixes}); ${REFUSED_EXIT}`,
});
}