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.5 KB
Raw Blame
/**
 * Canonical entity registry lookups and vault profile switching.
 *
 * Extracted from the former brain-tools.ts monolith; registration
 * happens through the aggregator, which preserves the public
 * BRAIN_TOOLS surface.
 */

import {
  EntityAmbiguityError,
  getEntity,
  listEntities,
} from "../../core/brain/entities/registry.ts";
import { validateEntityCategory } from "../../core/brain/entities/canonical.ts";
import {
  BRAIN_ENTITY_STATUS_VALUES,
  isBrainEntityStatus,
} from "../../core/brain/entities/types.ts";
import { switchProfile, listProfiles } from "../../core/brain/portability/profiles.ts";
import { defaultConfigPath } from "../../core/config.ts";
import { INTERNAL_ERROR, INVALID_PARAMS, MCPError } from "../protocol.ts";
import type { ServerContext, ToolDefinition } from "../tool-contract.ts";
import { MCP_PREVIEW_BUDGET } from "../preview-budget.ts";
import { coerceStr } from "../coerce.ts";
import { laneVault } from "./lane-vault.ts";

/** Serialize one entity for the MCP payload (no absolute paths). */
function entityToPayload(
  entity: import("../../core/brain/entities/types.ts").BrainEntity,
): Record<string, unknown> {
  return {
    id: entity.id,
    category: entity.category,
    name: entity.name,
    aliases: [...entity.aliases],
    status: entity.status,
    ...(entity.source_agent !== undefined ? { source_agent: entity.source_agent } : {}),
    ...(entity.confidence !== undefined ? { confidence: entity.confidence } : {}),
    created_at: entity.created_at,
    updated_at: entity.updated_at,
    ...(entity.archived_at !== undefined ? { archived_at: entity.archived_at } : {}),
    relations: entity.relations.map((r) => ({ relation: r.relation, target: r.target })),
    body: entity.body,
  };
}

async function toolBrainEntity(
  ctx: ServerContext,
  args: Record<string, unknown>,
): Promise<Record<string, unknown>> {
  // Argument validation happens at the boundary so INVALID_PARAMS is
  // reserved for genuine client-input errors; unexpected registry
  // failures (malformed entity file, I/O) surface as INTERNAL_ERROR.
  const view = coerceStr(args, "view", true)!;
  // A record-lane tool works with no vault: its pages are store records then.
  const vault = laneVault(ctx);
  if (view !== "get" && view !== "list") {
    throw new MCPError(INVALID_PARAMS, `brain_entity: unknown view '${view}' (get | list)`);
  }
  const category = coerceStr(args, "category", false);
  if (category !== null) {
    try {
      validateEntityCategory(category);
    } catch (err) {
      throw new MCPError(INVALID_PARAMS, `brain_entity: ${(err as Error).message}`);
    }
  }
  const status = coerceStr(args, "status", false);
  // Validated against the vocabulary itself, so the enum below and this
  // check cannot drift and a new status is reachable the day it exists.
  if (status !== null && !isBrainEntityStatus(status)) {
    throw new MCPError(
      INVALID_PARAMS,
      `brain_entity: status must be one of: ${BRAIN_ENTITY_STATUS_VALUES.join(", ")}`,
    );
  }
  const query = view === "get" ? coerceStr(args, "query", true)! : null;

  try {
    if (view === "get") {
      const entity = getEntity(vault, {
        query: query!,
        ...(category !== null ? { category } : {}),
      });
      if (entity === null) return { found: false, query: query! };
      return { found: true, ...entityToPayload(entity) };
    }
    const entities = listEntities(vault, {
      ...(category !== null ? { category } : {}),
      ...(status !== null ? { status } : {}),
    });
    return { entities: entities.map(entityToPayload), total: entities.length };
  } catch (err) {
    if (err instanceof MCPError) throw err;
    if (err instanceof EntityAmbiguityError) {
      // A category-less query hitting several categories is a
      // client-resolvable input problem, not a server fault.
      throw new MCPError(INVALID_PARAMS, `brain_entity: ${err.message}`);
    }
    throw new MCPError(INTERNAL_ERROR, `brain_entity: ${(err as Error).message}`);
  }
}

async function toolBrainSwitchVault(
  ctx: ServerContext,
  args: Record<string, unknown>,
): Promise<Record<string, unknown>> {
  const name = coerceStr(args, "name", true)!;
  const configPath = ctx.configPath ?? defaultConfigPath();
  try {
    switchProfile(configPath, name);
  } catch (err) {
    throw new Error(`brain_switch_vault: ${(err as Error).message ?? String(err)}`, {
      cause: err,
    });
  }
  // The running server keeps its already-resolved vault; the switch
  // takes effect for the next server launch / CLI invocation.
  return {
    active: name,
    profiles: listProfiles(configPath).profiles,
    note: "active profile updated; takes effect on next server launch",
  };
}

// ----- brain_doctor --------------------------------------------------------

export const ENTITY_TOOLS: ReadonlyArray<ToolDefinition> = Object.freeze([
  {
    name: "brain_entity",
    kind: "read",
    previewBudget: MCP_PREVIEW_BUDGET,
    description:
      "Look up (view: get) or list (view: list) canonical entities from the entity registry. Aliases resolve to the canonical record. Read-only; writes go through the o2b CLI.",
    inputSchema: {
      type: "object",
      properties: {
        view: {
          type: "string",
          enum: ["get", "list"],
          description: "get: resolve one entity by name or alias. list: enumerate the registry.",
        },
        query: {
          type: "string",
          description: "Name or alias to resolve (required for view: get).",
        },
        category: {
          type: "string",
          description: "Optional category filter (slug, e.g. `people`).",
        },
        status: {
          type: "string",
          enum: [...BRAIN_ENTITY_STATUS_VALUES],
          description:
            "Optional status filter for view: list. Omits quarantined entities " +
            "(they entered under untrusted provenance) unless you pass `quarantine`.",
        },
      },
      required: ["view"],
      additionalProperties: false,
    },
    handler: toolBrainEntity,
  },
  {
    name: "brain_switch_vault",
    kind: "write",
    description:
      "Activate a named vault profile (from the profiles registry). Updates the active pointer; the change takes effect on the next server launch - the running server keeps its already-resolved vault.",
    inputSchema: {
      type: "object",
      properties: {
        name: { type: "string", description: "Profile name to activate." },
      },
      required: ["name"],
      additionalProperties: false,
    },
    handler: toolBrainSwitchVault,
  },
]);