open-memex 0.7.0-alpha.8 → 0.7.0

package/src/distill-agents.ts

@@ -92,6 +92,13 @@ export function distillAgentsMarkdown(opts: DistillAgentsOptions): string {
     // stated them ("tool"). Keep the rubric one voice across surfaces.
     `- Mark captures you infer (rather than the user stating) with`,
     `  \`source: "inference"\` — provenance matters more than polish.`,
+    // D68: same voice for the visibility surface — opencode agents reading
+    // this footer never see the MCP handshake either.
+    `- When the user asks what you remember, list it conversationally`,
+    `  (\`memory_list\` with scope both, or \`open-memex inventory\`) — plain`,
+    `  words, not raw ids. Before deleting an entry they point at, read it`,
+    `  back in full and confirm; deletion is permanent. Offer hiding`,
+    `  (\`memory_forget\` soft / \`forget --soft\`) when they hesitate.`,
   );
   lines.push(``);
   return lines.join("\n");

package/src/index.ts

@@ -3,8 +3,10 @@ import {
   PLUGIN_ID,
   bootstrapPlugin,
   captureFromText,
+  captureHandoff,
   injectOnce,
 } from "./plugin-core.ts";
+import { pickScopeRoot } from "./scope.ts";
 import { makeTools } from "./tools/memory.ts";
 import { v2Plugin } from "./opencode-v2.ts";
 
