@engramx/openclaw 0.1.0-rc.2

package/dist/index.js

@@ -0,0 +1,951 @@
+/**
+ * OpenClaw Memory Plugin: EngramX (Hybrid Architecture)
+ *
+ * This plugin uses a hybrid approach:
+ *
+ *   EngramX canister  = source of truth for markdown memory files
+ *   Local SQLite       = performance cache for search (vector + FTS5)
+ *   EngramX backup API = disaster recovery for the SQLite database
+ *
+ * How it works:
+ *   1. Local SQLite search (memory_search / memory_get) — delegated to
+ *      OpenClaw's built-in memory-core runtime, which uses sqlite-vec
+ *      and FTS5 for sub-100ms hybrid search. Never queries the canister.
+ *
+ *   2. Memory file sync — pulls markdown files from the engram canister
+ *      to the local memory/ directory on startup and periodically. Local
+ *      file changes are pushed back to the canister. The existing SQLite
+ *      indexer watches these files and re-chunks/embeds automatically.
+ *
+ *   3. Database backup — auto-detects active databases (SQLite, QMD,
+ *      LanceDB) from openclaw.json and periodically uploads snapshots
+ *      to the engram canister's backup API for disaster recovery.
+ *
+ *   4. Session sync — serializes conversation transcripts to JSONL files
+ *      stored in the canister under sessions/{agentId}/{key}.jsonl.
+ *
+ *   5. Supplementary engram_* tools — direct canister access for wallet,
+ *      audit log, and cross-machine memory retrieval.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { createHash, randomBytes } from 'node:crypto';
+import { execFileSync } from 'node:child_process';
+import { tmpdir } from 'node:os';
+import { Type } from '@sinclair/typebox';
+import { EngramClient } from '@engramx/client';
+import { engramxConfigSchema } from './config.js';
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+const BACKUP_CHUNK_SIZE = 1_900_000; // ~1.9 MiB, under ICP's 2 MiB limit
+const MAX_BACKUP_SIZE = 500 * 1024 * 1024; // 500 MiB limit
+const SQLITE3_TIMEOUT_MS = 30_000;
+const NS_PER_MS = 1_000_000;
+const E8S_PER_ICP = 100_000_000;
+const TAR_TIMEOUT_MS = 120_000;
+const DB_TYPES = {
+    sqlite: 'openclaw-sqlite',
+    qmd: 'openclaw-qmd',
+    lancedb: 'openclaw-lancedb',
+};
+function loadOpenClawConfig(stateDir) {
+    const configPath = process.env['OPENCLAW_CONFIG_PATH'] ?? path.join(stateDir, 'openclaw.json');
+    if (!fs.existsSync(configPath))
+        return {};
+    try {
+        return JSON.parse(fs.readFileSync(configPath, 'utf-8'));
+    }
+    catch {
+        return {};
+    }
+}
+// ---------------------------------------------------------------------------
+// Config-driven database detection
+// ---------------------------------------------------------------------------
+function detectDatabases(stateDir) {
+    const ocConfig = loadOpenClawConfig(stateDir);
+    const detected = [];
+    const backend = ocConfig.memory?.backend ?? 'builtin';
+    // SQLite (builtin) — active when memory.backend is "builtin" or absent
+    if (backend === 'builtin') {
+        const storePath = ocConfig.agents?.defaults?.memorySearch?.store?.path;
+        let baseDir;
+        if (storePath) {
+            baseDir = path.dirname(storePath.replace(/\{agentId\}/g, '*'));
+            if (baseDir.includes('*')) {
+                baseDir = path.dirname(storePath.replace(/\{agentId\}.*$/, ''));
+            }
+        }
+        else {
+            baseDir = path.join(stateDir, 'memory');
+        }
+        const sqliteFiles = findFilesByExt(baseDir, '.sqlite');
+        if (sqliteFiles.length > 0) {
+            detected.push({
+                dbType: DB_TYPES.sqlite,
+                suffix: 'sqlite',
+                label: 'SQLite (builtin)',
+                filePaths: sqliteFiles,
+                isDirectory: false,
+            });
+        }
+    }
+    // QMD — active when memory.backend === "qmd"
+    if (backend === 'qmd') {
+        const agentsDir = path.join(stateDir, 'agents');
+        const qmdFiles = [];
+        if (fs.existsSync(agentsDir)) {
+            for (const entry of fs.readdirSync(agentsDir, { withFileTypes: true })) {
+                if (!entry.isDirectory())
+                    continue;
+                const qmdDir = path.join(agentsDir, entry.name, 'qmd');
+                if (fs.existsSync(qmdDir)) {
+                    qmdFiles.push(...findFilesByExt(qmdDir, '.sqlite'));
+                    qmdFiles.push(...findFilesByExt(qmdDir, '.db'));
+                }
+            }
+        }
+        if (qmdFiles.length > 0) {
+            detected.push({
+                dbType: DB_TYPES.qmd,
+                suffix: 'qmd',
+                label: 'QMD (experimental)',
+                filePaths: qmdFiles,
+                isDirectory: false,
+            });
+        }
+    }
+    // LanceDB — active when plugins.slots.memory === "memory-lancedb" and enabled
+    if (ocConfig.plugins?.slots?.memory === 'memory-lancedb') {
+        const lanceEntry = ocConfig.plugins?.entries?.['memory-lancedb'];
+        if (lanceEntry?.enabled !== false) {
+            const dbPath = lanceEntry?.config?.dbPath ?? path.join(stateDir, 'memory', 'lancedb');
+            if (fs.existsSync(dbPath) && fs.statSync(dbPath).isDirectory()) {
+                detected.push({
+                    dbType: DB_TYPES.lancedb,
+                    suffix: 'lancedb',
+                    label: 'LanceDB (plugin)',
+                    filePaths: [dbPath],
+                    isDirectory: true,
+                });
+            }
+        }
+    }
+    return detected;
+}
+function findFilesByExt(dir, ext) {
+    if (!fs.existsSync(dir))
+        return [];
+    try {
+        return fs
+            .readdirSync(dir, { withFileTypes: true })
+            .filter((e) => e.isFile() && e.name.endsWith(ext))
+            .map((e) => path.join(dir, e.name));
+    }
+    catch {
+        return [];
+    }
+}
+// ---------------------------------------------------------------------------
+// Backup strategies
+// ---------------------------------------------------------------------------
+function snapshotSqliteFile(dbPath, logger) {
+    const tmpPath = path.join(fs.mkdtempSync(path.join(tmpdir(), 'engramx-sqlite-')), `backup-${randomBytes(8).toString('hex')}.sqlite`);
+    try {
+        execFileSync('sqlite3', [dbPath, `.backup '${tmpPath.replace(/'/g, "''")}'`], {
+            timeout: SQLITE3_TIMEOUT_MS,
+            stdio: 'pipe',
+        });
+        return fs.readFileSync(tmpPath);
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        if (msg.includes('ENOENT') || msg.includes('not found')) {
+            logger?.warn('memory-engramx: sqlite3 CLI not available, falling back to direct file read. ' +
+                'WAL data may not be included.');
+            return fs.readFileSync(dbPath);
+        }
+        throw err;
+    }
+    finally {
+        try {
+            fs.rmSync(path.dirname(tmpPath), { recursive: true, force: true });
+        }
+        catch {
+            /* best-effort */
+        }
+    }
+}
+function tarDirectory(dirPath) {
+    const tmpDir = fs.mkdtempSync(path.join(tmpdir(), 'engramx-tar-'));
+    const tarPath = path.join(tmpDir, 'backup.tar.gz');
+    try {
+        execFileSync('tar', ['-czf', tarPath, '-C', path.dirname(dirPath), path.basename(dirPath)], {
+            timeout: TAR_TIMEOUT_MS,
+            stdio: 'pipe',
+        });
+        return fs.readFileSync(tarPath);
+    }
+    finally {
+        try {
+            fs.rmSync(tmpDir, { recursive: true, force: true });
+        }
+        catch {
+            /* best-effort */
+        }
+    }
+}
+function snapshotAndTarMultiple(filePaths, logger) {
+    const tmpDir = fs.mkdtempSync(path.join(tmpdir(), 'engramx-qmd-'));
+    try {
+        for (const fp of filePaths) {
+            const data = snapshotSqliteFile(fp, logger);
+            fs.writeFileSync(path.join(tmpDir, Buffer.from(fp).toString('base64url') + '.sqlite'), data);
+        }
+        const tarPath = path.join(tmpDir, 'backup.tar.gz');
+        execFileSync('tar', ['-czf', tarPath, '-C', tmpDir, '--exclude', 'backup.tar.gz', '.'], {
+            timeout: TAR_TIMEOUT_MS,
+            stdio: 'pipe',
+        });
+        return fs.readFileSync(tarPath);
+    }
+    finally {
+        try {
+            fs.rmSync(tmpDir, { recursive: true, force: true });
+        }
+        catch {
+            /* best-effort */
+        }
+    }
+}
+function prepareBackupData(db, logger) {
+    if (db.suffix === 'sqlite') {
+        return db.filePaths.length === 1
+            ? snapshotSqliteFile(db.filePaths[0], logger)
+            : snapshotAndTarMultiple(db.filePaths, logger);
+    }
+    if (db.suffix === 'qmd') {
+        return snapshotAndTarMultiple(db.filePaths, logger);
+    }
+    if (db.suffix === 'lancedb') {
+        return tarDirectory(db.filePaths[0]);
+    }
+    throw new Error(`Unknown database suffix: ${db.suffix}`);
+}
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+function resolveMemoryDir(api, override) {
+    if (override)
+        return api.resolvePath(override);
+    // Default: workspace memory directory that OpenClaw watches
+    return api.resolvePath('memory');
+}
+function sha256Buffer(data) {
+    return createHash('sha256').update(data).digest('hex');
+}
+// ---------------------------------------------------------------------------
+// Plugin definition
+// ---------------------------------------------------------------------------
+const memoryEngramXPlugin = {
+    id: 'memory-engramx',
+    name: 'Memory (EngramX)',
+    description: 'Hybrid memory: local SQLite search + EngramX canister as source of truth',
+    kind: 'memory',
+    configSchema: engramxConfigSchema,
+    register(api) {
+        const cfg = engramxConfigSchema.parse(api.pluginConfig);
+        const memoryDir = resolveMemoryDir(api, cfg.memoryDir);
+        const engram = new EngramClient({
+            canisterId: cfg.canisterId,
+            sessionKeyPath: cfg.sessionKeyPath,
+            host: cfg.host,
+            cacheMaxAge: 60_000,
+        });
+        api.logger.info(`memory-engramx: registered (canister: ${cfg.canisterId}, host: ${cfg.host ?? 'https://ic0.app'})`);
+        // ========================================================================
+        // 1. Local search — delegate to built-in memory-core runtime
+        // ========================================================================
+        api.registerTool((ctx) => {
+            const memorySearchTool = api.runtime.tools.createMemorySearchTool({
+                config: ctx.config,
+                agentSessionKey: ctx.sessionKey,
+            });
+            const memoryGetTool = api.runtime.tools.createMemoryGetTool({
+                config: ctx.config,
+                agentSessionKey: ctx.sessionKey,
+            });
+            if (!memorySearchTool || !memoryGetTool) {
+                return null;
+            }
+            return [memorySearchTool, memoryGetTool];
+        }, { names: ['memory_search', 'memory_get'] });
+        api.registerCli(({ program }) => {
+            api.runtime.tools.registerMemoryCli(program);
+        }, { commands: ['memory'] });
+        /** Pull all memory files from engram canister → local memory/ dir */
+        async function pullMemoryFiles() {
+            const remoteFiles = await engram.listMemoryFiles();
+            const remotePaths = new Set(remoteFiles.map((f) => f.path));
+            const result = { pulled: [], deleted: [] };
+            for (const info of remoteFiles) {
+                const localPath = path.join(memoryDir, info.path);
+                // Guard against path traversal from canister-supplied paths
+                const resolvedLocal = path.resolve(localPath);
+                if (!resolvedLocal.startsWith(memoryDir + path.sep) && resolvedLocal !== memoryDir) {
+                    api.logger.warn(`memory-engramx: Path traversal blocked: ${info.path}`);
+                    continue;
+                }
+                const localDir = path.dirname(localPath);
+                let needsPull = true;
+                let remoteContent = null;
+                try {
+                    const remote = await engram.readMemory(info.path);
+                    remoteContent = remote.content;
+                    const localContent = fs.readFileSync(localPath, 'utf-8');
+                    const localHash = createHash('sha256').update(localContent).digest('hex');
+                    const remoteHash = createHash('sha256').update(remoteContent).digest('hex');
+                    if (localHash === remoteHash) {
+                        needsPull = false;
+                    }
+                }
+                catch {
+                    // File doesn't exist locally or read error — pull it
+                }
+                if (needsPull) {
+                    if (!remoteContent) {
+                        const remote = await engram.readMemory(info.path);
+                        remoteContent = remote.content;
+                    }
+                    fs.mkdirSync(localDir, { recursive: true });
+                    const lstat = fs.lstatSync(localPath, { throwIfNoEntry: false });
+                    if (lstat && lstat.isSymbolicLink()) {
+                        throw new Error(`Symlink not allowed: ${localPath}`);
+                    }
+                    fs.writeFileSync(localPath, remoteContent, 'utf-8');
+                    result.pulled.push(info.path);
+                }
+            }
+            // Detect local .md files that no longer exist on the canister (owner deleted via frontend)
+            function collectLocalMd(dir) {
+                const paths = [];
+                if (!fs.existsSync(dir))
+                    return paths;
+                for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+                    if (entry.name.startsWith('.'))
+                        continue;
+                    const full = path.join(dir, entry.name);
+                    if (entry.isDirectory()) {
+                        paths.push(...collectLocalMd(full));
+                    }
+                    else if (entry.isFile() && entry.name.endsWith('.md')) {
+                        paths.push(path.relative(memoryDir, full));
+                    }
+                }
+                return paths;
+            }
+            const localFiles = collectLocalMd(memoryDir);
+            const toDelete = localFiles.filter((f) => !remotePaths.has(f));
+            if (toDelete.length > localFiles.length / 2 && toDelete.length > 5) {
+                api.logger.warn(`memory-engramx: bulk deletion blocked (${toDelete.length}/${localFiles.length} files) — possible canister data loss`);
+            }
+            else {
+                for (const localRel of toDelete) {
+                    const localPath = path.join(memoryDir, localRel);
+                    try {
+                        fs.unlinkSync(localPath);
+                        result.deleted.push(localRel);
+                    }
+                    catch {
+                        // best-effort
+                    }
+                }
+            }
+            return result;
+        }
+        /** Push a local memory file → engram canister */
+        async function pushMemoryFile(filePath) {
+            const relativePath = path.relative(memoryDir, filePath);
+            const resolvedPush = path.resolve(memoryDir, relativePath);
+            if (!resolvedPush.startsWith(memoryDir + path.sep) && resolvedPush !== memoryDir)
+                return;
+            const content = fs.readFileSync(filePath, 'utf-8');
+            await engram.appendMemory(relativePath, content);
+        }
+        /** Full bidirectional sync */
+        async function syncMemoryFiles() {
+            // Pull remote → local
+            const pullResult = await pullMemoryFiles();
+            // Push local → remote (files that don't exist remotely)
+            let pushed = 0;
+            const pushedFiles = [];
+            const remoteFiles = await engram.listMemoryFiles();
+            const remotePaths = new Set(remoteFiles.map((f) => f.path));
+            const pushPromises = [];
+            function walkDir(dir) {
+                if (!fs.existsSync(dir))
+                    return;
+                for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+                    const full = path.join(dir, entry.name);
+                    if (entry.isDirectory()) {
+                        walkDir(full);
+                    }
+                    else if (entry.isFile() && entry.name.endsWith('.md')) {
+                        const rel = path.relative(memoryDir, full);
+                        if (!remotePaths.has(rel)) {
+                            pushPromises.push(pushMemoryFile(full)
+                                .then(() => {
+                                pushed++;
+                                pushedFiles.push(rel);
+                            })
+                                .catch((err) => api.logger.warn(`memory-engramx: push failed for ${rel}: ${String(err)}`)));
+                        }
+                    }
+                }
+            }
+            walkDir(memoryDir);
+            await Promise.allSettled(pushPromises);
+            // Also sync top-level MEMORY.md if it exists. Operators can append-create
+            // a non-existent file but cannot overwrite an existing one (append-only).
+            // The `!remotePaths.has(...)` check above ensures this is a first-time push.
+            const topMemory = path.resolve(path.dirname(memoryDir), 'MEMORY.md');
+            if (fs.existsSync(topMemory) && !remotePaths.has('MEMORY.md')) {
+                try {
+                    const content = fs.readFileSync(topMemory, 'utf-8');
+                    await engram.appendMemory('MEMORY.md', content);
+                    pushed++;
+                    pushedFiles.push('MEMORY.md');
+                }
+                catch (err) {
+                    api.logger.warn(`memory-engramx: push MEMORY.md failed: ${String(err)}`);
+                }
+            }
+            // Build descriptive commit message
+            let commitMessage = null;
+            const parts = [];
+            if (pullResult.pulled.length > 0) {
+                parts.push(`pulled ${pullResult.pulled.join(', ')}`);
+            }
+            if (pullResult.deleted.length > 0) {
+                parts.push(`deleted ${pullResult.deleted.join(', ')}`);
+            }
+            if (pushedFiles.length > 0) {
+                parts.push(`pushed ${pushedFiles.join(', ')}`);
+            }
+            if (parts.length > 0) {
+                commitMessage = `engramx: sync — ${parts.join('; ')}`;
+                api.logger.info(`memory-engramx: synced (${parts.join(', ')})`);
+            }
+            return { pullResult, pushed, commitMessage };
+        }
+        // ========================================================================
+        // 3. Git versioning (memory dir → git repo → GitHub)
+        // ========================================================================
+        function gitExec(args) {
+            try {
+                return execFileSync('git', args, {
+                    cwd: memoryDir,
+                    stdio: 'pipe',
+                    timeout: 30_000,
+                })
+                    .toString()
+                    .trim();
+            }
+            catch {
+                return null;
+            }
+        }
+        function gitIsRepo() {
+            return gitExec(['rev-parse', '--is-inside-work-tree']) === 'true';
+        }
+        function gitHasRemote() {
+            const remotes = gitExec(['remote']);
+            return remotes !== null && remotes.length > 0;
+        }
+        function gitInit() {
+            if (gitIsRepo())
+                return true;
+            const result = gitExec(['init']);
+            if (result === null)
+                return false;
+            // Create .gitignore for non-markdown artifacts
+            const gitignorePath = path.join(memoryDir, '.gitignore');
+            if (!fs.existsSync(gitignorePath)) {
+                fs.writeFileSync(gitignorePath, [
+                    '# Auto-generated by memory-engramx',
+                    '*.sqlite',
+                    '*.sqlite-wal',
+                    '*.sqlite-shm',
+                    '*.db',
+                    '*.db-wal',
+                    '*.db-shm',
+                    'lancedb/',
+                    '.DS_Store',
+                    '',
+                ].join('\n'));
+            }
+            return true;
+        }
+        function gitCommit(msg) {
+            // Stage all changes in memory dir
+            if (gitExec(['add', '-A']) === null)
+                return false;
+            // Check if there are staged changes
+            const status = gitExec(['diff', '--cached', '--stat']);
+            if (!status)
+                return false; // nothing to commit
+            const commitMsg = msg ?? `engramx: sync ${new Date().toISOString()}`;
+            // Use execFileSync (array form) to avoid shell injection via commit message
+            try {
+                execFileSync('git', ['commit', '-m', commitMsg], {
+                    cwd: memoryDir,
+                    stdio: 'pipe',
+                    timeout: 30_000,
+                });
+                return true;
+            }
+            catch {
+                return false;
+            }
+        }
+        function gitPush() {
+            if (!gitHasRemote())
+                return false;
+            return gitExec(['push']) !== null;
+        }
+        // ========================================================================
+        // 4. Database backup (config-driven detection → engram backup API)
+        // ========================================================================
+        async function backupAllDatabases() {
+            const stateDir = process.env['OPENCLAW_STATE_DIR'] || path.join(process.env['HOME'] || '', '.openclaw');
+            const databases = detectDatabases(stateDir);
+            const result = { backed: [], skipped: [] };
+            if (databases.length === 0) {
+                api.logger.info('memory-engramx: no databases detected for backup');
+                return result;
+            }
+            for (const db of databases) {
+                try {
+                    api.logger.info(`memory-engramx: preparing backup for ${db.label}...`);
+                    const data = prepareBackupData(db, api.logger);
+                    if (data.length > MAX_BACKUP_SIZE) {
+                        api.logger.warn(`memory-engramx: ${db.label} backup is ${(data.length / 1024 / 1024).toFixed(0)} MiB, ` +
+                            `exceeds ${MAX_BACKUP_SIZE / 1024 / 1024} MiB limit — skipping`);
+                        result.skipped.push(`${db.label} (too large)`);
+                        continue;
+                    }
+                    // SHA-256 dedup: skip if latest finalized backup matches
+                    const hash = sha256Buffer(data);
+                    const existing = await engram.latestBackupMatchesHash(db.dbType, hash);
+                    if (existing) {
+                        api.logger.info(`memory-engramx: ${db.label}: sha256 match (${existing.backupId}), skipping`);
+                        result.skipped.push(`${db.label} (unchanged)`);
+                        continue;
+                    }
+                    const label = cfg.backup.dbLabel || `${db.suffix}-${new Date().toISOString().slice(0, 10)}`;
+                    const backupId = await engram.initBackup(db.dbType, { FullSnapshot: null }, null, hash, label);
+                    let chunkIndex = 0;
+                    for (let offset = 0; offset < data.length; offset += BACKUP_CHUNK_SIZE) {
+                        const chunk = new Uint8Array(data.buffer, data.byteOffset + offset, Math.min(BACKUP_CHUNK_SIZE, data.length - offset));
+                        await engram.pushBackupChunk(backupId, chunkIndex, chunk);
+                        chunkIndex++;
+                    }
+                    await engram.finalizeBackup(backupId);
+                    api.logger.info(`memory-engramx: ${db.label} backed up (${chunkIndex} chunks, id: ${backupId}, sha256: ${hash})`);
+                    result.backed.push(db.label);
+                }
+                catch (err) {
+                    api.logger.warn(`memory-engramx: backup failed for ${db.label}: ${String(err)}`);
+                    result.skipped.push(`${db.label} (error)`);
+                }
+            }
+            return result;
+        }
+        // ========================================================================
+        // 5. Supplementary engram_* tools (direct canister access)
+        // ========================================================================
+        api.registerTool({
+            name: 'engram_read_memory',
+            label: 'Engram Read Memory',
+            description: 'Read a memory file directly from the engram canister (for cross-machine access or verification)',
+            parameters: Type.Object({
+                path: Type.String({ description: 'File path in the engram' }),
+            }),
+            async execute(_toolCallId, params) {
+                const { path: filePath } = params;
+                const file = await engram.readMemory(filePath);
+                return {
+                    content: [{ type: 'text', text: file.content }],
+                    details: { path: filePath, version: Number(file.version) },
+                };
+            },
+        }, { name: 'engram_read_memory' });
+        api.registerTool({
+            name: 'engram_append_memory',
+            label: 'Engram Append Memory',
+            description: 'Append content to a memory file. Writes to both the engram canister (source of truth) and local disk (for SQLite indexing). Owner-protected paths (e.g. SOUL.md) are read-only for operators.',
+            parameters: Type.Object({
+                path: Type.String({ description: 'File path' }),
+                content: Type.String({ description: 'Content to append' }),
+            }),
+            async execute(_toolCallId, params) {
+                const { path: filePath, content } = params;
+                // Validate path before any canister or disk writes
+                if (cfg.sync.pushOnWrite) {
+                    const localPath = path.join(memoryDir, filePath);
+                    const resolvedAppend = path.resolve(localPath);
+                    if (!resolvedAppend.startsWith(memoryDir + path.sep) && resolvedAppend !== memoryDir) {
+                        return {
+                            content: [{ type: 'text', text: `Path traversal blocked: ${filePath}` }],
+                            details: { error: 'path_traversal' },
+                        };
+                    }
+                }
+                // Write to engram canister (source of truth)
+                const version = await engram.appendMemory(filePath, content);
+                // Write to local disk so SQLite indexer picks it up
+                if (cfg.sync.pushOnWrite) {
+                    const localPath = path.join(memoryDir, filePath);
+                    const localDir = path.dirname(localPath);
+                    fs.mkdirSync(localDir, { recursive: true });
+                    // Symlink check before writing
+                    const lstat = fs.lstatSync(localPath, { throwIfNoEntry: false });
+                    if (lstat && lstat.isSymbolicLink()) {
+                        throw new Error(`Symlink not allowed: ${localPath}`);
+                    }
+                    // Append to local file (matching what was sent to the canister)
+                    if (fs.existsSync(localPath)) {
+                        fs.appendFileSync(localPath, '\n' + content, 'utf-8');
+                    }
+                    else {
+                        fs.writeFileSync(localPath, content, 'utf-8');
+                    }
+                }
+                if (cfg.git.enabled) {
+                    gitCommit(`engramx: append to ${filePath}`);
+                }
+                return {
+                    content: [{ type: 'text', text: `Appended to ${filePath} (version ${version})` }],
+                    details: { path: filePath, version: Number(version) },
+                };
+            },
+        }, { name: 'engram_append_memory' });
+        api.registerTool({
+            name: 'engram_list_memory',
+            label: 'Engram List Memory',
+            description: 'List all memory files stored in the engram canister',
+            parameters: Type.Object({}),
+            async execute() {
+                const files = await engram.listMemoryFiles();
+                if (files.length === 0) {
+                    return {
+                        content: [{ type: 'text', text: 'No memory files in engram.' }],
+                        details: { count: 0 },
+                    };
+                }
+                const text = files
+                    .map((f) => `${f.path} (v${f.version}, modified ${new Date(Number(f.lastModifiedAt) / NS_PER_MS).toISOString()})`)
+                    .join('\n');
+                return {
+                    content: [{ type: 'text', text }],
+                    details: { count: files.length },
+                };
+            },
+        }, { name: 'engram_list_memory' });
+        api.registerTool({
+            name: 'engram_wallet_balance',
+            label: 'Engram Wallet Balance',
+            description: 'Check the engram wallet balance',
+            parameters: Type.Object({}),
+            async execute() {
+                const balance = await engram.walletBalance();
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: `Balance: ${Number(balance) / E8S_PER_ICP} ICP`,
+                        },
+                    ],
+                    details: { balanceE8s: Number(balance) },
+                };
+            },
+        }, { name: 'engram_wallet_balance' });
+        // NOTE: no `engram_transfer` tool by design. Operators are append-only with
+        // zero owner-level fund control; the only money-moving canister method is the
+        // owner-only `ownerWithdraw`, never exposed to operators. (Removed: it called a
+        // non-existent `operatorTransfer` and advertised a fund-transfer capability
+        // that violates the operator invariant.)
+        // ========================================================================
+        // 6. CLI Commands
+        // ========================================================================
+        api.registerCli(({ program }) => {
+            const cmd = program
+                .command('engram')
+                .description('EngramX sync, backup, and canister commands');
+            cmd
+                .command('status')
+                .description('Show engram canister status')
+                .action(async () => {
+                const status = await engram.status();
+                console.log(`Canister:        ${cfg.canisterId}`);
+                console.log(`Host:            ${cfg.host ?? 'https://ic0.app'}`);
+                console.log(`Memory files:    ${status.memoryFileCount}`);
+                console.log(`Operators:       ${status.operatorCount}`);
+                console.log(`Audit log:       ${status.auditLogSize} entries`);
+                console.log(`Cycles:          ${status.cyclesBalance}`);
+                console.log(`Backups:         ${status.backupCount}`);
+                console.log(`Version:         ${status.version}`);
+                console.log(`Writes paused:   ${status.writesPaused}`);
+                console.log(`Payments frozen: ${status.paymentsFrozen}`);
+            });
+            cmd
+                .command('sync')
+                .description('Sync memory files between engram canister and local disk')
+                .action(async () => {
+                console.log('Syncing memory files...');
+                const result = await syncMemoryFiles();
+                const { pullResult, pushed } = result;
+                console.log(`Done. Pulled ${pullResult.pulled.length}, deleted ${pullResult.deleted.length}, pushed ${pushed}.`);
+                if (pullResult.pulled.length > 0)
+                    console.log(`  Pulled: ${pullResult.pulled.join(', ')}`);
+                if (pullResult.deleted.length > 0)
+                    console.log(`  Deleted: ${pullResult.deleted.join(', ')}`);
+            });
+            cmd
+                .command('backup')
+                .description('Backup detected databases to engram canister')
+                .action(async () => {
+                const stateDir = process.env['OPENCLAW_STATE_DIR'] ||
+                    path.join(process.env['HOME'] || '', '.openclaw');
+                const databases = detectDatabases(stateDir);
+                console.log(`Detected databases (${stateDir}):`);
+                if (databases.length === 0) {
+                    console.log('  (none)');
+                    return;
+                }
+                for (const db of databases) {
+                    const files = db.isDirectory
+                        ? `directory: ${db.filePaths[0]}`
+                        : `${db.filePaths.length} file(s)`;
+                    console.log(`  ${db.label} [${db.dbType}] — ${files}`);
+                }
+                console.log('');
+                const result = await backupAllDatabases();
+                console.log('');
+                console.log('Backup complete:');
+                console.log(`  Backed up: ${result.backed.length > 0 ? result.backed.join(', ') : '(none)'}`);
+                console.log(`  Skipped:   ${result.skipped.length > 0 ? result.skipped.join(', ') : '(none)'}`);
+            });
+            cmd
+                .command('restore')
+                .description('List available backups for restore')
+                .action(async () => {
+                const allBackups = await engram.listBackups();
+                if (allBackups.length === 0) {
+                    console.log('No backups found.');
+                    return;
+                }
+                // Group by dbType
+                const grouped = new Map();
+                for (const backup of allBackups) {
+                    const list = grouped.get(backup.dbType) ?? [];
+                    list.push(backup);
+                    grouped.set(backup.dbType, list);
+                }
+                for (const [dbType, backups] of grouped) {
+                    console.log(`\n${dbType}:`);
+                    const sorted = backups.sort((a, b) => Number(b.createdAt) - Number(a.createdAt));
+                    for (const b of sorted) {
+                        const status = 'Finalized' in b.status ? 'ok' : 'Uploading' in b.status ? 'uploading' : 'failed';
+                        const sizeMb = (Number(b.totalSize) / 1024 / 1024).toFixed(1);
+                        const created = new Date(Number(b.createdAt) / NS_PER_MS).toISOString();
+                        console.log(`  ${b.backupId}  ${status}  ${sizeMb} MiB  ${b.chunkCount} chunks  ${created}  ${b.backupLabel ?? ''}`);
+                    }
+                }
+                console.log('\nTo restore, download chunks and write to disk. See README for details.');
+            });
+            cmd
+                .command('git-status')
+                .description('Show git status and recent history for the memory directory')
+                .action(() => {
+                if (!cfg.git.enabled || !gitIsRepo()) {
+                    console.log('Git versioning is not enabled.');
+                    console.log('Run: npx @engramx/client git-setup <remote-url>');
+                    return;
+                }
+                const status = gitExec(['status', '--short']);
+                if (status) {
+                    console.log('Changes:');
+                    console.log(status);
+                }
+                else {
+                    console.log('Working tree clean.');
+                }
+                console.log('\nRecent commits:');
+                const log = gitExec(['log', '--oneline', '-5']);
+                console.log(log || '(no commits)');
+            });
+            cmd
+                .command('files')
+                .description('List memory files in the engram canister')
+                .action(async () => {
+                const files = await engram.listMemoryFiles();
+                if (files.length === 0) {
+                    console.log('No memory files.');
+                    return;
+                }
+                for (const f of files) {
+                    const modified = new Date(Number(f.lastModifiedAt) / NS_PER_MS).toISOString();
+                    console.log(`${f.path}  v${f.version}  ${modified}`);
+                }
+            });
+        }, { commands: ['engram'] });
+        // ========================================================================
+        // 7. Lifecycle Hooks
+        // ========================================================================
+        // Session sync: serialize transcript to JSONL and store as a file
+        // in the canister under sessions/{agentId}/{key}.jsonl
+        api.on('agent_end', async (event) => {
+            if (!event.success || !event.messages || event.messages.length === 0) {
+                return;
+            }
+            try {
+                const sessionKey = event.sessionKey;
+                const agentId = event.agentId;
+                if (typeof sessionKey !== 'string')
+                    return;
+                const agentSlug = typeof agentId === 'string' ? agentId : 'default';
+                const lines = [];
+                for (const msg of event.messages) {
+                    if (!msg || typeof msg !== 'object')
+                        continue;
+                    const m = msg;
+                    const role = m.role;
+                    const content = typeof m.content === 'string'
+                        ? m.content
+                        : Array.isArray(m.content)
+                            ? m.content
+                                .filter((b) => b.type === 'text')
+                                .map((b) => b.text)
+                                .join('\n')
+                            : '';
+                    if (!content)
+                        continue;
+                    lines.push(JSON.stringify({
+                        role,
+                        content,
+                        ts: new Date().toISOString(),
+                    }));
+                }
+                if (lines.length > 0) {
+                    const jsonlChunk = lines.join('\n') + '\n';
+                    const monthKey = new Date().toISOString().slice(0, 7); // "YYYY-MM"
+                    const sessionPath = `sessions/${agentSlug}/${monthKey}.jsonl`;
+                    await engram.appendMemory(sessionPath, jsonlChunk);
+                    api.logger.info(`memory-engramx: synced ${lines.length} messages to ${sessionPath}`);
+                }
+            }
+            catch (err) {
+                api.logger.warn(`memory-engramx: session sync failed: ${String(err)}`);
+            }
+        });
+        // ========================================================================
+        // 8. Service (startup sync + periodic sync/backup)
+        // ========================================================================
+        let syncInterval = null;
+        let backupInterval = null;
+        api.registerService({
+            id: 'memory-engramx',
+            async start() {
+                api.logger.info(`memory-engramx: starting (canister: ${cfg.canisterId})`);
+                // Sync memory files on startup
+                let startupSyncResult = null;
+                if (cfg.sync.onStartup) {
+                    try {
+                        startupSyncResult = await syncMemoryFiles();
+                        const { pullResult, pushed } = startupSyncResult;
+                        api.logger.info(`memory-engramx: startup sync complete (pulled ${pullResult.pulled.length}, deleted ${pullResult.deleted.length}, pushed ${pushed})`);
+                    }
+                    catch (err) {
+                        api.logger.warn(`memory-engramx: startup sync failed: ${String(err)}`);
+                    }
+                }
+                // Initialize git versioning
+                if (cfg.git.enabled) {
+                    if (!gitInit()) {
+                        api.logger.warn('memory-engramx: failed to initialize git repo in memory directory');
+                    }
+                    else {
+                        api.logger.info(`memory-engramx: git versioning active (${memoryDir})`);
+                        // Commit any files that exist after startup sync
+                        const msg = startupSyncResult?.commitMessage ?? 'engramx: startup sync';
+                        if (gitCommit(msg)) {
+                            api.logger.info('memory-engramx: git committed post-startup sync');
+                            if (cfg.git.pushOnSync)
+                                gitPush();
+                        }
+                    }
+                }
+                // Periodic memory file sync
+                let syncInProgress = false;
+                if (cfg.sync.intervalMinutes > 0) {
+                    syncInterval = setInterval(() => {
+                        if (syncInProgress) {
+                            api.logger.warn('memory-engramx: previous sync still in progress, skipping');
+                            return;
+                        }
+                        syncInProgress = true;
+                        syncMemoryFiles()
+                            .then((result) => {
+                            if (cfg.git.enabled && result.commitMessage) {
+                                if (gitCommit(result.commitMessage)) {
+                                    api.logger.info('memory-engramx: git committed sync changes');
+                                    if (cfg.git.pushOnSync)
+                                        gitPush();
+                                }
+                            }
+                        })
+                            .catch((err) => api.logger.warn(`memory-engramx: periodic sync failed: ${String(err)}`))
+                            .finally(() => {
+                            syncInProgress = false;
+                        });
+                    }, cfg.sync.intervalMinutes * 60 * 1000);
+                }
+                // Periodic database backup (all detected types)
+                if (cfg.backup.enabled && cfg.backup.intervalMinutes > 0) {
+                    backupInterval = setInterval(() => {
+                        backupAllDatabases().catch((err) => api.logger.warn(`memory-engramx: periodic backup failed: ${String(err)}`));
+                    }, cfg.backup.intervalMinutes * 60 * 1000);
+                }
+            },
+            stop() {
+                if (syncInterval) {
+                    clearInterval(syncInterval);
+                    syncInterval = null;
+                }
+                if (backupInterval) {
+                    clearInterval(backupInterval);
+                    backupInterval = null;
+                }
+                // Final git commit + push on shutdown
+                if (cfg.git.enabled) {
+                    if (gitCommit('engramx: shutdown snapshot')) {
+                        api.logger.info('memory-engramx: git committed on shutdown');
+                    }
+                    if (cfg.git.pushOnStop && gitHasRemote()) {
+                        if (gitPush()) {
+                            api.logger.info('memory-engramx: git pushed to remote');
+                        }
+                        else {
+                            api.logger.warn('memory-engramx: git push failed on shutdown');
+                        }
+                    }
+                }
+                api.logger.info('memory-engramx: stopped');
+            },
+        });
+    },
+};
+export default memoryEngramXPlugin;
+//# sourceMappingURL=index.js.map