feat: bundle skills in plugin and seed Task schema on startup

- Bundle 4 skills (memory-tasks, memory-reflect, memory-defrag, memory-schema)
  directly in the plugin via openclaw.plugin.json skills array
- Seed Task schema note on first startup (check-before-write, non-fatal)
- Add schema/task-schema.ts with canonical Task Picoschema definition
- Update docs: bundled skills replace manual cp instructions, add npx skills
  as update path for users who want latest upstream skills
- Add readNote/writeNote mocks to index.test.ts for schema seed coverage

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: phernandez

MEMORY_TASK_FLOW.md

@@ -134,24 +134,19 @@ Use `bm_edit` (`find_replace`) to change `status: active` to `status: done`.
 3. Ensure `memoryDir` points to the directory that contains your `tasks/` folder.
 4. If task search looks wrong, verify `bm watch` is running and notes exist in expected paths.
 
-## Companion Skills (Optional)
+## Bundled Skills
 
-The companion repo
-[`basic-memory-skills`](https://github.com/basicmachines-co/basic-memory-skills)
-adds workflow-oriented skills that fit this plugin:
+This plugin ships with workflow-oriented skills that are automatically loaded when the plugin is enabled:
 
-- `memory-tasks`: standardized task creation/resume/update flow
-- `memory-reflect`: periodic memory consolidation from recent notes
-- `memory-defrag`: periodic cleanup/reorganization of memory files
+- **`memory-tasks`** — standardized task creation/resume/update flow
+- **`memory-reflect`** — periodic memory consolidation from recent notes
+- **`memory-defrag`** — periodic cleanup/reorganization of memory files
+- **`memory-schema`** — schema lifecycle management (infer, create, validate, diff, evolve)
 
-Install into your workspace:
+No manual installation needed. To update skills or install new ones as they become available:
 
 ```bash
-git clone https://github.com/basicmachines-co/basic-memory-skills.git
-cp -r basic-memory-skills/memory-tasks ~/.openclaw/workspace/skills/
-cp -r basic-memory-skills/memory-reflect ~/.openclaw/workspace/skills/
-cp -r basic-memory-skills/memory-defrag ~/.openclaw/workspace/skills/
+npx skills add basicmachines-co/basic-memory-skills --agent openclaw
 ```
 
-Use `~/.openclaw/skills/` instead if you want shared skills across agents/workspaces.
-After installing, start a new session so OpenClaw reloads the skill snapshot.
+See the upstream source at [`basic-memory-skills`](https://github.com/basicmachines-co/basic-memory-skills).

README.md

@@ -84,28 +84,30 @@ If you prefer loading directly from a path in config instead of `plugins install
 }
 ```
 
-### Optional: Install Companion Skills
+### Bundled Skills
 
-You can pair this plugin with skills from
-[`basic-memory-skills`](https://github.com/basicmachines-co/basic-memory-skills):
+This plugin ships with four skills that are automatically available when the plugin is enabled — no manual installation needed:
 
-- `memory-tasks` — structured task tracking that survives compaction
-- `memory-reflect` — periodic consolidation of recent notes into durable memory
-- `memory-defrag` — periodic cleanup/reorganization of memory files
+- **`memory-tasks`** — structured task tracking that survives context compaction
+- **`memory-reflect`** — periodic consolidation of recent notes into durable memory
+- **`memory-defrag`** — periodic cleanup/reorganization of memory files
+- **`memory-schema`** — schema lifecycle management (infer, create, validate, diff, evolve)
 
-Install (workspace-local):
+Skills are loaded from the plugin's `skills/` directory. See the upstream source at [`basic-memory-skills`](https://github.com/basicmachines-co/basic-memory-skills).
+
+#### Updating or adding skills with `npx skills`
+
+You can update bundled skills or install new ones as they become available using the [Skills CLI](https://github.com/vercel-labs/skills):
 
 ```bash
-git clone https://github.com/basicmachines-co/basic-memory-skills.git
-cp -r basic-memory-skills/memory-tasks ~/.openclaw/workspace/skills/
-cp -r basic-memory-skills/memory-reflect ~/.openclaw/workspace/skills/
-cp -r basic-memory-skills/memory-defrag ~/.openclaw/workspace/skills/
-```
+# Update all basic-memory skills to latest
+npx skills add basicmachines-co/basic-memory-skills --agent openclaw
 
-If you want these skills available to multiple workspaces/agents on the same machine,
-install to `~/.openclaw/skills/` instead.
+# Install a specific skill
+npx skills add basicmachines-co/basic-memory-skills --name memory-tasks --agent openclaw
+```
 
-After installation, start a new OpenClaw session so the refreshed skill set is loaded.
+This installs to the same `skills/` directory the plugin reads from, so updated skills take effect on the next session.
 
 ## Configuration
 

index.test.ts

@@ -14,6 +14,12 @@ describe("plugin service lifecycle", () => {
     const ensureProjectSpy = jest
       .spyOn(BmClient.prototype, "ensureProject")
       .mockResolvedValue(undefined)
+    const readNoteSpy = jest
+      .spyOn(BmClient.prototype, "readNote")
+      .mockRejectedValue(new Error("Entity not found"))
+    const writeNoteSpy = jest
+      .spyOn(BmClient.prototype, "writeNote")
+      .mockResolvedValue(undefined as any)
     const stopSpy = jest
       .spyOn(BmClient.prototype, "stop")
       .mockResolvedValue(undefined)
@@ -53,6 +59,14 @@ describe("plugin service lifecycle", () => {
     expect(startSpy).toHaveBeenCalledWith({ cwd: "/tmp/workspace" })
     expect(ensureProjectSpy).toHaveBeenCalledWith("/tmp/workspace/memory")
 
+    // Schema seed: readNote throws "not found" → writeNote called
+    expect(readNoteSpy).toHaveBeenCalledWith("schema/Task")
+    expect(writeNoteSpy).toHaveBeenCalledWith(
+      "Task",
+      expect.stringContaining("type: schema"),
+      "schema",
+    )
+
     await services[0].stop()
 
     expect(stopSpy).toHaveBeenCalledTimes(1)

index.ts

@@ -9,6 +9,7 @@ import {
 } from "./config.ts"
 import { buildCaptureHandler } from "./hooks/capture.ts"
 import { initLogger, log } from "./logger.ts"
+import { TASK_SCHEMA_CONTENT } from "./schema/task-schema.ts"
 import { registerContextTool } from "./tools/context.ts"
 import { registerDeleteTool } from "./tools/delete.ts"
 import { registerEditTool } from "./tools/edit.ts"
@@ -83,6 +84,19 @@ export default {
         await client.ensureProject(projectPath)
         log.debug(`project "${cfg.project}" at ${projectPath}`)
 
+        // Seed Task schema if not already present
+        try {
+          await client.readNote("schema/Task")
+          log.debug("Task schema already exists, skipping seed")
+        } catch {
+          try {
+            await client.writeNote("Task", TASK_SCHEMA_CONTENT, "schema")
+            log.debug("seeded Task schema note")
+          } catch (err) {
+            log.debug("Task schema seed failed (non-fatal)", err)
+          }
+        }
+
         setWorkspaceDir(workspace)
 
         log.info("connected — BM MCP stdio session running")

openclaw.plugin.json

@@ -1,6 +1,12 @@
 {
   "id": "basic-memory",
   "kind": "memory",
+  "skills": [
+    "skills/memory-tasks",
+    "skills/memory-reflect",
+    "skills/memory-defrag",
+    "skills/memory-schema"
+  ],
   "uiHints": {
     "project": {
       "label": "Project Name",

package.json

@@ -25,6 +25,8 @@
     "tools/search.ts",
     "tools/write.ts",
     "types/openclaw.d.ts",
+    "schema/task-schema.ts",
+    "skills/",
     "openclaw.plugin.json",
     "README.md",
     "LICENSE"

schema/task-schema.ts

@@ -0,0 +1,34 @@
+/**
+ * Canonical Task schema note content, seeded into new projects on first startup.
+ * If the schema already exists (user may have customized it), seeding is skipped.
+ */
+export const TASK_SCHEMA_CONTENT = `---
+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
+---
+
+# Task
+
+Structured task note for tracking multi-step work that survives context compaction.
+
+## Observations
+- [convention] Task files live in memory/tasks/ with format YYYY-MM-DD-short-name.md
+- [convention] Status transitions: active → blocked → done or abandoned
+- [convention] Include a ## Context section for resumption after memory loss
+- [convention] Include a ## Steps section with numbered checkbox items for step tracking
+`

skills/memory-defrag/SKILL.md

@@ -0,0 +1,87 @@
+---
+name: memory-defrag
+description: "Defragment and reorganize agent memory files: split bloated files, merge duplicates, remove stale information, and restructure the memory hierarchy. Use when memory files have grown unwieldy, contain redundancies, or need reorganization. Run periodically (weekly) or on demand."
+---
+
+# Memory Defrag
+
+Reorganize memory files for clarity, efficiency, and relevance. Like filesystem defragmentation but for knowledge.
+
+## When to Run
+
+- **Periodic**: Weekly or biweekly via cron (recommended)
+- **On demand**: User asks to clean up, reorganize, or defrag memory
+- **Threshold**: When MEMORY.md exceeds ~500 lines or daily notes accumulate without consolidation
+
+## Process
+
+### 1. Audit Current State
+
+Inventory all memory files:
+```
+MEMORY.md           — long-term memory
+memory/             — daily notes, tasks, topical files
+memory/tasks/       — active and completed tasks
+```
+
+For each file, note: line count, last modified, topic coverage, staleness.
+
+### 2. Identify Problems
+
+Look for these common issues:
+
+| Problem | Signal | Fix |
+|---------|--------|-----|
+| **Bloated file** | >300 lines, covers many topics | Split into focused files |
+| **Duplicate info** | Same fact in multiple places | Consolidate to one location |
+| **Stale entries** | References to completed work, old dates, resolved issues | Remove or archive |
+| **Orphan files** | Files in memory/ never referenced or updated | Review, merge, or remove |
+| **Inconsistencies** | Contradictory information across files | Resolve to ground truth |
+| **Poor organization** | Related info scattered across files | Restructure by topic |
+| **Recursive nesting** | `memory/memory/memory/...` directories | Delete nested dirs (indexer bug artifact) |
+
+### 3. Plan Changes
+
+Before making edits, write a brief plan:
+```markdown
+## Defrag Plan
+- [ ] Split MEMORY.md "Key People" section → memory/people.md
+- [ ] Remove completed tasks older than 30 days from memory/tasks/
+- [ ] Merge memory/bm-marketing-ideas.md into memory/competitive/
+- [ ] Update stale project status entries in MEMORY.md
+```
+
+### 4. Execute
+
+Apply changes one at a time:
+- **Split**: Extract sections from large files into focused topical files
+- **Merge**: Combine related small files into coherent documents
+- **Prune**: Remove information that is no longer relevant or accurate
+- **Restructure**: Move files to appropriate directories, rename for clarity
+- **Update**: Fix outdated facts, dates, statuses
+
+### 5. Verify & Log
+
+After changes:
+- Verify no information was lost (compare before/after)
+- Update any cross-references between files
+- Log what was done in today's daily note:
+
+```markdown
+## Memory Defrag (HH:MM)
+- Files reviewed: N
+- Split: [list]
+- Merged: [list]
+- Pruned: [list]
+- Net result: X files, Y total lines (was Z lines)
+```
+
+## Guidelines
+
+- **Back up first.** If git is available, commit before defragging. If not, note the pre-defrag state.
+- **Preserve raw daily notes.** Don't delete or modify `memory/YYYY-MM-DD.md` files — they're the audit trail.
+- **Target 15-25 focused files.** Too few means bloated files; too many means fragmentation. Aim for the sweet spot.
+- **File names should be scannable.** Use descriptive names: `people.md`, `project-status.md`, `competitive-landscape.md` — not `notes-2.md`.
+- **Don't over-organize.** One level of directories is usually enough. `memory/tasks/` and `memory/competitive/` are fine; `memory/work/projects/active/basic-memory/notes/` is not.
+- **Completed tasks**: Tasks with `status: done` older than 14 days can be removed. Their insights should already be in MEMORY.md via reflection.
+- **Ask before destructive changes.** If uncertain whether information is still relevant, keep it with a `(review needed)` tag rather than deleting.

skills/memory-reflect/SKILL.md

@@ -0,0 +1,63 @@
+---
+name: memory-reflect
+description: "Sleep-time memory reflection: review recent conversations and daily notes, extract insights, and consolidate into long-term memory. Use when triggered by cron, heartbeat, or explicit request to reflect on recent activity. Runs as background processing to improve memory quality over time."
+---
+
+# Memory Reflect
+
+Review recent activity and consolidate valuable insights into long-term memory.
+
+Inspired by sleep-time compute — the idea that memory formation happens best *between* active sessions, not during them.
+
+## When to Run
+
+- **Cron/heartbeat**: Schedule as a periodic background task (recommended: 1-2x daily)
+- **On demand**: User asks to reflect, consolidate, or review recent memory
+- **Post-compaction**: After context window compaction events
+
+## Process
+
+### 1. Gather Recent Material
+
+Read the last 2-3 days of daily notes from `memory/YYYY-MM-DD.md`. Also check:
+- Recent conversation transcripts (if accessible)
+- Any files modified in `memory/` in the last 48 hours
+- Active tasks in `memory/tasks/`
+
+### 2. Evaluate What Matters
+
+For each piece of information, ask:
+- Is this a **decision** that affects future work? → Keep
+- Is this a **lesson learned** or mistake to avoid? → Keep
+- Is this a **preference** or working style insight? → Keep
+- Is this a **relationship** detail (who does what, contact info)? → Keep
+- Is this **transient** (weather checked, heartbeat ran, routine task)? → Skip
+- Is this **already captured** in MEMORY.md or another long-term file? → Skip
+
+### 3. Update Long-Term Memory
+
+Write consolidated insights to `MEMORY.md` following its existing structure:
+- Add new sections or update existing ones
+- Use concise, factual language
+- Include dates for temporal context
+- Remove or update outdated entries that the new information supersedes
+
+### 4. Log the Reflection
+
+Append a brief entry to today's daily note:
+```markdown
+## Reflection (HH:MM)
+- Reviewed: [list of files reviewed]
+- Added to MEMORY.md: [brief summary of what was consolidated]
+- Removed/updated: [anything cleaned up]
+```
+
+## Guidelines
+
+- **Be selective.** The goal is distillation, not duplication. MEMORY.md should be curated wisdom, not a copy of daily notes.
+- **Preserve voice.** If the agent has a personality/soul file, reflections should match that voice.
+- **Don't delete daily notes.** They're the raw record. Reflection extracts from them; it doesn't replace them.
+- **Merge, don't append.** If MEMORY.md already has a section about a topic, update it in place rather than adding a duplicate entry.
+- **Flag uncertainty.** If something seems important but you're not sure, add it with a note like "(needs confirmation)" rather than skipping it entirely.
+- **Restructure over time.** If MEMORY.md is a chronological dump, restructure it into topical sections during reflection. Curated knowledge > raw logs.
+- **Check for filesystem issues.** Look for recursive nesting (memory/memory/memory/...), orphaned files, or bloat while gathering material.