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
11.4 KB
Raw Blame
/**
 * Brain write surface: taste signals, the dream learning pass, apply-evidence records, and narrative notes.
 *
 * Extracted from the former brain-tools.ts monolith; registration
 * happens through the aggregator, which preserves the public
 * BRAIN_TOOLS surface.
 */

import { DREAM_GATE_NAMES } from "../../core/brain/dream-gates.ts";
import { DREAM_STEP_RUNNABLE } from "../../core/brain/dream-step.ts";
import { EXPIRATION_CLEAR } from "../../core/brain/expiration-set.ts";
import { MCP_PREVIEW_BUDGET } from "../preview-budget.ts";
import { type ToolDefinition } from "../tool-contract.ts";
import { toolBrainFeedback } from "./feedback-tool.ts";
import { toolBrainDream } from "./dream-tools.ts";
import { toolBrainApplyEvidence, toolBrainNote, toolBrainObservedUse } from "./evidence-tools.ts";
import { EXPIRE_TOOL, toolBrainExpire } from "./expire-tools.ts";

/**
 * The registered exit the force-confirmed refusal names (write-side
 * trust, Task 12). Resolved at module scope on the write-binding
 * precedent: an unregistered code is registry drift and fails at import
 * rather than inside the refusal it was meant to explain.
 */

