memento-mcp-server 0.1.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 (555) hide show
  1. package/.cursor/rules/cache-management.mdc +171 -0
  2. package/.cursor/rules/database-schema.mdc +344 -0
  3. package/.cursor/rules/deployment.mdc +596 -0
  4. package/.cursor/rules/error-logging.mdc +298 -0
  5. package/.cursor/rules/forgetting-algorithms.mdc +426 -0
  6. package/.cursor/rules/http-server.mdc +432 -0
  7. package/.cursor/rules/hybrid-search.mdc +424 -0
  8. package/.cursor/rules/implementation.mdc +369 -0
  9. package/.cursor/rules/lightweight-embedding.mdc +178 -0
  10. package/.cursor/rules/mcp-client-development.mdc +0 -0
  11. package/.cursor/rules/mcp-server-development.mdc +0 -0
  12. package/.cursor/rules/mcp-tools-architecture.mdc +205 -0
  13. package/.cursor/rules/memento-memory-rule.mdc +8 -0
  14. package/.cursor/rules/memento-project-overview.mdc +0 -0
  15. package/.cursor/rules/memory-algorithms.mdc +502 -0
  16. package/.cursor/rules/monitoring.mdc +622 -0
  17. package/.cursor/rules/performance-alerts.mdc +537 -0
  18. package/.cursor/rules/performance-monitoring.mdc +345 -0
  19. package/.cursor/rules/performance-optimization.mdc +563 -0
  20. package/.cursor/rules/project-structure.mdc +310 -0
  21. package/.cursor/rules/testing.mdc +473 -0
  22. package/.dockerignore +15 -0
  23. package/.eslintrc.json +34 -0
  24. package/.github/ISSUE_TEMPLATE/bug_report.md +51 -0
  25. package/.github/ISSUE_TEMPLATE/feature_request.md +45 -0
  26. package/.github/ISSUE_TEMPLATE/question.md +31 -0
  27. package/.github/PULL_REQUEST_TEMPLATE.md +97 -0
  28. package/AGENTS.md +28 -0
  29. package/CHANGELOG.md +416 -0
  30. package/CODE_OF_CONDUCT.md +62 -0
  31. package/CONTRIBUTING.md +165 -0
  32. package/DOCKER_SETUP_GUIDE.md +84 -0
  33. package/Dockerfile +90 -0
  34. package/INSTALL.en.md +303 -0
  35. package/INSTALL.md +303 -0
  36. package/README.en.md +330 -0
  37. package/README.md +427 -0
  38. package/backup/legacy-removal-20250930-201816/http-server-legacy.ts +1068 -0
  39. package/backup/legacy-removal-20250930-201816/rollback-to-legacy.ps1 +46 -0
  40. package/backup/legacy-removal-20250930-201816/rollback-to-legacy.sh +48 -0
  41. package/dist/algorithms/forgetting-algorithm.d.ts +90 -0
  42. package/dist/algorithms/forgetting-algorithm.d.ts.map +1 -0
  43. package/dist/algorithms/forgetting-algorithm.js +160 -0
  44. package/dist/algorithms/forgetting-algorithm.js.map +1 -0
  45. package/dist/algorithms/hybrid-search-engine.d.ts +108 -0
  46. package/dist/algorithms/hybrid-search-engine.d.ts.map +1 -0
  47. package/dist/algorithms/hybrid-search-engine.js +384 -0
  48. package/dist/algorithms/hybrid-search-engine.js.map +1 -0
  49. package/dist/algorithms/search-engine.d.ts +64 -0
  50. package/dist/algorithms/search-engine.d.ts.map +1 -0
  51. package/dist/algorithms/search-engine.js +304 -0
  52. package/dist/algorithms/search-engine.js.map +1 -0
  53. package/dist/algorithms/search-ranking.d.ts +145 -0
  54. package/dist/algorithms/search-ranking.d.ts.map +1 -0
  55. package/dist/algorithms/search-ranking.js +311 -0
  56. package/dist/algorithms/search-ranking.js.map +1 -0
  57. package/dist/algorithms/spaced-repetition.d.ts +83 -0
  58. package/dist/algorithms/spaced-repetition.d.ts.map +1 -0
  59. package/dist/algorithms/spaced-repetition.js +153 -0
  60. package/dist/algorithms/spaced-repetition.js.map +1 -0
  61. package/dist/algorithms/vector-search-engine.d.ts +96 -0
  62. package/dist/algorithms/vector-search-engine.d.ts.map +1 -0
  63. package/dist/algorithms/vector-search-engine.js +410 -0
  64. package/dist/algorithms/vector-search-engine.js.map +1 -0
  65. package/dist/client/index.d.ts +55 -0
  66. package/dist/client/index.d.ts.map +1 -0
  67. package/dist/client/index.js +179 -0
  68. package/dist/client/index.js.map +1 -0
  69. package/dist/config/index.d.ts +20 -0
  70. package/dist/config/index.d.ts.map +1 -0
  71. package/dist/config/index.js +87 -0
  72. package/dist/config/index.js.map +1 -0
  73. package/dist/database/init.d.ts +7 -0
  74. package/dist/database/init.d.ts.map +1 -0
  75. package/dist/database/init.js +117 -0
  76. package/dist/database/init.js.map +1 -0
  77. package/dist/database/migrate.d.ts +6 -0
  78. package/dist/database/migrate.d.ts.map +1 -0
  79. package/dist/database/migrate.js +84 -0
  80. package/dist/database/migrate.js.map +1 -0
  81. package/dist/database/schema.sql +159 -0
  82. package/dist/npm-client/context-injector.d.ts +106 -0
  83. package/dist/npm-client/context-injector.d.ts.map +1 -0
  84. package/dist/npm-client/context-injector.js +296 -0
  85. package/dist/npm-client/context-injector.js.map +1 -0
  86. package/dist/npm-client/index.d.ts +42 -0
  87. package/dist/npm-client/index.d.ts.map +1 -0
  88. package/dist/npm-client/index.js +43 -0
  89. package/dist/npm-client/index.js.map +1 -0
  90. package/dist/npm-client/memento-client.d.ts +114 -0
  91. package/dist/npm-client/memento-client.d.ts.map +1 -0
  92. package/dist/npm-client/memento-client.js +391 -0
  93. package/dist/npm-client/memento-client.js.map +1 -0
  94. package/dist/npm-client/memory-manager.d.ts +137 -0
  95. package/dist/npm-client/memory-manager.d.ts.map +1 -0
  96. package/dist/npm-client/memory-manager.js +341 -0
  97. package/dist/npm-client/memory-manager.js.map +1 -0
  98. package/dist/npm-client/types.d.ts +216 -0
  99. package/dist/npm-client/types.d.ts.map +1 -0
  100. package/dist/npm-client/types.js +44 -0
  101. package/dist/npm-client/types.js.map +1 -0
  102. package/dist/npm-client/utils.d.ts +91 -0
  103. package/dist/npm-client/utils.d.ts.map +1 -0
  104. package/dist/npm-client/utils.js +351 -0
  105. package/dist/npm-client/utils.js.map +1 -0
  106. package/dist/scripts/copy-assets.d.ts +3 -0
  107. package/dist/scripts/copy-assets.d.ts.map +1 -0
  108. package/dist/scripts/copy-assets.js +31 -0
  109. package/dist/scripts/copy-assets.js.map +1 -0
  110. package/dist/server/http-server.d.ts +28 -0
  111. package/dist/server/http-server.d.ts.map +1 -0
  112. package/dist/server/http-server.js +930 -0
  113. package/dist/server/http-server.js.map +1 -0
  114. package/dist/server/index-backup.d.ts +5 -0
  115. package/dist/server/index-backup.d.ts.map +1 -0
  116. package/dist/server/index-backup.js +793 -0
  117. package/dist/server/index-backup.js.map +1 -0
  118. package/dist/server/index-refactored.d.ts +6 -0
  119. package/dist/server/index-refactored.d.ts.map +1 -0
  120. package/dist/server/index-refactored.js +206 -0
  121. package/dist/server/index-refactored.js.map +1 -0
  122. package/dist/server/index.d.ts +12 -0
  123. package/dist/server/index.d.ts.map +1 -0
  124. package/dist/server/index.js +301 -0
  125. package/dist/server/index.js.map +1 -0
  126. package/dist/server/simple-mcp-server.d.ts +8 -0
  127. package/dist/server/simple-mcp-server.d.ts.map +1 -0
  128. package/dist/server/simple-mcp-server.js +152 -0
  129. package/dist/server/simple-mcp-server.js.map +1 -0
  130. package/dist/services/async-optimizer.d.ts +136 -0
  131. package/dist/services/async-optimizer.d.ts.map +1 -0
  132. package/dist/services/async-optimizer.js +406 -0
  133. package/dist/services/async-optimizer.js.map +1 -0
  134. package/dist/services/batch-scheduler.d.ts +156 -0
  135. package/dist/services/batch-scheduler.d.ts.map +1 -0
  136. package/dist/services/batch-scheduler.js +612 -0
  137. package/dist/services/batch-scheduler.js.map +1 -0
  138. package/dist/services/cache-service.d.ts +168 -0
  139. package/dist/services/cache-service.d.ts.map +1 -0
  140. package/dist/services/cache-service.js +360 -0
  141. package/dist/services/cache-service.js.map +1 -0
  142. package/dist/services/database-optimizer.d.ts +110 -0
  143. package/dist/services/database-optimizer.d.ts.map +1 -0
  144. package/dist/services/database-optimizer.js +369 -0
  145. package/dist/services/database-optimizer.js.map +1 -0
  146. package/dist/services/embedding-provider-factory.d.ts +62 -0
  147. package/dist/services/embedding-provider-factory.d.ts.map +1 -0
  148. package/dist/services/embedding-provider-factory.js +152 -0
  149. package/dist/services/embedding-provider-factory.js.map +1 -0
  150. package/dist/services/embedding-service.d.ts +95 -0
  151. package/dist/services/embedding-service.d.ts.map +1 -0
  152. package/dist/services/embedding-service.js +276 -0
  153. package/dist/services/embedding-service.js.map +1 -0
  154. package/dist/services/error-logging-service.d.ts +134 -0
  155. package/dist/services/error-logging-service.d.ts.map +1 -0
  156. package/dist/services/error-logging-service.js +271 -0
  157. package/dist/services/error-logging-service.js.map +1 -0
  158. package/dist/services/forgetting-policy-service.d.ts +94 -0
  159. package/dist/services/forgetting-policy-service.d.ts.map +1 -0
  160. package/dist/services/forgetting-policy-service.js +233 -0
  161. package/dist/services/forgetting-policy-service.js.map +1 -0
  162. package/dist/services/gemini-embedding-service.d.ts +82 -0
  163. package/dist/services/gemini-embedding-service.d.ts.map +1 -0
  164. package/dist/services/gemini-embedding-service.js +232 -0
  165. package/dist/services/gemini-embedding-service.js.map +1 -0
  166. package/dist/services/lightweight-embedding-service.d.ts +95 -0
  167. package/dist/services/lightweight-embedding-service.d.ts.map +1 -0
  168. package/dist/services/lightweight-embedding-service.js +263 -0
  169. package/dist/services/lightweight-embedding-service.js.map +1 -0
  170. package/dist/services/memory-embedding-service.d.ts +69 -0
  171. package/dist/services/memory-embedding-service.d.ts.map +1 -0
  172. package/dist/services/memory-embedding-service.js +223 -0
  173. package/dist/services/memory-embedding-service.js.map +1 -0
  174. package/dist/services/minilm-embedding-service.d.ts +92 -0
  175. package/dist/services/minilm-embedding-service.d.ts.map +1 -0
  176. package/dist/services/minilm-embedding-service.js +216 -0
  177. package/dist/services/minilm-embedding-service.js.map +1 -0
  178. package/dist/services/performance-alert-service.d.ts +142 -0
  179. package/dist/services/performance-alert-service.d.ts.map +1 -0
  180. package/dist/services/performance-alert-service.js +366 -0
  181. package/dist/services/performance-alert-service.js.map +1 -0
  182. package/dist/services/performance-monitor.d.ts +144 -0
  183. package/dist/services/performance-monitor.d.ts.map +1 -0
  184. package/dist/services/performance-monitor.js +416 -0
  185. package/dist/services/performance-monitor.js.map +1 -0
  186. package/dist/services/performance-monitoring-integration.d.ts +77 -0
  187. package/dist/services/performance-monitoring-integration.d.ts.map +1 -0
  188. package/dist/services/performance-monitoring-integration.js +177 -0
  189. package/dist/services/performance-monitoring-integration.js.map +1 -0
  190. package/dist/services/unified-embedding-service.d.ts +75 -0
  191. package/dist/services/unified-embedding-service.d.ts.map +1 -0
  192. package/dist/services/unified-embedding-service.js +211 -0
  193. package/dist/services/unified-embedding-service.js.map +1 -0
  194. package/dist/test/debug-http-v2.d.ts +5 -0
  195. package/dist/test/debug-http-v2.d.ts.map +1 -0
  196. package/dist/test/debug-http-v2.js +28 -0
  197. package/dist/test/debug-http-v2.js.map +1 -0
  198. package/dist/test/performance-benchmark.d.ts +57 -0
  199. package/dist/test/performance-benchmark.d.ts.map +1 -0
  200. package/dist/test/performance-benchmark.js +427 -0
  201. package/dist/test/performance-benchmark.js.map +1 -0
  202. package/dist/test/test-alerts-direct.d.ts +7 -0
  203. package/dist/test/test-alerts-direct.d.ts.map +1 -0
  204. package/dist/test/test-alerts-direct.js +101 -0
  205. package/dist/test/test-alerts-direct.js.map +1 -0
  206. package/dist/test/test-batch-scheduler.d.ts +2 -0
  207. package/dist/test/test-batch-scheduler.d.ts.map +1 -0
  208. package/dist/test/test-batch-scheduler.js +156 -0
  209. package/dist/test/test-batch-scheduler.js.map +1 -0
  210. package/dist/test/test-client.d.ts +5 -0
  211. package/dist/test/test-client.d.ts.map +1 -0
  212. package/dist/test/test-client.js +86 -0
  213. package/dist/test/test-client.js.map +1 -0
  214. package/dist/test/test-embedding.d.ts +6 -0
  215. package/dist/test/test-embedding.d.ts.map +1 -0
  216. package/dist/test/test-embedding.js +142 -0
  217. package/dist/test/test-embedding.js.map +1 -0
  218. package/dist/test/test-error-logging.d.ts +7 -0
  219. package/dist/test/test-error-logging.d.ts.map +1 -0
  220. package/dist/test/test-error-logging.js +105 -0
  221. package/dist/test/test-error-logging.js.map +1 -0
  222. package/dist/test/test-forgetting.d.ts +6 -0
  223. package/dist/test/test-forgetting.d.ts.map +1 -0
  224. package/dist/test/test-forgetting.js +154 -0
  225. package/dist/test/test-forgetting.js.map +1 -0
  226. package/dist/test/test-gemini-embedding.d.ts +7 -0
  227. package/dist/test/test-gemini-embedding.d.ts.map +1 -0
  228. package/dist/test/test-gemini-embedding.js +134 -0
  229. package/dist/test/test-gemini-embedding.js.map +1 -0
  230. package/dist/test/test-http-server-v2-simple.d.ts +6 -0
  231. package/dist/test/test-http-server-v2-simple.d.ts.map +1 -0
  232. package/dist/test/test-http-server-v2-simple.js +131 -0
  233. package/dist/test/test-http-server-v2-simple.js.map +1 -0
  234. package/dist/test/test-http-server-v2.d.ts +7 -0
  235. package/dist/test/test-http-server-v2.d.ts.map +1 -0
  236. package/dist/test/test-http-server-v2.js +529 -0
  237. package/dist/test/test-http-server-v2.js.map +1 -0
  238. package/dist/test/test-lightweight-embedding.d.ts +6 -0
  239. package/dist/test/test-lightweight-embedding.d.ts.map +1 -0
  240. package/dist/test/test-lightweight-embedding.js +189 -0
  241. package/dist/test/test-lightweight-embedding.js.map +1 -0
  242. package/dist/test/test-m1-completion.d.ts +7 -0
  243. package/dist/test/test-m1-completion.d.ts.map +1 -0
  244. package/dist/test/test-m1-completion.js +124 -0
  245. package/dist/test/test-m1-completion.js.map +1 -0
  246. package/dist/test/test-memory-injection-prompt.d.ts +2 -0
  247. package/dist/test/test-memory-injection-prompt.d.ts.map +1 -0
  248. package/dist/test/test-memory-injection-prompt.js +299 -0
  249. package/dist/test/test-memory-injection-prompt.js.map +1 -0
  250. package/dist/test/test-performance-alerts.d.ts +7 -0
  251. package/dist/test/test-performance-alerts.d.ts.map +1 -0
  252. package/dist/test/test-performance-alerts.js +109 -0
  253. package/dist/test/test-performance-alerts.js.map +1 -0
  254. package/dist/test/test-performance-monitor.d.ts +2 -0
  255. package/dist/test/test-performance-monitor.d.ts.map +1 -0
  256. package/dist/test/test-performance-monitor.js +182 -0
  257. package/dist/test/test-performance-monitor.js.map +1 -0
  258. package/dist/test/test-performance-monitoring.d.ts +6 -0
  259. package/dist/test/test-performance-monitoring.d.ts.map +1 -0
  260. package/dist/test/test-performance-monitoring.js +156 -0
  261. package/dist/test/test-performance-monitoring.js.map +1 -0
  262. package/dist/test/test-search.d.ts +5 -0
  263. package/dist/test/test-search.d.ts.map +1 -0
  264. package/dist/test/test-search.js +141 -0
  265. package/dist/test/test-search.js.map +1 -0
  266. package/dist/test/test-simple-alerts.d.ts +6 -0
  267. package/dist/test/test-simple-alerts.d.ts.map +1 -0
  268. package/dist/test/test-simple-alerts.js +106 -0
  269. package/dist/test/test-simple-alerts.js.map +1 -0
  270. package/dist/test/test-vector-search-engine.d.ts +2 -0
  271. package/dist/test/test-vector-search-engine.d.ts.map +1 -0
  272. package/dist/test/test-vector-search-engine.js +225 -0
  273. package/dist/test/test-vector-search-engine.js.map +1 -0
  274. package/dist/tools/base-tool.d.ts +64 -0
  275. package/dist/tools/base-tool.d.ts.map +1 -0
  276. package/dist/tools/base-tool.js +158 -0
  277. package/dist/tools/base-tool.js.map +1 -0
  278. package/dist/tools/cleanup-memory-tool.d.ts +10 -0
  279. package/dist/tools/cleanup-memory-tool.d.ts.map +1 -0
  280. package/dist/tools/cleanup-memory-tool.js +66 -0
  281. package/dist/tools/cleanup-memory-tool.js.map +1 -0
  282. package/dist/tools/database-optimize-tool.d.ts +10 -0
  283. package/dist/tools/database-optimize-tool.d.ts.map +1 -0
  284. package/dist/tools/database-optimize-tool.js +64 -0
  285. package/dist/tools/database-optimize-tool.js.map +1 -0
  286. package/dist/tools/error-stats.d.ts +93 -0
  287. package/dist/tools/error-stats.d.ts.map +1 -0
  288. package/dist/tools/error-stats.js +115 -0
  289. package/dist/tools/error-stats.js.map +1 -0
  290. package/dist/tools/forget-tool.d.ts +63 -0
  291. package/dist/tools/forget-tool.d.ts.map +1 -0
  292. package/dist/tools/forget-tool.js +340 -0
  293. package/dist/tools/forget-tool.js.map +1 -0
  294. package/dist/tools/forgetting-stats-tool.d.ts +10 -0
  295. package/dist/tools/forgetting-stats-tool.d.ts.map +1 -0
  296. package/dist/tools/forgetting-stats-tool.js +37 -0
  297. package/dist/tools/forgetting-stats-tool.js.map +1 -0
  298. package/dist/tools/index.d.ts +33 -0
  299. package/dist/tools/index.d.ts.map +1 -0
  300. package/dist/tools/index.js +55 -0
  301. package/dist/tools/index.js.map +1 -0
  302. package/dist/tools/memory-injection-prompt.d.ts +31 -0
  303. package/dist/tools/memory-injection-prompt.d.ts.map +1 -0
  304. package/dist/tools/memory-injection-prompt.js +203 -0
  305. package/dist/tools/memory-injection-prompt.js.map +1 -0
  306. package/dist/tools/performance-alerts.d.ts +127 -0
  307. package/dist/tools/performance-alerts.d.ts.map +1 -0
  308. package/dist/tools/performance-alerts.js +208 -0
  309. package/dist/tools/performance-alerts.js.map +1 -0
  310. package/dist/tools/performance-stats-tool.d.ts +10 -0
  311. package/dist/tools/performance-stats-tool.d.ts.map +1 -0
  312. package/dist/tools/performance-stats-tool.js +38 -0
  313. package/dist/tools/performance-stats-tool.js.map +1 -0
  314. package/dist/tools/pin-tool.d.ts +39 -0
  315. package/dist/tools/pin-tool.d.ts.map +1 -0
  316. package/dist/tools/pin-tool.js +211 -0
  317. package/dist/tools/pin-tool.js.map +1 -0
  318. package/dist/tools/recall-tool.d.ts +27 -0
  319. package/dist/tools/recall-tool.d.ts.map +1 -0
  320. package/dist/tools/recall-tool.js +335 -0
  321. package/dist/tools/recall-tool.js.map +1 -0
  322. package/dist/tools/remember-tool.d.ts +10 -0
  323. package/dist/tools/remember-tool.d.ts.map +1 -0
  324. package/dist/tools/remember-tool.js +101 -0
  325. package/dist/tools/remember-tool.js.map +1 -0
  326. package/dist/tools/resolve-error.d.ts +54 -0
  327. package/dist/tools/resolve-error.d.ts.map +1 -0
  328. package/dist/tools/resolve-error.js +63 -0
  329. package/dist/tools/resolve-error.js.map +1 -0
  330. package/dist/tools/tool-registry.d.ts +134 -0
  331. package/dist/tools/tool-registry.d.ts.map +1 -0
  332. package/dist/tools/tool-registry.js +337 -0
  333. package/dist/tools/tool-registry.js.map +1 -0
  334. package/dist/tools/types.d.ts +56 -0
  335. package/dist/tools/types.d.ts.map +1 -0
  336. package/dist/tools/types.js +23 -0
  337. package/dist/tools/types.js.map +1 -0
  338. package/dist/tools/unpin-tool.d.ts +43 -0
  339. package/dist/tools/unpin-tool.d.ts.map +1 -0
  340. package/dist/tools/unpin-tool.js +233 -0
  341. package/dist/tools/unpin-tool.js.map +1 -0
  342. package/dist/types/embedding.types.d.ts +65 -0
  343. package/dist/types/embedding.types.d.ts.map +1 -0
  344. package/dist/types/embedding.types.js +6 -0
  345. package/dist/types/embedding.types.js.map +1 -0
  346. package/dist/types/index.d.ts +103 -0
  347. package/dist/types/index.d.ts.map +1 -0
  348. package/dist/types/index.js +5 -0
  349. package/dist/types/index.js.map +1 -0
  350. package/dist/utils/database.d.ts +62 -0
  351. package/dist/utils/database.d.ts.map +1 -0
  352. package/dist/utils/database.js +399 -0
  353. package/dist/utils/database.js.map +1 -0
  354. package/dist/utils/stopwords.d.ts +18 -0
  355. package/dist/utils/stopwords.d.ts.map +1 -0
  356. package/dist/utils/stopwords.js +117 -0
  357. package/dist/utils/stopwords.js.map +1 -0
  358. package/docker-compose.dev.yml +50 -0
  359. package/docker-compose.prod.yml +77 -0
  360. package/docker-compose.yml +43 -0
  361. package/docs/en/Memento-Goals.md +217 -0
  362. package/docs/en/Memento-M1-DetailSpecs.md +130 -0
  363. package/docs/en/Memento-Milestones.md +135 -0
  364. package/docs/en/Search-Ranking-Memory-Decay-Formulas.md +177 -0
  365. package/docs/en/api-reference.md +658 -0
  366. package/docs/en/architecture.md +1302 -0
  367. package/docs/en/developer-guide.md +1005 -0
  368. package/docs/en/user-manual.md +595 -0
  369. package/docs/ko/Memento-Goals.md +217 -0
  370. package/docs/ko/Memento-M1-DetailSpecs.md +130 -0
  371. package/docs/ko/Memento-Milestones.md +134 -0
  372. package/docs/ko/Search-Ranking-Memory-Decay-Formulas.md +177 -0
  373. package/docs/ko/api-reference.md +658 -0
  374. package/docs/ko/architecture.md +1302 -0
  375. package/docs/ko/developer-guide.md +1006 -0
  376. package/docs/ko/embedding-api-reference.md +122 -0
  377. package/docs/ko/embedding-configuration.md +62 -0
  378. package/docs/ko/embedding-performance-benchmark.md +62 -0
  379. package/docs/ko/embedding-service-guide.md +314 -0
  380. package/docs/ko/user-manual.md +595 -0
  381. package/env.example +49 -0
  382. package/install.sh +191 -0
  383. package/mcp-http-client.js +218 -0
  384. package/mcp.json +0 -0
  385. package/package.json +125 -0
  386. package/packages/mcp-client/docs/API-REFERENCE.md +560 -0
  387. package/packages/mcp-client/docs/BEST-PRACTICES.md +564 -0
  388. package/packages/mcp-client/docs/MIGRATION-GUIDE.md +344 -0
  389. package/packages/mcp-client/docs/PERFORMANCE-GUIDE.md +476 -0
  390. package/packages/mcp-client/docs/TROUBLESHOOTING.md +564 -0
  391. package/packages/mcp-client/package-lock.json +907 -0
  392. package/packages/mcp-client/package.json +58 -0
  393. package/packages/mcp-client/performance-optimizer.js +428 -0
  394. package/packages/mcp-client/test-basic.js +65 -0
  395. package/packages/mcp-client/test-integration.js +366 -0
  396. package/scripts/auto-setup.js +234 -0
  397. package/scripts/backup-daily.bat +28 -0
  398. package/scripts/backup-embeddings.js +108 -0
  399. package/scripts/check-db-integrity.js +93 -0
  400. package/scripts/debug-embeddings.js +184 -0
  401. package/scripts/direct-sql-migration.sql +36 -0
  402. package/scripts/docker-migration.sh +105 -0
  403. package/scripts/fix-migration.js +93 -0
  404. package/scripts/fix-vector-dimensions.js +206 -0
  405. package/scripts/migrate-embedding-data.js +307 -0
  406. package/scripts/regenerate-embeddings.js +144 -0
  407. package/scripts/restore-legacy.ps1 +60 -0
  408. package/scripts/restore-legacy.sh +62 -0
  409. package/scripts/run-migration.js +122 -0
  410. package/scripts/safe-migration.js +150 -0
  411. package/scripts/simple-migrate.js +41 -0
  412. package/scripts/simple-update.js +123 -0
  413. package/scripts/start-container.sh +10 -0
  414. package/src/algorithms/forgetting-algorithm.spec.ts +538 -0
  415. package/src/algorithms/forgetting-algorithm.ts +243 -0
  416. package/src/algorithms/hybrid-search-engine.spec.ts +484 -0
  417. package/src/algorithms/hybrid-search-engine.ts +489 -0
  418. package/src/algorithms/search-engine.spec.ts +429 -0
  419. package/src/algorithms/search-engine.ts +392 -0
  420. package/src/algorithms/search-ranking.spec.ts +293 -0
  421. package/src/algorithms/search-ranking.ts +407 -0
  422. package/src/algorithms/spaced-repetition.spec.ts +510 -0
  423. package/src/algorithms/spaced-repetition.ts +238 -0
  424. package/src/algorithms/vector-search-engine.ts +505 -0
  425. package/src/client/index.spec.ts +427 -0
  426. package/src/client/index.ts +222 -0
  427. package/src/config/index.spec.ts +339 -0
  428. package/src/config/index.ts +106 -0
  429. package/src/database/init.spec.ts +239 -0
  430. package/src/database/init.ts +130 -0
  431. package/src/database/migrate.spec.ts +293 -0
  432. package/src/database/migrate.ts +94 -0
  433. package/src/database/migrations/001_add_embedding_metadata.sql +29 -0
  434. package/src/database/schema.sql +159 -0
  435. package/src/npm-client/context-injector.spec.ts +335 -0
  436. package/src/npm-client/context-injector.ts +412 -0
  437. package/src/npm-client/index.spec.ts +108 -0
  438. package/src/npm-client/index.ts +96 -0
  439. package/src/npm-client/memento-client.spec.ts +549 -0
  440. package/src/npm-client/memento-client.ts +501 -0
  441. package/src/npm-client/memory-manager.spec.ts +374 -0
  442. package/src/npm-client/memory-manager.ts +414 -0
  443. package/src/npm-client/types.spec.ts +427 -0
  444. package/src/npm-client/types.ts +296 -0
  445. package/src/npm-client/utils.spec.ts +355 -0
  446. package/src/npm-client/utils.ts +423 -0
  447. package/src/scripts/copy-assets.js +37 -0
  448. package/src/server/http-server.spec.ts +648 -0
  449. package/src/server/http-server.ts +1030 -0
  450. package/src/server/index-backup.ts +875 -0
  451. package/src/server/index-refactored.ts +237 -0
  452. package/src/server/index.spec.ts +281 -0
  453. package/src/server/index.ts +347 -0
  454. package/src/server/simple-mcp-server.spec.ts +207 -0
  455. package/src/server/simple-mcp-server.ts +173 -0
  456. package/src/services/async-optimizer.spec.ts +569 -0
  457. package/src/services/async-optimizer.ts +484 -0
  458. package/src/services/batch-scheduler.ts +759 -0
  459. package/src/services/cache-service.spec.ts +372 -0
  460. package/src/services/cache-service.ts +434 -0
  461. package/src/services/database-optimizer.spec.ts +344 -0
  462. package/src/services/database-optimizer.ts +450 -0
  463. package/src/services/embedding-provider-factory.ts +173 -0
  464. package/src/services/embedding-service.spec.ts +342 -0
  465. package/src/services/embedding-service.ts +333 -0
  466. package/src/services/error-logging-service.spec.ts +416 -0
  467. package/src/services/error-logging-service.ts +383 -0
  468. package/src/services/forgetting-policy-service.spec.ts +140 -0
  469. package/src/services/forgetting-policy-service.ts +334 -0
  470. package/src/services/gemini-embedding-service.spec.ts +463 -0
  471. package/src/services/gemini-embedding-service.ts +283 -0
  472. package/src/services/lightweight-embedding-service.spec.ts +458 -0
  473. package/src/services/lightweight-embedding-service.ts +324 -0
  474. package/src/services/memory-embedding-service.spec.ts +417 -0
  475. package/src/services/memory-embedding-service.ts +289 -0
  476. package/src/services/minilm-embedding-service.spec.ts +104 -0
  477. package/src/services/minilm-embedding-service.ts +262 -0
  478. package/src/services/performance-alert-service.spec.ts +517 -0
  479. package/src/services/performance-alert-service.ts +477 -0
  480. package/src/services/performance-monitor.spec.ts +401 -0
  481. package/src/services/performance-monitor.ts +532 -0
  482. package/src/services/performance-monitoring-integration.spec.ts +478 -0
  483. package/src/services/performance-monitoring-integration.ts.bak +276 -0
  484. package/src/services/unified-embedding-service.spec.ts +224 -0
  485. package/src/services/unified-embedding-service.ts +255 -0
  486. package/src/test/debug-http-v2.ts +30 -0
  487. package/src/test/embedding-integration-test.spec.ts +295 -0
  488. package/src/test/embedding-integration-test.ts +295 -0
  489. package/src/test/embedding-performance-benchmark.spec.ts +354 -0
  490. package/src/test/embedding-performance-benchmark.ts +312 -0
  491. package/src/test/performance-benchmark.ts +565 -0
  492. package/src/test/test-alerts-direct.ts +136 -0
  493. package/src/test/test-batch-scheduler-simple.spec.ts +122 -0
  494. package/src/test/test-batch-scheduler.spec.ts +453 -0
  495. package/src/test/test-batch-scheduler.ts +182 -0
  496. package/src/test/test-client.ts +97 -0
  497. package/src/test/test-embedding.ts +153 -0
  498. package/src/test/test-error-handling.spec.ts +575 -0
  499. package/src/test/test-error-logging.ts +117 -0
  500. package/src/test/test-forgetting.ts +162 -0
  501. package/src/test/test-gemini-embedding.ts +159 -0
  502. package/src/test/test-http-server-v2-simple.ts +147 -0
  503. package/src/test/test-http-server-v2.ts +586 -0
  504. package/src/test/test-hybrid-search-engine.spec.ts +521 -0
  505. package/src/test/test-integration-fixed.spec.ts +612 -0
  506. package/src/test/test-integration.spec.ts +463 -0
  507. package/src/test/test-lightweight-embedding.ts +208 -0
  508. package/src/test/test-m1-completion.spec.ts +614 -0
  509. package/src/test/test-m1-completion.ts +141 -0
  510. package/src/test/test-m1-integration.spec.ts +514 -0
  511. package/src/test/test-memory-injection-prompt.spec.ts +650 -0
  512. package/src/test/test-memory-injection-prompt.ts +391 -0
  513. package/src/test/test-performance-alerts.ts +125 -0
  514. package/src/test/test-performance-monitor-updates.spec.ts +490 -0
  515. package/src/test/test-performance-monitor.spec.ts +284 -0
  516. package/src/test/test-performance-monitor.ts +228 -0
  517. package/src/test/test-performance-monitoring.ts +171 -0
  518. package/src/test/test-search.ts +151 -0
  519. package/src/test/test-simple-alerts.ts +136 -0
  520. package/src/test/test-vector-search-engine.spec.ts +408 -0
  521. package/src/test/test-vector-search-engine.ts +303 -0
  522. package/src/tools/base-tool.ts +189 -0
  523. package/src/tools/cleanup-memory-tool.ts +77 -0
  524. package/src/tools/database-optimize-tool.ts +79 -0
  525. package/src/tools/error-stats.ts +119 -0
  526. package/src/tools/forget-tool.spec.ts +613 -0
  527. package/src/tools/forget-tool.ts +454 -0
  528. package/src/tools/forgetting-stats-tool.ts +47 -0
  529. package/src/tools/index.ts +71 -0
  530. package/src/tools/memory-injection-prompt.ts +257 -0
  531. package/src/tools/performance-alerts.ts +226 -0
  532. package/src/tools/performance-stats-tool.ts +48 -0
  533. package/src/tools/pin-tool.spec.ts +497 -0
  534. package/src/tools/pin-tool.ts +277 -0
  535. package/src/tools/recall-tool.spec.ts +475 -0
  536. package/src/tools/recall-tool.ts +389 -0
  537. package/src/tools/remember-tool.spec.ts +469 -0
  538. package/src/tools/remember-tool.ts +112 -0
  539. package/src/tools/resolve-error.ts +69 -0
  540. package/src/tools/tool-registry.ts +417 -0
  541. package/src/tools/types.ts +63 -0
  542. package/src/tools/unpin-tool.spec.ts +549 -0
  543. package/src/tools/unpin-tool.ts +306 -0
  544. package/src/types/embedding.types.ts +78 -0
  545. package/src/types/index.spec.ts +420 -0
  546. package/src/types/index.ts +117 -0
  547. package/src/utils/database.spec.ts +77 -0
  548. package/src/utils/database.ts +458 -0
  549. package/src/utils/stopwords.ts +128 -0
  550. package/start-docker-setup.bat +38 -0
  551. package/static/logo.png +0 -0
  552. package/static/memento_logo.svg +2 -0
  553. package/test-docker.js +103 -0
  554. package/tsconfig.json +46 -0
  555. package/vitest.config.ts +23 -0
