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
20.4 KB
Raw Blame
/**
 * Session Knowledge Synthesis tools (t_325a7e4a, t_635a3ea5, t_6a201155).
 *
 * Registered through the brain-tools.ts aggregator. Every tool here is
 * agent-driven or read-only: the kernel validates and stores already-
 * extracted structure or reads existing edges, and never calls an LLM.
 */

import {
  appendSessionSummary,
  getSessionSummaryReport,
  listSessionSummaries,
  SessionSummaryError,
  type SessionSummaryDigest,
  type SessionSummaryRecordRef,
} from "../../core/brain/session-summary.ts";
import {
  saveSessionCheckpoint,
  SessionCheckpointError,
  type CheckpointSignalInput,
  type SessionCheckpointResult,
} from "../../core/brain/session-checkpoint.ts";
import { IdempotencyPayloadMismatchError } from "../../core/brain/idempotency-ledger.ts";
import { resolveAgentName } from "../../core/config.ts";
import { normalizeAgentArgument } from "../../core/agent-identity.ts";
import type { BrainSignalSign } from "../../core/brain/types.ts";
import {
  traceIdeaLineage,
  IdeaLineageError,
  type IdeaLineageResult,
} from "../../core/brain/idea-lineage.ts";
import { decomposeNoteHistory } from "../../core/brain/note-history.ts";
import { coerceStringOptional, unknownOperationError } from "../coerce.ts";
import { INVALID_PARAMS, MCPError } from "../protocol.ts";
import { TRANSPORT_REACH } from "../../core/graph/transport-reach.ts";
import { contextReach, type ServerContext, type ToolDefinition } from "../tool-contract.ts";
import { MCP_PREVIEW_BUDGET } from "../preview-budget.ts";
import { readableAtContextReach } from "./reach-readable.ts";

const SUMMARY_TOOL = "brain_session_summary";

function requiredSessionId(args: Record<string, unknown>): string {
  const value = args["session_id"];
  if (typeof value !== "string" || value.trim().length === 0) {
    throw new MCPError(INVALID_PARAMS, `${SUMMARY_TOOL}: session_id is required`);
  }
  return value.trim();
}

function stringArrayArg(
  args: Record<string, unknown>,
  name: string,
): ReadonlyArray<string> | undefined {
  const value = args[name];
  if (value === undefined || value === null) return undefined;
  if (!Array.isArray(value) || value.some((item) => typeof item !== "string")) {
    throw new MCPError(INVALID_PARAMS, `${SUMMARY_TOOL}: ${name} must be an array of strings`);
  }
  return value as ReadonlyArray<string>;
}

/**
 * Argument name for the project scope axis. Deliberately identical to the
 * `brain_search` filter (`src/mcp/search-tools.ts`) so an agent that knows
 * one knows the other; the core field it maps to is the `project` axis of
 * `CompositeScope`. Not to be confused with `o2b brain project`, the
 * unrelated configuration-level code-directory link.
 */
const PROJECT_SCOPE_ARG = "project_scope";

/** Longest accepted raw project token, matching the `brain_search` filter. */
const PROJECT_SCOPE_MAX_LEN = 128;

function serializeDigest(digest: SessionSummaryDigest): Record<string, unknown> {
  return {
    id: digest.id,
    // Presence-gated with the digest shape (t_22d58fa7): a record naming
    // no session carries no session_id key, never a fabricated "".
    ...(digest.sessionId !== undefined ? { session_id: digest.sessionId } : {}),
    request: digest.request,
    decisions: digest.decisions,
    learnings: digest.learnings,
    next_steps: digest.nextSteps,
    created_at: digest.createdAt,
    ...(digest.host !== undefined ? { host: digest.host } : {}),
    ...(digest.project !== undefined ? { project: digest.project } : {}),
  };
}

/** Wire shape of one divergence record: identity and hash, never a payload echo. */
function serializeDivergenceRecord(record: SessionSummaryRecordRef): Record<string, unknown> {
  return { id: record.id, created_at: record.createdAt, content_hash: record.contentHash };
}

