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
10.7 KB
Raw Blame
/**
 * `o2b brain knowledge-pack <export|preview|install|uninstall|list>` -
 * portable, privacy-scanned subsets of Brain knowledge (upstream task
 * t_d037251c). The mechanics live in
 * `src/core/brain/portability/knowledge-pack.ts`; this verb owns the
 * operator surface and the egress boundary.
 *
 * Named `knowledge-pack`, not `pack`, because `schema` packs (the
 * `_brain.yaml` vocabulary block, `schema_inspect view=packs`) are a
 * different thing and must never share a verb.
 *
 * `export` is the only subcommand that writes outside the vault. Its
 * content goes through the shared egress guard (registry entry
 * `brain-knowledge-pack-export`) BEFORE it is sealed, so the sha256 table
 * in `knowledge-pack.json` hashes the bytes that actually left: the OKF
 * manifest and the preference rows are scanned as trees, the page files as
 * text, exactly as `okf-export` and `bank-export` scan them.
 */

import {
  installKnowledgePack,
  KnowledgePackError,
  listInstalledKnowledgePacks,
  previewKnowledgePack,
  readKnowledgePack,
  sealKnowledgePack,
  selectKnowledgePack,
  uninstallKnowledgePack,
  type KnowledgePackPreview,
} from "../../../core/brain/portability/knowledge-pack.ts";
import { writeOkfBundle } from "../../../core/brain/portability/okf.ts";
import {
  EGRESS_OUTCOME,
  EGRESS_REDACTION_NOTICE,
  redactForEgress,
} from "../../../core/egress/guard.ts";
import { brainVerbContext, fail, info, ok, okJson, parse, resolveBrainAgent } from "../helpers.ts";

const USAGE =
  "usage: o2b brain knowledge-pack export --name <name> --select <sel>[,<sel>…] --out <dir> [--version <v>] [--force] [--json]\n" +
  "       o2b brain knowledge-pack preview <pack-dir> [--json]\n" +
  "       o2b brain knowledge-pack install <pack-dir> [--agent <name>] [--json]\n" +
  "       o2b brain knowledge-pack uninstall <name> [--confirm] [--json]\n" +
  "       o2b brain knowledge-pack list [--json]";

export async function cmdBrainKnowledgePack(argv: string[]): Promise<number> {
  const sub = argv[0];
  const rest = argv.slice(1);
  try {
    switch (sub) {
      case "export":
        return exportPack(rest);
      case "preview":
        return previewPack(rest);
      case "install":
        return installPack(rest);
      case "uninstall":
        return uninstallPack(rest);
      case "list":
        return listPacks(rest);
      default:
        return fail(USAGE);
    }
  } catch (exc) {
    if (exc instanceof KnowledgePackError) return fail(`knowledge-pack ${sub}: ${exc.message}`);
    return fail(`knowledge-pack ${sub ?? ""} failed: ${(exc as Error).message ?? exc}`);
  }
}

