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
22.4 KB
Raw Blame
/**
 * `o2b brain entity <set|get|list|relate|archive|merge>` - canonical entity
 * registry verbs (Memory Integrity Suite). Writes stay on the CLI;
 * the MCP surface exposes the read-only subset (`brain_entity`).
 */

import { resolveAgentName } from "../../../core/config.ts";
import {
  archiveEntity,
  getEntity,
  listEntities,
  relateEntities,
  upsertEntity,
} from "../../../core/brain/entities/registry.ts";
import {
  EntityMergeError,
  applyEntityMerge,
  entityMergePlanHash,
  planEntityMerge,
  type EntityMergePlan,
} from "../../../core/brain/entities/page-merge.ts";
import {
  BRAIN_ENTITY_STATUS_VALUES,
  isBrainEntityStatus,
  type BrainEntity,
} from "../../../core/brain/entities/types.ts";
import { pruneEntityLabels } from "../../../core/brain/entities/label-hygiene.ts";
import {
  deriveEntityLexicon,
  ENTITY_LEXICON_ARTIFACT_REL,
  writeEntityLexicon,
} from "../../../core/brain/entities/lexicon.ts";
import {
  brainVerbContext,
  CliError,
  fail,
  info,
  normalizeFlagString,
  ok,
  okJson,
  parse,
  readSingleLine,
  usageError,
} from "../helpers.ts";
import { shellWord } from "../../cron-recipe.ts";

function entityPayload(entity: BrainEntity): Record<string, unknown> {
  return {
    id: entity.id,
    category: entity.category,
    name: entity.name,
    aliases: [...entity.aliases],
    status: entity.status,
    ...(entity.source_agent !== undefined ? { source_agent: entity.source_agent } : {}),
    ...(entity.confidence !== undefined ? { confidence: entity.confidence } : {}),
    created_at: entity.created_at,
    updated_at: entity.updated_at,
    ...(entity.archived_at !== undefined ? { archived_at: entity.archived_at } : {}),
    relations: entity.relations.map((r) => ({ relation: r.relation, target: r.target })),
    path: entity.path,
  };
}

function entityLine(entity: BrainEntity): string {
  const aliases = entity.aliases.length > 0 ? `  aliases: ${entity.aliases.join(", ")}` : "";
  return `${entity.id}  [${entity.status}]  ${entity.category}/${entity.name}${aliases}`;
}

export async function cmdBrainEntity(argv: string[]): Promise<number> {
  const sub = argv[0];
  const rest = argv.slice(1);
  switch (sub) {
    case "set":
      return entitySet(rest);
    case "get":
      return entityGet(rest);
    case "list":
      return entityList(rest);
    case "relate":
      return entityRelate(rest);
    case "archive":
      return entityArchive(rest);
    case "prune":
      return entityPrune(rest);
    case "lexicon":
      return entityLexicon(rest);
    case "merge":
      return await entityMerge(rest);
    default:
      return usageError(
        "brain entity requires a subcommand: set <category> <name> | get <name> | list | " +
          "relate <from> <relation> <to> | archive <name> [--restore] | " +
          "prune [--confirm] [--include-advisory] | lexicon rebuild [--apply] | " +
          "merge <keep> <drop> [--dry-run] [--expect-hash <hash>]",
      );
  }
}

function entitySet(argv: string[]): number {
  const { flags, positional } = parse(argv, {
    vault: { type: "string" },
    alias: { type: "string-array" },
    body: { type: "string" },
    confidence: { type: "string" },
    json: { type: "boolean" },
  });
  if (positional.length < 2) {
    return fail("brain entity set requires <category> and <name> arguments");
  }
  const { config, vault } = brainVerbContext(flags);
  const agent = resolveAgentName(config);
  const body = normalizeFlagString(flags["body"]);
  const confidence = normalizeFlagString(flags["confidence"]);
  try {
    const out = upsertEntity(vault, {
      category: positional[0]!,
      name: positional[1]!,
      aliases: (flags["alias"] as string[] | undefined) ?? [],
      agent,
      now: new Date(),
      ...(body !== null ? { body } : {}),
      ...(confidence !== null ? { confidence } : {}),
    });
    if (flags["json"]) {
      okJson({ ...entityPayload(out.entity), created: out.created });
    } else {
      ok(`${out.created ? "created" : "updated"}: ${out.entity.id}`);
    }
    return 0;
  } catch (exc) {
    return fail(`brain entity set failed: ${(exc as Error).message}`);
  }
}

