@danielsimonjr/memory-mcp 0.48.0 → 9.8.0

package/dist/utils/formatters.d.ts

@@ -0,0 +1,145 @@
+/**
+ * Response and Pagination Formatters
+ *
+ * Consolidated module for MCP tool response formatting and pagination utilities.
+ * Centralizes response formatting for MCP tool calls to eliminate redundant patterns.
+ *
+ * @module utils/formatters
+ */
+/**
+ * MCP Tool Response type - uses the exact shape expected by the SDK.
+ * The 'as const' assertion ensures the type literal is preserved.
+ */
+export type ToolResponse = {
+    content: Array<{
+        type: 'text';
+        text: string;
+    }>;
+    isError?: boolean;
+};
+/**
+ * Formats data as an MCP tool response with JSON content.
+ * Centralizes the response format to ensure consistency and reduce duplication.
+ *
+ * @param data - Any data to be JSON stringified
+ * @returns Formatted MCP tool response
+ */
+export declare function formatToolResponse(data: unknown): {
+    content: {
+        type: "text";
+        text: string;
+    }[];
+};
+/**
+ * Formats a simple text message as an MCP tool response.
+ * Use for success messages that don't need JSON formatting.
+ *
+ * @param message - Plain text message
+ * @returns Formatted MCP tool response
+ */
+export declare function formatTextResponse(message: string): {
+    content: {
+        type: "text";
+        text: string;
+    }[];
+};
+/**
+ * Formats raw string content as an MCP tool response.
+ * Use for export formats that return pre-formatted strings (markdown, CSV, etc.)
+ *
+ * @param content - Raw string content
+ * @returns Formatted MCP tool response
+ */
+export declare function formatRawResponse(content: string): {
+    content: {
+        type: "text";
+        text: string;
+    }[];
+};
+/**
+ * Formats an error as an MCP tool response with isError flag.
+ *
+ * @param error - Error object or message string
+ * @returns Formatted MCP tool error response
+ */
+export declare function formatErrorResponse(error: Error | string): {
+    content: {
+        type: "text";
+        text: string;
+    }[];
+    isError: boolean;
+};
+/**
+ * Validated pagination parameters with helper methods.
+ */
+export interface ValidatedPagination {
+    /** Validated offset (guaranteed >= 0) */
+    offset: number;
+    /** Validated limit (guaranteed within SEARCH_LIMITS.MIN to SEARCH_LIMITS.MAX) */
+    limit: number;
+    /**
+     * Check if there are more results beyond the current page.
+     * @param totalCount - Total number of items
+     * @returns true if there are more items after this page
+     */
+    hasMore: (totalCount: number) => boolean;
+}
+/**
+ * Validates and normalizes pagination parameters.
+ * Ensures offset is non-negative and limit is within configured bounds.
+ *
+ * @param offset - Starting position (default: 0)
+ * @param limit - Maximum results to return (default: SEARCH_LIMITS.DEFAULT)
+ * @returns Validated pagination parameters with helper methods
+ *
+ * @example
+ * ```typescript
+ * const pagination = validatePagination(10, 50);
+ * const results = items.slice(pagination.offset, pagination.offset + pagination.limit);
+ * if (pagination.hasMore(items.length)) {
+ *   console.log('More results available');
+ * }
+ * ```
+ */
+export declare function validatePagination(offset?: number, limit?: number): ValidatedPagination;
+/**
+ * Applies pagination to an array of items.
+ *
+ * @param items - Array to paginate
+ * @param pagination - Validated pagination parameters
+ * @returns Paginated slice of the array
+ *
+ * @example
+ * ```typescript
+ * const pagination = validatePagination(offset, limit);
+ * const pageResults = applyPagination(allResults, pagination);
+ * ```
+ */
+export declare function applyPagination<T>(items: T[], pagination: ValidatedPagination): T[];
+/**
+ * Applies pagination using raw offset and limit values.
+ * Combines validation and application in one call.
+ *
+ * @param items - Array to paginate
+ * @param offset - Starting position
+ * @param limit - Maximum results
+ * @returns Paginated slice of the array
+ */
+export declare function paginateArray<T>(items: T[], offset?: number, limit?: number): T[];
+/**
+ * Calculates pagination metadata for a result set.
+ *
+ * @param totalCount - Total number of items
+ * @param offset - Current offset
+ * @param limit - Current limit
+ * @returns Pagination metadata
+ */
+export declare function getPaginationMeta(totalCount: number, offset?: number, limit?: number): {
+    totalCount: number;
+    offset: number;
+    limit: number;
+    hasMore: boolean;
+    pageNumber: number;
+    totalPages: number;
+};
+//# sourceMappingURL=formatters.d.ts.map

