open-memex 0.7.0-alpha.9 → 0.7.0

package/dist/tools/ops.js

@@ -7,19 +7,19 @@
  * result; each host adapts that to its own tool-result shape.
  */
 import fs from "node:fs";
-import path from "node:path";
 import { z } from "zod";
 import { PERSONAL_SCOPE } from "../scope.js";
 import { search, list, countList, hitStateLabel } from "../retrieve/search.js";
 import { formatInventoryLine, truncationNote } from "../retrieve/display.js";
 import { writeMemoryFile, readMemoryFile, ulid, msToRfc3339, MEMORY_TYPE_TAXONOMY, normalizeAliases, } from "../store/markdown.js";
 import { upsertFromFile, deleteFromIndex } from "../store/sync.js";
-import { findDuplicates, supersede, setStatus } from "../store/lifecycle.js";
+import { findDuplicates, findTurnEcho, supersede, setStatus } from "../store/lifecycle.js";
+import { TURN_ECHO_WINDOW_MS } from "../capture/handoff.js";
 import { db } from "../store/db.js";
 import { redact } from "../redact.js";
 import { getSyncStatus, formatSyncStatus, submitMemories, outboxDraftCount } from "../submit.js";
 import { getPrStatus, formatPrStatus, applyPrStatus } from "../github.js";
-import { paths } from "../paths.js";
+import { isInRepoMemoryFile } from "../paths.js";
 import { proposeMemories, promoteMemory, listConflicts, resolveConflict, formatReviewHistory, } from "../review.js";
 /**
  * D53: push, don't poll. Append the project-outbox pending count to mutating
@@ -38,7 +38,7 @@ export async function withOutboxNote(scopeKey, p, reviewHint) {
 }
 /** LLM-facing tool descriptions, shared by the opencode plugin and the MCP server. */
 export const TOOL_DESCRIPTIONS = {
-    memory_add: "Save a fact, preference, decision, or note to persistent local memory. Call this PROACTIVELY whenever the user shares something worth remembering across sessions — project conventions, tool choices, personal preferences, decisions made, error fixes and their causes. Worth saving: decisions and their reasons, preferences, conventions, gotchas, approaches tried and abandoned. Not worth saving: one-off task details or anything re-derivable from the code. Do not wait to be asked. For facts you infer yourself rather than the user stating, propose them first and save only on approval. Keep each memory to one self-contained statement; attach aliases when the parameter is available. Default scope is the current project; use the personal scope for facts about the user that apply across all projects.",
+    memory_add: "Save a fact, preference, decision, or note to persistent local memory. Call this PROACTIVELY whenever the user shares something worth remembering across sessions — project conventions, tool choices, personal preferences, decisions made, error fixes and their causes. Worth saving: decisions and their reasons, preferences, conventions, gotchas, approaches tried and abandoned. Not worth saving: one-off task details or anything re-derivable from the code. Do not wait to be asked. For facts you infer yourself rather than the user stating, propose them first and save only on approval. Keep each memory to one self-contained statement; attach aliases when the parameter is available. If a note tells you the user's own wording was already stored verbatim this turn, that statement is already saved: do not retry it in a rewording — save only what that text does not contain, or use memory_supersede on the given id. Default scope is the current project; use the personal scope for facts about the user that apply across all projects.",
     memory_search: "Search persistent memory by keyword (BM25 full-text). Returns matching memories from the current project and/or personal scope. Call before asking the user about past decisions, conventions, or preferences they may have told you before. Search well: break the question into its concepts and try 2–3 phrasings per concept — synonyms, the user's other language, shorter keyword forms — and check the other scope too, before concluding nothing is stored.",
     memory_list: "List memories in a scope, newest first, as a numbered inventory. Each line keeps the raw fields — [type] id=… created=… source=… — say them back to the user in plain words (source=user → 'you told me this'; inference → 'I inferred this, check me'; keyword → 'caught from your own wording'), never read the raw id aloud unless they ask. When the user asks 'what do you remember about me?', use scope=both and present the inventory conversationally. The user may point at an entry by its number ('delete #3'): numbers are only valid for the listing you just produced — re-run memory_list, read the candidate back in full, and get a confirmation before calling memory_forget (deletion is permanent). include=all is the audit view (superseded versions, retracted, archived also shown).",
     memory_supersede: "Replace an existing memory with a newer version. The old memory is kept as history (status: superseded) and retrieval returns the new one. Use when a saved fact becomes outdated and should be replaced rather than duplicated.",
@@ -198,6 +198,26 @@ export async function addMemory(getScope, cfg, args) {
             output: `Identical memory already exists: id=${dups.exact.id}. Not duplicated.`,
         };
     }
