A self-organizing Obsidian vault that gives AI coding agents persistent memory.
TypeScript ai-agentsclaude-codecodex-cligemini-cliknowledge-managementobsidianobsidian-vaultpersistent-memorysecond-braintemplate
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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsnew file mode 100644index 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.tsindex 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), []);+ });+});