@basicmemory/openclaw-basic-memory 0.1.0-alpha.1

package/skills/memory-tasks/SKILL.md

@@ -0,0 +1,162 @@
+---
+name: memory-tasks
+description: "Task management via Basic Memory schemas: create, track, and resume structured tasks that survive context compaction. Uses BM's schema system for uniform notes queryable through the knowledge graph."
+---
+
+# Memory Tasks
+
+Manage work-in-progress using Basic Memory's schema system. Tasks are just notes with `type: Task` — they live in the knowledge graph, validate against a schema, and survive context compaction.
+
+## When to Use
+
+- **Starting multi-step work** (3+ steps, or anything that might outlast the context window)
+- **After compaction/restart** — search for active tasks to resume
+- **Pre-compaction flush** — update all active tasks with current state
+- **On demand** — user asks to create, check, or manage tasks
+
+## Task Schema
+
+Tasks use the BM schema system (SPEC-SCHEMA). The schema note lives at `memory/schema/Task.md`:
+
+```yaml
+---
+title: Task
+type: schema
+entity: Task
+version: 1
+schema:
+  description: string, what needs to be done
+  status?(enum): [active, blocked, done, abandoned], current state
+  assigned_to?: string, who is working on this
+  steps?(array): string, ordered steps to complete
+  current_step?: integer, which step number we're on (1-indexed)
+  context?: string, key context needed to resume after memory loss
+  started?: string, when work began
+  completed?: string, when work finished
+  blockers?(array): string, what's preventing progress
+  parent_task?: Task, parent task if this is a subtask
+settings:
+  validation: warn
+---
+```
+
+## Creating a Task
+
+When work qualifies, create a note in `memory/tasks/YYYY-MM-DD-short-name.md`:
+
+```markdown
+---
+title: Descriptive task name
+type: Task
+status: active
+created: YYYY-MM-DD
+current_step: 1
+---
+
+# Descriptive task name
+
+## Observations
+- [description] What needs to be done, concisely
+- [status] active
+- [assigned_to] claw
+- [started] YYYY-MM-DD
+- [current_step] 1
+
+## Steps
+1. [ ] First concrete step
+2. [ ] Second concrete step
+3. [ ] Third concrete step
+
+## Context
+What future-you needs to pick up this work. Include:
+- Key file paths and repos involved
+- Decisions already made and why
+- What was tried and what worked/didn't
+- Where to look for related context
+```
+
+### Key Principles
+
+- **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
+- **Use observations for BM-queryable fields** — `[status]`, `[description]`, `[assigned_to]` etc. become searchable in the knowledge graph
+- **Relations link to other entities** — `parent_task [[Other Task]]`, `related_to [[Some Note]]`
+
+## Resuming After Compaction
+
+On session start or after compaction:
+
+1. **Search for active tasks:**
+   - Via BM: `search_notes("type:Task status:active")` or `search_notes("[status] active")`
+   - Via memory_search: query "active tasks" (composited search includes task scanning)
+
+2. **Read the task note** to get full context
+
+3. **Resume from `current_step`** using the `context` field
+
+4. **Update as you progress** — increment `current_step`, update context, check off steps
+
+## Updating Tasks
+
+As work progresses, update the task note:
+
+```markdown
+## Steps
+1. [x] First step — done, resulted in X
+2. [x] Second step — done, changed approach because Y
+3. [ ] Third step — next up
+
+## Context
+Updated context reflecting current state...
+```
+
+Update frontmatter too:
+```yaml
+current_step: 3
+```
+
+## Completing Tasks
+
+When done:
+```yaml
+status: done
+completed: YYYY-MM-DD
+```
+
+Add a brief summary of what was accomplished and any follow-up needed.
+
+## Pre-Compaction Flush
+
+When a compaction event is imminent:
+
+1. Find all active tasks: `search_notes("type:Task status:active")`
+2. For each, update:
+   - `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
+
+## Querying Tasks
+
+With BM's schema system, tasks are fully queryable:
+
+| Query | What it finds |
+|-------|--------------|
+| `search_notes("type:Task")` | All tasks |
+| `search_notes("[status] active")` | Active tasks |
+| `search_notes("[status] blocked")` | Blocked tasks |
+| `search_notes("[assigned_to] claw")` | My tasks |
+| `search_notes("type:Task [blockers]")` | Tasks with blockers |
+| `schema_validate(noteType="Task")` | Validate all tasks against schema |
+| `schema_diff(noteType="Task")` | Detect drift between schema and actual task notes |
+
+> **Plugin tools vs BM CLI**: The `schema_validate`, `schema_infer`, and `schema_diff` tools are available when using the `@openclaw/basic-memory` plugin. The raw `search_notes(...)` queries also work and are useful for ad-hoc filtering. `memory_search` composites results from all sources including active task scanning.
+
+## 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
+- **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 `bm schema validate Task` periodically to catch incomplete tasks

package/tools/build-context.ts

@@ -0,0 +1,123 @@
+import { Type } from "@sinclair/typebox"
+import type { OpenClawPluginApi } from "openclaw/plugin-sdk"
+import type { BmClient } from "../bm-client.ts"
+import { log } from "../logger.ts"
+
+export function registerContextTool(
+  api: OpenClawPluginApi,
+  client: BmClient,
+): void {
+  api.registerTool(
+    {
+      name: "build_context",
+      label: "Build Context",
+      description:
+        "Navigate the Basic Memory knowledge graph via memory:// URLs. " +
+        "Returns the target note plus related notes connected through the graph. " +
+        "Use this to follow relations and discover connected concepts.",
+      parameters: Type.Object({
+        url: Type.String({
+          description:
+            'Memory URL to navigate, e.g. "memory://agents/decisions" or "projects/my-project"',
+        }),
+        depth: Type.Optional(
+          Type.Number({
+            description: "How many relation hops to follow (default: 1)",
+          }),
+        ),
+        project: Type.Optional(
+          Type.String({
+            description: "Target project name (defaults to current project)",
+          }),
+        ),
+      }),
+      async execute(
+        _toolCallId: string,
+        params: { url: string; depth?: number; project?: string },
+      ) {
+        const depth = params.depth ?? 1
+        log.debug(`build_context: url="${params.url}" depth=${depth}`)
+
+        try {
+          const ctx = await client.buildContext(
+            params.url,
+            depth,
+            params.project,
+          )
+
+          if (!ctx.results || ctx.results.length === 0) {
+            return {
+              content: [
+                {
+                  type: "text" as const,
+                  text: `No context found for "${params.url}".`,
+                },
+              ],
+              details: {
+                url: params.url,
+                depth,
+                resultCount: 0,
+              },
+            }
+          }
+
+          const sections: string[] = []
+
+          for (const result of ctx.results) {
+            const primary = result.primary_result
+            sections.push(`## ${primary.title}\n${primary.content}`)
+
+            if (result.observations?.length > 0) {
+              const obs = result.observations
+                .map((o) => `- [${o.category}] ${o.content}`)
+                .join("\n")
+              sections.push(`### Observations\n${obs}`)
+            }
+
+            if (result.related_results?.length > 0) {
+              const rels = result.related_results
+                .map((r) => {
+                  if (r.type === "relation") {
+                    return `- ${r.relation_type} → **${r.to_entity}**`
+                  }
+                  const label = r.relation_type
+                    ? `${r.relation_type} → **${r.title}**`
+                    : `**${r.title}**`
+                  return r.permalink
+                    ? `- ${label} (${r.permalink})`
+                    : `- ${label}`
+                })
+                .join("\n")
+              sections.push(`### Related\n${rels}`)
+            }
+          }
+
+          return {
+            content: [
+              {
+                type: "text" as const,
+                text: sections.join("\n\n"),
+              },
+            ],
+            details: {
+              url: params.url,
+              depth,
+              resultCount: ctx.results.length,
+            },
+          }
+        } catch (err) {
+          log.error("build_context failed", err)
+          return {
+            content: [
+              {
+                type: "text" as const,
+                text: `Failed to build context for "${params.url}". Check logs for details.`,
+              },
+            ],
+          }
+        }
+      },
+    },
+    { name: "build_context" },
+  )
+}

