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
15.2 KB
Raw Blame
/**
 * Canonical entity registry hygiene (Memory Integrity Suite).
 *
 * Write seams refuse duplicates, so anything reported here arrived
 * through hand edits or sync merges - observable, never auto-deleted.
 */

import { join } from "node:path";
import { readFileSync } from "node:fs";

import {
  entityLexicalAliasCandidates,
  resolveEntitySemanticDedupConfig,
  type EntityAliasCandidate,
} from "../entities/semantic-dedup.ts";
import {
  anyDiffersOnlyByQuoteVariant,
  ENTITY_QUOTE_VARIANT_CAUSE,
  ENTITY_QUOTE_VARIANT_COLLISION_CODE,
  normalizeEntityName,
} from "../entities/canonical.ts";
import {
  buildEntityIndex,
  conflictClaimants,
  ENTITY_CONFLICT_KIND,
  type EntityIndex,
} from "../entities/index-builder.ts";
import { PERSON_NICKNAMES_ARTIFACT_REL } from "../entities/person-nicknames.ts";
import { isPersonCategory } from "../entities/person-variants.ts";
import { resolvePersonDerivedIndex, type PersonDerivedIndex } from "../entities/registry.ts";
import { findMalformedEntityLabels } from "../entities/label-hygiene.ts";
import type { BrainEntity, EntityConflict } from "../entities/types.ts";
import type { DoctorCheck } from "./check.ts";

/**
 * The label each claimant contributed to the contested key: its canonical
 * name for a name conflict, and the alias that matched for an alias one.
 *
 * `EntityConflict` carries `{kind, key, paths}` and not the raw labels,
 * which is the right shape for a finding about FILES - and it is also why
 * the cause has to be re-derived here. The alternative, widening the
 * shared record with the claimed forms, would put presentation data on a
 * type the index builder, the registry's write refusal and both doctor
 * surfaces all pass around, to serve one message. The paths are already
 * in the conflict and the index already holds the records, so this costs
 * a lookup instead.
 */
function claimedForms(index: EntityIndex, conflict: EntityConflict): string[] {
  const claimants: ReadonlyArray<BrainEntity> = conflictClaimants(index, conflict);
  if (conflict.kind === ENTITY_CONFLICT_KIND.duplicateName) {
    return claimants.map((c) => c.name);
  }
  return claimants.map(
    (c) => c.aliases.find((a) => normalizeEntityName(a) === conflict.key) ?? c.name,
  );
}

/** Doctor code of an unusable operator nickname map. */
export const PERSON_NICKNAMES_UNREADABLE_CODE = "person-nicknames-unreadable";

/** Doctor code of a proposal-only alias-merge candidate. */
export const ENTITY_ALIAS_CANDIDATE_CODE = "entity-alias-candidate";

/**
 * The one alias-merge sentence both candidate kinds are written with.
 * Kept in a single home so the doctor's findings and the decision-model
 * annotator's message-matching can never drift apart.
 */
function aliasMergeCandidateMessage(
  nameA: string,
  idA: string,
  nameB: string,
  idB: string,
  method: string,
  similarity: number | string,
): string {
  return (
    `possible alias-merge: '${nameA}' (${idA}) ~ '${nameB}' (${idB}) ` +
    `[${method} ${similarity}]. Review and add an alias to merge — never auto-merged.`
  );
}

/**
 * The doctor message of one alias-merge candidate. Shared with the
 * decision-model annotator (`entities/alias-verdicts.ts`), which matches
 * the doctor's issues back to their candidates by this exact text.
 */
export function entityAliasCandidateMessage(c: EntityAliasCandidate): string {
  return aliasMergeCandidateMessage(c.name_a, c.a, c.name_b, c.b, c.method, c.similarity);
}

/**
 * The doctor message of one DERIVED-VARIANT collision
 * (write-honesty-egress-consent, F3/C5): the same alias-merge shape,
 * with a `person-variant` method label. The similarity is 1 because the
 * collision is exact - the derived form equals the other record's
 * declared form byte-for-byte after normalization. The method label
 * differs from every lexical/embedding candidate's, so the annotator's
 * by-message match simply never pairs this finding with one.
 */
export function personVariantCollisionMessage(a: BrainEntity, b: BrainEntity): string {
  const [first, second] = a.id.localeCompare(b.id) <= 0 ? [a, b] : [b, a];
  return aliasMergeCandidateMessage(
    first.name,
    first.id,
    second.name,
    second.id,
    "person-variant",
    1,
  );
}

/**
 * Every pair of canonical PERSON records where a derived variant of one
 * equals a DECLARED form (name or alias) of the other
 * (write-honesty-egress-consent, F3/C5). Lookups stay exact-declared-
 * first, so nothing mis-resolves today - but the registry holds two
 * records answering to one form, and that is the same latent alias-merge
 * the candidates above nominate, so it is reported through the same
 * warning. Exactly one finding per unordered pair, however many variants
 * collide and whichever side derives.
 *
 * A form shared only as a DERIVED form on both sides is not a collision:
 * neither record declared it, so the collision scan has nothing to offer
 * the merge that the ambiguity error at lookup time does not already
 * say better.
 *
 * The join runs over the shared derived person-form index: one pass over
 * its per-form claimant lists, linear in forms times claimants, instead
 * of a variants-per-person rebuild inside an all-pairs loop.
 */
