refactor(mcp): single source of truth for memory-entry schema

The listMemories bug came from two hand-maintained copies of the
memory-entry shape drifting: a loose parse schema in the client and a
separate strict output schema in the tool. Move the entry/history/list
schemas into shared/types.ts and have both the client parser and the
tool output schema reference the same objects, so they can't diverge
again.

Audited the other 14 tools: none share this pattern — they either
project fields explicitly or validate loose-parsed data against the
same loose schema used to parse it.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

apps/mcp/src/server/client/index.ts

@@ -7,11 +7,14 @@ import { z } from "zod"
 import {
 	containerTagSchema,
 	documentsApiResponseSchema,
-	paginationSchema,
+	memoriesListSchema,
 	type ContainerTag,
 	type DocumentMemoryEntry,
 	type DocumentsApiResponse,
 	type DocumentWithMemories,
+	type MemoriesList,
+	type MemoryEntry,
+	type MemoryEntryHistory,
 } from "../../shared/types"
 
 const MAX_CHARS = 200000
@@ -34,44 +37,10 @@ export interface DocumentsListResponse {
 	pagination: SdkDocumentListResponse["pagination"]
 }
 
-// z.object strips API extras that the strict MCP output schema would reject.
-const memoryEntryHistorySchema = z.object({
-	id: z.string(),
-	memory: z.string(),
-	version: z.number(),
-	createdAt: z.string(),
-	updatedAt: z.string(),
-	parentMemoryId: z.string().nullish(),
-	rootMemoryId: z.string().nullish(),
-	isLatest: z.boolean().optional(),
-	isForgotten: z.boolean().optional(),
-})
-
-export type MemoryEntryHistory = z.infer<typeof memoryEntryHistorySchema>
-
-const memoryEntrySchema = z.object({
-	id: z.string(),
-	memory: z.string(),
-	version: z.number(),
-	isLatest: z.boolean(),
-	isForgotten: z.boolean(),
-	isStatic: z.boolean().optional(),
-	isInference: z.boolean().optional(),
-	createdAt: z.string(),
-	updatedAt: z.string(),
-	sourceCount: z.number().optional(),
-	documentIds: z.array(z.string()).optional(),
-	history: z.array(memoryEntryHistorySchema).optional(),
-})
-
-export type MemoryEntry = z.infer<typeof memoryEntrySchema>
-
-const memoryEntriesResponseSchema = z.object({
-	memoryEntries: z.array(memoryEntrySchema),
-	pagination: paginationSchema,
-})
-
-export type MemoryEntriesResponse = z.infer<typeof memoryEntriesResponseSchema>
+// Memory-entry shapes live in shared/types so the client parser and the
+// listMemories output schema share one definition and can't drift.
+export type { MemoryEntry, MemoryEntryHistory }
+export type MemoryEntriesResponse = MemoriesList
 
 export type Memory =
 	| {
@@ -453,7 +422,7 @@ export class SupermemoryClient {
 				})
 			}
 
-			return memoryEntriesResponseSchema.parse(await response.json())
+			return memoriesListSchema.parse(await response.json())
 		} catch (error) {
 			this.handleError(error)
 		}

apps/mcp/src/server/tools/output-schemas.ts

@@ -1,6 +1,7 @@
 import { z } from "zod"
 import {
 	containerTagAccessSchema,
+	memoriesListSchema,
 	paginationSchema,
 	sessionScopeSchema,
 } from "../../shared/types"
@@ -42,33 +43,6 @@ const documentSummarySchema = z.object({
 	summary: z.string().nullable(),
 })
 
-const memoryHistorySchema = z.object({
-	id: z.string(),
-	memory: z.string(),
-	version: z.number(),
-	createdAt: z.string(),
-	updatedAt: z.string(),
-	parentMemoryId: z.string().nullish(),
-	rootMemoryId: z.string().nullish(),
-	isLatest: z.boolean().optional(),
-	isForgotten: z.boolean().optional(),
-})
-
-const memoryEntryOutputSchema = z.object({
-	id: z.string(),
-	memory: z.string(),
-	version: z.number(),
-	isLatest: z.boolean(),
-	isForgotten: z.boolean(),
-	isStatic: z.boolean().optional(),
-	isInference: z.boolean().optional(),
-	createdAt: z.string(),
-	updatedAt: z.string(),
-	sourceCount: z.number().optional(),
-	documentIds: z.array(z.string()).optional(),
-	history: z.array(memoryHistorySchema).optional(),
-})
-
 export const addMemoryOutputSchema = z.object({
 	action: z.enum(["save", "forget"]),
 	success: z.boolean(),
@@ -104,10 +78,9 @@ export const listDocumentsOutputSchema = z.object({
 
 export type ListDocumentsOutput = z.infer<typeof listDocumentsOutputSchema>
 
-export const listMemoriesOutputSchema = z.object({
-	memoryEntries: z.array(memoryEntryOutputSchema),
-	pagination: paginationSchema,
-})
+// Reuse the shared schema so the tool's output contract stays identical to what
+// the client parses — the two can't drift.
+export const listMemoriesOutputSchema = memoriesListSchema
 
 export type ListMemoriesOutput = z.infer<typeof listMemoriesOutputSchema>
 

apps/mcp/src/shared/types.ts

@@ -116,6 +116,49 @@ export const documentsApiResponseSchema = z.object({
 
 export type DocumentsApiResponse = z.infer<typeof documentsApiResponseSchema>
 
+// Extracted memory entries from /v4/memories/list. Single source of truth for
+// both the client parser and the listMemories tool output schema, so the two
+// can't drift (a mismatch previously produced Ajv "must NOT have additional
+// properties"). z.object strips unknown API fields on parse, keeping parsed data
+// matched to the strict MCP output contract while tolerating new API fields.
+export const memoryEntryHistorySchema = z.object({
+	id: z.string(),
+	memory: z.string(),
+	version: z.number(),
+	createdAt: z.string(),
+	updatedAt: z.string(),
+	parentMemoryId: z.string().nullish(),
+	rootMemoryId: z.string().nullish(),
+	isLatest: z.boolean().optional(),
+	isForgotten: z.boolean().optional(),
+})
+
+export type MemoryEntryHistory = z.infer<typeof memoryEntryHistorySchema>
+
+export const memoryEntrySchema = z.object({
+	id: z.string(),
+	memory: z.string(),
+	version: z.number(),
+	isLatest: z.boolean(),
+	isForgotten: z.boolean(),
+	isStatic: z.boolean().optional(),
+	isInference: z.boolean().optional(),
+	createdAt: z.string(),
+	updatedAt: z.string(),
+	sourceCount: z.number().optional(),
+	documentIds: z.array(z.string()).optional(),
+	history: z.array(memoryEntryHistorySchema).optional(),
+})
+
+export type MemoryEntry = z.infer<typeof memoryEntrySchema>
+
+export const memoriesListSchema = z.object({
+	memoryEntries: z.array(memoryEntrySchema),
+	pagination: paginationSchema,
+})
+
+export type MemoriesList = z.infer<typeof memoriesListSchema>
+
 // ViewMessage — discriminated union returned by app tools as `structuredContent`.
 // The widget uses an exhaustive switch on `view` to dispatch to the correct view component.
 // Adding a new view here is a compile error in App.tsx until the case is handled.