mindgraph-mcp 0.3.2 → 0.3.4

package/dist/cli.js

@@ -874,7 +874,7 @@ var init_tools = __esm({
       },
       {
         name: "mindgraph_retrieve",
-        description: "Search and query the knowledge graph using full-text search (BM25). Use short keyword queries \u2014 specific nouns and terms, NOT full sentences. Only retrieve when the user's message references or benefits from stored knowledge \u2014 do NOT pre-fetch goals/questions/contradictions unless asked. Actions: 'context' for rich retrieval (FTS + graph traversal, returns connected entities and source chunks), 'text' for fast direct keyword search. Convenience queries (no query needed): 'active_goals', 'open_questions', 'weak_claims', 'pending_approvals', 'unresolved_contradictions'. Use 'layer' to browse a cognitive layer, 'recent' for latest additions.",
+        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",
@@ -1039,61 +1039,72 @@ var init_src = __esm({
       baseUrl: BASE_URL,
       apiKey: API_KEY
     });
-    INSTRUCTIONS = `You have access to a persistent knowledge graph via MindGraph. This is the user's long-term memory \u2014 use it proactively.
+    INSTRUCTIONS = `You have access to a persistent knowledge graph via MindGraph.
 
-## Critical: minimize latency
+## #1 RULE: Go straight to the user's topic
 
-- **Jump straight to the user's topic.** Do NOT pre-fetch goals, open questions, or other convenience queries unless the user specifically asks about them.
-- **Parallelize tool calls.** When you need to search and capture at the same time, issue all calls in a single parallel batch \u2014 never serialize independent calls.
+When the user asks about something, your FIRST and ONLY action should be a SINGLE \`mindgraph_retrieve\` call with action "context" and keyword terms from their message. Nothing else first.
 
-## When to READ from the graph
+**NEVER do any of these before addressing the user's topic:**
+- Do NOT retrieve active_goals
+- Do NOT retrieve open_questions
+- Do NOT retrieve contradictions or weak_claims
+- Do NOT follow a "session lifecycle" or "warm-up" sequence
+- Do NOT make multiple serial retrieve calls when one "context" call covers it
 
-Only retrieve when the user's message references or would benefit from stored knowledge:
-- User asks about a topic \u2192 \`mindgraph_retrieve\` with action "context" and keyword query
-- User asks about goals \u2192 \`mindgraph_retrieve\` with action "active_goals"
-- User asks about open questions \u2192 \`mindgraph_retrieve\` with action "open_questions"
-- Before asserting something the user previously told you \u2192 retrieve to check
+There is no session to open. There is no context to pre-load. Just search for what the user asked about.
 
-Do NOT retrieve preemptively. If the user says "let's discuss X", search for X \u2014 don't also fetch goals, questions, and contradictions.
+**Example:** User says "Tell me about Indian philosophy and 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
 
-MindGraph uses **full-text search (BM25)**, not semantic/embedding search. Write queries as **short keyword phrases**, not natural language questions:
-- GOOD: \`"Rust async runtime"\`, \`"project deadline March"\`, \`"Sarah engineering manager"\`
-- BAD: \`"what do I know about async programming in Rust?"\`, \`"tell me about Sarah's role"\`
+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).
 
-Use the most specific nouns and terms from the topic. Multiple keywords broaden recall across label, summary, and content fields.
+**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"\`
 
-## When to WRITE to the graph
+**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"\`
 
-Store knowledge whenever the user shares something worth remembering:
-- **People, organizations, places, events** \u2192 \`mindgraph_capture\` with action "entity"
-- **Quick notes, preferences, reflections, moods** \u2192 \`mindgraph_journal\`
-- **Factual observations** \u2192 \`mindgraph_capture\` with action "observation"
-- **Claims with evidence** \u2192 \`mindgraph_argue\`
-- **Questions to track** \u2192 \`mindgraph_inquire\` with action "open_question"
-- **Hypotheses or theories** \u2192 \`mindgraph_inquire\` with action "hypothesis" or "theory"
-- **Goals or projects** \u2192 \`mindgraph_commit\`
-- **Decisions** \u2192 \`mindgraph_decide\`
-- **Long-form content** \u2192 \`mindgraph_ingest\`
+If the first query returns no results, try synonym or related terms (e.g. \`"global warming"\` instead of \`"climate change"\`).
 
-## Tool selection guide
+## When to READ
 
-- **mindgraph_capture vs mindgraph_journal**: \`capture\` for structured entities and factual observations. \`journal\` for informal notes, preferences, and reflections.
-- **mindgraph_argue vs mindgraph_inquire**: \`argue\` when there's evidence. \`inquire\` for open questions and hypotheses without evidence yet.
-- **mindgraph_retrieve "text" vs "context"**: "text" for fast direct keyword lookup. "context" for richer retrieval that follows graph edges to connected entities and source chunks \u2014 best for RAG.
-- **mindgraph_ingest**: For content longer than a paragraph. Automatically extracts entities, claims, and relationships.
+- User asks about topic X \u2192 \`mindgraph_retrieve\` action "context", query "X keywords"
+- User explicitly asks "what are my goals?" \u2192 action "active_goals"
+- User explicitly asks about open questions \u2192 action "open_questions"
+- Before asserting something the user previously said \u2192 retrieve to check
+- Parallelize independent calls in a single batch
 
-## Important behaviors
+## When to WRITE
 
-- Be proactive about capturing: if the user mentions a person, place, or organization, capture it
-- Deduplicate: the graph handles deduplication automatically
-- Confidence scores: 0.9+ for stated facts, 0.5-0.8 for uncertain claims, below 0.5 for speculation
-- Don't narrate tool usage \u2014 capture knowledge naturally as part of the conversation`;
+Capture knowledge when the user shares something worth remembering:
+- People/orgs/places/events \u2192 \`mindgraph_capture\` action "entity"
+- Quick notes, preferences \u2192 \`mindgraph_journal\`
+- Factual observations \u2192 \`mindgraph_capture\` action "observation"
+- Claims with evidence \u2192 \`mindgraph_argue\`
+- Questions to track \u2192 \`mindgraph_inquire\` action "open_question"
+- Goals or projects \u2192 \`mindgraph_commit\`
+- Decisions \u2192 \`mindgraph_decide\`
+- Long-form content \u2192 \`mindgraph_ingest\`
+
+## Tool tips
+
+- \`capture\` for structured/factual, \`journal\` for personal/informal
+- \`argue\` when evidence exists, \`inquire\` for open questions
+- \`text\` for fast lookup, \`context\` for rich retrieval with graph traversal
+- Confidence: 0.9+ for facts, 0.5-0.8 for uncertain, <0.5 for speculation
+- Don't narrate tool usage \u2014 capture naturally as part of conversation`;
     server = new import_server.Server(
       {
         name: "mindgraph",
-        version: "0.2.1"
+        version: "0.3.4"
       },
       {
         capabilities: {
@@ -1226,7 +1237,7 @@ Store knowledge whenever 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.`
                 }
               }
             ]
@@ -1321,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 and query the knowledge graph using full-text search (BM25). Use short keyword queries \u2014 specific nouns and terms, NOT full sentences. Only retrieve when the user's message references or benefits from stored knowledge \u2014 do NOT pre-fetch goals/questions/contradictions unless asked. Actions: 'context' for rich retrieval (FTS + graph traversal, returns connected entities and source chunks), 'text' for fast direct keyword search. Convenience queries (no query needed): 'active_goals', 'open_questions', 'weak_claims', 'pending_approvals', 'unresolved_contradictions'. Use 'layer' to browse a cognitive layer, 'recent' for latest additions.",
+    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",
@@ -996,61 +996,72 @@ var client = new import_mindgraph.MindGraph({
   baseUrl: BASE_URL,
   apiKey: API_KEY
 });
-var INSTRUCTIONS = `You have access to a persistent knowledge graph via MindGraph. This is the user's long-term memory \u2014 use it proactively.
+var INSTRUCTIONS = `You have access to a persistent knowledge graph via MindGraph.
 
-## Critical: minimize latency
+## #1 RULE: Go straight to the user's topic
 
-- **Jump straight to the user's topic.** Do NOT pre-fetch goals, open questions, or other convenience queries unless the user specifically asks about them.
-- **Parallelize tool calls.** When you need to search and capture at the same time, issue all calls in a single parallel batch \u2014 never serialize independent calls.
+When the user asks about something, your FIRST and ONLY action should be a SINGLE \`mindgraph_retrieve\` call with action "context" and keyword terms from their message. Nothing else first.
 
-## When to READ from the graph
+**NEVER do any of these before addressing the user's topic:**
+- Do NOT retrieve active_goals
+- Do NOT retrieve open_questions
+- Do NOT retrieve contradictions or weak_claims
+- Do NOT follow a "session lifecycle" or "warm-up" sequence
+- Do NOT make multiple serial retrieve calls when one "context" call covers it
 
-Only retrieve when the user's message references or would benefit from stored knowledge:
-- User asks about a topic \u2192 \`mindgraph_retrieve\` with action "context" and keyword query
-- User asks about goals \u2192 \`mindgraph_retrieve\` with action "active_goals"
-- User asks about open questions \u2192 \`mindgraph_retrieve\` with action "open_questions"
-- Before asserting something the user previously told you \u2192 retrieve to check
+There is no session to open. There is no context to pre-load. Just search for what the user asked about.
 
-Do NOT retrieve preemptively. If the user says "let's discuss X", search for X \u2014 don't also fetch goals, questions, and contradictions.
+**Example:** User says "Tell me about Indian philosophy and 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
 
-MindGraph uses **full-text search (BM25)**, not semantic/embedding search. Write queries as **short keyword phrases**, not natural language questions:
-- GOOD: \`"Rust async runtime"\`, \`"project deadline March"\`, \`"Sarah engineering manager"\`
-- BAD: \`"what do I know about async programming in Rust?"\`, \`"tell me about Sarah's role"\`
+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).
 
-Use the most specific nouns and terms from the topic. Multiple keywords broaden recall across label, summary, and content fields.
+**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"\`
 
-## When to WRITE to the graph
+**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"\`
 
-Store knowledge whenever the user shares something worth remembering:
-- **People, organizations, places, events** \u2192 \`mindgraph_capture\` with action "entity"
-- **Quick notes, preferences, reflections, moods** \u2192 \`mindgraph_journal\`
-- **Factual observations** \u2192 \`mindgraph_capture\` with action "observation"
-- **Claims with evidence** \u2192 \`mindgraph_argue\`
-- **Questions to track** \u2192 \`mindgraph_inquire\` with action "open_question"
-- **Hypotheses or theories** \u2192 \`mindgraph_inquire\` with action "hypothesis" or "theory"
-- **Goals or projects** \u2192 \`mindgraph_commit\`
-- **Decisions** \u2192 \`mindgraph_decide\`
-- **Long-form content** \u2192 \`mindgraph_ingest\`
+If the first query returns no results, try synonym or related terms (e.g. \`"global warming"\` instead of \`"climate change"\`).
 
-## Tool selection guide
+## When to READ
 
-- **mindgraph_capture vs mindgraph_journal**: \`capture\` for structured entities and factual observations. \`journal\` for informal notes, preferences, and reflections.
-- **mindgraph_argue vs mindgraph_inquire**: \`argue\` when there's evidence. \`inquire\` for open questions and hypotheses without evidence yet.
-- **mindgraph_retrieve "text" vs "context"**: "text" for fast direct keyword lookup. "context" for richer retrieval that follows graph edges to connected entities and source chunks \u2014 best for RAG.
-- **mindgraph_ingest**: For content longer than a paragraph. Automatically extracts entities, claims, and relationships.
+- User asks about topic X \u2192 \`mindgraph_retrieve\` action "context", query "X keywords"
+- User explicitly asks "what are my goals?" \u2192 action "active_goals"
+- User explicitly asks about open questions \u2192 action "open_questions"
+- Before asserting something the user previously said \u2192 retrieve to check
+- Parallelize independent calls in a single batch
 
-## Important behaviors
+## When to WRITE
 
-- Be proactive about capturing: if the user mentions a person, place, or organization, capture it
-- Deduplicate: the graph handles deduplication automatically
-- Confidence scores: 0.9+ for stated facts, 0.5-0.8 for uncertain claims, below 0.5 for speculation
-- Don't narrate tool usage \u2014 capture knowledge naturally as part of the conversation`;
+Capture knowledge when the user shares something worth remembering:
+- People/orgs/places/events \u2192 \`mindgraph_capture\` action "entity"
+- Quick notes, preferences \u2192 \`mindgraph_journal\`
+- Factual observations \u2192 \`mindgraph_capture\` action "observation"
+- Claims with evidence \u2192 \`mindgraph_argue\`
+- Questions to track \u2192 \`mindgraph_inquire\` action "open_question"
+- Goals or projects \u2192 \`mindgraph_commit\`
+- Decisions \u2192 \`mindgraph_decide\`
+- Long-form content \u2192 \`mindgraph_ingest\`
+
+## Tool tips
+
+- \`capture\` for structured/factual, \`journal\` for personal/informal
+- \`argue\` when evidence exists, \`inquire\` for open questions
+- \`text\` for fast lookup, \`context\` for rich retrieval with graph traversal
+- Confidence: 0.9+ for facts, 0.5-0.8 for uncertain, <0.5 for speculation
+- Don't narrate tool usage \u2014 capture naturally as part of conversation`;
 var server = new import_server.Server(
   {
     name: "mindgraph",
-    version: "0.2.1"
+    version: "0.3.4"
   },
   {
     capabilities: {
@@ -1183,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.`
             }
           }
         ]
@@ -1278,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.2",
+  "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",