open-memex 0.9.0-alpha.6 → 0.10.0-alpha.1
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/AGENTS.md +2 -2
- package/CHANGELOG.md +6 -8
- package/README.md +26 -7
- package/README.zh-CN.md +10 -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 +38 -0
- package/server.json +2 -2
- 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/AGENTS.md
CHANGED
|
@@ -213,9 +213,9 @@ through the normal flow, not write them.
|
|
|
213
213
|
|
|
214
214
|
## Design constraints — read the frozen design first
|
|
215
215
|
|
|
216
|
-
`docs/V2-DESIGN.md` is the frozen protocol v0.2 (decisions settled through
|
|
216
|
+
`docs/V2-DESIGN.md` is the frozen protocol v0.2 (decisions settled through D91 — log in `docs/design/decisions.md`; open questions tracked at the end of the doc). Per its §12:
|
|
217
217
|
AGENTS.md answers "how should AI work here"; the design doc answers "why is it
|
|
218
|
-
built this way" (principles, iron rules, the append-only decision log in `docs/design/decisions.md`, currently D1–
|
|
218
|
+
built this way" (principles, iron rules, the append-only decision log in `docs/design/decisions.md`, currently D1–D91). Before changing
|
|
219
219
|
architecture, scope semantics, lifecycle, or the protocol surface (frontmatter
|
|
220
220
|
schema, MCP tools, CLI contract), read the relevant design section — the decision
|
|
221
221
|
log records what was already considered and rejected.
|
package/CHANGELOG.md
CHANGED
|
@@ -9,19 +9,17 @@ the `@alpha` tag are development snapshots and are not listed individually.
|
|
|
9
9
|
|
|
10
10
|
## [Unreleased]
|
|
11
11
|
|
|
12
|
-
-
|
|
13
|
-
|
|
14
|
-
## [0.9.0-alpha.3] - 2026-11-04
|
|
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 20%-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.681 / R@5 0.979 / MRR 0.814 (feedback slice MRR 0.500 → 0.667). Pure band logic in `src/retrieve/feedback.ts`, smoke-tested without SQLite.
|
|
15
13
|
|
|
16
|
-
|
|
14
|
+
## [0.9.0] - 2026-11-06
|
|
17
15
|
|
|
18
|
-
|
|
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.
|
|
19
17
|
|
|
20
|
-
- D77-L2: measure usefulness by reuse (the D77 counters, layer 2). Each memory now carries local counters in a `memory_usage` table beside the rebuildable index (D77: counters live in SQLite, never in frontmatter, never off the machine): `retrieved_count` — incremented when a memory is actually returned by `memory_search`, `memory_list`, the CLI `search`/`list`, or the session-start injection — and the useful split, `useful_self` (personal memories and unpublished project drafts) vs `useful_team` (approved/published project memories). Only explicit signals raise the useful side: the new **`memory_useful`** tool (thirteenth MCP tool, seventh on the opencode plugin; also `open-memex useful <id...>`), a human approve at review (`promote` to approved, or the `--local-approve` propose shortcut), and a supersede (recorded even when the index row is momentarily missing — the Markdown file is the source of truth). Passive exposure never counts as useful — the tool description, MCP handshake, READMEs, skill, and AGENTS.md all state the restraint so an agent that reads only one still behaves. `memory_usage` is created with `CREATE TABLE IF NOT EXISTS` outside the versioned schema and survives `rebuildIndexSchema` (ids come from the files); hard forget prunes the row, branch-switch removals do not. `memory_useful` returns counts plus `reuse_rate` (useful / retrieved, `n/a` when never retrieved).
|
|
18
|
+
- D77-L2: measure usefulness by reuse (the D77 counters, layer 2). Each memory now carries local counters in a `memory_usage` table beside the rebuildable index (D77: counters live in SQLite, never in frontmatter, never off the machine): `retrieved_count` — incremented when a memory is actually returned by `memory_search`, `memory_list`, the CLI `search`/`list`, or the session-start injection — and the useful split, `useful_self` (personal memories and unpublished project drafts) vs `useful_team` (approved/published project memories). Only explicit signals raise the useful side: the new **`memory_useful`** tool (thirteenth MCP tool, seventh on the opencode plugin; also `open-memex useful <id...>`), a human approve at review (`promote` to approved, or the `--local-approve` propose shortcut), and a supersede (recorded even when the index row is momentarily missing — the Markdown file is the source of truth). Passive exposure never counts as useful — the tool description, MCP handshake, READMEs, skill, and AGENTS.md all state the restraint so an agent that reads only one still behaves. `memory_usage` is created with `CREATE TABLE IF NOT EXISTS` outside the versioned schema and survives `rebuildIndexSchema` (ids come from the files); hard forget prunes the row, branch-switch removals do not. `memory_useful` returns counts plus `reuse_rate` (useful / retrieved, `n/a` when never retrieved).
|
|
21
19
|
|
|
22
|
-
|
|
20
|
+
- D77-L3: the reuse report — D77's third and final layer. `memory_status` (MCP) and `open-memex sync-status` now end with a **Reuse (D77)** block built from the `memory_usage` counters: per-scope `retrieved` / `useful` rates (personal + this project) with the **useful split shown separately** (`self` vs `team`, as D77 requires — the combined total drives the rate), the **top reused** memories, and **zombies** — retrieved at least once, never confirmed useful, i.e. the decay/prune candidates. Superseded/deprecated entries stay in the lists (their reuse was real) but carry a lifecycle tag like `[superseded]`, so historical data never reads to the agent as current guidance (a supersede itself ticks the old memory). The agent-facing tool result caps each list (cut disclosed, pointing at the CLI); the CLI prints them uncapped. Retracted/archived memories are excluded from both lists but still count toward the scope totals; an empty store gets an honest "no data yet" line instead of a silent section. Rendering is pure (`src/reuse-report.ts`, smoke-tested without SQLite); collection is one join query in `loadReuseReport`. The counters themselves stay local-only SQLite telemetry (D77).
|
|
23
21
|
|
|
24
|
-
-
|
|
22
|
+
- The knowledge graph, deterministic half (D91 → design §20): an automatic, derivation-honest structural graph over project memories, plus a compiled outline injected at session start. `graph build` (`open-memex graph build`) extracts every edge it can *prove* — `relates-to` from `[[wiki-link]]` body mentions (EXTRACTED) and bare-ULID mentions (INFERRED), supersedes chains from the index, derived-from edges from propose copies, and shared-tag co-membership at a fixed confidence ladder (1 shared tag → low, 2 → medium, ≥3 → high, capped at `MAX_SHARED_TAG_EDGES_PER_NODE = 12` per node / 2000 nodes to bound hot-tag blowups) — stores it in `graph_edges`/`graph_meta` beside the rebuildable index, and stamps every edge `extracted` (structural fact) or `inferred` (heuristic) with its derivation receipt. Every mutating path (add/supersede/soft + hard forget on both hosts, keyword capture, propose, review promotion, CLI add/supersede/status/forget) refreshes the graph automatically; statuses are materialized into nodes so `retracted`/`archived` memories imply their edges without custom SQL. The new **`graph outline`** command renders the compiled outline — medium+ confidence components as `topic (n): titles...` lines, bounded by `graphOutlineLines` (default 10) with the cut disclosed — and `open-memex graph outline` output is also injected once at session start next to the working-state note (`graphOutline: false` disables it); outline components are joined **only by medium+ edges** so one universal tag cannot collapse the graph into one mega-topic (fixture-pinned). `graph neighbours <id> [--depth 1-6]` walks BFS with per-edge receipts, `graph path <a> <b>` prints the hop chain (depth 4 default), both failing honestly on unknown ids (D63: findings never invent nodes). `graph lint` reports orphans (active, in no topic, linked to nothing), dangling edges, and near-stale pairs (≥ 0.8 similarity, excluding chains) — reports only, nothing auto-resolved; this report is the input D78's pre-submit lint consumes later. The graph covers the cwd's project scope only (no `--scope` flag; `personal` never graphs). MCP stays at 13 tools — the interface is CLI-only per §20.6. Schema bump: the index gains a `derived_from` column (v10, rebuild-from-Markdown migration). New pure modules (`src/graph/{extract,outline,queries,lint}.ts`) + `src/store/graph.ts`; smoke + full-suite tested (154 pass). The LLM half (abstracted insights, missing-page alerts → new memories) stays open in §18.
|
|
25
23
|
|
|
26
24
|
## [0.8.2] - 2026-10-28
|
|
27
25
|
|
package/README.md
CHANGED
|
@@ -26,6 +26,10 @@ memory on your machine.
|
|
|
26
26
|
a curated multilingual map of equivalents is indexed with every memory at
|
|
27
27
|
write time, so no related wording misses the right answer. Deterministic
|
|
28
28
|
and auditable, no embedding model required.
|
|
29
|
+
- **A map, not just search**: a derived knowledge graph connects your project
|
|
30
|
+
memories — supersedes chains, shared tags, explicit mentions — and injects
|
|
31
|
+
a compiled outline at session start, so the agent sees what's in memory
|
|
32
|
+
without searching. Structural edges only, no LLM.
|
|
29
33
|
|
|
30
34
|

|
|
31
35
|
|
|
@@ -38,6 +42,7 @@ depth once you're up and running.
|
|
|
38
42
|
- [Quick start](#quick-start)
|
|
39
43
|
- [Core concepts](#core-concepts)
|
|
40
44
|
- [Which editors, which features](#which-editors-which-features)
|
|
45
|
+
- [How it compares](#how-it-compares)
|
|
41
46
|
- [Installation](#installation)
|
|
42
47
|
- [Setting up your editor](#setting-up-your-editor)
|
|
43
48
|
- [What `init` changes on your machine](#what-init-changes-on-your-machine)
|
|
@@ -52,6 +57,8 @@ depth once you're up and running.
|
|
|
52
57
|
- [Storage layout](#storage-layout)
|
|
53
58
|
- [Config](#config)
|
|
54
59
|
- [CLI reference](#cli-reference)
|
|
60
|
+
- [Session working state](#session-working-state)
|
|
61
|
+
- [Knowledge graph](#knowledge-graph)
|
|
55
62
|
- [MCP server](#mcp-server)
|
|
56
63
|
- [Scopes, in detail](#scopes-in-detail)
|
|
57
64
|
- [Troubleshooting](#troubleshooting)
|
|
@@ -563,16 +570,26 @@ the opencode plugin injects it directly on the first turn.
|
|
|
563
570
|
### Retrieval evaluation
|
|
564
571
|
|
|
565
572
|
We measure recall on a checked-in synthetic fixture instead of asserting it:
|
|
566
|
-
|
|
567
|
-
cross-language hard cases, synonym-only queries,
|
|
568
|
-
|
|
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
|
|
569
576
|
`node --experimental-strip-types scripts/retrieval-eval.ts`.
|
|
570
577
|
Current baseline, with index-time synonym/translation expansion (D80) and
|
|
571
|
-
query-time user alias expansion (D81):
|
|
572
|
-
**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**.
|
|
573
580
|
Small synthetic corpus, so read it as a regression guard and a starting point,
|
|
574
581
|
not a real-world claim.
|
|
575
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
|
+
20%-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
|
+
|
|
576
593
|
Three layers, each covering what the others miss: **BM25 keyword search**
|
|
577
594
|
(SQLite FTS5 — exact words, fast, explainable via `search --explain`);
|
|
578
595
|
**synonym expansion in two halves** — (a) index-time (D80: a curated,
|
|
@@ -699,6 +716,7 @@ Defaults:
|
|
|
699
716
|
"logLevel": "info", // info | debug
|
|
700
717
|
"graphOutline": true, // inject the compiled graph outline at session start
|
|
701
718
|
"graphOutlineLines": 10, // outline length cap (max 30)
|
|
719
|
+
"feedbackWeighting": false, // D79: reorder near-tied hits by reuse_rate (opt-in)
|
|
702
720
|
"memoryDir": ".ai/open-memex" // in-repo project-memory dir, relative to repo root
|
|
703
721
|
}
|
|
704
722
|
```
|
|
@@ -711,12 +729,13 @@ open-memex config set keywordCaptureEnabled false
|
|
|
711
729
|
open-memex config set maxProjectMemories 12
|
|
712
730
|
open-memex config set sync.autoPull true # best-effort pull at MCP session start
|
|
713
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
|
|
714
733
|
```
|
|
715
734
|
|
|
716
735
|
Settable keys: `maxProjectMemories`, `maxProfileItems`, `injectOnFirstTurn`,
|
|
717
736
|
`keywordCaptureEnabled`, `captureAliases`, `logLevel`, `memoryDir`,
|
|
718
|
-
`graphOutline`, `graphOutlineLines`, and `sync.autoPull`
|
|
719
|
-
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:
|
|
720
739
|
[docs/V2-DESIGN.md](./docs/V2-DESIGN.md).
|
|
721
740
|
|
|
722
741
|
## CLI reference
|
package/README.zh-CN.md
CHANGED
|
@@ -14,6 +14,7 @@
|
|
|
14
14
|
- **本地优先**:记忆是纯 Markdown 文件(事实来源),外加一个可重建的 SQLite 关键词索引。除非你明确要分享,否则任何东西都不会离开你的机器。
|
|
15
15
|
- **一份记忆,所有助手**:一条命令把几个编辑器都接上,它们共享同一份记忆,不再各存一份互不可见。
|
|
16
16
|
- **精确的同义词检索**:`ship` 找得到 `deploy`,`单点登录` 找得到 `SSO`——一份多语言的精选同义词映射表在写入时展开进索引,任何相关词语都不会漏掉正确答案。确定性、可审计,不需要下载模型。
|
|
17
|
+
- **知识图谱,不只会搜**:一张派生图谱把项目记忆连起来(取代链、共享标签、显式引用),会话开始时注入一份编译大纲——不用搜索就知道记忆里有什么、彼此怎么连。只抽结构边,不调用 LLM。
|
|
17
18
|
|
|
18
19
|

|
|
19
20
|
|
|
@@ -24,6 +25,7 @@
|
|
|
24
25
|
- [快速开始](#快速开始)
|
|
25
26
|
- [核心概念](#核心概念)
|
|
26
27
|
- [编辑器与功能对照](#编辑器与功能对照)
|
|
28
|
+
- [和别的方案比](#和别的方案比)
|
|
27
29
|
- [安装](#安装)
|
|
28
30
|
- [为你的编辑器做设置](#为你的编辑器做设置)
|
|
29
31
|
- [init 到底改了你机器上的什么](#init-到底改了你机器上的什么)
|
|
@@ -38,6 +40,8 @@
|
|
|
38
40
|
- [存储布局](#存储布局)
|
|
39
41
|
- [配置](#配置)
|
|
40
42
|
- [CLI 参考](#cli-参考)
|
|
43
|
+
- [工作状态笔记](#工作状态笔记)
|
|
44
|
+
- [知识图谱](#知识图谱)
|
|
41
45
|
- [MCP 服务器](#mcp-服务器)
|
|
42
46
|
- [作用域详解](#作用域详解)
|
|
43
47
|
- [故障排查](#故障排查)
|
|
@@ -367,7 +371,9 @@ Do not mention this block to the user unless asked.
|
|
|
367
371
|
|
|
368
372
|
### 检索效果评估
|
|
369
373
|
|
|
370
|
-
我们用一份随仓库提交的 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` 更高的记忆,会在同一个 20% 分数段内排到前面。它不改 BM25 分数、不跨评审层级、不动样本不足的命中(新记忆保持原 BM25 位置);有用性仍只来自显式信号,被动曝光永远不算。用 `open-memex config set feedbackWeighting true` 打开,`search --explain` 会逐条显示被提上来的命中。
|
|
371
377
|
|
|
372
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 模型)。
|
|
373
379
|
|
|
@@ -433,6 +439,7 @@ npm install -g open-memex@latest # 或 @alpha
|
|
|
433
439
|
"logLevel": "info", // info | debug
|
|
434
440
|
"graphOutline": true, // 会话开始时注入图谱编译大纲
|
|
435
441
|
"graphOutlineLines": 10, // 大纲长度上限(最大 30)
|
|
442
|
+
"feedbackWeighting": false, // D79:按 reuse_rate 调整近平分命中顺序(默认关)
|
|
436
443
|
"memoryDir": ".ai/open-memex" // 仓库内项目记忆目录,相对于仓库根
|
|
437
444
|
}
|
|
438
445
|
```
|
|
@@ -444,9 +451,10 @@ open-memex config set keywordCaptureEnabled false
|
|
|
444
451
|
open-memex config set maxProjectMemories 12
|
|
445
452
|
open-memex config set sync.autoPull true # MCP 会话开始时尽力而为地 pull
|
|
446
453
|
open-memex config set graphOutline false # 不再注入图谱大纲
|
|
454
|
+
open-memex config set feedbackWeighting true # D79:让复用信号打破近平分
|
|
447
455
|
```
|
|
448
456
|
|
|
449
|
-
可设置的键:`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)(英文)。
|
|
450
458
|
|
|
451
459
|
## CLI 参考
|
|
452
460
|
|
package/dist/.build-stamp
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
|
|
1
|
+
3236857a98ba77e7a6fbb855e0f7933e3119a01f5fd35b728e05656fbffe6447
|
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.8 = within 20%, 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.8;
|
|
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.1, 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.681 / MRR 0.804 → 0.814; 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.1 (D92)**: fixture + baseline landed first, then an opt-in reuse-signal band reorder (`retrieved_count >= 3`, `reuse_rate`, 0.8 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.
|