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.7 KB
Raw Blame
/**
 * Lifecycle review: pre-dream intent review, retention lifecycle, dream dry-run preview, and staleness scan.
 *
 * Extracted from the former brain-tools.ts monolith; registration
 * happens through the aggregator, which preserves the public
 * BRAIN_TOOLS surface.
 */

import { resolveNearDuplicateRetireSiblingsEnabled } from "../../core/config.ts";
import { resolveSearchConfig } from "../../core/search/index.ts";
import { buildTimelineIndex } from "../../core/brain/temporal/build-index.ts";
import { findStaleEntries } from "../../core/brain/temporal/stale-watch.ts";
import { loadTemporalConfigSafe } from "../../core/brain/policy.ts";
import { buildIntentReview } from "../../core/brain/intent-review.ts";
import { buildRetentionReview, summarizeRetention } from "../../core/brain/retention.ts";
import { buildReviewCandidates } from "../../core/brain/review-candidates.ts";
import { gatedOwnerScopeView } from "../../core/brain/owner-scope-view.ts";
import { everyArtifactRefView, type ArtifactRefView } from "../../core/brain/artifact-ref-view.ts";
import { reachView } from "../../core/brain/reach-view.ts";
import { brainArtifactSlug } from "../../core/brain/wikilink.ts";
import { OPERATION } from "../../core/brain/safeguard.ts";
import type { ProgressSink } from "../../core/brain/progress.ts";
import { contextReach, type ServerContext, type ToolDefinition } from "../tool-contract.ts";
import { vaultPathField } from "../vault-path-field.ts";
import { readableAtContextReachOrUndefined } from "./reach-readable.ts";
import { coerceIsoDate } from "../coerce.ts";
import { toolSafeguard } from "./shared.ts";

/**
 * What this caller may see over the ids and paths a review row names:
 * the gated owner view ANDed with the reach view, so below local reach a
 * record the caller cannot read is named by no row, exactly as an absent
 * one is (a-label-is-not-a-boundary, U3).
 */
function reviewView(ctx: ServerContext): ArtifactRefView {
  return everyArtifactRefView(
    gatedOwnerScopeView(ctx.vault, ctx.agentName),
    reachView(ctx.vault, contextReach(ctx)),
  );
}

async function toolBrainIntentReview(
  ctx: ServerContext,
  args: Record<string, unknown>,
): Promise<Record<string, unknown>> {
  const nowDate = coerceIsoDate(args, "now");
  // Every row is a fold over inbox signal clusters - a topic, a decision,
  // a count - so below local reach the fold runs over the signals and
  // rejected retired records the caller may read only, and a withheld one
  // moves no topic, count or decision (a-label-is-not-a-boundary, U3).
  const readable = readableAtContextReachOrUndefined(ctx);
  const report = buildIntentReview(ctx.vault, {
    ...(nowDate ? { now: nowDate } : {}),
    ...(readable !== undefined ? { readable } : {}),
  });
  return {
    schema_version: report.schema_version,
    generated_at: report.generated_at,
    reviews: report.reviews.map((review) => ({
      topic: review.topic,
      decision: review.decision,
      signal_count: review.signal_count,
      risk_band: review.risk_band,
      risk_score: review.risk_score,
      reasons: [...review.reasons],
    })),
  };
}

async function toolBrainRetention(
  ctx: ServerContext,
  args: Record<string, unknown>,
): Promise<Record<string, unknown>> {
  const nowDate = coerceIsoDate(args, "now");
  const report = buildRetentionReview(ctx.vault, nowDate ? { now: nowDate } : {});
  // Each recommendation names a retired preference or a processed signal
  // by id and by vault-relative path (a-label-is-not-a-boundary, U3). The
  // summary is counted again over the kept rows: a count of withheld ones
  // would say they exist without naming them.
  const view = reviewView(ctx);
  const recommendations = view.keep(report.recommendations, (r) => [r.path, r.id]);
  return {
    schema_version: report.schema_version,
    generated_at: report.generated_at,
    summary: view.filtersNothing ? report.summary : summarizeRetention(recommendations),
    recommendations: recommendations.map((recommendation) => ({
      id: recommendation.id,
      artifact_type: recommendation.artifact_type,
      action: recommendation.action,
      reason: recommendation.reason,
      path: recommendation.path,
    })),
  };
}

