mindgraph-mcp 0.14.2 → 0.14.4

package/README.md

@@ -151,8 +151,14 @@ mindgraph-mcp uninstall-hooks  Remove MindGraph-owned hook entries
 mindgraph-mcp status           Show installation status
 ```
 
-Options: `--api-key <key>`, `--base-url <url>`, `--scope user|project`,
-`--project-dir <dir>`, `--harness <name>`, `--help`.
+Options: `--api-key <key>`, `--base-url <url>`, `--agent-id <id>`,
+`--scope user|project`, `--project-dir <dir>`, `--harness <name>`, `--help`.
+
+**Teams**: when several people share one org graph, give each member a
+distinct identity — `--agent-id claude-code:<name>` on `install-code` /
+`install-hooks`. Anchored knowledge is shared automatically; distinct agent
+ids keep task leases and resume briefs per-person (identical ids make
+teammates one logical agent, which claims each other's work).
 
 ## Environment
 

package/dist/cli.js

@@ -26,6 +26,895 @@ var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__ge
   mod
 ));
 
+// node_modules/mindgraph/dist/index.mjs
+function seg(value) {
+  return encodeURIComponent(String(value));
+}
+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 init_dist = __esm({
+  "node_modules/mindgraph/dist/index.mjs"() {
+    "use strict";
+    MindGraphError = class extends Error {
+      constructor(message, status, body) {
+        super(message);
+        this.status = status;
+        this.body = body;
+        this.name = "MindGraphError";
+      }
+    };
+    MindGraph = class {
+      constructor(config) {
+        this.baseUrl = config.baseUrl.replace(/\/$/, "");
+        this.headers = { "Content-Type": "application/json" };
+        if (config.apiKey) {
+          this.headers["Authorization"] = `Bearer ${config.apiKey}`;
+        } else if (config.jwt) {
+          this.headers["Authorization"] = `Bearer ${config.jwt}`;
+        }
+        if (config.orgId) {
+          this.headers["X-MindGraph-Org"] = config.orgId;
+        }
+        this.telemetrySurface = config.telemetrySurface;
+        this.maxRetries = config.maxRetries ?? 3;
+        this.retryBackoffMs = config.retryBackoffMs ?? 1e3;
+      }
+      // ---- HTTP helpers ----
+      async request(method, path6, body) {
+        const url = `${this.baseUrl}${path6}`;
+        const requestId = createRequestId();
+        const init = {
+          method,
+          headers: {
+            ...this.headers,
+            "X-MindGraph-Request-ID": requestId,
+            ...this.telemetrySurface ? { "X-MindGraph-Surface": this.telemetrySurface } : {}
+          }
+        };
+        if (body !== void 0) {
+          init.body = JSON.stringify(body);
+        }
+        let lastError;
+        for (let attempt = 0; attempt <= this.maxRetries; attempt++) {
+          const res = await fetch(url, init);
+          if (!res.ok) {
+            const text2 = await res.text().catch(() => "");
+            let parsed;
+            try {
+              parsed = JSON.parse(text2);
+            } catch {
+              parsed = text2;
+            }
+            const err5 = new MindGraphError(
+              `${method} ${path6} failed: ${res.status}`,
+              res.status,
+              parsed
+            );
+            if (res.status === 503 && attempt < this.maxRetries) {
+              lastError = err5;
+              const delay = this.retryBackoffMs * 2 ** attempt;
+              await new Promise((r) => setTimeout(r, delay));
+              continue;
+            }
+            throw err5;
+          }
+          const text = await res.text();
+          if (!text) return void 0;
+          return JSON.parse(text);
+        }
+        throw lastError;
+      }
+      get(path6) {
+        return this.request("GET", path6);
+      }
+      post(path6, body) {
+        return this.request("POST", path6, body);
+      }
+      patch(path6, body) {
+        return this.request("PATCH", path6, body);
+      }
+      del(path6) {
+        return this.request("DELETE", path6);
+      }
+      // ---- Health ----
+      async health() {
+        return this.get("/health");
+      }
+      async stats() {
+        return this.get("/stats");
+      }
+      /**
+       * Schema fill-rate report (measure-first tiering): per live node type,
+       * the exact live count and sampled per-field fill rates; near-empty
+       * fields flagged below 5%. `sample` caps per-type sampling (default
+       * 1000); `layer` restricts (e.g. "epistemic").
+       */
+      async schemaFillStats(params) {
+        const q = new URLSearchParams();
+        if (params?.sample !== void 0) q.set("sample", String(params.sample));
+        if (params?.layer) q.set("layer", params.layer);
+        const qs = q.toString();
+        return this.get(`/stats/schema-fill${qs ? `?${qs}` : ""}`);
+      }
+      // ---- Reality Layer ----
+      async capture(req) {
+        return this.post("/reality/capture", req);
+      }
+      async entity(req) {
+        return this.post("/reality/entity", req);
+      }
+      /** Convenience: create or find an entity by label. */
+      async findOrCreateEntity(label, props, agentId) {
+        return this.post("/reality/entity", {
+          action: "create",
+          label,
+          props: { entity_type: "other", ...props },
+          agent_id: agentId
+        });
+      }
+      /** Convenience: create or find a Person entity by label. */
+      async findOrCreatePerson(label, props, agentId) {
+        return this.findOrCreateEntity(label, { entity_type: "person", ...props }, agentId);
+      }
+      /** Convenience: create or find an Organization entity by label. */
+      async findOrCreateOrganization(label, props, agentId) {
+        return this.findOrCreateEntity(label, { entity_type: "organization", ...props }, agentId);
+      }
+      /** Convenience: create or find a Nation entity by label. */
+      async findOrCreateNation(label, props, agentId) {
+        return this.findOrCreateEntity(label, { entity_type: "nation", ...props }, agentId);
+      }
+      /** Convenience: create or find an Event entity by label. */
+      async findOrCreateEvent(label, props, agentId) {
+        return this.findOrCreateEntity(label, { entity_type: "event", ...props }, agentId);
+      }
+      /** Convenience: create or find a Place entity by label. */
+      async findOrCreatePlace(label, props, agentId) {
+        return this.findOrCreateEntity(label, { entity_type: "place", ...props }, agentId);
+      }
+      /** Convenience: create or find a Concept entity by label. */
+      async findOrCreateConcept(label, props, agentId) {
+        return this.findOrCreateEntity(label, { entity_type: "concept", ...props }, agentId);
+      }
+      /**
+       * Resolve text to an existing entity via alias matching.
+       * Returns `{ uid: string | null }`.
+       */
+      async resolveEntity(text, agentId) {
+        return this.post("/reality/entity", {
+          action: "resolve",
+          text,
+          agent_id: agentId
+        });
+      }
+      /**
+       * Fuzzy-match text against existing entities.
+       * Returns `{ matches: [{ uid, label, score }] }`.
+       */
+      async fuzzyResolveEntity(text, limit = 5, agentId) {
+        return this.post("/reality/entity", {
+          action: "fuzzy_resolve",
+          text,
+          limit,
+          agent_id: agentId
+        });
+      }
+      // ---- Epistemic Layer ----
+      async argue(req) {
+        return this.post("/epistemic/argument", req);
+      }
+      async inquire(req) {
+        return this.post("/epistemic/inquiry", req);
+      }
+      async structure(req) {
+        return this.post("/epistemic/structure", req);
+      }
+      /**
+       * Convenience: create a Claim node via the argument endpoint.
+       * Returns the full argument response including `claim_uid`.
+       */
+      async addClaim(label, content, confidence, agentId) {
+        return this.post("/epistemic/argument", {
+          claim: {
+            label,
+            confidence,
+            props: { content }
+          },
+          agent_id: agentId
+        });
+      }
+      /**
+       * Convenience: create an Evidence node attached to a claim via the argument endpoint.
+       * If `claimLabel` and `claimConfidence` are provided, also creates the claim.
+       */
+      async addEvidence(label, description, agentId) {
+        return this.post("/epistemic/argument", {
+          claim: { label: `Claim for: ${label}` },
+          evidence: [{ label, props: { description } }],
+          agent_id: agentId
+        });
+      }
+      /** Convenience: create an Observation node via the reality capture endpoint. */
+      async addObservation(label, description, agentId) {
+        return this.post("/reality/capture", {
+          action: "observation",
+          label,
+          summary: description,
+          agent_id: agentId
+        });
+      }
+      // ---- Intent Layer ----
+      async commit(req) {
+        return this.post("/intent/commitment", req);
+      }
+      async deliberate(req) {
+        return this.post("/intent/deliberation", req);
+      }
+      /** Open a new decision for deliberation. Returns the Decision node. */
+      async openDecision(label, opts) {
+        return this.post("/intent/deliberation", {
+          action: "open_decision",
+          label,
+          ...opts
+        });
+      }
+      /** Add an option to an open decision. Returns the Option node. */
+      async addOption(decisionUid, label, opts) {
+        return this.post("/intent/deliberation", {
+          action: "add_option",
+          decision_uid: decisionUid,
+          label,
+          ...opts
+        });
+      }
+      /**
+       * Resolve a decision by choosing an option.
+       * `chosenOptionUid` must be the uid of an option added via `addOption()`.
+       */
+      async resolveDecision(decisionUid, chosenOptionUid, opts) {
+        return this.post("/intent/deliberation", {
+          action: "resolve",
+          decision_uid: decisionUid,
+          chosen_option_uid: chosenOptionUid,
+          ...opts
+        });
+      }
+      // ---- Action Layer ----
+      async procedure(req) {
+        return this.post("/action/procedure", req);
+      }
+      async risk(req) {
+        return this.post("/action/risk", req);
+      }
+      // ---- Memory Layer ----
+      async session(req) {
+        return this.post("/memory/session", req);
+      }
+      async journal(label, props, options) {
+        return this.post("/memory/session", {
+          action: "journal",
+          label,
+          props,
+          ...options
+        });
+      }
+      async distill(req) {
+        return this.post("/memory/distill", req);
+      }
+      async memoryConfig(req) {
+        return this.post("/memory/config", req);
+      }
+      async memorySync(req) {
+        return this.post("/memory/sync", req);
+      }
+      // ---- Agent Layer ----
+      async plan(req) {
+        return this.post("/agent/plan", req);
+      }
+      async governance(req) {
+        return this.post("/agent/governance", req);
+      }
+      async execution(req) {
+        return this.post("/agent/execution", req);
+      }
+      // ---- Cross-cutting ----
+      /** Returns an array of results. Shape varies by action. */
+      async retrieve(req) {
+        return this.post("/retrieve", req);
+      }
+      async traverse(req) {
+        return this.post("/traverse", req);
+      }
+      async evolve(req) {
+        return this.post("/evolve", req);
+      }
+      // ---- Node CRUD ----
+      async getNode(uid) {
+        return this.get(`/node/${seg(uid)}`);
+      }
+      /**
+       * Create a node via the low-level CRUD endpoint.
+       *
+       * The server requires `props._type` to determine the node variant.
+       * If `node_type` is provided and `_type` is not already in `props`,
+       * it is injected automatically.
+       */
+      async addNode(body) {
+        const props = { ...body.props };
+        if (body.node_type && !("_type" in props)) {
+          props._type = body.node_type;
+        }
+        return this.post("/node", { ...body, props });
+      }
+      async updateNode(uid, body) {
+        return this.patch(`/node/${seg(uid)}`, body);
+      }
+      async deleteNode(uid) {
+        await this.del(`/node/${seg(uid)}`);
+      }
+      async batchDeleteNodes(params) {
+        const body = {};
+        if (params.uids) body.uids = params.uids;
+        if (params.agentId) body.agent_id = params.agentId;
+        if (params.filter) {
+          body.filter = {
+            node_type: params.filter.nodeType,
+            node_types: params.filter.nodeTypes,
+            layer: params.filter.layer,
+            label_contains: params.filter.labelContains,
+            prop_equals: params.filter.propEquals
+          };
+        }
+        if (params.reason) body.reason = params.reason;
+        if (params.by) body.by = params.by;
+        if (params.hardPurge) body.hard_purge = params.hardPurge;
+        return this.post("/nodes/delete", body);
+      }
+      async getNodeHistory(uid) {
+        return this.get(`/node/${seg(uid)}/history`);
+      }
+      async getNodeAtVersion(uid, version) {
+        return this.get(`/node/${seg(uid)}/history/${seg(version)}`);
+      }
+      // ---- Edge CRUD ----
+      async addLink(body) {
+        return this.post("/link", body);
+      }
+      /**
+       * Create an edge via the low-level CRUD endpoint.
+       *
+       * The server requires `props._type` to determine the edge variant.
+       * If `edge_type` is provided and `_type` is not already in `props`,
+       * it is injected automatically.
+       */
+      async addEdge(body) {
+        const props = { ...body.props };
+        if (body.edge_type && !("_type" in props)) {
+          props._type = body.edge_type;
+        }
+        return this.post("/edge", { ...body, props });
+      }
+      async updateEdge(uid, body) {
+        return this.patch(`/edge/${seg(uid)}`, body);
+      }
+      async deleteEdge(uid) {
+        await this.del(`/edge/${seg(uid)}`);
+      }
+      async getEdgeHistory(uid) {
+        return this.get(`/edge/${seg(uid)}/history`);
+      }
+      /**
+       * List edges filtered by source and/or target node.
+       * At least one of `from_uid` or `to_uid` is **required** —
+       * the server returns 400 if neither is provided.
+       */
+      async getEdges(params) {
+        if (!params.from_uid && !params.to_uid) {
+          throw new Error("at least one of from_uid or to_uid is required");
+        }
+        const qs = new URLSearchParams();
+        if (params.from_uid) qs.set("from_uid", params.from_uid);
+        if (params.to_uid) qs.set("to_uid", params.to_uid);
+        return this.get(`/edges?${qs}`);
+      }
+      async getEdgeBetween(params) {
+        const qs = new URLSearchParams();
+        qs.set("from_uid", params.from_uid);
+        qs.set("to_uid", params.to_uid);
+        if (params.edge_type) qs.set("edge_type", params.edge_type);
+        return this.get(`/edge/between?${qs}`);
+      }
+      // ---- Search ----
+      async search(query, opts) {
+        return this.post("/search", { query, ...opts });
+      }
+      /**
+       * Hybrid BM25 + vector search with reciprocal rank fusion. Pass
+       * `explain: true` to get per-leg contributions (`legs`) on each result —
+       * the "why retrieved" detail (server ≥ 1.2.0; older servers ignore it).
+       */
+      async hybridSearch(query, opts) {
+        return this.post("/retrieve", {
+          action: "hybrid",
+          query,
+          ...opts
+        });
+      }
+      // ---- Nodes listing ----
+      async getNodes(params) {
+        const qs = new URLSearchParams();
+        if (params?.node_type) qs.set("node_type", params.node_type);
+        if (params?.layer) qs.set("layer", params.layer);
+        if (params?.limit != null) qs.set("limit", String(params.limit));
+        if (params?.offset != null) qs.set("offset", String(params.offset));
+        return this.get(`/nodes?${qs}`);
+      }
+      async getAgentNodes(agentId) {
+        return this.get(`/agent/${seg(agentId)}/nodes`);
+      }
+      // ---- Batch ----
+      async batch(req) {
+        return this.post("/batch", req);
+      }
+      /** Fetch multiple nodes by UID in a single request. */
+      async getNodesBatch(uids) {
+        return this.post("/nodes/batch", { uids });
+      }
+      /** Fetch all edges between a set of node UIDs. */
+      async getEdgesBatch(uids) {
+        return this.post("/edges/batch", { uids });
+      }
+      // ---- Embeddings ----
+      async configureEmbeddings(body) {
+        return this.post("/embeddings/configure", body);
+      }
+      async embeddingSearch(body) {
+        return this.post("/embeddings/search", body);
+      }
+      async embeddingSearchText(body) {
+        return this.post("/embeddings/search-text", body);
+      }
+      async getEmbedding(uid) {
+        return this.get(`/node/${seg(uid)}/embedding`);
+      }
+      async setEmbedding(uid, vector) {
+        await this.request("PUT", `/node/${seg(uid)}/embedding`, { vector });
+      }
+      async deleteEmbedding(uid) {
+        await this.del(`/node/${seg(uid)}/embedding`);
+      }
+      // ---- Entity resolution ----
+      async mergeEntities(body) {
+        return this.post("/entities/merge", body);
+      }
+      async addAlias(body) {
+        return this.post("/alias", body);
+      }
+      async getAliases(uid) {
+        return this.get(`/aliases/${seg(uid)}`);
+      }
+      async resolveAlias(text) {
+        return this.get(`/resolve?text=${encodeURIComponent(text)}`);
+      }
+      // ---- Export / Import ----
+      async exportGraph() {
+        return this.get("/export");
+      }
+      /**
+       * Export one document's extraction provenance as JSON-LD: PROV-O
+       * entities/agents, CiTO relations between extracted claims, and the
+       * citation anchors as W3C Web Annotations (TextQuoteSelector +
+       * TextPositionSelector; positions are chunk-relative UTF-8 byte offsets,
+       * flagged via `mg:offsetUnit`).
+       */
+      async exportProvenance(documentUid) {
+        return this.get(
+          `/export/prov?document_uid=${encodeURIComponent(documentUid)}`
+        );
+      }
+      async importGraph(data) {
+        return this.post("/import", data);
+      }
+      // ---- Lifecycle ----
+      async decay(req) {
+        return this.post("/decay", req);
+      }
+      async purge(req) {
+        return this.post("/purge", req ?? {});
+      }
+      // ---- Traversal shortcuts ----
+      async reasoningChain(uid, maxDepth = 5) {
+        const r = await this.post("/traverse", {
+          action: "chain",
+          start_uid: uid,
+          max_depth: maxDepth
+        });
+        return r?.steps ?? r;
+      }
+      async neighborhood(uid, maxDepth = 1) {
+        const r = await this.post("/traverse", {
+          action: "neighborhood",
+          start_uid: uid,
+          max_depth: maxDepth
+        });
+        return r?.steps ?? r;
+      }
+      async subgraph(uid, opts) {
+        return this.post("/subgraph", { start_uids: [uid], ...opts });
+      }
+      // ---- Lifecycle shortcuts ----
+      async tombstone(uid, reason, agentId) {
+        return this.post("/evolve", {
+          action: "tombstone",
+          uid,
+          reason,
+          agent_id: agentId
+        });
+      }
+      async restore(uid, agentId) {
+        return this.post("/evolve", {
+          action: "restore",
+          uid,
+          agent_id: agentId
+        });
+      }
+      // ---- Epistemic queries ----
+      async getGoals() {
+        return this.get("/goals");
+      }
+      async getOpenDecisions() {
+        return this.get("/decisions");
+      }
+      async getOpenQuestions() {
+        return this.get("/questions");
+      }
+      async getWeakClaims() {
+        return this.get("/claims/weak");
+      }
+      async getContradictions() {
+        return this.get("/contradictions");
+      }
+      /**
+       * Pending merge candidates: suspected duplicate pairs recorded by the dedup
+       * pipeline's ambiguous zone as PossibleDuplicate edges, awaiting a human
+       * merge/dismiss decision (server >= 1.3).
+       */
+      async getMergeCandidates() {
+        return this.post("/retrieve", { action: "merge_candidates" });
+      }
+      /** Load-bearing conclusions awaiting repair after a premise changed. */
+      async getStaleDerivations(limit = 50, offset = 0) {
+        return this.post("/retrieve", { action: "stale_derivations", limit, offset });
+      }
+      async getPendingApprovals() {
+        return this.get("/approvals/pending");
+      }
+      // ---- Ingestion & Retrieval ----
+      async ingestChunk(req) {
+        return this.post("/ingest/chunk", req);
+      }
+      async ingestDocument(req) {
+        return this.post("/ingest/document", req);
+      }
+      async ingestSession(req) {
+        return this.post("/ingest/session", req);
+      }
+      async retrieveContext(req) {
+        return this.post("/retrieve/context", req);
+      }
+      /** Backfill node_source provenance for existing graphs. */
+      async backfillNodeSources() {
+        return this.post("/backfill/node-sources", {});
+      }
+      /** Backfill citation anchors (source_chunks spans) for existing graphs. Returns a background job id. */
+      async backfillAnchors() {
+        return this.post("/backfill/anchors", {});
+      }
+      async listJobs() {
+        return this.get("/jobs");
+      }
+      async getJob(id) {
+        return this.get(`/jobs/${seg(id)}`);
+      }
+      async cancelJob(id) {
+        return this.post(`/jobs/${seg(id)}/cancel`, {});
+      }
+      /** Resume ingestion of a document that has failed chunks. */
+      async resumeDocument(docUid, opts) {
+        return this.post(`/ingest/resume/${seg(docUid)}`, opts ?? {});
+      }
+      /** Delete a document and all its chunks and extracted nodes. */
+      async deleteDocument(uid) {
+        return this.del(`/ingest/document/${seg(uid)}`);
+      }
+      async cleanupOrphans() {
+        return this.post("/ingest/cleanup", {});
+      }
+      async embedAll() {
+        return this.post("/ingest/embed-all", {});
+      }
+      async clearGraph() {
+        return this.post("/clear", {});
+      }
+      // ── Wiki ──────────────────────────────────────────────────────────────
+      /** List wiki articles with optional filters. */
+      async listArticles(params) {
+        const q = new URLSearchParams();
+        if (params?.article_type) q.set("article_type", params.article_type);
+        if (params?.covers_node_type) q.set("covers_node_type", params.covers_node_type);
+        if (params?.search) q.set("search", params.search);
+        if (params?.limit) q.set("limit", String(params.limit));
+        if (params?.offset) q.set("offset", String(params.offset));
+        return this.get(`/wiki/articles?${q}`);
+      }
+      /** Get a single wiki article by UID. */
+      async getArticle(uid) {
+        return this.get(`/wiki/article/${seg(uid)}`);
+      }
+      /** Find the article that covers or summarizes a given entity/document UID. */
+      async getArticleBySubject(subjectUid) {
+        try {
+          return await this.get(`/wiki/article/by-subject/${seg(subjectUid)}`);
+        } catch {
+          return null;
+        }
+      }
+      /** Update an article's markdown content (user editing). */
+      async updateArticle(uid, content) {
+        return this.patch(`/wiki/article/${seg(uid)}`, { content });
+      }
+      /** Trigger wiki compilation for a specific document. */
+      async compileDocument(docUid) {
+        return this.post(`/wiki/compile/${seg(docUid)}`, {});
+      }
+      /** Trigger wiki compilation for a specific entity. */
+      async compileEntity(entityUid) {
+        return this.post(`/wiki/compile/entity/${seg(entityUid)}`, {});
+      }
+      /** Backfill: compile articles for all documents and eligible entities. */
+      async compileAll() {
+        return this.post("/wiki/compile/all", {});
+      }
+      // ── Synthesis (Projects) ──────────────────────────────────────────────
+      /**
+       * Mine structural synthesis signals for a project's document corpus.
+       *
+       * Returns candidate surface for downstream synthesis — entity bridges
+       * across documents, claim hubs, clustered claim hubs, theory support
+       * gaps, concept clusters, analogy candidates, and dialectical pairs.
+       *
+       * Blocking operation. No LLM calls; Datalog + embedding clustering only.
+       */
+      async signals(projectUid, opts) {
+        const q = new URLSearchParams();
+        if (opts?.signals) q.set("signals", opts.signals);
+        if (opts?.target_types) q.set("target_types", opts.target_types);
+        const qs = q.toString();
+        return this.get(`/synthesis/signals/${seg(projectUid)}${qs ? `?${qs}` : ""}`);
+      }
+      /**
+       * Spawn a background synthesis job for a project: mines signals,
+       * selects top idea clusters, runs LLM synthesis, and persists
+       * candidate Article nodes linked via `Covers` edges.
+       *
+       * Returns a `job_id` immediately; poll `getJob(id)` for progress.
+       */
+      async runSynthesis(projectUid) {
+        return this.post(`/synthesis/run/${seg(projectUid)}`, {});
+      }
+      // ============================================================================
+      // Operational Ontology Layer (Layer 7)
+      // ============================================================================
+      // ---- Schema management (cloud Postgres) ----
+      async listOntologySchemas() {
+        return this.get("/v1/ontology/schemas");
+      }
+      async getOntologySchema(id) {
+        return this.get(`/v1/ontology/schemas/${seg(id)}`);
+      }
+      async createOntologySchema(req) {
+        return this.post("/v1/ontology/schemas", req);
+      }
+      async updateOntologySchema(id, req) {
+        return this.patch(`/v1/ontology/schemas/${seg(id)}`, req);
+      }
+      async activateOntologySchema(id) {
+        return this.post(`/v1/ontology/schemas/${seg(id)}/activate`, {});
+      }
+      async deprecateOntologySchema(id) {
+        return this.post(`/v1/ontology/schemas/${seg(id)}/deprecate`, {});
+      }
+      async archiveOntologySchema(id) {
+        return this.del(`/v1/ontology/schemas/${seg(id)}`);
+      }
+      /**
+       * Kick off an LLM-driven schema proposal job.
+       * Returns immediately with `{ schema_id, job_id }`; poll
+       * `getOntologySchema(schema_id)` for streaming progress.
+       */
+      async proposeOntologySchema(req) {
+        return this.post("/v1/ontology/propose-schema", req);
+      }
+      async testOntologySchema(id, opts) {
+        return this.post(`/v1/ontology/schemas/${seg(id)}/test`, opts ?? {});
+      }
+      // ---- Schema sub-resources ----
+      async addOntologyObjectType(schemaId, req) {
+        return this.post(`/v1/ontology/schemas/${seg(schemaId)}/object-types`, req);
+      }
+      async updateOntologyObjectType(schemaId, typeId, req) {
+        return this.patch(
+          `/v1/ontology/schemas/${seg(schemaId)}/object-types/${seg(typeId)}`,
+          req
+        );
+      }
+      async deleteOntologyObjectType(schemaId, typeId) {
+        return this.del(
+          `/v1/ontology/schemas/${seg(schemaId)}/object-types/${seg(typeId)}`
+        );
+      }
+      async addOntologyRelationType(schemaId, req) {
+        return this.post(`/v1/ontology/schemas/${seg(schemaId)}/relation-types`, req);
+      }
+      async updateOntologyRelationType(schemaId, typeId, req) {
+        return this.patch(
+          `/v1/ontology/schemas/${seg(schemaId)}/relation-types/${seg(typeId)}`,
+          req
+        );
+      }
+      async deleteOntologyRelationType(schemaId, typeId) {
+        return this.del(
+          `/v1/ontology/schemas/${seg(schemaId)}/relation-types/${seg(typeId)}`
+        );
+      }
+      /** Generate inert semantic classifications for individual human review. */
+      async analyzeOntologySemanticGuidance(schemaId) {
+        return this.post(
+          `/v1/ontology/schemas/${seg(schemaId)}/semantic-guidance/analyze`,
+          {}
+        );
+      }
+      /** Read-only exact-identity collision audit; never merges graph data. */
+      async auditOntologyDuplicates(schemaId) {
+        return this.post(`/v1/ontology/schemas/${seg(schemaId)}/duplicates/audit`, {});
+      }
+      // ---- Proposals ----
+      async listOntologyProposals(opts) {
+        const q = new URLSearchParams();
+        if (opts?.status) q.set("status", opts.status);
+        if (opts?.schema_id) q.set("schema_id", opts.schema_id);
+        if (opts?.object_type) q.set("object_type", opts.object_type);
+        if (opts?.proposal_type) q.set("proposal_type", opts.proposal_type);
+        if (opts?.extract_job_id) q.set("extract_job_id", opts.extract_job_id);
+        if (opts?.limit != null) q.set("limit", String(opts.limit));
+        if (opts?.offset != null) q.set("offset", String(opts.offset));
+        const qs = q.toString();
+        return this.get(`/v1/ontology/proposals${qs ? `?${qs}` : ""}`);
+      }
+      async getOntologyProposal(id) {
+        return this.get(`/v1/ontology/proposals/${seg(id)}`);
+      }
+      async patchOntologyProposal(id, req) {
+        return this.patch(`/v1/ontology/proposals/${seg(id)}`, req);
+      }
+      async approveOntologyProposal(id, opts) {
+        return this.post(`/v1/ontology/proposals/${seg(id)}/approve`, opts ?? {});
+      }
+      async rejectOntologyProposal(id, reason) {
+        return this.post(`/v1/ontology/proposals/${seg(id)}/reject`, { reason });
+      }
+      async applyOntologyProposal(id) {
+        return this.post(`/v1/ontology/proposals/${seg(id)}/apply`, {});
+      }
+      async batchApproveOntologyProposals(ids, feedback) {
+        return this.post("/v1/ontology/proposals/batch-approve", { ids, feedback });
+      }
+      async batchRejectOntologyProposals(ids, reason) {
+        return this.post("/v1/ontology/proposals/batch-reject", { ids, reason });
+      }
+      // ---- Retrieval (graph server) ----
+      async queryOntology(req) {
+        return this.post("/ontology/query", req);
+      }
+      async queryDomainStructured(req) {
+        return this.post("/ontology/query/structured", req);
+      }
+      async queryRelatedDomainObjects(req) {
+        return this.queryDomainStructured({
+          schema_id: req.schema_id,
+          select: req.far_type,
+          ...req.project_uid ? { project_uid: req.project_uid } : {},
+          anchor: { type: req.entry_type, uid: req.uid },
+          path: [{
+            relation: req.relation,
+            entry_role: req.entry_role
+          }],
+          ...req.where ? { where: req.where } : {},
+          ...req.include_provenance ? { include: { provenance: true } } : {},
+          page: {
+            ...req.limit != null ? { limit: req.limit } : {},
+            ...req.offset != null ? { offset: req.offset } : {}
+          }
+        });
+      }
+      /**
+       * Schema-qualified read-tool descriptors generated from every active
+       * ontology. Includes per-object discovery/point/context tools,
+       * relation-and-role-specific related tools, and one structured composite.
+       */
+      async listOntologyTools() {
+        return this.get("/v1/ontology/tools");
+      }
+      async getDomainObject(uid, binding) {
+        const query = new URLSearchParams();
+        if (binding) {
+          query.set("schema_id", binding.schema_id);
+          query.set("object_type", binding.object_type);
+          if (binding.project_uid) query.set("project_uid", binding.project_uid);
+        }
+        const suffix = query.size > 0 ? `?${query.toString()}` : "";
+        return this.get(`/ontology/object/${seg(uid)}${suffix}`);
+      }
+      async getDomainObjectContext(uid, depth, binding) {
+        const query = new URLSearchParams();
+        if (depth != null) query.set("depth", String(depth));
+        if (binding) {
+          query.set("schema_id", binding.schema_id);
+          query.set("object_type", binding.object_type);
+          if (binding.project_uid) query.set("project_uid", binding.project_uid);
+        }
+        const suffix = query.size > 0 ? `?${query.toString()}` : "";
+        return this.get(`/ontology/object/${seg(uid)}/context${suffix}`);
+      }
+      async getDomainObjectHistory(uid) {
+        return this.get(`/ontology/object/${seg(uid)}/history`);
+      }
+      async listDomainObjects(opts) {
+        const q = new URLSearchParams();
+        q.set("schema_id", opts.schema_id);
+        if (opts.object_type) q.set("object_type", opts.object_type);
+        if (opts.limit != null) q.set("limit", String(opts.limit));
+        if (opts.offset != null) q.set("offset", String(opts.offset));
+        if (opts.sort) q.set("sort", opts.sort);
+        return this.get(`/ontology/objects?${q.toString()}`);
+      }
+      async searchDomainObjects(query, opts) {
+        return this.post("/ontology/objects/search", { query, ...opts ?? {} });
+      }
+      /**
+       * Per-object-type coverage stats for a schema (C2f): field fill rates
+       * (with a `near_empty` flag < 5%) and identity collisions, over a bounded
+       * per-type sample (default 500, max 2000).
+       */
+      async ontologyStats(schemaId, sample) {
+        const q = new URLSearchParams({ schema_id: schemaId });
+        if (sample != null) q.set("sample", String(sample));
+        return this.get(`/ontology/stats?${q.toString()}`);
+      }
+      /**
+       * 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.
+       */
+      async createDomainObject(req) {
+        return this.post("/v1/ontology/objects", req);
+      }
+      async linkDomainObjects(req) {
+        return this.post("/ontology/relation", { action: "create", ...req });
+      }
+      // ---- Extraction ----
+      async extractOntology(req) {
+        return this.post("/ontology/extract", req);
+      }
+    };
+  }
+});
+
 // src/codegraph.ts
 function normalizePath(path6) {
   return path6.replaceAll("\\", "/").replace(/^\.\//, "");
@@ -712,17 +1601,16 @@ var init_codegraph = __esm({
 
 // src/error-detail.ts
 function errorDetail(e) {
-  if (e instanceof import_mindgraph.MindGraphError && e.body !== void 0) {
+  if (e instanceof MindGraphError && e.body !== void 0) {
     const detail = typeof e.body === "string" ? e.body : JSON.stringify(e.body);
     return `${e.message} \u2014 ${detail}`;
   }
   return e instanceof Error ? e.message : String(e);
 }
-var import_mindgraph;
 var init_error_detail = __esm({
   "src/error-detail.ts"() {
     "use strict";
-    import_mindgraph = require("mindgraph");
+    init_dist();
   }
 });
 
@@ -3874,14 +4762,14 @@ async function main() {
     `MindGraph MCP server v0.7.1 running on stdio (${BASE_URL})`
   );
 }
-var import_server, import_stdio, import_types, import_mindgraph2, API_KEY, BASE_URL, AGENT_ID, ORG_ID, PROFILE, HARNESS, client, INSTRUCTIONS, server, GOVERNANCE_CONFIG, PROMPTS;
+var import_server, import_stdio, import_types, API_KEY, BASE_URL, AGENT_ID, ORG_ID, PROFILE, HARNESS, client, INSTRUCTIONS, server, GOVERNANCE_CONFIG, PROMPTS;
 var init_src = __esm({
   "src/index.ts"() {
     "use strict";
     import_server = require("@modelcontextprotocol/sdk/server/index.js");
     import_stdio = require("@modelcontextprotocol/sdk/server/stdio.js");
     import_types = require("@modelcontextprotocol/sdk/types.js");
-    import_mindgraph2 = require("mindgraph");
+    init_dist();
     init_tools();
     init_generated_tools();
     init_governance();
@@ -3898,7 +4786,7 @@ var init_src = __esm({
       );
       process.exit(1);
     }
-    client = new import_mindgraph2.MindGraph({
+    client = new MindGraph({
       baseUrl: BASE_URL,
       apiKey: API_KEY,
       orgId: ORG_ID,
@@ -4005,7 +4893,7 @@ Capture knowledge when the user shares something worth remembering:
     server = new import_server.Server(
       {
         name: "mindgraph",
-        version: "0.14.2"
+        version: "0.14.4"
       },
       {
         capabilities: {
@@ -4228,7 +5116,7 @@ var path5 = __toESM(require("path"));
 var os4 = __toESM(require("os"));
 var crypto4 = __toESM(require("crypto"));
 var import_child_process = require("child_process");
-var import_mindgraph3 = require("mindgraph");
+init_dist();
 
 // src/hook-env.ts
 var import_node_fs = __toESM(require("fs"));
@@ -4243,7 +5131,8 @@ function loadHookEnv(dir) {
     const parsed = JSON.parse(raw);
     return {
       baseUrl: typeof parsed.baseUrl === "string" ? parsed.baseUrl : void 0,
-      apiKey: typeof parsed.apiKey === "string" ? parsed.apiKey : void 0
+      apiKey: typeof parsed.apiKey === "string" ? parsed.apiKey : void 0,
+      agentId: typeof parsed.agentId === "string" ? parsed.agentId : void 0
     };
   } catch {
     return {};
@@ -4255,7 +5144,8 @@ function saveHookEnv(env, dir) {
   const existing = loadHookEnv(dir);
   const merged = {
     baseUrl: env.baseUrl ?? existing.baseUrl,
-    apiKey: env.apiKey ?? existing.apiKey
+    apiKey: env.apiKey ?? existing.apiKey,
+    agentId: env.agentId ?? existing.agentId
   };
   import_node_fs.default.writeFileSync(file, `${JSON.stringify(merged, null, 2)}
 `, {
@@ -4275,6 +5165,7 @@ function parseArgs(argv) {
   let projectDir;
   let harness;
   let hooks = false;
+  let agentId = process.env.MINDGRAPH_AGENT_ID;
   for (let i = 0; i < args.length; i++) {
     const arg = args[i];
     switch (arg) {
@@ -4298,6 +5189,9 @@ function parseArgs(argv) {
       case "--harness":
         harness = args[++i];
         break;
+      case "--agent-id":
+        agentId = args[++i];
+        break;
       case "--hooks":
         hooks = true;
         break;
@@ -4315,7 +5209,7 @@ function parseArgs(argv) {
         break;
     }
   }
-  return { command, apiKey, baseUrl, scope, projectDir, harness, hooks };
+  return { command, apiKey, baseUrl, scope, projectDir, harness, hooks, agentId };
 }
 function mcpAddFailureOutput(e) {
   const err5 = e;
@@ -4960,7 +5854,7 @@ function installClaudeDesktop(apiKey, baseUrl) {
   }
   console.log("Restart Claude Desktop to activate.");
 }
-function installClaudeCode(apiKey, baseUrl) {
+function installClaudeCode(apiKey, baseUrl, agentId) {
   const envArgs = [
     `--env`,
     `MINDGRAPH_API_KEY=${apiKey}`,
@@ -4969,7 +5863,7 @@ function installClaudeCode(apiKey, baseUrl) {
     "--env",
     "MINDGRAPH_HARNESS=claude-code",
     "--env",
-    "MINDGRAPH_AGENT_ID=claude-code"
+    `MINDGRAPH_AGENT_ID=${agentId || "claude-code"}`
   ];
   if (baseUrl) {
     envArgs.push("--env", `MINDGRAPH_BASE_URL=${baseUrl}`);
@@ -5063,7 +5957,7 @@ function printStatus() {
 function withHooksFlag() {
   return process.argv.includes("--hooks");
 }
-function finishCodeInstall(apiKey, baseUrl, withHooks) {
+function finishCodeInstall(apiKey, baseUrl, withHooks, agentId) {
   if (withHooks) {
     const runner = installHookRunner(__filename);
     console.log(`Installed pinned hook runner at ${runner}`);
@@ -5071,7 +5965,7 @@ function finishCodeInstall(apiKey, baseUrl, withHooks) {
     console.log(
       `Installed ${result.added} and refreshed ${result.updated} MindGraph Claude Code hook entries in ${result.path}`
     );
-    const envPath = saveHookEnv({ apiKey, baseUrl });
+    const envPath = saveHookEnv({ apiKey, baseUrl, agentId });
     console.log(`Saved hook connection settings to ${envPath} (mode 600)`);
   } else {
     console.log(
@@ -5223,13 +6117,23 @@ async function interactiveInit(baseUrl) {
       installClaudeDesktop(apiKey, baseUrl);
       break;
     case "2":
-      installClaudeCode(apiKey, baseUrl);
-      finishCodeInstall(apiKey, baseUrl, withHooksFlag());
+      installClaudeCode(apiKey, baseUrl, process.env.MINDGRAPH_AGENT_ID);
+      finishCodeInstall(
+        apiKey,
+        baseUrl,
+        withHooksFlag(),
+        process.env.MINDGRAPH_AGENT_ID
+      );
       break;
     case "3":
       installClaudeDesktop(apiKey, baseUrl);
-      installClaudeCode(apiKey, baseUrl);
-      finishCodeInstall(apiKey, baseUrl, withHooksFlag());
+      installClaudeCode(apiKey, baseUrl, process.env.MINDGRAPH_AGENT_ID);
+      finishCodeInstall(
+        apiKey,
+        baseUrl,
+        withHooksFlag(),
+        process.env.MINDGRAPH_AGENT_ID
+      );
       break;
     default:
       console.error("Invalid choice.");
@@ -5238,7 +6142,7 @@ async function interactiveInit(baseUrl) {
   console.log("\nDone! Your knowledge graph is now connected.");
 }
 async function main2() {
-  const { command, apiKey, baseUrl, scope, projectDir, harness, hooks } = parseArgs(process.argv);
+  const { command, apiKey, baseUrl, scope, projectDir, harness, hooks, agentId } = parseArgs(process.argv);
   switch (command) {
     case "help":
       printUsage();
@@ -5262,8 +6166,8 @@ async function main2() {
         );
         process.exit(1);
       }
-      installClaudeCode(apiKey, baseUrl);
-      finishCodeInstall(apiKey, baseUrl, withHooksFlag());
+      installClaudeCode(apiKey, baseUrl, agentId);
+      finishCodeInstall(apiKey, baseUrl, withHooksFlag(), agentId);
       break;
     case "uninstall":
       uninstallClaudeDesktop();
@@ -5281,8 +6185,8 @@ async function main2() {
       console.log(
         `Installed ${result.added} and refreshed ${result.updated} MindGraph Claude Code hook entries in ${result.path}`
       );
-      if (apiKey || baseUrl) {
-        const envPath = saveHookEnv({ apiKey, baseUrl });
+      if (apiKey || baseUrl || agentId) {
+        const envPath = saveHookEnv({ apiKey, baseUrl, agentId });
         console.log(`Saved hook connection settings to ${envPath} (mode 600)`);
       } else {
         console.log(
@@ -5312,7 +6216,7 @@ async function main2() {
       }
       try {
         const input = await readHookInput();
-        const client2 = new import_mindgraph3.MindGraph({
+        const client2 = new MindGraph({
           baseUrl: hookBaseUrl || "https://api.mindgraph.cloud",
           apiKey: hookApiKey,
           orgId: process.env.MINDGRAPH_ORG_ID,
@@ -5320,7 +6224,7 @@ async function main2() {
           telemetrySurface: "mcp"
         });
         const output = await runClaudeHook(input, client2, {
-          agentId: process.env.MINDGRAPH_AGENT_ID || "claude-code"
+          agentId: process.env.MINDGRAPH_AGENT_ID || stored.agentId || "claude-code"
         });
         process.stdout.write(`${JSON.stringify(output)}
 `);

package/dist/index.js

@@ -3931,7 +3931,7 @@ if (PROFILE === "coding") {
 var server = new import_server.Server(
   {
     name: "mindgraph",
-    version: "0.14.2"
+    version: "0.14.4"
   },
   {
     capabilities: {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mindgraph-mcp",
-  "version": "0.14.2",
+  "version": "0.14.4",
   "description": "MCP server for MindGraph — connect Claude Desktop, Claude Code, and any MCP client to your knowledge graph",
   "repository": {
     "type": "git",