@psiclawops/hypermem 0.5.0 → 0.5.2

package/dist/metrics-dashboard.js

@@ -0,0 +1,260 @@
+/**
+ * hypermem Metrics Dashboard
+ *
+ * Provides a unified surface for observing system health:
+ * - Memory counts (facts, pages, episodes, vectors)
+ * - Composition performance (avg assembly time, budget utilization)
+ * - Ingestion stats (indexer throughput, promotion rate)
+ * - Embedding stats (cache hit rate, Ollama availability)
+ *
+ * All queries are read-only and safe to call on hot DBs.
+ */
+import { HYPERMEM_COMPAT_VERSION } from './version.js';
+function safeQuery(db, sql, params = []) {
+    try {
+        const stmt = db.prepare(sql);
+        return stmt.get(...params);
+    }
+    catch {
+        return null;
+    }
+}
+function safeQueryAll(db, sql, params = []) {
+    try {
+        const stmt = db.prepare(sql);
+        return stmt.all(...params);
+    }
+    catch {
+        return [];
+    }
+}
+function buildAgentFilter(agentIds) {
+    if (!agentIds || agentIds.length === 0)
+        return { clause: '', params: [] };
+    const placeholders = agentIds.map(() => '?').join(', ');
+    return { clause: `AND agent_id IN (${placeholders})`, params: agentIds };
+}
+/**
+ * Collect fact metrics from the library DB.
+ */
+function collectFactMetrics(libraryDb, opts) {
+    const { clause, params } = buildAgentFilter(opts.agentIds);
+    const cutoff = new Date(Date.now() - 24 * 60 * 60 * 1000).toISOString();
+    const total = safeQuery(libraryDb, `SELECT COUNT(*) AS count FROM facts WHERE 1=1 ${clause}`, params);
+    const recent = safeQuery(libraryDb, `SELECT COUNT(*) AS count FROM facts WHERE created_at > ? ${clause}`, [cutoff, ...params]);
+    const byAgentRows = (opts.includeBreakdowns !== false)
+        ? safeQueryAll(libraryDb, `SELECT agent_id, COUNT(*) AS count FROM facts WHERE 1=1 ${clause} GROUP BY agent_id`, params)
+        : [];
+    return {
+        totalFacts: total?.count ?? 0,
+        byAgent: Object.fromEntries(byAgentRows.map(r => [r.agent_id, r.count])),
+        recentFacts: recent?.count ?? 0,
+    };
+}
+/**
+ * Collect wiki page metrics from the library DB (knowledge table, topic-synthesis domain).
+ */
+function collectWikiMetrics(libraryDb, opts) {
+    const { clause, params } = buildAgentFilter(opts.agentIds);
+    const cutoff = new Date(Date.now() - 24 * 60 * 60 * 1000).toISOString();
+    const total = safeQuery(libraryDb, `SELECT COUNT(*) AS count FROM knowledge WHERE domain = 'topic-synthesis' AND superseded_by IS NULL ${clause}`, params);
+    const recent = safeQuery(libraryDb, `SELECT COUNT(*) AS count FROM knowledge WHERE domain = 'topic-synthesis' AND superseded_by IS NULL AND created_at > ? ${clause}`, [cutoff, ...params]);
+    const oldest = safeQuery(libraryDb, `SELECT created_at FROM knowledge WHERE domain = 'topic-synthesis' AND superseded_by IS NULL ${clause} ORDER BY created_at ASC LIMIT 1`, params);
+    const byAgentRows = (opts.includeBreakdowns !== false)
+        ? safeQueryAll(libraryDb, `SELECT agent_id, COUNT(*) AS count FROM knowledge WHERE domain = 'topic-synthesis' AND superseded_by IS NULL ${clause} GROUP BY agent_id`, params)
+        : [];
+    let oldestPageAgeHours = null;
+    if (oldest?.created_at) {
+        const diffMs = Date.now() - new Date(oldest.created_at).getTime();
+        oldestPageAgeHours = Math.round(diffMs / (1000 * 60 * 60));
+    }
+    return {
+        totalPages: total?.count ?? 0,
+        byAgent: Object.fromEntries(byAgentRows.map(r => [r.agent_id, r.count])),
+        recentPages: recent?.count ?? 0,
+        oldestPageAgeHours,
+    };
+}
+/**
+ * Collect episode metrics from the library DB.
+ */
+function collectEpisodeMetrics(libraryDb, opts) {
+    const { clause, params } = buildAgentFilter(opts.agentIds);
+    const total = safeQuery(libraryDb, `SELECT COUNT(*) AS count FROM episodes WHERE 1=1 ${clause}`, params);
+    const avgSig = safeQuery(libraryDb, `SELECT AVG(significance) AS avg FROM episodes WHERE significance IS NOT NULL ${clause}`, params);
+    const byAgentRows = (opts.includeBreakdowns !== false)
+        ? safeQueryAll(libraryDb, `SELECT agent_id, COUNT(*) AS count FROM episodes WHERE 1=1 ${clause} GROUP BY agent_id`, params)
+        : [];
+    return {
+        totalEpisodes: total?.count ?? 0,
+        byAgent: Object.fromEntries(byAgentRows.map(r => [r.agent_id, r.count])),
+        avgSignificance: avgSig?.avg ?? null,
+    };
+}
+/**
+ * Collect vector index metrics from the library DB.
+ */
+function collectVectorMetrics(libraryDb) {
+    const total = safeQuery(libraryDb, 'SELECT COUNT(*) as cnt FROM vec_index_map');
+    const byTableRows = safeQueryAll(libraryDb, 'SELECT source_table, COUNT(*) as cnt FROM vec_index_map GROUP BY source_table');
+    return {
+        totalVectors: total?.cnt ?? 0,
+        byTable: Object.fromEntries(byTableRows.map(r => [r.source_table, r.cnt])),
+        cacheHitRate: null, // process-lifetime stat, not persisted
+    };
+}
+/**
+ * Collect composition performance metrics from the output_metrics table (main DB).
+ */
+function collectCompositionMetrics(mainDb, opts) {
+    const { clause, params } = buildAgentFilter(opts.agentIds);
+    const agg = safeQuery(mainDb, `SELECT
+       AVG(latency_ms) AS avg_latency,
+       AVG(output_tokens) AS avg_output,
+       AVG(input_tokens) AS avg_input,
+       AVG(cache_read_tokens) AS avg_cache,
+       COUNT(*) AS total
+     FROM output_metrics WHERE 1=1 ${clause.replace(/agent_id/g, 'agent_id')}`, params);
+    // p95: sort latency_ms and pick the 95th percentile row
+    let p95 = null;
+    if ((agg?.total ?? 0) > 0) {
+        const p95Row = safeQuery(mainDb, `SELECT latency_ms FROM output_metrics WHERE latency_ms IS NOT NULL ${clause}
+       ORDER BY latency_ms ASC
+       LIMIT 1 OFFSET MAX(0, CAST(COUNT(*) * 0.95 AS INT) - 1)`, params);
+        // Fallback: approximate p95 with a subquery
+        if (!p95Row) {
+            const p95Approx = safeQuery(mainDb, `SELECT latency_ms FROM output_metrics WHERE latency_ms IS NOT NULL ${clause}
+         ORDER BY latency_ms DESC
+         LIMIT 1 OFFSET (SELECT MAX(0, CAST(COUNT(*) * 0.05 AS INT)) FROM output_metrics WHERE latency_ms IS NOT NULL ${clause})`, [...params, ...params]);
+            p95 = p95Approx?.latency_ms ?? null;
+        }
+        else {
+            p95 = p95Row.latency_ms;
+        }
+    }
+    return {
+        avgAssemblyMs: agg?.avg_latency ? Math.round(agg.avg_latency) : null,
+        p95AssemblyMs: p95 ? Math.round(p95) : null,
+        avgOutputTokens: agg?.avg_output ? Math.round(agg.avg_output) : null,
+        avgInputTokens: agg?.avg_input ? Math.round(agg.avg_input) : null,
+        totalTurns: agg?.total ?? 0,
+        avgCacheReadTokens: agg?.avg_cache ? Math.round(agg.avg_cache) : null,
+    };
+}
+/**
+ * Collect ingestion pipeline metrics from the library DB.
+ */
+function collectIngestionMetrics(libraryDb, opts) {
+    const { clause, params } = buildAgentFilter(opts.agentIds);
+    const facts = safeQuery(libraryDb, `SELECT COUNT(*) AS count FROM facts WHERE 1=1 ${clause}`, params);
+    const episodes = safeQuery(libraryDb, `SELECT COUNT(*) AS count FROM episodes WHERE 1=1 ${clause}`, params);
+    const knowledge = safeQuery(libraryDb, `SELECT COUNT(*) AS count FROM knowledge WHERE superseded_by IS NULL ${clause}`, params);
+    const totalFacts = facts?.count ?? 0;
+    const totalEpisodes = episodes?.count ?? 0;
+    // Noise rejection: approximate from fact vs message ratio if messages available
+    const messages = safeQuery(libraryDb, `SELECT COUNT(*) AS count FROM facts WHERE 1=1 ${clause}`, // placeholder — we'd need message count from main
+    params);
+    return {
+        totalMessagesIndexed: 0, // requires main DB join — surfaced separately
+        totalFactsExtracted: totalFacts,
+        noiseRejectionRate: null, // requires cross-DB join
+        totalEpisodesCreated: totalEpisodes,
+        totalKnowledgePromoted: knowledge?.count ?? 0,
+    };
+}
+/**
+ * Collect system health from both DBs.
+ */
+function collectHealth(mainDb, libraryDb) {
+    let mainSchemaVersion = null;
+    let librarySchemaVersion = null;
+    let mainDbOk = false;
+    let libraryDbOk = false;
+    try {
+        const row = safeQuery(mainDb, 'SELECT schema_version FROM _meta LIMIT 1');
+        mainSchemaVersion = row?.schema_version ?? null;
+        mainDbOk = true;
+    }
+    catch { /* empty */ }
+    try {
+        const row = safeQuery(libraryDb, 'SELECT schema_version FROM _library_meta LIMIT 1');
+        librarySchemaVersion = row?.schema_version ?? null;
+        libraryDbOk = true;
+    }
+    catch { /* empty */ }
+    return {
+        mainDbOk,
+        libraryDbOk,
+        mainSchemaVersion,
+        librarySchemaVersion,
+        packageVersion: HYPERMEM_COMPAT_VERSION,
+        cacheOk: null, // caller must inject cache status
+        snapshotAt: new Date().toISOString(),
+    };
+}
+/**
+ * Collect all metrics in a single pass.
+ * Safe to call on live DBs — all queries are read-only.
+ */
+export async function collectMetrics(mainDb, libraryDb, opts = {}) {
+    return {
+        facts: collectFactMetrics(libraryDb, opts),
+        wiki: collectWikiMetrics(libraryDb, opts),
+        episodes: collectEpisodeMetrics(libraryDb, opts),
+        vectors: collectVectorMetrics(libraryDb),
+        composition: collectCompositionMetrics(mainDb, opts),
+        ingestion: collectIngestionMetrics(libraryDb, opts),
+        health: collectHealth(mainDb, libraryDb),
+    };
+}
+/**
+ * Format metrics as a human-readable summary string.
+ * Suitable for logging or status replies.
+ */
+export function formatMetricsSummary(m) {
+    const lines = [];
+    lines.push(`hypermem ${m.health.packageVersion} — metrics snapshot ${m.health.snapshotAt}`);
+    lines.push('');
+    lines.push('## Memory');
+    lines.push(`  facts:    ${m.facts.totalFacts.toLocaleString()} total, ${m.facts.recentFacts} added last 24h`);
+    lines.push(`  wiki:     ${m.wiki.totalPages} pages, ${m.wiki.recentPages} synthesized last 24h${m.wiki.oldestPageAgeHours !== null ? `, oldest ${m.wiki.oldestPageAgeHours}h` : ''}`);
+    lines.push(`  episodes: ${m.episodes.totalEpisodes.toLocaleString()}${m.episodes.avgSignificance !== null ? `, avg significance ${m.episodes.avgSignificance.toFixed(2)}` : ''}`);
+    lines.push(`  vectors:  ${m.vectors.totalVectors.toLocaleString()} indexed`);
+    if (Object.keys(m.vectors.byTable).length > 0) {
+        for (const [table, count] of Object.entries(m.vectors.byTable)) {
+            lines.push(`    ${table}: ${count.toLocaleString()}`);
+        }
+    }
+    lines.push('');
+    lines.push('## Composition');
+    if (m.composition.totalTurns > 0) {
+        lines.push(`  turns:    ${m.composition.totalTurns.toLocaleString()}`);
+        if (m.composition.avgAssemblyMs !== null)
+            lines.push(`  avg time: ${m.composition.avgAssemblyMs}ms`);
+        if (m.composition.p95AssemblyMs !== null)
+            lines.push(`  p95 time: ${m.composition.p95AssemblyMs}ms`);
+        if (m.composition.avgOutputTokens !== null)
+            lines.push(`  avg out:  ${m.composition.avgOutputTokens} tokens`);
+        if (m.composition.avgInputTokens !== null)
+            lines.push(`  avg in:   ${m.composition.avgInputTokens} tokens`);
+        if (m.composition.avgCacheReadTokens !== null)
+            lines.push(`  cache rd: ${m.composition.avgCacheReadTokens} tokens/turn`);
+    }
+    else {
+        lines.push('  no turn data yet');
+    }
+    lines.push('');
+    lines.push('## Ingestion');
+    lines.push(`  facts extracted:    ${m.ingestion.totalFactsExtracted.toLocaleString()}`);
+    lines.push(`  episodes created:   ${m.ingestion.totalEpisodesCreated.toLocaleString()}`);
+    lines.push(`  knowledge promoted: ${m.ingestion.totalKnowledgePromoted.toLocaleString()}`);
+    lines.push('');
+    lines.push('## Health');
+    lines.push(`  main db:    ${m.health.mainDbOk ? '✅' : '❌'}${m.health.mainSchemaVersion !== null ? ` (schema v${m.health.mainSchemaVersion})` : ''}`);
+    lines.push(`  library db: ${m.health.libraryDbOk ? '✅' : '❌'}${m.health.librarySchemaVersion !== null ? ` (schema v${m.health.librarySchemaVersion})` : ''}`);
+    if (m.health.cacheOk !== null) {
+        lines.push(`  cache:      ${m.health.cacheOk ? '✅' : '❌'}`);
+    }
+    return lines.join('\n');
+}
+//# sourceMappingURL=metrics-dashboard.js.map