function derivedVariantCollisionMessages(derivedIndex: PersonDerivedIndex): string[] {
  const seenPairs = new Set<string>();
  const messages: string[] = [];
  for (const claimants of derivedIndex.byForm.values()) {
    if (claimants.derived.length === 0) continue;
    // The collision is person-to-person: the declared claimant lane also
    // carries non-person records (every canonical entity claims its
    // declared forms there), and a person's nickname matching an org's
    // name is not the alias-merge this scan nominates.
    for (const deriver of claimants.derived) {
      for (const claimant of claimants.declared) {
        if (deriver.id === claimant.id) continue;
        if (!isPersonCategory(claimant.category)) continue;
        const pairKey = [deriver.id, claimant.id].toSorted().join("\u0000");
        if (seenPairs.has(pairKey)) continue;
        seenPairs.add(pairKey);
        messages.push(personVariantCollisionMessage(deriver, claimant));
      }
    }
  }
  return messages;
}

/** Doctor code of a silently-skipped `person-nicknames.json` entry. */
export const PERSON_NICKNAMES_ENTRY_SKIPPED_CODE = "person-nicknames-entry-skipped";

/**
 * The entries of `person-nicknames.json` the parser keeps the file's
 * other entries running without - a nickname that normalizes to an
 * empty form, a value list with no usable name, a nickname equal to the
 * full name it stands for - as one warning per skipped entry, naming
 * the entry's POSITION (the same numbering the parser's shape errors
 * use). A nickname below the derived-form floor is NOT a skip: declared
 * nicknames are exempt from that floor by design.
 *
 * The doctor is the surfacing point for operator data faults, and a
 * silently dropped entry is one: the file resolves, the read lanes
 * report no degradation, and without this pass the entry would vanish.
 * The raw document is read here because the shared reader deliberately
 * folds the skipped entries away. A file that is missing, unreadable or
 * unparseable reports nothing here - the unreadable warning or the
 * quiet missing-file posture already covers it.
 */
function personNicknameSkippedEntryWarnings(vault: string): string[] {
  const path = join(vault, PERSON_NICKNAMES_ARTIFACT_REL);
  let parsed: unknown;
  try {
    parsed = JSON.parse(readFileSync(path, "utf8"));
  } catch {
    return [];
  }
  if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) return [];
  const messages: string[] = [];
  let entryIndex = 0;
  for (const [rawKey, rawValue] of Object.entries(parsed as Record<string, unknown>)) {
    entryIndex += 1;
    const nick = normalizeEntityName(rawKey);
    if (!nick) {
      messages.push(
        `person-nicknames entry #${entryIndex} is skipped: the nickname normalizes to an ` +
          "empty form and can never resolve.",
      );
      continue;
    }
    if (!Array.isArray(rawValue)) continue; // the parser raises an unreadable-config fault for this
    const values = rawValue
      .filter((v): v is string => typeof v === "string")
      .map((v) => normalizeEntityName(v))
      .filter((v) => v !== "");
    if (values.length === 0) {
      messages.push(
        `person-nicknames entry #${entryIndex} is skipped: none of its values normalizes ` +
          "to a name, so the nickname stands for no one.",
      );
      continue;
    }
    if (values.includes(nick)) {
      messages.push(
        `person-nicknames entry #${entryIndex} never resolves: the nickname is one of the ` +
          "full names it stands for, so it adds no form.",
      );
    }
  }
  return messages;
}

/** `ent-a (path-a), ent-b (path-b)` - the records, not just their files. */
function describeClaimants(index: EntityIndex, conflict: EntityConflict): string {
  return conflictClaimants(index, conflict)
    .map((c) => `${c.id} (${c.path})`)
    .join(", ");
}

/**
 * `duplicate-entity` / `entity-quote-variant-collision` /
 * `broken-entity-relation`: duplicates come straight from the index
 * builder's conflict report; broken relations are edges whose target
 * resolves to no entity id in the registry.
 *
 * The duplicate report is split by CAUSE, because the two halves have
 * different exits and `doctor-exits.ts` may only publish one answer per
 * code. A duplicate that arrived by hand edit or sync merge has no single
 * command - which of the two files keeps the identity is a reading of
 * both - and is written up that way. A duplicate the quote fold created
 * has one: the records were distinct identities under the previous
 * binary, nothing the operator did merged them, and archiving either one
 * ends the collision. That is the code registered in `DIAGNOSTIC_SIGNALS`,
 * and this is what produces it - every doctor surface resolves a finding's
 * code through the advisory rail, so the command reaches the operator from
 * the registry rather than from a sentence spelled here.
 */
