@claude-flow/memory 3.0.0-alpha.1

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 (214) hide show
  1. package/.agentic-flow/intelligence.json +16 -0
  2. package/README.md +249 -0
  3. package/__tests__/coverage/base.css +224 -0
  4. package/__tests__/coverage/block-navigation.js +87 -0
  5. package/__tests__/coverage/coverage-final.json +19 -0
  6. package/__tests__/coverage/favicon.png +0 -0
  7. package/__tests__/coverage/index.html +206 -0
  8. package/__tests__/coverage/lcov-report/base.css +224 -0
  9. package/__tests__/coverage/lcov-report/block-navigation.js +87 -0
  10. package/__tests__/coverage/lcov-report/favicon.png +0 -0
  11. package/__tests__/coverage/lcov-report/index.html +206 -0
  12. package/__tests__/coverage/lcov-report/prettify.css +1 -0
  13. package/__tests__/coverage/lcov-report/prettify.js +2 -0
  14. package/__tests__/coverage/lcov-report/sort-arrow-sprite.png +0 -0
  15. package/__tests__/coverage/lcov-report/sorter.js +210 -0
  16. package/__tests__/coverage/lcov-report/src/agentdb-adapter.ts.html +2737 -0
  17. package/__tests__/coverage/lcov-report/src/agentdb-backend.ts.html +3130 -0
  18. package/__tests__/coverage/lcov-report/src/application/commands/delete-memory.command.ts.html +601 -0
  19. package/__tests__/coverage/lcov-report/src/application/commands/index.html +131 -0
  20. package/__tests__/coverage/lcov-report/src/application/commands/store-memory.command.ts.html +394 -0
  21. package/__tests__/coverage/lcov-report/src/application/queries/index.html +116 -0
  22. package/__tests__/coverage/lcov-report/src/application/queries/search-memory.query.ts.html +796 -0
  23. package/__tests__/coverage/lcov-report/src/application/services/index.html +116 -0
  24. package/__tests__/coverage/lcov-report/src/application/services/memory-application-service.ts.html +793 -0
  25. package/__tests__/coverage/lcov-report/src/cache-manager.ts.html +1633 -0
  26. package/__tests__/coverage/lcov-report/src/database-provider.ts.html +1618 -0
  27. package/__tests__/coverage/lcov-report/src/domain/entities/index.html +116 -0
  28. package/__tests__/coverage/lcov-report/src/domain/entities/memory-entry.ts.html +952 -0
  29. package/__tests__/coverage/lcov-report/src/domain/services/index.html +116 -0
  30. package/__tests__/coverage/lcov-report/src/domain/services/memory-domain-service.ts.html +1294 -0
  31. package/__tests__/coverage/lcov-report/src/hnsw-index.ts.html +3124 -0
  32. package/__tests__/coverage/lcov-report/src/hybrid-backend.ts.html +2167 -0
  33. package/__tests__/coverage/lcov-report/src/index.html +266 -0
  34. package/__tests__/coverage/lcov-report/src/infrastructure/repositories/hybrid-memory-repository.ts.html +1633 -0
  35. package/__tests__/coverage/lcov-report/src/infrastructure/repositories/index.html +116 -0
  36. package/__tests__/coverage/lcov-report/src/migration.ts.html +2092 -0
  37. package/__tests__/coverage/lcov-report/src/query-builder.ts.html +1711 -0
  38. package/__tests__/coverage/lcov-report/src/sqlite-backend.ts.html +2281 -0
  39. package/__tests__/coverage/lcov-report/src/sqljs-backend.ts.html +2374 -0
  40. package/__tests__/coverage/lcov-report/src/types.ts.html +2266 -0
  41. package/__tests__/coverage/lcov.info +10238 -0
  42. package/__tests__/coverage/prettify.css +1 -0
  43. package/__tests__/coverage/prettify.js +2 -0
  44. package/__tests__/coverage/sort-arrow-sprite.png +0 -0
  45. package/__tests__/coverage/sorter.js +210 -0
  46. package/__tests__/coverage/src/agentdb-adapter.ts.html +2737 -0
  47. package/__tests__/coverage/src/agentdb-backend.ts.html +3130 -0
  48. package/__tests__/coverage/src/application/commands/delete-memory.command.ts.html +601 -0
  49. package/__tests__/coverage/src/application/commands/index.html +131 -0
  50. package/__tests__/coverage/src/application/commands/store-memory.command.ts.html +394 -0
  51. package/__tests__/coverage/src/application/queries/index.html +116 -0
  52. package/__tests__/coverage/src/application/queries/search-memory.query.ts.html +796 -0
  53. package/__tests__/coverage/src/application/services/index.html +116 -0
  54. package/__tests__/coverage/src/application/services/memory-application-service.ts.html +793 -0
  55. package/__tests__/coverage/src/cache-manager.ts.html +1633 -0
  56. package/__tests__/coverage/src/database-provider.ts.html +1618 -0
  57. package/__tests__/coverage/src/domain/entities/index.html +116 -0
  58. package/__tests__/coverage/src/domain/entities/memory-entry.ts.html +952 -0
  59. package/__tests__/coverage/src/domain/services/index.html +116 -0
  60. package/__tests__/coverage/src/domain/services/memory-domain-service.ts.html +1294 -0
  61. package/__tests__/coverage/src/hnsw-index.ts.html +3124 -0
  62. package/__tests__/coverage/src/hybrid-backend.ts.html +2167 -0
  63. package/__tests__/coverage/src/index.html +266 -0
  64. package/__tests__/coverage/src/infrastructure/repositories/hybrid-memory-repository.ts.html +1633 -0
  65. package/__tests__/coverage/src/infrastructure/repositories/index.html +116 -0
  66. package/__tests__/coverage/src/migration.ts.html +2092 -0
  67. package/__tests__/coverage/src/query-builder.ts.html +1711 -0
  68. package/__tests__/coverage/src/sqlite-backend.ts.html +2281 -0
  69. package/__tests__/coverage/src/sqljs-backend.ts.html +2374 -0
  70. package/__tests__/coverage/src/types.ts.html +2266 -0
  71. package/benchmarks/cache-hit-rate.bench.ts +535 -0
  72. package/benchmarks/hnsw-indexing.bench.ts +552 -0
  73. package/benchmarks/memory-write.bench.ts +469 -0
  74. package/benchmarks/vector-search.bench.ts +449 -0
  75. package/dist/agentdb-adapter.d.ts +146 -0
  76. package/dist/agentdb-adapter.d.ts.map +1 -0
  77. package/dist/agentdb-adapter.js +679 -0
  78. package/dist/agentdb-adapter.js.map +1 -0
  79. package/dist/agentdb-backend.d.ts +214 -0
  80. package/dist/agentdb-backend.d.ts.map +1 -0
  81. package/dist/agentdb-backend.js +827 -0
  82. package/dist/agentdb-backend.js.map +1 -0
  83. package/dist/agentdb-backend.test.d.ts +7 -0
  84. package/dist/agentdb-backend.test.d.ts.map +1 -0
  85. package/dist/agentdb-backend.test.js +258 -0
  86. package/dist/agentdb-backend.test.js.map +1 -0
  87. package/dist/application/commands/delete-memory.command.d.ts +65 -0
  88. package/dist/application/commands/delete-memory.command.d.ts.map +1 -0
  89. package/dist/application/commands/delete-memory.command.js +129 -0
  90. package/dist/application/commands/delete-memory.command.js.map +1 -0
  91. package/dist/application/commands/store-memory.command.d.ts +48 -0
  92. package/dist/application/commands/store-memory.command.d.ts.map +1 -0
  93. package/dist/application/commands/store-memory.command.js +72 -0
  94. package/dist/application/commands/store-memory.command.js.map +1 -0
  95. package/dist/application/index.d.ts +12 -0
  96. package/dist/application/index.d.ts.map +1 -0
  97. package/dist/application/index.js +15 -0
  98. package/dist/application/index.js.map +1 -0
  99. package/dist/application/queries/search-memory.query.d.ts +72 -0
  100. package/dist/application/queries/search-memory.query.d.ts.map +1 -0
  101. package/dist/application/queries/search-memory.query.js +143 -0
  102. package/dist/application/queries/search-memory.query.js.map +1 -0
  103. package/dist/application/services/memory-application-service.d.ts +121 -0
  104. package/dist/application/services/memory-application-service.d.ts.map +1 -0
  105. package/dist/application/services/memory-application-service.js +190 -0
  106. package/dist/application/services/memory-application-service.js.map +1 -0
  107. package/dist/cache-manager.d.ts +134 -0
  108. package/dist/cache-manager.d.ts.map +1 -0
  109. package/dist/cache-manager.js +407 -0
  110. package/dist/cache-manager.js.map +1 -0
  111. package/dist/database-provider.d.ts +86 -0
  112. package/dist/database-provider.d.ts.map +1 -0
  113. package/dist/database-provider.js +385 -0
  114. package/dist/database-provider.js.map +1 -0
  115. package/dist/database-provider.test.d.ts +7 -0
  116. package/dist/database-provider.test.d.ts.map +1 -0
  117. package/dist/database-provider.test.js +285 -0
  118. package/dist/database-provider.test.js.map +1 -0
  119. package/dist/domain/entities/memory-entry.d.ts +143 -0
  120. package/dist/domain/entities/memory-entry.d.ts.map +1 -0
  121. package/dist/domain/entities/memory-entry.js +226 -0
  122. package/dist/domain/entities/memory-entry.js.map +1 -0
  123. package/dist/domain/index.d.ts +11 -0
  124. package/dist/domain/index.d.ts.map +1 -0
  125. package/dist/domain/index.js +12 -0
  126. package/dist/domain/index.js.map +1 -0
  127. package/dist/domain/repositories/memory-repository.interface.d.ts +102 -0
  128. package/dist/domain/repositories/memory-repository.interface.d.ts.map +1 -0
  129. package/dist/domain/repositories/memory-repository.interface.js +11 -0
  130. package/dist/domain/repositories/memory-repository.interface.js.map +1 -0
  131. package/dist/domain/services/memory-domain-service.d.ts +105 -0
  132. package/dist/domain/services/memory-domain-service.d.ts.map +1 -0
  133. package/dist/domain/services/memory-domain-service.js +297 -0
  134. package/dist/domain/services/memory-domain-service.js.map +1 -0
  135. package/dist/hnsw-index.d.ts +111 -0
  136. package/dist/hnsw-index.d.ts.map +1 -0
  137. package/dist/hnsw-index.js +781 -0
  138. package/dist/hnsw-index.js.map +1 -0
  139. package/dist/hybrid-backend.d.ts +217 -0
  140. package/dist/hybrid-backend.d.ts.map +1 -0
  141. package/dist/hybrid-backend.js +491 -0
  142. package/dist/hybrid-backend.js.map +1 -0
  143. package/dist/hybrid-backend.test.d.ts +8 -0
  144. package/dist/hybrid-backend.test.d.ts.map +1 -0
  145. package/dist/hybrid-backend.test.js +320 -0
  146. package/dist/hybrid-backend.test.js.map +1 -0
  147. package/dist/index.d.ts +188 -0
  148. package/dist/index.d.ts.map +1 -0
  149. package/dist/index.js +345 -0
  150. package/dist/index.js.map +1 -0
  151. package/dist/infrastructure/index.d.ts +17 -0
  152. package/dist/infrastructure/index.d.ts.map +1 -0
  153. package/dist/infrastructure/index.js +16 -0
  154. package/dist/infrastructure/index.js.map +1 -0
  155. package/dist/infrastructure/repositories/hybrid-memory-repository.d.ts +66 -0
  156. package/dist/infrastructure/repositories/hybrid-memory-repository.d.ts.map +1 -0
  157. package/dist/infrastructure/repositories/hybrid-memory-repository.js +409 -0
  158. package/dist/infrastructure/repositories/hybrid-memory-repository.js.map +1 -0
  159. package/dist/migration.d.ts +68 -0
  160. package/dist/migration.d.ts.map +1 -0
  161. package/dist/migration.js +513 -0
  162. package/dist/migration.js.map +1 -0
  163. package/dist/query-builder.d.ts +211 -0
  164. package/dist/query-builder.d.ts.map +1 -0
  165. package/dist/query-builder.js +438 -0
  166. package/dist/query-builder.js.map +1 -0
  167. package/dist/sqlite-backend.d.ts +121 -0
  168. package/dist/sqlite-backend.d.ts.map +1 -0
  169. package/dist/sqlite-backend.js +564 -0
  170. package/dist/sqlite-backend.js.map +1 -0
  171. package/dist/sqljs-backend.d.ts +128 -0
  172. package/dist/sqljs-backend.d.ts.map +1 -0
  173. package/dist/sqljs-backend.js +598 -0
  174. package/dist/sqljs-backend.js.map +1 -0
  175. package/dist/types.d.ts +481 -0
  176. package/dist/types.d.ts.map +1 -0
  177. package/dist/types.js +58 -0
  178. package/dist/types.js.map +1 -0
  179. package/docs/AGENTDB-INTEGRATION.md +388 -0
  180. package/docs/CROSS_PLATFORM.md +505 -0
  181. package/docs/WINDOWS_SUPPORT.md +422 -0
  182. package/examples/agentdb-example.ts +345 -0
  183. package/examples/cross-platform-usage.ts +326 -0
  184. package/framework/benchmark.ts +112 -0
  185. package/package.json +31 -0
  186. package/src/agentdb-adapter.ts +884 -0
  187. package/src/agentdb-backend.test.ts +339 -0
  188. package/src/agentdb-backend.ts +1016 -0
  189. package/src/application/commands/delete-memory.command.ts +172 -0
  190. package/src/application/commands/store-memory.command.ts +103 -0
  191. package/src/application/index.ts +36 -0
  192. package/src/application/queries/search-memory.query.ts +237 -0
  193. package/src/application/services/memory-application-service.ts +236 -0
  194. package/src/cache-manager.ts +516 -0
  195. package/src/database-provider.test.ts +364 -0
  196. package/src/database-provider.ts +511 -0
  197. package/src/domain/entities/memory-entry.ts +289 -0
  198. package/src/domain/index.ts +35 -0
  199. package/src/domain/repositories/memory-repository.interface.ts +120 -0
  200. package/src/domain/services/memory-domain-service.ts +403 -0
  201. package/src/hnsw-index.ts +1013 -0
  202. package/src/hybrid-backend.test.ts +399 -0
  203. package/src/hybrid-backend.ts +694 -0
  204. package/src/index.ts +515 -0
  205. package/src/infrastructure/index.ts +23 -0
  206. package/src/infrastructure/repositories/hybrid-memory-repository.ts +516 -0
  207. package/src/migration.ts +669 -0
  208. package/src/query-builder.ts +542 -0
  209. package/src/sqlite-backend.ts +732 -0
  210. package/src/sqljs-backend.ts +763 -0
  211. package/src/types.ts +727 -0
  212. package/tsconfig.json +9 -0
  213. package/tsconfig.tsbuildinfo +1 -0
  214. package/verify-cross-platform.ts +170 -0