+    // D73: one user statement, one memory. The keyword hook stores the user's
+    // sentence verbatim with no agent in the loop; a paraphrase of that same
+    // sentence is refused instead of written beside it. The stored id comes back
+    // so the caller can supersede it or save only the genuinely new part.
+    const echo = findTurnEcho(s.key, redacted, TURN_ECHO_WINDOW_MS);
+    if (echo.length > 0) {
+        const top = echo[0];
+        const others = echo
+            .slice(1)
+            .map((e) => `id=${e.id} (${e.source}, overlap ${e.score.toFixed(2)})`)
+            .join(", ");
+        return {
+            title: "memory: already captured verbatim",
+            output: `Not saved — the user's own words were already stored moments ago (source: ${top.source}, overlap ${top.score.toFixed(2)}): ` +
+                `id=${top.id} — ${top.snippet}` +
+                (others ? `\nAlso matching: ${others}` : "") +
+                `\nDo not retry with a rewording: that only adds a second copy of one statement. ` +
+                `Save a separate memory only for information that stored text does not contain, or call memory_supersede on that id if this replaces it.`,
+        };
+    }
     const fm = buildFrontmatter(s, {
         type: args.type ?? "fact",
         tags: args.tags ?? [],
@@ -247,10 +267,13 @@ export async function listMemories(getScope, args) {
     // every section reports its true total — a truncated list says so
     // instead of quietly looking complete (the D66 sync-status lesson).
     const include = args.include ?? "active";
+    // D70: numbering runs across every section of THIS listing, so "delete
+    // #3" names exactly one memory. A per-section counter emitted two "#1"s.
+    let seq = 0;
     const render = (scopeKey) => {
         const hits = list(scopeKey, { type: args.type, limit: args.limit, include });
         const total = countList(scopeKey, { type: args.type, include });
-        const lines = hits.map((h, i) => formatInventoryLine(i, h, PERSONAL_SCOPE.key));
+        const lines = hits.map((h) => formatInventoryLine(seq++, h, PERSONAL_SCOPE.key));
         const note = truncationNote(hits.length, total);
         if (note)
             lines.push(note);
@@ -331,7 +354,13 @@ export async function forgetMemory(args) {
             upsertFromFile(mf);
             return {
                 title: "memory: hidden",
-                output: `Hidden ${args.id} (retracted). It no longer appears in lists or search, but the file is kept. This is one-way — to bring the fact back, save it again as a new memory.`,
+                output: `Hidden ${args.id} (retracted). It no longer appears in lists or search, but the file is kept. This is one-way — to bring the fact back, save it again as a new memory.` +
+                    // D70: a retraction of an in-repo memory is a local working-tree
+                    // edit like the delete — without a commit (and a push) the memory
+                    // stands on every teammate's clone, so "hidden" would be a lie.
+                    (isInRepoMemoryFile(row.file_path)
+                        ? ` Note: this memory lives in the repo (.ai/open-memex/), so the retraction is only local until you commit and push it — until then the team still sees it.`
+                        : ""),
             };
         }
         catch (e) {
@@ -360,8 +389,7 @@ export async function forgetMemory(args) {
     // D64: forgetting an in-repo memory deletes a file inside the user's
     // git working tree. Say so — the deletion should ride a commit, or the
     // file silently diverges from what teammates have.
-    const inRepo = row.file_path.includes(`${path.sep}.ai${path.sep}`) &&
-        !row.file_path.startsWith(paths().root);
+    const inRepo = isInRepoMemoryFile(row.file_path);
     return {
         title: "memory: forgotten",
         output: inRepo

package/docs/TEST-PLAN.md

@@ -73,7 +73,7 @@
 
 ## H. 已知问题观察
 
-- [ ] better-sqlite3 在 Node 24 退出时偶发 crash（exit 134）：注意是否丢数据（预期：不丢，只影响退出码）
+- [x] better-sqlite3 在 Node 24 退出时偶发 crash（exit 134）：D72 已把驱动升到 13（N-API 线）；Linux Node 24.20 连续 3 次 `test-full` 114/114。Windows 真机仍需确认同一版本下无 `SIGABRT` / exit 134，且不丢数据。
 - [ ] `memory_list` 默认只列 project scope 是否符合预期（Stone 已定保持现状）
 
 ---

package/docs/V2-DESIGN.md

@@ -1,6 +1,6 @@
 # OpenMemex — Design Document (protocol v0.2)
 
-**Status:** FROZEN — protocol v0.2 (2026-09-26). Decisions D1–D68 are settled; open questions are tracked at the end of this document.
+**Status:** FROZEN — protocol v0.2 (2026-09-26). Decisions D1–D73 are settled; open questions are tracked at the end of this document.
 **Author:** Stone, with 小沐
 **Changelog vs v1:** incorporates round-3 review from Perplexity, Grok, Gemini, ChatGPT, DeepSeek.
 Key changes: Design Principles section; `role` separated from `type`; two iron rules;
@@ -1469,6 +1469,95 @@ requirement: personal data never touches third-party services). Benchmarks to tr
   entry back before deleting. The HTML rendering of the same data layer
   follows as a separate change; auto-draft stays gated on the unlock
   conditions in the design doc.
+- **D73 — one user statement, one memory: the keyword hook hands off to the
+  agent.** The keyword hook and the agent are two writers for one user turn,
+  and only one of them knows the sentence is already stored. Observed
+  2026-10-04: a single `remember this folder is for my spark tank ideas …
+  shared memory across agents and employees` produced **three** memories — one
+  `source: keyword` verbatim capture plus two `source: tool` paraphrases the
+  agent wrote because it could see the chat transcript but not the store. The
+  existing §3.4 guard could not catch it: token Jaccard scored those
+  paraphrases 0.21–0.38 against the capture, below the 0.8 near-dup bar, and
+  `open-memex audit` reported zero near-dup pairs, so the store looked healthy
+  while holding three copies of one statement (retrieval then returns all
+  three). Two mechanisms, deliberately layered:
+  **(a) hand-off note** — `captureFromText` records each capture against the
+  host session id (`chat.message` / v2 `prompt`, both of which carry one), and
+  the system-context hook (`experimental.chat.system.transform` / v2
+  `context`) pushes a short block naming what was already stored, delivered
+  once per capture and pruned after the turn window. The agent can now avoid
+  the duplicate write it had no way to see. In-memory only, like
+  `injectedSessions`: never persisted, gone on restart.
+  **(b) turn-echo guard** — `memory_add` additionally refuses a write that
+  overlaps a `source: keyword`/`user` memory created in the same scope within
+  the last 10 minutes, returning the stored id and pointing at
+  `memory_supersede`. This is the deterministic backstop for the case where
+  (a) is ignored. It is deliberately scoped and high-barred, because lexical
+  overlap **cannot** separate an agent's gloss from a genuinely new fact: in
+  the same measured set, the agent's gloss scored 0.211 and a distinct fact
+  the same sentence happened to contain scored 0.214. So the bar sits at
+  0.28 — wholesale re-saves of the captured sentence measure 0.29–0.36 and are
+  refused; anything below is left to (a) and the agent's judgment, and a
+  refusal always names the stored id so the caller can rephrase to the new
+  part or supersede. Agent-authored `source: tool` saves keep the old 0.8
+  near-dup *notice* and are never refused. The refused case is recoverable by
+  construction (supersede, or a follow-up add carrying only the new
+  information), and no D14-style masking, dedup, or lifecycle rule changes.
+  What is deliberately NOT done: no fuzzy-matching upgrade (D73 measures why a
+  better metric still cannot decide "new information"), no auto-merging of the
+  agent's gloss into the capture, and no transcript store (the replay-distillation
+  open question owns that).
+
+- **D72 — the Node SQLite driver moves to the N-API line.** The D70 suite was stable on Windows and failed in shifting clusters on Linux under Node 24.20: individual CLI processes intermittently died with `SIGABRT` in `Statement::~Statement()` (`RemoveEnvironmentCleanupHook ... Assertion failed: (env) != nullptr`) and lost their stdout, so unrelated supersede / submit / inventory checks failed depending on which process the GC reaped. The work itself had always landed; only the exit path was broken. Root cause is upstream: Node 24.19 changed `node::ObjectWrap` cleanup-hook registration, and `better-sqlite3` <13 (raw `node::ObjectWrap`) can finalize a prepared statement from a GC callback with no Environment entered. `better-sqlite3` 13 is the N-API rewrite and removes that path; it still supports Node ≥22, and every API this repo uses (`Database`, `prepare`, `exec`, `pragma`-style PRAGMAs, `close`) is unchanged. The suite's crash-retry shim stays as belt-and-braces for older installs, but the shipped driver no longer needs it on current Node. Verified: three consecutive Linux `test-full` runs at 114/114 plus a 40-command add/list/search loop with zero aborts (was ~50% per process).
+
+- **D71 — the scope seed is the folder opened, never a filesystem root.**
+  OpenCode v1 hands the plugin two roots: `worktree` (the repo root — but
+  the filesystem root itself, `C:\` or `/`, when the opened folder is not a
+  git repo) and `directory` (the folder actually opened). The v1 adapter
+  preferred `worktree`, so every non-git folder on a drive seeded its scope
+  on the drive root and collapsed into one shared
+  `project__workspace__<hash of the root>` bucket — a `c:\temp` project
+  landing in `project__workspace__3dc8472eaebe` (seed `c:\`) is what
+  surfaced it. `pickScopeRoot` (src/scope.ts) now takes `worktree` only when
+  it is a real directory below the filesystem root, else `directory`. The
+  repo-root behavior is unchanged: a real worktree still wins, so opening a
+  repo subfolder keeps the repo's scope. Memories already written under a
+  root-seeded key stay where they are (no auto-migration, per the existing
+  rule); `open-memex scopes` shows the stray bucket and
+  `open-memex migrate --from <old-key>` moves them. The v2 adapter already
+  seeded on the opened directory and is unaffected.
+
+- **D70 — visibility follow-ups: one number, one guard, one truth.** The
+  3-C review of D68/D69 found the surfaces honest individually and
+  inconsistent with each other. (1) **Every visibility surface discloses
+  truncation.** `memory_list` did; `open-memex list` — the command a
+  sceptical user runs first — silently showed 20 of 25. It now renders
+  the same structured line as the tool and states how many entries it
+  dropped, naming the command that shows everything. (2) **Numbers are
+  unique within a listing.** Ordinals ran per scope, so a single
+  `scope: both` output contained two `#1`s and "delete #3" was a guess;
+  the counter now runs across every section of one listing (tool, CLI and
+  the text report). (3) **A correction that touches the repo says so.**
+  The hard delete already did (D64); the soft hide did not, so a
+  retraction of an in-repo memory read as "hidden" while it was only a
+  local working-tree edit — the team still had the memory. Both surfaces
+  now name the commit and push. (4) **The report guard fails closed and
+  exists once.** `isInsideWorkTree` ran `git -C` on the output's parent
+  directory, so a not-yet-created directory made the check throw and
+  report "not in a worktree" — a fail-open on the one path where personal
+  memories would ride a commit; it now resolves the nearest existing
+  ancestor, reports a missing directory as itself, and both formats share
+  a single refusal helper instead of two copies. (5) **`open-memex-inventory/2`**
+  drops the absolute `file` path: the JSON renderer exists to be handed to
+  an agent, i.e. pasted into a cloud conversation, and it carried the
+  user's home directory. (6) Smaller honesty fixes: an empty scope is
+  reported as `(0)` instead of vanishing; only the HTML audit view loads
+  the hidden rows themselves (text/json pay for counts); the page's
+  "no network requests" claim is now enforced by a `default-src 'none'`
+  CSP rather than asserted; and `countList`'s comment states its one known
+  divergence (a self-healed dangling chain pointer) instead of claiming
+  equivalence. Deliberately NOT done, pending a decision: HTML i18n and a
+  size cap for very large stores.
 
 ## Open Questions
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "open-memex",
-  "version": "0.7.0-alpha.9",
+  "version": "0.7.0",
   "description": "Local-first memory layer and protocol for AI coding agents. Markdown source of truth, SQLite FTS5 index, zero cloud.",
   "type": "module",
   "license": "Apache-2.0",
@@ -23,7 +23,7 @@
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.30.1",
-    "better-sqlite3": "^11.7.0",
+    "better-sqlite3": "^13.0.3",
     "js-yaml": "^4.1.0",
     "zod": "^4.1.8"
   },

package/scripts/smoke-mcp.ts

@@ -128,7 +128,23 @@ try {
   check("memory_list keeps raw provenance field (D68)", listText.includes("source=tool"), listText.slice(0, 160));
   check("memory_list shows age token (D68)", /created=(now|\d+[mhd])/.test(listText), listText.slice(0, 160));
   const listBoth = await req("tools/call", { name: "memory_list", arguments: { scope: "both" } });
-  check("memory_list both scopes (D68)", (listBoth.result?.content?.[0]?.text ?? "").includes("About you"));
+  const listBothText = listBoth.result?.content?.[0]?.text ?? "";
+  check("memory_list both scopes (D68)", listBothText.includes("About you"));
+  // D70: numbers run across the whole listing, so "delete #3" names one memory.
+  // Needs a personal entry too, or there is only one section to number.
+  const personalAdd = await req("tools/call", {
+    name: "memory_add",
+    arguments: { content: "mcp e2e probe: a personal note for the both-scopes listing", type: "fact", scope: "personal" },
+  });
+  check("personal memory added for the both-scopes probe", (personalAdd.result?.content?.[0]?.text ?? "").includes("id="), (personalAdd.result?.content?.[0]?.text ?? "").slice(0, 120));
+  const listBoth2 = await req("tools/call", { name: "memory_list", arguments: { scope: "both" } });
+  const listBothText2 = listBoth2.result?.content?.[0]?.text ?? "";
+  const bothNums = [...listBothText2.matchAll(/^(\d+)\. \[/gm)].map((m) => Number(m[1]));
+  check(
+    "memory_list numbers are unique across scopes (D70)",
+    bothNums.length > 1 && new Set(bothNums).size === bothNums.length && bothNums[0] === 1,
+    JSON.stringify(bothNums),
+  );
 
   // D68: truncation is disclosed, never silent — one shown, total stated.
   const add2 = await req("tools/call", {

package/scripts/smoke-pure.ts

@@ -5,10 +5,17 @@ import { planConversion, isV2File, migrateV2 } from "../src/store/v2migrate.ts";
 import { redact, findSecret } from "../src/redact.ts";
 import { detectKeywords, scanKeywords } from "../src/capture/keywords.ts";
 import { DEFAULT_CONFIG } from "../src/config.ts";
-import { resolveProjectScope, resolveCwdScope, PERSONAL_SCOPE } from "../src/scope.ts";
+import { resolveProjectScope, resolveCwdScope, pickScopeRoot, PERSONAL_SCOPE } from "../src/scope.ts";
 import { cjkIndexText, cjkQueryExpr, hasCjk } from "../src/retrieve/cjk.ts";
 import { toFtsQuery } from "../src/retrieve/query.ts";
 import { contentHash, similarity, NEAR_DUP_THRESHOLD } from "../src/store/lifecycle.ts";
+import {
+  TURN_ECHO_THRESHOLD,
+  TURN_ECHO_WINDOW_MS,
+  isTurnEcho,
+  freshCaptures,
+  formatHandoffBlock,
+} from "../src/capture/handoff.ts";
 import { userMcpConfigPath, mergeServerEntry, detectInstalledClients, mergePluginEntry, mergeV2PluginEntry, removeV2PluginEntry, opencodeGlobalConfigPath, printManualEntryHint, parseJsonConfig, removeServerEntry, removePluginEntry, removeInstructionsSection, LEGACY_PACKAGE_NAME, shouldInstallSkill } from "../src/init.ts";
 import { z } from "zod";
 import { memoryAddArgs } from "../src/tools/ops.ts";
@@ -379,6 +386,17 @@ ok("cwd scope deterministic", cwdOnly.key === cwdOnly2.key);
 // (This repo does have an origin after `git push`.)
 console.log("     cwd.key   =", cwdOnly.key);
 
+console.log("== scope (pickScopeRoot, D71) ==");
+// OpenCode v1 reports the filesystem root as `worktree` for non-git folders;
+// seeding a scope on it merges every non-git folder on the drive into one
+// shared `project__workspace__…` bucket. A real worktree still wins.
+const fsRoot = path.parse(process.cwd()).root;
+ok("real worktree wins", pickScopeRoot(process.cwd(), "/elsewhere/opened") === process.cwd());
+ok("fs-root worktree yields to directory", pickScopeRoot(fsRoot, process.cwd()) === process.cwd());
+ok("missing worktree uses directory", pickScopeRoot(null, process.cwd()) === process.cwd());
+ok("nothing but fs root: last resort", pickScopeRoot(fsRoot, null) === fsRoot);
+ok("no candidates falls back to cwd", pickScopeRoot(null, null) === process.cwd());
+
 console.log("== cjk ==");
 ok("detects han", hasCjk("中文记忆"));
 ok("detects mixed", hasCjk("open中文"));
@@ -604,6 +622,50 @@ const near = similarity(
 ok(`similarity near-dup ${near.toFixed(2)} >= ${NEAR_DUP_THRESHOLD}`, near >= NEAR_DUP_THRESHOLD);
 ok("similarity empty → 0", similarity("", "anything") === 0);
 
+console.log("== handoff (turn echo, D73) ==");
+// One "remember ..." sentence produced three memories on 2026-10-04: the
+// hook's verbatim capture plus two agent paraphrases. The hook capture is
+// what the store already holds; the guard must refuse a re-save of it and
+// must NOT eat a genuinely new fact the same sentence carried.
+const HOOK_CAPTURE =
+  "this folder is for my spark tank ideas for ipipeline.  I have ideas for AI Agents and shared memory/knowledge accross agents and employees.";
+const reworded = [
+  `User's iPipeline spark-tank themes: AI Agents, and shared memory/knowledge across agents and across employees.`,
+  `This folder (C:\\temp\\AI_Inovation) is the user's "spark tank" for iPipeline ideas`,
+  "Planned work in this folder: AI Agents plus shared memory/knowledge across agents and employees",
+];
+const newFacts = [
+  "Deploy smoke tests live in tests/smoke/deploy.spec.ts and need a staging token",
+  "The staging cluster runs 3 nodes in us-east-1",
+  "Never deploy on Fridays after 15:00 UTC",
+];
+for (const r of reworded) {
+  const s = similarity(HOOK_CAPTURE, r);
+  ok(`refuses a re-save (${s.toFixed(2)} >= ${TURN_ECHO_THRESHOLD})`, isTurnEcho(s));
+}
+for (const f of newFacts) {
+  const s = similarity(HOOK_CAPTURE, f);
+  ok(`keeps a new fact (${s.toFixed(2)} < ${TURN_ECHO_THRESHOLD})`, !isTurnEcho(s));
+}
+ok("threshold is inclusive", isTurnEcho(TURN_ECHO_THRESHOLD));
+ok("below threshold passes", !isTurnEcho(TURN_ECHO_THRESHOLD - 0.001));
+
+const now = 1_700_000_000_000;
+const rec = { id: "01ABC", scopeKey: "project__demo__0123456789ab", content: HOOK_CAPTURE, at: now };
+ok("fresh inside window", freshCaptures([rec], now + 1000).length === 1);
+ok("stale past window", freshCaptures([rec], now + TURN_ECHO_WINDOW_MS + 1).length === 0);
+ok("no records → no block", formatHandoffBlock([]) === "");
+const block = formatHandoffBlock([rec]);
+ok("block names the id", block.includes("01ABC"));
+ok("block shows the stored text", block.includes("spark tank"));
+ok("block says do not re-add", block.includes("Do not call memory_add"));
+ok("block points at supersede", block.includes("memory_supersede"));
+ok(
+  "block collapses whitespace",
+  !formatHandoffBlock([{ ...rec, content: "a\n\n  b" }]).includes("\n\n"),
+);
+ok("window is 10 minutes", TURN_ECHO_WINDOW_MS === 10 * 60 * 1000);
+
 console.log("== init --global: userMcpConfigPath / mergeServerEntry ==");
 // D45: user-level MCP config locations, per platform (platform param is injectable).
 ok("vscode win32", userMcpConfigPath("vscode", "win32").endsWith(path.join("Code", "User", "mcp.json")));

package/scripts/test-full.ts

@@ -320,7 +320,7 @@ ok("inventory text lists the personal memory", r.out.includes("fulltest inventor
 ok("inventory text keeps structured provenance", /source=cli/.test(r.out));
 const invJson = cliRetry(["inventory", "--format", "json"], PROJ);
 const invData = JSON.parse(invJson.out.slice(invJson.out.indexOf("{")));
-ok("inventory json is the shared data layer", invData.format === "open-memex-inventory/1" && invData.total >= 1 && Array.isArray(invData.scopes));
+ok("inventory json is the shared data layer", invData.format === "open-memex-inventory/2" && invData.total >= 1 && Array.isArray(invData.scopes), invData.format);
 const invFile = path.join(T, "inventory.json");
 r = cliRetry(["inventory", "--format", "json", "--out", invFile], PROJ);
 ok("inventory --out writes the file", r.code === 0 && fs.existsSync(invFile), (r.err || r.out).slice(0, 150));
@@ -341,6 +341,22 @@ r = cliRetry(["list", "--include", "all"], PROJ);
 ok("hidden memory visible with --include all", r.out.includes(softId) && r.out.includes("[retracted]"), r.out.slice(0, 160));
 r = cliRetry(["forget", softId], PROJ);
 ok("hard forget still deletes a hidden memory", r.code === 0 && /deleted/.test(r.out));
+// D68 follow-up: the HTML rendering of the same data layer.
+const htmlId = addMem(["fulltest html page entry"], PROJ);
+cliRetry(["forget", htmlId, "--soft"], PROJ);
+const htmlFile = path.join(T, "inventory-page.html");
+r = cliRetry(["inventory", "--format", "html", "--out", htmlFile], PROJ);
+ok("inventory --format html writes the page", r.code === 0 && fs.existsSync(htmlFile), (r.err || r.out).slice(0, 150));
+const page = fs.readFileSync(htmlFile, "utf8");
+ok("html page shows current memories", page.includes("fulltest inventory entry"));
+ok("html page escapes memory content", page.includes("&lt;script&gt;alert(1)&lt;/script&gt;") && !page.includes("<script>alert(1)</script>"));
+ok("html page folds the hidden history", page.includes("Replaced &amp; hidden history") && page.includes(htmlId) && page.includes("retracted"));
+ok("html page enforces 'no network' with a CSP", /Content-Security-Policy/.test(page) && /default-src 'none'/.test(page));
+r = cliRetry(["inventory", "--format", "html"], PROJ);
+ok("html defaults to the data dir", r.code === 0 && fs.existsSync(path.join(T, "data", "inventory.html")), (r.err || r.out).slice(0, 150));
+const inTreePage = path.join(PROJ, "page.html");
+r = cliRetry(["inventory", "--format", "html", "--out", inTreePage], PROJ);
+ok("html refuses a worktree path without --allow-personal", r.code !== 0 && !fs.existsSync(inTreePage));
 
 // ---------- 8. pull / push ----------
 console.log("== pull / push ==");
@@ -612,6 +628,147 @@ console.log("== D64: p1 fixes (propose visibility / supersede published / status
   ok("uninstall finds and cleans .jsonc global config", r.code === 0 && !/open-memex/.test(afterText), (r.out + r.err).slice(0, 160) + " || " + afterText.slice(0, 120));
 }
 
+// ---------- 12. D70: the visibility fixes from the 3-C review ----------
+// Last section on purpose: nothing here may perturb the flows above it.
+// It writes only into a scratch project and into appdata fixtures (no
+// commits in PROJ, no extra CLI spawns beyond a handful) so the suite stays
+// order-independent and cheap — the shared PROJ git state is never dirtied.
+console.log("== D70: honest counts, stable numbers, one guard ==");
+{
+  const fixture = (dir: string, id: string, body: string, scopeKey: string) => {
+    const now = new Date().toISOString();
+    fs.mkdirSync(dir, { recursive: true });
+    fs.writeFileSync(
+      path.join(dir, `${id}.md`),
+      `---
+id: ${id}
+schema_version: 2
+scope_key: ${scopeKey}
+scope: project
+visibility: internal
+project_name: d70
+type: fact
+role: knowledge
+importance: normal
+status: active
+tags: []
+source: cli
+created_at: "${now}"
+updated_at: "${now}"
+supersedes: null
+superseded_by: null
+review_state: draft
+proposed_by: null
+approved_by: null
+derived_from: null
+review_note: null
+review_history: []
+---
+
+${body}
+`,
+      "utf8",
+    );
+  };
+
+  // The guard must not fail open: a --out whose parent directory does not
+  // exist used to skip the worktree check (git -C on a missing dir throws)
+  // and then die with a raw ENOENT. Outside a worktree the missing directory
+  // is the only problem left, so it gets its own message.
+  const missingDir = path.join(T, "no-such-dir", "report.json");
+  r = cliRetry(["inventory", "--out", missingDir], PROJ);
+  ok(
+    "inventory explains a missing parent directory",
+    r.code !== 0 && /does not exist/.test(r.err) && !r.err.includes("ENOENT"),
+    (r.err || r.out).slice(0, 160),
+  );
+  // ...and inside a worktree the personal-content refusal wins over it.
+  const missingInTree = path.join(PROJ, "no-such-dir", "report.json");
+  r = cliRetry(["inventory", "--out", missingInTree], PROJ);
+  ok(
+    "worktree refusal wins over a missing directory",
+    r.code !== 0 && /git working tree/.test(r.err) && !fs.existsSync(missingInTree),
+    (r.err || r.out).slice(0, 160),
+  );
+
+  // `open-memex list` is the surface a sceptical user runs first: it must
+  // not look complete when it isn't. Fixtures go straight into the outbox
+  // (appdata, never the repo), so this needs no commits and no cleanup in git.
+  const d70Key = (/project:\s*(\S+)/.exec(cli(["where"], PROJ).out) || [])[1] ?? "";
+  const outboxDir = path.join(TESTENV.MY_O_MEMORY_HOME as string, "memories", d70Key);
+  const fillerIds: string[] = [];
+  for (let i = 0; i < 22; i++) {
+    const cid = `01P1D70${String(i).padStart(19, "0")}`;
+    fillerIds.push(cid);
+    fixture(outboxDir, cid, `fulltest d70 filler ${i} padding text`, d70Key);
+  }
+  cli(["reindex"], PROJ);
+  r = cliRetry(["list", "--limit", "5"], PROJ);
+  ok("cli list discloses truncation", /… and \d+ more not shown/.test(r.out), r.out.slice(-160));
+  ok(
+    "cli list renders the structured inventory line",
+    /^\d+\. \[[a-z]+\] id=\S+ created=\S+ source=/m.test(r.out),
+    r.out.slice(0, 200),
+  );
+  // Numbering runs across the whole listing, so a number names one entry.
+  r = cliRetry(["list", "--scope", "both", "--limit", "5"], PROJ);
+  const nums = [...r.out.matchAll(/^(\d+)\. \[/gm)].map((m) => Number(m[1]));
+  ok(
+    "numbers are unique and ascending across scopes",
+    nums.length > 2 && new Set(nums).size === nums.length && nums[0] === 1 && nums.every((n, i) => i === 0 || n === nums[i - 1]! + 1),
+    JSON.stringify(nums),
+  );
+  // The text report numbers the same way.
+  r = cliRetry(["inventory", "--scope", "project"], PROJ);
+  const textNums = [...r.out.matchAll(/^(\d+)\. \[/gm)].map((m) => Number(m[1]));
+  ok(
+    "inventory text numbers continuously too",
+    textNums.length > 2 && new Set(textNums).size === textNums.length && textNums.every((n, i) => i === 0 || n === textNums[i - 1]! + 1),
+    JSON.stringify(textNums.slice(0, 8)),
+  );
+  for (const id of fillerIds) fs.rmSync(path.join(outboxDir, `${id}.md`), { force: true });
+  cli(["reindex"], PROJ);
+
+  // A retraction of an in-repo memory is a local working-tree edit until it
+  // is committed - "hidden" must not read as "gone for the team". Runs in its
+  // own project so PROJ's git state stays clean for the sections above.
+  const d70Proj = mkproj("d70-proj");
+  const repoHideId = addMem(["fulltest d70 repo retraction"], d70Proj);
+  cliRetry(["submit", repoHideId], d70Proj);
+  r = cliRetry(["forget", repoHideId, "--soft"], d70Proj);
+  ok(
+    "soft hide of a repo memory warns about the commit",
+    /commit and push/i.test(r.out) && /team still sees it/i.test(r.out),
+    r.out.slice(0, 200),
+  );
+  r = cliRetry(["forget", repoHideId], d70Proj);
+  ok("hard forget of a hidden repo memory still deletes", r.code === 0 && /deleted/i.test(r.out), (r.err || r.out).slice(0, 120));
+
+  // An empty scope must still appear: "this project has nothing" is an answer.
+  const emptyProj = mkproj("empty-proj");
+  r = cliRetry(["inventory", "--scope", "project"], emptyProj);
+  ok(
+    "inventory shows an empty scope as 0",
+    /Project:.*\(0\)/.test(r.out) && /nothing remembered/i.test(r.out),
+    r.out.slice(0, 200),
+  );
+
+  // JSON: no absolute local paths, and the format id records the change.
+  r = cliRetry(["inventory", "--format", "json"], PROJ);
+  const invJson2 = JSON.parse(r.out.slice(r.out.indexOf("{")));
+  ok(
+    "inventory json is /2 and carries no absolute file paths",
+    invJson2.format === "open-memex-inventory/2" &&
+      !JSON.stringify(invJson2).includes(TESTENV.MY_O_MEMORY_HOME as string) &&
+      !/"file":/.test(JSON.stringify(invJson2)),
+    `${invJson2.format} ${JSON.stringify(invJson2).slice(0, 120)}`,
+  );
+  ok(
+    "inventory json counts hidden without the entries",
+    invJson2.hidden !== undefined && !("hiddenEntries" in invJson2),
+  );
+}
+
 console.log("\n================ SUMMARY ================");
 console.log(`pass: ${pass}, fail: ${fail}`);
 if (failures.length) { console.log("failed tests:"); for (const f of failures) console.log("  - " + f); }

package/skills/open-memex/SKILL.md

@@ -25,6 +25,12 @@ open-memex add "I prefer concise diffs" --scope personal   # applies everywhere
 Keep each memory one self-contained statement. Scope routing: facts about the
 user ("I"/"me") → `personal`; everything else → the current project.
 
+One thing the user said is one memory. When their own wording triggered keyword
+capture (`remember …`, `记住…`), that sentence is already stored — do not save it
+again in any rewording. Save only what the stored text does not contain, as its
+own statement; if your version replaces it, use `memory_supersede`. `memory_add`
+refuses the echo and hands you the stored id.
+
 Worth saving: decisions and their reasons, preferences, conventions, gotchas,
 approaches tried and abandoned. Not worth saving: one-off task details or
 anything re-derivable from the code.
@@ -78,7 +84,9 @@ plain words (who the words came from, when it was saved, project or
 personal) instead of reading raw ids. If the user asks to remove one,
 read the entry back in full and get a confirmation before deleting —
 deletion is permanent, there is no undo. If they hesitate, offer hiding
-instead (`--soft`): it leaves lists and search but the file survives.
+instead (`--soft`): it disappears from lists and search, but the file
+survives. Either way, if the memory lives in the repo, the change is only
+yours until you commit and push it.
 
 ```sh
 open-memex forget <id>          # delete (permanent)

package/src/capture/handoff.ts

@@ -0,0 +1,74 @@
+/**
+ * Turn hand-off between keyword capture and the agent (D73).
+ *
+ * The keyword hook and the agent are two writers for one user turn. The hook
+ * stores the user's sentence verbatim, with no agent in the loop; the agent
+ * then sees only the chat transcript and cannot tell the sentence is already
+ * stored, so it saves its own paraphrase — the same statement lands two or
+ * three times (observed 2026-10-04: one `remember …` sentence → one
+ * `source: keyword` file plus two `source: tool` files).
+ *
+ * Two mechanisms, in this order:
+ *   (a) the hand-off note — this module's `formatHandoffBlock`, pushed into the
+ *       turn's system context so the agent knows what is already stored;
+ *   (b) the turn-echo guard — `TURN_ECHO_THRESHOLD` below, enforced in
+ *       `addMemory` (src/tools/ops.ts) over what the hook just wrote.
+ *
+ * Pure module: no db, no fs, no config, so the threshold behavior is testable
+ * in scripts/smoke-pure.ts.
+ */
+
+/**
+ * Overlap bar for refusing a re-save of a just-captured user statement.
+ *
+ * Deliberately high, and only ever applied to memories the *hook* wrote
+ * (`source: keyword` / `user`) inside `TURN_ECHO_WINDOW_MS`. Measured on the
+ * reported case and its near neighbours (token Jaccard, see
+ * `similarity` in src/store/lifecycle.ts): a wholesale re-save of the captured
+ * sentence scores 0.29–0.36, while a genuinely distinct fact the same
+ * sentence also contained scores 0.21 and below. Lexical overlap cannot
+ * separate an agent's gloss from a new fact — those two measured 0.211 and
+ * 0.214 — so the guard sits at the high-confidence end and everything under
+ * the bar is left to (a) and the agent's judgment. A refusal is always
+ * reported with the stored id, so the caller can supersede or rephrase.
+ */
+export const TURN_ECHO_THRESHOLD = 0.28;
+
+/** How long a hook capture counts as "this turn" (10 minutes). */
+export const TURN_ECHO_WINDOW_MS = 10 * 60 * 1000;
+
+/** One hook capture, in memory only — never persisted (like `injectedSessions`). */
+export interface CaptureRecord {
+  id: string;
+  scopeKey: string;
+  content: string;
+  at: number;
+  /** The note has already been pushed for this capture. */
+  delivered?: boolean;
+}
+
+export function isTurnEcho(score: number): boolean {
+  return score >= TURN_ECHO_THRESHOLD;
+}
+
+/** Records still inside the window. */
+export function freshCaptures(records: CaptureRecord[], now: number): CaptureRecord[] {
+  return records.filter((r) => now - r.at <= TURN_ECHO_WINDOW_MS);
+}
+
+function preview(content: string): string {
+  const one = content.replace(/\s+/g, " ").trim();
+  return one.length > 160 ? `${one.slice(0, 160)}…` : one;
+}
+
+/** The hand-off note (a). Empty string when there is nothing to hand off. */
+export function formatHandoffBlock(records: CaptureRecord[]): string {
+  if (records.length === 0) return "";
+  const lines = records.map((r) => `- id=${r.id} (${r.scopeKey}) — "${preview(r.content)}"`);
+  return [
+    "[open-memex] The user's own wording in this turn was ALREADY stored verbatim, before you saw it. It is not unsaved.",
+    ...lines,
+    "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.",
+    "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.",
+  ].join("\n");
+}