export const entityRegistryCheck: DoctorCheck = {
  failSoft: true,
  run({ vault }, { issues }) {
    const index = buildEntityIndex(vault);
    if (index.entities.length === 0 && index.conflicts.length === 0) return;

    for (const conflict of index.conflicts) {
      const subject = conflict.kind === ENTITY_CONFLICT_KIND.duplicateName ? "identity" : "alias";
      if (anyDiffersOnlyByQuoteVariant(claimedForms(index, conflict))) {
        issues.push({
          severity: "warning",
          code: ENTITY_QUOTE_VARIANT_COLLISION_CODE,
          message:
            `${subject} '${conflict.key}' is claimed by ${conflict.paths.length} entity ` +
            `records: ${describeClaimants(index, conflict)}. They were distinct identities ` +
            `before the identity kernel folded typographic quote variants - ` +
            `${ENTITY_QUOTE_VARIANT_CAUSE}. Archive the record you do not keep.`,
        });
        continue;
      }
      issues.push({
        severity: "warning",
        code: "duplicate-entity",
        message:
          `${subject} '${conflict.key}' is ` +
          `claimed by ${conflict.paths.length} entity files: ${conflict.paths.join(", ")}. ` +
          "Merge them or archive the duplicates - lookups resolve to the first claimant only.",
      });
    }

    const knownIds = new Set(index.entities.map((e) => e.id));
    for (const entity of index.entities) {
      for (const edge of entity.relations) {
        if (knownIds.has(edge.target)) continue;
        issues.push({
          severity: "warning",
          code: "broken-entity-relation",
          path: entity.path,
          message:
            `${entity.id} declares '${edge.relation}: [[${edge.target}]]' but no entity ` +
            "with that id exists in the registry.",
        });
      }
    }

    // A1 (t_657b365e): surface stored nodes whose labels fail the quality
    // gate (structurally junk after decoration stripping, or operator-
    // denylisted) as prune candidates. Warning severity - the operator runs
    // `o2b brain entity prune` (dry-run default) to review and remove them.
    for (const malformed of findMalformedEntityLabels(vault)) {
      issues.push({
        severity: "warning",
        code: "entity-label-malformed",
        path: malformed.path,
        message:
          `${malformed.id} has a malformed label ${JSON.stringify(malformed.name)} ` +
          `(${malformed.reason}). Review with 'o2b brain entity prune' and re-run with ` +
          "--confirm to remove the node and its edges behind a snapshot.",
      });
    }

    // write-honesty-egress-consent (F3/C5): a derived person variant of
    // one person that equals another person's declared form. Same
    // warning as the candidates below - it nominates the same remedy -
    // but deterministic and always on, like the lints above. Unlike the
    // conflict findings above, which deliberately read what is STORED
    // (scoping them would stop the doctor reporting on exactly the
    // records a read path hides), this scan and the malformed-label scan
    // resolve through the shared canonical predicate: a quarantined
    // person's variants nominate no merges.
    // An unusable nickname file degrades this scan to no derived
    // collisions rather than discarding the check - the read lanes keep
    // their documented degradations too - but the doctor is the
    // surfacing point: a present-yet-unusable operator file is one
    // warning, naming the path, with the error's own short
    // (position-only) detail. Entries the parser folds away silently
    // surface beside it, one warning each, by position.
    const derivedIndex = resolvePersonDerivedIndex(vault);
    if (derivedIndex.nicknameError !== null) {
      issues.push({
        severity: "warning",
        code: PERSON_NICKNAMES_UNREADABLE_CODE,
        path: derivedIndex.nicknameError.path,
        message:
          `the person nickname map at ${derivedIndex.nicknameError.path} is unusable and ` +
          `nickname-derived lookups run without it: ${derivedIndex.nicknameError.detail}`,
      });
    }
    for (const message of personNicknameSkippedEntryWarnings(vault)) {
      issues.push({
        severity: "warning",
        code: PERSON_NICKNAMES_ENTRY_SKIPPED_CODE,
        path: join(vault, PERSON_NICKNAMES_ARTIFACT_REL),
        message,
      });
    }
    for (const message of derivedVariantCollisionMessages(derivedIndex)) {
      issues.push({
        severity: "warning",
        code: ENTITY_ALIAS_CANDIDATE_CODE,
        message,
      });
    }

    // semantic-retrieval-precision (t_47fd9523): opt-in, proposal-only
    // alias-merge candidates. Off by default → this block is a no-op and
    // the report is byte-identical to the baseline. The doctor is
    // synchronous and embeds nothing, so it uses the deterministic lexical
    // (jaccard-over-names) layer; the embedding layer lives on the CLI/MCP
    // reader. Candidates are NOMINATIONS — never an auto-merge.
    const dedupCfg = resolveEntitySemanticDedupConfig();
    if (dedupCfg.enabled) {
      for (const c of entityLexicalAliasCandidates(vault, {
        threshold: dedupCfg.lexicalThreshold,
      })) {
        issues.push({
          severity: "warning",
          code: ENTITY_ALIAS_CANDIDATE_CODE,
          message: entityAliasCandidateMessage(c),
        });
      }
    }
  },
};