package/dist/obsidian-exporter.d.ts

@@ -0,0 +1,57 @@
+/**
+ * obsidian-exporter.ts
+ *
+ * Exports hypermem facts and wiki pages to an Obsidian vault.
+ * Complements obsidian-watcher.ts (import direction).
+ *
+ * Output format:
+ *   - Wiki pages → one .md file per topic, with frontmatter + [[wikilinks]]
+ *   - Facts → grouped by domain into .md files, frontmatter-tagged
+ *   - Index note → _hypermem-index.md with TOC and stats
+ *
+ * Safe to run repeatedly — existing files are overwritten only if content changed.
+ */
+import type { DatabaseSync } from 'node:sqlite';
+export interface ObsidianExportConfig {
+    /** Absolute path to target Obsidian vault directory */
+    vaultPath: string;
+    /** Sub-folder inside vault to write hypermem exports. Default: 'hypermem' */
+    vaultFolder?: string;
+    /** Agent ID to scope export to. If omitted, exports all agents */
+    agentId?: string;
+    /** Include raw facts (not just wiki pages). Default: true */
+    includeFacts?: boolean;
+    /** Include synthesized wiki pages. Default: true */
+    includeWikiPages?: boolean;
+    /** Include an index note. Default: true */
+    includeIndex?: boolean;
+    /** Tag prefix added to all exported notes. Default: 'hypermem' */
+    tagPrefix?: string;
+    /** Skip files whose content hasn't changed. Default: true */
+    skipUnchanged?: boolean;
+}
+export interface ObsidianExportResult {
+    written: number;
+    skipped: number;
+    errors: string[];
+    outputDir: string;
+    files: string[];
+}
+/**
+ * Export hypermem memories to an Obsidian vault.
+ *
+ * @param mainDb - hypermem main DB (facts, episodes)
+ * @param libraryDb - hypermem library DB (knowledge, wiki pages)
+ * @param config - export config
+ * @returns ObsidianExportResult with counts and file list
+ *
+ * @example
+ * const result = await exportToVault(mainDb, libraryDb, {
+ *   vaultPath: '/Users/me/obsidian/my-vault',
+ *   agentId: 'main',
+ *   tagPrefix: 'hypermem',
+ * });
+ * console.log(`Wrote ${result.written} files to ${result.outputDir}`);
+ */
+export declare function exportToVault(mainDb: DatabaseSync, libraryDb: DatabaseSync, config: ObsidianExportConfig): ObsidianExportResult;
+//# sourceMappingURL=obsidian-exporter.d.ts.map