function exportPack(argv: string[]): number {
  const { flags } = parse(argv, {
    vault: { type: "string" },
    name: { type: "string" },
    version: { type: "string" },
    select: { type: "string-array" },
    out: { type: "string" },
    force: { type: "boolean" },
    json: { type: "boolean" },
  });
  const { vault } = brainVerbContext(flags);
  const name = flags["name"] as string | undefined;
  const out = flags["out"] as string | undefined;
  if (name === undefined || out === undefined) {
    return fail("knowledge-pack export requires --name <name> and --out <dir>");
  }
  const select = (flags["select"] as string[] | undefined) ?? [];

  const selected = selectKnowledgePack(vault, select);
  const verdict = redactForEgress("brain-knowledge-pack-export", {
    okfManifest: selected.okfManifest,
    pageFiles: selected.pageFiles,
    preferences: selected.preferences,
  });
  if (verdict.outcome !== EGRESS_OUTCOME.released) return fail(verdict.detail);

  const sealed = sealKnowledgePack({
    name,
    version: (flags["version"] as string | undefined) ?? "1",
    selection: selected.selection,
    okfManifest: verdict.payload.okfManifest,
    pageFiles: verdict.payload.pageFiles,
    preferences: verdict.payload.preferences,
  });
  writeOkfBundle(
    out,
    { manifest: verdict.payload.okfManifest, files: sealed.files },
    { force: flags["force"] === true },
  );

  if (flags["json"]) {
    okJson({
      out,
      name: sealed.manifest.name,
      version: sealed.manifest.version,
      digest: sealed.manifest.integrity.digest,
      preferences: verdict.payload.preferences.length,
      pages: verdict.payload.okfManifest.pages.length,
      blocked: selected.blocked,
      warnings: selected.warnings,
      redacted: verdict.redacted,
    });
  } else {
    ok(
      `wrote knowledge pack ${sealed.manifest.name}@${sealed.manifest.version} to ${out} ` +
        `(${verdict.payload.preferences.length} preference(s), ` +
        `${verdict.payload.okfManifest.pages.length} page(s)); sha256 ${sealed.manifest.integrity.digest}`,
    );
    for (const b of selected.blocked) info(`  blocked ${b.kind} ${b.id}: ${b.reason}`);
    for (const w of selected.warnings) info(`  warning ${w.kind} ${w.id}: ${w.reasons.join(", ")}`);
  }
  if (verdict.redacted) process.stderr.write(EGRESS_REDACTION_NOTICE);
  return 0;
}

function renderPreview(preview: KnowledgePackPreview): void {
  ok(`knowledge pack ${preview.name}@${preview.version} (stamp ${preview.stamp})`);
  ok(
    `  integrity: ${preview.integrity.verified ? "verified" : "FAILED"} (sha256 ${preview.integrity.declared})`,
  );
  for (const p of preview.integrity.problems) info(`    - ${p}`);
  ok(
    `  ${preview.count} entr${preview.count === 1 ? "y" : "ies"}: ` +
      `${preview.counts.preferences} preference(s), ${preview.counts.pages} page(s)`,
  );
  for (const e of preview.entries) {
    const status = e.status !== null ? ` [source status: ${e.status}]` : "";
    info(`  - ${e.kind} ${e.id} -> ${e.target}${status}`);
    info(`      ${e.sample.replace(/\s+/g, " ").slice(0, 120)}`);
  }
  if (preview.conflicts.length > 0) {
    ok(`  conflicts: ${preview.conflicts.length}`);
    for (const c of preview.conflicts) info(`    - ${c.kind} ${c.id}: ${c.reason} (${c.detail})`);
  }
  if (preview.privacyWarnings.length > 0) {
    ok(`  privacy warnings: ${preview.privacyWarnings.length}`);
    for (const w of preview.privacyWarnings) {
      info(`    - ${w.kind} ${w.id}: ${w.reasons.join(", ")}`);
    }
  }
  info("  preferences install unconfirmed (fresh trial window); pages stage under OKF Review/");
}

function previewPack(argv: string[]): number {
  const { flags, positional } = parse(argv, {
    vault: { type: "string" },
    json: { type: "boolean" },
  });
  const dir = positional[0];
  if (dir === undefined) return fail("usage: o2b brain knowledge-pack preview <pack-dir> [--json]");
  const { vault } = brainVerbContext(flags);
  const preview = previewKnowledgePack(vault, readKnowledgePack(dir));
  if (flags["json"]) okJson({ ...preview });
  else renderPreview(preview);
  // A pack that fails its own integrity check is not something to install;
  // the preview still prints so the operator can see why.
  return preview.integrity.verified ? 0 : 1;
}

