Skip to content

Self-hosted MCP server + dashboard giving Claude Code, Cursor & Hermes agents shared long-term memory over a git-backed markdown vault. Agent-native, Obsidian-compatible second brain — markdown RAG, no vector DB.

fix(vault): stop the duplicate-stem warning reprinting on every reindex

Ronalds Palacisefa7e28081ab
diff --git a/lib/vault/dup-stems.test.ts b/lib/vault/dup-stems.test.ts
new file mode 100644
index 0000000..649e2ce
--- /dev/null
+++ b/lib/vault/dup-stems.test.ts
@@ -0,0 +1,86 @@
+import { test, expect, beforeEach } from "bun:test";
+import fs from "node:fs";
+import path from "node:path";
+import { TEST_VAULT } from "../../test/setup";
+import { rebuildIndex, refreshPaths } from "./store";
+
+/**
+ * A duplicated filename stem is a permanent property of a vault's layout — no reindex resolves it.
+ * The warning therefore has to be edge-triggered, because `recomputeLinks` runs on every write and
+ * every watcher flush. Warning on state instead of on change is what made a 4-README vault reprint
+ * the same line into the deploy log forever.
+ *
+ * "Already warned" is process-lifetime state, so each test below claims its OWN stem. Sharing one
+ * across tests would make them order-dependent — which is the honest cost of the memo, not a bug.
+ */
+
+function write(rel: string, body: string) {
+ const abs = path.join(TEST_VAULT, rel);
+ fs.mkdirSync(path.dirname(abs), { recursive: true });
+ fs.writeFileSync(abs, body);
+}
+
+function warnings(fn: () => void): string[] {
+ const out: string[] = [];
+ const orig = console.warn;
+ console.warn = (...a: unknown[]) => void out.push(a.join(" "));
+ try {
+ fn();
+ } finally {
+ console.warn = orig;
+ }
+ return out.filter((l) => l.includes("duplicate stem"));
+}
+
+/** Four notes sharing one stem, the layout that produced the original report. */
+function fourWay(stem: string) {
+ write(`${stem}.md`, "# Root\n");
+ write(`archive/${stem}.md`, "# Archive\n");
+ write(`leads/${stem}.md`, "# Leads\n");
+ write(`leads/brands/${stem}.md`, "# Brands\n");
+}
+
+beforeEach(() => {
+ fs.rmSync(TEST_VAULT, { recursive: true, force: true });
+ fs.mkdirSync(TEST_VAULT, { recursive: true });
+});
+
+test("duplicate stems nothing links to stay silent", () => {
+ fourWay("OVERVIEW");
+ write("notes/a.md", "# A\n\nno wikilinks here\n");
+ expect(warnings(rebuildIndex)).toEqual([]);
+});
+
+test("a linked duplicate stem is reported once, not on every later reindex", () => {
+ fourWay("README");
+ write("notes/a.md", "# A\n\nsee [[README]] for context\n");
+
+ const first = warnings(rebuildIndex);
+ expect(first).toHaveLength(1);
+ // Actionable: names the note holding the link, the winner, and what it shadows.
+ expect(first[0]).toContain("notes/a.md");
+ expect(first[0]).toContain("resolves to README.md");
+ expect(first[0]).toContain("leads/brands/README.md");
+
+ // Unrelated writes each re-run recomputeLinks. None of them may reprint.
+ for (let i = 0; i < 3; i++) {
+ write(`notes/b${i}.md`, `# B${i}\n\nunrelated\n`);
+ expect(warnings(() => refreshPaths([`notes/b${i}.md`]))).toEqual([]);
+ }
+ // Neither may a full rebuild.
+ expect(warnings(rebuildIndex)).toEqual([]);
+});
+
+test("a collision that is resolved and then reintroduced warns again", () => {
+ fourWay("GUIDE");
+ write("notes/a.md", "# A\n\nsee [[GUIDE]]\n");
+ expect(warnings(rebuildIndex)).toHaveLength(1);
+
+ // Resolve it: nothing links the ambiguous stem any more.
+ write("notes/a.md", "# A\n\nno link now\n");
+ expect(warnings(() => refreshPaths(["notes/a.md"]))).toEqual([]);
+
+ // Reintroduce it — the earlier report must not suppress the new one.
+ write("notes/a.md", "# A\n\nsee [[GUIDE]] again\n");
+ expect(warnings(() => refreshPaths(["notes/a.md"]))).toHaveLength(1);
+});
diff --git a/lib/vault/store.ts b/lib/vault/store.ts
index 42a4f5f..b4c0e6f 100644
--- a/lib/vault/store.ts
+++ b/lib/vault/store.ts
@@ -46,6 +46,18 @@ let state: IndexState | null = null;
let watcher: FSWatcher | null = null;
let watchedDir = "";
+/**
+ * Ambiguous stems already reported, and the vault they belong to.
+ *
+ * `recomputeLinks` runs on every write, every watcher flush and every full rebuild, so anything
+ * warned unconditionally from it reprints for as long as the vault keeps the collision — which is
+ * forever, because no reindex resolves a naming collision. Remembering what was already said turns
+ * the warning from level-triggered to edge-triggered: it fires when a collision appears, and stays
+ * quiet afterwards. Resolved stems are dropped from the set, so a collision reintroduced later is
+ * reported again.
+ */
+let warnedStems = { dir: "", stems: new Set<string>() };
+
function newIndex(): MiniSearch<IndexDoc> {
return new MiniSearch<IndexDoc>({
fields: ["title", "aliases", "tags", "body", "folder", "type"],
@@ -114,18 +126,28 @@ function recomputeLinks(s: IndexState): void {
s.duplicateStems.set(slug, dupes);
}
}
- // Only warn when something actually links to the ambiguous stem. Two notes sharing a
- // filename nothing references is harmless (every vault has a few READMEs), and warning
- // unconditionally reprints on every reindex — which buries the cases that DO silently
- // misresolve a link. The full set stays in s.duplicateStems for the integrity report.
- const linkedStems = new Set<string>();
- for (const stems of s.linksBySource.values()) {
- for (const stem of stems) linkedStems.add(stem);
+ // Only warn when something actually links the ambiguous stem: two notes sharing a filename
+ // nothing references is harmless (every vault has a few READMEs). Name a note that links it,
+ // so the warning points at the file to edit instead of just asserting a collision exists.
+ // The full set stays in s.duplicateStems for the integrity report either way.
+ const linkedFrom = new Map<string, string>();
+ for (const [src, stems] of s.linksBySource) {
+ for (const stem of stems) if (!linkedFrom.has(stem)) linkedFrom.set(stem, src);
}
+ if (warnedStems.dir !== s.dir) warnedStems = { dir: s.dir, stems: new Set() };
+ const ambiguous = new Set<string>();
for (const [slug, paths] of s.duplicateStems) {
- if (!linkedStems.has(slug)) continue;
- console.warn(`[vault] duplicate stem "${slug}" (${paths.join(", ")}) — wikilinks resolve to the first.`);
+ const src = linkedFrom.get(slug);
+ if (src === undefined) continue;
+ ambiguous.add(slug);
+ if (warnedStems.stems.has(slug)) continue; // already reported — see warnedStems
+ const [winner, ...shadowed] = paths;
+ console.warn(
+ `[vault] duplicate stem "${slug}" — [[${slug}]] (linked from ${src}) resolves to ${winner}, ` +
+ `shadowing ${shadowed.join(", ")}.`,
+ );
}
+ warnedStems.stems = ambiguous;
s.outEdges = new Map();
s.inEdges = new Map();