Garry's Opinionated OpenClaw/Hermes Agent Brain
TypeScript
/**
* `remember` with `items[]`: save several facts in one call (the
* pre-compaction "save what matters" path). Additive to the frozen
* MEMORY_VERBS v1 `remember` contract: a call without `items` is unchanged.
*
* Semantics:
* - every item is validated (same rules as a single remember) before any is
* admitted; one invalid item refuses the whole call and writes nothing;
* - each item is then admitted as its own write request with a
* deterministic child request_id derived from the caller's request_id and
* the item index, so replaying the same request_id replays each child
* (committed children return their receipt, nothing is written twice);
* - each item's receipt is compact (status, fact id, entity, the fact it
* superseded, warnings, and the write state only when it is not
* committed); repeated hints appear
* once at the top level;
* - publication is per item: the response reports each item's status and
* `partial: true` when some failed. Replaying the same request_id returns
* the same per-item outcomes; failed items are resubmitted in a new call
* with a new request_id.
*/
import { createHash, randomUUID } from 'node:crypto';
import type { OperationContext } from './operations.ts';
import { OperationError } from './ops/contract.ts';
import { clientRequestIdOf, parseWriteRequestId } from './persistence/preconditions.ts';
import { CLAIM_PARAM_KEYS, claimColumns } from './facts/typed-claim.ts';
import { withRefreshFenceBudget } from './persistence/admission-retry.ts';
export const REMEMBER_BATCH_MAX = 20;
const CLAIM_KEYS: readonly string[] = CLAIM_PARAM_KEYS;
const ITEM_KEYS = new Set(['fact', 'provenance', 'entity', 'infer_entity', 'kind', 'ttl', 'visibility', 'share', 'content_origin', 'valid_from', 'replaces', ...CLAIM_KEYS]);
/** #7432: every per-item field but the claim, `replaces` and the typed claim keys is also a top-level default (an item's own value wins); `source_id` is top-level only. */
const SHARED_KEYS = [...ITEM_KEYS].filter(key => key !== 'fact' && key !== 'replaces' && !CLAIM_KEYS.includes(key)).concat('source_id');
/** Deterministic UUID for child `index` of a batch request (stable across replays). */
export function childRequestId(requestId: string, index: number): string {
const h = createHash('sha256').update(`${requestId}\u0000remember-item\u0000${index}`).digest('hex');
// RFC 4122 layout with version 5 / variant bits so it reads as a UUID everywhere.
return `${h.slice(0, 8)}-${h.slice(8, 12)}-5${h.slice(13, 16)}-${((parseInt(h.slice(16, 18), 16) & 0x3f) | 0x80).toString(16)}${h.slice(18, 20)}-${h.slice(20, 32)}`;
}
type Handler = (ctx: OperationContext, p: Record<string, unknown>) => Promise<unknown>;
export interface BatchItemResult {
index: number;
status: string;
request_id: string;
[key: string]: unknown;
}
/** Runs a remember batch through the single-item handler. */
export async function runRememberBatch(ctx: OperationContext, p: Record<string, unknown>, single: Handler,
verbError: (code: string, message: string, suggestion: string) => Error): Promise<Record<string, unknown>> {
const items = p.items;
if (!Array.isArray(items) || items.length < 1 || items.length > REMEMBER_BATCH_MAX) {
throw verbError('invalid_params', `items must be an array of 1 to ${REMEMBER_BATCH_MAX} facts.`,
'Pass items: [{ "fact": "...", "entity": "..." }, ...] with provenance on each item or once at the top level.');
}
if (typeof p.fact === 'string' && p.fact.trim()) {
throw verbError('invalid_params', 'Pass either fact or items, not both.', 'Move the single fact into items, or drop items.');
}
if (p.replaces !== undefined) {
throw verbError('invalid_params', 'replaces names one fact, so it cannot apply to a whole batch.',
'Put replaces on the item it belongs to: items: [{ "fact": "...", "replaces": "<fact_id>" }].');
}
const sharedClaim = CLAIM_KEYS.filter(key => p[key] !== undefined);
if (sharedClaim.length) {
throw verbError('invalid_params', `${sharedClaim.join(', ')} describe one fact, so they cannot apply to a whole batch.`,
'Put the typed claim on the item it belongs to: items: [{ "fact": "...", "claim_metric": "mrr", "claim_value": 50000 }].');
}
// #6280: an unusable request_id refuses the batch before any write (F6 accepts a UUID or a printable client id).
if (p.request_id !== undefined) parseWriteRequestId(p.request_id);
const shared: Record<string, unknown> = {};
for (const key of SHARED_KEYS) if (p[key] !== undefined) shared[key] = p[key];
const normalized = items.map((raw, index) => {
// A bare string is the common shorthand for one fact.
if (typeof raw === 'string') return { ...shared, fact: raw };
if (!raw || typeof raw !== 'object' || Array.isArray(raw)) {
throw verbError('invalid_params', `items[${index}] must be an object.`, 'Each item is { "fact": "...", optional entity, kind, ttl, visibility, provenance, content_origin, valid_from }.');
}
const extra = Object.keys(raw).filter(k => !ITEM_KEYS.has(k));
if (extra.length) throw verbError('invalid_params', `items[${index}] has unknown field(s): ${extra.join(', ')}.`,
`${extra.includes('text') ? 'Rename text to fact. ' : ''}Allowed item fields: ${[...ITEM_KEYS].join(', ')}.`);
return { ...shared, ...(raw as Record<string, unknown>) };
});
// All-or-none validation before any admission.
for (const [index, item] of normalized.entries()) {
try { await single({ ...ctx, dryRun: true }, item); } catch (e) {
if (e instanceof OperationError) e.message = `items[${index}]: ${e.message} Nothing was saved; fix that item and resend the whole batch.`;
throw e;
}
}
if (ctx.dryRun) return { dry_run: true, action: 'remember', items: normalized.length, protocol_version: 1 };
// F6: child ids derive from the root string the client sent, so an accepted batch replays to the same receipts.
const rootId = typeof p.request_id === 'string' ? p.request_id : randomUUID();
const requestId = parseWriteRequestId(rootId)!;
const clientRequestId = clientRequestIdOf(rootId);
const results: BatchItemResult[] = [];
const hints = new Set<string>();
const failures: Array<{ index: number; error: OperationError }> = [];
// GST-1387: the items share one refresh-fence wait, so a fenced checkout delays the batch once, not once per item.
await withRefreshFenceBudget(async () => { for (const [index, item] of normalized.entries()) {
const child = childRequestId(rootId, index);
try {
const out = await single(ctx, { ...item, request_id: child }) as Record<string, unknown>;
// Compact per-item receipt: a batch lands in the agent's context, so it carries what the agent acts on, not the full single-fact envelope.
if (typeof out?.hint === 'string') hints.add(out.hint);
results.push({
index, request_id: child, status: String(out?.status ?? 'saved'),
...(out?.id !== undefined ? { id: out.id } : {}),
...(out?.entity_slug !== undefined ? { entity_slug: out.entity_slug } : {}),
...(out?.page !== undefined ? { page: out.page } : {}), ...(out?.visibility !== undefined ? { visibility: out.visibility } : {}),
// GST-2446: where the item landed (a page file, or the database alone and why), as the single form reports it.
...(out?.persistence !== undefined ? { persistence: out.persistence } : {}), ...(out?.write_through !== undefined ? { write_through: out.write_through } : {}),
...(out?.superseded_fact_id !== undefined ? { superseded_fact_id: out.superseded_fact_id } : {}), ...claimColumns(out),
...(Array.isArray(out?.warnings) && out.warnings.length ? { warnings: out.warnings } : {}),
...(out?.valid_until ? { valid_until: out.valid_until } : {}),
...(typeof out?.state === 'string' && out.state !== 'committed' ? { state: out.state, retry_after_ms: out.retry_after_ms ?? null } : {}),
});
} catch (e) {
if (!(e instanceof OperationError)) throw e;
// #7248: an accepted item still publishing is pending, not failed; resending it would save it twice.
if (e.writeError === 'write_pending' && e.writeRequest) {
results.push({ index, request_id: child, status: 'pending', state: e.writeRequest.state, retry_after_ms: e.writeRequest.retry_after_ms ?? null,
...(e.writeRequest.target ? { target: e.writeRequest.target } : {}) });
continue;
}
failures.push({ index, error: e });
results.push({ index, request_id: child, status: 'failed', error: { code: e.code, message: e.message, ...(e.canonical ? { canonical: e.canonical } : {}), ...(e.retryable !== undefined ? { retryable: e.retryable } : {}), ...(e.writeError ? { write_error: e.writeError } : {}), ...(e.detail ? { detail: e.detail } : {}), ...(e.suggestion ? { suggestion: e.suggestion } : {}), ...(e.withdrawn ? { withdrawn: e.withdrawn } : {}) } });
}
} });
const failed = results.filter(r => r.status === 'failed').length;
const pending = results.filter(r => r.status === 'pending').length;
// GST-1387: a batch that saved nothing is a refusal on every surface (CLI exit non-zero, MCP isError), never a success
// envelope; its first item's error keeps that item's code and fix. An item with a receipt (accepted, or its outcome
// unknown) keeps the per-item envelope so its child request_id is never lost.
if (failures.length && failed === results.length && failures.every(f => !f.error.writeRequest && f.error.writeError !== 'write_outcome_unknown')) {
const [{ index, error }] = failures as [{ index: number; error: OperationError }];
// A fence refusal names the batch's request_id, never an item's derived id: a retry under an item's id derives new
// item ids, so retrying it and the batch's own id would save every item twice.
if (error.requestId === childRequestId(rootId, index)) {
const child = error.requestId;
error.message = error.message.replaceAll(child, () => rootId);
error.suggestion = error.suggestion?.replaceAll(child, () => rootId);
if (error.fix) error.fix = { ...error.fix, why: error.fix.why.replaceAll(child, () => rootId) };
error.requestId = rootId;
}
error.message = `items[${index}]: ${error.message} None of the ${results.length} item(s) was saved.`;
throw error;
}
return {
...(failures.length ? { status: 'error', error: failures[0]!.error.code, code: failures[0]!.error.code,
message: `${failed} of ${results.length} item(s) failed (first: items[${failures[0]!.index}] ${failures[0]!.error.code}); see items[].error. Items not marked failed are stored.` } : {}),
protocol_version: 1,
request_id: requestId,
...(clientRequestId ? { client_request_id: clientRequestId } : {}),
items: results,
saved: results.length - failed - pending,
failed,
...(pending ? { pending } : {}),
partial: failed > 0 && failed < results.length,
...(hints.size ? { hints: [...hints] } : {}),
...(failed > 0 ? { next: 'Fix each failed item as its error says, then send only the failed items in a new remember call with a new request_id; the saved items are already stored.' }
: pending > 0 ? { next: 'Pending items are accepted and still publishing: poll get_write_request with each pending item\'s request_id; do not send them again.' } : {}),
};
}