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(parse): never swallow unreadable frontmatter

Ronalds Palacis0d5d61bcd769
diff --git a/lib/mcp/tools.ts b/lib/mcp/tools.ts
index 0e21ba3..9b01934 100644
--- a/lib/mcp/tools.ts
+++ b/lib/mcp/tools.ts
@@ -55,6 +55,24 @@ async function writeFromArgs(a: Args): Promise<string> {
);
}
+/**
+ * Report a write, warning loudly when the note's YAML did not survive the round-trip.
+ * Unparseable frontmatter is silently discarded on read, so a note claiming `status: locked`
+ * would rank as an ordinary note forever. The agent that wrote it should hear about it now.
+ */
+async function writeResult(a: Args) {
+ const p = await writeFromArgs(a);
+ const n = getNote(p);
+ if (n?.frontmatterError) {
+ return {
+ ok: true,
+ path: p,
+ warning: `Frontmatter was written but cannot be parsed (${n.frontmatterError}). Its status, tags and title are being ignored. Usual cause: an unquoted ":" in a value — quote it, e.g. title: "Decision: X". Re-write the note to fix.`,
+ };
+ }
+ return { ok: true, path: p };
+}
+
export const TOOLS: Tool[] = [
{
name: "brain_schema",
@@ -115,6 +133,11 @@ export const TOOLS: Tool[] = [
tags: n.tags,
frontmatter: n.frontmatter,
backlinks: getBacklinks(n.path).map((b) => b.path),
+ ...(n.frontmatterError
+ ? {
+ warning: `This note's frontmatter is unparseable (${n.frontmatterError}), so its status, tags and title are being ignored — whatever it claims about itself is NOT in effect. Usual cause: an unquoted ":" in a value.`,
+ }
+ : {}),
};
if (!section) return { ...base, content: n.raw };
@@ -196,7 +219,7 @@ export const TOOLS: Tool[] = [
},
required: ["path"],
},
- handler: async (a) => ({ ok: true, path: await writeFromArgs(a) }),
+ handler: async (a) => await writeResult(a),
},
{
name: "brain_edit",
@@ -212,7 +235,7 @@ export const TOOLS: Tool[] = [
},
required: ["path"],
},
- handler: async (a) => ({ ok: true, path: await writeFromArgs(a) }),
+ handler: async (a) => await writeResult(a),
},
{
name: "brain_append",
@@ -222,7 +245,11 @@ export const TOOLS: Tool[] = [
properties: { path: s("vault-relative path"), text: s("text to append") },
required: ["path", "text"],
},
- handler: async ({ path, text }) => ({ ok: true, path: await appendNote(String(path), String(text ?? "")) }),
+ handler: async ({ path, text }) => {
+ const p = await appendNote(String(path), String(text ?? ""));
+ const n = getNote(p);
+ return n?.frontmatterError ? { ok: true, path: p, warning: `Frontmatter unparseable (${n.frontmatterError}) — status and tags ignored.` } : { ok: true, path: p };
+ },
},
{
name: "brain_move",
diff --git a/lib/vault/parse.ts b/lib/vault/parse.ts
index 5223f54..e6527f9 100644
--- a/lib/vault/parse.ts
+++ b/lib/vault/parse.ts
@@ -100,12 +100,21 @@ export interface ParsedNote {
export function parseNote(relPath: string, raw: string): ParsedNote {
let data: Record<string, unknown> = {};
let body = raw;
+ let frontmatterError: string | undefined;
try {
const g = matter(raw);
data = (g.data ?? {}) as Record<string, unknown>;
body = g.content;
- } catch {
- // Tolerate malformed frontmatter — treat whole file as body.
+ } catch (e) {
+ // Tolerate malformed frontmatter — treat the whole file as body — but never silently.
+ // A YAML typo (e.g. an unquoted second colon in a title) would otherwise discard the
+ // note's status and tags, so an authoritative note quietly ranks as an ordinary one.
+ frontmatterError = (e as Error).message.split("\n")[0];
+ if (raw.trimStart().startsWith("---")) {
+ console.warn(`[vault] ${relPath}: unreadable frontmatter — ${frontmatterError}`);
+ } else {
+ frontmatterError = undefined;
+ }
}
const slug = (relPath.split("/").pop() || relPath).replace(/\.md$/i, "");
@@ -125,6 +134,7 @@ export function parseNote(relPath: string, raw: string): ParsedNote {
updated:
data.updated != null ? String(data.updated) : data.date != null ? String(data.date) : undefined,
frontmatter: data,
+ frontmatterError,
};
return { meta, body, rawLinks: extractRawLinks(body, data) };
diff --git a/lib/vault/store.ts b/lib/vault/store.ts
index 0a3141a..4973ded 100644
--- a/lib/vault/store.ts
+++ b/lib/vault/store.ts
@@ -403,6 +403,7 @@ export function vaultConventions() {
const folders = new Set<string>();
const statuses = new Map<string, number>();
const types = new Set<string>();
+ const malformed: Array<{ path: string; error: string }> = [];
let archived = 0;
for (const n of s.notes.values()) {
@@ -410,6 +411,7 @@ export function vaultConventions() {
if (n.type) types.add(n.type);
if (n.status) statuses.set(n.status, (statuses.get(n.status) ?? 0) + 1);
if (isArchivedPath(n.path)) archived++;
+ if (n.frontmatterError) malformed.push({ path: n.path, error: n.frontmatterError });
}
return {
@@ -421,13 +423,19 @@ export function vaultConventions() {
.sort((a, b) => b[1] - a[1])
.map(([status, count]) => ({ status, count })),
ranking: authorityRules(),
- integrity:
- s.duplicateStems.size === 0
- ? { duplicateStems: [] }
- : {
- duplicateStems: [...s.duplicateStems.entries()].map(([stem, paths]) => ({ stem, paths })),
- warning: "Wikilinks to a duplicated stem resolve to the first path only. Rename one.",
- },
+ integrity: {
+ duplicateStems: [...s.duplicateStems.entries()].map(([stem, paths]) => ({ stem, paths })),
+ malformedFrontmatter: malformed,
+ ...(s.duplicateStems.size > 0
+ ? { duplicateStemWarning: "Wikilinks to a duplicated stem resolve to the first path only. Rename one." }
+ : {}),
+ ...(malformed.length > 0
+ ? {
+ malformedFrontmatterWarning:
+ "These notes open with `---` but their YAML is unparseable, so their status, tags and title are being ignored — they rank as ordinary notes regardless of what they claim. Usual cause: an unquoted `:` in a value. Fix by quoting it.",
+ }
+ : {}),
+ },
};
}
diff --git a/lib/vault/types.ts b/lib/vault/types.ts
index 1a013bc..b6faccb 100644
--- a/lib/vault/types.ts
+++ b/lib/vault/types.ts
@@ -14,6 +14,11 @@ export interface NoteMeta {
created?: string;
updated?: string;
frontmatter: Record<string, unknown>;
+ /**
+ * Set when the note opens with `---` but its YAML could not be parsed. The frontmatter is
+ * then entirely lost — status, tags, title — so the note silently loses its authority.
+ */
+ frontmatterError?: string;
mtimeMs: number;
}