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.

feat(validity): capture supersedes colliding facts; manifest reports it

Ronalds Palacis1619ebe1c681
diff --git a/components/curator-chat.tsx b/components/curator-chat.tsx
index 76a31de..ca6bab1 100644
--- a/components/curator-chat.tsx
+++ b/components/curator-chat.tsx
@@ -17,6 +17,7 @@ interface Manifest {
updated: string[];
appended: string[];
moved: string[];
+ superseded: string[];
}
interface Msg {
@@ -34,8 +35,12 @@ function changeSummary(m?: Manifest): { label: string; paths: string[] } | null
if (m.updated.length) parts.push(`updated ${m.updated.length}`);
if (m.appended.length) parts.push(`appended ${m.appended.length}`);
if (m.moved.length) parts.push(`moved ${m.moved.length}`);
+ if (m.superseded?.length) parts.push(`superseded ${m.superseded.length}`);
if (!parts.length) return null;
- return { label: parts.join(" · "), paths: [...m.created, ...m.updated, ...m.appended, ...m.moved] };
+ return {
+ label: parts.join(" · "),
+ paths: [...m.created, ...m.updated, ...m.appended, ...m.moved, ...(m.superseded ?? [])],
+ };
}
export function CuratorChat() {
diff --git a/lib/agent.ts b/lib/agent.ts
index cd9370f..d0086b2 100644
--- a/lib/agent.ts
+++ b/lib/agent.ts
@@ -33,6 +33,8 @@ export interface Manifest {
updated: string[];
appended: string[];
moved: string[];
+ /** Notes retired via brain_supersede (their replacements land in `created`). */
+ superseded: string[];
}
export type AgentEvent =
@@ -67,10 +69,11 @@ const toAnthropicTool = (t: Tool): Anthropic.Tool => ({
const SHARED_RULES = `
Rules that hold on every turn:
- Ground every claim in the notes. Use brain_search to find them, brain_read to read them. Never invent a fact about this vault; if it isn't written down, say so.
-- Search ranks by keyword relevance, NOT by truth. Every result carries an "authority": authoritative > current > provisional > superseded > archived. Prefer the authoritative note. Never present a superseded, archived, or provisional note as current fact.
-- Compose freely for context and history. But a single-valued fact — a price, a guarantee, a legal entity, a contract term — has exactly one owning note. Do not merge sources for those, and never average two notes that disagree: that is a defect in the vault. Report it.
+- brain_search returns { hits, excluded }. Read hits; scan excluded for notes withheld as superseded/expired/archived. When you deliberately skip a stale note, say so and cite its excluded reason — never quote it as current.
+- Ranking is by relevance, NOT truth. Every hit carries an "authority": authoritative > current > provisional > superseded > archived. Prefer the authoritative note. Never present a superseded, archived, or provisional note as current fact.
+- A single-valued fact — a price, a guarantee, a legal entity, a contract term — has exactly one owning note. Do not merge sources for those, and never average two live notes that disagree: that is a defect in the vault. Report it.
- Read a note before you overwrite it. Writing a note you have not read destroys whatever was there.
-- Nothing is ever deleted. When a note stops being true, brain_move it into archive/ and leave a pointer in whatever replaced it.
+- When a fact changes, use brain_supersede(old, new) — it retires the old note and links the new one atomically, so search stops surfacing the dead value. Nothing is ever deleted.
`.trim();
const CHAT_PROMPT = `You are the Curator — the resident agent of this markdown "second brain". You help the operator recall, connect, and reason over their own notes.
@@ -91,8 +94,8 @@ How to work:
2. brain_search for what already exists on this subject. Do not skip this: filing a duplicate is worse than filing nothing.
3. Then decide, deliberately:
- Nothing exists → brain_write a new note at a sensible path.
- - A note covers this already → brain_read it, then brain_append the new material, or brain_edit it with the FULL merged content.
- - The dump supersedes an existing note → brain_move the old one into archive/ and write the replacement with a pointer to what it replaced.
+ - A note covers this already, and the dump ADDS to it → brain_read it, then brain_append the new material (or brain_edit with the FULL merged content).
+ - The dump CHANGES a fact an existing note states (a new price, a revised term) → brain_supersede(from: old-note, to: new-note, reason, body). One call retires the old note and creates/links the new one atomically. Do NOT just brain_write a second note — the old value would keep surfacing in search.
4. Prefer passing a \`frontmatter\` object plus a plain \`body\` over hand-writing YAML — it always parses.
5. Finish with one short sentence saying what you did and why. No preamble.
@@ -157,7 +160,7 @@ export async function* agentStream(opts: AgentOpts): AsyncGenerator<AgentEvent>
const model = opts.model && SUPPORTED_MODEL_IDS.has(opts.model) ? opts.model : DEFAULT_CURATOR_MODEL;
const client = new Anthropic({ apiKey });
- const manifest: Manifest = { created: [], updated: [], appended: [], moved: [] };
+ const manifest: Manifest = { created: [], updated: [], appended: [], moved: [], superseded: [] };
/** Paths this run has actually read. The loop may not overwrite a note it hasn't opened. */
const readPaths = new Set<string>();
@@ -187,6 +190,19 @@ export async function* agentStream(opts: AgentOpts): AsyncGenerator<AgentEvent>
const out = await withActor(opts.actor ?? "curator", () => tool.handler(input));
if (name === "brain_read" && target) readPaths.add(target);
+
+ // brain_supersede touches two notes: the retired one and its replacement.
+ if (name === "brain_supersede" && out && typeof out === "object" && "from" in out && "to" in out) {
+ const from = String((out as { from: unknown }).from);
+ const to = String((out as { to: unknown }).to);
+ if (!manifest.superseded.includes(from)) manifest.superseded.push(from);
+ const toBucket: keyof Manifest = readPaths.has(to) ? "updated" : "created";
+ if (!manifest[toBucket].includes(to)) manifest[toBucket].push(to);
+ readPaths.add(from);
+ readPaths.add(to);
+ return out;
+ }
+
const kind = MUTATION_KIND[name];
if (kind && out && typeof out === "object" && "path" in out) {
const p = String((out as { path: unknown }).path);
diff --git a/lib/harness.ts b/lib/harness.ts
index d414c6a..f480cd6 100644
--- a/lib/harness.ts
+++ b/lib/harness.ts
@@ -27,7 +27,7 @@ export async function captureNote(rough: string): Promise<CaptureResult> {
const prompt = `Today is ${today}.\n\n${captureContext()}\n\nRough note to file:\n"""\n${rough}\n"""`;
let summary = "";
- let manifest: Manifest = { created: [], updated: [], appended: [], moved: [] };
+ let manifest: Manifest = { created: [], updated: [], appended: [], moved: [], superseded: [] };
let failure = "";
for await (const ev of agentStream({
@@ -47,8 +47,14 @@ export async function captureNote(rough: string): Promise<CaptureResult> {
if (failure) throw new Error(failure);
// The dashboard opens one note after a capture; prefer what was created, then what was changed.
+ // A retired note (superseded) is last — the live replacement is already in `created`.
const primary =
- manifest.created[0] ?? manifest.updated[0] ?? manifest.appended[0] ?? manifest.moved[0] ?? "";
+ manifest.created[0] ??
+ manifest.updated[0] ??
+ manifest.appended[0] ??
+ manifest.moved[0] ??
+ manifest.superseded[0] ??
+ "";
if (!primary) {
throw new Error(`capture wrote nothing. The model said: ${summary.trim() || "(nothing)"}`);
}