@framers/agentos 0.1.101 → 0.1.102

package/dist/memory/io/JsonImporter.js

@@ -0,0 +1,234 @@
+/**
+ * @fileoverview JSON importer for AgentOS memory brain.
+ *
+ * Reads a JSON file produced by `JsonExporter` (or a compatible schema) and
+ * merges its traces, knowledge nodes, and edges into a target `SqliteBrain`.
+ * Deduplication is performed via SHA-256 content hash — any trace whose hash
+ * already exists in the target brain is skipped rather than duplicated.
+ *
+ * @module memory/io/JsonImporter
+ */
+import fs from 'node:fs/promises';
+import crypto from 'node:crypto';
+import { v4 as uuidv4 } from 'uuid';
+// ---------------------------------------------------------------------------
+// JsonImporter
+// ---------------------------------------------------------------------------
+/**
+ * Imports a `JsonExporter`-compatible JSON file into a `SqliteBrain`.
+ *
+ * **Usage:**
+ * ```ts
+ * const importer = new JsonImporter(brain);
+ * const result = await importer.import('/path/to/export.json');
+ * console.log(result.imported, result.skipped, result.errors);
+ * ```
+ */
+export class JsonImporter {
+    /**
+     * @param brain - The target `SqliteBrain` to import into.
+     */
+    constructor(brain) {
+        this.brain = brain;
+    }
+    // -------------------------------------------------------------------------
+    // Public API
+    // -------------------------------------------------------------------------
+    /**
+     * Read and merge a JSON export file into the target brain.
+     *
+     * Validation:
+     * - The file must be valid JSON.
+     * - The top-level object must contain a `traces` array.
+     *
+     * Deduplication:
+     * - For `memory_traces`: SHA-256 of `content` is used as the dedup key.
+     *   Existing rows with the same hash are skipped.
+     * - For `knowledge_nodes`: SHA-256 of `label` + `type`.
+     * - For `knowledge_edges`: SHA-256 of `source_id` + `target_id` + `type`.
+     *
+     * @param sourcePath - Absolute path to the JSON file to import.
+     * @returns `ImportResult` with counts of imported, skipped, and errored items.
+     */
+    async import(sourcePath) {
+        const result = { imported: 0, skipped: 0, errors: [] };
+        // ---- Load + parse ----
+        let raw;
+        try {
+            raw = await fs.readFile(sourcePath, 'utf8');
+        }
+        catch (err) {
+            result.errors.push(`Failed to read file: ${String(err)}`);
+            return result;
+        }
+        let payload;
+        try {
+            payload = JSON.parse(raw);
+        }
+        catch (err) {
+            result.errors.push(`Invalid JSON: ${String(err)}`);
+            return result;
+        }
+        if (!Array.isArray(payload.traces)) {
+            result.errors.push('Invalid export format: missing top-level "traces" array.');
+            return result;
+        }
+        // ---- Import in a single transaction for atomicity ----
+        this.brain.db.transaction(() => {
+            this._importTraces(payload.traces, result);
+            this._importNodes(payload.nodes ?? [], result);
+            this._importEdges(payload.edges ?? [], result);
+        })();
+        return result;
+    }
+    // -------------------------------------------------------------------------
+    // Private helpers
+    // -------------------------------------------------------------------------
+    /**
+     * Compute a SHA-256 hex digest of arbitrary string content.
+     * Used as a stable dedup key across import operations.
+     *
+     * @param content - The string to hash.
+     * @returns 64-character lowercase hex string.
+     */
+    _sha256(content) {
+        return crypto.createHash('sha256').update(content, 'utf8').digest('hex');
+    }
+    /**
+     * Import memory trace records into `memory_traces`.
+     *
+     * Each trace is deduplicated by the SHA-256 of its `content` field.
+     * If a trace with the same content hash already exists, it is skipped.
+     *
+     * @param traces - Array of serialised trace objects from the export.
+     * @param result - Mutable `ImportResult` to accumulate counts.
+     */
+    _importTraces(traces, result) {
+        const db = this.brain.db;
+        // Prepare dedup check using a JSON column approach — we store the content
+        // hash in the `metadata` JSON under the key `__import_hash`. This lets us
+        // do a fast exact-match lookup without a schema change.
+        const checkStmt = db.prepare(`SELECT id FROM memory_traces WHERE json_extract(metadata, '$.import_hash') = ? LIMIT 1`);
+        const insertStmt = db.prepare(`INSERT INTO memory_traces
+         (id, type, scope, content, embedding, strength, created_at, last_accessed,
+          retrieval_count, tags, emotions, metadata, deleted)
+       VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`);
+        for (const t of traces) {
+            try {
+                const hash = this._sha256(t.content);
+                const existing = checkStmt.get(hash);
+                if (existing) {
+                    result.skipped++;
+                    continue;
+                }
+                // Merge import_hash into the metadata JSON so future imports can dedup.
+                let meta = {};
+                try {
+                    meta = JSON.parse(t.metadata ?? '{}');
+                }
+                catch {
+                    // If metadata is malformed, start fresh.
+                }
+                meta['import_hash'] = hash;
+                // Decode embedding if present.
+                let embeddingBuf = null;
+                if (typeof t.embedding === 'string') {
+                    embeddingBuf = Buffer.from(t.embedding, 'base64');
+                }
+                insertStmt.run(t.id ?? `mt_${uuidv4()}`, t.type ?? 'episodic', t.scope ?? 'user', t.content, embeddingBuf, t.strength ?? 1.0, t.created_at ?? Date.now(), t.last_accessed ?? null, t.retrieval_count ?? 0, t.tags ?? '[]', t.emotions ?? '{}', JSON.stringify(meta), t.deleted ?? 0);
+                result.imported++;
+            }
+            catch (err) {
+                result.errors.push(`Trace import error: ${String(err)}`);
+            }
+        }
+    }
+    /**
+     * Import knowledge node records into `knowledge_nodes`.
+     *
+     * Dedup key: SHA-256 of `label` concatenated with `type`.
+     *
+     * @param nodes  - Array of serialised node objects.
+     * @param result - Mutable `ImportResult` to accumulate counts.
+     */
+    _importNodes(nodes, result) {
+        const db = this.brain.db;
+        const checkStmt = db.prepare(`SELECT id FROM knowledge_nodes WHERE json_extract(properties, '$.import_hash') = ? LIMIT 1`);
+        const insertStmt = db.prepare(`INSERT OR IGNORE INTO knowledge_nodes
+         (id, type, label, properties, embedding, confidence, source, created_at)
+       VALUES (?, ?, ?, ?, ?, ?, ?, ?)`);
+        for (const n of nodes) {
+            try {
+                const hash = this._sha256(`${n.label ?? ''}::${n.type ?? ''}`);
+                const existing = checkStmt.get(hash);
+                if (existing) {
+                    result.skipped++;
+                    continue;
+                }
+                let props = {};
+                try {
+                    props = JSON.parse(n.properties ?? '{}');
+                }
+                catch {
+                    // ignore malformed JSON
+                }
+                props['import_hash'] = hash;
+                let embeddingBuf = null;
+                if (typeof n.embedding === 'string') {
+                    embeddingBuf = Buffer.from(n.embedding, 'base64');
+                }
+                insertStmt.run(n.id ?? `kn_${uuidv4()}`, n.type ?? 'concept', n.label ?? '', JSON.stringify(props), embeddingBuf, n.confidence ?? 1.0, n.source ?? '{}', n.created_at ?? Date.now());
+                result.imported++;
+            }
+            catch (err) {
+                result.errors.push(`Node import error: ${String(err)}`);
+            }
+        }
+    }
+    /**
+     * Import knowledge edge records into `knowledge_edges`.
+     *
+     * Dedup key: SHA-256 of `source_id + target_id + type`.
+     * Edges referencing non-existent nodes are silently skipped (FK constraint).
+     *
+     * @param edges  - Array of serialised edge objects.
+     * @param result - Mutable `ImportResult` to accumulate counts.
+     */
+    _importEdges(edges, result) {
+        const db = this.brain.db;
+        const checkStmt = db.prepare(`SELECT id FROM knowledge_edges WHERE json_extract(metadata, '$.import_hash') = ? LIMIT 1`);
+        const insertStmt = db.prepare(`INSERT OR IGNORE INTO knowledge_edges
+         (id, source_id, target_id, type, weight, bidirectional, metadata, created_at)
+       VALUES (?, ?, ?, ?, ?, ?, ?, ?)`);
+        for (const e of edges) {
+            try {
+                if (!e.source_id || !e.target_id) {
+                    result.skipped++;
+                    continue;
+                }
+                const hash = this._sha256(`${e.source_id}::${e.target_id}::${e.type ?? ''}`);
+                const existing = checkStmt.get(hash);
+                if (existing) {
+                    result.skipped++;
+                    continue;
+                }
+                let meta = {};
+                try {
+                    meta = JSON.parse(e.metadata ?? '{}');
+                }
+                catch {
+                    // ignore malformed JSON
+                }
+                meta['import_hash'] = hash;
+                insertStmt.run(e.id ?? `ke_${uuidv4()}`, e.source_id, e.target_id, e.type ?? 'related_to', e.weight ?? 1.0, e.bidirectional ?? 0, JSON.stringify(meta), e.created_at ?? Date.now());
+                result.imported++;
+            }
+            catch (err) {
+                // FK constraint violation (referenced node doesn't exist) is common
+                // when importing partial exports — log but don't fail.
+                result.errors.push(`Edge import error: ${String(err)}`);
+            }
+        }
+    }
+}
+//# sourceMappingURL=JsonImporter.js.map

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

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

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

