suemo 0.0.1

package/src/cognitive/health.ts

@@ -0,0 +1,123 @@
+import type { Surreal } from 'surrealdb'
+import { checkCompatibility } from '../db/preflight.ts'
+import { getLogger } from '../logger.ts'
+import type { ConsolidationRun, HealthReport } from '../types.ts'
+
+const log = getLogger(['suemo', 'cognitive', 'health'])
+
+export async function healthReport(db: Surreal): Promise<HealthReport> {
+	log.info('healthReport()')
+
+	const [
+		totalResult,
+		activeResult,
+		consolidatedResult,
+		byKindResult,
+		byScopeResult,
+		relationCountResult,
+		activeGoalsResult,
+		frssDueResult,
+		lastRunResult,
+		compatResult,
+	] = await Promise.all([
+		// total nodes
+		db.query<[{ count: number }[]]>('SELECT count() AS count FROM memory GROUP ALL'),
+		// active nodes
+		db.query<[{ count: number }[]]>(`
+      SELECT count() AS count FROM memory
+      WHERE valid_until = NONE OR valid_until > time::now()
+      GROUP ALL
+    `),
+		// consolidated nodes
+		db.query<[{ count: number }[]]>(
+			'SELECT count() AS count FROM memory WHERE consolidated = true GROUP ALL',
+		),
+		// by kind
+		db.query<[{ kind: string; count: number }[]]>(
+			'SELECT kind, count() AS count FROM memory GROUP BY kind',
+		),
+		// by scope
+		db.query<[{ scope: string | null; count: number }[]]>(
+			'SELECT scope, count() AS count FROM memory WHERE scope != NONE GROUP BY scope',
+		),
+		// relation count
+		db.query<[{ count: number }[]]>('SELECT count() AS count FROM relates_to GROUP ALL'),
+		// active goals
+		db.query<[{ count: number }[]]>(`
+      SELECT count() AS count FROM memory
+      WHERE kind = 'goal' AND (valid_until = NONE OR valid_until > time::now())
+      GROUP ALL
+    `),
+		// FSRS due
+		db.query<[{ count: number }[]]>(`
+      SELECT count() AS count FROM memory
+      WHERE fsrs_next_review != NONE
+        AND fsrs_next_review <= time::now()
+        AND (valid_until = NONE OR valid_until > time::now())
+      GROUP ALL
+    `),
+		// last consolidation run
+		db.query<[ConsolidationRun[]]>(
+			'SELECT * FROM consolidation_run ORDER BY started_at DESC LIMIT 1',
+		),
+		// compat check (non-blocking)
+		checkCompatibility(db),
+	])
+
+	const byKind: Record<string, number> = {}
+	for (const row of byKindResult[0] ?? []) byKind[row.kind] = row.count
+
+	const byScope: Record<string, number> = {}
+	for (const row of byScopeResult[0] ?? []) {
+		if (row.scope) byScope[row.scope] = row.count
+	}
+
+	return {
+		nodes: {
+			total: totalResult[0]?.[0]?.count ?? 0,
+			active: activeResult[0]?.[0]?.count ?? 0,
+			consolidated: consolidatedResult[0]?.[0]?.count ?? 0,
+			by_kind: byKind,
+			by_scope: byScope,
+		},
+		relations: relationCountResult[0]?.[0]?.count ?? 0,
+		goals_active: activeGoalsResult[0]?.[0]?.count ?? 0,
+		fsrs_due: frssDueResult[0]?.[0]?.count ?? 0,
+		last_consolidation: lastRunResult[0]?.[0] ?? null,
+		version_check: {
+			surreal_version: compatResult.surrealVersion,
+			surrealkv: compatResult.surrealkv,
+			retention_ok: compatResult.retention_ok,
+		},
+	}
+}
+
+export async function vitals(db: Surreal): Promise<{
+	last10Runs: ConsolidationRun[]
+	nodesByKind: Record<string, number>
+	nodesByScope: Record<string, number>
+}> {
+	log.info('vitals()')
+	const [runsResult, byKindResult, byScopeResult] = await Promise.all([
+		db.query<[ConsolidationRun[]]>(
+			'SELECT * FROM consolidation_run ORDER BY started_at DESC LIMIT 10',
+		),
+		db.query<[{ kind: string; count: number }[]]>(
+			'SELECT kind, count() AS count FROM memory GROUP BY kind',
+		),
+		db.query<[{ scope: string | null; count: number }[]]>(
+			'SELECT scope, count() AS count FROM memory WHERE scope != NONE GROUP BY scope',
+		),
+	])
+
+	const nodesByKind: Record<string, number> = {}
+	for (const r of byKindResult[0] ?? []) nodesByKind[r.kind] = r.count
+	const nodesByScope: Record<string, number> = {}
+	for (const r of byScopeResult[0] ?? []) if (r.scope) nodesByScope[r.scope] = r.count
+
+	return {
+		last10Runs: runsResult[0] ?? [],
+		nodesByKind,
+		nodesByScope,
+	}
+}

