Garry's Opinionated OpenClaw/Hermes Agent Brain
TypeScript
/**
* MEMORY_VERBS v1 — the frozen memory protocol verbs (Cathedral 1).
*
* Four first-class Operations (`remember`, `entity`, `synthesize`, `forget`)
* that join the extended `recall` op (operations.ts) as the five-verb façade
* over the operation catalog. Frozen contract: docs/protocol/MEMORY_VERBS_v1.md
* — field names and semantics in v1 never change; additions are forever-
* additive; `protocol_version` rides every response; errors carry enumerated
* codes + populated `suggestion` (agents read it and self-correct).
*
* These are ordinary Operations: they inherit trust-boundary fail-closed
* semantics (ctx.remote), scope enforcement, and source isolation like every
* other op. `gbrain serve --surface verbs` exposes exactly the ops marked
* `verb: true`.
*
* Import-cycle note: operations.ts spreads these into its `operations` array
* at MODULE-EVAL time, so this file must be a RUNTIME LEAF — it may import
* operations.ts types (erased) but never its values statically. Handlers load
* verbError/parseTtlParam/sourceScopeOpts via dynamic import from the ops
* modules that define them (never the whole operations.ts registry, which a
* one-shot CLI call would otherwise evaluate in full, #7147); the import
* resolves after both modules finish evaluating.
* MEMORY_VERBS_VERSION lives HERE (operations.ts imports it from us) for the
* same reason. Violating this reintroduces the TDZ crash on whichever module
* evaluates second.
*/
import { recordFunnelEvent, recordRememberOutcome } from './funnel.ts';
import type { Operation } from './operations.ts';
import { WRITE_RECEIPT_SCHEMA, WRITE_REQUEST_PARAM, AGENT_CONTENT_PARAMS, CONTENT_ORIGIN_PARAM } from './persistence/params.ts';
import { WRITE_ERROR_CODES } from './persistence/types.ts';
import { isStrictIsoDateTime } from './utils.ts';
/** Frozen protocol version for the MEMORY_VERBS v1 verb set. Single source of truth. */
export const MEMORY_VERBS_VERSION = 1;
// v0.45.7 (issue #1): the frozen set grows from 5 to 7 with two ambient-recall
// verbs. The wire protocol_version STAYS 1 (additive) — MEMORY_VERBS_VERSION is
// unchanged so the five existing schemas + handlers keep stamping 1 and their
// conformance assertions (protocol_version === 1) hold.
export const VERB_NAMES = ['recall', 'remember', 'entity', 'synthesize', 'forget', 'context_pack', 'delta'] as const;
export type VerbName = (typeof VERB_NAMES)[number];
/**
* The `remember` INPUT enum — FROZEN at five by the v1 protocol contract
* (docs/protocol/MEMORY_VERBS_v1.md: "the values and their meanings stay
* fixed"). Widening the extractor/DB taxonomy does NOT widen this; a caller
* cannot write an `idea` through the verb surface.
*/
const FACT_KINDS = ['event', 'preference', 'commitment', 'belief', 'fact'] as const;
/**
* What a reader may RECEIVE. The extractor and the facts table carry `idea`
* (migration v145), so a stored idea fact flows back through `recall` — a
* response schema that omitted it would declare a contract the system itself
* violates. This is a widening for response consumers (strictly more values
* accepted), and it is deliberately a SEPARATE constant so the input freeze
* above can never drift into it.
*/
const FACT_KINDS_RESPONSE = [...FACT_KINDS, 'idea'] as const;
const PROVENANCE_MAX = 500;
const REMEMBER_CALL_SHAPE = 'A valid call: {"fact": "<one claim>", "entity": "<subject-slug>", "provenance": "<where you learned it, with the date>"}; several: items: [{fact, entity, provenance}, ...]. provenance (where the fact came from) is required.';
// ─── remember ────────────────────────────────────────────────────────────────
const remember: Operation = {
name: 'remember',
idempotent: true,
outputRedaction: 'no_stored_text',
description: 'Save {fact, provenance (required), `entity` (subject; recall needs it)} or items[]. Branch on `status`; write_pending: poll get_write_request.',
callShape: REMEMBER_CALL_SHAPE,
params: {
...AGENT_CONTENT_PARAMS,
fact: { type: 'string', description: 'One claim.' },
items: {
type: 'array',
description: '≤20 of {fact,entity,provenance,kind,ttl,visibility}',
items: { type: 'object' },
},
provenance: {
type: 'string',
// Required for a single fact (the handler refuses with provenance_required); with items it may be given per item.
description: 'Source (≤500 chars).',
},
ttl: {
type: 'string',
description: '"30d", "12h", ISO; omit = never.',
},
valid_from: {
type: 'string',
description: 'When true (ISO).',
fullSurfaceOnly: true,
},
entity: {
type: 'string',
description: 'Name or slug.',
},
infer_entity: {
type: 'boolean',
description: 'Default true.',
fullSurfaceOnly: true,
},
kind: {
type: 'string', description: 'Default fact.',
enum: [...FACT_KINDS],
},
share: {
type: 'boolean',
description: 'Members save privately, owner shared; true: all source readers recall it. Not for facts about a person.',
},
visibility: {
type: 'string',
enum: ['world', 'private'],
description: 'world (default) or private (local CLI). Members: use share.',
fullSurfaceOnly: true,
},
replaces: { type: 'string', description: 'fact_id this fact replaces (same entity, or none).', fullSurfaceOnly: true },
claim_metric: { type: 'string', description: 'Typed claim metric, e.g. mrr (with claim_value).', fullSurfaceOnly: true },
claim_value: { type: 'number', description: 'Typed claim value (finite number).', fullSurfaceOnly: true },
claim_unit: { type: 'string', description: 'Typed claim unit, e.g. USD.', fullSurfaceOnly: true },
claim_period: { type: 'string', description: 'Typed claim period, e.g. monthly.', fullSurfaceOnly: true },
},
mutating: true,
scope: 'write',
verb: true,
annotations: { title: 'remember (memory write)', idempotentHint: true },
handler: async (ctx, p) => {
const [{ verbError }, { parseTtlParam }] = await Promise.all([import('./ops/contract.ts'), import('./ops/facts.ts')]);
if (p.items !== undefined) {
const { runRememberBatch } = await import('./remember-batch.ts');
return runRememberBatch(ctx, p, remember.handler, (code, message, suggestion) => verbError(code as never, message, suggestion));
}
const { unquoteFactText } = await import('./search/transcript-quote.ts');
// #8377: a fact an agent copied out of a quoted read (recall, context_pack, hot memory) is stored without the fence.
const fact = typeof p.fact === 'string' ? (ctx.remote === false ? p.fact : unquoteFactText(p.fact)).trim() : '';
if (!fact) {
throw verbError(
'invalid_params',
'fact must be a non-empty string.',
p.fact === undefined && Object.keys(p).length === 0
? 'The call arrived with no arguments; a tool call cut off at your output-token limit looks like this. Pass fact, or items with fewer entries per call.'
: `Pass the claim to remember in fact. ${REMEMBER_CALL_SHAPE}`,
);
}
// v1 contract: an absent provenance is a missing required parameter (invalid_params), an empty one is provenance_required.
if (p.provenance === undefined) {
throw verbError(
'invalid_params',
'Missing required parameter: provenance',
'Pass `provenance` as a string (where the fact came from), e.g. provenance: "<where you learned it, with the date>". With items, provenance may be given per item instead.',
);
}
const provenance = typeof p.provenance === 'string' ? p.provenance.trim() : '';
if (!provenance) {
throw verbError(
'provenance_required',
'provenance is required and must be non-empty.',
'Pass where the fact came from, e.g. provenance: "<where you learned it, with the date>" or "import: notes.md".',
);
}
if (provenance.length > PROVENANCE_MAX) {
throw verbError(
'invalid_params',
`provenance exceeds ${PROVENANCE_MAX} chars (got ${provenance.length}).`,
'Shorten the attribution — provenance is a pointer, not a transcript.',
);
}
const kind = typeof p.kind === 'string' ? p.kind : 'fact';
if (!FACT_KINDS.includes(kind as (typeof FACT_KINDS)[number])) {
throw verbError(
'invalid_params',
`kind "${kind}" is not a fact kind.`,
`Use one of: ${FACT_KINDS.join(' | ')}.`,
);
}
const visibility = typeof p.visibility === 'string' ? p.visibility : 'world';
if (visibility !== 'world' && visibility !== 'private') {
throw verbError(
'invalid_params',
`visibility "${visibility}" is not valid.`,
'Use "world" (default — agents can recall it) or "private" (local CLI reads only).',
);
}
if (p.share !== undefined && typeof p.share !== 'boolean') {
throw verbError('invalid_params', 'share must be true or false.', 'Pass share: true to save the fact for everyone who reads this source, or omit it.');
}
if (p.share === true && p.visibility === 'private') {
throw verbError('invalid_params', 'share: true and visibility "private" contradict each other; nothing was saved.', 'Pass share: true to share the fact, or visibility "private" to keep it to yourself, not both.');
}
// GST-2249 W1: a save made for a person (x-qm-actor) stays on that person's member page; sharing it is a write every
// reader of the source sees, made with no owner approval, so it is refused like the direct page writes.
const memberFacts = await import('./access/member-facts.ts');
const attested = ctx.attestedOp !== 'memory_write' && (await import('./search/private-visibility.ts')).currentCallerAccess().actor != null;
if (attested && p.share === true) throw memberFacts.attestedShareRefused(verbError);
// GST-2243: a member shares only with share: true, so its explicit visibility "world" is refused, never quietly made private.
// GST-2346 D1: the brain owner speaking for itself is not refused; its "world" is saved shared.
if (p.share !== true && p.visibility === 'world' && ctx.attestedOp !== 'memory_write' && memberFacts.memberFactPage(ctx) && !memberFacts.ownerSpeaksForItself(ctx)) {
if (attested) throw memberFacts.attestedShareRefused(verbError);
// GST-2897 B: a fact about another member is never pointed at share: true, which holds it for the brain owner.
const subject = typeof p.entity === 'string' ? await memberFacts.otherMemberSubject(ctx.engine, p.entity.trim()) : null;
if (subject) {
throw Object.assign(verbError('invalid_params', 'remember: a member credential cannot save a fact with visibility "world"; nothing was saved.',
`${p.entity} is about member ${subject}. Retry with no visibility to keep the fact on your own member page; a shared fact about another member is held private until the brain owner confirms it.`),
{ reason: 'member_share_required' });
}
throw Object.assign(verbError('invalid_params', 'remember: a member credential shares a fact with share: true, not visibility "world"; nothing was saved.',
'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)) {
throw verbError(
'invalid_params',
'valid_from must be an ISO 8601 date or time in years 0001-9999.',
'Pass when the fact was said or became true as YYYY-MM-DD or YYYY-MM-DDTHH:MM[:SS][Z|±HH:MM], e.g. valid_from: "2026-03-01", or omit it.',
);
}
const claim = (await import('./facts/typed-claim.ts')).parseClaimParams(ctx.remote === false ? p : { ...p,
...Object.fromEntries((['claim_metric', 'claim_unit', 'claim_period'] as const).flatMap(k => typeof p[k] === 'string' ? [[k, unquoteFactText(p[k] as string)]] : [])) });
if (p.content_origin !== undefined && !CONTENT_ORIGIN_PARAM.enum!.includes(p.content_origin as string)) {
throw verbError('invalid_params', `content_origin must be one of ${CONTENT_ORIGIN_PARAM.enum!.join(', ')}; got ${JSON.stringify(p.content_origin)}.`,
'Pass content_origin as user_said, tool_output (text from a web page, email, file or other tool) or inferred, or omit it.');
}
const replaces = typeof p.replaces === 'string' ? p.replaces.trim() : typeof p.replaces === 'number' ? String(p.replaces) : undefined;
if (replaces !== undefined && (!/^\d+$/.test(replaces) || Number(replaces) <= 0)) {
throw verbError(
'not_found',
`No fact with id "${String(p.replaces)}" to replace.`,
'Pass the opaque fact_id from remember or recall (facts[].fact_id), or omit replaces.',
);
}
if (ctx.dryRun) {
parseTtlParam(p.ttl); // Dry runs still validate without admitting intent.
return {
dry_run: true,
action: 'remember',
fact,
protocol_version: MEMORY_VERBS_VERSION,
};
}
const { submitRememberMutation } = await import('./persistence/memory-mutations.ts');
const { runMemoryWrite } = await import('./persistence/verb-errors.ts');
const result = await runMemoryWrite(() => submitRememberMutation(ctx, { ...p, fact, provenance, kind, visibility, ...claim, ...(replaces !== undefined ? { replaces } : {}) },
undefined, { visibilityDefaulted: typeof p.visibility !== 'string' }));
// F8: the explanation the CLI formatter prints, as a model-visible notice.
if ((result as { degraded_dedup?: boolean } | null)?.degraded_dedup) {
const { degradedDedupNotice } = await import('./interop-notices.ts');
ctx.emitNotice?.(degradedDedupNotice(ctx.config));
}
if (visibility === 'private' && ctx.remote === false && (result as { status?: string } | null)?.status !== 'duplicate') {
const { privateFactNotice } = await import('./interop-notices.ts');
ctx.emitNotice?.(privateFactNotice((result as { id?: string | number } | null)?.id));
}
recordRememberOutcome(result);
return result;
},
cliHints: { name: 'remember', positional: ['fact'] },
};
// ─── entity ──────────────────────────────────────────────────────────────────
const entity: Operation = {
name: 'entity',
mutating: false,
idempotent: true,
outputRedaction: 'retrieval',
description: 'Person/company/account card, zero LLM. Previews are not evidence: fetch the page before stating status or dates. Miss: found:false with near matches (create_safety). Facts: recall.',
params: {
name: { type: 'string', description: 'Name, alias or slug.' },
names: { type: 'array', items: { type: 'string' }, description: 'Or up to 50 names/codes at once: compact rows.' },
source_id: { type: 'string', description: 'Read only this source. Default: your source first, then every source you can read.', fullSurfaceOnly: true },
prefer_source_id: { type: 'string', description: 'Source to try first (thin clients send .gbrain-source here); never narrows.', fullSurfaceOnly: true },
variants: { type: 'boolean', description: 'false: exact names only. Default true: with no exact match, one unambiguous name variant (card.match says which).', fullSurfaceOnly: true },
},
scope: 'read',
verb: true,
annotations: { title: 'entity (card lookup, zero LLM)', readOnlyHint: true },
handler: async (ctx, p) => {
const { verbError } = await import('./ops/contract.ts');
// #6723: resolve across the caller's readable sources (home first) unless source_id pins one.
const { ambientMissNotice, entitySources } = await import('./verbs/entity-source.ts');
const walk = await entitySources(ctx, p, 'entity');
const ambientMiss = (misses: Array<{ name: string; foundIn?: string }>) => {
const notice = ambientMissNotice('entity', walk, misses.filter(m => m.foundIn !== walk.ambient?.sourceId));
if (notice) ctx.emitNotice?.(notice);
};
if (p.names !== undefined) {
const { ENTITY_NAMES_MAX, lookupEntityNames } = await import('./verbs/entity-names.ts');
const names = Array.isArray(p.names) ? p.names.filter((n): n is string => typeof n === 'string' && n.trim() !== '') : [];
if (p.name !== undefined || !names.length || names.length > ENTITY_NAMES_MAX) {
throw verbError('invalid_params', `names must be 1 to ${ENTITY_NAMES_MAX} non-empty strings, without name.`,
`Pass either name: "Alice Example" for one full card, or names: ["Alice Example", "WGCO"] (up to ${ENTITY_NAMES_MAX}) for compact rows.`);
}
const t0 = Date.now();
const out = await lookupEntityNames(ctx.engine, walk.home, names, { remote: ctx.remote !== false, sources: walk.sources, surfaceCeiling: ctx.surfaceCeiling, variants: p.variants !== false,
emitNotice: n => ctx.emitNotice?.(n) });
ambientMiss(out.results.map(r => ({ name: r.name, ...(r.found ? { foundIn: r.source_id } : {}) })));
return { protocol_version: 1, latency_ms: Date.now() - t0, ...out };
}
const name = typeof p.name === 'string' ? p.name.trim() : '';
if (!name) {
throw verbError(
'invalid_params',
'name must be a non-empty string.',
'Pass the entity to look up, e.g. name: "Alice Example" or name: "people/alice-example".',
);
}
const t0 = Date.now();
const { buildEntityCard } = await import('./verbs/entity-card.ts');
const result = await buildEntityCard(ctx.engine, walk.home, name, {
remote: ctx.remote !== false, includeReferences: true, surfaceCeiling: ctx.surfaceCeiling, sources: walk.sources, variants: p.variants !== false,
omitQuarantined: ctx.remote !== false, // #5575: like get_page, a remote reader never gets a quarantined page's card
emitNotice: n => ctx.emitNotice?.(n),
});
const coverage = result.card?.coverage ?? result.coverage;
if (coverage) {
const { mentionCoverageNotice } = await import('./mentions/coverage.ts');
const notice = mentionCoverageNotice(coverage, result.card?.entity.type);
if (notice) ctx.emitNotice?.(notice);
}
ambientMiss([{ name, ...(result.source_id ? { foundIn: result.source_id } : {}) }]);
if (result.card?.identity_siblings?.capped) {
const { siblingsCappedNotice } = await import('./verbs/entity-card-identity.ts');
ctx.emitNotice?.(siblingsCappedNotice(result.card.entity.slug));
}
return {
protocol_version: MEMORY_VERBS_VERSION,
found: result.found,
latency_ms: Date.now() - t0,
...(result.card ? { card: result.card } : {}),
...(result.suggestions !== undefined ? { suggestions: result.suggestions } : {}),
...(!result.card && result.coverage ? { coverage: result.coverage } : {}),
...(result.text_mentions ? { text_mentions: result.text_mentions } : {}),
...(result.ambiguous ? { ambiguous: true } : {}),
};
},
cliHints: { name: 'entity', positional: ['name'] },
};
// ─── synthesize ──────────────────────────────────────────────────────────────
// [WP2/T5] compose-failure status → the machine-stable warning code named in
// the empty-gather `unavailable` error message. Freeform tails (provider
// messages) ride `detail` only; the message carries the code.
const SYNTHESIS_FAILURE_CODES: Record<string, string> = {
not_json: 'LLM_OUTPUT_NOT_JSON',
output_truncated: 'LLM_OUTPUT_TRUNCATED',
empty_answer: 'SYNTHESIS_EMPTY_ANSWER',
llm_error: 'LLM_CALL_FAILED',
model_unusable: 'MODEL_NOT_USABLE',
no_llm: 'NO_ANTHROPIC_API_KEY',
};
const synthesize: Operation = {
name: 'synthesize',
mutating: false,
idempotent: true,
outputRedaction: 'retrieval',
description: '[EXPENSIVE / SLOW: LLM calls] Cited answer to a broad question across pages. Lookups: recall or entity.',
params: {
question: { type: 'string', description: 'The question.', required: true },
since: { type: 'string', description: 'Window start (ISO 8601).' },
until: { type: 'string', description: 'Window end (ISO 8601).' },
},
scope: 'read',
verb: true,
annotations: { title: 'synthesize (slow, costly — LLM-backed)', readOnlyHint: true },
handler: async (ctx, p) => {
const [{ verbError }, { sourceScopeOpts }] = await Promise.all([import('./ops/contract.ts'), import('./ops/context.ts')]);
const question = typeof p.question === 'string' ? p.question.trim() : '';
if (!question) {
throw verbError(
'invalid_params',
'question must be a non-empty string.',
'Pass the question to synthesize an answer for, e.g. question: "what is our payments strategy?".',
);
}
const scope = sourceScopeOpts(ctx);
const { runThink } = await import('./think/index.ts');
const { embedQueryWithPrefix } = await import('./search/query-prefix.ts');
// Remote-safe delegation: save/take are NEVER offered through this verb,
// for any caller — the verb is a pure read.
const result = await runThink(ctx.engine, {
question,
since: p.since ? String(p.since) : undefined,
until: p.until ? String(p.until) : undefined,
takesHoldersAllowList: ctx.takesHoldersAllowList,
...(scope.sourceId !== undefined ? { sourceId: scope.sourceId } : {}),
...(scope.sourceIds !== undefined ? { allowedSources: scope.sourceIds } : {}),
// Fail-closed: only a context that explicitly says local gets local.
remote: ctx.remote !== false,
// #3734: activate takes' vector retrieval arm for the synthesize verb.
embedQuestion: (q) => embedQueryWithPrefix(ctx.engine, q),
});
// [c10] runThink degrades gracefully to a no-LLM stub RESULT; the protocol
// contract converts that state into an explicit `unavailable` error so
// agents branch on configure/retry instead of relaying a fake answer.
// Deliberately unconditional (fires even with a non-empty gather): an
// unconfigured key routed to the extractive fallback would be masked on
// every call and never get fixed.
if (result.warnings.includes('NO_ANTHROPIC_API_KEY')) {
// F9: a key enables paid calls, so the fix asks; the key never rides a command line.
const { chatKeyFix } = await import('./interop-notices.ts');
const e = verbError(
'unavailable',
'synthesize needs an LLM and none is configured.',
'Ask the user whether to add a chat-model API key (Anthropic or OpenAI; each synthesized answer is a paid call). Meanwhile recall and entity work without one: answer from their results.',
'chat gateway unconfigured (NO_ANTHROPIC_API_KEY)',
);
e.fix = chatKeyFix();
throw e;
}
// Best-effort cost block [E5/m3]: actual tokens when the gateway reported
// usage, priced via the canonical table; nulls when accounting is absent.
const { canonicalLookup } = await import('./model-pricing.ts');
const usage = result.usage ?? null;
const pricing = canonicalLookup(result.modelUsed);
const usdEstimate =
usage && pricing
? (usage.input_tokens * pricing.input + usage.output_tokens * pricing.output) / 1_000_000
: null;
const cost = {
model: result.modelUsed,
input_tokens: usage?.input_tokens ?? null,
output_tokens: usage?.output_tokens ?? null,
usd_estimate: usdEstimate,
};
// [WP2/T5+E2] compose-status precedence: 'ok' → the synthesized answer;
// any compose failure with a NON-EMPTY gather → the extractive fallback
// (quotes/cites ONLY gathered pages); compose failure with an EMPTY
// gather → typed error. An answer is NEVER fabricated from nothing
// (ENG-19). Defensive ?? 'ok' mirrors synthesisOk's back-compat posture.
const status = result.synthesis_status ?? 'ok';
const { recordThinkAnswer, feedbackMetaFields } = await import('./feedback/record.ts');
const feedbackMeta = feedbackMetaFields(await recordThinkAnswer(ctx, 'synthesize', result));
if (status !== 'ok') {
if (result.extractive) {
return {
answer: result.extractive.answer,
sources: result.extractive.citations.map(c => c.page_slug),
citations: sourceQualifiedCitations(result.extractive.citations),
gaps: result.gaps,
cost,
synthesis_status: 'extractive_fallback',
pages_gathered: result.pagesGathered,
takes_gathered: result.takesGathered,
evidence_truncated: result.evidence_truncated ?? false,
warnings: result.warnings,
...feedbackMeta,
protocol_version: MEMORY_VERBS_VERSION,
};
}
throw verbError(
'unavailable',
`retrieved ${result.pagesGathered} pages; compose failed: ${SYNTHESIS_FAILURE_CODES[status] ?? status}`,
'The LLM compose step failed and retrieval found nothing to fall back on. Rephrase or broaden the question (or the since/until window); if the code names the model or provider, fix the model config and retry.',
result.warnings.length > 0 ? result.warnings.join('; ') : undefined,
);
}
return {
answer: result.answer,
...(result.answer_raw !== undefined ? { answer_raw: result.answer_raw, quote_check: result.quote_check, unverified_quotes: result.unverified_quotes } : {}),
sources: result.citations.map(c => c.page_slug),
citations: sourceQualifiedCitations(result.citations),
gaps: result.gaps,
cost,
synthesis_status: 'ok',
pages_gathered: result.pagesGathered,
takes_gathered: result.takesGathered,
evidence_truncated: result.evidence_truncated ?? false,
warnings: result.warnings,
...feedbackMeta,
protocol_version: MEMORY_VERBS_VERSION,
};
},
cliHints: { name: 'synthesize', positional: ['question'] },
};
/** #5461: `sources[]` stays slugs (frozen); `citations[]` is the same list, source-qualified. */
function sourceQualifiedCitations(citations: Array<{ page_slug: string; row_num: number | null; source_id?: string | null }>) {
return citations.map(c => ({ slug: c.page_slug, source_id: c.source_id ?? null, row_num: c.row_num }));
}
// ─── forget ──────────────────────────────────────────────────────────────────
const forget: Operation = {
name: 'forget',
idempotent: true,
outputRedaction: 'no_stored_text',
description: 'Expire a remembered fact by its fact_id (never a page slug). Idempotent; the audit trail is kept.',
params: {
request_id: WRITE_REQUEST_PARAM,
id: { type: 'string', required: true, description: 'fact_id from remember or recall.' },
reason: { type: 'string', description: 'Audit note (default "forgotten").' },
semantic_review: { type: 'boolean', description: 'false: skip overnight rewording review.', fullSurfaceOnly: true },
},
mutating: true,
scope: 'write',
verb: true,
annotations: { title: 'forget (expire a fact)', destructiveHint: true, idempotentHint: true },
handler: async (ctx, p) => {
const { verbError } = await import('./ops/contract.ts');
const rawId = typeof p.id === 'string' ? p.id.trim() : typeof p.id === 'number' ? String(p.id) : '';
const numericId = Number(rawId);
if (!rawId || !Number.isInteger(numericId) || numericId <= 0) {
throw verbError(
'not_found',
`No fact with id "${String(p.id)}".`,
'Pass the opaque string id returned by remember or recall (facts[].fact_id) — page slugs are not fact ids.',
);
}
const reason = typeof p.reason === 'string' && p.reason.trim() ? p.reason.trim() : null;
if (ctx.dryRun) {
return { dry_run: true, action: 'forget', id: rawId, protocol_version: MEMORY_VERBS_VERSION };
}
const { submitForgetMutation } = await import('./persistence/memory-mutations.ts');
const { runMemoryWrite } = await import('./persistence/verb-errors.ts');
const out = await runMemoryWrite(() => submitForgetMutation(ctx, 'forget', { ...p, id: rawId, ...(reason ? { reason } : {}) }));
recordFunnelEvent('withdrawal');
return out;
},
// NO cliHints: `gbrain forget` is a CLI_ONLY command (recall.ts runForget)
// that dispatches BEFORE cliOps — a cliHint here would be silently
// shadowed. The CLI surface for forgetting stays the existing command;
// this verb is the MCP/protocol surface.
};
export const verbOperations: Operation[] = [remember, entity, synthesize, forget];
// ─── RESPONSE_SCHEMAS — the protocol's response-shape registry [c8] ─────────
//
// `Operation` carries input params only; response envelopes live HERE, hand-
// authored, and conformance validates LIVE responses against this registry so
// registry-vs-code drift is caught by the same fixtures that certify servers.
// Field names and semantics are FROZEN (additive-forever); enum values are
// part of the contract.
const EVIDENCE_ENUM = ['alias_hit', 'exact_title_match', 'high_vector_match', 'keyword_exact', 'weak_semantic'];
const CREATE_SAFETY_ENUM = ['exists', 'probable', 'unknown'];
const STATUS_ENUM = ['inserted', 'duplicate', 'superseded'];
// v0.45.x (WP2/T5+E2) — additive-forever. The verb emits 'ok' or
// 'extractive_fallback'; the remaining compose-failure values ride the
// non-verb `think` surface (the verb converts them to the extractive
// fallback or a typed `unavailable` error) and stay enum-listed so any
// v1 server emitting them validates.
const SYNTHESIS_STATUS_ENUM = [
'ok', 'empty_answer', 'not_json', 'output_truncated', 'no_llm', 'model_unusable', 'llm_error', 'extractive_fallback',
];
/** `coverage` on entity cards and misses (mentions/coverage.ts). */
const COVERAGE_SCHEMA = {
type: 'object',
required: ['state', 'pending_pages', 'last_pass_at'],
properties: {
state: { type: 'string', enum: ['complete', 'pending', 'disabled', 'type_not_linkable', 'failed'] },
pending_pages: { type: 'integer' },
last_pass_at: { type: ['string', 'null'] },
degraded: { type: 'boolean', const: true },
},
} as const;
/** One `referenced_by` row (mentions/referrers.ts). */
const REFERENCE_ROW_SCHEMA = {
type: 'object',
required: ['slug', 'title', 'type', 'canonical_type', 'date', 'date_source', 'preview', 'trust_tier', 'origin'],
properties: {
slug: { type: 'string' }, title: { type: 'string' }, type: { type: ['string', 'null'] }, canonical_type: { type: 'string' },
date: { type: ['string', 'null'] }, date_source: { type: 'string' }, preview: { type: 'string' },
trust_tier: { type: 'string' }, origin: { type: 'string' }, unconfirmed: { type: 'boolean', const: true },
},
} as const;
/** One record group (verbs/entity-references.ts): referring pages of an enrolled record type, newest page date first. */
const RECORD_GROUP_SCHEMA = {
type: 'object',
required: ['canonical_type', 'total', 'rows'],
properties: {
canonical_type: { type: 'string' },
total: { type: 'integer' },
rows: { type: 'array', items: { type: 'object', required: ['slug', 'title', 'date', 'date_source'], properties: {
slug: { type: 'string' }, title: { type: 'string' }, date: { type: ['string', 'null'] }, date_source: { type: 'string' },
page_status: { type: 'string' },
amends: { type: 'array', items: { type: 'object', required: ['slug'], properties: { slug: { type: 'string' }, since: { type: 'string' } } } },
supersedes: { type: 'array', items: { type: 'object', required: ['slug'], properties: { slug: { type: 'string' } } } },
} } },
capped: { type: 'string', enum: ['per_page', 'per_call'] },
next: { type: 'object', required: ['tool', 'arguments'], properties: {
tool: { type: 'string', const: 'get_backlinks' }, arguments: { type: 'object' }, requires_surface: { type: 'string', enum: ['starter'] } } },
},
} as const;
const REFERENCES_UNAVAILABLE_SCHEMA = { type: 'string', enum: ['deadline', 'read_failed'] } as const;
const RECALL_BUDGET_ARM_SCHEMA = {
type: 'object',
required: ['candidates', 'kept', 'dropped', 'used'],
properties: {
candidates: { type: 'integer', minimum: 0, description: 'Authorized, filtered, limit-capped candidates before packing.' },
kept: { type: 'integer', minimum: 0 },
dropped: { type: 'integer', minimum: 0 },
used: { type: 'integer', minimum: 0, description: 'Estimated tokens in retained evidence, excluding the JSON envelope.' },
},
};
export const RESPONSE_SCHEMAS: Record<VerbName, Record<string, unknown>> = {
recall: {
type: 'object',
required: ['facts', 'total', 'protocol_version'],
properties: {
protocol_version: { type: 'integer', const: MEMORY_VERBS_VERSION },
total: { type: 'integer' },
facts: {
type: 'array',
items: {
type: 'object',
required: ['id', 'fact', 'kind', 'fact_id', 'provenance'],
properties: {
id: { type: 'integer', description: 'LEGACY numeric id (pre-v1 consumers). Use fact_id.' },
fact_id: { type: 'string', description: 'Opaque protocol id — the value forget accepts.' },
fact: { type: 'string' },
kind: { type: 'string', enum: FACT_KINDS_RESPONSE as unknown as string[] },
entity_slug: { type: ['string', 'null'] },
provenance: { type: 'string' },
valid_until: { type: ['string', 'null'] },
visibility: { type: 'string', enum: ['private', 'world'] },
relevance: { type: 'number', description: 'Present when `question` was passed: cosine + term share + 0.1 when dated (about 0 to 2.1). A ranking score within this response, not a probability; not comparable across calls.' },
},
},
},
facts_order: { type: 'string', enum: ['relevance', 'newest'], description: 'How facts[] is ordered: relevance (question passed) or newest. A server without question ranking omits it.' },
facts_degraded: {
type: 'object',
description: 'Present when question ranking ran without full semantic matching, or date headers could not read when facts were said.',
properties: {
reason: { type: 'string', description: 'Why the cosine arm did not run: keyword_only_no_embedding_provider, keyword_only_embedding_disabled, embed_timeout, embed_unavailable, no_query_terms or facts_embedding_column_missing; or fact_observed_date_unavailable: date headers show observed unknown because the source-page read failed.' },
unembedded: { type: 'integer', description: 'Facts in scope without a comparable embedding (ranked by word overlap only).' },
},
},
facts_below_floor: { type: 'integer', description: 'Present when question ranking found candidate facts and none cleared the admission floor: how many. Absent when nothing matched.' },
facts_calibration: {
type: 'object',
description: 'Informational, present when question ranking used semantic matching on an embedding model whose fact admission floors were never measured: a short facts list is weaker evidence of "nothing matched". Never replaces facts_degraded.',
required: ['status', 'model_key'],
properties: {
status: { type: 'string', enum: ['unmeasured'] },
model_key: { type: 'string', description: 'provider:model@dims, the key doctor fact_admission_floors reports.' },
},
},
results: {
type: 'array',
description: 'Search arm — present only when `query` was passed.',
items: {
type: 'object',
required: ['slug', 'title', 'evidence', 'create_safety', 'provenance'],
properties: {
slug: { type: 'string' },
title: { type: ['string', 'null'] },
chunk: { type: ['string', 'null'] },
evidence: { type: 'string', enum: EVIDENCE_ENUM },
create_safety: { type: 'string', enum: CREATE_SAFETY_ENUM },
provenance: { type: 'string', description: 'Origin page slug.' },
source_id: { type: 'string', description: 'The source the hit came from (#4830; absent only when a federated read cannot name one).' },
},
},
},
search_degraded: { type: 'string', description: 'Present when the search arm fell back to keyword-only: keyword_only_no_embedding_provider (no embedding provider) or keyword_only_embedding_disabled (embeddings off by choice; no query text sent to a provider).' },
budget_tokens: { type: 'integer', description: 'Present for a positive finite numeric budget, including when its floor is zero.' },
budget_used: { type: 'integer' },
dropped_count: { type: 'integer' },
budget_packing: {
type: 'object',
description: 'Present only when a valid budget_policy is supplied. Per-arm used and dropped sums match budget_used and dropped_count when those fields exist.',
required: ['policy', 'applied', 'reason', 'facts', 'results'],
properties: {
policy: { type: 'string', enum: ['facts_first', 'query_first'], description: 'Effective policy; ineligible query_first requests fall back to facts_first.' },
applied: { type: 'boolean', description: 'Whether the requested budget policy applied, not whether all required evidence fit.' },
reason: { type: 'string', enum: ['no_query', 'no_positive_finite_budget', 'budget_below_one', 'no_candidates', 'first_items_exceed_budget', 'packed'] },
facts: RECALL_BUDGET_ARM_SCHEMA,
results: RECALL_BUDGET_ARM_SCHEMA,
},
},
},
},
remember: {
type: 'object',
required: ['id', 'status', 'status_text', 'entity_slug', 'valid_until', 'protocol_version'],
properties: {
protocol_version: { type: 'integer', const: MEMORY_VERBS_VERSION },
id: { type: 'string', description: 'Opaque fact id. On status=duplicate this is the EXISTING fact\'s id.' },
status: { type: 'string', enum: STATUS_ENUM, description: 'Branch on THIS, never on status_text.' },
status_text: { type: 'string', description: 'Human rendering of status. Display only — never branch on it.' },
entity_slug: { type: ['string', 'null'] },
valid_until: { type: ['string', 'null'], description: 'ISO 8601 or null (never expires).' },
degraded_dedup: { type: 'boolean', description: 'Present (true) when no embedding provider — near-duplicates may insert.' },
entity_inferred: { type: 'string', enum: ['mention'], description: 'Present when `entity` was omitted and the subject was inferred from an exact mention.' },
warnings: { type: 'array', items: { type: 'string', enum: ['NO_ENTITY', 'ENTITY_LINK_FAILED'] },
description: 'NO_ENTITY: saved unattributed. ENTITY_LINK_FAILED: an inferred entity could not be linked; saved unattributed.' },
hint: { type: 'string', description: 'Present with warnings: how to attribute the fact (pass `entity`).' },
superseded_fact_id: { type: 'string', description: 'Present on status=superseded: the fact this one replaced.' },
replaced_by_caller: { type: 'boolean', description: 'Present (true) when the caller named the replaced fact with `replaces`.' },
write_request: WRITE_RECEIPT_SCHEMA,
},
},
entity: {
type: 'object',
required: ['protocol_version', 'found', 'latency_ms'],
properties: {
protocol_version: { type: 'integer', const: MEMORY_VERBS_VERSION },
found: { type: 'boolean' },
latency_ms: { type: 'integer' },
card: {
type: 'object',
required: ['entity', 'aka', 'summary', 'last_touched', 'open_threads', 'edges', 'backlink_count', 'active_fact_count'],
properties: {
entity: {
type: 'object',
required: ['slug', 'title', 'type'],
properties: {
slug: { type: 'string' }, title: { type: 'string' }, type: { type: ['string', 'null'] },
// #6723 — ADDITIVE OPTIONAL: (source_id, slug) is the entity's identity.
source_id: { type: 'string' },
},
},
aka: { type: 'array', items: { type: 'string' } },
summary: { type: 'string' },
last_touched: {
type: 'object',
required: ['updated_at', 'last_retrieved_at', 'last_timeline_date'],
properties: {
updated_at: { type: ['string', 'null'] },
last_retrieved_at: { type: ['string', 'null'] },
last_timeline_date: { type: ['string', 'null'] },
},
},
open_threads: {
type: 'array',
items: {
type: 'object',
required: ['kind', 'text', 'date'],
properties: {
kind: { type: 'string', enum: ['commitment', 'recent_event'] },
text: { type: 'string' },
date: { type: ['string', 'null'] },
// v0.47 open-loop engine — ADDITIVE OPTIONAL (frozen-v1
// legal); present only on threads backed by an open_loops row.
direction: { type: 'string', enum: ['owed_by_me', 'owed_to_me', 'their_turn', 'my_turn'] },
due: { type: ['string', 'null'] },
counterparty: { type: ['string', 'null'] },
status: { type: 'string' },
loop_id: { type: 'number' },
},
},
},
edges: {
type: 'array',
items: {
type: 'object',
required: ['type', 'direction', 'slug'],
properties: {
type: { type: 'string' },
direction: { type: 'string', enum: ['out', 'in'] },
slug: { type: 'string' },
context: { type: ['string', 'null'] },
// Temporal typed edges — ADDITIVE OPTIONAL (frozen-v1 legal).
status: { type: 'string' },
since: { type: ['string', 'null'] },
until: { type: ['string', 'null'] },
},
},
},
backlink_count: { type: 'integer' },
active_fact_count: { type: 'integer' },
relationship_note: { type: 'string' },
// Entity recall — ADDITIVE OPTIONAL (frozen-v1 legal); the `entity`
// verb sets them, ambient callers (context_pack, delta) do not.
referenced_by_count: { type: 'integer' },
referenced_by: {
type: 'array',
items: {
type: 'object',
required: ['canonical_type', 'total', 'rows'],
properties: {
canonical_type: { type: 'string' },
total: { type: 'integer' },
rows: { type: 'array', items: REFERENCE_ROW_SCHEMA },
next: { type: 'object', required: ['tool', 'arguments'], properties: {
tool: { type: 'string', const: 'get_backlinks' }, arguments: { type: 'object' }, requires_surface: { type: 'string', enum: ['starter'] } } },
},
},
},
coverage: COVERAGE_SCHEMA,
// F1 record view — ADDITIVE OPTIONAL (frozen-v1 legal): only when record types are enrolled.
records: { type: 'array', items: RECORD_GROUP_SCHEMA },
references_unavailable: REFERENCES_UNAVAILABLE_SCHEMA,
},
},
coverage: COVERAGE_SCHEMA,
suggestions: {
type: 'array',
items: {
type: 'object',
required: ['slug', 'title', 'create_safety'],
properties: {
slug: { type: 'string' },
title: { type: 'string' },
create_safety: { type: 'string', enum: CREATE_SAFETY_ENUM },
source_id: { type: 'string' },
},
},
},
},
},
synthesize: {
type: 'object',
required: ['answer', 'sources', 'cost', 'protocol_version'],
properties: {
protocol_version: { type: 'integer', const: MEMORY_VERBS_VERSION },
answer: { type: 'string', description: 'Quoted words not found in the evidence are unquoted and marked [unverified]; never present them as quotes.' },
answer_raw: { type: 'string', description: 'With think.quote_verify on and quotes in the answer: the answer as the model wrote it.' },
quote_check: { type: 'object', properties: { grounded: { type: 'integer' }, repaired: { type: 'integer' }, unverified: { type: 'integer' } } },
unverified_quotes: { type: 'array', items: { type: 'object', properties: { text: { type: 'string' }, reason: { type: 'string' } } } },
sources: { type: 'array', items: { type: 'string' } },
gaps: { type: 'array', items: { type: 'string' } },
cost: {
type: 'object',
required: ['model', 'input_tokens', 'output_tokens', 'usd_estimate'],
description: 'Best-effort aggregate (retries/multi-call flows sum; cache hits may undercount). Honest signal, not an invoice.',
properties: {
model: { type: 'string' },
input_tokens: { type: ['integer', 'null'] },
output_tokens: { type: ['integer', 'null'] },
usd_estimate: { type: ['number', 'null'] },
},
},
// v0.45.x (WP2/T5+E2) additive compose-status fields — never required
// (a pre-v0.45.x v1 server that omits them must still certify).
synthesis_status: {
type: 'string',
enum: SYNTHESIS_STATUS_ENUM,
description:
'How the answer was produced. ok = LLM synthesis; extractive_fallback = compose failed with a non-empty gather — answer is an extractive digest quoting ONLY retrieved pages, sources cite the digested pages (never fabricated).',
},
pages_gathered: { type: 'integer', description: 'Pages retrieved by the gather phase behind this answer.' },
takes_gathered: { type: 'integer', description: 'Takes retrieved by the gather phase behind this answer.' },
warnings: { type: 'array', items: { type: 'string' }, description: 'Machine-stable pipeline warning codes (e.g. LLM_OUTPUT_NOT_JSON, LLM_CALL_FAILED: <class> where <class> is timeout | rate_limited | network | provider_error).' },
// #5461 additive: the pages budget is configurable and soft; callers learn when evidence was cut and which source each cited page came from.
evidence_truncated: { type: 'boolean', description: 'true when at least one gathered page reached the model as a cut excerpt (think.pages_budget_chars / think.excerpt_ceiling_chars, both soft bounds).' },
citations: {
type: 'array',
description: 'sources[] with provenance, same order and length: the gathered source each cited slug came from (null when the model cited a slug outside the gather).',
items: {
type: 'object',
required: ['slug', 'source_id'],
properties: { slug: { type: 'string' }, source_id: { type: ['string', 'null'] }, row_num: { type: ['integer', 'null'] } },
},
},
},
},
forget: {
type: 'object',
required: ['id', 'expired', 'reason', 'protocol_version'],
properties: {
protocol_version: { type: 'integer', const: MEMORY_VERBS_VERSION },
id: { type: 'string' },
expired: { type: 'boolean', description: 'true = this call expired the fact; false = it was ALREADY expired (idempotent re-forget).' },
reason: { type: ['string', 'null'] },
write_request: WRITE_RECEIPT_SCHEMA,
similar_active: {
type: 'object',
description: 'Active facts about the same entity close in meaning to the withdrawn claim (ids and scores only; zero model calls). Similarity is not sameness: ask the user before forgetting any of them.',
properties: {
state: { type: 'string', enum: ['checked', 'not_checked_no_embedding', 'not_checked_pending'] },
candidates: { type: 'array', items: { type: 'object', properties: { fact_id: { type: 'string' }, similarity: { type: 'number' } } } },
semantic_review: { type: 'string', enum: ['scheduled', 'off', 'unavailable', 'opted_out'] },
next: { type: 'string' },
},
},
},
},
// v0.45.7 (issue #1) — ambient recall. World-only by default; include_private
// widens all arms (local trusted callers only). protocol_version stays 1.
context_pack: {
type: 'object',
required: ['protocol_version', 'entities', 'cards', 'open_threads', 'facts'],
properties: {
protocol_version: { type: 'integer', const: MEMORY_VERBS_VERSION },
entities: { type: 'array', items: { type: 'string' } },
cards: {
type: 'array',
items: {
type: 'object',
required: ['slug', 'title', 'summary', 'open_threads'],
properties: {
slug: { type: 'string' },
// #6723 — ADDITIVE OPTIONAL: the card page's source; (source_id, slug) is the entity's identity.
source_id: { type: 'string' },
title: { type: 'string' },
type: { type: ['string', 'null'] },
summary: { type: 'string' },
open_threads: {
type: 'array',
items: {
type: 'object',
required: ['kind', 'text', 'date'],
properties: {
kind: { type: 'string', enum: ['commitment', 'recent_event'] },
text: { type: 'string' },
date: { type: ['string', 'null'] },
// v0.47 open-loop engine — additive optional.
direction: { type: 'string', enum: ['owed_by_me', 'owed_to_me', 'their_turn', 'my_turn'] },
due: { type: ['string', 'null'] },
counterparty: { type: ['string', 'null'] },
status: { type: 'string' },
loop_id: { type: 'number' },
},
},
},
edges: {
type: 'array',
items: {
type: 'object',
required: ['type', 'direction', 'slug'],
properties: {
type: { type: 'string' },
direction: { type: 'string', enum: ['out', 'in'] },
slug: { type: 'string' },
context: { type: ['string', 'null'] },
status: { type: 'string' },
since: { type: ['string', 'null'] },
until: { type: ['string', 'null'] },
},
},
},
backlink_count: { type: 'integer' },
relationship_note: { type: 'string' },
// F3 — ADDITIVE OPTIONAL: the card page's own frontmatter `status`, only when set (entity.row_page_status).
page_status: { type: 'string', maxLength: 40 },
// F1 record view — ADDITIVE OPTIONAL: only when record types are enrolled (pull verb only).
referenced_by_count: { type: 'integer' },
records: { type: 'array', items: RECORD_GROUP_SCHEMA },
sibling_records: { type: 'array', items: { type: 'object', required: ['slug', 'title'], properties: {
slug: { type: 'string' }, title: { type: 'string' }, referenced_by_count: { type: 'integer' },
records: { type: 'array', items: RECORD_GROUP_SCHEMA }, references_unavailable: REFERENCES_UNAVAILABLE_SCHEMA } } },
references_unavailable: REFERENCES_UNAVAILABLE_SCHEMA,
},
},
},
open_threads: {
type: 'array',
items: {
type: 'object',
required: ['kind', 'text', 'date'],
properties: {
kind: { type: 'string', enum: ['commitment', 'recent_event'] },
text: { type: 'string' },
date: { type: ['string', 'null'] },
// v0.47 open-loop engine — additive optional.
direction: { type: 'string', enum: ['owed_by_me', 'owed_to_me', 'their_turn', 'my_turn'] },
due: { type: ['string', 'null'] },
counterparty: { type: ['string', 'null'] },
status: { type: 'string' },
loop_id: { type: 'number' },
},
},
},
facts: {
type: 'array',
items: {
type: 'object',
required: ['fact', 'kind'],
properties: {
fact: { type: 'string' },
kind: { type: 'string' },
entity_slug: { type: ['string', 'null'] },
valid_from: { type: 'string' },
confidence: { type: 'number' },
fact_id: { type: 'string', description: 'Opaque protocol id — the value forget accepts.' },
provenance: { type: ['string', 'null'], description: 'The stored source attribution (remember --provenance).' },
},
},
},
// #6724 — ADDITIVE OPTIONAL: the packed entities' own facts, keyed to their card's (source_id, slug); `facts` stays hot memory.
entity_facts: {
type: 'array',
items: {
type: 'object',
required: ['source_id', 'slug', 'fact_id', 'fact', 'kind'],
properties: {
source_id: { type: 'string' },
slug: { type: 'string', description: 'The card this fact is about.' },
fact_id: { type: 'string', description: 'Opaque protocol id — the value forget accepts.' },
fact: { type: 'string' },
kind: { type: 'string' },
entity_slug: { type: ['string', 'null'] },
valid_from: { type: 'string' },
context: { type: ['string', 'null'] },
confidence: { type: 'number' },
attributed_to: { type: ['string', 'null'] },
provenance: { type: ['string', 'null'], description: 'The stored source attribution (remember --provenance).' },
trust_tier: { type: 'string' },
origin: { type: 'string' },
},
},
},
text: { type: 'string', description: 'Pre-rendered injectable block (envelope-wrapped).' },
degraded_reason: { type: 'string', description: 'Present when a wall-clock deadline returned a partial pack.' },
budget_tokens: { type: 'integer', description: 'Present when budget_tokens was passed.' },
budget_used: { type: 'integer' },
dropped_count: { type: 'integer' },
// C4 pinned questions — additive optional, owner-capable callers only; outside `text` and the budget.
pinned_questions: {
type: 'array',
description: 'Fresh sentences of pinned answers scoped to a packed entity (owner-capable callers only).',
items: {
type: 'object',
required: ['id', 'question', 'answer', 'freshness'],
properties: {
id: { type: 'string' },
question: { type: 'string' },
answer: { type: 'array', items: { type: 'string' } },
freshness: { type: 'string', enum: ['fresh', 'stale'] },
},
},
},
withheld: {
type: 'object',
required: ['stale_sentences', 'question_ids', 'refresh_command'],
description: 'Pinned-answer sentences left out because their evidence changed or is unreadable.',
properties: {
stale_sentences: { type: 'integer' },
question_ids: { type: 'array', items: { type: 'string' } },
refresh_command: { type: 'string' },
},
},
},
},
delta: {
type: 'object',
required: ['protocol_version', 'since', 'pages', 'facts', 'threads'],
properties: {
protocol_version: { type: 'integer', const: MEMORY_VERBS_VERSION },
since: { type: 'string', description: 'The ISO cursor this delta was computed against.' },
has_more: { type: 'boolean', description: 'True when more content is waiting (a fetch limit or the budget); each arm advanced only through what it delivered, so the rest surfaces on the next wake. Failure is degraded_reason, never has_more.' },
next_cursor: {
type: 'object',
required: ['since', 'slug'],
description: 'Where to resume. `cursor` (opaque, both arms exact) is passed back as cursor; older clients pass since + since_slug, which is conservative (may re-deliver, never skips): it holds while any arm failed and stays strictly before the oldest undelivered fact.',
properties: { since: { type: 'string' }, slug: { type: 'string' }, cursor: { type: 'string' } },
},
cursor_arms: {
type: 'object',
description: 'Replay audit trail: each arm\'s start and next keyset (pages: since + slug; facts: since + id).',
},
pages: {
type: 'array',
items: {
type: 'object',
required: ['slug', 'title', 'updated_at'],
properties: {
slug: { type: 'string' },
source_id: { type: 'string' },
title: { type: 'string' },
updated_at: { type: 'string' },
},
},
},
facts: {
type: 'array',
items: {
type: 'object',
required: ['fact', 'kind'],
properties: {
id: { type: 'integer', description: 'Fact id (dedupe key for replay).' },
fact: { type: 'string' },
kind: { type: 'string' },
entity_slug: { type: ['string', 'null'] },
valid_from: { type: 'string' },
confidence: { type: 'number' },
fact_id: { type: 'string', description: 'Opaque protocol id — the value forget accepts.' },
provenance: { type: ['string', 'null'], description: 'The stored source attribution (remember --provenance).' },
},
},
},
threads: {
type: 'array',
items: {
type: 'object',
required: ['kind', 'text', 'date'],
properties: {
kind: { type: 'string', enum: ['commitment', 'recent_event'] },
text: { type: 'string' },
date: { type: ['string', 'null'] },
},
},
},
text: { type: 'string' },
degraded_reason: { type: 'string', description: 'Comma-joined incomplete parts: deadline, pages, facts, threads, session_state. No cursor moved past anything undelivered; a delta_incomplete notice carries the retry step.' },
budget_tokens: { type: 'integer' },
budget_used: { type: 'integer' },
dropped_count: { type: 'integer' },
},
},
};
/** Error envelope schema (uniform across all verbs). */
export const ERROR_SCHEMA: Record<string, unknown> = {
type: 'object',
required: ['error', 'message'],
properties: {
error: {
type: 'string',
enum: [
'invalid_params',
'provenance_required',
'not_found',
'scope_denied',
'unavailable',
'budget_unsatisfiable', // RESERVED — schema-listed, never returned in v1
'internal',
],
},
message: { type: 'string' },
suggestion: { type: 'string', description: 'Populated on every verb error: problem + cause + fix.' },
detail: { type: 'string', description: 'Freeform specifics (e.g. which dependency failed).' },
protocol_version: { type: 'integer', const: MEMORY_VERBS_VERSION },
write_request: WRITE_RECEIPT_SCHEMA,
write_error: { type: 'string', enum: [...WRITE_ERROR_CODES] },
withdrawn: {
type: 'object',
required: ['at', 'subject', 'visibility'],
description: 'Additive, on a fact_withdrawn refusal: when and for which subject (an entity slug, or all_entities) the exact claim was forgotten. Absence carries no meaning.',
properties: {
at: { type: 'string' },
subject: { type: 'string' },
visibility: { type: 'string', enum: ['world', 'private'] },
},
},
},
};