suemo 0.0.4 → 0.0.6

package/README.md

@@ -34,11 +34,14 @@ suemo gives AI agents a memory that survives across sessions, models, and runtim
 SurrealDB must be started with SurrealKV and a retention window:
 
 ```sh
-SURREAL_DATASTORE_RETENTION=90d surreal start \
+SURREAL_DATASTORE_VERSIONED=true SURREAL_DATASTORE_RETENTION=90d surreal start \
   --bind 0.0.0.0:8000 \
-  surrealkv:///path/to/data
+  --allow-funcs "fn::*" \
+  -- surrealkv:///path/to/data
 ```
 
+For suemo, the critical capability is allowing custom functions (`fn::embed`) via `--allow-funcs "fn::*"`.
+
 An embedding model must be configured in SurrealDB for `fn::embed()` to work.
 
 ---
@@ -64,6 +67,19 @@ bun run src/cli/index.ts init config
 
 This writes `~/.suemo/suemo.ts`. Edit it with your SurrealDB URL, credentials, and LLM endpoint.
 
+Set project scope discovery in config (recommended):
+
+```ts
+export default defineConfig({
+	main: {
+		projectDir: '.ua',
+	},
+	// ...
+})
+```
+
+With this, suemo resolves default scope from nearest `.ua/suemo.json` (auto-created if missing).
+
 **2. Apply schema**
 
 Apply schema after you set/edit namespace/database:
@@ -106,6 +122,30 @@ suemo serve --dev
 
 ---
 
+## OpenCode setup (only integration target)
+
+Print copy-paste setup snippets:
+
+```sh
+suemo init opencode
+```
+
+This prints:
+
+- MCP config snippet (`command: suemo`, `args: ["serve", "--stdio", ...]`)
+- minimal AGENTS.md guidance snippet
+
+To fetch the latest skill docs directly from your local checkout:
+
+```sh
+suemo skill
+suemo skill core-workflow
+```
+
+No files are auto-written by this command.
+
+---
+
 ## CLI Reference
 
 ```
@@ -119,6 +159,7 @@ Commands:
   init                  Show init subcommands and usage guidance
   init config           Create/update ~/.suemo/suemo.ts
   init schema           Apply DB schema from current config (with confirm)
+  skill                 Print suemo skill docs (or specific reference)
   serve                 Start the MCP server (HTTP or stdio)
   observe <content>     Store an observation
   believe <content>     Store a belief (triggers contradiction detection)
@@ -277,12 +318,16 @@ This prints your active target (`url`, `namespace`, `database`) and step-by-step
 | `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                 |
+| `context`             | Recover recent session context for current/default scope            |
 | `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                            |
+| `update`              | Update an existing memory node by ID (re-embeds if content changed) |
+| `suggest_topic_key`   | Suggest deterministic canonical topic key from free text            |
+| `skill`               | Return current suemo skill docs or one named reference              |
 | `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                   |
@@ -293,6 +338,13 @@ This prints your active target (`url`, `namespace`, `database`) and step-by-step
 
 Agents never supply temporal fields (`valid_from`, `valid_until`). These are system-managed.
 
