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 bootstrap receipt (write-side-trust, Task 14).
*
* `.open-second-brain/bootstrap.lock.json` under the machine state root
* (`<vault>/` on an unswitched machine, the device-local state on a
* store-only one, `state/machine-state.ts`) records what one bootstrap
* actually established: the target, its install model, the
* owned entries the adapter reported, the provisioned token's NAME and
* non-secret prefix, and `applied_at`. Modeled on `install.lock.json`
* and `protect.lock.json` - the receipt is the durable, credential-free
* answer to "what did bootstrap do to this machine", which is also why
* the minted material appears nowhere in it. The token a receipt names
* authenticates hand-configured HTTP clients only; the registered stdio
* harness keeps its config-derived identity.
*
* Schema (`schema_version: 1`):
*
* ```
* {
* "schema_version": 1,
* "entries": {
* "<target>": { ...BootstrapReceiptEntry }
* }
* }
* ```
*
* The writer upserts one entry per target. No-churn is the CALLER's
* rule: a re-run that would recompute the identical entry writes
* nothing, so an idempotent bootstrap leaves the receipt byte-identical.
*/
import { existsSync, mkdirSync, readFileSync } from "node:fs";
import { dirname } from "node:path";
import { atomicWriteFileSync } from "../../core/fs-atomic.ts";
import { assertVaultIdentityForWrite } from "../../core/brain/vault-identity.ts";
import type { BootstrapMode } from "./targets.ts";
import { machineStatePath } from "../../core/state/machine-state.ts";
import { DERIVED_STORE_DIR } from "../../core/brain/path-constants.ts";
export const BOOTSTRAP_SCHEMA_VERSION = 1;
/** The non-secret token identification a receipt carries. */
export interface BootstrapTokenEntry {
readonly name: string;
readonly prefix: string;
}
export interface BootstrapReceiptEntry {
readonly target: string;
readonly mode: BootstrapMode;
readonly agent: string;
readonly config_path: string | null;
readonly owned_keys?: ReadonlyArray<string>;
readonly owned_paths?: ReadonlyArray<string>;
readonly owned_block_marker?: string;
readonly token?: BootstrapTokenEntry;
readonly applied_at: string;
}
export interface BootstrapReceipt {
readonly schema_version: typeof BOOTSTRAP_SCHEMA_VERSION;
readonly entries: Record<string, BootstrapReceiptEntry>;
}
export class BootstrapReceiptError extends Error {
constructor(message: string) {
super(message);
this.name = "BootstrapReceiptError";
}
}
const EMPTY_RECEIPT: BootstrapReceipt = { schema_version: BOOTSTRAP_SCHEMA_VERSION, entries: {} };
export function bootstrapReceiptPath(vault: string): string {
return machineStatePath(vault, DERIVED_STORE_DIR, "bootstrap.lock.json");
}
export function readBootstrapReceipt(vault: string): BootstrapReceipt {
const path = bootstrapReceiptPath(vault);
if (!existsSync(path)) return EMPTY_RECEIPT;
let parsed: unknown;
try {
parsed = JSON.parse(readFileSync(path, "utf8"));
} catch (e) {
throw new BootstrapReceiptError(
`bootstrap receipt is corrupted JSON: ${path} (${(e as Error).message})`,
);
}
if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
throw new BootstrapReceiptError(`bootstrap receipt is not an object: ${path}`);
}
const obj = parsed as Record<string, unknown>;
if (obj["schema_version"] !== BOOTSTRAP_SCHEMA_VERSION) {
throw new BootstrapReceiptError(
`bootstrap receipt schema_version ${String(obj["schema_version"])} not supported ` +
`(expected ${String(BOOTSTRAP_SCHEMA_VERSION)}): ${path}`,
);
}
const entries = obj["entries"];
if (entries === undefined) return EMPTY_RECEIPT;
if (entries === null || typeof entries !== "object" || Array.isArray(entries)) {
throw new BootstrapReceiptError(`bootstrap receipt entries is not an object: ${path}`);
}
return {
schema_version: BOOTSTRAP_SCHEMA_VERSION,
entries: entries as Record<string, BootstrapReceiptEntry>,
};
}
/** Upsert one target's entry, preserving every other entry verbatim. */
export function upsertBootstrapReceiptEntry(vault: string, entry: BootstrapReceiptEntry): void {
assertVaultIdentityForWrite(vault);
const current = readBootstrapReceipt(vault);
const next: BootstrapReceipt = {
schema_version: BOOTSTRAP_SCHEMA_VERSION,
entries: { ...current.entries, [entry.target]: entry },
};
const path = bootstrapReceiptPath(vault);
const dir = dirname(path);
if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
atomicWriteFileSync(path, JSON.stringify(next, null, 2) + "\n");
}
/**
* Drop one target's entry, preserving every other entry verbatim. This
* is how `--remove` rewrites the receipt: the entry goes away entirely,
* the way the install manifest models removal (the entry is dropped,
* the file stays), so a second remove finds nothing and says so.
* Answers false when the entry was already absent - a no-op, not an
* error.
*/
export function removeBootstrapReceiptEntry(vault: string, target: string): boolean {
assertVaultIdentityForWrite(vault);
const current = readBootstrapReceipt(vault);
if (current.entries[target] === undefined) return false;
const entries = { ...current.entries };
delete entries[target];
const path = bootstrapReceiptPath(vault);
atomicWriteFileSync(
path,
JSON.stringify({ schema_version: BOOTSTRAP_SCHEMA_VERSION, entries }, null, 2) + "\n",
);
return true;
}
/**
* Whether a receipt entry and a store record tell the same token story.
* Both absent: consistent (a tokenless bootstrap). Both present: name
* and non-secret prefix must agree. Exactly one present: the receipt
* and the store disagree, and `--check` must say so.
*/
export function receiptTokenMatches(
entry: BootstrapReceiptEntry | undefined,
record: { name: string; token_prefix: string } | undefined,
): boolean {
if (entry === undefined && record === undefined) return true;
if (entry === undefined || record === undefined) return false;
const token = entry.token;
if (token === undefined) return false;
return token.name === record.name && token.prefix === record.token_prefix;
}
/**
* Whether two entries agree on everything but `applied_at` - the
* comparison behind the no-churn rule. A byte-identical re-run must not
* touch the receipt, so the writer skips when this answers true.
*/
export function receiptEntryEqualsExcludingTimestamp(
left: BootstrapReceiptEntry,
right: BootstrapReceiptEntry,
): boolean {
const strip = (e: BootstrapReceiptEntry): string => {
const { applied_at: _applied_at, ...rest } = e;
return JSON.stringify(rest);
};
return strip(left) === strip(right);
}