suemo 0.0.2 → 0.0.4

package/README.md

@@ -96,6 +96,14 @@ suemo serve
 # Listening on http://127.0.0.1:4242
 ```
 
+For development with automatic restart on file changes:
+
+```sh
+suemo serve --dev
+```
+
+`--dev` re-runs `suemo serve` under Bun watch mode and restarts MCP when source files change.
+
 ---
 
 ## CLI Reference
@@ -125,7 +133,8 @@ Commands:
   doctor embed          Diagnose fn::embed setup and print fix steps
   health                Memory health report
   health vitals         Last 10 consolidation runs + node counts
-  sync                  Push memories to a remote SurrealDB instance
+  health stats          Lightweight usage counters and timestamps
+	sync                  Sync memories with a remote SurrealDB instance
   export                Stream memories to JSONL on stdout
   import <file>         Import memories from a JSONL file
 ```
@@ -160,8 +169,8 @@ export default defineConfig({
 		},
 	},
 	embedding: {
-		provider: 'surreal', // fn::embed() — configured in SurrealDB
-		dimension: 1536,
+		provider: 'surrealml', // fn::embed() — configured in SurrealDB
+		dimension: 384,
 	},
 	consolidation: {
 		trigger: 'timer',
@@ -176,9 +185,56 @@ export default defineConfig({
 		weights: { vector: 0.5, bm25: 0.25, graph: 0.15, temporal: 0.1 },
 	},
 	mcp: { port: 4242, host: '127.0.0.1' },
+	sync: {
+		remotes: {
+			vps: {
+				url: process.env.SUEMO_SYNC_URL!,
+				namespace: process.env.SUEMO_SYNC_NS!,
+				database: process.env.SUEMO_SYNC_DB!,
+				auth: {
+					user: process.env.SUEMO_SYNC_USER!,
+					pass: process.env.SUEMO_SYNC_PASS!,
+				},
+			},
+		},
+		defaultRemote: 'vps',
+		auto: {
+			enabled: false,
+			intervalSeconds: 300,
+			direction: 'push',
+			remote: 'vps',
+			onWrite: false,
+			minWriteIntervalSeconds: 30,
+		},
+	},
 })
 ```
 
+### Sync config notes
+
+- `sync.remotes` supports multiple named remote instances.
+- `sync.defaultRemote` is used by `suemo sync` unless `--remote` is provided.
+- Legacy `sync.remote` (single target) is still supported for migration compatibility.
+- `sync.auto` powers background sync in `suemo serve` (HTTP and stdio):
+  - `enabled`: master switch
+  - `intervalSeconds`: timer cadence
+  - `direction`: `push | pull | both`
+  - `remote`: named target from `sync.remotes`
+  - `onWrite`: trigger sync after mutating MCP tools
+  - `minWriteIntervalSeconds`: throttle for write-triggered sync
+
+Manual sync examples:
+
+```sh
+suemo sync --direction both
+suemo sync --remote vps --direction pull
+suemo sync --remote vps --direction push --dry-run
+```
+
+Minimal local↔VPS smoke test guide:
+
+- `data/scenarios/sync-local-vps.md`
+
 Multiple agents on the same machine use separate config files that extend a shared base:
 
 ```ts
@@ -212,22 +268,28 @@ This prints your active target (`url`, `namespace`, `database`) and step-by-step
 
 ## MCP Tools
 
