@danielsimonjr/memoryjs 1.0.0

package/dist/utils/constants.js

@@ -0,0 +1,253 @@
+/**
+ * Application Constants
+ *
+ * Centralized configuration constants for file paths, extensions, and default values.
+ *
+ * @module utils/constants
+ */
+/**
+ * File extensions used by the memory system.
+ */
+export const FILE_EXTENSIONS = {
+    /** JSONL format for line-delimited JSON storage */
+    JSONL: '.jsonl',
+    /** Legacy JSON format (backward compatibility) */
+    JSON: '.json',
+};
+/**
+ * File name suffixes for auxiliary data files.
+ * These suffixes are appended to the base memory file name.
+ */
+export const FILE_SUFFIXES = {
+    /** Suffix for saved searches file */
+    SAVED_SEARCHES: '-saved-searches',
+    /** Suffix for tag aliases file */
+    TAG_ALIASES: '-tag-aliases',
+};
+/**
+ * Default file names used by the memory system.
+ */
+export const DEFAULT_FILE_NAMES = {
+    /** Default memory file name */
+    MEMORY: 'memory',
+    /** Legacy memory file name (for backward compatibility) */
+    MEMORY_LEGACY: 'memory',
+};
+/**
+ * Environment variable names used for configuration.
+ */
+export const ENV_VARS = {
+    /** Environment variable for custom memory file path */
+    MEMORY_FILE_PATH: 'MEMORY_FILE_PATH',
+};
+/**
+ * Default base directory relative to the compiled code.
+ */
+export const DEFAULT_BASE_DIR = '../';
+/**
+ * Log message prefixes for consistent logging.
+ */
+export const LOG_PREFIXES = {
+    /** Informational message prefix */
+    INFO: '[INFO]',
+    /** Error message prefix */
+    ERROR: '[ERROR]',
+    /** Warning message prefix */
+    WARN: '[WARN]',
+};
+/**
+ * Similarity scoring weights for duplicate detection.
+ * These weights determine the relative importance of each factor
+ * when calculating entity similarity for duplicate detection.
+ * Total weights must sum to 1.0 (100%).
+ */
+export const SIMILARITY_WEIGHTS = {
+    /** Name similarity weight (40%) - Uses Levenshtein distance */
+    NAME: 0.4,
+    /** Entity type match weight (20%) - Exact match required */
+    TYPE: 0.2,
+    /** Observation overlap weight (30%) - Uses Jaccard similarity */
+    OBSERVATIONS: 0.3,
+    /** Tag overlap weight (10%) - Uses Jaccard similarity */
+    TAGS: 0.1,
+};
+/**
+ * Default threshold for duplicate detection (80% similarity required).
+ */
+export const DEFAULT_DUPLICATE_THRESHOLD = 0.8;
+/**
+ * Search result limits to prevent resource exhaustion.
+ */
+export const SEARCH_LIMITS = {
+    /** Default number of results to return */
+    DEFAULT: 50,
+    /** Maximum number of results allowed */
+    MAX: 200,
+    /** Minimum number of results (must be at least 1) */
+    MIN: 1,
+};
+/**
+ * Entity importance range validation constants.
+ * Importance is used to prioritize entities (0 = lowest, 10 = highest).
+ */
+export const IMPORTANCE_RANGE = {
+    /** Minimum importance value */
+    MIN: 0,
+    /** Maximum importance value */
+    MAX: 10,
+};
+/**
+ * Graph size limits to prevent resource exhaustion and ensure performance.
+ * These limits help maintain system stability and responsiveness.
+ */
+export const GRAPH_LIMITS = {
+    /** Maximum number of entities in the graph */
+    MAX_ENTITIES: 100000,
+    /** Maximum number of relations in the graph */
+    MAX_RELATIONS: 1000000,
+    /** Maximum graph file size in megabytes */
+    MAX_FILE_SIZE_MB: 500,
+    /** Maximum observations per entity */
+    MAX_OBSERVATIONS_PER_ENTITY: 1000,
+    /** Maximum tags per entity */
+    MAX_TAGS_PER_ENTITY: 100,
+};
+/**
+ * Query complexity limits to prevent expensive query operations.
+ * These limits protect against denial-of-service through complex queries.
+ */
+export const QUERY_LIMITS = {
+    /** Maximum nesting depth for boolean queries */
+    MAX_DEPTH: 10,
+    /** Maximum number of terms in a single query */
+    MAX_TERMS: 50,
+    /** Maximum number of boolean operators (AND/OR/NOT) */
+    MAX_OPERATORS: 20,
+    /** Maximum query string length */
+    MAX_QUERY_LENGTH: 5000,
+};
+/**
+ * Brotli compression configuration constants.
+ * Brotli is built into Node.js >=11.7.0 via the zlib module.
+ * No external dependencies required.
+ *
+ * Quality levels determine compression ratio vs speed tradeoff:
+ * - Lower values (0-4): Faster compression, lower ratio
+ * - Higher values (9-11): Slower compression, higher ratio
+ */
+export const COMPRESSION_CONFIG = {
+    // Quality levels (0-11)
+    /** Fast compression for real-time entity writes (quality 4) */
+    BROTLI_QUALITY_REALTIME: 4,
+    /** Balanced compression for exports and imports (quality 6) */
+    BROTLI_QUALITY_BATCH: 6,
+    /** Maximum compression for backups and archives (quality 11) */
+    BROTLI_QUALITY_ARCHIVE: 11,
+    /** Fast decompress for cache compression (quality 5) */
+    BROTLI_QUALITY_CACHE: 5,
+    // Auto-compression thresholds (in bytes)
+    /** Auto-compress exports larger than 100KB */
+    AUTO_COMPRESS_EXPORT_SIZE: 100 * 1024,
+    /** Auto-compress MCP responses larger than 256KB */
+    AUTO_COMPRESS_RESPONSE_SIZE: 256 * 1024,
+    /** Always compress backups by default */
+    AUTO_COMPRESS_BACKUP: true,
+    // File extension for compressed files
+    /** Brotli compressed file extension */
+    BROTLI_EXTENSION: '.br',
+    // Performance tuning
+    /** Chunk size for streaming compression (64KB) */
+    COMPRESSION_CHUNK_SIZE: 65536,
+    /** Default window size for brotli (lgwin parameter) */
+    COMPRESSION_WINDOW_SIZE: 22,
+};
+// ==================== Semantic Search Configuration (Phase 4 Sprint 10-12) ====================
+/**
+ * Environment variable names for embedding configuration.
+ */
+export const EMBEDDING_ENV_VARS = {
+    /** Embedding provider: 'openai', 'local', or 'none' (default: 'none') */
+    PROVIDER: 'MEMORY_EMBEDDING_PROVIDER',
+    /** OpenAI API key (required when provider is 'openai') */
+    OPENAI_API_KEY: 'MEMORY_OPENAI_API_KEY',
+    /** Optional model override for the embedding service */
+    MODEL: 'MEMORY_EMBEDDING_MODEL',
+    /** Auto-index entities on creation: 'true' or 'false' (default: 'false') */
+    AUTO_INDEX: 'MEMORY_AUTO_INDEX_EMBEDDINGS',
+};
+/**
+ * Default embedding configuration values.
+ */
+export const EMBEDDING_DEFAULTS = {
+    /** Default provider (disabled by default) */
+    PROVIDER: 'none',
+    /** Default OpenAI model for embeddings (1536 dimensions) */
+    OPENAI_MODEL: 'text-embedding-3-small',
+    /** Default local model for embeddings (384 dimensions) */
+    LOCAL_MODEL: 'Xenova/all-MiniLM-L6-v2',
+    /** OpenAI embedding dimensions for text-embedding-3-small */
+    OPENAI_DIMENSIONS: 1536,
+    /** Local embedding dimensions for all-MiniLM-L6-v2 */
+    LOCAL_DIMENSIONS: 384,
+    /** Maximum texts per batch for OpenAI */
+    OPENAI_MAX_BATCH_SIZE: 2048,
+    /** Default batch size for embedding operations */
+    DEFAULT_BATCH_SIZE: 100,
+    /** Whether to auto-index entities by default */
+    AUTO_INDEX: false,
+};
+/**
+ * Semantic search configuration limits.
+ */
+export const SEMANTIC_SEARCH_LIMITS = {
+    /** Default number of results for semantic search */
+    DEFAULT_LIMIT: 10,
+    /** Maximum number of results for semantic search */
+    MAX_LIMIT: 100,
+    /** Minimum similarity score for results (0.0-1.0) */
+    MIN_SIMILARITY: 0.0,
+};
+/**
+ * OpenAI API configuration.
+ */
+export const OPENAI_API_CONFIG = {
+    /** Base URL for OpenAI API */
+    BASE_URL: 'https://api.openai.com/v1',
+    /** Embeddings endpoint */
+    EMBEDDINGS_ENDPOINT: '/embeddings',
+    /** Maximum retries for rate limiting */
+    MAX_RETRIES: 3,
+    /** Initial backoff delay in milliseconds */
+    INITIAL_BACKOFF_MS: 1000,
+    /** Maximum backoff delay in milliseconds */
+    MAX_BACKOFF_MS: 10000,
+};
+/**
+ * Get embedding configuration from environment variables.
+ *
+ * @returns EmbeddingConfig object with values from environment or defaults
+ */
+export function getEmbeddingConfig() {
+    const provider = (process.env[EMBEDDING_ENV_VARS.PROVIDER] || EMBEDDING_DEFAULTS.PROVIDER);
+    const apiKey = process.env[EMBEDDING_ENV_VARS.OPENAI_API_KEY];
+    const model = process.env[EMBEDDING_ENV_VARS.MODEL];
+    const autoIndex = process.env[EMBEDDING_ENV_VARS.AUTO_INDEX] === 'true';
+    return { provider, apiKey, model, autoIndex };
+}
+// ==================== Streaming Export Configuration (Phase 7 Sprint 1) ====================
+/**
+ * Streaming export configuration.
+ *
+ * Controls when to use streaming mode and buffer sizes for optimal memory usage.
+ */
+export const STREAMING_CONFIG = {
+    /** Minimum entity count to trigger streaming mode */
+    STREAMING_THRESHOLD: 5000,
+    /** Chunk size for batched streaming operations */
+    CHUNK_SIZE: 500,
+    /** High water mark for stream buffers (bytes) */
+    HIGH_WATER_MARK: 64 * 1024,
+    /** Flush interval for long-running streams (ms) */
+    FLUSH_INTERVAL_MS: 100,
+};
+//# sourceMappingURL=constants.js.map

