agent-recall-core 3.4.50 → 3.5.2

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 (152) hide show
  1. package/README.md +559 -330
  2. package/dist/embeddings/config.d.ts.map +1 -1
  3. package/dist/embeddings/config.js +17 -4
  4. package/dist/embeddings/config.js.map +1 -1
  5. package/dist/helpers/alignment-patterns.d.ts +46 -0
  6. package/dist/helpers/alignment-patterns.d.ts.map +1 -1
  7. package/dist/helpers/alignment-patterns.js +103 -2
  8. package/dist/helpers/alignment-patterns.js.map +1 -1
  9. package/dist/helpers/journal-files.d.ts +12 -6
  10. package/dist/helpers/journal-files.d.ts.map +1 -1
  11. package/dist/helpers/journal-files.js +13 -7
  12. package/dist/helpers/journal-files.js.map +1 -1
  13. package/dist/helpers/transcript-project.d.ts +69 -0
  14. package/dist/helpers/transcript-project.d.ts.map +1 -0
  15. package/dist/helpers/transcript-project.js +212 -0
  16. package/dist/helpers/transcript-project.js.map +1 -0
  17. package/dist/index.d.ts +28 -7
  18. package/dist/index.d.ts.map +1 -1
  19. package/dist/index.js +62 -6
  20. package/dist/index.js.map +1 -1
  21. package/dist/palace/awareness.d.ts +6 -0
  22. package/dist/palace/awareness.d.ts.map +1 -1
  23. package/dist/palace/awareness.js +10 -4
  24. package/dist/palace/awareness.js.map +1 -1
  25. package/dist/prompts/consolidation-prompt.js +14 -14
  26. package/dist/retrieval/activation.d.ts +202 -0
  27. package/dist/retrieval/activation.d.ts.map +1 -0
  28. package/dist/retrieval/activation.js +313 -0
  29. package/dist/retrieval/activation.js.map +1 -0
  30. package/dist/retrieval/candidates.d.ts +17 -0
  31. package/dist/retrieval/candidates.d.ts.map +1 -1
  32. package/dist/retrieval/candidates.js +4 -2
  33. package/dist/retrieval/candidates.js.map +1 -1
  34. package/dist/retrieval/contradiction.d.ts +42 -0
  35. package/dist/retrieval/contradiction.d.ts.map +1 -1
  36. package/dist/retrieval/contradiction.js +126 -7
  37. package/dist/retrieval/contradiction.js.map +1 -1
  38. package/dist/retrieval/lexical-index.d.ts +150 -0
  39. package/dist/retrieval/lexical-index.d.ts.map +1 -0
  40. package/dist/retrieval/lexical-index.js +514 -0
  41. package/dist/retrieval/lexical-index.js.map +1 -0
  42. package/dist/retrieval/query-memory.d.ts +17 -7
  43. package/dist/retrieval/query-memory.d.ts.map +1 -1
  44. package/dist/retrieval/query-memory.js +274 -68
  45. package/dist/retrieval/query-memory.js.map +1 -1
  46. package/dist/storage/classification.d.ts.map +1 -1
  47. package/dist/storage/classification.js +4 -1
  48. package/dist/storage/classification.js.map +1 -1
  49. package/dist/storage/content-guard.d.ts +26 -0
  50. package/dist/storage/content-guard.d.ts.map +1 -1
  51. package/dist/storage/content-guard.js +450 -48
  52. package/dist/storage/content-guard.js.map +1 -1
  53. package/dist/storage/corrections.d.ts +140 -2
  54. package/dist/storage/corrections.d.ts.map +1 -1
  55. package/dist/storage/corrections.js +144 -70
  56. package/dist/storage/corrections.js.map +1 -1
  57. package/dist/storage/cwd-allowlist.d.ts +28 -2
  58. package/dist/storage/cwd-allowlist.d.ts.map +1 -1
  59. package/dist/storage/cwd-allowlist.js +61 -13
  60. package/dist/storage/cwd-allowlist.js.map +1 -1
  61. package/dist/storage/filelock.d.ts +26 -8
  62. package/dist/storage/filelock.d.ts.map +1 -1
  63. package/dist/storage/filelock.js +202 -26
  64. package/dist/storage/filelock.js.map +1 -1
  65. package/dist/storage/fs-utils.d.ts +51 -0
  66. package/dist/storage/fs-utils.d.ts.map +1 -1
  67. package/dist/storage/fs-utils.js +123 -2
  68. package/dist/storage/fs-utils.js.map +1 -1
  69. package/dist/storage/heed-tiers.d.ts +206 -0
  70. package/dist/storage/heed-tiers.d.ts.map +1 -0
  71. package/dist/storage/heed-tiers.js +318 -0
  72. package/dist/storage/heed-tiers.js.map +1 -0
  73. package/dist/storage/memory-protocol.js +55 -55
  74. package/dist/storage/paths.d.ts.map +1 -1
  75. package/dist/storage/paths.js +7 -2
  76. package/dist/storage/paths.js.map +1 -1
  77. package/dist/storage/project.d.ts.map +1 -1
  78. package/dist/storage/project.js +9 -2
  79. package/dist/storage/project.js.map +1 -1
  80. package/dist/storage/store-manifest.js +57 -57
  81. package/dist/supabase/embedding.d.ts.map +1 -1
  82. package/dist/supabase/embedding.js +7 -0
  83. package/dist/supabase/embedding.js.map +1 -1
  84. package/dist/supabase/sync.d.ts +1 -1
  85. package/dist/supabase/sync.d.ts.map +1 -1
  86. package/dist/supabase/sync.js +88 -28
  87. package/dist/supabase/sync.js.map +1 -1
  88. package/dist/tools-logic/association.d.ts +260 -0
  89. package/dist/tools-logic/association.d.ts.map +1 -0
  90. package/dist/tools-logic/association.js +502 -0
  91. package/dist/tools-logic/association.js.map +1 -0
  92. package/dist/tools-logic/bootstrap.d.ts.map +1 -1
  93. package/dist/tools-logic/bootstrap.js +4 -2
  94. package/dist/tools-logic/bootstrap.js.map +1 -1
  95. package/dist/tools-logic/check-action.d.ts.map +1 -1
  96. package/dist/tools-logic/check-action.js +14 -0
  97. package/dist/tools-logic/check-action.js.map +1 -1
  98. package/dist/tools-logic/check.d.ts +7 -0
  99. package/dist/tools-logic/check.d.ts.map +1 -1
  100. package/dist/tools-logic/check.js +54 -44
  101. package/dist/tools-logic/check.js.map +1 -1
  102. package/dist/tools-logic/dream-admission.js +29 -29
  103. package/dist/tools-logic/implicit-harvest.d.ts +196 -0
  104. package/dist/tools-logic/implicit-harvest.d.ts.map +1 -0
  105. package/dist/tools-logic/implicit-harvest.js +675 -0
  106. package/dist/tools-logic/implicit-harvest.js.map +1 -0
  107. package/dist/tools-logic/insight-promotion.d.ts.map +1 -1
  108. package/dist/tools-logic/insight-promotion.js +53 -1
  109. package/dist/tools-logic/insight-promotion.js.map +1 -1
  110. package/dist/tools-logic/recall-backend.d.ts.map +1 -1
  111. package/dist/tools-logic/recall-backend.js +3 -1
  112. package/dist/tools-logic/recall-backend.js.map +1 -1
  113. package/dist/tools-logic/retier.d.ts +274 -0
  114. package/dist/tools-logic/retier.d.ts.map +1 -0
  115. package/dist/tools-logic/retier.js +511 -0
  116. package/dist/tools-logic/retier.js.map +1 -0
  117. package/dist/tools-logic/session-end.d.ts +35 -0
  118. package/dist/tools-logic/session-end.d.ts.map +1 -1
  119. package/dist/tools-logic/session-end.js +26 -7
  120. package/dist/tools-logic/session-end.js.map +1 -1
  121. package/dist/tools-logic/session-start.d.ts +11 -0
  122. package/dist/tools-logic/session-start.d.ts.map +1 -1
  123. package/dist/tools-logic/session-start.js +34 -4
  124. package/dist/tools-logic/session-start.js.map +1 -1
  125. package/dist/tools-logic/smart-recall.d.ts +63 -0
  126. package/dist/tools-logic/smart-recall.d.ts.map +1 -1
  127. package/dist/tools-logic/smart-recall.js +213 -31
  128. package/dist/tools-logic/smart-recall.js.map +1 -1
  129. package/dist/tools-logic/smart-remember-vector.d.ts +3 -1
  130. package/dist/tools-logic/smart-remember-vector.d.ts.map +1 -1
  131. package/dist/tools-logic/smart-remember-vector.js +3 -1
  132. package/dist/tools-logic/smart-remember-vector.js.map +1 -1
  133. package/dist/tools-logic/smart-remember.d.ts.map +1 -1
  134. package/dist/tools-logic/smart-remember.js +6 -2
  135. package/dist/tools-logic/smart-remember.js.map +1 -1
  136. package/dist/tools-logic/transcript-audit.d.ts +128 -0
  137. package/dist/tools-logic/transcript-audit.d.ts.map +1 -0
  138. package/dist/tools-logic/transcript-audit.js +428 -0
  139. package/dist/tools-logic/transcript-audit.js.map +1 -0
  140. package/dist/types.d.ts +17 -2
  141. package/dist/types.d.ts.map +1 -1
  142. package/dist/types.js +31 -3
  143. package/dist/types.js.map +1 -1
  144. package/dist/vector/embedding.d.ts +20 -1
  145. package/dist/vector/embedding.d.ts.map +1 -1
  146. package/dist/vector/embedding.js +27 -1
  147. package/dist/vector/embedding.js.map +1 -1
  148. package/dist/vector/local-vector-backend.d.ts +4 -1
  149. package/dist/vector/local-vector-backend.d.ts.map +1 -1
  150. package/dist/vector/local-vector-backend.js +7 -3
  151. package/dist/vector/local-vector-backend.js.map +1 -1
  152. package/package.json +59 -59
