@fgv/ts-agent-memory 5.1.0-36

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 (331) hide show
  1. package/.rush/temp/chunked-rush-logs/ts-agent-memory.build.chunks.jsonl +9 -0
  2. package/.rush/temp/f6a88bfdd66517ccb98c2c7ae1be6e6fe9e15d38.tar.log +282 -0
  3. package/.rush/temp/operation/build/all.log +9 -0
  4. package/.rush/temp/operation/build/log-chunks.jsonl +9 -0
  5. package/.rush/temp/operation/build/state.json +3 -0
  6. package/.rush/temp/shrinkwrap-deps.json +688 -0
  7. package/LICENSE +21 -0
  8. package/README.md +45 -0
  9. package/config/api-extractor.json +343 -0
  10. package/config/jest.config.json +14 -0
  11. package/config/rig.json +4 -0
  12. package/dist/index.js +12 -0
  13. package/dist/index.js.map +1 -0
  14. package/dist/packlets/converters/bodyConverterRegistry.js +51 -0
  15. package/dist/packlets/converters/bodyConverterRegistry.js.map +1 -0
  16. package/dist/packlets/converters/envelopeConverter.js +159 -0
  17. package/dist/packlets/converters/envelopeConverter.js.map +1 -0
  18. package/dist/packlets/converters/index.js +7 -0
  19. package/dist/packlets/converters/index.js.map +1 -0
  20. package/dist/packlets/index/index.js +6 -0
  21. package/dist/packlets/index/index.js.map +1 -0
  22. package/dist/packlets/index/memoryIndex.js +170 -0
  23. package/dist/packlets/index/memoryIndex.js.map +1 -0
  24. package/dist/packlets/observe/index.js +7 -0
  25. package/dist/packlets/observe/index.js.map +1 -0
  26. package/dist/packlets/observe/memoryObservationStore.js +119 -0
  27. package/dist/packlets/observe/memoryObservationStore.js.map +1 -0
  28. package/dist/packlets/observe/observer.js +6 -0
  29. package/dist/packlets/observe/observer.js.map +1 -0
  30. package/dist/packlets/retrieve/hybridRetriever.js +135 -0
  31. package/dist/packlets/retrieve/hybridRetriever.js.map +1 -0
  32. package/dist/packlets/retrieve/index.js +12 -0
  33. package/dist/packlets/retrieve/index.js.map +1 -0
  34. package/dist/packlets/retrieve/linkTraversalRetriever.js +143 -0
  35. package/dist/packlets/retrieve/linkTraversalRetriever.js.map +1 -0
  36. package/dist/packlets/retrieve/recencyRetriever.js +33 -0
  37. package/dist/packlets/retrieve/recencyRetriever.js.map +1 -0
  38. package/dist/packlets/retrieve/retriever.js +110 -0
  39. package/dist/packlets/retrieve/retriever.js.map +1 -0
  40. package/dist/packlets/retrieve/semanticRetriever.js +86 -0
  41. package/dist/packlets/retrieve/semanticRetriever.js.map +1 -0
  42. package/dist/packlets/retrieve/structuredFilterRetriever.js +37 -0
  43. package/dist/packlets/retrieve/structuredFilterRetriever.js.map +1 -0
  44. package/dist/packlets/retrieve/tagRetriever.js +37 -0
  45. package/dist/packlets/retrieve/tagRetriever.js.map +1 -0
  46. package/dist/packlets/store/fileTreeMemoryStore.js +698 -0
  47. package/dist/packlets/store/fileTreeMemoryStore.js.map +1 -0
  48. package/dist/packlets/store/index.js +7 -0
  49. package/dist/packlets/store/index.js.map +1 -0
  50. package/dist/packlets/store/scopeEncoding.js +31 -0
  51. package/dist/packlets/store/scopeEncoding.js.map +1 -0
  52. package/dist/packlets/types/envelope.js +6 -0
  53. package/dist/packlets/types/envelope.js.map +1 -0
  54. package/dist/packlets/types/filenameSafety.js +52 -0
  55. package/dist/packlets/types/filenameSafety.js.map +1 -0
  56. package/dist/packlets/types/identityCodec.js +184 -0
  57. package/dist/packlets/types/identityCodec.js.map +1 -0
  58. package/dist/packlets/types/ids.js +67 -0
  59. package/dist/packlets/types/ids.js.map +1 -0
  60. package/dist/packlets/types/index.js +10 -0
  61. package/dist/packlets/types/index.js.map +1 -0
  62. package/dist/packlets/types/writePolicy.js +263 -0
  63. package/dist/packlets/types/writePolicy.js.map +1 -0
  64. package/dist/packlets/vector/inMemoryCosineIndex.js +150 -0
  65. package/dist/packlets/vector/inMemoryCosineIndex.js.map +1 -0
  66. package/dist/packlets/vector/index.js +7 -0
  67. package/dist/packlets/vector/index.js.map +1 -0
  68. package/dist/packlets/vector/vectorIndex.js +6 -0
  69. package/dist/packlets/vector/vectorIndex.js.map +1 -0
  70. package/dist/test/unit/converters/bodyConverterRegistry.test.js +72 -0
  71. package/dist/test/unit/converters/bodyConverterRegistry.test.js.map +1 -0
  72. package/dist/test/unit/converters/envelopeConverter.test.js +196 -0
  73. package/dist/test/unit/converters/envelopeConverter.test.js.map +1 -0
  74. package/dist/test/unit/index/memoryIndex.test.js +152 -0
  75. package/dist/test/unit/index/memoryIndex.test.js.map +1 -0
  76. package/dist/test/unit/observe/memoryObservationStore.test.js +118 -0
  77. package/dist/test/unit/observe/memoryObservationStore.test.js.map +1 -0
  78. package/dist/test/unit/retrieve/linkTraversalRetriever.test.js +182 -0
  79. package/dist/test/unit/retrieve/linkTraversalRetriever.test.js.map +1 -0
  80. package/dist/test/unit/retrieve/retrievers.test.js +506 -0
  81. package/dist/test/unit/retrieve/retrievers.test.js.map +1 -0
  82. package/dist/test/unit/store/embedOnWrite.test.js +260 -0
  83. package/dist/test/unit/store/embedOnWrite.test.js.map +1 -0
  84. package/dist/test/unit/store/fileTreeMemoryStore.test.js +647 -0
  85. package/dist/test/unit/store/fileTreeMemoryStore.test.js.map +1 -0
  86. package/dist/test/unit/store/observations.test.js +239 -0
  87. package/dist/test/unit/store/observations.test.js.map +1 -0
  88. package/dist/test/unit/store/scopeEncoding.test.js +24 -0
  89. package/dist/test/unit/store/scopeEncoding.test.js.map +1 -0
  90. package/dist/test/unit/types/identityCodec.test.js +187 -0
  91. package/dist/test/unit/types/identityCodec.test.js.map +1 -0
  92. package/dist/test/unit/types/ids.test.js +84 -0
  93. package/dist/test/unit/types/ids.test.js.map +1 -0
  94. package/dist/test/unit/types/writePolicy.test.js +241 -0
  95. package/dist/test/unit/types/writePolicy.test.js.map +1 -0
  96. package/dist/test/unit/vector/inMemoryCosineIndex.test.js +192 -0
  97. package/dist/test/unit/vector/inMemoryCosineIndex.test.js.map +1 -0
  98. package/dist/test/unit/vector/vectorIndex.test.js +42 -0
  99. package/dist/test/unit/vector/vectorIndex.test.js.map +1 -0
  100. package/dist/ts-agent-memory.d.ts +1901 -0
  101. package/dist/tsdoc-metadata.json +11 -0
  102. package/eslint.config.js +15 -0
  103. package/etc/ts-agent-memory.api.md +525 -0
  104. package/lib/index.d.ts +8 -0
  105. package/lib/index.d.ts.map +1 -0
  106. package/lib/index.js +28 -0
  107. package/lib/index.js.map +1 -0
  108. package/lib/packlets/converters/bodyConverterRegistry.d.ts +64 -0
  109. package/lib/packlets/converters/bodyConverterRegistry.d.ts.map +1 -0
  110. package/lib/packlets/converters/bodyConverterRegistry.js +55 -0
  111. package/lib/packlets/converters/bodyConverterRegistry.js.map +1 -0
  112. package/lib/packlets/converters/envelopeConverter.d.ts +70 -0
  113. package/lib/packlets/converters/envelopeConverter.d.ts.map +1 -0
  114. package/lib/packlets/converters/envelopeConverter.js +166 -0
  115. package/lib/packlets/converters/envelopeConverter.js.map +1 -0
  116. package/lib/packlets/converters/index.d.ts +3 -0
  117. package/lib/packlets/converters/index.d.ts.map +1 -0
  118. package/lib/packlets/converters/index.js +23 -0
  119. package/lib/packlets/converters/index.js.map +1 -0
  120. package/lib/packlets/index/index.d.ts +2 -0
  121. package/lib/packlets/index/index.d.ts.map +1 -0
  122. package/lib/packlets/index/index.js +22 -0
  123. package/lib/packlets/index/index.js.map +1 -0
  124. package/lib/packlets/index/memoryIndex.d.ts +127 -0
  125. package/lib/packlets/index/memoryIndex.d.ts.map +1 -0
  126. package/lib/packlets/index/memoryIndex.js +174 -0
  127. package/lib/packlets/index/memoryIndex.js.map +1 -0
  128. package/lib/packlets/observe/index.d.ts +3 -0
  129. package/lib/packlets/observe/index.d.ts.map +1 -0
  130. package/lib/packlets/observe/index.js +23 -0
  131. package/lib/packlets/observe/index.js.map +1 -0
  132. package/lib/packlets/observe/memoryObservationStore.d.ts +91 -0
  133. package/lib/packlets/observe/memoryObservationStore.d.ts.map +1 -0
  134. package/lib/packlets/observe/memoryObservationStore.js +123 -0
  135. package/lib/packlets/observe/memoryObservationStore.js.map +1 -0
  136. package/lib/packlets/observe/observer.d.ts +110 -0
  137. package/lib/packlets/observe/observer.d.ts.map +1 -0
  138. package/lib/packlets/observe/observer.js +7 -0
  139. package/lib/packlets/observe/observer.js.map +1 -0
  140. package/lib/packlets/retrieve/hybridRetriever.d.ts +79 -0
  141. package/lib/packlets/retrieve/hybridRetriever.d.ts.map +1 -0
  142. package/lib/packlets/retrieve/hybridRetriever.js +140 -0
  143. package/lib/packlets/retrieve/hybridRetriever.js.map +1 -0
  144. package/lib/packlets/retrieve/index.d.ts +8 -0
  145. package/lib/packlets/retrieve/index.d.ts.map +1 -0
  146. package/lib/packlets/retrieve/index.js +28 -0
  147. package/lib/packlets/retrieve/index.js.map +1 -0
  148. package/lib/packlets/retrieve/linkTraversalRetriever.d.ts +61 -0
  149. package/lib/packlets/retrieve/linkTraversalRetriever.d.ts.map +1 -0
  150. package/lib/packlets/retrieve/linkTraversalRetriever.js +147 -0
  151. package/lib/packlets/retrieve/linkTraversalRetriever.js.map +1 -0
  152. package/lib/packlets/retrieve/recencyRetriever.d.ts +21 -0
  153. package/lib/packlets/retrieve/recencyRetriever.d.ts.map +1 -0
  154. package/lib/packlets/retrieve/recencyRetriever.js +37 -0
  155. package/lib/packlets/retrieve/recencyRetriever.js.map +1 -0
  156. package/lib/packlets/retrieve/retriever.d.ts +133 -0
  157. package/lib/packlets/retrieve/retriever.d.ts.map +1 -0
  158. package/lib/packlets/retrieve/retriever.js +119 -0
  159. package/lib/packlets/retrieve/retriever.js.map +1 -0
  160. package/lib/packlets/retrieve/semanticRetriever.d.ts +69 -0
  161. package/lib/packlets/retrieve/semanticRetriever.d.ts.map +1 -0
  162. package/lib/packlets/retrieve/semanticRetriever.js +90 -0
  163. package/lib/packlets/retrieve/semanticRetriever.js.map +1 -0
  164. package/lib/packlets/retrieve/structuredFilterRetriever.d.ts +22 -0
  165. package/lib/packlets/retrieve/structuredFilterRetriever.d.ts.map +1 -0
  166. package/lib/packlets/retrieve/structuredFilterRetriever.js +41 -0
  167. package/lib/packlets/retrieve/structuredFilterRetriever.js.map +1 -0
  168. package/lib/packlets/retrieve/tagRetriever.d.ts +22 -0
  169. package/lib/packlets/retrieve/tagRetriever.d.ts.map +1 -0
  170. package/lib/packlets/retrieve/tagRetriever.js +41 -0
  171. package/lib/packlets/retrieve/tagRetriever.js.map +1 -0
  172. package/lib/packlets/store/fileTreeMemoryStore.d.ts +327 -0
  173. package/lib/packlets/store/fileTreeMemoryStore.d.ts.map +1 -0
  174. package/lib/packlets/store/fileTreeMemoryStore.js +702 -0
  175. package/lib/packlets/store/fileTreeMemoryStore.js.map +1 -0
  176. package/lib/packlets/store/index.d.ts +3 -0
  177. package/lib/packlets/store/index.d.ts.map +1 -0
  178. package/lib/packlets/store/index.js +23 -0
  179. package/lib/packlets/store/index.js.map +1 -0
  180. package/lib/packlets/store/scopeEncoding.d.ts +19 -0
  181. package/lib/packlets/store/scopeEncoding.d.ts.map +1 -0
  182. package/lib/packlets/store/scopeEncoding.js +34 -0
  183. package/lib/packlets/store/scopeEncoding.js.map +1 -0
  184. package/lib/packlets/types/envelope.d.ts +119 -0
  185. package/lib/packlets/types/envelope.d.ts.map +1 -0
  186. package/lib/packlets/types/envelope.js +7 -0
  187. package/lib/packlets/types/envelope.js.map +1 -0
  188. package/lib/packlets/types/filenameSafety.d.ts +16 -0
  189. package/lib/packlets/types/filenameSafety.d.ts.map +1 -0
  190. package/lib/packlets/types/filenameSafety.js +55 -0
  191. package/lib/packlets/types/filenameSafety.js.map +1 -0
  192. package/lib/packlets/types/identityCodec.d.ts +136 -0
  193. package/lib/packlets/types/identityCodec.d.ts.map +1 -0
  194. package/lib/packlets/types/identityCodec.js +190 -0
  195. package/lib/packlets/types/identityCodec.js.map +1 -0
  196. package/lib/packlets/types/ids.d.ts +55 -0
  197. package/lib/packlets/types/ids.d.ts.map +1 -0
  198. package/lib/packlets/types/ids.js +70 -0
  199. package/lib/packlets/types/ids.js.map +1 -0
  200. package/lib/packlets/types/index.d.ts +6 -0
  201. package/lib/packlets/types/index.d.ts.map +1 -0
  202. package/lib/packlets/types/index.js +26 -0
  203. package/lib/packlets/types/index.js.map +1 -0
  204. package/lib/packlets/types/writePolicy.d.ts +213 -0
  205. package/lib/packlets/types/writePolicy.d.ts.map +1 -0
  206. package/lib/packlets/types/writePolicy.js +268 -0
  207. package/lib/packlets/types/writePolicy.js.map +1 -0
  208. package/lib/packlets/vector/inMemoryCosineIndex.d.ts +69 -0
  209. package/lib/packlets/vector/inMemoryCosineIndex.d.ts.map +1 -0
  210. package/lib/packlets/vector/inMemoryCosineIndex.js +154 -0
  211. package/lib/packlets/vector/inMemoryCosineIndex.js.map +1 -0
  212. package/lib/packlets/vector/index.d.ts +3 -0
  213. package/lib/packlets/vector/index.d.ts.map +1 -0
  214. package/lib/packlets/vector/index.js +23 -0
  215. package/lib/packlets/vector/index.js.map +1 -0
  216. package/lib/packlets/vector/vectorIndex.d.ts +68 -0
  217. package/lib/packlets/vector/vectorIndex.d.ts.map +1 -0
  218. package/lib/packlets/vector/vectorIndex.js +7 -0
  219. package/lib/packlets/vector/vectorIndex.js.map +1 -0
  220. package/lib/test/unit/converters/bodyConverterRegistry.test.d.ts +2 -0
  221. package/lib/test/unit/converters/bodyConverterRegistry.test.d.ts.map +1 -0
  222. package/lib/test/unit/converters/bodyConverterRegistry.test.js +74 -0
  223. package/lib/test/unit/converters/bodyConverterRegistry.test.js.map +1 -0
  224. package/lib/test/unit/converters/envelopeConverter.test.d.ts +2 -0
  225. package/lib/test/unit/converters/envelopeConverter.test.d.ts.map +1 -0
  226. package/lib/test/unit/converters/envelopeConverter.test.js +198 -0
  227. package/lib/test/unit/converters/envelopeConverter.test.js.map +1 -0
  228. package/lib/test/unit/index/memoryIndex.test.d.ts +2 -0
  229. package/lib/test/unit/index/memoryIndex.test.d.ts.map +1 -0
  230. package/lib/test/unit/index/memoryIndex.test.js +154 -0
  231. package/lib/test/unit/index/memoryIndex.test.js.map +1 -0
  232. package/lib/test/unit/observe/memoryObservationStore.test.d.ts +2 -0
  233. package/lib/test/unit/observe/memoryObservationStore.test.d.ts.map +1 -0
  234. package/lib/test/unit/observe/memoryObservationStore.test.js +120 -0
  235. package/lib/test/unit/observe/memoryObservationStore.test.js.map +1 -0
  236. package/lib/test/unit/retrieve/linkTraversalRetriever.test.d.ts +2 -0
  237. package/lib/test/unit/retrieve/linkTraversalRetriever.test.d.ts.map +1 -0
  238. package/lib/test/unit/retrieve/linkTraversalRetriever.test.js +184 -0
  239. package/lib/test/unit/retrieve/linkTraversalRetriever.test.js.map +1 -0
  240. package/lib/test/unit/retrieve/retrievers.test.d.ts +2 -0
  241. package/lib/test/unit/retrieve/retrievers.test.d.ts.map +1 -0
  242. package/lib/test/unit/retrieve/retrievers.test.js +508 -0
  243. package/lib/test/unit/retrieve/retrievers.test.js.map +1 -0
  244. package/lib/test/unit/store/embedOnWrite.test.d.ts +2 -0
  245. package/lib/test/unit/store/embedOnWrite.test.d.ts.map +1 -0
  246. package/lib/test/unit/store/embedOnWrite.test.js +262 -0
  247. package/lib/test/unit/store/embedOnWrite.test.js.map +1 -0
  248. package/lib/test/unit/store/fileTreeMemoryStore.test.d.ts +2 -0
  249. package/lib/test/unit/store/fileTreeMemoryStore.test.d.ts.map +1 -0
  250. package/lib/test/unit/store/fileTreeMemoryStore.test.js +649 -0
  251. package/lib/test/unit/store/fileTreeMemoryStore.test.js.map +1 -0
  252. package/lib/test/unit/store/observations.test.d.ts +2 -0
  253. package/lib/test/unit/store/observations.test.d.ts.map +1 -0
  254. package/lib/test/unit/store/observations.test.js +241 -0
  255. package/lib/test/unit/store/observations.test.js.map +1 -0
  256. package/lib/test/unit/store/scopeEncoding.test.d.ts +2 -0
  257. package/lib/test/unit/store/scopeEncoding.test.d.ts.map +1 -0
  258. package/lib/test/unit/store/scopeEncoding.test.js +26 -0
  259. package/lib/test/unit/store/scopeEncoding.test.js.map +1 -0
  260. package/lib/test/unit/types/identityCodec.test.d.ts +2 -0
  261. package/lib/test/unit/types/identityCodec.test.d.ts.map +1 -0
  262. package/lib/test/unit/types/identityCodec.test.js +189 -0
  263. package/lib/test/unit/types/identityCodec.test.js.map +1 -0
  264. package/lib/test/unit/types/ids.test.d.ts +2 -0
  265. package/lib/test/unit/types/ids.test.d.ts.map +1 -0
  266. package/lib/test/unit/types/ids.test.js +86 -0
  267. package/lib/test/unit/types/ids.test.js.map +1 -0
  268. package/lib/test/unit/types/writePolicy.test.d.ts +2 -0
  269. package/lib/test/unit/types/writePolicy.test.d.ts.map +1 -0
  270. package/lib/test/unit/types/writePolicy.test.js +243 -0
  271. package/lib/test/unit/types/writePolicy.test.js.map +1 -0
  272. package/lib/test/unit/vector/inMemoryCosineIndex.test.d.ts +2 -0
  273. package/lib/test/unit/vector/inMemoryCosineIndex.test.d.ts.map +1 -0
  274. package/lib/test/unit/vector/inMemoryCosineIndex.test.js +194 -0
  275. package/lib/test/unit/vector/inMemoryCosineIndex.test.js.map +1 -0
  276. package/lib/test/unit/vector/vectorIndex.test.d.ts +2 -0
  277. package/lib/test/unit/vector/vectorIndex.test.d.ts.map +1 -0
  278. package/lib/test/unit/vector/vectorIndex.test.js +44 -0
  279. package/lib/test/unit/vector/vectorIndex.test.js.map +1 -0
  280. package/package.json +81 -0
  281. package/rush-logs/ts-agent-memory.build.cache.log +3 -0
  282. package/rush-logs/ts-agent-memory.build.log +9 -0
  283. package/src/index.ts +12 -0
  284. package/src/packlets/converters/bodyConverterRegistry.ts +105 -0
  285. package/src/packlets/converters/envelopeConverter.ts +210 -0
  286. package/src/packlets/converters/index.ts +7 -0
  287. package/src/packlets/index/index.ts +6 -0
  288. package/src/packlets/index/memoryIndex.ts +268 -0
  289. package/src/packlets/observe/index.ts +7 -0
  290. package/src/packlets/observe/memoryObservationStore.ts +153 -0
  291. package/src/packlets/observe/observer.ts +119 -0
  292. package/src/packlets/retrieve/hybridRetriever.ts +181 -0
  293. package/src/packlets/retrieve/index.ts +12 -0
  294. package/src/packlets/retrieve/linkTraversalRetriever.ts +169 -0
  295. package/src/packlets/retrieve/recencyRetriever.ts +54 -0
  296. package/src/packlets/retrieve/retriever.ts +207 -0
  297. package/src/packlets/retrieve/semanticRetriever.ts +147 -0
  298. package/src/packlets/retrieve/structuredFilterRetriever.ts +58 -0
  299. package/src/packlets/retrieve/tagRetriever.ts +58 -0
  300. package/src/packlets/store/fileTreeMemoryStore.ts +1073 -0
  301. package/src/packlets/store/index.ts +7 -0
  302. package/src/packlets/store/scopeEncoding.ts +36 -0
  303. package/src/packlets/types/envelope.ts +138 -0
  304. package/src/packlets/types/filenameSafety.ts +57 -0
  305. package/src/packlets/types/identityCodec.ts +263 -0
  306. package/src/packlets/types/ids.ts +124 -0
  307. package/src/packlets/types/index.ts +10 -0
  308. package/src/packlets/types/writePolicy.ts +447 -0
  309. package/src/packlets/vector/inMemoryCosineIndex.ts +173 -0
  310. package/src/packlets/vector/index.ts +7 -0
  311. package/src/packlets/vector/vectorIndex.ts +78 -0
  312. package/src/test/unit/converters/bodyConverterRegistry.test.ts +89 -0
  313. package/src/test/unit/converters/envelopeConverter.test.ts +261 -0
  314. package/src/test/unit/index/memoryIndex.test.ts +187 -0
  315. package/src/test/unit/observe/memoryObservationStore.test.ts +158 -0
  316. package/src/test/unit/retrieve/linkTraversalRetriever.test.ts +230 -0
  317. package/src/test/unit/retrieve/retrievers.test.ts +662 -0
  318. package/src/test/unit/store/embedOnWrite.test.ts +346 -0
  319. package/src/test/unit/store/fileTreeMemoryStore.test.ts +875 -0
  320. package/src/test/unit/store/observations.test.ts +290 -0
  321. package/src/test/unit/store/scopeEncoding.test.ts +37 -0
  322. package/src/test/unit/types/identityCodec.test.ts +266 -0
  323. package/src/test/unit/types/ids.test.ts +94 -0
  324. package/src/test/unit/types/writePolicy.test.ts +325 -0
  325. package/src/test/unit/vector/inMemoryCosineIndex.test.ts +242 -0
  326. package/src/test/unit/vector/vectorIndex.test.ts +48 -0
  327. package/temp/build/lint/_eslint-5eVG3S6w.json +182 -0
  328. package/temp/build/typescript/ts_8nwakTlr.json +1 -0
  329. package/temp/ts-agent-memory.api.json +12438 -0
  330. package/temp/ts-agent-memory.api.md +525 -0
  331. package/tsconfig.json +8 -0
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Erik Fortune
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md ADDED
@@ -0,0 +1,45 @@
1
+ # @fgv/ts-agent-memory
2
+
3
+ A FileTree-backed storage and retrieval substrate for agent memory and
4
+ knowledge. It owns persistence, identity, typed per-kind bodies, attributed
5
+ edges, content-hash dedup, and the optional-layer seams (vector / temporal /
6
+ observe). It owns none of a consumer's processing, transformation, or
7
+ composition logic.
8
+
9
+ > **Status:** v0.1, under active development. The package is being built
10
+ > knowledge-first. This tier (B0) ships the foundational type model and
11
+ > converters only — no store, index, retrieval, observe, or vector code yet.
12
+
13
+ ## B0 surface (this tier)
14
+
15
+ ### `types` packlet
16
+
17
+ - **Branded ids** — `MemoryId`, `EntityId`, `Kind`, `Tag`, `MemoryScopeKey`,
18
+ `LinkType`, plus the `Convert` converter constants.
19
+ - **Envelope model** — `IMemoryEnvelope`, `IEdge`, `IProvenance`,
20
+ `ITemporalBlock`, `IMemoryRecord<TBody>`.
21
+ - **Identity codec** — `IIdentityCodec` (domain key ⇄ `{ scope, idStem }`,
22
+ deterministic and reversible) and `KnowledgeIdentityCodec`.
23
+ - **Write policy** — `IWritePolicy`, `AdmissionDecision`, and the
24
+ last-write-wins `KnowledgeLwwPolicy` (RFC-7386 JSON Merge Patch over the
25
+ declared mutable fields).
26
+
27
+ ### `converters` packlet
28
+
29
+ - **`IBodyConverterRegistry` / `BodyConverterRegistry`** — per-kind body
30
+ Converter registry (`register`, `registerSchema`, `has`, `getConverter`,
31
+ `convert`).
32
+ - **Envelope converters** — `envelopeConverter` (object) /
33
+ `envelopeYamlConverter` (YAML frontmatter), plus the `splitFrontmatter` /
34
+ `joinFrontmatter` / `parseMemoryFile` / `serializeMemoryFile` helpers for
35
+ the `---\n<yaml>\n---\n<body>` memory-file format.
36
+
37
+ ## Conventions
38
+
39
+ `Result<T>` on every fallible operation; no `any`; Converters/Validators for
40
+ every `unknown` → typed boundary; branded ids; factory `create()` for fallible
41
+ construction. See the repository coding standards for the full set.
42
+
43
+ ## License
44
+
45
+ MIT
package/config/api-extractor.json ADDED
@@ -0,0 +1,343 @@
1
+ /**
2
+ * Config file for API Extractor. For more info, please visit: https://api-extractor.com
3
+ */
4
+ {
5
+ "$schema": "https://developer.microsoft.com/json-schemas/api-extractor/v7/api-extractor.schema.json",
6
+ /**
7
+ * Optionally specifies another JSON config file that this file extends from. This provides a way for
8
+ * standard settings to be shared across multiple projects.
9
+ *
10
+ * If the path starts with "./" or "../", the path is resolved relative to the folder of the file that contains
11
+ * the "extends" field. Otherwise, the first path segment is interpreted as an NPM package name, and will be
12
+ * resolved using NodeJS require().
13
+ *
14
+ * SUPPORTED TOKENS: none
15
+ * DEFAULT VALUE: ""
16
+ */
17
+ // "extends": "./shared/api-extractor-base.json"
18
+ // "extends": "my-package/include/api-extractor-base.json"
19
+ /**
20
+ * Determines the "<projectFolder>" token that can be used with other config file settings. The project folder
21
+ * typically contains the tsconfig.json and package.json config files, but the path is user-defined.
22
+ *
23
+ * The path is resolved relative to the folder of the config file that contains the setting.
24
+ *
25
+ * The default value for "projectFolder" is the token "<lookup>", which means the folder is determined by traversing
26
+ * parent folders, starting from the folder containing api-extractor.json, and stopping at the first folder
27
+ * that contains a tsconfig.json file. If a tsconfig.json file cannot be found in this way, then an error
28
+ * will be reported.
29
+ *
30
+ * SUPPORTED TOKENS: <lookup>
31
+ * DEFAULT VALUE: "<lookup>"
32
+ */
33
+ "projectFolder": "..",
34
+ /**
35
+ * (REQUIRED) Specifies the .d.ts file to be used as the starting point for analysis. API Extractor
36
+ * analyzes the symbols exported by this module.
37
+ *
38
+ * The file extension must be ".d.ts" and not ".ts".
39
+ *
40
+ * The path is resolved relative to the folder of the config file that contains the setting; to change this,
41
+ * prepend a folder token such as "<projectFolder>".
42
+ *
43
+ * SUPPORTED TOKENS: <projectFolder>, <packageName>, <unscopedPackageName>
44
+ */
45
+ "mainEntryPointFilePath": "<projectFolder>/lib/index.d.ts",
46
+ /**
47
+ * A list of NPM package names whose exports should be treated as part of this package.
48
+ *
49
+ * For example, suppose that Webpack is used to generate a distributed bundle for the project "library1",
50
+ * and another NPM package "library2" is embedded in this bundle. Some types from library2 may become part
51
+ * of the exported API for library1, but by default API Extractor would generate a .d.ts rollup that explicitly
52
+ * imports library2. To avoid this, we can specify:
53
+ *
54
+ * "bundledPackages": [ "library2" ],
55
+ *
56
+ * This would direct API Extractor to embed those types directly in the .d.ts rollup, as if they had been
57
+ * local files for library1.
58
+ */
59
+ "bundledPackages": [],
60
+ /**
61
+ * Determines how the TypeScript compiler engine will be invoked by API Extractor.
62
+ */
63
+ "compiler": {
64
+ /**
65
+ * Specifies the path to the tsconfig.json file to be used by API Extractor when analyzing the project.
66
+ *
67
+ * The path is resolved relative to the folder of the config file that contains the setting; to change this,
68
+ * prepend a folder token such as "<projectFolder>".
69
+ *
70
+ * Note: This setting will be ignored if "overrideTsconfig" is used.
71
+ *
72
+ * SUPPORTED TOKENS: <projectFolder>, <packageName>, <unscopedPackageName>
73
+ * DEFAULT VALUE: "<projectFolder>/tsconfig.json"
74
+ */
75
+ // "tsconfigFilePath": "<projectFolder>/tsconfig.json",
76
+ /**
77
+ * Provides a compiler configuration that will be used instead of reading the tsconfig.json file from disk.
78
+ * The object must conform to the TypeScript tsconfig schema:
79
+ *
80
+ * http://json.schemastore.org/tsconfig
81
+ *
82
+ * If omitted, then the tsconfig.json file will be read from the "projectFolder".
83
+ *
84
+ * DEFAULT VALUE: no overrideTsconfig section
85
+ */
86
+ // "overrideTsconfig": {
87
+ // . . .
88
+ // }
89
+ /**
90
+ * This option causes the compiler to be invoked with the --skipLibCheck option. This option is not recommended
91
+ * and may cause API Extractor to produce incomplete or incorrect declarations, but it may be required when
92
+ * dependencies contain declarations that are incompatible with the TypeScript engine that API Extractor uses
93
+ * for its analysis. Where possible, the underlying issue should be fixed rather than relying on skipLibCheck.
94
+ *
95
+ * DEFAULT VALUE: false
96
+ */
97
+ // "skipLibCheck": true,
98
+ },
99
+ /**
100
+ * Configures how the API report file (*.api.md) will be generated.
101
+ */
102
+ "apiReport": {
103
+ /**
104
+ * (REQUIRED) Whether to generate an API report.
105
+ */
106
+ "enabled": true
107
+ /**
108
+ * The filename for the API report files. It will be combined with "reportFolder" or "reportTempFolder" to produce
109
+ * a full file path.
110
+ *
111
+ * The file extension should be ".api.md", and the string should not contain a path separator such as "\" or "/".
112
+ *
113
+ * SUPPORTED TOKENS: <packageName>, <unscopedPackageName>
114
+ * DEFAULT VALUE: "<unscopedPackageName>.api.md"
115
+ */
116
+ // "reportFileName": "<unscopedPackageName>.api.md",
117
+ /**
118
+ * Specifies the folder where the API report file is written. The file name portion is determined by
119
+ * the "reportFileName" setting.
120
+ *
121
+ * The API report file is normally tracked by Git. Changes to it can be used to trigger a branch policy,
122
+ * e.g. for an API review.
123
+ *
124
+ * The path is resolved relative to the folder of the config file that contains the setting; to change this,
125
+ * prepend a folder token such as "<projectFolder>".
126
+ *
127
+ * SUPPORTED TOKENS: <projectFolder>, <packageName>, <unscopedPackageName>
128
+ * DEFAULT VALUE: "<projectFolder>/etc/"
129
+ */
130
+ // "reportFolder": "<projectFolder>/etc/",
131
+ /**
132
+ * Specifies the folder where the temporary report file is written. The file name portion is determined by
133
+ * the "reportFileName" setting.
134
+ *
135
+ * After the temporary file is written to disk, it is compared with the file in the "reportFolder".
136
+ * If they are different, a production build will fail.
137
+ *
138
+ * The path is resolved relative to the folder of the config file that contains the setting; to change this,
139
+ * prepend a folder token such as "<projectFolder>".
140
+ *
141
+ * SUPPORTED TOKENS: <projectFolder>, <packageName>, <unscopedPackageName>
142
+ * DEFAULT VALUE: "<projectFolder>/temp/"
143
+ */
144
+ // "reportTempFolder": "<projectFolder>/temp/"
145
+ },
146
+ /**
147
+ * Configures how the doc model file (*.api.json) will be generated.
148
+ */
149
+ "docModel": {
150
+ /**
151
+ * (REQUIRED) Whether to generate a doc model file.
152
+ */
153
+ "enabled": true
154
+ /**
155
+ * The output path for the doc model file. The file extension should be ".api.json".
156
+ *
157
+ * The path is resolved relative to the folder of the config file that contains the setting; to change this,
158
+ * prepend a folder token such as "<projectFolder>".
159
+ *
160
+ * SUPPORTED TOKENS: <projectFolder>, <packageName>, <unscopedPackageName>
161
+ * DEFAULT VALUE: "<projectFolder>/temp/<unscopedPackageName>.api.json"
162
+ */
163
+ // "apiJsonFilePath": "<projectFolder>/temp/<unscopedPackageName>.api.json"
164
+ },
165
+ /**
166
+ * Configures how the .d.ts rollup file will be generated.
167
+ */
168
+ "dtsRollup": {
169
+ /**
170
+ * (REQUIRED) Whether to generate the .d.ts rollup file.
171
+ */
172
+ "enabled": true
173
+ /**
174
+ * Specifies the output path for a .d.ts rollup file to be generated without any trimming.
175
+ * This file will include all declarations that are exported by the main entry point.
176
+ *
177
+ * If the path is an empty string, then this file will not be written.
178
+ *
179
+ * The path is resolved relative to the folder of the config file that contains the setting; to change this,
180
+ * prepend a folder token such as "<projectFolder>".
181
+ *
182
+ * SUPPORTED TOKENS: <projectFolder>, <packageName>, <unscopedPackageName>
183
+ * DEFAULT VALUE: "<projectFolder>/dist/<unscopedPackageName>.d.ts"
184
+ */
185
+ // "untrimmedFilePath": "<projectFolder>/dist/<unscopedPackageName>.d.ts",
186
+ /**
187
+ * Specifies the output path for a .d.ts rollup file to be generated with trimming for a "beta" release.
188
+ * This file will include only declarations that are marked as "@public" or "@beta".
189
+ *
190
+ * The path is resolved relative to the folder of the config file that contains the setting; to change this,
191
+ * prepend a folder token such as "<projectFolder>".
192
+ *
193
+ * SUPPORTED TOKENS: <projectFolder>, <packageName>, <unscopedPackageName>
194
+ * DEFAULT VALUE: ""
195
+ */
196
+ // "betaTrimmedFilePath": "<projectFolder>/dist/<unscopedPackageName>-beta.d.ts",
197
+ /**
198
+ * Specifies the output path for a .d.ts rollup file to be generated with trimming for a "public" release.
199
+ * This file will include only declarations that are marked as "@public".
200
+ *
201
+ * If the path is an empty string, then this file will not be written.
202
+ *
203
+ * The path is resolved relative to the folder of the config file that contains the setting; to change this,
204
+ * prepend a folder token such as "<projectFolder>".
205
+ *
206
+ * SUPPORTED TOKENS: <projectFolder>, <packageName>, <unscopedPackageName>
207
+ * DEFAULT VALUE: ""
208
+ */
209
+ // "publicTrimmedFilePath": "<projectFolder>/dist/<unscopedPackageName>-public.d.ts",
210
+ /**
211
+ * When a declaration is trimmed, by default it will be replaced by a code comment such as
212
+ * "Excluded from this release type: exampleMember". Set "omitTrimmingComments" to true to remove the
213
+ * declaration completely.
214
+ *
215
+ * DEFAULT VALUE: false
216
+ */
217
+ // "omitTrimmingComments": true
218
+ },
219
+ /**
220
+ * Configures how the tsdoc-metadata.json file will be generated.
221
+ */
222
+ "tsdocMetadata": {
223
+ /**
224
+ * Whether to generate the tsdoc-metadata.json file.
225
+ *
226
+ * DEFAULT VALUE: true
227
+ */
228
+ // "enabled": true,
229
+ /**
230
+ * Specifies where the TSDoc metadata file should be written.
231
+ *
232
+ * The path is resolved relative to the folder of the config file that contains the setting; to change this,
233
+ * prepend a folder token such as "<projectFolder>".
234
+ *
235
+ * The default value is "<lookup>", which causes the path to be automatically inferred from the "tsdocMetadata",
236
+ * "typings" or "main" fields of the project's package.json. If none of these fields are set, the lookup
237
+ * falls back to "tsdoc-metadata.json" in the package folder.
238
+ *
239
+ * SUPPORTED TOKENS: <projectFolder>, <packageName>, <unscopedPackageName>
240
+ * DEFAULT VALUE: "<lookup>"
241
+ */
242
+ // "tsdocMetadataFilePath": "<projectFolder>/dist/tsdoc-metadata.json"
243
+ },
244
+ /**
245
+ * Specifies what type of newlines API Extractor should use when writing output files. By default, the output files
246
+ * will be written with Windows-style newlines. To use POSIX-style newlines, specify "lf" instead.
247
+ * To use the OS's default newline kind, specify "os".
248
+ *
249
+ * DEFAULT VALUE: "crlf"
250
+ */
251
+ // "newlineKind": "crlf",
252
+ /**
253
+ * Configures how API Extractor reports error and warning messages produced during analysis.
254
+ *
255
+ * There are three sources of messages: compiler messages, API Extractor messages, and TSDoc messages.
256
+ */
257
+ "messages": {
258
+ /**
259
+ * Configures handling of diagnostic messages reported by the TypeScript compiler engine while analyzing
260
+ * the input .d.ts files.
261
+ *
262
+ * TypeScript message identifiers start with "TS" followed by an integer. For example: "TS2551"
263
+ *
264
+ * DEFAULT VALUE: A single "default" entry with logLevel=warning.
265
+ */
266
+ "compilerMessageReporting": {
267
+ /**
268
+ * Configures the default routing for messages that don't match an explicit rule in this table.
269
+ */
270
+ "default": {
271
+ /**
272
+ * Specifies whether the message should be written to the the tool's output log. Note that
273
+ * the "addToApiReportFile" property may supersede this option.
274
+ *
275
+ * Possible values: "error", "warning", "none"
276
+ *
277
+ * Errors cause the build to fail and return a nonzero exit code. Warnings cause a production build fail
278
+ * and return a nonzero exit code. For a non-production build (e.g. when "api-extractor run" includes
279
+ * the "--local" option), the warning is displayed but the build will not fail.
280
+ *
281
+ * DEFAULT VALUE: "warning"
282
+ */
283
+ "logLevel": "warning"
284
+ /**
285
+ * When addToApiReportFile is true: If API Extractor is configured to write an API report file (.api.md),
286
+ * then the message will be written inside that file; otherwise, the message is instead logged according to
287
+ * the "logLevel" option.
288
+ *
289
+ * DEFAULT VALUE: false
290
+ */
291
+ // "addToApiReportFile": false
292
+ }
293
+ // "TS2551": {
294
+ // "logLevel": "warning",
295
+ // "addToApiReportFile": true
296
+ // },
297
+ //
298
+ // . . .
299
+ },
300
+ /**
301
+ * Configures handling of messages reported by API Extractor during its analysis.
302
+ *
303
+ * API Extractor message identifiers start with "ae-". For example: "ae-extra-release-tag"
304
+ *
305
+ * DEFAULT VALUE: See api-extractor-defaults.json for the complete table of extractorMessageReporting mappings
306
+ */
307
+ "extractorMessageReporting": {
308
+ "default": {
309
+ "logLevel": "warning"
310
+ // "addToApiReportFile": false
311
+ },
312
+ "ae-unresolved-link": {
313
+ "logLevel": "none",
314
+ "addToApiReportFile": true
315
+ }
316
+ // "ae-extra-release-tag": {
317
+ // "logLevel": "warning",
318
+ // "addToApiReportFile": true
319
+ // },
320
+ //
321
+ // . . .
322
+ },
323
+ /**
324
+ * Configures handling of messages reported by the TSDoc parser when analyzing code comments.
325
+ *
326
+ * TSDoc message identifiers start with "tsdoc-". For example: "tsdoc-link-tag-unescaped-text"
327
+ *
328
+ * DEFAULT VALUE: A single "default" entry with logLevel=warning.
329
+ */
330
+ "tsdocMessageReporting": {
331
+ "default": {
332
+ "logLevel": "warning"
333
+ // "addToApiReportFile": false
334
+ }
335
+ // "tsdoc-link-tag-unescaped-text": {
336
+ // "logLevel": "warning",
337
+ // "addToApiReportFile": true
338
+ // },
339
+ //
340
+ // . . .
341
+ }
342
+ }
343
+ }
package/config/jest.config.json ADDED
@@ -0,0 +1,14 @@
1
+ {
2
+ "extends": "@rushstack/heft-node-rig/profiles/default/config/jest.config.json",
3
+ "coveragePathIgnorePatterns": ["index.js"],
4
+ "coverageThreshold": {
5
+ "global": {
6
+ "branches": 100,
7
+ "functions": 100,
8
+ "lines": 100,
9
+ "statements": 100
10
+ }
11
+ },
12
+ "collectCoverage": true,
13
+ "coverageReporters": ["text", "lcov", "html"]
14
+ }
package/config/rig.json ADDED
@@ -0,0 +1,4 @@
1
+ {
2
+ "$schema": "https://developer.microsoft.com/json-schemas/rig-package/rig.schema.json",
3
+ "rigPackageName": "@fgv/heft-dual-rig"
4
+ }
package/dist/index.js ADDED
@@ -0,0 +1,12 @@
1
+ /*
2
+ * Copyright (c) 2026 Erik Fortune
3
+ * SPDX-License-Identifier: MIT
4
+ */
5
+ export * from './packlets/types';
6
+ export * from './packlets/converters';
7
+ export * from './packlets/store';
8
+ export * from './packlets/index';
9
+ export * from './packlets/retrieve';
10
+ export * from './packlets/observe';
11
+ export * from './packlets/vector';
12
+ //# sourceMappingURL=index.js.map
package/dist/index.js.map ADDED
@@ -0,0 +1 @@
1
+ {"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,cAAc,kBAAkB,CAAC;AACjC,cAAc,uBAAuB,CAAC;AACtC,cAAc,kBAAkB,CAAC;AACjC,cAAc,kBAAkB,CAAC;AACjC,cAAc,qBAAqB,CAAC;AACpC,cAAc,oBAAoB,CAAC;AACnC,cAAc,mBAAmB,CAAC","sourcesContent":["/*\n * Copyright (c) 2026 Erik Fortune\n * SPDX-License-Identifier: MIT\n */\n\nexport * from './packlets/types';\nexport * from './packlets/converters';\nexport * from './packlets/store';\nexport * from './packlets/index';\nexport * from './packlets/retrieve';\nexport * from './packlets/observe';\nexport * from './packlets/vector';\n"]}
package/dist/packlets/converters/bodyConverterRegistry.js ADDED
@@ -0,0 +1,51 @@
1
+ /*
2
+ * Copyright (c) 2026 Erik Fortune
3
+ * SPDX-License-Identifier: MIT
4
+ */
5
+ import { Converters, fail, succeed } from '@fgv/ts-utils';
6
+ /**
7
+ * Default in-memory {@link IBodyConverterRegistry}.
8
+ *
9
+ * @remarks
10
+ * Both `register` and `registerSchema` adapt the supplied converter/validator
11
+ * into a `Converter<unknown>` via `Converters.generic`, so the heterogeneous
12
+ * per-kind types are stored uniformly with no cast and no `any`. A
13
+ * `Converter<T>` is not structurally a `Converter<unknown>` (the `map` callback
14
+ * makes the type invariant), so the `generic` wrapper — whose callback returns
15
+ * `Result<T>` (assignable to `Result<unknown>`) — is the type-safe bridge.
16
+ * @public
17
+ */
18
+ export class BodyConverterRegistry {
19
+ constructor() {
20
+ this._converters = new Map();
21
+ }
22
+ /** Family-convention factory. */
23
+ static create() {
24
+ return succeed(new BodyConverterRegistry());
25
+ }
26
+ /** {@inheritDoc IBodyConverterRegistry.register} */
27
+ register(kind, converter) {
28
+ this._converters.set(kind, Converters.generic((from) => converter.convert(from)));
29
+ }
30
+ /** {@inheritDoc IBodyConverterRegistry.registerSchema} */
31
+ registerSchema(kind, schema) {
32
+ this._converters.set(kind, Converters.generic((from) => schema.convert(from)));
33
+ }
34
+ /** {@inheritDoc IBodyConverterRegistry.has} */
35
+ has(kind) {
36
+ return this._converters.has(kind);
37
+ }
38
+ /** {@inheritDoc IBodyConverterRegistry.getConverter} */
39
+ getConverter(kind) {
40
+ const converter = this._converters.get(kind);
41
+ if (converter === undefined) {
42
+ return fail(`no converter registered for kind '${kind}'`);
43
+ }
44
+ return succeed(converter);
45
+ }
46
+ /** {@inheritDoc IBodyConverterRegistry.convert} */
47
+ convert(kind, body) {
48
+ return this.getConverter(kind).onSuccess((converter) => converter.convert(body));
49
+ }
50
+ }
51
+ //# sourceMappingURL=bodyConverterRegistry.js.map
package/dist/packlets/converters/bodyConverterRegistry.js.map ADDED
@@ -0,0 +1 @@
1
+ {"version":3,"file":"bodyConverterRegistry.js","sourceRoot":"","sources":["../../../src/packlets/converters/bodyConverterRegistry.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAa,UAAU,EAAU,IAAI,EAAE,OAAO,EAAE,MAAM,eAAe,CAAC;AAyC7E;;;;;;;;;;;GAWG;AACH,MAAM,OAAO,qBAAqB;IAGhC;QACE,IAAI,CAAC,WAAW,GAAG,IAAI,GAAG,EAA4B,CAAC;IACzD,CAAC;IAED,iCAAiC;IAC1B,MAAM,CAAC,MAAM;QAClB,OAAO,OAAO,CAAC,IAAI,qBAAqB,EAAE,CAAC,CAAC;IAC9C,CAAC;IAED,oDAAoD;IAC7C,QAAQ,CAAI,IAAU,EAAE,SAAuB;QACpD,IAAI,CAAC,WAAW,CAAC,GAAG,CAClB,IAAI,EACJ,UAAU,CAAC,OAAO,CAAU,CAAC,IAAa,EAAE,EAAE,CAAC,SAAS,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CACxE,CAAC;IACJ,CAAC;IAED,0DAA0D;IACnD,cAAc,CAAI,IAAU,EAAE,MAAsC;QACzE,IAAI,CAAC,WAAW,CAAC,GAAG,CAClB,IAAI,EACJ,UAAU,CAAC,OAAO,CAAU,CAAC,IAAa,EAAE,EAAE,CAAC,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CACrE,CAAC;IACJ,CAAC;IAED,+CAA+C;IACxC,GAAG,CAAC,IAAU;QACnB,OAAO,IAAI,CAAC,WAAW,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;IACpC,CAAC;IAED,wDAAwD;IACjD,YAAY,CAAC,IAAU;QAC5B,MAAM,SAAS,GAAmC,IAAI,CAAC,WAAW,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;QAC7E,IAAI,SAAS,KAAK,SAAS,EAAE,CAAC;YAC5B,OAAO,IAAI,CAAC,qCAAqC,IAAI,GAAG,CAAC,CAAC;QAC5D,CAAC;QACD,OAAO,OAAO,CAAC,SAAS,CAAC,CAAC;IAC5B,CAAC;IAED,mDAAmD;IAC5C,OAAO,CAAC,IAAU,EAAE,IAAa;QACtC,OAAO,IAAI,CAAC,YAAY,CAAC,IAAI,CAAC,CAAC,SAAS,CAAC,CAAC,SAAS,EAAE,EAAE,CAAC,SAAS,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC;IACnF,CAAC;CACF","sourcesContent":["/*\n * Copyright (c) 2026 Erik Fortune\n * SPDX-License-Identifier: MIT\n */\n\nimport { Converter, Converters, Result, fail, succeed } from '@fgv/ts-utils';\nimport { JsonSchema } from '@fgv/ts-json-base';\nimport { Kind } from '../types';\n\n/**\n * Registry of per-kind body Converters. Each memory {@link Kind} registers the\n * validated shape of its body; the store dispatches an `unknown` body through\n * the registered Converter on every write. Type-safe — no `any`.\n * @public\n */\nexport interface IBodyConverterRegistry {\n /**\n * Register a Converter for a kind. Replaces any prior registration for the\n * same kind.\n */\n register<T>(kind: Kind, converter: Converter<T>): void;\n\n /**\n * Register a `JsonSchema` validator (from `@fgv/ts-json-base`) for a kind —\n * the schema IS a Validator. Replaces any prior registration for the same\n * kind.\n */\n registerSchema<T>(kind: Kind, schema: JsonSchema.ISchemaValidator<T>): void;\n\n /** Returns `true` if a converter is registered for the kind. */\n has(kind: Kind): boolean;\n\n /**\n * Get the raw converter registered for a kind. Fails if the kind is\n * unregistered. Exposed for implementors that need to re-validate a patched\n * body (e.g. a temporal-versioned policy's `applyUpdate`).\n */\n getConverter(kind: Kind): Result<Converter<unknown>>;\n\n /**\n * Convert an `unknown` body value for the given kind. Fails with\n * `no converter registered for kind '<k>'` when unregistered.\n */\n convert(kind: Kind, body: unknown): Result<unknown>;\n}\n\n/**\n * Default in-memory {@link IBodyConverterRegistry}.\n *\n * @remarks\n * Both `register` and `registerSchema` adapt the supplied converter/validator\n * into a `Converter<unknown>` via `Converters.generic`, so the heterogeneous\n * per-kind types are stored uniformly with no cast and no `any`. A\n * `Converter<T>` is not structurally a `Converter<unknown>` (the `map` callback\n * makes the type invariant), so the `generic` wrapper — whose callback returns\n * `Result<T>` (assignable to `Result<unknown>`) — is the type-safe bridge.\n * @public\n */\nexport class BodyConverterRegistry implements IBodyConverterRegistry {\n private readonly _converters: Map<Kind, Converter<unknown>>;\n\n private constructor() {\n this._converters = new Map<Kind, Converter<unknown>>();\n }\n\n /** Family-convention factory. */\n public static create(): Result<BodyConverterRegistry> {\n return succeed(new BodyConverterRegistry());\n }\n\n /** {@inheritDoc IBodyConverterRegistry.register} */\n public register<T>(kind: Kind, converter: Converter<T>): void {\n this._converters.set(\n kind,\n Converters.generic<unknown>((from: unknown) => converter.convert(from))\n );\n }\n\n /** {@inheritDoc IBodyConverterRegistry.registerSchema} */\n public registerSchema<T>(kind: Kind, schema: JsonSchema.ISchemaValidator<T>): void {\n this._converters.set(\n kind,\n Converters.generic<unknown>((from: unknown) => schema.convert(from))\n );\n }\n\n /** {@inheritDoc IBodyConverterRegistry.has} */\n public has(kind: Kind): boolean {\n return this._converters.has(kind);\n }\n\n /** {@inheritDoc IBodyConverterRegistry.getConverter} */\n public getConverter(kind: Kind): Result<Converter<unknown>> {\n const converter: Converter<unknown> | undefined = this._converters.get(kind);\n if (converter === undefined) {\n return fail(`no converter registered for kind '${kind}'`);\n }\n return succeed(converter);\n }\n\n /** {@inheritDoc IBodyConverterRegistry.convert} */\n public convert(kind: Kind, body: unknown): Result<unknown> {\n return this.getConverter(kind).onSuccess((converter) => converter.convert(body));\n }\n}\n"]}
package/dist/packlets/converters/envelopeConverter.js ADDED
@@ -0,0 +1,159 @@
1
+ /*
2
+ * Copyright (c) 2026 Erik Fortune
3
+ * SPDX-License-Identifier: MIT
4
+ */
5
+ import { Converters, fail, succeed } from '@fgv/ts-utils';
6
+ import { Yaml } from '@fgv/ts-extras';
7
+ import { Convert } from '../types';
8
+ /** Matches exactly the JSON `null` literal. */
9
+ // eslint-disable-next-line @rushstack/no-new-null -- the envelope nullable fields (invalid_at, embeddingRef) carry meaningful null; design-lock §2.3-2.5
10
+ const nullConverter = Converters.generic((from) => from === null ? succeed(null) : fail('expected null'));
11
+ /** A nullable epoch-ms value (`number | null`). */
12
+ // eslint-disable-next-line @rushstack/no-new-null -- meaningful null for IEdge/ITemporalBlock.invalid_at; design-lock §2.3-2.4
13
+ const numberOrNull = Converters.oneOf([
14
+ Converters.number,
15
+ nullConverter
16
+ ]);
17
+ /** A nullable string value (`string | null`). */
18
+ // eslint-disable-next-line @rushstack/no-new-null -- meaningful null for IMemoryEnvelope.embeddingRef; design-lock §2.5
19
+ const stringOrNull = Converters.oneOf([
20
+ Converters.string,
21
+ nullConverter
22
+ ]);
23
+ /**
24
+ * Converter for the known {@link IProvenance} fields. The full
25
+ * {@link provenanceConverter} layers extension-key preservation on top.
26
+ */
27
+ const knownProvenanceConverter = Converters.object({
28
+ source: Converters.string,
29
+ by: Converters.string.optional(),
30
+ model: Converters.string.optional(),
31
+ confidence: Converters.number.optional(),
32
+ derivedFrom: Convert.memoryId.optional()
33
+ }, { optionalFields: ['by', 'model', 'confidence', 'derivedFrom'] });
34
+ /**
35
+ * Converter for {@link IProvenance}. Validates the known fields and preserves
36
+ * any extension keys verbatim (the `[key: string]: unknown` opaque payload),
37
+ * so a round-trip never drops consumer-attached data.
38
+ * @public
39
+ */
40
+ export const provenanceConverter = Converters.generic((from) => knownProvenanceConverter.convert(from).onSuccess((known) => {
41
+ // `from` is guaranteed to be a non-null object here — the known-field
42
+ // converter only succeeds on objects. Spread the original keys first,
43
+ // then the validated/normalized known fields on top, so extension keys
44
+ // survive while the known fields carry their converted values.
45
+ const merged = Object.assign(Object.assign({}, from), known);
46
+ return succeed(merged);
47
+ }));
48
+ /**
49
+ * Converter for an attributed {@link IEdge}.
50
+ * @public
51
+ */
52
+ export const edgeConverter = Converters.object({
53
+ type: Convert.linkType,
54
+ target: Convert.memoryId,
55
+ confidence: Converters.number.optional(),
56
+ provenance: provenanceConverter.optional(),
57
+ valid_at: Converters.number.optional(),
58
+ invalid_at: numberOrNull.optional()
59
+ }, { optionalFields: ['confidence', 'provenance', 'valid_at', 'invalid_at'] });
60
+ /**
61
+ * Converter for the optional {@link ITemporalBlock}.
62
+ * @public
63
+ */
64
+ export const temporalConverter = Converters.object({
65
+ valid_at: Converters.number.optional(),
66
+ invalid_at: numberOrNull.optional()
67
+ }, { optionalFields: ['valid_at', 'invalid_at'] });
68
+ /**
69
+ * Converter for the invariant {@link IMemoryEnvelope}. Validates a plain
70
+ * object (e.g. parsed YAML frontmatter) into a typed envelope.
71
+ * @public
72
+ */
73
+ export const envelopeConverter = Converters.object({
74
+ id: Convert.memoryId,
75
+ entityId: Convert.entityId,
76
+ kind: Convert.kind,
77
+ tags: Converters.arrayOf(Convert.tag),
78
+ links: Converters.arrayOf(edgeConverter),
79
+ created: Converters.number,
80
+ updated: Converters.number,
81
+ seq: Converters.number,
82
+ contentHash: Converters.string,
83
+ provenance: provenanceConverter,
84
+ temporal: temporalConverter.optional(),
85
+ embeddingRef: stringOrNull.optional()
86
+ }, { optionalFields: ['temporal', 'embeddingRef'] });
87
+ /**
88
+ * Converter that parses a YAML frontmatter string into an
89
+ * {@link IMemoryEnvelope}.
90
+ * @public
91
+ */
92
+ export const envelopeYamlConverter = Yaml.yamlConverter(envelopeConverter);
93
+ /** The frontmatter delimiter line. */
94
+ const FRONTMATTER_DELIMITER = '---';
95
+ /**
96
+ * Split a `---\n<yaml>\n---\n<body>` memory file into its frontmatter and
97
+ * body parts. Pure string handling — no external dependency.
98
+ * @public
99
+ */
100
+ export function splitFrontmatter(raw) {
101
+ // Split on '\n' and strip a trailing '\r' per line so CRLF-authored files
102
+ // parse identically to LF — otherwise the '\r' would ride along into the
103
+ // returned frontmatter (perturbing YAML parsing) and body (corrupting
104
+ // round-trip fidelity).
105
+ const lines = raw.split('\n').map((line) => (line.endsWith('\r') ? line.slice(0, -1) : line));
106
+ if (lines[0].trim() !== FRONTMATTER_DELIMITER) {
107
+ return fail("memory file: missing opening frontmatter delimiter '---'");
108
+ }
109
+ let closeIndex = -1;
110
+ for (let i = 1; i < lines.length; i++) {
111
+ if (lines[i].trim() === FRONTMATTER_DELIMITER) {
112
+ closeIndex = i;
113
+ break;
114
+ }
115
+ }
116
+ if (closeIndex === -1) {
117
+ return fail("memory file: missing closing frontmatter delimiter '---'");
118
+ }
119
+ return succeed({
120
+ frontmatter: lines.slice(1, closeIndex).join('\n'),
121
+ body: lines.slice(closeIndex + 1).join('\n')
122
+ });
123
+ }
124
+ /**
125
+ * Join a YAML frontmatter string and a body into the canonical
126
+ * `---\n<yaml>\n---\n<body>` memory-file format.
127
+ * @public
128
+ */
129
+ export function joinFrontmatter(frontmatter, body) {
130
+ const normalized = frontmatter.endsWith('\n') ? frontmatter : `${frontmatter}\n`;
131
+ return `${FRONTMATTER_DELIMITER}\n${normalized}${FRONTMATTER_DELIMITER}\n${body}`;
132
+ }
133
+ /**
134
+ * Parse a complete memory file into a typed {@link IMemoryRecord}. Splits the
135
+ * frontmatter, validates the envelope, and dispatches the body through the
136
+ * registered Converter for the envelope's kind.
137
+ * @public
138
+ */
139
+ export function parseMemoryFile(raw, registry) {
140
+ return splitFrontmatter(raw).onSuccess((parts) => envelopeYamlConverter
141
+ .convert(parts.frontmatter)
142
+ .withErrorFormat((msg) => `memory file: invalid envelope: ${msg}`)
143
+ .onSuccess((envelope) => registry
144
+ .convert(envelope.kind, parts.body)
145
+ .withErrorFormat((msg) => `memory file '${envelope.id}': invalid body: ${msg}`)
146
+ .onSuccess((body) => succeed({ envelope, body }))));
147
+ }
148
+ /**
149
+ * Serialize an envelope and its rendered body text into a memory file. The
150
+ * envelope is emitted as YAML frontmatter; the body is written verbatim after
151
+ * the closing delimiter.
152
+ * @public
153
+ */
154
+ export function serializeMemoryFile(envelope, body) {
155
+ return Yaml.yamlStringify(envelope)
156
+ .withErrorFormat((msg) => `memory file '${envelope.id}': failed to serialize envelope: ${msg}`)
157
+ .onSuccess((frontmatter) => succeed(joinFrontmatter(frontmatter, body)));
158
+ }
159
+ //# sourceMappingURL=envelopeConverter.js.map