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
/**
* Per-session hook state: a tiny, namespaced, expiry-stamped key/value store
* shared by the delivery-track hooks (nav-tier cadence, D1; strict read-block
* orientation, D2).
*
* Binding convention (design plan, D1/D2): stamps live under namespaced keys
* (`osb.nav_tier.*`, `osb.oriented.*`); each stamp carries an explicit
* epoch-ms expiry written by its producer; readers treat a missing, malformed,
* or expired stamp identically (absent) and NEVER throw. This is not a new
* general store - it is one JSON file per session scope beside the existing
* `.open-second-brain/` hook surfaces, mirroring how the search layer scopes
* `search-focus/<scope>.json`.
*
* The store is deliberately fail-soft on both sides: a read degrades to
* "absent" on any error so a hook can never be stranded by a corrupt file, and
* a write returns `false` rather than throwing so a hook's fail-open contract
* holds even on a read-only or full filesystem.
*/
import { createHash } from "node:crypto";
import { type BigIntStats, lstatSync, mkdirSync, readdirSync, unlinkSync } from "node:fs";
import { dirname, join } from "node:path";
import {
acquireLockSync,
type LockHandle,
removeStaleLockSync,
} from "../../src/core/brain/sync-lockfile.ts";
import {
resolveSessionScope,
SESSION_SCOPE_MAX_LENGTH,
} from "../../src/core/brain/session-scope.ts";
import {
derivedDirIsSymlinked,
readRegularFileNoFollow,
} from "../../src/core/derived-store-guard.ts";
import { atomicWriteText } from "../../src/core/fs-atomic.ts";
import { machineStateRoot } from "../../src/core/state/machine-state.ts";
/** The vault's hook-surface directory. */
const OSB_DIR = ".open-second-brain";
/** Directory (under {@link OSB_DIR}) holding per-scope state. */
const HOOK_STATE_DIR = "hook-state";
/** A scope state file name: a scope slug plus `.json`, nothing else. */
const SCOPE_FILE_RE = new RegExp(`^[a-z0-9-]{1,${SESSION_SCOPE_MAX_LENGTH}}\\.json$`);
/** A scope lockfile name: `<slug>.json.lock`. */
const SCOPE_LOCK_RE = new RegExp(`^[a-z0-9-]{1,${SESSION_SCOPE_MAX_LENGTH}}\\.json\\.lock$`);
/**
* Residue a killed hook can leave beside a scope file: an atomic-write temp
* file (`.<slug>.json.<pid>.<ms>.<rand>.tmp`), an abandoned scope lockfile
* (`<slug>.json.lock`), a takeover claim (`<slug>.json.lock.takeover-<ino>-<mtime>[-<gen>]`,
* see `removeStaleLockSync` in `src/core/brain/sync-lockfile.ts`) and the stale-lock aside earlier releases
* moved a lock to (`<slug>.json.lock.stale-<pid>`).
*/
const SCOPE_RESIDUE_RE = new RegExp(
`^(?:\\.[a-z0-9-]{1,${SESSION_SCOPE_MAX_LENGTH}}\\.json\\.\\d+\\.\\d+\\.[0-9a-f]+\\.tmp` +
`|[a-z0-9-]{1,${SESSION_SCOPE_MAX_LENGTH}}\\.json\\.lock(?:\\.stale-\\d+|\\.takeover-\\d+-\\d+(?:-\\d+)?)?)$`,
);
/** Scope slug used when no session id is available (single flat lane). */
const DEFAULT_SCOPE = "default";
/** One expiry-stamped marker. `expiresAt` is epoch milliseconds. */
export interface HookStamp {
readonly expiresAt: number;
readonly data?: Record<string, unknown>;
}
/** Slug characters kept in front of the hash suffix of a lossy slug (47 + 1 + 16 = 64). */
const LOSSY_SLUG_KEEP = SESSION_SCOPE_MAX_LENGTH - 17;
/**
* Normalise a raw session id into a filesystem-safe scope slug, falling back
* to {@link DEFAULT_SCOPE} for a missing, empty, or separator-only id so a
* host that omits the session id still gets a single stable lane rather than a
* throw.
*
* When the normalisation is lossy (case, punctuation, or past 64 characters),
* the slug is cut to {@link LOSSY_SLUG_KEEP} characters and suffixed with 16
* hex characters of the id's SHA-256, so `Sess_ABC` and `sess-abc`, or two
* long ids with a common prefix, never share a ledger and a queue. Ids that
* are already slugs, such as the Claude Code and Codex UUIDs, keep their
* plain name. The result stays inside {@link SCOPE_FILE_RE}.
*/
function scopeSlug(sessionId: string | null | undefined): string {
if (sessionId === null || sessionId === undefined || sessionId.length === 0) {
return DEFAULT_SCOPE;
}
let slug: string;
try {
slug = resolveSessionScope(sessionId);
} catch {
return DEFAULT_SCOPE;
}
if (slug === sessionId) return slug;
const digest = createHash("sha256").update(sessionId).digest("hex").slice(0, 16);
return `${slug.slice(0, LOSSY_SLUG_KEEP)}-${digest}`;
}
/**
* Absolute path of the state file for one vault + session scope: under the
* vault, or under the device-local state once this machine is switched
* (`state/machine-state.ts`, design D14).
*/
export function hookStateFilePath(vault: string, sessionId: string | null | undefined): string {
return stateFileAt(machineStateRoot(vault), sessionId);
}
/**
* The state file of one scope below a machine-state root already resolved.
* Each public entry point resolves the root ONCE (`machineStateRoot` asks
* the store on an unswitched machine) and hands it down, so the symlink
* check, the read and the write of one operation all name the same tree.
*/
function stateFileAt(root: string, sessionId: string | null | undefined): string {
return join(root, OSB_DIR, HOOK_STATE_DIR, `${scopeSlug(sessionId)}.json`);
}
/**
* True when `<vault>/.open-second-brain` or its `hook-state` directory is a
* symbolic link. A vault received from elsewhere could point either at any
* directory, so every reader, writer and the prune refuse such a tree: reads
* answer empty, writes fail, the sweep removes nothing.
*/
function hookStateDirIsSymlinked(root: string): boolean {
return derivedDirIsSymlinked(root, OSB_DIR, HOOK_STATE_DIR);
}
/**
* Read the whole state object for a scope. Any failure (missing file, unreadable,
* malformed JSON, non-object root, symlinked directory) degrades to an empty
* object so callers never throw and a corrupt file behaves exactly like a fresh
* one.
*/
function readState(root: string, sessionId: string | null | undefined): Record<string, unknown> {
return loadState(root, sessionId) ?? {};
}
/**
* The parsed state of a scope: `{}` when absent or when the hook-state tree is
* symlinked, `null` when present but unusable (including a state file that is
* not a regular file).
*/
function loadState(
root: string,
sessionId: string | null | undefined,
): Record<string, unknown> | null {
if (hookStateDirIsSymlinked(root)) return {};
const read = readRegularFileNoFollow(stateFileAt(root, sessionId));
if (read.status === "absent") return {};
if (read.status !== "ok") return null;
try {
const parsed = JSON.parse(read.text) as unknown;
if (parsed !== null && typeof parsed === "object" && !Array.isArray(parsed)) {
return parsed as Record<string, unknown>;
}
return null;
} catch {
return null;
}
}
/**
* True when the scope's state file exists but cannot be read or parsed into an
* object - the case every reader silently treats as a fresh session, surfaced
* so a caller can name it. Never throws.
*/
export function isHookStateCorrupt(vault: string, sessionId: string | null | undefined): boolean {
return loadState(machineStateRoot(vault), sessionId) === null;
}
/**
* Validate one raw stamp value. Returns `null` when it is missing, malformed
* (no finite numeric `expiresAt`), or expired (`expiresAt <= nowMs` - expiry is
* exclusive). A non-object `data` is dropped. Never throws.
*/
export function parseHookStamp(raw: unknown, nowMs: number): HookStamp | null {
if (raw === null || typeof raw !== "object" || Array.isArray(raw)) return null;
const record = raw as Record<string, unknown>;
const expiresAt = record["expiresAt"];
if (typeof expiresAt !== "number" || !Number.isFinite(expiresAt)) return null;
if (expiresAt <= nowMs) return null;
const data = record["data"];
if (data !== null && typeof data === "object" && !Array.isArray(data)) {
return Object.freeze({ expiresAt, data: data as Record<string, unknown> });
}
return Object.freeze({ expiresAt });
}
/**
* Read one namespaced stamp through {@link parseHookStamp}: `null` when the
* stamp is missing, malformed, or expired. Never throws.
*/
export function readHookStamp(
vault: string,
sessionId: string | null | undefined,
key: string,
nowMs: number = Date.now(),
): HookStamp | null {
return parseHookStamp(readState(machineStateRoot(vault), sessionId)[key], nowMs);
}
/** Bounded busy-retry acquiring the per-scope advisory lock. */
const LOCK_RETRIES = 20;
/** Sleep between lock attempts (ms). 20 * 5ms ~= 100ms worst-case wait. */
const HOOK_STATE_LOCK_RETRY_DELAY_MS = 5;
/**
* Age past which a scope lockfile is presumed abandoned and taken over: three
* times the 10 s host hook timeout, so no live hook can still hold it.
*/
export const HOOK_STATE_STALE_LOCK_MS = 30_000;
/** Sleep synchronously without spinning the CPU (hooks are sync end-to-end). */
function sleepSync(ms: number): void {
Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
}
/** One lock attempt; `null` on contention, rethrows anything else. */
function tryLock(path: string): LockHandle | null {
try {
return acquireLockSync(path);
} catch (err) {
if ((err as NodeJS.ErrnoException).code !== "ELOCKED") throw err;
return null;
}
}
/** Whether a lockfile was last modified more than the stale threshold ago. */
function isStale(st: BigIntStats): boolean {
return Date.now() - Number(st.mtimeMs) > HOOK_STATE_STALE_LOCK_MS;
}
/**
* Take over the scope lockfile when its mtime is older than
* {@link HOOK_STATE_STALE_LOCK_MS}, the residue of a hook killed mid-update.
* Returns `true` when it removed one, after which the caller makes one fresh
* acquire attempt like any other contender.
*
* The staleness judgement and the removal are tied to one file through
* `removeStaleLockSync` in `src/core/brain/sync-lockfile.ts`: the identity
* read with the judgement is the one it claims and re-checks, so a
* contender whose judgement is out of date (the abandoned lock was already
* taken over and a live holder re-acquired) removes nothing. A live
* holder's lock is never moved or removed, and a release removes only a
* lock its holder still owns, so the scope has at most one holder at a time
* through a takeover. Every I/O error reports `false`.
*/
function clearStaleLock(path: string, stale: (st: BigIntStats) => boolean = isStale): boolean {
return removeStaleLockSync(path + ".lock", stale);
}
/**
* Test-only entry to {@link clearStaleLock} with an injected stale check, so
* a test can run another contender's takeover between this contender's
* judgement and its act - an interleaving real processes reach only by luck.
*
* The leading underscore is this repo's marker for a test-only export.
*/
// oxlint-disable-next-line no-underscore-dangle
export const _clearStaleLockForTests = clearStaleLock;
/**
* Acquire the scope's advisory lock. The read-merge-write is not atomic on its
* own, so two concurrent hook processes could otherwise each read the file,
* merge their own key, and clobber the other's stamp. A stale lockfile is
* taken over once (claimed and removed, then one fresh attempt). With `tryOnce` a contended
* lock yields `null` immediately; otherwise it retries within a bounded budget
* before yielding `null`, and the caller degrades rather than throwing.
*/
function acquireScopeLock(path: string, tryOnce: boolean): LockHandle | null {
const first = tryLock(path);
if (first !== null) return first;
if (clearStaleLock(path)) {
const taken = tryLock(path);
if (taken !== null) return taken;
}
if (tryOnce) return null;
for (let attempt = 1; attempt < LOCK_RETRIES; attempt++) {
sleepSync(HOOK_STATE_LOCK_RETRY_DELAY_MS);
const handle = tryLock(path);
if (handle !== null) return handle;
}
return null;
}
/**
* Mutator applied by {@link updateHookState}: receives the scope's current
* state (a fresh copy) and the clock, returns the state to persist plus a
* caller-defined result.
*/
export type HookStateMutator<T> = (
state: Record<string, unknown>,
nowMs: number,
) => { readonly state: Record<string, unknown>; readonly result: T };
/** Outcome of {@link updateHookState}. */
export type HookStateUpdateOutcome<T> =
| { readonly status: "ok"; readonly result: T }
| { readonly status: "busy" }
| { readonly status: "failed" };
/**
* Locked read-modify-write over one scope's state file. The mutator runs while
* the per-scope advisory lock is held, and its state is written through an
* atomic rename so lock-free readers never see a torn file. `busy` means the
* lock stayed contended (`tryOnce`: a single attempt, no retry); `failed`
* means any other error, including a throwing mutator or a symlinked
* hook-state tree (see {@link hookStateDirIsSymlinked}), in which case nothing
* is written. Never throws.
*/
export function updateHookState<T>(
vault: string,
sessionId: string | null | undefined,
mutate: HookStateMutator<T>,
opts: { readonly tryOnce?: boolean; readonly nowMs?: number } = {},
): HookStateUpdateOutcome<T> {
let lock: LockHandle | null = null;
try {
const root = machineStateRoot(vault);
if (hookStateDirIsSymlinked(root)) return { status: "failed" };
const path = stateFileAt(root, sessionId);
mkdirSync(dirname(path), { recursive: true });
lock = acquireScopeLock(path, opts.tryOnce === true);
if (lock === null) return { status: "busy" };
const next = mutate(readState(root, sessionId), opts.nowMs ?? Date.now());
// Private mode: the re-grounding queue holds digest parts (standing and
// scoped rules, the memory digest), the same class of text the inject
// cache keeps at 0o600.
atomicWriteText(path, JSON.stringify(next.state, null, 2) + "\n", { mode: 0o600 });
return { status: "ok", result: next.result };
} catch {
return { status: "failed" };
} finally {
lock?.release();
}
}
/**
* Write one namespaced stamp, preserving every other key already in the
* scope's state file. The whole read-merge-write runs under a per-scope
* advisory lock so concurrent hook processes cannot drop each other's stamps.
* Returns `true` on success and `false` on any failure (unwritable filesystem,
* unresolvable lock contention, etc.) so a producer can record the outcome
* without ever throwing - the hooks that call this must stay fail-open.
*/
export function writeHookStamp(
vault: string,
sessionId: string | null | undefined,
key: string,
stamp: HookStamp,
): boolean {
const outcome = updateHookState(vault, sessionId, (state) => {
state[key] =
stamp.data !== undefined
? { expiresAt: stamp.expiresAt, data: stamp.data }
: { expiresAt: stamp.expiresAt };
return { state, result: true };
});
return outcome.status === "ok";
}
/** Default age past which {@link pruneHookStateFiles} removes a scope file. */
const PRUNE_MAX_AGE_MS = 7 * 86_400_000;
/** Default ceiling on files removed by one {@link pruneHookStateFiles} sweep. */
const PRUNE_MAX_FILES = 200;
/**
* Delete scope state files (`<slug>.json`) and their write and lock residue
* (see {@link SCOPE_RESIDUE_RE}) whose mtime is older than `maxAgeMs`,
* removing at most `maxFiles` per sweep. A lock that old is far past
* {@link HOOK_STATE_STALE_LOCK_MS}, so no live hook holds it; it is removed
* through the same claim a hook's takeover uses (`removeStaleLockSync`),
* which leaves a fresh claim file behind for
* a later sweep. Symlinks and
* any name outside those shapes are left alone, and nothing is swept
* when `.open-second-brain` or `hook-state` is itself a symlink: a vault
* received from elsewhere could otherwise point the sweep at any directory.
* Returns the number of files removed; a missing directory or any I/O error
* counts as nothing removed. Never throws.
*/
export function pruneHookStateFiles(
vault: string,
opts: { readonly maxAgeMs?: number; readonly maxFiles?: number; readonly nowMs?: number } = {},
): number {
const maxAgeMs = opts.maxAgeMs ?? PRUNE_MAX_AGE_MS;
const maxFiles = opts.maxFiles ?? PRUNE_MAX_FILES;
const nowMs = opts.nowMs ?? Date.now();
const root = machineStateRoot(vault);
if (hookStateDirIsSymlinked(root)) return 0;
const dir = join(root, OSB_DIR, HOOK_STATE_DIR);
let names: string[];
try {
names = readdirSync(dir);
} catch {
return 0;
}
// Locks last: removing a lock also sweeps its old takeover claims, which
// this loop would then find gone and not count. Directory order differs
// between filesystems, so fix the order rather than depend on it.
names.sort((a, b) => Number(SCOPE_LOCK_RE.test(a)) - Number(SCOPE_LOCK_RE.test(b)));
let removed = 0;
for (const name of names) {
if (removed >= maxFiles) break;
if (!SCOPE_FILE_RE.test(name) && !SCOPE_RESIDUE_RE.test(name)) continue;
const path = join(dir, name);
try {
const st = lstatSync(path, { bigint: true });
if (!st.isFile() || nowMs - Number(st.mtimeMs) <= maxAgeMs) continue;
// A lock goes through the takeover claim, like a hook's takeover, so the
// sweep and a hook that judged the same lock stale never both remove it
// (the second would remove the first's freshly re-acquired lock).
if (SCOPE_LOCK_RE.test(name)) {
if (!removeStaleLockSync(path, (seen) => nowMs - Number(seen.mtimeMs) > maxAgeMs)) {
continue;
}
} else {
unlinkSync(path);
}
removed += 1;
} catch {
// vanished or unremovable; leave it for the next sweep
}
}
return removed;
}