function entityGet(argv: string[]): number {
  const { flags, positional } = parse(argv, {
    vault: { type: "string" },
    category: { type: "string" },
    json: { type: "boolean" },
  });
  if (positional.length < 1) return fail("brain entity get requires a <name-or-alias> argument");
  const vault = brainVerbContext(flags).vault;
  const category = normalizeFlagString(flags["category"]);
  try {
    const entity = getEntity(vault, {
      query: positional[0]!,
      ...(category !== null ? { category } : {}),
    });
    if (entity === null) {
      process.stderr.write(`entity not found: ${positional[0]!}\n`);
      return 2;
    }
    if (flags["json"]) {
      okJson(entityPayload(entity));
    } else {
      ok(entityLine(entity));
      if (entity.body.trim().length > 0) ok(entity.body.trim());
    }
    return 0;
  } catch (exc) {
    return fail(`brain entity get failed: ${(exc as Error).message}`);
  }
}

function entityList(argv: string[]): number {
  const { flags } = parse(argv, {
    vault: { type: "string" },
    category: { type: "string" },
    status: { type: "string" },
    json: { type: "boolean" },
  });
  const vault = brainVerbContext(flags).vault;
  const category = normalizeFlagString(flags["category"]);
  const statusRaw = normalizeFlagString(flags["status"]);
  // Validated against the vocabulary itself rather than a hand-written pair,
  // so a new status is listable the day it exists. `--status quarantine` is
  // how an operator sees what an untrusted intake put aside.
  if (statusRaw !== null && !isBrainEntityStatus(statusRaw)) {
    return fail(`--status must be one of: ${BRAIN_ENTITY_STATUS_VALUES.join(", ")}`);
  }
  try {
    const entities = listEntities(vault, {
      ...(category !== null ? { category } : {}),
      ...(statusRaw !== null ? { status: statusRaw } : {}),
    });
    if (flags["json"]) {
      okJson({ entities: entities.map(entityPayload), total: entities.length });
    } else if (entities.length === 0) {
      ok("no entities");
    } else {
      for (const entity of entities) ok(entityLine(entity));
    }
    return 0;
  } catch (exc) {
    return fail(`brain entity list failed: ${(exc as Error).message}`);
  }
}

function entityRelate(argv: string[]): number {
  const { flags, positional } = parse(argv, {
    vault: { type: "string" },
    "from-category": { type: "string" },
    "to-category": { type: "string" },
    json: { type: "boolean" },
  });
  if (positional.length < 3) {
    return fail("brain entity relate requires <from> <relation> <to> arguments");
  }
  const vault = brainVerbContext(flags).vault;
  const fromCategory = normalizeFlagString(flags["from-category"]);
  const toCategory = normalizeFlagString(flags["to-category"]);
  try {
    const entity = relateEntities(vault, {
      from: { query: positional[0]!, ...(fromCategory !== null ? { category: fromCategory } : {}) },
      relation: positional[1]!,
      to: { query: positional[2]!, ...(toCategory !== null ? { category: toCategory } : {}) },
      now: new Date(),
    });
    if (flags["json"]) {
      okJson(entityPayload(entity));
    } else {
      ok(`${entity.id} ${positional[1]!} -> ${positional[2]!}`);
    }
    return 0;
  } catch (exc) {
    return fail(`brain entity relate failed: ${(exc as Error).message}`);
  }
}

