suemo 0.1.7 → 0.1.8

package/src/mcp/dispatch.ts

@@ -110,8 +110,23 @@ export async function handleToolCall(
 		}
 
 		case 'recall': {
-			const parsed = z.object({ nodeId: z.string() }).parse(params)
-			return recall(db, parsed.nodeId)
+			const parsed = z.object({
+				nodeId: z.string(),
+				rating: z.number().int().min(1).max(4).optional(),
+				at: z.string().optional(),
+				dryRun: z.boolean().optional(),
+			}).parse(params)
+			log.debug('Dispatch recall tool', {
+				nodeId: parsed.nodeId,
+				rating: parsed.rating ?? 3,
+				hasAt: parsed.at !== undefined,
+				dryRun: parsed.dryRun ?? false,
+			})
+			return recall(db, parsed.nodeId, {
+				...(parsed.rating !== undefined ? { rating: parsed.rating as 1 | 2 | 3 | 4 } : {}),
+				...(parsed.at !== undefined ? { at: parsed.at } : {}),
+				...(parsed.dryRun !== undefined ? { dryRun: parsed.dryRun } : {}),
+			})
 		}
 
 		case 'wander': {
@@ -143,9 +158,20 @@ export async function handleToolCall(
 		}
 
 		case 'context': {
-			const parsed = z.object({ scope: z.string().optional(), limit: z.number().optional() }).parse(params)
+			const parsed = z.object({
+				scope: z.string().optional(),
+				sessionId: z.string().optional(),
+				limit: z.number().optional(),
+			}).parse(params)
+			const resolvedScope = parsed.scope?.trim() || inferredScope
+			log.debug('Dispatch context tool', {
+				scope: resolvedScope,
+				sessionId: parsed.sessionId ?? null,
+				limit: parsed.limit ?? null,
+			})
 			return context(db, {
-				scope: parsed.scope?.trim() || inferredScope,
+				scope: resolvedScope,
+				...(parsed.sessionId !== undefined ? { sessionId: parsed.sessionId } : {}),
 				...(parsed.limit !== undefined ? { limit: parsed.limit } : {}),
 			})
 		}
@@ -205,7 +231,7 @@ export async function handleToolCall(
 		}
 
 		case 'health':
-			return healthReport(db)
+			return healthReport(db, { embeddingProvider: config.embedding.provider })
 
 		case 'stats':
 			return suemoStats(db)

package/src/mcp/server.ts

@@ -127,7 +127,14 @@ export async function startMcpServer(config: SuemoConfig): Promise<void> {
 		projectDir: config.main?.projectDir ?? '.ua',
 	})
 	const db = await connect(config.surreal)
-	await requireCompatibility(db)
+	log.debug('Running MCP HTTP compatibility preflight', {
+		embeddingProvider: config.embedding.provider,
+		context: 'mcp:http-startup',
+	})
+	await requireCompatibility(db, {
+		embeddingProvider: config.embedding.provider,
+		context: 'mcp:http-startup',
+	})
 	await runSchema(db)
 	const autoSync = createAutoSyncRunner(db, config)
 	autoSync.start()
