claude-mem-lite 6.26.1 → 6.27.0

package/.claude-plugin/marketplace.json

@@ -9,7 +9,7 @@
   "plugins": [
     {
       "name": "claude-mem-lite",
-      "version": "6.26.1",
+      "version": "6.27.0",
       "source": "./",
       "homepage": "https://github.com/sdsrss/claude-mem-lite",
       "description": "Persistent long-term memory for Claude Code via MCP — captures coding decisions, bugfixes, and context across sessions. FTS5 BM25 keyword search with episode batching. Single SQLite DB, no external services. A lighter, lower-cost alternative to claude-mem (episode batching + a smaller model; cost savings are an internal estimate, not a measured benchmark)."

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-mem-lite",
-  "version": "6.26.1",
+  "version": "6.27.0",
   "description": "Persistent long-term memory for Claude Code via MCP — captures coding decisions, bugfixes, and context across sessions. FTS5 BM25 keyword search with episode batching. Single SQLite DB, no external services. A lighter, lower-cost alternative to claude-mem (episode batching + a smaller model; cost savings are an internal estimate, not a measured benchmark).",
   "author": {
     "name": "sdsrss"

package/README.md

@@ -1141,6 +1141,8 @@ claude-mem-lite.
 | `CLAUDE_MEM_DEBUG` | Enable debug logging (`1` to enable). | _(disabled)_ |
 | `MEM_QUIET_HOOKS` | Low-noise hooks. `1` drops the `File Lessons` / `Key Context` sections from SessionStart injection, the lesson suffix from `[mem] Related memories`, and the `WHEN TO USE` / `Decision rules` blocks from MCP server instructions. IDs and the `Recent` table still surface so `mem_get(ids=[…])` remains reachable. Intended for users running the invited-memory adopt path or who otherwise want minimal auto-injection. **Since v2.82.0 this env no longer gates auto-adopt — use `MEM_NO_AUTO_ADOPT=1` for that.** | _(disabled)_ |
 | `CLAUDE_MEM_SESSION_EVENTS` | `1`/`on` restores the SessionStart `### Key Events` section (recent high-importance rows from the `events` table). **Off by default since v6.13.0**: an audit of 30 events read 2 accurate and 16 wrong. The UserPromptSubmit events block and PreToolUse recall are query-matched and stay on; `mem_search` still reaches every event. | _(off)_ |
+| `CLAUDE_MEM_STARTUP_RECENT_ROWS` | Rows in the SessionStart `### Recent` table: of the rows the token budget picks, the project's own first and then other projects' (each newest first). `0` hides the table. Was the whole pick before the injection-budget change (7–13 rows per SessionStart table on the corpus it was measured on, mean 9.4). | `5` |
+| `CLAUDE_MEM_DASHBOARD_EVENTS` | `1` puts the `💡 mem events: N entries` count back on the SessionStart dashboard (dropped in the injection-budget change: the model never ran `activity` from it on the corpus measured). | _(off)_ |
 | `CLAUDE_MEM_SUMMARY_TAIL` | `0`/`off` stops Stop from using the head of the final reply (first 120 characters, code blocks and line-leading markers removed) as a session's Completed line when that reply has no Done / Not done / Failed / Uncertain section; Completed then falls back to observation titles, as before v6.18.0; a line already written gives way to the titles at the session's next turn. A later reply under 400 characters does not replace an earlier one. | _(on)_ |
 | `CLAUDE_MEM_EPISODE_INPUT_FILTER` | What the episode summarizer may learn from. A subagent's tool calls stay out of the episode buffer unless they edit a file inside the project, and mutation probes (mutate → RED run → restore) and the agent's own failing inline scripts (a patch's `anchor not found`) are dropped before a window is saved or summarized — replayed over the 30 audited events, this removes 3 of the 16 that were wrong outright; with `CLAUDE_MEM_LESSON_GROUNDING` none of the 16 lessons is injected. `off` restores the unfiltered input. | _(on)_ |
 | `CLAUDE_MEM_BASH_RECALL` | File recall before a Bash command that views (`cat`, `sed -n`, `head`…) or writes (`sed -i`, `cat > f`, a python patch…) a file, like the Read / Edit recall. A bash prefilter keeps Node from starting for other commands. `off` disables this leg only. | _(on)_ |
@@ -1154,7 +1156,7 @@ claude-mem-lite.
 | Variable | Description | Default |
 |----------|-------------|---------|
 | `CLAUDE_MEM_ALL_TOOLS` | `1` exposes every registered MCP tool in `tools/list` instead of only the core ones (pre-v2.34.0 behavior). The 9 hidden tools stay callable by exact name either way; `mem_search_feedback` is registered only when search telemetry is enabled. | _(9 core)_ |
-| `CLAUDE_MEM_FILE_INTEL` | `0` disables the file-intel block injected before `Read` (past observations about the file you are about to open). | _(on)_ |
+| `CLAUDE_MEM_FILE_INTEL` | `1` turns on the file-intel line on the first read of a large file — a `Read`, or a Bash `cat` / `sed -n` / `head` — (its approximate token size and a one-line summary). Off by default since the injection-budget change: the line reaches the model next to the read's result, so it cannot shape that read. | _(off)_ |
 | `CLAUDE_MEM_FILE_INTEL_MIN_TOKENS` | Files smaller than this stay silent — file-intel only pays for itself on large files. | `800` |
 | `CLAUDE_MEM_REREAD_GUARD` | `0` disables the warning when the same file is read twice in a session. Never fires on `offset`/`limit` paging. | _(on)_ |
 | `CLAUDE_MEM_REREAD_MIN_TOKENS` | Token floor below which the re-read guard stays silent. | `600` |
@@ -1194,6 +1196,7 @@ benchmark and A/B harness are calibrated against — changing them invalidates t
 | `CLAUDE_MEM_REACH_DISCLOSURE` | `off` suppresses the one-line note that fires when a search's reported `total` exceeds what its pagination can hand back. The candidate pool is sized from `limit` alone and deliberately does not grow with `offset` (D#30 — an offset-scaled pool re-ranks its own prefix under RRF, so pages overlapped and gapped), while `total` is the full match count. Measured on a 128-row corpus: at the default limit of 20 the last non-empty offset is 59, so 60 of 128 rows are unreachable at any offset. The note reports that; it does not change retrieval, ranking, or which rows are returned. It stays **silent** when a filter you asked for (`tier`, or the CJK precision gate on prompts) removed rows after the count was taken — that gap is your filter, not the pool, and raising the limit would not recover it. | _(on)_ |
 | `CLAUDE_MEM_NORMALIZE_CROSS_PROJECT` | `1` restores the pre-fix behaviour where the daily unattended `normalize` runs ONCE over every project's concepts at the same time. That is how one project's stored content could steer synonym groups applied to another project's rows, so the default is now one scoped pass per project (bounded to 8 per run). The cost of the default is that `k8s` in one project and `kubernetes` in another are no longer unified automatically. Note that EVERY unscoped run fans out, including an explicit `optimize --run --task normalize` with no `--project` — this variable is the only route back to the single cross-project pass. A foreground `optimize` run prints a warning when it is set; the daily unattended pass cannot (its worker is spawned with stderr closed), so `claude-mem-lite doctor` reports it as a ⚠ instead. | _(off)_ |
 | `CLAUDE_MEM_AUTO_DEEP_CLI` | `0` disables the same auto-escalation on the CLI path only. | _(auto)_ |
+| `CLAUDE_MEM_UPS_PROMPT_ECHO` | `0` lets the "Past similar questions" fallback show a stored question identical (or nearly) to the prompt just typed, from an earlier session. The current session's own prompts stay excluded either way: showing the prompt just typed was a bug. | _(on)_ |
 | `CLAUDE_MEM_SCOPE_FILTER` | `1` stops environment-scoped observations from firing on file-triggered recall. They stay reachable via search. **Leave it off**: on the face it gates, `environment` is not the low-relevance class its premise assumes — it cites at least as well as `project` (47.5% vs 44.3%, intervals overlapping), and an earlier measurement left 173 recall groups empty with it on. | _(off)_ |
 | `CLAUDE_MEM_READS_CARRY` | An episode flush collects `reads-<project>.txt` only when it will actually save an observation, so a flush that records nothing no longer discards the Read paths it swept up (42.2% of the paths a flush consumed, measured over 1122 transcripts). `0` restores the pre-v3.83.0 behaviour. | _(on)_ |
 
@@ -1252,6 +1255,8 @@ and names can change between releases.
 | `CLAUDE_MEM_TASK_IMPERATIVE` | `on`/`1` injects the single most relevant lesson at prompt position under an imperative template. | _(off)_ |
 | `CLAUDE_MEM_SUBAGENT_INJECT` | Dispatch-time memory injection for subagents. | _(off)_ |
 | `CLAUDE_MEM_RECALL_FRAMING` | First line of a PreToolUse / PostToolUse recall block. Unset or `legacy` = "system-injected context, continue your planned action"; `factual` = a plain statement of where the notes come from; `ab` = each session gets one of the two, for `benchmark/citation-live-replay.mjs --by-framing`. Any other value is `legacy`. | `legacy` |
+| `CLAUDE_MEM_RECALL_HEADER_ONCE` | `0` puts the framing line on every PreToolUse recall block. By default a thread (the main session, or one subagent) gets it on its first block only, and again after `/compact`. | _(on)_ |
+| `CLAUDE_MEM_DIRECTIVE_ONCE` | `0` repeats the full default pre-edit directive on every block. By default a thread gets it in full once (again after `/compact`) and a short form that keeps the `#NN` tag rule after that. The `verdict` / `bind` / `bridge` arms always get their full text. | _(on)_ |
 | `CLAUDE_MEM_SALIENCE` | Selects how the pre-edit lesson line asks for a response: unset = name a lesson's `#NN` only where it changed the edit; `verdict` = the pre-6.17 per-lesson `applied` / `n/a` verdict (the adoption row in CLAUDE.md and the detail doc keep the new wording, and since 6.17.1 the directive says it overrides them); `bind` / `bridge` = comprehension-bridge arms (`bridge` keeps the pre-6.17 verdict wording as its fallback; neither says it overrides the adopted text, so their measured wording stays fixed); `legacy` = no directive. | _(unset)_ |
 | `CLAUDE_MEM_EDGE_DECAY` | Enables decay of file↔observation edges. | _(off)_ |
 | `CLAUDE_MEM_EDGE_DECAY_K` | Edge-decay threshold when the flag above is on (clamped to ≥1). | `3` |

package/hook-context.mjs

@@ -46,6 +46,8 @@ import { inferProjectDir } from './project-utils.mjs';
 import { TYPE_QUALITY, TYPE_QUALITY_DEFAULT } from './scoring-sql.mjs';
 
 import { DAY_MS } from './lib/time-constants.mjs';
+import { capRecentRows, recentTableRowCap } from './lib/recent-table.mjs';
+
 /**
  * Compute adaptive recall time windows based on project activity velocity.
  * High activity -> shorter windows (recent data more relevant).
@@ -532,14 +534,16 @@ const MIN_LOCAL_OBS = 3;
  * MIN_LOCAL_OBS, so the table gains at most two rows.
  *
  * The COUNT never shrinks; the composition can, and that is a ranking decision rather than
- * an accident. At the uncapped table site this only adds. At the `.slice(0, MIN_LOCAL_OBS)`
+ * an accident. At the table site, before its 5-row cap, this only added. At the `.slice(0, MIN_LOCAL_OBS)`
  * site the selected rows are PREPENDED, so with 1 local row and 3+ fallback rows the third
  * fallback title is evicted — still three rows, one of them now local. Exhaustive
  * enumeration over 42,436 ordered input pairs: 0 cases render fewer rows, 3,000 evict a
  * fallback row that way, max gain 2. Preferring the project's own rows over cross-project
  * ones inside a fixed window is the intended order, and saying so is the point: a new
  * population entering a limit-bounded window without a stated ranking is this repo's
- * recorded failure shape.
+ * recorded failure shape. The table site has been capped since the injection-budget change
+ * (5 rows), and its cut keeps that order too — capRecentRows ranks own rows first; a newest-5
+ * cut over the union evicted them (pre-ship defect review P2-1).
  */
 function withFallbackTopUp(observations, fallbackObs) {
   if (observations.length >= MIN_LOCAL_OBS) return observations;
@@ -914,8 +918,15 @@ export function buildSessionContextLines(
   // already chosen, so the token budget and the row set are untouched (pinned by a case in
   // tests/hook-context.test.mjs). Tiebroken on id for the same reason D#9 gives — an
   // untiebroken tie flips direction, and two saves in one millisecond are common.
+  //
+  // Injection budget C4: the display is then cut to `recentTableRowCap()` rows (5), the project's
+  // own rows ranked before the cross-project top-up (lib/recent-table.mjs). The knapsack still
+  // picks as before.
   const obsLines = [];
-  const obsToShow = [...withFallbackTopUp(observations, fallbackObs)].sort(
+  const obsToShow = capRecentRows(
+    withFallbackTopUp(observations, fallbackObs),
+    project,
+    recentTableRowCap(),
     (a, b) => Date.parse(b.created_at) - Date.parse(a.created_at) || b.id - a.id,
   );
   if (obsToShow.length > 0) {

package/hook.mjs

@@ -175,6 +175,7 @@ import { gcOldMetricShards, recordMetric } from './lib/metrics.mjs';
 import { detectMemOverride } from './lib/mem-override.mjs';
 import { injectedIdsFileName, keyContextIdsFileName, readInjectedMarker } from './lib/injected-ids.mjs';
 import { recordKeyContextInjection, touchKeyContextMarker } from './lib/keyctx-marker.mjs';
+import { RECALL_SHOWN_PREFIX, clearRecallShown } from './lib/recall-shown.mjs';
 import { liveObsFilterSql } from './lib/inject-search-core.mjs';
 import { selectErrorRecall } from './lib/error-recall-core.mjs';
 import { errorRecallSuppression } from './lib/error-recall-gate.mjs';
@@ -1871,7 +1872,8 @@ function gcStalePreRecallCooldowns() {
       const isInjectedMarker =
         name.startsWith('.claude-mem-injected-') ||
         name.startsWith('.claude-mem-keyctx-') || // D#123 Key Context marker — same per-session growth, same 24h GC
-        name.startsWith(BUGFIX_NUDGE_MARKER_PREFIX); // §9-B once-per-session nudge claim — same shape
+        name.startsWith(BUGFIX_NUDGE_MARKER_PREFIX) || // §9-B once-per-session nudge claim — same shape
+        name.startsWith(RECALL_SHOWN_PREFIX); // injection budget C1/C3 per-thread marker — same shape
       if (!isCooldown && !isInjectedMarker) continue;
       try {
         const p = join(RUNTIME_DIR, name);
@@ -3102,6 +3104,14 @@ async function handleSessionStart() {
   } catch {
     /* stdin unavailable — legacy behavior */
   }
+  // Injection budget C1/C3 (lib/recall-shown.mjs): the recall header and full directive are
+  // shown once per thread because the thread still holds the first copy. Compaction is when it
+  // stops holding it, so the main thread starts over; so does any fresh context (startup, or a
+  // /clear, which also rotates the session id). `resume` keeps the marker, on the ASSUMPTION that
+  // a resumed transcript still carries the earlier copies — not verified (pre-ship delta review);
+  // hooks/hooks.json does not even match `resume`, so this branch only sees it from a direct
+  // call. Clearing errs safe: the worst case is one more header.
+  if (ccSessionId && startSource !== 'resume') clearRecallShown(RUNTIME_DIR, ccSessionId);
 
   // Snapshot episode BEFORE flush for handoff extraction
   const episodeSnapshot = readEpisodeRaw();

package/lib/file-intel.mjs

@@ -17,6 +17,17 @@ const SUMMARY_MAX = 80;
 const DEFAULT_MIN_TOKENS = 800;
 const DEFAULT_MAX_READ_BYTES = 24 * 1024;
 
+/**
+ * Whether the hook injects the line at all. Opt-in since the injection-budget change
+ * (docs/audits/20261016-injection-budget-baseline.md): CLAUDE_MEM_FILE_INTEL=1/on/true/yes.
+ * Exported so benchmark/injection-budget.mjs replays the shipped predicate, not a copy.
+ * @param {Record<string, string|undefined>} [env]
+ * @returns {boolean}
+ */
+export function fileIntelEnabled(env = process.env) {
+  return ['1', 'on', 'true', 'yes'].includes(String(env.CLAUDE_MEM_FILE_INTEL || '').toLowerCase());
+}
+
 // Mirror of utils.estimateTokens (ASCII ~4 chars/token, CJK ~1.5). Kept local so
 // the standalone hook stays lean — see file header + the mirror test.
 export function estimateContentTokens(text) {

package/lib/recall-shown.mjs

@@ -0,0 +1,116 @@
+// lib/recall-shown.mjs — what one THREAD has already been shown once: the recall framing header
+// and the full cite directive (injection budget C1 / C3, docs/audits/20261016-injection-budget-baseline.md).
+//
+// Every PreToolUse recall block opened with the framing line — the legacy wording, or under the
+// `factual` arm (lib/recall-framing.mjs) a line naming the file — and every directive line carried
+// the same ACK text. On the frozen 52-session corpus the header was 2.78 KB/session over 1,546
+// blocks (220 distinct strings: 1,033 legacy at 82 B, 513 factual naming a file) and the
+// Read→Edit nudge carrying the full directive 2.03 KB/session over 340 — while a thread needs each
+// once to know what the `[mem]` blocks are and how to tag a lesson. (PostToolUse recall carries a
+// framing line only under the `bind` arm, and this module does not govern it.) So the first block of a
+// thread carries both in full, later blocks drop the header and carry a short directive that
+// keeps the tag rule. Lesson rows are never touched here: every `#NN` that was injected still
+// is, so the (session, id) pairs the cite-rate counts do not move.
+//
+// The marker is keyed like the cooldown (lib/cooldown-path.mjs threadKey): a subagent thread
+// shares no context with its parent, so it gets its own header. SessionStart clears the main
+// thread's marker on every source but `resume` — compaction, /clear and a fresh start are when the
+// earlier copy leaves (or was never in) the context. A subagent's marker goes only with the 24 h GC.
+//
+// Leaf on purpose: scripts/pre-tool-recall.js is a hot standalone hook and imports this.
+//
+// Switches (each restores the old behaviour on its own):
+//   CLAUDE_MEM_RECALL_HEADER_ONCE=0   header on every block
+//   CLAUDE_MEM_DIRECTIVE_ONCE=0       full directive on every block
+
+import { readFileSync, unlinkSync } from 'fs';
+import { join } from 'path';
+import { atomicWriteFileSync } from './atomic-write.mjs';
+import { cooldownSessionKey } from './cooldown-path.mjs';
+
+/** Filename prefix, exported so the SessionStart GC can match the family. */
+export const RECALL_SHOWN_PREFIX = 'recall-shown-';
+
+// The default salience arm's directive (D#98). Moved here from scripts/pre-tool-recall.js, byte
+// for byte, so benchmark/injection-budget.mjs can recognise it in recorded blocks.
+export const ACK_DIRECTIVE =
+  'apply each lesson to this edit or rule it out. If one changes the edit, add its bare tag (#NN) once at the end of the sentence describing that change; a lesson that did not apply needs no mention, and memory ids get no other mention in your reply.';
+// What later blocks of the same thread carry. It keeps the one rule a cite depends on (tag only
+// a lesson that changed the edit) and points back at the full text, which this thread has
+// already been shown — the marker is cleared whenever the context starts over (see above) precisely
+// so that stays true.
+export const ACK_DIRECTIVE_SHORT =
+  'apply each lesson to this edit — tag rule as before: (#NN) only where one changes it.';
+
+const OFF = ['0', 'off', 'false', 'no'];
+const isOn = (v) => !OFF.includes(String(v ?? '').toLowerCase());
+
+const EMPTY = Object.freeze({ header: false, directive: false });
+
+/**
+ * Decide what one recall block shows, given what the thread was already shown.
+ *
+ * @param {{header: boolean, directive: boolean}} shown
+ * @param {{header: boolean, directive: boolean}} wants  what the block would carry today
+ * @param {Record<string, string|undefined>} [env]
+ * @returns {{header: boolean, directive: 'full'|'short'|null, next: {header: boolean, directive: boolean}}}
+ */
+export function planRecallBlock(shown, wants, env = process.env) {
+  const s = shown || EMPTY;
+  const header = Boolean(wants?.header) && (!isOn(env.CLAUDE_MEM_RECALL_HEADER_ONCE) || !s.header);
+  let directive = null;
+  if (wants?.directive) directive = isOn(env.CLAUDE_MEM_DIRECTIVE_ONCE) && s.directive ? 'short' : 'full';
+  return {
+    header,
+    directive,
+    next: { header: Boolean(s.header || header), directive: Boolean(s.directive || directive === 'full') },
+  };
+}
+
+/**
+ * @param {string} runtimeDir
+ * @param {string|null|undefined} thread  threadKey(sessionId, agentId); null without a session
+ * @returns {string|null}
+ */
+export function recallShownPath(runtimeDir, thread) {
+  if (!thread) return null;
+  return join(runtimeDir, `${RECALL_SHOWN_PREFIX}${cooldownSessionKey(thread)}.json`);
+}
+
+/** @returns {{header: boolean, directive: boolean}} empty when absent, unreadable or no path */
+export function readRecallShown(path) {
+  if (!path) return { ...EMPTY };
+  try {
+    const v = JSON.parse(readFileSync(path, 'utf8'));
+    return { header: v?.header === true, directive: v?.directive === true };
+  } catch {
+    return { ...EMPTY };
+  }
+}
+
+/** Best-effort write; a lost write only means the next block shows the line again. */
+export function markRecallShown(path, shown) {
+  if (!path) return;
+  try {
+    atomicWriteFileSync(
+      path,
+      JSON.stringify({ header: Boolean(shown?.header), directive: Boolean(shown?.directive) }),
+    );
+  } catch {
+    /* silent — never block a tool call over a marker */
+  }
+}
+
+/**
+ * SessionStart (startup / clear / compact — every source but resume): the main thread starts
+ * from a context without the earlier copies.
+ */
+export function clearRecallShown(runtimeDir, sessionId) {
+  const p = recallShownPath(runtimeDir, sessionId);
+  if (!p) return;
+  try {
+    unlinkSync(p);
+  } catch {
+    /* absent is fine */
+  }
+}

package/lib/recent-table.mjs

@@ -0,0 +1,49 @@
+// lib/recent-table.mjs — how many rows the SessionStart `### Recent` table shows, and which
+// (injection budget C4, docs/audits/20261016-injection-budget-baseline.md).
+//
+// The table used to render the whole token-budget pick: 7–13 rows per table (60 SessionStart
+// tables) on the frozen 52-session corpus, 1.02 KB/session, ids cited 2 times in 498 (session, id) pairs. It now shows
+// `recentTableRowCap()` rows (5).
+//
+// WHICH five matters on a thin project: below MIN_LOCAL_OBS own rows, hook-context tops the pick up
+// with other projects' rows, which are often newer. A newest-5 cut over that union evicted the
+// project's OWN rows (pre-ship defect review P2-1: 5 of the 60 corpus tables, 10 own rows), so
+// the cut ranks own rows first and only then fills with foreign ones.
+//
+// Leaf (env-number only): benchmark/injection-budget.mjs replays these two functions, and
+// importing hook-context.mjs would create the data dir's runtime directory as a side effect.
+
+import { envNumber } from './env-number.mjs';
+
+/**
+ * Rows the table shows. Read per call so the CLI `context` command and tests see the current env.
+ * 0 hides the table.
+ * @param {Record<string, string|undefined>} [env]
+ * @returns {number}
+ */
+export function recentTableRowCap(env = process.env) {
+  return envNumber(env.CLAUDE_MEM_STARTUP_RECENT_ROWS, {
+    name: 'CLAUDE_MEM_STARTUP_RECENT_ROWS',
+    defaultValue: 5,
+    min: 0,
+    integer: true,
+  });
+}
+
+/**
+ * The rows the table keeps, in display order: the project's own rows first (a row with no
+ * `project`, or this project), then other projects' rows, each newest first by `newer`; cut to
+ * `cap`; then sorted by `newer` for display. Copies — the caller's array is not reordered.
+ *
+ * @template {{project?: string|null}} T
+ * @param {T[]} rows
+ * @param {string} project
+ * @param {number} cap
+ * @param {(a: T, b: T) => number} newer  the display comparator (newest first)
+ * @returns {T[]}
+ */
+export function capRecentRows(rows, project, cap, newer) {
+  const own = (o) => !o.project || o.project === project;
+  const ranked = [...rows.filter(own).sort(newer), ...rows.filter((o) => !own(o)).sort(newer)];
+  return ranked.slice(0, Math.max(0, cap)).sort(newer);
+}

package/lib/startup-dashboard.mjs

@@ -1,9 +1,10 @@
-// lib/startup-dashboard.mjs — aggregates git/tasks/plans/handoff/events stats
-// into a single SessionStart injection line (T10c v2.31).
+// lib/startup-dashboard.mjs — aggregates git/tasks/plans/handoff state
+// into a single SessionStart injection line (T10c v2.31; the events count left in the
+// injection-budget change).
 //
 // Pure function (with injectable stubs for test determinism). Never throws:
 // every external reader is try/catch'd so a broken git repo, missing tasks dir,
-// or absent events table cannot break SessionStart.
+// or absent table cannot break SessionStart.
 
 import { readGitState } from './git-state.mjs';
 import { readProjectTasks } from './task-reader.mjs';
@@ -47,7 +48,7 @@ function readRecentHandoff(db, project) {
  *
  * @param {object} options
  * @param {object} options.db - better-sqlite3 handle. May be null.
- * @param {string} options.project - project identifier used for handoff/events queries.
+ * @param {string} options.project - project identifier used for the handoff (and opt-in events) query.
  * @param {string} [options.projectPath=process.cwd()] - filesystem root for git + tasks.
  * @param {object} [options.stubs] - per-field test injectors:
  *        {git?, tasks?, plans?, handoff?}. handoff: pass explicit null to skip;
@@ -61,13 +62,6 @@ export function buildDashboard({ db, project, projectPath = process.cwd(), stubs
   // stubs.handoff === null means "test asserted no handoff"; undefined means "query DB".
   const handoff = stubs && 'handoff' in stubs ? stubs.handoff : readRecentHandoff(db, project);
 
-  let eventCount = 0;
-  try {
-    eventCount = db?.prepare(`SELECT COUNT(*) c FROM events WHERE project = ?`).get(project)?.c ?? 0;
-  } catch {
-    /* events table may not exist on very old DBs */
-  }
-
   const parts = [];
 
   if ((git?.changed?.length ?? 0) > 0 || (git?.stashes?.length ?? 0) > 0) {
@@ -110,8 +104,23 @@ export function buildDashboard({ db, project, projectPath = process.cwd(), stubs
     );
   }
 
-  if (eventCount > 0) {
-    parts.push(`💡 mem events: ${eventCount} entries (\`claude-mem-lite activity recent\`)`);
+  // Injection budget C6: a `💡 mem events: N entries (claude-mem-lite activity recent)` line
+  // used to follow. It sat in all 60 SessionStart blocks of the frozen 52-session corpus and
+  // `activity` was run in none of the 52 sessions (docs/audits/20261016-injection-budget-
+  // baseline.md; a first count said 56 and 4, corrected in the pre-ship claims review); the
+  // count tells the model nothing it acts on. `claude-mem-lite help` still lists `activity recent`.
+  // CLAUDE_MEM_DASHBOARD_EVENTS=1 brings the line back (pre-ship defect review P2-2).
+  if (
+    ['1', 'on', 'true', 'yes'].includes(String(process.env.CLAUDE_MEM_DASHBOARD_EVENTS || '').toLowerCase())
+  ) {
+    let eventCount = 0;
+    try {
+      eventCount = db?.prepare(`SELECT COUNT(*) c FROM events WHERE project = ?`).get(project)?.c ?? 0;
+    } catch {
+      /* events table may not exist on very old DBs */
+    }
+    if (eventCount > 0)
+      parts.push(`💡 mem events: ${eventCount} entries (\`claude-mem-lite activity recent\`)`);
   }
 
   // Invited-memory hint (Phase F): persists every SessionStart until the user

package/npm-shrinkwrap.json

@@ -1,12 +1,12 @@
 {
   "name": "claude-mem-lite",
-  "version": "6.26.1",
+  "version": "6.27.0",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "claude-mem-lite",
-      "version": "6.26.1",
+      "version": "6.27.0",
       "os": [
         "darwin",
         "linux",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-mem-lite",
-  "version": "6.26.1",
+  "version": "6.27.0",
   "description": "Persistent long-term memory for Claude Code via MCP — captures coding decisions, bugfixes, and context across sessions. FTS5 BM25 keyword search with episode batching. Single SQLite DB, no external services. A lighter, lower-cost alternative to claude-mem (episode batching + a smaller model; cost savings are an internal estimate, not a measured benchmark).",
   "type": "module",
   "packageManager": "npm@10.9.2",
@@ -123,6 +123,8 @@
     "lib/hook-stdout.mjs",
     "lib/hook-text-cap.mjs",
     "lib/recall-framing.mjs",
+    "lib/recall-shown.mjs",
+    "lib/recent-table.mjs",
     "lib/proc-lock.mjs",
     "lib/atomic-write.mjs",
     "lib/platform-gate.mjs",

package/scripts/pre-tool-recall.js

@@ -29,12 +29,21 @@ import {
   toolEditPath,
 } from '../lib/file-edge-match.mjs';
 import { scrubFilePath } from '../lib/scrub-record.mjs';
-import { fileIntelFor } from '../lib/file-intel.mjs';
+import { fileIntelFor, fileIntelEnabled } from '../lib/file-intel.mjs';
 import { shouldWarnReread, buildRereadWarning, readFileMeta } from '../lib/reread-guard.mjs';
 import { recordMetric } from '../lib/metrics.mjs';
 import { presentIdents } from '../lib/lesson-idents.mjs';
 import { neutralizeContextDelimiters } from '../format-utils.mjs';
 import { recallFramingLine } from '../lib/recall-framing.mjs';
+// Leaf (fs + path): the header and the full ACK directive once per thread (injection budget C1/C3).
+import {
+  ACK_DIRECTIVE,
+  ACK_DIRECTIVE_SHORT,
+  markRecallShown,
+  planRecallBlock,
+  readRecallShown,
+  recallShownPath,
+} from '../lib/recall-shown.mjs';
 // D#154: the one stdout writer. This script has THREE emit sites (Read→Edit ack,
 // repeated-read guard, lesson block) and they stay one document because each branch
 // process.exit()s before reaching the next.
@@ -158,8 +167,9 @@ const SALIENCE_BRIDGE = process.env.CLAUDE_MEM_SALIENCE === 'bridge';
 // would make readings before and after this change incomparable (pre-ship review P2-2).
 const VERDICT_DIRECTIVE =
   "apply each lesson to this edit or rule it out — state '#NN applied' or '#NN n/a — <reason>' in your next user-facing message.";
-const ACK_DIRECTIVE =
-  'apply each lesson to this edit or rule it out. If one changes the edit, add its bare tag (#NN) once at the end of the sentence describing that change; a lesson that did not apply needs no mention, and memory ids get no other mention in your reply.';
+// ACK_DIRECTIVE (the default) lives in lib/recall-shown.mjs with its short form: a thread gets the
+// full text once and the short one after (injection budget C3). Only the default arm shortens —
+// the other arms' text must stay the one their readings were taken with (see below).
 // v-bind salience forcing-function (#8771 audit: ack ≠ act). Instead of a cheap
 // '#NN applied / n/a' verdict, demand the model bind the lesson to the concrete
 // line it's editing and quote the satisfying edit line. Selected by
@@ -182,13 +192,20 @@ const ACTIVE_DIRECTIVE = SALIENCE_BIND
       : ACK_DIRECTIVE;
 const STALE_MS = 10 * 60 * 1000; // 10 minutes cleanup threshold for legacy file
 // Feature ① (file intelligence): on the first Read of a file each session, inject
-// its approximate token size + a one-line summary so the agent can decide to read
-// fully, slice, or grep. Read-only (Edit/Write already commit to the file). Default
-// ON; CLAUDE_MEM_FILE_INTEL=0 disables. Files below the token floor stay silent so
-// small reads carry no noise. Env names mirror schema.mjs CLAUDE_MEM_* convention (#8447).
-const FILE_INTEL_OFF = ['0', 'off', 'false', 'no'].includes(
-  String(process.env.CLAUDE_MEM_FILE_INTEL || '').toLowerCase(),
-);
+// its approximate token size + a one-line summary. Read-only (Edit/Write already commit
+// to the file). Files below the token floor stay silent. Env names mirror schema.mjs
+// CLAUDE_MEM_* convention (#8447).
+//
+// OPT-IN since the injection-budget change (docs/audits/20261016-injection-budget-baseline.md).
+// It was meant to let the agent "decide to read fully, slice, or grep", but PreToolUse
+// additionalContext is delivered next to the tool RESULT (Claude Code hooks reference, "Add
+// context for Claude"), so it can never change the call it rides on. On the frozen 52-session
+// corpus 89.9% of its 1,102 lines rode a call that was already a partial read (`sed -n`, grep,
+// Read with offset/limit), after a full Read the same file was sliced later in the turn LESS
+// often (34.9%, 22/63) than after a partial Bash read (69.1%), and no reply named a size (0/1,102) —
+// at 1.57 KB/session, plus the framing header of the 426 blocks it was the only content of.
+// CLAUDE_MEM_FILE_INTEL=1 turns it back on.
+const FILE_INTEL_ON = fileIntelEnabled();
 // P2 (D#78): edge-level decay ENFORCEMENT — opt-in (default OFF, shadow-first).
 // When on, a (obs,file) edge whose miss_streak reached K consecutive uncited
 // injections stops firing on this surface; the lesson stays reachable via
@@ -541,6 +558,33 @@ try {
   const isSessionScoped = Boolean(sessionId);
   const cooldown = readCooldown(cooldownPath);
   const now = Date.now();
+  // C1/C3 (lib/recall-shown.mjs): the framing header and the full ACK directive once per thread.
+  // Same thread key as the cooldown; null without a session, which shows both every time.
+  const shownPath = recallShownPath(RUNTIME_DIR, dedupKey);
+  // Prepends the header when this thread has not had one, fills the directive slot, and records
+  // what was shown. `body` is everything but the header; `directiveAt(text)` builds the line
+  // that carries the directive, or is null when the block has none.
+  // `name` is the file the factual framing arm names; the lesson block passes its scrubbed `fname`.
+  const emitRecallBlock = (body, directiveAt = null, name = basename(filePath)) => {
+    const shown = readRecallShown(shownPath);
+    const plan = planRecallBlock(shown, { header: true, directive: Boolean(directiveAt) });
+    const lines = [...body];
+    if (directiveAt) {
+      lines.push(
+        directiveAt(
+          plan.directive === 'short' && ACTIVE_DIRECTIVE === ACK_DIRECTIVE
+            ? ACK_DIRECTIVE_SHORT
+            : ACTIVE_DIRECTIVE,
+        ),
+      );
+    }
+    if (plan.header) lines.unshift(recallFramingLine('PreToolUse', { sessionId, fname: name }));
+    queueHookContext('PreToolUse', lines.join('\n'));
+    flushHookStdout();
+    if (plan.next.header !== shown.header || plan.next.directive !== shown.directive) {
+      markRecallShown(shownPath, plan.next);
+    }
+  };
   if (isSessionScoped) {
     const entry = cooldown[filePath];
     if (entry) {
@@ -556,14 +600,11 @@ try {
       if (!isRead && wasReadMode && seenIds.length > 0 && !SALIENCE_LEGACY) {
         // Namespaced per table: a bare `#N` for an event id names a different memory.
         const idList = lessonIdTokens(seenIds, entry.obsIds).join(', ');
-        queueHookContext(
-          'PreToolUse',
-          [
-            recallFramingLine('PreToolUse', { sessionId, fname: basename(filePath) }),
-            `[mem] ⚠ Lessons ${idList} were shown when you Read ${basename(filePath)} — ${ACTIVE_DIRECTIVE}`,
-          ].join('\n'),
+        emitRecallBlock(
+          [],
+          (directive) =>
+            `[mem] ⚠ Lessons ${idList} were shown when you Read ${basename(filePath)} — ${directive}`,
         );
-        flushHookStdout();
         cooldown[filePath] = { ...entry, mode: 'edit' };
         writeCooldown(cooldownPath, cooldown, isSessionScoped);
       } else if (isRead && !REREAD_GUARD_OFF && typeof entry === 'object' && entry.reread) {
@@ -571,14 +612,7 @@ try {
         // nudge to reuse what's already in context. Read-only; never throws.
         const meta = readFileMeta(filePath);
         if (shouldWarnReread(entry.reread, meta ? meta.mtimeMs : null, isFullRead, REREAD_MIN_TOKENS)) {
-          queueHookContext(
-            'PreToolUse',
-            [
-              recallFramingLine('PreToolUse', { sessionId, fname: basename(filePath) }),
-              buildRereadWarning(basename(filePath), entry.reread.tokens),
-            ].join('\n'),
-          );
-          flushHookStdout();
+          emitRecallBlock([buildRereadWarning(basename(filePath), entry.reread.tokens)]);
           recordMetric(DATA_DIR, { event: 'reread_warn' }); // tier-1 firing counter (②)
         }
       }
@@ -824,10 +858,10 @@ try {
     // reliably renders across CC variants (sdscc drops plain-text stdout from PreToolUse).
     // suppressOutput:true hides it from transcript mode per CC hook docs.
     // Feature ①: file intelligence (size + summary) for the first Read of this
-    // file this session. Read-only; opt out via CLAUDE_MEM_FILE_INTEL=0. Never
+    // file this session. Read-only; opt-in via CLAUDE_MEM_FILE_INTEL=1. Never
     // throws — fileIntelFor returns null on unreadable/below-threshold files.
     let fileIntelLine = null;
-    if (isRead && !FILE_INTEL_OFF) {
+    if (isRead && FILE_INTEL_ON) {
       try {
         fileIntelLine = fileIntelFor(filePath, { minTokens: FILE_INTEL_MIN_TOKENS });
       } catch {}
@@ -860,15 +894,14 @@ try {
         via: viaBash ? 'bash' : 'tool',
       });
     }
-    const showFraming =
-      hasLessons || Boolean(fileIntelLine) || (!isRead && process.env.CLAUDE_MEM_PRETOOL_NUDGE === '1');
-    if (showFraming) {
-      // Framing line mirrors #7758 handoff-injection fix: without an explicit
-      // "this is context, the call continues" line, observed turn-end after Edit+reminder
-      // when the model misreads passive lesson context as a closing note. Two wordings
-      // run side by side per session — lib/recall-framing.mjs.
-      lines.push(recallFramingLine('PreToolUse', { sessionId, fname }));
-    }
+    // Framing line mirrors #7758 handoff-injection fix: without an explicit
+    // "this is context, the call continues" line, observed turn-end after Edit+reminder
+    // when the model misreads passive lesson context as a closing note. Wording:
+    // lib/recall-framing.mjs. emitRecallBlock prepends it to the FIRST block of a thread
+    // only (C1, lib/recall-shown.mjs): every later block still opens with its own `[mem]`
+    // line, and the thread has already been told what those are.
+    // The directive slot, filled by emitRecallBlock (full text once per thread, short after).
+    let directiveAt = null;
     // MED-1 (full audit 2026-07-16): defang the injection-block delimiters in
     // all DB/file-derived text before it enters additionalContext (which CC wraps
     // in <system-reminder>). Stored text is raw — a lesson/title/summary carrying
@@ -925,7 +958,7 @@ try {
           lines.push(
             `[mem] ⚠ #${bridged.id} → this edit must: ${neutralizeContextDelimiters(bridged.check)}. Confirm your new code satisfies it.`,
           );
-        else lines.push(`[mem] ⚠ Before this edit: ${ACTIVE_DIRECTIVE}`);
+        else directiveAt = (directive) => `[mem] ⚠ Before this edit: ${directive}`;
       }
     } else if (!isRead && process.env.CLAUDE_MEM_PRETOOL_NUDGE === '1') {
       // R-4: Edit/Write empty → short backfill reminder. OPT-IN (default off) as
@@ -939,16 +972,12 @@ try {
       //
       // Read never emitted this (passive). The cooldown write below still runs on
       // every branch, so Read→Edit dedup + cite-back lessonId tracking are intact.
-      // (Framing line already pushed above via showFraming.)
       lines.push(
         `[mem] No prior lessons for ${fname} — if you solve a non-obvious bug here, run: /lesson --file ${fname} "<root cause + fix>"`,
       );
     }
 
-    if (lines.length > 0) {
-      queueHookContext('PreToolUse', lines.join('\n'));
-      flushHookStdout();
-    }
+    if (lines.length > 0) emitRecallBlock(lines, directiveAt, fname);
     // Cooldown applies on ALL branches (including silent-Read) so subsequent
     // calls on the same file in the same session don't re-query — preserving
     // the per-filePath invariant that underpins Read→Edit dedup.

package/scripts/prompt-search-utils.mjs

@@ -275,3 +275,26 @@ export function extractDeferredRefs(text) {
   }
   return out;
 }
+
+/**
+ * Whether a stored prompt is an echo of the current one: the same text after whitespace and
+ * case are folded, or one a prefix of the other covering at least 80% of the longer (a re-paste
+ * with a line added). Injection budget C5: the past-question fallback handed the model its own
+ * prompt back in 8 of 52 rows on the frozen corpus (docs/audits/20261016-injection-budget-baseline.md).
+ * @param {string} stored
+ * @param {string} current
+ * @returns {boolean}
+ */
+export function isPromptEcho(stored, current) {
+  const norm = (s) =>
+    String(s ?? '')
+      .replace(/\s+/g, ' ')
+      .trim()
+      .toLowerCase();
+  const a = norm(stored);
+  const b = norm(current);
+  if (!a || !b) return false;
+  if (a === b) return true;
+  const [short, long] = a.length <= b.length ? [a, b] : [b, a];
+  return short.length >= 0.8 * long.length && long.startsWith(short);
+}

package/scripts/user-prompt-search.js

@@ -40,6 +40,7 @@ import {
   extractDeferredRefs,
   DEDUP_STALE_MS,
   detectMemOverride,
+  isPromptEcho,
 } from './prompt-search-utils.mjs';
 import { injectedIdsFileName, mergeInjectedMarker } from '../lib/injected-ids.mjs';
 import { getDeferredByIds } from '../lib/deferred-work.mjs';
@@ -566,7 +567,13 @@ function searchByFile(db, files, project, limit) {
 // ranking with no scoring multipliers and no top-|rel| gate (prompts are
 // sparser and more surface-form than observations; the gate would rarely
 // fire and mostly kill real hits).
-function searchByUserPrompts(db, queryText, project, limit) {
+//
+// Injection budget C5: a prompt from THIS Claude Code session is already in the context, and the
+// current prompt itself can be in the table (hook.mjs user-prompt writes it in parallel with this
+// search) — so rows of the current session are excluded in SQL, and a row that is an echo of the
+// current prompt (isPromptEcho) in JS. Rows written before cc_session_id existed (NULL) stay
+// eligible.
+function searchByUserPrompts(db, queryText, project, limit, ccSessionId = null) {
   const ftsQuery = upsFtsQuery(queryText);
   if (!ftsQuery) return [];
 
@@ -584,6 +591,7 @@ function searchByUserPrompts(db, queryText, project, limit) {
       AND s.project = ?
       AND up.created_at_epoch > ?
       AND up.prompt_text NOT LIKE '<task-notification>%'
+      AND (? IS NULL OR up.cc_session_id IS NULL OR up.cc_session_id != ?)
     ORDER BY relevance
     LIMIT ?
   `;
@@ -596,13 +604,23 @@ function searchByUserPrompts(db, queryText, project, limit) {
   // filter, then take `limit` — same ORDER BY, so the old result is a prefix of this
   // one and a row can only be added, never displaced by something worse.
   const poolLimit = Math.min(limit * PROMPT_FALLBACK_POOL_FACTOR, PROMPT_FALLBACK_POOL_MAX);
-  let rows = db.prepare(sql).all(ftsQuery, project, cutoff, poolLimit);
+  const session = typeof ccSessionId === 'string' && ccSessionId ? ccSessionId : null;
+  // The echo filter runs BEFORE the OR relaxation decides: the current prompt matches every one
+  // of its own AND terms, so an echo is often the AND query's only row — filtering it after
+  // would leave nothing and never try the OR pool (the LIMIT-upstream-of-a-JS-filter shape).
+  // CLAUDE_MEM_UPS_PROMPT_ECHO=0 keeps echoes from EARLIER sessions (the pre-change behaviour);
+  // the current session's rows stay excluded in SQL either way — that half is the bug fix.
+  const echoFilterOn = !['0', 'off', 'false', 'no'].includes(
+    String(process.env.CLAUDE_MEM_UPS_PROMPT_ECHO || '').toLowerCase(),
+  );
+  const notEcho = (rs) => (echoFilterOn ? rs.filter((r) => !isPromptEcho(r.prompt_text, queryText)) : rs);
+  let rows = notEcho(db.prepare(sql).all(ftsQuery, project, cutoff, session, session, poolLimit));
 
   if (rows.length === 0) {
     const orQuery = relaxFtsQueryToOr(ftsQuery);
     if (orQuery) {
       try {
-        rows = db.prepare(sql).all(orQuery, project, cutoff, poolLimit);
+        rows = notEcho(db.prepare(sql).all(orQuery, project, cutoff, session, session, poolLimit));
       } catch {}
     }
   }
@@ -1092,7 +1110,7 @@ async function main() {
     // single highest-noise UPS path. Restored when REQUIRE_SIGNAL=0.
     let promptRows = [];
     if (rows.length === 0 && (!REQUIRE_EXPLICIT_SIGNAL || signalPresent)) {
-      promptRows = searchByUserPrompts(db, promptText, project, PROMPT_FALLBACK_LIMIT);
+      promptRows = searchByUserPrompts(db, promptText, project, PROMPT_FALLBACK_LIMIT, hookData.session_id);
     }
 
     const candidateIds = rows.length > 0 ? rows.map((r) => r.id) : promptRows.map((r) => `P${r.id}`);

package/source-files.mjs

@@ -157,6 +157,8 @@ export const SOURCE_FILES = [
   'lib/hook-stdout.mjs',
   'lib/hook-text-cap.mjs',
   'lib/recall-framing.mjs',
+  'lib/recall-shown.mjs',
+  'lib/recent-table.mjs',
   // audit P0/P1: inter-process install lock + atomic config writes — imported by
   // install.mjs (settings.json + install lock) and hook-update.mjs (.claude.json
   // + auto-update lock). Must ship or a partial install/update skips them.