function installPack(argv: string[]): number {
  const { flags, positional } = parse(argv, {
    vault: { type: "string" },
    agent: { type: "string" },
    json: { type: "boolean" },
  });
  const dir = positional[0];
  if (dir === undefined) return fail("usage: o2b brain knowledge-pack install <pack-dir>");
  const { vault, config } = brainVerbContext(flags);
  const result = installKnowledgePack(vault, readKnowledgePack(dir), {
    agent: resolveBrainAgent(flags, config),
  });
  const failures = result.preferences.failed.length + result.pages.errors.length;
  if (flags["json"]) {
    okJson({ ...result });
  } else {
    ok(`installed knowledge pack ${result.name}@${result.version} (stamp ${result.stamp})`);
    ok(
      `  preferences: ${result.preferences.installed.length} of ${result.preferences.carried} ` +
        `installed unconfirmed, ${result.preferences.conflicts.length} conflict(s), ` +
        `${result.preferences.failed.length} failed`,
    );
    for (const c of result.preferences.conflicts) info(`    - ${c.id}: ${c.reason} (${c.detail})`);
    for (const f of result.preferences.failed) {
      info(`    - ${f.id ?? `#${f.index}`}: ${f.reason} (${f.detail})`);
    }
    for (const c of result.preferences.topicKeyCollisions) {
      info(`    - topic key '${c.key}' is claimed by ${c.prefIds.join(", ")}`);
    }
    ok(
      `  pages: ${result.pages.written.length} staged for review, ` +
        `${result.pages.skipped.length} skipped, ${result.pages.errors.length} error(s)`,
    );
    for (const e of result.pages.errors) info(`    - ${e.path}: ${e.message}`);
    for (const w of result.privacyWarnings) {
      info(`  warning ${w.kind} ${w.id}: ${w.reasons.join(", ")}`);
    }
  }
  return failures > 0 ? 1 : 0;
}

function uninstallPack(argv: string[]): number {
  const { flags, positional } = parse(argv, {
    vault: { type: "string" },
    agent: { type: "string" },
    confirm: { type: "boolean" },
    json: { type: "boolean" },
  });
  const name = positional[0];
  if (name === undefined)
    return fail("usage: o2b brain knowledge-pack uninstall <name> [--confirm]");
  const { vault, config } = brainVerbContext(flags);
  const plan = uninstallKnowledgePack(vault, name, {
    confirm: flags["confirm"] === true,
    agent: resolveBrainAgent(flags, config),
  });
  if (flags["json"]) {
    okJson({ ...plan });
    return 0;
  }
  ok(`knowledge-pack uninstall${plan.confirmed ? "" : " (DRY RUN)"}: ${plan.name}`);
  ok(
    `  ${plan.remove.length} entr${plan.remove.length === 1 ? "y" : "ies"} ${plan.confirmed ? "removed" : "WOULD be removed"}:`,
  );
  for (const e of plan.remove) ok(`    - ${e.path} (${e.kind}, ${e.stamp})`);
  if (plan.kept.length > 0) {
    info(`  ${plan.kept.length} entr${plan.kept.length === 1 ? "y" : "ies"} kept:`);
    for (const k of plan.kept) info(`    - ${k.entry.path} (${k.reason})`);
  }
  if (plan.snapshotRunId !== null) {
    ok(`  recovery point: snapshot ${plan.snapshotRunId}`);
    if (plan.recoverability.blockers.length > 0) {
      info(
        `    coverage: ${plan.recoverability.state} ` +
          `(not covered: ${plan.recoverability.blockers.join(", ")}; re-install the pack to restore staged pages)`,
      );
    }
  }
  if (plan.auditRecordId !== null) ok(`  audit: ${plan.auditRecordId}`);
  if (!plan.confirmed) info("  re-run with --confirm to remove");
  return 0;
}

function listPacks(argv: string[]): number {
  const { flags } = parse(argv, {
    vault: { type: "string" },
    json: { type: "boolean" },
  });
  const { vault } = brainVerbContext(flags);
  const packs = listInstalledKnowledgePacks(vault);
  if (flags["json"]) {
    okJson({ packs });
    return 0;
  }
  if (packs.length === 0) {
    ok("no knowledge packs installed");
    return 0;
  }
  for (const pack of packs) {
    ok(
      `${pack.name} (${pack.stamps.join(", ")}): ${pack.entries.length} entr${pack.entries.length === 1 ? "y" : "ies"}`,
    );
    for (const e of pack.entries) info(`  - ${e.kind} ${e.path} [${e.state}]`);
  }
  return 0;
}