package/dist/types.js CHANGED
@@ -3,31 +3,59 @@
3
3
  */
4
4
  import * as path from "node:path";
5
5
  import * as os from "node:os";
6
+ import { AsyncLocalStorage } from "node:async_hooks";
6
7
  // ---------------------------------------------------------------------------
7
8
  // Constants
8
9
  // ---------------------------------------------------------------------------
9
- export const VERSION = "3.4.50";
10
+ export const VERSION = "3.5.2";
10
11
  // ---------------------------------------------------------------------------
11
12
  // Root directory (configurable at runtime for SDK usage)
12
13
  // ---------------------------------------------------------------------------
13
14
  let _root = null;
15
+ /**
16
+ * Per-call root scope (TOW2-324). withRoot() runs a (possibly async)
17
+ * function with an explicit root that takes precedence over the
18
+ * process-global `_root` for the duration of that call chain only.
19
+ * AsyncLocalStorage propagates the scope across awaits/promises/timers
20
+ * created inside the callback, and restores the outer context when the
21
+ * callback returns, throws, or rejects — a failed call can never leak
22
+ * its root onto subsequent unscoped calls.
23
+ */
24
+ const _rootScope = new AsyncLocalStorage();
14
25
  /**
15
26
  * Set the storage root directory. This is process-global state —
16
27
  * only one root is active at a time. Call before any other operations.
17
28
  * Use resetRoot() to revert to environment/default resolution.
29
+ * For per-instance/per-call scoping (e.g. multiple SDK instances in one
30
+ * process), use withRoot() instead.
18
31
  */
