Garry's Opinionated OpenClaw/Hermes Agent Brain
TypeScript
/**
* Temporal typed edges — deterministic evidence derivation (zero LLM).
*
* Given one page's content and the derived link rows it owns, produce:
* - the tense of each owned assertion row ('past' when every compiled-truth
* mention of the other endpoint carries a past-tense cue such as
* "previously at", "former CTO of"; otherwise 'present');
* - dated transitions: cue-bearing timeline lines ("- **2025-03-01** | left
* [Acme](...)"), the explicit grammar ("Ended works_at [[companies/acme]]",
* "Started advises [[companies/acme]]") inside a dated timeline entry, and
* `since:` / `until:` keys on relationship frontmatter objects.
*
* Natural cues only date relationships the page already asserts (an owned
* row of a matching state/event type); they never create a relationship.
* The explicit grammar is a full statement on its own: it names the relation
* and the target, so a closure survives even after the stale positive
* sentence is deleted. Lines whose timeline source label starts with
* `gbrain-dream` carry producer 'dream' (an applied contradiction proposal).
*
* Contract and examples: docs/guides/temporal-edges.md.
*/
import { createHash } from 'node:crypto';
import {
relationSemantics, normalizePartialDate, type AssertionTense, type DatePrecision,
type TransitionKind, type TransitionProducer,
} from './link-validity.ts';
import { KNOWN_LINK_TYPES } from './search/relational-intent.ts';
import { U4_NOT_EMPLOYMENT_ROLE, typingUnitEnabled } from './link-typing-units.ts';
export interface OwnedRow {
from_slug: string;
to_slug: string;
link_type?: string;
link_source?: string | null;
origin_field?: string | null;
}
export interface DerivedTransition {
from_slug: string;
to_slug: string;
link_type: string;
kind: TransitionKind;
occurred_on: string;
date_precision: DatePrecision;
producer: Extract<TransitionProducer, 'timeline' | 'explicit' | 'frontmatter' | 'dream'>;
line_hash: string;
}
export interface TemporalEvidence {
/** Tense per owned row, keyed by rowKey(). */
tense: Map<string, AssertionTense>;
transitions: DerivedTransition[];
/** Explicit-grammar lines whose relation or target could not be used. */
unmatched: Array<{ line: string; reason: 'not_temporal' | 'event_cannot_end' | 'no_target' }>;
}
export const rowKey = (r: Pick<OwnedRow, 'from_slug' | 'to_slug' | 'link_type'>) => `${r.from_slug}\0${r.to_slug}\0${r.link_type ?? ''}`;
// ─── Cue lexicon ─────────────────────────────────────────────────────────
// Each pattern is anchored at the END of the text just before a reference to
// the other endpoint, so the nearest phrase decides ("Left [Wisp] to join
// [Helix]": end for Wisp, start for Helix).
const ROLE = String.raw`(?:[\w&./-]+\s+){0,4}?`;
/** Role phrases that describe a change inside the job ("was promoted to CTO at"), not a past job. */
const NOT_PAST_ROLE = String.raw`(?!(?:promoted|hired|named|appointed|made|elected|brought|recently|just|newly|now|still|currently)\b)`;
/** Present perfect ("has worked at", "have spent years at") describes a job that is still going. */
const NOT_PERFECT = String.raw`(?<!\b(?:has|have|'s|’s)\s+(?:\w+\s+)?)`;
const OWNED = String.raw`(?:(?:her|his|their|my|the)\s+)?(?:time|stint|tenure|role|job|run)\s+`;
/** Employment start cues; `notJob` guards the "became … at/of" and "took … role at" forms (U4). */
// nosemgrep: javascript.lang.security.audit.detect-non-literal-regexp.detect-non-literal-regexp -- notJob is only '' or the module-level literal U4_NOT_EMPLOYMENT_ROLE, both fixed at load; no caller input reaches the pattern
const employmentStart = (notJob: string) => new RegExp(String.raw`\b(?:(?:re-?)?join(?:ed|s|ing)?(?:\s+${ROLE}(?:at|as))?|(?:was\s+)?hired\s+(?:by|at|as\s+${ROLE}at)|started\s+(?:at|with|working\s+(?:at|for)|(?:a\s+)?new\s+(?:role|job|position)\s+at)|became\s+${notJob}${ROLE}(?:at|of)|promoted\s+to\s+${ROLE}(?:at|of)|signed\s+on\s+(?:at|with)|named\s+${ROLE}(?:at|of)|accepted\s+(?:an?\s+)?(?:offer|role|position|job)\s+(?:at|with|from)|took\s+(?:an?\s+|the\s+)?${notJob}(?:\w+\s+){0,2}?(?:role|job|position)\s+(?:at|with)|came\s+(?:on\s+board|aboard)\s+(?:at|with)|went\s+to\s+work\s+(?:at|for)|returned\s+to)\s*$`, 'i');
const EMPLOYMENT = {
end: new RegExp(String.raw`\b(?:left|leaving|departed(?:\s+from)?|quit|resigned(?:\s+as\s+${ROLE})?(?:\s+from|\s+at)?|stepped\s+down(?:\s+as\s+${ROLE})?(?:\s+from|\s+at)?|stepped\s+away\s+from|moved\s+on\s+from|(?:moved|switched|transitioned|jumped)\s+(?:over\s+|out\s+)?from|(?:was\s+)?laid\s+off\s+(?:from|by|at)|(?:was\s+)?let\s+go\s+(?:from|by)|(?:was\s+)?fired\s+(?:from|by)|no\s+longer\s+(?:at|with|works\s+at|working\s+at)|exited|parted\s+ways\s+with|retired\s+from|(?:wrapped\s+up|finished|ended|concluded)\s+(?:${OWNED})?(?:at|with)|last\s+day\s+at|departure\s+from)\s*$`, 'i'),
start: employmentStart(''),
past: new RegExp(String.raw`\b(?:previously(?:\s+worked)?\s+(?:at|with|for)|formerly(?:\s+${ROLE})?\s*(?:at|of|with)|former\s+${ROLE}(?:at|of|with)|ex-[\w-]+\s+(?:at|of)|used\s+to\s+work\s+(?:at|for)|${NOT_PERFECT}worked\s+(?:at|for|with)|${NOT_PERFECT}spent\s+(?:[\w-]+\s+){1,4}?(?:at|with)|(?:his|her|their|my)\s+(?:time|stint|tenure)\s+at|stint\s+at|was\s+${NOT_PAST_ROLE}${ROLE}(?:at|of)|alum(?:nus|na|ni)?\s+of)\s*$`, 'i'),
};
/**
* Lines about investing, meetings or events mention organizations without
* changing anyone's job ("joined Acme's Series B", "back at Acme for an
* alumni dinner"). Natural cues on such lines never start or end a state
* relationship; only the explicit grammar does.
*/
const EVENT_CONTEXT = /\b(?:invest(?:ed|s|ing|or|ors|ment)?|angel|check|cap\s+table|round|seed|series\s+[a-z]|bridge|portfolio|fund(?:ing|raise)|alumni|alums?|reunion|dinner|lunch|breakfast|coffee|drinks|met\s+(?:with|up)|meet(?:ing|up)s?|panel|talk|keynote|conference|summit|event|offsite|party|visit(?:ed|ing)?|interview(?:ed|s|ing)?|demo\s+day|podcast|webinar|office\s+hours|hackathon|speaker|spoke|guest)\b/i;
/** "[Acme]'s advisory board": the one qualified reference that is about the relation itself (advises). */
const ADVISORY_BOARD_AFTER = /^\s*(?:'s|’s)\s+(?:advisory\s+board|board\s+of\s+advisors)\b/i;
/** After a reference: a possessive or a qualifying noun means the line is about something of the organization's, not the organization. */
const QUALIFIED_AFTER = /^(?:\s*(?:'s|’s)|\s+(?:alumni|alums?|investors?|board|round|event|team\s+event|community|network|office|campus))\b/i;
const ADVISORY = {
end: /\b(?:stepped\s+down\s+as\s+(?:an?\s+)?(?:\w+\s+)?advisor\s+(?:to|at|of|for)|left\s+(?:the\s+)?advisory\s+board\s+(?:of|at)|no\s+longer\s+advis(?:es|ing)|stopped\s+advising|ended\s+(?:the\s+|(?:his|her|their)\s+)?advisory\s+(?:role|work)\s+(?:with|at|for))\s*$/i,
start: /\b(?:joined\s+(?:the\s+)?advisory\s+board\s+(?:of|at)|became\s+(?:an?\s+)?(?:\w+\s+)?advisor\s+(?:to|at|of|for)|started\s+advising|began\s+advising)\s*$/i,
past: /\b(?:former\s+(?:\w+\s+)?advisor\s+(?:to|at|of|for)|previously\s+advised|used\s+to\s+advise|advised)\s*$/i,
};
const PARTNER = {
end: /\b(?:left|stepped\s+down\s+(?:as\s+(?:a\s+)?partner\s+)?(?:from|at))\s*$/i,
start: /\b(?:joined(?:\s+as\s+(?:a\s+)?(?:\w+\s+)?partner\s+at)?|became\s+(?:a\s+)?(?:\w+\s+)?partner\s+at)\s*$/i,
past: /\b(?:former\s+(?:\w+\s+)?partner\s+(?:at|of)|was\s+(?:a\s+)?(?:\w+\s+)?partner\s+at)\s*$/i,
};
const EVENT_START: Record<string, RegExp> = {
invested_in: /\b(?:invested\s+in|invests\s+in|backed|led\s+(?:the\s+)?(?:\w+\s+){0,3}?(?:round|investment|seed)\s+(?:in|for|of)|participated\s+in\s+(?:\w+\s+){0,3}?(?:round|seed)\s+(?:of|in|for)|wrote\s+(?:a|the|an)\s+(?:\w+\s+){0,2}?check\s+(?:to|for|into))\s*$/i,
led_round: /\b(?:led(?:\s+the)?(?:\s+\w+){0,3}?)\s*$/i,
founded: /\b(?:founded|co-?founded|started)\s*$/i,
};
/** U4 (src/core/link-typing-units.ts): the employment cues with advisory, board and investor roles kept out of the start cue. */
const EMPLOYMENT_U4 = { ...EMPLOYMENT, start: employmentStart(U4_NOT_EMPLOYMENT_ROLE) };
type CueSet = { end: RegExp; start: RegExp; past: RegExp };
function cuesFor(linkType: string): CueSet | null {
if (linkType === 'works_at') return typingUnitEnabled('U4') ? EMPLOYMENT_U4 : EMPLOYMENT;
if (linkType === 'advises') return ADVISORY;
if (linkType === 'yc_partner') return PARTNER;
return null;
}
// ─── References ──────────────────────────────────────────────────────────
/** Normalize a link target to a slug: strip ./ ../ prefixes, a .md suffix and an #anchor. */
export function normalizeLinkTarget(raw: string): string {
let s = raw.trim().replace(/[#?].*$/, '').replace(/\.md$/i, '');
while (s.startsWith('../') || s.startsWith('./')) s = s.replace(/^\.\.?\//, '');
return s.replace(/^\/+/, '');
}
interface RefHit { index: number; end: number; target: string }
const MD_LINK_RE = /\[[^\]\n]*\]\(([^)\s]+)(?:\s+"[^"]*")?\)/g;
const WIKI_LINK_RE = /\[\[([^\]|\n]+)(?:\|[^\]\n]*)?\]\]/g;
function referencesIn(text: string): RefHit[] {
const hits: RefHit[] = [];
for (const m of text.matchAll(MD_LINK_RE)) hits.push({ index: m.index!, end: m.index! + m[0].length, target: normalizeLinkTarget(m[1]) });
for (const m of text.matchAll(WIKI_LINK_RE)) hits.push({ index: m.index!, end: m.index! + m[0].length, target: normalizeLinkTarget(m[1].replace(/^[a-z0-9-]+:(?=[a-z])/i, '')) });
return hits.sort((a, b) => a.index - b.index);
}
/** Does a normalized link target point at `slug` (full path or unique basename form)? */
export function refersTo(target: string, slug: string): boolean {
if (target === slug) return true;
const base = slug.split('/').pop()!;
return !target.includes('/') && target.toLowerCase() === base.toLowerCase();
}
/** The clause right before a reference: back to the previous sentence/clause break or reference, max 90 chars. */
function windowBefore(text: string, index: number, prevRefEnd: number): string {
const start = Math.max(0, index - 90, prevRefEnd);
let w = text.slice(start, index);
const cut = Math.max(w.lastIndexOf('. '), w.lastIndexOf('; '), w.lastIndexOf('\n'), w.lastIndexOf(', and '));
if (cut >= 0) w = w.slice(cut + 1);
return w.replace(/\*\*|__|[*_`]/g, '');
}
// ─── Timeline lines ──────────────────────────────────────────────────────
const DATED_LINE_RE = /^\s*(?:[-*]\s*)?\*\*(\d{4}-\d{2}-\d{2})\*\*\s*[|\-–—]+\s*(.+?)\s*$/;
const DATED_HEADING_RE = /^\s*###\s+(\d{4}-\d{2}-\d{2})\s*[-–—]+\s*(.+?)\s*$/;
const EXPLICIT_RE = /\b(Started|Ended)\s+([a-z][a-z0-9_]*)\s+(?:\[\[([^\]|\n]+)(?:\|[^\]\n]*)?\]\]|\[[^\]\n]*\]\(([^)\s]+)\))/g;
/**
* "Started at [Acme]" is prose, not the grammar: the token after Started/Ended
* must name a relation (a known link type, a temporal type, or a snake_case
* identifier; non-temporal ones are reported).
*/
const isRelationToken = (token: string) => token.includes('_') || KNOWN_LINK_TYPES.has(token) || relationSemantics(token) !== 'reference';
const hasExplicit = (text: string) => [...text.matchAll(EXPLICIT_RE)].some(m => isRelationToken(m[2]));
export interface DatedLine { date: string; text: string; dream: boolean }
/** The dated timeline lines of `content` outside code fences. */
export function datedLines(content: string): DatedLine[] {
const out: DatedLine[] = [];
let fence = false;
for (const line of content.split('\n')) {
if (/^\s*(```|~~~)/.test(line)) { fence = !fence; continue; }
if (fence) continue;
const m = DATED_LINE_RE.exec(line) ?? DATED_HEADING_RE.exec(line);
if (!m || !normalizePartialDate(m[1])) continue;
out.push({ date: m[1], text: m[2], dream: /^gbrain-dream\b/i.test(m[2].trim()) });
}
return out;
}
export const lineHash = (s: string) => createHash('sha256').update(s).digest('hex').slice(0, 16);
// ─── Derivation ──────────────────────────────────────────────────────────
export interface PageForEvidence {
slug: string;
compiled_truth: string;
timeline: string;
frontmatter: Record<string, unknown> | null | undefined;
}
/** Receives each derived transition with the stable id of the cue that produced it (`cue.*`, `unit.*`). */
export type TransitionExplainer = (t: DerivedTransition, rule: string) => void;
/**
* What temporal evidence reads from a page body: the dated lines of the joined body and every reference in the
* compiled truth outside dated lines, with the clause before it. A segmented page collects them block by block.
*/
export interface TemporalInputs { lines: DatedLine[]; narrative: NarrativeRef[] }
export interface NarrativeRef { target: string; window: string }
/** The references of a compiled-truth text outside dated lines, each with the clause before it (windowBefore). */
export function narrativeRefs(truth: string): NarrativeRef[] {
const narrative = stripDatedLines(truth);
let prevEnd = 0;
return referencesIn(narrative).map(ref => {
const window = windowBefore(narrative, ref.index, prevEnd);
prevEnd = ref.index + 2;
return { target: ref.target, window };
});
}
export function deriveTemporalEvidence(page: PageForEvidence, rows: readonly OwnedRow[], explain?: TransitionExplainer): TemporalEvidence {
return temporalEvidenceFrom(page, { lines: datedLines(`${page.compiled_truth ?? ''}\n${page.timeline ?? ''}`), narrative: narrativeRefs(page.compiled_truth ?? '') },
rows, explain);
}
export function temporalEvidenceFrom(page: Pick<PageForEvidence, 'slug' | 'frontmatter'>, inputs: TemporalInputs, rows: readonly OwnedRow[],
explain?: TransitionExplainer): TemporalEvidence {
const tense = new Map<string, AssertionTense>();
const transitions: DerivedTransition[] = [];
const unmatched: TemporalEvidence['unmatched'] = [];
const { lines } = inputs;
const temporalRows = rows.filter(r => relationSemantics(r.link_type) !== 'reference');
const other = (r: OwnedRow) => (r.from_slug === page.slug ? r.to_slug : r.from_slug);
const seen = new Set<string>();
const push = (t: DerivedTransition, rule: string) => {
const k = `${t.from_slug}\0${t.to_slug}\0${t.link_type}\0${t.kind}\0${t.occurred_on}\0${t.producer}`;
if (!seen.has(k)) { seen.add(k); transitions.push(t); explain?.(t, rule); }
};
// 1. Explicit grammar inside dated timeline entries.
for (const line of lines) {
for (const m of line.text.matchAll(EXPLICIT_RE)) {
const linkType = m[2];
if (!isRelationToken(linkType)) continue;
const target = normalizeLinkTarget(m[3] ?? m[4] ?? '');
const semantics = relationSemantics(linkType);
if (!target) { unmatched.push({ line: line.text, reason: 'no_target' }); continue; }
if (semantics === 'reference') { unmatched.push({ line: line.text, reason: 'not_temporal' }); continue; }
if (semantics === 'event' && m[1] === 'Ended') { unmatched.push({ line: line.text, reason: 'event_cannot_end' }); continue; }
const resolved = target.includes('/') ? target : temporalRows.map(other).find(slug => refersTo(target, slug)) ?? null;
if (!resolved) { unmatched.push({ line: line.text, reason: 'no_target' }); continue; }
push({ from_slug: page.slug, to_slug: resolved, link_type: linkType, kind: m[1] === 'Started' ? 'start' : 'end',
occurred_on: line.date, date_precision: 'day', producer: line.dream ? 'dream' : 'explicit', line_hash: lineHash(line.text) }, 'cue.explicit');
}
}
// 2. Natural cues on dated lines, for relationships this page asserts.
// State relations take a cue only when it governs the reference itself:
// not on investing/meeting/event lines, not when the reference is
// qualified ("Acme's round", "Acme alumni"). "Left/moved from [A] to/for
// [B]" also starts B.
for (const line of lines) {
if (hasExplicit(line.text)) continue;
const refs = referencesIn(line.text);
const eventLine = EVENT_CONTEXT.test(line.text.replace(/\[[^\]\n]*\]\([^)\s]*\)|\[\[[^\]\n]*\]\]/g, ' '));
let prevEnd = 0;
let prevEnded = new Set<string>();
for (const ref of refs) {
const window = windowBefore(line.text, ref.index, prevEnd);
const between = window.replace(/^.*?(?:\]\([^)]*\)|\]\])/, '');
const qualified = QUALIFIED_AFTER.test(line.text.slice(ref.end));
prevEnd = ref.index + 2;
const endedHere = new Set<string>();
for (const r of temporalRows) {
if (!refersTo(ref.target, other(r)) || !r.link_type) continue;
const cues = cuesFor(r.link_type);
const family = r.link_type === 'works_at' ? 'employment' : r.link_type === 'advises' ? 'advisory' : 'partner';
let kind: TransitionKind | null = null;
let rule = '';
if (cues) {
if (eventLine) continue;
if (qualified) {
if (r.link_type !== 'advises' || !ADVISORY_BOARD_AFTER.test(line.text.slice(ref.end))) continue;
kind = /\b(?:left|stepped\s+(?:down|off|away)\s+from|resigned\s+from)\s*$/i.test(window) ? 'end'
: /\b(?:(?:re-?)?joined|was\s+(?:added|named|appointed)\s+to)\s*$/i.test(window) ? 'start' : null;
rule = `cue.advisory_board.${kind}`;
} else if (cues.end.test(window)) { kind = 'end'; rule = `cue.${family}.end`; }
else if (cues.start.test(window)) { kind = 'start'; rule = `cue.${family}.start`; }
else if (prevEnded.has(r.link_type) && /^\s*(?:to|for)\s*$/i.test(between)) { kind = 'start'; rule = 'cue.after_end.to_for'; }
} else if (EVENT_START[r.link_type]?.test(window)) { kind = 'start'; rule = `cue.event.${r.link_type}`; }
if (!kind) continue;
if (kind === 'end') endedHere.add(r.link_type);
push({ from_slug: r.from_slug, to_slug: r.to_slug, link_type: r.link_type, kind, occurred_on: line.date,
date_precision: 'day', producer: line.dream ? 'dream' : 'timeline', line_hash: lineHash(line.text) }, rule);
}
prevEnded = endedHere;
}
}
// 3. Frontmatter since/until on relationship objects ({name, since, until}).
// A name matches its target exactly or as a slug prefix ("Acme" for
// acme-example); when several objects in the field match one target, only
// the exact matches date it, so "MSA" never dates msa-renewal beside "MSA Renewal".
const fm = page.frontmatter ?? {};
for (const r of temporalRows) {
if (r.link_source !== 'frontmatter' || !r.origin_field) continue;
const field = fm[r.origin_field];
const named = (Array.isArray(field) ? field : [field]).flatMap(item => {
if (!item || typeof item !== 'object') return [];
const obj = item as Record<string, unknown>;
const name = typeof obj.name === 'string' ? obj.name : typeof obj.slug === 'string' ? obj.slug : null;
const match = name ? nameMatch(name, other(r)) : null;
return name && match ? [{ obj, name, exact: match === 'exact' }] : [];
});
for (const { obj, name } of named.length > 1 ? named.filter(n => n.exact) : named) {
for (const [key, kind] of [['since', 'start'], ['until', 'end']] as const) {
const d = normalizePartialDate(stringish(obj[key]));
if (!d) continue;
push({ from_slug: r.from_slug, to_slug: r.to_slug, link_type: r.link_type!, kind, occurred_on: d.date,
date_precision: d.precision, producer: 'frontmatter', line_hash: lineHash(`${r.origin_field}:${name}:${key}`) }, `cue.frontmatter.${key}`);
}
}
}
// 4. Tense of each owned assertion row, from compiled-truth mentions only.
for (const r of temporalRows) {
const cues = relationSemantics(r.link_type) === 'state' ? cuesFor(r.link_type!) : null;
if (!cues) { if (relationSemantics(r.link_type) === 'state') tense.set(rowKey(r), 'present'); continue; }
let past = 0, present = 0;
for (const { target, window } of inputs.narrative) {
if (!refersTo(target, other(r))) continue;
if (cues.past.test(window) || cues.end.test(window)) past++; else present++;
}
tense.set(rowKey(r), past > 0 && present === 0 && r.link_source !== 'frontmatter' ? 'past' : 'present');
}
return { tense, transitions, unmatched };
}
function stripDatedLines(text: string): string {
return text.split('\n').map(l => (DATED_LINE_RE.test(l) || DATED_HEADING_RE.test(l) ? '' : l)).join('\n');
}
function stringish(v: unknown): string | null {
if (v instanceof Date) return v.toISOString().slice(0, 10);
if (typeof v === 'number') return String(v);
if (typeof v !== 'string') return null;
// A YAML date (`since: 2021-04-09`) round-trips through page storage as a UTC-midnight timestamp.
return /^\d{4}-\d{2}-\d{2}T00:00:00(?:\.0+)?Z$/.test(v) ? v.slice(0, 10) : v;
}
function nameMatch(name: string, slug: string): 'exact' | 'prefix' | null {
const base = slug.split('/').pop()!.toLowerCase();
const norm = name.toLowerCase().trim().replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '');
if (norm === base || normalizeLinkTarget(name).toLowerCase() === slug.toLowerCase()) return 'exact';
return base.startsWith(`${norm}-`) ? 'prefix' : null;
}