mindgraph-mcp 0.2.1 → 0.3.0

package/dist/cli.js

@@ -411,33 +411,43 @@ async function handlePlan(client2, args) {
   }
 }
 async function handleRetrieve(client2, args) {
-  const { action, query, layer, limit, node_type, agent_id } = args;
+  const {
+    action,
+    query,
+    node_types,
+    layer,
+    limit,
+    include_chunks,
+    include_graph,
+    confidence_min,
+    salience_min,
+    agent_id
+  } = args;
   switch (action) {
     case "context":
       if (!query) return err("query is required for context retrieval");
-      return ok(await client2.retrieveContext({ query, k: limit }));
-    case "hybrid":
-      if (!query) return err("query is required for hybrid search");
       return ok(
-        await client2.hybridSearch(query, {
+        await client2.retrieveContext({
+          query,
           k: limit,
-          node_types: node_type ? [node_type] : void 0
+          node_types,
+          layer,
+          include_chunks,
+          include_graph
         })
       );
-    case "semantic":
-      if (!query) return err("query is required for semantic search");
+    case "text":
+      if (!query) return err("query is required for text search");
       return ok(
         await client2.retrieve({
-          action: "semantic",
+          action: "text",
           query,
           limit,
-          node_type,
+          node_types,
+          layer,
           agent_id
         })
       );
-    case "text":
-      if (!query) return err("query is required for text search");
-      return ok(await client2.search(query, { limit, node_type }));
     case "active_goals":
       return ok(await client2.getGoals());
     case "open_questions":
@@ -463,7 +473,9 @@ async function handleRetrieve(client2, args) {
         await client2.retrieve({
           action: "recent",
           limit,
-          node_type,
+          node_types,
+          confidence_min,
+          salience_min,
           agent_id
         })
       );
@@ -943,15 +955,13 @@ var init_tools = __esm({
       },
       {
         name: "mindgraph_retrieve",
-        description: "Search and query the knowledge graph. ALWAYS retrieve before answering questions about previously stored knowledge. Actions: 'context' for rich retrieval (follows graph edges \u2014 best for RAG), 'hybrid' for fast keyword+semantic search, 'text' for exact keyword match, 'semantic' for meaning-based search. Convenience queries: 'active_goals', 'open_questions', 'weak_claims', 'pending_approvals', 'unresolved_contradictions'. Use 'layer' to browse a specific cognitive layer, 'recent' for latest additions.",
+        description: "Search and query the knowledge graph using full-text search (BM25). ALWAYS retrieve before answering questions about previously stored knowledge. Use short keyword queries \u2014 specific nouns and terms, NOT full sentences. Actions: 'context' for rich retrieval (FTS + graph traversal \u2014 best for RAG, 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 specific cognitive layer, 'recent' for latest additions.",
         inputSchema: {
           type: "object",
           properties: {
             action: {
               type: "string",
               enum: [
-                "hybrid",
-                "semantic",
                 "text",
                 "context",
                 "active_goals",
@@ -966,7 +976,12 @@ var init_tools = __esm({
             },
             query: {
               type: "string",
-              description: "Search query (for hybrid, semantic, text, context)"
+              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)"
+            },
+            node_types: {
+              type: "array",
+              items: { type: "string" },
+              description: "Filter by node types (e.g. ['Claim', 'Entity', 'Observation'])"
             },
             layer: {
               type: "string",
@@ -978,15 +993,31 @@ var init_tools = __esm({
                 "memory",
                 "agent"
               ],
-              description: "Layer filter (for layer action)"
+              description: "Filter by cognitive layer (for context, text, layer actions)"
             },
             limit: {
               type: "number",
               description: "Max results to return (default: 10)"
             },
-            node_type: {
-              type: "string",
-              description: "Filter by node type"
+            include_chunks: {
+              type: "boolean",
+              description: "Include source document chunks in context results (default: true)"
+            },
+            include_graph: {
+              type: "boolean",
+              description: "Include graph nodes in context results (default: true)"
+            },
+            confidence_min: {
+              type: "number",
+              minimum: 0,
+              maximum: 1,
+              description: "Minimum confidence filter (for recent action)"
+            },
+            salience_min: {
+              type: "number",
+              minimum: 0,
+              maximum: 1,
+              description: "Minimum salience filter (for recent action)"
             },
             agent_id: {
               type: "string",
@@ -1064,7 +1095,7 @@ async function main() {
   const transport = new import_stdio.StdioServerTransport();
   await server.connect(transport);
   console.error(
-    `MindGraph MCP server v0.2.0 running on stdio (${BASE_URL})`
+    `MindGraph MCP server v0.3.0 running on stdio (${BASE_URL})`
   );
 }
 var import_server, import_stdio, import_types, import_mindgraph, API_KEY, BASE_URL, AGENT_ID, client, INSTRUCTIONS, server, PROMPTS;
@@ -1107,12 +1138,20 @@ Store knowledge whenever the user shares something worth remembering:
 ## When to READ from the graph
 
 Retrieve context before answering questions that might benefit from prior knowledge:
-- **"What do I know about X?"** \u2192 \`mindgraph_retrieve\` with action "hybrid" or "context"
+- **"What do I know about X?"** \u2192 \`mindgraph_retrieve\` with action "context" and keyword query
 - **"What are my goals?"** \u2192 \`mindgraph_retrieve\` with action "active_goals"
 - **"What questions are open?"** \u2192 \`mindgraph_retrieve\` with action "open_questions"
 - **Anything referencing past conversations or stored knowledge** \u2192 \`mindgraph_retrieve\` with action "context"
 - **Before making claims about things the user has told you** \u2192 retrieve first to avoid contradictions
 
+## Search query style
+
+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"\`
+
+Use the most specific nouns and terms from the topic. Multiple keywords broaden recall across label, summary, and content fields.
+
 ## Session management
 
 - Open a session with \`mindgraph_session\` action "open" at the start of a substantial conversation
@@ -1124,7 +1163,7 @@ Retrieve context before answering questions that might benefit from prior knowle
 - **mindgraph_capture vs mindgraph_journal**: Use \`capture\` for structured entities (people, orgs, places) and factual observations. Use \`journal\` for informal notes, preferences, reflections, and anything that's more about the user's inner state than external facts.
 - **mindgraph_argue vs mindgraph_inquire**: Use \`argue\` when there's a specific claim with supporting evidence. Use \`inquire\` for open-ended questions, hypotheses without evidence yet, or theoretical frameworks.
 - **mindgraph_commit vs mindgraph_plan**: Use \`commit\` for the user's goals, projects, and milestones. Use \`plan\` for agent-level task management and execution tracking.
-- **mindgraph_retrieve "hybrid" vs "context"**: Use "hybrid" for quick keyword+semantic search. Use "context" for richer retrieval that follows graph edges from matching chunks to find connected entities and claims.
+- **mindgraph_retrieve "text" vs "context"**: Use "text" for fast direct keyword lookup. Use "context" for richer retrieval that searches nodes via FTS, then follows graph edges to find connected entities, claims, and source chunks \u2014 best for RAG and comprehensive answers.
 - **mindgraph_ingest**: Use for any content longer than a paragraph. It automatically extracts entities, claims, and relationships. For short facts, use the specific cognitive tools instead.
 
 ## Important behaviors
@@ -1269,7 +1308,7 @@ Retrieve context before answering questions that might benefit from prior knowle
                 role: "user",
                 content: {
                   type: "text",
-                  text: `Search my knowledge graph for everything related to "${topic}". Use both hybrid search and context retrieval to find entities, claims, evidence, questions, and any connected knowledge. 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 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.`
                 }
               }
             ]
@@ -1463,7 +1502,7 @@ ${conversation}`
       const searchMatch = uri.match(/^mindgraph:\/\/search\/(.+)$/);
       if (searchMatch) {
         const query = decodeURIComponent(searchMatch[1]);
-        const results = await client.hybridSearch(query, { k: 20 });
+        const results = await client.search(query, { limit: 20 });
         return {
           contents: [
             {

package/dist/index.js

@@ -428,15 +428,13 @@ var TOOLS = [
   },
   {
     name: "mindgraph_retrieve",
-    description: "Search and query the knowledge graph. ALWAYS retrieve before answering questions about previously stored knowledge. Actions: 'context' for rich retrieval (follows graph edges \u2014 best for RAG), 'hybrid' for fast keyword+semantic search, 'text' for exact keyword match, 'semantic' for meaning-based search. Convenience queries: 'active_goals', 'open_questions', 'weak_claims', 'pending_approvals', 'unresolved_contradictions'. Use 'layer' to browse a specific cognitive layer, 'recent' for latest additions.",
+    description: "Search and query the knowledge graph using full-text search (BM25). ALWAYS retrieve before answering questions about previously stored knowledge. Use short keyword queries \u2014 specific nouns and terms, NOT full sentences. Actions: 'context' for rich retrieval (FTS + graph traversal \u2014 best for RAG, 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 specific cognitive layer, 'recent' for latest additions.",
     inputSchema: {
       type: "object",
       properties: {
         action: {
           type: "string",
           enum: [
-            "hybrid",
-            "semantic",
             "text",
             "context",
             "active_goals",
@@ -451,7 +449,12 @@ var TOOLS = [
         },
         query: {
           type: "string",
-          description: "Search query (for hybrid, semantic, text, context)"
+          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)"
+        },
+        node_types: {
+          type: "array",
+          items: { type: "string" },
+          description: "Filter by node types (e.g. ['Claim', 'Entity', 'Observation'])"
         },
         layer: {
           type: "string",
@@ -463,15 +466,31 @@ var TOOLS = [
             "memory",
             "agent"
           ],
-          description: "Layer filter (for layer action)"
+          description: "Filter by cognitive layer (for context, text, layer actions)"
         },
         limit: {
           type: "number",
           description: "Max results to return (default: 10)"
         },
-        node_type: {
-          type: "string",
-          description: "Filter by node type"
+        include_chunks: {
+          type: "boolean",
+          description: "Include source document chunks in context results (default: true)"
+        },
+        include_graph: {
+          type: "boolean",
+          description: "Include graph nodes in context results (default: true)"
+        },
+        confidence_min: {
+          type: "number",
+          minimum: 0,
+          maximum: 1,
+          description: "Minimum confidence filter (for recent action)"
+        },
+        salience_min: {
+          type: "number",
+          minimum: 0,
+          maximum: 1,
+          description: "Minimum salience filter (for recent action)"
         },
         agent_id: {
           type: "string",
@@ -924,33 +943,43 @@ async function handlePlan(client2, args) {
   }
 }
 async function handleRetrieve(client2, args) {
-  const { action, query, layer, limit, node_type, agent_id } = args;
+  const {
+    action,
+    query,
+    node_types,
+    layer,
+    limit,
+    include_chunks,
+    include_graph,
+    confidence_min,
+    salience_min,
+    agent_id
+  } = args;
   switch (action) {
     case "context":
       if (!query) return err("query is required for context retrieval");
-      return ok(await client2.retrieveContext({ query, k: limit }));
-    case "hybrid":
-      if (!query) return err("query is required for hybrid search");
       return ok(
-        await client2.hybridSearch(query, {
+        await client2.retrieveContext({
+          query,
           k: limit,
-          node_types: node_type ? [node_type] : void 0
+          node_types,
+          layer,
+          include_chunks,
+          include_graph
         })
       );
-    case "semantic":
-      if (!query) return err("query is required for semantic search");
+    case "text":
+      if (!query) return err("query is required for text search");
       return ok(
         await client2.retrieve({
-          action: "semantic",
+          action: "text",
           query,
           limit,
-          node_type,
+          node_types,
+          layer,
           agent_id
         })
       );
-    case "text":
-      if (!query) return err("query is required for text search");
-      return ok(await client2.search(query, { limit, node_type }));
     case "active_goals":
       return ok(await client2.getGoals());
     case "open_questions":
@@ -976,7 +1005,9 @@ async function handleRetrieve(client2, args) {
         await client2.retrieve({
           action: "recent",
           limit,
-          node_type,
+          node_types,
+          confidence_min,
+          salience_min,
           agent_id
         })
       );
@@ -1064,12 +1095,20 @@ Store knowledge whenever the user shares something worth remembering:
 ## When to READ from the graph
 
 Retrieve context before answering questions that might benefit from prior knowledge:
-- **"What do I know about X?"** \u2192 \`mindgraph_retrieve\` with action "hybrid" or "context"
+- **"What do I know about X?"** \u2192 \`mindgraph_retrieve\` with action "context" and keyword query
 - **"What are my goals?"** \u2192 \`mindgraph_retrieve\` with action "active_goals"
 - **"What questions are open?"** \u2192 \`mindgraph_retrieve\` with action "open_questions"
 - **Anything referencing past conversations or stored knowledge** \u2192 \`mindgraph_retrieve\` with action "context"
 - **Before making claims about things the user has told you** \u2192 retrieve first to avoid contradictions
 
+## Search query style
+
+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"\`
+
+Use the most specific nouns and terms from the topic. Multiple keywords broaden recall across label, summary, and content fields.
+
 ## Session management
 
 - Open a session with \`mindgraph_session\` action "open" at the start of a substantial conversation
@@ -1081,7 +1120,7 @@ Retrieve context before answering questions that might benefit from prior knowle
 - **mindgraph_capture vs mindgraph_journal**: Use \`capture\` for structured entities (people, orgs, places) and factual observations. Use \`journal\` for informal notes, preferences, reflections, and anything that's more about the user's inner state than external facts.
 - **mindgraph_argue vs mindgraph_inquire**: Use \`argue\` when there's a specific claim with supporting evidence. Use \`inquire\` for open-ended questions, hypotheses without evidence yet, or theoretical frameworks.
 - **mindgraph_commit vs mindgraph_plan**: Use \`commit\` for the user's goals, projects, and milestones. Use \`plan\` for agent-level task management and execution tracking.
-- **mindgraph_retrieve "hybrid" vs "context"**: Use "hybrid" for quick keyword+semantic search. Use "context" for richer retrieval that follows graph edges from matching chunks to find connected entities and claims.
+- **mindgraph_retrieve "text" vs "context"**: Use "text" for fast direct keyword lookup. Use "context" for richer retrieval that searches nodes via FTS, then follows graph edges to find connected entities, claims, and source chunks \u2014 best for RAG and comprehensive answers.
 - **mindgraph_ingest**: Use for any content longer than a paragraph. It automatically extracts entities, claims, and relationships. For short facts, use the specific cognitive tools instead.
 
 ## Important behaviors
@@ -1226,7 +1265,7 @@ server.setRequestHandler(import_types.GetPromptRequestSchema, async (request) =>
             role: "user",
             content: {
               type: "text",
-              text: `Search my knowledge graph for everything related to "${topic}". Use both hybrid search and context retrieval to find entities, claims, evidence, questions, and any connected knowledge. 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 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.`
             }
           }
         ]
@@ -1420,7 +1459,7 @@ server.setRequestHandler(import_types.ReadResourceRequestSchema, async (request)
   const searchMatch = uri.match(/^mindgraph:\/\/search\/(.+)$/);
   if (searchMatch) {
     const query = decodeURIComponent(searchMatch[1]);
-    const results = await client.hybridSearch(query, { k: 20 });
+    const results = await client.search(query, { limit: 20 });
     return {
       contents: [
         {
@@ -1451,7 +1490,7 @@ async function main() {
   const transport = new import_stdio.StdioServerTransport();
   await server.connect(transport);
   console.error(
-    `MindGraph MCP server v0.2.0 running on stdio (${BASE_URL})`
+    `MindGraph MCP server v0.3.0 running on stdio (${BASE_URL})`
   );
 }
 main().catch((error) => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mindgraph-mcp",
-  "version": "0.2.1",
+  "version": "0.3.0",
   "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",