19
32
  export function setRoot(root) {
20
33
  _root = root;
21
34
  }
22
35
  /**
23
36
  * Clear the explicitly-set root, reverting to AGENT_RECALL_ROOT env var
24
- * or the default ~/.agent-recall.
37
+ * or the default ~/.agent-recall. Does not affect active withRoot() scopes.
25
38
  */
26
39
  export function resetRoot() {
27
40
  _root = null;
28
41
  }
42
+ /**
43
+ * Run `fn` with `root` as the effective storage root for the duration of
44
+ * the call (including its entire async continuation chain). Concurrent
45
+ * scopes with different roots do not interfere: each interleaved call chain
46
+ * sees its own root. Code outside any scope (CLI, MCP server) keeps
47
+ * resolving via setRoot()/env/default exactly as before.
48
+ *
49
+ * Note: the scope propagates through promises, awaits, timers, and
50
+ * callbacks REGISTERED inside `fn`. It does not follow manually detached
51
+ * continuations (e.g. an EventEmitter whose listeners were registered
52
+ * outside the scope) — bind those explicitly if ever needed.
53
+ */
54
+ export function withRoot(root, fn) {
55
+ return _rootScope.run(root, fn);
56
+ }
29
57
  export function getRoot() {
30
- return _root ?? process.env.AGENT_RECALL_ROOT ?? path.join(os.homedir(), ".agent-recall");
58
+ return _rootScope.getStore() ?? _root ?? process.env.AGENT_RECALL_ROOT ?? path.join(os.homedir(), ".agent-recall");
31
59
  }
