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.3 KB
Raw Blame
/**
 * The one write path for preference writers that edit a preference's page
 * themselves instead of calling `writePreference` (task 2.10): the memory
 * importers, the frontmatter remediation, the expiration setter, page id
 * stamping, page dedup, lint consolidation and write batches.
 *
 * Each hands its legacy page write and the frontmatter the page carries
 * after it to {@link routePreferencePage}:
 *
 *  - on a store-only machine the page write never runs and the
 *    preference's records go to the store only, so nothing under `Brain/`
 *    changes;
 *  - on an unswitched machine the page is written and the same records
 *    are dual-written behind the flag, as `writePreference` does.
 *
 * The records are those `writePreference` writes (`preferenceStoreRecords`):
 * the page's fields under the store's names, with the value types the
 * writer writes (the page parser reads every scalar as text), the page's
 * identity keys left out. One privacy verdict covers the write: the
 * fields as the page carries them and, once switched, the preference as
 * the fold holds it.
 */

import type { Authority } from "../store/constants.ts";
import { authorityFromOrigin } from "../store/dual-write.ts";
import { withOperationPrivacy } from "../store/operation-scope.ts";
import { routeWrite, storeWrite, type RoutedWrite } from "../store/store-write.ts";
import { canonicalJson } from "../integrity/digest.ts";
import { join, posix } from "node:path";
import { BRAIN_PREFERENCES_REL, BRAIN_RETIRED_REL } from "./path-constants.ts";
import type { FrontmatterMap } from "../types.ts";
import { formatFrontmatter, parseFrontmatterText } from "../vault.ts";
import { atomicWriteFileSync } from "../fs-atomic.ts";
import { preferencePath } from "./paths.ts";
import { assertVaultIdentityForWrite } from "./vault-identity.ts";
import {
  preferencePrivacy,
  preferenceStoreRecords,
  preferencePageBody,
  storeFieldsOf,
  storePreferenceMeta,
  withPreferenceProse,
} from "./preference.ts";
import {
  PREFERENCE_TEXT_FIELD,
  preferencesStoreOnly,
  storePreferenceEntry,
  storePreferenceSlugs,
  typedPreferenceFields,
} from "./preference-store.ts";

export interface PreferencePageWrite<T> {
  readonly vault: string;
  /** The preference's slug: `pref-<slug>` (a retired page `ret-<slug>` is the same preference). */
  readonly slug: string;
  /** The page's frontmatter after the write, as the page carries it. */
  readonly frontmatter: FrontmatterMap | (() => FrontmatterMap);
  /** The legacy page write; runs only on an unswitched machine. */
  readonly legacy: () => T;
  /**
   * The page's body after the write, for a writer that writes one: its
   * prose (what the fields do not render) goes to the store as `text`
   * (FORMAT.md, "Preferences"). Absent for a writer that changes only
   * frontmatter, which leaves `text` as it is.
   */
  readonly body?: string | (() => string);
  /** Who decided; absent derives it from the process's origin channel. */
  readonly authority?: Authority;
  readonly configPath?: string;
}

/** The page's fields as the store records carry them. */
function storeFields(meta: FrontmatterMap): Record<string, unknown> {
  const {
    id: _id,
    kind: _kind,
    aliases: _aliases,
    ...fields
  } = typedPreferenceFields(storeFieldsOf(meta as Record<string, unknown>));
  return fields;
}

/** Route one preference page write; see the module docblock. */
export function routePreferencePage<T>(spec: PreferencePageWrite<T>): RoutedWrite<T> {
  // Vault-identity write guard (context-integrity-gates, Unit J): every
  // caller guards its own entry too; this one covers the shared path.
  assertVaultIdentityForWrite(spec.vault);
  const storeOnly = preferencesStoreOnly(spec.vault, spec.configPath);
  let fields: Record<string, unknown> | null = null;
  const fieldsOf = (): Record<string, unknown> => {
    if (fields === null) {
      const meta = typeof spec.frontmatter === "function" ? spec.frontmatter() : spec.frontmatter;
      fields = storeFields(meta);
      if (spec.body !== undefined) {
        const body = typeof spec.body === "function" ? spec.body() : spec.body;
        fields = withPreferenceProse(fields, meta, body);
      }
    }
    return fields;
  };
  let pagePrivacy: (() => boolean) | null = null;
  const privacy = (): boolean => {
    if (storeOnly && (storePreferenceEntry(spec.slug, spec.configPath)?.private ?? false)) {
      return true;
    }
    pagePrivacy ??= preferencePrivacy(spec.vault, fieldsOf());
    return pagePrivacy();
  };
  return withOperationPrivacy(privacy, () =>
    routeWrite({
      legacy: spec.legacy,
      store: () =>
        preferenceStoreRecords(
          `pref-${spec.slug}`,
          fieldsOf(),
          spec.authority ?? authorityFromOrigin(),
          privacy(),
        ),
      context: {
        vault: spec.vault,
        ...(spec.configPath !== undefined ? { configPath: spec.configPath } : {}),
      },
    }),
  );
}

