agentfootprint 8.6.0 → 8.8.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 (241) hide show
  1. package/AGENTS.md +12 -4
  2. package/CLAUDE.md +4 -2
  3. package/README.md +1 -1
  4. package/ai-instructions/claude-code/SKILL.md +1 -1
  5. package/ai-instructions/setup.sh +0 -0
  6. package/bin/agentfootprint-lint-tools.mjs +0 -0
  7. package/dist/core/agent/AgentBuilder.js +104 -0
  8. package/dist/core/agent/AgentBuilder.js.map +1 -1
  9. package/dist/core/agent/buildAgentChart.js +12 -1
  10. package/dist/core/agent/buildAgentChart.js.map +1 -1
  11. package/dist/core/agent/buildDynamicAgentChart.js +12 -1
  12. package/dist/core/agent/buildDynamicAgentChart.js.map +1 -1
  13. package/dist/core/agent/memoryRecallInjections.js +100 -10
  14. package/dist/core/agent/memoryRecallInjections.js.map +1 -1
  15. package/dist/core/agent/stages/deliver.js.map +1 -1
  16. package/dist/core/slots/buildSystemPromptSlot.js +10 -0
  17. package/dist/core/slots/buildSystemPromptSlot.js.map +1 -1
  18. package/dist/core/slots/buildToolsSlot.js +77 -0
  19. package/dist/core/slots/buildToolsSlot.js.map +1 -1
  20. package/dist/core/slots/helpers.js +12 -10
  21. package/dist/core/slots/helpers.js.map +1 -1
  22. package/dist/esm/core/agent/AgentBuilder.js +104 -0
  23. package/dist/esm/core/agent/AgentBuilder.js.map +1 -1
  24. package/dist/esm/core/agent/buildAgentChart.js +13 -2
  25. package/dist/esm/core/agent/buildAgentChart.js.map +1 -1
  26. package/dist/esm/core/agent/buildDynamicAgentChart.js +13 -2
  27. package/dist/esm/core/agent/buildDynamicAgentChart.js.map +1 -1
  28. package/dist/esm/core/agent/memoryRecallInjections.d.ts +13 -3
  29. package/dist/esm/core/agent/memoryRecallInjections.js +101 -11
  30. package/dist/esm/core/agent/memoryRecallInjections.js.map +1 -1
  31. package/dist/esm/core/agent/stages/deliver.d.ts +6 -3
  32. package/dist/esm/core/agent/stages/deliver.js.map +1 -1
  33. package/dist/esm/core/slots/buildSystemPromptSlot.js +10 -0
  34. package/dist/esm/core/slots/buildSystemPromptSlot.js.map +1 -1
  35. package/dist/esm/core/slots/buildToolsSlot.js +78 -1
  36. package/dist/esm/core/slots/buildToolsSlot.js.map +1 -1
  37. package/dist/esm/core/slots/helpers.d.ts +11 -2
  38. package/dist/esm/core/slots/helpers.js +11 -9
  39. package/dist/esm/core/slots/helpers.js.map +1 -1
  40. package/dist/esm/events/payloads.d.ts +92 -0
  41. package/dist/esm/events/registry.d.ts +5 -1
  42. package/dist/esm/events/registry.js +4 -0
  43. package/dist/esm/events/registry.js.map +1 -1
  44. package/dist/esm/index.d.ts +2 -1
  45. package/dist/esm/index.js +6 -1
  46. package/dist/esm/index.js.map +1 -1
  47. package/dist/esm/lib/fnv1a.d.ts +16 -0
  48. package/dist/esm/lib/fnv1a.js +24 -0
  49. package/dist/esm/lib/fnv1a.js.map +1 -0
  50. package/dist/esm/lib/injection-engine/factories/defineRelevanceHint.d.ts +15 -0
  51. package/dist/esm/lib/injection-engine/factories/defineRelevanceHint.js +16 -0
  52. package/dist/esm/lib/injection-engine/factories/defineRelevanceHint.js.map +1 -1
  53. package/dist/esm/lib/injection-engine/factories/defineSkill.d.ts +9 -0
  54. package/dist/esm/lib/injection-engine/factories/defineSkill.js.map +1 -1
  55. package/dist/esm/lib/injection-engine/index.d.ts +3 -3
  56. package/dist/esm/lib/injection-engine/index.js +8 -3
  57. package/dist/esm/lib/injection-engine/index.js.map +1 -1
  58. package/dist/esm/lib/injection-engine/skillContract.d.ts +25 -2
  59. package/dist/esm/lib/injection-engine/skillContract.js +11 -4
  60. package/dist/esm/lib/injection-engine/skillContract.js.map +1 -1
  61. package/dist/esm/lib/injection-engine/skillGraph.d.ts +65 -4
  62. package/dist/esm/lib/injection-engine/skillGraph.js +36 -11
  63. package/dist/esm/lib/injection-engine/skillGraph.js.map +1 -1
  64. package/dist/esm/lib/injection-engine/skillGraphCheckup.d.ts +47 -7
  65. package/dist/esm/lib/injection-engine/skillGraphCheckup.js +165 -13
  66. package/dist/esm/lib/injection-engine/skillGraphCheckup.js.map +1 -1
  67. package/dist/esm/lib/injection-engine/skillsFromDir.d.ts +24 -0
  68. package/dist/esm/lib/injection-engine/skillsFromDir.js +19 -0
  69. package/dist/esm/lib/injection-engine/skillsFromDir.js.map +1 -1
  70. package/dist/esm/lib/injection-engine/types.d.ts +25 -0
  71. package/dist/esm/lib/injection-engine/types.js.map +1 -1
  72. package/dist/esm/lib/rag/defineRAG.d.ts +126 -26
  73. package/dist/esm/lib/rag/defineRAG.js +112 -25
  74. package/dist/esm/lib/rag/defineRAG.js.map +1 -1
  75. package/dist/esm/lib/rag/index.d.ts +1 -1
  76. package/dist/esm/lib/rag/index.js +1 -1
  77. package/dist/esm/lib/rag/index.js.map +1 -1
  78. package/dist/esm/memory/define.js +38 -2
  79. package/dist/esm/memory/define.js.map +1 -1
  80. package/dist/esm/memory/define.types.d.ts +93 -1
  81. package/dist/esm/memory/define.types.js +18 -0
  82. package/dist/esm/memory/define.types.js.map +1 -1
  83. package/dist/esm/memory/embedding/loadRelevant.d.ts +49 -15
  84. package/dist/esm/memory/embedding/loadRelevant.js +136 -7
  85. package/dist/esm/memory/embedding/loadRelevant.js.map +1 -1
  86. package/dist/esm/memory/index.d.ts +2 -1
  87. package/dist/esm/memory/index.js +2 -1
  88. package/dist/esm/memory/index.js.map +1 -1
  89. package/dist/esm/memory/pipeline/semantic.d.ts +15 -0
  90. package/dist/esm/memory/pipeline/semantic.js +3 -1
  91. package/dist/esm/memory/pipeline/semantic.js.map +1 -1
  92. package/dist/esm/memory/retrieval/index.d.ts +10 -0
  93. package/dist/esm/memory/retrieval/index.js +3 -0
  94. package/dist/esm/memory/retrieval/index.js.map +1 -0
  95. package/dist/esm/memory/retrieval/provenance.d.ts +43 -0
  96. package/dist/esm/memory/retrieval/provenance.js +60 -0
  97. package/dist/esm/memory/retrieval/provenance.js.map +1 -0
  98. package/dist/esm/memory/retrieval/topK.d.ts +67 -0
  99. package/dist/esm/memory/retrieval/topK.js +53 -0
  100. package/dist/esm/memory/retrieval/topK.js.map +1 -0
  101. package/dist/esm/memory/retrieval/types.d.ts +189 -0
  102. package/dist/esm/memory/retrieval/types.js +2 -0
  103. package/dist/esm/memory/retrieval/types.js.map +1 -0
  104. package/dist/esm/memory/stages/formatDefault.d.ts +52 -26
  105. package/dist/esm/memory/stages/formatDefault.js +118 -28
  106. package/dist/esm/memory/stages/formatDefault.js.map +1 -1
  107. package/dist/esm/memory/stages/pickByBudget.js +53 -3
  108. package/dist/esm/memory/stages/pickByBudget.js.map +1 -1
  109. package/dist/esm/memory/stages/types.d.ts +15 -0
  110. package/dist/esm/memory/wire/mountMemoryPipeline.d.ts +25 -0
  111. package/dist/esm/memory/wire/mountMemoryPipeline.js +11 -2
  112. package/dist/esm/memory/wire/mountMemoryPipeline.js.map +1 -1
  113. package/dist/esm/tool-providers/index.d.ts +1 -1
  114. package/dist/esm/tool-providers/index.js +4 -1
  115. package/dist/esm/tool-providers/index.js.map +1 -1
  116. package/dist/esm/tool-providers/skillScopedTools.d.ts +4 -0
  117. package/dist/esm/tool-providers/skillScopedTools.js +33 -2
  118. package/dist/esm/tool-providers/skillScopedTools.js.map +1 -1
  119. package/dist/esm/tool-providers/types.d.ts +25 -0
  120. package/dist/events/registry.js +4 -0
  121. package/dist/events/registry.js.map +1 -1
  122. package/dist/index.js +8 -1
  123. package/dist/index.js.map +1 -1
  124. package/dist/lib/fnv1a.js +28 -0
  125. package/dist/lib/fnv1a.js.map +1 -0
  126. package/dist/lib/injection-engine/factories/defineRelevanceHint.js +17 -1
  127. package/dist/lib/injection-engine/factories/defineRelevanceHint.js.map +1 -1
  128. package/dist/lib/injection-engine/factories/defineSkill.js.map +1 -1
  129. package/dist/lib/injection-engine/index.js +7 -1
  130. package/dist/lib/injection-engine/index.js.map +1 -1
  131. package/dist/lib/injection-engine/skillContract.js +11 -4
  132. package/dist/lib/injection-engine/skillContract.js.map +1 -1
  133. package/dist/lib/injection-engine/skillGraph.js +37 -11
  134. package/dist/lib/injection-engine/skillGraph.js.map +1 -1
  135. package/dist/lib/injection-engine/skillGraphCheckup.js +165 -13
  136. package/dist/lib/injection-engine/skillGraphCheckup.js.map +1 -1
  137. package/dist/lib/injection-engine/skillsFromDir.js +19 -0
  138. package/dist/lib/injection-engine/skillsFromDir.js.map +1 -1
  139. package/dist/lib/injection-engine/types.js.map +1 -1
  140. package/dist/lib/rag/defineRAG.js +113 -26
  141. package/dist/lib/rag/defineRAG.js.map +1 -1
  142. package/dist/lib/rag/index.js +2 -1
  143. package/dist/lib/rag/index.js.map +1 -1
  144. package/dist/memory/define.js +38 -2
  145. package/dist/memory/define.js.map +1 -1
  146. package/dist/memory/define.types.js +21 -1
  147. package/dist/memory/define.types.js.map +1 -1
  148. package/dist/memory/embedding/loadRelevant.js +138 -8
  149. package/dist/memory/embedding/loadRelevant.js.map +1 -1
  150. package/dist/memory/index.js +5 -1
  151. package/dist/memory/index.js.map +1 -1
  152. package/dist/memory/pipeline/semantic.js +2 -0
  153. package/dist/memory/pipeline/semantic.js.map +1 -1
  154. package/dist/memory/retrieval/index.js +9 -0
  155. package/dist/memory/retrieval/index.js.map +1 -0
  156. package/dist/memory/retrieval/provenance.js +65 -0
  157. package/dist/memory/retrieval/provenance.js.map +1 -0
  158. package/dist/memory/retrieval/topK.js +57 -0
  159. package/dist/memory/retrieval/topK.js.map +1 -0
  160. package/dist/memory/retrieval/types.js +3 -0
  161. package/dist/memory/retrieval/types.js.map +1 -0
  162. package/dist/memory/stages/formatDefault.js +118 -28
  163. package/dist/memory/stages/formatDefault.js.map +1 -1
  164. package/dist/memory/stages/pickByBudget.js +53 -3
  165. package/dist/memory/stages/pickByBudget.js.map +1 -1
  166. package/dist/memory/wire/mountMemoryPipeline.js +11 -2
  167. package/dist/memory/wire/mountMemoryPipeline.js.map +1 -1
  168. package/dist/tool-providers/index.js +5 -1
  169. package/dist/tool-providers/index.js.map +1 -1
  170. package/dist/tool-providers/skillScopedTools.js +35 -3
  171. package/dist/tool-providers/skillScopedTools.js.map +1 -1
  172. package/dist/types/core/agent/AgentBuilder.d.ts.map +1 -1
  173. package/dist/types/core/agent/buildAgentChart.d.ts.map +1 -1
  174. package/dist/types/core/agent/buildDynamicAgentChart.d.ts.map +1 -1
  175. package/dist/types/core/agent/memoryRecallInjections.d.ts +13 -3
  176. package/dist/types/core/agent/memoryRecallInjections.d.ts.map +1 -1
  177. package/dist/types/core/agent/stages/deliver.d.ts +6 -3
  178. package/dist/types/core/agent/stages/deliver.d.ts.map +1 -1
  179. package/dist/types/core/slots/buildSystemPromptSlot.d.ts.map +1 -1
  180. package/dist/types/core/slots/buildToolsSlot.d.ts.map +1 -1
  181. package/dist/types/core/slots/helpers.d.ts +11 -2
  182. package/dist/types/core/slots/helpers.d.ts.map +1 -1
  183. package/dist/types/events/payloads.d.ts +92 -0
  184. package/dist/types/events/payloads.d.ts.map +1 -1
  185. package/dist/types/events/registry.d.ts +5 -1
  186. package/dist/types/events/registry.d.ts.map +1 -1
  187. package/dist/types/index.d.ts +2 -1
  188. package/dist/types/index.d.ts.map +1 -1
  189. package/dist/types/lib/fnv1a.d.ts +17 -0
  190. package/dist/types/lib/fnv1a.d.ts.map +1 -0
  191. package/dist/types/lib/injection-engine/factories/defineRelevanceHint.d.ts +15 -0
  192. package/dist/types/lib/injection-engine/factories/defineRelevanceHint.d.ts.map +1 -1
  193. package/dist/types/lib/injection-engine/factories/defineSkill.d.ts +9 -0
  194. package/dist/types/lib/injection-engine/factories/defineSkill.d.ts.map +1 -1
  195. package/dist/types/lib/injection-engine/index.d.ts +3 -3
  196. package/dist/types/lib/injection-engine/index.d.ts.map +1 -1
  197. package/dist/types/lib/injection-engine/skillContract.d.ts +25 -2
  198. package/dist/types/lib/injection-engine/skillContract.d.ts.map +1 -1
  199. package/dist/types/lib/injection-engine/skillGraph.d.ts +65 -4
  200. package/dist/types/lib/injection-engine/skillGraph.d.ts.map +1 -1
  201. package/dist/types/lib/injection-engine/skillGraphCheckup.d.ts +47 -7
  202. package/dist/types/lib/injection-engine/skillGraphCheckup.d.ts.map +1 -1
  203. package/dist/types/lib/injection-engine/skillsFromDir.d.ts +24 -0
  204. package/dist/types/lib/injection-engine/skillsFromDir.d.ts.map +1 -1
  205. package/dist/types/lib/injection-engine/types.d.ts +25 -0
  206. package/dist/types/lib/injection-engine/types.d.ts.map +1 -1
  207. package/dist/types/lib/rag/defineRAG.d.ts +126 -26
  208. package/dist/types/lib/rag/defineRAG.d.ts.map +1 -1
  209. package/dist/types/lib/rag/index.d.ts +1 -1
  210. package/dist/types/lib/rag/index.d.ts.map +1 -1
  211. package/dist/types/memory/define.d.ts.map +1 -1
  212. package/dist/types/memory/define.types.d.ts +93 -1
  213. package/dist/types/memory/define.types.d.ts.map +1 -1
  214. package/dist/types/memory/embedding/loadRelevant.d.ts +49 -15
  215. package/dist/types/memory/embedding/loadRelevant.d.ts.map +1 -1
  216. package/dist/types/memory/index.d.ts +2 -1
  217. package/dist/types/memory/index.d.ts.map +1 -1
  218. package/dist/types/memory/pipeline/semantic.d.ts +15 -0
  219. package/dist/types/memory/pipeline/semantic.d.ts.map +1 -1
  220. package/dist/types/memory/retrieval/index.d.ts +11 -0
  221. package/dist/types/memory/retrieval/index.d.ts.map +1 -0
  222. package/dist/types/memory/retrieval/provenance.d.ts +44 -0
  223. package/dist/types/memory/retrieval/provenance.d.ts.map +1 -0
  224. package/dist/types/memory/retrieval/topK.d.ts +68 -0
  225. package/dist/types/memory/retrieval/topK.d.ts.map +1 -0
  226. package/dist/types/memory/retrieval/types.d.ts +190 -0
  227. package/dist/types/memory/retrieval/types.d.ts.map +1 -0
  228. package/dist/types/memory/stages/formatDefault.d.ts +52 -26
  229. package/dist/types/memory/stages/formatDefault.d.ts.map +1 -1
  230. package/dist/types/memory/stages/pickByBudget.d.ts.map +1 -1
  231. package/dist/types/memory/stages/types.d.ts +15 -0
  232. package/dist/types/memory/stages/types.d.ts.map +1 -1
  233. package/dist/types/memory/wire/mountMemoryPipeline.d.ts +25 -0
  234. package/dist/types/memory/wire/mountMemoryPipeline.d.ts.map +1 -1
  235. package/dist/types/tool-providers/index.d.ts +1 -1
  236. package/dist/types/tool-providers/index.d.ts.map +1 -1
  237. package/dist/types/tool-providers/skillScopedTools.d.ts +4 -0
  238. package/dist/types/tool-providers/skillScopedTools.d.ts.map +1 -1
  239. package/dist/types/tool-providers/types.d.ts +25 -0
  240. package/dist/types/tool-providers/types.d.ts.map +1 -1
  241. package/package.json +1 -1
