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
7.3 KB
Raw Blame
/**
 * Shell-native Brain profile (Workspace Insight Suite, t_323a9a83).
 *
 * `Brain/profile.md` is a materialized compact digest of the current
 * Brain - static facts (artifact counts), the highest-confidence
 * preferences, and recent activity - so simple agents, scripts, and
 * humans can `cat` one file instead of learning MCP tools. The
 * companion `.o2bfs` marker at the vault root lets shell wrappers
 * detect a Brain root safely before applying any semantic behaviour.
 *
 * Built from the morning-brief kernel plus cheap directory counts;
 * never walks the whole vault. Regeneration is age-gated by
 * {@link isProfileStale} so repeated calls stay cheap.
 */

import { existsSync, readdirSync } from "node:fs";
import { join } from "node:path";

import { atomicWriteFileSync } from "../fs-atomic.ts";
import { buildMorningBrief } from "./morning-brief.ts";
import { fileAgeMs } from "./time.ts";
import {
  assertLaneWrite,
  lanePagesInStore,
  readLanePage,
  writeLaneText,
} from "../store/lane-pages.ts";
import { storeLogDays } from "./log-days.ts";
import { storeRecordPages } from "./memory-pages.ts";
import { brainDirs } from "./paths.ts";
import { isStoreOnly } from "../store/store-only.ts";
import { withOperationPrivacy } from "../store/operation-scope.ts";

/** Milliseconds in one second, for the `maxAgeSeconds` conversion. */
const MS_PER_SECOND = 1000;

export const PROFILE_DOC_REL = join("Brain", "profile.md");
export const O2BFS_MARKER_FILE = ".o2bfs";

export interface ProfileDoc {
  readonly text: string;
  readonly generatedAt: string;
}

export interface ProfileDocOptions {
  readonly now: Date;
  /** Max preferences listed; default 10. */
  readonly topK?: number;
}

function countMdFiles(dir: string): number {
  try {
    return readdirSync(dir).filter((name) => name.endsWith(".md")).length;
  } catch {
    return 0;
  }
}

/**
 * The profile's three counts: page files on an unswitched machine; on a
 * store-only one the preference pages, the inbox signals and the log days
 * the store's records render (the same folders, read from the store).
 */
function profileCounts(vault: string): {
  readonly confirmed: number;
  readonly signals: number;
  readonly logDays: number;
} {
  if (!isStoreOnly({ vault })) {
    const dirs = brainDirs(vault);
    return {
      confirmed: countMdFiles(dirs.preferences),
      signals: countMdFiles(dirs.inbox),
      logDays: countMdFiles(dirs.log),
    };
  }
  return {
    confirmed: storeRecordPages(vault, { kinds: new Set(["preference"]) }).length,
    signals: storeRecordPages(vault, {
      kinds: new Set(["signal"]),
      signalStates: new Set(["active"]),
    }).length,
    logDays: new Set((storeLogDays(vault) ?? []).map((day) => day.date)).size,
  };
}

/** Assemble the profile document. Read-only; deterministic given `now`. */
export function buildProfileDoc(vault: string, opts: ProfileDocOptions): ProfileDoc {
  const generatedAt = opts.now.toISOString();
  const brief = buildMorningBrief(vault, { now: opts.now, topK: opts.topK ?? 10 });

  const { confirmed, signals, logDays } = profileCounts(vault);

  const lines: string[] = [
    "---",
    `generated_at: ${generatedAt}`,
    "generator: open-second-brain profile",
    "---",
    "",
    "# Brain profile",
    "",
    "Auto-generated digest. Do not edit - regenerate with `o2b brain profile`.",
    "",
    "## Facts",
    "",
    `- confirmed preferences: ${confirmed}`,
    `- inbox signals: ${signals}`,
    `- log days on record: ${logDays}`,
    "",
  ];

  if (brief.preferences.length > 0) {
    lines.push("## Top preferences", "");
    for (const pref of brief.preferences) {
      lines.push(`- ${pref.id}: ${pref.principle}${pref.trimmed ? " …" : ""}`);
    }
    lines.push("");
  }
  if (brief.openQuestions.length > 0) {
    lines.push("## Open questions", "");
    for (const q of brief.openQuestions) lines.push(`- ${q.topic} (${q.domain})`);
    lines.push("");
  }
  if (brief.recentNotes.length > 0) {
    lines.push("## Recent activity", "");
    for (const note of brief.recentNotes) lines.push(`- ${note}`);
    lines.push("");
  }

  return Object.freeze({ text: lines.join("\n"), generatedAt });
}

