mindgraph-mcp 0.3.0 → 0.3.1

package/dist/cli.js

@@ -537,7 +537,7 @@ var init_tools = __esm({
     TOOLS = [
       {
         name: "mindgraph_session",
-        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.",
+        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: {
@@ -955,7 +955,7 @@ var init_tools = __esm({
       },
       {
         name: "mindgraph_retrieve",
-        description: "Search and query the knowledge graph using full-text search (BM25). ALWAYS retrieve before answering questions about previously stored knowledge. Use short keyword queries \u2014 specific nouns and terms, NOT full sentences. Actions: 'context' for rich retrieval (FTS + graph traversal \u2014 best for RAG, returns connected entities and source chunks), 'text' for fast direct keyword search. Convenience queries (no query needed): 'active_goals', 'open_questions', 'weak_claims', 'pending_approvals', 'unresolved_contradictions'. Use 'layer' to browse a specific cognitive layer, 'recent' for latest additions.",
+        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.",
         inputSchema: {
           type: "object",
           properties: {
@@ -1095,7 +1095,7 @@ async function main() {
   const transport = new import_stdio.StdioServerTransport();
   await server.connect(transport);
   console.error(
-    `MindGraph MCP server v0.3.0 running on stdio (${BASE_URL})`
+    `MindGraph MCP server v0.3.1 running on stdio (${BASE_URL})`
   );
 }
 var import_server, import_stdio, import_types, import_mindgraph, API_KEY, BASE_URL, AGENT_ID, client, INSTRUCTIONS, server, PROMPTS;
@@ -1122,27 +1122,21 @@ var init_src = __esm({
     });
     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
+## Critical: minimize latency
 
-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\`
+- **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 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 "context" and keyword query
-- **"What are my goals?"** \u2192 \`mindgraph_retrieve\` with action "active_goals"
-- **"What questions are open?"** \u2192 \`mindgraph_retrieve\` with action "open_questions"
-- **Anything referencing past conversations or stored knowledge** \u2192 \`mindgraph_retrieve\` with action "context"
-- **Before making claims about things the user has told you** \u2192 retrieve first to avoid contradictions
+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
+
+Do NOT retrieve preemptively. If the user says "let's discuss X", search for X \u2014 don't also fetch goals, questions, and contradictions.
 
 ## Search query style
 
@@ -1152,26 +1146,32 @@ MindGraph uses **full-text search (BM25)**, not semantic/embedding search. Write
 
 Use the most specific nouns and terms from the topic. Multiple keywords broaden recall across label, summary, and content fields.
 
-## Session management
+## When to WRITE to the graph
 
-- 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
+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\`
 
 ## 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 "text" vs "context"**: Use "text" for fast direct keyword lookup. Use "context" for richer retrieval that searches nodes via FTS, then follows graph edges to find connected entities, claims, and source chunks \u2014 best for RAG and comprehensive answers.
-- **mindgraph_ingest**: Use for any content longer than a paragraph. It automatically extracts entities, claims, and relationships. For short facts, use the specific cognitive tools instead.
+- **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.
 
 ## 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`;
+- 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`;
     server = new import_server.Server(
       {
         name: "mindgraph",

package/dist/index.js

@@ -10,7 +10,7 @@ var import_mindgraph = require("mindgraph");
 var TOOLS = [
   {
     name: "mindgraph_session",
-    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.",
+    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: {
@@ -428,7 +428,7 @@ var TOOLS = [
   },
   {
     name: "mindgraph_retrieve",
-    description: "Search and query the knowledge graph using full-text search (BM25). ALWAYS retrieve before answering questions about previously stored knowledge. Use short keyword queries \u2014 specific nouns and terms, NOT full sentences. Actions: 'context' for rich retrieval (FTS + graph traversal \u2014 best for RAG, returns connected entities and source chunks), 'text' for fast direct keyword search. Convenience queries (no query needed): 'active_goals', 'open_questions', 'weak_claims', 'pending_approvals', 'unresolved_contradictions'. Use 'layer' to browse a specific cognitive layer, 'recent' for latest additions.",
+    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.",
     inputSchema: {
       type: "object",
       properties: {
@@ -1079,27 +1079,21 @@ var client = new import_mindgraph.MindGraph({
 });
 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
+## Critical: minimize latency
 
-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\`
+- **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 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 "context" and keyword query
-- **"What are my goals?"** \u2192 \`mindgraph_retrieve\` with action "active_goals"
-- **"What questions are open?"** \u2192 \`mindgraph_retrieve\` with action "open_questions"
-- **Anything referencing past conversations or stored knowledge** \u2192 \`mindgraph_retrieve\` with action "context"
-- **Before making claims about things the user has told you** \u2192 retrieve first to avoid contradictions
+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
+
+Do NOT retrieve preemptively. If the user says "let's discuss X", search for X \u2014 don't also fetch goals, questions, and contradictions.
 
 ## Search query style
 
@@ -1109,26 +1103,32 @@ MindGraph uses **full-text search (BM25)**, not semantic/embedding search. Write
 
 Use the most specific nouns and terms from the topic. Multiple keywords broaden recall across label, summary, and content fields.
 
-## Session management
+## When to WRITE to the graph
 
-- 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
+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\`
 
 ## 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 "text" vs "context"**: Use "text" for fast direct keyword lookup. Use "context" for richer retrieval that searches nodes via FTS, then follows graph edges to find connected entities, claims, and source chunks \u2014 best for RAG and comprehensive answers.
-- **mindgraph_ingest**: Use for any content longer than a paragraph. It automatically extracts entities, claims, and relationships. For short facts, use the specific cognitive tools instead.
+- **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.
 
 ## 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`;
+- 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`;
 var server = new import_server.Server(
   {
     name: "mindgraph",
@@ -1490,7 +1490,7 @@ async function main() {
   const transport = new import_stdio.StdioServerTransport();
   await server.connect(transport);
   console.error(
-    `MindGraph MCP server v0.3.0 running on stdio (${BASE_URL})`
+    `MindGraph MCP server v0.3.1 running on stdio (${BASE_URL})`
   );
 }
 main().catch((error) => {

package/package.json

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