Skip to content

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.ts
index 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) => AIGat
let 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.ts
index 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.ts
index 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.ts
index 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.ts
new file mode 100644
index 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.ts
index 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);
}