mindgraph-mcp 0.17.0 → 0.19.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.
@@ -123,16 +174,17 @@ and never block the coding session.
 
 ## What You Get
 
-**8 tools** covering the full knowledge-graph workflow (**10** in the coding
+**9 tools** covering the full knowledge-graph workflow (**11** in the coding
 profile):
 
 | Tool | Purpose |
 |------|---------|
-| `mindgraph_capture` | Entities, observations, sources, snippets, concepts, journal entries |
+| `mindgraph_capture` | Entities, observations, sources, snippets, concepts, journals, lessons, governed skill candidates |
 | `mindgraph_reason` | Claims with evidence, open questions, hypotheses, theories, anomalies |
 | `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_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 |
 | `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) |
@@ -169,6 +221,8 @@ mindgraph-mcp uninstall        Remove from Claude Desktop config
 mindgraph-mcp uninstall-code   Remove from Claude Code
 mindgraph-mcp install-hooks    Install coding hooks (--harness claude-code|codex)
 mindgraph-mcp uninstall-hooks  Remove MindGraph-owned hook entries
+mindgraph-mcp skills pull      Render published and granted skills into local SKILL.md directories
+mindgraph-mcp skills push      Import or update one local SKILL.md as a governed candidate
 mindgraph-mcp status           Show installation status
 ```
 
@@ -192,6 +246,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