open-memex 0.9.0 → 0.10.0-alpha.2
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +2 -0
- package/README.md +19 -7
- package/README.zh-CN.md +6 -2
- package/dist/.build-stamp +1 -1
- package/dist/cli.js +24 -2
- package/dist/config.js +2 -0
- package/dist/mcp.js +1 -1
- package/dist/retrieve/feedback.js +95 -0
- package/dist/retrieve/search.js +56 -12
- package/dist/store/usage.js +23 -0
- package/dist/tools/memory.js +1 -1
- package/dist/tools/ops.js +2 -1
- package/docs/V2-DESIGN.md +2 -2
- package/docs/design/decisions.md +3 -0
- package/package.json +66 -66
- package/scripts/retrieval-eval/fixture.ts +67 -3
- package/scripts/retrieval-eval.ts +100 -24
- package/scripts/smoke-pure.ts +44 -0
- package/src/cli.ts +32 -5
- package/src/config.ts +9 -0
- package/src/mcp.ts +1 -1
- package/src/retrieve/feedback.ts +128 -0
- package/src/retrieve/search.ts +98 -4
- package/src/store/usage.ts +25 -0
- package/src/tools/memory.ts +1 -1
- package/src/tools/ops.ts +2 -0
package/package.json
CHANGED
|
@@ -1,66 +1,66 @@
|
|
|
1
|
-
{
|
|
2
|
-
"name": "open-memex",
|
|
3
|
-
"version": "0.
|
|
4
|
-
"mcpName": "io.github.stoneskin/open-memex",
|
|
5
|
-
"description": "Local-first memory layer and protocol for AI coding agents. Markdown source of truth, SQLite FTS5 index, zero cloud.",
|
|
6
|
-
"keywords": [
|
|
7
|
-
"mcp",
|
|
8
|
-
"model-context-protocol",
|
|
9
|
-
"mcp-server",
|
|
10
|
-
"opencode",
|
|
11
|
-
"ai-agents",
|
|
12
|
-
"agent-memory",
|
|
13
|
-
"persistent-memory",
|
|
14
|
-
"local-first",
|
|
15
|
-
"sqlite",
|
|
16
|
-
"fts5",
|
|
17
|
-
"markdown",
|
|
18
|
-
"memory",
|
|
19
|
-
"copilot",
|
|
20
|
-
"cursor",
|
|
21
|
-
"claude-code",
|
|
22
|
-
"vscode",
|
|
23
|
-
"knowledge-management",
|
|
24
|
-
"developer-tools",
|
|
25
|
-
"synonyms"
|
|
26
|
-
],
|
|
27
|
-
"type": "module",
|
|
28
|
-
"license": "Apache-2.0",
|
|
29
|
-
"repository": {
|
|
30
|
-
"type": "git",
|
|
31
|
-
"url": "git+https://github.com/stoneskin/open-memex.git"
|
|
32
|
-
},
|
|
33
|
-
"homepage": "https://github.com/stoneskin/open-memex#readme",
|
|
34
|
-
"bugs": {
|
|
35
|
-
"url": "https://github.com/stoneskin/open-memex/issues"
|
|
36
|
-
},
|
|
37
|
-
"main": "src/index.ts",
|
|
38
|
-
"scripts": {
|
|
39
|
-
"typecheck": "tsc --noEmit",
|
|
40
|
-
"cli": "node --experimental-strip-types src/cli.ts",
|
|
41
|
-
"mcp": "node --experimental-strip-types src/mcp.ts",
|
|
42
|
-
"build": "tsc -p tsconfig.build.json && node scripts/build-stamp.mjs",
|
|
43
|
-
"prepublishOnly": "npm run build",
|
|
44
|
-
"postinstall": "node scripts/postinstall.js",
|
|
45
|
-
"test-full": "node --experimental-strip-types scripts/test-full.ts"
|
|
46
|
-
},
|
|
47
|
-
"dependencies": {
|
|
48
|
-
"@modelcontextprotocol/sdk": "^1.30.1",
|
|
49
|
-
"better-sqlite3": "^13.0.3",
|
|
50
|
-
"js-yaml": "^4.1.0",
|
|
51
|
-
"zod": "^4.1.8"
|
|
52
|
-
},
|
|
53
|
-
"devDependencies": {
|
|
54
|
-
"@opencode-ai/plugin": "^1.18.30",
|
|
55
|
-
"@types/better-sqlite3": "^7.6.11",
|
|
56
|
-
"@types/js-yaml": "^4.0.9",
|
|
57
|
-
"@types/node": "^22.0.0",
|
|
58
|
-
"typescript": "^5.6.0"
|
|
59
|
-
},
|
|
60
|
-
"bin": {
|
|
61
|
-
"open-memex": "dist/cli.js"
|
|
62
|
-
},
|
|
63
|
-
"engines": {
|
|
64
|
-
"node": ">=22.14.0"
|
|
65
|
-
}
|
|
66
|
-
}
|
|
1
|
+
{
|
|
2
|
+
"name": "open-memex",
|
|
3
|
+
"version": "0.10.0-alpha.2",
|
|
4
|
+
"mcpName": "io.github.stoneskin/open-memex",
|
|
5
|
+
"description": "Local-first memory layer and protocol for AI coding agents. Markdown source of truth, SQLite FTS5 index, zero cloud.",
|
|
6
|
+
"keywords": [
|
|
7
|
+
"mcp",
|
|
8
|
+
"model-context-protocol",
|
|
9
|
+
"mcp-server",
|
|
10
|
+
"opencode",
|
|
11
|
+
"ai-agents",
|
|
12
|
+
"agent-memory",
|
|
13
|
+
"persistent-memory",
|
|
14
|
+
"local-first",
|
|
15
|
+
"sqlite",
|
|
16
|
+
"fts5",
|
|
17
|
+
"markdown",
|
|
18
|
+
"memory",
|
|
19
|
+
"copilot",
|
|
20
|
+
"cursor",
|
|
21
|
+
"claude-code",
|
|
22
|
+
"vscode",
|
|
23
|
+
"knowledge-management",
|
|
24
|
+
"developer-tools",
|
|
25
|
+
"synonyms"
|
|
26
|
+
],
|
|
27
|
+
"type": "module",
|
|
28
|
+
"license": "Apache-2.0",
|
|
29
|
+
"repository": {
|
|
30
|
+
"type": "git",
|
|
31
|
+
"url": "git+https://github.com/stoneskin/open-memex.git"
|
|
32
|
+
},
|
|
33
|
+
"homepage": "https://github.com/stoneskin/open-memex#readme",
|
|
34
|
+
"bugs": {
|
|
35
|
+
"url": "https://github.com/stoneskin/open-memex/issues"
|
|
36
|
+
},
|
|
37
|
+
"main": "src/index.ts",
|
|
38
|
+
"scripts": {
|
|
39
|
+
"typecheck": "tsc --noEmit",
|
|
40
|
+
"cli": "node --experimental-strip-types src/cli.ts",
|
|
41
|
+
"mcp": "node --experimental-strip-types src/mcp.ts",
|
|
42
|
+
"build": "tsc -p tsconfig.build.json && node scripts/build-stamp.mjs",
|
|
43
|
+
"prepublishOnly": "npm run build",
|
|
44
|
+
"postinstall": "node scripts/postinstall.js",
|
|
45
|
+
"test-full": "node --experimental-strip-types scripts/test-full.ts"
|
|
46
|
+
},
|
|
47
|
+
"dependencies": {
|
|
48
|
+
"@modelcontextprotocol/sdk": "^1.30.1",
|
|
49
|
+
"better-sqlite3": "^13.0.3",
|
|
50
|
+
"js-yaml": "^4.1.0",
|
|
51
|
+
"zod": "^4.1.8"
|
|
52
|
+
},
|
|
53
|
+
"devDependencies": {
|
|
54
|
+
"@opencode-ai/plugin": "^1.18.30",
|
|
55
|
+
"@types/better-sqlite3": "^7.6.11",
|
|
56
|
+
"@types/js-yaml": "^4.0.9",
|
|
57
|
+
"@types/node": "^22.0.0",
|
|
58
|
+
"typescript": "^5.6.0"
|
|
59
|
+
},
|
|
60
|
+
"bin": {
|
|
61
|
+
"open-memex": "dist/cli.js"
|
|
62
|
+
},
|
|
63
|
+
"engines": {
|
|
64
|
+
"node": ">=22.14.0"
|
|
65
|
+
}
|
|
66
|
+
}
|
|
@@ -1,13 +1,15 @@
|
|
|
1
1
|
/**
|
|
2
2
|
* Synthetic retrieval-eval fixture (D77).
|
|
3
3
|
*
|
|
4
|
-
*
|
|
4
|
+
* 60 personal-scope memories + 47 queries with gold ids. Written BEFORE
|
|
5
5
|
* running the eval — the fixture is the test, not tuned to the results.
|
|
6
6
|
* All memories share one scope/tier so the measured ranking is pure BM25.
|
|
7
7
|
* Mixed EN/ZH; includes paraphrase and synonym queries (the hard cases
|
|
8
8
|
* from the retrieval-robustness question), near-duplicate distractors,
|
|
9
|
-
*
|
|
10
|
-
*
|
|
9
|
+
* D81 user-defined alias vocabulary (bidirectional query-time expansion:
|
|
10
|
+
* 香蕉计划 ↔ 支付系统重构项目), and a 3-query D79 feedback slice where
|
|
11
|
+
* the gold memory carries useful-reuse counters and a retrieved-only
|
|
12
|
+
* distractor can outrank it on plain BM25.
|
|
11
13
|
*/
|
|
12
14
|
|
|
13
15
|
export interface FixtureMemory {
|
|
@@ -18,6 +20,14 @@ export interface FixtureMemory {
|
|
|
18
20
|
/** D81: user-defined alias vocabulary (nickname → referent). */
|
|
19
21
|
alias?: string;
|
|
20
22
|
target?: string;
|
|
23
|
+
/**
|
|
24
|
+
* D79 (first slice): seed D77-L2 telemetry for this memory before the eval
|
|
25
|
+
* runs. `retrieved` is written via recordRetrieved, `usefulSelf` via
|
|
26
|
+
* recordUseful. The retrieval-eval search calls pass `record: false`, so
|
|
27
|
+
* these are the only counters the run sees — and the baseline (feedback
|
|
28
|
+
* off) ignores them entirely.
|
|
29
|
+
*/
|
|
30
|
+
usage?: { retrieved: number; usefulSelf?: number };
|
|
21
31
|
body: string;
|
|
22
32
|
}
|
|
23
33
|
|
|
@@ -25,6 +35,8 @@ export interface FixtureQuery {
|
|
|
25
35
|
query: string;
|
|
26
36
|
gold: string[];
|
|
27
37
|
note: string;
|
|
38
|
+
/** Optional reporting slice, e.g. "feedback" for the D79 weighting rows. */
|
|
39
|
+
slice?: string;
|
|
28
40
|
}
|
|
29
41
|
|
|
30
42
|
export const MEMORIES: FixtureMemory[] = [
|
|
@@ -113,6 +125,53 @@ export const MEMORIES: FixtureMemory[] = [
|
|
|
113
125
|
{ id: "mem-052", type: "fact", tags: ["alias"], alias: "香蕉计划", target: "支付系统重构项目", body: "香蕉计划是支付系统重构项目的内部代号,团队日常用香蕉计划指代这个项目。" },
|
|
114
126
|
{ id: "mem-053", type: "decision", tags: ["backend"], body: "支付系统重构项目决定用 Go 重写网关层,Q4 启动。" },
|
|
115
127
|
{ id: "mem-054", type: "fact", tags: ["planning"], body: "香蕉计划下周一启动评审,材料周五前提交。" },
|
|
128
|
+
|
|
129
|
+
// ---- D79 feedback slice: near-tied pairs, one confirmed useful, one only retrieved ----
|
|
130
|
+
// Each pair is on-topic and similar in length; the distractor repeats the
|
|
131
|
+
// query vocabulary more often, so plain BM25 can put it first. The gold
|
|
132
|
+
// memory carries the D77 counters a real user would have produced.
|
|
133
|
+
{
|
|
134
|
+
id: "mem-055",
|
|
135
|
+
type: "decision",
|
|
136
|
+
tags: ["deploy", "release"],
|
|
137
|
+
usage: { retrieved: 6, usefulSelf: 3 },
|
|
138
|
+
body: "The production release train leaves every Thursday at 10:00 from the release branch. Hotfixes need the TL to announce the reason in the release channel; no Friday deploys.",
|
|
139
|
+
},
|
|
140
|
+
{
|
|
141
|
+
id: "mem-056",
|
|
142
|
+
type: "fact",
|
|
143
|
+
tags: ["deploy", "release"],
|
|
144
|
+
usage: { retrieved: 6 },
|
|
145
|
+
body: "Release channel and release branch rules: the release train schedule, release branch cut time, and release channel announcement template live in the runbook. Friday release questions go to the release channel.",
|
|
146
|
+
},
|
|
147
|
+
{
|
|
148
|
+
id: "mem-057",
|
|
149
|
+
type: "fact",
|
|
150
|
+
tags: ["database", "backup"],
|
|
151
|
+
usage: { retrieved: 5, usefulSelf: 3 },
|
|
152
|
+
body: "Database backups run daily at 02:00, keep thirty full copies, and a restore drill happens every quarter.",
|
|
153
|
+
},
|
|
154
|
+
{
|
|
155
|
+
id: "mem-058",
|
|
156
|
+
type: "fact",
|
|
157
|
+
tags: ["database", "backup"],
|
|
158
|
+
usage: { retrieved: 5 },
|
|
159
|
+
body: "Database backup policy: backup retention, backup restore drill, backup schedule, and database backup ownership are listed in the backup policy spreadsheet; daily backup jobs run from the database backup service.",
|
|
160
|
+
},
|
|
161
|
+
{
|
|
162
|
+
id: "mem-059",
|
|
163
|
+
type: "constraint",
|
|
164
|
+
tags: ["auth", "sso"],
|
|
165
|
+
usage: { retrieved: 5, usefulSelf: 3 },
|
|
166
|
+
body: "SSO through OIDC is mandatory for internal tools; password-only login was removed after the March credential-stuffing incident.",
|
|
167
|
+
},
|
|
168
|
+
{
|
|
169
|
+
id: "mem-060",
|
|
170
|
+
type: "fact",
|
|
171
|
+
tags: ["auth", "sso"],
|
|
172
|
+
usage: { retrieved: 5 },
|
|
173
|
+
body: "Auth policy: SSO provider config, OIDC login flow, password login removal checklist, and SSO provider ownership are documented in the auth policy wiki; internal tools login through the SSO provider.",
|
|
174
|
+
},
|
|
116
175
|
];
|
|
117
176
|
|
|
118
177
|
export const QUERIES: FixtureQuery[] = [
|
|
@@ -179,4 +238,9 @@ export const QUERIES: FixtureQuery[] = [
|
|
|
179
238
|
{ query: "香蕉计划用什么语言重写网关", gold: ["mem-053"], note: "alias→target: round 2 must find mem-053 via 支付系统重构项目" },
|
|
180
239
|
{ query: "支付系统重构项目什么时候启动评审", gold: ["mem-054"], note: "target→alias: round 2 must find mem-054 via 香蕉计划" },
|
|
181
240
|
{ query: "香蕉计划是哪个项目的代号", gold: ["mem-052"], note: "alias memory itself, round 1" },
|
|
241
|
+
|
|
242
|
+
// ---- D79 feedback slice (gold = the memory with confirmed useful reuse) ----
|
|
243
|
+
{ query: "release train schedule release branch thursday", gold: ["mem-055"], note: "feedback: useful mem vs retrieved-only distractor", slice: "feedback" },
|
|
244
|
+
{ query: "database backup retention restore drill schedule", gold: ["mem-057"], note: "feedback: useful mem vs retrieved-only distractor", slice: "feedback" },
|
|
245
|
+
{ query: "SSO OIDC internal tools password login", gold: ["mem-059"], note: "feedback: useful mem vs retrieved-only distractor", slice: "feedback" },
|
|
182
246
|
];
|
|
@@ -23,6 +23,7 @@ import { MEMORIES, QUERIES } from "./retrieval-eval/fixture.ts";
|
|
|
23
23
|
import { serialize, normalizeFrontmatter } from "../src/store/markdown.ts";
|
|
24
24
|
import { syncScope } from "../src/store/sync.ts";
|
|
25
25
|
import { search } from "../src/retrieve/search.ts";
|
|
26
|
+
import { recordRetrieved, recordUseful } from "../src/store/usage.ts";
|
|
26
27
|
import { memoriesDirPath } from "../src/paths.ts";
|
|
27
28
|
|
|
28
29
|
const K = 5;
|
|
@@ -44,39 +45,114 @@ for (const m of MEMORIES) {
|
|
|
44
45
|
fs.writeFileSync(path.join(dir, `${m.id}.md`), serialize(fm, m.body), "utf8");
|
|
45
46
|
}
|
|
46
47
|
const stats = syncScope("personal");
|
|
48
|
+
// D79: seed the D77-L2 counters the feedback slice needs. This is the
|
|
49
|
+
// "telemetry a real user already produced" — written through the same store
|
|
50
|
+
// API as the tool surfaces, not injected into the ranking. The baseline
|
|
51
|
+
// (feedback off) ignores it; the weighted run reads it.
|
|
52
|
+
for (const m of MEMORIES) {
|
|
53
|
+
if (!m.usage) continue;
|
|
54
|
+
for (let i = 0; i < m.usage.retrieved; i++) recordRetrieved([m.id]);
|
|
55
|
+
for (let i = 0; i < (m.usage.usefulSelf ?? 0); i++) recordUseful(m.id, "self", "tool");
|
|
56
|
+
}
|
|
47
57
|
console.log(`seeded ${MEMORIES.length} memories (indexed: ${stats.added})\n`);
|
|
48
58
|
|
|
49
59
|
// --- run ---
|
|
50
|
-
|
|
51
|
-
|
|
52
|
-
|
|
53
|
-
|
|
60
|
+
interface Metrics {
|
|
61
|
+
n: number;
|
|
62
|
+
r1: number;
|
|
63
|
+
r5: number;
|
|
64
|
+
mrr: number;
|
|
65
|
+
ranks: Map<string, number>; // query -> 0-based rank, -1 = miss
|
|
66
|
+
}
|
|
54
67
|
|
|
55
|
-
for
|
|
56
|
-
|
|
57
|
-
|
|
58
|
-
|
|
59
|
-
|
|
60
|
-
|
|
61
|
-
|
|
62
|
-
|
|
68
|
+
// D79: ablation knob for tuning the band by measurement. The shipped value
|
|
69
|
+
// lives in src/retrieve/feedback.ts; this env var exists only so the sweep
|
|
70
|
+
// (0.95 → 0.65) is reproducible without editing source.
|
|
71
|
+
const bandEnv = process.env.RETRIEVAL_FEEDBACK_BAND;
|
|
72
|
+
const bandRatio = bandEnv ? Number(bandEnv) : undefined;
|
|
73
|
+
|
|
74
|
+
function run(feedback: boolean): Metrics {
|
|
75
|
+
const ranks = new Map<string, number>();
|
|
76
|
+
let r1 = 0;
|
|
77
|
+
let r5 = 0;
|
|
78
|
+
let mrr = 0;
|
|
79
|
+
for (const q of QUERIES) {
|
|
80
|
+
const stats = { ftsQuery: "", candidates: 0, hiddenSuperseded: 0, hiddenExcluded: 0, aliasExpansions: [] as string[] };
|
|
81
|
+
const hits = search(q.query, {
|
|
82
|
+
scopeKeys: ["personal"],
|
|
83
|
+
limit: 50,
|
|
84
|
+
stats,
|
|
85
|
+
feedback,
|
|
86
|
+
feedbackBandRatio: bandRatio,
|
|
87
|
+
});
|
|
88
|
+
const ids = hits.map((h) => h.id);
|
|
89
|
+
let rank = -1;
|
|
90
|
+
for (const g of q.gold) {
|
|
91
|
+
const i = ids.indexOf(g);
|
|
92
|
+
if (i !== -1 && (rank === -1 || i < rank)) rank = i;
|
|
93
|
+
}
|
|
94
|
+
ranks.set(q.query, rank);
|
|
95
|
+
if (rank === 0) r1++;
|
|
96
|
+
if (rank !== -1 && rank < K) r5++;
|
|
97
|
+
if (rank !== -1) mrr += 1 / (rank + 1);
|
|
63
98
|
}
|
|
64
|
-
|
|
65
|
-
|
|
66
|
-
|
|
67
|
-
|
|
68
|
-
|
|
69
|
-
|
|
99
|
+
return { n: QUERIES.length, r1, r5, mrr, ranks };
|
|
100
|
+
}
|
|
101
|
+
|
|
102
|
+
function metricsFor(queries: typeof QUERIES, ranks: Map<string, number>): Metrics {
|
|
103
|
+
let r1 = 0;
|
|
104
|
+
let r5 = 0;
|
|
105
|
+
let mrr = 0;
|
|
106
|
+
for (const q of queries) {
|
|
107
|
+
const rank = ranks.get(q.query) ?? -1;
|
|
108
|
+
if (rank === 0) r1++;
|
|
109
|
+
if (rank !== -1 && rank < K) r5++;
|
|
110
|
+
if (rank !== -1) mrr += 1 / (rank + 1);
|
|
111
|
+
}
|
|
112
|
+
return { n: queries.length, r1, r5, mrr, ranks };
|
|
113
|
+
}
|
|
114
|
+
|
|
115
|
+
function row(label: string, m: Metrics): string {
|
|
116
|
+
return `${label.padEnd(10)} recall@1 ${(m.r1 / m.n).toFixed(3)} (${m.r1}/${m.n}) recall@5 ${(m.r5 / m.n).toFixed(3)} (${m.r5}/${m.n}) MRR ${(m.mrr / m.n).toFixed(3)}`;
|
|
117
|
+
}
|
|
118
|
+
|
|
119
|
+
const baseline = run(false);
|
|
120
|
+
const weighted = run(true);
|
|
121
|
+
|
|
122
|
+
// Per-query misses and non-top-1 ranks for the baseline (the regression view).
|
|
123
|
+
const misses: string[] = [];
|
|
124
|
+
for (const q of QUERIES) {
|
|
125
|
+
const rank = baseline.ranks.get(q.query) ?? -1;
|
|
126
|
+
if (rank === -1) {
|
|
127
|
+
misses.push(` MISS rank=- query="${q.query}" gold=${q.gold.join(",")} [${q.note}]`);
|
|
128
|
+
} else if (rank > 0) {
|
|
129
|
+
const after = weighted.ranks.get(q.query) ?? -1;
|
|
130
|
+
const changed = after !== rank ? ` → rank=${after + 1} with feedback` : "";
|
|
131
|
+
console.log(` rank=${rank + 1} query="${q.query}" gold=${q.gold.join(",")} [${q.note}]${changed}`);
|
|
70
132
|
}
|
|
71
133
|
}
|
|
72
134
|
|
|
73
|
-
|
|
74
|
-
console.log(`\n==== retrieval-eval: FTS5 baseline ====`);
|
|
135
|
+
console.log(`\n==== retrieval-eval: baseline vs D79 feedback ====`);
|
|
75
136
|
console.log(`corpus : ${MEMORIES.length} memories (personal scope, single tier)`);
|
|
76
|
-
console.log(`queries: ${
|
|
77
|
-
console.log(`
|
|
78
|
-
console.log(
|
|
79
|
-
console.log(
|
|
137
|
+
console.log(`queries: ${QUERIES.length}`);
|
|
138
|
+
if (bandRatio !== undefined) console.log(`band : ${bandRatio} (RETRIEVAL_FEEDBACK_BAND override)`);
|
|
139
|
+
console.log(row("baseline", baseline));
|
|
140
|
+
console.log(row("feedback", weighted));
|
|
141
|
+
|
|
142
|
+
const feedbackQueries = QUERIES.filter((q) => q.slice === "feedback");
|
|
143
|
+
if (feedbackQueries.length > 0) {
|
|
144
|
+
const w = weighted.ranks;
|
|
145
|
+
const b = baseline.ranks;
|
|
146
|
+
console.log(`\nfeedback slice (${feedbackQueries.length} queries):`);
|
|
147
|
+
console.log(row("baseline", metricsFor(feedbackQueries, b)));
|
|
148
|
+
console.log(row("feedback", metricsFor(feedbackQueries, w)));
|
|
149
|
+
for (const q of feedbackQueries) {
|
|
150
|
+
const rb = (b.get(q.query) ?? -1) + 1;
|
|
151
|
+
const rw = (w.get(q.query) ?? -1) + 1;
|
|
152
|
+
console.log(` ${rb} → ${rw} query="${q.query}" gold=${q.gold.join(",")}`);
|
|
153
|
+
}
|
|
154
|
+
}
|
|
155
|
+
|
|
80
156
|
if (misses.length > 0) {
|
|
81
157
|
console.log(`\nmisses (${misses.length}):`);
|
|
82
158
|
for (const m of misses) console.log(m);
|
package/scripts/smoke-pure.ts
CHANGED
|
@@ -10,6 +10,11 @@ import { cjkIndexText, cjkQueryExpr, hasCjk } from "../src/retrieve/cjk.ts";
|
|
|
10
10
|
import { toFtsQuery } from "../src/retrieve/query.ts";
|
|
11
11
|
import { expansionVariantsForDoc, MAX_AUTO_VARIANTS } from "../src/retrieve/synonyms.ts";
|
|
12
12
|
import { BM25_WEIGHTS, DEFAULT_EXPANSIONS_WEIGHT } from "../src/retrieve/weights.ts";
|
|
13
|
+
import {
|
|
14
|
+
applyFeedbackRanking,
|
|
15
|
+
FEEDBACK_MIN_RETRIEVED,
|
|
16
|
+
DEFAULT_FEEDBACK_BAND_RATIO,
|
|
17
|
+
} from "../src/retrieve/feedback.ts";
|
|
13
18
|
import { formatReuseReport } from "../src/reuse-report.ts";
|
|
14
19
|
import {
|
|
15
20
|
planAliasExpansions,
|
|
@@ -970,6 +975,45 @@ console.log("== D83 expansions BM25 weight + matchedVia ==");
|
|
|
970
975
|
ok("body stays the strongest column", BM25_WEIGHTS[0] >= BM25_WEIGHTS[3], JSON.stringify(BM25_WEIGHTS));
|
|
971
976
|
}
|
|
972
977
|
|
|
978
|
+
console.log("== D79 feedback ranking (reuse signal) ==");
|
|
979
|
+
{
|
|
980
|
+
const hits = [
|
|
981
|
+
{ id: "fresh", score: 20 },
|
|
982
|
+
{ id: "zombie", score: 18 },
|
|
983
|
+
{ id: "proven", score: 17 },
|
|
984
|
+
{ id: "far", score: 5 },
|
|
985
|
+
];
|
|
986
|
+
const usage = new Map([
|
|
987
|
+
["fresh", { retrieved: 1, useful: 0 }], // too few samples — must not move
|
|
988
|
+
["proven", { retrieved: 6, useful: 3 }], // rate 0.5
|
|
989
|
+
["zombie", { retrieved: 9, useful: 0 }], // enough samples, no useful
|
|
990
|
+
]);
|
|
991
|
+
const r = applyFeedbackRanking(hits, usage);
|
|
992
|
+
const order = r.ordered.map((h) => h.id).join(",");
|
|
993
|
+
ok("fresh memory keeps its BM25 place (min sample guard)", order.startsWith("fresh"), order);
|
|
994
|
+
// proven starts BELOW zombie on BM25; this assertion fails if the reorder
|
|
995
|
+
// is a no-op (the old fixture already had proven above zombie).
|
|
996
|
+
ok(
|
|
997
|
+
"proven swaps above the higher-BM25 retrieved-only hit",
|
|
998
|
+
order === "fresh,proven,zombie,far",
|
|
999
|
+
`${hits.map((h) => h.id).join(",")} -> ${order}`,
|
|
1000
|
+
);
|
|
1001
|
+
ok("large score gap is not crossed", r.ordered[3]!.id === "far", order);
|
|
1002
|
+
ok("ineligible vs eligible is reported", r.info.get("fresh")!.eligible === false && r.info.get("proven")!.eligible === true);
|
|
1003
|
+
ok("reuse rate may exceed 1.0 (signal, not probability)", (() => {
|
|
1004
|
+
const x = applyFeedbackRanking(
|
|
1005
|
+
[{ id: "a", score: 10 }, { id: "b", score: 9 }],
|
|
1006
|
+
new Map([["b", { retrieved: 2, useful: 4 }]]),
|
|
1007
|
+
);
|
|
1008
|
+
return x.info.get("b")!.rate === 2 && x.ordered[0]!.id === "a"; // 2 < min retrieved
|
|
1009
|
+
})());
|
|
1010
|
+
ok("min sample is 3 and band is 0.75", FEEDBACK_MIN_RETRIEVED === 3 && DEFAULT_FEEDBACK_BAND_RATIO === 0.75);
|
|
1011
|
+
ok("empty usage map changes nothing", (() => {
|
|
1012
|
+
const x = applyFeedbackRanking(hits, new Map());
|
|
1013
|
+
return x.ordered.map((h) => h.id).join(",") === hits.map((h) => h.id).join(",");
|
|
1014
|
+
})());
|
|
1015
|
+
}
|
|
1016
|
+
|
|
973
1017
|
console.log("== D89 working-state note (§3.6) ==");
|
|
974
1018
|
{
|
|
975
1019
|
const {
|
package/src/cli.ts
CHANGED
|
@@ -9,7 +9,7 @@ import { findDuplicates, supersede, setStatus } from "./store/lifecycle.ts";
|
|
|
9
9
|
import { proposeMemories, promoteMemory, listConflicts, resolveConflict, formatReviewHistory } from "./review.ts";
|
|
10
10
|
import { getSyncStatus, formatSyncStatus, submitMemories } from "./submit.ts";
|
|
11
11
|
import { getPrStatus, formatPrStatus, applyPrStatus } from "./github.ts";
|
|
12
|
-
import { search, list, countList, hitStateLabel } from "./retrieve/search.ts";
|
|
12
|
+
import { search, list, countList, hitStateLabel, type SearchStats } from "./retrieve/search.ts";
|
|
13
13
|
import { recordUseful, getUsage, reuseRate, usefulCount, usefulKindFor, deleteUsage, loadReuseReport } from "./store/usage.ts";
|
|
14
14
|
import { formatReuseReport } from "./reuse-report.ts";
|
|
15
15
|
import { DEFAULT_EXPANSIONS_WEIGHT } from "./retrieve/weights.ts";
|
|
@@ -123,8 +123,9 @@ Flags:
|
|
|
123
123
|
--scope project (default), personal, or both
|
|
124
124
|
--type filter by memory type
|
|
125
125
|
--limit max results
|
|
126
|
-
--explain show the FTS expression, per-hit score,
|
|
127
|
-
lifecycle hid (superseded / retracted / archived)
|
|
126
|
+
--explain show the FTS expression, per-hit score, how many matches
|
|
127
|
+
lifecycle hid (superseded / retracted / archived), and whether
|
|
128
|
+
D79 feedback weighting moved any hit up
|
|
128
129
|
|
|
129
130
|
Example:
|
|
130
131
|
open-memex search "deploy checklist" --scope both`,
|
|
@@ -1254,8 +1255,8 @@ async function main() {
|
|
|
1254
1255
|
? [project.key]
|
|
1255
1256
|
: [project.key, PERSONAL_SCOPE.key];
|
|
1256
1257
|
const explain = flags.explain === "true";
|
|
1257
|
-
const stats = explain
|
|
1258
|
-
? { ftsQuery: "", candidates: 0, hiddenSuperseded: 0, hiddenExcluded: 0, aliasExpansions: []
|
|
1258
|
+
const stats: SearchStats | undefined = explain
|
|
1259
|
+
? { ftsQuery: "", candidates: 0, hiddenSuperseded: 0, hiddenExcluded: 0, aliasExpansions: [] }
|
|
1259
1260
|
: undefined;
|
|
1260
1261
|
const hits = search(query, {
|
|
1261
1262
|
scopeKeys: keys,
|
|
@@ -1263,6 +1264,7 @@ async function main() {
|
|
|
1263
1264
|
type: flags.type,
|
|
1264
1265
|
stats,
|
|
1265
1266
|
record: true,
|
|
1267
|
+
feedback: cfg.feedbackWeighting,
|
|
1266
1268
|
});
|
|
1267
1269
|
if (explain && stats) {
|
|
1268
1270
|
console.log(`fts: ${stats.ftsQuery || "(empty query)"}`);
|
|
@@ -1272,6 +1274,31 @@ async function main() {
|
|
|
1272
1274
|
if (stats.aliasExpansions.length > 0) {
|
|
1273
1275
|
console.log(`alias rounds: ${stats.aliasExpansions.map((q) => `"${q}"`).join(" → ")}`);
|
|
1274
1276
|
}
|
|
1277
|
+
// D79: say whether the reuse-signal nudge ran and exactly which hits it
|
|
1278
|
+
// moved. The score column below stays the raw BM25 value — feedback
|
|
1279
|
+
// reorders bands, it never edits the number.
|
|
1280
|
+
if (stats.feedback) {
|
|
1281
|
+
const fb = stats.feedback;
|
|
1282
|
+
console.log(
|
|
1283
|
+
`feedback weighting: ${
|
|
1284
|
+
fb.enabled
|
|
1285
|
+
? `on (min retrieved=${fb.minRetrieved}, band=${fb.bandRatio})`
|
|
1286
|
+
: "off (default; enable with: open-memex config set feedbackWeighting true)"
|
|
1287
|
+
}`,
|
|
1288
|
+
);
|
|
1289
|
+
if (fb.enabled) {
|
|
1290
|
+
if (fb.promotions.length === 0) {
|
|
1291
|
+
console.log(" no hits moved by reuse signal");
|
|
1292
|
+
} else {
|
|
1293
|
+
for (const p of fb.promotions) {
|
|
1294
|
+
const rate = p.rate === null ? "n/a" : p.rate.toFixed(2);
|
|
1295
|
+
console.log(
|
|
1296
|
+
` ↑ ${p.id} +${p.promoted} (reuse ${rate}, retrieved=${p.retrieved}, useful=${p.useful})`,
|
|
1297
|
+
);
|
|
1298
|
+
}
|
|
1299
|
+
}
|
|
1300
|
+
}
|
|
1301
|
+
}
|
|
1275
1302
|
// D83: which indexed column each hit matched on. `expansion` means the
|
|
1276
1303
|
// hit only surfaced through a D80 derived variant, so it ranks below an
|
|
1277
1304
|
// equal body match by construction (BM25_WEIGHTS) — this is how a
|
package/src/config.ts
CHANGED
|
@@ -31,6 +31,13 @@ export interface MyOMemoryConfig {
|
|
|
31
31
|
*/
|
|
32
32
|
graphOutline: boolean;
|
|
33
33
|
graphOutlineLines: number;
|
|
34
|
+
/**
|
|
35
|
+
* D79 (first slice): reorder near-tied BM25 hits by D77 reuse_rate. Off by
|
|
36
|
+
* default — the counters start empty on a new install, and the loop is
|
|
37
|
+
* only worth trusting once explicit useful signals exist. Flat key, so
|
|
38
|
+
* `loadConfig`'s shallow merge cannot drop it.
|
|
39
|
+
*/
|
|
40
|
+
feedbackWeighting: boolean;
|
|
34
41
|
/** Patterns whose capture group 1 becomes the memory body; saved to the current scope. */
|
|
35
42
|
keywordPatterns: string[];
|
|
36
43
|
/** Same shape, but hits are forced into the personal scope (e.g. "remember for me"). */
|
|
@@ -63,6 +70,7 @@ export const DEFAULT_CONFIG: MyOMemoryConfig = {
|
|
|
63
70
|
workingStateTtlDays: 7,
|
|
64
71
|
graphOutline: true,
|
|
65
72
|
graphOutlineLines: 10,
|
|
73
|
+
feedbackWeighting: false,
|
|
66
74
|
keywordPatterns: [
|
|
67
75
|
"^\\s*remember(?!\\s+for\\s+me)(?:\\s+that|\\s+to)?[:,]?\\s+(.+)$",
|
|
68
76
|
"^\\s*(?:please\\s+)?note(?:\\s+that)?[:,]?\\s+(.+)$",
|
|
@@ -210,6 +218,7 @@ export const SETTABLE_KEYS: Record<string, (v: unknown) => unknown> = {
|
|
|
210
218
|
return n;
|
|
211
219
|
},
|
|
212
220
|
graphOutline: toBool,
|
|
221
|
+
feedbackWeighting: toBool,
|
|
213
222
|
graphOutlineLines: (v) => {
|
|
214
223
|
const n = toNonNegInt(v);
|
|
215
224
|
if (n < 1) throw new Error("must be a positive integer (topic lines)");
|
package/src/mcp.ts
CHANGED
|
@@ -240,7 +240,7 @@ export async function runMcpServer() {
|
|
|
240
240
|
inputSchema: z.object(memorySearchArgs),
|
|
241
241
|
annotations: { readOnlyHint: true, openWorldHint: false },
|
|
242
242
|
},
|
|
243
|
-
withSync((args) => toMcp(searchMemories(getScope, args))),
|
|
243
|
+
withSync((args) => toMcp(searchMemories(getScope, cfg, args))),
|
|
244
244
|
);
|
|
245
245
|
|
|
246
246
|
server.registerTool(
|