@@ -0,0 +1,95 @@
+/**
+ * @fileoverview Markdown exporter for AgentOS memory brain.
+ *
+ * Creates a directory of Markdown files — one per memory trace — organised
+ * into a `{output}/{scope}/{type}/` folder hierarchy.  Each file contains
+ * YAML front-matter (id, type, scope, strength, tags, createdAt) followed
+ * by the plain-text trace content.
+ *
+ * The `gray-matter` library is used to serialise the front-matter block so
+ * that the same library can later round-trip back via `MarkdownImporter`.
+ *
+ * ## Folder layout
+ * ```
+ * {outputDir}/
+ *   user/
+ *     episodic/
+ *       mt_abc123.md
+ *       mt_def456.md
+ *     semantic/
+ *       mt_789.md
+ *   thread/
+ *     procedural/
+ *       ...
+ * ```
+ *
+ * @module memory/io/MarkdownExporter
+ */
+import type { ExportOptions } from '../facade/types.js';
+import type { SqliteBrain } from '../store/SqliteBrain.js';
+/** Raw row shape from the `memory_traces` table. */
+interface TraceRow {
+    id: string;
+    type: string;
+    scope: string;
+    content: string;
+    strength: number;
+    created_at: number;
+    tags: string;
+}
+/**
+ * Exports memory traces as Markdown files with YAML front-matter.
+ *
+ * **Usage:**
+ * ```ts
+ * const exporter = new MarkdownExporter(brain);
+ * await exporter.export('/path/to/vault');
+ * ```
+ */
+export declare class MarkdownExporter {
+    protected readonly brain: SqliteBrain;
+    /**
+     * @param brain - The `SqliteBrain` instance to read from.
+     */
+    constructor(brain: SqliteBrain);
+    /**
+     * Export all memory traces as `.md` files into `outputDir`.
+     *
+     * Directories are created on demand (equivalent to `mkdir -p`).
+     *
+     * @param outputDir - Root directory to write the Markdown vault into.
+     * @param options   - Optional export configuration (currently unused but
+     *   accepted for API consistency with other exporters).
+     */
+    export(outputDir: string, _options?: ExportOptions): Promise<void>;
+    /**
+     * Build the Markdown content for a single trace.
+     *
+     * Subclasses (e.g. `ObsidianExporter`) override this to inject wiki-links
+     * and `#tag` decorations into the body.
+     *
+     * @param trace - Parsed trace row from the database.
+     * @returns Full Markdown file content (front-matter + body).
+     */
+    protected buildFileContent(trace: TraceRow): string;
+    /**
+     * Determine the relative file path for a trace within the output directory.
+     *
+     * Default: `{scope}/{type}/{id}.md`
+     *
+     * @param trace - The trace row.
+     * @returns Relative path string (no leading slash).
+     */
+    protected traceRelativePath(trace: TraceRow): string;
+    /**
+     * Write a single trace to disk.
+     *
+     * Creates any missing parent directories before writing.
+     *
+     * @param outputDir - Root output directory.
+     * @param trace     - Trace row to serialise.
+     */
+    private _writeTrace;
+}
+export {};
+//# sourceMappingURL=MarkdownExporter.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"MarkdownExporter.d.ts","sourceRoot":"","sources":["../../../src/memory/io/MarkdownExporter.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAKH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AACxD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,yBAAyB,CAAC;AAM3D,oDAAoD;AACpD,UAAU,QAAQ;IAChB,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,MAAM,CAAC;IACnB,IAAI,EAAE,MAAM,CAAC;CACd;AAMD;;;;;;;;GAQG;AACH,qBAAa,gBAAgB;IAIf,SAAS,CAAC,QAAQ,CAAC,KAAK,EAAE,WAAW;IAHjD;;OAEG;gBAC4B,KAAK,EAAE,WAAW;IAMjD;;;;;;;;OAQG;IACG,MAAM,CAAC,SAAS,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,aAAa,GAAG,OAAO,CAAC,IAAI,CAAC;IAkBxE;;;;;;;;OAQG;IACH,SAAS,CAAC,gBAAgB,CAAC,KAAK,EAAE,QAAQ,GAAG,MAAM;IAmBnD;;;;;;;OAOG;IACH,SAAS,CAAC,iBAAiB,CAAC,KAAK,EAAE,QAAQ,GAAG,MAAM;IAQpD;;;;;;;OAOG;YACW,WAAW;CAU1B"}

