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
12.3 KB
Raw Blame
/**
 * The session tools of the recall family (task 3.19):
 * `brain_session_grep`, its coverage view, `brain_session_describe` and
 * `brain_session_expand`, each answering at the caller's reach. Split
 * from `recall-tools.ts`; registration happens through that module's
 * registry, which preserves the public RECALL_TOOLS surface.
 */

import {
  coverageSessionRecall,
  DEFAULT_LIMIT as SESSION_RECALL_DEFAULT_LIMIT,
  decorateSessionRecallHits,
  describeSessionRecall,
  expandSessionRecall,
  searchSessionRecall,
  SessionCoverageEntityUnknownError,
  SessionCoverageInfeasibleError,
} from "../../core/brain/session-recall.ts";
import { MINED_KEY_MAX_LENGTH } from "../../core/brain/link-graph/session-mining.ts";
import { resolveTimeBounds } from "./time-bounds.ts";
import { isPayloadRemotelyReadable } from "../../core/brain/payload-inventory.ts";
import { pageSlice } from "../../core/brain/offset-cursor.ts";
import {
  DEFAULT_PAYLOAD_PAGE_CHARS,
  PayloadNotFoundError,
  PayloadRefError,
  PayloadRegistry,
  payloadIdFromRef,
} from "../../core/brain/payload-registry.ts";
import { TRANSPORT_REACH } from "../../core/graph/transport-reach.ts";
import { INVALID_PARAMS, MCPError } from "../protocol.ts";
import { contextReach } from "../tool-contract.ts";
import type { ServerContext } from "../tool-contract.ts";
import { coercePositiveInteger, optionalStringArg, requiredStringArg } from "./shared.ts";
import { cursorOffsetArg } from "./pagination.ts";
import { unknownOperationError } from "../coerce.ts";

// ----- brain_context_presets ----------------------------------------------

export async function toolBrainSessionGrep(
  ctx: ServerContext,
  args: Record<string, unknown>,
): Promise<Record<string, unknown>> {
  // Coverage-first selection (t_2c2a883c) rides this tool as an explicit
  // operation; omitted (the default) is the historical grep, byte-identical.
  const operation = args["operation"] ?? "match";
  if (operation === "coverage") return toolBrainSessionGrepCoverage(ctx, args);
  if (operation !== "match") {
    // The dispatch contract (surface-error-codes census): every tool whose
    // schema declares a dispatch enum answers an unknown value with the
    // shared `unknown_operation` code, message unchanged.
    throw unknownOperationError("brain_session_grep: operation must be 'match' or 'coverage'");
  }
  if (args["char_budget"] !== undefined) {
    throw new MCPError(
      INVALID_PARAMS,
      "brain_session_grep: char_budget is not applicable to operation 'match'; it sizes the coverage selection",
    );
  }
  if (args["entity_key"] !== undefined) {
    throw new MCPError(
      INVALID_PARAMS,
      "brain_session_grep: entity_key is not applicable to operation 'match'; it seeds the coverage fan-out",
    );
  }
  const limit = coercePositiveInteger("brain_session_grep", "limit", args["limit"]);
  const snippetChars = coercePositiveInteger(
    "brain_session_grep",
    "snippet_chars",
    args["snippet_chars"],
  );
  // Conversation-chronology bounds (S1): `since` / `before` parse through
  // the shared time-range grammar (ISO date/datetime, today/yesterday,
  // <n>h/<n>d/<n>w) via the shared time-bounds wrapper. `before` maps
  // onto the range's inclusive upper edge.
  const since = optionalStringArg("brain_session_grep", args, "since");
  const before = optionalStringArg("brain_session_grep", args, "before");
  const bounds = resolveTimeBounds(since, before);
  // Inline-raw disclosure (C2): opt-in flag inlines the raw captures beside
  // each derived record and stamps an extracted discriminator. Omitted, the
  // response stays byte-identical.
  const includeRaw = args["include_raw"] === true;
  const rawBudgetChars = coercePositiveInteger(
    "brain_session_grep",
    "raw_budget_chars",
    args["raw_budget_chars"],
  );
  // The matches are a deterministic ranked walk (score, then id), so the
  // page is cut here over the full hit set: `total` counts every match
  // across pages and `next_cursor` continues the walk (null when
  // exhausted). Absent `limit`, the page is the historical bounded
  // default (DEFAULT_LIMIT in session-recall.ts) - an unpaginated call
  // used to answer 10 hits, not every hit in the vault.
  //
  // The search below NEVER runs with includeRaw: decoration reads the
  // record set once per hit decorated, so decorating the full match set
  // on every page made a cursor walk O(N^2). The page is cut first and
  // only its items are decorated.
  const offset = cursorOffsetArg("brain_session_grep", args);
  const sessionIdArg = optionalStringArg("brain_session_grep", args, "session_id");
  const hits = searchSessionRecall(ctx.vault, {
    query: requiredStringArg("brain_session_grep", args, "query"),
    ...withheldAtRemoteReach(ctx),
    ...(sessionIdArg !== undefined ? { sessionId: sessionIdArg } : {}),
    limit: Number.MAX_SAFE_INTEGER,
    ...(snippetChars !== undefined ? { snippetChars } : {}),
    ...(bounds.sinceMs !== null ? { sinceMs: bounds.sinceMs } : {}),
    ...(bounds.untilMs !== null ? { untilMs: bounds.untilMs } : {}),
    ...(rawBudgetChars !== undefined ? { rawBudgetChars } : {}),
  });
  const page = pageSlice(hits.hits, offset, limit ?? SESSION_RECALL_DEFAULT_LIMIT);
  if (!includeRaw) {
    return { hits: page.items, total: page.total, next_cursor: page.next_cursor };
  }
  return {
    hits: decorateSessionRecallHits(ctx.vault, page.items, {
      ...withheldAtRemoteReach(ctx),
      ...(sessionIdArg !== undefined ? { sessionId: sessionIdArg } : {}),
      ...(rawBudgetChars !== undefined ? { rawBudgetChars } : {}),
    }),
    total: page.total,
    next_cursor: page.next_cursor,
  };
}

