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
5.7 KB
Raw Blame
/**
 * Agent-driven entity intake (model-based NER, Knowledge Provenance suite).
 *
 * Open Second Brain is provider-agnostic: it never runs an entity-recognition
 * model. The calling agent (which owns its model) extracts entities from free
 * note text and submits them here; OSB validates the typed payload and commits
 * it through the shared extraction-intake primitive into the canonical entity
 * registry. No ML dependency is bundled.
 *
 * This is opt-in and non-blocking by construction: a plain note write never
 * triggers it. The agent invokes the tool when it wants discovered entities
 * registered, so extraction adds no latency or token cost to an ordinary save.
 * The contract is structural - the agent returns typed entity/concept records;
 * OSB never matches a natural-language entity-type word list.
 */

import { intakeExtraction, IntakeValidationError } from "../../core/brain/intake/extract-intake.ts";
import { resolveAgentName } from "../../core/config.ts";
import type { ServerContext, ToolDefinition } from "../tool-contract.ts";
import { parseExtractionIntakeArgs } from "./intake-args.ts";
import { readableAtContextReach } from "./reach-readable.ts";
import { wrapToolErrors } from "./shared.ts";
import { vaultForNoteAction } from "./lane-vault.ts";

const TOOL = "brain_intake_entities";

async function toolBrainIntakeEntities(
  ctx: ServerContext,
  args: Record<string, unknown>,
): Promise<Record<string, unknown>> {
  // `source` is required by this tool's contract, and the parser refuses a
  // call without one before anything is written - a call that names no source
  // has no provenance to commit under, and this is the surface that can still
  // ask the caller for it.
  const parsed = parseExtractionIntakeArgs(args, TOOL, "required");
  const agent =
    parsed.agent && parsed.agent.trim().length > 0
      ? parsed.agent
      : resolveAgentName(ctx.configPath ?? undefined);
  // A malformed extraction is a client-resolvable input problem, not a
  // server fault - surface it as INVALID_PARAMS, never a fabricated result.
  return wrapToolErrors(TOOL, [IntakeValidationError], async () => {
    const result = intakeExtraction(vaultForNoteAction(ctx, TOOL), parsed.intake, {
      agent,
      now: new Date(),
      provenance: parsed.provenance,
      // A page the caller may not read at its reach answers as an absent one.
      readable: readableAtContextReach(ctx),
    });
    return {
      entities_created: [...result.entitiesCreated],
      entities_updated: [...result.entitiesUpdated],
      relations_applied: result.relationsApplied,
      // The lane the entities landed in, as the intake ACTUALLY committed it.
      // Classifying the source a second time here would be a second answer to
      // one question, free to disagree with the write that already happened.
      // An untrusted intake quarantines what it introduces, so a caller told
      // only which ids it created would be told nothing about whether it can
      // read them back.
      trust: result.trust,
    };
  });
}

export const NER_TOOLS: ReadonlyArray<ToolDefinition> = Object.freeze([
  {
    name: TOOL,
    kind: "write",
    description:
      "Intake entities the agent extracted from note text into the entity registry (this server runs no model). Supply `entities` (category, name, optional aliases), the `source` they came from, and optional typed `relations`. Entities are quarantined unless the source names a file that exists.",
    inputSchema: {
      type: "object",
      properties: {
        entities: {
          type: "array",
          description: "Entities discovered in the text (non-empty).",
          items: {
            type: "object",
            properties: {
              category: {
                type: "string",
                description: "Entity category slug, e.g. `people`, `concept`, `projects`.",
              },
              name: { type: "string", description: "Canonical display name." },
              aliases: {
                type: "array",
                items: { type: "string" },
                description: "Optional alternate names.",
              },
              confidence: {
                type: "string",
                description: "Optional confidence label passed through verbatim.",
              },
            },
            required: ["category", "name"],
            additionalProperties: false,
          },
        },
        relations: {
          type: "array",
          description: "Optional typed relations between the extracted entities.",
          items: {
            type: "object",
            properties: {
              from: { type: "string", description: "Source entity name." },
              from_category: { type: "string", description: "Optional source category." },
              relation: {
                type: "string",
                description: "Relation token from the relation vocabulary (e.g. `related`).",
              },
              to: { type: "string", description: "Target entity name." },
              to_category: { type: "string", description: "Optional target category." },
            },
            required: ["from", "relation", "to"],
            additionalProperties: false,
          },
        },
        source: {
          type: "string",
          description:
            "Where this extraction came from: a vault wikilink (`[[Articles/x.md]]`) or the address read. Cited on new entity pages; decides their provenance.",
        },
        agent: {
          type: "string",
          description: "Optional agent identity override; defaults to the server-resolved name.",
        },
      },
      required: ["entities", "source"],
      additionalProperties: false,
    },
    handler: toolBrainIntakeEntities,
  },
]);