32
60
  export function getLegacyRoot() {
33
61
  return path.join(os.homedir(), ".claude", "projects");
package/dist/types.js.map CHANGED
@@ -1 +1 @@
1
- {"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,IAAI,MAAM,WAAW,CAAC;AAClC,OAAO,KAAK,EAAE,MAAM,SAAS,CAAC;AAE9B,8EAA8E;AAC9E,YAAY;AACZ,8EAA8E;AAE9E,MAAM,CAAC,MAAM,OAAO,GAAG,QAAQ,CAAC;AAEhC,8EAA8E;AAC9E,yDAAyD;AACzD,8EAA8E;AAE9E,IAAI,KAAK,GAAkB,IAAI,CAAC;AAEhC;;;;GAIG;AACH,MAAM,UAAU,OAAO,CAAC,IAAY;IAClC,KAAK,GAAG,IAAI,CAAC;AACf,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,SAAS;IACvB,KAAK,GAAG,IAAI,CAAC;AACf,CAAC;AAED,MAAM,UAAU,OAAO;IACrB,OAAO,KAAK,IAAI,OAAO,CAAC,GAAG,CAAC,iBAAiB,IAAI,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,OAAO,EAAE,EAAE,eAAe,CAAC,CAAC;AAC5F,CAAC;AAED,MAAM,UAAU,aAAa;IAC3B,OAAO,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,OAAO,EAAE,EAAE,SAAS,EAAE,UAAU,CAAC,CAAC;AACxD,CAAC;AAED,MAAM,CAAC,MAAM,eAAe,GAA2B;IACrD,KAAK,EAAE,UAAU;IACjB,EAAE,EAAE,YAAY;IAChB,SAAS,EAAE,cAAc;IACzB,MAAM,EAAE,WAAW;IACnB,QAAQ,EAAE,aAAa;IACvB,IAAI,EAAE,SAAS;IACf,SAAS,EAAE,cAAc;IACzB,UAAU,EAAE,eAAe;IAC3B,KAAK,EAAE,kBAAkB;IACzB,YAAY,EAAE,iBAAiB;CAChC,CAAC;AAEF,MAAM,CAAC,MAAM,oBAAoB,GAAG;IAClC,EAAE,IAAI,EAAE,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,WAAW,EAAE,+CAA+C,EAAE,IAAI,EAAE,CAAC,UAAU,CAAC,EAAE;IAClH,EAAE,IAAI,EAAE,cAAc,EAAE,IAAI,EAAE,cAAc,EAAE,WAAW,EAAE,2CAA2C,EAAE,IAAI,EAAE,CAAC,WAAW,CAAC,EAAE;IAC7H,EAAE,IAAI,EAAE,WAAW,EAAE,IAAI,EAAE,WAAW,EAAE,WAAW,EAAE,kIAAkI,EAAE,IAAI,EAAE,CAAC,WAAW,CAAC,EAAE;IAC9M,EAAE,IAAI,EAAE,UAAU,EAAE,IAAI,EAAE,UAAU,EAAE,WAAW,EAAE,+BAA+B,EAAE,IAAI,EAAE,CAAC,QAAQ,CAAC,EAAE;IACtG,EAAE,IAAI,EAAE,WAAW,EAAE,IAAI,EAAE,WAAW,EAAE,WAAW,EAAE,mDAAmD,EAAE,IAAI,EAAE,CAAC,eAAe,CAAC,EAAE;IACnI,EAAE,IAAI,EAAE,WAAW,EAAE,IAAI,EAAE,WAAW,EAAE,WAAW,EAAE,6BAA6B,EAAE,IAAI,EAAE,CAAC,UAAU,CAAC,EAAE;CAChG,CAAC"}
1
+ {"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,IAAI,MAAM,WAAW,CAAC;AAClC,OAAO,KAAK,EAAE,MAAM,SAAS,CAAC;AAC9B,OAAO,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AAErD,8EAA8E;AAC9E,YAAY;AACZ,8EAA8E;AAE9E,MAAM,CAAC,MAAM,OAAO,GAAG,OAAO,CAAC;AAE/B,8EAA8E;AAC9E,yDAAyD;AACzD,8EAA8E;AAE9E,IAAI,KAAK,GAAkB,IAAI,CAAC;AAEhC;;;;;;;;GAQG;AACH,MAAM,UAAU,GAAG,IAAI,iBAAiB,EAAU,CAAC;AAEnD;;;;;;GAMG;AACH,MAAM,UAAU,OAAO,CAAC,IAAY;IAClC,KAAK,GAAG,IAAI,CAAC;AACf,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,SAAS;IACvB,KAAK,GAAG,IAAI,CAAC;AACf,CAAC;AAED;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,QAAQ,CAAI,IAAY,EAAE,EAAW;IACnD,OAAO,UAAU,CAAC,GAAG,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC;AAClC,CAAC;AAED,MAAM,UAAU,OAAO;IACrB,OAAO,UAAU,CAAC,QAAQ,EAAE,IAAI,KAAK,IAAI,OAAO,CAAC,GAAG,CAAC,iBAAiB,IAAI,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,OAAO,EAAE,EAAE,eAAe,CAAC,CAAC;AACrH,CAAC;AAED,MAAM,UAAU,aAAa;IAC3B,OAAO,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,OAAO,EAAE,EAAE,SAAS,EAAE,UAAU,CAAC,CAAC;AACxD,CAAC;AAED,MAAM,CAAC,MAAM,eAAe,GAA2B;IACrD,KAAK,EAAE,UAAU;IACjB,EAAE,EAAE,YAAY;IAChB,SAAS,EAAE,cAAc;IACzB,MAAM,EAAE,WAAW;IACnB,QAAQ,EAAE,aAAa;IACvB,IAAI,EAAE,SAAS;IACf,SAAS,EAAE,cAAc;IACzB,UAAU,EAAE,eAAe;IAC3B,KAAK,EAAE,kBAAkB;IACzB,YAAY,EAAE,iBAAiB;CAChC,CAAC;AAEF,MAAM,CAAC,MAAM,oBAAoB,GAAG;IAClC,EAAE,IAAI,EAAE,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,WAAW,EAAE,+CAA+C,EAAE,IAAI,EAAE,CAAC,UAAU,CAAC,EAAE;IAClH,EAAE,IAAI,EAAE,cAAc,EAAE,IAAI,EAAE,cAAc,EAAE,WAAW,EAAE,2CAA2C,EAAE,IAAI,EAAE,CAAC,WAAW,CAAC,EAAE;IAC7H,EAAE,IAAI,EAAE,WAAW,EAAE,IAAI,EAAE,WAAW,EAAE,WAAW,EAAE,kIAAkI,EAAE,IAAI,EAAE,CAAC,WAAW,CAAC,EAAE;IAC9M,EAAE,IAAI,EAAE,UAAU,EAAE,IAAI,EAAE,UAAU,EAAE,WAAW,EAAE,+BAA+B,EAAE,IAAI,EAAE,CAAC,QAAQ,CAAC,EAAE;IACtG,EAAE,IAAI,EAAE,WAAW,EAAE,IAAI,EAAE,WAAW,EAAE,WAAW,EAAE,mDAAmD,EAAE,IAAI,EAAE,CAAC,eAAe,CAAC,EAAE;IACnI,EAAE,IAAI,EAAE,WAAW,EAAE,IAAI,EAAE,WAAW,EAAE,WAAW,EAAE,6BAA6B,EAAE,IAAI,EAAE,CAAC,UAAU,CAAC,EAAE;CAChG,CAAC"}
@@ -18,10 +18,29 @@
18
18
  * OPT-IN via AGENT_RECALL_EMBEDDINGS). THIS file remains what it was: the
19
19
  * dormant CLOUD (OpenAI) seam, still not user-facing, still not on any
20
20
  * default path — the sanctioned local path does not use it.