export interface WriteProfileResult {
  /**
   * Where the profile is: the page on an unswitched machine; once
   * switched, its lane entry's name (`store:lanes/profile`), never a
   * vault path with no file behind it.
   */
  readonly path: string;
  /** The `.o2bfs` root marker, or `null` when none is written (store-only). */
  readonly markerPath: string | null;
  readonly generatedAt: string;
}

/** The name a store-only machine reports for its profile page. */
export const PROFILE_STORE_NAME = "store:lanes/profile";

/** Materialize `Brain/profile.md` and the `.o2bfs` root marker. */
export function writeProfileDoc(vault: string, opts: ProfileDocOptions): WriteProfileResult {
  // Vault-identity write guard (context-integrity-gates, Unit J) on an
  // unswitched machine; a store-only one writes a lane-entry record.
  assertLaneWrite(vault);
  const doc = buildProfileDoc(vault, opts);
  const path = join(vault, PROFILE_DOC_REL);
  const inStore = lanePagesInStore(vault);
  // The page lists the top principles, private ones included, as plain
  // lines no reference judge recognises: once switched its record is
  // private whenever any memory record it could draw on is (fail closed).
  withOperationPrivacy(
    () => inStore && storeRecordPages(vault, { signalStates: "all" }).some((p) => p.private),
    () => writeLaneText(vault, path, doc.text),
  );
  // The shell-root marker is a file at the vault root; a store-only
  // machine keeps no machine file in the vault (design D11), so only the
  // legacy layout writes it.
  if (inStore) {
    return Object.freeze({
      path: PROFILE_STORE_NAME,
      markerPath: null,
      generatedAt: doc.generatedAt,
    });
  }
  const markerPath = join(vault, O2BFS_MARKER_FILE);
  atomicWriteFileSync(
    markerPath,
    JSON.stringify({ vault, generated_at: doc.generatedAt }, null, 2) + "\n",
  );
  return Object.freeze({ path, markerPath, generatedAt: doc.generatedAt });
}

/**
 * True when the materialized profile is missing or older than
 * `maxAgeSeconds` relative to `now`.
 */
export function isProfileStale(vault: string, maxAgeSeconds: number, now: Date): boolean {
  const path = join(vault, PROFILE_DOC_REL);
  if (lanePagesInStore(vault)) {
    // The profile is a lane entry: its age is the time it was generated.
    const stamp = readLanePage(vault, path)?.frontmatter["generated_at"];
    const at = typeof stamp === "string" ? Date.parse(stamp) : Number.NaN;
    return Number.isNaN(at) || now.getTime() - at > maxAgeSeconds * MS_PER_SECOND;
  }
  // A missing root marker is stale too: shell-root detection depends
  // on it, so a deleted/failed marker must force regeneration.
  if (!existsSync(path) || !existsSync(join(vault, O2BFS_MARKER_FILE))) return true;
  const ageMs = fileAgeMs(path, now.getTime());
  // An unmeasurable age is stale, stated here rather than inherited from
  // a helper. This is the ONE gate on regeneration: a profile that exists
  // and cannot be aged is a profile nothing else will ever refresh, and
  // rewriting it costs a directory count. The opposite policy - the one
  // `idea-discovery` used to carry - would pin a broken profile as
  // permanently fresh.
  if (ageMs === null) return true;
  return ageMs > maxAgeSeconds * MS_PER_SECOND;
}