async function toolBrainSessionSummary(
  ctx: ServerContext,
  args: Record<string, unknown>,
): Promise<Record<string, unknown>> {
  const operation = args["operation"];
  if (operation !== "write" && operation !== "get" && operation !== "list") {
    throw unknownOperationError(`${SUMMARY_TOOL}: operation must be write|get|list`);
  }

  if (operation === "write") {
    const sessionId = requiredSessionId(args);
    const request = args["request"];
    const decisions = stringArrayArg(args, "decisions");
    const learnings = stringArrayArg(args, "learnings");
    const nextSteps = stringArrayArg(args, "next_steps");
    const host = args["host"];
    const sourceTurnIds = stringArrayArg(args, "source_turn_ids");
    const project = coerceStringOptional(args, PROJECT_SCOPE_ARG, PROJECT_SCOPE_MAX_LEN);
    try {
      const digest = appendSessionSummary(ctx.vault, {
        sessionId,
        ...(typeof request === "string" ? { request } : {}),
        ...(decisions !== undefined ? { decisions } : {}),
        ...(learnings !== undefined ? { learnings } : {}),
        ...(nextSteps !== undefined ? { nextSteps } : {}),
        ...(typeof host === "string" ? { host } : {}),
        ...(sourceTurnIds !== undefined ? { sourceTurnIds } : {}),
        ...(project !== undefined ? { project } : {}),
      });
      return { written: true, digest: serializeDigest(digest) };
    } catch (error) {
      if (error instanceof SessionSummaryError) {
        throw new MCPError(INVALID_PARAMS, error.message);
      }
      throw error;
    }
  }

  if (operation === "get") {
    const sessionId = requiredSessionId(args);
    const report = getSessionSummaryReport(ctx.vault, sessionId);
    if (report === null) return { found: false };
    // Additive divergence fields (t_59d4c919): the count always; the
    // divergent flag and the bounded id/hash sample only when the session
    // holds more than one content-differing digest. `{ found: false }` is
    // untouched.
    return {
      found: true,
      digest: serializeDigest(report.digest),
      digest_count: report.digestCount,
      ...(report.divergent === true
        ? {
            divergent: true,
            records: (report.records ?? []).map(serializeDivergenceRecord),
          }
        : {}),
    };
  }

  // operation === "list"
  const sessionIdRaw = args["session_id"];
  const sessionId =
    typeof sessionIdRaw === "string" && sessionIdRaw.trim().length > 0
      ? sessionIdRaw.trim()
      : undefined;
  const project = coerceStringOptional(args, PROJECT_SCOPE_ARG, PROJECT_SCOPE_MAX_LEN);
  try {
    const digests = listSessionSummaries(ctx.vault, {
      ...(sessionId !== undefined ? { sessionId } : {}),
      ...(project !== undefined ? { project } : {}),
    });
    return { count: digests.length, digests: digests.map(serializeDigest) };
  } catch (error) {
    if (error instanceof SessionSummaryError) {
      throw new MCPError(INVALID_PARAMS, error.message);
    }
    throw error;
  }
}

const CHECKPOINT_TOOL = "brain_session_checkpoint";

/** Parse the `signals` array into checkpoint signal inputs. Only STRUCTURAL
 * problems (not-an-array, an item that is not an object, a mistyped
 * scalar) are protocol errors here. SEMANTIC validity — a bad sign, a
 * missing topic / principle — is deliberately passed through so the kernel
 * attempts the write and collects the failure as a `partial` item (status
 * "mixed"), rather than aborting the whole batch. */
function parseCheckpointSignals(
  args: Record<string, unknown>,
): ReadonlyArray<CheckpointSignalInput> {
  const value = args["signals"];
  if (value === undefined || value === null) return [];
  if (!Array.isArray(value)) {
    throw new MCPError(INVALID_PARAMS, `${CHECKPOINT_TOOL}: signals must be an array`);
  }
  return value.map((raw, index) => {
    if (typeof raw !== "object" || raw === null) {
      throw new MCPError(INVALID_PARAMS, `${CHECKPOINT_TOOL}: signals[${index}] must be an object`);
    }
    const item = raw as Record<string, unknown>;
    const topic = typeof item["topic"] === "string" ? item["topic"] : "";
    const principle = typeof item["principle"] === "string" ? item["principle"] : "";
    // Sign passed through verbatim; the writer rejects an out-of-enum value
    // and the kernel surfaces it as a `partial` item.
    const sign = item["signal"] as BrainSignalSign;
    const scope = typeof item["scope"] === "string" ? item["scope"] : undefined;
    const rawText = typeof item["raw"] === "string" ? item["raw"] : undefined;
    const source = stringArrayField(item["source"], `signals[${index}].source`);
    return {
      topic,
      signal: sign,
      principle,
      ...(scope !== undefined ? { scope } : {}),
      ...(rawText !== undefined ? { raw: rawText } : {}),
      ...(source !== undefined ? { source } : {}),
    } satisfies CheckpointSignalInput;
  });
}

