suemo 0.0.1

package/src/logger.ts

@@ -0,0 +1,60 @@
+// src/logger.ts
+// Call initLogger() once in cli/index.ts and mcp/server.ts before anything else.
+
+import { getFileSink } from '@logtape/file'
+import { configure, getConsoleSink, getLogger, type Sink } from '@logtape/logtape'
+
+export { getLogger }
+
+export type LogLevel = 'debug' | 'info' | 'warning' | 'error' | 'fatal'
+
+// Different formatters for different purposes
+const prettySink: Sink = getConsoleSink({
+	formatter: record => `${record.level}: ${String(record.message)}\n`,
+})
+
+const jsonSink: Sink = getConsoleSink({
+	formatter: record =>
+		JSON.stringify({
+			level: record.level,
+			message: record.message,
+			category: record.category,
+			timestamp: record.timestamp,
+		}) + '\n',
+})
+
+export async function initLogger(options: {
+	level: LogLevel
+	logFile?: string // if set, also write to file
+}): Promise<void> {
+	const sinks: Record<string, ReturnType<typeof getConsoleSink>> = {
+		pretty: prettySink,
+		json: jsonSink,
+	}
+
+	if (options.logFile) {
+		sinks['file'] = getFileSink(options.logFile)
+	}
+
+	await configure({
+		reset: true,
+		sinks,
+		loggers: [
+			{
+				category: ['logtape', 'meta'],
+				lowestLevel: 'warning', // or 'error' to silence info messages
+				sinks: ['json'], // separate sink for logging diagnostics
+			},
+			{
+				category: ['suemo'],
+				lowestLevel: options.level,
+				sinks: Object.keys(sinks).filter(item => item !== 'json'),
+			},
+		],
+	})
+}
+
+// ── Logger factory — used in every domain module ──────────────────────────────
+// Usage: const log = getLogger(["suemo", "memory", "write"]);
+//        log.info("observe called", { content, scope });
+//        log.debug`raw result: ${JSON.stringify(result)}`;

package/src/mcp/server.ts

@@ -0,0 +1,23 @@
+// src/mcp/server.ts
+import { Elysia } from 'elysia'
+import type { SuemoConfig } from '../config.ts'
+import { connect } from '../db/client.ts'
+import { requireCompatibility } from '../db/preflight.ts'
+import { runSchema } from '../db/schema.ts'
+import { getLogger } from '../logger.ts'
+import { buildMcpRouter } from './tools.ts'
+
+const log = getLogger(['suemo', 'mcp'])
+
+export async function startMcpServer(config: SuemoConfig): Promise<void> {
+	const db = await connect(config.surreal)
+	await requireCompatibility(db)
+	await runSchema(db)
+
+	new Elysia()
+		.use(buildMcpRouter(db, config))
+		.get('/health', () => ({ status: 'ok' }))
+		.listen({ port: config.mcp.port, hostname: config.mcp.host })
+
+	log.info('MCP server listening', { port: config.mcp.port, host: config.mcp.host })
+}

package/src/mcp/tools.ts

