@namzu/sdk 48.3.1 → 49.0.0

package/src/store/memory/memory.ts

@@ -1,13 +1,14 @@
 import type { MemoryId } from '../../types/ids/index.js'
 import type {
+	ConditionalMemoryStore,
 	CreateMemoryParams,
 	MemoryContent,
 	MemoryIndexEntry,
 	MemoryRecord,
 	MemorySearchParams,
 	MemorySearchResult,
-	MemoryStore,
 	UpdateMemoryParams,
+	VersionedMemoryRecord,
 } from '../../types/memory/index.js'
 import { assertMemoryStatus } from '../../types/memory/index.js'
 import { generateMemoryId } from '../../utils/id.js'
@@ -18,8 +19,9 @@ import {
 	nameHolder,
 	withOptionalFields,
 } from './naming.js'
+import { assertMemoryRevision, memoryRevision } from './revision.js'
 
-export class InMemoryMemoryStore implements MemoryStore {
+export class InMemoryMemoryStore implements ConditionalMemoryStore {
 	private content = new Map<string, MemoryContent>()
 	private index = new InMemoryMemoryIndex()
 
@@ -70,10 +72,45 @@ export class InMemoryMemoryStore implements MemoryStore {
 		return entry && content ? structuredClone({ entry, content }) : undefined
 	}
 
+	async getVersionedRecord(id: MemoryId): Promise<VersionedMemoryRecord | undefined> {
+		const entry = this.index.getEntry(id)
+		const content = this.content.get(id)
+		if (!entry || !content) return undefined
+		const record = structuredClone({ entry, content })
+		return { ...record, revision: memoryRevision(record) }
+	}
+
 	async update(id: MemoryId, updates: UpdateMemoryParams): Promise<MemoryIndexEntry | undefined> {
+		return this.updateNow(id, updates)
+	}
+
+	async updateIfRevision(
+		id: MemoryId,
+		updates: UpdateMemoryParams,
+		expectedRevision: string,
+	): Promise<MemoryIndexEntry> {
+		// No await between the check and mutation: one in-memory operation turn.
+		const entry = this.updateNow(id, updates, expectedRevision)
+		if (!entry) throw new Error('A conditional memory update unexpectedly found no record.')
+		return entry
+	}
+
+	private updateNow(
+		id: MemoryId,
+		updates: UpdateMemoryParams,
+		expectedRevision?: string,
+	): MemoryIndexEntry | undefined {
 		if (updates.status !== undefined) assertMemoryStatus(updates.status)
 		assertOptionalMemoryFields(updates)
 		const existing = this.index.getEntry(id)
+		if (expectedRevision !== undefined) {
+			const content = this.content.get(id)
+			assertMemoryRevision(
+				id,
+				existing && content ? { entry: existing, content } : undefined,
+				expectedRevision,
+			)
+		}
 		if (!existing) return undefined
 		if (updates.name !== undefined) {
 			const holder = nameHolder(this.index.allEntries(), updates.name, id)
@@ -118,6 +155,19 @@ export class InMemoryMemoryStore implements MemoryStore {
 	}
 
 	async delete(id: MemoryId): Promise<boolean> {
+		return this.deleteNow(id)
+	}
+
+	async deleteIfRevision(id: MemoryId, expectedRevision: string): Promise<void> {
+		this.deleteNow(id, expectedRevision)
+	}
+
+	private deleteNow(id: MemoryId, expectedRevision?: string): boolean {
+		if (expectedRevision !== undefined) {
+			const entry = this.index.getEntry(id)
+			const content = this.content.get(id)
+			assertMemoryRevision(id, entry && content ? { entry, content } : undefined, expectedRevision)
+		}
 		const existed = this.index.remove(id)
 		this.content.delete(id)
 		return existed

package/src/store/memory/revision.ts

@@ -0,0 +1,158 @@
+import { createHash } from 'node:crypto'
+import { NamzuError } from '../../types/errors/index.js'
+import type { MemoryId } from '../../types/ids/index.js'
+import type { MemoryRecord } from '../../types/memory/index.js'
+
+/** A record can be read, but its metadata cannot be fingerprinted synchronously. */
+export class MemoryRevisionUnavailableError extends Error {
+	constructor() {
+		super('This memory contains metadata that cannot be revision-checked.')
+		this.name = 'MemoryRevisionUnavailableError'
+	}
+}
+
+/**
+ * Encode the same structured-clone snapshot `getRecord` returns. Type tags,
+ * object references and sorted plain-object keys preserve values JSON loses:
+ * BigInt, undefined, Map/Set contents, Date, typed arrays and cycles. Map and
+ * Set order is kept because it is observable. Unknown host objects (notably
+ * Blob, whose bytes need asynchronous reading) fail closed rather than hash as
+ * `{}` and allow a stale conditional write.
+ */
+function canonicalRecord(record: MemoryRecord): string {
+	let snapshot: MemoryRecord
+	try {
+		snapshot = structuredClone(record)
+	} catch {
+		throw new MemoryRevisionUnavailableError()
+	}
+	const seen = new WeakMap<object, number>()
+	let nextId = 0
+
+	function encode(value: unknown): unknown {
+		if (value === null) return ['null']
+		switch (typeof value) {
+			case 'undefined':
+				return ['undefined']
+			case 'string':
+				return ['string', value]
+			case 'boolean':
+				return ['boolean', value]
+			case 'bigint':
+				return ['bigint', value.toString()]
+			case 'number':
+				return ['number', Object.is(value, -0) ? '-0' : String(value)]
+			case 'function':
+			case 'symbol':
+				throw new MemoryRevisionUnavailableError()
+			case 'object':
+				break
+		}
+
+		const object = value as object
+		const previous = seen.get(object)
+		if (previous !== undefined) return ['ref', previous]
+		const id = nextId++
+		seen.set(object, id)
+		if (Array.isArray(object)) {
+			return [
+				'array',
+				id,
+				object.length,
+				Object.keys(object)
+					.sort()
+					.map((key) => [key, encode((object as unknown as Record<string, unknown>)[key])]),
+			]
+		}
+		if (object instanceof Map) {
+			return ['map', id, [...object].map(([key, item]) => [encode(key), encode(item)])]
+		}
+		if (object instanceof Set) return ['set', id, [...object].map(encode)]
+		if (object instanceof Date) return ['date', id, encode(object.getTime())]
+		if (object instanceof RegExp)
+			return ['regexp', id, object.source, object.flags, object.lastIndex]
+		if (object instanceof ArrayBuffer) {
+			const buffer = object as ArrayBuffer & {
+				readonly maxByteLength?: number
+				readonly resizable?: boolean
+			}
+			return [
+				'array-buffer',
+				id,
+				buffer.byteLength,
+				buffer.maxByteLength,
+				buffer.resizable,
+				Buffer.from(buffer).toString('hex'),
+			]
+		}
+		if (ArrayBuffer.isView(object)) {
+			// A view exposes its entire backing buffer through `.buffer`, even
+			// when its visible slice is one byte. Structured cloning keeps that
+			// backing and preserves aliases between multiple views.
+			if (
+				(typeof SharedArrayBuffer !== 'undefined' && object.buffer instanceof SharedArrayBuffer) ||
+				(object.buffer instanceof ArrayBuffer &&
+					(object.buffer as ArrayBuffer & { readonly resizable?: boolean }).resizable === true)
+			)
+				throw new MemoryRevisionUnavailableError()
+			return [
+				'array-buffer-view',
+				id,
+				object.constructor.name,
+				object.byteOffset,
+				object.byteLength,
+				encode(object.buffer),
+			]
+		}
+		if (object instanceof Error) {
+			return ['error', id, object.name, object.message, object.stack, encode(object.cause)]
+		}
+		if (object instanceof Number || object instanceof String || object instanceof Boolean)
+			return ['boxed', id, object.constructor.name, encode(object.valueOf())]
+		if (typeof SharedArrayBuffer !== 'undefined' && object instanceof SharedArrayBuffer)
+			throw new MemoryRevisionUnavailableError()
+		const prototype = Object.getPrototypeOf(object)
+		if (prototype !== Object.prototype && prototype !== null)
+			throw new MemoryRevisionUnavailableError()
+		return [
+			'object',
+			id,
+			Object.keys(object as Record<string, unknown>)
+				.sort()
+				.map((key) => [key, encode((object as Record<string, unknown>)[key])]),
+		]
+	}
+
+	return JSON.stringify(encode(snapshot))
+}
+
+/** A content-derived token; it includes metadata as well as the body. */
+export function memoryRevision(record: MemoryRecord): string {
+	return `m2:${createHash('sha256').update(canonicalRecord(record)).digest('hex')}`
+}
+
+/** The record changed or disappeared after its revision was read. */
+export class MemoryRevisionConflictError extends NamzuError {
+	readonly memoryId: MemoryId
+
+	constructor(memoryId: MemoryId) {
+		super({
+			code: 'storage_error',
+			message: `Memory ${memoryId} changed since it was read. Read it again before changing it.`,
+			details: { memoryId, reason: 'revision_conflict' },
+			retryable: false,
+		})
+		this.name = 'MemoryRevisionConflictError'
+		this.memoryId = memoryId
+	}
+}
+
+export function assertMemoryRevision(
+	id: MemoryId,
+	record: MemoryRecord | undefined,
+	expectedRevision: string,
+): asserts record is MemoryRecord {
+	if (!record || memoryRevision(record) !== expectedRevision) {
+		throw new MemoryRevisionConflictError(id)
+	}
+}

package/src/tools/builtins/wait-for-job-bounds.ts

@@ -1,4 +1,5 @@
 import type { BackgroundJobRegistryRef } from '../../types/tool/index.js'
+import { subscribeToAbort } from '../../utils/abort.js'
 
 /**
  * Waiting on a background job, bounded by two different questions — the
@@ -42,6 +43,8 @@ interface JobWaitProgress {
 	readonly output: string
 	readonly nextOffset: number
 	readonly droppedBytes: number
+	/** Earlier bytes omitted from this wait's own bounded output, separately from registry loss. */
+	readonly omittedOutputBytes: number
 }
 
 export type JobWaitOutcome =
@@ -67,12 +70,27 @@ export type JobWaitOutcome =
  */
 const POLL_INTERVAL_MS = 1_000
 
+/** Leave room for the status and recovery instructions inside the tool-result budget. */
+const MAX_WAIT_OUTPUT_BYTES = 32 * 1024
+
+function boundedTail(value: string): { output: string; omittedBytes: number } {
+	const bytes = Buffer.from(value, 'utf8')
+	if (bytes.length <= MAX_WAIT_OUTPUT_BYTES) return { output: value, omittedBytes: 0 }
+	let start = bytes.length - MAX_WAIT_OUTPUT_BYTES
+	// The cap is in bytes, but the displayed tail must begin at a UTF-8 character.
+	while (start < bytes.length && ((bytes[start] ?? 0) & 0xc0) === 0x80) start++
+	return {
+		output: bytes.subarray(start).toString('utf8'),
+		omittedBytes: start,
+	}
+}
+
 /**
- * Await a job under both bounds, accumulating its output as it goes.
+ * Await a job under both bounds, retaining a bounded tail as it goes.
  *
- * Returns the output gathered so far either way: a completed wait has all
- * of it, and a timed-out one has everything read up to the moment it gave
- * up, so the caller never has to throw away a partial answer.
+ * A completed or timed-out wait returns the bytes it observed up to its
+ * absolute cursor. If the displayed tail could not hold all of them, its
+ * omitted-byte count keeps that gap visible to the caller.
  */
 export async function waitForJobWithBounds(
 	jobs: Pick<BackgroundJobRegistryRef, 'read' | 'waitForExit'>,
@@ -90,8 +108,16 @@ export async function waitForJobWithBounds(
 	let cursor = options.fromOffset ?? 0
 	let output = ''
 	let droppedBytes = 0
+	let omittedOutputBytes = 0
 	let settled = false
 	let poll: ReturnType<typeof setInterval> | undefined
+	// Each bounded wait owns its exit subscription. A timeout must release that
+	// subscription even when the job itself runs forever.
+	const waitAbort = new AbortController()
+	const forwardAbort = (): void => waitAbort.abort(options.signal?.reason)
+	let disposeCallerAbort = () => {}
+	if (options.signal?.aborted) forwardAbort()
+	else if (options.signal) disposeCallerAbort = subscribeToAbort(options.signal, forwardAbort)
 
 	/** Read whatever is new since `cursor`, and count it as progress if it is. */
 	const drain = (): void => {
@@ -99,11 +125,15 @@ export async function waitForJobWithBounds(
 		if (chunk.droppedBytes > 0) droppedBytes += chunk.droppedBytes
 		if (chunk.nextOffset > cursor) lastProgressAt = now()
 		cursor = chunk.nextOffset
-		if (chunk.chunk) output += chunk.chunk
+		if (chunk.chunk) {
+			const bounded = boundedTail(output + chunk.chunk)
+			output = bounded.output
+			omittedOutputBytes += bounded.omittedBytes
+		}
 	}
 
 	try {
-		const exited = waitForExit(id, { signal: options.signal }).then((job): JobWaitOutcome => {
+		const exited = waitForExit(id, { signal: waitAbort.signal }).then((job): JobWaitOutcome => {
 			// One last read: the job can exit between ticks, and the bytes
 			// it wrote in its final moment are exactly the ones a caller
 			// most wants — the error, the summary line, the exit trace.
@@ -115,6 +145,7 @@ export async function waitForJobWithBounds(
 				output,
 				nextOffset: cursor,
 				droppedBytes,
+				omittedOutputBytes,
 			}
 		})
 
@@ -136,6 +167,7 @@ export async function waitForJobWithBounds(
 						output,
 						nextOffset: cursor,
 						droppedBytes,
+						omittedOutputBytes,
 					})
 					return
 				}
@@ -150,6 +182,7 @@ export async function waitForJobWithBounds(
 							output,
 							nextOffset: cursor,
 							droppedBytes,
+							omittedOutputBytes,
 						})
 					}
 				}
@@ -165,6 +198,8 @@ export async function waitForJobWithBounds(
 	} finally {
 		settled = true
 		if (poll !== undefined) clearInterval(poll)
+		disposeCallerAbort()
+		waitAbort.abort(new Error('Job wait finished'))
 	}
 }
 
@@ -174,7 +209,7 @@ export function describeJobWaitTimeout(
 	outcome: Extract<JobWaitOutcome, { kind: 'timeout' }>,
 ): string {
 	const seconds = Math.round(outcome.elapsedMs / 1000)
-	const resume = `call wait_for_job again, or job read with from_offset ${outcome.nextOffset}, to see what it does next`
+	const resume = `call wait_for_job or job read with from_offset ${outcome.nextOffset} to see only what comes next`
 	if (outcome.cause === 'idle') {
 		return `Job ${id} went quiet: no new output for a while, after ${seconds}s. It has not been stopped and may still be working — ${resume}.`
 	}

package/src/tools/builtins/wait-for-job.ts

@@ -35,6 +35,12 @@ const MAX_WAIT_MS = readPositiveIntEnv('NAMZU_JOB_WAIT_MAX_MS', 60 * 60 * 1000)
 
 const inputSchema = z.object({
 	id: z.string().describe('The job id, as returned by bash with run_in_background.'),
+	from_offset: z
+		.number()
+		.int()
+		.nonnegative()
+		.optional()
+		.describe('Resume after a previous wait: pass its next_offset to receive only new output.'),
 	timeout_ms: z
 		.number()
 		.int()
@@ -60,7 +66,7 @@ type WaitForJobInput = z.infer<typeof inputSchema>
 export const WaitForJobTool = defineTool({
 	name: 'wait_for_job',
 	description:
-		'Block until a background job started by bash with run_in_background ends, and return its accumulated output in one call. Use this instead of calling job with action "read" in a loop: it costs one call and no waiting turns. Gives up — WITHOUT stopping the job — if it runs too long or goes quiet for too long; either outcome says so, and the job keeps running either way.',
+		'Block until a background job started by bash with run_in_background ends, and return its bounded output in one call. Use this instead of calling job with action "read" in a loop: it costs one call and no waiting turns. A wait that runs too long or goes quiet returns its output and next_offset without stopping the job; pass that offset as from_offset on the next wait to avoid repeats.',
 	inputSchema,
 	category: 'shell',
 	permissions: ['shell_execute'],
@@ -128,6 +134,7 @@ export const WaitForJobTool = defineTool({
 			outcome = await waitForJobWithBounds(jobs, input.id, {
 				wallMs: input.timeout_ms ?? DEFAULT_TIMEOUT_MS,
 				idleMs: input.idle_timeout_ms ?? DEFAULT_IDLE_TIMEOUT_MS,
+				...(input.from_offset === undefined ? {} : { fromOffset: input.from_offset }),
 				signal: context.abortSignal,
 			})
 		} catch {
@@ -144,26 +151,32 @@ export const WaitForJobTool = defineTool({
 			}
 		}
 
+		const notices = [
+			...(outcome.droppedBytes > 0
+				? [`[${outcome.droppedBytes} bytes were dropped by the job's output retention cap]`]
+				: []),
+			...(outcome.omittedOutputBytes > 0
+				? [`[${outcome.omittedOutputBytes} earlier bytes omitted from this bounded wait result]`]
+				: []),
+		]
+		const observed = `${notices.length > 0 ? `${notices.join('\n')}\n` : ''}${outcome.output || '(no new output)'}`
+
 		if (outcome.kind === 'timeout') {
 			return {
-				success: false,
-				output: describeJobWaitTimeout(input.id, outcome),
+				// The wait observed a bound, not a failed command. A tool error
+				// would also be promoted as a durable failure by the turn's memory.
+				success: true,
+				output: `${describeJobWaitTimeout(input.id, outcome)}\n\n${observed}\n\n[next_offset ${outcome.nextOffset}]`,
 				data: {
 					jobId: input.id,
 					timedOut: outcome.cause,
 					nextOffset: outcome.nextOffset,
 					droppedBytes: outcome.droppedBytes,
+					omittedOutputBytes: outcome.omittedOutputBytes,
 				},
 			}
 		}
 
-		// The dropped count is stated, never absorbed — same rule `job read`
-		// follows, for the same reason: a job whose middle vanished quietly
-		// reads as a complete result that happens to be short.
-		const notice =
-			outcome.droppedBytes > 0
-				? `[${outcome.droppedBytes} bytes were dropped before this point — the job produced output faster than the retention cap holds]\n`
-				: ''
 		const status =
 			outcome.exitCode === undefined
 				? outcome.status
@@ -171,12 +184,13 @@ export const WaitForJobTool = defineTool({
 
 		return {
 			success: true,
-			output: `${notice}${outcome.output || '(no output)'}\n\n[job ${input.id} is ${status}; next_offset ${outcome.nextOffset}]`,
+			output: `${observed}\n\n[job ${input.id} is ${status}; next_offset ${outcome.nextOffset}]`,
 			data: {
 				jobId: input.id,
 				status: outcome.status,
 				nextOffset: outcome.nextOffset,
 				droppedBytes: outcome.droppedBytes,
+				omittedOutputBytes: outcome.omittedOutputBytes,
 				...(outcome.exitCode === undefined ? {} : { exitCode: outcome.exitCode }),
 			},
 		}

package/src/tools/memory/delete.ts

@@ -1,5 +1,7 @@
 import { z } from 'zod'
+import { MemoryRevisionConflictError } from '../../store/memory/revision.js'
 import type { MemoryStore } from '../../types/memory/index.js'
+import { hasConditionalMemoryWrites } from '../../types/memory/index.js'
 import type { ToolDefinition } from '../../types/tool/index.js'
 import { asMemoryId } from '../../utils/id.js'
 import { defineTool } from '../defineTool.js'
@@ -8,17 +10,45 @@ export function buildDeleteMemoryTool(store: MemoryStore): ToolDefinition {
 	return defineTool({
 		name: 'delete_memory',
 		description:
-			'Permanently delete a stored memory by ID. Use update_memory with status archived when the record should remain available for inspection. Deletion does not erase past conversation transcripts.',
+			'Permanently delete a stored memory by ID. Use update_memory with status archived when the record should remain available for inspection. Deletion does not erase past conversation transcripts. Pass the revision from read_memory when available to refuse a stale deletion.',
 		inputSchema: z.object({
 			id: z.string().describe('Memory ID to permanently delete'),
+			revision: z
+				.string()
+				.min(1)
+				.optional()
+				.describe('Opaque revision from read_memory; refuse deletion if the record changed'),
 		}),
 		category: 'custom',
 		permissions: [],
 		readOnly: false,
 		destructive: true,
 		concurrencySafe: true,
-		async execute({ id }) {
-			const removed = await store.delete(asMemoryId(id))
+		async execute({ id, revision }) {
+			if (revision !== undefined && !hasConditionalMemoryWrites(store)) {
+				return {
+					success: false,
+					output: 'This memory store does not support revision-checked deletion.',
+					error: 'Conditional memory deletion unavailable',
+				}
+			}
+			let removed: boolean
+			try {
+				if (revision === undefined) {
+					removed = await store.delete(asMemoryId(id))
+				} else if (hasConditionalMemoryWrites(store)) {
+					await store.deleteIfRevision(asMemoryId(id), revision)
+					removed = true
+				} else throw new Error('Conditional memory support changed during the deletion.')
+			} catch (error) {
+				if (!(error instanceof MemoryRevisionConflictError)) throw error
+				return {
+					success: false,
+					output: error.message,
+					error: 'Memory changed since read',
+					data: { reason: 'revision_conflict' },
+				}
+			}
 			return {
 				success: removed,
 				output: removed ? `Memory deleted: ${id}.` : `Memory ${id} not found.`,

package/src/tools/memory/read.ts

@@ -4,8 +4,10 @@ import {
 	describeMemoryAge,
 	memoryLinkNames,
 } from '../../store/memory/links.js'
+import { MemoryRevisionUnavailableError } from '../../store/memory/revision.js'
 import type { MemoryId } from '../../types/ids/index.js'
 import type { MemoryContent, MemoryIndexEntry, MemoryStore } from '../../types/memory/index.js'
+import { hasConditionalMemoryWrites } from '../../types/memory/index.js'
 import type { ToolDefinition } from '../../types/tool/index.js'
 import { defineTool } from '../defineTool.js'
 import { allMemoryEntries, resolveMemoryReference } from './resolve.js'
@@ -43,7 +45,22 @@ export function buildReadMemoryTool(store: MemoryStore): ToolDefinition {
 
 			let entry: MemoryIndexEntry | undefined
 			let content: MemoryContent | undefined
-			if (store.getRecord) {
+			let revision: string | undefined
+			if (hasConditionalMemoryWrites(store)) {
+				try {
+					const record = await store.getVersionedRecord(memoryId)
+					entry = record?.entry
+					content = record?.content
+					revision = record?.revision
+				} catch (error) {
+					if (!(error instanceof MemoryRevisionUnavailableError)) throw error
+					// Legacy in-memory records may hold cloneable host objects with
+					// inaccessible bytes. Read them without claiming CAS support.
+					const record = await store.getRecord?.(memoryId)
+					entry = record?.entry
+					content = record?.content ?? (await store.get(memoryId))
+				}
+			} else if (store.getRecord) {
 				const record = await store.getRecord(memoryId)
 				entry = record?.entry
 				content = record?.content
@@ -92,9 +109,24 @@ export function buildReadMemoryTool(store: MemoryStore): ToolDefinition {
 			// A JSON body stays exactly the stored text, parseable as it was
 			// before these notes existed; its age and links are in `data`.
 			const annotate = notes.length > 0 && content.format !== 'json'
+			const output = annotate ? `${content.content}\n\n---\n${notes.join('\n')}` : content.content
 			return {
 				success: true,
-				output: annotate ? `${content.content}\n\n---\n${notes.join('\n')}` : content.content,
+				output,
+				// The executor sends output or content to the model, not data. Keep
+				// output byte-compatible (including JSON) while exposing the token
+				// in a separate model-visible text block.
+				...(revision !== undefined
+					? {
+							content: [
+								{ type: 'text' as const, text: output },
+								{
+									type: 'text' as const,
+									text: `Memory revision: ${revision}. Pass it as revision to update_memory or delete_memory to reject stale changes.`,
+								},
+							],
+						}
+					: {}),
 				data: {
 					id: content.id,
 					format: content.format,
@@ -102,6 +134,7 @@ export function buildReadMemoryTool(store: MemoryStore): ToolDefinition {
 					...(entry?.name !== undefined ? { name: entry.name } : {}),
 					...(entry?.type !== undefined ? { type: entry.type } : {}),
 					...(entry ? { updatedAt: entry.updatedAt } : {}),
+					...(revision !== undefined ? { revision } : {}),
 					...(resolved.length > 0 ? { links: resolved } : {}),
 				},
 			}

package/src/tools/memory/search.ts

@@ -10,12 +10,13 @@ import type { ToolDefinition } from '../../types/tool/index.js'
 import { defineTool } from '../defineTool.js'
 
 type SearchMemory = (params: MemorySearchParams) => MemorySearchResult | Promise<MemorySearchResult>
+const MAX_MEMORY_SCAN = 256
 
 function defineSearchMemoryTool(search: SearchMemory): ToolDefinition {
 	return defineTool({
 		name: 'search_memory',
 		description:
-			'Search active stored memories by relevant words or tags. The built-in store ranks matches in names, titles, descriptions, summaries and full content. Returns the title, name, type, age and description of each match; use read_memory for evidence. Set status to archived to inspect obsolete records.',
+			'Search active stored memories by relevant words or tags. The built-in stores rank matches in names, titles, descriptions, summaries and full content. Built-in search examines at most 256 recent candidates per call; if incomplete, continue with the returned scan_offset. Use read_memory for evidence. Set status to archived to inspect obsolete records.',
 		inputSchema: z.object({
 			query: z.string().optional().describe('Relevant words or identifiers to search'),
 			tags: z.array(z.string()).optional().describe('Filter by tags (all must match)'),
@@ -30,20 +31,47 @@ function defineSearchMemoryTool(search: SearchMemory): ToolDefinition {
 				.max(50)
 				.default(10)
 				.describe('Maximum results to return (1–50)'),
+			scan_offset: z
+				.number()
+				.int()
+				.min(0)
+				.default(0)
+				.describe('Candidate offset from an earlier incomplete search; starts at 0'),
 		}),
 		category: 'analysis',
 		permissions: [],
 		readOnly: true,
 		destructive: false,
 		concurrencySafe: true,
-		async execute({ query, tags, status, limit }) {
-			const result = await search({ query, tags, status, limit })
+		async execute({ query, tags, status, limit, scan_offset }) {
+			const result = await search({
+				query,
+				tags,
+				status,
+				limit,
+				maxScanned: MAX_MEMORY_SCAN,
+				scanOffset: scan_offset,
+			})
+			const continuation = result.truncated
+				? result.nextScanOffset === undefined
+					? ' Search incomplete; narrow the query or read a known ID.'
+					: ` Search incomplete; continue with scan_offset ${result.nextScanOffset}.`
+				: ''
+			const page = scan_offset > 0 || result.truncated ? ' in this scan page' : ''
 
 			if (result.entries.length === 0) {
 				return {
 					success: true,
-					output: 'No memories found.',
-					data: { entries: [], totalCount: 0 },
+					output: `No memories found${page}.${continuation}`,
+					data: {
+						entries: [],
+						totalCount: result.totalCount,
+						truncated: result.truncated === true,
+						...(result.scannedCount !== undefined ? { scannedCount: result.scannedCount } : {}),
+						...(result.nextScanOffset !== undefined
+							? { nextScanOffset: result.nextScanOffset }
+							: {}),
+					},
 				}
 			}
 
@@ -57,8 +85,8 @@ function defineSearchMemoryTool(search: SearchMemory): ToolDefinition {
 
 			const output =
 				result.totalCount > result.entries.length
-					? `Found ${result.totalCount} memories (showing ${result.entries.length}):\n${lines.join('\n')}`
-					: `Found ${result.totalCount} memories:\n${lines.join('\n')}`
+					? `Found ${result.totalCount} memories${page} (showing ${result.entries.length}):\n${lines.join('\n')}${continuation}`
+					: `Found ${result.totalCount} memories${page}:\n${lines.join('\n')}${continuation}`
 
 			return {
 				success: true,
@@ -66,6 +94,9 @@ function defineSearchMemoryTool(search: SearchMemory): ToolDefinition {
 				data: {
 					entries: result.entries,
 					totalCount: result.totalCount,
+					truncated: result.truncated === true,
+					...(result.scannedCount !== undefined ? { scannedCount: result.scannedCount } : {}),
+					...(result.nextScanOffset !== undefined ? { nextScanOffset: result.nextScanOffset } : {}),
 				},
 			}
 		},