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 brain-usage block installer step for agent instruction files
* (t_ba41a78a), the producer the write-back contract anticipated.
*
* Upstream installers finish by writing a "use the brain" instruction
* block into the harness's own rules file; without one, a host that never
* loads an OSB hook never learns the brain exists, and the audited
* write-gate block is graded `missing-block` forever. This module is the
* narrow missing half: an install step that writes the canonical
* write-gate block (t_ba41a78a K2, {@link CANONICAL_WRITEBACK_BLOCK_BODY})
* into the agent-instruction file the installed host actually reads, at
* the VAULT root - the same workspace `o2b doctor --readiness` audits, so
* the probe grades exactly what install wrote.
*
* Which file, per host: {@link instructionBlockTargetFor} reads
* `HOST_INSTRUCTION_PRECEDENCE` - codex, cursor, opencode and aider read
* AGENTS.md, gemini-cli reads GEMINI.md (name-implied only, an open
* question that table's docblock already carries, surfaced as a plan note
* here rather than resolved by pretending certainty), and targets with no
* entry are a named skip. The mapping never forks a second host-to-file
* table.
*
* Every byte goes through the shared rules-block writer
* (`src/core/install/rules-block.ts`), never through a direct fs write:
* operator content outside the block is preserved byte-for-byte, the
* first write backs up exclusively, a re-apply is a byte no-op, and a
* hand-edited block refuses with `user-modified-block` unless forced.
*
* The apply is bound to the approved preview (the `o2b brain protect`
* pattern): {@link applyInstructionBlock} re-derives the plan from the
* live disk and refuses with `preview-drift` unless every field the
* consent was shown still holds - a write of anything but the approved
* bytes is a typed refusal, never a fallback.
*
* Ownership is recorded in
* `<vault>/.open-second-brain/instruction-block.lock.json`
* ({@link INSTRUCTION_BLOCK_LOCK_FILE}, the derived store beside
* `install.lock.json`): per file, which block owns the fence, the begin
* marker, and the applied time that drives the hand-edit refusal. The
* lock is what uninstall reads to remove exactly the pair this tool
* wrote. It is machine state, not a credential, and is declared in the
* state-surface inventory.
*
* Layering: core here, so no stdout, no exit codes, no prompts - the CLI
* (`src/cli/install/install.ts`) owns consent, rendering and exits.
*/
import { existsSync, lstatSync, mkdirSync, readFileSync, statSync } from "node:fs";
import { basename, dirname, join } from "node:path";
import { DERIVED_STORE_DIR } from "../brain/path-constants.ts";
import {
AGENT_INSTRUCTION_FILES,
CANONICAL_WRITEBACK_BLOCK_BODY,
HOST_INSTRUCTION_PRECEDENCE,
} from "../brain/writeback-contract.ts";
import { renderUnifiedDiff } from "../diff.ts";
import { atomicWriteFileSync } from "../fs-atomic.ts";
import { ManagedBlockError, insertManagedBlock, type BlockOpts } from "./managed-block.ts";
import {
RULES_BLOCK_ERROR_KIND,
RULES_BLOCK_ID,
RULES_BLOCK_MARKERS,
type RulesBlockId,
RulesBlockError,
removeRulesBlock,
writeRulesBlock,
} from "./rules-block.ts";
import type { InstallEnv } from "./types.ts";
import type { InstallTargetId } from "../runtime/host-facts.ts";
import { machineStatePath } from "../state/machine-state.ts";
// ----- Target mapping -------------------------------------------------------
/**
* The agent-instruction file `target`'s host reads at the vault root, or
* null when the host has no entry in `HOST_INSTRUCTION_PRECEDENCE` - a
* NAMED SKIP: such a target installs its adapter but no instruction step,
* and the plan says so rather than guessing a file. Derived from the
* table, so the checker and the installer can never disagree about which
* file a host reads; if the table grows, this follows it.
*/
export function instructionBlockTargetFor(target: InstallTargetId): string | null {
const files = (HOST_INSTRUCTION_PRECEDENCE as Readonly<Record<string, readonly string[]>>)[
target
];
return files?.[0] ?? null;
}
/**
* The named skip both install lanes record when `target` maps no
* agent-instruction file in `HOST_INSTRUCTION_PRECEDENCE`: one owner for
* the sentence the plan's post note, the uninstall payload's
* `skipped_reason` and the apply payload's `instruction_block` skip all
* carry, so the two JSON receipts cannot drift apart.
*/
export function instructionStepNoPrecedenceReason(target: InstallTargetId): string {
return `${target} reads no agent-instruction file in HOST_INSTRUCTION_PRECEDENCE`;
}
// ----- Plan -----------------------------------------------------------------
export interface InstructionBlockPlan {
/** The vault-root file the step would rewrite. */
readonly path: string;
/** Whether the file exists today; false means apply would create it. */
readonly exists: boolean;
/** Whether applying would change the file's bytes. */
readonly changed: boolean;
/** Unified diff of the rewrite; empty when `changed` is false. */
readonly diff: string;
/**
* The caveat or named note the consent render owes the operator, or
* null when the step is unremarkable. The gemini-cli reading caveat
* and the absent-file creation note land here.
*/
readonly note: string | null;
}
/**
* Plan notes keyed by instruction file, not by target: the caveat is
* about the FILE (how its host resolves it), and two targets mapping to
* one file must render the same honest sentence.
*/
const FILE_PLAN_NOTES: Readonly<Record<string, string>> = Object.freeze({
"GEMINI.md":
"gemini-cli reading GEMINI.md is name-implied only; upstream context.fileName can rename " +
"the surface, so the write follows the declared table and the readiness probe audits " +
"what the host actually sees",
});
/** The plan note for a file the apply would create. */
function creationNote(name: string): string {
return `creates ${name} at the vault root; the file becomes visible to the host agent and the vault indexer`;
}
/** Plan for one instruction file, by name. Pure read plus diff render. */
function planForFile(env: InstallEnv, name: string): InstructionBlockPlan {
const path = join(env.vault, name);
let exists: boolean;
let before: string;
try {
// The checker's posture: lstat first, refuse a link before any read.
const stat = lstatSync(path);
if (stat.isSymbolicLink()) {
throw new RulesBlockError(
`${path} is a symbolic link - the installer refuses to follow symlinks, because a ` +
"write through a link lands outside the file the write-back contract audits",
RULES_BLOCK_ERROR_KIND.symlink,
path,
);
}
exists = true;
before = readFileSync(path, "utf8");
} catch (err) {
if (err instanceof RulesBlockError) throw err;
if ((err as NodeJS.ErrnoException).code === "ENOENT") {
exists = false;
before = "";
} else {
throw new RulesBlockError(
`${path} could not be read: ${reasonOf(err)}`,
RULES_BLOCK_ERROR_KIND.unreadable,
path,
{ cause: err },
);
}
}
let after: string;
try {
after = insertManagedBlock(before, CANONICAL_WRITEBACK_BLOCK_BODY, usageBlockOpts());
} catch (err) {
// A malformed pair of the block's own spelling refuses the plan the
// same way the write would; broken markers are a fix-by-hand state,
// never a repair the installer performs (the readiness probe is the
// surface that grades it `malformed-block`).
if (err instanceof ManagedBlockError) {
throw new RulesBlockError(
`${path}: ${err.message} - fix or remove the broken block; the installer refuses ` +
"to write into a file with malformed markers",
RULES_BLOCK_ERROR_KIND.markers,
path,
{ cause: err },
);
}
throw err;
}
const changed = after !== before;
const notes: string[] = [];
const fileNote = FILE_PLAN_NOTES[name];
if (fileNote !== undefined) notes.push(fileNote);
if (!exists) notes.push(creationNote(name));
return {
path,
exists,
changed,
diff: changed ? renderUnifiedDiff(before, after, path) : "",
note: notes.length > 0 ? notes.join("; ") : null,
};
}
/** One line an fs error message, so a multi-line reason stays one detail. */
function reasonOf(err: unknown): string {
const message = err instanceof Error ? err.message : String(err);
return message.replace(/\s+/g, " ").trim();
}
/**
* Plan the instruction step for `target` against the vault `env` names.
* Pure: reads the candidate file, renders what apply would write, writes
* nothing, records nothing. A target with no precedence entry has no
* plan - the caller renders the named skip from
* {@link instructionBlockTargetFor} instead.
*/
export function planInstructionBlock(
env: InstallEnv,
target: InstallTargetId,
): InstructionBlockPlan {
const name = instructionBlockTargetFor(target);
if (name === null) {
throw new RulesBlockError(
`${target} installs no agent-instruction file: HOST_INSTRUCTION_PRECEDENCE has no ` +
"entry for it, so there is no instruction step to plan",
RULES_BLOCK_ERROR_KIND.invalidPlan,
target,
);
}
return planForFile(env, name);
}
/** The usage block's markers, as the editor's option shape. */
function usageBlockOpts(): BlockOpts {
const markers = RULES_BLOCK_MARKERS[RULES_BLOCK_ID.usage];
return { beginMarker: markers.begin, endMarker: markers.end };
}
// ----- Apply ----------------------------------------------------------------
export interface InstructionBlockApplyOptions {
/** 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 plan the consent verdict was rendered from. Required. */
readonly approved: InstructionBlockPlan;
}
export interface InstructionBlockApplyResult {
/** The exclusive-create backup of the prior bytes; null when none was taken. */
readonly backupPath: string | null;
/** True when the apply changed the file's bytes (or would, under `dryRun`). */
readonly changed: boolean;
/**
* True when the apply CREATED the file: it did not exist when the plan
* was re-derived. A first install takes no backup (there are no prior
* bytes), so `backupPath === null` cannot distinguish "created" from
* "already current" - the CLI's post-apply line branches on this field.
*/
readonly created: boolean;
}
/**
* Apply the approved instruction plan: re-derive it from the live disk
* and refuse unless it still holds, then write through the shared rules
* block writer and record the ownership lock.
*
* The preview binding: the apply recomputes the plan and every compared
* field (`path`, `exists`, `changed`, `diff`) must equal the approved
* one, else the on-disk bytes moved since consent and the refusal is
* `preview-drift` - the write of an unapproved rewrite is never a
* fallback. A plan naming anything but the vault-root agent-instruction
* file it claims is refused as `invalid-plan`.
*
* The hand-edit safety net rides the writer: a block diverged from the
* canonical body on a file newer than the lock's `applied_at` refuses
* with `user-modified-block` unless `force`; with no lock record at all,
* every diverged block refuses too, which is what protects a manually
* pasted docs snippet - `--force` is the documented upgrade path, and the
* backup it takes is the undo path.
*
* A successful non-dry-run apply records the lock entry even when nothing
* changed: the apply ran under consent and found or left the canonical
* block, so uninstall can find the pair it owns. `dryRun` runs the same
* refusals and writes nothing - no file change, no backup, no lock.
*/
export function applyInstructionBlock(
env: InstallEnv,
opts: InstructionBlockApplyOptions,
): InstructionBlockApplyResult {
const approved = opts.approved;
const name = basename(approved.path);
if (
!(AGENT_INSTRUCTION_FILES as ReadonlyArray<string>).includes(name) ||
approved.path !== join(env.vault, name)
) {
throw new RulesBlockError(
`the approved plan names ${approved.path}, which is not the vault-root agent-instruction ` +
`file ${name} for this vault; refusing to apply a plan that was not derived here`,
RULES_BLOCK_ERROR_KIND.invalidPlan,
approved.path,
);
}
const fresh = planForFile(env, name);
if (
fresh.exists !== approved.exists ||
fresh.changed !== approved.changed ||
fresh.diff !== approved.diff
) {
throw new RulesBlockError(
`${approved.path} changed since the plan was approved; the apply refuses to write ` +
"anything but the approved bytes. Re-run `o2b install --target <host>` to refresh " +
"the plan, then apply again",
RULES_BLOCK_ERROR_KIND.previewDrift,
approved.path,
);
}
const stored = readInstructionBlockLock(env.vault).files[name];
const parsedAt = stored === undefined ? Number.NaN : Date.parse(stored.applied_at);
const installedAtMs = Number.isFinite(parsedAt) ? parsedAt : null;
const result = writeRulesBlock(
approved.path,
RULES_BLOCK_ID.usage,
CANONICAL_WRITEBACK_BLOCK_BODY,
{
dryRun: opts.dryRun ?? false,
force: opts.force ?? false,
installedAtMs,
},
);
if (!opts.dryRun) {
// Stamp the moment the bytes landed, as the written file's own mtime -
// the exact anchor the writer's hand-edit gate compares against.
// env.now predates the plan render, the consent prompt and the adapter
// apply, so a run-start stamp can sit more than the gate's one-second
// slack behind the file's mtime and make our OWN write read as a later
// hand edit on the next canonical-body upgrade: every interactive
// install would then refuse that upgrade with user-modified-block
// instead of taking the documented rewrite path. A file that cannot be
// re-statted falls back to the wall clock at record time, which still
// postdates the run start.
let landed = Date.now();
try {
landed = statSync(approved.path, { throwIfNoEntry: false })?.mtimeMs ?? landed;
} catch {
// Keep the wall-clock fallback: the same posture the writer's own
// mtime probe takes, so any stat failure (EACCES, ELOOP, EIO)
// records a real post-write stamp instead of leaving the fresh
// write unrecorded.
}
recordInstructionBlock(env.vault, name, {
block_id: RULES_BLOCK_ID.usage,
begin_marker: RULES_BLOCK_MARKERS.usage.begin,
applied_at: new Date(landed).toISOString(),
});
}
return {
backupPath: result.backupPath,
changed: result.changed,
created: result.changed && !fresh.exists,
};
}
// ----- Uninstall ------------------------------------------------------------
export interface InstructionBlockUninstallOptions {
/** Plan the removal and touch nothing. */
readonly dryRun?: boolean;
}
export interface InstructionBlockUninstallResult {
/** True when the file's bytes changed: the pair existed and is gone. */
readonly removed: boolean;
}
/**
* Remove the usage block pair from one instruction file, the reverse of
* {@link applyInstructionBlock}. The removal goes through the shared
* writer's remove: only the pair this tool owns is rewritten away,
* operator bytes preserved, the file itself never removed. A file with
* no pair of that spelling is a NAMED SKIP (`removed: false`), and a
* stale lock entry is cleared either way so the lock never claims a pair
* that is gone. Malformed markers refuse - uninstall never repairs - and
* symbolic links refuse before any read.
*/
export function uninstallInstructionBlock(
env: InstallEnv,
name: string,
opts: InstructionBlockUninstallOptions = {},
): InstructionBlockUninstallResult {
const path = join(env.vault, name);
const result = removeRulesBlock(path, RULES_BLOCK_ID.usage, opts);
if (!opts.dryRun) clearInstructionBlock(env.vault, name);
return { removed: result.removed };
}
// ----- Ownership lock -------------------------------------------------------
/** The lock file this installer records its owned blocks in. */
export const INSTRUCTION_BLOCK_LOCK_FILE = "instruction-block.lock.json";
/** The one schema the lock parses. A different number refuses. */
const INSTRUCTION_BLOCK_LOCK_SCHEMA_VERSION = 1;
export interface InstructionBlockLockEntry {
/** The block id whose fence this file carries. Always `usage` today. */
readonly block_id: RulesBlockId;
/** The begin marker recorded at apply time, for audit. */
readonly begin_marker: string;
/** When this installer last wrote (or confirmed) the block, ISO 8601. */
readonly applied_at: string;
}
export interface InstructionBlockLock {
readonly schema_version: 1;
/** Instruction file basename to its ownership entry. */
readonly files: Record<string, InstructionBlockLockEntry>;
}
/** The lock's path in `vault`'s derived store. */
export function instructionBlockLockPath(vault: string): string {
return machineStatePath(vault, DERIVED_STORE_DIR, INSTRUCTION_BLOCK_LOCK_FILE);
}
/**
* Read the ownership lock. An absent file is the empty schema-1 document
* - nothing owns a block yet - never an error, because uninstall must be
* able to run before any install. A symbolic link refuses (a redirected
* lock would read state this vault never wrote); corrupted JSON, a
* non-object document and an unsupported schema version refuse with the
* path in the message, the same posture the install manifest's parser
* holds.
*/
export function readInstructionBlockLock(vault: string): InstructionBlockLock {
const path = instructionBlockLockPath(vault);
let stat;
try {
stat = lstatSync(path);
} catch (err) {
if ((err as NodeJS.ErrnoException).code === "ENOENT") {
return { schema_version: INSTRUCTION_BLOCK_LOCK_SCHEMA_VERSION, files: {} };
}
throw new RulesBlockError(
`${path} could not be stat'ed: ${reasonOf(err)}`,
RULES_BLOCK_ERROR_KIND.unreadable,
path,
{ cause: err },
);
}
if (stat.isSymbolicLink()) {
throw new RulesBlockError(
`${path} is a symbolic link - the lock refuses to read through links, because a ` +
"redirected lock would report ownership this vault never recorded",
RULES_BLOCK_ERROR_KIND.symlink,
path,
);
}
let raw: string;
try {
raw = readFileSync(path, "utf8");
} catch (err) {
throw new RulesBlockError(
`${path} could not be read: ${reasonOf(err)}`,
RULES_BLOCK_ERROR_KIND.unreadable,
path,
{ cause: err },
);
}
let parsed: unknown;
try {
parsed = JSON.parse(raw);
} catch (err) {
throw new Error(
`instruction-block lock is corrupted JSON: ${path}\nOriginal error: ${(err as Error).message}`,
{ cause: err },
);
}
if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
throw new Error(`instruction-block lock is not an object: ${path}`);
}
const obj = parsed as Record<string, unknown>;
const sv = obj["schema_version"];
if (sv !== INSTRUCTION_BLOCK_LOCK_SCHEMA_VERSION) {
throw new Error(
`instruction-block lock schema_version ${sv} not supported (expected ` +
`${INSTRUCTION_BLOCK_LOCK_SCHEMA_VERSION}): ${path}`,
);
}
const files = (obj["files"] ?? {}) as Record<string, InstructionBlockLockEntry>;
if (typeof files !== "object" || Array.isArray(files)) {
throw new Error(`instruction-block lock files field is not an object: ${path}`);
}
return { schema_version: INSTRUCTION_BLOCK_LOCK_SCHEMA_VERSION, files };
}
/**
* Record (or replace) one file's ownership entry and write the lock
* atomically. The derived store is created on demand; the write is the
* shared atomic writer's, so a crash leaves either the previous lock or
* the new one.
*/
export function recordInstructionBlock(
vault: string,
name: string,
entry: InstructionBlockLockEntry,
): void {
const current = readInstructionBlockLock(vault);
writeInstructionBlockLock(vault, {
schema_version: INSTRUCTION_BLOCK_LOCK_SCHEMA_VERSION,
files: { ...current.files, [name]: entry },
});
}
/**
* Drop one file's ownership entry. A name the lock never recorded is a
* quiet no-op: uninstall of an install that never recorded must stay a
* skip, not an error.
*/
export function clearInstructionBlock(vault: string, name: string): void {
const current = readInstructionBlockLock(vault);
if (!(name in current.files)) return;
const files = { ...current.files };
delete files[name];
writeInstructionBlockLock(vault, {
schema_version: INSTRUCTION_BLOCK_LOCK_SCHEMA_VERSION,
files,
});
}
function writeInstructionBlockLock(vault: string, lock: InstructionBlockLock): void {
const path = instructionBlockLockPath(vault);
// The atomic writer creates the parent directory with the write; the
// explicit mkdir mirrors the install manifest's posture so a read-only
// store fails here, at the named call, rather than inside the writer.
const dir = dirname(path);
if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
atomicWriteFileSync(path, JSON.stringify(lock, null, 2) + "\n");
}