@framers/agentos 0.1.101 → 0.1.103

package/dist/memory/io/ChatGptImporter.js

@@ -0,0 +1,231 @@
+/**
+ * @fileoverview ChatGPT export importer for AgentOS memory brain.
+ *
+ * Parses the `conversations.json` file produced by ChatGPT's "Export data"
+ * feature and imports each conversation into the target `SqliteBrain`.
+ *
+ * ## Import strategy
+ *
+ * For each conversation object in `conversations.json`:
+ * 1. A row is inserted into the `conversations` table (deduped by title + created_at).
+ * 2. Every user/assistant message pair is encoded as an **episodic memory trace**
+ *    whose content is `"[user]: {user_text}\n[assistant]: {assistant_text}"`.
+ *    This preserves conversational context in a single retrievable unit.
+ * 3. System messages and tool messages are skipped (they are not episodic memories).
+ *
+ * ## ChatGPT export format
+ * ```json
+ * [
+ *   {
+ *     "title": "Conversation title",
+ *     "create_time": 1711234567.89,
+ *     "mapping": {
+ *       "node-id": {
+ *         "message": {
+ *           "author": { "role": "user" },
+ *           "content": { "parts": ["Hello!"] }
+ *         },
+ *         "children": ["next-node-id"]
+ *       }
+ *     }
+ *   }
+ * ]
+ * ```
+ *
+ * @module memory/io/ChatGptImporter
+ */
+import fs from 'node:fs/promises';
+import crypto from 'node:crypto';
+import { v4 as uuidv4 } from 'uuid';
+// ---------------------------------------------------------------------------
+// ChatGptImporter
+// ---------------------------------------------------------------------------
+/**
+ * Imports a ChatGPT `conversations.json` export into a `SqliteBrain`.
+ *
+ * **Usage:**
+ * ```ts
+ * const importer = new ChatGptImporter(brain);
+ * const result = await importer.import('/path/to/conversations.json');
+ * ```
+ */
+export class ChatGptImporter {
+    /**
+     * @param brain - The target `SqliteBrain` to import into.
+     */
+    constructor(brain) {
+        this.brain = brain;
+    }
+    // -------------------------------------------------------------------------
+    // Public API
+    // -------------------------------------------------------------------------
+    /**
+     * Parse `conversations.json` and import all conversations and message pairs.
+     *
+     * @param sourcePath - Absolute path to the ChatGPT `conversations.json` file.
+     * @returns `ImportResult` with counts of imported traces, skipped duplicates,
+     *   and any per-item error messages.
+     */
+    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 conversations;
+        try {
+            conversations = JSON.parse(raw);
+        }
+        catch (err) {
+            result.errors.push(`Invalid JSON: ${String(err)}`);
+            return result;
+        }
+        if (!Array.isArray(conversations)) {
+            result.errors.push('Expected a JSON array at the top level of conversations.json');
+            return result;
+        }
+        // ---- Process each conversation ----
+        for (const convo of conversations) {
+            try {
+                this._importConversation(convo, result);
+            }
+            catch (err) {
+                result.errors.push(`Conversation import error: ${String(err)}`);
+            }
+        }
+        return result;
+    }
+    // -------------------------------------------------------------------------
+    // Private helpers
+    // -------------------------------------------------------------------------
+    /**
+     * Import a single ChatGPT conversation object.
+     *
+     * Creates a `conversations` row and then iterates through the message
+     * mapping in tree order (BFS), pairing adjacent user/assistant messages
+     * into episodic memory traces.
+     *
+     * @param convo  - Raw ChatGPT conversation object.
+     * @param result - Mutable result accumulator.
+     */
+    _importConversation(convo, result) {
+        const db = this.brain.db;
+        const title = convo.title ?? 'Untitled';
+        const createdAt = convo.create_time ? Math.round(convo.create_time * 1000) : Date.now();
+        const updatedAt = convo.update_time ? Math.round(convo.update_time * 1000) : createdAt;
+        // Insert the conversation row (ignore duplicates by title + created_at).
+        const conversationId = `cv_${uuidv4()}`;
+        try {
+            db.prepare(`INSERT OR IGNORE INTO conversations (id, title, created_at, updated_at, metadata)
+         VALUES (?, ?, ?, ?, ?)`).run(conversationId, title, createdAt, updatedAt, JSON.stringify({ source: 'chatgpt_export' }));
+        }
+        catch (err) {
+            result.errors.push(`Conversation insert error for "${title}": ${String(err)}`);
+            return;
+        }
+        if (!convo.mapping)
+            return;
+        // ---- Extract messages in tree order ----
+        // The mapping is a flat record of nodes keyed by ID.  We use BFS starting
+        // from the root (node with no parent) to traverse in conversation order.
+        const nodes = convo.mapping;
+        // Find root node(s) — nodes with no parent or null parent.
+        const rootIds = Object.keys(nodes).filter((id) => !nodes[id]?.parent);
+        // Collect messages in BFS order.
+        const orderedMessages = [];
+        const queue = [...rootIds];
+        const visited = new Set();
+        while (queue.length > 0) {
+            const nodeId = queue.shift();
+            if (visited.has(nodeId))
+                continue;
+            visited.add(nodeId);
+            const node = nodes[nodeId];
+            if (!node)
+                continue;
+            const msg = node.message;
+            if (msg?.author?.role && msg.content?.parts) {
+                const textParts = msg.content.parts
+                    .filter((p) => typeof p === 'string')
+                    .join('');
+                if (textParts.trim()) {
+                    orderedMessages.push({
+                        role: msg.author.role,
+                        text: textParts,
+                        time: msg.create_time ? Math.round(msg.create_time * 1000) : createdAt,
+                    });
+                }
+            }
+            // Enqueue children in order.
+            for (const childId of node.children ?? []) {
+                if (!visited.has(childId)) {
+                    queue.push(childId);
+                }
+            }
+        }
+        // ---- Pair user + assistant messages into episodic traces ----
+        // We slide through the ordered messages and pair each user message with
+        // the immediately following assistant message.
+        for (let i = 0; i < orderedMessages.length; i++) {
+            const msg = orderedMessages[i];
+            // Skip system / tool messages.
+            if (msg.role === 'system' || msg.role === 'tool')
+                continue;
+            if (msg.role === 'user') {
+                // Look ahead for an assistant response.
+                const next = orderedMessages[i + 1];
+                const assistantText = next?.role === 'assistant' ? next.text : '';
+                const content = assistantText
+                    ? `[user]: ${msg.text}\n[assistant]: ${assistantText}`
+                    : `[user]: ${msg.text}`;
+                this._insertEpisodicTrace(content, msg.time, conversationId, result);
+                // Skip the assistant message on the next iteration if we consumed it.
+                if (assistantText)
+                    i++;
+            }
+        }
+    }
+    /**
+     * Insert a single episodic memory trace derived from a message pair.
+     *
+     * Deduplication is based on SHA-256 of the combined `content` string.
+     *
+     * @param content        - The `[user]:...\n[assistant]:...` content string.
+     * @param createdAt      - Unix timestamp (ms) of the user message.
+     * @param conversationId - ID of the parent conversation row.
+     * @param result         - Mutable result accumulator.
+     */
+    _insertEpisodicTrace(content, createdAt, conversationId, result) {
+        const hash = crypto.createHash('sha256').update(content, 'utf8').digest('hex');
+        // Dedup check.
+        const existing = this.brain.db
+            .prepare(`SELECT id FROM memory_traces WHERE json_extract(metadata, '$.import_hash') = ? LIMIT 1`)
+            .get(hash);
+        if (existing) {
+            result.skipped++;
+            return;
+        }
+        try {
+            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 (?, 'episodic', 'user', ?, NULL, 1.0, ?, NULL, 0, '[]', '{}', ?, 0)`)
+                .run(`mt_${uuidv4()}`, content, createdAt, JSON.stringify({
+                import_hash: hash,
+                source: 'chatgpt_export',
+                conversation_id: conversationId,
+            }));
+            result.imported++;
+        }
+        catch (err) {
+            result.errors.push(`Trace insert error: ${String(err)}`);
+        }
+    }
+}
+//# sourceMappingURL=ChatGptImporter.js.map

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

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

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

@@ -0,0 +1,67 @@
+/**
+ * @fileoverview JSON exporter for AgentOS memory brain.
+ *
+ * Serialises all memory traces, knowledge graph nodes/edges, documents, and
+ * conversations from a `SqliteBrain` into a single structured JSON file.
+ * Optionally includes raw embedding vectors encoded as base64 strings.
+ *
+ * ## Output shape
+ * ```json
+ * {
+ *   "meta": { "schema_version": "1", "exported_at": 1711234567890, ... },
+ *   "traces": [...],
+ *   "nodes": [...],
+ *   "edges": [...],
+ *   "documents": [...],
+ *   "conversations": [...]
+ * }
+ * ```
+ *
+ * @module memory/io/JsonExporter
+ */
+import type { ExportOptions } from '../facade/types.js';
+import type { SqliteBrain } from '../store/SqliteBrain.js';
+/**
+ * Exports a `SqliteBrain` to a structured JSON file.
+ *
+ * **Usage:**
+ * ```ts
+ * const exporter = new JsonExporter(brain);
+ * await exporter.export('/path/to/export.json', { includeEmbeddings: false });
+ * ```
+ */
+export declare class JsonExporter {
+    private readonly brain;
+    /**
+     * @param brain - The `SqliteBrain` instance to read from.
+     */
+    constructor(brain: SqliteBrain);
+    /**
+     * Export the full brain state to a JSON file at `outputPath`.
+     *
+     * @param outputPath       - Absolute path to write the JSON output.
+     * @param options          - Optional export configuration.
+     * @param options.includeEmbeddings   - When `true`, raw embedding BLOBs are
+     *   encoded as base64 strings and included in the output. Defaults to `false`.
+     * @param options.includeConversations - When `false`, conversation rows are
+     *   omitted from the output. Defaults to `true`.
+     */
+    export(outputPath: string, options?: ExportOptions): Promise<void>;
+    /**
+     * Serialise a single `memory_traces` row, optionally stripping the embedding.
+     *
+     * @param row               - Raw DB row.
+     * @param includeEmbeddings - Whether to encode the BLOB as base64.
+     * @returns Plain JS object safe for JSON serialisation.
+     */
+    private _serializeTrace;
+    /**
+     * Serialise a single `knowledge_nodes` row, optionally stripping the embedding.
+     *
+     * @param row               - Raw DB row.
+     * @param includeEmbeddings - Whether to encode the BLOB as base64.
+     * @returns Plain JS object safe for JSON serialisation.
+     */
+    private _serializeNode;
+}
+//# sourceMappingURL=JsonExporter.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"JsonExporter.d.ts","sourceRoot":"","sources":["../../../src/memory/io/JsonExporter.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAGH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AACxD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,yBAAyB,CAAC;AAwE3D;;;;;;;;GAQG;AACH,qBAAa,YAAY;IAIX,OAAO,CAAC,QAAQ,CAAC,KAAK;IAHlC;;OAEG;gBAC0B,KAAK,EAAE,WAAW;IAM/C;;;;;;;;;OASG;IACG,MAAM,CAAC,UAAU,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,aAAa,GAAG,OAAO,CAAC,IAAI,CAAC;IA6DxE;;;;;;OAMG;IACH,OAAO,CAAC,eAAe;IAQvB;;;;;;OAMG;IACH,OAAO,CAAC,cAAc;CAOvB"}

package/dist/memory/io/JsonExporter.js

@@ -0,0 +1,132 @@
+/**
+ * @fileoverview JSON exporter for AgentOS memory brain.
+ *
+ * Serialises all memory traces, knowledge graph nodes/edges, documents, and
+ * conversations from a `SqliteBrain` into a single structured JSON file.
+ * Optionally includes raw embedding vectors encoded as base64 strings.
+ *
+ * ## Output shape
+ * ```json
+ * {
+ *   "meta": { "schema_version": "1", "exported_at": 1711234567890, ... },
+ *   "traces": [...],
+ *   "nodes": [...],
+ *   "edges": [...],
+ *   "documents": [...],
+ *   "conversations": [...]
+ * }
+ * ```
+ *
+ * @module memory/io/JsonExporter
+ */
+import fs from 'node:fs/promises';
+// ---------------------------------------------------------------------------
+// JsonExporter
+// ---------------------------------------------------------------------------
+/**
+ * Exports a `SqliteBrain` to a structured JSON file.
+ *
+ * **Usage:**
+ * ```ts
+ * const exporter = new JsonExporter(brain);
+ * await exporter.export('/path/to/export.json', { includeEmbeddings: false });
+ * ```
+ */
+export class JsonExporter {
+    /**
+     * @param brain - The `SqliteBrain` instance to read from.
+     */
+    constructor(brain) {
+        this.brain = brain;
+    }
+    // -------------------------------------------------------------------------
+    // Public API
+    // -------------------------------------------------------------------------
+    /**
+     * Export the full brain state to a JSON file at `outputPath`.
+     *
+     * @param outputPath       - Absolute path to write the JSON output.
+     * @param options          - Optional export configuration.
+     * @param options.includeEmbeddings   - When `true`, raw embedding BLOBs are
+     *   encoded as base64 strings and included in the output. Defaults to `false`.
+     * @param options.includeConversations - When `false`, conversation rows are
+     *   omitted from the output. Defaults to `true`.
+     */
+    async export(outputPath, options) {
+        const includeEmbeddings = options?.includeEmbeddings ?? false;
+        const includeConversations = options?.includeConversations ?? true;
+        const db = this.brain.db;
+        // Collect brain_meta as a plain object for the `meta` field.
+        const metaRows = db
+            .prepare('SELECT key, value FROM brain_meta')
+            .all();
+        const meta = {};
+        for (const row of metaRows) {
+            meta[row.key] = row.value;
+        }
+        meta['exported_at'] = String(Date.now());
+        // ---- memory_traces ----
+        const rawTraces = db
+            .prepare('SELECT * FROM memory_traces')
+            .all();
+        const traces = rawTraces.map((row) => this._serializeTrace(row, includeEmbeddings));
+        // ---- knowledge_nodes ----
+        const rawNodes = db
+            .prepare('SELECT * FROM knowledge_nodes')
+            .all();
+        const nodes = rawNodes.map((row) => this._serializeNode(row, includeEmbeddings));
+        // ---- knowledge_edges ----
+        const edges = db
+            .prepare('SELECT * FROM knowledge_edges')
+            .all();
+        // ---- documents ----
+        const documents = db
+            .prepare('SELECT * FROM documents')
+            .all();
+        // ---- conversations ----
+        const conversations = includeConversations
+            ? db.prepare('SELECT * FROM conversations').all()
+            : [];
+        const payload = {
+            meta,
+            traces,
+            nodes,
+            edges,
+            documents,
+            conversations,
+        };
+        await fs.writeFile(outputPath, JSON.stringify(payload, null, 2), 'utf8');
+    }
+    // -------------------------------------------------------------------------
+    // Private helpers
+    // -------------------------------------------------------------------------
+    /**
+     * Serialise a single `memory_traces` row, optionally stripping the embedding.
+     *
+     * @param row               - Raw DB row.
+     * @param includeEmbeddings - Whether to encode the BLOB as base64.
+     * @returns Plain JS object safe for JSON serialisation.
+     */
+    _serializeTrace(row, includeEmbeddings) {
+        const out = { ...row };
+        if (row.embedding instanceof Buffer) {
+            out['embedding'] = includeEmbeddings ? row.embedding.toString('base64') : undefined;
+        }
+        return out;
+    }
+    /**
+     * Serialise a single `knowledge_nodes` row, optionally stripping the embedding.
+     *
+     * @param row               - Raw DB row.
+     * @param includeEmbeddings - Whether to encode the BLOB as base64.
+     * @returns Plain JS object safe for JSON serialisation.
+     */
+    _serializeNode(row, includeEmbeddings) {
+        const out = { ...row };
+        if (row.embedding instanceof Buffer) {
+            out['embedding'] = includeEmbeddings ? row.embedding.toString('base64') : undefined;
+        }
+        return out;
+    }
+}
+//# sourceMappingURL=JsonExporter.js.map

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

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

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

@@ -0,0 +1,84 @@
+/**
+ * @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 type { ImportResult } from '../facade/types.js';
+import type { SqliteBrain } from '../store/SqliteBrain.js';
+/**
+ * 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 declare class JsonImporter {
+    private readonly brain;
+    /**
+     * @param brain - The target `SqliteBrain` to import into.
+     */
+    constructor(brain: SqliteBrain);
+    /**
+     * 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.
+     */
+    import(sourcePath: string): Promise<ImportResult>;
+    /**
+     * 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.
+     */
+    private _sha256;
+    /**
+     * 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.
+     */
+    private _importTraces;
+    /**
+     * 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.
+     */
+    private _importNodes;
+    /**
+     * 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.
+     */
+    private _importEdges;
+}
+//# sourceMappingURL=JsonImporter.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"JsonImporter.d.ts","sourceRoot":"","sources":["../../../src/memory/io/JsonImporter.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAKH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AACvD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,yBAAyB,CAAC;AAsF3D;;;;;;;;;GASG;AACH,qBAAa,YAAY;IAIX,OAAO,CAAC,QAAQ,CAAC,KAAK;IAHlC;;OAEG;gBAC0B,KAAK,EAAE,WAAW;IAM/C;;;;;;;;;;;;;;;OAeG;IACG,MAAM,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,CAAC;IAuCvD;;;;;;OAMG;IACH,OAAO,CAAC,OAAO;IAIf;;;;;;;;OAQG;IACH,OAAO,CAAC,aAAa;IAgErB;;;;;;;OAOG;IACH,OAAO,CAAC,YAAY;IAqDpB;;;;;;;;OAQG;IACH,OAAO,CAAC,YAAY;CAsDrB"}