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
8.6 KB
Raw Blame
/**
 * Pin / unpin operations.
 *
 * A pinned preference is exempt from the three automatic retire reasons
 * (`stale-no-evidence`, `expired-unconfirmed`, `rebutted`). Pinning is a
 * CLI-only operation β€” the MCP surface deliberately does NOT expose it
 * so autonomous agents cannot mutate the protected set (design doc
 * Β§7.4, Β§15 Step 9b).
 *
 * Surface:
 *
 *   - {@link setPinned} flips a single preference's `pinned` boolean
 *     atomically. The frontmatter is rewritten through
 *     `writeFrontmatterAtomic` with `overwrite: true`. The body bytes
 *     of the preference are preserved verbatim β€” we only touch the
 *     frontmatter. The function is idempotent: a no-op flip returns
 *     `changed: false` and writes nothing.
 *
 *   - {@link isPinned} is the trivial accessor with a default of
 *     `false`. The parser in `preference.ts` already coerces missing
 *     frontmatter values to `false`, but we keep this helper for
 *     callers (notably `dream`) that want to express intent without
 *     reaching into the `BrainPreference` shape directly.
 *
 * On a store-only machine (task 2.10) the flip is one `preference-set`
 * record of the field, read against the store's fold; no page changes.
 *
 * A successful flip emits a `pin` or `unpin` log event via
 * `appendLogEvent`. A no-op (`changed: false`) emits no log entry β€” the
 * log is reserved for state transitions, not redundant calls.
 */

import { legacyVaultOf } from "./no-vault.ts";
import { existsSync } from "node:fs";

import { writeFrontmatterAtomic, parseFrontmatter } from "../vault.ts";
import { authorityFromOrigin } from "../store/dual-write.ts";
import { routeWrite } from "../store/store-write.ts";
import { withOperationPrivacy } from "../store/operation-scope.ts";
import { preferenceSetRecord } from "../store/dual-write-records.ts";
import { callerInput, opaqueFields } from "../store/operation-privacy.ts";
import { regenerateActiveQuiet } from "./active.ts";
import { appendLogEvent, logEventPrivacyContent, type BrainLogEntry } from "./log.ts";
import {
  loadPreference,
  preferencePrivacy,
  storeFieldsOf,
  storePreferenceMeta,
} from "./preference.ts";
import { preferencesStoreOnly } from "./preference-store.ts";
import { preferencePathOf, validateSlug } from "./paths.ts";
import { assertVaultIdentityForWrite } from "./vault-identity.ts";
import { isoSecond } from "./time.ts";
import { BRAIN_LOG_EVENT_KIND, type BrainPreference } from "./types.ts";
import { renderPrefLink } from "./wikilink.ts";
import { BrainPreferenceNotFoundError } from "./apply-evidence.ts";

/** Fields of a pin call's input that are not text: its clock. */
const PIN_INPUT_OPAQUE: ReadonlySet<string> = opaqueFields("now");

export interface SetPinnedOptions {
  /** Override the wall clock used in the log event. */
  readonly now?: Date;
  /**
   * Source agent recorded as a payload field on the log event. Defaults
   * to `"cli"` to reflect that pinning is a CLI-only operation; the
   * CLI passes the resolved `AGENT_NAME`. The MCP surface never reaches
   * this code path (Brain MCP tools do not expose pin/unpin).
   */
  readonly agent?: string;
}

export interface SetPinnedResult {
  /** Absolute path of the preference file. */
  readonly path: string;
  /**
   * `true` if the on-disk value transitioned (false β†’ true or
   * true β†’ false). `false` when the requested state was already set β€”
   * the call is a no-op and no log entry was written.
   */
  readonly changed: boolean;
}

/**
 * Flip a preference's `pinned` frontmatter field. Atomic and
 * idempotent.
 *
 * @throws {@link BrainPreferenceNotFoundError} when the preference does
 *   not resolve to a file under `Brain/preferences/`. We reuse the
 *   `apply-evidence` error class so CLI surface treats both
 *   "wrong pref_id" cases consistently.
 */
