mindgraph-mcp 0.16.0 → 0.18.0

package/README.md

@@ -88,6 +88,57 @@ cleanly. Connection settings persist to `~/.mindgraph/hooks.json` (mode 600) so
 hooks work regardless of shell environment; the API key is never written into
 project settings.
 
+**Updates are hands-free.** The MCP registration floats on `npx @latest`,
+and at startup the server self-heals the pinned hook runner from its own
+bundle — upgrade-only (never a downgrade from a stale npx cache), atomic,
+and only on machines that already have hooks installed. When it refreshes
+the runner it also re-writes MindGraph-owned hook entries (timeout budgets,
+new events) in settings files that already carry them — your scope choice is
+respected, never expanded. So after a release, the next session start picks
+up the new server and refreshes the hooks; the session after that runs them.
+Opt out with `MINDGRAPH_HOOK_AUTOUPDATE=off` (the server then just prints a
+version-skew note and leaves updating to `install-hooks`).
+
+### Multi-repository workspaces
+
+Working across sibling repositories (a parent directory holding several
+checkouts)? Declare them once in `.mindgraph/workspace.json` at the parent:
+
+```json
+{
+  "v": 1,
+  "workspace_id": "my-workspace",
+  "repositories": [
+    { "root": "engine", "repo_id": "github.com/acme/engine", "space_uid": "space:project:engine" },
+    { "root": "core", "space_uid": "space:project:core" }
+  ]
+}
+```
+
+- **Discovery** walks up from the invocation directory to the nearest
+  `.mindgraph/workspace.json` (override with `MINDGRAPH_WORKSPACE_FILE`).
+  `root` paths are relative to the directory containing `.mindgraph`. Only
+  declared repositories participate — siblings are never scanned implicitly.
+- **Routing**: a code ref with a `path` routes to the repository defining that
+  file (nearest declared root, else its git root). A `repo` argument matches by
+  declared `repo_id`, root path, or directory basename. Bare symbol refs
+  resolve against the current repository only — pass `path` or `repo` to
+  target a sibling. An id that matches nothing errors (`unknown_repository`)
+  rather than guessing.
+- **Identity**: `repo_id` defaults to the normalized origin remote
+  (`github.com/acme/engine`), so teammates' clones converge on the same graph
+  entities; clones without a remote get a durable generated id.
+- **Spaces**: each repository's anchors are written into its `space_uid`.
+  Anchoring requires an explicit space — per-repo `space_uid`, a
+  `repo_space_uid` argument, or `MINDGRAPH_CODE_SPACE_UID` — so shared code
+  identity never lands silently in a private per-agent space.
+- **Memory-file sync**: `mindgraph_sync action=scan workspace=true` fans out
+  across the declared repositories (and errors with a diagnostic when nothing
+  is declared); all other sync actions stay single-repository.
+- **Precedence**: the legacy `MINDGRAPH_CODE_REPOS` env map (`{"repo-id":
+  {"root": "...", "space_uid": "..."}}`) merges over workspace-file entries
+  for the same root.
+
 ### Coding agents (Codex)
 
 Codex gets the same durable work substrate through its native command hooks.
@@ -133,9 +184,9 @@ profile):
 | `mindgraph_commit` | Goals, projects, decisions, options, milestones, and dated decision-context linkage |
 | `mindgraph_plan` | Plans, tasks, procedures, governance policies, risk assessments, executions |
 | `mindgraph_retrieve` | Context retrieval with bounded graph expansion, search, min-cost traversal, document index. Since 0.16.0, read results return as a rendered, token-bounded text block (labels, uids, summaries, epistemic status tags, relationships) — pass `format: "json"` on any call for the raw server response |
-| `mindgraph_ingest` | Chunk / document / session ingestion with LLM-powered extraction |
-| `mindgraph_synthesize` | Project-scoped cross-document synthesis — mine signals, spawn Article-generation jobs |
-| `mindgraph_ontology` | Operational Ontology (Layer 7) — typed domain objects, NL queries with provenance, extraction proposal review (approve/reject), object linking |
+| `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 |
+| `mindgraph_ontology` | Operational Ontology (Layer 7) — typed domain objects, NL queries with provenance, extraction proposal review (approve/reject), object linking. Read actions render as text since 0.17.0 (`format: "json"` for raw) |
 | `mindgraph_code` *(coding profile)* | Identity-stable code anchors + live structural federation: `anchor`/`recall`/`expand`/`affected` over a local codegraph index — what the graph knows about this code, joined to who calls it |
 | `mindgraph_sync` *(coding profile)* | Idempotent, resumable import of markdown memory files (`.claude/agent-memory/**` etc.) with content-hash drift tracking, conflict surfacing, and a retirement report |
 
@@ -145,7 +196,7 @@ composites: `resume_work` (deterministic bounded brief), `claim_task` /
 `block_task` / `complete_task` / `abandon_iteration` (idempotent material
 attempts with version conflict detection).
 
-Plus **dynamically generated read tools**: when the tenant's active schema declares object types, the server renders per-type `search_<objs>` / `get_<obj>` / `summarize_<obj>` tools (from the cloud's `GET /v1/ontology/tools` manifest) at session start. `summarize_<obj>` returns the object — whether mapped from a connected SQL database or extracted from documents — *plus* its cognitive context (claims, risks, decisions, evidence).
+Plus **dynamically generated read tools**: when the tenant's active schema declares object types, the server renders per-type `search_<objs>` / `get_<obj>` / `summarize_<obj>` tools (from the cloud's `GET /v1/ontology/tools` manifest) at session start. `summarize_<obj>` returns the object — whether mapped from a connected SQL database or extracted from documents — *plus* its cognitive context (claims, risks, decisions, evidence). Since 0.17.0 these read tools render as text by default (pass `format: "json"` for the raw response); `related_*` tools follow the same contract, and `structured_query_*` composites always return raw rows.
 
 **7 prompt templates** for common workflows:
 
@@ -192,6 +243,8 @@ teammates one logical agent, which claims each other's work).
 | `MINDGRAPH_AGENT_ID` | *(stable per-user id)* | Agent identity stamped on every write and used for durable-work leases. Defaults to a stable `u-<hash>` derived from user@host, shared by the hooks, the registration, and the serve path — set explicitly for cross-device continuity or per-teammate identities |
 | `MINDGRAPH_ORG_ID` | *(unset)* | Pin operations to a specific organization when a key has access to more than one |
 | `MINDGRAPH_CODEGRAPH_BIN` | *(auto)* | Explicit path to the codegraph binary (PATH and `~/.local/bin` are probed) |
+| `MINDGRAPH_HOOK_AUTOUPDATE` | *(on)* | `off` disables the server's startup self-heal of the pinned hook runner; the version-skew note then signals drift instead |
+| `MINDGRAPH_SKIP_MCP_REGISTRATION_CHECK` | *(unset)* | `1` silences the SessionStart warning for hooks running without a registered MindGraph MCP server (exotic registration layouts) |
 
 ## Usage in Claude