mindgraph-mcp 0.1.0 → 0.2.1

package/dist/cli.js

@@ -525,7 +525,7 @@ var init_tools = __esm({
     TOOLS = [
       {
         name: "mindgraph_session",
-        description: "Open, trace, or close a memory session. Sessions group related interactions and enable context continuity. Open a session at the start of a conversation, trace key moments during it, and close it at the end to trigger distillation.",
+        description: "Manage conversation sessions. ALWAYS open a session at the start of a substantial conversation (label it with the topic). Use 'trace' to bookmark key moments (decisions made, important facts shared). Close the session at the end with a summary of what was discussed. Sessions enable the graph to track conversation continuity and trigger knowledge distillation on close.",
         inputSchema: {
           type: "object",
           properties: {
@@ -560,7 +560,7 @@ var init_tools = __esm({
       },
       {
         name: "mindgraph_journal",
-        description: "Low-friction capture of observations, notes, preferences, and reflections. Creates a Journal node in the Memory layer. Use this for quick thoughts, user preferences, mood tracking, and daily notes that don't fit a formal structure.",
+        description: "Quick, informal capture for the user's inner world: preferences ('I prefer dark mode'), reflections ('I've been thinking about...'), moods, daily notes, and anything subjective. Use this instead of mindgraph_capture when the content is personal/informal rather than a structured fact about the external world. Good for: likes/dislikes, feelings, habits, reminders-to-self, freeform notes.",
         inputSchema: {
           type: "object",
           properties: {
@@ -595,7 +595,7 @@ var init_tools = __esm({
       },
       {
         name: "mindgraph_capture",
-        description: "Capture entities, observations, concepts, sources, and snippets into the Reality layer with automatic deduplication. Use 'entity' for people, organizations, places, events, nations, or abstract concepts. Use 'observation' for factual observations. Use 'source' for documents or references. Use 'snippet' for direct quotes linked to a source.",
+        description: "Capture structured facts about the external world into the Reality layer. Use proactively whenever the user mentions a named entity. Actions: 'entity' for people/orgs/places/events/nations/concepts (auto-deduplicates \u2014 safe to call even if already exists), 'observation' for factual statements about the world, 'source' for documents/URLs/references, 'snippet' for direct quotes from a source. Prefer this over mindgraph_journal when the content is an objective fact rather than a personal note.",
         inputSchema: {
           type: "object",
           properties: {
@@ -654,7 +654,7 @@ var init_tools = __esm({
       },
       {
         name: "mindgraph_argue",
-        description: "Construct a structured argument with claims, evidence, warrants, and rebuttals. Creates interconnected Epistemic layer nodes. Use this when you need to record or evaluate a reasoned position with supporting evidence and logical connections.",
+        description: "Record a claim WITH supporting evidence. Use when the user states something as true/false and provides reasoning or sources. Creates interconnected Claim + Evidence + Warrant nodes. Set confidence based on evidence strength: 0.9+ for well-sourced facts, 0.5-0.8 for plausible claims, below 0.5 for speculation. Prefer mindgraph_inquire instead when there's a question or hypothesis WITHOUT evidence yet.",
         inputSchema: {
           type: "object",
           properties: {
@@ -710,7 +710,7 @@ var init_tools = __esm({
       },
       {
         name: "mindgraph_inquire",
-        description: "Record questions, hypotheses, theories, anomalies, assumptions, and paradigms in the Epistemic layer. Use this to track open questions worth investigating, form testable hypotheses, flag anomalies that challenge existing understanding, or articulate theoretical frameworks.",
+        description: "Record things that need investigation or are uncertain. Use 'open_question' when the user asks something worth tracking ('How does X work?'), 'hypothesis' for testable predictions, 'theory' for explanatory frameworks, 'anomaly' for things that don't fit existing understanding, 'assumption' for unstated beliefs worth surfacing. These stay in the graph as open items until resolved. Prefer mindgraph_argue instead when there IS evidence to attach.",
         inputSchema: {
           type: "object",
           properties: {
@@ -761,7 +761,7 @@ var init_tools = __esm({
       },
       {
         name: "mindgraph_commit",
-        description: "Create goals, projects, and milestones in the Intent layer. Use 'goal' for desired outcomes, 'project' for organized efforts toward goals, and 'milestone' for measurable checkpoints within projects.",
+        description: "Track the user's goals, projects, and milestones. Use 'goal' when the user expresses a desired outcome ('I want to learn Rust'), 'project' for organized efforts ('my blog redesign'), 'milestone' for checkpoints ('launch MVP by March'). Link milestones to projects and projects to goals via parent_uid. These appear in daily briefings and active goals queries.",
         inputSchema: {
           type: "object",
           properties: {
@@ -806,7 +806,7 @@ var init_tools = __esm({
       },
       {
         name: "mindgraph_decide",
-        description: "Manage decisions through their full lifecycle: open a decision, add options and constraints, then resolve by choosing an option. Use 'get_open' to list all unresolved decisions.",
+        description: "Track decisions through their lifecycle. Use 'open_decision' when the user faces a choice ('Should I use Postgres or SQLite?'), 'add_option' to record each alternative, 'add_constraint' for requirements or dealbreakers, 'resolve' when a choice is made. Use 'get_open' to review pending decisions. This creates a structured decision record that can be referenced later.",
         inputSchema: {
           type: "object",
           properties: {
@@ -845,7 +845,7 @@ var init_tools = __esm({
       },
       {
         name: "mindgraph_action",
-        description: "Record procedural knowledge (workflows, steps, affordances, controls) and risk assessments in the Action layer. Use this for SOPs, runbooks, capability mappings, and risk analysis.",
+        description: "Record procedural knowledge and risk assessments. Use 'create_flow' for workflows/processes, 'add_step' for individual steps in a flow, 'add_affordance' for capabilities ('this API supports batch operations'), 'add_control' for guardrails/constraints. Use 'assess_risk' when the user identifies a risk or potential problem. Less commonly used than capture/argue/commit \u2014 reach for this when the conversation is about HOW to do something.",
         inputSchema: {
           type: "object",
           properties: {
@@ -887,7 +887,7 @@ var init_tools = __esm({
       },
       {
         name: "mindgraph_plan",
-        description: "Create and manage plans, tasks, execution tracking, and governance policies in the Agent layer. Supports full task lifecycle from creation through completion, plan hierarchies, and approval workflows.",
+        description: "Agent-level task management and governance. Use 'create_plan'/'create_task'/'add_step' for breaking down work into trackable items, 'update_status' to mark progress, 'start_execution'/'complete_execution'/'fail_execution' for execution tracking. Use 'create_policy' and 'request_approval' for governance workflows. Prefer mindgraph_commit for the user's goals/projects; use mindgraph_plan for agent-managed task breakdowns and execution.",
         inputSchema: {
           type: "object",
           properties: {
@@ -943,7 +943,7 @@ var init_tools = __esm({
       },
       {
         name: "mindgraph_retrieve",
-        description: "Search and query the knowledge graph. Supports hybrid (text + semantic) search, active goals, open questions, weak claims, pending approvals, contradictions, layer-filtered retrieval, and rich context retrieval that follows graph edges from matching chunks.",
+        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.",
         inputSchema: {
           type: "object",
           properties: {
@@ -998,7 +998,7 @@ var init_tools = __esm({
       },
       {
         name: "mindgraph_ingest",
-        description: "Ingest long-form content into the knowledge graph. Supports single chunks (synchronous), full documents (async with job tracking), and session transcripts. The ingestion pipeline automatically extracts entities, claims, relationships, and structures across cognitive layers.",
+        description: "Ingest long-form content (articles, transcripts, documents, meeting notes) into the knowledge graph. The pipeline automatically chunks the text, extracts entities/claims/relationships via LLM, and deduplicates against existing nodes. Use 'chunk' for a single passage (synchronous), 'document' for full documents (async \u2014 returns a job ID), 'session' for conversation transcripts. Use 'job_status' to check progress. For short individual facts, use the specific cognitive tools instead.",
         inputSchema: {
           type: "object",
           properties: {
@@ -1063,9 +1063,11 @@ var src_exports = {};
 async function main() {
   const transport = new import_stdio.StdioServerTransport();
   await server.connect(transport);
-  console.error("MindGraph MCP server running on stdio");
+  console.error(
+    `MindGraph MCP server v0.2.0 running on stdio (${BASE_URL})`
+  );
 }
-var import_server, import_stdio, import_types, import_mindgraph, API_KEY, BASE_URL, AGENT_ID, client, server;
+var import_server, import_stdio, import_types, import_mindgraph, API_KEY, BASE_URL, AGENT_ID, client, INSTRUCTIONS, server, PROMPTS;
 var init_src = __esm({
   "src/index.ts"() {
     "use strict";
@@ -1079,7 +1081,7 @@ var init_src = __esm({
     AGENT_ID = process.env.MINDGRAPH_AGENT_ID || "mcp";
     if (!API_KEY) {
       console.error(
-        "Error: MINDGRAPH_API_KEY environment variable is required.\nGet your API key at https://mindgraph.cloud/dashboard/keys"
+        "Error: MINDGRAPH_API_KEY environment variable is required.\nGet your API key at https://mindgraph.cloud/dashboard/keys\nOr run: npx mindgraph-mcp init"
       );
       process.exit(1);
     }
@@ -1087,16 +1089,62 @@ 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.
+
+## When to WRITE to the graph
+
+Store knowledge whenever the user shares something worth remembering:
+- **People, organizations, places, events** \u2192 \`mindgraph_capture\` with action "entity" and the appropriate entity_type
+- **Quick notes, preferences, reflections, moods** \u2192 \`mindgraph_journal\`
+- **Factual observations about the world** \u2192 \`mindgraph_capture\` with action "observation"
+- **Claims that could be true or false** \u2192 \`mindgraph_argue\` (with evidence if available)
+- **Questions to investigate later** \u2192 \`mindgraph_inquire\` with action "open_question"
+- **Hypotheses or theories** \u2192 \`mindgraph_inquire\` with action "hypothesis" or "theory"
+- **Goals or projects the user is working on** \u2192 \`mindgraph_commit\`
+- **Decisions being made** \u2192 \`mindgraph_decide\` (open, add options, resolve)
+- **Long-form content (articles, transcripts, documents)** \u2192 \`mindgraph_ingest\`
+
+## 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 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
+
+## Session management
+
+- Open a session with \`mindgraph_session\` action "open" at the start of a substantial conversation
+- Use action "trace" to mark key moments during the conversation
+- Close the session with action "close" and a summary at the end
+
+## Tool selection guide
+
+- **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_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
+
+- Be proactive: if the user mentions a person, place, or organization you haven't captured yet, capture it
+- Deduplicate: the graph handles entity deduplication automatically \u2014 don't worry about creating duplicates
+- Confidence scores: use 0.9+ for things the user states as fact, 0.5-0.8 for uncertain claims, below 0.5 for speculation
+- Don't narrate tool usage excessively \u2014 capture knowledge naturally as part of the conversation`;
     server = new import_server.Server(
       {
         name: "mindgraph",
-        version: "0.1.0"
+        version: "0.2.1"
       },
       {
         capabilities: {
           tools: {},
-          resources: {}
-        }
+          resources: {},
+          prompts: {}
+        },
+        instructions: INSTRUCTIONS
       }
     );
     server.setRequestHandler(import_types.ListToolsRequestSchema, async () => {
@@ -1110,6 +1158,164 @@ var init_src = __esm({
       }
       return handleTool(client, name, toolArgs);
     });
+    PROMPTS = [
+      {
+        name: "graph-summary",
+        description: "Get a comprehensive summary of what's in your knowledge graph \u2014 entities, claims, goals, and open questions.",
+        arguments: []
+      },
+      {
+        name: "active-goals",
+        description: "Review your active goals, projects, and milestones with their current status.",
+        arguments: []
+      },
+      {
+        name: "open-questions",
+        description: "List all open questions and hypotheses that need investigation.",
+        arguments: []
+      },
+      {
+        name: "review-contradictions",
+        description: "Find and analyze contradictions in your knowledge graph \u2014 claims that conflict with each other.",
+        arguments: []
+      },
+      {
+        name: "knowledge-about",
+        description: "Retrieve everything the knowledge graph knows about a specific topic.",
+        arguments: [
+          {
+            name: "topic",
+            description: "The topic to search for",
+            required: true
+          }
+        ]
+      },
+      {
+        name: "daily-briefing",
+        description: "Get a daily briefing: active goals, recent knowledge, open questions, and pending decisions.",
+        arguments: []
+      },
+      {
+        name: "capture-conversation",
+        description: "Analyze the current conversation and capture all important entities, claims, decisions, and action items into the knowledge graph.",
+        arguments: [
+          {
+            name: "conversation",
+            description: "The conversation text to analyze and capture",
+            required: true
+          }
+        ]
+      }
+    ];
+    server.setRequestHandler(import_types.ListPromptsRequestSchema, async () => {
+      return { prompts: PROMPTS };
+    });
+    server.setRequestHandler(import_types.GetPromptRequestSchema, async (request) => {
+      const { name, arguments: args } = request.params;
+      switch (name) {
+        case "graph-summary":
+          return {
+            messages: [
+              {
+                role: "user",
+                content: {
+                  type: "text",
+                  text: "Give me a comprehensive summary of my knowledge graph. Start by checking the graph stats, then retrieve my active goals, open questions, and any recent knowledge. Organize the summary by cognitive layer (Reality, Epistemic, Intent, Action, Memory)."
+                }
+              }
+            ]
+          };
+        case "active-goals":
+          return {
+            messages: [
+              {
+                role: "user",
+                content: {
+                  type: "text",
+                  text: "Review all my active goals, projects, and milestones. For each one, show its status, any linked decisions or tasks, and suggest next steps. Group them by project if applicable."
+                }
+              }
+            ]
+          };
+        case "open-questions":
+          return {
+            messages: [
+              {
+                role: "user",
+                content: {
+                  type: "text",
+                  text: "List all my open questions and hypotheses. For each one, check if there's any related evidence or claims in the graph that might help answer them. Prioritize by salience and suggest which ones I should investigate first."
+                }
+              }
+            ]
+          };
+        case "review-contradictions":
+          return {
+            messages: [
+              {
+                role: "user",
+                content: {
+                  type: "text",
+                  text: "Search my knowledge graph for contradictions \u2014 claims that conflict with each other, or evidence that undermines existing beliefs. Also look for weak claims (low confidence) that might need more evidence. For each contradiction found, explain the conflict and suggest how to resolve it."
+                }
+              }
+            ]
+          };
+        case "knowledge-about": {
+          const topic = args?.topic || "general";
+          return {
+            messages: [
+              {
+                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.`
+                }
+              }
+            ]
+          };
+        }
+        case "daily-briefing":
+          return {
+            messages: [
+              {
+                role: "user",
+                content: {
+                  type: "text",
+                  text: "Give me a daily briefing. Check:\n1. Active goals and their progress\n2. Open decisions that need resolution\n3. Recent knowledge added in the last few days\n4. Open questions worth investigating\n5. Any pending approvals\n6. Weak claims that need more evidence\n\nKeep it concise and actionable \u2014 highlight what needs my attention today."
+                }
+              }
+            ]
+          };
+        case "capture-conversation": {
+          const conversation = args?.conversation || "";
+          return {
+            messages: [
+              {
+                role: "user",
+                content: {
+                  type: "text",
+                  text: `Analyze the following conversation and capture all important information into my knowledge graph. Extract:
+- Named entities (people, organizations, places, events)
+- Factual claims and observations
+- Decisions made or pending
+- Goals or commitments mentioned
+- Open questions raised
+- Any hypotheses or theories discussed
+
+Use the appropriate MindGraph tools for each type of knowledge.
+
+Conversation:
+${conversation}`
+                }
+              }
+            ]
+          };
+        }
+        default:
+          throw new Error(`Unknown prompt: ${name}`);
+      }
+    });
     server.setRequestHandler(import_types.ListResourcesRequestSchema, async () => {
       return {
         resources: [
@@ -1130,6 +1336,42 @@ var init_src = __esm({
             name: "Open Questions",
             description: "All open questions in the knowledge graph",
             mimeType: "application/json"
+          },
+          {
+            uri: "mindgraph://contradictions",
+            name: "Contradictions",
+            description: "Contradictory claims in the knowledge graph",
+            mimeType: "application/json"
+          },
+          {
+            uri: "mindgraph://decisions",
+            name: "Open Decisions",
+            description: "Unresolved decisions awaiting resolution",
+            mimeType: "application/json"
+          }
+        ]
+      };
+    });
+    server.setRequestHandler(import_types.ListResourceTemplatesRequestSchema, async () => {
+      return {
+        resourceTemplates: [
+          {
+            uriTemplate: "mindgraph://node/{uid}",
+            name: "Graph Node",
+            description: "Retrieve a specific node by its UID, including all properties, edges, and version history",
+            mimeType: "application/json"
+          },
+          {
+            uriTemplate: "mindgraph://search/{query}",
+            name: "Search Results",
+            description: "Full-text search across all nodes in the knowledge graph",
+            mimeType: "application/json"
+          },
+          {
+            uriTemplate: "mindgraph://layer/{layer}",
+            name: "Layer Nodes",
+            description: "List all nodes in a specific cognitive layer (reality, epistemic, intent, action, memory, agent)",
+            mimeType: "application/json"
           }
         ]
       };
@@ -1173,9 +1415,80 @@ var init_src = __esm({
             ]
           };
         }
-        default:
-          throw new Error(`Unknown resource: ${uri}`);
+        case "mindgraph://contradictions": {
+          const contradictions = await client.getContradictions();
+          return {
+            contents: [
+              {
+                uri,
+                mimeType: "application/json",
+                text: JSON.stringify(contradictions, null, 2)
+              }
+            ]
+          };
+        }
+        case "mindgraph://decisions": {
+          const decisions = await client.getOpenDecisions();
+          return {
+            contents: [
+              {
+                uri,
+                mimeType: "application/json",
+                text: JSON.stringify(decisions, null, 2)
+              }
+            ]
+          };
+        }
+      }
+      const nodeMatch = uri.match(/^mindgraph:\/\/node\/(.+)$/);
+      if (nodeMatch) {
+        const uid = decodeURIComponent(nodeMatch[1]);
+        const node = await client.getNode(uid);
+        const edges = await client.getEdges({ from_uid: uid });
+        const inEdges = await client.getEdges({ to_uid: uid });
+        return {
+          contents: [
+            {
+              uri,
+              mimeType: "application/json",
+              text: JSON.stringify(
+                { node, outgoing_edges: edges, incoming_edges: inEdges },
+                null,
+                2
+              )
+            }
+          ]
+        };
+      }
+      const searchMatch = uri.match(/^mindgraph:\/\/search\/(.+)$/);
+      if (searchMatch) {
+        const query = decodeURIComponent(searchMatch[1]);
+        const results = await client.hybridSearch(query, { k: 20 });
+        return {
+          contents: [
+            {
+              uri,
+              mimeType: "application/json",
+              text: JSON.stringify(results, null, 2)
+            }
+          ]
+        };
+      }
+      const layerMatch = uri.match(/^mindgraph:\/\/layer\/(.+)$/);
+      if (layerMatch) {
+        const layer = decodeURIComponent(layerMatch[1]);
+        const nodes = await client.getNodes({ layer, limit: 50 });
+        return {
+          contents: [
+            {
+              uri,
+              mimeType: "application/json",
+              text: JSON.stringify(nodes, null, 2)
+            }
+          ]
+        };
       }
+      throw new Error(`Unknown resource: ${uri}`);
     });
     main().catch((error) => {
       console.error("Fatal error:", error);
@@ -1234,7 +1547,7 @@ function getMcpServerEntry(apiKey, baseUrl) {
   if (baseUrl) env.MINDGRAPH_BASE_URL = baseUrl;
   return {
     command: "npx",
-    args: ["-y", "mindgraph-mcp"],
+    args: ["-y", "mindgraph-mcp@latest"],
     env
   };
 }
@@ -1272,7 +1585,7 @@ function installClaudeCode(apiKey, baseUrl) {
         "--",
         "npx",
         "-y",
-        "mindgraph-mcp"
+        "mindgraph-mcp@latest"
       ].join(" "),
       { stdio: "inherit" }
     );

package/dist/index.js

@@ -10,7 +10,7 @@ var import_mindgraph = require("mindgraph");
 var TOOLS = [
   {
     name: "mindgraph_session",
-    description: "Open, trace, or close a memory session. Sessions group related interactions and enable context continuity. Open a session at the start of a conversation, trace key moments during it, and close it at the end to trigger distillation.",
+    description: "Manage conversation sessions. ALWAYS open a session at the start of a substantial conversation (label it with the topic). Use 'trace' to bookmark key moments (decisions made, important facts shared). Close the session at the end with a summary of what was discussed. Sessions enable the graph to track conversation continuity and trigger knowledge distillation on close.",
     inputSchema: {
       type: "object",
       properties: {
@@ -45,7 +45,7 @@ var TOOLS = [
   },
   {
     name: "mindgraph_journal",
-    description: "Low-friction capture of observations, notes, preferences, and reflections. Creates a Journal node in the Memory layer. Use this for quick thoughts, user preferences, mood tracking, and daily notes that don't fit a formal structure.",
+    description: "Quick, informal capture for the user's inner world: preferences ('I prefer dark mode'), reflections ('I've been thinking about...'), moods, daily notes, and anything subjective. Use this instead of mindgraph_capture when the content is personal/informal rather than a structured fact about the external world. Good for: likes/dislikes, feelings, habits, reminders-to-self, freeform notes.",
     inputSchema: {
       type: "object",
       properties: {
@@ -80,7 +80,7 @@ var TOOLS = [
   },
   {
     name: "mindgraph_capture",
-    description: "Capture entities, observations, concepts, sources, and snippets into the Reality layer with automatic deduplication. Use 'entity' for people, organizations, places, events, nations, or abstract concepts. Use 'observation' for factual observations. Use 'source' for documents or references. Use 'snippet' for direct quotes linked to a source.",
+    description: "Capture structured facts about the external world into the Reality layer. Use proactively whenever the user mentions a named entity. Actions: 'entity' for people/orgs/places/events/nations/concepts (auto-deduplicates \u2014 safe to call even if already exists), 'observation' for factual statements about the world, 'source' for documents/URLs/references, 'snippet' for direct quotes from a source. Prefer this over mindgraph_journal when the content is an objective fact rather than a personal note.",
     inputSchema: {
       type: "object",
       properties: {
@@ -139,7 +139,7 @@ var TOOLS = [
   },
   {
     name: "mindgraph_argue",
-    description: "Construct a structured argument with claims, evidence, warrants, and rebuttals. Creates interconnected Epistemic layer nodes. Use this when you need to record or evaluate a reasoned position with supporting evidence and logical connections.",
+    description: "Record a claim WITH supporting evidence. Use when the user states something as true/false and provides reasoning or sources. Creates interconnected Claim + Evidence + Warrant nodes. Set confidence based on evidence strength: 0.9+ for well-sourced facts, 0.5-0.8 for plausible claims, below 0.5 for speculation. Prefer mindgraph_inquire instead when there's a question or hypothesis WITHOUT evidence yet.",
     inputSchema: {
       type: "object",
       properties: {
@@ -195,7 +195,7 @@ var TOOLS = [
   },
   {
     name: "mindgraph_inquire",
-    description: "Record questions, hypotheses, theories, anomalies, assumptions, and paradigms in the Epistemic layer. Use this to track open questions worth investigating, form testable hypotheses, flag anomalies that challenge existing understanding, or articulate theoretical frameworks.",
+    description: "Record things that need investigation or are uncertain. Use 'open_question' when the user asks something worth tracking ('How does X work?'), 'hypothesis' for testable predictions, 'theory' for explanatory frameworks, 'anomaly' for things that don't fit existing understanding, 'assumption' for unstated beliefs worth surfacing. These stay in the graph as open items until resolved. Prefer mindgraph_argue instead when there IS evidence to attach.",
     inputSchema: {
       type: "object",
       properties: {
@@ -246,7 +246,7 @@ var TOOLS = [
   },
   {
     name: "mindgraph_commit",
-    description: "Create goals, projects, and milestones in the Intent layer. Use 'goal' for desired outcomes, 'project' for organized efforts toward goals, and 'milestone' for measurable checkpoints within projects.",
+    description: "Track the user's goals, projects, and milestones. Use 'goal' when the user expresses a desired outcome ('I want to learn Rust'), 'project' for organized efforts ('my blog redesign'), 'milestone' for checkpoints ('launch MVP by March'). Link milestones to projects and projects to goals via parent_uid. These appear in daily briefings and active goals queries.",
     inputSchema: {
       type: "object",
       properties: {
@@ -291,7 +291,7 @@ var TOOLS = [
   },
   {
     name: "mindgraph_decide",
-    description: "Manage decisions through their full lifecycle: open a decision, add options and constraints, then resolve by choosing an option. Use 'get_open' to list all unresolved decisions.",
+    description: "Track decisions through their lifecycle. Use 'open_decision' when the user faces a choice ('Should I use Postgres or SQLite?'), 'add_option' to record each alternative, 'add_constraint' for requirements or dealbreakers, 'resolve' when a choice is made. Use 'get_open' to review pending decisions. This creates a structured decision record that can be referenced later.",
     inputSchema: {
       type: "object",
       properties: {
@@ -330,7 +330,7 @@ var TOOLS = [
   },
   {
     name: "mindgraph_action",
-    description: "Record procedural knowledge (workflows, steps, affordances, controls) and risk assessments in the Action layer. Use this for SOPs, runbooks, capability mappings, and risk analysis.",
+    description: "Record procedural knowledge and risk assessments. Use 'create_flow' for workflows/processes, 'add_step' for individual steps in a flow, 'add_affordance' for capabilities ('this API supports batch operations'), 'add_control' for guardrails/constraints. Use 'assess_risk' when the user identifies a risk or potential problem. Less commonly used than capture/argue/commit \u2014 reach for this when the conversation is about HOW to do something.",
     inputSchema: {
       type: "object",
       properties: {
@@ -372,7 +372,7 @@ var TOOLS = [
   },
   {
     name: "mindgraph_plan",
-    description: "Create and manage plans, tasks, execution tracking, and governance policies in the Agent layer. Supports full task lifecycle from creation through completion, plan hierarchies, and approval workflows.",
+    description: "Agent-level task management and governance. Use 'create_plan'/'create_task'/'add_step' for breaking down work into trackable items, 'update_status' to mark progress, 'start_execution'/'complete_execution'/'fail_execution' for execution tracking. Use 'create_policy' and 'request_approval' for governance workflows. Prefer mindgraph_commit for the user's goals/projects; use mindgraph_plan for agent-managed task breakdowns and execution.",
     inputSchema: {
       type: "object",
       properties: {
@@ -428,7 +428,7 @@ var TOOLS = [
   },
   {
     name: "mindgraph_retrieve",
-    description: "Search and query the knowledge graph. Supports hybrid (text + semantic) search, active goals, open questions, weak claims, pending approvals, contradictions, layer-filtered retrieval, and rich context retrieval that follows graph edges from matching chunks.",
+    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.",
     inputSchema: {
       type: "object",
       properties: {
@@ -483,7 +483,7 @@ var TOOLS = [
   },
   {
     name: "mindgraph_ingest",
-    description: "Ingest long-form content into the knowledge graph. Supports single chunks (synchronous), full documents (async with job tracking), and session transcripts. The ingestion pipeline automatically extracts entities, claims, relationships, and structures across cognitive layers.",
+    description: "Ingest long-form content (articles, transcripts, documents, meeting notes) into the knowledge graph. The pipeline automatically chunks the text, extracts entities/claims/relationships via LLM, and deduplicates against existing nodes. Use 'chunk' for a single passage (synchronous), 'document' for full documents (async \u2014 returns a job ID), 'session' for conversation transcripts. Use 'job_status' to check progress. For short individual facts, use the specific cognitive tools instead.",
     inputSchema: {
       type: "object",
       properties: {
@@ -1038,7 +1038,7 @@ var BASE_URL = process.env.MINDGRAPH_BASE_URL || "https://api.mindgraph.cloud";
 var AGENT_ID = process.env.MINDGRAPH_AGENT_ID || "mcp";
 if (!API_KEY) {
   console.error(
-    "Error: MINDGRAPH_API_KEY environment variable is required.\nGet your API key at https://mindgraph.cloud/dashboard/keys"
+    "Error: MINDGRAPH_API_KEY environment variable is required.\nGet your API key at https://mindgraph.cloud/dashboard/keys\nOr run: npx mindgraph-mcp init"
   );
   process.exit(1);
 }
@@ -1046,16 +1046,62 @@ 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.
+
+## When to WRITE to the graph
+
+Store knowledge whenever the user shares something worth remembering:
+- **People, organizations, places, events** \u2192 \`mindgraph_capture\` with action "entity" and the appropriate entity_type
+- **Quick notes, preferences, reflections, moods** \u2192 \`mindgraph_journal\`
+- **Factual observations about the world** \u2192 \`mindgraph_capture\` with action "observation"
+- **Claims that could be true or false** \u2192 \`mindgraph_argue\` (with evidence if available)
+- **Questions to investigate later** \u2192 \`mindgraph_inquire\` with action "open_question"
+- **Hypotheses or theories** \u2192 \`mindgraph_inquire\` with action "hypothesis" or "theory"
+- **Goals or projects the user is working on** \u2192 \`mindgraph_commit\`
+- **Decisions being made** \u2192 \`mindgraph_decide\` (open, add options, resolve)
+- **Long-form content (articles, transcripts, documents)** \u2192 \`mindgraph_ingest\`
+
+## 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 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
+
+## Session management
+
+- Open a session with \`mindgraph_session\` action "open" at the start of a substantial conversation
+- Use action "trace" to mark key moments during the conversation
+- Close the session with action "close" and a summary at the end
+
+## Tool selection guide
+
+- **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_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
+
+- Be proactive: if the user mentions a person, place, or organization you haven't captured yet, capture it
+- Deduplicate: the graph handles entity deduplication automatically \u2014 don't worry about creating duplicates
+- Confidence scores: use 0.9+ for things the user states as fact, 0.5-0.8 for uncertain claims, below 0.5 for speculation
+- Don't narrate tool usage excessively \u2014 capture knowledge naturally as part of the conversation`;
 var server = new import_server.Server(
   {
     name: "mindgraph",
-    version: "0.1.0"
+    version: "0.2.1"
   },
   {
     capabilities: {
       tools: {},
-      resources: {}
-    }
+      resources: {},
+      prompts: {}
+    },
+    instructions: INSTRUCTIONS
   }
 );
 server.setRequestHandler(import_types.ListToolsRequestSchema, async () => {
@@ -1069,6 +1115,164 @@ server.setRequestHandler(import_types.CallToolRequestSchema, async (request) =>
   }
   return handleTool(client, name, toolArgs);
 });
+var PROMPTS = [
+  {
+    name: "graph-summary",
+    description: "Get a comprehensive summary of what's in your knowledge graph \u2014 entities, claims, goals, and open questions.",
+    arguments: []
+  },
+  {
+    name: "active-goals",
+    description: "Review your active goals, projects, and milestones with their current status.",
+    arguments: []
+  },
+  {
+    name: "open-questions",
+    description: "List all open questions and hypotheses that need investigation.",
+    arguments: []
+  },
+  {
+    name: "review-contradictions",
+    description: "Find and analyze contradictions in your knowledge graph \u2014 claims that conflict with each other.",
+    arguments: []
+  },
+  {
+    name: "knowledge-about",
+    description: "Retrieve everything the knowledge graph knows about a specific topic.",
+    arguments: [
+      {
+        name: "topic",
+        description: "The topic to search for",
+        required: true
+      }
+    ]
+  },
+  {
+    name: "daily-briefing",
+    description: "Get a daily briefing: active goals, recent knowledge, open questions, and pending decisions.",
+    arguments: []
+  },
+  {
+    name: "capture-conversation",
+    description: "Analyze the current conversation and capture all important entities, claims, decisions, and action items into the knowledge graph.",
+    arguments: [
+      {
+        name: "conversation",
+        description: "The conversation text to analyze and capture",
+        required: true
+      }
+    ]
+  }
+];
+server.setRequestHandler(import_types.ListPromptsRequestSchema, async () => {
+  return { prompts: PROMPTS };
+});
+server.setRequestHandler(import_types.GetPromptRequestSchema, async (request) => {
+  const { name, arguments: args } = request.params;
+  switch (name) {
+    case "graph-summary":
+      return {
+        messages: [
+          {
+            role: "user",
+            content: {
+              type: "text",
+              text: "Give me a comprehensive summary of my knowledge graph. Start by checking the graph stats, then retrieve my active goals, open questions, and any recent knowledge. Organize the summary by cognitive layer (Reality, Epistemic, Intent, Action, Memory)."
+            }
+          }
+        ]
+      };
+    case "active-goals":
+      return {
+        messages: [
+          {
+            role: "user",
+            content: {
+              type: "text",
+              text: "Review all my active goals, projects, and milestones. For each one, show its status, any linked decisions or tasks, and suggest next steps. Group them by project if applicable."
+            }
+          }
+        ]
+      };
+    case "open-questions":
+      return {
+        messages: [
+          {
+            role: "user",
+            content: {
+              type: "text",
+              text: "List all my open questions and hypotheses. For each one, check if there's any related evidence or claims in the graph that might help answer them. Prioritize by salience and suggest which ones I should investigate first."
+            }
+          }
+        ]
+      };
+    case "review-contradictions":
+      return {
+        messages: [
+          {
+            role: "user",
+            content: {
+              type: "text",
+              text: "Search my knowledge graph for contradictions \u2014 claims that conflict with each other, or evidence that undermines existing beliefs. Also look for weak claims (low confidence) that might need more evidence. For each contradiction found, explain the conflict and suggest how to resolve it."
+            }
+          }
+        ]
+      };
+    case "knowledge-about": {
+      const topic = args?.topic || "general";
+      return {
+        messages: [
+          {
+            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.`
+            }
+          }
+        ]
+      };
+    }
+    case "daily-briefing":
+      return {
+        messages: [
+          {
+            role: "user",
+            content: {
+              type: "text",
+              text: "Give me a daily briefing. Check:\n1. Active goals and their progress\n2. Open decisions that need resolution\n3. Recent knowledge added in the last few days\n4. Open questions worth investigating\n5. Any pending approvals\n6. Weak claims that need more evidence\n\nKeep it concise and actionable \u2014 highlight what needs my attention today."
+            }
+          }
+        ]
+      };
+    case "capture-conversation": {
+      const conversation = args?.conversation || "";
+      return {
+        messages: [
+          {
+            role: "user",
+            content: {
+              type: "text",
+              text: `Analyze the following conversation and capture all important information into my knowledge graph. Extract:
+- Named entities (people, organizations, places, events)
+- Factual claims and observations
+- Decisions made or pending
+- Goals or commitments mentioned
+- Open questions raised
+- Any hypotheses or theories discussed
+
+Use the appropriate MindGraph tools for each type of knowledge.
+
+Conversation:
+${conversation}`
+            }
+          }
+        ]
+      };
+    }
+    default:
+      throw new Error(`Unknown prompt: ${name}`);
+  }
+});
 server.setRequestHandler(import_types.ListResourcesRequestSchema, async () => {
   return {
     resources: [
@@ -1089,6 +1293,42 @@ server.setRequestHandler(import_types.ListResourcesRequestSchema, async () => {
         name: "Open Questions",
         description: "All open questions in the knowledge graph",
         mimeType: "application/json"
+      },
+      {
+        uri: "mindgraph://contradictions",
+        name: "Contradictions",
+        description: "Contradictory claims in the knowledge graph",
+        mimeType: "application/json"
+      },
+      {
+        uri: "mindgraph://decisions",
+        name: "Open Decisions",
+        description: "Unresolved decisions awaiting resolution",
+        mimeType: "application/json"
+      }
+    ]
+  };
+});
+server.setRequestHandler(import_types.ListResourceTemplatesRequestSchema, async () => {
+  return {
+    resourceTemplates: [
+      {
+        uriTemplate: "mindgraph://node/{uid}",
+        name: "Graph Node",
+        description: "Retrieve a specific node by its UID, including all properties, edges, and version history",
+        mimeType: "application/json"
+      },
+      {
+        uriTemplate: "mindgraph://search/{query}",
+        name: "Search Results",
+        description: "Full-text search across all nodes in the knowledge graph",
+        mimeType: "application/json"
+      },
+      {
+        uriTemplate: "mindgraph://layer/{layer}",
+        name: "Layer Nodes",
+        description: "List all nodes in a specific cognitive layer (reality, epistemic, intent, action, memory, agent)",
+        mimeType: "application/json"
       }
     ]
   };
@@ -1132,14 +1372,87 @@ server.setRequestHandler(import_types.ReadResourceRequestSchema, async (request)
         ]
       };
     }
-    default:
-      throw new Error(`Unknown resource: ${uri}`);
+    case "mindgraph://contradictions": {
+      const contradictions = await client.getContradictions();
+      return {
+        contents: [
+          {
+            uri,
+            mimeType: "application/json",
+            text: JSON.stringify(contradictions, null, 2)
+          }
+        ]
+      };
+    }
+    case "mindgraph://decisions": {
+      const decisions = await client.getOpenDecisions();
+      return {
+        contents: [
+          {
+            uri,
+            mimeType: "application/json",
+            text: JSON.stringify(decisions, null, 2)
+          }
+        ]
+      };
+    }
   }
+  const nodeMatch = uri.match(/^mindgraph:\/\/node\/(.+)$/);
+  if (nodeMatch) {
+    const uid = decodeURIComponent(nodeMatch[1]);
+    const node = await client.getNode(uid);
+    const edges = await client.getEdges({ from_uid: uid });
+    const inEdges = await client.getEdges({ to_uid: uid });
+    return {
+      contents: [
+        {
+          uri,
+          mimeType: "application/json",
+          text: JSON.stringify(
+            { node, outgoing_edges: edges, incoming_edges: inEdges },
+            null,
+            2
+          )
+        }
+      ]
+    };
+  }
+  const searchMatch = uri.match(/^mindgraph:\/\/search\/(.+)$/);
+  if (searchMatch) {
+    const query = decodeURIComponent(searchMatch[1]);
+    const results = await client.hybridSearch(query, { k: 20 });
+    return {
+      contents: [
+        {
+          uri,
+          mimeType: "application/json",
+          text: JSON.stringify(results, null, 2)
+        }
+      ]
+    };
+  }
+  const layerMatch = uri.match(/^mindgraph:\/\/layer\/(.+)$/);
+  if (layerMatch) {
+    const layer = decodeURIComponent(layerMatch[1]);
+    const nodes = await client.getNodes({ layer, limit: 50 });
+    return {
+      contents: [
+        {
+          uri,
+          mimeType: "application/json",
+          text: JSON.stringify(nodes, null, 2)
+        }
+      ]
+    };
+  }
+  throw new Error(`Unknown resource: ${uri}`);
 });
 async function main() {
   const transport = new import_stdio.StdioServerTransport();
   await server.connect(transport);
-  console.error("MindGraph MCP server running on stdio");
+  console.error(
+    `MindGraph MCP server v0.2.0 running on stdio (${BASE_URL})`
+  );
 }
 main().catch((error) => {
   console.error("Fatal error:", error);

package/package.json

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