@modusensus/dsh-mneme 0.6.7 → 0.6.9

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 (139) hide show
  1. package/.github/workflows/test.yml +32 -0
  2. package/.release-notes-v0.6.9.md +13 -0
  3. package/CHANGELOG.md +89 -0
  4. package/LICENSE +21 -21
  5. package/README.md +219 -463
  6. package/SECURITY.md +544 -0
  7. package/docs/devlog/2026-08-14-dsh-mneme-dev-log.md +247 -0
  8. package/docs/devlog/2026-08-15-dsh-mneme-audit-stress-dev-log.md +145 -0
  9. package/docs/devlog/2026-08-15-dsh-mneme-pipeline-dev-log.md +56 -0
  10. package/docs/devlog/2026-08-15-dsh-mneme-reflection-dev-log.md +77 -0
  11. package/docs/devlog/2026-08-15-dsh-mneme-review-fixes-dev-log.md +64 -0
  12. package/docs/devlog/2026-08-15-dsh-mneme-semantic-dev-log.md +90 -0
  13. package/dsh-mneme/CHANGELOG.md +248 -0
  14. package/dsh-mneme/LICENSE +21 -0
  15. package/dsh-mneme/README.md +465 -0
  16. package/{cordis.patch.yml → dsh-mneme/cordis.patch.yml} +15 -15
  17. package/dsh-mneme/docs/AGENT_MEMORY_RESEARCH.md +183 -0
  18. package/dsh-mneme/docs/ENTITIES.md +245 -0
  19. package/dsh-mneme/docs/LOCAL_MODEL.md +141 -0
  20. package/dsh-mneme/docs/MIGRATION.md +127 -0
  21. package/dsh-mneme/docs/SEMANTIC.md +256 -0
  22. package/dsh-mneme/docs/SLEEP.md +163 -0
  23. package/{lib → dsh-mneme/lib}/api.js +783 -783
  24. package/{lib → dsh-mneme/lib}/client.js +1757 -1757
  25. package/{src → dsh-mneme/lib}/commands.js +64 -64
  26. package/{lib → dsh-mneme/lib}/config.js +298 -288
  27. package/{lib → dsh-mneme/lib}/dream/clustering.js +118 -118
  28. package/{src → dsh-mneme/lib}/dream/decisions.js +488 -439
  29. package/{lib → dsh-mneme/lib}/dream/sleep.js +561 -554
  30. package/{src → dsh-mneme/lib}/dream/tag-extractor.js +156 -156
  31. package/{lib → dsh-mneme/lib}/dream.js +958 -929
  32. package/{src → dsh-mneme/lib}/embedding.js +154 -154
  33. package/{src → dsh-mneme/lib}/entities/extractor.js +242 -242
  34. package/{src → dsh-mneme/lib}/hot-memory.js +53 -53
  35. package/{lib → dsh-mneme/lib}/index.js +361 -361
  36. package/{src → dsh-mneme/lib}/inject.js +208 -208
  37. package/{lib → dsh-mneme/lib}/local-embedder.js +282 -282
  38. package/{lib → dsh-mneme/lib}/mirror.js +170 -170
  39. package/{lib → dsh-mneme/lib}/parser/tag.js +59 -59
  40. package/{lib → dsh-mneme/lib}/parser/wiki-link.js +38 -38
  41. package/{src → dsh-mneme/lib}/quality-filter.js +123 -123
  42. package/{lib → dsh-mneme/lib}/reranker.js +218 -218
  43. package/{lib → dsh-mneme/lib}/search/adaptive.js +22 -22
  44. package/{lib → dsh-mneme/lib}/search/bm25.js +96 -96
  45. package/{src → dsh-mneme/lib}/search/tag-boost.js +61 -61
  46. package/{src → dsh-mneme/lib}/service.js +1726 -1726
  47. package/{lib → dsh-mneme/lib}/settings.js +172 -172
  48. package/{lib → dsh-mneme/lib}/store.js +2238 -2238
  49. package/{lib → dsh-mneme/lib}/summarize.js +236 -236
  50. package/{lib → dsh-mneme/lib}/tools.js +290 -290
  51. package/{lib → dsh-mneme/lib}/vector-index.js +116 -116
  52. package/dsh-mneme/package-lock.json +1936 -0
  53. package/dsh-mneme/package.json +80 -0
  54. package/{scripts → dsh-mneme/scripts}/benchmark-embed.js +201 -201
  55. package/{scripts → dsh-mneme/scripts}/benchmark-recall.js +133 -133
  56. package/{scripts → dsh-mneme/scripts}/benchmark-rerank.js +166 -166
  57. package/{scripts → dsh-mneme/scripts}/e2e-dsh.js +218 -218
  58. package/{scripts → dsh-mneme/scripts}/stress-dsh.js +255 -255
  59. package/{scripts → dsh-mneme/scripts}/sync-lib.js +52 -52
  60. package/{src → dsh-mneme/src}/api.js +783 -783
  61. package/{lib → dsh-mneme/src}/commands.js +64 -64
  62. package/{src → dsh-mneme/src}/config.js +298 -288
  63. package/{src → dsh-mneme/src}/dream/clustering.js +118 -118
  64. package/{lib → dsh-mneme/src}/dream/decisions.js +488 -439
  65. package/{src → dsh-mneme/src}/dream/sleep.js +561 -554
  66. package/{lib → dsh-mneme/src}/dream/tag-extractor.js +156 -156
  67. package/{src → dsh-mneme/src}/dream.js +958 -929
  68. package/{lib → dsh-mneme/src}/embedding.js +154 -154
  69. package/{lib → dsh-mneme/src}/entities/extractor.js +242 -242
  70. package/{lib → dsh-mneme/src}/hot-memory.js +53 -53
  71. package/{src → dsh-mneme/src}/index.js +361 -361
  72. package/{lib → dsh-mneme/src}/inject.js +208 -208
  73. package/{src → dsh-mneme/src}/local-embedder.js +282 -282
  74. package/{src → dsh-mneme/src}/mirror.js +170 -170
  75. package/{src → dsh-mneme/src}/parser/tag.js +59 -59
  76. package/{src → dsh-mneme/src}/parser/wiki-link.js +38 -38
  77. package/{lib → dsh-mneme/src}/quality-filter.js +123 -123
  78. package/{src → dsh-mneme/src}/reranker.js +218 -218
  79. package/{src → dsh-mneme/src}/search/adaptive.js +22 -22
  80. package/{src → dsh-mneme/src}/search/bm25.js +96 -96
  81. package/{lib → dsh-mneme/src}/search/tag-boost.js +61 -61
  82. package/{lib → dsh-mneme/src}/service.js +1726 -1726
  83. package/{src → dsh-mneme/src}/settings.js +172 -172
  84. package/{src → dsh-mneme/src}/store.js +2238 -2238
  85. package/{src → dsh-mneme/src}/summarize.js +236 -236
  86. package/{src → dsh-mneme/src}/tools.js +290 -290
  87. package/{src → dsh-mneme/src}/vector-index.js +116 -116
  88. package/{test → dsh-mneme/test}/api.test.js +594 -594
  89. package/{test → dsh-mneme/test}/audit.test.js +448 -448
  90. package/{test → dsh-mneme/test}/benchmark.test.js +35 -35
  91. package/{test → dsh-mneme/test}/boundary-v0625.test.js +82 -82
  92. package/{test → dsh-mneme/test}/client.test.js +368 -368
  93. package/{test → dsh-mneme/test}/clustering.test.js +100 -100
  94. package/{test → dsh-mneme/test}/commands.test.js +69 -69
  95. package/{test → dsh-mneme/test}/config.test.js +50 -50
  96. package/{test → dsh-mneme/test}/conflict-freeze.test.js +290 -290
  97. package/{test → dsh-mneme/test}/directory.test.js +134 -134
  98. package/{test → dsh-mneme/test}/dream.test.js +1060 -901
  99. package/{test → dsh-mneme/test}/entities.test.js +522 -522
  100. package/{test → dsh-mneme/test}/epistemic.test.js +298 -298
  101. package/{test → dsh-mneme/test}/fnew-0112.test.js +311 -311
  102. package/{test → dsh-mneme/test}/fnew-03.test.js +422 -422
  103. package/{test → dsh-mneme/test}/graph-api.test.js +175 -175
  104. package/{test → dsh-mneme/test}/helpers/dream-mock.js +82 -82
  105. package/{test → dsh-mneme/test}/hot-memory.test.js +174 -174
  106. package/{test → dsh-mneme/test}/inject.test.js +103 -103
  107. package/{test → dsh-mneme/test}/llm-audit.test.js +279 -279
  108. package/{test → dsh-mneme/test}/local-embedder.test.js +227 -227
  109. package/{test → dsh-mneme/test}/mirror-dirty.test.js +424 -424
  110. package/{test → dsh-mneme/test}/mirror-edit-digest.test.js +187 -187
  111. package/{test → dsh-mneme/test}/mirror-generation.test.js +499 -499
  112. package/{test → dsh-mneme/test}/mirror.test.js +249 -249
  113. package/{test → dsh-mneme/test}/normalize-decisions.test.js +120 -120
  114. package/{test → dsh-mneme/test}/peer-blockers.test.js +190 -190
  115. package/{test → dsh-mneme/test}/policy-epoch.test.js +259 -259
  116. package/{test → dsh-mneme/test}/provenance.test.js +103 -103
  117. package/{test → dsh-mneme/test}/quality-filter.test.js +118 -118
  118. package/{test → dsh-mneme/test}/reasoning-effort.test.js +199 -199
  119. package/{test → dsh-mneme/test}/recall-evals.test.js +235 -235
  120. package/{test → dsh-mneme/test}/recall-layer.test.js +315 -315
  121. package/{test → dsh-mneme/test}/receipt-chain.test.js +451 -451
  122. package/{test → dsh-mneme/test}/reflection.test.js +226 -226
  123. package/{test → dsh-mneme/test}/reranker.test.js +240 -240
  124. package/{test → dsh-mneme/test}/search-fusion.test.js +90 -90
  125. package/{test → dsh-mneme/test}/semantic.test.js +124 -124
  126. package/{test → dsh-mneme/test}/service-search.test.js +199 -199
  127. package/{test → dsh-mneme/test}/service.test.js +435 -435
  128. package/{test → dsh-mneme/test}/settings.test.js +118 -118
  129. package/{test → dsh-mneme/test}/sleep.test.js +365 -365
  130. package/{test → dsh-mneme/test}/store.test.js +436 -436
  131. package/{test → dsh-mneme/test}/stress.test.js +209 -209
  132. package/{test → dsh-mneme/test}/summarize.test.js +191 -191
  133. package/{test → dsh-mneme/test}/tag-boost.test.js +125 -125
  134. package/{test → dsh-mneme/test}/tag.test.js +312 -312
  135. package/{test → dsh-mneme/test}/tools.test.js +285 -285
  136. package/{test → dsh-mneme/test}/vector-index.test.js +221 -221
  137. package/{test → dsh-mneme/test}/wiki-link.test.js +332 -332
  138. package/package.json +18 -40
  139. package//346/250/252/345/271/205.png +0 -0
