open-memex 0.10.0-alpha.3 → 0.10.0-alpha.4

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
@@ -147,6 +147,7 @@ Every write path (tool, keyword hook, CLI `add`) must:
147
147
  3. Check `findDuplicates` (design §3.4): identical content is idempotent (return existing id); near-duplicates (similarity ≥ 0.8) warn but save — suggest `supersede` when the new content replaces the old.
148
148
  4. `writeMemoryFile` first, then `readMemoryFile` + `upsertFromFile` to keep FTS in sync.
149
149
  5. Deletion reports honestly (D63): only ENOENT counts as "deleted"; any other unlink failure keeps the index row and returns failure — the file is the source of truth and would otherwise resurrect the memory on next sync.
150
+ 6. **Length nudge (D94): hint, never refusal.** Content over 500 characters still saves normally; append `lengthNudge()` (`src/capture/length.ts`) to the result — tool path via `addMemory`, CLI via `add`. Never reject or truncate a save for length; the only hard cap is keyword capture's `MAX_CAPTURE_CHARS` (2000, D67), unchanged, and an over-cap keyword drop surfaces to the agent in the D73 hand-off note (`formatCaptureDropBlock`) so it can re-save a shortened version. The keywords debug log stays.
150
151
 
151
152
  Capture-time aliases (D61): `memory_add`/`supersede` may carry up to 4
152
153
  `aliases` (alternate phrasings) into frontmatter; they index in their own FTS
@@ -158,6 +159,17 @@ invents aliases. Checkpoint-proposal guidance (propose, never auto-draft) is
158
159
  copy, not mechanism: keep the rubric wording in sync across the skill, the
159
160
  AGENTS.md hygiene footer, the MCP handshake, and the tool descriptions.
160
161
 
162
+ **Wake convention (D94) — documentation-only, no new surface.** The
163
+ session-start ritual is written in README (en + zh), the bundled Agent
164
+ Skill, and the MCP `SERVER_INSTRUCTIONS`; those three must keep saying the
165
+ same thing, and an agent that reads only one still has to behave. The
166
+ ritual: read the injected `[OPEN-MEMEX]` block (the working-state note and
167
+ the compiled graph outline ride it); if the block is empty or insufficient,
168
+ one `memory_search` with the task's keywords; never ask the user to
169
+ re-explain what memory may already hold. Do not invent tool names for it —
170
+ §18's `memory_recall` does not exist — and do not add an MCP tool or CLI
171
+ verb for the ritual.
172
+
161
173
  ## Lifecycle invariants (design §3.3)
162
174
 
163
175
  - Statuses: `active → superseded | deprecated | retracted | archived`. Retrieval excludes `retracted`/`archived`, ranks `active` above `deprecated`.
@@ -169,7 +181,7 @@ AGENTS.md hygiene footer, the MCP handshake, and the tool descriptions.
169
181
  - Chain integrity is self-healing: on read, a missing counterpart is auto-completed with a warning; a dangling pointer warns but is never fabricated. Don't "fix" chains by editing frontmatter directly — let the read path do it.
170
182
  - Frontmatter is `schema_version: 2`. The SQLite index schema is versioned separately and rebuilds automatically on version change — never hand-edit `index.db`.
171
183
 
172
- **Pre-submit curation (D78/D93) — deterministic only, every action undoable.** `submit` reports graph lint (report-only, never blocks) and auto-applies exactly three things: exact duplicates (`contentHash`-identical normalized body) merge into the oldest free active canonical via the supersede chain, empty/whitespace-only bodies archive, and a ragged first non-empty line is whitespace-normalized. Near-duplicates stay report-only; semantic merge/split and inferred type/tags are deliberately out. Planner is pure (`src/curate.ts`), writes go through `src/store/curate.ts` using `atomicWriteTextSync`/`setStatus` and append a `curation:` receipt to `review_history`; `open-memex curate undo <id>` reverses the latest merge/title action, `open-memex status <id> active` restores an archived empty. Never choose a chain-managed record as canonical, never merge into a non-active record, and never submit a non-active record — curated-out files stay in the outbox as history, not as proposed memories. Curation failure is reported and skipped, never fatal to the human's submit; a failure before the local commit rolls applied curation back. Keep the CLI, MCP `memory_submit` output, READMEs, and the fixture (`scripts/curate-eval.ts`) saying the same thing.
184
+ **Pre-submit curation (D78/D93) — deterministic only, every action undoable.** `submit` reports graph lint (report-only, never blocks) and auto-applies exactly three things: exact duplicates (`contentHash`-identical normalized body) merge into the oldest free active canonical via the supersede chain, empty/whitespace-only bodies archive, and a ragged first non-empty line is whitespace-normalized. Near-duplicates stay report-only; semantic merge/split and inferred type/tags are deliberately out. Planner is pure (`src/curate.ts`), writes go through `src/store/curate.ts` using `atomicWriteTextSync`/`setStatus` and append a `curation:` receipt to `review_history`; `open-memex curate undo <id>` reverses the latest merge/title action, `open-memex status <id> active` restores an archived empty. Never choose a chain-managed record as canonical, never merge into a non-active record, and never submit a non-active record — curated-out files stay in the outbox as history, not as proposed memories. Curation failure is reported and skipped, never fatal to the human's submit; a failure before the local commit rolls applied curation back. The printed `gh pr create` command's title/count/ids come from the actual submitted set, and its body carries the lint counts plus applied-action counts (shell-safe, no nested quotes). Keep the CLI, MCP `memory_submit` output, READMEs, and the fixture (`scripts/curate-eval.ts`) saying the same thing.
173
185
 
174
186
  Keyword capture fires from `chat.message` on the user's message parts (`UserMessage`). Patterns live in `src/capture/keywords.ts` / config `keywordPatterns`; regex group 1 is the memory body. Scope routing: personal patterns (`cfg.keywordPersonalPatterns`) force the personal scope — the rule is 我 → personal (记住我/替我记/帮我记/我觉得/我喜欢/remember for me/help me remember), 我们 → current scope (我们认为/我们决定/帮我们记住); personal patterns run first and claim their line so a generic trigger can't double-fire (a rejected personal match keeps the claim — see D67).
175
187
 
package/CHANGELOG.md CHANGED
@@ -9,7 +9,9 @@ the `@alpha` tag are development snapshots and are not listed individually.
9
9
 
10
10
  ## [Unreleased]
11
11
 