package/tools/delete-note.ts

@@ -0,0 +1,67 @@
+import { Type } from "@sinclair/typebox"
+import type { OpenClawPluginApi } from "openclaw/plugin-sdk"
+import type { BmClient } from "../bm-client.ts"
+import { log } from "../logger.ts"
+
+export function registerDeleteTool(
+  api: OpenClawPluginApi,
+  client: BmClient,
+): void {
+  api.registerTool(
+    {
+      name: "delete_note",
+      label: "Delete Note",
+      description:
+        "Delete a note from the Basic Memory knowledge graph. " +
+        "The note is permanently removed from the filesystem and the search index.",
+      parameters: Type.Object({
+        identifier: Type.String({
+          description: "Note title, permalink, or memory:// URL to delete",
+        }),
+        project: Type.Optional(
+          Type.String({
+            description: "Target project name (defaults to current project)",
+          }),
+        ),
+      }),
+      async execute(
+        _toolCallId: string,
+        params: { identifier: string; project?: string },
+      ) {
+        log.debug(`delete_note: identifier="${params.identifier}"`)
+
+        try {
+          const result = await client.deleteNote(
+            params.identifier,
+            params.project,
+          )
+
+          return {
+            content: [
+              {
+                type: "text" as const,
+                text: `Deleted: ${result.title} (${result.permalink})`,
+              },
+            ],
+            details: {
+              title: result.title,
+              permalink: result.permalink,
+              file_path: result.file_path,
+            },
+          }
+        } catch (err) {
+          log.error("delete_note failed", err)
+          return {
+            content: [
+              {
+                type: "text" as const,
+                text: `Failed to delete "${params.identifier}". It may not exist.`,
+              },
+            ],
+          }
+        }
+      },
+    },
+    { name: "delete_note" },
+  )
+}