function entityPrune(argv: string[]): number {
  const { flags } = parse(argv, {
    vault: { type: "string" },
    confirm: { type: "boolean" },
    "include-advisory": { type: "boolean" },
    json: { type: "boolean" },
  });
  const { vault } = brainVerbContext(flags);
  const confirm = flags["confirm"] === true;
  const includeAdvisory = flags["include-advisory"] === true;
  try {
    const result = pruneEntityLabels(vault, { confirm, includeAdvisory, now: new Date() });
    if (flags["json"]) {
      okJson({
        confirmed: result.confirmed,
        candidates: result.candidates.map((c) => ({
          id: c.id,
          category: c.category,
          name: c.name,
          status: c.status,
          reason: c.reason,
          advisory: c.advisory,
          path: c.path,
          inbound_references: [...c.inboundReferences],
        })),
        advisory_skipped: result.advisorySkipped,
        removed: [...result.removed],
        edges_stripped: result.edgesStripped,
        snapshot_run_id: result.snapshotRunId,
        snapshot_path: result.snapshotPath,
      });
      return 0;
    }
    const advisoryNote =
      result.advisorySkipped > 0
        ? ` (${result.advisorySkipped} advisory finding(s) skipped - a single-token shout ` +
          "or a common-word run; the doctor reports them)"
        : "";
    if (result.candidates.length === 0) {
      if (result.advisorySkipped > 0) {
        ok(`entity prune: no structural malformed labels found${advisoryNote}`);
        info("  re-run with --include-advisory to prune the advisory classes too");
      } else {
        ok("entity prune: no malformed labels found");
      }
      return 0;
    }
    if (result.confirmed) {
      ok(`entity prune: removed ${result.removed.length} node(s)${advisoryNote}`);
      for (const c of result.candidates) ok(`  - ${c.id} (${c.reason}) ${JSON.stringify(c.name)}`);
      if (result.edgesStripped > 0) ok(`  stripped ${result.edgesStripped} inbound edge(s)`);
      if (result.snapshotRunId) {
        ok(`  recovery point: snapshot ${result.snapshotRunId}`);
        if (result.snapshotPath) info(`    ${result.snapshotPath}`);
      }
      return 0;
    }
    ok(
      `entity prune (DRY RUN): ${result.candidates.length} malformed label(s) WOULD be ` +
        `removed${advisoryNote}:`,
    );
    for (const c of result.candidates) {
      const edges =
        c.inboundReferences.length > 0
          ? `, ${c.inboundReferences.length} inbound edge(s) from ${c.inboundReferences.join(", ")}`
          : "";
      ok(`  - ${c.id} (${c.reason}) ${JSON.stringify(c.name)}${edges}`);
    }
    info("  re-run with --confirm to remove (a snapshot is taken first)");
    return 0;
  } catch (exc) {
    const message = `brain entity prune failed: ${(exc as Error).message}`;
    if (flags["json"]) {
      okJson({ ok: false, message });
      return 1;
    }
    return fail(message);
  }
}

/**
 * `o2b brain entity lexicon rebuild` (recall-quality A4): re-derive the
 * store-learned entity lexicon over the vault's operator pages. Dry-run
 * report by default; `--apply` writes ONLY the derived artifact
 * (`Brain/entities/lexicon.json`) through the atomic, vault-identity-
 * guarded derived-artifact writer. A derived write mutates no entity node
 * and removes nothing, so it never needs `--confirm` - the flag reserved
 * for destructive work (see `entity prune`).
 */