/**
 * Write the whole text of the active preference page `pref-<slug>`: the
 * file on an unswitched machine, its records once switched.
 */
export function writePreferencePageText(
  vault: string,
  slug: string,
  text: string,
  options: { readonly authority?: Authority; readonly configPath?: string } = {},
): RoutedWrite<void> {
  return routePreferencePage({
    vault,
    slug,
    frontmatter: () => parseFrontmatterText(text)[0],
    body: () => parseFrontmatterText(text)[1],
    legacy: () => {
      atomicWriteFileSync(preferencePath(vault, slug), text);
    },
    ...options,
  });
}

/**
 * The text of the active preference page `pref-<slug>` a writer merges
 * into: the file on an unswitched machine (read by `readPage`), the page
 * rebuilt from the store's fold once switched (no body), or `null` when
 * there is none.
 */
export function existingPreferencePageText(
  vault: string,
  slug: string,
  readPage: (path: string) => string | null,
  configPath?: string,
): string | null {
  if (!preferencesStoreOnly(vault, configPath)) return readPage(preferencePath(vault, slug));
  const page = storePreferenceMeta(slug, configPath);
  return page === null || page.retired
    ? null
    : formatFrontmatter(page.meta, preferencePageBody(page.meta, page.text, false));
}

/** One preference of the store's fold as a page would carry it. */
export interface StorePreferencePage {
  readonly slug: string;
  readonly retired: boolean;
  /** The page's vault-relative path, `/`-separated, as the legacy tree names it. */
  readonly rel: string;
  /** The page's absolute path in the vault (no file exists once switched). */
  readonly abs: string;
  readonly meta: FrontmatterMap;
  /** The page body: the fold's `text`, else the body its fields render. */
  readonly body: string;
}

/** Every preference the store's fold holds, page-shaped (the store side of a page walk). */
export function storePreferencePages(vault: string, configPath?: string): StorePreferencePage[] {
  const out: StorePreferencePage[] = [];
  for (const slug of storePreferenceSlugs(configPath)) {
    const page = storePreferenceMeta(slug, configPath);
    if (page === null) continue;
    const rel = page.retired
      ? posix.join(BRAIN_RETIRED_REL, `ret-${slug}.md`)
      : posix.join(BRAIN_PREFERENCES_REL, `pref-${slug}.md`);
    out.push({
      slug,
      retired: page.retired,
      rel,
      abs: join(vault, ...rel.split("/")),
      meta: page.meta,
      body: preferencePageBody(page.meta, page.text, page.retired),
    });
  }
  return out;
}

/**
 * Write the fields a page-level rewrite changed on a preference of the
 * store's fold: `next` is the page's frontmatter after the rewrite. Only
 * the fields whose value changed are written. Returns whether anything
 * was written.
 */
export function rewriteStorePreference(
  vault: string,
  page: StorePreferencePage,
  next: FrontmatterMap,
  configPath?: string,
  nextBody?: string,
): boolean {
  const before = withPreferenceProse(storeFields(page.meta), page.meta, page.body, page.retired);
  const after =
    nextBody === undefined
      ? storeFields(next)
      : withPreferenceProse(storeFields(next), next, nextBody, page.retired);
  if (nextBody === undefined) delete before[PREFERENCE_TEXT_FIELD];
  // A field the rewrite dropped (lint consolidation, remediation, dedup)
  // is cleared (`null`): a record only proposes the fields it names, and
  // the page an unswitched machine rewrites loses the key.
  const changed: Record<string, unknown> = {};
  for (const name of new Set([...Object.keys(before), ...Object.keys(after)])) {
    const value = Object.hasOwn(after, name) ? after[name] : null;
    if (canonicalJson(value ?? null) !== canonicalJson(before[name] ?? null)) changed[name] = value;
  }
  if (Object.keys(changed).length === 0) return false;
  storeWritePreferenceFields(vault, page.slug, changed, configPath);
  return true;
}

/** Write `fields` of the preference `pref-<slug>` to the store only (a store-only machine). */
function storeWritePreferenceFields(
  vault: string,
  slug: string,
  fields: Record<string, unknown>,
  configPath?: string,
): void {
  const privacy = (): boolean =>
    (storePreferenceEntry(slug, configPath)?.private ?? true) || preferencePrivacy(vault, fields)();
  withOperationPrivacy(privacy, () =>
    storeWrite(
      () => preferenceStoreRecords(`pref-${slug}`, fields, authorityFromOrigin(), privacy()),
      { vault, ...(configPath !== undefined ? { configPath } : {}) },
    ),
  );
}