-| Tool            | Description                                                         |
-| --------------- | ------------------------------------------------------------------- |
-| `observe`       | Store an observation, belief, question, or hypothesis               |
-| `believe`       | Store a belief — auto-detects and invalidates contradicting beliefs |
-| `invalidate`    | Soft-delete a node by ID (sets `valid_until`)                       |
-| `query`         | Hybrid semantic search (vector + BM25 + graph)                      |
-| `recall`        | Fetch a node and its 1-hop neighbourhood; ticks FSRS                |
-| `wander`        | Spreading-activation walk through the graph                         |
-| `timeline`      | Chronological memory slice with optional date range                 |
-| `episode_start` | Begin a bounded session window                                      |
-| `episode_end`   | Close a session, optionally with a summary                          |
-| `goal_set`      | Create a goal node                                                  |
-| `goal_resolve`  | Mark a goal achieved                                                |
-| `goal_list`     | List active (or all) goals                                          |
-| `consolidate`   | Manually trigger NREM + REM consolidation                           |
-| `health`        | Graph health report                                                 |
+| Tool                  | Description                                                         |
+| --------------------- | ------------------------------------------------------------------- |
+| `observe`             | Store an observation, belief, question, or hypothesis               |
+| `believe`             | Store a belief — auto-detects and invalidates contradicting beliefs |
+| `invalidate`          | Soft-delete a node by ID (sets `valid_until`)                       |
+| `query`               | Hybrid semantic search (vector + BM25 + graph)                      |
+| `recall`              | Fetch a node and its 1-hop neighbourhood; ticks FSRS                |
+| `wander`              | Spreading-activation walk through the graph                         |
+| `timeline`            | Chronological memory slice with optional date range                 |
+| `episode_start`       | Begin a bounded session window                                      |
+| `episode_end`         | Close a session, optionally with a summary                          |
+| `goal_set`            | Create a goal node                                                  |
+| `goal_resolve`        | Mark a goal achieved                                                |
+| `goal_list`           | List active (or all) goals                                          |
+| `upsert_by_key`       | Upsert a memory node by stable topic key                            |
+| `capture_prompt`      | Capture raw prompt and link derived observations                    |
+| `session_context_get` | Fetch open episode summary/context by session ID                    |
+| `session_context_set` | Update open episode summary/context by session ID                   |
+| `consolidate`         | Manually trigger NREM + REM consolidation                           |
+| `health`              | Graph health report                                                 |
+| `vitals`              | Last 10 consolidation runs + grouped node counts                    |
+| `stats`               | Lightweight usage stats and write/query counters                    |
 
 Agents never supply temporal fields (`valid_from`, `valid_until`). These are system-managed.
 
@@ -258,6 +320,25 @@ The CLI and MCP server are both thin shells. All logic lives in the domain layer
 
 ---
 
+## Giant end-to-end scenario (all tools / fields)
+
+For full-system stress testing (CLI + MCP + consolidation + relation kinds), use:
+
+- `data/scenarios/giant-scenario.md` — walkthrough + validation queries
+- `data/scenarios/run-giant-cli.sh` — comprehensive CLI flow
+- `data/scenarios/run-giant-mcp.mjs` — comprehensive stdio MCP flow
+
+Example:
+
+```sh
+./data/scenarios/run-giant-cli.sh ~/.suemo/suemo.ts giant-cli-main
+bun data/scenarios/run-giant-mcp.mjs --config ~/.suemo/suemo.ts --scope giant-mcp-main
+```
+
+These scenarios intentionally exercise all memory kinds and all relation kinds, and produce enough incident-like data to observe NREM/REM behavior.
+
+---
+
 ## Stack
 
 - **Runtime** — [Bun](https://bun.sh)

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "suemo",
-	"version": "0.0.2",
+	"version": "0.0.4",
 	"description": "Persistent semantic memory for AI agents — backed by SurrealDB.",
 	"author": {
 		"name": "Umar Alfarouk",

package/src/cli/commands/export-import.ts

@@ -84,7 +84,32 @@ export const importCmd = app.sub('import')
 						await db.query('INSERT IGNORE INTO memory $row', { row })
 						imported++
 					} else if (type === 'relation') {
-						await db.query('INSERT IGNORE INTO relates_to $row', { row })
+						const inId = typeof row['in'] === 'string' ? row['in'] : undefined
+						const outId = typeof row['out'] === 'string' ? row['out'] : undefined
+						const kind = typeof row['kind'] === 'string' ? row['kind'] : undefined
+						const strength = typeof row['strength'] === 'number' ? row['strength'] : undefined
+
+						if (!inId || !outId || !kind || strength === undefined) {
+							skipped++
+							continue
+						}
+
+						await db.query(
+							`
+							LET $inRec = type::record($in);
+							LET $outRec = type::record($out);
+							RELATE $inRec->relates_to->$outRec CONTENT {
+							  kind: $kind,
+							  strength: $strength
+							};
+						`,
+							{
+								in: inId,
+								out: outId,
+								kind,
+								strength,
+							},
+						)
 						imported++
 					} else {
 						skipped++

package/src/cli/commands/health.ts

@@ -1,5 +1,5 @@
 import type { Surreal } from 'surrealdb'
-import { healthReport, vitals } from '../../cognitive/health.ts'
+import { healthReport, suemoStats, vitals } from '../../cognitive/health.ts'
 import { loadConfig } from '../../config.ts'
 import { connect, disconnect } from '../../db/client.ts'
 import { getLogger } from '../../logger.ts'
@@ -42,9 +42,26 @@ const vitalsCmd = health.sub('vitals')
 		}
 	})
 