function entityLexicon(argv: string[]): number {
  const sub = argv[0];
  if (sub !== "rebuild") {
    return fail("brain entity lexicon requires a subcommand: rebuild [--apply]");
  }
  const { flags } = parse(argv.slice(1), {
    vault: { type: "string" },
    apply: { type: "boolean" },
    json: { type: "boolean" },
  });
  const { vault } = brainVerbContext(flags);
  try {
    const doc = deriveEntityLexicon(vault, { now: new Date() });
    const applied = flags["apply"] === true;
    const path = applied ? writeEntityLexicon(vault, doc) : null;
    const entries = Object.keys(doc.entries).length;
    const scope = doc.caseful ? "caseful corpus" : "caseless corpus (case verdicts stay off)";
    if (flags["json"]) {
      okJson({
        applied,
        schema: doc.schema,
        entries,
        caseful: doc.caseful,
        corpus_scope: doc.corpus_scope,
        dataset_hash: doc.dataset_hash,
        generated_at: doc.generated_at,
        ...(path !== null ? { path } : {}),
      });
      return 0;
    }
    if (applied) {
      ok(`entity lexicon rebuild: wrote ${entries} token entries (${scope})`);
      info(`  artifact: ${ENTITY_LEXICON_ARTIFACT_REL}; dataset ${doc.dataset_hash}`);
    } else {
      ok(`entity lexicon rebuild (DRY RUN): ${entries} token entries WOULD be written (${scope})`);
      info(`  dataset ${doc.dataset_hash}`);
      info(`  re-run with --apply to write ${ENTITY_LEXICON_ARTIFACT_REL}`);
    }
    return 0;
  } catch (exc) {
    return fail(`brain entity lexicon rebuild failed: ${(exc as Error).message}`);
  }
}

function entityArchive(argv: string[]): number {
  const { flags, positional } = parse(argv, {
    vault: { type: "string" },
    category: { type: "string" },
    restore: { type: "boolean" },
    json: { type: "boolean" },
  });
  if (positional.length < 1) {
    return fail("brain entity archive requires a <name-or-alias> argument");
  }
  const vault = brainVerbContext(flags).vault;
  const category = normalizeFlagString(flags["category"]);
  try {
    const entity = archiveEntity(
      vault,
      { query: positional[0]!, ...(category !== null ? { category } : {}) },
      { now: new Date(), ...(flags["restore"] ? { restore: true } : {}) },
    );
    if (flags["json"]) {
      okJson(entityPayload(entity));
    } else {
      ok(`${entity.id} -> ${entity.status}`);
    }
    return 0;
  } catch (exc) {
    const message = (exc as Error).message;
    if (message.includes("not found")) {
      process.stderr.write(`${message}\n`);
      return 2;
    }
    return fail(`brain entity archive failed: ${message}`);
  }
}

/** One plan line an operator (or a TTY prompt) reads before consenting. */
function mergePlanLines(plan: EntityMergePlan, hash: string, applyCommand: string): string[] {
  return [
    "merge plan:",
    `  keep: ${plan.keep_id} (${plan.keep_name})`,
    `  drop: ${plan.drop_id} (${plan.drop_name}) -> ${plan.drop_path}`,
    `  alias added: ${plan.alias_added ?? "none - the survivor already answers to that name"}`,
    `  body: ${plan.body_folded ? "folded into the survivor" : "archived (nothing to fold)"}`,
    `  relations absorbed: ${plan.relations_absorbed}; inbound edges retargeted: ` +
      `${plan.inbound_edges_retargeted}; cyclic edges removed: ${plan.cyclic_edges_removed}`,
    // The bypass is a fact about this plan, stated where the consent is
    // given - never left to be inferred from a flag in the echo.
    ...(plan.guard_bypassed
      ? ["  guard: --force bypasses the text-level merge guard for this merge"]
      : []),
    `  plan-hash: ${hash}`,
    `  apply: ${applyCommand}`,
  ];
}

/** Refusals carry the CODE first, then the sentence an agent can skip. */
function entityMergeRefusal(exc: unknown, json: boolean): number {
  if (exc instanceof EntityMergeError) {
    if (json) {
      okJson({ ok: false, code: exc.code, message: exc.message });
      return 1;
    }
    return fail(`brain entity merge: ${exc.message}`);
  }
  // Not a merge refusal - vault identity, snapshot gate, fs. Rethrow so
  // the verb-level wrapper answers a JSON caller on stdout.
  throw exc;
}

