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
21.7 KB
Raw Blame
/**
 * Procedural memory: skill proposals, procedural reconcile, recurrence diagnostics, and the procedural graph.
 *
 * Extracted from the former brain-tools.ts monolith; registration
 * happens through the aggregator, which preserves the public
 * BRAIN_TOOLS surface.
 */

import { join } from "node:path";
import {
  acceptSkillProposal,
  discardUnreadableSkillAcceptJournals,
  learnSkillProposals,
  listPendingSkillProposals,
  pendingSkillProposalPatternKind,
  readSkillRewriteStatus,
  recoverSkillProposalAccepts,
  rejectSkillProposal,
  resolveSkillProposalEvidence,
  SCORED_REWRITE_PATTERN_KIND,
  type SkillContractInput,
} from "../../core/brain/skill-proposals.ts";
import { commitSkillPageDraft, planSkillPageDrafts } from "../../core/brain/skill-page-drafts.ts";
import { deriveSkillUsage } from "../../core/brain/skill-usage.ts";
import { resolveSkillsDir } from "../../core/config.ts";
import {
  listProceduralMemory,
  markProceduralMemoryUsed,
  recordProceduralOutcome,
  rankProceduralMemory,
  reconcileProceduralMemory,
} from "../../core/brain/procedural-memory.ts";
import { readProceduralGraph, rebuildProceduralGraph } from "../../core/brain/procedural-graph.ts";
import { readProceduralHints, rebuildProceduralHints } from "../../core/brain/procedural-hints.ts";
import {
  applyRecurrenceEvidence,
  getRecurrenceEntry,
  listRecurrenceEntries,
  purgeRecurrenceSource,
} from "../../core/brain/recurrence.ts";
import { INVALID_PARAMS, MCPError } from "../protocol.ts";
import { contextReach } from "../tool-contract.ts";
import { reachView } from "../../core/brain/reach-view.ts";
import type { ServerContext, ToolDefinition } from "../tool-contract.ts";
import { coerceStrList, unknownOperationError } from "../coerce.ts";
import { coercePositiveInteger, optionalStringArg, requiredStringArg } from "./shared.ts";
import { readableAtContextReach } from "./reach-readable.ts";
// Record-lane tools: with no vault their pages are store records (task 2.10 WP6).
import { laneVault } from "./lane-vault.ts";

