@danielsimonjr/memory-mcp 0.47.1 → 9.8.0

package/dist/features/AnalyticsManager.js

@@ -1,12 +1,13 @@
 /**
  * Analytics Manager
  *
- * Provides graph validation and analytics capabilities.
+ * Handles graph statistics and validation operations.
+ * Extracted from SearchManager (Phase 4: Consolidate God Objects).
  *
  * @module features/AnalyticsManager
  */
 /**
- * Performs validation and analytics on the knowledge graph.
+ * Manages analytics operations for the knowledge graph.
  */
 export class AnalyticsManager {
     storage;
@@ -28,21 +29,21 @@ export class AnalyticsManager {
      */
     async validateGraph() {
         const graph = await this.storage.loadGraph();
-        const errors = [];
+        const issues = [];
         const warnings = [];
         // Create a set of all entity names for fast lookup
         const entityNames = new Set(graph.entities.map(e => e.name));
         // Check for orphaned relations (relations pointing to non-existent entities)
         for (const relation of graph.relations) {
             if (!entityNames.has(relation.from)) {
-                errors.push({
+                issues.push({
                     type: 'orphaned_relation',
                     message: `Relation has non-existent source entity: "${relation.from}"`,
                     details: { relation, missingEntity: relation.from },
                 });
             }
             if (!entityNames.has(relation.to)) {
-                errors.push({
+                issues.push({
                     type: 'orphaned_relation',
                     message: `Relation has non-existent target entity: "${relation.to}"`,
                     details: { relation, missingEntity: relation.to },
@@ -57,7 +58,7 @@ export class AnalyticsManager {
         }
         for (const [name, count] of entityNameCounts.entries()) {
             if (count > 1) {
-                errors.push({
+                issues.push({
                     type: 'duplicate_entity',
                     message: `Duplicate entity name found: "${name}" (${count} instances)`,
                     details: { entityName: name, count },
@@ -67,21 +68,21 @@ export class AnalyticsManager {
         // Check for entities with invalid data
         for (const entity of graph.entities) {
             if (!entity.name || entity.name.trim() === '') {
-                errors.push({
+                issues.push({
                     type: 'invalid_data',
                     message: 'Entity has empty or missing name',
                     details: { entity },
                 });
             }
             if (!entity.entityType || entity.entityType.trim() === '') {
-                errors.push({
+                issues.push({
                     type: 'invalid_data',
                     message: `Entity "${entity.name}" has empty or missing entityType`,
                     details: { entity },
                 });
             }
             if (!Array.isArray(entity.observations)) {
-                errors.push({
+                issues.push({
                     type: 'invalid_data',
                     message: `Entity "${entity.name}" has invalid observations (not an array)`,
                     details: { entity },
@@ -131,14 +132,14 @@ export class AnalyticsManager {
             }
         }
         // Count specific issues
-        const orphanedRelationsCount = errors.filter(e => e.type === 'orphaned_relation').length;
+        const orphanedRelationsCount = issues.filter(e => e.type === 'orphaned_relation').length;
         const entitiesWithoutRelationsCount = warnings.filter(w => w.type === 'isolated_entity').length;
         return {
-            isValid: errors.length === 0,
-            errors,
+            isValid: issues.length === 0,
+            issues,
             warnings,
             summary: {
-                totalErrors: errors.length,
+                totalErrors: issues.length,
                 totalWarnings: warnings.length,
                 orphanedRelationsCount,
                 entitiesWithoutRelationsCount,

package/dist/features/ArchiveManager.d.ts

@@ -0,0 +1,133 @@
+/**
+ * Archive Manager
+ *
+ * Handles archiving (removal) of entities based on criteria.
+ * Archives are stored as compressed files for space-efficient long-term storage.
+ * Extracted from EntityManager (Phase 4: Consolidate God Objects).
+ * Enhanced with brotli compression in Phase 3 Sprint 5.
+ *
+ * @module features/ArchiveManager
+ */
+import type { LongRunningOperationOptions } from '../types/index.js';
+import type { GraphStorage } from '../core/GraphStorage.js';
+/**
+ * Criteria for archiving entities.
+ */
+export interface ArchiveCriteria {
+    /** Entities older than this date (ISO 8601) */
+    olderThan?: string;
+    /** Entities with importance less than this value */
+    importanceLessThan?: number;
+    /** Entities with any of these tags */
+    tags?: string[];
+}
+/**
+ * Options for archive operations.
+ * Phase 9B: Extended with LongRunningOperationOptions.
+ */
+export interface ArchiveOptions extends LongRunningOperationOptions {
+    /** Dry run mode - preview without making changes */
+    dryRun?: boolean;
+    /** Whether to save archived entities to a compressed file (default: true) */
+    saveToFile?: boolean;
+}
+/**
+ * Result of archive operation.
+ * Extends ArchiveResultExtended with compression statistics.
+ */
+export interface ArchiveResult {
+    /** Number of entities archived */
+    archived: number;
+    /** Names of archived entities */
+    entityNames: string[];
+    /** Path to the archive file (if created) */
+    archivePath?: string;
+    /** Original size of archive data in bytes */
+    originalSize?: number;
+    /** Compressed size in bytes */
+    compressedSize?: number;
+    /** Compression ratio (compressedSize / originalSize). Lower is better. */
+    compressionRatio?: number;
+}
+/**
+ * Manages archive operations for the knowledge graph.
+ *
+ * Archives are stored as brotli-compressed files in the `.archives` directory.
+ * Maximum compression quality is used for optimal long-term storage.
+ */
+export declare class ArchiveManager {
+    private storage;
+    private readonly archiveDir;
+    constructor(storage: GraphStorage);
+    /**
+     * Archive old or low-importance entities.
+     *
+     * Entities matching ANY of the criteria are archived:
+     * - lastModified older than olderThan date
+     * - importance less than importanceLessThan
+     * - has at least one tag from tags array
+     *
+     * By default, archived entities are saved to a compressed file before
+     * being removed from the active graph. Use `saveToFile: false` to
+     * skip creating the archive file.
+     *
+     * Phase 9B: Supports progress tracking and cancellation via options.
+     *
+     * @param criteria - Archiving criteria
+     * @param options - Archive options (dryRun, saveToFile, onProgress, signal)
+     * @returns Archive result with count, entity names, and compression stats
+     * @throws {OperationCancelledError} If operation is cancelled via signal (Phase 9B)
+     *
+     * @example
+     * ```typescript
+     * // Archive old entities with compression
+     * const result = await manager.archiveEntities({
+     *   olderThan: '2023-01-01T00:00:00Z',
+     *   importanceLessThan: 3
+     * });
+     * console.log(`Archived ${result.archived} entities`);
+     * console.log(`Compressed from ${result.originalSize} to ${result.compressedSize} bytes`);
+     *
+     * // Preview without making changes
+     * const preview = await manager.archiveEntities(criteria, { dryRun: true });
+     *
+     * // With progress tracking and cancellation (Phase 9B)
+     * const controller = new AbortController();
+     * const result = await manager.archiveEntities(criteria, {
+     *   signal: controller.signal,
+     *   onProgress: (p) => console.log(`${p.percentage}% complete`),
+     * });
+     * ```
+     */
+    archiveEntities(criteria: ArchiveCriteria, options?: ArchiveOptions | boolean): Promise<ArchiveResult>;
+    /**
+     * Save entities to a compressed archive file.
+     *
+     * Creates a brotli-compressed file in the `.archives` directory
+     * with maximum compression quality for space efficiency.
+     *
+     * @param entities - Entities to archive
+     * @returns Archive file path and compression statistics
+     */
+    private saveToArchive;
+    /**
+     * List all available archives.
+     *
+     * @returns Array of archive information with compression details
+     */
+    listArchives(): Promise<Array<{
+        fileName: string;
+        filePath: string;
+        timestamp: string;
+        entityCount: number;
+        compressed: boolean;
+        originalSize?: number;
+        compressedSize?: number;
+        compressionRatio?: number;
+    }>>;
+    /**
+     * Get the path to the archives directory.
+     */
+    getArchiveDir(): string;
+}
+//# sourceMappingURL=ArchiveManager.d.ts.map

package/dist/features/ArchiveManager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ArchiveManager.d.ts","sourceRoot":"","sources":["../../src/features/ArchiveManager.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAIH,OAAO,KAAK,EAAU,2BAA2B,EAAE,MAAM,mBAAmB,CAAC;AAC7E,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,yBAAyB,CAAC;AAS5D;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,+CAA+C;IAC/C,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,oDAAoD;IACpD,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,sCAAsC;IACtC,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;CACjB;AAED;;;GAGG;AACH,MAAM,WAAW,cAAe,SAAQ,2BAA2B;IACjE,oDAAoD;IACpD,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,6EAA6E;IAC7E,UAAU,CAAC,EAAE,OAAO,CAAC;CACtB;AAED;;;GAGG;AACH,MAAM,WAAW,aAAa;IAC5B,kCAAkC;IAClC,QAAQ,EAAE,MAAM,CAAC;IACjB,iCAAiC;IACjC,WAAW,EAAE,MAAM,EAAE,CAAC;IACtB,4CAA4C;IAC5C,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,6CAA6C;IAC7C,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,+BAA+B;IAC/B,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,0EAA0E;IAC1E,gBAAgB,CAAC,EAAE,MAAM,CAAC;CAC3B;AAED;;;;;GAKG;AACH,qBAAa,cAAc;IAGb,OAAO,CAAC,OAAO;IAF3B,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAS;gBAEhB,OAAO,EAAE,YAAY;IAMzC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAuCG;IACG,eAAe,CACnB,QAAQ,EAAE,eAAe,EACzB,OAAO,GAAE,cAAc,GAAG,OAAY,GACrC,OAAO,CAAC,aAAa,CAAC;IAuIzB;;;;;;;;OAQG;YACW,aAAa;IAmD3B;;;;OAIG;IACG,YAAY,IAAI,OAAO,CAAC,KAAK,CAAC;QAClC,QAAQ,EAAE,MAAM,CAAC;QACjB,QAAQ,EAAE,MAAM,CAAC;QACjB,SAAS,EAAE,MAAM,CAAC;QAClB,WAAW,EAAE,MAAM,CAAC;QACpB,UAAU,EAAE,OAAO,CAAC;QACpB,YAAY,CAAC,EAAE,MAAM,CAAC;QACtB,cAAc,CAAC,EAAE,MAAM,CAAC;QACxB,gBAAgB,CAAC,EAAE,MAAM,CAAC;KAC3B,CAAC,CAAC;IA6DH;;OAEG;IACH,aAAa,IAAI,MAAM;CAGxB"}

package/dist/features/ArchiveManager.js

@@ -1,17 +1,30 @@
 /**
  * Archive Manager
  *
- * Archives old or low-importance entities to reduce active graph size.
+ * Handles archiving (removal) of entities based on criteria.
+ * Archives are stored as compressed files for space-efficient long-term storage.
+ * Extracted from EntityManager (Phase 4: Consolidate God Objects).
+ * Enhanced with brotli compression in Phase 3 Sprint 5.
  *
  * @module features/ArchiveManager
  */
+import { promises as fs } from 'fs';
+import { dirname, join } from 'path';
+import { compress, COMPRESSION_CONFIG, checkCancellation, createProgressReporter, createProgress, } from '../utils/index.js';
 /**
- * Manages entity archival based on age, importance, and tags.
+ * Manages archive operations for the knowledge graph.
+ *
+ * Archives are stored as brotli-compressed files in the `.archives` directory.
+ * Maximum compression quality is used for optimal long-term storage.
  */
 export class ArchiveManager {
     storage;
+    archiveDir;
     constructor(storage) {
         this.storage = storage;
+        const filePath = this.storage.getFilePath();
+        const dir = dirname(filePath);
+        this.archiveDir = join(dir, '.archives');
     }
     /**
      * Archive old or low-importance entities.
@@ -21,16 +34,58 @@ export class ArchiveManager {
      * - importance less than importanceLessThan
      * - has at least one tag from tags array
      *
-     * Archived entities and their relations are removed from the graph.
+     * By default, archived entities are saved to a compressed file before
+     * being removed from the active graph. Use `saveToFile: false` to
+     * skip creating the archive file.
+     *
+     * Phase 9B: Supports progress tracking and cancellation via options.
      *
      * @param criteria - Archiving criteria
-     * @param dryRun - If true, preview what would be archived without making changes
-     * @returns Archive result with count and entity names
+     * @param options - Archive options (dryRun, saveToFile, onProgress, signal)
+     * @returns Archive result with count, entity names, and compression stats
+     * @throws {OperationCancelledError} If operation is cancelled via signal (Phase 9B)
+     *
+     * @example
+     * ```typescript
+     * // Archive old entities with compression
+     * const result = await manager.archiveEntities({
+     *   olderThan: '2023-01-01T00:00:00Z',
+     *   importanceLessThan: 3
+     * });
+     * console.log(`Archived ${result.archived} entities`);
+     * console.log(`Compressed from ${result.originalSize} to ${result.compressedSize} bytes`);
+     *
+     * // Preview without making changes
+     * const preview = await manager.archiveEntities(criteria, { dryRun: true });
+     *
+     * // With progress tracking and cancellation (Phase 9B)
+     * const controller = new AbortController();
+     * const result = await manager.archiveEntities(criteria, {
+     *   signal: controller.signal,
+     *   onProgress: (p) => console.log(`${p.percentage}% complete`),
+     * });
+     * ```
      */
-    async archiveEntities(criteria, dryRun = false) {
-        const graph = await this.storage.loadGraph();
+    async archiveEntities(criteria, options = {}) {
+        // Handle legacy boolean argument (backward compatibility)
+        const opts = typeof options === 'boolean'
+            ? { dryRun: options, saveToFile: true }
+            : { saveToFile: true, ...options };
+        // Check for early cancellation
+        checkCancellation(opts.signal, 'archiveEntities');
+        // Setup progress reporter
+        const reportProgress = createProgressReporter(opts.onProgress);
+        reportProgress?.(createProgress(0, 100, 'archiveEntities'));
+        // Use read-only graph for analysis
+        const readGraph = await this.storage.loadGraph();
         const toArchive = [];
-        for (const entity of graph.entities) {
+        const totalEntities = readGraph.entities.length;
+        let processedEntities = 0;
+        // Phase 1: Identify entities to archive (0-40% progress)
+        reportProgress?.(createProgress(5, 100, 'analyzing entities'));
+        for (const entity of readGraph.entities) {
+            // Check for cancellation periodically
+            checkCancellation(opts.signal, 'archiveEntities');
             let shouldArchive = false;
             // Check age criteria
             if (criteria.olderThan && entity.lastModified) {
@@ -58,17 +113,169 @@ export class ArchiveManager {
             if (shouldArchive) {
                 toArchive.push(entity);
             }
+            processedEntities++;
+            // Map analysis progress (0-100%) to overall progress (0-40%)
+            const analysisProgress = totalEntities > 0 ? Math.round((processedEntities / totalEntities) * 40) : 40;
+            reportProgress?.(createProgress(analysisProgress, 100, 'analyzing entities'));
+        }
+        reportProgress?.(createProgress(40, 100, 'analysis complete'));
+        // Dry run - return preview without changes
+        if (opts.dryRun) {
+            reportProgress?.(createProgress(100, 100, 'archiveEntities'));
+            return {
+                archived: toArchive.length,
+                entityNames: toArchive.map(e => e.name),
+            };
+        }
+        // No entities to archive
+        if (toArchive.length === 0) {
+            reportProgress?.(createProgress(100, 100, 'archiveEntities'));
+            return {
+                archived: 0,
+                entityNames: [],
+            };
+        }
+        // Check for cancellation before archiving
+        checkCancellation(opts.signal, 'archiveEntities');
+        // Phase 2: Save to compressed archive file (40-80% progress)
+        let archivePath;
+        let originalSize;
+        let compressedSize;
+        let compressionRatio;
+        if (opts.saveToFile) {
+            reportProgress?.(createProgress(50, 100, 'compressing archive'));
+            const archiveResult = await this.saveToArchive(toArchive);
+            archivePath = archiveResult.archivePath;
+            originalSize = archiveResult.originalSize;
+            compressedSize = archiveResult.compressedSize;
+            compressionRatio = archiveResult.compressionRatio;
+            reportProgress?.(createProgress(80, 100, 'archive saved'));
         }
-        if (!dryRun && toArchive.length > 0) {
-            // Remove archived entities from main graph
-            const archiveNames = new Set(toArchive.map(e => e.name));
-            graph.entities = graph.entities.filter(e => !archiveNames.has(e.name));
-            graph.relations = graph.relations.filter(r => !archiveNames.has(r.from) && !archiveNames.has(r.to));
-            await this.storage.saveGraph(graph);
+        else {
+            reportProgress?.(createProgress(80, 100, 'skipped archive file'));
         }
+        // Check for cancellation before graph modification
+        checkCancellation(opts.signal, 'archiveEntities');
+        // Phase 3: Remove from main graph (80-100% progress)
+        reportProgress?.(createProgress(85, 100, 'updating graph'));
+        // Get mutable copy for write operation
+        const graph = await this.storage.getGraphForMutation();
+        // Remove archived entities from main graph
+        const archiveNames = new Set(toArchive.map(e => e.name));
+        graph.entities = graph.entities.filter(e => !archiveNames.has(e.name));
+        graph.relations = graph.relations.filter(r => !archiveNames.has(r.from) && !archiveNames.has(r.to));
+        await this.storage.saveGraph(graph);
+        // Report completion
+        reportProgress?.(createProgress(100, 100, 'archiveEntities'));
         return {
             archived: toArchive.length,
             entityNames: toArchive.map(e => e.name),
+            archivePath,
+            originalSize,
+            compressedSize,
+            compressionRatio,
+        };
+    }
+    /**
+     * Save entities to a compressed archive file.
+     *
+     * Creates a brotli-compressed file in the `.archives` directory
+     * with maximum compression quality for space efficiency.
+     *
+     * @param entities - Entities to archive
+     * @returns Archive file path and compression statistics
+     */
+    async saveToArchive(entities) {
+        // Ensure archive directory exists
+        await fs.mkdir(this.archiveDir, { recursive: true });
+        // Generate timestamp-based filename
+        const timestamp = new Date().toISOString()
+            .replace(/:/g, '-')
+            .replace(/\./g, '-')
+            .replace('T', '_')
+            .replace('Z', '');
+        const archivePath = join(this.archiveDir, `archive_${timestamp}.jsonl.br`);
+        // Serialize entities to JSONL format
+        const content = entities.map(e => JSON.stringify(e)).join('\n');
+        // Compress with maximum quality for archives
+        const compressionResult = await compress(content, {
+            quality: COMPRESSION_CONFIG.BROTLI_QUALITY_ARCHIVE,
+            mode: 'text',
+        });
+        // Write compressed archive
+        await fs.writeFile(archivePath, compressionResult.compressed);
+        // Write metadata file
+        const metadataPath = `${archivePath}.meta.json`;
+        const metadata = {
+            timestamp: new Date().toISOString(),
+            entityCount: entities.length,
+            entityNames: entities.map(e => e.name),
+            compressed: true,
+            compressionFormat: 'brotli',
+            originalSize: compressionResult.originalSize,
+            compressedSize: compressionResult.compressedSize,
+            compressionRatio: compressionResult.ratio,
+        };
+        await fs.writeFile(metadataPath, JSON.stringify(metadata, null, 2));
+        return {
+            archivePath,
+            originalSize: compressionResult.originalSize,
+            compressedSize: compressionResult.compressedSize,
+            compressionRatio: compressionResult.ratio,
         };
     }
+    /**
+     * List all available archives.
+     *
+     * @returns Array of archive information with compression details
+     */
+    async listArchives() {
+        try {
+            try {
+                await fs.access(this.archiveDir);
+            }
+            catch {
+                return [];
+            }
+            const files = await fs.readdir(this.archiveDir);
+            const archiveFiles = files.filter(f => f.startsWith('archive_') &&
+                (f.endsWith('.jsonl') || f.endsWith('.jsonl.br')) &&
+                !f.endsWith('.meta.json'));
+            const archives = [];
+            for (const fileName of archiveFiles) {
+                const filePath = join(this.archiveDir, fileName);
+                const metadataPath = `${filePath}.meta.json`;
+                try {
+                    const metadataContent = await fs.readFile(metadataPath, 'utf-8');
+                    const metadata = JSON.parse(metadataContent);
+                    archives.push({
+                        fileName,
+                        filePath,
+                        timestamp: metadata.timestamp,
+                        entityCount: metadata.entityCount,
+                        compressed: metadata.compressed ?? fileName.endsWith('.br'),
+                        originalSize: metadata.originalSize,
+                        compressedSize: metadata.compressedSize,
+                        compressionRatio: metadata.compressionRatio,
+                    });
+                }
+                catch {
+                    // Skip archives without valid metadata
+                    continue;
+                }
+            }
+            // Sort by timestamp (newest first)
+            archives.sort((a, b) => new Date(b.timestamp).getTime() - new Date(a.timestamp).getTime());
+            return archives;
+        }
+        catch {
+            return [];
+        }
+    }
+    /**
+     * Get the path to the archives directory.
+     */
+    getArchiveDir() {
+        return this.archiveDir;
+    }
 }

package/dist/features/CompressionManager.d.ts

@@ -0,0 +1,117 @@
+/**
+ * Compression Manager
+ *
+ * Handles duplicate detection, entity merging, and graph compression.
+ * Extracted from SearchManager (Phase 4: Consolidate God Objects).
+ *
+ * @module features/CompressionManager
+ */
+import type { Entity, CompressionResult, KnowledgeGraph, LongRunningOperationOptions } from '../types/index.js';
+import type { GraphStorage } from '../core/GraphStorage.js';
+/**
+ * Manages compression operations for the knowledge graph.
+ */
+export declare class CompressionManager {
+    private storage;
+    constructor(storage: GraphStorage);
+    /**
+     * Prepare an entity for efficient similarity comparisons.
+     * Pre-computes all normalized data to avoid repeated computation.
+     *
+     * @param entity - The entity to prepare
+     * @returns PreparedEntity with pre-computed data
+     */
+    private prepareEntity;
+    /**
+     * Prepare multiple entities for efficient similarity comparisons.
+     * Use this before batch comparison operations.
+     *
+     * @param entities - Entities to prepare
+     * @returns Map of entity name to PreparedEntity
+     */
+    private prepareEntities;
+    /**
+     * Calculate similarity between two entities using multiple heuristics.
+     *
+     * Uses configurable weights defined in SIMILARITY_WEIGHTS constant.
+     * See SIMILARITY_WEIGHTS for the breakdown of scoring factors.
+     *
+     * NOTE: For batch comparisons, use prepareEntities() + calculatePreparedSimilarity() for better performance.
+     *
+     * @param e1 - First entity
+     * @param e2 - Second entity
+     * @returns Similarity score from 0 (completely different) to 1 (identical)
+     */
+    calculateEntitySimilarity(e1: Entity, e2: Entity): number;
+    /**
+     * Efficiently calculate intersection size of two Sets without creating a new Set.
+     * Iterates over the smaller set for O(min(m,n)) complexity.
+     */
+    private setIntersectionSize;
+    /**
+     * Calculate similarity between two prepared entities.
+     * OPTIMIZED: Uses pre-computed Sets to avoid O(n) set creation per comparison.
+     *
+     * @param p1 - First prepared entity
+     * @param p2 - Second prepared entity
+     * @returns Similarity score from 0 (completely different) to 1 (identical)
+     */
+    private calculatePreparedSimilarity;
+    /**
+     * Find duplicate entities in the graph based on similarity threshold.
+     *
+     * OPTIMIZED: Uses bucketing strategies to reduce O(n²) comparisons:
+     * 1. Buckets entities by entityType (only compare same types)
+     * 2. Within each type, buckets by name prefix (first 2 chars normalized)
+     * 3. Only compares entities within same or adjacent buckets
+     *
+     * Phase 9B: Supports progress tracking and cancellation via LongRunningOperationOptions.
+     *
+     * Complexity: O(n·k) where k is average bucket size (typically << n)
+     *
+     * @param threshold - Similarity threshold (0.0 to 1.0), default DEFAULT_DUPLICATE_THRESHOLD
+     * @param options - Optional progress/cancellation options (Phase 9B)
+     * @returns Array of duplicate groups (each group has similar entities)
+     * @throws {OperationCancelledError} If operation is cancelled via signal (Phase 9B)
+     */
+    findDuplicates(threshold?: number, options?: LongRunningOperationOptions): Promise<string[][]>;
+    /**
+     * Merge a group of entities into a single entity.
+     *
+     * Merging strategy:
+     * - First entity is kept (or renamed to targetName)
+     * - Observations: Union of all observations
+     * - Tags: Union of all tags
+     * - Importance: Maximum importance value
+     * - createdAt: Earliest date
+     * - lastModified: Current timestamp
+     * - Relations: Redirected to kept entity, duplicates removed
+     *
+     * @param entityNames - Names of entities to merge (first one is kept)
+     * @param targetName - Optional new name for merged entity (default: first entity name)
+     * @param options - Optional configuration
+     * @param options.graph - Pre-loaded graph to use (avoids reload)
+     * @param options.skipSave - If true, don't save (caller will save)
+     * @returns The merged entity
+     * @throws {InsufficientEntitiesError} If less than 2 entities provided
+     * @throws {EntityNotFoundError} If any entity not found
+     */
+    mergeEntities(entityNames: string[], targetName?: string, options?: {
+        graph?: KnowledgeGraph;
+        skipSave?: boolean;
+    }): Promise<Entity>;
+    /**
+     * Compress the knowledge graph by finding and merging duplicates.
+     * OPTIMIZED: Loads graph once, performs all merges, saves once.
+     *
+     * Phase 9B: Supports progress tracking and cancellation via LongRunningOperationOptions.
+     *
+     * @param threshold - Similarity threshold for duplicate detection (0.0 to 1.0), default DEFAULT_DUPLICATE_THRESHOLD
+     * @param dryRun - If true, only report what would be compressed without applying changes
+     * @param options - Optional progress/cancellation options (Phase 9B)
+     * @returns Compression result with statistics
+     * @throws {OperationCancelledError} If operation is cancelled via signal (Phase 9B)
+     */
+    compressGraph(threshold?: number, dryRun?: boolean, options?: LongRunningOperationOptions): Promise<CompressionResult>;
+}
+//# sourceMappingURL=CompressionManager.d.ts.map

package/dist/features/CompressionManager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"CompressionManager.d.ts","sourceRoot":"","sources":["../../src/features/CompressionManager.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAY,iBAAiB,EAAE,cAAc,EAAE,2BAA2B,EAAE,MAAM,mBAAmB,CAAC;AAC1H,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,yBAAyB,CAAC;AA2B5D;;GAEG;AACH,qBAAa,kBAAkB;IACjB,OAAO,CAAC,OAAO;gBAAP,OAAO,EAAE,YAAY;IAEzC;;;;;;OAMG;IACH,OAAO,CAAC,aAAa;IAUrB;;;;;;OAMG;IACH,OAAO,CAAC,eAAe;IAQvB;;;;;;;;;;;OAWG;IACH,yBAAyB,CAAC,EAAE,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,GAAG,MAAM;IAwCzD;;;OAGG;IACH,OAAO,CAAC,mBAAmB;IAU3B;;;;;;;OAOG;IACH,OAAO,CAAC,2BAA2B;IAoCnC;;;;;;;;;;;;;;;;OAgBG;IACG,cAAc,CAClB,SAAS,GAAE,MAAoC,EAC/C,OAAO,CAAC,EAAE,2BAA2B,GACpC,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC;IA0GtB;;;;;;;;;;;;;;;;;;;;OAoBG;IACG,aAAa,CACjB,WAAW,EAAE,MAAM,EAAE,EACrB,UAAU,CAAC,EAAE,MAAM,EACnB,OAAO,GAAE;QACP,KAAK,CAAC,EAAE,cAAc,CAAC;QACvB,QAAQ,CAAC,EAAE,OAAO,CAAC;KACf,GACL,OAAO,CAAC,MAAM,CAAC;IA8FlB;;;;;;;;;;;OAWG;IACG,aAAa,CACjB,SAAS,GAAE,MAAoC,EAC/C,MAAM,GAAE,OAAe,EACvB,OAAO,CAAC,EAAE,2BAA2B,GACpC,OAAO,CAAC,iBAAiB,CAAC;CA0G9B"}