claude-mem-lite 3.75.1 → 3.76.1

package/.claude-plugin/marketplace.json

@@ -10,7 +10,7 @@
   "plugins": [
     {
       "name": "claude-mem-lite",
-      "version": "3.75.1",
+      "version": "3.76.1",
       "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.75.1",
+  "version": "3.76.1",
   "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/adopt-content.mjs

@@ -159,7 +159,7 @@ PreToolUse hook 在你 Read / Edit / Write 文件前已自动 \`mem_recall\` 该
 | 改某条 | \`${CLI_INVOKE} update <id> [--lesson "<≤500>"] [--title T] [--type T] [--importance 1-3] [--narrative T] [--concepts "a b c"]\` |
 | 事件日志 | \`${CLI_INVOKE} activity save --type <bugfix\\|lesson\\|bug\\|discovery\\|refactor\\|feature\\|observation\\|decision> "<title>" [--body T] [--files f1,f2]\` |
 
-\`maintain\` / \`optimize\` / \`compress\` 见上方「维护 / 管理类工具」；\`maintain --ops\` 取值 \`cleanup,decay,boost,demote_pinned,dedup,purge_stale,rebuild_vectors,vacuum\`，\`--retain-days\` ∈ [7,365]。
+\`maintain\` / \`optimize\` / \`compress\` 见上方「维护 / 管理类工具」；\`maintain --ops\` 取值 \`cleanup,decay,boost,demote_pinned,dedup,purge_stale,rebuild_vectors,vacuum\`，省略时默认 \`cleanup,decay,boost,demote_pinned\`（顺序有意义：demote_pinned 必须在 boost 之后）；\`--retain-days\` ∈ [7,365]。
 
 ## 卸载 / 关闭
 

package/hook.mjs

@@ -50,7 +50,7 @@ import { formatHookError } from './lib/native-binding-hint.mjs';
 import { recordHookError } from './lib/hook-telemetry.mjs';
 import { queueHookContext, queueHookSystemMessage, flushHookStdout } from './lib/hook-stdout.mjs';
 import { selectCompressionCandidates, groupByProjectWeek, compressGroup } from './lib/compress-core.mjs';
-import { cleanupBroken, decayAndMarkIdle, boostAccessed, markAutoCompressible, selectFuzzyDedupeIds, stampDedupSuperseded, hardDeleteCandidateCount, purgeStale, recoverOrphanedChildren, recoverBuriedLessons, sweepDeferredWorkOrphans } from './lib/maintain-core.mjs';
+import { cleanupBroken, decayAndMarkIdle, boostAccessed, demotePinned, resolveDefaultMaintainOps, markAutoCompressible, selectFuzzyDedupeIds, stampDedupSuperseded, hardDeleteCandidateCount, purgeStale, recoverOrphanedChildren, recoverBuriedLessons, sweepDeferredWorkOrphans } from './lib/maintain-core.mjs';
 import { snapshotDb } from './lib/db-backup.mjs';
 import {
   extractCitationsFromTranscript,
@@ -1122,6 +1122,36 @@ function runSessionStartAutoMaintain(db, project) {
         }
       }
 
+      // v3.76.0: the automatic path used to promote and never demote. boostAccessed ran
+      // above; demotePinned was not even imported here, and it sat outside the default op
+      // set of the CLI and MCP faces too — so the only op that can reach a
+      // heavily-injected-but-uncited row (regular decay deliberately protects
+      // injection_count>0) ran solely when a human typed `--ops demote_pinned`. Measured
+      // on the maintainer's live DB before the fix: 148 rows demoted by citation decay,
+      // never cited, and back at importance>=3, 148/148 of them boost-eligible.
+      //
+      // Placed AFTER boost, for the obvious reason: boostAccessed lifts any
+      // access_count>3 row with importance<3, so demoting first hands the row straight
+      // back at 2 (mem-cli had exactly that order and silently undid its own demotion
+      // inside a single run).
+      //
+      // Placed AFTER fuzzy dedup, for a less obvious one, found by pre-tag review: the
+      // dedup block above re-SELECTs `importance` and selectFuzzyDedupeIds keeps the
+      // higher-importance member of a near-duplicate pair. Demoting first inverted that
+      // rule using a value rewritten 40 lines earlier in the same pass — the pinned row
+      // lost and was tombstoned, keeping the copy WITHOUT the injection history. Dedup
+      // now decides on pre-demotion importance. Nothing between boost and here reads
+      // importance, so the move is free.
+      //
+      // Whole-DB mctx (projectFilter ''), so unlike markAutoCompressibleIfDue this needs
+      // NO per-project gate: one run under the global 24h gate covers every project at
+      // once. Do not "fix" it into a per-project gate — that is the v3.75.0 regression in
+      // reverse.
+      const demotedPinned = resolveDefaultMaintainOps().includes('demote_pinned')
+        ? demotePinned(db, mctx)
+        : 0;
+      if (demotedPinned > 0) debugLog('DEBUG', 'auto-maintain', `demoted ${demotedPinned} pinned-but-uncited observations (no lesson → 1, lesson → 2)`);
+
       // Orphan sweep: remove `ep-flush-*` / `pending-*` runtime files older
       // than 1h. handleLLMEpisode normally unlinks its own tmpFile on every
       // exit path, but a crashed worker (OOM, host reboot, kill -9) leaves

package/lib/maintain-core.mjs

@@ -30,6 +30,45 @@ export const MINHASH_PRE_THRESHOLD = MINHASH_PRE_THRESHOLD_SRC;
 // the regular decay op can't touch (decay protects injection_count>0).
 export const PINNED_INJ_THRESHOLD = 8;
 
+// Single home for the default maintenance op set AND its order.
+//
+// Three faces run maintenance — hook.mjs auto-maintain, CLI `maintain execute`,
+// MCP `mem_maintain` — and each used to hand-list its own default set. They had
+// drifted in both ways a hand-copied list can:
+//   - `demote_pinned` was in NOBODY's default set, and hook.mjs did not even
+//     import demotePinned. Its opponent `boostAccessed` was in all three. So the
+//     automatic path promoted and never demoted: measured on the maintainer's live
+//     DB, 148 rows sat demoted-by-citation-decay, never cited, and back at
+//     importance>=3 — 148/148 of them boostAccessed-eligible (access_count>3).
+//   - the two faces that DID wire the op ran it in opposite orders: mem-cli did
+//     demote-then-boost, which hands the row straight back (importance 1 → 2);
+//     server.mjs did boost-then-demote, which lands it at 1.
+// Hence: order matters, and `demote_pinned` MUST come after `boost`.
+export const DEFAULT_MAINTAIN_OPS = Object.freeze(['cleanup', 'decay', 'boost', 'demote_pinned']);
+
+// Opt-out for the v3.76.0 default change. Scoped to the DEFAULT set ONLY — an
+// explicit `--ops demote_pinned` / `operations:["demote_pinned"]` still runs. An
+// accepted value that silently means something else is worse than an unsupported
+// one (cf. CLAUDE_MEM_RECOMMEND_MODE=live, which parses and then does not do what
+// it says).
+// The first cut of this compared `=== '1'`, which silently ignored `=true` / `=yes` /
+// `= 1` — precisely the failure mode the comment above warns about, committed three
+// lines under it. Sibling skip-flags in this repo are bare truthiness checks
+// (`if (!process.env.CLAUDE_MEM_SKIP_COMPRESS)`), so any non-empty value opts out;
+// the falsey WORDS are honoured too, because `=0` or `=false` reading as "skip" is the
+// same class of silent surprise in the other direction.
+function envFlagEnabled(raw) {
+  if (raw === undefined || raw === null) return false;
+  const v = String(raw).trim().toLowerCase();
+  return v !== '' && v !== '0' && v !== 'false' && v !== 'no' && v !== 'off';
+}
+
+export function resolveDefaultMaintainOps(env = process.env) {
+  return envFlagEnabled(env?.CLAUDE_MEM_SKIP_DEMOTE_PINNED)
+    ? DEFAULT_MAINTAIN_OPS.filter((op) => op !== 'demote_pinned')
+    : [...DEFAULT_MAINTAIN_OPS];
+}
+
 // Two trimmed bodies count as "the same body" when both are empty (a genuine
 // no-body re-save) or their word-set Jaccard clears the floor. One-empty-one-not
 // is treated as DISTINCT so a body-bearing observation is never hidden by a
@@ -158,10 +197,23 @@ export function markAutoCompressible(db, project, {
   // The write-side capNoiseImportance already forces imp=1 on these; this only shrinks GC
   // latency so the corpus reduction materializes within a week instead of bleeding into
   // the 30-day tier.
+  //
+  // v3.76.0: `injection_count = 0` added here to match the aged pass above, which has
+  // carried it since v2.56.0. Until this release nothing could reach BOTH `importance<=1`
+  // and `injection_count>=1`, so the omission was unobservable; `demote_pinned` joining
+  // the default op set creates exactly that population. Without this clause a demoted row
+  // could be marked COMPRESSED_AUTO on the NEXT maintain run — hidden from every
+  // `COALESCE(compressed_into,0)=0` read path, therefore never injected, therefore never
+  // cited, therefore with no path back. Pre-tag review reproduced that chain end to end.
+  // Today the two passes are also protected by an interlock — the title patterns below
+  // are the same set `notLowSignalTitleClause` (lib/low-signal-patterns.mjs) keeps off the
+  // only surfaces that bump `injection_count` — but that is two hand-listed sets in two
+  // files agreeing by maintenance, which is not a guarantee. This clause is.
   const noise = db.prepare(`
     UPDATE observations SET compressed_into = ${COMPRESSED_AUTO}
     WHERE COALESCE(compressed_into, 0) = 0
       AND COALESCE(importance, 1) <= 1
+      AND COALESCE(injection_count, 0) = 0
       AND (lesson_learned IS NULL OR lesson_learned = '' OR lesson_learned = 'none')
       AND (facts IS NULL OR facts = '' OR facts = '[]')
       AND (
@@ -340,21 +392,55 @@ export function boostAccessed(db, { projectFilter, baseParams, opCap = OP_CAP })
   `).run(...baseParams).changes;
 }
 
+// Every other automatic pass in this file carries this clause verbatim (lines 179, 192,
+// 299, 334) — a lesson is the distilled value a lessons store exists to hold, and
+// background machinery must not quietly dispose of one.
+const NO_LESSON_SQL = "(lesson_learned IS NULL OR lesson_learned = '' OR lesson_learned = 'none')";
+
+// The floor demotePinned writes, and therefore also the bound that decides whether a row
+// still HAS anything to demote. One home: v3.76.0 shipped with the floor here and the
+// forecast in maintenanceStats still hard-coded `importance > 1`, so a lesson row already
+// at 2 was counted as pinned forever while every execute reported "Demoted 0" — the exact
+// scan-forecast-vs-execute drift the decayAndMarkIdle comment below exists to prevent.
+const PINNED_FLOOR_SQL = `(CASE WHEN ${NO_LESSON_SQL} THEN 1 ELSE 2 END)`;
+// Shared by the op and its forecast. Callers add their own compressed_into/project filter.
+// Module-private on purpose: nothing outside this file consumes it, and exporting by habit
+// is how the knip baseline drifts (cf. the v3.70.0 DEFAULT_MARKETPLACE trio).
+const PINNED_PREDICATE_SQL = `
+  COALESCE(injection_count, 0) >= ${PINNED_INJ_THRESHOLD}
+  AND COALESCE(cited_count, 0) = 0
+  AND COALESCE(importance, 1) > ${PINNED_FLOOR_SQL}`;
+
 /**
  * Repair the citation-decay blind spot: heavy-injection + zero-citation rows that
- * decay protects (injection_count>0) stay pinned at max importance forever. Drop
- * them to importance 1 in one pass (injection priority is binary at >=2, so a
- * single step would not de-rank). Floor 1, not purge.
+ * decay protects (injection_count>0) stay pinned at max importance forever. Floor
+ * them; never purge.
+ *
+ * TWO floors, and the asymmetry is the point. `importance >= 2` is a hard WHERE on the
+ * injection faces that actually earn citations — pre-tool-recall
+ * (scripts/pre-tool-recall.js:428,470), SessionStart Key Context (hook-context.mjs:95,315)
+ * and cross-project (hook-memory.mjs:280) — whereas `injection_count`, the signal that
+ * triggers this op at all, is incremented ONLY on the two UserPromptSubmit faces
+ * (hook-memory.mjs:367, scripts/user-prompt-search.js:979). Those are the weakest faces
+ * by measured cite-rate. Dropping straight to 1 therefore convicts a row on its weakest
+ * surface and evicts it from its strongest — which pre-tag review caught: on the
+ * maintainer's live DB, 16 of the 17 rows this op would have moved were lesson-bearing.
+ *
+ *   no lesson -> 1  (fully de-ranked; the original behaviour, unchanged)
+ *   lesson    -> 2  (loses the top tier and its ranking weight, keeps eligibility on
+ *                    every importance>=2 face)
+ *
+ * The floor doubles as the WHERE bound so a row already sitting at its floor is not
+ * re-touched: SQLite counts a same-value UPDATE in `changes`, which would otherwise
+ * report phantom demotions on every run forever.
  */
 export function demotePinned(db, { projectFilter, baseParams, opCap = OP_CAP }) {
   return db.prepare(`
-    UPDATE observations SET importance = 1
+    UPDATE observations SET importance = ${PINNED_FLOOR_SQL}
     WHERE id IN (
       SELECT id FROM observations
       WHERE COALESCE(compressed_into, 0) = 0
-        AND COALESCE(injection_count, 0) >= ${PINNED_INJ_THRESHOLD}
-        AND COALESCE(cited_count, 0) = 0
-        AND COALESCE(importance, 1) > 1
+        AND ${PINNED_PREDICATE_SQL}
         ${projectFilter} LIMIT ${opCap}
     )
   `).run(...baseParams).changes;
@@ -528,9 +614,7 @@ export function maintenanceStats(db, { projectFilter, baseParams, staleAge }) {
                THEN 1 ELSE 0 END), 0) as broken,
       COALESCE(SUM(CASE WHEN COALESCE(access_count, 0) > 3 AND COALESCE(importance, 1) < 3
                THEN 1 ELSE 0 END), 0) as boostable,
-      COALESCE(SUM(CASE WHEN COALESCE(injection_count, 0) >= ${PINNED_INJ_THRESHOLD}
-                    AND COALESCE(cited_count, 0) = 0 AND COALESCE(importance, 1) > 1
-               THEN 1 ELSE 0 END), 0) as pinned
+      COALESCE(SUM(CASE WHEN ${PINNED_PREDICATE_SQL} THEN 1 ELSE 0 END), 0) as pinned
     FROM observations
     WHERE COALESCE(compressed_into, 0) = 0 ${projectFilter}
   `).get(staleAge, ...baseParams);

package/mem-cli.mjs

@@ -30,7 +30,7 @@ import {
   recoverOrphanedChildren, recoverBuriedLessons, sweepDeferredWorkOrphans,
   purgeStale, purgeStalePreview, findDuplicates, maintenanceStats, rebuildVectors, vacuum,
   hardDeleteCandidateCount,
-  OP_CAP, STALE_AGE_MS, PINNED_INJ_THRESHOLD,
+  OP_CAP, STALE_AGE_MS, PINNED_INJ_THRESHOLD, resolveDefaultMaintainOps,
 } from './lib/maintain-core.mjs';
 import { snapshotDb, listSnapshots, backupBudgetBytes } from './lib/db-backup.mjs';
 import { deleteObservations, previewDeleteRows } from './lib/delete-core.mjs';
@@ -2012,7 +2012,7 @@ function cmdMaintain(db, args) {
     out(`  Stale (>30d, imp=1, no access, never injected): ${stats.stale}`);
     out(`  Broken (no title/narrative): ${stats.broken}`);
     out(`  Boostable (accessed>3, imp<3): ${stats.boostable}`);
-    out(`  Pinned-but-uncited (inj>=${PINNED_INJ_THRESHOLD}, cited=0, imp>1): ${stats.pinned} — run: maintain execute --ops demote_pinned`);
+    out(`  Pinned-but-uncited (inj>=${PINNED_INJ_THRESHOLD}, cited=0, above floor): ${stats.pinned} — floored by the default maintain set since v3.76.0, no lesson → 1, lesson → 2 (opt out: CLAUDE_MEM_SKIP_DEMOTE_PINNED=1)`);
     out(formatPendingPurgeLine(stats.pendingPurge));
     if (duplicates.length > 0) {
       const autoMergeable = duplicates.filter(d => parseFloat(d.similarity) >= AUTO_MERGE_THRESHOLD);
@@ -2047,9 +2047,11 @@ function cmdMaintain(db, args) {
   const VALID_OPS = ['cleanup', 'decay', 'boost', 'demote_pinned', 'dedup', 'purge_stale', 'rebuild_vectors', 'vacuum'];
   // Distinguish flag-absent (use default op set) from flag-present-but-empty
   // (`--ops ""`, e.g. an unset shell var). The latter previously coerced via `||`
-  // to the destructive default cleanup,decay,boost and EXECUTED it; route it to the
-  // VALID_OPS check below instead so it's rejected like `--ops " "` / `--ops "decay,"`.
-  const opsStr = flags.ops === undefined ? 'cleanup,decay,boost' : String(flags.ops);
+  // to the destructive default set and EXECUTED it; route it to the VALID_OPS check
+  // below instead so it's rejected like `--ops " "` / `--ops "decay,"`. (That default
+  // was the literal `cleanup,decay,boost` when this was written; it now comes from
+  // DEFAULT_MAINTAIN_OPS, which is why the list is no longer spelled out here.)
+  const opsStr = flags.ops === undefined ? resolveDefaultMaintainOps().join(',') : String(flags.ops);
   const ops = opsStr.split(',').map(s => s.trim());
   const invalidOps = ops.filter(op => !VALID_OPS.includes(op));
   if (invalidOps.length > 0) {
@@ -2138,17 +2140,23 @@ function cmdMaintain(db, args) {
       results.push(`Decayed ${decayed} stale observations, marked ${idleMarked} idle as pending-purge${decayCap}`);
     }
 
+    if (ops.includes('boost')) {
+      const boosted = boostAccessed(db, mctx);
+      results.push(`Boosted ${boosted} frequently-accessed observations${capHint(boosted)}`);
+    }
+
+    // AFTER boost, matching server.mjs and hook.mjs. This block used to sit BEFORE
+    // it, and the order was load-bearing in the wrong direction: boostAccessed lifts
+    // any access_count>3 row with importance<3, so demoting a pinned row to 1 and
+    // then boosting handed it straight back at 2 — the demotion silently undone
+    // inside a single maintain run. DEFAULT_MAINTAIN_OPS pins the order; this block
+    // has to physically follow the boost block for that order to be real.
     if (ops.includes('demote_pinned')) {
       // Repair the citation-decay blind spot: decay protects injection_count>0, so a
       // heavily-injected-but-uncited memory stays pinned at max importance forever.
       // demotePinned (maintain-core) drops it to 1 in one pass. Floor 1, not purge.
       const demoted = demotePinned(db, mctx);
-      results.push(`Demoted ${demoted} pinned-but-uncited observations to importance 1 (inj>=${PINNED_INJ_THRESHOLD}, cited=0)${capHint(demoted)}`);
-    }
-
-    if (ops.includes('boost')) {
-      const boosted = boostAccessed(db, mctx);
-      results.push(`Boosted ${boosted} frequently-accessed observations${capHint(boosted)}`);
+      results.push(`Demoted ${demoted} pinned-but-uncited observations (inj>=${PINNED_INJ_THRESHOLD}, cited=0; no lesson → importance 1, lesson → 2)${capHint(demoted)}`);
     }
 
     if (ops.includes('dedup') && flags['merge-ids']) {
@@ -2784,10 +2792,15 @@ Commands:
 
   maintain <scan|execute>  Memory maintenance
     --ops O             Comma-separated: cleanup,decay,boost,demote_pinned,dedup,purge_stale,rebuild_vectors,vacuum
+                        Default when omitted: cleanup,decay,boost,demote_pinned (in that order)
     --merge-ids K:R,... For dedup: keepId:removeId pairs (e.g. 10:11,20:21:22)
     --project P         Filter by project
     --retain-days N     For purge_stale: keep last N days (default 30)
-                        demote_pinned: importance→1 for inj>=8 & cited=0 (clears pinned noise)
+                        demote_pinned: importance→1 for inj>=8 & cited=0 (clears pinned noise).
+                        In the default set since v3.76.0; runs AFTER boost, which would
+                        otherwise hand the row straight back. Opt out of the DEFAULT with
+                        CLAUDE_MEM_SKIP_DEMOTE_PINNED=1 — an explicit --ops demote_pinned
+                        still runs.
                         vacuum: reclaim freelist dead space (whole-DB, ignores --project)
 
   optimize              LLM-powered memory optimization (preview by default)

package/npm-shrinkwrap.json

@@ -1,12 +1,12 @@
 {
   "name": "claude-mem-lite",
-  "version": "3.75.1",
+  "version": "3.76.1",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "claude-mem-lite",
-      "version": "3.75.1",
+      "version": "3.76.1",
       "dependencies": {
         "@modelcontextprotocol/sdk": "^1.26.0",
         "better-sqlite3": "^12.6.2",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-mem-lite",
-  "version": "3.75.1",
+  "version": "3.76.1",
   "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/scripts/launch.mjs

@@ -42,8 +42,15 @@ if (!existsSync(join(ROOT, 'node_modules', 'better-sqlite3'))) {
     //
     // `e.status` not `e.code`: execSync failures carry the exit status on `status`,
     // so the old `|| e.code` rung was dead.
+    // `?? null` not `!= null`: the loose form is the idiom, but this file is
+    // linted under `eqeqeq: always`, and rewriting it as `!== undefined` would
+    // be a BEHAVIOUR change — execSync reports a signal kill with `status: null`,
+    // which `!== undefined` accepts and would render as "npm exited null".
+    // Coalescing first keeps the original both-nullish semantics exactly, `0`
+    // included.
+    const status = e?.status ?? null;
     const detail = e?.message?.split('\n')[0]
-      || (e?.status != null ? `npm exited ${e.status}` : '')
+      || (status !== null ? `npm exited ${status}` : '')
       || (e?.signal ? `npm killed by ${e.signal}` : '')
       || 'unknown error';
     process.stderr.write(`[claude-mem-lite] npm install failed in ${ROOT} — ${detail}\n`);

package/server.mjs

@@ -19,7 +19,7 @@ import {
   recoverOrphanedChildren, recoverBuriedLessons, sweepDeferredWorkOrphans,
   purgeStale, purgeStalePreview, findDuplicates, maintenanceStats, rebuildVectors, vacuum,
   hardDeleteCandidateCount,
-  OP_CAP, STALE_AGE_MS,
+  OP_CAP, STALE_AGE_MS, resolveDefaultMaintainOps, DEFAULT_MAINTAIN_OPS,
 } from './lib/maintain-core.mjs';
 import { snapshotDb } from './lib/db-backup.mjs';
 import { deleteObservations, previewDeleteRows } from './lib/delete-core.mjs';
@@ -1148,11 +1148,11 @@ server.registerTool(
     if (action === 'execute') {
       const ops = args.operations && args.operations.length > 0
         ? args.operations
-        : ['cleanup', 'decay', 'boost'];
+        : resolveDefaultMaintainOps();
       // T2-P1-A: reject explicit empty array (vs. omitted → defaults above). Empty-array
       // callers are almost always mistakes; silently running only FTS5 optimize hides the error.
       if (args.operations && args.operations.length === 0) {
-        return { content: [{ type: 'text', text: 'operations array is empty. Pass a non-empty list (e.g. ["cleanup","decay","boost"]) or omit operations to use the default set.' }], isError: true };
+        return { content: [{ type: 'text', text: `operations array is empty. Pass a non-empty list (e.g. ${JSON.stringify(DEFAULT_MAINTAIN_OPS)}) or omit operations to use the default set.` }], isError: true };
       }
       const results = [];
       const staleAge = Date.now() - STALE_AGE_MS;
@@ -1239,7 +1239,7 @@ server.registerTool(
 
         if (ops.includes('demote_pinned')) {
           const demoted = demotePinned(db, mctx);
-          results.push(`Demoted ${demoted} pinned-but-uncited observations to importance 1 (inj>=8, cited=0)` + (demoted >= OP_CAP ? ' (cap reached, re-run for more)' : ''));
+          results.push(`Demoted ${demoted} pinned-but-uncited observations (inj>=8, cited=0; no lesson → importance 1, lesson → 2)` + (demoted >= OP_CAP ? ' (cap reached, re-run for more)' : ''));
         }
 
         if (ops.includes('dedup') && args.merge_ids) {

package/tool-schemas.mjs

@@ -247,7 +247,7 @@ export const memOptimizeSchema = {
 export const memMaintainSchema = {
   action: z.enum(['scan', 'execute']).describe('scan=analyze candidates, execute=apply changes'),
   operations: z.array(z.enum(['dedup', 'decay', 'cleanup', 'boost', 'demote_pinned', 'purge_stale', 'rebuild_vectors', 'vacuum'])).optional()
-    .describe('Operations: dedup=find/merge duplicate observations, decay=reduce importance of old low-value obs, cleanup=remove orphaned records, boost=promote frequently-accessed obs, demote_pinned=importance→1 for obs injected>=8 times but never cited (clears pinned noise the decay op cannot reach), purge_stale=DELETE pending-purge obs older than retain_days (requires confirm=true; first call previews), rebuild_vectors=rebuild TF-IDF vocabulary and all observation vectors, vacuum=reclaim freelist dead space (whole-DB)'),
+    .describe('Operations: dedup=find/merge duplicate observations, decay=reduce importance of old low-value obs, cleanup=remove orphaned records, boost=promote frequently-accessed obs, demote_pinned=importance→1 for obs injected>=8 times but never cited (clears pinned noise the decay op cannot reach; in the default set since v3.76.0 and ordered after boost, since boost would otherwise raise the row straight back — set CLAUDE_MEM_SKIP_DEMOTE_PINNED=1 to drop it from the DEFAULT set only), purge_stale=DELETE pending-purge obs older than retain_days (requires confirm=true; first call previews), rebuild_vectors=rebuild TF-IDF vocabulary and all observation vectors, vacuum=reclaim freelist dead space (whole-DB)'),
   merge_ids: z.preprocess(
     (v) => Array.isArray(v) ? v.map(g => Array.isArray(g) ? g.map(x => typeof x === 'string' ? parseInt(x, 10) : x) : g) : v,
     z.array(z.array(z.number().int()).min(2))