recallnest 3.0.0 → 4.0.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 (246) hide show
  1. package/CHANGELOG.md +304 -0
  2. package/README.md +251 -258
  3. package/README_CN.md +226 -247
  4. package/assets/ui/app.js +6 -1
  5. package/bin/recallnest.mjs +20 -37
  6. package/docs/api-reference.md +8 -0
  7. package/docs/architecture.md +18 -13
  8. package/eval/cases-canary.json +107 -9
  9. package/integrations/examples/claude-agent-sdk/memory-agent.ts +2 -0
  10. package/integrations/examples/langchain/memory-chain.py +4 -0
  11. package/integrations/examples/openai-agents-sdk/memory-agent.py +4 -0
  12. package/package.json +12 -3
  13. package/src/activity-counter.ts +1 -0
  14. package/src/adaptive-retrieval.ts +23 -0
  15. package/src/api-server.ts +13 -11
  16. package/src/asset-sync.ts +26 -2
  17. package/src/audit-log.ts +2 -0
  18. package/src/auto-gc.ts +4 -3
  19. package/src/belief-history.ts +137 -31
  20. package/src/capture-engine.ts +459 -71
  21. package/src/cascade-forget.ts +7 -3
  22. package/src/checkpoint-mirror.ts +417 -0
  23. package/src/cli.ts +574 -54
  24. package/src/conflict-engine.ts +43 -15
  25. package/src/consolidation-engine.ts +24 -3
  26. package/src/context-collapse-renderer.ts +8 -1
  27. package/src/context-composer-stable.ts +5 -1
  28. package/src/context-composer.ts +11 -2
  29. package/src/distill-lock.ts +246 -74
  30. package/src/dream-pipeline.ts +3 -1
  31. package/src/embedder.ts +24 -0
  32. package/src/env-config.ts +136 -0
  33. package/src/flock.ts +97 -0
  34. package/src/forget-engine.ts +342 -58
  35. package/src/gateway-server.ts +4 -0
  36. package/src/ingest-plan.ts +56 -0
  37. package/src/ingest.ts +294 -121
  38. package/src/kg-contradiction.ts +753 -0
  39. package/src/kg-extractor.ts +17 -0
  40. package/src/kg-store.ts +1 -1
  41. package/src/known-item-eval.ts +455 -0
  42. package/src/llm-client.ts +13 -26
  43. package/src/llm-consolidation.ts +2 -2
  44. package/src/mcp-tool-deps.ts +6 -0
  45. package/src/mcp-tools-advanced.ts +80 -45
  46. package/src/mcp-tools-core.ts +23 -17
  47. package/src/mcp-tools-governance.ts +13 -7
  48. package/src/memory-assets.ts +144 -8
  49. package/src/memory-boundaries.ts +19 -0
  50. package/src/memory-evolution.ts +9 -0
  51. package/src/memory-lint.ts +1 -1
  52. package/src/memory-output.ts +311 -14
  53. package/src/memory-reconcile.ts +1437 -0
  54. package/src/memory-schema.ts +11 -0
  55. package/src/memory-store-port.ts +1 -0
  56. package/src/minis-archive.ts +151 -0
  57. package/src/noise-filter.ts +15 -2
  58. package/src/pii-detector.ts +31 -1
  59. package/src/pivot-apply.ts +55 -5
  60. package/src/pivot-evidence.ts +128 -0
  61. package/src/ppr-traversal.ts +25 -1
  62. package/src/preference-matcher.ts +40 -28
  63. package/src/prospective-memory.ts +7 -4
  64. package/src/retriever.ts +297 -57
  65. package/src/retroactive-boost.ts +3 -2
  66. package/src/runtime-config.ts +15 -1
  67. package/src/scope-policy.ts +1 -0
  68. package/src/session-distiller.ts +6 -2
  69. package/src/session-engine.ts +11 -4
  70. package/src/session-output.ts +20 -1
  71. package/src/session-schema.ts +5 -2
  72. package/src/session-store.ts +59 -12
  73. package/src/skill-promotion.ts +67 -1
  74. package/src/store-receipts.ts +109 -0
  75. package/src/store-write-budget.ts +37 -0
  76. package/src/store.ts +298 -57
  77. package/src/text-fingerprint.ts +25 -0
  78. package/src/trigger-store.ts +443 -0
  79. package/src/ui-server.ts +22 -21
  80. package/src/version-manager.ts +19 -5
  81. package/src/write-verifier.ts +16 -11
  82. package/src/__tests__/access-tracker-novelty.test.ts +0 -324
  83. package/src/__tests__/activity-counter.test.ts +0 -125
  84. package/src/__tests__/adaptive-fidelity.test.ts +0 -102
  85. package/src/__tests__/admission-control.test.ts +0 -206
  86. package/src/__tests__/age-label.test.ts +0 -33
  87. package/src/__tests__/anchor-generator.test.ts +0 -67
  88. package/src/__tests__/api-server-security.test.ts +0 -102
  89. package/src/__tests__/auto-consolidation.test.ts +0 -168
  90. package/src/__tests__/auto-recall.test.ts +0 -131
  91. package/src/__tests__/babel-integration.test.ts +0 -144
  92. package/src/__tests__/batch-dedup.test.ts +0 -65
  93. package/src/__tests__/belief-history.test.ts +0 -220
  94. package/src/__tests__/canary-eval.test.ts +0 -114
  95. package/src/__tests__/capture-engine.test.ts +0 -1328
  96. package/src/__tests__/capture-heuristic.test.ts +0 -171
  97. package/src/__tests__/cascade-forget.test.ts +0 -210
  98. package/src/__tests__/category-min-scores.test.ts +0 -116
  99. package/src/__tests__/cc8-cc1-essential-context.test.ts +0 -298
  100. package/src/__tests__/circuit-breaker.test.ts +0 -99
  101. package/src/__tests__/cluster-consolidation.test.ts +0 -1236
  102. package/src/__tests__/confidence-metadata.test.ts +0 -125
  103. package/src/__tests__/confidence-tracker.test.ts +0 -261
  104. package/src/__tests__/conflict-advisor.test.ts +0 -206
  105. package/src/__tests__/conflict-escalation.test.ts +0 -149
  106. package/src/__tests__/conflict-lifecycle.test.ts +0 -83
  107. package/src/__tests__/conflict-output.test.ts +0 -85
  108. package/src/__tests__/conflict-store.test.ts +0 -418
  109. package/src/__tests__/connector-v1.test.ts +0 -181
  110. package/src/__tests__/consolidation-engine.test.ts +0 -520
  111. package/src/__tests__/constructive-retrieval.test.ts +0 -509
  112. package/src/__tests__/context-collapse-renderer.test.ts +0 -214
  113. package/src/__tests__/context-composer-pins.test.ts +0 -64
  114. package/src/__tests__/context-composer-task-selection.test.ts +0 -24
  115. package/src/__tests__/context-reconstructor.test.ts +0 -65
  116. package/src/__tests__/context-renderer.test.ts +0 -91
  117. package/src/__tests__/continuity-eval.test.ts +0 -275
  118. package/src/__tests__/continuity-schema.test.ts +0 -97
  119. package/src/__tests__/contracts.test.ts +0 -262
  120. package/src/__tests__/conversation-importer.test.ts +0 -692
  121. package/src/__tests__/core-recall-eval.test.ts +0 -235
  122. package/src/__tests__/core-summary.test.ts +0 -109
  123. package/src/__tests__/data-checkup.test.ts +0 -304
  124. package/src/__tests__/decay-exemption.test.ts +0 -129
  125. package/src/__tests__/dedup-actions.test.ts +0 -58
  126. package/src/__tests__/dedup-guard.test.ts +0 -39
  127. package/src/__tests__/deterministic-id.test.ts +0 -39
  128. package/src/__tests__/distill-lock.test.ts +0 -305
  129. package/src/__tests__/distill-session-argshape.test.ts +0 -79
  130. package/src/__tests__/doctor.test.ts +0 -319
  131. package/src/__tests__/dream-pipeline.test.ts +0 -820
  132. package/src/__tests__/dream-scope-isolation.test.ts +0 -386
  133. package/src/__tests__/dream-write-batching.test.ts +0 -211
  134. package/src/__tests__/drill-down.test.ts +0 -108
  135. package/src/__tests__/embedder.test.ts +0 -122
  136. package/src/__tests__/emotion-decay.test.ts +0 -46
  137. package/src/__tests__/emotion-detector.test.ts +0 -56
  138. package/src/__tests__/emotion-phase1-integration.test.ts +0 -153
  139. package/src/__tests__/emotion-retrieval.test.ts +0 -56
  140. package/src/__tests__/entity-resolver.test.ts +0 -58
  141. package/src/__tests__/env-config-invariant.test.ts +0 -80
  142. package/src/__tests__/env-config.test.ts +0 -211
  143. package/src/__tests__/error-signature-boost.test.ts +0 -87
  144. package/src/__tests__/error-signature.test.ts +0 -95
  145. package/src/__tests__/error-taxonomy.test.ts +0 -129
  146. package/src/__tests__/ethics-layer.test.ts +0 -476
  147. package/src/__tests__/event-segmenter.test.ts +0 -153
  148. package/src/__tests__/feature-flags-integration.test.ts +0 -54
  149. package/src/__tests__/frequency-tracker.test.ts +0 -113
  150. package/src/__tests__/freshness.test.ts +0 -186
  151. package/src/__tests__/graph-export.test.ts +0 -489
  152. package/src/__tests__/hotness-blend.test.ts +0 -283
  153. package/src/__tests__/ingest-chunking.test.ts +0 -44
  154. package/src/__tests__/ingest-scope-prefix.test.ts +0 -69
  155. package/src/__tests__/ingest.test.ts +0 -360
  156. package/src/__tests__/interference-detector.test.ts +0 -203
  157. package/src/__tests__/kg-extractor.test.ts +0 -192
  158. package/src/__tests__/kg-store.test.ts +0 -300
  159. package/src/__tests__/llm-client-pivot.test.ts +0 -628
  160. package/src/__tests__/llm-consolidation.test.ts +0 -226
  161. package/src/__tests__/maintenance-locks.test.ts +0 -197
  162. package/src/__tests__/mcp-efficiency.test.ts +0 -288
  163. package/src/__tests__/mcp-related-scopes.test.ts +0 -151
  164. package/src/__tests__/memory-boundaries.test.ts +0 -282
  165. package/src/__tests__/memory-evolution-b2-b3-e1.test.ts +0 -362
  166. package/src/__tests__/memory-evolution.test.ts +0 -271
  167. package/src/__tests__/memory-health-rebalance.test.ts +0 -144
  168. package/src/__tests__/memory-lint.test.ts +0 -421
  169. package/src/__tests__/memory-output.test.ts +0 -224
  170. package/src/__tests__/memory-promotion.test.ts +0 -315
  171. package/src/__tests__/memory-utility.test.ts +0 -256
  172. package/src/__tests__/migrate-dedup-ids.test.ts +0 -65
  173. package/src/__tests__/multi-vector.test.ts +0 -242
  174. package/src/__tests__/narrative-architecture.test.ts +0 -456
  175. package/src/__tests__/noise-filter.test.ts +0 -205
  176. package/src/__tests__/noise-prototype-bank.test.ts +0 -280
  177. package/src/__tests__/obsidian-connector.test.ts +0 -363
  178. package/src/__tests__/omitted-reporting.test.ts +0 -98
  179. package/src/__tests__/openai-contract.test.ts +0 -513
  180. package/src/__tests__/pending-review.test.ts +0 -77
  181. package/src/__tests__/pii-redact.test.ts +0 -333
  182. package/src/__tests__/pivot-apply.test.ts +0 -373
  183. package/src/__tests__/pivot-distill-supervisor.test.ts +0 -457
  184. package/src/__tests__/pivot-distill.test.ts +0 -1178
  185. package/src/__tests__/post-retrieval-filter.test.ts +0 -178
  186. package/src/__tests__/ppr-traversal.test.ts +0 -256
  187. package/src/__tests__/prediction-engine.test.ts +0 -349
  188. package/src/__tests__/predictive-prospective-memory.test.ts +0 -416
  189. package/src/__tests__/preference-guard-smoke.test.ts +0 -211
  190. package/src/__tests__/preference-matcher.test.ts +0 -282
  191. package/src/__tests__/preference-slots.test.ts +0 -205
  192. package/src/__tests__/promotion-distinct-sources.test.ts +0 -162
  193. package/src/__tests__/prospective-memory.test.ts +0 -283
  194. package/src/__tests__/pull-from-macbook-sync-only.test.ts +0 -679
  195. package/src/__tests__/query-entity-detector.test.ts +0 -171
  196. package/src/__tests__/query-expander-alias.test.ts +0 -146
  197. package/src/__tests__/query-expander.test.ts +0 -34
  198. package/src/__tests__/recall-gate.test.ts +0 -266
  199. package/src/__tests__/recall-governor.test.ts +0 -227
  200. package/src/__tests__/recall-mode.test.ts +0 -64
  201. package/src/__tests__/resolve-db-path.test.ts +0 -130
  202. package/src/__tests__/resolve-tier.test.ts +0 -64
  203. package/src/__tests__/result-synthesizer.test.ts +0 -198
  204. package/src/__tests__/resume-context.test.ts +0 -4898
  205. package/src/__tests__/retrieval-eval.test.ts +0 -163
  206. package/src/__tests__/retrieval-trace.test.ts +0 -213
  207. package/src/__tests__/retrieve-audit-revision.test.ts +0 -255
  208. package/src/__tests__/retriever-boundary-weight.test.ts +0 -136
  209. package/src/__tests__/retriever-lazy-init-dispatch.test.ts +0 -123
  210. package/src/__tests__/retroactive-boost.test.ts +0 -223
  211. package/src/__tests__/salience-scoring.test.ts +0 -106
  212. package/src/__tests__/scope-inventory.test.ts +0 -200
  213. package/src/__tests__/scope-policy.test.ts +0 -69
  214. package/src/__tests__/scope-suggester.test.ts +0 -80
  215. package/src/__tests__/session-checkpoint.test.ts +0 -291
  216. package/src/__tests__/session-distiller.test.ts +0 -640
  217. package/src/__tests__/session-gc.test.ts +0 -215
  218. package/src/__tests__/skill-engine.test.ts +0 -552
  219. package/src/__tests__/skill-promotion.test.ts +0 -654
  220. package/src/__tests__/skill-verifier.test.ts +0 -122
  221. package/src/__tests__/source-heartbeat.test.ts +0 -254
  222. package/src/__tests__/stable-context-length-contract.test.ts +0 -62
  223. package/src/__tests__/store-patch-metadata.test.ts +0 -235
  224. package/src/__tests__/store-read-consistency.test.ts +0 -122
  225. package/src/__tests__/store-schema-migration.test.ts +0 -87
  226. package/src/__tests__/store-scope-audit.test.ts +0 -81
  227. package/src/__tests__/store-upsert.test.ts +0 -201
  228. package/src/__tests__/supersede-chain.test.ts +0 -154
  229. package/src/__tests__/synthesis-contract.test.ts +0 -252
  230. package/src/__tests__/synthesis-promotion.test.ts +0 -369
  231. package/src/__tests__/temporal-parser.test.ts +0 -241
  232. package/src/__tests__/temporal-validity.test.ts +0 -160
  233. package/src/__tests__/term-registry-terminal-roster.test.ts +0 -127
  234. package/src/__tests__/term-registry.test.ts +0 -121
  235. package/src/__tests__/tool-error-surfacing.test.ts +0 -98
  236. package/src/__tests__/tool-output-compressor.test.ts +0 -160
  237. package/src/__tests__/topic-tag.test.ts +0 -113
  238. package/src/__tests__/trusted-memory.test.ts +0 -867
  239. package/src/__tests__/ui-server-security.test.ts +0 -93
  240. package/src/__tests__/usage-tracker.test.ts +0 -287
  241. package/src/__tests__/utility-weight.test.ts +0 -57
  242. package/src/__tests__/verbatim-self-recall.test.ts +0 -279
  243. package/src/__tests__/version-manager.test.ts +0 -248
  244. package/src/__tests__/workflow-observation-skill-outcome.test.ts +0 -352
  245. package/src/__tests__/workflow-observation.test.ts +0 -433
  246. package/src/__tests__/write-verifier.test.ts +0 -122