@@ -1,235 +1,235 @@
1
- import test from "node:test";
2
- import assert from "node:assert/strict";
3
- import { DatabaseSync } from "node:sqlite";
4
- import { mkdtempSync, rmSync } from "node:fs";
5
- import { tmpdir } from "node:os";
6
- import { join } from "node:path";
7
- import { createStore } from "../src/store.js";
8
- import { createService } from "../src/service.js";
9
- import { Config } from "../src/config.js";
10
-
11
- // Mock embedder: every query maps to the fixed vector [1,0,0], so vector recall
12
- // surfaces any row embedded at [1,0,0] and excludes orthogonal ones.
13
- const embedder = {
14
- embedSingle: async () => [1, 0, 0],
15
- embed: async () => [1, 0, 0],
16
- schedule: () => {},
17
- modelHash: "eval#mock",
18
- dimension: 3
19
- };
20
-
21
- function setup(config = {}) {
22
- const store = createStore(":memory:");
23
- const service = createService({ store, mirror: null, config });
24
- return { store, service };
25
- }
26
-
27
- function saveMemory(service, title, content) {
28
- return service.saveWithDedupe({ type: "preference", title, content, importance: 5 }).memory;
29
- }
30
-
31
- // ---------------------------------------------------------------- schema / config
32
-
33
- test("config: evalPersistTestResults defaults to false (opt-in)", () => {
34
- assert.equal(Config({}).evalPersistTestResults, false, "off by default");
35
- assert.equal(Config({ evalPersistTestResults: true }).evalPersistTestResults, true, "explicit opt-in");
36
- });
37
-
38
- test("schema: recall_evals table exists with the expected columns", () => {
39
- const store = createStore(":memory:");
40
- const cols = store.db.prepare("PRAGMA table_info(recall_evals)").all().map((c) => c.name);
41
- for (const col of ["id", "recall_run_id", "query", "expected_ids", "actual_ids", "metrics", "eval_type", "created_at"]) {
42
- assert.ok(cols.includes(col), `column ${col} present`);
43
- }
44
- // FK clause is declared against recall_runs.
45
- const fks = store.db.prepare("PRAGMA foreign_key_list(recall_evals)").all();
46
- assert.ok(fks.some((fk) => fk.table === "recall_runs" && fk.from === "recall_run_id"), "FK to recall_runs(id) declared");
47
- store.close();
48
- });
49
-
50
- test("legacy DB without recall_evals is upgraded idempotently on open", () => {
51
- const dir = mkdtempSync(join(tmpdir(), "dsh-mneme-recall-evals-"));
52
- const dbPath = join(dir, "memory.db");
53
- try {
54
- const old = new DatabaseSync(dbPath);
55
- old.exec(`
56
- CREATE TABLE recall_runs (
57
- id TEXT PRIMARY KEY, query TEXT NOT NULL, mode TEXT NOT NULL,
58
- top_k INTEGER, threshold REAL, candidates TEXT NOT NULL, created_at TEXT NOT NULL
59
- );
60
- INSERT INTO recall_runs (id, query, mode, candidates, created_at) VALUES ('r1', '旧', 'keyword', '[]', 't');
61
- `);
62
- old.close();
63
- const store = createStore(dbPath);
64
- const cols = store.db.prepare("PRAGMA table_info(recall_evals)").all().map((c) => c.name);
65
- assert.ok(cols.includes("id"), "recall_evals created on a legacy DB");
66
- assert.equal(store.getRecallRun("r1").query, "旧", "legacy recall_runs row preserved");
67
- store.close();
68
- } finally {
69
- rmSync(dir, { recursive: true, force: true });
70
- }
71
- });
72
-
73
- // ---------------------------------------------------------------- switch-off / switch-on
74
-
75
- test("switch off: evaluateRetrieval computes metrics but writes nothing", async () => {
76
- const { store, service } = setup({}); // evalPersistTestResults defaults false
77
- const m = saveMemory(service, "量子计算入门", "叠加态");
78
- const res = await service.evaluateRetrieval("量子", [m.id], { mode: "keyword", topK: 10 });
79
- assert.ok(res.metrics.precision >= 0 && res.metrics.precision <= 1, "metrics computed");
80
- assert.deepEqual(res.actualIds, [m.id], "retrieval ran and returned the memory");
81
- assert.equal(res.persisted, false, "no persistence when switch is off");
82
- assert.deepEqual(store.listRecallEvals(), [], "recall_evals stays empty");
83
- store.close();
84
- });
85
-
86
- test("switch on: evaluateRetrieval persists a recall_evals snapshot", async () => {
87
- const { store, service } = setup({ evalPersistTestResults: true });
88
- const m = saveMemory(service, "量子计算入门", "叠加态");
89
- const res = await service.evaluateRetrieval("量子", [m.id], { mode: "keyword", topK: 10, evalType: "regression" });
90
- assert.equal(res.persisted, true, "snapshot persisted");
91
- const evals = store.listRecallEvals();
92
- assert.equal(evals.length, 1, "one eval row");
93
- const row = evals[0];
94
- assert.equal(row.query, "量子");
95
- assert.deepEqual(row.expected_ids, [m.id], "expected ids round-trip");
96
- assert.deepEqual(row.actual_ids, [m.id], "actual ids round-trip");
97
- assert.equal(row.eval_type, "regression");
98
- assert.ok(row.metrics && typeof row.metrics.precision === "number", "metrics JSON round-trips");
99
- assert.ok(typeof row.created_at === "string" && row.created_at.length > 0, "timestamp captured");
100
- // Idempotent on id: the same logical eval id replays without duplicates.
101
- store.saveRecallEval({ id: "ev-x", query: "q", expected_ids: [], actual_ids: [], metrics: {}, eval_type: "manual" });
102
- store.saveRecallEval({ id: "ev-x", query: "q2", expected_ids: [], actual_ids: [], metrics: {}, eval_type: "manual" });
103
- assert.equal(store.listRecallEvals().filter((e) => e.id === "ev-x").length, 1, "replay overwrites, no duplicate");
104
- store.close();
105
- });
106
-
107
- test("persist override: call-level persist:true writes even with the switch off", async () => {
108
- const { store, service } = setup({}); // switch off
109
- const m = saveMemory(service, "量子计算入门", "叠加态");
110
- const res = await service.evaluateRetrieval("量子", [m.id], { mode: "keyword", persist: true });
111
- assert.equal(res.persisted, true, "explicit persist override honored");
112
- assert.equal(store.listRecallEvals().length, 1);
113
- store.close();
114
- });
115
-
116
- test("persist override: call-level persist:false suppresses even with the switch on", async () => {
117
- const { store, service } = setup({ evalPersistTestResults: true });
118
- saveMemory(service, "量子计算入门", "叠加态");
119
- const res = await service.evaluateRetrieval("量子", [], { mode: "keyword", persist: false });
120
- assert.equal(res.persisted, false, "explicit opt-out honored");
121
- assert.deepEqual(store.listRecallEvals(), [], "nothing written");
122
- store.close();
123
- });
124
-
125
- // ---------------------------------------------------------------- metrics correctness
126
-
127
- test("metrics: computeRetrievalMetrics is exact for known inputs", () => {
128
- const { service } = setup();
129
- // a,b,c retrieved; a,x expected → 1 relevant at rank 1.
130
- assert.deepEqual(
131
- service.computeRetrievalMetrics(["a", "b", "c"], ["a", "x"]),
132
- { precision: 0.3333, recall: 0.5, mrr: 1, hit_count: 1 }
133
- );
134
- // relevant at rank 3 → mrr 1/3.
135
- assert.deepEqual(
136
- service.computeRetrievalMetrics(["x", "y", "a"], ["a", "b"]),
137
- { precision: 0.3333, recall: 0.5, mrr: 0.3333, hit_count: 1 }
138
- );
139
- // empty retrieval → zero metrics, no divide-by-zero.
140
- assert.deepEqual(
141
- service.computeRetrievalMetrics([], ["a", "b"]),
142
- { precision: 0, recall: 0, mrr: 0, hit_count: 0 }
143
- );
144
- // everything relevant, nothing missed → perfect scores.
145
- assert.deepEqual(
146
- service.computeRetrievalMetrics(["a", "b"], ["a", "b"]),
147
- { precision: 1, recall: 1, mrr: 1, hit_count: 2 }
148
- );
149
- // extra noise harms precision but not recall.
150
- assert.deepEqual(
151
- service.computeRetrievalMetrics(["a", "b", "c", "d"], ["a"]),
152
- { precision: 0.25, recall: 1, mrr: 1, hit_count: 1 }
153
- );
154
- });
155
-
156
- test("metrics: integration — partial hit scores precision/recall/mrr from real recall", async () => {
157
- const { store, service } = setup({ evalPersistTestResults: true });
158
- const hit = saveMemory(service, "量子计算入门", "叠加态");
159
- saveMemory(service, "量子纠缠", "贝尔态");
160
- saveMemory(service, "猫咪饲养", "喂食");
161
- const res = await service.evaluateRetrieval("量子", [hit.id], { mode: "keyword", topK: 10 });
162
- // Two literal 量子 hits retrieved, one relevant → precision 1/2, recall 1/1.
163
- // Title-tied, equal-importance rows order by updated_at DESC, so the later
164
- // saved 量子纠缠 ranks first and the relevant row is at rank 2 → mrr 1/2.
165
- assert.equal(res.metrics.hit_count, 1);
166
- assert.equal(res.metrics.precision, 0.5);
167
- assert.equal(res.metrics.recall, 1);
168
- assert.equal(res.metrics.mrr, 0.5);
169
- const row = store.listRecallEvals()[0];
170
- assert.equal(row.metrics.precision, 0.5, "persisted metrics match");
171
- store.close();
172
- });
173
-
174
- // ---------------------------------------------------------------- FK linkage
175
-
176
- test("FK: recordRecall=true links the eval to the recall_runs audit row", async () => {
177
- const { store, service } = setup({ evalPersistTestResults: true });
178
- const m = saveMemory(service, "量子计算入门", "叠加态");
179
- const res = await service.evaluateRetrieval("量子", [m.id], { mode: "keyword", topK: 5, recordRecall: true });
180
- assert.ok(res.recallRunId, "a recall run was recorded for the same scene");
181
- assert.equal(store.listRecallRuns().length, 1, "exactly one recall_runs row");
182
- const run = store.getRecallRun(res.recallRunId);
183
- assert.equal(run.query, "量子");
184
- const evals = store.listRecallEvals();
185
- assert.equal(evals.length, 1);
186
- assert.equal(evals[0].recall_run_id, res.recallRunId, "eval links to the recorded run");
187
- store.close();
188
- });
189
-
190
- test("FK: explicit recallRunId is preserved — recordRecall never clobbers it (regression)", async () => {
191
- const { store, service } = setup({ evalPersistTestResults: true });
192
- const m = saveMemory(service, "量子计算入门", "叠加态");
193
- // Pre-existing audit run the evaluator wants to link against.
194
- const run = store.saveRecallRun({
195
- query: "量子", mode: "keyword", topK: 5, candidates: [], created_at: new Date().toISOString()
196
- });
197
- // recordRecall=true alongside an explicit recallRunId: the explicit link wins,
198
- // and NO extra recall_runs row is minted.
199
- const res = await service.evaluateRetrieval("量子", [m.id], { mode: "keyword", recordRecall: true, recallRunId: run.id });
200
- assert.equal(res.recallRunId, run.id, "explicit recallRunId preserved");
201
- assert.equal(store.listRecallRuns().length, 1, "no duplicate recall_runs row minted");
202
- const evals = store.listRecallEvals();
203
- assert.equal(evals[0].recall_run_id, run.id, "eval links to the pre-existing run");
204
- store.close();
205
- });
206
-
207
- test("FK: recordRecall=false leaves recall_run_id null and writes no recall_runs row", async () => {
208
- const { store, service } = setup({ evalPersistTestResults: true });
209
- const m = saveMemory(service, "量子计算入门", "叠加态");
210
- const res = await service.evaluateRetrieval("量子", [m.id], { mode: "keyword" });
211
- assert.equal(res.recallRunId, null, "no run recorded by default");
212
- assert.deepEqual(store.listRecallRuns(), [], "recall_runs untouched by evals");
213
- const row = store.listRecallEvals()[0];
214
- assert.ok(!row.recall_run_id, "eval row has no recall_run_id");
215
- store.close();
216
- });
217
-
218
- // ---------------------------------------------------------------- production isolation
219
-
220
- test("production search never writes recall_evals, even with the switch on", async () => {
221
- const { store, service } = setup({ evalPersistTestResults: true });
222
- // Mimic src/index.js wiring: the recall recorder persists to recall_runs.
223
- service.setRecallRecorder((recall) => {
224
- store.saveRecallRun({
225
- query: recall.query, mode: recall.mode, topK: recall.topK, threshold: recall.threshold ?? null,
226
- candidates: recall.candidates ?? [], created_at: recall.createdAt
227
- });
228
- });
229
- saveMemory(service, "量子计算入门", "叠加态");
230
- const rows = await service.searchMemories("量子", { mode: "keyword", recordRecall: true });
231
- assert.ok(rows.length >= 1, "search returned results");
232
- assert.equal(store.listRecallRuns().length, 1, "production audit lands in recall_runs");
233
- assert.deepEqual(store.listRecallEvals(), [], "recall_evals stays untouched by production search");
234
- store.close();
235
- });
1
+ import test from "node:test";
2
+ import assert from "node:assert/strict";
3
+ import { DatabaseSync } from "node:sqlite";
4
+ import { mkdtempSync, rmSync } from "node:fs";
5
+ import { tmpdir } from "node:os";
6
+ import { join } from "node:path";
7
+ import { createStore } from "../src/store.js";
8
+ import { createService } from "../src/service.js";
9
+ import { Config } from "../src/config.js";
10
+
11
+ // Mock embedder: every query maps to the fixed vector [1,0,0], so vector recall
12
+ // surfaces any row embedded at [1,0,0] and excludes orthogonal ones.
13
+ const embedder = {
14
+ embedSingle: async () => [1, 0, 0],
15
+ embed: async () => [1, 0, 0],
16
+ schedule: () => {},
17
+ modelHash: "eval#mock",
18
+ dimension: 3
19
+ };
20
+
21
+ function setup(config = {}) {
22
+ const store = createStore(":memory:");
23
+ const service = createService({ store, mirror: null, config });
24
+ return { store, service };
25
+ }
26
+
27
+ function saveMemory(service, title, content) {
28
+ return service.saveWithDedupe({ type: "preference", title, content, importance: 5 }).memory;
29
+ }
30
+
31
+ // ---------------------------------------------------------------- schema / config
32
+
33
+ test("config: evalPersistTestResults defaults to false (opt-in)", () => {
34
+ assert.equal(Config({}).evalPersistTestResults, false, "off by default");
35
+ assert.equal(Config({ evalPersistTestResults: true }).evalPersistTestResults, true, "explicit opt-in");
36
+ });
37
+
38
+ test("schema: recall_evals table exists with the expected columns", () => {
39
+ const store = createStore(":memory:");
40
+ const cols = store.db.prepare("PRAGMA table_info(recall_evals)").all().map((c) => c.name);
41
+ for (const col of ["id", "recall_run_id", "query", "expected_ids", "actual_ids", "metrics", "eval_type", "created_at"]) {
42
+ assert.ok(cols.includes(col), `column ${col} present`);
43
+ }
44
+ // FK clause is declared against recall_runs.
45
+ const fks = store.db.prepare("PRAGMA foreign_key_list(recall_evals)").all();
46
+ assert.ok(fks.some((fk) => fk.table === "recall_runs" && fk.from === "recall_run_id"), "FK to recall_runs(id) declared");
47
+ store.close();
48
+ });
49
+
50
+ test("legacy DB without recall_evals is upgraded idempotently on open", () => {
51
+ const dir = mkdtempSync(join(tmpdir(), "dsh-mneme-recall-evals-"));
52
+ const dbPath = join(dir, "memory.db");
53
+ try {
54
+ const old = new DatabaseSync(dbPath);
55
+ old.exec(`
56
+ CREATE TABLE recall_runs (
57
+ id TEXT PRIMARY KEY, query TEXT NOT NULL, mode TEXT NOT NULL,
58
+ top_k INTEGER, threshold REAL, candidates TEXT NOT NULL, created_at TEXT NOT NULL
59
+ );
60
+ INSERT INTO recall_runs (id, query, mode, candidates, created_at) VALUES ('r1', '旧', 'keyword', '[]', 't');
61
+ `);
62
+ old.close();
63
+ const store = createStore(dbPath);
64
+ const cols = store.db.prepare("PRAGMA table_info(recall_evals)").all().map((c) => c.name);
65
+ assert.ok(cols.includes("id"), "recall_evals created on a legacy DB");
66
+ assert.equal(store.getRecallRun("r1").query, "旧", "legacy recall_runs row preserved");
67
+ store.close();
68
+ } finally {
69
+ rmSync(dir, { recursive: true, force: true });
70
+ }
71
+ });
72
+
73
+ // ---------------------------------------------------------------- switch-off / switch-on
74
+
75
+ test("switch off: evaluateRetrieval computes metrics but writes nothing", async () => {
76
+ const { store, service } = setup({}); // evalPersistTestResults defaults false
77
+ const m = saveMemory(service, "量子计算入门", "叠加态");
78
+ const res = await service.evaluateRetrieval("量子", [m.id], { mode: "keyword", topK: 10 });
79
+ assert.ok(res.metrics.precision >= 0 && res.metrics.precision <= 1, "metrics computed");
80
+ assert.deepEqual(res.actualIds, [m.id], "retrieval ran and returned the memory");
81
+ assert.equal(res.persisted, false, "no persistence when switch is off");
82
+ assert.deepEqual(store.listRecallEvals(), [], "recall_evals stays empty");
83
+ store.close();
84
+ });
85
+
86
+ test("switch on: evaluateRetrieval persists a recall_evals snapshot", async () => {
87
+ const { store, service } = setup({ evalPersistTestResults: true });
88
+ const m = saveMemory(service, "量子计算入门", "叠加态");
89
+ const res = await service.evaluateRetrieval("量子", [m.id], { mode: "keyword", topK: 10, evalType: "regression" });
90
+ assert.equal(res.persisted, true, "snapshot persisted");
91
+ const evals = store.listRecallEvals();
92
+ assert.equal(evals.length, 1, "one eval row");
93
+ const row = evals[0];
94
+ assert.equal(row.query, "量子");
95
+ assert.deepEqual(row.expected_ids, [m.id], "expected ids round-trip");
96
+ assert.deepEqual(row.actual_ids, [m.id], "actual ids round-trip");
97
+ assert.equal(row.eval_type, "regression");
98
+ assert.ok(row.metrics && typeof row.metrics.precision === "number", "metrics JSON round-trips");
99
+ assert.ok(typeof row.created_at === "string" && row.created_at.length > 0, "timestamp captured");
100
+ // Idempotent on id: the same logical eval id replays without duplicates.
101
+ store.saveRecallEval({ id: "ev-x", query: "q", expected_ids: [], actual_ids: [], metrics: {}, eval_type: "manual" });
102
+ store.saveRecallEval({ id: "ev-x", query: "q2", expected_ids: [], actual_ids: [], metrics: {}, eval_type: "manual" });
103
+ assert.equal(store.listRecallEvals().filter((e) => e.id === "ev-x").length, 1, "replay overwrites, no duplicate");
104
+ store.close();
105
+ });
106
+
107
+ test("persist override: call-level persist:true writes even with the switch off", async () => {
108
+ const { store, service } = setup({}); // switch off
109
+ const m = saveMemory(service, "量子计算入门", "叠加态");
110
+ const res = await service.evaluateRetrieval("量子", [m.id], { mode: "keyword", persist: true });
111
+ assert.equal(res.persisted, true, "explicit persist override honored");
112
+ assert.equal(store.listRecallEvals().length, 1);
113
+ store.close();
114
+ });
115
+
116
+ test("persist override: call-level persist:false suppresses even with the switch on", async () => {
117
+ const { store, service } = setup({ evalPersistTestResults: true });
118
+ saveMemory(service, "量子计算入门", "叠加态");
119
+ const res = await service.evaluateRetrieval("量子", [], { mode: "keyword", persist: false });
120
+ assert.equal(res.persisted, false, "explicit opt-out honored");
121
+ assert.deepEqual(store.listRecallEvals(), [], "nothing written");
122
+ store.close();
123
+ });
124
+
125
+ // ---------------------------------------------------------------- metrics correctness
126
+
127
+ test("metrics: computeRetrievalMetrics is exact for known inputs", () => {
128
+ const { service } = setup();
129
+ // a,b,c retrieved; a,x expected → 1 relevant at rank 1.
130
+ assert.deepEqual(
131
+ service.computeRetrievalMetrics(["a", "b", "c"], ["a", "x"]),
132
+ { precision: 0.3333, recall: 0.5, mrr: 1, hit_count: 1 }
133
+ );
134
+ // relevant at rank 3 → mrr 1/3.
135
+ assert.deepEqual(
136
+ service.computeRetrievalMetrics(["x", "y", "a"], ["a", "b"]),
137
+ { precision: 0.3333, recall: 0.5, mrr: 0.3333, hit_count: 1 }
138
+ );
139
+ // empty retrieval → zero metrics, no divide-by-zero.
140
+ assert.deepEqual(
141
+ service.computeRetrievalMetrics([], ["a", "b"]),
142
+ { precision: 0, recall: 0, mrr: 0, hit_count: 0 }
143
+ );
144
+ // everything relevant, nothing missed → perfect scores.
145
+ assert.deepEqual(
146
+ service.computeRetrievalMetrics(["a", "b"], ["a", "b"]),
147
+ { precision: 1, recall: 1, mrr: 1, hit_count: 2 }
148
+ );
149
+ // extra noise harms precision but not recall.
150
+ assert.deepEqual(
151
+ service.computeRetrievalMetrics(["a", "b", "c", "d"], ["a"]),
152
+ { precision: 0.25, recall: 1, mrr: 1, hit_count: 1 }
153
+ );
154
+ });
155
+
156
+ test("metrics: integration — partial hit scores precision/recall/mrr from real recall", async () => {
157
+ const { store, service } = setup({ evalPersistTestResults: true });
158
+ const hit = saveMemory(service, "量子计算入门", "叠加态");
159
+ saveMemory(service, "量子纠缠", "贝尔态");
160
+ saveMemory(service, "猫咪饲养", "喂食");
161
+ const res = await service.evaluateRetrieval("量子", [hit.id], { mode: "keyword", topK: 10 });
162
+ // Two literal 量子 hits retrieved, one relevant → precision 1/2, recall 1/1.
163
+ // Title-tied, equal-importance rows order by updated_at DESC, so the later
164
+ // saved 量子纠缠 ranks first and the relevant row is at rank 2 → mrr 1/2.
165
+ assert.equal(res.metrics.hit_count, 1);
166
+ assert.equal(res.metrics.precision, 0.5);
167
+ assert.equal(res.metrics.recall, 1);
168
+ assert.equal(res.metrics.mrr, 0.5);
169
+ const row = store.listRecallEvals()[0];
170
+ assert.equal(row.metrics.precision, 0.5, "persisted metrics match");
171
+ store.close();
172
+ });
173
+
174
+ // ---------------------------------------------------------------- FK linkage
175
+
176
+ test("FK: recordRecall=true links the eval to the recall_runs audit row", async () => {
177
+ const { store, service } = setup({ evalPersistTestResults: true });
178
+ const m = saveMemory(service, "量子计算入门", "叠加态");
179
+ const res = await service.evaluateRetrieval("量子", [m.id], { mode: "keyword", topK: 5, recordRecall: true });
180
+ assert.ok(res.recallRunId, "a recall run was recorded for the same scene");
181
+ assert.equal(store.listRecallRuns().length, 1, "exactly one recall_runs row");
182
+ const run = store.getRecallRun(res.recallRunId);
183
+ assert.equal(run.query, "量子");
184
+ const evals = store.listRecallEvals();
185
+ assert.equal(evals.length, 1);
186
+ assert.equal(evals[0].recall_run_id, res.recallRunId, "eval links to the recorded run");
187
+ store.close();
188
+ });
189
+
190
+ test("FK: explicit recallRunId is preserved — recordRecall never clobbers it (regression)", async () => {
191
+ const { store, service } = setup({ evalPersistTestResults: true });
192
+ const m = saveMemory(service, "量子计算入门", "叠加态");
193
+ // Pre-existing audit run the evaluator wants to link against.
194
+ const run = store.saveRecallRun({
195
+ query: "量子", mode: "keyword", topK: 5, candidates: [], created_at: new Date().toISOString()
196
+ });
197
+ // recordRecall=true alongside an explicit recallRunId: the explicit link wins,
198
+ // and NO extra recall_runs row is minted.
199
+ const res = await service.evaluateRetrieval("量子", [m.id], { mode: "keyword", recordRecall: true, recallRunId: run.id });
200
+ assert.equal(res.recallRunId, run.id, "explicit recallRunId preserved");
201
+ assert.equal(store.listRecallRuns().length, 1, "no duplicate recall_runs row minted");
202
+ const evals = store.listRecallEvals();
203
+ assert.equal(evals[0].recall_run_id, run.id, "eval links to the pre-existing run");
204
+ store.close();
205
+ });
206
+
207
+ test("FK: recordRecall=false leaves recall_run_id null and writes no recall_runs row", async () => {
208
+ const { store, service } = setup({ evalPersistTestResults: true });
209
+ const m = saveMemory(service, "量子计算入门", "叠加态");
210
+ const res = await service.evaluateRetrieval("量子", [m.id], { mode: "keyword" });
211
+ assert.equal(res.recallRunId, null, "no run recorded by default");
212
+ assert.deepEqual(store.listRecallRuns(), [], "recall_runs untouched by evals");
213
+ const row = store.listRecallEvals()[0];
214
+ assert.ok(!row.recall_run_id, "eval row has no recall_run_id");
215
+ store.close();
216
+ });
217
+
218
+ // ---------------------------------------------------------------- production isolation
219
+
220
+ test("production search never writes recall_evals, even with the switch on", async () => {
221
+ const { store, service } = setup({ evalPersistTestResults: true });
222
+ // Mimic src/index.js wiring: the recall recorder persists to recall_runs.
223
+ service.setRecallRecorder((recall) => {
224
+ store.saveRecallRun({
225
+ query: recall.query, mode: recall.mode, topK: recall.topK, threshold: recall.threshold ?? null,
226
+ candidates: recall.candidates ?? [], created_at: recall.createdAt
227
+ });
228
+ });
229
+ saveMemory(service, "量子计算入门", "叠加态");
230
+ const rows = await service.searchMemories("量子", { mode: "keyword", recordRecall: true });
231
+ assert.ok(rows.length >= 1, "search returned results");
232
+ assert.equal(store.listRecallRuns().length, 1, "production audit lands in recall_runs");
233
+ assert.deepEqual(store.listRecallEvals(), [], "recall_evals stays untouched by production search");
234
+ store.close();
235
+ });