12
- - D78 pre-submit curation, first slice: `submit` now runs a report-only graph lint and a deterministic auto-apply tier before copying drafts into the repo. Lint reports orphans, dangling edges, and near-stale pairs but never blocks; exact duplicates are merged into the oldest free active copy through the existing supersede chain, empty / whitespace-only bodies are archived (not deleted), and a first non-empty line with ragged whitespace is normalized without touching the rest of the body. Near-duplicates stay report-only - semantic merge/split and inferred type/tags need a human. Every applied action prints a receipt and is reversible: `open-memex curate undo <id>` for merges and title fixes, `open-memex status <id> active` for empty-body archives (the marker lives in the file's `review_history`, so undo works across branches and machines). `submit --no-curate` skips the apply tier but still reports lint; it can now appear before or after the ids. Curated-out outbox files remain in appdata as history and are no longer counted as pending drafts (`sync-status` reports them separately); submit refuses non-active records instead of proposing history. `graph lint` no longer calls an intentional supersede-chain duplicate stale. Checked-in fixture (`scripts/curate-eval.ts`): 9 lint findings and 3 deterministic candidates before curation, 6 findings after (orphans 7→4, dangling 1, stale 1), `--no-curate` applies 0, and all 3 undo checks pass. Planner is pure (`src/curate.ts`), writes live in `src/store/curate.ts`; `smoke-pure` and `test-full` cover the new paths.
12
+ - D94 OptMem small items (§18 item 5): open-memex's prompt/token overhead is now **measured and published**, not asserted — `scripts/token-cost.ts` renders the real `buildContextBlock` output (8 project + 5 personal + the compiled graph outline) and the real `TOOL_DESCRIPTIONS` text on a scratch store, estimating tokens as characters ÷ 4 (no tokenizer dependency); measured: injection block 2125 chars (~531 tokens), 13 tool descriptions 8814 chars (~2204 tokens), total 10939 chars (~2735 tokens), quoted as approximations in both READMEs with the method stated and the once-per-session (not per-turn) injection spelled out. A **wake convention** documents the session-start ritual — read the injected `[OPEN-MEMEX]` block (working-state note + graph outline ride it); if empty or insufficient, one `memory_search` with the task's keywords; never re-ask the user for what memory holds — stated identically in README (en + zh), the bundled Agent Skill, and the MCP handshake instructions, with no new tool or CLI verb and no invented tool name. A **capture length nudge**: bodies over 500 characters save normally and the result carries a one-line hint (`lengthNudge`, pure, smoke-tested) on `memory_add` and CLI `add` — nothing is refused; and a keyword match over the unchanged 2000-character hard cap, previously dropped with only a debug log line, is now surfaced to the agent in the D73 hand-off note so it can re-save a shortened version.
13
+
14
+ - D78 pre-submit curation, first slice: `submit` now runs a report-only graph lint and a deterministic auto-apply tier before copying drafts into the repo. Lint reports orphans, dangling edges, and near-stale pairs but never blocks; exact duplicates are merged into the oldest free active copy through the existing supersede chain, empty / whitespace-only bodies are archived (not deleted), and a first non-empty line with ragged whitespace is normalized without touching the rest of the body. Near-duplicates stay report-only - semantic merge/split and inferred type/tags need a human. Every applied action prints a receipt and is reversible: `open-memex curate undo <id>` for merges and title fixes, `open-memex status <id> active` for empty-body archives (the marker lives in the file's `review_history`, so undo works across branches and machines). The generated `gh pr create` command counts only the ids actually submitted and puts the lint + applied-action summary in its body. `submit --no-curate` skips the apply tier but still reports lint; it can now appear before or after the ids. Curated-out outbox files remain in appdata as history and are no longer counted as pending drafts (`sync-status` reports them separately); submit refuses non-active records instead of proposing history. `graph lint` no longer calls an intentional supersede-chain duplicate stale. Checked-in fixture (`scripts/curate-eval.ts`): 9 lint findings and 3 deterministic candidates before curation, 6 findings after (orphans 7→4, dangling 1, stale 1), `--no-curate` applies 0, and all 3 undo checks pass. Planner is pure (`src/curate.ts`), writes live in `src/store/curate.ts`; `smoke-pure` and `test-full` cover the new paths.
13
15
 
14
16
  - D79 feedback-weighted ranking, first slice: `search()` can now reorder near-tied BM25 hits by the D77 reuse signal. A memory with `retrieved_count >= 3` and a higher `reuse_rate` moves ahead of equally relevant hits inside the same 25%-score band; the BM25 score is never modified, review tiers are never crossed, and hits with too little telemetry keep their exact BM25 slot (no cold-start penalty). Off by default (`feedbackWeighting: false`, a flat key settable with `config set`), because the counters start empty and the loop is only worth trusting once explicit useful signals exist. Guardrails unchanged: only `memory_useful`, a human approve at review, or a supersede raise usefulness — passive exposure only increments `retrieved_count`. `search --explain` reports whether weighting ran and lists every promoted hit with its reuse rate and move size. Fixture grows to 60 memories / 47 queries with a 3-query reuse slice; measured baseline (off) R@1 0.660 / R@5 0.979 / MRR 0.804 → weighted R@1 0.702 / R@5 0.979 / MRR 0.825 (feedback slice MRR 0.500 → 0.833). Pure band logic in `src/retrieve/feedback.ts`, smoke-tested without SQLite.
15
17
 
package/README.md CHANGED
@@ -407,11 +407,16 @@ Three ways memories get in:
407
407
  own sentence: the plugin tells the agent what it just stored, and a
408
408
  `memory_add` that re-saves the same words within the next few minutes is
409
409
  refused with the stored id (D73) — one thing you said is one memory, not
410
- three copies of it.
410
+ three copies of it. A keyword match over the 2000-character hard cap is
411
+ dropped, never truncated into a memory — the agent is told in its session
412
+ context (D94) and can re-save a shortened version.
411
413
  - **The agent saves it**: in any editor, ask your agent to remember something
412
414
  (or it saves on its own when you state a fact worth keeping) — it calls
413
415
  `memory_add`. The routing above is a heuristic; you can always say "save this
414
- to my personal memory" or use the CLI with `--scope` to be explicit.
416
+ to my personal memory" or use the CLI with `--scope` to be explicit. Long
417
+ bodies are never refused: over 500 characters the save proceeds and the
418
+ result just carries a soft hint that shorter, self-contained statements
419
+ retrieve better (D94).
415
420
  - **Checkpoint proposals**: when a task wraps up, the agent proposes 1–3 short
416
421
  candidate memories distilled from the session — decisions and their reasons,
417
422
  conventions, gotchas, approaches tried and abandoned — and saves only the
@@ -572,6 +577,46 @@ time for the rest. Both top-N counts are configurable (see [Config](#config)).
572
577
  For MCP clients this block is delivered as handshake guidance the agent follows;
573
578
  the opencode plugin injects it directly on the first turn.
574
579
 
580
+ ### The session-start ritual (wake)
581
+
582
+ open-memex sessions start from what is already in context, not from questions:
583
+
584
+ 1. Read the `[OPEN-MEMEX]` block injected at session start (opencode) — or the
585
+ equivalent guidance in the MCP handshake instructions. It carries the top
586
+ project memories, your preferences, the working-state note from a previous
587
+ session (if any), and the compiled memory map.
588
+ 2. If the block is empty or doesn't cover the current task, call `memory_search`
589
+ **once** with the task's keywords (try 2–3 phrasings, both scopes) before
590
+ concluding anything is missing.
591
+ 3. Don't ask the user to re-explain what memory already holds — repeated
592
+ "didn't we decide X?" questions are the failure mode open-memex exists to
593
+ prevent. Ask only about what neither the block nor search can answer.
594
+
595
+ The block is injected **once per session, not once per turn** — mid-session,
596
+ open-memex adds nothing to the context unless a tool is called. The same
597
+ ritual is written into the bundled `open-memex` Agent Skill and the MCP
598
+ handshake instructions, so an agent that reads only one of the three still
599
+ behaves the same way.
600
+
601
+ ### What this costs in context (tokens)
602
+
603
+ Measured, not asserted (D94, inspired by OptMem's published "426-token
604
+ prompt"). On the checked-in fixture in `scripts/token-cost.ts` — 8 project
605
+ memories + 5 personal + the compiled graph outline, default config — with
606
+ tokens estimated as characters ÷ 4 (the rough ratio for English prose; a
607
+ deliberately tokenizer-free method, no new dependency):
608
+
609
+ | Surface | Characters | ≈ Tokens | When |
610
+ |---|---|---|---|
611
+ | Session-start injection block | 2,125 | ~530 | once per session (not per turn) |
612
+ | All 13 MCP tool descriptions | 8,814 | ~2,200 | once per session, at the MCP handshake |
613
+ | Total | 10,939 | ~2,700 | |
614
+
615
+ These are approximations and they move with your memory sizes and config —
616
+ re-run `node --experimental-strip-types scripts/token-cost.ts` to measure
617
+ your own numbers and to regenerate the fixture's. (The script's output and
618
+ this table must agree; update both together, never by hand.)
619
+
575
620
  ### Retrieval evaluation
576
621
 
577
622
  We measure recall on a checked-in synthetic fixture instead of asserting it:
@@ -812,6 +857,8 @@ open-memex submit <id...> [--branch <name>] [--base <branch>] [--no-curate]
812
857
  # (exact-duplicate merge, empty-body archive, first-line title cleanup).
813
858
  # --no-curate skips the cleanup but still prints lint. Near-duplicates are
814
859
  # reported, never merged. Every applied action prints its undo command.
860
+ # The generated gh pr create body carries the lint + curation summary and
861
+ # counts only the ids actually submitted (not the pre-curation batch).
815
862
  # All-or-nothing; conflicts (same id, different content) abort cleanly.
816
863
  # Prints the push + gh pr commands; an agent holding your Yes carries
817
864
  # through push/PR itself. --branch <name> creates the branch first
package/README.zh-CN.md CHANGED
@@ -269,8 +269,8 @@ open-memex uninstall --yes
269
269
 
270
270
  三种存入方式:
271
271
 
272
- - **关键词触发**(仅 opencode 原生插件):说 `remember …`、`note that …`、`don't forget: …`、`TIL …`、`save this …`——中文 `记住…` / `记一下…` / `记录一下…` / `别忘了:…`——这句话就被存下来,不需要任何工具调用。捕获默认进当前 **project**;`remember for me …`、`help me remember: …`、`记住我…`、`替我记…`、`帮我记…`、`我觉得…`、`我喜欢…` 这类"这是关于我"的信号会改为进 **personal**;`我们决定…`、`帮我们记住…` 等团队语境仍留在项目里。两条降噪规则(D67):触发词必须是**对存储说的话**,所以叙述型的 `记得…` / `remind me to…` / `别忘了带伞` / `don't forget the wifi password` 一律不触发(加一个分隔符——`别忘了:…`、`don't forget: …`——或用 `that`,才算指令);捕获内容不足 3 个字符按碎片丢弃,不会存下来——`capture --dry-run` 会明确说明,不再悄悄吞掉。另外,一句触发捕获的话只归一条记忆:插件会把它刚存下的内容告诉助手,几分钟内再用 `memory_add` 重复存同样的字眼会被拒绝(并给出已存的 id,D73)——你说的一件事就是一条记忆,不是它的三个副本。
273
- - **助手主动保存**:在任何编辑器里,你让助手记住某件事(或者你陈述了一个值得记的事实、它自己判断该保存),它会调用 `memory_add`。上面的路由是启发式规则;你可以明说"存到我的个人记忆",或用 CLI 加 `--scope` 明确指定。
272
+ - **关键词触发**(仅 opencode 原生插件):说 `remember …`、`note that …`、`don't forget: …`、`TIL …`、`save this …`——中文 `记住…` / `记一下…` / `记录一下…` / `别忘了:…`——这句话就被存下来,不需要任何工具调用。捕获默认进当前 **project**;`remember for me …`、`help me remember: …`、`记住我…`、`替我记…`、`帮我记…`、`我觉得…`、`我喜欢…` 这类"这是关于我"的信号会改为进 **personal**;`我们决定…`、`帮我们记住…` 等团队语境仍留在项目里。两条降噪规则(D67):触发词必须是**对存储说的话**,所以叙述型的 `记得…` / `remind me to…` / `别忘了带伞` / `don't forget the wifi password` 一律不触发(加一个分隔符——`别忘了:…`、`don't forget: …`——或用 `that`,才算指令);捕获内容不足 3 个字符按碎片丢弃,不会存下来——`capture --dry-run` 会明确说明,不再悄悄吞掉。另外,一句触发捕获的话只归一条记忆:插件会把它刚存下的内容告诉助手,几分钟内再用 `memory_add` 重复存同样的字眼会被拒绝(并给出已存的 id,D73)——你说的一件事就是一条记忆,不是它的三个副本。超过 2000 字符硬上限的关键词匹配会被丢弃,绝不截断成记忆——助手会在会话上下文里被告知(D94),可以再存一个缩短版。
273
+ - **助手主动保存**:在任何编辑器里,你让助手记住某件事(或者你陈述了一个值得记的事实、它自己判断该保存),它会调用 `memory_add`。上面的路由是启发式规则;你可以明说"存到我的个人记忆",或用 CLI 加 `--scope` 明确指定。长内容不会被拒绝:超过 500 字符照常保存,只是返回结果里附一句软提示——更短、自包含的陈述检索效果更好(D94)。
274
274
  - **检查点提议**:一个任务收尾时,助手会提议 1–3 条从这轮工作里提炼的候选记忆——决定及其理由、约定、踩过的坑、走过又放弃的路——只有你点头的那几条才存。不会有任何东西在你不知情时被写下来。
275
275
  - **CLI**:`open-memex add "…"`,可选 `--scope` / `--tag` / `--type` / `--aliases`。
276
276
 
@@ -369,6 +369,28 @@ Do not mention this block to the user unless asked.
369
369
 
370
370
  这是一个快照,不是全量记忆——其余的随时用 `memory_search` 就能查。两个前 N 的数都可以配(见[配置](#配置))。对 MCP 客户端,这个块以握手引导的形式送达、由助手遵循;opencode 插件则在第一轮直接注入。
371
371
 
372
+ ### 会话开始仪式(wake)
373
+
374
+ open-memex 的会话从已有上下文开始,而不是从提问开始:
375
+
376
+ 1. 先读会话开始注入的 `[OPEN-MEMEX]` 块(opencode)——或 MCP 握手里的等价指引。里面带着最新的项目记忆、你的偏好、上一会话留下的工作态笔记(如果有),以及编译好的记忆图谱。
377
+ 2. 块是空的、或覆盖不了当前任务时,先用任务关键词调**一次** `memory_search`(换 2–3 种说法、两个作用域都查),再下"没有"的结论。
378
+ 3. 不要让用户重新解释记忆里已经有的东西——反复问"我们之前不是定过 X 吗?"正是 open-memex 要消灭的失败模式。只问块和搜索都答不上来的事。
379
+
380
+ 注入块**每个会话只发生一次,不是每轮一次**——会话中段除非调用工具,open-memex 不再往上下文里加任何东西。同一套仪式也写进了随包分发的 `open-memex` Agent Skill 和 MCP 握手指引:三处只读过其一的助手,行为也一样。
381
+
382
+ ### 上下文 token 开销
383
+
384
+ 用测量说话,而不是断言(D94,受 OptMem 公布的 "426-token prompt" 启发)。在随仓库提交的 fixture(`scripts/token-cost.ts`——8 条项目记忆 + 5 条个人 + 编译好的图谱 outline,默认配置)上量得;token 数按"字符数 ÷ 4"估算(英文文本的粗略比例,刻意不引入 tokenizer 依赖):
385
+
386
+ | 开销面 | 字符数 | ≈ token 数 | 时机 |
387
+ |---|---|---|---|
388
+ | 会话开始注入块 | 2,125 | ~530 | 每会话一次(不是每轮) |
389
+ | 全部 13 个 MCP 工具描述 | 8,814 | ~2,200 | 每会话一次(MCP 握手时) |
390
+ | 合计 | 10,939 | ~2,700 | |
391
+
392
+ 这些是约数,会随你的记忆大小和配置变化——跑 `node --experimental-strip-types scripts/token-cost.ts` 量你自己的数字,也用它重新生成 fixture 的数字。(脚本输出和这张表必须一致;两者一起改,绝不手改。)
393
+
372
394
  ### 检索效果评估
373
395
 
374
396
  我们用一份随仓库提交的 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**。语料小且是合成的,请把它当回归守卫和起点,而不是真实场景的承诺。
@@ -515,6 +537,8 @@ open-memex submit <id...> [--branch <name>] [--base <branch>] [--no-curate]
515
537
  # 复制前:只读图谱 lint + 确定性策展(完全重复合并、空正文归档、
516
538
  # 首行标题清理)。--no-curate 跳过清理但仍打印 lint;近重复只报告,
517
539
  # 永不自动合并。每个已应用动作都会打印撤销命令。
540
+ # 生成的 gh pr create body 带 lint + 策展摘要,人数只算实际提交的 id
541
+ #(不是提交前的批次)。
518
542
  # 全有全无;冲突(同 id 不同内容)干净地中止。
519
543
  # 打印 push + gh pr 命令;持有你 Yes 的助手可以一并执行 push/PR。
520
544
  # --branch <name> 先建分支(助手全链路路径)。PR base 默认是当前分支
package/dist/.build-stamp CHANGED
@@ -1 +1 @@
1
- 2375384d33d2c269139ad6efd211a1ee8b5ddf3c529db58766dd7634947c17eb
1
+ d15bb866b9ff6cb250556f01a9b29ce9eec085641e31a2b7db2ba3b482bbedee
@@ -17,6 +17,7 @@
17
17
  * Pure module: no db, no fs, no config, so the threshold behavior is testable
18
18
  * in scripts/smoke-pure.ts.
19
19
  */
20
+ import { MAX_CAPTURE_CHARS } from "./keywords.js";
20
21
  /**
21
22
  * Overlap bar for refusing a re-save of a just-captured user statement.
22
23
  *
@@ -53,7 +54,27 @@ export function formatHandoffBlock(records) {
53
54
  return [
54
55
  "[open-memex] The user's own wording in this turn was ALREADY stored verbatim, before you saw it. It is not unsaved.",
55
56
  ...lines,
56
- "Do not call memory_add to save that text again in any rewording — one statement is already one memory, and a rewording only adds a second copy that retrieval will return alongside the first.",
57
+ "Do not call memory_add to save that text again in any rewording - one statement is already one memory, and a rewording only adds a second copy that retrieval will return alongside the first.",
57
58
  "Save a memory only for information those lines do NOT contain, as its own self-contained statement. If your version is meant to replace one of them, call memory_supersede with that id instead of memory_add.",
58
59
  ].join("\n");
59
60
  }
61
+ /**
62
+ * D94: the over-cap drop note. Tells the agent a keyword match was dropped
63
+ * for exceeding MAX_CAPTURE_CHARS (imported, not hardcoded) so it can
64
+ * re-save a shortened version. Empty string when there is nothing to
65
+ * report; never mentions too-short drops.
66
+ */
67
+ export function formatCaptureDropBlock(drops) {
68
+ if (drops.length === 0)
69
+ return "";
70
+ const lines = drops.map((d) => {
71
+ const one = d.content.replace(/\s+/g, " ").trim();
72
+ const preview = one.length > 120 ? `${one.slice(0, 120)}...` : one;
73
+ return `- "${preview}" (${d.content.length} chars)`;
74
+ });
75
+ return [
76
+ `[open-memex] A keyword capture in this turn matched but was NOT saved: the body is over the ${MAX_CAPTURE_CHARS}-character hard cap, so it was dropped.`,
77
+ ...lines,
78
+ "Long matches are never truncated into a memory - the cap is unchanged. If any of the dropped text is worth keeping, save a shortened, self-contained version with memory_add.",
79
+ ].join("\n");
80
+ }
@@ -0,0 +1,26 @@
1
+ /**
2
+ * Capture length nudge (D94, OptMem small item 3): a soft length hint at
3
+ * capture time. Inspired by OptMem's 280-byte hard cap, but deliberately
4
+ * softer: a long body is saved normally and the caller just gets a hint
5
+ * appended to the result. Nothing is ever refused for length - the only
6
+ * hard ceiling is the keyword-capture `MAX_CAPTURE_CHARS` (2000, D67),
7
+ * which stays untouched.
8
+ *
9
+ * Pure module: no db, no fs, no config, so the threshold behavior is
10
+ * testable in scripts/smoke-pure.ts.
11
+ */
12
+ /** Over this many characters a save proceeds but its result carries a hint. */
13
+ export const LENGTH_NUDGE_CHARS = 500;
14
+ /**
15
+ * One-line hint appended to the save result when the body is long.
16
+ * Returns null at or under the threshold - the boundary is inclusive:
17
+ * 500 chars = no hint, 501 = hint. The wording says the save happened, so
18
+ * an agent reading only the hint never mistakes it for a refusal.
19
+ */
20
+ export function lengthNudge(content) {
21
+ if (content.length <= LENGTH_NUDGE_CHARS)
22
+ return null;
23
+ return (`Note: this memory is ${content.length} characters, over the ${LENGTH_NUDGE_CHARS}-character soft limit. ` +
24
+ `It saved fine - nothing was refused. Short, self-contained statements retrieve better; ` +
25
+ `consider replacing it with a tighter version (supersede) if one exists.`);
26
+ }
package/dist/cli.js CHANGED
@@ -18,6 +18,7 @@ import { writeMemoryFile, readMemoryFile, ulid, msToRfc3339, normalizeAliases, }
18
18
  import { loadConfig, configSource } from "./config.js";
19
19
  import { paths, projectRoot, isInRepoMemoryFile } from "./paths.js";
20
20
  import { redact } from "./redact.js";
21
+ import { lengthNudge } from "./capture/length.js";
21
22
  import { readWorkingState, clearWorkingState, workingStatePath } from "./working-state.js";
22
23
  import { refreshGraph, refreshGraphQuiet, ensureGraph, loadGraphEdges, loadGraphNodes, loadAllMemoryIds } from "./store/graph.js";
23
24
  import { graphNeighbours, shortestPath } from "./graph/queries.js";
@@ -311,8 +312,9 @@ Example:
311
312
  curate: `Undo one deterministic curation action applied by submit.
312
313
 
313
314
  Every action is recorded in the memory file's review_history, so undo works
314
- across branches and machines. The latest curation on that id is undone; run it
315
- again to undo an older one (where the latest is itself an undo, it refuses).
315
+ across branches and machines. Only the most recent curation action on an id is
316
+ undoable: an undo appends its own receipt, so a second run refuses. Inspect the
317
+ file's review_history for the older trail.
316
318
 
317
319
  Usage: open-memex curate undo <id>
318
320
 
@@ -1294,6 +1296,10 @@ async function main() {
1294
1296
  for (const n of dups.near) {
1295
1297
  console.log(`warning: similar memory exists (score ${n.score.toFixed(2)}): id=${n.id}\n ${n.snippet}\n use \`open-memex supersede ${n.id} "new content"\` if this replaces it.`);
1296
1298
  }
1299
+ // D94: soft length hint - the save already happened; this is advisory only.
1300
+ const nudge = lengthNudge(red);
1301
+ if (nudge)
1302
+ console.log(nudge);
1297
1303
  return;
1298
1304
  }
1299
1305
  if (cmd === "supersede") {
package/dist/mcp.js CHANGED
@@ -58,6 +58,13 @@ memory_forget, memory_useful, memory_workingstate, memory_status, memory_submit,
58
58
  memory_propose, memory_promote, memory_resolve, memory_pr_status — always call
59
59
  them by these full names.
60
60
 
61
+ - Session start (the wake ritual): treat these instructions as already-known
62
+ context, not as something to re-confirm. If the task needs more than they
63
+ cover, call memory_search once with the task's keywords — try 2-3 phrasings
64
+ and check both scopes — before concluding anything is missing. Do not ask
65
+ the user to re-explain past decisions or preferences memory may already
66
+ hold; search first, and only ask about what search cannot answer.
67
+
61
68
  - The server tells you when project outbox drafts are waiting for review —
62
69
  in tool results, and in these session-start instructions. When it does,
63
70
  summarize them (one line each) and ask the user which ones to sync into the
@@ -7,8 +7,8 @@ import { scopeHasFiles } from "./store/migrate.js";
7
7
  import { writeMemoryFile, readMemoryFile, ulid, msToRfc3339, } from "./store/markdown.js";
8
8
  import { buildContextBlock } from "./retrieve/inject.js";
9
9
  import { workingStateBlock } from "./working-state.js";
10
- import { detectKeywords } from "./capture/keywords.js";
11
- import { formatHandoffBlock, freshCaptures, } from "./capture/handoff.js";
10
+ import { scanKeywords } from "./capture/keywords.js";
11
+ import { TURN_ECHO_WINDOW_MS, formatHandoffBlock, formatCaptureDropBlock, freshCaptures, } from "./capture/handoff.js";
12
12
  import { findDuplicates } from "./store/lifecycle.js";
13
13
  import { redact } from "./redact.js";
14
14
  /**
@@ -47,7 +47,7 @@ export function bootstrapPlugin(root) {
47
47
  catch (err) {
48
48
  console.error("[open-memex] init failed:", err);
49
49
  }
50
- return { cfg, scope, injectedSessions: new Set(), workingStateSessions: new Set(), captures: new Map() };
50
+ return { cfg, scope, injectedSessions: new Set(), workingStateSessions: new Set(), captures: new Map(), drops: new Map() };
51
51
  }
52
52
  /**
53
53
  * Keyword capture (§ capture): scan one user message for "remember …"
@@ -60,7 +60,16 @@ export function captureFromText(text, state, sessionID) {
60
60
  const { cfg, scope } = state;
61
61
  if (!cfg.keywordCaptureEnabled || !text)
62
62
  return;
63
- const hits = detectKeywords(text, cfg);
63
+ // D94: scanKeywords over detectKeywords - the dropped matches come back
64
+ // too. Over-cap (too-long) drops are recorded against the session so the
65
+ // D73 hand-off note can surface them; too-short stays debug-log-only.
66
+ const scan = scanKeywords(text, cfg);
67
+ const hits = scan.hits;
68
+ for (const d of scan.dropped) {
69
+ if (d.reason !== "too-long")
70
+ continue;
71
+ recordCaptureDrop(state, sessionID, { content: d.content, at: Date.now() });
72
+ }
64
73
  for (const h of hits) {
65
74
  const { content, hadSecret, matchedPattern } = redact(h.content, cfg.redactPatterns);
66
75
  // Secrets are masked (first 4 chars kept) and the capture proceeds;
@@ -131,12 +140,22 @@ function recordCapture(state, sessionID, record) {
131
140
  list.push(record);
132
141
  state.captures.set(sessionID, list);
133
142
  }
143
+ /** Note one over-cap drop against its session (D94). No-op without a session. */
144
+ function recordCaptureDrop(state, sessionID, record) {
145
+ if (!sessionID)
146
+ return;
147
+ const list = state.drops.get(sessionID) ?? [];
148
+ list.push(record);
149
+ state.drops.set(sessionID, list);
150
+ }
134
151
  /**
135
152
  * D73 hand-off note (a): what the keyword hook already stored for this
136
153
  * session, delivered once per capture into the turn's system context. The
137
154
  * agent cannot avoid re-saving a statement it cannot see is stored, so the
138
- * store tells it. Returns "" when there is nothing new to hand off; stale
139
- * records are pruned (in-memory only, like `injectedSessions`).
155
+ * store tells it. D94: over-cap keyword drops ride the same note, so the
156
+ * agent learns a long match was dropped and can re-save a shorter version.
157
+ * Returns "" when there is nothing new to hand off; stale records are
158
+ * pruned (in-memory only, like `injectedSessions`).
140
159
  *
141
160
  * Both host adapters push this from their system/context hook — the one that
142
161
  * runs before the model request, i.e. after `chat.message` / `prompt`.
@@ -144,23 +163,44 @@ function recordCapture(state, sessionID, record) {
144
163
  export function captureHandoff(sessionID, state) {
145
164
  if (!sessionID)
146
165
  return "";
147
- const list = state.captures.get(sessionID);
148
- if (!list || list.length === 0)
149
- return "";
150
166
  const now = Date.now();
151
- const fresh = freshCaptures(list, now);
152
- if (fresh.length !== list.length) {
153
- if (fresh.length === 0)
154
- state.captures.delete(sessionID);
155
- else
156
- state.captures.set(sessionID, fresh);
167
+ const list = state.captures.get(sessionID);
168
+ let capturesBlock = "";
169
+ if (list && list.length > 0) {
170
+ const fresh = freshCaptures(list, now);
171
+ if (fresh.length !== list.length) {
172
+ if (fresh.length === 0)
173
+ state.captures.delete(sessionID);
174
+ else
175
+ state.captures.set(sessionID, fresh);
176
+ }
177
+ const pending = fresh.filter((r) => !r.delivered);
178
+ if (pending.length > 0) {
179
+ for (const r of pending)
180
+ r.delivered = true;
181
+ capturesBlock = formatHandoffBlock(pending);
182
+ }
157
183
  }
158
- const pending = fresh.filter((r) => !r.delivered);
159
- if (pending.length === 0)
160
- return "";
161
- for (const r of pending)
162
- r.delivered = true;
163
- return formatHandoffBlock(pending);
184
+ const dropList = state.drops.get(sessionID);
185
+ let dropsBlock = "";
186
+ if (dropList && dropList.length > 0) {
187
+ const fresh = dropList.filter((d) => now - d.at <= TURN_ECHO_WINDOW_MS);
188
+ if (fresh.length !== dropList.length) {
189
+ if (fresh.length === 0)
190
+ state.drops.delete(sessionID);
191
+ else
192
+ state.drops.set(sessionID, fresh);
193
+ }
194
+ const pending = fresh.filter((d) => !d.delivered);
195
+ if (pending.length > 0) {
196
+ for (const d of pending)
197
+ d.delivered = true;
198
+ dropsBlock = formatCaptureDropBlock(pending);
199
+ }
200
+ }
201
+ if (capturesBlock && dropsBlock)
202
+ return `${capturesBlock}\n\n${dropsBlock}`;
203
+ return capturesBlock || dropsBlock;
164
204
  }
165
205
  /**
166
206
  * First-turn context injection: exactly once per session. The host adapter
package/dist/submit.js CHANGED
@@ -36,6 +36,29 @@ import { lintGraph } from "./graph/lint.js";
36
36
  function fail(msg) {
37
37
  throw new Error(`[open-memex] ${msg}`);
38
38
  }
39
+ function curationPrBody(ids, curation) {
40
+ const c = curation.lintCounts;
41
+ const lint = `${curation.lintFindings.length} finding(s) (orphans ${c.orphan}, dangling ${c["dangling-edge"]}, stale ${c.stale}; report only)`;
42
+ let applied = "Auto-applied 0.";
43
+ if (curation.disabled) {
44
+ applied = "Auto-apply skipped (--no-curate).";
45
+ }
46
+ else if (curation.applied.length > 0) {
47
+ let merged = 0;
48
+ let archived = 0;
49
+ let normalized = 0;
50
+ for (const a of curation.applied) {
51
+ if (a.action.kind === "merge-duplicate")
52
+ merged++;
53
+ else if (a.action.kind === "archive-empty")
54
+ archived++;
55
+ else
56
+ normalized++;
57
+ }
58
+ applied = `Auto-applied ${curation.applied.length}: merged ${merged}, archived ${archived}, normalized ${normalized}.`;
59
+ }
60
+ return `Submitted from the open-memex outbox. IDs: ${ids.join(" ")}. Lint before curation: ${lint}. ${applied}`;
61
+ }
39
62
  function git(root, args) {
40
63
  try {
41
64
  return execFileSync("git", args, {
@@ -462,15 +485,28 @@ export function submitMemories(ids, opts = {}) {
462
485
  }
463
486
  throw e;
464
487
  }
465
- const ids8 = validated.map((v) => v.id.slice(0, 8)).join(" ");
466
- // D31: the submit itself is a sync event — visible in sync-status.
488
+ const curationReport = {
489
+ disabled: opts.noCurate === true,
490
+ lintFindings,
491
+ lintCounts,
492
+ plan,
493
+ applied,
494
+ skipped: curationSkipped,
495
+ warnings,
496
+ };
497
+ const submittedIds8 = submitted.map((s) => s.id.slice(0, 8));
498
+ const submittedCount = submitted.length;
499
+ const prTitle = `mem: review ${submittedCount} ${submittedCount === 1 ? "memory" : "memories"}`;
500
+ const prBody = curationPrBody(submittedIds8, curationReport);
501
+ const ghPr = `gh pr create --base ${base} --title "${prTitle}" --body "${prBody}"`;
502
+ // D31: the submit itself is a sync event - visible in sync-status.
467
503
  recordSync(scope.key, "submit", {
468
504
  added: submitted.length,
469
505
  updated: skippedIdentical.length,
470
506
  removed: 0,
471
507
  scanned: validated.length,
472
508
  });
473
- // D36: no auto-branch — the commit sits on the branch you were already on.
509
+ // D36: no auto-branch - the commit sits on the branch you were already on.
474
510
  // Next steps are printed, not run. For a separate memory PR, create a branch
475
511
  // first (the commit comes along), then push + open the PR.
476
512
  const branchCmd = `git checkout -b mem/sync-YYYYMMDD`;
@@ -482,17 +518,11 @@ export function submitMemories(ids, opts = {}) {
482
518
  committed,
483
519
  createdBranch,
484
520
  pushCommand: `git push -u origin ${branch}`,
485
- prCommand: createdBranch
486
- ? `gh pr create --base ${base} --title "mem: review ${validated.length} ${validated.length === 1 ? "memory" : "memories"}" --body "Submitted from the open-memex outbox: ${ids8}."`
487
- : `${branchCmd} # if you want a separate memory PR (else push ${branch} directly)\n git push -u origin <new-branch> && gh pr create --base ${base} --title "mem: review ${validated.length}" --body "Submitted from the open-memex outbox: ${ids8}."`,
488
- curation: {
489
- disabled: opts.noCurate === true,
490
- lintFindings,
491
- lintCounts,
492
- plan,
493
- applied,
494
- skipped: curationSkipped,
495
- warnings,
496
- },
521
+ prCommand: submittedCount === 0
522
+ ? "nothing to submit after curation - no PR to open."
523
+ : createdBranch
524
+ ? ghPr
525
+ : `${branchCmd} # if you want a separate memory PR (else push ${branch} directly)\n git push -u origin <new-branch> && ${ghPr}`,
526
+ curation: curationReport,
497
527
  };
498
528
  }
package/dist/tools/ops.js CHANGED
@@ -15,6 +15,7 @@ import { writeMemoryFile, readMemoryFile, ulid, msToRfc3339, MEMORY_TYPE_TAXONOM
15
15
  import { upsertFromFile, deleteFromIndex } from "../store/sync.js";
16
16
  import { findDuplicates, findTurnEcho, supersede, setStatus } from "../store/lifecycle.js";
17
17
  import { TURN_ECHO_WINDOW_MS } from "../capture/handoff.js";
18
+ import { lengthNudge } from "../capture/length.js";
18
19
  import { getUsage, recordUseful, reuseRate, usefulKindFor, usefulCount, deleteUsage, loadReuseReport, } from "../store/usage.js";
19
20
  import { formatReuseReport } from "../reuse-report.js";
20
21
  import { formatCurationAction } from "../curate.js";
@@ -307,6 +308,13 @@ export async function addMemory(getScope, cfg, args) {
307
308
  for (const n of dups.near) {
308
309
  output += `\nNote: similar memory exists (score ${n.score.toFixed(2)}): id=${n.id} — ${n.snippet}. Use memory_supersede if this replaces it.`;
309
310
  }
311
+ // D94: soft length hint. The save already happened (write, dedup, redact
312
+ // above are untouched); over ~500 chars the result just carries a hint so
313
+ // the agent can tighten the memory. Never a refusal - the only hard cap
314
+ // is keyword capture's MAX_CAPTURE_CHARS.
315
+ const nudge = lengthNudge(redacted);
316
+ if (nudge)
317
+ output += `\n${nudge}`;
310
318
  return { title: `memory: saved ${fm.id}`, output };
311
319
  }
312
320
  export async function searchMemories(getScope, cfg, args) {
package/docs/V2-DESIGN.md CHANGED
@@ -582,7 +582,7 @@ requirement: personal data never touches third-party services). Benchmarks to tr
582
582
  for enterprise knowledge systems.
583
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). **First slice built 2026-11-13 (0.10.0-alpha.3, D93):** deterministic auto-apply (exact duplicates / empty bodies / title whitespace), report-only lint and near-duplicates, `--no-curate`, `curate undo`; batch-confirm, semantic merges/splits, and inferred type/tags remain open. D79 follow-ups: feedback-weighted ranking ✅ first slice built 2026-11-11 (0.10.0-alpha.2, D92): opt-in `feedbackWeighting`, near-tied BM25 band reordered by `reuse_rate` only for `retrieved_count >= 3`, explain trace, fixture R@1 0.660 → 0.702 / MRR 0.804 → 0.825; embeddings gate decision against the published baseline; reranker evaluation. Cross-lingual embedding rerank (Stone 2026-10-16, from obsidian-mind comparison): ablation showed multilingual vectors beat BM25 by +12pp R@5 on the cross-lingual slice — the one gap lexical can't cover. Design as opt-in rerank for EN↔ZH queries only, not a default path; local stays BM25-first per the retrieval split above. TDQS nit (separate PR): tighten search/list `type` to `z.enum`. Retrieval eval: grow the fixture (project-scope tier cases) as retrieval logic evolves. Retrieval split — local vs share server (Stone 2026-10-07): the two environments emphasize different mechanisms. Local (personal machine): BM25 + curated index-time expansion as the primary — deterministic, zero model download (D7), fast on CPU, index bloat bounded by the small corpus; embeddings opt-in only. Share server (team/org, enterprise): embeddings + ANN + reranker as the primary — server-grade compute with models resident, corpus too large and multi-author for any curated map; the curated map stays as a precision layer plus org glossary. The server additionally aggregates D77 useful_count across users into feedback-weighted ranking (already in D79 follow-ups) — a signal a single machine can never have. Bottom-up loop: curated pairs that many users converge on locally become org-glossary candidates. Economics flip: N users each downloading a model vs one model amortized on the server. OptMem lessons (Stone 2026-10-16, from kafkaup's OptMem post): three friction-reduction ideas worth stealing from the minimalist end of the spectrum. (1) **Token cost as spec** — measure and publish open-memex's prompt/token overhead in the README, the way OptMem advertises its "426-token prompt"; acquisition copy, not just engineering. (2) **`wake` convention** — document a session-start ritual (one `memory_recall` call at the beginning of every session), mirroring OptMem's `memo wake`; the MCP tools exist but the habit isn't specified. (3) **Capture length nudge** — a soft length cap or conciseness hint at capture time, inspired by OptMem's 280-byte hard cap; forces conciseness at write time, cheap to implement, aligned with the distill-to-AGENTS.md direction (D40). Three-tier memory zones (Stone 2026-10-18, from Westenberg "I Deleted My Second Brain" + his own reflection): the second brain should have zones like cache vs database, not "keep everything" vs "delete everything". **Hot** (active zone, cache-like: small, curated, always in context — D81 aliases, WHAT-level) · **Warm** (compost/incubation: not active but not cold; periodic review, rotted items deleted — this is "forget on purpose" as engineering) · **Cold** (full archive, searchable, not resident). The hard part is the **promotion/demotion policy** — what moves between zones, when, by what rule (the cache-replacement problem for knowledge; "useful" ≠ "recently used"). Capture restraint is a separate gate: not everything deserves to enter even cold storage. Spec the policy before building the zones. Auto-capture design brief (Stone 2026-10-19, from ai-memory comparison): open-memex wants auto-capture but under the restraint philosophy (not ai-memory's capture-everything). Five design questions: (1) **End-session trigger** — what hooks does opencode actually expose? (check before designing; ai-memory built finalize-session fallback for harnesses without SessionEnd); candidates: native hook / idle timeout / explicit command / context-near-full. (2) **Distillation** — rules first (what happened: git diff, tool calls, decision sentences; zero LLM), interpretation layer (what it means) left to human/LLM. (3) **Save-value triage** — three tiers: clearly valuable → save; clearly noise → drop; ambiguous → ask human. Boundary principle: **rather over-ask than over-save** (polluted retrieval costs more than a missed memory). (4) **Routing** — four exits: project memory / personal memory / AGENTS.md proposal (distill-agents exists) / discard; keep v1 routing rules simple. (5) **Human interaction** — one batch confirmation at session end ("save these 3? [y/n/edit]"), never per-item popups. Relations: D73 keyword capture is turn-level (no conflict); `wake` convention is session-start (this is session-end — the other bookend); three-tier zones govern where auto-captured items land. Cross-agent study (Stone 2026-10-19): open-memex has cross-agent on the roadmap — study how ai-memory does it (handoff claim-once semantics, lifecycle hooks per harness, VSCode support via MCP-only) before designing ours; borrow the semantics, not the push-injection behavior (discoverability > injection). Injection cost discipline (Stone 2026-10-19, from Harness² paper arXiv:2610.14224): "ALWAYS-ON PROSE IS THE EXPENSIVE OPTION" — every always-on word competes with the agent's output budget. Current session-start injection (8 project + 5 personal) is the expensive path; direction: move "important but not needed every turn" memories to on-demand (tool/skill-triggered loading), keep only truly every-turn items resident. Tolerable now, better not to tolerate. Component cost ladder for reference: SKILL (default, zero-cost until invoked) > SCRIPT > SUBAGENT > PLUGIN ("prose can be skipped, a hook cannot") > ALWAYS-ON TEXT (last resort). Read-less compression (Stone 2026-10-19, from caveman https://github.com/JuliusBrussee/caveman): the execution layer of injection cost discipline — compress what the agent READS before it reaches context, not just what we inject. Caveman's measured numbers: 33.2% fewer input tokens per session (CSV 98.9%, logs 98.5%, YAML 99.1%, JSON 98.5% per-file; HTML has no compressor yet). Direction for open-memex: a pre-retrieval compression pass on tool outputs and retrieved passages (structured data → compact form), originals stay on disk and pullable on demand. Two design principles borrowed: (1) never compress the user's own prompt/input (Adobe CAVEWOMAN finding: cavemanning user prompts makes answers worse); (2) leave code/tool calls/payloads verbatim — compress the wrapper, not the payload. Caveats: caveman's own rules cost ~1,160 input tokens fixed; per-request billing (Copilot-style) nullifies the saving — compression pays off on per-token billing only. Knowledge upkeep as a first-class direction (Stone 2026-10-23; external validation: Hedy Zhang's FDE field retrospective on enterprise AI knowledge bases, X article 2026-10-22 — enterprise knowledge bases die on unowned upkeep, not on retrieval: stale answers served silently, conflicts with no owner, updates nobody owns after delivery). The mechanisms already exist (supersede chains, lifecycle states, `audit` health check, curator convention); the direction is driving the human cost of upkeep toward zero: (1) staleness signals — age, contradiction with newer captures, D77 zero-reuse counters — feeding a standing review queue instead of waiting for someone to remember to run `audit`; (2) a conflict inbox — semantic conflicts and broken chains as a persistent todo; (3) the endgame is D78 confidence-tier auto-curation (auto-apply the safe tier, batch-confirm the rest). Success metric: the base stays trustworthy on minutes-per-week of human attention, not a curator shift. README pitches the shipped half of this as core concept 4 (Knowledge stays current) plus a "When facts change" comparison row. Session working state note (D89, 2026-11-02) → BUILT, shipped 2026-11-03 as D90: 12th tool `memory_workingstate` on both hosts, session-start surfacing, `audit` expiry report, `wstate` CLI; opencode write path is instruction + tool (plugin API has no Stop hook).
584
584
 
585
- - **Build order after D77-L3 (2026-11-04, Stone approved; (1) shipped 2026-11-06).** Once PR #74 (D77-L3 reuse report) merges, the queue is: (1) §20 / D88 deterministic half — **shipped 0.9.0-alpha.6 (D91)**: `graph build` (structural edges only), compiled outline injected at session start, `graph neighbours` / `graph path` / `graph outline` / `graph lint` CLI (orphans / dangling / stale; missing-page alerts are part of the LLM half, still open); no LLM, no ranking change. Remaining under §20: **the LLM half** — semantic insights, missing-page alerts that propose new memories (through the D61 propose-first flow), compiled wiki pages — D78's pre-submit integration of the lint report shipped in D93 (0.10.0-alpha.3); the LLM half stays open. (2) D79 feedback-weighted ranking — **first slice shipped 0.10.0-alpha.2 (D92)**: fixture + baseline landed first, then an opt-in reuse-signal band reorder (`retrieved_count >= 3`, `reuse_rate`, 0.75 near-tie band); no embedding/cross-lingual rerank yet. (3) D78 curate+submit — **first slice shipped 0.10.0-alpha.3 (D93)**: pre-submit lint + deterministic auto-apply (exact duplicate / empty body / title) + `curate undo`, fixture 9→6 lint findings; batch-confirm, semantic merge/split, and type/tag inference remain the upkeep endgame. (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 — D78's pre-submit integration of the lint report shipped in D93 (0.10.0-alpha.3); the LLM half stays open. (2) D79 feedback-weighted ranking — **first slice shipped 0.10.0-alpha.2 (D92)**: fixture + baseline landed first, then an opt-in reuse-signal band reorder (`retrieved_count >= 3`, `reuse_rate`, 0.75 near-tie band); no embedding/cross-lingual rerank yet. (3) D78 curate+submit — **first slice shipped 0.10.0-alpha.3 (D93)**: pre-submit lint + deterministic auto-apply (exact duplicate / empty body / title) + `curate undo`, fixture 9→6 lint findings; batch-confirm, semantic merge/split, and type/tag inference remain the upkeep endgame. (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 — **shipped 0.10.0-alpha.4 (D94)**: token cost measured (`scripts/token-cost.ts`, chars/4 estimate) and published in the READMEs; `wake` ritual documented (README en+zh, Agent Skill, MCP handshake - docs only, no new surface); capture length nudge at 500 chars (hint appended to the save result, never a refusal; keyword 2000-char hard cap unchanged, over-cap drops now surface in the D73 hand-off note). (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.