@@ -1,200 +0,0 @@
1
- import { afterEach, describe, expect, it } from "bun:test";
2
- import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
3
- import { tmpdir } from "node:os";
4
- import { join } from "node:path";
5
-
6
- import { collectScopeInventory, formatScopeInventoryReport } from "../scope-inventory.js";
7
- import { MemoryStore } from "../store.js";
8
-
9
- const cleanupPaths: string[] = [];
10
-
11
- afterEach(() => {
12
- while (cleanupPaths.length > 0) {
13
- const target = cleanupPaths.pop();
14
- if (target) {
15
- rmSync(target, { recursive: true, force: true });
16
- }
17
- }
18
- });
19
-
20
- function createTempRoot(): string {
21
- const root = mkdtempSync(join(tmpdir(), "recallnest-scope-inventory-"));
22
- cleanupPaths.push(root);
23
- return root;
24
- }
25
-
26
- function writeJson(dir: string, name: string, payload: unknown): void {
27
- mkdirSync(dir, { recursive: true });
28
- writeFileSync(join(dir, name), JSON.stringify(payload, null, 2) + "\n");
29
- }
30
-
31
- describe("collectScopeInventory", () => {
32
- it("audits memories, pins, checkpoints, and workflow observations separately", async () => {
33
- const root = createTempRoot();
34
- const store = new MemoryStore({
35
- dbPath: join(root, "db"),
36
- vectorDim: 3,
37
- });
38
-
39
- await store.store({
40
- text: "Scoped durable memory.",
41
- vector: [1, 0, 0],
42
- category: "entities",
43
- scope: "project:recallnest",
44
- importance: 0.8,
45
- metadata: "{}",
46
- });
47
- await store.store({
48
- text: "Historical global memory row.",
49
- vector: [0, 1, 0],
50
- category: "events",
51
- scope: "global",
52
- importance: 0.5,
53
- metadata: "{}",
54
- });
55
-
56
- const pinsDir = join(root, "pins");
57
- writeJson(pinsDir, "pin-legacy.json", {
58
- id: "pin-legacy",
59
- type: "pinned-memory",
60
- title: "Legacy pin",
61
- summary: "Pinned from an old global row.",
62
- source: {
63
- memoryId: "memory-1",
64
- scope: "global",
65
- timestamp: Date.now(),
66
- metadata: {},
67
- },
68
- createdAt: "2026-03-18T00:00:00.000Z",
69
- updatedAt: "2026-03-18T00:00:00.000Z",
70
- snippet: "Legacy pin snippet.",
71
- });
72
-
73
- const checkpointsDir = join(root, "session-checkpoints");
74
- writeJson(checkpointsDir, "checkpoint-legacy.json", {
75
- checkpointId: "checkpoint-legacy",
76
- sessionId: "session-1",
77
- resolvedScope: " ",
78
- summary: "Old checkpoint that never got a real resolved scope.",
79
- updatedAt: "2026-03-18T00:01:00.000Z",
80
- });
81
-
82
- const workflowDir = join(root, "workflow-observations");
83
- writeJson(workflowDir, "workflow-legacy.json", {
84
- observationId: "workflow-legacy",
85
- workflowId: "resume_context",
86
- resolvedScope: null,
87
- summary: "Legacy workflow observation missing scope.",
88
- recordedAt: "2026-03-18T00:02:00.000Z",
89
- });
90
- mkdirSync(workflowDir, { recursive: true });
91
- writeFileSync(join(workflowDir, "broken.json"), "{not-json");
92
-
93
- const report = await collectScopeInventory({
94
- store,
95
- sampleLimit: 10,
96
- pinsDir,
97
- checkpointsDir,
98
- workflowObservationsDir: workflowDir,
99
- });
100
-
101
- expect(report.totalScannedCount).toBe(6);
102
- expect(report.totalAnomalyCount).toBe(4);
103
- expect(report.totalInvalidCount).toBe(1);
104
- expect(report.totalReviewedCount).toBe(0);
105
-
106
- const memoryLayer = report.layers.find((layer) => layer.layer === "memories");
107
- const pinLayer = report.layers.find((layer) => layer.layer === "pins");
108
- const checkpointLayer = report.layers.find((layer) => layer.layer === "session-checkpoints");
109
- const workflowLayer = report.layers.find((layer) => layer.layer === "workflow-observations");
110
-
111
- expect(memoryLayer?.anomalyCount).toBe(1);
112
- expect(memoryLayer?.counts.global).toBe(1);
113
- expect(pinLayer?.anomalyCount).toBe(1);
114
- expect(pinLayer?.counts.global).toBe(1);
115
- expect(checkpointLayer?.anomalyCount).toBe(1);
116
- expect(checkpointLayer?.counts.empty).toBe(1);
117
- expect(workflowLayer?.anomalyCount).toBe(1);
118
- expect(workflowLayer?.counts.missing).toBe(1);
119
- expect(workflowLayer?.invalidCount).toBe(1);
120
- expect(workflowLayer?.reviewedCount).toBe(0);
121
-
122
- const output = formatScopeInventoryReport(report);
123
- expect(output).toContain("Scope inventory");
124
- expect(output).toContain("[memories]");
125
- expect(output).toContain("[pins]");
126
- expect(output).toContain("[session-checkpoints]");
127
- expect(output).toContain("[workflow-observations]");
128
- });
129
-
130
- it("returns a clean report when every layer is scoped correctly", async () => {
131
- const root = createTempRoot();
132
- const store = new MemoryStore({
133
- dbPath: join(root, "db"),
134
- vectorDim: 3,
135
- });
136
-
137
- await store.store({
138
- text: "Scoped memory.",
139
- vector: [1, 0, 0],
140
- category: "entities",
141
- scope: "project:recallnest",
142
- importance: 0.9,
143
- metadata: "{}",
144
- });
145
-
146
- const report = await collectScopeInventory({
147
- store,
148
- sampleLimit: 5,
149
- pinsDir: join(root, "missing-pins"),
150
- checkpointsDir: join(root, "missing-checkpoints"),
151
- workflowObservationsDir: join(root, "missing-workflows"),
152
- });
153
-
154
- expect(report.totalScannedCount).toBe(1);
155
- expect(report.totalAnomalyCount).toBe(0);
156
- expect(report.totalInvalidCount).toBe(0);
157
- expect(report.totalReviewedCount).toBe(0);
158
- expect(report.layers.every((layer) => layer.samples.length === 0)).toBe(true);
159
- expect(formatScopeInventoryReport(report)).toContain("No unresolved legacy scope anomalies found");
160
- });
161
-
162
- it("suppresses reviewed keep-global workflow observations from unresolved anomaly counts", async () => {
163
- const root = createTempRoot();
164
- const store = new MemoryStore({
165
- dbPath: join(root, "db"),
166
- vectorDim: 3,
167
- });
168
-
169
- const workflowDir = join(root, "workflow-observations");
170
- writeJson(workflowDir, "workflow-reviewed.json", {
171
- observationId: "workflow-reviewed",
172
- workflowId: "resume_context",
173
- resolvedScope: "global",
174
- summary: "Legacy workflow observation intentionally left global.",
175
- recordedAt: "2026-03-18T00:02:00.000Z",
176
- legacyScopeReview: {
177
- decision: "keep",
178
- kind: "global",
179
- reason: "external-task",
180
- reviewedAt: "2026-03-18T00:03:00.000Z",
181
- },
182
- });
183
-
184
- const report = await collectScopeInventory({
185
- store,
186
- sampleLimit: 5,
187
- workflowObservationsDir: workflowDir,
188
- pinsDir: join(root, "missing-pins"),
189
- checkpointsDir: join(root, "missing-checkpoints"),
190
- });
191
-
192
- const workflowLayer = report.layers.find((layer) => layer.layer === "workflow-observations");
193
- expect(report.totalAnomalyCount).toBe(0);
194
- expect(report.totalReviewedCount).toBe(1);
195
- expect(workflowLayer?.anomalyCount).toBe(0);
196
- expect(workflowLayer?.reviewedCount).toBe(1);
197
- expect(workflowLayer?.samples).toHaveLength(0);
198
- expect(formatScopeInventoryReport(report)).toContain("Reviewed keeps : 1");
199
- });
200
- });
@@ -1,69 +0,0 @@
1
- import { describe, expect, it } from "bun:test";
2
-
3
- import { matchesScopeFilter, resolveScopeSelection, resolveSessionScope } from "../scope-policy.js";
4
-
5
- describe("scope-policy", () => {
6
- it("prefers explicit scope over inferred values", () => {
7
- const resolved = resolveScopeSelection({
8
- scope: "project:recallnest",
9
- sessionId: "session-123",
10
- operation: "test:search",
11
- env: {
12
- RECALLNEST_DEFAULT_SCOPE: "project:other",
13
- } as NodeJS.ProcessEnv,
14
- });
15
-
16
- expect(resolved.resolvedScope).toBe("project:recallnest");
17
- expect(resolved.scopeFilter).toEqual(["project:recallnest"]);
18
- expect(resolved.inferredFrom).toBe("scope");
19
- });
20
-
21
- it("falls back to session scope when explicit scope is absent", () => {
22
- expect(resolveSessionScope("session-123")).toBe("session:session-123");
23
-
24
- const resolved = resolveScopeSelection({
25
- sessionId: "session-123",
26
- operation: "test:search",
27
- env: {} as NodeJS.ProcessEnv,
28
- });
29
-
30
- expect(resolved.resolvedScope).toBe("session:session-123");
31
- expect(resolved.scopeFilter).toEqual(["session:session-123"]);
32
- expect(resolved.inferredFrom).toBe("sessionId");
33
- });
34
-
35
- it("uses environment defaults when request scope is omitted", () => {
36
- const resolved = resolveScopeSelection({
37
- operation: "test:search",
38
- env: {
39
- RECALLNEST_DEFAULT_SCOPE: "project:recallnest",
40
- } as NodeJS.ProcessEnv,
41
- });
42
-
43
- expect(resolved.resolvedScope).toBe("project:recallnest");
44
- expect(resolved.scopeFilter).toEqual(["project:recallnest"]);
45
- expect(resolved.inferredFrom).toBe("RECALLNEST_DEFAULT_SCOPE");
46
- });
47
-
48
- it("requires explicit opt-in before allowing cross-scope reads", () => {
49
- expect(() => resolveScopeSelection({
50
- operation: "test:search",
51
- env: {} as NodeJS.ProcessEnv,
52
- })).toThrow("requires a scope");
53
-
54
- const allScopes = resolveScopeSelection({
55
- operation: "test:search",
56
- allScopes: true,
57
- env: {} as NodeJS.ProcessEnv,
58
- });
59
-
60
- expect(allScopes.allScopes).toBe(true);
61
- expect(allScopes.scopeFilter).toBeUndefined();
62
- });
63
-
64
- it("matches both exact and prefix scope filters", () => {
65
- expect(matchesScopeFilter("project:recallnest", ["project:recallnest"])).toBe(true);
66
- expect(matchesScopeFilter("cc:session-123", ["cc"])).toBe(true);
67
- expect(matchesScopeFilter("project:other", ["project:recallnest"])).toBe(false);
68
- });
69
- });
@@ -1,80 +0,0 @@
1
- import { describe, expect, it } from "bun:test";
2
-
3
- import {
4
- boundedLevenshtein,
5
- createScopeSuggester,
6
- formatScopeSuggestion,
7
- normalizeScope,
8
- suggestScopes,
9
- } from "../scope-suggester.js";
10
-
11
- describe("normalizeScope", () => {
12
- it("lowercases and strips separators", () => {
13
- expect(normalizeScope("CC-Foo")).toBe("ccfoo");
14
- expect(normalizeScope("cc_foo bar")).toBe("ccfoobar");
15
- });
16
- });
17
-
18
- describe("boundedLevenshtein", () => {
19
- it("computes small distances and early-exits beyond max", () => {
20
- expect(boundedLevenshtein("recallnest", "recallnest", 2)).toBe(0);
21
- expect(boundedLevenshtein("recallnst", "recallnest", 2)).toBe(1);
22
- expect(boundedLevenshtein("recalnst", "recallnest", 2)).toBe(2);
23
- expect(boundedLevenshtein("abc", "xyzuvw", 2)).toBe(3); // max+1
24
- });
25
- });
26
-
27
- describe("suggestScopes", () => {
28
- const known = ["recallnest", "recallnest:self", "cc", "cc:55bcbfb3", "project:test"];
29
-
30
- it("matches typos within edit distance 2", () => {
31
- expect(suggestScopes("recallnst", known)).toContain("recallnest");
32
- });
33
-
34
- it("matches case differences via normalization", () => {
35
- expect(suggestScopes("RecallNest", known)[0]).toBe("recallnest");
36
- });
37
-
38
- it("matches separator convention drift", () => {
39
- expect(suggestScopes("recall-nest", known)[0]).toBe("recallnest");
40
- expect(suggestScopes("recall_nest", known)[0]).toBe("recallnest");
41
- });
42
-
43
- it("matches by prefix in both directions", () => {
44
- expect(suggestScopes("recall", known)).toContain("recallnest");
45
- });
46
-
47
- it("returns empty for unrelated input", () => {
48
- expect(suggestScopes("totally-unrelated-thing", known)).toEqual([]);
49
- expect(suggestScopes("", known)).toEqual([]);
50
- });
51
-
52
- it("caps suggestions at maxSuggestions", () => {
53
- const many = ["aa1", "aa2", "aa3", "aa4", "aa5"];
54
- expect(suggestScopes("aa", many, 3)).toHaveLength(3);
55
- });
56
- });
57
-
58
- describe("createScopeSuggester", () => {
59
- it("derives prefix families and caches scope counts", async () => {
60
- let calls = 0;
61
- const suggest = createScopeSuggester(async () => {
62
- calls++;
63
- return { "cc:55bcbfb3": 100, "cc:65314581": 50, "codex:019cc122": 30 };
64
- });
65
-
66
- // 拼错的 prefix 应命中 prefix 家族(cc),不需要整串 session scope 相似
67
- const r1 = await suggest("ccc");
68
- expect(r1).toContain("cc");
69
-
70
- await suggest("codx");
71
- expect(calls).toBe(1); // 60s TTL 内复用缓存
72
- });
73
- });
74
-
75
- describe("formatScopeSuggestion", () => {
76
- it("renders hint or empty string", () => {
77
- expect(formatScopeSuggestion("recallnst", ["recallnest"])).toContain("recallnest");
78
- expect(formatScopeSuggestion("x", [])).toBe("");
79
- });
80
- });
@@ -1,291 +0,0 @@
1
- import { describe, expect, it } from "bun:test";
2
- import { mkdtempSync, readdirSync, rmSync } from "node:fs";
3
- import { tmpdir } from "node:os";
4
- import { join } from "node:path";
5
-
6
- import { buildSessionCheckpointRecord, buildSessionCheckpointResult, normalizeCheckpointScope, resolveCheckpointScope, type CheckpointQuality } from "../session-engine.js";
7
- import { formatCheckpointRecallSummary, formatCheckpointSaved, formatCheckpointSummary, formatResumeContext } from "../session-output.js";
8
- import { SessionCheckpointStore } from "../session-store.js";
9
-
10
- describe("session checkpoint engine", () => {
11
- it("defaults checkpoint scope to session:<sessionId>", () => {
12
- const record = buildSessionCheckpointRecord({
13
- sessionId: "session-abc",
14
- summary: "Implement checkpoint storage",
15
- });
16
-
17
- expect(resolveCheckpointScope(record)).toBe("session:session-abc");
18
- expect(record.resolvedScope).toBe("session:session-abc");
19
- });
20
- });
21
-
22
- describe("SessionCheckpointStore", () => {
23
- it("saves and retrieves latest checkpoints by scope and session", async () => {
24
- const dir = mkdtempSync(join(tmpdir(), "recallnest-checkpoints-"));
25
- try {
26
- const store = new SessionCheckpointStore(dir);
27
-
28
- const first = await store.save(buildSessionCheckpointRecord({
29
- sessionId: "session-1",
30
- scope: "agent:codex",
31
- summary: "First checkpoint",
32
- nextActions: ["Implement checkpoint_session"],
33
- updatedAt: "2026-03-16T03:00:00.000Z",
34
- }));
35
-
36
- const second = await store.save(buildSessionCheckpointRecord({
37
- sessionId: "session-2",
38
- scope: "agent:codex",
39
- summary: "Second checkpoint",
40
- updatedAt: "2026-03-16T03:05:00.000Z",
41
- }));
42
-
43
- const latestByScope = await store.getLatest({ scope: "agent:codex" });
44
- const latestBySession = await store.getLatest({ sessionId: "session-1" });
45
-
46
- expect(latestByScope?.checkpointId).toBe(second.checkpointId);
47
- expect(latestBySession?.checkpointId).toBe(first.checkpointId);
48
- } finally {
49
- rmSync(dir, { recursive: true, force: true });
50
- }
51
- });
52
-
53
- it("uses idempotencyKey to replace retried checkpoint files", async () => {
54
- const dir = mkdtempSync(join(tmpdir(), "recallnest-checkpoint-idempotency-"));
55
- try {
56
- const store = new SessionCheckpointStore(dir);
57
- const baseInput = {
58
- sessionId: "session-retry",
59
- scope: "project:recallnest",
60
- summary: "Save retry-safe checkpoint state.",
61
- decisions: ["Use explicit idempotency keys for client retries"],
62
- idempotencyKey: "checkpoint-request-123",
63
- };
64
-
65
- const first = await store.save(buildSessionCheckpointRecord({
66
- ...baseInput,
67
- updatedAt: "2026-06-26T01:00:00.000Z",
68
- }));
69
- const retried = await store.save(buildSessionCheckpointRecord({
70
- ...baseInput,
71
- updatedAt: "2026-06-26T01:01:00.000Z",
72
- }));
73
-
74
- expect(retried.checkpointId).toBe(first.checkpointId);
75
- expect(readdirSync(dir).filter((name) => name.endsWith(".json"))).toHaveLength(1);
76
-
77
- const recent = await store.listRecent({ sessionId: "session-retry", limit: 10 });
78
- expect(recent).toHaveLength(1);
79
- expect(recent[0]?.updatedAt).toBe("2026-06-26T01:01:00.000Z");
80
- } finally {
81
- rmSync(dir, { recursive: true, force: true });
82
- }
83
- });
84
- });
85
-
86
- describe("session checkpoint output", () => {
87
- it("formats saved and summary views", () => {
88
- const record = buildSessionCheckpointRecord({
89
- sessionId: "session-xyz",
90
- summary: "Current task is implementing session checkpoints",
91
- decisions: ["Keep checkpoints out of LanceDB"],
92
- openLoops: ["Need resume_context next"],
93
- nextActions: ["Add latest checkpoint API"],
94
- });
95
-
96
- expect(formatCheckpointSaved(record)).toContain("Keep checkpoints out of LanceDB");
97
- expect(formatCheckpointSummary(record)).toContain("Latest checkpoint");
98
- expect(formatCheckpointSummary(null)).toBe("No checkpoint found.");
99
- });
100
-
101
- it("enriches recall checkpoint summaries with missing entity hints only once", () => {
102
- const record = buildSessionCheckpointRecord({
103
- sessionId: "session-entity-hints",
104
- summary: "Raised continuity coverage for RecallNest startup recovery.",
105
- entities: ["RecallNest", "smoke:claude-continuity", "resume_context"],
106
- });
107
-
108
- expect(formatCheckpointRecallSummary(record)).toBe(
109
- "Raised continuity coverage for RecallNest startup recovery. Entities: smoke:claude-continuity, resume_context",
110
- );
111
- });
112
-
113
- it("includes recall-only guidance in formatted resume context output", () => {
114
- const output = formatResumeContext({
115
- summary: "Stable context: Preference: 用户不喜欢 AI 味太重的文案语气。",
116
- resolvedScope: "project:writing",
117
- stableContext: ["Preference: 用户不喜欢 AI 味太重的文案语气。"],
118
- relevantPatterns: [],
119
- recentCases: [],
120
- latestCheckpoint: {
121
- sessionId: "session-writing",
122
- resolvedScope: "project:writing",
123
- summary: "Continue writing-style preference recovery.",
124
- updatedAt: "2026-03-16T04:30:00.000Z",
125
- },
126
- responseMode: "recall-only",
127
- responseGuidance: "Recall-only mode: answer from the recalled stable context item only.",
128
- generatedAt: "2026-03-16T04:40:00.000Z",
129
- });
130
-
131
- expect(output).toContain("Scope: project:writing");
132
- expect(output).toContain("Response mode: recall-only");
133
- expect(output).toContain("Guidance: Recall-only mode");
134
- expect(output).toContain("Stable context:");
135
- });
136
-
137
- it("sanitizes repo-state text out of checkpoint content", () => {
138
- const result = buildSessionCheckpointResult({
139
- sessionId: "session-repo-state",
140
- summary: "Only resumed context in this window. git status shows many modified files.",
141
- task: "Handle git status follow-up",
142
- decisions: ["Keep repo-state out of checkpoints."],
143
- openLoops: ["git status shows many uncommitted changes that still need review"],
144
- nextActions: ["Process modified files after checking git status locally"],
145
- });
146
- const { record } = result;
147
-
148
- expect(record.summary).toBe("Checkpoint captured current task state without repo-state details.");
149
- expect(record.task).toBeUndefined();
150
- expect(record.decisions).toEqual(["Keep repo-state out of checkpoints."]);
151
- expect(record.openLoops).toEqual(["Current repo state still needs local verification if it matters for the next task."]);
152
- expect(record.nextActions).toEqual(["Verify current repo state locally if it matters for the next task."]);
153
- expect(result.sanitization.changed).toBe(true);
154
- expect(result.sanitization.changedFields).toEqual(["summary", "task", "openLoops", "nextActions"]);
155
- });
156
-
157
- it("does not mark sanitization when checkpoint content is already clean", () => {
158
- const result = buildSessionCheckpointResult({
159
- sessionId: "session-clean",
160
- summary: "Continue wiring workflow observations into managed continuity.",
161
- task: "Hook managed continuity observations",
162
- decisions: ["Keep observations out of durable memory."],
163
- openLoops: ["Need to update the managed snippets."],
164
- nextActions: ["Add MCP and HTTP auto-observation coverage."],
165
- });
166
-
167
- expect(result.sanitization.changed).toBe(false);
168
- expect(result.sanitization.changedFields).toEqual([]);
169
- });
170
- });
171
-
172
- describe("checkpoint scope normalization", () => {
173
- it("normalizes bare project names to project: prefix", () => {
174
- expect(normalizeCheckpointScope("recallnest")).toBe("project:recallnest");
175
- expect(normalizeCheckpointScope("RecallNest")).toBe("project:recallnest");
176
- expect(normalizeCheckpointScope("telegram-bridge")).toBe("project:telegram-bridge");
177
- });
178
-
179
- it("preserves existing prefixes but lowercases", () => {
180
- expect(normalizeCheckpointScope("project:RecallNest")).toBe("project:recallnest");
181
- expect(normalizeCheckpointScope("session:abc")).toBe("session:abc");
182
- expect(normalizeCheckpointScope("eval:continuity")).toBe("eval:continuity");
183
- });
184
-
185
- it("applies normalization at save time via resolveCheckpointScope", () => {
186
- expect(resolveCheckpointScope({ sessionId: "s1", scope: "RecallNest" })).toBe("project:recallnest");
187
- expect(resolveCheckpointScope({ sessionId: "s1", scope: "project:RecallNest" })).toBe("project:recallnest");
188
- expect(resolveCheckpointScope({ sessionId: "s1" })).toBe("session:s1");
189
- });
190
-
191
- it("matches checkpoints across scope variants in getLatest", async () => {
192
- const dir = mkdtempSync(join(tmpdir(), "recallnest-scope-norm-"));
193
- try {
194
- const store = new SessionCheckpointStore(dir);
195
-
196
- // Save with bare "recallnest" — will be normalized to "project:recallnest"
197
- await store.save(buildSessionCheckpointRecord({
198
- sessionId: "s-bare",
199
- scope: "recallnest",
200
- summary: "Bare scope checkpoint",
201
- }));
202
-
203
- // Save with "project:RecallNest" — will be normalized to "project:recallnest"
204
- const later = buildSessionCheckpointRecord({
205
- sessionId: "s-cased",
206
- scope: "project:RecallNest",
207
- summary: "Cased scope checkpoint",
208
- });
209
- // Manually set a later timestamp
210
- (later as any).updatedAt = new Date(Date.now() + 1000).toISOString().replace(/\.\d+Z$/, ".000Z");
211
- await store.save(later);
212
-
213
- // Query with canonical "project:recallnest" should find both, return latest
214
- const latest = await store.getLatest({ scope: "project:recallnest" });
215
- expect(latest).not.toBeNull();
216
- expect(latest!.summary).toBe("Cased scope checkpoint");
217
-
218
- // Query with bare "recallnest" should also work
219
- const latestBare = await store.getLatest({ scope: "recallnest" });
220
- expect(latestBare).not.toBeNull();
221
- expect(latestBare!.summary).toBe("Cased scope checkpoint");
222
- } finally {
223
- rmSync(dir, { recursive: true, force: true });
224
- }
225
- });
226
- });
227
-
228
- describe("checkpoint quality gate", () => {
229
- it("classifies checkpoints with fallback summary and empty fields as minimal", () => {
230
- const result = buildSessionCheckpointResult({
231
- sessionId: "s-empty",
232
- scope: "project:recallnest",
233
- summary: "git status shows 5 modified files and 3 untracked files",
234
- });
235
- // Summary was sanitized to fallback, no decisions/openLoops/nextActions
236
- expect(result.quality).toBe("minimal");
237
- expect(result.sanitization.changed).toBe(true);
238
- });
239
-
240
- it("classifies checkpoints with real content as rich", () => {
241
- const result = buildSessionCheckpointResult({
242
- sessionId: "s-rich",
243
- scope: "project:recallnest",
244
- summary: "Completed scope normalization and checkpoint quality gate.",
245
- decisions: ["Normalize scope at save and query time"],
246
- });
247
- expect(result.quality).toBe("rich");
248
- });
249
-
250
- it("classifies checkpoints with fallback summary but structured fields as rich", () => {
251
- const result = buildSessionCheckpointResult({
252
- sessionId: "s-mixed",
253
- scope: "project:recallnest",
254
- summary: "git status shows dirty worktree",
255
- decisions: ["Keep using bun for builds"],
256
- });
257
- // Summary sanitized to fallback but decisions non-empty → still rich
258
- expect(result.quality).toBe("rich");
259
- });
260
-
261
- it("prefers rich checkpoints over minimal ones in getLatest", async () => {
262
- const dir = mkdtempSync(join(tmpdir(), "recallnest-quality-gate-"));
263
- try {
264
- const store = new SessionCheckpointStore(dir);
265
-
266
- // Save a rich checkpoint first (older)
267
- await store.save(buildSessionCheckpointRecord({
268
- sessionId: "s-rich",
269
- scope: "project:recallnest",
270
- summary: "Good checkpoint with real content.",
271
- decisions: ["Keep checkpoints clean"],
272
- updatedAt: "2026-03-22T01:00:00.000Z",
273
- }));
274
-
275
- // Save a minimal checkpoint later (newer) — all-sanitized fallback
276
- await store.save(buildSessionCheckpointRecord({
277
- sessionId: "s-minimal",
278
- scope: "project:recallnest",
279
- summary: "Checkpoint captured current task state without repo-state details.",
280
- updatedAt: "2026-03-22T02:00:00.000Z",
281
- }));
282
-
283
- const latest = await store.getLatest({ scope: "project:recallnest" });
284
- expect(latest).not.toBeNull();
285
- // Should return the rich one even though it's older
286
- expect(latest!.summary).toBe("Good checkpoint with real content.");
287
- } finally {
288
- rmSync(dir, { recursive: true, force: true });
289
- }
290
- });
291
- });