@@ -1,23 +1,66 @@
1
1
  /**
2
- * defineRAG — sugar factory for retrieval-augmented generation.
2
+ * defineRAG — retrieval-augmented generation over a document corpus.
3
3
  *
4
- * RAG is a context-engineering flavor: embed the user's question,
5
- * retrieve top-K semantically similar chunks from a vector store,
6
- * inject those chunks into the system-prompt slot of the next LLM call.
7
- * It's the same plumbing as `defineMemory({ type: SEMANTIC,
8
- * strategy: TOP_K })` — the rename is for intent + ergonomics.
4
+ * Embed the user's question, retrieve the most similar chunks from a
5
+ * vector store, inject them into the system-prompt slot of the next LLM
6
+ * call. It is the same machinery as `defineMemory({ type: SEMANTIC,
7
+ * strategy: TOP_K })` — with three differences that are not cosmetic:
9
8
  *
10
9
  * defineMemory ─┬─► EPISODIC (raw conversation)
11
10
  * ├─► SEMANTIC (extracted facts / RAG chunks)
12
11
  * ├─► NARRATIVE (beats / summaries)
13
12
  * └─► CAUSAL (footprintjs decision snapshots)
14
13
  *
15
- * defineRAG ─► SEMANTIC + TOP_K with RAG-specific defaults
16
- * (topK=3, threshold=0.7, no LLM-extract)
14
+ * defineRAG ─► SEMANTIC + TOP_K, READ-ONLY, over a NAMED CORPUS,
15
+ * rendered as citable <source> blocks.
16
+ *
17
+ * ─── What changed in 8.8.0, and why ────────────────────────────────────
18
+ *
19
+ * **1. A corpus is read-only.** Until 8.8.0 `defineRAG` also mounted the
20
+ * semantic pipeline's WRITE half, which embedded every conversation turn
21
+ * and stored it in the same namespace as the documents. The consequence
22
+ * was measurable and bad: the user's own question, re-embedded, is the
23
+ * single best-scoring "document" in the corpus (cosine 1.0 against
24
+ * itself), so it came back as retrieval hit #1 and consumed a slot in
25
+ * the top-K budget that a real passage should have had. A corpus is not
26
+ * a conversation log. Nothing this retriever reads is written back.
27
+ *
28
+ * If you want conversation memory ALONGSIDE a corpus, that is what
29
+ * `defineMemory` is for, and the two are registered separately, each
30
+ * with its own store:
31
+ *
32
+ * ```ts
33
+ * const agent = Agent.create({ provider })
34
+ * .rag(defineRAG({ id: 'product-docs', store: corpusStore, embedder }))
35
+ * .memory(defineMemory({
36
+ * id: 'chat',
37
+ * type: MEMORY_TYPES.EPISODIC,
38
+ * strategy: { kind: MEMORY_STRATEGIES.WINDOW, size: 10 },
39
+ * store: conversationStore,
40
+ * }))
41
+ * .build();
42
+ * ```
43
+ *
44
+ * **2. The corpus has its own namespace.** A memory reads under the
45
+ * identity passed to `agent.run()`. For conversation recall that is
46
+ * right. For a shared corpus it was the reason the documented example
47
+ * retrieved NOTHING: `indexDocuments` writes under
48
+ * `{ conversationId: '_global' }` by default, while a run with no
49
+ * explicit identity gets `{ conversationId: 'run-<timestamp>-<n>' }` —
50
+ * so the write side and the read side never met, silently. `corpus`
51
+ * defaults to the same `'_global'` the indexer uses, so the documented
52
+ * example works with no extra arguments; pass it explicitly when you
53
+ * index per tenant.
54
+ *
55
+ * **3. Chunks are citable.** Retrieved passages render as
56
+ * `<source id="refunds.md#3" doc="refunds.md" score="0.81">` under a
57
+ * corpus header, instead of the conversation-recall shape that printed
58
+ * `role="unknown" turn="0"` on a page of a PDF and gave the model
59
+ * nothing to cite.
17
60
  *
18
61
  * Pattern: Composition over duplication — defineRAG returns a
19
62
  * MemoryDefinition produced by defineMemory. No new engine
20
- * code, no new slot subflow, no new event type.
63
+ * code, no new slot subflow, no new stage.
21
64
  *
22
65
  * Role: Layer-3 context-engineering primitive. Lives next to
23
66
  * defineSkill / defineSteering / defineInstruction / defineFact
@@ -25,27 +68,32 @@
25
68
  * (RAG content is computed at runtime via async retrieval —
26
69
  * can't fit the synchronous Injection.inject shape).
27
70
  *
28
- * Emits: Indirectly — the underlying memory pipeline emits
29
- * `agentfootprint.context.injected` when retrieved chunks
30
- * land in the system-prompt slot.
71
+ * Emits: `agentfootprint.memory.retrieved` (once per retrieval, with
72
+ * every candidate and its score — including the rejected ones),
73
+ * `agentfootprint.memory.attached` (once per chunk that reached
74
+ * the prompt), and `agentfootprint.context.injected` with
75
+ * `source: 'rag'` (once per chunk).
31
76
  *
32
77
  * @see ./indexDocuments.ts for the seeding helper
33
78
  * @see ../../memory/define.ts for the underlying factory
79
+ * @see ../../memory/retrieval/ for the retrieval seam
34
80
  * @see ../../memory/asRoleRefusal.ts for why `asRole` is refused, not honoured
35
81
  *
36
- * @example Basic usage
82
+ * @example Basic usage — works with no identity argument anywhere
37
83
  * ```ts
38
- * import { * Agent, defineRAG, indexDocuments, * } from 'agentfootprint'
39
- import { InMemoryStore, mockEmbedder } from 'agentfootprint/memory'
40
- import { mock } from 'agentfootprint/llm-providers';
84
+ * import { Agent, defineRAG, indexDocuments } from 'agentfootprint';
85
+ * import { InMemoryStore, mockEmbedder } from 'agentfootprint/memory';
86
+ * import { mock } from 'agentfootprint/providers';
41
87
  *
42
88
  * const embedder = mockEmbedder();
43
89
  * const store = new InMemoryStore();
44
90
  *
45
- * // Seed the store once at startup
91
+ * // Seed the corpus once at startup (defaults to the '_global' namespace).
46
92
  * await indexDocuments(store, embedder, [
47
- * { id: 'doc1', content: 'Refunds are processed within 3 business days.' },
48
- * { id: 'doc2', content: 'Pro plan costs $20/month.' },
93
+ * { id: 'refunds.md#0', content: 'Refunds are processed within 3 business days.',
94
+ * metadata: { source: 'refunds.md' } },
95
+ * { id: 'pricing.md#0', content: 'Pro plan costs $20/month.',
96
+ * metadata: { source: 'pricing.md' } },
49
97
  * ]);
50
98
  *
51
99
  * const docs = defineRAG({
@@ -60,11 +108,27 @@ import { mock } from 'agentfootprint/llm-providers';
60
108
  * const agent = Agent.create({ provider: mock({ reply: 'ok' }), model: 'mock' })
61
109
  * .rag(docs)
62
110
  * .build();
111
+ *
112
+ * agent.on('agentfootprint.memory.retrieved', (e) => {
113
+ * // every candidate, admitted or not, with its score and its reason
114
+ * console.log(e.payload.candidates);
115
+ * });
116
+ *
117
+ * await agent.run({ message: 'How long do refunds take?' });
63
118
  * ```
64
119
  */
