@basicmemory/openclaw-basic-memory 0.23.1 → 0.24.0

package/README.md

@@ -161,8 +161,8 @@ All tools accept an optional `project` parameter for cross-project operations.
 | `memory_get` | Read a specific note by title or path |
 | `search_notes` | Search the knowledge graph directly |
 | `read_note` | Read a note by title, permalink, or `memory://` URL |
-| `write_note` | Create or update a note |
-| `edit_note` | Append, prepend, find/replace, or replace a section |
+| `write_note` | Create or overwrite a note with optional tags, note type, and custom frontmatter metadata |
+| `edit_note` | Append, prepend, replace content, and merge custom frontmatter metadata |
 | `delete_note` | Delete a note |
 | `move_note` | Move a note to a different folder |
 | `build_context` | Navigate the knowledge graph — follow relations and connections |
@@ -172,6 +172,22 @@ All tools accept an optional `project` parameter for cross-project operations.
 | `schema_infer` | Analyze notes and suggest a schema |
 | `schema_diff` | Detect drift between schema and actual usage |
 
+Use the dedicated frontmatter parameters when creating structured notes:
+
+```
+write_note(
+  title="auth-middleware-rollout",
+  folder="tasks",
+  note_type="Task",
+  tags=["auth", "rollout"],
+  metadata={"status": "active", "current_step": 2},
+  content="""## Context
+Rolling JWT middleware to all API routes."""
+)
+```
+
+`edit_note` accepts `metadata` alongside any edit operation, so content and frontmatter state can be updated in one call. Metadata keys supplied by the caller are merged into existing frontmatter; unrelated fields remain unchanged.
+
 ## Slash commands
 
 | Command | Description |
@@ -196,14 +212,17 @@ openclaw basic-memory status
 
 ## Bundled skills
 
-Ten skills ship with the plugin — no installation needed:
+These skills ship with the plugin — no installation needed:
 
-- **memory-defrag** — cleanup and reorganization of memory files
+- **memory-comark** — charts, tables, boards, and live views in notes with `::bm-*` components
+- **memory-defrag** — cleanup and reorganization of a project's notes
 - **memory-ingest** — import existing material into Basic Memory
 - **memory-lifecycle** — manage note/project lifecycle workflows
 - **memory-literary-analysis** — analyze texts and reading notes
 - **memory-metadata-search** — query notes by frontmatter fields
 - **memory-notes** — guidance for writing well-structured notes
+- **memory-okf** — make a project ready for OKF export
+- **memory-onboarding** — guided setup of a new knowledge system
 - **memory-reflect** — periodic consolidation of recent notes into durable memory
 - **memory-research** — research synthesis into durable notes
 - **memory-schema** — schema lifecycle (infer, create, validate, diff)
@@ -253,14 +272,12 @@ Cloud extends local-first — still plain Markdown, still yours. [Start a free t
 
 ## Troubleshooting
 
-**`bm` not found** — Install uv, then restart the gateway. Or install manually: `uv tool install basic-memory`
+**`bm` not found** — Install uv, then restart the gateway. Or install manually: `uv tool install basic-memory --prerelease=allow` (the flag is required — basic-memory depends on a FastMCP pre-release, and without it uv silently installs an older release)
 
 **Search returns nothing** — Check that Basic Memory connected (look for `connected to BM` in logs). Verify files exist in the project directory.
 
 **Jiti cache issues** — `rm -rf /tmp/jiti/ "$TMPDIR/jiti/"` then restart the gateway.
 
-**Disable semantic search** — Set `BASIC_MEMORY_SEMANTIC_SEARCH_ENABLED=false` to fall back to full-text only.
-
 ## More
 
 - [Memory + Task Flow](./MEMORY_TASK_FLOW.md) — practical runbook

package/bm-client.ts

@@ -14,6 +14,40 @@ export class NoteAlreadyExistsError extends Error {
   }
 }
 
