Skip to content

A self-organizing Obsidian vault that gives AI coding agents persistent memory.

27.5 KB
Raw Blame
/**
 * The vault memory layer — write path.
 *
 * Pure functions over plain data, plus one thin IO shell (`writeMemory`), so the
 * epistemic contract can be hammered by tests without an MCP client, a vault on
 * disk, or a search index.
 *
 * WHY THIS IS SEPARATE FROM A WORK RECORD
 *
 * A *work record* ("what I did in this repo today") is single-valued by nature:
 * it belongs to the project it happened in, and it is a log entry. A *memory*
 * ("a tsup-external dependency can't be fixed by a local patch") is multi-valued
 * by nature: it transfers, and its whole worth is that a session in a DIFFERENT
 * repo can find it. One tool for both would force a single shape on two
 * artifacts and lose the facets that make the second findable.
 *
 * The routing test, stated for the model in the tool description: *would this
 * help someone working in a different repo?*
 */

import { mkdirSync, writeFileSync, readFileSync } from "node:fs";
import { join, dirname, basename } from "node:path";
import { claimFile } from "./atomic-write.ts";

/** Vault-relative root for every memory. Writes are confined to this prefix. */
export const MEMORY_ROOT = "memories";

/**
 * The `source` value that marks a file as agent-written.
 *
 * Here rather than beside the readers because this module is the one that
 * STAMPS it, and it already owns the store's on-disk contract. A reader can
 * import a constant the writer defines; the reverse would invert the dependency.
 */
export const MEMORY_SOURCE = "mcp-capture";

/**
 * The source a capture carries when the tool could not take it and the session
 * wrote the file itself.
 *
 * Recognised deliberately. `agentMemories` exists to leave a HUMAN note that
 * wandered into the memory folder alone, which is a good rule with one blind
 * spot: knowing exactly one value, it could not tell a wandering note from a
 * correctly-formed capture written by something other than the tool. A capture
 * in the second class has full facets, sits in the right folder, parses
 * cleanly, and was served by nothing — so the more honestly a file labelled its
 * own provenance, the more certainly it disappeared.
 *
 * That matters because the refusals are real: a tool call can be refused for a
 * reason the caller cannot repair by rewording, and a session holding a lesson
 * worth keeping will write the file rather than lose it. That is the right
 * call, and it should not cost the memory its entire audience.
 */
export const HAND_FILED_SOURCE = "hand-filed";

/** Sources marking a file as a deliberate agent capture rather than a stray note. */
export const AGENT_SOURCES: readonly string[] = [MEMORY_SOURCE, HAND_FILED_SOURCE];

export const SCOPES = ["general", "platform", "project"] as const;
export const CONFIDENCE = ["verified", "inferred", "unverified"] as const;

export type Scope = (typeof SCOPES)[number];
export type Confidence = (typeof CONFIDENCE)[number];

/** Filenames truncate here; long titles are still fine as the H1. */
const SLUG_MAX = 60;

/** A memory shorter than this is not a memory, it is a shrug. */
const MIN_BODY = 40;

/**
 * Windows refuses these as filename stems, with or without an extension. A vault
 * syncing across machines gets a corrupt file rather than an error, so they are
 * rewritten rather than rejected.
 */
const WINDOWS_RESERVED = /^(?:CON|PRN|AUX|NUL|COM[1-9]|LPT[1-9])$/i;

export interface MemoryInput {
	readonly title?: unknown;
	readonly body?: unknown;
	readonly confidence?: unknown;
	readonly verification?: unknown;
	readonly scope?: unknown;
	readonly generality?: unknown;
	readonly projects?: unknown;
	readonly platforms?: unknown;
}

export interface MemoryValue {
	readonly title: string;
	readonly body: string;
	readonly confidence: Confidence;
	readonly claimed_confidence: Confidence | null;
	readonly flags: string[];
	readonly verification: string | null;
	readonly generality: string | null;
	readonly scope: Scope;
	readonly projects: string[];
	readonly platforms: string[];
	readonly downgraded_from: Scope | null;
	readonly origin: string | null;
	readonly date: Date;
}

