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
10.2 KB
Raw Blame
/**
 * Context assembly: write sessions, pinned scratchpad, session bootstrap, context packing, receipts, presets, and pre-compress/pre-compact surfaces.
 *
 * Extracted from the former brain-tools.ts monolith; registration
 * happens through the aggregator, which preserves the public
 * BRAIN_TOOLS surface.
 */

import { SCOPED_RULE_AXES } from "../../core/brain/scoped-rules.ts";
import { CURSOR_SCHEMA } from "./pagination.ts";
import { type ToolDefinition } from "../tool-contract.ts";
import { VAULT_PATH_OUTPUT_SCHEMA } from "../vault-path-field.ts";
import { toolBrainWriteSession } from "./context-session-tools.ts";
import { toolBrainPinnedContext } from "./context-pinned-tools.ts";
import { toolBrainContext } from "./context-active-tools.ts";

/**
 * One agent-facing surface for the write-session kernel: `op`
 * discriminates the lifecycle operation, `kind` (open only) picks
 * artifact vs panel. Envelopes are the same JSON the CLI prints -
 * status, step, prompt, errors, attempts_left, expires_at, target.
 * Structured request failures surface as INVALID_PARAMS with the
 * machine-readable error list in the message.
 */

// ----- brain_context (v0.10.10) --------------------------------------------

// ----- brain_digest --------------------------------------------------------

const PINNED_CONTEXT_OUTPUT_SCHEMA: NonNullable<ToolDefinition["outputSchema"]> = {
  type: "object",
  required: ["present", "path", "absolute_path", "content"],
  properties: {
    operation: { type: "string", enum: ["read", "write", "append", "clear"] },
    present: { type: "boolean" },
    path: { type: "string" },
    absolute_path: { type: "string" },
    content: { type: "string" },
    done: { type: "boolean" },
    operations_applied: { type: "integer" },
  },
  additionalProperties: false,
};

const BRAIN_CONTEXT_OUTPUT_SCHEMA: NonNullable<ToolDefinition["outputSchema"]> = {
  type: "object",
  required: [
    "vault_path",
    "present",
    "active_path",
    "content",
    "counts",
    "generated_at",
    "pinned",
    "maintenance_overdue",
  ],
  properties: {
    vault_path: VAULT_PATH_OUTPUT_SCHEMA,
    present: { type: "boolean" },
    active_path: { type: "string" },
    content: { type: "string" },
    counts: {
      type: "object",
      required: ["confirmed", "quarantine", "retired_recent", "most_applied_30d"],
      properties: {
        confirmed: { type: "integer" },
        quarantine: { type: "integer" },
        retired_recent: { type: "integer" },
        most_applied_30d: { type: "integer" },
      },
      additionalProperties: false,
    },
    generated_at: {},
    pinned: PINNED_CONTEXT_OUTPUT_SCHEMA,
    // `boolean | null` (empty schema, matching `generated_at` above): a
    // cheap, bounded proxy over the single newest `Brain/log/` day only -
    // `null` when there is no log history yet or the newest day could
    // not be read. See `computeMaintenanceOverdueFlag`'s docblock
    // (`src/core/brain/status.ts`) for exactly what it measures and its
    // cost bound; it is NOT the precise `maintenance_debt` figure that
    // `second_brain_status` / `osb://status` report.
    maintenance_overdue: {},
    // Declared but deliberately NOT required: a vault whose operator has
    // written no standing rules omits the key entirely, exactly as the
    // vault-instruction field does, so hosts that strip unknown fields
    // stay byte-identical on the common path.
    standing_rules: {
      type: "object",
      required: ["path", "content", "truncated"],
      properties: {
        path: { type: "string" },
        content: { type: "string" },
        truncated: { type: "boolean" },
      },
      additionalProperties: false,
    },
    // Declared, not required: present only at local reach and only when a
    // scoped rule file matched this server's project, harness or host (or
    // the host notice applies), so the common path stays byte-identical.
    scoped_rules: {
      type: "object",
      required: ["scope", "files"],
      properties: {
        scope: {
          type: "object",
          required: ["project", "harness", "host"],
          // `string | null` each (empty schema, as `generated_at` above):
          // the descriptor subset has no union type.
          properties: { project: {}, harness: {}, host: {} },
          additionalProperties: false,
        },
        files: {
          type: "array",
          items: {
            type: "object",
            required: ["path", "axis", "truncated"],
            properties: {
              path: { type: "string" },
              axis: { type: "string", enum: SCOPED_RULE_AXES },
              truncated: { type: "boolean" },
            },
            additionalProperties: false,
          },
        },
      },
      additionalProperties: false,
    },
    // Present only when the instruction-file read failed; see the
    // "a throw is not an absence" note on the handler.
    vault_instruction_error: { type: "string" },
  },
};