+/**
+ * write_note 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).
+ */
+export class NoteRevisionConflictError extends Error {
+  readonly permalink: string | null
+  readonly currentChecksum: string | null
+  constructor(
+    title: string,
+    permalink: string | null,
+    currentChecksum: string | null,
+  ) {
+    super(`Note revision conflict: "${title}" changed since it was read`)
+    this.name = "NoteRevisionConflictError"
+    this.permalink = permalink
+    this.currentChecksum = currentChecksum
+  }
+}
+
+/** A BM MCP tool returned isError; toolMessage is the tool's own error text. */
+export class BmToolError extends Error {
+  readonly toolName: string
+  readonly toolMessage: string
+  constructor(toolName: string, toolMessage: string) {
+    super(
+      `BM MCP tool ${toolName} failed${toolMessage ? `: ${toolMessage}` : ""}`,
+    )
+    this.name = "BmToolError"
+    this.toolName = toolName
+    this.toolMessage = toolMessage
+  }
+}
+
 const REQUIRED_TOOLS = [
   "search_notes",
   "read_note",
@@ -59,12 +93,25 @@ export interface EditNoteResult {
 
 interface ReadNoteOptions {
   includeFrontmatter?: boolean
+  /** Project external_id; routes to that exact project instead of by name. */
+  projectId?: string
+}
+
+interface WriteNoteOptions {
+  metadata?: Record<string, unknown>
+  tags?: string[] | string
+  noteType?: string
+  /** Project external_id; routes to that exact project instead of by name. */
+  projectId?: string
+  /** Checksum of the revision read; overwrite only while it is still current. */
+  expectedChecksum?: string
 }
 
 interface EditNoteOptions {
   find_text?: string
   section?: string
   expected_replacements?: number
+  metadata?: Record<string, unknown>
 }
 
 export interface ContextResult {
@@ -95,6 +142,9 @@ export interface RecentResult {
 export interface ProjectListResult {
   name: string
   path: string
+  external_id?: string | null
+  source?: string | null
+  qualified_name?: string | null
   display_name?: string | null
   is_private?: boolean
   is_default?: boolean
@@ -214,6 +264,19 @@ 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
+// error text (plain-text failures, older servers) is not a refusal payload.
+function parseRefusalPayload(text: string): Record<string, unknown> | null {
+  let parsed: unknown
+  try {
+    parsed = JSON.parse(text)
+  } catch {
+    return null
+  }
+  return isRecord(parsed) && typeof parsed.error === "string" ? parsed : null
+}
+
 function projectMatchesWorkspace(
   project: ProjectListResult,
   workspace: string,
@@ -432,10 +495,7 @@ export class BmClient {
         })
 
         if (isRecord(result) && result.isError === true) {
-          const message = extractTextFromContent(result.content)
-          throw new Error(
-            `BM MCP tool ${name} failed${message ? `: ${message}` : ""}`,
-          )
+          throw new BmToolError(name, extractTextFromContent(result.content))
         }
 
         return result
@@ -486,6 +546,17 @@ 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 }
+    return { project: this.routedProject(project) }
+  }
+
   async ensureProject(projectPath: string): Promise<void> {
     const payload = await this.callTool("create_memory_project", {
       project_name: this.project,
@@ -572,7 +643,7 @@ export class BmClient {
       identifier,
       include_frontmatter: options.includeFrontmatter === true,
       output_format: "json",
-      project: this.routedProject(project),
+      ...this.routing(project, options.projectId),
     }
 
     const payload = await this.callTool("read_note", args)
@@ -596,6 +667,7 @@ export class BmClient {
       content,
       file_path: filePath,
       frontmatter: isRecord(payload.frontmatter) ? payload.frontmatter : null,
+      checksum: asString(payload.checksum),
     }
   }
 
@@ -605,22 +677,49 @@ export class BmClient {
     folder: string,
     project?: string,
     overwrite?: boolean,
+    options: WriteNoteOptions = {},
   ): Promise<NoteResult> {
     const args: Record<string, unknown> = {
       title,
       content,
       directory: folder,
       output_format: "json",
-      project: this.routedProject(project),
+      ...this.routing(project, options.projectId),
     }
     if (overwrite !== undefined) args.overwrite = overwrite
+    if (options.metadata !== undefined) args.metadata = options.metadata
+    if (options.tags !== undefined) args.tags = options.tags
+    if (options.noteType !== undefined) args.note_type = options.noteType
+    if (options.expectedChecksum !== undefined)
+      args.expected_checksum = options.expectedChecksum
 
-    const payload = await this.callTool("write_note", args)
+    let payload: unknown
+    try {
+      payload = await this.callTool("write_note", args)
+    } catch (err) {
+      const refusal =
+        err instanceof BmToolError ? parseRefusalPayload(err.toolMessage) : null
+      if (refusal?.error === "NOTE_ALREADY_EXISTS") {
+        throw new NoteAlreadyExistsError(
+          asString(refusal.title) ?? title,
+          asString(refusal.permalink) ?? "",
+        )
+      }
+      if (refusal?.error === "NOTE_REVISION_CONFLICT") {
+        throw new NoteRevisionConflictError(
+          asString(refusal.title) ?? title,
+          asString(refusal.permalink),
+          asString(refusal.currentChecksum),
+        )
+      }
+      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,
@@ -707,6 +806,7 @@ export class BmClient {
     if (options.section) args.section = options.section
     if (options.expected_replacements != null)
       args.expected_replacements = options.expected_replacements
+    if (options.metadata !== undefined) args.metadata = options.metadata
 
     const payload = await this.callTool("edit_note", args)
 

package/dist/bm-client.d.ts

@@ -2,6 +2,22 @@ export declare class NoteAlreadyExistsError extends Error {
     readonly permalink: string;
     constructor(title: string, permalink: string);
 }
+/**
+ * write_note 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).
+ */
+export declare class NoteRevisionConflictError extends Error {
+    readonly permalink: string | null;
+    readonly currentChecksum: string | null;
+    constructor(title: string, permalink: string | null, currentChecksum: string | null);
+}
+/** A BM MCP tool returned isError; toolMessage is the tool's own error text. */
+export declare class BmToolError extends Error {
+    readonly toolName: string;
+    readonly toolMessage: string;
+    constructor(toolName: string, toolMessage: string);
+}
 export interface SearchResult {
     title: string;
     permalink: string;
@@ -27,11 +43,23 @@ export interface EditNoteResult {
 }
 interface ReadNoteOptions {
     includeFrontmatter?: boolean;
+    /** Project external_id; routes to that exact project instead of by name. */
+    projectId?: string;
+}
+interface WriteNoteOptions {
+    metadata?: Record<string, unknown>;
+    tags?: string[] | string;
+    noteType?: string;
+    /** Project external_id; routes to that exact project instead of by name. */
+    projectId?: string;
+    /** Checksum of the revision read; overwrite only while it is still current. */
+    expectedChecksum?: string;
 }
 interface EditNoteOptions {
     find_text?: string;
     section?: string;
     expected_replacements?: number;
+    metadata?: Record<string, unknown>;
 }
 export interface ContextResult {
     results: Array<{
@@ -59,6 +87,9 @@ export interface RecentResult {
 export interface ProjectListResult {
     name: string;
     path: string;
+    external_id?: string | null;
+    source?: string | null;
+    qualified_name?: string | null;
     display_name?: string | null;
     is_private?: boolean;
     is_default?: boolean;
@@ -149,6 +180,7 @@ export declare class BmClient {
     private callToolRaw;
     private callTool;
     private routedProject;
+    private routing;
     ensureProject(projectPath: string): Promise<void>;
     listWorkspaces(): Promise<WorkspaceResult[]>;
     listProjects(workspace?: string): Promise<ProjectListResult[]>;
@@ -160,7 +192,7 @@ export declare class BmClient {
         entity_types?: string[];
     }): Promise<SearchResult[]>;
     readNote(identifier: string, options?: ReadNoteOptions, project?: string): Promise<NoteResult>;
-    writeNote(title: string, content: string, folder: string, project?: string, overwrite?: boolean): Promise<NoteResult>;
+    writeNote(title: string, content: string, folder: string, project?: string, overwrite?: boolean, options?: WriteNoteOptions): Promise<NoteResult>;
     buildContext(url: string, depth?: number, project?: string): Promise<ContextResult>;
     recentActivity(timeframe?: string, project?: string): Promise<RecentResult[]>;
     editNote(identifier: string, operation: "append" | "prepend" | "find_replace" | "replace_section", content: string, options?: EditNoteOptions, project?: string): Promise<EditNoteResult>;

package/dist/bm-client.js

@@ -11,6 +11,32 @@ export class NoteAlreadyExistsError extends Error {
         this.permalink = permalink;
     }
 }
+/**
+ * write_note 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).
+ */
+export class NoteRevisionConflictError extends Error {
+    permalink;
+    currentChecksum;
+    constructor(title, permalink, currentChecksum) {
+        super(`Note revision conflict: "${title}" changed since it was read`);
+        this.name = "NoteRevisionConflictError";
+        this.permalink = permalink;
+        this.currentChecksum = currentChecksum;
+    }
+}
+/** A BM MCP tool returned isError; toolMessage is the tool's own error text. */
+export class BmToolError extends Error {
+    toolName;
+    toolMessage;
+    constructor(toolName, toolMessage) {
+        super(`BM MCP tool ${toolName} failed${toolMessage ? `: ${toolMessage}` : ""}`);
+        this.name = "BmToolError";
+        this.toolName = toolName;
+        this.toolMessage = toolMessage;
+    }
+}
 const REQUIRED_TOOLS = [
     "search_notes",
     "read_note",
@@ -65,6 +91,19 @@ function isNoteNotFoundError(err) {
 function asString(value) {
     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
+// error text (plain-text failures, older servers) is not a refusal payload.
+function parseRefusalPayload(text) {
+    let parsed;
+    try {
+        parsed = JSON.parse(text);
+    }
+    catch {
+        return null;
+    }
+    return isRecord(parsed) && typeof parsed.error === "string" ? parsed : null;
+}
 function projectMatchesWorkspace(project, workspace) {
     const requested = workspace.trim().toLowerCase();
     if (!requested)
@@ -235,8 +274,7 @@ export class BmClient {
                     arguments: args,
                 });
                 if (isRecord(result) && result.isError === true) {
-                    const message = extractTextFromContent(result.content);
-                    throw new Error(`BM MCP tool ${name} failed${message ? `: ${message}` : ""}`);
+                    throw new BmToolError(name, extractTextFromContent(result.content));
                 }
                 return result;
             }
@@ -272,6 +310,14 @@ export class BmClient {
     routedProject(project) {
         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.
+    routing(project, projectId) {
+        if (projectId !== undefined)
+            return { project_id: projectId };
+        return { project: this.routedProject(project) };
+    }
     async ensureProject(projectPath) {
         const payload = await this.callTool("create_memory_project", {
             project_name: this.project,
@@ -335,7 +381,7 @@ export class BmClient {
             identifier,
             include_frontmatter: options.includeFrontmatter === true,
             output_format: "json",
-            project: this.routedProject(project),
+            ...this.routing(project, options.projectId),
         };
         const payload = await this.callTool("read_note", args);
         if (!isRecord(payload)) {
@@ -354,22 +400,45 @@ export class BmClient {
             content,
             file_path: filePath,
             frontmatter: isRecord(payload.frontmatter) ? payload.frontmatter : null,
+            checksum: asString(payload.checksum),
         };
     }
-    async writeNote(title, content, folder, project, overwrite) {
+    async writeNote(title, content, folder, project, overwrite, options = {}) {
         const args = {
             title,
             content,
             directory: folder,
             output_format: "json",
-            project: this.routedProject(project),
+            ...this.routing(project, options.projectId),
         };
         if (overwrite !== undefined)
             args.overwrite = overwrite;
-        const payload = await this.callTool("write_note", args);
+        if (options.metadata !== undefined)
+            args.metadata = options.metadata;
+        if (options.tags !== undefined)
+            args.tags = options.tags;
+        if (options.noteType !== undefined)
+            args.note_type = options.noteType;
+        if (options.expectedChecksum !== undefined)
+            args.expected_checksum = options.expectedChecksum;
+        let payload;
+        try {
+            payload = await this.callTool("write_note", args);
+        }
+        catch (err) {
+            const refusal = err instanceof BmToolError ? parseRefusalPayload(err.toolMessage) : null;
+            if (refusal?.error === "NOTE_ALREADY_EXISTS") {
+                throw new NoteAlreadyExistsError(asString(refusal.title) ?? title, asString(refusal.permalink) ?? "");
+            }
+            if (refusal?.error === "NOTE_REVISION_CONFLICT") {
+                throw new NoteRevisionConflictError(asString(refusal.title) ?? title, asString(refusal.permalink), asString(refusal.currentChecksum));
+            }
+            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) ?? "");
         }
@@ -429,6 +498,8 @@ export class BmClient {
             args.section = options.section;
         if (options.expected_replacements != null)
             args.expected_replacements = options.expected_replacements;
+        if (options.metadata !== undefined)
+            args.metadata = options.metadata;
         const payload = await this.callTool("edit_note", args);
         if (!isRecord(payload)) {
             throw new Error("invalid edit_note response");

package/dist/index.js

@@ -77,7 +77,15 @@ export default definePluginEntry({
                             throw new Error("uv not found");
                         }
                         log.info("installing basic-memory via uv (this may take a minute)...");
-                        const result = execFileSync("uv", ["tool", "install", "basic-memory", "--force"], {
+                        // basic-memory pins a FastMCP pre-release; without this flag uv
+                        // silently installs the last release that had none (#1338).
+                        const result = execFileSync("uv", [
+                            "tool",
+                            "install",
+                            "basic-memory",
+                            "--prerelease=allow",
+                            "--force",
+                        ], {
                             encoding: "utf-8",
                             timeout: 120_000,
                             stdio: ["ignore", "pipe", "pipe"],

package/dist/tools/edit-note.js

@@ -6,7 +6,9 @@ export function registerEditTool(api, client) {
         label: "Edit Note",
         description: "Incrementally edit an existing note in the Basic Memory knowledge graph. " +
             "Supports append, prepend, find/replace, and section replacement " +
-            "without rewriting the entire note.",
+            "without rewriting the entire note. The result returns the note's " +
+            "permalink and file_path: cite those exact values when confirming " +
+            "the edit — never report a save that no tool call performed.",
         parameters: Type.Object({
             identifier: Type.String({
                 description: "Note title, permalink, or memory:// URL to edit",
@@ -35,6 +37,10 @@ export function registerEditTool(api, client) {
             project: Type.Optional(Type.String({
                 description: "Target project name (defaults to current project)",
             })),
+            metadata: Type.Optional(Type.Object({}, {
+                additionalProperties: true,
+                description: "Frontmatter fields to merge independently of the edit operation. Nested objects are supported.",
+            })),
         }),
         async execute(_toolCallId, params) {
             log.debug(`edit_note: id="${params.identifier}" op=${params.operation}`);
@@ -43,6 +49,7 @@ export function registerEditTool(api, client) {
                     find_text: params.find_text,
                     section: params.section,
                     expected_replacements: params.expected_replacements,
+                    metadata: params.metadata,
                 }, params.project);
                 return {
                     content: [

package/dist/tools/list-memory-projects.js

@@ -3,6 +3,9 @@ import { log } from "../logger.js";
 function normalizeProject(project) {
     return {
         name: project.name,
+        external_id: project.external_id ?? null,
+        qualified_name: project.qualified_name ?? null,
+        source: project.source ?? null,
         path: project.path,
         display_name: project.display_name ?? null,
         is_private: project.is_private === true,
@@ -17,7 +20,12 @@ export function registerProjectListTool(api, client) {
     api.registerTool({
         name: "list_memory_projects",
         label: "List Projects",
-        description: "List all Basic Memory projects accessible to this agent",
+        description: "List Basic Memory projects accessible to this agent, optionally filtered by " +
+            "workspace. Returns each project's name, external_id, source (local, cloud, " +
+            "or local+cloud), path, default flag, workspace, and qualified name. " +
+            "Call this before passing `project` to another tool when the user names a " +
+            "project that isn't the default. Pass a project's external_id as " +
+            "`project_id` to route to that exact project.",
         parameters: Type.Object({
             workspace: Type.Optional(Type.String({
                 description: "Filter by workspace name, slug, or tenant_id",
@@ -45,10 +53,20 @@ export function registerProjectListTool(api, client) {
                 const text = normalized
                     .map((project, idx) => {
                     const defaultSuffix = project.is_default ? " (default)" : "";
-                    const displayLine = project.display_name
-                        ? `\n   Display Name: ${project.display_name}`
-                        : "";
-                    return `${idx + 1}. **${project.name}**${defaultSuffix}\n   Path: ${project.path}\n   Private: ${project.is_private}${displayLine}`;
+                    const lines = [
+                        `${idx + 1}. **${project.name}**${defaultSuffix}`,
+                        project.external_id ? `   ID: ${project.external_id}` : null,
+                        project.source ? `   Source: ${project.source}` : null,
+                        `   Path: ${project.path}`,
+                        `   Private: ${project.is_private}`,
+                        project.display_name
+                            ? `   Display Name: ${project.display_name}`
+                            : null,
+                        project.qualified_name
+                            ? `   Qualified Name: ${project.qualified_name}`
+                            : null,
+                    ];
+                    return lines.filter((line) => line !== null).join("\n");
                 })
                     .join("\n\n");
                 return {

package/dist/tools/list-workspaces.js

@@ -9,7 +9,9 @@ export function registerWorkspaceListTool(api, client) {
     api.registerTool({
         name: "list_workspaces",
         label: "List Workspaces",
-        description: "List all Basic Memory workspaces (personal and organization) accessible to this user",
+        description: "List all Basic Memory workspaces (personal and organization) accessible to this user. " +
+            "Use it to find the workspace to pass to list_memory_projects when the same " +
+            "project name may exist in more than one workspace.",
         parameters: Type.Object({}),
         async execute(_toolCallId, _params) {
             log.debug("list_workspaces");

package/dist/tools/memory-provider.js

@@ -140,7 +140,8 @@ export function registerMemoryProvider(api, client, cfg) {
         label: "Memory Search",
         description: "Search across all memory sources: MEMORY.md (working memory), " +
             "Basic Memory knowledge graph (long-term archive), and active tasks. " +
-            "Returns composited results from all sources.",
+            "Returns composited results from all sources. Use it for broad recall; use " +
+            "search_notes when you need metadata, tag, or status filters or a specific project.",
         parameters: Type.Object({
             query: Type.String({
                 description: "Search query — natural language or keywords",

package/dist/tools/read-note.js

@@ -5,7 +5,9 @@ export function registerReadTool(api, client) {
         name: "read_note",
         label: "Read Note",
         description: "Read a specific note from the Basic Memory knowledge graph by title or permalink. " +
-            "Returns the full note content including observations and relations.",
+            "Returns the full note content including observations and relations, " +
+            "followed by the note's checksum: pass it to write_note as " +
+            "expected_checksum (with overwrite=true) to replace only this revision.",
         parameters: Type.Object({
             identifier: Type.String({
                 description: "Note title, permalink, or memory:// URL to read",
@@ -16,16 +18,28 @@ export function registerReadTool(api, client) {
             project: Type.Optional(Type.String({
                 description: "Target project name (defaults to current project)",
             })),
+            project_id: Type.Optional(Type.String({
+                description: "Target project external_id from list_memory_projects. Routes to " +
+                    "that exact project and takes precedence over `project`.",
+            })),
         }),
         async execute(_toolCallId, params) {
             log.debug(`read_note: identifier="${params.identifier}"`);
             try {
-                const note = await client.readNote(params.identifier, { includeFrontmatter: params.include_frontmatter === true }, params.project);
+                const note = await client.readNote(params.identifier, {
+                    includeFrontmatter: params.include_frontmatter === true,
+                    projectId: params.project_id,
+                }, params.project);
+                // The checksum identifies the revision just read; the model sees only
+                // `content`, so it has to travel in the text to reach a guarded write.
+                const text = note.checksum
+                    ? `${note.content}\n\nChecksum: ${note.checksum}`
+                    : note.content;
                 return {
                     content: [
                         {
                             type: "text",
-                            text: note.content,
+                            text,
                         },
                     ],
                     details: {
@@ -33,6 +47,7 @@ export function registerReadTool(api, client) {
                         permalink: note.permalink,
                         file_path: note.file_path,
                         frontmatter: note.frontmatter ?? null,
+                        checksum: note.checksum ?? null,
                     },
                 };
             }

package/dist/tools/search-notes.js

@@ -6,7 +6,9 @@ export function registerSearchTool(api, client) {
         label: "Knowledge Search",
         description: "Search the Basic Memory knowledge graph for relevant notes, concepts, and connections. " +
             "Returns matching notes with titles, content previews, and relevance scores. " +
-            "Optionally filter by frontmatter metadata fields, tags, or status.",
+            "Optionally filter by frontmatter metadata fields, tags, or status, or target " +
+            "another project. For a quick cross-source recall that also covers MEMORY.md " +
+            "and active tasks, use memory_search.",
         parameters: Type.Object({
             query: Type.String({ description: "Search query" }),
             limit: Type.Optional(Type.Number({ description: "Max results (default: 10)" })),