suemo 0.0.2 → 0.0.4

package/src/config.ts

@@ -19,7 +19,7 @@ export interface SurrealTarget {
 
 export type EmbeddingProvider =
 	| { provider: 'openai-compatible'; url: string; model: string; dimension: number; apiKey?: string }
-	| { provider: 'surreal'; dimension: number }
+	| { provider: 'surrealml'; dimension: number }
 	| { provider: 'stub'; dimension: number }
 
 export interface LLMConfig {
@@ -51,9 +51,41 @@ export interface McpConfig {
 	host: string
 }
 
+export type SyncDirectionConfig = 'push' | 'pull' | 'both'
+
+export interface SyncAutoConfig {
+	enabled?: boolean
+	intervalSeconds?: number
+	direction?: SyncDirectionConfig
+	remote?: string
+	onWrite?: boolean
+	minWriteIntervalSeconds?: number
+}
+
 export interface SyncConfig {
-	remote: SurrealTarget
-	cursor?: string // ISO datetime; absence means full sync on first run
+	/** Legacy single-remote config (still supported for migration safety). */
+	remote?: SurrealTarget
+	/** Named remotes for selectable sync targets. */
+	remotes?: Record<string, SurrealTarget>
+	/** Default key from `remotes` when no explicit remote is selected. */
+	defaultRemote?: string
+	/** Optional auto-sync behavior for long-running MCP servers. */
+	auto?: SyncAutoConfig
+}
+
+export interface ResolvedSyncAutoConfig {
+	enabled: boolean
+	intervalSeconds: number
+	direction: SyncDirectionConfig
+	remote: string
+	onWrite: boolean
+	minWriteIntervalSeconds: number
+}
+
+export interface ResolvedSyncConfig {
+	remotes: Record<string, SurrealTarget>
+	defaultRemote: string
+	auto: ResolvedSyncAutoConfig
 }
 
 export interface SuemoConfig {
@@ -71,6 +103,55 @@ export function defineConfig(config: SuemoConfig): SuemoConfig {
 	return config
 }
 
+export function resolveSyncConfig(config: SuemoConfig): ResolvedSyncConfig | null {
+	if (!config.sync) return null
+
+	const remotes: Record<string, SurrealTarget> = config.sync.remotes
+		? { ...config.sync.remotes }
+		: (config.sync.remote ? { default: config.sync.remote } : {})
+
+	const remoteNames = Object.keys(remotes)
+	if (remoteNames.length === 0) return null
+
+	const defaultRemote = config.sync.defaultRemote ?? remoteNames[0]!
+	if (!remotes[defaultRemote]) {
+		throw new Error(
+			`sync.defaultRemote \"${defaultRemote}\" does not exist in sync.remotes. Available: ${remoteNames.join(', ')}`,
+		)
+	}
+
+	const auto = config.sync.auto ?? {}
+	const intervalSeconds = auto.intervalSeconds ?? 300
+	const minWriteIntervalSeconds = auto.minWriteIntervalSeconds ?? 30
+
+	if (!Number.isFinite(intervalSeconds) || intervalSeconds <= 0) {
+		throw new Error('sync.auto.intervalSeconds must be a positive number')
+	}
+	if (!Number.isFinite(minWriteIntervalSeconds) || minWriteIntervalSeconds < 0) {
+		throw new Error('sync.auto.minWriteIntervalSeconds must be >= 0')
+	}
+
+	const autoRemote = auto.remote ?? defaultRemote
+	if (!remotes[autoRemote]) {
+		throw new Error(
+			`sync.auto.remote \"${autoRemote}\" does not exist in sync.remotes. Available: ${remoteNames.join(', ')}`,
+		)
+	}
+
+	return {
+		remotes,
+		defaultRemote,
+		auto: {
+			enabled: auto.enabled ?? false,
+			intervalSeconds,
+			direction: auto.direction ?? 'push',
+			remote: autoRemote,
+			onWrite: auto.onWrite ?? false,
+			minWriteIntervalSeconds,
+		},
+	}
+}
+
 // ── loadConfig — resolution chain ────────────────────────────────────────────
 
 const CONFIG_CANDIDATES = [
@@ -135,9 +216,9 @@ export async function loadConfig(
 async function importConfig(path: string): Promise<SuemoConfig> {
 	log.debug('Importing config module', { path })
 	const mod = await import(pathToFileURL(path).href)
-	const cfg: unknown = mod.default ?? mod
-	if (!cfg || typeof cfg !== 'object') {
+	const cfgRaw: unknown = mod.default ?? mod
+	if (!cfgRaw || typeof cfgRaw !== 'object') {
 		throw new Error(`Config at ${path} does not export a default object`)
 	}
-	return cfg as SuemoConfig // trust defineConfig() for now; add Zod parse if needed
+	return cfgRaw as SuemoConfig // trust defineConfig() for now; add Zod parse if needed
 }

package/src/db/preflight.ts

@@ -65,7 +65,7 @@ export async function checkCompatibility(
 	// We CREATE a sentinel record, query it with VERSION, then DELETE it.
 	// If VERSION errors, the storage engine is not SurrealKV.
 	try {
-		await db.query('CREATE suemo_preflight:probe SET checked_at = time::now()')
+		await db.query('UPSERT suemo_preflight:probe SET checked_at = time::now()')
 		// VERSION at a past datetime should return an empty result set (or the record
 		// if it was around then), not throw. An error means VERSION is unsupported.
 		await db.query("SELECT * FROM suemo_preflight:probe VERSION d'2020-01-01T00:00:00Z'")
@@ -97,7 +97,7 @@ export async function checkCompatibility(
 	if (surrealkv) {
 		try {
 			const ninetyDaysAgo = new Date(Date.now() - 90 * 24 * 60 * 60 * 1000).toISOString()
-			await db.query('CREATE suemo_retention_probe:v SET t = time::now()')
+			await db.query('UPSERT suemo_retention_probe:v SET t = time::now()')
 			await db.query(`SELECT * FROM suemo_retention_probe:v VERSION d'${ninetyDaysAgo}'`)
 			retention_ok = true
 			log.debug('Retention probe passed', { ninetyDaysAgo })
@@ -152,9 +152,13 @@ export async function checkCompatibility(
 	}
 
 	const ok = errors.length === 0
+	const embedSkipped = !requireEmbedding && !embedding
 
 	if (ok) {
 		log.info('All preflight checks passed', { surrealVersion, surrealkv, retention_ok, embedding })
+		if (embedSkipped) {
+			log.info('fn::embed preflight check skipped due to non-surrealml embedding profile', { context })
+		}
 	} else {
 		log.error('Preflight checks failed', { errors })
 	}

package/src/db/schema.surql

@@ -13,6 +13,7 @@ DEFINE FIELD OVERWRITE content      ON memory TYPE string;
 DEFINE FIELD OVERWRITE summary      ON memory TYPE option<string>;
 DEFINE FIELD OVERWRITE tags         ON memory TYPE set<string>    DEFAULT {};
 DEFINE FIELD OVERWRITE scope        ON memory TYPE option<string>;
+DEFINE FIELD OVERWRITE topic_key    ON memory TYPE option<string> DEFAULT NONE;
 DEFINE FIELD OVERWRITE embedding    ON memory TYPE array<float>   DEFAULT [];
 DEFINE FIELD OVERWRITE confidence   ON memory TYPE float          DEFAULT 1.0;
 DEFINE FIELD OVERWRITE salience     ON memory TYPE float          DEFAULT 0.5;
@@ -24,6 +25,7 @@ DEFINE FIELD OVERWRITE valid_from   ON memory TYPE datetime       DEFAULT time::
 DEFINE FIELD OVERWRITE valid_until  ON memory TYPE option<datetime> DEFAULT NONE;
 
 DEFINE FIELD OVERWRITE source       ON memory TYPE option<string>;
+DEFINE FIELD OVERWRITE prompt_source ON memory TYPE option<record<memory>> DEFAULT NONE;
 DEFINE FIELD OVERWRITE created_at   ON memory TYPE datetime       DEFAULT time::now();
 DEFINE FIELD OVERWRITE updated_at   ON memory TYPE datetime       DEFAULT time::now();
 DEFINE FIELD OVERWRITE consolidated ON memory TYPE bool           DEFAULT false;
@@ -65,6 +67,9 @@ DEFINE INDEX OVERWRITE idx_memory_kind_valid
 DEFINE INDEX OVERWRITE idx_memory_salience
   ON memory FIELDS salience;
 
+DEFINE INDEX OVERWRITE idx_memory_topic_key
+  ON memory FIELDS topic_key;
+
 -- ── relates_to ───────────────────────────────────────────────────────────────
 DEFINE TABLE OVERWRITE relates_to SCHEMAFULL
   TYPE RELATION IN memory OUT memory;
@@ -76,6 +81,7 @@ DEFINE FIELD OVERWRITE strength   ON relates_to TYPE float   DEFAULT 0.5;
 DEFINE FIELD OVERWRITE valid_from  ON relates_to TYPE datetime DEFAULT time::now();
 DEFINE FIELD OVERWRITE valid_until ON relates_to TYPE option<datetime> DEFAULT NONE;
 DEFINE FIELD OVERWRITE created_at ON relates_to TYPE datetime DEFAULT time::now();
+DEFINE FIELD OVERWRITE updated_at ON relates_to TYPE datetime DEFAULT time::now();
 
 -- ── episode ───────────────────────────────────────────────────────────────────
 DEFINE TABLE OVERWRITE episode SCHEMAFULL;
@@ -84,6 +90,7 @@ DEFINE FIELD OVERWRITE session_id  ON episode TYPE string;
 DEFINE FIELD OVERWRITE started_at  ON episode TYPE datetime DEFAULT time::now();
 DEFINE FIELD OVERWRITE ended_at    ON episode TYPE option<datetime> DEFAULT NONE;
 DEFINE FIELD OVERWRITE summary     ON episode TYPE option<string>;
+DEFINE FIELD OVERWRITE context     ON episode TYPE option<object> FLEXIBLE DEFAULT NONE;
 
 -- REFERENCES: bidirectional array of memory links
 DEFINE FIELD OVERWRITE memory_ids  ON episode
@@ -105,8 +112,19 @@ DEFINE FIELD OVERWRITE error        ON consolidation_run TYPE option<string> DEF
 
 -- ── sync_cursor ───────────────────────────────────────────────────────────────
 -- One record per (remote.url, remote.ns, remote.db) triple.
--- Stores the last successfully synced created_at timestamp.
+-- Stores per-remote cursors for push/pull sync based on updated_at.
 DEFINE TABLE OVERWRITE sync_cursor SCHEMAFULL;
 DEFINE FIELD OVERWRITE remote_key  ON sync_cursor TYPE string;  -- sha1(url+ns+db)
 DEFINE FIELD OVERWRITE cursor      ON sync_cursor TYPE datetime;
+DEFINE FIELD OVERWRITE push_cursor ON sync_cursor TYPE datetime DEFAULT d'1970-01-01T00:00:00Z';
+DEFINE FIELD OVERWRITE pull_cursor ON sync_cursor TYPE datetime DEFAULT d'1970-01-01T00:00:00Z';
 DEFINE FIELD OVERWRITE last_synced ON sync_cursor TYPE datetime DEFAULT time::now();
+
+-- ── suemo_stats ──────────────────────────────────────────────────────────────
+DEFINE TABLE OVERWRITE suemo_stats SCHEMAFULL;
+DEFINE FIELD OVERWRITE ns_db         ON suemo_stats TYPE string;
+DEFINE FIELD OVERWRITE total_writes  ON suemo_stats TYPE int DEFAULT 0;
+DEFINE FIELD OVERWRITE total_queries ON suemo_stats TYPE int DEFAULT 0;
+DEFINE FIELD OVERWRITE last_write    ON suemo_stats TYPE option<datetime> DEFAULT NONE;
+DEFINE FIELD OVERWRITE last_query    ON suemo_stats TYPE option<datetime> DEFAULT NONE;
+DEFINE INDEX OVERWRITE idx_stats_ns  ON suemo_stats FIELDS ns_db;

package/src/db/schema.ts

@@ -5,6 +5,29 @@ import SCHEMA from './schema.surql' with { type: 'text' }
 
 const log = getLogger(['suemo', 'db', 'schema'])
 
+const MAX_RETRY_ATTEMPTS = 6
+const BASE_RETRY_DELAY_MS = 100
+const MAX_RETRY_DELAY_MS = 1500
+
+function isRetryableSchemaError(error: unknown): boolean {
+	const message = String(error).toLowerCase()
+	return message.includes('transaction conflict')
+		|| message.includes('write conflict')
+		|| message.includes('serialization')
+		|| message.includes('temporarily unavailable')
+		|| message.includes('can be retried')
+}
+
+function computeRetryDelayMs(attempt: number): number {
+	const raw = Math.min(MAX_RETRY_DELAY_MS, BASE_RETRY_DELAY_MS * (2 ** attempt))
+	const jitterFactor = 0.8 + Math.random() * 0.4
+	return Math.round(raw * jitterFactor)
+}
+
+async function sleep(ms: number): Promise<void> {
+	await new Promise((resolve) => setTimeout(resolve, ms))
+}
+
 // schema.surql is inlined as a template string to avoid filesystem read concerns
 // at runtime. Each statement is separated by ";\n" and executed individually.
 
@@ -13,15 +36,40 @@ export async function runSchema(db: Surreal): Promise<void> {
 	const statements = SCHEMA.split(/;\s*\n/).map((s) => s.trim()).filter(Boolean)
 	log.debug('Prepared schema statements', { count: statements.length, schemaBytes: SCHEMA.length })
 	for (const [index, stmt] of statements.entries()) {
-		try {
-			const snippet = stmt.length > 160 ? `${stmt.slice(0, 160)}…` : stmt
-			log.debug('Executing schema statement', { index, snippet })
-			await db.query(stmt)
-			log.debug('Schema statement OK', { index, stmt: stmt.slice(0, 60) })
-		} catch (e) {
-			log.error('Schema statement failed', { index, stmt, error: String(e) })
-			throw e
+		const snippet = stmt.length > 160 ? `${stmt.slice(0, 160)}…` : stmt
+		let lastError: unknown
+		for (let attempt = 0; attempt < MAX_RETRY_ATTEMPTS; attempt++) {
+			try {
+				log.debug('Executing schema statement', { index, attempt, snippet })
+				await db.query(stmt)
+				log.debug('Schema statement OK', { index, attempt, stmt: stmt.slice(0, 60) })
+				lastError = undefined
+				break
+			} catch (e) {
+				lastError = e
+				const retryable = isRetryableSchemaError(e)
+				const hasNextAttempt = attempt < MAX_RETRY_ATTEMPTS - 1
+				if (!retryable || !hasNextAttempt) {
+					log.error('Schema statement failed', {
+						index,
+						attempt,
+						retryable,
+						stmt,
+						error: String(e),
+					})
+					throw e
+				}
+				const delayMs = computeRetryDelayMs(attempt)
+				log.warning('Schema statement conflict; retrying', {
+					index,
+					attempt,
+					delayMs,
+					error: String(e),
+				})
+				await sleep(delayMs)
+			}
 		}
+		if (lastError) throw lastError
 	}
 	log.info('Schema ready')
 }

package/src/embedding/index.ts

@@ -16,7 +16,7 @@ export async function getEmbedding(
 	log.debug('getEmbedding()', { provider: config.provider, dimension: config.dimension })
 
 	switch (config.provider) {
-		case 'surreal':
+		case 'surrealml':
 			return { clause: 'fn::embed($content)' }
 
 		case 'openai-compatible': {
@@ -39,7 +39,7 @@ export async function getEmbedding(
 
 export function buildEmbeddingClause(config: EmbeddingProvider): string {
 	switch (config.provider) {
-		case 'surreal':
+		case 'surrealml':
 			return 'fn::embed($content)'
 		case 'openai-compatible':
 		case 'stub':

package/src/index.ts

@@ -1,13 +1,17 @@
 // src/index.ts — public API surface
-export { defineConfig, loadConfig } from './config.ts'
+export { defineConfig, loadConfig, resolveSyncConfig } from './config.ts'
 export type {
 	AuthConfig,
 	ConsolidationConfig,
 	EmbeddingProvider,
 	LLMConfig,
 	McpConfig,
+	ResolvedSyncAutoConfig,
+	ResolvedSyncConfig,
 	RetrievalConfig,
 	SuemoConfig,
 	SurrealTarget,
+	SyncAutoConfig,
 	SyncConfig,
+	SyncDirectionConfig,
 } from './config.ts'

package/src/mcp/dispatch.ts

@@ -1,28 +1,54 @@
 import type { Surreal } from 'surrealdb'
 import { z } from 'zod'
 import { consolidate } from '../cognitive/consolidate.ts'
-import { healthReport, vitals } from '../cognitive/health.ts'
+import { healthReport, suemoStats, vitals } from '../cognitive/health.ts'
 import type { SuemoConfig } from '../config.ts'
 import { goalList, goalResolve, goalSet } from '../goal.ts'
 import { getLogger } from '../logger.ts'
-import { episodeEnd, episodeStart } from '../memory/episode.ts'
+import { episodeEnd, episodeStart, getSessionContext, setSessionContext } from '../memory/episode.ts'
 import { query, recall, timeline, wander } from '../memory/read.ts'
-import { believe, invalidate, observe } from '../memory/write.ts'
+import { believe, capturePrompt, invalidate, observe, upsertByKey } from '../memory/write.ts'
 import { ObserveInputSchema, QueryInputSchema } from '../types.ts'
 
 const log = getLogger(['suemo', 'mcp', 'dispatch'])
 
+const MUTATING_TOOLS = new Set([
+	'observe',
+	'believe',
+	'invalidate',
+	'goal_set',
+	'goal_resolve',
+	'upsert_by_key',
+	'capture_prompt',
+	'session_context_set',
+])
+
+interface DispatchOptions {
+	onMutation?: (tool: string) => Promise<void>
+}
+
 export async function handleToolCall(
 	db: Surreal,
 	config: SuemoConfig,
 	method: string,
 	params: Record<string, unknown>,
+	opts: DispatchOptions = {},
 ): Promise<unknown> {
 	log.debug('Dispatching MCP tool call', { method, paramKeys: Object.keys(params) })
 
+	const maybeTriggerMutationSync = (): void => {
+		if (!MUTATING_TOOLS.has(method) || !opts.onMutation) return
+		void opts.onMutation(method).catch((error) => {
+			log.warning('Post-mutation hook failed', { method, error: String(error) })
+		})
+	}
+
 	switch (method) {
-		case 'observe':
-			return observe(db, ObserveInputSchema.parse(params), config)
+		case 'observe': {
+			const result = await observe(db, ObserveInputSchema.parse(params), config)
+			maybeTriggerMutationSync()
+			return result
+		}
 
 		case 'believe': {
 			const parsed = z
@@ -32,12 +58,15 @@ export async function handleToolCall(
 					confidence: z.number().optional(),
 				})
 				.parse(params)
-			return believe(db, parsed, config)
+			const result = await believe(db, parsed, config)
+			maybeTriggerMutationSync()
+			return result
 		}
 
 		case 'invalidate': {
 			const parsed = z.object({ nodeId: z.string(), reason: z.string().optional() }).parse(params)
 			await invalidate(db, parsed.nodeId, parsed.reason)
+			maybeTriggerMutationSync()
 			return { ok: true }
 		}
 
@@ -91,15 +120,18 @@ export async function handleToolCall(
 			const parsed = z
 				.object({ content: z.string(), scope: z.string().optional(), tags: z.array(z.string()).optional() })
 				.parse(params)
-			return goalSet(db, parsed.content, config, {
+			const result = await goalSet(db, parsed.content, config, {
 				...(parsed.scope ? { scope: parsed.scope } : {}),
 				tags: parsed.tags ?? [],
 			})
+			maybeTriggerMutationSync()
+			return result
 		}
 
 		case 'goal_resolve': {
 			const parsed = z.object({ goalId: z.string() }).parse(params)
 			await goalResolve(db, parsed.goalId)
+			maybeTriggerMutationSync()
 			return { ok: true }
 		}
 
@@ -114,6 +146,9 @@ export async function handleToolCall(
 		case 'health':
 			return healthReport(db)
 
+		case 'stats':
+			return suemoStats(db)
+
 		case 'vitals':
 			return vitals(db)
 
@@ -128,6 +163,69 @@ export async function handleToolCall(
 			})
 		}
 
+		case 'upsert_by_key': {
+			const parsed = z
+				.object({
+					topicKey: z.string(),
+					content: z.string(),
+					scope: z.string().optional(),
+					tags: z.array(z.string()).optional(),
+					confidence: z.number().optional(),
+					source: z.string().optional(),
+					sessionId: z.string().optional(),
+					kind: z.enum(['observation', 'belief', 'question', 'hypothesis', 'goal']).optional(),
+				})
+				.parse(params)
+			const result = await upsertByKey(db, config, parsed.topicKey, parsed.content, {
+				...(parsed.scope ? { scope: parsed.scope } : {}),
+				tags: parsed.tags ?? [],
+				...(parsed.source ? { source: parsed.source } : {}),
+				...(parsed.sessionId ? { sessionId: parsed.sessionId } : {}),
+				confidence: parsed.confidence ?? 1.0,
+				...(parsed.kind ? { kind: parsed.kind } : {}),
+			})
+			maybeTriggerMutationSync()
+			return result
+		}
+
+		case 'capture_prompt': {
+			const parsed = z
+				.object({
+					prompt: z.string(),
+					derivedIds: z.array(z.string()).optional(),
+					scope: z.string().optional(),
+					sessionId: z.string().optional(),
+				})
+				.parse(params)
+			const result = await capturePrompt(db, config, parsed.prompt, parsed.derivedIds ?? [], {
+				...(parsed.scope ? { scope: parsed.scope } : {}),
+				...(parsed.sessionId ? { sessionId: parsed.sessionId } : {}),
+			})
+			maybeTriggerMutationSync()
+			return result
+		}
+
+		case 'session_context_get': {
+			const parsed = z.object({ sessionId: z.string() }).parse(params)
+			return getSessionContext(db, parsed.sessionId)
+		}
+
+		case 'session_context_set': {
+			const parsed = z
+				.object({
+					sessionId: z.string(),
+					summary: z.string().optional(),
+					context: z.record(z.string(), z.unknown()).optional(),
+				})
+				.parse(params)
+			await setSessionContext(db, parsed.sessionId, {
+				...(parsed.summary !== undefined ? { summary: parsed.summary } : {}),
+				...(parsed.context !== undefined ? { context: parsed.context } : {}),
+			})
+			maybeTriggerMutationSync()
+			return { ok: true }
+		}
+
 		default:
 			throw new Error(`Unknown MCP tool: ${method}`)
 	}

package/src/mcp/server.ts

@@ -1,22 +1,142 @@
 // src/mcp/server.ts
 import { Elysia } from 'elysia'
-import type { SuemoConfig } from '../config.ts'
+import { resolveSyncConfig, type SuemoConfig } from '../config.ts'
 import { connect, disconnect } from '../db/client.ts'
 import { checkCompatibility, requireCompatibility } from '../db/preflight.ts'
 import { runSchema } from '../db/schema.ts'
 import { getLogger } from '../logger.ts'
+import { syncTo } from '../sync.ts'
 import { runStdioServer } from './stdio.ts'
 import { buildMcpRouter } from './tools.ts'
 
 const log = getLogger(['suemo', 'mcp'])
 
+interface AutoSyncOptions {
+	reason: 'timer' | 'write'
+	force?: boolean
+}
+
+function createAutoSyncRunner(
+	db: ReturnType<typeof connect> extends Promise<infer T> ? T : never,
+	config: SuemoConfig,
+): {
+	start: () => void
+	onWrite: (tool: string) => Promise<void>
+	stop: () => void
+} {
+	const resolvedSync = resolveSyncConfig(config)
+	if (!resolvedSync) {
+		return {
+			start: () => {},
+			onWrite: async () => {},
+			stop: () => {},
+		}
+	}
+
+	let timer: ReturnType<typeof setInterval> | null = null
+	let running = false
+	let queued = false
+	let lastRunAt = 0
+
+	const runAutoSync = async ({ reason, force = false }: AutoSyncOptions): Promise<void> => {
+		if (!resolvedSync.auto.enabled) return
+		if (reason === 'write' && !resolvedSync.auto.onWrite) return
+
+		const now = Date.now()
+		const minIntervalMs = resolvedSync.auto.minWriteIntervalSeconds * 1000
+		if (!force && reason === 'write' && lastRunAt > 0 && now - lastRunAt < minIntervalMs) {
+			return
+		}
+
+		if (running) {
+			queued = true
+			return
+		}
+
+		const target = resolvedSync.remotes[resolvedSync.auto.remote]
+		if (!target) {
+			log.warning('Auto-sync skipped: remote missing', { remote: resolvedSync.auto.remote, reason })
+			return
+		}
+
+		running = true
+		try {
+			const result = await syncTo(db, target, {
+				direction: resolvedSync.auto.direction,
+			})
+			lastRunAt = Date.now()
+			log.info('Auto-sync completed', {
+				reason,
+				remote: resolvedSync.auto.remote,
+				direction: resolvedSync.auto.direction,
+				pushed: result.pushed,
+				errors: result.errors,
+			})
+		} catch (error) {
+			log.warning('Auto-sync failed', { reason, error: String(error) })
+		} finally {
+			running = false
+			if (queued) {
+				queued = false
+				queueMicrotask(() => {
+					void runAutoSync({ reason: 'write', force: true })
+				})
+			}
+		}
+	}
+
+	const start = (): void => {
+		if (!resolvedSync.auto.enabled) return
+		if (timer) return
+		const intervalMs = resolvedSync.auto.intervalSeconds * 1000
+		timer = setInterval(() => {
+			void runAutoSync({ reason: 'timer' })
+		}, intervalMs)
+		log.info('Auto-sync timer started', {
+			intervalSeconds: resolvedSync.auto.intervalSeconds,
+			remote: resolvedSync.auto.remote,
+			direction: resolvedSync.auto.direction,
+		})
+	}
+
+	const stop = (): void => {
+		if (!timer) return
+		clearInterval(timer)
+		timer = null
+		log.info('Auto-sync timer stopped')
+	}
+
+	const onWrite = async (tool: string): Promise<void> => {
+		if (!resolvedSync.auto.enabled || !resolvedSync.auto.onWrite) return
+		log.debug('Auto-sync write trigger', { tool })
+		await runAutoSync({ reason: 'write' })
+	}
+
+	return { start, onWrite, stop }
+}
+
 export async function startMcpServer(config: SuemoConfig): Promise<void> {
 	const db = await connect(config.surreal)
 	await requireCompatibility(db)
 	await runSchema(db)
+	const autoSync = createAutoSyncRunner(db, config)
+	autoSync.start()
+
+	const shutdown = async (): Promise<void> => {
+		autoSync.stop()
+		await disconnect()
+		process.exit(0)
+	}
+
+	process.once('SIGINT', () => {
+		void shutdown()
+	})
+	process.once('SIGTERM', () => {
+		void shutdown()
+	})
 
 	new Elysia()
-		.use(buildMcpRouter(db, config))
+		.use(buildMcpRouter(db, config, { onMutation: autoSync.onWrite }))
 		.get('/health', () => ({ status: 'ok' }))
 		.listen({ port: config.mcp.port, hostname: config.mcp.host })
 
@@ -25,9 +145,11 @@ export async function startMcpServer(config: SuemoConfig): Promise<void> {
 
 export async function startMcpStdioServer(config: SuemoConfig): Promise<void> {
 	const db = await connect(config.surreal)
+	const autoSync = createAutoSyncRunner(db, config)
+	autoSync.start()
 	try {
 		const compat = await checkCompatibility(db, {
-			requireEmbedding: config.embedding.provider === 'surreal',
+			requireEmbedding: config.embedding.provider === 'surrealml',
 			context: 'mcp:stdio-startup',
 		})
 		if (!compat.ok) {
@@ -39,8 +161,9 @@ export async function startMcpStdioServer(config: SuemoConfig): Promise<void> {
 			process.exit(1)
 		}
 		await runSchema(db)
-		await runStdioServer(db, config)
+		await runStdioServer(db, config, { onMutation: autoSync.onWrite })
 	} finally {
+		autoSync.stop()
 		await disconnect()
 	}
 }