feat: add overwrite guard to write_note tool

phernandez · claude · phernandez · commit 097b6a9ccc8a · 2026-03-02T21:26:26.000-06:00
Align with basic-memory PR #632 — write_note is now non-destructive by
default. When a note already exists, the agent gets a helpful error
with alternatives (edit_note, read_note, or explicit overwrite=true).

- Add NoteAlreadyExistsError class to bm-client
- Add overwrite param to BmClient.writeNote(), pass through to MCP
- Detect NOTE_ALREADY_EXISTS JSON response and throw typed error
- Tool handler catches conflict and returns actionable guidance
- indexConversation passes overwrite=true (intentional create-or-replace)
- Update description from "Create or update" to "Create a note"

Co-Authored-By: Claude Opus 4.6 &lt;noreply@anthropic.com&gt;
diff --git a/bm-client.test.ts b/bm-client.test.ts
@@ -109,6 +109,49 @@ describe("BmClient MCP behavior", () => {
     expect(result.action).toBe("created")
   })
 
+  it("writeNote passes overwrite flag when provided", async () => {
+    const callTool = jest.fn().mockResolvedValue(
+      mcpResult({
+        title: "Note",
+        permalink: "notes/note",
+        file_path: "notes/note.md",
+        action: "updated",
+      }),
+    )
+    setConnected(client, callTool)
+
+    await client.writeNote("Note", "hello", "notes", undefined, true)
+
+    expect(callTool).toHaveBeenCalledWith({
+      name: "write_note",
+      arguments: {
+        title: "Note",
+        content: "hello",
+        directory: "notes",
+        output_format: "json",
+        overwrite: true,
+      },
+    })
+  })
+
+  it("writeNote throws NoteAlreadyExistsError on conflict response", async () => {
+    const callTool = jest.fn().mockResolvedValue(
+      mcpResult({
+        title: "Existing",
+        permalink: "notes/existing",
+        file_path: null,
+        checksum: null,
+        action: "conflict",
+        error: "NOTE_ALREADY_EXISTS",
+      }),
+    )
+    setConnected(client, callTool)
+
+    await expect(
+      client.writeNote("Existing", "content", "notes"),
+    ).rejects.toThrow("Note already exists")
+  })
+
   it("editNote calls edit_note with MCP argument names", async () => {
     const callTool = jest.fn().mockResolvedValue(
       mcpResult({
@@ -540,6 +583,9 @@ describe("BmClient MCP behavior", () => {
     )
 
     expect((client as any).writeNote).toHaveBeenCalledTimes(1)
+    const args = (client as any).writeNote.mock.calls[0]
+    expect(args[3]).toBeUndefined() // project
+    expect(args[4]).toBe(true) // overwrite
   })
 
   it("indexConversation creates fallback note only on note-not-found errors", async () => {
diff --git a/bm-client.ts b/bm-client.ts
@@ -5,6 +5,15 @@ import { log } from "./logger.ts"
 
 const DEFAULT_RETRY_DELAYS_MS = [500, 1000, 2000]
 
+export class NoteAlreadyExistsError extends Error {
+  readonly permalink: string
+  constructor(title: string, permalink: string) {
+    super(`Note already exists: "${title}" (${permalink})`)
+    this.name = "NoteAlreadyExistsError"
+    this.permalink = permalink
+  }
+}
+
 const REQUIRED_TOOLS = [
   "search_notes",
   "read_note",
@@ -569,6 +578,7 @@ export class BmClient {
     content: string,
     folder: string,
     project?: string,
+    overwrite?: boolean,
   ): Promise<NoteResult> {
     const args: Record<string, unknown> = {
       title,
@@ -577,13 +587,21 @@ export class BmClient {
       output_format: "json",
     }
     if (project) args.project = project
+    if (overwrite !== undefined) args.overwrite = overwrite
 
     const payload = await this.callTool("write_note", args)
 
     if (!isRecord(payload)) {
       throw new Error("invalid write_note response")
     }
 
+    if (payload.error === "NOTE_ALREADY_EXISTS") {
+      throw new NoteAlreadyExistsError(
+        asString(payload.title) ?? title,
+        asString(payload.permalink) ?? "",
+      )
+    }
+
     const resultTitle = asString(payload.title)
     const permalink = asString(payload.permalink)
     const filePath = asString(payload.file_path)
@@ -850,7 +868,7 @@ export class BmClient {
     ].join("\n")
 
     try {
-      await this.writeNote(title, content, "conversations")
+      await this.writeNote(title, content, "conversations", undefined, true)
       log.debug(`created conversation note: ${title}`)
     } catch (err) {
       log.error("conversation index failed", err)
diff --git a/tools/write-note.test.ts b/tools/write-note.test.ts
@@ -1,6 +1,7 @@
 import { beforeEach, describe, expect, it, jest } from "bun:test"
 import type { OpenClawPluginApi } from "openclaw/plugin-sdk"
 import type { BmClient } from "../bm-client.ts"
+import { NoteAlreadyExistsError } from "../bm-client.ts"
 import { registerWriteTool } from "./write-note.ts"
 
 describe("write tool", () => {
@@ -26,7 +27,7 @@ describe("write tool", () => {
           name: "write_note",
           label: "Write Note",
           description: expect.stringContaining(
-            "Create or update a note in the Basic Memory knowledge graph",
+            "Create a note in the Basic Memory knowledge graph",
           ),
           parameters: expect.objectContaining({
             type: "object",
@@ -46,6 +47,9 @@ describe("write tool", () => {
               project: expect.objectContaining({
                 type: "string",
               }),
+              overwrite: expect.objectContaining({
+                type: "boolean",
+              }),
             }),
           }),
           execute: expect.any(Function),
@@ -88,6 +92,7 @@ describe("write tool", () => {
         "This is test content",
         "notes",
         undefined,
+        undefined,
       )
 
       expect(result).toEqual({
@@ -128,6 +133,7 @@ describe("write tool", () => {
         "Root level note",
         "",
         undefined,
+        undefined,
       )
     })
 
@@ -154,6 +160,7 @@ describe("write tool", () => {
         "Nested folder note",
         "projects/subfolder",
         undefined,
+        undefined,
       )
     })
 
@@ -197,6 +204,7 @@ const code = "example";
         markdownContent,
         "notes",
         undefined,
+        undefined,
       )
     })
 
@@ -224,6 +232,7 @@ const code = "example";
         "Content",
         "notes",
         undefined,
+        undefined,
       )
     })
 
@@ -253,6 +262,7 @@ const code = "example";
         unicodeContent,
         "notes",
         undefined,
+        undefined,
       )
     })
 
@@ -280,6 +290,7 @@ const code = "example";
         longContent,
         "notes",
         undefined,
+        undefined,
       )
     })
 
@@ -306,6 +317,7 @@ const code = "example";
         "",
         "notes",
         undefined,
+        undefined,
       )
     })
 
