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

package/index.ts

@@ -0,0 +1,120 @@
+import type { OpenClawPluginApi } from "openclaw/plugin-sdk"
+import { BmClient } from "./bm-client.ts"
+import { registerCli } from "./commands/cli.ts"
+import { registerSkillCommands } from "./commands/skills.ts"
+import { registerCommands } from "./commands/slash.ts"
+import {
+  basicMemoryConfigSchema,
+  parseConfig,
+  resolveProjectPath,
+} from "./config.ts"
+import { buildCaptureHandler } from "./hooks/capture.ts"
+import { buildRecallHandler } from "./hooks/recall.ts"
+import { initLogger, log } from "./logger.ts"
+import { TASK_SCHEMA_CONTENT } from "./schema/task-schema.ts"
+import { registerContextTool } from "./tools/build-context.ts"
+import { registerDeleteTool } from "./tools/delete-note.ts"
+import { registerEditTool } from "./tools/edit-note.ts"
+import { registerProjectListTool } from "./tools/list-memory-projects.ts"
+import { registerWorkspaceListTool } from "./tools/list-workspaces.ts"
+import {
+  registerMemoryProvider,
+  setWorkspaceDir,
+} from "./tools/memory-provider.ts"
+import { registerMoveTool } from "./tools/move-note.ts"
+import { registerReadTool } from "./tools/read-note.ts"
+import { registerSchemaDiffTool } from "./tools/schema-diff.ts"
+import { registerSchemaInferTool } from "./tools/schema-infer.ts"
+import { registerSchemaValidateTool } from "./tools/schema-validate.ts"
+import { registerSearchTool } from "./tools/search-notes.ts"
+import { registerWriteTool } from "./tools/write-note.ts"
+
+export default {
+  id: "basic-memory",
+  name: "Basic Memory",
+  description:
+    "Local-first knowledge graph for OpenClaw — persistent memory with graph search and composited memory_search",
+  kind: "memory" as const,
+  configSchema: basicMemoryConfigSchema,
+
+  register(api: OpenClawPluginApi) {
+    const cfg = parseConfig(api.pluginConfig)
+
+    initLogger(api.logger, cfg.debug)
+
+    log.info(
+      `project=${cfg.project} memoryDir=${cfg.memoryDir} memoryFile=${cfg.memoryFile}`,
+    )
+
+    const client = new BmClient(cfg.bmPath, cfg.project)
+
+    // --- BM Tools (always registered) ---
+    registerSearchTool(api, client)
+    registerProjectListTool(api, client)
+    registerWorkspaceListTool(api, client)
+    registerReadTool(api, client)
+    registerWriteTool(api, client)
+    registerEditTool(api, client)
+    registerContextTool(api, client)
+    registerDeleteTool(api, client)
+    registerMoveTool(api, client)
+    registerSchemaValidateTool(api, client)
+    registerSchemaInferTool(api, client)
+    registerSchemaDiffTool(api, client)
+
+    // --- Composited memory_search + memory_get (always registered) ---
+    registerMemoryProvider(api, client, cfg)
+    log.info("registered composited memory_search + memory_get")
+
+    if (cfg.autoCapture) {
+      api.on("agent_end", buildCaptureHandler(client, cfg))
+    }
+
+    if (cfg.autoRecall) {
+      api.on("agent_start", buildRecallHandler(client, cfg))
+    }
+
+    // --- Commands ---
+    registerCommands(api, client)
+    registerSkillCommands(api)
+    registerCli(api, client, cfg)
+
+    // --- Service lifecycle ---
+    api.registerService({
+      id: "basic-memory",
+      start: async (ctx: { config?: unknown; workspaceDir?: string }) => {
+        log.info("starting...")
+
+        const workspace = ctx.workspaceDir ?? process.cwd()
+        const projectPath = resolveProjectPath(cfg.projectPath, workspace)
+        cfg.projectPath = projectPath
+
+        await client.start({ cwd: workspace })
+        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")
+      },
+      stop: async () => {
+        log.info("stopping BM MCP session...")
+        await client.stop()
+        log.info("stopped")
+      },
+    })
+  },
+}

package/logger.ts