package/tools/edit-note.ts

@@ -0,0 +1,118 @@
+import { Type } from "@sinclair/typebox"
+import type { OpenClawPluginApi } from "openclaw/plugin-sdk"
+import type { BmClient } from "../bm-client.ts"
+import { log } from "../logger.ts"
+
+export function registerEditTool(
+  api: OpenClawPluginApi,
+  client: BmClient,
+): void {
+  api.registerTool(
+    {
+      name: "edit_note",
+      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.",
+      parameters: Type.Object({
+        identifier: Type.String({
+          description: "Note title, permalink, or memory:// URL to edit",
+        }),
+        operation: Type.Union(
+          [
+            Type.Literal("append"),
+            Type.Literal("prepend"),
+            Type.Literal("find_replace"),
+            Type.Literal("replace_section"),
+          ],
+          {
+            description:
+              "Edit operation: append (add to end), prepend (add to start), " +
+              "find_replace (replace matching text), replace_section (replace a heading section)",
+          },
+        ),
+        content: Type.String({
+          description: "New content to add or replace with",
+        }),
+        find_text: Type.Optional(
+          Type.String({
+            description: "Text to find (required for find_replace)",
+          }),
+        ),
+        section: Type.Optional(
+          Type.String({
+            description:
+              "Section heading to replace (required for replace_section)",
+          }),
+        ),
+        expected_replacements: Type.Optional(
+          Type.Number({
+            description:
+              "Expected replacement count for find_replace (default: 1)",
+          }),
+        ),
+        project: Type.Optional(
+          Type.String({
+            description: "Target project name (defaults to current project)",
+          }),
+        ),
+      }),
+      async execute(
+        _toolCallId: string,
+        params: {
+          identifier: string
+          operation: "append" | "prepend" | "find_replace" | "replace_section"
+          content: string
+          find_text?: string
+          section?: string
+          expected_replacements?: number
+          project?: string
+        },
+      ) {
+        log.debug(`edit_note: id="${params.identifier}" op=${params.operation}`)
+
+        try {
+          const note = await client.editNote(
+            params.identifier,
+            params.operation,
+            params.content,
+            {
+              find_text: params.find_text,
+              section: params.section,
+              expected_replacements: params.expected_replacements,
+            },
+            params.project,
+          )
+
+          return {
+            content: [
+              {
+                type: "text" as const,
+                text: `Note updated: ${note.title} (${note.permalink})`,
+              },
+            ],
+            details: {
+              title: note.title,
+              permalink: note.permalink,
+              file_path: note.file_path,
+              operation: params.operation,
+              checksum: note.checksum ?? null,
+            },
+          }
+        } catch (err) {
+          log.error("edit_note failed", err)
+          return {
+            content: [
+              {
+                type: "text" as const,
+                text: `Failed to edit note "${params.identifier}". It may not exist.`,
+              },
+            ],
+          }
+        }
+      },
+    },
+    { name: "edit_note" },
+  )
+}

package/tools/list-memory-projects.ts