package/dist/utils/formatters.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"formatters.d.ts","sourceRoot":"","sources":["../../src/utils/formatters.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAMH;;;GAGG;AACH,MAAM,MAAM,YAAY,GAAG;IACzB,OAAO,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAC/C,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB,CAAC;AAEF;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,OAAO;;;;;EAI/C;AAED;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,MAAM;;;;;EAIjD;AAED;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,MAAM;;;;;EAIhD;AAED;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,KAAK,GAAG,MAAM;;;;;;EAMxD;AAID;;GAEG;AACH,MAAM,WAAW,mBAAmB;IAClC,yCAAyC;IACzC,MAAM,EAAE,MAAM,CAAC;IACf,iFAAiF;IACjF,KAAK,EAAE,MAAM,CAAC;IACd;;;;OAIG;IACH,OAAO,EAAE,CAAC,UAAU,EAAE,MAAM,KAAK,OAAO,CAAC;CAC1C;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,kBAAkB,CAChC,MAAM,GAAE,MAAU,EAClB,KAAK,GAAE,MAA8B,GACpC,mBAAmB,CAYrB;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,eAAe,CAAC,CAAC,EAC/B,KAAK,EAAE,CAAC,EAAE,EACV,UAAU,EAAE,mBAAmB,GAC9B,CAAC,EAAE,CAEL;AAED;;;;;;;;GAQG;AACH,wBAAgB,aAAa,CAAC,CAAC,EAC7B,KAAK,EAAE,CAAC,EAAE,EACV,MAAM,GAAE,MAAU,EAClB,KAAK,GAAE,MAA8B,GACpC,CAAC,EAAE,CAGL;AAED;;;;;;;GAOG;AACH,wBAAgB,iBAAiB,CAC/B,UAAU,EAAE,MAAM,EAClB,MAAM,GAAE,MAAU,EAClB,KAAK,GAAE,MAA8B,GACpC;IACD,UAAU,EAAE,MAAM,CAAC;IACnB,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,OAAO,CAAC;IACjB,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,MAAM,CAAC;CACpB,CAWA"}

package/dist/utils/{paginationUtils.js → formatters.js}

@@ -1,10 +1,61 @@
 /**
- * Pagination Utilities
+ * Response and Pagination Formatters
  *
- * Centralizes pagination validation and application logic
- * to eliminate duplicate patterns across search implementations.
+ * Consolidated module for MCP tool response formatting and pagination utilities.
+ * Centralizes response formatting for MCP tool calls to eliminate redundant patterns.
+ *
+ * @module utils/formatters
  */
 import { SEARCH_LIMITS } from './constants.js';