@@ -0,0 +1,392 @@
1
+ /**
2
+ * 개선된 검색 엔진 구현
3
+ * FTS5 + 랭킹 알고리즘 + 필터링 결합
4
+ */
5
+
6
+ import { SearchRanking } from './search-ranking.js';
7
+ import type { MemorySearchResult, MemorySearchFilters } from '../types/index.js';
8
+ import { getStopWords } from '../utils/stopwords.js';
9
+
10
+ export interface SearchQuery {
11
+ query: string;
12
+ filters?: MemorySearchFilters | undefined;
13
+ limit?: number | undefined;
14
+ }
15
+
16
+ export interface SearchResult {
17
+ id: string;
18
+ content: string;
19
+ type: string;
20
+ importance: number;
21
+ created_at: string;
22
+ last_accessed?: string;
23
+ pinned: boolean;
24
+ tags?: string[];
25
+ score: number;
26
+ recall_reason: string;
27
+ }
28
+
29
+ export class SearchEngine {
30
+ private ranking: SearchRanking;
31
+
32
+ constructor() {
33
+ this.ranking = new SearchRanking();
34
+ }
35
+
36
+ /**
37
+ * 개선된 검색 구현 - FTS5 최적화
38
+ */
39
+ async search(
40
+ db: any,
41
+ query: SearchQuery
42
+ ): Promise<{ items: SearchResult[], total_count: number, query_time: number }> {
43
+ const startTime = process.hrtime.bigint();
44
+ const { query: searchQuery, filters, limit = 10 } = query;
45
+
46
+ // 1. ID 필터가 있으면 내용 검색 조건을 건너뛰기
47
+ const hasIdFilter = filters?.id && filters.id.length > 0;
48
+
49
+ let sql: string;
50
+ const params: any[] = [];
51
+
52
+ // 2. FTS5 검색 사용 (ID 필터가 없고 검색어가 있을 때)
53
+ if (!hasIdFilter && searchQuery.trim().length > 0) {
54
+ // FTS5 사용 가능 여부 확인
55
+ const ftsAvailable = await this.checkFTS5Availability(db);
56
+
57
+ if (ftsAvailable) {
58
+ const ftsQuery = this.buildFTSQuery(searchQuery);
59
+ sql = `
60
+ SELECT
61
+ m.id, m.content, m.type, m.importance, m.created_at,
62
+ m.last_accessed, m.pinned, m.tags, m.source,
63
+ memory_item_fts.rank as fts_rank
64
+ FROM memory_item_fts
65
+ JOIN memory_item m ON memory_item_fts.rowid = m.rowid
66
+ WHERE memory_item_fts MATCH ?
67
+ `;
68
+ params.push(ftsQuery);
69
+ } else {
70
+ // FTS5가 없으면 기본 LIKE 검색 사용
71
+ const likeQuery = `%${searchQuery}%`;
72
+ sql = `
73
+ SELECT
74
+ m.id, m.content, m.type, m.importance, m.created_at,
75
+ m.last_accessed, m.pinned, m.tags, m.source,
76
+ 0 as fts_rank
77
+ FROM memory_item m
78
+ WHERE m.content LIKE ? OR m.tags LIKE ? OR m.source LIKE ?
79
+ `;
80
+ params.push(likeQuery, likeQuery, likeQuery);
81
+ }
82
+ } else {
83
+ // 3. 기본 SQL 쿼리 구성 (ID 필터가 있거나 검색어가 없을 때)
84
+ sql = `
85
+ SELECT
86
+ m.id, m.content, m.type, m.importance, m.created_at,
87
+ m.last_accessed, m.pinned, m.tags, m.source,
88
+ 0 as fts_rank
89
+ FROM memory_item m
90
+ `;
91
+
92
+ // 내용 검색 조건 (검색어가 있을 때만)
93
+ if (!hasIdFilter && searchQuery.trim().length > 0) {
94
+ const likeQuery = `%${searchQuery}%`;
95
+ sql += ` WHERE m.content LIKE ?`;
96
+ params.push(likeQuery);
97
+ }
98
+ }
99
+
100
+ // 4. 필터 조건 추가
101
+ const conditions: string[] = [];
102
+
103
+ if (filters?.id && filters.id.length > 0) {
104
+ conditions.push(`m.id IN (${filters.id.map(() => '?').join(',')})`);
105
+ params.push(...filters.id);
106
+ }
107
+
108
+ if (filters?.type && filters.type.length > 0) {
109
+ conditions.push(`m.type IN (${filters.type.map(() => '?').join(',')})`);
110
+ params.push(...filters.type);
111
+ }
112
+
113
+ if (filters?.privacy_scope && filters.privacy_scope.length > 0) {
114
+ conditions.push(`m.privacy_scope IN (${filters.privacy_scope.map(() => '?').join(',')})`);
115
+ params.push(...filters.privacy_scope);
116
+ }
117
+
118
+ if (filters?.pinned !== undefined) {
119
+ conditions.push(`m.pinned = ?`);
120
+ params.push(filters.pinned ? 1 : 0); // boolean을 숫자로 변환
121
+ }
122
+
123
+ if (filters?.time_from) {
124
+ conditions.push(`m.created_at >= ?`);
125
+ params.push(filters.time_from);
126
+ }
127
+
128
+ if (filters?.time_to) {
129
+ conditions.push(`m.created_at <= ?`);
130
+ params.push(filters.time_to);
131
+ }
132
+
133
+ // WHERE 절 추가
134
+ if (conditions.length > 0) {
135
+ const whereClause = sql.includes('WHERE') ? ' AND ' : ' WHERE ';
136
+ sql += whereClause + conditions.join(' AND ');
137
+ }
138
+
139
+ // 5. 결과 제한 및 정렬 최적화
140
+ sql += ` ORDER BY fts_rank DESC, m.created_at DESC LIMIT ?`;
141
+ params.push(limit * 3); // FTS5 랭킹을 고려하여 더 많은 후보 가져오기
142
+
143
+ // 6. 데이터베이스 쿼리 실행
144
+ console.log('🔍 검색 쿼리:', sql);
145
+ console.log('🔍 검색 파라미터:', params);
146
+ const results = await this.executeQuery(db, sql, params);
147
+ console.log('🔍 검색 결과 개수:', results.length);
148
+
149
+ // 7. 랭킹 알고리즘 적용 (FTS5 랭킹 활용)
150
+ const rankedResults = this.applyRanking(results, searchQuery);
151
+
152
+ // 8. 최종 결과 반환 (limit 적용)
153
+ const finalResults = rankedResults.slice(0, limit);
154
+
155
+ // 9. 쿼리 시간 측정
156
+ const endTime = process.hrtime.bigint();
157
+ const queryTime = Number(endTime - startTime) / 1_000_000; // 밀리초로 변환
158
+
159
+ return {
160
+ items: finalResults,
161
+ total_count: finalResults.length,
162
+ query_time: queryTime
163
+ };
164
+ }
165
+
166
+ /**
167
+ * FTS5 검색 쿼리 구성
168
+ * 아키텍처 문서에 따른 쿼리 전처리 구현
169
+ */
170
+ private buildFTSQuery(query: string): string {
171
+ console.log('🔍 원본 쿼리:', `"${query}"`);
172
+
173
+ // 1. 쿼리 전처리
174
+ const preprocessedQuery = this.preprocessQuery(query);
175
+ console.log('🔍 전처리 후:', `"${preprocessedQuery}"`);
176
+
177
+ if (preprocessedQuery.length === 0) {
178
+ console.log('🔍 빈 쿼리, 모든 문서 검색');
179
+ return '*'; // 빈 쿼리인 경우 모든 문서 검색
180
+ }
181
+
182
+ // 2. FTS5 안전 쿼리 생성
183
+ const safeQuery = this.makeFTSSafe(preprocessedQuery);
184
+ console.log('🔍 FTS5 안전 쿼리:', `"${safeQuery}"`);
185
+
186
+ if (safeQuery.length === 0) {
187
+ console.log('🔍 안전 쿼리 빈 문자열, 모든 문서 검색');
188
+ return '*';
189
+ }
190
+
191
+ return safeQuery;
192
+ }
193
+
194
+ /**
195
+ * 쿼리 전처리 - 아키텍처 문서의 전처리 과정 구현
196
+ */
197
+ private preprocessQuery(query: string): string {
198
+ // 1. 공백 정규화
199
+ let processed = query.trim().replace(/\s+/g, ' ');
200
+
201
+ // 2. 한글과 영문, 숫자, 공백만 유지 (특수문자 제거)
202
+ processed = processed.replace(/[^a-zA-Z0-9가-힣\s]/g, ' ');
203
+
204
+ // 3. 연속된 공백 제거
205
+ processed = processed.replace(/\s+/g, ' ');
206
+
207
+ // 4. 불용어 제거 (한국어/영어 불용어)
208
+ const stopWords = getStopWords();
209
+ const words = processed.split(' ').filter(word =>
210
+ word.length > 0 && !stopWords.has(word.toLowerCase())
211
+ );
212
+
213
+ // 5. FTS5를 위한 공백으로 구분된 쿼리 반환
214
+ return words.join(' ');
215
+ }
216
+
217
+ /**
218
+ * FTS5 안전 쿼리 생성
219
+ */
220
+ private makeFTSSafe(query: string): string {
221
+ // FTS5에서 특수문자 이스케이프
222
+ return query
223
+ .replace(/"/g, '""') // 따옴표 이스케이프
224
+ .replace(/'/g, "''") // 작은따옴표 이스케이프
225
+ .replace(/[\[\]{}()]/g, ' ') // 대괄호, 중괄호, 소괄호 제거
226
+ .replace(/\s+/g, ' ') // 연속 공백 정리
227
+ .trim();
228
+ }
229
+
230
+ /**
231
+ * 데이터베이스 쿼리 실행
232
+ */
233
+ private async executeQuery(db: any, sql: string, params: any[]): Promise<any[]> {
234
+ // better-sqlite3는 동기적이므로 직접 실행
235
+ try {
236
+ return db.prepare(sql).all(params);
237
+ } catch (error) {
238
+ throw error;
239
+ }
240
+ }
241
+
242
+ /**
243
+ * 랭킹 알고리즘 적용 - FTS5 랭킹 활용
244
+ */
245
+ private applyRanking(results: any[], query: string): SearchResult[] {
246
+ const selectedContents: string[] = [];
247
+
248
+ return results
249
+ .map((row: any) => {
250
+ // FTS5 랭킹이 있으면 활용, 없으면 기본 관련성 계산
251
+ const ftsRank = row.fts_rank || 0;
252
+ const relevance = ftsRank > 0 ?
253
+ Math.min(ftsRank / 100, 1.0) : // FTS5 랭킹을 0-1 범위로 정규화
254
+ this.ranking.calculateRelevance({
255
+ query,
256
+ content: row.content,
257
+ tags: row.tags ? JSON.parse(row.tags) : []
258
+ });
259
+
260
+ // 최근성 계산
261
+ const recency = this.ranking.calculateRecency(
262
+ new Date(row.created_at),
263
+ row.type
264
+ );
265
+
266
+ // 중요도 계산
267
+ const importance = this.ranking.calculateImportance(
268
+ row.importance,
269
+ row.pinned,
270
+ row.type
271
+ );
272
+
273
+ // 사용성 계산 (기본 메트릭 사용)
274
+ const usage = this.ranking.calculateUsage({
275
+ viewCount: 1, // 기본값
276
+ citeCount: 0,
277
+ editCount: 0
278
+ });
279
+
280
+ // 중복 패널티 계산
281
+ const duplicationPenalty = this.ranking.calculateDuplicationPenalty(
282
+ row.content,
283
+ selectedContents
284
+ );
285
+
286
+ // 최종 점수 계산 (FTS5 랭킹 가중치 적용)
287
+ const finalScore = ftsRank > 0 ?
288
+ ftsRank * 0.7 + this.ranking.calculateFinalScore({
289
+ relevance: 0.3,
290
+ recency,
291
+ importance,
292
+ usage,
293
+ duplication_penalty: duplicationPenalty
294
+ }) * 0.3 :
295
+ this.ranking.calculateFinalScore({
296
+ relevance,
297
+ recency,
298
+ importance,
299
+ usage,
300
+ duplication_penalty: duplicationPenalty
301
+ });
302
+
303
+ // 선택된 콘텐츠에 추가 (다양성 확보)
304
+ selectedContents.push(row.content);
305
+
306
+ return {
307
+ id: row.id,
308
+ content: row.content,
309
+ type: row.type,
310
+ importance: row.importance,
311
+ created_at: row.created_at,
312
+ last_accessed: row.last_accessed,
313
+ pinned: row.pinned,
314
+ tags: row.tags ? JSON.parse(row.tags) : [],
315
+ score: finalScore,
316
+ recall_reason: this.generateRecallReason(relevance, recency, importance, finalScore, ftsRank > 0)
317
+ };
318
+ })
319
+ .sort((a, b) => b.score - a.score); // 점수 내림차순 정렬
320
+ }
321
+
322
+ /**
323
+ * FTS5 사용 가능 여부 확인
324
+ */
325
+ private async checkFTS5Availability(db: any): Promise<boolean> {
326
+ try {
327
+ // FTS5 테이블 존재 여부 확인
328
+ const result = db.prepare(`
329
+ SELECT name FROM sqlite_master
330
+ WHERE type='table' AND name='memory_item_fts'
331
+ `).get();
332
+
333
+ if (!result) {
334
+ console.log('⚠️ FTS5 테이블이 존재하지 않음, 기본 검색으로 전환');
335
+ return false;
336
+ }
337
+
338
+ // FTS5 테이블에 데이터가 있는지 확인
339
+ const count = db.prepare('SELECT COUNT(*) as count FROM memory_item_fts').get();
340
+ const hasData = count && count.count > 0;
341
+
342
+ if (!hasData) {
343
+ console.log('⚠️ FTS5 테이블에 데이터가 없음, 기본 검색으로 전환');
344
+ return false;
345
+ }
346
+
347
+ // FTS5 쿼리 테스트
348
+ try {
349
+ db.prepare('SELECT * FROM memory_item_fts LIMIT 1').get();
350
+ console.log('✅ FTS5 사용 가능');
351
+ return true;
352
+ } catch (ftsError) {
353
+ console.log('⚠️ FTS5 쿼리 실패, 기본 검색으로 전환:', ftsError);
354
+ return false;
355
+ }
356
+ } catch (error) {
357
+ console.log('⚠️ FTS5 사용 불가능, 기본 검색으로 전환:', error);
358
+ return false;
359
+ }
360
+ }
361
+
362
+ /**
363
+ * 검색 이유 생성
364
+ */
365
+ private generateRecallReason(
366
+ relevance: number,
367
+ recency: number,
368
+ importance: number,
369
+ finalScore: number,
370
+ isFTS: boolean = false
371
+ ): string {
372
+ const reasons: string[] = [];
373
+
374
+ if (isFTS) {
375
+ reasons.push('FTS5 전문 검색');
376
+ }
377
+ if (relevance > 0.7) {
378
+ reasons.push('높은 관련성');
379
+ }
380
+ if (recency > 0.8) {
381
+ reasons.push('최근 생성');
382
+ }
383
+ if (importance > 0.8) {
384
+ reasons.push('높은 중요도');
385
+ }
386
+ if (finalScore > 0.9) {
387
+ reasons.push('종합 점수 우수');
388
+ }
389
+
390
+ return reasons.length > 0 ? reasons.join(', ') : '일반 검색 결과';
391
+ }
392
+ }
@@ -0,0 +1,293 @@
1
+ import { describe, it, expect } from 'vitest';
2
+ import { SearchRanking } from './search-ranking.js';
3
+
4
+ describe('SearchRanking', () => {
5
+ const ranking = new SearchRanking();
6
+
7
+ describe('calculateFinalScore', () => {
8
+ it('가중치에 따라 최종 점수를 계산한다', () => {
9
+ const score = ranking.calculateFinalScore({
10
+ relevance: 0.9,
11
+ recency: 0.8,
12
+ importance: 0.6,
13
+ usage: 0.4,
14
+ duplication_penalty: 0.2,
15
+ });
16
+
17
+ const expected = 0.5 * 0.9 + 0.2 * 0.8 + 0.2 * 0.6 + 0.1 * 0.4 - 0.15 * 0.2;
18
+ expect(score).toBeCloseTo(expected, 5);
19
+ });
20
+
21
+ it('음수 점수가 나올 수 있다', () => {
22
+ const score = ranking.calculateFinalScore({
23
+ relevance: 0.1,
24
+ recency: 0.1,
25
+ importance: 0.1,
26
+ usage: 0.1,
27
+ duplication_penalty: 0.9,
28
+ });
29
+
30
+ expect(score).toBeLessThan(0);
31
+ });
32
+ });
33
+
34
+ describe('calculateRelevance', () => {
35
+ it('기본 관련성 점수를 계산한다', () => {
36
+ const relevance = ranking.calculateRelevance({
37
+ query: 'React Hook',
38
+ content: 'React Hook에 대해 설명한 문서입니다. Hook API 예시 포함.',
39
+ tags: ['frontend', 'react']
40
+ });
41
+
42
+ expect(relevance).toBeLessThanOrEqual(1);
43
+ expect(relevance).toBeGreaterThan(0);
44
+ });
45
+
46
+ it('임베딩 유사도가 제공된 경우 관련성 점수를 계산한다', () => {
47
+ const relevance = ranking.calculateRelevance({
48
+ query: 'React Hook',
49
+ content: 'React Hook에 대한 내용',
50
+ tags: ['react'],
51
+ embeddingSimilarity: {
52
+ queryEmbedding: [0.1, 0.2, 0.3, 0.4],
53
+ docEmbedding: [0.1, 0.2, 0.3, 0.4]
54
+ }
55
+ });
56
+ expect(relevance).toBeGreaterThan(0);
57
+ });
58
+
59
+ it('BM25 결과가 제공된 경우 관련성 점수를 계산한다', () => {
60
+ const relevance = ranking.calculateRelevance({
61
+ query: 'React Hook',
62
+ content: 'React Hook에 대한 내용',
63
+ tags: ['react'],
64
+ bm25Result: { score: 2.5, normalizedScore: 0.8 }
65
+ });
66
+ expect(relevance).toBeGreaterThan(0);
67
+ });
68
+
69
+ it('타이틀이 있는 경우 타이틀 히트 점수를 반영한다', () => {
70
+ const relevance = ranking.calculateRelevance({
71
+ query: 'React Hook',
72
+ content: 'React Hook에 대한 내용',
73
+ title: 'React Hook Guide',
74
+ tags: ['react']
75
+ });
76
+ expect(relevance).toBeGreaterThan(0);
77
+ });
78
+
79
+ it('빈 문자열 입력에 대해 안전하게 처리한다', () => {
80
+ const relevance = ranking.calculateRelevance({
81
+ query: '',
82
+ content: '',
83
+ tags: []
84
+ });
85
+ expect(relevance).toBe(0);
86
+ });
87
+
88
+ it('null/undefined 입력에 대해 안전하게 처리한다', () => {
89
+ const relevance = ranking.calculateRelevance({
90
+ query: null as any,
91
+ content: undefined as any,
92
+ tags: []
93
+ });
94
+ expect(relevance).toBe(0);
95
+ });
96
+ });
97
+
98
+ describe('calculateRecency', () => {
99
+ it('최근성이 높은 기억은 더 높은 점수를 받는다', () => {
100
+ const recent = ranking.calculateRecency(
101
+ new Date(Date.now() - 1 * 24 * 60 * 60 * 1000),
102
+ 'semantic'
103
+ );
104
+ const old = ranking.calculateRecency(
105
+ new Date(Date.now() - 200 * 24 * 60 * 60 * 1000),
106
+ 'semantic'
107
+ );
108
+
109
+ expect(recent).toBeGreaterThan(old);
110
+ expect(recent).toBeLessThanOrEqual(1);
111
+ });
112
+
113
+ it('타입별로 다른 반감기를 적용한다', () => {
114
+ const working = ranking.calculateRecency(
115
+ new Date(Date.now() - 1 * 24 * 60 * 60 * 1000),
116
+ 'working'
117
+ );
118
+ const episodic = ranking.calculateRecency(
119
+ new Date(Date.now() - 1 * 24 * 60 * 60 * 1000),
120
+ 'episodic'
121
+ );
122
+ const semantic = ranking.calculateRecency(
123
+ new Date(Date.now() - 1 * 24 * 60 * 60 * 1000),
124
+ 'semantic'
125
+ );
126
+
127
+ expect(working).toBeLessThan(episodic);
128
+ expect(episodic).toBeLessThan(semantic);
129
+ });
130
+
131
+ it('매우 오래된 기억은 낮은 점수를 받는다', () => {
132
+ const veryOld = ranking.calculateRecency(
133
+ new Date(Date.now() - 1000 * 24 * 60 * 60 * 1000),
134
+ 'semantic'
135
+ );
136
+ expect(veryOld).toBeLessThan(0.1); // 1000일 전의 기억은 0.1보다 작은 점수
137
+ });
138
+ });
139
+
140
+ describe('calculateImportance', () => {
141
+ it('고정된 중요 기억은 부스트를 받아 점수가 상승한다', () => {
142
+ const base = ranking.calculateImportance(0.4, false, 'episodic');
143
+ const pinned = ranking.calculateImportance(0.4, true, 'episodic');
144
+ const semantic = ranking.calculateImportance(0.4, false, 'semantic');
145
+
146
+ expect(pinned).toBeGreaterThan(base);
147
+ expect(semantic).toBeGreaterThan(base);
148
+ expect(pinned).toBeLessThanOrEqual(1);
149
+ });
150
+
151
+ it('타입별로 다른 부스트를 적용한다', () => {
152
+ const working = ranking.calculateImportance(0.5, false, 'working');
153
+ const episodic = ranking.calculateImportance(0.5, false, 'episodic');
154
+ const semantic = ranking.calculateImportance(0.5, false, 'semantic');
155
+ const procedural = ranking.calculateImportance(0.5, false, 'procedural');
156
+
157
+ expect(working).toBeLessThan(episodic);
158
+ expect(episodic).toBeLessThan(procedural);
159
+ expect(procedural).toBeLessThan(semantic);
160
+ });
161
+
162
+ it('중요도는 0과 1 사이로 제한된다', () => {
163
+ const low = ranking.calculateImportance(-0.5, false, 'episodic');
164
+ const high = ranking.calculateImportance(1.5, false, 'episodic');
165
+
166
+ expect(low).toBeGreaterThanOrEqual(0);
167
+ expect(high).toBeLessThanOrEqual(1);
168
+ });
169
+ });
170
+
171
+ describe('calculateUsage', () => {
172
+ it('접근 이력이 없는 경우 기본 사용성 점수를 적용한다', () => {
173
+ const metrics = { viewCount: 0, citeCount: 0, editCount: 0 };
174
+ expect(ranking.calculateUsage(metrics)).toBeCloseTo(0.1, 5);
175
+ });
176
+
177
+ it('다양한 사용성 메트릭을 올바르게 계산한다', () => {
178
+ const metrics = { viewCount: 10, citeCount: 5, editCount: 2 };
179
+ const usage = ranking.calculateUsage(metrics);
180
+ expect(usage).toBeGreaterThan(0.1);
181
+ expect(usage).toBeLessThanOrEqual(1);
182
+ });
183
+
184
+ it('배치 정규화가 적용된 사용성 점수를 계산한다', () => {
185
+ const metrics = { viewCount: 10, citeCount: 5, editCount: 2 };
186
+ const usage = ranking.calculateUsage(metrics, 0, 20);
187
+ expect(usage).toBeGreaterThanOrEqual(0);
188
+ expect(usage).toBeLessThanOrEqual(1);
189
+ });
190
+
191
+ it('null 입력에 대해 안전하게 처리한다', () => {
192
+ const usage = ranking.calculateUsage(null as any);
193
+ expect(usage).toBe(0);
194
+ });
195
+
196
+ it('모든 메트릭이 0인 경우 기본값을 반환한다', () => {
197
+ const metrics = { viewCount: 0, citeCount: 0, editCount: 0 };
198
+ const usage = ranking.calculateUsage(metrics);
199
+ expect(usage).toBeCloseTo(0.1, 5);
200
+ });
201
+ });
202
+
203
+ describe('calculateBatchUsage', () => {
204
+ it('여러 메모리에 대한 배치 사용성 점수를 계산한다', () => {
205
+ const metricsList = [
206
+ { viewCount: 10, citeCount: 5, editCount: 2 },
207
+ { viewCount: 20, citeCount: 10, editCount: 4 },
208
+ { viewCount: 5, citeCount: 2, editCount: 1 }
209
+ ];
210
+
211
+ const result = ranking.calculateBatchUsage(metricsList);
212
+ expect(result.normalized).toHaveLength(3);
213
+ expect(result.min).toBeLessThanOrEqual(result.max);
214
+ expect(result.normalized.every(score => score >= 0 && score <= 1)).toBe(true);
215
+ });
216
+
217
+ it('빈 배열에 대해 안전하게 처리한다', () => {
218
+ const result = ranking.calculateBatchUsage([]);
219
+ expect(result.normalized).toHaveLength(0);
220
+ });
221
+ });
222
+
223
+ describe('calculateDuplicationPenalty', () => {
224
+ it('중복 패널티는 선택된 콘텐츠와의 최대 유사도를 반영한다', () => {
225
+ const penalty = ranking.calculateDuplicationPenalty(
226
+ 'TypeScript Generic Tutorial',
227
+ ['React Hook Guide', 'TypeScript Advanced Generic Tutorial']
228
+ );
229
+
230
+ expect(penalty).toBeGreaterThan(0);
231
+ expect(penalty).toBeLessThan(1);
232
+ });
233
+
234
+ it('선택된 콘텐츠가 없으면 패널티가 0이다', () => {
235
+ const penalty = ranking.calculateDuplicationPenalty(
236
+ 'TypeScript Generic Tutorial',
237
+ []
238
+ );
239
+ expect(penalty).toBe(0);
240
+ });
241
+
242
+ it('완전히 다른 콘텐츠는 낮은 패널티를 받는다', () => {
243
+ const penalty = ranking.calculateDuplicationPenalty(
244
+ 'React Hook Guide',
245
+ ['Python Machine Learning', 'Database Design Patterns']
246
+ );
247
+ expect(penalty).toBeLessThan(0.5);
248
+ });
249
+ });
250
+
251
+ describe('하위 호환성 메서드들', () => {
252
+ it('calculateRelevanceSimple이 올바르게 작동한다', () => {
253
+ const relevance = ranking.calculateRelevanceSimple(
254
+ 'React Hook',
255
+ 'React Hook에 대한 내용',
256
+ ['react', 'hook']
257
+ );
258
+ expect(relevance).toBeGreaterThan(0);
259
+ });
260
+
261
+ it('calculateUsageSimple이 올바르게 작동한다', () => {
262
+ const recentDate = new Date(Date.now() - 1 * 24 * 60 * 60 * 1000);
263
+ const usage = ranking.calculateUsageSimple(recentDate);
264
+ expect(usage).toBeGreaterThan(0);
265
+ });
266
+
267
+ it('calculateUsageSimple에서 lastAccessed가 없으면 기본값을 반환한다', () => {
268
+ const usage = ranking.calculateUsageSimple(undefined);
269
+ expect(usage).toBeCloseTo(0.1, 5);
270
+ });
271
+ });
272
+
273
+ describe('엣지 케이스들', () => {
274
+ it('0으로 나누기 상황을 안전하게 처리한다', () => {
275
+ const usage = ranking.calculateUsage(
276
+ { viewCount: 0, citeCount: 0, editCount: 0 },
277
+ 0, 0 // min과 max가 같을 때
278
+ );
279
+ // rawUsage가 0이므로 기본값 0.1을 반환
280
+ expect(usage).toBe(0.1);
281
+ });
282
+
283
+ it('매우 큰 값들에 대해 안전하게 처리한다', () => {
284
+ const relevance = ranking.calculateRelevance({
285
+ query: 'a'.repeat(10000),
286
+ content: 'b'.repeat(10000),
287
+ tags: Array(1000).fill('tag')
288
+ });
289
+ expect(relevance).toBeGreaterThanOrEqual(0);
290
+ expect(relevance).toBeLessThanOrEqual(1);
291
+ });
292
+ });
293
+ });