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
/**
* Open an existing brain store, and describe it as a {@link StoreHandle}
* the appender and reader work through.
*
* A partition is held on this machine when its folder carries the store
* identity file (`store.json`, `{ "store_id": <ulid>, "format": 1 }`).
* Opening never creates a store or a partition: a store is created only by
* `o2b store init` (`store-init.ts`). A root that holds no partition is
* refused with {@link NoStoreError}, so a writer on a second machine whose
* sync has not delivered the store yet cannot mint a store id of its own.
* The format document of the root and of every held partition is
* refreshed (never downgraded).
*
* Partitions of two different stores under one root are refused by name.
*
* The held partitions are sticky per machine (`held-ledger.ts`): the
* writing open records them, and a partition this machine has held whose
* identity file is now missing makes both opens refuse with
* {@link HeldPartitionLostError}, so a protection reader fails closed
* instead of reading a shared-only store.
*/
import { readFileSync, statSync } from "node:fs";
import { join } from "node:path";
import { processDirsEnv, type PlatformDirsEnv } from "../platform-dirs.ts";
import { isUsableLocalDeviceId } from "../config.ts";
import { STORE_IDENTITY_FILE, STORE_PARTITIONS, type StorePartition } from "./constants.ts";
import { writeFormatDoc } from "./format-doc.ts";
import { lostHeldPartitions, recordHeldPartitions } from "./held-ledger.ts";
import { deviceStateDirFor, partitionDir } from "./store-paths.ts";
import { isUlid } from "./ulid.ts";
/** An opened store, as one device sees it. */
export interface StoreHandle {
/** The store root. */
readonly root: string;
/** The store id shared by every partition. */
readonly storeId: string;
/** This device's id; it names every shard this device writes. */
readonly device: string;
/** Device-local state directory: locks, the persisted clock. Never synced. */
readonly deviceStateDir: string;
/** Partitions this machine holds. */
readonly partitions: ReadonlySet<StorePartition>;
}
export interface OpenStoreOptions {
readonly root: string;
readonly device: string;
/** Platform source for the device-local directory (default: this process). */
readonly dirs?: PlatformDirsEnv;
}
/** A store that cannot be opened as asked. */
export class StoreOpenError extends Error {
constructor(message: string) {
super(message);
this.name = "StoreOpenError";
}
}
/** The root holds no store yet; `o2b store init` creates one. */
export class NoStoreError extends StoreOpenError {
constructor(readonly root: string) {
super(
`no brain store at ${root}: no partition holds ${STORE_IDENTITY_FILE}; ` +
"run `o2b store init` to create one, or let sync deliver it from a machine that has it",
);
this.name = "NoStoreError";
}
}
/** A partition's identity file exists but holds no valid store id (corrupt, or half written). */
export class StoreIdentityError extends StoreOpenError {
constructor(message: string) {
super(message);
this.name = "StoreIdentityError";
}
}
/**
* A partition this machine has held lost its identity file: the store as it
* shows now would read without that partition's records, so it is not
* opened at all (design D14, fail closed).
*/
export class HeldPartitionLostError extends StoreOpenError {
constructor(
readonly root: string,
readonly partitions: ReadonlyArray<StorePartition>,
) {
// Leaving `shared` is leaving the store, so the verb refuses it: for a
// lost `shared` the only remedy is the restore. With `shared` among the
// lost partitions, leaving anything else cannot work either: the leave
// reads the store id from `shared/store.json` before it clears anything,
// so it refuses with `no-store-id` and changes nothing. Name only the
// restores.
const leave = partitions.includes("shared")
? ""
: `, or run ${partitions
.map((p) => `\`o2b store partition leave ${p}\``)
.join(" and ")} to stop holding ${partitions.length > 1 ? "them" : "it"} on this machine`;
super(
`the ${partitions.join(" and ")} partition${partitions.length > 1 ? "s" : ""} of the ` +
`brain store at ${root}, which this machine has held, no longer show${
partitions.length > 1 ? "" : "s"
} ${STORE_IDENTITY_FILE}; its records cannot be read, so the store is not opened. ` +
`Restore ${partitions.map((p) => `${p}/${STORE_IDENTITY_FILE}`).join(" and ")} ` +
`from sync or a backup${leave}`,
);
this.name = "HeldPartitionLostError";
}
}
/** The store id in a partition's identity file; `null` when the partition is not held. */
export function readStoreId(dir: string): string | null {
let text: string;
try {
text = readFileSync(join(dir, STORE_IDENTITY_FILE), "utf8");
} catch (err) {
if ((err as NodeJS.ErrnoException).code === "ENOENT") return null;
throw err;
}
let parsed: { store_id?: unknown };
try {
parsed = JSON.parse(text) as { store_id?: unknown };
} catch {
throw new StoreIdentityError(`${join(dir, STORE_IDENTITY_FILE)} is not valid JSON`);
}
if (!isUlid(parsed.store_id)) {
throw new StoreIdentityError(`${join(dir, STORE_IDENTITY_FILE)} carries no valid store_id`);
}
return parsed.store_id;
}
/**
* The partitions under `root` that carry an identity file, and the one
* store id they share. Throws {@link StoreOpenError} when they belong to
* different stores. The one rule of which partitions count as held, for
* the read-only open, the writing open and `store init`.
*/
export function heldPartitions(root: string): {
held: Set<StorePartition>;
storeId: string | null;
} {
// A root that exists but is not a directory holds no store and never
// will. Said here, because the partition reads below cannot: POSIX
// answers them with ENOTDIR, but Windows answers ENOENT, which would
// read as "no store yet, run init".
if (statSync(root, { throwIfNoEntry: false })?.isDirectory() === false) {
throw new StoreOpenError(
`the brain store root ${root} is not a directory; move the file away or point ` +
"the store root at a directory",
);
}
const ids = new Map<StorePartition, string>();
for (const partition of STORE_PARTITIONS) {
const id = readStoreId(partitionDir(root, partition));
if (id !== null) ids.set(partition, id);
}
if (new Set(ids.values()).size > 1) {
throw new StoreOpenError(
`the partitions under ${root} belong to different stores (${[...ids]
.map(([p, id]) => `${p}: ${id}`)
.join(", ")}); keep one store per root`,
);
}
const first = ids.values().next();
return { held: new Set(ids.keys()), storeId: first.done === true ? null : first.value };
}
/**
* {@link heldPartitions}, refused with {@link HeldPartitionLostError} when a
* partition this machine has held no longer shows its identity file.
*/
function heldPartitionsChecked(root: string): ReturnType<typeof heldPartitions> {
const found = heldPartitions(root);
const lost = lostHeldPartitions(root, found.held);
if (lost.length > 0) throw new HeldPartitionLostError(root, lost);
return found;
}
/** What a read-only look at a store root finds. */
export interface StoreInspection {
readonly root: string;
readonly storeId: string;
readonly partitions: ReadonlySet<StorePartition>;
}
/**
* Look at the store at `root` without creating or refreshing anything:
* `null` when no partition holds an identity file. Throws
* {@link StoreOpenError} when the partitions belong to different stores,
* or a partition this machine has held lost its identity file. For
* read-only callers (doctor); writers use {@link openStore}.
*/
export function inspectStore(root: string): StoreInspection | null {
const { held, storeId } = heldPartitionsChecked(root);
return storeId === null ? null : { root, storeId, partitions: held };
}
/** Open the store at `options.root`; throws {@link NoStoreError} when it holds none. */
export function openStore(options: OpenStoreOptions): StoreHandle {
if (!isUsableLocalDeviceId(options.device)) {
throw new StoreOpenError(
`the brain store needs a device id, got "${options.device}"; set device_id in the machine ` +
`config or O2B_DEVICE_ID to lowercase letters, digits and hyphens`,
);
}
const { held, storeId } = heldPartitionsChecked(options.root);
if (storeId === null) throw new NoStoreError(options.root);
recordHeldPartitions(options.root, held, options.dirs);
// The root copy is device-local (the root is never synced), so it is
// refreshed like every partition copy.
writeFormatDoc(options.root);
for (const partition of held) writeFormatDoc(partitionDir(options.root, partition));
return {
root: options.root,
storeId,
device: options.device,
deviceStateDir: deviceStateDirFor(storeId, options.dirs ?? processDirsEnv()),
partitions: held,
};
}