Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript

memory_recall: query_keep tail ranks a long query on its end and reports query_truncated (v3, #8694); recall max_chars keeps facts_groups and entity_unspecified to delivered facts; pin source_id "" as omitted on recall and write

garrytane3bcd387fe2c
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 3be021437e..213b24ac96 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -347,6 +347,8 @@ Install commands now name `stable` (`bun install -g github:garrytan/gbrain#stabl
| Attested `context_pack` | JSON in `content` | `content` is the rendered pack text; the rest of the result is in `structuredContent` |
| Attested personal read over the result cap once `structuredContent` is counted | sent | refused whole with `result_too_large` |
| `memory_recall` fact rows | `{id, text, date, kind}` | add `arm`: `own` or `ranked`; no score |
+| `memory_recall` query over 2,000 characters | ranked on its first 2,000 characters, cut silently | the same by default; `query_keep: "tail"` (v3) ranks its last 2,000, so a turn after a long preamble still ranks, and sending `query_keep` adds `query_truncated` (#8694) |
+| `recall` with `max_chars` that cuts facts | `facts_groups` and `entity_unspecified` could still name the facts left out | they name only the facts and entities delivered |
| The same tools without `x-qm-actor` | as above | unchanged |
**An attested call can no longer write pages directly: `add_timeline_entry`, `add_link`, `put_page` and `edit_page` are not attestable.** They write to pages that everyone who reads the page sees, so a trusted system acting as one person could put that person's words in front of a whole audience with no one approving them. They now wait for owner-approved proposals, the way `capture` and take writes already do. An operator whose `--attest-ops` list names one of them sees `gbrain auth rescope` refuse the list, and each attested call to it is refused (`actor_not_attested`, reason `op_not_attested`); a queued attested write of one fails when it publishes. Unattested calls, and credentials bound to a member, are unchanged. `v2.json` lists the new deferred operations; `v1.json` is unchanged.
diff --git a/docs/contracts/qm-memory-provider/README.md b/docs/contracts/qm-memory-provider/README.md
index be2fc43b54..cf8f799a23 100644
--- a/docs/contracts/qm-memory-provider/README.md
+++ b/docs/contracts/qm-memory-provider/README.md
@@ -14,7 +14,9 @@ a person's own DM, read as that person (`query`, `get_page`, `get_timeline`,
served input schema and a frozen result shape: the fields every success carries,
with other fields allowed and ignored. `get_write_request` freezes the write-request
states, and a state not listed means unknown, not published. v3 also adds each
-`memory_recall` fact's `arm` (`own` or `ranked`). None of the v3 tools is a
+`memory_recall` fact's `arm` (`own` or `ranked`), and `memory_recall`'s `query_keep`:
+`tail` ranks a query over 2,000 characters on its end instead of its start, and a
+call that sends it gets `query_truncated`. None of the v3 tools is a
default attested operation (only `get_write_request` is): the brain operator lists
each one in the client's `--attest-ops`. No v3 tool is marked as a shared-scope
read yet; a later version adds those markings.
diff --git a/docs/contracts/qm-memory-provider/v3.json b/docs/contracts/qm-memory-provider/v3.json
index 7e0dd7bbfa..428e51f1ef 100644
--- a/docs/contracts/qm-memory-provider/v3.json
+++ b/docs/contracts/qm-memory-provider/v3.json
@@ -54,6 +54,14 @@
"type": "integer",
"description": "Text cap in UTF-16 code units, 200-12000 (default 6000)."
},
+ "query_keep": {
+ "type": "string",
+ "description": "Which end of a query over 2000 characters ranks the facts: head (the default) or tail. Sending it adds query_truncated.",
+ "enum": [
+ "head",
+ "tail"
+ ]
+ },
"acting_user": {
"type": "string",
"description": "Set by the trusted system: equal to the x-qm-actor header, or omit."
@@ -1121,7 +1129,7 @@
"query_chars_ranked": 2000,
"own_recent_window_hours": 24
},
- "arguments_checked": "query and max_chars are checked before any read, also for an unlinked person (invalid_params); a longer query is ranked on its first 2000 characters and never refused (recall's question is refused over 2000: invalid_params reason question_too_long)",
+ "arguments_checked": "query, max_chars and query_keep are checked before any read, also for an unlinked person (invalid_params); a longer query is never refused (recall's question is refused over 2000: invalid_params reason question_too_long) and is ranked on its first 2000 characters, or on its last 2000 with query_keep tail; a call that sends query_keep gets structuredContent.query_truncated, true when the query was cut",
"content": {
"line": "- <fact> (<YYYY-MM-DD>; <kind>)",
"never": [
@@ -1148,6 +1156,7 @@
}
],
"truncated": "boolean",
+ "query_truncated": "boolean, only when the call sent query_keep",
"code": "actor_unlinked (only on unlinked_recall)"
},
"arm": "own: the person's own fact from the last 24 hours; ranked: matched by query (a fact found both ways is own); a call that names sources answers ranked rows only",
diff --git a/docs/guides/qm.md b/docs/guides/qm.md
index 17381eb609..96ca76bc97 100644
--- a/docs/guides/qm.md
+++ b/docs/guides/qm.md
@@ -104,7 +104,9 @@ until a writer publishes them.
On success the result is in `structuredContent`, and `content` holds only the text
for the model. Each fact in `structuredContent.facts` carries `arm`: `own` (the
person's own recent fact) or `ranked` (matched by `query`); a recall that names
-sources has only `ranked` rows. An attested call to a v3 personal tool also gets its
+sources has only `ranked` rows. A query over 2,000 characters is ranked on its start;
+send `query_keep: "tail"` when QM puts its preamble ahead of the turn, and read
+`query_truncated` to tell a cut query from a short one. An attested call to a v3 personal tool also gets its
result in `structuredContent` (a list as `structuredContent.results`), while
`content` keeps the JSON; `context_pack`'s `content` is its rendered text alone. The
same tools called without `x-qm-actor` answer as before, with no `structuredContent`.
diff --git a/scripts/build-qm-memory-contract.ts b/scripts/build-qm-memory-contract.ts
index 5dbe93db9e..6285809acd 100644
--- a/scripts/build-qm-memory-contract.ts
+++ b/scripts/build-qm-memory-contract.ts
@@ -30,6 +30,8 @@ export const QM_CONTRACT_PATHS: Record<QmContractVersion, string> = {
export const QM_CONTRACT_PATH = QM_CONTRACT_PATHS[1];
/** The arguments v1 publishes per tool, frozen: later arguments appear from v2 on. */
const V1_PARAMS: Record<string, readonly string[]> = { memory_recall: ['query', 'max_chars', 'acting_user'], memory_write: ['facts', 'idempotency_key', 'acting_user'] };
+/** The arguments v2 publishes per tool, frozen: #8694's query_keep appears from v3 on. */
+const V2_PARAMS: Record<string, readonly string[]> = { memory_recall: [...V1_PARAMS.memory_recall!, 'source_id', 'source_ids'], memory_write: [...V1_PARAMS.memory_write!, 'source_id'] };
/** The deferred operations v1 published, frozen: GST-1158 F9 deferred more from v2 on. */
const V1_DEFERRED_OPS: readonly string[] = ['capture', 'extract_facts', 'list_write_conflicts', 'takes_add', 'takes_resolve', 'takes_supersede', 'takes_update'];
/** Catalogue summaries v1 published before they changed, frozen. */
@@ -142,7 +144,8 @@ const V2_REASON_FIXES: Partial<typeof ACTOR_REASON_FIXES> = {
function toolEntry(name: string, version: QmContractVersion) {
const op = operations.find(o => o.name === name);
if (!op) throw new Error(name + ' is not in the operation registry');
- const params = Object.entries(op.params).filter(([k]) => version > 1 || V1_PARAMS[name]!.includes(k));
+ const frozen = version === 1 ? V1_PARAMS[name] : version === 2 ? V2_PARAMS[name] : undefined;
+ const params = Object.entries(op.params).filter(([k]) => !frozen || frozen.includes(k));
return {
name, description: op.description, scope: op.scope ?? 'read', mutating: op.mutating === true,
input_schema: { type: 'object', properties: Object.fromEntries(params.map(([k, v]) => [k, paramDefToSchema(v)])),
@@ -181,13 +184,15 @@ export function buildQmMemoryContract(version: QmContractVersion): Record<string
} } : {}),
memory_recall: {
limits: { max_chars: { ...MEMORY_RECALL_MAX_CHARS, whole_number: true, unit: 'UTF-16 code units (JavaScript string length)' }, query_chars_ranked: MEMORY_RECALL_QUERY_CHARS, own_recent_window_hours: OWN_RECENT_WINDOW_HOURS },
- arguments_checked: v2
+ arguments_checked: v3
+ ? `query, max_chars and query_keep are checked before any read, also for an unlinked person (invalid_params); a longer query is never refused (recall's question is refused over ${QUESTION_MAX_CHARS}: invalid_params reason question_too_long) and is ranked on its first ${MEMORY_RECALL_QUERY_CHARS} characters, or on its last ${MEMORY_RECALL_QUERY_CHARS} with query_keep tail; a call that sends query_keep gets structuredContent.query_truncated, true when the query was cut`
+ : v2
? `query and max_chars are checked before any read, also for an unlinked person (invalid_params); a longer query is ranked on its first ${MEMORY_RECALL_QUERY_CHARS} characters and never refused (recall's question is refused over ${QUESTION_MAX_CHARS}: invalid_params reason question_too_long)`
: 'query and max_chars are checked before any read, also for an unlinked person (invalid_params)',
content: { line: '- <fact> (<YYYY-MM-DD>; <kind>)', never: ['page bodies', 'fence markers', 'heading markers', 'line breaks or control characters inside a fact'], bounded_by: 'max_chars: as many whole lines as fit; facts left out set structuredContent.truncated, with no marker line, because every line is one fact' },
order: ['own facts from the last ' + OWN_RECENT_WINDOW_HOURS + ' hours, newest first', 'facts the person may read, ranked by query'],
ranking: 'keyword-only unless an embedding provider is configured (no embedding call on a keyless brain)',
- structured_content: { facts: [{ id: 'string', text: 'string', date: 'YYYY-MM-DD', kind: 'string', ...(v3 ? { arm: '"own" | "ranked"' } : {}) }], truncated: 'boolean', code: 'actor_unlinked (only on unlinked_recall)' },
+ structured_content: { facts: [{ id: 'string', text: 'string', date: 'YYYY-MM-DD', kind: 'string', ...(v3 ? { arm: '"own" | "ranked"' } : {}) }], truncated: 'boolean', ...(v3 ? { query_truncated: 'boolean, only when the call sent query_keep' } : {}), code: 'actor_unlinked (only on unlinked_recall)' },
...(v3 ? { arm: 'own: the person\'s own fact from the last ' + OWN_RECENT_WINDOW_HOURS + ' hours; ranked: matched by query (a fact found both ways is own); a call that names sources answers ranked rows only' } : {}),
...(v2 ? { scope_read: {
arguments: ['source_id', 'source_ids'],
diff --git a/src/core/operation-manifest.generated.ts b/src/core/operation-manifest.generated.ts
index 4f3cba05e1..a73eb493f3 100644
--- a/src/core/operation-manifest.generated.ts
+++ b/src/core/operation-manifest.generated.ts
@@ -6458,6 +6458,15 @@ export const OPERATION_MANIFEST: OperationMeta[] = [
"type": "integer",
"description": "Text cap in UTF-16 code units, 200-12000 (default 6000)."
},
+ "query_keep": {
+ "type": "string",
+ "enum": [
+ "head",
+ "tail"
+ ],
+ "description": "Which end of a query over 2000 characters ranks the facts: head (the default) or tail. Sending it adds query_truncated.",
+ "fullSurfaceOnly": true
+ },
"acting_user": {
"type": "string",
"description": "Set by the trusted system: equal to the x-qm-actor header, or omit.",
diff --git a/src/core/ops/qm-memory.ts b/src/core/ops/qm-memory.ts
index 05a83e8bb2..e924dfaf1b 100644
--- a/src/core/ops/qm-memory.ts
+++ b/src/core/ops/qm-memory.ts
@@ -108,10 +108,18 @@ export function parseMaxChars(raw: unknown): number {
return raw;
}
-/** memory_recall's arguments, checked before any read (and before an unlinked person's empty answer): query and max_chars. */
-export function recallArguments(p: Record<string, unknown> | undefined): { query: string; maxChars: number } {
+/**
+ * memory_recall's arguments, checked before any read (and before an unlinked person's empty answer): query, max_chars and
+ * query_keep. A query over MEMORY_RECALL_QUERY_CHARS is ranked on its head (v1) or, with query_keep tail (v3, #8694), on
+ * its tail; query_keep also reports the cut as queryTruncated.
+ */
+export function recallArguments(p: Record<string, unknown> | undefined): { query: string; maxChars: number; queryTruncated?: boolean } {
if (typeof p?.query !== 'string') throw invalid('query is required and must be a string.', 'Pass what the turn is about as query.');
- return { query: p.query.trim().slice(0, MEMORY_RECALL_QUERY_CHARS), maxChars: parseMaxChars(p.max_chars) };
+ const keep = p.query_keep ?? undefined;
+ if (keep !== undefined && keep !== 'head' && keep !== 'tail') throw invalid('query_keep must be "head" or "tail".', `Omit query_keep to rank a long query on its first ${MEMORY_RECALL_QUERY_CHARS} characters, or send "tail" to rank it on its last ${MEMORY_RECALL_QUERY_CHARS}.`);
+ const query = p.query.trim();
+ const kept = keep === 'tail' ? query.slice(-MEMORY_RECALL_QUERY_CHARS) : query.slice(0, MEMORY_RECALL_QUERY_CHARS);
+ return { query: kept, maxChars: parseMaxChars(p.max_chars), ...(keep === undefined ? {} : { queryTruncated: kept.length < query.length }) };
}
type ReadPolicy = { excludePrivate: boolean; eligibility: Awaited<ReturnType<typeof resolveReadEligibility>> };
@@ -180,6 +188,7 @@ const memory_recall: Operation = {
params: {
query: { type: 'string', required: true, description: 'What the turn is about; ranks the facts.' },
max_chars: { type: 'integer', description: `Text cap in UTF-16 code units, ${MEMORY_RECALL_MAX_CHARS.min}-${MEMORY_RECALL_MAX_CHARS.max} (default ${MEMORY_RECALL_MAX_CHARS.default}).` },
+ query_keep: { type: 'string', enum: ['head', 'tail'], description: `Which end of a query over ${MEMORY_RECALL_QUERY_CHARS} characters ranks the facts: head (the default) or tail. Sending it adds query_truncated.`, fullSurfaceOnly: true },
[ACTOR_ARGUMENT]: actorParam,
source_id: { type: 'string', description: 'Read this one source as its audience (a shared scope): never the person\'s own facts.', fullSurfaceOnly: true },
source_ids: { ...SOURCE_IDS_PARAM, description: 'Read only these sources as their audience (a shared scope): never the person\'s own facts.', fullSurfaceOnly: true },
@@ -187,11 +196,12 @@ const memory_recall: Operation = {
scope: 'read',
annotations: { title: 'memory_recall (QM memory read)', readOnlyHint: true },
handler: async (ctx, p) => {
- const { query, maxChars } = recallArguments(p);
+ const { query, maxChars, queryTruncated } = recallArguments(p);
const { sources, named } = await recallSources(ctx, p);
- if (!named || ctx.remote === false) return recallFacts(ctx, query, maxChars, sources, named);
+ const cut = queryTruncated === undefined ? {} : { query_truncated: queryTruncated };
+ if (!named || ctx.remote === false) return { ...await recallFacts(ctx, query, maxChars, sources, named), ...cut };
const { folderCoverage } = await folderAccessFor(ctx.engine, []);
- return withCallerAccess({ ...SCOPE_READ_ACCESS, folderCoverage }, () => recallFacts(ctx, query, maxChars, sources, true));
+ return { ...await withCallerAccess({ ...SCOPE_READ_ACCESS, folderCoverage }, () => recallFacts(ctx, query, maxChars, sources, true)), ...cut };
},
};
@@ -362,11 +372,21 @@ export const qmMemoryOperations: Operation[] = [memory_recall, memory_write];
/**
* GST-900: recall's max_chars, memory_recall's bound on recall's text: the fact texts, then the results' chunk texts,
* one per line, keep the whole items that fit; the first item that would cross the cap ends both lists, with no
- * marker. `truncated` says whether anything was cut and `total` counts the facts kept.
+ * marker. `truncated` says whether anything was cut and `total` counts the facts kept; `facts_groups` and
+ * `entity_unspecified` keep only the facts and entities still delivered.
*/
-export function boundRecallChars<T extends { facts: Array<{ fact: string }>; total: number; results?: Array<{ chunk?: unknown }> }>(out: T, maxChars: number): T & { truncated: boolean } {
+export function boundRecallChars<T extends { facts: Array<{ id?: unknown; fact: string }>; total: number; results?: Array<{ chunk?: unknown }>;
+ facts_groups?: Array<{ source_id: string; entity_slug: string | null; fact_ids: string[] }>;
+ entity_unspecified?: { candidates: Array<{ source_id: string; entity_slug: string }> } }>(out: T, maxChars: number): T & { truncated: boolean } {
const lines = [...out.facts.map(f => f.fact), ...(out.results ?? []).map(r => String(r.chunk ?? ''))];
const { kept } = boundFactLines(lines, maxChars);
const facts = out.facts.slice(0, kept);
- return { ...out, facts, total: facts.length, ...(out.results ? { results: out.results.slice(0, Math.max(0, kept - out.facts.length)) } : {}), truncated: kept < lines.length };
+ const bounded = { ...out, facts, total: facts.length, ...(out.results ? { results: out.results.slice(0, Math.max(0, kept - out.facts.length)) } : {}), truncated: kept < lines.length };
+ if (facts.length === out.facts.length || !out.facts_groups) return bounded;
+ const ids = new Set(facts.map(f => String(f.id)));
+ const facts_groups = out.facts_groups.map(g => ({ ...g, fact_ids: g.fact_ids.filter(id => ids.has(id)) })).filter(g => g.fact_ids.length);
+ const named = new Set(facts_groups.filter(g => g.entity_slug !== null).map(g => g.source_id + '\u0000' + g.entity_slug));
+ const candidates = out.entity_unspecified?.candidates.filter(c => named.has(c.source_id + '\u0000' + c.entity_slug)) ?? [];
+ const { entity_unspecified: _cut, ...rest } = bounded;
+ return { ...rest, facts_groups, ...(out.entity_unspecified && candidates.length >= 2 ? { entity_unspecified: { ...out.entity_unspecified, candidates } } : {}) } as T & { truncated: boolean };
}
diff --git a/test/fixtures/goldens/cli/tools-json.json b/test/fixtures/goldens/cli/tools-json.json
index c742bbcd5b..94f1080457 100644
--- a/test/fixtures/goldens/cli/tools-json.json
+++ b/test/fixtures/goldens/cli/tools-json.json
@@ -2,8 +2,8 @@
"golden": {
"exitCode": 0,
"stderr": "",
- "stdoutBytes": 282967,
- "stdoutSha256": "73f135de04ba7cceced4d9fd952b23aaefd7fb4cad5ebdf3dce1aca953c70f84",
+ "stdoutBytes": 283280,
+ "stdoutSha256": "15699b963218128d3b3716ea40b8286c9e286678cb893205ceb960eb83efd11b",
"toolNames": [
"remember",
"entity",
@@ -7426,6 +7426,7 @@
"acting_user": "string?",
"max_chars": "integer?",
"query": "string",
+ "query_keep": "string?",
"source_id": "string?",
"source_ids": "array?"
},
@@ -7444,6 +7445,14 @@
"description": "What the turn is about; ranks the facts.",
"type": "string"
},
+ "query_keep": {
+ "description": "Which end of a query over 2000 characters ranks the facts: head (the default) or tail. Sending it adds query_truncated.",
+ "enum": [
+ "head",
+ "tail"
+ ],
+ "type": "string"
+ },
"source_id": {
"description": "Read this one source as its audience (a shared scope): never the person's own facts.",
"type": "string"
diff --git a/test/qm-memory-contract.test.ts b/test/qm-memory-contract.test.ts
index 14685aeec9..c70e335a02 100644
--- a/test/qm-memory-contract.test.ts
+++ b/test/qm-memory-contract.test.ts
@@ -85,11 +85,14 @@ describe('QM memory-provider contract v2 (GST-1094 scope read, GST-900)', () =>
expect(QM_CONTRACT_PATHS[1].endsWith(join('docs', 'contracts', 'qm-memory-provider', 'v1.json'))).toBe(true);
});
- test('the tool schemas are the ones MCP serves', () => {
+ test('the tool schemas are the ones MCP serves, restricted to v2\'s arguments (v3 adds query_keep)', () => {
const served = buildToolDefs(operations.filter(o => o.name === 'memory_recall' || o.name === 'memory_write'));
for (const tool of fixture.tools) {
const def = served.find(d => d.name === tool.name)!;
- expect({ description: tool.description, ...tool.input_schema }).toEqual({ description: def.description, ...def.inputSchema });
+ const servedKeys = Object.keys(def.inputSchema.properties as Record<string, unknown>);
+ expect(servedKeys.filter(k => !(k in tool.input_schema.properties))).toEqual(tool.name === 'memory_recall' ? ['query_keep'] : []);
+ const properties = Object.fromEntries(Object.entries(def.inputSchema.properties as Record<string, unknown>).filter(([k]) => k in tool.input_schema.properties));
+ expect({ description: tool.description, ...tool.input_schema }).toEqual({ description: def.description, ...def.inputSchema, properties });
}
});
@@ -133,22 +136,38 @@ describe('QM memory-provider contract v3 (GST-1158 F1: personal tools, frozen re
expect(readFileSync(QM_CONTRACT_PATHS[3], 'utf8')).toBe(renderQmMemoryContract(3));
});
- test('it keeps everything v2 has; only the version, recall\'s fact rows and the error list grow', () => {
+ test('it keeps everything v2 has; only the version, recall\'s fact rows, query_keep and the error list grow', () => {
expect(fixture.version).toBe(3);
for (const key of Object.keys(v2)) {
- if (key === 'version' || key === 'memory_recall' || key === 'errors') continue;
+ if (key === 'version' || key === 'memory_recall' || key === 'errors' || key === 'tools') continue;
expect(fixture[key]).toEqual(v2[key]);
}
- const { structured_content: recallShape, arm: _arm, ...recallRest } = fixture.memory_recall;
- const { structured_content: v2Shape, ...v2Rest } = v2.memory_recall;
+ const withoutKeep = (tools: Array<{ name: string; input_schema: { properties: Record<string, unknown> } }>) => tools.map(t => {
+ const { query_keep: _keep, ...properties } = t.input_schema.properties;
+ return { ...t, input_schema: { ...t.input_schema, properties } };
+ });
+ expect(withoutKeep(fixture.tools)).toEqual(v2.tools);
+ const { structured_content: recallShape, arm: _arm, arguments_checked: _checked, ...recallRest } = fixture.memory_recall;
+ const { structured_content: v2Shape, arguments_checked: _v2Checked, ...v2Rest } = v2.memory_recall;
expect(recallRest).toEqual(v2Rest);
- expect({ ...recallShape, facts: [{ ...recallShape.facts[0], arm: undefined }] }).toEqual({ ...v2Shape, facts: [{ ...v2Shape.facts[0], arm: undefined }] });
+ const { query_truncated: _cut, ...recallShapeV2 } = recallShape;
+ expect({ ...recallShapeV2, facts: [{ ...recallShape.facts[0], arm: undefined }] }).toEqual({ ...v2Shape, facts: [{ ...v2Shape.facts[0], arm: undefined }] });
expect(fixture.errors.shape).toEqual(v2.errors.shape);
for (const code of v2.errors.codes) expect(fixture.errors.codes.find((c: { code: string }) => c.code === code.code)).toBeDefined();
expect(v2.personal_tools).toBeUndefined();
expect(v2.memory_recall.structured_content.facts[0].arm).toBeUndefined();
});
+ test('memory_recall publishes query_keep head|tail and query_truncated only when it is sent (#8694); v2 has neither', () => {
+ const recall = fixture.tools.find((t: { name: string }) => t.name === 'memory_recall');
+ expect(recall.input_schema.properties.query_keep).toMatchObject({ type: 'string', enum: ['head', 'tail'] });
+ expect(recall.input_schema.required).toEqual(['query']);
+ expect(fixture.memory_recall.structured_content.query_truncated).toBe('boolean, only when the call sent query_keep');
+ expect(fixture.memory_recall.arguments_checked).toContain('on its last 2000 with query_keep tail');
+ expect(v2.tools.find((t: { name: string }) => t.name === 'memory_recall').input_schema.properties.query_keep).toBeUndefined();
+ expect(v2.memory_recall.structured_content.query_truncated).toBeUndefined();
+ });
+
test('memory_recall fact rows carry their arm, own or ranked, and no score', () => {
expect(fixture.memory_recall.structured_content.facts[0]).toEqual({ id: 'string', text: 'string', date: 'YYYY-MM-DD', kind: 'string', arm: '"own" | "ranked"' });
expect(fixture.memory_recall.arm).toContain('ranked rows only');
diff --git a/test/qm-memory-tools.test.ts b/test/qm-memory-tools.test.ts
index aac4a26a2d..ef8266998f 100644
--- a/test/qm-memory-tools.test.ts
+++ b/test/qm-memory-tools.test.ts
@@ -32,7 +32,7 @@ import { __resetHotMemoryCacheForTests, getBrainHotMemoryMeta } from '../src/cor
import { addMember, bindCredential } from '../src/core/access/members.ts';
import { attestRightOf, linkedMember, linkMember } from '../src/core/access/actor.ts';
import { disposePersistenceConsumer } from '../src/core/persistence/service.ts';
-import { boundFactLines, isoDate, memoryWriteRequestId, plainFactText, MEMORY_RECALL_MAX_CHARS } from '../src/core/ops/qm-memory.ts';
+import { boundFactLines, boundRecallChars, isoDate, memoryWriteRequestId, plainFactText, MEMORY_RECALL_MAX_CHARS } from '../src/core/ops/qm-memory.ts';
import { mintLegacyToken } from '../src/core/token-mint.ts';
import { operations } from '../src/core/operations.ts';
import { startHttpTransport } from '../src/mcp/http-transport.ts';
@@ -74,6 +74,24 @@ describe('memory_recall text bounds (pure)', () => {
}
});
+ test('a max_chars cut drops the cut facts from facts_groups and entity_unspecified, never naming a fact it left out (#8465 note)', () => {
+ const fact = (id: number, entity: string) => ({ id, fact: 'Fact ' + id + ' about ' + entity + ' ' + 'ledger detail '.repeat(10) });
+ const facts = [fact(1, 'acme-example'), fact(2, 'beta-example'), fact(3, 'gamma-example')];
+ const group = (id: number, entity: string) => ({ source_id: 'source-a', entity_slug: 'companies/' + entity, fact_ids: [String(id)], top_relevance: 1 / id });
+ const out = { facts, total: 3, facts_groups: [group(1, 'acme-example'), group(2, 'beta-example'), group(3, 'gamma-example')],
+ entity_unspecified: { candidates: ['acme-example', 'beta-example', 'gamma-example'].map(e => ({ source_id: 'source-a', entity_slug: 'companies/' + e })), suggestion: 'Ask which one.' } };
+ const two = boundRecallChars(out, facts[0]!.fact.length + 1 + facts[1]!.fact.length);
+ expect(two.facts.map(f => f.id)).toEqual([1, 2]);
+ expect(two.facts_groups.map(g => g.fact_ids)).toEqual([['1'], ['2']]);
+ expect(two.entity_unspecified?.candidates.map(c => c.entity_slug)).toEqual(['companies/acme-example', 'companies/beta-example']);
+ const one = boundRecallChars(out, facts[0]!.fact.length + 1);
+ expect(one.facts.map(f => f.id)).toEqual([1]);
+ expect(one.facts_groups.map(g => g.fact_ids)).toEqual([['1']]);
+ expect('entity_unspecified' in one).toBe(false);
+ const whole = boundRecallChars(out, 12_000);
+ expect({ groups: whole.facts_groups, unspecified: whole.entity_unspecified, truncated: whole.truncated }).toEqual({ groups: out.facts_groups, unspecified: out.entity_unspecified, truncated: false });
+ });
+
test('a list that fits is returned whole with no tail; an empty list is empty text', () => {
expect(boundFactLines(lines.slice(0, 3), 6000)).toEqual({ kept: 3, text: lines.slice(0, 3).join('\n') });
expect(boundFactLines([], 200)).toEqual({ kept: 0, text: '' });
@@ -293,6 +311,18 @@ for (const kind of testBackends()) {
expect(await factRows('canaryemptyrefused')).toHaveLength(0);
}, 120_000);
+ test('source_id "" or null, as a model fills an optional argument, reads as omitted on recall and write (#8465 note)', async () => {
+ for (const empty of ['', null]) {
+ const filled = await recall(alice, 'budget ledger', { source_id: empty });
+ const omitted = await recall(alice, 'budget ledger');
+ expect({ isError: filled.isError, code: filled.json.code, text: filled.text }).toEqual({ isError: omitted.isError, code: omitted.json.code, text: omitted.text });
+ const saved = await call(alice, 'memory_write', { facts: [{ fact: 'Empty source id write canaryemptysource' + (empty === null ? 'null' : 'blank'), provenance: 'x' }], idempotency_key: randomUUID(), source_id: empty }, { writeWaitMs: 30_000 });
+ expect(saved.structured?.status ?? saved.text).toBe('committed');
+ }
+ const rows = await factRows('canaryemptysource');
+ expect(rows.map(r => r.source_markdown_slug)).toEqual(['memory/members/alice-example', 'memory/members/alice-example']);
+ }, 120_000);
+
test('a squatted member page (readers beyond its member) takes no memory_write, and its receipt is not left behind', async () => {
const dave: Who = { token: 'qm', actor: DAVE_ID };
const squat = '---\ntype: note\ntitle: Memory of dave-example\nreadable_by:\n - member:bob-example\n - member:dave-example\n---\n# Memory of dave-example\n';
@@ -788,6 +818,30 @@ for (const kind of testBackends()) {
expect(tailOnly.isError).toBe(false);
}, 60_000);
+ test('query_keep "tail" ranks a long query on its last 2,000 characters and reports the cut in query_truncated; without it the v1 head cut is unchanged (#8694, v3)', async () => {
+ await engine.insertFact({ fact: 'The harbor tea supplier is canarytailquery', kind: 'fact', entity_slug: null, source: 'test', visibility: 'world' }, { source_id: SRC });
+ const preamble = 'You are the provider preamble for this turn and you follow the house style. '.repeat(30);
+ const turn = ' which harbor tea supplier canarytailquery';
+ try {
+ resetGateway();
+ configureGateway({ embedding_model: 'openai:text-embedding-3-small', embedding_dimensions: DIMS, env: {} });
+ const tail = await recall(bob, preamble + turn, { query_keep: 'tail' });
+ expect(tail.isError).toBe(false);
+ expect(tail.text).toContain('canarytailquery');
+ expect(tail.structured?.query_truncated).toBe(true);
+ const head = await recall(bob, preamble + turn);
+ expect(head.text).not.toContain('canarytailquery');
+ expect('query_truncated' in (head.structured ?? {})).toBe(false);
+ expect((await recall(bob, preamble + turn, { query_keep: 'head' })).structured?.query_truncated).toBe(true);
+ expect((await recall(bob, turn, { query_keep: 'tail' })).structured?.query_truncated).toBe(false);
+ const bad = await recall(bob, turn, { query_keep: 'middle' });
+ expect({ isError: bad.isError, code: bad.json.code }).toEqual({ isError: true, code: 'invalid_params' });
+ } finally {
+ resetGateway();
+ keyedEmbeddings();
+ }
+ }, 60_000);
+
test('a keyless brain ranks by keyword and makes no embedding call', async () => {
let embedCalls = 0;
try {