function stringArrayField(value: unknown, name: string): ReadonlyArray<string> | undefined {
  if (value === undefined || value === null) return undefined;
  if (!Array.isArray(value) || value.some((v) => typeof v !== "string")) {
    throw new MCPError(INVALID_PARAMS, `${CHECKPOINT_TOOL}: ${name} must be an array of strings`);
  }
  return value as ReadonlyArray<string>;
}

function serializeCheckpoint(result: SessionCheckpointResult): Record<string, unknown> {
  return {
    status: result.status,
    session_id: result.sessionId,
    deduped: result.deduped,
    signals: result.signals.map((s) => ({ id: s.id, path: s.path, deduped: s.deduped })),
    summary: result.summary === null ? null : { id: result.summary.id },
    diary_written: result.diaryWritten,
    partial: result.partial.map((p) => ({
      kind: p.kind,
      ...(p.index !== undefined ? { index: p.index } : {}),
      ...(p.topic !== undefined ? { topic: p.topic } : {}),
      reason: p.reason,
    })),
  };
}

async function toolBrainSessionCheckpoint(
  ctx: ServerContext,
  args: Record<string, unknown>,
): Promise<Record<string, unknown>> {
  const sessionIdRaw = args["session_id"];
  if (typeof sessionIdRaw !== "string" || sessionIdRaw.trim().length === 0) {
    throw new MCPError(INVALID_PARAMS, `${CHECKPOINT_TOOL}: session_id is required`);
  }
  const agentArg = typeof args["agent"] === "string" ? args["agent"] : null;
  const agent = normalizeAgentArgument(agentArg) ?? resolveAgentName(ctx.configPath ?? undefined);
  const signals = parseCheckpointSignals(args);
  const request = typeof args["request"] === "string" ? args["request"] : undefined;
  const decisions = stringArrayField(args["decisions"], "decisions");
  const learnings = stringArrayField(args["learnings"], "learnings");
  const nextSteps = stringArrayField(args["next_steps"], "next_steps");
  const sourceTurnIds = stringArrayField(args["source_turn_ids"], "source_turn_ids");
  const host = typeof args["host"] === "string" ? args["host"] : undefined;
  const diary = typeof args["diary"] === "string" ? args["diary"] : undefined;

  try {
    const result = saveSessionCheckpoint(ctx.vault, {
      sessionId: sessionIdRaw.trim(),
      agent,
      signals,
      ...(request !== undefined ? { request } : {}),
      ...(decisions !== undefined ? { decisions } : {}),
      ...(learnings !== undefined ? { learnings } : {}),
      ...(nextSteps !== undefined ? { nextSteps } : {}),
      ...(sourceTurnIds !== undefined ? { sourceTurnIds } : {}),
      ...(host !== undefined ? { host } : {}),
      ...(diary !== undefined ? { diary } : {}),
    });
    return serializeCheckpoint(result);
  } catch (error) {
    if (
      error instanceof SessionCheckpointError ||
      error instanceof IdempotencyPayloadMismatchError
    ) {
      throw new MCPError(INVALID_PARAMS, error.message);
    }
    throw error;
  }
}

const LINEAGE_TOOL = "brain_idea_lineage";

function serializeLineage(result: IdeaLineageResult): Record<string, unknown> {
  return {
    root: result.root,
    nodes: result.nodes,
    edges: result.edges,
    truncated: result.truncated,
  };
}