@@ -0,0 +1,47 @@
+export type LoggerBackend = {
+  info(msg: string, ...args: unknown[]): void
+  warn(msg: string, ...args: unknown[]): void
+  error(msg: string, ...args: unknown[]): void
+  debug?(msg: string, ...args: unknown[]): void
+}
+
+const NOOP_LOGGER: LoggerBackend = {
+  info() {},
+  warn() {},
+  error() {},
+  debug() {},
+}
+
+let _backend: LoggerBackend = NOOP_LOGGER
+let _debug = false
+
+export function initLogger(backend: LoggerBackend, debug: boolean): void {
+  _backend = backend
+  _debug = debug
+}
+
+export const log = {
+  info(msg: string, ...args: unknown[]): void {
+    _backend.info(`basic-memory: ${msg}`, ...args)
+  },
+
+  warn(msg: string, ...args: unknown[]): void {
+    _backend.warn(`basic-memory: ${msg}`, ...args)
+  },
+
+  error(msg: string, err?: unknown): void {
+    const detail =
+      err instanceof Error
+        ? err.message
+        : err !== undefined && err !== ""
+          ? String(err)
+          : ""
+    _backend.error(`basic-memory: ${msg}${detail ? ` — ${detail}` : ""}`)
+  },
+
+  debug(msg: string, ...args: unknown[]): void {
+    if (!_debug) return
+    const fn = _backend.debug ?? _backend.info
+    fn(`basic-memory [debug]: ${msg}`, ...args)
+  },
+}

package/openclaw.plugin.json

@@ -0,0 +1,83 @@
+{
+  "id": "basic-memory",
+  "kind": "memory",
+  "skills": [
+    "skills/memory-tasks",
+    "skills/memory-reflect",
+    "skills/memory-defrag",
+    "skills/memory-schema",
+    "skills/memory-metadata-search",
+    "skills/memory-notes"
+  ],
+  "uiHints": {
+    "project": {
+      "label": "Project Name",
+      "placeholder": "my-agent",
+      "help": "Basic Memory project name. Created automatically if it doesn't exist."
+    },
+    "memoryDir": {
+      "label": "Memory Directory",
+      "placeholder": "memory/",
+      "help": "Directory to index into the knowledge graph (relative to workspace)"
+    },
+    "memoryFile": {
+      "label": "Memory File",
+      "placeholder": "MEMORY.md",
+      "help": "Working memory file (searched but not indexed into BM)"
+    },
+    "bmPath": {
+      "label": "BM CLI Path",
+      "placeholder": "bm",
+      "help": "Path to the basic-memory CLI binary (default: 'bm')",
+      "advanced": true
+    },
+    "indexInterval": {
+      "label": "Index Interval (seconds)",
+      "placeholder": "300",
+      "help": "Seconds between periodic re-indexing sweeps",
+      "advanced": true
+    },
+    "autoCapture": {
+      "label": "Auto-Capture",
+      "help": "Automatically index conversation content after each turn"
+    },
+    "debug": {
+      "label": "Debug Logging",
+      "help": "Enable verbose debug logs",
+      "advanced": true
+    },
+    "projectPath": {
+      "label": "Project Path",
+      "placeholder": "~/.openclaw/workspace/memory/",
+      "help": "Filesystem path for Basic Memory project data (relative paths resolve from workspace); created automatically if missing",
+      "advanced": true
+    },
+    "cloud": {
+      "label": "Cloud Backend",
+      "help": "Optional cloud backend config (url + api_key). If present, uses cloud instead of local BM.",
+      "advanced": true
+    }
+  },
+  "configSchema": {
+    "type": "object",
+    "additionalProperties": false,
+    "properties": {
+      "project": { "type": "string" },
+      "memoryDir": { "type": "string" },
+      "memoryFile": { "type": "string" },
+      "bmPath": { "type": "string" },
+      "indexInterval": { "type": "number", "minimum": 30, "maximum": 3600 },
+      "autoCapture": { "type": "boolean" },
+      "debug": { "type": "boolean" },
+      "projectPath": { "type": "string" },
+      "cloud": {
+        "type": "object",
+        "properties": {
+          "url": { "type": "string" },
+          "api_key": { "type": "string" }
+        }
+      }
+    },
+    "required": []
+  }
+}

package/package.json

