@basicmemory/openclaw-basic-memory 0.23.1 → 0.24.0

package/skills/memory-schema/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: memory-schema
-description: "Schema lifecycle management for Basic Memory: discover unschemaed notes, infer schemas, create and edit schema definitions, validate notes, and detect drift. Use when working with structured note types (Task, Person, Meeting, etc.) to maintain consistency across the knowledge graph."
+description: "Manage Basic Memory schemas: find unschemaed notes, infer and edit schemas, validate notes, detect drift. Use when structured note types (Task, Person, Meeting) need consistency across the graph."
 ---
 
 # Memory Schema
@@ -112,12 +112,12 @@ settings:
 
 Look for clusters of notes that share structure but have no schema:
 
-1. **Search by type**: `search_notes(query="type:Meeting")` — if many notes share a `type` but no `schema/Meeting.md` exists, it's a candidate.
+1. **Search by type**: `search_notes(note_types=["meeting"])` — if many notes share a `type` but no `schema/Meeting.md` exists, it's a candidate.
 
 2. **Infer a schema**: Use `schema_infer` to analyze existing notes and generate a suggested schema:
    ```python
-   schema_infer(noteType="Meeting")
-   schema_infer(noteType="Meeting", threshold=0.5)  # fields in 50%+ of notes
+   schema_infer(note_type="Meeting")
+   schema_infer(note_type="Meeting", threshold=0.5)  # fields in 50%+ of notes
    ```
    The threshold (0.0–1.0) controls how common a field must be to be included. Default is usually fine; lower it to catch rarer fields.
 
@@ -168,7 +168,7 @@ Check how well existing notes conform to their schema:
 
 ```python
 # Validate all notes of a type
-schema_validate(noteType="Meeting")
+schema_validate(note_type="Meeting")
 
 # Validate a single note
 schema_validate(identifier="meetings/2026-02-10-standup")
@@ -176,11 +176,10 @@ schema_validate(identifier="meetings/2026-02-10-standup")
 
 **Important:** `schema_validate` checks for schema fields as **observation categories** in the note body — e.g., a `status` field expects `- [status] active` as an observation. Fields stored only in frontmatter metadata won't satisfy validation. To pass cleanly, include schema fields as both frontmatter values (for metadata search) and observations (for schema validation).
 
-Validation reports:
-- **Missing required fields** — the note lacks a field the schema requires (as an observation category)
-- **Unknown fields** — the note has fields the schema doesn't define
-- **Type mismatches** — a field value doesn't match the expected type
-- **Invalid enum values** — a value isn't in the allowed set
+Validation reports **missing required fields** (as observation categories, or relations
+for entity-reference fields) and **invalid enum values**. Undeclared observation categories
+and relations are listed as informational "unmatched" items. Scalar values are not
+type-checked.
 
 ### Handling Validation Results
 
@@ -192,32 +191,41 @@ Validation reports:
 Over time, notes evolve and schemas lag behind. Use `schema_diff` to find divergence:
 
 ```python
-schema_diff(noteType="Meeting")
+schema_diff(note_type="Meeting")
 ```
 
 Diff reports:
 - **Fields in notes but not in schema** — candidates for adding to the schema (as optional)
 - **Schema fields rarely used** — consider making optional or removing
-- **Type inconsistencies** — fields used as different types across notes
+- **Cardinality changes** — a field that moved between single-value and array
 
 ## Schema Evolution
 
 When note structure changes:
 
-1. **Run diff** to see current state: `schema_diff(noteType="Meeting")`
-2. **Update the schema note** via `edit_note`:
+1. **Run diff** to see current state: `schema_diff(note_type="Meeting")`
+2. **Update the schema note** via `edit_note` with the `metadata` parameter. Top-level
+   keys are replaced whole, so pass the complete updated `schema` map along with the new
+   `version`:
    ```python
    edit_note(
      identifier="schema/Meeting",
-     operation="find_replace",
-     find_text="version: 1",
-     content="version: 2",
-     expected_replacements=1
+     operation="append",
+     content="",
+     metadata={
+       "version": 2,
+       "schema": {
+         "topic": "string, what was discussed",
+         "date": "string, when it happened",
+         "attendees?(array)": "Person, who attended",
+         "decisions?(array)": "string, decisions made",
+         "location?": "string, where it happened"
+       }
+     }
    )
    ```
-3. **Add/remove/modify fields** in the `schema:` block
-4. **Re-validate** to confirm existing notes still pass: `schema_validate(noteType="Meeting")`
-5. **Fix outliers** — update notes that don't conform to the new schema
+3. **Re-validate** to confirm existing notes still pass: `schema_validate(note_type="Meeting")`
+4. **Fix outliers** — update notes that don't conform to the new schema
 
 ### Evolution Guidelines
 

package/skills/memory-tasks/SKILL.md

@@ -16,7 +16,7 @@ Manage work-in-progress using Basic Memory's schema system. Tasks are just notes
 
 ## Task Schema
 
-Tasks use the BM schema system (SPEC-SCHEMA). The schema note lives at `memory/schema/Task.md`:
+Tasks use the BM schema system. The schema note lives at `schema/Task.md`:
 
 ```yaml
 ---