21
+ *
22
+ * EGRESS GATE (fix 3.5.2, 2026-10-16, rigorous-eval §5 finding 1): an AMBIENT
23
+ * OPENAI_API_KEY — set for any other tool on the machine — used to be enough
24
+ * to select this seam and silently send recall queries and remembered content
25
+ * to api.openai.com. Cloud embeddings now additionally require the EXPLICIT
26
+ * opt-in env AGENT_RECALL_CLOUD_EMBEDDINGS=1 (or "true"). The key alone sends
27
+ * nothing. Not to be confused with AGENT_RECALL_EMBEDDINGS, which gates the
28
+ * LOCAL ONNX leg (no network). The Supabase embedding providers
29
+ * (supabase/embedding.ts) are unaffected: they never read OPENAI_API_KEY and
30
+ * are reachable only via an explicitly configured embedding_api_key.
31
+ */
32
+ /**
33
+ * Explicit opt-in gate for CLOUD (OpenAI) embeddings. True only when BOTH
34
+ * AGENT_RECALL_CLOUD_EMBEDDINGS=1|true AND OPENAI_API_KEY are set. Every
35
+ * path that could send text to api.openai.com on the ambient key must check
36
+ * this (embed() below checks it itself, as the egress chokepoint).
21
37
  */
38
+ export declare function cloudEmbeddingsEnabled(): boolean;
22
39
  /**
23
40
  * Embed a piece of text using OpenAI text-embedding-3-small (1536 dims).
24
- * Returns null if OPENAI_API_KEY is not set or if the request fails or times out.
41
+ * Returns null unless cloud embeddings are explicitly opted in
42
+ * (AGENT_RECALL_CLOUD_EMBEDDINGS=1 AND OPENAI_API_KEY), or if the request
43
+ * fails or times out.
25
44
  * Never throws — callers must handle null and fall back to keyword search.
26
45
  */
27
46
  export declare function embed(text: string): Promise<number[] | null>;