+const statsCmd = health.sub('stats')
+	.meta({ description: 'Lightweight usage stats' })
+	.run(async ({ flags }) => {
+		await initCliCommand('health stats', { debug: flags.debug, config: flags.config })
+		log.debug('Running health stats command')
+		const config = await loadConfig(process.cwd(), flags.config)
+		let db: Surreal | undefined
+		try {
+			db = await connect(config.surreal)
+			const s = await suemoStats(db)
+			console.log(JSON.stringify(s, null, 2))
+		} finally {
+			if (db) await disconnect()
+		}
+	})
+
 export const healthCmd = health
 	.command(reportCmd)
 	.command(vitalsCmd)
+	.command(statsCmd)
 	// Default: run the report when just `suemo health` is called
 	.run(async ({ flags }) => {
 		await initCliCommand('health', { debug: flags.debug, config: flags.config })

package/src/cli/commands/observe.ts

@@ -44,6 +44,7 @@ export const observeCmd = app.sub('observe')
 				scope: flags.scope,
 				confidence: flags.confidence,
 				source: flags.source,
+				sessionId: flags.session,
 			}, config)
 			console.log(JSON.stringify({ id: node.id, kind: node.kind, valid_from: node.valid_from }, null, 2))
 		} finally {

package/src/cli/commands/serve.ts

@@ -1,20 +1,92 @@
-import { loadConfig } from '../../config.ts'
+import { loadConfig, resolveSyncConfig } from '../../config.ts'
 import { getLogger } from '../../logger.ts'
 import { startMcpServer, startMcpStdioServer } from '../../mcp/server.ts'
 import { app, initCliCommand } from '../shared.ts'
 
 const log = getLogger(['suemo', 'cli', 'serve'])
 
+function printDevRestartBanner(): void {
+	if (process.env.SUEMO_DEV_WATCH !== '1') return
+	const now = new Date().toISOString()
+	console.log(`\n[suemo:dev] MCP restarted (${now})\n`)
+}
+
+async function runServeDevMode(): Promise<never> {
+	const scriptPath = process.argv[1] ?? 'src/cli/index.ts'
+	const forwardedArgs = process.argv.slice(2).filter((arg) => arg !== '--dev')
+	const bunExecutable = process.execPath.includes('bun') ? process.execPath : 'bun'
+	const cmd = [bunExecutable, '--watch', scriptPath, ...forwardedArgs]
+
+	log.info('Starting serve dev mode (bun --watch)', {
+		scriptPath,
+		forwardedArgs,
+	})
+
+	const child = Bun.spawn({
+		cmd,
+		env: { ...process.env, SUEMO_DEV_WATCH: '1' },
+		stdin: 'inherit',
+		stdout: 'inherit',
+		stderr: 'inherit',
+	})
+
+	const shutdown = (signal: NodeJS.Signals): void => {
+		log.info('Stopping dev watcher', { signal })
+		try {
+			child.kill(signal)
+		} catch {
+			// noop
+		}
+	}
+
+	process.once('SIGINT', () => {
+		shutdown('SIGINT')
+	})
+	process.once('SIGTERM', () => {
+		shutdown('SIGTERM')
+	})
+
+	const exitCode = await child.exited
+	process.exit(exitCode)
+}
+
+async function maybeDelayDevStartup(): Promise<void> {
+	if (process.env.SUEMO_DEV_WATCH !== '1') return
+	const rawDelay = process.env.SUEMO_DEV_RESTART_DELAY_MS ?? '250'
+	const parsed = Number(rawDelay)
+	const delayMs = Number.isFinite(parsed) && parsed > 0 ? parsed : 250
+	if (delayMs > 0) {
+		log.debug('Delaying startup for dev restart stability', { delayMs })
+		await Bun.sleep(delayMs)
+	}
+}
+
 export const serveCmd = app.sub('serve')
 	.meta({ description: 'Start the MCP server (HTTP or stdio)' })
 	.flags({
 		port: { type: 'number', short: 'p', description: 'Port to listen on (overrides config)' },
 		host: { type: 'string', description: 'Host to bind to (overrides config)' },
 		stdio: { type: 'boolean', description: 'Use stdio transport instead of HTTP' },
+		dev: { type: 'boolean', description: 'Restart MCP server on code changes (bun --watch)' },
 	})
 	.run(async ({ flags }) => {
+		printDevRestartBanner()
+		await maybeDelayDevStartup()
 		await initCliCommand('serve', { debug: flags.debug, config: flags.config })
+		if (flags.dev) {
+			await runServeDevMode()
+		}
 		const config = await loadConfig(process.cwd(), flags.config)
+		const sync = resolveSyncConfig(config)
+		if (sync?.auto.enabled) {
+			log.info('Auto-sync enabled', {
+				remote: sync.auto.remote,
+				direction: sync.auto.direction,
+				intervalSeconds: sync.auto.intervalSeconds,
+				onWrite: sync.auto.onWrite,
+				minWriteIntervalSeconds: sync.auto.minWriteIntervalSeconds,
+			})
+		}
 		if (flags.stdio) {
 			log.debug('Starting MCP stdio transport')
 			await startMcpStdioServer(config)

package/src/cli/commands/sync.ts

@@ -1,4 +1,4 @@
-import { loadConfig } from '../../config.ts'
+import { loadConfig, resolveSyncConfig, type SurrealTarget } from '../../config.ts'
 import { connect, disconnect } from '../../db/client.ts'
 import { getLogger } from '../../logger.ts'
 import { syncTo } from '../../sync.ts'
@@ -7,24 +7,49 @@ import { app, initCliCommand } from '../shared.ts'
 const log = getLogger(['suemo', 'cli', 'sync'])
 
 export const syncCmd = app.sub('sync')
-	.meta({ description: 'Push memories to remote SurrealDB (append-only)' })
+	.meta({ description: 'Sync memories with remote SurrealDB (push/pull/both)' })
 	.flags({
 		'dry-run': { type: 'boolean', description: 'Show what would be pushed without writing', default: false },
+		direction: { type: 'string', description: 'Sync direction: push | pull | both', default: 'push' },
+		remote: { type: 'string', description: 'Named remote from sync.remotes (defaults to sync.defaultRemote)' },
 	})
 	.run(async ({ flags }) => {
 		await initCliCommand('sync', { debug: flags.debug, config: flags.config })
 		const config = await loadConfig(process.cwd(), flags.config)
-		if (!config.sync) {
-			console.error('No sync.remote configured in suemo config.')
+		const sync = resolveSyncConfig(config)
+		if (!sync) {
+			console.error('No sync remotes configured. Set sync.remotes (or legacy sync.remote) in suemo config.')
 			process.exit(1)
 		}
+
+		const selectedRemoteName = flags.remote ?? sync.defaultRemote
+		const remote: SurrealTarget | undefined = sync.remotes[selectedRemoteName]
+		if (!remote) {
+			console.error(
+				`Unknown sync remote "${selectedRemoteName}". Available: ${Object.keys(sync.remotes).join(', ')}`,
+			)
+			process.exit(1)
+		}
+
 		log.debug('Running sync command', {
 			dryRun: flags['dry-run'],
-			target: `${config.sync.remote.url}/${config.sync.remote.namespace}/${config.sync.remote.database}`,
+			direction: flags.direction,
+			remote: selectedRemoteName,
+			target: `${remote.url}/${remote.namespace}/${remote.database}`,
 		})
+
+		const direction = flags.direction as 'push' | 'pull' | 'both'
+		if (!['push', 'pull', 'both'].includes(direction)) {
+			console.error(`Invalid direction "${flags.direction}". Use: push, pull, or both`)
+			process.exit(1)
+		}
+
 		const db = await connect(config.surreal)
 		try {
-			const result = await syncTo(db, config.sync.remote, { dryRun: flags['dry-run'] })
+			const result = await syncTo(db, remote, {
+				dryRun: flags['dry-run'],
+				direction,
+			})
 			console.log(JSON.stringify(result, null, 2))
 		} finally {
 			await disconnect()

package/src/cli/commands/wander.ts

@@ -33,6 +33,10 @@ export const wanderCmd = app.sub('wander')
 			if (flags.json) {
 				console.log(JSON.stringify(nodes, null, 2))
 			} else {
+				if (nodes.length === 0) {
+					console.log('No memories found for this wander query.')
+					return
+				}
 				for (const n of nodes) {
 					console.log(`[${n.kind}] ${n.id}  salience=${n.salience.toFixed(2)}`)
 					console.log(`  ${n.content.slice(0, 120)}`)

package/src/cognitive/consolidate.ts

@@ -77,22 +77,16 @@ async function runNREM(
 		// Find similar unassigned nodes using DB-side cosine
 		const similarResult = await db.query<[{ id: string; score: number }[]]>(
 			`
-      LET $cand = (
-        SELECT id, embedding
+      SELECT id, score
+      FROM (
+        SELECT id, vector::similarity::cosine(embedding, $emb) AS score
         FROM memory
         WHERE consolidated = false
           AND id != $self
           AND (valid_until = NONE OR valid_until > time::now())
-          AND embedding <|10, 20|> $emb
-      );
-
-      SELECT id, score
-      FROM (
-        SELECT id, vector::similarity::cosine(embedding, $emb) AS score
-        FROM $cand
       )
       ORDER BY score DESC
-      LIMIT 10
+      LIMIT 500
     `,
 			{ emb: node.embedding, self: node.id },
 		)
@@ -238,13 +232,10 @@ async function runREM(
 		const candidates = await db.query<[MemoryNode[]]>(
 			`
       SELECT * FROM memory
-      WHERE id IN (
-        SELECT VALUE id FROM memory
-        WHERE id != $self
-          AND consolidated = true
-          AND (valid_until = NONE OR valid_until > time::now())
-          AND embedding <|10, 40|> $emb
-      )
+      WHERE id != $self
+        AND consolidated = true
+        AND (valid_until = NONE OR valid_until > time::now())
+      ORDER BY vector::similarity::cosine(embedding, $emb) DESC
       LIMIT 10
     `,
 			{ self: node.id, emb: node.embedding },

package/src/cognitive/contradiction.ts

@@ -21,21 +21,15 @@ export async function detectContradiction(
 
 	log.debug('detectContradiction()', { nodeId: newNode.id })
 
-	const candidates = await db.query<[{ id: string; score: number }[]]>(
+	const candidates = await db.query<unknown[]>(
 		`
-    LET $cand = (
-      SELECT id, embedding
+    SELECT id, score
+    FROM (
+      SELECT id, vector::similarity::cosine(embedding, $emb) AS score
       FROM memory
       WHERE kind = 'belief'
         AND id != $self
         AND (valid_until = NONE OR valid_until > time::now())
-        AND embedding <|3, 20|> $emb
-    );
-
-    SELECT id, score
-    FROM (
-      SELECT id, vector::similarity::cosine(embedding, $emb) AS score
-      FROM $cand
     )
     ORDER BY score DESC
     LIMIT 3
@@ -43,7 +37,7 @@ export async function detectContradiction(
 		{ emb: newNode.embedding, self: newNode.id },
 	)
 
-	const top = candidates[0]
+	const top = candidates.at(-1) as { id: string; score: number }[] | undefined
 	if (!top || top.length === 0) return null
 
 	const best = top[0]!

package/src/cognitive/health.ts

@@ -1,7 +1,7 @@
 import type { Surreal } from 'surrealdb'
 import { checkCompatibility } from '../db/preflight.ts'
 import { getLogger } from '../logger.ts'
-import type { ConsolidationRun, HealthReport } from '../types.ts'
+import type { ConsolidationRun, HealthReport, SuemoStats } from '../types.ts'
 
 const log = getLogger(['suemo', 'cognitive', 'health'])
 
@@ -121,3 +121,63 @@ export async function vitals(db: Surreal): Promise<{
 		nodesByScope,
 	}
 }
+
+export async function suemoStats(db: Surreal): Promise<SuemoStats> {
+	log.info('suemoStats()')
+
+	const [totalR, activeR, kindR, relR, runR, statsR] = await Promise.all([
+		db.query<[{ count: number }[]]>('SELECT count() AS count FROM memory GROUP ALL'),
+		db.query<[{ count: number }[]]>(
+			'SELECT count() AS count FROM memory WHERE valid_until = NONE OR valid_until > time::now() GROUP ALL',
+		),
+		db.query<[{ kind: string; count: number }[]]>('SELECT kind, count() AS count FROM memory GROUP BY kind'),
+		db.query<[{ count: number }[]]>('SELECT count() AS count FROM relates_to GROUP ALL'),
+		db.query<[{ count: number }[]]>('SELECT count() AS count FROM consolidation_run GROUP ALL'),
+		db.query<[
+			{ total_writes: number; total_queries: number; last_write: string | null; last_query: string | null }[],
+		]>(
+			'SELECT total_writes, total_queries, last_write, last_query FROM suemo_stats:default LIMIT 1',
+		),
+	])
+
+	const byKind: Record<string, number> = {}
+	for (const r of kindR[0] ?? []) byKind[r.kind] = r.count
+
+	const s = statsR[0]?.[0]
+
+	return {
+		totalNodes: totalR[0]?.[0]?.count ?? 0,
+		activeNodes: activeR[0]?.[0]?.count ?? 0,
+		nodesByKind: byKind,
+		relations: relR[0]?.[0]?.count ?? 0,
+		consolidationRuns: runR[0]?.[0]?.count ?? 0,
+		lastWrite: s?.last_write ?? null,
+		lastQuery: s?.last_query ?? null,
+		totalWrites: s?.total_writes ?? 0,
+		totalQueries: s?.total_queries ?? 0,
+	}
+}
+
+export async function incrementWriteStats(db: Surreal): Promise<void> {
+	await db.query(
+		`
+	  UPSERT suemo_stats:default SET
+	    ns_db        = $nsDb,
+	    total_writes = IF total_writes = NONE THEN 1 ELSE total_writes + 1 END,
+	    last_write   = time::now()
+	  `,
+		{ nsDb: 'default' },
+	)
+}
+
+export async function incrementQueryStats(db: Surreal): Promise<void> {
+	await db.query(
+		`
+	  UPSERT suemo_stats:default SET
+	    ns_db         = $nsDb,
+	    total_queries = IF total_queries = NONE THEN 1 ELSE total_queries + 1 END,
+	    last_query    = time::now()
+	  `,
+		{ nsDb: 'default' },
+	)
+}

package/src/config.template.ts

@@ -33,4 +33,26 @@ export default defineConfig({
 		port: Number(process.env.SUEMO_PORT) || 4242,
 		host: '127.0.0.1',
 	},
+	sync: {
+		remotes: {
+			vps: {
+				url: process.env.SUEMO_SYNC_URL ?? process.env.SUEMO_URL ?? 'ws://localhost:8000',
+				namespace: process.env.SUEMO_SYNC_NS ?? process.env.SUEMO_NS ?? 'suemo',
+				database: process.env.SUEMO_SYNC_DB ?? process.env.SUEMO_DB ?? 'suemo',
+				auth: {
+					user: process.env.SUEMO_SYNC_USER ?? process.env.SUEMO_USER ?? 'root',
+					pass: process.env.SUEMO_SYNC_PASS ?? process.env.SUEMO_PASS ?? 'pass',
+				},
+			},
+		},
+		defaultRemote: 'vps',
+		auto: {
+			enabled: false,
+			intervalSeconds: 300,
+			direction: 'push',
+			remote: 'vps',
+			onWrite: false,
+			minWriteIntervalSeconds: 30,
+		},
+	},
 })