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
9.9 KB
Raw Blame
/**
 * Grounded agent-stated claim core (truth-correctable-time-aware,
 * task 4): the bridge from an agent's stated claims
 * (`{ subject, relation, object }` plus the assertion `text` they came
 * from) into claim-ledger events.
 *
 * Two boundaries govern the path, with different strictness:
 *
 *   - The payload boundary refuses WHOLE calls: an unknown relation
 *     (validated against the single relation vocabulary), missing text,
 *     missing source, an empty agent or a malformed ts throws
 *     {@link StatedClaimsRefusal} before anything is written.
 *   - The anchoring verdict is PER CLAIM, using the one occurrence
 *     kernel {@link anchorEntityForms} (quality-gated normalized match
 *     forms, minimum length 3): a claim whose subject and object both
 *     anchor in the text commits with `extractor: "agent_stated"`; an
 *     ungrounded claim is reported back with machine reason codes.
 *     The store-learned lexicon is resolved beside the gate
 *     (`resolveEntityLexicon`, fail-open null), so a verdict here
 *     never anchors a form the creation gate refuses; with no fresh
 *     artifact every verdict is byte-identical to the pre-lexicon
 *     behavior.
 *     Per-claim partial commit is safe here because each event is an
 *     independent append in an append-only ledger and the outcome
 *     reports exactly what landed.
 *
 * The extractor tag is annotation only: conflict detection reads the
 * ledger exactly as before and the tag never re-ranks or resolves a
 * conflict. Naming deliberately avoids "grounding", which is taken by
 * the source-diversity score in `truth/grounding.ts` - verdicts here
 * speak of anchoring.
 */

import { isKnownRelation, normalizeRelation } from "../../graph/relation-vocab.ts";
import { anchorEntityForms, type AtomicEntityLike } from "../atomic-facts.ts";
import { normalizeEntityName, type EntityLexiconHandle } from "../entities/canonical.ts";
import { resolveEntityLexicon } from "../entities/lexicon.ts";
import type { AppendClaimInput, AppendClaimResult } from "./store.ts";
import {
  appendClaimEvent,
  ISO_UTC_TS_RE,
  isValidClaimSampleId,
  SAMPLE_ID_MAX_LENGTH,
} from "./store.ts";
import type { ClaimExtractor } from "./types.ts";

/** How this release tags agent-stated claims. */
const AGENT_STATED: ClaimExtractor = "agent_stated";

/** One stated claim: subject, typed relation, object. */
export interface StatedClaim {
  readonly subject: string;
  readonly relation: string;
  readonly object: string;
}

/** The payload the agent states, anchored by one shared assertion text. */
export interface StatedClaimsPayload {
  readonly claims: ReadonlyArray<StatedClaim>;
  /** The assertion text every claim must anchor in. */
  readonly text: string;
  readonly agent: string;
  /** Canonical ISO-8601 UTC timestamp for the committed events. */
  readonly ts: string;
  /** Provenance wikilink or vault-relative path. */
  readonly source: string;
  /**
   * Optional attribution id (answer-trust, task B2): the recall/
   * context-pack quality-sample id these claims were stated against.
   * Trimmed and shape-checked when present - non-empty, at most 256
   * characters, no control characters; anything else is a named
   * refusal, never coerced to absent - and threaded trimmed onto every
   * committed event as `sample_id` (the store stores the same trimmed
   * form). Opaque: treated as an opaque token end to end and never
   * logged beside answer or source text.
   */
  readonly sampleId?: string;
}

export interface StatedClaimsOptions {
  /**
   * Registry entities whose aliases extend the anchoring forms: an
   * entity whose canonical name normalizes equal to a claim's subject
   * or object contributes its full alias pool to that side.
   */
  readonly entities?: ReadonlyArray<AtomicEntityLike>;
  readonly configPath?: string;
  /**
   * The caller's reach gate over the payload's source page (see
   * `AppendClaimOptions.readableSource`): a source the caller cannot
   * read resolves no frontmatter window, exactly like an absent one.
   * Absent at operator reach.
   */
  readonly readableSource?: (rel: string) => boolean;
}

/** Machine-readable reason codes for an ungrounded claim. */
export type StatedClaimRefusalReason =
  | "missing_subject"
  | "missing_object"
  | "subject_unanchored"
  | "object_unanchored";

/** A claim that was reported back instead of committed. */
export interface UngroundedStatedClaim {
  readonly claim: StatedClaim;
  readonly reasons: ReadonlyArray<StatedClaimRefusalReason>;
}

export interface StatedClaimsOutcome {
  /** What landed, in payload order. */
  readonly committed: ReadonlyArray<AppendClaimResult>;
  /** What was reported back, in payload order. */
  readonly ungrounded: ReadonlyArray<UngroundedStatedClaim>;
}

/** The payload boundary's typed refusal. Nothing has been written. */
export class StatedClaimsRefusal extends Error {
  constructor(message: string) {
    super(message);
    this.name = "StatedClaimsRefusal";
  }
}

/**
 * The anchoring forms for one claimed side: the stated value itself,
 * plus the alias pool of a registry entity whose canonical name
 * normalizes equal to it.
 */
