@danielsimonjr/memory-mcp 12.2.3 → 12.5.2

package/dist/server/toolDefinitions.js

@@ -1846,9 +1846,30 @@ export const toolDefinitions = [
             additionalProperties: false,
         },
     },
-    // Phase 13: Config tool
-    // TODO: set_project_scope requires server state management (activeProjectId on MCPServer)
-    // Skipped in this pass — implement when MCPServer exposes mutable server state to handlers.
+    // Phase 13 (v12.3.2 backport): Active project scope. Mutable per-server state stored in a
+    // WeakMap keyed on ManagerContext (see toolHandlers.ts projectScopeMap). Handlers that
+    // want to apply the active scope may call getActiveProjectScope(ctx).
+    {
+        name: 'set_project_scope',
+        description: 'Set the active project scope for this server session. New entities passed without an explicit projectId may be auto-stamped with this value by scope-aware handlers; pass an empty string to clear the scope. Returns { projectId } where projectId is the new active scope (null when cleared).',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                projectId: { type: 'string', description: 'Project ID to scope to. Empty string clears the active scope.' },
+            },
+            required: ['projectId'],
+            additionalProperties: false,
+        },
+    },
+    {
+        name: 'get_project_scope',
+        description: 'Returns the active project scope for this server session (set via set_project_scope). Returns { projectId } where projectId is null when no scope is active.',
+        inputSchema: {
+            type: 'object',
+            properties: {},
+            additionalProperties: false,
+        },
+    },
     // ==================== SESSION & WORKING MEMORY TOOLS ====================
     {
         name: 'session_start',
@@ -2605,6 +2626,727 @@ export const toolDefinitions = [
             additionalProperties: false,
         },
     },
