mindgraph-mcp 0.3.3 → 0.4.0

package/dist/cli.js

@@ -41,20 +41,12 @@ function err(message) {
 async function handleTool(client2, name, args) {
   try {
     switch (name) {
-      case "mindgraph_journal":
-        return await handleJournal(client2, args);
       case "mindgraph_capture":
         return await handleCapture(client2, args);
-      case "mindgraph_argue":
-        return await handleArgue(client2, args);
-      case "mindgraph_inquire":
-        return await handleInquire(client2, args);
+      case "mindgraph_reason":
+        return await handleReason(client2, args);
       case "mindgraph_commit":
         return await handleCommit(client2, args);
-      case "mindgraph_decide":
-        return await handleDecide(client2, args);
-      case "mindgraph_action":
-        return await handleAction(client2, args);
       case "mindgraph_plan":
         return await handlePlan(client2, args);
       case "mindgraph_retrieve":
@@ -69,31 +61,29 @@ async function handleTool(client2, name, args) {
     return err(message);
   }
 }
-async function handleJournal(client2, args) {
-  const { label, content, mood, tags, agent_id } = args;
-  const props = { content };
-  if (mood) props.mood = mood;
-  if (tags) props.tags = tags;
-  const result = await client2.journal(
-    label,
-    props,
-    { agent_id }
-  );
-  return ok(result);
-}
 async function handleCapture(client2, args) {
   const {
     action,
     label,
     summary,
+    content,
     entity_type,
     source_uid,
+    mood,
+    tags,
     confidence,
     salience,
     props,
     agent_id
   } = args;
   switch (action) {
+    case "journal": {
+      if (!content) return err("content is required for action=journal");
+      const journalProps = { content };
+      if (mood) journalProps.mood = mood;
+      if (tags) journalProps.tags = tags;
+      return ok(await client2.journal(label, journalProps, { agent_id }));
+    }
     case "entity": {
       const type = entity_type || "concept";
       const entityProps = { ...props };
@@ -167,58 +157,85 @@ async function handleCapture(client2, args) {
       return err(`Unknown capture action: ${action}`);
   }
 }
-async function handleArgue(client2, args) {
-  const { claim, evidence, warrant, argument, agent_id } = args;
-  const result = await client2.argue({
+async function handleReason(client2, args) {
+  const {
+    action,
+    label,
+    summary,
     claim,
     evidence,
     warrant,
     argument,
-    agent_id
-  });
-  return ok(result);
-}
-async function handleInquire(client2, args) {
-  const { action, label, summary, confidence, salience, props, agent_id } = args;
-  const result = await client2.inquire({
-    action,
-    label,
-    summary,
     confidence,
     salience,
     props,
     agent_id
-  });
-  return ok(result);
+  } = args;
+  if (action === "claim") {
+    const claimObj = claim || (label ? { label, confidence } : null);
+    if (!claimObj) return err("claim object or label is required for action=claim");
+    return ok(
+      await client2.argue({
+        claim: claimObj,
+        evidence,
+        warrant,
+        argument,
+        agent_id
+      })
+    );
+  }
+  if (!label) return err(`label is required for action=${action}`);
+  return ok(
+    await client2.inquire({
+      action,
+      label,
+      summary,
+      confidence,
+      salience,
+      props,
+      agent_id
+    })
+  );
 }
 async function handleCommit(client2, args) {
-  const { action, label, summary, parent_uid, confidence, salience, props, agent_id } = args;
-  const result = await client2.commit({
+  const {
     action,
     label,
     summary,
     parent_uid,
+    decision_uid,
+    chosen_option_uid,
     confidence,
     salience,
     props,
     agent_id
-  });
-  return ok(result);
-}
-async function handleDecide(client2, args) {
-  const { action, label, summary, decision_uid, chosen_option_uid, props, agent_id } = args;
+  } = args;
   switch (action) {
+    case "goal":
+    case "project":
+    case "milestone":
+      if (!label) return err(`label is required for action=${action}`);
+      return ok(
+        await client2.commit({
+          action,
+          label,
+          summary,
+          parent_uid,
+          confidence,
+          salience,
+          props,
+          agent_id
+        })
+      );
     case "open_decision":
       if (!label) return err("label is required for open_decision");
       return ok(await client2.openDecision(label, { summary, props, agent_id }));
     case "add_option":
-      if (!decision_uid) return err("decision_uid is required");
+      if (!decision_uid) return err("decision_uid is required for add_option");
       if (!label) return err("label is required for add_option");
-      return ok(
-        await client2.addOption(decision_uid, label, { summary, props, agent_id })
-      );
+      return ok(await client2.addOption(decision_uid, label, { summary, props, agent_id }));
     case "add_constraint":
-      if (!decision_uid) return err("decision_uid is required");
+      if (!decision_uid) return err("decision_uid is required for add_constraint");
       return ok(
         await client2.deliberate({
           action: "add_constraint",
@@ -229,64 +246,35 @@ async function handleDecide(client2, args) {
           agent_id
         })
       );
-    case "resolve":
-      if (!decision_uid) return err("decision_uid is required");
-      if (!chosen_option_uid) return err("chosen_option_uid is required");
+    case "resolve_decision":
+      if (!decision_uid) return err("decision_uid is required for resolve_decision");
+      if (!chosen_option_uid) return err("chosen_option_uid is required for resolve_decision");
       return ok(
         await client2.resolveDecision(decision_uid, chosen_option_uid, {
           summary,
           agent_id
         })
       );
-    case "get_open":
+    case "get_open_decisions":
       return ok(await client2.getOpenDecisions());
     default:
-      return err(`Unknown decide action: ${action}`);
-  }
-}
-async function handleAction(client2, args) {
-  const { action, label, summary, target_uid, props, agent_id } = args;
-  switch (action) {
-    case "create_flow":
-    case "add_step":
-    case "add_affordance":
-    case "add_control":
-      return ok(
-        await client2.procedure({
-          action,
-          label,
-          summary,
-          target_uid,
-          props,
-          agent_id
-        })
-      );
-    case "assess_risk":
-      return ok(
-        await client2.risk({
-          action: "assess",
-          label,
-          summary,
-          target_uid,
-          props,
-          agent_id
-        })
-      );
-    case "get_assessments":
-      return ok(
-        await client2.risk({
-          action: "get_assessments",
-          target_uid,
-          agent_id
-        })
-      );
-    default:
-      return err(`Unknown action: ${action}`);
+      return err(`Unknown commit action: ${action}`);
   }
 }
 async function handlePlan(client2, args) {
-  const { action, label, summary, plan_uid, task_uid, status, props, agent_id } = args;
+  const {
+    action,
+    label,
+    summary,
+    plan_uid,
+    task_uid,
+    target_uid,
+    status,
+    props,
+    agent_id
+  } = args;
   switch (action) {
+    // Agent planning
     case "create_task":
     case "create_plan":
     case "add_step":
@@ -304,63 +292,70 @@ async function handlePlan(client2, args) {
           agent_id
         })
       );
+    // Execution tracking
     case "start_execution":
+      return ok(await client2.execution({ action: "start", task_uid, agent_id }));
+    case "complete_execution":
+      return ok(await client2.execution({ action: "complete", task_uid, agent_id }));
+    case "fail_execution":
+      return ok(await client2.execution({ action: "fail", task_uid, agent_id }));
+    // Governance
+    case "create_policy":
       return ok(
-        await client2.execution({
-          action: "start",
-          task_uid,
-          agent_id
-        })
+        await client2.governance({ action: "create_policy", label, summary, props, agent_id })
       );
-    case "complete_execution":
+    case "request_approval":
       return ok(
-        await client2.execution({
-          action: "complete",
-          task_uid,
-          agent_id
-        })
+        await client2.governance({ action: "request_approval", label, summary, props, agent_id })
       );
-    case "fail_execution":
+    case "resolve_approval":
       return ok(
-        await client2.execution({
-          action: "fail",
-          task_uid,
-          agent_id
-        })
+        await client2.governance({ action: "resolve_approval", task_uid, props, agent_id })
       );
-    case "create_policy":
+    case "get_pending":
+      return ok(await client2.governance({ action: "get_pending", agent_id }));
+    // Procedures (merged from mindgraph_action)
+    case "create_flow":
+    case "add_affordance":
+    case "add_control":
       return ok(
-        await client2.governance({
-          action: "create_policy",
+        await client2.procedure({
+          action,
           label,
           summary,
+          target_uid,
           props,
           agent_id
         })
       );
-    case "request_approval":
+    case "add_procedure_step":
       return ok(
-        await client2.governance({
-          action: "request_approval",
+        await client2.procedure({
+          action: "add_step",
           label,
           summary,
+          target_uid,
           props,
           agent_id
         })
       );
-    case "resolve_approval":
+    // Risk assessment (merged from mindgraph_action)
+    case "assess_risk":
       return ok(
-        await client2.governance({
-          action: "resolve_approval",
-          task_uid,
+        await client2.risk({
+          action: "assess",
+          label,
+          summary,
+          target_uid,
           props,
           agent_id
         })
       );
-    case "get_pending":
+    case "get_assessments":
       return ok(
-        await client2.governance({
-          action: "get_pending",
+        await client2.risk({
+          action: "get_assessments",
+          target_uid,
           agent_id
         })
       );
@@ -372,6 +367,11 @@ async function handleRetrieve(client2, args) {
   const {
     action,
     query,
+    start_uid,
+    end_uid,
+    max_depth,
+    direction,
+    edge_types,
     node_types,
     layer,
     limit,
@@ -406,6 +406,31 @@ async function handleRetrieve(client2, args) {
           agent_id
         })
       );
+    case "semantic":
+      if (!query) return err("query is required for semantic search");
+      return ok(
+        await client2.retrieve({
+          action: "semantic",
+          query,
+          k: limit,
+          node_types,
+          layer,
+          agent_id
+        })
+      );
+    case "hybrid":
+      if (!query) return err("query is required for hybrid search");
+      return ok(
+        await client2.retrieve({
+          action: "hybrid",
+          query,
+          k: limit,
+          node_types,
+          layer,
+          agent_id
+        })
+      );
+    // Structured queries
     case "active_goals":
       return ok(await client2.getGoals());
     case "open_questions":
@@ -437,6 +462,51 @@ async function handleRetrieve(client2, args) {
           agent_id
         })
       );
+    // Graph traversal
+    case "chain":
+      if (!start_uid) return err("start_uid is required for chain traversal");
+      return ok(
+        await client2.traverse({
+          action: "chain",
+          start_uid,
+          max_depth
+        })
+      );
+    case "neighborhood":
+      if (!start_uid) return err("start_uid is required for neighborhood traversal");
+      return ok(
+        await client2.traverse({
+          action: "neighborhood",
+          start_uid,
+          max_depth,
+          direction,
+          edge_types
+        })
+      );
+    case "path":
+      if (!start_uid) return err("start_uid is required for path traversal");
+      if (!end_uid) return err("end_uid is required for path traversal");
+      return ok(
+        await client2.traverse({
+          action: "path",
+          start_uid,
+          end_uid,
+          max_depth,
+          direction,
+          edge_types
+        })
+      );
+    case "subgraph":
+      if (!start_uid) return err("start_uid is required for subgraph traversal");
+      return ok(
+        await client2.traverse({
+          action: "subgraph",
+          start_uid,
+          max_depth,
+          direction,
+          edge_types
+        })
+      );
     default:
       return err(`Unknown retrieve action: ${action}`);
   }
@@ -493,72 +563,47 @@ var init_tools = __esm({
   "src/tools.ts"() {
     "use strict";
     TOOLS = [
-      {
-        name: "mindgraph_journal",
-        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: {
-            label: {
-              type: "string",
-              description: "Brief title for the journal entry"
-            },
-            content: {
-              type: "string",
-              description: "The journal content/body text"
-            },
-            mood: {
-              type: "string",
-              description: "Emotional tone or mood tag"
-            },
-            tags: {
-              type: "array",
-              items: { type: "string" },
-              description: "Categorization tags"
-            },
-            agent_id: {
-              type: "string",
-              description: "Agent identity"
-            }
-          },
-          required: ["label", "content"]
-        }
-      },
       {
         name: "mindgraph_capture",
-        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.",
+        description: "Capture knowledge into the graph. Use 'entity' for people/orgs/places/events/nations/concepts (auto-deduplicates \u2014 safe to call even if already exists), 'observation' for factual statements, 'source' for documents/URLs, 'snippet' for quotes from a source, 'concept' for abstract ideas. Use 'journal' for quick personal notes, preferences, reflections, moods \u2014 anything subjective or informal. Prefer 'entity'/'observation' for objective facts, 'journal' for personal notes.",
         inputSchema: {
           type: "object",
           properties: {
             action: {
               type: "string",
-              enum: ["entity", "observation", "source", "snippet", "concept"],
-              description: "Type of reality to capture"
+              enum: ["entity", "observation", "source", "snippet", "concept", "journal"],
+              description: "Type of knowledge to capture"
             },
             label: {
               type: "string",
-              description: "Name or title"
+              description: "Name, title, or brief heading"
             },
             summary: {
               type: "string",
-              description: "Description or summary text"
+              description: "Description or summary text (for entity/observation/source/snippet/concept)"
+            },
+            content: {
+              type: "string",
+              description: "Journal content/body text (for action=journal)"
             },
             entity_type: {
               type: "string",
-              enum: [
-                "person",
-                "organization",
-                "place",
-                "event",
-                "nation",
-                "concept"
-              ],
+              enum: ["person", "organization", "place", "event", "nation", "concept"],
               description: "Entity subtype (only for action=entity)"
             },
             source_uid: {
               type: "string",
               description: "Source node UID (for snippets)"
             },
+            mood: {
+              type: "string",
+              description: "Emotional tone or mood tag (for action=journal)"
+            },
+            tags: {
+              type: "array",
+              items: { type: "string" },
+              description: "Categorization tags (for action=journal)"
+            },
             confidence: {
               type: "number",
               minimum: 0,
@@ -584,11 +629,33 @@ var init_tools = __esm({
         }
       },
       {
-        name: "mindgraph_argue",
-        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.",
+        name: "mindgraph_reason",
+        description: "Record reasoning, claims, and open questions. Use 'claim' when the user states something as true/false with reasoning \u2014 creates interconnected Claim + Evidence + Warrant nodes. Set confidence by evidence: 0.9+ for well-sourced, 0.5-0.8 for plausible, <0.5 for speculation. Use 'open_question' for questions worth tracking, 'hypothesis' for testable predictions, 'theory' for explanatory frameworks, 'anomaly' for things that don't fit, 'assumption' for unstated beliefs. Prefer 'claim' when evidence exists, other actions when it doesn't yet.",
         inputSchema: {
           type: "object",
           properties: {
+            action: {
+              type: "string",
+              enum: [
+                "claim",
+                "question",
+                "open_question",
+                "hypothesis",
+                "theory",
+                "paradigm",
+                "anomaly",
+                "assumption"
+              ],
+              description: "Type of reasoning to record"
+            },
+            label: {
+              type: "string",
+              description: "The claim, question, or hypothesis statement (used for non-claim actions, or as fallback for claim if claim object omitted)"
+            },
+            summary: {
+              type: "string",
+              description: "Expanded description or context (for non-claim actions)"
+            },
             claim: {
               type: "object",
               properties: {
@@ -602,7 +669,7 @@ var init_tools = __esm({
                 }
               },
               required: ["label"],
-              description: "The central claim being argued"
+              description: "The central claim being argued (for action=claim)"
             },
             evidence: {
               type: "array",
@@ -614,7 +681,7 @@ var init_tools = __esm({
                 },
                 required: ["label"]
               },
-              description: "Supporting evidence items"
+              description: "Supporting evidence items (for action=claim)"
             },
             warrant: {
               type: "object",
@@ -622,61 +689,26 @@ var init_tools = __esm({
                 label: { type: "string" },
                 content: { type: "string" }
               },
-              description: "Logical warrant connecting evidence to claim"
+              description: "Logical warrant connecting evidence to claim (for action=claim)"
             },
             argument: {
               type: "object",
               properties: {
                 label: { type: "string" }
               },
-              description: "Top-level argument container"
-            },
-            agent_id: {
-              type: "string",
-              description: "Agent identity"
-            }
-          },
-          required: ["claim"]
-        }
-      },
-      {
-        name: "mindgraph_inquire",
-        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: {
-            action: {
-              type: "string",
-              enum: [
-                "question",
-                "open_question",
-                "hypothesis",
-                "theory",
-                "paradigm",
-                "anomaly",
-                "assumption"
-              ],
-              description: "Type of epistemic inquiry"
-            },
-            label: {
-              type: "string",
-              description: "The question, hypothesis, or theory statement"
-            },
-            summary: {
-              type: "string",
-              description: "Expanded description or context"
+              description: "Top-level argument container (for action=claim)"
             },
             confidence: {
               type: "number",
               minimum: 0,
               maximum: 1,
-              description: "Confidence level (0-1)"
+              description: "Confidence level (for non-claim actions)"
             },
             salience: {
               type: "number",
               minimum: 0,
               maximum: 1,
-              description: "Importance score (0-1)"
+              description: "Importance score (for non-claim actions)"
             },
             props: {
               type: "object",
@@ -687,31 +719,48 @@ var init_tools = __esm({
               description: "Agent identity"
             }
           },
-          required: ["action", "label"]
+          required: ["action"]
         }
       },
       {
         name: "mindgraph_commit",
-        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.",
+        description: "Track goals, projects, milestones, and decisions. Use 'goal' for desired outcomes ('I want to learn Rust'), 'project' for organized efforts, 'milestone' for checkpoints. Link milestones to projects and projects to goals via parent_uid. Use 'open_decision' when facing a choice ('Postgres vs SQLite?'), 'add_option'/'add_constraint' to build out alternatives, 'resolve_decision' to pick one, 'get_open_decisions' to review pending choices.",
         inputSchema: {
           type: "object",
           properties: {
             action: {
               type: "string",
-              enum: ["goal", "project", "milestone"],
-              description: "Type of commitment"
+              enum: [
+                "goal",
+                "project",
+                "milestone",
+                "open_decision",
+                "add_option",
+                "add_constraint",
+                "resolve_decision",
+                "get_open_decisions"
+              ],
+              description: "Commitment or decision action"
             },
             label: {
               type: "string",
-              description: "Name of the goal, project, or milestone"
+              description: "Name of the goal, project, milestone, decision, option, or constraint"
             },
             summary: {
               type: "string",
-              description: "Description and success criteria"
+              description: "Description, success criteria, or rationale"
             },
             parent_uid: {
               type: "string",
-              description: "Parent goal/project UID to link under"
+              description: "Parent goal/project UID to link under (for goal/project/milestone)"
+            },
+            decision_uid: {
+              type: "string",
+              description: "Decision UID (for add_option, add_constraint, resolve_decision)"
+            },
+            chosen_option_uid: {
+              type: "string",
+              description: "UID of the chosen option (for resolve_decision)"
             },
             confidence: {
               type: "number",
@@ -732,93 +781,12 @@ var init_tools = __esm({
               description: "Agent identity"
             }
           },
-          required: ["action", "label"]
-        }
-      },
-      {
-        name: "mindgraph_decide",
-        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: {
-            action: {
-              type: "string",
-              enum: ["open_decision", "add_option", "add_constraint", "resolve", "get_open"],
-              description: "Decision lifecycle action"
-            },
-            label: {
-              type: "string",
-              description: "Decision, option, or constraint label"
-            },
-            summary: {
-              type: "string",
-              description: "Description or rationale"
-            },
-            decision_uid: {
-              type: "string",
-              description: "Decision UID (for add_option, add_constraint, resolve)"
-            },
-            chosen_option_uid: {
-              type: "string",
-              description: "UID of the chosen option (for resolve)"
-            },
-            props: {
-              type: "object",
-              description: "Additional properties"
-            },
-            agent_id: {
-              type: "string",
-              description: "Agent identity"
-            }
-          },
-          required: ["action"]
-        }
-      },
-      {
-        name: "mindgraph_action",
-        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: {
-            action: {
-              type: "string",
-              enum: [
-                "create_flow",
-                "add_step",
-                "add_affordance",
-                "add_control",
-                "assess_risk",
-                "get_assessments"
-              ],
-              description: "Action layer operation"
-            },
-            label: {
-              type: "string",
-              description: "Flow, step, affordance, control, or risk label"
-            },
-            summary: {
-              type: "string",
-              description: "Description"
-            },
-            target_uid: {
-              type: "string",
-              description: "Parent flow/step UID or target node for risk assessment"
-            },
-            props: {
-              type: "object",
-              description: "Type-specific properties (e.g. likelihood, impact, mitigation for risks)"
-            },
-            agent_id: {
-              type: "string",
-              description: "Agent identity"
-            }
-          },
           required: ["action"]
         }
       },
       {
         name: "mindgraph_plan",
-        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.",
+        description: "Agent-level task management, governance, and procedural knowledge. Use 'create_plan'/'create_task'/'add_step' for task breakdowns, 'update_status' for progress, 'get_plan' to review. Use 'create_flow'/'add_procedure_step'/'add_affordance'/'add_control' for workflows and procedures. Use 'assess_risk'/'get_assessments' for risk analysis. Use 'create_policy'/'request_approval'/'resolve_approval'/'get_pending' for governance. Prefer mindgraph_commit for user goals/projects; use this for agent-managed execution.",
         inputSchema: {
           type: "object",
           properties: {
@@ -836,13 +804,19 @@ var init_tools = __esm({
                 "create_policy",
                 "request_approval",
                 "resolve_approval",
-                "get_pending"
+                "get_pending",
+                "create_flow",
+                "add_procedure_step",
+                "add_affordance",
+                "add_control",
+                "assess_risk",
+                "get_assessments"
               ],
-              description: "Agent layer operation"
+              description: "Planning, procedure, or governance action"
             },
             label: {
               type: "string",
-              description: "Task, plan, step, or policy label"
+              description: "Task, plan, step, flow, policy, or risk label"
             },
             summary: {
               type: "string",
@@ -854,7 +828,11 @@ var init_tools = __esm({
             },
             task_uid: {
               type: "string",
-              description: "Task/step UID (for update_status, execution actions)"
+              description: "Task/step UID (for update_status, execution actions, resolve_approval)"
+            },
+            target_uid: {
+              type: "string",
+              description: "Parent flow/step UID or target node (for procedure/risk actions)"
             },
             status: {
               type: "string",
@@ -862,7 +840,7 @@ var init_tools = __esm({
             },
             props: {
               type: "object",
-              description: "Additional properties"
+              description: "Additional properties (e.g. likelihood, impact, mitigation for risks)"
             },
             agent_id: {
               type: "string",
@@ -874,7 +852,7 @@ var init_tools = __esm({
       },
       {
         name: "mindgraph_retrieve",
-        description: "Search the knowledge graph. Primary action: 'context' \u2014 pass a short keyword query (specific nouns/terms, not sentences) for FTS + graph traversal results. Use 'text' for fast keyword-only lookup. Other actions ('active_goals', 'open_questions', 'weak_claims', 'pending_approvals', 'unresolved_contradictions', 'layer', 'recent') are ONLY for when the user explicitly asks about those topics \u2014 never pre-fetch them.",
+        description: "Search and explore the knowledge graph. Use 'context' (default) for BM25 keyword retrieval \u2014 pass 1-3 discriminating keywords (proper nouns, technical terms), not sentences. GOOD: 'Kissinger NATO'. BAD: 'What is Kissinger\\'s view on NATO?'. Use 'semantic' when keywords return nothing \u2014 good for conceptual/fuzzy queries where user words differ from stored labels. Use 'hybrid' to combine keyword + semantic. Use 'text' for fast keyword-only lookup. Use 'neighborhood' to explore around a known node, 'chain' for reasoning chains, 'path' between two nodes, 'subgraph' for connected components. Other actions ('active_goals', 'open_questions', etc.) only when the user explicitly asks.",
         inputSchema: {
           type: "object",
           properties: {
@@ -883,19 +861,47 @@ var init_tools = __esm({
               enum: [
                 "text",
                 "context",
+                "semantic",
+                "hybrid",
                 "active_goals",
                 "open_questions",
                 "weak_claims",
                 "pending_approvals",
                 "unresolved_contradictions",
                 "layer",
-                "recent"
+                "recent",
+                "chain",
+                "neighborhood",
+                "path",
+                "subgraph"
               ],
-              description: "Retrieval strategy"
+              description: "Retrieval or traversal strategy"
             },
             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: "Search query \u2014 for 'text'/'context': 1-3 BM25 keywords, drop filler words. For 'semantic'/'hybrid': natural language is OK since it uses vector similarity."
+            },
+            start_uid: {
+              type: "string",
+              description: "Starting node UID (for chain, neighborhood, path, subgraph)"
+            },
+            end_uid: {
+              type: "string",
+              description: "Target node UID (for path)"
+            },
+            max_depth: {
+              type: "number",
+              description: "Maximum traversal depth (for chain, neighborhood, path, subgraph)"
+            },
+            direction: {
+              type: "string",
+              enum: ["outgoing", "incoming", "both"],
+              description: "Traversal direction (for neighborhood, subgraph)"
+            },
+            edge_types: {
+              type: "array",
+              items: { type: "string" },
+              description: "Filter by edge types (for traversal actions)"
             },
             node_types: {
               type: "array",
@@ -904,15 +910,8 @@ var init_tools = __esm({
             },
             layer: {
               type: "string",
-              enum: [
-                "reality",
-                "epistemic",
-                "intent",
-                "action",
-                "memory",
-                "agent"
-              ],
-              description: "Filter by cognitive layer (for context, text, layer actions)"
+              enum: ["reality", "epistemic", "intent", "action", "memory", "agent"],
+              description: "Filter by cognitive layer"
             },
             limit: {
               type: "number",
@@ -1014,7 +1013,7 @@ async function main() {
   const transport = new import_stdio.StdioServerTransport();
   await server.connect(transport);
   console.error(
-    `MindGraph MCP server v0.3.2 running on stdio (${BASE_URL})`
+    `MindGraph MCP server v0.4.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;
@@ -1039,16 +1038,14 @@ var init_src = __esm({
       baseUrl: BASE_URL,
       apiKey: API_KEY
     });
-    INSTRUCTIONS = `You have access to a persistent knowledge graph via MindGraph.
+    INSTRUCTIONS = `You have access to a persistent knowledge graph via MindGraph (6 tools).
 
 ## #1 RULE: Go straight to the user's topic
 
 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.
 
 **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 retrieve active_goals, open_questions, 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
 
@@ -1056,45 +1053,55 @@ There is no session to open. There is no context to pre-load. Just search for wh
 
 **Example:** User says "Tell me about Indian philosophy and Taoism"
 \u2713 CORRECT: \`mindgraph_retrieve({action: "context", query: "Indian philosophy Taoism"})\`
-\u2717 WRONG: First retrieve active_goals, then open_questions, then search for the topic
+\u2717 WRONG: First retrieve active_goals, then open_questions, then search
+\u2717 WRONG: \`mindgraph_retrieve({action: "context", query: "Tell me about Indian philosophy and Taoism"})\` \u2014 natural language won't match BM25
+
+## Search strategy \u2014 keyword first, semantic as fallback
 
-## Search query style
+The default search uses BM25 keyword matching. Query with 1\u20133 discriminating terms (proper nouns, technical terms). Drop filler words.
 
-Full-text search (BM25) \u2014 use short keyword phrases, not natural language:
-- GOOD: \`"Rust async runtime"\`, \`"Indian philosophy Taoism"\`
-- BAD: \`"what do I know about async programming in Rust?"\`
+**Keyword examples:**
+- "What is Kissinger's view on NATO?" \u2192 query: \`"Kissinger NATO"\`
+- "Tell me about async in Rust" \u2192 query: \`"Rust async runtime"\`
+- "Implications of carbon tax?" \u2192 query: \`"carbon tax"\`
+
+If keyword search returns no results, escalate:
+1. Try synonyms (e.g. \`"global warming"\` instead of \`"climate change"\`)
+2. Use \`action: "semantic"\` \u2014 vector similarity, natural language OK (e.g. \`"ways to manage stress"\` finds "mental health" nodes)
+3. Use \`action: "hybrid"\` \u2014 combines BM25 + semantic for best coverage
 
 ## When to READ
 
 - 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
+- Explore around a known node \u2192 action "neighborhood" with start_uid
+- Find connections between nodes \u2192 action "path" with start_uid + end_uid
 
 ## When to WRITE
 
 Capture knowledge when the user shares something worth remembering:
 - People/orgs/places/events \u2192 \`mindgraph_capture\` action "entity"
-- Quick notes, preferences \u2192 \`mindgraph_journal\`
+- Quick notes, preferences \u2192 \`mindgraph_capture\` action "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\`
+- Claims with evidence \u2192 \`mindgraph_reason\` action "claim"
+- Questions to track \u2192 \`mindgraph_reason\` action "open_question"
+- Goals or projects \u2192 \`mindgraph_commit\` action "goal"/"project"
+- Decisions \u2192 \`mindgraph_commit\` action "open_decision"
 - 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
+- \`capture\`: "entity"/"observation" for facts, "journal" for personal/informal
+- \`reason\`: "claim" when evidence exists, "open_question"/"hypothesis" otherwise
+- \`retrieve\`: "context" (FTS default) \u2192 "semantic" (conceptual fallback) \u2192 "hybrid" (both)
+- \`retrieve\`: "neighborhood"/"chain"/"path"/"subgraph" for graph exploration
 - 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.3.3"
+        version: "0.4.0"
       },
       {
         capabilities: {
@@ -1227,7 +1234,7 @@ Capture knowledge when the user shares something worth remembering:
                 role: "user",
                 content: {
                   type: "text",
-                  text: `Search my knowledge graph for everything related to "${topic}". Use context retrieval with keyword queries to find entities, claims, evidence, questions, and any connected knowledge. Try multiple keyword variations to ensure broad coverage. Present a structured overview of what I know about this topic, highlighting any gaps or open questions.`
+                  text: `Search my knowledge graph for everything related to "${topic}". Use context retrieval with short BM25 keyword queries (1\u20133 discriminating terms extracted from the topic, not full sentences). Try multiple keyword variations and synonyms to ensure broad coverage. Present a structured overview of what I know about this topic, highlighting any gaps or open questions.`
                 }
               }
             ]
@@ -1254,14 +1261,12 @@ Capture knowledge when the user shares something worth remembering:
                 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.
+- Named entities (people, organizations, places, events) \u2192 mindgraph_capture action "entity"
+- Factual claims and observations \u2192 mindgraph_capture action "observation" or mindgraph_reason action "claim"
+- Decisions made or pending \u2192 mindgraph_commit action "open_decision"
+- Goals or commitments mentioned \u2192 mindgraph_commit action "goal"/"project"
+- Open questions raised \u2192 mindgraph_reason action "open_question"
+- Any hypotheses or theories discussed \u2192 mindgraph_reason action "hypothesis"/"theory"
 
 Conversation:
 ${conversation}`
@@ -1322,7 +1327,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"
           },
           {