mindgraph-mcp 0.20.0 → 0.21.0

package/README.md

@@ -174,7 +174,7 @@ and never block the coding session.
 
 ## What You Get
 
-**10 tools** covering the full knowledge-graph workflow (**12** in the coding
+**11 tools** covering the full knowledge-graph workflow (**13** in the coding
 profile):
 
 | Tool | Purpose |
@@ -185,6 +185,7 @@ profile):
 | `mindgraph_plan` | Plans, tasks, procedures, governance policies, risk assessments, executions |
 | `mindgraph_retrieve` | Context retrieval with bounded graph expansion, search, min-cost traversal, document index. Read results return as compact rendered text (labels, uids, summaries, epistemic status tags, relationships, traversal depth/cost); set `max_output_chars` for a hard whole-item character budget, or pass `format: "json"` for the raw server response |
 | `mindgraph_memory` | Read-only M0 memory workflow: inspect honest integration status, retrieve bounded topic context, or recover authoritative task-first resume/continuity context. Returns model-ready text plus a structured envelope with scope, hashes, trace, budget, freshness, and warnings |
+| `mindgraph_remember` | Small-text fast path: `remember` stores one fact/preference/decision synchronously and it is BM25- and vector-searchable on return; a stable `custom_id` makes re-sends an upsert of the same memory. `forget` reversibly removes by uid or custom_id, with `dry_run` previewing the affected edge uids |
 | `mindgraph_series_query` | Bounded, read-only dense-measurement queries: list an entity's Series, inspect latest values, page a time window, or calculate calendar aggregates |
 | `mindgraph_ingest` | Chunk / document / session ingestion with LLM-powered extraction. `job_status` without an id renders the 20 most recent jobs (`format: "json"` for the full list) |
 | `mindgraph_synthesize` | Project-scoped cross-document synthesis — mine signals (rendered as sections since 0.17.0), spawn Article-generation jobs |
@@ -300,3 +301,17 @@ npm run dev              # tsup --watch
 ## License
 
 MIT
+
+### Engine failures and retries
+
+Tool failures carry `isError: true`; `code`, `status`, and optional `retriable`
+are preserved in both the JSON text and structured content. Lease-conflict fields
+remain available to hooks. A failed retrieval is not an empty successful result.
+Explicit `retriable: false` stops automatic retries, including index maintenance.
+Other 503 responses retry only reviewed reads or atomically keyed work operations.
+
+This adoption branch pins the TypeScript SDK to immutable source commit
+`02bad10728836bf55129c08efabf71386432deee` so installs and CI exercise the same
+retry implementation. Git installation builds the SDK through its `prepare` hook.
+Replace this source pin and regenerate the lockfile only after a registry release
+containing that implementation is verified; older SDK releases retry all 503s.

package/dist/cli.js

@@ -27,25 +27,127 @@ var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__ge
 ));
 
 // node_modules/mindgraph/dist/index.mjs
+function errorFields(body) {
+  if (!body || typeof body !== "object" || Array.isArray(body)) return {};
+  const fields = body;
+  return {
+    ...typeof fields.code === "string" ? { code: fields.code } : {},
+    ...typeof fields.retriable === "boolean" ? { retriable: fields.retriable } : {}
+  };
+}
+function canRetryRequest(method, path8, body) {
+  if (method === "GET" || method === "HEAD") return true;
+  if (method !== "POST") return false;
+  if (READ_POSTS.has(path8)) return true;
+  const fields = body && typeof body === "object" && !Array.isArray(body) ? body : {};
+  if (typeof fields.action !== "string") return false;
+  if (Object.prototype.hasOwnProperty.call(READ_ACTIONS, path8) && READ_ACTIONS[path8].includes(fields.action)) return true;
+  return path8 === "/agent/plan" && IDEMPOTENT_WORK.has(fields.action) && typeof fields.idempotency_key === "string" && fields.idempotency_key.trim().length > 0;
+}
+function permitsRetry(fields) {
+  return fields.retriable !== false && ![
+    "query_memory_budget_exceeded",
+    "query_timeout",
+    "query_cancelled",
+    "vector_index_rebuilding"
+  ].includes(fields.code ?? "");
+}
+function retryDelayMs(header, backoff, attempt) {
+  const hint = Number(header);
+  return Number.isFinite(hint) && hint > 0 ? Math.min(hint * 1e3, 1e4) : Math.min(backoff * 2 ** Math.min(attempt, 32), 1e4);
+}
 function seg(value) {
   return encodeURIComponent(String(value));
 }
