escribano 0.4.5 → 0.5.0

package/dist/adapters/storage.adapter.js

@@ -0,0 +1,81 @@
+/**
+ * Escribano - Storage Adapter
+ *
+ * Saves and loads sessions from filesystem
+ */
+import { mkdir, readdir, readFile, writeFile } from 'node:fs/promises';
+import os from 'node:os';
+import { join } from 'node:path';
+const SESSIONS_DIR = join(os.homedir(), '.escribano', 'sessions');
+export function createStorageService() {
+    return {
+        saveSession,
+        loadSession,
+        listSessions,
+        saveArtifact,
+        loadArtifacts,
+    };
+}
+async function ensureSessionsDir() {
+    await mkdir(SESSIONS_DIR, { recursive: true });
+}
+async function saveSession(session) {
+    await ensureSessionsDir();
+    const sessionPath = join(SESSIONS_DIR, `${session.id}.json`);
+    await writeFile(sessionPath, JSON.stringify(session, null, 2), 'utf-8');
+}
+async function loadSession(sessionId) {
+    await ensureSessionsDir();
+    const sessionPath = join(SESSIONS_DIR, `${sessionId}.json`);
+    try {
+        const content = await readFile(sessionPath, 'utf-8');
+        return JSON.parse(content);
+    }
+    catch {
+        return null;
+    }
+}
+async function listSessions() {
+    await ensureSessionsDir();
+    const files = await readdir(SESSIONS_DIR);
+    const jsonFiles = files.filter((file) => file.endsWith('.json'));
+    const sessions = [];
+    for (const file of jsonFiles) {
+        const content = await readFile(join(SESSIONS_DIR, file), 'utf-8');
+        sessions.push(JSON.parse(content));
+    }
+    return sessions;
+}
+async function saveArtifact(sessionId, artifact) {
+    const artifactsDir = join(SESSIONS_DIR, sessionId, 'artifacts');
+    await mkdir(artifactsDir, { recursive: true });
+    const timestamp = new Date().toISOString().replace(/:/g, '-').split('.')[0];
+    const filename = `${artifact.type}-${timestamp}.${artifact.format}`;
+    const artifactPath = join(artifactsDir, filename);
+    await writeFile(artifactPath, artifact.content, 'utf-8');
+}
+async function loadArtifacts(sessionId) {
+    const artifactsDir = join(SESSIONS_DIR, sessionId, 'artifacts');
+    try {
+        const files = await readdir(artifactsDir);
+        const artifacts = [];
+        for (const file of files) {
+            const content = await readFile(join(artifactsDir, file), 'utf-8');
+            const match = file.match(/^(\w+)-(.+)\.md$/);
+            if (!match)
+                continue;
+            const [, type] = match;
+            artifacts.push({
+                id: `${sessionId}-${file.replace('.md', '')}`,
+                type: type,
+                content,
+                format: 'markdown',
+                createdAt: new Date(),
+            });
+        }
+        return artifacts;
+    }
+    catch {
+        return [];
+    }
+}

package/dist/adapters/whisper.adapter.js

