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 one predicate "this machine writes to the store only" (design D14
* item 1, task 2.10).
*
* A machine is store-only when either holds:
*
* - **Switched.** It holds its own `device-switched` record (D14 item 1):
* the migration writes one on every machine it switches, the first
* machine included (beside its `migration-done`), and `o2b init` writes
* one on a fresh install once the store exists (`fresh-switch.ts`). The
* record is read by `isDeviceSwitched` (`../store-migration/
* migration-records.ts`); a `migration-done` alone does not switch.
* - **Fresh install.** There is no legacy tree to keep writing: no vault
* is configured, or the vault has no `Brain/` directory. Such a machine
* is store-only from its first write.
*
* Every other machine is unswitched: the legacy writers keep the legacy
* tree and dual-write behind the flag exactly as in phase 1.
*
* The switch is sticky per machine. The migration records it in a
* device-local marker beside the stores' state as it switches the device
* ({@link recordSwitchMarker}), and the first answer that sees a switch
* record writes it too. From then on the marker alone answers switched:
* a store that cannot be read (a sync tool rewriting `store.json`) and a
* `settings` shard that is absent or unreadable while sync delivers it
* never send the machine back into the legacy tree; its writes fail with
* the store's reason instead. Only a rollback (`--rollback`, D11) removes
* the marker, with the switch. Callers that ask whether THIS device
* switched use {@link deviceSwitchedHere}, which reads the same marker.
*/
import { existsSync, mkdirSync, readFileSync } from "node:fs";
import { dirname, join } from "node:path";
import { BRAIN_ROOT_REL } from "../brain/path-constants.ts";
import { readDeviceId, resolveVault } from "../config.ts";
import { atomicWriteFileSync } from "../fs-atomic.ts";
import {
DEVICE_SWITCHED_KIND as MIGRATION_DEVICE_SWITCHED_KIND,
isDeviceSwitched,
} from "../store-migration/migration-records.ts";
import { processDirsEnv } from "../platform-dirs.ts";
import { withLocalLock } from "./local-lock.ts";
import { inspectStore, type StoreHandle, type StoreInspection } from "./store-open.ts";
import { resolveConfiguredStoreRoot, storesStateDir } from "./store-paths.ts";
/** Kind of the record that switches the device that wrote it (D11, D14 item 1). */
export const DEVICE_SWITCHED_KIND = MIGRATION_DEVICE_SWITCHED_KIND;
/** Device-local file listing the (store root, device) pairs seen switched. */
const SWITCH_MARKER_FILE = "store-only.json";
/** Whether `deviceId` holds its own switch record in `store`. */
export type DeviceSwitchedReader = (store: StoreInspection, deviceId: string) => boolean;
/** Where the store-only answer comes from. */
export interface StoreOnlyContext {
/**
* The vault the caller works on: a path, `null` for none, or absent to
* resolve the configured one.
*/
readonly vault?: string | null;
/** The machine config the vault, the device id and the store root come from. */
readonly configPath?: string;
}
export interface StoreOnlyOptions {
/** A read-only preview must not persist a newly observed switch. */
readonly persistSwitch?: boolean;
/**
* The switch-record reader (default: {@link readSwitchRecords}); no
* production caller sets it. It stays for the read-facade parity tests,
* which read ONE dual-written vault both as an unswitched and as a
* switched machine: a real switch record is sticky (the device-local
* marker), so the same vault could not be read the legacy way again.
*/
readonly readSwitched?: DeviceSwitchedReader;
}
/** Why the machine is, or is not, store-only. */
export type StoreOnlyReason = "device-switched" | "no-legacy-tree" | "legacy";
export interface StoreOnlyMode {
readonly storeOnly: boolean;
readonly reason: StoreOnlyReason;
/** The vault the answer was given for (`null`: none configured). */
readonly vault: string | null;
}
/**
* The default reader: this device's own `device-switched` record in the
* `settings` stream of `shared`, as the migration reads it.
*/
export const readSwitchRecords: DeviceSwitchedReader = (store, deviceId) =>
isDeviceSwitched(store, deviceId);
/**
* Whether `vault` holds a `Brain/` folder: an unswitched machine with one
* writes the legacy tree. Whether that folder holds anything to migrate is
* `legacy-tree.ts`; a bootstrap-only folder becomes store-only through the
* fresh-install switch (`fresh-switch.ts`).
*/
export function hasLegacyTree(vault: string | null): boolean {
if (vault === null || vault.trim() === "") return false;
return existsSync(join(vault, BRAIN_ROOT_REL));
}
function markerPath(): string {
return join(storesStateDir(processDirsEnv()), SWITCH_MARKER_FILE);
}
function markerKey(root: string, device: string): string {
return `${root}\u0000${device}`;
}
function readMarker(): Set<string> {
try {
const parsed = JSON.parse(readFileSync(markerPath(), "utf8")) as { switched?: unknown };
if (!Array.isArray(parsed.switched)) return new Set();
return new Set(
parsed.switched
.filter(
(e): e is { root: string; device: string } =>
typeof e === "object" &&
e !== null &&
typeof (e as { root?: unknown }).root === "string" &&
typeof (e as { device?: unknown }).device === "string",
)
.map((e) => markerKey(e.root, e.device)),
);
} catch {
return new Set();
}
}
/**
* Change the marker under its device-local lock, so two processes never
* lose each other's entries. Never throws: the marker only makes a switch
* survive an unreadable store, and the switch record in the store stays
* the source of truth.
*/
function updateMarker(change: (known: Set<string>) => boolean, strict = false): void {
try {
mkdirSync(dirname(markerPath()), { recursive: true });
withLocalLock(markerPath(), () => {
const known = readMarker();
if (!change(known)) return;
const switched = [...known].map((key) => {
const [r, d] = key.split("\u0000") as [string, string];
return { root: r, device: d };
});
atomicWriteFileSync(markerPath(), `${JSON.stringify({ switched }, null, 2)}\n`);
});
} catch (err) {
// see above; a strict update (a clear) reports its failure
if (strict) throw err;
}
}
/** Switches seen in this process, so a switched machine reads its store once. */
const seenSwitched = new Set<string>();
function writeMarker(root: string, device: string, strict = false): void {
const key = markerKey(root, device);
updateMarker((known) => {
if (known.has(key)) return false;
known.add(key);
return true;
}, strict);
}
/**
* Record on this machine that `device` switched to the store at `root`
* (the sticky marker). The migration calls it as it switches the device;
* it throws when the marker cannot be written, so a run that cannot make
* its switch durable is finished by the next `migrate-store`.
*/
export function recordSwitchMarker(root: string, device: string): void {
writeMarker(root, device, true);
seenSwitched.add(markerKey(root, device));
}
/**
* Whether `device` switched on this machine: the sticky marker names it,
* or the store holds its own standing `device-switched` record. The
* migration, the rollback, the status block and the doctor ask this, so
* an absent or unreadable `settings` shard never reads as unswitched
* where the marker says otherwise.
*/
export function deviceSwitchedHere(
store: Pick<StoreHandle, "root" | "partitions">,
device: string,
): boolean {
return readMarker().has(markerKey(store.root, device)) || isDeviceSwitched(store, device);
}
function vaultOf(context: StoreOnlyContext): string | null {
if (context.vault !== undefined) return context.vault;
try {
return resolveVault(context.configPath);
} catch {
return null;
}
}
/** This machine's (configured store root, device), or null when either cannot be resolved. */
function configuredSwitchKey(configPath?: string): { root: string; device: string } | null {
try {
const device = readDeviceId(configPath ?? null);
const root = resolveConfiguredStoreRoot(configPath).root;
return device === null ? null : { root, device };
} catch {
return null;
}
}
/** Whether the sticky marker (or this process) names `key` switched. */
function markedKey(key: string): boolean {
if (seenSwitched.has(key)) return true;
if (!readMarker().has(key)) return false;
seenSwitched.add(key);
return true;
}
/**
* Whether the sticky marker says this machine's device switched to the
* configured store, without opening the store. A protection reader asks
* this when the store cannot be opened: on such a machine that is a
* failure to fail closed on, never "no store, no rules"
* (`read/protection-store.ts`).
*/
export function markedSwitched(context: Pick<StoreOnlyContext, "configPath"> = {}): boolean {
const at = configuredSwitchKey(context.configPath);
return at !== null && markedKey(markerKey(at.root, at.device));
}
function isSwitched(context: StoreOnlyContext, options: StoreOnlyOptions): boolean {
const at = configuredSwitchKey(context.configPath);
if (at === null) return false;
const { root, device } = at;
const key = markerKey(root, device);
// The marker first: once this machine recorded its switch, nothing the
// synced store shows right now (no partition, an unreadable store, an
// absent or unreadable `settings` shard) takes it back to the legacy
// tree. Only a rollback clears it.
if (markedKey(key)) return true;
let store: StoreInspection | null;
try {
store = inspectStore(root);
} catch {
return false;
}
if (store === null) return false;
let switched: boolean;
try {
switched = (options.readSwitched ?? readSwitchRecords)(store, device);
} catch {
switched = false;
}
if (switched && options.persistSwitch !== false) {
seenSwitched.add(key);
writeMarker(root, device);
}
return switched;
}
/** Whether, and why, this machine writes to the store only. */
export function storeOnlyMode(
context: StoreOnlyContext = {},
options: StoreOnlyOptions = {},
): StoreOnlyMode {
const vault = vaultOf(context);
if (isSwitched(context, options)) return { storeOnly: true, reason: "device-switched", vault };
if (!hasLegacyTree(vault)) return { storeOnly: true, reason: "no-legacy-tree", vault };
return { storeOnly: false, reason: "legacy", vault };
}
/** Whether this machine writes to the store only; see the module docblock. */
export function isStoreOnly(
context: StoreOnlyContext = {},
options: StoreOnlyOptions = {},
): boolean {
return storeOnlyMode(context, options).storeOnly;
}
/**
* Drop `(root, device)` from the sticky marker and from this process's
* memory of switches: a rollback took the device back to the legacy
* layout (design D11 "Rollback"), so an unreadable store must no longer
* answer store-only for it. Unlike a write of the marker, a clear that
* fails throws (a lock that stays busy, a failed write): a rollback must
* not report success while the marker still names the device.
*/
export function clearSwitchMarker(root: string, device: string): void {
const key = markerKey(root, device);
seenSwitched.delete(key);
updateMarker((known) => known.delete(key), true);
}