suemo 0.1.7 → 0.1.8

package/src/memory/read.ts

@@ -2,6 +2,7 @@ import { incrementQueryStats } from '@/src/cognitive/health.ts'
 import type { SuemoConfig } from '@/src/config.ts'
 import { getEmbedding } from '@/src/embedding/index.ts'
 import { getLogger } from '@/src/logger.ts'
+import { applyFsrsReview, type FsrsRating } from '@/src/memory/fsrs.ts'
 import type {
 	Episode,
 	MemoryNode,
@@ -498,12 +499,85 @@ export async function query(
 	return merged
 }
 
-// ── recall() — single node + FSRS tick ───────────────────────────────────────
+export interface RecallOptions {
+	rating?: FsrsRating
+	at?: string
+	dryRun?: boolean
+}
+
+export interface RecallResult {
+	node: MemoryNode
+	neighbors: MemoryNode[]
+	fsrs: {
+		rating: FsrsRating
+		retrievability: number
+		elapsedDays: number
+		intervalDays: number
+		nextReview: string
+		stateBefore: 'new' | 'learning' | 'review' | 'relearning'
+		stateAfter: 'new' | 'learning' | 'review' | 'relearning'
+		dryRun: boolean
+	}
+}
+
+function parseFsrsState(value: unknown): 'new' | 'learning' | 'review' | 'relearning' | null {
+	if (value === null || value === undefined) return null
+	if (value === 'new' || value === 'learning' || value === 'review' || value === 'relearning') {
+		return value
+	}
+	return null
+}
+
+function parseFsrsGrade(value: unknown): number | null {
+	if (typeof value !== 'number' || !Number.isInteger(value)) return null
+	if (value < 1 || value > 4) return null
+	return value
+}
+
+function parseFsrsCount(value: unknown): number | null {
+	if (typeof value !== 'number' || !Number.isFinite(value)) return null
+	const parsed = Math.trunc(value)
+	if (parsed < 0) return null
+	return parsed
+}
+
+function withFsrsDefaults(node: MemoryNode): MemoryNode {
+	const raw = node as MemoryNode & {
+		fsrs_state?: unknown
+		fsrs_last_review?: unknown
+		fsrs_reps?: unknown
+		fsrs_lapses?: unknown
+		fsrs_last_grade?: unknown
+	}
+	const nextReview = typeof raw.fsrs_next_review === 'string' ? raw.fsrs_next_review : null
+	const lastReview = typeof raw.fsrs_last_review === 'string' ? raw.fsrs_last_review : null
+	return {
+		...node,
+		fsrs_next_review: nextReview,
+		fsrs_state: parseFsrsState(raw.fsrs_state),
+		fsrs_last_review: lastReview,
+		fsrs_reps: parseFsrsCount(raw.fsrs_reps),
+		fsrs_lapses: parseFsrsCount(raw.fsrs_lapses),
+		fsrs_last_grade: parseFsrsGrade(raw.fsrs_last_grade),
+	}
+}
+
+// ── recall() — single node + FSRS scheduling ─────────────────────────────────
 export async function recall(
 	db: Surreal,
 	nodeId: string,
-): Promise<{ node: MemoryNode; neighbors: MemoryNode[] }> {
-	log.info('recall()', { nodeId })
+	options: RecallOptions = {},
+): Promise<RecallResult> {
+	const rating = options.rating ?? 3
+	if (![1, 2, 3, 4].includes(rating)) {
+		throw new Error(`Invalid recall rating: ${rating}. Expected 1|2|3|4.`)
+	}
+	const reviewAt = options.at ? new Date(options.at) : new Date()
+	if (Number.isNaN(reviewAt.getTime())) {
+		throw new Error(`Invalid recall.at datetime: ${options.at}`)
+	}
+
+	log.info('recall()', { nodeId, rating, at: reviewAt.toISOString(), dryRun: options.dryRun ?? false })
 
 	const [nodeResult, neighborResult] = await Promise.all([
 		db.query<[MemoryNode[]]>(
@@ -523,21 +597,94 @@ export async function recall(
 		),
 	])
 
-	const node = nodeResult[0]?.[0]
-	if (!node) throw new Error(`Memory node not found: ${nodeId}`)
+	const nodeRaw = nodeResult[0]?.[0]
+	if (!nodeRaw) throw new Error(`Memory node not found: ${nodeId}`)
+	const node = withFsrsDefaults(nodeRaw)
+	const neighbors = neighborResult[0] ?? []
 
-	// FSRS tick — simplified next review interval
-	await db.query(
-		`
-    UPDATE <record<memory>>$id SET
-      fsrs_next_review = time::now() + 1d,
-      updated_at       = time::now()
-  `,
-		{ id: nodeId },
+	const fsrs = applyFsrsReview(
+		{
+			fsrs_stability: node.fsrs_stability,
+			fsrs_difficulty: node.fsrs_difficulty,
+			fsrs_next_review: node.fsrs_next_review,
+			fsrs_state: node.fsrs_state,
+			fsrs_last_review: node.fsrs_last_review,
+			fsrs_reps: node.fsrs_reps,
+			fsrs_lapses: node.fsrs_lapses,
+			fsrs_last_grade: node.fsrs_last_grade,
+		},
+		rating,
+		reviewAt,
 	)
+
+	if (!options.dryRun) {
+		await db.query(
+			`
+      UPDATE <record<memory>>$id SET
+        fsrs_stability   = $stability,
+        fsrs_difficulty  = $difficulty,
+        fsrs_next_review = <datetime>$nextReview,
+        fsrs_state       = $state,
+        fsrs_last_review = <datetime>$lastReview,
+        fsrs_reps        = $reps,
+        fsrs_lapses      = $lapses,
+        fsrs_last_grade  = $lastGrade,
+        updated_at       = time::now()
+    `,
+			{
+				id: nodeId,
+				stability: fsrs.stability,
+				difficulty: fsrs.difficulty,
+				nextReview: fsrs.nextReview,
+				state: fsrs.stateAfter,
+				lastReview: fsrs.lastReview,
+				reps: fsrs.reps,
+				lapses: fsrs.lapses,
+				lastGrade: fsrs.rating,
+			},
+		)
+		log.debug('recall() persisted FSRS review state', {
+			nodeId,
+			rating,
+			nextReview: fsrs.nextReview,
+			state: fsrs.stateAfter,
+			reps: fsrs.reps,
+			lapses: fsrs.lapses,
+		})
+	} else {
+		log.debug('recall() dry-run; skipped FSRS persistence', {
+			nodeId,
+			rating,
+			nextReview: fsrs.nextReview,
+			state: fsrs.stateAfter,
+		})
+	}
 	await incrementQueryStats(db)
 
-	return { node, neighbors: neighborResult[0] ?? [] }
+	return {
+		node: {
+			...node,
+			fsrs_stability: fsrs.stability,
+			fsrs_difficulty: fsrs.difficulty,
+			fsrs_next_review: fsrs.nextReview,
+			fsrs_state: fsrs.stateAfter,
+			fsrs_last_review: fsrs.lastReview,
+			fsrs_reps: fsrs.reps,
+			fsrs_lapses: fsrs.lapses,
+			fsrs_last_grade: fsrs.rating,
+		},
+		neighbors,
+		fsrs: {
+			rating: fsrs.rating,
+			retrievability: fsrs.retrievability,
+			elapsedDays: fsrs.elapsedDays,
+			intervalDays: fsrs.intervalDays,
+			nextReview: fsrs.nextReview,
+			stateBefore: fsrs.stateBefore,
+			stateAfter: fsrs.stateAfter,
+			dryRun: options.dryRun ?? false,
+		},
+	}
 }
 
 // ── wander() — spreading activation walk ─────────────────────────────────────
@@ -615,6 +762,7 @@ export async function timeline(
 
 export interface ContextPayload {
 	scope: string
+	sessionId: string | null
 	openEpisode: Episode | null
 	lastEpisode: Episode | null
 	recent: MemoryNode[]
@@ -623,20 +771,31 @@ export interface ContextPayload {
 
 export async function context(
 	db: Surreal,
-	opts: { scope: string; limit?: number },
+	opts: { scope: string; sessionId?: string; limit?: number },
 ): Promise<ContextPayload> {
 	const limit = Math.min(Math.max(opts.limit ?? 20, 1), 100)
 	const scope = opts.scope
+	const sessionId = opts.sessionId?.trim() || null
+
+	log.debug('context()', { scope, sessionId, limit })
+
+	const openEpisodePromise: Promise<[Episode[]]> = sessionId
+		? db.query<[Episode[]]>(
+			`SELECT * FROM episode WHERE session_id = $sessionId AND ended_at = NONE ORDER BY started_at DESC LIMIT 1`,
+			{ sessionId },
+		)
+		: Promise.resolve([[]] as [Episode[]])
+
+	const lastEpisodePromise: Promise<[Episode[]]> = sessionId
+		? db.query<[Episode[]]>(
+			`SELECT * FROM episode WHERE session_id = $sessionId ORDER BY started_at DESC LIMIT 1`,
+			{ sessionId },
+		)
+		: Promise.resolve([[]] as [Episode[]])
 
 	const [openEpisodeR, lastEpisodeR, recentR, totalR, activeR, statsR] = await Promise.all([
-		db.query<[Episode[]]>(
-			`SELECT * FROM episode WHERE session_id = $scope AND ended_at = NONE ORDER BY started_at DESC LIMIT 1`,
-			{ scope },
-		),
-		db.query<[Episode[]]>(
-			`SELECT * FROM episode WHERE session_id = $scope ORDER BY started_at DESC LIMIT 1`,
-			{ scope },
-		),
+		openEpisodePromise,
+		lastEpisodePromise,
 		db.query<[MemoryNode[]]>(
 			`
       SELECT * FROM memory
@@ -662,11 +821,20 @@ export async function context(
 		),
 	])
 
+	log.debug('context() query batches complete', {
+		scope,
+		sessionId,
+		recentCount: recentR[0]?.length ?? 0,
+		hasOpenEpisode: Boolean(openEpisodeR[0]?.[0]),
+		hasLastEpisode: Boolean(lastEpisodeR[0]?.[0]),
+	})
+
 	await incrementQueryStats(db)
 
 	const statsRow = statsR[0]?.[0]
 	return {
 		scope,
+		sessionId,
 		openEpisode: openEpisodeR[0]?.[0] ?? null,
 		lastEpisode: lastEpisodeR[0]?.[0] ?? null,
 		recent: recentR[0] ?? [],

package/src/memory/write.ts

@@ -10,6 +10,36 @@ import type { Surreal } from 'surrealdb'
 
 const log = getLogger(['suemo', 'memory', 'write'])
 
+async function attachToEpisodeWithLogging(
+	db: Surreal,
+	sessionId: string,
+	memoryId: string,
+): Promise<void> {
+	const result = await attachToEpisode(db, sessionId, memoryId)
+	if (result.attached) {
+		log.debug('Attached memory to episode', {
+			sessionId,
+			memoryId,
+			episodeId: result.episodeId,
+		})
+		return
+	}
+
+	if (result.reason === 'no-open-episode') {
+		log.warning('attachToEpisode skipped: no open episode', { sessionId, memoryId })
+		return
+	}
+
+	if (result.reason === 'already-attached') {
+		log.debug('attachToEpisode skipped: already attached', {
+			sessionId,
+			memoryId,
+			episodeId: result.episodeId,
+		})
+		return
+	}
+}
+
 // ── observe() ─────────────────────────────────────────────────────────────────
 export async function observe(
 	db: Surreal,
@@ -84,11 +114,7 @@ export async function observe(
 		)
 		const merged = updated[0]![0]!
 		if (input.sessionId) {
-			try {
-				await attachToEpisode(db, input.sessionId, merged.id)
-			} catch {
-				log.debug('attachToEpisode skipped (no open episode)', { sessionId: input.sessionId })
-			}
+			await attachToEpisodeWithLogging(db, input.sessionId, merged.id)
 		}
 		await incrementWriteStats(db)
 		return merged
@@ -111,7 +137,12 @@ export async function observe(
       consolidated_into: NONE,
       fsrs_stability:    NONE,
       fsrs_difficulty:   NONE,
-      fsrs_next_review:  NONE
+      fsrs_next_review:  NONE,
+      fsrs_state:        NONE,
+      fsrs_last_review:  NONE,
+      fsrs_reps:         NONE,
+      fsrs_lapses:       NONE,
+      fsrs_last_grade:   NONE
     }
   `,
 		{
@@ -127,11 +158,7 @@ export async function observe(
 
 	const node = created[0]![0]!
 	if (input.sessionId) {
-		try {
-			await attachToEpisode(db, input.sessionId, node.id)
-		} catch {
-			log.debug('attachToEpisode skipped (no open episode)', { sessionId: input.sessionId })
-		}
+		await attachToEpisodeWithLogging(db, input.sessionId, node.id)
 	}
 	await incrementWriteStats(db)
 	log.info('observe() created', { id: node.id })
@@ -267,11 +294,7 @@ export async function upsertByKey(
 
 		const node = updated[0]![0]!
 		if (parsed.sessionId) {
-			try {
-				await attachToEpisode(db, parsed.sessionId, node.id)
-			} catch {
-				log.debug('attachToEpisode skipped (no open episode)', { sessionId: parsed.sessionId })
-			}
+			await attachToEpisodeWithLogging(db, parsed.sessionId, node.id)
 		}
 		await incrementWriteStats(db)
 		return { node, wasUpdate: true }
@@ -296,7 +319,12 @@ export async function upsertByKey(
       consolidated_into: NONE,
       fsrs_stability:    NONE,
       fsrs_difficulty:   NONE,
-      fsrs_next_review:  NONE
+      fsrs_next_review:  NONE,
+      fsrs_state:        NONE,
+      fsrs_last_review:  NONE,
+      fsrs_reps:         NONE,
+      fsrs_lapses:       NONE,
+      fsrs_last_grade:   NONE
     }
   `,
 		{
@@ -313,11 +341,7 @@ export async function upsertByKey(
 
 	const node = created[0]![0]!
 	if (parsed.sessionId) {
-		try {
-			await attachToEpisode(db, parsed.sessionId, node.id)
-		} catch {
-			log.debug('attachToEpisode skipped (no open episode)', { sessionId: parsed.sessionId })
-		}
+		await attachToEpisodeWithLogging(db, parsed.sessionId, node.id)
 	}
 	await incrementWriteStats(db)
 	return { node, wasUpdate: false }

package/src/opencode/plugin.ts

@@ -1,5 +1,5 @@
 /**
- * suemo OpenCode plugin (v0.1.7)
+ * suemo OpenCode plugin (v0.1.8)
  *
  * Purpose:
  * - Inject strict, always-on suemo memory workflow instructions.
@@ -9,6 +9,12 @@
  *   ~/.config/opencode/plugins/suemo.ts
  */
 
+import type { Plugin } from '@opencode-ai/plugin'
+
+const SERVICE = 'suemo-plugin'
+const PLUGIN_VERSION = '0.1.8'
+const PROTOCOL_MARKER = 'Suemo Persistent Memory — Protocol'
+
 interface SystemTransformOutput {
 	system: string[]
 }
@@ -21,7 +27,18 @@ interface SessionCompactingOutput {
 	context: string[]
 }
 
-const MEMORY_INSTRUCTIONS = `## Suemo Persistent Memory — Protocol (v0.1.7)
+interface MessageTransformOutput {
+	messages: Array<{
+		info: Record<string, unknown>
+		parts: Array<Record<string, unknown>>
+	}>
+}
+
+interface PluginLogExtra {
+	[key: string]: unknown
+}
+
+const MEMORY_INSTRUCTIONS = `## Suemo Persistent Memory — Protocol (v0.1.8)
 
 You have access to suemo persistent memory tools (commonly prefixed as \`suemo_*\`).
 
@@ -76,30 +93,134 @@ If context is compacted/reset, FIRST:
 3. Then continue work
 `
 
-export const Suemo = async () => {
-	return {
-		'experimental.chat.system.transform': async (_input: unknown, output: SystemTransformOutput) => {
-			if (output.system.length > 0) {
-				output.system[output.system.length - 1] += `\n\n${MEMORY_INSTRUCTIONS}`
-				return
+function isDebugEnabled(): boolean {
+	const raw = process.env.SUEMO_PLUGIN_DEBUG?.trim().toLowerCase()
+	return raw === '1' || raw === 'true' || raw === 'yes'
+}
+
+function stringifyError(error: unknown): string {
+	if (error instanceof Error) return `${error.name}: ${error.message}`
+	return String(error)
+}
+
+function hasProtocolMarkerInSystem(system: string[]): boolean {
+	return system.some((item) => item.includes(PROTOCOL_MARKER))
+}
+
+function hasProtocolMarkerInMessages(output: MessageTransformOutput): boolean {
+	return output.messages.some((message) =>
+		message.parts.some((part) => {
+			const text = part.text
+			return typeof text === 'string' && text.includes(PROTOCOL_MARKER)
+		})
+	)
+}
+
+export const Suemo: Plugin = async (ctx) => {
+	async function pluginLog(
+		level: 'debug' | 'info' | 'warn' | 'error',
+		message: string,
+		extra?: PluginLogExtra,
+	): Promise<void> {
+		try {
+			await ctx.client.app.log({
+				body: {
+					service: SERVICE,
+					level,
+					message,
+					...(extra ? { extra } : {}),
+				},
+			})
+		} catch {
+			if (level === 'error' || isDebugEnabled()) {
+				const suffix = extra ? ` ${JSON.stringify(extra)}` : ''
+				process.stderr.write(`[${SERVICE}] ${level}: ${message}${suffix}\n`)
+			}
+		}
+	}
+
+	await pluginLog('info', 'plugin.loaded', { version: PLUGIN_VERSION })
+
+	const hooks: Awaited<ReturnType<Plugin>> = {
+		'experimental.chat.system.transform': async (input: unknown, output: SystemTransformOutput) => {
+			try {
+				if (hasProtocolMarkerInSystem(output.system)) {
+					await pluginLog('debug', 'system.transform.skip.already-present', {
+						hasSystem: output.system.length > 0,
+						sessionID: (input as { sessionID?: string })?.sessionID ?? null,
+					})
+					return
+				}
+
+				if (output.system.length > 0) {
+					output.system[output.system.length - 1] += `\n\n${MEMORY_INSTRUCTIONS}`
+				} else {
+					output.system.push(MEMORY_INSTRUCTIONS)
+				}
+
+				await pluginLog('info', 'system.transform.injected', {
+					hasSystem: output.system.length > 0,
+					sessionID: (input as { sessionID?: string })?.sessionID ?? null,
+				})
+			} catch (error) {
+				await pluginLog('error', 'system.transform.failed', { error: stringifyError(error) })
+			}
+		},
+
+		// Fallback injection path for clients where system transform is not surfaced as expected.
+		'experimental.chat.messages.transform': async (_input: unknown, output: MessageTransformOutput) => {
+			try {
+				if (hasProtocolMarkerInMessages(output)) {
+					await pluginLog('debug', 'messages.transform.skip.already-present', {
+						messageCount: output.messages.length,
+					})
+					return
+				}
+
+				output.messages.unshift({
+					info: {
+						role: 'system',
+						source: SERVICE,
+					},
+					parts: [
+						{
+							type: 'text',
+							text: MEMORY_INSTRUCTIONS,
+							synthetic: true,
+						},
+					],
+				})
+
+				await pluginLog('info', 'messages.transform.injected-fallback', {
+					messageCount: output.messages.length,
+				})
+			} catch (error) {
+				await pluginLog('error', 'messages.transform.failed', { error: stringifyError(error) })
 			}
-			output.system.push(MEMORY_INSTRUCTIONS)
 		},
 
 		'experimental.session.compacting': async (
 			input: SessionCompactingInput,
 			output: SessionCompactingOutput,
 		) => {
-			const sessionId = input.sessionID ?? '<current-session-id>'
-			output.context.push(
-				[
-					'FIRST ACTION REQUIRED:',
-					`Call suemo_session_context_set({ sessionId: "${sessionId}", summary: "<compacted summary>" }) before any other work.`,
-					'Then call suemo_context({ scope: "<project-scope>", limit: 20 }) to recover continuity.',
-				].join(' '),
-			)
+			try {
+				const sessionId = input.sessionID ?? '<current-session-id>'
+				output.context.push(
+					[
+						'FIRST ACTION REQUIRED:',
+						`Call suemo_session_context_set({ sessionId: "${sessionId}", summary: "<compacted summary>" }) before any other work.`,
+						'Then call suemo_context({ scope: "<project-scope>", limit: 20 }) to recover continuity.',
+					].join(' '),
+				)
+
+				await pluginLog('info', 'session.compacting.reminder-injected', { sessionID: sessionId })
+			} catch (error) {
+				await pluginLog('error', 'session.compacting.failed', { error: stringifyError(error) })
+			}
 		},
 	}
+
+	return hooks
 }
 
 export default Suemo

package/src/sync.ts

@@ -1,9 +1,9 @@
 import type { SurrealTarget } from '@/src/config.ts'
+import { createSurrealEngines, toSurrealConnectionError } from '@/src/db/engines.ts'
 import { getLogger } from '@/src/logger.ts'
 import type { SyncResult } from '@/src/types.ts'
-import { createNodeEngines } from '@surrealdb/node'
 import { createHash } from 'node:crypto'
-import { createRemoteEngines, Surreal } from 'surrealdb'
+import { Surreal } from 'surrealdb'
 
 const log = getLogger(['suemo', 'sync'])
 
@@ -32,21 +32,24 @@ function remoteKey(target: SurrealTarget): string {
 }
 
 async function makeRemoteDb(target: SurrealTarget): Promise<Surreal> {
-	const db = new Surreal({
-		engines: {
-			...createRemoteEngines(),
-			...createNodeEngines(),
-		},
-	})
-	await db.connect(target.url, {
-		namespace: target.namespace,
-		database: target.database,
-		authentication: () => ({
-			username: target.auth.user,
-			password: target.auth.pass,
-		}),
-	})
-	return db
+	try {
+		const engines = await createSurrealEngines({
+			url: target.url,
+			context: 'sync:remote-connect',
+		})
+		const db = new Surreal({ engines })
+		await db.connect(target.url, {
+			namespace: target.namespace,
+			database: target.database,
+			authentication: () => ({
+				username: target.auth.user,
+				password: target.auth.pass,
+			}),
+		})
+		return db
+	} catch (error) {
+		throw toSurrealConnectionError(error, 'sync:remote-connect', target.url)
+	}
 }
 
 async function pushMemoryBatch(

package/src/types.ts

@@ -3,13 +3,15 @@
 import { z } from 'zod'
 
 // ── Memory kinds ─────────────────────────────────────────────────────────────
-export const MemoryKindSchema = z.enum([
+export const MEMORY_KIND_VALUES = [
 	'observation',
 	'belief',
 	'question',
 	'hypothesis',
 	'goal',
-])
+] as const
+
+export const MemoryKindSchema = z.enum(MEMORY_KIND_VALUES)
 export type MemoryKind = z.infer<typeof MemoryKindSchema>
 
 // ── Relation kinds ───────────────────────────────────────────────────────────
@@ -47,6 +49,11 @@ export const MemoryNodeSchema = z.object({
 	fsrs_stability: z.number().nullable(),
 	fsrs_difficulty: z.number().nullable(),
 	fsrs_next_review: z.iso.datetime().nullable(),
+	fsrs_state: z.enum(['new', 'learning', 'review', 'relearning']).nullable(),
+	fsrs_last_review: z.iso.datetime().nullable(),
+	fsrs_reps: z.number().int().nullable(),
+	fsrs_lapses: z.number().int().nullable(),
+	fsrs_last_grade: z.number().int().min(1).max(4).nullable(),
 })
 export type MemoryNode = z.infer<typeof MemoryNodeSchema>