@@ -0,0 +1,100 @@
+// src/mcp/tools.ts
+// Each tool: parse input with Zod → call domain fn → return result.
+// No business logic here. SSoT lives in domain modules.
+
+import type { Elysia } from 'elysia'
+import type { Surreal } from 'surrealdb'
+import { z } from 'zod'
+import { consolidate } from '../cognitive/consolidate.ts'
+import { healthReport, vitals } from '../cognitive/health.ts'
+import type { SuemoConfig } from '../config.ts'
+import { goalList, goalResolve, goalSet } from '../goal.ts'
+import { episodeEnd, episodeStart } from '../memory/episode.ts'
+import { query, recall, timeline, wander } from '../memory/read.ts'
+import { believe, invalidate, observe } from '../memory/write.ts'
+import { ObserveInputSchema, QueryInputSchema } from '../types.ts'
+
+export function buildMcpRouter(db: Surreal, config: SuemoConfig) {
+	// Returns an Elysia plugin that adds all /mcp/* routes.
+	// Each route maps 1:1 to a domain function.
+	return (app: Elysia) =>
+		app
+			.post('/mcp/observe', async ({ body }) => observe(db, ObserveInputSchema.parse(body)))
+			.post('/mcp/believe', async ({ body }) => {
+				const p = z.object({ content: z.string(), scope: z.string().optional(), confidence: z.number().optional() })
+					.parse(body)
+				return believe(db, p)
+			})
+			.post('/mcp/invalidate', async ({ body }) => {
+				const p = z.object({ nodeId: z.string(), reason: z.string().optional() }).parse(body)
+				await invalidate(db, p.nodeId, p.reason)
+				return { ok: true }
+			})
+			.post('/mcp/query', async ({ body }) => query(db, QueryInputSchema.parse(body)))
+			.post('/mcp/recall', async ({ body }) => {
+				const p = z.object({ nodeId: z.string() }).parse(body)
+				return recall(db, p.nodeId)
+			})
+			.post('/mcp/wander', async ({ body }) => {
+				const p = z.object({ anchor: z.string().optional(), hops: z.number().optional(), scope: z.string().optional() })
+					.parse(body)
+				return wander(db, {
+					...(p.anchor ? { anchor: p.anchor } : {}),
+					...(p.hops ? { hops: p.hops } : {}),
+					...(p.scope ? { scope: p.scope } : {}),
+				})
+			})
+			.post('/mcp/timeline', async ({ body }) => {
+				const p = z.object({
+					scope: z.string().optional(),
+					from: z.string().optional(),
+					until: z.string().optional(),
+					limit: z.number().optional(),
+				}).parse(body)
+				return timeline(db, {
+					...(p.scope ? { scope: p.scope } : {}),
+					...(p.from ? { from: p.from } : {}),
+					...(p.until ? { until: p.until } : {}),
+					...(p.limit ? { limit: p.limit } : {}),
+				})
+			})
+			.post('/mcp/episode_start', async ({ body }) => {
+				const p = z.object({ sessionId: z.string() }).parse(body)
+				return episodeStart(db, p.sessionId)
+			})
+			.post('/mcp/episode_end', async ({ body }) => {
+				const p = z.object({ sessionId: z.string(), summary: z.string().optional() }).parse(body)
+				return episodeEnd(db, p.sessionId, p.summary)
+			})
+			.post('/mcp/goal_set', async ({ body }) => {
+				const p = z.object({ content: z.string(), scope: z.string().optional(), tags: z.array(z.string()).optional() })
+					.parse(body)
+				return goalSet(db, p.content, {
+					...(p.scope ? { scope: p.scope } : {}),
+					tags: p.tags ?? [],
+				})
+			})
+			.post('/mcp/goal_resolve', async ({ body }) => {
+				const p = z.object({ goalId: z.string() }).parse(body)
+				await goalResolve(db, p.goalId)
+				return { ok: true }
+			})
+			.post('/mcp/goal_list', async ({ body }) => {
+				const p = z.object({ scope: z.string().optional(), includeResolved: z.boolean().optional() }).parse(body)
+				return goalList(db, {
+					...(p.scope ? { scope: p.scope } : {}),
+					includeResolved: p.includeResolved ?? false,
+				})
+			})
+			.get('/mcp/health', async () => healthReport(db))
+			.get('/mcp/vitals', async () => vitals(db))
+			.post('/mcp/consolidate', async ({ body }) => {
+				const p = z.object({ nremOnly: z.boolean().optional() }).parse(body ?? {})
+				return consolidate(db, {
+					nremOnly: p.nremOnly ?? false,
+					nremSimilarityThreshold: config.consolidation.nremSimilarityThreshold,
+					remRelationThreshold: config.consolidation.remRelationThreshold,
+					llm: config.consolidation.llm,
+				})
+			})
+}

package/src/memory/episode.ts

@@ -0,0 +1,66 @@
+import type { Surreal } from 'surrealdb'
+import { getLogger } from '../logger.ts'
+import type { Episode } from '../types.ts'
+
+const log = getLogger(['suemo', 'memory', 'episode'])
+
+export async function episodeStart(
+	db: Surreal,
+	sessionId: string,
+): Promise<Episode> {
+	log.info('episodeStart()', { sessionId })
+	const result = await db.query<[Episode[]]>(
+		`
+    CREATE episode CONTENT {
+      session_id: $sessionId,
+      ended_at:   NONE,
+      summary:    NONE,
+      memory_ids: []
+    }
+  `,
+		{ sessionId },
+	)
+	return result[0]![0]!
+}
+
+export async function episodeEnd(
+	db: Surreal,
+	sessionId: string,
+	summary?: string,
+): Promise<Episode> {
+	log.info('episodeEnd()', { sessionId })
+	const result = await db.query<[Episode[]]>(
+		`
+    UPDATE episode
+    SET ended_at = time::now(),
+        summary  = $summary
+    WHERE session_id = $sessionId
+      AND ended_at   = NONE
+    RETURN AFTER
+  `,
+		{ sessionId, summary: summary ?? null },
+	)
+	const episode = result[0]?.[0]
+	if (!episode) throw new Error(`No open episode found for session: ${sessionId}`)
+	return episode
+}
+
+/**
+ * Attach a memory node to the current open episode for a session.
+ * Called internally from observe() when a session context is active.
+ */
+export async function attachToEpisode(
+	db: Surreal,
+	sessionId: string,
+	memoryId: string,
+): Promise<void> {
+	log.debug('attachToEpisode()', { sessionId, memoryId })
+	await db.query(
+		`
+    UPDATE episode
+    SET memory_ids += [$memoryId]
+    WHERE session_id = $sessionId AND ended_at = NONE
+  `,
+		{ sessionId, memoryId },
+	)
+}

