@danielsimonjr/memory-mcp 12.5.2 → 12.7.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (159) hide show
  1. package/README.md +158 -14
  2. package/dist/core/EntityManager.d.ts +263 -0
  3. package/dist/core/EntityManager.d.ts.map +1 -0
  4. package/dist/core/EntityManager.js +478 -0
  5. package/dist/core/GraphStorage.d.ts +344 -0
  6. package/dist/core/GraphStorage.d.ts.map +1 -0
  7. package/dist/core/GraphStorage.js +708 -0
  8. package/dist/core/GraphTraversal.d.ts +136 -0
  9. package/dist/core/GraphTraversal.d.ts.map +1 -0
  10. package/dist/core/GraphTraversal.js +556 -0
  11. package/dist/core/HierarchyManager.d.ts +111 -0
  12. package/dist/core/HierarchyManager.d.ts.map +1 -0
  13. package/dist/core/HierarchyManager.js +224 -0
  14. package/dist/core/ManagerContext.d.ts +72 -0
  15. package/dist/core/ManagerContext.d.ts.map +1 -0
  16. package/dist/core/ManagerContext.js +118 -0
  17. package/dist/core/ObservationManager.d.ts +85 -0
  18. package/dist/core/ObservationManager.d.ts.map +1 -0
  19. package/dist/core/ObservationManager.js +123 -0
  20. package/dist/core/RelationManager.d.ts +131 -0
  21. package/dist/core/RelationManager.d.ts.map +1 -0
  22. package/dist/core/RelationManager.js +210 -0
  23. package/dist/core/SQLiteStorage.d.ts +354 -0
  24. package/dist/core/SQLiteStorage.d.ts.map +1 -0
  25. package/dist/core/SQLiteStorage.js +917 -0
  26. package/dist/core/StorageFactory.d.ts +45 -0
  27. package/dist/core/StorageFactory.d.ts.map +1 -0
  28. package/dist/core/StorageFactory.js +64 -0
  29. package/dist/core/TransactionManager.d.ts +259 -0
  30. package/dist/core/TransactionManager.d.ts.map +1 -0
  31. package/dist/core/TransactionManager.js +392 -0
  32. package/dist/core/index.d.ts +16 -0
  33. package/dist/core/index.d.ts.map +1 -0
  34. package/dist/core/index.js +17 -0
  35. package/dist/features/AnalyticsManager.d.ts +44 -0
  36. package/dist/features/AnalyticsManager.d.ts.map +1 -0
  37. package/dist/features/AnalyticsManager.js +223 -0
  38. package/dist/features/ArchiveManager.d.ts +121 -0
  39. package/dist/features/ArchiveManager.d.ts.map +1 -0
  40. package/dist/features/ArchiveManager.js +240 -0
  41. package/dist/features/CompressionManager.d.ts +109 -0
  42. package/dist/features/CompressionManager.d.ts.map +1 -0
  43. package/dist/features/CompressionManager.js +404 -0
  44. package/dist/features/IOManager.d.ts +221 -0
  45. package/dist/features/IOManager.d.ts.map +1 -0
  46. package/dist/features/IOManager.js +997 -0
  47. package/dist/features/StreamingExporter.d.ts +105 -0
  48. package/dist/features/StreamingExporter.d.ts.map +1 -0
  49. package/dist/features/StreamingExporter.js +150 -0
  50. package/dist/features/TagManager.d.ts +147 -0
  51. package/dist/features/TagManager.d.ts.map +1 -0
  52. package/dist/features/TagManager.js +210 -0
  53. package/dist/features/index.d.ts +12 -0
  54. package/dist/features/index.d.ts.map +1 -0
  55. package/dist/features/index.js +11 -0
  56. package/dist/index.js +8 -2
  57. package/dist/search/BasicSearch.d.ts +51 -0
  58. package/dist/search/BasicSearch.d.ts.map +1 -0
  59. package/dist/search/BasicSearch.js +137 -0
  60. package/dist/search/BooleanSearch.d.ts +98 -0
  61. package/dist/search/BooleanSearch.d.ts.map +1 -0
  62. package/dist/search/BooleanSearch.js +430 -0
  63. package/dist/search/EmbeddingService.d.ts +178 -0
  64. package/dist/search/EmbeddingService.d.ts.map +1 -0
  65. package/dist/search/EmbeddingService.js +358 -0
  66. package/dist/search/FuzzySearch.d.ts +118 -0
  67. package/dist/search/FuzzySearch.d.ts.map +1 -0
  68. package/dist/search/FuzzySearch.js +312 -0
  69. package/dist/search/RankedSearch.d.ts +71 -0
  70. package/dist/search/RankedSearch.d.ts.map +1 -0
  71. package/dist/search/RankedSearch.js +238 -0
  72. package/dist/search/SavedSearchManager.d.ts +79 -0
  73. package/dist/search/SavedSearchManager.d.ts.map +1 -0
  74. package/dist/search/SavedSearchManager.js +145 -0
  75. package/dist/search/SearchFilterChain.d.ts +120 -0
  76. package/dist/search/SearchFilterChain.d.ts.map +1 -0
  77. package/dist/search/SearchFilterChain.js +185 -0
  78. package/dist/search/SearchManager.d.ts +285 -0
  79. package/dist/search/SearchManager.d.ts.map +1 -0
  80. package/dist/search/SearchManager.js +338 -0
  81. package/dist/search/SearchSuggestions.d.ts +27 -0
  82. package/dist/search/SearchSuggestions.d.ts.map +1 -0
  83. package/dist/search/SearchSuggestions.js +57 -0
  84. package/dist/search/SemanticSearch.d.ts +146 -0
  85. package/dist/search/SemanticSearch.d.ts.map +1 -0
  86. package/dist/search/SemanticSearch.js +313 -0
  87. package/dist/search/TFIDFIndexManager.d.ts +63 -0
  88. package/dist/search/TFIDFIndexManager.d.ts.map +1 -0
  89. package/dist/search/TFIDFIndexManager.js +215 -0
  90. package/dist/search/VectorStore.d.ts +235 -0
  91. package/dist/search/VectorStore.d.ts.map +1 -0
  92. package/dist/search/VectorStore.js +311 -0
  93. package/dist/search/index.d.ts +18 -0
  94. package/dist/search/index.d.ts.map +1 -0
  95. package/dist/search/index.js +21 -0
  96. package/dist/server/MCPServer.d.ts.map +1 -1
  97. package/dist/server/toolDefinitions.d.ts +1 -1
  98. package/dist/server/toolDefinitions.d.ts.map +1 -1
  99. package/dist/server/toolDefinitions.js +254 -2
  100. package/dist/server/toolHandlers.d.ts.map +1 -1
  101. package/dist/server/toolHandlers.js +241 -25
  102. package/dist/types/index.d.ts +13 -0
  103. package/dist/types/index.d.ts.map +1 -0
  104. package/dist/types/index.js +12 -0
  105. package/dist/types/types.d.ts +1234 -0
  106. package/dist/types/types.d.ts.map +1 -0
  107. package/dist/types/types.js +9 -0
  108. package/dist/utils/compressedCache.d.ts +192 -0
  109. package/dist/utils/compressedCache.d.ts.map +1 -0
  110. package/dist/utils/compressedCache.js +309 -0
  111. package/dist/utils/compressionUtil.d.ts +214 -0
  112. package/dist/utils/compressionUtil.d.ts.map +1 -0
  113. package/dist/utils/compressionUtil.js +247 -0
  114. package/dist/utils/constants.d.ts +245 -0
  115. package/dist/utils/constants.d.ts.map +1 -0
  116. package/dist/utils/constants.js +252 -0
  117. package/dist/utils/entityUtils.d.ts +321 -0
  118. package/dist/utils/entityUtils.d.ts.map +1 -0
  119. package/dist/utils/entityUtils.js +538 -0
  120. package/dist/utils/errors.d.ts +77 -0
  121. package/dist/utils/errors.d.ts.map +1 -0
  122. package/dist/utils/errors.js +121 -0
  123. package/dist/utils/formatters.d.ts +145 -0
  124. package/dist/utils/formatters.d.ts.map +1 -0
  125. package/dist/utils/formatters.js +132 -0
  126. package/dist/utils/index.d.ts +22 -0
  127. package/dist/utils/index.d.ts.map +1 -0
  128. package/dist/utils/index.js +75 -0
  129. package/dist/utils/indexes.d.ts +270 -0
  130. package/dist/utils/indexes.d.ts.map +1 -0
  131. package/dist/utils/indexes.js +526 -0
  132. package/dist/utils/logger.d.ts +24 -0
  133. package/dist/utils/logger.d.ts.map +1 -0
  134. package/dist/utils/logger.js +33 -0
  135. package/dist/utils/parallelUtils.d.ts +72 -0
  136. package/dist/utils/parallelUtils.d.ts.map +1 -0
  137. package/dist/utils/parallelUtils.js +169 -0
  138. package/dist/utils/schemas.d.ts +374 -0
  139. package/dist/utils/schemas.d.ts.map +1 -0
  140. package/dist/utils/schemas.js +484 -0
  141. package/dist/utils/searchAlgorithms.d.ts +99 -0
  142. package/dist/utils/searchAlgorithms.d.ts.map +1 -0
  143. package/dist/utils/searchAlgorithms.js +167 -0
  144. package/dist/utils/searchCache.d.ts +108 -0
  145. package/dist/utils/searchCache.d.ts.map +1 -0
  146. package/dist/utils/searchCache.js +209 -0
  147. package/dist/utils/taskScheduler.d.ts +290 -0
  148. package/dist/utils/taskScheduler.d.ts.map +1 -0
  149. package/dist/utils/taskScheduler.js +466 -0
  150. package/dist/workers/WorkerPool.d.ts +81 -0
  151. package/dist/workers/WorkerPool.d.ts.map +1 -0
  152. package/dist/workers/WorkerPool.js +121 -0
  153. package/dist/workers/index.d.ts +12 -0
  154. package/dist/workers/index.d.ts.map +1 -0
  155. package/dist/workers/index.js +9 -0
  156. package/dist/workers/levenshteinWorker.d.ts +60 -0
  157. package/dist/workers/levenshteinWorker.d.ts.map +1 -0
  158. package/dist/workers/levenshteinWorker.js +98 -0
  159. package/package.json +7 -7
