dsh-loci 2.0.3 → 2.1.0

package/CHANGELOG.md

@@ -4,6 +4,51 @@ All notable changes to this project are documented here. The format follows
 [Keep a Changelog](https://keepachangelog.com/en/1.1.0/); the project follows
 [Semantic Versioning](https://semver.org/spec/v2.0.0.html) from 1.0.0.
 
+## [2.1.0] — 2026-11-15
+
+Two findings from an independent blind review, where seven reviewers compared this
+plugin against the rest of the field. Two of them caught the same false claim; the
+other had the sharpest product objection, and both are addressed here.
+
+### Fixed
+
+- **The "no network" claim was false.** `README` and the threat-model row both said
+  "no network unless `vectorMode` is http", while `updateCheck` defaulted to `true`
+  and the panel's update route fetched the registry. Rather than reword the claim,
+  the default is now **false**, so the sentence is true: turning the check on is one
+  click, and a disabled check reads "Update check off" instead of looking like a
+  dead button. `test/unit/network-claims.test.mjs` also greps the source, so a new
+  `fetch` outside the two opt-in modules fails CI.
+
+### Added
+
+- **A pending-review line in the injected section.** Verified-only injection has an
+  invisible failure mode: a fact written at midnight is absent at 9 a.m., and "never
+  saved" looks exactly like "saved but gated". When — and only when — something is
+  waiting, the footer now carries one line with the count and says those items are
+  deliberately absent. An empty queue still costs exactly 0 bytes, and the count is
+  part of the render cache key so a new candidate appears on the next request.
+
+- **Per-entry usage counters (schema v2).** `memory_usage` records `inject_count`,
+  `read_count`, `last_injected_at`, `last_read_at` per memory, so "which line spends
+  prompt bytes and is never opened" becomes answerable. The panel's Stats tab lists
+  that dead weight; `loci_get` records a read.
+
+### Migration
+
+Schema v1 → v2 adds one table. It runs through the existing migration runner: a
+`VACUUM INTO` snapshot first, then one immediate transaction, then a row-count guard
+over every pre-existing table. Rollback stays "restore the snapshot". This is the
+first real migration this project has shipped, so `test/integration/migrate.test.mjs`
+now exercises both the rehearsal step and the shipped one.
+
+### Note
+
+The same review found two things worth stating openly rather than burying: the
+plugin is **not yet in the DSH plugin catalog** (the catalog snapshot predates its
+publication), and it has been verified on `0.2.2-rc.1` only, while `engines.dsh`
+admits the whole `0.2.2-rc.1 <0.3.0-0` range. Both are tracked as open work.
+
 ## [2.0.3] — 2026-11-14
 
 ### Fixed

package/README.md

@@ -119,7 +119,7 @@ The settings page writes the fields marked *live* without a restart.
 
 - No model call in any automatic path in v1.0 — capture and summaries are
   deterministic, so the cost is visible and zero.
-- No cloud, no telemetry, no network unless you configure `vectorMode: 'http'`.
+- No cloud, no telemetry. Two optional network paths, both off by default: the update check (`updateCheck`) and the HTTP embedding channel (`vectorMode: 'http'`).
 - No cross-project leakage: reads use an explicit scope-key set, never a wildcard.
 - No physical deletion by default; `purge` needs a config switch, a confirmation,
   and leaves an audit line.

package/README.zh.md

@@ -88,7 +88,7 @@ node "$HOME/.dsh/profiles/<profile>/node_modules/dsh-loci/scripts/cli.mjs" docto
 ## 它明确不做
 
 - v1.0 的自动路径里没有模型调用 —— 捕获与摘要是确定性的，成本可见且为零。
-- 无云、无遥测；除非你配置 `vectorMode: 'http'`，否则不出网。
+- 无云、无遥测。只有两条可选出网路径，**都默认关闭**：更新检查（`updateCheck`）与 HTTP 向量通道（`vectorMode: 'http'`）。
 - 不跨项目串味：读取用显式 scope-key 集合，从不通配。
 - 默认不物理删除；`purge` 需要配置开关 + 确认 + 留审计。
 

package/client.js

@@ -43,6 +43,7 @@ window.__ModuleLoader__.load({
       'card.check': 'Check for updates',
       'card.upToDate': 'Up to date',
       'card.updateTo': 'Update available',
+      'card.checkOff': 'Update check off',
       'card.checking': 'Checking…',
       'card.unknown': 'Version check unavailable',
       'card.unpublished': 'Not on npm yet',
@@ -138,6 +139,9 @@ window.__ModuleLoader__.load({
       'panel.verifyAll': 'Verify all {n}',
       'panel.actionFailed': 'Action failed',
       'panel.injections': 'Recent injections',
+      'panel.deadWeight': 'Injected but never opened',
+      'panel.injected': 'injected',
+      'panel.opened': 'opened',
       'panel.store': 'Store',
       'panel.confirmDelete': 'Soft-delete this entry?',
       'panel.error': 'Request failed',
@@ -160,6 +164,7 @@ window.__ModuleLoader__.load({
       'card.check': '检查更新',
       'card.upToDate': '已是最新',
       'card.updateTo': '有新版本',
+      'card.checkOff': '更新检查已关闭',
       'card.checking': '检查中…',
       'card.unknown': '无法检查版本',
       'card.unpublished': '尚未发布',
@@ -255,6 +260,9 @@ window.__ModuleLoader__.load({
       'panel.verifyAll': '全部核实（{n}）',
       'panel.actionFailed': '操作失败',
       'panel.injections': '最近注入',
+      'panel.deadWeight': '注入了但从未被打开',
+      'panel.injected': '次注入',
+      'panel.opened': '次打开',
       'panel.store': '存储',
       'panel.confirmDelete': '软删除这条记忆？',
       'panel.error': '请求失败',
@@ -483,13 +491,18 @@ window.__ModuleLoader__.load({
       const version = typeof update?.version === 'string' ? update.version.replace(/^v/i, '') : null;
       const hasUpdate = update?.updateAvailable === true;
       const unknown = update !== undefined && update.status === 'unavailable';
+      // The check is opt-in, so "off" is a normal state, not a failure: it must read
+      // as switched off rather than as a button that does nothing.
+      const checkDisabled = update?.checkEnabled === false;
       const text = hasUpdate
         ? `${t('card.updateTo')}${update.latestVersion ? ` · v${update.latestVersion}` : ''}`
         : unknown
           ? t('card.unknown')
-          : update?.status === 'ok'
-            ? t('card.upToDate')
-            : t('card.check');
+          : checkDisabled
+            ? t('card.checkOff')
+            : update?.status === 'ok'
+              ? t('card.upToDate')
+              : t('card.check');
       return h(
         'span',
         { className: 'loci-card-line', style: { gap: '5px' } },
@@ -500,7 +513,7 @@ window.__ModuleLoader__.load({
             type: 'button',
             className: 'loci-btn is-quiet',
             title: text,
-            disabled: checking === true,
+            disabled: checking === true || checkDisabled,
             onClick: (event) => {
               event.stopPropagation();
               onCheck?.();
@@ -1077,6 +1090,31 @@ window.__ModuleLoader__.load({
                 ),
               ),
               h('div', { className: 'loci-meta', style: { marginTop: '14px' } }, `${t('panel.version')} v${data.pluginVersion ?? '—'}`),
+              // Which lines spend prompt bytes and are never opened. Sorted host-side,
+              // so the first row is the most expensive and least used.
+              (data.usage ?? []).some((row) => row.injections > 0 && row.reads === 0)
+                ? h(
+                    'div',
+                    null,
+                    h('div', { className: 'loci-section' }, t('panel.deadWeight')),
+                    (data.usage ?? [])
+                      .filter((row) => row.injections > 0 && row.reads === 0)
+                      .slice(0, 8)
+                      .map((row) =>
+                        h(
+                          'div',
+                          { key: row.id, className: 'loci-row' },
+                          h('span', { className: 'loci-id' }, row.id),
+                          h(
+                            'div',
+                            { className: 'loci-main' },
+                            h('div', { className: 'loci-name' }, row.title),
+                            h('div', { className: 'loci-meta' }, `${row.injections}×${t('panel.injected')} · 0×${t('panel.opened')}`),
+                          ),
+                        ),
+                      ),
+                  )
+                : null,
             )
           : null,
       );

package/docs/SECURITY.md

@@ -17,7 +17,7 @@ file sandbox, approval policy) are the Harness's and are assumed to work.
 | T6 | The panel API is reachable from another origin | Local admin surface exposed to a web page | exact `connection.fetch` route (owner Peer, same-origin fence), JSON-only writes, 256 KB body cap, no CORS headers |
 | T7 | Data written outside the Harness home | Un-backed-up, un-scoped secrets | single root `$DSH_HOME/memory/loci/`, every path asserted with `assertInside` |
 | T8 | A write blocks the agent loop | Turn hangs | WAL + bounded busy timeout + six retries; transactions are single-digit milliseconds; capture is debounced and never awaited by the turn |
-| T9 | Memory exfiltration over the network | Privacy breach | no network code unless `vectorMode: 'http'`; the endpoint is user-configured; a failure parks the channel |
+| T9 | Memory exfiltration over the network | Privacy breach | two opt-in paths only, both off by default: the update check (`updateCheck`, one `GET` of the package metadata, carries nothing about memory) and the HTTP embedding channel (`vectorMode: 'http'`, endpoint user-configured, failure parks the channel). No other request exists — `docs/PRIVACY.md` §3 lists both |
 | T10 | Unbounded growth | Token cost creep | hard byte budget, pinned/rule caps, soft per-scope cap option |
 
 ## 2. The trust gate, precisely

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-loci",
-  "version": "2.0.3",
+  "version": "2.1.0",
   "description": "Layered long-term memory for DeepSeek Harness: the prompt sees only a stable index, full text is one lookup away. Bi-temporal facts, strict scope isolation, verified-only injection.",
   "type": "module",
   "license": "MIT",

package/src/host/api/routes.js

@@ -101,6 +101,9 @@ export function registerApiRoutes(ctx, deps) {
       pluginVersion: deps.version ?? '0.0.0',
       injections: store.recentInjections(50),
       audit: store.auditTail(50),
+      // Which entries spend prompt bytes and are never opened. Aggregate request
+      // stats cannot answer this, which is why schema v2 added per-entry counters.
+      usage: store.usageReport({ scopeKeys, limit: 50 }),
     });
   });
 
@@ -347,6 +350,9 @@ function installedOnly(version) {
     updateAvailable: false,
     checkedAt: null,
     status: 'idle',
+    // The card shows a "check" button; without this flag a disabled check looks
+    // broken ("nothing happens") instead of switched off.
+    checkEnabled: false,
   };
 }
 

package/src/host/config.js

@@ -100,8 +100,15 @@ export const DEFAULTS = Object.freeze({
   workingTtlDays: 7,
   /** Allow `op:'purge'` to physically delete revisions. */
   allowHardDelete: false,
-  /** Ask the registry for a newer version when the card is opened. */
-  updateCheck: true,
+  /**
+   * Ask the registry for a newer version when the card is opened.
+   *
+   * Off by default: the whole product claims "no network unless you opt in", and a
+   * default-on version check made that sentence false. A reviewer caught it, and the
+   * claim is worth more than the convenience — turning this on is one click in
+   * Settings, and the request carries nothing about memory.
+   */
+  updateCheck: false,
   /** Registry used by that check; point it at a mirror when npmjs.org is slow. */
   updateRegistry: 'https://registry.npmjs.org',
   /** 'error' | 'info' | 'debug'. */

package/src/host/index.js

@@ -22,7 +22,7 @@ import { registerCommands } from './commands.js';
 import { runDoctor } from './doctor.js';
 
 /** Version stamped into the database and diagnostics. */
-export const VERSION = '2.0.3';
+export const VERSION = '2.1.0';
 
 /** Optional collaborators; without them the plugin still serves tools. */
 export const inject = ['systemPrompt', 'tools'];

package/src/host/inject/index-section.js

@@ -24,8 +24,14 @@ export const INDEX_SECTION_NAME = 'loci:index';
 /** Placement: after MCP servers (3100), before the tools SDK section (5000). */
 export const INDEX_SECTION_ORDER = 4000;
 
-/** Bytes reserved for the closing footer before index lines are admitted. */
-const FOOTER_RESERVE = 240;
+/**
+ * Bytes reserved for the closing footer before index lines are admitted.
+ *
+ * The footer is not fixed: "… +N more" and the pending-review notice grow with the
+ * store, and the shrink loop below would otherwise admit a line and immediately
+ * take it back on every render. 400 bytes covers the worst realistic footer.
+ */
+const FOOTER_RESERVE = 400;
 
 /** Days in milliseconds. */
 export const DAY = 86_400_000;
@@ -64,14 +70,17 @@ export function renderIndexBody(options) {
   const rulesMaxBytes = Math.max(0, Math.min(maxBytes, cfg('rulesMaxBytes')));
   const maxEntries = Math.max(1, Math.min(2000, cfg('indexMaxEntries')));
   const lineChars = Math.max(40, Math.min(400, cfg('indexLineMaxChars')));
-  const empty = { text: '', bytes: 0, listed: 0, total: 0, hidden: 0 };
+  const empty = { text: '', bytes: 0, listed: 0, total: 0, hidden: 0, ids: [] };
 
   const rules = store.ruleEntries({ scopeKeys, now, limit: 24 });
   const entries = store.indexEntries({ scopeKeys, now, limit: maxEntries + 1 });
   const truncatedByCount = entries.length > maxEntries;
   const visible = truncatedByCount ? entries.slice(0, maxEntries) : entries;
   const total = truncatedByCount ? store.countIndex(scopeKeys, now) : visible.length;
-  if (rules.length === 0 && visible.length === 0) return empty;
+  // Counted always, rendered only when it is not zero: an empty queue must cost
+  // exactly zero bytes, or the "0 bytes when empty" promise is a lie.
+  const pending = store.countPending(scopeKeys);
+  if (rules.length === 0 && visible.length === 0 && pending === 0) return empty;
 
   const headLines = [FENCE_OPEN];
   const ruleLines = [];
@@ -95,19 +104,30 @@ export function renderIndexBody(options) {
   // A scope label comes from a directory name, which a user can make contain a
   // newline. Flattening it here is what stops a crafted folder name from writing
   // extra lines into the fence.
-  const indexHeader = `Index — ${renderSafe(indexTitle(scopeLabel, 120))}`;
+  // Only when there is an index to label. A store holding nothing but pending
+  // candidates used to render an empty "Index —" heading, which reads as "memory is
+  // empty" right next to the line saying something is waiting.
+  const indexHeader = visible.length > 0 ? `Index — ${renderSafe(indexTitle(scopeLabel, 120))}` : '';
   const entryLine = (entry) => `- ${entry.id} · ${entry.kind} · ${formatDate(entry.validFrom)} · ${renderSafe(indexTitle(entry.title, lineChars))}`;
 
   const footerFor = (listed) => {
     const hidden = Math.max(0, total - listed);
     const parts = [];
     if (hidden > 0) parts.push(`… +${hidden} more (loci_search finds the rest; this section shows ${listed} of ${total})`);
+    // The one line that makes verified-only injection legible from inside the
+    // conversation. Without it "you never saved that" and "I saved it but it is
+    // waiting for you" are indistinguishable to the model and to the user.
+    if (pending > 0) {
+      parts.push(
+        `${pending} item(s) await review and are deliberately absent here — a person approves them in Memory → Review (/loci review); say so if the user expects them.`,
+      );
+    }
     parts.push(`as of ${formatDate(now)} · ${FULL_TEXT_HINT}`);
     parts.push(FENCE_CLOSE);
     return parts.join('\n');
   };
 
-  const baseBytes = bytes([...headLines, ...ruleLines, indexHeader].join('\n'));
+  const baseBytes = bytes([...headLines, ...ruleLines, ...(indexHeader === '' ? [] : [indexHeader])].join('\n'));
 
   // Admit entries while the reserved footer still fits.
   let admitted = 0;
@@ -123,7 +143,7 @@ export function renderIndexBody(options) {
   let listed = admitted;
   let text = '';
   for (let n = admitted; ; n -= 1) {
-    const lines = [...headLines, ...ruleLines, indexHeader, ...visible.slice(0, n).map(entryLine), footerFor(n)];
+    const lines = [...headLines, ...ruleLines, ...(indexHeader === '' ? [] : [indexHeader]), ...visible.slice(0, n).map(entryLine), footerFor(n)];
     text = lines.join('\n');
     if (bytes(text) <= maxBytes || n === 0) {
       listed = n;
@@ -135,12 +155,23 @@ export function renderIndexBody(options) {
   // lines from the tail rather than ever exceeding the budget.
   while (bytes(text) > maxBytes && ruleLines.length > 0) {
     ruleLines.pop();
-    const lines = [...headLines, ...ruleLines, indexHeader, footerFor(0)];
+    const lines = [...headLines, ...ruleLines, ...(indexHeader === '' ? [] : [indexHeader]), footerFor(0)];
     text = lines.join('\n');
     listed = 0;
   }
 
-  return { text, bytes: bytes(text), listed, total, hidden: Math.max(0, total - listed) };
+  return {
+    text,
+    bytes: bytes(text),
+    listed,
+    total,
+    hidden: Math.max(0, total - listed),
+    // Rule lines are injected too, and they are the ones a person most wants usage
+    // data for, so both blocks report their ids.
+    // Rule lines are injected too, and they are the ones a person most wants usage
+    // data for, so both blocks report their ids. `ruleEntries` is already verified-only.
+    ids: [...rules.slice(0, 12).map((rule) => rule.id), ...visible.slice(0, listed).map((entry) => entry.id)],
+  };
 }
 
 /**
@@ -168,6 +199,7 @@ export function createIndexSection(options) {
         bytes: rendered.bytes,
         listed: rendered.listed,
         hidden: rendered.hidden,
+        ids: rendered.ids ?? [],
       });
     } catch (error) {
       log?.warn?.(`loci: cannot record injection: ${String(error?.message ?? error)}`);
@@ -203,7 +235,11 @@ export function createIndexSection(options) {
     ].join(':');
     const now = Date.now();
     const day = new Date(now).toISOString().slice(0, 10);
-    const key = `${context.scopeKeys.join(',')}|${store.indexRev()}|${configKey}|${day}`;
+    // The pending count is part of the key: if it is not, a newly queued candidate
+    // stays invisible until something else invalidates the cache, which defeats
+    // the whole point of the notice.
+    const pending = store.countPending(context.scopeKeys);
+    const key = `${context.scopeKeys.join(',')}|${store.indexRev()}|${configKey}|${day}|${pending}`;
     const cached = cache.get(key);
     if (cached !== undefined) {
       record(context, cached);

package/src/host/store/migrate.js

@@ -12,6 +12,7 @@
 import { copyFileSync, existsSync, readdirSync, rmSync, statSync } from 'node:fs';
 import { join } from 'node:path';
 import { backupTo, tableCounts, withTransaction } from './db.js';
+import { MEMORY_USAGE_DDL } from './schema.js';
 import {
   META_KEYS,
   SCHEMA_VERSION,
@@ -28,7 +29,18 @@ import {
  * drives it with a rehearsal step so the path is never untested.
  * @type {Array<{from:number,to:number,up:(db:import('node:sqlite').DatabaseSync)=>void,verify?:(db:import('node:sqlite').DatabaseSync)=>void}>}
  */
-export const SHIPPED_MIGRATIONS = [];
+export const SHIPPED_MIGRATIONS = [
+  {
+    from: 1,
+    to: 2,
+    // v2 adds per-entry usage counters. The table is new and empty, so the
+    // migration cannot lose a row; the row-count guard in \`migrate()\` still runs
+    // over every existing table and would catch a mistake here.
+    up(db) {
+      db.exec(MEMORY_USAGE_DDL);
+    },
+  },
+];
 
 /**
  * Whether the file already holds the Loci core table.

package/src/host/store/schema.js

@@ -8,7 +8,27 @@
  */
 
 /** Schema version this build writes and expects. */
-export const SCHEMA_VERSION = 1;
+export const SCHEMA_VERSION = 2;
+
+/**
+ * DDL for the v2 per-entry usage table.
+ *
+ * Kept as its own constant because two paths must agree on it: a fresh database
+ * (via {@link SCHEMA_SQL}) and an existing one (via the v1→v2 migration). A table
+ * that only exists on new installs is the classic way a feature "works on my
+ * machine".
+ */
+export const MEMORY_USAGE_DDL = `
+CREATE TABLE IF NOT EXISTS memory_usage (
+  id               TEXT PRIMARY KEY,
+  inject_count     INTEGER NOT NULL DEFAULT 0,
+  read_count       INTEGER NOT NULL DEFAULT 0,
+  last_injected_at INTEGER,
+  last_read_at     INTEGER
+);
+CREATE INDEX IF NOT EXISTS ix_memory_usage_inject ON memory_usage (inject_count DESC);
+CREATE INDEX IF NOT EXISTS ix_memory_usage_read ON memory_usage (read_count DESC);
+`;
 
 /** DDL for a fresh database. Order matters: FTS and the head table follow `memory`. */
 export const SCHEMA_SQL = `
@@ -113,6 +133,9 @@ CREATE TABLE IF NOT EXISTS token_stat (
   df    INTEGER NOT NULL DEFAULT 0
 );
 
+${MEMORY_USAGE_DDL}
+
+
 CREATE TABLE IF NOT EXISTS request_stat (
   id             INTEGER PRIMARY KEY AUTOINCREMENT,
   ts             INTEGER NOT NULL,

package/src/host/store/store.js

@@ -829,6 +829,32 @@ export class Store {
     );
   }
 
+  /**
+   * How many entries in these scopes are waiting for a human.
+   *
+   * This is what the injected section reports. Verified-only injection has a
+   * failure mode the user cannot see: a fact the model wrote at midnight is simply
+   * absent at 9 a.m., and "never saved" looks exactly like "saved but gated". One
+   * number in the prompt is enough to tell those apart, and it costs nothing when
+   * the queue is empty.
+   *
+   * @param scopeKeys - explicit scope keys (never a wildcard).
+   * @returns the count of candidate and disputed entries.
+   */
+  countPending(scopeKeys) {
+    if (scopeKeys.length === 0) return 0;
+    const marks = scopeKeys.map(() => '?').join(', ');
+    return Number(
+      this.db
+        .prepare(
+          `SELECT COUNT(*) AS n FROM memory m
+           WHERE m.status IN ('candidate', 'disputed') AND m.deleted_at IS NULL
+             AND m.scope_key IN (${marks})`,
+        )
+        .get(...scopeKeys)?.n ?? 0,
+    );
+  }
+
   /**
    * Verified rules for the rules block, newest last.
    * @param options - `scopeKeys`, `now`, `limit`.
@@ -1062,6 +1088,20 @@ export class Store {
         'INSERT INTO request_stat (ts, session_id, scope_key, section_bytes, entries_listed, entries_hidden) VALUES (?, ?, ?, ?, ?, ?)',
       )
       .run(this.now(), row.sessionId ?? null, row.scopeKey ?? null, row.bytes, row.listed, row.hidden);
+    // Per-entry counters, so "which line earns its bytes" stays answerable after the
+    // aggregate rows rotate out. A listed entry never fetched by id is the dead
+    // weight this product exists to find.
+    if (Array.isArray(row.ids) && row.ids.length > 0) {
+      const bump = this.db.prepare(
+        `INSERT INTO memory_usage (id, inject_count, read_count, last_injected_at)
+         VALUES (?, 1, 0, ?)
+         ON CONFLICT(id) DO UPDATE SET inject_count = inject_count + 1, last_injected_at = excluded.last_injected_at`,
+      );
+      const now = this.now();
+      withTransaction(this.db, () => {
+        for (const id of row.ids) bump.run(id, now);
+      });
+    }
     this.db.prepare('DELETE FROM request_stat WHERE ts < ?').run(this.now() - 90 * 86_400_000);
     this.audit.append('inject', {
       sessionId: row.sessionId ?? null,
@@ -1072,6 +1112,64 @@ export class Store {
     });
   }
 
+  /**
+   * Record that one entry was fetched by id.
+   *
+   * Injection counts alone cannot tell "the index line was enough" from "the model
+   * opened it": only this counter can.
+   * @param id - memory id.
+   */
+  recordRead(id) {
+    if (typeof id !== 'string' || id.length === 0) return;
+    try {
+      this.db
+        .prepare(
+          `INSERT INTO memory_usage (id, inject_count, read_count, last_read_at)
+           VALUES (?, 0, 1, ?)
+           ON CONFLICT(id) DO UPDATE SET read_count = read_count + 1, last_read_at = excluded.last_read_at`,
+        )
+        .run(id, this.now());
+    } catch {
+      // A counter must never fail a read.
+    }
+  }
+
+  /**
+   * Which entries spend prompt budget without being opened.
+   *
+   * @param options - `scopeKeys`, `limit`.
+   * @returns rows sorted by injections desc, reads asc.
+   */
+  usageReport(options = {}) {
+    const keys = options.scopeKeys ?? [];
+    const limit = Math.max(1, Math.min(200, options.limit ?? 20));
+    const marks = keys.length > 0 ? ` AND m.scope_key IN (${keys.map(() => '?').join(', ')})` : '';
+    const rows = this.db
+      .prepare(
+        `SELECT m.id, m.title, m.kind, h.status,
+                COALESCE(u.inject_count, 0) AS injections,
+                COALESCE(u.read_count, 0) AS reads,
+                u.last_injected_at, u.last_read_at
+         FROM memory m
+         JOIN memory_head h ON h.ord = m.ord
+         LEFT JOIN memory_usage u ON u.id = m.id
+         WHERE m.deleted_at IS NULL${marks}
+         ORDER BY COALESCE(u.inject_count, 0) DESC, COALESCE(u.read_count, 0) ASC
+         LIMIT ?`,
+      )
+      .all(...keys, limit);
+    return rows.map((row) => ({
+      id: row.id,
+      title: row.title,
+      kind: row.kind,
+      status: row.status,
+      injections: Number(row.injections),
+      reads: Number(row.reads),
+      lastInjectedAt: row.last_injected_at === null ? null : Number(row.last_injected_at),
+      lastReadAt: row.last_read_at === null ? null : Number(row.last_read_at),
+    }));
+  }
+
   /**
    * Record one recall.
    * @param row - `query` length, counts, timing, channels.

package/src/host/tools/tools.js

@@ -333,7 +333,17 @@ export function createTools(deps) {
       const id = str(args, 'id', { required: true, maxChars: 64 });
       const revision = int(args, 'revision', { min: 1 });
       const includeHistory = bool(args, 'includeHistory', true);
-      return store.get(id, { revision, includeHistory });
+      const result = store.get(id, { revision, includeHistory });
+      // A read counter is what separates "the index line was enough" from "the model
+      // had to open it". It must never fail the read itself.
+      if (result?.entry !== undefined) {
+        try {
+          store.recordRead(result.entry.id);
+        } catch {
+          /* counting is best effort */
+        }
+      }
+      return result;
     },
   };
 

package/src/mcp/store-facade.js

@@ -36,7 +36,7 @@ export function openFacadeStore(options = {}) {
     memoryRoot: root,
     paths,
     config,
-    pluginVersion: '2.0.3',
+    pluginVersion: '2.1.0',
     readOnly: options.readOnly === true,
   });
   return { store, paths };