+/**
+ * Formats data as an MCP tool response with JSON content.
+ * Centralizes the response format to ensure consistency and reduce duplication.
+ *
+ * @param data - Any data to be JSON stringified
+ * @returns Formatted MCP tool response
+ */
+export function formatToolResponse(data) {
+    return {
+        content: [{ type: 'text', text: JSON.stringify(data, null, 2) }],
+    };
+}
+/**
+ * Formats a simple text message as an MCP tool response.
+ * Use for success messages that don't need JSON formatting.
+ *
+ * @param message - Plain text message
+ * @returns Formatted MCP tool response
+ */
+export function formatTextResponse(message) {
+    return {
+        content: [{ type: 'text', text: message }],
+    };
+}
+/**
+ * Formats raw string content as an MCP tool response.
+ * Use for export formats that return pre-formatted strings (markdown, CSV, etc.)
+ *
+ * @param content - Raw string content
+ * @returns Formatted MCP tool response
+ */
+export function formatRawResponse(content) {
+    return {
+        content: [{ type: 'text', text: content }],
+    };
+}
+/**
+ * Formats an error as an MCP tool response with isError flag.
+ *
+ * @param error - Error object or message string
+ * @returns Formatted MCP tool error response
+ */
+export function formatErrorResponse(error) {
+    const message = error instanceof Error ? error.message : error;
+    return {
+        content: [{ type: 'text', text: message }],
+        isError: true,
+    };
+}
 /**
  * Validates and normalizes pagination parameters.
  * Ensures offset is non-negative and limit is within configured bounds.

package/dist/utils/index.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Utilities Module Barrel Export
+ *
+ * Centralizes all utility exports for convenient importing.
+ * Consolidated from 17 files to 9 focused modules (Phase 5 cleanup).
+ *
+ * @module utils
+ */
+export { KnowledgeGraphError, EntityNotFoundError, RelationNotFoundError, DuplicateEntityError, ValidationError, CycleDetectedError, InvalidImportanceError, FileOperationError, ImportError, ExportError, InsufficientEntitiesError, OperationCancelledError, } from './errors.js';
+export { FILE_EXTENSIONS, FILE_SUFFIXES, DEFAULT_FILE_NAMES, ENV_VARS, DEFAULT_BASE_DIR, LOG_PREFIXES, SIMILARITY_WEIGHTS, DEFAULT_DUPLICATE_THRESHOLD, SEARCH_LIMITS, IMPORTANCE_RANGE, GRAPH_LIMITS, QUERY_LIMITS, COMPRESSION_CONFIG, STREAMING_CONFIG, type CompressionQuality, } from './constants.js';
+export { compress, decompress, compressFile, decompressFile, compressToBase64, decompressFromBase64, hasBrotliExtension, getCompressionRatio, createMetadata, createUncompressedMetadata, type CompressionOptions, type CompressionResult, type CompressionMetadata, } from './compressionUtil.js';
+export { CompressedCache, type CompressedCacheOptions, type CompressedCacheStats, } from './compressedCache.js';
+export { logger } from './logger.js';
+export { levenshteinDistance, calculateTF, calculateIDF, calculateIDFFromTokenSets, calculateTFIDF, tokenize, } from './searchAlgorithms.js';
+export { NameIndex, TypeIndex, LowercaseCache, RelationIndex, } from './indexes.js';
+export { SearchCache, searchCaches, clearAllSearchCaches, getAllCacheStats, cleanupAllCaches, type CacheStats, } from './searchCache.js';
+export { EntitySchema, CreateEntitySchema, UpdateEntitySchema, RelationSchema, CreateRelationSchema, SearchQuerySchema, DateRangeSchema, TagAliasSchema, ExportFormatSchema, BatchCreateEntitiesSchema, BatchCreateRelationsSchema, EntityNamesSchema, DeleteRelationsSchema, AddObservationInputSchema, AddObservationsInputSchema, DeleteObservationInputSchema, DeleteObservationsInputSchema, ArchiveCriteriaSchema, SavedSearchInputSchema, SavedSearchUpdateSchema, ImportFormatSchema, ExtendedExportFormatSchema, MergeStrategySchema, ExportFilterSchema, OptionalTagsSchema, OptionalEntityNamesSchema, type EntityInput, type CreateEntityInput, type UpdateEntityInput, type RelationInput, type CreateRelationInput, type SearchQuery, type DateRange, type TagAlias, type ExportFormat, type AddObservationInput, type DeleteObservationInput, type ArchiveCriteriaInput, type SavedSearchInput, type SavedSearchUpdateInput, type ImportFormat, type ExtendedExportFormat, type MergeStrategy, type ExportFilterInput, type ValidationResult, formatZodErrors, validateWithSchema, validateSafe, validateArrayWithSchema, validateEntity, validateRelation, validateImportance, validateTags, } from './schemas.js';
+export { formatToolResponse, formatTextResponse, formatRawResponse, formatErrorResponse, type ToolResponse, validatePagination, applyPagination, paginateArray, getPaginationMeta, type ValidatedPagination, } from './formatters.js';
+export { findEntityByName, findEntitiesByNames, entityExists, getEntityIndex, removeEntityByName, getEntityNameSet, groupEntitiesByType, touchEntity, normalizeTag, normalizeTags, hasMatchingTag, hasAllTags, filterByTags, addUniqueTags, removeTags, isWithinDateRange, parseDateRange, isValidISODate, getCurrentTimestamp, isWithinImportanceRange, filterByImportance, filterByCreatedDate, filterByModifiedDate, filterByEntityType, entityPassesFilters, type CommonSearchFilters, validateFilePath, defaultMemoryPath, ensureMemoryFilePath, } from './entityUtils.js';
+export { parallelMap, parallelFilter, getPoolStats, shutdownParallelUtils, } from './parallelUtils.js';
+export { TaskPriority, TaskStatus, type Task, type TaskResult, type ProgressCallback, type BatchOptions, type QueueStats, TaskQueue, batchProcess, rateLimitedProcess, withRetry, debounce, throttle, } from './taskScheduler.js';
+export { checkCancellation, createProgressReporter, createProgress, executeWithPhases, processBatchesWithProgress, type PhaseDefinition, } from './operationUtils.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/utils/index.d.ts.map

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