+### Scope and longevity notes
+
+- Default inferred project scope now uses nearest `<projectDir>/suemo.json` with `main.projectDir` defaulting to `.ua`.
+- Semantic operations are scope-aware (dedup, contradiction detection, upsert-by-key, consolidation).
+- Retention probe is fail-closed on unexpected probe errors.
+- Episode records are included in sync and export/import flows.
+
 ---
 
 ## Architecture

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "suemo",
-	"version": "0.0.4",
+	"version": "0.0.6",
 	"description": "Persistent semantic memory for AI agents — backed by SurrealDB.",
 	"author": {
 		"name": "Umar Alfarouk",
@@ -37,7 +37,10 @@
 	"scripts": {
 		"dev": "bun run src/cli/index.ts",
 		"start": "bun run src/cli/index.ts",
-		"check": "bun tsc --noEmit"
+		"ssot:check": "bun run scripts/ssot.ts check",
+		"ssot:sync": "bun run scripts/ssot.ts sync",
+		"check": "bun tsc --noEmit && bun run ssot:check",
+		"sync": "bun run ssot:sync"
 	},
 	"dependencies": {
 		"@crustjs/core": "^0.0.15",

package/src/cli/commands/believe.ts

@@ -2,7 +2,7 @@ import { loadConfig } from '../../config.ts'
 import { connect, disconnect } from '../../db/client.ts'
 import { getLogger } from '../../logger.ts'
 import { believe } from '../../memory/write.ts'
-import { app, initCliCommand } from '../shared.ts'
+import { app, initCliCommand, printCliJson, resolveOutputModeOrExit, resolveScopeLabel } from '../shared.ts'
 
 const log = getLogger(['suemo', 'cli', 'believe'])
 
@@ -12,25 +12,42 @@ export const believeCmd = app.sub('believe')
 	.flags({
 		scope: { type: 'string', short: 's', description: 'Scope label' },
 		confidence: { type: 'number', description: 'Confidence 0.0–1.0', default: 1.0 },
+		json: { type: 'boolean', description: 'Output JSON result' },
+		pretty: { type: 'boolean', description: 'Human-readable output (default)' },
 	})
 	.run(async ({ args, flags }) => {
-		await initCliCommand('believe', { debug: flags.debug, config: flags.config })
+		const outputMode = resolveOutputModeOrExit(flags)
+		await initCliCommand('believe', {
+			debug: flags.debug,
+			config: flags.config,
+			json: outputMode === 'json',
+			quiet: flags.quiet,
+		})
 		const config = await loadConfig(process.cwd(), flags.config)
+		const resolvedScope = resolveScopeLabel(flags.scope, config)
+		log.debug('Resolved believe scope', { scope: resolvedScope, explicit: flags.scope ?? null })
 		const db = await connect(config.surreal)
 		try {
 			log.debug('Running believe command', {
-				hasScope: Boolean(flags.scope),
+				hasScope: Boolean(resolvedScope),
+				scope: resolvedScope,
 				confidence: flags.confidence,
 				contentLength: args.content.length,
 			})
 			const { node, contradicted } = await believe(db, {
 				content: args.content,
-				scope: flags.scope,
+				scope: resolvedScope,
 				confidence: flags.confidence,
 			}, config)
-			const out: Record<string, unknown> = { id: node.id, valid_from: node.valid_from }
-			if (contradicted) out.contradicted = contradicted.id
-			console.log(JSON.stringify(out, null, 2))
+			if (outputMode === 'json') {
+				const out: Record<string, unknown> = { id: node.id, valid_from: node.valid_from }
+				if (contradicted) out.contradicted = contradicted.id
+				printCliJson(out, flags)
+			} else {
+				console.log(`Stored belief memory: ${node.id}`)
+				console.log(`  valid_from: ${node.valid_from}`)
+				if (contradicted) console.log(`  contradicted: ${contradicted.id}`)
+			}
 		} finally {
 			await disconnect()
 		}

package/src/cli/commands/consolidate.ts

@@ -2,7 +2,7 @@ import { consolidate } from '../../cognitive/consolidate.ts'
 import { loadConfig } from '../../config.ts'
 import { connect, disconnect } from '../../db/client.ts'
 import { getLogger } from '../../logger.ts'
-import { app, initCliCommand } from '../shared.ts'
+import { app, initCliCommand, printCliJson, resolveOutputModeOrExit, resolveScopeLabel } from '../shared.ts'
 
 const log = getLogger(['suemo', 'cli', 'consolidate'])
 
@@ -10,11 +10,21 @@ export const consolidateCmd = app.sub('consolidate')
 	.meta({ description: 'Manually trigger memory consolidation (NREM + REM)' })
 	.flags({
 		'nrem-only': { type: 'boolean', description: 'Run only NREM (compression) phase', default: false },
+		scope: { type: 'string', short: 's', description: 'Scope label (defaults to inferred project scope)' },
+		json: { type: 'boolean', description: 'Output full JSON' },
+		pretty: { type: 'boolean', description: 'Human-readable output (default)' },
 	})
 	.run(async ({ flags }) => {
-		await initCliCommand('consolidate', { debug: flags.debug, config: flags.config })
+		const outputMode = resolveOutputModeOrExit(flags)
+		await initCliCommand('consolidate', {
+			debug: flags.debug,
+			config: flags.config,
+			json: outputMode === 'json',
+			quiet: flags.quiet,
+		})
 		log.debug('Running consolidate command', { nremOnly: flags['nrem-only'] })
 		const config = await loadConfig(process.cwd(), flags.config)
+		const scope = resolveScopeLabel(flags.scope, config)
 		const db = await connect(config.surreal)
 		try {
 			const run = await consolidate(db, {
@@ -23,8 +33,16 @@ export const consolidateCmd = app.sub('consolidate')
 				remRelationThreshold: config.consolidation.remRelationThreshold,
 				llm: config.consolidation.llm,
 				embedding: config.embedding,
+				...(scope ? { scope } : {}),
 			})
-			console.log(JSON.stringify(run, null, 2))
+			if (outputMode === 'json') {
+				printCliJson(run, flags)
+			} else {
+				console.log(
+					`Consolidation ${run.status}: phase=${run.phase} nodes_in=${run.nodes_in} nodes_out=${run.nodes_out}`,
+				)
+				if (run.error) console.log(`  error: ${run.error}`)
+			}
 		} finally {
 			await disconnect()
 		}

package/src/cli/commands/doctor.ts

@@ -3,7 +3,7 @@ import { loadConfig } from '../../config.ts'
 import { connect, disconnect } from '../../db/client.ts'
 import { checkCompatibility } from '../../db/preflight.ts'
 import { getLogger } from '../../logger.ts'
-import { app, initCliCommand } from '../shared.ts'
+import { app, initCliCommand, resolveOutputModeOrExit } from '../shared.ts'
 
 const log = getLogger(['suemo', 'cli', 'doctor'])
 
@@ -50,8 +50,19 @@ async function detectModelNames(db: Surreal): Promise<string[]> {
 
 const doctorEmbedCmd = doctor.sub('embed')
 	.meta({ description: 'Diagnose fn::embed() and show setup steps' })
+	.flags({
+		json: { type: 'boolean', description: 'Machine-readable output mode' },
+		'verbose-json': { type: 'boolean', description: 'Include embeddings in JSON output (implies --json)' },
+		pretty: { type: 'boolean', description: 'Human-readable output (default)' },
+	})
 	.run(async ({ flags }) => {
-		await initCliCommand('doctor embed', { debug: flags.debug, config: flags.config })
+		const outputMode = resolveOutputModeOrExit(flags)
+		await initCliCommand('doctor embed', {
+			debug: flags.debug,
+			config: flags.config,
+			json: outputMode === 'json',
+			quiet: flags.quiet,
+		})
 
 		const config = await loadConfig(process.cwd(), flags.config)
 		const endpoint = toCliEndpoint(config.surreal.url)
@@ -93,6 +104,8 @@ const doctorEmbedCmd = doctor.sub('embed')
 			console.log('\nHow to set up fn::embed() (step-by-step):')
 			console.log('\n1) Ensure SurrealDB CLI exposes ML commands:')
 			console.log('   surreal ml --help')
+			console.log('\n   and start SurrealDB with custom function capability:')
+			console.log('   surreal start --allow-funcs "fn::*" ...')
 			console.log('\n2) Import a .surml embedding model into this exact NS/DB:')
 			console.log(
 				`   surreal ml import --conn ${endpoint} --user <USER> --pass <PASS> --ns ${config.surreal.namespace} --db ${config.surreal.database} path/to/your-model.surml`,
@@ -115,8 +128,19 @@ const doctorEmbedCmd = doctor.sub('embed')
 
 export const doctorCmd = doctor
 	.command(doctorEmbedCmd)
+	.flags({
+		json: { type: 'boolean', description: 'Machine-readable output mode' },
+		'verbose-json': { type: 'boolean', description: 'Include embeddings in JSON output (implies --json)' },
+		pretty: { type: 'boolean', description: 'Human-readable output (default)' },
+	})
 	.run(async ({ flags }) => {
-		await initCliCommand('doctor', { debug: flags.debug, config: flags.config })
+		const outputMode = resolveOutputModeOrExit(flags)
+		await initCliCommand('doctor', {
+			debug: flags.debug,
+			config: flags.config,
+			json: outputMode === 'json',
+			quiet: flags.quiet,
+		})
 		console.log('Use one of:')
 		console.log('  suemo doctor embed')
 		console.log('\nRun `suemo doctor --help` for full details.')

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

@@ -4,7 +4,7 @@ import { loadConfig } from '../../config.ts'
 import { connect, disconnect } from '../../db/client.ts'
 import { getLogger } from '../../logger.ts'
 import type { MemoryNode, Relation } from '../../types.ts'
-import { app, initCliCommand } from '../shared.ts'
+import { app, initCliCommand, printCliJson, resolveOutputModeOrExit, resolveScopeLabel } from '../shared.ts'
 
 const log = getLogger(['suemo', 'cli', 'export-import'])
 
@@ -14,27 +14,41 @@ export const exportCmd = app.sub('export')
 	.flags({
 		scope: { type: 'string', short: 's', description: 'Filter by scope' },
 		all: { type: 'boolean', description: 'Include invalidated nodes' },
+		json: { type: 'boolean', description: 'Force JSONL-safe mode (stderr logs only)' },
+		pretty: { type: 'boolean', description: 'Human-readable output mode (default)' },
 	})
 	.run(async ({ flags }) => {
-		await initCliCommand('export', { debug: flags.debug, config: flags.config })
+		const outputMode = resolveOutputModeOrExit(flags)
+		await initCliCommand('export', {
+			debug: flags.debug,
+			config: flags.config,
+			json: outputMode === 'json',
+			quiet: flags.quiet,
+		})
 		log.debug('Running export command', {
 			hasScope: Boolean(flags.scope),
 			includeInvalidated: Boolean(flags.all),
 		})
 		const config = await loadConfig(process.cwd(), flags.config)
+		const resolvedScope = resolveScopeLabel(flags.scope, config)
+		log.debug('Resolved export scope', { scope: resolvedScope, explicit: flags.scope ?? null })
 		const db = await connect(config.surreal)
 		try {
 			const activeFilter = flags.all ? 'true' : '(valid_until = NONE OR valid_until > time::now())'
 			const scopeFilter = '($scope = NONE OR scope = $scope)'
 
-			const [nodesResult, relationsResult] = await Promise.all([
+			const [nodesResult, relationsResult, episodesResult] = await Promise.all([
 				db.query<[MemoryNode[]]>(
 					`
         SELECT * FROM memory WHERE ${activeFilter} AND ${scopeFilter} ORDER BY created_at ASC
       `,
-					{ scope: flags.scope ?? null },
+					{ scope: resolvedScope },
 				),
 				db.query<[Relation[]]>('SELECT * FROM relates_to ORDER BY created_at ASC'),
+				db.query<[Record<string, unknown>[]]>(
+					`SELECT * FROM episode WHERE ($scope = NONE OR session_id = $scope) ORDER BY started_at ASC`,
+					{ scope: resolvedScope },
+				),
 			])
 
 			for (const node of nodesResult[0] ?? []) {
@@ -43,6 +57,9 @@ export const exportCmd = app.sub('export')
 			for (const rel of relationsResult[0] ?? []) {
 				process.stdout.write(JSON.stringify({ _type: 'relation', ...rel }) + '\n')
 			}
+			for (const ep of episodesResult[0] ?? []) {
+				process.stdout.write(JSON.stringify({ _type: 'episode', ...ep }) + '\n')
+			}
 		} finally {
 			await disconnect()
 		}
@@ -52,8 +69,18 @@ export const exportCmd = app.sub('export')
 export const importCmd = app.sub('import')
 	.meta({ description: 'Import memories from a JSONL file' })
 	.args([{ name: 'file', type: 'string', required: true }])
+	.flags({
+		json: { type: 'boolean', description: 'Output JSON summary' },
+		pretty: { type: 'boolean', description: 'Human-readable output (default)' },
+	})
 	.run(async ({ args, flags }) => {
-		await initCliCommand('import', { debug: flags.debug, config: flags.config })
+		const outputMode = resolveOutputModeOrExit(flags)
+		await initCliCommand('import', {
+			debug: flags.debug,
+			config: flags.config,
+			json: outputMode === 'json',
+			quiet: flags.quiet,
+		})
 		log.debug('Running import command', { file: args.file })
 		const config = await loadConfig(process.cwd(), flags.config)
 		const db = await connect(config.surreal)
@@ -61,6 +88,7 @@ export const importCmd = app.sub('import')
 		const rl = createInterface({ input: createReadStream(args.file) })
 		let lineNum = 0
 		let imported = 0
+		let importedEpisode = 0
 		let skipped = 0
 		let errors = 0
 
@@ -111,6 +139,13 @@ export const importCmd = app.sub('import')
 							},
 						)
 						imported++
+					} else if (type === 'episode') {
+						await db.query('UPSERT <record<episode>>$id CONTENT $row', {
+							id: row['id'],
+							row,
+						})
+						importedEpisode++
+						imported++
 					} else {
 						skipped++
 					}
@@ -123,5 +158,11 @@ export const importCmd = app.sub('import')
 			rl.close()
 			await disconnect()
 		}
-		console.log(JSON.stringify({ imported, skipped, errors, lines: lineNum }, null, 2))
+		if (outputMode === 'json') {
+			printCliJson({ imported, importedEpisode, skipped, errors, lines: lineNum }, flags)
+		} else {
+			console.log(
+				`import done: imported=${imported} (episodes=${importedEpisode}) skipped=${skipped} errors=${errors} lines=${lineNum}`,
+			)
+		}
 	})

package/src/cli/commands/goal.ts

@@ -3,7 +3,7 @@ import { loadConfig } from '../../config.ts'
 import { connect, disconnect } from '../../db/client.ts'
 import { goalList, goalResolve, goalSet } from '../../goal.ts'
 import { getLogger } from '../../logger.ts'
-import { app, initCliCommand } from '../shared.ts'
+import { app, initCliCommand, printCliJson, resolveOutputModeOrExit, resolveScopeLabel } from '../shared.ts'
 
 const log = getLogger(['suemo', 'cli', 'goal'])
 
@@ -17,23 +17,38 @@ const setCmd = goal.sub('set')
 	.flags({
 		scope: { type: 'string', short: 's', description: 'Scope label' },
 		tags: { type: 'string', short: 't', description: 'Comma-separated tags' },
+		json: { type: 'boolean', description: 'Output JSON result' },
+		pretty: { type: 'boolean', description: 'Human-readable output (default)' },
 	})
 	.run(async ({ args, flags }) => {
-		await initCliCommand('goal set', { debug: flags.debug, config: flags.config })
+		const outputMode = resolveOutputModeOrExit(flags)
+		await initCliCommand('goal set', {
+			debug: flags.debug,
+			config: flags.config,
+			json: outputMode === 'json',
+			quiet: flags.quiet,
+		})
 		log.debug('Running goal set command', {
 			hasScope: Boolean(flags.scope),
 			tagCount: flags.tags ? flags.tags.split(',').filter(Boolean).length : 0,
 			contentLength: args.content.length,
 		})
 		const config = await loadConfig(process.cwd(), flags.config)
+		const resolvedScope = resolveScopeLabel(flags.scope, config)
+		log.debug('Resolved goal set scope', { scope: resolvedScope, explicit: flags.scope ?? null })
 		let db: Surreal | undefined
 		try {
 			db = await connect(config.surreal)
 			const node = await goalSet(db, args.content, config, {
-				...(flags.scope ? { scope: flags.scope } : {}),
+				scope: resolvedScope,
 				tags: flags.tags ? flags.tags.split(',').map((t) => t.trim()) : [],
 			})
-			console.log(JSON.stringify({ id: node.id, content: node.content }, null, 2))
+			if (outputMode === 'json') {
+				printCliJson({ id: node.id, content: node.content }, flags)
+			} else {
+				console.log(`Created goal: ${node.id}`)
+				console.log(`  ${node.content}`)
+			}
 		} finally {
 			if (db) await disconnect()
 		}
@@ -45,26 +60,45 @@ const listCmd = goal.sub('list')
 	.flags({
 		scope: { type: 'string', short: 's', description: 'Filter by scope' },
 		resolved: { type: 'boolean', description: 'Include resolved goals', default: false },
+		json: { type: 'boolean', description: 'Output JSON result' },
+		pretty: { type: 'boolean', description: 'Human-readable output (default)' },
 	})
 	.run(async ({ flags }) => {
-		await initCliCommand('goal list', { debug: flags.debug, config: flags.config })
+		const outputMode = resolveOutputModeOrExit(flags)
+		await initCliCommand('goal list', {
+			debug: flags.debug,
+			config: flags.config,
+			json: outputMode === 'json',
+			quiet: flags.quiet,
+		})
+		const config = await loadConfig(process.cwd(), flags.config)
+		const resolvedScope = resolveScopeLabel(flags.scope, config)
+		log.debug('Resolved goal list scope', { scope: resolvedScope, explicit: flags.scope ?? null })
 		log.debug('Running goal list command', {
-			hasScope: Boolean(flags.scope),
+			hasScope: Boolean(resolvedScope),
+			scope: resolvedScope,
 			includeResolved: Boolean(flags.resolved),
 		})
-		const config = await loadConfig(process.cwd(), flags.config)
 		let db: Surreal | undefined
 		try {
 			db = await connect(config.surreal)
 			const goals = await goalList(db, {
-				...(flags.scope ? { scope: flags.scope } : {}),
+				scope: resolvedScope,
 				includeResolved: flags.resolved,
 			})
-			for (const g of goals) {
-				const status = g.valid_until ? `resolved ${g.valid_until}` : 'active'
-				console.log(`[${status}] ${g.id}`)
-				console.log(`  ${g.content}`)
-				console.log()
+			if (outputMode === 'json') {
+				printCliJson(goals, flags)
+			} else {
+				if (goals.length === 0) {
+					console.log('No goals found.')
+					return
+				}
+				for (const g of goals) {
+					const status = g.valid_until ? `resolved ${g.valid_until}` : 'active'
+					console.log(`[${status}] ${g.id}`)
+					console.log(`  ${g.content}`)
+					console.log()
+				}
 			}
 		} finally {
 			if (db) await disconnect()
@@ -75,15 +109,29 @@ const listCmd = goal.sub('list')
 const resolveCmd = goal.sub('resolve')
 	.meta({ description: 'Mark a goal as resolved' })
 	.args([{ name: 'goalId', type: 'string', required: true }])
+	.flags({
+		json: { type: 'boolean', description: 'Output JSON result' },
+		pretty: { type: 'boolean', description: 'Human-readable output (default)' },
+	})
 	.run(async ({ args, flags }) => {
-		await initCliCommand('goal resolve', { debug: flags.debug, config: flags.config })
+		const outputMode = resolveOutputModeOrExit(flags)
+		await initCliCommand('goal resolve', {
+			debug: flags.debug,
+			config: flags.config,
+			json: outputMode === 'json',
+			quiet: flags.quiet,
+		})
 		log.debug('Running goal resolve command', { goalId: args.goalId })
 		const config = await loadConfig(process.cwd(), flags.config)
 		let db: Surreal | undefined
 		try {
 			db = await connect(config.surreal)
 			await goalResolve(db, args.goalId)
-			console.log(`✓ Goal ${args.goalId} resolved`)
+			if (outputMode === 'json') {
+				printCliJson({ ok: true, goalId: args.goalId }, flags)
+			} else {
+				console.log(`✓ Goal ${args.goalId} resolved`)
+			}
 		} finally {
 			if (db) await disconnect()
 		}