@danielsimonjr/memoryjs 1.2.2 → 1.4.0

package/dist/index.d.cts

@@ -2,6 +2,222 @@ import { z, ZodError, ZodSchema } from 'zod';
 import workerpool, { Pool, PoolStats } from '@danielsimonjr/workerpool';
 import { EventEmitter } from 'events';
 
+/**
+ * Search Types
+ *
+ * Type definitions for search operations, tracing, and explanation.
+ * Phase 1 Sprint 6-7: Query logging, tracing, and result explanation.
+ *
+ * @module types/search
+ */
+/**
+ * Log level for query logging.
+ */
+type LogLevel = 'debug' | 'info' | 'warn' | 'error';
+/**
+ * Entry in the query log.
+ */
+interface QueryLogEntry {
+    /** ISO 8601 timestamp */
+    timestamp: string;
+    /** Unique identifier for the query */
+    queryId: string;
+    /** Log level */
+    level: LogLevel;
+    /** Event name */
+    event: string;
+    /** Original query text */
+    queryText?: string;
+    /** Type of search performed */
+    queryType?: string;
+    /** Duration in milliseconds */
+    duration?: number;
+    /** Number of results */
+    resultCount?: number;
+    /** Additional metadata */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Complete trace of a search query execution.
+ */
+interface QueryTrace {
+    /** Unique identifier for this query */
+    queryId: string;
+    /** Original query text */
+    queryText: string;
+    /** Type of search performed */
+    queryType: 'basic' | 'fuzzy' | 'boolean' | 'ranked' | 'bm25' | 'semantic' | 'hybrid';
+    /** ISO 8601 timestamp when query started */
+    startTime: string;
+    /** ISO 8601 timestamp when query completed */
+    endTime: string;
+    /** Total duration in milliseconds */
+    durationMs: number;
+    /** Number of results returned */
+    resultCount: number;
+    /** Breakdown of time spent in each stage */
+    stages: QueryStage[];
+    /** Additional metadata */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * A single stage in query execution.
+ */
+interface QueryStage {
+    /** Name of this stage */
+    name: string;
+    /** Duration in milliseconds */
+    durationMs: number;
+    /** Items processed in this stage */
+    itemsProcessed?: number;
+    /** Additional stage-specific data */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Explanation of why an entity matched a search query.
+ */
+interface SearchExplanation {
+    /** Entity that was matched */
+    entityName: string;
+    /** Final computed score */
+    totalScore: number;
+    /** Breakdown of scoring signals */
+    signals: ScoringSignal[];
+    /** Terms from query that matched */
+    matchedTerms: MatchedTerm[];
+    /** Boost factors applied */
+    boosts: ScoreBoost[];
+    /** Human-readable summary */
+    summary: string;
+}
+/**
+ * A single scoring signal contributing to the total score.
+ */
+interface ScoringSignal {
+    /** Name of this signal (e.g., 'tf-idf', 'bm25', 'semantic') */
+    name: string;
+    /** Raw value of this signal */
+    value: number;
+    /** Weight applied to this signal */
+    weight: number;
+    /** Contribution to final score (value * weight) */
+    contribution: number;
+    /** Percentage of total score from this signal */
+    percentage: number;
+    /** Additional signal-specific details */
+    details?: Record<string, unknown>;
+}
+/**
+ * Information about a matched term.
+ */
+interface MatchedTerm {
+    /** The term that matched */
+    term: string;
+    /** Where it matched (name, observation, tag) */
+    field: 'name' | 'entityType' | 'observation' | 'tag';
+    /** Number of times it matched */
+    frequency: number;
+    /** TF-IDF or similar score for this term */
+    termScore: number;
+}
+/**
+ * A boost factor applied to the score.
+ */
+interface ScoreBoost {
+    /** Name of the boost */
+    name: string;
+    /** Multiplier applied */
+    multiplier: number;
+    /** Reason for the boost */
+    reason: string;
+}
+/**
+ * Search result with explanation attached.
+ */
+interface ExplainedSearchResult<T = unknown> {
+    /** The matched entity */
+    entity: T;
+    /** Computed score */
+    score: number;
+    /** Detailed explanation */
+    explanation: SearchExplanation;
+}
+/**
+ * Union of all query node types.
+ */
+type QueryNode = TermNode | PhraseNode | WildcardNode | ProximityNode | FieldNode | BooleanOpNode;
+/**
+ * A simple term node.
+ */
+interface TermNode {
+    type: 'term';
+    value: string;
+}
+/**
+ * An exact phrase node.
+ */
+interface PhraseNode {
+    type: 'phrase';
+    terms: string[];
+}
+/**
+ * A wildcard pattern node.
+ */
+interface WildcardNode {
+    type: 'wildcard';
+    pattern: string;
+    regex: RegExp;
+}
+/**
+ * A proximity search node.
+ */
+interface ProximityNode {
+    type: 'proximity';
+    terms: string[];
+    distance: number;
+}
+/**
+ * A field-specific search node.
+ */
+interface FieldNode {
+    type: 'field';
+    field: string;
+    query: QueryNode;
+}
+/**
+ * A boolean operator node in the query parser.
+ * Note: Different from BooleanQueryNode in types.ts which is for AST representation.
+ */
+interface BooleanOpNode {
+    type: 'boolean';
+    operator: 'AND' | 'OR' | 'NOT';
+    operands: QueryNode[];
+}
+/**
+ * Builder for creating QueryTrace objects.
+ */
+declare class QueryTraceBuilder {
+    private trace;
+    private stageStart?;
+    constructor(queryId: string, queryText: string, queryType: QueryTrace['queryType']);
+    /**
+     * Start timing a stage.
+     */
+    startStage(_name: string): this;
+    /**
+     * End timing the current stage and record it.
+     */
+    endStage(name: string, metadata?: Record<string, unknown>): this;
+    /**
+     * Add a completed stage with known duration.
+     */
+    addStage(name: string, durationMs: number, metadata?: Record<string, unknown>): this;
+    /**
+     * Complete the trace and return the final QueryTrace.
+     */
+    complete(resultCount: number, metadata?: Record<string, unknown>): QueryTrace;
+}
+
 /**
  * Task Scheduler
  *
@@ -345,6 +561,44 @@ interface Entity {
     /** Optional parent entity name for hierarchical nesting */
     parentId?: string;
 }
+/**
+ * Typed properties for relations.
+ * Use this for structured access to common relation attributes.
+ * For arbitrary key-value pairs, use the `metadata` field instead.
+ *
+ * @example
+ * ```typescript
+ * const relation: Relation = {
+ *   from: 'Alice',
+ *   to: 'Bob',
+ *   relationType: 'knows',
+ *   weight: 0.8,
+ *   properties: {
+ *     bidirectional: true,
+ *     validFrom: '2024-01-01',
+ *     source: 'social_network_import',
+ *   },
+ * };
+ * ```
+ */
+interface RelationProperties {
+    /** Whether this relation is bidirectional (A->B implies B->A) */
+    bidirectional?: boolean;
+    /** Temporal validity - when this relation became valid (ISO 8601) */
+    validFrom?: string;
+    /** Temporal validity - when this relation stops being valid (ISO 8601) */
+    validUntil?: string;
+    /** Source/provenance of this relation */
+    source?: string;
+    /** How this relation was established */
+    method?: 'observed' | 'inferred' | 'declared' | 'imported';
+    /** Number of times this relation has been confirmed */
+    confirmationCount?: number;
+    /** Number of times this relation has been contradicted */
+    contradictionCount?: number;
+    /** Custom typed properties for domain-specific extensions */
+    custom?: Record<string, unknown>;
+}
 /**
  * Represents a directed relation between two entities.
  *
@@ -373,6 +627,14 @@ interface Relation {
     createdAt?: string;
     /** ISO 8601 timestamp when relation was last modified */
     lastModified?: string;
+    /** Relation weight/strength (0-1), useful for weighted graph algorithms */
+    weight?: number;
+    /** Confidence score for this relation (0-1) */
+    confidence?: number;
+    /** Structured properties for typed access */
+    properties?: RelationProperties;
+    /** Arbitrary metadata for custom attributes */
+    metadata?: Record<string, unknown>;
 }
 /**
  * Represents the complete knowledge graph structure.
@@ -1365,13 +1627,33 @@ interface CentralityResult {
     algorithm: 'degree' | 'betweenness' | 'pagerank';
 }
 /**
- * Phase 4 Sprint 9: Extended relation with optional weight and metadata.
+ * A relation that has a weight value (required).
+ * Useful for weighted graph algorithms (e.g., shortest path with weights).
+ *
+ * NOTE: The base Relation interface now has optional weight/metadata (Phase 1 Sprint 4).
+ * Use WeightedRelation when weight is required.
  */
 interface WeightedRelation extends Relation {
-    /** Optional weight for the relation (default: 1.0) */
-    weight?: number;
-    /** Optional metadata for the relation */
-    metadata?: Record<string, unknown>;
+    /** Weight for the relation - required for weighted algorithms (0-1) */
+    weight: number;
+}
+/**
+ * A relation with temporal validity.
+ * Use for time-varying knowledge that has a valid date range.
+ */
+interface TemporalRelation extends Relation {
+    properties: RelationProperties & {
+        validFrom: string;
+    };
+}
+/**
+ * A bidirectional relation (symmetric: A->B implies B->A).
+ * Use for symmetric relationships like "married_to", "sibling_of".
+ */
+interface BidirectionalRelation extends Relation {
+    properties: RelationProperties & {
+        bidirectional: true;
+    };
 }
 /**
  * Phase 12 Sprint 5: Embedding mode for query-optimized encoding.
@@ -3027,20 +3309,154 @@ interface AgentMetadata {
     metadata?: Record<string, unknown>;
 }
 
+/**
+ * Progress Types
+ *
+ * Type definitions for progress reporting.
+ * Phase 1 Sprint 10: Progress Callbacks and Error Improvements.
+ *
+ * @module types/progress
+ */
+/**
+ * Progress information for batch operations.
+ */
+interface ProgressInfo {
+    /** Current item index (0-based) */
+    current: number;
+    /** Total number of items */
+    total: number;
+    /** Percentage complete (0-100) */
+    percentage: number;
+    /** Human-readable progress message */
+    message: string;
+    /** Current phase of operation (for multi-phase operations) */
+    phase?: string;
+    /** Name/identifier of current item being processed */
+    currentItem?: string;
+    /** Estimated time remaining in milliseconds */
+    estimatedRemainingMs?: number;
+    /** Start time of operation (ISO 8601) */
+    startedAt?: string;
+    /** Whether operation can be cancelled */
+    cancellable?: boolean;
+}
+/**
+ * Callback for receiving detailed progress updates.
+ * Uses ProgressInfo for rich progress information.
+ * (Note: utils/taskScheduler.ts exports a simpler ProgressInfoCallback type)
+ */
+type ProgressInfoCallback = (progress: ProgressInfo) => void;
+/**
+ * Options for operations that support progress reporting.
+ */
+interface ProgressOptions {
+    /** Callback to receive progress updates */
+    onProgress?: ProgressInfoCallback;
+    /** Minimum interval between progress callbacks (ms) */
+    progressInterval?: number;
+    /** Cancellation token */
+    signal?: AbortSignal;
+}
+/**
+ * Helper to create progress info.
+ */
+declare function createProgressInfo(current: number, total: number, options?: {
+    phase?: string;
+    currentItem?: string;
+    message?: string;
+    startedAt?: Date;
+    cancellable?: boolean;
+}): ProgressInfo;
+/**
+ * Throttle progress callbacks to avoid overwhelming consumers.
+ */
+declare function createThrottledProgress(callback: ProgressInfoCallback, intervalMs?: number): ProgressInfoCallback;
+/**
+ * Create a detailed progress reporter with automatic throttling.
+ * Returns an object with report/complete/cancel methods.
+ * (Note: utils/operationUtils.ts exports a simpler createProgressReporter function)
+ */
+declare function createDetailedProgressReporter(total: number, callback?: ProgressInfoCallback, options?: {
+    intervalMs?: number;
+    phase?: string;
+    cancellable?: boolean;
+}): {
+    report: (current: number, item?: string) => void;
+    complete: () => void;
+    cancel: () => void;
+};
+
 /**
  * Custom Error Types
  *
  * Defines custom error classes for better error handling and debugging.
+ * Phase 1 Sprint 10: Enhanced with ErrorCode enum and suggestions.
  *
  * @module utils/errors
  */
+/**
+ * Error codes for programmatic handling.
+ * Phase 1 Sprint 10: Centralized error codes.
+ */
+declare enum ErrorCode {
+    VALIDATION_FAILED = "VALIDATION_ERROR",
+    REQUIRED_FIELD_MISSING = "REQUIRED_FIELD_MISSING",
+    INVALID_FIELD_VALUE = "INVALID_FIELD_VALUE",
+    SCHEMA_VALIDATION_FAILED = "SCHEMA_VALIDATION_FAILED",
+    STORAGE_READ_FAILED = "STORAGE_READ_FAILED",
+    STORAGE_WRITE_FAILED = "STORAGE_WRITE_FAILED",
+    ENTITY_NOT_FOUND = "ENTITY_NOT_FOUND",
+    RELATION_NOT_FOUND = "RELATION_NOT_FOUND",
+    DUPLICATE_ENTITY = "DUPLICATE_ENTITY",
+    STORAGE_CORRUPTED = "STORAGE_CORRUPTED",
+    FILE_OPERATION_ERROR = "FILE_OPERATION_ERROR",
+    SEARCH_FAILED = "SEARCH_FAILED",
+    INVALID_QUERY = "INVALID_QUERY",
+    INDEX_NOT_READY = "INDEX_NOT_READY",
+    EMBEDDING_FAILED = "EMBEDDING_FAILED",
+    INVALID_CONFIG = "INVALID_CONFIG",
+    MISSING_DEPENDENCY = "MISSING_DEPENDENCY",
+    UNSUPPORTED_FEATURE = "UNSUPPORTED_FEATURE",
+    CYCLE_DETECTED = "CYCLE_DETECTED",
+    INVALID_IMPORTANCE = "INVALID_IMPORTANCE",
+    INSUFFICIENT_ENTITIES = "INSUFFICIENT_ENTITIES",
+    OPERATION_CANCELLED = "OPERATION_CANCELLED",
+    IMPORT_ERROR = "IMPORT_ERROR",
+    EXPORT_ERROR = "EXPORT_ERROR",
+    UNKNOWN_ERROR = "UNKNOWN_ERROR"
+}
+/**
+ * Options for enhanced error construction.
+ */
+interface ErrorOptions {
+    /** Additional context for debugging */
+    context?: Record<string, unknown>;
+    /** Recovery suggestions for the user */
+    suggestions?: string[];
+    /** Original error that caused this one */
+    cause?: Error;
+}
 /**
  * Base error class for all knowledge graph errors.
  * Extends the native Error class with additional context.
+ * Phase 1 Sprint 10: Enhanced with suggestions and context.
  */
 declare class KnowledgeGraphError extends Error {
-    readonly code?: string | undefined;
-    constructor(message: string, code?: string | undefined);
+    /** Error code for programmatic handling */
+    readonly code: string;
+    /** Additional context for debugging */
+    readonly context?: Record<string, unknown>;
+    /** Recovery suggestions for the user */
+    readonly suggestions: string[];
+    constructor(message: string, code?: string, options?: ErrorOptions);
+    /**
+     * Get a formatted error message with suggestions.
+     */
+    getDetailedMessage(): string;
+    /**
+     * Convert to a plain object for serialization.
+     */
+    toJSON(): Record<string, unknown>;
 }
 /**
  * Error thrown when an entity is not found.
@@ -3062,6 +3478,7 @@ declare class DuplicateEntityError extends KnowledgeGraphError {
 }
 /**
  * Error thrown when validation fails.
+ * Note: Maintains backward-compatible signature with errors: string[].
  */
 declare class ValidationError extends KnowledgeGraphError {
     readonly errors: string[];
@@ -3122,6 +3539,24 @@ declare class OperationCancelledError extends KnowledgeGraphError {
     constructor(operation?: string);
 }
 
+/**
+ * Error Suggestion Generator
+ *
+ * Provides context-specific suggestions for error recovery.
+ * Phase 1 Sprint 10: Progress Callbacks and Error Improvements.
+ *
+ * @module utils/errorSuggestions
+ */
+
+/**
+ * Generate context-specific suggestions based on error code and context.
+ */
+declare function generateSuggestions(code: ErrorCode | string, context?: Record<string, unknown>): string[];
+/**
+ * Get a single-line recovery hint for an error code.
+ */
+declare function getQuickHint(code: ErrorCode | string): string;
+
 /**
  * Application Constants
  *
@@ -4531,16 +4966,16 @@ declare const SavedSearchInputSchema: z.ZodObject<{
     maxImportance: z.ZodOptional<z.ZodNumber>;
     entityType: z.ZodOptional<z.ZodString>;
 }, "strict", z.ZodTypeAny, {
-    query: string;
     name: string;
+    query: string;
     entityType?: string | undefined;
     tags?: string[] | undefined;
     description?: string | undefined;
     minImportance?: number | undefined;
     maxImportance?: number | undefined;
 }, {
-    query: string;
     name: string;
+    query: string;
     entityType?: string | undefined;
     tags?: string[] | undefined;
     description?: string | undefined;
@@ -4559,15 +4994,15 @@ declare const SavedSearchUpdateSchema: z.ZodObject<{
     maxImportance: z.ZodOptional<z.ZodNumber>;
     entityType: z.ZodOptional<z.ZodString>;
 }, "strict", z.ZodTypeAny, {
-    query?: string | undefined;
     entityType?: string | undefined;
+    query?: string | undefined;
     tags?: string[] | undefined;
     description?: string | undefined;
     minImportance?: number | undefined;
     maxImportance?: number | undefined;
 }, {
-    query?: string | undefined;
     entityType?: string | undefined;
+    query?: string | undefined;
     tags?: string[] | undefined;
     description?: string | undefined;
     minImportance?: number | undefined;
@@ -5963,180 +6398,758 @@ declare function mapParallel<TInput, TOutput>(items: TInput[], mapper: (item: TI
 declare function filterParallel<T>(items: T[], predicate: (item: T, index: number) => Promise<boolean>, concurrency?: number): Promise<T[]>;
 
 /**
- * Memory Usage Monitor
- *
- * Phase 12 Sprint 6: Track memory usage across all components
- * with human-readable formatting.
- *
- * @module utils/MemoryMonitor
+ * Memory Usage Monitor
+ *
+ * Phase 12 Sprint 6: Track memory usage across all components
+ * with human-readable formatting.
+ *
+ * @module utils/MemoryMonitor
+ */
+/**
+ * Memory usage for a single component.
+ */
+interface ComponentMemoryUsage {
+    /** Component name */
+    name: string;
+    /** Estimated memory usage in bytes */
+    bytes: number;
+    /** Item count (if applicable) */
+    itemCount?: number;
+    /** Average bytes per item */
+    bytesPerItem?: number;
+}
+/**
+ * Aggregate memory usage statistics.
+ */
+interface MemoryUsageStats {
+    /** Total memory usage in bytes */
+    totalBytes: number;
+    /** Formatted total memory */
+    totalFormatted: string;
+    /** Per-component breakdown */
+    components: ComponentMemoryUsage[];
+    /** Timestamp of measurement */
+    timestamp: Date;
+    /** Node.js heap stats (if available) */
+    heapStats?: {
+        heapUsed: number;
+        heapTotal: number;
+        external: number;
+        rss: number;
+    };
+}
+/**
+ * Memory threshold configuration.
+ */
+interface MemoryThresholds {
+    /** Warning threshold in bytes */
+    warning: number;
+    /** Critical threshold in bytes */
+    critical: number;
+}
+/**
+ * Memory alert.
+ */
+interface MemoryAlert {
+    /** Alert level */
+    level: 'warning' | 'critical';
+    /** Component that triggered the alert */
+    component: string;
+    /** Current usage */
+    currentBytes: number;
+    /** Threshold exceeded */
+    threshold: number;
+    /** Message */
+    message: string;
+}
+/**
+ * Callback for memory change events.
+ */
+type MemoryChangeCallback = (usage: MemoryUsageStats) => void;
+/**
+ * Memory Monitor for tracking usage across components.
+ *
+ * @example
+ * ```typescript
+ * const monitor = new MemoryMonitor();
+ *
+ * // Register components
+ * monitor.registerComponent('entities', () => entities.length * 500);
+ * monitor.registerComponent('vectors', () => vectors.size * dimension * 4);
+ *
+ * // Get usage stats
+ * const stats = monitor.getUsage();
+ * console.log(`Total memory: ${stats.totalFormatted}`);
+ *
+ * // Check for alerts
+ * const alerts = monitor.checkThresholds();
+ * ```
+ */
+declare class MemoryMonitor {
+    private componentEstimators;
+    private itemCounters;
+    private thresholds;
+    private listeners;
+    private lastUsage;
+    constructor(thresholds?: Partial<MemoryThresholds>);
+    /**
+     * Register a component for memory tracking.
+     *
+     * @param name - Component name
+     * @param estimator - Function that returns estimated bytes
+     * @param itemCounter - Optional function that returns item count
+     */
+    registerComponent(name: string, estimator: () => number, itemCounter?: () => number): void;
+    /**
+     * Unregister a component.
+     *
+     * @param name - Component name
+     */
+    unregisterComponent(name: string): void;
+    /**
+     * Get current memory usage statistics.
+     */
+    getUsage(): MemoryUsageStats;
+    /**
+     * Get memory usage for a specific component.
+     *
+     * @param name - Component name
+     */
+    getComponentUsage(name: string): ComponentMemoryUsage | undefined;
+    /**
+     * Check memory thresholds and return alerts.
+     */
+    checkThresholds(): MemoryAlert[];
+    /**
+     * Set memory thresholds.
+     *
+     * @param thresholds - New threshold values
+     */
+    setThresholds(thresholds: Partial<MemoryThresholds>): void;
+    /**
+     * Get current thresholds.
+     */
+    getThresholds(): MemoryThresholds;
+    /**
+     * Add a listener for memory changes.
+     *
+     * @param callback - Callback to invoke on memory changes
+     */
+    addListener(callback: MemoryChangeCallback): void;
+    /**
+     * Remove a listener.
+     *
+     * @param callback - Callback to remove
+     */
+    removeListener(callback: MemoryChangeCallback): void;
+    /**
+     * Get a human-readable summary of memory usage.
+     */
+    getSummary(): string;
+    /**
+     * Get the last recorded usage without triggering a new measurement.
+     */
+    getLastUsage(): MemoryUsageStats | null;
+    /**
+     * Format bytes as human-readable string.
+     *
+     * @param bytes - Number of bytes
+     */
+    formatBytes(bytes: number): string;
+    /**
+     * Parse a formatted byte string back to number.
+     *
+     * @param formatted - Formatted string like "10 MB"
+     */
+    parseBytes(formatted: string): number;
+    /**
+     * Clear all registered components.
+     */
+    clear(): void;
+    private notifyListeners;
+}
+/**
+ * Singleton instance for global memory monitoring.
+ */
+declare const globalMemoryMonitor: MemoryMonitor;
+
+/**
+ * Relation Helper Utilities
+ *
+ * Type guards and builder pattern for working with relations.
+ *
+ * @module utils/relationHelpers
+ */
+
+/**
+ * Type guard to check if a relation has a weight.
+ *
+ * @param relation - The relation to check
+ * @returns True if the relation has a numeric weight
+ *
+ * @example
+ * ```typescript
+ * const rel: Relation = { from: 'A', to: 'B', relationType: 'knows', weight: 0.5 };
+ * if (isWeightedRelation(rel)) {
+ *   console.log(rel.weight); // TypeScript knows weight is number
+ * }
+ * ```
+ */
+declare function isWeightedRelation(relation: Relation): relation is WeightedRelation;
+/**
+ * Type guard to check if a relation has temporal validity.
+ *
+ * @param relation - The relation to check
+ * @returns True if the relation has a validFrom property
+ *
+ * @example
+ * ```typescript
+ * if (isTemporalRelation(rel)) {
+ *   console.log(`Valid from: ${rel.properties.validFrom}`);
+ * }
+ * ```
+ */
+declare function isTemporalRelation(relation: Relation): relation is TemporalRelation;
+/**
+ * Type guard to check if a relation is bidirectional.
+ *
+ * @param relation - The relation to check
+ * @returns True if the relation is marked as bidirectional
+ *
+ * @example
+ * ```typescript
+ * if (isBidirectionalRelation(rel)) {
+ *   // This relation implies the reverse relation exists
+ * }
+ * ```
+ */
+declare function isBidirectionalRelation(relation: Relation): relation is BidirectionalRelation;
+/**
+ * Check if a relation has a confidence score.
+ *
+ * @param relation - The relation to check
+ * @returns True if the relation has a confidence score
+ */
+declare function hasConfidence(relation: Relation): boolean;
+/**
+ * Check if a relation is currently valid based on temporal properties.
+ *
+ * @param relation - The relation to check
+ * @param referenceDate - Date to check against (default: now)
+ * @returns True if the relation is valid at the reference date
+ */
+declare function isCurrentlyValid(relation: Relation, referenceDate?: Date): boolean;
+/**
+ * Fluent builder for constructing relations.
+ *
+ * Provides a convenient way to build relations with validation.
+ *
+ * @example
+ * ```typescript
+ * const relation = new RelationBuilder('Alice', 'Bob', 'knows')
+ *   .withWeight(0.8)
+ *   .withConfidence(0.95)
+ *   .bidirectional()
+ *   .validFrom('2024-01-01')
+ *   .build();
+ * ```
+ */
+declare class RelationBuilder {
+    private relation;
+    /**
+     * Create a new RelationBuilder.
+     *
+     * @param from - Source entity name
+     * @param to - Target entity name
+     * @param relationType - Type of relationship
+     */
+    constructor(from: string, to: string, relationType: string);
+    /**
+     * Set the weight for this relation.
+     *
+     * @param weight - Weight value (must be between 0 and 1)
+     * @throws Error if weight is out of range
+     */
+    withWeight(weight: number): this;
+    /**
+     * Set the confidence score for this relation.
+     *
+     * @param confidence - Confidence value (must be between 0 and 1)
+     * @throws Error if confidence is out of range
+     */
+    withConfidence(confidence: number): this;
+    /**
+     * Mark this relation as bidirectional.
+     *
+     * @param value - Whether the relation is bidirectional (default: true)
+     */
+    bidirectional(value?: boolean): this;
+    /**
+     * Set when this relation becomes valid.
+     *
+     * @param date - ISO 8601 date string
+     */
+    validFrom(date: string): this;
+    /**
+     * Set when this relation stops being valid.
+     *
+     * @param date - ISO 8601 date string
+     */
+    validUntil(date: string): this;
+    /**
+     * Set the source/provenance of this relation.
+     *
+     * @param source - Source identifier
+     */
+    withSource(source: string): this;
+    /**
+     * Set how this relation was established.
+     *
+     * @param method - Establishment method
+     */
+    withMethod(method: RelationProperties['method']): this;
+    /**
+     * Add arbitrary metadata to the relation.
+     *
+     * @param metadata - Key-value pairs to add
+     */
+    withMetadata(metadata: Record<string, unknown>): this;
+    /**
+     * Build the final relation object.
+     *
+     * Automatically sets createdAt timestamp if not already set.
+     *
+     * @returns The constructed relation
+     */
+    build(): Relation;
+}
+
+/**
+ * Relation Validation Utilities
+ *
+ * Functions for validating relation properties.
+ *
+ * @module utils/relationValidation
+ */
+
+/**
+ * A validation error for relation fields.
+ * Named distinctly from ValidationIssue in types.ts which is for graph validation.
+ */
+interface RelationValidationError {
+    /** Field that has the error */
+    field: string;
+    /** Error message */
+    message: string;
+    /** The invalid value (if applicable) */
+    value?: unknown;
+}
+/**
+ * A validation warning for relation fields.
+ * Warnings don't make a relation invalid, but may indicate potential issues.
+ */
+interface RelationValidationWarning {
+    /** Field that has the warning */
+    field: string;
+    /** Warning message */
+    message: string;
+    /** Suggested fix (if applicable) */
+    suggestion?: string;
+}
+/**
+ * Result of relation validation.
+ */
+interface RelationValidationResult {
+    /** Whether the relation is valid (no errors) */
+    isValid: boolean;
+    /** List of validation errors */
+    errors: RelationValidationError[];
+    /** List of validation warnings */
+    warnings: RelationValidationWarning[];
+}
+/**
+ * Validate relation properties.
+ *
+ * Checks:
+ * - Required fields (from, to, relationType)
+ * - Weight range (0-1) if present
+ * - Confidence range (0-1) if present
+ * - Temporal consistency (validFrom <= validUntil) if both present
+ * - Self-referential relations (warning)
+ *
+ * @param relation - The relation to validate
+ * @returns Validation result with errors and warnings
+ *
+ * @example
+ * ```typescript
+ * const result = validateRelationMetadata({
+ *   from: 'Alice',
+ *   to: 'Bob',
+ *   relationType: 'knows',
+ *   weight: 1.5, // Invalid - out of range
+ * });
+ *
+ * if (!result.isValid) {
+ *   console.log('Errors:', result.errors);
+ * }
+ * ```
+ */
+declare function validateRelationMetadata(relation: Relation): RelationValidationResult;
+/**
+ * Validate multiple relations at once.
+ *
+ * @param relations - Array of relations to validate
+ * @returns Array of validation results (same order as input)
+ */
+declare function validateRelationsMetadata(relations: Relation[]): RelationValidationResult[];
+/**
+ * Check if all relations are valid.
+ *
+ * @param relations - Array of relations to check
+ * @returns True if all relations are valid
+ */
+declare function allRelationsValidMetadata(relations: Relation[]): boolean;
+
+/**
+ * Entity Validator
+ *
+ * Validates entities against configurable rules.
+ * Types are embedded to avoid collision with ValidationIssue in types.ts
+ * Phase 1 Sprint 9: Entity Validation Helpers.
+ *
+ * @module utils/EntityValidator
+ */
+
+/**
+ * A validation rule for entities.
+ */
+interface EntityValidationRule {
+    /** Name of this rule for identification */
+    name: string;
+    /** Field path to validate (e.g., 'name', 'observations.0') */
+    field: string;
+    /** Validation function */
+    validate: (entity: Entity) => EntityRuleResult | Promise<EntityRuleResult>;
+    /** Error message if validation fails */
+    message: string;
+    /** Severity level */
+    severity?: 'error' | 'warning';
+}
+/**
+ * Result of a single rule validation.
+ */
+interface EntityRuleResult {
+    /** Whether validation passed */
+    valid: boolean;
+    /** Optional custom message override */
+    message?: string;
+}
+/**
+ * A validation issue found during entity validation.
+ * Named distinctly from ValidationIssue in types.ts (which is for graph validation).
+ */
+interface EntityValidationIssue {
+    /** Field that failed validation */
+    field: string;
+    /** Error/warning message */
+    message: string;
+    /** Severity level */
+    severity: 'error' | 'warning';
+    /** Current value of the field */
+    value?: unknown;
+    /** Name of the rule that failed */
+    rule?: string;
+    /** Suggestion for fixing the issue */
+    suggestion?: string;
+}
+/**
+ * Complete validation result for an entity.
+ */
+interface EntityValidationResult {
+    /** Whether entity is valid */
+    isValid: boolean;
+    /** Validation errors */
+    errors: EntityValidationIssue[];
+    /** Validation warnings */
+    warnings: EntityValidationIssue[];
+    /** The entity that was validated */
+    entity: Entity;
+}
+interface EntityValidatorConfig {
+    /** Rules to apply */
+    rules?: EntityValidationRule[];
+    /** Stop on first error */
+    failFast?: boolean;
+    /** Treat warnings as errors */
+    strict?: boolean;
+}
+/**
+ * Validates entities against configurable rules.
+ *
+ * @example
+ * ```typescript
+ * import { EntityValidator, required, minLength, pattern } from './EntityValidator.js';
+ *
+ * const validator = new EntityValidator({
+ *   rules: [
+ *     required('name'),
+ *     minLength('name', 3),
+ *     pattern('name', /^[a-zA-Z]/),
+ *   ],
+ * });
+ *
+ * const result = await validator.validate(entity);
+ * if (!result.isValid) {
+ *   console.error(result.errors);
+ * }
+ * ```
+ */
+declare class EntityValidator {
+    private readonly config;
+    constructor(config?: EntityValidatorConfig);
+    /**
+     * Add a validation rule.
+     */
+    addRule(rule: EntityValidationRule): this;
+    /**
+     * Add multiple validation rules.
+     */
+    addRules(rules: EntityValidationRule[]): this;
+    /**
+     * Get all registered rules.
+     */
+    getRules(): EntityValidationRule[];
+    /**
+     * Clear all rules.
+     */
+    clearRules(): this;
+    /**
+     * Validate an entity against all rules.
+     */
+    validate(entity: Entity): Promise<EntityValidationResult>;
+    /**
+     * Validate multiple entities.
+     */
+    validateAll(entities: Entity[]): Promise<Map<string, EntityValidationResult>>;
+    /**
+     * Validate an entity synchronously (only works if all rules are sync).
+     */
+    validateSync(entity: Entity): EntityValidationResult;
+    /**
+     * Get a field value from entity using dot notation path.
+     */
+    private getFieldValue;
+}
+
+/**
+ * Built-in Validators
+ *
+ * Factory functions for common validation rules.
+ * Phase 1 Sprint 9: Entity Validation Helpers.
+ *
+ * @module utils/validators
+ */
+
+/**
+ * Require a field to have a value.
+ */
+declare function required(field: string, message?: string): EntityValidationRule;
+/**
+ * Require a string field to have minimum length.
+ */
+declare function minLength(field: string, min: number, message?: string): EntityValidationRule;
+/**
+ * Require a string field to have maximum length.
+ */
+declare function maxLength(field: string, max: number, message?: string): EntityValidationRule;
+/**
+ * Require a string field to match a pattern.
+ */
+declare function pattern(field: string, regex: RegExp, description?: string, message?: string): EntityValidationRule;
+/**
+ * Require a numeric field to be within range.
+ */
+declare function range(field: string, min: number, max: number, message?: string): EntityValidationRule;
+/**
+ * Require a numeric field to be at least a minimum value.
+ */
+declare function min(field: string, minValue: number, message?: string): EntityValidationRule;
+/**
+ * Require a numeric field to be at most a maximum value.
+ */
+declare function max(field: string, maxValue: number, message?: string): EntityValidationRule;
+/**
+ * Require a field to be one of specified values.
+ */
+declare function oneOf<T>(field: string, values: T[], message?: string): EntityValidationRule;
+/**
+ * Require array field to have minimum items.
+ */
+declare function minItems(field: string, minCount: number, message?: string): EntityValidationRule;
+/**
+ * Require array field to have maximum items.
+ */
+declare function maxItems(field: string, maxCount: number, message?: string): EntityValidationRule;
+/**
+ * Require a field to be a valid email address.
+ */
+declare function email(field: string, message?: string): EntityValidationRule;
+/**
+ * Require a field to be a valid URL.
+ */
+declare function url(field: string, message?: string): EntityValidationRule;
+/**
+ * Require a field to be a valid ISO 8601 date string.
+ */
+declare function isoDate(field: string, message?: string): EntityValidationRule;
+/**
+ * Require a field to be of a specific type.
+ */
+declare function typeOf(field: string, expectedType: 'string' | 'number' | 'boolean' | 'object' | 'array', message?: string): EntityValidationRule;
+/**
+ * Custom validator with user-provided function.
  */
+declare function custom(field: string, validator: (value: unknown, entity: Entity) => boolean | Promise<boolean>, message: string): EntityValidationRule;
 /**
- * Memory usage for a single component.
+ * Synchronous custom validator.
  */
-interface ComponentMemoryUsage {
-    /** Component name */
-    name: string;
-    /** Estimated memory usage in bytes */
-    bytes: number;
-    /** Item count (if applicable) */
-    itemCount?: number;
-    /** Average bytes per item */
-    bytesPerItem?: number;
-}
+declare function customSync(field: string, validator: (value: unknown, entity: Entity) => boolean, message: string): EntityValidationRule;
 /**
- * Aggregate memory usage statistics.
+ * Create a warning (non-blocking) version of a rule.
  */
-interface MemoryUsageStats {
-    /** Total memory usage in bytes */
-    totalBytes: number;
-    /** Formatted total memory */
-    totalFormatted: string;
-    /** Per-component breakdown */
-    components: ComponentMemoryUsage[];
-    /** Timestamp of measurement */
-    timestamp: Date;
-    /** Node.js heap stats (if available) */
-    heapStats?: {
-        heapUsed: number;
-        heapTotal: number;
-        external: number;
-        rss: number;
-    };
-}
+declare function asWarning(rule: EntityValidationRule): EntityValidationRule;
 /**
- * Memory threshold configuration.
+ * Combine multiple rules for the same field.
  */
-interface MemoryThresholds {
-    /** Warning threshold in bytes */
-    warning: number;
-    /** Critical threshold in bytes */
-    critical: number;
-}
+declare function all(...rules: EntityValidationRule[]): EntityValidationRule[];
 /**
- * Memory alert.
+ * Conditionally apply a rule based on a predicate.
  */
-interface MemoryAlert {
-    /** Alert level */
-    level: 'warning' | 'critical';
-    /** Component that triggered the alert */
-    component: string;
-    /** Current usage */
-    currentBytes: number;
-    /** Threshold exceeded */
-    threshold: number;
-    /** Message */
-    message: string;
-}
+declare function when(predicate: (entity: Entity) => boolean, rule: EntityValidationRule): EntityValidationRule;
+
 /**
- * Callback for memory change events.
+ * Schema Validator
+ *
+ * JSON Schema validation for entities using ajv.
+ * Phase 1 Sprint 9: Entity Validation Helpers.
+ *
+ * @module utils/SchemaValidator
  */
-type MemoryChangeCallback = (usage: MemoryUsageStats) => void;
+
 /**
- * Memory Monitor for tracking usage across components.
+ * JSON Schema type definition (simplified).
+ */
+interface JsonSchema {
+    type?: string | string[];
+    properties?: Record<string, JsonSchema>;
+    required?: string[];
+    additionalProperties?: boolean;
+    minLength?: number;
+    maxLength?: number;
+    minimum?: number;
+    maximum?: number;
+    pattern?: string;
+    enum?: unknown[];
+    items?: JsonSchema;
+    minItems?: number;
+    maxItems?: number;
+    format?: string;
+    default?: unknown;
+    description?: string;
+    $ref?: string;
+    allOf?: JsonSchema[];
+    anyOf?: JsonSchema[];
+    oneOf?: JsonSchema[];
+    not?: JsonSchema;
+    if?: JsonSchema;
+    then?: JsonSchema;
+    else?: JsonSchema;
+    [key: string]: unknown;
+}
+/**
+ * Validates entities against JSON Schemas.
+ * Requires ajv to be installed as optional peer dependency.
  *
  * @example
  * ```typescript
- * const monitor = new MemoryMonitor();
- *
- * // Register components
- * monitor.registerComponent('entities', () => entities.length * 500);
- * monitor.registerComponent('vectors', () => vectors.size * dimension * 4);
- *
- * // Get usage stats
- * const stats = monitor.getUsage();
- * console.log(`Total memory: ${stats.totalFormatted}`);
+ * const validator = new SchemaValidator();
+ * await validator.initialize(); // Load ajv dynamically
+ *
+ * validator.registerSchema('person', {
+ *   type: 'object',
+ *   required: ['name', 'entityType'],
+ *   properties: {
+ *     name: { type: 'string', minLength: 1 },
+ *     entityType: { type: 'string', enum: ['person'] },
+ *   },
+ * });
  *
- * // Check for alerts
- * const alerts = monitor.checkThresholds();
+ * const result = validator.validate(entity);
  * ```
  */
-declare class MemoryMonitor {
-    private componentEstimators;
-    private itemCounters;
-    private thresholds;
-    private listeners;
-    private lastUsage;
-    constructor(thresholds?: Partial<MemoryThresholds>);
+declare class SchemaValidator {
+    private schemas;
+    private ajv;
+    private validators;
+    private initialized;
     /**
-     * Register a component for memory tracking.
-     *
-     * @param name - Component name
-     * @param estimator - Function that returns estimated bytes
-     * @param itemCounter - Optional function that returns item count
+     * Initialize the validator by loading ajv dynamically.
+     * Call this before using validate() if you want schema validation.
      */
-    registerComponent(name: string, estimator: () => number, itemCounter?: () => number): void;
+    initialize(): Promise<boolean>;
     /**
-     * Unregister a component.
-     *
-     * @param name - Component name
+     * Check if schema validation is available.
      */
-    unregisterComponent(name: string): void;
+    isAvailable(): boolean;
     /**
-     * Get current memory usage statistics.
+     * Check if initialized.
      */
-    getUsage(): MemoryUsageStats;
+    isInitialized(): boolean;
     /**
-     * Get memory usage for a specific component.
-     *
-     * @param name - Component name
+     * Register a schema for an entity type.
      */
-    getComponentUsage(name: string): ComponentMemoryUsage | undefined;
+    registerSchema(entityType: string, schema: JsonSchema): void;
     /**
-     * Check memory thresholds and return alerts.
+     * Compile a schema using ajv.
      */
-    checkThresholds(): MemoryAlert[];
+    private compileSchema;
     /**
-     * Set memory thresholds.
-     *
-     * @param thresholds - New threshold values
+     * Unregister a schema.
      */
-    setThresholds(thresholds: Partial<MemoryThresholds>): void;
+    unregisterSchema(entityType: string): void;
     /**
-     * Get current thresholds.
+     * Validate an entity against its type's schema.
      */
-    getThresholds(): MemoryThresholds;
+    validate(entity: Entity): EntityValidationResult;
     /**
-     * Add a listener for memory changes.
-     *
-     * @param callback - Callback to invoke on memory changes
+     * Validate multiple entities.
      */
-    addListener(callback: MemoryChangeCallback): void;
+    validateAll(entities: Entity[]): Map<string, EntityValidationResult>;
     /**
-     * Remove a listener.
-     *
-     * @param callback - Callback to remove
+     * Get field path from AJV error.
      */
-    removeListener(callback: MemoryChangeCallback): void;
+    private getFieldPath;
     /**
-     * Get a human-readable summary of memory usage.
+     * Get human-readable error message.
      */
-    getSummary(): string;
+    private getErrorMessage;
     /**
-     * Get the last recorded usage without triggering a new measurement.
+     * Get suggestion for fixing the error.
      */
-    getLastUsage(): MemoryUsageStats | null;
+    private getSuggestion;
     /**
-     * Format bytes as human-readable string.
-     *
-     * @param bytes - Number of bytes
+     * Get registered schema for entity type.
      */
-    formatBytes(bytes: number): string;
+    getSchema(entityType: string): JsonSchema | undefined;
     /**
-     * Parse a formatted byte string back to number.
-     *
-     * @param formatted - Formatted string like "10 MB"
+     * Get all registered entity types.
      */
-    parseBytes(formatted: string): number;
+    getRegisteredTypes(): string[];
     /**
-     * Clear all registered components.
+     * Check if a schema is registered for an entity type.
      */
-    clear(): void;
-    private notifyListeners;
+    hasSchema(entityType: string): boolean;
 }
-/**
- * Singleton instance for global memory monitoring.
- */
-declare const globalMemoryMonitor: MemoryMonitor;
 
 /**
  * Transaction Manager
@@ -7297,6 +8310,11 @@ declare class SQLiteStorage implements IGraphStorage {
      * Create database tables, indexes, and FTS5 virtual table.
      */
     private createTables;
+    /**
+     * Phase 1 Sprint 5: Migrate relations table to add metadata columns.
+     * Checks if columns exist and adds them if not for backward compatibility.
+     */
+    private migrateRelationsTable;
     /**
      * Load all data from SQLite into memory cache.
      */
@@ -7307,6 +8325,7 @@ declare class SQLiteStorage implements IGraphStorage {
     private rowToEntity;
     /**
      * Convert a database row to a Relation object.
+     * Phase 1 Sprint 5: Includes metadata fields.
      */
     private rowToRelation;
     /**
@@ -12479,6 +13498,244 @@ declare class QuantizedVectorStore {
     private computeError;
 }
 
+/**
+ * Query Logger
+ *
+ * Provides structured logging for search operations.
+ * Supports console, file, and callback outputs.
+ * Phase 1 Sprint 6: Query Logging and Tracing.
+ *
+ * @module search/QueryLogger
+ */
+
+/**
+ * Configuration for QueryLogger.
+ */
+interface QueryLoggerConfig {
+    /** Minimum log level to output */
+    level?: LogLevel;
+    /** Log to console */
+    console?: boolean;
+    /** Log to file path */
+    filePath?: string;
+    /** Custom callback for log entries */
+    callback?: (entry: QueryLogEntry) => void;
+    /** Include timestamps in console output */
+    timestamps?: boolean;
+}
+/**
+ * Query logger for search operations.
+ *
+ * @example
+ * ```typescript
+ * const logger = new QueryLogger({ level: 'debug', console: true });
+ * logger.logQueryStart('q123', 'hello world', 'ranked');
+ * // ... search executes ...
+ * logger.logQueryEnd('q123', 150, 10);
+ * ```
+ */
+declare class QueryLogger {
+    private readonly config;
+    constructor(config?: QueryLoggerConfig);
+    /**
+     * Check if logging is enabled (any output configured).
+     */
+    isEnabled(): boolean;
+    /**
+     * Log the start of a query.
+     */
+    logQueryStart(queryId: string, queryText: string, queryType: string): void;
+    /**
+     * Log the end of a query.
+     */
+    logQueryEnd(queryId: string, durationMs: number, resultCount: number): void;
+    /**
+     * Log a query stage.
+     */
+    logStage(queryId: string, stage: string, durationMs: number, metadata?: Record<string, unknown>): void;
+    /**
+     * Log a debug message.
+     */
+    debug(queryId: string, message: string, metadata?: Record<string, unknown>): void;
+    /**
+     * Log an info message.
+     */
+    info(queryId: string, message: string, metadata?: Record<string, unknown>): void;
+    /**
+     * Log a warning.
+     */
+    warn(queryId: string, message: string, metadata?: Record<string, unknown>): void;
+    /**
+     * Log an error.
+     */
+    error(queryId: string, message: string, error?: Error): void;
+    private log;
+    /**
+     * Format data for console output (remove undefined values).
+     */
+    private formatConsoleData;
+    /**
+     * Generate a unique query ID.
+     */
+    static generateQueryId(): string;
+}
+
+/**
+ * Query Parser
+ *
+ * Parses search query strings into structured query objects.
+ * Supports: phrases ("..."), wildcards (*?), proximity (~N), fields (field:).
+ * Phase 1 Sprint 8: Full-Text Search Operators.
+ *
+ * @module search/QueryParser
+ */
+
+/**
+ * Query parser for advanced search syntax.
+ *
+ * @example
+ * ```typescript
+ * const parser = new QueryParser();
+ *
+ * // Phrase search
+ * parser.parse('"machine learning"');
+ *
+ * // Wildcard search
+ * parser.parse('data*');
+ *
+ * // Proximity search
+ * parser.parse('"machine learning"~3');
+ *
+ * // Field-specific search
+ * parser.parse('name:Alice');
+ *
+ * // Combined
+ * parser.parse('name:"John Doe" AND type:person');
+ * ```
+ */
+declare class QueryParser {
+    /**
+     * Parse a query string into a QueryNode tree.
+     */
+    parse(query: string): QueryNode;
+    /**
+     * Check if a query uses advanced operators.
+     */
+    hasAdvancedOperators(query: string): boolean;
+    /**
+     * Parse boolean expressions (AND, OR, NOT).
+     */
+    private parseBooleanExpression;
+    /**
+     * Split query by operator, respecting quotes.
+     */
+    private splitByOperator;
+    /**
+     * Tokenize query string, handling quotes.
+     */
+    private tokenize;
+    /**
+     * Parse tokenized query.
+     */
+    private parseTokens;
+    /**
+     * Parse a single token into a QueryNode.
+     */
+    private parseToken;
+    /**
+     * Convert wildcard pattern to regex.
+     */
+    private wildcardToRegex;
+}
+/**
+ * Check if text contains the phrase (terms in order).
+ */
+declare function matchesPhrase(text: string, terms: string[]): boolean;
+/**
+ * Check if pattern is a simple prefix (e.g., 'foo*').
+ */
+declare function isPrefixPattern(pattern: string): boolean;
+/**
+ * Match text against prefix pattern.
+ */
+declare function matchesPrefix(text: string, pattern: string): boolean;
+
+/**
+ * Proximity Search
+ *
+ * Finds entities where terms appear within a specified distance.
+ * Phase 1 Sprint 8: Full-Text Search Operators.
+ *
+ * @module search/ProximitySearch
+ */
+
+/**
+ * Result of a proximity match.
+ */
+interface ProximityMatch {
+    /** The matched entity */
+    entity: Entity;
+    /** Score based on proximity (closer = higher) */
+    score: number;
+    /** Minimum distance found between terms */
+    minDistance: number;
+    /** Detailed match locations */
+    matches: ProximityMatchLocation[];
+}
+/**
+ * Location where proximity match was found.
+ */
+interface ProximityMatchLocation {
+    /** Field where match was found */
+    field: string;
+    /** Term positions in the text */
+    positions: Map<string, number[]>;
+    /** Distance between terms */
+    distance: number;
+}
+/**
+ * Proximity search implementation.
+ *
+ * @example
+ * ```typescript
+ * const search = new ProximitySearch();
+ *
+ * // Find entities where "machine" and "learning" appear within 3 words
+ * const results = search.search(entities, {
+ *   type: 'proximity',
+ *   terms: ['machine', 'learning'],
+ *   distance: 3
+ * });
+ * ```
+ */
+declare class ProximitySearch {
+    /**
+     * Search for entities where terms appear within distance.
+     */
+    search(entities: Entity[], node: ProximityNode): ProximityMatch[];
+    /**
+     * Check if entity matches the proximity query.
+     */
+    private matchEntity;
+    /**
+     * Find minimum distance between all terms in text.
+     * Returns null if any term is not found.
+     */
+    private findProximity;
+    /**
+     * Find minimum span containing all terms.
+     */
+    private findMinSpan;
+    /**
+     * Get positions of all terms in text.
+     */
+    private getPositions;
+    /**
+     * Calculate proximity score between two specific terms.
+     */
+    static calculateProximityScore(text: string, term1: string, term2: string, maxDistance: number): number | null;
+}
+
 /**
  * IO Manager
  *
@@ -16966,4 +18223,4 @@ declare class KeywordExtractor {
     getDomainBoosts(): Map<string, number>;
 }
 
-export { type AccessContext, AccessContextBuilder, type AccessPattern, type AdaptiveDepthConfig, type AddObservationInput, AddObservationInputSchema, AddObservationsInputSchema, type AdequacyCheck, type AgentEntity, type AgentObservation, AnalyticsManager, type ArchiveCriteria, type ArchiveCriteriaInput, ArchiveCriteriaSchema, ArchiveManager, type ArchiveOptions, type ArchiveResult, type ArchiveResultExtended, type AutoSearchResult, type BM25Config, type BM25DocumentEntry, type BM25Index, BM25Search, type BackupInfo, type BackupInfoExtended, type BackupMetadata, type BackupMetadataExtended, type BackupOptions, type BackupResult, BasicSearch, BatchCreateEntitiesSchema, BatchCreateRelationsSchema, type BatchItemResult, type BatchOperation, type BatchOperationType, type BatchOptions, type BatchProcessResult, BatchProcessor, type BatchProcessorOptions, type BatchProgress, type BatchProgressCallback, type BatchResult, BatchTransaction, type BooleanCacheEntry, type BooleanQueryNode, BooleanSearch, COMPRESSION_CONFIG, type CacheCompressionStats, type CacheStats, type CachedQueryEntry, type CentralityResult, type CommonSearchFilters, type ComponentMemoryUsage, CompressedCache, type CompressedCacheOptions, type CompressedCacheStats, CompressionManager, type CompressionMetadata, type CompressionOptions, type CompressionQuality, type CompressionResult, type ConnectedComponentsResult, type ConsolidateOptions, type ConsolidationAction, type ConsolidationResult, type ConsolidationRule, type ConsolidationTrigger, type ContextPackage, type ContextRetrievalOptions, type CreateEntityInput, CreateEntitySchema, type CreateRelationInput, CreateRelationSchema, CycleDetectedError, DEFAULT_BASE_DIR, DEFAULT_BM25_CONFIG, DEFAULT_DUPLICATE_THRESHOLD, DEFAULT_EMBEDDING_CACHE_OPTIONS, DEFAULT_FILE_NAMES, DEFAULT_HYBRID_WEIGHTS, DEFAULT_INDEXER_OPTIONS, DEFAULT_SCORER_WEIGHTS, DOCUMENT_PREFIX, type DateRange, DateRangeSchema, type DecayOptions, type DecayResult, type DeleteObservationInput, DeleteObservationInputSchema, DeleteObservationsInputSchema, DeleteRelationsSchema, type DocumentVector, DuplicateEntityError, type DuplicatePair, ENV_VARS, EarlyTerminationManager, type EarlyTerminationOptions, type EarlyTerminationResult, EmbeddingCache, type EmbeddingCacheOptions, type EmbeddingCacheStats, type EmbeddingConfig, type EmbeddingMode, type EmbeddingProgressCallback, type EmbeddingService, type Entity, type EntityCreatedEvent, type EntityDeletedEvent, type EntityInput, EntityManager, EntityNamesSchema, EntityNotFoundError, EntitySchema, type EntityUpdatedEvent, type EpisodicMemoryEntity, type ExcludedEntity, ExportError, type ExportFilter, type ExportFilterInput, ExportFilterSchema, type ExportFormat, ExportFormatSchema, type ExportOptions, type ExportResult, type ExtendedExportFormatInput, ExtendedExportFormatSchema, type ExtendedPoolStats, type ExtendedQueryCostEstimate, type ExtractedEntity, FILE_EXTENSIONS, FILE_SUFFIXES, FileOperationError, type FlushResult, type ForgetOptions, type ForgetResult, type FuzzyCacheKey, FuzzySearch, type FuzzySearchOptions, GRAPH_LIMITS, type GraphCompressionResult, type GraphEvent, type GraphEventBase, GraphEventEmitter, type GraphEventListener, type GraphEventMap, type GraphEventType, type GraphLoadedEvent, type GraphSavedEvent, type GraphStats, GraphStorage, GraphTraversal, HierarchyManager, HybridScorer, type HybridScorerOptions, HybridSearchManager, type HybridSearchOptions, type HybridSearchResult, type HybridWeights, type IGraphStorage, IMPORTANCE_RANGE, IOManager, type IVectorStore, ImportError, type ImportFormat, type ImportFormatInput, ImportFormatSchema, type ImportResult, InMemoryVectorStore, IncrementalIndexer, type IncrementalIndexerOptions, type IndexMemoryUsage, type IndexOperation, type IndexOperationType, InsufficientEntitiesError, InvalidImportanceError, KeywordExtractor, type KnowledgeGraph, KnowledgeGraphError, ManagerContext as KnowledgeGraphManager, LOG_PREFIXES, type LayerRecommendationOptions, type LayerTiming, type LexicalSearchResult, LocalEmbeddingService, type LongRunningOperationOptions, LowercaseCache, type LowercaseData, ManagerContext, type MemoryAcquisitionMethod, type MemoryAlert, type MemoryChangeCallback, type MemoryMergeStrategy, MemoryMonitor, type MemorySource, type MemoryThresholds, type MemoryType, type MemoryUsageStats, type MemoryVisibility, type MergeResult, type MergeStrategy, type MergeStrategyInput, MergeStrategySchema, MockEmbeddingService, NameIndex, type NormalizationOptions, type NormalizationResult, type ObservationAddedEvent, type ObservationDeletedEvent, ObservationManager, ObservationNormalizer, type ObservationSource, OpenAIEmbeddingService, OperationCancelledError, OperationType, OptimizedInvertedIndex, OptionalEntityNamesSchema, OptionalTagsSchema, type PaginatedCacheEntry, ParallelSearchExecutor, type ParallelSearchOptions, type ParallelSearchResult, type PathResult, type PatternResult, type PhaseDefinition, type PoolEventCallback, type PostingListResult, type PreparedEntity, type ProceduralMemoryEntity, type ProgressCallback, QUERY_LIMITS, QUERY_PREFIX, type QuantizationParams, type QuantizedSearchResult, QuantizedVectorStore, type QuantizedVectorStoreOptions, type QuantizedVectorStoreStats, type QueryAnalysis, QueryAnalyzer, type QueryCostEstimate, QueryCostEstimator, type QueryCostEstimatorOptions, type QueryPlan, QueryPlanCache, type QueryPlanCacheOptions, type QueryPlanCacheStats, QueryPlanner, type QueueStats, RankedSearch, type ReadonlyKnowledgeGraph, type RefinementHistoryEntry, ReflectionManager, type ReflectionOptions, type ReflectionResult, type Relation, type RelationCreatedEvent, type RelationDeletedEvent, RelationIndex, type RelationInput, RelationManager, RelationNotFoundError, RelationSchema, type RestoreResult, type RuleConditions, type RuleEvaluationResult, SEARCH_LIMITS, SIMILARITY_WEIGHTS, SQLiteStorage, type SQLiteStorageWithEmbeddings, SQLiteVectorStore, STOPWORDS, STREAMING_CONFIG, type SalienceComponents, type SalienceContext, type SalienceWeights, type SavedSearch, type SavedSearchInput, SavedSearchInputSchema, SavedSearchManager, type SavedSearchUpdateInput, SavedSearchUpdateSchema, type ScoredEntity, type ScoredKeyword, type ScoredResult, SearchCache, SearchFilterChain, type SearchFilters, type SearchLayer, SearchManager, type SearchMethod, type SearchQuery, SearchQuerySchema, type SearchResult, SearchSuggestions, type SemanticIndexOptions, type SemanticLayerResult, type SemanticMemoryEntity, SemanticSearch, type SemanticSearchResult, type SessionEntity, type SessionStatus, type StorageConfig, type StreamResult, StreamingExporter, type SubQuery, type SummarizationResult, type SymbolicFilters, type SymbolicResult, SymbolicSearch, type SymbolicSearchResult, TFIDFEventSync, type TFIDFIndex, TFIDFIndexManager, type TagAlias, type TagAliasInput, TagAliasSchema, TagManager, type Task, type TaskBatchOptions, TaskPriority, TaskQueue, type TaskResult, TaskStatus, type TemporalFocus, type TemporalRange, type TokenBreakdown, type TokenEstimationOptions, type TokenizedEntity, type ToolResponse, TransactionManager, type TransactionOperation, type TransactionResult, type TraversalOptions, type TraversalResult, TypeIndex, type UpdateEntityInput, UpdateEntitySchema, type ValidatedPagination, ValidationError, type ValidationIssue, type ValidationReport, type ValidationResult, type ValidationWarning, type VectorSearchResult, type WeightedRelation, type WorkerPoolConfig, WorkerPoolManager, type WorkingMemoryEntity, type WorkingMemoryOptions, addUniqueTags, applyPagination, batchProcess, calculateIDF, calculateIDFFromTokenSets, calculateTF, calculateTFIDF, checkCancellation, chunkArray, cleanupAllCaches, clearAllSearchCaches, compress, compressFile, compressToBase64, cosineSimilarity, createEmbeddingService, createMetadata, createProgress, createProgressReporter, createStorage, createStorageFromPath, createUncompressedMetadata, createVectorStore, debounce, decompress, decompressFile, decompressFromBase64, defaultMemoryPath, ensureMemoryFilePath, entityExists, entityPassesFilters, entityToText, escapeCsvFormula, executeWithPhases, filterByCreatedDate, filterByEntityType, filterByImportance, filterByModifiedDate, filterByTags, filterParallel, findEntitiesByNames, findEntityByName, fnv1aHash, formatErrorResponse, formatRawResponse, formatTextResponse, formatToolResponse, formatZodErrors, getAllCacheStats, getCompressionRatio, getCurrentTimestamp, getEntityIndex, getEntityNameSet, getPaginationMeta, getPoolStats, getWorkerPoolManager, globalMemoryMonitor, groupEntitiesByType, hasAllTags, hasBrotliExtension, hasMatchingTag, isAgentEntity, isEpisodicMemory, isProceduralMemory, isSemanticMemory, isSessionEntity, isValidISODate, isWithinDateRange, isWithinImportanceRange, isWorkingMemory, l2Normalize, levenshteinDistance, logger, mapParallel, normalizeTag, normalizeTags, paginateArray, parallelFilter, parallelLimit, parallelMap, parseDateRange, processBatch, processBatchesWithProgress, processWithRetry, rateLimitedProcess, removeEntityByName, removeTags, sanitizeObject, searchCaches, shutdownParallelUtils, throttle, tokenize, touchEntity, validateArrayWithSchema, validateEntity, validateFilePath, validateImportance, validatePagination, validateRelation, validateSafe, validateTags, validateWithSchema, withRetry };
+export { type AccessContext, AccessContextBuilder, type AccessPattern, type AdaptiveDepthConfig, type AddObservationInput, AddObservationInputSchema, AddObservationsInputSchema, type AdequacyCheck, type AgentEntity, type AgentObservation, AnalyticsManager, type ArchiveCriteria, type ArchiveCriteriaInput, ArchiveCriteriaSchema, ArchiveManager, type ArchiveOptions, type ArchiveResult, type ArchiveResultExtended, type AutoSearchResult, type BM25Config, type BM25DocumentEntry, type BM25Index, BM25Search, type BackupInfo, type BackupInfoExtended, type BackupMetadata, type BackupMetadataExtended, type BackupOptions, type BackupResult, BasicSearch, BatchCreateEntitiesSchema, BatchCreateRelationsSchema, type BatchItemResult, type BatchOperation, type BatchOperationType, type BatchOptions, type BatchProcessResult, BatchProcessor, type BatchProcessorOptions, type BatchProgress, type BatchProgressCallback, type BatchResult, BatchTransaction, type BidirectionalRelation, type BooleanCacheEntry, type BooleanOpNode, type BooleanQueryNode, BooleanSearch, COMPRESSION_CONFIG, type CacheCompressionStats, type CacheStats, type CachedQueryEntry, type CentralityResult, type CommonSearchFilters, type ComponentMemoryUsage, CompressedCache, type CompressedCacheOptions, type CompressedCacheStats, CompressionManager, type CompressionMetadata, type CompressionOptions, type CompressionQuality, type CompressionResult, type ConnectedComponentsResult, type ConsolidateOptions, type ConsolidationAction, type ConsolidationResult, type ConsolidationRule, type ConsolidationTrigger, type ContextPackage, type ContextRetrievalOptions, type CreateEntityInput, CreateEntitySchema, type CreateRelationInput, CreateRelationSchema, CycleDetectedError, DEFAULT_BASE_DIR, DEFAULT_BM25_CONFIG, DEFAULT_DUPLICATE_THRESHOLD, DEFAULT_EMBEDDING_CACHE_OPTIONS, DEFAULT_FILE_NAMES, DEFAULT_HYBRID_WEIGHTS, DEFAULT_INDEXER_OPTIONS, DEFAULT_SCORER_WEIGHTS, DOCUMENT_PREFIX, type DateRange, DateRangeSchema, type DecayOptions, type DecayResult, type DeleteObservationInput, DeleteObservationInputSchema, DeleteObservationsInputSchema, DeleteRelationsSchema, type DocumentVector, DuplicateEntityError, type DuplicatePair, ENV_VARS, EarlyTerminationManager, type EarlyTerminationOptions, type EarlyTerminationResult, EmbeddingCache, type EmbeddingCacheOptions, type EmbeddingCacheStats, type EmbeddingConfig, type EmbeddingMode, type EmbeddingProgressCallback, type EmbeddingService, type Entity, type EntityCreatedEvent, type EntityDeletedEvent, type EntityInput, EntityManager, EntityNamesSchema, EntityNotFoundError, type EntityRuleResult, EntitySchema, type EntityUpdatedEvent, type EntityValidationIssue, type EntityValidationResult, type EntityValidationRule, EntityValidator, type EntityValidatorConfig, type EpisodicMemoryEntity, ErrorCode, type ErrorOptions, type ExcludedEntity, type ExplainedSearchResult, ExportError, type ExportFilter, type ExportFilterInput, ExportFilterSchema, type ExportFormat, ExportFormatSchema, type ExportOptions, type ExportResult, type ExtendedExportFormatInput, ExtendedExportFormatSchema, type ExtendedPoolStats, type ExtendedQueryCostEstimate, type ExtractedEntity, FILE_EXTENSIONS, FILE_SUFFIXES, type FieldNode, FileOperationError, type FlushResult, type ForgetOptions, type ForgetResult, type FuzzyCacheKey, FuzzySearch, type FuzzySearchOptions, GRAPH_LIMITS, type GraphCompressionResult, type GraphEvent, type GraphEventBase, GraphEventEmitter, type GraphEventListener, type GraphEventMap, type GraphEventType, type GraphLoadedEvent, type GraphSavedEvent, type GraphStats, GraphStorage, GraphTraversal, HierarchyManager, HybridScorer, type HybridScorerOptions, HybridSearchManager, type HybridSearchOptions, type HybridSearchResult, type HybridWeights, type IGraphStorage, IMPORTANCE_RANGE, IOManager, type IVectorStore, ImportError, type ImportFormat, type ImportFormatInput, ImportFormatSchema, type ImportResult, InMemoryVectorStore, IncrementalIndexer, type IncrementalIndexerOptions, type IndexMemoryUsage, type IndexOperation, type IndexOperationType, InsufficientEntitiesError, InvalidImportanceError, type JsonSchema, KeywordExtractor, type KnowledgeGraph, KnowledgeGraphError, ManagerContext as KnowledgeGraphManager, LOG_PREFIXES, type LayerRecommendationOptions, type LayerTiming, type LexicalSearchResult, LocalEmbeddingService, type LogLevel, type LongRunningOperationOptions, LowercaseCache, type LowercaseData, ManagerContext, type MatchedTerm, type MemoryAcquisitionMethod, type MemoryAlert, type MemoryChangeCallback, type MemoryMergeStrategy, MemoryMonitor, type MemorySource, type MemoryThresholds, type MemoryType, type MemoryUsageStats, type MemoryVisibility, type MergeResult, type MergeStrategy, type MergeStrategyInput, MergeStrategySchema, MockEmbeddingService, NameIndex, type NormalizationOptions, type NormalizationResult, type ObservationAddedEvent, type ObservationDeletedEvent, ObservationManager, ObservationNormalizer, type ObservationSource, OpenAIEmbeddingService, OperationCancelledError, OperationType, OptimizedInvertedIndex, OptionalEntityNamesSchema, OptionalTagsSchema, type PaginatedCacheEntry, ParallelSearchExecutor, type ParallelSearchOptions, type ParallelSearchResult, type PathResult, type PatternResult, type PhaseDefinition, type PhraseNode, type PoolEventCallback, type PostingListResult, type PreparedEntity, type ProceduralMemoryEntity, type ProgressCallback, type ProgressInfo, type ProgressInfoCallback, type ProgressOptions, type ProximityMatch, type ProximityMatchLocation, type ProximityNode, ProximitySearch, QUERY_LIMITS, QUERY_PREFIX, type QuantizationParams, type QuantizedSearchResult, QuantizedVectorStore, type QuantizedVectorStoreOptions, type QuantizedVectorStoreStats, type QueryAnalysis, QueryAnalyzer, type QueryCostEstimate, QueryCostEstimator, type QueryCostEstimatorOptions, type QueryLogEntry, QueryLogger, type QueryLoggerConfig, type QueryNode, QueryParser, type QueryPlan, QueryPlanCache, type QueryPlanCacheOptions, type QueryPlanCacheStats, QueryPlanner, type QueryStage, type QueryTrace, QueryTraceBuilder, type QueueStats, RankedSearch, type ReadonlyKnowledgeGraph, type RefinementHistoryEntry, ReflectionManager, type ReflectionOptions, type ReflectionResult, type Relation, RelationBuilder, type RelationCreatedEvent, type RelationDeletedEvent, RelationIndex, type RelationInput, RelationManager, RelationNotFoundError, type RelationProperties, RelationSchema, type RelationValidationError, type RelationValidationResult, type RelationValidationWarning, type RestoreResult, type RuleConditions, type RuleEvaluationResult, SEARCH_LIMITS, SIMILARITY_WEIGHTS, SQLiteStorage, type SQLiteStorageWithEmbeddings, SQLiteVectorStore, STOPWORDS, STREAMING_CONFIG, type SalienceComponents, type SalienceContext, type SalienceWeights, type SavedSearch, type SavedSearchInput, SavedSearchInputSchema, SavedSearchManager, type SavedSearchUpdateInput, SavedSearchUpdateSchema, SchemaValidator, type ScoreBoost, type ScoredEntity, type ScoredKeyword, type ScoredResult, type ScoringSignal, SearchCache, type SearchExplanation, SearchFilterChain, type SearchFilters, type SearchLayer, SearchManager, type SearchMethod, type SearchQuery, SearchQuerySchema, type SearchResult, SearchSuggestions, type SemanticIndexOptions, type SemanticLayerResult, type SemanticMemoryEntity, SemanticSearch, type SemanticSearchResult, type SessionEntity, type SessionStatus, type StorageConfig, type StreamResult, StreamingExporter, type SubQuery, type SummarizationResult, type SymbolicFilters, type SymbolicResult, SymbolicSearch, type SymbolicSearchResult, TFIDFEventSync, type TFIDFIndex, TFIDFIndexManager, type TagAlias, type TagAliasInput, TagAliasSchema, TagManager, type Task, type TaskBatchOptions, TaskPriority, TaskQueue, type TaskResult, TaskStatus, type TemporalFocus, type TemporalRange, type TemporalRelation, type TermNode, type TokenBreakdown, type TokenEstimationOptions, type TokenizedEntity, type ToolResponse, TransactionManager, type TransactionOperation, type TransactionResult, type TraversalOptions, type TraversalResult, TypeIndex, type UpdateEntityInput, UpdateEntitySchema, type ValidatedPagination, ValidationError, type ValidationIssue, type ValidationReport, type ValidationResult, type ValidationWarning, type VectorSearchResult, type WeightedRelation, type WildcardNode, type WorkerPoolConfig, WorkerPoolManager, type WorkingMemoryEntity, type WorkingMemoryOptions, addUniqueTags, all, allRelationsValidMetadata, applyPagination, asWarning, batchProcess, calculateIDF, calculateIDFFromTokenSets, calculateTF, calculateTFIDF, checkCancellation, chunkArray, cleanupAllCaches, clearAllSearchCaches, compress, compressFile, compressToBase64, cosineSimilarity, createDetailedProgressReporter, createEmbeddingService, createMetadata, createProgress, createProgressInfo, createProgressReporter, createStorage, createStorageFromPath, createThrottledProgress, createUncompressedMetadata, createVectorStore, custom, customSync, debounce, decompress, decompressFile, decompressFromBase64, defaultMemoryPath, email, ensureMemoryFilePath, entityExists, entityPassesFilters, entityToText, escapeCsvFormula, executeWithPhases, filterByCreatedDate, filterByEntityType, filterByImportance, filterByModifiedDate, filterByTags, filterParallel, findEntitiesByNames, findEntityByName, fnv1aHash, formatErrorResponse, formatRawResponse, formatTextResponse, formatToolResponse, formatZodErrors, generateSuggestions, getAllCacheStats, getCompressionRatio, getCurrentTimestamp, getEntityIndex, getEntityNameSet, getPaginationMeta, getPoolStats, getQuickHint, getWorkerPoolManager, globalMemoryMonitor, groupEntitiesByType, hasAllTags, hasBrotliExtension, hasConfidence, hasMatchingTag, isAgentEntity, isBidirectionalRelation, isCurrentlyValid, isEpisodicMemory, isPrefixPattern, isProceduralMemory, isSemanticMemory, isSessionEntity, isTemporalRelation, isValidISODate, isWeightedRelation, isWithinDateRange, isWithinImportanceRange, isWorkingMemory, isoDate, l2Normalize, levenshteinDistance, logger, mapParallel, matchesPhrase, matchesPrefix, max, maxItems, maxLength, min, minItems, minLength, normalizeTag, normalizeTags, oneOf, paginateArray, parallelFilter, parallelLimit, parallelMap, parseDateRange, pattern, processBatch, processBatchesWithProgress, processWithRetry, range, rateLimitedProcess, removeEntityByName, removeTags, required, sanitizeObject, searchCaches, shutdownParallelUtils, throttle, tokenize, touchEntity, typeOf, url, validateArrayWithSchema, validateEntity, validateFilePath, validateImportance, validatePagination, validateRelation, validateRelationMetadata, validateRelationsMetadata, validateSafe, validateTags, validateWithSchema, when, withRetry };