package/dist/utils/index.js

@@ -2,38 +2,76 @@
  * Utilities Module Barrel Export
  *
  * Centralizes all utility exports for convenient importing.
- * Sprint 1 additions: responseFormatter, tagUtils, entityUtils,
- * validationHelper, paginationUtils, filterUtils
+ * Consolidated from 17 files to 9 focused modules (Phase 5 cleanup).
+ *
+ * @module utils
  */
-// Error types
-export { KnowledgeGraphError, EntityNotFoundError, RelationNotFoundError, DuplicateEntityError, ValidationError, CycleDetectedError, InvalidImportanceError, FileOperationError, ImportError, ExportError, InsufficientEntitiesError, } from './errors.js';
-// String utilities
-export { levenshteinDistance } from './levenshtein.js';
-export { calculateTF, calculateIDF, calculateTFIDF, tokenize } from './tfidf.js';
-// Logging
+// ==================== Error Types ====================
+export { KnowledgeGraphError, EntityNotFoundError, RelationNotFoundError, DuplicateEntityError, ValidationError, CycleDetectedError, InvalidImportanceError, FileOperationError, ImportError, ExportError, InsufficientEntitiesError, OperationCancelledError, } from './errors.js';
+// ==================== Constants ====================
+export { FILE_EXTENSIONS, FILE_SUFFIXES, DEFAULT_FILE_NAMES, ENV_VARS, DEFAULT_BASE_DIR, LOG_PREFIXES, SIMILARITY_WEIGHTS, DEFAULT_DUPLICATE_THRESHOLD, SEARCH_LIMITS, IMPORTANCE_RANGE, GRAPH_LIMITS, QUERY_LIMITS, COMPRESSION_CONFIG, STREAMING_CONFIG, } from './constants.js';
+// ==================== Compression Utilities ====================
+export { compress, decompress, compressFile, decompressFile, compressToBase64, decompressFromBase64, hasBrotliExtension, getCompressionRatio, createMetadata, createUncompressedMetadata, } from './compressionUtil.js';
+// ==================== Compressed Cache ====================
+export { CompressedCache, } from './compressedCache.js';
+// ==================== Logger ====================
 export { logger } from './logger.js';