package/dist/obsidian-exporter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"obsidian-exporter.d.ts","sourceRoot":"","sources":["../src/obsidian-exporter.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAKH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAIhD,MAAM,WAAW,oBAAoB;IACnC,uDAAuD;IACvD,SAAS,EAAE,MAAM,CAAC;IAClB,6EAA6E;IAC7E,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,kEAAkE;IAClE,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,6DAA6D;IAC7D,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,oDAAoD;IACpD,gBAAgB,CAAC,EAAE,OAAO,CAAC;IAC3B,2CAA2C;IAC3C,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,kEAAkE;IAClE,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,6DAA6D;IAC7D,aAAa,CAAC,EAAE,OAAO,CAAC;CACzB;AAED,MAAM,WAAW,oBAAoB;IACnC,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,MAAM,EAAE,CAAC;CACjB;AA8SD;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,aAAa,CAC3B,MAAM,EAAE,YAAY,EACpB,SAAS,EAAE,YAAY,EACvB,MAAM,EAAE,oBAAoB,GAC3B,oBAAoB,CAiCtB"}

package/dist/obsidian-exporter.js

@@ -0,0 +1,274 @@
+/**
+ * obsidian-exporter.ts
+ *
+ * Exports hypermem facts and wiki pages to an Obsidian vault.
+ * Complements obsidian-watcher.ts (import direction).
+ *
+ * Output format:
+ *   - Wiki pages → one .md file per topic, with frontmatter + [[wikilinks]]
+ *   - Facts → grouped by domain into .md files, frontmatter-tagged
+ *   - Index note → _hypermem-index.md with TOC and stats
+ *
+ * Safe to run repeatedly — existing files are overwritten only if content changed.
+ */
+import { mkdirSync, writeFileSync, existsSync, readFileSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+import { createHash } from 'node:crypto';
+// ─── Helpers ────────────────────────────────────────────────────────────────
+function hashContent(content) {
+    return createHash('sha256').update(content).digest('hex').slice(0, 16);
+}
+function safeFilename(name) {
+    return name
+        .replace(/[\\/:*?"<>|]/g, '-')
+        .replace(/\s+/g, ' ')
+        .trim()
+        .slice(0, 200);
+}
+function formatTimestamp(unixMs) {
+    return new Date(unixMs).toISOString().split('T')[0];
+}
+function yamlString(value) {
+    if (/[:#\[\]{},&*?|<>=!%@`]/.test(value) || value.includes('\n')) {
+        return `"${value.replace(/"/g, '\\"')}"`;
+    }
+    return value;
+}
+function buildFrontmatter(fields) {
+    const lines = ['---'];
+    for (const [key, value] of Object.entries(fields)) {
+        if (value === null || value === undefined)
+            continue;
+        if (Array.isArray(value)) {
+            if (value.length === 0)
+                continue;
+            lines.push(`${key}:`);
+            for (const item of value)
+                lines.push(`  - ${yamlString(String(item))}`);
+        }
+        else {
+            lines.push(`${key}: ${yamlString(String(value))}`);
+        }
+    }
+    lines.push('---', '');
+    return lines.join('\n');
+}
+function writeIfChanged(filePath, content, skipUnchanged, result) {
+    if (skipUnchanged && existsSync(filePath)) {
+        const existing = readFileSync(filePath, 'utf8');
+        if (existing === content) {
+            result.skipped++;
+            return;
+        }
+    }
+    writeFileSync(filePath, content, 'utf8');
+    result.written++;
+    result.files.push(filePath);
+}
+// ─── Wiki page export ────────────────────────────────────────────────────────
+function exportWikiPages(libraryDb, outputDir, agentFilter, tagPrefix, skipUnchanged, result) {
+    const wikiDir = join(outputDir, 'wiki');
+    mkdirSync(wikiDir, { recursive: true });
+    let rows;
+    try {
+        const sql = agentFilter
+            ? `SELECT * FROM knowledge WHERE agent_id = ? AND superseded_at IS NULL AND domain = 'topic-synthesis' ORDER BY updated_at DESC`
+            : `SELECT * FROM knowledge WHERE superseded_at IS NULL AND domain = 'topic-synthesis' ORDER BY updated_at DESC`;
+        rows = (agentFilter
+            ? libraryDb.prepare(sql).all(agentFilter)
+            : libraryDb.prepare(sql).all());
+    }
+    catch {
+        result.errors.push('wiki: failed to query knowledge table');
+        return [];
+    }
+    const topicFiles = [];
+    for (const row of rows) {
+        try {
+            const rawTags = row.tags ? JSON.parse(row.tags) : [];
+            const tags = [tagPrefix, `${tagPrefix}/wiki`, ...rawTags];
+            // Resolve cross-links from knowledge_links table
+            let linkRows = [];
+            try {
+                linkRows = libraryDb.prepare(`
+          SELECT kl.from_id, kl.to_id, kl.link_type, k.key as to_key
+          FROM knowledge_links kl
+          JOIN knowledge k ON k.id = kl.to_id
+          WHERE kl.from_id = ? AND kl.from_type = 'knowledge' AND kl.to_type = 'knowledge'
+        `).all(row.id);
+            }
+            catch {
+                // knowledge_links may not exist yet — non-fatal
+            }
+            const wikilinks = linkRows
+                .map(l => `[[${safeFilename(l.to_key)}]]`)
+                .join(' ');
+            const frontmatter = buildFrontmatter({
+                title: row.key,
+                tags,
+                agent: row.agent_id,
+                topic: row.topic || row.key,
+                domain: row.domain,
+                'hypermem-type': 'wiki-page',
+                'last-synthesized': formatTimestamp(row.updated_at),
+                'created-at': formatTimestamp(row.created_at),
+            });
+            let body = row.content.trim();
+            if (linkRows.length > 0) {
+                body += `\n\n## Related Topics\n\n${wikilinks}`;
+            }
+            const note = `${frontmatter}${body}\n`;
+            const fileName = `${safeFilename(row.key)}.md`;
+            const filePath = join(wikiDir, fileName);
+            writeIfChanged(filePath, note, skipUnchanged, result);
+            topicFiles.push(fileName);
+        }
+        catch (err) {
+            result.errors.push(`wiki: failed to export topic '${row.key}': ${String(err)}`);
+        }
+    }
+    return topicFiles;
+}
+// ─── Facts export ────────────────────────────────────────────────────────────
+function exportFacts(mainDb, outputDir, agentFilter, tagPrefix, skipUnchanged, result) {
+    const factsDir = join(outputDir, 'facts');
+    mkdirSync(factsDir, { recursive: true });
+    let rows;
+    try {
+        const sql = agentFilter
+            ? `SELECT * FROM facts WHERE agent_id = ? ORDER BY domain, updated_at DESC`
+            : `SELECT * FROM facts ORDER BY agent_id, domain, updated_at DESC`;
+        rows = (agentFilter
+            ? mainDb.prepare(sql).all(agentFilter)
+            : mainDb.prepare(sql).all());
+    }
+    catch {
+        result.errors.push('facts: failed to query facts table');
+        return [];
+    }
+    // Group by agent + domain
+    const groups = new Map();
+    for (const row of rows) {
+        const domain = row.domain || 'general';
+        const key = `${row.agent_id}__${domain}`;
+        if (!groups.has(key))
+            groups.set(key, []);
+        groups.get(key).push(row);
+    }
+    const factFiles = [];
+    for (const [groupKey, facts] of groups) {
+        try {
+            const [agentId, domain] = groupKey.split('__');
+            const rawTags = [tagPrefix, `${tagPrefix}/facts`, `agent/${agentId}`, `domain/${domain}`];
+            const frontmatter = buildFrontmatter({
+                title: `${agentId} — ${domain} facts`,
+                tags: rawTags,
+                agent: agentId,
+                domain,
+                'hypermem-type': 'facts',
+                'fact-count': facts.length,
+                'last-updated': formatTimestamp(Math.max(...facts.map(f => f.updated_at))),
+            });
+            const lines = [`# ${agentId} — ${domain}\n`];
+            for (const fact of facts) {
+                const confidence = Math.round(fact.confidence * 100);
+                const date = formatTimestamp(fact.updated_at);
+                const factTags = fact.tags
+                    ? JSON.parse(fact.tags).map(t => `#${t}`).join(' ')
+                    : '';
+                lines.push(`- ${fact.content}  `);
+                lines.push(`  *confidence: ${confidence}% · ${date}${factTags ? ' · ' + factTags : ''}*\n`);
+            }
+            const note = `${frontmatter}${lines.join('\n')}\n`;
+            const fileName = `${safeFilename(agentId)}-${safeFilename(domain)}.md`;
+            const filePath = join(factsDir, fileName);
+            writeIfChanged(filePath, note, skipUnchanged, result);
+            factFiles.push(fileName);
+        }
+        catch (err) {
+            result.errors.push(`facts: failed to export group '${groupKey}': ${String(err)}`);
+        }
+    }
+    return factFiles;
+}
+// ─── Index note ───────────────────────────────────────────────────────────────
+function exportIndex(outputDir, wikiFiles, factFiles, tagPrefix, skipUnchanged, result) {
+    const now = new Date().toISOString();
+    const frontmatter = buildFrontmatter({
+        title: 'hypermem export index',
+        tags: [tagPrefix, `${tagPrefix}/index`],
+        'hypermem-type': 'index',
+        'exported-at': now,
+        'wiki-pages': wikiFiles.length,
+        'fact-files': factFiles.length,
+    });
+    const lines = [
+        '# hypermem export index\n',
+        `> exported at ${now}\n`,
+    ];
+    if (wikiFiles.length > 0) {
+        lines.push('## wiki pages\n');
+        for (const f of wikiFiles) {
+            const name = f.replace('.md', '');
+            lines.push(`- [[wiki/${name}]]`);
+        }
+        lines.push('');
+    }
+    if (factFiles.length > 0) {
+        lines.push('## fact collections\n');
+        for (const f of factFiles) {
+            const name = f.replace('.md', '');
+            lines.push(`- [[facts/${name}]]`);
+        }
+        lines.push('');
+    }
+    const note = `${frontmatter}${lines.join('\n')}\n`;
+    const filePath = join(outputDir, '_hypermem-index.md');
+    writeIfChanged(filePath, note, skipUnchanged, result);
+}
+// ─── Main export function ────────────────────────────────────────────────────
+/**
+ * Export hypermem memories to an Obsidian vault.
+ *
+ * @param mainDb - hypermem main DB (facts, episodes)
+ * @param libraryDb - hypermem library DB (knowledge, wiki pages)
+ * @param config - export config
+ * @returns ObsidianExportResult with counts and file list
+ *
+ * @example
+ * const result = await exportToVault(mainDb, libraryDb, {
+ *   vaultPath: '/Users/me/obsidian/my-vault',
+ *   agentId: 'main',
+ *   tagPrefix: 'hypermem',
+ * });
+ * console.log(`Wrote ${result.written} files to ${result.outputDir}`);
+ */
+export function exportToVault(mainDb, libraryDb, config) {
+    const vaultFolder = config.vaultFolder ?? 'hypermem';
+    const tagPrefix = config.tagPrefix ?? 'hypermem';
+    const includeFacts = config.includeFacts ?? true;
+    const includeWikiPages = config.includeWikiPages ?? true;
+    const includeIndex = config.includeIndex ?? true;
+    const skipUnchanged = config.skipUnchanged ?? true;
+    const agentFilter = config.agentId ?? null;
+    const outputDir = resolve(config.vaultPath, vaultFolder);
+    mkdirSync(outputDir, { recursive: true });
+    const result = {
+        written: 0,
+        skipped: 0,
+        errors: [],
+        outputDir,
+        files: [],
+    };
+    const wikiFiles = includeWikiPages
+        ? exportWikiPages(libraryDb, outputDir, agentFilter, tagPrefix, skipUnchanged, result)
+        : [];
+    const factFiles = includeFacts
+        ? exportFacts(mainDb, outputDir, agentFilter, tagPrefix, skipUnchanged, result)
+        : [];
+    if (includeIndex) {
+        exportIndex(outputDir, wikiFiles, factFiles, tagPrefix, skipUnchanged, result);
+    }
+    return result;
+}
+//# sourceMappingURL=obsidian-exporter.js.map