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 {
buildLog,
buildOkfBundleFromPages,
collectOkfPages,
OKF_INDEX_FILENAME,
OKF_MANIFEST_FILENAME,
renderIndex,
renderOkfManifest,
writeOkfBundle,
type OkfBundle,
type OkfBundleFile,
} from "../../../core/brain/portability/okf.ts";
import {
omittedPageReferenceMatcher,
readContentClass,
} 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 change-log entries the default content-
* class policy dropped from `log.md`, beside the page omission notice.
* A log the policy shortened without a word is the same silently smaller
* export the page notice exists to prevent.
*/
function logOmissionNotice(dropped: number): string {
return (
`note: ${dropped} log line(s) left out by the same policy (agent-channel lines and ` +
"lines naming a left-out page); pass --include-prompt-derived to keep the log whole\n"
);
}
/**
* The stderr line counting the kept pages' structured citations that
* named a left-out page and were dropped from the manifest. The page
* bodies are untouched - a dropped citation is a metadata omission, and
* the notice says so.
*/
function citationOmissionNotice(dropped: number): string {
return (
`note: ${dropped} citation(s) to left-out page(s) dropped from kept pages' manifest ` +
"metadata; page text is untouched\n"
);
}
/**
* `o2b brain okf-export --out <dir> [--force] [--include-prompt-derived]`
* — write a portable Open Knowledge Format bundle (concepts / queries /
* references + date-grouped `log.md` + `okf.json` manifest) to a
* directory. Read-only on the vault.
*
* This is the only export that carries page bodies verbatim, so it is the
* widest leak by volume and the reason the shared egress guard exists
* (registry entry `brain-okf-export`). The bundle is redacted in two
* pieces because they are two kinds of document: the MANIFEST is scanned
* as a tree and `okf.json` re-serialised from the result, since a pass
* over serialised JSON can consume a closing quote; the markdown files
* are scanned as text.
*
* Pages whose `content_class` frontmatter carries the reserved
* `prompt-derived` value are left out of the bundle BEFORE it is composed
* - they are absent from the manifest and no file is written for them -
* and every omission is named on stderr. `--include-prompt-derived` is
* the operator override; it carries the pages back in and says so. The
* bundle is composed FROM the kept pages rather than by re-walking the
* vault, so the walk that fed the split is the walk the bundle is built
* from: a page appearing or changing between two walks could otherwise
* re-admit what the policy just left out.
*
* The reserved bundle-root files ride every bundle: `index.md` is
* re-rendered from the REDACTED manifest by the same renderer the
* builder uses - the pre-redaction index named the excluded pages, and
* an index that lists pages or values the shipped `okf.json` does not
* carry would make the bundle disagree with itself - and `log.md` gets
* the content-class policy too. Its entries are day-keyed events, not
* page content, but the shards hold agent-written material: an entry the
* MCP transport appended is agent-dictated text, and a write entry whose
* `target` is a page the split left out would name the very omission
* back into the bundle. Under the default, both kinds of entry leave
* (counted on stderr beside the page notice) and every kept entry rides
* byte-exactly; `--include-prompt-derived` keeps the log whole and says
* so. The log still rides the same redaction scan as the page files.
*
* A kept page's own prose is never rewritten, but the manifest's
* structured `citations` are not prose: a citation naming a left-out
* page is the omitted page's name leaving through a kept page, so such
* citations are dropped from the manifest (counted on stderr) while the
* body text that carries the link stays exactly as written.
*
* A redacted bundle is no longer a lossless round-trip of the vault. The
* verb says so on stderr rather than leaving the interchange contract to
* imply otherwise.
*/
export async function cmdBrainOkfExport(argv: string[]): Promise<number> {
const { flags } = parse(argv, {
vault: { type: "string" },
out: { type: "string" },
force: { type: "boolean" },
"include-prompt-derived": { type: "boolean" },
});
const { vault } = brainVerbContext(flags);
const out = flags["out"] as string | undefined;
if (out === undefined) {
return fail("--out <dir> is required for okf-export");
}
const classPolicy = { contentClass: { include: flags["include-prompt-derived"] === true } };
try {
// The split runs over the pages the walk collected, and the bundle
// below is composed FROM the kept pages: a marked page is absent
// from the manifest and its bundle file is never composed - not
// redacted after the fact. Composing from `split.kept` (the
// `buildOkfBundleFromPages` entry point) is also the honest choice
// about the walk: the alternative re-walk in `buildOkfBundle` could
// disagree with the very split that decided what may leave.
const split = egressContentClassSplit(collectOkfPages(vault), classPolicy, {
name: (page) => page.path,
isPromptDerived: (page) => readContentClass(page.frontmatter) !== null,
});
// A kept page's structured citations naming a left-out page are
// metadata, not prose: they leave the manifest, counted, while the
// page body that carries the link is untouched. The bundle's
// `sources` need no second pass - they are resolved against the kept
// pages alone, so a citation to an omitted page already resolves to
// nothing there.
const namesOmitted = omittedPageReferenceMatcher(split.omitted);
let droppedCitations = 0;
const keptPages = split.kept.map((page) => {
const citations = page.citations.filter((target) => !namesOmitted(target));
droppedCitations += page.citations.length - citations.length;
return { ...page, citations };
});
// The log gets the same policy the pages got: agent-channel entries
// and entries naming a left-out page leave under the default, and the
// prebuilt result is handed to the builder so the vault is read once.
const log = buildLog(vault, {
includePromptDerived: flags["include-prompt-derived"] === true,
omittedPaths: new Set(split.omitted),
});
const built = buildOkfBundleFromPages(vault, keptPages, log);
const verdict = redactForEgress("brain-okf-export", {
manifest: built.manifest,
// The two reserved files rendered FROM the manifest are re-rendered
// after redaction below, so only the per-page files and the log are
// scanned as text here. The log arrives already carrying the class
// policy's filter, and is scanned like any other markdown the
// bundle carries.
files: built.files.filter(
(file) => file.path !== OKF_MANIFEST_FILENAME && file.path !== OKF_INDEX_FILENAME,
),
});
if (verdict.outcome !== EGRESS_OUTCOME.released) return fail(verdict.detail);
const files: OkfBundleFile[] = [
{
path: OKF_MANIFEST_FILENAME,
contents: renderOkfManifest(verdict.payload.manifest),
},
// Same renderer the builder uses, redacted manifest in: the index
// can never list a page the manifest left out (the pre-redaction
// index did) nor name a value the guard replaced.
{ path: OKF_INDEX_FILENAME, contents: renderIndex(verdict.payload.manifest) },
...verdict.payload.files,
];
files.sort((a, b) => (a.path < b.path ? -1 : a.path > b.path ? 1 : 0));
const bundle: OkfBundle = { manifest: verdict.payload.manifest, files };
writeOkfBundle(out, bundle, { force: flags["force"] === true });
process.stdout.write(
`wrote OKF bundle to ${out} (${bundle.manifest.pages.length} page(s), ` +
`${bundle.manifest.log_days} log day(s))\n`,
);
// The partition rule, not the content class: the count prints whatever
// the operator's flag did with the prompt-derived entries.
if (log.privateEntries > 0) {
process.stderr.write(
`okf-export: left ${log.privateEntries} private log ` +
`${log.privateEntries === 1 ? "entry" : "entries"} out of log.md\n`,
);
}
if (flags["include-prompt-derived"] === true) {
process.stderr.write(EGRESS_CONTENT_CLASS_INCLUDE_NOTICE);
} else {
if (split.omitted.length > 0) {
process.stderr.write(contentClassOmissionNotice(split.omitted));
}
if (log.droppedEntries > 0) process.stderr.write(logOmissionNotice(log.droppedEntries));
if (droppedCitations > 0) {
process.stderr.write(citationOmissionNotice(droppedCitations));
}
}
if (verdict.redacted) process.stderr.write(EGRESS_REDACTION_NOTICE);
} catch (exc) {
return fail(`okf-export failed: ${(exc as Error).message ?? exc}`);
}
return 0;
}