async function toolBrainReviewCandidates(
  ctx: ServerContext,
  args: Record<string, unknown>,
  onProgress?: ProgressSink,
): Promise<Record<string, unknown>> {
  const nowDate = coerceIsoDate(args, "now");
  // Surprisal annotation (t_fddfe64a) is best-effort: a resolvable
  // search config adds novelty ranking, anything else degrades to the
  // plain report.
  let searchConfig: ReturnType<typeof resolveSearchConfig> | undefined;
  try {
    searchConfig = resolveSearchConfig({
      vault: ctx.vault,
      configPath: ctx.configPath ?? undefined,
    });
  } catch {
    searchConfig = undefined;
  }
  // Below local reach the dry run plans over the records the caller may
  // read only, so `clusters_below_threshold` and `intent_reviews` - folds
  // over inbox signal clusters keyed by topic - count no withheld signal,
  // and no withheld preference routes a cluster.
  const readable = readableAtContextReachOrUndefined(ctx);
  // The projected rows name preferences that EXIST by the id they would
  // get after the pass, so `ret-<slug>` is resolved back through the
  // shared slug fold and both spellings are asked about
  // (a-label-is-not-a-boundary, U3).
  const view = reviewView(ctx);
  const bothSpellings = (id: string): ReadonlyArray<string> => {
    const slug = brainArtifactSlug(id);
    return [`pref-${slug}`, `ret-${slug}`];
  };
  const report = await buildReviewCandidates(ctx.vault, {
    ...(readable !== undefined ? { readable } : {}),
    // The stored-vector tier probes only the retires `would_retire` keeps,
    // so `retire_siblings_semantic` reflects no hidden retire.
    retiringVisible: (id) => view.row(...bothSpellings(id)),
    // The gate honours the server's own config file, as the write side does.
    retireSiblingsEnabled: resolveNearDuplicateRetireSiblingsEnabled(ctx.configPath ?? undefined),
    // The projection is read-only, but it runs a full dry-run
    // consolidation pass to produce it - the same pass, and so the same
    // budget, as `brain_dream`.
    safeguard: toolSafeguard(ctx, OPERATION.dream),
    ...(onProgress ? { onProgress } : {}),
    ...(nowDate ? { now: nowDate } : {}),
    ...(searchConfig !== undefined ? { searchConfig } : {}),
  });
  // A retire-sibling pair names two preferences; it is kept only when the
  // caller may see both, in both spellings, and the list is filtered
  // before anything is counted, so a withheld page moves no number.
  const retireSiblings =
    report.retire_siblings !== undefined
      ? view.keep(report.retire_siblings, (p) => [
          ...bothSpellings(p.retiring_id),
          ...bothSpellings(p.sibling_id),
        ])
      : [];
  return {
    // Signal rows name an inbox signal by id AND by vault-relative path.
    ...(report.signal_novelty !== undefined
      ? { signal_novelty: view.keep(report.signal_novelty, (s) => [s.path, s.id]) }
      : {}),
    ...(retireSiblings.length > 0
      ? {
          retire_siblings: retireSiblings.map((p) => ({
            retiring_id: p.retiring_id,
            sibling_id: p.sibling_id,
            score: p.score,
            method: p.method,
          })),
        }
      : {}),
    ...(report.retire_siblings_semantic !== undefined
      ? { retire_siblings_semantic: report.retire_siblings_semantic }
      : {}),
    ...(report.retire_siblings_semantic_detail !== undefined
      ? { retire_siblings_semantic_detail: report.retire_siblings_semantic_detail }
      : {}),
    // `would_create` names ids the pass has not written yet, so most of
    // them resolve to nothing and pass; asking anyway is what keeps a
    // projection over an id that DOES already exist from crossing.
    would_create: view.keep(report.would_create, (id) => bothSpellings(id)),
    // `would_promote` is the one that always names live pages: an
    // unconfirmed preference on disk, transitioning to confirmed.
    would_promote: view.keep(report.would_promote, (id) => bothSpellings(id)),
    would_retire: view
      .keep(report.would_retire, (r) => bothSpellings(r.id))
      .map((r) => ({
        id: r.id,
        reason: r.reason,
      })),
    would_supersede: view
      .keep(report.would_supersede, (r) => bothSpellings(r.id))
      .map((r) => ({
        id: r.id,
        reason: r.reason,
      })),
    clusters_below_threshold: report.clusters_below_threshold.map((c) => ({
      topic: c.topic,
      signal_count: c.signal_count,
      distinct_agents: c.distinct_agents,
      age_days: c.age_days,
      failed_gates: [...c.failed_gates],
    })),
    gated_retires: view
      .keep(report.gated_retires, (g) => bothSpellings(g.pref_id))
      .map((g) => ({
        pref_id: g.pref_id,
        topic: g.topic,
        applied_count: g.applied_count,
        violated_count: g.violated_count,
        threshold: g.threshold,
        attempted_reason: g.attempted_reason,
      })),
    intent_reviews: report.intent_reviews.map((review) => ({
      topic: review.topic,
      decision: review.decision,
      signal_count: review.signal_count,
      risk_band: review.risk_band,
      risk_score: review.risk_score,
      reasons: [...review.reasons],
    })),
  };
}

