@namzu/sdk 48.3.1 → 49.0.0

package/src/runtime/jobs/registry.ts

@@ -4,7 +4,7 @@ import { SANDBOX_KILL_GRACE_MS } from '../../constants/sandbox/index.js'
 import { killTree } from '../../process/kill-tree.js'
 import { hostShellSpawn } from '../../tools/command-shell.js'
 import { scrubInheritedEnv } from '../../tools/env-scrub.js'
-import { awaitWithAbort } from '../../utils/await-with-abort.js'
+import { subscribeToAbort } from '../../utils/abort.js'
 
 /**
  * Work that outlives a tool call, owned by whoever started it.
@@ -343,13 +343,30 @@ export class BackgroundJobRegistry {
 		const entry = this.jobs.get(id)
 		if (!entry) throw new UnknownBackgroundJobError({ id })
 		if (entry.record.status !== 'running') return Promise.resolve(entry.record)
-		// `entry` is the same object the `finalize` closure in `start()`
-		// mutates in place, so reading `entry.record` after `exit` settles
-		// sees the final status — the same trick `kill()` already relies on.
-		return awaitWithAbort(
-			entry.exit.then(() => entry.record),
-			opts.signal,
-		)
+		if (!opts.signal) {
+			// Keep the original promise path for callers without cancellation.
+			return entry.exit.then(() => entry.record)
+		}
+		const signal = opts.signal
+		if (signal.aborted) return Promise.reject(signal.reason)
+
+		// A Promise.race against entry.exit leaves a continuation on that
+		// never-ending promise after cancellation. An exit listener can instead
+		// be removed as soon as this particular wait is abandoned.
+		return new Promise<BackgroundJob>((resolve, reject) => {
+			let disposeAbort = () => {}
+			const unsubscribe = this.onExit((job) => {
+				if (job.id !== id) return
+				unsubscribe()
+				disposeAbort()
+				resolve(job)
+			})
+			disposeAbort = subscribeToAbort(signal, () => {
+				unsubscribe()
+				disposeAbort()
+				reject(signal.reason)
+			})
+		})
 	}
 
 	/**

package/src/runtime/query/index.ts

@@ -264,6 +264,12 @@ export interface QueryParams {
 	 * finishes.
 	 */
 	backgroundJobOwner?: string
