suemo 0.0.1 → 0.0.3

package/src/config.ts

@@ -1,6 +1,7 @@
 import { existsSync } from 'node:fs'
 import { join, resolve } from 'node:path'
 import { pathToFileURL } from 'node:url'
+import { getLogger } from './logger.ts'
 
 // ── Config shape ──────────────────────────────────────────────────────────────
 
@@ -17,8 +18,9 @@ export interface SurrealTarget {
 }
 
 export type EmbeddingProvider =
+	| { provider: 'openai-compatible'; url: string; model: string; dimension: number; apiKey?: string }
 	| { provider: 'surreal'; dimension: number }
-	| { provider: 'stub'; dimension: number } // test-only
+	| { provider: 'stub'; dimension: number }
 
 export interface LLMConfig {
 	url: string // OpenAI-compatible endpoint
@@ -49,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 {
@@ -69,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 = [
@@ -76,11 +159,21 @@ const CONFIG_CANDIDATES = [
 	'suemo.config.js',
 ]
 
-const HOME_CONFIG = join(
-	process.env.HOME ?? process.env.USERPROFILE ?? '~',
-	'.suemo',
-	'suemo.ts',
-)
+const log = getLogger(['suemo', 'config'])
+
+function getHomeConfigPath(): string | null {
+	const home = process.env.HOME ?? process.env.USERPROFILE
+	if (!home) return null
+	return join(home, '.suemo', 'suemo.ts')
+}
+
+function resolveConfigPath(p: string): string {
+	if (p.startsWith('~/')) {
+		const home = process.env.HOME ?? process.env.USERPROFILE
+		if (home) return resolve(home, p.slice(2))
+	}
+	return resolve(p)
+}
 
 export async function loadConfig(
 	cwd = process.cwd(),
@@ -88,23 +181,40 @@ export async function loadConfig(
 ): Promise<SuemoConfig> {
 	// 1. Explicit --config flag
 	if (overridePath) {
-		return importConfig(resolve(overridePath))
+		const resolved = resolveConfigPath(overridePath)
+		log.debug('Loading config from --config', { path: resolved })
+		return importConfig(resolved)
+	}
+	// 2. Environment override
+	const envConfigPath = process.env.SUEMO_CONFIG_PATH?.trim()
+	if (envConfigPath) {
+		const resolved = resolveConfigPath(envConfigPath)
+		log.debug('Loading config from SUEMO_CONFIG_PATH', { path: resolved })
+		return importConfig(resolved)
 	}
-	// 2. Project-local
+	// 3. Project-local
 	for (const name of CONFIG_CANDIDATES) {
 		const p = resolve(cwd, name)
-		if (existsSync(p)) return importConfig(p)
+		if (existsSync(p)) {
+			log.debug('Loading project-local config', { path: p })
+			return importConfig(p)
+		}
+	}
+	// 4. User-level
+	const homeConfig = getHomeConfigPath()
+	if (homeConfig && existsSync(homeConfig)) {
+		log.debug('Loading user-level config', { path: homeConfig })
+		return importConfig(homeConfig)
 	}
-	// 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.',
+			+ 'Run `suemo init config` to create ~/.suemo/suemo.ts, set SUEMO_CONFIG_PATH, or create suemo.config.ts in the project root.',
 	)
 }
 
 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') {

package/src/db/preflight.ts

@@ -12,18 +12,33 @@ export interface CompatibilityResult {
 	errors: string[]
 }
 
+export interface CompatibilityOptions {
+	/**
+	 * Whether missing fn::embed() should fail compatibility.
+	 * Keep true for runtime paths that execute vector/embed queries.
+	 */
+	requireEmbedding?: boolean
+	/**
+	 * Human-readable label for logging this preflight execution.
+	 */
+	context?: string
+}
+
 const MIN_MAJOR = 3
 
 export async function checkCompatibility(
 	db: Surreal,
+	options: CompatibilityOptions = {},
 ): Promise<CompatibilityResult> {
 	const errors: string[] = []
 	let surrealVersion = 'unknown'
 	let surrealkv = false
 	let retention_ok = false
 	let embedding = false
+	const requireEmbedding = options.requireEmbedding ?? true
+	const context = options.context ?? 'default'
 
-	log.info('Running preflight compatibility checks')
+	log.info('Running preflight compatibility checks', { requireEmbedding, context })
 
 	// ── Check 1: version string ───────────────────────────────────────────────
 	try {
@@ -41,6 +56,7 @@ export async function checkCompatibility(
 				)
 			}
 		}
+		log.debug('SurrealDB version check complete', { surrealVersion })
 	} catch (e) {
 		errors.push(`Cannot retrieve SurrealDB version: ${String(e)}`)
 	}
@@ -54,6 +70,7 @@ export async function checkCompatibility(
 		// 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
+		log.debug('SurrealKV VERSION probe passed')
 	} catch (e: unknown) {
 		const msg = String(e).toLowerCase()
 		if (msg.includes('version') || msg.includes('surrealkv') || msg.includes('not supported')) {
@@ -83,6 +100,7 @@ export async function checkCompatibility(
 			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
+			log.debug('Retention probe passed', { ninetyDaysAgo })
 		} catch (e: unknown) {
 			const msg = String(e).toLowerCase()
 			if (msg.includes('retention') || msg.includes('version')) {
@@ -104,20 +122,28 @@ export async function checkCompatibility(
 
 	// ── 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.
+	// An "Unknown function" error means embedding runtime is unavailable.
 	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
+		log.debug('Embedding function probe passed')
 	} 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).",
-			)
+			embedding = false
+			if (requireEmbedding) {
+				errors.push(
+					'fn::embed() is not available in this SurrealDB database. Import/configure a SurrealML embedding model for this namespace/database, then retry.',
+				)
+			} else {
+				log.warn('Embedding function unavailable; continuing due to non-strict preflight mode', {
+					context,
+					error: String(e),
+				})
+			}
 		} else {
 			// Other error (e.g. no model configured but function exists) — treat as available
 			embedding = true

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,33 +25,37 @@ 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;
 
 -- REFERENCES: bidirectional record link (SurrealDB v3.0)
 DEFINE FIELD OVERWRITE consolidated_into ON memory
-  TYPE option<record<memory>> REFERENCES;
+  TYPE option<record<memory>> REFERENCE;
 
 -- 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
+-- Vector index: HNSW (keep syntax compatible with current SurrealDB target)
 DEFINE INDEX OVERWRITE idx_memory_embedding
   ON memory FIELDS embedding
-  HNSW DIMENSION 1536 DIST COSINE
-  DEFER;
+  HNSW DIMENSION 384 DIST COSINE;
 
 -- 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;
+DEFINE INDEX OVERWRITE idx_memory_content_fts
+  ON memory FIELDS content
+  FULLTEXT ANALYZER suemo_analyzer BM25;
+
+DEFINE INDEX OVERWRITE idx_memory_summary_fts
+  ON memory FIELDS summary
+  FULLTEXT ANALYZER suemo_analyzer BM25;
 
 -- Compound indexes for timeline and filter queries
 DEFINE INDEX OVERWRITE idx_memory_scope_time
@@ -62,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;
@@ -73,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;
@@ -81,10 +90,11 @@ 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> DEFAULT NONE;
 
 -- REFERENCES: bidirectional array of memory links
 DEFINE FIELD OVERWRITE memory_ids  ON episode
-  TYPE array<record<memory>> REFERENCES
+  TYPE array<record<memory>> REFERENCE
   DEFAULT [];
 
 -- ── consolidation_run ────────────────────────────────────────────────────────
@@ -102,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

@@ -11,12 +11,15 @@ const log = getLogger(['suemo', 'db', 'schema'])
 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) {
+	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', { stmt: stmt.slice(0, 60) })
+			log.debug('Schema statement OK', { index, stmt: stmt.slice(0, 60) })
 		} catch (e) {
-			log.error('Schema statement failed', { stmt, error: String(e) })
+			log.error('Schema statement failed', { index, stmt, error: String(e) })
 			throw e
 		}
 	}

package/src/embedding/index.ts

@@ -0,0 +1,52 @@
+import type { EmbeddingProvider } from '../config.ts'
+import { getLogger } from '../logger.ts'
+import { embedText } from './openai-compatible.ts'
+
+const log = getLogger(['suemo', 'embedding'])
+
+export interface EmbeddingResult {
+	clause: string
+	param?: number[]
+}
+
+export async function getEmbedding(
+	text: string,
+	config: EmbeddingProvider,
+): Promise<EmbeddingResult> {
+	log.debug('getEmbedding()', { provider: config.provider, dimension: config.dimension })
+
+	switch (config.provider) {
+		case 'surreal':
+			return { clause: 'fn::embed($content)' }
+
+		case 'openai-compatible': {
+			const vec = await embedText(text, config)
+			if (vec.length !== config.dimension) {
+				throw new Error(
+					`Embedding dimension mismatch: expected ${config.dimension}, got ${vec.length}`,
+				)
+			}
+			return { clause: '$embedding', param: vec }
+		}
+
+		case 'stub': {
+			const vec = new Array(config.dimension).fill(0)
+			log.debug('stub embedding: returning zero vector', { dimension: config.dimension })
+			return { clause: '$embedding', param: vec }
+		}
+	}
+}
+
+export function buildEmbeddingClause(config: EmbeddingProvider): string {
+	switch (config.provider) {
+		case 'surreal':
+			return 'fn::embed($content)'
+		case 'openai-compatible':
+		case 'stub':
+			return '$embedding'
+	}
+}
+
+export function getZeroVector(dimension: number): number[] {
+	return new Array(dimension).fill(0)
+}

package/src/embedding/openai-compatible.ts

@@ -0,0 +1,43 @@
+// src/embedding/openai_compatible.ts
+import { getLogger } from "../logger.ts";
+
+const log = getLogger(["suemo", "embedding", "openai-compatible"]);
+
+export interface OpenAICompatibleEmbeddingConfig {
+	url: string;       // e.g. http://127.0.0.1:8080/v1/embeddings
+	model: string;
+	dimension: number;
+	apiKey?: string;
+}
+
+export async function embedText(
+	text: string,
+	config: OpenAICompatibleEmbeddingConfig,
+): Promise<number[]> {
+	log.debug("embedText()", { textPreview: text.slice(0, 60) });
+
+	const res = await fetch(config.url, {
+		method: "POST",
+		headers: {
+			"Content-Type": "application/json",
+			"Authorization": `Bearer ${config.apiKey ?? "local"}`,
+		},
+		body: JSON.stringify({ input: text, model: config.model }),
+	});
+
+	if (!res.ok) {
+		throw new Error(`Embedding server error ${res.status}: ${await res.text()}`);
+	}
+
+	const json = await res.json() as {
+		data: { embedding: number[]; index: number }[];
+	};
+
+	const vec = json.data[0]?.embedding;
+	if (!vec) throw new Error("Embedding server returned empty data");
+	if (vec.length !== config.dimension) {
+		throw new Error(`Dimension mismatch: expected ${config.dimension}, got ${vec.length}`);
+	}
+
+	return vec;
+}

package/src/goal.ts

@@ -1,4 +1,5 @@
 import type { Surreal } from 'surrealdb'
+import type { SuemoConfig } from './config.ts'
 import { getLogger } from './logger.ts'
 import { invalidate, observe } from './memory/write.ts'
 import type { MemoryNode } from './types.ts'
@@ -8,10 +9,11 @@ const log = getLogger(['suemo', 'goal'])
 export async function goalSet(
 	db: Surreal,
 	content: string,
+	config: SuemoConfig,
 	opts: { scope?: string; tags?: string[] } = {},
 ): Promise<MemoryNode> {
 	log.info('goalSet()', { content: content.slice(0, 60) })
-	return observe(db, { content, kind: 'goal', ...opts })
+	return observe(db, { content, kind: 'goal', ...opts }, config)
 }
 
 export async function goalResolve(db: Surreal, goalId: string): Promise<void> {

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'