@danielsimonjr/memory-mcp 12.2.3 → 12.7.0

package/dist/server/toolDefinitions.js

@@ -2,7 +2,7 @@
  * MCP Tool Definitions
  *
  * Extracted from MCPServer.ts to reduce file size and improve maintainability.
- * Contains all 106 tool schemas for the Knowledge Graph MCP Server.
+ * Contains all 241 tool schemas for the Knowledge Graph MCP Server.
  *
  * @module server/toolDefinitions
  */
@@ -476,7 +476,7 @@ export const toolDefinitions = [
     // Phase 11 Sprint 2: Hybrid Search
     {
         name: 'hybrid_search',
-        description: 'Search using combined semantic, lexical, and metadata signals. Provides better recall than single-signal search by fusing multiple relevance signals.',
+        description: 'Search using combined semantic, lexical, and metadata signals. Provides better recall than single-signal search by fusing multiple relevance signals. v3 additive options: graphWeight adds a graph-connectivity (PageRank) channel, expandNeighbors appends one-hop neighbors of top results, explain annotates results with evidence paths from query anchors, lookFor ranks expansion neighbors by a free-text connection description.',
         inputSchema: {
             type: 'object',
             properties: {
@@ -531,6 +531,27 @@ export const toolDefinitions = [
                     additionalProperties: false,
                 },
                 limit: { type: 'number', description: 'Maximum results to return (default: 10)' },
+                graphWeight: {
+                    type: 'number',
+                    description: 'Weight for the graph-connectivity channel (normalized PageRank). 0/omitted = channel disabled (default)',
+                },
+                expandNeighbors: {
+                    type: 'object',
+                    description: 'One-hop neighbor expansion: neighbors of the top-K results are appended with a damped score and re-sorted',
+                    properties: {
+                        topK: { type: 'number', description: 'Number of top-ranked results to expand from (default: 10)' },
+                        damping: { type: 'number', description: "Damping factor applied to the parent's combined score (default: 0.3)" },
+                    },
+                    additionalProperties: false,
+                },
+                explain: {
+                    type: 'boolean',
+                    description: 'Annotate each result with evidencePaths — graph paths connecting query anchor matches to the result (default: false)',
+                },
+                lookFor: {
+                    type: 'string',
+                    description: 'Free-text description of the desired connection; expansion neighbors are ranked by similarity to it (lookForScore)',
+                },
             },
             required: ['query'],
             additionalProperties: false,
@@ -1846,9 +1867,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 +2647,958 @@ 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,
+        },
+    },
+    // ==================== EVENT MEMORY TOOLS (memoryjs v3.0.0) ====================
+    {
+        name: 'record_event',
+        description: 'Record an n-ary event: the action becomes a first-class event hub entity with role-typed relations (actor_of/targeted/occurred_in/participant_in). Missing endpoints auto-create as concept stubs. Optional flowKey groups events into a named flow.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                action: { type: 'string', description: 'The verb — what happened (e.g. "deployed", "approved")' },
+                actor: { type: 'string', description: 'Entity name of who performed the action' },
+                target: { type: 'string', description: 'Entity name the action was performed on' },
+                context: { type: 'string', description: 'Entity name of where/within-what the event occurred' },
+                participants: { type: 'array', items: { type: 'string' }, description: 'Additional participant entity names' },
+                occurredAt: { type: 'string', description: 'ISO 8601 timestamp of when the event occurred' },
+                flowKey: { type: 'string', description: 'Flow key grouping related events (case-insensitive)' },
+                detail: { type: 'array', items: { type: 'string' }, description: 'Free-text detail observations attached to the event' },
+                importance: { type: 'number', description: 'Importance score for the event entity' },
+            },
+            required: ['action', 'actor'],
+            additionalProperties: false,
+        },
+    },
+    {
+        name: 'get_event',
+        description: 'Load one recorded event by its entity name, joining the event hub with its role-typed relation endpoints (actor, target, context, participants).',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                name: { type: 'string', description: 'Event entity name (as returned by record_event / query_events)' },
+            },
+            required: ['name'],
+            additionalProperties: false,
+        },
+    },
+    {
+        name: 'query_events',
+        description: 'Query recorded events by any combination of actor, target, action, flowKey, and inclusive time range. Results are chronologically ordered (occurredAt, falling back to createdAt). Uses relation/type indexes — never a full-graph scan.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                actor: { type: 'string', description: 'Filter by actor entity name' },
+                target: { type: 'string', description: 'Filter by target entity name' },
+                action: { type: 'string', description: 'Filter by action verb' },
+                flowKey: { type: 'string', description: 'Filter by flow key' },
+                timeRange: {
+                    type: 'object',
+                    properties: {
+                        start: { type: 'string', description: 'Inclusive lower bound (ISO 8601)' },
+                        end: { type: 'string', description: 'Inclusive upper bound (ISO 8601)' },
+                    },
+                    additionalProperties: false,
+                    description: 'Inclusive time range; either bound may be omitted',
+                },
+                limit: { type: 'number', description: 'Max events to return' },
+            },
+            additionalProperties: false,
+        },
+    },
+    {
+        name: 'get_event_flow',
+        description: 'All events sharing a flow key (flow:<key> tag), chronologically ordered — the full timeline of a named flow (e.g. a release, an incident).',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                flowKey: { type: 'string', description: 'Flow key (case-insensitive)' },
+            },
+            required: ['flowKey'],
+            additionalProperties: false,
+        },
+    },
+    {
+        name: 'who_did_what',
+        description: 'Convenience join answering "who did what (to target / in context / within time range)?" over recorded events. Returns actor + action + event tuples; events without a resolvable actor are omitted.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                target: { type: 'string', description: 'Filter by target entity name' },
+                context: { type: 'string', description: 'Filter by context entity name' },
+                timeRange: {
+                    type: 'object',
+                    properties: {
+                        start: { type: 'string', description: 'Inclusive lower bound (ISO 8601)' },
+                        end: { type: 'string', description: 'Inclusive upper bound (ISO 8601)' },
+                    },
+                    additionalProperties: false,
+                    description: 'Inclusive time range; either bound may be omitted',
+                },
+                limit: { type: 'number', description: 'Max entries to return' },
+            },
+            additionalProperties: false,
+        },
+    },
+    // ==================== RECONSTRUCTIVE MEMORY TOOLS (memoryjs v3.0.0) ====================
+    {
+        name: 'ingest_dialogue',
+        description: 'Distill raw dialogue turns into the Cue–Tag–Content associative memory graph (MRAgent-style "memory is reconstructed, not retrieved"). Episodic/semantic/topic layers are also persisted into the live knowledge graph. Multiple calls accumulate.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                turns: {
+                    type: 'array',
+                    items: {
+                        type: 'object',
+                        properties: {
+                            id: { type: 'string', description: 'Unique turn id' },
+                            speaker: { type: 'string', description: 'Speaker name' },
+                            text: { type: 'string', description: 'Turn text' },
+                            timestamp: { type: 'string', description: 'ISO 8601 timestamp' },
+                        },
+                        required: ['id', 'text'],
+                        additionalProperties: false,
+                    },
+                    description: 'Dialogue turns to distill and ingest',
+                },
+            },
+            required: ['turns'],
+            additionalProperties: false,
+        },
+    },
+    {
+        name: 'reconstruct_memory',
+        description: 'Answer a query via active multi-step traversal of the reconstructive (Cue–Tag–Content) memory graph. Returns accumulated evidence, the step-by-step trajectory, and whether the loop stopped early on a satisfied condition vs. budget.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                query: { type: 'string', description: 'Query to reconstruct an answer for' },
+                maxSteps: { type: 'number', description: 'Max reasoning turns (default 8)' },
+                perStepBudget: { type: 'number', description: 'Max content nodes routed per step (default 10)' },
+                evidenceTarget: { type: 'number', description: 'Stop once this many distinct evidence items accumulate (default 12)' },
+            },
+            required: ['query'],
+            additionalProperties: false,
+        },
+    },
+    {
+        name: 'reconstructive_memory_stats',
+        description: 'Size statistics of the reconstructive (Cue–Tag–Content) memory graph: cue / tag / content node counts and edge counts.',
+        inputSchema: { type: 'object', properties: {}, additionalProperties: false },
+    },
+    // ==================== RELATION CONSOLIDATION TOOLS (memoryjs v3.0.0) ====================
+    {
+        name: 'analyze_relation_duplicates',
+        description: 'Dry-run the three-tier relation janitor: tier 1 finds trivial relationType spelling variants (WorksAt/works-at/works_at) and redundant bidirectional mirrors; tier 2 (when an embedding provider is configured) finds semantically equivalent same-pair relations. Report-only — never mutates the graph.',
+        inputSchema: { type: 'object', properties: {}, additionalProperties: false },
+    },
+    {
+        name: 'consolidate_relations',
+        description: 'Run relation-duplicate analysis and — when apply=true — merge tier 1+2 duplicate groups (delete variants, create the canonical survivor with summed confirmationCount). apply=false (default) is identical to analyze_relation_duplicates.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                apply: { type: 'boolean', description: 'Apply tier 1+2 merges (default false = dry-run)' },
+            },
+            additionalProperties: false,
+        },
+    },
+    // ==================== AGENT REFLECTION TOOLS (memoryjs v3.0.0) ====================
+    {
+        name: 'create_reflection',
+        description: 'Persist an agent reflection — a generalized lesson distilled from experience, backed by evidence entities. Deduplicated by evidence hash; scoped to session, project, or global.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                scope: { type: 'string', enum: ['session', 'project', 'global'], description: 'Generalization scope of the reflection' },
+                summary: { type: 'string', description: 'The reflection text (non-empty)' },
+                evidence: { type: 'array', items: { type: 'string' }, description: 'Entity names backing this reflection (non-empty)' },
+                generalizationConfidence: { type: 'number', description: 'Confidence in [0.0, 1.0] that the lesson generalizes' },
+                keyInsights: { type: 'array', items: { type: 'string' }, description: 'Top pattern strings (max 5)' },
+                experienceType: { type: 'string', description: 'Experience type label (e.g. "success", "failure")' },
+                sourceSessionId: { type: 'string', description: 'Session the reflection was distilled from' },
+                sourceProjectId: { type: 'string', description: 'Project the reflection was distilled from' },
+                importance: { type: 'number', description: 'Importance score for the reflection entity' },
+                agentId: { type: 'string', description: 'Agent that authored the reflection' },
+            },
+            required: ['scope', 'summary', 'evidence', 'generalizationConfidence'],
+            additionalProperties: false,
+        },
+    },
+    {
+        name: 'list_reflections',
+        description: 'List stored agent reflections, filterable by scope, source session/project, and minimum generalization confidence. Archived reflections are excluded unless includeArchived is set.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                scope: { type: 'string', enum: ['session', 'project', 'global'], description: 'Filter by scope' },
+                sourceSessionId: { type: 'string', description: 'Filter by source session' },
+                sourceProjectId: { type: 'string', description: 'Filter by source project' },
+                minConfidence: { type: 'number', description: 'Minimum generalization_confidence (inclusive)' },
+                includeArchived: { type: 'boolean', description: 'Include archived reflections (default false)' },
+                limit: { type: 'number', description: 'Max reflections to return' },
+            },
+            additionalProperties: false,
+        },
+    },
+    {
+        name: 'get_relevant_reflections',
+        description: 'Reflections relevant to a session: matches by sourceSessionId, plus evidence overlap with the supplied session entity names. Use at session start to surface applicable past lessons.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                sessionId: { type: 'string', description: 'Session to find relevant reflections for' },
+                sessionEntityNames: { type: 'array', items: { type: 'string' }, description: 'Entity names from the session for evidence-overlap matching' },
+                minConfidence: { type: 'number', description: 'Minimum generalization_confidence (inclusive)' },
+                limit: { type: 'number', description: 'Max reflections to return (default 10)' },
+            },
+            required: ['sessionId'],
+            additionalProperties: false,
+        },
+    },
+    {
+        name: 'archive_reflection',
+        description: 'Archive a reflection by id so it no longer appears in default listings or relevance matches (soft delete — the record is retained).',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                id: { type: 'string', description: 'Reflection id to archive' },
+            },
+            required: ['id'],
+            additionalProperties: false,
+        },
+    },
+    // ==================== RECONSTRUCTIVE MEMORY PERSISTENCE TOOLS (memoryjs v3.0.0) ====================
+    {
+        name: 'save_reconstructive_memory',
+        description: 'Serialize the in-memory Cue–Tag–Content reconstructive graph to a JSON sidecar next to the storage file (<basename>-reconstructive.json). The CTC graph is process-local; save before shutdown to survive restarts.',
+        inputSchema: { type: 'object', properties: {}, additionalProperties: false },
+    },
+    {
+        name: 'load_reconstructive_memory',
+        description: 'Restore the Cue–Tag–Content reconstructive graph from the <basename>-reconstructive.json sidecar written by save_reconstructive_memory, replacing the current in-memory graph. Errors if no sidecar exists.',
+        inputSchema: { type: 'object', properties: {}, additionalProperties: false },
+    },
 ];
 // Tool categories are documented in CLAUDE.md for reference:
 // - Entity Operations: create_entities, delete_entities, read_graph, open_nodes