+function pathSteps(response) {
+  const wrapped = response && typeof response === "object" && !Array.isArray(response) ? response : void 0;
+  const raw = wrapped?.steps ?? response;
+  if (!Array.isArray(raw)) return [];
+  return raw.flatMap((value) => {
+    if (!value || typeof value !== "object" || Array.isArray(value)) return [];
+    const step = value;
+    const taggedName = (tagged) => {
+      if (typeof tagged === "string") return tagged;
+      if (!tagged || typeof tagged !== "object" || Array.isArray(tagged)) return null;
+      const custom = tagged.Custom;
+      return typeof custom === "string" ? custom : null;
+    };
+    return [{
+      ...step,
+      node_type: taggedName(step.node_type) ?? "Unknown",
+      edge_type: taggedName(step.edge_type)
+    }];
+  });
+}
 function createRequestId() {
   if (typeof globalThis.crypto?.randomUUID === "function") {
     return globalThis.crypto.randomUUID();
   }
   return `${Date.now().toString(36)}-${Math.random().toString(36).slice(2)}`;
 }
-var MindGraphError, MindGraph;
+var READ_POSTS, READ_ACTIONS, IDEMPOTENT_WORK, MindGraphError, MindGraph;
 var init_dist = __esm({
   "node_modules/mindgraph/dist/index.mjs"() {
     "use strict";
+    READ_POSTS = /* @__PURE__ */ new Set([
+      "/search",
+      "/retrieve/context",
+      "/nodes/batch",
+      "/edges/batch",
+      "/subgraph",
+      "/embeddings/search",
+      "/embeddings/search-text",
+      "/ontology/query",
+      "/ontology/query/structured",
+      "/ontology/objects/search"
+    ]);
+    READ_ACTIONS = {
+      "/retrieve": [
+        "text",
+        "semantic",
+        "hybrid",
+        "active_goals",
+        "open_questions",
+        "preferences",
+        "weak_claims",
+        "pending_approvals",
+        "unresolved_contradictions",
+        "merge_candidates",
+        "stale_derivations",
+        "curation_counts",
+        "layer",
+        "recent"
+      ],
+      "/traverse": ["chain", "top_k_paths", "neighborhood", "path", "subgraph"],
+      "/reality/series": ["window", "aggregate", "latest", "list_for_entity", "batch_latest", "batch_aggregate"],
+      "/intent/deliberation": ["get_open"],
+      "/action/risk": ["get_assessments"],
+      "/action/skill": ["get", "list"],
+      "/memory/config": ["get_preferences", "get_policies"],
+      "/memory/sync": ["status"],
+      "/agent/plan": ["get_plan", "resume_work"],
+      "/agent/governance": ["get_pending", "check"],
+      "/agent/execution": ["get_executions"],
+      "/evolve": ["history", "snapshot"]
+    };
+    IDEMPOTENT_WORK = /* @__PURE__ */ new Set([
+      "claim_task",
+      "heartbeat",
+      "start_iteration",
+      "checkpoint_iteration",
+      "block_task",
+      "complete_task",
+      "abandon_iteration"
+    ]);
     MindGraphError = class extends Error {
       constructor(message, status, body) {
         super(message);
         this.status = status;
         this.body = body;
         this.name = "MindGraphError";
+        const fields = errorFields(body);
+        this.code = fields.code;
+        this.retriable = fields.retriable;
       }
     };
     MindGraph = class {
@@ -63,6 +165,18 @@ var init_dist = __esm({
         this.telemetrySurface = config.telemetrySurface;
         this.maxRetries = config.maxRetries ?? 3;
         this.retryBackoffMs = config.retryBackoffMs ?? 1e3;
+        if (!Number.isSafeInteger(this.maxRetries) || this.maxRetries < 0) {
+          throw new RangeError("maxRetries must be a non-negative safe integer");
+        }
+        if (!Number.isFinite(this.retryBackoffMs) || this.retryBackoffMs < 0) {
+          throw new RangeError("retryBackoffMs must be finite and non-negative");
+        }
+        if (config.timeoutMs !== void 0) {
+          if (!Number.isFinite(config.timeoutMs) || config.timeoutMs <= 0) {
+            throw new RangeError("timeoutMs must be a positive finite number of milliseconds");
+          }
+          this.timeoutMs = config.timeoutMs;
+        }
       }
       // ---- HTTP helpers ----
       async request(method, path8, body) {
@@ -79,9 +193,14 @@ var init_dist = __esm({
         if (body !== void 0) {
           init.body = JSON.stringify(body);
         }
+        const retrySafe = canRetryRequest(
+          method,
+          path8,
+          typeof init.body === "string" ? JSON.parse(init.body) : void 0
+        );
         let lastError;
         for (let attempt = 0; attempt <= this.maxRetries; attempt++) {
-          const res = await fetch(url, init);
+          const res = await this.fetchWithDeadline(url, init, method, path8);
           if (!res.ok) {
             const text22 = await res.text().catch(() => "");
             let parsed;
@@ -95,10 +214,9 @@ var init_dist = __esm({
               res.status,
               parsed
             );
-            if (res.status === 503 && attempt < this.maxRetries) {
+            if (res.status === 503 && retrySafe && permitsRetry(err5) && attempt < this.maxRetries) {
               lastError = err5;
-              const retryAfterSecs = Number(res.headers.get("retry-after"));
-              const delay = Number.isFinite(retryAfterSecs) && retryAfterSecs > 0 ? Math.min(retryAfterSecs * 1e3, 1e4) : this.retryBackoffMs * 2 ** attempt;
+              const delay = retryDelayMs(res.headers.get("retry-after"), this.retryBackoffMs, attempt);
               await new Promise((r) => setTimeout(r, delay));
               continue;
             }
@@ -110,6 +228,33 @@ var init_dist = __esm({
         }
         throw lastError;
       }
+      /**
+       * One HTTP attempt. With `timeoutMs` set, the attempt is aborted at the
+       * deadline and surfaces as a non-retriable `MindGraphError` (`code:
+       * "timeout"`, `status: 0`). Without it the request is sent unchanged — no
+       * AbortSignal is attached, preserving the pre-0.16 behaviour.
+       */
+      async fetchWithDeadline(url, init, method, path8) {
+        if (this.timeoutMs === void 0) {
+          return fetch(url, init);
+        }
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), this.timeoutMs);
+        try {
+          return await fetch(url, { ...init, signal: controller.signal });
+        } catch (error2) {
+          if (controller.signal.aborted) {
+            throw new MindGraphError(
+              `${method} ${path8} timed out after ${this.timeoutMs}ms`,
+              0,
+              { error: "timeout", code: "timeout", retriable: false }
+            );
+          }
+          throw error2;
+        } finally {
+          clearTimeout(timer);
+        }
+      }
       get(path8) {
         return this.request("GET", path8);
       }
@@ -359,6 +504,40 @@ var init_dist = __esm({
       async memorySync(req) {
         return this.post("/memory/sync", req);
       }
+      // ---- Memory (fast path) ----
+      /**
+       * Store a small piece of text as a memory, synchronously. The node is
+       * BM25- and vector-searchable when this resolves (`searchable` says which).
+       * Pass `custom_id` to make re-sends an upsert of the same node.
+       */
+      async remember(text2, options = {}) {
+        return this.post("/memory/remember", { text: text2, ...options });
+      }
+      /**
+       * Reversibly remove a memory by `uid` or `custom_id` (tombstone plus its
+       * connected edges). `dry_run: true` previews the affected edge uids first.
+       * Undo with `restore(uid)` and `evolve({ action: "restore_edge", uid })`.
+       */
+      async forget(target, options = {}) {
+        return this.post("/memory/forget", { ...target, ...options });
+      }
+      /**
+       * Operator guidance for what agents should remember into a Space; surfaced
+       * on every `remember()` response and on `retrieveContext()`. Empty clears it.
+       */
+      async setRememberInstructions(text2, options = {}) {
+        return this.post("/memory/config", {
+          action: "set_remember_instructions",
+          text: text2,
+          ...options
+        });
+      }
+      async getRememberInstructions(options = {}) {
+        return this.post("/memory/config", {
+          action: "get_remember_instructions",
+          ...options
+        });
+      }
       // ---- Agent Layer ----
       async plan(req) {
         return this.post("/agent/plan", req);
@@ -581,7 +760,7 @@ var init_dist = __esm({
           start_uid: uid,
           max_depth: maxDepth
         });
-        return r?.steps ?? r;
+        return pathSteps(r);
       }
       async neighborhood(uid, maxDepth = 1) {
         const r = await this.post("/traverse", {
@@ -589,7 +768,7 @@ var init_dist = __esm({
           start_uid: uid,
           max_depth: maxDepth
         });
-        return r?.steps ?? r;
+        return pathSteps(r);
       }
       async subgraph(uid, opts) {
         return this.post("/subgraph", { start_uids: [uid], ...opts });
@@ -960,11 +1139,19 @@ var init_dist = __esm({
       /**
        * Create a domain object by hand (auto-approved). Returns the created node
        * uid + the audit proposal id. Throws 409 if an object of the same type +
-       * canonical_name already exists, unless `allow_duplicate` is set.
+       * canonical_name already exists, unless `allow_duplicate` is set. The
+       * schema's identity key is always enforced.
        */
       async createDomainObject(req) {
         return this.post("/v1/ontology/objects", req);
       }
+      /**
+       * Schema-validated authored update with optimistic concurrency. Identity
+       * fields are immutable; create and explicitly merge when identity changes.
+       */
+      async updateDomainObject(uid, req) {
+        return this.patch(`/v1/ontology/objects/${seg(uid)}`, req);
+      }
       async linkDomainObjects(req) {
         return this.post("/ontology/relation", { action: "create", ...req });
       }
@@ -1787,6 +1974,22 @@ function conflictState(e) {
   }
   return lifted;
 }
+function toolError(e, fallbackCode) {
+  const body = e instanceof 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 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
+  };
+}
 var CONFLICT_STATE_KEYS;
 var init_error_detail = __esm({
   "src/error-detail.ts"() {
@@ -1994,7 +2197,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) {
@@ -2738,7 +2941,7 @@ async function handleSyncTool(client2, args) {
     }
     return ok2(await remote.memorySync(request));
   } catch (error2) {
-    return err2("sync_failed", errorDetail(error2));
+    return toolError(error2, "sync_failed");
   }
 }
 async function scanRepository(remote, repository, requested, provider, agentId) {
@@ -4179,6 +4382,9 @@ async function handleTool(client2, name, args, memoryConfig = {}) {
       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;
@@ -4211,19 +4417,7 @@ async function handleTool(client2, name, args, memoryConfig = {}) {
     ].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) {
@@ -4247,6 +4441,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,
@@ -6430,6 +6674,66 @@ var init_tools = __esm({
           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
@@ -6605,13 +6909,14 @@ 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);
   }
 }
 var ok4, rendered, err4, CACHE_TTL_MS, FAILURE_COOLDOWN_MS, cache, retryNotBefore, EMPTY, DuplicateGeneratedToolError, STRUCTURED_QUERY_PASSTHROUGH;
 var init_generated_tools = __esm({
   "src/generated-tools.ts"() {
     "use strict";
+    init_error_detail();
     init_render();
     ok4 = (data) => ({
       // Compact on purpose — pretty-printing doubled the token cost.
@@ -6671,6 +6976,7 @@ function unsupportedResponse(status, body) {
 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";
@@ -7021,7 +7327,7 @@ async function main() {
   const transport = new import_stdio.StdioServerTransport();
   await server.connect(transport);
   console.error(
-    `MindGraph MCP server v${"0.20.0"} running on stdio (${BASE_URL})`
+    `MindGraph MCP server v${"0.21.0"} running on stdio (${BASE_URL})`
   );
 }
 var import_server, import_stdio, import_types, import_node_path6, API_KEY, BASE_URL, AGENT_ID, ORG_ID, PROFILE, HARNESS, client, INSTRUCTIONS, RUNNER_REFRESH, HOOK_SKEW_NOTE, server, GOVERNANCE_CONFIG, MEMORY_RUNTIME_CONFIG, PROMPTS;
@@ -7073,11 +7379,13 @@ var init_src = __esm({
 
 **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.
 
+**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.
+
 **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.
 
 ## Topic retrieval details
 
-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 fails, use \`mindgraph_retrieve\` with \`semantic\` or \`hybrid\`; use \`document_index\` to inspect ingested sources.
+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.
 
 ## Comprehensive read tools
 
@@ -7136,7 +7444,7 @@ Capture knowledge when the user shares something worth remembering:
     }
     RUNNER_REFRESH = (() => {
       try {
-        return refreshHookRunner("0.20.0", import_node_path6.default.join(__dirname, "cli.js"));
+        return refreshHookRunner("0.21.0", import_node_path6.default.join(__dirname, "cli.js"));
       } catch {
         return void 0;
       }
@@ -7150,12 +7458,12 @@ Capture knowledge when the user shares something worth remembering:
         }
       })();
       console.error(
-        `[mindgraph-mcp] refreshed pinned hook runner ${RUNNER_REFRESH.runnerVersion ? `v${RUNNER_REFRESH.runnerVersion}` : "(pre-sidecar)"} \u2192 v${"0.20.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(", ")}` : "")
       );
     }
     HOOK_SKEW_NOTE = (() => {
       try {
-        return versionSkewNote("0.20.0");
+        return versionSkewNote("0.21.0");
       } catch {
         return void 0;
       }
@@ -7169,7 +7477,7 @@ ${HOOK_SKEW_NOTE}`;
     server = new import_server.Server(
       {
         name: "mindgraph",
-        version: "0.20.0"
+        version: "0.21.0"
       },
       {
         capabilities: {
@@ -7194,7 +7502,7 @@ ${HOOK_SKEW_NOTE}`;
       }
     };
     MEMORY_RUNTIME_CONFIG = {
-      serverVersion: "0.20.0",
+      serverVersion: "0.21.0",
       baseUrl: BASE_URL,
       profile: PROFILE,
       harness: HARNESS,
@@ -8961,7 +9269,7 @@ function withHooksFlag() {
 }
 function finishCodeInstall(apiKey, baseUrl, withHooks, agentId) {
   if (withHooks) {
-    const runner = installHookRunner(__filename, void 0, "0.20.0");
+    const runner = installHookRunner(__filename, void 0, "0.21.0");
     console.log(`Installed pinned hook runner at ${runner}`);
     const result = installClaudeHooks("user");
     console.log(
@@ -9276,7 +9584,7 @@ ${total} skill(s) synced.`);
       if (hookHarness !== "claude-code" && hookHarness !== "codex") {
         throw new Error("--harness must be claude-code or codex");
       }
-      const runner = installHookRunner(__filename, void 0, "0.20.0");
+      const runner = installHookRunner(__filename, void 0, "0.21.0");
       console.log(`Installed pinned hook runner at ${runner}`);
       const result = hookHarness === "codex" ? installCodexHooks(scope, projectDir) : installClaudeHooks(scope, projectDir);
       console.log(

package/dist/index.js

@@ -89,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");
@@ -1086,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) {
@@ -1558,7 +1574,7 @@ async function handleSyncTool(client2, args) {
     }
     return ok2(await remote.memorySync(request));
   } catch (error2) {
-    return err2("sync_failed", errorDetail(error2));
+    return toolError(error2, "sync_failed");
   }
 }
 async function scanRepository(remote, repository, requested, provider, agentId) {
@@ -3919,6 +3935,66 @@ 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
@@ -4004,6 +4080,9 @@ async function handleTool(client2, name, args, memoryConfig = {}) {
       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;
@@ -4036,19 +4115,7 @@ async function handleTool(client2, name, args, memoryConfig = {}) {
     ].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) {
@@ -4072,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,
@@ -5346,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);
   }
 }
 
@@ -5398,6 +5515,7 @@ var ONTOLOGY_READ_ACTIONS = /* @__PURE__ */ new Set([
 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";
@@ -5958,11 +6076,13 @@ var INSTRUCTIONS = `You have access to a persistent knowledge graph via MindGrap
 
 **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.
 
+**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.
+
 **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.
 
 ## Topic retrieval details
 
-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 fails, use \`mindgraph_retrieve\` with \`semantic\` or \`hybrid\`; use \`document_index\` to inspect ingested sources.
+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.
 
 ## Comprehensive read tools
 
@@ -6021,7 +6141,7 @@ if (PROFILE === "coding") {
 }
 var RUNNER_REFRESH = (() => {
   try {
-    return refreshHookRunner("0.20.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;
   }
@@ -6035,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.20.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.20.0");
+    return versionSkewNote("0.21.0");
   } catch {
     return void 0;
   }
@@ -6054,7 +6174,7 @@ ${HOOK_SKEW_NOTE}`;
 var server = new import_server.Server(
   {
     name: "mindgraph",
-    version: "0.20.0"
+    version: "0.21.0"
   },
   {
     capabilities: {
@@ -6079,7 +6199,7 @@ var GOVERNANCE_CONFIG = {
   }
 };
 var MEMORY_RUNTIME_CONFIG = {
-  serverVersion: "0.20.0",
+  serverVersion: "0.21.0",
   baseUrl: BASE_URL,
   profile: PROFILE,
   harness: HARNESS,
@@ -6281,7 +6401,7 @@ async function main() {
   const transport = new import_stdio.StdioServerTransport();
   await server.connect(transport);
   console.error(
-    `MindGraph MCP server v${"0.20.0"} running on stdio (${BASE_URL})`
+    `MindGraph MCP server v${"0.21.0"} running on stdio (${BASE_URL})`
   );
 }
 main().catch((error2) => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mindgraph-mcp",
-  "version": "0.20.0",
+  "version": "0.21.0",
   "description": "MCP server for MindGraph — connect Claude Desktop, Claude Code, and any MCP client to your knowledge graph",
   "repository": {
     "type": "git",
@@ -32,7 +32,7 @@
   "license": "MIT",
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.12.1",
-    "mindgraph": "^0.15.0"
+    "mindgraph": "^0.16.0"
   },
   "devDependencies": {
     "@types/node": "^22.0.0",