package/src/memory/read.ts

@@ -0,0 +1,223 @@
+import type { Surreal } from 'surrealdb'
+import { getLogger } from '../logger.ts'
+import type { MemoryNode, QueryInput } from '../types.ts'
+import { QueryInputSchema } from '../types.ts'
+
+const log = getLogger(['suemo', 'memory', 'read'])
+
+const ACTIVE_FILTER = '(valid_until = NONE OR valid_until > time::now())'
+
+// ── query() — parallel hybrid retrieval ──────────────────────────────────────
+export async function query(
+	db: Surreal,
+	rawInput: QueryInput,
+): Promise<MemoryNode[]> {
+	const input = QueryInputSchema.parse(rawInput)
+	log.info('query()', { input: input.input, strategies: input.strategies, topK: input.topK })
+
+	const weights = { vector: 0.5, bm25: 0.25, graph: 0.15, temporal: 0.1 } // from config ideally
+
+	const topK = input.topK ?? 5
+	const strategies = input.strategies ?? ['vector', 'bm25', 'graph']
+	const candidateK = topK * 4 // over-fetch before reranking
+	const activeFilter = input.activeOnly ? ACTIVE_FILTER : 'true'
+	const scopeFilter = '($scope = NONE OR scope = $scope)'
+	const kindFilter = '($kinds = NONE OR kind INSIDE $kinds)'
+
+	const params = {
+		queryText: input.input,
+		scope: input.scope ?? null,
+		kinds: input.kind ?? null,
+		topK: input.topK,
+		candidateK,
+	}
+
+	const promises: Promise<MemoryNode[]>[] = []
+
+	// ── Strategy A: RRF — vector + BM25 combined (one SurrealDB round trip) ──
+	if (strategies.includes('vector') || strategies.includes('bm25')) {
+		promises.push(
+			db.query<[MemoryNode[]]>(
+				`
+      LET $vec = fn::embed($queryText);
+      SELECT *,
+        (
+          search::score(1) * ${weights.bm25} +
+          vector::similarity::cosine(embedding, $vec) * ${weights.vector}
+        ) AS _score
+      FROM memory
+      WHERE content @1@ $queryText
+        AND embedding <|$candidateK, 40|> $vec
+        AND ${activeFilter}
+        AND ${scopeFilter}
+        AND ${kindFilter}
+      ORDER BY _score DESC
+      LIMIT $candidateK
+    `,
+				params,
+			).then((r) => r[0] ?? []),
+		)
+	}
+
+	// ── Strategy B: Graph spreading activation ───────────────────────────────
+	if (strategies.includes('graph')) {
+		// First get anchor IDs from a quick vector probe, then fan out via graph
+		promises.push(
+			db.query<[MemoryNode[]]>(
+				`
+      LET $vec = fn::embed($queryText);
+      LET $anchors = (
+        SELECT id FROM memory
+        WHERE ${activeFilter}
+        ORDER BY embedding <|5, 20|> $vec
+        LIMIT 5
+      ).id;
+      SELECT *,
+        math::mean(<-relates_to[WHERE valid_until = NONE OR valid_until > time::now()].strength) AS _score
+      FROM memory
+      WHERE id INSIDE (
+        SELECT ->relates_to[WHERE strength > 0.3 AND (valid_until = NONE OR valid_until > time::now())]->memory.id
+        FROM $anchors
+      )
+      AND ${activeFilter}
+      AND ${scopeFilter}
+      ORDER BY _score DESC
+      LIMIT $candidateK
+    `,
+				params,
+			).then((r) => r[0] ?? []),
+		)
+	}
+
+	const resultSets = await Promise.all(promises)
+
+	// ── Merge and rerank by deduplicated ID ──────────────────────────────────
+	const seen = new Map<string, MemoryNode & { _score?: number }>()
+	for (const set of resultSets) {
+		for (const node of set) {
+			const existing = seen.get(node.id)
+			if (!existing) {
+				seen.set(node.id, node)
+			} else {
+				// Boost score if the node appears in multiple strategies
+				;(existing as Record<string, unknown>)['_score'] =
+					((existing as Record<string, unknown>)['_score'] as number ?? 0)
+					+ ((node as Record<string, unknown>)['_score'] as number ?? 0)
+			}
+		}
+	}
+
+	const merged = [...seen.values()]
+		.sort((a, b) =>
+			((b as Record<string, unknown>)['_score'] as number ?? 0)
+			- ((a as Record<string, unknown>)['_score'] as number ?? 0)
+		)
+		.slice(0, input.topK)
+		.map(({ ...rest }) => {
+			delete (rest as Record<string, unknown>)['_score']
+			return rest as MemoryNode
+		})
+
+	log.info('query() returned', { count: merged.length })
+	return merged
+}
+
+// ── recall() — single node + FSRS tick ───────────────────────────────────────
+export async function recall(
+	db: Surreal,
+	nodeId: string,
+): Promise<{ node: MemoryNode; neighbors: MemoryNode[] }> {
+	log.info('recall()', { nodeId })
+
+	const [nodeResult, neighborResult] = await Promise.all([
+		db.query<[MemoryNode[]]>('SELECT * FROM $id', { id: nodeId }),
+		db.query<[MemoryNode[]]>(
+			`
+      SELECT * FROM memory
+      WHERE id INSIDE (
+        SELECT ->relates_to[WHERE valid_until = NONE OR valid_until > time::now()]->memory.id
+        FROM $id
+      )
+      LIMIT 10
+    `,
+			{ id: nodeId },
+		),
+	])
+
+	const node = nodeResult[0]?.[0]
+	if (!node) throw new Error(`Memory node not found: ${nodeId}`)
+
+	// FSRS tick — simplified next review interval
+	await db.query(
+		`
+    UPDATE $id SET
+      fsrs_next_review = time::now() + 1d,
+      updated_at       = time::now()
+  `,
+		{ id: nodeId },
+	)
+
+	return { node, neighbors: neighborResult[0] ?? [] }
+}
+
+// ── wander() — spreading activation walk ─────────────────────────────────────
+export async function wander(
+	db: Surreal,
+	opts: { anchor?: string; hops?: number; scope?: string },
+): Promise<MemoryNode[]> {
+	// const _hops = opts.hops ?? 3
+	log.info('wander()', opts)
+
+	// If no anchor, pick a random high-salience active node
+	const anchorId = opts.anchor ?? await db.query<[{ id: string }[]]>(
+		`
+    SELECT id FROM memory
+    WHERE ${ACTIVE_FILTER} AND ($scope = NONE OR scope = $scope)
+    ORDER BY salience * rand() DESC
+    LIMIT 1
+  `,
+		{ scope: opts.scope ?? null },
+	).then((r) => r[0]?.[0]?.id)
+
+	if (!anchorId) return []
+
+	// Walk hops: follow relates_to edges, weight by strength
+	return db.query<[MemoryNode[]]>(
+		`
+    SELECT * FROM memory
+    WHERE id INSIDE (
+      SELECT ->relates_to[WHERE strength > 0.3]->memory
+              ->relates_to[WHERE strength > 0.3]->memory.id
+      FROM $anchor
+    )
+    AND ${ACTIVE_FILTER}
+    LIMIT 20
+  `,
+		{ anchor: anchorId },
+	).then((r) => r[0] ?? [])
+}
+
+// ── timeline() ───────────────────────────────────────────────────────────────
+export async function timeline(
+	db: Surreal,
+	opts: { scope?: string; from?: string; until?: string; limit?: number },
+): Promise<MemoryNode[]> {
+	log.info('timeline()', opts)
+	return db.query<[MemoryNode[]]>(
+		`
+    SELECT * FROM memory
+    WHERE (valid_until = NONE OR valid_until > time::now())
+      AND ($scope = NONE OR scope = $scope)
+      AND ($from  = NONE OR created_at >= <datetime>$from)
+      AND ($until = NONE OR created_at <= <datetime>$until)
+    ORDER BY created_at DESC
+    LIMIT $limit
+  `,
+		{
+			scope: opts.scope ?? null,
+			from: opts.from ?? null,
+			until: opts.until ?? null,
+			limit: opts.limit ?? 50,
+		},
+	).then((r) => r[0] ?? [])
+}

