Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript
5.8 KB
Raw Blame
/**
 * Saved facts about the entity a search names. Facts saved with `remember`
 * live in the facts table, not in page chunks, so a search whose words differ
 * from the fact's ("discount code for ONSO" against "Ondresso Systems is being
 * folded into Dovalto Energy") never found them by word overlap, and agents
 * answered from older documents instead of the newer saved correction.
 *
 * When the query names an entity (search/alias-fanout.ts), its newest active
 * facts (also those saved under an identity sibling or its bare name) are
 * returned first. One hop: an entity a returned fact names ("folded into
 * Dovalto Energy", "uses Dovalto Energy's discount code") contributes its own
 * newest facts, tagged `linked_from`, so a redirection reaches the value it
 * points to. Same source scope, active-fact, visibility and read-eligibility
 * rules as recall (quarantined-page and needs_rederive facts hidden, the
 * caller's trust floor applied),
 * and recall's collapse (#7043): copies of one claim read as one fact, before
 * the caps, so they never crowd out a distinct one.
 */

import type { BrainEngine } from '../engine.ts';
import { AUDIT_ROW_SOURCES } from '../facts/audit-sources.ts';
import { privateFactFilterForReader, worldOnlyFacts } from './private-visibility.ts';
import { grantedPrivateFactSql } from '../access/member-facts.ts';
import { factEntitySlugs } from '../mentions/siblings.ts';
import { resolveQueryEntities, type ResolvedEntity } from './alias-fanout.ts';
import { collapseFactReads } from '../facts/capture-dedup.ts';
import type { FactAttribution } from '../engine.ts';
import { projectionEligibleSql } from '../eligibility/sql.ts';
import type { TrustTier } from '../trust/tier.ts';

export const ENTITY_FACTS_CAP = 5;
export const LINKED_FACTS_CAP = 3;
const LINKED_ENTITIES_CAP = 2;

export interface EntityFact { id: number; fact: string; entity_slug: string | null; kind: string; valid_from: string; source: string; linked_from?: string;
  /** #7043: every entity of the copies this row stands for, and how many rows it stands for. */
  entity_slugs?: string[]; collapsed_count?: number }

/** Rows read per cap so copies of one claim collapse before the cap (#7043). */
export const SAVED_FACTS_COLLAPSE_WINDOW = 50;
/** The columns the collapse reads besides a saved fact's own; `stripCollapseColumns` drops them from the response. */
export const SAVED_FACT_COLLAPSE_COLUMNS = 'f.source_id, f.visibility, f.created_at, f.attributed_to, gbrain_fact_fingerprint(f.fact) AS fact_fingerprint';
export type CollapseColumns = { source_id: string; visibility: string; created_at: Date | string; attributed_to: FactAttribution | null; fact_fingerprint: string };

/** A saved fact as the response carries it, without the collapse columns and member ids. */
export function stripCollapseColumns<T extends CollapseColumns & { collapsed_ids?: number[] }>({ source_id: _s, visibility: _v, created_at: _c, attributed_to: _a, fact_fingerprint: _f, collapsed_ids: _i, ...rest }: T): Omit<T, keyof CollapseColumns | 'collapsed_ids'> {
  return rest;
}

async function newestFacts(engine: BrainEngine, sourceId: string, slugs: string[], opts: { remote: boolean; minTrust?: TrustTier }, limit: number): Promise<Array<EntityFact & CollapseColumns>> {
  const visibility = opts.remote ? `${worldOnlyFacts(opts.remote) ? `AND (f.visibility = 'world' OR ${grantedPrivateFactSql('f')})` : ''} AND ${privateFactFilterForReader('f')}` : '';
  const rows = await engine.executeRaw<EntityFact & CollapseColumns>(
    `SELECT f.id, f.fact, f.entity_slug, f.kind, f.valid_from::text AS valid_from, f.source, ${SAVED_FACT_COLLAPSE_COLUMNS}
       FROM facts f
      WHERE f.source_id = $1 AND f.entity_slug = ANY($2::text[])
        AND f.expired_at IS NULL AND (f.valid_until IS NULL OR f.valid_until > now())
        AND f.source != ALL($3::text[])
        ${visibility}
        AND ${projectionEligibleSql('facts', 'f', { floor: opts.minTrust })}
      ORDER BY f.valid_from DESC, f.id DESC
      LIMIT ${SAVED_FACTS_COLLAPSE_WINDOW}`,
    [sourceId, slugs, [...AUDIT_ROW_SOURCES]]);
  return (await collapseFactReads(engine, rows.map(r => ({ ...r, id: Number(r.id) })))).slice(0, limit);
}

/** The named entity's newest facts, then those of entities its facts name, with the collapse columns. Fail-soft: errors return []. */
export async function entitySavedFacts(engine: BrainEngine, entity: ResolvedEntity, opts: { remote: boolean; excludePrivate: boolean; minTrust?: TrustTier }): Promise<Array<EntityFact & CollapseColumns>> {
  try {
    const sourceId = entity.pages[0]!.source_id;
    const own = new Set<string>();
    for (const p of entity.pages) for (const s of await factEntitySlugs(engine, sourceId, p.slug, { excludePrivate: opts.excludePrivate })) own.add(s);
    const facts = await newestFacts(engine, sourceId, [...own], opts, ENTITY_FACTS_CAP);
    const out: Array<EntityFact & CollapseColumns> = [...facts];
    const seenEntities = new Set(own);
    let linked = 0;
    for (const f of facts) {
      if (linked >= LINKED_ENTITIES_CAP) break;
      for (const other of await resolveQueryEntities(engine, f.fact, { sourceId, excludePrivate: opts.excludePrivate })) {
        if (linked >= LINKED_ENTITIES_CAP || other.pages.some(p => seenEntities.has(p.slug))) continue;
        const slugs = new Set<string>();
        for (const p of other.pages) for (const s of await factEntitySlugs(engine, sourceId, p.slug, { excludePrivate: opts.excludePrivate })) slugs.add(s);
        if ([...slugs].some(s => seenEntities.has(s))) continue;
        for (const s of slugs) seenEntities.add(s);
        linked++;
        for (const g of await newestFacts(engine, sourceId, [...slugs], opts, LINKED_FACTS_CAP)) {
          if (!out.some(x => x.id === g.id)) out.push({ ...g, linked_from: f.entity_slug ?? entity.pages[0]!.slug });
        }
      }
    }
    return out;
  } catch {
    return [];
  }
}