Garry's Opinionated OpenClaw/Hermes Agent Brain
TypeScript
/**
* GBRA-219: memory writeback settings over MCP. Every case runs on a keyless,
* in-memory PGLite brain with no git repository (repo-less brains are first
* class): the settings live in the config table and the audit row in the
* request log.
*/
import { describe, test, expect, beforeAll, afterAll, beforeEach } from 'bun:test';
import { PGLiteEngine } from '../src/core/pglite-engine.ts';
import { resetPgliteState } from './helpers/reset-pglite.ts';
import { dispatchToolCall } from '../src/mcp/dispatch.ts';
import { operations } from '../src/core/operations.ts';
import { disabledOpsForPublishGates } from '../src/mcp/publish-gates.ts';
import { isCallable } from '../src/core/ops/callable.ts';
import { buildMcpInstructions } from '../src/mcp/instructions.ts';
import { buildAmbientWritebackSection } from '../src/core/facts/writeback-instructions.ts';
import { ambientOptsFrom, captureLaneStates, resolveWritebackConfig } from '../src/core/facts/writeback-config.ts';
import { resolveAgentWriteback } from '../src/core/facts/writeback-settings.ts';
import { stdioAmbientOpts } from '../src/mcp/server.ts';
import type { AuthInfo } from '../src/core/ops/contract.ts';
import { addMember } from '../src/core/access/members.ts';
import type { GBrainConfig } from '../src/core/config.ts';
const CONFIG = { engine: 'pglite' } as GBrainConfig;
let engine: PGLiteEngine;
beforeAll(async () => {
engine = new PGLiteEngine();
await engine.connect({});
await engine.initSchema();
});
afterAll(async () => {
await engine.disconnect();
});
beforeEach(async () => {
await resetPgliteState(engine);
});
const auth = (scopes: string[], extra: Partial<AuthInfo> = {}): AuthInfo => ({ token: 't', clientId: 'client-a', scopes, ...extra }) as AuthInfo;
async function call(name: string, params: Record<string, unknown>, opts: { scopes?: string[]; auth?: AuthInfo; remote?: boolean } = {}) {
const res = await dispatchToolCall(engine, name, params, {
remote: opts.remote ?? true,
transport: 'http',
config: CONFIG,
auth: opts.auth ?? auth(opts.scopes ?? ['admin']),
sourceId: 'default',
});
return { isError: res.isError === true, body: JSON.parse(res.content[0].text) as Record<string, any> };
}
async function auditRows(): Promise<Array<{ params: Record<string, unknown> }>> {
return engine.executeRaw(`SELECT params FROM mcp_request_log WHERE operation = 'memory_setting_change' ORDER BY id`) as never;
}
const op = (name: string) => operations.find(o => o.name === name)!;
describe('set_memory_writeback: operator grant + admin scope', () => {
test('gate unset: hidden from the catalog and refused at call time; nothing written', async () => {
const disabled = await disabledOpsForPublishGates(engine, CONFIG);
expect(disabled.has('set_memory_writeback')).toBe(true);
const gates = { 'mcp.publish_memory_settings': false };
expect(isCallable(op('set_memory_writeback'), { transport: 'http', surface: 'full', scopes: ['admin'], publishGates: gates })).toBe(false);
const res = await call('set_memory_writeback', { mode: 'all' });
expect(res.isError).toBe(true);
expect(JSON.stringify(res.body)).toContain('mcp.publish_memory_settings');
expect(await engine.getConfig('memory.agent_writeback')).toBeNull();
expect(await auditRows()).toHaveLength(0);
});
test('gate on: write scope is not enough, admin scope changes only the agent override', async () => {
await engine.setConfig('mcp.publish_memory_settings', 'true');
expect(isCallable(op('set_memory_writeback'), { transport: 'http', surface: 'full', scopes: ['read', 'write'], publishGates: { 'mcp.publish_memory_settings': true } })).toBe(false);
const denied = await call('set_memory_writeback', { mode: 'all' }, { scopes: ['read', 'write'] });
expect(denied.isError).toBe(true);
expect(await engine.getConfig('memory.agent_writeback')).toBeNull();
const ok = await call('set_memory_writeback', { mode: 'salient' });
expect(ok.isError).toBe(false);
expect(ok.body.applied).toBe(true);
expect(ok.body.background_capture_unchanged).toBe(true);
expect(await engine.getConfig('memory.agent_writeback')).toBe('salient');
expect(await engine.getConfig('memory.auto_writeback')).toBeNull();
const rows = await auditRows();
expect(rows).toHaveLength(1);
expect(rows[0].params).toMatchObject({ key: 'memory.agent_writeback', actor: 'client-a', old: null, new: 'salient', transport: 'http' });
});
test('remote off then remote salient never moves the host capture lanes', async () => {
await engine.setConfig('mcp.publish_memory_settings', 'true');
await engine.setConfig('memory.auto_writeback', 'salient');
const before = captureLaneStates(await resolveWritebackConfig(engine, CONFIG, { gate: true }));
expect((await call('set_memory_writeback', { mode: 'off' })).isError).toBe(false);
expect(captureLaneStates(await resolveWritebackConfig(engine, CONFIG, { gate: true }))).toEqual(before);
expect((await call('set_memory_writeback', { mode: 'salient' })).isError).toBe(false);
expect(captureLaneStates(await resolveWritebackConfig(engine, CONFIG, { gate: true }))).toEqual(before);
expect(await engine.getConfig('memory.auto_writeback')).toBe('salient');
});
test('a restrictive override says background capture keeps running', async () => {
await engine.setConfig('mcp.publish_memory_settings', 'true');
await engine.setConfig('memory.auto_writeback', 'all');
const res = await call('set_memory_writeback', { mode: 'off' });
expect(res.body.effective_mode).toBe('off');
expect(res.body.note).toContain('keeps running');
});
test('dry_run writes neither the setting nor an audit row', async () => {
await engine.setConfig('mcp.publish_memory_settings', 'true');
const res = await call('set_memory_writeback', { mode: 'all', dry_run: true });
expect(res.body).toMatchObject({ applied: false, dry_run: true, requested: 'all', previous: 'inherit' });
expect(await engine.getConfig('memory.agent_writeback')).toBeNull();
expect(await auditRows()).toHaveLength(0);
});
test('setting and audit commit together: a failed audit insert leaves the setting unchanged and says the outcome is unknown', async () => {
await engine.setConfig('mcp.publish_memory_settings', 'true');
await engine.executeRaw('ALTER TABLE mcp_request_log RENAME TO mcp_request_log_gone');
let res: Awaited<ReturnType<typeof call>>;
try {
res = await call('set_memory_writeback', { mode: 'all' });
} finally {
await engine.executeRaw('ALTER TABLE mcp_request_log_gone RENAME TO mcp_request_log');
}
expect(res.isError).toBe(true);
expect(JSON.stringify(res.body)).toContain('memory_setting_write_outcome_unknown');
expect(JSON.stringify(res.body)).toContain('get_memory_settings');
expect(await engine.getConfig('memory.agent_writeback')).toBeNull();
});
test('the trusted local CLI needs no grant', async () => {
const res = await call('set_memory_writeback', { mode: 'all' }, { remote: false });
expect(res.isError).toBe(false);
expect(await engine.getConfig('memory.agent_writeback')).toBe('all');
});
});
describe('resolveAgentWriteback: the override never widens on doubt', () => {
test('inherit and unset follow the operator; a valid override wins', async () => {
await engine.setConfig('memory.auto_writeback', 'salient');
expect((await resolveAgentWriteback(engine, CONFIG)).bundle.mode).toBe('salient');
await engine.setConfig('memory.agent_writeback', 'inherit');
expect((await resolveAgentWriteback(engine, CONFIG)).bundle.mode).toBe('salient');
await engine.setConfig('memory.agent_writeback', 'off');
const off = await resolveAgentWriteback(engine, CONFIG);
expect(off.bundle).toMatchObject({ mode: 'off', enabled: false });
expect(off.operator.mode).toBe('salient');
expect(off.status).toBe('ok');
});
test('an unrecognized override fails closed to off, degraded', async () => {
await engine.setConfig('memory.auto_writeback', 'all');
await engine.setConfig('memory.agent_writeback', 'everything');
const r = await resolveAgentWriteback(engine, CONFIG);
expect(r).toMatchObject({ source: 'fail_closed', status: 'degraded' });
expect(r.bundle.mode).toBe('off');
expect(r.reasons).toContain('agent_override_invalid');
});
test('an unreadable override with no last-known-good fails closed to off', async () => {
const real = engine.getConfig.bind(engine);
const flaky = Object.create(engine) as PGLiteEngine;
flaky.getConfig = async (key: string) => {
if (key === 'memory.agent_writeback') throw new Error('config read failed');
return key === 'memory.auto_writeback' ? 'all' : real(key);
};
const r = await resolveAgentWriteback(flaky, CONFIG);
expect(r.bundle.mode).toBe('off');
expect(r.reasons).toContain('agent_override_unreadable');
});
});
describe('resolveAgentWriteback: cold failures', () => {
test('an operator read failure with no last-known-good never emits an enabled rule on default posture', async () => {
await engine.setConfig('memory.agent_writeback', 'all');
await engine.setConfig('facts.default_visibility', 'private');
const real = engine.getConfig.bind(engine);
const cold = Object.create(engine) as PGLiteEngine;
cold.getConfig = async (key: string) => {
if (key === 'facts.default_visibility' || key === 'memory.auto_writeback') throw new Error('config read failed');
return real(key);
};
const r = await resolveAgentWriteback(cold, CONFIG);
expect(r.bundle.enabled).toBe(false);
expect(r).toMatchObject({ source: 'fail_closed', status: 'degraded' });
});
test('a confirmed restrictive write replaces the cached override, so a later read failure cannot revive the old one', async () => {
await engine.setConfig('mcp.publish_memory_settings', 'true');
await call('set_memory_writeback', { mode: 'all' });
expect((await resolveAgentWriteback(engine, CONFIG)).bundle.mode).toBe('all');
await call('set_memory_writeback', { mode: 'off' }, { remote: false });
const real = engine.getConfig;
engine.getConfig = async (key: string) => {
if (key === 'memory.agent_writeback') throw new Error('config read failed');
return real.call(engine, key);
};
try {
expect((await resolveAgentWriteback(engine, CONFIG)).bundle.mode).toBe('off');
} finally {
engine.getConfig = real;
}
});
});
describe('get_memory_settings', () => {
test('rule text matches what initialize renders; off has none; every mode is previewable', async () => {
const off = await call('get_memory_settings', {}, { scopes: ['read', 'write'] });
expect(off.body.effective_mode).toBe('off');
expect(off.body.rule_text).toBeNull();
expect(off.body.rule_texts.salient).toContain('mode: salient');
expect(off.body.rule_texts.all).toContain('mode: all');
expect(off.body.operator_mode).toEqual({ mode: 'off', explicit: false });
await engine.setConfig('memory.agent_writeback', 'salient');
const on = await call('get_memory_settings', {}, { scopes: ['read', 'write'] });
const bundle = (await resolveAgentWriteback(engine, CONFIG)).bundle;
const rendered = buildMcpInstructions({ writeback: ambientOptsFrom(bundle, { remember: true, extractFacts: true }) });
expect(on.body.rule_text).toBe(buildAmbientWritebackSection({ mode: 'salient', transientTtl: '3d', visibility: 'world', extractFactsAvailable: true }));
expect(rendered).toContain(on.body.rule_text);
expect(on.body.source).toBe('agent_override');
});
test('can_set names the missing grant with the operator command; conversation switch needs remember', async () => {
const reader = await call('get_memory_settings', {}, { scopes: ['read'] });
expect(reader.body.can_set).toMatchObject({ allowed: false, blocked_by: ['gate_off', 'scope'] });
expect(JSON.stringify(reader.body.can_set.fix)).toContain('mcp.publish_memory_settings');
expect(reader.body.conversation_switch.available).toBe(false);
expect(reader.body.rule_text).toBeNull();
await engine.setConfig('mcp.publish_memory_settings', 'true');
const writer = (await call('get_memory_settings', {}, { scopes: ['read', 'write'] })).body.can_set;
expect(writer).toMatchObject({ allowed: false, blocked_by: ['scope'] });
expect(writer.fix).toBeUndefined();
expect((await call('get_memory_settings', {})).body.can_set).toEqual({ allowed: true });
});
test('a degraded read says so instead of reporting a plain off', async () => {
await engine.setConfig('memory.agent_writeback', 'bogus');
const res = await call('get_memory_settings', {}, { scopes: ['read'] });
expect(res.body.status).toBe('degraded');
expect(res.body.note).toContain('not proof');
});
});
describe('memory_conversation_mode', () => {
test('GST-2243: a stdio server bound to a member (mcp.stdio_member) gets the member rule, never "pass visibility: world"', async () => {
await addMember(engine, 'alice-example');
await engine.setConfig('mcp.stdio_member', 'alice-example');
const res = await dispatchToolCall(engine, 'memory_conversation_mode', { mode: 'all' }, { remote: true, transport: 'stdio', config: CONFIG, sourceId: 'default' });
const body = JSON.parse(res.content[0].text) as Record<string, any>;
expect(res.isError === true).toBe(false);
expect(body.rule_text).toContain('share: true');
expect(body.rule_text).not.toContain('Pass visibility:');
});
test('GST-2243: the stdio serve\'s ambient writeback section carries the member rule only when mcp.stdio_member binds a live member', async () => {
await engine.setConfig('memory.agent_writeback', 'all');
const { bundle } = await resolveAgentWriteback(engine, CONFIG);
expect((await stdioAmbientOpts(engine, bundle, undefined))?.member).toBeUndefined();
await addMember(engine, 'alice-example');
await engine.setConfig('mcp.stdio_member', 'alice-example');
const opts = await stdioAmbientOpts(engine, bundle, undefined);
expect(opts?.member).toBe(true);
expect(buildAmbientWritebackSection(opts!)).toContain('share: true');
expect(await stdioAmbientOpts(engine, bundle, new Set(['search']))).toBeNull();
});
test('all returns a conversation rule with the brain\'s private posture, even when the operator set off; nothing is stored', async () => {
await engine.setConfig('memory.auto_writeback', 'off');
await engine.setConfig('facts.default_visibility', 'private');
const before = await engine.executeRaw('SELECT key, value FROM config ORDER BY key');
const res = await call('memory_conversation_mode', { mode: 'all' }, { scopes: ['read', 'write'] });
expect(res.isError).toBe(false);
expect(res.body).toMatchObject({ mode: 'all', persisted: false, applies_to: 'this_conversation', background_capture_unchanged: true });
expect(res.body.rule_text).toContain('for the rest of this conversation');
expect(res.body.rule_text).toContain('visibility: "private"');
expect(await engine.executeRaw('SELECT key, value FROM config ORDER BY key')).toEqual(before);
});
test('off returns the explicit-only rule and is honest about host capture', async () => {
await engine.setConfig('memory.agent_writeback', 'all');
const res = await call('memory_conversation_mode', { mode: 'off' }, { scopes: ['write'] });
expect(res.body.effective_mode).toBe('off');
expect(res.body.rule_text).toContain('only what the user explicitly asks you to keep');
expect(res.body.rule_text).toContain('background capture');
});
test('brain returns the brain\'s effective rule', async () => {
await engine.setConfig('memory.agent_writeback', 'salient');
const res = await call('memory_conversation_mode', { mode: 'brain' }, { scopes: ['write'] });
expect(res.body.effective_mode).toBe('salient');
expect(res.body.rule_text).toContain('enabled by this brain');
});
test('a read-only connection is refused; an invalid mode is never repaired into another mode', async () => {
const ro = await call('memory_conversation_mode', { mode: 'all' }, { scopes: ['read'] });
expect(ro.isError).toBe(true);
const bound = await call('memory_conversation_mode', { mode: 'all' }, { auth: auth(['read', 'write'], { boundSlugPrefixes: ['people/alice-example'] } as Partial<AuthInfo>) });
expect(bound.isError).toBe(true);
const bad = await call('memory_conversation_mode', { mode: 'pause' }, { scopes: ['write'] });
expect(bad.isError).toBe(true);
expect(JSON.stringify(bad.body)).not.toContain('"tool":"memory_conversation_mode"');
});
});
describe('initialize instructions', () => {
test('the switch clause appears only when the tool is callable, after the governing rule', () => {
const withIt = buildMcpInstructions({ tools: { callable: () => true } });
const at = withIt.indexOf('memory_conversation_mode');
expect(at).toBeGreaterThan(withIt.indexOf('The record whose terms are in effect'));
expect(withIt).toContain('save everything from here, or to stop saving');
const without = buildMcpInstructions({ tools: { callable: n => n !== 'memory_conversation_mode' } });
expect(without).not.toContain('memory_conversation_mode');
});
test('an agent override turns the ambient section on even while the operator mode is unset', async () => {
await engine.setConfig('memory.agent_writeback', 'all');
const bundle = (await resolveAgentWriteback(engine, CONFIG)).bundle;
const text = buildMcpInstructions({ writeback: ambientOptsFrom(bundle, { remember: true, extractFacts: true }) });
expect(text).toContain('Ambient memory writeback (enabled by this brain');
expect(captureLaneStates(await resolveWritebackConfig(engine, CONFIG, { gate: true })).writeback).toBe('retire');
});
});