@@ -0,0 +1,168 @@
+/**
+ * Whisper Adapter
+ *
+ * Transcribes audio using whisper.cpp or OpenAI's whisper CLI.
+ * Shells out to the whisper binary for simplicity.
+ *
+ * Prerequisites:
+ * - whisper.cpp installed: brew install whisper-cpp
+ * - ffmpeg installed: brew install ffmpeg (for audio format conversion)
+ * - Or Python whisper: pip install openai-whisper
+ */
+import { exec } from 'node:child_process';
+import { readFile, unlink } from 'node:fs/promises';
+import { promisify } from 'node:util';
+const execAsync = promisify(exec);
+async function convertToWavIfNeeded(audioPath) {
+    const ext = audioPath.toLowerCase().split('.').pop();
+    if (['wav', 'flac', 'mp3'].includes(ext || '')) {
+        return audioPath;
+    }
+    const outputPath = `${audioPath}.converted.wav`;
+    try {
+        console.log(`Converting ${audioPath} to WAV format...`);
+        await execAsync(`ffmpeg -i "${audioPath}" -f wav -ar 16000 -ac 1 "${outputPath}" -y`, { timeout: 10 * 60 * 1000 });
+        console.log(`Conversion complete: ${outputPath}`);
+        return outputPath;
+    }
+    catch (error) {
+        console.error(`Audio conversion failed for ${audioPath}`);
+        throw new Error(`Failed to convert audio to WAV: ${error.message}`);
+    }
+}
+/**
+ * Creates a TranscriptionService that uses whisper CLI
+ */
+export function createWhisperTranscriber(config = {}) {
+    const resolvedConfig = {
+        binaryPath: config.binaryPath ?? 'whisper-cpp',
+        model: config.model ?? 'base',
+        outputFormat: config.outputFormat ?? 'json',
+        language: config.language,
+    };
+    return {
+        transcribe: (audioPath) => transcribeWithWhisper(audioPath, resolvedConfig),
+    };
+}
+/**
+ * Transcribe audio file using whisper CLI
+ */
+async function transcribeWithWhisper(audioPath, config) {
+    const audioToProcess = await convertToWavIfNeeded(audioPath);
+    const args = [
+        `-m ${config.model}`,
+        `-f "${audioToProcess}"`,
+        '-oj', // Output JSON
+        config.language ? `-l ${config.language}` : '',
+    ].filter(Boolean);
+    const command = `${config.binaryPath} ${args.join(' ')}`;
+    try {
+        const { stdout, stderr } = await execAsync(command, {
+            cwd: config.cwd,
+            maxBuffer: 50 * 1024 * 1024, // 50MB buffer for large transcripts
+            timeout: 10 * 60 * 1000, // 10 minute timeout
+        });
+        const hasError = stderr.includes('error:') ||
+            stderr.includes('Error:') ||
+            stderr.includes('failed to');
+        if (hasError) {
+            if (audioToProcess !== audioPath) {
+                await unlink(audioToProcess).catch(() => { });
+            }
+            throw new Error(`Whisper transcription failed:\n${stderr}`);
+        }
+        // whisper-cpp outputs JSON to a file named <input>.json
+        const jsonOutputPath = `${audioToProcess}.json`;
+        try {
+            const jsonContent = await readFile(jsonOutputPath, 'utf-8');
+            const whisperOutput = JSON.parse(jsonContent);
+            // Clean up the temp JSON file and converted audio
+            await unlink(jsonOutputPath).catch(() => { });
+            if (audioToProcess !== audioPath) {
+                await unlink(audioToProcess).catch(() => { });
+            }
+            return parseWhisperOutput(whisperOutput);
+        }
+        catch {
+            // Fallback: try to parse stdout as the transcript
+            return parseWhisperStdout(stdout);
+        }
+    }
+    catch (error) {
+        if (audioToProcess && audioToProcess !== audioPath) {
+            await unlink(audioToProcess).catch(() => { });
+        }
+        throw new Error(`Whisper transcription failed: ${error.message}`);
+    }
+}
+/**
+ * Parse whisper.cpp JSON output into our Transcript format
+ */
+function parseWhisperOutput(output) {
+    const segments = output.transcription.map((seg, index) => ({
+        id: `seg-${index}`,
+        start: seg.offsets.from / 1000, // Convert ms to seconds
+        end: seg.offsets.to / 1000,
+        text: seg.text.trim(),
+        speaker: null,
+    }));
+    const fullText = segments.map((s) => s.text).join(' ');
+    const duration = segments.length > 0 ? segments[segments.length - 1].end : 0;
+    return {
+        fullText,
+        segments,
+        language: 'en', // whisper.cpp doesn't always report language in JSON
+        duration,
+    };
+}
+/**
+ * Fallback: parse whisper stdout (plain text with timestamps)
+ */
+function parseWhisperStdout(stdout) {
+    // Example format: "[00:00:00.000 --> 00:00:05.000] Hello world"
+    const lines = stdout.split('\n').filter((l) => l.trim());
+    const segments = [];
+    const timestampRegex = /\[(\d{2}:\d{2}:\d{2}\.\d{3})\s*-->\s*(\d{2}:\d{2}:\d{2}\.\d{3})\]\s*(.*)/;
+    for (const line of lines) {
+        const match = line.match(timestampRegex);
+        if (match) {
+            const [, startStr, endStr, text] = match;
+            segments.push({
+                id: `seg-${segments.length}`,
+                start: parseTimestamp(startStr),
+                end: parseTimestamp(endStr),
+                text: text.trim(),
+                speaker: null,
+            });
+        }
+    }
+    // If no timestamps found, treat entire output as single segment
+    if (segments.length === 0 && stdout.trim()) {
+        segments.push({
+            id: 'seg-0',
+            start: 0,
+            end: 0,
+            text: stdout.trim(),
+            speaker: null,
+        });
+    }
+    const fullText = segments.map((s) => s.text).join(' ');
+    const duration = segments.length > 0 ? segments[segments.length - 1].end : 0;
+    return {
+        fullText,
+        segments,
+        language: 'en',
+        duration,
+    };
+}
+/**
+ * Parse timestamp string "00:00:00.000" to seconds
+ */
+function parseTimestamp(timestamp) {
+    const [hours, minutes, rest] = timestamp.split(':');
+    const [seconds, ms] = rest.split('.');
+    return (parseInt(hours, 10) * 3600 +
+        parseInt(minutes, 10) * 60 +
+        parseInt(seconds, 10) +
+        parseInt(ms, 10) / 1000);
+}