65
120
  import type { Embedder } from '../../memory/embedding/index.js';
66
121
  import type { MemoryStore } from '../../memory/store/index.js';
122
+ import type { MemoryIdentity } from '../../memory/identity/index.js';
67
123
  import type { MemoryDefinition } from '../../memory/define.types.js';
124
+ import type { RetrievalStrategy } from '../../memory/retrieval/index.js';
125
+ /**
126
+ * The namespace a corpus lives in unless told otherwise — the same one
127
+ * `indexDocuments` writes to by default. The two defaults are one value
128
+ * on purpose: index with no options, retrieve with no options, and the
129
+ * documents are found.
130
+ */
131
+ export declare const DEFAULT_CORPUS_IDENTITY: MemoryIdentity;
68
132
  export interface DefineRAGOptions {
69
133
  /** Stable id. Becomes the scope-key suffix and the Lens label. */
70
134
  readonly id: string;
@@ -78,13 +142,13 @@ export interface DefineRAGOptions {
78
142
  * Vector-capable store containing the indexed corpus. Must implement
79
143
  * `search()`. Use `indexDocuments(store, embedder, docs)` at startup
80
144
  * to populate it. Ships with `InMemoryStore` for dev/tests; swap to
81
- * `pgvector` / Pinecone / Qdrant adapters in production.
145
+ * a durable adapter in production.
82
146
  */
83
147
  readonly store: MemoryStore;
84
148
  /**
85
149
  * Embedder used for the read-side query. Pass the SAME embedder
86
- * instance (or one with the same `name`) that was used for indexing
87
- * — cross-model similarity scores are not comparable.
150
+ * instance (or one with the same `embedderId`) that was used for
151
+ * indexing — cross-model similarity scores are not comparable.
88
152
  */
89
153
  readonly embedder: Embedder;
90
154
  /**
@@ -93,10 +157,28 @@ export interface DefineRAGOptions {
93
157
  * embedder swap doesn't pollute results.
94
158
  */
95
159
  readonly embedderId?: string;
160
+ /**
161
+ * The namespace this corpus lives in. Default
162
+ * `{ conversationId: '_global' }` — the same default `indexDocuments`
163
+ * writes to, so the plain path needs no argument on either side.
164
+ *
165
+ * A corpus is deliberately NOT scoped to the run's identity: it is
166
+ * shared by every conversation, and reading it under a per-run
167
+ * conversation id is the bug this default fixes.
168
+ *
169
+ * **Multi-tenant:** pass the tenant's identity here AND the same one to
170
+ * `indexDocuments({ identity })`. A namespace that holds nothing is now
171
+ * reported (`corpusEmpty` on `agentfootprint.memory.retrieved`, plus a
172
+ * one-time warning naming the namespace), so a mismatch is loud rather
173
+ * than an empty answer.
174
+ */
175
+ readonly corpus?: MemoryIdentity;
96
176
  /**
97
177
  * Top-K chunks to retrieve per turn. Default 3 (balanced —
98
178
  * defends against lost-in-the-middle while giving multiple
99
179
  * perspectives). Increase for richer context, decrease for cost.
180
+ *
181
+ * Shorthand for `retrieval: topK({ k })`; the two EXCLUDE.
100
182
  */
101
183
  readonly topK?: number;
102
184
  /**
@@ -106,12 +188,29 @@ export interface DefineRAGOptions {
106
188
  *
107
189
  * Tuning note: 0.7 is a high bar for some embedders. Sentence-BERT
108
190
  * relatives (`all-MiniLM-L6-v2`, etc.) often score 0.4–0.6 even on
109
- * relevant chunks. If you see frequent zero-result silent skips,
110
- * lower to ~0.5 and observe the `agentfootprint.context.injected`
111
- * stream. OpenAI `text-embedding-3-*` and Cohere embed-v3 typically
112
- * sit comfortably with 0.7.
191
+ * relevant chunks. You no longer have to guess: the rejected
192
+ * candidates and their scores are on every
193
+ * `agentfootprint.memory.retrieved` event, so the right threshold is
194
+ * a number you can read off a run.
195
+ *
196
+ * Shorthand for `retrieval: topK({ threshold })`; the two EXCLUDE.
113
197
  */
114
198
  readonly threshold?: number;
199
+ /**
200
+ * The retrieval rule, spelled out. Replaces `topK` + `threshold`
201
+ * entirely — passing both is refused, because they could disagree
202
+ * and the recording would then name a `k` the run did not use.
203
+ *
204
+ * ```ts
205
+ * import { topK } from 'agentfootprint/memory';
206
+ * defineRAG({ id, store, embedder, retrieval: topK({ k: 5, threshold: 0.55 }) });
207
+ * ```
208
+ *
209
+ * A cross-encoder re-ranker and a diversity (MMR) selector are the
210
+ * next two adapters behind this same interface; neither ships in
211
+ * 8.8.0, and the seam exists so that when they do, nothing else moves.
212
+ */
213
+ readonly retrieval?: RetrievalStrategy;
115
214
  }
116
215
  /**
117
216
  * Build a RAG context-engineering definition. The returned
@@ -120,5 +219,6 @@ export interface DefineRAGOptions {
120
219
  *
121
220
  * @throws when `store` does not implement `search()`. RAG requires a
122
221
  * vector-capable adapter.
222
+ * @throws when `retrieval` is combined with `topK` or `threshold`.
123
223
  */
124
224
  export declare function defineRAG(opts: DefineRAGOptions): MemoryDefinition;
@@ -1,23 +1,66 @@
1
1
  /**
2
- * defineRAG — sugar factory for retrieval-augmented generation.
2
+ * defineRAG — retrieval-augmented generation over a document corpus.
3
3
  *
4
- * RAG is a context-engineering flavor: embed the user's question,
5
- * retrieve top-K semantically similar chunks from a vector store,
6
- * inject those chunks into the system-prompt slot of the next LLM call.
7
- * It's the same plumbing as `defineMemory({ type: SEMANTIC,
8
- * strategy: TOP_K })` — the rename is for intent + ergonomics.
4
+ * Embed the user's question, retrieve the most similar chunks from a
5
+ * vector store, inject them into the system-prompt slot of the next LLM
6
+ * call. It is the same machinery as `defineMemory({ type: SEMANTIC,
7
+ * strategy: TOP_K })` — with three differences that are not cosmetic:
9
8
  *
10
9
  * defineMemory ─┬─► EPISODIC (raw conversation)
11
10
  * ├─► SEMANTIC (extracted facts / RAG chunks)
12
11
  * ├─► NARRATIVE (beats / summaries)
13
12
  * └─► CAUSAL (footprintjs decision snapshots)
14
13
  *
15
- * defineRAG ─► SEMANTIC + TOP_K with RAG-specific defaults
16
- * (topK=3, threshold=0.7, no LLM-extract)
14
+ * defineRAG ─► SEMANTIC + TOP_K, READ-ONLY, over a NAMED CORPUS,
15
+ * rendered as citable <source> blocks.
16
+ *
17
+ * ─── What changed in 8.8.0, and why ────────────────────────────────────
18
+ *
19
+ * **1. A corpus is read-only.** Until 8.8.0 `defineRAG` also mounted the
20
+ * semantic pipeline's WRITE half, which embedded every conversation turn
21
+ * and stored it in the same namespace as the documents. The consequence
22
+ * was measurable and bad: the user's own question, re-embedded, is the
23
+ * single best-scoring "document" in the corpus (cosine 1.0 against
24
+ * itself), so it came back as retrieval hit #1 and consumed a slot in
25
+ * the top-K budget that a real passage should have had. A corpus is not
26
+ * a conversation log. Nothing this retriever reads is written back.
27
+ *
28
+ * If you want conversation memory ALONGSIDE a corpus, that is what
29
+ * `defineMemory` is for, and the two are registered separately, each
30
+ * with its own store:
31
+ *
32
+ * ```ts
33
+ * const agent = Agent.create({ provider })
34
+ * .rag(defineRAG({ id: 'product-docs', store: corpusStore, embedder }))
35
+ * .memory(defineMemory({
36
+ * id: 'chat',
37
+ * type: MEMORY_TYPES.EPISODIC,
38
+ * strategy: { kind: MEMORY_STRATEGIES.WINDOW, size: 10 },
39
+ * store: conversationStore,
40
+ * }))
41
+ * .build();
42
+ * ```
43
+ *
44
+ * **2. The corpus has its own namespace.** A memory reads under the
45
+ * identity passed to `agent.run()`. For conversation recall that is
46
+ * right. For a shared corpus it was the reason the documented example
47
+ * retrieved NOTHING: `indexDocuments` writes under
48
+ * `{ conversationId: '_global' }` by default, while a run with no
49
+ * explicit identity gets `{ conversationId: 'run-<timestamp>-<n>' }` —
50
+ * so the write side and the read side never met, silently. `corpus`
51
+ * defaults to the same `'_global'` the indexer uses, so the documented
52
+ * example works with no extra arguments; pass it explicitly when you
53
+ * index per tenant.
54
+ *
55
+ * **3. Chunks are citable.** Retrieved passages render as
56
+ * `<source id="refunds.md#3" doc="refunds.md" score="0.81">` under a
57
+ * corpus header, instead of the conversation-recall shape that printed
58
+ * `role="unknown" turn="0"` on a page of a PDF and gave the model
59
+ * nothing to cite.
17
60
  *
18
61
  * Pattern: Composition over duplication — defineRAG returns a
19
62
  * MemoryDefinition produced by defineMemory. No new engine
20
- * code, no new slot subflow, no new event type.
63
+ * code, no new slot subflow, no new stage.
21
64
  *
22
65
  * Role: Layer-3 context-engineering primitive. Lives next to
23
66
  * defineSkill / defineSteering / defineInstruction / defineFact
@@ -25,27 +68,32 @@
25
68
  * (RAG content is computed at runtime via async retrieval —
26
69
  * can't fit the synchronous Injection.inject shape).
27
70
  *
28
- * Emits: Indirectly — the underlying memory pipeline emits
29
- * `agentfootprint.context.injected` when retrieved chunks
30
- * land in the system-prompt slot.
71
+ * Emits: `agentfootprint.memory.retrieved` (once per retrieval, with
72
+ * every candidate and its score — including the rejected ones),
73
+ * `agentfootprint.memory.attached` (once per chunk that reached
74
+ * the prompt), and `agentfootprint.context.injected` with
75
+ * `source: 'rag'` (once per chunk).
31
76
  *
32
77
  * @see ./indexDocuments.ts for the seeding helper
33
78
  * @see ../../memory/define.ts for the underlying factory
79
+ * @see ../../memory/retrieval/ for the retrieval seam
34
80
  * @see ../../memory/asRoleRefusal.ts for why `asRole` is refused, not honoured
35
81
  *
36
- * @example Basic usage
82
+ * @example Basic usage — works with no identity argument anywhere
37
83
  * ```ts
38
- * import { * Agent, defineRAG, indexDocuments, * } from 'agentfootprint'
39
- import { InMemoryStore, mockEmbedder } from 'agentfootprint/memory'
40
- import { mock } from 'agentfootprint/llm-providers';
84
+ * import { Agent, defineRAG, indexDocuments } from 'agentfootprint';
85
+ * import { InMemoryStore, mockEmbedder } from 'agentfootprint/memory';
86
+ * import { mock } from 'agentfootprint/providers';
41
87
  *
42
88
  * const embedder = mockEmbedder();
43
89
  * const store = new InMemoryStore();
44
90
  *
45
- * // Seed the store once at startup
91
+ * // Seed the corpus once at startup (defaults to the '_global' namespace).
46
92
  * await indexDocuments(store, embedder, [
47
- * { id: 'doc1', content: 'Refunds are processed within 3 business days.' },
48
- * { id: 'doc2', content: 'Pro plan costs $20/month.' },
93
+ * { id: 'refunds.md#0', content: 'Refunds are processed within 3 business days.',
94
+ * metadata: { source: 'refunds.md' } },
95
+ * { id: 'pricing.md#0', content: 'Pro plan costs $20/month.',
96
+ * metadata: { source: 'pricing.md' } },
49
97
  * ]);
50
98
  *
51
99
  * const docs = defineRAG({
@@ -60,11 +108,25 @@ import { mock } from 'agentfootprint/llm-providers';
60
108
  * const agent = Agent.create({ provider: mock({ reply: 'ok' }), model: 'mock' })
61
109
  * .rag(docs)
62
110
  * .build();
111
+ *
112
+ * agent.on('agentfootprint.memory.retrieved', (e) => {
113
+ * // every candidate, admitted or not, with its score and its reason
114
+ * console.log(e.payload.candidates);
115
+ * });
116
+ *
117
+ * await agent.run({ message: 'How long do refunds take?' });
63
118
  * ```
64
119
  */
65
120
  import { MEMORY_TYPES, MEMORY_STRATEGIES } from '../../memory/define.types.js';
66
121
  import { defineMemory } from '../../memory/define.js';
67
122
  import { refuseAsRole } from '../../memory/asRoleRefusal.js';
123
+ /**
124
+ * The namespace a corpus lives in unless told otherwise — the same one
125
+ * `indexDocuments` writes to by default. The two defaults are one value
126
+ * on purpose: index with no options, retrieve with no options, and the
127
+ * documents are found.
128
+ */
129
+ export const DEFAULT_CORPUS_IDENTITY = { conversationId: '_global' };
68
130
  /**
69
131
  * Build a RAG context-engineering definition. The returned
70
132
  * `MemoryDefinition` is registered on the Agent via `.rag(definition)`
@@ -72,6 +134,7 @@ import { refuseAsRole } from '../../memory/asRoleRefusal.js';
72
134
  *
73
135
  * @throws when `store` does not implement `search()`. RAG requires a
74
136
  * vector-capable adapter.
137
+ * @throws when `retrieval` is combined with `topK` or `threshold`.
75
138
  */
76
139
  export function defineRAG(opts) {
77
140
  if (!opts.id || opts.id.trim() === '') {
@@ -91,17 +154,41 @@ export function defineRAG(opts) {
91
154
  throw new Error(`defineRAG[${opts.id}]: store must implement search(). ` +
92
155
  'Pass a vector-capable adapter (InMemoryStore, pgvector, Pinecone, ...).');
93
156
  }
157
+ if (opts.retrieval !== undefined) {
158
+ const shorthand = [];
159
+ if (opts.topK !== undefined)
160
+ shorthand.push('`topK`');
161
+ if (opts.threshold !== undefined)
162
+ shorthand.push('`threshold`');
163
+ if (shorthand.length > 0) {
164
+ throw new Error(`defineRAG[${opts.id}]: ${shorthand.join(' and ')} cannot be combined with \`retrieval\` ` +
165
+ '— they are two spellings of the same rule and could disagree. Keep ' +
166
+ `\`retrieval: ${opts.retrieval.name}({ ... })\` and drop ${shorthand.join('/')}.`);
167
+ }
168
+ }
94
169
  return defineMemory({
95
170
  id: opts.id,
96
171
  ...(opts.description !== undefined && { description: opts.description }),
97
172
  type: MEMORY_TYPES.SEMANTIC,
98
- strategy: {
99
- kind: MEMORY_STRATEGIES.TOP_K,
100
- topK: opts.topK ?? 3,
101
- threshold: opts.threshold ?? 0.7,
102
- embedder: opts.embedder,
103
- },
173
+ strategy: opts.retrieval !== undefined
174
+ ? {
175
+ kind: MEMORY_STRATEGIES.TOP_K,
176
+ embedder: opts.embedder,
177
+ retrieval: opts.retrieval,
178
+ ...(opts.embedderId !== undefined && { embedderId: opts.embedderId }),
179
+ }
180
+ : {
181
+ kind: MEMORY_STRATEGIES.TOP_K,
182
+ topK: opts.topK ?? 3,
183
+ threshold: opts.threshold ?? 0.7,
184
+ embedder: opts.embedder,
185
+ ...(opts.embedderId !== undefined && { embedderId: opts.embedderId }),
186
+ },
104
187
  store: opts.store,
188
+ // A corpus is not a conversation log — see the header.
189
+ readOnly: true,
190
+ corpus: opts.corpus ?? DEFAULT_CORPUS_IDENTITY,
191
+ flavor: 'rag',
105
192
  });
106
193
  }
107
194
  //# sourceMappingURL=defineRAG.js.map
@@ -1 +1 @@
1
- {"version":3,"file":"defineRAG.js","sourceRoot":"","sources":["../../../../src/lib/rag/defineRAG.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+DG;AAKH,OAAO,EAAE,YAAY,EAAE,iBAAiB,EAAE,MAAM,8BAA8B,CAAC;AAC/E,OAAO,EAAE,YAAY,EAAE,MAAM,wBAAwB,CAAC;AACtD,OAAO,EAAE,YAAY,EAAE,MAAM,+BAA+B,CAAC;AAkE7D;;;;;;;GAOG;AACH,MAAM,UAAU,SAAS,CAAC,IAAsB;IAC9C,IAAI,CAAC,IAAI,CAAC,EAAE,IAAI,IAAI,CAAC,EAAE,CAAC,IAAI,EAAE,KAAK,EAAE,EAAE,CAAC;QACtC,MAAM,IAAI,KAAK,CAAC,oDAAoD,CAAC,CAAC;IACxE,CAAC;IACD,sEAAsE;IACtE,oEAAoE;IACpE,uDAAuD;IACvD,YAAY,CAAC,IAAI,EAAE,cAAc,IAAI,CAAC,EAAE,IAAI,CAAC,CAAC;IAC9C,IAAI,CAAC,IAAI,CAAC,KAAK,EAAE,CAAC;QAChB,MAAM,IAAI,KAAK,CAAC,aAAa,IAAI,CAAC,EAAE,2BAA2B,CAAC,CAAC;IACnE,CAAC;IACD,IAAI,CAAC,IAAI,CAAC,QAAQ,EAAE,CAAC;QACnB,MAAM,IAAI,KAAK,CAAC,aAAa,IAAI,CAAC,EAAE,8BAA8B,CAAC,CAAC;IACtE,CAAC;IACD,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,MAAM,EAAE,CAAC;QACvB,MAAM,IAAI,KAAK,CACb,aAAa,IAAI,CAAC,EAAE,oCAAoC;YACtD,yEAAyE,CAC5E,CAAC;IACJ,CAAC;IAED,OAAO,YAAY,CAAC;QAClB,EAAE,EAAE,IAAI,CAAC,EAAE;QACX,GAAG,CAAC,IAAI,CAAC,WAAW,KAAK,SAAS,IAAI,EAAE,WAAW,EAAE,IAAI,CAAC,WAAW,EAAE,CAAC;QACxE,IAAI,EAAE,YAAY,CAAC,QAAQ;QAC3B,QAAQ,EAAE;YACR,IAAI,EAAE,iBAAiB,CAAC,KAAK;YAC7B,IAAI,EAAE,IAAI,CAAC,IAAI,IAAI,CAAC;YACpB,SAAS,EAAE,IAAI,CAAC,SAAS,IAAI,GAAG;YAChC,QAAQ,EAAE,IAAI,CAAC,QAAQ;SACxB;QACD,KAAK,EAAE,IAAI,CAAC,KAAK;KAClB,CAAC,CAAC;AACL,CAAC"}
1
+ {"version":3,"file":"defineRAG.js","sourceRoot":"","sources":["../../../../src/lib/rag/defineRAG.ts"],"names":[],"mappings":"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"}
@@ -3,5 +3,5 @@
3
3
  * flavor. ONE factory + ONE seeding helper. Composes over the memory
4
4
  * subsystem (semantic + top-K + strict threshold).
5
5
  */
6
- export { defineRAG, type DefineRAGOptions } from './defineRAG.js';
6
+ export { defineRAG, DEFAULT_CORPUS_IDENTITY, type DefineRAGOptions } from './defineRAG.js';
7
7
  export { indexDocuments, type IndexDocumentsOptions, type RagDocument } from './indexDocuments.js';
@@ -3,6 +3,6 @@
3
3
  * flavor. ONE factory + ONE seeding helper. Composes over the memory
4
4
  * subsystem (semantic + top-K + strict threshold).
5
5
  */
6
- export { defineRAG } from './defineRAG.js';
6
+ export { defineRAG, DEFAULT_CORPUS_IDENTITY } from './defineRAG.js';
7
7
  export { indexDocuments } from './indexDocuments.js';
8
8
  //# sourceMappingURL=index.js.map
@@ -1 +1 @@
1
- {"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../src/lib/rag/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,EAAE,SAAS,EAAyB,MAAM,gBAAgB,CAAC;AAClE,OAAO,EAAE,cAAc,EAAgD,MAAM,qBAAqB,CAAC"}
1
+ {"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../src/lib/rag/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,EAAE,SAAS,EAAE,uBAAuB,EAAyB,MAAM,gBAAgB,CAAC;AAC3F,OAAO,EAAE,cAAc,EAAgD,MAAM,qBAAqB,CAAC"}
@@ -65,14 +65,21 @@ import { MEMORY_TYPES, MEMORY_STRATEGIES, MEMORY_TIMING, } from './define.types.
65
65
  export function defineMemory(options) {
66
66
  validate(options);
67
67
  const pipeline = buildPipeline(options);
68
+ // `readOnly` drops the write half entirely (8.8.0). Not "writes are
69
+ // skipped at runtime" — the subflow is never compiled and never mounted,
70
+ // so a read-only memory has no write stage in its chart, no write commit
71
+ // in its log, and nothing to disable later by accident.
72
+ const write = options.readOnly === true ? undefined : pipeline.write;
68
73
  const definition = {
69
74
  id: options.id,
70
75
  ...(options.description !== undefined && { description: options.description }),
71
76
  type: options.type,
72
77
  read: brandPipeline(pipeline.read),
73
- ...(pipeline.write !== undefined && { write: brandPipeline(pipeline.write) }),
78
+ ...(write !== undefined && { write: brandPipeline(write) }),
74
79
  timing: options.timing ?? MEMORY_TIMING.TURN_START,
75
80
  ...(options.redact !== undefined && { redact: options.redact }),
81
+ ...(options.corpus !== undefined && { corpus: options.corpus }),
82
+ ...(options.flavor !== undefined && { flavor: options.flavor }),
76
83
  ...(options.type === MEMORY_TYPES.CAUSAL &&
77
84
  options.projection !== undefined && {
78
85
  projection: options.projection,
@@ -93,6 +100,26 @@ function validate(options) {
93
100
  throw new Error(`defineMemory[id=${options.id}]: \`store\` is required. ` +
94
101
  'Pass `new InMemoryStore()` for dev/tests, or a backed store for production.');
95
102
  }
103
+ // The shorthand and the spelled-out rule EXCLUDE. Accepting both would
104
+ // mean one of two numbers silently loses, and the recording would name
105
+ // a `k` the run did not use.
106
+ // Read through a structural shape, not the union: the union's arms
107
+ // declare the OTHER spelling as `never`, so intersecting them here
108
+ // would make the very field this check reads unreadable.
109
+ const strategy = options.strategy;
110
+ if (strategy?.retrieval !== undefined) {
111
+ const shorthand = [];
112
+ if (strategy.topK !== undefined)
113
+ shorthand.push('`topK`');
114
+ if (strategy.threshold !== undefined)
115
+ shorthand.push('`threshold`');
116
+ if (shorthand.length > 0) {
117
+ throw new Error(`defineMemory[id=${options.id}]: ${shorthand.join(' and ')} cannot be combined with ` +
118
+ '`retrieval` — they are two spellings of the same rule and could disagree. ' +
119
+ `Keep the strategy (\`retrieval: ${strategy.retrieval.name}({ ... })\`) and drop ` +
120
+ `${shorthand.join('/')}, or drop \`retrieval\`.`);
121
+ }
122
+ }
96
123
  }
97
124
  // ─── Pipeline dispatch ─────────────────────────────────────────────
98
125
  function buildPipeline(options) {
@@ -177,8 +204,11 @@ function buildSemanticPipeline(options) {
177
204
  const config = {
178
205
  store: options.store,
179
206
  embedder: t.embedder,
180
- k: t.topK,
207
+ ...(t.topK !== undefined && { k: t.topK }),
181
208
  ...(t.threshold !== undefined && { minScore: t.threshold }),
209
+ ...(t.embedderId !== undefined && { embedderId: t.embedderId }),
210
+ ...(t.retrieval !== undefined && { retrieval: t.retrieval }),
211
+ ...(options.flavor !== undefined && { flavor: options.flavor }),
182
212
  };
183
213
  return semanticPipeline(config);
184
214
  }
@@ -268,6 +298,12 @@ function buildCausalPipeline(options) {
268
298
  'Pass `new InMemoryStore({ embedder })` for dev/tests, or a vector adapter ' +
269
299
  '(pgvector, Pinecone, Qdrant) for production.');
270
300
  }
301
+ // CAUSAL predates the retrieval seam and reads the shorthand only. A
302
+ // strategy passed here would be accepted and ignored, so it is refused.
303
+ if (s.retrieval !== undefined) {
304
+ throw new Error(`defineMemory[${options.id}]: CAUSAL type does not read \`retrieval\` — snapshot recall ` +
305
+ 'matches a stored query vector, not a document pool. Use `topK` + `threshold`.');
306
+ }
271
307
  const config = {
272
308
  store: options.store,
273
309
  embedder: s.embedder,
@@ -1 +1 @@
1
- {"version":3,"file":"define.js","sourceRoot":"","sources":["../../../src/memory/define.ts"],"names":[],"mappings":"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"}
1
+ {"version":3,"file":"define.js","sourceRoot":"","sources":["../../../src/memory/define.ts"],"names":[],"mappings":"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"}