Garry's Opinionated OpenClaw/Hermes Agent Brain
TypeScript
/**
* v0.31 — `_meta.brain_hot_memory` MCP injection helper.
*
* Per /plan-eng-review eD3 + eE4 + eD10:
*
* - Best-effort: own try/catch in the dispatcher; any error here degrades
* to no-_meta rather than failing the tool call.
* - Cache key is (source_id, session_id, hash(takesHoldersAllowList sorted),
* caller identity hash). Visibility-aware: cache entries don't bleed across
* token tiers or across the people one credential reads for.
* - 30s TTL per session. A successful mutating tool call on the engine
* drops that engine's entries (`invalidateHotMemoryForEngine`, called by
* dispatch on every MCP transport), and every hit revalidates the
* source's withdrawal-ledger watermark, so a forget committed by any
* process is never served from the cache.
* - #5575 ENG-11: the key also folds the effective read eligibility (floor
* and activation control), and every hit revalidates the brain's trust
* policy generation (eligibility/generation.ts), read before the rows.
* A tier change, quarantine transition, floor or `trust.%` config change
* or purge in any process makes the next call rebuild. When the
* generation cannot be read, or the rebuild fails, nothing is delivered;
* a cached payload is never served in its place.
* - Facts are read through the 'hot_memory' proactive eligibility (floor,
* quarantined pages, needs_rederive in SQL; activation control by
* eligibility/activation.ts after ranking), and each carries its
* `trust_tier` and `origin`. The payload's `suppressed` field counts what
* activation control withheld, never its content (DX-10).
* - Cap at top-K facts per response so the injection stays lean.
* - A session with no facts of its own falls back to the source's newest
* 24h facts unless the caller passes `sessionOnly` (the IPC handlers do
* when `context.hot_memory.session_only` is on); the flag is part of the
* cache key, so the two answers never share an entry.
*
* Both stdio and HTTP MCP transports pass this hook into dispatchToolCall
* so the felt-memory feature works on every transport.
*/
import type { OperationContext } from './../operations.ts';
import type { BrainEngine, FactRow } from './../engine.ts';
import { effectiveConfidence } from './decay.ts';
import { collapseHotFacts } from './capture-dedup.ts';
import { proactiveEligibility } from '../eligibility/registry.ts';
import { partitionForActivation, suppressionSummary } from '../eligibility/activation.ts';
import { trustFields } from '../eligibility/labels.ts';
import { quoteFacts } from '../search/transcript-quote.ts';
import { eligibilityCacheField, readTrustGeneration } from '../eligibility/generation.ts';
import { callerRelaxesPrivacy, privateFactSources, resolveExcludePrivatePages, worldOnlyFacts } from '../search/private-visibility.ts';
import { isConfigTruthy } from '../config.ts';
import { callerIdentityKey } from '../access/member-facts.ts';
const DEFAULT_TTL_MS = 30_000;
const DEFAULT_TOP_K = 10;
/**
* Hard bound on cache entries. The key folds caller-controlled
* `_meta.session_id`, so without a bound a remote caller could grow the map
* without limit by minting fresh session ids per call. On overflow the entry
* with the OLDEST expiry is evicted (it dies soonest anyway; expiries are
* near-uniform, clamped shorter only when a row's valid_until lands inside
* the window).
*/
export const HOT_MEMORY_CACHE_MAX_ENTRIES = 1000;
/** DB-plane, default false: hot memory never falls back to other sessions' facts. */
export const HOT_MEMORY_SESSION_ONLY_KEY = 'context.hot_memory.session_only';
/** The serve-side reading of `context.hot_memory.session_only`; an unreadable value keeps the default (false). */
export async function readHotMemorySessionOnly(engine: Pick<BrainEngine, 'getConfig'>): Promise<boolean> {
return isConfigTruthy(await engine.getConfig(HOT_MEMORY_SESSION_ONLY_KEY).catch(() => null));
}
interface CacheEntry {
expiresAt: number;
payload: Record<string, unknown> | undefined;
withdrawals?: string;
/** The trust policy generation the payload was built under (ENG-11). */
trustGeneration?: string;
}
const _cache = new Map<string, CacheEntry>();
const _generations = new WeakMap<object, number>();
/**
* Drop every cached payload built from `engine` and bump its generation, so
* a build that read the database before the write cannot store its stale
* result afterwards.
*/
export function invalidateHotMemoryForEngine(engine: object): void {
_generations.set(engine, (_generations.get(engine) ?? 0) + 1);
const key = ENGINE_KEYS.get(engine);
if (!key) return;
for (const k of _cache.keys()) if (k.split('::')[0] === key) _cache.delete(k);
}
/**
* Changes whenever a withdrawal is recorded for the source or (GBRA-218) a folder rulebook is installed, by any process.
* Read-only embedder engines without raw SQL fall back to the TTL alone.
*/
async function withdrawalWatermark(engine: OperationContext['engine'], sourceId: string): Promise<string> {
if (typeof engine.executeRaw !== 'function') return '';
const [row] = await engine.executeRaw<{ n: number; at: string | null; rules: string | null }>(
`SELECT count(*)::int AS n, max(withdrawn_at)::text AS at,
(SELECT md5(coalesce(string_agg(source_id || '/' || rule_id || '/' || prefix || '/' || array_to_string(readable_by, ',') || '/' || revision::text, '|' ORDER BY source_id, rule_id), '')) FROM access_rules)
|| ':' || (SELECT md5(coalesce(string_agg(source_id || '/' || prefix || '/' || reason || '/' || coalesce(revision::text, ''), '|' ORDER BY source_id, prefix, reason), '')) FROM access_pending_coverage) AS rules
FROM fact_withdrawals WHERE source_id = $1`, [sourceId]);
return `${row?.n ?? 0}:${row?.at ?? ''}:${row?.rules ?? ''}`;
}
/** Bounded set: evict the oldest-expiry entry when inserting at capacity. */
function cacheSet(key: string, entry: CacheEntry): void {
if (!_cache.has(key) && _cache.size >= HOT_MEMORY_CACHE_MAX_ENTRIES) {
let oldestKey: string | null = null;
let oldestExpiry = Infinity;
for (const [k, v] of _cache) {
if (v.expiresAt < oldestExpiry) {
oldestExpiry = v.expiresAt;
oldestKey = k;
}
}
if (oldestKey !== null) _cache.delete(oldestKey);
}
_cache.set(key, entry);
}
/**
* Build the `_meta.brain_hot_memory` payload for an MCP tool-call response.
*
* Returns undefined when there's nothing to inject (no facts, no source
* context, helper disabled, etc.). Errors are absorbed by the caller's
* try/catch in dispatch.ts, so this function is allowed to throw — but it
* should fail cleanly rather than throw on the happy path.
*/
export async function getBrainHotMemoryMeta(
name: string,
ctx: OperationContext,
opts: { topK?: number; ttlMs?: number; sessionOnly?: boolean; untrusted?: boolean } = {},
): Promise<Record<string, unknown> | undefined> {
// Don't inject on tool calls that themselves manipulate hot memory —
// the agent doesn't need the brain's hot memory wrapped around its own
// recall response.
// GST-359 C2: nor on QM's memory pair, whose own answer is the member's memory.
if (name === 'recall' || name === 'extract_facts' || name === 'forget_fact' || name === 'memory_recall' || name === 'memory_write') return undefined;
const sourceId = ctx.sourceId ?? 'default';
// CX2-11: session identity is the TYPED OperationContext.sessionId field,
// set from MCP `_meta.session_id` at the dispatch boundary. The old ad-hoc
// `source_session` read is kept as a fallback for legacy embedders, but no
// shipped transport ever set it — without the typed field every caller
// collapsed onto the null-session cache key.
const sessionId = ctx.sessionId
?? (ctx as { source_session?: string }).source_session
?? null;
const allowListHash = hashAllowList(ctx.takesHoldersAllowList);
// v0.45.7 (ambient-recall adversarial review, P1): the visibility TIER is part
// of the key. Without it, a trusted-local call (remote:false → all rows,
// private included) warms the cache and a later remote/world-only call with
// the same source+session+allowList is SERVED the private payload — a
// cross-tier leak through the cache, not through the query.
// The operator opt-out (search.remote_private_pages) changes what a world
// read returns, so it is part of the tier too.
const excludePrivate = await resolveExcludePrivatePages(ctx.engine, ctx.remote);
// GBRA-218: on a brain with member restrictions a relaxed read still applies the readers part, so it has its own tier.
// GST-2089: the brain owner reads private facts too, so its remote tier is marked apart from every world-only tier.
const worldOnly = worldOnlyFacts(ctx.remote);
const pageTier = !excludePrivate ? 'world+private-pages' : callerRelaxesPrivacy() ? 'world+private-pages-readers' : 'world';
// GBRA-575: a world-only read under a private-facts grant admits private facts in the granted sources, so it has its own tier.
const granted = worldOnly ? [...privateFactSources()].sort().join(',') : '';
const tier = ctx.remote === false ? 'all' : !worldOnly ? `private-facts+${pageTier}` : granted ? `${pageTier}+xpf=${granted}` : pageTier;
// encodeCacheField (F5): source_id / session_id are caller-controlled and
// may contain the '::' delimiter; percent-encode ':' so bumpHotMemoryCache's
// split('::') can never mis-slice a component.
// The ENGINE is part of the key: one process can serve multiple brains
// (hosted multi-tenant, test shards, mounted brains), and two engines with
// the same source id / tier / session must never share hot-memory payloads
// — a cached entry from brain A served to brain B's caller is a cross-brain
// fact leak through the cache, not through any query.
const ttl = Math.max(1000, opts.ttlMs ?? DEFAULT_TTL_MS);
const sessionOnly = opts.sessionOnly === true;
// GST-687: an untrusted (remote MCP) reader gets facts below the owner's tier quoted; it is part of the key.
const untrusted = opts.untrusted ?? ctx.remote !== false;
const topK = Math.max(1, Math.min(opts.topK ?? DEFAULT_TOP_K, 25));
// The watermark and the trust generation are read before the rows, so a
// build that raced a forget or a trust transition stores the older value
// and the next hit rebuilds. The eligibility is read after the generation:
// a `trust.%` config change bumps it.
// The two are independent, so they are sent together (one round trip).
const generation = _generations.get(ctx.engine) ?? 0;
const withdrawalsRead = withdrawalWatermark(ctx.engine, sourceId);
const trustGenerationRead = readTrustGeneration(ctx.engine);
trustGenerationRead.catch(() => {});
const withdrawals = await withdrawalsRead;
let trustGeneration: string;
let policy: Awaited<ReturnType<typeof proactiveEligibility>>;
try {
trustGeneration = await trustGenerationRead;
policy = await proactiveEligibility(ctx, 'hot_memory');
} catch {
return undefined;
}
// The effective eligibility is part of the key: two connections with
// different floors never share an entry.
// GST-359 C2: and the caller's identity (attested actor, member, audience): a member's own private facts ride the
// payload, so two people behind one credential and one session id never share an entry. Unbound callers add nothing.
const identityKey = ctx.remote === false ? '' : callerIdentityKey();
const cacheKey = `${engineCacheField(ctx.engine)}::${encodeCacheField(sourceId)}::${tier}::${encodeCacheField(sessionId ?? '_')}::${allowListHash}::${encodeCacheField(eligibilityCacheField(policy))}::${sessionOnly ? 'session-only' : 'fallback'}::${untrusted ? 'quoted' : 'raw'}${identityKey ? `::xid=${identityKey}` : ''}`;
// Cache hit?
const cached = _cache.get(cacheKey);
if (cached) {
if (cached.expiresAt > Date.now() && cached.withdrawals === withdrawals && cached.trustGeneration === trustGeneration) return cached.payload;
// Expired or withdrawn since: evict BEFORE the rebuild. If the rebuild
// below throws (the caller's try/catch absorbs it), the dead entry must
// not linger — with remote-influencable keys, lingering corpses defeat
// the size bound.
_cache.delete(cacheKey);
}
const store = (entry: CacheEntry) => {
if ((_generations.get(ctx.engine) ?? 0) === generation) cacheSet(cacheKey, { ...entry, withdrawals, trustGeneration });
};
// Build a fresh payload. Visibility tier: remote → world-only;
// local and the brain owner → all rows.
const visibility = worldOnly ? ['world'] as ('world' | 'private')[] : undefined;
// Floor, quarantined pages and needs_rederive apply in SQL; activation
// control runs after ranking so the withheld count can be reported.
const eligibility = { ...policy, suppressFlagged: false };
// #5888 V2: over-fetch so collapsing duplicates still fills topK.
let fetched: FactRow[] = [];
if (sessionId) {
fetched = await ctx.engine.listFactsBySession(sourceId, sessionId, {
activeOnly: true, limit: topK * 3, visibility, excludePrivate, fingerprint: true, eligibility,
});
}
// If no session-scoped rows, fall back to recent across the source, unless
// the caller asked for this session's facts only.
if (fetched.length === 0 && !sessionOnly) {
fetched = await ctx.engine.listFactsSince(sourceId, new Date(Date.now() - 24 * 60 * 60 * 1000), {
activeOnly: true, limit: topK * 3, visibility, excludePrivate, fingerprint: true, eligibility,
});
}
if (fetched.length === 0) {
store({ expiresAt: Date.now() + ttl, payload: undefined });
return undefined;
}
// One representative per (fingerprint, entity) group, then sort by
// effective confidence (decayed) before truncating.
const collapsed = await collapseHotFacts(ctx.engine, sourceId, fetched);
const now = new Date();
collapsed.sort((a, b) => effectiveConfidence(b, now) - effectiveConfidence(a, now));
const { kept, withheld } = await partitionForActivation(ctx.engine, collapsed, r => ({ table: 'facts', id: r.id }), policy);
const rows = kept.slice(0, topK).map(k => k.item);
// Under trust.agent_activation=allow (the default) a flagged fact stays in the block, labeled unconfirmed.
const unconfirmed = new Set(kept.filter(k => k.unconfirmed).map(k => k.item.id));
const suppressed = suppressionSummary(withheld);
if (rows.length === 0 && !suppressed) {
store({ expiresAt: Date.now() + ttl, payload: undefined });
return undefined;
}
const payload = {
brain_hot_memory: {
source_id: sourceId,
session_id: sessionId,
...(suppressed ? { suppressed } : {}),
// #8042: a fact saved from a chat page rides the ambient channel quoted; GST-687: for an untrusted reader, so does a fact below the owner's tier.
facts: (await quoteFacts(ctx.engine, rows, untrusted)).map(r => ({
id: r.id,
fact: r.fact,
kind: r.kind,
// v0.31.2: surface notability so connected agents can filter or
// weight HIGH-tier facts in their context budget.
notability: r.notability,
entity_slug: r.entity_slug,
...(r.entity_slugs ? { entity_slugs: r.entity_slugs } : {}),
valid_from: r.valid_from.toISOString(),
// v0.45.7 ambient recall: recording time, so delta's "new facts since my
// last wake" filters on WHEN the fact was learned, not its semantic
// validity date (a fact recorded today about last month is NEW).
created_at: r.created_at.toISOString(),
// #4206: provenance context (e.g. the source_slug extract_facts threaded
// in) rides the pack/delta projections instead of being recall-only.
context: r.context ?? null,
confidence: Number(effectiveConfidence(r, now).toFixed(3)),
...(r.attributed_to ? { attributed_to: r.attributed_to } : {}),
...trustFields(r.trust_tier, r.write_origin),
...(unconfirmed.has(r.id) ? { unconfirmed: true as const } : {}),
...(r.quoted ? { quoted: r.quoted } : {}),
})),
},
};
// Read-time TTL honesty (adversarial review, this wave): a row whose
// valid_until lands INSIDE the cache window would otherwise keep riding
// the ambient channel for up to `ttl` past its expiry even though the
// underlying reads now filter it — clamp this entry's cache deadline to
// the earliest retained valid_until so the next call re-reads on time.
let expiresAt = Date.now() + ttl;
for (const r of rows) {
const vu = r.valid_until?.getTime();
if (vu !== undefined && Number.isFinite(vu) && vu < expiresAt) expiresAt = vu;
}
store({ expiresAt, payload });
return payload;
}
/** Invalidate the cache for a (source_id, session_id) pair after extraction. */
export function bumpHotMemoryCache(sourceId: string, sessionId: string | null): void {
// Walk the cache and prune any entry matching this source+session
// regardless of visibility tier, allow-list hash, OR engine — key layout is
// engine::encField(source)::tier::encField(session)::allowHash::eligibility::scope. Pruning
// across engines is deliberate over-invalidation: a bump is a freshness
// signal and a stale-drop on a sibling engine costs one rebuild, never a
// leak. Components are ':'-encoded, so split('::') slices cleanly even
// when the source/session id itself contains '::' (F5).
const encSource = encodeCacheField(sourceId);
const encSession = encodeCacheField(sessionId ?? '_');
for (const k of _cache.keys()) {
const parts = k.split('::');
if (parts[1] === encSource && parts[3] === encSession) _cache.delete(k);
}
}
// Engine identity for the cache key: a WeakMap-issued serial, so the key
// stays a flat string (the bounded Map + prefix pruning keep working) and a
// disconnected engine can be garbage-collected.
const ENGINE_KEYS = new WeakMap<object, string>();
let engineKeySeq = 0;
function engineCacheField(engine: object): string {
let k = ENGINE_KEYS.get(engine);
if (!k) {
k = `e${++engineKeySeq}`;
ENGINE_KEYS.set(engine, k);
}
return k;
}
/** Percent-encode ':' so a caller-controlled id can't inject the '::' key
* delimiter (F5). Cheap, reversible, and keeps keys human-readable. */
function encodeCacheField(v: string): string {
return v.replace(/:/g, '%3A');
}
/** Test helper: clear the cache. */
export function __resetHotMemoryCacheForTests(): void {
_cache.clear();
}
/** Test helper: direct cache access (expiry mutation + size/eviction pins). */
export function __hotMemoryCacheForTests(): Map<string, { expiresAt: number; payload: Record<string, unknown> | undefined }> {
return _cache;
}
/**
* Stable hash of the (sorted) allow-list. Mirrors the auth contract.
*
* The allow-list affects cache IDENTITY only — the payload itself is filtered
* by fact visibility (see the `visibility` tier above), never by the takes
* allow-list. Keeping `[]` (explicit deny-all grant) distinct from undefined
* (no grant) is insurance so a future allowlist-dependent payload is born
* safe, not a claim that `[]` suppresses hot memory today.
*
* Encoding is collision-free: undefined maps to a token no JSON array can
* produce, and every concrete list serializes via JSON.stringify. A bare
* `sorted.join('|')` would have collided `['a|b']` with `['a','b']`, and bare
* sentinels would have collided `['(empty)']` with `[]` — so a holder value
* that happened to equal a sentinel could not share a cache bucket it
* shouldn't.
*/
function hashAllowList(list: string[] | undefined): string {
if (!list) return 'none';
return JSON.stringify([...list].sort());
}