@basicmemory/openclaw-basic-memory 0.2.4 → 0.23.1

package/scripts/fetch-skills.ts

@@ -1,29 +1,26 @@
 /**
- * Fetch all memory-* skills from basicmachines-co/basic-memory-skills.
+ * Copy all memory-* skills from the top-level basic-memory skills source.
  *
- * 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")
+ * Auto-discovers skill directories in ../../../skills, copies each skill's
+ * SKILL.md plus any bundled resources (references/, evals/, assets/, ...)
+ * into this package's skills/<dir>/, and generates skills/manifest.json.
  */
 
-import { mkdirSync, writeFileSync } from "node:fs"
+import {
+  cpSync,
+  existsSync,
+  mkdirSync,
+  readdirSync,
+  readFileSync,
+  rmSync,
+  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"
-}
+const SOURCE_SKILLS_DIR = resolve(__dirname, "..", "..", "..", "skills")
 
 interface SkillManifestEntry {
   dir: string
@@ -31,31 +28,6 @@ interface SkillManifestEntry {
   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")
@@ -76,58 +48,81 @@ function parseFrontmatter(md: string): { name: string; description: string } {
   return { name, description }
 }
 
-async function main() {
-  console.log(`Fetching skills from ${REPO}@${BRANCH}`)
+function discoverSkillDirs(): string[] {
+  if (!existsSync(SOURCE_SKILLS_DIR)) {
+    throw new Error(`Missing source skills directory: ${SOURCE_SKILLS_DIR}`)
+  }
 
-  // 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-"))
+  const skillDirs = readdirSync(SOURCE_SKILLS_DIR, { withFileTypes: true })
+    .filter((e) => e.isDirectory() && e.name.startsWith("memory-"))
     .map((e) => e.name)
     .sort()
 
   if (skillDirs.length === 0) {
-    throw new Error("No memory-* directories found in repo")
+    throw new Error(`No memory-* directories found in ${SOURCE_SKILLS_DIR}`)
   }
 
+  return skillDirs
+}
+
+function main() {
+  console.log(`Copying skills from ${SOURCE_SKILLS_DIR}`)
+
+  const skillDirs = discoverSkillDirs()
   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 }
-    }),
-  )
+  for (const dir of skillDirs) {
+    const skillPath = resolve(SOURCE_SKILLS_DIR, dir, "SKILL.md")
+    if (!existsSync(skillPath)) {
+      throw new Error(`Missing SKILL.md for ${dir}: ${skillPath}`)
+    }
+
+    const content = readFileSync(skillPath, "utf8")
+    const meta = parseFrontmatter(content)
 
-  // 3. Write files and build manifest
-  for (const { dir, content, meta } of results) {
     const outDir = resolve(SKILLS_DIR, dir)
+    // Clear any previously generated copy so files deleted or renamed in
+    // the source skill don't survive as stale artifacts in the package.
+    rmSync(outDir, { recursive: true, force: true })
     mkdirSync(outDir, { recursive: true })
     writeFileSync(resolve(outDir, "SKILL.md"), content)
+
+    // Copy bundled resources (references/, evals/, assets/, ...) so
+    // multi-file skills stay self-contained in the generated package.
+    for (const entry of readdirSync(resolve(SOURCE_SKILLS_DIR, dir), {
+      withFileTypes: true,
+    })) {
+      if (entry.name === "SKILL.md") continue
+      cpSync(
+        resolve(SOURCE_SKILLS_DIR, dir, entry.name),
+        resolve(outDir, entry.name),
+        { recursive: true },
+      )
+    }
+
     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/`)
+  console.log(
+    `\nWrote ${manifest.length} skills + manifest.json to ${SKILLS_DIR}`,
+  )
 }
 
-main().catch((err) => {
-  console.error("Fatal:", err.message)
+try {
+  main()
+} catch (err) {
+  const message = err instanceof Error ? err.message : String(err)
+  console.error("Fatal:", message)
   process.exit(1)
-})
+}

package/scripts/setup-bm.sh

@@ -1,10 +1,10 @@
 #!/usr/bin/env bash
-# Install basic-memory CLI via uv from a pinned release tag.
+# Install the latest released basic-memory CLI via uv.
 # Idempotent — safe to re-run. Fails gracefully when uv is absent.
 set -euo pipefail
 
 BM_REPO="https://github.com/basicmachines-co/basic-memory.git"
-BM_REF="${BM_REF:-v0.20.2}"
+BM_REF="${BM_REF:-}"
 
 # ── check for uv ──────────────────────────────────────────────────
 if ! command -v uv >/dev/null 2>&1; then
@@ -16,16 +16,33 @@ if ! command -v uv >/dev/null 2>&1; then
 fi
 
 # ── install basic-memory ────────────────────────────────
-echo "Installing basic-memory from ${BM_REPO}@${BM_REF} ..."
-uv tool install \
-  "basic-memory @ git+${BM_REPO}@${BM_REF}" \
-  --force
+if [[ -n "${BM_REF}" ]]; then
+  echo "Installing basic-memory from ${BM_REPO}@${BM_REF} ..."
+  uv tool install \
+    "basic-memory @ git+${BM_REPO}@${BM_REF}" \
+    --force
+else
+  echo "Installing latest basic-memory from PyPI ..."
+  uv tool install basic-memory --force
+fi
 
 # ── verify ────────────────────────────────────────────────────────
-if ! command -v bm >/dev/null 2>&1; then
-  echo "❌  bm binary not found on PATH after install."
-  echo "   You may need to add uv's bin directory to your PATH."
+UV_BIN_DIR="$(uv tool dir --bin)"
+BM_BIN="${UV_BIN_DIR}/bm"
+if [[ ! -x "${BM_BIN}" ]]; then
+  BM_BIN="${UV_BIN_DIR}/basic-memory"
+fi
+
+if [[ ! -x "${BM_BIN}" ]]; then
+  echo "❌  basic-memory binary not found in uv's tool bin after install."
+  echo "   You may need to add uv's bin directory to your PATH: ${UV_BIN_DIR}"
   exit 1
 fi
 
-echo "✅  $(bm --version)"
+PATH_BM="$(command -v bm || true)"
+if [[ -n "${PATH_BM}" && "${PATH_BM}" != "${UV_BIN_DIR}/bm" ]]; then
+  echo "⚠  bm on PATH resolves to ${PATH_BM}"
+  echo "   uv installed basic-memory at ${BM_BIN}; move ${UV_BIN_DIR} earlier in PATH or set bmPath."
+fi
+
+echo "✅  $("${BM_BIN}" --version)"

package/skills/manifest.json

@@ -1,4 +1,24 @@
 [
+  {
+    "dir": "memory-capture",
+    "name": "memory-capture",
+    "description": "Capture the current state of a working thread or conversation into a single coherent Basic Memory note — synthesize where it landed, don't append a log. On re-capture, rewrite the same note in place instead of duplicating. Use mid-thread or end-of-thread when decisions, insights, or context are worth preserving."
+  },
+  {
+    "dir": "memory-ci-capture",
+    "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`."
+  },
+  {
+    "dir": "memory-continue",
+    "name": "memory-continue",
+    "description": "Resume prior work by rebuilding context from the Basic Memory knowledge graph — pick up where you left off using memory:// URLs, recent activity, and search. Use when starting a session or when the user says 'continue with...', 'back to...', or 'where were we?'"
+  },
+  {
+    "dir": "memory-curate",
+    "name": "memory-curate",
+    "description": "Curate the Basic Memory knowledge graph: find orphan notes and suggest links, propose typed relations, merge duplicates, audit tags and folders, and build hub notes. Use to organize, connect, and improve a knowledge base as notes accumulate."
+  },
   {
     "dir": "memory-defrag",
     "name": "memory-defrag",
@@ -29,6 +49,11 @@
     "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-onboarding",
+    "name": "memory-onboarding",
+    "description": "Guide someone new to Basic Memory through designing and building a complete personal knowledge system — interview them about what they want to track, propose a structure, build it with schemas and instruction notes, teach them to use it, and set up their AI assistant to load it automatically. Use this skill whenever a user says they're new to Basic Memory, wants to 'get started', 'set up', or 'onboard' with Basic Memory, doesn't know what to use it for, asks how to organize their memory project or knowledge base, wants help designing folders/schemas/conventions, or asks how to make their assistant remember context between sessions. Also use it when a user has an empty or messy Basic Memory project and wants structure."
+  },
   {
     "dir": "memory-reflect",
     "name": "memory-reflect",

package/skills/memory-capture/SKILL.md

@@ -0,0 +1,275 @@
+---
+name: memory-capture
+description: "Capture the current state of a working thread or conversation into a single coherent Basic Memory note — synthesize where it landed, don't append a log. On re-capture, rewrite the same note in place instead of duplicating. Use mid-thread or end-of-thread when decisions, insights, or context are worth preserving."
+---
+
+# Memory Capture
+
+Capture the gist of a working thread — the decisions made, insights surfaced, and context built — into a single coherent Basic Memory note that reflects where the thread has landed.
+
+## Purpose
+
+A thread has a beginning, middle, and end. Things change as the conversation progresses: an early decision gets revised, a problem looks different in light of new information, a trade-off is settled differently than it first seemed. When this skill is invoked, capture the **current state of understanding**, not the history of how it got there.
+
+If the skill is invoked more than once in the same thread, the **same note is rewritten** so it stays coherent — not appended to. The result should read top-to-bottom as a single document about the thread's outcome, with brief prose where a meaningful change is worth acknowledging.
+
+## When to Use
+
+Typical timing is **mid-thread or end-of-thread**, after enough has been settled to be worth preserving.
+
+Use this skill when:
+- Key decisions have been made and shouldn't evaporate when the thread closes
+- A design, debugging, or planning discussion has produced something concrete
+- The user explicitly asks to capture, save, or remember what's been discussed
+- Toward the end of a session, to summarize the outcome
+
+It is fine — and expected — to invoke this skill multiple times in the same thread as the conversation evolves.
+
+## Same-Thread Detection
+
+To rewrite the same note on re-capture instead of duplicating, key the note to a stable `thread_id` in its frontmatter.
+
+**If your agent exposes a stable session or thread id**, store it as `thread_id` so subsequent captures within the same thread find and rewrite the same note. Any value that stays constant for the duration of the thread works — a session UUID, a conversation id, a ticket number the work is scoped to.
+
+> **Example (hosts with a JSONL transcript):** some agents write a per-session transcript whose filename is a stable session UUID. If yours does, you can derive the id from the most-recently-modified transcript file and use it as `thread_id`. This is optional — only do it if your host actually exposes such a transcript.
+
+**If no stable id is available**, match the existing note by title/topic instead: search for a note covering the same thread (`search_notes(query="<topic>")`), and if you find the one this thread already produced, rewrite it. Omit `thread_id` and rely on a consistent title.
+
+## Decision Flow
+
+1. **Determine the thread key.** Use a stable session/thread id if your agent exposes one; otherwise plan to match by title/topic.
+2. **Search Basic Memory** for the existing thread note.
+   - With a thread id, use `metadata_filters` (not `query`) — full-text query doesn't reliably match YAML frontmatter custom fields:
+     ```python
+     search_notes(
+         metadata_filters={"thread_id": "<thread-id>"},
+         project="<project>"
+     )
+     ```
+   - Without one, search by topic and identify the note this thread already produced:
+     ```python
+     search_notes(query="<thread topic>", project="<project>")
+     ```
+3. **If a match is found:**
+   - Read the existing note (use the full permalink returned by search)
+   - Synthesize a new version that integrates the latest understanding from the conversation
+   - Overwrite via `write_note` with `overwrite=True` (same title, same `thread_id` if used, same directory)
+4. **If no match is found:**
+   - Synthesize the note from the conversation
+   - If you have a thread id, pass `metadata={"thread_id": "<thread-id>"}` to `write_note` (it surfaces as a custom frontmatter field)
+   - Save it
+
+## Synthesis Rules
+
+When updating an existing thread note, **synthesize, don't append**:
+
+- Decisions that are still current → keep, possibly refined
+- Decisions that have been superseded → replaced inline (the new one goes where the old one was)
+- Significant revisions that deserve explanation → a sentence woven into the relevant section, *not* an appended changelog
+- Outdated context → removed
+
+Goal: the note reads top-to-bottom as a single coherent document. A reader who never saw the conversation should still understand the outcome from the note alone. There is no `## Changes` section at the bottom; revisions live in the prose where they're relevant.
+
+## Escape Hatch
+
+If the user explicitly asks for a separate note (e.g., "capture this as a new note, don't merge with the existing thread note"), skip the same-thread lookup and create a fresh note without setting `thread_id`. This is rare; the default is to update.
+
+## Note Structure
+
+```markdown
+---
+title: <descriptive title for the thread>
+type: note
+thread_id: <thread-id, if your agent exposes one>
+tags:
+- relevant
+- tags
+---
+
+# <Title>
+
+## Context
+
+What this thread is about — the situation, problem, or topic being explored.
+
+## <One or more topical sections>
+
+The actual content. Could be decisions, a design rationale, an investigation summary, etc.
+
+## Observations
+
+- [decision] What was decided #tag
+- [insight] Key understanding gained #tag
+- [tradeoff] Option A chosen over B because... #tag
+
+## Relations
+
+- relates_to [[Related Concept]]
+- implements [[Parent Spec]]
+```
+
+## Common Observation Categories
+
+- `[decision]` — choices made
+- `[insight]` — understanding gained
+- `[pattern]` — reusable approaches
+- `[learning]` — lessons learned
+- `[tradeoff]` — options weighed
+- `[problem]` — issues identified
+- `[solution]` — fixes applied
+
+## Title
+
+The title should reflect the thread's topic. On update, the title can be refined if the topic has clarified — but it should still describe the same thread. Don't drift to a wholly new topic; if that's needed, use the escape hatch and create a new note.
+
+## MCP Tools Used
+
+```python
+# Find existing thread note by thread id (use metadata_filters, not query)
+search_notes(
+    metadata_filters={"thread_id": "<thread-id>"},
+    project="<project>"
+)
+
+# Or, without a thread id, find it by topic
+search_notes(query="<thread topic>", project="<project>")
+
+# Read existing thread note (use the full permalink from search results)
+read_note(
+    identifier="<full-permalink>",
+    project="<project>"
+)
+
+# Create
+write_note(
+    title="<title>",
+    content="<markdown body — frontmatter is generated from title/tags/metadata>",
+    directory="<folder>",
+    tags=["..."],
+    metadata={"thread_id": "<thread-id>"},  # omit if no stable id
+    project="<project>"
+)
+
+# Overwrite an existing note (same path)
+write_note(
+    title="<same title>",
+    content="<new content>",
+    directory="<same folder>",
+    tags=["..."],
+    metadata={"thread_id": "<same thread-id>"},  # omit if no stable id
+    overwrite=True,
+    project="<project>"
+)
+```
+
+## Examples
+
+### Example 1 — First capture during a brand design conversation
+
+**Preceding conversation:** The user has been working through visual identity decisions for a new product. They settled on a deep navy primary (`#2B3651`), explored accent options and chose orange (`#F26B3A`) for warmth, and picked Inter as the body font with Helvetica Neue as the display font.
+
+**User asks to capture.**
+
+**Result — note created:**
+
+```markdown
+---
+title: Visual identity — initial decisions
+type: note
+thread_id: 7c1d4a2e-3b5f-4d8a-9e1c-2f6b8a4d7c39
+tags:
+- branding
+- design
+---
+
+# Visual identity — initial decisions
+
+## Context
+
+Working through the visual identity for the new product. This thread covers the initial palette and typography pass — a starting point that will likely be refined.
+
+## Color palette
+
+- Primary: deep navy `#2B3651` — calm and professional
+- Accent: warm orange `#F26B3A` — energy and warmth as a complement to the navy
+
+## Typography
+
+- Body: Inter — neutral, readable at small sizes
+- Display: Helvetica Neue — strong presence for headings without being heavy
+
+## Observations
+
+- [decision] Primary color is navy `#2B3651` #branding
+- [decision] Accent color is orange `#F26B3A` #branding
+- [decision] Inter for body, Helvetica Neue for display #typography
+- [tradeoff] Considered teal as accent; orange tested better for warmth #branding
+
+## Relations
+
+- relates_to [[Brand Strategy]]
+```
+
+### Example 2 — Update capture later in the same thread
+
+**Preceding conversation (continued):** After the initial decisions above, the conversation continued. The orange accent felt too aggressive in mock-ups, so we tested a coral (`#E89B7A`) which read warmer and more refined. The body font also shifted: Geist felt slightly tighter and more modern than Inter. Helvetica Neue for display stayed.
+
+**User asks to capture again — same thread.**
+
+**Result — same note rewritten (note the same `thread_id`):**
+
+```markdown
+---
+title: Visual identity — initial decisions
+type: note
+thread_id: 7c1d4a2e-3b5f-4d8a-9e1c-2f6b8a4d7c39
+tags:
+- branding
+- design
+---
+
+# Visual identity — initial decisions
+
+## Context
+
+Working through the visual identity for the new product. This thread settled on a navy + coral palette and a Geist/Helvetica typography pairing after a round of refinement.
+
+## Color palette
+
+- Primary: deep navy `#2B3651` — calm and professional
+- Accent: coral `#E89B7A` — warm and refined
+
+The accent went through a round of revision: an initial orange (`#F26B3A`) felt too aggressive in mock-ups, so we shifted to a coral that reads warmer and more refined while keeping the energy.
+
+## Typography
+
+- Body: Geist — slightly tighter and more modern than Inter, which we tried first
+- Display: Helvetica Neue — strong presence for headings without being heavy
+
+## Observations
+
+- [decision] Primary color is navy `#2B3651` #branding
+- [decision] Accent color is coral `#E89B7A` — warmer and more refined than the originally-chosen orange #branding
+- [decision] Geist for body, Helvetica Neue for display #typography
+- [tradeoff] Inter felt neutral but Geist edged it for spacing and modernity #typography
+- [tradeoff] Orange accent rejected as too aggressive; coral preferred #branding
+
+## Relations
+
+- relates_to [[Brand Strategy]]
+```
+
+Notice that:
+- The orange and Inter decisions are **no longer the primary content** — they're acknowledged in prose ("which we tried first," "originally-chosen orange") and in tradeoff observations
+- There is **no "Changes" section** at the bottom — revisions are integrated where they belong
+- The note still reads top-to-bottom as a single coherent document
+- The `thread_id` is unchanged, so the note was updated in place rather than duplicated
+
+## Best Practices
+
+1. **Capture the current state, not the history.** The note represents where the thread has landed.
+2. **Synthesize, don't log.** Each invocation produces a coherent document, not an accumulating record.
+3. **Brief prose for revisions.** A sentence in the section that changed is enough — don't add a changelog.
+4. **Always run the same-thread lookup** before deciding to create or update.
+5. **Use observations for the structured layer.** Decisions, insights, tradeoffs go in `## Observations` so they're searchable.
+6. **Link relations liberally.** Notes the user might want to reach from this one.

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

@@ -0,0 +1,56 @@
+---
+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.