claude-mem-lite 2.87.0 → 2.89.0

package/.claude-plugin/marketplace.json

@@ -10,9 +10,9 @@
   "plugins": [
     {
       "name": "claude-mem-lite",
-      "version": "2.87.0",
+      "version": "2.89.0",
       "source": "./",
-      "description": "Persistent long-term memory for Claude Code via MCP — captures coding decisions, bugfixes, and context across sessions. Hybrid FTS5 + TF-IDF search with episode batching. Single SQLite DB, no external services. Alternative to claude-mem with 600x lower cost."
+      "description": "Persistent long-term memory for Claude Code via MCP — captures coding decisions, bugfixes, and context across sessions. Hybrid FTS5 + TF-IDF 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,7 +1,7 @@
 {
   "name": "claude-mem-lite",
-  "version": "2.87.0",
-  "description": "Persistent long-term memory for Claude Code via MCP — captures coding decisions, bugfixes, and context across sessions. Hybrid FTS5 + TF-IDF search with episode batching. Single SQLite DB, no external services. Alternative to claude-mem with 600x lower cost.",
+  "version": "2.89.0",
+  "description": "Persistent long-term memory for Claude Code via MCP — captures coding decisions, bugfixes, and context across sessions. Hybrid FTS5 + TF-IDF 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

@@ -4,7 +4,7 @@
 
 `claude-mem-lite` is a **persistent memory** (also called *long-term memory* or *cross-session context*) system for **[Claude Code](https://docs.anthropic.com/en/docs/claude-code)** — Anthropic's CLI coding agent. It runs as an **[MCP](https://modelcontextprotocol.io/) server** plus a set of Claude Code hooks, automatically capturing coding observations, decisions, and bug fixes during sessions, then providing hybrid full-text + semantic search to recall them later.
 
-Compared to general-purpose LLM memory frameworks like [`mem0`](https://github.com/mem0ai/mem0) or the MCP reference [`memory`](https://github.com/modelcontextprotocol/servers/tree/main/src/memory) server, claude-mem-lite is purpose-built for Claude Code's hook lifecycle: episode batching cuts LLM calls 7–10× vs the original [claude-mem](https://github.com/thedotmack/claude-mem) (600× lower total cost), and the hybrid FTS5 + TF-IDF retriever benchmarks at 0.88 Recall@10 / 0.96 Precision@10.
+Compared to general-purpose LLM memory frameworks like [`mem0`](https://github.com/mem0ai/mem0) or the MCP reference [`memory`](https://github.com/modelcontextprotocol/servers/tree/main/src/memory) server, claude-mem-lite is purpose-built for Claude Code's hook lifecycle: episode batching cuts LLM calls 7–10× vs the original [claude-mem](https://github.com/thedotmack/claude-mem) (an estimated ~600× lower total cost — see the cost model below; this is an architecture estimate, not a measured benchmark), while the hybrid FTS5 + TF-IDF retriever benchmarks at 0.88 Recall@10 / 0.96 Precision@10.
 
 > 中文简介：claude-mem-lite 是 Claude Code 的轻量级**持久化记忆 / 长期记忆 / 跨会话上下文**插件，基于 MCP 协议 + 钩子机制，自动捕获编码会话中的决策、修复和上下文，并通过 FTS5 + TF-IDF 混合检索召回。详见 [中文 README](README.zh-CN.md)。
 
@@ -29,15 +29,17 @@ A ground-up redesign of [claude-mem](https://github.com/thedotmack/claude-mem),
 
 ### Token & cost efficiency
 
-For a typical 50-tool-call session:
+For a typical 50-tool-call session (illustrative cost model — the ratios below are
+architecture estimates derived from batch size, token counts, and model pricing, **not**
+a measured end-to-end benchmark):
 
-| | claude-mem | claude-mem-lite | Ratio |
+| | claude-mem | claude-mem-lite | Ratio (estimated) |
 |---|---|---|---|
-| LLM calls | ~50 (every tool use) | ~5-8 (per episode) | **7-10x fewer** |
-| Tokens per call | 1,000-5,000 (raw JSON + history) | 200-500 (summaries only) | **5-10x smaller** |
-| Total tokens | ~100K-250K | ~1K-4K | **50-100x less** |
-| Model cost | Sonnet ($3/$15 per M) | Haiku ($0.25/$1.25 per M) | **12x cheaper** |
-| Combined savings | | | **600x+ lower cost** |
+| LLM calls | ~50 (every tool use) | ~5-8 (per episode) | **~7-10x fewer** |
+| Tokens per call | 1,000-5,000 (raw JSON + history) | 200-500 (summaries only) | **~5-10x smaller** |
+| Total tokens | ~100K-250K | ~1K-4K | **~50-100x less** |
+| Model cost | Sonnet ($3/$15 per M) | Haiku ($0.25/$1.25 per M) | **~12x cheaper** |
+| Combined savings | | | **~600x lower cost (estimated)** |
 
 ### Quality comparison
 
@@ -681,7 +683,7 @@ No. Claude Code's `CLAUDE.md` and `MEMORY.md` files act as static instruction me
 
 ### Why "lite"? What did the original claude-mem do differently?
 
-The original called an LLM on every tool use with raw JSON inputs. claude-mem-lite batches 5–10 operations per LLM call, uses a smaller model (Haiku), and runs a deterministic code-level filter before sending anything to the model. Net result: ~600× lower cost with equivalent search quality. See the [Architecture comparison](#architecture-comparison) above.
+The original called an LLM on every tool use with raw JSON inputs. claude-mem-lite batches 5–10 operations per LLM call, uses a smaller model (Haiku), and runs a deterministic code-level filter before sending anything to the model. Net result: an estimated ~600× lower cost (an architecture estimate from the cost model above, not a measured benchmark) with equivalent search quality. See the [Architecture comparison](#architecture-comparison) above.
 
 ### Does this work cross-project? Cross-machine?
 

package/README.zh-CN.md

@@ -4,7 +4,7 @@
 
 `claude-mem-lite` 是 **[Claude Code](https://docs.anthropic.com/en/docs/claude-code)**（Anthropic 官方 CLI 编程代理）的 **持久化记忆系统**（也称 **长期记忆 / 跨会话上下文 / Claude Code 记忆插件**）。它以 **[MCP](https://modelcontextprotocol.io/) 服务器** + Claude Code 钩子（hooks）的形式运行，在编码会话中自动捕获观察记录、决策、bug 修复，并通过 FTS5 全文检索 + TF-IDF 向量的混合检索召回历史上下文。
 
-与 [`mem0`](https://github.com/mem0ai/mem0)、MCP 官方参考实现的 [`memory`](https://github.com/modelcontextprotocol/servers/tree/main/src/memory) 服务器等通用 LLM 记忆框架相比，claude-mem-lite 专为 Claude Code 的钩子生命周期定制：episode 批处理把 LLM 调用量相比原版 [claude-mem](https://github.com/thedotmack/claude-mem) 减少 7-10 倍（综合成本下降 600 倍），FTS5 + TF-IDF 混合检索在 30 个查询的基准上达到 **Recall@10 = 0.88 / Precision@10 = 0.96**。
+与 [`mem0`](https://github.com/mem0ai/mem0)、MCP 官方参考实现的 [`memory`](https://github.com/modelcontextprotocol/servers/tree/main/src/memory) 服务器等通用 LLM 记忆框架相比，claude-mem-lite 专为 Claude Code 的钩子生命周期定制：episode 批处理把 LLM 调用量相比原版 [claude-mem](https://github.com/thedotmack/claude-mem) 减少 7-10 倍（综合成本估算下降约 600 倍 —— 见下方成本模型，属架构估算而非实测基准）；FTS5 + TF-IDF 混合检索在 30 个查询的基准上达到 **Recall@10 = 0.88 / Precision@10 = 0.96**。
 
 无需外部服务。单一 SQLite 数据库。开销极低。
 
@@ -27,15 +27,15 @@
 
 ### Token 与成本效率
 
-以典型的 50 次工具调用的会话为例：
+以典型的 50 次工具调用的会话为例（成本模型示意 —— 下列比率由批大小、token 量与模型定价**估算**得出，并非端到端实测）：
 
-| | claude-mem | claude-mem-lite | 比率 |
+| | claude-mem | claude-mem-lite | 比率（估算） |
 |---|---|---|---|
-| LLM 调用次数 | ~50（每次工具使用） | ~5-8（按 episode） | **减少 7-10 倍** |
-| 每次调用 token | 1,000-5,000（原始 JSON + 历史） | 200-500（仅摘要） | **减少 5-10 倍** |
-| 总 token 量 | ~100K-250K | ~1K-4K | **减少 50-100 倍** |
-| 模型成本 | Sonnet ($3/$15 每百万) | Haiku ($0.25/$1.25 每百万) | **便宜 12 倍** |
-| 综合节省 | | | **成本降低 600 倍+** |
+| LLM 调用次数 | ~50（每次工具使用） | ~5-8（按 episode） | **约减少 7-10 倍** |
+| 每次调用 token | 1,000-5,000（原始 JSON + 历史） | 200-500（仅摘要） | **约减少 5-10 倍** |
+| 总 token 量 | ~100K-250K | ~1K-4K | **约减少 50-100 倍** |
+| 模型成本 | Sonnet ($3/$15 每百万) | Haiku ($0.25/$1.25 每百万) | **约便宜 12 倍** |
+| 综合节省 | | | **成本降低约 600 倍（估算）** |
 
 ### 质量对比
 

package/haiku-client.mjs

@@ -20,6 +20,14 @@ const MODEL_MAP = {
   sonnet: 'claude-sonnet-4-5-20250929',
 };
 
+// Every background LLM call here is fixed-schema extraction / classification
+// (episode→JSON, type/merge classification, synonym + metadata extraction) whose
+// output is consumed deterministically (JSON.parse, MinHash dedup). Pin temperature
+// to 0 so the provider default (~1.0) doesn't inject wording variance that breaks
+// JSON parsing or defeats the wording-sensitive MinHash near-duplicate detector.
+// A call that genuinely needs sampling can pass opts.temperature to override.
+const DEFAULT_LLM_TEMPERATURE = 0;
+
 /**
  * Resolve the LLM model to use for background calls.
  * Reads CLAUDE_MEM_MODEL env var, defaults to 'haiku'.
@@ -143,7 +151,7 @@ export function flattenForCLI(input) {
  * @param {number} [opts.maxTokens=500] Max tokens in response
  * @returns {Promise<{text: string}|null>} Response or null on failure
  */
-export async function callHaiku(prompt, { timeout = 10000, maxTokens = 500 } = {}) {
+export async function callHaiku(prompt, { timeout = 10000, maxTokens = 500, temperature = DEFAULT_LLM_TEMPERATURE } = {}) {
   if (!prompt) return null;
 
   const mode = detectMode();
@@ -160,8 +168,8 @@ export async function callHaiku(prompt, { timeout = 10000, maxTokens = 500 } = {
   let primary = null;
   try {
     primary = mode === 'api'
-      ? await callHaikuAPI(prompt, { timeout, maxTokens })
-      : await callOpenRouterAPI(prompt, resolveModel().cli, { timeout, maxTokens });
+      ? await callHaikuAPI(prompt, { timeout, maxTokens, temperature })
+      : await callOpenRouterAPI(prompt, resolveModel().cli, { timeout, maxTokens, temperature });
   } catch (e) {
     debugCatch(e, `callHaiku:${mode}`);
   }
@@ -198,7 +206,7 @@ export async function callHaikuJSON(prompt, opts) {
  * @param {number} [opts.maxTokens=1000] Max tokens in response
  * @returns {Promise<{text: string}|null>} Response or null on failure
  */
-export async function callLLMWithModel(prompt, model = 'haiku', { timeout = 15000, maxTokens = 1000 } = {}) {
+export async function callLLMWithModel(prompt, model = 'haiku', { timeout = 15000, maxTokens = 1000, temperature = DEFAULT_LLM_TEMPERATURE } = {}) {
   if (!prompt) return null;
   const resolvedModel = MODEL_MAP[model] ? model : 'haiku';
   const mode = detectMode();
@@ -214,8 +222,8 @@ export async function callLLMWithModel(prompt, model = 'haiku', { timeout = 1500
   let primary = null;
   try {
     primary = mode === 'api'
-      ? await callModelAPI(prompt, resolvedModel, { timeout, maxTokens })
-      : await callOpenRouterAPI(prompt, resolvedModel, { timeout, maxTokens });
+      ? await callModelAPI(prompt, resolvedModel, { timeout, maxTokens, temperature })
+      : await callOpenRouterAPI(prompt, resolvedModel, { timeout, maxTokens, temperature });
   } catch (e) {
     debugCatch(e, `callLLMWithModel:${mode}:${resolvedModel}`);
   }
@@ -239,7 +247,7 @@ export async function callModelJSON(prompt, model = 'haiku', opts) {
   return parseJsonFromLLM(result.text);
 }
 
-async function callModelAPI(prompt, model, { timeout, maxTokens }) {
+async function callModelAPI(prompt, model, { timeout, maxTokens, temperature = DEFAULT_LLM_TEMPERATURE }) {
   const apiKey = process.env.ANTHROPIC_API_KEY;
   if (!apiKey) return null;
 
@@ -252,6 +260,7 @@ async function callModelAPI(prompt, model, { timeout, maxTokens }) {
     const body = {
       model: modelId,
       max_tokens: maxTokens,
+      temperature,
       messages: [{ role: 'user', content: user }],
     };
     // System slot is constant per call type (instructions, schema, type taxonomy)
@@ -312,7 +321,7 @@ function callModelCLI(prompt, model, { timeout }) {
 
 // ─── API Mode ────────────────────────────────────────────────────────────────
 
-async function callHaikuAPI(prompt, { timeout, maxTokens }) {
+async function callHaikuAPI(prompt, { timeout, maxTokens, temperature = DEFAULT_LLM_TEMPERATURE }) {
   const apiKey = process.env.ANTHROPIC_API_KEY;
   if (!apiKey) return null;
 
@@ -325,6 +334,7 @@ async function callHaikuAPI(prompt, { timeout, maxTokens }) {
     const body = {
       model: modelId,
       max_tokens: maxTokens,
+      temperature,
       messages: [{ role: 'user', content: user }],
     };
     // See callModelAPI: cache_control on the constant system slot.
@@ -365,7 +375,7 @@ async function callHaikuAPI(prompt, { timeout, maxTokens }) {
 // `cache_control` field has no OpenAI-format equivalent and is omitted.
 // `tier` is the resolved model tier ('haiku'|'sonnet'); OPENROUTER_MODEL can
 // override the resulting slug entirely (see resolveOpenRouterModel).
-async function callOpenRouterAPI(prompt, tier, { timeout, maxTokens }) {
+async function callOpenRouterAPI(prompt, tier, { timeout, maxTokens, temperature = DEFAULT_LLM_TEMPERATURE }) {
   const apiKey = process.env.OPENROUTER_API_KEY;
   if (!apiKey) return null;
 
@@ -387,7 +397,7 @@ async function callOpenRouterAPI(prompt, tier, { timeout, maxTokens }) {
         // Optional OpenRouter attribution headers (ignored by the API if absent).
         'X-Title': 'claude-mem-lite',
       },
-      body: JSON.stringify({ model, max_tokens: maxTokens, messages }),
+      body: JSON.stringify({ model, max_tokens: maxTokens, temperature, messages }),
       signal: controller.signal,
     });
 

package/hook-llm.mjs

@@ -12,6 +12,7 @@ import {
 import { acquireLLMSlot, releaseLLMSlot } from './hook-semaphore.mjs';
 import { scrubRecord } from './lib/scrub-record.mjs';
 import { getVocabulary, computeVector } from './tfidf.mjs';
+import { DEDUP_JACCARD_THRESHOLD, AUTO_MERGE_THRESHOLD } from './lib/dedup-constants.mjs';
 import {
   RUNTIME_DIR, DEDUP_WINDOW_MS, RELATED_OBS_WINDOW_MS,
   sessionFile, getSessionId, openDb, callLLM, sleep,
@@ -148,7 +149,7 @@ export function saveObservation(obs, projectOverride, sessionIdOverride, externa
       ORDER BY created_at_epoch DESC LIMIT 10
     `).all(project, fiveMinAgo);
 
-    if (obs.title && recent.some(r => jaccardSimilarity(r.title, obs.title) > 0.7)) {
+    if (obs.title && recent.some(r => jaccardSimilarity(r.title, obs.title) > DEDUP_JACCARD_THRESHOLD)) {
       return null; // dedup: Jaccard title match
     }
 
@@ -173,8 +174,8 @@ export function saveObservation(obs, projectOverride, sessionIdOverride, externa
         WHERE project = ? AND created_at_epoch > ? AND created_at_epoch <= ?
         ORDER BY created_at_epoch DESC LIMIT 60
       `).all(project, threeDaysAgo, fiveMinAgo);
-      if (extRecent.some(r => jaccardSimilarity(r.title, obs.title) > 0.85)) {
-        return null; // dedup: low-signal Jaccard match
+      if (extRecent.some(r => jaccardSimilarity(r.title, obs.title) > AUTO_MERGE_THRESHOLD)) {
+        return null; // dedup: low-signal Jaccard match (stricter cutoff for degraded titles)
       }
     }
 

package/hook-optimize.mjs

@@ -13,6 +13,7 @@ import { callModelJSON } from './haiku-client.mjs';
 import { acquireLLMSlot, releaseLLMSlot } from './hook-semaphore.mjs';
 import { scrubRecord } from './lib/scrub-record.mjs';
 import { getVocabulary, computeVector, cosineSimilarity } from './tfidf.mjs';
+import { MERGE_JACCARD_LOW, AUTO_MERGE_THRESHOLD } from './lib/dedup-constants.mjs';
 import { DB_DIR } from './schema.mjs';
 
 const RUNTIME_DIR = join(DB_DIR, 'runtime');
@@ -331,8 +332,9 @@ export async function executeNormalize(db, force = false, { project } = {}) {
 // ─── Task 3: Cluster-merge ─────────────────────────────────────────────────
 
 const MERGE_TIME_WINDOW_MS = 30 * 86400000;
-const MERGE_JACCARD_LOW = 0.4;
-const MERGE_JACCARD_HIGH = 0.85;
+// Merge-review band [MERGE_JACCARD_LOW, AUTO_MERGE_THRESHOLD): titles in this
+// Jaccard range are LLM-reviewed for merge; at/above AUTO_MERGE_THRESHOLD they'd
+// already auto-merge elsewhere, below MERGE_JACCARD_LOW they're too dissimilar.
 
 export function findMergeCandidates(db, maxClusters = 5, { project } = {}) {
   const cutoff = Date.now() - MERGE_TIME_WINDOW_MS;
@@ -363,12 +365,14 @@ export function findMergeCandidates(db, maxClusters = 5, { project } = {}) {
       if (Math.abs(rows[i].created_at_epoch - rows[j].created_at_epoch) > MERGE_TIME_WINDOW_MS) continue;
 
       if (rows[i].minhash_sig && rows[j].minhash_sig) {
+        // 0.8 slack: the MinHash estimate is noisy, so pre-filter a band below
+        // MERGE_JACCARD_LOW rather than at it, to avoid dropping true candidates.
         const est = estimateJaccardFromMinHash(rows[i].minhash_sig, rows[j].minhash_sig);
         if (est < MERGE_JACCARD_LOW * 0.8) continue;
       }
 
       const titleSim = jaccardSimilarity(rows[i].title, rows[j].title);
-      if (titleSim >= MERGE_JACCARD_LOW && titleSim < MERGE_JACCARD_HIGH) {
+      if (titleSim >= MERGE_JACCARD_LOW && titleSim < AUTO_MERGE_THRESHOLD) {
         cluster.push(rows[j]);
         used.add(rows[j].id);
       }

package/hook.mjs

@@ -26,7 +26,7 @@ import {
   truncate, inferProject, detectBashSignificance,
   extractErrorKeywords, extractFilePaths, isRelatedToEpisode,
   makeEntryDesc, scrubSecrets, stripPrivate, EDIT_TOOLS, debugCatch, debugLog,
-  COMPRESSED_AUTO, COMPRESSED_PENDING_PURGE, isoWeekKey, OBS_BM25,
+  COMPRESSED_AUTO, COMPRESSED_PENDING_PURGE, OBS_BM25,
   computeMinHash, estimateJaccardFromMinHash, jaccardSimilarity,
 } from './utils.mjs';
 import {
@@ -45,6 +45,8 @@ import {
 } from './hook-shared.mjs';
 import { handleLLMEpisode, handleLLMSummary, saveObservation, buildImmediateObservation } from './hook-llm.mjs';
 import { scrubRecord } from './lib/scrub-record.mjs';
+import { selectCompressionCandidates, groupByProjectWeek, compressGroup } from './lib/compress-core.mjs';
+import { cleanupBroken, decayAndMarkIdle, boostAccessed } from './lib/maintain-core.mjs';
 import {
   extractCitationsFromTranscript,
   extractAllInjected,
@@ -61,7 +63,8 @@ import { checkForUpdate, getCachedUpdateBanner, isUpdateCheckDue } from './hook-
 import { handleLLMOptimize } from './hook-optimize.mjs';
 import { silentAutoAdopt, hasAutoAdoptMarker } from './adopt-cli.mjs';
 import { emitV270UpgradeBanner } from './lib/upgrade-banner.mjs';
-import { loadCiteBackForEpisode, buildUnsavedBugfixHint, countUnsavedBugfixShape, buildCiteRecallNudge as libBuildCiteRecallNudge, nextCiteLowStreak } from './lib/cite-back-hint.mjs';
+import { loadCiteBackForEpisode, extractCiteBackSignals, buildUnsavedBugfixHint, countUnsavedBugfixShape, buildCiteRecallNudge as libBuildCiteRecallNudge, nextCiteLowStreak } from './lib/cite-back-hint.mjs';
+import { MINHASH_PREFILTER, FUZZY_DEDUP_THRESHOLD } from './lib/dedup-constants.mjs';
 // plugin-cache-guard.mjs loaded dynamically — pre-2.31.2 installs that auto-upgraded
 // from an older hook-update.mjs SOURCE_FILES (which did not list this module) would
 // crash on static import. Degrade gracefully to no-op when the module is absent.
@@ -540,6 +543,12 @@ async function handleStop() {
           // contract test in tests/citation-tracker-userprompt.test.mjs covers it.
           try {
             const injected = extractAllInjected(transcriptPath);
+            // P5 ①: cite-back signals — observations whose warned file the agent
+            // edited this session. Union into injected so they're resolved (they
+            // were injected via pre-tool-recall) and, below, into cited so the
+            // edit promotes them even without a literal #NN in text.
+            const citeBackIds = extractCiteBackSignals(transcriptPath);
+            for (const id of citeBackIds) injected.add(id);
             if (injected.size > 0) {
               // Text-floor gate: skip decay on tool-only Stops. Without this,
               // a turn that ends on tool_use locks every injected obs as
@@ -552,6 +561,7 @@ async function handleStop() {
                 debugLog('DEBUG', 'handleStop', `citation-decay: skipped (no main-thread assistant text yet, injected=${injected.size})`);
               } else {
                 const citedMain = extractCitationsFromTranscript(transcriptPath, { mainOnly: true });
+                for (const id of citeBackIds) citedMain.add(id);
                 const r = applyCitationDecay(db, project, injected, citedMain, sessionId);
                 debugLog('DEBUG', 'handleStop', `citation-decay: touched=${r.touched} promoted=${r.promoted} demoted=${r.demoted}`);
               }
@@ -819,65 +829,19 @@ async function handleSessionStart() {
         `).run(Date.now() - 37 * 86400000);
         if (purged.changes > 0) debugLog('DEBUG', 'auto-maintain', `purged ${purged.changes} stale observations`);
 
-        // Cleanup: remove broken observations (no title AND no narrative)
-        const cleaned = db.prepare(`
-          DELETE FROM observations WHERE id IN (
-            SELECT id FROM observations
-            WHERE COALESCE(compressed_into, 0) = 0
-              AND (title IS NULL OR title = '') AND (narrative IS NULL OR narrative = '')
-            LIMIT ${OP_CAP}
-          )
-        `).run();
-        if (cleaned.changes > 0) debugLog('DEBUG', 'auto-maintain', `cleaned ${cleaned.changes} broken observations`);
-
-        // Decay: reduce importance of old, never-accessed observations
-        // v2.56.0 #4: injection_count is a separate engagement signal —
-        // hook-memory.mjs bumps it when the obs is auto-injected into Claude's
-        // context. Pre-v2.56 only checked access_count, so an obs auto-injected
-        // 8x (proven contextually relevant) still got decayed/marked. Adding
-        // `injection_count = 0` treats injection as first-class engagement.
-        const decayed = db.prepare(`
-          UPDATE observations SET importance = MAX(1, COALESCE(importance, 1) - 1)
-          WHERE id IN (
-            SELECT id FROM observations
-            WHERE COALESCE(compressed_into, 0) = 0
-              AND COALESCE(importance, 1) > 1
-              AND COALESCE(access_count, 0) = 0
-              AND COALESCE(injection_count, 0) = 0
-              AND created_at_epoch < ?
-            LIMIT ${OP_CAP}
-          )
-        `).run(STALE_AGE);
-        if (decayed.changes > 0) debugLog('DEBUG', 'auto-maintain', `decayed ${decayed.changes} stale observations`);
-
-        // Mark idle: importance=1, never-accessed, never-injected, old → pending-purge
-        // (will be purged next cycle). v2.56.0 #4: injection_count protects.
-        const idleMarked = db.prepare(`
-          UPDATE observations SET compressed_into = ${COMPRESSED_PENDING_PURGE}
-          WHERE id IN (
-            SELECT id FROM observations
-            WHERE COALESCE(compressed_into, 0) = 0
-              AND COALESCE(importance, 1) = 1
-              AND COALESCE(access_count, 0) = 0
-              AND COALESCE(injection_count, 0) = 0
-              AND created_at_epoch < ?
-            LIMIT ${OP_CAP}
-          )
-        `).run(STALE_AGE);
-        if (idleMarked.changes > 0) debugLog('DEBUG', 'auto-maintain', `marked ${idleMarked.changes} idle as pending-purge`);
-
-        // Boost: increase importance of frequently-accessed observations
-        const boosted = db.prepare(`
-          UPDATE observations SET importance = MIN(3, COALESCE(importance, 1) + 1)
-          WHERE id IN (
-            SELECT id FROM observations
-            WHERE COALESCE(compressed_into, 0) = 0
-              AND COALESCE(access_count, 0) > 3
-              AND COALESCE(importance, 1) < 3
-            LIMIT ${OP_CAP}
-          )
-        `).run();
-        if (boosted.changes > 0) debugLog('DEBUG', 'auto-maintain', `boosted ${boosted.changes} frequently-accessed observations`);
+        // cleanup / decay+mark-idle / boost via maintain-core (shared with CLI + MCP).
+        // injection_count>0 protection lives in decayAndMarkIdle. Whole-DB, cap 500.
+        const mctx = { projectFilter: '', baseParams: [], staleAge: STALE_AGE, opCap: OP_CAP };
+
+        const cleaned = cleanupBroken(db, mctx);
+        if (cleaned > 0) debugLog('DEBUG', 'auto-maintain', `cleaned ${cleaned} broken observations`);
+
+        const { decayed, idleMarked } = decayAndMarkIdle(db, mctx);
+        if (decayed > 0) debugLog('DEBUG', 'auto-maintain', `decayed ${decayed} stale observations`);
+        if (idleMarked > 0) debugLog('DEBUG', 'auto-maintain', `marked ${idleMarked} idle as pending-purge`);
+
+        const boosted = boostAccessed(db, mctx);
+        if (boosted > 0) debugLog('DEBUG', 'auto-maintain', `boosted ${boosted} frequently-accessed observations`);
 
         // Auto-dedup (exact): merge identical-title observations within 1h.
         // Catches rapid duplicate writes (same hook firing twice, race conditions).
@@ -908,8 +872,6 @@ async function handleSessionStart() {
         if (!process.env.CLAUDE_MEM_SKIP_AUTO_DEDUP_FUZZY) {
           const SCAN_LIMIT = 500;
           const FUZZY_MAX_MERGES = 20;
-          const FUZZY_THRESHOLD = 0.95;
-          const MINHASH_PREFILTER = 0.7;
           const recent = db.prepare(`
             SELECT id, title, importance, created_at_epoch
             FROM observations
@@ -929,7 +891,7 @@ async function handleSessionStart() {
               for (let j = i + 1; j < recent.length; j++) {
                 if (!minhashes[j] || removed.has(recent[j].id)) continue;
                 if (estimateJaccardFromMinHash(minhashes[i], minhashes[j]) < MINHASH_PREFILTER) continue;
-                if (jaccardSimilarity(titles[i], titles[j]) < FUZZY_THRESHOLD) continue;
+                if (jaccardSimilarity(titles[i], titles[j]) < FUZZY_DEDUP_THRESHOLD) continue;
                 // Keep the higher-importance row; tiebreak by older (lower id wins access history)
                 const keep = (recent[i].importance ?? 1) >= (recent[j].importance ?? 1) ? recent[i] : recent[j];
                 const remove = keep === recent[i] ? recent[j] : recent[i];
@@ -1361,57 +1323,16 @@ function handleAutoCompress() {
 
   try {
     const compressCutoff = Date.now() - 60 * 86400000; // 60 days
-    const compressCandidates = db.prepare(`
-      SELECT id, project, type, title, created_at_epoch
-      FROM observations
-      WHERE COALESCE(importance, 1) = 1 AND COALESCE(access_count, 0) = 0
-        AND created_at_epoch < ?
-        AND (compressed_into IS NULL OR compressed_into = ${COMPRESSED_AUTO})
-      ORDER BY project, created_at_epoch
-    `).all(compressCutoff);
+    const compressCandidates = selectCompressionCandidates(db, { cutoff: compressCutoff, includeAutoMarked: true });
     if (compressCandidates.length < 3) return;
 
-    const groups = new Map();
-    for (const c of compressCandidates) {
-      const key = `${c.project}::${isoWeekKey(c.created_at_epoch)}`;
-      if (!groups.has(key)) groups.set(key, []);
-      groups.get(key).push(c);
-    }
-    // Transact each group to prevent orphan summaries on crash
-    const compressGroup = db.transaction((proj, obs) => {
-      const types = {};
-      for (const o of obs) types[o.type] = (types[o.type] || 0) + 1;
-      const dominantType = Object.entries(types).sort((a, b) => b[1] - a[1])[0][0];
-      const title = `Weekly summary: ${obs.length} ${dominantType} observations`;
-      const narrative = obs.map(o => `- ${o.title || '(untitled)'}`).join('\n');
-      const sortedEpochs = obs.map(o => o.created_at_epoch).sort((a, b) => a - b);
-      const medianEpoch = sortedEpochs[Math.floor(sortedEpochs.length / 2)];
-      const sessionId = `compress-${proj}`;
-      const now = new Date();
-      db.prepare(`INSERT OR IGNORE INTO sdk_sessions
-        (content_session_id, memory_session_id, project, started_at, started_at_epoch, status)
-        VALUES (?,?,?,?,?,'active')`
-      ).run(sessionId, sessionId, proj, now.toISOString(), now.getTime());
-      // Defense-in-depth: title/narrative are derived from already-stored
-      // obs.title, but those rows pre-date the central scrub policy in some
-      // cases. Re-scrub at the persistence boundary.
-      const safe = scrubRecord('observations', { text: narrative, title, narrative });
-      const summaryResult = db.prepare(`INSERT INTO observations
-        (memory_session_id, project, text, type, title, subtitle, narrative, concepts, facts,
-         files_read, files_modified, importance, created_at, created_at_epoch)
-        VALUES (?,?,?,?,?,'',?,'','','[]','[]',2,?,?)`
-      ).run(sessionId, proj, safe.text, dominantType, safe.title, safe.narrative, new Date(medianEpoch).toISOString(), medianEpoch);
-      const summaryId = Number(summaryResult.lastInsertRowid);
-      const obsIds = obs.map(o => o.id);
-      db.prepare(`UPDATE observations SET compressed_into = ? WHERE id IN (${obsIds.map(() => '?').join(',')})`)
-        .run(summaryId, ...obsIds);
-      return obs.length;
-    });
+    const groups = groupByProjectWeek(compressCandidates);
+    // Transact each group to prevent orphan summaries on crash (CLI/MCP wrap all groups in one).
+    const compressGroupTxn = db.transaction((proj, obs) => compressGroup(db, proj, obs).compressed);
     let totalCompressed = 0;
     for (const [key, obs] of groups) {
-      if (obs.length < 3) continue;
       const [proj] = key.split('::');
-      totalCompressed += compressGroup(proj, obs);
+      totalCompressed += compressGroupTxn(proj, obs);
     }
     if (totalCompressed > 0) {
       debugLog('DEBUG', 'auto-compress', `auto-compressed ${totalCompressed} observations into weekly summaries`);

package/lib/citation-tracker.mjs

@@ -387,6 +387,42 @@ const IMPORTANCE_CAP = 3;
 const IMPORTANCE_FLOOR = 0;
 const UNCITED_STREAK_THRESHOLD = 3;
 
+// Adoption-rate gate (P5 ②). A project's cite-rate is SUM(cited_count) /
+// SUM(decay_seen_count) over its non-superseded observations: of every decay
+// resolution this project has ever produced, what fraction were citations.
+// Below ADOPTION_THRESHOLD with at least ADOPTION_MIN_SEEN resolutions on record,
+// the project has demonstrably not adopted the #NN convention, so we suppress
+// DEMOTION (never promotion) — see the construct-validity note on
+// applyCitationDecay. MIN_SEEN keeps the gate dormant for low-data projects so
+// the established behavior is preserved until there's enough signal to judge.
+const ADOPTION_THRESHOLD = 0.02;
+const ADOPTION_MIN_SEEN = 8;
+
+/**
+ * Compute a project's citation-adoption snapshot: total citations vs total decay
+ * resolutions on record, and their ratio. Read-only; safe to call before the
+ * decay transaction (the gate decision is made on the pre-mutation snapshot).
+ *
+ * @param {import('better-sqlite3').Database} db
+ * @param {string} project
+ * @returns {{cited: number, seen: number, rate: number}}
+ */
+export function computeCitationAdoption(db, project) {
+  const empty = { cited: 0, seen: 0, rate: 0 };
+  if (!db || !project) return empty;
+  try {
+    const row = db.prepare(`
+      SELECT COALESCE(SUM(cited_count), 0)       AS cited,
+             COALESCE(SUM(decay_seen_count), 0)  AS seen
+        FROM observations
+       WHERE project = ? AND superseded_at IS NULL
+    `).get(project);
+    const cited = row?.cited || 0;
+    const seen = row?.seen || 0;
+    return { cited, seen, rate: seen > 0 ? cited / seen : 0 };
+  } catch (e) { debugCatch(e, 'computeCitationAdoption'); return empty; }
+}
+
 /**
  * Apply the citation-feedback loop for one session: for each injected obs id,
  * decide cited vs uncited and mutate importance/streak/cited_count per spec.
@@ -398,6 +434,20 @@ const UNCITED_STREAK_THRESHOLD = 3;
  * - cross-project IDs are silently ignored by the WHERE clause.
  * - MEM_DISABLE_CITATION_DECAY=1 disables all writes; returns zeros.
  *
+ * CONSTRUCT-VALIDITY ASSUMPTION (P5): a "citation" is operationally two signals,
+ * neither of which is ground-truth behavioral impact:
+ *   1. the literal `#NN` token appears in main-thread assistant text (citedIds), and
+ *   2. (cite-back) the agent edited a file a prior lesson #NN had warned about —
+ *      unioned into citedIds by the Stop handler before this call.
+ * Signal 2 was added because signal 1 alone penalizes projects that act on a
+ * lesson without typing its id. Even so, both are proxies. For a project that has
+ * never cited anything (cite-rate below ADOPTION_THRESHOLD over ≥ADOPTION_MIN_SEEN
+ * resolutions), demotion is suppressed: absent any positive signal we cannot
+ * distinguish "useless lesson" from "useful lesson in a project that doesn't use
+ * the #NN convention," and a false demotion is the costlier error. The gate trades
+ * missed demotions (stale lessons linger) for avoided false demotions. Promotion
+ * is never gated — a single citation lifts the project's rate and re-enables decay.
+ *
  * @param {import('better-sqlite3').Database} db
  * @param {string} project
  * @param {Set<number>|Iterable<number>} injectedIds
@@ -413,6 +463,13 @@ export function applyCitationDecay(db, project, injectedIds, citedIds, sessionId
   if (injected.size === 0) return empty;
   const cited = citedIds instanceof Set ? citedIds : new Set(citedIds || []);
 
+  // Adoption gate (snapshot taken before any mutation this run). Suppress only
+  // demotion; promotion always proceeds. Threshold overridable via env.
+  const adoption = computeCitationAdoption(db, project);
+  const envThreshold = Number.parseFloat(process.env.CLAUDE_MEM_CITATION_ADOPTION_THRESHOLD);
+  const adoptionThreshold = Number.isFinite(envThreshold) && envThreshold >= 0 ? envThreshold : ADOPTION_THRESHOLD;
+  const suppressDemotion = adoption.seen >= ADOPTION_MIN_SEEN && adoption.rate < adoptionThreshold;
+
   const selectStmt = db.prepare(
     'SELECT id, importance, uncited_streak, last_decided_session_id FROM observations WHERE id = ? AND project = ?'
   );
@@ -457,7 +514,10 @@ export function applyCitationDecay(db, project, injectedIds, citedIds, sessionId
         promoted++;
       } else {
         const nextStreak = (row.uncited_streak || 0) + 1;
-        if (nextStreak >= UNCITED_STREAK_THRESHOLD) {
+        // Demote only when the streak is up AND the project has demonstrably
+        // adopted citations. A non-adopting project advances the streak (idempotent
+        // bookkeeping) but never loses importance — see construct-validity note.
+        if (nextStreak >= UNCITED_STREAK_THRESHOLD && !suppressDemotion) {
           updateDemote.run(IMPORTANCE_FLOOR, sessionId, Date.now(), id);
           demoted++;
         } else {

package/lib/cite-back-hint.mjs

@@ -17,6 +17,11 @@ import { EDIT_TOOLS } from '../utils.mjs';
 
 const MAX_FILES = 2;
 
+// Leader literal for the cite-back hint. Shared by the builder (below) and the
+// Stop-time signal extractor (extractCiteBackSignals) so the two can never drift
+// — the extractor finds hint emissions by this exact prefix.
+const CITE_BACK_HINT_LEADER = '[mem] ⚠ Cite-back:';
+
 export function buildCiteBackHint(episode, cooldown) {
   if (!episode || !cooldown) return null;
   const entries = episode.entries;
@@ -48,7 +53,7 @@ export function buildCiteBackHint(episode, cooldown) {
   // numeric framing is measurably harder to dismiss than a hedged hint.
   const totalLessons = matches.reduce((sum, m) => sum + m.ids.length, 0);
   const lines = [
-    `[mem] ⚠ Cite-back: edited ${matches.length} file(s) with ${totalLessons} prior lesson(s) this session. Save now if any was the root cause:`,
+    `${CITE_BACK_HINT_LEADER} edited ${matches.length} file(s) with ${totalLessons} prior lesson(s) this session. Save now if any was the root cause:`,
   ];
   for (const m of matches) {
     const fname = basename(m.file);
@@ -242,3 +247,36 @@ export function loadCiteBackForEpisode(episode, runtimeDir) {
   }
   return buildCiteBackHint(episode, cooldown);
 }
+
+// ─── extractCiteBackSignals (P5 ①) ──────────────────────────────────────────
+// Stop-time positive-citation signal. Scans the transcript for cite-back hint
+// emissions (PostToolUse attachment.stdout carrying CITE_BACK_HINT_LEADER — the
+// same source countUnsavedBugfixShape reads) and collects the `#NN` lesson ids
+// they name. Each id is an observation whose warned file the agent actually
+// EDITED this session — a behavioral citation even when the agent never typed
+// #NN. The Stop handler unions these into the cited set passed to
+// applyCitationDecay (lib/citation-tracker.mjs), so acting on a lesson promotes
+// it and lifts the project's adoption rate. Returns an empty set on missing path.
+const CITE_BACK_ID_RE = /#(\d{1,7})\b/g;
+
+export function extractCiteBackSignals(transcriptPath) {
+  const ids = new Set();
+  if (!transcriptPath || !existsSync(transcriptPath)) return ids;
+  let raw;
+  try { raw = readFileSync(transcriptPath, 'utf8'); } catch { return ids; }
+  for (const line of raw.split('\n')) {
+    if (!line.trim()) continue;
+    let entry;
+    try { entry = JSON.parse(line); } catch { continue; }
+    if (entry.type !== 'attachment') continue;
+    const stdout = entry.attachment?.stdout || '';
+    if (!stdout.includes(CITE_BACK_HINT_LEADER)) continue;
+    CITE_BACK_ID_RE.lastIndex = 0;
+    let m;
+    while ((m = CITE_BACK_ID_RE.exec(stdout))) {
+      const id = Number(m[1]);
+      if (Number.isInteger(id) && id > 0 && id < 1e7) ids.add(id);
+    }
+  }
+  return ids;
+}