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
/**
* Controlled-vocabulary labels (write-time-integrity-governance).
*
* The schema pack declares label dimensions with a fixed enum of
* allowed values (`schema.labels`); this module is the write-time
* enforcement seam. Assignment is fail-closed - an unknown dimension
* or value is rejected with the declared vocabulary in the error -
* and classification is single-choice: one value per dimension per
* note. Labels persist as a sorted `labels: [dim/value]` frontmatter
* array (filterable through the existing `--property` post-rank
* filter) plus a canonical `label` entity in the registry so related
* notes cluster without free-form tag drift.
*
* Both writes take a caller-named path and resolve it through
* `resolveNotePath`, which guarantees containment and nothing about which
* file is being rewritten. One file needs more than that:
* `Brain/standing-rules.md` is the operator's own text, and
* `assertStandingRulesNotTargeted` refuses it by name here because the
* Brain-root refusal that covers the note-write tools is not on this path.
* The other caller-named-write walls - the write binding's own authority,
* `Brain/_brain.yaml`, and the operator's declared write binding - are
* applied through `governCallerNamedWritePath` for the same reason: a
* caller-named write answers to the same governance whether it lands
* through the note envelope or around it.
*/
import { parseFrontmatter, writeFrontmatterAtomic } from "../vault.ts";
import { resolveNotePath } from "./note-path.ts";
import { governCallerNamedWritePath } from "../write-binding/index.ts";
import { assertStandingRulesNotTargeted } from "./standing-rules.ts";
import { normalizeSchemaToken } from "./schema-vocab.ts";
import { upsertEntity } from "./entities/registry.ts";
import { assertVaultIdentityForWrite } from "./vault-identity.ts";
import type { SchemaPack } from "./schema-pack.ts";
export const LABEL_ENTITY_CATEGORY = "label";
/**
* How the two label writes name themselves in a refusal. Named constants
* rather than inline strings because the words appear in an operator- and
* agent-facing error and must not drift between the two paths.
*/
const LABEL_ASSIGN_SURFACE = "label assignment";
const LABEL_REMOVE_SURFACE = "label removal";
export class LabelVocabularyError extends Error {
readonly dimension: string;
readonly allowed: ReadonlyArray<string>;
constructor(dimension: string, allowed: ReadonlyArray<string>, message: string) {
super(message);
this.name = "LabelVocabularyError";
this.dimension = dimension;
this.allowed = allowed;
}
}
export interface LabelAssignment {
readonly dimension: string;
readonly value: string;
/** Canonical `dimension/value` form stored in frontmatter. */
readonly token: string;
}
export interface AssignNoteLabelOptions {
readonly dimension: string;
readonly value: string;
readonly pack: SchemaPack;
/** Agent identity stamped on the canonical label entity. */
readonly agent: string;
/** Injected clock for deterministic registry stamps. */
readonly now: Date;
/** The paths the caller may read; see {@link NoteLabelReach}. */
readonly readable?: NoteLabelReach;
}
export interface RemoveNoteLabelOptions {
readonly dimension: string;
readonly pack: SchemaPack;
/** The paths the caller may read; see {@link NoteLabelReach}. */
readonly readable?: NoteLabelReach;
}
/**
* The vault-relative paths the caller may read. A note it may not read is
* refused with the error a missing note gets, before its frontmatter is
* read or written. Absent, every note may be labelled.
*/
export type NoteLabelReach = (rel: string) => boolean;
export interface NoteLabelResult {
/** Vault-relative path of the labelled note. */
readonly path: string;
/** The note's full label set after the operation, sorted. */
readonly labels: ReadonlyArray<string>;
/** Whether the file content changed. */
readonly changed: boolean;
}
export interface RemoveNoteLabelResult extends NoteLabelResult {
/** Whether the dimension was present before removal. */
readonly removed: boolean;
}
/** Render the canonical `dimension/value` label form. */
export function labelToken(dimension: string, value: string): string {
return `${dimension}/${value}`;
}
/**
* Validate one assignment against the declared vocabulary.
* Fail-closed: unknown dimensions and values throw with the declared
* alternatives listed, so a caller (or its operator) can self-correct.
*/
export function validateLabelAssignment(
pack: SchemaPack,
dimension: string,
value: string,
): LabelAssignment {
const dimensions = Object.keys(pack.labels);
if (dimensions.length === 0) {
throw new LabelVocabularyError(
normalizeSchemaToken(dimension),
[],
"no label dimensions are declared in the schema pack",
);
}
const normalizedDimension = normalizeSchemaToken(dimension);
const allowed = pack.labels[normalizedDimension];
if (allowed === undefined) {
throw new LabelVocabularyError(
normalizedDimension,
dimensions,
`unknown label dimension "${normalizedDimension}" - declared dimensions: ${dimensions.join(", ")}`,
);
}
const normalizedValue = normalizeSchemaToken(value);
if (!allowed.includes(normalizedValue)) {
throw new LabelVocabularyError(
normalizedDimension,
allowed,
`label ${normalizedDimension}="${normalizedValue}" is not in the vocabulary - allowed values: ${allowed.join(", ")}`,
);
}
return {
dimension: normalizedDimension,
value: normalizedValue,
token: labelToken(normalizedDimension, normalizedValue),
};
}
/**
* Assign one label to a note: validates against the pack, replaces
* any existing value of the same dimension (single-choice), writes a
* sorted `labels` frontmatter array atomically, and registers the
* canonical `label` entity. Validation runs before any I/O so an
* invalid assignment never touches the file.
*/
export function assignNoteLabel(
vault: string,
relPath: string,
opts: AssignNoteLabelOptions,
): NoteLabelResult {
// Vault-identity write guard (context-integrity-gates, Unit J).
assertVaultIdentityForWrite(vault);
// The operator's standing rules are refused by NAME here. This surface
// takes a caller-named path and reaches the file through
// `resolveNotePath`, which enforces containment and symlinks and nothing
// about which file is being written, so the Brain-root refusal that
// protects the note-write tools does not reach it. Placed before the
// vocabulary check so the refusal is about the target rather than about
// whichever dimension the caller happened to invent.
assertStandingRulesNotTargeted(vault, relPath, LABEL_ASSIGN_SURFACE);
// The other caller-named-write walls bind this surface too: the write
// binding's own authority (`Brain/_brain.yaml`) and the operator's
// declared write binding. Without this, a caller-named label write
// rewrote frontmatter anywhere in the vault regardless of the binding.
governCallerNamedWritePath(vault, relPath, LABEL_ASSIGN_SURFACE);
const assignment = validateLabelAssignment(opts.pack, opts.dimension, opts.value);
const path = resolveNotePath(
vault,
relPath,
opts.readable !== undefined ? { readable: opts.readable } : {},
);
const [metadata, body] = parseFrontmatter(path);
const existing = readLabels(metadata);
const kept = existing.filter((token) => !token.startsWith(`${assignment.dimension}/`));
const next = [...kept, assignment.token].toSorted((a, b) => a.localeCompare(b));
const changed = !sameLabels(existing, next);
if (changed) {
const nextMetadata = { ...metadata, labels: next };
writeFrontmatterAtomic(path, nextMetadata, body, { overwrite: true });
}
upsertEntity(vault, {
category: LABEL_ENTITY_CATEGORY,
name: assignment.token,
agent: opts.agent,
now: opts.now,
});
return { path: relPath, labels: next, changed };
}
/**
* Remove a dimension's label from a note. The canonical label entity
* stays in the registry - other notes may still carry the label, and
* an orphaned label entity is harmless vocabulary, not corruption.
*/
export function removeNoteLabel(
vault: string,
relPath: string,
opts: RemoveNoteLabelOptions,
): RemoveNoteLabelResult {
// Vault-identity write guard (context-integrity-gates, Unit J).
assertVaultIdentityForWrite(vault);
// Removal rewrites the same frontmatter with the same overwrite, so it
// is the same write and takes the same refusals.
assertStandingRulesNotTargeted(vault, relPath, LABEL_REMOVE_SURFACE);
governCallerNamedWritePath(vault, relPath, LABEL_REMOVE_SURFACE);
const dimension = normalizeSchemaToken(opts.dimension);
const path = resolveNotePath(
vault,
relPath,
opts.readable !== undefined ? { readable: opts.readable } : {},
);
const [metadata, body] = parseFrontmatter(path);
const existing = readLabels(metadata);
const next = existing.filter((token) => !token.startsWith(`${dimension}/`));
const removed = next.length !== existing.length;
if (removed) {
const nextMetadata = { ...metadata };
if (next.length > 0) nextMetadata["labels"] = next;
else delete nextMetadata["labels"];
writeFrontmatterAtomic(path, nextMetadata, body, { overwrite: true });
}
return { path: relPath, labels: next, changed: removed, removed };
}
/** Read the validated string entries of a note's `labels` array. */
export function readLabels(metadata: Record<string, unknown>): string[] {
const raw = metadata["labels"];
if (!Array.isArray(raw)) return [];
return raw.filter((entry): entry is string => typeof entry === "string");
}
function sameLabels(left: ReadonlyArray<string>, right: ReadonlyArray<string>): boolean {
return left.length === right.length && left.every((token, index) => token === right[index]);
}