@@ -1 +1 @@
1
- {"version":3,"file":"embedding.d.ts","sourceRoot":"","sources":["../../src/vector/embedding.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAKH;;;;GAIG;AACH,wBAAsB,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,GAAG,IAAI,CAAC,CAuBlE"}
1
+ {"version":3,"file":"embedding.d.ts","sourceRoot":"","sources":["../../src/vector/embedding.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AAKH;;;;;GAKG;AACH,wBAAgB,sBAAsB,IAAI,OAAO,CAIhD;AAED;;;;;;GAMG;AACH,wBAAsB,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,GAAG,IAAI,CAAC,CAwBlE"}
@@ -18,15 +18,41 @@
18
18
  * OPT-IN via AGENT_RECALL_EMBEDDINGS). THIS file remains what it was: the
19
19
  * dormant CLOUD (OpenAI) seam, still not user-facing, still not on any
20
20
  * default path — the sanctioned local path does not use it.
21
+ *
22
+ * EGRESS GATE (fix 3.5.2, 2026-10-16, rigorous-eval §5 finding 1): an AMBIENT
23
+ * OPENAI_API_KEY — set for any other tool on the machine — used to be enough
24
+ * to select this seam and silently send recall queries and remembered content
25
+ * to api.openai.com. Cloud embeddings now additionally require the EXPLICIT
26
+ * opt-in env AGENT_RECALL_CLOUD_EMBEDDINGS=1 (or "true"). The key alone sends
27
+ * nothing. Not to be confused with AGENT_RECALL_EMBEDDINGS, which gates the
28
+ * LOCAL ONNX leg (no network). The Supabase embedding providers
29
+ * (supabase/embedding.ts) are unaffected: they never read OPENAI_API_KEY and
30
+ * are reachable only via an explicitly configured embedding_api_key.
21
31
  */
22
32
  /** Timeout in ms for the embedding fetch. Not a user-facing env flag — internal seam only. */
23
33
  const EMBED_TIMEOUT_MS = parseInt(process.env.AGENT_RECALL_EMBED_TIMEOUT_MS ?? "2000", 10);
34
+ /**
35
+ * Explicit opt-in gate for CLOUD (OpenAI) embeddings. True only when BOTH
36
+ * AGENT_RECALL_CLOUD_EMBEDDINGS=1|true AND OPENAI_API_KEY are set. Every
37
+ * path that could send text to api.openai.com on the ambient key must check
38
+ * this (embed() below checks it itself, as the egress chokepoint).
39
+ */
40
+ export function cloudEmbeddingsEnabled() {
41
+ const flag = process.env.AGENT_RECALL_CLOUD_EMBEDDINGS;
42
+ if (flag !== "1" && flag !== "true")
43
+ return false;
44
+ return !!process.env.OPENAI_API_KEY;
45
+ }
24
46
  /**
25
47
  * Embed a piece of text using OpenAI text-embedding-3-small (1536 dims).
26
- * Returns null if OPENAI_API_KEY is not set or if the request fails or times out.
48
+ * Returns null unless cloud embeddings are explicitly opted in
49
+ * (AGENT_RECALL_CLOUD_EMBEDDINGS=1 AND OPENAI_API_KEY), or if the request
50
+ * fails or times out.
27
51
  * Never throws — callers must handle null and fall back to keyword search.
28
52
  */
29
53
  export async function embed(text) {
54
+ if (!cloudEmbeddingsEnabled())
55
+ return null;
30
56
  const apiKey = process.env.OPENAI_API_KEY;
31
57
  if (!apiKey)
32
58
  return null;
@@ -1 +1 @@
1
- {"version":3,"file":"embedding.js","sourceRoot":"","sources":["../../src/vector/embedding.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,8FAA8F;AAC9F,MAAM,gBAAgB,GAAG,QAAQ,CAAC,OAAO,CAAC,GAAG,CAAC,6BAA6B,IAAI,MAAM,EAAE,EAAE,CAAC,CAAC;AAE3F;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,KAAK,CAAC,IAAY;IACtC,MAAM,MAAM,GAAG,OAAO,CAAC,GAAG,CAAC,cAAc,CAAC;IAC1C,IAAI,CAAC,MAAM;QAAE,OAAO,IAAI,CAAC;IAEzB,IAAI,CAAC;QACH,MAAM,GAAG,GAAG,MAAM,KAAK,CAAC,sCAAsC,EAAE;YAC9D,MAAM,EAAE,MAAM;YACd,OAAO,EAAE;gBACP,eAAe,EAAE,UAAU,MAAM,EAAE;gBACnC,cAAc,EAAE,kBAAkB;aACnC;YACD,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,EAAE,KAAK,EAAE,wBAAwB,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC;YACtE,MAAM,EAAE,WAAW,CAAC,OAAO,CAAC,gBAAgB,CAAC;SAC9C,CAAC,CAAC;QAEH,IAAI,CAAC,GAAG,CAAC,EAAE;YAAE,OAAO,IAAI,CAAC;QAEzB,MAAM,IAAI,GAAG,MAAM,GAAG,CAAC,IAAI,EAA8C,CAAC;QAC1E,OAAO,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,SAAS,IAAI,IAAI,CAAC;IACzC,CAAC;IAAC,MAAM,CAAC;QACP,uFAAuF;QACvF,OAAO,IAAI,CAAC;IACd,CAAC;AACH,CAAC"}
1
+ {"version":3,"file":"embedding.js","sourceRoot":"","sources":["../../src/vector/embedding.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AAEH,8FAA8F;AAC9F,MAAM,gBAAgB,GAAG,QAAQ,CAAC,OAAO,CAAC,GAAG,CAAC,6BAA6B,IAAI,MAAM,EAAE,EAAE,CAAC,CAAC;AAE3F;;;;;GAKG;AACH,MAAM,UAAU,sBAAsB;IACpC,MAAM,IAAI,GAAG,OAAO,CAAC,GAAG,CAAC,6BAA6B,CAAC;IACvD,IAAI,IAAI,KAAK,GAAG,IAAI,IAAI,KAAK,MAAM;QAAE,OAAO,KAAK,CAAC;IAClD,OAAO,CAAC,CAAC,OAAO,CAAC,GAAG,CAAC,cAAc,CAAC;AACtC,CAAC;AAED;;;;;;GAMG;AACH,MAAM,CAAC,KAAK,UAAU,KAAK,CAAC,IAAY;IACtC,IAAI,CAAC,sBAAsB,EAAE;QAAE,OAAO,IAAI,CAAC;IAC3C,MAAM,MAAM,GAAG,OAAO,CAAC,GAAG,CAAC,cAAc,CAAC;IAC1C,IAAI,CAAC,MAAM;QAAE,OAAO,IAAI,CAAC;IAEzB,IAAI,CAAC;QACH,MAAM,GAAG,GAAG,MAAM,KAAK,CAAC,sCAAsC,EAAE;YAC9D,MAAM,EAAE,MAAM;YACd,OAAO,EAAE;gBACP,eAAe,EAAE,UAAU,MAAM,EAAE;gBACnC,cAAc,EAAE,kBAAkB;aACnC;YACD,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,EAAE,KAAK,EAAE,wBAAwB,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC;YACtE,MAAM,EAAE,WAAW,CAAC,OAAO,CAAC,gBAAgB,CAAC;SAC9C,CAAC,CAAC;QAEH,IAAI,CAAC,GAAG,CAAC,EAAE;YAAE,OAAO,IAAI,CAAC;QAEzB,MAAM,IAAI,GAAG,MAAM,GAAG,CAAC,IAAI,EAA8C,CAAC;QAC1E,OAAO,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,SAAS,IAAI,IAAI,CAAC;IACzC,CAAC;IAAC,MAAM,CAAC;QACP,uFAAuF;QACvF,OAAO,IAAI,CAAC;IACd,CAAC;AACH,CAAC"}
@@ -1,7 +1,10 @@
1
1
  /**
2
2
  * LocalVectorRecallBackend — semantic recall using local vectra index.
3
3
  *
4
- * Selected when OPENAI_API_KEY is set and no Supabase config is present.
4
+ * Selected only on EXPLICIT opt-in — AGENT_RECALL_CLOUD_EMBEDDINGS=1 AND
5
+ * OPENAI_API_KEY — and no Supabase config present. An ambient OPENAI_API_KEY
6
+ * alone must never select this backend (egress gate, fix 3.5.2 — see
7
+ * vector/embedding.ts).
5
8
  * Falls back to an empty result set (not an error) when embedding fails or
6
9
  * the index has no data yet — the caller (smartRecall) will then use
7
10
  * keyword search as a safety net.
@@ -1 +1 @@
1
- {"version":3,"file":"local-vector-backend.d.ts","sourceRoot":"","sources":["../../src/vector/local-vector-backend.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAIH,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,gCAAgC,CAAC;AAG5E,qBAAa,wBAAwB;IACnC,SAAS,IAAI,OAAO;IAId,MAAM,CACV,KAAK,EAAE,MAAM,EACb,OAAO,EAAE,MAAM,GAAG,SAAS,EAC3B,KAAK,EAAE,MAAM,GACZ,OAAO,CAAC,qBAAqB,EAAE,CAAC;CAyBpC"}
1
+ {"version":3,"file":"local-vector-backend.d.ts","sourceRoot":"","sources":["../../src/vector/local-vector-backend.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAIH,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,gCAAgC,CAAC;AAG5E,qBAAa,wBAAwB;IACnC,SAAS,IAAI,OAAO;IAKd,MAAM,CACV,KAAK,EAAE,MAAM,EACb,OAAO,EAAE,MAAM,GAAG,SAAS,EAC3B,KAAK,EAAE,MAAM,GACZ,OAAO,CAAC,qBAAqB,EAAE,CAAC;CAyBpC"}
@@ -1,17 +1,21 @@
1
1
  /**
2
2
  * LocalVectorRecallBackend — semantic recall using local vectra index.
3
3
  *
4
- * Selected when OPENAI_API_KEY is set and no Supabase config is present.
4
+ * Selected only on EXPLICIT opt-in — AGENT_RECALL_CLOUD_EMBEDDINGS=1 AND
5
+ * OPENAI_API_KEY — and no Supabase config present. An ambient OPENAI_API_KEY
6
+ * alone must never select this backend (egress gate, fix 3.5.2 — see
7
+ * vector/embedding.ts).
5
8
  * Falls back to an empty result set (not an error) when embedding fails or
6
9
  * the index has no data yet — the caller (smartRecall) will then use
7
10
  * keyword search as a safety net.
8
11
  */
9
- import { embed } from "./embedding.js";
12
+ import { embed, cloudEmbeddingsEnabled } from "./embedding.js";
10
13
  import { queryVector } from "./local-vector-store.js";
11
14
  import { calibratedConfidence } from "../tools-logic/confidence.js";
12
15
  export class LocalVectorRecallBackend {
13
16
  available() {
14
- return !!process.env.OPENAI_API_KEY;
17
+ // Explicit opt-in only — the ambient key alone selects nothing.
18
+ return cloudEmbeddingsEnabled();
15
19
  }
16
20
  async search(query, project, limit) {
17
21
  if (!project)
@@ -1 +1 @@
1
- {"version":3,"file":"local-vector-backend.js","sourceRoot":"","sources":["../../src/vector/local-vector-backend.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,KAAK,EAAE,MAAM,gBAAgB,CAAC;AACvC,OAAO,EAAE,WAAW,EAAE,MAAM,yBAAyB,CAAC;AAEtD,OAAO,EAAE,oBAAoB,EAAE,MAAM,8BAA8B,CAAC;AAEpE,MAAM,OAAO,wBAAwB;IACnC,SAAS;QACP,OAAO,CAAC,CAAC,OAAO,CAAC,GAAG,CAAC,cAAc,CAAC;IACtC,CAAC;IAED,KAAK,CAAC,MAAM,CACV,KAAa,EACb,OAA2B,EAC3B,KAAa;QAEb,IAAI,CAAC,OAAO;YAAE,OAAO,EAAE,CAAC;QAExB,MAAM,SAAS,GAAG,MAAM,KAAK,CAAC,KAAK,CAAC,CAAC;QACrC,IAAI,CAAC,SAAS,EAAE,CAAC;YACf,iFAAiF;YACjF,OAAO,EAAE,CAAC;QACZ,CAAC;QAED,MAAM,IAAI,GAAG,MAAM,WAAW,CAAC,OAAO,EAAE,SAAS,EAAE,KAAK,CAAC,CAAC;QAE1D,OAAO,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE;YACpB,4DAA4D;YAC5D,MAAM,CAAC,GAAG,oBAAoB,CAAC,CAAC,CAAC,KAAK,EAAE,QAAQ,CAAC,CAAC;YAClD,OAAO;gBACL,EAAE,EAAE,CAAC,CAAC,EAAE;gBACR,MAAM,EAAE,CAAC,CAAC,MAAM;gBAChB,KAAK,EAAE,CAAC,CAAC,KAAK;gBACd,OAAO,EAAE,CAAC,CAAC,OAAO;gBAClB,KAAK,EAAE,CAAC,CAAC,KAAK;gBACd,UAAU,EAAE,CAAC,CAAC,KAAK;gBACnB,UAAU,EAAE,CAAC,CAAC,UAAU;aACzB,CAAC;QACJ,CAAC,CAAC,CAAC;IACL,CAAC;CACF"}
1
+ {"version":3,"file":"local-vector-backend.js","sourceRoot":"","sources":["../../src/vector/local-vector-backend.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,EAAE,KAAK,EAAE,sBAAsB,EAAE,MAAM,gBAAgB,CAAC;AAC/D,OAAO,EAAE,WAAW,EAAE,MAAM,yBAAyB,CAAC;AAEtD,OAAO,EAAE,oBAAoB,EAAE,MAAM,8BAA8B,CAAC;AAEpE,MAAM,OAAO,wBAAwB;IACnC,SAAS;QACP,gEAAgE;QAChE,OAAO,sBAAsB,EAAE,CAAC;IAClC,CAAC;IAED,KAAK,CAAC,MAAM,CACV,KAAa,EACb,OAA2B,EAC3B,KAAa;QAEb,IAAI,CAAC,OAAO;YAAE,OAAO,EAAE,CAAC;QAExB,MAAM,SAAS,GAAG,MAAM,KAAK,CAAC,KAAK,CAAC,CAAC;QACrC,IAAI,CAAC,SAAS,EAAE,CAAC;YACf,iFAAiF;YACjF,OAAO,EAAE,CAAC;QACZ,CAAC;QAED,MAAM,IAAI,GAAG,MAAM,WAAW,CAAC,OAAO,EAAE,SAAS,EAAE,KAAK,CAAC,CAAC;QAE1D,OAAO,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE;YACpB,4DAA4D;YAC5D,MAAM,CAAC,GAAG,oBAAoB,CAAC,CAAC,CAAC,KAAK,EAAE,QAAQ,CAAC,CAAC;YAClD,OAAO;gBACL,EAAE,EAAE,CAAC,CAAC,EAAE;gBACR,MAAM,EAAE,CAAC,CAAC,MAAM;gBAChB,KAAK,EAAE,CAAC,CAAC,KAAK;gBACd,OAAO,EAAE,CAAC,CAAC,OAAO;gBAClB,KAAK,EAAE,CAAC,CAAC,KAAK;gBACd,UAAU,EAAE,CAAC,CAAC,KAAK;gBACnB,UAAU,EAAE,CAAC,CAAC,UAAU;aACzB,CAAC;QACJ,CAAC,CAAC,CAAC;IACL,CAAC;CACF"}
package/package.json CHANGED
@@ -1,59 +1,59 @@
1
- {
2
- "name": "agent-recall-core",
3
- "version": "3.4.50",
4
- "description": "Core memory palace engine for AgentRecall",
5
- "type": "module",
6
- "main": "dist/index.js",
7
- "types": "dist/index.d.ts",
8
- "exports": {
9
- ".": {
10
- "types": "./dist/index.d.ts",
11
- "import": "./dist/index.js"
12
- }
13
- },
14
- "files": [
15
- "dist",
16
- "README.md"
17
- ],
18
- "scripts": {
19
- "build": "tsc",
20
- "test": "node --test test/*.test.mjs"
21
- },
22
- "keywords": [
23
- "agent-recall",
24
- "ai-memory",
25
- "memory-palace",
26
- "agent-memory",
27
- "mcp",
28
- "mcp-server",
29
- "persistent-memory",
30
- "correction-tracking",
31
- "claude-code",
32
- "claude-mcp",
33
- "agent-learning",
34
- "session-memory",
35
- "compounding-memory",
36
- "langchain",
37
- "crewai",
38
- "knowledge-graph",
39
- "obsidian"
40
- ],
41
- "dependencies": {
42
- "@supabase/supabase-js": "^2.105.1",
43
- "vectra": "^0.14.0"
44
- },
45
- "devDependencies": {
46
- "@types/node": "^22.0.0",
47
- "typescript": "^5.7.0"
48
- },
49
- "engines": {
50
- "node": ">=18.0.0"
51
- },
52
- "license": "MIT",
53
- "repository": {
54
- "type": "git",
55
- "url": "git+https://github.com/Goldentrii/AgentRecall-X.git",
56
- "directory": "packages/core"
57
- },
58
- "homepage": "https://github.com/Goldentrii/AgentRecall-X#readme"
59
- }
1
+ {
2
+ "name": "agent-recall-core",
3
+ "version": "3.5.2",
4
+ "description": "Core memory palace engine for AgentRecall",
5
+ "type": "module",
6
+ "main": "dist/index.js",
7
+ "types": "dist/index.d.ts",
8
+ "exports": {
9
+ ".": {
10
+ "types": "./dist/index.d.ts",
11
+ "import": "./dist/index.js"
12
+ }
13
+ },
14
+ "files": [
15
+ "dist",
16
+ "README.md"
17
+ ],
18
+ "scripts": {
19
+ "build": "tsc",
20
+ "test": "node --test test/*.test.mjs"
21
+ },
22
+ "keywords": [
23
+ "agent-recall",
24
+ "ai-memory",
25
+ "memory-palace",
26
+ "agent-memory",
27
+ "mcp",
28
+ "mcp-server",
29
+ "persistent-memory",
30
+ "correction-tracking",
31
+ "claude-code",
32
+ "claude-mcp",
33
+ "agent-learning",
34
+ "session-memory",
35
+ "compounding-memory",
36
+ "langchain",
37
+ "crewai",
38
+ "knowledge-graph",
39
+ "obsidian"
40
+ ],
41
+ "dependencies": {
42
+ "@supabase/supabase-js": "^2.105.1",
43
+ "vectra": "^0.14.0"
44
+ },
45
+ "devDependencies": {
46
+ "@types/node": "^22.0.0",
47
+ "typescript": "^5.7.0"
48
+ },
49
+ "engines": {
50
+ "node": ">=18.0.0"
51
+ },
52
+ "license": "MIT",
53
+ "repository": {
54
+ "type": "git",
55
+ "url": "git+https://github.com/Goldentrii/AgentRecall-X.git",
56
+ "directory": "packages/core"
57
+ },
58
+ "homepage": "https://github.com/Goldentrii/AgentRecall-X#readme"
59
+ }