Skip to content

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
9.1 KB
Raw Blame
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;
}