@basicmemory/openclaw-basic-memory 0.1.3 → 0.1.5

package/README.md

@@ -152,6 +152,7 @@ All tools accept an optional `project` parameter for cross-project operations.
 
 | Command | Description |
 |---------|-------------|
+| `/bm-setup` | Install or update the Basic Memory CLI |
 | `/remember <text>` | Save a quick note |
 | `/recall <query>` | Search the knowledge graph |
 | `/tasks [args]` | Create, track, resume structured tasks |

package/bm-client.ts

@@ -5,6 +5,15 @@ import { log } from "./logger.ts"
 
 const DEFAULT_RETRY_DELAYS_MS = [500, 1000, 2000]
 
+export class NoteAlreadyExistsError extends Error {
+  readonly permalink: string
+  constructor(title: string, permalink: string) {
+    super(`Note already exists: "${title}" (${permalink})`)
+    this.name = "NoteAlreadyExistsError"
+    this.permalink = permalink
+  }
+}
+
 const REQUIRED_TOOLS = [
   "search_notes",
   "read_note",
@@ -569,6 +578,7 @@ export class BmClient {
     content: string,
     folder: string,
     project?: string,
+    overwrite?: boolean,
   ): Promise<NoteResult> {
     const args: Record<string, unknown> = {
       title,
@@ -577,6 +587,7 @@ export class BmClient {
       output_format: "json",
     }
     if (project) args.project = project
+    if (overwrite !== undefined) args.overwrite = overwrite
 
     const payload = await this.callTool("write_note", args)
 
@@ -584,6 +595,13 @@ export class BmClient {
       throw new Error("invalid write_note response")
     }
 
+    if (payload.error === "NOTE_ALREADY_EXISTS") {
+      throw new NoteAlreadyExistsError(
+        asString(payload.title) ?? title,
+        asString(payload.permalink) ?? "",
+      )
+    }
+
     const resultTitle = asString(payload.title)
     const permalink = asString(payload.permalink)
     const filePath = asString(payload.file_path)
@@ -850,7 +868,7 @@ export class BmClient {
     ].join("\n")
 
     try {
-      await this.writeNote(title, content, "conversations")
+      await this.writeNote(title, content, "conversations", undefined, true)
       log.debug(`created conversation note: ${title}`)
     } catch (err) {
       log.error("conversation index failed", err)

package/commands/skills.ts

@@ -5,39 +5,39 @@ import type { OpenClawPluginApi } from "openclaw/plugin-sdk"
 
 const __dirname = dirname(fileURLToPath(import.meta.url))
 const SKILLS_DIR = resolve(__dirname, "..", "skills")
+const MANIFEST_PATH = resolve(SKILLS_DIR, "manifest.json")
+
+interface ManifestEntry {
+  dir: string
+  name: string
+  description: string
+}
+
+function loadManifest(): ManifestEntry[] {
+  try {
+    const raw = readFileSync(MANIFEST_PATH, "utf-8")
+    return JSON.parse(raw) as ManifestEntry[]
+  } catch {
+    throw new Error(
+      "skills/manifest.json not found. Run `bun scripts/fetch-skills.ts` first.",
+    )
+  }
+}
 
 function loadSkill(dir: string): string {
   return readFileSync(resolve(SKILLS_DIR, dir, "SKILL.md"), "utf-8")
 }
 
-const SKILLS = [
-  { name: "tasks", dir: "memory-tasks", desc: "Task management workflow" },
-  {
-    name: "reflect",
-    dir: "memory-reflect",
-    desc: "Memory reflection workflow",
-  },
-  { name: "defrag", dir: "memory-defrag", desc: "Memory defrag workflow" },
-  { name: "schema", dir: "memory-schema", desc: "Schema management workflow" },
-  {
-    name: "notes",
-    dir: "memory-notes",
-    desc: "How to write well-structured notes",
-  },
-  {
-    name: "metadata-search",
-    dir: "memory-metadata-search",
-    desc: "Structured metadata search workflow",
-  },
-] as const
-
 export function registerSkillCommands(api: OpenClawPluginApi): void {
-  for (const skill of SKILLS) {
-    const content = loadSkill(skill.dir)
+  const manifest = loadManifest()
+
+  for (const entry of manifest) {
+    const commandName = entry.dir.replace(/^memory-/, "")
+    const content = loadSkill(entry.dir)
 
     api.registerCommand({
-      name: skill.name,
-      description: skill.desc,
+      name: commandName,
+      description: entry.description,
       acceptsArgs: true,
       requireAuth: true,
       handler: async (ctx: { args?: string }) => {

package/commands/slash.ts

@@ -1,11 +1,43 @@
+import { execSync } from "node:child_process"
+import { dirname, resolve } from "node:path"
+import { fileURLToPath } from "node:url"
 import type { OpenClawPluginApi } from "openclaw/plugin-sdk"
 import type { BmClient } from "../bm-client.ts"
 import { log } from "../logger.ts"
 
+const __dirname = dirname(fileURLToPath(import.meta.url))
+
 export function registerCommands(
   api: OpenClawPluginApi,
   client: BmClient,
 ): void {
+  api.registerCommand({
+    name: "bm-setup",
+    description: "Install or update the Basic Memory CLI (requires uv)",
+    requireAuth: true,
+    handler: async () => {
+      const scriptPath = resolve(__dirname, "..", "scripts", "setup-bm.sh")
+      log.info(`/bm-setup: running ${scriptPath}`)
+
+      try {
+        const output = execSync(`bash "${scriptPath}"`, {
+          encoding: "utf-8",
+          timeout: 180_000,
+          stdio: "pipe",
+          env: { ...process.env },
+        })
+        return { text: output.trim() }
+      } catch (err: unknown) {
+        const execErr = err as { stderr?: string; stdout?: string }
+        const detail = execErr.stderr || execErr.stdout || String(err)
+        log.error("/bm-setup failed", err)
+        return {
+          text: `Setup failed:\n${detail.trim()}`,
+        }
+      }
+    },
+  })
+
   api.registerCommand({
     name: "remember",
     description: "Save something to the Basic Memory knowledge graph",

package/openclaw.plugin.json

@@ -2,12 +2,15 @@
   "id": "openclaw-basic-memory",
   "kind": "memory",
   "skills": [
-    "skills/memory-tasks",
-    "skills/memory-reflect",
     "skills/memory-defrag",
-    "skills/memory-schema",
+    "skills/memory-ingest",
+    "skills/memory-lifecycle",
     "skills/memory-metadata-search",
-    "skills/memory-notes"
+    "skills/memory-notes",
+    "skills/memory-reflect",
+    "skills/memory-research",
+    "skills/memory-schema",
+    "skills/memory-tasks"
   ],
   "uiHints": {
     "project": {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@basicmemory/openclaw-basic-memory",
-  "version": "0.1.3",
+  "version": "0.1.5",
   "type": "module",
   "description": "Basic Memory plugin for OpenClaw — local-first knowledge graph for agent memory",
   "license": "MIT",
@@ -35,6 +35,7 @@
     "schema/task-schema.ts",
     "schema/conversation-schema.ts",
     "skills/",
+    "scripts/fetch-skills.ts",
     "scripts/setup-bm.sh",
     "openclaw.plugin.json",
     "README.md",
@@ -55,6 +56,8 @@
     "check-types": "tsc --noEmit",
     "lint": "bunx @biomejs/biome ci .",
     "lint:fix": "bunx @biomejs/biome check --write .",
+    "fetch-skills": "bun scripts/fetch-skills.ts",
+    "prepack": "bun scripts/fetch-skills.ts",
     "test": "bun test",
     "test:int": "BM_INTEGRATION=1 BM_BIN=${BM_BIN:-./scripts/bm-local.sh} bun test integration --timeout 120000",
     "test:coverage": "bun test --coverage",

package/scripts/fetch-skills.ts

@@ -0,0 +1,133 @@
+/**
+ * Fetch all memory-* skills from basicmachines-co/basic-memory-skills.
+ *
+ * Auto-discovers skill directories via GitHub Contents API, downloads each
+ * SKILL.md, writes to skills/<dir>/SKILL.md, and generates skills/manifest.json.
+ *
+ * Env vars:
+ *   GITHUB_TOKEN   — optional, avoids 60 req/hr unauthenticated rate limit
+ *   SKILLS_BRANCH  — branch to fetch from (default: "main")
+ */
+
+import { mkdirSync, writeFileSync } from "node:fs"
+import { dirname, resolve } from "node:path"
+import { fileURLToPath } from "node:url"
+
+const __dirname = dirname(fileURLToPath(import.meta.url))
+const SKILLS_DIR = resolve(__dirname, "..", "skills")
+
+const REPO = "basicmachines-co/basic-memory-skills"
+const BRANCH = process.env.SKILLS_BRANCH ?? "main"
+const TOKEN = process.env.GITHUB_TOKEN
+
+interface GitHubEntry {
+  name: string
+  type: "file" | "dir"
+}
+
+interface SkillManifestEntry {
+  dir: string
+  name: string
+  description: string
+}
+
+function headers(): Record<string, string> {
+  const h: Record<string, string> = {
+    Accept: "application/vnd.github.v3+json",
+    "User-Agent": "openclaw-basic-memory/fetch-skills",
+  }
+  if (TOKEN) h.Authorization = `Bearer ${TOKEN}`
+  return h
+}
+
+async function fetchJSON<T>(url: string): Promise<T> {
+  const res = await fetch(url, { headers: headers() })
+  if (!res.ok) {
+    throw new Error(`GET ${url} → ${res.status} ${res.statusText}`)
+  }
+  return res.json() as Promise<T>
+}
+
+async function fetchText(url: string): Promise<string> {
+  const res = await fetch(url, { headers: headers() })
+  if (!res.ok) {
+    throw new Error(`GET ${url} → ${res.status} ${res.statusText}`)
+  }
+  return res.text()
+}
+
+function parseFrontmatter(md: string): { name: string; description: string } {
+  const match = md.match(/^---\r?\n([\s\S]*?)\r?\n---/)
+  if (!match) throw new Error("SKILL.md missing YAML frontmatter")
+
+  const yaml = match[1]
+  const name = yaml
+    .match(/^name:\s*(.+)$/m)?.[1]
+    ?.trim()
+    .replace(/^["']|["']$/g, "")
+  const description = yaml
+    .match(/^description:\s*(.+)$/m)?.[1]
+    ?.trim()
+    .replace(/^["']|["']$/g, "")
+
+  if (!name) throw new Error("Frontmatter missing 'name'")
+  if (!description) throw new Error("Frontmatter missing 'description'")
+
+  return { name, description }
+}
+
+async function main() {
+  console.log(`Fetching skills from ${REPO}@${BRANCH}`)
+
+  // 1. Discover all memory-* directories
+  const contentsUrl = `https://api.github.com/repos/${REPO}/contents?ref=${BRANCH}`
+  const entries = await fetchJSON<GitHubEntry[]>(contentsUrl)
+  const skillDirs = entries
+    .filter((e) => e.type === "dir" && e.name.startsWith("memory-"))
+    .map((e) => e.name)
+    .sort()
+
+  if (skillDirs.length === 0) {
+    throw new Error("No memory-* directories found in repo")
+  }
+
+  console.log(`Found ${skillDirs.length} skills: ${skillDirs.join(", ")}`)
+
+  // 2. Download each SKILL.md and parse frontmatter
+  const manifest: SkillManifestEntry[] = []
+
+  const results = await Promise.all(
+    skillDirs.map(async (dir) => {
+      const rawUrl = `https://raw.githubusercontent.com/${REPO}/${BRANCH}/${dir}/SKILL.md`
+      const content = await fetchText(rawUrl)
+      const meta = parseFrontmatter(content)
+      return { dir, content, meta }
+    }),
+  )
+
+  // 3. Write files and build manifest
+  for (const { dir, content, meta } of results) {
+    const outDir = resolve(SKILLS_DIR, dir)
+    mkdirSync(outDir, { recursive: true })
+    writeFileSync(resolve(outDir, "SKILL.md"), content)
+    manifest.push({ dir, name: meta.name, description: meta.description })
+    console.log(`  ✓ ${dir}`)
+  }
+
+  // Sort manifest by dir name for deterministic output
+  manifest.sort((a, b) => a.dir.localeCompare(b.dir))
+
+  // 4. Write manifest
+  mkdirSync(SKILLS_DIR, { recursive: true })
+  writeFileSync(
+    resolve(SKILLS_DIR, "manifest.json"),
+    `${JSON.stringify(manifest, null, 2)}\n`,
+  )
+
+  console.log(`\nWrote ${manifest.length} skills + manifest.json to skills/`)
+}
+
+main().catch((err) => {
+  console.error("Fatal:", err.message)
+  process.exit(1)
+})

package/skills/manifest.json

@@ -0,0 +1,47 @@
+[
+  {
+    "dir": "memory-defrag",
+    "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."
+  },
+  {
+    "dir": "memory-ingest",
+    "name": "memory-ingest",
+    "description": "Process unstructured external input (meeting transcripts, conversation logs, pasted documents) into structured Basic Memory entities. Extracts entities, searches for existing matches, proposes new entities with approval, creates notes with observations and relations, and captures action items."
+  },
+  {
+    "dir": "memory-lifecycle",
+    "name": "memory-lifecycle",
+    "description": "Manage entity status transitions in Basic Memory: archive completed work, move notes between status folders, update frontmatter, and handle edge cases. Use when marking items complete, archiving old entities, or managing any folder-based status workflow."
+  },
+  {
+    "dir": "memory-metadata-search",
+    "name": "memory-metadata-search",
+    "description": "Structured metadata search for Basic Memory: query notes by custom frontmatter fields using equality, range, array, and nested filters. Use when finding notes by status, priority, confidence, or any custom YAML field rather than free-text content."
+  },
+  {
+    "dir": "memory-notes",
+    "name": "memory-notes",
+    "description": "How to write well-structured Basic Memory notes: frontmatter, observations with semantic categories, relations with wiki-links, and best practices for building a rich knowledge graph. Use when creating or improving notes."
+  },
+  {
+    "dir": "memory-reflect",
+    "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."
+  },
+  {
+    "dir": "memory-research",
+    "name": "memory-research",
+    "description": "Research an external subject using web search, synthesize findings into a structured Basic Memory entity. Use when asked to research a company, person, technology, or topic — or when a bare name or URL is provided that implies a research request."
+  },
+  {
+    "dir": "memory-schema",
+    "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."
+  },
+  {
+    "dir": "memory-tasks",
+    "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."
+  }
+]

package/skills/memory-defrag/SKILL.md

@@ -78,7 +78,6 @@ After changes:
 
 ## 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`.