+// ==================== Search Algorithms ====================
+export { levenshteinDistance, calculateTF, calculateIDF, calculateIDFFromTokenSets, calculateTFIDF, tokenize, } from './searchAlgorithms.js';
+// ==================== Indexes ====================
+export { NameIndex, TypeIndex, LowercaseCache, RelationIndex, } from './indexes.js';
+// ==================== Search Cache ====================
+export { SearchCache, searchCaches, clearAllSearchCaches, getAllCacheStats, cleanupAllCaches, } from './searchCache.js';
+// ==================== Schemas and Validation ====================
+// Consolidated from: schemas.ts, validationHelper.ts, validationUtils.ts
+export { 
+// Zod schemas - Entity/Relation
+EntitySchema, CreateEntitySchema, UpdateEntitySchema, RelationSchema, CreateRelationSchema, SearchQuerySchema, DateRangeSchema, TagAliasSchema, ExportFormatSchema, BatchCreateEntitiesSchema, BatchCreateRelationsSchema, EntityNamesSchema, DeleteRelationsSchema, 
+// Zod schemas - Observations
+AddObservationInputSchema, AddObservationsInputSchema, DeleteObservationInputSchema, DeleteObservationsInputSchema, 
+// Zod schemas - Archive
+ArchiveCriteriaSchema, 
+// Zod schemas - Saved Search
+SavedSearchInputSchema, SavedSearchUpdateSchema, 
+// Zod schemas - Import/Export
+ImportFormatSchema, ExtendedExportFormatSchema, MergeStrategySchema, ExportFilterSchema, 
+// Zod schemas - Search
+OptionalTagsSchema, OptionalEntityNamesSchema, 
+// Zod helpers
+formatZodErrors, validateWithSchema, validateSafe, validateArrayWithSchema, 
+// Manual validation functions
+validateEntity, validateRelation, validateImportance, validateTags, } from './schemas.js';
+// ==================== Formatters ====================
+// Consolidated from: responseFormatter.ts, paginationUtils.ts
+export { 
+// Response formatting
+formatToolResponse, formatTextResponse, formatRawResponse, formatErrorResponse, 
+// Pagination utilities
+validatePagination, applyPagination, paginateArray, getPaginationMeta, } from './formatters.js';
+// ==================== Entity Utilities ====================
+// Consolidated from: entityUtils.ts, tagUtils.ts, dateUtils.ts, filterUtils.ts, pathUtils.ts
+export { 
+// Entity lookup
+findEntityByName, findEntitiesByNames, entityExists, getEntityIndex, removeEntityByName, getEntityNameSet, groupEntitiesByType, touchEntity, 
+// Tag utilities
+normalizeTag, normalizeTags, hasMatchingTag, hasAllTags, filterByTags, addUniqueTags, removeTags, 
 // Date utilities
-export { isWithinDateRange, parseDateRange, isValidISODate, getCurrentTimestamp } from './dateUtils.js';
-// Validation utilities
-export { validateEntity, validateRelation, validateImportance, validateTags } from './validationUtils.js';
+isWithinDateRange, parseDateRange, isValidISODate, getCurrentTimestamp, 
+// Filter utilities
+isWithinImportanceRange, filterByImportance, filterByCreatedDate, filterByModifiedDate, filterByEntityType, entityPassesFilters, 
 // Path utilities
-export { defaultMemoryPath, ensureMemoryFilePath, validateFilePath } from './pathUtils.js';
-// Constants
-export { FILE_EXTENSIONS, FILE_SUFFIXES, DEFAULT_FILE_NAMES, ENV_VARS, DEFAULT_BASE_DIR, LOG_PREFIXES, SIMILARITY_WEIGHTS, DEFAULT_DUPLICATE_THRESHOLD, SEARCH_LIMITS, IMPORTANCE_RANGE, } from './constants.js';
-// Zod schemas
-export { EntitySchema, CreateEntitySchema, UpdateEntitySchema, RelationSchema, CreateRelationSchema, SearchQuerySchema, DateRangeSchema, TagAliasSchema, ExportFormatSchema, BatchCreateEntitiesSchema, BatchCreateRelationsSchema, EntityNamesSchema, DeleteRelationsSchema, } from './schemas.js';
-// Search cache
-export { SearchCache, searchCaches, clearAllSearchCaches, getAllCacheStats, cleanupAllCaches, } from './searchCache.js';
-// === Sprint 1: New Utility Exports ===
-// MCP Response formatting (Task 1.1)
-export { formatToolResponse, formatTextResponse, formatRawResponse, formatErrorResponse, } from './responseFormatter.js';
-// Tag utilities (Task 1.2)
-export { normalizeTag, normalizeTags, hasMatchingTag, hasAllTags, filterByTags, addUniqueTags, removeTags, } from './tagUtils.js';
-// Entity utilities (Task 1.3)
-export { findEntityByName, findEntitiesByNames, entityExists, getEntityIndex, removeEntityByName, getEntityNameSet, groupEntitiesByType, touchEntity, } from './entityUtils.js';
-// Zod validation helpers (Task 1.4)
-export { formatZodErrors, validateWithSchema, validateSafe, validateArrayWithSchema, } from './validationHelper.js';
-// Pagination utilities (Task 1.5)
-export { validatePagination, applyPagination, paginateArray, getPaginationMeta, } from './paginationUtils.js';
-// Filter utilities (Task 1.6)
-export { isWithinImportanceRange, filterByImportance, filterByCreatedDate, filterByModifiedDate, filterByEntityType, entityPassesFilters, } from './filterUtils.js';
+validateFilePath, defaultMemoryPath, ensureMemoryFilePath, } from './entityUtils.js';
+// ==================== Parallel Utilities ====================
+export { parallelMap, parallelFilter, getPoolStats, shutdownParallelUtils, } from './parallelUtils.js';
+// ==================== Task Scheduler ====================
+export { 
+// Types and Enums
+TaskPriority, TaskStatus, 
+// Task Queue
+TaskQueue, 
+// Batch Processing
+batchProcess, rateLimitedProcess, withRetry, 
+// Rate Limiting
+debounce, throttle, } from './taskScheduler.js';
+// ==================== Operation Utilities (Phase 9B) ====================
+export { checkCancellation, createProgressReporter, createProgress, executeWithPhases, processBatchesWithProgress, } from './operationUtils.js';

