@danielsimonjr/memory-mcp 0.47.1 → 9.8.0

package/dist/core/GraphStorage.d.ts

@@ -0,0 +1,395 @@
+/**
+ * Graph Storage
+ *
+ * Handles file I/O operations for the knowledge graph using JSONL format.
+ * Implements IGraphStorage interface for storage abstraction.
+ *
+ * @module core/GraphStorage
+ */
+import type { KnowledgeGraph, Entity, Relation, ReadonlyKnowledgeGraph, IGraphStorage, LowercaseData } from '../types/index.js';
+import { BatchTransaction } from './TransactionManager.js';
+import { GraphEventEmitter } from './GraphEventEmitter.js';
+/**
+ * GraphStorage manages persistence of the knowledge graph to disk.
+ *
+ * Uses JSONL (JSON Lines) format where each line is a separate JSON object
+ * representing either an entity or a relation.
+ *
+ * OPTIMIZED: Implements in-memory caching to avoid repeated disk reads.
+ * Cache is invalidated on every write operation to ensure consistency.
+ *
+ * @example
+ * ```typescript
+ * const storage = new GraphStorage('/path/to/memory.jsonl');
+ * const graph = await storage.loadGraph();
+ * graph.entities.push(newEntity);
+ * await storage.saveGraph(graph);
+ * ```
+ */
+export declare class GraphStorage implements IGraphStorage {
+    private memoryFilePath;
+    /**
+     * Mutex for thread-safe access to storage operations.
+     * Prevents concurrent writes from corrupting the file or cache.
+     */
+    private mutex;
+    /**
+     * In-memory cache of the knowledge graph.
+     * Null when cache is empty or invalidated.
+     */
+    private cache;
+    /**
+     * Number of pending append operations since last compaction.
+     * Used to trigger automatic compaction when threshold is reached.
+     */
+    private pendingAppends;
+    /**
+     * 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
+     */
+    private get compactionThreshold();
+    /**
+     * O(1) entity lookup by name.
+     */
+    private nameIndex;
+    /**
+     * O(1) entity lookup by type.
+     */
+    private typeIndex;
+    /**
+     * Pre-computed lowercase strings for search optimization.
+     */
+    private lowercaseCache;
+    /**
+     * O(1) relation lookup by entity name.
+     */
+    private relationIndex;
+    /**
+     * O(1) observation word lookup by entity.
+     * Maps words in observations to entity names.
+     */
+    private observationIndex;
+    /**
+     * Phase 10 Sprint 2: Event emitter for graph change notifications.
+     * Allows external systems to subscribe to graph changes.
+     */
+    private eventEmitter;
+    /**
+     * Create a new GraphStorage instance.
+     *
+     * @param memoryFilePath - Absolute path to the JSONL file
+     */
+    constructor(memoryFilePath: string);
+    /**
+     * Get the event emitter for subscribing to graph changes.
+     *
+     * @returns GraphEventEmitter instance
+     *
+     * @example
+     * ```typescript
+     * const storage = new GraphStorage('/data/memory.jsonl');
+     *
+     * // Subscribe to entity creation events
+     * storage.events.on('entity:created', (event) => {
+     *   console.log(`Entity ${event.entity.name} created`);
+     * });
+     *
+     * // Subscribe to all events
+     * storage.events.onAny((event) => {
+     *   console.log(`Graph event: ${event.type}`);
+     * });
+     * ```
+     */
+    get events(): GraphEventEmitter;
+    /**
+     * Write content to file with fsync for durability.
+     *
+     * @param content - Content to write
+     */
+    private durableWriteFile;
+    /**
+     * Append content to file with fsync for durability.
+     *
+     * @param content - Content to append
+     * @param prependNewline - Whether to prepend a newline
+     */
+    private durableAppendFile;
+    /**
+     * 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
+     */
+    loadGraph(): Promise<ReadonlyKnowledgeGraph>;
+    /**
+     * 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
+     */
+    getGraphForMutation(): Promise<KnowledgeGraph>;
+    /**
+     * Ensure the cache is loaded from disk.
+     *
+     * @returns Promise resolving when cache is populated
+     */
+    ensureLoaded(): Promise<void>;
+    /**
+     * Internal method to load graph from disk into cache.
+     */
+    private loadFromDisk;
+    /**
+     * Build all entity indexes from entity array.
+     */
+    private buildEntityIndexes;
+    /**
+     * Build relation index from relation array.
+     */
+    private buildRelationIndex;
+    /**
+     * Clear all indexes.
+     */
+    private clearIndexes;
+    /**
+     * Save the knowledge graph to disk.
+     *
+     * 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.
+     *
+     * @param graph - The knowledge graph to save
+     * @returns Promise resolving when save is complete
+     * @throws Error if file cannot be written
+     */
+    saveGraph(graph: KnowledgeGraph): Promise<void>;
+    /**
+     * 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
+     */
+    appendEntity(entity: Entity): Promise<void>;
+    /**
+     * 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
+     */
+    appendRelation(relation: Relation): Promise<void>;
+    /**
+     * 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
+     */
+    compact(): Promise<void>;
+    /**
+     * Internal compact implementation (must be called within mutex).
+     *
+     * @returns Promise resolving when compaction is complete
+     */
+    private compactInternal;
+    /**
+     * Internal saveGraph implementation (must be called within mutex).
+     *
+     * @param graph - The knowledge graph to save
+     * @returns Promise resolving when save is complete
+     */
+    private saveGraphInternal;
+    /**
+     * Get the current pending appends count.
+     *
+     * Useful for testing compaction behavior.
+     *
+     * @returns Number of pending appends since last compaction
+     */
+    getPendingAppends(): number;
+    /**
+     * 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
+     */
+    updateEntity(entityName: string, updates: Partial<Entity>): Promise<boolean>;
+    /**
+     * Manually clear the cache.
+     *
+     * Useful for testing or when external processes modify the file.
+     *
+     * @returns void
+     */
+    clearCache(): void;
+    /**
+     * Get the file path being used for storage.
+     *
+     * @returns The memory file path
+     */
+    getFilePath(): string;
+    /**
+     * 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: string): Entity | undefined;
+    /**
+     * Check if an entity exists by name in O(1) time.
+     *
+     * @param name - Entity name to check
+     * @returns True if entity exists
+     */
+    hasEntity(name: string): boolean;
+    /**
+     * 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: string): Entity[];
+    /**
+     * 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: string): LowercaseData | undefined;
+    /**
+     * Get all unique entity types in the graph.
+     *
+     * @returns Array of unique entity types (lowercase)
+     */
+    getEntityTypes(): string[];
+    /**
+     * 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: string): Relation[];
+    /**
+     * 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: string): Relation[];
+    /**
+     * 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: string): Relation[];
+    /**
+     * Check if an entity has any relations.
+     *
+     * @param entityName - Entity name to check
+     * @returns True if entity has any relations
+     */
+    hasRelations(entityName: string): boolean;
+    /**
+     * 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: string): Set<string>;
+    /**
+     * 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: string[]): Set<string>;
+    /**
+     * 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: string[]): Set<string>;
+    /**
+     * Get statistics about the observation index.
+     *
+     * @returns Object with wordCount and entityCount
+     */
+    getObservationIndexStats(): {
+        wordCount: number;
+        entityCount: number;
+    };
+    /**
+     * 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(): BatchTransaction;
+}
+//# sourceMappingURL=GraphStorage.d.ts.map

package/dist/core/GraphStorage.d.ts.map

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