@basicmemory/openclaw-basic-memory 0.24.0 → 1.0.0

package/bm-client.ts

@@ -1,3 +1,4 @@
+import { createHash } from "node:crypto"
 import { setTimeout as delay } from "node:timers/promises"
 import { Client } from "@modelcontextprotocol/sdk/client"
 import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js"
@@ -7,17 +8,18 @@ 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})`)
+  constructor(title: string, permalink: string, message?: string) {
+    super(message ?? `Note already exists: "${title}" (${permalink})`)
     this.name = "NoteAlreadyExistsError"
     this.permalink = permalink
   }
 }
 
 /**
- * write_note refused a conditional overwrite: the note is no longer the
+ * bm_write refused a conditional overwrite: the note is no longer the
  * revision named by expected_checksum. Nothing was written; currentChecksum is
- * the revision to re-read and retry against (null once no note owns the path).
+ * available revision when supplied by a server. A null value means unknown;
+ * 1.0 puts revision details in the refusal message, not a checksum field.
  */
 export class NoteRevisionConflictError extends Error {
   readonly permalink: string | null
@@ -26,8 +28,11 @@ export class NoteRevisionConflictError extends Error {
     title: string,
     permalink: string | null,
     currentChecksum: string | null,
+    message?: string,
   ) {
-    super(`Note revision conflict: "${title}" changed since it was read`)
+    super(
+      message ?? `Note revision conflict: "${title}" changed since it was read`,
+    )
     this.name = "NoteRevisionConflictError"
     this.permalink = permalink
     this.currentChecksum = currentChecksum
@@ -49,20 +54,15 @@ export class BmToolError extends Error {
 }
 
 const REQUIRED_TOOLS = [
-  "search_notes",
-  "read_note",
-  "write_note",
-  "edit_note",
-  "build_context",
-  "recent_activity",
-  "list_memory_projects",
-  "list_workspaces",
-  "create_memory_project",
-  "delete_note",
-  "move_note",
-  "schema_validate",
-  "schema_infer",
-  "schema_diff",
+  "bm_search",
+  "bm_read",
+  "bm_write",
+  "bm_edit",
+  "bm_context",
+  "bm_project",
+  "bm_delete",
+  "bm_move",
+  "bm_schema",
 ]
 
 export interface SearchResult {
@@ -71,6 +71,17 @@ export interface SearchResult {
   content: string
   score?: number
   file_path: string
+  // The chunk of the note that matched, when the server ranked by chunk.
+  matched_chunk?: string | null
+}
+
+/**
+ * The text to preview for a search hit. `content` is the start of the note,
+ * so for a long note (a day of captured conversation) the matching part can
+ * sit far below any preview cut-off; the matched chunk is the part that hit.
+ */
+export function searchResultText(result: SearchResult): string {
+  return result.matched_chunk?.trim() || result.content || ""
 }
 
 export interface NoteResult {
@@ -87,7 +98,7 @@ export interface EditNoteResult {
   title: string
   permalink: string
   file_path: string
-  operation: "append" | "prepend" | "find_replace" | "replace_section"
+  operation: EditOperation
   checksum?: string | null
 }
 
@@ -107,6 +118,16 @@ interface WriteNoteOptions {
   expectedChecksum?: string
 }
 
+// bm_edit commands the plugin exposes. set_metadata is left out: edit_note
+// already merges `metadata` alongside any other operation.
+export type EditOperation =
+  | "append"
+  | "prepend"
+  | "find_replace"
+  | "replace_section"
+  | "insert_before_section"
+  | "insert_after_section"
+
 interface EditNoteOptions {
   find_text?: string
   section?: string
@@ -127,7 +148,10 @@ export interface ContextResult {
       permalink: string
       relation_type?: string
       from_entity?: string
-      to_entity?: string
+      // Null for a forward reference whose target note does not exist yet;
+      // to_name then carries the link text.
+      to_entity?: string | null
+      to_name?: string | null
     }>
   }>
 }
@@ -158,10 +182,7 @@ export interface ProjectListResult {
 export interface WorkspaceResult {
   tenant_id: string
   name: string
-  workspace_type: string
-  role: string
-  organization_id?: string | null
-  has_active_subscription: boolean
+  workspace_type: string | null
 }
 
 export interface SchemaValidationResult {
@@ -249,23 +270,32 @@ function isRecoverableConnectionError(err: unknown): boolean {
   )
 }
 
-function isNoteNotFoundError(err: unknown): boolean {
-  const msg = getErrorMessage(err).toLowerCase()
+export function isNoteNotFoundError(err: unknown): boolean {
   return (
-    msg.includes("entity not found") ||
-    msg.includes("note not found") ||
-    msg.includes("resource not found") ||
-    msg.includes("could not find note matching") ||
-    msg.includes("404")
+    err instanceof BmToolError &&
+    parseRefusalPayload(err.toolMessage)?.error === "NOT_FOUND"
   )
 }
 
+export type ConversationCaptureStatus = "committed" | "duplicate"
+
+function conversationDate(date: Date): string {
+  return date.toISOString().split("T")[0]
+}
+
+// Host advancement keys are opaque and may contain characters that would end
+// an HTML comment, so the note stores a fixed-length digest instead.
+function conversationTurnMarker(turnKey: string): string {
+  const digest = createHash("sha256").update(turnKey).digest("hex").slice(0, 32)
+  return `<!-- openclaw-turn:${digest} -->`
+}
+
 function asString(value: unknown): string | null {
   return typeof value === "string" ? value : null
 }
 
 // In JSON mode BM reports a refused write as a tool error whose text is the
-// refusal payload itself ({"error": "NOTE_ALREADY_EXISTS", ...}). Any other
+// refusal payload itself ({"error": "ALREADY_EXISTS", ...}). Any other
 // error text (plain-text failures, older servers) is not a refusal payload.
 function parseRefusalPayload(text: string): Record<string, unknown> | null {
   let parsed: unknown
@@ -277,6 +307,24 @@ function parseRefusalPayload(text: string): Record<string, unknown> | null {
   return isRecord(parsed) && typeof parsed.error === "string" ? parsed : null
 }
 
+/**
+ * The server's own explanation of a failed tool call, for showing to an agent.
+ * A refusal payload becomes "CODE: message"; other tool text passes through.
+ */
+export function describeToolError(err: unknown): string {
+  if (!(err instanceof BmToolError)) return getErrorMessage(err)
+  const payload = parseRefusalPayload(err.toolMessage)
+  if (!payload) return err.toolMessage || err.message
+  const message = asString(payload.message)
+  return message ? `${payload.error}: ${message}` : String(payload.error)
+}
+
+/** describeToolError, but saying plainly when the note does not exist. */
+export function describeNoteError(err: unknown): string {
+  const reason = describeToolError(err)
+  return isNoteNotFoundError(err) ? `it does not exist. ${reason}` : reason
+}
+
 function projectMatchesWorkspace(
   project: ProjectListResult,
   workspace: string,
@@ -299,34 +347,103 @@ export class BmClient {
   private cwd?: string
   private env?: Record<string, string>
   private shouldRun = false
+  // True only between start() and stop(), i.e. while the plugin service owns
+  // the BM MCP session. A lazy connection opened by a tool or memory call in a
+  // one-shot CLI process leaves this false.
+  private serviceRunning = false
+  // Connect plus project creation, started by start(). Tool calls wait for
+  // it so none can reach a project that does not exist yet. Null when the
+  // client was never started (tests, one-shot CLI readers).
+  private startup: Promise<void> | null = null
+  private startupRetry: Promise<void> | null = null
+  private projectPath?: string
+  private prepare?: () => Promise<void>
 
   private client: Client | null = null
   private transport: StdioClientTransport | null = null
   private connectPromise: Promise<void> | null = null
   private retryDelaysMs = [...DEFAULT_RETRY_DELAYS_MS]
+  // Conversation captures run one at a time so a turn-key duplicate check
+  // and the append that follows it cannot interleave with another capture.
+  private conversationWrites: Promise<unknown> = Promise.resolve()
 
   constructor(bmPath: string, project: string) {
     this.bmPath = bmPath
     this.project = project
   }
 
-  async start(options?: {
+  /**
+   * Connect to BM and create the plugin's project.
+   *
+   * Returns the startup promise; callers that must not block (the plugin
+   * service, which OpenClaw gives only a few seconds) can leave it running.
+   * Tool calls made meanwhile wait for it. If it fails, the next tool call
+   * runs it again, so a transient failure does not leave the plugin dead.
+   */
+  start(options?: {
     cwd?: string
     env?: Record<string, string>
+    projectPath?: string
+    // Runs before each connect attempt, e.g. installing the bm CLI.
+    prepare?: () => Promise<void>
   }): Promise<void> {
     this.shouldRun = true
+    this.serviceRunning = true
     if (options?.cwd) {
       this.cwd = options.cwd
     }
     if (options?.env) {
       this.env = options.env
     }
+    if (options?.projectPath) {
+      this.projectPath = options.projectPath
+    }
+    if (options?.prepare) {
+      this.prepare = options.prepare
+    }
+
+    this.startup = this.runStartup()
+    return this.startup
+  }
 
+  private async runStartup(): Promise<void> {
+    await this.prepare?.()
     await this.connectWithRetries()
+    if (this.projectPath) await this.createProject(this.projectPath)
+  }
+
+  private async waitForStartup(): Promise<void> {
+    if (!this.startup) return
+    try {
+      await this.startup
+    } catch (err) {
+      // Trigger: the startup this call was waiting on failed.
+      // Why: the service no longer fails on a slow or failed start, so the
+      //   first tool call afterwards is the place to recover.
+      // Outcome: one fresh attempt, shared by concurrent callers; its error
+      //   reaches the tool if it fails too.
+      if (!this.serviceRunning) throw err
+      if (this.startupRetry === null) {
+        this.startupRetry = this.runStartup().finally(() => {
+          this.startupRetry = null
+        })
+        this.startup = this.startupRetry
+      }
+      await this.startupRetry
+    }
+  }
+
+  isServiceRunning(): boolean {
+    return this.serviceRunning
   }
 
   async stop(): Promise<void> {
     this.shouldRun = false
+    this.serviceRunning = false
+    // Let an in-flight startup settle first, so it cannot reconnect after
+    // the disconnect below.
+    await this.startup?.catch(() => undefined)
+    this.startup = null
     await this.disconnectCurrent(this.client, this.transport)
     this.client = null
     this.transport = null
@@ -527,6 +644,15 @@ export class BmClient {
   private async callTool(
     name: string,
     args: Record<string, unknown>,
+  ): Promise<unknown> {
+    await this.waitForStartup()
+    return this.callStructured(name, args)
+  }
+
+  // Ungated: startup itself calls this to create the project.
+  private async callStructured(
+    name: string,
+    args: Record<string, unknown>,
   ): Promise<unknown> {
     const result = await this.callToolRaw(name, args)
 
@@ -546,44 +672,49 @@ export class BmClient {
     return project ?? this.project
   }
 
-  // project_id names one exact project, so it is sent alone: pairing it with
-  // a name (or the plugin's default project) would make routing depend on
-  // server-side precedence rather than on what the caller asked for.
-  private routing(
-    project?: string,
-    projectId?: string,
-  ): { project: string } | { project_id: string } {
-    if (projectId !== undefined) return { project_id: projectId }
+  // The 1.0 project parameter accepts either a name or an exact project UUID.
+  private routing(project?: string, projectId?: string): { project: string } {
+    if (projectId !== undefined) return { project: projectId }
     return { project: this.routedProject(project) }
   }
 
   async ensureProject(projectPath: string): Promise<void> {
-    const payload = await this.callTool("create_memory_project", {
-      project_name: this.project,
-      project_path: projectPath,
+    await this.waitForStartup()
+    await this.createProject(projectPath)
+  }
+
+  private async createProject(projectPath: string): Promise<void> {
+    const payload = await this.callStructured("bm_project", {
+      command: "create",
+      name: this.project,
+      path: projectPath,
       set_default: true,
       output_format: "json",
     })
 
     if (!isRecord(payload)) {
-      throw new Error("invalid create_memory_project response")
+      throw new Error("invalid bm_project response")
     }
   }
 
   async listWorkspaces(): Promise<WorkspaceResult[]> {
-    const payload = await this.callTool("list_workspaces", {
-      output_format: "json",
-    })
-
-    if (isRecord(payload) && Array.isArray(payload.workspaces)) {
-      return payload.workspaces as WorkspaceResult[]
+    const projects = await this.listProjects()
+    const workspaces = new Map<string, WorkspaceResult>()
+    for (const project of projects) {
+      if (project.workspace_tenant_id && project.workspace_name) {
+        workspaces.set(project.workspace_tenant_id, {
+          tenant_id: project.workspace_tenant_id,
+          name: project.workspace_name,
+          workspace_type: project.workspace_type ?? null,
+        })
+      }
     }
-
-    throw new Error("invalid list_workspaces response")
+    return [...workspaces.values()]
   }
 
   async listProjects(workspace?: string): Promise<ProjectListResult[]> {
-    const payload = await this.callTool("list_memory_projects", {
+    const payload = await this.callTool("bm_project", {
+      command: "list",
       output_format: "json",
     })
 
@@ -597,7 +728,7 @@ export class BmClient {
       return projects
     }
 
-    throw new Error("invalid list_memory_projects response")
+    throw new Error("invalid bm_project response")
   }
 
   async search(
@@ -619,16 +750,23 @@ export class BmClient {
       project: this.routedProject(project),
     }
     if (query) args.query = query
-    if (metadata?.filters) args.metadata_filters = metadata.filters
-    if (metadata?.tags) args.tags = metadata.tags
-    if (metadata?.status) args.status = metadata.status
+    const filters = { ...metadata?.filters }
+    // Explicit predicates take precedence over convenience shortcuts.
+    if (metadata?.tags?.length && !("tags" in filters))
+      filters.tags = { $contains: metadata.tags }
+    if (metadata?.status && !("status" in filters))
+      filters.status = metadata.status
+    if (Object.keys(filters).length) args.filters = filters
     if (metadata?.note_types) args.note_types = metadata.note_types
-    if (metadata?.entity_types) args.entity_types = metadata.entity_types
+    if (metadata?.entity_types)
+      args.items = metadata.entity_types.map((item) =>
+        item === "entity" ? "note" : item,
+      )
 
-    const payload = await this.callTool("search_notes", args)
+    const payload = await this.callTool("bm_search", args)
 
     if (!isRecord(payload) || !Array.isArray(payload.results)) {
-      throw new Error("invalid search_notes response")
+      throw new Error("invalid bm_search response")
     }
 
     return payload.results as SearchResult[]
@@ -646,10 +784,10 @@ export class BmClient {
       ...this.routing(project, options.projectId),
     }
 
-    const payload = await this.callTool("read_note", args)
+    const payload = await this.callTool("bm_read", args)
 
     if (!isRecord(payload)) {
-      throw new Error("invalid read_note response")
+      throw new Error("invalid bm_read response")
     }
 
     const title = asString(payload.title)
@@ -658,7 +796,7 @@ export class BmClient {
     const filePath = asString(payload.file_path)
 
     if (!title || !permalink || content === null || !filePath) {
-      throw new Error("invalid read_note payload")
+      throw new Error("invalid bm_read payload")
     }
 
     return {
@@ -695,36 +833,30 @@ export class BmClient {
 
     let payload: unknown
     try {
-      payload = await this.callTool("write_note", args)
+      payload = await this.callTool("bm_write", args)
     } catch (err) {
       const refusal =
         err instanceof BmToolError ? parseRefusalPayload(err.toolMessage) : null
-      if (refusal?.error === "NOTE_ALREADY_EXISTS") {
+      if (refusal?.error === "ALREADY_EXISTS") {
         throw new NoteAlreadyExistsError(
           asString(refusal.title) ?? title,
           asString(refusal.permalink) ?? "",
+          asString(refusal.message) ?? undefined,
         )
       }
-      if (refusal?.error === "NOTE_REVISION_CONFLICT") {
+      if (refusal?.error === "REVISION_CONFLICT") {
         throw new NoteRevisionConflictError(
           asString(refusal.title) ?? title,
           asString(refusal.permalink),
           asString(refusal.currentChecksum),
+          asString(refusal.message) ?? undefined,
         )
       }
       throw err
     }
 
     if (!isRecord(payload)) {
-      throw new Error("invalid write_note response")
-    }
-
-    // Older servers returned the refusal as a successful payload.
-    if (payload.error === "NOTE_ALREADY_EXISTS") {
-      throw new NoteAlreadyExistsError(
-        asString(payload.title) ?? title,
-        asString(payload.permalink) ?? "",
-      )
+      throw new Error("invalid bm_write response")
     }
 
     const resultTitle = asString(payload.title)
@@ -732,7 +864,7 @@ export class BmClient {
     const filePath = asString(payload.file_path)
 
     if (!resultTitle || !permalink || !filePath) {
-      throw new Error("invalid write_note payload")
+      throw new Error("invalid bm_write payload")
     }
 
     return {
@@ -754,16 +886,16 @@ export class BmClient {
     project?: string,
   ): Promise<ContextResult> {
     const args: Record<string, unknown> = {
-      url,
+      identifier: url,
       depth,
       output_format: "json",
       project: this.routedProject(project),
     }
 
-    const payload = await this.callTool("build_context", args)
+    const payload = await this.callTool("bm_context", args)
 
     if (!isRecord(payload) || !Array.isArray(payload.results)) {
-      throw new Error("invalid build_context response")
+      throw new Error("invalid bm_context response")
     }
 
     return payload as unknown as ContextResult
@@ -774,30 +906,31 @@ export class BmClient {
     project?: string,
   ): Promise<RecentResult[]> {
     const args: Record<string, unknown> = {
-      timeframe,
+      command: "recent",
+      since: timeframe,
       output_format: "json",
       project: this.routedProject(project),
     }
 
-    const payload = await this.callTool("recent_activity", args)
+    const payload = await this.callTool("bm_project", args)
 
-    if (Array.isArray(payload)) {
-      return payload as RecentResult[]
+    if (isRecord(payload) && Array.isArray(payload.results)) {
+      return payload.results as RecentResult[]
     }
 
-    throw new Error("invalid recent_activity response")
+    throw new Error("invalid bm_project response")
   }
 
   async editNote(
     identifier: string,
-    operation: "append" | "prepend" | "find_replace" | "replace_section",
+    operation: EditOperation,
     content: string,
     options: EditNoteOptions = {},
     project?: string,
   ): Promise<EditNoteResult> {
     const args: Record<string, unknown> = {
       identifier,
-      operation,
+      command: operation,
       content,
       output_format: "json",
       project: this.routedProject(project),
@@ -808,10 +941,10 @@ export class BmClient {
       args.expected_replacements = options.expected_replacements
     if (options.metadata !== undefined) args.metadata = options.metadata
 
-    const payload = await this.callTool("edit_note", args)
+    const payload = await this.callTool("bm_edit", args)
 
     if (!isRecord(payload)) {
-      throw new Error("invalid edit_note response")
+      throw new Error("invalid bm_edit response")
     }
 
     const title = asString(payload.title)
@@ -819,7 +952,7 @@ export class BmClient {
     const filePath = asString(payload.file_path)
 
     if (!title || !permalink || !filePath) {
-      throw new Error("invalid edit_note payload")
+      throw new Error("invalid bm_edit payload")
     }
 
     return {
@@ -841,14 +974,14 @@ export class BmClient {
       project: this.routedProject(project),
     }
 
-    const payload = await this.callTool("delete_note", args)
+    const payload = await this.callTool("bm_delete", args)
 
     if (!isRecord(payload)) {
-      throw new Error("invalid delete_note response")
+      throw new Error("invalid bm_delete response")
     }
 
-    if (payload.deleted !== true) {
-      throw new Error(`delete_note did not delete "${identifier}"`)
+    if (payload.action !== "deleted") {
+      throw new Error(`bm_delete did not delete "${identifier}"`)
     }
 
     return {
@@ -865,21 +998,21 @@ export class BmClient {
   ): Promise<NoteResult> {
     const args: Record<string, unknown> = {
       identifier,
-      destination_folder: newFolder,
+      destination: `${newFolder.replace(/\/+$/, "")}/`,
       output_format: "json",
       project: this.routedProject(project),
     }
 
-    const payload = await this.callTool("move_note", args)
+    const payload = await this.callTool("bm_move", args)
 
     if (!isRecord(payload)) {
-      throw new Error("invalid move_note response")
+      throw new Error("invalid bm_move response")
     }
 
-    if (payload.moved !== true) {
+    if (payload.action !== "moved") {
       throw new Error(
         asString(payload.error) ??
-          `move_note did not move "${identifier}" to "${newFolder}"`,
+          `bm_move did not move "${identifier}" to "${newFolder}"`,
       )
     }
 
@@ -897,16 +1030,17 @@ export class BmClient {
     project?: string,
   ): Promise<SchemaValidationResult> {
     const args: Record<string, unknown> = {
+      command: "validate",
       output_format: "json",
       project: this.routedProject(project),
     }
     if (noteType) args.note_type = noteType
     if (identifier) args.identifier = identifier
 
-    const payload = await this.callTool("schema_validate", args)
+    const payload = await this.callTool("bm_schema", args)
 
     if (!isRecord(payload)) {
-      throw new Error("invalid schema_validate response")
+      throw new Error("invalid bm_schema response")
     }
 
     return payload as unknown as SchemaValidationResult
@@ -918,16 +1052,17 @@ export class BmClient {
     project?: string,
   ): Promise<SchemaInferResult> {
     const args: Record<string, unknown> = {
+      command: "infer",
       note_type: noteType,
       threshold,
       output_format: "json",
       project: this.routedProject(project),
     }
 
-    const payload = await this.callTool("schema_infer", args)
+    const payload = await this.callTool("bm_schema", args)
 
     if (!isRecord(payload)) {
-      throw new Error("invalid schema_infer response")
+      throw new Error("invalid bm_schema response")
     }
 
     return payload as unknown as SchemaInferResult
@@ -938,31 +1073,76 @@ export class BmClient {
     project?: string,
   ): Promise<SchemaDiffResult> {
     const args: Record<string, unknown> = {
+      command: "diff",
       note_type: noteType,
       output_format: "json",
       project: this.routedProject(project),
     }
 
-    const payload = await this.callTool("schema_diff", args)
+    const payload = await this.callTool("bm_schema", args)
 
     if (!isRecord(payload)) {
-      throw new Error("invalid schema_diff response")
+      throw new Error("invalid bm_schema response")
     }
 
     return payload as unknown as SchemaDiffResult
   }
 
+  /**
+   * Append one user/assistant exchange to today's conversation note.
+   *
+   * With a turnKey the capture is idempotent: the entry carries a marker
+   * derived from the key, and a key already present in today's or
+   * yesterday's note is reported as a duplicate instead of written again.
+   * Yesterday is checked because a host retry can cross midnight.
+   */
   async indexConversation(
     userMessage: string,
     assistantResponse: string,
-  ): Promise<void> {
+    options: { turnKey?: string } = {},
+  ): Promise<ConversationCaptureStatus> {
+    const write = this.conversationWrites.then(() =>
+      this.writeConversationEntry(
+        userMessage,
+        assistantResponse,
+        options.turnKey,
+      ),
+    )
+    this.conversationWrites = write.catch(() => undefined)
+    return write
+  }
+
+  private async writeConversationEntry(
+    userMessage: string,
+    assistantResponse: string,
+    turnKey: string | undefined,
+  ): Promise<ConversationCaptureStatus> {
     const now = new Date()
-    const dateStr = now.toISOString().split("T")[0]
+    const dateStr = conversationDate(now)
     const timeStr = now.toTimeString().slice(0, 5)
     const title = `conversations-${dateStr}`
+    const marker = turnKey ? conversationTurnMarker(turnKey) : null
+
+    // Trigger: the host supplied an advancement key for this turn.
+    // Why: hosts retry commits after a crash, and a second append would
+    //   duplicate the exchange in the note.
+    // Outcome: an already-recorded key short-circuits before any write.
+    if (marker) {
+      const yesterday = new Date(now.getTime() - 24 * 60 * 60 * 1000)
+      for (const candidate of [
+        title,
+        `conversations-${conversationDate(yesterday)}`,
+      ]) {
+        if (await this.noteContains(candidate, marker)) {
+          log.debug(`conversation turn already recorded in: ${candidate}`)
+          return "duplicate"
+        }
+      }
+    }
 
     const entry = [
       `### ${timeStr}`,
+      ...(marker ? [marker] : []),
       "",
       "**User:**",
       userMessage,
@@ -976,7 +1156,7 @@ export class BmClient {
     try {
       await this.editNote(title, "append", entry)
       log.debug(`appended conversation to: ${title}`)
-      return
+      return "committed"
     } catch (err) {
       if (!isNoteNotFoundError(err)) {
         log.error(`conversation append failed: ${getErrorMessage(err)}`, err)
@@ -1001,11 +1181,21 @@ export class BmClient {
       entry,
     ].join("\n")
 
+    await this.writeNote(title, content, "conversations")
+    log.debug(`created conversation note: ${title}`)
+    return "committed"
+  }
+
+  private async noteContains(
+    identifier: string,
+    text: string,
+  ): Promise<boolean> {
     try {
-      await this.writeNote(title, content, "conversations")
-      log.debug(`created conversation note: ${title}`)
+      const note = await this.readNote(identifier)
+      return note.content.includes(text)
     } catch (err) {
-      log.error("conversation index failed", err)
+      if (isNoteNotFoundError(err)) return false
+      throw err
     }
   }