+	/**
+	 * Called with job ids only when their exit notices enter model context:
+	 * a tool result or a recorded job-exit message. An exit event alone does not
+	 * mean the model saw it. A host can carry unacknowledged exits to its next turn.
+	 */
+	onJobNoticeDelivered?: (jobIds: readonly string[]) => void
 
 	/**
 	 * What else goes in this turn's prompt.
@@ -1319,6 +1325,20 @@ export async function* query(params: QueryParams): AsyncGenerator<SessionEvent,
 		// subscription that fills it below, because the wait-intent recorder needs
 		// to ask whether its text has been read yet.
 		const jobNotices = params.backgroundJobs ? new SteeringBinding() : undefined
+		const pendingJobNoticeIds = new Set<string>()
+		const acknowledgeJobNotices = () => {
+			if (pendingJobNoticeIds.size === 0) return
+			const ids = [...pendingJobNoticeIds]
+			pendingJobNoticeIds.clear()
+			try {
+				params.onJobNoticeDelivered?.(ids)
+			} catch (error) {
+				// A host observer cannot retract model-visible context or fail the turn.
+				ctx.log.warn('A background job notice observer failed', {
+					'exception.message': error instanceof Error ? error.message : String(error),
+				})
+			}
+		}
 		// Jobs the model told `wait_for_job` it is waiting on, which is the only
 		// thing that can hold this turn open for a job. Built only where there is a
 		// registry, so a host with no background mode carries no recorder and the
@@ -1425,6 +1445,7 @@ export async function* query(params: QueryParams): AsyncGenerator<SessionEvent,
 			jobNotices?.steer(
 				`Background job ${job.id} (${job.command}) ${outcome}. Read its output with the job tool if you need it.`,
 			)
+			pendingJobNoticeIds.add(job.id)
 			void eventTranslator
 				.emitEvent({
 					type: 'background_job_exited',
@@ -1567,6 +1588,7 @@ export async function* query(params: QueryParams): AsyncGenerator<SessionEvent,
 				: {}),
 			tools: toolManager,
 			allowedTools: effectiveAllowedTools,
+			showDeferredToolContext: params.contextLevel !== 'minimal',
 			recorder: ctx.recorder,
 			toolExecutor,
 			guard,
@@ -1582,6 +1604,7 @@ export async function* query(params: QueryParams): AsyncGenerator<SessionEvent,
 			promptContributions,
 			...(params.steering ? { steering: params.steering } : {}),
 			...(jobNotices ? { jobNotices } : {}),
+			...(jobNotices ? { onJobNoticeDelivered: acknowledgeJobNotices } : {}),
 			...(awaitedJobs ? { awaitedJobs } : {}),
 			checkpointMgr,
 			planManager: ctx.planManager,
@@ -1807,7 +1830,7 @@ export async function* query(params: QueryParams): AsyncGenerator<SessionEvent,
 					if (annotations.length > 0) {
 						promptContributions.replace({
 							id: 'hooks:user_prompt_submit',
-							placement: 'dynamic',
+							placement: 'context',
 							render: () => `Context from the operator's hooks:\n\n${annotations.join('\n\n')}`,
 						})
 					}

package/src/runtime/query/iteration/index.ts

@@ -3,7 +3,9 @@ import {
 	extractFromAssistantMessage,
 	extractFromUserMessage,
 } from '../../../compaction/extractor.js'
+import { estimateMessageTokens } from '../../../compaction/token-estimate.js'
 import { AUTO_CONTINUATION_USER_MESSAGE } from '../../../constants/continuation.js'
+import { CHARS_PER_TOKEN } from '../../../constants/limits.js'
 import {
 	DEFAULT_STRUCTURED_OUTPUT_RETRIES,
 	STRUCTURED_OUTPUT_REPROMPT,
@@ -548,13 +550,37 @@ export class IterationOrchestrator {
 					// Shape this step before calling the model. `stopWhen` decides
 					// whether to keep going; this decides HOW. No-op when the host
 					// supplied no hook.
+					// Render request-only contributions once before preparation. Their
+					// estimated cost reduces every stage's headroom, and the same text
+					// reaches the provider even if a stage changes external state.
+					const contextSections =
+						this.ctx.promptContributions?.render('context', { iteration: iterationNum }) ?? []
+					const deferredMcpHints =
+						this.ctx.showDeferredToolContext !== false
+							? this.ctx.tools.snapshotUntrustedDeferredContext()
+							: undefined
+					const pricedContextText = [
+						...contextSections,
+						...(deferredMcpHints?.all ? [deferredMcpHints.all] : []),
+					].join('\n\n')
+					const shaping: StepShaping = {
+						...this.stepShaping(),
+						requestContextTokens: pricedContextText
+							? estimateMessageTokens(stepContextMessage(pricedContextText)) +
+								Math.ceil(
+									((deferredMcpHints?.maxRenderedChars ?? 0) -
+										(deferredMcpHints?.all.length ?? 0)) /
+										CHARS_PER_TOKEN,
+								)
+							: 0,
+					}
 					const contextModelBeforePreparation = this.ctx.contextModel ?? model
-					const step = await prepareStep(this.stepShaping(), iterationNum)
+					const step = await prepareStep(shaping, iterationNum)
 					// Preparation inference belongs to the turn, not the main-model step.
 					usageBefore = { ...recorder.tokenUsage }
 					costBefore = { ...recorder.costInfo }
 					stepModel = step.model ?? model
-					await selectContextModel(this.stepShaping(), stepModel)
+					await selectContextModel(shaping, stepModel)
 					// Preserve post-compaction preparation/recall semantics. A changed
 					// model needs a second check against its own window; never replay
 					// host preparation effects merely to rebuild its request guidance.
@@ -563,6 +589,11 @@ export class IterationOrchestrator {
 					yield* this.ctx.drainPending()
 
 					const stepAllowedTools = step.allowedTools ?? this.ctx.allowedTools
+					const deferredMcpContext = deferredMcpHints?.forNames(stepAllowedTools) ?? ''
+					const contextText = [
+						...contextSections,
+						...(deferredMcpContext ? [deferredMcpContext] : []),
+					].join('\n\n')
 					const llmTools = this.ctx.tools
 						.toLLMTools(stepAllowedTools)
 						.filter(
@@ -643,11 +674,6 @@ export class IterationOrchestrator {
 					// (compaction preserves it there) and leaves the request's
 					// system run here.
 					const workingMemory = splitWorkingMemoryForRequest(baseMessages)
-					const contextSections =
-						this.ctx.promptContributions?.render('context', {
-							iteration: iterationNum,
-						}) ?? []
-
 					const stepPreamble = [step.system, stepSkills, policyNotice, ...turnSections]
 						.filter(Boolean)
 						.join('\n\n')
@@ -655,15 +681,14 @@ export class IterationOrchestrator {
 						? [...workingMemory.history, createSystemMessage(stepPreamble)]
 						: [...workingMemory.history]
 					if (workingMemory.context) requestHistory.push(workingMemory.context)
-					if (contextSections.length > 0)
-						requestHistory.push(stepContextMessage(contextSections.join('\n\n')))
+					if (contextText) requestHistory.push(stepContextMessage(contextText))
 					if (step.context) requestHistory.push(stepContextMessage(step.context))
 					const messages = projectRequestRichContent(
 						this.projectObservations(requestHistory),
 						this.ctx.turnConfig.maxRequestRichContentBytes ??
 							DEFAULT_MAX_REQUEST_RICH_CONTENT_BYTES,
 					)
-					appendWorkContext(this.stepShaping(), messages, iterationNum, step)
+					appendWorkContext(shaping, messages, iterationNum, step)
 					if (closingDirective) messages.push(closingDirective)
 					await this.reportUnsupportedToolResults(messages)
 					yield* this.ctx.drainPending()

package/src/runtime/query/iteration/outstanding-work.ts

@@ -260,6 +260,7 @@ export function deliverAwaitedJobExits(ctx: IterationContext): boolean {
 		'namzu.runtime.jobs': delivered.exits.map((job) => job.id),
 	})
 	ctx.recorder.pushMessage(createRuntimeContextMessage(formatJobNote(delivered.text), 'job-exit'))
+	ctx.onJobNoticeDelivered?.()
 	return true
 }
 
@@ -383,4 +384,5 @@ export function deliverArrivedJobExits(ctx: IterationContext): void {
 		'namzu.runtime.jobs': delivered.exits.map((job) => job.id),
 	})
 	ctx.recorder.pushMessage(createRuntimeContextMessage(formatJobNote(delivered.text), 'job-exit'))
+	ctx.onJobNoticeDelivered?.()
 }

package/src/runtime/query/iteration/phases/context.ts

@@ -98,6 +98,8 @@ export interface IterationContext {
 	readonly structuredOutput?: StructuredOutputConfig
 	readonly tools: ToolManager
 	readonly allowedTools?: string[]
+	/** The minimal context level omits tool discovery from both system and request context. */
+	readonly showDeferredToolContext?: boolean
 	readonly recorder: TurnRecorder
 	readonly toolExecutor: ToolExecutor
 	readonly guard: GuardCoordinator
