mindgraph-mcp 0.20.0 → 0.22.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 |
@@ -286,6 +287,35 @@ lifecycle observation, context delivery, and managed curation.
 
 Search strategy is **keyword-first**: `mindgraph_retrieve` defaults to `action: "context"`, which seeds bounded cheapest-first graph expansion from BM25/hybrid recall. Escalate to `semantic` or `hybrid` only when keywords fail. Set `graph_expansion_limit: 0` when direct-only retrieval is required. For model-facing reads, `max_output_chars` bounds the rendered response from 512 to 24,000 characters while preserving whole evidence items and reporting omissions; `format: "json"` deliberately bypasses that rendering contract.
 
+## Hosted mode
+
+The same tool surface is importable as a library for a hosted Streamable HTTP
+endpoint (the `https://mindgraph.cloud/mcp` connector that claude.ai, Claude
+Code, ChatGPT and Cursor sign in to with OAuth). `mindgraph-mcp/server` exports
+a per-request factory and has no load-time side effects — it never exits for a
+missing key or touches hook files:
+
+```ts
+import { handleHostedRequest } from "mindgraph-mcp/server";
+
+// After the route has verified the OAuth bearer and exchanged it for an API token:
+return handleHostedRequest(request, {
+  client, bearer, baseUrl, orgId, orgName, agentId: `mcp:${clientHost}:${userId}`,
+  user: { id: userId, name, email },
+  profile: "general", harness: "hosted", serverVersion,
+  caches, // { generatedTools: Map, governance: Map } — one entry per org, kept by the route
+});
+```
+
+Hosted mode serves the `general` profile plus the org's generated ontology
+tools and three extra tools — `search`, `fetch` (the ChatGPT connector
+contract, `structuredContent` + text twin) and `whoami` — each annotated and
+carrying `_meta.securitySchemes` with its `graph:read` / `graph:write` /
+`graph:evolve` scope. The signed-in member's identity overwrites `agent_id`
+on every call; a model-supplied value is kept only as `requested_agent_id`
+metadata. `mindgraph_code`, `mindgraph_sync` and hook installation are stdio-only.
+The HTTP auth gate (401/403) is the route's job, not the library's.
+
 ## Development
 
 ```bash
@@ -300,3 +330,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.