Skip to content

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

fix: a superseded memory reaches only where its correction reaches (#208)

HoangThai18d396eceed37e
diff --git a/.claude/scripts/lib/mcp-tools.ts b/.claude/scripts/lib/mcp-tools.ts
index c92b148..bc7b0e2 100644
--- a/.claude/scripts/lib/mcp-tools.ts
+++ b/.claude/scripts/lib/mcp-tools.ts
@@ -219,7 +219,7 @@ export const TOOLS: readonly ToolDef[] = [
type: "array",
items: { type: "string" },
description:
- "Exact titles of memories this CORRECTS. They are kept and back-linked, not deleted, and this one will outrank them. Use when you have learned that something recorded earlier is wrong.",
+ "Exact titles of memories this CORRECTS. They are kept and back-linked, not deleted, and this one will outrank them. Use when you have learned that something recorded earlier is wrong — including when only its REACH was wrong: re-file with the right scope and supersede the original, and the narrowing takes effect, because a superseded memory is served only where its correction can follow it.",
},
force: {
type: "boolean",
diff --git a/.claude/scripts/lib/memory-recall.ts b/.claude/scripts/lib/memory-recall.ts
index 3794c3d..1e86c8d 100644
--- a/.claude/scripts/lib/memory-recall.ts
+++ b/.claude/scripts/lib/memory-recall.ts
@@ -27,6 +27,7 @@ import { readFileSync, readdirSync, statSync, existsSync } from "node:fs";
import { join } from "node:path";
import { MEMORY_ROOT, MEMORY_SOURCE } from "./memory-write.ts";
import { parsePromotedMarker, type PromotedRef } from "./memory-promoted.ts";
+import { resolveSupersedes } from "./memory-supersede.ts";
// Re-exported so a reader can take the marker from the module it reads with,
// while the writer that stamps it stays the one place it is defined.
@@ -221,6 +222,39 @@ export function visibilityReason(facets: Facets | null | undefined, caller: Call
return `no facet matches caller (project="${project}", platforms=[${platforms.join(", ")}])`;
}
+/** How `explain` names this exclusion, kept apart from the scope reasons. */
+export const SUPERSEDED_OUT_OF_REACH = "superseded by a memory this caller cannot see";
+
+/**
+ * Does this memory's replacement fail to reach where the memory itself reaches?
+ *
+ * Sinking a superseded memory is safe only while the reader can see what
+ * replaced it, ranked above. When a correction NARROWS reach — which is one of
+ * the most useful things a correction can do, a `general` lesson re-filed as
+ * `platform` once recognised as platform-specific — the original survives
+ * carrying the wider scope, and the caller the correction was written to
+ * exclude keeps receiving the retired claim. The narrower correction is
+ * precisely the half that got scoped away, so it is not returned alongside it.
+ *
+ * Serving the stale half ALONE is worse than serving neither: there is nothing
+ * above it, no signal it was retired, and no access to what replaced it.
+ *
+ * An unresolvable `superseded_by` claim leaves the memory visible. Reach is
+ * declared at write time, and a title matching nothing is metadata rot rather
+ * than a reach decision — withholding on it would silently lose a real memory
+ * to a typo.
+ */
+export function supersededOutOfReach(
+ entry: MemoryEntry,
+ corpus: readonly MemoryEntry[],
+ caller: Caller,
+): boolean {
+ if (entry.facets.superseded_by.length === 0) return false;
+ const { matched } = resolveSupersedes(entry.facets.superseded_by, corpus);
+ if (matched.length === 0) return false;
+ return !matched.some((m) => isVisibleTo(m.facets, caller));
+}
+
// ---------------------------------------------------------------------------
// Ranking
// ---------------------------------------------------------------------------
@@ -406,13 +440,23 @@ export function recallFrom(
): MemoryEntry[] | { visible: MemoryEntry[]; withheld: MemoryEntry[] } {
const visible: MemoryEntry[] = [];
const withheld: MemoryEntry[] = [];
- for (const entry of agentMemories(entries)) {
+ // Judged against the agent corpus rather than the raw entries, so a claim is
+ // resolved against the set `recall` can actually serve.
+ const corpus = agentMemories(entries);
+ for (const entry of corpus) {
const facets = entry.facets;
- if (isVisibleTo(facets, caller)) {
- visible.push(explain ? { ...entry, why: visibilityReason(facets, caller) } : entry);
- } else if (explain) {
- withheld.push({ ...entry, why: visibilityReason(facets, caller) });
+ if (!isVisibleTo(facets, caller)) {
+ if (explain) withheld.push({ ...entry, why: visibilityReason(facets, caller) });
+ continue;
+ }
+ // Checked after visibility so the two kinds of exclusion stay
+ // distinguishable: a memory that never reached this caller is a scope
+ // answer, not a supersession one.
+ if (supersededOutOfReach(entry, corpus, caller)) {
+ if (explain) withheld.push({ ...entry, why: SUPERSEDED_OUT_OF_REACH });
+ continue;
}
+ visible.push(explain ? { ...entry, why: visibilityReason(facets, caller) } : entry);
}
const ranked = rankMemories(visible, caller);
return explain ? { visible: ranked, withheld } : ranked;
diff --git a/.claude/scripts/tests/memory-recall.test.ts b/.claude/scripts/tests/memory-recall.test.ts
index ce92298..14058cc 100644
--- a/.claude/scripts/tests/memory-recall.test.ts
+++ b/.claude/scripts/tests/memory-recall.test.ts
@@ -30,12 +30,17 @@ import { readFileSync } from "node:fs";
import { validateMemory, writeMemory } from "../lib/memory-write.ts";
import {
recall,
+ recallFrom,
isVisibleTo,
facetsOf,
parseFrontmatter,
specificity,
rankMemories,
+ supersededOutOfReach,
+ SUPERSEDED_OUT_OF_REACH,
+ MEMORY_SOURCE,
type Caller,
+ type MemoryEntry,
} from "../lib/memory-recall.ts";
const DAY = new Date(2026, 6, 26);
@@ -381,3 +386,66 @@ describe("a promoted capture says so", () => {
}
});
});
+
+/**
+ * A correction that NARROWS reach used to invert itself.
+ *
+ * `remember` is append-only, so correcting a memory means writing a new one and
+ * marking the old one superseded. The old one keeps the scope it was written
+ * with — fine while the correction is as wide or wider, broken the moment it is
+ * narrower, which is one of the most useful things a correction can do. Sinking
+ * the original is only safe because the reader sees the replacement ranked above
+ * it; where the replacement cannot follow, the reader gets a retired claim alone,
+ * with no signal it was retired and no access to what replaced it.
+ */
+describe("a superseded memory reaches only where its successor reaches", () => {
+ const entry = (title: string, fm: Record<string, unknown>): MemoryEntry => ({
+ rel: `memories/2026/07/${title}.md`,
+ full: `/nowhere/${title}.md`,
+ facets: facetsOf({ source: MEMORY_SOURCE, date: "2026-07-26", ...fm }),
+ title,
+ body: "b",
+ });
+
+ // The exact shape from the issue: captured wide, recognised as iOS-specific,
+ // re-filed narrow. `harbor` is the web caller the correction excludes.
+ const ORIGINAL = entry("keychain access needs an entitlement", {
+ scope: "general",
+ superseded_by: ["keychain access needs an entitlement (iOS)"],
+ });
+ const CORRECTION = entry("keychain access needs an entitlement (iOS)", {
+ scope: "platform",
+ platforms: ["ios"],
+ });
+ const CORPUS = [ORIGINAL, CORRECTION];
+
+ test("the stale original is withheld where its correction cannot reach", () => {
+ const titles = recallFrom(CORPUS, CALLERS.harbor).map((m) => m.title);
+ assert.deepEqual(titles, [], "serving the retired half alone is worse than serving neither");
+ });
+
+ test("where the caller reaches both, nothing changes and the correction ranks first", () => {
+ const titles = recallFrom(CORPUS, CALLERS.atlas).map((m) => m.title);
+ assert.deepEqual(titles, [CORRECTION.title, ORIGINAL.title], "history stays available, sunk");
+ });
+
+ test("explain names supersession, not scope, so the two exclusions stay apart", () => {
+ const { withheld } = recallFrom(CORPUS, CALLERS.harbor, { explain: true });
+ const why = withheld.find((m) => m.title === ORIGINAL.title)?.why;
+ assert.equal(why, SUPERSEDED_OUT_OF_REACH);
+ assert.ok(!/scope/.test(why ?? ""), "a scope explanation here sends the reader after the wrong thing");
+ });
+
+ // Reach is declared at write time; a title matching nothing is metadata rot,
+ // not a reach decision. Withholding on it loses a real memory to a typo.
+ test("an unresolvable superseded_by claim leaves the memory visible", () => {
+ const orphan = entry("still useful", { scope: "general", superseded_by: ["no such memory"] });
+ assert.equal(supersededOutOfReach(orphan, [orphan], CALLERS.harbor), false);
+ assert.deepEqual(recallFrom([orphan], CALLERS.harbor).map((m) => m.title), ["still useful"]);
+ });
+
+ test("a memory with no supersession is untouched by the rule", () => {
+ const plain = entry("plain", { scope: "general" });
+ assert.equal(supersededOutOfReach(plain, [plain], CALLERS.harbor), false);
+ });
+});
diff --git a/CLAUDE.md b/CLAUDE.md
index 6d6b538..efc0ff2 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -362,6 +362,8 @@ This is the part worth understanding, and it is what the layer is for. Every mem
A reader never widens what the writer declared, so a sibling app on the same platform does not inherit another app's project-scoped constraints. `recall` with `explain: true` reports why each memory was shown and how many were withheld.
+**Getting the reach wrong is corrected the same way any other error is** — `remember` is append-only, so re-file the lesson with the right scope and pass `supersedes: ["<its exact title>"]`. Narrowing takes effect: a superseded memory is served only where its correction can follow it, so the caller the correction excludes stops receiving the wider stale copy rather than receiving it alone with nothing to replace it.
+
**A repo is identified by its folder name**, which is usually right and occasionally not: two repos both called `api` share one identity, so each receives the other's memories. Write a distinct name into a `.om-project` file at the repo root to separate them — `health` reports which repo it thinks is calling and where that name came from.
### Which notes the server serves