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
import { atomicWriteFileSync } from "../../../core/fs-atomic.ts";
import {
exportBankBundleDetailed,
type BankBundleExportOptions,
} from "../../../core/brain/portability/bundle.ts";
import { preferenceDenialNotice, type PreferenceDenial } from "../../../core/brain/export.ts";
import {
isPromptDerivedPage,
omittedPageReferenceMatcher,
} from "../../../core/brain/provenance/content-class.ts";
import {
EGRESS_OUTCOME,
EGRESS_CONTENT_CLASS_INCLUDE_NOTICE,
EGRESS_REDACTION_NOTICE,
contentClassOmissionNotice,
egressContentClassSplit,
redactForEgress,
} from "../../../core/egress/guard.ts";
import { brainVerbContext, fail, parse } from "../helpers.ts";
/**
* The stderr line counting the kept pages' structured references (graph
* links and relation targets, page-contract citations) that named a
* left-out page and were dropped. A bundle the policy shortened without
* a word is the same silently smaller export the page omission notice
* exists to prevent.
*/
function referenceOmissionNotice(dropped: number): string {
return (
`note: ${dropped} link/relation/citation target(s) to left-out page(s) dropped from ` +
"kept pages' structured references\n"
);
}
/**
* The stderr line naming the reserved preferences a `--include-reserved`
* run carried into the backup, in the `EGRESS_CONTENT_CLASS_INCLUDE_NOTICE`
* shape: counted, each row named with the key that denied it, the flag
* spelled, and the one-line account of what the override changed.
*/
function reservedInclusionNotice(denied: ReadonlyArray<PreferenceDenial>): string {
const list = denied.map((d) => `${d.id} (${d.denied_by})`).join(", ");
return (
`note: ${denied.length} reserved preference(s) INCLUDED by override (--include-reserved): ` +
`${list}; this personal backup carries material the shared lanes leave out\n`
);
}
/**
* `o2b brain bank-export [--out <file>] [--include-prompt-derived]
* [--include-reserved]` - serialise a whole-vault bank bundle
* (preferences + page graph + page contracts + sources dashboard) to a
* schema-versioned JSON. Prints to stdout, or writes to `--out <file>`.
* Read-only on the vault.
*
* Every byte goes through the shared egress guard first (registry entry
* `brain-bank-export`). The guard runs over the bundle TREE and the JSON
* is serialised afterwards, so redaction can never disturb the
* document's own quoting.
*
* A page whose `content_class` frontmatter carries the reserved
* `prompt-derived` value is left out of BOTH page sections - its graph
* node and its page contract - and every omission is named once on
* stderr. `--include-prompt-derived` is the operator override; it
* carries the pages back in and says so. The sources dashboard is an
* aggregate over signal records, not pages, and carries no page text, so
* the class policy does not reach it.
*
* A kept page can still name a left-out one in its structured
* references - graph links and relation targets, contract citations -
* and such a reference is the omitted page's name leaving through a page
* the policy kept, so those targets drop from the bundle (counted on
* stderr). Everything else about the kept records, their remaining
* targets included, stays exactly as the exporters derived it.
*
* A preference the privacy deny markers reserve (`visibility: private`,
* or an informal marker saying the same thing) is left out of the
* preferences section before the guard runs, and the bundle's
* `preferences_omitted` report is disclosed on stderr in the same notice
* shape, beside whatever the class policy did: the page override carries
* the marked pages back in and says so, and the denial is named on that
* run exactly as on the default run - a bundle shared with another
* reader is a shared lane, and no page flag carries a reserved rule.
* `--include-reserved` is the ONE override for the reservation itself,
* and it exists for the documented purpose of this verb: the one-file
* backup of the operator's own vault. A reservation is a statement about
* shared readers; the operator's own restore copy is not one, so the
* flag carries the reserved rows into the section whole and the run
* prints the inclusion notice where the denial notice would have been -
* a backup that silently lost a rule would fail exactly when it is used.
*/
export async function cmdBrainBankExport(argv: string[]): Promise<number> {
const { flags } = parse(argv, {
vault: { type: "string" },
out: { type: "string" },
"include-prompt-derived": { type: "boolean" },
"include-reserved": { type: "boolean" },
});
const { vault } = brainVerbContext(flags);
const classPolicy = { contentClass: { include: flags["include-prompt-derived"] === true } };
const includeReserved = flags["include-reserved"] === true;
const bundleOpts: BankBundleExportOptions = { includeReserved };
let json: string;
let redacted: boolean;
let omitted: ReadonlyArray<string> = [];
let preferenceOmissions: ReadonlyArray<PreferenceDenial> = [];
let reservedCarried: ReadonlyArray<PreferenceDenial> = [];
let droppedReferences = 0;
try {
const { bundle, reserved } = exportBankBundleDetailed(vault, bundleOpts);
reservedCarried = includeReserved ? reserved : [];
const nodeSplit = egressContentClassSplit(bundle.graph.nodes, classPolicy, {
name: (node) => node.path,
isPromptDerived: (node) => isPromptDerivedPage(vault, node.path),
});
const pageSplit = egressContentClassSplit(bundle.pages, classPolicy, {
name: (page) => page.path,
isPromptDerived: (page) => isPromptDerivedPage(vault, page.path),
});
// One page can appear in both sections; an omission is named once.
omitted = [...new Set([...nodeSplit.omitted, ...pageSplit.omitted])];
// The structured references of the kept records: a graph link, a
// relation target or a contract citation naming a left-out page drops,
// counted; a relation left with no targets drops with it, matching the
// graph exporter's own shape of carrying only non-empty fields.
const namesOmitted = omittedPageReferenceMatcher(omitted);
const keptNodes = nodeSplit.kept.map((node) => {
const links = node.links.filter((target) => !namesOmitted(target));
const relations: Record<string, ReadonlyArray<string>> = {};
let dropped = node.links.length - links.length;
for (const [relation, targets] of Object.entries(node.relations)) {
const kept = targets.filter((target) => !namesOmitted(target));
dropped += targets.length - kept.length;
if (kept.length > 0) relations[relation] = kept;
}
droppedReferences += dropped;
return { ...node, links, relations };
});
const keptPages = pageSplit.kept.map((page) => {
const citations = page.citations.filter((target) => !namesOmitted(target));
droppedReferences += page.citations.length - citations.length;
return { ...page, citations };
});
const verdict = redactForEgress("brain-bank-export", {
...bundle,
graph: { ...bundle.graph, nodes: keptNodes },
pages: keptPages,
});
if (verdict.outcome !== EGRESS_OUTCOME.released) return fail(verdict.detail);
// Absent-when-empty: the bundle carries the field only when a
// reservation held a row back. Read from the RELEASED payload, so the
// notice names each denied id in the same scrubbed form the export
// carries - a hand-edited id whose credential the guard stripped
// reaches stderr scrubbed, never raw.
preferenceOmissions = verdict.payload.preferences_omitted ?? [];
// The carried rows' names for the inclusion notice go through the
// same boundary: the ids ride the bundle scrubbed, and the notice
// spells them the way the bundle does.
if (reservedCarried.length > 0) {
const reservedVerdict = redactForEgress("brain-bank-export", reservedCarried);
if (reservedVerdict.outcome !== EGRESS_OUTCOME.released) return fail(reservedVerdict.detail);
reservedCarried = reservedVerdict.payload;
}
json = JSON.stringify(verdict.payload, null, 2) + "\n";
redacted = verdict.redacted;
} catch (exc) {
return fail(`bank-export failed: ${(exc as Error).message ?? exc}`);
}
try {
if (typeof flags["out"] === "string") {
atomicWriteFileSync(flags["out"], json);
process.stdout.write(`wrote ${flags["out"]}\n`);
} else {
process.stdout.write(json);
}
} catch (exc) {
return fail(`bank-export failed to write output: ${(exc as Error).message ?? exc}`);
}
// The reservation notice sits above the class-policy arm: whichever
// way the reservation was answered - withheld and named, or carried in
// under --include-reserved and named - an operator overriding the page
// policy is told about it too.
if (reservedCarried.length > 0) {
process.stderr.write(reservedInclusionNotice(reservedCarried));
} else if (preferenceOmissions.length > 0) {
process.stderr.write(preferenceDenialNotice(preferenceOmissions));
}
if (flags["include-prompt-derived"] === true) {
process.stderr.write(EGRESS_CONTENT_CLASS_INCLUDE_NOTICE);
} else {
if (omitted.length > 0) process.stderr.write(contentClassOmissionNotice(omitted));
if (droppedReferences > 0) process.stderr.write(referenceOmissionNotice(droppedReferences));
}
if (redacted) process.stderr.write(EGRESS_REDACTION_NOTICE);
return 0;
}