@@ -163,7 +170,13 @@ export async function startMcpStdioServer(config: SuemoConfig): Promise<void> {
 	const autoSync = createAutoSyncRunner(db, config)
 	autoSync.start()
 	try {
+		log.debug('Running MCP stdio compatibility preflight', {
+			embeddingProvider: config.embedding.provider,
+			requireEmbedding: config.embedding.provider === 'surrealml',
+			context: 'mcp:stdio-startup',
+		})
 		const compat = await checkCompatibility(db, {
+			embeddingProvider: config.embedding.provider,
 			requireEmbedding: config.embedding.provider === 'surrealml',
 			context: 'mcp:stdio-startup',
 		})

package/src/mcp/stdio.ts

@@ -1,6 +1,7 @@
 import type { SuemoConfig } from '@/src/config.ts'
 import { getLogger } from '@/src/logger.ts'
 import { handleToolCall } from '@/src/mcp/dispatch.ts'
+import { MEMORY_KIND_VALUES } from '@/src/types.ts'
 import { createInterface } from 'node:readline'
 import type { Surreal } from 'surrealdb'
 
@@ -36,7 +37,7 @@ const MCP_TOOLS: McpToolDefinition[] = [
 			type: 'object',
 			properties: {
 				content: { type: 'string' },
-				kind: { type: 'string', enum: ['observation', 'belief', 'question', 'hypothesis', 'goal'] },
+				kind: { type: 'string', enum: [...MEMORY_KIND_VALUES] },
 				tags: { type: 'array', items: { type: 'string' } },
 				scope: { type: 'string' },
 				source: { type: 'string' },
@@ -96,7 +97,12 @@ const MCP_TOOLS: McpToolDefinition[] = [
 		description: 'Fetch one node and neighbors; tick review schedule',
 		inputSchema: {
 			type: 'object',
-			properties: { nodeId: { type: 'string' } },
+			properties: {
+				nodeId: { type: 'string' },
+				rating: { type: 'number', minimum: 1, maximum: 4 },
+				at: { type: 'string', description: 'ISO datetime override for deterministic replay/testing' },
+				dryRun: { type: 'boolean' },
+			},
 			required: ['nodeId'],
 		},
 	},
@@ -132,6 +138,7 @@ const MCP_TOOLS: McpToolDefinition[] = [
 			type: 'object',
 			properties: {
 				scope: { type: 'string' },
+				sessionId: { type: 'string' },
 				limit: { type: 'number' },
 			},
 		},
@@ -233,7 +240,7 @@ const MCP_TOOLS: McpToolDefinition[] = [
 				source: { type: 'string' },
 				confidence: { type: 'number' },
 				sessionId: { type: 'string' },
-				kind: { type: 'string', enum: ['observation', 'belief', 'question', 'hypothesis', 'goal'] },
+				kind: { type: 'string', enum: [...MEMORY_KIND_VALUES] },
 			},
 			required: ['topicKey', 'content'],
 		},
@@ -246,7 +253,7 @@ const MCP_TOOLS: McpToolDefinition[] = [
 			properties: {
 				nodeId: { type: 'string' },
 				content: { type: 'string' },
-				kind: { type: 'string', enum: ['observation', 'belief', 'question', 'hypothesis', 'goal'] },
+				kind: { type: 'string', enum: [...MEMORY_KIND_VALUES] },
 				tags: { type: 'array', items: { type: 'string' } },
 				scope: { type: ['string', 'null'] },
 				source: { type: ['string', 'null'] },
@@ -378,7 +385,7 @@ export async function runStdioServer(
 	log.info('stdin closed — stdio server exiting')
 }
 
-async function handleRpcMethod(
+export async function handleRpcMethod(
 	db: Surreal,
 	config: SuemoConfig,
 	method: string,
@@ -397,6 +404,8 @@ async function handleRpcMethod(
 			protocolVersion,
 			capabilities: {
 				tools: { listChanged: false },
+				prompts: { listChanged: false },
+				resources: { listChanged: false },
 			},
 			serverInfo: {
 				name: 'suemo',
@@ -417,6 +426,21 @@ async function handleRpcMethod(
 		return { tools: MCP_TOOLS }
 	}
 
+	// Optional MCP surfaces queried by some clients during capability probing.
+	// We currently do not expose custom prompts/resources, but we should answer
+	// with empty lists instead of throwing unknown-method errors.
+	if (method === 'prompts/list') {
+		return { prompts: [] }
+	}
+
+	if (method === 'resources/list') {
+		return { resources: [] }
+	}
+
+	if (method === 'resources/templates/list') {
+		return { resourceTemplates: [] }
+	}
+
 	if (method === 'tools/call') {
 		const name = typeof params.name === 'string' ? params.name : null
 		if (!name) {
@@ -432,6 +456,10 @@ async function handleRpcMethod(
 			: {}
 
 		try {
+			log.debug('tools/call dispatching', {
+				name,
+				argumentKeys: Object.keys(toolArgs),
+			})
 			const toolResult = await handleToolCall(db, config, name, toolArgs, opts)
 			const structuredContent = toolResult && typeof toolResult === 'object' && !Array.isArray(toolResult)
 				? toolResult

package/src/memory/episode.ts

@@ -5,11 +5,127 @@ import type { Surreal } from 'surrealdb'
 
 const log = getLogger(['suemo', 'memory', 'episode'])
 
+function normalizeRecordId(value: unknown): string {
+	if (typeof value === 'string') return value
+	if (value && typeof value === 'object') {
+		const recordLike = value as { tb?: unknown; id?: unknown; toString?: () => string }
+		if (typeof recordLike.tb === 'string' && (typeof recordLike.id === 'string' || typeof recordLike.id === 'number')) {
+			return `${recordLike.tb}:${String(recordLike.id)}`
+		}
+		if (typeof recordLike.toString === 'function') {
+			const asString = recordLike.toString()
+			if (asString && asString !== '[object Object]') return asString
+		}
+	}
+	return String(value)
+}
+
+function normalizeDatetime(value: unknown, field: string): string {
+	if (typeof value === 'string') {
+		const parsed = Date.parse(value)
+		if (Number.isFinite(parsed)) return new Date(parsed).toISOString()
+	}
+	if (value instanceof Date) return value.toISOString()
+	if (value && typeof value === 'object') {
+		const maybeDate = value as { toISOString?: () => string; toString?: () => string }
+		if (typeof maybeDate.toISOString === 'function') {
+			const iso = maybeDate.toISOString()
+			const parsed = Date.parse(iso)
+			if (Number.isFinite(parsed)) return new Date(parsed).toISOString()
+		}
+		if (typeof maybeDate.toString === 'function') {
+			const asString = maybeDate.toString()
+			const parsed = Date.parse(asString)
+			if (Number.isFinite(parsed)) return new Date(parsed).toISOString()
+		}
+	}
+	throw new Error(`Invalid episode datetime field: ${field}`)
+}
+
+function normalizeMemoryRef(value: unknown): string {
+	return normalizeRecordId(value)
+}
+
+function normalizeEpisodeRow(raw: unknown): Episode {
+	if (!raw || typeof raw !== 'object') {
+		throw new Error('Invalid episode row returned from database')
+	}
+	const row = raw as Record<string, unknown>
+	const sessionId = typeof row.session_id === 'string' ? row.session_id : null
+	if (!sessionId) throw new Error('Episode row missing session_id')
+
+	return {
+		id: normalizeRecordId(row.id),
+		session_id: sessionId,
+		started_at: normalizeDatetime(row.started_at, 'started_at'),
+		ended_at: row.ended_at == null ? null : normalizeDatetime(row.ended_at, 'ended_at'),
+		summary: typeof row.summary === 'string' ? row.summary : null,
+		context: row.context && typeof row.context === 'object' && !Array.isArray(row.context)
+			? row.context as Record<string, unknown>
+			: null,
+		goal: typeof row.goal === 'string' ? row.goal : null,
+		discoveries: Array.isArray(row.discoveries)
+			? row.discoveries.filter((item): item is string => typeof item === 'string')
+			: null,
+		accomplished: Array.isArray(row.accomplished)
+			? row.accomplished.filter((item): item is string => typeof item === 'string')
+			: null,
+		files_changed: Array.isArray(row.files_changed)
+			? row.files_changed.filter((item): item is string => typeof item === 'string')
+			: null,
+		memory_ids: Array.isArray(row.memory_ids)
+			? row.memory_ids.map((item) => normalizeMemoryRef(item))
+			: [],
+	}
+}
+
 export async function episodeStart(
 	db: Surreal,
 	sessionId: string,
 ): Promise<Episode> {
 	log.info('episodeStart()', { sessionId })
+	const openEpisodesResult = await db.query<[Episode[]]>(
+		`
+    SELECT * FROM episode
+    WHERE session_id = $sessionId
+      AND ended_at = NONE
+    ORDER BY started_at DESC
+    LIMIT 20
+  `,
+		{ sessionId },
+	)
+	const openEpisodes = (openEpisodesResult[0] ?? []).map((episode) => normalizeEpisodeRow(episode))
+	log.debug('episodeStart() open episode probe', {
+		sessionId,
+		openCount: openEpisodes.length,
+	})
+	if (openEpisodes.length > 0) {
+		const [latest, ...stale] = openEpisodes
+		if (stale.length > 0 && latest) {
+			const staleIds = stale.map((episode) => episode.id)
+			log.warning('episodeStart() found multiple open episodes, closing stale entries', {
+				sessionId,
+				staleCount: staleIds.length,
+				latestEpisodeId: latest.id,
+			})
+			await db.query(
+				`
+        UPDATE episode
+        SET ended_at = time::now(),
+            updated_at = time::now()
+        WHERE id INSIDE $staleIds
+      `,
+				{ staleIds },
+			)
+			await incrementWriteStats(db)
+		}
+		log.debug('episodeStart() reused existing open episode', {
+			sessionId,
+			episodeId: latest?.id,
+		})
+		if (latest) return latest
+	}
+
 	const result = await db.query<[Episode[]]>(
 		`
     CREATE episode CONTENT {
@@ -27,7 +143,7 @@ export async function episodeStart(
 		{ sessionId },
 	)
 	await incrementWriteStats(db)
-	return result[0]![0]!
+	return normalizeEpisodeRow(result[0]![0]!)
 }
 
 export async function episodeEnd(
@@ -71,8 +187,15 @@ export async function episodeEnd(
 				: null,
 		},
 	)
-	const episode = result[0]?.[0]
+	const episodeRaw = result[0]?.[0]
+	const episode = episodeRaw ? normalizeEpisodeRow(episodeRaw) : undefined
 	if (!episode) throw new Error(`No open episode found for session: ${sessionId}`)
+	log.debug('episodeEnd() closed open episode', {
+		sessionId,
+		episodeId: episode.id,
+		hasSummary: Boolean(summaryText),
+		hasStructured: Boolean(fields),
+	})
 	await incrementWriteStats(db)
 	return episode
 }
@@ -85,17 +208,40 @@ export async function attachToEpisode(
 	db: Surreal,
 	sessionId: string,
 	memoryId: string,
-): Promise<void> {
+): Promise<{ attached: boolean; reason?: 'no-open-episode' | 'already-attached'; episodeId?: string }> {
 	log.debug('attachToEpisode()', { sessionId, memoryId })
+	const openEpisodeResult = await db.query<[Episode[]]>(
+		`
+    SELECT * FROM episode
+    WHERE session_id = $sessionId
+      AND ended_at = NONE
+    ORDER BY started_at DESC
+    LIMIT 1
+  `,
+		{ sessionId },
+	)
+	const openEpisodeRaw = openEpisodeResult[0]?.[0]
+	const openEpisode = openEpisodeRaw ? normalizeEpisodeRow(openEpisodeRaw) : undefined
+	if (!openEpisode) {
+		log.debug('attachToEpisode() no open episode found', { sessionId, memoryId })
+		return { attached: false, reason: 'no-open-episode' }
+	}
+
+	const currentIds = (openEpisode.memory_ids ?? []).map((entry) => normalizeMemoryRef(entry))
+	if (currentIds.includes(memoryId)) {
+		return { attached: false, reason: 'already-attached', episodeId: openEpisode.id }
+	}
+
 	await db.query(
 		`
-    UPDATE episode
-    SET memory_ids += [$memoryId]
+    UPDATE <record<episode>>$episodeId
+    SET memory_ids = array::distinct(memory_ids + [<record<memory>>$memoryId])
       , updated_at = time::now()
-    WHERE session_id = $sessionId AND ended_at = NONE
   `,
-		{ sessionId, memoryId },
+		{ episodeId: openEpisode.id, memoryId },
 	)
+	await incrementWriteStats(db)
+	return { attached: true, episodeId: openEpisode.id }
 }
 
 export interface SessionContext {

package/src/memory/fsrs.ts

@@ -0,0 +1,237 @@
+import { getLogger } from '@/src/logger.ts'
+
+const log = getLogger(['suemo', 'memory', 'fsrs'])
+
+export type FsrsRating = 1 | 2 | 3 | 4
+export type FsrsState = 'new' | 'learning' | 'review' | 'relearning'
+
+export interface FsrsSnapshot {
+	fsrs_stability: number | null
+	fsrs_difficulty: number | null
+	fsrs_next_review: string | null
+	fsrs_state: FsrsState | null
+	fsrs_last_review: string | null
+	fsrs_reps: number | null
+	fsrs_lapses: number | null
+	fsrs_last_grade: number | null
+}
+
+export interface FsrsReviewResult {
+	rating: FsrsRating
+	retrievability: number
+	elapsedDays: number
+	intervalDays: number
+	stability: number
+	difficulty: number
+	stateBefore: FsrsState
+	stateAfter: FsrsState
+	nextReview: string
+	lastReview: string
+	reps: number
+	lapses: number
+}
+
+const FSRS5_WEIGHTS = [
+	0.40255,
+	1.18385,
+	3.173,
+	15.69105,
+	7.1949,
+	0.5345,
+	1.4604,
+	0.0046,
+	1.54575,
+	0.1192,
+	1.01925,
+	1.9395,
+	0.11,
+	0.29605,
+	2.2698,
+	0.2315,
+	2.9898,
+	0.51655,
+	0.6621,
+] as const
+
+const FORGET_DECAY = -0.5
+const FORGET_FACTOR = 19 / 81
+const REQUEST_RETENTION = 0.9
+const MIN_STABILITY = 0.1
+const MAX_STABILITY = 36500
+
+function clamp(value: number, min: number, max: number): number {
+	return Math.max(min, Math.min(max, value))
+}
+
+function round(value: number, precision = 8): number {
+	const factor = 10 ** precision
+	return Math.round(value * factor) / factor
+}
+
+function parseDate(value: string | null): Date | null {
+	if (!value) return null
+	const parsed = new Date(value)
+	if (Number.isNaN(parsed.getTime())) return null
+	return parsed
+}
+
+function elapsedDaysSince(previous: Date | null, now: Date): number {
+	if (!previous) return 0
+	const diffMs = now.getTime() - previous.getTime()
+	if (!Number.isFinite(diffMs) || diffMs <= 0) return 0
+	return diffMs / (24 * 60 * 60 * 1000)
+}
+
+function initStability(rating: FsrsRating): number {
+	const weight = FSRS5_WEIGHTS[rating - 1] ?? FSRS5_WEIGHTS[2]
+	return clamp(weight, MIN_STABILITY, MAX_STABILITY)
+}
+
+function initDifficulty(rating: FsrsRating): number {
+	const value = FSRS5_WEIGHTS[4] - Math.exp((rating - 1) * FSRS5_WEIGHTS[5]) + 1
+	return clamp(round(value), 1, 10)
+}
+
+function forgettingCurve(stability: number, elapsedDays: number): number {
+	if (elapsedDays <= 0) return 1
+	const retrievability = Math.pow(1 + (FORGET_FACTOR * elapsedDays) / stability, FORGET_DECAY)
+	return clamp(round(retrievability), 0, 1)
+}
+
+function nextDifficulty(currentDifficulty: number, rating: FsrsRating): number {
+	const delta = -FSRS5_WEIGHTS[6] * (rating - 3)
+	const damped = currentDifficulty + (delta * (10 - currentDifficulty)) / 9
+	const targetEasyDifficulty = initDifficulty(4)
+	const reverted = FSRS5_WEIGHTS[7] * targetEasyDifficulty + (1 - FSRS5_WEIGHTS[7]) * damped
+	return clamp(round(reverted), 1, 10)
+}
+
+function nextRecallStability(
+	difficulty: number,
+	stability: number,
+	retrievability: number,
+	rating: FsrsRating,
+): number {
+	const hardPenalty = rating === 2 ? FSRS5_WEIGHTS[15] : 1
+	const easyBonus = rating === 4 ? FSRS5_WEIGHTS[16] : 1
+	const increment = Math.exp(FSRS5_WEIGHTS[8])
+		* (11 - difficulty)
+		* Math.pow(stability, -FSRS5_WEIGHTS[9])
+		* (Math.exp((1 - retrievability) * FSRS5_WEIGHTS[10]) - 1)
+		* hardPenalty
+		* easyBonus
+	const next = stability * (1 + increment)
+	return clamp(round(next), MIN_STABILITY, MAX_STABILITY)
+}
+
+function nextForgetStability(
+	difficulty: number,
+	stability: number,
+	retrievability: number,
+): number {
+	const next = FSRS5_WEIGHTS[11]
+		* Math.pow(difficulty, -FSRS5_WEIGHTS[12])
+		* (Math.pow(stability + 1, FSRS5_WEIGHTS[13]) - 1)
+		* Math.exp((1 - retrievability) * FSRS5_WEIGHTS[14])
+	return clamp(round(next), MIN_STABILITY, MAX_STABILITY)
+}
+
+function nextShortTermStability(stability: number, rating: FsrsRating): number {
+	const increment = Math.exp(FSRS5_WEIGHTS[17] * (rating - 3 + FSRS5_WEIGHTS[18]))
+	const next = stability * increment
+	return clamp(round(next), MIN_STABILITY, MAX_STABILITY)
+}
+
+function nextState(current: FsrsState, rating: FsrsRating): FsrsState {
+	if (rating === 1) {
+		return current === 'review' ? 'relearning' : 'learning'
+	}
+	if (current === 'new' || current === 'learning' || current === 'relearning') {
+		return rating >= 3 ? 'review' : current
+	}
+	return 'review'
+}
+
+function intervalFromStability(stability: number, rating: FsrsRating): number {
+	const modifier = (Math.pow(REQUEST_RETENTION, 1 / FORGET_DECAY) - 1) / FORGET_FACTOR
+	let interval = clamp(Math.round(stability * modifier), 1, MAX_STABILITY)
+	if (rating === 2) interval = Math.max(1, Math.round(interval * 0.85))
+	if (rating === 4) interval = Math.min(MAX_STABILITY, Math.round(interval * 1.15))
+	return interval
+}
+
+function learningIntervalDays(rating: FsrsRating, state: FsrsState): number {
+	if (rating === 1) return state === 'relearning' ? 5 / 1440 : 10 / 1440
+	if (rating === 2) return 20 / 1440
+	if (rating === 3) return 1
+	return 2
+}
+
+export function applyFsrsReview(
+	current: FsrsSnapshot,
+	rating: FsrsRating,
+	reviewAt: Date,
+): FsrsReviewResult {
+	if (![1, 2, 3, 4].includes(rating)) {
+		throw new Error(`Invalid FSRS rating: ${rating}. Expected 1|2|3|4.`)
+	}
+	if (Number.isNaN(reviewAt.getTime())) {
+		throw new Error('Invalid review date for FSRS review')
+	}
+
+	const stateBefore: FsrsState = current.fsrs_state ?? 'new'
+	const lastReviewDate = parseDate(current.fsrs_last_review)
+	const elapsedDays = round(elapsedDaysSince(lastReviewDate, reviewAt))
+
+	const hadState = current.fsrs_stability !== null && current.fsrs_difficulty !== null
+
+	let stability = hadState ? current.fsrs_stability! : initStability(rating)
+	let difficulty = hadState ? current.fsrs_difficulty! : initDifficulty(rating)
+	let retrievability = hadState ? forgettingCurve(stability, elapsedDays) : 1
+
+	if (hadState) {
+		difficulty = nextDifficulty(difficulty, rating)
+		if (elapsedDays < 1) {
+			stability = nextShortTermStability(stability, rating)
+		} else if (rating === 1) {
+			stability = nextForgetStability(difficulty, stability, retrievability)
+		} else {
+			stability = nextRecallStability(difficulty, stability, retrievability, rating)
+		}
+	}
+
+	const stateAfter = nextState(stateBefore, rating)
+	const intervalDays = stateAfter === 'review'
+		? intervalFromStability(stability, rating)
+		: learningIntervalDays(rating, stateAfter)
+
+	const nextReview = new Date(reviewAt.getTime() + intervalDays * 24 * 60 * 60 * 1000)
+	const reps = (current.fsrs_reps ?? 0) + 1
+	const lapses = (current.fsrs_lapses ?? 0) + (rating === 1 ? 1 : 0)
+
+	const result: FsrsReviewResult = {
+		rating,
+		retrievability,
+		elapsedDays,
+		intervalDays: round(intervalDays),
+		stability,
+		difficulty,
+		stateBefore,
+		stateAfter,
+		nextReview: nextReview.toISOString(),
+		lastReview: reviewAt.toISOString(),
+		reps,
+		lapses,
+	}
+
+	log.debug('FSRS review computed', {
+		rating,
+		elapsedDays: result.elapsedDays,
+		intervalDays: result.intervalDays,
+		stateBefore,
+		stateAfter,
+		nextReview: result.nextReview,
+	})
+
+	return result
+}