/**
 * The coverage operation of `brain_session_grep` (t_2c2a883c): the
 * coverage-first thread selection over the lineage-scoped record set,
 * fanning out under the adaptive topic budget and the caller's
 * `char_budget`, returning the selected turns chronologically beside the
 * selection diagnostics. The typed floor-violation infeasibility maps to
 * INVALID_PARAMS - a budget that cannot hold the floor-weighted
 * selection is a caller error, named so it can be retried, never a
 * silent truncation.
 */
export function toolBrainSessionGrepCoverage(
  ctx: ServerContext,
  args: Record<string, unknown>,
): Record<string, unknown> {
  if (args["query"] !== undefined) {
    throw new MCPError(
      INVALID_PARAMS,
      "brain_session_grep: operation 'coverage' selects whole topics; it takes no `query`",
    );
  }
  for (const inapplicable of [
    "since",
    "before",
    "limit",
    "snippet_chars",
    "include_raw",
    "raw_budget_chars",
    "cursor",
  ] as const) {
    if (args[inapplicable] !== undefined) {
      throw new MCPError(
        INVALID_PARAMS,
        `brain_session_grep: ${inapplicable} is not applicable to operation 'coverage'; it pages, sizes or filters the match operation`,
      );
    }
  }
  const charBudget = coercePositiveInteger(
    "brain_session_grep",
    "char_budget",
    args["char_budget"],
  );
  if (charBudget === undefined) {
    throw new MCPError(
      INVALID_PARAMS,
      "brain_session_grep: char_budget is required for the coverage operation",
    );
  }
  const sessionId = optionalStringArg("brain_session_grep", args, "session_id");
  // The miner's own cap: mined keys run to MINED_KEY_MAX_LENGTH, so a
  // 129-200 character URL or path key must be able to seed coverage here.
  const entityKey = optionalStringArg(
    "brain_session_grep",
    args,
    "entity_key",
    MINED_KEY_MAX_LENGTH,
  );
  let result;
  try {
    result = coverageSessionRecall(ctx.vault, {
      ...withheldAtRemoteReach(ctx),
      ...(sessionId !== undefined ? { sessionId } : {}),
      ...(entityKey !== undefined ? { entityKey } : {}),
      charBudget,
    });
  } catch (err) {
    if (err instanceof SessionCoverageInfeasibleError) {
      throw new MCPError(INVALID_PARAMS, err.message);
    }
    if (err instanceof SessionCoverageEntityUnknownError) {
      throw new MCPError(INVALID_PARAMS, err.message);
    }
    throw err;
  }
  return { ...result };
}

/**
 * Private continuity rows are session data a remote caller does not get:
 * the recall tools answer about them exactly as about a row that does not
 * exist. A local caller keeps every row.
 */
