claude-mem-lite 3.13.0 → 3.15.0

package/.claude-plugin/marketplace.json

@@ -10,7 +10,7 @@
   "plugins": [
     {
       "name": "claude-mem-lite",
-      "version": "3.13.0",
+      "version": "3.15.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. 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": "3.13.0",
+  "version": "3.15.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

@@ -299,10 +299,15 @@ surface — reach them through the CLI column in the second table.
 
 ### Invited Memory (v2.32+)
 
-Opt-in mechanism that installs a single sentinel-wrapped line into the project's
-memdir (`~/.claude/projects/<encoded>/memory/MEMORY.md`) so Claude Code loads
-the plugin's MCP-tool triggers as **user-memory** — a higher instruction-following
-authority than MCP server instructions (which are framed as tool metadata).
+Opt-in mechanism that installs a slug-scoped managed block into the project's
+own `CLAUDE.md` (plus an on-demand detail doc under `.claude/`) so Claude Code
+loads the plugin's MCP-tool triggers as **project instructions** — a higher
+instruction-following authority than MCP server instructions (which are framed
+as tool metadata). Claude Code loads `CLAUDE.md` and the memdir `MEMORY.md` at
+equal weight, so steering lives in `CLAUDE.md` (the canonical home for project
+instructions) rather than polluting `MEMORY.md`, which is reserved for the user's
+own memories. The pre-v3.13 scheme wrote into `MEMORY.md`; it is migrated away
+automatically on the next SessionStart.
 
 ```bash
 claude-mem-lite adopt              # install for current project
@@ -317,30 +322,38 @@ claude-mem-lite unadopt            # remove sentinel + doc (runtime marker stays
 Slash commands `/adopt` and `/unadopt` wrap the same CLI.
 
 **What adoption changes:**
-- A `<!-- claude-mem-lite:begin v1 -->…<!-- claude-mem-lite:end -->` block is
-  added to `MEMORY.md` under a `## 插件契约` header, containing one ≤150-char
-  line pointing at `mem_recall` / `mem_save` with their key arguments.
-- A `plugin_claude_mem_lite.md` detail file is written (not auto-loaded; read
-  on demand when the MEMORY.md pointer surfaces in context).
+- A `<!-- claude-mem-lite:begin v1 -->…<!-- claude-mem-lite:end -->` managed
+  block is added to `<cwd>/CLAUDE.md` under its own
+  `## claude-mem-lite — persistent memory` header, containing a compact trigger
+  table pointing at `mem_recall` / `mem_save` / `mem_defer` with their key
+  arguments. The block is slug-scoped: only this region is managed; the rest of
+  your `CLAUDE.md` is preserved verbatim, and it coexists with other plugins'
+  blocks (e.g. `code-graph-mcp`) in the same file.
+- A `<cwd>/.claude/plugin_claude_mem_lite.md` detail file is written (not
+  auto-loaded; read on demand when the `CLAUDE.md` block points to it). The
+  block auto-refreshes when the shipped content drifts (version bump or template
+  change), unless `CLAUDE_MEM_NO_TEMPLATE_REFRESH=1`.
 - Post-adopt the conservative hook layer auto-trims: MCP server instructions
   drop the `WHEN TO USE` section, SessionStart injection drops the `File Lessons`
   / `Key Context` sections. `#ID` references and the `Recent` table still fire
   so `mem_get` remains reachable.
 
 **When does it take effect?**
-- The MEMORY.md sentinel and the hook-layer trim (`File Lessons` / `Key Context` /
-  lesson suffix) apply on the **next SessionStart** (any new Claude Code session
-  in the adopted project).
+- The `CLAUDE.md` managed block and the hook-layer trim (`File Lessons` /
+  `Key Context` / lesson suffix) apply on the **next SessionStart** (any new
+  Claude Code session in the adopted project).
 - The MCP server instructions are built once at server boot and MCP has no
   "push" protocol — the `WHEN TO USE` / `Decision rules` trim only applies
   after Claude Code restarts and re-spawns the mem-lite MCP server. A single
   `/exit` + fresh session is enough. Same caveat applies to `unadopt`.
 
 **Safety:**
-- Hash-guarded: editing the sentinel body yourself blocks automatic rewrites
-  unless you pass `--force`.
-- Budget-gated: refuses to insert when MEMORY.md is already >180 lines, so
-  Claude Code's 200-line MEMORY.md cap won't truncate the block.
+- Hash-guarded: editing the managed-block body yourself blocks automatic
+  rewrites unless you pass `--force`.
+- Slug-scoped & dedup-guarded: only the `claude-mem-lite:begin…end` region is
+  ever rewritten, and duplicate / CRLF-orphaned copies are collapsed to one.
+  Unlike the legacy `MEMORY.md` scheme there is no line-budget gate — `CLAUDE.md`
+  has no truncation cap.
 - **Auto-adopt fires on the first SessionStart per project for any install
   path (v2.82.1+).** Per-project opt-out: `claude-mem-lite adopt --disable`
   (writes a durable `<memdir>/.mem-no-auto-adopt` sentinel that survives marker

package/adopt-cli.mjs

@@ -13,9 +13,9 @@
 // it is redefined as a legacy-cleanup sweep (strip old memory-dir sentinels across
 // every memdir). New-scheme adoption happens per-project on SessionStart (cwd known).
 
-import { existsSync, readdirSync, statSync, mkdirSync, writeFileSync, unlinkSync } from 'fs';
+import { existsSync, readdirSync, statSync, mkdirSync, writeFileSync, unlinkSync, readFileSync } from 'fs';
 import { homedir } from 'os';
-import { join } from 'path';
+import { join, isAbsolute } from 'path';
 import {
   memdirPath, removePluginSection, removePluginDoc,
   isAdopted as memdirIsAdopted, hasPluginState,
@@ -54,6 +54,25 @@ function listAllMemdirs() {
   return out;
 }
 
+function claudeConfigPath() { return join(homedir(), '.claude.json'); }
+
+// Real adopted-project paths come from Claude Code's own ~/.claude.json `projects`
+// map (keys are absolute cwds Claude Code has opened). The memdir slug under
+// ~/.claude/projects/ is a LOSSY encoding that can't be decoded back to a path,
+// so this is the only source that lets `unadopt --all` reach scattered CLAUDE.md
+// managed blocks. Filtered to absolute, still-existing dirs; claudeMdIsAdopted()
+// then gates which actually carry our block. Caveat: a project Claude Code never
+// recorded is invisible here and needs a per-project `unadopt`.
+function listKnownProjectDirs() {
+  const p = claudeConfigPath();
+  if (!existsSync(p)) return [];
+  try {
+    const cfg = JSON.parse(readFileSync(p, 'utf8'));
+    const projects = cfg && cfg.projects && typeof cfg.projects === 'object' ? Object.keys(cfg.projects) : [];
+    return projects.filter((d) => typeof d === 'string' && isAbsolute(d) && existsSync(d));
+  } catch { return []; }
+}
+
 function hasFlag(args, flag) { return Array.isArray(args) && args.includes(flag); }
 
 // ─── Per-project auto-adopt opt-out sentinel ─────────────────────────────────
@@ -290,6 +309,12 @@ function statusAll() {
   log(`[adopt --status] scanned ${dirs.length} memdir(s): ${legacy} with legacy sentinel (await migration), ${disabled} auto-adopt-disabled.`);
   if (legacy > 0) log('[adopt --status] run `claude-mem-lite adopt --all` to sweep legacy memory-dir sentinels now.');
 
+  const known = listKnownProjectDirs();
+  let adoptedCount = 0;
+  for (const dir of known) if (claudeMdIsAdopted(dir, PLUGIN_SLUG)) adoptedCount++;
+  log(`[adopt --status] known projects (~/.claude.json): ${known.length} scanned, ${adoptedCount} with a CLAUDE.md managed block.`);
+  if (adoptedCount > 0) log('[adopt --status] run `claude-mem-lite unadopt --all` to remove every CLAUDE.md block.');
+
   const pluginRoot = process.env.CLAUDE_PLUGIN_ROOT ? 'set' : 'unset';
   const noAutoAdopt = process.env.MEM_NO_AUTO_ADOPT === '1' ? '1 (opt-out)' : 'unset';
   log('');
@@ -305,6 +330,54 @@ function statusAll() {
  * memory-dir cleanup across every memdir (CLAUDE.md blocks for other projects
  * can't be located from the lossy slug). Idempotent: exit code stays 0.
  */
+/**
+ * unadoptAll — `claude-mem-lite unadopt --all`. Removes the CLAUDE.md managed
+ * block + detail doc from EVERY adopted project Claude Code knows about (real
+ * paths from ~/.claude.json `projects`), then sweeps the legacy memory-dir
+ * residue across all memdirs. removeManaged is slug-scoped, so user content and
+ * other plugins' blocks are never touched. Honors --dry-run / --force.
+ *
+ * Unlike `adopt --all` (still a legacy-only sweep — adopting arbitrary projects
+ * is unsafe), unadopt is purely subtractive, so reaching every known project is
+ * both safe and what the uninstall hint promises.
+ */
+function unadoptAll(args) {
+  const force = hasFlag(args, '--force');
+  const dryRun = hasFlag(args, '--dry-run');
+
+  // 1. New scheme: scrub CLAUDE.md managed blocks across known project paths.
+  const projectDirs = listKnownProjectDirs();
+  let blocks = 0;
+  for (const dir of projectDirs) {
+    if (!claudeMdIsAdopted(dir, PLUGIN_SLUG)) continue;
+    if (dryRun) {
+      log(`[unadopt --all --dry-run] ${dir} → would-remove CLAUDE.md block + detail doc`);
+      blocks++;
+      continue;
+    }
+    const r = removeManaged(dir, PLUGIN_SLUG);
+    if (r.action === 'removed') { log(`[unadopt --all] ${dir} → removed`); blocks++; }
+  }
+
+  // 2. Legacy memory-dir cleanup across every memdir (foreign-content guarded).
+  const dirs = listAllMemdirs();
+  let legacy = 0;
+  for (const { memdir } of dirs) {
+    if (dryRun) {
+      if (memdirIsAdopted(memdir, PLUGIN_SLUG) && (hasPluginState(memdir, PLUGIN_SLUG) || force)) legacy++;
+      continue;
+    }
+    const r = removePluginSection(memdir, PLUGIN_SLUG, { force });
+    if (r.action === 'removed') { removePluginDoc(memdir, PLUGIN_SLUG); legacy++; }
+  }
+
+  log('');
+  log(`[unadopt --all] ${dryRun ? 'would remove' : 'removed'} ${blocks} CLAUDE.md block(s) across ${projectDirs.length} known project(s); ${legacy} legacy memory-dir sentinel(s) ${dryRun ? 'pending' : 'cleaned'}.`);
+  if (projectDirs.length === 0) {
+    log('[unadopt --all] no known projects found in ~/.claude.json — if a project was adopted but never opened in Claude Code, run `claude-mem-lite unadopt` from inside it.');
+  }
+}
+
 export function cmdUnadopt(args = []) {
   if (hasFlag(args, '--status')) return statusAll();
 
@@ -312,7 +385,7 @@ export function cmdUnadopt(args = []) {
   const dryRun = hasFlag(args, '--dry-run');
   const force = hasFlag(args, '--force');
 
-  if (all) return migrateAll(['--all', ...(force ? ['--force'] : []), ...(dryRun ? ['--dry-run'] : [])]);
+  if (all) return unadoptAll(args);
 
   const cwd = detectCwd();
   if (dryRun) {

package/adopt-content.mjs

@@ -3,16 +3,21 @@
 // <cwd>/.claude/plugin_claude_mem_lite.md detail doc. Kept separate from the
 // claudemd.mjs primitives so the strings are testable without side effects.
 //
-// Bumping CURRENT_SENTINEL_VERSION: pick the next vN. On the next SessionStart
-// needsRefresh() sees the version change and refreshes the block in place
-// (version bump = intended content change, so it overwrites rather than treating
-// the drift as a user edit). v1 = legacy memory-dir sentinel (now migrated away);
-// v2 = project-tree CLAUDE.md managed block.
+// CURRENT_SENTINEL_VERSION tags the managed block as `<!-- claude-mem-lite:begin
+// vN -->`. needsRefresh() only checks for *inequality* against the installed tag,
+// so any change triggers an in-place refresh (version change = intended content
+// change, overwritten rather than treated as a user edit) — the value need not be
+// monotonic. We deliberately use `v1` (not `v2`) so the version digit differs from
+// the sibling code-graph-mcp plugin's `<!-- code-graph-mcp:begin v2 -->` block in
+// the same CLAUDE.md; the slug already scopes the two independently (claudemd.mjs),
+// so this is a cosmetic distinguisher, not a functional one. The pre-v3.13 legacy
+// memory-dir MEMORY.md sentinel also carried `v1`, but it lives in a different file
+// and is migrated away (claudemd.migrateLegacyMemoryDir), so there is no collision.
 
 import { CLI_INVOKE } from './cli-path.mjs';
 
 export const PLUGIN_SLUG = 'claude-mem-lite';
-export const CURRENT_SENTINEL_VERSION = 'v2';
+export const CURRENT_SENTINEL_VERSION = 'v1';
 
 /**
  * The concise managed block injected into <cwd>/CLAUDE.md (between the
@@ -26,19 +31,19 @@ export function buildClaudeMdBlock() {
   // resolves to an absolute path that differs per install — it would make this
   // committed/refreshed block churn across machines). The robust CLI table lives
   // in the detail doc (.claude/, gitignored).
-  return `## claude-mem-lite — 持久记忆 (persistent memory)
+  return `## claude-mem-lite — persistent memory
 
-PreToolUse hooks 在 Read/Edit/Write 前已自动 \`mem_recall\` 过往教训。下面是值得你主动发起的调用：
+PreToolUse hooks already run \`mem_recall\` for past lessons before Read/Edit/Write. The calls worth making proactively:
 
-| 时机 | 调用 |
+| When | Call |
 |------|------|
-| Edit/Write 前 | hook 已自动 recall；若注入了 \`#NN\` 教训，下次产出用户可见文字时引用 \`#NN\`（引用=采纳反馈，未引用会衰减） |
-| 解决非平凡 bug 后 | \`mem_save(type="bugfix", lesson_learned="<根因+修法>", importance=2)\` |
-| 非显然架构决策后 | \`mem_save(type="decision", lesson_learned="<约束+取舍>")\` |
-| 推迟到下个会话 | \`mem_defer({title, priority:1|2|3, detail})\`；修好时给 \`mem_save\` 加 \`closes_deferred=[N]\` |
-| 查过往工作 / 历史 | \`mem_search "关键词"\` · \`mem_recent\` · \`mem_timeline\` |
+| Before Edit/Write | hook already recalled; if a \`#NN\` lesson was injected, cite \`#NN\` next time you produce user-visible text (citing = adopting the feedback; uncited lessons decay) |
+| After fixing a non-trivial bug | \`mem_save(type="bugfix", lesson_learned="<root cause + fix>", importance=2)\` |
+| After a non-obvious architecture decision | \`mem_save(type="decision", lesson_learned="<constraint + tradeoff>")\` |
+| Deferring to a future session | \`mem_defer({title, priority:1|2|3, detail})\`; when fixed, add \`closes_deferred=[N]\` to \`mem_save\` |
+| Looking up past work / history | \`mem_search "keywords"\` · \`mem_recent\` · \`mem_timeline\` |
 
-完整工具+CLI 表、citation/decay 规则、save 纪律见 → \`.claude/plugin_claude_mem_lite.md\``;
+Full tool + CLI tables, citation/decay rules, and save discipline → \`.claude/plugin_claude_mem_lite.md\``;
 }
 
 /**

package/bash-utils.mjs

@@ -76,7 +76,14 @@ export function detectBashSignificance(input, response) {
   // Allow intervening global git options (`-C <path>`, `-c k=v`, `--no-pager`, …) between
   // `git` and the subcommand — `git -C /repo push` is the standard multi-repo/scripted form.
   const isGit = /\bgit\s+(?:(?:-[cC]\s+\S+|--?[\w-]+(?:=\S+)?)\s+)*(commit|merge|rebase|cherry-pick|push)\b/i.test(cmd);
-  const isDeploy = /\b(deploy|docker|kubectl|terraform)\b/i.test(cmd);
+  // Deploy + publish/release: the actual "ship". Package publish and GitHub
+  // release are rare, high-value events; without them a release session records
+  // the git push but not the publish that defines it. `npm run publish-*` is
+  // excluded (custom script, ambiguous) — only the direct publish verb counts.
+  const isDeploy = /\b(deploy|docker|kubectl|terraform)\b/i.test(cmd)
+    || /\b(?:npm|pnpm|yarn|bun|cargo)\s+publish\b/i.test(cmd)
+    || /\bgh\s+release\s+(?:create|edit|upload|delete)\b/i.test(cmd)
+    || /\btwine\s+upload\b/i.test(cmd);
   return {
     isError, isTest, isBuild, isGit, isDeploy,
     isSignificant: isError || isTest || isBuild || isGit || isDeploy,

package/commands/adopt.md

@@ -16,7 +16,7 @@ force it immediately (e.g. after editing the block out by hand).
 
 ## What it writes
 
-1. **`<cwd>/CLAUDE.md`** — a concise `<!-- claude-mem-lite:begin v2 -->…<!-- :end -->`
+1. **`<cwd>/CLAUDE.md`** — a concise `<!-- claude-mem-lite:begin v1 -->…<!-- :end -->`
    managed block (trigger table → `mem_recall` / `mem_save` / `mem_defer`).
    Slug-scoped: only this block is managed; the rest of your `CLAUDE.md` is
    preserved verbatim. Auto-refreshes when the shipped content drifts.

package/commands/unadopt.md

@@ -1,6 +1,6 @@
 ---
 name: unadopt
-description: "Use when: user wants to remove the claude-mem-lite steering block from the current project (or sweep legacy memory-dir sentinels everywhere with --all). Removes the <cwd>/CLAUDE.md managed block + <cwd>/.claude/plugin_claude_mem_lite.md and cleans any legacy memory-dir residue. User content outside the sentinel is preserved. Benign no-op when not adopted."
+description: "Use when: user wants to remove the claude-mem-lite steering block from the current project (or from every project Claude Code knows about with --all). Removes the <cwd>/CLAUDE.md managed block + <cwd>/.claude/plugin_claude_mem_lite.md and cleans any legacy memory-dir residue. User content outside the sentinel is preserved. Benign no-op when not adopted."
 ---
 
 # /unadopt
@@ -24,9 +24,11 @@ project (slug-scoped — other plugins' blocks survive).
 
 - `--force` — also remove a legacy memory-dir block lacking a state sidecar
 - `--dry-run` — preview what would be removed; no writes
-- `--all` — legacy-cleanup sweep: strip the old memory-dir sentinel across every
-  project (CLAUDE.md blocks for other projects can't be located from the encoded
-  slug — `cd` into a project and run `/unadopt` there to remove its block).
+- `--all` — remove the CLAUDE.md managed block from every project in Claude
+  Code's known-project list (`~/.claude.json` `projects`), plus sweep any legacy
+  memory-dir sentinels. Slug-scoped, so user content and other plugins' blocks
+  survive. A project Claude Code never opened isn't listed — `cd` into it and run
+  `/unadopt` there. Pair with `--dry-run` to preview.
 - `--status` — read-only adoption probe (mirrors `/adopt --status`)
 
 ## Note: this does not stop auto-adopt

package/hook-memory.mjs

@@ -131,7 +131,23 @@ function hasFilePaths(filesModified) {
  * @returns {object[]} Top memories (max 3) with {id, type, title, lesson_learned}
  */
 export function searchRelevantMemories(db, userPrompt, project, excludeIds = []) {
-  if (!db || !userPrompt || userPrompt.length < 5) return [];
+  // Min-length guard is English-centric: 5 chars ≈ one short English word. A CJK
+  // query is meaningful at 2 chars (状态/架构) and most real Chinese queries are
+  // 2-4 chars (状态管理, 召回率, 熔断降级) — the bare `.length < 5` silently
+  // rejected ALL of them, so a Chinese-primary user got zero memory injection.
+  // Apply the 5-char floor only to non-CJK queries; CJK needs ≥2.
+  if (!db || !userPrompt) return [];
+  const queryHasCjk = /[一-鿿㐀-䶿]/.test(userPrompt);
+  if (userPrompt.length < (queryHasCjk ? 2 : 5)) return [];
+  // CJK-DOMINANT (not merely CJK-containing) gates the OR-fallback bypass below.
+  // A substring test would let one incidental CJK char — an IME-leaked particle,
+  // a 中文 noun in an otherwise-English prompt — flip OR-fallback on and inject
+  // off-topic noise (a real precision regression for bilingual users). Require
+  // CJK chars to be at least as many as ASCII letters so only genuinely-Chinese
+  // queries (优化召回率) get the bigram-inflation rescue, not "fix the bug 啊".
+  const _cjkChars = (userPrompt.match(/[一-鿿㐀-䶿]/g) || []).length;
+  const _asciiLetters = (userPrompt.match(/[A-Za-z]/g) || []).length;
+  const queryIsCjkDominant = _cjkChars > 0 && _cjkChars >= _asciiLetters;
 
   // v2.41 metrics: record timing + candidate/filter/return counts per call.
   // Gated by CLAUDE_MEM_METRICS=1 — no-op when disabled (zero hot-path cost).
@@ -192,9 +208,16 @@ export function searchRelevantMemories(db, userPrompt, project, excludeIds = [])
     const queryTokenCount = ftsQuery.includes(' AND ')
       ? ftsQuery.split(' AND ').length
       : ftsQuery.split(/\s+/).filter(t => t && !t.startsWith('(') || !t.endsWith(')')).length;
+    // CJK-dominant queries bypass the token-count gate: a single CJK word becomes
+    // 2-N overlapping bigrams (优化召回率 → 优化/召回/回率), inflating
+    // queryTokenCount past the gate, so the AND-too-strict query never gets the OR
+    // rescue that CJK retrieval relies on. The CLI/hybrid path relaxes CJK to OR
+    // unconditionally; mirror that here. Noise is contained downstream (0.4x OR
+    // penalty + BM25 threshold + term-coverage filter). queryIsCjkDominant (not
+    // mere CJK presence) is the gate — see its definition at the function top.
     if (rows.length === 0) {
       const orQuery = relaxFtsQueryToOr(ftsQuery);
-      if (orQuery && queryTokenCount <= OR_FALLBACK_MAX_TOKENS) {
+      if (orQuery && (queryIsCjkDominant || queryTokenCount <= OR_FALLBACK_MAX_TOKENS)) {
         try { rows = selectStmt.all(orQuery, project, cutoff); usedOrFallback = true; } catch {}
       }
     }
@@ -225,7 +248,7 @@ export function searchRelevantMemories(db, userPrompt, project, excludeIds = [])
       crossRows = crossStmt.all(ftsQuery, project, cutoff);
       if (crossRows.length === 0) {
         const orQuery = relaxFtsQueryToOr(ftsQuery);
-        if (orQuery && queryTokenCount <= OR_FALLBACK_MAX_TOKENS) {
+        if (orQuery && (queryIsCjkDominant || queryTokenCount <= OR_FALLBACK_MAX_TOKENS)) {
           try { crossRows = crossStmt.all(orQuery, project, cutoff); crossUsedOr = true; } catch {}
         }
       }

package/hook.mjs

@@ -1188,8 +1188,13 @@ async function handleSessionStart() {
     // project that the `### Deferred Work` block now reads from the
     // deferred_work table (was: high-importance observations in v2.69.x).
     // Idempotent via marker file; subsequent SessionStarts are silent.
-    try { emitV270UpgradeBanner({ project, runtimeDir: RUNTIME_DIR }); }
-    catch (e) { debugCatch(e, 'session-start-v270-banner'); }
+    try {
+      // Gate on prior data: a brand-new install never had v2.69.x deferred-block
+      // semantics, so the migration notice is wrong noise (it fired for every
+      // fresh install since v2.70). Only genuine upgraders with observations see it.
+      const obsCount = db.prepare('SELECT COUNT(*) AS c FROM observations WHERE project = ?').get(project)?.c || 0;
+      emitV270UpgradeBanner({ project, runtimeDir: RUNTIME_DIR, hasPriorData: obsCount > 0 });
+    } catch (e) { debugCatch(e, 'session-start-v270-banner'); }
 
     // Pre-load TF-IDF vocabulary cache for this session (from DB, ~1ms)
     try { getVocabulary(db); } catch (e) { debugCatch(e, 'session-start-vocab'); }

package/install.mjs

@@ -1116,8 +1116,15 @@ async function uninstall() {
   cleanupMemHooksFromSettings(settings);
 
   // 2b. Uninstall does NOT auto-unadopt — an adopted project may be in active use
-  // by the user in other Claude Code sessions. Tell them the command instead.
-  log('Invited-memory: adopt state preserved. Run `claude-mem-lite unadopt --all` to remove sentinel sections.');
+  // in other Claude Code sessions, and adoption lives in EACH project's own
+  // CLAUDE.md. `unadopt --all` now strips every block across the projects Claude
+  // Code knows about (~/.claude.json), so point at it — but note the timing: a
+  // --purge run removes the CLI symlink, so this is best done BEFORE uninstall.
+  log('Invited-memory: project adoption left in place (each adopted project keeps its');
+  log('  CLAUDE.md managed block + .claude/plugin_claude_mem_lite.md). To remove it from');
+  log('  every known project, run `claude-mem-lite unadopt --all` — best done BEFORE');
+  log('  uninstall, while the CLI is still on PATH. A project Claude Code never opened');
+  log('  is not in the known list — run `claude-mem-lite unadopt` from inside it.');
 
   // 3. Clean plugin registry entries conservatively (avoid deleting other plugins
   // from the same marketplace publisher)

package/lib/upgrade-banner.mjs

@@ -17,15 +17,26 @@ import { join } from 'path';
  * @param {object} args
  * @param {string} args.project Project name (used in banner + marker filename).
  * @param {string} args.runtimeDir RUNTIME_DIR (test override; production passes hook-shared.RUNTIME_DIR).
+ * @param {boolean} [args.hasPriorData=true] Whether the project has pre-existing
+ *   observations. A fresh install never had the v2.69.x deferred-block semantics,
+ *   so the migration notice (and its "pin to 2.69.x" advice, nonsensical 40+
+ *   versions on) is wrong noise — suppress it but still write the marker so it
+ *   stays suppressed once the new user starts saving memories. Defaults to true
+ *   for backward-compatibility with callers that don't probe.
  */
-export function emitV270UpgradeBanner({ project, runtimeDir }) {
+export function emitV270UpgradeBanner({ project, runtimeDir, hasPriorData = true }) {
   const marker = join(runtimeDir, `.deferred-block-migrated-${project}`);
   if (existsSync(marker)) return;
-  process.stderr.write(
-    `[mem] v2.70.0 upgrade notice (project "${project}"): Deferred Work block now ` +
-    `backed by deferred_work table. To keep an obs visible there, run ` +
-    `\`claude-mem-lite defer add "<title>" --priority 3\`. ` +
-    `Pin to 2.69.x to revert.\n`
-  );
+  // The banner only matters to someone who had high-importance observations
+  // under the old deferred-block semantics. No prior data → nothing migrated →
+  // suppress (but mark, so a brand-new user never sees it later either).
+  if (hasPriorData) {
+    process.stderr.write(
+      `[mem] v2.70.0 upgrade notice (project "${project}"): Deferred Work block now ` +
+      `backed by deferred_work table. To keep an obs visible there, run ` +
+      `\`claude-mem-lite defer add "<title>" --priority 3\`. ` +
+      `Pin to 2.69.x to revert.\n`
+    );
+  }
   try { writeFileSync(marker, String(Date.now())); } catch { /* best-effort marker */ }
 }

package/nlp.mjs

@@ -222,7 +222,19 @@ export function expandToken(token) {
 
 // ─── Stop Words ──────────────────────────────────────────────────────────────
 
-export const FTS_STOP_WORDS = new Set([...BASE_STOP_WORDS]);
+// Orphan stems left when apostrophe-splitting contractions ("I've"→"ve",
+// "wouldn't"→"wouldn"). Non-words only — they'd otherwise survive as required
+// AND terms and silently shrink recall. Ambiguous real words are intentionally
+// excluded so legitimate queries for them still work: don/won/haven/can, and
+// 're' ("re:"/regarding) — even though that leaves the they're/we're artifact,
+// dropping a real word is the worse failure.
+const CONTRACTION_FRAGMENTS = [
+  've', 'll',
+  'doesn', 'didn', 'isn', 'wasn', 'aren', 'weren',
+  'wouldn', 'couldn', 'shouldn', 'hasn', 'hadn', 'mustn', 'needn', 'mightn',
+];
+
+export const FTS_STOP_WORDS = new Set([...BASE_STOP_WORDS, ...CONTRACTION_FRAGMENTS]);
 
 // ─── FTS5 Query Sanitization ─────────────────────────────────────────────────
 
@@ -241,15 +253,30 @@ export function sanitizeFtsQuery(query) {
     // "never throws on MATCH" invariant. The metachar class below doesn't cover them.
     // eslint-disable-next-line no-control-regex -- intentional: stripping control chars IS the fix
     .replace(/[\x00-\x1f\x7f]/g, ' ')
+    // Apostrophe variants → space, matching FTS5 unicode61's own tokenization
+    // (it splits on apostrophe: "doesn't" is indexed as "doesn"+"t"). Without
+    // this, a possessive/contraction ("sister's", "What's") would phrase-quote
+    // to "sister s" (adjacency) and miss the bare-word mention ("my sister") in
+    // the doc, and contraction stems never reach the stopword filter. Straight
+    // ('), curly (' '), and modifier (ʼ) apostrophes all normalized.
+    .replace(/['‘’ʼ]/g, ' ')
     .replace(/[{}()[\]^~*:"\\]/g, ' ')
     .replace(/(^|\s)-/g, '$1')
     .trim();
   if (!cleaned) return null;
-  let tokens = cleaned.split(/\s+/).filter(t =>
-    t && !/^-+$/.test(t) && !FTS5_KEYWORDS.has(t.toUpperCase()) && !/^NEAR(\/\d*)?$/i.test(t)
-    // Skip single ASCII-letter tokens — too noisy for FTS5 (CJK single chars handled separately below)
-    && !(t.length === 1 && /^[a-zA-Z]$/.test(t))
-  );
+  let tokens = cleaned.split(/\s+/)
+    // Trim leading/trailing sentence punctuation (. , ? ! ; …) from each token.
+    // Natural-language queries end in "?" and clauses in ",": left on, the final
+    // (most salient) token rides as "bug?"/"month," which (a) misses the synonym
+    // map → no OR-expansion, and (b) gets phrase-quoted as a literal by
+    // expandToken. Edges only — internal dots/hyphens (cli.mjs, gardening-related)
+    // are preserved so filenames/compounds still phrase-match.
+    .map(t => t.replace(/^[.,;:!?]+|[.,;:!?]+$/g, ''))
+    .filter(t =>
+      t && !/^-+$/.test(t) && !FTS5_KEYWORDS.has(t.toUpperCase()) && !/^NEAR(\/\d*)?$/i.test(t)
+      // Skip single ASCII-letter tokens — too noisy for FTS5 (CJK single chars handled separately below)
+      && !(t.length === 1 && /^[a-zA-Z]$/.test(t))
+    );
   // Filter stop words (but keep all if filtering would empty the query)
   const filtered = tokens.filter(t => !FTS_STOP_WORDS.has(t.toLowerCase()));
   if (filtered.length > 0) tokens = filtered;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-mem-lite",
-  "version": "3.13.0",
+  "version": "3.15.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).",
   "type": "module",
   "packageManager": "npm@10.9.2",

package/tier.mjs

@@ -110,7 +110,12 @@ export function tierSqlParams(ctx) {
  * @returns {string}
  */
 export function relativeTime(epoch, now) {
-  const diff = now - epoch;
+  // Clamp negative diffs: a future / clock-skewed epoch must not render as a
+  // negative duration ("-7200s ago"). The first branch below (diff < 60000)
+  // would otherwise fire on any negative diff and print Math.floor(diff/1000),
+  // i.e. "-7200s ago" for a 2h-future timestamp. (cli/common.mjs's sibling
+  // relativeTime handles this via an early `diff < 0` → "just now".)
+  const diff = Math.max(0, now - epoch);
   if (diff < 60000) return `${Math.floor(diff / 1000)}s ago`;
   if (diff < 3600000) return `${Math.floor(diff / 60000)}min ago`;
   if (diff < 86400000) return `${Math.floor(diff / 3600000)}h ago`;