mindgraph-mcp 0.3.3 → 0.3.4

package/dist/cli.js

@@ -874,7 +874,7 @@ var init_tools = __esm({
       },
       {
         name: "mindgraph_retrieve",
-        description: "Search the knowledge graph. Primary action: 'context' \u2014 pass a short keyword query (specific nouns/terms, not sentences) for FTS + graph traversal results. Use 'text' for fast keyword-only lookup. Other actions ('active_goals', 'open_questions', 'weak_claims', 'pending_approvals', 'unresolved_contradictions', 'layer', 'recent') are ONLY for when the user explicitly asks about those topics \u2014 never pre-fetch them.",
+        description: "Search the knowledge graph using BM25 keyword matching. Primary action: 'context' \u2014 pass 1\u20133 discriminating keywords (proper nouns, technical terms) extracted from the user's question. Drop filler words (what, how, tell me about, implications of). GOOD: 'Kissinger NATO', 'Rust async runtime'. BAD: 'What is Kissinger\\'s view on NATO?'. Use 'text' for fast keyword-only lookup. Other actions ('active_goals', 'open_questions', 'weak_claims', 'pending_approvals', 'unresolved_contradictions', 'layer', 'recent') are ONLY for when the user explicitly asks about those topics \u2014 never pre-fetch them.",
         inputSchema: {
           type: "object",
           properties: {
@@ -895,7 +895,7 @@ var init_tools = __esm({
             },
             query: {
               type: "string",
-              description: "Keyword search query \u2014 use specific nouns and terms, e.g. 'Rust async runtime' not 'what do I know about async in Rust' (for text, context)"
+              description: "BM25 keyword query \u2014 extract 1\u20133 discriminating terms from the user's question, drop filler words. User asks 'What is Kissinger's view on NATO?' \u2192 'Kissinger NATO'. User asks about async in Rust \u2192 'Rust async runtime'. NEVER pass natural language sentences. (for text, context)"
             },
             node_types: {
               type: "array",
@@ -1055,14 +1055,24 @@ When the user asks about something, your FIRST and ONLY action should be a SINGL
 There is no session to open. There is no context to pre-load. Just search for what the user asked about.
 
 **Example:** User says "Tell me about Indian philosophy and Taoism"
-\u2713 CORRECT: \`mindgraph_retrieve({action: "context", query: "Indian philosophy Taoism"})\`
+\u2713 CORRECT: \`mindgraph_retrieve({action: "context", query: "Indian philosophy Taoism"})\` \u2014 extracted key nouns, dropped "Tell me about"
 \u2717 WRONG: First retrieve active_goals, then open_questions, then search for the topic
+\u2717 WRONG: \`mindgraph_retrieve({action: "context", query: "Tell me about Indian philosophy and Taoism"})\` \u2014 natural language sentence won't match BM25 index
 
-## Search query style
+## Search query style \u2014 BM25 keyword matching
 
-Full-text search (BM25) \u2014 use short keyword phrases, not natural language:
-- GOOD: \`"Rust async runtime"\`, \`"Indian philosophy Taoism"\`
-- BAD: \`"what do I know about async programming in Rust?"\`
+The search index uses BM25 keyword matching against node labels and summaries. It matches individual words, NOT meaning or concepts. Drop filler words like "what", "how", "implications of", "tell me about". Query with 1\u20133 discriminating terms (proper nouns, technical terms, domain-specific words).
+
+**Derive keywords from the user's question \u2014 examples:**
+- User asks "What is Kissinger's view on NATO expansion?" \u2192 query: \`"Kissinger NATO"\`
+- User asks "Tell me about async programming in Rust" \u2192 query: \`"Rust async runtime"\`
+- User asks "How does Indian philosophy relate to Taoism?" \u2192 query: \`"Indian philosophy Taoism"\`
+- User asks "What are the implications of carbon tax policy?" \u2192 query: \`"carbon tax"\`
+
+**GOOD queries:** \`"Rust async runtime"\`, \`"Kissinger NATO"\`, \`"carbon tax emissions"\`
+**BAD queries:** \`"what do I know about async programming in Rust?"\`, \`"how does X relate to Y"\`, \`"implications of climate change"\`
+
+If the first query returns no results, try synonym or related terms (e.g. \`"global warming"\` instead of \`"climate change"\`).
 
 ## When to READ
 
@@ -1094,7 +1104,7 @@ Capture knowledge when the user shares something worth remembering:
     server = new import_server.Server(
       {
         name: "mindgraph",
-        version: "0.3.3"
+        version: "0.3.4"
       },
       {
         capabilities: {
@@ -1227,7 +1237,7 @@ Capture knowledge when the user shares something worth remembering:
                 role: "user",
                 content: {
                   type: "text",
-                  text: `Search my knowledge graph for everything related to "${topic}". Use context retrieval with keyword queries to find entities, claims, evidence, questions, and any connected knowledge. Try multiple keyword variations to ensure broad coverage. Present a structured overview of what I know about this topic, highlighting any gaps or open questions.`
+                  text: `Search my knowledge graph for everything related to "${topic}". Use context retrieval with short BM25 keyword queries (1\u20133 discriminating terms extracted from the topic, not full sentences). Try multiple keyword variations and synonyms to ensure broad coverage. Present a structured overview of what I know about this topic, highlighting any gaps or open questions.`
                 }
               }
             ]
@@ -1322,7 +1332,7 @@ ${conversation}`
           {
             uriTemplate: "mindgraph://search/{query}",
             name: "Search Results",
-            description: "Full-text search across all nodes in the knowledge graph",
+            description: "BM25 keyword search across all nodes \u2014 pass 1\u20133 discriminating terms (e.g. 'Kissinger NATO'), not natural language sentences",
             mimeType: "application/json"
           },
           {

package/dist/index.js

@@ -389,7 +389,7 @@ var TOOLS = [
   },
   {
     name: "mindgraph_retrieve",
-    description: "Search the knowledge graph. Primary action: 'context' \u2014 pass a short keyword query (specific nouns/terms, not sentences) for FTS + graph traversal results. Use 'text' for fast keyword-only lookup. Other actions ('active_goals', 'open_questions', 'weak_claims', 'pending_approvals', 'unresolved_contradictions', 'layer', 'recent') are ONLY for when the user explicitly asks about those topics \u2014 never pre-fetch them.",
+    description: "Search the knowledge graph using BM25 keyword matching. Primary action: 'context' \u2014 pass 1\u20133 discriminating keywords (proper nouns, technical terms) extracted from the user's question. Drop filler words (what, how, tell me about, implications of). GOOD: 'Kissinger NATO', 'Rust async runtime'. BAD: 'What is Kissinger\\'s view on NATO?'. Use 'text' for fast keyword-only lookup. Other actions ('active_goals', 'open_questions', 'weak_claims', 'pending_approvals', 'unresolved_contradictions', 'layer', 'recent') are ONLY for when the user explicitly asks about those topics \u2014 never pre-fetch them.",
     inputSchema: {
       type: "object",
       properties: {
@@ -410,7 +410,7 @@ var TOOLS = [
         },
         query: {
           type: "string",
-          description: "Keyword search query \u2014 use specific nouns and terms, e.g. 'Rust async runtime' not 'what do I know about async in Rust' (for text, context)"
+          description: "BM25 keyword query \u2014 extract 1\u20133 discriminating terms from the user's question, drop filler words. User asks 'What is Kissinger's view on NATO?' \u2192 'Kissinger NATO'. User asks about async in Rust \u2192 'Rust async runtime'. NEVER pass natural language sentences. (for text, context)"
         },
         node_types: {
           type: "array",
@@ -1012,14 +1012,24 @@ When the user asks about something, your FIRST and ONLY action should be a SINGL
 There is no session to open. There is no context to pre-load. Just search for what the user asked about.
 
 **Example:** User says "Tell me about Indian philosophy and Taoism"
-\u2713 CORRECT: \`mindgraph_retrieve({action: "context", query: "Indian philosophy Taoism"})\`
+\u2713 CORRECT: \`mindgraph_retrieve({action: "context", query: "Indian philosophy Taoism"})\` \u2014 extracted key nouns, dropped "Tell me about"
 \u2717 WRONG: First retrieve active_goals, then open_questions, then search for the topic
+\u2717 WRONG: \`mindgraph_retrieve({action: "context", query: "Tell me about Indian philosophy and Taoism"})\` \u2014 natural language sentence won't match BM25 index
 
-## Search query style
+## Search query style \u2014 BM25 keyword matching
 
-Full-text search (BM25) \u2014 use short keyword phrases, not natural language:
-- GOOD: \`"Rust async runtime"\`, \`"Indian philosophy Taoism"\`
-- BAD: \`"what do I know about async programming in Rust?"\`
+The search index uses BM25 keyword matching against node labels and summaries. It matches individual words, NOT meaning or concepts. Drop filler words like "what", "how", "implications of", "tell me about". Query with 1\u20133 discriminating terms (proper nouns, technical terms, domain-specific words).
+
+**Derive keywords from the user's question \u2014 examples:**
+- User asks "What is Kissinger's view on NATO expansion?" \u2192 query: \`"Kissinger NATO"\`
+- User asks "Tell me about async programming in Rust" \u2192 query: \`"Rust async runtime"\`
+- User asks "How does Indian philosophy relate to Taoism?" \u2192 query: \`"Indian philosophy Taoism"\`
+- User asks "What are the implications of carbon tax policy?" \u2192 query: \`"carbon tax"\`
+
+**GOOD queries:** \`"Rust async runtime"\`, \`"Kissinger NATO"\`, \`"carbon tax emissions"\`
+**BAD queries:** \`"what do I know about async programming in Rust?"\`, \`"how does X relate to Y"\`, \`"implications of climate change"\`
+
+If the first query returns no results, try synonym or related terms (e.g. \`"global warming"\` instead of \`"climate change"\`).
 
 ## When to READ
 
@@ -1051,7 +1061,7 @@ Capture knowledge when the user shares something worth remembering:
 var server = new import_server.Server(
   {
     name: "mindgraph",
-    version: "0.3.3"
+    version: "0.3.4"
   },
   {
     capabilities: {
@@ -1184,7 +1194,7 @@ server.setRequestHandler(import_types.GetPromptRequestSchema, async (request) =>
             role: "user",
             content: {
               type: "text",
-              text: `Search my knowledge graph for everything related to "${topic}". Use context retrieval with keyword queries to find entities, claims, evidence, questions, and any connected knowledge. Try multiple keyword variations to ensure broad coverage. Present a structured overview of what I know about this topic, highlighting any gaps or open questions.`
+              text: `Search my knowledge graph for everything related to "${topic}". Use context retrieval with short BM25 keyword queries (1\u20133 discriminating terms extracted from the topic, not full sentences). Try multiple keyword variations and synonyms to ensure broad coverage. Present a structured overview of what I know about this topic, highlighting any gaps or open questions.`
             }
           }
         ]
@@ -1279,7 +1289,7 @@ server.setRequestHandler(import_types.ListResourceTemplatesRequestSchema, async
       {
         uriTemplate: "mindgraph://search/{query}",
         name: "Search Results",
-        description: "Full-text search across all nodes in the knowledge graph",
+        description: "BM25 keyword search across all nodes \u2014 pass 1\u20133 discriminating terms (e.g. 'Kissinger NATO'), not natural language sentences",
         mimeType: "application/json"
       },
       {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mindgraph-mcp",
-  "version": "0.3.3",
+  "version": "0.3.4",
   "description": "MCP server for MindGraph — connect Claude Desktop, Claude Code, and any MCP client to your knowledge graph",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",