package/dist/memory/io/MarkdownExporter.js

@@ -0,0 +1,130 @@
+/**
+ * @fileoverview Markdown exporter for AgentOS memory brain.
+ *
+ * Creates a directory of Markdown files — one per memory trace — organised
+ * into a `{output}/{scope}/{type}/` folder hierarchy.  Each file contains
+ * YAML front-matter (id, type, scope, strength, tags, createdAt) followed
+ * by the plain-text trace content.
+ *
+ * The `gray-matter` library is used to serialise the front-matter block so
+ * that the same library can later round-trip back via `MarkdownImporter`.
+ *
+ * ## Folder layout
+ * ```
+ * {outputDir}/
+ *   user/
+ *     episodic/
+ *       mt_abc123.md
+ *       mt_def456.md
+ *     semantic/
+ *       mt_789.md
+ *   thread/
+ *     procedural/
+ *       ...
+ * ```
+ *
+ * @module memory/io/MarkdownExporter
+ */
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import matter from 'gray-matter';
+// ---------------------------------------------------------------------------
+// MarkdownExporter
+// ---------------------------------------------------------------------------
+/**
+ * Exports memory traces as Markdown files with YAML front-matter.
+ *
+ * **Usage:**
+ * ```ts
+ * const exporter = new MarkdownExporter(brain);
+ * await exporter.export('/path/to/vault');
+ * ```
+ */
+export class MarkdownExporter {
+    /**
+     * @param brain - The `SqliteBrain` instance to read from.
+     */
+    constructor(brain) {
+        this.brain = brain;
+    }
+    // -------------------------------------------------------------------------
+    // Public API
+    // -------------------------------------------------------------------------
+    /**
+     * Export all memory traces as `.md` files into `outputDir`.
+     *
+     * Directories are created on demand (equivalent to `mkdir -p`).
+     *
+     * @param outputDir - Root directory to write the Markdown vault into.
+     * @param options   - Optional export configuration (currently unused but
+     *   accepted for API consistency with other exporters).
+     */
+    async export(outputDir, _options) {
+        const db = this.brain.db;
+        const traces = db
+            .prepare('SELECT id, type, scope, content, strength, created_at, tags FROM memory_traces WHERE deleted = 0')
+            .all();
+        await Promise.all(traces.map((trace) => this._writeTrace(outputDir, trace)));
+    }
+    // -------------------------------------------------------------------------
+    // Protected helpers (overridden by ObsidianExporter)
+    // -------------------------------------------------------------------------
+    /**
+     * Build the Markdown content for a single trace.
+     *
+     * Subclasses (e.g. `ObsidianExporter`) override this to inject wiki-links
+     * and `#tag` decorations into the body.
+     *
+     * @param trace - Parsed trace row from the database.
+     * @returns Full Markdown file content (front-matter + body).
+     */
+    buildFileContent(trace) {
+        let tags = [];
+        try {
+            tags = JSON.parse(trace.tags);
+        }
+        catch {
+            tags = [];
+        }
+        // gray-matter's `stringify` method generates the YAML block for us.
+        return matter.stringify(trace.content, {
+            id: trace.id,
+            type: trace.type,
+            scope: trace.scope,
+            strength: trace.strength,
+            tags,
+            createdAt: trace.created_at,
+        });
+    }
+    /**
+     * Determine the relative file path for a trace within the output directory.
+     *
+     * Default: `{scope}/{type}/{id}.md`
+     *
+     * @param trace - The trace row.
+     * @returns Relative path string (no leading slash).
+     */
+    traceRelativePath(trace) {
+        return path.join(trace.scope, trace.type, `${trace.id}.md`);
+    }
+    // -------------------------------------------------------------------------
+    // Private helpers
+    // -------------------------------------------------------------------------
+    /**
+     * Write a single trace to disk.
+     *
+     * Creates any missing parent directories before writing.
+     *
+     * @param outputDir - Root output directory.
+     * @param trace     - Trace row to serialise.
+     */
+    async _writeTrace(outputDir, trace) {
+        const relPath = this.traceRelativePath(trace);
+        const absPath = path.join(outputDir, relPath);
+        // Ensure parent directory exists.
+        await fs.mkdir(path.dirname(absPath), { recursive: true });
+        const content = this.buildFileContent(trace);
+        await fs.writeFile(absPath, content, 'utf8');
+    }
+}
+//# sourceMappingURL=MarkdownExporter.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"MarkdownExporter.js","sourceRoot":"","sources":["../../../src/memory/io/MarkdownExporter.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAEH,OAAO,EAAE,MAAM,kBAAkB,CAAC;AAClC,OAAO,IAAI,MAAM,WAAW,CAAC;AAC7B,OAAO,MAAM,MAAM,aAAa,CAAC;AAmBjC,8EAA8E;AAC9E,mBAAmB;AACnB,8EAA8E;AAE9E;;;;;;;;GAQG;AACH,MAAM,OAAO,gBAAgB;IAC3B;;OAEG;IACH,YAA+B,KAAkB;QAAlB,UAAK,GAAL,KAAK,CAAa;IAAG,CAAC;IAErD,4EAA4E;IAC5E,aAAa;IACb,4EAA4E;IAE5E;;;;;;;;OAQG;IACH,KAAK,CAAC,MAAM,CAAC,SAAiB,EAAE,QAAwB;QACtD,MAAM,EAAE,GAAG,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC;QAEzB,MAAM,MAAM,GAAG,EAAE;aACd,OAAO,CACN,kGAAkG,CACnG;aACA,GAAG,EAAE,CAAC;QAET,MAAM,OAAO,CAAC,GAAG,CACf,MAAM,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,IAAI,CAAC,WAAW,CAAC,SAAS,EAAE,KAAK,CAAC,CAAC,CAC1D,CAAC;IACJ,CAAC;IAED,4EAA4E;IAC5E,qDAAqD;IACrD,4EAA4E;IAE5E;;;;;;;;OAQG;IACO,gBAAgB,CAAC,KAAe;QACxC,IAAI,IAAI,GAAa,EAAE,CAAC;QACxB,IAAI,CAAC;YACH,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,IAAI,CAAa,CAAC;QAC5C,CAAC;QAAC,MAAM,CAAC;YACP,IAAI,GAAG,EAAE,CAAC;QACZ,CAAC;QAED,oEAAoE;QACpE,OAAO,MAAM,CAAC,SAAS,CAAC,KAAK,CAAC,OAAO,EAAE;YACrC,EAAE,EAAE,KAAK,CAAC,EAAE;YACZ,IAAI,EAAE,KAAK,CAAC,IAAI;YAChB,KAAK,EAAE,KAAK,CAAC,KAAK;YAClB,QAAQ,EAAE,KAAK,CAAC,QAAQ;YACxB,IAAI;YACJ,SAAS,EAAE,KAAK,CAAC,UAAU;SAC5B,CAAC,CAAC;IACL,CAAC;IAED;;;;;;;OAOG;IACO,iBAAiB,CAAC,KAAe;QACzC,OAAO,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,KAAK,EAAE,KAAK,CAAC,IAAI,EAAE,GAAG,KAAK,CAAC,EAAE,KAAK,CAAC,CAAC;IAC9D,CAAC;IAED,4EAA4E;IAC5E,kBAAkB;IAClB,4EAA4E;IAE5E;;;;;;;OAOG;IACK,KAAK,CAAC,WAAW,CAAC,SAAiB,EAAE,KAAe;QAC1D,MAAM,OAAO,GAAG,IAAI,CAAC,iBAAiB,CAAC,KAAK,CAAC,CAAC;QAC9C,MAAM,OAAO,GAAG,IAAI,CAAC,IAAI,CAAC,SAAS,EAAE,OAAO,CAAC,CAAC;QAE9C,kCAAkC;QAClC,MAAM,EAAE,CAAC,KAAK,CAAC,IAAI,CAAC,OAAO,CAAC,OAAO,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;QAE3D,MAAM,OAAO,GAAG,IAAI,CAAC,gBAAgB,CAAC,KAAK,CAAC,CAAC;QAC7C,MAAM,EAAE,CAAC,SAAS,CAAC,OAAO,EAAE,OAAO,EAAE,MAAM,CAAC,CAAC;IAC/C,CAAC;CACF"}

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

