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
6.9 KB
Raw Blame
/**
 * Shared body for appending a `note` event to today's Brain log.
 * Both the MCP `brain_note` tool and the `o2b brain note` CLI verb
 * delegate here so the on-disk shape cannot drift between them.
 * Wrappers translate the thrown `Error` into their protocol's
 * idiom (MCP `INVALID_PARAMS` envelope, CLI exit code).
 */

import { resolve } from "node:path";

import { normalizeAgentArgument } from "../agent-identity.ts";
import { resolveAgentName } from "../config.ts";
import { vaultRelative } from "../path-safety.ts";
import { sanitiseTextField } from "../redactor.ts";

import {
  callerInput,
  opaqueFields,
  operationPrivacy,
  type OperationPrivacy,
  type PrivacyVerdict,
} from "../store/operation-privacy.ts";
import { withOperationPrivacy } from "../store/operation-scope.ts";
import { appendLogEvent, logEventPrivacyContent, type AppendLogEventResult } from "./log.ts";
import {
  mirrorNote,
  mirrorReportFields,
  resolveSharedNamespace,
  type MirrorOutcome,
} from "./shared-namespace.ts";
import { isoSecond } from "./time.ts";
import { BRAIN_LOG_EVENT_KIND } from "./types.ts";

const NOTE_TEXT_MAX_LEN = 4096;

export interface AppendBrainNoteInput {
  /** The vault; `null` on a store-only machine with none (design D14). */
  readonly vault: string | null;
  readonly text: string;
  /** Identity override. Resolver default is used when omitted or blank. */
  readonly agent?: string;
  /** Wall clock for the event timestamp. Defaults to `new Date()`. */
  readonly now?: Date;
  /** Config path for `resolveAgentName`. Optional. */
  readonly configPath?: string;
  /**
   * The privacy verdict of an enclosing operation (a write batch), which
   * the event's store record inherits. See `AppendLogEventOptions.storePrivate`.
   */
  readonly storePrivate?: PrivacyVerdict;
}

export interface AppendBrainNoteResult {
  /** Canonical ISO-8601 UTC second of the appended event. */
  readonly logged_at: string;
  /**
   * Where the event went: the vault-relative POSIX path of the log day
   * page (`Brain/log/<date>.md`) on an unswitched machine, the store shard
   * (`shared/log/<device>/<YYYY-MM>.jsonl`) on a store-only one.
   */
  readonly log_path: string;
  /** Absolute filesystem path of that file. */
  readonly absolute_log_path: string;
  /** The store record id of the event on a store-only machine; absent otherwise. */
  readonly record_id?: string;
  /** Identity actually written into the log entry. */
  readonly agent: string;
  /**
   * Shared-namespace mirror outcome (t_936a1a61). Present only when
   * the `shared_namespace` config key is set - unconfigured setups
   * keep the previous result shape.
   */
  readonly mirror?: MirrorOutcome;
  /**
   * Why the mirror did not succeed. Present exactly when `mirror` is
   * present and is not `ok`: a fail-soft outcome that carries no diagnosis
   * is a bit the operator cannot act on.
   */
  readonly mirror_reason?: string;
}

function sanitiseNoteText(text: string): string {
  return sanitiseTextField(text, { maxLen: NOTE_TEXT_MAX_LEN, singleLine: true }).trim();
}

/**
 * Fields of a note call's input that are local settings, not text: the
 * vault, the clock, the config path and an enclosing verdict.
 */
const NOTE_INPUT_OPAQUE: ReadonlySet<string> = opaqueFields(
  "vault",
  "now",
  "configPath",
  "storePrivate",
);

/**
 * The privacy verdict of the note event {@link appendBrainNote} would
 * append for `input`: its whole input (the text, raw and as the event
 * carries it, and the agent), judged as the log appender judges the
 * event, plus `inherit` (an enclosing operation). A write batch judges
 * its log lines with it before it commits.
 */
export function brainNotePrivacy(
  vault: string | null,
  input: Omit<AppendBrainNoteInput, "vault">,
  inherit?: PrivacyVerdict,
): OperationPrivacy {
  return operationPrivacy(vault, {
    content: [
      logEventPrivacyContent({ text: sanitiseNoteText(input.text) }),
      callerInput(input, NOTE_INPUT_OPAQUE),
    ],
    inherit: [inherit],
  });
}

/**
 * Append one `note` event to the Brain log through `appendLogEvent`: the
 * log day files on an unswitched machine, the store only on a store-only
 * one. Throws plain `Error` on empty text
 * — wrappers translate the error to their protocol's idiom.
 */
export function appendBrainNote(input: AppendBrainNoteInput): AppendBrainNoteResult {
  const sanitised = sanitiseNoteText(input.text);
  if (!sanitised) {
    throw new Error("brain_note: text is required");
  }
  // Every store record written from here on (the note event, a mirror
  // copy, anything a writer below appends) carries this call's verdict
  // (`store/operation-scope.ts`).
  const privacy = brainNotePrivacy(input.vault, input, input.storePrivate);
  return withOperationPrivacy(privacy, () => appendJudgedNote(input, sanitised, privacy));
}

/** The note's log as the result reports it: the store shard, or the day file vault-relative. */
function reportedLogPath(res: AppendLogEventResult, vault: string | null): string {
  if (res.storeShard !== null) return res.storeShard;
  if (vault === null || res.logPath === "") return res.logPath;
  return vaultRelative(res.logPath, vault);
}

function appendJudgedNote(
  input: AppendBrainNoteInput,
  sanitised: string,
  privacy: OperationPrivacy,
): AppendBrainNoteResult {
  const explicitAgent = normalizeAgentArgument(input.agent ?? null);
  const agent = explicitAgent ?? resolveAgentName(input.configPath);
  const timestamp = isoSecond(input.now ?? new Date());
  const entry = {
    timestamp,
    eventType: BRAIN_LOG_EVENT_KIND.note,
    body: { text: sanitised, agent },
  } as const;
  // The routing (store-only or not) and the store root follow the same
  // machine config the agent name came from.
  const res = appendLogEvent(input.vault, entry, {
    storePrivate: privacy,
    ...(input.configPath !== undefined ? { configPath: input.configPath } : {}),
  });
  // t_936a1a61: mirror AFTER the primary append succeeded; the mirror
  // is fail-soft and must never alter the primary result. The mirror
  // copies the note into another vault's legacy log: with no vault there
  // is nothing to mirror from, and once the note went to the store a
  // "mirror" would only be a second record in this same store.
  const vault = input.vault;
  const shared =
    vault === null || res.stored === "store"
      ? null
      : resolveSharedNamespace(input.configPath ?? null);
  const mirror =
    shared === null || vault === null
      ? undefined
      : mirrorNote(
          shared,
          vault,
          { text: sanitised, agent, ...(input.now ? { now: input.now } : {}) },
          input.configPath,
        );
  return {
    logged_at: timestamp,
    log_path: reportedLogPath(res, vault),
    // A fail-open write that did not land names no file (never the cwd).
    absolute_log_path: res.logPath === "" ? "" : resolve(res.logPath),
    ...(res.recordId !== null ? { record_id: res.recordId } : {}),
    agent,
    ...mirrorReportFields(mirror),
  };
}