@@ -141,6 +143,8 @@ export interface IterationContext {
 	readonly onSteeringDelivered?: (text: string) => void
 	/** Exit notices for the turn's background jobs, drained into the next tool result. */
 	readonly jobNotices?: SteeringChannel
+	/** Acknowledge exit notices only after their text enters model context. */
+	readonly onJobNoticeDelivered?: () => void
 	/**
 	 * Background jobs the model said it is waiting on, which is the only kind
 	 * the loop holds a finishing run open for.

package/src/runtime/query/iteration/phases/tool-review.ts

@@ -186,6 +186,7 @@ export async function* runToolReview(
 		// block must be answered by a `tool_result` with the same id, so a
 		// user message wedged between them is rejected by the provider. Same
 		// delivery a denial already uses, without the refusal.
+		let jobNoticeDelivered = false
 		for (const msg of attachRepeatNotice(
 			attachNotice(
 				attachSteering(batch.messages, ctx.steering, ctx.onSteeringDelivered),
@@ -194,12 +195,16 @@ export async function* runToolReview(
 				// The exits that text accounts for have now been read, so the
 				// record of them stops being pending work. Left standing, it
 				// buys the model a turn the next time any job queues a notice.
-				() => ctx.awaitedJobs?.noticesDelivered(),
+				() => {
+					ctx.awaitedJobs?.noticesDelivered()
+					jobNoticeDelivered = true
+				},
 			),
 			notices,
 		)) {
 			ctx.recorder.pushMessage(msg)
 		}
+		if (jobNoticeDelivered) ctx.onJobNoticeDelivered?.()
 		// The complete tool-result batch is already in history before host policy
 		// may react, so a replacement cannot split provider-required adjacency.
 		// Commit each accepted observation before entering the next one. A single

package/src/runtime/query/iteration/step-shaping.ts

@@ -38,6 +38,8 @@ export interface StepShaping {
 	readonly ctx: IterationContext
 	readonly latestUserMessage: () => UserMessage | undefined
 	readonly steps: () => readonly StepResult[]
+	/** Request-only contributions already rendered for this model step. */
+	readonly requestContextTokens?: number
 }
 
 export { stepContextMessage }
