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 permissions document: `<vault>/Brain/_permissions.yaml` (write-side-
* trust, Task 1).
*
* Trust policy is state the operator hand-edits and syncs to every device,
* exactly like the freeze marker - so it is a vault FILE, not a
* `_brain.yaml` block. The strict machinery it borrows from the config
* blocks is pattern, not import: field-named {@link PermissionsDocumentError}
* raises, unknown-key warnings, and a `version` key that hard-refuses
* anything but 1.
*
* The one split every consumer answers through {@link loadPermissionsDocument}:
*
* - ABSENT - `{ document: null }`. The default posture; every gate
* proceeds exactly as it did before this document existed.
* - PRESENT BUT UNREADABLE - malformed YAML, a wrong-typed field, an
* unsupported version, a permission error, a directory in the file's
* place. The operator's policy exists and is NOT in force; answering
* with permissive silence would turn a typo into an open gate, so the
* loader throws and never returns a document.
*
* The YAML subset is the indent-aware one `src/core/brain/yaml-parse.ts`
* established for `_brain.yaml`, extended with the one shape the schema
* needs beyond it: a list of small mappings under `entries:`. Anchors,
* aliases and deeply nested inline structures stay outside the grammar on
* purpose - a policy file an operator cannot eyeball is a policy nobody
* can trust.
*
* LEAF MODULE: imports nothing from the Brain layer. The resolver
* (`./resolve.ts`), the ledger (`./ledger.ts`) and every gate lane build on
* the types and the loader exported here.
*/
import { existsSync, readFileSync } from "node:fs";
import { join } from "node:path";
import { canonicalNotePath } from "../../path-safety.ts";
/** The vault-relative directory the document lives in. */
const DOCUMENT_DIRECTORY = "Brain";
/** The file name, beside `_brain.yaml` and the freeze marker. */
const DOCUMENT_BASENAME = "_permissions.yaml";
/** Vault-relative location of the permissions document. */
export const PERMISSIONS_DOCUMENT_REL = `${DOCUMENT_DIRECTORY}/${DOCUMENT_BASENAME}`;
/**
* The shared setting that holds the document's text once a machine writes
* the store only (design D14 item 3): an operator-only store-native setting
* the migration imports `_permissions.yaml` into.
*/
export const PERMISSIONS_DOCUMENT_SETTING = "permissions.document";
/** The only schema version this build reads. Anything else hard-refuses. */
export const PERMISSIONS_SCHEMA_VERSION = 1;
/**
* The canonical form of a rule target: Windows separators and `.`-dot
* segments folded away, then the canonical note identity every stored
* path carries ({@link canonicalNotePath}: POSIX separators, NFC).
*
* The document is a hand-edited file synced across devices while the
* targets the gates consult are stored POSIX note paths, so a target
* spelled the way the writing host spells paths (`Notes\a.md`,
* `.\Notes\a.md`, `./Notes/a.md`) must reach the same rule the stored
* spelling does. Idempotent: an already-canonical target returns
* byte-identical. A `..` segment deliberately survives: the resolver
* matches canonical identities exactly, so such a target is inert by
* construction, and the loader warns rather than second-guessing the
* operator's spelling.
*/
export function canonicalPermissionTarget(target: string): string {
const folded = target
.replaceAll("\\", "/")
.split("/")
.filter((segment) => segment !== "" && segment !== ".")
.join("/");
return canonicalNotePath(folded);
}
/** What a rule says about one action. Deny wins every tie. */
export type PermissionVerdict = "allow" | "ask" | "deny";
/** What a rule is about: the two write lanes and the owner-stamp lane. */
export type PermissionAction = "write" | "ingest" | "owner_write";
/** The closed vocabularies, in the order equal-specificity ties resolve. */
const VERDICTS: ReadonlyArray<PermissionVerdict> = ["allow", "ask", "deny"];
const ACTIONS: ReadonlyArray<PermissionAction> = ["write", "ingest", "owner_write"];
/** One target-scoped exception or blanket rule the operator wrote. */
export interface PermissionEntry {
id: string;
agent?: string;
role?: string;
action: PermissionAction;
target?: string;
verdict: PermissionVerdict;
}
/**
* The parsed document. `default_action` is REQUIRED - there is no silent
* default - so a document is always a closed world the operator spelled.
*/
export interface PermissionsDocument {
version: 1;
default_action: PermissionVerdict;
roles: Record<string, Partial<Record<PermissionAction, PermissionVerdict>>>;
agents: Record<
string,
{
role?: string;
write?: PermissionVerdict;
ingest?: PermissionVerdict;
owner_write?: PermissionVerdict;
}
>;
entries: PermissionEntry[];
ledger?: { record_allows?: boolean };
}
/**
* Why the document could not be read. The message always names the file
* and, for every schema-level refusal, the exact field that refused.
*/
export class PermissionsDocumentError extends Error {}
// ----- YAML subset ----------------------------------------------------------
type YamlScalar = string | number | boolean | null;
type YamlValue = YamlScalar | YamlMapping | YamlValue[];
/** Insertion-ordered mapping; key order drives the deterministic warnings. */
interface YamlMapping {
[key: string]: YamlValue;
}
interface Line {
readonly indent: number;
readonly content: string;
readonly lineNumber: number;
}
/** A parse failure, carrying its line like `yaml-parse.ts` does. */
class YamlSyntaxError extends Error {}
/**
* The subset's scalar grammar, shared with `yaml-parse.ts`: quoted strings
* are taken verbatim, `true`/`false`/`null`/`~` are literals, plain
* integers and finite decimals parse as numbers, everything else stays a
* string - so `yes` and `no` are honest strings, not booleans.
*/
function parseScalar(text: string): YamlScalar {
if (
text.length >= 2 &&
((text[0] === '"' && text.at(-1) === '"') || (text[0] === "'" && text.at(-1) === "'"))
) {
return text.slice(1, -1);
}
if (text === "true") return true;
if (text === "false") return false;
if (text === "null" || text === "~") return null;
if (/^-?\d+$/.test(text)) return parseInt(text, 10);
if (/^-?\d+\.\d+$/.test(text)) return parseFloat(text);
return text;
}
function splitLines(text: string): Line[] {
const out: Line[] = [];
let lineNumber = 0;
for (const raw of text.split(/\r?\n/)) {
lineNumber++;
const stripped = raw.replace(/\s+$/, "");
if (stripped.trim() === "" || stripped.trimStart().startsWith("#")) continue;
// Inline comments are honoured only where they cannot be content: a
// line carrying quotes keeps everything, the same rule yaml-parse uses.
let content = stripped;
if (!/['"]/.test(stripped)) {
const hashAt = stripped.indexOf(" #");
if (hashAt >= 0) content = stripped.slice(0, hashAt).replace(/\s+$/, "");
}
const indent = content.length - content.trimStart().length;
out.push({ indent, content: content.slice(indent), lineNumber });
}
return out;
}
interface KeyValue {
readonly key: string;
readonly value: string;
}
function splitKeyValue(line: Line): KeyValue {
const at = line.content.indexOf(":");
if (at <= 0) {
throw new YamlSyntaxError(
`line ${line.lineNumber}: expected 'key: value', got: ${JSON.stringify(line.content)}`,
);
}
const key = line.content.slice(0, at).trim();
if (!/^[A-Za-z_][A-Za-z0-9_-]*$/.test(key)) {
throw new YamlSyntaxError(`line ${line.lineNumber}: invalid key name: ${JSON.stringify(key)}`);
}
if (key === "__proto__" || key === "constructor" || key === "prototype") {
throw new YamlSyntaxError(`line ${line.lineNumber}: reserved key name: ${JSON.stringify(key)}`);
}
return { key, value: line.content.slice(at + 1).trim() };
}
/** True when the line opens a list item (`- ` prefix). */
function isListItem(line: Line): boolean {
return line.content === "-" || line.content.startsWith("- ");
}
/**
* Parse a mapping whose keys sit at exactly `indent`. A key with an empty
* value opens either a nested mapping or a list at a deeper indent; with
* nothing deeper, it stands for an empty mapping.
*/
function parseMapping(lines: Line[], start: number, indent: number): [YamlMapping, number] {
const out: YamlMapping = {};
let i = start;
while (i < lines.length && lines[i]!.indent === indent) {
const line = lines[i]!;
if (isListItem(line)) break;
const { key, value } = splitKeyValue(line);
if (key in out) {
throw new YamlSyntaxError(`line ${line.lineNumber}: duplicate key '${key}'`);
}
if (value !== "") {
out[key] = parseScalar(value);
i++;
// A scalar line followed by a deeper one is the shape a misdedented
// block takes; refuse rather than guess which line is right.
if (i < lines.length && lines[i]!.indent > indent) {
throw new YamlSyntaxError(
`line ${lines[i]!.lineNumber}: unexpected indentation under '${key}'`,
);
}
continue;
}
i++;
if (i < lines.length && lines[i]!.indent > indent) {
const childIndent = lines[i]!.indent;
const [child, next] = isListItem(lines[i]!)
? parseList(lines, i, childIndent)
: parseMapping(lines, i, childIndent);
out[key] = child;
i = next;
} else {
out[key] = {};
}
}
return [out, i];
}
/**
* Parse a list whose `- ` items sit at exactly `indent`. An item whose
* content names a key opens a small mapping: the inline pair is its first
* entry and the siblings align two columns deeper (the `- ` width), which
* is the layout the entries block takes.
*/
function parseList(lines: Line[], start: number, indent: number): [YamlValue[], number] {
const out: YamlValue[] = [];
let i = start;
while (i < lines.length && lines[i]!.indent === indent && isListItem(lines[i]!)) {
const line = lines[i]!;
const item = line.content === "-" ? "" : line.content.slice(2).trim();
const itemKey = item.indexOf(":");
if (item === "") {
throw new YamlSyntaxError(`line ${line.lineNumber}: empty list item is not supported`);
}
if (itemKey <= 0) {
out.push(parseScalar(item));
i++;
continue;
}
// A mapping item: re-parse the inline pair plus the aligned siblings.
const itemIndent = indent + 2;
const synthetic: Line = {
indent: itemIndent,
content: item,
lineNumber: line.lineNumber,
};
const rest = parseMapping([synthetic, ...lines.slice(i + 1)], 0, itemIndent);
out.push(rest[0]);
// Count how many input lines the item mapping consumed: the synthetic
// first line plus everything after it up to the returned cursor.
const consumed = rest[1] - 1;
i += 1 + consumed;
if (i < lines.length && lines[i]!.indent > indent && !isListItem(lines[i]!)) {
throw new YamlSyntaxError(
`line ${lines[i]!.lineNumber}: inconsistent indentation in list item ` +
`(expected ${itemIndent}, got ${lines[i]!.indent})`,
);
}
}
return [out, i];
}
function parseDocumentYaml(text: string): YamlMapping {
const lines = splitLines(text);
if (lines.length === 0) return {};
const [out, next] = parseMapping(lines, 0, 0);
if (next < lines.length) {
throw new YamlSyntaxError(
`line ${lines[next]!.lineNumber}: unexpected indentation at the document level`,
);
}
return out;
}
// ----- Validation -----------------------------------------------------------
function fail(path: string, field: string, message: string): PermissionsDocumentError {
return new PermissionsDocumentError(`${path}: ${field}: ${message}`);
}
function describeValue(value: unknown): string {
if (value === null) return "null";
if (Array.isArray(value)) return "a list";
return typeof value === "string" ? JSON.stringify(value) : `a ${typeof value}`;
}
function isMapping(value: YamlValue | undefined): value is YamlMapping {
return value !== null && typeof value === "object" && !Array.isArray(value);
}
/**
* Loader diagnostics write once per UNIQUE warning, not once per consult:
* the resolver runs on every gate check, and a permission write consults
* the document it just loaded, so the same warning repeated per write
* reads like a fresh defect - while a document with several distinct
* findings still reports each of them. A reset hook keeps it testable.
*/
const warned = new Set<string>();
export function resetPermissionWarnings(): void {
warned.clear();
}
function warn(path: string, field: string, message: string): void {
const key = `${path}\u0000${field}\u0000${message}`;
if (warned.has(key)) return;
warned.add(key);
process.stderr.write(`warning: ${path}: ${field}: ${message}\n`);
}
function isVerdict(value: YamlValue): value is PermissionVerdict {
return typeof value === "string" && (VERDICTS as ReadonlyArray<string>).includes(value);
}
function requireVerdict(path: string, field: string, value: YamlValue): PermissionVerdict {
if (!isVerdict(value)) {
throw fail(path, field, `must be one of ${VERDICTS.join(", ")}; got ${describeValue(value)}`);
}
return value;
}
/** A required string field: absent, non-string or blank all refuse by name. */
function requireString(path: string, field: string, value: YamlValue | undefined): string {
if (value === undefined) throw fail(path, field, "is required");
if (typeof value !== "string" || value.trim() === "") {
throw fail(path, field, `must be a non-empty string; got ${describeValue(value)}`);
}
return value;
}
/** An optional string field: absent stays absent, present must be a real string. */
function optionalString(
path: string,
field: string,
value: YamlValue | undefined,
): string | undefined {
return value === undefined ? undefined : requireString(path, field, value);
}
function parseActionMapping(
path: string,
field: string,
value: YamlValue,
warnings: string[],
): Partial<Record<PermissionAction, PermissionVerdict>> {
if (!isMapping(value)) {
throw fail(path, field, `must be a mapping; got ${describeValue(value)}`);
}
const out: Partial<Record<PermissionAction, PermissionVerdict>> = {};
for (const [key, raw] of Object.entries(value)) {
if (!(ACTIONS as ReadonlyArray<string>).includes(key)) {
warnings.push(`${field}.${key}`);
continue;
}
out[key as PermissionAction] = requireVerdict(path, `${field}.${key}`, raw);
}
return out;
}
function validateRoles(
path: string,
raw: YamlValue,
warnings: string[],
): Record<string, Partial<Record<PermissionAction, PermissionVerdict>>> {
if (!isMapping(raw)) throw fail(path, "roles", `must be a mapping; got ${describeValue(raw)}`);
const roles: Record<string, Partial<Record<PermissionAction, PermissionVerdict>>> = {};
for (const [name, value] of Object.entries(raw)) {
roles[name] = parseActionMapping(path, `roles.${name}`, value, warnings);
}
return roles;
}
const AGENT_ACTION_KEYS: ReadonlyArray<string> = ACTIONS;
function validateAgents(
path: string,
raw: YamlValue,
warnings: string[],
): PermissionsDocument["agents"] {
if (!isMapping(raw)) throw fail(path, "agents", `must be a mapping; got ${describeValue(raw)}`);
const agents: PermissionsDocument["agents"] = {};
for (const [name, value] of Object.entries(raw)) {
if (!isMapping(value)) {
throw fail(path, `agents.${name}`, `must be a mapping; got ${describeValue(value)}`);
}
const agent: PermissionsDocument["agents"][string] = {};
for (const [key, inner] of Object.entries(value)) {
if (key === "role") {
agent.role = requireString(path, `agents.${name}.role`, inner);
continue;
}
if ((AGENT_ACTION_KEYS as ReadonlyArray<string>).includes(key)) {
agent[key as PermissionAction] = requireVerdict(path, `agents.${name}.${key}`, inner);
continue;
}
warnings.push(`agents.${name}.${key}`);
}
agents[name] = agent;
}
return agents;
}
function validateEntries(path: string, raw: YamlValue, warnings: string[]): PermissionEntry[] {
if (!Array.isArray(raw)) throw fail(path, "entries", `must be a list; got ${describeValue(raw)}`);
const entries: PermissionEntry[] = [];
for (const [index, item] of raw.entries()) {
const field = `entries[${index}]`;
if (!isMapping(item)) throw fail(path, field, `must be a mapping; got ${describeValue(item)}`);
const id = requireString(path, `${field}.id`, item["id"]);
const actionRaw = item["action"];
if (actionRaw === undefined) {
throw fail(path, `${field}.action`, "is required");
}
if (typeof actionRaw !== "string" || !(ACTIONS as ReadonlyArray<string>).includes(actionRaw)) {
throw fail(
path,
`${field}.action`,
`must be one of ${ACTIONS.join(", ")}; got ${describeValue(actionRaw)}`,
);
}
const verdictRaw = item["verdict"];
if (verdictRaw === undefined) {
throw fail(path, `${field}.verdict`, "is required");
}
const verdict = requireVerdict(path, `${field}.verdict`, verdictRaw);
const agent = optionalString(path, `${field}.agent`, item["agent"]);
const role = optionalString(path, `${field}.role`, item["role"]);
if (agent !== undefined && role !== undefined) {
throw fail(
path,
field,
"declares both agent and role; an entry names one principal, never two",
);
}
const target = optionalString(path, `${field}.target`, item["target"]);
for (const key of Object.keys(item)) {
if (
!(["id", "action", "verdict", "agent", "role", "target"] as ReadonlyArray<string>).includes(
key,
)
) {
warnings.push(`${field}.${key}`);
}
}
entries.push({
id,
...(agent !== undefined ? { agent } : {}),
...(role !== undefined ? { role } : {}),
action: actionRaw as PermissionAction,
...(target !== undefined ? { target } : {}),
verdict,
});
}
return entries;
}
function validateLedger(
path: string,
raw: YamlValue,
warnings: string[],
): { record_allows?: boolean } {
if (!isMapping(raw)) throw fail(path, "ledger", `must be a mapping; got ${describeValue(raw)}`);
const ledger: { record_allows?: boolean } = {};
for (const [key, value] of Object.entries(raw)) {
if (key === "record_allows") {
if (typeof value !== "boolean") {
throw fail(path, `ledger.${key}`, `must be a boolean; got ${describeValue(value)}`);
}
ledger.record_allows = value;
continue;
}
warnings.push(`ledger.${key}`);
}
return ledger;
}
/** The absolute path of the document inside `vault`. */
function documentPath(vault: string): string {
return join(vault, DOCUMENT_DIRECTORY, DOCUMENT_BASENAME);
}
/**
* Read the permissions document.
*
* ABSENT: `{ document: null }` and every consumer proceeds as today.
* PRESENT: the file is parsed and validated strictly; anything it cannot
* honour raises {@link PermissionsDocumentError} naming the file and the
* field, and UNKNOWN keys warn on stderr while the document still loads.
*/
export function loadPermissionsDocument(vault: string): {
document: PermissionsDocument | null;
path: string;
} {
const path = documentPath(vault);
if (!existsSync(path)) return { document: null, path };
let text: string;
try {
text = readFileSync(path, "utf8");
} catch (err) {
throw new PermissionsDocumentError(
`${path}: could not be read: ${err instanceof Error ? err.message : String(err)}`,
);
}
return { document: parsePermissionsDocumentText(text, path), path };
}
/**
* Parse and validate a permissions document from its text, with the same
* strict rules as the file. `path` names where the text came from in every
* refusal and warning (the file, or the shared setting a store-only
* machine reads it from).
*/
export function parsePermissionsDocumentText(text: string, path: string): PermissionsDocument {
let raw: YamlMapping;
try {
raw = parseDocumentYaml(text);
} catch (err) {
throw new PermissionsDocumentError(
`${path}: ${err instanceof Error ? err.message : String(err)}`,
);
}
const warnings: string[] = [];
for (const key of Object.keys(raw)) {
if (
!(
[
"version",
"default_action",
"roles",
"agents",
"entries",
"ledger",
] as ReadonlyArray<string>
).includes(key)
) {
warnings.push(key);
}
}
const version = raw["version"];
if (version !== PERMISSIONS_SCHEMA_VERSION) {
throw fail(
path,
"version",
`must be ${PERMISSIONS_SCHEMA_VERSION}; got ${describeValue(version)}`,
);
}
const defaultRaw = raw["default_action"];
if (defaultRaw === undefined) {
throw fail(path, "default_action", "is required - a document is a closed world, not a filter");
}
const default_action = requireVerdict(path, "default_action", defaultRaw);
const roles = raw["roles"] === undefined ? {} : validateRoles(path, raw["roles"], warnings);
const agents = raw["agents"] === undefined ? {} : validateAgents(path, raw["agents"], warnings);
const entries =
raw["entries"] === undefined ? [] : validateEntries(path, raw["entries"], warnings);
const ledger =
raw["ledger"] === undefined ? undefined : validateLedger(path, raw["ledger"], warnings);
// Warnings are emitted only once the document is known loadable, so a
// refusing file never drowns its error in forward-compat noise.
for (const field of warnings) {
warn(path, field, "unknown field ignored (forward-compat)");
}
for (const [index, entry] of entries.entries()) {
if (entry.target === undefined) continue;
const canonical = canonicalPermissionTarget(entry.target);
if (canonical !== entry.target) {
warn(
path,
`entries[${index}].target`,
`non-canonical target ${JSON.stringify(entry.target)}; it matches as ${JSON.stringify(canonical)}`,
);
}
// `..` survives canonicalization on purpose - the resolver matches
// canonical identities exactly, and a stored note path is
// vault-relative, so such a rule is silently inert. That silence is
// the hazard: an operator who wrote `../secrets/a.md` believes they
// closed a gate they never reached. Warn, and leave the exact-match
// semantics alone.
if (canonical.split("/").includes("..")) {
warn(
path,
`entries[${index}].target`,
`target ${JSON.stringify(entry.target)} still contains a '..' segment; ` +
"stored note paths are vault-relative, so this rule can never match",
);
}
}
return {
version: 1,
default_action,
roles,
agents,
entries,
...(ledger !== undefined ? { ledger } : {}),
};
}