package/dist/utils/constants.js.map

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

package/dist/utils/entityUtils.d.ts

@@ -0,0 +1,379 @@
+/**
+ * Entity Utilities
+ *
+ * Consolidated module for entity-related utilities including:
+ * - Entity lookup and manipulation functions
+ * - Tag normalization and matching
+ * - Date parsing and validation
+ * - Entity filtering by various criteria
+ * - Path utilities and validation
+ *
+ * @module utils/entityUtils
+ */
+import type { Entity, KnowledgeGraph } from '../types/index.js';
+/**
+ * FNV-1a hash function for fast string hashing.
+ *
+ * This is a non-cryptographic hash function that provides good distribution
+ * for bucketing and deduplication purposes. It's optimized for speed
+ * and produces a 32-bit unsigned integer.
+ *
+ * FNV-1a has the following properties:
+ * - Fast computation (single pass through string)
+ * - Good distribution for hash table use
+ * - Deterministic output for same input
+ *
+ * @param text - The string to hash
+ * @returns A 32-bit unsigned integer hash value
+ *
+ * @example
+ * ```typescript
+ * const hash = fnv1aHash('hello');
+ * console.log(hash); // 1335831723
+ *
+ * // Use for bucketing similar entities
+ * const bucket = fnv1aHash(entity.name.toLowerCase()) % numBuckets;
+ * ```
+ */
+export declare function fnv1aHash(text: string): number;
+/**
+ * Finds an entity by name in the graph.
+ * Overloaded to provide type-safe returns based on throwIfNotFound parameter.
+ *
+ * @param graph - The knowledge graph to search
+ * @param name - The entity name to find
+ * @param throwIfNotFound - Whether to throw if entity doesn't exist (default: true)
+ * @returns The entity if found, null if not found and throwIfNotFound is false
+ * @throws EntityNotFoundError if entity not found and throwIfNotFound is true
+ */
+export declare function findEntityByName(graph: KnowledgeGraph, name: string, throwIfNotFound: true): Entity;
+export declare function findEntityByName(graph: KnowledgeGraph, name: string, throwIfNotFound: false): Entity | null;
+export declare function findEntityByName(graph: KnowledgeGraph, name: string, throwIfNotFound?: boolean): Entity | null;
+/**
+ * Finds multiple entities by name.
+ *
+ * @param graph - The knowledge graph to search
+ * @param names - Array of entity names to find
+ * @param throwIfAnyNotFound - Whether to throw if any entity doesn't exist (default: true)
+ * @returns Array of found entities (may be shorter than names if throwIfAnyNotFound is false)
+ * @throws EntityNotFoundError if any entity not found and throwIfAnyNotFound is true
+ */
+export declare function findEntitiesByNames(graph: KnowledgeGraph, names: string[], throwIfAnyNotFound?: boolean): Entity[];
+/**
+ * Checks if an entity exists in the graph.
+ *
+ * @param graph - The knowledge graph to search
+ * @param name - The entity name to check
+ * @returns true if entity exists, false otherwise
+ */
+export declare function entityExists(graph: KnowledgeGraph, name: string): boolean;
+/**
+ * Gets the index of an entity in the graph's entities array.
+ *
+ * @param graph - The knowledge graph to search
+ * @param name - The entity name to find
+ * @returns The index if found, -1 otherwise
+ */
+export declare function getEntityIndex(graph: KnowledgeGraph, name: string): number;
+/**
+ * Removes an entity from the graph by name.
+ * Mutates the graph's entities array in place.
+ *
+ * @param graph - The knowledge graph to modify
+ * @param name - The entity name to remove
+ * @returns true if entity was removed, false if not found
+ */
+export declare function removeEntityByName(graph: KnowledgeGraph, name: string): boolean;
+/**
+ * Gets all entity names as a Set for fast lookup.
+ *
+ * @param graph - The knowledge graph
+ * @returns Set of all entity names
+ */
+export declare function getEntityNameSet(graph: KnowledgeGraph): Set<string>;
+/**
+ * Groups entities by their type.
+ *
+ * @param entities - Array of entities to group
+ * @returns Map of entity type to array of entities
+ */
+export declare function groupEntitiesByType(entities: Entity[]): Map<string, Entity[]>;
+/**
+ * Updates the lastModified timestamp on an entity.
+ * Mutates the entity in place.
+ *
+ * @param entity - The entity to update
+ * @returns The updated entity (same reference)
+ */
+export declare function touchEntity(entity: Entity): Entity;
+/**
+ * Normalizes a single tag to lowercase and trimmed.
+ *
+ * @param tag - Tag to normalize
+ * @returns Normalized tag
+ */
+export declare function normalizeTag(tag: string): string;
+/**
+ * Normalizes an array of tags to lowercase.
+ * Handles undefined/null input gracefully.
+ *
+ * @param tags - Array of tags to normalize, or undefined
+ * @returns Normalized tags array, or empty array if input is undefined/null
+ */
+export declare function normalizeTags(tags: string[] | undefined | null): string[];
+/**
+ * Checks if an entity's tags include any of the specified search tags.
+ * Both inputs are normalized before comparison.
+ *
+ * @param entityTags - Tags on the entity (may be undefined)
+ * @param searchTags - Tags to search for (may be undefined)
+ * @returns true if any search tag matches any entity tag, false if no match or either is empty
+ */
+export declare function hasMatchingTag(entityTags: string[] | undefined, searchTags: string[] | undefined): boolean;
+/**
+ * Checks if entity tags include ALL of the specified required tags.
+ *
+ * @param entityTags - Tags on the entity (may be undefined)
+ * @param requiredTags - All tags that must be present
+ * @returns true if all required tags are present
+ */
+export declare function hasAllTags(entityTags: string[] | undefined, requiredTags: string[]): boolean;
+/**
+ * Filters entities by tag match.
+ * Returns all entities if searchTags is empty or undefined.
+ *
+ * @param entities - Array of entities with optional tags property
+ * @param searchTags - Tags to filter by
+ * @returns Filtered entities that have at least one matching tag
+ */
+export declare function filterByTags<T extends {
+    tags?: string[];
+}>(entities: T[], searchTags: string[] | undefined): T[];
+/**
+ * Adds new tags to an existing tag array, avoiding duplicates.
+ * All tags are normalized to lowercase.
+ *
+ * @param existingTags - Current tags (may be undefined)
+ * @param newTags - Tags to add
+ * @returns Combined tags array with no duplicates
+ */
+export declare function addUniqueTags(existingTags: string[] | undefined, newTags: string[]): string[];
+/**
+ * Removes specified tags from an existing tag array.
+ * Comparison is case-insensitive.
+ *
+ * @param existingTags - Current tags (may be undefined)
+ * @param tagsToRemove - Tags to remove
+ * @returns Tags array with specified tags removed
+ */
+export declare function removeTags(existingTags: string[] | undefined, tagsToRemove: string[]): string[];
+/**
+ * Check if a date falls within a specified range.
+ *
+ * @param date - ISO 8601 date string to check (may be undefined)
+ * @param start - Optional start date (inclusive)
+ * @param end - Optional end date (inclusive)
+ * @returns True if date is within range or no filters are set
+ *
+ * @example
+ * ```typescript
+ * isWithinDateRange('2024-06-15T00:00:00Z', '2024-01-01T00:00:00Z', '2024-12-31T23:59:59Z'); // true
+ * isWithinDateRange('2024-06-15T00:00:00Z', '2024-07-01T00:00:00Z'); // false
+ * isWithinDateRange(undefined); // true (no filters)
+ * isWithinDateRange(undefined, '2024-01-01T00:00:00Z'); // false (has filter but no date)
+ * ```
+ */
+export declare function isWithinDateRange(date: string | undefined, start?: string, end?: string): boolean;
+/**
+ * Parse and validate date range strings.
+ *
+ * @param startDate - Optional ISO 8601 start date
+ * @param endDate - Optional ISO 8601 end date
+ * @returns Parsed Date objects or null
+ */
+export declare function parseDateRange(startDate?: string, endDate?: string): {
+    start: Date | null;
+    end: Date | null;
+};
+/**
+ * Validate if a string is a valid ISO 8601 date.
+ *
+ * @param date - Date string to validate
+ * @returns True if valid ISO 8601 date
+ */
+export declare function isValidISODate(date: string): boolean;
+/**
+ * Get current timestamp in ISO 8601 format.
+ *
+ * @returns Current timestamp string
+ */
+export declare function getCurrentTimestamp(): string;
+/**
+ * Checks if an entity's importance is within the specified range.
+ * Entities without importance are treated as not matching if any filter is set.
+ *
+ * @param importance - The entity's importance value (may be undefined)
+ * @param minImportance - Minimum importance filter (inclusive)
+ * @param maxImportance - Maximum importance filter (inclusive)
+ * @returns true if importance is within range or no filters are set
+ *
+ * @example
+ * ```typescript
+ * // Check if entity passes importance filter
+ * if (isWithinImportanceRange(entity.importance, 5, 10)) {
+ *   // Entity has importance between 5 and 10
+ * }
+ * ```
+ */
+export declare function isWithinImportanceRange(importance: number | undefined, minImportance?: number, maxImportance?: number): boolean;
+/**
+ * Filters entities by importance range.
+ * Returns all entities if no importance filters are specified.
+ *
+ * @param entities - Array of entities to filter
+ * @param minImportance - Minimum importance filter (inclusive)
+ * @param maxImportance - Maximum importance filter (inclusive)
+ * @returns Filtered entities within the importance range
+ */
+export declare function filterByImportance(entities: Entity[], minImportance?: number, maxImportance?: number): Entity[];
+/**
+ * Filters entities by creation date range.
+ *
+ * @param entities - Array of entities to filter
+ * @param startDate - Start of date range (inclusive)
+ * @param endDate - End of date range (inclusive)
+ * @returns Filtered entities created within the date range
+ */
+export declare function filterByCreatedDate(entities: Entity[], startDate?: string, endDate?: string): Entity[];
+/**
+ * Filters entities by last modified date range.
+ *
+ * @param entities - Array of entities to filter
+ * @param startDate - Start of date range (inclusive)
+ * @param endDate - End of date range (inclusive)
+ * @returns Filtered entities modified within the date range
+ */
+export declare function filterByModifiedDate(entities: Entity[], startDate?: string, endDate?: string): Entity[];
+/**
+ * Filters entities by entity type.
+ *
+ * @param entities - Array of entities to filter
+ * @param entityType - Entity type to filter by (case-sensitive)
+ * @returns Filtered entities of the specified type
+ */
+export declare function filterByEntityType(entities: Entity[], entityType?: string): Entity[];
+/**
+ * Common search filters that can be applied to entities.
+ */
+export interface CommonSearchFilters {
+    tags?: string[];
+    minImportance?: number;
+    maxImportance?: number;
+    entityType?: string;
+    createdAfter?: string;
+    createdBefore?: string;
+    modifiedAfter?: string;
+    modifiedBefore?: string;
+}
+/**
+ * Checks if an entity passes all the specified filters.
+ * Short-circuits on first failing filter for performance.
+ *
+ * Note: Tag filtering should be handled separately using hasMatchingTag
+ * as it requires special normalization logic.
+ *
+ * @param entity - Entity to check
+ * @param filters - Filters to apply
+ * @returns true if entity passes all filters
+ */
+export declare function entityPassesFilters(entity: Entity, filters: Omit<CommonSearchFilters, 'tags'>): boolean;
+/**
+ * Sanitizes an object by removing potentially dangerous keys.
+ * This prevents prototype pollution attacks when using Object.assign() or spread operators.
+ *
+ * @param obj - The object to sanitize
+ * @returns A new object with dangerous keys removed
+ *
+ * @example
+ * ```typescript
+ * // Safe usage with Object.assign
+ * const updates = sanitizeObject(userInput);
+ * Object.assign(entity, updates);
+ *
+ * // Protects against prototype pollution
+ * const malicious = { __proto__: { admin: true } };
+ * const safe = sanitizeObject(malicious); // { }
+ * ```
+ */
+export declare function sanitizeObject<T extends Record<string, unknown>>(obj: T): Partial<T>;
+/**
+ * Escapes a CSV field to prevent formula injection attacks.
+ * Prepends a single quote to values that start with dangerous characters.
+ *
+ * @param field - The field value to escape
+ * @returns Escaped field value safe for CSV export
+ *
+ * @example
+ * ```typescript
+ * escapeCsvFormula('=SUM(A1:A10)'); // "'=SUM(A1:A10)"
+ * escapeCsvFormula('normal text'); // 'normal text'
+ * ```
+ */
+export declare function escapeCsvFormula(field: string | undefined | null): string;
+/**
+ * Validate and normalize a file path to prevent path traversal attacks.
+ *
+ * This function:
+ * - Normalizes the path to canonical form
+ * - Converts relative paths to absolute paths
+ * - Detects and prevents path traversal attempts (..)
+ *
+ * @param filePath - The file path to validate
+ * @param baseDir - Optional base directory for relative paths (defaults to process.cwd())
+ * @returns Validated absolute file path
+ * @throws {FileOperationError} If path traversal is detected or path is invalid
+ *
+ * @example
+ * ```typescript
+ * // Valid paths
+ * validateFilePath('/var/data/memory.jsonl'); // Returns absolute path
+ * validateFilePath('data/memory.jsonl'); // Returns absolute path from cwd
+ *
+ * // Invalid paths (throws FileOperationError)
+ * validateFilePath('../../../etc/passwd'); // Path traversal detected
+ * validateFilePath('/var/data/../../../etc/passwd'); // Path traversal detected
+ * ```
+ */
+export declare function validateFilePath(filePath: string, baseDir?: string): string;
+/**
+ * Default memory file path (in project root directory, outside dist/).
+ */
+export declare const defaultMemoryPath: string;
+/**
+ * Ensure memory file path with backward compatibility migration.
+ *
+ * Handles:
+ * 1. Custom MEMORY_FILE_PATH environment variable (with path traversal protection)
+ * 2. Backward compatibility: migrates memory.json to memory.jsonl
+ * 3. Absolute vs relative path resolution
+ *
+ * @returns Resolved and validated memory file path
+ * @throws {FileOperationError} If path traversal is detected in MEMORY_FILE_PATH
+ *
+ * @example
+ * ```typescript
+ * // Use environment variable
+ * process.env.MEMORY_FILE_PATH = '/data/memory.jsonl';
+ * const path = await ensureMemoryFilePath(); // '/data/memory.jsonl'
+ *
+ * // Use default path
+ * delete process.env.MEMORY_FILE_PATH;
+ * const path = await ensureMemoryFilePath(); // './memory.jsonl'
+ *
+ * // Invalid path (throws error)
+ * process.env.MEMORY_FILE_PATH = '../../../etc/passwd';
+ * await ensureMemoryFilePath(); // Throws FileOperationError
+ * ```
+ */
+export declare function ensureMemoryFilePath(): Promise<string>;
+//# sourceMappingURL=entityUtils.d.ts.map

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

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