@@ -0,0 +1,94 @@
+import { Type } from "@sinclair/typebox"
+import type { OpenClawPluginApi } from "openclaw/plugin-sdk"
+import type { BmClient, ProjectListResult } from "../bm-client.ts"
+import { log } from "../logger.ts"
+
+function normalizeProject(project: ProjectListResult) {
+  return {
+    name: project.name,
+    path: project.path,
+    display_name: project.display_name ?? null,
+    is_private: project.is_private === true,
+    is_default: project.is_default === true || project.isDefault === true,
+    workspace_name: project.workspace_name ?? null,
+    workspace_type: project.workspace_type ?? null,
+    workspace_tenant_id: project.workspace_tenant_id ?? null,
+  }
+}
+
+export function registerProjectListTool(
+  api: OpenClawPluginApi,
+  client: BmClient,
+): void {
+  api.registerTool(
+    {
+      name: "list_memory_projects",
+      label: "List Projects",
+      description: "List all Basic Memory projects accessible to this agent",
+      parameters: Type.Object({
+        workspace: Type.Optional(
+          Type.String({
+            description: "Filter by workspace name or tenant_id",
+          }),
+        ),
+      }),
+      async execute(_toolCallId: string, params: { workspace?: string }) {
+        log.debug(`list_memory_projects: workspace="${params.workspace ?? ""}"`)
+
+        try {
+          const projects = await client.listProjects(params.workspace)
+          const normalized = projects.map(normalizeProject)
+
+          if (normalized.length === 0) {
+            return {
+              content: [
+                {
+                  type: "text" as const,
+                  text: "No Basic Memory projects found.",
+                },
+              ],
+              details: {
+                count: 0,
+                projects: [],
+              },
+            }
+          }
+
+          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}`
+            })
+            .join("\n\n")
+
+          return {
+            content: [
+              {
+                type: "text" as const,
+                text: `Found ${normalized.length} project(s):\n\n${text}`,
+              },
+            ],
+            details: {
+              count: normalized.length,
+              projects: normalized,
+            },
+          }
+        } catch (err) {
+          log.error("list_memory_projects failed", err)
+          return {
+            content: [
+              {
+                type: "text" as const,
+                text: "Failed to list Basic Memory projects. Is Basic Memory running? Check logs for details.",
+              },
+            ],
+          }
+        }
+      },
+    },
+    { name: "list_memory_projects" },
+  )
+}

package/tools/list-workspaces.ts

@@ -0,0 +1,75 @@
+import { Type } from "@sinclair/typebox"
+import type { OpenClawPluginApi } from "openclaw/plugin-sdk"
+import type { BmClient, WorkspaceResult } from "../bm-client.ts"
+import { log } from "../logger.ts"
+
+function formatWorkspace(ws: WorkspaceResult, idx: number): string {
+  const subscription = ws.has_active_subscription ? "active" : "none"
+  return (
+    `${idx + 1}. **${ws.name}**\n` +
+    `   Type: ${ws.workspace_type} | Role: ${ws.role} | Subscription: ${subscription}`
+  )
+}
+
+export function registerWorkspaceListTool(
+  api: OpenClawPluginApi,
+  client: BmClient,
+): void {
+  api.registerTool(
+    {
+      name: "list_workspaces",
+      label: "List Workspaces",
+      description:
+        "List all Basic Memory workspaces (personal and organization) accessible to this user",
+      parameters: Type.Object({}),
+      async execute(_toolCallId: string, _params: Record<string, never>) {
+        log.debug("list_workspaces")
+
+        try {
+          const workspaces = await client.listWorkspaces()
+
+          if (workspaces.length === 0) {
+            return {
+              content: [
+                {
+                  type: "text" as const,
+                  text: "No workspaces found.",
+                },
+              ],
+              details: {
+                count: 0,
+                workspaces: [],
+              },
+            }
+          }
+
+          const text = workspaces.map(formatWorkspace).join("\n\n")
+
+          return {
+            content: [
+              {
+                type: "text" as const,
+                text: `Found ${workspaces.length} workspace(s):\n\n${text}`,
+              },
+            ],
+            details: {
+              count: workspaces.length,
+              workspaces,
+            },
+          }
+        } catch (err) {
+          log.error("list_workspaces failed", err)
+          return {
+            content: [
+              {
+                type: "text" as const,
+                text: "Failed to list workspaces. Is Basic Memory running? Check logs for details.",
+              },
+            ],
+          }
+        }
+      },
+    },
+    { name: "list_workspaces" },
+  )
+}