function statedAnchorForms(
  value: string,
  entities: ReadonlyArray<AtomicEntityLike>,
): ReadonlyArray<string> {
  const normalized = normalizeEntityName(value);
  for (const entity of entities) {
    if (normalizeEntityName(entity.name) === normalized) {
      return [value, ...entity.aliases];
    }
  }
  return [value];
}

/** Per-claim anchoring verdict: why the claim cannot commit, if it cannot. */
function ungroundedReasons(
  claim: StatedClaim,
  text: string,
  entities: ReadonlyArray<AtomicEntityLike>,
  lexicon: EntityLexiconHandle | null,
): ReadonlyArray<StatedClaimRefusalReason> {
  const reasons: StatedClaimRefusalReason[] = [];
  if (normalizeEntityName(claim.subject) === "") {
    reasons.push("missing_subject");
  } else if (
    anchorEntityForms(text, statedAnchorForms(claim.subject, entities), { lexicon }).length === 0
  ) {
    reasons.push("subject_unanchored");
  }
  if (claim.object.trim() === "") {
    reasons.push("missing_object");
  } else if (
    anchorEntityForms(text, statedAnchorForms(claim.object, entities), { lexicon }).length === 0
  ) {
    reasons.push("object_unanchored");
  }
  return reasons;
}

/**
 * Validate the payload boundary, commit the grounded claims as ledger
 * events, and report the ungrounded ones back. Refused payloads write
 * nothing; anchoring verdicts are per claim. The outcome reports
 * exactly what landed, in payload order on both sides.
 */
export function appendStatedClaims(
  vault: string,
  payload: StatedClaimsPayload,
  opts: StatedClaimsOptions = {},
): StatedClaimsOutcome {
  const source = payload.source.trim();
  if (source === "") {
    throw new StatedClaimsRefusal("stated claims: source is required");
  }
  if (payload.text.trim() === "") {
    throw new StatedClaimsRefusal("stated claims: text is required");
  }
  for (const claim of payload.claims) {
    if (!isKnownRelation(claim.relation)) {
      throw new StatedClaimsRefusal(
        `stated claims: unknown relation: ${JSON.stringify(claim.relation)}`,
      );
    }
  }
  // The whole-call promise covers every field the committed events
  // carry: an empty agent or a malformed ts must refuse HERE, through
  // the typed refusal channel, before the first write - not surface
  // mid-loop as the store's plain error outside the documented refusal
  // channel.
  if (payload.agent.trim() === "") {
    throw new StatedClaimsRefusal("stated claims: agent is required");
  }
  if (!ISO_UTC_TS_RE.test(payload.ts)) {
    throw new StatedClaimsRefusal(
      `stated claims: ts must be canonical ISO-8601 UTC: ${JSON.stringify(payload.ts)}`,
    );
  }
  // Sample id (answer-trust, task B2): presence-gated, part of the
  // whole-call promise. The value is trimmed and must pass the same
  // shape check the store append applies - non-empty, at most 256
  // characters, no control characters (review L2.1) - so an unacceptable
  // id refuses HERE, before the first write, through the typed refusal
  // channel like the agent and ts checks above, never coerced to absent
  // and never surfacing mid-loop as the store's plain error.
  const sampleId = payload.sampleId === undefined ? undefined : payload.sampleId.trim();
  if (sampleId !== undefined && !isValidClaimSampleId(sampleId)) {
    throw new StatedClaimsRefusal(
      `stated claims: sample_id must be a non-empty string of at most ${SAMPLE_ID_MAX_LENGTH} characters without control characters`,
    );
  }

  const entities = opts.entities ?? [];
  // The same store-learned lexicon the creation gate resolves (fail-open
  // null), threaded into the shared anchoring kernel so a stated value
  // whose only forms the gate refuses is reported unanchored exactly as
  // the creation boundary refuses it (recall-quality M6). No artifact,
  // and every verdict is byte-identical to the pre-lexicon behavior.
  const lexicon = resolveEntityLexicon(vault);
  const committed: AppendClaimResult[] = [];
  const ungrounded: UngroundedStatedClaim[] = [];
  for (const claim of payload.claims) {
    const reasons = ungroundedReasons(claim, payload.text, entities, lexicon);
    if (reasons.length > 0) {
      ungrounded.push(Object.freeze({ claim, reasons: Object.freeze(reasons) }));
      continue;
    }
    const input: AppendClaimInput = {
      ts: payload.ts,
      agent: payload.agent,
      entity: normalizeEntityName(claim.subject),
      aspect: normalizeRelation(claim.relation),
      value: claim.object.trim(),
      extractor: AGENT_STATED,
      source,
      ...(sampleId !== undefined ? { sample_id: sampleId } : {}),
    };
    committed.push(
      appendClaimEvent(vault, input, {
        configPath: opts.configPath,
        ...(opts.readableSource !== undefined ? { readableSource: opts.readableSource } : {}),
      }),
    );
  }
  return Object.freeze({
    committed: Object.freeze(committed),
    ungrounded: Object.freeze(ungrounded),
  });
}