/** Refusal code for a merge nobody consented to: consent missing, not wrong. */
const CONSENT_REQUIRED_CODE = "consent-required";

/** The parsed-flag shape `parse` returns, restated for the run helper. */
type EntityMergeFlags = Record<string, string | boolean | string[] | undefined>;

/**
 * `o2b brain entity merge <keep> <drop>` (actionable-now batch, A2 /
 * t_28a8789d): preview-and-apply repair for two entity pages that denote
 * one subject - the doctor's `duplicate-entity` collision, or an opt-in
 * `entity-alias-candidate` nomination. Both subjects accept ids, names
 * and aliases, so either finding resolves.
 *
 * The gate is the plan hash: `--dry-run` renders the plan and echoes its
 * hash; apply requires `--expect-hash <hash>` and re-plans, refusing
 * before any write when the live vault no longer produces the plan the
 * caller read. Consent is a TTY y/N prompt, `--force` for agents, and
 * `--json` refuses without `--force` because the prompt cannot render.
 * The apply itself never bare-deletes: the old page is archived behind
 * the destructive-snapshot gate, the old name becomes an alias on the
 * survivor, and no claim is rewritten.
 *
 * The body runs under one more gate: a failure below the verb's own
 * refusal vocabulary (vault identity, the snapshot gate, the filesystem)
 * still owes a `--json` caller a structured line on stdout instead of
 * prose on a channel the caller never reads.
 */
async function entityMerge(argv: string[]): Promise<number> {
  const { flags, positional } = parse(argv, {
    vault: { type: "string" },
    "dry-run": { type: "boolean" },
    "expect-hash": { type: "string" },
    force: { type: "boolean" },
    agent: { type: "string" },
    json: { type: "boolean" },
  });
  const json = flags["json"] === true;
  try {
    return await runEntityMerge(flags, positional, json);
  } catch (exc) {
    // A missing or empty --vault stays a usage-level CliError with its own
    // top-level formatting; everything else is an internal failure, and
    // the message travels alone - never a stack.
    if (exc instanceof CliError) throw exc;
    const message = exc instanceof Error ? exc.message : String(exc);
    if (json) {
      okJson({ ok: false, code: "internal-error", message });
      return 1;
    }
    return fail(`brain entity merge failed: ${message}`);
  }
}

