mindgraph-mcp 0.19.0 → 0.21.0

package/dist/index.js

@@ -60,6 +60,9 @@ function loadHookEnv(dir) {
   }
 }
 
+// src/tools.ts
+var import_node_crypto5 = require("crypto");
+
 // src/error-detail.ts
 var import_mindgraph = require("mindgraph");
 function errorDetail(e) {
@@ -86,6 +89,22 @@ function conflictState(e) {
   }
   return lifted;
 }
+function toolError(e, fallbackCode) {
+  const body = e instanceof import_mindgraph.MindGraphError && e.body && typeof e.body === "object" && !Array.isArray(e.body) ? e.body : {};
+  const code = typeof body.code === "string" ? body.code : fallbackCode;
+  const payload = {
+    error: errorDetail(e),
+    ...conflictState(e),
+    ...e instanceof import_mindgraph.MindGraphError ? { status: e.status } : {},
+    ...code !== void 0 ? { code } : {},
+    ...typeof body.retriable === "boolean" ? { retriable: body.retriable } : {}
+  };
+  return {
+    content: [{ type: "text", text: JSON.stringify(payload) }],
+    structuredContent: payload,
+    isError: true
+  };
+}
 
 // src/codegraph.ts
 var import_node_child_process = require("child_process");
@@ -238,29 +257,29 @@ async function runProcess(executable, args, timeoutMs, env, cwd) {
     child.stderr.on("data", collect(stderr));
     child.on("error", (cause) => {
       clearTimeout(timer);
-      const error = new Error(cause.message);
-      error.kind = cause.code === "ENOENT" ? "absent" : "command_failed";
-      rejectPromise(error);
+      const error2 = new Error(cause.message);
+      error2.kind = cause.code === "ENOENT" ? "absent" : "command_failed";
+      rejectPromise(error2);
     });
     child.on("close", (code) => {
       clearTimeout(timer);
       if (timedOut) {
-        const error = new Error(`command timed out after ${timeoutMs}ms`);
-        error.kind = "timeout";
-        rejectPromise(error);
+        const error2 = new Error(`command timed out after ${timeoutMs}ms`);
+        error2.kind = "timeout";
+        rejectPromise(error2);
         return;
       }
       if (outputBytes > MAX_OUTPUT_BYTES) {
-        const error = new Error("codegraph output exceeded 5 MiB");
-        error.kind = "command_failed";
-        rejectPromise(error);
+        const error2 = new Error("codegraph output exceeded 5 MiB");
+        error2.kind = "command_failed";
+        rejectPromise(error2);
         return;
       }
       if (code !== 0) {
-        const error = new Error(Buffer.concat(stderr).toString("utf8").trim());
-        error.kind = "command_failed";
-        error.exitCode = code;
-        rejectPromise(error);
+        const error2 = new Error(Buffer.concat(stderr).toString("utf8").trim());
+        error2.kind = "command_failed";
+        error2.exitCode = code;
+        rejectPromise(error2);
         return;
       }
       resolvePromise(Buffer.concat(stdout).toString("utf8"));
@@ -813,9 +832,7 @@ function codeRefIdentityKey(ref) {
     qualified_name: ref.qualifiedName,
     disambiguator: {
       signature: ref.signature ?? "",
-      path: ref.path,
-      start_line: ref.startLine,
-      end_line: ref.endLine
+      path: ref.path
     }
   };
 }
@@ -1085,7 +1102,7 @@ async function handleCodeTool(client2, args, adapter = new CodegraphAdapter({ cw
     if (cause instanceof UnknownRepositoryError) {
       return err("unknown_repository", cause.message);
     }
-    return err("code_tool_failed", errorDetail(cause));
+    return toolError(cause, "code_tool_failed");
   }
 }
 async function attachCodeRefsToToolResult(client2, result, args, adapter) {
@@ -1193,7 +1210,7 @@ async function anchorCodeRef(client2, ref, repositoryUid, spaceUid, agentId) {
     identity_space_uid: spaceUid,
     agent_id: agentId
   });
-  if (response.uid) {
+  if (response.uid && response.created !== false && response.status !== "existing") {
     await client2.entity({
       action: "relate",
       source_uid: response.uid,
@@ -1556,8 +1573,8 @@ async function handleSyncTool(client2, args) {
       }
     }
     return ok2(await remote.memorySync(request));
-  } catch (error) {
-    return err2("sync_failed", errorDetail(error));
+  } catch (error2) {
+    return toolError(error2, "sync_failed");
   }
 }
 async function scanRepository(remote, repository, requested, provider, agentId) {
@@ -1595,6 +1612,9 @@ async function scanRepository(remote, repository, requested, provider, agentId)
   };
 }
 
+// src/memory-tool.ts
+var import_node_crypto4 = require("crypto");
+
 // src/render.ts
 var LABEL_MAX = 200;
 var SUMMARY_MAX = 400;
@@ -1603,6 +1623,8 @@ var ARTICLE_MAX = 6e3;
 var CHUNK_MAX = 6e3;
 var RELATIONSHIP_MAX = 40;
 var RENDER_CHAR_BUDGET = 24e3;
+var MIN_RENDER_CHAR_BUDGET = 512;
+var BOUNDED_MARKER_RESERVE = 220;
 var CURATION_EDGE_TYPES = /* @__PURE__ */ new Set(["POSSIBLE_DUPLICATE", "PossibleDuplicate"]);
 var INFRA_NODE_TYPES = /* @__PURE__ */ new Set(["Chunk", "Document", "Article"]);
 function obj(value) {
@@ -1614,12 +1636,22 @@ function str(value) {
 function num(value) {
   return typeof value === "number" && Number.isFinite(value) ? value : void 0;
 }
+function edgeTypeName(value) {
+  return str(value) ?? str(obj(value)?.Custom);
+}
+function renderBudget(requested) {
+  if (requested === void 0 || !Number.isFinite(requested)) return RENDER_CHAR_BUDGET;
+  return Math.min(
+    RENDER_CHAR_BUDGET,
+    Math.max(MIN_RENDER_CHAR_BUDGET, Math.floor(requested))
+  );
+}
 function clip(value, max, state) {
-  const text = str(value);
-  if (!text) return void 0;
-  if (text.length <= max) return text;
+  const text2 = str(value);
+  if (!text2) return void 0;
+  if (text2.length <= max) return text2;
   state.bounded = true;
-  return `${text.slice(0, max - 1)}\u2026`;
+  return `${text2.slice(0, max - 1)}\u2026`;
 }
 function isNodeShaped(value) {
   const node = obj(value);
@@ -1741,7 +1773,7 @@ function relationshipItems(edges, labelByUid, state, options) {
   for (const raw of edges) {
     const edge = obj(raw);
     if (!edge) continue;
-    const type = str(edge.edge_type) || "?";
+    const type = edgeTypeName(edge.edge_type) || "?";
     const from = str(edge.from_uid);
     const to = str(edge.to_uid);
     if (CURATION_EDGE_TYPES.has(type)) continue;
@@ -1754,25 +1786,29 @@ function relationshipItems(edges, labelByUid, state, options) {
   if (lines.length > RELATIONSHIP_MAX) {
     state.bounded = true;
     const extra = lines.length - RELATIONSHIP_MAX;
+    state.omitted += extra;
     return [...lines.slice(0, RELATIONSHIP_MAX), `- (+${extra} more relationships)`];
   }
   return lines;
 }
-function assemble(header, sections, state) {
+function assemble(header, sections, state, maxChars) {
+  const budget = renderBudget(maxChars);
+  const packingBudget = Math.max(header.length, budget - BOUNDED_MARKER_RESERVE);
   const lines = [header];
   let used = header.length;
   for (const section of sections) {
     if (section.items.length === 0 && !section.heading) continue;
     const headingCost = section.heading.length + 2;
-    if (used + headingCost > RENDER_CHAR_BUDGET) {
+    if (used + headingCost > packingBudget) {
       state.bounded = true;
+      state.omitted += Math.max(1, section.items.length);
       continue;
     }
     let sectionUsed = 0;
     const kept = [];
     let dropped = 0;
     for (const item of section.items) {
-      if (used + headingCost + sectionUsed + item.length + 1 > RENDER_CHAR_BUDGET) {
+      if (used + headingCost + sectionUsed + item.length + 1 > packingBudget) {
         dropped += 1;
         continue;
       }
@@ -1781,13 +1817,17 @@ function assemble(header, sections, state) {
     }
     if (kept.length === 0 && section.items.length > 0) {
       state.bounded = true;
+      state.omitted += dropped;
       continue;
     }
     if (dropped > 0) {
       state.bounded = true;
+      state.omitted += dropped;
       const marker = `(+${dropped} more not shown)`;
-      kept.push(marker);
-      sectionUsed += marker.length + 1;
+      if (used + headingCost + sectionUsed + marker.length + 1 <= packingBudget) {
+        kept.push(marker);
+        sectionUsed += marker.length + 1;
+      }
     }
     lines.push(
       section.items.length === 0 ? section.heading : section.heading ? `${section.heading}
@@ -1797,10 +1837,10 @@ ${kept.join("\n")}` : kept.join("\n")
   }
   if (state.bounded) {
     lines.push(
-      '\u2026[rendered context bounded \u2014 fetch full node content by uid, or pass format: "json" for the raw response]'
+      `\u2026[rendered context bounded to ${budget} chars; ${state.omitted} item(s) omitted \u2014 fetch full node content by uid, narrow the query, raise max_output_chars, or pass format: "json" for the raw response]`
     );
   }
-  return lines.join("\n\n");
+  return lines.join("\n\n").slice(0, budget);
 }
 function policySections(payload, state) {
   const policies = Array.isArray(payload.applicable_policies) ? payload.applicable_policies : [];
@@ -1821,7 +1861,7 @@ function hiddenSections(payload) {
     }
   ];
 }
-function renderContext(response) {
+function renderContext(response, maxChars) {
   const payload = obj(response);
   if (!payload) return void 0;
   const graph = obj(payload.graph);
@@ -1831,7 +1871,7 @@ function renderContext(response) {
   const infraOnly = shaped.length - nodes.length;
   const articles = Array.isArray(payload.articles) ? payload.articles : [];
   const chunks = Array.isArray(payload.chunks) ? payload.chunks : [];
-  const state = { bounded: false };
+  const state = { bounded: false, omitted: 0 };
   const sections = [];
   if (articles.length > 0) {
     sections.push({
@@ -1874,11 +1914,129 @@ ${clip(article.content, ARTICLE_MAX, state) || ""}`
     return "No results found for this search.";
   }
   if (nodes.length === 0 && articles.length === 0 && chunks.length === 0) {
-    return assemble("# Retrieved context\n\nNo graph results matched this search.", sections, state);
+    return assemble(
+      "# Retrieved context\n\nNo graph results matched this search.",
+      sections,
+      state,
+      maxChars
+    );
   }
-  return assemble("# Retrieved context", sections, state);
+  return assemble("# Retrieved context", sections, state, maxChars);
+}
+function resumeEntry(raw, state, fallbackType) {
+  const wrapper = obj(raw);
+  if (!wrapper) return void 0;
+  const value = obj(wrapper.node) ?? wrapper;
+  if (isNodeShaped(value)) return nodeLines(value, state);
+  const uid = str(value.uid);
+  const props = obj(value.props);
+  const label = clip(value.label, LABEL_MAX, state) ?? clip(value.name, LABEL_MAX, state) ?? clip(value.title, LABEL_MAX, state) ?? clip(value.action, LABEL_MAX, state) ?? fallbackType;
+  const status = str(value.status) ?? str(props?.status);
+  const summary = clip(value.summary, SUMMARY_MAX, state) ?? clip(value.description, SUMMARY_MAX, state) ?? clip(value.content, SUMMARY_MAX, state) ?? clip(value.outcome_summary, SUMMARY_MAX, state) ?? clip(props?.summary, SUMMARY_MAX, state);
+  const details = [
+    status ? `status ${status}` : void 0,
+    str(value.path) ? `path ${str(value.path)}` : void 0,
+    str(value.symbol) ? `symbol ${str(value.symbol)}` : void 0
+  ].filter(Boolean);
+  const head = `- **${label}**${uid ? ` [${uid}]` : ""}${details.length > 0 ? ` (${details.join(", ")})` : ""}`;
+  return summary && summary !== label ? `${head}: ${summary}` : head;
+}
+function resumeSection(heading, values, state, fallbackType) {
+  const items = values.map((value) => resumeEntry(value, state, fallbackType)).filter((value) => Boolean(value));
+  return items.length > 0 ? { heading, items } : void 0;
+}
+function renderResumeContext(response, maxChars) {
+  const payload = obj(response);
+  if (!payload) return void 0;
+  const state = { bounded: false, omitted: 0 };
+  const status = str(payload.status);
+  if (!payload.task && status === "no_eligible_work") {
+    const scopedOut = Array.isArray(payload.scoped_out_tasks) ? payload.scoped_out_tasks.length : 0;
+    const note = scopedOut > 0 ? ` ${scopedOut} task(s) exist outside the requested scope.` : "";
+    return assemble(
+      "# Resume context",
+      [{ heading: `No eligible work was found in the requested scope.${note}`, items: [] }],
+      state,
+      maxChars
+    );
+  }
+  const sections = [];
+  const push = (section) => {
+    if (section) sections.push(section);
+  };
+  push(resumeSection("## Current task", [payload.task], state, "Task"));
+  push(
+    resumeSection(
+      "## Goal and project",
+      [payload.goal, payload.project].filter(Boolean),
+      state,
+      "Scope"
+    )
+  );
+  push(resumeSection("## Plan", [payload.plan], state, "Plan"));
+  push(
+    resumeSection(
+      "## Next steps",
+      Array.isArray(payload.next_steps) ? payload.next_steps : [],
+      state,
+      "Next step"
+    )
+  );
+  push(
+    resumeSection(
+      "## Blockers",
+      Array.isArray(payload.blockers) ? payload.blockers : [],
+      state,
+      "Blocker"
+    )
+  );
+  const knowledge = obj(payload.knowledge);
+  push(
+    resumeSection(
+      "## Relevant lessons and risks",
+      [
+        ...Array.isArray(knowledge?.lessons) ? knowledge.lessons : [],
+        ...Array.isArray(knowledge?.risks) ? knowledge.risks : []
+      ],
+      state,
+      "Knowledge"
+    )
+  );
+  push(
+    resumeSection(
+      "## Active execution",
+      [payload.active_execution].filter(Boolean),
+      state,
+      "Execution"
+    )
+  );
+  push(
+    resumeSection(
+      "## Recent executions",
+      Array.isArray(payload.recent_executions) ? payload.recent_executions : [],
+      state,
+      "Execution"
+    )
+  );
+  push(
+    resumeSection(
+      "## Code targets",
+      Array.isArray(payload.code_targets) ? payload.code_targets : [],
+      state,
+      "Code target"
+    )
+  );
+  push(resumeSection("## Lease", [payload.lease].filter(Boolean), state, "Lease"));
+  const warning = clip(payload.warning, SUMMARY_MAX, state);
+  if (warning) sections.push({ heading: "## Warning", items: [`- ${warning}`] });
+  const selectionReason = clip(payload.selection_reason, SUMMARY_MAX, state);
+  if (selectionReason) {
+    sections.push({ heading: "## Selection", items: [`- ${selectionReason}`] });
+  }
+  if (sections.length === 0) return void 0;
+  return assemble("# Resume context", sections, state, maxChars);
 }
-function renderNodeList(response, title, limit) {
+function renderNodeList(response, title, limit, maxChars) {
   let candidates = [];
   if (Array.isArray(response)) {
     candidates = response;
@@ -1896,8 +2054,9 @@ function renderNodeList(response, title, limit) {
   let nodes = candidates.map(unwrapSearchResult).filter((node) => Boolean(node));
   if (nodes.length === 0) return void 0;
   const total = nodes.length;
-  const state = { bounded: false };
+  const state = { bounded: false, omitted: 0 };
   if (limit !== void 0 && limit > 0 && nodes.length > limit) {
+    state.omitted += nodes.length - limit;
     nodes = nodes.slice(0, limit);
     state.bounded = true;
   }
@@ -1906,18 +2065,23 @@ function renderNodeList(response, title, limit) {
   return assemble(
     `# ${title} (${shown === total ? total : `${shown} of ${total}`})`,
     sections,
-    state
+    state,
+    maxChars
   );
 }
-function renderTraversal(response) {
+function renderTraversal(response, maxChars) {
+  const directSteps = Array.isArray(response) ? response : void 0;
   const payload = obj(response);
-  if (!payload) return void 0;
-  const container = obj(payload.graph) ?? payload;
+  if (!payload && !directSteps) return void 0;
+  const body = payload ?? {};
+  const container = obj(body.graph) ?? body;
   const rawNodes = Array.isArray(container.nodes) ? container.nodes : [];
   const nodes = rawNodes.filter(isNodeShaped);
-  const paths = Array.isArray(payload.paths) ? payload.paths : [];
-  if (nodes.length === 0 && paths.length === 0) return void 0;
-  const state = { bounded: false };
+  const paths = Array.isArray(body.paths) ? body.paths : [];
+  const hasSteps = directSteps !== void 0 || Object.hasOwn(body, "steps");
+  const rawSteps = directSteps ?? (Array.isArray(body.steps) ? body.steps : []);
+  if (nodes.length === 0 && paths.length === 0 && !hasSteps) return void 0;
+  const state = { bounded: false, omitted: 0 };
   const sections = [];
   const labelByUid = /* @__PURE__ */ new Map();
   for (const node of nodes) labelByUid.set(str(node.uid), str(node.label) || "?");
@@ -1941,6 +2105,42 @@ function renderTraversal(response) {
     });
     sections.push({ heading: "## Paths", items });
   }
+  if (hasSteps) {
+    const stepItems = rawSteps.map((raw) => obj(raw)).filter((step) => Boolean(step)).map((step) => {
+      const depth = num(step.depth);
+      const uid = str(step.node_uid) ?? str(step.uid) ?? str(step.edge_to_uid) ?? "?";
+      const parent = str(step.parent_uid) ?? str(step.edge_from_uid);
+      const label = str(step.label) || "(unlabeled)";
+      const relation = edgeTypeName(step.edge_type);
+      const role = str(step.traversal_role);
+      const type = str(step.node_type) ?? str(obj(step.node_type)?.Custom);
+      const cost = num(step.path_cost);
+      const confidence = num(step.path_confidence);
+      const prefix = [
+        depth !== void 0 ? `depth ${depth}` : void 0,
+        role,
+        relation ? `\u2014${relation}\u2192` : void 0
+      ].filter(Boolean).join(" ");
+      const meta = [
+        type,
+        parent ? `parent ${parent}` : void 0,
+        cost !== void 0 ? `cost ${cost}` : void 0,
+        confidence !== void 0 ? `confidence ${confidence}` : void 0
+      ].filter(Boolean).join(", ");
+      return `- ${prefix ? `${prefix}: ` : ""}**${label}** [${uid}]${meta ? ` (${meta})` : ""}`;
+    });
+    if (stepItems.length > 0) {
+      sections.push({ heading: "## Traversal steps", items: stepItems });
+    } else {
+      const start = str(body.start_uid) || "?";
+      const end = str(body.end_uid);
+      const mode2 = str(body.mode);
+      sections.push({
+        heading: mode2 === "path" && end ? `No path found from [${start}] to [${end}].` : `No traversal steps returned from [${start}].`,
+        items: []
+      });
+    }
+  }
   if (nodes.length > 0) {
     sections.push(...groupedNodeSections(nodes, state, "## Nodes\n\n"));
     const relationships = relationshipItems(
@@ -1952,7 +2152,13 @@ function renderTraversal(response) {
       sections.push({ heading: "## Relationships", items: relationships });
     }
   }
-  return assemble("# Graph traversal", sections, state);
+  const mode = str(body.mode);
+  return assemble(
+    `# Graph traversal${mode ? ` (${mode})` : ""}`,
+    sections,
+    state,
+    maxChars
+  );
 }
 function neighborLine(value) {
   const node = obj(value);
@@ -1973,7 +2179,7 @@ function renderOntologyAnswer(response) {
   if (objects.length === 0 && cognitiveEmpty && provenance.length === 0) {
     return hasQuerySignature ? "No matching domain objects." : void 0;
   }
-  const state = { bounded: false };
+  const state = { bounded: false, omitted: 0 };
   const sections = [];
   if (objects.length > 0) {
     sections.push(...groupedNodeSections(objects, state));
@@ -2039,7 +2245,7 @@ function renderObjectList(response, title) {
   if (items.length === 0) {
     return rawItems ? `# ${title} (0 results)` : void 0;
   }
-  const state = { bounded: false };
+  const state = { bounded: false, omitted: 0 };
   const sections = groupedNodeSections(items, state);
   const total = num(payload.total_count);
   const truncations = Array.isArray(payload.truncation_reasons) ? payload.truncation_reasons.filter((reason) => typeof reason === "string") : [];
@@ -2055,7 +2261,7 @@ function renderJobs(response) {
   const jobs = Array.isArray(response) ? response : obj(response)?.jobs;
   if (!Array.isArray(jobs)) return void 0;
   if (jobs.length === 0) return "No ingestion jobs.";
-  const state = { bounded: false };
+  const state = { bounded: false, omitted: 0 };
   const sorted = jobs.map((raw) => obj(raw)).filter((job) => Boolean(job)).sort((a, b) => (num(b.created_at) ?? 0) - (num(a.created_at) ?? 0));
   const shown = sorted.slice(0, JOBS_RENDER_MAX);
   if (shown.length < sorted.length) state.bounded = true;
@@ -2081,7 +2287,7 @@ function renderJobs(response) {
 function renderSignals(response) {
   const payload = obj(response);
   if (!payload) return void 0;
-  const state = { bounded: false };
+  const state = { bounded: false, omitted: 0 };
   const sections = [];
   for (const [key, value] of Object.entries(payload)) {
     if (!Array.isArray(value) || value.length === 0) continue;
@@ -2106,7 +2312,581 @@ function renderSignals(response) {
   return assemble("# Synthesis signals", sections, state);
 }
 
+// src/memory-tool.ts
+var RESULT_SCHEMA_VERSION = "mindgraph.memory.result.v1";
+var DEFAULT_OUTPUT_CHARS = 8e3;
+var MIN_OUTPUT_CHARS = 512;
+var MAX_OUTPUT_CHARS = 24e3;
+var HIDDEN_CONTEXT_NODE_TYPES = /* @__PURE__ */ new Set(["Chunk", "Document", "Article"]);
+var HIDDEN_CONTEXT_EDGE_TYPES = /* @__PURE__ */ new Set(["POSSIBLE_DUPLICATE", "PossibleDuplicate"]);
+var MEMORY_TOOL = {
+  name: "mindgraph_memory",
+  description: "Read the portable MindGraph memory surface. Use action='context' with mode='resume' or 'continuity' for authoritative task-first work state, and mode='topic' with a short keyword query for prior knowledge relevant to the user's request. Use action='status' to inspect integration capabilities and limitations. This tool never writes; durable capture and correction use the existing typed MindGraph write tools.",
+  inputSchema: {
+    type: "object",
+    properties: {
+      action: {
+        type: "string",
+        enum: ["status", "context"],
+        description: "Read integration status or bounded memory context"
+      },
+      mode: {
+        type: "string",
+        enum: ["topic", "continuity", "resume"],
+        description: "Context strategy. topic uses query-shaped retrieval; continuity/resume use authoritative task-first resume_work."
+      },
+      query: {
+        type: "string",
+        description: "Required for mode='topic': 1-3 discriminating BM25 keywords, not a full sentence"
+      },
+      project_uid: { type: "string", description: "Optional project scope" },
+      task_uid: { type: "string", description: "Optional task scope for resume context" },
+      session_uid: { type: "string", description: "Optional durable session scope" },
+      scope_uids: {
+        type: "array",
+        items: { type: "string" },
+        description: "Optional explicit graph scopes for continuity/resume"
+      },
+      node_types: {
+        type: "array",
+        items: { type: "string" },
+        description: "Optional node-type filter for topic context"
+      },
+      layer: {
+        type: "string",
+        enum: ["reality", "epistemic", "intent", "action", "memory", "agent"],
+        description: "Optional cognitive-layer filter for topic context"
+      },
+      limit: {
+        type: "integer",
+        minimum: 1,
+        maximum: 50,
+        default: 8,
+        description: "Maximum direct graph items requested before bounded expansion"
+      },
+      include_chunks: {
+        type: "boolean",
+        default: false,
+        description: "Include bounded source excerpts when topic summaries are insufficient"
+      },
+      include_documents: {
+        type: "boolean",
+        default: false,
+        description: "Include bounded knowledge articles for topic context"
+      },
+      valid_at: {
+        type: "string",
+        description: "Optional ISO timestamp for time-aware topic retrieval"
+      },
+      graph_expansion_limit: {
+        type: "integer",
+        minimum: 0,
+        maximum: 20,
+        default: 3,
+        description: "Bounded graph neighbors added after direct topic matches"
+      },
+      graph_max_depth: {
+        type: "integer",
+        minimum: 0,
+        maximum: 5,
+        default: 2,
+        description: "Maximum graph-expansion depth for topic context"
+      },
+      max_output_chars: {
+        type: "integer",
+        minimum: MIN_OUTPUT_CHARS,
+        maximum: MAX_OUTPUT_CHARS,
+        default: DEFAULT_OUTPUT_CHARS,
+        description: "Hard character budget for model-ready context; whole items are retained or omitted"
+      },
+      agent_id: { type: "string", description: "Agent identity" }
+    },
+    required: ["action"]
+  },
+  outputSchema: {
+    type: "object",
+    properties: {
+      schema_version: { type: "string", const: RESULT_SCHEMA_VERSION },
+      action: { type: "string", enum: ["status", "context"] },
+      profile: { type: "string" },
+      server: { type: "object" },
+      integration: { type: "object" },
+      capabilities: { type: "object" },
+      degradation: { type: "array", items: { type: "object" } },
+      context_id: { type: "string" },
+      mode: { type: "string", enum: ["topic", "continuity", "resume"] },
+      scope: { type: "object" },
+      rendered_context: { type: "string" },
+      rendered_hash: { type: "string" },
+      items: { type: "array", items: { type: "object" } },
+      retrieval_trace: { type: "object" },
+      budget: { type: "object" },
+      freshness: { type: "object" },
+      warnings: { type: "array", items: { type: "object" } }
+    },
+    required: ["schema_version", "action"],
+    oneOf: [
+      {
+        properties: { action: { const: "status" } },
+        required: ["profile", "server", "integration", "scope", "capabilities", "degradation"]
+      },
+      {
+        properties: { action: { const: "context" } },
+        required: [
+          "context_id",
+          "mode",
+          "scope",
+          "rendered_context",
+          "rendered_hash",
+          "items",
+          "retrieval_trace",
+          "budget",
+          "freshness",
+          "warnings"
+        ]
+      }
+    ]
+  },
+  annotations: {
+    readOnlyHint: true,
+    destructiveHint: false,
+    idempotentHint: true,
+    openWorldHint: false
+  }
+};
+function obj2(value) {
+  return value && typeof value === "object" && !Array.isArray(value) ? value : void 0;
+}
+function text(value) {
+  return typeof value === "string" && value.length > 0 ? value : void 0;
+}
+function stableJson(value) {
+  if (Array.isArray(value)) return `[${value.map(stableJson).join(",")}]`;
+  if (value && typeof value === "object") {
+    return `{${Object.entries(value).filter(([, item]) => item !== void 0).sort(([left], [right]) => left.localeCompare(right)).map(([key, item]) => `${JSON.stringify(key)}:${stableJson(item)}`).join(",")}}`;
+  }
+  return JSON.stringify(value);
+}
+function sha256(value) {
+  return (0, import_node_crypto4.createHash)("sha256").update(value).digest("hex");
+}
+function outputBudget(value) {
+  if (typeof value !== "number" || !Number.isFinite(value)) return DEFAULT_OUTPUT_CHARS;
+  return Math.min(MAX_OUTPUT_CHARS, Math.max(MIN_OUTPUT_CHARS, Math.floor(value)));
+}
+function defined(values) {
+  return Object.fromEntries(Object.entries(values).filter(([, value]) => value !== void 0));
+}
+function memoryStatus(config = {}) {
+  return {
+    schema_version: RESULT_SCHEMA_VERSION,
+    action: "status",
+    profile: "M0",
+    server: defined({
+      name: "mindgraph-mcp",
+      version: config.serverVersion ?? "unknown",
+      base_url: config.baseUrl
+    }),
+    integration: {
+      adapter_state: "model_controlled",
+      harness: config.harness ?? "generic",
+      configured_tool_profile: config.profile ?? "general",
+      automatic_capture: false,
+      automatic_delivery: false,
+      delivery_verification: "unsupported",
+      curator_mode: "disabled"
+    },
+    scope: defined({ org_id: config.orgId, agent_id: config.agentId }),
+    capabilities: {
+      status: true,
+      topic_context: true,
+      authoritative_resume_context: true,
+      bounded_rendering: true,
+      structured_content: true,
+      typed_explicit_writes: true,
+      lifecycle_event_ingest: false,
+      automatic_context_injection: false,
+      curator_mutation: false
+    },
+    degradation: [
+      {
+        code: "automatic_capture_unavailable",
+        message: "M0 does not observe host lifecycle events; explicit typed write tools remain available."
+      },
+      {
+        code: "delivery_unverified",
+        message: "A successful MCP read does not prove that the host injected or used the returned context."
+      },
+      {
+        code: "curator_disabled",
+        message: "Curator proposals and autonomous mutation are not enabled in M0."
+      }
+    ]
+  };
+}
+function nodeType(node) {
+  const raw = node.node_type;
+  if (typeof raw === "string") return raw;
+  return text(obj2(raw)?.Custom) ?? "Node";
+}
+function compactItem(raw, fallbackType) {
+  const wrapper = obj2(raw);
+  if (!wrapper) return void 0;
+  const value = obj2(wrapper.node) ?? obj2(wrapper.object) ?? wrapper;
+  const uid = text(value.uid) ?? text(value.chunk_uid);
+  if (!uid) return void 0;
+  return defined({
+    uid,
+    type: fallbackType ?? nodeType(value),
+    label: text(value.label) ?? text(value.document_title),
+    truth_status: text(value.truth_status) ?? text(obj2(value.props)?.truth_status),
+    superseded: value.superseded === true ? true : void 0,
+    currently_valid: value.currently_valid === false ? false : void 0,
+    valid_at_time: value.valid_at_time === false ? false : void 0,
+    retrieval_origin: text(value.retrieval_origin),
+    retrieval_depth: typeof value.retrieval_depth === "number" ? value.retrieval_depth : void 0
+  });
+}
+function topicCandidates(raw) {
+  const payload = obj2(raw);
+  if (!payload) return [];
+  const graph = obj2(payload.graph);
+  const items = [];
+  for (const article of Array.isArray(payload.articles) ? payload.articles : []) {
+    const item = compactItem(article, "Article");
+    if (item) items.push(item);
+  }
+  const rawNodes = Array.isArray(graph?.nodes) ? graph.nodes : [];
+  const labels = /* @__PURE__ */ new Map();
+  for (const node of rawNodes) {
+    const item = compactItem(node);
+    if (item) {
+      if (HIDDEN_CONTEXT_NODE_TYPES.has(text(item.type) ?? "")) continue;
+      items.push(item);
+      const uid = text(item.uid);
+      const label = text(item.label);
+      if (uid && label) labels.set(uid, label);
+    }
+  }
+  for (const rawEdge of Array.isArray(graph?.edges) ? graph.edges : []) {
+    const edge = obj2(rawEdge);
+    const fromUid = text(edge?.from_uid);
+    const toUid = text(edge?.to_uid);
+    const edgeType = text(edge?.edge_type) ?? text(obj2(edge?.edge_type)?.Custom);
+    if (!fromUid || !toUid || !edgeType || HIDDEN_CONTEXT_EDGE_TYPES.has(edgeType) || !labels.has(fromUid) || !labels.has(toUid)) {
+      continue;
+    }
+    items.push(
+      defined({
+        type: "Relationship",
+        from_uid: fromUid,
+        to_uid: toUid,
+        edge_type: edgeType,
+        from_label: labels.get(fromUid),
+        to_label: labels.get(toUid)
+      })
+    );
+  }
+  for (const chunk of Array.isArray(payload.chunks) ? payload.chunks : []) {
+    const item = compactItem(chunk, "SourceExcerpt");
+    if (item) items.push(item);
+  }
+  return items;
+}
+function resumeCandidates(raw) {
+  const payload = obj2(raw);
+  if (!payload) return [];
+  const items = [];
+  for (const key of ["task", "goal", "project", "plan", "active_execution", "lease"]) {
+    const item = compactItem(payload[key], key);
+    if (item) items.push(item);
+  }
+  for (const key of ["next_steps", "recent_executions", "blockers", "code_targets"]) {
+    for (const value of Array.isArray(payload[key]) ? payload[key] : []) {
+      const item = compactItem(value, key.replace(/s$/, ""));
+      if (item) items.push(item);
+    }
+  }
+  const knowledge = obj2(payload.knowledge);
+  for (const key of ["lessons", "risks"]) {
+    for (const value of Array.isArray(knowledge?.[key]) ? knowledge[key] : []) {
+      const item = compactItem(value, key.replace(/s$/, ""));
+      if (item) items.push(item);
+    }
+  }
+  return items;
+}
+function visibleItems(candidates, rendered2) {
+  const seen = /* @__PURE__ */ new Set();
+  return candidates.filter((item) => {
+    const uid = text(item.uid);
+    if (uid) {
+      if (seen.has(uid) || !rendered2.includes(`[${uid}]`)) return false;
+      seen.add(uid);
+      return true;
+    }
+    if (item.type === "Relationship") {
+      const from = text(item.from_label);
+      const to = text(item.to_label);
+      const edgeType = text(item.edge_type);
+      if (!from || !to || !edgeType) return false;
+      const key = `${text(item.from_uid)}:${edgeType}:${text(item.to_uid)}`;
+      if (seen.has(key) || !rendered2.includes(`${from} \u2014${edgeType}\u2192 ${to}`)) return false;
+      seen.add(key);
+      return true;
+    }
+    return false;
+  });
+}
+function latestTimestamp(value) {
+  let latest;
+  const visit = (current) => {
+    if (Array.isArray(current)) {
+      for (const item of current) visit(item);
+      return;
+    }
+    const record = obj2(current);
+    if (!record) return;
+    for (const [key, item] of Object.entries(record)) {
+      if (["updated_at", "created_at", "completed_at", "started_at", "observed_at"].includes(key) && typeof item === "string" && !Number.isNaN(Date.parse(item)) && (!latest || Date.parse(item) > Date.parse(latest))) {
+        latest = item;
+      }
+      visit(item);
+    }
+  };
+  visit(value);
+  return latest;
+}
+function contextWarnings(raw, rendered2, available, returned) {
+  const warnings = [
+    {
+      code: "delivery_unverified",
+      message: "The MCP server returned this context but cannot verify that the host injected or used it."
+    }
+  ];
+  const serialized = JSON.stringify(raw);
+  if (available > returned || rendered2.includes("item(s) omitted")) {
+    warnings.push({
+      code: "context_bounded",
+      message: `${Math.max(0, available - returned)} structured item(s) were omitted from the rendered context.`
+    });
+  }
+  if (/"superseded":true/.test(serialized)) {
+    warnings.push({ code: "superseded_items_present", message: "Some retrieved items are superseded." });
+  }
+  if (/"currently_valid":false|"valid_at_time":false/.test(serialized)) {
+    warnings.push({
+      code: "validity_warning",
+      message: "Some retrieved items are outside their current or requested validity window."
+    });
+  }
+  const payload = obj2(raw);
+  if (payload?.truncated === true || obj2(payload?.truncation)) {
+    const truncation = obj2(payload?.truncation);
+    if (payload?.truncated === true || Object.values(truncation ?? {}).some(Boolean)) {
+      warnings.push({ code: "source_truncated", message: "The authoritative source reported truncated fields." });
+    }
+  }
+  if (text(payload?.warning)) {
+    warnings.push({ code: "source_warning", message: text(payload?.warning) });
+  }
+  return warnings;
+}
+function error(message) {
+  return {
+    content: [{ type: "text", text: JSON.stringify({ error: message }) }],
+    isError: true
+  };
+}
+async function handleMemoryTool(client2, args, config = {}) {
+  const action = text(args.action);
+  if (action === "status") {
+    const status = memoryStatus({ ...config, agentId: text(args.agent_id) ?? config.agentId });
+    return {
+      content: [{ type: "text", text: JSON.stringify(status) }],
+      structuredContent: status
+    };
+  }
+  if (action !== "context") {
+    return error("action must be 'status' or 'context'");
+  }
+  const mode = text(args.mode) ?? (text(args.query) ? "topic" : void 0);
+  if (!mode || !["topic", "continuity", "resume"].includes(mode)) {
+    return error("action='context' requires mode='topic', 'continuity', or 'resume'");
+  }
+  const budget = outputBudget(args.max_output_chars);
+  const agentId = text(args.agent_id) ?? config.agentId;
+  let raw;
+  let rendered2;
+  let strategy;
+  let candidates;
+  if (mode === "topic") {
+    const query = text(args.query);
+    if (!query) return error("mode='topic' requires a non-empty query of 1-3 discriminating keywords");
+    const limit = typeof args.limit === "number" && Number.isFinite(args.limit) ? Math.min(50, Math.max(1, Math.floor(args.limit))) : 8;
+    const request = defined({
+      query,
+      project_uid: text(args.project_uid),
+      node_limit: limit,
+      node_types: Array.isArray(args.node_types) ? args.node_types.map(String) : void 0,
+      layer: text(args.layer),
+      chunk_limit: args.include_chunks === true ? limit : 0,
+      article_limit: args.include_documents === true ? limit : 0,
+      valid_at: text(args.valid_at),
+      include_graph: true,
+      graph_expansion_limit: typeof args.graph_expansion_limit === "number" ? args.graph_expansion_limit : 3,
+      graph_max_depth: typeof args.graph_max_depth === "number" ? args.graph_max_depth : 2
+    });
+    raw = await client2.retrieveContext(request);
+    rendered2 = renderContext(raw, budget) ?? "No results found for this search.";
+    strategy = "retrieve_context";
+    candidates = topicCandidates(raw);
+  } else {
+    const scopeUids = Array.from(
+      /* @__PURE__ */ new Set([
+        ...Array.isArray(args.scope_uids) ? args.scope_uids.map(String) : [],
+        ...text(args.project_uid) ? [text(args.project_uid)] : []
+      ])
+    );
+    raw = await client2.plan(
+      defined({
+        action: "resume_work",
+        task_uid: text(args.task_uid),
+        session_uid: text(args.session_uid),
+        scope_uids: scopeUids.length > 0 ? scopeUids : void 0,
+        limit: 1,
+        agent_id: agentId
+      })
+    );
+    rendered2 = renderResumeContext(raw, budget) ?? "No eligible work was found in the requested scope.";
+    strategy = "resume_work";
+    candidates = resumeCandidates(raw);
+  }
+  const items = visibleItems(candidates, rendered2);
+  const renderedHash = sha256(rendered2);
+  const scope = defined({
+    org_id: config.orgId,
+    agent_id: agentId,
+    harness: config.harness ?? "generic",
+    project_uid: text(args.project_uid),
+    task_uid: text(args.task_uid),
+    session_uid: text(args.session_uid),
+    scope_uids: Array.isArray(args.scope_uids) ? args.scope_uids.map(String) : void 0
+  });
+  const contextId = `ctx_${sha256(
+    stableJson({ mode, scope, strategy, query: text(args.query), rendered_hash: renderedHash })
+  ).slice(0, 24)}`;
+  const bounded = candidates.length > items.length || rendered2.includes("item(s) omitted");
+  const result = {
+    schema_version: RESULT_SCHEMA_VERSION,
+    action: "context",
+    context_id: contextId,
+    mode,
+    scope,
+    rendered_context: rendered2,
+    rendered_hash: renderedHash,
+    items,
+    retrieval_trace: defined({
+      strategy,
+      query: text(args.query),
+      project_uid: text(args.project_uid),
+      task_uid: text(args.task_uid),
+      session_uid: text(args.session_uid),
+      node_types: Array.isArray(args.node_types) ? args.node_types.map(String) : void 0,
+      graph_expansion_limit: mode === "topic" ? args.graph_expansion_limit ?? 3 : void 0,
+      graph_max_depth: mode === "topic" ? args.graph_max_depth ?? 2 : void 0,
+      available_items: candidates.length,
+      returned_items: items.length,
+      omitted_items: Math.max(0, candidates.length - items.length)
+    }),
+    budget: {
+      unit: "characters",
+      requested_chars: budget,
+      used_chars: rendered2.length,
+      available_items: candidates.length,
+      returned_items: items.length,
+      omitted_items: Math.max(0, candidates.length - items.length),
+      bounded
+    },
+    freshness: defined({
+      valid_at: text(args.valid_at),
+      latest_source_timestamp: latestTimestamp(raw)
+    }),
+    warnings: contextWarnings(raw, rendered2, candidates.length, items.length)
+  };
+  return {
+    content: [{ type: "text", text: rendered2 }],
+    structuredContent: result
+  };
+}
+
 // src/tools.ts
+var RESOLUTION_PROPERTIES = {
+  idempotency_key: {
+    type: "string",
+    description: "Stable retry key; a mismatched replay is rejected"
+  },
+  reuse_uid: {
+    type: "string",
+    description: "Reuse this live same-scope node after a duplicate response"
+  },
+  supersedes_uid: {
+    type: "string",
+    description: "Create and mark this same-scope node as superseded"
+  },
+  contradicts_uid: {
+    type: "string",
+    description: "Create and mark this same-scope node as contradicted"
+  },
+  confirm_new: {
+    type: "boolean",
+    description: "Confirm that the new fact is genuinely distinct"
+  },
+  on_near_duplicate: {
+    type: "string",
+    enum: ["create"],
+    description: "Alias for confirm_new on a near-duplicate response"
+  }
+};
+function stableJson2(value) {
+  if (Array.isArray(value)) return `[${value.map(stableJson2).join(",")}]`;
+  if (value && typeof value === "object") {
+    return `{${Object.entries(value).sort(([left], [right]) => left.localeCompare(right)).map(([key, item]) => `${JSON.stringify(key)}:${stableJson2(item)}`).join(",")}}`;
+  }
+  return JSON.stringify(value);
+}
+function defaultWriteIdempotencyKey(tool, args) {
+  if (typeof args.idempotency_key === "string") return args.idempotency_key;
+  const context = args.invocation_context;
+  const sessionId = context?.harnessSessionId;
+  if (typeof sessionId !== "string" || sessionId.length === 0) return void 0;
+  const canonicalArgs = Object.fromEntries(
+    Object.entries(args).filter(
+      ([key]) => key !== "invocation_context" && key !== "idempotency_key"
+    )
+  );
+  return (0, import_node_crypto5.createHash)("sha256").update(
+    stableJson2({
+      harness_session_id: sessionId,
+      harness_turn_id: context?.harnessTurnId ?? null,
+      tool,
+      action: args.action ?? null,
+      args: canonicalArgs
+    })
+  ).digest("hex");
+}
+function resolutionFields(args) {
+  return Object.fromEntries(
+    [
+      "idempotency_key",
+      "reuse_uid",
+      "supersedes_uid",
+      "contradicts_uid",
+      "confirm_new",
+      "on_near_duplicate"
+    ].filter((key) => args[key] !== void 0).map((key) => [key, args[key]])
+  );
+}
 var TOOLS = [
   {
     name: "mindgraph_capture",
@@ -2171,14 +2951,7 @@ var TOOLS = [
           type: "string",
           description: "Material Execution that produced the lesson"
         },
-        idempotency_key: {
-          type: "string",
-          description: "Stable retry key for an intentional capture"
-        },
-        supersedes_uid: {
-          type: "string",
-          description: "Earlier capture corrected or superseded by this one"
-        },
+        ...RESOLUTION_PROPERTIES,
         summarizes_uids: {
           type: "array",
           items: { type: "string" },
@@ -2276,6 +3049,7 @@ var TOOLS = [
     inputSchema: {
       type: "object",
       properties: {
+        ...RESOLUTION_PROPERTIES,
         action: {
           type: "string",
           enum: [
@@ -2370,6 +3144,7 @@ var TOOLS = [
     inputSchema: {
       type: "object",
       properties: {
+        ...RESOLUTION_PROPERTIES,
         action: {
           type: "string",
           enum: [
@@ -2728,6 +3503,12 @@ var TOOLS = [
           enum: ["text", "json"],
           description: "Output format (default 'text'): a compact rendered context block \u2014 labels, uids, summaries, status tags, relationships. Pass 'json' for the raw server response (full props, source-chunk offsets, retrieval metadata)."
         },
+        max_output_chars: {
+          type: "integer",
+          minimum: 512,
+          maximum: 24e3,
+          description: "Hard character budget for rendered text output (512-24000; default 24000). Normal per-field clipping still applies. Whole evidence items are then kept or omitted rather than cut to satisfy this budget; the final marker reports omissions. Ignored when format='json'."
+        },
         query: {
           type: "string",
           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."
@@ -3154,6 +3935,67 @@ var TOOLS = [
       required: ["action"]
     }
   },
+  {
+    name: "mindgraph_remember",
+    description: "Small-text memory fast path. 'remember' stores one fact, preference, decision or note synchronously; it is BM25- and vector-searchable the moment the call returns (the response says which). Pass a stable custom_id (e.g. 'pref:theme', 'deploy:target') so re-sending the same key UPDATES the same memory instead of creating a duplicate \u2014 that is the idempotency contract; without custom_id an exact duplicate is reused. 'forget' reversibly removes a memory by uid or custom_id (tombstone plus connected edges): call it with dry_run=true first to see the edge uids it would remove, then without. Undo with mindgraph_capture-independent server actions /evolve restore and restore_edge. Use mindgraph_capture for typed entities, sources and skills, and mindgraph_ingest for documents longer than a few paragraphs.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        action: {
+          type: "string",
+          enum: ["remember", "forget"],
+          description: "remember = store/upsert one small text; forget = reversible removal"
+        },
+        text: {
+          type: "string",
+          description: "remember: the memory text (\u2264 8 KiB). Use mindgraph_ingest for longer content."
+        },
+        custom_id: {
+          type: "string",
+          description: "Caller-owned key. remember: re-sending it edits the same memory (version bump, history kept). forget: the memory to remove."
+        },
+        label: {
+          type: "string",
+          description: "remember: optional short title; defaults to the first line of text"
+        },
+        uid: {
+          type: "string",
+          description: "forget: node uid to remove (alternative to custom_id)"
+        },
+        dry_run: {
+          type: "boolean",
+          description: "forget: preview the affected edge uids without changing anything"
+        },
+        cascade: {
+          type: "boolean",
+          description: "forget: also tombstone connected edges (default true)"
+        },
+        reason: {
+          type: "string",
+          description: "forget: why (recorded on the tombstone)"
+        },
+        space_uid: {
+          type: "string",
+          description: "remember: explicit target Space (default: the org space)"
+        },
+        on_near_duplicate: {
+          type: "string",
+          enum: ["reuse", "create"],
+          description: "remember without custom_id: on an exact duplicate, reuse the existing memory (default) or create anyway"
+        },
+        props: {
+          type: "object",
+          description: "remember: extra Observation props"
+        },
+        agent_id: {
+          type: "string",
+          description: "Agent identifier (default: configured agent)"
+        }
+      },
+      required: ["action"]
+    }
+  },
+  MEMORY_TOOL,
   SYNC_TOOL,
   CODE_TOOL
 ];
@@ -3174,7 +4016,7 @@ var INVOCATION_CONTEXT_SCHEMA = {
   }
 };
 for (const tool of TOOLS) {
-  if (tool.name === "mindgraph_retrieve") continue;
+  if (tool.name === "mindgraph_retrieve" || tool.name === "mindgraph_memory") continue;
   const schema = tool.inputSchema;
   if (schema.properties && !schema.properties.invocation_context) {
     schema.properties.invocation_context = INVOCATION_CONTEXT_SCHEMA;
@@ -3193,8 +4035,8 @@ function ok3(data) {
 }
 function renderedResult(format, raw, render) {
   if (format === "json") return ok3(raw);
-  const text = render(raw);
-  return text !== void 0 ? { content: [{ type: "text", text }] } : ok3(raw);
+  const text2 = render(raw);
+  return text2 !== void 0 ? { content: [{ type: "text", text: text2 }] } : ok3(raw);
 }
 function err3(message) {
   return {
@@ -3202,8 +4044,22 @@ function err3(message) {
     isError: true
   };
 }
-async function handleTool(client2, name, args) {
+async function handleTool(client2, name, args, memoryConfig = {}) {
   try {
+    if (["mindgraph_capture", "mindgraph_reason", "mindgraph_commit"].includes(name) && args.action !== "get_open_decisions") {
+      const key = defaultWriteIdempotencyKey(name, args);
+      if (key) args = { ...args, idempotency_key: key };
+      const dispositions = [
+        args.reuse_uid,
+        args.supersedes_uid,
+        args.contradicts_uid,
+        args.confirm_new === true ? true : void 0,
+        args.on_near_duplicate
+      ].filter((value) => value !== void 0);
+      if (dispositions.length > 1) {
+        return err3("resolution dispositions are mutually exclusive");
+      }
+    }
     let result;
     switch (name) {
       case "mindgraph_capture":
@@ -3221,6 +4077,12 @@ async function handleTool(client2, name, args) {
       case "mindgraph_retrieve":
         result = await handleRetrieve(client2, args);
         break;
+      case "mindgraph_memory":
+        result = await handleMemoryTool(client2, args, memoryConfig);
+        break;
+      case "mindgraph_remember":
+        result = await handleRemember(client2, args);
+        break;
       case "mindgraph_series_query":
         result = await handleSeriesQuery(client2, args);
         break;
@@ -3253,19 +4115,7 @@ async function handleTool(client2, name, args) {
     ].includes(action);
     return attach ? await attachCodeRefsToToolResult(client2, result, args) : result;
   } catch (e) {
-    const lifted = conflictState(e);
-    if (Object.keys(lifted).length > 0) {
-      return {
-        content: [
-          {
-            type: "text",
-            text: JSON.stringify({ error: errorDetail(e), ...lifted })
-          }
-        ],
-        isError: true
-      };
-    }
-    return err3(errorDetail(e));
+    return toolError(e);
   }
 }
 async function handleSeriesQuery(client2, args) {
@@ -3289,6 +4139,56 @@ async function handleSeriesQuery(client2, args) {
     await client2.series(args)
   );
 }
+async function handleRemember(client2, args) {
+  const {
+    action,
+    text: text2,
+    custom_id,
+    label,
+    uid,
+    dry_run,
+    cascade,
+    reason,
+    space_uid,
+    on_near_duplicate,
+    props,
+    agent_id,
+    // Adapter-owned; consumed locally, never sent to the API.
+    invocation_context: _invocationContext,
+    ...rest
+  } = args;
+  void _invocationContext;
+  void rest;
+  switch (action) {
+    case "remember": {
+      if (typeof text2 !== "string" || !text2.trim()) {
+        return err3("remember requires non-empty text");
+      }
+      const options = {};
+      if (typeof custom_id === "string" && custom_id.trim()) options.custom_id = custom_id.trim();
+      if (typeof label === "string" && label.trim()) options.label = label;
+      if (typeof space_uid === "string" && space_uid.trim()) options.space_uid = space_uid;
+      if (on_near_duplicate === "reuse" || on_near_duplicate === "create") {
+        options.on_near_duplicate = on_near_duplicate;
+      }
+      if (props && typeof props === "object") options.props = props;
+      if (typeof agent_id === "string") options.agent_id = agent_id;
+      return ok3(await client2.remember(text2, options));
+    }
+    case "forget": {
+      const target = typeof uid === "string" && uid.trim() ? { uid: uid.trim() } : typeof custom_id === "string" && custom_id.trim() ? { custom_id: custom_id.trim() } : null;
+      if (!target) return err3("forget requires uid or custom_id");
+      const options = {};
+      if (dry_run === true) options.dry_run = true;
+      if (typeof cascade === "boolean") options.cascade = cascade;
+      if (typeof reason === "string" && reason.trim()) options.reason = reason;
+      if (typeof agent_id === "string") options.agent_id = agent_id;
+      return ok3(await client2.forget(target, options));
+    }
+    default:
+      return err3(`Unknown remember action: ${String(action)}`);
+  }
+}
 async function handleCapture(client2, args) {
   const {
     action,
@@ -3302,7 +4202,11 @@ async function handleCapture(client2, args) {
     work_uid,
     execution_uid,
     idempotency_key,
+    reuse_uid,
     supersedes_uid,
+    contradicts_uid,
+    confirm_new,
+    on_near_duplicate,
     summarizes_uids,
     entity_type,
     source_uid,
@@ -3326,7 +4230,11 @@ async function handleCapture(client2, args) {
           work_uid,
           execution_uid,
           idempotency_key,
+          reuse_uid,
           supersedes_uid,
+          contradicts_uid,
+          confirm_new,
+          on_near_duplicate,
           summarizes_uids,
           props,
           agent_id
@@ -3372,27 +4280,32 @@ async function handleCapture(client2, args) {
       const journalProps = { content };
       if (mood) journalProps.mood = mood;
       if (tags) journalProps.tags = tags;
-      return ok3(await client2.journal(label, journalProps, { agent_id }));
+      return ok3(await client2.journal(label, journalProps, {
+        agent_id,
+        idempotency_key,
+        reuse_uid,
+        supersedes_uid,
+        contradicts_uid,
+        confirm_new,
+        on_near_duplicate
+      }));
     }
     case "entity": {
       const type = entity_type || "concept";
       const entityProps = { ...props };
       if (summary) entityProps.description = summary;
-      switch (type) {
-        case "person":
-          return ok3(await client2.findOrCreatePerson(label, entityProps, agent_id));
-        case "organization":
-          return ok3(await client2.findOrCreateOrganization(label, entityProps, agent_id));
-        case "nation":
-          return ok3(await client2.findOrCreateNation(label, entityProps, agent_id));
-        case "event":
-          return ok3(await client2.findOrCreateEvent(label, entityProps, agent_id));
-        case "place":
-          return ok3(await client2.findOrCreatePlace(label, entityProps, agent_id));
-        case "concept":
-        default:
-          return ok3(await client2.findOrCreateConcept(label, entityProps, agent_id));
-      }
+      return ok3(await client2.entity({
+        action: "create",
+        label,
+        props: { ...entityProps, entity_type: type },
+        agent_id,
+        idempotency_key,
+        reuse_uid,
+        supersedes_uid,
+        contradicts_uid,
+        confirm_new,
+        on_near_duplicate
+      }));
     }
     case "observation":
       return ok3(
@@ -3403,7 +4316,13 @@ async function handleCapture(client2, args) {
           confidence,
           salience,
           props,
-          agent_id
+          agent_id,
+          idempotency_key,
+          reuse_uid,
+          supersedes_uid,
+          contradicts_uid,
+          confirm_new,
+          on_near_duplicate
         })
       );
     case "source":
@@ -3415,7 +4334,13 @@ async function handleCapture(client2, args) {
           confidence,
           salience,
           props,
-          agent_id
+          agent_id,
+          idempotency_key,
+          reuse_uid,
+          supersedes_uid,
+          contradicts_uid,
+          confirm_new,
+          on_near_duplicate
         })
       );
     case "snippet":
@@ -3428,26 +4353,38 @@ async function handleCapture(client2, args) {
           confidence,
           salience,
           props,
-          agent_id
+          agent_id,
+          idempotency_key,
+          reuse_uid,
+          supersedes_uid,
+          contradicts_uid,
+          confirm_new,
+          on_near_duplicate
         })
       );
     case "concept":
-      return ok3(
-        await client2.structure({
-          action: "concept",
-          label,
-          summary,
-          confidence,
-          salience,
-          props,
-          agent_id
-        })
-      );
+      return ok3(await client2.entity({
+        action: "create",
+        label,
+        props: {
+          ...props,
+          entity_type: "concept",
+          ...summary ? { description: summary } : {}
+        },
+        agent_id,
+        idempotency_key,
+        reuse_uid,
+        supersedes_uid,
+        contradicts_uid,
+        confirm_new,
+        on_near_duplicate
+      }));
     default:
       return err3(`Unknown capture action: ${action}`);
   }
 }
 async function handleReason(client2, args) {
+  const resolution = resolutionFields(args);
   const {
     action,
     label,
@@ -3480,7 +4417,8 @@ async function handleReason(client2, args) {
           ...warrant.content ? { props: { content: warrant.content } } : {}
         } : void 0,
         argument,
-        agent_id
+        agent_id,
+        ...resolution
       })
     );
   }
@@ -3493,11 +4431,13 @@ async function handleReason(client2, args) {
       confidence,
       salience,
       props,
-      agent_id
+      agent_id,
+      ...resolution
     })
   );
 }
 async function handleCommit(client2, args) {
+  const resolution = resolutionFields(args);
   const {
     action,
     label,
@@ -3528,16 +4468,17 @@ async function handleCommit(client2, args) {
           confidence,
           salience,
           props,
-          agent_id
+          agent_id,
+          ...resolution
         })
       );
     case "open_decision":
       if (!label) return err3("label is required for open_decision");
-      return ok3(await client2.openDecision(label, { summary, props, agent_id }));
+      return ok3(await client2.openDecision(label, { summary, props, agent_id, ...resolution }));
     case "add_option":
       if (!decision_uid) return err3("decision_uid is required for add_option");
       if (!label) return err3("label is required for add_option");
-      return ok3(await client2.addOption(decision_uid, label, { summary, props, agent_id }));
+      return ok3(await client2.addOption(decision_uid, label, { summary, props, agent_id, ...resolution }));
     case "add_constraint":
       if (!decision_uid) return err3("decision_uid is required for add_constraint");
       return ok3(
@@ -3547,7 +4488,8 @@ async function handleCommit(client2, args) {
           decision_uid,
           summary,
           props,
-          agent_id
+          agent_id,
+          ...resolution
         })
       );
     case "resolve_decision":
@@ -3561,7 +4503,8 @@ async function handleCommit(client2, args) {
           as_of_date,
           session_id,
           retrieval_trace_id,
-          agent_id
+          agent_id,
+          ...resolution
         })
       );
     case "get_open_decisions":
@@ -3642,7 +4585,7 @@ async function handlePlan(client2, args) {
     output_snapshot,
     side_effects,
     outcome,
-    error,
+    error: error2,
     next_action,
     checkpoint_summary,
     test_summary,
@@ -3705,7 +4648,7 @@ async function handlePlan(client2, args) {
           output_snapshot,
           side_effects,
           outcome,
-          error,
+          error: error2,
           next_action,
           checkpoint_summary,
           test_summary,
@@ -3754,7 +4697,7 @@ async function handlePlan(client2, args) {
           output_snapshot,
           side_effects,
           outcome,
-          error,
+          error: error2,
           props,
           agent_id
         })
@@ -3840,6 +4783,7 @@ async function handleRetrieve(client2, args) {
   const {
     action,
     format,
+    max_output_chars,
     query,
     start_uid,
     end_uid,
@@ -3894,7 +4838,7 @@ async function handleRetrieve(client2, args) {
           graph_expansion_limit: graph_expansion_limit ?? 3,
           graph_max_depth: graph_max_depth ?? 2
         }),
-        renderContext
+        (raw) => renderContext(raw, max_output_chars)
       );
     case "text":
       if (!query) return err3("query is required for text search");
@@ -3908,7 +4852,7 @@ async function handleRetrieve(client2, args) {
           explain,
           agent_id
         }),
-        (raw) => renderNodeList(raw, `Text search: ${query}`)
+        (raw) => renderNodeList(raw, `Text search: ${query}`, void 0, max_output_chars)
       );
     case "semantic":
       if (!query) return err3("query is required for semantic search");
@@ -3922,7 +4866,7 @@ async function handleRetrieve(client2, args) {
           explain,
           agent_id
         }),
-        (raw) => renderNodeList(raw, `Semantic search: ${query}`)
+        (raw) => renderNodeList(raw, `Semantic search: ${query}`, void 0, max_output_chars)
       );
     case "hybrid":
       if (!query) return err3("query is required for hybrid search");
@@ -3937,7 +4881,7 @@ async function handleRetrieve(client2, args) {
           agent_id
         }),
         // With explain, per-leg scoring must survive — raw JSON only.
-        explain ? () => void 0 : (raw) => renderNodeList(raw, `Hybrid search: ${query}`)
+        explain ? () => void 0 : (raw) => renderNodeList(raw, `Hybrid search: ${query}`, void 0, max_output_chars)
       );
     // Structured queries. These go through the generic /retrieve action
     // dispatch rather than the SDK's no-argument convenience methods — the
@@ -3955,7 +4899,7 @@ async function handleRetrieve(client2, args) {
           offset,
           agent_id
         }),
-        (raw) => renderNodeList(raw, action.replace(/_/g, " "), limit)
+        (raw) => renderNodeList(raw, action.replace(/_/g, " "), limit, max_output_chars)
       );
     case "stale_derivations":
       return rendered2(
@@ -3964,7 +4908,7 @@ async function handleRetrieve(client2, args) {
           limit,
           offset
         }),
-        (raw) => renderNodeList(raw, "stale derivations", limit)
+        (raw) => renderNodeList(raw, "stale derivations", limit, max_output_chars)
       );
     case "preferences":
       return rendered2(
@@ -3974,7 +4918,7 @@ async function handleRetrieve(client2, args) {
           limit,
           agent_id
         }),
-        (raw) => renderNodeList(raw, "Preferences", limit)
+        (raw) => renderNodeList(raw, "Preferences", limit, max_output_chars)
       );
     case "layer":
       if (!layer) return err3("layer is required for layer retrieval");
@@ -3986,7 +4930,7 @@ async function handleRetrieve(client2, args) {
           node_types,
           agent_id
         }),
-        (raw) => renderNodeList(raw, `Layer: ${layer}`, limit)
+        (raw) => renderNodeList(raw, `Layer: ${layer}`, limit, max_output_chars)
       );
     case "recent":
       return rendered2(
@@ -4000,7 +4944,7 @@ async function handleRetrieve(client2, args) {
           created_before,
           agent_id
         }),
-        (raw) => renderNodeList(raw, "Recently ingested", limit)
+        (raw) => renderNodeList(raw, "Recently ingested", limit, max_output_chars)
       );
     // Document inventory
     case "document_index":
@@ -4009,7 +4953,7 @@ async function handleRetrieve(client2, args) {
           node_type: "Document",
           limit: limit ?? 100
         }),
-        (raw) => renderNodeList(raw, "Ingested documents")
+        (raw) => renderNodeList(raw, "Ingested documents", void 0, max_output_chars)
       );
     // Graph traversal
     case "chain":
@@ -4023,7 +4967,7 @@ async function handleRetrieve(client2, args) {
           include_provenance,
           max_nodes
         }),
-        renderTraversal
+        (raw) => renderTraversal(raw, max_output_chars)
       );
     case "neighborhood":
       if (!start_uid) return err3("start_uid is required for neighborhood traversal");
@@ -4038,7 +4982,7 @@ async function handleRetrieve(client2, args) {
           include_provenance,
           max_nodes
         }),
-        renderTraversal
+        (raw) => renderTraversal(raw, max_output_chars)
       );
     case "path":
       if (!start_uid) return err3("start_uid is required for path traversal");
@@ -4055,7 +4999,7 @@ async function handleRetrieve(client2, args) {
           include_provenance,
           max_nodes
         }),
-        renderTraversal
+        (raw) => renderTraversal(raw, max_output_chars)
       );
     case "subgraph":
       if (!start_uid) return err3("start_uid is required for subgraph traversal");
@@ -4070,7 +5014,7 @@ async function handleRetrieve(client2, args) {
           include_provenance,
           max_nodes
         }),
-        renderTraversal
+        (raw) => renderTraversal(raw, max_output_chars)
       );
     case "top_k_paths":
       if (!start_uid) return err3("start_uid is required for top_k_paths");
@@ -4086,7 +5030,7 @@ async function handleRetrieve(client2, args) {
           edge_types,
           exclude_edge_types
         }),
-        renderTraversal
+        (raw) => renderTraversal(raw, max_output_chars)
       );
     default:
       return err3(`Unknown retrieve action: ${action}`);
@@ -4350,8 +5294,8 @@ var ok4 = (data) => ({
 });
 var rendered = (format, raw, render) => {
   if (format === "json") return ok4(raw);
-  const text = render(raw);
-  return text !== void 0 ? { content: [{ type: "text", text }] } : ok4(raw);
+  const text2 = render(raw);
+  return text2 !== void 0 ? { content: [{ type: "text", text: text2 }] } : ok4(raw);
 };
 var err4 = (message) => ({
   content: [{ type: "text", text: JSON.stringify({ error: message }) }],
@@ -4411,8 +5355,8 @@ async function getGeneratedTools(client2) {
     cache = { tools, byName, fetchedAt: Date.now() };
     retryNotBefore = 0;
     return { tools, byName };
-  } catch (error) {
-    if (error instanceof DuplicateGeneratedToolError) throw error;
+  } catch (error2) {
+    if (error2 instanceof DuplicateGeneratedToolError) throw error2;
     retryNotBefore = Date.now() + FAILURE_COOLDOWN_MS;
     return cache ? { tools: cache.tools, byName: cache.byName } : EMPTY;
   }
@@ -4519,7 +5463,7 @@ async function handleGeneratedTool(client2, desc, args) {
         return err4(`unknown generated tool mapping: ${desc.maps_to}`);
     }
   } catch (e) {
-    return err4(e instanceof Error ? e.message : String(e));
+    return toolError(e);
   }
 }
 
@@ -4569,7 +5513,9 @@ var ONTOLOGY_READ_ACTIONS = /* @__PURE__ */ new Set([
   "get_proposal"
 ]);
 function toolMutability(toolName, action) {
+  if (toolName === "mindgraph_memory") return "read";
   if (toolName === "mindgraph_retrieve") return "read";
+  if (toolName === "mindgraph_remember") return "write";
   if (toolName === "mindgraph_series_query") return "read";
   if (toolName === "mindgraph_plan") {
     return action && PLAN_READ_ACTIONS.has(action) ? "read" : "write";
@@ -4689,8 +5635,8 @@ async function checkMcpGovernance(toolName, args, config) {
       response = candidate;
       body = candidateBody;
       break;
-    } catch (error) {
-      lastFailure = error instanceof Error ? error.message : String(error);
+    } catch (error2) {
+      lastFailure = error2 instanceof Error ? error2.message : String(error2);
       if (attempt < retryDelays.length) {
         await sleep(retryDelays[attempt]);
         continue;
@@ -4764,6 +5710,12 @@ async function checkMcpGovernance(toolName, args, config) {
 
 // src/resources.ts
 var RESOURCES = [
+  {
+    uri: "mindgraph://memory/status",
+    name: "Memory Integration Status",
+    description: "Portable memory profile, adapter state, supported capabilities, and explicit limitations",
+    mimeType: "application/json"
+  },
   {
     uri: "mindgraph://stats",
     name: "Graph Statistics",
@@ -4821,8 +5773,10 @@ function json(uri, data) {
     contents: [{ uri, mimeType: "application/json", text: JSON.stringify(data) }]
   };
 }
-async function readResource(client2, uri) {
+async function readResource(client2, uri, memoryConfig = {}) {
   switch (uri) {
+    case "mindgraph://memory/status":
+      return json(uri, memoryStatus(memoryConfig));
     case "mindgraph://stats":
       return json(uri, await client2.stats());
     case "mindgraph://goals":
@@ -4854,16 +5808,18 @@ async function readResource(client2, uri) {
   }
   throw new Error(`Unknown resource: ${uri}`);
 }
-async function readGovernedResource(client2, uri, governanceConfig) {
+async function readGovernedResource(client2, uri, governanceConfig, memoryConfig = {}) {
+  const toolName = uri === "mindgraph://memory/status" ? "mindgraph_memory" : RESOURCE_GOVERNANCE_TOOL;
+  const toolArgs = uri === "mindgraph://memory/status" ? { action: "status" } : {};
   const governance = await checkMcpGovernance(
-    RESOURCE_GOVERNANCE_TOOL,
-    {},
+    toolName,
+    toolArgs,
     { ...governanceConfig, context: { resource_uri: uri } }
   );
   if (!governance.allowed) {
     throw new Error(governance.message);
   }
-  return readResource(client2, uri);
+  return readResource(client2, uri, memoryConfig);
 }
 
 // src/index.ts
@@ -4873,7 +5829,7 @@ var import_node_path5 = __toESM(require("path"));
 var import_node_fs4 = __toESM(require("fs"));
 var import_node_os3 = __toESM(require("os"));
 var import_node_path4 = __toESM(require("path"));
-var import_node_crypto4 = __toESM(require("crypto"));
+var import_node_crypto6 = __toESM(require("crypto"));
 var OWNER_MARKER = "--owner mindgraph";
 var RUNNER_RELATIVE = ".mindgraph/bin/mindgraph-hook.cjs";
 function command(harness) {
@@ -4886,7 +5842,7 @@ var RUNNER_VERSION_RELATIVE = `${RUNNER_RELATIVE}.version`;
 function installHookRunner(sourceFile, homeDir, version) {
   const target = import_node_path4.default.join(homeDir || import_node_os3.default.homedir(), RUNNER_RELATIVE);
   import_node_fs4.default.mkdirSync(import_node_path4.default.dirname(target), { recursive: true });
-  const temporary = `${target}.${process.pid}.${import_node_crypto4.default.randomUUID()}.tmp`;
+  const temporary = `${target}.${process.pid}.${import_node_crypto6.default.randomUUID()}.tmp`;
   import_node_fs4.default.copyFileSync(sourceFile, temporary);
   import_node_fs4.default.renameSync(temporary, target);
   const versionPath = import_node_path4.default.join(homeDir || import_node_os3.default.homedir(), RUNNER_VERSION_RELATIVE);
@@ -5056,7 +6012,7 @@ function entryHasOwnedHook(value) {
 }
 function writeSettings(file, settings) {
   import_node_fs4.default.mkdirSync(import_node_path4.default.dirname(file), { recursive: true });
-  const temporary = `${file}.${process.pid}.${import_node_crypto4.default.randomUUID()}.tmp`;
+  const temporary = `${file}.${process.pid}.${import_node_crypto6.default.randomUUID()}.tmp`;
   import_node_fs4.default.writeFileSync(temporary, `${JSON.stringify(settings, null, 2)}
 `, {
     mode: 384
@@ -5109,56 +6065,31 @@ var client = new import_mindgraph2.MindGraph({
 });
 var INSTRUCTIONS = `You have access to a persistent knowledge graph via MindGraph, plus any ontology tools generated by the active schema.
 
-## #1 RULE: Go straight to the user's topic
+## Default memory workflow: orient \u2192 answer \u2192 preserve
 
-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.
+**Orient only when prior durable state may matter.** Self-contained questions do not require a memory call or a warm-up sequence.
 
-**NEVER do any of these before addressing the user's topic:**
-- 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
+- Resuming work, asking what was in progress, or continuing a task: call \`mindgraph_memory\` once with action \`context\` and mode \`resume\` or \`continuity\`. This uses authoritative, task-first, lease-aware work state.
+- Asking about a topic that may depend on prior knowledge: call \`mindgraph_memory\` once with action \`context\`, mode \`topic\`, and 1\u20133 discriminating keywords.
+- Asking about integration capability or automatic behavior: call \`mindgraph_memory\` with action \`status\`.
+- Use the comprehensive read tools below only when the high-level result is insufficient or the user asks for a specific graph operation.
 
-There is no session to open. There is no context to pre-load. Just search for what the user asked about.
+**Answer from the bounded result.** Treat superseded, refuted, or out-of-validity items as warnings, not current facts. Retrieval proves only that the server returned context; it does not prove that a host automatically injected or used it.
 
-**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
-\u2717 WRONG: \`mindgraph_retrieve({action: "context", query: "Tell me about Indian philosophy and Taoism"})\` \u2014 natural language won't match BM25
+**Respect failed tool results.** An isError result is a failed operation, not evidence that the graph has no matches. Preserve its code and retry guidance. If retriable is false, do not automatically repeat the unchanged call or silently substitute another retrieval mode. Explain the failure; a narrower query or a later user-requested retry is a separate decision.
 
-## Two-phase retrieval protocol
+**Preserve selectively after material durable change.** Use the existing typed write tool for a fact, correction, decision, work-state transition, or reusable lesson. Do not write ephemeral conversation, routine mechanics, unsupported guesses, or information already represented accurately. An explicit no-write is the correct outcome when nothing durable changed.
 
-**Phase 1 \u2014 Orient (default, fast, lightweight):**
-Use \`action: "context"\` with keywords. By default this returns only graph nodes \u2014 structured knowledge with labels, summaries, types, confidence scores, and edges. This is usually sufficient and keeps results compact.
+## Topic retrieval details
 
-**Phase 2 \u2014 Fetch source text (only when needed):**
-If you need the original source text behind a node (for verbatim quotes, citations, or when graph summaries lack detail), use \`action: "context"\` with \`include_chunks: true\`. This adds full document chunks (400-800 words each) to the response.
+Topic context is graph-only by default. Set \`include_chunks: true\` only for source text needed for quotes, citations, or missing detail. Query with a few proper nouns or technical terms rather than a full sentence. If keyword retrieval succeeds but returns no matches, use \`mindgraph_retrieve\` with \`semantic\` or \`hybrid\`; use \`document_index\` to inspect ingested sources.
 
-**Orientation shortcut:**
-- \`action: "document_index"\` \u2014 list all ingested documents (titles, dates, UIDs) to see what's in the graph
+## Comprehensive read tools
 
-## Search strategy \u2014 keyword first, semantic as fallback
-
-The default search uses BM25 keyword matching. Query with 1\u20133 discriminating terms (proper nouns, technical terms). Drop filler words.
-
-**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 asks "what documents are in my graph?" \u2192 action "document_index"
-- User explicitly asks "what are my goals?" \u2192 action "active_goals"
-- User explicitly asks about open questions \u2192 action "open_questions"
-- User asks for advice or a recommendation ("suggest a hotel", "what should I read?") \u2192 action "preferences", query "topic keywords" \u2014 tailor the answer to what they like
-- Explore around a known node \u2192 action "neighborhood" with start_uid
-- Find connections between nodes \u2192 action "path" with start_uid + end_uid
+- Explicit graph inventory or state questions \u2192 the matching \`mindgraph_retrieve\` action such as \`document_index\`, \`active_goals\`, or \`open_questions\`
+- Advice or recommendations \u2192 \`mindgraph_retrieve\` action \`preferences\`, with topic keywords
+- Explore around a known node \u2192 \`mindgraph_retrieve\` action \`neighborhood\` with start_uid
+- Find connections between nodes \u2192 \`mindgraph_retrieve\` action \`path\` with start_uid + end_uid
 
 ## When to WRITE
 
@@ -5193,13 +6124,14 @@ if (PROFILE === "coding") {
 
 ## Coding profile
 
-**Recall order (overrides the #1 rule above for work and code questions):**
-- "What was I working on?" / current work state / resuming anything: call \`mindgraph_plan\` action \`resume_work\` FIRST. Work state is structural; never answer it from keyword search ("recent work" famously retrieves people named Work).
+**Coding recall order:**
+- "What was I working on?" / current work state / resuming anything: call \`mindgraph_memory\` action \`context\`, mode \`resume\` FIRST. It delegates to structural \`resume_work\`; never answer work state from keyword search ("recent work" famously retrieves people named Work).
 - Knowledge about specific code (a function, file, or route): \`mindgraph_code\` action \`recall\` \u2014 anchor-based, not keyword-based.
 - Broad knowledge searches: \`mindgraph_retrieve\` as usual, but when searching for work artifacts pass node_types filters (Task, Lesson, RiskAssessment, Claim) to keep personal-graph content out of engineering answers.
 
 - Use mindgraph_sync for explicit, one-way project memory-file imports. It discovers and hashes files, but you deliberately map durable assertions with record; it never writes graph state back to files.
 - Capture corrections, decisions with rationale, fixes that survived meaningful failed attempts, durable invariants/preferences, and blockers with evidence.
+- If a write returns \`near_duplicate\`, choose \`reuse_uid\` or \`supersedes_uid\`; use \`confirm_new\` only for genuinely distinct facts.
 - Do not capture routine mechanics, transient command output, facts cheaply derivable from code, unsupported speculation as high-confidence lessons, or completion without evidence.
 - Adapter context is owned by ${HARNESS}; omit invocation_context because hooks replace it.`;
 } else {
@@ -5209,7 +6141,7 @@ if (PROFILE === "coding") {
 }
 var RUNNER_REFRESH = (() => {
   try {
-    return refreshHookRunner("0.19.0", import_node_path5.default.join(__dirname, "cli.js"));
+    return refreshHookRunner("0.21.0", import_node_path5.default.join(__dirname, "cli.js"));
   } catch {
     return void 0;
   }
@@ -5223,12 +6155,12 @@ if (RUNNER_REFRESH?.refreshed) {
     }
   })();
   console.error(
-    `[mindgraph-mcp] refreshed pinned hook runner ${RUNNER_REFRESH.runnerVersion ? `v${RUNNER_REFRESH.runnerVersion}` : "(pre-sidecar)"} \u2192 v${"0.19.0"}` + (refreshedSettings.length > 0 ? `; refreshed owned hook entries in ${refreshedSettings.join(", ")}` : "")
+    `[mindgraph-mcp] refreshed pinned hook runner ${RUNNER_REFRESH.runnerVersion ? `v${RUNNER_REFRESH.runnerVersion}` : "(pre-sidecar)"} \u2192 v${"0.21.0"}` + (refreshedSettings.length > 0 ? `; refreshed owned hook entries in ${refreshedSettings.join(", ")}` : "")
   );
 }
 var HOOK_SKEW_NOTE = (() => {
   try {
-    return versionSkewNote("0.19.0");
+    return versionSkewNote("0.21.0");
   } catch {
     return void 0;
   }
@@ -5242,7 +6174,7 @@ ${HOOK_SKEW_NOTE}`;
 var server = new import_server.Server(
   {
     name: "mindgraph",
-    version: "0.19.0"
+    version: "0.21.0"
   },
   {
     capabilities: {
@@ -5266,6 +6198,14 @@ var GOVERNANCE_CONFIG = {
     return process.env.MINDGRAPH_GOVERNANCE === "off";
   }
 };
+var MEMORY_RUNTIME_CONFIG = {
+  serverVersion: "0.21.0",
+  baseUrl: BASE_URL,
+  profile: PROFILE,
+  harness: HARNESS,
+  orgId: ORG_ID,
+  agentId: AGENT_ID
+};
 server.setRequestHandler(import_types.CallToolRequestSchema, async (request) => {
   const { name, arguments: args } = request.params;
   const rawArgs = { ...args || {} };
@@ -5285,7 +6225,7 @@ server.setRequestHandler(import_types.CallToolRequestSchema, async (request) =>
   if (desc) {
     return handleGeneratedTool(client, desc, rawArgs);
   }
-  return handleTool(client, name, toolArgs);
+  return handleTool(client, name, toolArgs, MEMORY_RUNTIME_CONFIG);
 });
 var PROMPTS = [
   {
@@ -5450,16 +6390,21 @@ server.setRequestHandler(import_types.ListResourceTemplatesRequestSchema, async
   return { resourceTemplates: RESOURCE_TEMPLATES };
 });
 server.setRequestHandler(import_types.ReadResourceRequestSchema, async (request) => {
-  return readGovernedResource(client, request.params.uri, GOVERNANCE_CONFIG);
+  return readGovernedResource(
+    client,
+    request.params.uri,
+    GOVERNANCE_CONFIG,
+    MEMORY_RUNTIME_CONFIG
+  );
 });
 async function main() {
   const transport = new import_stdio.StdioServerTransport();
   await server.connect(transport);
   console.error(
-    `MindGraph MCP server v${"0.19.0"} running on stdio (${BASE_URL})`
+    `MindGraph MCP server v${"0.21.0"} running on stdio (${BASE_URL})`
   );
 }
-main().catch((error) => {
-  console.error("Fatal error:", error);
+main().catch((error2) => {
+  console.error("Fatal error:", error2);
   process.exit(1);
 });