async function toolBrainSkillProposals(
  ctx: ServerContext,
  args: Record<string, unknown>,
): Promise<Record<string, unknown>> {
  const operation = requiredStringArg("brain_skill_proposals", args, "operation");
  if (operation === "learn") {
    const minSupport = coercePositiveInteger(
      "brain_skill_proposals",
      "min_support",
      args["min_support"],
    );
    const result =
      minSupport !== undefined
        ? learnSkillProposals(laneVault(ctx), { minSupport })
        : learnSkillProposals(laneVault(ctx));
    return { ...result };
  }
  if (operation === "list") {
    const proposals = listPendingSkillProposals(laneVault(ctx));
    return { total: proposals.length, proposals };
  }
  if (operation === "accept") {
    const slug = requiredStringArg("brain_skill_proposals", args, "slug");
    refuseScoredRewriteAccept(laneVault(ctx), slug);
    const note = optionalStringArg("brain_skill_proposals", args, "note");
    const contract = readSkillContract(args);
    // Resolved from THIS server's config chain: a `mature_page` accept
    // materializes a SKILL.md into whichever skills root it names, and the
    // core cannot know which chain the server was started with.
    const skillsRoot = resolveSkillsDir(ctx.configPath ?? undefined);
    const reviewed = acceptSkillProposal(laneVault(ctx), slug, {
      ...(note ? { note } : {}),
      ...(contract ? { contract } : {}),
      ...(skillsRoot !== null ? { skillsRoot } : {}),
    });
    return { ...reviewed };
  }
  if (operation === "page_candidates") {
    // Read-only: which mature vault pages deserve a skill, each with its
    // own needs-llm-step envelope, plus every page the gate turned down
    // with the reason it did.
    const skillsDir = resolveSkillsDir(ctx.configPath ?? undefined);
    const report = planSkillPageDrafts(laneVault(ctx), {
      now: new Date(),
      ...(ctx.repoRoot ? { repoRoot: ctx.repoRoot } : {}),
      ...(skillsDir !== null ? { skillsDir } : {}),
    });
    // `planSkillPageDrafts` walks with `MAINTENANCE_LANE_REACH`, which is
    // right for a plan that has to see the whole vault it is proposing
    // over - and wrong to hand to a caller unfiltered, because both lists
    // report a page's path and title and `skipped` adds a `detail` about
    // it. The rule is asked here, over what the caller is told.
    //
    // `pages_scanned` is recomputed from the visible lists for the same
    // reason `brain_hygiene` recomputes its counts: a corpus size taken
    // before the filter states how many pages were withheld.
    const view = reachView(laneVault(ctx), contextReach(ctx));
    const admitted = report.admitted.filter((c) => view.visible(c.path));
    const skipped = report.skipped.filter((s) => view.visible(s.path));
    return {
      generated_at: report.generatedAt,
      pages_scanned: view.filtersNothing ? report.pagesScanned : admitted.length + skipped.length,
      admitted: admitted.map((c) => ({
        path: c.path,
        title: c.title,
        tier: c.tier,
        lifecycle: c.lifecycle,
        confidence: c.confidence,
        reuse_score: c.reuseScore,
        reuse_observations: c.reuseObservations,
        llm_step: c.llmStep,
      })),
      skipped: skipped.map((s) => ({
        path: s.path,
        title: s.title,
        reason: s.reason,
        detail: s.detail,
      })),
    };
  }
  if (operation === "page_draft") {
    const page = requiredStringArg("brain_skill_proposals", args, "page");
    const result = commitSkillPageDraft(laneVault(ctx), page, args["draft"], { now: new Date() });
    return { ...result };
  }
  if (operation === "evidence") {
    const slug = requiredStringArg("brain_skill_proposals", args, "slug");
    return { ...resolveSkillProposalEvidence(laneVault(ctx), slug) };
  }
  if (operation === "reject") {
    const slug = requiredStringArg("brain_skill_proposals", args, "slug");
    const note = requiredStringArg("brain_skill_proposals", args, "note");
    const reviewed = rejectSkillProposal(laneVault(ctx), slug, { note });
    return { ...reviewed };
  }
  if (operation === "recover") {
    // The accept sequence's write-ahead journal was recoverable in the
    // library and reachable from no tool, so an agent whose accept
    // crashed had nothing to call. Both refusals it can raise carry the
    // file and the exit in their message; they surface as errors here
    // rather than as a result field, because neither is a state this
    // operation completed.
    const discarded =
      args["discard_unreadable"] === true
        ? discardUnreadableSkillAcceptJournals(laneVault(ctx))
        : [];
    const recovered = recoverSkillProposalAccepts(laneVault(ctx));
    return { discarded, recovered, total: recovered.length };
  }
  if (operation === "usage") {
    // Per-skill invocation telemetry (t_56a12bde): deterministic counts
    // derived from skill_invoked continuity records, distinct from proposing
    // or ranking. Real usage evidence for the dream/synthesis pass.
    // Each row also carries `offerAttributedCount` (t_ccb05134) - how many of
    // those invocations cited the offer they came from. The command-line
    // surface prints the same figure as `from_offer=`. The remainder are not
    // unattributed-by-error: most runtimes' skill calls follow no offer.
    const usage = deriveSkillUsage(laneVault(ctx));
    return { total: usage.length, usage };
  }
  throw unknownOperationError(
    "brain_skill_proposals: operation must be one of " +
      "learn|list|accept|reject|recover|usage|evidence|page_candidates|page_draft",
  );
}

/**
 * Read the optional execution contract from an accept payload. Returns
 * undefined when the caller supplied none, so the accept path stays
 * byte-identical to a pre-contract acceptance.
 */
function readSkillContract(args: Record<string, unknown>): SkillContractInput | undefined {
  const prerequisites = coerceStrList(args, "prerequisites");
  const rollback = coerceStrList(args, "rollback");
  const sideEffects = coerceStrList(args, "side_effects");
  const verification = coerceStrList(args, "verification");
  if (
    prerequisites.length === 0 &&
    rollback.length === 0 &&
    sideEffects.length === 0 &&
    verification.length === 0
  ) {
    return undefined;
  }
  return { prerequisites, rollback, sideEffects, verification };
}

