suemo 0.0.2 → 0.0.3

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,6 +145,8 @@ 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',
@@ -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()
 	}
 }

package/src/mcp/stdio.ts

@@ -22,6 +22,10 @@ interface McpToolDefinition {
 const SUPPORTED_PROTOCOL_VERSIONS = new Set(['2024-11-05', '2025-03-26'])
 const DEFAULT_PROTOCOL_VERSION = '2024-11-05'
 
+interface StdioServerOptions {
+	onMutation?: (tool: string) => Promise<void>
+}
+
 const MCP_TOOLS: McpToolDefinition[] = [
 	{
 		name: 'observe',
@@ -35,6 +39,7 @@ const MCP_TOOLS: McpToolDefinition[] = [
 				scope: { type: 'string' },
 				source: { type: 'string' },
 				confidence: { type: 'number' },
+				sessionId: { type: 'string' },
 			},
 			required: ['content'],
 		},
@@ -178,6 +183,11 @@ const MCP_TOOLS: McpToolDefinition[] = [
 		description: 'Get health vitals summary',
 		inputSchema: { type: 'object', properties: {} },
 	},
+	{
+		name: 'stats',
+		description: 'Get lightweight usage stats summary',
+		inputSchema: { type: 'object', properties: {} },
+	},
 	{
 		name: 'consolidate',
 		description: 'Trigger memory consolidation',
@@ -186,9 +196,69 @@ const MCP_TOOLS: McpToolDefinition[] = [
 			properties: { nremOnly: { type: 'boolean' } },
 		},
 	},
+	{
+		name: 'upsert_by_key',
+		description: 'Upsert a memory node by topic key',
+		inputSchema: {
+			type: 'object',
+			properties: {
+				topicKey: { type: 'string' },
+				content: { type: 'string' },
+				scope: { type: 'string' },
+				tags: { type: 'array', items: { type: 'string' } },
+				source: { type: 'string' },
+				confidence: { type: 'number' },
+				sessionId: { type: 'string' },
+				kind: { type: 'string', enum: ['observation', 'belief', 'question', 'hypothesis', 'goal'] },
+			},
+			required: ['topicKey', 'content'],
+		},
+	},
+	{
+		name: 'capture_prompt',
+		description: 'Capture a raw prompt and link derived observations',
+		inputSchema: {
+			type: 'object',
+			properties: {
+				prompt: { type: 'string' },
+				derivedIds: { type: 'array', items: { type: 'string' } },
+				scope: { type: 'string' },
+				sessionId: { type: 'string' },
+			},
+			required: ['prompt'],
+		},
+	},
+	{
+		name: 'session_context_get',
+		description: 'Get open session context by session ID',
+		inputSchema: {
+			type: 'object',
+			properties: {
+				sessionId: { type: 'string' },
+			},
+			required: ['sessionId'],
+		},
+	},
+	{
+		name: 'session_context_set',
+		description: 'Update summary/context for open session by session ID',
+		inputSchema: {
+			type: 'object',
+			properties: {
+				sessionId: { type: 'string' },
+				summary: { type: 'string' },
+				context: { type: 'object' },
+			},
+			required: ['sessionId'],
+		},
+	},
 ]
 
-export async function runStdioServer(db: Surreal, config: SuemoConfig): Promise<void> {
+export async function runStdioServer(
+	db: Surreal,
+	config: SuemoConfig,
+	opts: StdioServerOptions = {},
+): Promise<void> {
 	log.info('MCP stdio transport started')
 
 	const rl = createInterface({ input: process.stdin, terminal: false })
@@ -227,7 +297,7 @@ export async function runStdioServer(db: Surreal, config: SuemoConfig): Promise<
 			log.debug('Received stdio MCP request', { method })
 
 			try {
-				const result = await handleRpcMethod(db, config, method, params)
+				const result = await handleRpcMethod(db, config, method, params, opts)
 				if (id === null) continue
 				writeJsonRpc({ jsonrpc: '2.0', id, result })
 			} catch (error) {
@@ -251,6 +321,7 @@ async function handleRpcMethod(
 	config: SuemoConfig,
 	method: string,
 	params: Record<string, unknown>,
+	opts: StdioServerOptions,
 ): Promise<unknown> {
 	if (method === 'initialize' || method === 'initiaize') {
 		const requestedVersion = typeof params.protocolVersion === 'string'
@@ -294,7 +365,7 @@ async function handleRpcMethod(
 			? params.arguments as Record<string, unknown>
 			: {}
 
-		const toolResult = await handleToolCall(db, config, name, toolArgs)
+		const toolResult = await handleToolCall(db, config, name, toolArgs, opts)
 		return {
 			content: [{ type: 'text', text: JSON.stringify(toolResult, null, 2) }],
 			structuredContent: toolResult,
@@ -303,7 +374,7 @@ async function handleRpcMethod(
 
 	// Backward-compatible direct tool method invocation.
 	if (MCP_TOOLS.some((t) => t.name === method)) {
-		return handleToolCall(db, config, method, params)
+		return handleToolCall(db, config, method, params, opts)
 	}
 
 	throw new Error(`Unknown MCP method: ${method}`)

package/src/mcp/tools.ts

@@ -6,7 +6,11 @@ import type { Surreal } from 'surrealdb'
 import type { SuemoConfig } from '../config.ts'
 import { handleToolCall } from './dispatch.ts'
 
-export function buildMcpRouter(db: Surreal, config: SuemoConfig) {
+interface McpRouterOptions {
+	onMutation?: (tool: string) => Promise<void>
+}
+
+export function buildMcpRouter(db: Surreal, config: SuemoConfig, opts: McpRouterOptions = {}) {
 	// Elysia plugin: route-level transport, shared dispatch handles behavior.
 	return (app: Elysia) =>
 		app
@@ -14,6 +18,6 @@ export function buildMcpRouter(db: Surreal, config: SuemoConfig) {
 				const payload = body && typeof body === 'object' && !Array.isArray(body)
 					? body as Record<string, unknown>
 					: {}
-				return handleToolCall(db, config, params.tool, payload)
+				return handleToolCall(db, config, params.tool, payload, opts)
 			})
 }

package/src/memory/episode.ts

@@ -15,6 +15,7 @@ export async function episodeStart(
       session_id: $sessionId,
       ended_at:   NONE,
       summary:    NONE,
+      context:    NONE,
       memory_ids: []
     }
   `,
@@ -64,3 +65,94 @@ export async function attachToEpisode(
 		{ sessionId, memoryId },
 	)
 }
+
+export interface SessionContext {
+	summary?: string
+	context?: Record<string, unknown>
+	memoryCount: number
+	startedAt: string
+}
+
+export async function getSessionContext(
+	db: Surreal,
+	sessionId: string,
+): Promise<SessionContext | null> {
+	const result = await db.query<[
+		{
+			session_id: string
+			summary: string | null
+			context: Record<string, unknown> | null
+			memory_ids: string[]
+			started_at: string
+		}[],
+	]>(
+		`
+    SELECT session_id, summary, context, memory_ids, started_at
+    FROM episode
+    WHERE session_id = $sessionId AND ended_at = NONE
+    LIMIT 1
+  `,
+		{ sessionId },
+	)
+
+	const ep = result[0]?.[0]
+	if (!ep) return null
+
+	const out: SessionContext = {
+		memoryCount: ep.memory_ids.length,
+		startedAt: ep.started_at,
+	}
+	if (ep.summary !== null) out.summary = ep.summary
+	if (ep.context !== null) out.context = ep.context
+	return out
+}
+
+export async function setSessionContext(
+	db: Surreal,
+	sessionId: string,
+	patch: { summary?: string; context?: Record<string, unknown> },
+): Promise<void> {
+	log.info('setSessionContext()', { sessionId })
+
+	if (patch.summary === undefined && patch.context === undefined) return
+
+	if (patch.summary !== undefined && patch.context !== undefined) {
+		const result = await db.query<[Episode[]]>(
+			`
+      UPDATE episode
+      SET summary = $summary,
+          context = $context
+      WHERE session_id = $sessionId AND ended_at = NONE
+      RETURN AFTER
+    `,
+			{ sessionId, summary: patch.summary, context: patch.context },
+		)
+		if (!result[0]?.[0]) throw new Error(`No open episode found for session: ${sessionId}`)
+		return
+	}
+
+	if (patch.summary !== undefined) {
+		const result = await db.query<[Episode[]]>(
+			`
+      UPDATE episode
+      SET summary = $summary
+      WHERE session_id = $sessionId AND ended_at = NONE
+      RETURN AFTER
+    `,
+			{ sessionId, summary: patch.summary },
+		)
+		if (!result[0]?.[0]) throw new Error(`No open episode found for session: ${sessionId}`)
+		return
+	}
+
+	const result = await db.query<[Episode[]]>(
+		`
+    UPDATE episode
+    SET context = $context
+    WHERE session_id = $sessionId AND ended_at = NONE
+    RETURN AFTER
+  `,
+		{ sessionId, context: patch.context },
+	)
+	if (!result[0]?.[0]) throw new Error(`No open episode found for session: ${sessionId}`)
+}

package/src/memory/read.ts

@@ -1,4 +1,5 @@
 import type { Surreal } from 'surrealdb'
+import { incrementQueryStats } from '../cognitive/health.ts'
 import type { SuemoConfig } from '../config.ts'
 import { getEmbedding } from '../embedding/index.ts'
 import { getLogger } from '../logger.ts'
@@ -167,6 +168,7 @@ export async function query(
 		})
 
 	log.info('query() returned', { count: merged.length })
+	await incrementQueryStats(db)
 	return merged
 }