@danielsimonjr/memory-mcp 0.7.2 → 0.41.0

package/dist/core/GraphStorage.js

@@ -0,0 +1,172 @@
+/**
+ * Graph Storage
+ *
+ * Handles file I/O operations for the knowledge graph using JSONL format.
+ * Provides persistence layer abstraction for graph data.
+ *
+ * @module core/GraphStorage
+ */
+import { promises as fs } from 'fs';
+import { clearAllSearchCaches } from '../utils/searchCache.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 class GraphStorage {
+    memoryFilePath;
+    /**
+     * In-memory cache of the knowledge graph.
+     * Null when cache is empty or invalidated.
+     */
+    cache = null;
+    /**
+     * Create a new GraphStorage instance.
+     *
+     * @param memoryFilePath - Absolute path to the JSONL file
+     */
+    constructor(memoryFilePath) {
+        this.memoryFilePath = memoryFilePath;
+    }
+    /**
+     * Load the knowledge graph from disk.
+     *
+     * OPTIMIZED: Uses in-memory cache to avoid repeated disk reads.
+     * Cache is populated on first load and invalidated on writes.
+     *
+     * Reads the JSONL file and reconstructs the graph structure.
+     * Returns empty graph if file doesn't exist.
+     *
+     * @returns Promise resolving to the loaded knowledge graph
+     * @throws Error if file exists but cannot be read or parsed
+     */
+    async loadGraph() {
+        // Return cached graph if available
+        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 })),
+            };
+        }
+        // Cache miss - load from disk
+        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) => {
+                const item = JSON.parse(line);
+                if (item.type === 'entity') {
+                    // Add createdAt if missing for backward compatibility
+                    if (!item.createdAt)
+                        item.createdAt = new Date().toISOString();
+                    // Add lastModified if missing for backward compatibility
+                    if (!item.lastModified)
+                        item.lastModified = item.createdAt;
+                    graph.entities.push(item);
+                }
+                if (item.type === 'relation') {
+                    // Add createdAt if missing for backward compatibility
+                    if (!item.createdAt)
+                        item.createdAt = new Date().toISOString();
+                    // Add lastModified if missing for backward compatibility
+                    if (!item.lastModified)
+                        item.lastModified = item.createdAt;
+                    graph.relations.push(item);
+                }
+                return graph;
+            }, { entities: [], relations: [] });
+            // Populate cache
+            this.cache = graph;
+            // Return a deep copy
+            return {
+                entities: graph.entities.map(e => ({ ...e })),
+                relations: graph.relations.map(r => ({ ...r })),
+            };
+        }
+        catch (error) {
+            // File doesn't exist - return empty graph
+            if (error instanceof Error && 'code' in error && error.code === 'ENOENT') {
+                const emptyGraph = { entities: [], relations: [] };
+                this.cache = emptyGraph;
+                return { entities: [], relations: [] };
+            }
+            throw error;
+        }
+    }
+    /**
+     * Save the knowledge graph to disk.
+     *
+     * OPTIMIZED: Invalidates cache after write to ensure consistency.
+     *
+     * 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
+     */
+    async saveGraph(graph) {
+        const lines = [
+            ...graph.entities.map(e => {
+                const entityData = {
+                    type: 'entity',
+                    name: e.name,
+                    entityType: e.entityType,
+                    observations: e.observations,
+                    createdAt: e.createdAt,
+                    lastModified: e.lastModified,
+                };
+                // Only include optional fields if they exist
+                if (e.tags !== undefined)
+                    entityData.tags = e.tags;
+                if (e.importance !== undefined)
+                    entityData.importance = e.importance;
+                if (e.parentId !== undefined)
+                    entityData.parentId = e.parentId;
+                return JSON.stringify(entityData);
+            }),
+            ...graph.relations.map(r => JSON.stringify({
+                type: 'relation',
+                from: r.from,
+                to: r.to,
+                relationType: r.relationType,
+                createdAt: r.createdAt,
+                lastModified: r.lastModified,
+            })),
+        ];
+        await fs.writeFile(this.memoryFilePath, lines.join('\n'));
+        // Invalidate cache to ensure next load reads fresh data
+        this.cache = null;
+        // Clear all search caches since graph data has changed
+        clearAllSearchCaches();
+    }
+    /**
+     * Manually clear the cache.
+     *
+     * Useful for testing or when external processes modify the file.
+     *
+     * @returns void
+     */
+    clearCache() {
+        this.cache = null;
+    }
+    /**
+     * Get the file path being used for storage.
+     *
+     * @returns The memory file path
+     */
+    getFilePath() {
+        return this.memoryFilePath;
+    }
+}