package/dist/utils/indexes.d.ts

@@ -0,0 +1,270 @@
+/**
+ * Search Indexes
+ *
+ * Provides O(1) lookup structures to avoid repeated linear scans.
+ * - NameIndex: O(1) entity lookup by name
+ * - TypeIndex: O(1) entities by type
+ * - LowercaseCache: Pre-computed lowercase strings to avoid repeated toLowerCase()
+ * - RelationIndex: O(1) relation lookup by entity name (from/to)
+ * - ObservationIndex: O(1) observation word lookup by entity
+ *
+ * @module utils/indexes
+ */
+import type { Entity, LowercaseData, Relation } from '../types/index.js';
+/**
+ * NameIndex provides O(1) entity lookup by name.
+ *
+ * Uses a Map internally for constant-time access.
+ */
+export declare class NameIndex {
+    private index;
+    /**
+     * Build the index from an array of entities.
+     * Clears any existing index data first.
+     */
+    build(entities: Entity[]): void;
+    /**
+     * Get an entity by name in O(1) time.
+     */
+    get(name: string): Entity | undefined;
+    /**
+     * Add a single entity to the index.
+     */
+    add(entity: Entity): void;
+    /**
+     * Remove an entity from the index by name.
+     */
+    remove(name: string): void;
+    /**
+     * Check if an entity exists in the index.
+     */
+    has(name: string): boolean;
+    /**
+     * Get the number of entities in the index.
+     */
+    get size(): number;
+    /**
+     * Clear all entries from the index.
+     */
+    clear(): void;
+}
+/**
+ * TypeIndex provides O(1) lookup of entities by type.
+ *
+ * Uses a Map<type, Set<entityName>> structure for efficient type queries.
+ * Type comparisons are case-insensitive.
+ */
+export declare class TypeIndex {
+    private index;
+    /**
+     * Build the index from an array of entities.
+     * Clears any existing index data first.
+     */
+    build(entities: Entity[]): void;
+    /**
+     * Get all entity names of a given type in O(1) time.
+     * Type comparison is case-insensitive.
+     */
+    getNames(entityType: string): Set<string>;
+    /**
+     * Add an entity to the type index.
+     */
+    add(entity: Entity): void;
+    /**
+     * Remove an entity from the type index.
+     * Requires the entity type to know which bucket to remove from.
+     */
+    remove(entityName: string, entityType: string): void;
+    /**
+     * Update an entity's type in the index.
+     * Removes from old type and adds to new type.
+     */
+    updateType(entityName: string, oldType: string, newType: string): void;
+    /**
+     * Get all unique types in the index.
+     */
+    getTypes(): string[];
+    /**
+     * Clear all entries from the index.
+     */
+    clear(): void;
+    private addToIndex;
+}
+/**
+ * LowercaseCache pre-computes lowercase versions of all searchable fields.
+ *
+ * Eliminates the need for repeated toLowerCase() calls during search,
+ * which is expensive with many entities and observations.
+ */
+export declare class LowercaseCache {
+    private cache;
+    /**
+     * Build the cache from an array of entities.
+     * Clears any existing cache data first.
+     */
+    build(entities: Entity[]): void;
+    /**
+     * Get pre-computed lowercase data for an entity.
+     */
+    get(entityName: string): LowercaseData | undefined;
+    /**
+     * Add or update an entity in the cache.
+     */
+    set(entity: Entity): void;
+    /**
+     * Remove an entity from the cache.
+     */
+    remove(entityName: string): void;
+    /**
+     * Check if an entity exists in the cache.
+     */
+    has(entityName: string): boolean;
+    /**
+     * Clear all entries from the cache.
+     */
+    clear(): void;
+    /**
+     * Get the number of entries in the cache.
+     */
+    get size(): number;
+    private computeLowercase;
+}
+/**
+ * RelationIndex provides O(1) lookup of relations by entity name.
+ *
+ * Maintains two separate indexes for efficient directional queries:
+ * - fromIndex: Map from source entity name to its outgoing relations
+ * - toIndex: Map from target entity name to its incoming relations
+ *
+ * This eliminates O(n) array scans when looking up relations for an entity.
+ */
+export declare class RelationIndex {
+    /** Index of relations by source (from) entity */
+    private fromIndex;
+    /** Index of relations by target (to) entity */
+    private toIndex;
+    /**
+     * Build the index from an array of relations.
+     * Clears any existing index data first.
+     */
+    build(relations: Relation[]): void;
+    /**
+     * Get all relations where the entity is the source (outgoing relations).
+     * Returns empty array if no relations found.
+     */
+    getRelationsFrom(entityName: string): Relation[];
+    /**
+     * Get all relations where the entity is the target (incoming relations).
+     * Returns empty array if no relations found.
+     */
+    getRelationsTo(entityName: string): Relation[];
+    /**
+     * Get all relations involving the entity (both incoming and outgoing).
+     * Returns empty array if no relations found.
+     */
+    getRelationsFor(entityName: string): Relation[];
+    /**
+     * Add a single relation to the index.
+     */
+    add(relation: Relation): void;
+    /**
+     * Remove a relation from the index.
+     * Matches by from, to, and relationType.
+     */
+    remove(relation: Relation): void;
+    /**
+     * Remove all relations involving a specific entity.
+     * Returns the relations that were removed.
+     */
+    removeAllForEntity(entityName: string): Relation[];
+    /**
+     * Check if any relations exist for an entity.
+     */
+    hasRelations(entityName: string): boolean;
+    /**
+     * Get count of outgoing relations for an entity.
+     */
+    getOutgoingCount(entityName: string): number;
+    /**
+     * Get count of incoming relations for an entity.
+     */
+    getIncomingCount(entityName: string): number;
+    /**
+     * Get total count of unique relations in the index.
+     */
+    get size(): number;
+    /**
+     * Clear all entries from the index.
+     */
+    clear(): void;
+    private addToIndexes;
+}
+/**
+ * Inverted index mapping observation keywords to entity names.
+ * Enables O(1) lookup for 'which entities mention word X?' queries.
+ * Words are normalized to lowercase and split on whitespace/punctuation.
+ */
+export declare class ObservationIndex {
+    private index;
+    private entityObservations;
+    /**
+     * Add an entity's observations to the index.
+     * Tokenizes observations into words and creates reverse mapping.
+     *
+     * @param entityName - Name of the entity
+     * @param observations - Array of observation strings
+     */
+    add(entityName: string, observations: string[]): void;
+    /**
+     * Remove an entity from the index.
+     * Cleans up all word mappings for this entity.
+     *
+     * @param entityName - Name of the entity to remove
+     */
+    remove(entityName: string): void;
+    /**
+     * Get all entities that have observations containing the given word.
+     * Word matching is case-insensitive.
+     *
+     * @param word - Word to search for
+     * @returns Set of entity names containing this word
+     */
+    getEntitiesWithWord(word: string): Set<string>;
+    /**
+     * Get all entities that have observations containing ANY of the given words (union).
+     *
+     * @param words - Array of words to search for
+     * @returns Set of entity names containing any of the words
+     */
+    getEntitiesWithAnyWord(words: string[]): Set<string>;
+    /**
+     * Get all entities that have observations containing ALL of the given words (intersection).
+     *
+     * @param words - Array of words that must all be present
+     * @returns Set of entity names containing all of the words
+     */
+    getEntitiesWithAllWords(words: string[]): Set<string>;
+    /**
+     * Clear all entries from the index.
+     */
+    clear(): void;
+    /**
+     * Get statistics about the index.
+     *
+     * @returns Object with wordCount and entityCount
+     */
+    getStats(): {
+        wordCount: number;
+        entityCount: number;
+    };
+    /**
+     * Tokenize text into searchable words.
+     * Normalizes to lowercase, splits on non-alphanumeric characters,
+     * and filters out words less than 2 characters.
+     *
+     * @param text - Text to tokenize
+     * @returns Array of normalized words
+     */
+    private tokenize;
+}
+//# sourceMappingURL=indexes.d.ts.map

package/dist/utils/indexes.d.ts.map

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