Garry's Opinionated OpenClaw/Hermes Agent Brain
TypeScript
feat(embedded): settings.cache_namespace keeps a reopened brain's query embeddings warm (B3a G)
garrytaneada45bea016
diff --git a/src/core/ai/engine-gateway.ts b/src/core/ai/engine-gateway.tsindex 7459060e51..e0e993d923 100644--- a/src/core/ai/engine-gateway.ts+++ b/src/core/ai/engine-gateway.ts@@ -3,6 +3,7 @@* alone: no `process.env` key, no `~/.gbrain/config.json` and no process-wide gateway reaches it. The gateway* (gateway.ts) reads it for every call that runs in that engine's scope (engine-scope.ts).*/+import { createHash } from 'node:crypto';import { opError } from '../ops/contract.ts';import { embeddedSettingsRecord, releasedEngineKeys, type EngineAISettings, type EngineSettings } from '../embedded-engine.ts';@@ -118,17 +119,30 @@ export function scopedGatewayState(normalize: (config: AIGatewayConfig) => AIGatlet state = states.get(settings);if (!state) {const { config, providers } = engineGatewayInput(settings);- state = freshGatewayState(normalize(config), `engine:${crypto.randomUUID()}:`, providers);+ state = freshGatewayState(normalize(config), queryCacheTag(settings), providers);states.set(settings, state);}return state;}-/** At an embedded engine's close, before its settings go: drop the query embeddings its calls cached. */+/**+ * The query-embedding cache tag: unique to this engine object, or, with `settings.cache_namespace`, the namespace plus+ * the provider-configuration generation (provider ids, base URLs and a fingerprint of each key; the key itself never+ * enters the tag), so a reopened brain hits and a replaced key or endpoint starts cold.+ */+function queryCacheTag(settings: EngineSettings): string {+ if (!settings.cache_namespace) return `engine:${crypto.randomUUID()}:`;+ const sha = (value: string) => createHash('sha256').update(value).digest('hex');+ const generation = Object.entries(settings.ai?.providers ?? {}).sort(([a], [b]) => a.localeCompare(b))+ .map(([id, provider]) => [id, provider.baseUrl ?? '', provider.apiKey ? sha(provider.apiKey) : '']);+ return `ns:${sha(JSON.stringify([settings.cache_namespace, generation]))}:`;+}++/** At an embedded engine's close, before its settings go: drop the query embeddings it cached, unless a namespace keeps them for its next open. */export function releaseEngineGatewayState(engine: object): void {const settings = embeddedSettingsRecord(engine);const state = settings && states.get(settings);- if (state) dropQueryEmbeddingsTagged(state.cacheTag);+ if (state && !settings.cache_namespace) dropQueryEmbeddingsTagged(state.cacheTag);}/** Provider keys of a disconnected engine in scope, as env entries, so a call still in flight scrubs them from its error. */diff --git a/src/core/ai/query-embed-cache.ts b/src/core/ai/query-embed-cache.tsindex 335eba6c91..96e77a7f28 100644--- a/src/core/ai/query-embed-cache.ts+++ b/src/core/ai/query-embed-cache.ts@@ -49,9 +49,9 @@ export function dropQueryEmbeddingsTagged(tag: string): void {for (const key of entries.keys()) if (key.includes(tag)) entries.delete(key);}-/** @internal exported for tests: how many entries the cache holds. */-export function __queryEmbedCacheSizeForTests(): number {- return entries.size;+/** @internal exported for tests: the cache keys, oldest first. */+export function __queryEmbedCacheKeysForTests(): string[] {+ return [...entries.keys()];}export function clearQueryEmbedCache(): void {diff --git a/src/core/embedded-engine.ts b/src/core/embedded-engine.tsindex 14acef6aa1..76f1228248 100644--- a/src/core/embedded-engine.ts+++ b/src/core/embedded-engine.ts@@ -30,6 +30,13 @@ export interface EngineSettings {* model is `embedding` above. Without it every AI call refuses `engine_scope_missing`; no process key is used.*/ai?: EngineAISettings;+ /**+ * Opaque name the host owns for one tenant database incarnation. With it, query embeddings cached for this engine+ * stay warm across reopens of the same brain (tagged by the namespace and a hash of the provider configuration);+ * without it every engine starts cold and its entries go when it closes. Never derive it from the stored brain id:+ * a cloned or restored database shares that.+ */+ cache_namespace?: string;}export interface EngineAISettings {diff --git a/src/core/engine-open.ts b/src/core/engine-open.tsindex 2a2fb5ca38..470557d330 100644--- a/src/core/engine-open.ts+++ b/src/core/engine-open.ts@@ -59,7 +59,7 @@ function checkAI(ai: EngineAISettings): void {/** Each setting openEngine reads, with the fields it reads inside it (null: a value, or fields another check reads: ai.providers, storage in Wave C). */const SETTINGS_FIELDS: Record<string, readonly string[] | null> = {embedded_core: null, engine: null, database: ['url', 'directUrl', 'path'], pool: ['max'], host: ['id'], writer: ['id', 'credential', 'lane'],- embedding: ['model', 'dimensions'], keyword_statement_timeout_ms: null, pglite: ['shared_buffers'], ai: ['providers', 'models'], storage: null,+ embedding: ['model', 'dimensions'], keyword_statement_timeout_ms: null, pglite: ['shared_buffers'], ai: ['providers', 'models'], storage: null, cache_namespace: null,};/** A misspelled or foreign key would be silently ignored, so it refuses, naming the key and never its value. */@@ -102,6 +102,8 @@ function checkSettings(settings: EngineSettings): void {throw invalid('embedding', 'embedding is { model, dimensions } with a model name and a positive whole width.');}if (settings.ai !== undefined) checkAI(settings.ai);+ const namespace = settings.cache_namespace;+ if (namespace !== undefined && !(text(namespace) && namespace.length <= 256)) throw invalid('cache_namespace', 'cache_namespace is an opaque string of 1 to 256 characters when given.');}/**diff --git a/test/engine-cache-namespace.test.ts b/test/engine-cache-namespace.test.tsnew file mode 100644index 0000000000..a9e1590b0f--- /dev/null+++ b/test/engine-cache-namespace.test.ts@@ -0,0 +1,90 @@+/**+ * GBRA-283 B3a (N2, gate d3a/d9a): an embedded engine's query-embedding cache entries are tagged per engine object by+ * default (cold for every new engine, dropped at close). A host that reopens a brain per call may pass+ * settings.cache_namespace, an opaque string it owns for one tenant database: the tag is then that namespace plus the+ * provider-configuration generation (provider set, base URLs and a key fingerprint, never the key), so a reopened+ * brain hits, another namespace never does even on a cloned database, and a replaced key starts cold.+ */+import { afterEach, describe, expect, test } from 'bun:test';+import { cpSync, mkdtempSync } from 'node:fs';+import { tmpdir } from 'node:os';+import { join } from 'node:path';+import { randomBytes, randomUUID } from 'node:crypto';+import { __setEmbedTransportForTests, embedQuery, resetGateway } from '../src/core/ai/gateway.ts';+import { __queryEmbedCacheKeysForTests } from '../src/core/ai/query-embed-cache.ts';+import { embeddedSettings, openEngine, withEngineScope, type EngineSettings } from '../src/core/engine-open.ts';+import type { BrainEngine } from '../src/core/engine.ts';++const EMBEDDING = { model: 'openai:text-embedding-3-small', dimensions: 1536 };+const key = () => `sk-ns-${randomBytes(12).toString('hex')}`;+const calls: string[] = [];+afterEach(() => {+ calls.length = 0;+ __setEmbedTransportForTests(null);+ resetGateway();+});+function stubEmbeds(): void {+ __setEmbedTransportForTests((async ({ model, values }: any) => {+ const headers = await model.config.headers();+ calls.push(headers.authorization ?? '');+ return { embeddings: values.map(() => Array.from({ length: EMBEDDING.dimensions }, (_, i) => (i % 7) + 1)), usage: { tokens: 1 } };+ }) as any);+}+const settingsFor = (path: string | undefined, apiKey: string, cache_namespace?: string): EngineSettings => ({+ embedded_core: true, engine: 'pglite', database: path ? { path } : {}, host: { id: randomUUID() }, embedding: EMBEDDING,+ ai: { providers: { openai: { apiKey } } }, ...(cache_namespace !== undefined ? { cache_namespace } : {}),+});+/** Opens, embeds one query in the engine's scope, closes; returns how many provider calls it made. */+async function askOnce(settings: EngineSettings, query = 'what did brain-a plan'): Promise<number> {+ const before = calls.length;+ const engine: BrainEngine = await openEngine(settings);+ try { await withEngineScope(engine, () => embedQuery(query)); } finally { await engine.disconnect(); }+ return calls.length - before;+}++describe('settings.cache_namespace', () => {+ test('two copies of one database under different namespaces miss on their own; the same namespace reopened hits; a replaced key misses', async () => {+ stubEmbeds();+ const dir = mkdtempSync(join(tmpdir(), 'gbrain-cache-ns-'));+ const original = join(dir, 'brain-a.pglite');+ const seed = await openEngine(settingsFor(original, key()));+ await seed.initSchema();+ await seed.disconnect();+ const copy = join(dir, 'brain-a-copy.pglite');+ cpSync(original, copy, { recursive: true });+ const apiKey = key();+ expect(await askOnce(settingsFor(original, apiKey, 'tenant-a-incarnation-1'))).toBe(1);+ expect(await askOnce(settingsFor(copy, apiKey, 'tenant-b-incarnation-1'))).toBe(1);+ expect(await askOnce(settingsFor(original, apiKey, 'tenant-a-incarnation-1'))).toBe(0);+ expect(await askOnce(settingsFor(copy, apiKey, 'tenant-b-incarnation-1'))).toBe(0);+ expect(await askOnce(settingsFor(original, key(), 'tenant-a-incarnation-1'))).toBe(1);+ }, 120_000);++ test('without a namespace every new engine starts cold', async () => {+ stubEmbeds();+ const apiKey = key();+ expect(await askOnce(settingsFor(undefined, apiKey))).toBe(1);+ expect(await askOnce(settingsFor(undefined, apiKey))).toBe(1);+ }, 60_000);++ test('the namespace is an opaque non-empty string, read back as given, and no tag carries the key', async () => {+ for (const bad of ['', 42, { id: 'x' }, 'x'.repeat(257)]) {+ const error = await openEngine({ ...settingsFor(undefined, key()), cache_namespace: bad as never }).then(e => e.disconnect().then(() => null), e => e);+ expect(error?.code).toBe('engine_settings_invalid');+ expect(error?.message).toContain('cache_namespace');+ }+ stubEmbeds();+ const apiKey = key();+ const engine = await openEngine(settingsFor(undefined, apiKey, 'tenant-a'));+ try {+ expect(embeddedSettings(engine)?.cache_namespace).toBe('tenant-a');+ await withEngineScope(engine, () => embedQuery('a question for brain-a'));+ const tagged = __queryEmbedCacheKeysForTests().filter(k => k.includes('a question for brain-a'));+ expect(tagged).toHaveLength(1);+ expect(tagged[0]).not.toContain(apiKey);+ expect(tagged[0]).not.toContain('tenant-a');+ } finally {+ await engine.disconnect();+ }+ }, 60_000);+});diff --git a/test/engine-gateway-state.test.ts b/test/engine-gateway-state.test.tsindex 2aad1f3281..b268994014 100644--- a/test/engine-gateway-state.test.ts+++ b/test/engine-gateway-state.test.ts@@ -13,7 +13,7 @@ import {__getShrinkStateForTests, __setEmbedTransportForTests, __setGenerateObjectTransportForTests, __setGenerateTextTransportForTests,configureGateway, embed, embedQuery, expand, rerank, resetGateway,} from '../src/core/ai/gateway.ts';-import { __queryEmbedCacheSizeForTests } from '../src/core/ai/query-embed-cache.ts';+import { __queryEmbedCacheKeysForTests } from '../src/core/ai/query-embed-cache.ts';import { readRecentRerankFailures } from '../src/core/rerank-audit.ts';import { openEngine, withEngineScope, withLocalScope, type EngineSettings } from '../src/core/engine-open.ts';import type { BrainEngine } from '../src/core/engine.ts';@@ -98,13 +98,13 @@ describe('per-engine adaptive gateway state', () => {const a = await open({ providers: { voyage: { apiKey: key('a') } } });const b = await open({ providers: { voyage: { apiKey: key('b') } } });try {- const before = __queryEmbedCacheSizeForTests();+ const before = __queryEmbedCacheKeysForTests().length;await withEngineScope(a, () => embedQuery('a question'));await withEngineScope(a, () => embedQuery('another question'));await withEngineScope(b, () => embedQuery('a question'));- expect(__queryEmbedCacheSizeForTests()).toBe(before + 3);+ expect(__queryEmbedCacheKeysForTests().length).toBe(before + 3);await a.disconnect();- expect(__queryEmbedCacheSizeForTests()).toBe(before + 1);+ expect(__queryEmbedCacheKeysForTests().length).toBe(before + 1);} finally {await closeAll(a, b);}