Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript

fix(facts): the brain owner gets private facts in query, think, hot memory, delta and question-ranked recall (GST-2089)

garrytan46acb6c2c0af
diff --git a/src/core/context/turn-context.ts b/src/core/context/turn-context.ts
index 8451c57b1d..b8093fd108 100644
--- a/src/core/context/turn-context.ts
+++ b/src/core/context/turn-context.ts
@@ -798,8 +798,8 @@ async function assembleDelta(
if (!pastDeadline()) {
try {
const after = opts.factsAfter ?? (since ? { at: since, id: null } : null);
- const visibility = remote ? (['world'] as ('private' | 'world')[]) : undefined;
- const { resolveExcludePrivatePages } = await import('../search/private-visibility.ts');
+ const { resolveExcludePrivatePages, worldOnlyFacts } = await import('../search/private-visibility.ts');
+ const visibility = worldOnlyFacts(remote) ? (['world'] as ('private' | 'world')[]) : undefined;
const excludePrivate = await resolveExcludePrivatePages(engine, remote ? undefined : false);
const rows = await engine.listFactsKeyset(
opts.sourceId,
diff --git a/src/core/facts/meta-hook.ts b/src/core/facts/meta-hook.ts
index f7f0a9cc78..c172279e79 100644
--- a/src/core/facts/meta-hook.ts
+++ b/src/core/facts/meta-hook.ts
@@ -44,7 +44,7 @@ import { partitionForActivation, suppressionSummary } from '../eligibility/activ
import { trustFields } from '../eligibility/labels.ts';
import { quoteFacts } from '../search/transcript-quote.ts';
import { eligibilityCacheField, readTrustGeneration } from '../eligibility/generation.ts';
-import { callerRelaxesPrivacy, resolveExcludePrivatePages } from '../search/private-visibility.ts';
+import { callerRelaxesPrivacy, resolveExcludePrivatePages, worldOnlyFacts } from '../search/private-visibility.ts';
import { isConfigTruthy } from '../config.ts';
import { callerIdentityKey } from '../access/member-facts.ts';
@@ -160,7 +160,10 @@ export async function getBrainHotMemoryMeta(
// 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.
- const tier = ctx.remote === false ? 'all' : !excludePrivate ? 'world+private-pages' : callerRelaxesPrivacy() ? 'world+private-pages-readers' : 'world';
+ // 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';
+ const tier = ctx.remote === false ? 'all' : worldOnly ? pageTier : `private-facts+${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.
@@ -215,8 +218,8 @@ export async function getBrainHotMemoryMeta(
};
// Build a fresh payload. Visibility tier: remote → world-only;
- // local → all rows.
- const visibility = ctx.remote === false ? undefined : ['world'] as ('world' | 'private')[];
+ // 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.
diff --git a/src/core/ops/facts.ts b/src/core/ops/facts.ts
index 9dbe67882c..e12fca7489 100644
--- a/src/core/ops/facts.ts
+++ b/src/core/ops/facts.ts
@@ -365,11 +365,9 @@ const recall: Operation = {
const scalarSource = factSources.length === 1 ? factSources[0] : undefined;
// Visibility filter: remote callers see world-only facts; the local CLI and (GST-2059) the brain owner see all.
- const { resolveExcludePrivatePages, callerIsOwner } = await import('../search/private-visibility.ts');
- const visibility =
- ctx.remote === false || callerIsOwner()
- ? undefined
- : ['world'] as ('private' | 'world')[];
+ const { resolveExcludePrivatePages, worldOnlyFacts } = await import('../search/private-visibility.ts');
+ const worldOnly = worldOnlyFacts(ctx.remote);
+ const visibility = worldOnly ? ['world'] as ('private' | 'world')[] : undefined;
const excludePrivate = await resolveExcludePrivatePages(ctx.engine, ctx.remote); // #4352: fact and page arms alike
const eligibility = await resolveReadEligibility(ctx, { minTrust: p.min_trust }); // #5575 floor + quarantine/rederive hiding
@@ -433,7 +431,7 @@ const recall: Operation = {
if (question !== null && !readsNoSource) {
ranking = await rankFactsByQuestion(ctx, { question, params: p, factSources, limit, entity: entityParam, sessionId: sessionParam, since, grep, includeExpired,
- scope: { sourceIds: factSources, remote: ctx.remote !== false, excludePrivate, minTrust: eligibility.floor, suppressFlagged: eligibility.suppressFlagged } });
+ scope: { sourceIds: factSources, worldOnly, excludePrivate, minTrust: eligibility.floor, suppressFlagged: eligibility.suppressFlagged } });
({ rows, ambiguousEntity } = ranking);
for (const notice of questionRecallNotices(ranking, ctx.brainId)) ctx.emitNotice?.(notice);
} else if (p.supersessions === true) {
diff --git a/src/core/ops/qm-memory.ts b/src/core/ops/qm-memory.ts
index 21e46fef0e..5e34df66cb 100644
--- a/src/core/ops/qm-memory.ts
+++ b/src/core/ops/qm-memory.ts
@@ -149,7 +149,7 @@ async function recallFacts(ctx: OperationContext, query: string, maxChars: numbe
const { rankFactsByQuestion } = await import('../facts/question-recall.ts');
const ranked = query && sources.length ? (await rankFactsByQuestion(ctx, {
question: query, params: { question: query }, factSources: sources, limit: MEMORY_RECALL_ARM_LIMIT, entity: null, sessionId: null, since: null, grep: null,
- scope: { sourceIds: sources, remote, excludePrivate: read.excludePrivate, minTrust: read.eligibility.floor, suppressFlagged: read.eligibility.suppressFlagged },
+ scope: { sourceIds: sources, worldOnly: remote, excludePrivate: read.excludePrivate, minTrust: read.eligibility.floor, suppressFlagged: read.eligibility.suppressFlagged },
})).rows : [];
const seen = new Set<number>();
const rows = [...own, ...ranked].filter(r => !seen.has(r.id) && !!seen.add(r.id));
diff --git a/src/core/search/fact-relevance.ts b/src/core/search/fact-relevance.ts
index a417c38b3d..a3b5397958 100644
--- a/src/core/search/fact-relevance.ts
+++ b/src/core/search/fact-relevance.ts
@@ -82,7 +82,9 @@ export const FACTS_ARM_COSINE_MIN = 0.6;
export const FACT_ADMISSION_FLOOR_EVIDENCE: Readonly<Record<string, string>> = {};
export interface FactPoolScope {
- sourceId?: string; sourceIds?: string[]; remote: boolean;
+ sourceId?: string; sourceIds?: string[];
+ /** World-only facts: worldOnlyFacts(remote) for the caller (private facts only for the local CLI and the brain owner). */
+ worldOnly: boolean;
/** #5575 read floor and activation control, applied in the pool SQL like every retrieval arm. */
minTrust?: TrustTier; suppressFlagged?: boolean;
/** Hide facts whose provenance page is private (resolveExcludePrivatePages for the caller). */
@@ -151,7 +153,7 @@ function poolPredicate(scope: FactPoolScope, filters: FactPoolFilters | undefine
filters?.includeExpired ? 'f.source_id = ANY($1::text[])' : 'f.source_id = ANY($1::text[]) AND f.expired_at IS NULL AND f.superseded_by IS NULL',
filters?.includeExpired ? 'f.source != ALL($2::text[])' : '(f.valid_until IS NULL OR f.valid_until > now()) AND f.source != ALL($2::text[])',
quarantinedProvenanceFilterFragment('f'),
- ...(scope.remote ? [factVisibilitySql('f', ['world'])] : []),
+ ...(scope.worldOnly ? [factVisibilitySql('f', ['world'])] : []),
...(scope.excludePrivate ? [privateProvenanceFilterUnderPolicy('f')] : []),
projectionEligibleSql('facts', 'f', { floor: scope.minTrust, suppressFlagged: scope.suppressFlagged }),
];
diff --git a/src/core/search/facts-arm.ts b/src/core/search/facts-arm.ts
index 2c839a5555..380adbb840 100644
--- a/src/core/search/facts-arm.ts
+++ b/src/core/search/facts-arm.ts
@@ -19,7 +19,7 @@
*/
import type { BrainEngine } from '../engine.ts';
import type { PageReadScope, SearchResult } from '../types.ts';
-import { resolveExcludePrivatePages } from './private-visibility.ts';
+import { resolveExcludePrivatePages, worldOnlyFacts } from './private-visibility.ts';
import { admitted, collectFactCandidates, FACTS_ARM_COSINE_MIN, queryTerms, scoreFactCandidates, type FactCandidate as PoolCandidate, type FactPoolScope } from './fact-relevance.ts';
import { pageReadFilter } from './read-policy-sql.ts';
import { enforceTokenBudget, resultTokens } from './token-budget.ts';
@@ -76,7 +76,7 @@ export interface FactsArmScope {
type FactCandidate = PoolCandidate;
async function poolScope(engine: BrainEngine, scope: FactsArmScope): Promise<FactPoolScope> {
- return { ...scope, excludePrivate: await resolveExcludePrivatePages(engine, scope.remote) };
+ return { ...scope, worldOnly: worldOnlyFacts(scope.remote), excludePrivate: await resolveExcludePrivatePages(engine, scope.remote) };
}
const day = (v: Date | string | null) => (v ? new Date(v).toISOString().slice(0, 10) : null);
diff --git a/src/core/search/private-visibility.ts b/src/core/search/private-visibility.ts
index 65ee019c4d..1082c81b80 100644
--- a/src/core/search/private-visibility.ts
+++ b/src/core/search/private-visibility.ts
@@ -302,6 +302,15 @@ export function callerIsOwner(): boolean {
return currentCallerAccess().owner;
}
+/**
+ * GST-2089: whether a fact read stays world-only (visibility = 'world'). Only the trusted local CLI (remote strictly
+ * false) and the brain owner (CallerAccess.owner, the page rule) read private facts; provenance, source grants and
+ * member access still apply to both. Fact arms decide their visibility list here and nowhere else.
+ */
+export function worldOnlyFacts(remote: boolean | undefined): boolean {
+ return remote !== false && !callerIsOwner();
+}
+
/** The current caller's member identity; empty outside a bound remote read or a local --as, and for an audience of several entries (see callerIdentities). */
export function callerIdentity(): readonly string[] {
return currentCallerAccess().identity;
diff --git a/src/core/think/index.ts b/src/core/think/index.ts
index d81f8f51be..79c21e9ec8 100644
--- a/src/core/think/index.ts
+++ b/src/core/think/index.ts
@@ -37,7 +37,7 @@ import { normalizeModelId } from '../model-id.ts';
import { hasAnthropicKey } from '../ai/anthropic-key.ts';
import { resolveThinkWindow, trajectoryPointsInWindow } from './temporal-window.ts';
import { resolveThinkTemporalContext } from './temporal-context.ts';
-import { resolveExcludePrivatePages } from '../search/private-visibility.ts';
+import { resolveExcludePrivatePages, worldOnlyFacts } from '../search/private-visibility.ts';
import { deliverEvidence, effectivePlan, resolveEvidencePlan, EVIDENCE_BLOCK_CHAR_CAP, THINK_RETURN_UNIT_CONFIG_KEY, type DeliveryMeta } from '../search/evidence-delivery.ts';
import { evidenceTitlesEnabled } from '../search/evidence-date.ts';
import { startThinkDecide, thinkAbstainResult, type ThinkAbstention } from './decide.ts';
@@ -771,7 +771,7 @@ export async function runThink(
entitySlug: resolved.slug,
...(opts.sourceId !== undefined ? { sourceId: opts.sourceId } : {}),
...(opts.allowedSources !== undefined ? { sourceIds: opts.allowedSources } : {}),
- ...(opts.remote !== undefined ? { remote: opts.remote } : {}),
+ ...(opts.remote !== undefined ? { remote: worldOnlyFacts(opts.remote) } : {}),
excludePrivate,
kind: 'all',
limit: 100,
diff --git a/test/access-owner-reads.test.ts b/test/access-owner-reads.test.ts
index 1228fee4e7..9b5422d4ce 100644
--- a/test/access-owner-reads.test.ts
+++ b/test/access-owner-reads.test.ts
@@ -27,6 +27,7 @@ import { bindCredential } from '../src/core/access/members.ts';
import { accessCheck } from '../src/commands/access.ts';
import { openAsPreview } from '../src/cli/as-preview.ts';
import type { AuthInfo } from '../src/core/ops/contract.ts';
+import { getBrainHotMemoryMeta, __resetHotMemoryCacheForTests } from '../src/core/facts/meta-hook.ts';
import { testBackends } from './helpers/test-backends.ts';
import { isolatedPersistencePostgres } from './helpers/persistence-postgres.ts';
@@ -55,6 +56,12 @@ const OPEN = { slug: 'notes/open-plan', canary: 'canaryownopen' };
/** Another person's page: member access keeps it from the owner too. */
const BOBS = { slug: 'notes/bob-plan', canary: 'canaryownbob' };
const PRIVATE_FACT = 'canaryownfact';
+/** GST-2089: a private dated fact about a person, which think's trajectory reads. */
+const PERSON = 'people/carol-example';
+const PRIVATE_TRAJECTORY = 'canaryowntraj';
+/** Private facts the owner must not read: one taken from another person's readable_by page, one in a source its grant does not read. */
+const BOBS_FACT = 'canaryownbobfact';
+const UNGRANTED_FACT = 'canaryownungranted';
const pageText = (title: string, canary: string, fm: readonly string[]) =>
['---', ...(fm.some(l => l.startsWith('type:')) ? [] : ['type: note']), `title: ${title}`, ...fm, '---', `# ${title}`, '', `Harbor ledger planning notes ${canary} for the roadmap.`].join('\n');
@@ -77,13 +84,13 @@ for (const kind of testBackends()) {
const tokens: Record<string, string> = {};
const provider = () => new GBrainOAuthProvider({ sql: sqlQueryForEngine(engine), transaction: fn => engine.transaction(tx => fn(sqlQueryForEngine(tx))) });
- async function call(who: string, op: string, params: Record<string, unknown>, header?: string): Promise<{ isError: boolean; text: string; meta: Record<string, unknown> | undefined }> {
+ async function call(who: string, op: string, params: Record<string, unknown>, header?: string, extra: { metaHook?: typeof getBrainHotMemoryMeta } = {}): Promise<{ isError: boolean; text: string; meta: Record<string, unknown> | undefined }> {
const auth = await provider().verifyAccessToken(tokens[who]!) as unknown as AuthInfo;
const sourceId = auth.sourceId ?? 'default';
const localFederated = await noGrantFederatedScope(engine, auth.hasSourceGrant, sourceId);
const out = await dispatchToolCall(engine, op, { ...params }, {
remote: true, transport: 'http', auth, sourceId, takesHoldersAllowList: auth.takesHoldersAllowList ?? ['world'],
- ...(localFederated ? { localFederatedSourceIds: localFederated } : {}), ...(header ? { onBehalfOf: { header } } : {}),
+ ...(localFederated ? { localFederatedSourceIds: localFederated } : {}), ...(header ? { onBehalfOf: { header } } : {}), ...extra,
});
return { isError: out.isError === true, text: out.content.map(c => c.text).join('\n'), meta: out._meta as Record<string, unknown> | undefined };
}
@@ -116,6 +123,14 @@ for (const kind of testBackends()) {
await importFromContent(engine, BOBS.slug, pageText('Bob plan', BOBS.canary, ['readable_by: [bob-example]']), { sourceId: SRC });
const fact = await dispatchToolCall(engine, 'remember', { fact: `Harbor ledger planning notes ${PRIVATE_FACT}`, provenance: 'fixture', entity: OPEN.slug, visibility: 'private' }, { remote: false, sourceId: SRC });
if (fact.isError) throw new Error(`fixture remember: ${fact.content.map(c => c.text).join(' ')}`);
+ // think resolves trajectory entities in its scalar source, which is default for a caller with a source grant.
+ for (const sourceId of [SRC, 'default']) await importFromContent(engine, PERSON, ['---', 'type: person', 'title: Carol Example', '---', '# Carol Example', '', 'Carol is a founder.'].join('\n'), { sourceId });
+ await engine.executeRaw(`INSERT INTO facts (source_id, entity_slug, fact, kind, visibility, valid_from, source, event_type)
+ VALUES ($1, $2, $3, 'event', 'private', '2026-05-01T00:00:00Z', 'fixture', 'job_change')`, [SRC, PERSON, `Carol switched jobs ${PRIVATE_TRAJECTORY}`]);
+ for (const [sourceId, canary, provenance] of [[SRC, BOBS_FACT, BOBS.slug], ['default', UNGRANTED_FACT, null]] as const) {
+ await engine.executeRaw(`INSERT INTO facts (source_id, entity_slug, fact, kind, visibility, valid_from, source, event_type, source_markdown_slug)
+ VALUES ($1, $2, $3, 'event', 'private', '2026-06-01T00:00:00Z', 'fixture', 'job_change', $4)`, [sourceId, PERSON, `Harbor ledger planning notes ${canary}`, provenance]);
+ }
for (const id of [OWNER, 'bob-example']) await engine.executeRaw('INSERT INTO access_members (id) VALUES ($1)', [id]);
const mint = async (name: string, member?: string, mayActFor?: string[]) => {
const minted = await mintLegacyToken(engine, { name, scopes: ['read'], takesHolders: ['world'], sourceGrant: [SRC] });
@@ -154,6 +169,72 @@ for (const kind of testBackends()) {
for (const who of ['bob', 'unbound']) expect({ who, seen: (await call(who, 'recall', { query: 'harbor ledger planning notes' })).text.includes(PRIVATE_FACT) }).toEqual({ who, seen: false });
}, 120_000);
+ /** GST-2089: which fact surfaces show `who` a private fact: the query facts arm, ranked recall, hot memory, delta, context_pack and think's trajectory. */
+ async function privateFactsSeenBy(who: string, header?: string, canary = PRIVATE_FACT): Promise<string[]> {
+ const seen: string[] = [];
+ const surfaces: Array<[string, () => Promise<string>, string]> = [
+ ['query', async () => (await call(who, 'query', { query: 'harbor ledger planning notes', expand: false, limit: 20 }, header)).text, canary],
+ ['recall question', async () => (await call(who, 'recall', { question: `Harbor ledger planning notes ${canary}` }, header)).text, canary],
+ ['recall entity question', async () => (await call(who, 'recall', { entity: OPEN.slug, question: `Harbor ledger planning notes ${canary}` }, header)).text, canary],
+ ['hot memory', async () => JSON.stringify((await call(who, 'get_page', { slug: OPEN.slug }, header, { metaHook: getBrainHotMemoryMeta })).meta?.brain_hot_memory ?? null), canary],
+ ['delta', async () => (await call(who, 'delta', { since: '2000-01-01T00:00:00Z' }, header)).text, canary],
+ ['context_pack', async () => (await call(who, 'context_pack', { entities: OPEN.slug }, header)).text, canary],
+ ['think trajectory', async () => (await call(who, 'think', { question: 'When did Carol last switch jobs?' }, header)).text.match(/TRAJECTORY_INJECTED_\d+_POINTS/)?.[0] ?? '', 'TRAJECTORY_INJECTED'],
+ ];
+ for (const [label, read, shown] of surfaces) if ((await read()).includes(shown)) seen.push(label);
+ return seen;
+ }
+ const FACT_SURFACES = ['query', 'recall question', 'recall entity question', 'hot memory', 'delta', 'context_pack', 'think trajectory'];
+
+ test('fixture control: a trusted local caller gets the private facts on every fact surface', async () => {
+ const local = (op: string, params: Record<string, unknown>) => dispatchToolCall(engine, op, params, { remote: false, sourceId: SRC }).then(o => o.content.map(c => c.text).join('\n'));
+ expect(await local('recall', { question: `Harbor ledger planning notes ${PRIVATE_FACT}` })).toContain(PRIVATE_FACT);
+ expect(await local('think', { question: 'When did Carol last switch jobs?' })).toMatch(/TRAJECTORY_INJECTED_\d+_POINTS/);
+ expect(await local('recall', { question: `Harbor ledger planning notes ${BOBS_FACT}` })).toContain(BOBS_FACT);
+ expect((await dispatchToolCall(engine, 'recall', { question: `Harbor ledger planning notes ${UNGRANTED_FACT}` }, { remote: false, sourceId: 'default' })).content.map(c => c.text).join('\n')).toContain(UNGRANTED_FACT);
+ }, 120_000);
+
+ test('GST-2089: the owner and its delegate get private facts on every fact surface; another member and an unbound token get world-only facts', async () => {
+ __resetHotMemoryCacheForTests();
+ for (const who of ['owner', 'delegate']) expect({ who, seen: await privateFactsSeenBy(who) }).toEqual({ who, seen: FACT_SURFACES });
+ for (const who of ['bob', 'unbound']) expect({ who, seen: await privateFactsSeenBy(who) }).toEqual({ who, seen: [] });
+ }, 240_000);
+
+ test('GST-2089: the owner reads no private fact taken from another person\'s readable_by page or kept in a source its grant does not read', async () => {
+ __resetHotMemoryCacheForTests();
+ for (const canary of [BOBS_FACT, UNGRANTED_FACT]) expect({ canary, seen: (await privateFactsSeenBy('owner', undefined, canary)).filter(s => s !== 'think trajectory') }).toEqual({ canary, seen: [] });
+ expect((await call('owner', 'think', { question: 'When did Carol last switch jobs?' })).text).toContain('TRAJECTORY_INJECTED_1_POINTS');
+ }, 240_000);
+
+ test('GST-2089: the owner speaking for itself alone keeps private facts; for a channel audience it gets world-only facts', async () => {
+ __resetHotMemoryCacheForTests();
+ expect(await privateFactsSeenBy('owner', `member:${OWNER}`)).toEqual(FACT_SURFACES);
+ expect(await privateFactsSeenBy('owner', `member:${OWNER},member:bob-example`)).toEqual([]);
+ }, 240_000);
+
+ test('GST-2089: hot memory keys on the caller: after the owner warms the entry, the next caller with the same session reads world-only facts', async () => {
+ const hot = async (who: string, header?: string) => JSON.stringify((await call(who, 'get_page', { slug: OPEN.slug }, header, { metaHook: getBrainHotMemoryMeta })).meta?.brain_hot_memory ?? null);
+ for (const next of [['bob'], ['unbound'], ['owner', `member:${OWNER},member:bob-example`]] as const) {
+ __resetHotMemoryCacheForTests();
+ expect(await hot('owner')).toContain(PRIVATE_FACT);
+ expect({ next, seen: (await hot(next[0], next[1])).includes(PRIVATE_FACT) }).toEqual({ next, seen: false });
+ }
+ // With privacy relaxed by the operator, the same credential after `gbrain access owner clear` shares the owner's
+ // page tier and identity; the fact tier still keeps it off the owner's cached private facts.
+ await engine.setConfig('search.remote_private_pages', 'visible');
+ __resetPrivateVisibilityCacheForTests();
+ __resetHotMemoryCacheForTests();
+ try {
+ expect(await hot('owner')).toContain(PRIVATE_FACT);
+ await clearOwner(engine);
+ expect(await hot('owner')).not.toContain(PRIVATE_FACT);
+ } finally {
+ await setOwner(engine, OWNER);
+ await engine.unsetConfig('search.remote_private_pages');
+ __resetPrivateVisibilityCacheForTests();
+ }
+ }, 120_000);
+
test('another member and an unbound token still see no private page on any path, after the owner read them', async () => {
expect(await privateSeenBy('bob')).toEqual({});
expect(await privateSeenBy('unbound')).toEqual({});