mindgraph-mcp 0.3.1 → 0.3.3

package/dist/cli.js

@@ -41,8 +41,6 @@ function err(message) {
 async function handleTool(client2, name, args) {
   try {
     switch (name) {
-      case "mindgraph_session":
-        return await handleSession(client2, args);
       case "mindgraph_journal":
         return await handleJournal(client2, args);
       case "mindgraph_capture":
@@ -71,55 +69,15 @@ async function handleTool(client2, name, args) {
     return err(message);
   }
 }
-async function handleSession(client2, args) {
-  const { action, label, session_uid, summary, props, agent_id } = args;
-  switch (action) {
-    case "open": {
-      if (!label) return err("label is required for open");
-      const result = await client2.session({
-        action: "open",
-        label,
-        summary,
-        props,
-        agent_id
-      });
-      return ok(result);
-    }
-    case "trace": {
-      if (!session_uid) return err("session_uid is required for trace");
-      if (!label) return err("label is required for trace");
-      const result = await client2.session({
-        action: "trace",
-        label,
-        session_uid,
-        props,
-        agent_id
-      });
-      return ok(result);
-    }
-    case "close": {
-      if (!session_uid) return err("session_uid is required for close");
-      const result = await client2.session({
-        action: "close",
-        session_uid,
-        summary,
-        agent_id
-      });
-      return ok(result);
-    }
-    default:
-      return err(`Unknown session action: ${action}`);
-  }
-}
 async function handleJournal(client2, args) {
-  const { label, content, mood, tags, session_uid, agent_id } = 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,
-    { session_uid, agent_id }
+    { agent_id }
   );
   return ok(result);
 }
@@ -535,41 +493,6 @@ var init_tools = __esm({
   "src/tools.ts"() {
     "use strict";
     TOOLS = [
-      {
-        name: "mindgraph_session",
-        description: "Manage conversation sessions. Only open a session for long, substantive conversations \u2014 never as a first action. Use 'trace' to bookmark key moments (decisions, important facts). Close with a summary to trigger knowledge distillation. Sessions track conversation continuity but are optional for short interactions.",
-        inputSchema: {
-          type: "object",
-          properties: {
-            action: {
-              type: "string",
-              enum: ["open", "trace", "close"],
-              description: "Session lifecycle action"
-            },
-            label: {
-              type: "string",
-              description: "Session or trace label (required for open/trace)"
-            },
-            session_uid: {
-              type: "string",
-              description: "Session UID (required for trace/close)"
-            },
-            summary: {
-              type: "string",
-              description: "Session summary (used on close)"
-            },
-            props: {
-              type: "object",
-              description: "Additional properties"
-            },
-            agent_id: {
-              type: "string",
-              description: "Agent identity for multi-agent systems"
-            }
-          },
-          required: ["action"]
-        }
-      },
       {
         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.",
@@ -593,10 +516,6 @@ var init_tools = __esm({
               items: { type: "string" },
               description: "Categorization tags"
             },
-            session_uid: {
-              type: "string",
-              description: "Link to an active session"
-            },
             agent_id: {
               type: "string",
               description: "Agent identity"
@@ -955,7 +874,7 @@ var init_tools = __esm({
       },
       {
         name: "mindgraph_retrieve",
-        description: "Search and query the knowledge graph using full-text search (BM25). Use short keyword queries \u2014 specific nouns and terms, NOT full sentences. Only retrieve when the user's message references or benefits from stored knowledge \u2014 do NOT pre-fetch goals/questions/contradictions unless asked. Actions: 'context' for rich retrieval (FTS + graph traversal, returns connected entities and source chunks), 'text' for fast direct keyword search. Convenience queries (no query needed): 'active_goals', 'open_questions', 'weak_claims', 'pending_approvals', 'unresolved_contradictions'. Use 'layer' to browse a cognitive layer, 'recent' for latest additions.",
+        description: "Search the knowledge graph. 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.",
         inputSchema: {
           type: "object",
           properties: {
@@ -1095,7 +1014,7 @@ async function main() {
   const transport = new import_stdio.StdioServerTransport();
   await server.connect(transport);
   console.error(
-    `MindGraph MCP server v0.3.1 running on stdio (${BASE_URL})`
+    `MindGraph MCP server v0.3.2 running on stdio (${BASE_URL})`
   );
 }
 var import_server, import_stdio, import_types, import_mindgraph, API_KEY, BASE_URL, AGENT_ID, client, INSTRUCTIONS, server, PROMPTS;
@@ -1120,62 +1039,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.
+    INSTRUCTIONS = `You have access to a persistent knowledge graph via MindGraph.
 
-## Critical: minimize latency
+## #1 RULE: Go straight to the user's topic
 
-- **Jump straight to the user's topic.** Do NOT pre-fetch goals, open questions, or other convenience queries unless the user specifically asks about them.
-- **Parallelize tool calls.** When you need to search and capture at the same time, issue all calls in a single parallel batch \u2014 never serialize independent calls.
-- **Sessions are optional.** Only open a session if the conversation is long and substantive. Never open a session as a first action \u2014 answer the user's question first, then open a session in the background if warranted.
+When the user asks about something, your FIRST and ONLY action should be a SINGLE \`mindgraph_retrieve\` call with action "context" and keyword terms from their message. Nothing else first.
 
-## When to READ from the graph
+**NEVER do any of these before addressing the user's topic:**
+- Do NOT retrieve active_goals
+- Do NOT retrieve open_questions
+- Do NOT retrieve contradictions or weak_claims
+- Do NOT follow a "session lifecycle" or "warm-up" sequence
+- Do NOT make multiple serial retrieve calls when one "context" call covers it
 
-Only retrieve when the user's message references or would benefit from stored knowledge:
-- User asks about a topic \u2192 \`mindgraph_retrieve\` with action "context" and keyword query
-- User asks about goals \u2192 \`mindgraph_retrieve\` with action "active_goals"
-- User asks about open questions \u2192 \`mindgraph_retrieve\` with action "open_questions"
-- Before asserting something the user previously told you \u2192 retrieve to check
+There is no session to open. There is no context to pre-load. Just search for what the user asked about.
 
-Do NOT retrieve preemptively. If the user says "let's discuss X", search for X \u2014 don't also fetch goals, questions, and contradictions.
+**Example:** User says "Tell me about Indian philosophy and Taoism"
+\u2713 CORRECT: \`mindgraph_retrieve({action: "context", query: "Indian philosophy Taoism"})\`
+\u2717 WRONG: First retrieve active_goals, then open_questions, then search for the topic
 
 ## Search query style
 
-MindGraph uses **full-text search (BM25)**, not semantic/embedding search. Write queries as **short keyword phrases**, not natural language questions:
-- GOOD: \`"Rust async runtime"\`, \`"project deadline March"\`, \`"Sarah engineering manager"\`
-- BAD: \`"what do I know about async programming in Rust?"\`, \`"tell me about Sarah's role"\`
-
-Use the most specific nouns and terms from the topic. Multiple keywords broaden recall across label, summary, and content fields.
+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?"\`
 
-## When to WRITE to the graph
+## When to READ
 
-Store knowledge whenever the user shares something worth remembering:
-- **People, organizations, places, events** \u2192 \`mindgraph_capture\` with action "entity"
-- **Quick notes, preferences, reflections, moods** \u2192 \`mindgraph_journal\`
-- **Factual observations** \u2192 \`mindgraph_capture\` with action "observation"
-- **Claims with evidence** \u2192 \`mindgraph_argue\`
-- **Questions to track** \u2192 \`mindgraph_inquire\` with action "open_question"
-- **Hypotheses or theories** \u2192 \`mindgraph_inquire\` with action "hypothesis" or "theory"
-- **Goals or projects** \u2192 \`mindgraph_commit\`
-- **Decisions** \u2192 \`mindgraph_decide\`
-- **Long-form content** \u2192 \`mindgraph_ingest\`
+- 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
 
-## Tool selection guide
+## When to WRITE
 
-- **mindgraph_capture vs mindgraph_journal**: \`capture\` for structured entities and factual observations. \`journal\` for informal notes, preferences, and reflections.
-- **mindgraph_argue vs mindgraph_inquire**: \`argue\` when there's evidence. \`inquire\` for open questions and hypotheses without evidence yet.
-- **mindgraph_retrieve "text" vs "context"**: "text" for fast direct keyword lookup. "context" for richer retrieval that follows graph edges to connected entities and source chunks \u2014 best for RAG.
-- **mindgraph_ingest**: For content longer than a paragraph. Automatically extracts entities, claims, and relationships.
+Capture knowledge when the user shares something worth remembering:
+- People/orgs/places/events \u2192 \`mindgraph_capture\` action "entity"
+- Quick notes, preferences \u2192 \`mindgraph_journal\`
+- Factual observations \u2192 \`mindgraph_capture\` action "observation"
+- Claims with evidence \u2192 \`mindgraph_argue\`
+- Questions to track \u2192 \`mindgraph_inquire\` action "open_question"
+- Goals or projects \u2192 \`mindgraph_commit\`
+- Decisions \u2192 \`mindgraph_decide\`
+- Long-form content \u2192 \`mindgraph_ingest\`
 
-## Important behaviors
+## Tool tips
 
-- Be proactive about capturing: if the user mentions a person, place, or organization, capture it
-- Deduplicate: the graph handles deduplication automatically
-- Confidence scores: 0.9+ for stated facts, 0.5-0.8 for uncertain claims, below 0.5 for speculation
-- Don't narrate tool usage \u2014 capture knowledge naturally as part of the conversation`;
+- \`capture\` for structured/factual, \`journal\` for personal/informal
+- \`argue\` when evidence exists, \`inquire\` for open questions
+- \`text\` for fast lookup, \`context\` for rich retrieval with graph traversal
+- Confidence: 0.9+ for facts, 0.5-0.8 for uncertain, <0.5 for speculation
+- Don't narrate tool usage \u2014 capture naturally as part of conversation`;
     server = new import_server.Server(
       {
         name: "mindgraph",
-        version: "0.2.1"
+        version: "0.3.3"
       },
       {
         capabilities: {

package/dist/index.js

@@ -8,41 +8,6 @@ var import_mindgraph = require("mindgraph");
 
 // src/tools.ts
 var TOOLS = [
-  {
-    name: "mindgraph_session",
-    description: "Manage conversation sessions. Only open a session for long, substantive conversations \u2014 never as a first action. Use 'trace' to bookmark key moments (decisions, important facts). Close with a summary to trigger knowledge distillation. Sessions track conversation continuity but are optional for short interactions.",
-    inputSchema: {
-      type: "object",
-      properties: {
-        action: {
-          type: "string",
-          enum: ["open", "trace", "close"],
-          description: "Session lifecycle action"
-        },
-        label: {
-          type: "string",
-          description: "Session or trace label (required for open/trace)"
-        },
-        session_uid: {
-          type: "string",
-          description: "Session UID (required for trace/close)"
-        },
-        summary: {
-          type: "string",
-          description: "Session summary (used on close)"
-        },
-        props: {
-          type: "object",
-          description: "Additional properties"
-        },
-        agent_id: {
-          type: "string",
-          description: "Agent identity for multi-agent systems"
-        }
-      },
-      required: ["action"]
-    }
-  },
   {
     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.",
@@ -66,10 +31,6 @@ var TOOLS = [
           items: { type: "string" },
           description: "Categorization tags"
         },
-        session_uid: {
-          type: "string",
-          description: "Link to an active session"
-        },
         agent_id: {
           type: "string",
           description: "Agent identity"
@@ -428,7 +389,7 @@ var TOOLS = [
   },
   {
     name: "mindgraph_retrieve",
-    description: "Search and query the knowledge graph using full-text search (BM25). Use short keyword queries \u2014 specific nouns and terms, NOT full sentences. Only retrieve when the user's message references or benefits from stored knowledge \u2014 do NOT pre-fetch goals/questions/contradictions unless asked. Actions: 'context' for rich retrieval (FTS + graph traversal, returns connected entities and source chunks), 'text' for fast direct keyword search. Convenience queries (no query needed): 'active_goals', 'open_questions', 'weak_claims', 'pending_approvals', 'unresolved_contradictions'. Use 'layer' to browse a cognitive layer, 'recent' for latest additions.",
+    description: "Search the knowledge graph. 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.",
     inputSchema: {
       type: "object",
       properties: {
@@ -573,8 +534,6 @@ function err(message) {
 async function handleTool(client2, name, args) {
   try {
     switch (name) {
-      case "mindgraph_session":
-        return await handleSession(client2, args);
       case "mindgraph_journal":
         return await handleJournal(client2, args);
       case "mindgraph_capture":
@@ -603,55 +562,15 @@ async function handleTool(client2, name, args) {
     return err(message);
   }
 }
-async function handleSession(client2, args) {
-  const { action, label, session_uid, summary, props, agent_id } = args;
-  switch (action) {
-    case "open": {
-      if (!label) return err("label is required for open");
-      const result = await client2.session({
-        action: "open",
-        label,
-        summary,
-        props,
-        agent_id
-      });
-      return ok(result);
-    }
-    case "trace": {
-      if (!session_uid) return err("session_uid is required for trace");
-      if (!label) return err("label is required for trace");
-      const result = await client2.session({
-        action: "trace",
-        label,
-        session_uid,
-        props,
-        agent_id
-      });
-      return ok(result);
-    }
-    case "close": {
-      if (!session_uid) return err("session_uid is required for close");
-      const result = await client2.session({
-        action: "close",
-        session_uid,
-        summary,
-        agent_id
-      });
-      return ok(result);
-    }
-    default:
-      return err(`Unknown session action: ${action}`);
-  }
-}
 async function handleJournal(client2, args) {
-  const { label, content, mood, tags, session_uid, agent_id } = 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,
-    { session_uid, agent_id }
+    { agent_id }
   );
   return ok(result);
 }
@@ -1077,62 +996,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.
+var INSTRUCTIONS = `You have access to a persistent knowledge graph via MindGraph.
 
-## Critical: minimize latency
+## #1 RULE: Go straight to the user's topic
 
-- **Jump straight to the user's topic.** Do NOT pre-fetch goals, open questions, or other convenience queries unless the user specifically asks about them.
-- **Parallelize tool calls.** When you need to search and capture at the same time, issue all calls in a single parallel batch \u2014 never serialize independent calls.
-- **Sessions are optional.** Only open a session if the conversation is long and substantive. Never open a session as a first action \u2014 answer the user's question first, then open a session in the background if warranted.
+When the user asks about something, your FIRST and ONLY action should be a SINGLE \`mindgraph_retrieve\` call with action "context" and keyword terms from their message. Nothing else first.
 
-## When to READ from the graph
+**NEVER do any of these before addressing the user's topic:**
+- Do NOT retrieve active_goals
+- Do NOT retrieve open_questions
+- Do NOT retrieve contradictions or weak_claims
+- Do NOT follow a "session lifecycle" or "warm-up" sequence
+- Do NOT make multiple serial retrieve calls when one "context" call covers it
 
-Only retrieve when the user's message references or would benefit from stored knowledge:
-- User asks about a topic \u2192 \`mindgraph_retrieve\` with action "context" and keyword query
-- User asks about goals \u2192 \`mindgraph_retrieve\` with action "active_goals"
-- User asks about open questions \u2192 \`mindgraph_retrieve\` with action "open_questions"
-- Before asserting something the user previously told you \u2192 retrieve to check
+There is no session to open. There is no context to pre-load. Just search for what the user asked about.
 
-Do NOT retrieve preemptively. If the user says "let's discuss X", search for X \u2014 don't also fetch goals, questions, and contradictions.
+**Example:** User says "Tell me about Indian philosophy and Taoism"
+\u2713 CORRECT: \`mindgraph_retrieve({action: "context", query: "Indian philosophy Taoism"})\`
+\u2717 WRONG: First retrieve active_goals, then open_questions, then search for the topic
 
 ## Search query style
 
-MindGraph uses **full-text search (BM25)**, not semantic/embedding search. Write queries as **short keyword phrases**, not natural language questions:
-- GOOD: \`"Rust async runtime"\`, \`"project deadline March"\`, \`"Sarah engineering manager"\`
-- BAD: \`"what do I know about async programming in Rust?"\`, \`"tell me about Sarah's role"\`
-
-Use the most specific nouns and terms from the topic. Multiple keywords broaden recall across label, summary, and content fields.
+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?"\`
 
-## When to WRITE to the graph
+## When to READ
 
-Store knowledge whenever the user shares something worth remembering:
-- **People, organizations, places, events** \u2192 \`mindgraph_capture\` with action "entity"
-- **Quick notes, preferences, reflections, moods** \u2192 \`mindgraph_journal\`
-- **Factual observations** \u2192 \`mindgraph_capture\` with action "observation"
-- **Claims with evidence** \u2192 \`mindgraph_argue\`
-- **Questions to track** \u2192 \`mindgraph_inquire\` with action "open_question"
-- **Hypotheses or theories** \u2192 \`mindgraph_inquire\` with action "hypothesis" or "theory"
-- **Goals or projects** \u2192 \`mindgraph_commit\`
-- **Decisions** \u2192 \`mindgraph_decide\`
-- **Long-form content** \u2192 \`mindgraph_ingest\`
+- 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
 
-## Tool selection guide
+## When to WRITE
 
-- **mindgraph_capture vs mindgraph_journal**: \`capture\` for structured entities and factual observations. \`journal\` for informal notes, preferences, and reflections.
-- **mindgraph_argue vs mindgraph_inquire**: \`argue\` when there's evidence. \`inquire\` for open questions and hypotheses without evidence yet.
-- **mindgraph_retrieve "text" vs "context"**: "text" for fast direct keyword lookup. "context" for richer retrieval that follows graph edges to connected entities and source chunks \u2014 best for RAG.
-- **mindgraph_ingest**: For content longer than a paragraph. Automatically extracts entities, claims, and relationships.
+Capture knowledge when the user shares something worth remembering:
+- People/orgs/places/events \u2192 \`mindgraph_capture\` action "entity"
+- Quick notes, preferences \u2192 \`mindgraph_journal\`
+- Factual observations \u2192 \`mindgraph_capture\` action "observation"
+- Claims with evidence \u2192 \`mindgraph_argue\`
+- Questions to track \u2192 \`mindgraph_inquire\` action "open_question"
+- Goals or projects \u2192 \`mindgraph_commit\`
+- Decisions \u2192 \`mindgraph_decide\`
+- Long-form content \u2192 \`mindgraph_ingest\`
 
-## Important behaviors
+## Tool tips
 
-- Be proactive about capturing: if the user mentions a person, place, or organization, capture it
-- Deduplicate: the graph handles deduplication automatically
-- Confidence scores: 0.9+ for stated facts, 0.5-0.8 for uncertain claims, below 0.5 for speculation
-- Don't narrate tool usage \u2014 capture knowledge naturally as part of the conversation`;
+- \`capture\` for structured/factual, \`journal\` for personal/informal
+- \`argue\` when evidence exists, \`inquire\` for open questions
+- \`text\` for fast lookup, \`context\` for rich retrieval with graph traversal
+- Confidence: 0.9+ for facts, 0.5-0.8 for uncertain, <0.5 for speculation
+- Don't narrate tool usage \u2014 capture naturally as part of conversation`;
 var server = new import_server.Server(
   {
     name: "mindgraph",
-    version: "0.2.1"
+    version: "0.3.3"
   },
   {
     capabilities: {
@@ -1490,7 +1409,7 @@ async function main() {
   const transport = new import_stdio.StdioServerTransport();
   await server.connect(transport);
   console.error(
-    `MindGraph MCP server v0.3.1 running on stdio (${BASE_URL})`
+    `MindGraph MCP server v0.3.2 running on stdio (${BASE_URL})`
   );
 }
 main().catch((error) => {

package/package.json

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