@@ -0,0 +1,121 @@
1
+ /**
2
+ * SQLite Memory Backend
3
+ *
4
+ * Provides structured storage for memory entries using SQLite.
5
+ * Optimized for ACID transactions, exact matches, and complex queries.
6
+ * Part of ADR-009: Hybrid Memory Backend (SQLite + AgentDB)
7
+ *
8
+ * @module v3/memory/sqlite-backend
9
+ */
10
+ import { EventEmitter } from 'node:events';
11
+ import { IMemoryBackend, MemoryEntry, MemoryEntryUpdate, MemoryQuery, SearchOptions, SearchResult, BackendStats, HealthCheckResult, EmbeddingGenerator } from './types.js';
12
+ /**
13
+ * Configuration for SQLite Backend
14
+ */
15
+ export interface SQLiteBackendConfig {
16
+ /** Path to SQLite database file (:memory: for in-memory) */
17
+ databasePath: string;
18
+ /** Enable WAL mode for better concurrency */
19
+ walMode: boolean;
20
+ /** Enable query optimization */
21
+ optimize: boolean;
22
+ /** Default namespace */
23
+ defaultNamespace: string;
24
+ /** Embedding generator (for compatibility with hybrid mode) */
25
+ embeddingGenerator?: EmbeddingGenerator;
26
+ /** Maximum entries before auto-cleanup */
27
+ maxEntries: number;
28
+ /** Enable verbose logging */
29
+ verbose: boolean;
30
+ }
31
+ /**
32
+ * SQLite Backend for Structured Memory Storage
33
+ *
34
+ * Provides:
35
+ * - ACID transactions for data consistency
36
+ * - Efficient indexing for exact matches and prefix queries
37
+ * - Full-text search capabilities
38
+ * - Complex SQL queries with joins and aggregations
39
+ * - Persistent storage with WAL mode
40
+ */
41
+ export declare class SQLiteBackend extends EventEmitter implements IMemoryBackend {
42
+ private config;
43
+ private db;
44
+ private initialized;
45
+ private stats;
46
+ constructor(config?: Partial<SQLiteBackendConfig>);
47
+ /**
48
+ * Initialize the SQLite backend
49
+ */
50
+ initialize(): Promise<void>;
51
+ /**
52
+ * Shutdown the backend
53
+ */
54
+ shutdown(): Promise<void>;
55
+ /**
56
+ * Store a memory entry
57
+ */
58
+ store(entry: MemoryEntry): Promise<void>;
59
+ /**
60
+ * Get a memory entry by ID
61
+ */
62
+ get(id: string): Promise<MemoryEntry | null>;
63
+ /**
64
+ * Get a memory entry by key within a namespace
65
+ */
66
+ getByKey(namespace: string, key: string): Promise<MemoryEntry | null>;
67
+ /**
68
+ * Update a memory entry
69
+ */
70
+ update(id: string, update: MemoryEntryUpdate): Promise<MemoryEntry | null>;
71
+ /**
72
+ * Delete a memory entry
73
+ */
74
+ delete(id: string): Promise<boolean>;
75
+ /**
76
+ * Query memory entries with filters
77
+ */
78
+ query(query: MemoryQuery): Promise<MemoryEntry[]>;
79
+ /**
80
+ * Semantic vector search (not optimized for SQLite, returns empty)
81
+ * Use HybridBackend for semantic search with AgentDB
82
+ */
83
+ search(embedding: Float32Array, options: SearchOptions): Promise<SearchResult[]>;
84
+ /**
85
+ * Bulk insert entries
86
+ */
87
+ bulkInsert(entries: MemoryEntry[]): Promise<void>;
88
+ /**
89
+ * Bulk delete entries
90
+ */
91
+ bulkDelete(ids: string[]): Promise<number>;
92
+ /**
93
+ * Get entry count
94
+ */
95
+ count(namespace?: string): Promise<number>;
96
+ /**
97
+ * List all namespaces
98
+ */
99
+ listNamespaces(): Promise<string[]>;
100
+ /**
101
+ * Clear all entries in a namespace
102
+ */
103
+ clearNamespace(namespace: string): Promise<number>;
104
+ /**
105
+ * Get backend statistics
106
+ */
107
+ getStats(): Promise<BackendStats>;
108
+ /**
109
+ * Perform health check
110
+ */
111
+ healthCheck(): Promise<HealthCheckResult>;
112
+ private ensureInitialized;
113
+ private createSchema;
114
+ private rowToEntry;
115
+ /**
116
+ * Synchronous store for use in transactions
117
+ */
118
+ private storeSync;
119
+ }
120
+ export default SQLiteBackend;
121
+ //# sourceMappingURL=sqlite-backend.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"sqlite-backend.d.ts","sourceRoot":"","sources":["../src/sqlite-backend.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAE3C,OAAO,EACL,cAAc,EACd,WAAW,EAEX,iBAAiB,EACjB,WAAW,EACX,aAAa,EACb,YAAY,EACZ,YAAY,EACZ,iBAAiB,EAGjB,kBAAkB,EAGnB,MAAM,YAAY,CAAC;AAEpB;;GAEG;AACH,MAAM,WAAW,mBAAmB;IAClC,4DAA4D;IAC5D,YAAY,EAAE,MAAM,CAAC;IAErB,6CAA6C;IAC7C,OAAO,EAAE,OAAO,CAAC;IAEjB,gCAAgC;IAChC,QAAQ,EAAE,OAAO,CAAC;IAElB,wBAAwB;IACxB,gBAAgB,EAAE,MAAM,CAAC;IAEzB,+DAA+D;IAC/D,kBAAkB,CAAC,EAAE,kBAAkB,CAAC;IAExC,0CAA0C;IAC1C,UAAU,EAAE,MAAM,CAAC;IAEnB,6BAA6B;IAC7B,OAAO,EAAE,OAAO,CAAC;CAClB;AAcD;;;;;;;;;GASG;AACH,qBAAa,aAAc,SAAQ,YAAa,YAAW,cAAc;IACvE,OAAO,CAAC,MAAM,CAAsB;IACpC,OAAO,CAAC,EAAE,CAAkC;IAC5C,OAAO,CAAC,WAAW,CAAkB;IAGrC,OAAO,CAAC,KAAK,CAKX;gBAEU,MAAM,GAAE,OAAO,CAAC,mBAAmB,CAAM;IAKrD;;OAEG;IACG,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC;IA2BjC;;OAEG;IACG,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC;IAc/B;;OAEG;IACG,KAAK,CAAC,KAAK,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC;IA+C9C;;OAEG;IACG,GAAG,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,GAAG,IAAI,CAAC;IAWlD;;OAEG;IACG,QAAQ,CAAC,SAAS,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,GAAG,IAAI,CAAC;IAc3E;;OAEG;IACG,MAAM,CAAC,EAAE,EAAE,MAAM,EAAE,MAAM,EAAE,iBAAiB,GAAG,OAAO,CAAC,WAAW,GAAG,IAAI,CAAC;IA0BhF;;OAEG;IACG,MAAM,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAiB1C;;OAEG;IACG,KAAK,CAAC,KAAK,EAAE,WAAW,GAAG,OAAO,CAAC,WAAW,EAAE,CAAC;IAuGvD;;;OAGG;IACG,MAAM,CACV,SAAS,EAAE,YAAY,EACvB,OAAO,EAAE,aAAa,GACrB,OAAO,CAAC,YAAY,EAAE,CAAC;IAS1B;;OAEG;IACG,UAAU,CAAC,OAAO,EAAE,WAAW,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IAavD;;OAEG;IACG,UAAU,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,CAAC;IAmBhD;;OAEG;IACG,KAAK,CAAC,SAAS,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAgBhD;;OAEG;IACG,cAAc,IAAI,OAAO,CAAC,MAAM,EAAE,CAAC;IAQzC;;OAEG;IACG,cAAc,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAexD;;OAEG;IACG,QAAQ,IAAI,OAAO,CAAC,YAAY,CAAC;IAqDvC;;OAEG;IACG,WAAW,IAAI,OAAO,CAAC,iBAAiB,CAAC;IAwE/C,OAAO,CAAC,iBAAiB;IAMzB,OAAO,CAAC,YAAY;IAyCpB,OAAO,CAAC,UAAU;IAgClB;;OAEG;IACH,OAAO,CAAC,SAAS;CAoClB;AAED,eAAe,aAAa,CAAC"}
@@ -0,0 +1,564 @@
1
+ /**
2
+ * SQLite Memory Backend
3
+ *
4
+ * Provides structured storage for memory entries using SQLite.
5
+ * Optimized for ACID transactions, exact matches, and complex queries.
6
+ * Part of ADR-009: Hybrid Memory Backend (SQLite + AgentDB)
7
+ *
8
+ * @module v3/memory/sqlite-backend
9
+ */
10
+ import { EventEmitter } from 'node:events';
11
+ import Database from 'better-sqlite3';
12
+ /**
13
+ * Default configuration values
14
+ */
15
+ const DEFAULT_CONFIG = {
16
+ databasePath: ':memory:',
17
+ walMode: true,
18
+ optimize: true,
19
+ defaultNamespace: 'default',
20
+ maxEntries: 1000000,
21
+ verbose: false,
22
+ };
23
+ /**
24
+ * SQLite Backend for Structured Memory Storage
25
+ *
26
+ * Provides:
27
+ * - ACID transactions for data consistency
28
+ * - Efficient indexing for exact matches and prefix queries
29
+ * - Full-text search capabilities
30
+ * - Complex SQL queries with joins and aggregations
31
+ * - Persistent storage with WAL mode
32
+ */
33
+ export class SQLiteBackend extends EventEmitter {
34
+ config;
35
+ db = null;
36
+ initialized = false;
37
+ // Performance tracking
38
+ stats = {
39
+ queryCount: 0,
40
+ totalQueryTime: 0,
41
+ writeCount: 0,
42
+ totalWriteTime: 0,
43
+ };
44
+ constructor(config = {}) {
45
+ super();
46
+ this.config = { ...DEFAULT_CONFIG, ...config };
47
+ }
48
+ /**
49
+ * Initialize the SQLite backend
50
+ */
51
+ async initialize() {
52
+ if (this.initialized)
53
+ return;
54
+ // Open database connection
55
+ this.db = new Database(this.config.databasePath, {
56
+ verbose: this.config.verbose ? console.log : undefined,
57
+ });
58
+ // Enable WAL mode for better concurrency
59
+ if (this.config.walMode) {
60
+ this.db.pragma('journal_mode = WAL');
61
+ }
62
+ // Performance optimizations
63
+ if (this.config.optimize) {
64
+ this.db.pragma('synchronous = NORMAL');
65
+ this.db.pragma('cache_size = 10000');
66
+ this.db.pragma('temp_store = MEMORY');
67
+ }
68
+ // Create schema
69
+ this.createSchema();
70
+ this.initialized = true;
71
+ this.emit('initialized');
72
+ }
73
+ /**
74
+ * Shutdown the backend
75
+ */
76
+ async shutdown() {
77
+ if (!this.initialized || !this.db)
78
+ return;
79
+ // Optimize database before closing
80
+ if (this.config.optimize) {
81
+ this.db.pragma('optimize');
82
+ }
83
+ this.db.close();
84
+ this.db = null;
85
+ this.initialized = false;
86
+ this.emit('shutdown');
87
+ }
88
+ /**
89
+ * Store a memory entry
90
+ */
91
+ async store(entry) {
92
+ this.ensureInitialized();
93
+ const startTime = performance.now();
94
+ const stmt = this.db.prepare(`
95
+ INSERT OR REPLACE INTO memory_entries (
96
+ id, key, content, type, namespace, tags, metadata,
97
+ owner_id, access_level, created_at, updated_at, expires_at,
98
+ version, references, access_count, last_accessed_at
99
+ ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
100
+ `);
101
+ stmt.run(entry.id, entry.key, entry.content, entry.type, entry.namespace, JSON.stringify(entry.tags), JSON.stringify(entry.metadata), entry.ownerId || null, entry.accessLevel, entry.createdAt, entry.updatedAt, entry.expiresAt || null, entry.version, JSON.stringify(entry.references), entry.accessCount, entry.lastAccessedAt);
102
+ // Store embedding separately (as BLOB)
103
+ if (entry.embedding) {
104
+ const embeddingStmt = this.db.prepare(`
105
+ INSERT OR REPLACE INTO memory_embeddings (entry_id, embedding)
106
+ VALUES (?, ?)
107
+ `);
108
+ embeddingStmt.run(entry.id, Buffer.from(entry.embedding.buffer));
109
+ }
110
+ const duration = performance.now() - startTime;
111
+ this.stats.writeCount++;
112
+ this.stats.totalWriteTime += duration;
113
+ this.emit('entry:stored', { id: entry.id, duration });
114
+ }
115
+ /**
116
+ * Get a memory entry by ID
117
+ */
118
+ async get(id) {
119
+ this.ensureInitialized();
120
+ const stmt = this.db.prepare('SELECT * FROM memory_entries WHERE id = ?');
121
+ const row = stmt.get(id);
122
+ if (!row)
123
+ return null;
124
+ return this.rowToEntry(row);
125
+ }
126
+ /**
127
+ * Get a memory entry by key within a namespace
128
+ */
129
+ async getByKey(namespace, key) {
130
+ this.ensureInitialized();
131
+ const stmt = this.db.prepare(`
132
+ SELECT * FROM memory_entries
133
+ WHERE namespace = ? AND key = ?
134
+ `);
135
+ const row = stmt.get(namespace, key);
136
+ if (!row)
137
+ return null;
138
+ return this.rowToEntry(row);
139
+ }
140
+ /**
141
+ * Update a memory entry
142
+ */
143
+ async update(id, update) {
144
+ this.ensureInitialized();
145
+ const entry = await this.get(id);
146
+ if (!entry)
147
+ return null;
148
+ // Apply updates
149
+ if (update.content !== undefined)
150
+ entry.content = update.content;
151
+ if (update.tags !== undefined)
152
+ entry.tags = update.tags;
153
+ if (update.metadata !== undefined) {
154
+ entry.metadata = { ...entry.metadata, ...update.metadata };
155
+ }
156
+ if (update.accessLevel !== undefined)
157
+ entry.accessLevel = update.accessLevel;
158
+ if (update.expiresAt !== undefined)
159
+ entry.expiresAt = update.expiresAt;
160
+ if (update.references !== undefined)
161
+ entry.references = update.references;
162
+ entry.updatedAt = Date.now();
163
+ entry.version++;
164
+ // Store updated entry
165
+ await this.store(entry);
166
+ this.emit('entry:updated', { id });
167
+ return entry;
168
+ }
169
+ /**
170
+ * Delete a memory entry
171
+ */
172
+ async delete(id) {
173
+ this.ensureInitialized();
174
+ const deleteEntry = this.db.prepare('DELETE FROM memory_entries WHERE id = ?');
175
+ const deleteEmbedding = this.db.prepare('DELETE FROM memory_embeddings WHERE entry_id = ?');
176
+ const result = deleteEntry.run(id);
177
+ deleteEmbedding.run(id);
178
+ if (result.changes > 0) {
179
+ this.emit('entry:deleted', { id });
180
+ return true;
181
+ }
182
+ return false;
183
+ }
184
+ /**
185
+ * Query memory entries with filters
186
+ */
187
+ async query(query) {
188
+ this.ensureInitialized();
189
+ const startTime = performance.now();
190
+ let sql = 'SELECT * FROM memory_entries WHERE 1=1';
191
+ const params = [];
192
+ // Build WHERE clauses
193
+ if (query.namespace) {
194
+ sql += ' AND namespace = ?';
195
+ params.push(query.namespace);
196
+ }
197
+ if (query.key) {
198
+ sql += ' AND key = ?';
199
+ params.push(query.key);
200
+ }
201
+ if (query.keyPrefix) {
202
+ sql += ' AND key LIKE ?';
203
+ params.push(`${query.keyPrefix}%`);
204
+ }
205
+ if (query.memoryType) {
206
+ sql += ' AND type = ?';
207
+ params.push(query.memoryType);
208
+ }
209
+ if (query.accessLevel) {
210
+ sql += ' AND access_level = ?';
211
+ params.push(query.accessLevel);
212
+ }
213
+ if (query.ownerId) {
214
+ sql += ' AND owner_id = ?';
215
+ params.push(query.ownerId);
216
+ }
217
+ if (query.createdAfter) {
218
+ sql += ' AND created_at >= ?';
219
+ params.push(query.createdAfter);
220
+ }
221
+ if (query.createdBefore) {
222
+ sql += ' AND created_at <= ?';
223
+ params.push(query.createdBefore);
224
+ }
225
+ if (query.updatedAfter) {
226
+ sql += ' AND updated_at >= ?';
227
+ params.push(query.updatedAfter);
228
+ }
229
+ if (query.updatedBefore) {
230
+ sql += ' AND updated_at <= ?';
231
+ params.push(query.updatedBefore);
232
+ }
233
+ if (!query.includeExpired) {
234
+ sql += ' AND (expires_at IS NULL OR expires_at > ?)';
235
+ params.push(Date.now());
236
+ }
237
+ // Tag filtering (safe parameterized query)
238
+ if (query.tags && query.tags.length > 0) {
239
+ // Validate tags before using in query
240
+ for (const tag of query.tags) {
241
+ if (typeof tag !== 'string' || !/^[a-zA-Z0-9_\-.:]+$/.test(tag)) {
242
+ throw new Error(`Invalid tag format: ${tag}`);
243
+ }
244
+ }
245
+ // Use parameterized query with JSON functions
246
+ const tagPlaceholders = query.tags.map(() => '?').join(', ');
247
+ sql += ` AND EXISTS (
248
+ SELECT 1 FROM json_each(tags) AS t
249
+ WHERE t.value IN (${tagPlaceholders})
250
+ )`;
251
+ params.push(...query.tags);
252
+ }
253
+ // Pagination
254
+ sql += ' ORDER BY created_at DESC';
255
+ if (query.limit) {
256
+ sql += ' LIMIT ?';
257
+ params.push(query.limit);
258
+ }
259
+ if (query.offset) {
260
+ sql += ' OFFSET ?';
261
+ params.push(query.offset);
262
+ }
263
+ const stmt = this.db.prepare(sql);
264
+ const rows = stmt.all(...params);
265
+ const results = rows.map((row) => this.rowToEntry(row));
266
+ const duration = performance.now() - startTime;
267
+ this.stats.queryCount++;
268
+ this.stats.totalQueryTime += duration;
269
+ return results;
270
+ }
271
+ /**
272
+ * Semantic vector search (not optimized for SQLite, returns empty)
273
+ * Use HybridBackend for semantic search with AgentDB
274
+ */
275
+ async search(embedding, options) {
276
+ // SQLite is not optimized for vector search
277
+ // This method returns empty to encourage use of HybridBackend
278
+ console.warn('SQLiteBackend.search(): Vector search not optimized. Use HybridBackend for semantic search.');
279
+ return [];
280
+ }
281
+ /**
282
+ * Bulk insert entries
283
+ */
284
+ async bulkInsert(entries) {
285
+ this.ensureInitialized();
286
+ const transaction = this.db.transaction((entries) => {
287
+ for (const entry of entries) {
288
+ this.storeSync(entry);
289
+ }
290
+ });
291
+ transaction(entries);
292
+ this.emit('bulk:inserted', { count: entries.length });
293
+ }
294
+ /**
295
+ * Bulk delete entries
296
+ */
297
+ async bulkDelete(ids) {
298
+ this.ensureInitialized();
299
+ const deleteEntry = this.db.prepare('DELETE FROM memory_entries WHERE id = ?');
300
+ const deleteEmbedding = this.db.prepare('DELETE FROM memory_embeddings WHERE entry_id = ?');
301
+ const transaction = this.db.transaction((ids) => {
302
+ let deleted = 0;
303
+ for (const id of ids) {
304
+ const result = deleteEntry.run(id);
305
+ deleteEmbedding.run(id);
306
+ if (result.changes > 0)
307
+ deleted++;
308
+ }
309
+ return deleted;
310
+ });
311
+ return transaction(ids);
312
+ }
313
+ /**
314
+ * Get entry count
315
+ */
316
+ async count(namespace) {
317
+ this.ensureInitialized();
318
+ let sql = 'SELECT COUNT(*) as count FROM memory_entries';
319
+ const params = [];
320
+ if (namespace) {
321
+ sql += ' WHERE namespace = ?';
322
+ params.push(namespace);
323
+ }
324
+ const stmt = this.db.prepare(sql);
325
+ const result = stmt.get(...params);
326
+ return result.count;
327
+ }
328
+ /**
329
+ * List all namespaces
330
+ */
331
+ async listNamespaces() {
332
+ this.ensureInitialized();
333
+ const stmt = this.db.prepare('SELECT DISTINCT namespace FROM memory_entries');
334
+ const rows = stmt.all();
335
+ return rows.map((row) => row.namespace);
336
+ }
337
+ /**
338
+ * Clear all entries in a namespace
339
+ */
340
+ async clearNamespace(namespace) {
341
+ this.ensureInitialized();
342
+ const deleteEntries = this.db.prepare('DELETE FROM memory_entries WHERE namespace = ?');
343
+ const result = deleteEntries.run(namespace);
344
+ // Clean up orphaned embeddings
345
+ this.db.prepare(`
346
+ DELETE FROM memory_embeddings
347
+ WHERE entry_id NOT IN (SELECT id FROM memory_entries)
348
+ `).run();
349
+ return result.changes;
350
+ }
351
+ /**
352
+ * Get backend statistics
353
+ */
354
+ async getStats() {
355
+ this.ensureInitialized();
356
+ // Count by namespace
357
+ const namespaceStmt = this.db.prepare(`
358
+ SELECT namespace, COUNT(*) as count
359
+ FROM memory_entries
360
+ GROUP BY namespace
361
+ `);
362
+ const namespaceRows = namespaceStmt.all();
363
+ const entriesByNamespace = {};
364
+ for (const row of namespaceRows) {
365
+ entriesByNamespace[row.namespace] = row.count;
366
+ }
367
+ // Count by type
368
+ const typeStmt = this.db.prepare(`
369
+ SELECT type, COUNT(*) as count
370
+ FROM memory_entries
371
+ GROUP BY type
372
+ `);
373
+ const typeRows = typeStmt.all();
374
+ const entriesByType = {
375
+ episodic: 0,
376
+ semantic: 0,
377
+ procedural: 0,
378
+ working: 0,
379
+ cache: 0,
380
+ };
381
+ for (const row of typeRows) {
382
+ entriesByType[row.type] = row.count;
383
+ }
384
+ // Get database size
385
+ const pageCount = this.db.pragma('page_count', { simple: true });
386
+ const pageSize = this.db.pragma('page_size', { simple: true });
387
+ const memoryUsage = pageCount * pageSize;
388
+ const totalEntries = await this.count();
389
+ return {
390
+ totalEntries,
391
+ entriesByNamespace,
392
+ entriesByType,
393
+ memoryUsage,
394
+ avgQueryTime: this.stats.queryCount > 0
395
+ ? this.stats.totalQueryTime / this.stats.queryCount
396
+ : 0,
397
+ avgSearchTime: 0, // Not applicable for SQLite
398
+ };
399
+ }
400
+ /**
401
+ * Perform health check
402
+ */
403
+ async healthCheck() {
404
+ const issues = [];
405
+ const recommendations = [];
406
+ if (!this.initialized || !this.db) {
407
+ return {
408
+ status: 'unhealthy',
409
+ components: {
410
+ storage: { status: 'unhealthy', latency: 0, message: 'Not initialized' },
411
+ index: { status: 'healthy', latency: 0 },
412
+ cache: { status: 'healthy', latency: 0 },
413
+ },
414
+ timestamp: Date.now(),
415
+ issues: ['Backend not initialized'],
416
+ recommendations: ['Call initialize() before using'],
417
+ };
418
+ }
419
+ // Check database integrity
420
+ let storageHealth;
421
+ try {
422
+ const integrityCheck = this.db.pragma('integrity_check', { simple: true });
423
+ if (integrityCheck === 'ok') {
424
+ storageHealth = { status: 'healthy', latency: 0 };
425
+ }
426
+ else {
427
+ issues.push('Database integrity check failed');
428
+ recommendations.push('Run VACUUM to repair database');
429
+ storageHealth = { status: 'unhealthy', latency: 0, message: 'Integrity check failed' };
430
+ }
431
+ }
432
+ catch (error) {
433
+ issues.push('Failed to check database integrity');
434
+ storageHealth = { status: 'unhealthy', latency: 0, message: String(error) };
435
+ }
436
+ // Check utilization
437
+ const totalEntries = await this.count();
438
+ const utilizationPercent = (totalEntries / this.config.maxEntries) * 100;
439
+ if (utilizationPercent > 95) {
440
+ issues.push('Storage utilization critical (>95%)');
441
+ recommendations.push('Cleanup old data or increase maxEntries');
442
+ storageHealth = { status: 'unhealthy', latency: 0, message: 'Near capacity' };
443
+ }
444
+ else if (utilizationPercent > 80) {
445
+ issues.push('Storage utilization high (>80%)');
446
+ recommendations.push('Consider cleanup');
447
+ if (storageHealth.status === 'healthy') {
448
+ storageHealth = { status: 'degraded', latency: 0, message: 'High utilization' };
449
+ }
450
+ }
451
+ const status = storageHealth.status === 'unhealthy'
452
+ ? 'unhealthy'
453
+ : storageHealth.status === 'degraded'
454
+ ? 'degraded'
455
+ : 'healthy';
456
+ return {
457
+ status,
458
+ components: {
459
+ storage: storageHealth,
460
+ index: { status: 'healthy', latency: 0 },
461
+ cache: { status: 'healthy', latency: 0 },
462
+ },
463
+ timestamp: Date.now(),
464
+ issues,
465
+ recommendations,
466
+ };
467
+ }
468
+ // ===== Private Methods =====
469
+ ensureInitialized() {
470
+ if (!this.initialized || !this.db) {
471
+ throw new Error('SQLiteBackend not initialized. Call initialize() first.');
472
+ }
473
+ }
474
+ createSchema() {
475
+ if (!this.db)
476
+ return;
477
+ // Main entries table
478
+ this.db.exec(`
479
+ CREATE TABLE IF NOT EXISTS memory_entries (
480
+ id TEXT PRIMARY KEY,
481
+ key TEXT NOT NULL,
482
+ content TEXT NOT NULL,
483
+ type TEXT NOT NULL,
484
+ namespace TEXT NOT NULL,
485
+ tags TEXT NOT NULL,
486
+ metadata TEXT NOT NULL,
487
+ owner_id TEXT,
488
+ access_level TEXT NOT NULL,
489
+ created_at INTEGER NOT NULL,
490
+ updated_at INTEGER NOT NULL,
491
+ expires_at INTEGER,
492
+ version INTEGER NOT NULL,
493
+ references TEXT NOT NULL,
494
+ access_count INTEGER NOT NULL,
495
+ last_accessed_at INTEGER NOT NULL
496
+ );
497
+
498
+ CREATE INDEX IF NOT EXISTS idx_namespace ON memory_entries(namespace);
499
+ CREATE INDEX IF NOT EXISTS idx_key ON memory_entries(key);
500
+ CREATE INDEX IF NOT EXISTS idx_namespace_key ON memory_entries(namespace, key);
501
+ CREATE INDEX IF NOT EXISTS idx_type ON memory_entries(type);
502
+ CREATE INDEX IF NOT EXISTS idx_owner_id ON memory_entries(owner_id);
503
+ CREATE INDEX IF NOT EXISTS idx_created_at ON memory_entries(created_at);
504
+ CREATE INDEX IF NOT EXISTS idx_updated_at ON memory_entries(updated_at);
505
+ CREATE INDEX IF NOT EXISTS idx_expires_at ON memory_entries(expires_at);
506
+
507
+ CREATE TABLE IF NOT EXISTS memory_embeddings (
508
+ entry_id TEXT PRIMARY KEY,
509
+ embedding BLOB,
510
+ FOREIGN KEY (entry_id) REFERENCES memory_entries(id) ON DELETE CASCADE
511
+ );
512
+ `);
513
+ }
514
+ rowToEntry(row) {
515
+ // Get embedding if exists
516
+ let embedding;
517
+ const embeddingStmt = this.db.prepare('SELECT embedding FROM memory_embeddings WHERE entry_id = ?');
518
+ const embeddingRow = embeddingStmt.get(row.id);
519
+ if (embeddingRow && embeddingRow.embedding) {
520
+ embedding = new Float32Array(embeddingRow.embedding.buffer);
521
+ }
522
+ return {
523
+ id: row.id,
524
+ key: row.key,
525
+ content: row.content,
526
+ embedding,
527
+ type: row.type,
528
+ namespace: row.namespace,
529
+ tags: JSON.parse(row.tags),
530
+ metadata: JSON.parse(row.metadata),
531
+ ownerId: row.owner_id,
532
+ accessLevel: row.access_level,
533
+ createdAt: row.created_at,
534
+ updatedAt: row.updated_at,
535
+ expiresAt: row.expires_at,
536
+ version: row.version,
537
+ references: JSON.parse(row.references),
538
+ accessCount: row.access_count,
539
+ lastAccessedAt: row.last_accessed_at,
540
+ };
541
+ }
542
+ /**
543
+ * Synchronous store for use in transactions
544
+ */
545
+ storeSync(entry) {
546
+ const stmt = this.db.prepare(`
547
+ INSERT OR REPLACE INTO memory_entries (
548
+ id, key, content, type, namespace, tags, metadata,
549
+ owner_id, access_level, created_at, updated_at, expires_at,
550
+ version, references, access_count, last_accessed_at
551
+ ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
552
+ `);
553
+ stmt.run(entry.id, entry.key, entry.content, entry.type, entry.namespace, JSON.stringify(entry.tags), JSON.stringify(entry.metadata), entry.ownerId || null, entry.accessLevel, entry.createdAt, entry.updatedAt, entry.expiresAt || null, entry.version, JSON.stringify(entry.references), entry.accessCount, entry.lastAccessedAt);
554
+ if (entry.embedding) {
555
+ const embeddingStmt = this.db.prepare(`
556
+ INSERT OR REPLACE INTO memory_embeddings (entry_id, embedding)
557
+ VALUES (?, ?)
558
+ `);
559
+ embeddingStmt.run(entry.id, Buffer.from(entry.embedding.buffer));
560
+ }
561
+ }
562
+ }
563
+ export default SQLiteBackend;
564
+ //# sourceMappingURL=sqlite-backend.js.map