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,520 +0,0 @@
1
- import { describe, expect, it } from "bun:test";
2
-
3
- import { ConsolidationEngine, DEFAULT_CONSOLIDATION_CONFIG, formatConsolidationResult, tripleJaccard, type ConsolidationResult, type ConsolidationTripleEvidence } from "../consolidation-engine.js";
4
- import type { MemoryEntry, MemorySearchResult } from "../store.js";
5
-
6
- function makeEntry(overrides: Partial<MemoryEntry> & { id: string; text: string }): MemoryEntry {
7
- return {
8
- vector: [1, 0, 0],
9
- category: "events",
10
- scope: "project:test",
11
- importance: 0.7,
12
- timestamp: Date.now(),
13
- metadata: "{}",
14
- ...overrides,
15
- };
16
- }
17
-
18
- function createMockStore(entries: MemoryEntry[], similarityMap: Map<string, Map<string, number>> = new Map()) {
19
- const data = new Map(entries.map(e => [e.id, { ...e }]));
20
- const updates: Array<{ id: string; metadata: string }> = [];
21
-
22
- return {
23
- updates,
24
- store: {
25
- async list(scopeFilter?: string[], _category?: string, limit = 500, _offset = 0) {
26
- return [...data.values()]
27
- .filter(e => !scopeFilter || scopeFilter.some(s => e.scope === s))
28
- .slice(0, limit);
29
- },
30
- async getById(id: string) {
31
- return data.get(id) ?? null;
32
- },
33
- async vectorSearch(vector: number[], limit = 5, minScore = 0.3, scopeFilter?: string[]) {
34
- // Use the similarity map to compute fake scores
35
- const sourceEntry = [...data.values()].find(e =>
36
- e.vector.length === vector.length && e.vector.every((v, i) => v === vector[i])
37
- );
38
- if (!sourceEntry) return [];
39
-
40
- const sourceMap = similarityMap.get(sourceEntry.id);
41
- if (!sourceMap) return [];
42
-
43
- const results: MemorySearchResult[] = [];
44
- for (const [targetId, score] of sourceMap) {
45
- if (score < minScore) continue;
46
- const target = data.get(targetId);
47
- if (!target) continue;
48
- if (scopeFilter && !scopeFilter.some(s => target.scope === s)) continue;
49
- results.push({ entry: target, score });
50
- }
51
- return results.sort((a, b) => b.score - a.score).slice(0, limit);
52
- },
53
- async update(id: string, upd: { metadata?: string }) {
54
- const entry = data.get(id);
55
- if (!entry) return null;
56
- if (upd.metadata) {
57
- entry.metadata = upd.metadata;
58
- updates.push({ id, metadata: upd.metadata });
59
- }
60
- return entry;
61
- },
62
- // 2026-08-14: 忠实模拟生产语义 —— 以 mock 存储的最新行起底应用 patchFn、按序执行、
63
- // 就地落库。批量写同样进 updates 数组,既有的 updates.find() 断言无需改动。
64
- async patchMetadataBatch(
65
- patches: Array<{ id: string; patchFn: (meta: Record<string, unknown>, entry: MemoryEntry) => Record<string, unknown> }>,
66
- _scopeFilter?: string[],
67
- ) {
68
- let written = 0;
69
- for (const { id, patchFn } of patches) {
70
- const entry = data.get(id);
71
- if (!entry) continue;
72
- let meta: Record<string, unknown>;
73
- try { meta = JSON.parse(entry.metadata || "{}") as Record<string, unknown>; } catch { meta = {}; }
74
- const patched = patchFn(meta, entry);
75
- entry.metadata = JSON.stringify(patched);
76
- updates.push({ id, metadata: entry.metadata });
77
- written++;
78
- }
79
- return written;
80
- },
81
- },
82
- };
83
- }
84
-
85
- describe("ConsolidationEngine", () => {
86
- it("returns empty result for empty scope", async () => {
87
- const { store } = createMockStore([]);
88
- const engine = new ConsolidationEngine(store);
89
- const result = await engine.run("project:test");
90
- expect(result.originalCount).toBe(0);
91
- expect(result.clustersFound).toBe(0);
92
- });
93
-
94
- it("skips single-entry categories", async () => {
95
- const entries = [makeEntry({ id: "a", text: "only one" })];
96
- const { store } = createMockStore(entries);
97
- const engine = new ConsolidationEngine(store);
98
- const result = await engine.run("project:test");
99
- expect(result.originalCount).toBe(1);
100
- expect(result.clustersFound).toBe(0);
101
- });
102
-
103
- // 2026-08-14 Bug-1 回归:旧逐条写路径里 cluster 循环基于从不刷新的旧内存串 patch,
104
- // member 的 consolidatedMeta 写与 canonical 的 sourceMemories 写会把 createVersionGroup
105
- // 刚落库的 version_group 抹掉(2 成员 cluster 同样全丢),下一个 member 还会新造 groupId。
106
- // 断言口径是**最终存储态**(getById 终值)——旧测试用 updates.find() 只看首写,恰好
107
- // 看不见覆盖(互审 C3 指出的断言形态缺陷)。
108
- it("Bug-1 回归:2 成员 merge 后双方 version_group 同组共存,sourceMemories/consolidatedInto 齐全", async () => {
109
- const entryA = makeEntry({ id: "a", text: "canonical fact", vector: [1, 0, 0], importance: 0.9 });
110
- const entryB = makeEntry({ id: "b", text: "duplicate fact", vector: [0.99, 0.1, 0], importance: 0.5 });
111
- const simMap = new Map([
112
- ["a", new Map([["b", 0.95]])],
113
- ["b", new Map([["a", 0.95]])],
114
- ]);
115
- const { store } = createMockStore([entryA, entryB], simMap);
116
- const engine = new ConsolidationEngine(store, { ...DEFAULT_CONSOLIDATION_CONFIG, mergeThreshold: 0.92 });
117
- await engine.run("project:test");
118
-
119
- const finalA = JSON.parse((await store.getById("a"))!.metadata!) as Record<string, any>;
120
- const finalB = JSON.parse((await store.getById("b"))!.metadata!) as Record<string, any>;
121
- expect(typeof finalA.version_group).toBe("string");
122
- expect(finalB.version_group).toBe(finalA.version_group); // 同组,且都没被后续写抹掉
123
- expect(typeof finalA.version_rank).toBe("number");
124
- expect(typeof finalB.version_rank).toBe("number");
125
- expect(finalA.evolution.sourceMemories).toContain("b");
126
- expect(finalB.evolution.status).toBe("consolidated");
127
- expect(finalB.evolution.consolidatedInto).toBe("a");
128
- });
129
-
130
- it("Bug-1 回归:多 member merge 共享同一个 groupId,canonical 的 sourceMemories 不丢前面的 member", async () => {
131
- const entryA = makeEntry({ id: "a", text: "fact v1", vector: [1, 0, 0], importance: 0.9 });
132
- const entryB = makeEntry({ id: "b", text: "fact v2", vector: [0.99, 0.1, 0], importance: 0.5 });
133
- const entryC = makeEntry({ id: "c", text: "fact v3", vector: [0.98, 0.15, 0], importance: 0.4 });
134
- const simMap = new Map([
135
- ["a", new Map([["b", 0.95], ["c", 0.94]])],
136
- ["b", new Map([["a", 0.95], ["c", 0.93]])],
137
- ["c", new Map([["a", 0.94], ["b", 0.93]])],
138
- ]);
139
- const { store } = createMockStore([entryA, entryB, entryC], simMap);
140
- const engine = new ConsolidationEngine(store, { ...DEFAULT_CONSOLIDATION_CONFIG, mergeThreshold: 0.92 });
141
- await engine.run("project:test");
142
-
143
- const finalA = JSON.parse((await store.getById("a"))!.metadata!) as Record<string, any>;
144
- const finalB = JSON.parse((await store.getById("b"))!.metadata!) as Record<string, any>;
145
- const finalC = JSON.parse((await store.getById("c"))!.metadata!) as Record<string, any>;
146
- expect(typeof finalA.version_group).toBe("string");
147
- expect(finalB.version_group).toBe(finalA.version_group); // 旧路径这里各是一个新组
148
- expect(finalC.version_group).toBe(finalA.version_group);
149
- expect(finalA.evolution.sourceMemories).toEqual(expect.arrayContaining(["b", "c"])); // 旧路径只剩最后一个
150
- });
151
-
152
- it("link 分支回归:多 member 时 canonical 的 cluster_members 累积全部(不再只剩最后一个)", async () => {
153
- const entryA = makeEntry({ id: "a", text: "topic center", vector: [1, 0, 0], importance: 0.9 });
154
- const entryB = makeEntry({ id: "b", text: "related one", vector: [0.9, 0.3, 0], importance: 0.5 });
155
- const entryC = makeEntry({ id: "c", text: "related two", vector: [0.88, 0.35, 0], importance: 0.4 });
156
- // 0.85 落在 clusterThreshold(0.82) 与 mergeThreshold(0.92) 之间 → link 分支
157
- const simMap = new Map([
158
- ["a", new Map([["b", 0.85], ["c", 0.85]])],
159
- ["b", new Map([["a", 0.85], ["c", 0.84]])],
160
- ["c", new Map([["a", 0.85], ["b", 0.84]])],
161
- ]);
162
- const { store } = createMockStore([entryA, entryB, entryC], simMap);
163
- const engine = new ConsolidationEngine(store, { ...DEFAULT_CONSOLIDATION_CONFIG, clusterThreshold: 0.82, mergeThreshold: 0.92 });
164
- await engine.run("project:test");
165
-
166
- const finalA = JSON.parse((await store.getById("a"))!.metadata!) as Record<string, any>;
167
- const finalB = JSON.parse((await store.getById("b"))!.metadata!) as Record<string, any>;
168
- const finalC = JSON.parse((await store.getById("c"))!.metadata!) as Record<string, any>;
169
- expect(finalA.cluster_members).toEqual(expect.arrayContaining(["b", "c"]));
170
- expect(finalB.clustered_with).toBe("a");
171
- expect(finalC.clustered_with).toBe("a");
172
- });
173
-
174
- it("merges near-duplicates above mergeThreshold", async () => {
175
- const entryA = makeEntry({ id: "a", text: "I prefer TypeScript", vector: [1, 0, 0], importance: 0.9 });
176
- const entryB = makeEntry({ id: "b", text: "I prefer TypeScript language", vector: [0.99, 0.1, 0], importance: 0.5 });
177
-
178
- const simMap = new Map([
179
- ["a", new Map([["b", 0.95]])],
180
- ["b", new Map([["a", 0.95]])],
181
- ]);
182
-
183
- const { store, updates } = createMockStore([entryA, entryB], simMap);
184
- const engine = new ConsolidationEngine(store, { ...DEFAULT_CONSOLIDATION_CONFIG, mergeThreshold: 0.92 });
185
- const result = await engine.run("project:test");
186
-
187
- expect(result.clustersFound).toBe(1);
188
- expect(result.mergedCount).toBe(1);
189
- // Tier 3.3: Both entries now coexist in a version group instead of archiving.
190
- // Both A and B should have version_group metadata.
191
- const updateA = updates.find(u => u.id === "a");
192
- const updateB = updates.find(u => u.id === "b");
193
- expect(updateA).toBeTruthy();
194
- expect(updateB).toBeTruthy();
195
- const metaA = JSON.parse(updateA!.metadata);
196
- const metaB = JSON.parse(updateB!.metadata);
197
- expect(metaA.version_group).toBeTruthy();
198
- expect(metaB.version_group).toBe(metaA.version_group);
199
- // Canonical (A, higher importance) should have higher rank
200
- expect(metaA.version_rank).toBeGreaterThan(metaB.version_rank);
201
- });
202
-
203
- it("never clusters a live entry with its own superseded belief-history row", async () => {
204
- // A rephrased belief sits far above mergeThreshold from its archived version, and
205
- // canonicalScore (importance × access count, no recency) ties them exactly — the
206
- // history row inherits both. Losing that coin flip would mark the LIVE entry
207
- // consolidated, dropping the current belief out of default retrieval while the
208
- // abandoned wording stands in as canonical.
209
- const live = makeEntry({
210
- id: "live",
211
- text: "User prefers concise, code-first replies",
212
- vector: [1, 0, 0],
213
- });
214
- // Clustering is skipped outright when a category holds fewer than two ACTIVE entries,
215
- // so an unrelated second live entry is what makes this scenario reachable at all.
216
- const unrelated = makeEntry({
217
- id: "other",
218
- text: "Project uses Bun as the runtime",
219
- vector: [0, 0, 1],
220
- });
221
- const history = makeEntry({
222
- id: "hist",
223
- text: "User prefers concise, direct replies",
224
- vector: [0, 1, 0],
225
- metadata: JSON.stringify({
226
- evolution: { status: "superseded", validUntil: Date.now(), supersededBy: "live" },
227
- }),
228
- });
229
-
230
- const simMap = new Map([["live", new Map([["hist", 0.98]])]]);
231
-
232
- const { store, updates } = createMockStore([live, unrelated, history], simMap);
233
- const engine = new ConsolidationEngine(store, { ...DEFAULT_CONSOLIDATION_CONFIG, mergeThreshold: 0.92 });
234
- const result = await engine.run("project:test");
235
-
236
- expect(result.clustersFound).toBe(0);
237
- expect(result.mergedCount).toBe(0);
238
- // Above all: the live entry must not have been touched.
239
- expect(updates.find(u => u.id === "live")).toBeUndefined();
240
- });
241
-
242
- it("links related entries below mergeThreshold but above clusterThreshold", async () => {
243
- const entryA = makeEntry({ id: "a", text: "TypeScript config", vector: [1, 0, 0] });
244
- const entryB = makeEntry({ id: "b", text: "TypeScript setup", vector: [0.9, 0.1, 0] });
245
-
246
- const simMap = new Map([
247
- ["a", new Map([["b", 0.85]])],
248
- ["b", new Map([["a", 0.85]])],
249
- ]);
250
-
251
- const { store, updates } = createMockStore([entryA, entryB], simMap);
252
- const engine = new ConsolidationEngine(store, { ...DEFAULT_CONSOLIDATION_CONFIG, clusterThreshold: 0.82, mergeThreshold: 0.92 });
253
- const result = await engine.run("project:test");
254
-
255
- expect(result.clustersFound).toBe(1);
256
- expect(result.mergedCount).toBe(0);
257
- expect(result.relationsAdded).toBe(1);
258
- // Both should have clustering metadata
259
- const linkUpdate = updates.find(u => u.id === "b");
260
- expect(linkUpdate).toBeTruthy();
261
- const meta = JSON.parse(linkUpdate!.metadata);
262
- expect(meta.clustered_with).toBe("a");
263
- });
264
-
265
- it("detects heuristic contradictions", async () => {
266
- const entryA = makeEntry({ id: "a", text: "Always use strict mode in TypeScript projects", vector: [1, 0, 0] });
267
- const entryB = makeEntry({ id: "b", text: "Never use strict mode in TypeScript projects", vector: [0.98, 0.1, 0] });
268
-
269
- const simMap = new Map([
270
- ["a", new Map([["b", 0.95]])],
271
- ["b", new Map([["a", 0.95]])],
272
- ]);
273
-
274
- const { store } = createMockStore([entryA, entryB], simMap);
275
- const engine = new ConsolidationEngine(store, DEFAULT_CONSOLIDATION_CONFIG);
276
- const result = await engine.run("project:test");
277
-
278
- expect(result.conflictsDetected.length).toBe(1);
279
- expect(result.conflictsDetected[0].type).toBe("heuristic_contradiction");
280
- });
281
-
282
- it("skips archived entries", async () => {
283
- const entryA = makeEntry({ id: "a", text: "active entry here", vector: [1, 0, 0] });
284
- const entryB = makeEntry({ id: "b", text: "archived entry here", vector: [0.95, 0.1, 0], metadata: JSON.stringify({ evolution: { status: "archived" } }) });
285
-
286
- const { store } = createMockStore([entryA, entryB]);
287
- const engine = new ConsolidationEngine(store);
288
- const result = await engine.run("project:test");
289
-
290
- expect(result.originalCount).toBe(1); // only active
291
- });
292
-
293
- describe("KG triple evidence (second merge-evidence source)", () => {
294
- function createMockKGSource(byMemory: Record<string, ConsolidationTripleEvidence[]>) {
295
- return {
296
- async getTriplesBySourceMemories(memoryIds: string[]) {
297
- const result = new Map<string, ConsolidationTripleEvidence[]>();
298
- for (const id of memoryIds) {
299
- if (byMemory[id]) result.set(id, byMemory[id]);
300
- }
301
- return result;
302
- },
303
- };
304
- }
305
- const t = (id: string, mention = 1): ConsolidationTripleEvidence => ({ id, mention_count: mention });
306
-
307
- function greyZonePair() {
308
- const entryA = makeEntry({ id: "a", text: "Alice's main machine is the MacBook", vector: [1, 0, 0], importance: 0.9 });
309
- const entryB = makeEntry({ id: "b", text: "Alice uses a MacBook as her primary computer", vector: [0.9, 0.1, 0], importance: 0.5 });
310
- const simMap = new Map([
311
- ["a", new Map([["b", 0.85]])], // grey zone: above cluster 0.82, below merge 0.92
312
- ["b", new Map([["a", 0.85]])],
313
- ]);
314
- return { entryA, entryB, simMap };
315
- }
316
-
317
- it("merges a grey-zone pair when triple sets overlap", async () => {
318
- const { entryA, entryB, simMap } = greyZonePair();
319
- const kg = createMockKGSource({
320
- a: [t("t1"), t("t2")],
321
- b: [t("t1"), t("t2")], // Jaccard 1.0
322
- });
323
- const { store, updates } = createMockStore([entryA, entryB], simMap);
324
- const engine = new ConsolidationEngine(store, DEFAULT_CONSOLIDATION_CONFIG, kg);
325
- const result = await engine.run("project:test");
326
-
327
- expect(result.mergedCount).toBe(1);
328
- expect(result.tripleEvidenceMerges).toBe(1);
329
- expect(result.relationsAdded).toBe(0);
330
- const metaB = JSON.parse(updates.find(u => u.id === "b")!.metadata);
331
- expect(metaB.version_group).toBeTruthy();
332
- });
333
-
334
- it("does not merge a grey-zone pair when triple sets are disjoint", async () => {
335
- const { entryA, entryB, simMap } = greyZonePair();
336
- const kg = createMockKGSource({
337
- a: [t("t1"), t("t2")],
338
- b: [t("t3"), t("t4")], // Jaccard 0
339
- });
340
- const { store } = createMockStore([entryA, entryB], simMap);
341
- const engine = new ConsolidationEngine(store, DEFAULT_CONSOLIDATION_CONFIG, kg);
342
- const result = await engine.run("project:test");
343
-
344
- expect(result.mergedCount).toBe(0);
345
- expect(result.tripleEvidenceMerges).toBe(0);
346
- expect(result.relationsAdded).toBe(1); // falls back to link, current behavior
347
- });
348
-
349
- it("requires minTriplesForEvidence on both sides — a single shared triple is too weak", async () => {
350
- const { entryA, entryB, simMap } = greyZonePair();
351
- const kg = createMockKGSource({
352
- a: [t("t1")],
353
- b: [t("t1")], // overlap 1.0 but only one triple each — below default minTriplesForEvidence 2
354
- });
355
- const { store } = createMockStore([entryA, entryB], simMap);
356
- const engine = new ConsolidationEngine(store, DEFAULT_CONSOLIDATION_CONFIG, kg);
357
- const result = await engine.run("project:test");
358
-
359
- expect(result.mergedCount).toBe(0);
360
- expect(result.relationsAdded).toBe(1);
361
- });
362
-
363
- it("without a kgSource the grey zone links exactly as before", async () => {
364
- const { entryA, entryB, simMap } = greyZonePair();
365
- const { store } = createMockStore([entryA, entryB], simMap);
366
- const engine = new ConsolidationEngine(store, DEFAULT_CONSOLIDATION_CONFIG);
367
- const result = await engine.run("project:test");
368
-
369
- expect(result.mergedCount).toBe(0);
370
- expect(result.tripleEvidenceMerges).toBe(0);
371
- expect(result.relationsAdded).toBe(1);
372
- });
373
-
374
- it("mention frequency boosts canonical selection", async () => {
375
- // Same importance — the mention boost must be what flips the canonical
376
- const entryA = makeEntry({ id: "a", text: "fact mentioned once", vector: [1, 0, 0], importance: 0.7 });
377
- const entryB = makeEntry({ id: "b", text: "fact mentioned many times", vector: [0.99, 0.1, 0], importance: 0.7 });
378
- const simMap = new Map([
379
- ["a", new Map([["b", 0.95]])], // merge zone
380
- ["b", new Map([["a", 0.95]])],
381
- ]);
382
- const kg = createMockKGSource({
383
- a: [t("ta", 1), t("tx", 1)],
384
- b: [t("tb", 9), t("ty", 1)], // b carries a fact mentioned 9 times → higher canonical score
385
- });
386
- const { store, updates } = createMockStore([entryA, entryB], simMap);
387
- const engine = new ConsolidationEngine(store, DEFAULT_CONSOLIDATION_CONFIG, kg);
388
- const result = await engine.run("project:test");
389
-
390
- expect(result.mergedCount).toBe(1);
391
- // B is canonical (the boost flipped the tie): A is the member, marked
392
- // consolidatedInto B. version_rank can't witness this — computeVersionRank
393
- // ignores the engine's canonical pick when importance ties.
394
- const finalMetaA = JSON.parse(updates.filter(u => u.id === "a").at(-1)!.metadata);
395
- expect(finalMetaA.evolution?.consolidatedInto).toBe("b");
396
- // And B was never marked consolidated into anything
397
- const bUpdates = updates.filter(u => u.id === "b").map(u => JSON.parse(u.metadata));
398
- expect(bUpdates.every(m => !m.evolution?.consolidatedInto)).toBe(true);
399
- });
400
-
401
- it("mention boost must NOT override a clear importance gap (tie-breaker only)", async () => {
402
- // A is substantially more important; B carries an extremely frequent triple.
403
- // The capped boost (≤1.1) must not demote A to consolidated status.
404
- const entryA = makeEntry({ id: "a", text: "the important synthesis", vector: [1, 0, 0], importance: 0.9 });
405
- const entryB = makeEntry({ id: "b", text: "minor note repeating a hot fact", vector: [0.99, 0.1, 0], importance: 0.5 });
406
- const simMap = new Map([
407
- ["a", new Map([["b", 0.95]])],
408
- ["b", new Map([["a", 0.95]])],
409
- ]);
410
- const kg = createMockKGSource({
411
- a: [],
412
- b: [t("hot", 500), t("tb", 1)], // absurdly frequent fact on the weak side
413
- });
414
- const { store, updates } = createMockStore([entryA, entryB], simMap);
415
- const engine = new ConsolidationEngine(store, DEFAULT_CONSOLIDATION_CONFIG, kg);
416
- const result = await engine.run("project:test");
417
-
418
- expect(result.mergedCount).toBe(1);
419
- // A stays canonical: B is the one marked consolidatedInto A
420
- const finalMetaB = JSON.parse(updates.filter(u => u.id === "b").at(-1)!.metadata);
421
- expect(finalMetaB.evolution?.consolidatedInto).toBe("a");
422
- const aUpdates = updates.filter(u => u.id === "a").map(u => JSON.parse(u.metadata));
423
- expect(aUpdates.every(m => !m.evolution?.consolidatedInto)).toBe(true);
424
- });
425
- });
426
- });
427
-
428
- describe("tripleJaccard", () => {
429
- const set = (...ids: string[]) => new Set(ids);
430
-
431
- it("computes intersection over union", () => {
432
- expect(tripleJaccard(set("a", "b"), set("a", "b"))).toBe(1);
433
- expect(tripleJaccard(set("a", "b"), set("b", "c"))).toBeCloseTo(1 / 3);
434
- expect(tripleJaccard(set("a", "b"), set("c", "d"))).toBe(0);
435
- });
436
-
437
- it("returns 0 below the min-size floor (either side)", () => {
438
- expect(tripleJaccard(set("a"), set("a"))).toBe(0); // default minSize 2
439
- expect(tripleJaccard(set("a"), set("a"), 1)).toBe(1);
440
- expect(tripleJaccard(undefined, set("a", "b"))).toBe(0);
441
- expect(tripleJaccard(set("a", "b"), undefined)).toBe(0);
442
- });
443
- });
444
-
445
- describe("formatConsolidationResult", () => {
446
- it("formats a result with conflicts", () => {
447
- const result: ConsolidationResult = {
448
- originalCount: 100,
449
- clustersFound: 5,
450
- mergedCount: 3,
451
- relationsAdded: 7,
452
- tripleEvidenceMerges: 1,
453
- conflictsDetected: [{ memoryA: "aaaa-bbbb", memoryB: "cccc-dddd", type: "heuristic_contradiction" }],
454
- scope: "project:test",
455
- };
456
- const text = formatConsolidationResult(result);
457
- expect(text).toContain("Scanned: 100");
458
- expect(text).toContain("Clusters found: 5");
459
- expect(text).toContain("Merged (versioned): 3");
460
- expect(text).toContain("Conflicts:");
461
- });
462
- });
463
-
464
- // ---------------------------------------------------------------------------
465
- // computeSynthesisUptake (Artel synthesis_uptake_rate 对应物)
466
- // ---------------------------------------------------------------------------
467
-
468
- import { computeSynthesisUptake } from "../consolidation-engine.js";
469
- import type { MemoryEntry as UptakeEntry } from "../store.js";
470
-
471
- function uptakeEntry(id: string, metadata: Record<string, unknown>): UptakeEntry {
472
- return {
473
- id,
474
- text: `t-${id}`,
475
- vector: [],
476
- category: "patterns",
477
- scope: "project:test",
478
- importance: 0.7,
479
- timestamp: Date.now(),
480
- metadata: JSON.stringify(metadata),
481
- } as UptakeEntry;
482
- }
483
-
484
- function pagedStore(all: UptakeEntry[]) {
485
- return {
486
- async listPage({ limit = 1000, offset = 0 }: { limit?: number; offset?: number; includeVector?: boolean }) {
487
- return all.slice(offset, offset + limit);
488
- },
489
- };
490
- }
491
-
492
- describe("computeSynthesisUptake", () => {
493
- it("computes uptake over derived insights only", async () => {
494
- const store = pagedStore([
495
- uptakeEntry("d1", { cluster_insight: true, accessCount: 2 }), // derived, read
496
- uptakeEntry("d2", { cross_memory_pattern: true }), // derived, unread
497
- uptakeEntry("n1", { accessCount: 5 }), // not derived
498
- ]);
499
- const s = await computeSynthesisUptake(store, 20_000, 2);
500
- expect(s.scanned).toBe(3);
501
- expect(s.derivedTotal).toBe(2);
502
- expect(s.derivedRead).toBe(1);
503
- expect(s.uptakeRate).toBeCloseTo(0.5, 5);
504
- expect(s.truncated).toBe(false);
505
- });
506
-
507
- it("returns null rate when no derived insights exist", async () => {
508
- const s = await computeSynthesisUptake(pagedStore([uptakeEntry("n1", {})]));
509
- expect(s.derivedTotal).toBe(0);
510
- expect(s.uptakeRate).toBeNull();
511
- });
512
-
513
- it("respects scan cap and reports truncation", async () => {
514
- const all = Array.from({ length: 10 }, (_, i) => uptakeEntry(`e${i}`, { cluster_insight: true, accessCount: 1 }));
515
- const s = await computeSynthesisUptake(pagedStore(all), 4, 2);
516
- expect(s.scanned).toBe(4);
517
- expect(s.truncated).toBe(true);
518
- expect(s.derivedTotal).toBe(4);
519
- });
520
- });