@@ -0,0 +1,68 @@
+{
+  "name": "@basicmemory/openclaw-basic-memory",
+  "version": "0.1.0-alpha.1",
+  "type": "module",
+  "description": "Basic Memory plugin for OpenClaw — local-first knowledge graph for agent memory",
+  "license": "MIT",
+  "files": [
+    "index.ts",
+    "bm-client.ts",
+    "config.ts",
+    "logger.ts",
+    "commands/cli.ts",
+    "commands/skills.ts",
+    "commands/slash.ts",
+    "hooks/capture.ts",
+    "hooks/recall.ts",
+    "tools/build-context.ts",
+    "tools/delete-note.ts",
+    "tools/edit-note.ts",
+    "tools/list-memory-projects.ts",
+    "tools/list-workspaces.ts",
+    "tools/memory-provider.ts",
+    "tools/move-note.ts",
+    "tools/read-note.ts",
+    "tools/schema-diff.ts",
+    "tools/schema-infer.ts",
+    "tools/schema-validate.ts",
+    "tools/search-notes.ts",
+    "tools/write-note.ts",
+    "types/openclaw.d.ts",
+    "schema/task-schema.ts",
+    "skills/",
+    "scripts/setup-bm.sh",
+    "openclaw.plugin.json",
+    "README.md",
+    "LICENSE"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.26.0",
+    "@sinclair/typebox": "0.34.47"
+  },
+  "peerDependencies": {
+    "openclaw": ">=2026.1.29"
+  },
+  "scripts": {
+    "postinstall": "bash scripts/setup-bm.sh || true",
+    "check-types": "tsc --noEmit",
+    "lint": "bunx @biomejs/biome ci .",
+    "lint:fix": "bunx @biomejs/biome check --write .",
+    "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",
+    "release:check": "bun run check-types && bun test && npm pack --dry-run"
+  },
+  "openclaw": {
+    "extensions": [
+      "./index.ts"
+    ]
+  },
+  "devDependencies": {
+    "@biomejs/biome": "^2.3.8",
+    "@types/node": "^20.0.0",
+    "typescript": "^5.9.3"
+  }
+}

