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 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 D88 — log in `docs/design/decisions.md`; open questions tracked at the end of the doc). Per its §12:
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–D88). Before changing
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
- - 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.
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
- - 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).
14
+ ## [0.9.0] - 2026-11-06
17
15
 
18
- ## [0.9.0-alpha.2] - 2026-11-03
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). The D77-L3 reuse report (top reused, zero-reuse zombies, per-scope rates) remains open.
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
- ## [0.9.0-alpha.1] - 2026-11-03
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
- - 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.
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
  ![Terminal demo: two memories saved on Monday, recalled by search in a fresh session on Friday](./docs/assets/open-memex-demo.svg)
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
- 54 memories + 44 queries (exact terms, paraphrases, synonyms, Chinese,
567
- cross-language hard cases, synonym-only queries, and D81 user-defined
568
- alias queries) — reproduce with
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.75, recall@5 0.98, MRR 0.86**.
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` (a dotted
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
  ![终端演示:周一存下的两条记忆,周五在新会话里被搜索召回](./docs/assets/open-memex-demo.svg)
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 来度量召回率,而不是空口断言:54 条记忆 + 44 个查询(精确词、改写、同义词、中文、跨语言 hard case、纯同义词查询、D81 用户别名查询),运行 `node --experimental-strip-types scripts/retrieval-eval.ts` 即可复现。当前基线(含 D80 的 index-time 同义词/翻译展开和 D81 的 query-time 用户别名展开):**recall@1 0.75、recall@5 0.98、MRR 0.86**。语料小且是合成的,请把它当回归守卫和起点,而不是真实场景的承诺。
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
- 1a872598f56a092aab47264914caf532b86c553e96a92f73333742e4e0d9588b
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, and how many matches
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
+ }
@@ -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
- return [...tiers[0], ...tiers[1], ...tiers[2], ...deprecated].slice(0, limit);
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 hits = resolveVisible(merged, limit, opts.stats);
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)
@@ -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,
@@ -45,7 +45,7 @@ export function makeTools(getScope, cfg) {
45
45
  args: memorySearchArgs,
46
46
  async execute(args) {
47
47
  syncFirst();
48
- return searchMemories(getScope, args);
48
+ return searchMemories(getScope, cfg, args);
49
49
  },
50
50
  });
51
51
  const memory_list = tool({
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 once D77 counters land; 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).
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 — D77-L2 counters landed 2026-11-03, so this is newly unblocked; fixture + baseline first (measurement before mechanism). (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.
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.