Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript

remember: a service that names a member per call is told both save rules, and the refusal names the exact retry (GST-2243)

garrytan015056d35956
diff --git a/CHANGELOG.md b/CHANGELOG.md
index f64a04ae92..6f2f0204eb 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -18,7 +18,7 @@ identifiers and attribution are available in the pre-removal Git revision
- `src/core/verbs.ts`: `remember` takes a `share` boolean on every MCP surface, starter included. A non-boolean `share`, `share: true` with `visibility: "private"`, and a member's `visibility: "world"` (`member_share_required`) are refused with `invalid_params` before anything is saved, so one such item refuses a whole batch.
- `src/core/persistence/memory-mutations.ts`: a member's `share: true` saves on the entity page with world visibility; when that page's facts would be private (whatever `visibility` the call passed), the save is refused (`share_target_restricted`), and preparation refuses it again if the page turned restricted after admission. In a batch, items saved before a refused item stay saved, as with other save-time refusals. New and replayed replies carry `page` and `visibility`.
-- `src/core/facts/writeback-instructions.ts`, `writeback-config.ts`, `src/mcp/instructions.ts`, the HTTP serves, the stdio serve bound through `mcp.stdio_member` and `memory_conversation_mode`: with ambient writeback on, a member caller is told to omit `visibility` and to pass `share: true` only for facts about the team's work, instead of the brain-wide "pass visibility: world" line its saves would now be refused for.
+- `src/core/facts/writeback-instructions.ts`, `writeback-config.ts`, `src/mcp/instructions.ts`, the HTTP serves, the stdio serve bound through `mcp.stdio_member` and `memory_conversation_mode`: with ambient writeback on, a member caller is told to omit `visibility` and to pass `share: true` only for facts about the team's work, instead of the brain-wide "pass visibility: world" line its saves would now be refused for. A credential that may name a member per call (`x-qm-actor` on `remember`, as QM's service does) is told both: the member rule on calls made for a member, `visibility: "world"` on the rest. The `member_share_required` refusal names the exact retry.
- `src/core/remember-batch.ts`: `share` is accepted per item and as a shared top-level key, and each item's receipt carries `page` and `visibility`.
- `test/mcp-schema-budget.test.ts`: the starter tool-list ceilings and the `remember` budget grow by what `share` costs (+144 characters, 200 headroom kept).
- QM's `memory_write` and its per-person contract (`docs/contracts/qm-memory-provider/v1.json`) are unchanged.
diff --git a/src/commands/serve-http-mcp.ts b/src/commands/serve-http-mcp.ts
index cf56ed6ba7..31c0ba859b 100644
--- a/src/commands/serve-http-mcp.ts
+++ b/src/commands/serve-http-mcp.ts
@@ -20,7 +20,7 @@ import { httpInstructionTools } from '../mcp/initialize-context.ts';
import { installCapabilitiesResource, mcpAdministrationGuidance } from '../mcp/capabilities.ts';
import { createSkillResources } from '../mcp/skill-resources.ts';
import { resolveAuthCapabilities } from '../core/harness/capabilities.ts';
-import { ambientOptsFrom, type WritebackConfig } from '../core/facts/writeback-config.ts';
+import { ambientOptsFrom, writebackCaller, type WritebackConfig } from '../core/facts/writeback-config.ts';
import { resolveAgentWriteback } from '../core/facts/writeback-settings.ts';
import { hasScope, operationScopesAllowed } from '../core/scope.ts';
import { summarizeMcpParams, dispatchToolCall, requestLogStatusForResult, requestMetaSessionId, hotMemoryOffIn, acceptedPendingReceipt, unknownToolEnvelope, errorResult, dispatchRenderContext, grantBlockedNotices, admitNotices, audienceRefusal, type ToolResult } from '../mcp/dispatch.ts';
@@ -219,7 +219,7 @@ function createMcpRequestServer(
writebackOpts = ambientOptsFrom(writeback, {
remember: rememberOp !== undefined && opAllowedForBoundClient(authInfo, rememberOp),
extractFacts: extractFactsOp !== undefined && opAllowedForBoundClient(authInfo, extractFactsOp),
- member: !!authInfo?.member,
+ ...writebackCaller(authInfo),
});
}
const server = new Server(
diff --git a/src/core/behavior-change-notice.ts b/src/core/behavior-change-notice.ts
index 5adf344a6d..cf9acefc0c 100644
--- a/src/core/behavior-change-notice.ts
+++ b/src/core/behavior-change-notice.ts
@@ -1494,7 +1494,7 @@ export const BEHAVIOR_CHANGES: ReadonlyArray<{ since: string; text: ChangeText;
{ since: '0.60.622.0', id: 'purge_cancels_deferred_write_gst1602', text: 'With `persistence.refresh_barrier` on, `gbrain forget <id> --purge` no longer refuses `purge_blocked_pending_recovery` while a write deferred behind a refresh holds the claim in its staged body: the deferred write was never claimed, so the purge cancels it with `purged_content`, as it does a queued one, and removes the content at once instead of up to 15 minutes later.' },
{ since: '0.60.623.0', id: 'owner_reads_private_gst2059', text: 'A brain can now name its owner: `gbrain access owner set <member>` (config `access.owner_member`, an enabled member). Every remote credential or stdio server bound to that member reads the whole brain, `visibility: private` pages, privacy-alias pages (`access: private`, ...), derived and pinned-question pages included, through `get_page`, `search`, `query`, `recall` and the other page reads in the sources its grant reads, and `recall` returns its private facts. `readable_by` and folder rules still bind it, and it is not relaxed when it speaks for a shared-room audience. A page the owner\'s credential creates in `default` through `put_page` is not kept to the owner (no `readable_by: [member:<id>]`). Other members, unbound and public callers are unchanged. `_meta.access.relaxation` reads `owner` for such a call, and `gbrain access check --token <name>` reports it. `gbrain repair private-labels` (named runs only) previews the `access: private` labels stamped on ordinary pages with counts per category, keeps real restrictions, and clears the rest in reviewed batches (`--apply --expect <hash>`), recording each change so `--class restore` can put it back. The bulk-ingestion page template no longer writes an `access:` line; what each designation means is in docs/guides/access-designations.md.' },
{ since: '0.60.626.0', id: 'record_origin_checkout_lockdown_8888', text: '`gbrain sources record-origin <id>... --remote --apply` now also turns git-lfs downloads and hooks off in each recorded source\'s existing checkout (its `.git/config`: `lfs.fetchexclude=*`, `core.hooksPath=/dev/null`, `lfs.locksverify=false`), not only on later reclones, in the repository\'s shared config, and refuses `write_failed` naming the key when a worktree-scoped or included setting still overrides one; a source already recorded as remote gets the lock-down on the next `--remote --apply` when its checkout lacks it, even when its files now use git-lfs, and a key that holds several values in that config is replaced by the one clone-time value. On a managed brain it takes the same worktree locks a reclone takes, refusing the id `source_busy` while a reclone, refresh or write holds them, and a reclone reads the record under its own locks. A write that fails is reported for its own id (`write_failed`) instead of ending the run. The git-lfs check reads a committed `.gitattributes` under a directory whose name holds a tab, ignores commented-out `filter=lfs` lines, says when a committed rule only declares an LFS filter, records a clone of an empty repository instead of refusing it, and names the cause of an `lfs_unknown` refusal.' },
- { since: 'TBD', id: 'remember_share_gst2243', text: 'A member credential\'s `remember` still saves privately on `memory/members/<member>` by default, and can now pass `share: true` to save the fact on its subject\'s page for everyone who reads the source, as every non-member caller does. A member\'s explicit `visibility: "world"`, which used to be saved as private without a word, is now refused (`invalid_params`, reason `member_share_required`) and nothing is saved; `share: true` with `visibility: "private"`, or onto a page whose facts are kept private, is refused too (`share_target_restricted` for the page). Only the brain host can withdraw a shared fact. With ambient writeback on, a member credential\'s instructions say to omit `visibility` and use `share: true` for team facts. Every `remember` reply, for any caller, now names the `page` the fact went to and its `visibility`. QM\'s `memory_write` is unchanged.' },
+ { since: 'TBD', id: 'remember_share_gst2243', text: 'A member credential\'s `remember` still saves privately on `memory/members/<member>` by default, and can now pass `share: true` to save the fact on its subject\'s page for everyone who reads the source, as every non-member caller does. A member\'s explicit `visibility: "world"`, which used to be saved as private without a word, is now refused (`invalid_params`, reason `member_share_required`) and nothing is saved; `share: true` with `visibility: "private"`, or onto a page whose facts are kept private, is refused too (`share_target_restricted` for the page). Only the brain host can withdraw a shared fact. With ambient writeback on, a member credential\'s instructions say to omit `visibility` and use `share: true` for team facts, and a credential that may name a member through `x-qm-actor` is told to do so on those calls and pass `visibility: "world"` on the rest. Every `remember` reply, for any caller, now names the `page` the fact went to and its `visibility`. QM\'s `memory_write` is unchanged.' },
];
/** The newest disclosed change's release: the notice id moves only when a release adds rows. */
diff --git a/src/core/facts/writeback-config.ts b/src/core/facts/writeback-config.ts
index adc4091bd4..cfd52f71eb 100644
--- a/src/core/facts/writeback-config.ts
+++ b/src/core/facts/writeback-config.ts
@@ -49,6 +49,7 @@
import type { BrainEngine } from '../engine.ts';
import type { GBrainConfig } from '../config.ts';
+import type { AuthInfo } from '../ops/contract.ts';
import { validateTtlConfig } from './ttl-parse.ts';
export const AUTO_WRITEBACK_KEY = 'memory.auto_writeback';
@@ -155,7 +156,7 @@ const lkg = new WeakMap<BrainEngine, WritebackConfig>();
*/
export function ambientOptsFrom(
wb: WritebackConfig,
- avail: { remember: boolean; extractFacts: boolean; member?: boolean },
+ avail: { remember: boolean; extractFacts: boolean; member?: boolean; actor?: boolean },
): AmbientOptsShape | null {
if (!wb.enabled || wb.mode === 'off') return null;
if (!avail.remember) return null;
@@ -164,7 +165,7 @@ export function ambientOptsFrom(
transientTtl: wb.transient_ttl,
visibility: wb.visibility,
extractFactsAvailable: avail.extractFacts,
- ...(avail.member ? { member: true } : {}),
+ ...(avail.member ? { member: true } : avail.actor ? { actor: true } : {}),
};
}
interface AmbientOptsShape {
@@ -173,6 +174,16 @@ interface AmbientOptsShape {
visibility: 'world' | 'private';
extractFactsAvailable: boolean;
member?: boolean;
+ actor?: boolean;
+}
+
+/**
+ * GST-2243: who an HTTP credential writes as, for its instructions: a member-bound credential is one member; a credential
+ * that may name a member per call (x-qm-actor on remember) writes as that member on those calls and as itself otherwise.
+ */
+export function writebackCaller(auth: Pick<AuthInfo, 'member' | 'attest'> | undefined): { member?: true; actor?: true } {
+ if (auth?.member) return { member: true };
+ return auth?.attest?.ops.includes('remember') ? { actor: true } : {};
}
/**
diff --git a/src/core/facts/writeback-instructions.ts b/src/core/facts/writeback-instructions.ts
index f8c42beb1e..1dde579327 100644
--- a/src/core/facts/writeback-instructions.ts
+++ b/src/core/facts/writeback-instructions.ts
@@ -28,6 +28,8 @@ export interface AmbientWritebackOpts {
visibility: 'world' | 'private';
/** GST-2243: the caller is one team member, whose remember is private unless it passes share: true. */
member?: boolean;
+ /** GST-2243: the credential may name the team member a call serves (x-qm-actor); those calls write as that member. */
+ actor?: boolean;
/** True only when `extract_facts` is actually callable on this transport's
* allowed-op set (OV2-14) — never advertise an uncallable tool. The
* engine-free harness block cannot probe the serve's surface, so it passes
@@ -54,6 +56,8 @@ export function buildAmbientWritebackSection(opts: AmbientWritebackOpts): string
: `always save via remember with ttl: "${opts.transientTtl}" — never batch them through extract_facts (it cannot set a ttl, so they would become permanent).`;
const visibilityLine = opts.member
? 'Omit visibility: your saves stay private to you. Pass share: true only for a fact about the team\'s work, never about a person; every reader of this source then recalls it, and only the brain host can withdraw it.'
+ : opts.visibility === 'world' && opts.actor
+ ? 'On a save made for a team member (x-qm-actor), omit visibility: it stays private to that member, and share: true shares a fact about the team\'s work with every reader of this source. On any other save, pass visibility: "world" explicitly. "world" means readable by agents authorized on THIS brain — not the public internet. Never widen a private fact on your own.'
: opts.visibility === 'world'
? 'Pass visibility: "world" explicitly on every save. "world" means readable by agents authorized on THIS brain — not the public internet. Never widen a private fact on your own.'
: 'Pass visibility: "private" explicitly on every save — this brain\'s operator keeps facts private by default (omitting visibility would silently widen: remember defaults to world). Private facts are readable by the local CLI only, not by remote sessions: you, and every other MCP or HTTP session, cannot recall or forget a fact you save as private. Never widen to world on your own.';
diff --git a/src/core/verbs.ts b/src/core/verbs.ts
index aa5a673d2b..4b5ced8f39 100644
--- a/src/core/verbs.ts
+++ b/src/core/verbs.ts
@@ -190,7 +190,7 @@ const remember: Operation = {
// GST-2243: a member shares only with share: true, so its explicit visibility "world" is refused, never quietly made private.
if (p.share !== true && p.visibility === 'world' && ctx.attestedOp !== 'memory_write' && (await import('./access/member-facts.ts')).memberFactPage(ctx)) {
throw Object.assign(verbError('invalid_params', 'remember: a member credential shares a fact with share: true, not visibility "world"; nothing was saved.',
- 'Facts about the team\'s work: pass share: true and everyone who reads this source recalls them. Facts about a person: drop visibility and they stay on your own member page, recalled by you alone.'),
+ 'Retry the same call with share: true in place of visibility "world" to share a fact about the team\'s work with everyone who reads this source, or with no visibility to keep a fact about a person on your own member page. A member shares only this way: pass share: true, never visibility "world".'),
{ reason: 'member_share_required' });
}
if (p.valid_from !== undefined && !isStrictIsoDateTime(p.valid_from)) {
diff --git a/src/mcp/http-transport.ts b/src/mcp/http-transport.ts
index 989224fdcb..c4057e443c 100644
--- a/src/mcp/http-transport.ts
+++ b/src/mcp/http-transport.ts
@@ -34,7 +34,7 @@ import type { BrainEngine } from '../core/engine.ts';
import { buildToolDefs } from './tool-defs.ts';
import { MCP_SERVER_DESCRIPTION, readInstructionContent, resolveMcpInstructions } from './instructions.ts';
import { httpInstructionTools } from './initialize-context.ts';
-import { ambientOptsFrom } from '../core/facts/writeback-config.ts';
+import { ambientOptsFrom, writebackCaller } from '../core/facts/writeback-config.ts';
import { resolveAgentWriteback } from '../core/facts/writeback-settings.ts';
import { operations, operationsByName, opAllowedForBoundClient } from '../core/operations.ts';
import { scopeDeniedError } from '../core/ops/op-fix.ts';
@@ -473,7 +473,7 @@ export async function startHttpTransport(opts: HttpTransportOptions) {
capabilities: { tools: {}, resources: {} },
// #4748: contract (+ opt-in writeback section) + deployment identity.
instructions: resolveMcpInstructions(fileConfig, process.env, {
- writeback: ambientOptsFrom(writeback, { remember: canWriteOp('remember'), extractFacts: canWriteOp('extract_facts'), member: !!auth.auth?.member }),
+ writeback: ambientOptsFrom(writeback, { remember: canWriteOp('remember'), extractFacts: canWriteOp('extract_facts'), ...writebackCaller(auth.auth) }),
tools: await httpInstructionTools(engine, fileConfig, { ops: surfacedOps, surface, auth: auth.auth!, allowedOps: surfaceAllowedOps }), // F1
...await readInstructionContent(engine),
}),
diff --git a/test/remember-share-gst2243.test.ts b/test/remember-share-gst2243.test.ts
index 78a2c5ee65..b5d2e3dbfd 100644
--- a/test/remember-share-gst2243.test.ts
+++ b/test/remember-share-gst2243.test.ts
@@ -25,6 +25,8 @@ import { addMember, bindCredential } from '../src/core/access/members.ts';
import { prepareMemoryMutation } from '../src/core/persistence/memory-prepare.ts';
import { linkMember } from '../src/core/access/actor.ts';
import type { AuthInfo } from '../src/core/ops/contract.ts';
+import { ambientOptsFrom, writebackCaller } from '../src/core/facts/writeback-config.ts';
+import { buildAmbientWritebackSection } from '../src/core/facts/writeback-instructions.ts';
import { testBackends } from './helpers/test-backends.ts';
import { isolatedPersistencePostgres } from './helpers/persistence-postgres.ts';
@@ -171,6 +173,24 @@ for (const kind of testBackends()) {
expect(await factRow('canarymixedtwo')).toBeUndefined();
}, 120_000);
+ test('a QM service acting for a member is told both cases, and its plain remember with visibility "world" is refused with the exact retry', async () => {
+ const opts = ambientOptsFrom({ enabled: true, mode: 'salient', transient_ttl: '3d', visibility: 'world' } as never, { remember: true, extractFacts: true, ...writebackCaller(await verify(tokens.qm!)) });
+ const section = buildAmbientWritebackSection(opts!);
+ expect(section).toContain('share: true');
+ expect(section).toContain('visibility: "world"');
+ expect(writebackCaller(await verify(tokens.plain!))).toEqual({});
+ expect(writebackCaller(await verify(tokens.alice!))).toEqual({ member: true });
+ const world = await remember(who.alice(), 'Acme asked for audit logs canaryactorworld', { entity: ACME, visibility: 'world' });
+ expect(world.isError).toBe(true);
+ expect(world.all).toContain('member_share_required');
+ expect(world.all).toContain('Retry the same call with share: true in place of visibility');
+ expect(await factRow('canaryactorworld')).toBeUndefined();
+ const retried = await remember(who.alice(), 'Acme asked for audit logs canaryactorworld', { entity: ACME, share: true });
+ expect([retried.isError, retried.json.page, retried.json.visibility]).toEqual([false, ACME, 'world']);
+ const kept = await remember(who.alice(), 'Acme audit worried me canaryactorkept', { entity: ACME });
+ expect([kept.isError, kept.json.page, kept.json.visibility]).toEqual([false, 'memory/members/alice-example', 'private']);
+ }, 120_000);
+
test('QM memory_write, which takes no share, still saves on the member page, and share is on the starter surface', async () => {
const out = await call(who.alice(), 'memory_write', { facts: [{ fact: 'Alice prefers async standups canaryqmwrite', provenance: 'qm test' }], idempotency_key: randomUUID() });
expect(out.isError).toBe(false);