+    // ==================== v2.1.0 TOOL AFFORDANCE TOOLS ====================
+    {
+        name: 'record_tool_outcome',
+        description: 'v2.1.0 — Record a single tool-call outcome directly via ToolAffordanceManager (bypasses ToolCallObserver). Creates the record on first call; appends to rolling window on subsequent. Throws "conflict" on concurrent writer mismatch.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                toolName: { type: 'string' },
+                outcome: { type: 'string', enum: ['success', 'failure', 'partial'] },
+                errorMessage: { type: 'string', description: 'Required when outcome is failure or partial (ranked in commonFailureModes).' },
+                durationMs: { type: 'number', minimum: 0, description: 'Wall-clock duration. Optional.' },
+            },
+            required: ['toolName', 'outcome'],
+            additionalProperties: false,
+        },
+    },
+    {
+        name: 'get_tool_affordance_stats',
+        description: 'v2.1.0 — Flat rolling stats for a tool: success_rate, total_calls, common_failure_modes, avg_duration_ms.',
+        inputSchema: {
+            type: 'object',
+            properties: { toolName: { type: 'string' } },
+            required: ['toolName'],
+            additionalProperties: false,
+        },
+    },
+    {
+        name: 'suggest_tool',
+        description: 'v2.1.0 — Suggest tools matching a task hint, ranked by successRate × recency factor (1.0 at ≤1d, linearly decays to 0.1 at ≥30d).',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                taskHint: { type: 'string', description: 'Substring matched against toolName.' },
+                limit: { type: 'number', minimum: 1, description: 'Max candidates. Default 5.' },
+                minScore: { type: 'number', minimum: 0, maximum: 1, description: 'Default 0.' },
+            },
+            required: ['taskHint'],
+            additionalProperties: false,
+        },
+    },
+    {
+        name: 'list_tool_affordances',
+        description: 'v2.1.0 — All recorded ToolAffordanceRecords.',
+        inputSchema: { type: 'object', properties: {}, additionalProperties: false },
+    },
+    {
+        name: 'remove_tool_affordance',
+        description: 'v2.1.0 — Drop a tool-affordance record by toolName.',
+        inputSchema: {
+            type: 'object',
+            properties: { toolName: { type: 'string' } },
+            required: ['toolName'],
+            additionalProperties: false,
+        },
+    },
+    {
+        name: 'observe_tool_start',
+        description: 'v2.1.0 — Begin observing a tool call. Returns a callId the caller threads through observe_tool_complete / observe_tool_error / observe_tool_partial / observe_tool_cancel. Emits toolCall:start on the observer EventEmitter.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                toolName: { type: 'string' },
+                args: { type: 'object', additionalProperties: true, description: 'Optional structured args for telemetry.' },
+            },
+            required: ['toolName'],
+            additionalProperties: false,
+        },
+    },
+    {
+        name: 'observe_tool_complete',
+        description: 'v2.1.0 — Record successful completion. Computes durationMs from observe_tool_start. No-op on unknown callId.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                callId: { type: 'string' },
+                result: { type: 'string', description: 'Optional summary string for telemetry.' },
+            },
+            required: ['callId'],
+            additionalProperties: false,
+        },
+    },
+    {
+        name: 'observe_tool_error',
+        description: 'v2.1.0 — Record failure with an error message. No-op on unknown callId.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                callId: { type: 'string' },
+                errorMessage: { type: 'string' },
+            },
+            required: ['callId', 'errorMessage'],
+            additionalProperties: false,
+        },
+    },
+    {
+        name: 'observe_tool_partial',
+        description: 'v2.1.0 — Record a partial result (tool returned a usable but incomplete result). No-op on unknown callId.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                callId: { type: 'string' },
+                reason: { type: 'string' },
+            },
+            required: ['callId', 'reason'],
+            additionalProperties: false,
+        },
+    },
+    {
+        name: 'observe_tool_cancel',
+        description: 'v2.1.0 — Drop an in-flight observation without recording (e.g. user cancelled). No-op on unknown callId.',
+        inputSchema: {
+            type: 'object',
+            properties: { callId: { type: 'string' } },
+            required: ['callId'],
+            additionalProperties: false,
+        },
+    },
+    {
+        name: 'tool_observer_in_flight_count',
+        description: 'v2.1.0 — Diagnostic: number of in-flight (started but not yet completed) tool-call observations.',
+        inputSchema: { type: 'object', properties: {}, additionalProperties: false },
+    },
+    // ==================== v2.1.0 HEURISTIC GUIDELINES TOOLS ====================
+    {
+        name: 'add_heuristic',
+        description: 'v2.1.0 — Register a new condition→action heuristic. Storage-backed; default confidence 0.5. Pass an explicit content-addressed id (e.g. h_<sha256(condition|action)>) for caller-managed idempotency.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                condition: { type: 'string', description: 'Natural-language condition that triggers the action.' },
+                action: { type: 'string', description: 'Recommended action when the condition matches.' },
+                priority: { type: 'number', description: 'Tie-breaker when multiple match (higher wins).' },
+                initialConfidence: { type: 'number', minimum: 0, maximum: 1, description: 'Default 0.5.' },
+                importance: { type: 'number', minimum: 0, maximum: 10 },
+                agentId: { type: 'string' },
+                id: { type: 'string', description: 'Optional explicit id for idempotent registration.' },
+            },
+            required: ['condition', 'action'],
+            additionalProperties: false,
+        },
+    },
+    {
+        name: 'get_heuristic',
+        description: 'v2.1.0 — Sync lookup by HeuristicId.',
+        inputSchema: {
+            type: 'object',
+            properties: { id: { type: 'string' } },
+            required: ['id'],
+            additionalProperties: false,
+        },
+    },
+    {
+        name: 'list_heuristics',
+        description: 'v2.1.0 — All registered heuristics.',
+        inputSchema: { type: 'object', properties: {}, additionalProperties: false },
+    },
+    {
+        name: 'heuristic_count',
+        description: 'v2.1.0 — Count of stored heuristics.',
+        inputSchema: { type: 'object', properties: {}, additionalProperties: false },
+    },
+    {
+        name: 'match_heuristics',
+        description: 'v2.1.0 — Find heuristics whose condition matches input via Jaccard token-overlap × confidence; sorted descending, then by priority.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                input: { type: 'string', description: 'Text to match against heuristic conditions.' },
+                limit: { type: 'number', minimum: 1, description: 'Max matches returned. Default 10.' },
+                minScore: { type: 'number', minimum: 0, maximum: 1, description: 'Minimum score. Default 0.1.' },
+            },
+            required: ['input'],
+            additionalProperties: false,
+        },
+    },
+    {
+        name: 'reinforce_heuristic',
+        description: 'v2.1.0 — Record a successful application: bumps support; raises confidence asymptotically (new = old + (1-old)*0.1). OCC-protected — surfaces "conflict" when concurrent writer collides.',
+        inputSchema: {
+            type: 'object',
+            properties: { id: { type: 'string' } },
+            required: ['id'],
+            additionalProperties: false,
+        },
+    },
+    {
+        name: 'record_heuristic_contradiction',
+        description: 'v2.1.0 — Record a counter-example: bumps contradictions; lowers confidence (new = old - old*0.2). OCC-protected.',
+        inputSchema: {
+            type: 'object',
+            properties: { id: { type: 'string' } },
+            required: ['id'],
+            additionalProperties: false,
+        },
+    },
+    {
+        name: 'detect_heuristic_conflicts',
+        description: 'v2.1.0 — Pair-wise overlap/contradiction detection across stored heuristics. Surfaces overlap (same condition tokens, different actions) and contradiction (opposing actions on overlapping conditions; negation prefixes such as "do not" / "never" / "avoid").',
+        inputSchema: { type: 'object', properties: {}, additionalProperties: false },
+    },
+    {
+        name: 'remove_heuristic',
+        description: 'v2.1.0 — Drop a heuristic by id.',
+        inputSchema: {
+            type: 'object',
+            properties: { id: { type: 'string' } },
+            required: ['id'],
+            additionalProperties: false,
+        },
+    },
+    {
+        name: 'clear_heuristics',
+        description: 'v2.1.0 — Drop every heuristic (across all entities of type "heuristic").',
+        inputSchema: { type: 'object', properties: {}, additionalProperties: false },
+    },
+    // ==================== v2.1.0 PROJECT CONTEXT TOOLS ====================
+    {
+        name: 'upsert_project_context',
+        description: 'v2.1.0 — Merge structured project knowledge into the ProjectContextRecord for `projectId`. Array fields (facts/conventions/commands/glossary) append + dedup; scalars overwrite. One record per projectId.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                projectId: { type: 'string', description: 'Project identifier (unique key).' },
+                facts: { type: 'array', items: { type: 'string' } },
+                conventions: { type: 'array', items: { type: 'string' } },
+                commands: {
+                    type: 'array',
+                    items: {
+                        type: 'object',
+                        properties: {
+                            name: { type: 'string' },
+                            command: { type: 'string' },
+                            purpose: { type: 'string' },
+                        },
+                        required: ['name', 'command', 'purpose'],
+                    },
+                },
+                glossary: {
+                    type: 'array',
+                    items: {
+                        type: 'object',
+                        properties: {
+                            term: { type: 'string' },
+                            definition: { type: 'string' },
+                        },
+                        required: ['term', 'definition'],
+                    },
+                },
+            },
+            required: ['projectId'],
+            additionalProperties: false,
+        },
+    },
+    {
+        name: 'get_project_context',
+        description: 'v2.1.0 — Sync lookup of the ProjectContextRecord for projectId.',
+        inputSchema: {
+            type: 'object',
+            properties: { projectId: { type: 'string' } },
+            required: ['projectId'],
+            additionalProperties: false,
+        },
+    },
+    {
+        name: 'append_project_fact',
+        description: 'v2.1.0 — Append one fact to a project context (auto-creates the record on first call; dedups).',
+        inputSchema: {
+            type: 'object',
+            properties: { projectId: { type: 'string' }, fact: { type: 'string' } },
+            required: ['projectId', 'fact'],
+            additionalProperties: false,
+        },
+    },
+    {
+        name: 'append_project_convention',
+        description: 'v2.1.0 — Append one convention to a project context (auto-creates; dedups).',
+        inputSchema: {
+            type: 'object',
+            properties: { projectId: { type: 'string' }, convention: { type: 'string' } },
+            required: ['projectId', 'convention'],
+            additionalProperties: false,
+        },
+    },
+    {
+        name: 'append_project_command',
+        description: 'v2.1.0 — Append a documented project command (dedup by name).',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                projectId: { type: 'string' },
+                name: { type: 'string', description: 'Short command name (e.g. "test").' },
+                command: { type: 'string', description: 'The command line (e.g. "npm test").' },
+                purpose: { type: 'string', description: 'What the command does.' },
+            },
+            required: ['projectId', 'name', 'command', 'purpose'],
+            additionalProperties: false,
+        },
+    },
+    {
+        name: 'append_project_glossary_term',
+        description: 'v2.1.0 — Append a glossary term (dedup by term).',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                projectId: { type: 'string' },
+                term: { type: 'string' },
+                definition: { type: 'string' },
+            },
+            required: ['projectId', 'term', 'definition'],
+            additionalProperties: false,
+        },
+    },
+    {
+        name: 'remove_project_fact',
+        description: 'v2.1.0 — Remove a single fact. Returns true if found.',
+        inputSchema: {
+            type: 'object',
+            properties: { projectId: { type: 'string' }, fact: { type: 'string' } },
+            required: ['projectId', 'fact'],
+            additionalProperties: false,
+        },
+    },
+    {
+        name: 'remove_project_convention',
+        description: 'v2.1.0 — Remove a single convention. Returns true if found.',
+        inputSchema: {
+            type: 'object',
+            properties: { projectId: { type: 'string' }, convention: { type: 'string' } },
+            required: ['projectId', 'convention'],
+            additionalProperties: false,
+        },
+    },
+    {
+        name: 'remove_project_command',
+        description: 'v2.1.0 — Remove a command by name. Returns true if found.',
+        inputSchema: {
+            type: 'object',
+            properties: { projectId: { type: 'string' }, commandName: { type: 'string' } },
+            required: ['projectId', 'commandName'],
+            additionalProperties: false,
+        },
+    },
+    {
+        name: 'remove_project_glossary_term',
+        description: 'v2.1.0 — Remove a glossary entry by term. Returns true if found.',
+        inputSchema: {
+            type: 'object',
+            properties: { projectId: { type: 'string' }, term: { type: 'string' } },
+            required: ['projectId', 'term'],
+            additionalProperties: false,
+        },
+    },
+    {
+        name: 'clear_project_context',
+        description: 'v2.1.0 — Wipe the four arrays (facts/conventions/commands/glossary) for projectId; keeps the entity.',
+        inputSchema: {
+            type: 'object',
+            properties: { projectId: { type: 'string' } },
+            required: ['projectId'],
+            additionalProperties: false,
+        },
+    },
+    {
+        name: 'format_project_context_for_llm',
+        description: 'v2.1.0 — Render the ProjectContextRecord as a prose summary suitable for the wakeUp L0 layer or a system prompt. Honors budgetChars with ellipsis truncation.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                projectId: { type: 'string' },
+                budgetChars: { type: 'number', minimum: 1, description: 'Character cap for the rendered prose.' },
+            },
+            required: ['projectId'],
+            additionalProperties: false,
+        },
+    },
+    // ==================== v2.1.0 DECISION RATIONALE TOOLS ====================
+    {
+        name: 'propose_decision',
+        description: 'v2.1.0 — Propose a new architecture-decision-record (ADR-equivalent). Creates a "proposed" DecisionRecord. Default importance 8.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                context: { type: 'string', description: 'Problem-space description (the question the decision answers)' },
+                decision: { type: 'string', description: 'The chosen path' },
+                alternatives: { type: 'array', items: { type: 'string' }, description: 'Considered-but-not-chosen options. Default [].' },
+                consequences: { type: 'array', items: { type: 'string' }, description: 'Anticipated downstream effects. Default [].' },
+                relatedFiles: { type: 'array', items: { type: 'string' }, description: 'Optional paths to related ADRs / code.' },
+                supersedes: { type: 'string', description: 'Optional backward link to the decision being replaced (DecisionId).' },
+                sourceSessionId: { type: 'string' },
+                sourceProjectId: { type: 'string' },
+                importance: { type: 'number', minimum: 0, maximum: 10, description: 'Entity-level importance. Default 8.' },
+                agentId: { type: 'string', description: 'Owning agent.' },
+            },
+            required: ['context', 'decision'],
+            additionalProperties: false,
+        },
+    },
+    {
+        name: 'accept_decision',
+        description: 'v2.1.0 — Transition a proposed decision to accepted. Returns one of: accepted | already-accepted | not-found | illegal-transition | conflict | vanished-mid-update.',
+        inputSchema: {
+            type: 'object',
+            properties: { id: { type: 'string', description: 'DecisionId' } },
+            required: ['id'],
+            additionalProperties: false,
+        },
+    },
+    {
+        name: 'reject_decision',
+        description: 'v2.1.0 — Transition a proposed decision to rejected with a reason. Returns rejected | already-rejected | not-found | illegal-transition | conflict | vanished-mid-update.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                id: { type: 'string', description: 'DecisionId' },
+                reason: { type: 'string', description: 'Why the decision is being rejected.' },
+            },
+            required: ['id', 'reason'],
+            additionalProperties: false,
+        },
+    },
+    {
+        name: 'supersede_decision',
+        description: 'v2.1.0 — Mark an accepted decision as superseded by another. illegal-transition when target is not accepted. not-found when target or replacement is missing.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                id: { type: 'string', description: 'Decision being superseded' },
+                by: { type: 'string', description: 'DecisionId of the replacement' },
+            },
+            required: ['id', 'by'],
+            additionalProperties: false,
+        },
+    },
+    {
+        name: 'find_decisions_by_context',
+        description: 'v2.1.0 — Substring search across context, decision, and consequences fields.',
+        inputSchema: {
+            type: 'object',
+            properties: { query: { type: 'string', description: 'Substring to search for' } },
+            required: ['query'],
+            additionalProperties: false,
+        },
+    },
+    {
+        name: 'get_decision_chain',
+        description: 'v2.1.0 — Walk the supersedes link backward from the supplied id to the original proposal. Returns chain oldest-first; cycle-protected.',
+        inputSchema: {
+            type: 'object',
+            properties: { id: { type: 'string', description: 'Any DecisionId in the chain' } },
+            required: ['id'],
+            additionalProperties: false,
+        },
+    },
+    {
+        name: 'list_decisions',
+        description: 'v2.1.0 — List decisions, optionally filtered by status / sourceSessionId / sourceProjectId.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                status: { type: 'string', enum: ['proposed', 'accepted', 'superseded', 'rejected'] },
+                sourceSessionId: { type: 'string' },
+                sourceProjectId: { type: 'string' },
+                limit: { type: 'number', minimum: 1 },
+            },
+            additionalProperties: false,
+        },
+    },
+    {
+        name: 'get_decision',
+        description: 'v2.1.0 — Sync lookup by DecisionId.',
+        inputSchema: {
+            type: 'object',
+            properties: { id: { type: 'string', description: 'DecisionId' } },
+            required: ['id'],
+            additionalProperties: false,
+        },
+    },
+    {
+        name: 'export_decision_as_adr_markdown',
+        description: 'v2.1.0 — Render a stored decision as ADR-format markdown (# title, Status, Context, Decision, Consequences bullet list, Alternatives bullet list, optional Supersedes link).',
+        inputSchema: {
+            type: 'object',
+            properties: { id: { type: 'string', description: 'DecisionId' } },
+            required: ['id'],
+            additionalProperties: false,
+        },
+    },
+    {
+        name: 'parse_adr_markdown',
+        description: 'v2.1.0 — Parse a hand-written or previously-exported ADR markdown into a DecisionInput shape (static; no persistence). Returns null when required Context or Decision sections are missing.',
+        inputSchema: {
+            type: 'object',
+            properties: { text: { type: 'string', description: 'Raw ADR markdown text' } },
+            required: ['text'],
+            additionalProperties: false,
+        },
+    },
+    // ==================== v2.1.0 do_not_remember (Exclusion) TOOLS ====================
+    {
+        name: 'add_exclusion_rule',
+        description: 'v2.1.0 — Add a content-pattern exclusion rule (do_not_remember). Hard-deletes existing matches (per `scope`) and write-blocks future ones when consulted by upstream callers. v1 substring-only.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                pattern: { type: 'string', description: 'Substring to match (case-insensitive).' },
+                scope: {
+                    type: 'string',
+                    enum: ['future-only', 'past-only', 'both'],
+                    description: 'When the rule applies. Default: both.',
+                },
+                entityType: { type: 'string', description: 'Optional restriction by entityType.' },
+                reason: { type: 'string', description: 'Free-text justification (e.g. "GDPR request 2026-05-15").' },
+            },
+            required: ['pattern'],
+            additionalProperties: false,
+        },
+    },
+    {
+        name: 'list_exclusion_rules',
+        description: 'v2.1.0 — Return every registered ExclusionRule.',
+        inputSchema: { type: 'object', properties: {}, additionalProperties: false },
+    },
+    {
+        name: 'remove_exclusion_rule',
+        description: 'v2.1.0 — Drop an exclusion rule by id. Does NOT restore previously deleted memories — the contract is "user said forget".',
+        inputSchema: {
+            type: 'object',
+            properties: { id: { type: 'string', description: 'Rule id (exclusion-...)' } },
+            required: ['id'],
+            additionalProperties: false,
+        },
+    },
+    {
+        name: 'check_exclusion',
+        description: 'v2.1.0 — Check whether content would be blocked by any active forward-blocking rule. Returns {blocked, ruleId?, reason?}. Past-only rules are skipped.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                content: { type: 'string', description: 'Content to test.' },
+                entityType: { type: 'string', description: 'Optional entityType — narrows entityType-scoped rules.' },
+            },
+            required: ['content'],
+            additionalProperties: false,
+        },
+    },
+    {
+        name: 'find_matching_memories_for_rule',
+        description: 'v2.1.0 — Dry-run preview: return entities whose observations would match the candidate exclusion pattern. Does NOT persist the rule.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                pattern: { type: 'string', description: 'Candidate substring pattern.' },
+                entityType: { type: 'string', description: 'Optional entityType restriction.' },
+            },
+            required: ['pattern'],
+            additionalProperties: false,
+        },
+    },
+    // ==================== v2.1.0 OBSERVATION DEDUP TOOLS ====================
+    {
+        name: 'find_duplicate_observations',
+        description: 'v2.1.0 — Find verbatim duplicate observation strings across distinct entities (SHA-256 exact tier). Complementary to MemoryEngine.checkDuplicate (turn-level) and CompressionManager.findDuplicates (whole-entity). Report-only.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                entityType: {
+                    oneOf: [
+                        { type: 'string', description: 'Single entityType to include' },
+                        { type: 'array', items: { type: 'string' }, description: 'Multiple entityTypes to include' },
+                    ],
+                    description: 'Optional entityType filter (single or array). Omit to scan all.',
+                },
+                projectId: { type: 'string', description: 'Restrict to entities with this projectId.' },
+                sessionId: { type: 'string', description: 'Restrict to entities with this sessionId.' },
+                minOccurrences: { type: 'number', minimum: 2, description: 'Minimum occurrences to count as a group. Default 2.' },
+                maxGroups: { type: 'number', minimum: 1, description: 'Cap on groups returned. Default 100.' },
+            },
+            additionalProperties: false,
+        },
+    },
+    {
+        name: 'find_jaccard_duplicate_observations',
+        description: 'v2.1.0 — Find near-duplicate observation strings across distinct entities via token-Jaccard similarity with union-find grouping. More expensive than the exact tier (O(o²)); opt-in for higher recall.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                entityType: {
+                    oneOf: [
+                        { type: 'string' },
+                        { type: 'array', items: { type: 'string' } },
+                    ],
+                },
+                projectId: { type: 'string' },
+                sessionId: { type: 'string' },
+                minOccurrences: { type: 'number', minimum: 2 },
+                maxGroups: { type: 'number', minimum: 1 },
+            },
+            additionalProperties: false,
+        },
+    },
+    // ==================== v2.1.0 SPELL CORRECTION TOOLS ====================
+    {
+        name: 'spell_suggest',
+        description: 'v2.1.0 — Suggest close matches for a (potentially misspelled) query over the vocabulary of entity names + tag values. Two-stage: bigram-Jaccard pre-filter (NGramIndex) + Levenshtein re-rank.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                query: { type: 'string', description: 'The (potentially misspelled) query string' },
+                limit: { type: 'number', minimum: 1, description: 'Maximum corrections to return. Default 5.' },
+                minScore: { type: 'number', minimum: 0, maximum: 1, description: 'Minimum final similarity score (1 - distance/maxLen). Default 0.4.' },
+                maxDistance: { type: 'number', minimum: 0, description: 'Maximum Levenshtein edit distance to allow. Default 3.' },
+            },
+            required: ['query'],
+            additionalProperties: false,
+        },
+    },
+    {
+        name: 'spell_rebuild_vocabulary',
+        description: 'v2.1.0 — Force a rebuild of the SpellChecker vocabulary + n-gram index. Call after bulk entity churn; the lazy cache is otherwise correct for low-churn graphs.',
+        inputSchema: {
+            type: 'object',
+            properties: {},
+            additionalProperties: false,
+        },
+    },
+    {
+        name: 'spell_vocabulary_size',
+        description: 'v2.1.0 — Return the count of unique terms in the SpellChecker vocabulary (entity names + tag values by default). Mostly diagnostic.',
+        inputSchema: {
+            type: 'object',
+            properties: {},
+            additionalProperties: false,
+        },
+    },
+    // ==================== v12.5.0 ENGINEERING / DIAGNOSTIC TOOLS ====================
+    // Parallel surface to the memoryjs CLI engineering commands (`memory diag`,
+    // `memory check`, `memory reindex`, etc.). Useful when the MCP server is up
+    // but the graph state is suspect.
+    {
+        name: 'diag',
+        description: 'v12.5.0 — Runtime + storage diagnostic snapshot: node version, platform, storage path/type/size, entity + relation counts, ISO timestamp. Good first call when something feels off.',
+        inputSchema: { type: 'object', properties: {}, additionalProperties: false },
+    },
+    {
+        name: 'health',
+        description: 'v12.5.0 — Fast integrity checks: storage:loadGraph, entities:distinct-names, relations:no-orphans, hierarchy:no-cycles-no-missing-parents. Returns per-check duration; ok=false when any check fails.',
+        inputSchema: { type: 'object', properties: {}, additionalProperties: false },
+    },
+    {
+        name: 'check_graph',
+        description: 'v12.5.0 — Detect orphan relations (from/to references a missing entity), missing parents (entity.parentId references a missing entity), and hierarchy cycles. Reports findings. With apply=true, deletes orphan relations and clears missing parentIds; cycles are always reported but never auto-repaired (no safe default for which edge to break).',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                apply: { type: 'boolean', description: 'When true, repair orphan relations + missing parentIds. Default false (dry-run).' },
+            },
+            additionalProperties: false,
+        },
+    },
+    {
+        name: 'reindex',
+        description: 'v12.5.0 — Rebuild search-side indexes that may have drifted (TF-IDF/BM25 ranked + spell-checker vocabulary). Pass ranked=false or spell=false to scope. Returns per-target ok flag + durationMs.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                ranked: { type: 'boolean', description: 'Rebuild the ranked-search (TF-IDF/BM25) index (default true)' },
+                spell: { type: 'boolean', description: 'Rebuild the spell-checker vocabulary (default true)' },
+            },
+            additionalProperties: false,
+        },
+    },
+    {
+        name: 'cache_stats',
+        description: 'v12.5.0 — Per-tier snapshot of the global search caches (basic / ranked / boolean / fuzzy) showing hits / misses / size / hitRate. Process-local — every fresh server process starts at zero.',
+        inputSchema: { type: 'object', properties: {}, additionalProperties: false },
+    },
+    {
+        name: 'cache_clear',
+        description: 'v12.5.0 — Bust all four global search caches. Idempotent; safe after manual graph edits to drop stale results.',
+        inputSchema: { type: 'object', properties: {}, additionalProperties: false },
+    },
+    {
+        name: 'graph_size',
+        description: 'v12.5.0 — Graph + storage footprint: entity / relation / observation counts, distinct tag count, avg observations per entity, on-disk byte size + JSONL line count.',
+        inputSchema: { type: 'object', properties: {}, additionalProperties: false },
+    },
+    {
+        name: 'inspect_entity',
+        description: 'v12.5.0 — Verbose snapshot of one entity: observations (resolved via ObservationManager so the column-store sidecar is consulted), outgoing + incoming relations, tags, importance, timestamps, parentId, immediate children, full ancestors. Errors when entity not found.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                name: { type: 'string', description: 'Entity name to inspect' },
+            },
+            required: ['name'],
+            additionalProperties: false,
+        },
+    },
+    {
+        name: 'hierarchy_tree',
+        description: 'v12.5.0 — Hierarchy tree as nested JSON. With an explicit root, returns just that subtree; without, returns all root entities. Useful for visualising parent/child structure.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                root: { type: 'string', description: 'Root entity name. Omit to return all root entities.' },
+            },
+            additionalProperties: false,
+        },
+    },
+    {
+        name: 'entity_neighbors',
+        description: 'v12.5.0 — Incoming + outgoing relations for one entity, plus in/out degree counts. Lighter than inspect_entity when you only need the graph-topology view.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                name: { type: 'string', description: 'Entity name' },
+            },
+            required: ['name'],
+            additionalProperties: false,
+        },
+    },
 ];
 // Tool categories are documented in CLAUDE.md for reference:
 // - Entity Operations: create_entities, delete_entities, read_graph, open_nodes