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
9.8 KB
Raw Blame
/**
 * Session signal-mining tool (salience-lifecycle-enrichment, unit 2,
 * t_1dace26d).
 *
 * One tool, two phases, mirroring the CLI verb. Called without `items`
 * it is read-only and returns the mining plan plus the single
 * needs-llm-step envelope; called with `items` it validates the answer
 * and writes the accepted ones as speculative inbox signals. OSB runs no
 * model on either path.
 */

import { commitExtractedSignals, ExtractSignalsError } from "../../core/brain/extract-signals.ts";
import { loadDedupIndex } from "../../core/brain/dedup-hash.ts";
import { TRANSPORT_REACH } from "../../core/graph/transport-reach.ts";
import {
  planExtractSignalsPrefiltered,
  recordExtractPrefilterCommit,
  resolveExtractPrefilterConfig,
} from "../../core/brain/extract-signals-prefilter.ts";
import { ResponseCheckError } from "../../core/brain/response-checks.ts";
import { ResponseShapeError } from "../../core/brain/response-shape.ts";
import { resolveAgentName, resolveTokenImpactLedgerEnabled } from "../../core/config.ts";
import { coerceStr } from "../coerce.ts";
import { INVALID_PARAMS, MCPError } from "../protocol.ts";
import { MCP_PREVIEW_BUDGET } from "../preview-budget.ts";
import { contextReach, type ServerContext, type ToolDefinition } from "../tool-contract.ts";
import { wrapToolErrors } from "./shared.ts";
import { toolPath } from "./device-path.ts";

const TOOL = "brain_extract_signals";

/** The refusal classes this tool reports as caller errors, not server faults. */
const NAMED_REFUSALS = [ExtractSignalsError, ResponseShapeError, ResponseCheckError];

async function toolBrainExtractSignals(
  ctx: ServerContext,
  args: Record<string, unknown>,
): Promise<Record<string, unknown>> {
  const session = coerceStr(args, "session", true)!;
  const agentArg = coerceStr(args, "agent", false);
  const agent =
    agentArg && agentArg.trim().length > 0
      ? agentArg
      : resolveAgentName(ctx.configPath ?? undefined);

  return wrapToolErrors(TOOL, NAMED_REFUSALS, async () => {
    // Absent `items` is the plan phase. An empty array is NOT: it is an
    // answer claiming the session states nothing, and it goes through the
    // validators like any other so the caller gets one contract.
    const decisionModel = resolveExtractPrefilterConfig(ctx.vault, ctx.configPath ?? undefined);
    // Below local reach a store failure is named without its raised
    // message, which carries the absolute host path.
    const closeHostErrors = contextReach(ctx) !== TRANSPORT_REACH.local;
    if (args["items"] === undefined) {
      const plan = await planExtractSignalsPrefiltered(ctx.vault, session, {
        now: new Date(),
        decisionModel,
        tokenImpactEnabled:
          decisionModel !== null && resolveTokenImpactLedgerEnabled(ctx.configPath ?? undefined),
        // The re-mine escape: bypass the zero-yield tombstone for this one
        // plan call, for "I removed the downstream item and want it
        // re-proposed".
        force: args["force"] === true,
        closeHostErrors,
      });
      return {
        phase: "plan",
        session_id: plan.sessionId,
        generated_at: plan.generatedAt,
        boundary_decision: plan.boundaryDecision,
        turns_scanned: plan.turnsScanned,
        turns_mined: plan.turnsMined.map((t) => ({
          turn_id: t.turnId,
          text: t.text,
          timestamp: t.timestamp,
        })),
        // The hash of the material this plan offered, also recorded as a
        // pending survey; the commit that answers it may pass it back as
        // `surveyed_turns_hash` to check the session did not change.
        surveyed_turns_hash: plan.surveyedTurnsHash,
        cap: plan.cap,
        confidence_floor: plan.confidenceFloor,
        llm_step: plan.llmStep,
        // Optional fields, present only while the decision-model turn
        // pre-filter is on (never with the use `off`) or when the session
        // carries a zero-yield mining tombstone.
        ...(plan.turnsDropped !== undefined ? { turns_dropped: plan.turnsDropped } : {}),
        ...(plan.skipped !== undefined
          ? {
              skipped: {
                reason: plan.skipped.reason,
                ...(plan.skipped.turnsDropped !== undefined
                  ? { turns_dropped: plan.skipped.turnsDropped }
                  : {}),
                ...(plan.skipped.miningOutcome !== undefined
                  ? {
                      mining_outcome: {
                        written: plan.skipped.miningOutcome.written,
                        staged: plan.skipped.miningOutcome.staged,
                        deduped: plan.skipped.miningOutcome.deduped,
                        durability_rejected: plan.skipped.miningOutcome.durabilityRejected,
                      },
                    }
                  : {}),
              },
            }
          : {}),
        ...(plan.decisionModel !== undefined
          ? { decision_model: { degraded: plan.decisionModel.degraded } }
          : {}),
        // Present only when the plan could not record its survey; a barren
        // commit then needs `surveyed_turns_hash` to record its tombstone.
        ...(plan.surveyRecordFailure !== undefined
          ? { survey_record_failure: plan.surveyRecordFailure }
          : {}),
      };
    }
    const now = new Date();
    // Read raw rather than through coerceStr, which maps "" to absent: an
    // empty relay is a malformed hash, and the core refuses it by name.
    const surveyedRaw = args["surveyed_turns_hash"];
    if (surveyedRaw !== undefined && surveyedRaw !== null && typeof surveyedRaw !== "string") {
      throw new MCPError(INVALID_PARAMS, "argument 'surveyed_turns_hash' must be a string");
    }
    const surveyedTurnsHash = typeof surveyedRaw === "string" ? surveyedRaw : undefined;
    const res = commitExtractedSignals(
      ctx.vault,
      session,
      { items: args["items"] },
      // Loaded with parallel I/O here, where the tool can await it.
      {
        agent,
        now,
        dedup: await loadDedupIndex(ctx.vault),
        // The answered plan's surveyed hash, when the caller echoes it: a
        // check that the session did not change since the plan. Absent,
        // the commit checks the survey the plan recorded instead.
        ...(surveyedTurnsHash !== undefined ? { surveyedTurnsHash } : {}),
        closeHostErrors,
      },
    );
    recordExtractPrefilterCommit(ctx.vault, decisionModel, res, now);
    return {
      phase: "commit",
      session_id: res.sessionId,
      // Vault-relative, like every other path this server emits: an MCP
      // response lands in model context, and the absolute host path is
      // not this surface's to hand out.
      written: res.written.map((w) => ({
        id: w.id,
        path: toolPath(ctx, w.path),
        topic: w.topic,
      })),
      staged: res.staged,
      deduped: res.deduped,
      durability_rejected: res.durabilityRejected,
      rejected: res.rejected.map((r) => ({ topic: r.topic, reason: r.reason })),
      // Present only when the commit succeeded but the zero-yield mining
      // tombstone could not be recorded - named, never thrown.
      ...(res.miningLedgerFailure !== undefined
        ? { mining_ledger_failure: res.miningLedgerFailure }
        : {}),
    };
  });
}