function toolBrainIdeaLineage(
  ctx: ServerContext,
  args: Record<string, unknown>,
): Record<string, unknown> {
  const idRaw = args["id"];
  if (typeof idRaw !== "string" || idRaw.trim().length === 0) {
    throw new MCPError(INVALID_PARAMS, `${LINEAGE_TOOL}: id is required`);
  }
  const maxDepthRaw = args["max_depth"];
  let maxDepth: number | undefined;
  if (maxDepthRaw !== undefined && maxDepthRaw !== null) {
    if (typeof maxDepthRaw !== "number" || !Number.isInteger(maxDepthRaw) || maxDepthRaw < 1) {
      throw new MCPError(INVALID_PARAMS, `${LINEAGE_TOOL}: max_depth must be a positive integer`);
    }
    maxDepth = maxDepthRaw;
  }
  try {
    return serializeLineage(
      traceIdeaLineage(
        ctx.vault,
        { id: idRaw.trim() },
        {
          ...(maxDepth !== undefined ? { maxDepth } : {}),
          // A private continuity row is withheld from a remote caller as
          // if it did not exist, as in the session recall tools.
          ...(contextReach(ctx) === TRANSPORT_REACH.local ? {} : { withholdPrivate: true }),
        },
      ),
    );
  } catch (error) {
    if (error instanceof IdeaLineageError) {
      throw new MCPError(INVALID_PARAMS, error.message);
    }
    throw error;
  }
}

const HISTORY_TOOL = "brain_note_history";

function toolBrainNoteHistory(
  ctx: ServerContext,
  args: Record<string, unknown>,
): Record<string, unknown> {
  const pathRaw = args["path"];
  if (typeof pathRaw !== "string" || pathRaw.trim().length === 0) {
    throw new MCPError(INVALID_PARAMS, `${HISTORY_TOOL}: path is required`);
  }
  const gapHours = positiveIntArg(args, "gap_hours");
  const maxCount = positiveIntArg(args, "max_count");
  const result = decomposeNoteHistory(ctx.vault, pathRaw.trim(), {
    ...(gapHours !== undefined ? { gapHours } : {}),
    ...(maxCount !== undefined ? { maxCount } : {}),
    // A page the caller may not read at its reach answers as a path no
    // commit touches.
    include: readableAtContextReach(ctx),
  });
  return {
    note_path: result.notePath,
    available: result.available,
    ...(result.reason !== undefined ? { reason: result.reason } : {}),
    commit_count: result.commitCount,
    phases: result.phases,
  };
}

function positiveIntArg(args: Record<string, unknown>, name: string): number | undefined {
  const value = args[name];
  if (value === undefined || value === null) return undefined;
  if (typeof value !== "number" || !Number.isInteger(value) || value < 1) {
    throw new MCPError(INVALID_PARAMS, `${HISTORY_TOOL}: ${name} must be a positive integer`);
  }
  return value;
}

