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.
TypeScript agent-memoryai-agentsanthropicclaude-codecursorgitknowledge-baseknowledge-graphllmmarkdownmcpmcp-servermodel-context-protocolnote-takingobsidianpkmragsecond-brainself-hostedzettelkasten
import fsp from "node:fs/promises";
import path from "node:path";
import matter from "gray-matter";
import { activeVaultDir } from "@/lib/repos";
import { refreshPaths, getNote } from "./store";
import { humanize, stemOf } from "./parse";
import { checkFrontmatter, frontmatterErrorMessage } from "./validate";
import { guardConflict } from "./conflict";
import { resolveInVault } from "./paths";
import { requestSync } from "@/lib/git";
import { currentActor } from "@/lib/actor";
/** Resolve a vault-relative path to an absolute path in the active vault, refusing escapes. */
function safeAbs(relPath: string): string {
return resolveInVault(activeVaultDir(), relPath);
}
export function normalizeNotePath(relPath: string): string {
const p = relPath.replace(/\\/g, "/").replace(/^\/+/, "").replace(/\.\.(\/|$)/g, "");
return /\.md$/i.test(p) ? p : `${p}.md`;
}
/**
* Re-index only what changed, then queue a git commit stamped with who caused it.
* The actor prefix is what turns the Activity feed into an audit trail rather than a
* list of anonymous edits. `touched` are vault-relative paths.
*/
function after(message: string, touched: string[]) {
refreshPaths(touched);
requestSync(`${currentActor()}: ${message}`);
}
export interface WriteOpts {
/**
* Reject the write when the frontmatter cannot be parsed back.
* True for agents (MCP) — a machine has no excuse for emitting broken YAML, and a corrupt
* note silently loses its authority. False for the dashboard editor, where a human may save
* a half-typed document; they get a warning instead of losing their work.
*/
strict?: boolean;
/**
* Permit a write that destroys most of an existing note. Default false for agents.
* A human in the editor is looking at what they're deleting; an agent usually is not.
*/
allowShrink?: boolean;
/**
* Permit creating a note that duplicates a live note's subject. Default false for agents.
* See `guardConflict` — the common failure is an agent adding a second live price note
* instead of superseding the first.
*/
allowConflict?: boolean;
}
/** An existing note this size or larger is worth protecting from an accidental truncation. */
const SHRINK_FLOOR_BYTES = 400;
/** Replacing a note with less than this fraction of its content looks like an accident. */
const SHRINK_RATIO = 0.3;
/**
* Refuse to replace a substantial note with a stub.
*
* A real incident: an agent was told "replace {{BOOKING_LINK}} in this file", and wrote that
* *instruction* into the file as its entire contents — destroying a 5.6KB snippet library.
* `writeNote` overwrites blind, so nothing stopped it. Overwriting is legitimate (an agent
* reads a note and writes it back), but collapsing 5.6KB to 170 bytes is a mistake worth
* refusing until someone says they meant it.
*/
async function guardTruncation(abs: string, relPath: string, next: string, allowShrink: boolean): Promise<void> {
if (allowShrink) return;
let existing: string;
try {
existing = await fsp.readFile(abs, "utf8");
} catch {
return; // new note — nothing to destroy
}
if (existing.length < SHRINK_FLOOR_BYTES) return;
if (next.length >= existing.length * SHRINK_RATIO) return;
throw new Error(
`Refusing to write ${relPath}: it would shrink from ${existing.length} to ${next.length} bytes, ` +
`discarding most of the note. Read it first (brain_read) and write back the full content you intend to keep. ` +
`To append, use brain_append. If you really mean to replace it, pass overwrite: true.`,
);
}
/**
* Structural read-before-overwrite. Not a size heuristic like `guardTruncation` — this refuses the
* write outright until the caller has actually opened the note, so a same-size clobber is caught
* too. Returns an error message for the model, or null to proceed.
*
* Shared by the Curator loop (which tracks reads per run) and the MCP tools (which track them per
* caller — see lib/mcp/session.ts). It used to live only in the loop, which left the surface that
* matters most, a coding agent writing over MCP, protected by the size heuristic alone.
*/
export function guardOverwrite(toolName: string, target: string, hasRead: (p: string) => boolean): string | null {
if (toolName !== "brain_write" && toolName !== "brain_edit") return null;
if (!target || hasRead(target)) return null;
let exists = false;
try {
exists = getNote(normalizeNotePath(target)) !== null;
} catch {
return null;
}
if (!exists) return null;
return `${target} already exists and you have not read it in this session. Call brain_read("${target}") first, then write back the full content you intend to keep — or use brain_append to add to it.`;
}
async function fileExists(abs: string): Promise<boolean> {
try {
await fsp.access(abs);
return true;
} catch {
return false;
}
}
/** Write a note from a raw markdown string (frontmatter included). Used by the editor. */
export async function writeNoteRaw(relPath: string, content: string, opts: WriteOpts = {}): Promise<string> {
const p = normalizeNotePath(relPath);
if (opts.strict) {
const check = checkFrontmatter(content);
if (!check.ok) throw new Error(frontmatterErrorMessage(p, check.error!));
}
const abs = safeAbs(p);
// Agents only. A human in the editor who names a note `pricing-2026` next to `pricing` can see
// both in the sidebar and meant it; an agent usually has not looked.
if (opts.strict) guardConflict(p, !(await fileExists(abs)), opts.allowConflict === true);
await guardTruncation(abs, p, content, opts.allowShrink === true);
await fsp.mkdir(path.dirname(abs), { recursive: true });
await fsp.writeFile(abs, content, "utf8");
after(`edit ${p}`, [p]);
return p;
}
/**
* Write a note from a body + optional frontmatter object. Used by agents (MCP) and the harness.
* `matter.stringify` serialises the object, so the YAML always parses — this path cannot
* produce the corruption that hand-written frontmatter can.
*/
export async function writeNote(
relPath: string,
body: string,
frontmatter?: Record<string, unknown>,
opts: WriteOpts = {},
): Promise<string> {
const content =
frontmatter && Object.keys(frontmatter).length > 0 ? matter.stringify(body ?? "", frontmatter) : (body ?? "");
return writeNoteRaw(relPath, content, { ...opts, strict: true });
}
/**
* Append text to a note, creating it if missing.
*
* Refuses an empty append. `writeNote` has always refused to create an empty note; this path did
* not, so an append whose payload never arrived wrote `existing + "\n"` and reported success — a
* blank line where a log entry should have been (the 2026-08-06 incident). An append with nothing
* to append is never intentional, and the write path must not be the layer that discovers this
* quietly.
*/
export async function appendNote(relPath: string, text: string): Promise<string> {
const p = normalizeNotePath(relPath);
if (typeof text !== "string" || text.trim() === "") {
throw new Error(
`Nothing to append to ${p}: \`text\` was empty. Pass the markdown to append as \`text\` ` +
`(brain_append takes \`text\`, not \`content\` or \`body\`). The note was not modified.`,
);
}
const abs = safeAbs(p);
let existing = "";
try {
existing = await fsp.readFile(abs, "utf8");
} catch {
/* new file */
}
await fsp.mkdir(path.dirname(abs), { recursive: true });
const sep = existing && !existing.endsWith("\n") ? "\n" : "";
await fsp.writeFile(abs, `${existing}${sep}${text}\n`, "utf8");
after(`append ${p}`, [p]);
return p;
}
export async function moveNote(from: string, to: string): Promise<string> {
const a = safeAbs(normalizeNotePath(from));
const b = safeAbs(normalizeNotePath(to));
await fsp.mkdir(path.dirname(b), { recursive: true });
await fsp.rename(a, b);
after(`move ${from} -> ${to}`, [normalizeNotePath(from), normalizeNotePath(to)]);
return normalizeNotePath(to);
}
export async function deleteNote(relPath: string): Promise<void> {
await fsp.rm(safeAbs(normalizeNotePath(relPath)));
after(`delete ${relPath}`, [normalizeNotePath(relPath)]);
}
/**
* Atomically retire OLD in favor of NEW, in a single commit.
*
* This is the "add and retire can't drift apart" primitive. It marks the old note superseded
* *in place* (frontmatter only — body preserved, so backlinks and chronology survive and the
* truncation guard never trips), ensures the replacement exists, and records both in ONE `after()`
* call so git-sync produces exactly one commit (the `moveNote` atomicity pattern). Query-time
* search then withholds the old note with the reason "superseded by <new>".
*
* Uses raw `fsp` writes deliberately — `writeNote`/`appendNote` each call `after()` themselves,
* which would split the operation across two commits.
*/
export async function supersedeNote(
from: string,
to: string,
reason?: string,
body?: string,
): Promise<{ from: string; to: string }> {
const fromPath = normalizeNotePath(from);
const toPath = normalizeNotePath(to);
if (fromPath === toPath) throw new Error("supersede: `from` and `to` must be different notes.");
const fromAbs = safeAbs(fromPath);
const toAbs = safeAbs(toPath);
let oldRaw: string;
try {
oldRaw = await fsp.readFile(fromAbs, "utf8");
} catch {
throw new Error(`Cannot supersede ${fromPath}: it does not exist.`);
}
// Refuse rather than silently rewrite a note whose YAML is already broken.
const check = checkFrontmatter(oldRaw);
if (!check.ok) {
throw new Error(`Refusing to supersede ${fromPath}: its frontmatter is already unparseable (${check.error}). Fix it first.`);
}
const toStem = stemOf(toPath);
const fromStem = stemOf(fromPath);
const today = new Date(Date.now()).toISOString().slice(0, 10);
// 1. Mark OLD superseded in place — frontmatter only, body verbatim.
const g = matter(oldRaw);
const data: Record<string, unknown> = { ...(g.data as Record<string, unknown>) };
data.status = "superseded";
data.superseded_by = `[[${toStem}]]`;
data.superseded_at = today;
if (reason) data.superseded_reason = reason;
const oldOut = matter.stringify(g.content, data);
// 2. Prepare NEW if it doesn't exist yet (from `body`, or a minimal stub linking back).
let newContent: string | null = null;
try {
await fsp.access(toAbs);
} catch {
if (body && body.trim().startsWith("---")) {
const bc = checkFrontmatter(body);
if (!bc.ok) throw new Error(`supersede: the replacement's frontmatter is invalid (${bc.error}). Pass a plain body, or valid YAML.`);
newContent = body;
} else {
newContent = matter.stringify(body?.trim() || `Supersedes [[${fromStem}]]${reason ? ` — ${reason}` : ""}.`, {
title: humanize(toStem),
supersedes: `[[${fromStem}]]`,
});
}
}
// 3. Write both, then one after() → one refreshPaths + one commit.
await fsp.mkdir(path.dirname(fromAbs), { recursive: true });
await fsp.writeFile(fromAbs, oldOut, "utf8");
if (newContent !== null) {
await fsp.mkdir(path.dirname(toAbs), { recursive: true });
await fsp.writeFile(toAbs, newContent, "utf8");
}
after(`supersede ${fromPath} -> ${toPath}${reason ? `: ${reason}` : ""}`, [fromPath, toPath]);
return { from: fromPath, to: toPath };
}
export async function createFolder(relPath: string): Promise<string> {
const p = relPath.replace(/\\/g, "/").replace(/^\/+|\/+$/g, "").replace(/\.\.(\/|$)/g, "");
const abs = safeAbs(p);
await fsp.mkdir(abs, { recursive: true });
await fsp.writeFile(path.join(abs, ".gitkeep"), "", "utf8");
requestSync(`${currentActor()}: mkdir ${p}`);
return p;
}