Skip to content

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

fix: audit what was refused, and serve a capture the tool refused (#227)

Brenno Ferrari7291f7ea247e
diff --git a/.claude/scripts/lib/mcp-caller.ts b/.claude/scripts/lib/mcp-caller.ts
index 19246ed..b16ed74 100644
--- a/.claude/scripts/lib/mcp-caller.ts
+++ b/.claude/scripts/lib/mcp-caller.ts
@@ -149,8 +149,10 @@ export interface AuditEntry {
}
/**
- * Append-only log of what each caller read. Write failures are swallowed: the
- * log must never be able to break the server.
+ * Append-only log of what each caller did, including what it was REFUSED.
+ * Successes alone answer "what did this repo read and write" and cannot answer
+ * "what did it try and fail to do", which is the question a refusal loop needs.
+ * Write failures are swallowed: the log must never be able to break the server.
*/
/** Rotate at 5MB — roughly a year of ordinary use, kept for one generation. */
export const AUDIT_MAX_BYTES = 5 * 1024 * 1024;
diff --git a/.claude/scripts/lib/mcp-server.ts b/.claude/scripts/lib/mcp-server.ts
index 5f26be6..48ad0f9 100644
--- a/.claude/scripts/lib/mcp-server.ts
+++ b/.claude/scripts/lib/mcp-server.ts
@@ -421,6 +421,7 @@ export function createHandlers(deps: ServerDeps): Handlers {
// would be scoped to the vault-as-a-project — reaching only sessions that
// by definition did not need it. Write-only by construction.
if (isVaultItself(ctx.vaultRoot, session.roots)) {
+ audit("refused", { tool: "remember", reason: "session is the vault itself" });
return [
"Refused: this session is running inside the vault itself.",
"",
@@ -437,7 +438,19 @@ export function createHandlers(deps: ServerDeps): Handlers {
// wikilink neutralisation, because a field that has swallowed the following
// field is not text worth cleaning up.
const corruptedMemory = describeToolMarkup(args);
- if (corruptedMemory) return toolMarkupRefusal(corruptedMemory);
+ if (corruptedMemory) {
+ // The field name, offset and shape only. No caller prose: this is the
+ // one refusal that is NOT self-correcting, so a loop has to be
+ // diagnosable from the log without the log becoming a copy of the call.
+ audit("refused", {
+ tool: "remember",
+ reason: "tool-call markup",
+ field: corruptedMemory.field,
+ offset: corruptedMemory.offset,
+ trailing: corruptedMemory.trailing,
+ });
+ return toolMarkupRefusal(corruptedMemory);
+ }
const who = caller();
const resolvable = resolvableNames(visibleFiles(ctx.vaultRoot, policy));
@@ -456,6 +469,9 @@ export function createHandlers(deps: ServerDeps): Handlers {
{ now: now(), origin: who.project },
);
if (!v.ok || !v.value) {
+ // The count, not the messages. They quote the caller's own title and
+ // body back, and the log is not the place for that.
+ audit("refused", { tool: "remember", reason: "validation", errors: v.errors.length });
return `Refused:\n${v.errors.map((e) => `- ${e}`).join("\n")}`;
}
@@ -529,7 +545,16 @@ export function createHandlers(deps: ServerDeps): Handlers {
// corrupted note whose damage is invisible until a human reads the rendered
// markup, which is exactly how one shipped unnoticed.
const corrupted = describeToolMarkup(args);
- if (corrupted) return toolMarkupRefusal(corrupted);
+ if (corrupted) {
+ audit("refused", {
+ tool: "record_work",
+ reason: "tool-call markup",
+ field: corrupted.field,
+ offset: corrupted.offset,
+ trailing: corrupted.trailing,
+ });
+ return toolMarkupRefusal(corrupted);
+ }
const who = callerProject(session.roots);
const resolvable = resolvableNames(visibleFiles(ctx.vaultRoot, policy));
let r;
diff --git a/.claude/scripts/lib/memory-recall.ts b/.claude/scripts/lib/memory-recall.ts
index 06ba854..0374363 100644
--- a/.claude/scripts/lib/memory-recall.ts
+++ b/.claude/scripts/lib/memory-recall.ts
@@ -25,7 +25,7 @@
import { readFileSync, readdirSync, statSync, existsSync } from "node:fs";
import { join } from "node:path";
-import { MEMORY_ROOT, MEMORY_SOURCE } from "./memory-write.ts";
+import { MEMORY_ROOT, MEMORY_SOURCE, AGENT_SOURCES } from "./memory-write.ts";
import { parsePromotedMarker, type PromotedRef } from "./memory-promoted.ts";
import { resolveSupersedes } from "./memory-supersede.ts";
@@ -512,7 +512,12 @@ export function readMemories(vaultRoot: string, root: string = MEMORY_ROOT): Mem
* is answered in a single place.
*/
export function agentMemories(entries: readonly MemoryEntry[]): MemoryEntry[] {
- return entries.filter((m) => m.facets.source === MEMORY_SOURCE);
+ // Both agent sources count. A capture the tool refused is what a session
+ // writes when the lesson is worth keeping anyway; excluding it meant the
+ // honest label cost the memory its whole audience, which punishes exactly the
+ // behaviour that saved the lesson. A note with any OTHER source, or none, is
+ // still left alone — that is the rule this predicate is for.
+ return entries.filter((m) => AGENT_SOURCES.includes(String(m.facets.source)));
}
/**
diff --git a/.claude/scripts/lib/memory-write.ts b/.claude/scripts/lib/memory-write.ts
index eac846d..073be88 100644
--- a/.claude/scripts/lib/memory-write.ts
+++ b/.claude/scripts/lib/memory-write.ts
@@ -34,6 +34,28 @@ export const MEMORY_ROOT = "memories";
*/
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;
diff --git a/.claude/scripts/tests/mcp-refusal-audit.test.ts b/.claude/scripts/tests/mcp-refusal-audit.test.ts
new file mode 100644
index 0000000..d8604a8
--- /dev/null
+++ b/.claude/scripts/tests/mcp-refusal-audit.test.ts
@@ -0,0 +1,119 @@
+/**
+ * A refusal has to leave a trace.
+ *
+ * Every `audit(...)` call sat on a success path, so the log answered "what did
+ * this repo read and write" and could not answer "what did it try and fail to
+ * do". That is the question a refusal loop needs, and it matters most for the
+ * markup refusal, which is NOT self-correcting: its trigger is a serialization
+ * failure in the caller's own arguments, so a caller that re-sends the same
+ * content hits it again. Such a loop was invisible in the log, and the only
+ * artefact left behind was whatever the caller did instead.
+ *
+ * Driven through the real `tools/call` dispatch with a duck-typed session, so
+ * these assert the wiring rather than a helper in isolation. A test that only
+ * checked the success path would have passed throughout the old behaviour,
+ * which is exactly how the gap survived.
+ */
+
+import { test, describe } from "node:test";
+import assert from "node:assert/strict";
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+import { createHandlers } from "../lib/mcp-server.ts";
+
+interface Logged {
+ readonly action: string;
+ readonly detail: Record<string, unknown>;
+}
+
+function harness(vaultRoot: string): { call: (name: string, args: Record<string, unknown>) => Promise<void>; logged: Logged[] } {
+ const logged: Logged[] = [];
+ const session = {
+ roots: [{ uri: `file:///elsewhere/some-project`, name: "some-project" }],
+ identityReady: async () => {},
+ ok: (_id: unknown, r: unknown) => r,
+ error: (_id: unknown, e: unknown) => e,
+ };
+ const handlers = createHandlers({
+ ctx: { vaultRoot, memoryRoot: "memories", qmdIndex: null },
+ policy: { roots: ["brain"], never_expose: [] },
+ session,
+ qmd: () => ({}),
+ audit: (action: string, detail: Record<string, unknown> = {}) => logged.push({ action, detail }),
+ now: () => new Date(2026, 6, 26),
+ } as never);
+ const call = async (name: string, args: Record<string, unknown>): Promise<void> => {
+ await (handlers as never as Record<string, (id: number, p: unknown) => Promise<unknown>>)["tools/call"]!(
+ 1,
+ { name, arguments: args },
+ );
+ };
+ return { call, logged };
+}
+
+/** The shape a broken serialization actually produces in the field. */
+const CORRUPTED = {
+ title: "a lesson worth keeping",
+ body: 'the prose is fine<parameter name="changes">and then the next field arrived as text',
+};
+
+describe("a refused call is auditable", () => {
+ test("remember records the refusal, with the field and shape but no prose", async () => {
+ const dir = mkdtempSync(join(tmpdir(), "refuse-"));
+ try {
+ const { call, logged } = harness(dir);
+ await call("remember", CORRUPTED);
+
+ const refusals = logged.filter((l) => l.action === "refused");
+ assert.equal(refusals.length, 1, "a refusal that logs nothing is a loop nobody can diagnose");
+ assert.equal(refusals[0]!.detail["tool"], "remember");
+ assert.equal(refusals[0]!.detail["reason"], "tool-call markup");
+ // The diagnosable part: which field, and which of the two repairs.
+ assert.equal(refusals[0]!.detail["field"], "body");
+ assert.equal(typeof refusals[0]!.detail["trailing"], "boolean");
+ // The caller's prose must not be copied into the log.
+ const serialised = JSON.stringify(refusals[0]);
+ assert.ok(!serialised.includes("the prose is fine"), "the log must not become a copy of the call");
+ } finally {
+ rmSync(dir, { recursive: true, force: true });
+ }
+ });
+
+ test("record_work records its refusal too, named as itself", async () => {
+ const dir = mkdtempSync(join(tmpdir(), "refuse-"));
+ try {
+ const { call, logged } = harness(dir);
+ await call("record_work", { ...CORRUPTED, folder: "brain" });
+
+ const refusals = logged.filter((l) => l.action === "refused");
+ assert.equal(refusals.length, 1);
+ assert.equal(refusals[0]!.detail["tool"], "record_work");
+ } finally {
+ rmSync(dir, { recursive: true, force: true });
+ }
+ });
+
+ // The other direction, so the guard cannot be satisfied by auditing "refused"
+ // unconditionally: a call that is not refused must not log one.
+ test("a call that is not refused logs no refusal", async () => {
+ const dir = mkdtempSync(join(tmpdir(), "refuse-"));
+ try {
+ const { call, logged } = harness(dir);
+ await call("remember", {
+ title: "a clean title stated as a claim",
+ body: "A body written for a session that will not have this context, long enough to clear the minimum.",
+ confidence: "inferred",
+ scope: "general",
+ });
+ assert.deepEqual(
+ logged.filter((l) => l.action === "refused"),
+ [],
+ "a call that was not refused must not log a refusal",
+ );
+ } finally {
+ rmSync(dir, { recursive: true, force: true });
+ }
+ });
+});
diff --git a/.claude/scripts/tests/memory-recall.test.ts b/.claude/scripts/tests/memory-recall.test.ts
index b50ee68..078cc80 100644
--- a/.claude/scripts/tests/memory-recall.test.ts
+++ b/.claude/scripts/tests/memory-recall.test.ts
@@ -37,6 +37,7 @@ import {
specificity,
rankMemories,
supersededOutOfReach,
+ agentMemories,
SUPERSEDED_OUT_OF_REACH,
MEMORY_SOURCE,
type Caller,
@@ -528,3 +529,44 @@ describe("a superseded memory reaches only where its successor reaches", () => {
assert.deepEqual(served.sort(), ["X", "Y"]);
});
});
+
+/**
+ * A capture the tool refused still has to reach someone.
+ *
+ * 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
+ * itself rather than lose it. Labelling that honestly then excluded it from
+ * `recall`, because the agent-source predicate knew exactly one value: the
+ * lesson landed in the vault and was served to nobody, including the session
+ * that wrote it. The honest label cost the memory its entire audience.
+ */
+describe("a hand-filed capture is still an agent memory", () => {
+ const entryWith = (source: string | null, title: string): MemoryEntry => ({
+ rel: `memories/2026/08/${title}.md`,
+ full: `/nowhere/${title}.md`,
+ facets: facetsOf({ ...(source ? { source } : {}), date: "2026-08-14", scope: "general" }),
+ title,
+ body: "b",
+ });
+ const handFiled = entryWith("hand-filed", "filed by hand after the tool refused");
+ const stray = entryWith(null, "a human note that wandered in");
+
+ test("recall serves it", () => {
+ assert.deepEqual(
+ recallFrom([handFiled], CALLERS.harbor).map((m) => m.title),
+ ["filed by hand after the tool refused"],
+ );
+ });
+
+ test("agentMemories counts it", () => {
+ assert.equal(agentMemories([handFiled]).length, 1);
+ });
+
+ // The rule the predicate exists for, unchanged: a note with no agent source
+ // is still left alone rather than silently governed by these rules. Stays
+ // green across the change by design — it is the non-regression, not the fix.
+ test("a stray note with no agent source is still left alone", () => {
+ assert.equal(agentMemories([stray]).length, 0);
+ assert.deepEqual(recallFrom([stray], CALLERS.harbor), []);
+ });
+});