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/CHANGELOG.md
CHANGED
|
@@ -9,6 +9,8 @@ the `@alpha` tag are development snapshots and are not listed individually.
|
|
|
9
9
|
|
|
10
10
|
## [Unreleased]
|
|
11
11
|
|
|
12
|
+
- D79 feedback-weighted ranking, first slice: `search()` can now reorder near-tied BM25 hits by the D77 reuse signal. A memory with `retrieved_count >= 3` and a higher `reuse_rate` moves ahead of equally relevant hits inside the same 25%-score band; the BM25 score is never modified, review tiers are never crossed, and hits with too little telemetry keep their exact BM25 slot (no cold-start penalty). Off by default (`feedbackWeighting: false`, a flat key settable with `config set`), because the counters start empty and the loop is only worth trusting once explicit useful signals exist. Guardrails unchanged: only `memory_useful`, a human approve at review, or a supersede raise usefulness — passive exposure only increments `retrieved_count`. `search --explain` reports whether weighting ran and lists every promoted hit with its reuse rate and move size. Fixture grows to 60 memories / 47 queries with a 3-query reuse slice; measured baseline (off) R@1 0.660 / R@5 0.979 / MRR 0.804 → weighted R@1 0.702 / R@5 0.979 / MRR 0.825 (feedback slice MRR 0.500 → 0.833). Pure band logic in `src/retrieve/feedback.ts`, smoke-tested without SQLite.
|
|
13
|
+
|
|
12
14
|
## [0.9.0] - 2026-11-06
|
|
13
15
|
|
|
14
16
|
- Session working-state note (D89 → D90, new minor line): one ephemeral per-project Markdown note for resuming an interrupted task — task summary, open files, last commands, where the work stands, next step. The agent writes it at wrap-up via the new **`memory_workingstate`** tool (now the **twelve** tools on both the opencode plugin and the MCP server), it surfaces once at session start next to the first-turn injection (framed as scratch, never knowledge), it never enters `memories/` or the retrieval index or the review ladder, and anything in it worth keeping goes through the normal propose-first flow. TTL defaults to 7 days (`workingStateTtlDays`; `workingStateEnabled` gates the whole feature — both flat keys, settable via `config set`). Expired notes stay silent at session start and are reported by `open-memex audit`; `open-memex wstate` (`--clear`) is the human surface. The write passes through `redact()` and `atomicWriteTextSync` like every path. One correction to D89's wording, recorded as D90: the opencode plugin API has no Stop hook, so the opencode write path is the instruction + tool branch (the agent refreshes the note when the user signals wrap-up); Claude Code's Stop hook waits for the Phase 2C native plugin.
|
package/README.md
CHANGED
|
@@ -570,16 +570,26 @@ the opencode plugin injects it directly on the first turn.
|
|
|
570
570
|
### Retrieval evaluation
|
|
571
571
|
|
|
572
572
|
We measure recall on a checked-in synthetic fixture instead of asserting it:
|
|
573
|
-
|
|
574
|
-
cross-language hard cases, synonym-only queries,
|
|
575
|
-
|
|
573
|
+
60 memories + 47 queries (exact terms, paraphrases, synonyms, Chinese,
|
|
574
|
+
cross-language hard cases, synonym-only queries, D81 user-defined alias
|
|
575
|
+
queries, and a D79 reuse-signal slice) — reproduce with
|
|
576
576
|
`node --experimental-strip-types scripts/retrieval-eval.ts`.
|
|
577
577
|
Current baseline, with index-time synonym/translation expansion (D80) and
|
|
578
|
-
query-time user alias expansion (D81):
|
|
579
|
-
**recall@1 0.
|
|
578
|
+
query-time user alias expansion (D81), feedback weighting off by default:
|
|
579
|
+
**recall@1 0.66, recall@5 0.98, MRR 0.80**.
|
|
580
580
|
Small synthetic corpus, so read it as a regression guard and a starting point,
|
|
581
581
|
not a real-world claim.
|
|
582
582
|
|
|
583
|
+
Optional feedback weighting (D79, first slice, **off by default**) breaks
|
|
584
|
+
near-ties among BM25 hits using the D77 reuse counters: a memory with at least
|
|
585
|
+
3 recorded retrievals and a higher `reuse_rate` moves ahead inside the same
|
|
586
|
+
25%-score band. It never edits the BM25 score, never crosses a review tier,
|
|
587
|
+
never reorders hits with too little telemetry (new memories keep their exact
|
|
588
|
+
BM25 slot), and usefulness still comes only from explicit signals — passive
|
|
589
|
+
retrieval exposure never counts. Enable with
|
|
590
|
+
`open-memex config set feedbackWeighting true`; `search --explain` shows every
|
|
591
|
+
promotion.
|
|
592
|
+
|
|
583
593
|
Three layers, each covering what the others miss: **BM25 keyword search**
|
|
584
594
|
(SQLite FTS5 — exact words, fast, explainable via `search --explain`);
|
|
585
595
|
**synonym expansion in two halves** — (a) index-time (D80: a curated,
|
|
@@ -706,6 +716,7 @@ Defaults:
|
|
|
706
716
|
"logLevel": "info", // info | debug
|
|
707
717
|
"graphOutline": true, // inject the compiled graph outline at session start
|
|
708
718
|
"graphOutlineLines": 10, // outline length cap (max 30)
|
|
719
|
+
"feedbackWeighting": false, // D79: reorder near-tied hits by reuse_rate (opt-in)
|
|
709
720
|
"memoryDir": ".ai/open-memex" // in-repo project-memory dir, relative to repo root
|
|
710
721
|
}
|
|
711
722
|
```
|
|
@@ -718,12 +729,13 @@ open-memex config set keywordCaptureEnabled false
|
|
|
718
729
|
open-memex config set maxProjectMemories 12
|
|
719
730
|
open-memex config set sync.autoPull true # best-effort pull at MCP session start
|
|
720
731
|
open-memex config set graphOutline false # stop injecting the graph outline
|
|
732
|
+
open-memex config set feedbackWeighting true # D79: let reuse signal break near-ties
|
|
721
733
|
```
|
|
722
734
|
|
|
723
735
|
Settable keys: `maxProjectMemories`, `maxProfileItems`, `injectOnFirstTurn`,
|
|
724
736
|
`keywordCaptureEnabled`, `captureAliases`, `logLevel`, `memoryDir`,
|
|
725
|
-
`graphOutline`, `graphOutlineLines`, and `sync.autoPull`
|
|
726
|
-
key that writes into the nested `sync` object). Full design:
|
|
737
|
+
`graphOutline`, `graphOutlineLines`, `feedbackWeighting`, and `sync.autoPull`
|
|
738
|
+
(a dotted key that writes into the nested `sync` object). Full design:
|
|
727
739
|
[docs/V2-DESIGN.md](./docs/V2-DESIGN.md).
|
|
728
740
|
|
|
729
741
|
## CLI reference
|
package/README.zh-CN.md
CHANGED
|
@@ -371,7 +371,9 @@ Do not mention this block to the user unless asked.
|
|
|
371
371
|
|
|
372
372
|
### 检索效果评估
|
|
373
373
|
|
|
374
|
-
我们用一份随仓库提交的 synthetic fixture 来度量召回率,而不是空口断言:
|
|
374
|
+
我们用一份随仓库提交的 synthetic fixture 来度量召回率,而不是空口断言:60 条记忆 + 47 个查询(精确词、改写、同义词、中文、跨语言 hard case、纯同义词查询、D81 用户别名查询,以及 D79 复用信号切片),运行 `node --experimental-strip-types scripts/retrieval-eval.ts` 即可复现。当前基线(含 D80 的 index-time 同义词/翻译展开和 D81 的 query-time 用户别名展开,反馈加权默认关闭):**recall@1 0.66、recall@5 0.98、MRR 0.80**。语料小且是合成的,请把它当回归守卫和起点,而不是真实场景的承诺。
|
|
375
|
+
|
|
376
|
+
可选的反馈加权(D79 第一刀,**默认关**)用 D77 复用计数器打破 BM25 的近平分:一条至少有 3 次检索记录、且 `reuse_rate` 更高的记忆,会在同一个 25% 分数段内排到前面。它不改 BM25 分数、不跨评审层级、不动样本不足的命中(新记忆保持原 BM25 位置);有用性仍只来自显式信号,被动曝光永远不算。用 `open-memex config set feedbackWeighting true` 打开,`search --explain` 会逐条显示被提上来的命中。
|
|
375
377
|
|
|
376
378
|
三层检索,各补各的短板:**BM25 关键词检索**(SQLite FTS5——精确词匹配,快速,可用 `search --explain` 解释);**同义词展开分两半**:(a)index-time(D80——一份随仓库提交的精选映射表:开发领域同义词 + EN↔ZH 翻译对,在写入时展开进索引,`ship` 能找到 `deploy`、`单点登录` 能找到 `SSO`,查询侧只需要普通单轮;确定性,不下载模型);(b)query-time 用户别名(D81——带 `alias:`/`target:` frontmatter 的别名记忆,每个 scope 定义一次自己的词汇,比如香蕉计划→支付系统重构项目;查询提到任一侧就触发对另一侧的第二轮搜索,双向,与第一轮等权重合并,别名命中不降权;别名变更不用 reindex);**语义向量**作为 opt-in 实验(本地多语言 embedding,在跨语言 fixture 切片上 R@5 92.7%——见 `docs/retrieval-ablation-study.md` §4.7;未经你明确允许绝不下载 embedding 模型)。
|
|
377
379
|
|
|
@@ -437,6 +439,7 @@ npm install -g open-memex@latest # 或 @alpha
|
|
|
437
439
|
"logLevel": "info", // info | debug
|
|
438
440
|
"graphOutline": true, // 会话开始时注入图谱编译大纲
|
|
439
441
|
"graphOutlineLines": 10, // 大纲长度上限(最大 30)
|
|
442
|
+
"feedbackWeighting": false, // D79:按 reuse_rate 调整近平分命中顺序(默认关)
|
|
440
443
|
"memoryDir": ".ai/open-memex" // 仓库内项目记忆目录,相对于仓库根
|
|
441
444
|
}
|
|
442
445
|
```
|
|
@@ -448,9 +451,10 @@ open-memex config set keywordCaptureEnabled false
|
|
|
448
451
|
open-memex config set maxProjectMemories 12
|
|
449
452
|
open-memex config set sync.autoPull true # MCP 会话开始时尽力而为地 pull
|
|
450
453
|
open-memex config set graphOutline false # 不再注入图谱大纲
|
|
454
|
+
open-memex config set feedbackWeighting true # D79:让复用信号打破近平分
|
|
451
455
|
```
|
|
452
456
|
|
|
453
|
-
可设置的键:`maxProjectMemories`、`maxProfileItems`、`injectOnFirstTurn`、`keywordCaptureEnabled`、`captureAliases`、`logLevel`、`memoryDir`、`graphOutline`、`graphOutlineLines`,以及 `sync.autoPull`(带点的键,写入嵌套的 `sync` 对象)。完整设计:[docs/V2-DESIGN.md](./docs/V2-DESIGN.md)(英文)。
|
|
457
|
+
可设置的键:`maxProjectMemories`、`maxProfileItems`、`injectOnFirstTurn`、`keywordCaptureEnabled`、`captureAliases`、`logLevel`、`memoryDir`、`graphOutline`、`graphOutlineLines`、`feedbackWeighting`,以及 `sync.autoPull`(带点的键,写入嵌套的 `sync` 对象)。完整设计:[docs/V2-DESIGN.md](./docs/V2-DESIGN.md)(英文)。
|
|
454
458
|
|
|
455
459
|
## CLI 参考
|
|
456
460
|
|
package/dist/.build-stamp
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
|
|
1
|
+
464868e10d99af47b99de7f97f1608d72bb591175a2be1dfc392cae9792d1934
|
package/dist/cli.js
CHANGED
|
@@ -107,8 +107,9 @@ Flags:
|
|
|
107
107
|
--scope project (default), personal, or both
|
|
108
108
|
--type filter by memory type
|
|
109
109
|
--limit max results
|
|
110
|
-
--explain show the FTS expression, per-hit score,
|
|
111
|
-
lifecycle hid (superseded / retracted / archived)
|
|
110
|
+
--explain show the FTS expression, per-hit score, how many matches
|
|
111
|
+
lifecycle hid (superseded / retracted / archived), and whether
|
|
112
|
+
D79 feedback weighting moved any hit up
|
|
112
113
|
|
|
113
114
|
Example:
|
|
114
115
|
open-memex search "deploy checklist" --scope both`,
|
|
@@ -1136,6 +1137,7 @@ async function main() {
|
|
|
1136
1137
|
type: flags.type,
|
|
1137
1138
|
stats,
|
|
1138
1139
|
record: true,
|
|
1140
|
+
feedback: cfg.feedbackWeighting,
|
|
1139
1141
|
});
|
|
1140
1142
|
if (explain && stats) {
|
|
1141
1143
|
console.log(`fts: ${stats.ftsQuery || "(empty query)"}`);
|
|
@@ -1143,6 +1145,26 @@ async function main() {
|
|
|
1143
1145
|
if (stats.aliasExpansions.length > 0) {
|
|
1144
1146
|
console.log(`alias rounds: ${stats.aliasExpansions.map((q) => `"${q}"`).join(" → ")}`);
|
|
1145
1147
|
}
|
|
1148
|
+
// D79: say whether the reuse-signal nudge ran and exactly which hits it
|
|
1149
|
+
// moved. The score column below stays the raw BM25 value — feedback
|
|
1150
|
+
// reorders bands, it never edits the number.
|
|
1151
|
+
if (stats.feedback) {
|
|
1152
|
+
const fb = stats.feedback;
|
|
1153
|
+
console.log(`feedback weighting: ${fb.enabled
|
|
1154
|
+
? `on (min retrieved=${fb.minRetrieved}, band=${fb.bandRatio})`
|
|
1155
|
+
: "off (default; enable with: open-memex config set feedbackWeighting true)"}`);
|
|
1156
|
+
if (fb.enabled) {
|
|
1157
|
+
if (fb.promotions.length === 0) {
|
|
1158
|
+
console.log(" no hits moved by reuse signal");
|
|
1159
|
+
}
|
|
1160
|
+
else {
|
|
1161
|
+
for (const p of fb.promotions) {
|
|
1162
|
+
const rate = p.rate === null ? "n/a" : p.rate.toFixed(2);
|
|
1163
|
+
console.log(` ↑ ${p.id} +${p.promoted} (reuse ${rate}, retrieved=${p.retrieved}, useful=${p.useful})`);
|
|
1164
|
+
}
|
|
1165
|
+
}
|
|
1166
|
+
}
|
|
1167
|
+
}
|
|
1146
1168
|
// D83: which indexed column each hit matched on. `expansion` means the
|
|
1147
1169
|
// hit only surfaced through a D80 derived variant, so it ranks below an
|
|
1148
1170
|
// equal body match by construction (BM25_WEIGHTS) — this is how a
|
package/dist/config.js
CHANGED
|
@@ -11,6 +11,7 @@ export const DEFAULT_CONFIG = {
|
|
|
11
11
|
workingStateTtlDays: 7,
|
|
12
12
|
graphOutline: true,
|
|
13
13
|
graphOutlineLines: 10,
|
|
14
|
+
feedbackWeighting: false,
|
|
14
15
|
keywordPatterns: [
|
|
15
16
|
"^\\s*remember(?!\\s+for\\s+me)(?:\\s+that|\\s+to)?[:,]?\\s+(.+)$",
|
|
16
17
|
"^\\s*(?:please\\s+)?note(?:\\s+that)?[:,]?\\s+(.+)$",
|
|
@@ -162,6 +163,7 @@ export const SETTABLE_KEYS = {
|
|
|
162
163
|
return n;
|
|
163
164
|
},
|
|
164
165
|
graphOutline: toBool,
|
|
166
|
+
feedbackWeighting: toBool,
|
|
165
167
|
graphOutlineLines: (v) => {
|
|
166
168
|
const n = toNonNegInt(v);
|
|
167
169
|
if (n < 1)
|
package/dist/mcp.js
CHANGED
|
@@ -185,7 +185,7 @@ export async function runMcpServer() {
|
|
|
185
185
|
description: TOOL_DESCRIPTIONS.memory_search,
|
|
186
186
|
inputSchema: z.object(memorySearchArgs),
|
|
187
187
|
annotations: { readOnlyHint: true, openWorldHint: false },
|
|
188
|
-
}, withSync((args) => toMcp(searchMemories(getScope, args))));
|
|
188
|
+
}, withSync((args) => toMcp(searchMemories(getScope, cfg, args))));
|
|
189
189
|
server.registerTool("memory_list", {
|
|
190
190
|
description: TOOL_DESCRIPTIONS.memory_list,
|
|
191
191
|
inputSchema: z.object(memoryListArgs),
|
|
@@ -0,0 +1,95 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* D79 (first slice): reuse-signal ranking.
|
|
3
|
+
*
|
|
4
|
+
* D77-L2 already records `retrieved_count` (exposure) and the useful split
|
|
5
|
+
* (explicit confirmations only). This module turns that telemetry into a
|
|
6
|
+
* deliberately small ranking nudge: inside a near-tied BM25 band, memories
|
|
7
|
+
* with a high `reuse_rate` move ahead of equally relevant memories that were
|
|
8
|
+
* only ever retrieved.
|
|
9
|
+
*
|
|
10
|
+
* Guardrails (D77, non-negotiable):
|
|
11
|
+
* - the score itself is never modified — feedback only reorders a band, so
|
|
12
|
+
* `search --explain` still shows the raw BM25 number;
|
|
13
|
+
* - only memories with `retrieved_count >= FEEDBACK_MIN_RETRIEVED` participate;
|
|
14
|
+
* new/rare memories keep their exact BM25 slot (no cold-start penalty),
|
|
15
|
+
* and an eligible run never jumps over one of them;
|
|
16
|
+
* - `reuse_rate` is signal strength, not a probability (it may exceed 1.0);
|
|
17
|
+
* it is never used as a hard prune threshold;
|
|
18
|
+
* - band membership is anchored to the band head's score, so a large score gap
|
|
19
|
+
* cannot be crossed. Review tiers are reordered separately by search.ts —
|
|
20
|
+
* feedback never lifts a draft over reviewed knowledge.
|
|
21
|
+
*
|
|
22
|
+
* Pure by construction: smoke-pure.ts tests it without opening SQLite.
|
|
23
|
+
*/
|
|
24
|
+
/** Minimum exposure before a memory may be reordered by feedback. */
|
|
25
|
+
export const FEEDBACK_MIN_RETRIEVED = 3;
|
|
26
|
+
/**
|
|
27
|
+
* A hit is in the same band as the band head while its score is at least
|
|
28
|
+
* this fraction of the head's. 0.75 = within 25%, i.e. a near-tie, not a
|
|
29
|
+
* relevance gap. Measured on the D79 fixture (see docs/design/decisions.md).
|
|
30
|
+
*/
|
|
31
|
+
export const DEFAULT_FEEDBACK_BAND_RATIO = 0.75;
|
|
32
|
+
/**
|
|
33
|
+
* Reorder one review tier. Callers pass a tier's hits in BM25 order. Within
|
|
34
|
+
* each near-tied band, only contiguous runs of eligible hits are re-sorted by
|
|
35
|
+
* reuse_rate (descending, stable); ineligible hits keep their exact slot. So a
|
|
36
|
+
* memory with too little telemetry is never pushed down by this mechanism.
|
|
37
|
+
*/
|
|
38
|
+
export function applyFeedbackRanking(hits, usage, opts = {}) {
|
|
39
|
+
const minRetrieved = opts.minRetrieved ?? FEEDBACK_MIN_RETRIEVED;
|
|
40
|
+
const bandRatio = opts.bandRatio ?? DEFAULT_FEEDBACK_BAND_RATIO;
|
|
41
|
+
const info = new Map();
|
|
42
|
+
for (const h of hits) {
|
|
43
|
+
const u = usage.get(h.id);
|
|
44
|
+
const retrieved = Math.max(0, Number(u?.retrieved) || 0);
|
|
45
|
+
const useful = Math.max(0, Number(u?.useful) || 0);
|
|
46
|
+
const rate = retrieved > 0 ? useful / retrieved : null;
|
|
47
|
+
info.set(h.id, {
|
|
48
|
+
retrieved,
|
|
49
|
+
useful,
|
|
50
|
+
rate,
|
|
51
|
+
eligible: retrieved >= minRetrieved,
|
|
52
|
+
});
|
|
53
|
+
}
|
|
54
|
+
const ordered = [];
|
|
55
|
+
let i = 0;
|
|
56
|
+
while (i < hits.length) {
|
|
57
|
+
const head = hits[i];
|
|
58
|
+
const threshold = head.score > 0 ? head.score * bandRatio : head.score;
|
|
59
|
+
let j = i + 1;
|
|
60
|
+
while (j < hits.length && hits[j].score >= threshold)
|
|
61
|
+
j++;
|
|
62
|
+
const band = hits.slice(i, j);
|
|
63
|
+
ordered.push(...reorderBand(band, info));
|
|
64
|
+
i = j;
|
|
65
|
+
}
|
|
66
|
+
return { ordered, info };
|
|
67
|
+
}
|
|
68
|
+
function reorderBand(band, info) {
|
|
69
|
+
if (band.length < 2)
|
|
70
|
+
return [...band];
|
|
71
|
+
const out = [...band];
|
|
72
|
+
let i = 0;
|
|
73
|
+
while (i < band.length) {
|
|
74
|
+
if (!info.get(band[i].id).eligible) {
|
|
75
|
+
i++;
|
|
76
|
+
continue;
|
|
77
|
+
}
|
|
78
|
+
let j = i + 1;
|
|
79
|
+
while (j < band.length && info.get(band[j].id).eligible)
|
|
80
|
+
j++;
|
|
81
|
+
if (j - i > 1) {
|
|
82
|
+
// Stable sort of the run only. Ineligible hits are barriers, so a run
|
|
83
|
+
// can never jump over a memory with too little telemetry.
|
|
84
|
+
const run = band.slice(i, j).map((h, k) => ({ h, k }));
|
|
85
|
+
run.sort((a, b) => {
|
|
86
|
+
const ra = info.get(a.h.id).rate ?? 0;
|
|
87
|
+
const rb = info.get(b.h.id).rate ?? 0;
|
|
88
|
+
return ra !== rb ? rb - ra : a.k - b.k;
|
|
89
|
+
});
|
|
90
|
+
run.forEach((x, k) => (out[i + k] = x.h));
|
|
91
|
+
}
|
|
92
|
+
i = j;
|
|
93
|
+
}
|
|
94
|
+
return out;
|
|
95
|
+
}
|
package/dist/retrieve/search.js
CHANGED
|
@@ -2,7 +2,8 @@ import { db } from "../store/db.js";
|
|
|
2
2
|
import { toFtsQuery } from "./query.js";
|
|
3
3
|
import { BM25_WEIGHTS } from "./weights.js";
|
|
4
4
|
import { loadAliasEntries, planAliasExpansions, mergeRounds, } from "./alias-memory.js";
|
|
5
|
-
import { recordRetrieved } from "../store/usage.js";
|
|
5
|
+
import { recordRetrieved, loadUsageForIds, usefulCount } from "../store/usage.js";
|
|
6
|
+
import { applyFeedbackRanking, FEEDBACK_MIN_RETRIEVED, DEFAULT_FEEDBACK_BAND_RATIO, } from "./feedback.js";
|
|
6
7
|
function toHit(r) {
|
|
7
8
|
const aliases = r.aliases ? r.aliases.split(",").map((a) => a.trim()).filter(Boolean) : [];
|
|
8
9
|
let snippet = r.snippet ?? "";
|
|
@@ -78,15 +79,7 @@ export function hitStateLabel(h) {
|
|
|
78
79
|
return "";
|
|
79
80
|
return ` [${h.review_state || "draft"}]`;
|
|
80
81
|
}
|
|
81
|
-
|
|
82
|
-
* Lifecycle-aware post-processing (§3.3):
|
|
83
|
-
* - retracted / archived are excluded from retrieval (kept for audit);
|
|
84
|
-
* - a superseded memory resolves to the newest of its chain (cycle-safe);
|
|
85
|
-
* - D30: approved/published project memories rank first, project
|
|
86
|
-
* drafts/rejected rank after unreviewed content;
|
|
87
|
-
* - deprecated stays visible as a warning but ranks after active.
|
|
88
|
-
*/
|
|
89
|
-
function resolveVisible(rows, limit, stats) {
|
|
82
|
+
function resolveVisible(rows, limit, stats, feedback) {
|
|
90
83
|
const byId = new Map(rows.map((r) => [r.id, r]));
|
|
91
84
|
const fullRow = (id) => {
|
|
92
85
|
const cached = byId.get(id);
|
|
@@ -140,7 +133,49 @@ function resolveVisible(rows, limit, stats) {
|
|
|
140
133
|
else
|
|
141
134
|
tiers[reviewTier(target)].push(hit);
|
|
142
135
|
}
|
|
143
|
-
|
|
136
|
+
// D79: tiers are reordered independently, so feedback can never lift a
|
|
137
|
+
// draft over reviewed knowledge. Without feedback this is exactly the old
|
|
138
|
+
// concatenation.
|
|
139
|
+
const before = [...tiers[0], ...tiers[1], ...tiers[2], ...deprecated];
|
|
140
|
+
if (!feedback)
|
|
141
|
+
return before.slice(0, limit);
|
|
142
|
+
const usageById = loadUsageForIds(before.map((h) => h.id));
|
|
143
|
+
const signals = new Map();
|
|
144
|
+
for (const [id, u] of usageById) {
|
|
145
|
+
signals.set(id, { retrieved: u.retrieved_count, useful: usefulCount(u) });
|
|
146
|
+
}
|
|
147
|
+
const beforeRank = new Map(before.map((h, i) => [h.id, i]));
|
|
148
|
+
const infoById = new Map();
|
|
149
|
+
const ordered = [];
|
|
150
|
+
for (const tier of [...tiers, deprecated]) {
|
|
151
|
+
const r = applyFeedbackRanking(tier, signals, feedback);
|
|
152
|
+
ordered.push(...r.ordered);
|
|
153
|
+
for (const [id, info] of r.info)
|
|
154
|
+
infoById.set(id, info);
|
|
155
|
+
}
|
|
156
|
+
ordered.forEach((h, i) => {
|
|
157
|
+
const info = infoById.get(h.id);
|
|
158
|
+
if (!info)
|
|
159
|
+
return;
|
|
160
|
+
h.feedback = { ...info, promoted: (beforeRank.get(h.id) ?? i) - i };
|
|
161
|
+
});
|
|
162
|
+
if (stats) {
|
|
163
|
+
stats.feedback = {
|
|
164
|
+
enabled: true,
|
|
165
|
+
minRetrieved: feedback.minRetrieved ?? FEEDBACK_MIN_RETRIEVED,
|
|
166
|
+
bandRatio: feedback.bandRatio ?? DEFAULT_FEEDBACK_BAND_RATIO,
|
|
167
|
+
promotions: ordered
|
|
168
|
+
.filter((h) => (h.feedback?.promoted ?? 0) > 0)
|
|
169
|
+
.map((h) => ({
|
|
170
|
+
id: h.id,
|
|
171
|
+
promoted: h.feedback.promoted,
|
|
172
|
+
rate: h.feedback.rate,
|
|
173
|
+
retrieved: h.feedback.retrieved,
|
|
174
|
+
useful: h.feedback.useful,
|
|
175
|
+
})),
|
|
176
|
+
};
|
|
177
|
+
}
|
|
178
|
+
return ordered.slice(0, limit);
|
|
144
179
|
}
|
|
145
180
|
/**
|
|
146
181
|
* FTS5 query construction lives in query.ts (pure, unit-tested): free-text
|
|
@@ -156,6 +191,12 @@ export function search(query, opts = {}) {
|
|
|
156
191
|
opts.stats.hiddenSuperseded = 0;
|
|
157
192
|
opts.stats.hiddenExcluded = 0;
|
|
158
193
|
opts.stats.aliasExpansions = [];
|
|
194
|
+
opts.stats.feedback = {
|
|
195
|
+
enabled: opts.feedback === true,
|
|
196
|
+
minRetrieved: opts.feedbackMinRetrieved ?? FEEDBACK_MIN_RETRIEVED,
|
|
197
|
+
bandRatio: opts.feedbackBandRatio ?? DEFAULT_FEEDBACK_BAND_RATIO,
|
|
198
|
+
promotions: [],
|
|
199
|
+
};
|
|
159
200
|
}
|
|
160
201
|
if (!q)
|
|
161
202
|
return [];
|
|
@@ -233,7 +274,10 @@ export function search(query, opts = {}) {
|
|
|
233
274
|
// without a user alias the query side stays a single FTS round.
|
|
234
275
|
if (opts.stats)
|
|
235
276
|
opts.stats.candidates = merged.length;
|
|
236
|
-
const
|
|
277
|
+
const feedback = opts.feedback === true
|
|
278
|
+
? { minRetrieved: opts.feedbackMinRetrieved, bandRatio: opts.feedbackBandRatio }
|
|
279
|
+
: undefined;
|
|
280
|
+
const hits = resolveVisible(merged, limit, opts.stats, feedback);
|
|
237
281
|
// D77-L2: record only the ids actually returned — the candidate pool is
|
|
238
282
|
// not an exposure, and #53 guarantees the cut below is the final result.
|
|
239
283
|
if (opts.record && hits.length > 0)
|
package/dist/store/usage.js
CHANGED
|
@@ -99,6 +99,29 @@ export function recordUseful(id, kind, _via, atMs = Date.now()) {
|
|
|
99
99
|
// getUsage cannot miss the row just upserted.
|
|
100
100
|
return getUsage(id);
|
|
101
101
|
}
|
|
102
|
+
/**
|
|
103
|
+
* D79: batch-read the counters a search ranking needs, keyed by id. One
|
|
104
|
+
* query per retrieval pass, not one per candidate; missing ids are simply
|
|
105
|
+
* absent (no exposure yet), never synthesized.
|
|
106
|
+
*/
|
|
107
|
+
export function loadUsageForIds(ids) {
|
|
108
|
+
const unique = [...new Set(ids)];
|
|
109
|
+
if (unique.length === 0)
|
|
110
|
+
return new Map();
|
|
111
|
+
const rows = db()
|
|
112
|
+
.prepare(`SELECT id, retrieved_count, useful_self, useful_team,
|
|
113
|
+
last_retrieved_at, last_useful_at, updated_at
|
|
114
|
+
FROM memory_usage WHERE id IN (${unique.map(() => "?").join(",")})`)
|
|
115
|
+
.all(...unique);
|
|
116
|
+
const map = new Map();
|
|
117
|
+
for (const row of rows) {
|
|
118
|
+
row.retrieved_count = Number(row.retrieved_count) || 0;
|
|
119
|
+
row.useful_self = Number(row.useful_self) || 0;
|
|
120
|
+
row.useful_team = Number(row.useful_team) || 0;
|
|
121
|
+
map.set(row.id, row);
|
|
122
|
+
}
|
|
123
|
+
return map;
|
|
124
|
+
}
|
|
102
125
|
export function getUsage(id) {
|
|
103
126
|
const row = db()
|
|
104
127
|
.prepare(`SELECT id, retrieved_count, useful_self, useful_team,
|
package/dist/tools/memory.js
CHANGED
package/dist/tools/ops.js
CHANGED
|
@@ -304,7 +304,7 @@ export async function addMemory(getScope, cfg, args) {
|
|
|
304
304
|
}
|
|
305
305
|
return { title: `memory: saved ${fm.id}`, output };
|
|
306
306
|
}
|
|
307
|
-
export async function searchMemories(getScope, args) {
|
|
307
|
+
export async function searchMemories(getScope, cfg, args) {
|
|
308
308
|
const project = getScope();
|
|
309
309
|
const scopeKeys = args.scope === "personal"
|
|
310
310
|
? [PERSONAL_SCOPE.key]
|
|
@@ -317,6 +317,7 @@ export async function searchMemories(getScope, args) {
|
|
|
317
317
|
limit: args.limit,
|
|
318
318
|
type: args.type,
|
|
319
319
|
record: true,
|
|
320
|
+
feedback: cfg.feedbackWeighting,
|
|
320
321
|
});
|
|
321
322
|
if (hits.length === 0) {
|
|
322
323
|
return {
|
package/docs/V2-DESIGN.md
CHANGED
|
@@ -580,9 +580,9 @@ requirement: personal data never touches third-party services). Benchmarks to tr
|
|
|
580
580
|
- **Phase 4 — Future, signal-gated.** Cloud `RemoteProvider` customization only on: multi-private-repo
|
|
581
581
|
sharing needs, fine-grained ACL, audit/compliance mandates · optional API-backed exporters/providers
|
|
582
582
|
for enterprise knowledge systems.
|
|
583
|
-
- **Near-term backlog — committed direction, not yet built (2026-10-07).** Stone's rule: anything said as "later" is written down here. D77-L2 ✅ built 2026-11-03 (0.9.0-alpha.2): per-memory `retrieved_count`/`useful_count` (`useful_self` vs `useful_team`) + `memory_useful` tool, counters in a `memory_usage` table beside the rebuildable index. D77-L3 ✅ built 2026-11-04 (0.9.0-alpha.3): `memory_status`/`sync-status` reuse report — per-scope rates, top reused, zero-reuse "zombies". D77: external bench — LongMemEval-S run 2026-10-07 (`scripts/bench-longmemeval.ts`, 470 questions, recall_any@k: R@5 97.0% / MRR 0.909 per-question, R@5 40.6% on a pooled 22k corpus; ahead of agentmemory’s BM25-only, level with their BM25+vector). MemoryAgentBench still open as a second external data point. D79 follow-up SUPERSEDED → built as **D80** (2026-10-07): index-time synonym/translation expansion shipped; 41-query fixture recall@5 0.854 → 0.976, MRR 0.791 → 0.859. Embedding-model configurability (Stone 2026-10-07): the multilingual model is his personal need (EN↔ZH), not everyone’s — the model must be user-configurable. Timing: (1) NOW in the bench only — a `--model` flag to measure the multilingual tax (multilingual vs English-only on English data), which decides the DEFAULT. (2) AT SHIP TIME — `embedding.model` in `MyOMemoryConfig` + `SETTABLE_KEYS`, model-agnostic storage from day one (dim + model id stored with vectors, cache dir), download UX and `doctor` checks. Not before the gate passes: building config UX for a layer we haven’t decided to ship is premature. If multilingual tax ≈ 0, default multilingual (covers everyone); else default English-only with a docs note.D78: curate+submit — pre-submit lint, then confidence-tier auto-curation (auto-apply / batch-confirm / explicit human). D79 follow-ups: feedback-weighted ranking
|
|
583
|
+
- **Near-term backlog — committed direction, not yet built (2026-10-07).** Stone's rule: anything said as "later" is written down here. D77-L2 ✅ built 2026-11-03 (0.9.0-alpha.2): per-memory `retrieved_count`/`useful_count` (`useful_self` vs `useful_team`) + `memory_useful` tool, counters in a `memory_usage` table beside the rebuildable index. D77-L3 ✅ built 2026-11-04 (0.9.0-alpha.3): `memory_status`/`sync-status` reuse report — per-scope rates, top reused, zero-reuse "zombies". D77: external bench — LongMemEval-S run 2026-10-07 (`scripts/bench-longmemeval.ts`, 470 questions, recall_any@k: R@5 97.0% / MRR 0.909 per-question, R@5 40.6% on a pooled 22k corpus; ahead of agentmemory’s BM25-only, level with their BM25+vector). MemoryAgentBench still open as a second external data point. D79 follow-up SUPERSEDED → built as **D80** (2026-10-07): index-time synonym/translation expansion shipped; 41-query fixture recall@5 0.854 → 0.976, MRR 0.791 → 0.859. Embedding-model configurability (Stone 2026-10-07): the multilingual model is his personal need (EN↔ZH), not everyone’s — the model must be user-configurable. Timing: (1) NOW in the bench only — a `--model` flag to measure the multilingual tax (multilingual vs English-only on English data), which decides the DEFAULT. (2) AT SHIP TIME — `embedding.model` in `MyOMemoryConfig` + `SETTABLE_KEYS`, model-agnostic storage from day one (dim + model id stored with vectors, cache dir), download UX and `doctor` checks. Not before the gate passes: building config UX for a layer we haven’t decided to ship is premature. If multilingual tax ≈ 0, default multilingual (covers everyone); else default English-only with a docs note.D78: curate+submit — pre-submit lint, then confidence-tier auto-curation (auto-apply / batch-confirm / explicit human). D79 follow-ups: feedback-weighted ranking ✅ first slice built 2026-11-11 (0.10.0-alpha.2, D92): opt-in `feedbackWeighting`, near-tied BM25 band reordered by `reuse_rate` only for `retrieved_count >= 3`, explain trace, fixture R@1 0.660 → 0.702 / MRR 0.804 → 0.825; embeddings gate decision against the published baseline; reranker evaluation. Cross-lingual embedding rerank (Stone 2026-10-16, from obsidian-mind comparison): ablation showed multilingual vectors beat BM25 by +12pp R@5 on the cross-lingual slice — the one gap lexical can't cover. Design as opt-in rerank for EN↔ZH queries only, not a default path; local stays BM25-first per the retrieval split above. TDQS nit (separate PR): tighten search/list `type` to `z.enum`. Retrieval eval: grow the fixture (project-scope tier cases) as retrieval logic evolves. Retrieval split — local vs share server (Stone 2026-10-07): the two environments emphasize different mechanisms. Local (personal machine): BM25 + curated index-time expansion as the primary — deterministic, zero model download (D7), fast on CPU, index bloat bounded by the small corpus; embeddings opt-in only. Share server (team/org, enterprise): embeddings + ANN + reranker as the primary — server-grade compute with models resident, corpus too large and multi-author for any curated map; the curated map stays as a precision layer plus org glossary. The server additionally aggregates D77 useful_count across users into feedback-weighted ranking (already in D79 follow-ups) — a signal a single machine can never have. Bottom-up loop: curated pairs that many users converge on locally become org-glossary candidates. Economics flip: N users each downloading a model vs one model amortized on the server. OptMem lessons (Stone 2026-10-16, from kafkaup's OptMem post): three friction-reduction ideas worth stealing from the minimalist end of the spectrum. (1) **Token cost as spec** — measure and publish open-memex's prompt/token overhead in the README, the way OptMem advertises its "426-token prompt"; acquisition copy, not just engineering. (2) **`wake` convention** — document a session-start ritual (one `memory_recall` call at the beginning of every session), mirroring OptMem's `memo wake`; the MCP tools exist but the habit isn't specified. (3) **Capture length nudge** — a soft length cap or conciseness hint at capture time, inspired by OptMem's 280-byte hard cap; forces conciseness at write time, cheap to implement, aligned with the distill-to-AGENTS.md direction (D40). Three-tier memory zones (Stone 2026-10-18, from Westenberg "I Deleted My Second Brain" + his own reflection): the second brain should have zones like cache vs database, not "keep everything" vs "delete everything". **Hot** (active zone, cache-like: small, curated, always in context — D81 aliases, WHAT-level) · **Warm** (compost/incubation: not active but not cold; periodic review, rotted items deleted — this is "forget on purpose" as engineering) · **Cold** (full archive, searchable, not resident). The hard part is the **promotion/demotion policy** — what moves between zones, when, by what rule (the cache-replacement problem for knowledge; "useful" ≠ "recently used"). Capture restraint is a separate gate: not everything deserves to enter even cold storage. Spec the policy before building the zones. Auto-capture design brief (Stone 2026-10-19, from ai-memory comparison): open-memex wants auto-capture but under the restraint philosophy (not ai-memory's capture-everything). Five design questions: (1) **End-session trigger** — what hooks does opencode actually expose? (check before designing; ai-memory built finalize-session fallback for harnesses without SessionEnd); candidates: native hook / idle timeout / explicit command / context-near-full. (2) **Distillation** — rules first (what happened: git diff, tool calls, decision sentences; zero LLM), interpretation layer (what it means) left to human/LLM. (3) **Save-value triage** — three tiers: clearly valuable → save; clearly noise → drop; ambiguous → ask human. Boundary principle: **rather over-ask than over-save** (polluted retrieval costs more than a missed memory). (4) **Routing** — four exits: project memory / personal memory / AGENTS.md proposal (distill-agents exists) / discard; keep v1 routing rules simple. (5) **Human interaction** — one batch confirmation at session end ("save these 3? [y/n/edit]"), never per-item popups. Relations: D73 keyword capture is turn-level (no conflict); `wake` convention is session-start (this is session-end — the other bookend); three-tier zones govern where auto-captured items land. Cross-agent study (Stone 2026-10-19): open-memex has cross-agent on the roadmap — study how ai-memory does it (handoff claim-once semantics, lifecycle hooks per harness, VSCode support via MCP-only) before designing ours; borrow the semantics, not the push-injection behavior (discoverability > injection). Injection cost discipline (Stone 2026-10-19, from Harness² paper arXiv:2610.14224): "ALWAYS-ON PROSE IS THE EXPENSIVE OPTION" — every always-on word competes with the agent's output budget. Current session-start injection (8 project + 5 personal) is the expensive path; direction: move "important but not needed every turn" memories to on-demand (tool/skill-triggered loading), keep only truly every-turn items resident. Tolerable now, better not to tolerate. Component cost ladder for reference: SKILL (default, zero-cost until invoked) > SCRIPT > SUBAGENT > PLUGIN ("prose can be skipped, a hook cannot") > ALWAYS-ON TEXT (last resort). Read-less compression (Stone 2026-10-19, from caveman https://github.com/JuliusBrussee/caveman): the execution layer of injection cost discipline — compress what the agent READS before it reaches context, not just what we inject. Caveman's measured numbers: 33.2% fewer input tokens per session (CSV 98.9%, logs 98.5%, YAML 99.1%, JSON 98.5% per-file; HTML has no compressor yet). Direction for open-memex: a pre-retrieval compression pass on tool outputs and retrieved passages (structured data → compact form), originals stay on disk and pullable on demand. Two design principles borrowed: (1) never compress the user's own prompt/input (Adobe CAVEWOMAN finding: cavemanning user prompts makes answers worse); (2) leave code/tool calls/payloads verbatim — compress the wrapper, not the payload. Caveats: caveman's own rules cost ~1,160 input tokens fixed; per-request billing (Copilot-style) nullifies the saving — compression pays off on per-token billing only. Knowledge upkeep as a first-class direction (Stone 2026-10-23; external validation: Hedy Zhang's FDE field retrospective on enterprise AI knowledge bases, X article 2026-10-22 — enterprise knowledge bases die on unowned upkeep, not on retrieval: stale answers served silently, conflicts with no owner, updates nobody owns after delivery). The mechanisms already exist (supersede chains, lifecycle states, `audit` health check, curator convention); the direction is driving the human cost of upkeep toward zero: (1) staleness signals — age, contradiction with newer captures, D77 zero-reuse counters — feeding a standing review queue instead of waiting for someone to remember to run `audit`; (2) a conflict inbox — semantic conflicts and broken chains as a persistent todo; (3) the endgame is D78 confidence-tier auto-curation (auto-apply the safe tier, batch-confirm the rest). Success metric: the base stays trustworthy on minutes-per-week of human attention, not a curator shift. README pitches the shipped half of this as core concept 4 (Knowledge stays current) plus a "When facts change" comparison row. Session working state note (D89, 2026-11-02) → BUILT, shipped 2026-11-03 as D90: 12th tool `memory_workingstate` on both hosts, session-start surfacing, `audit` expiry report, `wstate` CLI; opencode write path is instruction + tool (plugin API has no Stop hook).
|
|
584
584
|
|
|
585
|
-
- **Build order after D77-L3 (2026-11-04, Stone approved; (1) shipped 2026-11-06).** Once PR #74 (D77-L3 reuse report) merges, the queue is: (1) §20 / D88 deterministic half — **shipped 0.9.0-alpha.6 (D91)**: `graph build` (structural edges only), compiled outline injected at session start, `graph neighbours` / `graph path` / `graph outline` / `graph lint` CLI (orphans / dangling / stale; missing-page alerts are part of the LLM half, still open); no LLM, no ranking change. Remaining under §20: **the LLM half** — semantic insights, missing-page alerts that propose new memories (through the D61 propose-first flow), compiled wiki pages — plus D78's pre-submit integration of the lint report. (2) D79 feedback-weighted ranking —
|
|
585
|
+
- **Build order after D77-L3 (2026-11-04, Stone approved; (1) shipped 2026-11-06).** Once PR #74 (D77-L3 reuse report) merges, the queue is: (1) §20 / D88 deterministic half — **shipped 0.9.0-alpha.6 (D91)**: `graph build` (structural edges only), compiled outline injected at session start, `graph neighbours` / `graph path` / `graph outline` / `graph lint` CLI (orphans / dangling / stale; missing-page alerts are part of the LLM half, still open); no LLM, no ranking change. Remaining under §20: **the LLM half** — semantic insights, missing-page alerts that propose new memories (through the D61 propose-first flow), compiled wiki pages — plus D78's pre-submit integration of the lint report. (2) D79 feedback-weighted ranking — **first slice shipped 0.10.0-alpha.2 (D92)**: fixture + baseline landed first, then an opt-in reuse-signal band reorder (`retrieved_count >= 3`, `reuse_rate`, 0.75 near-tie band); no embedding/cross-lingual rerank yet. (3) D78 curate+submit — the upkeep endgame; consumes §20 lint output. (4) Embeddings gate decision (bench `--model` measures the multilingual tax) + opt-in cross-lingual rerank for EN↔ZH queries only; local stays BM25-first. (5) OptMem small items — token cost in README, `wake` session-start ritual, capture length nudge. (6) Three-tier memory zones policy spec (Hot/Warm/Cold promotion/demotion rules) before building; §20's compiled outline already covers part of Hot. (7) Auto-capture design — answer the five open questions first (notably which session-end trigger opencode exposes). Then measurement/candidates: MemoryAgentBench second external data point; Phase 2C native plugins (candidate, not committed); D9 LAN reference server likely dropped; D2/D11 iron-rule gate is a known safety gap awaiting a build/drop decision. Non-code track: Phase 2B 1–2 colleague pilot (needs people, not code). Dependency chain: §20 lint → D78; D77-L2 counters → D79; gate decision → rerank. Tension to respect: §20's resident outline must stay compact per the injection-cost discipline (2026-10-19) — "important but not every turn" stays on-demand.
|
|
586
586
|
|
|
587
587
|
- **Phase 5 — Candidates recorded 2026-10-04 (not committed).** From the competitor scan (D75): an offline FTS5 retrieval eval with a published recall number (gates any semantic-layer decision) [promoted to next build, D77] · per-client trust levels on the review ladder · cold-start Markdown import into outbox drafts · `doctor` check that each editor's MCP registration points at the intended data root (mis-rooted servers are a real failure mode elsewhere). Sequencing and scope TBD per candidate.
|
|
588
588
|
- **Phase 5 — Candidates recorded 2026-10-11 (not committed).** From the XERJ review (xerj-org/xerj, Apache-2.0; founder Ivan N requested open-memex D81 for the XERJ Corpus Hub — agreed 2026-10-11, attribution + repo link): schema-first querying (`xerj_map` — agent fetches the field map before writing query DSL; candidate: a schema/describe helper ahead of `memory_search` to cut dead queries) · token-budgeted MCP results (their `token_budget.rs` — truncate to a token budget, not a fixed row limit) · hybrid retrieval as the scale answer (BM25 + vector kNN with fused ranking, e.g. RRF — the reference pattern for the eventual embedding layer; our lexical ceiling is already measured at R@5 40.6% pooled) · NL-to-validated-query planning (`xerj_plan` — natural language in, validated query out; candidate: a query lint/validate step before search executes) · evidence-carrying memory links (typed links with evidence + confidence, soft-retire never hard-delete — same spirit as our review-state ladder; prior art for a future memory-graph direction) · honest isolation docs (state what a namespace guarantees and does NOT — query-level vs trust boundary; same spirit as our Limitations section) · cost-accounted evals (report tokens + dollars per approach, as in their case studies — the format for proving "memory makes agents cheaper"). Sequencing and scope TBD per candidate.
|
package/docs/design/decisions.md
CHANGED
|
@@ -1147,3 +1147,6 @@
|
|
|
1147
1147
|
|
|
1148
1148
|
- **D91 — the knowledge graph, deterministic half (§20, 2026-11-06).** Implements the graph layer D88 designed, split at the derivation boundary: this change ships only edges the code can *prove* or derive from structure, with no LLM call anywhere. Edge extraction (`src/graph/extract.ts`, pure): (1) **supersedes** edges from the index chain (`superseded_by`, plus the reverse derived from that column — the index has no `supersedes` column), EXTRACTED/high; (2) **derived-from** edges from the propose-copy's `derived_from` frontmatter (now also an index column, schema v10), EXTRACTED/high; (3) **relates-to** edges from `[[wiki-link]]` body mentions of a node's ULID, EXTRACTED/high, and from bare ULID mentions, INFERRED/high; (4) **relates-to** from shared tags at a fixed ladder — 1 shared tag → low, 2 → medium, ≥3 → high — INFERRED, capped at `MAX_SHARED_TAG_EDGES_PER_NODE = 12` per node and `MAX_SHARED_TAG_NODES = 2000` overall so one universal tag cannot produce an O(n²) edge set; one relational edge per unordered pair, EXTRACTED beats INFERRED on the same pair. Stored in `graph_edges`/`graph_meta` beside the rebuildable index with `CREATE TABLE IF NOT EXISTS` (like `memory_usage`, D77), so the graph is derived, disposable, and never touches Markdown or the source of truth. Every mutating path refreshes it automatically (`refreshGraphQuiet` on the write hooks: add/supersede/soft + hard forget on both hosts, keyword capture, propose, review promotion, CLI add/supersede/status/forget); `refreshGraph` is the explicit `graph build` path and reports honestly (D63 — a missing id fails, findings never invent nodes). **Outline** (`src/graph/outline.ts`, pure): connected components joined **only by medium+ INFERRED shared-tag edges** (the universal-tag collapse guard — a single low/medium tag must not merge unrelated memories; fixture-pinned in `smoke-pure.ts`), rendered `topic (n): titles…` with the cut disclosed at `maxLines` (config `graphOutlineLines`, default 10, cap 30); the compiled outline is stored in `graph_meta` and injected once at session start next to the working-state note (`graphOutline`, default on; injected lines contribute exposure ids to D77 `recordRetrieved`, never usefulness). **Queries** (`src/graph/queries.ts`, pure): `graph neighbours <id> [--depth 1-6]` (BFS, default 1, per-edge receipts with type/provenance/confidence) and `graph path <a> <b>` (shortest path, default depth 4, per-hop receipts). **Lint** (`src/graph/lint.ts`, pure): orphans (active, no topic, no edges), dangling edges (endpoint absent from the index — but an endpoint that exists in *another* scope is a legitimate foreign link, e.g. a propose copy deriving from its personal original, and is skipped), and near-stale pairs (similarity ≥ 0.8, chains excluded) via the existing lifecycle `similarity()`; reports only, nothing auto-resolved — this is the report D78's pre-submit lint consumes later. Scope contract: the graph covers the cwd's **project** scope only, no `--scope` flag, `personal` never graphs (§20.5). The interface is **CLI only** (`open-memex graph build|neighbours|path|lint|outline`) — the MCP surface stays at 13 tools; the outline reaches sessions through injection, not a tool (§20.6). Schema bump: added `derived_from TEXT` to `memories` (`SCHEMA_VERSION` 9 → 10, rebuild-from-Markdown migration — the frontmatter field already existed at `markdown.ts`). The **LLM half** — abstracted insights and missing-page alerts that propose new memories — remains open in §18/§20 and must go through the D61 propose-first flow.
|
|
1149
1149
|
*Status (2026-11-06): 部分实现 (0.9.0-alpha.6) — deterministic half shipped: `src/graph/{extract,outline,queries,lint}.ts` + `src/store/graph.ts`, auto-refresh on every mutating path, outline injection, CLI `graph` group; smoke-pure + test-full (154 checks) green. LLM half (abstracted insights, missing-page → new memories) remains 未实现.*
|
|
1150
|
+
|
|
1151
|
+
- **D92 — feedback-weighted ranking, first slice (2026-11-11).** The D79 follow-up that D77-L2 unblocked: the reuse counters now have a *measured*, deliberately small effect on `search()` order. **Measurement first:** commit 1 added a 3-query reuse slice to `scripts/retrieval-eval.ts` — each query has a gold memory carrying `retrieved=5..6, useful=3` counters and a near-tied distractor with the same retrieval count but zero useful confirmations — and seeded that telemetry through the real `recordRetrieved`/`recordUseful` API. Baseline with feedback still off: 60 memories / 47 queries, R@1 0.660 / R@5 0.979 / MRR 0.804. **Mechanism:** `src/retrieve/feedback.ts` (pure, smoke-tested) reorders only inside a near-tied BM25 band (score ≥ **0.75×** the band head), only among hits with `retrieved_count >= 3`, by `reuse_rate` descending, and only within a contiguous run of eligible hits — so an ineligible/new memory keeps its exact BM25 slot and its neighbours cannot leapfrog it. The BM25 score is never changed; `search --explain` still prints it, plus a `feedback:` line listing every promotion (`↑ id +N (reuse …)`) so the trace is auditable. Tiers are reordered independently, so feedback never lifts a draft over reviewed knowledge. Config is a flat key `feedbackWeighting` (**default false**, `SETTABLE_KEYS`, shallow-merge-safe); callers (`memory_search` both hosts, CLI `search`) pass it, and the eval passes both values explicitly. **Result:** weighted R@1 0.702 / R@5 0.979 / MRR 0.825; reuse slice MRR 0.500 → 0.833 (two of three golds promoted 2→1). Band sweep on the fixture: 0.95 → no effect, 0.9/0.85/0.8 → +1 R@1, 0.75 → +2, 0.67 → +3; 0.75 is shipped because it is the widest band that still catches the two strongest reuse signals; 0.67 would also promote a hit ~33% below the band head, which is a relevance gap, not a near-tie. **Guardrails unchanged (D77):** useful only via `memory_useful`, human approve at review, or supersede — passive exposure still increments only `retrieved_count`; `reuse_rate` may exceed 1.0 and is signal strength, never a prune threshold; counters stay in local SQLite and survive index rebuilds. **Explicitly not in this slice:** embedding gate, cross-lingual rerank (D79 item 4, after D78), automatic zombie demotion/eviction (D78), and any change to `memory_useful` or the D77-L3 report's accounting.
|
|
1152
|
+
*Status (2026-11-11): 已实现(第一刀,0.10.0-alpha.2)— `src/retrieve/feedback.ts` + `search()` wiring + `feedbackWeighting` flat key + `search --explain` promotion trace; fixture baseline vs weighted numbers in `scripts/retrieval-eval.ts`. D79 的 embedding gate / 跨语言 rerank / 自动淘汰仍留给后续。*
|