claude-mem-lite 3.96.0 → 3.97.0

package/tool-schemas.mjs

@@ -9,48 +9,51 @@ export const OBS_TYPE_ENUM = z.enum([...OBS_TYPES]);
 
 // LLM-friendly coercion: accept string numbers and normalize to proper types
 const coerceInt = z.preprocess(
-  (v) => (typeof v === 'string' && /^-?\d+$/.test(v.trim())) ? parseInt(v.trim(), 10) : v,
-  z.number().int()
+  (v) => (typeof v === 'string' && /^-?\d+$/.test(v.trim()) ? parseInt(v.trim(), 10) : v),
+  z.number().int(),
 );
 
 // LLM-friendly coercion: accept "true"/"false"/"True"/"TRUE" strings as boolean
 const coerceBool = z.preprocess(
-  (v) => typeof v === 'string' ? ({ true: true, false: false })[v.toLowerCase()] ?? v : v,
-  z.boolean()
+  (v) => (typeof v === 'string' ? ({ true: true, false: false }[v.toLowerCase()] ?? v) : v),
+  z.boolean(),
 );
 
 // Coerce ids: accept single number, string "123", comma-separated "1,2,3", or array
-const coerceIntArray = z.preprocess(
-  (v) => {
-    if (Array.isArray(v)) return v.map(x => typeof x === 'string' ? parseInt(x, 10) : x);
-    if (typeof v === 'number') return [v];
-    if (typeof v === 'string') return v.split(',').map(s => parseInt(s.trim(), 10)).filter(n => !isNaN(n));
-    return v;
-  },
-  z.array(z.number().int())
-);
+const coerceIntArray = z.preprocess((v) => {
+  if (Array.isArray(v)) return v.map((x) => (typeof x === 'string' ? parseInt(x, 10) : x));
+  if (typeof v === 'number') return [v];
+  if (typeof v === 'string')
+    return v
+      .split(',')
+      .map((s) => parseInt(s.trim(), 10))
+      .filter((n) => !isNaN(n));
+  return v;
+}, z.array(z.number().int()));
 
 // Coerce string arrays: accept array, comma-separated string, JSON-array string, or bare string.
 // MCP bridges sometimes JSON-stringify complex args — bare `z.array(z.string())` rejects those
 // with "expected array, received string" and the caller loses the field silently. Parity with
 // coerceIntArray: tolerate the same shapes so files/fields survive client serialization quirks.