export const EXTRACT_TOOLS: ReadonlyArray<ToolDefinition> = Object.freeze([
  {
    name: TOOL,
    kind: "write",
    description:
      "Mine taste signals from an imported session's USER turns; runs no model. Omit `items` for the plan; with `items` commit, and a barren commit records a tombstone. Barren sessions skip as 'mining_tombstone'; `force` re-mines once. Refuses caps, floors, repeats.",
    inputSchema: {
      type: "object",
      properties: {
        session: {
          type: "string",
          description: "Recall session id of an already-imported session.",
        },
        surveyed_turns_hash: {
          type: "string",
          description:
            "Commit phase only, optional: the plan's `surveyed_turns_hash`. If the session changed since that plan, no mining record is written.",
        },
        items: {
          type: "array",
          description: "Mined signals; omit to get the plan and the envelope instead.",
          items: {
            type: "object",
            properties: {
              topic: {
                type: "string",
                description: "Stable kebab-slug naming the rule, unique within the payload.",
              },
              signal: {
                type: "string",
                enum: ["positive", "negative"],
                description: "positive = the rule to follow; negative = what to avoid.",
              },
              principle: {
                type: "string",
                description: "One imperative line stating the rule.",
              },
              confidence: {
                type: "number",
                description: "How sure the caller is; items under the floor refuse the payload.",
              },
              scope: {
                type: "string",
                description: "Optional soft category, e.g. `writing`, `coding`.",
              },
              source_turn: {
                type: "string",
                description: "Optional id of the plan turn the rule was stated in.",
              },
            },
            required: ["topic", "signal", "principle", "confidence"],
            additionalProperties: false,
          },
        },
        agent: {
          type: "string",
          description: "Optional agent identity override; defaults to the server-resolved name.",
        },
        force: {
          type: "boolean",
          description:
            "Plan phase only: bypass the zero-yield mining tombstone for this one call and re-propose the session.",
        },
      },
      required: ["session"],
      additionalProperties: false,
    },
    previewBudget: MCP_PREVIEW_BUDGET,
    handler: toolBrainExtractSignals,
  },
]);