Module: ClaudeMemory::MCP::ToolDefinitions

Defined in:
lib/claude_memory/mcp/tool_definitions.rb

Overview

MCP tool definitions for Claude Memory Pure data structure - no logic, just tool schemas

Constant Summary collapse

READ_ONLY =

Annotations for read-only query tools (safe to call anytime)

{readOnlyHint: true, idempotentHint: true, destructiveHint: false}.freeze
WRITE =

Annotations for state-changing but non-destructive tools

{readOnlyHint: false, idempotentHint: false, destructiveHint: false}.freeze
WRITE_IDEMPOTENT =

Annotations for idempotent writes (safe to retry)

{readOnlyHint: false, idempotentHint: true, destructiveHint: false}.freeze
PREDICATE_COUNT_SCHEMA =

Schema for count entries

{
  type: "object",
  properties: {
    predicate: {type: "string"},
    count: {type: "integer"}
  },
  required: ["predicate", "count"]
}.freeze
DATABASE_STATS_SCHEMA =

Schema for per-database stats block returned by memory.stats

{
  type: "object",
  properties: {
    exists: {type: "boolean"},
    schema_version: {type: "integer"},
    facts: {
      type: "object",
      properties: {
        total: {type: "integer"},
        active: {type: "integer"},
        superseded: {type: "integer"},
        top_predicates: {
          type: "array",
          description: "Top 10 predicates by count (known + novel combined)",
          items: PREDICATE_COUNT_SCHEMA
        },
        predicates_known: {
          type: "array",
          description: "Predicates with explicit cardinality policies in PredicatePolicy::POLICIES, sorted by count desc",
          items: PREDICATE_COUNT_SCHEMA
        },
        predicates_novel: {
          type: "array",
          description: "Predicates not in PredicatePolicy::POLICIES, sorted by count desc. Novel predicates with high counts are candidates for promotion to known status with explicit cardinality policies (canonicalization signal).",
          items: PREDICATE_COUNT_SCHEMA
        }
      }
    },
    entities: {
      type: "object",
      properties: {
        total: {type: "integer"},
        by_type: {type: "array", items: {type: "object"}}
      }
    },
    content_items: {type: "object"},
    provenance: {type: "object"},
    conflicts: {type: "object"},
    vec: {type: "object"}
  }
}.freeze

Class Method Summary collapse

Class Method Details

.all ⇒ Array<Hash>

Returns array of tool definitions for MCP protocol

Returns:

  • (Array<Hash>) —

    Tool definitions with name, description, and inputSchema



72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
 
# File 'lib/claude_memory/mcp/tool_definitions.rb', line 72