@@ -19,26 +21,32 @@ import { v2Plugin } from "./opencode-v2.ts";
  * type-only (D58), and v2's decode is structural.
  */
 const server: Plugin = async ({ worktree, directory }) => {
-  const roots = worktree || directory || process.cwd();
-  const state = bootstrapPlugin(roots);
+  // v1's `worktree` is the filesystem root for non-git folders — never seed a
+  // scope on it (D71). `pickScopeRoot` falls back to the opened `directory`.
+  const state = bootstrapPlugin(pickScopeRoot(worktree, directory));
   const tools = makeTools(() => state.scope, state.cfg);
 
   return {
     tool: tools,
 
-    async "chat.message"(_input, output) {
+    async "chat.message"(input, output) {
       const parts = (output.parts ?? []) as Array<{ type: string; text?: string }>;
       const text = parts
         .map((p) => (p?.type === "text" ? p.text ?? "" : ""))
         .filter(Boolean)
         .join("\n");
-      captureFromText(text, state);
+      captureFromText(text, state, input.sessionID ?? "");
     },
 
     async "experimental.chat.system.transform"(input, output) {
-      injectOnce(input.sessionID ?? "", state, (block) => {
+      const sessionID = input.sessionID ?? "";
+      injectOnce(sessionID, state, (block) => {
         output.system.push(block);
       });
+      // D73: runs on every request, so the note lands on the very turn whose
+      // message the hook just captured. Delivered once per capture.
+      const handoff = captureHandoff(sessionID, state);
+      if (handoff) output.system.push(handoff);
     },
   };
 };

package/src/inventory-html.ts

@@ -0,0 +1,191 @@
+/**
+ * HTML renderer for the inventory (D68 follow-up): a single local file
+ * a user opens in any browser to read what the store remembers. It
+ * renders the SAME data layer as the text/JSON formats
+ * (`src/inventory.ts`) — one source, three renderings, no drift.
+ *
+ * Design rules (3-C v2) enforced here:
+ * - Every byte of memory content is HTML-escaped. Memory text can come
+ *   from an imported bundle or a pasted web page; under file:// an
+ *   unescaped <script> would execute in the user's own browser.
+ * - The filter box is plain show/hide over server-rendered entries
+ *   (no innerHTML, no network, no external resources).
+ * - History (superseded versions, retracted, archived) is a folded
+ *   section with supersede-chain pointers — auditable, never mixed
+ *   into "what is remembered now". At scale (>50 current entries) the
+ *   scope sections fold too.
+ * - Read-only: no delete buttons, no server callback. Deletion stays a
+ *   confirmed conversation; the page says so, with the id to quote.
+ */
+
+import path from "node:path";
+
+import { PERSONAL_SCOPE } from "./scope.ts";
+import {
+  escapeHtml,
+  relativeTime,
+  reviewStateLabel,
+  sourceLabel,
+} from "./retrieve/display.ts";
+import type { InventoryData, InventoryRow } from "./inventory.ts";
+
+const FOLD_THRESHOLD = 50;
+
+function entryHtml(row: InventoryRow, now: number): string {
+  const meta: string[] = [escapeHtml(sourceLabel(row.source))];
+  const when = relativeTime(row.created_at, now);
+  if (when) meta.push(escapeHtml(when));
+  if (row.scope_key !== PERSONAL_SCOPE.key) {
+    meta.push(escapeHtml(reviewStateLabel(row.review_state)));
+    if (row.review_state !== "draft") {
+      meta.push(
+        row.file_path.replace(/\\/g, "/").includes("/.ai/open-memex/")
+          ? "file is in the repo"
+          : "file is not in the repo yet",
+      );
+    }
+  }
+  if (row.status !== "active") meta.push(escapeHtml(`marked ${row.status}`));
+  return `    <article class="entry">
+      <p class="body">${escapeHtml(row.content.trim())}</p>
+      <p class="meta">${meta.join(" · ")} · <span class="id">id ${escapeHtml(row.id)}</span></p>
+    </article>`;
+}
+
+function hiddenEntryHtml(row: InventoryRow, now: number): string {
+  const when = relativeTime(row.created_at, now);
+  const chain = row.superseded_by
+    ? ` · replaced by <span class="id">${escapeHtml(row.superseded_by)}</span>`
+    : "";
+  return `    <article class="entry hidden-entry">
+      <p class="body">${escapeHtml(row.content.trim())}</p>
+      <p class="meta">${escapeHtml(row.status)}${when ? ` · saved ${escapeHtml(when)}` : ""}${chain} · <span class="id">id ${escapeHtml(row.id)}</span></p>
+    </article>`;
+}
+
+function sectionHtml(
+  title: string,
+  blurb: string,
+  entries: string,
+  count: number,
+  fold: boolean,
+  open: boolean,
+): string {
+  if (fold) {
+    return `  <details${open ? " open" : ""}>
+    <summary>${escapeHtml(title)} <span class="count">${count}</span></summary>
+    <p class="blurb">${escapeHtml(blurb)}</p>
+${entries}
+  </details>`;
+  }
+  return `  <section>
+    <h2>${escapeHtml(title)} <span class="count">${count}</span></h2>
+    <p class="blurb">${escapeHtml(blurb)}</p>
+${entries || '    <p class="empty">(nothing here yet)</p>'}
+  </section>`;
+}
+
+export function renderInventoryHtml(data: InventoryData): string {
+  const now = Date.now();
+  const fold = data.total > FOLD_THRESHOLD;
+  const personalCount = data.scopes
+    .filter((s) => s.scopeKey === PERSONAL_SCOPE.key)
+    .reduce((n, s) => n + s.rows.length, 0);
+
+  const parts: string[] = [];
+  data.scopes.forEach((s, i) => {
+    const isPersonal = s.scopeKey === PERSONAL_SCOPE.key;
+    parts.push(
+      sectionHtml(
+        isPersonal ? "About you — personal" : `Project: ${s.projectName}`,
+        isPersonal
+          ? "These describe you, apply in every project, and never leave this machine."
+          : "Project memories. Each entry says whether it is still only on this machine (the outbox) or has reached the repo.",
+        s.rows.map((r) => entryHtml(r, now)).join("\n"),
+        s.rows.length,
+        fold,
+        isPersonal || i === 0,
+      ),
+    );
+  });
+  if (data.outbox.length > 0) {
+    parts.push(
+      sectionHtml(
+        "Not in the repo yet — outbox drafts",
+        "These drafts exist only on this machine. They reach the repo through review (submit → promote), never automatically.",
+        data.outbox.map((r) => entryHtml(r, now)).join("\n"),
+        data.outbox.length,
+        fold,
+        false,
+      ),
+    );
+  }
+  if (data.hiddenEntries.length > 0) {
+    const h = data.hiddenEntries.map((r) => hiddenEntryHtml(r, now)).join("\n");
+    parts.push(`  <details>
+    <summary>Replaced &amp; hidden history <span class="count">${data.hiddenEntries.length}</span></summary>
+    <p class="blurb">Older versions and withdrawn memories. Kept so you can audit how a fact changed; none of this is used for recall.</p>
+${h}
+  </details>`);
+  }
+
+  return `<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<!-- D70: the page claims it makes no network requests - enforce it. Inline
+     style/script are the only allowances; anything else (a stray <img
+     src>, a remote font) is blocked by the browser, not just by our promise. -->
+<meta http-equiv="Content-Security-Policy" content="default-src 'none'; style-src 'unsafe-inline'; script-src 'unsafe-inline'">
+<title>What OpenMemex remembers</title>
+<style>
+  body { font-family: system-ui, sans-serif; margin: 2rem auto; max-width: 44rem; padding: 0 1rem; color: #1a1a1a; background: #fdfdfb; }
+  h1 { font-size: 1.4rem; margin-bottom: 0.25rem; }
+  h2, summary { font-size: 1.1rem; font-weight: 600; }
+  summary { cursor: pointer; margin: 1.2rem 0 0.4rem; }
+  .sub { color: #666; font-size: 0.9rem; margin-top: 0; }
+  .count { color: #888; font-weight: normal; font-size: 0.85em; }
+  .blurb { color: #555; font-size: 0.9rem; }
+  .entry { border-top: 1px solid #e5e2d9; padding: 0.75rem 0; }
+  .hidden-entry { opacity: 0.75; }
+  .body { white-space: pre-wrap; margin: 0 0 0.35rem; }
+  .meta { color: #666; font-size: 0.82rem; margin: 0; }
+  .id { font-family: ui-monospace, monospace; font-size: 0.78rem; }
+  .empty { color: #888; }
+  .howto { background: #f4f1e8; border-radius: 6px; padding: 0.75rem 1rem; font-size: 0.9rem; }
+  input[type="search"] { width: 100%; padding: 0.5rem; font-size: 1rem; margin: 1rem 0; box-sizing: border-box; }
+  .hidden { display: none; }
+</style>
+</head>
+<body>
+<h1>What OpenMemex remembers about you</h1>
+<p class="sub">Generated ${escapeHtml(data.generatedAt)} · ${data.total} memories (${personalCount} personal, ${data.total - personalCount} project incl. outbox). Read-only report.</p>
+<input type="search" id="filter" placeholder="Filter memories…" aria-label="Filter memories">
+<div class="howto">
+  <strong>Checking my work:</strong> every entry shows where it came from.
+  “I inferred this” means I wrote it from context, not from your words — those are the ones to check.
+  To remove one, tell your agent <em>“forget the memory about …”</em> (quote the id if you like) and it will read the entry back before deleting it — deletion is permanent, there is no undo.
+  A memory that lives in a repo is only truly gone once the deletion is committed.
+</div>
+${parts.join("\n")}
+<script>
+  var input = document.getElementById('filter');
+  input.addEventListener('input', function () {
+    var q = input.value.trim().toLowerCase();
+    var entries = document.querySelectorAll('.entry');
+    for (var i = 0; i < entries.length; i++) {
+      var el = entries[i];
+      el.classList.toggle('hidden', q !== '' && el.textContent.toLowerCase().indexOf(q) === -1);
+    }
+  });
+</script>
+</body>
+</html>
+`;
+}
+
+/** Default report location: the data dir, never a working tree. */
+export function defaultHtmlOutPath(dataRoot: string): string {
+  return path.join(dataRoot, "inventory.html");
+}

package/src/inventory.ts

@@ -0,0 +1,242 @@
+/**
+ * `open-memex inventory` (D68): what the store remembers, in the open.
+ * One data layer, three renderers (text / json / html). The HTML
+ * renderer lives in inventory-html.ts; this module owns the data and
+ * the two renderers an agent or a terminal consumes directly.
+ *
+ * Design rules (3-C v2) enforced here:
+ * - Default scope is personal + the current project — "can't see it"
+ *   is the disease this surface treats.
+ * - Nothing truncates silently: every section states its totals, and
+ *   hidden history (superseded versions, retracted, archived) is
+ *   counted and pointed at, never just omitted.
+ * - Drafts that have not reached the repo (the outbox) are their own
+ *   section, consistent with what memory_status reports.
+ * - The report is read-only. Deleting stays a confirmed conversation.
+ */
+
+import { db } from "./store/db.ts";
+import { PERSONAL_SCOPE } from "./scope.ts";
+import { formatInventoryLine } from "./retrieve/display.ts";
+
+export interface InventoryRow {
+  id: string;
+  scope_key: string;
+  project_name: string;
+  type: string;
+  status: string;
+  review_state: string;
+  source: string;
+  created_at: number;
+  updated_at: number;
+  content: string;
+  file_path: string;
+  superseded_by?: string | null;
+}
+
+export interface InventoryData {
+  generatedAt: string;
+  /** Currently-remembered rows (active/deprecated), grouped by scope. */
+  scopes: Array<{ scopeKey: string; projectName: string; rows: InventoryRow[] }>;
+  /** Project drafts still in the outbox (not in the repo yet). */
+  outbox: InventoryRow[];
+  /** History that exists but is not "remembered": counted, not listed. */
+  hidden: { superseded: number; retracted: number; archived: number };
+  /**
+   * The hidden rows themselves — audit surfaces only. D70: loaded when
+   * the caller asks for `hidden: "entries"` (the HTML report); text/json
+   * report the counts and must not pay to load every retired body.
+   */
+  hiddenEntries: InventoryRow[];
+  total: number;
+}
+
+const BASE_COLS = `id, scope_key, project_name, type, status, review_state,
+  source, created_at, updated_at, content, file_path`;
+
+/**
+ * Load the inventory for the given scopes. `projectScopeKey` separates the
+ * outbox drafts (they belong to that scope's draft rows).
+ *
+ * D70: `hidden: "entries"` fetches the hidden rows themselves (HTML audit
+ * view); the default keeps the cheap COUNT query, because pulling every
+ * superseded body for a text report nobody reads is pure waste.
+ */
+export function loadInventory(
+  scopeKeys: string[],
+  opts: { hidden?: "counts" | "entries" } = {},
+): InventoryData {
+  const inList = scopeKeys.map(() => "?").join(",");
+  const current = db()
+    .prepare(
+      `SELECT ${BASE_COLS} FROM memories
+       WHERE scope_key IN (${inList}) AND status IN ('active', 'deprecated')
+       ORDER BY scope_key, updated_at DESC`,
+    )
+    .all(...scopeKeys) as unknown as InventoryRow[];
+  const hiddenEntries: InventoryRow[] =
+    opts.hidden === "entries"
+      ? (db()
+          .prepare(
+            `SELECT ${BASE_COLS}, superseded_by FROM memories
+             WHERE scope_key IN (${inList}) AND status IN ('superseded', 'retracted', 'archived')
+             ORDER BY updated_at DESC`,
+          )
+          .all(...scopeKeys) as unknown as InventoryRow[])
+      : [];
+  const hidden = { superseded: 0, retracted: 0, archived: 0 };
+  if (hiddenEntries.length > 0) {
+    for (const r of hiddenEntries) {
+      if (r.status === "superseded") hidden.superseded++;
+      if (r.status === "retracted") hidden.retracted++;
+      if (r.status === "archived") hidden.archived++;
+    }
+  } else {
+    const counted = db()
+      .prepare(
+        `SELECT status, COUNT(*) AS n FROM memories
+         WHERE scope_key IN (${inList}) AND status IN ('superseded', 'retracted', 'archived')
+         GROUP BY status`,
+      )
+      .all(...scopeKeys) as unknown as Array<{ status: string; n: number }>;
+    for (const r of counted) {
+      if (r.status === "superseded") hidden.superseded = r.n;
+      if (r.status === "retracted") hidden.retracted = r.n;
+      if (r.status === "archived") hidden.archived = r.n;
+    }
+  }
+
+  const outbox = current.filter(
+    (r) => r.scope_key !== PERSONAL_SCOPE.key && r.review_state === "draft",
+  );
+  const outboxIds = new Set(outbox.map((r) => r.id));
+
+  const byScope = new Map<string, InventoryRow[]>();
+  for (const r of current) {
+    if (outboxIds.has(r.id)) continue;
+    const arr = byScope.get(r.scope_key) ?? [];
+    arr.push(r);
+    byScope.set(r.scope_key, arr);
+  }
+  // Personal first, then project scopes by key for a stable order.
+  // D70: every requested scope appears, including one with nothing in it —
+  // "this project has no memories" is part of the answer, and dropping the
+  // section made the report look like the project was never looked at.
+  const orderedKeys = [
+    ...scopeKeys.filter((k) => k === PERSONAL_SCOPE.key),
+    ...scopeKeys.filter((k) => k !== PERSONAL_SCOPE.key).sort(),
+  ];
+  const scopes = orderedKeys.map((k) => {
+    const rows = byScope.get(k) ?? [];
+    return {
+      scopeKey: k,
+      projectName: rows[0]?.project_name || k,
+      rows,
+    };
+  });
+
+  return {
+    generatedAt: new Date().toISOString(),
+    scopes,
+    outbox,
+    hidden,
+    hiddenEntries,
+    total: current.length,
+  };
+}
+
+function hiddenLine(data: InventoryData): string {
+  const { superseded, retracted, archived } = data.hidden;
+  if (superseded + retracted + archived === 0) return "";
+  return `Not shown: ${superseded} superseded version(s), ${retracted} retracted, ${archived} archived — inspect with \`open-memex list --include all\`.`;
+}
+
+function entriesText(rows: InventoryRow[], startAt = 0): string {
+  if (rows.length === 0) return "(nothing remembered in this scope yet)";
+  return rows
+    .map((r, i) =>
+      formatInventoryLine(
+        startAt + i,
+        { ...r, snippet: r.content },
+        PERSONAL_SCOPE.key,
+      ),
+    )
+    .join("\n");
+}
+
+/** Plain-text rendering: diffable in any terminal or CI log. */
+export function renderInventoryText(data: InventoryData): string {
+  const out: string[] = [];
+  out.push(`What OpenMemex remembers — ${data.generatedAt}`);
+  out.push(
+    `${data.total} memories (${data.scopes.reduce((n, s) => n + (s.scopeKey === PERSONAL_SCOPE.key ? s.rows.length : 0), 0)} personal, ${data.outbox.length} in the outbox).`,
+  );
+  // D70: one running counter across every section, so a number quoted back
+  // ("delete #3") names exactly one entry in this report.
+  let seq = 0;
+  for (const s of data.scopes) {
+    const title =
+      s.scopeKey === PERSONAL_SCOPE.key
+        ? "About you — personal (never leaves this machine)"
+        : `Project: ${s.projectName}`;
+    out.push("", `## ${title} (${s.rows.length})`, entriesText(s.rows, seq));
+    seq += s.rows.length;
+  }
+  if (data.outbox.length > 0) {
+    out.push(
+      "",
+      `## Not in the repo yet — outbox drafts (${data.outbox.length})`,
+      "These exist only on this machine. They reach the repo through review (submit → promote), never automatically.",
+      entriesText(data.outbox, seq),
+    );
+    seq += data.outbox.length;
+  }
+  const hidden = hiddenLine(data);
+  if (hidden) out.push("", hidden);
+  out.push(
+    "",
+    "Read-only report. To remove a memory, tell your agent to forget it — it will read the entry back before deleting (deletion is permanent).",
+  );
+  return out.join("\n") + "\n";
+}
+
+/**
+ * JSON rendering: same data, for agents. Mirrors the export field names.
+ *
+ * D70: format `/2` drops the absolute `file` path. This artifact is meant
+ * to be handed to an agent — i.e. pasted into a cloud conversation — and it
+ * carried the user's home directory and name with it. The id locates the
+ * file (`open-memex where` prints the data root).
+ */
+export function renderInventoryJson(data: InventoryData): string {
+  const entry = (r: InventoryRow) => ({
+    id: r.id,
+    scope: r.scope_key,
+    project: r.project_name,
+    type: r.type,
+    status: r.status,
+    review_state: r.review_state,
+    source: r.source,
+    created_at: new Date(r.created_at).toISOString(),
+    updated_at: new Date(r.updated_at).toISOString(),
+    content: r.content,
+  });
+  return (
+    JSON.stringify(
+      {
+        format: "open-memex-inventory/2",
+        generated_at: data.generatedAt,
+        total: data.total,
+        scopes: data.scopes.map((s) => ({
+          scope: s.scopeKey,
+          project: s.projectName,
+          memories: s.rows.map(entry),
+        })),
+        outbox: data.outbox.map(entry),
+        hidden: data.hidden,
+      },
+      null,
+      2,
+    ) + "\n"
+  );
+}

package/src/mcp.ts

@@ -116,6 +116,15 @@ memory_resolve, memory_pr_status — always call them by these full names.
   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.
+- When the user asks what you remember (about them, or in this project),
+  call memory_list with scope=both and present it conversationally — turn
+  the structured fields into plain words (source=user → "you told me
+  this"; source=inference → "I inferred this, check me"), and don't read
+  raw ids aloud. If they ask to remove or hide an entry, re-run
+  memory_list first (numbers from an older listing may have shifted),
+  read the candidate back in full, and get a confirmation before calling
+  memory_forget: deletion is permanent. If they hesitate, offer soft=true
+  (hide it instead — still one-way, but the file survives).
 - Memories default to this project's scope; use the personal scope for facts
   about the user that hold across all projects. When a saved fact becomes
   outdated, call memory_supersede (find the old memory's id with memory_search

package/src/opencode-v2.ts

@@ -3,6 +3,7 @@ import {
   PLUGIN_ID,
   bootstrapPlugin,
   captureFromText,
+  captureHandoff,
   injectOnce,
   type PluginState,
 } from "./plugin-core.ts";
@@ -101,14 +102,18 @@ export const v2Plugin = {
 
     registrations.push(
       await ctx.session.hook("prompt", (ev: V2PromptEvent) => {
-        captureFromText(ev.prompt?.text ?? "", state);
+        captureFromText(ev.prompt?.text ?? "", state, ev.sessionID ?? "");
       }),
     );
     registrations.push(
       await ctx.session.hook("context", (ev: V2ContextEvent) => {
-        injectOnce(ev.sessionID ?? "", state, (block) => {
+        const sessionID = ev.sessionID ?? "";
+        injectOnce(sessionID, state, (block) => {
           ev.system.push({ type: "text", text: block });
         });
+        // D73: tell the agent what the keyword hook already stored this turn.
+        const handoff = captureHandoff(sessionID, state);
+        if (handoff) ev.system.push({ type: "text", text: handoff });
       }),
     );
 

package/src/paths.ts

@@ -96,6 +96,25 @@ export function inRepoMemoriesDir(root: string, memoryDir: string): string {
 }
 
 /** Same as `inRepoMemoriesDir` but never creates the directory. */
+/**
+ * True when a memory file lives inside the user's git working tree (the
+ * in-repo `.ai/open-memex/` copy) rather than in the local data root.
+ *
+ * D70: both destructive/corrective surfaces need this — the hard delete
+ * already said "commit the deletion so the team sees it" (D64), and the
+ * soft hide has to say the same, because a retraction that never gets
+ * committed leaves the memory standing on every teammate's clone.
+ */
+export function isInRepoMemoryFile(filePath: string): boolean {
+  if (!filePath) return false;
+  const normalized = filePath.replace(/\\/g, "/");
+  return normalized.includes("/.ai/open-memex/") && !normalized.startsWith(root());
+}
+
+function root(): string {
+  return paths().root.replace(/\\/g, "/");
+}
+
 export function inRepoMemoriesDirPath(root: string, memoryDir: string): string {
   return path.join(root, memoryDir);
 }

package/src/plugin-core.ts

@@ -12,6 +12,12 @@ import {
 } from "./store/markdown.ts";
 import { buildContextBlock } from "./retrieve/inject.ts";
 import { detectKeywords } from "./capture/keywords.ts";
+import {
+  TURN_ECHO_WINDOW_MS,
+  formatHandoffBlock,
+  freshCaptures,
+  type CaptureRecord,
+} from "./capture/handoff.ts";
 import { findDuplicates } from "./store/lifecycle.ts";
 import { redact } from "./redact.ts";
 
@@ -28,6 +34,12 @@ export interface PluginState {
   scope: Scope;
   /** Sessions that already received the one-time context injection. */
   injectedSessions: Set<string>;
+  /**
+   * D73: what the keyword hook stored this session, so the agent can be told
+   * before it re-saves the same statement. In memory only, like
+   * `injectedSessions` — never persisted, pruned by the turn window.
+   */
+  captures: Map<string, CaptureRecord[]>;
 }
 
 /**
@@ -60,15 +72,21 @@ export function bootstrapPlugin(root: string): PluginState {
   } catch (err) {
     console.error("[open-memex] init failed:", err);
   }
-  return { cfg, scope, injectedSessions: new Set<string>() };
+  return { cfg, scope, injectedSessions: new Set<string>(), captures: new Map() };
 }
 
 /**
  * Keyword capture (§ capture): scan one user message for "remember …"
  * triggers and save each hit. Shared by the v1 `chat.message` hook and
- * the v2 session `prompt` hook — both hand us the message text.
+ * the v2 session `prompt` hook — both hand us the message text and the
+ * session id. The session id is what makes the D73 hand-off possible: without
+ * it the agent never learns the sentence is already stored.
  */
-export function captureFromText(text: string, state: PluginState): void {
+export function captureFromText(
+  text: string,
+  state: PluginState,
+  sessionID?: string,
+): void {
   const { cfg, scope } = state;
   if (!cfg.keywordCaptureEnabled || !text) return;
   const hits = detectKeywords(text, cfg);
@@ -119,12 +137,53 @@ export function captureFromText(text: string, state: PluginState): void {
       // offers no toast channel, so the plugin log is the feedback surface.
       const preview = content.length > 60 ? content.slice(0, 60) + "…" : content;
       console.log(`[open-memex] remembered → ${target.kind} scope: "${preview}"`);
+      // D73 hand-off: the agent gets told about this capture in the turn's
+      // system context, so it does not save the same statement again.
+      recordCapture(state, sessionID, { id: fm.id, scopeKey: target.key, content, at: now });
     } catch (err) {
       console.error("[open-memex] keyword capture failed:", err);
     }
   }
 }
 
+/** Note one hook capture against its session (D73). No-op without a session. */
+function recordCapture(
+  state: PluginState,
+  sessionID: string | undefined,
+  record: CaptureRecord,
+): void {
+  if (!sessionID) return;
+  const list = state.captures.get(sessionID) ?? [];
+  list.push(record);
+  state.captures.set(sessionID, list);
+}
+
+/**
+ * D73 hand-off note (a): what the keyword hook already stored for this
+ * session, delivered once per capture into the turn's system context. The
+ * agent cannot avoid re-saving a statement it cannot see is stored, so the
+ * store tells it. Returns "" when there is nothing new to hand off; stale
+ * records are pruned (in-memory only, like `injectedSessions`).
+ *
+ * Both host adapters push this from their system/context hook — the one that
+ * runs before the model request, i.e. after `chat.message` / `prompt`.
+ */
+export function captureHandoff(sessionID: string, state: PluginState): string {
+  if (!sessionID) return "";
+  const list = state.captures.get(sessionID);
+  if (!list || list.length === 0) return "";
+  const now = Date.now();
+  const fresh = freshCaptures(list, now);
+  if (fresh.length !== list.length) {
+    if (fresh.length === 0) state.captures.delete(sessionID);
+    else state.captures.set(sessionID, fresh);
+  }
+  const pending = fresh.filter((r) => !r.delivered);
+  if (pending.length === 0) return "";
+  for (const r of pending) r.delivered = true;
+  return formatHandoffBlock(pending);
+}
+
 /**
  * First-turn context injection: exactly once per session. The host adapter
  * supplies `push` (v1: output.system.push; v2: the session context hook's