suemo 0.1.7 → 0.1.9

package/README.md

@@ -11,7 +11,25 @@
 
 suemo gives AI agents a memory that survives across sessions, models, and runtimes. Write observations from a Telegram bot, query them from OpenCode, consolidate overnight — all agents share one source of truth in SurrealDB.
 
-Canonical behavioral specification: **[`SPEC.md`](./SPEC.md)**.
+Specifications:
+
+- Index: **[`specs/SPEC.md`](./specs/SPEC.md)**
+- Technical/runtime contract: **[`specs/SPEC-technical.md`](./specs/SPEC-technical.md)**
+- Psychological/critique framing: **[`specs/SPEC-psychological.md`](./specs/SPEC-psychological.md)**
+
+## For professional critique authors (longevity-focused)
+
+If you're designing high-quality external critiques for suemo, evaluate it as **persistent coding-agent memory infrastructure**, not as a general AGI cognition claim.
+
+Use this framing:
+
+1. **Psychological intent** — what memory quality should hold over time?
+2. **Technical mechanism** — what exact table/field/tool enforces that quality?
+3. **Operational evidence** — what logs/tests/metrics prove it under drift and contradiction?
+
+Questions are most useful when they stress long-horizon behavior (30–180 day operation), contradiction handling, consolidation quality, retrieval interference, and scope/session isolation.
+
+For rigorous critique language and category framing, start from **[`specs/SPEC-psychological.md`](./specs/SPEC-psychological.md)**.
 
 ---
 