@@ -108,7 +110,13 @@ export function stepContext(
 			windowTokens: window.tokens,
 			remainingTokens: Math.max(
 				0,
-				Math.floor(window.tokens - measureContext(ctx).tokens - preparedTokens - responseReserve),
+				Math.floor(
+					window.tokens -
+						measureContext(ctx).tokens -
+						(shaping.requestContextTokens ?? 0) -
+						preparedTokens -
+						responseReserve,
+				),
 			),
 		},
 		steps: steps(),

package/src/store/index.ts

@@ -36,6 +36,7 @@ export {
 	slugifyMemoryName,
 } from './memory/naming.js'
 export type { MemoryContentRejection } from './memory/naming.js'
+export { MemoryRevisionConflictError } from './memory/revision.js'
 
 // Was that answer any good — recorded per message, durably, with
 // compare-and-set. Every consumer used to invent its own side table for the

package/src/store/memory/disk.ts

@@ -3,14 +3,15 @@ import { dirname, join, resolve } from 'node:path'
 import { NamzuError } from '../../types/errors/index.js'
 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, isMemoryType } from '../../types/memory/index.js'
 import { generateMemoryId, isEntityId } from '../../utils/id.js'
@@ -18,7 +19,7 @@ import { SCOPE_ATTRIBUTE } from '../../utils/log/types.js'
 import { type Logger, resolveLogger } from '../../utils/logger.js'
 import { DiskRecordStore } from '../kv/record-store.js'
 import { SCHEMA_VERSION_KEY, defineSchema } from '../schema.js'
