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
5.8 KB
Raw Blame
import { createHash } from "node:crypto";
import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
import { basename, join, sep } from "node:path";

import { memoryFromStore, storeRecordPages } from "../memory-pages.ts";
import { parseFrontmatter } from "../../vault.ts";
import { storeLogDays } from "../log-days.ts";
import { brainDirs, vaultRelative } from "../paths.ts";

export interface ForgetPlanEntry {
  readonly id: string;
  readonly path: string;
  readonly kind: "inbox" | "processed" | "archived" | "preference" | "retired" | "log" | "other";
  readonly action: "would-remove-source-support";
  readonly sha256: string;
}

export interface ForgetPlan {
  readonly mode: "dry-run";
  readonly source: string;
  readonly entries: ReadonlyArray<ForgetPlanEntry>;
  readonly audit: {
    readonly contentIncluded: false;
    readonly entryCount: number;
  };
}

export function buildForgetPlan(vault: string, opts: { readonly source: string }): ForgetPlan {
  const source = opts.source.trim();
  if (!source) {
    return Object.freeze({
      mode: "dry-run",
      source,
      entries: Object.freeze([]),
      audit: Object.freeze({ contentIncluded: false, entryCount: 0 }),
    });
  }

  const entries: ForgetPlanEntry[] = [];
  for (const { path, read, id } of brainMarkdown(vault)) {
    let text: string;
    try {
      text = read();
    } catch {
      continue;
    }
    if (!text.includes(source)) continue;
    entries.push({
      id: id ?? readId(path),
      path: vaultRelative(path, vault),
      kind: classify(vault, path),
      action: "would-remove-source-support",
      sha256: createHash("sha256").update(text, "utf8").digest("hex"),
    });
  }
  entries.sort((a, b) => a.path.localeCompare(b.path));

  return Object.freeze({
    mode: "dry-run",
    source,
    entries: Object.freeze(entries),
    audit: Object.freeze({
      contentIncluded: false,
      entryCount: entries.length,
    }),
  });
}

interface BrainMarkdown {
  readonly path: string;
  readonly read: () => string;
  /** The record's id when known without reading the file. */
  readonly id?: string;
}

/**
 * Every Markdown document of the Brain layer. On a store-only machine
 * (task 2.10) the preferences and signals are the folds' records, as the
 * pages they would be, the log is one entry per day of the store's
 * `log-event` records, and their legacy folders are not walked. The
 * compiled digests are rendered on demand there, not written to the vault,
 * so they are no document to plan.
 */
function brainMarkdown(vault: string): BrainMarkdown[] {
  if (!memoryFromStore(vault)) {
    return walkBrainMarkdown(vault).map((path) => ({
      path,
      read: () => readFileSync(path, "utf8"),
    }));
  }
  const dirs = brainDirs(vault);
  // The log is the store's `log-event` records too: one entry per day.
  const memoryDirs = [dirs.inbox, dirs.preferences, dirs.retired, dirs.log];
  // `pending/` also stages notes; only its signals are memory records.
  const isMemory = (path: string): boolean =>
    memoryDirs.some((dir) => insideDir(path, dir)) ||
    (insideDir(path, dirs.pending) && basename(path).startsWith("sig-"));
  const files = walkBrainMarkdown(vault)
    .filter((path) => !isMemory(path))
    .map((path) => ({ path, read: () => readFileSync(path, "utf8") }));
  const records = storeRecordPages(vault, { signalStates: "all" }).map((page) => ({
    path: page.path,
    read: () => page.text,
    id: typeof page.meta["id"] === "string" && page.meta["id"].trim() ? page.meta["id"] : page.id,
  }));
  const logDays = (storeLogDays(vault) ?? []).map((day) => ({
    path: join(dirs.log, `${day.date}.md`),
    // The entries' own string values, unescaped, as a day file would hold
    // them: a JSON rendering escapes backslashes, quotes and newlines, so
    // a source like a Windows path would never match it.
    read: () => day.entries.flatMap((entry) => stringsOf(entry)).join("\n"),
    id: day.date,
  }));
  return [...files, ...records, ...logDays];
}

/** Every string value below `value`, depth first. */
function stringsOf(value: unknown): string[] {
  if (typeof value === "string") return [value];
  if (Array.isArray(value)) return value.flatMap(stringsOf);
  if (value !== null && typeof value === "object") return Object.values(value).flatMap(stringsOf);
  return [];
}

function walkBrainMarkdown(vault: string): string[] {
  const root = brainDirs(vault).brain;
  if (!existsSync(root)) return [];
  const out: string[] = [];
  const visit = (dir: string): void => {
    let names: string[];
    try {
      names = readdirSync(dir);
    } catch {
      return;
    }
    for (const name of names) {
      if (name.startsWith(".")) continue;
      const full = join(dir, name);
      let st;
      try {
        st = statSync(full);
      } catch {
        continue;
      }
      if (st.isDirectory()) {
        visit(full);
        continue;
      }
      if (st.isFile() && name.endsWith(".md")) out.push(full);
    }
  };
  visit(root);
  out.sort();
  return out;
}

function readId(path: string): string {
  try {
    const [meta] = parseFrontmatter(path);
    if (typeof meta["id"] === "string" && meta["id"].trim()) return meta["id"];
  } catch {
    // Fall back to the basename below.
  }
  return basename(path, ".md");
}

function classify(vault: string, path: string): ForgetPlanEntry["kind"] {
  const dirs = brainDirs(vault);
  if (insideDir(path, dirs.processed)) return "processed";
  if (insideDir(path, dirs.archived)) return "archived";
  if (insideDir(path, dirs.inbox)) return "inbox";
  if (insideDir(path, dirs.preferences)) return "preference";
  if (insideDir(path, dirs.retired)) return "retired";
  if (insideDir(path, dirs.log)) return "log";
  return "other";
}

function insideDir(path: string, dir: string): boolean {
  return path === dir || path.startsWith(`${dir}${sep}`);
}