def self.all
  [
    {
      name: "memory.recall",
      description: "Search facts matching a query from both global and project memory databases. Returns full facts with provenance (~800 tokens/result, ~300 with compact: true). For token-efficient browsing, use memory.recall_index first (~200 tokens/result), then memory.recall_details for selected facts.",
      inputSchema: {
        type: "object",
        properties: {
          query: {type: "string", description: "Search query for existing knowledge (e.g., 'authentication flow', 'error handling', 'database setup')"},
          intent: {type: "string", description: "Optional intent to disambiguate the query (e.g., 'migration' or 'performance' when query is 'database'). Steers search without replacing the query."},
          limit: {type: "integer", description: "Max results", default: 10},
          scope: {type: "string", enum: ["all", "global", "project"], description: "Filter by scope: 'all' (default), 'global', or 'project'", default: "all"},
          compact: {type: "boolean", description: "Omit provenance receipts for ~60% smaller responses (~800 → ~300 tokens/result)", default: false}
        },
        required: ["query"]
      },
      annotations: READ_ONLY
    },
    {
      name: "memory.recall_index",
      description: "Lightweight search returning fact previews, IDs, and token costs (~200 tokens/result). Step 1 of progressive disclosure: browse results here, then call memory.recall_details with selected fact IDs for full information (~500 tokens/fact). Saves ~60% tokens vs memory.recall when you only need a few facts.",
      inputSchema: {
        type: "object",
        properties: {
          query: {type: "string", description: "Search query for existing knowledge (e.g., 'client errors', 'database choice')"},
          intent: {type: "string", description: "Optional intent to disambiguate the query (e.g., 'schema' or 'optimization' when query is 'database'). Steers search without replacing the query."},
          limit: {type: "integer", description: "Maximum results to return", default: 20},
          scope: {type: "string", enum: ["all", "global", "project"], description: "Scope: 'all' (both), 'global' (user-wide), 'project' (current only)", default: "all"}
        },
        required: ["query"]
      },
      annotations: READ_ONLY
    },
    {
      name: "memory.recall_details",
      description: "Fetch full details for specific fact IDs (~500 tokens/fact). Step 2 of progressive disclosure: use after memory.recall_index to get provenance and metadata for selected facts only.",
      inputSchema: {
        type: "object",
        properties: {
          fact_ids: {type: "array", items: {type: "integer"}, description: "Fact IDs from memory.recall_index"},
          scope: {type: "string", enum: ["project", "global"], description: "Database to query", default: "project"}
        },
        required: ["fact_ids"]
      },
      annotations: READ_ONLY
    },
    {
      name: "memory.explain",
      description: "Get detailed explanation of a fact with provenance",
      inputSchema: {
        type: "object",
        properties: {
          fact_id: {description: "Fact ID (integer) or docid (8-char hex string) to explain"},
          scope: {type: "string", enum: ["global", "project"], description: "Which database to look in", default: "project"}
        },
        required: ["fact_id"]
      },
      annotations: READ_ONLY
    },
    {
      name: "memory.changes",
      description: "List recent fact changes from both databases",
      inputSchema: {
        type: "object",
        properties: {
          since: {type: "string", description: "ISO timestamp"},
          limit: {type: "integer", default: 20},
          scope: {type: "string", enum: ["all", "global", "project"], default: "all"}
        }
      },
      annotations: READ_ONLY
    },
    {
      name: "memory.conflicts",
      description: "List open conflicts from both databases",
      inputSchema: {
        type: "object",
        properties: {
          scope: {type: "string", enum: ["all", "global", "project"], default: "all"}
        }
      },
      annotations: READ_ONLY
    },
    {
      name: "memory.sweep_now",
      description: "Run maintenance sweep on a database. Use escalate: true for guaranteed progress (normal → aggressive → fallback).",
      inputSchema: {
        type: "object",
        properties: {
          budget_seconds: {type: "integer", default: 5},
          scope: {type: "string", enum: ["global", "project"], default: "project"},
          escalate: {type: "boolean", default: false, description: "Enable three-level escalation (normal → aggressive → fallback) to guarantee progress"}
        }
      },
      annotations: WRITE
    },
    {
      name: "memory.status",
      description: "Get memory system status for both databases",
      inputSchema: {
        type: "object",
        properties: {}
      },
      annotations: READ_ONLY
    },
    {
      name: "memory.stats",
      description: "Get detailed statistics about the memory system (facts by predicate, entities by type, provenance coverage, conflicts, database sizes).",
      inputSchema: {
        type: "object",
        properties: {
          scope: {type: "string", enum: ["all", "global", "project"], description: "Show stats for: all (default), global, or project", default: "all"}
        }
      },
      outputSchema: {
        type: "object",
        properties: {
          scope: {type: "string", enum: ["all", "global", "project"]},
          databases: {
            type: "object",
            description: "Per-database stats. Keys are 'global', 'project', or 'legacy' depending on connection mode.",
            properties: {
              global: DATABASE_STATS_SCHEMA,
              project: DATABASE_STATS_SCHEMA,
              legacy: DATABASE_STATS_SCHEMA
            }
          }
        },
        required: ["scope", "databases"]
      },
      annotations: READ_ONLY
    },
    {
      name: "memory.promote",
      description: "Promote a project fact to global memory. Use when user says a preference should apply everywhere.",
      inputSchema: {
        type: "object",
        properties: {
          fact_id: {type: "integer", description: "Project fact ID to promote to global"}
        },
        required: ["fact_id"]
      },
      annotations: WRITE_IDEMPOTENT
    },
    {
      name: "memory.reject_fact",
      description: "Mark a fact as rejected (e.g. a distiller hallucination). Sets status to 'rejected' and closes any open conflicts involving the fact. Use when the user confirms a fact is wrong.",
      inputSchema: {
        type: "object",
        properties: {
          fact_id: {type: "integer", description: "Fact ID to reject"},
          docid: {type: "string", description: "8-char docid (alternative to fact_id)"},
          reason: {type: "string", description: "Why the fact is wrong (recorded in conflict notes)"},
          scope: {type: "string", enum: ["project", "global"], description: "Database scope", default: "project"}
        }
      },
      annotations: WRITE_IDEMPOTENT
    },
    {
      name: "memory.store_extraction",
      description: "Store extracted facts, entities, and decisions from a conversation. Call this to persist knowledge you've learned during the session.",
      inputSchema: {
        type: "object",
        properties: {
          entities: {
            type: "array",
            description: "Entities mentioned (databases, frameworks, services, etc.)",
            items: {
              type: "object",
              properties: {
                type: {type: "string", description: "Entity type. Common types: database, framework, language, platform, repo, module, person, service, tool, library, concept. You may use other types if needed."},
                name: {type: "string", description: "Canonical name"},
                confidence: {type: "number", description: "0.0-1.0 extraction confidence"}
              },
              required: ["type", "name"]
            }
          },
          facts: {
            type: "array",
            description: "Facts learned during the session",
            items: {
              type: "object",
              properties: {
                subject: {type: "string", description: "Entity name or 'repo' for project-level facts"},
                predicate: {type: "string", description: "Relationship type. Known predicates: #{ClaudeMemory::Resolve::PredicatePolicy.known_predicates.join(", ")}. You may use other snake_case predicates for relations that don't fit these — be specific and reuse existing predicates when possible."},
                object: {type: "string", description: "The value or target entity"},
                confidence: {type: "number", description: "0.0-1.0 how confident"},
                quote: {type: "string", description: "Source text excerpt (max 200 chars)"},
                strength: {type: "string", enum: ["stated", "inferred"], description: "Was this explicitly stated or inferred?"},
                scope_hint: {type: "string", enum: ["project", "global"], description: "Should this apply to just this project or globally?"}
              },
              required: ["subject", "predicate", "object"]
            }
          },
          decisions: {
            type: "array",
            description: "Decisions made during the session",
            items: {
              type: "object",
              properties: {
                title: {type: "string", description: "Short summary (max 100 chars)"},
                summary: {type: "string", description: "Full description"},
                status_hint: {type: "string", enum: ["accepted", "proposed", "rejected"]}
              },
              required: ["title", "summary"]
            }
          },
          scope: {type: "string", enum: ["global", "project"], description: "Default scope for facts", default: "project"}
        },
        required: ["facts"]
      },
      annotations: WRITE
    },
    {
      name: "memory.decisions",
      description: "List architectural decisions, constraints, and rules.",
      inputSchema: {
        type: "object",
        properties: {
          limit: {type: "integer", default: 10, description: "Maximum results to return"}
        }
      },
      annotations: READ_ONLY
    },
    {
      name: "memory.conventions",
      description: "List coding conventions and style preferences from global memory.",
      inputSchema: {
        type: "object",
        properties: {
          limit: {type: "integer", default: 20, description: "Maximum results to return"}
        }
      },
      annotations: READ_ONLY
    },
    {
      name: "memory.architecture",
      description: "List framework choices and architectural patterns.",
      inputSchema: {
        type: "object",
        properties: {
          limit: {type: "integer", default: 10, description: "Maximum results to return"}
        }
      },
      annotations: READ_ONLY
    },
    {
      name: "memory.facts_by_tool",
      description: "Find facts discovered using a specific tool (Read, Edit, Bash, etc.)",
      inputSchema: {
        type: "object",
        properties: {
          tool_name: {type: "string", description: "Tool name (Read, Edit, Bash, etc.)"},
          limit: {type: "integer", default: 20, description: "Maximum results to return"},
          scope: {type: "string", enum: ["all", "global", "project"], default: "all", description: "Filter by scope"}
        },
        required: ["tool_name"]
      },
      annotations: READ_ONLY
    },
    {
      name: "memory.facts_by_context",
      description: "Find facts learned in specific context (branch, directory)",
      inputSchema: {
        type: "object",
        properties: {
          git_branch: {type: "string", description: "Git branch name"},
          cwd: {type: "string", description: "Working directory path"},
          limit: {type: "integer", default: 20, description: "Maximum results to return"},
          scope: {type: "string", enum: ["all", "global", "project"], default: "all", description: "Filter by scope"}
        }
      },
      annotations: READ_ONLY
    },
    {
      name: "memory.recall_semantic",
      description: "Search facts using semantic similarity (finds conceptually related facts using vector embeddings). ~800 tokens/result, ~300 with compact: true.",
      inputSchema: {
        type: "object",
        properties: {
          query: {type: "string", description: "Search query"},
          intent: {type: "string", description: "Optional intent to disambiguate the query (e.g., 'security' when query is 'authentication'). Disables BM25 shortcut to ensure vector search runs."},
          mode: {type: "string", enum: ["vector", "text", "both"], default: "both", description: "Search mode: vector (embeddings), text (FTS), or both (hybrid)"},
          limit: {type: "integer", default: 10, description: "Maximum results to return"},
          scope: {type: "string", enum: ["all", "global", "project"], default: "all", description: "Filter by scope"},
          compact: {type: "boolean", description: "Omit provenance receipts for ~60% smaller responses (~800 → ~300 tokens/result)", default: false},
          explain: {type: "boolean", description: "Include per-result score traces showing FTS rank, vector similarity, and RRF contribution", default: false}
        },
        required: ["query"]
      },
      annotations: READ_ONLY
    },
    {
      name: "memory.search_concepts",
      description: "Search for facts matching ALL of the provided concepts (AND query). Ranks by average similarity across all concepts.",
      inputSchema: {
        type: "object",
        properties: {
          concepts: {
            type: "array",
            items: {type: "string"},
            minItems: 2,
            maxItems: 5,
            description: "2-5 concepts that must all be present"
          },
          limit: {type: "integer", default: 10, description: "Maximum results to return"},
          scope: {type: "string", enum: ["all", "global", "project"], default: "all", description: "Filter by scope"},
          compact: {type: "boolean", description: "Omit provenance receipts for ~60% smaller responses (~800 → ~300 tokens/result)", default: false}
        },
        required: ["concepts"]
      },
      annotations: READ_ONLY
    },
    {
      name: "memory.fact_graph",
      description: "Build a dependency graph showing how facts relate through supersession and conflict links. Returns nodes (facts) and edges (supersedes/conflicts).",
      inputSchema: {
        type: "object",
        properties: {
          fact_id: {type: "integer", description: "Root fact ID to start traversal from"},
          depth: {type: "integer", description: "Maximum BFS traversal depth (1-5)", default: 2},
          scope: {type: "string", enum: ["global", "project"], description: "Which database to search", default: "project"}
        },
        required: ["fact_id"]
      },
      annotations: READ_ONLY
    },
    {
      name: "memory.undistilled",
      description: "List content items not yet deeply distilled. Returns raw transcript text for knowledge extraction.",
      inputSchema: {
        type: "object",
        properties: {
          limit: {type: "integer", default: 3, description: "Max items to return"},
          min_length: {type: "integer", default: 200, description: "Min text length (skip tiny deltas)"}
        }
      },
      annotations: READ_ONLY
    },
    {
      name: "memory.mark_distilled",
      description: "Mark a content item as distilled after extracting facts from it.",
      inputSchema: {
        type: "object",
        properties: {
          content_item_id: {type: "integer", description: "ID of the distilled content item"},
          facts_extracted: {type: "integer", default: 0, description: "Number of facts extracted"}
        },
        required: ["content_item_id"]
      },
      annotations: WRITE_IDEMPOTENT
    },
    {
      name: "memory.check_setup",
      description: "Check ClaudeMemory initialization status. Returns version info, issues found, and recommendations.",
      inputSchema: {
        type: "object",
        properties: {}
      },
      annotations: READ_ONLY
    },
    {
      name: "memory.list_projects",
      description: "List all known memory databases with fact counts and status. Shows global database, current project, and other projects discovered from promoted facts. Helps discover available search scopes before querying.",
      inputSchema: {
        type: "object",
        properties: {}
      },
      annotations: READ_ONLY
    }
  ]
end