Skip to content

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

fix: stop remember refusing a correction that passes supersedes (#336)

yi1110e5c0ce65986
diff --git a/.claude/scripts/lib/mcp-server.ts b/.claude/scripts/lib/mcp-server.ts
index 9aa560f..33d900f 100644
--- a/.claude/scripts/lib/mcp-server.ts
+++ b/.claude/scripts/lib/mcp-server.ts
@@ -525,24 +525,14 @@ export function createHandlers(deps: ServerDeps): Handlers {
const digests = digestsFrom(storeFresh());
- // Near-duplicate suppression, facet-gated so two projects can each hold
- // their own copy of the same lesson.
- if (args.force !== true) {
- const { duplicates } = findSimilar(v.value, digests);
- if (duplicates.length) {
- const d = duplicates[0]!;
- return [
- `Not recorded: a near-identical memory already exists (${Math.round(d.score * 100)}% similar).`,
- ` ${d.entry.title}`,
- ` ${d.entry.rel}`,
- "",
- "If this genuinely differs, pass force: true. If it CORRECTS that memory,",
- "pass supersedes: [\"<its exact title>\"] instead — the old one is kept and back-linked.",
- ].join("\n");
- }
- }
-
- const { resolved, dropped } = resolveLinks(args.links, resolvable);
+ // Resolved BEFORE the duplicate check, because a correction is by nature a
+ // near-copy of what it corrects: same subject, one value or one cause
+ // changed. A check that ran first asked "is this a restatement?" of a
+ // memory the caller had already named as replaced, then told the caller to
+ // pass supersedes — which they had. The named targets drop out of the
+ // comparison; every OTHER memory stays in it, so a correction that also
+ // duplicates a third note is still refused, which is the check working.
+ //
// Only what recall serves this caller (#364). A title can name a memory
// scoped to another project, or one recall already withholds; marking it
// would withhold it from its own project's callers, whose only replacement
@@ -558,6 +548,48 @@ export function createHandlers(deps: ServerDeps): Handlers {
args.supersedes,
digests.filter((d) => served.has(d.rel)),
);
+ const superseded = new Set(supers.matched.map((m) => m.rel));
+
+ // Near-duplicate suppression, facet-gated so two projects can each hold
+ // their own copy of the same lesson.
+ if (args.force !== true) {
+ const { duplicates } = findSimilar(
+ v.value,
+ digests.filter((d) => !superseded.has(d.rel)),
+ );
+ if (duplicates.length) {
+ const d = duplicates[0]!;
+ // When the caller DID pass supersedes and NONE of them resolved,
+ // repeating "pass supersedes" is an instruction they already followed
+ // and cannot follow successfully — the title they named does not exist.
+ // Say which ones did not resolve, and point at the exact-match rule,
+ // instead of sending them round the loop a second time.
+ // If at least one title DID match, keep the original "pass supersedes"
+ // advice for the colliding memory — a typo among several targets must
+ // not hide the hint that still applies to the collision.
+ const advice =
+ supers.unmatched.length && supers.matched.length === 0
+ ? [
+ "If this genuinely differs, pass force: true.",
+ "",
+ `Supersedes did not match any memory: ${supers.unmatched.join(", ")}.`,
+ "Titles are matched exactly, case-insensitively — check the spelling against a recall result.",
+ ]
+ : [
+ "If this genuinely differs, pass force: true. If it CORRECTS that memory,",
+ "pass supersedes: [\"<its exact title>\"] instead — the old one is kept and back-linked.",
+ ];
+ return [
+ `Not recorded: a near-identical memory already exists (${Math.round(d.score * 100)}% similar).`,
+ ` ${d.entry.title}`,
+ ` ${d.entry.rel}`,
+ "",
+ ...advice,
+ ].join("\n");
+ }
+ }
+
+ const { resolved, dropped } = resolveLinks(args.links, resolvable);
// A match the server may not modify (a hand-filed memory) is shown apart,
// so a preview never promises a mark the write will refuse.
const markable = supers.matched.filter((d) => isServerOwned(d.source));
diff --git a/.claude/scripts/tests/om-mcp.integration.test.ts b/.claude/scripts/tests/om-mcp.integration.test.ts
index 8c22ba6..ffa24b7 100644
--- a/.claude/scripts/tests/om-mcp.integration.test.ts
+++ b/.claude/scripts/tests/om-mcp.integration.test.ts
@@ -411,6 +411,131 @@ describe("the om server on the wire", () => {
assert.match(textOf(dup), /near-identical memory already exists/);
});
+ /**
+ * Supersession vs. the duplicate guard, over the wire.
+ *
+ * A correction is a near-copy of what it corrects — same subject, one value or
+ * one cause changed — so the near-duplicate check used to refuse exactly the
+ * call `supersedes` exists for, then told the caller to pass `supersedes`,
+ * which they had. What has to hold is the ORDER inside `callRemember`, and a
+ * unit test of `findSimilar` cannot tell the two orderings apart: only the
+ * live server sees the refusal, the back-link and the advice together.
+ */
+ describe("a correction that supersedes an existing memory", () => {
+ /** Fixture memory, written the way the server writes one so supersession may touch it. */
+ const memory = (name: string, title: string, body: string): string => {
+ const rel = `memories/2026/07/${name}.md`;
+ put(
+ rel,
+ "---\n" +
+ `description: "${body}"\n` +
+ "tags: [memory]\n" +
+ "source: mcp-capture\n" +
+ `origin: "${CALLER}"\n` +
+ "scope: project\n" +
+ `projects: [${CALLER}]\n` +
+ "confidence: verified\n" +
+ "---\n\n" +
+ `# ${title}\n\n${body}\n`,
+ );
+ return rel;
+ };
+
+ const remember = (args: Record<string, unknown>): Promise<Rpc> =>
+ call("tools/call", {
+ name: "remember",
+ arguments: {
+ confidence: "verified",
+ verification: "Observed in this run.",
+ scope: "project",
+ projects: [CALLER],
+ ...args,
+ },
+ });
+
+ test("is recorded instead of refused, and back-links the memory it replaces", async () => {
+ const title = "The importer times out after 30 seconds on large CSV files";
+ const body =
+ "The importer times out after 30 seconds on large CSV files because the reader holds the whole file in memory instead of streaming rows.";
+ const correction =
+ "The importer times out after 30 seconds on large CSV files because the proxy in front of it times out first, not the reader holding the whole file in memory.";
+ const rel = memory("import-timeout", title, body);
+
+ const t = textOf(
+ await remember({ title, body: correction, supersedes: [title] }),
+ );
+ assert.match(t, /Recorded: memories\//, "a declared correction must not be refused as a duplicate");
+ assert.match(t, new RegExp(`Superseded: ${title}`));
+
+ // Kept, not deleted — the history is the point, so the proof is the
+ // back-link landing in the file.
+ const old = readFileSync(join(vault, rel), "utf8");
+ assert.match(old, /superseded_by: \["The importer times out/);
+ });
+
+ test("the same correction WITHOUT supersedes is still refused", async () => {
+ // Own titles — the suite shares one vault, so reusing the first test's
+ // titles would refuse against that test's recorded correction instead of
+ // this fixture.
+ const title = "CSV export stalls when the row buffer fills";
+ const body =
+ "CSV export stalls when the row buffer fills because the writer waits for the whole batch before flushing to disk.";
+ const correction =
+ "CSV export stalls when the row buffer fills because the downstream socket backpressures, not because the writer waits for the whole batch.";
+ memory("csv-export-undeclared", title, body);
+
+ const t = textOf(await remember({ title, body: correction }));
+ assert.match(t, /near-identical memory already exists/);
+ assert.doesNotMatch(t, /Recorded:/, "an undeclared restatement is what the guard is for");
+ });
+
+ test("superseding A does not excuse a near-copy of B", async () => {
+ const aTitle = "Nightly sync drops rows older than 90 days";
+ const aBody =
+ "Nightly sync drops rows older than 90 days because the retention filter runs before the upsert, so historical rows never land.";
+ const bTitle = "The compile cache misses when node_modules is rewritten";
+ const bBody =
+ "The compile cache misses when node_modules is rewritten because the cache key is derived from the package tree hash, so every task reruns from scratch.";
+ memory("compile-cache", bTitle, bBody);
+ const aRel = memory("nightly-sync", aTitle, aBody);
+
+ // Names A, but the text collides with B. Only the NAMED target drops out
+ // of the comparison — a correction is not a licence.
+ const t = textOf(
+ await remember({
+ title: bTitle,
+ body: `${bBody.replace(/reruns from scratch\.$/, "reruns from scratch on a clean checkout.")}`,
+ supersedes: [aTitle],
+ }),
+ );
+ assert.match(t, /near-identical memory already exists/);
+ assert.match(t, new RegExp(bTitle), "the refusal must name the memory that actually collides");
+ // A refusal never prints Superseded:, so prove A was left alone in the file.
+ const aFile = readFileSync(join(vault, aRel), "utf8");
+ assert.doesNotMatch(aFile, /superseded_by/, "a refused remember must not back-link A");
+ });
+
+ test("a supersedes title that matches nothing is named, not re-advised", async () => {
+ const bTitle = "Warm starts skip the schema migration step";
+ const bBody =
+ "Warm starts skip the schema migration step because the boot path hashes the migration directory, so every task reruns from scratch.";
+ memory("warm-start-unmatched", bTitle, bBody);
+
+ const t = textOf(
+ await remember({
+ title: bTitle,
+ body: `${bBody.replace(/reruns from scratch\.$/, "reruns from scratch on a clean checkout.")}`,
+ supersedes: ["A title nobody has ever written"],
+ }),
+ );
+ assert.match(t, /near-identical memory already exists/);
+ // The caller DID pass supersedes and it cannot work, so repeating the
+ // advice sends them round the same loop. Say what did not resolve.
+ assert.match(t, /Supersedes did not match any memory: A title nobody has ever written/);
+ assert.doesNotMatch(t, /pass supersedes/, "the advice the caller already followed must not come back");
+ });
+ });
+
/**
* Promotion, over the wire.
*
diff --git a/ARCHITECTURE.md b/ARCHITECTURE.md
index e05424c..2905eb7 100644
--- a/ARCHITECTURE.md
+++ b/ARCHITECTURE.md
@@ -737,8 +737,9 @@ flowchart TB
Vault -->|no| Neut["neutralise dangling wikilinks<br/>in title AND body"]
Neut --> Val["validateMemory<br/>epistemic contract"]
Val -->|fails| Report["refused, with reasons"]
- Val --> Dup{"near-duplicate?<br/>facet-gated"}
- Dup -->|"yes, and force is not set"| Collide["reports what it collided with,<br/>suggests supersedes"]
+ Val --> Sup0["resolve supersedes — the named targets<br/>drop out of the comparison"]
+ Sup0 --> Dup{"near-duplicate against the rest?<br/>facet-gated"}
+ Dup -->|"yes, and force is not set"| Collide["reports what it collided with —<br/>suggests supersedes, or names the<br/>supersedes titles that matched nothing"]
Dup -->|no| Links["resolve links — emitted only if the target exists"]
Links --> Write["claimFile: atomic exclusive create"]
Write --> Sup["mark superseded memories,<br/>kept and back-linked"]