// ----- brain_apply_evidence ------------------------------------------------

/**
 * `brain_stale_scan` - structural staleness report for preferences,
 * signals, and log files. Thresholds come from the `temporal:` config
 * block.
 */
async function toolBrainStaleScan(
  ctx: ServerContext,
  _args: Record<string, unknown>,
): Promise<Record<string, unknown>> {
  void _args;
  const cfg = loadTemporalConfigSafe(ctx.vault);
  // Every stale row names its artifact by id, topic and vault-relative
  // path (a-label-is-not-a-boundary, U3). Log shards are named by date
  // and shared by construction, so they carry no ownership to read.
  // Below local reach a private log event anchors no preference's age.
  const view = reviewView(ctx);
  const index = buildTimelineIndex(ctx.vault, {
    withholdsPrivate: view.withholdsPrivate === true,
  });
  const report = findStaleEntries(index, ctx.vault, cfg);
  return {
    vault_path: vaultPathField(ctx),
    thresholds: report.thresholds,
    stale_preferences: view.keep(report.stalePreferences, (r) => [r.path, r.prefId]),
    stale_signals: view.keep(report.staleSignals, (r) => [r.path, r.signalId]),
    stale_log_files: report.staleLogFiles,
    generated_at: report.generatedAt,
  };
}

export const REVIEW_TOOLS: ReadonlyArray<ToolDefinition> = Object.freeze([
  {
    name: "brain_intent_review",
    kind: "read",
    description:
      "Read-only pre-dream intent review over active signal clusters. Returns each topic's decision, signal count, risk band, risk score, and reasons without mutating files.",
    inputSchema: {
      type: "object",
      properties: {
        now: {
          type: "string",
          description:
            "Optional ISO-8601 timestamp used as the wall clock for the review (testing / replay).",
        },
      },
      additionalProperties: false,
    },
    handler: toolBrainIntentReview,
  },
  {
    name: "brain_retention",
    kind: "read",
    description:
      "Recommendation-only lifecycle review over retired preferences and processed signals. Returns keep/improve/park/prune candidates and never deletes or moves artifacts.",
    inputSchema: {
      type: "object",
      properties: {
        now: {
          type: "string",
          description:
            "Optional ISO-8601 timestamp used as the wall clock for the review (testing / replay).",
        },
      },
      additionalProperties: false,
    },
    handler: toolBrainRetention,
  },
  {
    name: "brain_review_candidates",
    kind: "read",
    description:
      "Read-only preview of the next `brain_dream` pass: would_create / would_promote / would_retire / would_supersede, clusters below threshold, gated retires, intent reviews, and opt-in retire_siblings (lexical or stored-vector pairs; tier status in retire_siblings_semantic). Mutates nothing.",
    inputSchema: {
      type: "object",
      properties: {
        now: {
          type: "string",
          description:
            "Optional ISO-8601 timestamp used as the wall clock for the dry-run (testing / replay).",
        },
      },
      additionalProperties: false,
    },
    handler: toolBrainReviewCandidates,
  },
  {
    name: "brain_stale_scan",
    kind: "read",
    description:
      "Structural staleness report: preferences, signals, and log days inactive longer than the configured `temporal:` thresholds (stale_pref_days / stale_signal_days / stale_log_days). Read-only.",
    inputSchema: {
      type: "object",
      properties: {},
      additionalProperties: false,
    },
    handler: toolBrainStaleScan,
  },
]);