package/dist/core/KnowledgeGraphManager.js

@@ -0,0 +1,400 @@
+/**
+ * Knowledge Graph Manager
+ *
+ * Central manager coordinating all knowledge graph operations.
+ * Delegates to specialized managers for different concerns.
+ *
+ * @module core/KnowledgeGraphManager
+ */
+import path from 'path';
+import { DEFAULT_DUPLICATE_THRESHOLD, SEARCH_LIMITS } from '../utils/constants.js';
+import { GraphStorage } from './GraphStorage.js';
+import { EntityManager } from './EntityManager.js';
+import { RelationManager } from './RelationManager.js';
+import { SearchManager } from '../search/SearchManager.js';
+import { CompressionManager } from '../features/CompressionManager.js';
+import { HierarchyManager } from '../features/HierarchyManager.js';
+import { ExportManager } from '../features/ExportManager.js';
+import { ImportManager } from '../features/ImportManager.js';
+import { AnalyticsManager } from '../features/AnalyticsManager.js';
+import { TagManager } from '../features/TagManager.js';
+import { ArchiveManager } from '../features/ArchiveManager.js';
+/**
+ * Central manager coordinating all knowledge graph operations.
+ *
+ * This class serves as the main facade for interacting with the knowledge graph,
+ * delegating to specialized managers for different concerns:
+ * - EntityManager: Entity CRUD operations
+ * - RelationManager: Relation CRUD operations
+ * - SearchManager: All search operations (basic, ranked, boolean, fuzzy)
+ * - CompressionManager: Duplicate detection and merging
+ * - HierarchyManager: Parent-child relationships and tree operations
+ * - ExportManager: Export to various formats
+ * - ImportManager: Import from various formats
+ * - AnalyticsManager: Statistics and validation
+ * - TagManager: Tag alias management
+ * - ArchiveManager: Entity archiving
+ */
+export class KnowledgeGraphManager {
+    savedSearchesFilePath;
+    tagAliasesFilePath;
+    storage;
+    entityManager;
+    relationManager;
+    searchManager;
+    compressionManager;
+    hierarchyManager;
+    exportManager;
+    importManager;
+    analyticsManager;
+    tagManager;
+    archiveManager;
+    constructor(memoryFilePath) {
+        // Saved searches file is stored alongside the memory file
+        const dir = path.dirname(memoryFilePath);
+        const basename = path.basename(memoryFilePath, path.extname(memoryFilePath));
+        this.savedSearchesFilePath = path.join(dir, `${basename}-saved-searches.jsonl`);
+        this.tagAliasesFilePath = path.join(dir, `${basename}-tag-aliases.jsonl`);
+        this.storage = new GraphStorage(memoryFilePath);
+        this.entityManager = new EntityManager(this.storage);
+        this.relationManager = new RelationManager(this.storage);
+        this.searchManager = new SearchManager(this.storage, this.savedSearchesFilePath);
+        this.compressionManager = new CompressionManager(this.storage);
+        this.hierarchyManager = new HierarchyManager(this.storage);
+        this.exportManager = new ExportManager();
+        this.importManager = new ImportManager(this.storage);
+        this.analyticsManager = new AnalyticsManager(this.storage);
+        this.tagManager = new TagManager(this.tagAliasesFilePath);
+        this.archiveManager = new ArchiveManager(this.storage);
+    }
+    async loadGraph() {
+        return this.storage.loadGraph();
+    }
+    /**
+     * Phase 4: Create multiple entities in a single batch operation.
+     * Batch optimization: All entities are processed and saved in a single saveGraph() call,
+     * minimizing disk I/O. This is significantly more efficient than creating entities one at a time.
+     */
+    async createEntities(entities) {
+        return this.entityManager.createEntities(entities);
+    }
+    /**
+     * Phase 4: Create multiple relations in a single batch operation.
+     * Batch optimization: All relations are processed and saved in a single saveGraph() call,
+     * minimizing disk I/O. This is significantly more efficient than creating relations one at a time.
+     */
+    async createRelations(relations) {
+        return this.relationManager.createRelations(relations);
+    }
+    async addObservations(observations) {
+        return this.entityManager.addObservations(observations);
+    }
+    async deleteEntities(entityNames) {
+        return this.entityManager.deleteEntities(entityNames);
+    }
+    async deleteObservations(deletions) {
+        return this.entityManager.deleteObservations(deletions);
+    }
+    async deleteRelations(relations) {
+        return this.relationManager.deleteRelations(relations);
+    }
+    async readGraph() {
+        return this.loadGraph();
+    }
+    // Phase 3: Enhanced search function with tags and importance filters
+    async searchNodes(query, tags, minImportance, maxImportance) {
+        return this.searchManager.searchNodes(query, tags, minImportance, maxImportance);
+    }
+    async openNodes(names) {
+        return this.searchManager.openNodes(names);
+    }
+    // Phase 3: Enhanced searchByDateRange with tags filter
+    async searchByDateRange(startDate, endDate, entityType, tags) {
+        return this.searchManager.searchByDateRange(startDate, endDate, entityType, tags);
+    }
+    async getGraphStats() {
+        return this.analyticsManager.getGraphStats();
+    }
+    // Phase 3: Add tags to an entity
+    async addTags(entityName, tags) {
+        return this.entityManager.addTags(entityName, tags);
+    }
+    // Phase 3: Remove tags from an entity
+    async removeTags(entityName, tags) {
+        return this.entityManager.removeTags(entityName, tags);
+    }
+    // Phase 3: Set importance level for an entity
+    async setImportance(entityName, importance) {
+        return this.entityManager.setImportance(entityName, importance);
+    }
+    // Tier 0 B5: Bulk tag operations for efficient tag management
+    /**
+     * Add tags to multiple entities in a single operation
+     */
+    async addTagsToMultipleEntities(entityNames, tags) {
+        return this.entityManager.addTagsToMultipleEntities(entityNames, tags);
+    }
+    /**
+     * Replace a tag with a new tag across all entities (rename tag)
+     */
+    async replaceTag(oldTag, newTag) {
+        return this.entityManager.replaceTag(oldTag, newTag);
+    }
+    /**
+     * Merge two tags into one (combine tag1 and tag2 into targetTag)
+     */
+    async mergeTags(tag1, tag2, targetTag) {
+        return this.entityManager.mergeTags(tag1, tag2, targetTag);
+    }
+    // Tier 0 A1: Graph validation for data integrity
+    /**
+     * Validate the knowledge graph for integrity issues and provide a detailed report
+     */
+    async validateGraph() {
+        return this.analyticsManager.validateGraph();
+    }
+    // Tier 0 C4: Saved searches for efficient query management
+    /**
+     * Save a search query for later reuse
+     */
+    async saveSearch(search) {
+        return this.searchManager.saveSearch(search);
+    }
+    /**
+     * List all saved searches
+     */
+    async listSavedSearches() {
+        return this.searchManager.listSavedSearches();
+    }
+    /**
+     * Get a specific saved search by name
+     */
+    async getSavedSearch(name) {
+        return this.searchManager.getSavedSearch(name);
+    }
+    /**
+     * Execute a saved search by name
+     */
+    async executeSavedSearch(name) {
+        return this.searchManager.executeSavedSearch(name);
+    }
+    /**
+     * Delete a saved search
+     */
+    async deleteSavedSearch(name) {
+        return this.searchManager.deleteSavedSearch(name);
+    }
+    /**
+     * Update a saved search
+     */
+    async updateSavedSearch(name, updates) {
+        return this.searchManager.updateSavedSearch(name, updates);
+    }
+    /**
+     * Fuzzy search for entities with typo tolerance
+     * @param query - Search query
+     * @param threshold - Similarity threshold (0.0 to 1.0), default 0.7
+     * @param tags - Optional tags filter
+     * @param minImportance - Optional minimum importance
+     * @param maxImportance - Optional maximum importance
+     * @returns Filtered knowledge graph with fuzzy matches
+     */
+    async fuzzySearch(query, threshold = 0.7, tags, minImportance, maxImportance) {
+        return this.searchManager.fuzzySearch(query, threshold, tags, minImportance, maxImportance);
+    }
+    /**
+     * Get "did you mean?" suggestions for a query
+     * @param query - The search query
+     * @param maxSuggestions - Maximum number of suggestions to return
+     * @returns Array of suggested entity/type names
+     */
+    async getSearchSuggestions(query, maxSuggestions = 5) {
+        return this.searchManager.getSearchSuggestions(query, maxSuggestions);
+    }
+    /**
+     * Search nodes with TF-IDF ranking for relevance scoring
+     * @param query - Search query
+     * @param tags - Optional tags filter
+     * @param minImportance - Optional minimum importance
+     * @param maxImportance - Optional maximum importance
+     * @param limit - Optional maximum number of results (default 50)
+     * @returns Array of search results with scores, sorted by relevance
+     */
+    async searchNodesRanked(query, tags, minImportance, maxImportance, limit = SEARCH_LIMITS.DEFAULT) {
+        return this.searchManager.searchNodesRanked(query, tags, minImportance, maxImportance, limit);
+    }
+    /**
+     * Boolean search with support for AND, OR, NOT operators and field-specific queries
+     * @param query - Boolean query string (e.g., "name:Alice AND (type:person OR observation:programming)")
+     * @param tags - Optional tags filter
+     * @param minImportance - Optional minimum importance
+     * @param maxImportance - Optional maximum importance
+     * @returns Filtered knowledge graph matching the boolean query
+     */
+    async booleanSearch(query, tags, minImportance, maxImportance) {
+        return this.searchManager.booleanSearch(query, tags, minImportance, maxImportance);
+    }
+    // Phase 2: Hierarchical nesting - hierarchy navigation methods
+    /**
+     * Set the parent of an entity (creates hierarchy relationship)
+     * @param entityName - Name of the entity to set parent for
+     * @param parentName - Name of the parent entity (or null to remove parent)
+     * @returns Updated entity
+     */
+    async setEntityParent(entityName, parentName) {
+        return this.hierarchyManager.setEntityParent(entityName, parentName);
+    }
+    /**
+     * Get the immediate children of an entity
+     */
+    async getChildren(entityName) {
+        return this.hierarchyManager.getChildren(entityName);
+    }
+    /**
+     * Get the parent of an entity
+     */
+    async getParent(entityName) {
+        return this.hierarchyManager.getParent(entityName);
+    }
+    /**
+     * Get all ancestors of an entity (parent, grandparent, etc.)
+     */
+    async getAncestors(entityName) {
+        return this.hierarchyManager.getAncestors(entityName);
+    }
+    /**
+     * Get all descendants of an entity (children, grandchildren, etc.)
+     */
+    async getDescendants(entityName) {
+        return this.hierarchyManager.getDescendants(entityName);
+    }
+    /**
+     * Get the entire subtree rooted at an entity (entity + all descendants)
+     */
+    async getSubtree(entityName) {
+        return this.hierarchyManager.getSubtree(entityName);
+    }
+    /**
+     * Get root entities (entities with no parent)
+     */
+    async getRootEntities() {
+        return this.hierarchyManager.getRootEntities();
+    }
+    /**
+     * Get the depth of an entity in the hierarchy (0 for root, 1 for child of root, etc.)
+     */
+    async getEntityDepth(entityName) {
+        return this.hierarchyManager.getEntityDepth(entityName);
+    }
+    /**
+     * Move an entity to a new parent (maintaining its descendants)
+     */
+    async moveEntity(entityName, newParentName) {
+        return this.hierarchyManager.moveEntity(entityName, newParentName);
+    }
+    // Phase 3: Memory compression - duplicate detection and merging
+    /**
+     * Find duplicate entities in the graph based on similarity threshold
+     * @param threshold - Similarity threshold (0.0 to 1.0), default 0.8
+     * @returns Array of duplicate groups (each group has similar entities)
+     */
+    async findDuplicates(threshold = DEFAULT_DUPLICATE_THRESHOLD) {
+        return this.compressionManager.findDuplicates(threshold);
+    }
+    /**
+     * Merge a group of entities into a single entity
+     * @param entityNames - Names of entities to merge (first one is kept)
+     * @param targetName - Optional new name for merged entity (default: first entity name)
+     * @returns The merged entity
+     */
+    async mergeEntities(entityNames, targetName) {
+        return this.compressionManager.mergeEntities(entityNames, targetName);
+    }
+    /**
+     * Compress the knowledge graph by finding and merging duplicates
+     * @param threshold - Similarity threshold for duplicate detection (0.0 to 1.0)
+     * @param dryRun - If true, only report what would be compressed without applying changes
+     * @returns Compression result with statistics
+     */
+    async compressGraph(threshold = 0.8, dryRun = false) {
+        return this.compressionManager.compressGraph(threshold, dryRun);
+    }
+    // Phase 4: Memory archiving system
+    /**
+     * Archive old or low-importance entities to a separate storage
+     * @param criteria - Criteria for archiving (age, importance, tags)
+     * @param dryRun - If true, preview what would be archived
+     * @returns Number of entities archived
+     */
+    async archiveEntities(criteria, dryRun = false) {
+        return this.archiveManager.archiveEntities(criteria, dryRun);
+    }
+    // Tier 0 B2: Tag aliases for synonym management
+    /**
+     * Resolve a tag through aliases to get its canonical form
+     * @param tag - Tag to resolve (can be alias or canonical)
+     * @returns Canonical tag name
+     */
+    async resolveTag(tag) {
+        return this.tagManager.resolveTag(tag);
+    }
+    /**
+     * Add a tag alias (synonym mapping)
+     * @param alias - The alias/synonym
+     * @param canonical - The canonical (main) tag name
+     * @param description - Optional description of the alias
+     */
+    async addTagAlias(alias, canonical, description) {
+        return this.tagManager.addTagAlias(alias, canonical, description);
+    }
+    /**
+     * List all tag aliases
+     */
+    async listTagAliases() {
+        return this.tagManager.listTagAliases();
+    }
+    /**
+     * Remove a tag alias
+     */
+    async removeTagAlias(alias) {
+        return this.tagManager.removeTagAlias(alias);
+    }
+    /**
+     * Get all aliases for a canonical tag
+     */
+    async getAliasesForTag(canonicalTag) {
+        return this.tagManager.getAliasesForTag(canonicalTag);
+    }
+    // Phase 4 & Tier 0 D1: Export graph in various formats
+    /**
+     * Export the knowledge graph in the specified format with optional filtering.
+     * Supports JSON, CSV, GraphML, GEXF, DOT, Markdown, and Mermaid formats.
+     *
+     * @param format - Export format: 'json', 'csv', 'graphml', 'gexf', 'dot', 'markdown', 'mermaid'
+     * @param filter - Optional filter object with same structure as searchByDateRange
+     * @returns Exported graph data as a formatted string
+     */
+    async exportGraph(format, filter) {
+        // Get filtered or full graph based on filter parameter
+        let graph;
+        if (filter) {
+            graph = await this.searchByDateRange(filter.startDate, filter.endDate, filter.entityType, filter.tags);
+        }
+        else {
+            graph = await this.loadGraph();
+        }
+        return this.exportManager.exportGraph(graph, format);
+    }
+    // Tier 0 D2: Import capabilities with merge strategies
+    /**
+     * Import knowledge graph from various formats
+     * @param format - Import format: 'json', 'csv', or 'graphml'
+     * @param data - The import data as a string
+     * @param mergeStrategy - How to handle conflicts: 'replace', 'skip', 'merge', 'fail'
+     * @param dryRun - If true, preview changes without applying them
+     * @returns Import result with statistics
+     */
+    async importGraph(format, data, mergeStrategy = 'skip', dryRun = false) {
+        return this.importManager.importGraph(format, data, mergeStrategy, dryRun);
+    }
+}

