@staix/vault-mem 0.13.0 → 0.13.1
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 +6 -0
- package/package.json +1 -1
- package/src/mcp-vault.ts +19 -2
- package/src/ui/graph-snapshot.ts +8 -5
- package/src/ui/plugin.ts +16 -1
- package/src/vault-graph.ts +27 -1
- package/src/writer.ts +2 -1
package/CHANGELOG.md
CHANGED
|
@@ -2,6 +2,12 @@
|
|
|
2
2
|
|
|
3
3
|
## [Unreleased]
|
|
4
4
|
|
|
5
|
+
## [0.13.1] - 2026-11-22
|
|
6
|
+
|
|
7
|
+
- Add directed `supersedes` and `superseded_by` frontmatter edges to Graph console snapshots. CLI and MCP graph outputs keep their existing behavior.
|
|
8
|
+
|
|
9
|
+
- Add an opt-in two-step mode to `vmem_link` (`preview`, `confirm`, `fingerprint`; a stale fingerprint returns a fresh preview) and a console `link` action that previews both notes, the relation and the log event before confirming; an existing link is a no-op. Calls without `preview` or `confirm` write in one step as before.
|
|
10
|
+
|
|
5
11
|
## [0.13.0] - 2026-11-22
|
|
6
12
|
|
|
7
13
|
- N-1: 0.12.1 and 0.13.0 share the note and spec index files and config format 6. The 0.13.0 CLI adds assertion coverage lines and changes skills-mine filtering and cap reporting; the 0.12.1 CLI keeps its previous behavior. MCP tool names and arguments are unchanged; `vmem_assertions` coverage and `vmem_skills_mine` dropped counts gain additive fields, which 0.12.1 clients may ignore; for an unsupported entry inside an incomplete batch, `coverage.unsupported[].seq` now identifies the first excluded batch entry, as `untrusted[].seq` already did. In 0.12.1 it identifies the unsupported line; `failedSeq` now retains that value. The 0.13.0 console provider adds the Graph panel; an older provider remains usable without it.
|
package/package.json
CHANGED
package/src/mcp-vault.ts
CHANGED
|
@@ -92,7 +92,7 @@ export function vaultTools(ids: readonly string[], orgIds: readonly string[] = [
|
|
|
92
92
|
tool("vmem_patch", "Replace exact strings in a note: one oldString/newString pair, or edits (1..32 pairs, each matching once in the original text, non-overlapping) applied all-or-nothing with one receipt and one log event.", object({ vault, path: note, oldString: string(8192), newString: string(8192, 0), edits: { type: "array", minItems: 1, maxItems: 32, items: object({ oldString: string(8192), newString: string(8192, 0) }, ["oldString", "newString"]) }, expectedSha: sha, log: logEvent }, ["path"]), "write"),
|
|
93
93
|
tool("vmem_append", "Append markdown to a section of a note.", object({ vault, path: note, section: string(120), markdown: string(16384), expectedSha: sha, log: logEvent }, ["path", "section", "markdown"]), "write"),
|
|
94
94
|
tool("vmem_set_frontmatter", "Set or unset frontmatter keys of a note.", object({ vault, path: note, set: metadata, unset: { type: "array", maxItems: 32, items: string(64) }, expectedSha: sha, log: logEvent }, ["path"]), "write"),
|
|
95
|
-
tool("vmem_link", "Add a typed relation link between two notes (bidirectional by default).", object({ vault, from: note, to: note, relation: { type: "string", enum: RELATIONS }, context: string(500), bidirectional: { type: "boolean" }, log: logEvent }, ["from", "to", "relation"]), "write"),
|
|
95
|
+
tool("vmem_link", "Add a typed relation link between two notes (bidirectional by default). One step by default. Opt-in two-step: preview=true returns the planned changes to each note, the log event and a fingerprint without writing; confirm=true with that fingerprint writes only while it still matches, otherwise a fresh preview (stale=true) is returned and nothing is written.", object({ vault, from: note, to: note, relation: { type: "string", enum: RELATIONS }, context: string(500), bidirectional: { type: "boolean" }, preview: { type: "boolean" }, ...twoStep, log: logEvent }, ["from", "to", "relation"]), "write"),
|
|
96
96
|
tool("vmem_supersede", "Mark a note superseded by another.", object({ vault, old: note, next: note, log: logEvent }, ["old", "next"]), "write"),
|
|
97
97
|
tool("vmem_log_append", "Append one validated event line to the vault log.", object({ vault, type: { type: "string", enum: LOG_TYPES }, project: string(64), source: string(512), dest: string(512), note: string(500) }, ["type", "project", "source", "note"]), "write"),
|
|
98
98
|
tool("vmem_move", "Two-step rename with link rewrites: without confirm returns preview and fingerprint; then confirm=true with that fingerprint (pass log on the confirm call).", object({ vault, from: note, to: note, ...twoStep, log: logEvent }, ["from", "to"]), "confirm"),
|
|
@@ -313,7 +313,24 @@ export function createVaultMcp(home: string, env: NodeJS.ProcessEnv = process.en
|
|
|
313
313
|
vmem_patch: args => write(args, { op: "patch", path: str(args.path)!, ...(args.oldString !== undefined ? { oldString: str(args.oldString) } : {}), ...(args.newString !== undefined ? { newString: str(args.newString) } : {}), ...(args.edits !== undefined ? { edits: args.edits as PatchEdit[] } : {}), expectedSha: str(args.expectedSha) }),
|
|
314
314
|
vmem_append: args => write(args, { op: "append", path: str(args.path)!, section: str(args.section)!, markdown: str(args.markdown)!, expectedSha: str(args.expectedSha) }),
|
|
315
315
|
vmem_set_frontmatter: args => write(args, { op: "frontmatter", path: str(args.path)!, set: (args.set as Record<string, unknown> | undefined) ?? {}, ...(args.unset ? { unset: args.unset as string[] } : {}), expectedSha: str(args.expectedSha) }),
|
|
316
|
-
vmem_link: args =>
|
|
316
|
+
vmem_link: args => {
|
|
317
|
+
const operation: WriteOp = { op: "link", from: str(args.from)!, to: str(args.to)!, relation: args.relation as Extract<WriteOp, { op: "link" }>["relation"], ...(str(args.context) ? { context: str(args.context) } : {}), bidirectional: args.bidirectional !== false };
|
|
318
|
+
if (args.confirm === true && !str(args.fingerprint)) throw new Error("link: confirm requires the preview fingerprint; request a preview with preview=true");
|
|
319
|
+
if (args.confirm !== true && args.fingerprint !== undefined) throw new Error("link: fingerprint requires confirm=true; request a new preview");
|
|
320
|
+
// The default log event the write would append; a given `log` replaces it.
|
|
321
|
+
const preview = (stale: boolean) => {
|
|
322
|
+
const receipt = write(args, operation, { dryRun: true });
|
|
323
|
+
if (!receipt.ok) return receipt;
|
|
324
|
+
const event = (args.log as LogEvent | undefined) ?? { type: "CONNECT", project: "-", source: notePath(operation.from), dest: notePath(operation.to), note: "link" };
|
|
325
|
+
return { ...receipt, logEvent: event, ...(stale ? { stale: true } : {}) };
|
|
326
|
+
};
|
|
327
|
+
if (args.confirm === true) {
|
|
328
|
+
const receipt = write(args, operation, twoStep(args));
|
|
329
|
+
const staleFingerprint = !receipt.ok && !receipt.applied && receipt.issues.length === 1 && receipt.issues[0]?.code === "V09" && /fingerprint/.test(receipt.issues[0].message);
|
|
330
|
+
return staleFingerprint ? preview(true) : receipt;
|
|
331
|
+
}
|
|
332
|
+
return args.preview === true ? preview(false) : write(args, operation);
|
|
333
|
+
},
|
|
317
334
|
vmem_supersede: args => write(args, { op: "supersede", old: str(args.old)!, next: str(args.next)! }),
|
|
318
335
|
vmem_log_append: args => {
|
|
319
336
|
const event: LogEvent = { type: str(args.type)!, project: str(args.project)!, source: str(args.source)!, note: str(args.note)!, ...(str(args.dest) ? { dest: str(args.dest) } : {}) };
|
package/src/ui/graph-snapshot.ts
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
import { createHash } from "node:crypto";
|
|
2
2
|
import type { AnalysisSnapshot } from "../analysis-types.ts";
|
|
3
3
|
import { scalarText } from "../analysis-yaml.ts";
|
|
4
|
-
import { buildGraph, collectUnresolvedGraph, codePointCompare, graphFrontmatter, pythonTitle } from "../vault-graph.ts";
|
|
4
|
+
import { buildGraph, collectUnresolvedGraph, collectSupersedesEdges, codePointCompare, graphFrontmatter, pythonTitle } from "../vault-graph.ts";
|
|
5
5
|
import type { GraphEdge } from "../vault-graph.ts";
|
|
6
6
|
import type { GraphSnapshotPage, GraphNodeColumns, GraphEdgeColumns } from "./panel-types.ts";
|
|
7
7
|
|
|
@@ -31,7 +31,10 @@ export function graphEdgeColumns(rows: GraphEdgeRow[]): GraphEdgeColumns {
|
|
|
31
31
|
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
32
|
}
|
|
33
33
|
export function assembleGraphSnapshot(snapshot: AnalysisSnapshot, vault: string): GraphSnapshotAssembly {
|
|
34
|
-
const graph = buildGraph(snapshot),
|
|
34
|
+
const graph = buildGraph(snapshot), ids = new Set(graph.nodes.map(node => node.id));
|
|
35
|
+
const supersedes = collectSupersedesEdges(snapshot), resolved = supersedes.filter(edge => ids.has(edge.target));
|
|
36
|
+
if (graph.edges.length + resolved.length > MAX_EDGES) throw new Error(`graph: exceeds ${MAX_EDGES} edges`);
|
|
37
|
+
const unresolved = [...collectUnresolvedGraph(snapshot), ...supersedes.filter(edge => !ids.has(edge.target))];
|
|
35
38
|
const grouped = new Map<string, GraphEdge[]>();
|
|
36
39
|
for (const edge of unresolved) { const list = grouped.get(edge.target) ?? []; list.push(edge); grouped.set(edge.target, list); }
|
|
37
40
|
const notes = new Map(snapshot.notes.map(n => [n.path.replace(/^notes\//, "").slice(0, -3), n]));
|
|
@@ -41,14 +44,14 @@ export function assembleGraphSnapshot(snapshot: AnalysisSnapshot, vault: string)
|
|
|
41
44
|
});
|
|
42
45
|
const extra: GraphEdge[] = [];
|
|
43
46
|
let omitted = 0, full = false;
|
|
44
|
-
for (const [id, edges] of grouped) {
|
|
45
|
-
if (full || nodes.length >= MAX_NODES || graph.edges.length + extra.length + edges.length > MAX_EDGES) { full = true; omitted++; continue; }
|
|
47
|
+
for (const [id, edges] of [...grouped].sort(([a], [b]) => codePointCompare(a, b))) {
|
|
48
|
+
if (full || nodes.length >= MAX_NODES || graph.edges.length + resolved.length + extra.length + edges.length > MAX_EDGES) { full = true; omitted++; continue; }
|
|
46
49
|
nodes.push({ id, label: pythonTitle(id.replaceAll("-", " ")), type: null, domain: null, source_file: null, community: null, degree: edges.length, updated: null, date: null, placeholder: true, description: null, confidence: null, topics: null });
|
|
47
50
|
extra.push(...edges);
|
|
48
51
|
}
|
|
49
52
|
extra.sort((a, b) => codePointCompare(a.source, b.source) || codePointCompare(a.target, b.target));
|
|
50
53
|
const indices = new Map(nodes.map((n, i) => [n.id, i]));
|
|
51
|
-
const edges: GraphEdgeRow[] = [...graph.edges, ...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 }));
|
|
54
|
+
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 }));
|
|
52
55
|
const metadata = { directed: graph.directed, multigraph: graph.multigraph, ...graph.graph };
|
|
53
56
|
const totals = { nodes: nodes.length, edges: edges.length, placeholders: nodes.length - graph.nodes.length, placeholdersOmitted: omitted };
|
|
54
57
|
const revision = createHash("sha256").update(JSON.stringify([1, vault, metadata, totals, nodes, edges])).digest("hex");
|
package/src/ui/plugin.ts
CHANGED
|
@@ -16,6 +16,7 @@ import type { GraphSnapshotAssembly } from "./graph-snapshot.ts";
|
|
|
16
16
|
import { assertionCoverageWarnings } from "./panel-types.ts";
|
|
17
17
|
import type { AssertionsReadResult } from "../assertion-read.ts";
|
|
18
18
|
import { createInboxSnapshot } from "./inbox.ts";
|
|
19
|
+
import { LINK_RELATIONS } from "../links.ts";
|
|
19
20
|
import { lintVault } from "../vault-lint.ts";
|
|
20
21
|
import { readLogSince } from "../vault-log.ts";
|
|
21
22
|
import type { LintCode } from "../analysis-types.ts";
|
|
@@ -132,7 +133,7 @@ export const plugin: ConsolePlugin = {
|
|
|
132
133
|
{ id: "history", title: "History", order: 10 },
|
|
133
134
|
{ id: "graph", title: "Graph", order: 11, maxAgeMs: REUSE_MS },
|
|
134
135
|
],
|
|
135
|
-
capabilities: { actions: ["delete", "move", "promote", "promote-from-amem", "settings", "proposal-apply", "proposal-reject"], confirm: true, inbox: true, inboxMaxAgeMs: REUSE_MS, search: true },
|
|
136
|
+
capabilities: { actions: ["delete", "move", "promote", "promote-from-amem", "settings", "proposal-apply", "proposal-reject", "link"], confirm: true, inbox: true, inboxMaxAgeMs: REUSE_MS, search: true },
|
|
136
137
|
},
|
|
137
138
|
async open(ctx): Promise<ConsoleProvider> {
|
|
138
139
|
const home = resolveHome().home;
|
|
@@ -204,11 +205,17 @@ export const plugin: ConsolePlugin = {
|
|
|
204
205
|
if (typeof args === "string") return { ok: false, error: args };
|
|
205
206
|
const preview = await call(tool, args);
|
|
206
207
|
if (preview.refused || preview.ok === false || typeof preview.fingerprint !== "string") return { ok: false, error: firstIssue(preview) };
|
|
208
|
+
if (preview.unchanged === true) return { ok: true, message: `${describe(preview).verb}: already done, nothing changed` };
|
|
207
209
|
if (!confirmed || fingerprint !== preview.fingerprint) {
|
|
208
210
|
const d = describe(preview);
|
|
209
211
|
return { ok: false, needsConfirm: true, fingerprint: preview.fingerprint, verb: d.verb, preview: d.preview, changes: d.changes, ...(d.warnings.length ? { warnings: d.warnings } : {}) };
|
|
210
212
|
}
|
|
211
213
|
const done = await call(tool, { ...args, confirm: true, fingerprint });
|
|
214
|
+
// A tool that answers a stale fingerprint with a fresh preview (vmem_link) gets a new confirmation, never a write.
|
|
215
|
+
if (done.stale === true && typeof done.fingerprint === "string") {
|
|
216
|
+
const d = describe(done);
|
|
217
|
+
return { ok: false, needsConfirm: true, fingerprint: done.fingerprint, verb: d.verb, preview: d.preview, changes: d.changes, warnings: ["the notes changed since the preview; review the fresh preview", ...d.warnings] };
|
|
218
|
+
}
|
|
212
219
|
if (done.applied === true) { lintCache.clear(); revision.invalidate(); inbox.invalidate(); }
|
|
213
220
|
return confirmedOutcome(done, describe(preview).verb);
|
|
214
221
|
}
|
|
@@ -370,6 +377,14 @@ export const plugin: ConsolePlugin = {
|
|
|
370
377
|
warnings: backlinks.length ? [`${backlinks.length} links point here: ${[...new Set(backlinks.map(b => b.source))].slice(0, 5).join(", ")}`] : [] };
|
|
371
378
|
});
|
|
372
379
|
}
|
|
380
|
+
case "link": {
|
|
381
|
+
const from = str(args.from), to = str(args.to), relation = str(args.relation);
|
|
382
|
+
if (!from || !to || !relation) return { ok: false, error: "link: from, to and relation are required; pick both notes and a relation" };
|
|
383
|
+
if (!(LINK_RELATIONS as readonly string[]).includes(relation)) return { ok: false, error: `link: invalid relation ${relation}; use one of ${LINK_RELATIONS.join(", ")}` };
|
|
384
|
+
const both = args.bidirectional !== false && args.bidirectional !== "false";
|
|
385
|
+
return twoStep("vmem_link", forward("vmem_link", args, { preview: true, bidirectional: both }), confirmed, fingerprint, p => ({ verb: "Link notes",
|
|
386
|
+
preview: [`link ${from} → ${to} (${relation})${both ? ", both directions" : ", one way"}`, ...(p.logEvent ? [`log: ${JSON.stringify(p.logEvent)}`] : [])], changes: changesOf(p), warnings: [] }));
|
|
387
|
+
}
|
|
373
388
|
case "move": {
|
|
374
389
|
const from = str(args.from), to = str(args.to);
|
|
375
390
|
if (!from || !to) return { ok: false, error: "from and to are required" };
|
package/src/vault-graph.ts
CHANGED
|
@@ -1,5 +1,5 @@
|
|
|
1
1
|
import type { AnalysisSnapshot } from "./analysis-types.ts";
|
|
2
|
-
import { authoredLinkOffsets, LINK_RELATIONS } from "./links.ts";
|
|
2
|
+
import { authoredLinkOffsets, LINK_RELATIONS, noteKey } from "./links.ts";
|
|
3
3
|
export { LINK_RELATIONS };
|
|
4
4
|
import { AnalysisYamlUnsupported, parseAnalysisYaml, scalarText, yamlTruthy } from "./analysis-yaml.ts";
|
|
5
5
|
|
|
@@ -137,6 +137,32 @@ export function collectUnresolvedGraph(snapshot: AnalysisSnapshot): GraphEdge[]
|
|
|
137
137
|
}
|
|
138
138
|
return [...edges.values()].sort((a, b) => compare(a.target, b.target) || compare(a.source, b.source));
|
|
139
139
|
}
|
|
140
|
+
/** Directed frontmatter references for the console snapshot; the legacy graph stays unchanged. */
|
|
141
|
+
export function collectSupersedesEdges(snapshot: AnalysisSnapshot): GraphEdge[] {
|
|
142
|
+
const sources = [...snapshot.notes].sort((a, b) => compare(a.path, b.path));
|
|
143
|
+
const ids = new Map<string, string>();
|
|
144
|
+
for (const note of sources) {
|
|
145
|
+
const id = note.path.replace(/^notes\//, "").slice(0, -3);
|
|
146
|
+
ids.set(noteKey(note.path), id);
|
|
147
|
+
}
|
|
148
|
+
const edges: GraphEdge[] = [];
|
|
149
|
+
for (const note of sources) {
|
|
150
|
+
const source = note.path.replace(/^notes\//, "").slice(0, -3), fm = parse(note.source).fm;
|
|
151
|
+
for (const field of ["supersedes", "superseded_by"] as const) {
|
|
152
|
+
const values = Array.isArray(fm[field]) ? fm[field] : [fm[field]];
|
|
153
|
+
for (const value of values) {
|
|
154
|
+
if (typeof value !== "string") continue;
|
|
155
|
+
for (const match of value.matchAll(LEGACY_LINK)) {
|
|
156
|
+
const raw = match[1]!.split("#", 1)[0]!.trim(), key = noteKey(raw);
|
|
157
|
+
if (!key) continue;
|
|
158
|
+
const target = ids.get(key) ?? ids.get(noteKey(legacyTarget(key))) ?? legacyTarget(key);
|
|
159
|
+
edges.push({ source, target, relation: "supersedes", field, confidence_tag: "EXTRACTED", confidence: 1 });
|
|
160
|
+
}
|
|
161
|
+
}
|
|
162
|
+
}
|
|
163
|
+
}
|
|
164
|
+
return edges;
|
|
165
|
+
}
|
|
140
166
|
function adjacency(graph: Pick<VaultGraph, "nodes" | "edges">): Map<string, Set<string>> {
|
|
141
167
|
const neighbors = new Map(graph.nodes.map(node => [node.id, new Set<string>()]));
|
|
142
168
|
for (const edge of graph.edges) { neighbors.get(edge.source)?.add(edge.target); neighbors.get(edge.target)?.add(edge.source); }
|
package/src/writer.ts
CHANGED
|
@@ -360,7 +360,8 @@ function runWrite(home: string, request: WriteRequest, options: WriteOptions & {
|
|
|
360
360
|
const logIssues = checkLogEvent(home, { vault: request.vault, event: request.log, channel: request.channel }, options.env);
|
|
361
361
|
if (logIssues.length) throw new WriteRefusal(logIssues.map(issue => ({ ...issue, message: `log event refused, nothing written: ${issue.message}; fix the event fields (rules as for \`log append\`) or omit the event for the default line` })));
|
|
362
362
|
}
|
|
363
|
-
|
|
363
|
+
// link is one-step unless the caller confirms a preview fingerprint (opt-in two-step, #295).
|
|
364
|
+
const twoStep = ["move", "delete", "tidy", "merge"].includes(request.operation.op) || (request.operation.op === "link" && request.confirm === true);
|
|
364
365
|
const preview = request.operation.op === "check" || request.dryRun === true || (twoStep && request.confirm !== true);
|
|
365
366
|
if (options.proposal && (preview || !options.binding || !["create", "patch", "infer-link"].includes(request.operation.op))) refuse("V01", "proposal confirmation requires one supported proposal operation and a bound vault; request a new preview");
|
|
366
367
|
if (!preview) {
|