@danielsimonjr/memory-mcp 0.48.0 → 9.8.2

package/dist/core/GraphStorage.js

@@ -2,12 +2,17 @@
  * Graph Storage
  *
  * Handles file I/O operations for the knowledge graph using JSONL format.
- * Provides persistence layer abstraction for graph data.
+ * Implements IGraphStorage interface for storage abstraction.
  *
  * @module core/GraphStorage
  */
 import { promises as fs } from 'fs';
+import { Mutex } from 'async-mutex';
 import { clearAllSearchCaches } from '../utils/searchCache.js';
+import { NameIndex, TypeIndex, LowercaseCache, RelationIndex, ObservationIndex } from '../utils/indexes.js';
+import { sanitizeObject } from '../utils/index.js';
+import { BatchTransaction } from './TransactionManager.js';
+import { GraphEventEmitter } from './GraphEventEmitter.js';
 /**
  * GraphStorage manages persistence of the knowledge graph to disk.
  *
@@ -27,11 +32,59 @@ import { clearAllSearchCaches } from '../utils/searchCache.js';
  */
 export class GraphStorage {
     memoryFilePath;
+    /**
+     * Mutex for thread-safe access to storage operations.
+     * Prevents concurrent writes from corrupting the file or cache.
+     */
+    mutex = new Mutex();
     /**
      * In-memory cache of the knowledge graph.
      * Null when cache is empty or invalidated.
      */
     cache = null;
+    /**
+     * Number of pending append operations since last compaction.
+     * Used to trigger automatic compaction when threshold is reached.
+     */
+    pendingAppends = 0;
+    /**
+     * Dynamic threshold for automatic compaction.
+     *
+     * Returns the larger of 100 or 10% of the current entity count.
+     * This scales with graph size to avoid too-frequent compaction on large graphs
+     * while maintaining a reasonable minimum for small graphs.
+     *
+     * @returns Compaction threshold value
+     */
+    get compactionThreshold() {
+        return Math.max(100, Math.floor((this.cache?.entities.length ?? 0) * 0.1));
+    }
+    /**
+     * O(1) entity lookup by name.
+     */
+    nameIndex = new NameIndex();
+    /**
+     * O(1) entity lookup by type.
+     */
+    typeIndex = new TypeIndex();
+    /**
+     * Pre-computed lowercase strings for search optimization.
+     */
+    lowercaseCache = new LowercaseCache();
+    /**
+     * O(1) relation lookup by entity name.
+     */
+    relationIndex = new RelationIndex();
+    /**
+     * O(1) observation word lookup by entity.
+     * Maps words in observations to entity names.
+     */
+    observationIndex = new ObservationIndex();
+    /**
+     * Phase 10 Sprint 2: Event emitter for graph change notifications.
+     * Allows external systems to subscribe to graph changes.
+     */
+    eventEmitter = new GraphEventEmitter();
     /**
      * Create a new GraphStorage instance.
      *
@@ -40,32 +93,123 @@ export class GraphStorage {
     constructor(memoryFilePath) {
         this.memoryFilePath = memoryFilePath;
     }
+    // ==================== Phase 10 Sprint 2: Event Emitter Access ====================
     /**
-     * Load the knowledge graph from disk.
+     * Get the event emitter for subscribing to graph changes.
+     *
+     * @returns GraphEventEmitter instance
+     *
+     * @example
+     * ```typescript
+     * const storage = new GraphStorage('/data/memory.jsonl');
      *
-     * OPTIMIZED: Uses in-memory cache to avoid repeated disk reads.
-     * Cache is populated on first load and invalidated on writes.
+     * // Subscribe to entity creation events
+     * storage.events.on('entity:created', (event) => {
+     *   console.log(`Entity ${event.entity.name} created`);
+     * });
      *
-     * Reads the JSONL file and reconstructs the graph structure.
-     * Returns empty graph if file doesn't exist.
+     * // Subscribe to all events
+     * storage.events.onAny((event) => {
+     *   console.log(`Graph event: ${event.type}`);
+     * });
+     * ```
+     */
+    get events() {
+        return this.eventEmitter;
+    }
+    // ==================== Durable File Operations ====================
+    /**
+     * Write content to file with fsync for durability.
      *
-     * @returns Promise resolving to the loaded knowledge graph
+     * @param content - Content to write
+     */
+    async durableWriteFile(content) {
+        const fd = await fs.open(this.memoryFilePath, 'w');
+        try {
+            await fd.write(content);
+            await fd.sync();
+        }
+        finally {
+            await fd.close();
+        }
+    }
+    /**
+     * Append content to file with fsync for durability.
+     *
+     * @param content - Content to append
+     * @param prependNewline - Whether to prepend a newline
+     */
+    async durableAppendFile(content, prependNewline) {
+        const fd = await fs.open(this.memoryFilePath, 'a');
+        try {
+            const dataToWrite = prependNewline ? '\n' + content : content;
+            await fd.write(dataToWrite);
+            await fd.sync();
+        }
+        finally {
+            await fd.close();
+        }
+    }
+    /**
+     * Load the knowledge graph from disk (read-only access).
+     *
+     * OPTIMIZED: Returns cached reference directly without copying.
+     * This is O(1) regardless of graph size. For mutation operations,
+     * use getGraphForMutation() instead.
+     *
+     * @returns Promise resolving to read-only knowledge graph reference
      * @throws Error if file exists but cannot be read or parsed
      */
     async loadGraph() {
-        // Return cached graph if available
+        // Return cached graph directly (no copying - O(1))
         if (this.cache !== null) {
-            // Return a deep copy to prevent external mutations from affecting cache
-            return {
-                entities: this.cache.entities.map(e => ({ ...e })),
-                relations: this.cache.relations.map(r => ({ ...r })),
-            };
+            return this.cache;
         }
         // Cache miss - load from disk
+        await this.loadFromDisk();
+        return this.cache;
+    }
+    /**
+     * Get a mutable copy of the graph for write operations.
+     *
+     * Creates deep copies of entity and relation arrays to allow
+     * safe mutation without affecting the cached data.
+     *
+     * @returns Promise resolving to mutable knowledge graph copy
+     */
+    async getGraphForMutation() {
+        await this.ensureLoaded();
+        return {
+            entities: this.cache.entities.map(e => ({
+                ...e,
+                observations: [...e.observations],
+                tags: e.tags ? [...e.tags] : undefined,
+            })),
+            relations: this.cache.relations.map(r => ({ ...r })),
+        };
+    }
+    /**
+     * Ensure the cache is loaded from disk.
+     *
+     * @returns Promise resolving when cache is populated
+     */
+    async ensureLoaded() {
+        if (this.cache === null) {
+            await this.loadFromDisk();
+        }
+    }
+    /**
+     * Internal method to load graph from disk into cache.
+     */
+    async loadFromDisk() {
         try {
             const data = await fs.readFile(this.memoryFilePath, 'utf-8');
             const lines = data.split('\n').filter((line) => line.trim() !== '');
-            const graph = lines.reduce((graph, line) => {
+            // Use Maps to deduplicate - later entries override earlier ones
+            // This supports append-only updates where new versions are appended
+            const entityMap = new Map();
+            const relationMap = new Map();
+            for (const line of lines) {
                 const item = JSON.parse(line);
                 if (item.type === 'entity') {
                     // Add createdAt if missing for backward compatibility
@@ -74,7 +218,8 @@ export class GraphStorage {
                     // Add lastModified if missing for backward compatibility
                     if (!item.lastModified)
                         item.lastModified = item.createdAt;
-                    graph.entities.push(item);
+                    // Use name as key - later entries override earlier ones
+                    entityMap.set(item.name, item);
                 }
                 if (item.type === 'relation') {
                     // Add createdAt if missing for backward compatibility
@@ -83,32 +228,70 @@ export class GraphStorage {
                     // Add lastModified if missing for backward compatibility
                     if (!item.lastModified)
                         item.lastModified = item.createdAt;
-                    graph.relations.push(item);
+                    // Use composite key for relations
+                    const key = `${item.from}:${item.to}:${item.relationType}`;
+                    relationMap.set(key, item);
                 }
-                return graph;
-            }, { entities: [], relations: [] });
+            }
+            // Convert maps to arrays
+            const graph = {
+                entities: Array.from(entityMap.values()),
+                relations: Array.from(relationMap.values()),
+            };
             // Populate cache
             this.cache = graph;
-            // Return a deep copy
-            return {
-                entities: graph.entities.map(e => ({ ...e })),
-                relations: graph.relations.map(r => ({ ...r })),
-            };
+            // Build indexes from loaded data
+            this.buildEntityIndexes(graph.entities);
+            this.buildRelationIndex(graph.relations);
+            // Phase 10 Sprint 2: Emit graph:loaded event
+            this.eventEmitter.emitGraphLoaded(graph.entities.length, graph.relations.length);
         }
         catch (error) {
-            // File doesn't exist - return empty graph
+            // File doesn't exist - create empty graph
             if (error instanceof Error && 'code' in error && error.code === 'ENOENT') {
-                const emptyGraph = { entities: [], relations: [] };
-                this.cache = emptyGraph;
-                return { entities: [], relations: [] };
+                this.cache = { entities: [], relations: [] };
+                this.clearIndexes();
+                // Phase 10 Sprint 2: Emit graph:loaded event for empty graph
+                this.eventEmitter.emitGraphLoaded(0, 0);
+                return;
             }
             throw error;
         }
     }
+    /**
+     * Build all entity indexes from entity array.
+     */
+    buildEntityIndexes(entities) {
+        this.nameIndex.build(entities);
+        this.typeIndex.build(entities);
+        this.lowercaseCache.build(entities);
+        // Build observation index
+        this.observationIndex.clear();
+        for (const entity of entities) {
+            this.observationIndex.add(entity.name, entity.observations);
+        }
+    }
+    /**
+     * Build relation index from relation array.
+     */
+    buildRelationIndex(relations) {
+        this.relationIndex.build(relations);
+    }
+    /**
+     * Clear all indexes.
+     */
+    clearIndexes() {
+        this.nameIndex.clear();
+        this.typeIndex.clear();
+        this.lowercaseCache.clear();
+        this.relationIndex.clear();
+        this.observationIndex.clear();
+    }
     /**
      * Save the knowledge graph to disk.
      *
-     * OPTIMIZED: Invalidates cache after write to ensure consistency.
+     * OPTIMIZED: Updates cache directly after write to avoid re-reading.
+     * THREAD-SAFE: Uses mutex to prevent concurrent write operations.
      *
      * Writes the graph to JSONL format, with one JSON object per line.
      *
@@ -117,6 +300,155 @@ export class GraphStorage {
      * @throws Error if file cannot be written
      */
     async saveGraph(graph) {
+        return this.mutex.runExclusive(async () => {
+            await this.saveGraphInternal(graph);
+        });
+    }
+    /**
+     * Append a single entity to the file (O(1) write operation).
+     *
+     * OPTIMIZED: Uses file append instead of full rewrite.
+     * THREAD-SAFE: Uses mutex to prevent concurrent write operations.
+     * Updates cache in-place and triggers compaction when threshold is reached.
+     *
+     * @param entity - The entity to append
+     * @returns Promise resolving when append is complete
+     */
+    async appendEntity(entity) {
+        await this.ensureLoaded();
+        return this.mutex.runExclusive(async () => {
+            const entityData = {
+                type: 'entity',
+                name: entity.name,
+                entityType: entity.entityType,
+                observations: entity.observations,
+                createdAt: entity.createdAt,
+                lastModified: entity.lastModified,
+            };
+            // Only include optional fields if they exist
+            if (entity.tags !== undefined)
+                entityData.tags = entity.tags;
+            if (entity.importance !== undefined)
+                entityData.importance = entity.importance;
+            if (entity.parentId !== undefined)
+                entityData.parentId = entity.parentId;
+            const line = JSON.stringify(entityData);
+            // Append to file with fsync for durability (write FIRST, then update cache)
+            try {
+                const stat = await fs.stat(this.memoryFilePath);
+                await this.durableAppendFile(line, stat.size > 0);
+            }
+            catch (error) {
+                // File doesn't exist - create it
+                if (error instanceof Error && 'code' in error && error.code === 'ENOENT') {
+                    await this.durableWriteFile(line);
+                }
+                else {
+                    throw error;
+                }
+            }
+            // Update cache in-place (after successful file write)
+            this.cache.entities.push(entity);
+            // Update indexes
+            this.nameIndex.add(entity);
+            this.typeIndex.add(entity);
+            this.lowercaseCache.set(entity);
+            this.observationIndex.add(entity.name, entity.observations);
+            this.pendingAppends++;
+            // Clear search caches
+            clearAllSearchCaches();
+            // Phase 10 Sprint 2: Emit entity:created event
+            this.eventEmitter.emitEntityCreated(entity);
+            // Trigger compaction if threshold reached
+            if (this.pendingAppends >= this.compactionThreshold) {
+                await this.compactInternal();
+            }
+        });
+    }
+    /**
+     * Append a single relation to the file (O(1) write operation).
+     *
+     * OPTIMIZED: Uses file append instead of full rewrite.
+     * THREAD-SAFE: Uses mutex to prevent concurrent write operations.
+     * Updates cache in-place and triggers compaction when threshold is reached.
+     *
+     * @param relation - The relation to append
+     * @returns Promise resolving when append is complete
+     */
+    async appendRelation(relation) {
+        await this.ensureLoaded();
+        return this.mutex.runExclusive(async () => {
+            const line = JSON.stringify({
+                type: 'relation',
+                from: relation.from,
+                to: relation.to,
+                relationType: relation.relationType,
+                createdAt: relation.createdAt,
+                lastModified: relation.lastModified,
+            });
+            // Append to file with fsync for durability (write FIRST, then update cache)
+            try {
+                const stat = await fs.stat(this.memoryFilePath);
+                await this.durableAppendFile(line, stat.size > 0);
+            }
+            catch (error) {
+                // File doesn't exist - create it
+                if (error instanceof Error && 'code' in error && error.code === 'ENOENT') {
+                    await this.durableWriteFile(line);
+                }
+                else {
+                    throw error;
+                }
+            }
+            // Update cache in-place (after successful file write)
+            this.cache.relations.push(relation);
+            // Update relation index
+            this.relationIndex.add(relation);
+            this.pendingAppends++;
+            // Clear search caches
+            clearAllSearchCaches();
+            // Phase 10 Sprint 2: Emit relation:created event
+            this.eventEmitter.emitRelationCreated(relation);
+            // Trigger compaction if threshold reached
+            if (this.pendingAppends >= this.compactionThreshold) {
+                await this.compactInternal();
+            }
+        });
+    }
+    /**
+     * Compact the file by rewriting it with only current cache contents.
+     *
+     * THREAD-SAFE: Uses mutex to prevent concurrent operations.
+     * Removes duplicate entries and cleans up the file.
+     * Resets pending appends counter.
+     *
+     * @returns Promise resolving when compaction is complete
+     */
+    async compact() {
+        return this.mutex.runExclusive(async () => {
+            await this.compactInternal();
+        });
+    }
+    /**
+     * Internal compact implementation (must be called within mutex).
+     *
+     * @returns Promise resolving when compaction is complete
+     */
+    async compactInternal() {
+        if (this.cache === null) {
+            return;
+        }
+        // Rewrite file with current cache (removes duplicates/updates)
+        await this.saveGraphInternal(this.cache);
+        this.pendingAppends = 0;
+    }
+    /**
+     * Internal saveGraph implementation (must be called within mutex).
+     *
+     * @param graph - The knowledge graph to save
+     * @returns Promise resolving when save is complete
+     */
+    async saveGraphInternal(graph) {
         const lines = [
             ...graph.entities.map(e => {
                 const entityData = {
@@ -145,11 +477,116 @@ export class GraphStorage {
                 lastModified: r.lastModified,
             })),
         ];
-        await fs.writeFile(this.memoryFilePath, lines.join('\n'));
-        // Invalidate cache to ensure next load reads fresh data
-        this.cache = null;
+        await this.durableWriteFile(lines.join('\n'));
+        // Update cache directly with the saved graph (avoid re-reading from disk)
+        this.cache = graph;
+        // Rebuild indexes with new graph data
+        this.buildEntityIndexes(graph.entities);
+        this.buildRelationIndex(graph.relations);
+        // Reset pending appends since file is now clean
+        this.pendingAppends = 0;
         // Clear all search caches since graph data has changed
         clearAllSearchCaches();
+        // Phase 10 Sprint 2: Emit graph:saved event
+        this.eventEmitter.emitGraphSaved(graph.entities.length, graph.relations.length);
+    }
+    /**
+     * Get the current pending appends count.
+     *
+     * Useful for testing compaction behavior.
+     *
+     * @returns Number of pending appends since last compaction
+     */
+    getPendingAppends() {
+        return this.pendingAppends;
+    }
+    /**
+     * Update an entity in-place in the cache and append to file.
+     *
+     * OPTIMIZED: Modifies cache directly and appends updated version to file.
+     * THREAD-SAFE: Uses mutex to prevent concurrent write operations.
+     * Does not rewrite the entire file - compaction handles deduplication later.
+     *
+     * @param entityName - Name of the entity to update
+     * @param updates - Partial entity updates to apply
+     * @returns Promise resolving to true if entity was found and updated, false otherwise
+     */
+    async updateEntity(entityName, updates) {
+        await this.ensureLoaded();
+        return this.mutex.runExclusive(async () => {
+            const entityIndex = this.cache.entities.findIndex(e => e.name === entityName);
+            if (entityIndex === -1) {
+                return false;
+            }
+            const entity = this.cache.entities[entityIndex];
+            const oldType = entity.entityType;
+            const timestamp = new Date().toISOString();
+            // Phase 10 Sprint 2: Capture previous values for event
+            const previousValues = {};
+            for (const key of Object.keys(updates)) {
+                if (key in entity) {
+                    previousValues[key] = entity[key];
+                }
+            }
+            // Build the updated entity data for file write BEFORE modifying cache
+            // This ensures cache consistency if file write fails
+            const updatedEntity = {
+                ...entity,
+                ...updates,
+                lastModified: timestamp,
+            };
+            const entityData = {
+                type: 'entity',
+                name: updatedEntity.name,
+                entityType: updatedEntity.entityType,
+                observations: updatedEntity.observations,
+                createdAt: updatedEntity.createdAt,
+                lastModified: updatedEntity.lastModified,
+            };
+            if (updatedEntity.tags !== undefined)
+                entityData.tags = updatedEntity.tags;
+            if (updatedEntity.importance !== undefined)
+                entityData.importance = updatedEntity.importance;
+            if (updatedEntity.parentId !== undefined)
+                entityData.parentId = updatedEntity.parentId;
+            const line = JSON.stringify(entityData);
+            // Write to file FIRST with durability - if this fails, cache remains consistent
+            try {
+                const stat = await fs.stat(this.memoryFilePath);
+                await this.durableAppendFile(line, stat.size > 0);
+            }
+            catch (error) {
+                if (error instanceof Error && 'code' in error && error.code === 'ENOENT') {
+                    await this.durableWriteFile(line);
+                }
+                else {
+                    throw error;
+                }
+            }
+            // File write succeeded - NOW update cache in-place (sanitized to prevent prototype pollution)
+            Object.assign(entity, sanitizeObject(updates));
+            entity.lastModified = timestamp;
+            // Update indexes
+            this.nameIndex.add(entity); // Update reference
+            if (updates.entityType && updates.entityType !== oldType) {
+                this.typeIndex.updateType(entityName, oldType, updates.entityType);
+            }
+            this.lowercaseCache.set(entity); // Recompute lowercase
+            if (updates.observations) {
+                this.observationIndex.remove(entityName); // Remove old observations
+                this.observationIndex.add(entityName, entity.observations); // Add new observations
+            }
+            this.pendingAppends++;
+            // Clear search caches
+            clearAllSearchCaches();
+            // Phase 10 Sprint 2: Emit entity:updated event
+            this.eventEmitter.emitEntityUpdated(entityName, updates, previousValues);
+            // Trigger compaction if threshold reached
+            if (this.pendingAppends >= this.compactionThreshold) {
+                await this.compactInternal();
+            }
+            return true;
+        });
     }
     /**
      * Manually clear the cache.
@@ -160,6 +597,7 @@ export class GraphStorage {
      */
     clearCache() {
         this.cache = null;
+        this.clearIndexes();
     }
     /**
      * Get the file path being used for storage.
@@ -169,4 +607,179 @@ export class GraphStorage {
     getFilePath() {
         return this.memoryFilePath;
     }
+    // ==================== Index Accessors ====================
+    /**
+     * Get an entity by name in O(1) time.
+     *
+     * OPTIMIZED: Uses NameIndex for constant-time lookup.
+     *
+     * @param name - Entity name to look up
+     * @returns Entity if found, undefined otherwise
+     */
+    getEntityByName(name) {
+        return this.nameIndex.get(name);
+    }
+    /**
+     * Check if an entity exists by name in O(1) time.
+     *
+     * @param name - Entity name to check
+     * @returns True if entity exists
+     */
+    hasEntity(name) {
+        return this.nameIndex.has(name);
+    }
+    /**
+     * Get all entities of a given type in O(1) time.
+     *
+     * OPTIMIZED: Uses TypeIndex for constant-time lookup of entity names,
+     * then uses NameIndex for O(1) entity retrieval.
+     *
+     * @param entityType - Entity type to filter by (case-insensitive)
+     * @returns Array of entities with the given type
+     */
+    getEntitiesByType(entityType) {
+        const names = this.typeIndex.getNames(entityType);
+        const entities = [];
+        for (const name of names) {
+            const entity = this.nameIndex.get(name);
+            if (entity) {
+                entities.push(entity);
+            }
+        }
+        return entities;
+    }
+    /**
+     * Get pre-computed lowercase data for an entity.
+     *
+     * OPTIMIZED: Avoids repeated toLowerCase() calls during search.
+     *
+     * @param entityName - Entity name to get lowercase data for
+     * @returns LowercaseData if entity exists, undefined otherwise
+     */
+    getLowercased(entityName) {
+        return this.lowercaseCache.get(entityName);
+    }
+    /**
+     * Get all unique entity types in the graph.
+     *
+     * @returns Array of unique entity types (lowercase)
+     */
+    getEntityTypes() {
+        return this.typeIndex.getTypes();
+    }
+    // ==================== Relation Index Accessors ====================
+    /**
+     * Get all relations where the entity is the source (outgoing relations) in O(1) time.
+     *
+     * OPTIMIZED: Uses RelationIndex for constant-time lookup.
+     *
+     * @param entityName - Entity name to look up outgoing relations for
+     * @returns Array of relations where entity is the source
+     */
+    getRelationsFrom(entityName) {
+        return this.relationIndex.getRelationsFrom(entityName);
+    }
+    /**
+     * Get all relations where the entity is the target (incoming relations) in O(1) time.
+     *
+     * OPTIMIZED: Uses RelationIndex for constant-time lookup.
+     *
+     * @param entityName - Entity name to look up incoming relations for
+     * @returns Array of relations where entity is the target
+     */
+    getRelationsTo(entityName) {
+        return this.relationIndex.getRelationsTo(entityName);
+    }
+    /**
+     * Get all relations involving the entity (both incoming and outgoing) in O(1) time.
+     *
+     * OPTIMIZED: Uses RelationIndex for constant-time lookup.
+     *
+     * @param entityName - Entity name to look up all relations for
+     * @returns Array of all relations involving the entity
+     */
+    getRelationsFor(entityName) {
+        return this.relationIndex.getRelationsFor(entityName);
+    }
+    /**
+     * Check if an entity has any relations.
+     *
+     * @param entityName - Entity name to check
+     * @returns True if entity has any relations
+     */
+    hasRelations(entityName) {
+        return this.relationIndex.hasRelations(entityName);
+    }
+    // ==================== Observation Index Accessors ====================
+    /**
+     * Get entities that have observations containing the given word.
+     * Uses the observation index for O(1) lookup.
+     *
+     * OPTIMIZED: Uses ObservationIndex for constant-time lookup instead of
+     * linear scan through all entities and their observations.
+     *
+     * @param word - Word to search for in observations
+     * @returns Set of entity names
+     */
+    getEntitiesByObservationWord(word) {
+        return this.observationIndex.getEntitiesWithWord(word);
+    }
+    /**
+     * Get entities that have observations containing ANY of the given words (union).
+     * Uses the observation index for O(1) lookup per word.
+     *
+     * OPTIMIZED: Uses ObservationIndex for constant-time lookups.
+     *
+     * @param words - Array of words to search for
+     * @returns Set of entity names containing any of the words
+     */
+    getEntitiesByAnyObservationWord(words) {
+        return this.observationIndex.getEntitiesWithAnyWord(words);
+    }
+    /**
+     * Get entities that have observations containing ALL of the given words (intersection).
+     * Uses the observation index for O(1) lookup per word.
+     *
+     * OPTIMIZED: Uses ObservationIndex for constant-time lookups and set intersection.
+     *
+     * @param words - Array of words that must all be present
+     * @returns Set of entity names containing all of the words
+     */
+    getEntitiesByAllObservationWords(words) {
+        return this.observationIndex.getEntitiesWithAllWords(words);
+    }
+    /**
+     * Get statistics about the observation index.
+     *
+     * @returns Object with wordCount and entityCount
+     */
+    getObservationIndexStats() {
+        return this.observationIndex.getStats();
+    }
+    // ==================== Phase 10 Sprint 1: Transaction Factory ====================
+    /**
+     * Create a new batch transaction for atomic operations.
+     *
+     * Returns a BatchTransaction instance that can be used to queue multiple
+     * operations and execute them atomically with a single save operation.
+     *
+     * @returns A new BatchTransaction instance
+     *
+     * @example
+     * ```typescript
+     * const storage = new GraphStorage('/data/memory.jsonl');
+     *
+     * // Create and execute a batch transaction
+     * const result = await storage.transaction()
+     *   .createEntity({ name: 'Alice', entityType: 'person', observations: ['Developer'] })
+     *   .createEntity({ name: 'Bob', entityType: 'person', observations: ['Designer'] })
+     *   .createRelation({ from: 'Alice', to: 'Bob', relationType: 'knows' })
+     *   .execute();
+     *
+     * console.log(`Batch completed: ${result.operationsExecuted} operations`);
+     * ```
+     */
+    transaction() {
+        return new BatchTransaction(this);
+    }
 }