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
/**
 * Consolidated brief dispatcher: morning/daily/weekly/monthly views, digest, and the operator summary behind the brain_brief view parameter.
 *
 * Extracted from the former brain-tools.ts monolith; registration
 * happens through the aggregator, which preserves the public
 * BRAIN_TOOLS surface.
 */

import { INVALID_PARAMS, MCPError } from "../protocol.ts";
import { type ServerContext, type ToolDefinition } from "../tool-contract.ts";
import { MCP_PREVIEW_BUDGET } from "../preview-budget.ts";
import { AGENT_SCOPE_ARG_NAME, AGENT_SCOPE_SCHEMA } from "../coerce.ts";
import { dispatchByView, localizeEnvelope } from "./shared.ts";
import type { ProgressSink } from "../../core/brain/progress.ts";
import {
  toolBrainDailyBrief,
  toolBrainDigest,
  toolBrainMonthlyReview,
  toolBrainMorningBrief,
  toolBrainOperatorSummary,
  toolBrainToday,
  toolBrainWeeklySynthesis,
} from "./brief-view-tools.ts";

/** What a reader outside the operator's queue is told about it: nothing. */
const BRIEF_VIEW_HANDLERS: Readonly<
  Record<
    string,
    (
      ctx: ServerContext,
      args: Record<string, unknown>,
      onProgress?: ProgressSink,
    ) => Promise<unknown> | unknown
  >
> = Object.freeze({
  morning: toolBrainMorningBrief,
  daily: toolBrainDailyBrief,
  weekly: toolBrainWeeklySynthesis,
  monthly: toolBrainMonthlyReview,
  operator: toolBrainOperatorSummary,
  digest: toolBrainDigest,
  today: toolBrainToday,
});

/**
 * The views that accept an explicit `agent_scope` argument.
 *
 * EVERY view in this dispatcher narrows to the caller's server-resolved
 * identity under `integrity.owner_scope_delivery: fail`, whether or not
 * it takes the argument: `morning` and `digest` thread the scope through
 * their builders; `daily` and `weekly` ask the enforced rule per row
 * through `periodRowsAtReach`; `monthly` and `today` through the
 * request's reference view; `operator` through the doctor/action view it
 * composes. The set below therefore answers a narrower question: where
 * the argument itself is accepted. It is declared once for the whole
 * tool, so a view that cannot honour it must not silently discard it -
 * the other five REFUSE it (`context-integrity-gates`, A6) and stay
 * scoped by the identity instead.
 */
const AGENT_SCOPE_VIEWS: ReadonlySet<string> = new Set(["morning", "digest"]);

async function toolBrainBrief(
  ctx: ServerContext,
  args: Record<string, unknown>,
  onProgress?: ProgressSink,
): Promise<unknown> {
  const view = typeof args["view"] === "string" ? args["view"] : "";
  const scopeSupplied =
    AGENT_SCOPE_ARG_NAME in args &&
    args[AGENT_SCOPE_ARG_NAME] !== undefined &&
    args[AGENT_SCOPE_ARG_NAME] !== null;
  // Only an EXPLICIT argument is refused: the gated surfaces default their
  // scope from `ServerContext.agentName`, and refusing that would make the
  // tool unusable for every client that never passes the argument.
  if (scopeSupplied && view in BRIEF_VIEW_HANDLERS && !AGENT_SCOPE_VIEWS.has(view)) {
    throw new MCPError(
      INVALID_PARAMS,
      `brain_brief view=${view} cannot honour '${AGENT_SCOPE_ARG_NAME}'; ` +
        `an explicit scope is accepted by view=${[...AGENT_SCOPE_VIEWS].join(", view=")}; ` +
        `every view is already scoped by the server-resolved identity`,
    );
  }
  return localizeEnvelope(ctx, await dispatchByView(BRIEF_VIEW_HANDLERS, ctx, args, onProgress));
}

export const BRIEF_TOOLS: ReadonlyArray<ToolDefinition> = Object.freeze([
  {
    name: "brain_brief",
    // Write-mode-dominant (tool-contract.ts), not "read": view=digest
    // persists the window's structured snapshot under `Brain/reports/`
    // through `captureReportDelta` when report snapshots are enabled, so
    // the next digest run can diff against it. The write is opt-in and
    // skipped for restricted or scope-narrowed callers, but an opt-in
    // durable write still classifies the whole tool `write`.
    kind: "write",
    previewBudget: MCP_PREVIEW_BUDGET,
    description:
      "Brain summary, one tool for every window: view=morning, daily, weekly, monthly, operator (maintenance dashboard), digest (activity window + report snapshot), or today (operator dashboard: due obligations, one-off pledges, open loops, recent activity, totals). Replaces the per-window brief tools.",
    inputSchema: {
      type: "object",
      properties: {
        view: {
          type: "string",
          enum: ["morning", "daily", "weekly", "monthly", "operator", "digest", "today"],
          description: "Which summary to produce.",
        },
        date: {
          type: "string",
          description: "view=daily: ISO date (YYYY-MM-DD), default today UTC.",
        },
        week_end: {
          type: "string",
          description: "view=weekly: ISO end date (exclusive), default today UTC.",
        },
        month: {
          type: "string",
          description: "view=monthly: target month (YYYY-MM), default current UTC month.",
        },
        since: {
          type: "string",
          description: "view=digest: inclusive ISO lower bound, default until - 24h.",
        },
        until: {
          type: "string",
          description: "view=digest: exclusive ISO upper bound, default now.",
        },
        format: {
          type: "string",
          enum: ["markdown", "json"],
          description: "view=digest: output format, default markdown.",
        },
        top_k: {
          type: "integer",
          minimum: 1,
          description: "view=morning: max confirmed preferences (default 10).",
        },
        lookback_days: {
          type: "integer",
          // 0 is a valid today window (empty recent-activity section); view=morning
          // still rejects 0 at runtime via its positive-integer coercer.
          minimum: 0,
          description:
            "view=morning: days of log history (default 7). view=today: recent-activity window in days (default 7).",
        },
        limit: {
          type: "integer",
          minimum: 0,
          description: "view=today: max recent-activity entries, newest first (default 20).",
        },
        max_chars_per_memory: {
          type: "integer",
          minimum: 1,
          description: "view=morning: per-entry character cap.",
        },
        max_total_chars: {
          type: "integer",
          minimum: 1,
          description: "view=morning: total character cap.",
        },
        include_dream: {
          type: "boolean",
          description: "view=operator: fold a dry-run dream delta in (default true).",
        },
        top_actions: {
          type: "integer",
          minimum: 0,
          description: "view=operator: cap on ranked actions (default 5).",
        },
        // The one place this argument's shared description is overridden,
        // and only to name WHICH views honour it - a caller cannot learn
        // that from a tool-wide declaration, and learning it from a
        // rejection after the fact is worse. Kept inside the registry
        // guard's 160-character property-description cap.
        agent_scope: {
          ...AGENT_SCOPE_SCHEMA,
          description:
            "Optional agent-ownership scope; ownerless memories always match. Accepted by view=morning and view=digest only; other views reject it, never ignore it.",
        },
      },
      required: ["view"],
      additionalProperties: false,
    },
    handler: toolBrainBrief,
  },
]);