export interface ValidationResult {
	readonly ok: boolean;
	readonly errors: string[];
	readonly warnings: string[];
	readonly value: MemoryValue | null;
}

// ---------------------------------------------------------------------------
// Slug and path
// ---------------------------------------------------------------------------

/**
 * Filename-safe slug. Deliberately strict: the result is concatenated into a
 * path, so anything that could traverse (`..`), escape (`/`, `\`) or break a
 * filesystem (control chars, trailing dots) must not survive.
 */
export function slugify(title: unknown): string {
	let out = String(title ?? "")
		.normalize("NFKD")
		.replace(/[\u0300-\u036f]/g, "")
		.replace(/[<>:"|?*\u0000-\u001f]/g, " ")
		.replace(/[/\\]/g, " ")
		// Square brackets go too. A title carrying `[[Something]]` otherwise
		// produces a file literally named `... [[Something]].md`, which reads as a
		// wikilink embedded in a filename and confuses every surface showing it.
		//
		// `#` goes with them, and is the worse case of the two. It is the heading
		// separator, so `[[A note #7 landed]]` resolves to the note `A note ` and
		// the heading `7 landed`: a link that points somewhere else without ever
		// erroring, to a note that looks perfectly normal in every listing. The
		// alias written for a truncated title does not rescue it, because the
		// split happens before any alias lookup.
		//
		// **The class is the set of characters that terminate a wikilink target**,
		// which is `#`, `|`, `[` and `]`. `|` is absent here only because the
		// Windows-illegal class above already removes it, and that is coverage by
		// coincidence rather than by rule: if that class were ever narrowed, this
		// one would silently stop being complete. Stated here so the next reader
		// checks all four rather than the two that are visible.
		//
		// Replaced with a space rather than deleted, so `Flag #7 set` becomes
		// `Flag 7 set` and not `Flag7 set`. The whitespace collapse below tidies
		// the double space that leaves.
		//
		// The backtick is not a terminator, but it breaks a link the same way
		// from the other side: the link reader strips inline code before it
		// reads links (so a `[[x]]` inside code is not counted), and a code span
		// INSIDE `[[...]]` is stripped out of the target, leaving a name that
		// does not exist. Keeping code spans would bring that miscount back, so
		// the filename gives the backtick up instead.
		.replace(/[[\]#`]/g, " ")
		.replace(/\.{2,}/g, " ")
		.replace(/\s+/g, " ")
		.trim();

	if (out.length > SLUG_MAX) {
		out = out.slice(0, SLUG_MAX);
		const lastSpace = out.lastIndexOf(" ");
		if (lastSpace > SLUG_MAX * 0.6) out = out.slice(0, lastSpace);
		out = out.trim();
	}

	// NTFS silently strips trailing dots and spaces, producing a different file
	// than the one planned — fold them so path and reality agree.
	out = out.replace(/[. ]+$/, "");
	if (WINDOWS_RESERVED.test(out)) out = `_${out}`;
	return out;
}

/** `2026-07-26` from a Date, in the vault's local-date convention. */
export function isoDate(d: Date): string {
	const pad = (n: number): string => String(n).padStart(2, "0");
	return `${d.getFullYear()}-${pad(d.getMonth() + 1)}-${pad(d.getDate())}`;
}

/**
 * `memories/2026/07/2026-07-26 <slug>.md`
 *
 * Time is the ONLY thing in the path, because time is the only single-valued
 * fact about a memory. Two levels keeps any folder to a month's worth and the
 * tree at depth 3 — inside Obsidian's guidance, and matching the daily-note
 * convention users already recognise.
 */
export function memoryPath(date: Date, title: unknown, root: string = MEMORY_ROOT): string {
	const iso = isoDate(date);
	const [y, m] = iso.split("-");
	return `${root}/${y}/${m}/${iso} ${slugify(title)}.md`;
}

// ---------------------------------------------------------------------------
// Scope narrowing
// ---------------------------------------------------------------------------

/**
 * The caller proposes a scope; the server narrows it. Never widens.
 *
 * `general` is the only claim worth policing: widest blast radius, and the
 * cheapest thing for a session to over-claim. Because `projects` is a LIST, a
 * caller with a genuinely cross-project lesson can name them all honestly — so
 * an unjustified `general` is the one remaining way to over-reach, and the
 * origin repo is the evidence against it.
 *
 * The original claim is preserved: a downgrade that hides what was asked for is
 * a downgrade nobody can audit.
 */
export function narrowScope(input: {
	scope?: unknown;
	projects?: unknown;
	origin?: string | null;
}): { scope: Scope; projects: string[]; downgraded_from: Scope | null } {
	const claimed: Scope = (SCOPES as readonly string[]).includes(String(input.scope))
		? (input.scope as Scope)
		: "project";
	const named = Array.isArray(input.projects) ? (input.projects as unknown[]).filter(Boolean).map(String) : [];
	const origin = input.origin ?? null;

	// `general` is honest only when the memory names no project. If the caller
	// named projects, it is scoped to them by its own admission.
	if (claimed === "general" && named.length > 0) {
		return { scope: "project", projects: named, downgraded_from: "general" };
	}
	// `general` naming nothing STANDS.
	//
	// An earlier revision narrowed this to the origin repo, reasoning that one
	// session should not speak for the whole vault. The effect was that `general`
	// became UNREACHABLE through the server — every caller has an origin, so
	// every general memory silently became project-scoped to whoever wrote it.
	// The tier stayed in the reader, the tool schema, the Base view and the docs,
	// and nothing could ever produce it.
	//
	// It also contradicted the rule immediately above: general is honest exactly
	// WHEN no project is named, and this narrowed precisely that case. Declared
	// reach is the design; silently overriding an explicit declaration is not a
	// narrowing, it is a different memory. Over-claiming is answered by the
	// contract's warnings and by `origin` being recorded as evidence, not by
	// rewriting what the caller said.
	if (claimed === "project" && named.length === 0 && origin) {
		return { scope: "project", projects: [origin], downgraded_from: null };
	}
	return { scope: claimed, projects: named, downgraded_from: null };
}

// ---------------------------------------------------------------------------
// Link resolution
// ---------------------------------------------------------------------------

/**
 * Neutralise wikilinks in free text that point at notes which do not exist.
 *
 * `resolveLinks` below governs the `links:` ARRAY. This governs the BODY, and it
 * is needed for the same reason with a sharper consequence: a broken wikilink
 * anywhere in a note trips the vault's own wikilink gate, so an agent writing
 * `[[Some Note]]` from another repo can turn the user's test suite red in a
 * repository it has never seen.
 *
 * Neutralised rather than refused, and reported rather than silent. The text
 * survives as plain words — `[[Ghost]]` becomes `Ghost`, `[[Ghost|shown]]`
 * becomes `shown` — so the meaning is kept while the dangling edge is not
 * created. Refusing the whole write would throw away a good memory over a
 * formatting detail; writing it unchanged degrades the graph silently.
 */
export function neutralizeWikilinks(
	text: unknown,
	resolvableSet: ReadonlySet<string>,
): { text: string; dropped: string[] } {
	const dropped: string[] = [];
	const out = String(text ?? "").replace(
		/\[\[([^\]|#]+)((?:[#|][^\]]*)?)\]\]/g,
		(whole, rawTarget: string, suffix: string) => {
			const target = rawTarget.trim();
			if (resolvableSet.has(target.toLowerCase())) return whole;
			if (!dropped.includes(target)) dropped.push(target);
			// Prefer the alias, which is what a human was meant to read.
			const alias = suffix.startsWith("|") ? suffix.slice(1).trim() : "";
			return alias || target;
		},
	);
	return { text: out, dropped };
}

/**
 * Resolve proposed wikilink targets against names that actually exist.
 *
 * An MCP write bypasses the vault's own write-validation hook, so "never emit a
 * broken link" is re-implemented here. Unresolvable targets are dropped AND
 * reported — silently dropping would let a session believe it made a connection
 * it did not make.
 */
export function resolveLinks(
	proposed: unknown,
	resolvableSet: ReadonlySet<string>,
): { resolved: string[]; dropped: string[] } {
	const resolved: string[] = [];
	const dropped: string[] = [];
	const seen = new Set<string>();
	for (const raw of Array.isArray(proposed) ? proposed : []) {
		const name = String(raw ?? "").trim();
		if (!name) continue;
		const key = name.toLowerCase();
		if (seen.has(key)) continue;
		seen.add(key);
		if (resolvableSet.has(key)) resolved.push(name);
		else dropped.push(name);
	}
	return { resolved, dropped };
}

// ---------------------------------------------------------------------------
// The epistemic contract, as data
// ---------------------------------------------------------------------------

const HAPPENING =
	"break|breaks|broke|fail|fails|failed|crash|crashes|crashed|hang|hangs|error|errors|happen|happens|recover|recovers|work|works|worked";

// String.raw, NOT a plain template literal: in a template literal `\b` is the
// BACKSPACE character, so `new RegExp` would be handed a control char instead of
// a word boundary and the rule could never fire — silently. This bit once
// already, which is why every pattern here has a known-NEGATIVE test as well as
// a positive one.
const RECURRENCE = new RegExp(
	String.raw`\b(?:always|never)\b[^.!?]{0,40}\b(?:${HAPPENING})\b` +
		String.raw`|\bevery\s+time\b` +
		String.raw`|\bkeeps?\s+(?:on\s+)?(?:happening|breaking|failing|crashing)\b` +
		String.raw`|\brecurring\b` +
		String.raw`|\bconsistently\s+(?:${HAPPENING})\b`,
	"i",
);

const VOLATILE = /\b\d[\d,._]*\s*(stars?|forks?|downloads?|users?|subscribers?|followers?|commits?)\b/i;
const DATE_ANCHOR = /\bas of\b|\d{4}-\d{2}-\d{2}/i;
const SPEAKER = /^\s*(user|assistant|human|ai|system)\s*:/gim;

export interface ContractRule {
	readonly id: string;
	readonly severity: "reject" | "flag";
	readonly marker?: string;
	readonly test: (body: string) => boolean;
	readonly message: string;
}

/**
 * Rules as a list so a vault can extend, disable or reorder them without forking
 * the validator. Each declares its own severity, and that choice is the design:
 *
 *   reject — the artifact is structurally wrong. Nothing is written.
 *   flag   — the CLAIM is weak. The memory IS written, confidence is capped at
 *            `inferred`, and a marker lands in frontmatter for a review view.
 *
 * The first version rejected on prose judgements and immediately refused its own
 * canonical example: "the patch NEVER reaches them" is a deterministic
 * consequence, not a claim of recurrence. That is the argument against blocking
 * on prose — a false reject destroys knowledge the session already had, while a
 * false flag costs one line of frontmatter. Severity chosen accordingly, which
 * also means these patterns do not need to be perfect.
 */
export const CONTRACT_RULES: readonly ContractRule[] = [
	{
		id: "transcript",
		severity: "reject",
		// Structural, not a judgement: a transcript is a different artifact. The
		// threshold is high so a memory QUOTING one exchange is unaffected.
		test: (body) => (body.match(SPEAKER) ?? []).length >= 4,
		message:
			"body looks like a transcript. A memory is a conclusion, not a log — record what was learned, not the conversation that produced it.",
	},
	{
		id: "recurrence",
		severity: "flag",
		marker: "generalised",
		test: (body) => RECURRENCE.test(body),
		message:
			"body generalises over occurrences (always / every time / keeps failing). One session sees one occurrence, so confidence is capped at `inferred` — state the occurrence with its date and let the vault decide it is a pattern.",
	},
	{
		id: "undated-volatile",
		severity: "flag",
		marker: "volatile",
		test: (body) => VOLATILE.test(body) && !DATE_ANCHOR.test(body),
		message:
			'body states a figure that rots with no date anchor. Add "as of <date>" so staleness is visible instead of silent; the memory is flagged `volatile` until then.',
	},
];

/** Run the contract. Pure: returns verdicts, changes nothing. */
export function applyContract(
	body: string,
	rules: readonly ContractRule[] = CONTRACT_RULES,
): { rejections: string[]; flags: { id: string; marker: string; message: string }[] } {
	const rejections: string[] = [];
	const flags: { id: string; marker: string; message: string }[] = [];
	for (const rule of rules) {
		let hit = false;
		try {
			hit = Boolean(rule.test(body));
		} catch {
			// A broken custom rule must not take the whole write down.
			continue;
		}
		if (!hit) continue;
		if (rule.severity === "reject") rejections.push(rule.message);
		else flags.push({ id: rule.id, marker: rule.marker ?? rule.id, message: rule.message });
	}
	return { rejections, flags };
}

// ---------------------------------------------------------------------------
// Validation
// ---------------------------------------------------------------------------

export function validateMemory(
	input: MemoryInput | null | undefined,
	ctx: { now?: Date; origin?: string | null; rules?: readonly ContractRule[] } = {},
): ValidationResult {
	const errors: string[] = [];
	const warnings: string[] = [];

	const title = String(input?.title ?? "").trim();
	const body = String(input?.body ?? "").trim();
	const now = ctx.now instanceof Date ? ctx.now : new Date();

	if (!title) errors.push("title is required");
	else if (title.length > 200) errors.push("title is too long (max 200 chars)");
	else if (!slugify(title)) {
		errors.push(
			`title ${JSON.stringify(title)} contains no characters usable in a filename — give it a title with letters or digits`,
		);
	}

	if (!body) errors.push("body is required");
	else if (body.length < MIN_BODY) {
		errors.push(
			`body is ${body.length} chars; a memory needs at least ${MIN_BODY}. Write it for a session that will not have your context.`,
		);
	}

	const confidence = String(input?.confidence ?? "").trim();
	if (!(CONFIDENCE as readonly string[]).includes(confidence)) {
		errors.push(`confidence must be one of ${CONFIDENCE.join(" | ")}`);
	}

	if (input?.scope !== undefined && !(SCOPES as readonly string[]).includes(String(input.scope))) {
		errors.push(`scope must be one of ${SCOPES.join(" | ")}`);
	}

	for (const field of ["projects", "platforms"] as const) {
		const v = input?.[field];
		if (v === undefined || v === null) continue;
		if (!Array.isArray(v)) {
			errors.push(`${field} must be an array (it is the multi-valued axis)`);
			continue;
		}
		for (const item of v as unknown[]) {
			if (typeof item !== "string" || !/^[\w.-]+$/.test(item)) {
				errors.push(`${field} entries must be simple slugs; got ${JSON.stringify(item)}`);
			}
		}
	}

	const { rejections, flags } = applyContract(body, ctx.rules ?? CONTRACT_RULES);
	errors.push(...rejections);
	for (const f of flags) warnings.push(f.message);

	if (body.length > 8000) {
		warnings.push(`body is ${body.length} chars. Memories are atomic; consider splitting into separate lessons.`);
	}
	if (confidence === "verified" && !input?.verification) {
		warnings.push(
			'confidence is "verified" but no verification was given. Say how you know — otherwise "inferred" is the honest value.',
		);
	}

	if (errors.length) return { ok: false, errors, warnings, value: null };

	const narrowed = narrowScope({
		scope: input?.scope ?? "project",
		projects: input?.projects,
		origin: ctx.origin ?? null,
	});
	const platformsGiven = Array.isArray(input?.platforms)
		? (input.platforms as unknown[]).filter(Boolean).map(String)
		: [];

	// REFUSE A MEMORY THAT WOULD REACH NOBODY.
	//
	// A project-scoped memory naming no projects is invisible to every caller:
	// the visibility rule has nothing to match on. It would validate, write,
	// index and report success — and be unreachable forever. The hole is a caller
	// with neither identity nor named projects, i.e. a client that never answered
	// `roots/list`, which is an observed state rather than a theoretical one.
	//
	// Refusing beats widening to `general`: scope IS reach, and granting the
	// widest possible reach because the narrowest could not be determined is the
	// exact opposite of what narrowing exists to do.
	if (narrowed.scope === "project" && narrowed.projects.length === 0) {
		return {
			ok: false,
			errors: [
				'This memory would reach nobody: it is project-scoped, names no projects, and the caller has no identity (no MCP roots). Name the projects it applies to, or pass scope: "general" if it genuinely applies everywhere.',
			],
			warnings,
			value: null,
		};
	}
	if (narrowed.scope === "platform" && platformsGiven.length === 0) {
		return {
			ok: false,
			errors: [
				'This memory would reach nobody: it is platform-scoped but names no platforms. List them, or use scope: "project" with the projects it applies to.',
			],
			warnings,
			value: null,
		};
	}

	// OVER-CLAIMED REACH IS ANSWERED HERE, AND ONLY HERE.
	//
	// Sibling of the `verified`-without-`verification` warning above, and the same
	// severity on purpose. Narrowing `general` by inspecting content was tried and
	// reverted (see `narrowScope`): declared reach is the caller's to declare, and
	// over-claiming is answered by warnings and by `origin` as evidence, never by
	// rewriting what the caller said. This asks for the reasoning instead.
	//
	// Keyed on the NARROWED scope, not the claimed one. A caller who says
	// `general` and names projects has already been downgraded to `project` by
	// their own admission, and warning them about generality would be noise.
	if (narrowed.scope === "general" && !input?.generality) {
		warnings.push(
			'scope is "general" but no generality was given. Say why it reaches everywhere: a dependency, language or toolchain lesson is "platform", however hard-won.',
		);
	}

	const capped = flags.length && confidence === "verified";
	return {
		ok: true,
		errors,
		warnings,
		value: {
			title,
			body,
			// A flagged claim cannot stay `verified` regardless of what the caller
			// asserted: the flag exists precisely because the claim outruns what one
			// session can know. Capping is the enforcement; the marker is the audit.
			confidence: capped ? "inferred" : (confidence as Confidence),
			claimed_confidence: capped ? "verified" : null,
			flags: flags.map((f) => f.marker),
			verification: input?.verification ? String(input.verification).trim() : null,
			generality: input?.generality ? String(input.generality).trim() : null,
			scope: narrowed.scope,
			projects: narrowed.projects,
			platforms: platformsGiven,
			downgraded_from: narrowed.downgraded_from,
			origin: ctx.origin ?? null,
			date: now,
		},
	};
}

// ---------------------------------------------------------------------------
// Render
// ---------------------------------------------------------------------------

/** YAML-safe double-quoted scalar. Frontmatter that fails to parse is invisible. */
function yamlString(s: unknown): string {
	return JSON.stringify(String(s));
}

function yamlList(items: readonly string[]): string {
	return `[${items.map((i) => yamlString(i)).join(", ")}]`;
}

/**
 * ~150-char description, the vault-wide requirement. Derived from the body's
 * first sentence so it is always present without asking the caller for it.
 */
export function deriveDescription(body: string): string {
	const flat = body.replace(/\s+/g, " ").trim();
	const firstStop = flat.search(/[.!?]\s/);
	let out = firstStop > 40 ? flat.slice(0, firstStop + 1) : flat;
	if (out.length > 150) {
		out = out.slice(0, 150);
		const lastSpace = out.lastIndexOf(" ");
		if (lastSpace > 100) out = out.slice(0, lastSpace);
		out = `${out.trim()}…`;
	}
	return out;
}

export function renderMemory(value: MemoryValue, links: readonly string[] = []): string {
	const fm = [
		"---",
		`date: ${isoDate(value.date)}`,
		`description: ${yamlString(deriveDescription(value.body))}`,
		"tags: [memory]",
		`source: ${MEMORY_SOURCE}`,
		`origin: ${yamlString(value.origin ?? "unknown")}`,
		`session: ${yamlString(value.date.toISOString())}`,
		`scope: ${value.scope}`,
		`projects: ${yamlList(value.projects)}`,
	];
	if (value.platforms.length) fm.push(`platforms: ${yamlList(value.platforms)}`);
	// An alias whenever the filename cannot carry the whole title.
	//
	// `slugify` truncates at SLUG_MAX and the comment there says a long title is
	// "still fine as the H1" — true for READING, false for LINKING. Obsidian
	// resolves a link target against filenames and aliases; an H1 is never a link
	// target. So a memory whose title outran the slug could not be cited by the
	// one string anyone would naturally use: its own stated claim.
	//
	// Titles run long as a RULE rather than as an exception here, because the
	// `remember` contract asks for the lesson "stated as a claim" and a
	// claim-shaped sentence passes 60 characters more often than not.
	//
	// Emitted only when the slug actually lost something, so a short-titled
	// memory keeps the frontmatter it has always had and no existing note churns.
	if (slugify(value.title) !== value.title) fm.push(`aliases: ${yamlList([value.title])}`);
	fm.push(`confidence: ${value.confidence}`);
	if (value.claimed_confidence) fm.push(`claimed_confidence: ${value.claimed_confidence}`);
	// Markers make the contract operational: a Base can list every weak claim in
	// the vault without re-reading a single body.
	if (value.flags.length) fm.push(`flags: ${yamlList(value.flags)}`);
	if (value.downgraded_from) fm.push(`claimed_scope: ${value.downgraded_from}`);
	fm.push("---", "");

	const parts = [fm.join("\n"), `# ${value.title}`, "", value.body, ""];
	if (value.verification) parts.push("## How this is known", "", value.verification, "");
	// Rendered rather than kept in frontmatter: a reach claim is an argument, and a
	// later reader has to be able to judge it the same way they judge the evidence.
	if (value.generality) parts.push("## Why this reaches everywhere", "", value.generality, "");
	// A note without links is a bug — the vault's own doctrine. Links are the only
	// way a memory reaches the project it is about, since it does not live inside
	// that project's folder.
	if (links.length) parts.push("## Related", "", ...links.map((l) => `- [[${l}]]`), "");
	return parts.join("\n");
}

// ---------------------------------------------------------------------------
// IO shell
// ---------------------------------------------------------------------------

/**
 * Write the memory. The only impure function here.
 *
 * Collision handling matters more than it looks: two memories captured the same
 * day with the same title would otherwise silently overwrite, and the loser is
 * unrecoverable. Suffix rather than clobber.
 */
export function writeMemory(
	vaultRoot: string,
	value: MemoryValue,
	links: readonly string[],
	{ root = MEMORY_ROOT }: { root?: string } = {},
): { rel: string; full: string } {
	const base = memoryPath(value.date, value.title, root).replace(/\.md$/, "");
	const dir = dirname(join(vaultRoot, `${base}.md`));
	mkdirSync(dir, { recursive: true });
	const body = renderMemory(value, links);

	// Claimed atomically rather than checked-then-written; see `atomic-write.ts`
	// for why, and for what the naive version cost.
	const claimed = claimFile(dir, body, (n) => `${basename(base)}${n === 1 ? "" : ` (${n})`}.md`, {
		exhaustedMessage: "too many same-titled memories on one day",
	});
	return { rel: `${dirname(base)}/${claimed.name}`.replace(/\\/g, "/"), full: claimed.full };
}

/** Read back what was written — used by tests and the post-write self-check. */
export function readMemory(vaultRoot: string, rel: string): string {
	return readFileSync(join(vaultRoot, rel), "utf8");
}