@@ -466,7 +484,7 @@ Current behavior: only write paths invoked with `sessionId` append to `memory_id
 - CLI: `suemo believe "..." --session <sessionId>`
 - MCP: `believe({ content, sessionId, ... })`
 
-See `SPEC.md` for full normative semantics and hardening targets.
+See `specs/SPEC-technical.md` for full normative semantics and hardening targets.
 
 ### Scope and longevity notes
 
@@ -526,7 +544,7 @@ These scenarios intentionally exercise all memory kinds and all relation kinds,
 - **Runtime** — [Bun](https://bun.sh)
 - **Language** — TypeScript (strict, `exactOptionalPropertyTypes`)
 - **Database** — [SurrealDB](https://surrealdb.com) v3.0+ (SurrealKV)
-- **SDK** — [surrealdb.js](https://github.com/surrealdb/surrealdb.js) v2 + `@surrealdb/node`
+- **SDK** — [surrealdb.js](https://github.com/surrealdb/surrealdb.js) v2 + `@mdrv/surreal-node` (fork of `@surrealdb/node`)
 - **CLI** — [crust](https://github.com/chenxin-yan/crust) (`@crustjs/core`)
 - **HTTP / MCP** — [Elysia](https://elysiajs.com) v1.4
 - **Validation** — [Zod](https://zod.dev) v4

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "suemo",
-	"version": "0.1.7",
+	"version": "0.1.9",
 	"description": "Persistent semantic memory for AI agents — backed by SurrealDB.",
 	"author": {
 		"name": "Umar Alfarouk",
@@ -37,10 +37,11 @@
 	"scripts": {
 		"dev": "bun run src/cli/index.ts",
 		"start": "bun run src/cli/index.ts",
+		"test": "bun test",
 		"ssot:check": "bun run scripts/ssot.ts check",
 		"ssot:sync": "bun run scripts/ssot.ts sync",
 		"fmt": "dprint fmt",
-		"check": "bun run fmt && bun tsc --noEmit && bun run ssot:check",
+		"check": "bun run fmt && bun tsc --noEmit && bun test && bun run ssot:check",
 		"sync": "bun run ssot:sync"
 	},
 	"dependencies": {
@@ -50,12 +51,13 @@
 		"@crustjs/style": "^0.0.6",
 		"@logtape/file": "^2.0.4",
 		"@logtape/logtape": "^2.0.4",
-		"@surrealdb/node": "^3.0.3",
+		"@mdrv/surreal-node": "latest",
 		"elysia": "^1.4.28",
 		"surrealdb": "^2.0.3",
 		"zod": "^4.3.6"
 	},
 	"devDependencies": {
+		"@opencode-ai/plugin": "^1.3.0",
 		"@types/bun": "^1.3.11",
 		"typescript": "^5.9.3"
 	}

package/skills/suemo/SKILL.md

@@ -3,14 +3,14 @@ name: suemo
 description: OpenCode-focused persistent memory workflow for suemo with CLI/MCP parity and versioned references.
 license: GPL-3.0-only
 compatibility: opencode
-version: 0.1.7
+version: 0.1.9
 ---
 
 # suemo skill
 
 Use suemo to persist technical context across sessions with minimal, project-scoped memory.
 
-## Strict defaults (v0.1.7)
+## Strict defaults (v0.1.8)
 
 - Always run pre-checks before implementation:
   - `goal_list({ scope })`

package/skills/suemo/references/agents-snippet.md

@@ -1,7 +1,7 @@
 ---
 name: agents-snippet
 description: AGENTS.md snippet optimized for suemo skill discovery and usage.
-version: 0.1.7
+version: 0.1.9
 ---
 
 # AGENTS.md snippet

package/skills/suemo/references/cli-reference.md

@@ -1,7 +1,7 @@
 ---
 name: cli-reference
 description: CLI command reference for suemo v0.0.6 including skill access.
-version: 0.1.7
+version: 0.1.9
 ---
 
 # CLI reference

package/skills/suemo/references/core-workflow.md

@@ -1,7 +1,7 @@
 ---
 name: core-workflow
 description: Canonical suemo operating loop for OpenCode agents.
-version: 0.1.7
+version: 0.1.9
 ---
 
 # Core workflow

package/skills/suemo/references/manual-test-plan.md

@@ -1,7 +1,7 @@
 ---
 name: manual-test-plan
 description: Comprehensive manual test matrix for suemo features and commands.
-version: 0.1.7
+version: 0.1.9
 ---
 
 # Manual test plan

package/skills/suemo/references/mcp-reference.md

@@ -1,7 +1,7 @@
 ---
 name: mcp-reference
 description: MCP tool reference for suemo v0.0.6.
-version: 0.1.7
+version: 0.1.9
 ---
 
 # MCP tools

package/skills/suemo/references/schema-retention-longevity.md

@@ -1,7 +1,7 @@
 ---
 name: schema-retention-longevity
 description: Long-term schema and retention design expectations for suemo.
-version: 0.1.7
+version: 0.1.9
 ---
 
 # Schema + retention longevity

package/skills/suemo/references/sync-local-vps.md

@@ -1,7 +1,7 @@
 ---
 name: sync-local-vps
 description: Two-way sync manual scenario for local and VPS SurrealDB.
-version: 0.1.7
+version: 0.1.9
 ---
 
 # Local ↔ VPS sync scenario

package/src/AGENTS.md

@@ -127,4 +127,4 @@ Load docs once per session unless requirements changed.
 
 ---
 
-_Version: 0.1.7 | Updated: 2026-03-23 | Summary: stricter schema + explicit completion contract_
+_Version: 0.1.9 | Updated: 2026-03-24 | Summary: stricter schema + explicit completion contract_

package/src/cli/commands/health.ts

@@ -29,7 +29,7 @@ const reportCmd = health.sub('report')
 		let db: Surreal | undefined
 		try {
 			db = await connect(config.surreal)
-			const report = await healthReport(db)
+			const report = await healthReport(db, { embeddingProvider: config.embedding.provider })
 			if (outputMode === 'json') {
 				printCliJson(report, flags)
 			} else {
@@ -129,7 +129,7 @@ export const healthCmd = health
 		let db: Surreal | undefined
 		try {
 			db = await connect(config.surreal)
-			const report = await healthReport(db)
+			const report = await healthReport(db, { embeddingProvider: config.embedding.provider })
 			if (outputMode === 'json') {
 				printCliJson(report, flags)
 			} else {

package/src/cli/commands/recall.ts

@@ -10,6 +10,9 @@ export const recallCmd = app.sub('recall')
 	.meta({ description: 'Fetch a single node + its neighbours (ticks FSRS)' })
 	.args([{ name: 'nodeId', type: 'string', required: true }])
 	.flags({
+		rating: { type: 'number', short: 'r', description: 'FSRS rating (1=Again,2=Hard,3=Good,4=Easy)' },
+		at: { type: 'string', description: 'ISO datetime override for deterministic replay/testing' },
+		'dry-run': { type: 'boolean', description: 'Compute FSRS schedule without writing', default: false },
 		json: { type: 'boolean', description: 'Output full JSON' },
 		pretty: { type: 'boolean', description: 'Human-readable output (default)' },
 	})
@@ -25,13 +28,38 @@ export const recallCmd = app.sub('recall')
 		const config = await loadConfig(process.cwd(), flags.config)
 		const db = await connect(config.surreal)
 		try {
-			const result = await recall(db, args.nodeId)
+			const rating = flags.rating === undefined ? undefined : Number(flags.rating)
+			if (rating !== undefined && ![1, 2, 3, 4].includes(rating)) {
+				throw new Error(`Invalid --rating value: ${flags.rating}. Expected one of: 1,2,3,4`)
+			}
+			if (flags.at) {
+				const atDate = new Date(String(flags.at))
+				if (Number.isNaN(atDate.getTime())) {
+					throw new Error(`Invalid --at datetime: ${flags.at}`)
+				}
+			}
+
+			const result = await recall(db, args.nodeId, {
+				...(rating !== undefined ? { rating: rating as 1 | 2 | 3 | 4 } : {}),
+				...(flags.at ? { at: String(flags.at) } : {}),
+				dryRun: Boolean(flags['dry-run']),
+			})
+			log.debug('recall command completed', {
+				nodeId: args.nodeId,
+				rating: result.fsrs.rating,
+				nextReview: result.fsrs.nextReview,
+				stateAfter: result.fsrs.stateAfter,
+				dryRun: result.fsrs.dryRun,
+			})
 			if (outputMode === 'json') {
 				printCliJson(result, flags)
 			} else {
 				console.log(`[${result.node.kind}] ${result.node.id}`)
 				console.log(`  ${result.node.content.slice(0, 120)}`)
 				console.log(`  neighbors: ${result.neighbors.length}`)
+				console.log(`  fsrs: rating=${result.fsrs.rating} interval=${result.fsrs.intervalDays}d`)
+				console.log(`  next_review: ${result.fsrs.nextReview} (${result.fsrs.stateAfter})`)
+				if (result.fsrs.dryRun) console.log('  [dry-run] no FSRS state written')
 			}
 		} finally {
 			await disconnect()

package/src/cli/commands/serve.ts

@@ -192,12 +192,24 @@ export const serveCmd = app.sub('serve')
 		}
 		if (flags.stdio) {
 			log.debug('Starting MCP stdio transport')
+			log.debug('Serve transport resolved', {
+				transport: 'stdio',
+				embeddingProvider: config.embedding.provider,
+				autoSyncEnabled: Boolean(sync?.auto.enabled),
+			})
 			await runServerWithDevRetry({ stdio: true, config })
 			return
 		}
 		if (flags.port) config.mcp.port = flags.port
 		if (flags.host) config.mcp.host = flags.host
 		log.debug('Starting MCP HTTP transport', { host: config.mcp.host, port: config.mcp.port })
+		log.debug('Serve transport resolved', {
+			transport: 'http',
+			host: config.mcp.host,
+			port: config.mcp.port,
+			embeddingProvider: config.embedding.provider,
+			autoSyncEnabled: Boolean(sync?.auto.enabled),
+		})
 		await runServerWithDevRetry({ stdio: false, config })
 		// Server runs indefinitely — no disconnect
 	})

package/src/cognitive/consolidate.ts

@@ -168,7 +168,12 @@ async function runNREM(
         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
       }
     `,
 			{

package/src/cognitive/health.ts

@@ -1,3 +1,4 @@
+import type { EmbeddingProvider } from '@/src/config.ts'
 import { checkCompatibility } from '@/src/db/preflight.ts'
 import { getLogger } from '@/src/logger.ts'
 import type { ConsolidationRun, HealthReport, SuemoStats } from '@/src/types.ts'
@@ -5,8 +6,14 @@ import type { Surreal } from 'surrealdb'
 
 const log = getLogger(['suemo', 'cognitive', 'health'])
 
-export async function healthReport(db: Surreal): Promise<HealthReport> {
-	log.debug('healthReport()')
+export async function healthReport(
+	db: Surreal,
+	options: { embeddingProvider?: EmbeddingProvider['provider'] } = {},
+): Promise<HealthReport> {
+	log.debug('healthReport()', {
+		embeddingProvider: options.embeddingProvider ?? null,
+		context: 'health:report',
+	})
 
 	const [
 		totalResult,
@@ -61,9 +68,24 @@ export async function healthReport(db: Surreal): Promise<HealthReport> {
 			'SELECT * FROM consolidation_run ORDER BY started_at DESC LIMIT 1',
 		),
 		// compat check (non-blocking)
-		checkCompatibility(db),
+		checkCompatibility(db, {
+			...(options.embeddingProvider ? { embeddingProvider: options.embeddingProvider } : {}),
+			context: 'health:report',
+		}),
 	])
 
+	log.debug('healthReport() query batches complete', {
+		totalRows: totalResult[0]?.length ?? 0,
+		activeRows: activeResult[0]?.length ?? 0,
+		consolidatedRows: consolidatedResult[0]?.length ?? 0,
+		byKindRows: byKindResult[0]?.length ?? 0,
+		byScopeRows: byScopeResult[0]?.length ?? 0,
+		relationRows: relationCountResult[0]?.length ?? 0,
+		goalsRows: activeGoalsResult[0]?.length ?? 0,
+		fsrsDueRows: frssDueResult[0]?.length ?? 0,
+		compatOk: compatResult.ok,
+	})
+
 	const byKind: Record<string, number> = {}
 	for (const row of byKindResult[0] ?? []) byKind[row.kind] = row.count
 

package/src/db/client.ts

@@ -3,7 +3,7 @@
 // createNodeEngines() patches in the Node.js WebSocket implementation.
 import type { SurrealTarget } from '@/src/config.ts'
 import { getLogger } from '@/src/logger.ts'
-import { createNodeEngines } from '@surrealdb/node'
+import { createNodeEngines } from '@mdrv/surreal-node'
 import { createRemoteEngines, Surreal } from 'surrealdb'
 
 const log = getLogger(['suemo', 'db', 'client'])

package/src/db/preflight.ts

@@ -18,6 +18,11 @@ export interface CompatibilityOptions {
 	 * Keep true for runtime paths that execute vector/embed queries.
 	 */
 	requireEmbedding?: boolean
+	/**
+	 * Embedding provider profile for this runtime.
+	 * When set, requireEmbedding defaults to true only for surrealml.
+	 */
+	embeddingProvider?: 'surrealml' | 'openai-compatible' | 'stub'
 	/**
 	 * Human-readable label for logging this preflight execution.
 	 */
@@ -35,10 +40,12 @@ export async function checkCompatibility(
 	let surrealkv = false
 	let retention_ok = false
 	let embedding = false
-	const requireEmbedding = options.requireEmbedding ?? true
+	const embeddingProvider = options.embeddingProvider
+	const requireEmbedding = options.requireEmbedding
+		?? (embeddingProvider ? embeddingProvider === 'surrealml' : true)
 	const context = options.context ?? 'default'
 
-	log.info('Running preflight compatibility checks', { requireEmbedding, context })
+	log.info('Running preflight compatibility checks', { requireEmbedding, embeddingProvider, context })
 
 	// ── Check 1: version string ───────────────────────────────────────────────
 	try {
@@ -126,31 +133,41 @@ export async function checkCompatibility(
 	// ── Check 4: fn::embed() resolves ────────────────────────────────────────
 	// We don't actually embed anything — we just check that the function exists.
 	// An "Unknown function" error means embedding runtime is unavailable.
-	try {
-		// fn::embed requires the ML module and a configured model.
-		// If it throws "No embedding model configured" that's acceptable — the
-		// function exists. If it throws "Unknown function 'fn::embed'" → not available.
-		await db.query(`RETURN fn::embed("suemo preflight test")`)
-		embedding = true
-		log.debug('Embedding function probe passed')
-	} catch (e: unknown) {
-		const msg = String(e).toLowerCase()
-		if (msg.includes('unknown function') || msg.includes('fn::embed')) {
-			embedding = false
-			if (requireEmbedding) {
-				errors.push(
-					'fn::embed() is not available in this SurrealDB database. Import/configure a SurrealML embedding model for this namespace/database, then retry.',
-				)
+	if (!requireEmbedding && embeddingProvider && embeddingProvider !== 'surrealml') {
+		embedding = false
+		log.info('Skipping fn::embed preflight check for non-surrealml provider', {
+			context,
+			embeddingProvider,
+		})
+	} else {
+		try {
+			// fn::embed requires the ML module and a configured model.
+			// If it throws "No embedding model configured" that's acceptable — the
+			// function exists. If it throws "Unknown function 'fn::embed'" → not available.
+			await db.query(`RETURN fn::embed("suemo preflight test")`)
+			embedding = true
+			log.debug('Embedding function probe passed')
+		} catch (e: unknown) {
+			const msg = String(e).toLowerCase()
+			if (msg.includes('unknown function') || msg.includes('fn::embed')) {
+				embedding = false
+				if (requireEmbedding) {
+					errors.push(
+						'fn::embed() is not available in this SurrealDB database. Import/configure a SurrealML embedding model for this namespace/database, then retry.',
+					)
+				} else {
+					log.warn('Embedding function unavailable; continuing due to non-strict preflight mode', {
+						context,
+						error: String(e),
+					})
+				}
 			} else {
-				log.warn('Embedding function unavailable; continuing due to non-strict preflight mode', {
-					context,
+				// Other error (e.g. no model configured but function exists) — treat as available
+				embedding = true
+				log.debug('fn::embed() exists but returned an error (model may not be configured yet)', {
 					error: String(e),
 				})
 			}
-		} else {
-			// Other error (e.g. no model configured but function exists) — treat as available
-			embedding = true
-			log.debug('fn::embed() exists but returned an error (model may not be configured yet)', { error: String(e) })
 		}
 	}
 
@@ -158,9 +175,18 @@ export async function checkCompatibility(
 	const embedSkipped = !requireEmbedding && !embedding
 
 	if (ok) {
-		log.info('All preflight checks passed', { surrealVersion, surrealkv, retention_ok, embedding })
+		log.info('All preflight checks passed', {
+			surrealVersion,
+			surrealkv,
+			retention_ok,
+			embedding,
+			embeddingProvider,
+		})
 		if (embedSkipped) {
-			log.info('fn::embed preflight check skipped due to non-surrealml embedding profile', { context })
+			log.info('fn::embed preflight check skipped due to non-surrealml embedding profile', {
+				context,
+				embeddingProvider,
+			})
 		}
 	} else {
 		log.error('Preflight checks failed', { errors })
@@ -172,8 +198,11 @@ export async function checkCompatibility(
 /**
  * Hard-exit variant. Call in CLI commands; throw in MCP server startup.
  */
-export async function requireCompatibility(db: Surreal): Promise<void> {
-	const result = await checkCompatibility(db)
+export async function requireCompatibility(
+	db: Surreal,
+	options: CompatibilityOptions = {},
+): Promise<void> {
+	const result = await checkCompatibility(db, options)
 	if (!result.ok) {
 		const details = result.errors.map((err) => `  ✗ ${err}`).join('\n')
 		throw new Error(`\n[suemo] Compatibility check failed:\n\n${details}\n\nFix the issues above and retry.\n`)

package/src/db/schema.surql

@@ -38,6 +38,13 @@ DEFINE FIELD OVERWRITE consolidated_into ON memory
 DEFINE FIELD OVERWRITE fsrs_stability   ON memory TYPE option<float>;
 DEFINE FIELD OVERWRITE fsrs_difficulty  ON memory TYPE option<float>;
 DEFINE FIELD OVERWRITE fsrs_next_review ON memory TYPE option<datetime>;
+DEFINE FIELD OVERWRITE fsrs_state       ON memory TYPE option<string>
+  ASSERT $value = NONE OR $value INSIDE ['new','learning','review','relearning'];
+DEFINE FIELD OVERWRITE fsrs_last_review ON memory TYPE option<datetime>;
+DEFINE FIELD OVERWRITE fsrs_reps        ON memory TYPE option<int>;
+DEFINE FIELD OVERWRITE fsrs_lapses      ON memory TYPE option<int>;
+DEFINE FIELD OVERWRITE fsrs_last_grade  ON memory TYPE option<int>
+  ASSERT $value = NONE OR $value INSIDE [1,2,3,4];
 
 -- Vector index: HNSW (keep syntax compatible with current SurrealDB target)
 DEFINE INDEX OVERWRITE idx_memory_embedding

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',
 		})