@@ -0,0 +1,105 @@
1
+ /**
2
+ * Streaming Export Module
3
+ *
4
+ * Provides streaming export functionality for large knowledge graphs to avoid
5
+ * loading entire graphs into memory. Supports JSONL and CSV formats with
6
+ * incremental writing to disk.
7
+ *
8
+ * @module features/StreamingExporter
9
+ */
10
+ import type { ReadonlyKnowledgeGraph } from '../types/types.js';
11
+ /**
12
+ * Result summary from a streaming export operation.
13
+ *
14
+ * Provides statistics about the export including bytes written,
15
+ * entity/relation counts, and duration.
16
+ *
17
+ * @example
18
+ * ```typescript
19
+ * const result: StreamResult = {
20
+ * bytesWritten: 125000,
21
+ * entitiesWritten: 150,
22
+ * relationsWritten: 320,
23
+ * durationMs: 1250
24
+ * };
25
+ * ```
26
+ */
27
+ export interface StreamResult {
28
+ /** Total bytes written to the output file */
29
+ bytesWritten: number;
30
+ /** Number of entities written */
31
+ entitiesWritten: number;
32
+ /** Number of relations written */
33
+ relationsWritten: number;
34
+ /** Duration of the export operation in milliseconds */
35
+ durationMs: number;
36
+ }
37
+ /**
38
+ * Streaming exporter for knowledge graphs.
39
+ *
40
+ * Provides memory-efficient export by streaming data directly to files
41
+ * instead of building large strings in memory. Supports JSONL and CSV formats.
42
+ *
43
+ * @example
44
+ * ```typescript
45
+ * const exporter = new StreamingExporter('/path/to/output.jsonl');
46
+ * const result = await exporter.streamJSONL(graph);
47
+ * console.log(`Wrote ${result.bytesWritten} bytes in ${result.durationMs}ms`);
48
+ * ```
49
+ */
50
+ export declare class StreamingExporter {
51
+ private readonly filePath;
52
+ /**
53
+ * Create a new streaming exporter.
54
+ *
55
+ * @param filePath - Path to the output file
56
+ */
57
+ constructor(filePath: string);
58
+ /**
59
+ * Stream a knowledge graph to JSONL format.
60
+ *
61
+ * Each entity and relation is written as a separate JSON line.
62
+ * Memory usage is constant regardless of graph size.
63
+ *
64
+ * @param graph - The knowledge graph to export
65
+ * @returns Promise resolving to export statistics
66
+ *
67
+ * @example
68
+ * ```typescript
69
+ * const exporter = new StreamingExporter('export.jsonl');
70
+ * const result = await exporter.streamJSONL(graph);
71
+ * console.log(`Exported ${result.entitiesWritten} entities`);
72
+ * ```
73
+ */
74
+ streamJSONL(graph: ReadonlyKnowledgeGraph): Promise<StreamResult>;
75
+ /**
76
+ * Stream a knowledge graph to CSV format.
77
+ *
78
+ * Exports entities as CSV rows with proper escaping for special characters.
79
+ * Header row includes: name, type, observations, tags, importance, createdAt, lastModified.
80
+ *
81
+ * @param graph - The knowledge graph to export
82
+ * @returns Promise resolving to export statistics
83
+ *
84
+ * @example
85
+ * ```typescript
86
+ * const exporter = new StreamingExporter('export.csv');
87
+ * const result = await exporter.streamCSV(graph);
88
+ * console.log(`Exported ${result.entitiesWritten} entities as CSV`);
89
+ * ```
90
+ */
91
+ streamCSV(graph: ReadonlyKnowledgeGraph): Promise<StreamResult>;
92
+ /**
93
+ * Convert an entity to a CSV row with proper escaping.
94
+ *
95
+ * Escapes double quotes by doubling them and wraps fields in quotes.
96
+ * Arrays (observations, tags) are joined with semicolons.
97
+ *
98
+ * @param entity - The entity to convert
99
+ * @returns CSV row string (without trailing newline)
100
+ *
101
+ * @private
102
+ */
103
+ private entityToCSVRow;
104
+ }
105
+ //# sourceMappingURL=StreamingExporter.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"StreamingExporter.d.ts","sourceRoot":"","sources":["../../src/features/StreamingExporter.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAGH,OAAO,KAAK,EAAU,sBAAsB,EAAE,MAAM,mBAAmB,CAAC;AAExE;;;;;;;;;;;;;;;GAeG;AACH,MAAM,WAAW,YAAY;IAC3B,6CAA6C;IAC7C,YAAY,EAAE,MAAM,CAAC;IAErB,iCAAiC;IACjC,eAAe,EAAE,MAAM,CAAC;IAExB,kCAAkC;IAClC,gBAAgB,EAAE,MAAM,CAAC;IAEzB,uDAAuD;IACvD,UAAU,EAAE,MAAM,CAAC;CACpB;AAED;;;;;;;;;;;;GAYG;AACH,qBAAa,iBAAiB;IAMhB,OAAO,CAAC,QAAQ,CAAC,QAAQ;IALrC;;;;OAIG;gBAC0B,QAAQ,EAAE,MAAM;IAE7C;;;;;;;;;;;;;;;OAeG;IACG,WAAW,CAAC,KAAK,EAAE,sBAAsB,GAAG,OAAO,CAAC,YAAY,CAAC;IAsCvE;;;;;;;;;;;;;;;OAeG;IACG,SAAS,CAAC,KAAK,EAAE,sBAAsB,GAAG,OAAO,CAAC,YAAY,CAAC;IAmCrE;;;;;;;;;;OAUG;IACH,OAAO,CAAC,cAAc;CAcvB"}
@@ -0,0 +1,150 @@
1
+ /**
2
+ * Streaming Export Module
3
+ *
4
+ * Provides streaming export functionality for large knowledge graphs to avoid
5
+ * loading entire graphs into memory. Supports JSONL and CSV formats with
6
+ * incremental writing to disk.
7
+ *
8
+ * @module features/StreamingExporter
9
+ */
10
+ import { createWriteStream } from 'fs';
11
+ /**
12
+ * Streaming exporter for knowledge graphs.
13
+ *
14
+ * Provides memory-efficient export by streaming data directly to files
15
+ * instead of building large strings in memory. Supports JSONL and CSV formats.
16
+ *
17
+ * @example
18
+ * ```typescript
19
+ * const exporter = new StreamingExporter('/path/to/output.jsonl');
20
+ * const result = await exporter.streamJSONL(graph);
21
+ * console.log(`Wrote ${result.bytesWritten} bytes in ${result.durationMs}ms`);
22
+ * ```
23
+ */
24
+ export class StreamingExporter {
25
+ filePath;
26
+ /**
27
+ * Create a new streaming exporter.
28
+ *
29
+ * @param filePath - Path to the output file
30
+ */
31
+ constructor(filePath) {
32
+ this.filePath = filePath;
33
+ }
34
+ /**
35
+ * Stream a knowledge graph to JSONL format.
36
+ *
37
+ * Each entity and relation is written as a separate JSON line.
38
+ * Memory usage is constant regardless of graph size.
39
+ *
40
+ * @param graph - The knowledge graph to export
41
+ * @returns Promise resolving to export statistics
42
+ *
43
+ * @example
44
+ * ```typescript
45
+ * const exporter = new StreamingExporter('export.jsonl');
46
+ * const result = await exporter.streamJSONL(graph);
47
+ * console.log(`Exported ${result.entitiesWritten} entities`);
48
+ * ```
49
+ */
50
+ async streamJSONL(graph) {
51
+ const start = Date.now();
52
+ let bytesWritten = 0;
53
+ let entitiesWritten = 0;
54
+ let relationsWritten = 0;
55
+ const writeStream = createWriteStream(this.filePath);
56
+ // Write entities
57
+ for (const entity of graph.entities) {
58
+ const line = JSON.stringify(entity) + '\n';
59
+ writeStream.write(line);
60
+ bytesWritten += Buffer.byteLength(line, 'utf-8');
61
+ entitiesWritten++;
62
+ }
63
+ // Write relations
64
+ for (const relation of graph.relations) {
65
+ const line = JSON.stringify(relation) + '\n';
66
+ writeStream.write(line);
67
+ bytesWritten += Buffer.byteLength(line, 'utf-8');
68
+ relationsWritten++;
69
+ }
70
+ // Wait for stream to finish
71
+ await new Promise((resolve, reject) => {
72
+ writeStream.end(() => resolve());
73
+ writeStream.on('error', reject);
74
+ });
75
+ return {
76
+ bytesWritten,
77
+ entitiesWritten,
78
+ relationsWritten,
79
+ durationMs: Date.now() - start,
80
+ };
81
+ }
82
+ /**
83
+ * Stream a knowledge graph to CSV format.
84
+ *
85
+ * Exports entities as CSV rows with proper escaping for special characters.
86
+ * Header row includes: name, type, observations, tags, importance, createdAt, lastModified.
87
+ *
88
+ * @param graph - The knowledge graph to export
89
+ * @returns Promise resolving to export statistics
90
+ *
91
+ * @example
92
+ * ```typescript
93
+ * const exporter = new StreamingExporter('export.csv');
94
+ * const result = await exporter.streamCSV(graph);
95
+ * console.log(`Exported ${result.entitiesWritten} entities as CSV`);
96
+ * ```
97
+ */
98
+ async streamCSV(graph) {
99
+ const start = Date.now();
100
+ let bytesWritten = 0;
101
+ let entitiesWritten = 0;
102
+ const relationsWritten = 0; // CSV format doesn't export relations
103
+ const writeStream = createWriteStream(this.filePath);
104
+ // Write header
105
+ const header = 'name,type,observations,tags,importance,createdAt,lastModified\n';
106
+ writeStream.write(header);
107
+ bytesWritten += Buffer.byteLength(header, 'utf-8');
108
+ // Write entity rows
109
+ for (const entity of graph.entities) {
110
+ const row = this.entityToCSVRow(entity) + '\n';
111
+ writeStream.write(row);
112
+ bytesWritten += Buffer.byteLength(row, 'utf-8');
113
+ entitiesWritten++;
114
+ }
115
+ // Wait for stream to finish
116
+ await new Promise((resolve, reject) => {
117
+ writeStream.end(() => resolve());
118
+ writeStream.on('error', reject);
119
+ });
120
+ return {
121
+ bytesWritten,
122
+ entitiesWritten,
123
+ relationsWritten,
124
+ durationMs: Date.now() - start,
125
+ };
126
+ }
127
+ /**
128
+ * Convert an entity to a CSV row with proper escaping.
129
+ *
130
+ * Escapes double quotes by doubling them and wraps fields in quotes.
131
+ * Arrays (observations, tags) are joined with semicolons.
132
+ *
133
+ * @param entity - The entity to convert
134
+ * @returns CSV row string (without trailing newline)
135
+ *
136
+ * @private
137
+ */
138
+ entityToCSVRow(entity) {
139
+ const escape = (s) => `"${s.replace(/"/g, '""')}"`;
140
+ return [
141
+ escape(entity.name),
142
+ escape(entity.entityType),
143
+ escape(entity.observations.join('; ')),
144
+ escape((entity.tags ?? []).join('; ')),
145
+ entity.importance?.toString() ?? '',
146
+ entity.createdAt ?? '',
147
+ entity.lastModified ?? '',
148
+ ].join(',');
149
+ }
150
+ }
@@ -0,0 +1,147 @@
1
+ /**
2
+ * Tag Manager
3
+ *
4
+ * Manages tag aliases and canonical tag resolution.
5
+ *
6
+ * @module features/TagManager
7
+ */
8
+ import type { TagAlias } from '../types/index.js';
9
+ /**
10
+ * Manages tag alias system for synonym mapping.
11
+ */
12
+ export declare class TagManager {
13
+ private tagAliasesFilePath;
14
+ constructor(tagAliasesFilePath: string);
15
+ /**
16
+ * Load all tag aliases from JSONL file.
17
+ *
18
+ * @returns Array of tag aliases
19
+ */
20
+ private loadTagAliases;
21
+ /**
22
+ * Save tag aliases to JSONL file.
23
+ *
24
+ * @param aliases - Array of tag aliases
25
+ */
26
+ private saveTagAliases;
27
+ /**
28
+ * Resolve a tag through aliases to get its canonical form.
29
+ *
30
+ * This method follows the alias chain to find the canonical (main) tag name.
31
+ * All tags are normalized to lowercase for consistency.
32
+ * If the tag has no alias, it returns the tag itself as canonical.
33
+ *
34
+ * @param tag - Tag to resolve (can be alias or canonical)
35
+ * @returns Canonical tag name (lowercase)
36
+ *
37
+ * @example
38
+ * ```typescript
39
+ * const manager = new TagManager(tagAliasesPath);
40
+ *
41
+ * // Set up: assume "js" is aliased to "javascript"
42
+ * await manager.addTagAlias('js', 'javascript');
43
+ *
44
+ * // Resolve alias to canonical
45
+ * const canonical = await manager.resolveTag('js');
46
+ * console.log(canonical); // "javascript"
47
+ *
48
+ * // Resolve canonical tag (returns as-is)
49
+ * const unchanged = await manager.resolveTag('javascript');
50
+ * console.log(unchanged); // "javascript"
51
+ *
52
+ * // Resolve unknown tag (returns normalized)
53
+ * const unknown = await manager.resolveTag('PYTHON');
54
+ * console.log(unknown); // "python"
55
+ * ```
56
+ */
57
+ resolveTag(tag: string): Promise<string>;
58
+ /**
59
+ * Add a tag alias (synonym mapping).
60
+ *
61
+ * Creates a mapping from an alias (synonym) to a canonical (main) tag.
62
+ * This enables flexible tagging where users can use different terms
63
+ * that all resolve to the same canonical tag.
64
+ *
65
+ * Validation rules:
66
+ * - Prevents duplicate aliases (same alias can't map to different canonicals)
67
+ * - Prevents chained aliases (alias must point to canonical, not another alias)
68
+ * - All tags are normalized to lowercase
69
+ *
70
+ * @param alias - The alias/synonym (will be normalized to lowercase)
71
+ * @param canonical - The canonical (main) tag name (will be normalized to lowercase)
72
+ * @param description - Optional description explaining the alias relationship
73
+ * @returns Newly created TagAlias object with metadata
74
+ * @throws {Error} If alias already exists or would create chained aliases
75
+ *
76
+ * @example
77
+ * ```typescript
78
+ * const manager = new TagManager(tagAliasesPath);
79
+ *
80
+ * // Create simple alias
81
+ * await manager.addTagAlias('js', 'javascript', 'Common abbreviation');
82
+ *
83
+ * // Create multiple aliases for same canonical
84
+ * await manager.addTagAlias('py', 'python');
85
+ * await manager.addTagAlias('py3', 'python', 'Python 3.x');
86
+ *
87
+ * // Error: duplicate alias
88
+ * try {
89
+ * await manager.addTagAlias('js', 'ecmascript'); // Fails - 'js' already aliased
90
+ * } catch (error) {
91
+ * console.error('Alias already exists');
92
+ * }
93
+ *
94
+ * // Error: chained alias
95
+ * await manager.addTagAlias('js', 'javascript');
96
+ * try {
97
+ * await manager.addTagAlias('javascript', 'ecmascript'); // Fails - can't alias canonical
98
+ * } catch (error) {
99
+ * console.error('Cannot create chained aliases');
100
+ * }
101
+ * ```
102
+ */
103
+ addTagAlias(alias: string, canonical: string, description?: string): Promise<TagAlias>;
104
+ /**
105
+ * List all tag aliases.
106
+ *
107
+ * @returns Array of all tag aliases
108
+ */
109
+ listTagAliases(): Promise<TagAlias[]>;
110
+ /**
111
+ * Remove a tag alias.
112
+ *
113
+ * @param alias - Alias to remove
114
+ * @returns True if removed, false if not found
115
+ */
116
+ removeTagAlias(alias: string): Promise<boolean>;
117
+ /**
118
+ * Get all aliases (synonyms) for a canonical tag.
119
+ *
120
+ * Returns all alias names that resolve to the specified canonical tag.
121
+ * Useful for discovering alternative names users might use for a tag.
122
+ * The canonical tag name is normalized to lowercase.
123
+ *
124
+ * @param canonicalTag - Canonical tag name (will be normalized to lowercase)
125
+ * @returns Array of alias names (all lowercase)
126
+ *
127
+ * @example
128
+ * ```typescript
129
+ * const manager = new TagManager(tagAliasesPath);
130
+ *
131
+ * // Set up some aliases
132
+ * await manager.addTagAlias('js', 'javascript');
133
+ * await manager.addTagAlias('ecmascript', 'javascript');
134
+ * await manager.addTagAlias('es6', 'javascript');
135
+ *
136
+ * // Get all aliases for canonical tag
137
+ * const aliases = await manager.getAliasesForTag('javascript');
138
+ * console.log(aliases); // ['js', 'ecmascript', 'es6']
139
+ *
140
+ * // Empty array if no aliases
141
+ * const noAliases = await manager.getAliasesForTag('python');
142
+ * console.log(noAliases); // []
143
+ * ```
144
+ */
145
+ getAliasesForTag(canonicalTag: string): Promise<string[]>;
146
+ }
147
+ //# sourceMappingURL=TagManager.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"TagManager.d.ts","sourceRoot":"","sources":["../../src/features/TagManager.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAGH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,mBAAmB,CAAC;AAElD;;GAEG;AACH,qBAAa,UAAU;IACT,OAAO,CAAC,kBAAkB;gBAAlB,kBAAkB,EAAE,MAAM;IAE9C;;;;OAIG;YACW,cAAc;IAa5B;;;;OAIG;YACW,cAAc;IAK5B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA6BG;IACG,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAc9C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA4CG;IACG,WAAW,CAAC,KAAK,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,WAAW,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,QAAQ,CAAC;IA8B5F;;;;OAIG;IACG,cAAc,IAAI,OAAO,CAAC,QAAQ,EAAE,CAAC;IAI3C;;;;;OAKG;IACG,cAAc,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAcrD;;;;;;;;;;;;;;;;;;;;;;;;;;;OA2BG;IACG,gBAAgB,CAAC,YAAY,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC;CAKhE"}
@@ -0,0 +1,210 @@
1
+ /**
2
+ * Tag Manager
3
+ *
4
+ * Manages tag aliases and canonical tag resolution.
5
+ *
6
+ * @module features/TagManager
7
+ */
8
+ import * as fs from 'fs/promises';
9
+ /**
10
+ * Manages tag alias system for synonym mapping.
11
+ */
12
+ export class TagManager {
13
+ tagAliasesFilePath;
14
+ constructor(tagAliasesFilePath) {
15
+ this.tagAliasesFilePath = tagAliasesFilePath;
16
+ }
17
+ /**
18
+ * Load all tag aliases from JSONL file.
19
+ *
20
+ * @returns Array of tag aliases
21
+ */
22
+ async loadTagAliases() {
23
+ try {
24
+ const data = await fs.readFile(this.tagAliasesFilePath, 'utf-8');
25
+ const lines = data.split('\n').filter((line) => line.trim() !== '');
26
+ return lines.map((line) => JSON.parse(line));
27
+ }
28
+ catch (error) {
29
+ if (error instanceof Error && 'code' in error && error.code === 'ENOENT') {
30
+ return [];
31
+ }
32
+ throw error;
33
+ }
34
+ }
35
+ /**
36
+ * Save tag aliases to JSONL file.
37
+ *
38
+ * @param aliases - Array of tag aliases
39
+ */
40
+ async saveTagAliases(aliases) {
41
+ const lines = aliases.map(a => JSON.stringify(a));
42
+ await fs.writeFile(this.tagAliasesFilePath, lines.join('\n'));
43
+ }
44
+ /**
45
+ * Resolve a tag through aliases to get its canonical form.
46
+ *
47
+ * This method follows the alias chain to find the canonical (main) tag name.
48
+ * All tags are normalized to lowercase for consistency.
49
+ * If the tag has no alias, it returns the tag itself as canonical.
50
+ *
51
+ * @param tag - Tag to resolve (can be alias or canonical)
52
+ * @returns Canonical tag name (lowercase)
53
+ *
54
+ * @example
55
+ * ```typescript
56
+ * const manager = new TagManager(tagAliasesPath);
57
+ *
58
+ * // Set up: assume "js" is aliased to "javascript"
59
+ * await manager.addTagAlias('js', 'javascript');
60
+ *
61
+ * // Resolve alias to canonical
62
+ * const canonical = await manager.resolveTag('js');
63
+ * console.log(canonical); // "javascript"
64
+ *
65
+ * // Resolve canonical tag (returns as-is)
66
+ * const unchanged = await manager.resolveTag('javascript');
67
+ * console.log(unchanged); // "javascript"
68
+ *
69
+ * // Resolve unknown tag (returns normalized)
70
+ * const unknown = await manager.resolveTag('PYTHON');
71
+ * console.log(unknown); // "python"
72
+ * ```
73
+ */
74
+ async resolveTag(tag) {
75
+ const aliases = await this.loadTagAliases();
76
+ const normalized = tag.toLowerCase();
77
+ // Check if this tag is an alias
78
+ const alias = aliases.find(a => a.alias === normalized);
79
+ if (alias) {
80
+ return alias.canonical;
81
+ }
82
+ // Return as-is (might be canonical or unaliased tag)
83
+ return normalized;
84
+ }
85
+ /**
86
+ * Add a tag alias (synonym mapping).
87
+ *
88
+ * Creates a mapping from an alias (synonym) to a canonical (main) tag.
89
+ * This enables flexible tagging where users can use different terms
90
+ * that all resolve to the same canonical tag.
91
+ *
92
+ * Validation rules:
93
+ * - Prevents duplicate aliases (same alias can't map to different canonicals)
94
+ * - Prevents chained aliases (alias must point to canonical, not another alias)
95
+ * - All tags are normalized to lowercase
96
+ *
97
+ * @param alias - The alias/synonym (will be normalized to lowercase)
98
+ * @param canonical - The canonical (main) tag name (will be normalized to lowercase)
99
+ * @param description - Optional description explaining the alias relationship
100
+ * @returns Newly created TagAlias object with metadata
101
+ * @throws {Error} If alias already exists or would create chained aliases
102
+ *
103
+ * @example
104
+ * ```typescript
105
+ * const manager = new TagManager(tagAliasesPath);
106
+ *
107
+ * // Create simple alias
108
+ * await manager.addTagAlias('js', 'javascript', 'Common abbreviation');
109
+ *
110
+ * // Create multiple aliases for same canonical
111
+ * await manager.addTagAlias('py', 'python');
112
+ * await manager.addTagAlias('py3', 'python', 'Python 3.x');
113
+ *
114
+ * // Error: duplicate alias
115
+ * try {
116
+ * await manager.addTagAlias('js', 'ecmascript'); // Fails - 'js' already aliased
117
+ * } catch (error) {
118
+ * console.error('Alias already exists');
119
+ * }
120
+ *
121
+ * // Error: chained alias
122
+ * await manager.addTagAlias('js', 'javascript');
123
+ * try {
124
+ * await manager.addTagAlias('javascript', 'ecmascript'); // Fails - can't alias canonical
125
+ * } catch (error) {
126
+ * console.error('Cannot create chained aliases');
127
+ * }
128
+ * ```
129
+ */
130
+ async addTagAlias(alias, canonical, description) {
131
+ const aliases = await this.loadTagAliases();
132
+ const normalizedAlias = alias.toLowerCase();
133
+ const normalizedCanonical = canonical.toLowerCase();
134
+ // Check if alias already exists
135
+ if (aliases.some(a => a.alias === normalizedAlias)) {
136
+ throw new Error(`Tag alias "${alias}" already exists`);
137
+ }
138
+ // Prevent aliasing to another alias (aliases should point to canonical tags)
139
+ if (aliases.some(a => a.canonical === normalizedAlias)) {
140
+ throw new Error(`Cannot create alias to "${alias}" because it is a canonical tag with existing aliases`);
141
+ }
142
+ const newAlias = {
143
+ alias: normalizedAlias,
144
+ canonical: normalizedCanonical,
145
+ description,
146
+ createdAt: new Date().toISOString(),
147
+ };
148
+ aliases.push(newAlias);
149
+ await this.saveTagAliases(aliases);
150
+ return newAlias;
151
+ }
152
+ /**
153
+ * List all tag aliases.
154
+ *
155
+ * @returns Array of all tag aliases
156
+ */
157
+ async listTagAliases() {
158
+ return await this.loadTagAliases();
159
+ }
160
+ /**
161
+ * Remove a tag alias.
162
+ *
163
+ * @param alias - Alias to remove
164
+ * @returns True if removed, false if not found
165
+ */
166
+ async removeTagAlias(alias) {
167
+ const aliases = await this.loadTagAliases();
168
+ const normalizedAlias = alias.toLowerCase();
169
+ const initialLength = aliases.length;
170
+ const filtered = aliases.filter(a => a.alias !== normalizedAlias);
171
+ if (filtered.length === initialLength) {
172
+ return false; // Alias not found
173
+ }
174
+ await this.saveTagAliases(filtered);
175
+ return true;
176
+ }
177
+ /**
178
+ * Get all aliases (synonyms) for a canonical tag.
179
+ *
180
+ * Returns all alias names that resolve to the specified canonical tag.
181
+ * Useful for discovering alternative names users might use for a tag.
182
+ * The canonical tag name is normalized to lowercase.
183
+ *
184
+ * @param canonicalTag - Canonical tag name (will be normalized to lowercase)
185
+ * @returns Array of alias names (all lowercase)
186
+ *
187
+ * @example
188
+ * ```typescript
189
+ * const manager = new TagManager(tagAliasesPath);
190
+ *
191
+ * // Set up some aliases
192
+ * await manager.addTagAlias('js', 'javascript');
193
+ * await manager.addTagAlias('ecmascript', 'javascript');
194
+ * await manager.addTagAlias('es6', 'javascript');
195
+ *
196
+ * // Get all aliases for canonical tag
197
+ * const aliases = await manager.getAliasesForTag('javascript');
198
+ * console.log(aliases); // ['js', 'ecmascript', 'es6']
199
+ *
200
+ * // Empty array if no aliases
201
+ * const noAliases = await manager.getAliasesForTag('python');
202
+ * console.log(noAliases); // []
203
+ * ```
204
+ */
205
+ async getAliasesForTag(canonicalTag) {
206
+ const aliases = await this.loadTagAliases();
207
+ const normalized = canonicalTag.toLowerCase();
208
+ return aliases.filter(a => a.canonical === normalized).map(a => a.alias);
209
+ }
210
+ }
@@ -0,0 +1,12 @@
1
+ /**
2
+ * Features Module Barrel Export
3
+ * Phase 4: Re-extracted specialized managers for single responsibility
4
+ * Phase 7: Added streaming export utilities
5
+ */
6
+ export { TagManager } from './TagManager.js';
7
+ export { IOManager, type ExportFormat, type ImportFormat, type MergeStrategy, type BackupMetadata, type BackupInfo, } from './IOManager.js';
8
+ export { AnalyticsManager } from './AnalyticsManager.js';
9
+ export { CompressionManager } from './CompressionManager.js';
10
+ export { ArchiveManager, type ArchiveCriteria, type ArchiveOptions, type ArchiveResult, } from './ArchiveManager.js';
11
+ export { StreamingExporter, type StreamResult } from './StreamingExporter.js';
12
+ //# sourceMappingURL=index.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/features/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAC7C,OAAO,EACL,SAAS,EACT,KAAK,YAAY,EACjB,KAAK,YAAY,EACjB,KAAK,aAAa,EAClB,KAAK,cAAc,EACnB,KAAK,UAAU,GAChB,MAAM,gBAAgB,CAAC;AACxB,OAAO,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AACzD,OAAO,EAAE,kBAAkB,EAAE,MAAM,yBAAyB,CAAC;AAC7D,OAAO,EACL,cAAc,EACd,KAAK,eAAe,EACpB,KAAK,cAAc,EACnB,KAAK,aAAa,GACnB,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EAAE,iBAAiB,EAAE,KAAK,YAAY,EAAE,MAAM,wBAAwB,CAAC"}
@@ -0,0 +1,11 @@
1
+ /**
2
+ * Features Module Barrel Export
3
+ * Phase 4: Re-extracted specialized managers for single responsibility
4
+ * Phase 7: Added streaming export utilities
5
+ */
6
+ export { TagManager } from './TagManager.js';
7
+ export { IOManager, } from './IOManager.js';
8
+ export { AnalyticsManager } from './AnalyticsManager.js';
9
+ export { CompressionManager } from './CompressionManager.js';
10
+ export { ArchiveManager, } from './ArchiveManager.js';
11
+ export { StreamingExporter } from './StreamingExporter.js';
package/dist/index.js CHANGED
@@ -20,8 +20,14 @@ let managerContext;
20
20
  // tearing down the connection). Without this, other event-loop refs — file
21
21
  // watchers, the embeddings pool, the consolidation timer — can keep the
22
22
  // process alive as an orphan until manually killed.
23
- process.stdin.on("end", () => process.exit(0));
24
- process.stdin.on("close", () => process.exit(0));
23
+ // ctx.close() (memoryjs v3) releases storage handles before exit; it is a
24
+ // no-op for JSONL but closes the SQLite handle when MEMORY_STORAGE_TYPE=sqlite.
25
+ function shutdown() {
26
+ managerContext?.close();
27
+ process.exit(0);
28
+ }
29
+ process.stdin.on("end", shutdown);
30
+ process.stdin.on("close", shutdown);
25
31
  async function main() {
26
32
  // Initialize memory file path with backward compatibility
27
33
  const memoryFilePath = await ensureMemoryFilePath();