@staix/vault-mem 0.13.1 → 0.14.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.14.0] - 2026-11-22
6
+
7
+ - N-1: 0.13.1 and 0.14.0 share the note and spec index files, config format 6 and the enrichment sidecar format. CLI commands and MCP tool names, arguments and receipts are unchanged. Only the console provider differs: its Graph snapshot adds the first-page `enrichment` field and the `similar` and `semantic` arguments, which the 0.13.1 provider does not offer.
8
+
9
+ - Add Graph enrichment capability metadata, similar-note queries and opt-in paged semantic similarity edges; embeddings remain inside the provider.
10
+
5
11
  ## [0.13.1] - 2026-11-22
6
12
 
7
13
  - Add directed `supersedes` and `superseded_by` frontmatter edges to Graph console snapshots. CLI and MCP graph outputs keep their existing behavior.
package/README.md CHANGED
@@ -81,7 +81,7 @@ Each installed directory has a `.vmem-skill.json` ownership marker with its pack
81
81
 
82
82
  ## Library
83
83
 
84
- The only runtime dependency is the first-party range <!-- facts:amem-pin -->`@staix/agent-mem@>=0.33.0 <1.0.0`<!-- /facts:amem-pin -->; host API 1 is checked at load before any agent-mem store opens. Registry commands do not load the agent-mem root. New compatible minors are resolved on installation or update; an existing installation keeps its resolved version. Public library exports (`@staix/vault-mem`, from `src/index.ts`) cover configuration and home resolution, registry operations, frontmatter, link resolution and the derived index, validated writes, the append-only log, the MCP server and its vault tools, host setup, the CLI command table and completion, promotion from agent-mem and to org vaults, lint and graph analysis, sync, source references, migration tidy, the temporal assertion journal and its evaluation, and the spec source registry, graph, validation and freshness. `@staix/vault-mem/ui-plugin` is the console plugin entry, with panels for graph snapshots, proposals (list, show, apply, reject), assertions and note history and changes, and their snapshot types (see [Console plugin](docs/reference/mcp-and-setup.md#console-plugin)). No console bin is shipped. Exported functions and constants by module:
84
+ The only runtime dependency is the first-party range <!-- facts:amem-pin -->`@staix/agent-mem@>=0.33.0 <1.0.0`<!-- /facts:amem-pin -->; host API 1 is checked at load before any agent-mem store opens. Registry commands do not load the agent-mem root. New compatible minors are resolved on installation or update; an existing installation keeps its resolved version. Public library exports (`@staix/vault-mem`, from `src/index.ts`) cover configuration and home resolution, registry operations, frontmatter, link resolution and the derived index, validated writes, the append-only log, the MCP server and its vault tools, host setup, the CLI command table and completion, promotion from agent-mem and to org vaults, lint and graph analysis, sync, source references, migration tidy, the temporal assertion journal and its evaluation, and the spec source registry, graph, validation and freshness. `@staix/vault-mem/ui-plugin` is the console plugin entry, with panels for graph snapshots with optional enrichment and semantic edges, proposals (list, show, apply, reject), assertions and note history and changes, and their snapshot types (see [Console plugin](docs/reference/mcp-and-setup.md#console-plugin)). No console bin is shipped. Exported functions and constants by module:
85
85
  <!-- facts:exports -->
86
86
 
87
87
  - `src/assertion-read.ts`: `readAssertions`, `ASSERTIONS_PAGE_LIMIT`
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@staix/vault-mem",
3
- "version": "0.13.1",
3
+ "version": "0.14.0",
4
4
  "description": "Validated Obsidian-compatible knowledge vaults for agents and people",
5
5
  "license": "MIT",
6
6
  "type": "module",
@@ -1,5 +1,7 @@
1
1
  /** Bounded hybrid ranking over current indexed notes and local stored vectors. */
2
2
  import { join } from "node:path";
3
+ import { createHash } from "node:crypto";
4
+ import type { AnalysisSnapshot } from "./analysis-types.ts";
3
5
  import { loadRegistry } from "./registry.ts";
4
6
  import { logBinding, matchesBinding } from "./vault-log.ts";
5
7
  import { canonicalPath, isDenied } from "./platform.ts";
@@ -39,6 +41,25 @@ function candidates(ctx: ReturnType<typeof queryContext>, index: VaultIndex, que
39
41
  return [{ id, score: vectorSimilarity(query.values, r.value as number[]), note }];
40
42
  }).sort((a, b) => b.score - a.score || (a.id < b.id ? -1 : a.id > b.id ? 1 : 0));
41
43
  }
44
+ /** Internal graph inputs: only current, allowed vectors; callers must never serialize values. */
45
+ export function graphEnrichmentInputs(home: string, vault: string, snapshot: AnalysisSnapshot) {
46
+ const ctx = queryContext(home, vault);
47
+ if (!ctx.store) { ctx.check(); return undefined; }
48
+ const metadata = new Map(snapshot.notes.map(note => {
49
+ const path = note.path.replace(/^notes\//, "");
50
+ return [path, createHash("sha256").update(note.source).digest("hex")] as const;
51
+ }));
52
+ const vectors = ctx.store.records.flatMap(record => {
53
+ if (record.kind !== "embedding" || !Array.isArray(record.value)) return [];
54
+ const path = record.path.slice(6);
55
+ if (!allowed(ctx, path) || metadata.get(path) !== record.contentHash) return [];
56
+ return [{ path, values: record.value as number[] }];
57
+ }).sort((a, b) => a.path < b.path ? -1 : a.path > b.path ? 1 : 0);
58
+ const hash = createHash("sha256").update(JSON.stringify([ctx.store.model ?? null, snapshot.notes.length]));
59
+ for (const item of vectors) hash.update(JSON.stringify([item.path, item.values]));
60
+ ctx.check();
61
+ return { model: ctx.store.model ?? null, embedded: vectors.length, total: snapshot.notes.length, digest: hash.digest("hex"), vectors };
62
+ }
42
63
  export function hybridSearch(home: string, vault: string, index: VaultIndex, query: string, options: SearchOptions, vector: QueryVector): SearchResult[] {
43
64
  const limit = resultLimit(options.limit), ctx = queryContext(home, vault);
44
65
  if (index.vault.id !== ctx.vault.id || index.vault.path !== ctx.vault.path || !index.sourceIdentityCurrent()) throw new Error("enrichment: index is unscanned or belongs to another vault; reopen and scan the selected vault before retrying");
@@ -111,6 +111,17 @@ function readFile(loc: ReturnType<typeof location>): EnrichmentStore {
111
111
  export function readEnrichmentStore(home: string, vault: VaultSpec, roots: VaultSpec[], denyPaths: string[]): EnrichmentStore {
112
112
  return readFile(location(home, vault, roots, denyPaths, false));
113
113
  }
114
+ /** Metadata-only identity for invalidating in-process views after an atomic sidecar replacement. */
115
+ export function enrichmentStoreStamp(home: string, vault: VaultSpec, roots: VaultSpec[], denyPaths: string[]): string {
116
+ const loc = location(home, vault, roots, denyPaths, false);
117
+ try {
118
+ const stat = lstatSync(loc.file, { bigint: true });
119
+ return `${stat.dev}:${stat.ino}:${stat.size}:${stat.mtimeNs}:${stat.ctimeNs}`;
120
+ } catch (error) {
121
+ if ((error as NodeJS.ErrnoException).code === "ENOENT") return "missing";
122
+ throw new Error("enrichment: sidecar identity cannot be read; inspect the local enrichment store", { cause: error });
123
+ }
124
+ }
114
125
  /** Validate complete metadata and vector shape before any side effects. */
115
126
  export function validateEnrichmentRecord(record: EnrichmentRecord): void {
116
127
  if (!record || typeof record !== "object") fail("intake record is missing; supply a complete result");
@@ -3,13 +3,16 @@ import type { AnalysisSnapshot } from "../analysis-types.ts";
3
3
  import { scalarText } from "../analysis-yaml.ts";
4
4
  import { buildGraph, collectUnresolvedGraph, collectSupersedesEdges, codePointCompare, graphFrontmatter, pythonTitle } from "../vault-graph.ts";
5
5
  import type { GraphEdge } from "../vault-graph.ts";
6
- import type { GraphSnapshotPage, GraphNodeColumns, GraphEdgeColumns } from "./panel-types.ts";
6
+ import type { GraphSnapshotPage, GraphNodeColumns, GraphEdgeColumns, SemanticGraphPage } from "./panel-types.ts";
7
7
 
8
8
  type NodeRow = { id: string; label: string; type: string | null; domain: string | null; source_file: string | null; community: number | null; degree: number; updated: string | null; date: string | null; placeholder: boolean; description: string | null; confidence: string | null; topics: string | null };
9
9
  export type GraphEdgeRow = { source: number; target: number; relation: string; field: string | null; rel: string | null; confidence_tag: string; confidence: number };
10
- export interface GraphSnapshotAssembly { vault: string; revision: string; pages: GraphSnapshotPage[] }
10
+ export interface GraphEnrichmentInputs { model: string | null; embedded: number; total: number; digest: string; vectors: { path: string; values: number[] }[] }
11
+ export interface GraphSnapshotAssembly { vault: string; revision: string; pages: GraphSnapshotPage[]; enrichment?: GraphEnrichmentInputs }
11
12
  const MAX_BYTES = 1_048_576 - 32;
12
13
  const MAX_NODES = 10_000, MAX_EDGES = 100_000;
14
+ // ponytail: exact all-pairs search is bounded here; larger vaults need ANN or precomputed neighbors.
15
+ const MAX_SEMANTIC_EMBEDDINGS = 3_000;
13
16
  const scalar = (v: unknown): string | null => scalarText(v) ?? (typeof v === "string" || typeof v === "number" || typeof v === "boolean" || typeof v === "bigint" ? String(v) : null);
14
17
  const token = (vault: string, revision: string, kind: string, offset: number): string => Buffer.from(JSON.stringify([1, vault, revision, kind, offset])).toString("base64url");
15
18
  export const encodeGraphPage = (assembly: GraphSnapshotAssembly, page: GraphSnapshotPage): string => token(assembly.vault, assembly.revision, page.kind, page.offset);
@@ -30,7 +33,7 @@ export function graphEdgeColumns(rows: GraphEdgeRow[]): GraphEdgeColumns {
30
33
  const relations = [...new Set(rows.map(r => r.relation))], tags = rows.map(r => r.confidence_tag), confidence = rows.map(r => r.confidence);
31
34
  return { source: rows.map(r => r.source), target: rows.map(r => r.target), relations, relation: rows.map(r => relations.indexOf(r.relation)), field: rows.map(r => r.field), rel: rows.map(r => r.rel), confidence_tag: tags.every(t => t === tags[0]) ? tags[0] ?? [] : tags, confidence: confidence.every(c => c === confidence[0]) ? confidence[0] ?? [] : confidence };
32
35
  }
33
- export function assembleGraphSnapshot(snapshot: AnalysisSnapshot, vault: string): GraphSnapshotAssembly {
36
+ export function assembleGraphSnapshot(snapshot: AnalysisSnapshot, vault: string, enrichment?: GraphEnrichmentInputs): GraphSnapshotAssembly {
34
37
  const graph = buildGraph(snapshot), ids = new Set(graph.nodes.map(node => node.id));
35
38
  const supersedes = collectSupersedesEdges(snapshot), resolved = supersedes.filter(edge => ids.has(edge.target));
36
39
  if (graph.edges.length + resolved.length > MAX_EDGES) throw new Error(`graph: exceeds ${MAX_EDGES} edges`);
@@ -54,13 +57,13 @@ export function assembleGraphSnapshot(snapshot: AnalysisSnapshot, vault: string)
54
57
  const edges: GraphEdgeRow[] = [...graph.edges, ...resolved, ...extra].map(e => ({ source: indices.get(e.source)!, target: indices.get(e.target)!, relation: e.relation, field: e.field ?? null, rel: e.rel ?? null, confidence_tag: e.confidence_tag, confidence: e.confidence }));
55
58
  const metadata = { directed: graph.directed, multigraph: graph.multigraph, ...graph.graph };
56
59
  const totals = { nodes: nodes.length, edges: edges.length, placeholders: nodes.length - graph.nodes.length, placeholdersOmitted: omitted };
57
- const revision = createHash("sha256").update(JSON.stringify([1, vault, metadata, totals, nodes, edges])).digest("hex");
60
+ const revision = createHash("sha256").update(JSON.stringify([1, vault, metadata, totals, nodes, edges, ...(enrichment ? [enrichment.digest] : [])])).digest("hex");
58
61
  const pages: GraphSnapshotPage[] = [];
59
62
  const envelope = (kind: "nodes" | "edges", offset: number, count: number, columns: GraphNodeColumns | GraphEdgeColumns): GraphSnapshotPage => {
60
63
  const total = kind === "nodes" ? nodes.length : edges.length;
61
64
  const next = offset + count < total ? token(vault, revision, kind, offset + count)
62
65
  : kind === "nodes" && edges.length ? token(vault, revision, "edges", 0) : null;
63
- return { schema: 1, vault, revision, graph: metadata, totals, kind, offset, count, columns, next };
66
+ return { schema: 1, vault, revision, graph: metadata, totals, kind, offset, count, columns, next, ...(enrichment && kind === "nodes" && offset === 0 ? { enrichment: { model: enrichment.model, embedded: enrichment.embedded, total: enrichment.total } } : {}) };
64
67
  };
65
68
  // Binary search each page boundary: every candidate is measured before its rows are accepted.
66
69
  function paginate<T>(kind: "nodes" | "edges", rows: T[], columns: (items: T[]) => GraphNodeColumns | GraphEdgeColumns): void {
@@ -87,5 +90,68 @@ export function assembleGraphSnapshot(snapshot: AnalysisSnapshot, vault: string)
87
90
  }
88
91
  }
89
92
  paginate("nodes", nodes, nodeColumns); paginate("edges", edges, graphEdgeColumns);
90
- return { vault, revision, pages };
93
+ return { vault, revision, pages, ...(enrichment ? { enrichment } : {}) };
94
+ }
95
+
96
+ /** Exact undirected union of each note's top-k cosine neighbors. Vectors remain in process. */
97
+ export function assembleSemanticPages(assembly: GraphSnapshotAssembly, k: number, minScore: number): SemanticGraphPage[] {
98
+ if (!Number.isInteger(k) || k < 1 || k > 20 || typeof minScore !== "number" || !Number.isFinite(minScore) || minScore < 0 || minScore > 1)
99
+ throw new Error("graph semantic: k must be 1..20 and minScore must be 0..1; correct the parameters and restart");
100
+ if (!assembly.enrichment) throw new Error("enrichment: enrichment is disabled; enable it in settings");
101
+ if (assembly.enrichment.embedded > MAX_SEMANTIC_EMBEDDINGS) throw new Error(`graph semantic: exceeds ${MAX_SEMANTIC_EMBEDDINGS} current embeddings; reduce the embedded set or use similar notes`);
102
+ const ids = new Map<string, number>();
103
+ for (const page of assembly.pages) if (page.kind === "nodes") {
104
+ const columns = page.columns as GraphNodeColumns;
105
+ columns.source_file.forEach((path, i) => { if (path) ids.set(path.slice(6), page.offset + i); });
106
+ }
107
+ const vectors = assembly.enrichment.vectors.flatMap(item => {
108
+ const index = ids.get(item.path); if (index === undefined) return [];
109
+ let scale = 0; for (const v of item.values) scale = Math.max(scale, Math.abs(v));
110
+ let norm = 0; for (const v of item.values) norm += (v / scale) ** 2;
111
+ norm = Math.sqrt(norm);
112
+ return [{ index, vector: Float64Array.from(item.values, v => v / scale / norm) }];
113
+ }).sort((a, b) => a.index - b.index);
114
+ const tops: { index: number; score: number }[][] = vectors.map(() => []);
115
+ const insert = (list: { index: number; score: number }[], index: number, score: number) => {
116
+ let at = 0;
117
+ while (at < list.length && (list[at]!.score > score || (list[at]!.score === score && list[at]!.index < index))) at++;
118
+ if (at >= k) return;
119
+ list.splice(at, 0, { index, score }); if (list.length > k) list.pop();
120
+ };
121
+ for (let i = 0; i < vectors.length; i++) for (let j = i + 1; j < vectors.length; j++) {
122
+ const left = vectors[i]!.vector, right = vectors[j]!.vector;
123
+ let score = 0; for (let d = 0; d < left.length; d++) score += left[d]! * right[d]!;
124
+ score = Math.max(-1, Math.min(1, score));
125
+ if (score >= minScore) { insert(tops[i]!, j, score); insert(tops[j]!, i, score); }
126
+ }
127
+ const unique = new Map<string, { source: number; target: number; score: number }>();
128
+ tops.forEach((list, i) => { for (const item of list) {
129
+ const source = Math.min(vectors[i]!.index, vectors[item.index]!.index), target = Math.max(vectors[i]!.index, vectors[item.index]!.index);
130
+ unique.set(`${source}:${target}`, { source, target, score: item.score });
131
+ } });
132
+ const rows = [...unique.values()].sort((a, b) => a.source - b.source || a.target - b.target);
133
+ const encode = (offset: number) => Buffer.from(JSON.stringify([1, assembly.vault, assembly.revision, "semantic", k, minScore, offset])).toString("base64url");
134
+ const make = (offset: number, count: number): SemanticGraphPage => {
135
+ const slice = rows.slice(offset, offset + count);
136
+ return { schema: 1, vault: assembly.vault, revision: assembly.revision, kind: "semantic", offset, count, semantic: { source: slice.map(r => r.source), target: slice.map(r => r.target), score: slice.map(r => r.score) }, next: offset + count < rows.length ? encode(offset + count) : null };
137
+ };
138
+ const pages: SemanticGraphPage[] = []; let offset = 0;
139
+ do {
140
+ let low = 0, high = rows.length - offset;
141
+ if (Buffer.byteLength(JSON.stringify(make(offset, high))) <= MAX_BYTES) { pages.push(make(offset, high)); break; }
142
+ high--;
143
+ while (low < high) { const mid = Math.ceil((low + high) / 2); if (Buffer.byteLength(JSON.stringify(make(offset, mid))) <= MAX_BYTES) low = mid; else high = mid - 1; }
144
+ if (!low) throw new Error("graph semantic: page exceeds the byte budget; reduce the vault id and restart");
145
+ pages.push(make(offset, low)); offset += low;
146
+ } while (offset < rows.length);
147
+ return pages;
148
+ }
149
+ export function resolveSemanticPage(assembly: GraphSnapshotAssembly, pages: SemanticGraphPage[], k: number, minScore: number, page?: string): SemanticGraphPage {
150
+ if (page === undefined) return pages[0]!;
151
+ try {
152
+ const value: unknown = JSON.parse(Buffer.from(page, "base64url").toString("utf8"));
153
+ if (!Array.isArray(value) || value.length !== 7 || value[0] !== 1 || value[1] !== assembly.vault || value[2] !== assembly.revision || value[3] !== "semantic" || value[4] !== k || value[5] !== minScore || !Number.isSafeInteger(value[6]) || value[6] < 0 || Buffer.from(JSON.stringify(value)).toString("base64url") !== page) throw new Error();
154
+ const found = pages.find(p => p.offset === value[6]); if (found) return found;
155
+ } catch { /* All invalid tokens get the same recovery instruction. */ }
156
+ throw new Error("graph semantic page is invalid or expired; restart from the first page");
91
157
  }
@@ -57,6 +57,11 @@ export interface GraphSnapshotPage {
57
57
  totals: { nodes: number; edges: number; placeholders: number; placeholdersOmitted: number };
58
58
  kind: "nodes" | "edges"; offset: number; count: number;
59
59
  columns: GraphNodeColumns | GraphEdgeColumns; next: string | null;
60
+ enrichment?: { model: string | null; embedded: number; total: number };
61
+ }
62
+ export interface SemanticGraphPage {
63
+ schema: 1; vault: string; revision: string; kind: "semantic"; offset: number; count: number;
64
+ semantic: { source: number[]; target: number[]; score: number[] }; next: string | null;
60
65
  }
61
66
  /** The provider attaches a numeric cursor for console conditional polling. */
62
67
  export type GraphPanelPage = GraphSnapshotPage & { cursor: number };
package/src/ui/plugin.ts CHANGED
@@ -11,8 +11,11 @@ import { validArguments } from "../mcp.ts";
11
11
  import { listPromotionCandidates } from "../promote.ts";
12
12
  import { changeSettings, settingsSnapshot, loadRegistry } from "../registry.ts";
13
13
  import { createSnapshotRevision, createPromoteSnapshot, nextSnapshotCursor } from "./snapshot-cache.ts";
14
- import { assembleGraphSnapshot, resolveGraphPage } from "./graph-snapshot.ts";
14
+ import { assembleGraphSnapshot, resolveGraphPage, assembleSemanticPages, resolveSemanticPage } from "./graph-snapshot.ts";
15
15
  import type { GraphSnapshotAssembly } from "./graph-snapshot.ts";
16
+ import type { SemanticGraphPage } from "./panel-types.ts";
17
+ import { graphEnrichmentInputs } from "../enrichment-query.ts";
18
+ import { enrichmentStoreStamp } from "../enrichment-store.ts";
16
19
  import { assertionCoverageWarnings } from "./panel-types.ts";
17
20
  import type { AssertionsReadResult } from "../assertion-read.ts";
18
21
  import { createInboxSnapshot } from "./inbox.ts";
@@ -26,32 +29,48 @@ const VERSION = (JSON.parse(asset("../../package.json")) as { version: string })
26
29
  const LINT_ERRORS: LintCode[] = ["L01", "L02", "L13"];
27
30
  const CACHE_MS = 60_000;
28
31
  /** Revision-bound assemblies, shared between concurrent requests and bounded to two vaults. */
29
- export function createGraphSnapshotCache(revision: () => number, load: (vault: string) => Promise<GraphSnapshotAssembly>, now: () => number = Date.now) {
30
- type Entry = { stamp: number; at: number; assembly: GraphSnapshotAssembly; cursors: Map<string, number> };
32
+ export function createGraphSnapshotCache(revision: (vault: string) => number | string, load: (vault: string) => Promise<GraphSnapshotAssembly>, now: () => number = Date.now) {
33
+ type Entry = { stamp: number | string; at: number; assembly: GraphSnapshotAssembly; cursors: Map<string, number>; semantic: Map<string, SemanticGraphPage[]> };
31
34
  const cache = new Map<string, Entry>(), flights = new Map<string, Promise<Entry>>();
32
35
  return {
33
36
  async snapshot(vault: string, args: Record<string, unknown>): Promise<Record<string, unknown>> {
34
37
  let entry: Entry | undefined;
35
38
  for (let attempts = 0; attempts < 3; attempts++) {
36
- const stamp = revision(), hit = cache.get(vault);
39
+ const stamp = revision(vault), hit = cache.get(vault);
37
40
  if (hit && hit.stamp === stamp && now() - hit.at < CACHE_MS) { entry = hit; break; }
38
41
  let flight = flights.get(vault);
39
42
  if (!flight) {
40
- flight = load(vault).then(assembly => ({ stamp, at: now(), assembly, cursors: new Map<string, number>() }));
43
+ flight = load(vault).then(assembly => ({ stamp, at: now(), assembly, cursors: new Map<string, number>(), semantic: new Map<string, SemanticGraphPage[]>() }));
41
44
  flights.set(vault, flight);
42
45
  }
43
46
  try { entry = await flight; } finally { if (flights.get(vault) === flight) flights.delete(vault); }
44
- if (entry.stamp === revision()) { cache.delete(vault); cache.set(vault, entry); while (cache.size > 2) cache.delete(cache.keys().next().value!); break; }
47
+ if (entry.stamp === revision(vault)) { cache.delete(vault); cache.set(vault, entry); while (cache.size > 2) cache.delete(cache.keys().next().value!); break; }
45
48
  entry = undefined;
46
49
  }
47
50
  if (!entry) throw new Error("graph changed while assembling; restart from the first page");
48
51
  cache.delete(vault); cache.set(vault, entry);
49
52
  while (cache.size > 2) cache.delete(cache.keys().next().value!);
50
53
  if (args.page !== undefined && typeof args.page !== "string") throw new Error("graph page is invalid; restart from the first page");
51
- const page = resolveGraphPage(entry.assembly, args.page as string | undefined);
52
- const key = `${page.kind}:${page.offset}`;
54
+ let page: ReturnType<typeof resolveGraphPage> | SemanticGraphPage;
55
+ let query = "";
56
+ if (args.semantic !== undefined) {
57
+ const options = args.semantic;
58
+ if (!options || typeof options !== "object" || Array.isArray(options) || Object.keys(options).some(key => key !== "k" && key !== "minScore")) throw new Error("graph semantic: supply k and minScore; correct the parameters and restart");
59
+ const { k, minScore } = options as Record<string, unknown>;
60
+ if (typeof k !== "number" || !Number.isInteger(k) || k < 1 || k > 20 || typeof minScore !== "number" || !Number.isFinite(minScore) || minScore < 0 || minScore > 1) throw new Error("graph semantic: k must be 1..20 and minScore must be 0..1; correct the parameters and restart");
61
+ query = JSON.stringify([k, minScore]);
62
+ let pages = entry.semantic.get(query);
63
+ if (!pages) {
64
+ pages = assembleSemanticPages(entry.assembly, k, minScore);
65
+ if (entry.stamp !== revision(vault)) throw new Error("graph changed while assembling semantic edges; restart from the first page");
66
+ if (entry.semantic.size >= 4) entry.semantic.delete(entry.semantic.keys().next().value!);
67
+ entry.semantic.set(query, pages);
68
+ }
69
+ page = resolveSemanticPage(entry.assembly, pages, k, minScore, args.page as string | undefined);
70
+ } else page = resolveGraphPage(entry.assembly, args.page as string | undefined);
71
+ const key = `${page.kind}:${query}:${page.offset}`;
53
72
  let cursor = entry.cursors.get(key);
54
- if (cursor === undefined) { cursor = nextSnapshotCursor(); entry.cursors.set(key, cursor); }
73
+ if (cursor === undefined) { if (entry.cursors.size >= 256) entry.cursors.delete(entry.cursors.keys().next().value!); cursor = nextSnapshotCursor(); entry.cursors.set(key, cursor); }
55
74
  if (args.after === cursor) return { changed: false, cursor };
56
75
  return { ...page, cursor };
57
76
  },
@@ -192,9 +211,15 @@ export const plugin: ConsolePlugin = {
192
211
  };
193
212
 
194
213
  const promote = createPromoteSnapshot(revision.current, candidates);
195
- const graph = createGraphSnapshotCache(revision.current, async id => {
214
+ const graphStamp = (id: string) => {
215
+ const config = loadRegistry(home), vault = config.vaults.find(v => v.id === id);
216
+ if (!vault) throw new Error("graph: vault is no longer registered; select a registered vault");
217
+ return `${revision.current()}:${vault.enrichment?.enabled ? enrichmentStoreStamp(home, vault, config.vaults, config.denyPaths ?? []) : "disabled"}`;
218
+ };
219
+ const graph = createGraphSnapshotCache(graphStamp, async id => {
196
220
  const spec = mcp.vaults.find(v => v.id === id)!;
197
- return assembleGraphSnapshot(analysisInput(home, id, { expectedVault: spec }).snapshot, id);
221
+ const snapshot = analysisInput(home, id, { expectedVault: spec }).snapshot;
222
+ return assembleGraphSnapshot(snapshot, id, graphEnrichmentInputs(home, id, snapshot));
198
223
  });
199
224
  const inbox = createInboxSnapshot(home, mcp.vaults, ctx.log, undefined, revision.current);
200
225
  // One cursor for the whole Promote failure: a fresh one per failed scan would rebuild the panel every poll.
@@ -243,6 +268,10 @@ export const plugin: ConsolePlugin = {
243
268
  case "graph": {
244
269
  const vault = vaultOf(args);
245
270
  if (!vault) return { vault: null, error: str(args.vault) ? `unknown vault ${str(args.vault)}; pick a registered vault from Overview` : "graph: no selected vault; select a registered vault" };
271
+ if (args.similar !== undefined) {
272
+ const result = await readTool("vmem_similar", args, { vault: vault.id, path: args.similar });
273
+ return "error" in result ? result : { similar: result.result.hits };
274
+ }
246
275
  const stem = (value: unknown) => typeof value === "string" && value.startsWith("notes/") && value.endsWith(".md") ? value.slice(6, -3) : value;
247
276
  if (args.neighbors !== undefined) {
248
277
  const r = await readTool("vmem_graph_neighbors", args, { vault: vault.id, path: stem(args.neighbors) });
@@ -461,5 +490,5 @@ export const plugin: ConsolePlugin = {
461
490
  };
462
491
 
463
492
  export default plugin;
464
- export type { ProposalState, ProposalsSnapshot, AssertionsSnapshot, HistorySnapshot, CoverageWarning, GraphSnapshotPage, GraphPanelPage, GraphNodeColumns, GraphEdgeColumns } from "./panel-types.ts";
493
+ export type { ProposalState, ProposalsSnapshot, AssertionsSnapshot, HistorySnapshot, CoverageWarning, GraphSnapshotPage, GraphPanelPage, GraphNodeColumns, GraphEdgeColumns, SemanticGraphPage } from "./panel-types.ts";
465
494
  export { assertionCoverageWarnings } from "./panel-types.ts";