@@ -52,6 +52,7 @@ write_note(
   metadata={
     "status": "active",
     "priority": "high",
+    "assigned_to": "claude",
     "current_step": 1,
     "steps": ["First step", "Second step", "Third step"]
   },
@@ -85,7 +86,7 @@ What future-you needs to pick up this work. Include:
 - **Steps are concrete and checkable** — "Implement X in file Y", not "figure out stuff"
 - **Context is for post-amnesia resumption** — Write it as if explaining to a smart person who knows nothing about what you've been doing
 - **Relations link to other entities** — `parent_task [[Other Task]]`, `related_to [[Some Note]]`
-- **`note_types` is case-sensitive** — `write_note(note_type="Task")` stores the type as lowercase `task` in frontmatter. Use `note_types=["task"]` (lowercase) in search queries.
+- **Note types are normalized to snake_case** — `write_note(note_type="Task")` stores `type: task`, and `note_types=["Task"]` or `note_types=["task"]` both match it.
 
 ## Resuming After Compaction
 
@@ -116,9 +117,21 @@ As work progresses, update the task note:
 Updated context reflecting current state...
 ```
 
-Update frontmatter too:
-```yaml
-current_step: 3
+Read the task as JSON first and pass its checksum as `expected_checksum` on each
+edit. Two sessions often update the same task, for example in a pre-compaction
+flush; a revision conflict means the other one wrote first, so re-read before
+writing.
+
+Update frontmatter too, with the `metadata` parameter (empty `content` leaves the body alone):
+```python
+task = read_note(identifier="tasks/descriptive-task-name", output_format="json")
+edit_note(
+  identifier="tasks/descriptive-task-name",
+  operation="append",
+  content="",
+  metadata={"current_step": 3},
+  expected_checksum=task["checksum"]
+)
 ```
 
 ## Completing Tasks
@@ -140,7 +153,7 @@ When a compaction event is imminent:
    - `current_step` to reflect actual progress
    - `context` with everything needed to resume
    - Step checkboxes to show what's done
-3. This is **critical** — context not written down is context lost
+3. Context that isn't written down is lost at compaction
 
 ## Querying Tasks
 
@@ -153,14 +166,27 @@ With BM's schema system, tasks are fully queryable:
 | `search_notes(note_types=["task"], status="blocked")` | Blocked tasks |
 | `search_notes(note_types=["task"], metadata_filters={"assigned_to": "claude"})` | My tasks |
 | `search_notes("blockers", note_types=["task"])` | Tasks with blockers |
-| `schema_validate(noteType="Task")` | Validate all tasks against schema |
-| `schema_diff(noteType="Task")` | Detect drift between schema and actual task notes |
+| `search_notes(note_types=["task"], time_kind="due", valid_overlaps="[2026-10-14,2026-10-21)")` | Tasks with a step due this week |
+| `schema_validate(note_type="Task")` | Validate all tasks against schema |
+| `schema_diff(note_type="Task")` | Detect drift between schema and actual task notes |
+
+### Due Dates
+
+Give a step or the task a due date with a qualifier (see **memory-notes**), so
+"what's due" is one search:
+
+```markdown
+- [deadline] @due:2026-10-20 Draft ready for review
+```
+
+A day-precision due date counts from that day onward, so a due-this-week search
+also returns overdue items.
 
 ## Guidelines
 
 - **One task per unit of work** — Don't cram multiple projects into one task
-- **Externalize early** — If you think "I should remember this", write it down NOW
+- **Externalize early** — write things down when you notice them
 - **Context > steps** — Steps tell you what to do; context tells you why and how
 - **Close finished tasks** — Don't leave completed work as `active`
 - **Link related tasks** — Use `parent_task [[X]]` or relations to connect related work
-- **Schema validation is your friend** — Run `schema_validate(noteType="Task")` periodically to catch incomplete tasks
+- **Schema validation is your friend** — Run `schema_validate(note_type="Task")` periodically to catch incomplete tasks

package/tools/edit-note.ts

@@ -14,7 +14,9 @@ export function registerEditTool(
       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",
@@ -57,6 +59,16 @@ export function registerEditTool(
             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: string,
@@ -68,6 +80,7 @@ export function registerEditTool(
           section?: string
           expected_replacements?: number
           project?: string
+          metadata?: Record<string, unknown>
         },
       ) {
         log.debug(`edit_note: id="${params.identifier}" op=${params.operation}`)
@@ -81,6 +94,7 @@ export function registerEditTool(
               find_text: params.find_text,
               section: params.section,
               expected_replacements: params.expected_replacements,
+              metadata: params.metadata,
             },
             params.project,
           )

package/tools/list-memory-projects.ts

@@ -6,6 +6,9 @@ import { log } from "../logger.ts"
 function normalizeProject(project: ProjectListResult) {
   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,
@@ -25,7 +28,13 @@ export function registerProjectListTool(
     {
       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({
@@ -58,10 +67,20 @@ export function registerProjectListTool(
           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")
 

package/tools/list-workspaces.ts

@@ -20,7 +20,9 @@ export function registerWorkspaceListTool(
       name: "list_workspaces",
       label: "List Workspaces",
       description:
-        "List all Basic Memory workspaces (personal and organization) accessible to this user",
+        "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: string, _params: Record<string, never>) {
         log.debug("list_workspaces")

package/tools/memory-provider.ts

@@ -175,7 +175,8 @@ export function registerMemoryProvider(
       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/tools/read-note.ts

@@ -13,7 +13,9 @@ export function registerReadTool(
       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",
@@ -29,6 +31,13 @@ export function registerReadTool(
             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: string,
@@ -36,6 +45,7 @@ export function registerReadTool(
           identifier: string
           include_frontmatter?: boolean
           project?: string
+          project_id?: string
         },
       ) {
         log.debug(`read_note: identifier="${params.identifier}"`)
@@ -43,15 +53,23 @@ export function registerReadTool(
         try {
           const note = await client.readNote(
             params.identifier,
-            { includeFrontmatter: params.include_frontmatter === true },
+            {
+              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" as const,
-                text: note.content,
+                text,
               },
             ],
             details: {
@@ -59,6 +77,7 @@ export function registerReadTool(
               permalink: note.permalink,
               file_path: note.file_path,
               frontmatter: note.frontmatter ?? null,
+              checksum: note.checksum ?? null,
             },
           }
         } catch (err) {

package/tools/search-notes.ts

@@ -14,7 +14,9 @@ export function registerSearchTool(
       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(

package/tools/write-note.ts

@@ -1,7 +1,10 @@
 import { Type } from "@sinclair/typebox"
 import type { OpenClawPluginApi } from "openclaw/plugin-sdk/plugin-entry"
 import type { BmClient } from "../bm-client.ts"
-import { NoteAlreadyExistsError } from "../bm-client.ts"
+import {
+  NoteAlreadyExistsError,
+  NoteRevisionConflictError,
+} from "../bm-client.ts"
 import { log } from "../logger.ts"
 
 export function registerWriteTool(
@@ -14,8 +17,14 @@ export function registerWriteTool(
       label: "Write Note",
       description:
         "Create a note in the Basic Memory knowledge graph. " +
+        "Call this whenever the user asks to remember, record, save, or note " +
+        "something — saying 'saved' without this call saves nothing. The result " +
+        "returns the note's permalink and file_path: cite those exact values " +
+        "when confirming, never a recalled filename. " +
         "If the note already exists, returns an error by default. " +
-        "Pass overwrite=true to replace, or use edit_note for incremental updates.",
+        "Pass overwrite=true to replace, or use edit_note for incremental updates. " +
+        "To replace only the revision you read, also pass expected_checksum " +
+        "(the checksum read_note reports); a newer revision is then left untouched.",
       parameters: Type.Object({
         title: Type.String({ description: "Note title" }),
         content: Type.String({
@@ -27,12 +36,47 @@ export function registerWriteTool(
             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`.",
+          }),
+        ),
         overwrite: Type.Optional(
           Type.Boolean({
             description:
               "Set to true to replace an existing note. Defaults to false.",
           }),
         ),
+        metadata: Type.Optional(
+          Type.Object(
+            {},
+            {
+              additionalProperties: true,
+              description:
+                "Extra frontmatter fields to merge into the note. Nested objects are supported.",
+            },
+          ),
+        ),
+        tags: Type.Optional(
+          Type.Union([Type.Array(Type.String()), Type.String()], {
+            description:
+              "Tags for the note, as an array or comma-separated string.",
+          }),
+        ),
+        note_type: Type.Optional(
+          Type.String({
+            description: 'Note type stored in frontmatter. Defaults to "note".',
+          }),
+        ),
+        expected_checksum: Type.Optional(
+          Type.String({
+            description:
+              "Requires overwrite=true. The checksum of the note as you read it; " +
+              "the note is replaced only while it is still that revision.",
+          }),
+        ),
       }),
       async execute(
         _toolCallId: string,
@@ -41,11 +85,31 @@ export function registerWriteTool(
           content: string
           folder: string
           project?: string
+          project_id?: string
           overwrite?: boolean
+          metadata?: Record<string, unknown>
+          tags?: string[] | string
+          note_type?: string
+          expected_checksum?: string
         },
       ) {
         log.debug(`write_note: title=${params.title} folder=${params.folder}`)
 
+        const options =
+          params.metadata !== undefined ||
+          params.tags !== undefined ||
+          params.note_type !== undefined ||
+          params.project_id !== undefined ||
+          params.expected_checksum !== undefined
+            ? {
+                metadata: params.metadata,
+                tags: params.tags,
+                noteType: params.note_type,
+                projectId: params.project_id,
+                expectedChecksum: params.expected_checksum,
+              }
+            : undefined
+
         try {
           const note = await client.writeNote(
             params.title,
@@ -53,9 +117,13 @@ export function registerWriteTool(
             params.folder,
             params.project,
             params.overwrite,
+            options,
           )
 
-          const msg = `Note saved: ${note.title} (${note.permalink})`
+          const checksumSuffix = note.checksum
+            ? `\nChecksum: ${note.checksum}`
+            : ""
+          const msg = `Note saved: ${note.title} (${note.permalink})${checksumSuffix}`
           return {
             content: [
               {
@@ -67,6 +135,7 @@ export function registerWriteTool(
               title: note.title,
               permalink: note.permalink,
               file_path: note.file_path,
+              checksum: note.checksum ?? null,
             },
           }
         } catch (err) {
@@ -78,7 +147,7 @@ export function registerWriteTool(
               `  - 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`,
+              `  - read_note("${err.permalink}", include_frontmatter=true) to inspect it first; pass its checksum as expected_checksum with overwrite=true to replace only that revision`,
             ].join("\n")
 
             return {
@@ -91,6 +160,27 @@ export function registerWriteTool(
             }
           }
 
+          if (err instanceof NoteRevisionConflictError) {
+            const current = err.currentChecksum
+              ? `Its current checksum is ${err.currentChecksum}.`
+              : "No note exists at that path any more."
+            const text = [
+              `Note revision conflict: "${params.title}" changed since it was read, so nothing was replaced. ${current}`,
+              "",
+              "Read the note again, confirm it should still be replaced, then retry with the new checksum as expected_checksum.",
+            ].join("\n")
+
+            return {
+              content: [{ type: "text" as const, text }],
+              details: {
+                title: params.title,
+                permalink: err.permalink,
+                current_checksum: err.currentChecksum,
+                error: "note_revision_conflict",
+              },
+            }
+          }
+
           log.error("write_note failed", err)
           return {
             content: [

package/skills/memory-ci-capture/SKILL.md

@@ -1,56 +0,0 @@
----
-name: memory-ci-capture
-description: Synthesize GitHub delivery context into a concise Basic Memory project update. Use in CI after `bm ci collect` prepares a ProjectUpdateContext; return only structured AgentSynthesis JSON for `bm ci publish`.
----
-
-# Memory CI Capture
-
-Turn a meaningful GitHub delivery moment into project memory. GitHub records the
-mechanics. Basic Memory remembers what changed and why.
-
-## Inputs
-
-Read the `ProjectUpdateContext` JSON produced by `bm ci collect` at
-`.github/basic-memory/project-update-context.json`. Treat it as the immutable
-source of truth for repository, event type, PR number, workflow run, SHA, source
-URL, timestamps, and deployment environment.
-
-Do not invent tests, deploy checks, linked issues, product impact, or decisions.
-If evidence is absent, say so briefly in `verification` or leave the field empty.
-
-## Output
-
-Return only JSON matching the `AgentSynthesis` shape:
-
-```json
-{
-  "summary": "What changed.",
-  "why_it_matters": "Why this update matters for future humans and agents.",
-  "user_facing_changes": [],
-  "internal_changes": [],
-  "verification": [],
-  "follow_ups": [],
-  "decision_candidates": [],
-  "task_candidates": []
-}
-```
-
-## Synthesis Rules
-
-- Prefer a short explanation over a commit-by-commit changelog.
-- Preserve intent, changed behavior, source links, verification evidence present
-  in the context, and concrete follow-ups.
-- Put explicit product or architecture decisions in `decision_candidates` only
-  when the source context clearly contains them.
-- Put future work in `task_candidates` only when it is concrete enough to act on.
-- Keep the tone factual and useful. This is project memory, not marketing copy.
-
-## Event Guidance
-
-For merged pull requests, focus on why the PR existed, what area changed, what
-issues it advanced or closed, and what verification evidence appears in the
-context.
-
-For production deploys, focus on what reached production, the deployed SHA,
-environment, workflow run, and verification evidence. Do not overclaim success
-beyond the workflow and source facts.