/**
 * Refuse the one accept the design keeps out of the agent's reach
 * (review security M1c): a `scored_rewrite` proposal OVERWRITES an
 * incumbent SKILL.md, and its acceptance is the operator's step - MCP
 * proposes, the human accepts on the command line. The sibling read tool
 * `brain_skill_rewrite_status` states this in its own description; this
 * guard is what makes it true for the whole surface family.
 *
 * Mined, declared and mature-page accepts are unchanged: they create or
 * fill vault pages, they never overwrite, and the calling agent has always
 * been able to write those trees directly.
 */
function refuseScoredRewriteAccept(vault: string, slug: string): void {
  if (pendingSkillProposalPatternKind(vault, slug) !== SCORED_REWRITE_PATTERN_KIND) return;
  throw new MCPError(
    INVALID_PARAMS,
    `brain_skill_proposals: '${slug}' is a ${SCORED_REWRITE_PATTERN_KIND} proposal, whose accept ` +
      "OVERWRITES an incumbent skill; MCP never accepts a benchmark-gated rewrite - the " +
      "operator reviews and accepts it on the command line: o2b brain skill-proposals accept",
  );
}

async function toolBrainProceduralMemory(
  ctx: ServerContext,
  args: Record<string, unknown>,
): Promise<Record<string, unknown>> {
  const operation = requiredStringArg("brain_procedural_memory", args, "operation");
  // An entry names its page's path, title and frontmatter lists, so a page
  // the caller may not read at its reach is answered as an absent one: left
  // out of every count and list, and an unknown id to the two mark
  // operations, refused before anything is written.
  const readable = readableAtContextReach(ctx);
  const unknownId = (id: string): boolean => {
    const entry = listProceduralMemory(laneVault(ctx)).find((e) => e.id === id);
    return entry === undefined || !readable(entry.sourcePath);
  };
  if (operation === "reconcile") {
    const roots = coerceStrList(args, "roots");
    const effectiveRoots =
      roots.length > 0
        ? roots
        : [
            join(laneVault(ctx), "Brain", "procedures"),
            join(laneVault(ctx), "skills"),
            join(laneVault(ctx), "runbooks"),
          ];
    return {
      ...reconcileProceduralMemory(laneVault(ctx), { roots: effectiveRoots, include: readable }),
    };
  }
  if (operation === "list") {
    const entries = listProceduralMemory(laneVault(ctx)).filter((e) => readable(e.sourcePath));
    // Opt-in success-rate ranking (t_703f7b18); default order unchanged.
    const ordered = args["ranked"] === true ? rankProceduralMemory(entries) : entries;
    return { total: ordered.length, entries: ordered };
  }
  if (operation === "mark_used") {
    const id = requiredStringArg("brain_procedural_memory", args, "id");
    const updated = unknownId(id) ? null : markProceduralMemoryUsed(laneVault(ctx), id);
    if (!updated) {
      throw new MCPError(INVALID_PARAMS, `brain_procedural_memory: unknown entry id: ${id}`);
    }
    return { ...updated };
  }
  if (operation === "mark_outcome") {
    const id = requiredStringArg("brain_procedural_memory", args, "id");
    const outcome = requiredStringArg("brain_procedural_memory", args, "outcome");
    if (outcome !== "success" && outcome !== "failure") {
      throw new MCPError(
        INVALID_PARAMS,
        "brain_procedural_memory: outcome must be 'success' or 'failure'",
      );
    }
    const updated = unknownId(id) ? null : recordProceduralOutcome(laneVault(ctx), id, outcome);
    if (!updated) {
      throw new MCPError(INVALID_PARAMS, `brain_procedural_memory: unknown entry id: ${id}`);
    }
    return { ...updated };
  }
  throw unknownOperationError(
    "brain_procedural_memory: operation must be one of reconcile|list|mark_used|mark_outcome",
  );
}

