Enhanced Knowledge Graph Memory Server

# Index.ts Refactoring - Detailed Implementation Tasks This document provides a granular breakdown of all tasks required to complete the refactoring, organized by phase with dependencies, acceptance criteria, and test requirements. **Total Tasks**: 110 **Estimated Effort**: 140-175 hours **Duration**: 7 weeks --- ## Task Organization ### Task Numbering Convention - **Phase.Section.Task** (e.g., 1.1.1) - Phase: 1-8 (matching REFACTORING_PLAN.md phases) - Section: Functional area within phase - Task: Sequential task number ### Task Status Tracking - ⏸️ **Pending**: Not started - 🔄 **In Progress**: Currently being worked on - ✅ **Completed**: Done and tested - ⚠️ **Blocked**: Waiting on dependency --- ## Phase 1: Foundation (Week 1) **Goal**: Establish new structure without breaking existing code ### 1.1 Directory Structure Setup #### 1.1.1 Create base directory structure **Status**: ⏸️ Pending **Files to create**: ```bash src/memory/types/ src/memory/core/ src/memory/search/ src/memory/features/ src/memory/features/import-export/ src/memory/features/import-export/formats/ src/memory/utils/ src/memory/mcp/ src/memory/mcp/tools/ src/memory/mcp/handlers/ src/memory/config/ src/memory/__tests__/unit/ src/memory/__tests__/unit/core/ src/memory/__tests__/unit/search/ src/memory/__tests__/unit/features/ src/memory/__tests__/unit/utils/ src/memory/__tests__/integration/ src/memory/__tests__/performance/ ``` **Acceptance Criteria**: - [ ] All directories created - [ ] No existing code broken - [ ] README added to each directory explaining purpose **Estimated Time**: 30 minutes --- ### 1.2 Extract Type Definitions #### 1.2.1 Extract Entity types to types/entity.types.ts **Status**: ⏸️ Pending **Dependencies**: 1.1.1 **Target Size**: <100 lines **Content**: - `Entity` interface - `Relation` interface - `KnowledgeGraph` interface **Acceptance Criteria**: - [ ] All entity-related types extracted - [ ] Proper JSDoc comments added - [ ] Exports are named exports - [ ] File is <100 lines - [ ] No breaking changes to existing imports **Estimated Time**: 45 minutes #### 1.2.2 Extract Search types to types/search.types.ts **Status**: ⏸️ Pending **Dependencies**: 1.2.1 **Target Size**: <100 lines **Content**: - `SearchResult` interface - `SavedSearch` interface - `BooleanQueryNode` type **Acceptance Criteria**: - [ ] All search-related types extracted - [ ] Proper JSDoc comments added - [ ] File is <100 lines - [ ] Types are properly exported **Estimated Time**: 45 minutes #### 1.2.3 Extract Analytics types to types/analytics.types.ts **Status**: ⏸️ Pending **Dependencies**: 1.2.2 **Target Size**: <150 lines **Content**: - `GraphStats` interface - `ValidationReport` interface - `ValidationError` interface - `ValidationWarning` interface **Acceptance Criteria**: - [ ] All analytics-related types extracted - [ ] Proper JSDoc comments added - [ ] File is <150 lines - [ ] Types include examples in comments **Estimated Time**: 1 hour #### 1.2.4 Extract ImportExport types to types/import-export.types.ts **Status**: ⏸️ Pending **Dependencies**: 1.2.3 **Target Size**: <50 lines **Content**: - `ImportResult` interface - `CompressionResult` interface **Acceptance Criteria**: - [ ] All import/export-related types extracted - [ ] Proper JSDoc comments added - [ ] File is <50 lines **Estimated Time**: 30 minutes #### 1.2.5 Extract Tag types to types/tag.types.ts **Status**: ⏸️ Pending **Dependencies**: 1.2.4 **Target Size**: <50 lines **Content**: - `TagAlias` interface **Acceptance Criteria**: - [ ] All tag-related types extracted - [ ] Proper JSDoc comments added - [ ] File is <50 lines **Estimated Time**: 30 minutes #### 1.2.6 Create types/index.ts to re-export all types **Status**: ⏸️ Pending **Dependencies**: 1.2.1, 1.2.2, 1.2.3, 1.2.4, 1.2.5 **Target Size**: <50 lines **Content**: ```typescript export * from './entity.types.js'; export * from './search.types.js'; export * from './analytics.types.js'; export * from './import-export.types.js'; export * from './tag.types.js'; ``` **Acceptance Criteria**: - [ ] All types re-exported - [ ] Barrel export pattern used - [ ] No circular dependencies - [ ] File is <50 lines **Estimated Time**: 15 minutes **Phase 1 Total Time**: ~4.5 hours --- ## Phase 2: Extract Utilities (Week 1-2) **Goal**: Move pure utility functions to separate files ### 2.1 String Utilities #### 2.1.1 Extract Levenshtein distance to utils/levenshtein.ts **Status**: ⏸️ Pending **Dependencies**: 1.2.6 **Target Size**: <50 lines **Content**: - `levenshteinDistance(str1: string, str2: string): number` **Acceptance Criteria**: - [ ] Function extracted from index.ts - [ ] Proper JSDoc with algorithm explanation - [ ] Time/space complexity documented - [ ] File is <50 lines - [ ] Pure function with no side effects **Estimated Time**: 30 minutes #### 2.1.2 Write comprehensive tests for utils/levenshtein.ts **Status**: ⏸️ Pending **Dependencies**: 2.1.1 **Target Size**: <100 lines **Test Cases**: - Empty strings - Identical strings - Single character difference - Complete mismatch - Different lengths - Unicode characters - Performance with long strings **Acceptance Criteria**: - [ ] 100% code coverage - [ ] All edge cases tested - [ ] Performance tests included - [ ] Test file is <100 lines **Estimated Time**: 1 hour #### 2.1.3 Extract TF-IDF functions to utils/tfidf.ts **Status**: ⏸️ Pending **Dependencies**: 2.1.2 **Target Size**: <150 lines **Content**: - `calculateTF(term: string, document: string): number` - `calculateIDF(term: string, documents: string[]): number` - `calculateTFIDF(term: string, document: string, documents: string[]): number` - Helper functions for tokenization **Acceptance Criteria**: - [ ] All TF-IDF functions extracted - [ ] Algorithm properly documented - [ ] File is <150 lines - [ ] Functions are pure **Estimated Time**: 1.5 hours #### 2.1.4 Write comprehensive tests for utils/tfidf.ts **Status**: ⏸️ Pending **Dependencies**: 2.1.3 **Target Size**: <150 lines **Test Cases**: - Term frequency calculations - Inverse document frequency - Complete TF-IDF scoring - Multiple documents - Edge cases (empty docs, no matches) **Acceptance Criteria**: - [ ] 100% code coverage - [ ] Mathematical correctness verified - [ ] Test file is <150 lines **Estimated Time**: 1.5 hours ### 2.2 Date Utilities #### 2.2.1 Extract date utilities to utils/dateUtils.ts **Status**: ⏸️ Pending **Dependencies**: 2.1.4 **Target Size**: <100 lines **Content**: - `isWithinDateRange(date: string, start?: string, end?: string): boolean` - `parseDateRange(startDate?: string, endDate?: string): { start: Date | null; end: Date | null }` - `isValidISODate(date: string): boolean` **Acceptance Criteria**: - [ ] All date functions extracted - [ ] ISO 8601 format handling - [ ] Timezone handling documented - [ ] File is <100 lines **Estimated Time**: 1 hour #### 2.2.2 Write tests for utils/dateUtils.ts **Status**: ⏸️ Pending **Dependencies**: 2.2.1 **Target Size**: <100 lines **Test Cases**: - Valid date ranges - Invalid dates - Boundary conditions - Timezone edge cases - ISO 8601 format variations **Acceptance Criteria**: - [ ] 100% code coverage - [ ] All date formats tested - [ ] Test file is <100 lines **Estimated Time**: 1 hour ### 2.3 Validation Utilities #### 2.3.1 Extract validation utilities to utils/validationUtils.ts **Status**: ⏸️ Pending **Dependencies**: 2.2.2 **Target Size**: <150 lines **Content**: - `validateEntity(entity: Entity): { valid: boolean; errors: string[] }` - `validateRelation(relation: Relation): { valid: boolean; errors: string[] }` - `validateImportance(importance: number): boolean` - `validateTags(tags: string[]): { valid: boolean; errors: string[] }` **Acceptance Criteria**: - [ ] All validation logic extracted - [ ] Clear error messages - [ ] File is <150 lines - [ ] Functions are pure **Estimated Time**: 1.5 hours #### 2.3.2 Write tests for utils/validationUtils.ts **Status**: ⏸️ Pending **Dependencies**: 2.3.1 **Target Size**: <150 lines **Test Cases**: - Valid entities/relations - Invalid data - Boundary values (importance 0, 10) - Missing required fields - Type validation **Acceptance Criteria**: - [ ] 100% code coverage - [ ] All validation paths tested - [ ] Test file is <150 lines **Estimated Time**: 1.5 hours ### 2.4 Path Utilities #### 2.4.1 Extract path utilities to utils/pathUtils.ts **Status**: ⏸️ Pending **Dependencies**: 2.3.2 **Target Size**: <100 lines **Content**: - `ensureMemoryFilePath(): Promise<string>` - `defaultMemoryPath` constant - Backward compatibility logic **Acceptance Criteria**: - [ ] File path logic extracted - [ ] Backward compatibility maintained - [ ] File is <100 lines - [ ] Cross-platform path handling **Estimated Time**: 1 hour #### 2.4.2 Write tests for utils/pathUtils.ts **Status**: ⏸️ Pending **Dependencies**: 2.4.1 **Target Size**: <100 lines **Test Cases**: - Default path resolution - Custom MEMORY_FILE_PATH env var - Backward compatibility migration - Absolute vs relative paths - Cross-platform paths **Acceptance Criteria**: - [ ] 100% code coverage - [ ] Migration logic tested - [ ] Test file is <100 lines **Estimated Time**: 1 hour **Phase 2 Total Time**: ~12 hours --- ## Phase 3: Extract Storage Layer (Week 2) **Goal**: Separate file I/O from business logic ### 3.1 Graph Storage Module #### 3.1.1 Create GraphStorage.ts with loadGraph() and saveGraph() **Status**: ⏸️ Pending **Dependencies**: 2.4.2 **Target Size**: <150 lines **Content**: - `constructor(memoryFilePath: string)` - `loadGraph(): Promise<KnowledgeGraph>` - `saveGraph(graph: KnowledgeGraph): Promise<void>` - Backward compatibility for JSONL format - Error handling **Acceptance Criteria**: - [ ] File I/O logic extracted - [ ] JSONL format handling - [ ] Backward compatibility maintained - [ ] Proper error handling - [ ] File is <150 lines **Estimated Time**: 2 hours #### 3.1.2 Write unit tests for GraphStorage.ts **Status**: ⏸️ Pending **Dependencies**: 3.1.1 **Target Size**: <250 lines **Test Cases**: - Load empty graph - Load existing graph - Save new graph - JSONL format validation - File not found handling - Corrupted file handling - Concurrent access (if applicable) - Backward compatibility **Acceptance Criteria**: - [ ] 100% code coverage - [ ] Mock file system - [ ] Test file is <250 lines - [ ] All error paths tested **Estimated Time**: 2.5 hours #### 3.1.3 Update index.ts to use GraphStorage **Status**: ⏸️ Pending **Dependencies**: 3.1.2 **Target Size**: N/A (modifying existing) **Changes**: - Replace direct fs calls with GraphStorage - Inject GraphStorage into KnowledgeGraphManager - Verify backward compatibility **Acceptance Criteria**: - [ ] All existing tests pass - [ ] No regressions - [ ] GraphStorage properly injected - [ ] File operations delegated to GraphStorage **Estimated Time**: 1.5 hours **Phase 3 Total Time**: ~6 hours --- ## Phase 4: Extract Core Managers (Week 3) **Goal**: Separate CRUD operations by domain ### 4.1 Entity Manager #### 4.1.1 Create EntityManager.ts with CRUD operations **Status**: ⏸️ Pending **Dependencies**: 3.1.3 **Target Size**: <200 lines **Content**: - `constructor(storage: GraphStorage)` - `createEntities(entities: Entity[]): Promise<Entity[]>` - `deleteEntities(entityNames: string[]): Promise<void>` - `getEntity(name: string): Promise<Entity | null>` - `updateEntity(name: string, updates: Partial<Entity>): Promise<Entity>` - Timestamp management **Acceptance Criteria**: - [ ] All entity CRUD operations - [ ] Dependency injection used - [ ] File is <200 lines - [ ] Proper error handling **Estimated Time**: 2.5 hours #### 4.1.2 Write unit tests for EntityManager.ts **Status**: ⏸️ Pending **Dependencies**: 4.1.1 **Target Size**: <300 lines **Test Cases**: - Create single entity - Create multiple entities - Create duplicate (should skip) - Delete entity - Delete non-existent entity - Get entity - Update entity - Timestamp updates **Acceptance Criteria**: - [ ] 100% code coverage - [ ] Mock GraphStorage - [ ] Test file is <300 lines - [ ] All CRUD operations tested **Estimated Time**: 3 hours ### 4.2 Relation Manager #### 4.2.1 Create RelationManager.ts with CRUD operations **Status**: ⏸️ Pending **Dependencies**: 4.1.2 **Target Size**: <150 lines **Content**: - `constructor(storage: GraphStorage)` - `createRelations(relations: Relation[]): Promise<Relation[]>` - `deleteRelations(relations: Relation[]): Promise<void>` - `getRelations(entityName: string): Promise<Relation[]>` - Timestamp management **Acceptance Criteria**: - [ ] All relation CRUD operations - [ ] Dependency injection used - [ ] File is <150 lines - [ ] Cascading delete awareness **Estimated Time**: 2 hours #### 4.2.2 Write unit tests for RelationManager.ts **Status**: ⏸️ Pending **Dependencies**: 4.2.1 **Target Size**: <250 lines **Test Cases**: - Create relations - Create duplicates - Delete relations - Get relations for entity - Orphaned relations handling **Acceptance Criteria**: - [ ] 100% code coverage - [ ] Mock GraphStorage - [ ] Test file is <250 lines **Estimated Time**: 2.5 hours ### 4.3 Observation Manager #### 4.3.1 Create ObservationManager.ts with CRUD operations **Status**: ⏸️ Pending **Dependencies**: 4.2.2 **Target Size**: <100 lines **Content**: - `constructor(storage: GraphStorage)` - `addObservations(observations: {...}[]): Promise<{...}[]>` - `deleteObservations(deletions: {...}[]): Promise<void>` - Timestamp updates **Acceptance Criteria**: - [ ] All observation CRUD operations - [ ] Dependency injection used - [ ] File is <100 lines - [ ] Duplicate detection **Estimated Time**: 1.5 hours #### 4.3.2 Write unit tests for ObservationManager.ts **Status**: ⏸️ Pending **Dependencies**: 4.3.1 **Target Size**: <200 lines **Test Cases**: - Add observations - Add duplicates (should skip) - Delete observations - Delete non-existent observations - Timestamp updates **Acceptance Criteria**: - [ ] 100% code coverage - [ ] Mock GraphStorage - [ ] Test file is <200 lines **Estimated Time**: 2 hours ### 4.4 Knowledge Graph Manager Refactoring #### 4.4.1 Refactor KnowledgeGraphManager to use composition pattern **Status**: ⏸️ Pending **Dependencies**: 4.3.2 **Target Size**: <350 lines **Changes**: - Add manager dependencies - Delegate CRUD to managers - Maintain public API - Use composition over inheritance **Acceptance Criteria**: - [ ] All managers injected - [ ] Methods delegate to managers - [ ] Public API unchanged - [ ] File is <350 lines - [ ] Backward compatibility maintained **Estimated Time**: 3 hours #### 4.4.2 Write integration tests for core managers **Status**: ⏸️ Pending **Dependencies**: 4.4.1 **Target Size**: <350 lines **Test Cases**: - End-to-end entity workflows - Entity-relation interactions - Observation workflows - Cascade operations - Error propagation **Acceptance Criteria**: - [ ] All manager interactions tested - [ ] Real file system (temp dir) - [ ] Test file is <350 lines **Estimated Time**: 3.5 hours **Phase 4 Total Time**: ~20 hours --- ## Phase 5: Extract Search Module (Week 4) **Goal**: Modularize complex search functionality ### 5.1 Basic Search #### 5.1.1 Create BasicSearch.ts with searchNodes and openNodes **Status**: ⏸️ Pending **Dependencies**: 4.4.2 **Target Size**: <200 lines **Content**: - `constructor(storage: GraphStorage)` - `searchNodes(query, tags?, minImportance?, maxImportance?): Promise<KnowledgeGraph>` - `openNodes(names: string[]): Promise<KnowledgeGraph>` - `searchByDateRange(...): Promise<KnowledgeGraph>` **Acceptance Criteria**: - [ ] Basic search logic extracted - [ ] Tag filtering works - [ ] Importance filtering works - [ ] File is <200 lines **Estimated Time**: 2.5 hours #### 5.1.2 Write unit tests for BasicSearch.ts **Status**: ⏸️ Pending **Dependencies**: 5.1.1 **Target Size**: <300 lines **Test Cases**: - Text search - Tag filtering - Importance filtering - Combined filters - Empty results - Date range search **Acceptance Criteria**: - [ ] 100% code coverage - [ ] Mock GraphStorage - [ ] Test file is <300 lines **Estimated Time**: 3 hours ### 5.2 Ranked Search #### 5.2.1 Create RankedSearch.ts with TF-IDF implementation **Status**: ⏸️ Pending **Dependencies**: 5.1.2 **Target Size**: <300 lines **Content**: - `constructor(storage: GraphStorage)` - `searchNodesRanked(query, ...): Promise<SearchResult[]>` - `calculateTFIDF(query, entities): Map<Entity, number>` - `calculateTF(term, entity): number` - `calculateIDF(term, entities): number` - Result ranking **Acceptance Criteria**: - [ ] TF-IDF algorithm implemented - [ ] Results sorted by score - [ ] File is <300 lines - [ ] Uses utils/tfidf.ts **Estimated Time**: 3.5 hours #### 5.2.2 Write unit tests for RankedSearch.ts **Status**: ⏸️ Pending **Dependencies**: 5.2.1 **Target Size**: <350 lines **Test Cases**: - Relevance scoring - Multiple terms - Score ordering - Edge cases (no matches) - Limit parameter **Acceptance Criteria**: - [ ] 100% code coverage - [ ] Ranking correctness verified - [ ] Test file is <350 lines **Estimated Time**: 3.5 hours ### 5.3 Boolean Search #### 5.3.1 Create BooleanSearch.ts with query parser **Status**: ⏸️ Pending **Dependencies**: 5.2.2 **Target Size**: <350 lines **Content**: - `constructor(storage: GraphStorage)` - `booleanSearch(query, ...): Promise<KnowledgeGraph>` - `parseBooleanQuery(query): BooleanQueryNode` - `evaluateBooleanQuery(node, entity): boolean` - `tokenize(query): Token[]` - AND, OR, NOT support - Field-specific queries **Acceptance Criteria**: - [ ] Boolean parser implemented - [ ] AST evaluation works - [ ] Field queries supported - [ ] File is <350 lines **Estimated Time**: 4 hours #### 5.3.2 Write unit tests for BooleanSearch.ts **Status**: ⏸️ Pending **Dependencies**: 5.3.1 **Target Size**: <400 lines **Test Cases**: - AND queries - OR queries - NOT queries - Nested queries - Field-specific queries - Parser errors - Complex expressions **Acceptance Criteria**: - [ ] 100% code coverage - [ ] All query types tested - [ ] Test file is <400 lines **Estimated Time**: 4 hours ### 5.4 Fuzzy Search #### 5.4.1 Create FuzzySearch.ts with Levenshtein matching **Status**: ⏸️ Pending **Dependencies**: 5.3.2 **Target Size**: <150 lines **Content**: - `constructor(storage: GraphStorage)` - `fuzzySearch(query, threshold?, ...): Promise<KnowledgeGraph>` - `isFuzzyMatch(str1, str2, threshold): boolean` - Uses utils/levenshtein.ts **Acceptance Criteria**: - [ ] Fuzzy matching implemented - [ ] Threshold configurable - [ ] File is <150 lines - [ ] Uses Levenshtein utility **Estimated Time**: 2 hours #### 5.4.2 Write unit tests for FuzzySearch.ts **Status**: ⏸️ Pending **Dependencies**: 5.4.1 **Target Size**: <250 lines **Test Cases**: - Exact matches - Close matches - Typo handling - Threshold variations - No matches **Acceptance Criteria**: - [ ] 100% code coverage - [ ] Fuzzy logic verified - [ ] Test file is <250 lines **Estimated Time**: 2.5 hours ### 5.5 Search Suggestions #### 5.5.1 Create SearchSuggestions.ts with trigram algorithm **Status**: ⏸️ Pending **Dependencies**: 5.4.2 **Target Size**: <150 lines **Content**: - `constructor(storage: GraphStorage)` - `getSearchSuggestions(query, maxSuggestions?): Promise<string[]>` - `generateTriGrams(text): Set<string>` - `triGramSimilarity(text1, text2): number` **Acceptance Criteria**: - [ ] Trigram similarity implemented - [ ] Suggestions sorted by relevance - [ ] File is <150 lines **Estimated Time**: 2 hours #### 5.5.2 Write unit tests for SearchSuggestions.ts **Status**: ⏸️ Pending **Dependencies**: 5.5.1 **Target Size**: <200 lines **Test Cases**: - Exact prefix matches - Partial matches - Trigram similarity - Max suggestions limit - Empty query **Acceptance Criteria**: - [ ] 100% code coverage - [ ] Suggestion quality verified - [ ] Test file is <200 lines **Estimated Time**: 2 hours ### 5.6 Saved Search Manager #### 5.6.1 Create SavedSearchManager.ts with search persistence **Status**: ⏸️ Pending **Dependencies**: 5.5.2 **Target Size**: <200 lines **Content**: - `constructor(savedSearchesPath: string)` - `saveSearch(search): Promise<SavedSearch>` - `listSavedSearches(): Promise<SavedSearch[]>` - `getSavedSearch(name): Promise<SavedSearch | null>` - `executeSavedSearch(name): Promise<KnowledgeGraph>` - `deleteSavedSearch(name): Promise<boolean>` - `updateSavedSearch(name, updates): Promise<SavedSearch>` **Acceptance Criteria**: - [ ] All saved search operations - [ ] Use count tracking - [ ] Last used tracking - [ ] File is <200 lines **Estimated Time**: 2.5 hours #### 5.6.2 Write unit tests for SavedSearchManager.ts **Status**: ⏸️ Pending **Dependencies**: 5.6.1 **Target Size**: <250 lines **Test Cases**: - Save search - List searches - Execute search - Delete search - Update search - Use count increments **Acceptance Criteria**: - [ ] 100% code coverage - [ ] JSONL persistence tested - [ ] Test file is <250 lines **Estimated Time**: 2.5 hours ### 5.7 Search Manager Orchestration #### 5.7.1 Create SearchManager.ts to orchestrate all search types **Status**: ⏸️ Pending **Dependencies**: 5.6.2 **Target Size**: <200 lines **Content**: - `constructor(storage, savedSearchPath)` - Delegates to specialized search classes - Provides unified search interface **Acceptance Criteria**: - [ ] All search types accessible - [ ] Clean delegation - [ ] File is <200 lines **Estimated Time**: 2 hours #### 5.7.2 Write integration tests for search operations **Status**: ⏸️ Pending **Dependencies**: 5.7.1 **Target Size**: <400 lines **Test Cases**: - All search types end-to-end - Search combinations - Performance benchmarks - Large datasets **Acceptance Criteria**: - [ ] All search types tested - [ ] Integration scenarios covered - [ ] Test file is <400 lines **Estimated Time**: 4 hours **Phase 5 Total Time**: ~40 hours --- ## Phase 6: Extract Feature Managers (Week 5) **Goal**: Separate advanced features ### 6.1 Tag Manager #### 6.1.1 Create TagManager.ts with tag operations and aliases **Status**: ⏸️ Pending **Dependencies**: 5.7.2 **Target Size**: <400 lines **Content**: - All tag CRUD operations - Tag alias management - Tag resolution - Tag merging - Bulk tag operations **Acceptance Criteria**: - [ ] All tag operations implemented - [ ] Alias resolution works - [ ] File is <400 lines **Estimated Time**: 4 hours #### 6.1.2 Write unit tests for TagManager.ts **Status**: ⏸️ Pending **Dependencies**: 6.1.1 **Target Size**: <400 lines **Test Cases**: - Add/remove tags - Bulk operations - Tag aliases - Tag resolution - Tag merging - Replace tag **Acceptance Criteria**: - [ ] 100% code coverage - [ ] All tag operations tested - [ ] Test file is <400 lines **Estimated Time**: 4 hours ### 6.2 Importance Manager #### 6.2.1 Create ImportanceManager.ts with importance operations **Status**: ⏸️ Pending **Dependencies**: 6.1.2 **Target Size**: <50 lines **Content**: - `setImportance(entityName, importance): Promise<{...}>` - Validation (0-10 range) **Acceptance Criteria**: - [ ] Importance setting works - [ ] Validation in place - [ ] File is <50 lines **Estimated Time**: 30 minutes #### 6.2.2 Write unit tests for ImportanceManager.ts **Status**: ⏸️ Pending **Dependencies**: 6.2.1 **Target Size**: <100 lines **Test Cases**: - Set valid importance - Reject invalid values - Boundary values (0, 10) - Out of range values **Acceptance Criteria**: - [ ] 100% code coverage - [ ] Validation tested - [ ] Test file is <100 lines **Estimated Time**: 45 minutes ### 6.3 Hierarchy Manager #### 6.3.1 Create HierarchyManager.ts with parent-child operations **Status**: ⏸️ Pending **Dependencies**: 6.2.2 **Target Size**: <450 lines **Content**: - Set parent - Get children/parent - Get ancestors/descendants - Get subtree - Get root entities - Get entity depth - Move entity - Cycle detection **Acceptance Criteria**: - [ ] All hierarchy operations - [ ] Cycle prevention works - [ ] File is <450 lines **Estimated Time**: 5 hours #### 6.3.2 Write unit tests for HierarchyManager.ts **Status**: ⏸️ Pending **Dependencies**: 6.3.1 **Target Size**: <400 lines **Test Cases**: - Parent-child relationships - Ancestry traversal - Descendant traversal - Subtree extraction - Cycle detection - Move operations - Depth calculation **Acceptance Criteria**: - [ ] 100% code coverage - [ ] All hierarchy paths tested - [ ] Test file is <400 lines **Estimated Time**: 4.5 hours ### 6.4 Analytics Manager #### 6.4.1 Create AnalyticsManager.ts with stats and validation **Status**: ⏸️ Pending **Dependencies**: 6.3.2 **Target Size**: <300 lines **Content**: - `getGraphStats(): Promise<GraphStats>` - `validateGraph(): Promise<ValidationReport>` - Statistics calculations - Validation checks **Acceptance Criteria**: - [ ] Stats calculation works - [ ] Validation comprehensive - [ ] File is <300 lines **Estimated Time**: 3.5 hours #### 6.4.2 Write unit tests for AnalyticsManager.ts **Status**: ⏸️ Pending **Dependencies**: 6.4.1 **Target Size**: <300 lines **Test Cases**: - Stats on empty graph - Stats on populated graph - Validation errors detection - Validation warnings - Orphaned relations - Isolated entities **Acceptance Criteria**: - [ ] 100% code coverage - [ ] All stats verified - [ ] Test file is <300 lines **Estimated Time**: 3 hours ### 6.5 Compression Manager #### 6.5.1 Create CompressionManager.ts with deduplication logic **Status**: ⏸️ Pending **Dependencies**: 6.4.2 **Target Size**: <400 lines **Content**: - `findDuplicates(threshold?): Promise<string[][]>` - `mergeEntities(entityNames, targetName?): Promise<Entity>` - `compressGraph(threshold?, dryRun?): Promise<CompressionResult>` - Similarity calculation **Acceptance Criteria**: - [ ] Duplicate detection works - [ ] Entity merging preserves data - [ ] Dry run mode works - [ ] File is <400 lines **Estimated Time**: 4.5 hours #### 6.5.2 Write unit tests for CompressionManager.ts **Status**: ⏸️ Pending **Dependencies**: 6.5.1 **Target Size**: <350 lines **Test Cases**: - Duplicate detection - Similarity thresholds - Entity merging - Observation preservation - Tag merging - Dry run vs real run - Compression results **Acceptance Criteria**: - [ ] 100% code coverage - [ ] Merging logic verified - [ ] Test file is <350 lines **Estimated Time**: 3.5 hours ### 6.6 Archive Manager #### 6.6.1 Create ArchiveManager.ts with archiving criteria **Status**: ⏸️ Pending **Dependencies**: 6.5.2 **Target Size**: <150 lines **Content**: - `archiveEntities(criteria, dryRun?): Promise<ImportResult>` - Age-based archiving - Importance-based archiving - Tag-based archiving - Multiple criteria (OR logic) **Acceptance Criteria**: - [ ] All criteria work - [ ] OR logic implemented - [ ] Dry run mode works - [ ] File is <150 lines **Estimated Time**: 2 hours #### 6.6.2 Write unit tests for ArchiveManager.ts **Status**: ⏸️ Pending **Dependencies**: 6.6.1 **Target Size**: <250 lines **Test Cases**: - Archive by age - Archive by importance - Archive by tags - Combined criteria - Dry run mode - Archive results **Acceptance Criteria**: - [ ] 100% code coverage - [ ] All criteria tested - [ ] Test file is <250 lines **Estimated Time**: 2.5 hours ### 6.7 Import/Export Manager #### 6.7.1 Create import-export/ subdirectory structure **Status**: ⏸️ Pending **Dependencies**: 6.6.2 **Estimated Time**: 15 minutes #### 6.7.2 Create ImportExportManager.ts orchestrator **Status**: ⏸️ Pending **Dependencies**: 6.7.1 **Target Size**: <150 lines **Content**: - `exportGraph(format, filter?): Promise<string>` - `importGraph(format, data, strategy?, dryRun?): Promise<ImportResult>` - Delegates to format-specific handlers **Acceptance Criteria**: - [ ] Orchestration works - [ ] All formats supported - [ ] File is <150 lines **Estimated Time**: 2 hours #### 6.7.3 Create ExportManager.ts **Status**: ⏸️ Pending **Dependencies**: 6.7.2 **Target Size**: <200 lines **Content**: - Orchestrates exports - Applies filters - Delegates to exporters **Acceptance Criteria**: - [ ] Filter logic works - [ ] Delegates correctly - [ ] File is <200 lines **Estimated Time**: 2 hours #### 6.7.4 Create ImportManager.ts **Status**: ⏸️ Pending **Dependencies**: 6.7.3 **Target Size**: <200 lines **Content**: - Orchestrates imports - Handles merge strategies - Validates data **Acceptance Criteria**: - [ ] All merge strategies work - [ ] Validation in place - [ ] File is <200 lines **Estimated Time**: 2 hours #### 6.7.5 Create formats/JSONExporter.ts **Status**: ⏸️ Pending **Dependencies**: 6.7.4 **Target Size**: <100 lines **Estimated Time**: 1 hour #### 6.7.6 Create formats/JSONImporter.ts **Status**: ⏸️ Pending **Dependencies**: 6.7.5 **Target Size**: <100 lines **Estimated Time**: 1 hour #### 6.7.7 Write tests for JSON import/export **Status**: ⏸️ Pending **Dependencies**: 6.7.6 **Target Size**: <200 lines **Estimated Time**: 1.5 hours #### 6.7.8 Create formats/CSVExporter.ts **Status**: ⏸️ Pending **Dependencies**: 6.7.7 **Target Size**: <150 lines **Estimated Time**: 2 hours #### 6.7.9 Create formats/CSVImporter.ts **Status**: ⏸️ Pending **Dependencies**: 6.7.8 **Target Size**: <200 lines **Estimated Time**: 2.5 hours #### 6.7.10 Write tests for CSV import/export **Status**: ⏸️ Pending **Dependencies**: 6.7.9 **Target Size**: <250 lines **Estimated Time**: 2 hours #### 6.7.11 Create formats/GraphMLExporter.ts **Status**: ⏸️ Pending **Dependencies**: 6.7.10 **Target Size**: <200 lines **Estimated Time**: 2.5 hours #### 6.7.12 Create formats/GraphMLImporter.ts **Status**: ⏸️ Pending **Dependencies**: 6.7.11 **Target Size**: <200 lines **Estimated Time**: 2.5 hours #### 6.7.13 Write tests for GraphML import/export **Status**: ⏸️ Pending **Dependencies**: 6.7.12 **Target Size**: <250 lines **Estimated Time**: 2 hours #### 6.7.14 Create formats/GEXFExporter.ts **Status**: ⏸️ Pending **Dependencies**: 6.7.13 **Target Size**: <200 lines **Estimated Time**: 2.5 hours #### 6.7.15 Write tests for GEXF export **Status**: ⏸️ Pending **Dependencies**: 6.7.14 **Target Size**: <200 lines **Estimated Time**: 1.5 hours #### 6.7.16 Create formats/DOTExporter.ts **Status**: ⏸️ Pending **Dependencies**: 6.7.15 **Target Size**: <150 lines **Estimated Time**: 2 hours #### 6.7.17 Write tests for DOT export **Status**: ⏸️ Pending **Dependencies**: 6.7.16 **Target Size**: <150 lines **Estimated Time**: 1.5 hours #### 6.7.18 Create formats/MarkdownExporter.ts **Status**: ⏸️ Pending **Dependencies**: 6.7.17 **Target Size**: <150 lines **Estimated Time**: 1.5 hours #### 6.7.19 Write tests for Markdown export **Status**: ⏸️ Pending **Dependencies**: 6.7.18 **Target Size**: <150 lines **Estimated Time**: 1.5 hours #### 6.7.20 Create formats/MermaidExporter.ts **Status**: ⏸️ Pending **Dependencies**: 6.7.19 **Target Size**: <150 lines **Estimated Time**: 2 hours #### 6.7.21 Write tests for Mermaid export **Status**: ⏸️ Pending **Dependencies**: 6.7.20 **Target Size**: <150 lines **Estimated Time**: 1.5 hours #### 6.7.22 Write integration tests for import/export **Status**: ⏸️ Pending **Dependencies**: 6.7.21 **Target Size**: <400 lines **Estimated Time**: 3 hours #### 6.7.23 Write integration tests for hierarchy operations **Status**: ⏸️ Pending **Dependencies**: 6.7.22 **Target Size**: <350 lines **Estimated Time**: 3 hours **Phase 6 Total Time**: ~75 hours --- ## Phase 7: Extract MCP Layer (Week 6) **Goal**: Separate API definitions from business logic ### 7.1 Server Setup #### 7.1.1 Create mcp/server.ts with server initialization **Status**: ⏸️ Pending **Dependencies**: 6.7.23 **Target Size**: <100 lines **Content**: - `createServer(knowledgeGraphManager): Promise<Server>` - Server configuration - Request handler setup **Acceptance Criteria**: - [ ] Server initialization extracted - [ ] Clean separation - [ ] File is <100 lines **Estimated Time**: 1.5 hours ### 7.2 Tool Definitions #### 7.2.1 Create mcp/tools/entity.tools.ts **Status**: ⏸️ Pending **Dependencies**: 7.1.1 **Target Size**: <150 lines **Content**: Tool schemas for entity operations **Estimated Time**: 2 hours #### 7.2.2 Create mcp/tools/search.tools.ts **Status**: ⏸️ Pending **Dependencies**: 7.2.1 **Target Size**: <250 lines **Content**: Tool schemas for search operations **Estimated Time**: 3 hours #### 7.2.3 Create mcp/tools/tag.tools.ts **Status**: ⏸️ Pending **Dependencies**: 7.2.2 **Target Size**: <300 lines **Content**: Tool schemas for tag operations **Estimated Time**: 3.5 hours #### 7.2.4 Create mcp/tools/hierarchy.tools.ts **Status**: ⏸️ Pending **Dependencies**: 7.2.3 **Target Size**: <250 lines **Content**: Tool schemas for hierarchy operations **Estimated Time**: 3 hours #### 7.2.5 Create mcp/tools/analytics.tools.ts **Status**: ⏸️ Pending **Dependencies**: 7.2.4 **Target Size**: <100 lines **Content**: Tool schemas for analytics operations **Estimated Time**: 1.5 hours #### 7.2.6 Create mcp/tools/import-export.tools.ts **Status**: ⏸️ Pending **Dependencies**: 7.2.5 **Target Size**: <250 lines **Content**: Tool schemas for import/export operations **Estimated Time**: 3 hours #### 7.2.7 Create mcp/tools/index.ts tool registry **Status**: ⏸️ Pending **Dependencies**: 7.2.6 **Target Size**: <100 lines **Content**: Aggregates all tool definitions **Estimated Time**: 1 hour ### 7.3 Tool Handlers #### 7.3.1 Create mcp/handlers/entity.handlers.ts **Status**: ⏸️ Pending **Dependencies**: 7.2.7 **Target Size**: <150 lines **Content**: Handlers for entity tools **Estimated Time**: 2 hours #### 7.3.2 Create mcp/handlers/search.handlers.ts **Status**: ⏸️ Pending **Dependencies**: 7.3.1 **Target Size**: <250 lines **Content**: Handlers for search tools **Estimated Time**: 3 hours #### 7.3.3 Create mcp/handlers/tag.handlers.ts **Status**: ⏸️ Pending **Dependencies**: 7.3.2 **Target Size**: <250 lines **Content**: Handlers for tag tools **Estimated Time**: 3 hours #### 7.3.4 Create mcp/handlers/hierarchy.handlers.ts **Status**: ⏸️ Pending **Dependencies**: 7.3.3 **Target Size**: <200 lines **Content**: Handlers for hierarchy tools **Estimated Time**: 2.5 hours #### 7.3.5 Create mcp/handlers/analytics.handlers.ts **Status**: ⏸️ Pending **Dependencies**: 7.3.4 **Target Size**: <100 lines **Content**: Handlers for analytics tools **Estimated Time**: 1.5 hours #### 7.3.6 Create mcp/handlers/import-export.handlers.ts **Status**: ⏸️ Pending **Dependencies**: 7.3.5 **Target Size**: <200 lines **Content**: Handlers for import/export tools **Estimated Time**: 2.5 hours #### 7.3.7 Create mcp/handlers/index.ts handler registry **Status**: ⏸️ Pending **Dependencies**: 7.3.6 **Target Size**: <150 lines **Content**: Routing logic for all handlers **Estimated Time**: 2 hours ### 7.4 Main Entry Point #### 7.4.1 Refactor main index.ts to minimal bootstrapping **Status**: ⏸️ Pending **Dependencies**: 7.3.7 **Target Size**: <50 lines **Content**: - Import and wire up components - Main function - Error handling **Acceptance Criteria**: - [ ] Entry point is minimal - [ ] All components wired correctly - [ ] File is <50 lines - [ ] Backward compatibility maintained **Estimated Time**: 2 hours **Phase 7 Total Time**: ~37 hours --- ## Phase 8: Final Integration & Testing (Week 7) **Goal**: Ensure everything works together ### 8.1 Integration Testing #### 8.1.1 Run all existing tests to verify backward compatibility **Status**: ⏸️ Pending **Dependencies**: 7.4.1 **Acceptance Criteria**: - [ ] All existing tests pass - [ ] No regressions detected **Estimated Time**: 1 hour #### 8.1.2 Write end-to-end tests for all 45 tools **Status**: ⏸️ Pending **Dependencies**: 8.1.1 **Target Size**: <400 lines (split across files) **Test Cases**: - Each tool tested end-to-end - Tool interactions - Error handling **Acceptance Criteria**: - [ ] All 45 tools tested - [ ] Real MCP server used - [ ] Files are <400 lines each **Estimated Time**: 6 hours ### 8.2 Performance Testing #### 8.2.1 Write performance benchmarks for search operations **Status**: ⏸️ Pending **Dependencies**: 8.1.2 **Target Size**: <300 lines **Benchmarks**: - Basic search performance - Ranked search performance - Boolean search performance - Fuzzy search performance - Large dataset handling **Acceptance Criteria**: - [ ] Baseline established - [ ] Performance within 5% of original - [ ] File is <300 lines **Estimated Time**: 3 hours #### 8.2.2 Write large graph performance tests **Status**: ⏸️ Pending **Dependencies**: 8.2.1 **Target Size**: <250 lines **Test Cases**: - 1,000 entities - 10,000 entities - Complex relationships - Search performance - Memory usage **Acceptance Criteria**: - [ ] Large datasets handled - [ ] No performance degradation - [ ] File is <250 lines **Estimated Time**: 3 hours ### 8.3 Code Quality #### 8.3.1 Run test coverage report and ensure >85% coverage **Status**: ⏸️ Pending **Dependencies**: 8.2.2 **Acceptance Criteria**: - [ ] Coverage >85% - [ ] All critical paths covered - [ ] Report generated **Estimated Time**: 2 hours #### 8.3.2 Verify all files are under size limits **Status**: ⏸️ Pending **Dependencies**: 8.3.1 **Acceptance Criteria**: - [ ] All implementation files <500 lines - [ ] All test files <400 lines - [ ] Automated check added **Estimated Time**: 1 hour #### 8.3.3 Run ESLint and fix all errors **Status**: ⏸️ Pending **Dependencies**: 8.3.2 **Acceptance Criteria**: - [ ] Zero ESLint errors - [ ] Code style consistent - [ ] Prettier applied **Estimated Time**: 2 hours #### 8.3.4 Run TypeScript strict mode checks **Status**: ⏸️ Pending **Dependencies**: 8.3.3 **Acceptance Criteria**: - [ ] Zero TypeScript errors - [ ] Strict mode enabled - [ ] No any types (where possible) **Estimated Time**: 2 hours ### 8.4 Documentation #### 8.4.1 Update README.md with new architecture documentation **Status**: ⏸️ Pending **Dependencies**: 8.3.4 **Content**: - New architecture overview - Module descriptions - Import examples **Acceptance Criteria**: - [ ] README updated - [ ] Examples work - [ ] Clear and concise **Estimated Time**: 2.5 hours #### 8.4.2 Create ARCHITECTURE.md with module diagrams **Status**: ⏸️ Pending **Dependencies**: 8.4.1 **Content**: - Dependency graphs - Module interactions - Design patterns used **Acceptance Criteria**: - [ ] Architecture documented - [ ] Diagrams included - [ ] Design decisions explained **Estimated Time**: 3 hours #### 8.4.3 Create MIGRATION_GUIDE.md **Status**: ⏸️ Pending **Dependencies**: 8.4.2 **Content**: - Upgrade instructions - API changes (none expected) - New features **Acceptance Criteria**: - [ ] Migration path clear - [ ] Examples provided - [ ] Troubleshooting section **Estimated Time**: 2 hours #### 8.4.4 Update CHANGELOG.md **Status**: ⏸️ Pending **Dependencies**: 8.4.3 **Content**: - Refactoring details - New structure - Benefits **Acceptance Criteria**: - [ ] Changelog updated - [ ] Version 0.9.0 documented **Estimated Time**: 1 hour ### 8.5 Automation #### 8.5.1 Setup pre-commit hook for file size enforcement **Status**: ⏸️ Pending **Dependencies**: 8.4.4 **Content**: - Pre-commit script - File size checks - Auto-rejection **Acceptance Criteria**: - [ ] Hook installed - [ ] Size checks work - [ ] Clear error messages **Estimated Time**: 1.5 hours #### 8.5.2 Add CI/CD checks for file size limits **Status**: ⏸️ Pending **Dependencies**: 8.5.1 **Content**: - GitHub Actions workflow - File size validation - Automated checks **Acceptance Criteria**: - [ ] CI checks added - [ ] Failing builds on violations - [ ] Clear error messages **Estimated Time**: 2 hours ### 8.6 Release Preparation #### 8.6.1 Final code review of all refactored modules **Status**: ⏸️ Pending **Dependencies**: 8.5.2 **Review Items**: - Code quality - Test coverage - Documentation - Performance **Acceptance Criteria**: - [ ] All modules reviewed - [ ] Issues addressed - [ ] Approval obtained **Estimated Time**: 4 hours #### 8.6.2 Create release notes for v0.9.0 **Status**: ⏸️ Pending **Dependencies**: 8.6.1 **Content**: - Refactoring highlights - New structure benefits - Migration instructions **Acceptance Criteria**: - [ ] Release notes complete - [ ] Clear and compelling - [ ] Examples included **Estimated Time**: 2 hours #### 8.6.3 Version bump to 0.9.0 in package.json **Status**: ⏸️ Pending **Dependencies**: 8.6.2 **Changes**: - Update version - Update dependencies - Final build test **Acceptance Criteria**: - [ ] Version bumped - [ ] Build succeeds - [ ] Ready to publish **Estimated Time**: 30 minutes **Phase 8 Total Time**: ~38 hours --- ## Summary ### Total Effort by Phase | Phase | Focus | Tasks | Estimated Hours | |-------|-------|-------|----------------| | 1 | Foundation | 7 | 4.5 | | 2 | Utilities | 10 | 12 | | 3 | Storage | 3 | 6 | | 4 | Core Managers | 8 | 20 | | 5 | Search Module | 14 | 40 | | 6 | Feature Managers | 52 | 75 | | 7 | MCP Layer | 15 | 37 | | 8 | Integration & Testing | 16 | 38 | | **Total** | **All Phases** | **110** | **232.5** | ### Critical Path 1. Phase 1 → Phase 2 → Phase 3 (Foundation) 2. Phase 4 (Core) depends on Phase 3 3. Phase 5 (Search) depends on Phase 4 4. Phase 6 (Features) depends on Phase 5 5. Phase 7 (MCP) depends on Phase 6 6. Phase 8 (Testing) depends on Phase 7 ### Risk Mitigation - Each task has clear acceptance criteria - Tests written immediately after implementation - Backward compatibility verified at each phase - File size constraints enforced throughout ### Success Metrics - ✅ All 110 tasks completed - ✅ Test coverage >85% - ✅ All files <500 lines (implementation) or <400 lines (tests) - ✅ Zero regressions - ✅ Performance within 5% of baseline - ✅ Full documentation --- ## Notes ### Using This Document 1. Check off tasks as completed 2. Update status indicators (⏸️ → 🔄 → ✅) 3. Track time spent vs estimated 4. Note any blockers or issues 5. Update dependencies if they change ### Parallel Work Opportunities - Phases can have multiple tasks in progress - Utilities (Phase 2) can be parallelized - Format exporters/importers can be done in parallel - Documentation can be written during implementation ### Quality Gates Before proceeding to next phase: - [ ] All tasks completed - [ ] All tests passing - [ ] Code reviewed - [ ] Documentation updated - [ ] No regressions --- **Document Version**: 1.0 **Last Updated**: 2025-11-23 **Status**: Ready for Implementation