export const CONTEXT_TOOLS: ReadonlyArray<ToolDefinition> = Object.freeze([
  {
    name: "brain_write_session",
    kind: "write",
    description:
      "Provider-agnostic Brain write sessions (artifact and decision-panel kinds): open returns a generation prompt, submit validates the text, only clean artifacts commit. Correction loop, retry cap, collision guard, optional operator review. The calling agent generates; the Brain never does.",
    inputSchema: {
      type: "object",
      properties: {
        op: {
          type: "string",
          enum: ["open", "submit", "approve", "abandon", "status", "list"],
          description: "Lifecycle operation.",
        },
        kind: {
          type: "string",
          enum: ["artifact", "panel"],
          description: "Session kind for op=open. Defaults to artifact.",
        },
        session_id: {
          type: "string",
          description: "Session id (`ws-...`) for submit/approve/abandon/status.",
        },
        target: {
          type: "string",
          description:
            "Commit target: Brain/sources/, reports/, distillations/, notes/ or decisions/panels/ (artifact open; panel override). The rest of Brain/ is refused.",
        },
        text: {
          type: "string",
          description:
            "Generated text for op=submit: the full artifact, a persona answer, or the synthesis.",
        },
        topic: { type: "string", description: "Decision topic (panel open)." },
        personas: {
          type: "array",
          items: { type: "string" },
          description:
            "Persona slugs to convene in order (panel open). Defaults to every loaded persona.",
        },
        schema_type: {
          type: "string",
          description: "Schema-pack page type the artifact must declare (artifact open).",
        },
        intent: {
          type: "string",
          enum: ["create", "overwrite", "merge"],
          description:
            "Commit intent against an existing target (artifact open). Default create - never overwrites.",
        },
        prompt: { type: "string", description: "Custom generation instruction (artifact open)." },
        require_review: {
          type: "boolean",
          description: "Park the validated artifact at needs-review until an operator approves.",
        },
        retry_cap: { type: "number", description: "Failed submits allowed per step (default 3)." },
        limit: {
          type: "number",
          description: "Max sessions returned by op=list (default 100, cap 500).",
        },
        cursor: CURSOR_SCHEMA,
        agent: { type: "string", description: "Agent identity override (open)." },
      },
      required: ["op"],
      additionalProperties: false,
    },
    handler: toolBrainWriteSession,
  },
  {
    name: "brain_pinned_context",
    kind: "write",
    description:
      "Read, write, append, or clear the transient current-task scratchpad (pinned context). Use for facts that should survive context rotation but should not become permanent preferences. Pass `operations` to apply an ordered batch atomically (all-or-nothing).",
    inputSchema: {
      type: "object",
      properties: {
        operation: {
          type: "string",
          enum: ["read", "write", "append", "clear"],
          description:
            "Single operation to perform. Defaults to read. Ignored when `operations` is given.",
        },
        content: {
          type: "string",
          description: "Pinned context body for write/append operations.",
        },
        operations: {
          type: "array",
          description:
            "Ordered batch applied atomically; any invalid op aborts the whole batch with no write.",
          items: {
            type: "object",
            properties: {
              op: {
                type: "string",
                enum: ["write", "append", "clear", "replace"],
                description: "What this step does to the pinned body.",
              },
              content: { type: "string", description: "Body for write/append ops." },
              find: { type: "string", description: "Exact segment to locate for a replace op." },
              replace: { type: "string", description: "Replacement text for a replace op." },
            },
            required: ["op"],
            additionalProperties: false,
          },
        },
      },
      additionalProperties: false,
    },
    outputSchema: PINNED_CONTEXT_OUTPUT_SCHEMA,
    handler: toolBrainPinnedContext,
  },
  {
    name: "brain_context",
    // Write-mode-dominant (tool-contract.ts), not "read": the bootstrap
    // path calls `regenerateActive`, which writes the shared
    // `Brain/active.md` whenever the body is absent or stale. A read
    // classification would let concurrent session starts regenerate that
    // one shared file beside each other on the stdio read path.
    kind: "write",
    description:
      "Pull the active-preferences digest, pinned current-task context, and active-preference counts. Use at session start when SessionStart hook is unavailable (Cursor, Aider, raw Claude API). Regenerates the digest when absent or stale.",
    inputSchema: {
      type: "object",
      properties: {},
      additionalProperties: false,
    },
    outputSchema: BRAIN_CONTEXT_OUTPUT_SCHEMA,
    handler: toolBrainContext,
  },
]);