-import { InMemoryMemoryIndex, searchMemoryEntries } from './index.js'
+import { InMemoryMemoryIndex, searchMemoryEntries, selectMemorySearchCandidates } from './index.js'
 import {
 	MemoryNameConflictError,
 	assertOptionalMemoryFields,
@@ -31,6 +32,7 @@ import {
 	acquireMemoryOperationLock,
 	validateMemoryLockTimeout,
 } from './operation-lock.js'
+import { MemoryRevisionConflictError, assertMemoryRevision, memoryRevision } from './revision.js'
 
 /**
  * This store's on-disk format, versioned as a unit — which is how a
@@ -181,7 +183,7 @@ export interface DiskMemoryStoreConfig {
 	lockTimeoutMs?: number
 }
 
-export class DiskMemoryStore implements MemoryStore {
+export class DiskMemoryStore implements ConditionalMemoryStore {
 	private readonly baseDir: string
 	private readonly log: Logger
 	private readonly lockTimeoutMs: number
@@ -355,18 +357,54 @@ export class DiskMemoryStore implements MemoryStore {
 		})
 	}
 
+	async getVersionedRecord(id: MemoryId): Promise<VersionedMemoryRecord | undefined> {
+		return this.withAuthoritativeIndex(async (location) => {
+			assertStorageMemoryId(id, (reason) => invalidContent(id, reason, { field: 'id' }))
+			const entry = this.index.getEntry(id)
+			if (!entry) return undefined
+			const record = structuredClone({ entry, content: await this.readContent(location, id) })
+			return { ...record, revision: memoryRevision(record) }
+		})
+	}
+
 	async update(id: MemoryId, updates: UpdateMemoryParams): Promise<MemoryIndexEntry | undefined> {
+		return this.updateInternal(id, updates)
+	}
+
+	async updateIfRevision(
+		id: MemoryId,
+		updates: UpdateMemoryParams,
+		expectedRevision: string,
+	): Promise<MemoryIndexEntry> {
+		const updated = await this.updateInternal(id, updates, expectedRevision)
+		if (!updated) throw new MemoryRevisionConflictError(id)
+		return updated
+	}
+
+	private async updateInternal(
+		id: MemoryId,
+		updates: UpdateMemoryParams,
+		expectedRevision?: string,
+	): Promise<MemoryIndexEntry | undefined> {
 		if (updates.status !== undefined) assertMemoryStatus(updates.status)
 		assertOptionalMemoryFields(updates)
 		return this.withAuthoritativeIndex(async (location) => {
 			assertStorageMemoryId(id, (reason) => invalidContent(id, reason, { field: 'id' }))
 			const existing = this.index.getEntry(id)
+			const existingContent = existing ? await this.readContent(location, id) : undefined
+			if (expectedRevision !== undefined) {
+				assertMemoryRevision(
+					id,
+					existing && existingContent ? { entry: existing, content: existingContent } : undefined,
+					expectedRevision,
+				)
+			}
 			if (!existing) return undefined
 			if (updates.name !== undefined) {
 				const holder = nameHolder(this.index.allEntries(), updates.name, id)
 				if (holder) throw new MemoryNameConflictError(updates.name, holder.id)
 			}
-			const existingContent = await this.readContent(location, id)
+			if (!existingContent) invalidContent(id, 'the indexed content record is missing')
 			const updated: MemoryIndexEntry = withOptionalFields(
 				{
 					...existing,
@@ -403,9 +441,27 @@ export class DiskMemoryStore implements MemoryStore {
 	}
 
 	async delete(id: MemoryId): Promise<boolean> {
+		return this.deleteInternal(id)
+	}
+
+	async deleteIfRevision(id: MemoryId, expectedRevision: string): Promise<void> {
+		const deleted = await this.deleteInternal(id, expectedRevision)
+		if (!deleted) throw new MemoryRevisionConflictError(id)
+	}
+
+	private async deleteInternal(id: MemoryId, expectedRevision?: string): Promise<boolean> {
 		return this.withAuthoritativeIndex(async (location) => {
 			assertStorageMemoryId(id, (reason) => invalidContent(id, reason, { field: 'id' }))
-			if (!this.index.getEntry(id)) return false
+			const entry = this.index.getEntry(id)
+			if (expectedRevision !== undefined) {
+				const content = entry ? await this.readContent(location, id) : undefined
+				assertMemoryRevision(
+					id,
+					entry && content ? { entry, content } : undefined,
+					expectedRevision,
+				)
+			}
+			if (!entry) return false
 
 			try {
 				await unlink(this.contentPath(location, id))
@@ -432,12 +488,31 @@ export class DiskMemoryStore implements MemoryStore {
 				query: undefined,
 				limit: undefined,
 				requiredIdentifiers: undefined,
+				maxScanned: undefined,
+				scanOffset: undefined,
 			})
+			const selection = selectMemorySearchCandidates(candidates.entries, params)
 			const contents = new Map<MemoryId, string>()
-			for (const entry of candidates.entries) {
+			for (const entry of selection.entries) {
 				contents.set(entry.id, (await this.readContent(location, entry.id)).content)
 			}
-			return searchMemoryEntries(candidates.entries, params, (id) => contents.get(id) ?? '')
+			const matched = searchMemoryEntries(
+				selection.entries,
+				{ ...params, maxScanned: undefined, scanOffset: undefined },
+				(id) => contents.get(id) ?? '',
+			)
+			return {
+				...matched,
+				...(params.maxScanned !== undefined || params.scanOffset !== undefined
+					? {
+							truncated: selection.truncated,
+							scannedCount: selection.scannedCount,
+							...(selection.nextScanOffset !== undefined
+								? { nextScanOffset: selection.nextScanOffset }
+								: {}),
+						}
+					: {}),
+			}
 		})
 	}
 

package/src/store/memory/index.ts

@@ -26,6 +26,56 @@ export function matchesMemoryIdentifier(text: string, identifiers: ReadonlySet<s
 	return false
 }
 
+interface MemoryScanSelection {
+	readonly entries: readonly MemoryIndexEntry[]
+	readonly truncated: boolean
+	readonly scannedCount: number
+	readonly nextScanOffset?: number
+}
+
+/** Select a bounded, resumable snapshot of indexed candidates before reading any bodies. */
+export function selectMemorySearchCandidates(
+	entries: readonly MemoryIndexEntry[],
+	params: MemorySearchParams,
+): MemoryScanSelection {
+	if (
+		params.maxScanned !== undefined &&
+		(!Number.isSafeInteger(params.maxScanned) || params.maxScanned < 1)
+	) {
+		throw new RangeError('maxScanned must be a positive safe integer')
+	}
+	if (
+		params.scanOffset !== undefined &&
+		(!Number.isSafeInteger(params.scanOffset) || params.scanOffset < 0)
+	) {
+		throw new RangeError('scanOffset must be a nonnegative safe integer')
+	}
+	const query = terms(params.query ?? '')
+	if (params.query?.trim() && query.size === 0)
+		return { entries: [], truncated: false, scannedCount: 0 }
+	const bodySearch =
+		query.size > 0 ||
+		Boolean(params.requiredIdentifiers?.length) ||
+		params.maxScanned !== undefined ||
+		params.scanOffset !== undefined
+	if (!bodySearch) return { entries, truncated: false, scannedCount: 0 }
+	const ordered = [...entries].sort(
+		(a, b) => b.updatedAt - a.updatedAt || (a.id < b.id ? -1 : a.id > b.id ? 1 : 0),
+	)
+	const start = params.scanOffset ?? 0
+	const selected = ordered.slice(
+		start,
+		params.maxScanned === undefined ? undefined : start + params.maxScanned,
+	)
+	const next = start + selected.length
+	return {
+		entries: selected,
+		truncated: next < ordered.length,
+		scannedCount: selected.length,
+		...(next < ordered.length ? { nextScanOffset: next } : {}),
+	}
+}
+
 /** Shared lexical ranking; a caller-owned index can omit body content. */
 export function searchMemoryEntries(
 	entries: readonly MemoryIndexEntry[],
@@ -36,13 +86,13 @@ export function searchMemoryEntries(
 	const identifiers = new Set(
 		params.requiredIdentifiers?.map((id) => id.normalize('NFKC').toLowerCase()),
 	)
-	if (params.query?.trim() && query.size === 0) return { entries: [], totalCount: 0 }
-	const ranked = entries
-		.filter(
-			(entry) =>
-				(!params.status || entry.status === params.status) &&
-				(!params.tags?.length || params.tags.every((tag) => entry.tags.includes(tag))),
-		)
+	const candidates = entries.filter(
+		(entry) =>
+			(!params.status || entry.status === params.status) &&
+			(!params.tags?.length || params.tags.every((tag) => entry.tags.includes(tag))),
+	)
+	const selection = selectMemorySearchCandidates(candidates, params)
+	const ranked = selection.entries
 		.filter(
 			(entry) =>
 				!identifiers.size ||
@@ -79,6 +129,15 @@ export function searchMemoryEntries(
 	return {
 		entries: ranked.slice(0, params.limit ?? ranked.length).map(({ entry }) => entry),
 		totalCount: ranked.length,
+		...(params.maxScanned !== undefined || params.scanOffset !== undefined
+			? {
+					truncated: selection.truncated,
+					scannedCount: selection.scannedCount,
+					...(selection.nextScanOffset !== undefined
+						? { nextScanOffset: selection.nextScanOffset }
+						: {}),
+				}
+			: {}),
 	}
 }
 

package/src/store/memory/markdown.ts

@@ -5,15 +5,16 @@ import { dirname, join, resolve } from 'node:path'
 import { NamzuError } from '../../types/errors/index.js'
 import type { MemoryId } from '../../types/ids/index.js'
 import type {
+	ConditionalMemoryStore,
 	CreateMemoryParams,
 	MemoryContent,
 	MemoryIndexEntry,
 	MemoryRecord,
 	MemorySearchParams,
 	MemorySearchResult,
-	MemoryStore,
 	MemoryType,
 	UpdateMemoryParams,
+	VersionedMemoryRecord,
 } from '../../types/memory/index.js'
 import { assertMemoryStatus, isMemoryType } from '../../types/memory/index.js'
 import { atomicWriteFile } from '../../utils/atomic-write.js'
@@ -47,6 +48,7 @@ import {
 	acquireMemoryOperationLock,
 	validateMemoryLockTimeout,
 } from './operation-lock.js'
+import { MemoryRevisionConflictError, assertMemoryRevision, memoryRevision } from './revision.js'
 
 /**
  * Versioned like every other record this SDK persists. A memory file carries
@@ -296,7 +298,7 @@ function decodeMemoryFile(
  * holds with {@link MemoryNameConflictError}, and derives a free one from the
  * title when none is given.
  */
-export class MarkdownMemoryStore implements MemoryStore {
+export class MarkdownMemoryStore implements ConditionalMemoryStore {
 	private readonly directory: string
 	private readonly log: Logger
 	private readonly lockTimeoutMs: number
@@ -587,6 +589,15 @@ export class MarkdownMemoryStore implements MemoryStore {
 		})
 	}
 
+	async getVersionedRecord(id: MemoryId): Promise<VersionedMemoryRecord | undefined> {
+		return this.withLoaded(async (_dir, loaded) => {
+			const memory = loaded.get(id)
+			if (!memory) return undefined
+			const record = structuredClone({ entry: memory.entry, content: memory.content })
+			return { ...record, revision: memoryRevision(record) }
+		})
+	}
+
 	/** The current record held under `name`, archived included, or `undefined`. */
 	async getByName(name: string): Promise<MemoryRecord | undefined> {
 		return this.withLoaded(async (_dir, loaded) => {
@@ -603,10 +614,35 @@ export class MarkdownMemoryStore implements MemoryStore {
 	}
 
 	async update(id: MemoryId, updates: UpdateMemoryParams): Promise<MemoryIndexEntry | undefined> {
+		return this.updateInternal(id, updates)
+	}
+
+	async updateIfRevision(
+		id: MemoryId,
+		updates: UpdateMemoryParams,
+		expectedRevision: string,
+	): Promise<MemoryIndexEntry> {
+		const updated = await this.updateInternal(id, updates, expectedRevision)
+		if (!updated) throw new MemoryRevisionConflictError(id)
+		return updated
+	}
+
+	private async updateInternal(
+		id: MemoryId,
+		updates: UpdateMemoryParams,
+		expectedRevision?: string,
+	): Promise<MemoryIndexEntry | undefined> {
 		if (updates.status !== undefined) assertMemoryStatus(updates.status)
 		assertOptionalMemoryFields(updates)
 		return this.mutate(async (dir, loaded) => {
 			const existing = loaded.get(id)
+			if (expectedRevision !== undefined) {
+				assertMemoryRevision(
+					id,
+					existing ? { entry: existing.entry, content: existing.content } : undefined,
+					expectedRevision,
+				)
+			}
 			if (!existing) return undefined
 			const entries = this.entries(loaded)
 			if (updates.name !== undefined) {
@@ -645,8 +681,24 @@ export class MarkdownMemoryStore implements MemoryStore {
 	}
 
 	async delete(id: MemoryId): Promise<boolean> {
+		return this.deleteInternal(id)
+	}
+
+	async deleteIfRevision(id: MemoryId, expectedRevision: string): Promise<void> {
+		const deleted = await this.deleteInternal(id, expectedRevision)
+		if (!deleted) throw new MemoryRevisionConflictError(id)
+	}
+
+	private async deleteInternal(id: MemoryId, expectedRevision?: string): Promise<boolean> {
 		return this.mutate(async (dir, loaded) => {
 			const existing = loaded.get(id)
+			if (expectedRevision !== undefined) {
+				assertMemoryRevision(
+					id,
+					existing ? { entry: existing.entry, content: existing.content } : undefined,
+					expectedRevision,
+				)
+			}
 			if (!existing) return false
 			try {
 				await unlink(existing.path)