@@ -329,9 +341,56 @@ const code = "example";
         "content",
         "notes",
         "other-project",
+        undefined,
       )
     })
 
+    it("should pass overwrite=true to client.writeNote", async () => {
+      ;(mockClient.writeNote as jest.MockedFunction<any>).mockResolvedValue({
+        title: "Note",
+        permalink: "note",
+        content: "content",
+        file_path: "notes/note.md",
+        action: "updated",
+      })
+
+      const result = await executeFunction("tool-call-id", {
+        title: "Note",
+        content: "content",
+        folder: "notes",
+        overwrite: true,
+      })
+
+      expect(mockClient.writeNote).toHaveBeenCalledWith(
+        "Note",
+        "content",
+        "notes",
+        undefined,
+        true,
+      )
+
+      expect(result.content[0].text).toContain("Note saved: Note")
+    })
+
+    it("should return helpful hint when note already exists", async () => {
+      ;(mockClient.writeNote as jest.MockedFunction<any>).mockRejectedValue(
+        new NoteAlreadyExistsError("Existing Note", "notes/existing-note"),
+      )
+
+      const result = await executeFunction("tool-call-id", {
+        title: "Existing Note",
+        content: "New content",
+        folder: "notes",
+      })
+
+      const text = result.content[0].text
+      expect(text).toContain('Note already exists: "Existing Note"')
+      expect(text).toContain("notes/existing-note")
+      expect(text).toContain("edit_note")
+      expect(text).toContain("overwrite=true")
+      expect(text).toContain("read_note")
+    })
+
     it("should handle write errors gracefully", async () => {
       const writeError = new Error("Failed to write note")
       ;(mockClient.writeNote as jest.MockedFunction<any>).mockRejectedValue(
@@ -385,6 +444,7 @@ Normal line
         formattedContent,
         "notes",
         undefined,
+        undefined,
       )
     })
 
