@dollhousemcp/mcp-server 1.8.0 → 1.9.0

package/dist/elements/memories/Memory.d.ts

@@ -0,0 +1,190 @@
+/**
+ * Memory Element - Persistent context storage for continuity and learning
+ *
+ * Provides multiple storage backends, retention policies, and search capabilities
+ * for maintaining context across sessions and interactions.
+ *
+ * SECURITY MEASURES IMPLEMENTED:
+ * 1. Input sanitization for all memory content
+ * 2. Memory size limits to prevent unbounded growth
+ * 3. Path validation for file-based storage
+ * 4. Retention policy enforcement
+ * 5. Privacy level access control
+ * 6. Audit logging for all operations
+ */
+import { BaseElement } from '../BaseElement.js';
+import { IElement, ElementValidationResult } from '../../types/elements/index.js';
+import { IElementMetadata } from '../../types/elements/IElement.js';
+import { PrivacyLevel, StorageBackend } from './constants.js';
+export interface MemoryMetadata extends IElementMetadata {
+    storageBackend?: StorageBackend;
+    retentionDays?: number;
+    privacyLevel?: PrivacyLevel;
+    searchable?: boolean;
+    maxEntries?: number;
+    encryptionEnabled?: boolean;
+    indexThreshold?: number;
+    enableContentIndex?: boolean;
+    maxTermsPerEntry?: number;
+    minTermLength?: number;
+}
+export interface MemoryEntry {
+    id: string;
+    timestamp: Date;
+    content: string;
+    tags?: string[];
+    metadata?: Record<string, any>;
+    expiresAt?: Date;
+    privacyLevel?: PrivacyLevel;
+}
+export interface MemorySearchOptions {
+    query?: string;
+    tags?: string[];
+    startDate?: Date;
+    endDate?: Date;
+    limit?: number;
+    privacyLevel?: PrivacyLevel;
+}
+/**
+ * Memory Element Implementation
+ *
+ * TODO: Memory Sharding Strategy (Issue #981)
+ * ---------------------------------------------
+ * Current: Single Map<id, entry> for all memories
+ * Problem: Large memory sets (>10K entries) cause performance degradation
+ *
+ * Planned Sharding Architecture:
+ * 1. Shard memories across multiple files based on hash(memoryId) % shardCount
+ * 2. Each shard file <256KB for optimal YAML parsing
+ * 3. Memory references stored separately from content (like git objects)
+ * 4. Large binary content (PDFs, images) stored as external references
+ *
+ * Benefits:
+ * - Parallel loading of memory shards
+ * - Reduced memory footprint (load only needed shards)
+ * - Better corruption resistance (one shard failure doesn't affect others)
+ * - Efficient incremental updates
+ *
+ * TODO: Content Integrity Verification (Issue #982)
+ * --------------------------------------------------
+ * Add SHA-256 hashes to detect:
+ * - Accidental corruption from disk errors
+ * - Intentional tampering with memory files
+ * - Version conflicts during concurrent access
+ *
+ * Implementation:
+ * - Store hash in memory metadata
+ * - Verify on load, warn on mismatch
+ * - Option to auto-restore from backup on corruption
+ *
+ * TODO: Memory Capacity Management (Issue #983)
+ * ---------------------------------------------
+ * Current: Synchronous retention enforcement on each add
+ * Better: Background cleanup with smart triggers:
+ * - Cleanup when 90% capacity reached
+ * - Batch deletions for efficiency
+ * - LRU eviction with access tracking
+ * - Preserve "pinned" memories regardless of age
+ */
+export declare class Memory extends BaseElement implements IElement {
+    private entries;
+    private storageBackend;
+    private retentionDays;
+    private privacyLevel;
+    private searchable;
+    private maxEntries;
+    private searchIndex;
+    private sanitizationCache;
+    constructor(metadata?: Partial<MemoryMetadata>);
+    /**
+     * Add a new memory entry
+     * SECURITY: Validates and sanitizes all input, enforces size limits
+     */
+    addEntry(content: string, tags?: string[], metadata?: Record<string, any>): Promise<MemoryEntry>;
+    /**
+     * Search memory entries
+     * SECURITY: Respects privacy levels and sanitizes search queries
+     *
+     * IMPLEMENTED: Basic indexed search for O(log n) performance (Issue #984)
+     * - Tag index: Map<tag, Set<entryId>> for instant tag lookups ✓
+     * - Content index: Inverted index for term search ✓
+     * - Date index: Binary tree for efficient range queries ✓
+     * - Privacy index: Pre-sorted entries by privacy level ✓
+     *
+     * TODO: Advanced indexing features (Future enhancements):
+     * - Composite indices: Combined indices for common query patterns
+     * - Index-of-indexes pattern:
+     *   - Master index file (meta.yaml) with pointers to shard indices
+     *   - Each shard maintains its own local index
+     *   - Periodic index compaction and optimization
+     * - Persistent index storage to disk
+     * - Incremental index updates for large datasets
+     *
+     * Performance improvement achieved:
+     * - Previous: ~100ms for 10,000 entries (linear scan)
+     * - Current: <5ms for same dataset (indexed search)
+     */
+    search(options?: MemorySearchOptions): Promise<MemoryEntry[]>;
+    /**
+     * Get a specific memory entry by ID
+     */
+    getEntry(id: string): Promise<MemoryEntry | undefined>;
+    /**
+     * Delete a memory entry
+     * SECURITY: Validates permissions and logs deletion
+     */
+    deleteEntry(id: string): Promise<boolean>;
+    /**
+     * Enforce retention policy by removing expired entries
+     * SECURITY: Ensures memory doesn't grow unbounded
+     */
+    enforceRetentionPolicy(): Promise<number>;
+    /**
+     * Clear all memory entries
+     * SECURITY: Requires confirmation and logs the action
+     */
+    clearAll(confirm?: boolean): Promise<void>;
+    /**
+     * Get memory statistics
+     */
+    getStats(): {
+        totalEntries: number;
+        totalSize: number;
+        oldestEntry?: Date;
+        newestEntry?: Date;
+        tagFrequency: Map<string, number>;
+    };
+    /**
+     * Validate the memory element
+     */
+    validate(): ElementValidationResult;
+    /**
+     * Serialize memory to string
+     */
+    serialize(): string;
+    /**
+     * Deserialize memory from string
+     * SECURITY: Validates all loaded data
+     */
+    deserialize(data: string): void;
+    private calculateExpiryDate;
+    private sanitizeTags;
+    private sanitizeMetadata;
+    private canAccessPrivacyLevel;
+    private isValidEntry;
+    /**
+     * Optimized sanitization with checksum caching
+     * Avoids re-sanitizing content that hasn't changed
+     * @param content Content to sanitize
+     * @param maxLength Maximum allowed length
+     * @returns Sanitized content
+     */
+    private sanitizeWithCache;
+    /**
+     * Build search index with retry logic
+     * Attempts to build the index up to 3 times with exponential backoff
+     * This ensures search functionality even if there are transient failures
+     */
+    private buildSearchIndexWithRetry;
+}
+//# sourceMappingURL=Memory.d.ts.map

package/dist/elements/memories/Memory.d.ts.map

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