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 shared marker-fenced rules-block writer for agent instruction files.
*
* ONE writer owns every byte that enters a managed block in a vault-root
* agent rules file (AGENTS.md / CLAUDE.md / GEMINI.md). Two producers call
* it and neither writes such a file any other way:
*
* - the `usage` producer (the installer, `src/core/install/
* instruction-block.ts`) writes the ambient write-back gate block,
* - the `lessons` producer (the operator verbs over
* `src/core/brain/lessons-promotion.ts`) promotes approved lessons
* into a sibling block.
*
* The two producers coexist in ONE file because each block id carries its
* OWN marker spelling: `usage` keeps the settled default managed-block
* markers (the write-back contract's contract spellings,
* `src/core/brain/writeback-contract.ts`), `lessons` uses a distinct
* HTML-comment pair. The editor below validates one pair per spelling, so
* a second block never fights the first (t_1e952e43, section 3.3).
*
* Invariants, each pinned by `tests/core/install/rules-block.test.ts`:
*
* - every operator byte OUTSIDE the block is preserved (the
* `managed-block.ts` editor guarantee);
* - a re-apply with the canonical body is a byte no-op (`changed:
* false`), so producers can run on every render;
* - CRLF files keep CRLF line endings, detected and restored by the
* editor;
* - the first write to an existing file takes an exclusive-create,
* collision-laddered backup beside the file and returns its path; a
* no-op takes none;
* - a block whose body diverges from the canonical body on a file
* NEWER than the recorded install time is a hand edit: refused with
* kind `user-modified-block` unless `force` (the aider adapter's
* safety net, generalised here so both producers share it). A
* diverged block on a file OLDER than the install time is a canonical
* body that moved under an untouched file: rewritten, not refused.
* No install time at all refuses too - a block nobody recorded cannot
* be proven ours, and silently replacing it would clobber operator
* text. The same refusal covers a file that cannot be re-statted at
* gate time and an install stamp that sits in the future: neither can
* prove the block untouched, and the gate fails closed;
* - the bytes the merge was based on are re-checked before anything is
* written, and again inside the atomic writer immediately before the
* rename. A mid-flight edit elsewhere refuses with kind
* `concurrent-modification`, leaving the file and any backup
* untouched; `force` is the deliberate overwrite;
* - symbolic links are refused before any read or write: a writer that
* follows a link has left the file the audit measures;
* - multiple, unpaired or reversed markers of the block's OWN spelling
* refuse with a wrapped `ManagedBlockError`; a different spelling's
* stray markers never block this block;
* - `dryRun` computes and refuses exactly like a real run and writes
* nothing on every path.
*
* This module reads and writes single files named by the caller and
* reaches the disk only through the shared atomic writers
* (`src/core/fs-atomic.ts`): it joins no vault path, keeps no state, and
* never removes a file - removal means rewriting the file without the
* block.
*/
import { lstatSync, readFileSync, statSync } from "node:fs";
import {
atomicCreateFileSyncExclusive,
atomicWriteFileSync,
fileMatchesExpected,
isFileAlreadyExists,
isFileDrift,
} from "../fs-atomic.ts";
import {
DEFAULT_BEGIN_MARKER,
DEFAULT_END_MARKER,
ManagedBlockError,
extractManagedBlock,
insertManagedBlock,
removeManagedBlock,
type BlockOpts,
} from "./managed-block.ts";
// ----- Errors ---------------------------------------------------------------
/** Why a rules-block operation refused, as a closed vocabulary. */
export const RULES_BLOCK_ERROR_KIND = Object.freeze({
/** The path could not be stat'ed or read as a file. */
unreadable: "unreadable",
/** The path is a symbolic link; the operation refuses to follow it. */
symlink: "symlink",
/** The block's own markers are multiple, unpaired or reversed. */
markers: "markers",
/** The block diverged from the canonical body on a hand-edited file. */
userModifiedBlock: "user-modified-block",
/**
* The on-disk bytes moved since the caller's approved preview. Thrown
* by the installer's plan/apply binding
* (`src/core/install/instruction-block.ts`), which re-derives the
* preview at apply time and must refuse a write of anything else.
*/
previewDrift: "preview-drift",
/**
* The approved preview does not name a file this installer could have
* derived: a path off the vault root, or not an agent-instruction file
* at all. A plan that was not produced against this vault must never
* be applied to it.
*/
invalidPlan: "invalid-plan",
/**
* The on-disk bytes moved while the operation was being prepared: the
* merge or removal was based on bytes that are no longer current.
* Nothing was written and no backup was taken; the operator re-runs
* the command (a re-run re-reads the file and converges) or passes
* `--force` to overwrite the current bytes deliberately.
*/
concurrentModification: "concurrent-modification",
} as const);
/** Closed union over {@link RULES_BLOCK_ERROR_KIND}. */
export type RulesBlockErrorKind =
(typeof RULES_BLOCK_ERROR_KIND)[keyof typeof RULES_BLOCK_ERROR_KIND];
/**
* A rules-block refusal, named so callers branch on `kind` and never on
* message text. Marker-shape refusals carry the editor's own
* `ManagedBlockError` as their `cause`: one validation vocabulary, two
* error surfaces.
*/
export class RulesBlockError extends Error {
constructor(
message: string,
public readonly kind: RulesBlockErrorKind,
public readonly path: string,
options?: { readonly cause?: unknown },
) {
super(message, options);
this.name = "RulesBlockError";
}
}
// ----- Block identity -------------------------------------------------------
/** The managed blocks this writer installs into agent rules files. */
export const RULES_BLOCK_ID = Object.freeze({
/** The ambient write-back gate block, the write-back contract's subject. */
usage: "usage",
/** The operator-approved lessons block (t_1e952e43). */
lessons: "lessons",
} as const);
/** Closed union over {@link RULES_BLOCK_ID}. */
export type RulesBlockId = (typeof RULES_BLOCK_ID)[keyof typeof RULES_BLOCK_ID];
/**
* Each block id's marker spelling. The `usage` entry IS the settled
* default managed-block pair - the write-back contract audits those exact
* lines, so they are re-exported rather than re-spelled. The `lessons`
* entry is a distinct HTML-comment pair so both blocks can live in one
* file: the editor holds one pair per spelling, and spellings never share
* a marker line.
*/
export const RULES_BLOCK_MARKERS: Readonly<
Record<RulesBlockId, { readonly begin: string; readonly end: string }>
> = Object.freeze({
usage: Object.freeze({ begin: DEFAULT_BEGIN_MARKER, end: DEFAULT_END_MARKER }),
lessons: Object.freeze({
begin: "<!-- >>> open-second-brain lessons >>> -->",
end: "<!-- >>> open-second-brain lessons <<< -->",
}),
});
/** The markers for `blockId`, as the editor's option shape. */
function blockOpts(blockId: RulesBlockId): BlockOpts {
const markers = RULES_BLOCK_MARKERS[blockId];
return { beginMarker: markers.begin, endMarker: markers.end };
}
// ----- Rendering ------------------------------------------------------------
export interface RenderedRulesBlock {
readonly beginMarker: string;
readonly endMarker: string;
/** The full file a NEW rules file starts as, trailing newline included. */
readonly document: string;
}
/**
* Render the fenced document `body` becomes in a rules file. The document
* is produced by the same editor call a write to an absent file takes, so
* a rendered preview and a real first write cannot disagree.
*/
export function renderRulesBlock(blockId: RulesBlockId, body: string): RenderedRulesBlock {
const markers = RULES_BLOCK_MARKERS[blockId];
return {
beginMarker: markers.begin,
endMarker: markers.end,
document: insertManagedBlock("", body, blockOpts(blockId)),
};
}
// ----- Reading --------------------------------------------------------------
interface ReadResult {
/** Whether any file exists at the path. */
readonly exists: boolean;
/** The file's bytes as read; the empty string when it does not exist. */
readonly content: string;
/** The file's mtime in ms, from the same lstat the refusal used. */
readonly mtimeMs: number;
/** True when a well-formed pair of this spelling exists. */
readonly present: boolean;
/** The extracted body; null unless `present`. */
readonly body: string | null;
}
/**
* lstat the file, refusing symbolic links and absent paths by name, then
* read it and decide whether a well-formed pair of this spelling exists.
*
* The marker shapes are decided here so the refusals can be NAMED rather
* than collapsed into a null: multiple, unpaired or reversed markers of
* this spelling throw {@link RulesBlockError} wrapping the editor's
* `ManagedBlockError`, while a file with no marker line of this spelling
* at all is simply `present: false`. Extraction itself stays the editor's
* (`extractManagedBlock`), so reading can never disagree with writing.
*/
function readRulesFile(file: string, blockId: RulesBlockId): ReadResult {
let stat;
try {
stat = lstatSync(file);
} catch (err) {
if ((err as NodeJS.ErrnoException).code === "ENOENT") {
return { exists: false, content: "", mtimeMs: 0, present: false, body: null };
}
throw new RulesBlockError(
`${file} could not be stat'ed: ${reason(err)}`,
RULES_BLOCK_ERROR_KIND.unreadable,
file,
{ cause: err },
);
}
if (stat.isSymbolicLink()) {
throw new RulesBlockError(
`${file} is a symbolic link - the rules-block writer refuses to follow symlinks, ` +
"because a write through a link lands outside the file the audit measures",
RULES_BLOCK_ERROR_KIND.symlink,
file,
);
}
let content: string;
try {
content = readFileSync(file, "utf8");
} catch (err) {
throw new RulesBlockError(
`${file} could not be read: ${reason(err)}`,
RULES_BLOCK_ERROR_KIND.unreadable,
file,
{ cause: err },
);
}
return { exists: true, content, mtimeMs: stat.mtimeMs, ...blockStateIn(content, blockId, file) };
}
/**
* Whether `content` carries this block, and its body, without touching
* the filesystem. Absent is silent; a malformed pair of this spelling is
* a named refusal wrapping `ManagedBlockError`.
*/
function blockStateIn(
content: string,
blockId: RulesBlockId,
file: string,
): { present: boolean; body: string | null } {
const markers = RULES_BLOCK_MARKERS[blockId];
const lines = content.replace(/\r\n/g, "\n").split("\n");
let begins = 0;
let ends = 0;
for (const line of lines) {
if (line === markers.begin) begins += 1;
if (line === markers.end) ends += 1;
}
if (begins === 0 && ends === 0) return { present: false, body: null };
// The editor's validator refuses every non-single-pair shape; drive it
// through a pure re-insert so the message vocabulary stays the editor's.
try {
insertManagedBlock(content, "shape probe", blockOpts(blockId));
} catch (err) {
if (err instanceof ManagedBlockError) {
throw new RulesBlockError(
`${markers.begin} / ${markers.end}: ${err.message} - fix or remove the broken ` +
"block before this operation can run",
RULES_BLOCK_ERROR_KIND.markers,
file,
{ cause: err },
);
}
throw err;
}
const body = extractManagedBlock(content, blockOpts(blockId));
if (body === null) {
// One begin, one end, in order - yet the editor could not extract.
// Unreachable per the editor's contract; refused rather than guessed.
throw new RulesBlockError(
`${markers.begin} / ${markers.end}: a well-formed pair validated but extracted no body`,
RULES_BLOCK_ERROR_KIND.markers,
file,
);
}
return { present: true, body };
}
/** One line an fs error message, so a multi-line reason stays one detail. */
function reason(err: unknown): string {
const message = err instanceof Error ? err.message : String(err);
return message.replace(/\s+/g, " ").trim();
}
/**
* The block body `file` carries for `blockId`, or null when the file (or
* the pair of this spelling) does not exist. Malformed pairs and symlinks
* refuse by name - a reader that silently ignored either would report a
* block absent that is in fact broken or unreadable.
*/
export function readRulesBlock(file: string, blockId: RulesBlockId): string | null {
return readRulesFile(file, blockId).body;
}
// ----- Drift ----------------------------------------------------------------
/** How a managed block compares to the canonical body it should carry. */
export const RULES_BLOCK_STATE = Object.freeze({
/** No file, or no pair of this spelling in it. */
absent: "absent",
/** The pair exists and its body matches the canonical body. */
current: "current",
/** The pair exists but its body diverged from the canonical body. */
drifted: "drifted",
} as const);
/** Closed union over {@link RULES_BLOCK_STATE}. */
export type RulesBlockState = (typeof RULES_BLOCK_STATE)[keyof typeof RULES_BLOCK_STATE];
export interface RulesBlockDriftResult {
readonly state: RulesBlockState;
/** The extracted body; null unless the pair exists. */
readonly extracted: string | null;
}
/** True when two block bodies are the same text, ignoring the fence-adjacent trailing newline. */
function sameBlockBody(extracted: string, canonical: string): boolean {
return stripTrailingNewline(extracted) === stripTrailingNewline(canonical);
}
function stripTrailingNewline(text: string): string {
return text.replace(/[\r\n]+$/, "");
}
/**
* Compare `file`'s block for `blockId` against `canonicalBody`. READ-ONLY:
* producers call it to decide whether a write is owed, and doctor and
* status surfaces call it to grade a managed block without writing.
* Malformed pairs and symlinks refuse by name, as in
* {@link readRulesBlock}.
*/
export function rulesBlockDrift(
file: string,
blockId: RulesBlockId,
canonicalBody: string,
): RulesBlockDriftResult {
const read = readRulesFile(file, blockId);
if (!read.present) return { state: RULES_BLOCK_STATE.absent, extracted: null };
return {
state: sameBlockBody(read.body as string, canonicalBody)
? RULES_BLOCK_STATE.current
: RULES_BLOCK_STATE.drifted,
extracted: read.body,
};
}
// ----- Writing --------------------------------------------------------------
export interface RulesBlockWriteOptions {
/** Plan the write and touch nothing. Refusals still fire. */
readonly dryRun?: boolean;
/** Override the hand-edit refusal and write the canonical body. */
readonly force?: boolean;
/**
* The install time recorded for this block, in ms. A diverged block on
* a file newer than this (plus a small clock slack) is a hand edit and
* refuses unless `force`; a diverged block on an older file is a
* canonical body that moved and is rewritten. `null` or omitted means
* no ownership record exists, so every diverged block refuses - a block
* nobody recorded cannot be proven ours. A stamp further than
* {@link FUTURE_ANCHOR_ALLOWANCE_MS} into the future counts as no
* record either: a future stamp would silently disarm the gate.
*/
readonly installedAtMs?: number | null;
/** Test seams for the race-window refusals; production omits them. */
readonly seams?: RulesBlockSeams;
}
/**
* Test-only indirections over the two re-reads the fail-closed gates
* perform, so the race-window refusals can be pinned deterministically
* without racing a real second writer (the same pattern as
* `RenameRetrySeams` in `src/core/fs-atomic.ts`). Production callers
* never pass this.
*/
export interface RulesBlockSeams {
/**
* The mtime the hand-edit gate reads from the live file; null models a
* stat failure (a mid-flight move). Defaults to a real `statSync`.
*/
readonly fileMtimeMs?: (path: string) => number | null;
/**
* The current-bytes comparison behind the drift refusal; false models
* the file having moved since the merge read it. Defaults to
* `fileMatchesExpected` from `src/core/fs-atomic.ts`.
*/
readonly currentBytesMatch?: (target: string, expected: string | null) => boolean;
}
export interface RulesBlockWriteResult {
/** True when the file's bytes changed (or would, under `dryRun`). */
readonly changed: boolean;
/** The exclusive-create backup of the prior bytes; null when none was taken. */
readonly backupPath: string | null;
}
/**
* Bound on distinct backup names one stamp tries (`<file>.bak.<ms>`,
* `-2`, ...). Exhaustion is a typed refusal, never an overwrite.
*/
export const RULES_BLOCK_BACKUP_MAX_ATTEMPTS = 128;
/**
* Clock slack between the recorded install time and the file mtime, in
* ms. The aider adapter's precedent: a write that lands within a second
* of its own record must not read as a later hand edit.
*/
const MTIME_SLACK_MS = 1000;
/**
* How far past `Date.now()` an install or promotion anchor may sit and
* still count as a record: a small clock-skew allowance. An anchor any
* further into the future is treated as NO record - the fail-closed
* direction - because the anchor lives in agent-writable state, and a
* future-stamped record would make every later operator hand-edit read
* as a canonical move under an untouched file, silently disarming the
* hand-edit gate.
*/
export const FUTURE_ANCHOR_ALLOWANCE_MS = 5 * 60 * 1000;
/** Candidate `attempt` of the backup-name ladder. */
function collisionCandidate(base: string, attempt: number): string {
return attempt === 1 ? base : `${base}-${attempt}`;
}
/**
* Back the current bytes up beside `file` before the first rewrite.
* Exclusive create (`link(2)`, `src/core/fs-atomic.ts`), private 0600,
* same-millisecond collisions ladder the name, and an exhausted ladder is
* a typed refusal rather than a silent overwrite.
*/
function backupRulesFile(file: string, before: string): string {
const base = `${file}.bak.${Date.now()}`;
for (let attempt = 1; attempt <= RULES_BLOCK_BACKUP_MAX_ATTEMPTS; attempt++) {
try {
atomicCreateFileSyncExclusive(collisionCandidate(base, attempt), before, { mode: 0o600 });
return collisionCandidate(base, attempt);
} catch (err) {
if (!isFileAlreadyExists(err)) throw err;
}
}
throw new RulesBlockError(
`backup allocation exhausted for ${file} (${RULES_BLOCK_BACKUP_MAX_ATTEMPTS} candidates ` +
"taken); refusing to overwrite",
RULES_BLOCK_ERROR_KIND.unreadable,
file,
);
}
/**
* Write (or plan) the managed block for `blockId` in `file`, carrying
* `canonicalBody` between the markers.
*
* Absent file: the file is created with just the rendered block - no
* backup, because there are no prior bytes. Existing file: the editor
* inserts or replaces the pair of this spelling, every byte outside it
* preserved; the first byte-changing write takes an exclusive-create
* backup of the current bytes and returns its path. A byte-identical
* re-apply reports `changed: false` and takes no backup.
*
* Refusals, all named: symlinks (`symlink`), unreadable paths
* (`unreadable`), malformed marker pairs of this spelling (`markers`,
* wrapping `ManagedBlockError`), a hand-edited block
* (`user-modified-block`) when the body diverged from the canonical body
* and the file is newer than `installedAtMs` - or when no trustworthy
* install time is known at all, which includes a file that cannot be
* re-statted at gate time and a stamp sitting in the future - and a
* mid-flight edit elsewhere (`concurrent-modification`). `force`
* overrides the hand-edit refusal and the drift refusal; it is the
* operator's deliberate overwrite.
*/
export function writeRulesBlock(
file: string,
blockId: RulesBlockId,
canonicalBody: string,
opts: RulesBlockWriteOptions = {},
): RulesBlockWriteResult {
const read = readRulesFile(file, blockId);
const absent = !read.exists;
const next = absent
? renderRulesBlock(blockId, canonicalBody).document
: insertManagedBlock(read.content, canonicalBody, blockOpts(blockId));
if (next === read.content) return { changed: false, backupPath: null };
// The hand-edit safety net: a diverged block on a file the operator
// touched after the install (or with no trustworthy recorded install)
// is theirs until `force` says otherwise.
if (read.present) {
const diverged = !sameBlockBody(read.body as string, canonicalBody);
const anchor =
typeof opts.installedAtMs === "number" && Number.isFinite(opts.installedAtMs)
? opts.installedAtMs
: null;
const anchorTrusted = anchor !== null && anchor <= Date.now() + FUTURE_ANCHOR_ALLOWANCE_MS;
const mtime = (opts.seams?.fileMtimeMs ?? fileMtimeMs)(file);
const touchedAfterInstall =
!anchorTrusted || mtime === null || mtime > (anchor as number) + MTIME_SLACK_MS;
if (diverged && touchedAfterInstall && !opts.force) {
const gateDetail =
anchor !== null && !anchorTrusted
? " - the recorded install time is in the future and is treated as no record"
: mtime === null
? " - the file could not be re-statted, so it cannot be proven untouched"
: "";
throw new RulesBlockError(
`${file} appears hand-edited after the last install (the ${blockId} block diverges ` +
`from canonical content${gateDetail}); refusing to overwrite. ` +
"Re-run with --force to overwrite, or uninstall first",
RULES_BLOCK_ERROR_KIND.userModifiedBlock,
file,
);
}
}
// The drift guard: the merge above was computed from the bytes the
// first read saw. If those are no longer current, writing would clobber
// an edit this run never saw - refused before the backup is taken, so
// the refused run touches nothing. The atomic writer re-checks the same
// expectation immediately before the rename, closing the window this
// pre-check leaves; a drift surfacing there is wrapped into the same
// named refusal.
const expected = absent ? null : read.content;
const concurrentMessage =
`${file} changed while the ${blockId} block write was being prepared; refusing to ` +
"overwrite bytes this run never saw. Re-run the command to converge, or pass " +
"--force to overwrite the current bytes deliberately";
if (!opts.force && !(opts.seams?.currentBytesMatch ?? fileMatchesExpected)(file, expected)) {
throw new RulesBlockError(
concurrentMessage,
RULES_BLOCK_ERROR_KIND.concurrentModification,
file,
);
}
if (opts.dryRun) {
return { changed: true, backupPath: null };
}
const backupPath = absent ? null : backupRulesFile(file, read.content);
try {
atomicWriteFileSync(file, next, opts.force ? {} : { expectBefore: expected });
} catch (err) {
if (isFileDrift(err)) {
throw new RulesBlockError(
concurrentMessage,
RULES_BLOCK_ERROR_KIND.concurrentModification,
file,
{
cause: err,
},
);
}
throw err;
}
return { changed: true, backupPath };
}
function fileMtimeMs(path: string): number | null {
try {
return statSync(path, { throwIfNoEntry: false })?.mtimeMs ?? null;
} catch {
return null;
}
}
export interface RulesBlockRemoveOptions {
/** Plan the removal and touch nothing. */
readonly dryRun?: boolean;
/** Test seams for the race-window refusal; production omits them. */
readonly seams?: RulesBlockSeams;
}
export interface RulesBlockRemoveResult {
/**
* True when the file will change (or changed): the pair of this
* spelling existed and the file is rewritten without it.
*/
readonly removed: boolean;
}
/**
* Remove the managed block for `blockId` from `file`: rewrite the file
* without that marker pair and its body, collapsing the padding the pair
* carried, every other byte preserved. A file with no pair of this
* spelling is a NAMED SKIP (`removed: false`), not an error, so
* uninstalling an install that never landed stays quiet. The file itself
* is never removed. Symlinks refuse by name, as everywhere above, and
* the same drift guard as the write path refuses a mid-flight edit with
* kind `concurrent-modification`, leaving the file untouched.
*/
export function removeRulesBlock(
file: string,
blockId: RulesBlockId,
opts: RulesBlockRemoveOptions = {},
): RulesBlockRemoveResult {
const read = readRulesFile(file, blockId);
const state = blockStateIn(read.content, blockId, file);
if (!state.present) return { removed: false };
const next = removeManagedBlock(read.content, blockOpts(blockId));
if (next === read.content) return { removed: false };
const concurrentMessage =
`${file} changed while the ${blockId} block removal was being prepared; refusing to ` +
"overwrite bytes this run never saw. Re-run the removal to converge";
if (!(opts.seams?.currentBytesMatch ?? fileMatchesExpected)(file, read.content)) {
throw new RulesBlockError(
concurrentMessage,
RULES_BLOCK_ERROR_KIND.concurrentModification,
file,
);
}
if (opts.dryRun) return { removed: true };
try {
atomicWriteFileSync(file, next, { expectBefore: read.content });
} catch (err) {
if (isFileDrift(err)) {
throw new RulesBlockError(
concurrentMessage,
RULES_BLOCK_ERROR_KIND.concurrentModification,
file,
{
cause: err,
},
);
}
throw err;
}
return { removed: true };
}