package/dist/batch-context.js

@@ -29,7 +29,7 @@ import { createDefaultConfig, loadConfig, logConfig } from './config.js';
 import { getDbPath, getRepositories } from './db/index.js';
 import { log, setResourceTracker, step, withPipeline, } from './pipeline/context.js';
 import { ResourceTracker, setupStatsObserver, } from './stats/index.js';
-import { formatModelSelection, selectBestLLMModel, } from './utils/model-detector.js';
+import { formatModelSelection, selectBestLLMModel, selectBestMLXModel, } from './utils/model-detector.js';
 const MODELS_DIR = path.join(homedir(), '.escribano', 'models');
 const MODEL_FILE = 'ggml-large-v3.bin';
 const MODEL_PATH = path.join(MODELS_DIR, MODEL_FILE);
@@ -50,15 +50,24 @@ export async function initializeSystem() {
     console.log('');
     // Setup stats observer to capture pipeline events
     setupStatsObserver(repos.stats);
-    // Detect best LLM model
-    const modelSelection = await selectBestLLMModel();
-    console.log(formatModelSelection(modelSelection));
-    console.log('');
-    // Initialize adapters ONCE (config is now used by adapters)
-    console.log('[VLM] Using MLX-VLM for image processing');
-    const vlm = createMlxIntelligenceService(config);
-    console.log('[LLM] Using Ollama for text generation');
-    const llm = createOllamaIntelligenceService(config);
+    // Detect best LLM model based on configured backend
+    let llm;
+    let mlxService = null;
+    if (config.llmBackend === 'mlx') {
+        console.log('[LLM] Using MLX for text generation');
+        const mlxModelSelection = await selectBestMLXModel();
+        console.log(formatModelSelection(mlxModelSelection));
+        console.log('');
+        mlxService = createMlxIntelligenceService();
+        llm = mlxService;
+    }
+    else {
+        console.log('[LLM] Using Ollama for text generation');
+        const ollamaModelSelection = await selectBestLLMModel();
+        console.log(formatModelSelection(ollamaModelSelection));
+        console.log('');
+        llm = createOllamaIntelligenceService();
+    }
     const video = createFfmpegVideoService();
     const preprocessor = createSileroPreprocessor();
     const transcription = createWhisperTranscriptionService({
@@ -67,32 +76,42 @@ export async function initializeSystem() {
         cwd: MODELS_DIR,
         outputFormat: 'json',
     });
-    // Setup resource tracking
     const resourceTracker = new ResourceTracker();
-    resourceTracker.register(vlm);
     resourceTracker.register(video);
     resourceTracker.register(preprocessor);
-    // Ollama runs as a daemon - special case
-    resourceTracker.register({
-        getResourceName: () => 'ollama',
-        getPid: () => {
-            try {
-                const output = execSync('pgrep -f "ollama serve"').toString().trim();
-                const pid = parseInt(output.split('\n')[0] ?? '0', 10);
-                return pid > 0 ? pid : null;
-            }
-            catch {
-                return null;
-            }
-        },
-    });
+    if (config.llmBackend === 'ollama') {
+        resourceTracker.register({
+            getResourceName: () => 'ollama',
+            getPid: () => {
+                try {
+                    const output = execSync('pgrep -f "ollama serve"').toString().trim();
+                    const pid = parseInt(output.split('\n')[0] ?? '0', 10);
+                    return pid > 0 ? pid : null;
+                }
+                catch {
+                    return null;
+                }
+            },
+        });
+    }
+    else if (mlxService) {
+        resourceTracker.register(mlxService);
+    }
     setResourceTracker(resourceTracker);
     const outlineConfig = getOutlineConfig();
     return {
         repos,
-        adapters: { vlm, llm, video, preprocessor, transcription },
+        adapters: {
+            vlm: null,
+            llm,
+            video,
+            preprocessor,
+            transcription,
+        },
         resourceTracker,
         outlineConfig,
+        config,
+        llmBackend: config.llmBackend,
     };
 }
 /**
@@ -105,7 +124,7 @@ export async function processVideo(videoPath, ctx, options = {}) {
     const startTime = Date.now();
     const { force = false, skipSummary = false, micAudioPath, systemAudioPath, format = 'card', includePersonal = false, copyToClipboard = false, printToStdout = false, } = options;
     const { repos, adapters, outlineConfig } = ctx;
-    const { vlm, llm, video, preprocessor, transcription } = adapters;
+    const { llm, video, preprocessor, transcription } = adapters;
     // Load unified config for lifecycle management
     const config = loadConfig();
     try {
@@ -157,28 +176,60 @@ export async function processVideo(videoPath, ctx, options = {}) {
         const skipProcessing = dbRec &&
             (dbRec.status === 'processed' || dbRec.status === 'published') &&
             !force;
+        // Create VLM adapter lazily (only if needed)
+        let vlm = null;
+        if (!skipProcessing) {
+            // Reuse the same MLX service instance for VLM (unified adapter handles both)
+            // Check if LLM is MLX backend - if so, it's already a unified VLM+LLM service
+            if (ctx.config.llmBackend === 'mlx' && llm) {
+                vlm = llm;
+            }
+            else {
+                console.log('[VLM] Initializing MLX-VLM for frame analysis...');
+                vlm = createMlxIntelligenceService();
+                ctx.resourceTracker.register(vlm);
+            }
+            ctx.adapters.vlm = vlm;
+        }
         if (!skipProcessing) {
             const runType = force
                 ? 'force'
                 : dbRec?.processing_step
                     ? 'resume'
                     : 'initial';
-            const runMetadata = collectRunMetadata(ctx.resourceTracker);
+            const runMetadata = collectRunMetadata(ctx.resourceTracker, ctx.config);
             await withPipeline(recording.id, runType, runMetadata, async () => {
+                if (!vlm)
+                    throw new Error('[VLM] Internal error: VLM adapter expected but not initialized');
                 await processRecordingV3(recording.id, repos, { preprocessor, transcription, video, intelligence: vlm }, { force });
             });
-            // Free VLM memory after processing (good hygiene for all RAM tiers)
-            console.log('[VLM] Freeing VLM memory...');
-            cleanupMlxBridge();
+            // Clean up VLM bridge after processing to free memory for LLM
+            if (vlm) {
+                console.log('[VLM] Unloading VLM model to free memory...');
+                await vlm.unloadVlm?.();
+                // Note: We don't kill the bridge process here, just unload the model
+                // The bridge process will be reused for subsequent recordings if needed
+            }
         }
         // Generate artifact and publish (unless skipped), tracked as a pipeline run
         let artifact = null;
         let outlineUrl;
         if (!skipSummary) {
-            const artifactRunMetadata = collectRunMetadata(ctx.resourceTracker);
+            // Guard: Ensure VLM is unloaded before LLM generation to prevent memory contention
+            if (ctx.adapters.vlm) {
+                console.log('[VLM] Warning: VLM bridge still loaded during artifact generation');
+                console.log('[VLM] Unloading to prevent memory contention with LLM...');
+                if ('unloadVlm' in ctx.adapters.vlm && ctx.adapters.vlm.unloadVlm) {
+                    await ctx.adapters.vlm.unloadVlm();
+                }
+                ctx.adapters.vlm = null;
+            }
+            const artifactRunMetadata = collectRunMetadata(ctx.resourceTracker, ctx.config);
             const pipelineResult = await withPipeline(recording.id, 'artifact', artifactRunMetadata, async () => {
                 console.log(`\nGenerating ${format} artifact...`);
                 let generatedArtifact;
+                // LLM model loading is handled internally by generateText()
+                // No explicit load/unload calls needed here
                 if (format === 'narrative') {
                     // Route narrative through the corrected path
                     generatedArtifact = await generateSummaryV3(recording.id, repos, llm, {
@@ -301,6 +352,11 @@ export async function processVideo(videoPath, ctx, options = {}) {
                 };
                 await unloadOllamaModel(config.llmModel, intelConfig);
             }
+            else if ('unloadLlm' in ctx.adapters.llm &&
+                ctx.adapters.llm.unloadLlm) {
+                console.log('[LLM] Unloading MLX model to free memory...');
+                await ctx.adapters.llm.unloadLlm();
+            }
         }
         console.log('\n✓ Complete!');
         return {
@@ -345,7 +401,7 @@ function getOutlineConfig() {
 /**
  * Collect metadata about the current run.
  */
-function collectRunMetadata(resourceTracker) {
+function collectRunMetadata(resourceTracker, config) {
     let commitHash = 'unknown';
     try {
         commitHash = execSync('git rev-parse --short HEAD', {
@@ -359,6 +415,7 @@ function collectRunMetadata(resourceTracker) {
         vlm_model: process.env.ESCRIBANO_VLM_MODEL ??
             'mlx-community/Qwen3-VL-2B-Instruct-bf16',
         llm_model: process.env.ESCRIBANO_LLM_MODEL ?? 'auto-detected',
+        llm_backend: config?.llmBackend ?? 'ollama',
         commit_hash: commitHash,
         node_version: process.version,
         platform: process.platform,

package/dist/config.js

@@ -27,12 +27,15 @@ const configSchema = z.object({
     vlmMaxTokens: z.number().int().min(500).max(8000).default(2000),
     // === MODELS ===
     llmModel: z.string().optional(),
+    llmBackend: z.enum(['mlx', 'ollama']).default('mlx'),
+    llmMlxModel: z.string().optional(),
     vlmModel: z.string().default('mlx-community/Qwen3-VL-2B-Instruct-4bit'),
     subjectGroupingModel: z.string().optional(),
     // === DEBUGGING ===
     verbose: z.boolean().default(false),
     debugOllama: z.boolean().default(false),
     debugVlm: z.boolean().default(false),
+    debugLlm: z.boolean().default(false),
     skipLlm: z.boolean().default(false),
     // === ADVANCED ===
     sceneMinInterval: z.number().int().min(1).max(10).default(2),
@@ -72,10 +75,12 @@ const BASE_DEFAULTS = {
     sampleInterval: 10,
     sceneThreshold: 0.4,
     vlmMaxTokens: 2000,
+    llmBackend: 'mlx',
     vlmModel: 'mlx-community/Qwen3-VL-2B-Instruct-4bit',
     verbose: false,
     debugOllama: false,
     debugVlm: false,
+    debugLlm: false,
     skipLlm: false,
     sceneMinInterval: 2,
     sampleGapThreshold: 15,
@@ -103,12 +108,15 @@ ESCRIBANO_SCENE_THRESHOLD=0.4         # Scene detection sensitivity (0.0-1.0)
 ESCRIBANO_VLM_MAX_TOKENS=2000         # Token budget per batch
 
 # === MODELS ===
-# ESCRIBANO_LLM_MODEL=qwen3.5:27b     # Summary generation (auto-detected if not set)
+# ESCRIBANO_LLM_BACKEND=mlx             # LLM backend: 'mlx' (default) or 'ollama'
+# ESCRIBANO_LLM_MODEL=qwen3.5:27b       # Ollama model (only used if llmBackend='ollama')
+# ESCRIBANO_LLM_MLX_MODEL=              # MLX model (only used if llmBackend='mlx', auto-detected if not set)
 ESCRIBANO_VLM_MODEL=mlx-community/Qwen3-VL-2B-Instruct-4bit
 
 # === DEBUGGING ===
 ESCRIBANO_VERBOSE=false               # Enable verbose logging
 ESCRIBANO_DEBUG_VLM=false             # Debug VLM processing
+ESCRIBANO_DEBUG_LLM=false             # Log all LLM calls to debug table
 
 # === ADVANCED ===
 ESCRIBANO_SCENE_MIN_INTERVAL=2
@@ -199,12 +207,15 @@ export function loadConfig() {
         vlmMaxTokens: parseEnvNumberWithSource('ESCRIBANO_VLM_MAX_TOKENS', BASE_DEFAULTS.vlmMaxTokens, sources, 'vlmMaxTokens'),
         // === MODELS ===
         llmModel: parseEnvStringWithSource('ESCRIBANO_LLM_MODEL', undefined, sources, 'llmModel'),
+        llmBackend: (parseEnvStringWithSource('ESCRIBANO_LLM_BACKEND', BASE_DEFAULTS.llmBackend, sources, 'llmBackend') ?? 'mlx'),
+        llmMlxModel: parseEnvStringWithSource('ESCRIBANO_LLM_MLX_MODEL', undefined, sources, 'llmMlxModel'),
         vlmModel: parseEnvStringWithSource('ESCRIBANO_VLM_MODEL', BASE_DEFAULTS.vlmModel, sources, 'vlmModel'),
         subjectGroupingModel: parseEnvStringWithSource('ESCRIBANO_SUBJECT_GROUPING_MODEL', undefined, sources, 'subjectGroupingModel'),
         // === DEBUGGING ===
         verbose: parseEnvBooleanWithSource('ESCRIBANO_VERBOSE', BASE_DEFAULTS.verbose, sources, 'verbose'),
         debugOllama: parseEnvBooleanWithSource('ESCRIBANO_DEBUG_OLLAMA', BASE_DEFAULTS.debugOllama, sources, 'debugOllama'),
         debugVlm: parseEnvBooleanWithSource('ESCRIBANO_DEBUG_VLM', BASE_DEFAULTS.debugVlm, sources, 'debugVlm'),
+        debugLlm: parseEnvBooleanWithSource('ESCRIBANO_DEBUG_LLM', BASE_DEFAULTS.debugLlm, sources, 'debugLlm'),
         skipLlm: parseEnvBooleanWithSource('ESCRIBANO_SKIP_LLM', BASE_DEFAULTS.skipLlm, sources, 'skipLlm'),
         // === ADVANCED ===
         sceneMinInterval: parseEnvNumberWithSource('ESCRIBANO_SCENE_MIN_INTERVAL', BASE_DEFAULTS.sceneMinInterval, sources, 'sceneMinInterval'),

package/dist/db/repositories/subject.sqlite.js

@@ -7,7 +7,7 @@ export function createSqliteSubjectRepository(db) {
         findById: db.prepare('SELECT * FROM subjects WHERE id = ?'),
         findByRecording: db.prepare('SELECT * FROM subjects WHERE recording_id = ? ORDER BY created_at ASC'),
         insert: db.prepare(`
-      INSERT INTO subjects (id, recording_id, label, is_personal, duration, activity_breakdown, metadata, created_at)
+      INSERT OR IGNORE INTO subjects (id, recording_id, label, is_personal, duration, activity_breakdown, metadata, created_at)
       VALUES (?, ?, ?, ?, ?, ?, ?, ?)
     `),
         insertLink: db.prepare(`

package/dist/domain/context.js

@@ -0,0 +1,97 @@
+/**
+ * Escribano - Context Extraction Domain Module
+ */
+export const Context = {
+    /**
+     * Extract semantic contexts from raw OCR text using regex patterns.
+     * This is a fast-path optimization for common applications and URLs.
+     */
+    extractFromOCR: (ocrText) => {
+        const contexts = [];
+        const text = ocrText.trim();
+        if (!text)
+            return contexts;
+        // 1. App Detection
+        const apps = [
+            { name: 'Ghostty', pattern: /Ghostty/i },
+            { name: 'VS Code', pattern: /Visual Studio Code|VS Code/i },
+            { name: 'Chrome', pattern: /Google Chrome/i },
+            { name: 'Arc', pattern: /Arc/i },
+            { name: 'Cursor', pattern: /Cursor/i },
+            { name: 'TablePlus', pattern: /TablePlus/i },
+            { name: 'Slack', pattern: /Slack/i },
+            { name: 'Spotify', pattern: /Spotify/i },
+            { name: 'YouTube Music', pattern: /YouTube Music/i },
+        ];
+        for (const app of apps) {
+            if (app.pattern.test(text)) {
+                contexts.push({
+                    type: 'app',
+                    value: app.name,
+                    confidence: 0.9,
+                });
+            }
+        }
+        // 2. URL Detection
+        const urlPattern = /https?:\/\/[^\s]+/g;
+        const urls = text.match(urlPattern);
+        if (urls) {
+            for (const url of urls) {
+                contexts.push({
+                    type: 'url',
+                    value: url.replace(/[,.)}>]$/, ''), // Clean trailing punctuation
+                    confidence: 1.0,
+                });
+            }
+        }
+        // 3. Domain Detection (Specific known domains)
+        const domains = [
+            { name: 'github.com', pattern: /github\.com/i },
+            { name: 'linkedin.com', pattern: /linkedin\.com/i },
+            { name: 'stackoverflow.com', pattern: /stackoverflow\.com/i },
+            { name: 'docs.rs', pattern: /docs\.rs/i },
+            { name: 'ollama.com', pattern: /ollama\.com/i },
+        ];
+        for (const domain of domains) {
+            if (domain.pattern.test(text)) {
+                // Only add if not already covered by a full URL
+                if (!contexts.some((c) => c.type === 'url' && c.value.includes(domain.name))) {
+                    contexts.push({
+                        type: 'url',
+                        value: domain.name,
+                        confidence: 0.8,
+                    });
+                }
+            }
+        }
+        // 4. File Path Detection
+        const pathPattern = /(?:~\/|\/Users\/)[^\s]+\.(?:ts|js|py|rs|md|go|json|yml|yaml)/g;
+        const paths = text.match(pathPattern);
+        if (paths) {
+            for (const path of paths) {
+                contexts.push({
+                    type: 'file',
+                    value: path,
+                    confidence: 0.9,
+                });
+            }
+        }
+        // TODO: Implement Step 2 - Embedding clustering for topic grouping
+        // This will be used when regex patterns don't yield high-confidence results
+        // or when we want to group related segments together.
+        return contexts;
+    },
+    /**
+     * Aggregate multiple contexts and remove duplicates
+     */
+    unique: (contexts) => {
+        const seen = new Set();
+        return contexts.filter((c) => {
+            const key = `${c.type}:${c.value}`;
+            if (seen.has(key))
+                return false;
+            seen.add(key);
+            return true;
+        });
+    },
+};

package/dist/domain/index.js

@@ -0,0 +1,2 @@
+export * from './observation.js';
+export * from './recording.js';

package/dist/domain/observation.js

@@ -0,0 +1,17 @@
+import { generateId } from '../db/helpers.js';
+/**
+ * Factory for audio observations
+ */
+export function createAudioObservation(params) {
+    return {
+        id: generateId(),
+        recordingId: params.recordingId,
+        type: 'audio',
+        timestamp: params.timestamp,
+        endTimestamp: params.endTimestamp,
+        text: params.text,
+        audioSource: params.audioSource,
+        audioType: 'speech',
+        confidence: params.confidence ?? null,
+    };
+}