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 device-local migration gate (design D11 step 2). While a brain
* store migration runs on this machine, the gate file in the device-local
* state (`<state base>/open-second-brain/migration-gate.json`, never
* synced) names the vault it migrates, and every content writer on this
* machine refuses with a migration-in-progress message
* ({@link assertNoMigrationInProgress}, called from the vault-identity
* write guard every content writer passes).
*
* It replaces the vault freeze marker for the migration because that
* marker syncs: other machines keep writing during a migration here, and
* their writes reach the store through the delta pass and the transition
* import.
*
* The gate is one small JSON file, read once per content write (a missing
* file is one failed open). Vaults are compared by their real path, case
* folded on Windows, so a writer reaching the vault by another spelling
* (a link, a junction, another drive-letter case) is refused too.
*/
import { mkdirSync, readFileSync, realpathSync, unlinkSync } from "node:fs";
import { dirname, join, resolve } from "node:path";
import { atomicWriteFileSync, sleepSync } from "./fs-atomic.ts";
import { processDirsEnv, stateRootDir, type PlatformDirsEnv } from "./platform-dirs.ts";
/** What the gate file holds. */
export interface MigrationGate {
/** Resolved path of the vault being migrated. */
readonly vault: string;
readonly run_id: string;
readonly since: string;
/** Process id of the run holding the gate. */
readonly pid: number;
/**
* The start identity of that process (`store-migration/process-identity.ts`),
* so a pid reused by an unrelated process is told apart from the holder.
* Absent in a gate written by an older release.
*/
readonly started?: string;
}
const GATE_FILE = "migration-gate.json";
/** The command that continues an interrupted migration, which also lifts the gate. */
export const MIGRATION_GATE_NEXT_COMMAND = "o2b brain migrate-store --resume";
/** A content write refused because a migration of its vault is running here. */
export class MigrationInProgressError extends Error {
override readonly name = "MigrationInProgressError";
readonly next_command = MIGRATION_GATE_NEXT_COMMAND;
constructor(readonly gate: MigrationGate) {
super(
`a brain store migration of this vault is in progress on this machine (run ${gate.run_id}, ` +
`since ${gate.since}); the write was refused and nothing was written. Try again when ` +
"`o2b brain migrate-store` has finished, or resume an interrupted one with `--resume`",
);
}
}
export function migrationGatePath(source: PlatformDirsEnv = processDirsEnv()): string {
return join(stateRootDir(source), GATE_FILE);
}
/**
* The form two spellings of one vault share: its real path (links and
* junctions resolved), case folded on Windows, where `C:\Vault` and
* `c:\vault` are one folder. A path that cannot be resolved keeps its
* resolved spelling.
*/
export function canonicalVault(vault: string): string {
let path: string;
try {
path = realpathSync(vault);
} catch {
path = resolve(vault);
}
return process.platform === "win32" ? path.toLowerCase() : path;
}
/** Whether the gate names `vault`, however either was spelled. */
function gateNames(gate: MigrationGate, vault: string): boolean {
return canonicalVault(gate.vault) === canonicalVault(vault);
}
/**
* What the gate file says: no gate, a gate, a damaged gate (it was read
* but is not a gate: the migration is its remedy), or a gate that exists
* and could not be read even after a few short retries (a sharing
* violation while another run rewrites it: it may be live, so it is never
* taken over or released on that read).
*/
export type MigrationGateState =
| { readonly kind: "none" }
| { readonly kind: "held"; readonly gate: MigrationGate }
| { readonly kind: "damaged" }
| { readonly kind: "unreadable"; readonly code: string };
/** Attempts and pause of a gate read that hits an I/O failure. */
const READ_ATTEMPTS = 3;
const READ_RETRY_MS = 25;
/** Read and classify the gate file (see {@link MigrationGateState}). */
export function readMigrationGateState(source?: PlatformDirsEnv): MigrationGateState {
const path = migrationGatePath(source);
let text: string | null = null;
let code = "";
for (let attempt = 0; attempt < READ_ATTEMPTS && text === null; attempt++) {
if (attempt > 0) sleepSync(READ_RETRY_MS);
try {
text = readFileSync(path, "utf8");
} catch (err) {
// Released between a check and the read, or never held: not held.
code = String((err as NodeJS.ErrnoException).code ?? "EIO");
if (code === "ENOENT") return { kind: "none" };
}
}
if (text === null) return { kind: "unreadable", code };
try {
const parsed = JSON.parse(text) as Partial<MigrationGate>;
if (typeof parsed.vault === "string" && typeof parsed.run_id === "string") {
return {
kind: "held",
gate: {
vault: parsed.vault,
run_id: parsed.run_id,
since: typeof parsed.since === "string" ? parsed.since : "",
pid: typeof parsed.pid === "number" ? parsed.pid : 0,
...(typeof parsed.started === "string" ? { started: parsed.started } : {}),
},
};
}
} catch {
// fall through: not a gate
}
return { kind: "damaged" };
}
/** The gate, or null when no migration holds it (an unreadable gate counts as held). */
export function readMigrationGate(source?: PlatformDirsEnv): MigrationGate | null {
const state = readMigrationGateState(source);
if (state.kind === "none") return null;
return state.kind === "held" ? state.gate : UNREADABLE_GATE;
}
const UNREADABLE_GATE: MigrationGate = Object.freeze({
vault: "",
run_id: "unknown",
since: "",
pid: 0,
});
/** A migration asked for the gate while a migration of another vault holds it. */
export class MigrationGateHeldError extends Error {
override readonly name = "MigrationGateHeldError";
/** With `readError`, the gate file exists and could not be read (that code). */
constructor(
readonly gate: MigrationGate,
readError?: string,
) {
super(
readError === undefined
? `another brain store migration holds this machine's migration gate (run ${gate.run_id}, ` +
`since ${gate.since}); let it finish, or resume it with \`${MIGRATION_GATE_NEXT_COMMAND}\``
: `this machine's migration gate ${migrationGatePath()} cannot be read (${readError}); ` +
"nothing was changed. Try again in a moment",
);
}
}
/**
* Hold the gate for `vault` and run `runId`, recording `started`, the start
* identity of this process, when it is known. A gate already held for the
* same vault is taken over (a resumed run, or the rollback of an
* interrupted one, re-holds what the last run left); a gate held for
* another vault is refused with a {@link MigrationGateHeldError}, so one
* run never lifts another's protection. A damaged gate is replaced: the
* migration is its remedy. A gate that cannot be read at all is refused
* too: it may be another run's live gate.
*/
export function holdMigrationGate(
vault: string,
runId: string,
started: string | null = null,
): void {
const state = readMigrationGateState();
if (state.kind === "unreadable") throw new MigrationGateHeldError(UNREADABLE_GATE, state.code);
if (state.kind === "held" && !gateNames(state.gate, vault)) {
throw new MigrationGateHeldError(state.gate);
}
const path = migrationGatePath();
mkdirSync(dirname(path), { recursive: true });
const gate: MigrationGate = {
vault: resolve(vault),
run_id: runId,
since: new Date().toISOString(),
pid: process.pid,
...(started === null ? {} : { started }),
};
atomicWriteFileSync(path, `${JSON.stringify(gate, null, 2)}\n`);
}
/**
* Release the gate when it is held for `vault` by the run `runId`: a run
* removes only its own gate, never one a later run took over. A damaged
* gate is released by any run on any vault; a gate that cannot be read is
* left in place (it may be another run's live gate).
*/
export function releaseMigrationGate(vault: string, runId: string): void {
const state = readMigrationGateState();
if (state.kind === "none" || state.kind === "unreadable") return;
if (state.kind === "held" && (!gateNames(state.gate, vault) || state.gate.run_id !== runId)) {
return;
}
try {
unlinkSync(migrationGatePath());
} catch {
// already gone
}
}
/**
* Refuse a content write to `vault` while a migration of it runs on this
* machine. An unreadable gate refuses every vault (fails closed).
*/
export function assertNoMigrationInProgress(vault: string): void {
const gate = readMigrationGate();
if (gate === null) return;
if (gate.vault === "" || gateNames(gate, vault)) throw new MigrationInProgressError(gate);
}