package/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
+`

package/scripts/setup-bm.sh

@@ -0,0 +1,32 @@
+#!/usr/bin/env bash
+# Install basic-memory CLI via uv from the latest main branch.
+# 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:-main}"
+
+# ── check for uv ──────────────────────────────────────────────────
+if ! command -v uv >/dev/null 2>&1; then
+  echo "⚠  uv not found — skipping basic-memory install."
+  echo "   Install uv:  brew install uv"
+  echo "            or:  curl -LsSf https://astral.sh/uv/install.sh | sh"
+  echo "   Then re-run:  bash scripts/setup-bm.sh"
+  exit 0
+fi
+
+# ── install basic-memory[semantic] ────────────────────────────────
+echo "Installing basic-memory from ${BM_REPO}@${BM_REF} ..."
+uv tool install \
+  "basic-memory[semantic] @ git+${BM_REPO}@${BM_REF}" \
+  --with 'onnxruntime<1.24; platform_system == "Darwin" and platform_machine == "x86_64"' \
+  --force
+
+# ── 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."
+  exit 1
+fi
+
+echo "✅  $(bm --version)"

package/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.

package/skills/memory-metadata-search/SKILL.md

@@ -0,0 +1,208 @@
+---
+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."
+---
+
+# Memory Metadata Search
+
+Find notes by their structured frontmatter fields instead of (or in addition to) free-text content. Any custom YAML key in a note's frontmatter beyond the standard set (`title`, `type`, `tags`, `permalink`, `schema`) is automatically indexed as `entity_metadata` and becomes queryable.
+
+## When to Use
+
+- **Filtering by status or priority** — find all notes with `status: draft` or `priority: high`
+- **Querying custom fields** — any frontmatter key you invent is searchable
+- **Range queries** — find notes with `confidence > 0.7` or `score between 0.3 and 0.8`
+- **Combining text + metadata** — narrow a text search with structured constraints
+- **Tag-based filtering** — find notes tagged with specific frontmatter tags
+- **Schema-aware queries** — filter by nested schema fields using dot notation
+
+## Tool
+
+Use the `search_notes` tool with the optional `metadata_filters`, `tags`, and `status` parameters.
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `query` | string | Text search query (can be empty for filter-only searches) |
+| `metadata_filters` | object | Filter by frontmatter fields (see filter syntax below) |
+| `tags` | string[] | Filter by frontmatter tags (all must match) |
+| `status` | string | Filter by frontmatter status field |
+
+## Filter Syntax
+
+Filters are a JSON dictionary. Each key targets a frontmatter field; the value specifies the match condition. Multiple keys combine with **AND** logic.
+
+### Equality
+
+```json
+{"status": "active"}
+```
+
+### Array Contains (all listed values must be present)
+
+```json
+{"tags": ["security", "oauth"]}
+```
+
+### `$in` (match any value in list)
+
+```json
+{"priority": {"$in": ["high", "critical"]}}
+```
+
+### Comparisons (`$gt`, `$gte`, `$lt`, `$lte`)
+
+```json
+{"confidence": {"$gt": 0.7}}
+```
+
+Numeric values use numeric comparison; strings use lexicographic comparison.
+
+### `$between` (inclusive range)
+
+```json
+{"score": {"$between": [0.3, 0.8]}}
+```
+
+### Nested Access (dot notation)
+
+```json
+{"schema.version": "2"}
+```
+
+### Quick Reference
+
+| Operator | Syntax | Example |
+|----------|--------|---------|
+| Equality | `{"field": "value"}` | `{"status": "active"}` |
+| Array contains | `{"field": ["a", "b"]}` | `{"tags": ["security", "oauth"]}` |
+| `$in` | `{"field": {"$in": [...]}}` | `{"priority": {"$in": ["high", "critical"]}}` |
+| `$gt` / `$gte` | `{"field": {"$gt": N}}` | `{"confidence": {"$gt": 0.7}}` |
+| `$lt` / `$lte` | `{"field": {"$lt": N}}` | `{"score": {"$lt": 0.5}}` |
+| `$between` | `{"field": {"$between": [lo, hi]}}` | `{"score": {"$between": [0.3, 0.8]}}` |
+| Nested | `{"a.b": "value"}` | `{"schema.version": "2"}` |
+
+**Rules:**
+- Keys must match `[A-Za-z0-9_-]+` (dots separate nesting levels)
+- Operator dicts must contain exactly one operator
+- `$in` and array-contains require non-empty lists
+- `$between` requires exactly `[min, max]`
+
+## Examples
+
+### Metadata-only search (empty query)
+
+```
+search_notes(query="", metadata_filters={"status": "in-progress", "type": "spec"})
+```
+
+### Text search narrowed by metadata
+
+```
+search_notes(query="authentication", metadata_filters={"status": "draft"})
+```
+
+### Filter by tags
+
+```
+search_notes(query="", tags=["security", "oauth"])
+```
+
+### Filter by status shortcut
+
+```
+search_notes(query="planning", status="active")
+```
+
+### Combined text + metadata + tags
+
+```
+search_notes(
+    query="oauth flow",
+    metadata_filters={"confidence": {"$gt": 0.7}},
+    tags=["security"],
+    status="in-progress",
+)
+```
+
+### High-priority notes in a specific project
+
+```
+search_notes(
+    query="",
+    metadata_filters={"priority": {"$in": ["high", "critical"]}},
+    project="research",
+    limit=10,
+)
+```
+
+### Numeric range query
+
+```
+search_notes(query="", metadata_filters={"score": {"$between": [0.3, 0.8]}})
+```
+
+## Tag Search Shorthand
+
+The `tag:` prefix in a query converts to a tag filter automatically:
+
+```
+# These are equivalent:
+search_notes(query="tag:tier1")
+search_notes(query="", tags=["tier1"])
+
+# Multiple tags (comma or space separated) — all must match:
+search_notes(query="tag:tier1,alpha")
+```
+
+## Example: Custom Frontmatter in Practice
+
+A note with custom fields:
+
+```markdown
+---
+title: Auth Design
+type: spec
+tags: [security, oauth]
+status: in-progress
+priority: high
+confidence: 0.85
+---
+
+# Auth Design
+
+## Observations
+- [decision] Use OAuth 2.1 with PKCE for all client types #security
+- [requirement] Token refresh must be transparent to the user
+
+## Relations
+- implements [[Security Requirements]]
+```
+
+Queries that find it:
+
+```
+# By status and type
+search_notes(query="", metadata_filters={"status": "in-progress", "type": "spec"})
+
+# By numeric threshold
+search_notes(query="", metadata_filters={"confidence": {"$gt": 0.7}})
+
+# By priority set
+search_notes(query="", metadata_filters={"priority": {"$in": ["high", "critical"]}})
+
+# By tag shorthand
+search_notes(query="tag:security")
+
+# Combined text + metadata
+search_notes(query="OAuth", metadata_filters={"status": "in-progress"})
+```
+
+## Guidelines
+
+- **Use metadata filters for structured queries.** If you're looking for notes by a known field value (status, priority, type), metadata filters are more precise than text search.
+- **Use text search for content queries.** If you're looking for notes *about* something, text search is better. Combine both when you need precision.
+- **Custom fields are free.** Any YAML key you put in frontmatter becomes queryable — no schema or configuration required.
+- **Multiple filters are AND.** `{"status": "active", "priority": "high"}` requires both conditions.
+- **Use empty query for filter-only searches.** Pass `query=""` with `metadata_filters` when you only need structured filtering.
+- **Dot notation for nesting.** Access nested YAML structures with dots: `{"schema.version": "2"}` queries the `version` key inside a `schema` object.
+- **Tags and status are convenient shortcuts.** Use the dedicated `tags` and `status` parameters for common fields, or `metadata_filters` for anything else.