agentic-qe 3.15.15 → 3.15.17

package/dist/integrations/agentic-flow/reasoning-bank/pattern-evolution.js

@@ -223,31 +223,38 @@ export class PatternEvolution {
      */
     async trackVersion(patternId, embedding, changes = [], trigger = 'manual') {
         this.ensureInitialized();
-        // Get current version count
-        const countStmt = this.prepared.get('getVersionCount');
-        const countResult = countStmt?.get(patternId);
-        const newVersion = (countResult?.count ?? 0) + 1;
-        // Get pattern quality/success rate
-        const patternStmt = this.prepared.get('getPattern');
-        const pattern = patternStmt?.get(patternId);
         const id = uuidv4();
-        const version = {
-            id,
-            patternId,
-            version: newVersion,
-            embedding,
-            changes,
-            qualityScore: pattern?.quality_score ?? 0.5,
-            successRate: pattern?.success_rate ?? 0.5,
-            timestamp: new Date(),
-            trigger,
-        };
-        // Store in database
-        const insertStmt = this.prepared.get('insertVersion');
-        if (insertStmt) {
-            const embeddingBuffer = this.floatArrayToBuffer(embedding);
-            insertStmt.run(id, patternId, newVersion, embeddingBuffer, embedding.length, JSON.stringify(changes), version.qualityScore, version.successRate, trigger);
-        }
+        const embeddingBuffer = this.floatArrayToBuffer(embedding);
+        // #1283: read the version count and insert the new version as one queued
+        // unit, so a locked memory.db does not freeze the MCP server and two
+        // concurrent calls cannot both claim the same version number.
+        const version = await this.write(() => {
+            // Get current version count
+            const countStmt = this.prepared.get('getVersionCount');
+            const countResult = countStmt?.get(patternId);
+            const newVersion = (countResult?.count ?? 0) + 1;
+            // Get pattern quality/success rate
+            const patternStmt = this.prepared.get('getPattern');
+            const pattern = patternStmt?.get(patternId);
+            const tracked = {
+                id,
+                patternId,
+                version: newVersion,
+                embedding,
+                changes,
+                qualityScore: pattern?.quality_score ?? 0.5,
+                successRate: pattern?.success_rate ?? 0.5,
+                timestamp: new Date(),
+                trigger,
+            };
+            // Store in database
+            const insertStmt = this.prepared.get('insertVersion');
+            if (insertStmt) {
+                insertStmt.run(id, patternId, newVersion, embeddingBuffer, embedding.length, JSON.stringify(changes), tracked.qualityScore, tracked.successRate, trigger);
+            }
+            return tracked;
+        });
+        const newVersion = version.version;
         // Update embedding cache
         this.embeddingCache.set(patternId, embedding);
         // Record evolution event
@@ -429,7 +436,8 @@ export class PatternEvolution {
      */
     async mergePatterns(patternId1, patternId2, mergedName) {
         this.ensureInitialized();
-        if (!this.db)
+        const db = this.db;
+        if (!db)
             return null;
         const patternStmt = this.prepared.get('getPattern');
         const p1 = patternStmt?.get(patternId1);
@@ -442,13 +450,13 @@ export class PatternEvolution {
             : [p2, p1];
         // Update retained pattern name if provided
         if (mergedName) {
-            this.db.prepare(`UPDATE qe_patterns SET name = ? WHERE id = ?`).run(mergedName, retained.id);
+            await this.write(() => db.prepare(`UPDATE qe_patterns SET name = ? WHERE id = ?`).run(mergedName, retained.id));
         }
         // Combine usage counts and recalculate success rate
         const totalUsage = (retained.usage_count ?? 0) + (archived.usage_count ?? 0);
         const totalSuccess = (retained.successful_uses ?? 0) + (archived.successful_uses ?? 0);
         const newSuccessRate = totalUsage > 0 ? totalSuccess / totalUsage : 0;
-        this.db.prepare(`
+        await this.write(() => db.prepare(`
       UPDATE qe_patterns SET
         usage_count = ?,
         successful_uses = ?,
@@ -460,14 +468,15 @@ export class PatternEvolution {
         END,
         updated_at = datetime('now')
       WHERE id = ?
-    `).run(totalUsage, totalSuccess, newSuccessRate, archived.last_used_at, archived.last_used_at, archived.last_used_at, retained.id);
+    `).run(totalUsage, totalSuccess, newSuccessRate, archived.last_used_at, archived.last_used_at, archived.last_used_at, retained.id));
         // Record merge relationship
         const relStmt = this.prepared.get('insertRelationship');
         if (relStmt) {
-            relStmt.run(uuidv4(), archived.id, retained.id, 'merged', 1.0);
+            const relId = uuidv4();
+            await this.write(() => relStmt.run(relId, archived.id, retained.id, 'merged', 1.0));
         }
         // Archive the lower quality pattern (mark as archived)
-        this.db.prepare(`UPDATE qe_patterns SET tier = 'archived' WHERE id = ?`).run(archived.id);
+        await this.write(() => db.prepare(`UPDATE qe_patterns SET tier = 'archived' WHERE id = ?`).run(archived.id));
         // Record events
         await this.recordEvent(retained.id, 'merged', { absorbedFrom: archived.id });
         await this.recordEvent(archived.id, 'archived', { mergedInto: retained.id });
@@ -497,8 +506,9 @@ export class PatternEvolution {
         for (const candidate of pruneCandidates) {
             if (candidate.reason === 'low-quality' || candidate.reason === 'obsolete') {
                 // Actually delete the pattern
-                if (this.db) {
-                    this.db.prepare(`DELETE FROM qe_patterns WHERE id = ?`).run(candidate.patternId);
+                const db = this.db;
+                if (db) {
+                    await this.write(() => db.prepare(`DELETE FROM qe_patterns WHERE id = ?`).run(candidate.patternId));
                     this.embeddingCache.delete(candidate.patternId);
                     await this.recordEvent(candidate.patternId, 'pruned', { reason: candidate.reason });
                     pruned++;
@@ -560,10 +570,18 @@ export class PatternEvolution {
                 details,
                 timestamp: new Date(),
             };
-            insertStmt.run(event.id, patternId, eventType, JSON.stringify(details));
+            await this.write(() => insertStmt.run(event.id, patternId, eventType, JSON.stringify(details)));
             this.recentEvents.push(event);
         }
     }
+    /**
+     * Run a write through the shared connection's writeWhenUnlocked queue, so a
+     * locked memory.db does not freeze the MCP server's event loop while the
+     * hourly consolidation timer merges and prunes patterns (#1274).
+     */
+    write(fn) {
+        return this.unifiedMemory ? this.unifiedMemory.writeWhenUnlocked(fn) : Promise.resolve(fn());
+    }
     /**
      * Get statistics
      */

package/dist/integrations/agentic-flow/reasoning-bank/trajectory-tracker.js

@@ -75,7 +75,7 @@ export class TrajectoryTracker {
         // Load recent trajectories into buffer
         await this.loadRecentTrajectories();
         // Clean up orphaned trajectories from previous sessions (started > 1 hour ago, never completed)
-        this.cleanupOrphanedTrajectories();
+        await this.cleanupOrphanedTrajectories();
         this.initialized = true;
         console.log('[TrajectoryTracker] Initialized');
     }
@@ -83,18 +83,20 @@ export class TrajectoryTracker {
      * Clean up orphaned trajectories that were started but never completed.
      * Marks them as failed with an auto-close reason. Runs at initialization.
      */
-    cleanupOrphanedTrajectories() {
-        if (!this.db)
+    async cleanupOrphanedTrajectories() {
+        const db = this.db;
+        if (!db || !this.unifiedMemory)
             return;
         try {
-            const result = this.db.prepare(`
+            // #1263: retried asynchronously, so a locked DB does not freeze the MCP server.
+            const result = await this.unifiedMemory.writeWhenUnlocked(() => db.prepare(`
         UPDATE qe_trajectories
         SET success = 0,
             ended_at = datetime('now'),
             feedback = 'auto-closed: orphaned trajectory from previous session'
         WHERE success IS NULL
           AND started_at < datetime('now', '-1 hour')
-      `).run();
+      `).run());
             if (result.changes > 0) {
                 this.stats.trajectoriesAbandoned += result.changes;
                 console.log(`[TrajectoryTracker] Cleaned up ${result.changes} orphaned trajectories`);
@@ -238,10 +240,13 @@ export class TrajectoryTracker {
             startedAt,
             context: options.context,
         });
-        // Persist to SQLite
+        // Persist to SQLite. Queued (#1283): task_orchestrate starts a trajectory
+        // inside the tool call, and a locked memory.db must not freeze the MCP
+        // server's event loop. The later end update queues after this insert.
         const insertStmt = this.prepared.get('insertTrajectory');
         if (insertStmt) {
-            insertStmt.run(id, task, options.agent || null, options.domain || null, startedAt.toISOString(), options.context ? JSON.stringify(options.context) : null);
+            const run = () => insertStmt.run(id, task, options.agent || null, options.domain || null, startedAt.toISOString(), options.context ? JSON.stringify(options.context) : null);
+            await (this.unifiedMemory ? this.unifiedMemory.writeWhenUnlocked(run) : run());
         }
         this.stats.trajectoriesStarted++;
         // Set auto-end timeout
@@ -344,12 +349,15 @@ export class TrajectoryTracker {
             endedAt,
             feedback,
         };
-        // Persist to SQLite
+        // Persist to SQLite. Queued (#1274): task completion events end
+        // trajectories in the background, and a locked memory.db must not freeze
+        // the MCP server's event loop.
         const updateStmt = this.prepared.get('updateTrajectory');
         if (updateStmt) {
-            updateStmt.run(endedAt.toISOString(), success ? 1 : 0, JSON.stringify(active.steps), JSON.stringify({ metrics, context: active.context }), null, // embedding - computed later if needed
+            const run = () => updateStmt.run(endedAt.toISOString(), success ? 1 : 0, JSON.stringify(active.steps), JSON.stringify({ metrics, context: active.context }), null, // embedding - computed later if needed
             feedback ?? null, null, // related_patterns - computed later
             trajectoryId);
+            await (this.unifiedMemory ? this.unifiedMemory.writeWhenUnlocked(run) : run());
         }
         // Remove from active, add to recent buffer
         this.activeTrajectories.delete(trajectoryId);

package/dist/integrations/embeddings/cache/EmbeddingCache.d.ts

@@ -84,6 +84,14 @@ export declare class EmbeddingCache {
      * Persist entry to disk
      */
     private persistToDisk;
+    /**
+     * Run a write on the cache's connection without blocking the caller
+     * (#1283). On the shared memory.db connection it goes through the write
+     * queue, so a locked database does not freeze the MCP server's event loop;
+     * on a private (legacy) connection it runs at once. A failure is logged,
+     * since the in-memory cache is already up to date.
+     */
+    private persist;
     /**
      * Flush writes that were queued during async DB initialization
      */

package/dist/integrations/embeddings/cache/EmbeddingCache.js

@@ -24,6 +24,7 @@ import { join } from 'path';
 import { existsSync, mkdirSync } from 'fs';
 import { getUnifiedMemory, findProjectRoot } from '../../../kernel/unified-memory.js';
 import { safeJsonParse } from '../../../shared/safe-json.js';
+import { writeWhenUnlockedOn } from '../../../shared/sqlite-write-queue.js';
 /**
  * Embedding cache with LRU eviction and persistent storage
  */
@@ -183,8 +184,7 @@ export class EmbeddingCache {
         const cache = this.memoryCache.get(namespace);
         const deleted = cache?.delete(key) || false;
         if (deleted && this.persistent && this.db) {
-            const stmt = this.db.prepare('DELETE FROM embeddings WHERE key = ? AND namespace = ?');
-            stmt.run(key, namespace);
+            this.persist('delete', (db) => db.prepare('DELETE FROM embeddings WHERE key = ? AND namespace = ?').run(key, namespace));
         }
         return deleted;
     }
@@ -196,8 +196,7 @@ export class EmbeddingCache {
             const cache = this.memoryCache.get(namespace);
             cache?.clear();
             if (this.persistent && this.db) {
-                const stmt = this.db.prepare('DELETE FROM embeddings WHERE namespace = ?');
-                stmt.run(namespace);
+                this.persist('clear', (db) => db.prepare('DELETE FROM embeddings WHERE namespace = ?').run(namespace));
             }
         }
         else {
@@ -205,7 +204,7 @@ export class EmbeddingCache {
                 cache.clear();
             }
             if (this.persistent && this.db) {
-                this.db.exec('DELETE FROM embeddings');
+                this.persist('clear', (db) => db.exec('DELETE FROM embeddings'));
             }
         }
     }
@@ -243,8 +242,8 @@ export class EmbeddingCache {
         if (lruKey) {
             cache.delete(lruKey);
             if (this.persistent && this.db) {
-                const stmt = this.db.prepare('DELETE FROM embeddings WHERE key = ? AND namespace = ?');
-                stmt.run(lruKey, namespace);
+                const evicted = lruKey;
+                this.persist('evict', (db) => db.prepare('DELETE FROM embeddings WHERE key = ? AND namespace = ?').run(evicted, namespace));
             }
         }
     }
@@ -259,17 +258,32 @@ export class EmbeddingCache {
             const metadataJson = embedding.metadata
                 ? JSON.stringify(embedding.metadata)
                 : null;
-            const stmt = this.db.prepare(`
+            const lastAccess = Date.now();
+            this.persist('persist', (db) => db.prepare(`
         INSERT OR REPLACE INTO embeddings
         (key, namespace, vector, dimension, text, timestamp, quantization, metadata, last_access)
         VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)
-      `);
-            stmt.run(key, namespace, vectorBuffer, embedding.dimension, embedding.text, embedding.timestamp, embedding.quantization, metadataJson, Date.now());
+      `).run(key, namespace, vectorBuffer, embedding.dimension, embedding.text, embedding.timestamp, embedding.quantization, metadataJson, lastAccess));
         }
         catch (error) {
             console.warn('Failed to persist embedding:', error);
         }
     }
+    /**
+     * Run a write on the cache's connection without blocking the caller
+     * (#1283). On the shared memory.db connection it goes through the write
+     * queue, so a locked database does not freeze the MCP server's event loop;
+     * on a private (legacy) connection it runs at once. A failure is logged,
+     * since the in-memory cache is already up to date.
+     */
+    persist(action, write) {
+        const db = this.db;
+        if (!db)
+            return;
+        writeWhenUnlockedOn(db, () => write(db)).catch((error) => {
+            console.warn(`Failed to ${action} embedding cache entry:`, error);
+        });
+    }
     /**
      * Flush writes that were queued during async DB initialization
      */

package/dist/integrations/ruvector/delta-tracker.d.ts

@@ -77,6 +77,17 @@ export declare class DeltaTracker {
     initialize(): void;
     private prepareStatements;
     private ensureInitialized;
+    /**
+     * createGenesis() through the shared connection's write queue (#1283). The
+     * version check and the insert run as one queued unit.
+     */
+    createGenesisWhenUnlocked(patternId: string, snapshot: object, metadata?: Record<string, unknown>): Promise<DeltaEvent>;
+    /**
+     * recordDelta() through the shared connection's write queue (#1283). Reading
+     * the current version, the insert and retention run as one queued unit, so
+     * two deltas cannot get the same version number.
+     */
+    recordDeltaWhenUnlocked(patternId: string, before: object, after: object, metadata?: Record<string, unknown>): Promise<DeltaEvent>;
     /**
      * Create a genesis snapshot for a pattern (version 0).
      * The full object is stored in metadata.snapshot; patches are empty.

package/dist/integrations/ruvector/delta-tracker.js

@@ -8,6 +8,7 @@
  * @module integrations/ruvector/delta-tracker
  */
 import { v4 as uuidv4 } from 'uuid';
+import { writeWhenUnlockedOn } from '../../shared/sqlite-write-queue.js';
 import * as fastJsonPatchNs from 'fast-json-patch';
 // fast-json-patch ships two entry points with different export shapes: its CJS
 // entry (index.js) attaches named exports directly via Object.assign(exports,
@@ -156,6 +157,21 @@ export class DeltaTracker {
     // --------------------------------------------------------------------------
     // Public API
     // --------------------------------------------------------------------------
+    /**
+     * createGenesis() through the shared connection's write queue (#1283). The
+     * version check and the insert run as one queued unit.
+     */
+    createGenesisWhenUnlocked(patternId, snapshot, metadata) {
+        return writeWhenUnlockedOn(this.db, () => this.createGenesis(patternId, snapshot, metadata));
+    }
+    /**
+     * recordDelta() through the shared connection's write queue (#1283). Reading
+     * the current version, the insert and retention run as one queued unit, so
+     * two deltas cannot get the same version number.
+     */
+    recordDeltaWhenUnlocked(patternId, before, after, metadata) {
+        return writeWhenUnlockedOn(this.db, () => this.recordDelta(patternId, before, after, metadata));
+    }
     /**
      * Create a genesis snapshot for a pattern (version 0).
      * The full object is stored in metadata.snapshot; patches are empty.

package/dist/integrations/ruvector/sona-persistence.d.ts

@@ -95,6 +95,8 @@ export declare class PersistentSONAEngine {
     private initPromise;
     private pendingSaves;
     private saveTimer;
+    /** The deferred batch currently being written, if any (#1283). */
+    private flushInFlight;
     private consecutiveSaveFailures;
     private serverClient;
     constructor(config: PersistentSONAConfig);
@@ -419,6 +421,14 @@ export declare class PersistentSONAEngine {
      * Schedule batched save
      */
     private scheduleSave;
+    /**
+     * Write the batched patterns. Each write is queued on the shared connection
+     * (#1283): in the MCP server a locked memory.db no longer freezes the event
+     * loop for the whole busy_timeout per pattern; the write retries
+     * asynchronously instead. A row that still fails stays pending and the batch
+     * is retried with backoff, as before.
+     */
+    private flushPendingSaves;
     /**
      * Update pattern usage in SQLite
      */

package/dist/integrations/ruvector/sona-persistence.js

@@ -29,6 +29,7 @@ import { getUnifiedPersistence } from '../../kernel/unified-persistence.js';
 import { toErrorMessage } from '../../shared/error-utils.js';
 import { safeJsonParse } from '../../shared/safe-json.js';
 import { LoggerFactory } from '../../logging/index.js';
+import { writeWhenUnlockedOn } from '../../shared/sqlite-write-queue.js';
 const logger = LoggerFactory.create('sona-persistence');
 // ============================================================================
 // Schema (added to unified-memory.ts as part of migration)
@@ -112,6 +113,8 @@ export class PersistentSONAEngine {
     initPromise = null;
     pendingSaves = new Map();
     saveTimer = null;
+    /** The deferred batch currently being written, if any (#1283). */
+    flushInFlight = null;
     consecutiveSaveFailures = 0;
     serverClient = null;
     constructor(config) {
@@ -801,6 +804,10 @@ export class PersistentSONAEngine {
      * Close the engine
      */
     async close() {
+        // Let a deferred batch that is already writing finish first (#1283); it
+        // may schedule a retry, which the clearTimeout below then cancels.
+        if (this.flushInFlight)
+            await this.flushInFlight;
         // Flush pending saves
         if (this.saveTimer) {
             clearTimeout(this.saveTimer);
@@ -808,9 +815,9 @@ export class PersistentSONAEngine {
         }
         if (this.pendingSaves.size > 0) {
             const failures = [];
-            for (const pattern of this.pendingSaves.values()) {
+            for (const pattern of Array.from(this.pendingSaves.values())) {
                 try {
-                    this.savePatternToDb(pattern);
+                    await writeWhenUnlockedOn(this.db, () => this.savePatternToDb(pattern));
                     this.pendingSaves.delete(pattern.id);
                 }
                 catch (error) {
@@ -1085,33 +1092,51 @@ export class PersistentSONAEngine {
         }
         this.saveTimer = setTimeout(() => {
             this.saveTimer = null;
-            const patterns = Array.from(this.pendingSaves.values());
-            for (const pattern of patterns) {
-                try {
-                    this.savePatternToDb(pattern);
-                    this.pendingSaves.delete(pattern.id);
-                }
-                catch (error) {
-                    logger.warn('Deferred SONA save failed; retaining pending pattern', {
-                        patternId: pattern.id, error: toErrorMessage(error),
-                    });
-                }
-            }
-            if (this.pendingSaves.size > 0) {
-                this.consecutiveSaveFailures++;
-                // Stop after five failed batches; close() can still flush retained rows.
-                if (this.consecutiveSaveFailures < 5 && this.db?.open) {
-                    this.scheduleSave(Math.min(60000, Math.max(1000, this.config.autoSaveInterval) * 2 ** (this.consecutiveSaveFailures - 1)));
-                }
-            }
-            else {
-                this.consecutiveSaveFailures = 0;
-            }
+            const flush = this.flushPendingSaves().finally(() => {
+                if (this.flushInFlight === flush)
+                    this.flushInFlight = null;
+            });
+            this.flushInFlight = flush;
         }, delayMs);
         // The initial batch must flush on natural exit; only failure retries are optional.
         if (this.consecutiveSaveFailures > 0)
             this.saveTimer.unref();
     }
+    /**
+     * Write the batched patterns. Each write is queued on the shared connection
+     * (#1283): in the MCP server a locked memory.db no longer freezes the event
+     * loop for the whole busy_timeout per pattern; the write retries
+     * asynchronously instead. A row that still fails stays pending and the batch
+     * is retried with backoff, as before.
+     */
+    async flushPendingSaves() {
+        const patterns = Array.from(this.pendingSaves.values());
+        let failed = 0;
+        for (const pattern of patterns) {
+            try {
+                await writeWhenUnlockedOn(this.db, () => this.savePatternToDb(pattern));
+                // A newer snapshot queued during the write stays pending.
+                if (this.pendingSaves.get(pattern.id) === pattern)
+                    this.pendingSaves.delete(pattern.id);
+            }
+            catch (error) {
+                failed++;
+                logger.warn('Deferred SONA save failed; retaining pending pattern', {
+                    patternId: pattern.id, error: toErrorMessage(error),
+                });
+            }
+        }
+        if (failed > 0) {
+            this.consecutiveSaveFailures++;
+            // Stop after five failed batches; close() can still flush retained rows.
+            if (this.consecutiveSaveFailures < 5 && this.db?.open) {
+                this.scheduleSave(Math.min(60000, Math.max(1000, this.config.autoSaveInterval) * 2 ** (this.consecutiveSaveFailures - 1)));
+            }
+        }
+        else {
+            this.consecutiveSaveFailures = 0;
+        }
+    }
     /**
      * Update pattern usage in SQLite
      */

package/dist/kernel/unified-memory.d.ts

@@ -69,6 +69,9 @@ export declare class UnifiedMemoryManager {
     private initialized;
     private vectorsLoaded;
     private initPromise;
+    /** Tail of the FIFO write queue and how many writes are in it (#1263). */
+    private writeQueue;
+    private queuedWrites;
     private preparedStatements;
     private vectorIndex;
     private crdtStore;
@@ -79,6 +82,8 @@ export declare class UnifiedMemoryManager {
     private constructor();
     static getInstance(config?: Partial<UnifiedMemoryConfig>): UnifiedMemoryManager;
     static getInstanceAsync(config?: Partial<UnifiedMemoryConfig>): Promise<UnifiedMemoryManager>;
+    /** The shared instance when it is initialized; never creates one. */
+    static peekInitialized(): UnifiedMemoryManager | null;
     static resetInstance(): void;
     initialize(options?: {
         signal?: AbortSignal;
@@ -115,6 +120,19 @@ export declare class UnifiedMemoryManager {
      */
     private migrateToV11GoapExecutionSteps;
     private loadVectorIndex;
+    /**
+     * Run a write on the shared connection (#1263). Under the MCP server's lock
+     * wait cap each attempt blocks for at most the cap and the write retries
+     * asynchronously, so a locked memory.db does not freeze the event loop. The
+     * write still fails with SQLITE_BUSY once the configured busyTimeout has
+     * passed. Without a cap (CLI) this is one attempt with the full busyTimeout.
+     *
+     * Writes run one at a time in call order (FIFO), so a later write to the
+     * same key cannot land before an earlier one that is still retrying. A
+     * failed write does not hold up the next. With nothing queued the first
+     * attempt runs synchronously, as the write did before.
+     */
+    writeWhenUnlocked<T>(fn: () => T): Promise<T>;
     kvSet(key: string, value: unknown, namespace?: string, ttl?: number): Promise<void>;
     kvGet<T>(key: string, namespace?: string): Promise<T | undefined>;
     kvDelete(key: string, namespace?: string): Promise<boolean>;
@@ -211,5 +229,19 @@ export declare class UnifiedMemoryManager {
 }
 export declare function getUnifiedMemory(config?: Partial<UnifiedMemoryConfig>): UnifiedMemoryManager;
 export declare function initializeUnifiedMemory(config?: Partial<UnifiedMemoryConfig>): Promise<UnifiedMemoryManager>;
+/**
+ * The shared memory.db connection when UnifiedMemory is already initialized,
+ * else null. Never opens it: callers that run before it keep their
+ * no-database behavior (#1298).
+ */
+export declare function getOpenUnifiedMemoryDatabase(): DatabaseType | null;
 export declare function resetUnifiedMemory(): void;
+/**
+ * Run a write on `db` through the shared manager's writeWhenUnlocked queue
+ * when `db` is that manager's connection (#1274), for modules that hold only
+ * the raw connection. The write then neither blocks the MCP server's event
+ * loop for the whole busy_timeout nor lands before an earlier queued write.
+ * A write on any other connection runs now, as before.
+ */
+export declare function writeWhenUnlockedOn<T>(db: DatabaseType, fn: () => T): Promise<T>;
 //# sourceMappingURL=unified-memory.d.ts.map