-const coerceStringArray = z.preprocess(
-  (v) => {
-    if (Array.isArray(v)) return v.map(x => typeof x === 'string' ? x : String(x));
-    if (typeof v === 'string') {
-      const s = v.trim();
-      if (s.startsWith('[') && s.endsWith(']')) {
-        try {
-          const parsed = JSON.parse(s);
-          if (Array.isArray(parsed)) return parsed.map(x => typeof x === 'string' ? x : String(x));
-        } catch { /* fall through to comma-split */ }
+const coerceStringArray = z.preprocess((v) => {
+  if (Array.isArray(v)) return v.map((x) => (typeof x === 'string' ? x : String(x)));
+  if (typeof v === 'string') {
+    const s = v.trim();
+    if (s.startsWith('[') && s.endsWith(']')) {
+      try {
+        const parsed = JSON.parse(s);
+        if (Array.isArray(parsed)) return parsed.map((x) => (typeof x === 'string' ? x : String(x)));
+      } catch {
+        /* fall through to comma-split */
       }
-      return s.split(',').map(x => x.trim()).filter(x => x.length > 0);
     }
-    return v;
-  },
-  z.array(z.string())
-);
+    return s
+      .split(',')
+      .map((x) => x.trim())
+      .filter((x) => x.length > 0);
+  }
+  return v;
+}, z.array(z.string()));
 
 // Coerce mixed ID tokens (#N / P#N / S#N / D#N / bare N) for mem_get. Accepts:
 //   - native arrays: [1, "P#2", "#3"]
@@ -61,45 +64,93 @@ const coerceStringArray = z.preprocess(
 // at the handler. Closes the CLI↔MCP gap noted in #8127.
 const coerceMixedIdTokens = z.preprocess(
   (v) => {
-    const norm = (x) => typeof x === 'string' ? x.trim() : String(x);
-    if (Array.isArray(v)) return v.map(norm).filter(s => s.length > 0);
+    const norm = (x) => (typeof x === 'string' ? x.trim() : String(x));
+    if (Array.isArray(v)) return v.map(norm).filter((s) => s.length > 0);
     if (typeof v === 'number') return [String(v)];
     if (typeof v === 'string') {
       const s = v.trim();
       if (s.startsWith('[') && s.endsWith(']')) {
         try {
           const parsed = JSON.parse(s);
-          if (Array.isArray(parsed)) return parsed.map(norm).filter(x => x.length > 0);
-        } catch { /* fall through to comma-split */ }
+          if (Array.isArray(parsed)) return parsed.map(norm).filter((x) => x.length > 0);
+        } catch {
+          /* fall through to comma-split */
+        }
       }
-      return s.split(',').map(x => x.trim()).filter(Boolean);
+      return s
+        .split(',')
+        .map((x) => x.trim())
+        .filter(Boolean);
     }
     return v;
   },
   // D#N (deferred_work) requires the `#` — bare "D92" is prose, not a token.
   // Round-trip rule: `defer list` renders "(D#92)", so mem_get must accept it
   // back (tests/schema-roundtrip.test.mjs). Delete/timeline keep rejecting D#.
-  z.array(z.string().regex(/^(?:[Dd]#|[EePpSs]?#?)\d+$/, 'Expected N, #N, P#N, S#N, E#N, or D#N')).min(1).max(20)
+  z
+    .array(z.string().regex(/^(?:[Dd]#|[EePpSs]?#?)\d+$/, 'Expected N, #N, P#N, S#N, E#N, or D#N'))
+    .min(1)
+    .max(20),
 );
 
 export const memSearchSchema = {
   query: z.string().optional().describe('Search query (FTS5 syntax supported)'),
-  type: z.enum(['observations', 'sessions', 'prompts', 'events']).optional().describe('Limit to one source table (default: all). events = the canonical bugfix/feature/decision/lesson history (auto-captured event-typed memories)'),
+  type: z
+    .enum(['observations', 'sessions', 'prompts', 'events'])
+    .optional()
+    .describe(
+      'Limit to one source table (default: all). events = the canonical bugfix/feature/decision/lesson history (auto-captured event-typed memories)',
+    ),
   obs_type: OBS_TYPE_ENUM.optional().describe('Filter observation type'),
   project: z.string().optional().describe('Filter by project name'),
   date_from: z.string().optional().describe('Start date (ISO 8601 or YYYY-MM-DD)'),
-  date_to: z.string().optional().describe('End date (ISO 8601 or YYYY-MM-DD). Date-only format is inclusive (covers full day)'),
-  date_since: z.string().optional().describe('Relative lower bound from now: 7d/24h/90m/2w/30s. Use for "recent" queries instead of computing a date_from; ignored when date_from is set'),
-  importance: coerceInt.pipe(z.number().int().min(1).max(3)).optional().describe('Minimum importance (1=routine, 2=notable, 3=critical)'),
+  date_to: z
+    .string()
+    .optional()
+    .describe('End date (ISO 8601 or YYYY-MM-DD). Date-only format is inclusive (covers full day)'),
+  date_since: z
+    .string()
+    .optional()
+    .describe(
+      'Relative lower bound from now: 7d/24h/90m/2w/30s. Use for "recent" queries instead of computing a date_from; ignored when date_from is set',
+    ),
+  importance: coerceInt
+    .pipe(z.number().int().min(1).max(3))
+    .optional()
+    .describe('Minimum importance (1=routine, 2=notable, 3=critical)'),
   branch: z.string().optional().describe('Filter by git branch name'),
-  tier: z.enum(['working', 'active', 'archive']).optional().describe('Filter by memory tier (working=current session, active=within decay window, archive=old/compressed)'),
+  tier: z
+    .enum(['working', 'active', 'archive'])
+    .optional()
+    .describe(
+      'Filter by memory tier (working=current session, active=within decay window, archive=old/compressed)',
+    ),
   limit: coerceInt.pipe(z.number().int().min(1).max(100)).optional().describe('Max results (default 20)'),
   offset: coerceInt.pipe(z.number().int().min(0)).optional().describe('Offset for pagination'),
-  sort: z.enum(['relevance', 'time', 'importance']).optional().describe('Sort order: relevance (default, BM25), time (newest first), importance (highest first)'),
-  include_noise: coerceBool.optional().describe('Include hook-llm fallback titles ("Modified X", "Worked on X", raw error logs) — hidden by default as they have ~3% access rate'),
-  or: coerceBool.optional().describe('Force OR semantics between query terms from the start (default: AND with automatic OR-fallback when AND returns 0). Aligns with CLI --or.'),
-  deep: coerceBool.optional().describe('Tri-state LLM multi-query/HyDE deep search (observations-only). true=force; false=never; omit=AUTO (default ON for mem_search): a normal search that returns weak/few results auto-escalates with ONE Haiku call (query rewritten to keyword/concept/HyDE variants, RRF-fused). Set CLAUDE_MEM_AUTO_DEEP=0 to disable AUTO. Passive recall stays single-query.'),
-  rerank: coerceBool.optional().describe('Opt-in: LLM-rerank the deep-search candidates for ranking precision (one extra Haiku call, ~1.4s). Requires deep=true (no effect on AUTO/normal). Reserve for hard, ranking-sensitive queries where the right memory is likely retrieved but mis-ranked — skip for routine search. Default off.'),
+  sort: z
+    .enum(['relevance', 'time', 'importance'])
+    .optional()
+    .describe('Sort order: relevance (default, BM25), time (newest first), importance (highest first)'),
+  include_noise: coerceBool
+    .optional()
+    .describe(
+      'Include hook-llm fallback titles ("Modified X", "Worked on X", raw error logs) — hidden by default as they have ~3% access rate',
+    ),
+  or: coerceBool
+    .optional()
+    .describe(
+      'Force OR semantics between query terms from the start (default: AND with automatic OR-fallback when AND returns 0). Aligns with CLI --or.',
+    ),
+  deep: coerceBool
+    .optional()
+    .describe(
+      'Tri-state LLM multi-query/HyDE deep search (observations-only). true=force; false=never; omit=AUTO (default ON for mem_search): a normal search that returns weak/few results auto-escalates with ONE Haiku call (query rewritten to keyword/concept/HyDE variants, RRF-fused). Set CLAUDE_MEM_AUTO_DEEP=0 to disable AUTO. Passive recall stays single-query.',
+    ),
+  rerank: coerceBool
+    .optional()
+    .describe(
+      'Opt-in: LLM-rerank the deep-search candidates for ranking precision (one extra Haiku call, ~1.4s). Requires deep=true (no effect on AUTO/normal). Reserve for hard, ranking-sensitive queries where the right memory is likely retrieved but mis-ranked — skip for routine search. Default off.',
+    ),
   // ── CLI-flag aliases (v3.61.0) ──────────────────────────────────────────────
   // A property the schema doesn't declare is STRIPPED by the validator, so a caller
   // using the CLI vocabulary (`--source` / `--from` / `--to` / `--since`) previously
@@ -107,7 +158,12 @@ export const memSearchSchema = {
   // result set that reads as filtered. Declaring the aliases makes the filter apply;
   // the canonical name wins when both are supplied. Mirror of v3.59.0, which taught
   // the CLI to accept MCP field names.
-  source: z.enum(['observations', 'sessions', 'prompts', 'events']).optional().describe('Alias for `type` (CLI `search --source`). Note: CLI `--type` is the OBSERVATION type — that is `obs_type` here.'),
+  source: z
+    .enum(['observations', 'sessions', 'prompts', 'events'])
+    .optional()
+    .describe(
+      'Alias for `type` (CLI `search --source`). Note: CLI `--type` is the OBSERVATION type — that is `obs_type` here.',
+    ),
   from: z.string().optional().describe('Alias for `date_from` (CLI `search --from`)'),
   to: z.string().optional().describe('Alias for `date_to` (CLI `search --to`)'),
   since: z.string().optional().describe('Alias for `date_since` (CLI `search --since`)'),
@@ -116,8 +172,15 @@ export const memSearchSchema = {
 export const memRecentSchema = {
   limit: coerceInt.pipe(z.number().int().min(1).max(100)).optional().describe('Max results (default 10)'),
   project: z.string().optional().describe('Filter by project (default: inferred from CWD)'),
-  obs_type: OBS_TYPE_ENUM.optional().describe('Filter observation type (e.g. bugfix, decision) — CLI `recent --type` parity'),
-  date_since: z.string().optional().describe('Relative lower bound from now: 7d/24h/90m/2w/30s. Only items newer than the window (pair with a high limit for "everything since X")'),
+  obs_type: OBS_TYPE_ENUM.optional().describe(
+    'Filter observation type (e.g. bugfix, decision) — CLI `recent --type` parity',
+  ),
+  date_since: z
+    .string()
+    .optional()
+    .describe(
+      'Relative lower bound from now: 7d/24h/90m/2w/30s. Only items newer than the window (pair with a high limit for "everything since X")',
+    ),
   // CLI-flag aliases — see the note on memSearchSchema. `recent --type` IS the
   // observation type here (unlike `search --type`, which the CLI spells `--source`),
   // so `type` maps to obs_type on this tool.
@@ -138,17 +201,27 @@ const coerceAnchor = z.preprocess(
     }
     return v;
   },
-  z.union([
-    z.number().int(),
-    z.string().regex(/^[EePpSs]?#?\d+$/, 'Expected N, #N, P#N, S#N, or E#N'),
-  ])
+  z.union([z.number().int(), z.string().regex(/^[EePpSs]?#?\d+$/, 'Expected N, #N, P#N, S#N, or E#N')]),
 );
 
 export const memTimelineSchema = {
-  anchor: coerceAnchor.optional().describe('Anchor as observation ID (int) or prefixed token string: "#123", "P#123" (prompt → nearest obs), "S#123" (session → nearest obs), "E#123" (event → nearest obs). Takes precedence over query.'),
-  query: z.string().optional().describe('FTS5 query to auto-find anchor. Ignored when anchor is also given; use one or the other.'),
-  before: coerceInt.pipe(z.number().int().min(0).max(50)).optional().describe('Items before anchor (default 5)'),
-  after: coerceInt.pipe(z.number().int().min(0).max(50)).optional().describe('Items after anchor (default 5)'),
+  anchor: coerceAnchor
+    .optional()
+    .describe(
+      'Anchor as observation ID (int) or prefixed token string: "#123", "P#123" (prompt → nearest obs), "S#123" (session → nearest obs), "E#123" (event → nearest obs). Takes precedence over query.',
+    ),
+  query: z
+    .string()
+    .optional()
+    .describe('FTS5 query to auto-find anchor. Ignored when anchor is also given; use one or the other.'),
+  before: coerceInt
+    .pipe(z.number().int().min(0).max(50))
+    .optional()
+    .describe('Items before anchor (default 5)'),
+  after: coerceInt
+    .pipe(z.number().int().min(0).max(50))
+    .optional()
+    .describe('Items after anchor (default 5)'),
   project: z.string().optional().describe('Filter by project'),
 };
 
@@ -156,9 +229,20 @@ export const memGetSchema = {
   // Accepts mixed tokens so pasted search results work verbatim: [1], [1, "P#2"], "1,P#2,S#3",
   // or the JSON-stringified form ["1","P#2"]. Each token's prefix routes to its source bucket
   // in server.mjs via lib/id-routing.bucketIdTokens. An explicit `source` override still wins.
-  ids: coerceMixedIdTokens.describe('Mixed observation/prompt/session/event/deferred IDs — accepts N, #N, P#N, S#N, E#N, D#N; comma-strings and JSON arrays also coerced. D#N reads a deferred_work item with FULL detail (defer list is title-only)'),
-  source: z.enum(['obs', 'session', 'prompt', 'event']).optional().describe('Force all IDs to this source (overrides per-token prefixes). Omit to let P#/S#/E#/# prefixes route individually. D#N tokens are exempt — they always read deferred_work.'),
-  fields: coerceStringArray.optional().describe('Specific fields to return (default: all; validated against obs schema — session/prompt sources ignore this filter)'),
+  ids: coerceMixedIdTokens.describe(
+    'Mixed observation/prompt/session/event/deferred IDs — accepts N, #N, P#N, S#N, E#N, D#N; comma-strings and JSON arrays also coerced. D#N reads a deferred_work item with FULL detail (defer list is title-only)',
+  ),
+  source: z
+    .enum(['obs', 'session', 'prompt', 'event'])
+    .optional()
+    .describe(
+      'Force all IDs to this source (overrides per-token prefixes). Omit to let P#/S#/E#/# prefixes route individually. D#N tokens are exempt — they always read deferred_work.',
+    ),
+  fields: coerceStringArray
+    .optional()
+    .describe(
+      'Specific fields to return (default: all; validated against obs schema — session/prompt sources ignore this filter)',
+    ),
 };
 
 export const memDeleteSchema = {
@@ -173,7 +257,7 @@ export const memDeleteSchema = {
 const coerceDeferredTokens = z.preprocess(
   (v) => {
     if (Array.isArray(v)) {
-      return v.map(x => {
+      return v.map((x) => {
         if (typeof x === 'number') return x;
         if (typeof x === 'string') {
           const s = x.trim();
@@ -185,10 +269,15 @@ const coerceDeferredTokens = z.preprocess(
     }
     return v;
   },
-  z.array(z.union([
-    z.number().int().positive(),
-    z.string().regex(/^D#\d+$/, 'expected D#N (raw id) or positive integer (ordinal)'),
-  ])).min(1).max(20)
+  z
+    .array(
+      z.union([
+        z.number().int().positive(),
+        z.string().regex(/^D#\d+$/, 'expected D#N (raw id) or positive integer (ordinal)'),
+      ]),
+    )
+    .min(1)
+    .max(20),
 );
 
 // Coerce supersedes input — positive observation ids, plus `E#<n>` for an EVENT row
@@ -198,13 +287,19 @@ const coerceDeferredTokens = z.preprocess(
 // a number here would lose the only thing that says which table it names.
 // Empty/other shapes reject.
 const coerceSupersedes = z.preprocess(
-  (v) => (Array.isArray(v)
-    ? v.map(x => (typeof x === 'string' && /^\d+$/.test(x.trim()) ? parseInt(x.trim(), 10) : x))
-    : v),
-  z.array(z.union([
-    z.number().int().positive(),
-    z.string().regex(/^[Ee]#?\d+$/, 'expected a positive observation id or E#<n> for an event'),
-  ])).min(1).max(20)
+  (v) =>
+    Array.isArray(v)
+      ? v.map((x) => (typeof x === 'string' && /^\d+$/.test(x.trim()) ? parseInt(x.trim(), 10) : x))
+      : v,
+  z
+    .array(
+      z.union([
+        z.number().int().positive(),
+        z.string().regex(/^[Ee]#?\d+$/, 'expected a positive observation id or E#<n> for an event'),
+      ]),
+    )
+    .min(1)
+    .max(20),
 );
 
 export const memSaveSchema = {
@@ -219,50 +314,122 @@ export const memSaveSchema = {
   // every `--type bugfix` filter, so it must not be a silent coercion.
   obs_type: OBS_TYPE_ENUM.optional().describe('Alias for `type` (parity with mem_search/mem_recent)'),
   project: z.string().optional().describe('Project name (default: inferred from CWD)'),
-  importance: coerceInt.pipe(z.number().int().min(1).max(3)).optional().describe('Importance level: 1=routine, 2=notable, 3=critical (default: 2 for explicit saves)'),
-  files: coerceStringArray.optional().describe('File paths associated with this observation. Stored in the `files_modified` column and rendered as `files` — passing a path here does not assert the file was edited; a file you only read belongs here too'),
-  lesson_learned: z.string().max(500).optional().describe('Key lesson or takeaway, ≤500 chars (for bugfix: root cause & fix; for decision: rationale)'),
-  closes_deferred: coerceDeferredTokens.optional().describe('Close one or more deferred_work items in the same project. Mixed array: bare integer = ordinal-within-project, "D#<n>" string = raw id. Transactional with the obs insert — a single invalid id rolls back the whole save.'),
-  supersedes: coerceSupersedes.optional().describe('Ids (same project) that this save overturns: a bare number for an observation, or E#<n> for an event — the same prefix events are shown with in the injected lessons block, so you can retire one by typing back what you read. They are marked superseded (dropped from live search); observations are also linked to the new row via superseded_by, events are not, because that column can only reference another event. Use ONLY when this genuinely replaces a prior conclusion; do NOT use for merely-related or updated-but-still-valid memories.'),
+  importance: coerceInt
+    .pipe(z.number().int().min(1).max(3))
+    .optional()
+    .describe('Importance level: 1=routine, 2=notable, 3=critical (default: 2 for explicit saves)'),
+  files: coerceStringArray
+    .optional()
+    .describe(
+      'File paths associated with this observation. Stored in the `files_modified` column and rendered as `files` — passing a path here does not assert the file was edited; a file you only read belongs here too',
+    ),
+  lesson_learned: z
+    .string()
+    .max(500)
+    .optional()
+    .describe('Key lesson or takeaway, ≤500 chars (for bugfix: root cause & fix; for decision: rationale)'),
+  closes_deferred: coerceDeferredTokens
+    .optional()
+    .describe(
+      'Close one or more deferred_work items in the same project. Mixed array: bare integer = ordinal-within-project, "D#<n>" string = raw id. Transactional with the obs insert — a single invalid id rolls back the whole save.',
+    ),
+  supersedes: coerceSupersedes
+    .optional()
+    .describe(
+      'Ids (same project) that this save overturns: a bare number for an observation, or E#<n> for an event — the same prefix events are shown with in the injected lessons block, so you can retire one by typing back what you read. They are marked superseded (dropped from live search); observations are also linked to the new row via superseded_by, events are not, because that column can only reference another event. Use ONLY when this genuinely replaces a prior conclusion; do NOT use for merely-related or updated-but-still-valid memories.',
+    ),
 };
 
 export const memStatsSchema = {
   project: z.string().optional().describe('Filter by project'),
   days: coerceInt.pipe(z.number().int().min(1).max(365)).optional().describe('Look back N days (default 30)'),
-  quality: coerceBool.optional().describe('Return quality dashboard (lesson rate, LOW_SIGNAL rate, per-type hit/lesson %, top-accessed lessons, R-2 watchdog) instead of default stats. Aligns with CLI --quality.'),
+  quality: coerceBool
+    .optional()
+    .describe(
+      'Return quality dashboard (lesson rate, LOW_SIGNAL rate, per-type hit/lesson %, top-accessed lessons, R-2 watchdog) instead of default stats. Aligns with CLI --quality.',
+    ),
 };
 
 export const memCompressSchema = {
   preview: coerceBool.optional().describe('true=count candidates, false=execute compression (default: true)'),
-  age_days: coerceInt.pipe(z.number().int().min(30).max(365)).optional().describe('Min age in days (default: 30, minimum: 30)'),
+  age_days: coerceInt
+    .pipe(z.number().int().min(30).max(365))
+    .optional()
+    .describe('Min age in days (default: 30, minimum: 30)'),
   project: z.string().optional().describe('Filter by project'),
 };
 
 export const memOptimizeSchema = {
-  action: z.enum(['preview', 'run', 'run_all']).optional().default('preview')
+  action: z
+    .enum(['preview', 'run', 'run_all'])
+    .optional()
+    .default('preview')
     .describe('preview=scan candidates, run=execute with limits, run_all=bypass gates'),
-  tasks: z.array(z.enum(['re-enrich', 'normalize', 'cluster-merge', 'smart-compress'])).optional()
+  tasks: z
+    .array(z.enum(['re-enrich', 'normalize', 'cluster-merge', 'smart-compress']))
+    .optional()
     .describe('Which optimization tasks to run (default: all)'),
-  max_items: coerceInt.pipe(z.number().int().min(1).max(100)).optional().default(15)
+  max_items: coerceInt
+    .pipe(z.number().int().min(1).max(100))
+    .optional()
+    .default(15)
     .describe('Maximum LLM calls across all tasks (default: 15)'),
-  scope: z.enum(['narrow', 'wide']).optional().default('narrow')
-    .describe("Re-enrich scope: narrow=narrative-only candidates (default); wide=R-7 backfill (bugfix/refactor/feature/decision with narrative but lesson_learned='none'). CLI parity: --scope wide."),
-  project: z.string().optional().describe('Filter all 4 tasks to a single project. Default: scan all projects.'),
-  detail: coerceBool.optional().describe('preview action only — include cluster contents + re-enrich/compress sample arrays alongside aggregate counts.'),
+  scope: z
+    .enum(['narrow', 'wide'])
+    .optional()
+    .default('narrow')
+    .describe(
+      "Re-enrich scope: narrow=narrative-only candidates (default); wide=R-7 backfill (bugfix/refactor/feature/decision with narrative but lesson_learned='none'). CLI parity: --scope wide.",
+    ),
+  project: z
+    .string()
+    .optional()
+    .describe('Filter all 4 tasks to a single project. Default: scan all projects.'),
+  detail: coerceBool
+    .optional()
+    .describe(
+      'preview action only — include cluster contents + re-enrich/compress sample arrays alongside aggregate counts.',
+    ),
 };
 
 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=floor importance for obs injected>=8 times but never cited — to 1 with no lesson_learned, to 2 with one (v3.76.1: a lesson-bearing row keeps eligibility on every importance>=2 injection face) (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))
-  ).optional().describe('For dedup: [[keepId, removeId1, removeId2], ...] — first ID in each group is kept'),
-  retain_days: coerceInt.pipe(z.number().int().min(7).max(365)).optional()
+  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=floor importance for obs injected>=8 times but never cited — to 1 with no lesson_learned, to 2 with one (v3.76.1: a lesson-bearing row keeps eligibility on every importance>=2 injection face) (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)),
+    )
+    .optional()
+    .describe('For dedup: [[keepId, removeId1, removeId2], ...] — first ID in each group is kept'),
+  retain_days: coerceInt
+    .pipe(z.number().int().min(7).max(365))
+    .optional()
     .describe('For purge_stale: keep observations newer than N days (default 30)'),
-  confirm: coerceBool.optional()
-    .describe('Required for destructive ops in `execute` mode (currently: purge_stale). Omit/false → dry-run preview; true → actually delete.'),
+  confirm: coerceBool
+    .optional()
+    .describe(
+      'Required for destructive ops in `execute` mode (currently: purge_stale). Omit/false → dry-run preview; true → actually delete.',
+    ),
   project: z.string().optional().describe('Filter by project'),
 };
 
@@ -270,10 +437,18 @@ export const memUpdateSchema = {
   id: coerceInt.pipe(z.number().int().positive()).describe('Observation ID to update'),
   // CLI parity (cmdUpdate): empty/whitespace title would render as `(untitled)`
   // in every listing — reject here like the CLI does, instead of persisting it.
-  title: z.string().refine(s => s.trim() !== '', 'title cannot be empty').optional().describe('New title'),
+  title: z
+    .string()
+    .refine((s) => s.trim() !== '', 'title cannot be empty')
+    .optional()
+    .describe('New title'),
   // Reject empty content fields (parity with `title` above + cmdUpdate): an explicit
   // '' would blank narrative/lesson/concepts irrecoverably (mem_update takes no snapshot).
-  narrative: z.string().refine(s => s.trim() !== '', 'narrative cannot be empty').optional().describe('New narrative/content'),
+  narrative: z
+    .string()
+    .refine((s) => s.trim() !== '', 'narrative cannot be empty')
+    .optional()
+    .describe('New narrative/content'),
   type: OBS_TYPE_ENUM.optional().describe('New observation type'),
   // Same alias as memSaveSchema, for the same reason and found by the same review: without
   // it `mem_update({id, importance: 3, obs_type: 'bugfix'})` reported
@@ -283,8 +458,17 @@ export const memUpdateSchema = {
   importance: coerceInt.pipe(z.number().int().min(1).max(3)).optional().describe('New importance (1-3)'),
   // 500-char cap mirrors memSaveSchema + cmdUpdate — update was the one path
   // that let overlong lessons leak into the DB via MCP.
-  lesson_learned: z.string().max(500).refine(s => s.trim() !== '', 'lesson_learned cannot be empty').optional().describe('Add or update lesson learned'),
-  concepts: z.string().refine(s => s.trim() !== '', 'concepts cannot be empty').optional().describe('Space-separated concept tags'),
+  lesson_learned: z
+    .string()
+    .max(500)
+    .refine((s) => s.trim() !== '', 'lesson_learned cannot be empty')
+    .optional()
+    .describe('Add or update lesson learned'),
+  concepts: z
+    .string()
+    .refine((s) => s.trim() !== '', 'concepts cannot be empty')
+    .optional()
+    .describe('Space-separated concept tags'),
 };
 
 export const memExportSchema = {
@@ -305,13 +489,22 @@ export const memExportSchema = {
   // The default stays 200 because an MCP result is model context — a bare exploratory call
   // must not dump a whole store into the transcript — but a capped result now announces
   // itself as PARTIAL and names the limit that would return all of it.
-  limit: coerceInt.pipe(z.number().int().min(1)).optional().describe('Max observations to export (default: 200 — a capped result is flagged PARTIAL and names the total; pass that total for a complete backup, no upper bound)'),
+  limit: coerceInt
+    .pipe(z.number().int().min(1))
+    .optional()
+    .describe(
+      'Max observations to export (default: 200 — a capped result is flagged PARTIAL and names the total; pass that total for a complete backup, no upper bound)',
+    ),
 };
 
 export const memRecallSchema = {
   file: z.string().min(1).describe('File path or filename to recall observations for'),
   limit: coerceInt.pipe(z.number().int().min(1).max(50)).optional().describe('Max results (default 10)'),
-  include_noise: coerceBool.optional().describe('Include hook-llm fallback titles ("Modified X", "Worked on X", raw error logs) — hidden by default for parity with mem_search'),
+  include_noise: coerceBool
+    .optional()
+    .describe(
+      'Include hook-llm fallback titles ("Modified X", "Worked on X", raw error logs) — hidden by default for parity with mem_search',
+    ),
 };
 
 export const memFtsCheckSchema = {
@@ -319,12 +512,17 @@ export const memFtsCheckSchema = {
 };
 
 export const memRegistrySchema = {
-  action: z.enum(['list', 'stats', 'search', 'import', 'remove', 'reindex', 'import_url', 'enrich']).describe('Registry operation'),
+  action: z
+    .enum(['list', 'stats', 'search', 'import', 'remove', 'reindex', 'import_url', 'enrich'])
+    .describe('Registry operation'),
   query: z.string().optional().describe('Search query — keywords describing what you need (for search)'),
   type: z.enum(['skill', 'agent']).optional().describe('Filter by resource type (for list/search)'),
   name: z.string().optional().describe('Resource name (for import/remove)'),
   resource_type: z.enum(['skill', 'agent']).optional().describe('Resource type (for import/remove)'),
-  source: z.enum(['preinstalled', 'user', 'github']).optional().describe('Source (for import, default: user)'),
+  source: z
+    .enum(['preinstalled', 'user', 'github'])
+    .optional()
+    .describe('Source (for import, default: user)'),
   repo_url: z.string().optional().describe('GitHub repository URL (for import)'),
   local_path: z.string().optional().describe('Local file path (for import)'),
   invocation_name: z.string().optional().describe('Invocation name like "plugin:skill" (for import)'),
@@ -337,8 +535,14 @@ export const memRegistrySchema = {
   use_cases: z.string().optional().describe('Usage scenarios (for import)'),
   url: z.string().optional().describe('GitHub repository URL (for import_url action)'),
   enrich: coerceBool.optional().describe('Auto-enrich imported resources (for import_url action)'),
-  category: z.string().optional().describe("Filter by category (e.g., 'testing', 'code-quality', 'debugging')"),
-  quality: z.enum(['installed', 'verified', 'community']).optional().describe('Filter by quality tier (default: all)'),
+  category: z
+    .string()
+    .optional()
+    .describe("Filter by category (e.g., 'testing', 'code-quality', 'debugging')"),
+  quality: z
+    .enum(['installed', 'verified', 'community'])
+    .optional()
+    .describe('Filter by quality tier (default: all)'),
 };
 
 export const memUseSchema = {
@@ -349,12 +553,18 @@ export const memUseSchema = {
 export const memBrowseSchema = {
   project: z.string().optional().describe('Filter by project (default: inferred from CWD)'),
   tier: z.enum(['working', 'active', 'archive']).optional().describe('Show only this tier'),
-  limit: coerceInt.pipe(z.number().int().min(1).max(100)).optional().describe('Max entries per tier (default 5, or 20 when filtering by tier)'),
+  limit: coerceInt
+    .pipe(z.number().int().min(1).max(100))
+    .optional()
+    .describe('Max entries per tier (default 5, or 20 when filtering by tier)'),
 };
 
 export const memDeferSchema = {
   title: z.string().min(1).max(200).describe('One-line subject of the deferred item'),
-  priority: coerceInt.pipe(z.number().int().min(1).max(3)).optional().describe('1=low, 2=normal, 3=urgent (default: 2)'),
+  priority: coerceInt
+    .pipe(z.number().int().min(1).max(3))
+    .optional()
+    .describe('1=low, 2=normal, 3=urgent (default: 2)'),
   detail: z.string().max(2000).optional().describe('Optional longer description / constraint / why deferred'),
   files: coerceStringArray.optional().describe('Optional file paths this deferred item concerns'),
   project: z.string().optional().describe('Project name (default: inferred from CWD)'),
@@ -366,10 +576,12 @@ export const memDeferListSchema = {
 };
 
 export const memDeferDropSchema = {
-  id: z.union([
-    coerceInt.pipe(z.number().int().positive()),
-    z.string().regex(/^D#\d+$/, 'expected D#N or positive integer'),
-  ]).describe('Deferred item id — accepts D#N (raw id) or positive integer (ordinal-within-project)'),
+  id: z
+    .union([
+      coerceInt.pipe(z.number().int().positive()),
+      z.string().regex(/^D#\d+$/, 'expected D#N or positive integer'),
+    ])
+    .describe('Deferred item id — accepts D#N (raw id) or positive integer (ordinal-within-project)'),
   reason: z.string().min(1).max(500).describe('Why this item is being dropped (required for audit trail)'),
   project: z.string().optional().describe('Project name (default: inferred from CWD)'),
 };
@@ -418,7 +630,9 @@ export const tools = [
       '  - Looking for prior art on a module/feature before refactoring\n' +
       '  - A normal search missed — weak results auto-escalate to deep (set deep=false to opt out)\n' +
       '\n' +
-      'Equivalent CLI: ' + CLI_INVOKE + ' search "<query>" [--type bugfix] [--deep]',
+      'Equivalent CLI: ' +
+      CLI_INVOKE +
+      ' search "<query>" [--type bugfix] [--deep]',
     inputSchema: memSearchSchema,
   },
   {
@@ -436,7 +650,9 @@ export const tools = [
       '  - User asks "what did we do yesterday / last" with no topic keyword\n' +
       '  - Verifying that a just-made change was captured as an observation\n' +
       '\n' +
-      'Equivalent CLI: ' + CLI_INVOKE + ' recent [N]',
+      'Equivalent CLI: ' +
+      CLI_INVOKE +
+      ' recent [N]',
     inputSchema: memRecentSchema,
   },
   {
@@ -456,7 +672,9 @@ export const tools = [
       '  - A search hit is interesting and you want its chronological neighbours\n' +
       '  - Replaying a session narrative around a known observation ID\n' +
       '\n' +
-      'Equivalent CLI: ' + CLI_INVOKE + ' timeline --anchor <ID> [--before N --after N]',
+      'Equivalent CLI: ' +
+      CLI_INVOKE +
+      ' timeline --anchor <ID> [--before N --after N]',
     inputSchema: memTimelineSchema,
   },
   {
@@ -476,7 +694,9 @@ export const tools = [
       '\n' +
       'On miss, response includes "Try: …" hint listing other sources the ID lives in.\n' +
       '\n' +
-      'Equivalent CLI: ' + CLI_INVOKE + ' get <id>[,<id>,...] — accepts P#/S#/# prefix.',
+      'Equivalent CLI: ' +
+      CLI_INVOKE +
+      ' get <id>[,<id>,...] — accepts P#/S#/# prefix.',
     inputSchema: memGetSchema,
   },
   {
@@ -494,7 +714,9 @@ export const tools = [
       '  - Cleaning up an observation saved from a test run or incorrect save\n' +
       '  - Always run once with confirm=false, then again with confirm=true\n' +
       '\n' +
-      'Equivalent CLI: ' + CLI_INVOKE + ' delete <id>[,<id>,...] [--confirm]',
+      'Equivalent CLI: ' +
+      CLI_INVOKE +
+      ' delete <id>[,<id>,...] [--confirm]',
     inputSchema: memDeleteSchema,
     hidden: true,
   },
@@ -513,7 +735,9 @@ export const tools = [
       '  - After a non-obvious architecture/tradeoff decision — set type="decision", lesson_learned="<constraint + why>"\n' +
       '  - User explicitly asks "remember this" or "save a note that ..."\n' +
       '\n' +
-      'Equivalent CLI: ' + CLI_INVOKE + ' save --type bugfix --lesson "..." "<content>"',
+      'Equivalent CLI: ' +
+      CLI_INVOKE +
+      ' save --type bugfix --lesson "..." "<content>"',
     inputSchema: memSaveSchema,
   },
   {
@@ -531,7 +755,9 @@ export const tools = [
       '  - Diagnosing why search feels sparse or noisy at a macro level\n' +
       '  - Auditing a project before major compression/maintenance\n' +
       '\n' +
-      'Equivalent CLI: ' + CLI_INVOKE + ' stats [--project X] [--days 30]',
+      'Equivalent CLI: ' +
+      CLI_INVOKE +
+      ' stats [--project X] [--days 30]',
     inputSchema: memStatsSchema,
     hidden: true,
   },
@@ -550,7 +776,9 @@ export const tools = [
       '  - After a major project phase completes and old per-file observations are noise\n' +
       '  - Stats show thousands of low-importance rows dragging search quality\n' +
       '\n' +
-      'Equivalent CLI: ' + CLI_INVOKE + ' compress [--execute] [--age-days 90]  (preview is default)',
+      'Equivalent CLI: ' +
+      CLI_INVOKE +
+      ' compress [--execute] [--age-days 90]  (preview is default)',
     inputSchema: memCompressSchema,
     hidden: true,
   },
@@ -569,7 +797,9 @@ export const tools = [
       '  - After bulk imports or a long offline period\n' +
       '  - User asks for periodic maintenance / cleanup\n' +
       '\n' +
-      'Equivalent CLI: ' + CLI_INVOKE + ' maintain scan --ops dedup,decay',
+      'Equivalent CLI: ' +
+      CLI_INVOKE +
+      ' maintain scan --ops dedup,decay',
     inputSchema: memMaintainSchema,
     hidden: true,
   },
@@ -588,7 +818,9 @@ export const tools = [
       '  - stats show many degraded (title-only, no lesson) observations\n' +
       '  - Start with action="preview" to see candidates before spending tokens\n' +
       '\n' +
-      'Equivalent CLI: ' + CLI_INVOKE + ' optimize [--run|--run-all] [--task re-enrich,normalize,cluster-merge,smart-compress] [--max N]  (preview is default)',
+      'Equivalent CLI: ' +
+      CLI_INVOKE +
+      ' optimize [--run|--run-all] [--task re-enrich,normalize,cluster-merge,smart-compress] [--max N]  (preview is default)',
     inputSchema: memOptimizeSchema,
     hidden: true,
   },
@@ -607,7 +839,9 @@ export const tools = [
       '  - Looking for a tool by capability → action="search" with keywords\n' +
       '  - User explicitly asks to import a GitHub repo → action="import_url"\n' +
       '\n' +
-      'Equivalent CLI: ' + CLI_INVOKE + ' registry <list|search|import|...> [args]',
+      'Equivalent CLI: ' +
+      CLI_INVOKE +
+      ' registry <list|search|import|...> [args]',
     inputSchema: memRegistrySchema,
     hidden: true,
   },
@@ -615,7 +849,7 @@ export const tools = [
     name: 'mem_use',
     description:
       'Load and activate a skill or agent from the registry by EXACT name or invocation_name.\n' +
-      'A name that matches nothing returns closest-match names to pick from — never another resource\'s content.\n' +
+      "A name that matches nothing returns closest-match names to pick from — never another resource's content.\n" +
       '\n' +
       'DO NOT use when:\n' +
       '  - You have not confirmed the skill exists (run mem_registry action="list" first)\n' +
@@ -646,7 +880,9 @@ export const tools = [
       '  - You later discover additional context worth appending to lesson_learned\n' +
       '  - Reclassifying an observation after its true type becomes clear\n' +
       '\n' +
-      'Equivalent CLI: ' + CLI_INVOKE + ' update <id> [--title ...] [--lesson ...]',
+      'Equivalent CLI: ' +
+      CLI_INVOKE +
+      ' update <id> [--title ...] [--lesson ...]',
     inputSchema: memUpdateSchema,
     hidden: true,
   },
@@ -663,9 +899,11 @@ export const tools = [
       'USE when:\n' +
       '  - Backing up memory before a migration or reinstall\n' +
       '  - Moving observations between machines or projects\n' +
-      '  - User asks for a JSON snapshot of a project\'s memories\n' +
+      "  - User asks for a JSON snapshot of a project's memories\n" +
       '\n' +
-      'Equivalent CLI: ' + CLI_INVOKE + ' export [--format jsonl] [--project X] [--limit 500]',
+      'Equivalent CLI: ' +
+      CLI_INVOKE +
+      ' export [--format jsonl] [--project X] [--limit 500]',
     inputSchema: memExportSchema,
     hidden: true,
   },
@@ -684,7 +922,9 @@ export const tools = [
       '  - User asks "what do we know about <file>"\n' +
       '  - Investigating a recurring issue in a file you have not touched recently\n' +
       '\n' +
-      'Equivalent CLI: ' + CLI_INVOKE + ' recall "<file>" [--limit 10]',
+      'Equivalent CLI: ' +
+      CLI_INVOKE +
+      ' recall "<file>" [--limit 10]',
     inputSchema: memRecallSchema,
   },
   {
@@ -702,7 +942,9 @@ export const tools = [
       '  - After a crash, power loss, or manual DB edit\n' +
       '  - doctor / stats flags FTS integrity problems\n' +
       '\n' +
-      'Equivalent CLI: ' + CLI_INVOKE + ' fts-check <check|rebuild>',
+      'Equivalent CLI: ' +
+      CLI_INVOKE +
+      ' fts-check <check|rebuild>',
     inputSchema: memFtsCheckSchema,
     hidden: true,
   },
@@ -721,7 +963,9 @@ export const tools = [
       '  - Triaging what to compress or clean up before running maintenance\n' +
       '  - Scanning for interesting anchors to follow up with mem_timeline\n' +
       '\n' +
-      'Equivalent CLI: ' + CLI_INVOKE + ' browse [--tier active] [--project X]',
+      'Equivalent CLI: ' +
+      CLI_INVOKE +
+      ' browse [--tier active] [--project X]',
     inputSchema: memBrowseSchema,
     hidden: true,
   },
@@ -738,9 +982,11 @@ export const tools = [
       'USE when:\n' +
       '  - User says "下次/next session/留给下个会话/defer to next round"\n' +
       '  - Wrap-up phase enumerates follow-up items for the next session\n' +
-      '  - Bug surfaces but root cause is out of this session\'s scope\n' +
+      "  - Bug surfaces but root cause is out of this session's scope\n" +
       '\n' +
-      'Equivalent CLI: ' + CLI_INVOKE + ' defer add "<title>" [--priority 1|2|3] [--detail "..."] [--files a.mjs,b.mjs]',
+      'Equivalent CLI: ' +
+      CLI_INVOKE +
+      ' defer add "<title>" [--priority 1|2|3] [--detail "..."] [--files a.mjs,b.mjs]',
     inputSchema: memDeferSchema,
   },
   {
@@ -757,7 +1003,9 @@ export const tools = [
       '  - About to refer to "item N" and need to confirm what N points to\n' +
       '  - Auditing carry-forward state across multiple sessions\n' +
       '\n' +
-      'Equivalent CLI: ' + CLI_INVOKE + ' defer list [--project X] [--limit 10]',
+      'Equivalent CLI: ' +
+      CLI_INVOKE +
+      ' defer list [--project X] [--limit 10]',
     inputSchema: memDeferListSchema,
   },
   {
@@ -775,7 +1023,9 @@ export const tools = [
       '  - Scope changed and the work is no longer needed\n' +
       '  - User explicitly says "drop the deferred X, never mind"\n' +
       '\n' +
-      'Equivalent CLI: ' + CLI_INVOKE + ' defer drop <D#N|ordinal> --reason "..."',
+      'Equivalent CLI: ' +
+      CLI_INVOKE +
+      ' defer drop <D#N|ordinal> --reason "..."',
     inputSchema: memDeferDropSchema,
   },
 ];