export function setPinned(
  vault: string | null,
  prefId: string,
  value: boolean,
  opts: SetPinnedOptions = {},
): SetPinnedResult {
  // Vault-identity write guard (context-integrity-gates, Unit J). With no
  // vault the store write checks the store identity instead (D14 item 13).
  if (vault !== null) assertVaultIdentityForWrite(vault);
  if (typeof prefId !== "string" || !prefId.trim()) {
    throw new Error("setPinned missing field: pref_id");
  }
  if (typeof value !== "boolean") {
    throw new Error(`setPinned: 'value' must be a boolean; got ${JSON.stringify(value)}`);
  }

  const trimmed = prefId.trim();
  const slug = trimmed.startsWith("pref-") ? trimmed.slice("pref-".length) : trimmed;
  if (!slug) {
    throw new Error(`setPinned: invalid pref_id (empty slug): ${prefId}`);
  }
  validateSlug(slug);
  const path = preferencePathOf(vault, slug);
  // Store-only (task 2.10), and always with no vault: the preference is the
  // store's fold and the flip is one `preference-set` record; no page is
  // rewritten.
  const storeOnly = vault === null || preferencesStoreOnly(vault);
  // Parse the preference once, to drive the idempotency check off the
  // canonical boolean (rather than the raw frontmatter string), and to
  // validate its shape before we rewrite it. A corrupt preference here
  // is a hard error β€” the caller asked us to mutate a specific rule;
  // we refuse to make that decision blindly. `null` is "no such
  // preference" in both modes (no page, or no live fold entry).
  const loaded = storeOnly || existsSync(path) ? loadPreference(vault, slug) : null;
  if (loaded === null) throw new BrainPreferenceNotFoundError(`pref-${slug}`, path);
  const current: BrainPreference = loaded;
  if (current.pinned === value) {
    return { path, changed: false };
  }

  // Read the raw frontmatter + body so we can rewrite without
  // disturbing the human-authored prose ("## Principle", "## Origin",
  // "## How to apply", and any custom sections appended downstream).
  // The preference's fields, for the privacy verdict below.
  const meta = storeOnly ? (storePreferenceMeta(slug)?.meta ?? {}) : parseFrontmatter(path)[0];
  const newMeta = { ...meta, pinned: value };
  // Emit the log event only on a real transition.
  const now = opts.now ?? new Date();
  const entry: BrainLogEntry = {
    timestamp: isoSecond(now),
    eventType: value ? BRAIN_LOG_EVENT_KIND.pin : BRAIN_LOG_EVENT_KIND.unpin,
    body: {
      preference: renderPrefLink({
        id: `pref-${slug}`,
        principle: current.principle,
      }),
      agent: (opts.agent ?? "cli").trim() || "cli",
    },
  };
  // One privacy verdict for both store records of this call, the pinned
  // field and the log event: the preference's own (its frontmatter, its
  // content fields), the event's body and the caller's whole input.
  const privacy = preferencePrivacy(vault, storeFieldsOf(newMeta), [
    logEventPrivacyContent(entry.body),
    callerInput({ prefId, ...opts }, PIN_INPUT_OPAQUE),
  ]);
  // Every store record written from here on, by this call or by any
  // writer it calls, carries this verdict (`store/operation-scope.ts`).
  return withOperationPrivacy(privacy, () => {
    // Brain store dual write (task 1.11): the one field this call changed,
    // filed under the preference's own scope.
    // On a store-only machine that record is the whole write.
    const routed = routeWrite({
      // The page is read again inside the write: whatever mode the route
      // decides on, the legacy page keeps its own prose and frontmatter.
      legacy: () => {
        const [pageMeta, pageBody] = parseFrontmatter(path);
        return writeFrontmatterAtomic(path, { ...pageMeta, pinned: value }, pageBody, {
          overwrite: true,
          existsErrorKind: "preference",
          vaultForRelativePath: legacyVaultOf(vault, "setPinned"),
        });
      },
      store: () => {
        const record = preferenceSetRecord({
          id: `pref-${slug}`,
          frontmatter: { pinned: value },
          authority: authorityFromOrigin(),
          private: privacy(),
        });
        const scope = current.scope?.trim();
        return record === null ? null : { ...record, scope: scope ? scope : null };
      },
      context: { vault },
    });
    appendLogEvent(vault, entry, { storePrivate: privacy });
    // The digest is a page of the legacy tree; a store-only machine renders
    // it on demand (design D14 item 7). Decided by the route the write took.
    if (routed.mode === "legacy") regenerateActiveQuiet(legacyVaultOf(vault, "setPinned"), { now });

    return { path, changed: true };
  });
}

/**
 * Read the `pinned` boolean off a parsed preference, defaulting to
 * `false`. The parser already coerces missing/null values, so this is
 * a trivial accessor β€” but having it as a named helper keeps `dream`'s
 * pin-skip branches readable.
 */
export function isPinned(pref: BrainPreference): boolean {
  return pref.pinned === true;
}