async function runEntityMerge(
  flags: EntityMergeFlags,
  positional: string[],
  json: boolean,
): Promise<number> {
  if (positional.length !== 2) {
    return fail("brain entity merge requires <keep> and <drop> (ids, names or aliases)");
  }
  const { config, vault } = brainVerbContext(flags);
  const refs = { keep: positional[0]!, drop: positional[1]! };
  const force = flags["force"] === true;
  const dryRun = flags["dry-run"] === true;
  const expectHash = normalizeFlagString(flags["expect-hash"]);
  // The acting identity, resolved the way the sibling entity verbs do:
  // an explicit --agent wins, a blank one normalizes away, and the
  // configured agent_name attributes what is left - never "unknown"
  // while a config names an agent, and never a null actor at all.
  const agent = normalizeFlagString(flags["agent"]) ?? resolveAgentName(config);

  let plan: EntityMergePlan;
  try {
    // `--force` is the consent for the text-level merge guard bypass, so it
    // reaches the preview too: a guarded pair must be previewable (to get
    // its plan hash) exactly as it is applicable. The plan-hash gate below
    // is separate and stays unbypassable.
    plan = planEntityMerge(vault, refs, { bypassEntityGuard: force });
  } catch (exc) {
    return entityMergeRefusal(exc, json);
  }
  const hash = entityMergePlanHash(plan);
  // The echo is a command an operator (or an agent) pastes back, so every
  // argument a shell would split is quoted: subjects AND the vault. An
  // explicit --vault rides along - against a synced copy with identical
  // ids and paths, an echo that dropped it would apply to whichever vault
  // the paste resolved instead of the one that was previewed.
  const vaultFlag = normalizeFlagString(flags["vault"]);
  const applyCommand =
    `o2b brain entity merge ${shellWord(refs.keep)} ${shellWord(refs.drop)}` +
    (vaultFlag !== null ? ` --vault ${shellWord(vaultFlag)}` : "") +
    ` --expect-hash ${hash}` +
    (force ? " --force" : "");
  const planLines = mergePlanLines(plan, hash, applyCommand);

  if (dryRun) {
    if (json) {
      okJson({ dry_run: true, plan, plan_hash: hash, apply: applyCommand });
    } else {
      for (const line of planLines) ok(line);
      ok("dry-run; no changes written");
    }
    return 0;
  }

  // The hash gate is a fact-check, not a consent gate: it runs before the
  // prompt and refuses regardless of --force, because a stale plan is a
  // vault that moved under the operator.
  if (expectHash === null) {
    return entityMergeRefusal(
      new EntityMergeError(
        "hash-required",
        "no --expect-hash given; run the --dry-run preview first and present the plan hash " +
          "it echoes",
      ),
      json,
    );
  }
  if (expectHash !== hash) {
    // One story, whatever the stance history: the plan hash seals the
    // vault state the preview saw (a guard-passing pair hashes
    // identically at either --force stance - only an override the guard
    // would have refused stamps differently, and a pair the guard
    // refuses cannot be re-planned without it), so a mismatch means the
    // vault moved under the operator, and the refusal says so plainly.
    return entityMergeRefusal(
      new EntityMergeError(
        "hash-mismatch",
        `--expect-hash ${expectHash} does not describe this vault's merge plan any more ` +
          `(${hash}); the vault changed since the preview - re-run the preview and apply ` +
          "the hash it echoes",
      ),
      json,
    );
  }

  if (!force) {
    // Either consent refusal keeps its prose line for a human, but a JSON
    // caller gets the structured shape on stdout - same contract as every
    // other refusal this verb emits.
    const consentRefusal = (message: string): number => {
      if (json) {
        okJson({ ok: false, code: CONSENT_REQUIRED_CODE, message });
        return 1;
      }
      return fail(message);
    };
    if (json) {
      return consentRefusal(
        "brain entity merge: --json without --force is not supported (interactive prompt " +
          "cannot render)",
      );
    }
    if (!process.stdin.isTTY) {
      return consentRefusal(
        "brain entity merge: --force required when stdin is not a TTY (cannot prompt for " +
          "confirmation)",
      );
    }
    for (const line of planLines) process.stderr.write(line + "\n");
    process.stderr.write("Proceed? [y/N] ");
    const ans = (await readSingleLine()).toLowerCase();
    if (ans !== "y" && ans !== "yes") {
      ok("merge cancelled");
      return 0;
    }
  }

  try {
    const result = applyEntityMerge(vault, refs, {
      expectHash,
      bypassEntityGuard: force,
      now: new Date(),
      agent,
    });
    if (json) {
      okJson({
        applied: true,
        keep_id: result.plan.keep_id,
        drop_id: result.plan.drop_id,
        alias_added: result.plan.alias_added,
        body_folded: result.plan.body_folded,
        dropped_path: result.dropped_path,
        plan_hash: result.verified_hash,
        snapshot_run_id: result.snapshot_run_id,
        snapshot_path: result.snapshot_path,
      });
    } else {
      ok(`merged: ${result.plan.drop_id} -> ${result.plan.keep_id}`);
      if (result.plan.alias_added !== null) ok(`  alias added: ${result.plan.alias_added}`);
      ok(`  recovery point: snapshot ${result.snapshot_run_id}`);
      if (result.snapshot_path) info(`    ${result.snapshot_path}`);
    }
    return 0;
  } catch (exc) {
    return entityMergeRefusal(exc, json);
  }
}