@staix/vault-mem 0.7.0 → 0.8.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/CHANGELOG.md CHANGED
@@ -2,6 +2,12 @@
2
2
 
3
3
  ## [Unreleased]
4
4
 
5
+ ## [0.8.0] - 2026-11-12
6
+
7
+ - N-1: 0.7.0 runs beside 0.8.0 without either version rebuilding the other's derived state or rewriting the other's configuration: both use the same note and spec index files (`links2-schema4`, schema 4) and config format 4, and note/spec files stay shared. Link resolution is unchanged, the pinned MCP `initialize` instructions are the same bytes, and no receipt field or error code changes. The surface only gains the CLI `graph path` and the read-only MCP `vmem_graph_path` (37 -> 38 tools), and the only other observable difference is message text: the `graph: use build ...` usage line and the `--relation` option-scope message now also name `graph path`, so a 0.7.0 client sees the same results for every command and tool it already calls.
8
+
9
+ - Add `vmem graph path` and read-only `vmem_graph_path`: the shortest undirected link path between two notes from the live index (breadth-first, code-point tie order, `moc`/`bu` hubs not used as intermediate steps unless `--via-hubs`/`viaHubs`, optional relation filter, `--max-hops` 1..6). No path within the limit is `found: false`, not an error (#211).
10
+
5
11
  ## [0.7.0] - 2026-11-11
6
12
 
7
13
  - N-1: 0.6.0 runs beside 0.7.0 without either version rebuilding the other's derived state or rewriting the other's configuration: both use the same note and spec index files (`links2-schema4`, schema 4) and config format 4, and note/spec files stay shared. The command set only gains `vmem brief` / `vmem_brief`, and the pinned MCP `initialize` instructions are the same bytes, but receipts a client reads change: `vmem_promote` and `vmem_promote_from_amem` omit `refused: true` when the receipt is applied with errors, the amem promotion receipt reports `applied: true` once the note was written, rollback receipts mark which paths stayed applied and keep the original forward cause instead of the rollback drift, a publication-path permission, storage or descriptor failure is `IO` rather than `V09` (note writes) or `DRIFT` (spec writes), and `LINK` is reserved for the native hard-link operation, so a client keyed on `refused`, `applied` or those codes needs 0.7.0.
package/README.md CHANGED
@@ -67,7 +67,7 @@ The only runtime dependency is the exact first-party pin <!-- facts:amem-pin -->
67
67
  - `src/commands-table.ts`: `COMMANDS`, `completionDefinitions`, `completionScript`
68
68
  - `src/promote.ts`: `promoteFromAmem`, `listPromotionCandidates`, `draftNote`, `stemFor`, `logProjectFor`
69
69
  - `src/vault-lint.ts`: `lintVault`
70
- - `src/vault-graph.ts`: `buildGraph`, `graphNeighbors`, `graphReport`
70
+ - `src/vault-graph.ts`: `buildGraph`, `graphNeighbors`, `graphPath`, `graphReport`
71
71
  - `src/analysis-reports.ts`: `writeAnalysisReports`
72
72
  - `src/org-promote.ts`: `promoteToOrg`, `screenForOrg`, `dropUnresolvedLinks`, `lintPromoted`
73
73
  - `src/sync.ts`: `syncVault`, `sameRemote`
@@ -274,7 +274,7 @@ The vault set is read once at startup: every tool's `vault` property is an enum
274
274
 
275
275
  <!-- facts:mcp-tools -->
276
276
 
277
- `vmem mcp` lists 37 tools: `vmem_status`, `vmem_search`, `vmem_brief`, `vmem_read`, `vmem_read_many`, `vmem_list`, `vmem_links`, `vmem_mocs`, `vmem_check`, `vmem_log_tail`, `vmem_create`, `vmem_patch`, `vmem_append`, `vmem_set_frontmatter`, `vmem_link`, `vmem_supersede`, `vmem_log_append`, `vmem_move`, `vmem_merge`, `vmem_delete`, `vmem_promote_from_amem`, `vmem_lint`, `vmem_graph_build`, `vmem_graph_neighbors`, `vmem_promote`, `vmem_skills_mine`, `vmem_read_file`, `vmem_list_files`, `vmem_report`, `vmem_stats`, `vmem_spec_get`, `vmem_spec_graph`, `vmem_spec_grep`, `vmem_spec_validate`, `vmem_spec_create`, `vmem_spec_update`, `vmem_spec_delete`.
277
+ `vmem mcp` lists 38 tools: `vmem_status`, `vmem_search`, `vmem_brief`, `vmem_read`, `vmem_read_many`, `vmem_list`, `vmem_links`, `vmem_mocs`, `vmem_check`, `vmem_log_tail`, `vmem_create`, `vmem_patch`, `vmem_append`, `vmem_set_frontmatter`, `vmem_link`, `vmem_supersede`, `vmem_log_append`, `vmem_move`, `vmem_merge`, `vmem_delete`, `vmem_promote_from_amem`, `vmem_lint`, `vmem_graph_build`, `vmem_graph_neighbors`, `vmem_graph_path`, `vmem_promote`, `vmem_skills_mine`, `vmem_read_file`, `vmem_list_files`, `vmem_report`, `vmem_stats`, `vmem_spec_get`, `vmem_spec_graph`, `vmem_spec_grep`, `vmem_spec_validate`, `vmem_spec_create`, `vmem_spec_update`, `vmem_spec_delete`.
278
278
 
279
279
  <!-- /facts:mcp-tools -->
280
280
 
@@ -341,7 +341,7 @@ Rows and `canonTableWarnings` are advisory, outside the fingerprint: changing `c
341
341
 
342
342
  `vmem lint <vault>` checks L01/L02/L03/L09/L10/L11/L12 and L13 (lowercase ASCII kebab-case filenames). An L01 finding for a dead link adds at most one suggested existing target and its title score, dropped when no title scores above the minimum; the hint is reported and the link is never rewritten. Hints are computed for at most 1000 distinct dead link texts per run: a text past that bound is reported as `hint not computed (cap 1000)` with the count left out, never as a missing match. L15 is a warning, not a write error: a note with `confidence: proven` and an empty `source` (absent, empty string or empty list) is listed with what to add, and existing notes are never refused. `--note notes/example.md` limits note findings. Section names and `SUMMARY errors=N warnings=N` follow the Python reference. `--write` writes a screened lint report and LINT event; `--dry-run` previews without persistence. Findings may identify paths, link targets and malformed log prefixes. Note bodies are never included in analysis results.
343
343
 
344
- `vmem graph build <vault> [--dry-run]` writes `reports/vault-graph.json`, a dated graph report, graph trend history and GRAPH events through `applyWrite`. Old dated reports are preserved. Trend history appends one row per build, including repeated builds on the same date. Output receipts expose partial report/log failure; these separate writes are not a single transaction. A `- [[x]] (relation)` line written by `vmem link --relation` keeps its relation as `rel` on the `wiki_link` edge (`supports`, `contradicts`, `extends`, `applies-to`, `context-for`); other links carry no `rel`. Edges stay undirected, so `rel` does not say which note supports which, and when a pair carries different relations the first in note path order is kept. `vmem graph neighbors <vault> <stem> [--hops 1..2] [--limit 1..500] [--relation REL]` reads a bounded neighborhood; `--relation` (MCP `relation`) follows only edges of that relation, `wiki_link` meaning untyped links, and an unknown relation is refused. Matching MCP tools are `vmem_lint`, `vmem_graph_build`, and `vmem_graph_neighbors`; MCP report writes require `write=mcp`.
344
+ `vmem graph build <vault> [--dry-run]` writes `reports/vault-graph.json`, a dated graph report, graph trend history and GRAPH events through `applyWrite`. Old dated reports are preserved. Trend history appends one row per build, including repeated builds on the same date. Output receipts expose partial report/log failure; these separate writes are not a single transaction. A `- [[x]] (relation)` line written by `vmem link --relation` keeps its relation as `rel` on the `wiki_link` edge (`supports`, `contradicts`, `extends`, `applies-to`, `context-for`); other links carry no `rel`. Edges stay undirected, so `rel` does not say which note supports which, and when a pair carries different relations the first in note path order is kept. `vmem graph neighbors <vault> <stem> [--hops 1..2] [--limit 1..500] [--relation REL]` reads a bounded neighborhood; `--relation` (MCP `relation`) follows only edges of that relation, `wiki_link` meaning untyped links, and an unknown relation is refused. `vmem graph path <vault> <from> <to> [--max-hops 1..6] [--relation REL] [--via-hubs]` reads the shortest path between two notes from the live index: breadth-first over the same undirected edges, neighbours in code-point order so equal-length ties resolve the same way every run. `moc`/`bu` hubs are not used as intermediate steps unless `--via-hubs` (either endpoint may be a hub). The result is `{from, to, found, length, nodes, edges}` with one edge per step; no path within `--max-hops` (default 6) is `found: false`, not an error. Unknown notes, relations and out-of-range hops are refused as for `graph neighbors`. Matching MCP tools are `vmem_lint`, `vmem_graph_build`, `vmem_graph_neighbors` and `vmem_graph_path`; MCP report writes require `write=mcp`.
345
345
 
346
346
  **Communities** come from a deterministic, dependency-free Leiden (Traag, Waltman and van Eck 2019) optimizing modularity with resolution γ = 1.0: fast local moving with a node queue, refinement that merges only well-connected nodes inside each community (the greedy variant, so no random step), and aggregation on the refined partition initialized from the unrefined one, repeated while modularity improves. Nodes are processed in code-point id order and gain ties go to the lowest community id, so the same graph gives byte-identical output whatever the input order. Every community induces a connected subgraph. MOC (and, in the workspace graph, `bu`) nodes are excluded and get `community: null`; an isolated note is its own community. Community ids are numbered by size (descending), then by smallest member id; they are build-local, so cite a member, not the id. `vault-graph.json` records `graph.partitioner: "leiden"`, `resolution`, the achieved `modularity` and the number of levels, and the report Overview prints the partitioner, resolution and modularity. Modularity has a resolution limit: communities smaller than a size that grows with the whole graph cannot be separated, so a very small cluster may merge into a neighbor. There is no resolution setting yet. Skill mining (`vmem skills mine`) and the workspace graph use the same function. `bun scripts/leiden-live.ts <vault-id>` prints counts only: modularity, community count, largest share, connectivity, clustering time and NMI against the Python reference's Leiden partition.
347
347
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@staix/vault-mem",
3
- "version": "0.7.0",
3
+ "version": "0.8.0",
4
4
  "description": "Validated Obsidian-compatible knowledge vaults for agents and people",
5
5
  "license": "MIT",
6
6
  "type": "module",
@@ -1,12 +1,12 @@
1
1
  import { analysisInput } from "./analysis-input.ts";
2
2
  import { lintDetails } from "./vault-lint.ts";
3
- import { analysisWriteText, lintText, neighborsText } from "./read-output.ts";
4
- import { buildGraph, graphNeighbors } from "./vault-graph.ts";
3
+ import { analysisWriteText, lintText, neighborsText, pathText } from "./read-output.ts";
4
+ import { buildGraph, graphNeighbors, graphPath } from "./vault-graph.ts";
5
5
  import { writeAnalysisReports } from "./analysis-reports.ts";
6
6
  import { PLAIN, type TextOptions } from "./text-output.ts";
7
7
 
8
8
  const OPTION_SCOPE: Record<string, string> = {
9
- "--hops": "graph neighbors", "--limit": "graph neighbors", "--relation": "graph neighbors",
9
+ "--hops": "graph neighbors", "--limit": "graph neighbors", "--relation": "graph neighbors and graph path", "--max-hops": "graph path", "--via-hubs": "graph path",
10
10
  "--note": "lint", "--write": "lint", "--workspace": "graph build", "--dry-run": "lint --write and graph build",
11
11
  };
12
12
  export function runAnalysisCommand(command: string, args: string[], home: string, env: NodeJS.ProcessEnv = process.env, text: TextOptions = PLAIN): { text: string; code: number } {
@@ -15,13 +15,13 @@ export function runAnalysisCommand(command: string, args: string[], home: string
15
15
  const word = args[i]!;
16
16
  if (!word.startsWith("-")) { positional.push(word); continue; }
17
17
  if (word in values || flags.has(word)) throw new Error("analysis: repeated option");
18
- if (["--json","--dry-run","--write","--workspace"].includes(word)) flags.add(word);
19
- else if (["--note","--hops","--limit","--relation"].includes(word)) { const value = args[++i]; if (!value || value.startsWith("--")) throw new Error(`${word}: requires value`); values[word]=value; }
18
+ if (["--json","--dry-run","--write","--workspace","--via-hubs"].includes(word)) flags.add(word);
19
+ else if (["--note","--hops","--limit","--relation","--max-hops"].includes(word)) { const value = args[++i]; if (!value || value.startsWith("--")) throw new Error(`${word}: requires value`); values[word]=value; }
20
20
  else throw new Error(`analysis: unknown option ${word}`);
21
21
  }
22
22
  // An option the subcommand does not take is named with where it applies, before any positional check.
23
23
  const subcommand = command === "lint" ? "lint" : `graph ${positional[0] ?? ""}`.trim();
24
- const accepted = command === "lint" ? ["--json", "--dry-run", "--write", "--note"] : positional[0] === "build" ? ["--json", "--dry-run", "--workspace"] : positional[0] === "neighbors" ? ["--json", "--hops", "--limit", "--relation"] : undefined;
24
+ const accepted = command === "lint" ? ["--json", "--dry-run", "--write", "--note"] : positional[0] === "build" ? ["--json", "--dry-run", "--workspace"] : positional[0] === "neighbors" ? ["--json", "--hops", "--limit", "--relation"] : positional[0] === "path" ? ["--json", "--max-hops", "--relation", "--via-hubs"] : undefined;
25
25
  if (accepted) for (const option of [...flags, ...Object.keys(values)]) if (!accepted.includes(option)) throw new Error(`${subcommand}: ${option} applies only to ${OPTION_SCOPE[option]}`);
26
26
  if (command === "lint") {
27
27
  if (positional.length !== 1) throw new Error("lint: requires one vault id");
@@ -36,7 +36,16 @@ export function runAnalysisCommand(command: string, args: string[], home: string
36
36
  const result = writeAnalysisReports(home,{vault:positional[0]!,kind:"graph",workspace:flags.has("--workspace"),dryRun:flags.has("--dry-run")},env);
37
37
  return {text:flags.has("--json") ? JSON.stringify(result) : analysisWriteText(result,text,{kind:"graph",dryRun:flags.has("--dry-run")}),code:result.ok ? 0 : 1};
38
38
  }
39
- if (action !== "neighbors" || positional.length !== 2) throw new Error("graph: use build <vault> or neighbors <vault> <stem>");
39
+ if (action === "path") {
40
+ if (positional.length !== 3) throw new Error("graph path: requires <vault> <from> <to>");
41
+ const maxHops = Number(values["--max-hops"] ?? 6);
42
+ if (!Number.isInteger(maxHops) || maxHops < 1 || maxHops > 6) throw new Error("graph path: max hops 1..6");
43
+ const {snapshot} = analysisInput(home,positional[0]!);
44
+ const viaHubs = flags.has("--via-hubs"), relation = values["--relation"];
45
+ const result = graphPath(buildGraph(snapshot),positional[1]!,positional[2]!,{maxHops,viaHubs,...(relation === undefined ? {} : {relation})});
46
+ return {text:flags.has("--json") ? JSON.stringify(result) : pathText(result,text,{vault:positional[0]!,maxHops,viaHubs,relation}),code:0};
47
+ }
48
+ if (action !== "neighbors" || positional.length !== 2) throw new Error("graph: use build <vault>, neighbors <vault> <stem> or path <vault> <from> <to>");
40
49
  const hops = Number(values["--hops"] ?? 1), limit = Number(values["--limit"] ?? 50);
41
50
  if ((hops !== 1 && hops !== 2) || !Number.isInteger(limit) || limit < 1 || limit > 500) throw new Error("graph neighbors: hops 1..2, limit 1..500");
42
51
  const {snapshot} = analysisInput(home,positional[0]!);
@@ -19,6 +19,7 @@ export const COMMANDS = [
19
19
  { name: "lint", usage: "lint <vault> [--note PATH] [--write] [--dry-run] [--json]", mutates: "write", section: "Analysis", description: "lint links, schema, filenames and the log; --write saves a screened report" },
20
20
  { name: "graph build", usage: "graph build <vault> [--workspace] [--dry-run] [--json]", mutates: true, section: "Analysis", description: "build the vault graph, or the workspace graph with --workspace, under reports/" },
21
21
  { name: "graph neighbors", usage: "graph neighbors <vault> <stem> [--hops 1..2] [--limit 1..500] [--relation REL] [--json]", mutates: false, section: "Analysis", description: "read a note's graph neighborhood up to two hops, optionally over one link relation" },
22
+ { name: "graph path", usage: "graph path <vault> <from> <to> [--max-hops 1..6] [--relation REL] [--via-hubs] [--json]", mutates: false, section: "Analysis", description: "read the shortest link path between two notes, skipping MOC/bu hubs unless --via-hubs" },
22
23
  { name: "skills mine", usage: "skills mine <vault> [--days N] [--project KEY|--all-projects] [--vocab DIR] [--skills DIR] [--min-size N] [--min-novelty X] [--json]", mutates: false, section: "Analysis", description: "rank repeated work patterns in agent memory as new-skill candidates" },
23
24
  { name: "rebuild", usage: "rebuild <vault> [--json]", mutates: "cache", section: "Read", description: "rebuild the derived search index from the vault files" },
24
25
  { name: "brief", usage: "brief <vault> --for INTENT [--paths PATH]... [--bytes 256..4096] [--json]", mutates: "cache", section: "Read", description: "rank screened note pointers and one-hop neighbors within a byte cap" },
@@ -101,7 +102,7 @@ export function completionScript(shell: string): string {
101
102
  cur="\${COMP_WORDS[COMP_CWORD]}"
102
103
  if [ "$COMP_CWORD" -eq 1 ]; then COMPREPLY=($(compgen -W ${quote(top.join(" "))} -- "$cur")); return; fi
103
104
  key="\${COMP_WORDS[1]}"
104
- case "$key" in spec) if [ "$COMP_CWORD" -eq 2 ]; then COMPREPLY=($(compgen -W '${SPEC_COMMANDS.map(item => item.command).join(" ")}' -- "$cur")); return; fi; key="$key \${COMP_WORDS[2]}" ;; graph) if [ "$COMP_CWORD" -eq 2 ]; then COMPREPLY=($(compgen -W 'build neighbors' -- "$cur")); return; fi; key="$key \${COMP_WORDS[2]}" ;; skills) if [ "$COMP_CWORD" -eq 2 ]; then COMPREPLY=($(compgen -W 'mine' -- "$cur")); return; fi; key="$key \${COMP_WORDS[2]}" ;; specs) if [ "$COMP_CWORD" -eq 2 ]; then COMPREPLY=($(compgen -W 'list add remove' -- "$cur")); return; fi; key="$key \${COMP_WORDS[2]}" ;; vaults|log) if [ "$COMP_CWORD" -eq 2 ]; then COMPREPLY=($(compgen -W "$( [ "$key" = vaults ] && echo 'list add remove' || echo 'tail grep append')" -- "$cur")); return; fi; key="$key \${COMP_WORDS[2]}" ;; esac
105
+ case "$key" in spec) if [ "$COMP_CWORD" -eq 2 ]; then COMPREPLY=($(compgen -W '${SPEC_COMMANDS.map(item => item.command).join(" ")}' -- "$cur")); return; fi; key="$key \${COMP_WORDS[2]}" ;; graph) if [ "$COMP_CWORD" -eq 2 ]; then COMPREPLY=($(compgen -W 'build neighbors path' -- "$cur")); return; fi; key="$key \${COMP_WORDS[2]}" ;; skills) if [ "$COMP_CWORD" -eq 2 ]; then COMPREPLY=($(compgen -W 'mine' -- "$cur")); return; fi; key="$key \${COMP_WORDS[2]}" ;; specs) if [ "$COMP_CWORD" -eq 2 ]; then COMPREPLY=($(compgen -W 'list add remove' -- "$cur")); return; fi; key="$key \${COMP_WORDS[2]}" ;; vaults|log) if [ "$COMP_CWORD" -eq 2 ]; then COMPREPLY=($(compgen -W "$( [ "$key" = vaults ] && echo 'list add remove' || echo 'tail grep append')" -- "$cur")); return; fi; key="$key \${COMP_WORDS[2]}" ;; esac
105
106
  case "$key" in
106
107
  ${cases.join("\n")}
107
108
  *) words='' ;;
package/src/index.ts CHANGED
@@ -28,7 +28,7 @@ export type { AmemSeam, AmemCandidate, AmemOptions } from "./amem/seam.ts";
28
28
 
29
29
 
30
30
  export { lintVault } from "./vault-lint.ts";
31
- export { buildGraph, graphNeighbors, graphReport } from "./vault-graph.ts";
31
+ export { buildGraph, graphNeighbors, graphPath, graphReport } from "./vault-graph.ts";
32
32
  export type { VaultGraph, GraphNeighborhood } from "./vault-graph.ts";
33
33
  export type { AnalysisSnapshot, LintCode, LintReport } from "./analysis-types.ts";
34
34
  export { writeAnalysisReports } from "./analysis-reports.ts";
package/src/mcp-vault.ts CHANGED
@@ -2,7 +2,7 @@ import { vaultBrief } from "./vault-brief.ts";
2
2
  import { createSpecMcp } from "./mcp-spec.ts";
3
3
  import { SPEC_COMMANDS } from "./spec-command-table.ts";
4
4
  import { analysisInput } from "./analysis-input.ts";
5
- import { buildGraph, graphNeighbors, LINK_RELATIONS } from "./vault-graph.ts";
5
+ import { buildGraph, graphNeighbors, graphPath, LINK_RELATIONS } from "./vault-graph.ts";
6
6
  import { lintVault } from "./vault-lint.ts";
7
7
  import { writeAnalysisReports } from "./analysis-reports.ts";
8
8
  import { parseFrontmatter } from "./frontmatter.ts";
@@ -34,7 +34,7 @@ const metadata = { type: "object", maxProperties: 32, properties: { authors: { t
34
34
 
35
35
  /** Tool names for the implemented read, write, log, analysis and promotion providers. */
36
36
  export const VMEM_TOOL_NAMES = ["vmem_status", "vmem_search", "vmem_brief", "vmem_read", "vmem_read_many", "vmem_list", "vmem_links", "vmem_mocs", "vmem_check", "vmem_log_tail",
37
- "vmem_create", "vmem_patch", "vmem_append", "vmem_set_frontmatter", "vmem_link", "vmem_supersede", "vmem_log_append", "vmem_move", "vmem_merge", "vmem_delete", "vmem_promote_from_amem", "vmem_lint", "vmem_graph_build", "vmem_graph_neighbors", "vmem_promote", "vmem_skills_mine", "vmem_read_file", "vmem_list_files", "vmem_report", "vmem_stats", ...SPEC_COMMANDS.map(item => item.name)] as const;
37
+ "vmem_create", "vmem_patch", "vmem_append", "vmem_set_frontmatter", "vmem_link", "vmem_supersede", "vmem_log_append", "vmem_move", "vmem_merge", "vmem_delete", "vmem_promote_from_amem", "vmem_lint", "vmem_graph_build", "vmem_graph_neighbors", "vmem_graph_path", "vmem_promote", "vmem_skills_mine", "vmem_read_file", "vmem_list_files", "vmem_report", "vmem_stats", ...SPEC_COMMANDS.map(item => item.name)] as const;
38
38
 
39
39
  /** Server `initialize` instructions: purpose, navigation order and the write contract. Pinned by a test, under 400 bytes. */
40
40
  export const VMEM_INSTRUCTIONS = "vmem is a vault of durable, linked knowledge: notes with frontmatter, wiki-links and an append-only log. Search first with vmem_search, then read the best match with vmem_read, using section for one H2. Writes are validated and receipted: a refusal lists issues, and a failure after publication can leave changes behind, so read the receipt and its issues before retrying.";
@@ -70,6 +70,7 @@ export function vaultTools(ids: readonly string[], orgIds: readonly string[] = [
70
70
  tool("vmem_lint", "Lint a private derived snapshot; write=true writes a screened report.", object({ vault, write: { type: "boolean" }, dryRun: { type: "boolean" } }), "write"),
71
71
  tool("vmem_graph_build", "Build a deterministic graph and screened reports; dryRun changes nothing.", object({ vault, dryRun: { type: "boolean" }, workspace: { type: "boolean" } }), "write"),
72
72
  tool("vmem_graph_neighbors", "Read a bounded graph neighborhood.", object({ vault, path: note, hops: integer(1,2), limit: integer(1,500), relation: { type: "string", enum: ["wiki_link", ...LINK_RELATIONS] } }, ["path"])),
73
+ tool("vmem_graph_path", "Read the shortest undirected link path between two notes (BFS, code-point tie order). MOC/bu hubs are not intermediates unless viaHubs. found=false when no path within maxHops (default 6).", object({ vault, from: note, to: note, maxHops: integer(1,6), relation: { type: "string", enum: ["wiki_link", ...LINK_RELATIONS] }, viaHubs: { type: "boolean" } }, ["from", "to"])),
73
74
  tool("vmem_promote", "Two-step promotion of a personal note into a local org vault clone (never pushes): without confirm returns the full transformed text, dropped links, screen result and fingerprint; confirm=true with that fingerprint writes the org note, source provenance and SYNC log lines. Configured target-vault canonTables add advisory canonical row matches and link-existing choices; personal rows are never included and matches do not affect the fingerprint or block confirm. Publishing is the separate `vmem sync` CLI.",
74
75
  object({ path: note, to: orgVault, topics: { type: "array", maxItems: 32, items: string(200) }, again: { type: "boolean" }, ...twoStep }, ["path", "to"]), "confirm"),
75
76
  tool("vmem_skills_mine", "Read-only skill-candidate mining over amem curated entries, amem capture rows and vault notes: dictionary matching, deterministic communities and novelty scoring. Returns counts, masked candidates and a markdown report; writes nothing.",
@@ -143,6 +144,7 @@ export function createVaultMcp(home: string, env: NodeJS.ProcessEnv = process.en
143
144
  vmem_lint: args => args.write === true ? writeAnalysisReports(home,{vault:pick(args).id,kind:"lint",channel:"mcp",expectedVault:pick(args),dryRun:args.dryRun === true},env) : lintVault(analysisInput(home,pick(args).id,{expectedVault:pick(args),hints:true}).snapshot),
144
145
  vmem_graph_build: args => writeAnalysisReports(home,{vault:pick(args).id,kind:"graph",workspace:args.workspace === true,channel:"mcp",expectedVault:pick(args),dryRun:args.dryRun === true},env),
145
146
  vmem_graph_neighbors: args => graphNeighbors(buildGraph(analysisInput(home,pick(args).id,{expectedVault:pick(args)}).snapshot),str(args.path)!, (args.hops as 1|2|undefined) ?? 1, (args.limit as number|undefined) ?? 50, str(args.relation)),
147
+ vmem_graph_path: args => graphPath(buildGraph(analysisInput(home,pick(args).id,{expectedVault:pick(args)}).snapshot),str(args.from)!,str(args.to)!,{maxHops:(args.maxHops as number|undefined) ?? 6,viaHubs:args.viaHubs === true,...(str(args.relation) === undefined ? {} : {relation:str(args.relation)!})}),
146
148
  vmem_status: () => ({ defaultVault: defaultVault ?? null, vaults: registryStatus(home).filter(v => ids.includes(v.id)) }),
147
149
  vmem_search: args => read(args, index => ({ hits: index.search(str(args.query)!, { limit: (args.limit as number | undefined) ?? 20, type: str(args.type), domain: str(args.domain) }) })),
148
150
  vmem_read: args => read(args, index => { const r = index.show(str(args.path)!, (args.maxBytes as number | undefined) ?? 16384, str(args.section), args.offset as number | undefined); return document(r); }),
@@ -6,7 +6,7 @@ import type { SearchResult, NoteReadResult } from "./vault-index.ts";
6
6
  import type { ResolvedLink, SuggestedLink } from "./links.ts";
7
7
  import type { LogReadResult, LogReceipt } from "./log-types.ts";
8
8
  import type { LintCode, LintReport } from "./analysis-types.ts";
9
- import type { GraphNeighborhood } from "./vault-graph.ts";
9
+ import type { GraphNeighborhood, GraphPath } from "./vault-graph.ts";
10
10
  import type { WriteIssue, WriteReceipt } from "./write-types.ts";
11
11
  import { blocks, clean, fields, heading, issueTable, nextCommand, paint, paragraph, plural, shellWord, table, tone, type CellInput, type TextOptions, stripTerminal } from "./text-output.ts";
12
12
 
@@ -99,3 +99,14 @@ export function neighborsText(r: GraphNeighborhood, o: TextOptions, c: { vault:
99
99
  if (!nodes.length) return [count, more].filter(Boolean).join("\n");
100
100
  return blocks(table(["NOTE", "HOPS", "RELATION", "TITLE"], nodes.map(n => [n.id, hops.get(n.id), relation(n.id), n.label]), o), [count, more].filter(Boolean).join("\n"));
101
101
  }
102
+
103
+ export function pathText(r: GraphPath, o: TextOptions, c: { vault: string; maxHops: number; viaHubs: boolean; relation?: string }): string {
104
+ if (!r.found) {
105
+ const words = ["graph", "path", c.vault, r.from, r.to, ...(c.relation ? ["--relation", c.relation] : [])];
106
+ const hints = [...(c.viaHubs ? [] : [nextCommand("next", command(...words, "--max-hops", String(c.maxHops), "--via-hubs"), o)]),
107
+ ...(c.maxHops < 6 ? [nextCommand("next", command(...words, "--max-hops", "6", ...(c.viaHubs ? ["--via-hubs"] : [])), o)] : [])];
108
+ return [`no path from ${clean(r.from)} to ${clean(r.to)} within ${plural(c.maxHops, "hop")}`, ...hints].join("\n");
109
+ }
110
+ const lines = r.edges.map(e => `${clean(e.source)} -[${e.relation === "wiki_link" ? e.rel ?? e.relation : e.relation}]-> ${clean(e.target)}`);
111
+ return [...lines, `path from ${clean(r.from)} to ${clean(r.to)}: ${plural(r.length, "hop")}`].join("\n");
112
+ }
@@ -401,6 +401,42 @@ export function graphNeighbors(graph: VaultGraph, start: string, hops: 1 | 2, li
401
401
  const selected = new Set([...distances].sort(([a, ad], [b, bd]) => ad - bd || compare(a, b)).slice(0, limit).map(([id]) => id));
402
402
  return { start, hops, nodes: graph.nodes.filter(node => selected.has(node.id)), edges: graph.edges.filter(edge => selected.has(edge.source) && selected.has(edge.target)), truncated: distances.size > limit };
403
403
  }
404
+ export interface GraphPathOptions { maxHops?: number; relation?: string; viaHubs?: boolean }
405
+ export interface GraphPath { from: string; to: string; found: boolean; length: number; nodes: GraphNode[]; edges: GraphEdge[] }
406
+ /** Undirected BFS shortest path; neighbours in code-point order, `moc`/`bu` hubs skipped as intermediates unless `viaHubs`. */
407
+ export function graphPath(graph: VaultGraph, from: string, to: string, options: GraphPathOptions = {}): GraphPath {
408
+ const maxHops = options.maxHops ?? 6, relation = options.relation;
409
+ if (!Number.isInteger(maxHops) || maxHops < 1 || maxHops > 6) throw new Error("graph path: max hops must be 1..6");
410
+ if (relation !== undefined && relation !== "wiki_link" && !(LINK_RELATIONS as readonly string[]).includes(relation))
411
+ throw new Error(`graph path: unknown relation ${JSON.stringify(relation)}; use wiki_link or ${LINK_RELATIONS.join(", ")}`);
412
+ const edges = relation === undefined ? graph.edges : graph.edges.filter(edge => edgeRelation(edge) === relation);
413
+ const neighbors = adjacency({ ...graph, edges });
414
+ if (!neighbors.has(from)) throw new Error("graph path: unknown note (from)");
415
+ if (!neighbors.has(to)) throw new Error("graph path: unknown note (to)");
416
+ const byId = new Map(graph.nodes.map(node => [node.id, node]));
417
+ if (from === to) return { from, to, found: true, length: 0, nodes: [byId.get(from)!], edges: [] };
418
+ const hub = (id: string) => !options.viaHubs && HUB_TYPES.has(byId.get(id)!.type);
419
+ const parent = new Map<string, string>([[from, from]]), depth = new Map([[from, 0]]), queue = [from];
420
+ search: for (let i = 0; i < queue.length; i++) {
421
+ const id = queue[i]!, d = depth.get(id)!;
422
+ if (d >= maxHops || (id !== from && hub(id))) continue;
423
+ for (const next of [...neighbors.get(id)!].sort(compare)) {
424
+ if (parent.has(next)) continue;
425
+ parent.set(next, id); depth.set(next, d + 1); queue.push(next);
426
+ if (next === to) break search;
427
+ }
428
+ }
429
+ if (!parent.has(to)) return { from, to, found: false, length: 0, nodes: [], edges: [] };
430
+ const ids = [to];
431
+ while (ids[0] !== from) ids.unshift(parent.get(ids[0]!)!);
432
+ const steps: GraphEdge[] = [];
433
+ for (let i = 1; i < ids.length; i++) {
434
+ const [a, b] = [ids[i - 1]!, ids[i]!];
435
+ const edge = edges.find(e => (e.source === a && e.target === b) || (e.source === b && e.target === a))!;
436
+ steps.push({ ...edge, source: a, target: b });
437
+ }
438
+ return { from, to, found: true, length: steps.length, nodes: ids.map(id => byId.get(id)!), edges: steps };
439
+ }
404
440
  export function graphReport(graph: VaultGraph, today: string): string {
405
441
  const byId = new Map(graph.nodes.map(node => [node.id, node]));
406
442
  const rank = (a: GraphNode, b: GraphNode) => b.degree - a.degree || compare(a.id, b.id);