async function toolBrainRecurrence(
  ctx: ServerContext,
  args: Record<string, unknown>,
): Promise<Record<string, unknown>> {
  const operation = requiredStringArg("brain_recurrence", args, "operation");
  if (operation === "list") {
    const entries = listRecurrenceEntries(laneVault(ctx));
    return { total: entries.length, entries };
  }
  if (operation === "show") {
    const contentHash = requiredStringArg("brain_recurrence", args, "content_hash");
    const entry = getRecurrenceEntry(laneVault(ctx), contentHash);
    if (!entry) {
      throw new MCPError(INVALID_PARAMS, `brain_recurrence: unknown content hash: ${contentHash}`);
    }
    return { ...entry };
  }
  if (operation === "learn" || operation === "forget") {
    const contentHash = requiredStringArg("brain_recurrence", args, "content_hash");
    const scope = requiredStringArg("brain_recurrence", args, "scope");
    const sourceId = requiredStringArg("brain_recurrence", args, "source_id");
    const entry = applyRecurrenceEvidence(laneVault(ctx), {
      contentHash,
      scope,
      sourceId,
      action: operation,
    });
    return { operation, entry };
  }
  if (operation === "purge_source") {
    const sourceId = requiredStringArg("brain_recurrence", args, "source_id");
    purgeRecurrenceSource(laneVault(ctx), sourceId);
    return { ok: true, source_id: sourceId };
  }
  throw unknownOperationError(
    "brain_recurrence: operation must be one of list|show|learn|forget|purge_source",
  );
}

async function toolBrainSkillRewriteStatus(
  ctx: ServerContext,
  args: Record<string, unknown>,
): Promise<Record<string, unknown>> {
  const skillName = requiredStringArg("brain_skill_rewrite_status", args, "skill_name");
  const status = readSkillRewriteStatus(laneVault(ctx), skillName);
  return {
    skill: status.skill,
    receipt: status.receipt,
    grades: status.grades,
    unreadable_grades: status.unreadable_grades,
    pending_rewrite_slug: status.pending_rewrite_slug,
  };
}

async function toolBrainProceduralGraph(
  ctx: ServerContext,
  args: Record<string, unknown>,
): Promise<Record<string, unknown>> {
  const operation = requiredStringArg("brain_procedural_graph", args, "operation");
  if (operation === "rebuild") {
    const graph = rebuildProceduralGraph(laneVault(ctx));
    const hints = rebuildProceduralHints(laneVault(ctx), { graph });
    return {
      operation,
      graph: {
        nodes: graph.nodes.length,
        edges: graph.edges.length,
        generated_at: graph.generated_at,
      },
      hints: {
        entries: hints.entries.length,
        generated_at: hints.generated_at,
      },
    };
  }
  if (operation === "show") {
    const graph = readProceduralGraph(laneVault(ctx));
    if (!graph) {
      throw new MCPError(INVALID_PARAMS, "brain_procedural_graph: graph projection not found");
    }
    return { ...graph };
  }
  if (operation === "hints") {
    const hints = readProceduralHints(laneVault(ctx));
    if (!hints) {
      throw new MCPError(INVALID_PARAMS, "brain_procedural_graph: hints projection not found");
    }
    return { ...hints };
  }
  throw unknownOperationError(
    "brain_procedural_graph: operation must be one of rebuild|show|hints",
  );
}

