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
13.7 KB
Raw Blame
/**
 * Knowledge graph: foresight, bridge discovery, community clusters, MOC audit, deep synthesis, idea discovery, the claim ledger, and dead ends.
 *
 * Extracted from the former brain-tools.ts monolith; registration
 * happens through the aggregator, which preserves the public
 * BRAIN_TOOLS surface.
 */

import type { ToolDefinition } from "../tool-contract.ts";
import { MCP_PREVIEW_BUDGET } from "../preview-budget.ts";
import { AGENT_SCOPE_SCHEMA } from "../coerce.ts";
import { toolBrainClaims } from "./knowledge-claim-tools.ts";
import {
  toolBrainCodegraphReport,
  toolBrainDeadEnds,
  toolBrainTruth,
} from "./knowledge-truth-tools.ts";
import {
  toolBrainBridges,
  toolBrainClusters,
  toolBrainDeepSynthesis,
  toolBrainDiarize,
  toolBrainForesight,
  toolBrainIdeaDiscovery,
  toolBrainMocAudit,
} from "./knowledge-lane-tools.ts";

export { statedClaimEntities, claimEventsReport } from "./knowledge-claim-tools.ts";

export const KNOWLEDGE_TOOLS: ReadonlyArray<ToolDefinition> = Object.freeze([
  {
    name: "brain_claims",
    kind: "write",
    description:
      "Claim-graph query (a projection over superseded_by / contradicts / valid_from / valid_until). operation: current (default) = truth now; at = truth at an instant; history = every claim incl. tombstoned; replaced = what replaced X; contests = what contests X; rebuild = rebuild the projection.",
    inputSchema: {
      type: "object",
      properties: {
        operation: {
          type: "string",
          enum: ["current", "at", "history", "replaced", "contests", "rebuild"],
          description: "Which claim-graph query to run (default: current).",
        },
        at: {
          type: "string",
          description: "at: ISO-8601 instant or YYYY-MM-DD date to evaluate truth.",
        },
        id: { type: "string", description: "replaced/contests: the claim id/wikilink to resolve." },
      },
      required: [],
      additionalProperties: false,
    },
    handler: toolBrainClaims,
    previewBudget: MCP_PREVIEW_BUDGET,
  },
  {
    name: "brain_codegraph_report",
    kind: "read",
    description:
      "Read-only codegraph partner report: in-scope project, index state + counts, and Cargo.toml workspace members. When indexed, adds a non-blocking graph-health gate (index.health: dangling refs, self-loops, collapsed edges, cache-root mismatch) before labeling/import trust the graph. Never mutates.",
    inputSchema: {
      type: "object",
      properties: {},
      additionalProperties: false,
    },
    handler: toolBrainCodegraphReport,
    previewBudget: MCP_PREVIEW_BUDGET,
  },
  {
    name: "brain_foresight",
    kind: "read",
    description:
      "Forward-looking projection (Brain's only anticipatory surface): recurring routines coming due within the horizon via cadence arithmetic, recent open commitments, and open questions - deterministic, every item carries sources.",
    inputSchema: {
      type: "object",
      properties: {
        horizon_days: {
          type: "integer",
          minimum: 1,
          description: "Forward horizon in days (default 14).",
        },
      },
      additionalProperties: false,
    },
    handler: toolBrainForesight,
    previewBudget: MCP_PREVIEW_BUDGET,
  },
  {
    name: "brain_bridges",
    kind: "write",
    description:
      "Bridge discovery over the vec index: discover proposes links between embedding-near notes that share no edge (orphan-first, regenerates the bridge proposals page, records a metric); accept writes one related wikilink into the source note; dismiss silences a pair; list reads the artifact back.",
    inputSchema: {
      type: "object",
      properties: {
        operation: {
          type: "string",
          enum: ["discover", "list", "accept", "dismiss"],
          description: "Tool operation.",
        },
        source: { type: "string", description: "Vault-relative source note (accept/dismiss)." },
        target: { type: "string", description: "Vault-relative target note (accept/dismiss)." },
        max: { type: "integer", minimum: 1, description: "Proposal cap (discover)." },
        min_similarity: {
          type: "number",
          exclusiveMinimum: 0,
          maximum: 1,
          description: "Cosine similarity threshold (discover, default 0.8).",
        },
      },
      required: ["operation"],
      additionalProperties: false,
    },
    handler: toolBrainBridges,
    previewBudget: MCP_PREVIEW_BUDGET,
  },
  {
    name: "brain_clusters",
    kind: "write",
    description:
      "Graph-wide community detection: run applies deterministic label propagation, materializes one note per community of size >= min_size, removes stale notes, records a metric; list reads them back. Optional batch_size chunks work with isolated, reported per-batch failures.",
    inputSchema: {
      type: "object",
      properties: {
        operation: { type: "string", enum: ["run", "list"], description: "Tool operation." },
        min_size: {
          type: "integer",
          minimum: 2,
          description: "Smallest community that materializes (run, default 4).",
        },
        batch_size: {
          type: "integer",
          minimum: 1,
          description:
            "Materialize communities in chunks of this size (run); each batch is isolated and reported in the batches array. Default: single pass.",
        },
      },
      required: ["operation"],
      additionalProperties: false,
    },
    handler: toolBrainClusters,
    previewBudget: MCP_PREVIEW_BUDGET,
  },
  {
    name: "brain_moc_audit",
    kind: "read",
    description:
      "Per-MOC coverage audit. Given a hub note id, classifies its outbound cluster into well-covered / fragile / candidate-missing and surfaces a suggested-next candidate. MOC detection is purely structural (outbound link count + link density). Read-only.",
    inputSchema: {
      type: "object",
      properties: {
        id: {
          type: "string",
          description: "Hub note id (e.g. `pref-foo`). Wikilink decoration is stripped if present.",
        },
      },
      required: ["id"],
      additionalProperties: false,
    },
    handler: toolBrainMocAudit,
  },
  {
    name: "brain_deep_synthesis",
    kind: "write",
    description:
      "Topic-scoped deterministic dossier: matched notes, agreements, contradictions, stale claims, knowledge gaps (dangling wikilinks), plus per-finding causal context, decomposed confidence, and a visible evidence-loss ledger. Evidence assembly only. triggers=true enqueues findings.",
    inputSchema: {
      type: "object",
      properties: {
        topic: {
          type: "string",
          minLength: 1,
          maxLength: 500,
          description: "Subject the dossier is built around; matched notes are recalled for it.",
        },
        limit: {
          type: "integer",
          minimum: 1,
          maximum: 100,
          description: "How many matched notes feed the synthesis. Default 30.",
        },
        triggers: {
          type: "boolean",
          description: "Enqueue contradiction/gap findings into the trigger queue.",
        },
        agent_scope: AGENT_SCOPE_SCHEMA,
      },
      required: ["topic"],
      additionalProperties: false,
    },
    previewBudget: MCP_PREVIEW_BUDGET,
    handler: toolBrainDeepSynthesis,
  },
  {
    name: "brain_diarize",
    kind: "read",
    description:
      "Subject profile for a registry entity: assembles its document set from the registry and sources, computes a deterministic stated-vs-evidenced gap (claims vs evidence frequency and recency), and emits a profile skeleton plus one needs-llm-step envelope. Read-only. Unknown entity errors.",
    inputSchema: {
      type: "object",
      properties: {
        entity: {
          type: "string",
          minLength: 1,
          maxLength: 200,
          description: "Entity name or alias to profile.",
        },
        category: {
          type: "string",
          description: "Optional category to disambiguate the entity lookup.",
        },
      },
      required: ["entity"],
      additionalProperties: false,
    },
    previewBudget: MCP_PREVIEW_BUDGET,
    handler: toolBrainDiarize,
  },
  {
    name: "brain_idea_discovery",
    kind: "write",
    description:
      "Ranked next-direction candidates from the vault's open loops: unanswered open questions, orphan research notes (no inbound links), and aging unresolved inbox signals. Deterministic scoring; triggers=true enqueues the ranked ideas.",
    inputSchema: {
      type: "object",
      properties: {
        cap: {
          type: "integer",
          minimum: 1,
          maximum: 50,
          description: "How many ranked ideas to return. Default 5.",
        },
        triggers: {
          type: "boolean",
          description: "Enqueue the ranked ideas into the trigger queue.",
        },
      },
      additionalProperties: false,
    },
    previewBudget: MCP_PREVIEW_BUDGET,
    handler: toolBrainIdeaDiscovery,
  },
  {
    name: "brain_truth",
    kind: "write",
    description:
      "Entity claim ledger: ingest a claim, render current-truth slots, list conflicts, aggregate quantities, report collisions, window recall via the events operation, or commit grounded agent-stated claims via the state operation with per-claim anchoring verdicts.",
    inputSchema: {
      type: "object",
      properties: {
        operation: {
          type: "string",
          enum: ["ingest", "slots", "conflicts", "aggregate", "collisions", "events", "state"],
          description: "Tool operation.",
        },
        entity: {
          type: "string",
          description: "Entity name (ingest, slots filter, aggregate filter, events filter).",
        },
        aspect: { type: "string", description: "Aspect slot for ingest." },
        value: { type: "string", description: "Claim value for ingest." },
        source: { type: "string", description: "Provenance wikilink/path for ingest and state." },
        agent: { type: "string", description: "Agent identity override for ingest and state." },
        quantity_value: { type: "number", description: "Numeric value for quantity claims." },
        quantity_unit: { type: "string", description: "Unit token for quantity claims." },
        quantity_action: { type: "string", description: "Measured action for quantity claims." },
        valid_from: {
          type: "string",
          description:
            "ingest: validity window start (bare ISO date or canonical UTC timestamp); wins over the source frontmatter's valid_from.",
        },
        valid_until: {
          type: "string",
          description:
            "ingest: exclusive validity window end (bare ISO date or canonical UTC timestamp); wins over the source frontmatter's valid_until.",
        },
        action: { type: "string", description: "Measured action for aggregate." },
        unit: { type: "string", description: "Unit token for aggregate (omit for unitless)." },
        since: {
          type: "string",
          description:
            "events: inclusive lower bound on the events' assertion ts (ISO date/datetime, today/yesterday, last week/month, <n>h/<n>d/<n>w). Never a validity filter.",
        },
        until: {
          type: "string",
          description:
            "events: inclusive upper bound on the events' assertion ts, same grammar as since. Never a validity filter.",
        },
        limit: {
          type: "integer",
          minimum: 1,
          description:
            "events: page size (default 200, capped at 1000); rows are ascending assertion ts, so tail-following paginates by advancing since.",
        },
        claims: {
          type: "array",
          items: {
            type: "object",
            properties: {
              subject: { type: "string", description: "Entity the claim is about." },
              relation: {
                type: "string",
                description:
                  "Relation-vocabulary token between subject and object (related, extends, depends_on, refines, contradicts, superseded_by).",
              },
              object: { type: "string", description: "Entity the claim points at." },
            },
            required: ["subject", "relation", "object"],
            additionalProperties: false,
          },
          description:
            "state: the agent-stated claims to ground; each commits only when its subject and object anchor in text.",
        },
        text: {
          type: "string",
          description: "state: the assertion text every claim is anchored against.",
        },
        sample_id: {
          type: "string",
          description:
            "state: the quality-sample id (a context receipt id or opaque hash) these claims were stated against; frozen per claim, reads hydrate it into provenance.",
        },
      },
      required: ["operation"],
      additionalProperties: false,
    },
    handler: toolBrainTruth,
    previewBudget: MCP_PREVIEW_BUDGET,
  },
  {
    name: "brain_dead_ends",
    kind: "write",
    description:
      "Negative-knowledge registry (dead-ends): record one tried-and-failed approach with why it failed, or list the bounded active set so recall surfaces avoid-X alongside prefer-Y.",
    inputSchema: {
      type: "object",
      properties: {
        operation: {
          type: "string",
          enum: ["record", "list"],
          description: "Tool operation.",
        },
        approach: { type: "string", description: "What was tried (record)." },
        reason: { type: "string", description: "Why it failed or was set aside (record)." },
        context: { type: "string", description: "Optional context (record)." },
        agent: { type: "string", description: "Agent identity override (record)." },
      },
      required: ["operation"],
      additionalProperties: false,
    },
    handler: toolBrainDeadEnds,
    previewBudget: MCP_PREVIEW_BUDGET,
  },
]);