export function withheldAtRemoteReach(ctx: ServerContext): { withholdPrivate?: true } {
  return contextReach(ctx) === TRANSPORT_REACH.local ? {} : { withholdPrivate: true };
}

export async function toolBrainSessionDescribe(
  ctx: ServerContext,
  args: Record<string, unknown>,
): Promise<Record<string, unknown>> {
  return {
    ...describeSessionRecall(ctx.vault, {
      sessionId: requiredStringArg("brain_session_describe", args, "session_id"),
      ...withheldAtRemoteReach(ctx),
      ...(args["topics"] === true ? { topics: true } : {}),
    }),
  };
}

export async function toolBrainSessionExpand(
  ctx: ServerContext,
  args: Record<string, unknown>,
): Promise<Record<string, unknown>> {
  const payloadRef = optionalStringArg("brain_session_expand", args, "payload");
  if (payloadRef !== undefined) return expandPayload(ctx, args, payloadRef);
  const rawLimit = coercePositiveInteger("brain_session_expand", "raw_limit", args["raw_limit"]);
  return {
    ...expandSessionRecall(ctx.vault, {
      id: requiredStringArg("brain_session_expand", args, "id"),
      ...withheldAtRemoteReach(ctx),
      ...(rawLimit !== undefined ? { rawLimit } : {}),
      ...(optionalStringArg("brain_session_expand", args, "cursor") !== undefined
        ? { cursor: optionalStringArg("brain_session_expand", args, "cursor") }
        : {}),
    }),
  };
}

/**
 * Page one externalized payload (t_35440e83) - the `payload` mode of
 * `brain_session_expand`.
 *
 * Payloads only ever come out of session import, so expanding a
 * placeholder found in a recalled turn is the same act as expanding the
 * turn: one more level of "give me the exact source". Riding this tool
 * rather than adding one keeps the tool budget and every profile that
 * already carries the session tools unchanged.
 *
 * Reach: a local caller reads any stored payload. A REMOTE caller reads
 * one only when a non-private session turn references it, directly or
 * through another remotely readable payload (`payload-inventory.ts`).
 * Pages grant nothing: a page can be written by tools a session turn
 * cannot. A payload referenced only from a private row or a page, and an
 * orphan nobody references, answer the same refusal, so a remote caller
 * cannot use the difference to probe what exists.
 */
export function expandPayload(
  ctx: ServerContext,
  args: Record<string, unknown>,
  ref: string,
): Record<string, unknown> {
  if (args["id"] !== undefined || args["raw_limit"] !== undefined) {
    throw new MCPError(
      INVALID_PARAMS,
      "brain_session_expand: `payload` pages one payload ref; it cannot be combined with `id` or `raw_limit`",
    );
  }
  let sha256: string;
  try {
    sha256 = payloadIdFromRef(ref);
  } catch (err) {
    if (err instanceof PayloadRefError) throw new MCPError(INVALID_PARAMS, err.message);
    throw err;
  }
  if (
    contextReach(ctx) !== TRANSPORT_REACH.local &&
    !isPayloadRemotelyReadable(ctx.vault, sha256)
  ) {
    throw new MCPError(
      INVALID_PARAMS,
      `brain_session_expand: payload ${ref} is not readable at remote reach - no non-private ` +
        "session turn references it",
    );
  }
  const cursor = optionalStringArg("brain_session_expand", args, "cursor");
  const offset = cursor === undefined ? 0 : Number.parseInt(cursor, 10);
  if (cursor !== undefined && (!/^[0-9]+$/.test(cursor) || !Number.isFinite(offset))) {
    throw new MCPError(
      INVALID_PARAMS,
      "brain_session_expand: a payload cursor is the next_cursor of a previous page",
    );
  }
  const limit =
    coercePositiveInteger("brain_session_expand", "payload_chars", args["payload_chars"]) ??
    DEFAULT_PAYLOAD_PAGE_CHARS;
  try {
    const page = new PayloadRegistry({ vault: ctx.vault, maxInlineChars: 1 }).get(ref, {
      offset,
      limit,
    });
    return {
      payload: {
        ref: page.ref,
        offset: page.offset,
        limit: page.limit,
        total_chars: page.totalChars,
        content: page.content,
      },
      next_cursor: page.nextOffset === null ? null : String(page.nextOffset),
    };
  } catch (err) {
    if (err instanceof PayloadNotFoundError) throw new MCPError(INVALID_PARAMS, err.message);
    throw err;
  }
}

// ----- brain_pre_compress_pack (v0.20.0) -----------------------------------