@@ -412,6 +472,7 @@ Normal line
         "Content",
         "notes",
         undefined,
+        undefined,
       )
     })
 
diff --git a/tools/write-note.ts b/tools/write-note.ts
@@ -1,6 +1,7 @@
 import { Type } from "@sinclair/typebox"
 import type { OpenClawPluginApi } from "openclaw/plugin-sdk"
 import type { BmClient } from "../bm-client.ts"
+import { NoteAlreadyExistsError } from "../bm-client.ts"
 import { log } from "../logger.ts"
 
 export function registerWriteTool(
@@ -12,9 +13,9 @@ export function registerWriteTool(
       name: "write_note",
       label: "Write Note",
       description:
-        "Create or update a note in the Basic Memory knowledge graph. " +
-        "Notes are stored as Markdown files with semantic structure " +
-        "(observations, relations) that build a connected knowledge graph.",
+        "Create a note in the Basic Memory knowledge graph. " +
+        "If the note already exists, returns an error by default. " +
+        "Pass overwrite=true to replace, or use edit_note for incremental updates.",
       parameters: Type.Object({
         title: Type.String({ description: "Note title" }),
         content: Type.String({
@@ -26,6 +27,12 @@ export function registerWriteTool(
             description: "Target project name (defaults to current project)",
           }),
         ),
+        overwrite: Type.Optional(
+          Type.Boolean({
+            description:
+              "Set to true to replace an existing note. Defaults to false.",
+          }),
+        ),
       }),
       async execute(
         _toolCallId: string,
@@ -34,6 +41,7 @@ export function registerWriteTool(
           content: string
           folder: string
           project?: string
+          overwrite?: boolean
         },
       ) {
         log.debug(`write_note: title=${params.title} folder=${params.folder}`)
@@ -44,6 +52,7 @@ export function registerWriteTool(
             params.content,
             params.folder,
             params.project,
+            params.overwrite,
           )
 
           const msg = `Note saved: ${note.title} (${note.permalink})`
@@ -61,6 +70,22 @@ export function registerWriteTool(
             },
           }
         } catch (err) {
+          if (err instanceof NoteAlreadyExistsError) {
+            const hint = [
+              `Note already exists: "${params.title}" (${err.permalink})`,
+              "",
+              "To update this note, use one of:",
+              `  - edit_note("${err.permalink}", operation="append", content="...")`,
+              `  - edit_note("${err.permalink}", operation="replace_section", section="...", content="...")`,
+              `  - write_note("${params.title}", ..., overwrite=true) to fully replace`,
+              `  - read_note("${err.permalink}") to inspect current content first`,
+            ].join("\n")
+
+            return {
+              content: [{ type: "text" as const, text: hint }],
+            }
+          }
+
           log.error("write_note failed", err)
           return {
             content: [