export const SYNTHESIS_TOOLS: ReadonlyArray<ToolDefinition> = Object.freeze([
  {
    name: SUMMARY_TOOL,
    kind: "write",
    description:
      "Session-scoped structured digest over request/decisions/learnings/next_steps. write stores agent-extracted categories; get returns a session's latest digest; list returns all (optionally one session). Append-only, deduped; an all-empty digest is rejected.",
    inputSchema: {
      type: "object",
      properties: {
        operation: {
          type: "string",
          enum: ["write", "get", "list"],
          description: "Tool operation.",
        },
        session_id: {
          type: "string",
          description: "Session id (required for write/get; optional scope for list).",
        },
        request: {
          type: "string",
          description: "write: one-line statement of the session's goal.",
        },
        decisions: {
          type: "array",
          items: { type: "string" },
          description: "write: decisions made this session.",
        },
        learnings: {
          type: "array",
          items: { type: "string" },
          description: "write: things learned this session.",
        },
        next_steps: {
          type: "array",
          items: { type: "string" },
          description: "write: follow-up actions.",
        },
        source_turn_ids: {
          type: "array",
          items: { type: "string" },
          description: "write: turn ids the digest was distilled from (lineage edges).",
        },
        host: { type: "string", description: "write: originating runtime (claude, codex, ...)." },
        [PROJECT_SCOPE_ARG]: {
          type: "string",
          description:
            "Project scope axis; same name and slug rule as the brain_search filter. write: scopes the digest and its dedupe key; list: filters by it. Unsluggable = error.",
        },
      },
      required: ["operation"],
      additionalProperties: false,
    },
    handler: toolBrainSessionSummary,
    previewBudget: MCP_PREVIEW_BUDGET,
  },
  {
    name: CHECKPOINT_TOOL,
    kind: "write",
    description:
      "Batch-save a whole session's signals + a decisions/learnings/next_steps summary + optional diary in one idempotent round-trip, keyed by session_id. A same-content retry dedupes; a different-content retry is payload_mismatch. Items needing review return in `partial` (status 'mixed'), never dropped.",
    inputSchema: {
      type: "object",
      properties: {
        session_id: { type: "string", description: "Session id; the idempotency key." },
        agent: { type: "string", description: "Identity stamped on written signals (optional)." },
        signals: {
          type: "array",
          description: "Extracted memories to persist as signals.",
          items: {
            type: "object",
            properties: {
              topic: { type: "string", description: "Stable kebab-slug topic." },
              signal: {
                type: "string",
                enum: ["positive", "negative"],
                description: "positive = rule to follow; negative = to avoid.",
              },
              principle: { type: "string", description: "One-line rule formulation." },
              scope: { type: "string", description: "Soft category (optional)." },
              raw: { type: "string", description: "Verbatim source quote (optional)." },
              source: {
                type: "array",
                items: { type: "string" },
                description: "Wikilinks to triggering artifacts (optional).",
              },
            },
            required: ["topic", "signal", "principle"],
            additionalProperties: false,
          },
        },
        request: { type: "string", description: "One-line session goal." },
        decisions: { type: "array", items: { type: "string" }, description: "Decisions made." },
        learnings: { type: "array", items: { type: "string" }, description: "Things learned." },
        next_steps: { type: "array", items: { type: "string" }, description: "Follow-up actions." },
        source_turn_ids: {
          type: "array",
          items: { type: "string" },
          description: "Turn ids the summary was distilled from.",
        },
        host: { type: "string", description: "Originating runtime (claude, codex, ...)." },
        diary: { type: "string", description: "Optional narrative diary line for the Brain log." },
      },
      required: ["session_id"],
      additionalProperties: false,
    },
    handler: toolBrainSessionCheckpoint,
    previewBudget: MCP_PREVIEW_BUDGET,
  },
  {
    name: LINEAGE_TOOL,
    kind: "read",
    description:
      "Read-only provenance tracer: how a derived artifact was reached, as an observation -> synthesis -> conclusion graph. A ctn_ id walks the sourceRefs graph; a pref-/ret- id adapts belief-evolution. Cycle-guarded, depth-bounded; an unknown id errors.",
    inputSchema: {
      type: "object",
      properties: {
        id: {
          type: "string",
          description: "Continuity record id (ctn_...) or preference id (pref-.../ret-...).",
        },
        max_depth: {
          type: "integer",
          minimum: 1,
          description: "Maximum backward hops from the artifact (default 8).",
        },
      },
      required: ["id"],
      additionalProperties: false,
    },
    handler: toolBrainIdeaLineage,
    previewBudget: MCP_PREVIEW_BUDGET,
  },
  {
    name: HISTORY_TOOL,
    kind: "read",
    description:
      "Decompose a note's git history into episodic phases, split when the gap between commits exceeds gap_hours (default 72) - deterministic and language-agnostic. Each phase carries subjects, dates, authors. Missing repo: available=false; no commits: zero phases. Read-only.",
    inputSchema: {
      type: "object",
      properties: {
        path: { type: "string", description: "Repo-relative note path (git pathspec)." },
        gap_hours: {
          type: "integer",
          minimum: 1,
          description: "Inter-commit gap that starts a new phase (default 72).",
        },
        max_count: {
          type: "integer",
          minimum: 1,
          description: "Bound the walk to the newest N commits touching the path.",
        },
      },
      required: ["path"],
      additionalProperties: false,
    },
    handler: toolBrainNoteHistory,
    previewBudget: MCP_PREVIEW_BUDGET,
  },
]);