export const FEEDBACK_TOOLS: ReadonlyArray<ToolDefinition> = Object.freeze([
  {
    name: "brain_feedback",
    kind: "write",
    description:
      "Record one Brain taste signal in the signal inbox. With `force_confirmed: true`, create the preference directly (skips the dream trial window).",
    inputSchema: {
      type: "object",
      properties: {
        topic: {
          type: "string",
          description: "Stable kebab-slug for the rule, e.g. `no-internal-abbrev`.",
        },
        signal: {
          type: "string",
          enum: ["positive", "negative"],
          description:
            "`positive` when the principle is the rule to follow, `negative` when it's what to avoid.",
        },
        principle: {
          type: "string",
          description: "One-line, agent-readable formulation of the rule (imperative voice).",
        },
        scope: {
          type: "string",
          description:
            "Optional soft category for later application-scope matching, e.g. `writing`, `coding`.",
        },
        source: {
          type: "array",
          items: { type: "string" },
          description: "Optional wikilinks to the artifacts or notes that triggered the signal.",
        },
        agent: {
          type: "string",
          description: "Optional agent identity override; defaults to the server-resolved name.",
        },
        raw: {
          type: "string",
          description: "Optional free-form raw quote (rendered under `## Raw` in the signal file).",
        },
        force_confirmed: {
          type: "boolean",
          description:
            "When true, also creates an immediately-active confirmed `pref-*` alongside the inbox signal, skipping the dream-pass promotion step.",
        },
        event_time: {
          type: "string",
          description:
            "Optional ISO-8601 event-time for a backfilled signal (when it actually happened). Stamps `created_at`/`valid_from`/`recorded_at`; absent uses wall-clock.",
        },
        idempotency_key: {
          type: "string",
          description:
            "Optional client key that dedupes retried calls: same key + same payload is a no-op; same key + different payload is rejected.",
        },
        expires: {
          type: "string",
          description:
            "Optional YYYY-MM-DD or ISO-8601 lifetime. Past it the signal (and any force-confirmed preference) drops out of default reads; the file is never deleted.",
        },
      },
      required: ["topic", "signal", "principle"],
      additionalProperties: false,
    },
    handler: toolBrainFeedback,
  },
  {
    name: "brain_dream",
    kind: "write",
    description:
      "Deterministic learning pass over the signal inbox. action=run (default) promotes inline; the staged lifecycle persists a reviewable bundle: stage -> validate -> apply (or discard), plus list and retriage. Typically scheduled via cron.",
    inputSchema: {
      type: "object",
      properties: {
        action: {
          type: "string",
          enum: ["run", "stage", "validate", "apply", "retriage", "discard", "list"],
          description:
            "run executes inline; stage persists a bundle; validate/apply/discard manage one by run_id; retriage re-scores a bundle's salience gate; list shows bundles.",
        },
        run_id: {
          type: "string",
          description: "Bundle id for validate/apply/retriage/discard (from action=stage or list).",
        },
        dry_run: {
          type: "boolean",
          description: "action=run only: compute the plan without writing any files.",
        },
        now: {
          type: "string",
          description:
            "Optional ISO-8601 timestamp used as the wall clock for the run (testing / replay).",
        },
        agent: {
          type: "string",
          description:
            "Optional caller identity; a mismatch with the configured primary agent emits a warning. Defaults to the server-resolved name.",
        },
        expect: {
          type: "integer",
          minimum: 0,
          description:
            "action=run count guard: assert the pass will create/confirm/retire/move exactly N preferences. On mismatch it aborts without writing.",
        },
        strict: {
          type: "boolean",
          description: "action=run: refuse a guardless run (no `expect`). Default false.",
        },
        step: {
          // Deliberately NOT an enum. A closed schema would reject a
          // non-runnable step with a generic validation error, losing the
          // specific reason `DreamStepNotRunnableError` carries - which
          // is the whole deliverable for the steps that are refused.
          type: "string",
          description:
            `action=run: run ONE step (${DREAM_STEP_RUNNABLE.join(", ")}) and return a partial ` +
            `result, not a run summary. Any other token is refused with the reason it cannot run alone.`,
        },
        gates: {
          type: "object",
          description:
            `action=run: override a phase gate for THIS RUN ONLY, never written back to ` +
            `the brain settings. Known gates: ${DREAM_GATE_NAMES.join(", ")}.`,
          properties: {
            heal_enrich: {
              type: "boolean",
              description:
                "Overrides dream.heal_enrich_enabled for this run. Omitted: the configured value decides.",
            },
          },
          additionalProperties: false,
        },
      },
      additionalProperties: false,
    },
    handler: toolBrainDream,
  },
  {
    name: "brain_apply_evidence",
    kind: "write",
    description:
      "Record whether an active preference was applied, violated, or marked outdated against a freshly-produced durable artifact. Appends one event to today's brain log. A single `outdated` event triggers retire on the next dream pass.",
    inputSchema: {
      type: "object",
      properties: {
        pref_id: {
          type: "string",
          description: "Preference id (`pref-<slug>` or bare `<slug>`).",
        },
        artifact: {
          type: "string",
          description:
            "Wikilink identifying the artifact; optional inclusive line-range suffix, e.g. `[[src/cli/main.ts:120-145]]`.",
        },
        result: {
          type: "string",
          enum: ["applied", "violated", "outdated"],
          description:
            "`applied` if the rule held, `violated` if broken, `outdated` if the artifact shows the rule itself is obsolete.",
        },
        agent: {
          type: "string",
          description: "Optional agent identity override; defaults to the server-resolved name.",
        },
        outcome: {
          type: "string",
          enum: ["success", "failure", "unknown"],
          description:
            "Optional downstream outcome of the artifact (t_d478df53): did the work the rule was applied to actually succeed? `unknown` is treated like an absent outcome.",
        },
        note: {
          type: "string",
          description: "Optional one-line context.",
        },
      },
      required: ["pref_id", "artifact", "result"],
      additionalProperties: false,
    },
    handler: toolBrainApplyEvidence,
  },
  {
    name: "brain_note",
    kind: "write",
    description:
      "Append one narrative-milestone line (release shipped, PR merged, fact discovered) to today's Brain log under the `note` event kind. Use when neither brain_feedback nor brain_apply_evidence fits.",
    inputSchema: {
      type: "object",
      properties: {
        text: {
          type: "string",
          description:
            "One-line narrative description. Newlines collapse to single spaces; the shared redactor strips secret-shaped tokens.",
        },
        agent: {
          type: "string",
          description: "Optional agent identity override; defaults to the server-resolved name.",
        },
      },
      required: ["text"],
      additionalProperties: false,
    },
    handler: toolBrainNote,
  },
  {
    name: "brain_observed_use",
    kind: "write",
    description:
      "Record session-end observed-use verdicts (USED/IGNORED/CONTRADICTED) per injected memory. The host supplies structured verdicts; the kernel stores and aggregates them into the observed-reuse recall-ranking signal (no LLM).",
    inputSchema: {
      type: "object",
      properties: {
        entries: {
          type: "array",
          description: "One verdict per injected memory.",
          items: {
            type: "object",
            properties: {
              id: { type: "string", description: "Injected memory id (e.g. docId:chunkId)." },
              path: { type: "string", description: "Vault-relative path when known." },
              verdict: {
                type: "string",
                enum: ["USED", "IGNORED", "CONTRADICTED"],
                description: "Observed use of this memory in the session.",
              },
            },
            required: ["id", "verdict"],
            additionalProperties: false,
          },
        },
        host: { type: "string", description: "Host label; defaults to 'mcp'." },
        session_id: { type: "string", description: "Correlation id for the session." },
        turn_id: { type: "string", description: "Correlation id for the prompt-submit turn." },
      },
      required: ["entries"],
      additionalProperties: false,
    },
    handler: toolBrainObservedUse,
  },
  {
    name: EXPIRE_TOOL,
    kind: "write",
    description:
      "Set, change or clear the expiration_date of one signal or preference, by id. An expired memory is filtered out of default reads and never deleted or moved. Clearing is the explicit word 'none'.",
    inputSchema: {
      type: "object",
      properties: {
        id: {
          type: "string",
          description:
            "Artifact id: sig-<date>-<slug>, pref-<slug> or ret-<slug>. Never a path - this surface does not accept one.",
        },
        expires: {
          type: "string",
          description: `YYYY-MM-DD, an ISO-8601 timestamp, or '${EXPIRATION_CLEAR}' to clear. An unparseable value is refused before any write.`,
        },
        agent: {
          type: "string",
          description: "Optional agent identity stamped on the audit event.",
        },
      },
      required: ["id", "expires"],
      additionalProperties: false,
    },
    previewBudget: MCP_PREVIEW_BUDGET,
    handler: toolBrainExpire,
  },
]);