package/dist/core/ObservationManager.js

@@ -0,0 +1,129 @@
+/**
+ * Observation Manager
+ *
+ * Handles CRUD operations for observations within entities.
+ *
+ * @module core/ObservationManager
+ */
+import { EntityNotFoundError } from '../utils/errors.js';
+/**
+ * Manages observation operations with automatic timestamp handling.
+ */
+export class ObservationManager {
+    storage;
+    constructor(storage) {
+        this.storage = storage;
+    }
+    /**
+     * Add observations to multiple entities in a single batch operation.
+     *
+     * This method performs the following operations:
+     * - Validates that all specified entities exist
+     * - Filters out duplicate observations (observations already present)
+     * - Adds new observations to each entity
+     * - Automatically updates lastModified timestamp for modified entities
+     *
+     * @param observations - Array of objects, each containing entityName and array of observation contents
+     * @returns Promise resolving to array of results showing added observations per entity
+     * @throws {EntityNotFoundError} If any specified entity does not exist
+     *
+     * @example
+     * ```typescript
+     * const manager = new ObservationManager(storage);
+     *
+     * // Add observations to single entity
+     * const results = await manager.addObservations([
+     *   {
+     *     entityName: 'Alice',
+     *     contents: ['Works on frontend', 'Expertise in React']
+     *   }
+     * ]);
+     * console.log(results[0].addedObservations); // ['Works on frontend', 'Expertise in React']
+     *
+     * // Add observations to multiple entities at once
+     * await manager.addObservations([
+     *   { entityName: 'Bob', contents: ['Team lead', 'Experienced in Node.js'] },
+     *   { entityName: 'Charlie', contents: ['New hire', 'Learning the codebase'] }
+     * ]);
+     *
+     * // Duplicate observations are filtered out
+     * await manager.addObservations([
+     *   { entityName: 'Alice', contents: ['Works on frontend'] } // Already exists, won't be added
+     * ]);
+     * ```
+     */
+    async addObservations(observations) {
+        const graph = await this.storage.loadGraph();
+        const timestamp = new Date().toISOString();
+        const results = observations.map(o => {
+            const entity = graph.entities.find(e => e.name === o.entityName);
+            if (!entity) {
+                throw new EntityNotFoundError(o.entityName);
+            }
+            const newObservations = o.contents.filter(content => !entity.observations.includes(content));
+            entity.observations.push(...newObservations);
+            // Update lastModified if observations were added
+            if (newObservations.length > 0) {
+                entity.lastModified = timestamp;
+            }
+            return {
+                entityName: o.entityName,
+                addedObservations: newObservations,
+            };
+        });
+        await this.storage.saveGraph(graph);
+        return results;
+    }
+    /**
+     * Delete specific observations from multiple entities in a single batch operation.
+     *
+     * This method performs the following operations:
+     * - Removes specified observations from each entity
+     * - Silently ignores entities that don't exist (no error thrown)
+     * - Silently ignores observations that don't exist in the entity
+     * - Automatically updates lastModified timestamp for modified entities
+     *
+     * @param deletions - Array of objects, each containing entityName and array of observations to delete
+     * @returns Promise that resolves when deletion is complete
+     *
+     * @example
+     * ```typescript
+     * const manager = new ObservationManager(storage);
+     *
+     * // Delete specific observations from single entity
+     * await manager.deleteObservations([
+     *   {
+     *     entityName: 'Alice',
+     *     observations: ['Works on frontend', 'Expertise in React']
+     *   }
+     * ]);
+     *
+     * // Delete observations from multiple entities at once
+     * await manager.deleteObservations([
+     *   { entityName: 'Bob', observations: ['Team lead'] },
+     *   { entityName: 'Charlie', observations: ['New hire', 'Learning the codebase'] }
+     * ]);
+     *
+     * // Safe to delete non-existent observations or from non-existent entities
+     * await manager.deleteObservations([
+     *   { entityName: 'NonExistent', observations: ['Some observation'] } // No error
+     * ]);
+     * ```
+     */
+    async deleteObservations(deletions) {
+        const graph = await this.storage.loadGraph();
+        const timestamp = new Date().toISOString();
+        deletions.forEach(d => {
+            const entity = graph.entities.find(e => e.name === d.entityName);
+            if (entity) {
+                const originalLength = entity.observations.length;
+                entity.observations = entity.observations.filter(o => !d.observations.includes(o));
+                // Update lastModified if observations were deleted
+                if (entity.observations.length < originalLength) {
+                    entity.lastModified = timestamp;
+                }
+            }
+        });
+        await this.storage.saveGraph(graph);
+    }
+}