@framers/agentos 0.1.101 → 0.1.102

package/dist/memory/io/ObsidianImporter.js

@@ -0,0 +1,221 @@
+/**
+ * @fileoverview Obsidian vault importer for AgentOS memory brain.
+ *
+ * Extends `MarkdownImporter` with Obsidian-specific parsing:
+ *
+ * 1. **`[[wikilinks]]`** — each `[[Target Note]]` (or `[[Target|Alias]]`) in
+ *    a note's body is parsed.  For each wikilink, the importer looks up (or
+ *    creates) a `knowledge_nodes` entry for the target label and then creates
+ *    a `knowledge_edges` row of type `'related_to'` linking the source trace
+ *    node to the target node.
+ *
+ * 2. **`#tags`** — inline hashtags are extracted from the body and merged
+ *    into the trace's `tags` JSON column (in addition to any front-matter tags).
+ *
+ * 3. **`![[image.png]]`** — embedded-image syntax is detected and a warning
+ *    is logged.  Embedded images are not imported in the current version.
+ *
+ * @module memory/io/ObsidianImporter
+ */
+import crypto from 'node:crypto';
+import { v4 as uuidv4 } from 'uuid';
+import { MarkdownImporter } from './MarkdownImporter.js';
+// ---------------------------------------------------------------------------
+// Regex constants
+// ---------------------------------------------------------------------------
+/**
+ * Matches Obsidian wikilinks: `[[Target]]` or `[[Target|Alias]]`.
+ * Capture group 1 is the target note name; alias (if any) is ignored.
+ * Does NOT match embedded images (`![[...]]`) — those use a separate pattern.
+ */
+const WIKILINK_RE = /(?<!!)\[\[([^\]|]+)(?:\|[^\]]+)?\]\]/g;
+/**
+ * Matches Obsidian embedded images: `![[image.png]]`.
+ * Used to emit a warning — embedded images are not yet supported for import.
+ */
+const EMBED_RE = /!\[\[[^\]]+\]\]/g;
+/**
+ * Matches inline hashtags: `#tagName` (not preceded by `[` or `#`).
+ * Only captures the tag name (group 1) without the leading `#`.
+ */
+const HASHTAG_RE = /(?<![[\#])#([\w-]+)/g;
+// ---------------------------------------------------------------------------
+// ObsidianImporter
+// ---------------------------------------------------------------------------
+/**
+ * Imports an Obsidian vault (directory of Markdown files) into a `SqliteBrain`.
+ *
+ * **Usage:**
+ * ```ts
+ * const importer = new ObsidianImporter(brain);
+ * const result = await importer.import('/path/to/obsidian-vault');
+ * ```
+ */
+export class ObsidianImporter extends MarkdownImporter {
+    /**
+     * @param brain - The target `SqliteBrain` to import into.
+     */
+    constructor(brain) {
+        super(brain);
+    }
+    // -------------------------------------------------------------------------
+    // Overridden hook
+    // -------------------------------------------------------------------------
+    /**
+     * Post-process a successfully imported Markdown file:
+     *
+     * 1. Warn about any embedded images (`![[...]]`).
+     * 2. Extract inline `#hashtags` and merge them into the trace's tag list.
+     * 3. Parse `[[wikilinks]]` and create `knowledge_edges` entries.
+     *
+     * @param _filePath    - Absolute path of the source file (unused here).
+     * @param _frontmatter - Parsed front-matter data.
+     * @param body         - Markdown body (content after front-matter).
+     * @param result       - Mutable `ImportResult` accumulator.
+     * @param traceId      - The ID of the just-inserted trace.
+     */
+    async postProcess(_filePath, _frontmatter, body, result, traceId) {
+        // ---- 1. Warn about embedded images ----
+        const embedMatches = body.match(EMBED_RE);
+        if (embedMatches && embedMatches.length > 0) {
+            console.warn(`[ObsidianImporter] Embedded images are not yet supported in import. ` +
+                `Found ${embedMatches.length} embed(s) in trace ${traceId}.`);
+        }
+        // ---- 2. Extract inline hashtags and persist to trace ----
+        const inlineTags = [];
+        let tagMatch;
+        HASHTAG_RE.lastIndex = 0;
+        while ((tagMatch = HASHTAG_RE.exec(body)) !== null) {
+            if (tagMatch[1])
+                inlineTags.push(tagMatch[1]);
+        }
+        if (inlineTags.length > 0) {
+            this._mergeTagsIntoTrace(traceId, inlineTags, result);
+        }
+        // ---- 3. Parse wikilinks and create knowledge_edges ----
+        const wikiTargets = [];
+        let wikilinkMatch;
+        WIKILINK_RE.lastIndex = 0;
+        while ((wikilinkMatch = WIKILINK_RE.exec(body)) !== null) {
+            if (wikilinkMatch[1])
+                wikiTargets.push(wikilinkMatch[1].trim());
+        }
+        for (const target of wikiTargets) {
+            this._upsertWikiEdge(traceId, target, result);
+        }
+    }
+    // -------------------------------------------------------------------------
+    // Private helpers
+    // -------------------------------------------------------------------------
+    /**
+     * Merge a list of inline hashtag names into a trace's `tags` JSON column.
+     *
+     * Reads the current tags array, deduplicates, and writes back.
+     *
+     * @param traceId    - ID of the trace to update.
+     * @param newTags    - Hashtag names to add (without the leading `#`).
+     * @param result     - Mutable result accumulator (errors recorded here).
+     */
+    _mergeTagsIntoTrace(traceId, newTags, result) {
+        try {
+            const db = this.brain.db;
+            const row = db
+                .prepare('SELECT tags FROM memory_traces WHERE id = ?')
+                .get(traceId);
+            if (!row)
+                return;
+            let existing = [];
+            try {
+                existing = JSON.parse(row.tags);
+            }
+            catch {
+                existing = [];
+            }
+            const merged = Array.from(new Set([...existing, ...newTags]));
+            db.prepare('UPDATE memory_traces SET tags = ? WHERE id = ?').run(JSON.stringify(merged), traceId);
+        }
+        catch (err) {
+            result.errors.push(`Tag merge error for trace ${traceId}: ${String(err)}`);
+        }
+    }
+    /**
+     * Ensure `knowledge_nodes` entries exist for both the source trace and the
+     * target label, then create a `knowledge_edges` row (type `'related_to'`)
+     * linking them.
+     *
+     * Because `knowledge_edges.source_id` has a FK reference to
+     * `knowledge_nodes(id)`, we first upsert a node for the source trace (using
+     * the trace content as the label) before creating the edge.  This lets
+     * Obsidian's graph view visualise which note links to which concept.
+     *
+     * Both node upserts and the edge insert use `INSERT OR IGNORE` so repeated
+     * imports don't create duplicates.
+     *
+     * @param sourceTraceId - The memory trace ID that contains the wikilink.
+     * @param targetLabel   - The label of the linked note (wikilink target).
+     * @param result        - Mutable result accumulator.
+     */
+    _upsertWikiEdge(sourceTraceId, targetLabel, result) {
+        try {
+            // Access brain.db through the protected field inherited from MarkdownImporter.
+            const db = this.brain.db;
+            // ---- Upsert source knowledge node for the trace ----
+            // We use the trace ID itself as the node label so the graph stays navigable.
+            const sourceLabel = `trace:${sourceTraceId}`;
+            const sourceHash = crypto
+                .createHash('sha256')
+                .update(`wiki-source::${sourceTraceId}`)
+                .digest('hex');
+            let sourceNodeId;
+            const existingSource = db
+                .prepare(`SELECT id FROM knowledge_nodes WHERE label = ? LIMIT 1`)
+                .get(sourceLabel);
+            if (existingSource) {
+                sourceNodeId = existingSource.id;
+            }
+            else {
+                sourceNodeId = `kn_${uuidv4()}`;
+                db.prepare(`INSERT OR IGNORE INTO knowledge_nodes
+             (id, type, label, properties, embedding, confidence, source, created_at)
+           VALUES (?, 'trace', ?, ?, NULL, 1.0, '{}', ?)`).run(sourceNodeId, sourceLabel, JSON.stringify({ import_hash: sourceHash, trace_id: sourceTraceId }), Date.now());
+            }
+            // ---- Upsert target knowledge node for the wikilink label ----
+            const targetHash = crypto
+                .createHash('sha256')
+                .update(`wiki::${targetLabel}`)
+                .digest('hex');
+            let targetNodeId;
+            const existingTarget = db
+                .prepare(`SELECT id FROM knowledge_nodes WHERE label = ? LIMIT 1`)
+                .get(targetLabel);
+            if (existingTarget) {
+                targetNodeId = existingTarget.id;
+            }
+            else {
+                targetNodeId = `kn_${uuidv4()}`;
+                db.prepare(`INSERT OR IGNORE INTO knowledge_nodes
+             (id, type, label, properties, embedding, confidence, source, created_at)
+           VALUES (?, 'concept', ?, ?, NULL, 1.0, '{}', ?)`).run(targetNodeId, targetLabel, JSON.stringify({ import_hash: targetHash, obsidian_wikilink: true }), Date.now());
+            }
+            // ---- Create the directed edge: source node → target node ----
+            const edgeHash = crypto
+                .createHash('sha256')
+                .update(`${sourceNodeId}::${targetNodeId}::related_to`)
+                .digest('hex');
+            // Check for existing edge before insert (extra safety beyond OR IGNORE).
+            const existingEdge = db
+                .prepare(`SELECT id FROM knowledge_edges
+           WHERE json_extract(metadata, '$.import_hash') = ? LIMIT 1`)
+                .get(edgeHash);
+            if (!existingEdge) {
+                db.prepare(`INSERT OR IGNORE INTO knowledge_edges
+             (id, source_id, target_id, type, weight, bidirectional, metadata, created_at)
+           VALUES (?, ?, ?, 'related_to', 1.0, 0, ?, ?)`).run(`ke_${uuidv4()}`, sourceNodeId, targetNodeId, JSON.stringify({ import_hash: edgeHash, source: 'obsidian_wikilink', trace_id: sourceTraceId }), Date.now());
+            }
+        }
+        catch (err) {
+            result.errors.push(`Wikilink edge error (${sourceTraceId} → "${targetLabel}"): ${String(err)}`);
+        }
+    }
+}
+//# sourceMappingURL=ObsidianImporter.js.map

package/dist/memory/io/ObsidianImporter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ObsidianImporter.js","sourceRoot":"","sources":["../../../src/memory/io/ObsidianImporter.ts"],"names":[],"mappings":"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"}

package/dist/memory/io/SqliteExporter.d.ts

@@ -0,0 +1,47 @@
+/**
+ * @fileoverview SQLite exporter for AgentOS memory brain.
+ *
+ * Provides a full-fidelity backup of the `SqliteBrain` SQLite file by copying
+ * the database file to a specified output path.  This is the highest-fidelity
+ * export format — it preserves all tables, indexes, and metadata exactly.
+ *
+ * Because `better-sqlite3` keeps the file open in WAL mode, we use the
+ * built-in `VACUUM INTO` SQL command (SQLite 3.27+) which atomically creates
+ * a clean, fully checkpointed copy without any WAL sidecar file.
+ *
+ * @module memory/io/SqliteExporter
+ */
+import type { ExportOptions } from '../facade/types.js';
+import type { SqliteBrain } from '../store/SqliteBrain.js';
+/**
+ * Exports a `SqliteBrain` as a portable SQLite file.
+ *
+ * **Usage:**
+ * ```ts
+ * const exporter = new SqliteExporter(brain);
+ * await exporter.export('/path/to/backup.sqlite');
+ * ```
+ */
+export declare class SqliteExporter {
+    private readonly brain;
+    /**
+     * @param brain - The `SqliteBrain` instance to export.
+     */
+    constructor(brain: SqliteBrain);
+    /**
+     * Copy the brain database to `outputPath`.
+     *
+     * Uses `VACUUM INTO` which:
+     * - Checkpoints all WAL frames into the output file.
+     * - Creates a compact, defragmented copy (no `-wal` or `-shm` sidecar).
+     * - Is safe to run while the database is open and being written to.
+     *
+     * The parent directory of `outputPath` must already exist.
+     *
+     * @param outputPath - Absolute path for the SQLite backup file.
+     * @param _options   - Export options (unused — SQLite export always includes
+     *   all data including embeddings).
+     */
+    export(outputPath: string, _options?: ExportOptions): Promise<void>;
+}
+//# sourceMappingURL=SqliteExporter.d.ts.map

package/dist/memory/io/SqliteExporter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"SqliteExporter.d.ts","sourceRoot":"","sources":["../../../src/memory/io/SqliteExporter.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AACxD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,yBAAyB,CAAC;AAM3D;;;;;;;;GAQG;AACH,qBAAa,cAAc;IAIb,OAAO,CAAC,QAAQ,CAAC,KAAK;IAHlC;;OAEG;gBAC0B,KAAK,EAAE,WAAW;IAM/C;;;;;;;;;;;;;OAaG;IACG,MAAM,CAAC,UAAU,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,aAAa,GAAG,OAAO,CAAC,IAAI,CAAC;CAK1E"}

package/dist/memory/io/SqliteExporter.js

@@ -0,0 +1,56 @@
+/**
+ * @fileoverview SQLite exporter for AgentOS memory brain.
+ *
+ * Provides a full-fidelity backup of the `SqliteBrain` SQLite file by copying
+ * the database file to a specified output path.  This is the highest-fidelity
+ * export format — it preserves all tables, indexes, and metadata exactly.
+ *
+ * Because `better-sqlite3` keeps the file open in WAL mode, we use the
+ * built-in `VACUUM INTO` SQL command (SQLite 3.27+) which atomically creates
+ * a clean, fully checkpointed copy without any WAL sidecar file.
+ *
+ * @module memory/io/SqliteExporter
+ */
+// ---------------------------------------------------------------------------
+// SqliteExporter
+// ---------------------------------------------------------------------------
+/**
+ * Exports a `SqliteBrain` as a portable SQLite file.
+ *
+ * **Usage:**
+ * ```ts
+ * const exporter = new SqliteExporter(brain);
+ * await exporter.export('/path/to/backup.sqlite');
+ * ```
+ */
+export class SqliteExporter {
+    /**
+     * @param brain - The `SqliteBrain` instance to export.
+     */
+    constructor(brain) {
+        this.brain = brain;
+    }
+    // -------------------------------------------------------------------------
+    // Public API
+    // -------------------------------------------------------------------------
+    /**
+     * Copy the brain database to `outputPath`.
+     *
+     * Uses `VACUUM INTO` which:
+     * - Checkpoints all WAL frames into the output file.
+     * - Creates a compact, defragmented copy (no `-wal` or `-shm` sidecar).
+     * - Is safe to run while the database is open and being written to.
+     *
+     * The parent directory of `outputPath` must already exist.
+     *
+     * @param outputPath - Absolute path for the SQLite backup file.
+     * @param _options   - Export options (unused — SQLite export always includes
+     *   all data including embeddings).
+     */
+    async export(outputPath, _options) {
+        // VACUUM INTO creates a compact, defragmented copy of the live database.
+        // It is an atomic operation from SQLite's perspective.
+        this.brain.db.exec(`VACUUM INTO '${outputPath.replace(/'/g, "''")}'`);
+    }
+}
+//# sourceMappingURL=SqliteExporter.js.map

package/dist/memory/io/SqliteExporter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"SqliteExporter.js","sourceRoot":"","sources":["../../../src/memory/io/SqliteExporter.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAKH,8EAA8E;AAC9E,iBAAiB;AACjB,8EAA8E;AAE9E;;;;;;;;GAQG;AACH,MAAM,OAAO,cAAc;IACzB;;OAEG;IACH,YAA6B,KAAkB;QAAlB,UAAK,GAAL,KAAK,CAAa;IAAG,CAAC;IAEnD,4EAA4E;IAC5E,aAAa;IACb,4EAA4E;IAE5E;;;;;;;;;;;;;OAaG;IACH,KAAK,CAAC,MAAM,CAAC,UAAkB,EAAE,QAAwB;QACvD,yEAAyE;QACzE,uDAAuD;QACvD,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC,IAAI,CAAC,gBAAgB,UAAU,CAAC,OAAO,CAAC,IAAI,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC;IACxE,CAAC;CACF"}

package/dist/memory/io/SqliteImporter.d.ts

@@ -0,0 +1,82 @@
+/**
+ * @fileoverview SQLite importer for AgentOS memory brain.
+ *
+ * Opens a source SQLite file (exported by `SqliteExporter` or any compatible
+ * AgentOS brain) as a separate `better-sqlite3` connection, reads all data
+ * tables, and merges them into the target `SqliteBrain`.
+ *
+ * ## Merge strategy
+ * - **memory_traces**: deduplicated by SHA-256 of `content`.
+ *   - If a trace with the same hash already exists in the target:
+ *     - Keep the newer `created_at` / `last_accessed` timestamp.
+ *     - Merge `tags` arrays (union, dedup).
+ *   - New traces are inserted wholesale.
+ * - **knowledge_nodes**: deduplicated by `label` + `type`.
+ *   - New nodes are inserted; existing nodes are left unchanged.
+ * - **knowledge_edges**: deduplicated by `source_id` + `target_id` + `type`.
+ *   - New edges are inserted; existing edges are left unchanged.
+ *
+ * @module memory/io/SqliteImporter
+ */
+import type { ImportResult } from '../facade/types.js';
+import type { SqliteBrain } from '../store/SqliteBrain.js';
+/**
+ * Merges a source SQLite brain file into a target `SqliteBrain`.
+ *
+ * **Usage:**
+ * ```ts
+ * const importer = new SqliteImporter(targetBrain);
+ * const result = await importer.import('/path/to/source.sqlite');
+ * ```
+ */
+export declare class SqliteImporter {
+    private readonly brain;
+    /**
+     * @param brain - The target `SqliteBrain` to merge data into.
+     */
+    constructor(brain: SqliteBrain);
+    /**
+     * Open `sourcePath` as a read-only SQLite connection, read all tables, and
+     * merge their contents into the target brain.
+     *
+     * The source connection is closed when this method returns (even on error).
+     *
+     * @param sourcePath - Absolute path to the source `.sqlite` file to import.
+     * @returns `ImportResult` with counts of imported, skipped, and errored items.
+     */
+    import(sourcePath: string): Promise<ImportResult>;
+    /**
+     * SHA-256 of an arbitrary string (hex output).
+     */
+    private _sha256;
+    /**
+     * Merge `memory_traces` from source into target.
+     *
+     * Dedup key: SHA-256 of `content`.
+     * Conflict resolution: keep newer timestamp, union tags.
+     *
+     * @param src    - Open source `better-sqlite3` database.
+     * @param result - Mutable result accumulator.
+     */
+    private _mergeTraces;
+    /**
+     * Merge `knowledge_nodes` from source into target.
+     *
+     * Dedup key: SHA-256 of `label` + `type`.
+     *
+     * @param src    - Open source database.
+     * @param result - Mutable result accumulator.
+     */
+    private _mergeNodes;
+    /**
+     * Merge `knowledge_edges` from source into target.
+     *
+     * Dedup key: SHA-256 of `source_id` + `target_id` + `type`.
+     * Edges whose referenced nodes don't exist in the target are skipped.
+     *
+     * @param src    - Open source database.
+     * @param result - Mutable result accumulator.
+     */
+    private _mergeEdges;
+}
+//# sourceMappingURL=SqliteImporter.d.ts.map

package/dist/memory/io/SqliteImporter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"SqliteImporter.d.ts","sourceRoot":"","sources":["../../../src/memory/io/SqliteImporter.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAKH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AACvD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,yBAAyB,CAAC;AAgD3D;;;;;;;;GAQG;AACH,qBAAa,cAAc;IAIb,OAAO,CAAC,QAAQ,CAAC,KAAK;IAHlC;;OAEG;gBAC0B,KAAK,EAAE,WAAW;IAM/C;;;;;;;;OAQG;IACG,MAAM,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,CAAC;IA8BvD;;OAEG;IACH,OAAO,CAAC,OAAO;IAIf;;;;;;;;OAQG;IACH,OAAO,CAAC,YAAY;IA8EpB;;;;;;;OAOG;IACH,OAAO,CAAC,WAAW;IA4CnB;;;;;;;;OAQG;IACH,OAAO,CAAC,WAAW;CAmDpB"}

package/dist/memory/io/SqliteImporter.js

@@ -0,0 +1,232 @@
+/**
+ * @fileoverview SQLite importer for AgentOS memory brain.
+ *
+ * Opens a source SQLite file (exported by `SqliteExporter` or any compatible
+ * AgentOS brain) as a separate `better-sqlite3` connection, reads all data
+ * tables, and merges them into the target `SqliteBrain`.
+ *
+ * ## Merge strategy
+ * - **memory_traces**: deduplicated by SHA-256 of `content`.
+ *   - If a trace with the same hash already exists in the target:
+ *     - Keep the newer `created_at` / `last_accessed` timestamp.
+ *     - Merge `tags` arrays (union, dedup).
+ *   - New traces are inserted wholesale.
+ * - **knowledge_nodes**: deduplicated by `label` + `type`.
+ *   - New nodes are inserted; existing nodes are left unchanged.
+ * - **knowledge_edges**: deduplicated by `source_id` + `target_id` + `type`.
+ *   - New edges are inserted; existing edges are left unchanged.
+ *
+ * @module memory/io/SqliteImporter
+ */
+import Database from 'better-sqlite3';
+import crypto from 'node:crypto';
+import { v4 as uuidv4 } from 'uuid';
+// ---------------------------------------------------------------------------
+// SqliteImporter
+// ---------------------------------------------------------------------------
+/**
+ * Merges a source SQLite brain file into a target `SqliteBrain`.
+ *
+ * **Usage:**
+ * ```ts
+ * const importer = new SqliteImporter(targetBrain);
+ * const result = await importer.import('/path/to/source.sqlite');
+ * ```
+ */
+export class SqliteImporter {
+    /**
+     * @param brain - The target `SqliteBrain` to merge data into.
+     */
+    constructor(brain) {
+        this.brain = brain;
+    }
+    // -------------------------------------------------------------------------
+    // Public API
+    // -------------------------------------------------------------------------
+    /**
+     * Open `sourcePath` as a read-only SQLite connection, read all tables, and
+     * merge their contents into the target brain.
+     *
+     * The source connection is closed when this method returns (even on error).
+     *
+     * @param sourcePath - Absolute path to the source `.sqlite` file to import.
+     * @returns `ImportResult` with counts of imported, skipped, and errored items.
+     */
+    async import(sourcePath) {
+        const result = { imported: 0, skipped: 0, errors: [] };
+        // Open the source file read-only so we cannot accidentally corrupt it.
+        let sourceDb;
+        try {
+            sourceDb = new Database(sourcePath, { readonly: true });
+        }
+        catch (err) {
+            result.errors.push(`Cannot open source SQLite: ${String(err)}`);
+            return result;
+        }
+        try {
+            // Run the whole merge in a single transaction on the target brain.
+            this.brain.db.transaction(() => {
+                this._mergeTraces(sourceDb, result);
+                this._mergeNodes(sourceDb, result);
+                this._mergeEdges(sourceDb, result);
+            })();
+        }
+        finally {
+            sourceDb.close();
+        }
+        return result;
+    }
+    // -------------------------------------------------------------------------
+    // Private helpers
+    // -------------------------------------------------------------------------
+    /**
+     * SHA-256 of an arbitrary string (hex output).
+     */
+    _sha256(s) {
+        return crypto.createHash('sha256').update(s, 'utf8').digest('hex');
+    }
+    /**
+     * Merge `memory_traces` from source into target.
+     *
+     * Dedup key: SHA-256 of `content`.
+     * Conflict resolution: keep newer timestamp, union tags.
+     *
+     * @param src    - Open source `better-sqlite3` database.
+     * @param result - Mutable result accumulator.
+     */
+    _mergeTraces(src, result) {
+        let sourceRows;
+        try {
+            sourceRows = src.prepare('SELECT * FROM memory_traces').all();
+        }
+        catch {
+            // Table might not exist in an incompatible source.
+            return;
+        }
+        const checkStmt = this.brain.db.prepare(`SELECT id, created_at, tags
+       FROM memory_traces
+       WHERE json_extract(metadata, '$.import_hash') = ?
+          OR content = ?
+       LIMIT 1`);
+        const insertStmt = this.brain.db.prepare(`INSERT INTO memory_traces
+         (id, type, scope, content, embedding, strength, created_at, last_accessed,
+          retrieval_count, tags, emotions, metadata, deleted)
+       VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`);
+        const updateTimestampStmt = this.brain.db.prepare(`UPDATE memory_traces SET created_at = ?, tags = ? WHERE id = ?`);
+        for (const row of sourceRows) {
+            try {
+                const hash = this._sha256(row.content);
+                const existing = checkStmt.get(hash, row.content);
+                if (existing) {
+                    // Keep the newer timestamp and union the tags.
+                    const newerAt = Math.max(existing.created_at, row.created_at);
+                    let existingTags = [];
+                    try {
+                        existingTags = JSON.parse(existing.tags);
+                    }
+                    catch { /* ignore */ }
+                    let sourceTags = [];
+                    try {
+                        sourceTags = JSON.parse(row.tags);
+                    }
+                    catch { /* ignore */ }
+                    const merged = Array.from(new Set([...existingTags, ...sourceTags]));
+                    updateTimestampStmt.run(newerAt, JSON.stringify(merged), existing.id);
+                    result.skipped++;
+                    continue;
+                }
+                // New trace — enrich metadata with import_hash.
+                let meta = {};
+                try {
+                    meta = JSON.parse(row.metadata);
+                }
+                catch { /* ignore */ }
+                meta['import_hash'] = hash;
+                insertStmt.run(row.id ?? `mt_${uuidv4()}`, row.type ?? 'episodic', row.scope ?? 'user', row.content, row.embedding ?? null, row.strength ?? 1.0, row.created_at ?? Date.now(), row.last_accessed ?? null, row.retrieval_count ?? 0, row.tags ?? '[]', row.emotions ?? '{}', JSON.stringify(meta), row.deleted ?? 0);
+                result.imported++;
+            }
+            catch (err) {
+                result.errors.push(`Trace merge error: ${String(err)}`);
+            }
+        }
+    }
+    /**
+     * Merge `knowledge_nodes` from source into target.
+     *
+     * Dedup key: SHA-256 of `label` + `type`.
+     *
+     * @param src    - Open source database.
+     * @param result - Mutable result accumulator.
+     */
+    _mergeNodes(src, result) {
+        let sourceRows;
+        try {
+            sourceRows = src.prepare('SELECT * FROM knowledge_nodes').all();
+        }
+        catch {
+            return;
+        }
+        const checkStmt = this.brain.db.prepare(`SELECT id FROM knowledge_nodes WHERE label = ? AND type = ? LIMIT 1`);
+        const insertStmt = this.brain.db.prepare(`INSERT OR IGNORE INTO knowledge_nodes
+         (id, type, label, properties, embedding, confidence, source, created_at)
+       VALUES (?, ?, ?, ?, ?, ?, ?, ?)`);
+        for (const row of sourceRows) {
+            try {
+                const existing = checkStmt.get(row.label ?? '', row.type ?? '');
+                if (existing) {
+                    result.skipped++;
+                    continue;
+                }
+                insertStmt.run(row.id ?? `kn_${uuidv4()}`, row.type ?? 'concept', row.label ?? '', row.properties ?? '{}', row.embedding ?? null, row.confidence ?? 1.0, row.source ?? '{}', row.created_at ?? Date.now());
+                result.imported++;
+            }
+            catch (err) {
+                result.errors.push(`Node merge error: ${String(err)}`);
+            }
+        }
+    }
+    /**
+     * Merge `knowledge_edges` from source into target.
+     *
+     * Dedup key: SHA-256 of `source_id` + `target_id` + `type`.
+     * Edges whose referenced nodes don't exist in the target are skipped.
+     *
+     * @param src    - Open source database.
+     * @param result - Mutable result accumulator.
+     */
+    _mergeEdges(src, result) {
+        let sourceRows;
+        try {
+            sourceRows = src.prepare('SELECT * FROM knowledge_edges').all();
+        }
+        catch {
+            return;
+        }
+        const checkStmt = this.brain.db.prepare(`SELECT id FROM knowledge_edges
+       WHERE source_id = ? AND target_id = ? AND type = ?
+       LIMIT 1`);
+        const insertStmt = this.brain.db.prepare(`INSERT OR IGNORE INTO knowledge_edges
+         (id, source_id, target_id, type, weight, bidirectional, metadata, created_at)
+       VALUES (?, ?, ?, ?, ?, ?, ?, ?)`);
+        for (const row of sourceRows) {
+            try {
+                if (!row.source_id || !row.target_id) {
+                    result.skipped++;
+                    continue;
+                }
+                const existing = checkStmt.get(row.source_id, row.target_id, row.type ?? '');
+                if (existing) {
+                    result.skipped++;
+                    continue;
+                }
+                insertStmt.run(row.id ?? `ke_${uuidv4()}`, row.source_id, row.target_id, row.type ?? 'related_to', row.weight ?? 1.0, row.bidirectional ?? 0, row.metadata ?? '{}', row.created_at ?? Date.now());
+                result.imported++;
+            }
+            catch (err) {
+                // FK constraint: target node not in this brain — expected for partial imports.
+                result.errors.push(`Edge merge error: ${String(err)}`);
+            }
+        }
+    }
+}
+//# sourceMappingURL=SqliteImporter.js.map