package/src/memory/write.ts

@@ -0,0 +1,134 @@
+import type { Surreal } from 'surrealdb'
+import { detectContradiction } from '../cognitive/contradiction.ts'
+import { getLogger } from '../logger.ts'
+import type { MemoryNode, ObserveInput } from '../types.ts'
+import { ObserveInputSchema } from '../types.ts'
+
+const log = getLogger(['suemo', 'memory', 'write'])
+
+// ── observe() ─────────────────────────────────────────────────────────────────
+export async function observe(
+	db: Surreal,
+	rawInput: ObserveInput,
+): Promise<MemoryNode> {
+	const input = ObserveInputSchema.parse(rawInput)
+	log.info('observe()', { kind: input.kind, scope: input.scope, contentPreview: input.content.slice(0, 60) })
+
+	// 1. Get embedding — fn::embed() runs server-side
+	// We embed inside the CREATE query; the embedding field is set by UPSERT logic.
+	// We first check for a near-duplicate before inserting.
+
+	// 2. Dedup probe: ANN search for cosine similarity > 0.97
+	const dedupResult = await db.query<[{ id: string; score: number }[]]>(
+		`
+    LET $vec = fn::embed($content);
+    SELECT id, vector::similarity::cosine(embedding, $vec) AS score
+    FROM memory
+    WHERE (valid_until = NONE OR valid_until > time::now())
+    ORDER BY embedding <|1, 20|> $vec
+    LIMIT 1
+  `,
+		{ content: input.content },
+	)
+
+	const topHit = dedupResult[0]?.[0]
+	if (topHit && topHit.score > 0.97) {
+		log.debug('Near-duplicate detected — merging tags, updating updated_at', {
+			existingId: topHit.id,
+			score: topHit.score,
+		})
+		const updated = await db.query<[MemoryNode[]]>(
+			`
+      UPDATE $id SET
+        tags += $tags,
+        updated_at = time::now()
+    `,
+			{ id: topHit.id, tags: input.tags },
+		)
+		return updated[0]![0]!
+	}
+
+	// 3. Create new node with server-side embedding
+	const created = await db.query<[MemoryNode[]]>(
+		`
+    CREATE memory CONTENT {
+      kind:       $kind,
+      content:    $content,
+      summary:    NONE,
+      tags:       $tags,
+      scope:      $scope,
+      embedding:  fn::embed($content),
+      confidence: $confidence,
+      salience:   0.5,
+      source:     $source,
+      consolidated: false,
+      consolidated_into: NONE,
+      fsrs_stability:    NONE,
+      fsrs_difficulty:   NONE,
+      fsrs_next_review:  NONE
+    }
+  `,
+		{
+			kind: input.kind,
+			content: input.content,
+			tags: input.tags,
+			scope: input.scope ?? null,
+			confidence: input.confidence,
+			source: input.source ?? null,
+		},
+	)
+
+	const node = created[0]![0]!
+	log.info('observe() created', { id: node.id })
+	return node
+}
+
+// ── believe() ─────────────────────────────────────────────────────────────────
+// Calls observe(), then runs contradiction detection on existing beliefs.
+// If a contradiction is found, the old belief is invalidated automatically.
+export async function believe(
+	db: Surreal,
+	input: Omit<ObserveInput, 'kind'>,
+): Promise<{ node: MemoryNode; contradicted?: MemoryNode }> {
+	log.info('believe()', { scope: input.scope })
+
+	const node = await observe(db, { ...input, kind: 'belief' })
+
+	const contradicted = await detectContradiction(db, node)
+	if (contradicted) {
+		log.info('Contradiction detected — invalidating old belief', { old: contradicted.id, new: node.id })
+		await invalidate(db, contradicted.id, 'contradicted by ' + node.id)
+		// Create a contradicts relation
+		await db.query(
+			`
+      RELATE $new->relates_to->$old CONTENT {
+        kind:     'contradicts',
+        strength: 0.9
+      }
+    `,
+			{ new: node.id, old: contradicted.id },
+		)
+	}
+
+	return { node, ...(contradicted ? { contradicted } : {}) }
+}
+
+// ── invalidate() ──────────────────────────────────────────────────────────────
+// Sets valid_until = now() on the target node. Never deletes.
+// Called by: believe() on contradiction, goal_resolve(), explicit CLI/MCP call.
+// Agents supply the node ID, never a timestamp.
+export async function invalidate(
+	db: Surreal,
+	nodeId: string,
+	reason?: string,
+): Promise<void> {
+	log.info('invalidate()', { nodeId, reason })
+	await db.query(
+		`
+    UPDATE $id SET
+      valid_until = time::now(),
+      updated_at  = time::now()
+  `,
+		{ id: nodeId },
+	)
+}