@@ -0,0 +1,84 @@
+/**
+ * @fileoverview Markdown importer for AgentOS memory brain.
+ *
+ * Recursively walks a directory of Markdown files and inserts each file as a
+ * memory trace in the target `SqliteBrain`.  Front-matter fields (parsed via
+ * `gray-matter`) are mapped to trace columns; the document body becomes the
+ * trace content.
+ *
+ * Deduplication uses SHA-256 of the content body — files already present in
+ * the target brain (same hash in `metadata.import_hash`) are skipped.
+ *
+ * @module memory/io/MarkdownImporter
+ */
+import type { ImportResult } from '../facade/types.js';
+import type { SqliteBrain } from '../store/SqliteBrain.js';
+/**
+ * Parsed front-matter fields extracted from a Markdown trace file.
+ * All fields are optional — the importer falls back to safe defaults.
+ */
+interface TraceFrontmatter {
+    id?: string;
+    type?: string;
+    scope?: string;
+    strength?: number;
+    tags?: string[];
+    createdAt?: number;
+    [key: string]: unknown;
+}
+/**
+ * Imports Markdown files from a directory into a `SqliteBrain`.
+ *
+ * **Usage:**
+ * ```ts
+ * const importer = new MarkdownImporter(brain);
+ * const result = await importer.import('/path/to/vault');
+ * console.log(result.imported, result.skipped);
+ * ```
+ */
+export declare class MarkdownImporter {
+    protected readonly brain: SqliteBrain;
+    /**
+     * @param brain - The target `SqliteBrain` to import into.
+     */
+    constructor(brain: SqliteBrain);
+    /**
+     * Recursively walk `sourceDir`, parse every `.md` file, and insert traces.
+     *
+     * Non-Markdown files are silently ignored.  Files that fail to parse are
+     * recorded in `result.errors` and processing continues.
+     *
+     * @param sourceDir - Directory to recursively scan for `.md` files.
+     * @returns `ImportResult` with counts of imported, skipped, and errored items.
+     */
+    import(sourceDir: string): Promise<ImportResult>;
+    /**
+     * Post-process a parsed file before it is inserted into the database.
+     *
+     * The base implementation is a no-op.  `ObsidianImporter` overrides this
+     * to extract `[[wikilinks]]` and `#tags`.
+     *
+     * @param _filePath   - Absolute path of the source file.
+     * @param _frontmatter - Parsed front-matter data.
+     * @param _body       - Markdown body content.
+     * @param _result     - Mutable result accumulator.
+     * @param _traceId    - The ID assigned (or taken from front-matter) for this trace.
+     */
+    protected postProcess(_filePath: string, _frontmatter: TraceFrontmatter, _body: string, _result: ImportResult, _traceId: string): Promise<void>;
+    /**
+     * Recursively collect all `.md` file paths under `dir`.
+     *
+     * @param dir - Root directory to scan.
+     * @returns Sorted list of absolute file paths.
+     */
+    private _collectMarkdownFiles;
+    /**
+     * Parse and insert a single Markdown file.
+     *
+     * @param filePath - Absolute path to the `.md` file.
+     * @param result   - Mutable `ImportResult` accumulator.
+     */
+    private _processFile;
+}
+export {};
+//# sourceMappingURL=MarkdownImporter.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"MarkdownImporter.d.ts","sourceRoot":"","sources":["../../../src/memory/io/MarkdownImporter.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAOH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AACvD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,yBAAyB,CAAC;AAM3D;;;GAGG;AACH,UAAU,gBAAgB;IACxB,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAChB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AAMD;;;;;;;;;GASG;AACH,qBAAa,gBAAgB;IAIf,SAAS,CAAC,QAAQ,CAAC,KAAK,EAAE,WAAW;IAHjD;;OAEG;gBAC4B,KAAK,EAAE,WAAW;IAMjD;;;;;;;;OAQG;IACG,MAAM,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,CAAC;IAgBtD;;;;;;;;;;;OAWG;cACa,WAAW,CACzB,SAAS,EAAE,MAAM,EACjB,YAAY,EAAE,gBAAgB,EAC9B,KAAK,EAAE,MAAM,EACb,OAAO,EAAE,YAAY,EACrB,QAAQ,EAAE,MAAM,GACf,OAAO,CAAC,IAAI,CAAC;IAQhB;;;;;OAKG;YACW,qBAAqB;IAyBnC;;;;;OAKG;YACW,YAAY;CAuE3B"}