export const PROCEDURE_TOOLS: ReadonlyArray<ToolDefinition> = Object.freeze([
  {
    name: "brain_skill_proposals",
    kind: "write",
    description:
      "Skill proposals: learn, list, accept, reject; recover abandoned accepts; usage counts; evidence against the outcome ledger. page_candidates gates mature vault pages (tier, lifecycle, confidence, reuse; skips ones a skill covers), one envelope each; page_draft stages the returned draft.",
    inputSchema: {
      type: "object",
      properties: {
        operation: {
          type: "string",
          enum: [
            "learn",
            "list",
            "accept",
            "reject",
            "recover",
            "usage",
            "evidence",
            "page_candidates",
            "page_draft",
          ],
          description: "Tool operation.",
        },
        discard_unreadable: {
          type: "boolean",
          description:
            "recover only: delete accept-journal markers that cannot be parsed. Off by default: removing one unblocks accepting without resolving the sequence it marked.",
        },
        min_support: {
          type: "integer",
          minimum: 1,
          description: "Optional minimum evidence support for learn.",
        },
        slug: {
          type: "string",
          description:
            "Proposal slug for accept/reject/evidence. scored_rewrite accepts are refused here: " +
            "the operator accepts them on the command line.",
        },
        note: {
          type: "string",
          description: "Optional review note; required for reject.",
        },
        prerequisites: {
          type: "array",
          items: { type: "string" },
          description: "accept only: conditions that must hold before the procedure runs.",
        },
        rollback: {
          type: "array",
          items: { type: "string" },
          description: "accept only: steps that undo the procedure.",
        },
        side_effects: {
          type: "array",
          items: { type: "string" },
          description: "accept only: state the procedure changes outside its own output.",
        },
        verification: {
          type: "array",
          items: { type: "string" },
          description: "accept only: checks that confirm the procedure worked.",
        },
        page: {
          type: "string",
          description: "page_draft only: vault-relative path of the page the draft came from.",
        },
        draft: {
          type: "object",
          description: "page_draft only: the SKILL.md draft written for that page.",
          properties: {
            name: {
              type: "string",
              description: "Skill directory name: lowercase letters, digits, single hyphens.",
            },
            description: {
              type: "string",
              description: "One line naming when an agent should reach for this skill.",
            },
            triggers: {
              type: "array",
              items: { type: "string" },
              description: "Keywords a matcher scores the skill on; each must be non-empty.",
            },
            body: {
              type: "string",
              description: "The SKILL.md body: imperative and self-contained.",
            },
          },
          required: ["name", "description", "triggers", "body"],
          additionalProperties: false,
        },
      },
      required: ["operation"],
      additionalProperties: false,
    },
    handler: toolBrainSkillProposals,
  },
  {
    name: "brain_skill_rewrite_status",
    kind: "read",
    description:
      "Read-only rewrite-lane status: the frozen benchmark receipt and whether the task set still verifies, completed gate runs' verdicts and rates, and any staged rewrite awaiting a human accept. MCP never accepts or scores.",
    inputSchema: {
      type: "object",
      properties: {
        skill_name: {
          type: "string",
          description: "Skill directory name: lowercase letters, digits, single hyphens.",
        },
      },
      required: ["skill_name"],
      additionalProperties: false,
    },
    handler: toolBrainSkillRewriteStatus,
  },
  {
    name: "brain_procedural_memory",
    kind: "write",
    description:
      "Reconcile/list procedural memory and update the usage + outcome sidecar (reconcile, list, mark_used, mark_outcome). list accepts ranked:true to order by validated success rate.",
    inputSchema: {
      type: "object",
      properties: {
        operation: {
          type: "string",
          enum: ["reconcile", "list", "mark_used", "mark_outcome"],
          description: "Tool operation.",
        },
        roots: {
          type: "array",
          items: { type: "string" },
          description: "Optional root directories for reconcile.",
        },
        id: {
          type: "string",
          description: "Procedural entry id for mark_used / mark_outcome.",
        },
        outcome: {
          type: "string",
          enum: ["success", "failure"],
          description: "Host-reported result for mark_outcome.",
        },
        ranked: {
          type: "boolean",
          description: "list only: order entries by validated success rate.",
        },
      },
      required: ["operation"],
      additionalProperties: false,
    },
    handler: toolBrainProceduralMemory,
  },
  {
    name: "brain_recurrence",
    kind: "write",
    description:
      "Inspect and update recurrence/support diagnostics (list, show, learn, forget, purge_source).",
    inputSchema: {
      type: "object",
      properties: {
        operation: {
          type: "string",
          enum: ["list", "show", "learn", "forget", "purge_source"],
          description: "Tool operation.",
        },
        content_hash: {
          type: "string",
          description: "Content hash for show/learn/forget.",
        },
        scope: {
          type: "string",
          description: "Scope for learn/forget.",
        },
        source_id: {
          type: "string",
          description: "Source id for learn/forget/purge_source.",
        },
      },
      required: ["operation"],
      additionalProperties: false,
    },
    handler: toolBrainRecurrence,
  },
  {
    name: "brain_procedural_graph",
    kind: "write",
    description:
      "Rebuild/show procedural graph projection and prospective hint projection (rebuild, show, hints).",
    inputSchema: {
      type: "object",
      properties: {
        operation: {
          type: "string",
          enum: ["rebuild", "show", "hints"],
          description: "Tool operation.",
        },
      },
      required: ["operation"],
      additionalProperties: false,
    },
    handler: toolBrainProceduralGraph,
  },
]);