package/src/config.ts

@@ -0,0 +1,114 @@
+import { existsSync } from 'node:fs'
+import { join, resolve } from 'node:path'
+import { pathToFileURL } from 'node:url'
+
+// ── Config shape ──────────────────────────────────────────────────────────────
+
+export interface AuthConfig {
+	user: string
+	pass: string
+}
+
+export interface SurrealTarget {
+	url: string
+	namespace: string
+	database: string
+	auth: AuthConfig
+}
+
+export type EmbeddingProvider =
+	| { provider: 'surreal'; dimension: number }
+	| { provider: 'stub'; dimension: number } // test-only
+
+export interface LLMConfig {
+	url: string // OpenAI-compatible endpoint
+	model: string
+	apiKey: string
+}
+
+export interface ConsolidationConfig {
+	trigger: 'timer' | 'reactive' | 'manual'
+	intervalMinutes: number
+	reactiveThreshold: number // unconsolidated node count before auto-trigger
+	nremSimilarityThreshold: number // cosine threshold for clustering (0.0–1.0)
+	remRelationThreshold: number // min score to create an auto-relation (0.0–1.0)
+	llm: LLMConfig
+}
+
+export interface RetrievalConfig {
+	weights: {
+		vector: number
+		bm25: number
+		graph: number
+		temporal: number
+	}
+}
+
+export interface McpConfig {
+	port: number
+	host: string
+}
+
+export interface SyncConfig {
+	remote: SurrealTarget
+	cursor?: string // ISO datetime; absence means full sync on first run
+}
+
+export interface SuemoConfig {
+	surreal: SurrealTarget
+	embedding: EmbeddingProvider
+	consolidation: ConsolidationConfig
+	retrieval: RetrievalConfig
+	mcp: McpConfig
+	sync?: SyncConfig
+}
+
+// ── defineConfig — identity fn for type safety ─────────────────────────────
+
+export function defineConfig(config: SuemoConfig): SuemoConfig {
+	return config
+}
+
+// ── loadConfig — resolution chain ────────────────────────────────────────────
+
+const CONFIG_CANDIDATES = [
+	'suemo.config.ts',
+	'suemo.config.js',
+]
+
+const HOME_CONFIG = join(
+	process.env.HOME ?? process.env.USERPROFILE ?? '~',
+	'.suemo',
+	'suemo.ts',
+)
+
+export async function loadConfig(
+	cwd = process.cwd(),
+	overridePath?: string,
+): Promise<SuemoConfig> {
+	// 1. Explicit --config flag
+	if (overridePath) {
+		return importConfig(resolve(overridePath))
+	}
+	// 2. Project-local
+	for (const name of CONFIG_CANDIDATES) {
+		const p = resolve(cwd, name)
+		if (existsSync(p)) return importConfig(p)
+	}
+	// 3. User-level
+	if (existsSync(HOME_CONFIG)) return importConfig(HOME_CONFIG)
+
+	throw new Error(
+		'No suemo config found.\n'
+			+ 'Run `suemo init` to create ~/.suemo/suemo.ts, or create suemo.config.ts in the project root.',
+	)
+}
+
+async function importConfig(path: string): Promise<SuemoConfig> {
+	const mod = await import(pathToFileURL(path).href)
+	const cfg: unknown = mod.default ?? mod
+	if (!cfg || typeof cfg !== '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
+}

package/src/db/client.ts

@@ -0,0 +1,59 @@
+// SDK v2: requires @surrealdb/node for WebSocket support in Bun/Node runtimes.
+// createRemoteEngines() handles ws://, wss://, http://, https:// connections.
+// createNodeEngines() patches in the Node.js WebSocket implementation.
+import { createNodeEngines } from '@surrealdb/node'
+import { createRemoteEngines, Surreal } from 'surrealdb'
+import type { SurrealTarget } from '../config.ts'
+import { getLogger } from '../logger.ts'
+
+const log = getLogger(['suemo', 'db', 'client'])
+
+let _db: Surreal | null = null
+
+export async function connect(target: SurrealTarget): Promise<Surreal> {
+	if (_db) return _db
+
+	log.info('Connecting to SurrealDB', {
+		url: target.url,
+		ns: target.namespace,
+		db: target.database,
+	})
+
+	// v2 SDK: engines are registered at construction time, not at connect.
+	// Both remote (ws/wss/http) and Node.js engines are needed for Bun.
+	const db = new Surreal({
+		engines: {
+			...createRemoteEngines(),
+			...createNodeEngines(),
+		},
+	})
+
+	// v2 SDK: namespace, database, and authentication can all be passed inline
+	// to connect(). The `authentication` callback is invoked on connect and on
+	// any automatic reconnection/token-refresh cycle.
+	await db.connect(target.url, {
+		namespace: target.namespace,
+		database: target.database,
+		authentication: () => ({
+			username: target.auth.user,
+			password: target.auth.pass,
+		}),
+	})
+
+	_db = db
+	log.info('Connected')
+	return db
+}
+
+export function getDb(): Surreal {
+	if (!_db) throw new Error('SurrealDB not connected. Call connect() first.')
+	return _db
+}
+
+export async function disconnect(): Promise<void> {
+	if (_db) {
+		await _db.close()
+		_db = null
+		log.info('Disconnected')
+	}
+}

package/src/db/preflight.ts

@@ -0,0 +1,152 @@
+import type { Surreal } from 'surrealdb'
+import { getLogger } from '../logger.ts'
+
+const log = getLogger(['suemo', 'db', 'preflight'])
+
+export interface CompatibilityResult {
+	ok: boolean
+	surrealVersion: string
+	surrealkv: boolean
+	retention_ok: boolean // SURREAL_DATASTORE_RETENTION on server >= 90d
+	embedding: boolean
+	errors: string[]
+}
+
+const MIN_MAJOR = 3
+
+export async function checkCompatibility(
+	db: Surreal,
+): Promise<CompatibilityResult> {
+	const errors: string[] = []
+	let surrealVersion = 'unknown'
+	let surrealkv = false
+	let retention_ok = false
+	let embedding = false
+
+	log.info('Running preflight compatibility checks')
+
+	// ── Check 1: version string ───────────────────────────────────────────────
+	try {
+		surrealVersion = (await db.version()).version
+		// version string: "surrealdb-3.0.4" → extract semver
+		const match = surrealVersion.match(/(\d+)\.(\d+)\.(\d+)/)
+		if (!match) {
+			errors.push(`Cannot parse version string: "${surrealVersion}"`)
+		} else {
+			const major = parseInt(match[1]!, 10)
+			if (major < MIN_MAJOR) {
+				errors.push(
+					`SurrealDB ${surrealVersion} is below the required v${MIN_MAJOR}.0.0. `
+						+ `Start suemo with: surreal start --bind 0.0.0.0:8000 surrealkv://path/to/data`,
+				)
+			}
+		}
+	} catch (e) {
+		errors.push(`Cannot retrieve SurrealDB version: ${String(e)}`)
+	}
+
+	// ── Check 2: SurrealKV (VERSION keyword probe) ────────────────────────────
+	// 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()')
+		// 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'")
+		surrealkv = true
+	} catch (e: unknown) {
+		const msg = String(e).toLowerCase()
+		if (msg.includes('version') || msg.includes('surrealkv') || msg.includes('not supported')) {
+			errors.push(
+				'VERSION queries not supported — SurrealDB must be started with SurrealKV storage. '
+					+ 'Use: surreal start surrealkv://path/to/data',
+			)
+		} else {
+			// Unexpected error — still fail but report verbatim
+			errors.push(`SurrealKV probe failed unexpectedly: ${String(e)}`)
+		}
+	} finally {
+		try {
+			await db.query('DELETE suemo_preflight:probe')
+		} catch { /* ignore cleanup errors */ }
+	}
+
+	// ── Check 3: SURREAL_DATASTORE_RETENTION — probe VERSION reach ──────────────
+	// We can't read env vars from the server directly via SurrealQL. Instead we
+	// probe how far back VERSION queries can reach using the sentinel record we
+	// already created above (or a second probe). If VERSION 90 days ago resolves
+	// without a "retention" error, the server has sufficient retention configured.
+	// Note: SurrealKV has no hard deletes yet — retention controls time-travel depth.
+	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(`SELECT * FROM suemo_retention_probe:v VERSION d'${ninetyDaysAgo}'`)
+			retention_ok = true
+		} catch (e: unknown) {
+			const msg = String(e).toLowerCase()
+			if (msg.includes('retention') || msg.includes('version')) {
+				errors.push(
+					'SurrealDB VERSION time-travel cannot reach 90 days back. '
+						+ 'Start SurrealDB with: SURREAL_DATASTORE_RETENTION=90d surreal start surrealkv://path/to/data',
+				)
+			} else {
+				// Unexpected error — still flag but don't assume retention is wrong
+				retention_ok = true
+				log.debug('Retention probe returned unexpected error (may be fine)', { error: String(e) })
+			}
+		} finally {
+			try {
+				await db.query('DELETE suemo_retention_probe:v')
+			} catch { /* ignore */ }
+		}
+	}
+
+	// ── Check 4: fn::embed() resolves ────────────────────────────────────────
+	// We don't actually embed anything — we just check that the function exists.
+	// An "Unknown function" error means the embedding plugin is not configured.
+	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
+	} catch (e: unknown) {
+		const msg = String(e).toLowerCase()
+		if (msg.includes('unknown function') || msg.includes('fn::embed')) {
+			errors.push(
+				'fn::embed() is not available. Configure an embedding model in SurrealDB, or '
+					+ "use embedding.provider = 'stub' in suemo config (test-only).",
+			)
+		} 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) })
+		}
+	}
+
+	const ok = errors.length === 0
+
+	if (ok) {
+		log.info('All preflight checks passed', { surrealVersion, surrealkv, retention_ok, embedding })
+	} else {
+		log.error('Preflight checks failed', { errors })
+	}
+
+	return { ok, surrealVersion, surrealkv, retention_ok, embedding, errors }
+}
+
+/**
+ * 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)
+	if (!result.ok) {
+		console.error('\n[suemo] Compatibility check failed:\n')
+		for (const err of result.errors) {
+			console.error(`  ✗ ${err}`)
+		}
+		console.error('\nFix the issues above and retry.\n')
+		process.exit(1)
+	}
+}

package/src/db/schema.surql

@@ -0,0 +1,109 @@
+-- ─────────────────────────────────────────────────────────────────────────────
+-- suemo schema — SurrealDB v3.0 + SurrealKV
+-- All DEFINE statements use OVERWRITE so this is idempotent.
+-- ─────────────────────────────────────────────────────────────────────────────
+
+-- ── memory ───────────────────────────────────────────────────────────────────
+DEFINE TABLE OVERWRITE memory SCHEMAFULL;
+
+DEFINE FIELD OVERWRITE kind         ON memory TYPE string
+  ASSERT $value INSIDE ['observation','belief','question','hypothesis','goal'];
+
+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 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;
+
+-- Temporal: valid_from always set by system at write time
+-- valid_until: set by system on contradiction detection or explicit invalidate()
+-- Agents NEVER supply either field.
+DEFINE FIELD OVERWRITE valid_from   ON memory TYPE datetime       DEFAULT time::now();
+DEFINE FIELD OVERWRITE valid_until  ON memory TYPE option<datetime> DEFAULT NONE;
+
+DEFINE FIELD OVERWRITE source       ON memory TYPE option<string>;
+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;
+
+-- REFERENCES: bidirectional record link (SurrealDB v3.0)
+DEFINE FIELD OVERWRITE consolidated_into ON memory
+  TYPE option<record<memory>> REFERENCES;
+
+-- FSRS spaced-repetition fields (all optional; populated on first recall())
+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>;
+
+-- Vector index: HNSW, DEFER so init does not block on large existing datasets
+DEFINE INDEX OVERWRITE idx_memory_embedding
+  ON memory FIELDS embedding
+  HNSW DIMENSION 1536 DIST COSINE
+  DEFER;
+
+-- Full-text index: BM25 over content + summary
+DEFINE ANALYZER OVERWRITE suemo_analyzer
+  TOKENIZERS blank,class
+  FILTERS lowercase,snowball(english);
+
+DEFINE INDEX OVERWRITE idx_memory_fts
+  ON memory FIELDS content, summary
+  SEARCH ANALYZER suemo_analyzer BM25;
+
+-- Compound indexes for timeline and filter queries
+DEFINE INDEX OVERWRITE idx_memory_scope_time
+  ON memory FIELDS scope, created_at;
+
+DEFINE INDEX OVERWRITE idx_memory_kind_valid
+  ON memory FIELDS kind, valid_until;
+
+DEFINE INDEX OVERWRITE idx_memory_salience
+  ON memory FIELDS salience;
+
+-- ── relates_to ───────────────────────────────────────────────────────────────
+DEFINE TABLE OVERWRITE relates_to SCHEMAFULL
+  TYPE RELATION IN memory OUT memory;
+
+DEFINE FIELD OVERWRITE kind       ON relates_to TYPE string
+  ASSERT $value INSIDE ['supports','contradicts','derived_from','caused_by','similar_to','updates','sequential'];
+
+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();
+
+-- ── episode ───────────────────────────────────────────────────────────────────
+DEFINE TABLE OVERWRITE episode SCHEMAFULL;
+
+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>;
+
+-- REFERENCES: bidirectional array of memory links
+DEFINE FIELD OVERWRITE memory_ids  ON episode
+  TYPE array<record<memory>> REFERENCES
+  DEFAULT [];
+
+-- ── consolidation_run ────────────────────────────────────────────────────────
+DEFINE TABLE OVERWRITE consolidation_run SCHEMAFULL;
+
+DEFINE FIELD OVERWRITE started_at   ON consolidation_run TYPE datetime DEFAULT time::now();
+DEFINE FIELD OVERWRITE completed_at ON consolidation_run TYPE option<datetime> DEFAULT NONE;
+DEFINE FIELD OVERWRITE phase        ON consolidation_run TYPE string
+  ASSERT $value INSIDE ['nrem','rem','full'];
+DEFINE FIELD OVERWRITE nodes_in     ON consolidation_run TYPE int     DEFAULT 0;
+DEFINE FIELD OVERWRITE nodes_out    ON consolidation_run TYPE int     DEFAULT 0;
+DEFINE FIELD OVERWRITE status       ON consolidation_run TYPE string
+  ASSERT $value INSIDE ['running','done','failed'];
+DEFINE FIELD OVERWRITE error        ON consolidation_run TYPE option<string> DEFAULT NONE;
+
+-- ── sync_cursor ───────────────────────────────────────────────────────────────
+-- One record per (remote.url, remote.ns, remote.db) triple.
+-- Stores the last successfully synced created_at timestamp.
+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 last_synced ON sync_cursor TYPE datetime DEFAULT time::now();

package/src/db/schema.ts

@@ -0,0 +1,24 @@
+import { Surreal } from 'surrealdb'
+import { getLogger } from '../logger.ts'
+
+import SCHEMA from './schema.surql' with { type: 'text' }
+
+const log = getLogger(['suemo', 'db', 'schema'])
+
+// schema.surql is inlined as a template string to avoid filesystem read concerns
+// at runtime. Each statement is separated by ";\n" and executed individually.
+
+export async function runSchema(db: Surreal): Promise<void> {
+	log.info('Running schema migrations')
+	const statements = SCHEMA.split(/;\s*\n/).map((s) => s.trim()).filter(Boolean)
+	for (const stmt of statements) {
+		try {
+			await db.query(stmt)
+			log.debug('Schema statement OK', { stmt: stmt.slice(0, 60) })
+		} catch (e) {
+			log.error('Schema statement failed', { stmt, error: String(e) })
+			throw e
+		}
+	}
+	log.info('Schema ready')
+}

package/src/env.d.ts

@@ -0,0 +1,4 @@
+declare module '*.surql' {
+	const content: string
+	export default content
+}

package/src/goal.ts

@@ -0,0 +1,39 @@
+import type { Surreal } from 'surrealdb'
+import { getLogger } from './logger.ts'
+import { invalidate, observe } from './memory/write.ts'
+import type { MemoryNode } from './types.ts'
+
+const log = getLogger(['suemo', 'goal'])
+
+export async function goalSet(
+	db: Surreal,
+	content: string,
+	opts: { scope?: string; tags?: string[] } = {},
+): Promise<MemoryNode> {
+	log.info('goalSet()', { content: content.slice(0, 60) })
+	return observe(db, { content, kind: 'goal', ...opts })
+}
+
+export async function goalResolve(db: Surreal, goalId: string): Promise<void> {
+	log.info('goalResolve()', { goalId })
+	await invalidate(db, goalId, 'resolved')
+}
+
+export async function goalList(
+	db: Surreal,
+	opts: { scope?: string; includeResolved?: boolean } = {},
+): Promise<MemoryNode[]> {
+	log.info('goalList()', opts)
+	const filter = opts.includeResolved
+		? "kind = 'goal'"
+		: "kind = 'goal' AND (valid_until = NONE OR valid_until > time::now())"
+	return db.query<[MemoryNode[]]>(
+		`
+    SELECT * FROM memory
+    WHERE ${filter}
+      AND ($scope = NONE OR scope = $scope)
+    ORDER BY created_at DESC
+  `,
+		{ scope: opts.scope ?? null },
+	).then((r) => r[0] ?? [])
+}

package/src/index.ts

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