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
/**
* Managed-template resolution and rendering primitives shared by
* `init.ts` (first install) and `upgrade.ts` (subsequent
* migrations). Keeping them here means the two paths cannot drift
* on which file is "managed" or how its `{{key}}` placeholders are
* filled.
*
* Unknown placeholders are left intact so a typo surfaces in the
* rendered file rather than disappearing silently.
*/
import { readFileSync } from "node:fs";
import { dirname, join, resolve } from "node:path";
import { fileURLToPath } from "node:url";
import { escapeRegex } from "../strings.ts";
import { BRAIN_MANIFEST_SIDECAR_SINCE_VERSION } from "./manifest.ts";
import { DEFAULT_BRAIN_CONFIG } from "./policy.ts";
import type { BrainConfig } from "./types.ts";
// Template files ship in the same directory as the source so a future
// bundled build that keeps assets alongside the JS output keeps
// working without path surgery.
const TEMPLATE_DIR = resolve(dirname(fileURLToPath(import.meta.url)), "templates");
/** Operating manual rendered at `Brain/_BRAIN.md`. */
export const BRAIN_MANUAL_TEMPLATE_PATH = join(TEMPLATE_DIR, "_BRAIN.md.tpl");
/**
* Revision of the manual template, rendered into the manual's frontmatter
* as `template_revision:`. A manual without the line is revision 0.
*
* The manual is synced vault content and devices sharing a vault may run
* different releases. Without an order between renderings, an older
* release saw a newer release's manual as a pending upgrade and rewrote it
* back, and the newer release upgraded it forward again, each step behind a
* pre-apply snapshot. The upgrade plan now leaves a manual from a newer
* revision as it is (`planManagedPath` in `upgrade.ts`).
*
* Bump it by one whenever the rendered manual changes (the template text,
* or a release constant it renders), and set
* {@link BRAIN_MANUAL_TEMPLATE_SHA256} to the new hash: a test fails while
* the hash does not match, so a change cannot ship under an old revision.
* The revision moves only with the template, so a release that leaves the
* template alone causes no upgrade on any vault.
*/
export const BRAIN_MANUAL_TEMPLATE_REVISION = 1;
/**
* SHA-256 (hex) of the manual as this release renders it with every
* device-independent substitution applied (all but `vault_name`), line
* endings normalised to LF, at {@link BRAIN_MANUAL_TEMPLATE_REVISION}. A
* change to the template text OR to a release constant it renders
* (`schema_version`, `manifest_sidecar_since`) changes the bytes every
* device writes, so it fails the guard test until the revision is bumped.
* Read only by that test.
*/
export const BRAIN_MANUAL_TEMPLATE_SHA256 =
"40b711db15b7215225cc8218d12400dd72825f39fe859b8446a5665b32367804";
/**
* Read a template file from disk. A missing template would indicate a
* broken open-second-brain install — the message names the canonical
* cause so the operator does not chase an opaque `ENOENT`.
*/
export function readTemplate(path: string): string {
try {
return readFileSync(path, "utf8");
} catch (err) {
const message = err instanceof Error ? err.message : String(err);
throw new Error(
`Failed to load Brain template at ${path}: ${message}. ` +
"This indicates a broken open-second-brain install — the " +
"src/core/brain/templates/ directory must ship alongside templates.ts.",
{ cause: err },
);
}
}
/**
* Compute `{{key}}` substitutions for the given vault. Kept tiny on
* purpose; new substitutions are a one-line change here.
*/
export function buildSubstitutions(
vault: string,
config: BrainConfig = DEFAULT_BRAIN_CONFIG,
): ReadonlyMap<string, string> {
return new Map<string, string>([
["vault_name", vaultDisplayName(vault)],
["schema_version", String(config.schema_version)],
["template_revision", String(BRAIN_MANUAL_TEMPLATE_REVISION)],
// The release the sidecar manifest shipped in. A substitution rather
// than a literal in the template, because the same version is stated
// in the rollback warning and in the verb help; one owner, three
// readers.
["manifest_sidecar_since", BRAIN_MANIFEST_SIDECAR_SINCE_VERSION],
]);
}
/**
* Apply `{{key}}` substitutions to `template`. Unknown placeholders
* are left intact so a typo surfaces in the rendered file rather
* than disappearing silently.
*/
export function renderTemplate(
template: string,
substitutions: ReadonlyMap<string, string>,
): string {
if (substitutions.size === 0) return template;
// One pass over the template: a substituted value is never scanned
// again, so a value that itself reads `{{schema_version}}` (a vault name
// kept from a synced manual, say) stays literal instead of being
// expanded by a later key.
const keys = [...substitutions.keys()].map(escapeRegex).join("|");
const pattern = new RegExp(`\\{\\{\\s*(${keys})\\s*\\}\\}`, "g");
// Function form keeps the substitution literal — string-form
// `replace` interprets `$&` / `$1` / `$n` / `$$` in `value` as
// backreference syntax. A vault name like `pay-$1` or
// `team-$everyone` would otherwise be silently mangled.
return template.replace(pattern, (match, key: string) => substitutions.get(key) ?? match);
}
/**
* Render the operating manual the way the current release ships it
* for `vault`. Used by both `bootstrapBrain` (first write) and
* `planUpgrade` (drift check).
*/
export function renderBrainManual(
vault: string,
config: BrainConfig = DEFAULT_BRAIN_CONFIG,
): string {
return renderTemplate(
readTemplate(BRAIN_MANUAL_TEMPLATE_PATH),
buildSubstitutions(vault, config),
);
}
/**
* Render the manual for `vault`, keeping the `vault_name` an existing
* manual already carries.
*
* The display name is the basename of the vault path on THIS device, but
* the manual is synced vault content. A vault shared between a Mac
* (`/Users/<user>/Vault`) and Linux hosts (`/root/vault`, `/srv/vault`)
* gave every device its own spelling: each saw the manual another device
* wrote as a pending upgrade, and the start-up self-heal rewrote it back,
* pre-apply snapshot included, on every start of every device (hundreds of
* `upgrade-*` snapshots on one live vault). The same happened with two
* spellings of one directory on a case-insensitive filesystem.
*
* So the name is decided once, when the manual is first written (or when
* an existing manual has no `vault_name:` line), and kept from then on: a
* device-local fact must never make synced content look stale. The cost is
* cosmetic: a vault moved to a new directory name keeps its old display
* name until the line is edited by hand.
*/
export function renderBrainManualFor(
vault: string,
existing: string | null,
config: BrainConfig = DEFAULT_BRAIN_CONFIG,
): string {
const recorded = existing === null ? null : recordedVaultName(existing);
if (recorded === null) return renderBrainManual(vault, config);
const substitutions = new Map(buildSubstitutions(vault, config));
substitutions.set("vault_name", recorded);
return renderTemplate(readTemplate(BRAIN_MANUAL_TEMPLATE_PATH), substitutions);
}
/**
* The frontmatter block of a rendered manual, or null. A leading UTF-8 BOM
* (some Windows editors add one on save) is allowed before the opening
* fence.
*/
function manualFrontmatter(manual: string): string | null {
const match = /^\uFEFF?---\r?\n([\s\S]*?)\r?\n---(?:\r?\n|$)/.exec(manual);
return match === null ? null : match[1]!;
}
/**
* The `vault_name:` value a rendered manual carries in its frontmatter,
* or null. A line in the body never counts: it would be lifted into the
* frontmatter for good.
*/
function recordedVaultName(manual: string): string | null {
const frontmatter = manualFrontmatter(manual);
if (frontmatter === null) return null;
const match = /^vault_name: (.+?)\r?$/m.exec(frontmatter);
if (match === null) return null;
const name = match[1]!.trim();
return name === "" ? null : name;
}
/**
* The `template_revision:` a rendered manual carries in its frontmatter.
* A manual without the line (written before the stamp existed), or with a
* value that is not a non-negative integer, is revision 0.
*/
export function templateRevisionOf(manual: string): number {
const frontmatter = manualFrontmatter(manual);
if (frontmatter === null) return 0;
const match = /^template_revision:[ \t]*(\d+)[ \t]*\r?$/m.exec(frontmatter);
return match === null ? 0 : Number(match[1]);
}
/**
* The manual's template revision when a newer release wrote it (higher than
* {@link BRAIN_MANUAL_TEMPLATE_REVISION}), else null. Such a manual is never
* rewritten back to this release's template.
*/
export function manualRevisionAhead(manual: string): number | null {
const revision = templateRevisionOf(manual);
return revision > BRAIN_MANUAL_TEMPLATE_REVISION ? revision : null;
}
/**
* One line for a manual a newer release wrote, kept rather than rewritten
* to this release's template. `o2b brain upgrade` and `o2b brain status`
* both print it, so the two surfaces word it the same way.
*/
export function describeManualRevisionAhead(path: string, aheadRevision: number): string {
return (
`${path}: kept; written by a newer release (template revision ${aheadRevision}, ` +
`this release ships ${BRAIN_MANUAL_TEMPLATE_REVISION})`
);
}
/**
* Best-effort display name for the vault: the trailing directory name
* with separators stripped. Falls back to the literal `Second Brain`
* if the vault path has no usable basename.
*/
export function vaultDisplayName(vault: string): string {
const parts = vault.split(/[\\/]/).filter((p) => p.length > 0);
const last = parts.length > 0 ? parts[parts.length - 1]! : "";
return last !== "" ? last : "Second Brain";
}